The GNU C Library

Table of Contents

Introduction

Getting Started
Standards and Portability

ISO C
POSIX (The Portable Operating System Interface)
Berkeley Unix
SVID (The System V Interface Description)
XPG (The X/Open Portability Guide)

Using the Library

Header Files
Macro Definitions of Functions
Reserved Names
Feature Test Macros

Roadmap to the Manual

Error Reporting

Checking for Errors
Error Codes
Error Messages

Virtual Memory Allocation And Paging

Process Memory Concepts
Allocating Storage For Program Data

Memory Allocation in C Programs

Dynamic Memory Allocation

Unconstrained Allocation

Basic Memory Allocation
Examples of malloc
Freeing Memory Allocated with malloc
Changing the Size of a Block
Allocating Cleared Space
Efficiency Considerations for malloc
Allocating Aligned Memory Blocks
Malloc Tunable Parameters
Heap Consistency Checking
Memory Allocation Hooks
Statistics for Memory Allocation with malloc
Summary of malloc-Related Functions

Allocation Debugging

How to install the tracing functionality
Example program excerpts
Some more or less clever ideas
Interpreting the traces

Obstacks

Creating Obstacks
Preparing for Using Obstacks
Allocation in an Obstack
Freeing Objects in an Obstack
Obstack Functions and Macros
Growing Objects
Extra Fast Growing Objects
Status of an Obstack
Alignment of Data in Obstacks
Obstack Chunks
Summary of Obstack Functions

Automatic Storage with Variable Size

alloca Example
Advantages of alloca
Disadvantages of alloca
GNU C Variable-Size Arrays

Resizing the Data Segment
Locking Pages

Why Lock Pages
Locked Memory Details
Functions To Lock And Unlock Pages

Character Handling

Classification of Characters
Case Conversion
Character class determination for wide characters
Notes on using the wide character classes
Mapping of wide characters.

String and Array Utilities

Representation of Strings
String and Array Conventions
String Length
Copying and Concatenation
String/Array Comparison
Collation Functions
Search Functions

Compatibility String Search Functions

Finding Tokens in a String
strfry
Trivial Encryption
Encode Binary Data
Argz and Envz Vectors

Argz Functions
Envz Functions

Character Set Handling

Introduction to Extended Characters
Overview about Character Handling Functions
Restartable Multibyte Conversion Functions

Selecting the conversion and its properties
Representing the state of the conversion
Converting Single Characters
Converting Multibyte and Wide Character Strings
A Complete Multibyte Conversion Example

Non-reentrant Conversion Function

Non-reentrant Conversion of Single Characters
Non-reentrant Conversion of Strings
States in Non-reentrant Functions

Generic Charset Conversion

Generic Character Set Conversion Interface
A complete iconv example
Some Details about other iconv Implementations
The iconv Implementation in the GNU C library

Format of `gconv-modules' files
Finding the conversion path in iconv
iconv module data structures
iconv module interfaces

Locales and Internationalization

What Effects a Locale Has
Choosing a Locale
Categories of Activities that Locales Affect
How Programs Set the Locale
Standard Locales
Accessing Locale Information

localeconv: It is portable but ...

Generic Numeric Formatting Parameters
Printing the Currency Symbol
Printing the Sign of a Monetary Amount

Pinpoint Access to Locale Data

A dedicated function to format numbers

Message Translation

X/Open Message Catalog Handling

The catgets function family
Format of the message catalog files
Generate Message Catalogs files
How to use the catgets interface

Not using symbolic names
Using symbolic names
How does to this allow to develop

The Uniforum approach to Message Translation

The gettext family of functions

What has to be done to translate a message?
How to determine which catalog to be used
Additional functions for more complicated situations
How to specify the output character set gettext uses
How to use gettext in GUI programs
User influence on gettext

Programs to handle message catalogs for gettext

Searching and Sorting

Defining the Comparison Function
Array Search Function
Array Sort Function
Searching and Sorting Example
The hsearch function.
The tsearch function.

Pattern Matching

Wildcard Matching
Globbing

Calling glob
Flags for Globbing
More Flags for Globbing

Regular Expression Matching

POSIX Regular Expression Compilation
Flags for POSIX Regular Expressions
Matching a Compiled POSIX Regular Expression
Match Results with Subexpressions
Complications in Subexpression Matching
POSIX Regexp Matching Cleanup

Shell-Style Word Expansion

The Stages of Word Expansion
Calling wordexp
Flags for Word Expansion
wordexp Example
Details of Tilde Expansion
Details of Variable Substitution

Input/Output Overview

Input/Output Concepts

Streams and File Descriptors
File Position

File Names

Directories
File Name Resolution
File Name Errors
Portability of File Names

Input/Output on Streams

Streams
Standard Streams
Opening Streams
Closing Streams
Streams and Threads
Streams in Internationalized Applications
Simple Output by Characters or Lines
Character Input
Line-Oriented Input
Unreading

What Unreading Means
Using ungetc To Do Unreading

Block Input/Output
Formatted Output

Formatted Output Basics
Output Conversion Syntax
Table of Output Conversions
Integer Conversions
Floating-Point Conversions
Other Output Conversions
Formatted Output Functions
Dynamically Allocating Formatted Output
Variable Arguments Output Functions
Parsing a Template String
Example of Parsing a Template String

Customizing printf

Registering New Conversions
Conversion Specifier Options
Defining the Output Handler
printf Extension Example
Predefined printf Handlers

Formatted Input

Formatted Input Basics
Input Conversion Syntax
Table of Input Conversions
Numeric Input Conversions
String Input Conversions
Dynamically Allocating String Conversions
Other Input Conversions
Formatted Input Functions
Variable Arguments Input Functions

End-Of-File and Errors
Recovering from errors
Text and Binary Streams
File Positioning
Portable File-Position Functions
Stream Buffering

Buffering Concepts
Flushing Buffers
Controlling Which Kind of Buffering

Other Kinds of Streams

String Streams
Obstack Streams
Programming Your Own Custom Streams

Custom Streams and Cookies
Custom Stream Hook Functions

Formatted Messages

Printing Formatted Messages
Adding Severity Classes
How to use fmtmsg and addseverity

Low-Level Input/Output

Opening and Closing Files
Input and Output Primitives
Setting the File Position of a Descriptor
Descriptors and Streams
Dangers of Mixing Streams and Descriptors

Linked Channels
Independent Channels
Cleaning Streams

Fast Scatter-Gather I/O
Memory-mapped I/O
Waiting for Input or Output
Synchronizing I/O operations
Perform I/O Operations in Parallel

Asynchronous Read and Write Operations
Getting the Status of AIO Operations
Getting into a Consistent State
Cancellation of AIO Operations
How to optimize the AIO implementation

Control Operations on Files
Duplicating Descriptors
File Descriptor Flags
File Status Flags

File Access Modes
Open-time Flags
I/O Operating Modes
Getting and Setting File Status Flags

File Locks
Interrupt-Driven Input
Generic I/O Control operations

File System Interface

Working Directory
Accessing Directories

Format of a Directory Entry
Opening a Directory Stream
Reading and Closing a Directory Stream
Simple Program to List a Directory
Random Access in a Directory Stream
Scanning the Content of a Directory
Simple Program to List a Directory, Mark II

Working with Directory Trees
Hard Links
Symbolic Links
Deleting Files
Renaming Files
Creating Directories
File Attributes

The meaning of the File Attributes
Reading the Attributes of a File
Testing the Type of a File
File Owner
The Mode Bits for Access Permission
How Your Access to a File is Decided
Assigning File Permissions
Testing Permission to Access a File
File Times
File Size

Making Special Files
Temporary Files

Pipes and FIFOs

Creating a Pipe
Pipe to a Subprocess
FIFO Special Files
Atomicity of Pipe I/O

Sockets

Socket Concepts
Communication Styles
Socket Addresses

Address Formats
Setting the Address of a Socket
Reading the Address of a Socket

Interface Naming
The Local Namespace

Local Namespace Concepts
Details of Local Namespace
Example of Local-Namespace Sockets

The Internet Namespace

Internet Socket Address Formats
Host Addresses

Internet Host Addresses
Host Address Data Type
Host Address Functions
Host Names

Internet Ports
The Services Database
Byte Order Conversion
Protocols Database
Internet Socket Example

Other Namespaces
Opening and Closing Sockets

Creating a Socket
Closing a Socket
Socket Pairs

Using Sockets with Connections

Making a Connection
Listening for Connections
Accepting Connections
Who is Connected to Me?
Transferring Data

Sending Data
Receiving Data
Socket Data Options

Byte Stream Socket Example
Byte Stream Connection Server Example
Out-of-Band Data

Datagram Socket Operations

Sending Datagrams
Receiving Datagrams
Datagram Socket Example
Example of Reading Datagrams

The inetd Daemon

inetd Servers
Configuring inetd

Socket Options

Socket Option Functions
Socket-Level Options

Networks Database

Low-Level Terminal Interface

Identifying Terminals
I/O Queues
Two Styles of Input: Canonical or Not
Terminal Modes

Terminal Mode Data Types
Terminal Mode Functions
Setting Terminal Modes Properly
Input Modes
Output Modes
Control Modes
Local Modes
Line Speed
Special Characters

Characters for Input Editing
Characters that Cause Signals
Special Characters for Flow Control
Other Special Characters

Noncanonical Input

BSD Terminal Modes
Line Control Functions
Noncanonical Mode Example
Pseudo-Terminals

Allocating Pseudo-Terminals
Opening a Pseudo-Terminal Pair

Syslog

Overview of Syslog
Submitting Syslog Messages

openlog
syslog, vsyslog
closelog
setlogmask
Syslog Example

Mathematics

Predefined Mathematical Constants
Trigonometric Functions
Inverse Trigonometric Functions
Exponentiation and Logarithms
Hyperbolic Functions
Special Functions
Known Maximum Errors in Math Functions
Pseudo-Random Numbers

ISO C Random Number Functions
BSD Random Number Functions
SVID Random Number Function

Is Fast Code or Small Code preferred?

Arithmetic Functions

Integers
Integer Division
Floating Point Numbers
Floating-Point Number Classification Functions
Errors in Floating-Point Calculations

FP Exceptions
Infinity and NaN
Examining the FPU status word
Error Reporting by Mathematical Functions

Rounding Modes
Floating-Point Control Functions
Arithmetic Functions

Absolute Value
Normalization Functions
Rounding Functions
Remainder Functions
Setting and modifying single bits of FP values
Floating-Point Comparison Functions
Miscellaneous FP arithmetic functions

Complex Numbers
Projections, Conjugates, and Decomposing of Complex Numbers
Parsing of Numbers

Parsing of Integers
Parsing of Floats

Old-fashioned System V number-to-string functions

Date and Time

Time Basics
Elapsed Time
Processor And CPU Time

CPU Time Inquiry
Processor Time Inquiry

Calendar Time

Simple Calendar Time
High-Resolution Calendar
Broken-down Time
High Accuracy Clock
Formatting Calendar Time
Convert textual time and date information back

Interpret string according to given format
A More User-friendly Way to Parse Times and Dates

Specifying the Time Zone with TZ
Functions and Variables for Time Zones
Time Functions Example

Setting an Alarm
Sleeping

Resource Usage And Limitation

Resource Usage
Limiting Resource Usage
Process CPU Priority And Scheduling

Absolute Priority

Using Absolute Priority

Realtime Scheduling
Basic Scheduling Functions
Traditional Scheduling

Introduction To Traditional Scheduling
Functions For Traditional Scheduling

Querying memory available resources

Overview about traditional Unix memory handling
How to get information about the memory subsystem?

Learn about the processors available

Non-Local Exits

Introduction to Non-Local Exits
Details of Non-Local Exits
Non-Local Exits and Signals
Complete Context Control

Signal Handling

Basic Concepts of Signals

Some Kinds of Signals
Concepts of Signal Generation
How Signals Are Delivered

Standard Signals

Program Error Signals
Termination Signals
Alarm Signals
Asynchronous I/O Signals
Job Control Signals
Operation Error Signals
Miscellaneous Signals
Signal Messages

Specifying Signal Actions

Basic Signal Handling
Advanced Signal Handling
Interaction of signal and sigaction
sigaction Function Example
Flags for sigaction
Initial Signal Actions

Defining Signal Handlers

Signal Handlers that Return
Handlers That Terminate the Process
Nonlocal Control Transfer in Handlers
Signals Arriving While a Handler Runs
Signals Close Together Merge into One
Signal Handling and Nonreentrant Functions
Atomic Data Access and Signal Handling

Problems with Non-Atomic Access
Atomic Types
Atomic Usage Patterns

Primitives Interrupted by Signals
Generating Signals

Signaling Yourself
Signaling Another Process
Permission for using kill
Using kill for Communication

Blocking Signals

Why Blocking Signals is Useful
Signal Sets
Process Signal Mask
Blocking to Test for Delivery of a Signal
Blocking Signals for a Handler
Checking for Pending Signals
Remembering a Signal to Act On Later

Waiting for a Signal

Using pause
Problems with pause
Using sigsuspend

Using a Separate Signal Stack
BSD Signal Handling

BSD Function to Establish a Handler
BSD Functions for Blocking Signals

The Basic Program/System Interface

Program Arguments

Program Argument Syntax Conventions
Parsing Program Arguments

Parsing program options using getopt

Using the getopt function
Example of Parsing Arguments with getopt
Parsing Long Options with getopt_long
Example of Parsing Long Options with getopt_long

Parsing Program Options with Argp

The argp_parse Function
Argp Global Variables
Specifying Argp Parsers
Specifying Options in an Argp Parser

Flags for Argp Options

Argp Parser Functions

Special Keys for Argp Parser Functions
Functions For Use in Argp Parsers
Argp Parsing State

Combining Multiple Argp Parsers
Flags for argp_parse
Customizing Argp Help Output

Special Keys for Argp Help Filter Functions

The argp_help Function
Flags for the argp_help Function
Argp Examples

A Minimal Program Using Argp
A Program Using Argp with Only Default Options
A Program Using Argp with User Options
A Program Using Multiple Combined Argp Parsers

Argp User Customization

Parsing of Suboptions

Parsing of Suboptions Example

Environment Variables

Environment Access
Standard Environment Variables

System Calls
Program Termination

Normal Termination
Exit Status
Cleanups on Exit
Aborting a Program
Termination Internals

Processes

Running a Command
Process Creation Concepts
Process Identification
Creating a Process
Executing a File
Process Completion
Process Completion Status
BSD Process Wait Functions
Process Creation Example

Job Control

Concepts of Job Control
Job Control is Optional
Controlling Terminal of a Process
Access to the Controlling Terminal
Orphaned Process Groups
Implementing a Job Control Shell

Data Structures for the Shell
Initializing the Shell
Launching Jobs
Foreground and Background
Stopped and Terminated Jobs
Continuing Stopped Jobs
The Missing Pieces

Functions for Job Control

Identifying the Controlling Terminal
Process Group Functions
Functions for Controlling Terminal Access

System Databases and Name Service Switch

NSS Basics
The NSS Configuration File

Services in the NSS configuration File
Actions in the NSS configuration
Notes on the NSS Configuration File

NSS Module Internals

The Naming Scheme of the NSS Modules
The Interface of the Function in NSS Modules

Extending NSS

Adding another Service to NSS
Internals of the NSS Module Functions

Users and Groups

User and Group IDs
The Persona of a Process
Why Change the Persona of a Process?
How an Application Can Change Persona
Reading the Persona of a Process
Setting the User ID
Setting the Group IDs
Enabling and Disabling Setuid Access
Setuid Program Example
Tips for Writing Setuid Programs
Identifying Who Logged In
The User Accounting Database

Manipulating the User Accounting Database
XPG User Accounting Database Functions
Logging In and Out

User Database

The Data Structure that Describes a User
Looking Up One User
Scanning the List of All Users
Writing a User Entry

Group Database

The Data Structure for a Group
Looking Up One Group
Scanning the List of All Groups

User and Group Database Example
Netgroup Database

Netgroup Data
Looking up one Netgroup
Testing for Netgroup Membership

System Management

Host Identification
Platform Type Identification
Controlling and Querying Mounts

Mount Information

The `fstab' file
The `mtab' file
Other (Non-libc) Sources of Mount Information

Mount, Unmount, Remount

System Parameters

System Configuration Parameters

General Capacity Limits
Overall System Options
Which Version of POSIX is Supported
Using sysconf

Definition of sysconf
Constants for sysconf Parameters
Examples of sysconf

Minimum Values for General Capacity Limits
Limits on File System Capacity
Optional Features in File Support
Minimum Values for File System Limits
Using pathconf
Utility Program Capacity Limits
Minimum Values for Utility Limits
String-Valued Parameters

DES Encryption and Password Handling

Legal Problems
Reading Passwords
Encrypting Passwords
DES Encryption

Debugging support

Backtraces

C Language Facilities in the Library

Explicitly Checking Internal Consistency
Variadic Functions

Why Variadic Functions are Used
How Variadic Functions are Defined and Used

Syntax for Variable Arguments
Receiving the Argument Values
How Many Arguments Were Supplied
Calling Variadic Functions
Argument Access Macros

Example of a Variadic Function

Old-Style Variadic Functions

Null Pointer Constant
Important Data Types
Data Type Measurements

Computing the Width of an Integer Data Type
Range of an Integer Type
Floating Type Macros

Floating Point Representation Concepts
Floating Point Parameters
IEEE Floating Point

Structure Field Offset Measurement

Summary of Library Facilities
Installing the GNU C Library

Configuring and compiling GNU Libc
Installing the C Library
Recommended Tools for Compilation
Supported Configurations
Specific advice for Linux systems
Reporting Bugs

Library Maintenance

Adding New Functions
Porting the GNU C Library

Layout of the `sysdeps' Directory Hierarchy
Porting the GNU C Library to Unix Systems

Contributors to the GNU C Library
GNU LIBRARY GENERAL PUBLIC LICENSE

Preamble
TERMS AND CONDITIONS FOR COPYING,
DISTRIBUTION AND MODIFICATION
How to Apply These Terms to Your New Libraries

Concept Index
Type Index
Function and Macro Index
Variable and Constant Macro Index
Program and File Index

Introduction

The C language provides no built-in facilities for performing such common operations as input/output, memory management, string manipulation, and the like. Instead, these facilities are defined in a standard library, which you compile and link with your programs.

The GNU C library, described in this document, defines all of the library functions that are specified by the ISO C standard, as well as additional features specific to POSIX and other derivatives of the Unix operating system, and extensions specific to the GNU system.

The purpose of this manual is to tell you how to use the facilities of the GNU library. We have mentioned which features belong to which standards to help you identify things that are potentially non-portable to other systems. But the emphasis in this manual is not on strict portability.

Getting Started

This manual is written with the assumption that you are at least somewhat familiar with the C programming language and basic programming concepts. Specifically, familiarity with ISO standard C (see section ISO C), rather than "traditional" pre-ISO C dialects, is assumed.

The GNU C library includes several header files, each of which provides definitions and declarations for a group of related facilities; this information is used by the C compiler when processing your program. For example, the header file `stdio.h' declares facilities for performing input and output, and the header file `string.h' declares string processing utilities. The organization of this manual generally follows the same division as the header files.

If you are reading this manual for the first time, you should read all of the introductory material and skim the remaining chapters. There are a lot of functions in the GNU C library and it's not realistic to expect that you will be able to remember exactly how to use each and every one of them. It's more important to become generally familiar with the kinds of facilities that the library provides, so that when you are writing your programs you can recognize when to make use of library functions, and where in this manual you can find more specific information about them.

Standards and Portability

This section discusses the various standards and other sources that the GNU C library is based upon. These sources include the ISO C and POSIX standards, and the System V and Berkeley Unix implementations.

The primary focus of this manual is to tell you how to make effective use of the GNU library facilities. But if you are concerned about making your programs compatible with these standards, or portable to operating systems other than GNU, this can affect how you use the library. This section gives you an overview of these standards, so that you will know what they are when they are mentioned in other parts of the manual.

See section Summary of Library Facilities, for an alphabetical list of the functions and other symbols provided by the library. This list also states which standards each function or symbol comes from.

ISO C

The GNU C library is compatible with the C standard adopted by the American National Standards Institute (ANSI): American National Standard X3.159-1989---"ANSI C" and later by the International Standardization Organization (ISO): ISO/IEC 9899:1990, "Programming languages--C". We here refer to the standard as ISO C since this is the more general standard in respect of ratification. The header files and library facilities that make up the GNU library are a superset of those specified by the ISO C standard.

If you are concerned about strict adherence to the ISO C standard, you should use the `-ansi' option when you compile your programs with the GNU C compiler. This tells the compiler to define only ISO standard features from the library header files, unless you explicitly ask for additional features. See section Feature Test Macros, for information on how to do this.

Being able to restrict the library to include only ISO C features is important because ISO C puts limitations on what names can be defined by the library implementation, and the GNU extensions don't fit these limitations. See section Reserved Names, for more information about these restrictions.

This manual does not attempt to give you complete details on the differences between ISO C and older dialects. It gives advice on how to write programs to work portably under multiple C dialects, but does not aim for completeness.

POSIX (The Portable Operating System Interface)

The GNU library is also compatible with the ISO POSIX family of standards, known more formally as the Portable Operating System Interface for Computer Environments (ISO/IEC 9945). They were also published as ANSI/IEEE Std 1003. POSIX is derived mostly from various versions of the Unix operating system.

The library facilities specified by the POSIX standards are a superset of those required by ISO C; POSIX specifies additional features for ISO C functions, as well as specifying new additional functions. In general, the additional requirements and functionality defined by the POSIX standards are aimed at providing lower-level support for a particular kind of operating system environment, rather than general programming language support which can run in many diverse operating system environments.

The GNU C library implements all of the functions specified in ISO/IEC 9945-1:1996, the POSIX System Application Program Interface, commonly referred to as POSIX.1. The primary extensions to the ISO C facilities specified by this standard include file system interface primitives (see section File System Interface), device-specific terminal control functions (see section Low-Level Terminal Interface), and process control functions (see section Processes).

Some facilities from ISO/IEC 9945-2:1993, the POSIX Shell and Utilities standard (POSIX.2) are also implemented in the GNU library. These include utilities for dealing with regular expressions and other pattern matching facilities (see section Pattern Matching).

Berkeley Unix

The GNU C library defines facilities from some versions of Unix which are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD, and 4.4 BSD Unix systems (also known as Berkeley Unix) and from SunOS (a popular 4.2 BSD derivative that includes some Unix System V functionality). These systems support most of the ISO C and POSIX facilities, and 4.4 BSD and newer releases of SunOS in fact support them all.

The BSD facilities include symbolic links (see section Symbolic Links), the select function (see section Waiting for Input or Output), the BSD signal functions (see section BSD Signal Handling), and sockets (see section Sockets).

SVID (The System V Interface Description)

The System V Interface Description (SVID) is a document describing the AT&T Unix System V operating system. It is to some extent a superset of the POSIX standard (see section POSIX (The Portable Operating System Interface)).

The GNU C library defines most of the facilities required by the SVID that are not also required by the ISO C or POSIX standards, for compatibility with System V Unix and other Unix systems (such as SunOS) which include these facilities. However, many of the more obscure and less generally useful facilities required by the SVID are not included. (In fact, Unix System V itself does not provide them all.)

The supported facilities from System V include the methods for inter-process communication and shared memory, the hsearch and drand48 families of functions, fmtmsg and several of the mathematical functions.

XPG (The X/Open Portability Guide)

The X/Open Portability Guide, published by the X/Open Company, Ltd., is a more general standard than POSIX. X/Open owns the Unix copyright and the XPG specifies the requirements for systems which are intended to be a Unix system.

The GNU C library complies to the X/Open Portability Guide, Issue 4.2, with all extensions common to XSI (X/Open System Interface) compliant systems and also all X/Open UNIX extensions.

The additions on top of POSIX are mainly derived from functionality available in System V and BSD systems. Some of the really bad mistakes in System V systems were corrected, though. Since fulfilling the XPG standard with the Unix extensions is a precondition for getting the Unix brand chances are good that the functionality is available on commercial systems.

Using the Library

This section describes some of the practical issues involved in using the GNU C library.

Header Files

Libraries for use by C programs really consist of two parts: header files that define types and macros and declare variables and functions; and the actual library or archive that contains the definitions of the variables and functions.

(Recall that in C, a declaration merely provides information that a function or variable exists and gives its type. For a function declaration, information about the types of its arguments might be provided as well. The purpose of declarations is to allow the compiler to correctly process references to the declared variables and functions. A definition, on the other hand, actually allocates storage for a variable or says what a function does.)

In order to use the facilities in the GNU C library, you should be sure that your program source files include the appropriate header files. This is so that the compiler has declarations of these facilities available and can correctly process references to them. Once your program has been compiled, the linker resolves these references to the actual definitions provided in the archive file.

Header files are included into a program source file by the `#include' preprocessor directive. The C language supports two forms of this directive; the first,
#include "header"
is typically used to include a header file header that you write yourself; this would contain definitions and declarations describing the interfaces between the different parts of your particular application. By contrast,
#include <file.h>
is typically used to include a header file `file.h' that contains definitions and declarations for a standard library. This file would normally be installed in a standard place by your system administrator. You should use this second form for the C library header files.

Typically, `#include' directives are placed at the top of the C source file, before any other code. If you begin your source files with some comments explaining what the code in the file does (a good idea), put the `#include' directives immediately afterwards, following the feature test macro definition (see section Feature Test Macros).

For more information about the use of header files and `#include' directives, see section `Header Files' in The GNU C Preprocessor Manual.

The GNU C library provides several header files, each of which contains the type and macro definitions and variable and function declarations for a group of related facilities. This means that your programs may need to include several header files, depending on exactly which facilities you are using.

Some library header files include other library header files automatically. However, as a matter of programming style, you should not rely on this; it is better to explicitly include all the header files required for the library facilities you are using. The GNU C library header files have been written in such a way that it doesn't matter if a header file is accidentally included more than once; including a header file a second time has no effect. Likewise, if your program needs to include multiple header files, the order in which they are included doesn't matter.

Compatibility Note: Inclusion of standard header files in any order and any number of times works in any ISO C implementation. However, this has traditionally not been the case in many older C implementations.

Strictly speaking, you don't have to include a header file to use a function it declares; you could declare the function explicitly yourself, according to the specifications in this manual. But it is usually better to include the header file because it may define types and macros that are not otherwise available and because it may define more efficient macro replacements for some functions. It is also a sure way to have the correct declaration.

Macro Definitions of Functions

If we describe something as a function in this manual, it may have a macro definition as well. This normally has no effect on how your program runs--the macro definition does the same thing as the function would. In particular, macro equivalents for library functions evaluate arguments exactly once, in the same way that a function call would. The main reason for these macro definitions is that sometimes they can produce an inline expansion that is considerably faster than an actual function call.

Taking the address of a library function works even if it is also defined as a macro. This is because, in this context, the name of the function isn't followed by the left parenthesis that is syntactically necessary to recognize a macro call.

You might occasionally want to avoid using the macro definition of a function--perhaps to make your program easier to debug. There are two ways you can do this:

You can avoid a macro definition in a specific use by enclosing the name of the function in parentheses. This works because the name of the function doesn't appear in a syntactic context where it is recognizable as a macro call.
You can suppress any macro definition for a whole source file by using the `#undef' preprocessor directive, unless otherwise stated explicitly in the description of that facility.

For example, suppose the header file `stdlib.h' declares a function named abs with
extern int abs (int);
and also provides a macro definition for abs. Then, in:
#include <stdlib.h>
int f (int *i) { return abs (++*i); }
the reference to abs might refer to either a macro or a function. On the other hand, in each of the following examples the reference is to a function and not a macro.
#include <stdlib.h>
int g (int *i) { return (abs) (++*i); }

#undef abs
int h (int *i) { return abs (++*i); }
Since macro definitions that double for a function behave in exactly the same way as the actual function version, there is usually no need for any of these methods. In fact, removing macro definitions usually just makes your program slower.

Reserved Names

The names of all library types, macros, variables and functions that come from the ISO C standard are reserved unconditionally; your program may not redefine these names. All other library names are reserved if your program explicitly includes the header file that defines or declares them. There are several reasons for these restrictions:

Other people reading your code could get very confused if you were using a function named exit to do something completely different from what the standard exit function does, for example. Preventing this situation helps to make your programs easier to understand and contributes to modularity and maintainability.
It avoids the possibility of a user accidentally redefining a library function that is called by other library functions. If redefinition were allowed, those other functions would not work properly.
It allows the compiler to do whatever special optimizations it pleases on calls to these functions, without the possibility that they may have been redefined by the user. Some library facilities, such as those for dealing with variadic arguments (see section Variadic Functions) and non-local exits (see section Non-Local Exits), actually require a considerable amount of cooperation on the part of the C compiler, and implementationally it might be easier for the compiler to treat these as built-in parts of the language.

In addition to the names documented in this manual, reserved names include all external identifiers (global functions and variables) that begin with an underscore (`_') and all identifiers regardless of use that begin with either two underscores or an underscore followed by a capital letter are reserved names. This is so that the library and header files can define functions, variables, and macros for internal purposes without risk of conflict with names in user programs.

Some additional classes of identifier names are reserved for future extensions to the C language or the POSIX.1 environment. While using these names for your own purposes right now might not cause a problem, they do raise the possibility of conflict with future versions of the C or POSIX standards, so you should avoid these names.

Names beginning with a capital `E' followed a digit or uppercase letter may be used for additional error code names. See section Error Reporting.
Names that begin with either `is' or `to' followed by a lowercase letter may be used for additional character testing and conversion functions. See section Character Handling.
Names that begin with `LC_' followed by an uppercase letter may be used for additional macros specifying locale attributes. See section Locales and Internationalization.
Names of all existing mathematics functions (see section Mathematics) suffixed with `f' or `l' are reserved for corresponding functions that operate on float and long double arguments, respectively.
Names that begin with `SIG' followed by an uppercase letter are reserved for additional signal names. See section Standard Signals.
Names that begin with `SIG_' followed by an uppercase letter are reserved for additional signal actions. See section Basic Signal Handling.
Names beginning with `str', `mem', or `wcs' followed by a lowercase letter are reserved for additional string and array functions. See section String and Array Utilities.
Names that end with `_t' are reserved for additional type names.

In addition, some individual header files reserve names beyond those that they actually define. You only need to worry about these restrictions if your program includes that particular header file.

The header file `dirent.h' reserves names prefixed with `d_'.
The header file `fcntl.h' reserves names prefixed with `l_', `F_', `O_', and `S_'.
The header file `grp.h' reserves names prefixed with `gr_'.
The header file `limits.h' reserves names suffixed with `_MAX'.
The header file `pwd.h' reserves names prefixed with `pw_'.
The header file `signal.h' reserves names prefixed with `sa_' and `SA_'.
The header file `sys/stat.h' reserves names prefixed with `st_' and `S_'.
The header file `sys/times.h' reserves names prefixed with `tms_'.
The header file `termios.h' reserves names prefixed with `c_', `V', `I', `O', and `TC'; and names prefixed with `B' followed by a digit.

Feature Test Macros

The exact set of features available when you compile a source file is controlled by which feature test macros you define.

If you compile your programs using `gcc -ansi', you get only the ISO C library features, unless you explicitly request additional features by defining one or more of the feature macros. See section `GNU CC Command Options' in The GNU CC Manual, for more information about GCC options.

You should define these macros by using `#define' preprocessor directives at the top of your source code files. These directives must come before any #include of a system header file. It is best to make them the very first thing in the file, preceded only by comments. You could also use the `-D' option to GCC, but it's better if you make the source files indicate their own meaning in a self-contained way.

This system exists to allow the library to conform to multiple standards. Although the different standards are often described as supersets of each other, they are usually incompatible because larger standards require functions with names that smaller ones reserve to the user program. This is not mere pedantry -- it has been a problem in practice. For instance, some non-GNU programs define functions named getline that have nothing to do with this library's getline. They would not be compilable if all features were enabled indiscriminately.

This should not be used to verify that a program conforms to a limited standard. It is insufficient for this purpose, as it will not protect you from including header files outside the standard, or relying on semantics undefined within the standard.

Macro: _POSIX_SOURCE
If you define this macro, then the functionality from the POSIX.1 standard (IEEE Standard 1003.1) is available, as well as all of the ISO C facilities.

The state of _POSIX_SOURCE is irrelevant if you define the macro _POSIX_C_SOURCE to a positive integer.

Macro: _POSIX_C_SOURCE
Define this macro to a positive integer to control which POSIX functionality is made available. The greater the value of this macro, the more functionality is made available.

If you define this macro to a value greater than or equal to 1, then the functionality from the 1990 edition of the POSIX.1 standard (IEEE Standard 1003.1-1990) is made available.

If you define this macro to a value greater than or equal to 2, then the functionality from the 1992 edition of the POSIX.2 standard (IEEE Standard 1003.2-1992) is made available.

If you define this macro to a value greater than or equal to 199309L, then the functionality from the 1993 edition of the POSIX.1b standard (IEEE Standard 1003.1b-1993) is made available.

Greater values for _POSIX_C_SOURCE will enable future extensions. The POSIX standards process will define these values as necessary, and the GNU C Library should support them some time after they become standardized. The 1996 edition of POSIX.1 (ISO/IEC 9945-1: 1996) states that if you define _POSIX_C_SOURCE to a value greater than or equal to 199506L, then the functionality from the 1996 edition is made available.

Macro: _BSD_SOURCE
If you define this macro, functionality derived from 4.3 BSD Unix is included as well as the ISO C, POSIX.1, and POSIX.2 material.

Some of the features derived from 4.3 BSD Unix conflict with the corresponding features specified by the POSIX.1 standard. If this macro is defined, the 4.3 BSD definitions take precedence over the POSIX definitions.

Due to the nature of some of the conflicts between 4.3 BSD and POSIX.1, you need to use a special BSD compatibility library when linking programs compiled for BSD compatibility. This is because some functions must be defined in two different ways, one of them in the normal C library, and one of them in the compatibility library. If your program defines _BSD_SOURCE, you must give the option `-lbsd-compat' to the compiler or linker when linking the program, to tell it to find functions in this special compatibility library before looking for them in the normal C library.

Macro: _SVID_SOURCE
If you define this macro, functionality derived from SVID is included as well as the ISO C, POSIX.1, POSIX.2, and X/Open material.

Macro: _XOPEN_SOURCE

Macro: _XOPEN_SOURCE_EXTENDED
If you define this macro, functionality described in the X/Open Portability Guide is included. This is a superset of the POSIX.1 and POSIX.2 functionality and in fact _POSIX_SOURCE and _POSIX_C_SOURCE are automatically defined.

As the unification of all Unices, functionality only available in BSD and SVID is also included.

If the macro _XOPEN_SOURCE_EXTENDED is also defined, even more functionality is available. The extra functions will make all functions available which are necessary for the X/Open Unix brand.

If the macro _XOPEN_SOURCE has the value @math{500} this includes all functionality described so far plus some new definitions from the Single Unix Specification, version 2.

Macro: _LARGEFILE_SOURCE
If this macro is defined some extra functions are available which rectify a few shortcomings in all previous standards. Specifically, the functions fseeko and ftello are available. Without these functions the difference between the ISO C interface (fseek, ftell) and the low-level POSIX interface (lseek) would lead to problems.

This macro was introduced as part of the Large File Support extension (LFS).

Macro: _LARGEFILE64_SOURCE
If you define this macro an additional set of functions is made available which enables 32 bit systems to use files of sizes beyond the usual limit of 2GB. This interface is not available if the system does not support files that large. On systems where the natural file size limit is greater than 2GB (i.e., on 64 bit systems) the new functions are identical to the replaced functions.

The new functionality is made available by a new set of types and functions which replace the existing ones. The names of these new objects contain 64 to indicate the intention, e.g., off_t vs. off64_t and fseeko vs. fseeko64.

This macro was introduced as part of the Large File Support extension (LFS). It is a transition interface for the period when 64 bit offsets are not generally used (see _FILE_OFFSET_BITS).

Macro: _FILE_OFFSET_BITS
This macro determines which file system interface shall be used, one replacing the other. Whereas _LARGEFILE64_SOURCE makes the 64 bit interface available as an additional interface, _FILE_OFFSET_BITS allows the 64 bit interface to replace the old interface.

If _FILE_OFFSET_BITS is undefined, or if it is defined to the value 32, nothing changes. The 32 bit interface is used and types like off_t have a size of 32 bits on 32 bit systems.

If the macro is defined to the value 64, the large file interface replaces the old interface. I.e., the functions are not made available under different names (as they are with _LARGEFILE64_SOURCE). Instead the old function names now reference the new functions, e.g., a call to fseeko now indeed calls fseeko64.

This macro should only be selected if the system provides mechanisms for handling large files. On 64 bit systems this macro has no effect since the *64 functions are identical to the normal functions.

This macro was introduced as part of the Large File Support extension (LFS).

Macro: _ISOC99_SOURCE
Until the revised ISO C standard is widely adopted the new features are not automatically enabled. The GNU libc nevertheless has a complete implementation of the new standard and to enable the new features the macro _ISOC99_SOURCE should be defined.

Macro: _GNU_SOURCE
If you define this macro, everything is included: ISO C89, ISO C99, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions. In the cases where POSIX.1 conflicts with BSD, the POSIX definitions take precedence.

If you want to get the full effect of _GNU_SOURCE but make the BSD definitions take precedence over the POSIX definitions, use this sequence of definitions:
#define _GNU_SOURCE
#define _BSD_SOURCE
#define _SVID_SOURCE
Note that if you do this, you must link your program with the BSD compatibility library by passing the `-lbsd-compat' option to the compiler or linker. Note: If you forget to do this, you may get very strange errors at run time.

Macro: _REENTRANT

Macro: _THREAD_SAFE
If you define one of these macros, reentrant versions of several functions get declared. Some of the functions are specified in POSIX.1c but many others are only available on a few other systems or are unique to GNU libc. The problem is the delay in the standardization of the thread safe C library interface.

Unlike on some other systems, no special version of the C library must be used for linking. There is only one version but while compiling this it must have been specified to compile as thread safe.

We recommend you use _GNU_SOURCE in new programs. If you don't specify the `-ansi' option to GCC and don't define any of these macros explicitly, the effect is the same as defining _POSIX_C_SOURCE to 2 and _POSIX_SOURCE, _SVID_SOURCE, and _BSD_SOURCE to 1.

When you define a feature test macro to request a larger class of features, it is harmless to define in addition a feature test macro for a subset of those features. For example, if you define _POSIX_C_SOURCE, then defining _POSIX_SOURCE as well has no effect. Likewise, if you define _GNU_SOURCE, then defining either _POSIX_SOURCE or _POSIX_C_SOURCE or _SVID_SOURCE as well has no effect.

Note, however, that the features of _BSD_SOURCE are not a subset of any of the other feature test macros supported. This is because it defines BSD features that take precedence over the POSIX features that are requested by the other macros. For this reason, defining _BSD_SOURCE in addition to the other feature test macros does have an effect: it causes the BSD features to take priority over the conflicting POSIX features.

Roadmap to the Manual

Here is an overview of the contents of the remaining chapters of this manual.

section Error Reporting, describes how errors detected by the library are reported.
section C Language Facilities in the Library, contains information about library support for standard parts of the C language, including things like the sizeof operator and the symbolic constant NULL, how to write functions accepting variable numbers of arguments, and constants describing the ranges and other properties of the numerical types. There is also a simple debugging mechanism which allows you to put assertions in your code, and have diagnostic messages printed if the tests fail.
section Virtual Memory Allocation And Paging, describes the GNU library's facilities for managing and using virtual and real memory, including dynamic allocation of virtual memory. If you do not know in advance how much memory your program needs, you can allocate it dynamically instead, and manipulate it via pointers.
section Character Handling, contains information about character classification functions (such as isspace) and functions for performing case conversion.
section String and Array Utilities, has descriptions of functions for manipulating strings (null-terminated character arrays) and general byte arrays, including operations such as copying and comparison.
section Input/Output Overview, gives an overall look at the input and output facilities in the library, and contains information about basic concepts such as file names.
section Input/Output on Streams, describes I/O operations involving streams (or FILE * objects). These are the normal C library functions from `stdio.h'.
section Low-Level Input/Output, contains information about I/O operations on file descriptors. File descriptors are a lower-level mechanism specific to the Unix family of operating systems.
section File System Interface, has descriptions of operations on entire files, such as functions for deleting and renaming them and for creating new directories. This chapter also contains information about how you can access the attributes of a file, such as its owner and file protection modes.
section Pipes and FIFOs, contains information about simple interprocess communication mechanisms. Pipes allow communication between two related processes (such as between a parent and child), while FIFOs allow communication between processes sharing a common file system on the same machine.
section Sockets, describes a more complicated interprocess communication mechanism that allows processes running on different machines to communicate over a network. This chapter also contains information about Internet host addressing and how to use the system network databases.
section Low-Level Terminal Interface, describes how you can change the attributes of a terminal device. If you want to disable echo of characters typed by the user, for example, read this chapter.
section Mathematics, contains information about the math library functions. These include things like random-number generators and remainder functions on integers as well as the usual trigonometric and exponential functions on floating-point numbers.
section Arithmetic Functions, describes functions for simple arithmetic, analysis of floating-point values, and reading numbers from strings.
section Searching and Sorting, contains information about functions for searching and sorting arrays. You can use these functions on any kind of array by providing an appropriate comparison function.
section Pattern Matching, presents functions for matching regular expressions and shell file name patterns, and for expanding words as the shell does.
section Date and Time, describes functions for measuring both calendar time and CPU time, as well as functions for setting alarms and timers.
section Character Set Handling, contains information about manipulating characters and strings using character sets larger than will fit in the usual char data type.
section Locales and Internationalization, describes how selecting a particular country or language affects the behavior of the library. For example, the locale affects collation sequences for strings and how monetary values are formatted.
section Non-Local Exits, contains descriptions of the setjmp and longjmp functions. These functions provide a facility for goto-like jumps which can jump from one function to another.
section Signal Handling, tells you all about signals--what they are, how to establish a handler that is called when a particular kind of signal is delivered, and how to prevent signals from arriving during critical sections of your program.
section The Basic Program/System Interface, tells how your programs can access their command-line arguments and environment variables.
section Processes, contains information about how to start new processes and run programs.
section Job Control, describes functions for manipulating process groups and the controlling terminal. This material is probably only of interest if you are writing a shell or other program which handles job control specially.
section System Databases and Name Service Switch, describes the services which are available for looking up names in the system databases, how to determine which service is used for which database, and how these services are implemented so that contributors can design their own services.
section User Database, and section Group Database, tell you how to access the system user and group databases.
section System Management, describes functions for controlling and getting information about the hardware and software configuration your program is executing under.
section System Configuration Parameters, tells you how you can get information about various operating system limits. Most of these parameters are provided for compatibility with POSIX.
section Summary of Library Facilities, gives a summary of all the functions, variables, and macros in the library, with complete data types and function prototypes, and says what standard or system each is derived from.
section Library Maintenance, explains how to build and install the GNU C library on your system, how to report any bugs you might find, and how to add new functions or port the library to a new system.

If you already know the name of the facility you are interested in, you can look it up in section Summary of Library Facilities. This gives you a summary of its syntax and a pointer to where you can find a more detailed description. This appendix is particularly useful if you just want to verify the order and type of arguments to a function, for example. It also tells you what standard or system each function, variable, or macro is derived from.
Error Reporting

Many functions in the GNU C library detect and report error conditions, and sometimes your programs need to check for these error conditions. For example, when you open an input file, you should verify that the file was actually opened correctly, and print an error message or take other appropriate action if the call to the library function failed.

This chapter describes how the error reporting facility works. Your program should include the header file `errno.h' to use this facility.

Checking for Errors

Most library functions return a special value to indicate that they have failed. The special value is typically -1, a null pointer, or a constant such as EOF that is defined for that purpose. But this return value tells you only that an error has occurred. To find out what kind of error it was, you need to look at the error code stored in the variable errno. This variable is declared in the header file `errno.h'.

Variable: volatile int errno
The variable errno contains the system error number. You can change the value of errno.

Since errno is declared volatile, it might be changed asynchronously by a signal handler; see section Defining Signal Handlers. However, a properly written signal handler saves and restores the value of errno, so you generally do not need to worry about this possibility except when writing signal handlers.

The initial value of errno at program startup is zero. Many library functions are guaranteed to set it to certain nonzero values when they encounter certain kinds of errors. These error conditions are listed for each function. These functions do not change errno when they succeed; thus, the value of errno after a successful call is not necessarily zero, and you should not use errno to determine whether a call failed. The proper way to do that is documented for each function. If the call failed, you can examine errno.

Many library functions can set errno to a nonzero value as a result of calling other library functions which might fail. You should assume that any library function might alter errno when the function returns an error.

Portability Note: ISO C specifies errno as a "modifiable lvalue" rather than as a variable, permitting it to be implemented as a macro. For example, its expansion might involve a function call, like *_errno (). In fact, that is what it is on the GNU system itself. The GNU library, on non-GNU systems, does whatever is right for the particular system.

There are a few library functions, like sqrt and atan, that return a perfectly legitimate value in case of an error, but also set errno. For these functions, if you want to check to see whether an error occurred, the recommended method is to set errno to zero before calling the function, and then check its value afterward.

All the error codes have symbolic names; they are macros defined in `errno.h'. The names start with `E' and an upper-case letter or digit; you should consider names of this form to be reserved names. See section Reserved Names.

The error code values are all positive integers and are all distinct, with one exception: EWOULDBLOCK and EAGAIN are the same. Since the values are distinct, you can use them as labels in a switch statement; just don't use both EWOULDBLOCK and EAGAIN. Your program should not make any other assumptions about the specific values of these symbolic constants.

The value of errno doesn't necessarily have to correspond to any of these macros, since some library functions might return other error codes of their own for other situations. The only values that are guaranteed to be meaningful for a particular library function are the ones that this manual lists for that function.

On non-GNU systems, almost any system call can return EFAULT if it is given an invalid pointer as an argument. Since this could only happen as a result of a bug in your program, and since it will not happen on the GNU system, we have saved space by not mentioning EFAULT in the descriptions of individual functions.

In some Unix systems, many system calls can also return EFAULT if given as an argument a pointer into the stack, and the kernel for some obscure reason fails in its attempt to extend the stack. If this ever happens, you should probably try using statically or dynamically allocated memory instead of stack memory on that system.

Error Codes

The error code macros are defined in the header file `errno.h'. All of them expand into integer constant values. Some of these error codes can't occur on the GNU system, but they can occur using the GNU library on other systems.

Macro: int EPERM
Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation.

Macro: int ENOENT
No such file or directory. This is a "file doesn't exist" error for ordinary files that are referenced in contexts where they are expected to already exist.

Macro: int ESRCH
No process matches the specified process ID.

Macro: int EINTR
Interrupted function call; an asynchronous signal occurred and prevented completion of the call. When this happens, you should try the call again.

You can choose to have functions resume after a signal that is handled, rather than failing with EINTR; see section Primitives Interrupted by Signals.

Macro: int EIO
Input/output error; usually used for physical read or write errors.

Macro: int ENXIO
No such device or address. The system tried to use the device represented by a file you specified, and it couldn't find the device. This can mean that the device file was installed incorrectly, or that the physical device is missing or not correctly attached to the computer.

Macro: int E2BIG
Argument list too long; used when the arguments passed to a new program being executed with one of the exec functions (see section Executing a File) occupy too much memory space. This condition never arises in the GNU system.

Macro: int ENOEXEC
Invalid executable file format. This condition is detected by the exec functions; see section Executing a File.

Macro: int EBADF
Bad file descriptor; for example, I/O on a descriptor that has been closed or reading from a descriptor open only for writing (or vice versa).

Macro: int ECHILD
There are no child processes. This error happens on operations that are supposed to manipulate child processes, when there aren't any processes to manipulate.

Macro: int EDEADLK
Deadlock avoided; allocating a system resource would have resulted in a deadlock situation. The system does not guarantee that it will notice all such situations. This error means you got lucky and the system noticed; it might just hang. See section File Locks, for an example.

Macro: int ENOMEM
No memory available. The system cannot allocate more virtual memory because its capacity is full.

Macro: int EACCES
Permission denied; the file permissions do not allow the attempted operation.

Macro: int EFAULT
Bad address; an invalid pointer was detected. In the GNU system, this error never happens; you get a signal instead.

Macro: int ENOTBLK
A file that isn't a block special file was given in a situation that requires one. For example, trying to mount an ordinary file as a file system in Unix gives this error.

Macro: int EBUSY
Resource busy; a system resource that can't be shared is already in use. For example, if you try to delete a file that is the root of a currently mounted filesystem, you get this error.

Macro: int EEXIST
File exists; an existing file was specified in a context where it only makes sense to specify a new file.

Macro: int EXDEV
An attempt to make an improper link across file systems was detected. This happens not only when you use link (see section Hard Links) but also when you rename a file with rename (see section Renaming Files).

Macro: int ENODEV
The wrong type of device was given to a function that expects a particular sort of device.

Macro: int ENOTDIR
A file that isn't a directory was specified when a directory is required.

Macro: int EISDIR
File is a directory; you cannot open a directory for writing, or create or remove hard links to it.

Macro: int EINVAL
Invalid argument. This is used to indicate various kinds of problems with passing the wrong argument to a library function.

Macro: int EMFILE
The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit.

In BSD and GNU, the number of open files is controlled by a resource limit that can usually be increased. If you get this error, you might want to increase the RLIMIT_NOFILE limit or make it unlimited; see section Limiting Resource Usage.

Macro: int ENFILE
There are too many distinct file openings in the entire system. Note that any number of linked channels count as just one file opening; see section Linked Channels. This error never occurs in the GNU system.

Macro: int ENOTTY
Inappropriate I/O control operation, such as trying to set terminal modes on an ordinary file.

Macro: int ETXTBSY
An attempt to execute a file that is currently open for writing, or write to a file that is currently being executed. Often using a debugger to run a program is considered having it open for writing and will cause this error. (The name stands for "text file busy".) This is not an error in the GNU system; the text is copied as necessary.

Macro: int EFBIG
File too big; the size of a file would be larger than allowed by the system.

Macro: int ENOSPC
No space left on device; write operation on a file failed because the disk is full.

Macro: int ESPIPE
Invalid seek operation (such as on a pipe).

Macro: int EROFS
An attempt was made to modify something on a read-only file system.

Macro: int EMLINK
Too many links; the link count of a single file would become too large. rename can cause this error if the file being renamed already has as many links as it can take (see section Renaming Files).

Macro: int EPIPE
Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a SIGPIPE signal; this signal terminates the program if not handled or blocked. Thus, your program will never actually see EPIPE unless it has handled or blocked SIGPIPE.

Macro: int EDOM
Domain error; used by mathematical functions when an argument value does not fall into the domain over which the function is defined.

Macro: int ERANGE
Range error; used by mathematical functions when the result value is not representable because of overflow or underflow.

Macro: int EAGAIN
Resource temporarily unavailable; the call might work if you try again later. The macro EWOULDBLOCK is another name for EAGAIN; they are always the same in the GNU C library.

This error can happen in a few different situations:

An operation that would block was attempted on an object that has non-blocking mode selected. Trying the same operation again will block until some external condition makes it possible to read, write, or connect (whatever the operation). You can use select to find out when the operation will be possible; see section Waiting for Input or Output. Portability Note: In many older Unix systems, this condition was indicated by EWOULDBLOCK, which was a distinct error code different from EAGAIN. To make your program portable, you should check for both codes and treat them the same.
A temporary resource shortage made an operation impossible. fork can return this error. It indicates that the shortage is expected to pass, so your program can try the call again later and it may succeed. It is probably a good idea to delay for a few seconds before trying it again, to allow time for other processes to release scarce resources. Such shortages are usually fairly serious and affect the whole system, so usually an interactive program should report the error to the user and return to its command loop.

Macro: int EWOULDBLOCK
In the GNU C library, this is another name for EAGAIN (above). The values are always the same, on every operating system.

C libraries in many older Unix systems have EWOULDBLOCK as a separate error code.

Macro: int EINPROGRESS
An operation that cannot complete immediately was initiated on an object that has non-blocking mode selected. Some functions that must always block (such as connect; see section Making a Connection) never return EAGAIN. Instead, they return EINPROGRESS to indicate that the operation has begun and will take some time. Attempts to manipulate the object before the call completes return EALREADY. You can use the select function to find out when the pending operation has completed; see section Waiting for Input or Output.

Macro: int EALREADY
An operation is already in progress on an object that has non-blocking mode selected.

Macro: int ENOTSOCK
A file that isn't a socket was specified when a socket is required.

Macro: int EMSGSIZE
The size of a message sent on a socket was larger than the supported maximum size.

Macro: int EPROTOTYPE
The socket type does not support the requested communications protocol.

Macro: int ENOPROTOOPT
You specified a socket option that doesn't make sense for the particular protocol being used by the socket. See section Socket Options.

Macro: int EPROTONOSUPPORT
The socket domain does not support the requested communications protocol (perhaps because the requested protocol is completely invalid). See section Creating a Socket.

Macro: int ESOCKTNOSUPPORT
The socket type is not supported.

Macro: int EOPNOTSUPP
The operation you requested is not supported. Some socket functions don't make sense for all types of sockets, and others may not be implemented for all communications protocols. In the GNU system, this error can happen for many calls when the object does not support the particular operation; it is a generic indication that the server knows nothing to do for that call.

Macro: int EPFNOSUPPORT
The socket communications protocol family you requested is not supported.

Macro: int EAFNOSUPPORT
The address family specified for a socket is not supported; it is inconsistent with the protocol being used on the socket. See section Sockets.

Macro: int EADDRINUSE
The requested socket address is already in use. See section Socket Addresses.

Macro: int EADDRNOTAVAIL
The requested socket address is not available; for example, you tried to give a socket a name that doesn't match the local host name. See section Socket Addresses.

Macro: int ENETDOWN
A socket operation failed because the network was down.

Macro: int ENETUNREACH
A socket operation failed because the subnet containing the remote host was unreachable.

Macro: int ENETRESET
A network connection was reset because the remote host crashed.

Macro: int ECONNABORTED
A network connection was aborted locally.

Macro: int ECONNRESET
A network connection was closed for reasons outside the control of the local host, such as by the remote machine rebooting or an unrecoverable protocol violation.

Macro: int ENOBUFS
The kernel's buffers for I/O operations are all in use. In GNU, this error is always synonymous with ENOMEM; you may get one or the other from network operations.

Macro: int EISCONN
You tried to connect a socket that is already connected. See section Making a Connection.

Macro: int ENOTCONN
The socket is not connected to anything. You get this error when you try to transmit data over a socket, without first specifying a destination for the data. For a connectionless socket (for datagram protocols, such as UDP), you get EDESTADDRREQ instead.

Macro: int EDESTADDRREQ
No default destination address was set for the socket. You get this error when you try to transmit data over a connectionless socket, without first specifying a destination for the data with connect.

Macro: int ESHUTDOWN
The socket has already been shut down.

Macro: int ETOOMANYREFS
???

Macro: int ETIMEDOUT
A socket operation with a specified timeout received no response during the timeout period.

Macro: int ECONNREFUSED
A remote host refused to allow the network connection (typically because it is not running the requested service).

Macro: int ELOOP
Too many levels of symbolic links were encountered in looking up a file name. This often indicates a cycle of symbolic links.

Macro: int ENAMETOOLONG
Filename too long (longer than PATH_MAX; see section Limits on File System Capacity) or host name too long (in gethostname or sethostname; see section Host Identification).

Macro: int EHOSTDOWN
The remote host for a requested network connection is down.

Macro: int EHOSTUNREACH
The remote host for a requested network connection is not reachable.

Macro: int ENOTEMPTY
Directory not empty, where an empty directory was expected. Typically, this error occurs when you are trying to delete a directory.

Macro: int EPROCLIM
This means that the per-user limit on new process would be exceeded by an attempted fork. See section Limiting Resource Usage, for details on the RLIMIT_NPROC limit.

Macro: int EUSERS
The file quota system is confused because there are too many users.

Macro: int EDQUOT
The user's disk quota was exceeded.

Macro: int ESTALE
Stale NFS file handle. This indicates an internal confusion in the NFS system which is due to file system rearrangements on the server host. Repairing this condition usually requires unmounting and remounting the NFS file system on the local host.

Macro: int EREMOTE
An attempt was made to NFS-mount a remote file system with a file name that already specifies an NFS-mounted file. (This is an error on some operating systems, but we expect it to work properly on the GNU system, making this error code impossible.)

Macro: int EBADRPC
???

Macro: int ERPCMISMATCH
???

Macro: int EPROGUNAVAIL
???

Macro: int EPROGMISMATCH
???

Macro: int EPROCUNAVAIL
???

Macro: int ENOLCK
No locks available. This is used by the file locking facilities; see section File Locks. This error is never generated by the GNU system, but it can result from an operation to an NFS server running another operating system.

Macro: int EFTYPE
Inappropriate file type or format. The file was the wrong type for the operation, or a data file had the wrong format.

On some systems chmod returns this error if you try to set the sticky bit on a non-directory file; see section Assigning File Permissions.

Macro: int EAUTH
???

Macro: int ENEEDAUTH
???

Macro: int ENOSYS
Function not implemented. This indicates that the function called is not implemented at all, either in the C library itself or in the operating system. When you get this error, you can be sure that this particular function will always fail with ENOSYS unless you install a new version of the C library or the operating system.

Macro: int ENOTSUP
Not supported. A function returns this error when certain parameter values are valid, but the functionality they request is not available. This can mean that the function does not implement a particular command or option value or flag bit at all. For functions that operate on some object given in a parameter, such as a file descriptor or a port, it might instead mean that only that specific object (file descriptor, port, etc.) is unable to support the other parameters given; different file descriptors might support different ranges of parameter values.

If the entire function is not available at all in the implementation, it returns ENOSYS instead.

Macro: int EILSEQ
While decoding a multibyte character the function came along an invalid or an incomplete sequence of bytes or the given wide character is invalid.

Macro: int EBACKGROUND
In the GNU system, servers supporting the term protocol return this error for certain operations when the caller is not in the foreground process group of the terminal. Users do not usually see this error because functions such as read and write translate it into a SIGTTIN or SIGTTOU signal. See section Job Control, for information on process groups and these signals.

Macro: int EDIED
In the GNU system, opening a file returns this error when the file is translated by a program and the translator program dies while starting up, before it has connected to the file.

Macro: int ED
The experienced user will know what is wrong.

Macro: int EGREGIOUS
You did what?

Macro: int EIEIO
Go home and have a glass of warm, dairy-fresh milk.

Macro: int EGRATUITOUS
This error code has no purpose.

Macro: int EBADMSG

Macro: int EIDRM

Macro: int EMULTIHOP

Macro: int ENODATA

Macro: int ENOLINK

Macro: int ENOMSG

Macro: int ENOSR

Macro: int ENOSTR

Macro: int EOVERFLOW

Macro: int EPROTO

Macro: int ETIME

The following error codes are defined by the Linux/i386 kernel. They are not yet documented.

Macro: int ERESTART

Macro: int ECHRNG

Macro: int EL2NSYNC

Macro: int EL3HLT

Macro: int EL3RST

Macro: int ELNRNG

Macro: int EUNATCH

Macro: int ENOCSI

Macro: int EL2HLT

Macro: int EBADE

Macro: int EBADR

Macro: int EXFULL

Macro: int ENOANO

Macro: int EBADRQC

Macro: int EBADSLT

Macro: int EDEADLOCK

Macro: int EBFONT

Macro: int ENONET

Macro: int ENOPKG

Macro: int EADV

Macro: int ESRMNT

Macro: int ECOMM

Macro: int EDOTDOT

Macro: int ENOTUNIQ

Macro: int EBADFD

Macro: int EREMCHG

Macro: int ELIBACC

Macro: int ELIBBAD

Macro: int ELIBSCN

Macro: int ELIBMAX

Macro: int ELIBEXEC

Macro: int ESTRPIPE

Macro: int EUCLEAN

Macro: int ENOTNAM

Macro: int ENAVAIL

Macro: int EISNAM

Macro: int EREMOTEIO

Macro: int ENOMEDIUM

Macro: int EMEDIUMTYPE

Error Messages

The library has functions and variables designed to make it easy for your program to report informative error messages in the customary format about the failure of a library call. The functions strerror and perror give you the standard error message for a given error code; the variable program_invocation_short_name gives you convenient access to the name of the program that encountered the error.

Function: char * strerror (int errnum)
The strerror function maps the error code (see section Checking for Errors) specified by the errnum argument to a descriptive error message string. The return value is a pointer to this string.

The value errnum normally comes from the variable errno.

You should not modify the string returned by strerror. Also, if you make subsequent calls to strerror, the string might be overwritten. (But it's guaranteed that no library function ever calls strerror behind your back.)

The function strerror is declared in `string.h'.

Function: char * strerror_r (int errnum, char *buf, size_t n)
The strerror_r function works like strerror but instead of returning the error message in a statically allocated buffer shared by all threads in the process, it returns a private copy for the thread. This might be either some permanent global data or a message string in the user supplied buffer starting at buf with the length of n bytes.

At most n characters are written (including the NUL byte) so it is up to the user to select the buffer large enough.

This function should always be used in multi-threaded programs since there is no way to guarantee the string returned by strerror really belongs to the last call of the current thread.

This function strerror_r is a GNU extension and it is declared in `string.h'.

Function: void perror (const char *message)
This function prints an error message to the stream stderr; see section Standard Streams.

If you call perror with a message that is either a null pointer or an empty string, perror just prints the error message corresponding to errno, adding a trailing newline.

If you supply a non-null message argument, then perror prefixes its output with this string. It adds a colon and a space character to separate the message from the error string corresponding to errno.

The function perror is declared in `stdio.h'.

strerror and perror produce the exact same message for any given error code; the precise text varies from system to system. On the GNU system, the messages are fairly short; there are no multi-line messages or embedded newlines. Each error message begins with a capital letter and does not include any terminating punctuation.

Compatibility Note: The strerror function is a new feature of ISO C. Many older C systems do not support this function yet.

Many programs that don't read input from the terminal are designed to exit if any system call fails. By convention, the error message from such a program should start with the program's name, sans directories. You can find that name in the variable program_invocation_short_name; the full file name is stored the variable program_invocation_name.

Variable: char * program_invocation_name
This variable's value is the name that was used to invoke the program running in the current process. It is the same as argv[0]. Note that this is not necessarily a useful file name; often it contains no directory names. See section Program Arguments.

Variable: char * program_invocation_short_name
This variable's value is the name that was used to invoke the program running in the current process, with directory names removed. (That is to say, it is the same as program_invocation_name minus everything up to the last slash, if any.)

The library initialization code sets up both of these variables before calling main.

Portability Note: These two variables are GNU extensions. If you want your program to work with non-GNU libraries, you must save the value of argv[0] in main, and then strip off the directory names yourself. We added these extensions to make it possible to write self-contained error-reporting subroutines that require no explicit cooperation from main.

Here is an example showing how to handle failure to open a file correctly. The function open_sesame tries to open the named file for reading and returns a stream if successful. The fopen library function returns a null pointer if it couldn't open the file for some reason. In that situation, open_sesame constructs an appropriate error message using the strerror function, and terminates the program. If we were going to make some other library calls before passing the error code to strerror, we'd have to save it in a local variable instead, because those other library functions might overwrite errno in the meantime.
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

FILE *
open_sesame (char *name)
{
  FILE *stream;

  errno = 0;
  stream = fopen (name, "r");
  if (stream == NULL)
    {
      fprintf (stderr, "%s: Couldn't open file %s; %s\n",
               program_invocation_short_name, name, strerror (errno));
      exit (EXIT_FAILURE);
    }
  else
    return stream;
}
Virtual Memory Allocation And Paging

This chapter describes how processes manage and use memory in a system that uses the GNU C library.

The GNU C Library has several functions for dynamically allocating virtual memory in various ways. They vary in generality and in efficiency. The library also provides functions for controlling paging and allocation of real memory.

Memory mapped I/O is not discussed in this chapter. See section Memory-mapped I/O.

Process Memory Concepts

One of the most basic resources a process has available to it is memory. There are a lot of different ways systems organize memory, but in a typical one, each process has one linear virtual address space, with addresses running from zero to some huge maximum. It need not be contiguous; i.e. not all of these addresses actually can be used to store data.

The virtual memory is divided into pages (4 kilobytes is typical). Backing each page of virtual memory is a page of real memory (called a frame) or some secondary storage, usually disk space. The disk space might be swap space or just some ordinary disk file. Actually, a page of all zeroes sometimes has nothing at all backing it -- there's just a flag saying it is all zeroes.

The same frame of real memory or backing store can back multiple virtual pages belonging to multiple processes. This is normally the case, for example, with virtual memory occupied by GNU C library code. The same real memory frame containing the printf function backs a virtual memory page in each of the existing processes that has a printf call in its program.

In order for a program to access any part of a virtual page, the page must at that moment be backed by ("connected to") a real frame. But because there is usually a lot more virtual memory than real memory, the pages must move back and forth between real memory and backing store regularly, coming into real memory when a process needs to access them and then retreating to backing store when not needed anymore. This movement is called paging.

When a program attempts to access a page which is not at that moment backed by real memory, this is known as a page fault. When a page fault occurs, the kernel suspends the process, places the page into a real page frame (this is called "paging in" or "faulting in"), then resumes the process so that from the process' point of view, the page was in real memory all along. In fact, to the process, all pages always seem to be in real memory. Except for one thing: the elapsed execution time of an instruction that would normally be a few nanoseconds is suddenly much, much, longer (because the kernel normally has to do I/O to complete the page-in). For programs sensitive to that, the functions described in section Locking Pages can control it.

Within each virtual address space, a process has to keep track of what is at which addresses, and that process is called memory allocation. Allocation usually brings to mind meting out scarce resources, but in the case of virtual memory, that's not a major goal, because there is generally much more of it than anyone needs. Memory allocation within a process is mainly just a matter of making sure that the same byte of memory isn't used to store two different things.

Processes allocate memory in two major ways: by exec and programmatically. Actually, forking is a third way, but it's not very interesting. See section Creating a Process.

Exec is the operation of creating a virtual address space for a process, loading its basic program into it, and executing the program. It is done by the "exec" family of functions (e.g. execl). The operation takes a program file (an executable), it allocates space to load all the data in the executable, loads it, and transfers control to it. That data is most notably the instructions of the program (the text), but also literals and constants in the program and even some variables: C variables with the static storage class (see section Memory Allocation in C Programs).

Once that program begins to execute, it uses programmatic allocation to gain additional memory. In a C program with the GNU C library, there are two kinds of programmatic allocation: automatic and dynamic. See section Memory Allocation in C Programs.

Memory-mapped I/O is another form of dynamic virtual memory allocation. Mapping memory to a file means declaring that the contents of certain range of a process' addresses shall be identical to the contents of a specified regular file. The system makes the virtual memory initially contain the contents of the file, and if you modify the memory, the system writes the same modification to the file. Note that due to the magic of virtual memory and page faults, there is no reason for the system to do I/O to read the file, or allocate real memory for its contents, until the program accesses the virtual memory. See section Memory-mapped I/O.

Just as it programmatically allocates memory, the program can programmatically deallocate (free) it. You can't free the memory that was allocated by exec. When the program exits or execs, you might say that all its memory gets freed, but since in both cases the address space ceases to exist, the point is really moot. See section Program Termination.

A process' virtual address space is divided into segments. A segment is a contiguous range of virtual addresses. Three important segments are:

The text segment contains a program's instructions and literals and static constants. It is allocated by exec and stays the same size for the life of the virtual address space.
The data segment is working storage for the program. It can be preallocated and preloaded by exec and the process can extend or shrink it by calling functions as described in See section Resizing the Data Segment. Its lower end is fixed.
The stack segment contains a program stack. It grows as the stack grows, but doesn't shrink when the stack shrinks.

Allocating Storage For Program Data

This section covers how ordinary programs manage storage for their data, including the famous malloc function and some fancier facilities special the GNU C library and GNU Compiler.

Memory Allocation in C Programs

The C language supports two kinds of memory allocation through the variables in C programs:

Static allocation is what happens when you declare a static or global variable. Each static or global variable defines one block of space, of a fixed size. The space is allocated once, when your program is started (part of the exec operation), and is never freed.
Automatic allocation happens when you declare an automatic variable, such as a function argument or a local variable. The space for an automatic variable is allocated when the compound statement containing the declaration is entered, and is freed when that compound statement is exited. In GNU C, the size of the automatic storage can be an expression that varies. In other C implementations, it must be a constant.

A third important kind of memory allocation, dynamic allocation, is not supported by C variables but is available via GNU C library functions.

Dynamic Memory Allocation

Dynamic memory allocation is a technique in which programs determine as they are running where to store some information. You need dynamic allocation when the amount of memory you need, or how long you continue to need it, depends on factors that are not known before the program runs.

For example, you may need a block to store a line read from an input file; since there is no limit to how long a line can be, you must allocate the memory dynamically and make it dynamically larger as you read more of the line.

Or, you may need a block for each record or each definition in the input data; since you can't know in advance how many there will be, you must allocate a new block for each record or definition as you read it.

When you use dynamic allocation, the allocation of a block of memory is an action that the program requests explicitly. You call a function or macro when you want to allocate space, and specify the size with an argument. If you want to free the space, you do so by calling another function or macro. You can do these things whenever you want, as often as you want.

Dynamic allocation is not supported by C variables; there is no storage class "dynamic", and there can never be a C variable whose value is stored in dynamically allocated space. The only way to get dynamically allocated memory is via a system call (which is generally via a GNU C library function call), and the only way to refer to dynamically allocated space is through a pointer. Because it is less convenient, and because the actual process of dynamic allocation requires more computation time, programmers generally use dynamic allocation only when neither static nor automatic allocation will serve.

For example, if you want to allocate dynamically some space to hold a struct foobar, you cannot declare a variable of type struct foobar whose contents are the dynamically allocated space. But you can declare a variable of pointer type struct foobar * and assign it the address of the space. Then you can use the operators `*' and `->' on this pointer variable to refer to the contents of the space:
{
  struct foobar *ptr
     = (struct foobar *) malloc (sizeof (struct foobar));
  ptr->name = x;
  ptr->next = current_foobar;
  current_foobar = ptr;
}
Unconstrained Allocation

The most general dynamic allocation facility is malloc. It allows you to allocate blocks of memory of any size at any time, make them bigger or smaller at any time, and free the blocks individually at any time (or never).

Basic Memory Allocation

To allocate a block of memory, call malloc. The prototype for this function is in `stdlib.h'.

Function: void * malloc (size_t size)
This function returns a pointer to a newly allocated block size bytes long, or a null pointer if the block could not be allocated.

The contents of the block are undefined; you must initialize it yourself (or use calloc instead; see section Allocating Cleared Space). Normally you would cast the value as a pointer to the kind of object that you want to store in the block. Here we show an example of doing so, and of initializing the space with zeros using the library function memset (see section Copying and Concatenation):
struct foo *ptr;
...
ptr = (struct foo *) malloc (sizeof (struct foo));
if (ptr == 0) abort ();
memset (ptr, 0, sizeof (struct foo));
You can store the result of malloc into any pointer variable without a cast, because ISO C automatically converts the type void * to another type of pointer when necessary. But the cast is necessary in contexts other than assignment operators or if you might want your code to run in traditional C.

Remember that when allocating space for a string, the argument to malloc must be one plus the length of the string. This is because a string is terminated with a null character that doesn't count in the "length" of the string but does need space. For example:
char *ptr;
...
ptr = (char *) malloc (length + 1);
See section Representation of Strings, for more information about this.

Examples of malloc

If no more space is available, malloc returns a null pointer. You should check the value of every call to malloc. It is useful to write a subroutine that calls malloc and reports an error if the value is a null pointer, returning only if the value is nonzero. This function is conventionally called xmalloc. Here it is:
void *
xmalloc (size_t size)
{
  register void *value = malloc (size);
  if (value == 0)
    fatal ("virtual memory exhausted");
  return value;
}
Here is a real example of using malloc (by way of xmalloc). The function savestring will copy a sequence of characters into a newly allocated null-terminated string:
char *
savestring (const char *ptr, size_t len)
{
  register char *value = (char *) xmalloc (len + 1);
  value[len] = '\0';
  return (char *) memcpy (value, ptr, len);
}
The block that malloc gives you is guaranteed to be aligned so that it can hold any type of data. In the GNU system, the address is always a multiple of eight on most systems, and a multiple of 16 on 64-bit systems. Only rarely is any higher boundary (such as a page boundary) necessary; for those cases, use memalign, posix_memalign or valloc (see section Allocating Aligned Memory Blocks).

Note that the memory located after the end of the block is likely to be in use for something else; perhaps a block already allocated by another call to malloc. If you attempt to treat the block as longer than you asked for it to be, you are liable to destroy the data that malloc uses to keep track of its blocks, or you may destroy the contents of another block. If you have already allocated a block and discover you want it to be bigger, use realloc (see section Changing the Size of a Block).

Freeing Memory Allocated with malloc

When you no longer need a block that you got with malloc, use the function free to make the block available to be allocated again. The prototype for this function is in `stdlib.h'.

Function: void free (void *ptr)
The free function deallocates the block of memory pointed at by ptr.

Function: void cfree (void *ptr)
This function does the same thing as free. It's provided for backward compatibility with SunOS; you should use free instead.

Freeing a block alters the contents of the block. Do not expect to find any data (such as a pointer to the next block in a chain of blocks) in the block after freeing it. Copy whatever you need out of the block before freeing it! Here is an example of the proper way to free all the blocks in a chain, and the strings that they point to:
struct chain
  {
    struct chain *next;
    char *name;
  }

void
free_chain (struct chain *chain)
{
  while (chain != 0)
    {
      struct chain *next = chain->next;
      free (chain->name);
      free (chain);
      chain = next;
    }
}
Occasionally, free can actually return memory to the operating system and make the process smaller. Usually, all it can do is allow a later call to malloc to reuse the space. In the meantime, the space remains in your program as part of a free-list used internally by malloc.

There is no point in freeing blocks at the end of a program, because all of the program's space is given back to the system when the process terminates.

Changing the Size of a Block

Often you do not know for certain how big a block you will ultimately need at the time you must begin to use the block. For example, the block might be a buffer that you use to hold a line being read from a file; no matter how long you make the buffer initially, you may encounter a line that is longer.

You can make the block longer by calling realloc. This function is declared in `stdlib.h'.

Function: void * realloc (void *ptr, size_t newsize)
The realloc function changes the size of the block whose address is ptr to be newsize.

Since the space after the end of the block may be in use, realloc may find it necessary to copy the block to a new address where more free space is available. The value of realloc is the new address of the block. If the block needs to be moved, realloc copies the old contents.

If you pass a null pointer for ptr, realloc behaves just like `malloc (newsize)'. This can be convenient, but beware that older implementations (before ISO C) may not support this behavior, and will probably crash when realloc is passed a null pointer.

Like malloc, realloc may return a null pointer if no memory space is available to make the block bigger. When this happens, the original block is untouched; it has not been modified or relocated.

In most cases it makes no difference what happens to the original block when realloc fails, because the application program cannot continue when it is out of memory, and the only thing to do is to give a fatal error message. Often it is convenient to write and use a subroutine, conventionally called xrealloc, that takes care of the error message as xmalloc does for malloc:
void *
xrealloc (void *ptr, size_t size)
{
  register void *value = realloc (ptr, size);
  if (value == 0)
    fatal ("Virtual memory exhausted");
  return value;
}
You can also use realloc to make a block smaller. The reason you would do this is to avoid tying up a lot of memory space when only a little is needed. In several allocation implementations, making a block smaller sometimes necessitates copying it, so it can fail if no other space is available.

If the new size you specify is the same as the old size, realloc is guaranteed to change nothing and return the same address that you gave.

Allocating Cleared Space

The function calloc allocates memory and clears it to zero. It is declared in `stdlib.h'.

Function: void * calloc (size_t count, size_t eltsize)
This function allocates a block long enough to contain a vector of count elements, each of size eltsize. Its contents are cleared to zero before calloc returns.

You could define calloc as follows:
void *
calloc (size_t count, size_t eltsize)
{
  size_t size = count * eltsize;
  void *value = malloc (size);
  if (value != 0)
    memset (value, 0, size);
  return value;
}
But in general, it is not guaranteed that calloc calls malloc internally. Therefore, if an application provides its own malloc/realloc/free outside the C library, it should always define calloc, too.

Efficiency Considerations for malloc

As opposed to other versions, the malloc in the GNU C Library does not round up block sizes to powers of two, neither for large nor for small sizes. Neighboring chunks can be coalesced on a free no matter what their size is. This makes the implementation suitable for all kinds of allocation patterns without generally incurring high memory waste through fragmentation.

Very large blocks (much larger than a page) are allocated with mmap (anonymous or via /dev/zero) by this implementation. This has the great advantage that these chunks are returned to the system immediately when they are freed. Therefore, it cannot happen that a large chunk becomes "locked" in between smaller ones and even after calling free wastes memory. The size threshold for mmap to be used can be adjusted with mallopt. The use of mmap can also be disabled completely.

Allocating Aligned Memory Blocks

The address of a block returned by malloc or realloc in the GNU system is always a multiple of eight (or sixteen on 64-bit systems). If you need a block whose address is a multiple of a higher power of two than that, use memalign, posix_memalign, or valloc. These functions are declared in `stdlib.h'.

With the GNU library, you can use free to free the blocks that memalign, posix_memalign, and valloc return. That does not work in BSD, however--BSD does not provide any way to free such blocks.

Function: void * memalign (size_t boundary, size_t size)
The memalign function allocates a block of size bytes whose address is a multiple of boundary. The boundary must be a power of two! The function memalign works by allocating a somewhat larger block, and then returning an address within the block that is on the specified boundary.

Function: int posix_memalign (void **memptr, size_t alignment, size_t size)
The posix_memalign function is similar to the memalign function in that it returns a buffer of size bytes aligned to a multiple of alignment. But it adds one requirement to the parameter alignment: the value must be a power of two multiple of sizeof (void *).

If the function succeeds in allocation memory a pointer to the allocated memory is returned in *memptr and the return value is zero. Otherwise the function returns an error value indicating the problem.

This function was introduced in POSIX 1003.1d.

Function: void * valloc (size_t size)
Using valloc is like using memalign and passing the page size as the value of the second argument. It is implemented like this:
void *
valloc (size_t size)
{
  return memalign (getpagesize (), size);
}
section How to get information about the memory subsystem? for more information about the memory subsystem.

Malloc Tunable Parameters

You can adjust some parameters for dynamic memory allocation with the mallopt function. This function is the general SVID/XPG interface, defined in `malloc.h'.

Function: int mallopt (int param, int value)
When calling mallopt, the param argument specifies the parameter to be set, and value the new value to be set. Possible choices for param, as defined in `malloc.h', are:

M_TRIM_THRESHOLD
This is the minimum size (in bytes) of the top-most, releasable chunk that will cause sbrk to be called with a negative argument in order to return memory to the system.
M_TOP_PAD
This parameter determines the amount of extra memory to obtain from the system when a call to sbrk is required. It also specifies the number of bytes to retain when shrinking the heap by calling sbrk with a negative argument. This provides the necessary hysteresis in heap size such that excessive amounts of system calls can be avoided.
M_MMAP_THRESHOLD
All chunks larger than this value are allocated outside the normal heap, using the mmap system call. This way it is guaranteed that the memory for these chunks can be returned to the system on free.
M_MMAP_MAX
The maximum number of chunks to allocate with mmap. Setting this to zero disables all use of mmap.
Heap Consistency Checking

You can ask malloc to check the consistency of dynamic memory by using the mcheck function. This function is a GNU extension, declared in `mcheck.h'.

Function: int mcheck (void (*abortfn) (enum mcheck_status status))
Calling mcheck tells malloc to perform occasional consistency checks. These will catch things such as writing past the end of a block that was allocated with malloc.

The abortfn argument is the function to call when an inconsistency is found. If you supply a null pointer, then mcheck uses a default function which prints a message and calls abort (see section Aborting a Program). The function you supply is called with one argument, which says what sort of inconsistency was detected; its type is described below.

It is too late to begin allocation checking once you have allocated anything with malloc. So mcheck does nothing in that case. The function returns -1 if you call it too late, and 0 otherwise (when it is successful).

The easiest way to arrange to call mcheck early enough is to use the option `-lmcheck' when you link your program; then you don't need to modify your program source at all. Alternatively you might use a debugger to insert a call to mcheck whenever the program is started, for example these gdb commands will automatically call mcheck whenever the program starts:
(gdb) break main
Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10
(gdb) command 1
Type commands for when breakpoint 1 is hit, one per line.
End with a line saying just "end".
>call mcheck(0)
>continue
>end
(gdb) ...
This will however only work if no initialization function of any object involved calls any of the malloc functions since mcheck must be called before the first such function.

Function: enum mcheck_status mprobe (void *pointer)
The mprobe function lets you explicitly check for inconsistencies in a particular allocated block. You must have already called mcheck at the beginning of the program, to do its occasional checks; calling mprobe requests an additional consistency check to be done at the time of the call.

The argument pointer must be a pointer returned by malloc or realloc. mprobe returns a value that says what inconsistency, if any, was found. The values are described below.

Data Type: enum mcheck_status
This enumerated type describes what kind of inconsistency was detected in an allocated block, if any. Here are the possible values:

MCHECK_DISABLED
mcheck was not called before the first allocation. No consistency checking can be done.
MCHECK_OK
No inconsistency detected.
MCHECK_HEAD
The data immediately before the block was modified. This commonly happens when an array index or pointer is decremented too far.
MCHECK_TAIL
The data immediately after the block was modified. This commonly happens when an array index or pointer is incremented too far.
MCHECK_FREE
The block was already freed.
Another possibility to check for and guard against bugs in the use of malloc, realloc and free is to set the environment variable MALLOC_CHECK_. When MALLOC_CHECK_ is set, a special (less efficient) implementation is used which is designed to be tolerant against simple errors, such as double calls of free with the same argument, or overruns of a single byte (off-by-one bugs). Not all such errors can be protected against, however, and memory leaks can result. If MALLOC_CHECK_ is set to 0, any detected heap corruption is silently ignored; if set to 1, a diagnostic is printed on stderr; if set to 2, abort is called immediately. This can be useful because otherwise a crash may happen much later, and the true cause for the problem is then very hard to track down.

There is one problem with MALLOC_CHECK_: in SUID or SGID binaries it could possibly be exploited since diverging from the normal programs behaviour it now writes something to the standard error desriptor. Therefore the use of MALLOC_CHECK_ is disabled by default for SUID and SGID binaries. It can be enabled again by the system administrator by adding a file `/etc/suid-debug' (the content is not important it could be empty).

So, what's the difference between using MALLOC_CHECK_ and linking with `-lmcheck'? MALLOC_CHECK_ is orthogonal with respect to `-lmcheck'. `-lmcheck' has been added for backward compatibility. Both MALLOC_CHECK_ and `-lmcheck' should uncover the same bugs - but using MALLOC_CHECK_ you don't need to recompile your application.

Memory Allocation Hooks

The GNU C library lets you modify the behavior of malloc, realloc, and free by specifying appropriate hook functions. You can use these hooks to help you debug programs that use dynamic memory allocation, for example.

The hook variables are declared in `malloc.h'.

Variable: __malloc_hook
The value of this variable is a pointer to the function that malloc uses whenever it is called. You should define this function to look like malloc; that is, like:
void *function (size_t size, const void *caller)
The value of caller is the return address found on the stack when the malloc function was called. This value allows you to trace the memory consumption of the program.

Variable: __realloc_hook
The value of this variable is a pointer to function that realloc uses whenever it is called. You should define this function to look like realloc; that is, like:
void *function (void *ptr, size_t size, const void *caller)
The value of caller is the return address found on the stack when the realloc function was called. This value allows you to trace the memory consumption of the program.

Variable: __free_hook
The value of this variable is a pointer to function that free uses whenever it is called. You should define this function to look like free; that is, like:
void function (void *ptr, const void *caller)
The value of caller is the return address found on the stack when the free function was called. This value allows you to trace the memory consumption of the program.

Variable: __memalign_hook
The value of this variable is a pointer to function that memalign uses whenever it is called. You should define this function to look like memalign; that is, like:
void *function (size_t size, size_t alignment, const void *caller)
The value of caller is the return address found on the stack when the memalign function was called. This value allows you to trace the memory consumption of the program.

You must make sure that the function you install as a hook for one of these functions does not call that function recursively without restoring the old value of the hook first! Otherwise, your program will get stuck in an infinite recursion. Before calling the function recursively, one should make sure to restore all the hooks to their previous value. When coming back from the recursive call, all the hooks should be resaved since a hook might modify itself.

Variable: __malloc_initialize_hook
The value of this variable is a pointer to a function that is called once when the malloc implementation is initialized. This is a weak variable, so it can be overridden in the application with a definition like the following:
void (*__malloc_initialize_hook) (void) = my_init_hook;
An issue to look out for is the time at which the malloc hook functions can be safely installed. If the hook functions call the malloc-related functions recursively, it is necessary that malloc has already properly initialized itself at the time when __malloc_hook etc. is assigned to. On the other hand, if the hook functions provide a complete malloc implementation of their own, it is vital that the hooks are assigned to before the very first malloc call has completed, because otherwise a chunk obtained from the ordinary, un-hooked malloc may later be handed to __free_hook, for example.

In both cases, the problem can be solved by setting up the hooks from within a user-defined function pointed to by __malloc_initialize_hook---then the hooks will be set up safely at the right time.

Here is an example showing how to use __malloc_hook and __free_hook properly. It installs a function that prints out information every time malloc or free is called. We just assume here that realloc and memalign are not used in our program.
/* Prototypes for __malloc_hook, __free_hook */
#include <malloc.h>

/* Prototypes for our hooks.  */
static void *my_init_hook (void);
static void *my_malloc_hook (size_t, const void *);
static void my_free_hook (void*, const void *);

/* Override initializing hook from the C library. */
void (*__malloc_initialize_hook) (void) = my_init_hook;

static void
my_init_hook (void)
{
  old_malloc_hook = __malloc_hook;
  old_free_hook = __free_hook;
  __malloc_hook = my_malloc_hook;
  __free_hook = my_free_hook;
}

static void *
my_malloc_hook (size_t size, const void *caller)
{
  void *result;
  /* Restore all old hooks */
  __malloc_hook = old_malloc_hook;
  __free_hook = old_free_hook;
  /* Call recursively */
  result = malloc (size);
  /* Save underlaying hooks */
  old_malloc_hook = __malloc_hook;
  old_free_hook = __free_hook;
  /* printf might call malloc, so protect it too. */
  printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
  /* Restore our own hooks */
  __malloc_hook = my_malloc_hook;
  __free_hook = my_free_hook;
  return result;
}

static void *
my_free_hook (void *ptr, const void *caller)
{
  /* Restore all old hooks */
  __malloc_hook = old_malloc_hook;
  __free_hook = old_free_hook;
  /* Call recursively */
  free (ptr);
  /* Save underlaying hooks */
  old_malloc_hook = __malloc_hook;
  old_free_hook = __free_hook;
  /* printf might call free, so protect it too. */
  printf ("freed pointer %p\n", ptr);
  /* Restore our own hooks */
  __malloc_hook = my_malloc_hook;
  __free_hook = my_free_hook;
}

main ()
{
  ...
}
The mcheck function (see section Heap Consistency Checking) works by installing such hooks.

Statistics for Memory Allocation with malloc

You can get information about dynamic memory allocation by calling the mallinfo function. This function and its associated data type are declared in `malloc.h'; they are an extension of the standard SVID/XPG version.

Data Type: struct mallinfo
This structure type is used to return information about the dynamic memory allocator. It contains the following members:

int arena
This is the total size of memory allocated with sbrk by malloc, in bytes.
int ordblks
This is the number of chunks not in use. (The memory allocator internally gets chunks of memory from the operating system, and then carves them up to satisfy individual malloc requests; see section Efficiency Considerations for malloc.)
int smblks
This field is unused.
int hblks
This is the total number of chunks allocated with mmap.
int hblkhd
This is the total size of memory allocated with mmap, in bytes.
int usmblks
This field is unused.
int fsmblks
This field is unused.
int uordblks
This is the total size of memory occupied by chunks handed out by malloc.
int fordblks
This is the total size of memory occupied by free (not in use) chunks.
int keepcost
This is the size of the top-most releasable chunk that normally borders the end of the heap (i.e. the high end of the virtual address space's data segment).

Function: struct mallinfo mallinfo (void)
This function returns information about the current dynamic memory usage in a structure of type struct mallinfo.

Summary of malloc-Related Functions

Here is a summary of the functions that work with malloc:

void *malloc (size_t size)
Allocate a block of size bytes. See section Basic Memory Allocation.
void free (void *addr)
Free a block previously allocated by malloc. See section Freeing Memory Allocated with malloc.
void *realloc (void *addr, size_t size)
Make a block previously allocated by malloc larger or smaller, possibly by copying it to a new location. See section Changing the Size of a Block.
void *calloc (size_t count, size_t eltsize)
Allocate a block of count * eltsize bytes using malloc, and set its contents to zero. See section Allocating Cleared Space.
void *valloc (size_t size)
Allocate a block of size bytes, starting on a page boundary. See section Allocating Aligned Memory Blocks.
void *memalign (size_t size, size_t boundary)
Allocate a block of size bytes, starting on an address that is a multiple of boundary. See section Allocating Aligned Memory Blocks.
int mallopt (int param, int value)
Adjust a tunable parameter. See section Malloc Tunable Parameters.
int mcheck (void (*abortfn) (void))
Tell malloc to perform occasional consistency checks on dynamically allocated memory, and to call abortfn when an inconsistency is found. See section Heap Consistency Checking.
void *(*__malloc_hook) (size_t size, const void *caller)
A pointer to a function that malloc uses whenever it is called.
void *(*__realloc_hook) (void *ptr, size_t size, const void *caller)
A pointer to a function that realloc uses whenever it is called.
void (*__free_hook) (void *ptr, const void *caller)
A pointer to a function that free uses whenever it is called.
void (*__memalign_hook) (size_t size, size_t alignment, const void *caller)
A pointer to a function that memalign uses whenever it is called.
struct mallinfo mallinfo (void)
Return information about the current dynamic memory usage. See section Statistics for Memory Allocation with malloc.
Allocation Debugging

A complicated task when programming with languages which do not use garbage collected dynamic memory allocation is to find memory leaks. Long running programs must assure that dynamically allocated objects are freed at the end of their lifetime. If this does not happen the system runs out of memory, sooner or later.

The malloc implementation in the GNU C library provides some simple means to detect such leaks and obtain some information to find the location. To do this the application must be started in a special mode which is enabled by an environment variable. There are no speed penalties for the program if the debugging mode is not enabled.

How to install the tracing functionality

Function: void mtrace (void)
When the mtrace function is called it looks for an environment variable named MALLOC_TRACE. This variable is supposed to contain a valid file name. The user must have write access. If the file already exists it is truncated. If the environment variable is not set or it does not name a valid file which can be opened for writing nothing is done. The behaviour of malloc etc. is not changed. For obvious reasons this also happens if the application is installed with the SUID or SGID bit set.

If the named file is successfully opened, mtrace installs special handlers for the functions malloc, realloc, and free (see section Memory Allocation Hooks). From then on, all uses of these functions are traced and protocolled into the file. There is now of course a speed penalty for all calls to the traced functions so tracing should not be enabled during normal use.

This function is a GNU extension and generally not available on other systems. The prototype can be found in `mcheck.h'.

Function: void muntrace (void)
The muntrace function can be called after mtrace was used to enable tracing the malloc calls. If no (succesful) call of mtrace was made muntrace does nothing.

Otherwise it deinstalls the handlers for malloc, realloc, and free and then closes the protocol file. No calls are protocolled anymore and the program runs again at full speed.

This function is a GNU extension and generally not available on other systems. The prototype can be found in `mcheck.h'.

Example program excerpts

Even though the tracing functionality does not influence the runtime behaviour of the program it is not a good idea to call mtrace in all programs. Just imagine that you debug a program using mtrace and all other programs used in the debugging session also trace their malloc calls. The output file would be the same for all programs and thus is unusable. Therefore one should call mtrace only if compiled for debugging. A program could therefore start like this:
#include <mcheck.h>

int
main (int argc, char *argv[])
{
#ifdef DEBUGGING
  mtrace ();
#endif
  ...
}
This is all what is needed if you want to trace the calls during the whole runtime of the program. Alternatively you can stop the tracing at any time with a call to muntrace. It is even possible to restart the tracing again with a new call to mtrace. But this can cause unreliable results since there may be calls of the functions which are not called. Please note that not only the application uses the traced functions, also libraries (including the C library itself) use these functions.

This last point is also why it is no good idea to call muntrace before the program terminated. The libraries are informed about the termination of the program only after the program returns from main or calls exit and so cannot free the memory they use before this time.

So the best thing one can do is to call mtrace as the very first function in the program and never call muntrace. So the program traces almost all uses of the malloc functions (except those calls which are executed by constructors of the program or used libraries).

Some more or less clever ideas

You know the situation. The program is prepared for debugging and in all debugging sessions it runs well. But once it is started without debugging the error shows up. A typical example is a memory leak that becomes visible only when we turn off the debugging. If you foresee such situations you can still win. Simply use something equivalent to the following little program:
#include <mcheck.h>
#include <signal.h>

static void
enable (int sig)
{
  mtrace ();
  signal (SIGUSR1, enable);
}

static void
disable (int sig)
{
  muntrace ();
  signal (SIGUSR2, disable);
}

int
main (int argc, char *argv[])
{
  ...

  signal (SIGUSR1, enable);
  signal (SIGUSR2, disable);

  ...
}
I.e., the user can start the memory debugger any time s/he wants if the program was started with MALLOC_TRACE set in the environment. The output will of course not show the allocations which happened before the first signal but if there is a memory leak this will show up nevertheless.

Interpreting the traces

If you take a look at the output it will look similar to this:
= Start
 [0x8048209] - 0x8064cc8
 [0x8048209] - 0x8064ce0
 [0x8048209] - 0x8064cf8
 [0x80481eb] + 0x8064c48 0x14
 [0x80481eb] + 0x8064c60 0x14
 [0x80481eb] + 0x8064c78 0x14
 [0x80481eb] + 0x8064c90 0x14
= End
What this all means is not really important since the trace file is not meant to be read by a human. Therefore no attention is given to readability. Instead there is a program which comes with the GNU C library which interprets the traces and outputs a summary in an user-friendly way. The program is called mtrace (it is in fact a Perl script) and it takes one or two arguments. In any case the name of the file with the trace output must be specified. If an optional argument precedes the name of the trace file this must be the name of the program which generated the trace.
drepper$ mtrace tst-mtrace log
No memory leaks.
In this case the program tst-mtrace was run and it produced a trace file `log'. The message printed by mtrace shows there are no problems with the code, all allocated memory was freed afterwards.

If we call mtrace on the example trace given above we would get a different outout:
drepper$ mtrace errlog
- 0x08064cc8 Free 2 was never alloc'd 0x8048209
- 0x08064ce0 Free 3 was never alloc'd 0x8048209
- 0x08064cf8 Free 4 was never alloc'd 0x8048209

Memory not freed:
-----------------
   Address     Size     Caller
0x08064c48     0x14  at 0x80481eb
0x08064c60     0x14  at 0x80481eb
0x08064c78     0x14  at 0x80481eb
0x08064c90     0x14  at 0x80481eb
We have called mtrace with only one argument and so the script has no chance to find out what is meant with the addresses given in the trace. We can do better:
drepper$ mtrace tst errlog
- 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
- 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
- 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39

Memory not freed:
-----------------
   Address     Size     Caller
0x08064c48     0x14  at /home/drepper/tst.c:33
0x08064c60     0x14  at /home/drepper/tst.c:33
0x08064c78     0x14  at /home/drepper/tst.c:33
0x08064c90     0x14  at /home/drepper/tst.c:33
Suddenly the output makes much more sense and the user can see immediately where the function calls causing the trouble can be found.

Interpreting this output is not complicated. There are at most two different situations being detected. First, free was called for pointers which were never returned by one of the allocation functions. This is usually a very bad problem and what this looks like is shown in the first three lines of the output. Situations like this are quite rare and if they appear they show up very drastically: the program normally crashes.

The other situation which is much harder to detect are memory leaks. As you can see in the output the mtrace function collects all this information and so can say that the program calls an allocation function from line 33 in the source file `/home/drepper/tst-mtrace.c' four times without freeing this memory before the program terminates. Whether this is a real problem remains to be investigated.

Obstacks

An obstack is a pool of memory containing a stack of objects. You can create any number of separate obstacks, and then allocate objects in specified obstacks. Within each obstack, the last object allocated must always be the first one freed, but distinct obstacks are independent of each other.

Aside from this one constraint of order of freeing, obstacks are totally general: an obstack can contain any number of objects of any size. They are implemented with macros, so allocation is usually very fast as long as the objects are usually small. And the only space overhead per object is the padding needed to start each object on a suitable boundary.

Creating Obstacks

The utilities for manipulating obstacks are declared in the header file `obstack.h'.

Data Type: struct obstack
An obstack is represented by a data structure of type struct obstack. This structure has a small fixed size; it records the status of the obstack and how to find the space in which objects are allocated. It does not contain any of the objects themselves. You should not try to access the contents of the structure directly; use only the functions described in this chapter.

You can declare variables of type struct obstack and use them as obstacks, or you can allocate obstacks dynamically like any other kind of object. Dynamic allocation of obstacks allows your program to have a variable number of different stacks. (You can even allocate an obstack structure in another obstack, but this is rarely useful.)

All the functions that work with obstacks require you to specify which obstack to use. You do this with a pointer of type struct obstack *. In the following, we often say "an obstack" when strictly speaking the object at hand is such a pointer.

The objects in the obstack are packed into large blocks called chunks. The struct obstack structure points to a chain of the chunks currently in use.

The obstack library obtains a new chunk whenever you allocate an object that won't fit in the previous chunk. Since the obstack library manages chunks automatically, you don't need to pay much attention to them, but you do need to supply a function which the obstack library should use to get a chunk. Usually you supply a function which uses malloc directly or indirectly. You must also supply a function to free a chunk. These matters are described in the following section.

Preparing for Using Obstacks

Each source file in which you plan to use the obstack functions must include the header file `obstack.h', like this:
#include <obstack.h>
Also, if the source file uses the macro obstack_init, it must declare or define two functions or macros that will be called by the obstack library. One, obstack_chunk_alloc, is used to allocate the chunks of memory into which objects are packed. The other, obstack_chunk_free, is used to return chunks when the objects in them are freed. These macros should appear before any use of obstacks in the source file.

Usually these are defined to use malloc via the intermediary xmalloc (see section Unconstrained Allocation). This is done with the following pair of macro definitions:
#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free
Though the memory you get using obstacks really comes from malloc, using obstacks is faster because malloc is called less often, for larger blocks of memory. See section Obstack Chunks, for full details.

At run time, before the program can use a struct obstack object as an obstack, it must initialize the obstack by calling obstack_init.

Function: int obstack_init (struct obstack *obstack-ptr)
Initialize obstack obstack-ptr for allocation of objects. This function calls the obstack's obstack_chunk_alloc function. If allocation of memory fails, the function pointed to by obstack_alloc_failed_handler is called. The obstack_init function always returns 1 (Compatibility notice: Former versions of obstack returned 0 if allocation failed).

Here are two examples of how to allocate the space for an obstack and initialize it. First, an obstack that is a static variable:
static struct obstack myobstack;
...
obstack_init (&myobstack);
Second, an obstack that is itself dynamically allocated:
struct obstack *myobstack_ptr
  = (struct obstack *) xmalloc (sizeof (struct obstack));

obstack_init (myobstack_ptr);
Variable: obstack_alloc_failed_handler
The value of this variable is a pointer to a function that obstack uses when obstack_chunk_alloc fails to allocate memory. The default action is to print a message and abort. You should supply a function that either calls exit (see section Program Termination) or longjmp (see section Non-Local Exits) and doesn't return.
void my_obstack_alloc_failed (void)
...
obstack_alloc_failed_handler = &my_obstack_alloc_failed;
Allocation in an Obstack

The most direct way to allocate an object in an obstack is with obstack_alloc, which is invoked almost like malloc.

Function: void * obstack_alloc (struct obstack *obstack-ptr, int size)
This allocates an uninitialized block of size bytes in an obstack and returns its address. Here obstack-ptr specifies which obstack to allocate the block in; it is the address of the struct obstack object which represents the obstack. Each obstack function or macro requires you to specify an obstack-ptr as the first argument.

This function calls the obstack's obstack_chunk_alloc function if it needs to allocate a new chunk of memory; it calls obstack_alloc_failed_handler if allocation of memory by obstack_chunk_alloc failed.

For example, here is a function that allocates a copy of a string str in a specific obstack, which is in the variable string_obstack:
struct obstack string_obstack;

char *
copystring (char *string)
{
  size_t len = strlen (string) + 1;
  char *s = (char *) obstack_alloc (&string_obstack, len);
  memcpy (s, string, len);
  return s;
}
To allocate a block with specified contents, use the function obstack_copy, declared like this:

Function: void * obstack_copy (struct obstack *obstack-ptr, void *address, int size)
This allocates a block and initializes it by copying size bytes of data starting at address. It calls obstack_alloc_failed_handler if allocation of memory by obstack_chunk_alloc failed.

Function: void * obstack_copy0 (struct obstack *obstack-ptr, void *address, int size)
Like obstack_copy, but appends an extra byte containing a null character. This extra byte is not counted in the argument size.

The obstack_copy0 function is convenient for copying a sequence of characters into an obstack as a null-terminated string. Here is an example of its use:
char *
obstack_savestring (char *addr, int size)
{
  return obstack_copy0 (&myobstack, addr, size);
}
Contrast this with the previous example of savestring using malloc (see section Basic Memory Allocation).

Freeing Objects in an Obstack

To free an object allocated in an obstack, use the function obstack_free. Since the obstack is a stack of objects, freeing one object automatically frees all other objects allocated more recently in the same obstack.

Function: void obstack_free (struct obstack *obstack-ptr, void *object)
If object is a null pointer, everything allocated in the obstack is freed. Otherwise, object must be the address of an object allocated in the obstack. Then object is freed, along with everything allocated in obstack since object.

Note that if object is a null pointer, the result is an uninitialized obstack. To free all memory in an obstack but leave it valid for further allocation, call obstack_free with the address of the first object allocated on the obstack:
obstack_free (obstack_ptr, first_object_allocated_ptr);
Recall that the objects in an obstack are grouped into chunks. When all the objects in a chunk become free, the obstack library automatically frees the chunk (see section Preparing for Using Obstacks). Then other obstacks, or non-obstack allocation, can reuse the space of the chunk.

Obstack Functions and Macros

The interfaces for using obstacks may be defined either as functions or as macros, depending on the compiler. The obstack facility works with all C compilers, including both ISO C and traditional C, but there are precautions you must take if you plan to use compilers other than GNU C.

If you are using an old-fashioned non-ISO C compiler, all the obstack "functions" are actually defined only as macros. You can call these macros like functions, but you cannot use them in any other way (for example, you cannot take their address).

Calling the macros requires a special precaution: namely, the first operand (the obstack pointer) may not contain any side effects, because it may be computed more than once. For example, if you write this:
obstack_alloc (get_obstack (), 4);
you will find that get_obstack may be called several times. If you use *obstack_list_ptr++ as the obstack pointer argument, you will get very strange results since the incrementation may occur several times.

In ISO C, each function has both a macro definition and a function definition. The function definition is used if you take the address of the function without calling it. An ordinary call uses the macro definition by default, but you can request the function definition instead by writing the function name in parentheses, as shown here:
char *x;
void *(*funcp) ();
/* Use the macro.  */
x = (char *) obstack_alloc (obptr, size);
/* Call the function.  */
x = (char *) (obstack_alloc) (obptr, size);
/* Take the address of the function.  */
funcp = obstack_alloc;
This is the same situation that exists in ISO C for the standard library functions. See section Macro Definitions of Functions.

Warning: When you do use the macros, you must observe the precaution of avoiding side effects in the first operand, even in ISO C.

If you use the GNU C compiler, this precaution is not necessary, because various language extensions in GNU C permit defining the macros so as to compute each argument only once.

Growing Objects

Because memory in obstack chunks is used sequentially, it is possible to build up an object step by step, adding one or more bytes at a time to the end of the object. With this technique, you do not need to know how much data you will put in the object until you come to the end of it. We call this the technique of growing objects. The special functions for adding data to the growing object are described in this section.

You don't need to do anything special when you start to grow an object. Using one of the functions to add data to the object automatically starts it. However, it is necessary to say explicitly when the object is finished. This is done with the function obstack_finish.

The actual address of the object thus built up is not known until the object is finished. Until then, it always remains possible that you will add so much data that the object must be copied into a new chunk.

While the obstack is in use for a growing object, you cannot use it for ordinary allocation of another object. If you try to do so, the space already added to the growing object will become part of the other object.

Function: void obstack_blank (struct obstack *obstack-ptr, int size)
The most basic function for adding to a growing object is obstack_blank, which adds space without initializing it.

Function: void obstack_grow (struct obstack *obstack-ptr, void *data, int size)
To add a block of initialized space, use obstack_grow, which is the growing-object analogue of obstack_copy. It adds size bytes of data to the growing object, copying the contents from data.

Function: void obstack_grow0 (struct obstack *obstack-ptr, void *data, int size)
This is the growing-object analogue of obstack_copy0. It adds size bytes copied from data, followed by an additional null character.

Function: void obstack_1grow (struct obstack *obstack-ptr, char c)
To add one character at a time, use the function obstack_1grow. It adds a single byte containing c to the growing object.

Function: void obstack_ptr_grow (struct obstack *obstack-ptr, void *data)
Adding the value of a pointer one can use the function obstack_ptr_grow. It adds sizeof (void *) bytes containing the value of data.

Function: void obstack_int_grow (struct obstack *obstack-ptr, int data)
A single value of type int can be added by using the obstack_int_grow function. It adds sizeof (int) bytes to the growing object and initializes them with the value of data.

Function: void * obstack_finish (struct obstack *obstack-ptr)
When you are finished growing the object, use the function obstack_finish to close it off and return its final address.

Once you have finished the object, the obstack is available for ordinary allocation or for growing another object.

This function can return a null pointer under the same conditions as obstack_alloc (see section Allocation in an Obstack).

When you build an object by growing it, you will probably need to know afterward how long it became. You need not keep track of this as you grow the object, because you can find out the length from the obstack just before finishing the object with the function obstack_object_size, declared as follows:

Function: int obstack_object_size (struct obstack *obstack-ptr)
This function returns the current size of the growing object, in bytes. Remember to call this function before finishing the object. After it is finished, obstack_object_size will return zero.

If you have started growing an object and wish to cancel it, you should finish it and then free it, like this:
obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
This has no effect if no object was growing.

You can use obstack_blank with a negative size argument to make the current object smaller. Just don't try to shrink it beyond zero length--there's no telling what will happen if you do that.

Extra Fast Growing Objects

The usual functions for growing objects incur overhead for checking whether there is room for the new growth in the current chunk. If you are frequently constructing objects in small steps of growth, this overhead can be significant.

You can reduce the overhead by using special "fast growth" functions that grow the object without checking. In order to have a robust program, you must do the checking yourself. If you do this checking in the simplest way each time you are about to add data to the object, you have not saved anything, because that is what the ordinary growth functions do. But if you can arrange to check less often, or check more efficiently, then you make the program faster.

The function obstack_room returns the amount of room available in the current chunk. It is declared as follows:

Function: int obstack_room (struct obstack *obstack-ptr)
This returns the number of bytes that can be added safely to the current growing object (or to an object about to be started) in obstack obstack using the fast growth functions.

While you know there is room, you can use these fast growth functions for adding data to a growing object:

Function: void obstack_1grow_fast (struct obstack *obstack-ptr, char c)
The function obstack_1grow_fast adds one byte containing the character c to the growing object in obstack obstack-ptr.

Function: void obstack_ptr_grow_fast (struct obstack *obstack-ptr, void *data)
The function obstack_ptr_grow_fast adds sizeof (void *) bytes containing the value of data to the growing object in obstack obstack-ptr.

Function: void obstack_int_grow_fast (struct obstack *obstack-ptr, int data)
The function obstack_int_grow_fast adds sizeof (int) bytes containing the value of data to the growing object in obstack obstack-ptr.

Function: void obstack_blank_fast (struct obstack *obstack-ptr, int size)
The function obstack_blank_fast adds size bytes to the growing object in obstack obstack-ptr without initializing them.

When you check for space using obstack_room and there is not enough room for what you want to add, the fast growth functions are not safe. In this case, simply use the corresponding ordinary growth function instead. Very soon this will copy the object to a new chunk; then there will be lots of room available again.

So, each time you use an ordinary growth function, check afterward for sufficient space using obstack_room. Once the object is copied to a new chunk, there will be plenty of space again, so the program will start using the fast growth functions again.

Here is an example:
void
add_string (struct obstack *obstack, const char *ptr, int len)
{
  while (len > 0)
    {
      int room = obstack_room (obstack);
      if (room == 0)
        {
          /* Not enough room. Add one character slowly,
             which may copy to a new chunk and make room.  */
          obstack_1grow (obstack, *ptr++);
          len--;
        }
      else
        {
          if (room > len)
            room = len;
          /* Add fast as much as we have room for. */
          len -= room;
          while (room-- > 0)
            obstack_1grow_fast (obstack, *ptr++);
        }
    }
}
Status of an Obstack

Here are functions that provide information on the current status of allocation in an obstack. You can use them to learn about an object while still growing it.

Function: void * obstack_base (struct obstack *obstack-ptr)
This function returns the tentative address of the beginning of the currently growing object in obstack-ptr. If you finish the object immediately, it will have that address. If you make it larger first, it may outgrow the current chunk--then its address will change!

If no object is growing, this value says where the next object you allocate will start (once again assuming it fits in the current chunk).

Function: void * obstack_next_free (struct obstack *obstack-ptr)
This function returns the address of the first free byte in the current chunk of obstack obstack-ptr. This is the end of the currently growing object. If no object is growing, obstack_next_free returns the same value as obstack_base.

Function: int obstack_object_size (struct obstack *obstack-ptr)
This function returns the size in bytes of the currently growing object. This is equivalent to
obstack_next_free (obstack-ptr) - obstack_base (obstack-ptr)
Alignment of Data in Obstacks

Each obstack has an alignment boundary; each object allocated in the obstack automatically starts on an address that is a multiple of the specified boundary. By default, this boundary is 4 bytes.

To access an obstack's alignment boundary, use the macro obstack_alignment_mask, whose function prototype looks like this:

Macro: int obstack_alignment_mask (struct obstack *obstack-ptr)
The value is a bit mask; a bit that is 1 indicates that the corresponding bit in the address of an object should be 0. The mask value should be one less than a power of 2; the effect is that all object addresses are multiples of that power of 2. The default value of the mask is 3, so that addresses are multiples of 4. A mask value of 0 means an object can start on any multiple of 1 (that is, no alignment is required).

The expansion of the macro obstack_alignment_mask is an lvalue, so you can alter the mask by assignment. For example, this statement:
obstack_alignment_mask (obstack_ptr) = 0;
has the effect of turning off alignment processing in the specified obstack.

Note that a change in alignment mask does not take effect until after the next time an object is allocated or finished in the obstack. If you are not growing an object, you can make the new alignment mask take effect immediately by calling obstack_finish. This will finish a zero-length object and then do proper alignment for the next object.

Obstack Chunks

Obstacks work by allocating space for themselves in large chunks, and then parceling out space in the chunks to satisfy your requests. Chunks are normally 4096 bytes long unless you specify a different chunk size. The chunk size includes 8 bytes of overhead that are not actually used for storing objects. Regardless of the specified size, longer chunks will be allocated when necessary for long objects.

The obstack library allocates chunks by calling the function obstack_chunk_alloc, which you must define. When a chunk is no longer needed because you have freed all the objects in it, the obstack library frees the chunk by calling obstack_chunk_free, which you must also define.

These two must be defined (as macros) or declared (as functions) in each source file that uses obstack_init (see section Creating Obstacks). Most often they are defined as macros like this:
#define obstack_chunk_alloc malloc
#define obstack_chunk_free free
Note that these are simple macros (no arguments). Macro definitions with arguments will not work! It is necessary that obstack_chunk_alloc or obstack_chunk_free, alone, expand into a function name if it is not itself a function name.

If you allocate chunks with malloc, the chunk size should be a power of 2. The default chunk size, 4096, was chosen because it is long enough to satisfy many typical requests on the obstack yet short enough not to waste too much memory in the portion of the last chunk not yet used.

Macro: int obstack_chunk_size (struct obstack *obstack-ptr)
This returns the chunk size of the given obstack.

Since this macro expands to an lvalue, you can specify a new chunk size by assigning it a new value. Doing so does not affect the chunks already allocated, but will change the size of chunks allocated for that particular obstack in the future. It is unlikely to be useful to make the chunk size smaller, but making it larger might improve efficiency if you are allocating many objects whose size is comparable to the chunk size. Here is how to do so cleanly:
if (obstack_chunk_size (obstack_ptr) < new-chunk-size)
  obstack_chunk_size (obstack_ptr) = new-chunk-size;
Summary of Obstack Functions

Here is a summary of all the functions associated with obstacks. Each takes the address of an obstack (struct obstack *) as its first argument.

void obstack_init (struct obstack *obstack-ptr)
Initialize use of an obstack. See section Creating Obstacks.
void *obstack_alloc (struct obstack *obstack-ptr, int size)
Allocate an object of size uninitialized bytes. See section Allocation in an Obstack.
void *obstack_copy (struct obstack *obstack-ptr, void *address, int size)
Allocate an object of size bytes, with contents copied from address. See section Allocation in an Obstack.
void *obstack_copy0 (struct obstack *obstack-ptr, void *address, int size)
Allocate an object of size+1 bytes, with size of them copied from address, followed by a null character at the end. See section Allocation in an Obstack.
void obstack_free (struct obstack *obstack-ptr, void *object)
Free object (and everything allocated in the specified obstack more recently than object). See section Freeing Objects in an Obstack.
void obstack_blank (struct obstack *obstack-ptr, int size)
Add size uninitialized bytes to a growing object. See section Growing Objects.
void obstack_grow (struct obstack *obstack-ptr, void *address, int size)
Add size bytes, copied from address, to a growing object. See section Growing Objects.
void obstack_grow0 (struct obstack *obstack-ptr, void *address, int size)
Add size bytes, copied from address, to a growing object, and then add another byte containing a null character. See section Growing Objects.
void obstack_1grow (struct obstack *obstack-ptr, char data-char)
Add one byte containing data-char to a growing object. See section Growing Objects.
void *obstack_finish (struct obstack *obstack-ptr)
Finalize the object that is growing and return its permanent address. See section Growing Objects.
int obstack_object_size (struct obstack *obstack-ptr)
Get the current size of the currently growing object. See section Growing Objects.
void obstack_blank_fast (struct obstack *obstack-ptr, int size)
Add size uninitialized bytes to a growing object without checking that there is enough room. See section Extra Fast Growing Objects.
void obstack_1grow_fast (struct obstack *obstack-ptr, char data-char)
Add one byte containing data-char to a growing object without checking that there is enough room. See section Extra Fast Growing Objects.
int obstack_room (struct obstack *obstack-ptr)
Get the amount of room now available for growing the current object. See section Extra Fast Growing Objects.
int obstack_alignment_mask (struct obstack *obstack-ptr)
The mask used for aligning the beginning of an object. This is an lvalue. See section Alignment of Data in Obstacks.
int obstack_chunk_size (struct obstack *obstack-ptr)
The size for allocating chunks. This is an lvalue. See section Obstack Chunks.
void *obstack_base (struct obstack *obstack-ptr)
Tentative starting address of the currently growing object. See section Status of an Obstack.
void *obstack_next_free (struct obstack *obstack-ptr)
Address just after the end of the currently growing object. See section Status of an Obstack.
Automatic Storage with Variable Size

The function alloca supports a kind of half-dynamic allocation in which blocks are allocated dynamically but freed automatically.

Allocating a block with alloca is an explicit action; you can allocate as many blocks as you wish, and compute the size at run time. But all the blocks are freed when you exit the function that alloca was called from, just as if they were automatic variables declared in that function. There is no way to free the space explicitly.

The prototype for alloca is in `stdlib.h'. This function is a BSD extension.

Function: void * alloca (size_t size);
The return value of alloca is the address of a block of size bytes of memory, allocated in the stack frame of the calling function.

Do not use alloca inside the arguments of a function call--you will get unpredictable results, because the stack space for the alloca would appear on the stack in the middle of the space for the function arguments. An example of what to avoid is foo (x, alloca (4), y).

alloca Example

As an example of the use of alloca, here is a function that opens a file name made from concatenating two argument strings, and returns a file descriptor or minus one signifying failure:
int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  stpcpy (stpcpy (name, str1), str2);
  return open (name, flags, mode);
}
Here is how you would get the same results with malloc and free:
int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
  int desc;
  if (name == 0)
    fatal ("virtual memory exceeded");
  stpcpy (stpcpy (name, str1), str2);
  desc = open (name, flags, mode);
  free (name);
  return desc;
}
As you can see, it is simpler with alloca. But alloca has other, more important advantages, and some disadvantages.

Advantages of alloca

Here are the reasons why alloca may be preferable to malloc:

Using alloca wastes very little space and is very fast. (It is open-coded by the GNU C compiler.)
Since alloca does not have separate pools for different sizes of block, space used for any size block can be reused for any other size. alloca does not cause memory fragmentation.
Nonlocal exits done with longjmp (see section Non-Local Exits) automatically free the space allocated with alloca when they exit through the function that called alloca. This is the most important reason to use alloca. To illustrate this, suppose you have a function open_or_report_error which returns a descriptor, like open, if it succeeds, but does not return to its caller if it fails. If the file cannot be opened, it prints an error message and jumps out to the command level of your program using longjmp. Let's change open2 (see section alloca Example) to use this subroutine:
int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  stpcpy (stpcpy (name, str1), str2);
  return open_or_report_error (name, flags, mode);
}
Because of the way alloca works, the memory it allocates is freed even when an error occurs, with no special effort required. By contrast, the previous definition of open2 (which uses malloc and free) would develop a memory leak if it were changed in this way. Even if you are willing to make more changes to fix it, there is no easy way to do so.

Disadvantages of alloca

These are the disadvantages of alloca in comparison with malloc:

If you try to allocate more memory than the machine can provide, you don't get a clean error message. Instead you get a fatal signal like the one you would get from an infinite recursion; probably a segmentation violation (see section Program Error Signals).
Some non-GNU systems fail to support alloca, so it is less portable. However, a slower emulation of alloca written in C is available for use on systems with this deficiency.

GNU C Variable-Size Arrays

In GNU C, you can replace most uses of alloca with an array of variable size. Here is how open2 would look then:
int open2 (char *str1, char *str2, int flags, int mode)
{
  char name[strlen (str1) + strlen (str2) + 1];
  stpcpy (stpcpy (name, str1), str2);
  return open (name, flags, mode);
}
But alloca is not always equivalent to a variable-sized array, for several reasons:

A variable size array's space is freed at the end of the scope of the name of the array. The space allocated with alloca remains until the end of the function.
It is possible to use alloca within a loop, allocating an additional block on each iteration. This is impossible with variable-sized arrays.

Note: If you mix use of alloca and variable-sized arrays within one function, exiting a scope in which a variable-sized array was declared frees all blocks allocated with alloca during the execution of that scope.

Resizing the Data Segment

The symbols in this section are declared in `unistd.h'.

You will not normally use the functions in this section, because the functions described in section Allocating Storage For Program Data are easier to use. Those are interfaces to a GNU C Library memory allocator that uses the functions below itself. The functions below are simple interfaces to system calls.

Function: int brk (void *addr)

brk sets the high end of the calling process' data segment to addr.

The address of the end of a segment is defined to be the address of the last byte in the segment plus 1.

The function has no effect if addr is lower than the low end of the data segment. (This is considered success, by the way).

The function fails if it would cause the data segment to overlap another segment or exceed the process' data storage limit (see section Limiting Resource Usage).

The function is named for a common historical case where data storage and the stack are in the same segment. Data storage allocation grows upward from the bottom of the segment while the stack grows downward toward it from the top of the segment and the curtain between them is called the break.

The return value is zero on success. On failure, the return value is -1 and errno is set accordingly. The following errno values are specific to this function:

ENOMEM
The request would cause the data segment to overlap another segment or exceed the process' data storage limit.

Function: int sbrk (ptrdiff_t delta)
This function is the same as brk except that you specify the new end of the data segment as an offset delta from the current end and on success the return value is the address of the resulting end of the data segment instead of zero.

This means you can use `sbrk(0)' to find out what the current end of the data segment is.

Locking Pages

You can tell the system to associate a particular virtual memory page with a real page frame and keep it that way -- i.e. cause the page to be paged in if it isn't already and mark it so it will never be paged out and consequently will never cause a page fault. This is called locking a page.

The functions in this chapter lock and unlock the calling process' pages.

Why Lock Pages

Because page faults cause paged out pages to be paged in transparently, a process rarely needs to be concerned about locking pages. However, there are two reasons people sometimes are:

Speed. A page fault is transparent only insofar as the process is not sensitive to how long it takes to do a simple memory access. Time-critical processes, especially realtime processes, may not be able to wait or may not be able to tolerate variance in execution speed. A process that needs to lock pages for this reason probably also needs priority among other processes for use of the CPU. See section Process CPU Priority And Scheduling. In some cases, the programmer knows better than the system's demand paging allocator which pages should remain in real memory to optimize system performance. In this case, locking pages can help.
Privacy. If you keep secrets in virtual memory and that virtual memory gets paged out, that increases the chance that the secrets will get out. If a password gets written out to disk swap space, for example, it might still be there long after virtual and real memory have been wiped clean.

Be aware that when you lock a page, that's one fewer page frame that can be used to back other virtual memory (by the same or other processes), which can mean more page faults, which means the system runs more slowly. In fact, if you lock enough memory, some programs may not be able to run at all for lack of real memory.

Locked Memory Details

A memory lock is associated with a virtual page, not a real frame. The paging rule is: If a frame backs at least one locked page, don't page it out.

Memory locks do not stack. I.e. you can't lock a particular page twice so that it has to be unlocked twice before it is truly unlocked. It is either locked or it isn't.

A memory lock persists until the process that owns the memory explicitly unlocks it. (But process termination and exec cause the virtual memory to cease to exist, which you might say means it isn't locked any more).

Memory locks are not inherited by child processes. (But note that on a modern Unix system, immediately after a fork, the parent's and the child's virtual address space are backed by the same real page frames, so the child enjoys the parent's locks). See section Creating a Process.

Because of its ability to impact other processes, only the superuser can lock a page. Any process can unlock its own page.

The system sets limits on the amount of memory a process can have locked and the amount of real memory it can have dedicated to it. See section Limiting Resource Usage.

In Linux, locked pages aren't as locked as you might think. Two virtual pages that are not shared memory can nonetheless be backed by the same real frame. The kernel does this in the name of efficiency when it knows both virtual pages contain identical data, and does it even if one or both of the virtual pages are locked.

But when a process modifies one of those pages, the kernel must get it a separate frame and fill it with the page's data. This is known as a copy-on-write page fault. It takes a small amount of time and in a pathological case, getting that frame may require I/O.

To make sure this doesn't happen to your program, don't just lock the pages. Write to them as well, unless you know you won't write to them ever. And to make sure you have pre-allocated frames for your stack, enter a scope that declares a C automatic variable larger than the maximum stack size you will need, set it to something, then return from its scope.

Functions To Lock And Unlock Pages

The symbols in this section are declared in `sys/mman.h'. These functions are defined by POSIX.1b, but their availability depends on your kernel. If your kernel doesn't allow these functions, they exist but always fail. They are available with a Linux kernel.

Portability Note: POSIX.1b requires that when the mlock and munlock functions are available, the file `unistd.h' define the macro _POSIX_MEMLOCK_RANGE and the file limits.h define the macro PAGESIZE to be the size of a memory page in bytes. It requires that when the mlockall and munlockall functions are available, the `unistd.h' file define the macro _POSIX_MEMLOCK. The GNU C library conforms to this requirement.

Function: int mlock (const void *addr, size_t len)

mlock locks a range of the calling process' virtual pages.

The range of memory starts at address addr and is len bytes long. Actually, since you must lock whole pages, it is the range of pages that include any part of the specified range.

When the function returns successfully, each of those pages is backed by (connected to) a real frame (is resident) and is marked to stay that way. This means the function may cause page-ins and have to wait for them.

When the function fails, it does not affect the lock status of any pages.

The return value is zero if the function succeeds. Otherwise, it is -1 and errno is set accordingly. errno values specific to this function are:

ENOMEM

At least some of the specified address range does not exist in the calling process' virtual address space.
The locking would cause the process to exceed its locked page limit.

EPERM
The calling process is not superuser.
EINVAL
len is not positive.
ENOSYS
The kernel does not provide mlock capability.
You can lock all a process' memory with mlockall. You unlock memory with munlock or munlockall.

To avoid all page faults in a C program, you have to use mlockall, because some of the memory a program uses is hidden from the C code, e.g. the stack and automatic variables, and you wouldn't know what address to tell mlock.

Function: int munlock (const void *addr, size_t len)

mlock unlocks a range of the calling process' virtual pages.

munlock is the inverse of mlock and functions completely analogously to mlock, except that there is no EPERM failure.

Function: int mlockall (int flags)

mlockall locks all the pages in a process' virtual memory address space, and/or any that are added to it in the future. This includes the pages of the code, data and stack segment, as well as shared libraries, user space kernel data, shared memory, and memory mapped files.

flags is a string of single bit flags represented by the following macros. They tell mlockall which of its functions you want. All other bits must be zero.

MCL_CURRENT
Lock all pages which currently exist in the calling process' virtual address space.
MCL_FUTURE
Set a mode such that any pages added to the process' virtual address space in the future will be locked from birth. This mode does not affect future address spaces owned by the same process so exec, which replaces a process' address space, wipes out MCL_FUTURE. See section Executing a File.
When the function returns successfully, and you specified MCL_CURRENT, all of the process' pages are backed by (connected to) real frames (they are resident) and are marked to stay that way. This means the function may cause page-ins and have to wait for them.

When the process is in MCL_FUTURE mode because it successfully executed this function and specified MCL_CURRENT, any system call by the process that requires space be added to its virtual address space fails with errno = ENOMEM if locking the additional space would cause the process to exceed its locked page limit. In the case that the address space addition that can't be accomodated is stack expansion, the stack expansion fails and the kernel sends a SIGSEGV signal to the process.

When the function fails, it does not affect the lock status of any pages or the future locking mode.

The return value is zero if the function succeeds. Otherwise, it is -1 and errno is set accordingly. errno values specific to this function are:

ENOMEM

At least some of the specified address range does not exist in the calling process' virtual address space.
The locking would cause the process to exceed its locked page limit.

EPERM
The calling process is not superuser.
EINVAL
Undefined bits in flags are not zero.
ENOSYS
The kernel does not provide mlockall capability.
You can lock just specific pages with mlock. You unlock pages with munlockall and munlock.

Function: int munlockall (void)

munlockall unlocks every page in the calling process' virtual address space and turn off MCL_FUTURE future locking mode.

The return value is zero if the function succeeds. Otherwise, it is -1 and errno is set accordingly. The only way this function can fail is for generic reasons that all functions and system calls can fail, so there are no specific errno values.

Character Handling

Programs that work with characters and strings often need to classify a character--is it alphabetic, is it a digit, is it whitespace, and so on--and perform case conversion operations on characters. The functions in the header file `ctype.h' are provided for this purpose.

Since the choice of locale and character set can alter the classifications of particular character codes, all of these functions are affected by the current locale. (More precisely, they are affected by the locale currently selected for character classification--the LC_CTYPE category; see section Categories of Activities that Locales Affect.)

The ISO C standard specifies two different sets of functions. The one set works on char type characters, the other one on wchar_t wide characters (see section Introduction to Extended Characters).

Classification of Characters

This section explains the library functions for classifying characters. For example, isalpha is the function to test for an alphabetic character. It takes one argument, the character to test, and returns a nonzero integer if the character is alphabetic, and zero otherwise. You would use it like this:
if (isalpha (c))
  printf ("The character `%c' is alphabetic.\n", c);
Each of the functions in this section tests for membership in a particular class of characters; each has a name starting with `is'. Each of them takes one argument, which is a character to test, and returns an int which is treated as a boolean value. The character argument is passed as an int, and it may be the constant value EOF instead of a real character.

The attributes of any given character can vary between locales. See section Locales and Internationalization, for more information on locales.

These functions are declared in the header file `ctype.h'.

Function: int islower (int c)
Returns true if c is a lower-case letter. The letter need not be from the Latin alphabet, any alphabet representable is valid.

Function: int isupper (int c)
Returns true if c is an upper-case letter. The letter need not be from the Latin alphabet, any alphabet representable is valid.

Function: int isalpha (int c)
Returns true if c is an alphabetic character (a letter). If islower or isupper is true of a character, then isalpha is also true.

In some locales, there may be additional characters for which isalpha is true--letters which are neither upper case nor lower case. But in the standard "C" locale, there are no such additional characters.

Function: int isdigit (int c)
Returns true if c is a decimal digit (`0' through `9').

Function: int isalnum (int c)
Returns true if c is an alphanumeric character (a letter or number); in other words, if either isalpha or isdigit is true of a character, then isalnum is also true.

Function: int isxdigit (int c)
Returns true if c is a hexadecimal digit. Hexadecimal digits include the normal decimal digits `0' through `9' and the letters `A' through `F' and `a' through `f'.

Function: int ispunct (int c)
Returns true if c is a punctuation character. This means any printing character that is not alphanumeric or a space character.

Function: int isspace (int c)
Returns true if c is a whitespace character. In the standard "C" locale, isspace returns true for only the standard whitespace characters:

' '
space
'\f'
formfeed
'\n'
newline
'\r'
carriage return
'\t'
horizontal tab
'\v'
vertical tab

Function: int isblank (int c)
Returns true if c is a blank character; that is, a space or a tab. This function is a GNU extension.

Function: int isgraph (int c)
Returns true if c is a graphic character; that is, a character that has a glyph associated with it. The whitespace characters are not considered graphic.

Function: int isprint (int c)
Returns true if c is a printing character. Printing characters include all the graphic characters, plus the space (` ') character.

Function: int iscntrl (int c)
Returns true if c is a control character (that is, a character that is not a printing character).

Function: int isascii (int c)
Returns true if c is a 7-bit unsigned char value that fits into the US/UK ASCII character set. This function is a BSD extension and is also an SVID extension.

Case Conversion

This section explains the library functions for performing conversions such as case mappings on characters. For example, toupper converts any character to upper case if possible. If the character can't be converted, toupper returns it unchanged.

These functions take one argument of type int, which is the character to convert, and return the converted character as an int. If the conversion is not applicable to the argument given, the argument is returned unchanged.

Compatibility Note: In pre-ISO C dialects, instead of returning the argument unchanged, these functions may fail when the argument is not suitable for the conversion. Thus for portability, you may need to write islower(c) ? toupper(c) : c rather than just toupper(c).

These functions are declared in the header file `ctype.h'.

Function: int tolower (int c)
If c is an upper-case letter, tolower returns the corresponding lower-case letter. If c is not an upper-case letter, c is returned unchanged.

Function: int toupper (int c)
If c is a lower-case letter, toupper returns the corresponding upper-case letter. Otherwise c is returned unchanged.

Function: int toascii (int c)
This function converts c to a 7-bit unsigned char value that fits into the US/UK ASCII character set, by clearing the high-order bits. This function is a BSD extension and is also an SVID extension.

Function: int _tolower (int c)
This is identical to tolower, and is provided for compatibility with the SVID. See section SVID (The System V Interface Description).

Function: int _toupper (int c)
This is identical to toupper, and is provided for compatibility with the SVID.

Character class determination for wide characters

Amendment 1 to ISO C90 defines functions to classify wide characters. Although the original ISO C90 standard already defined the type wchar_t, no functions operating on them were defined.

The general design of the classification functions for wide characters is more general. It allows extensions to the set of available classifications, beyond those which are always available. The POSIX standard specifies how extensions can be made, and this is already implemented in the GNU C library implementation of the localedef program.

The character class functions are normally implemented with bitsets, with a bitset per character. For a given character, the appropriate bitset is read from a table and a test is performed as to whether a certain bit is set. Which bit is tested for is determined by the class.

For the wide character classification functions this is made visible. There is a type classification type defined, a function to retrieve this value for a given class, and a function to test whether a given character is in this class, using the classification value. On top of this the normal character classification functions as used for char objects can be defined.

Data type: wctype_t
The wctype_t can hold a value which represents a character class. The only defined way to generate such a value is by using the wctype function.

This type is defined in `wctype.h'.

Function: wctype_t wctype (const char *property)
The wctype returns a value representing a class of wide characters which is identified by the string property. Beside some standard properties each locale can define its own ones. In case no property with the given name is known for the current locale selected for the LC_CTYPE category, the function returns zero.

The properties known in every locale are:

@multitable @columnfractions .25 .25 .25 .25
"alnum" @tab "alpha" @tab "cntrl" @tab "digit"
"graph" @tab "lower" @tab "print" @tab "punct"
"space" @tab "upper" @tab "xdigit" This function is declared in `wctype.h'. To test the membership of a character to one of the non-standard classes the ISO C standard defines a completely new function.
Function: int iswctype (wint_t wc, wctype_t desc)
This function returns a nonzero value if wc is in the character class specified by desc. desc must previously be returned by a successful call to wctype. This function is declared in `wctype.h'. To make it easier to use the commonly-used classification functions, they are defined in the C library. There is no need to use wctype if the property string is one of the known character classes. In some situations it is desirable to construct the property strings, and then it is important that wctype can also handle the standard classes.
Function: int iswalnum (wint_t wc)
This function returns a nonzero value if wc is an alphanumeric character (a letter or number); in other words, if either iswalpha or iswdigit is true of a character, then iswalnum is also true. This function can be implemented using
iswctype (wc, wctype ("alnum"))
It is declared in `wctype.h'.
Function: int iswalpha (wint_t wc)
Returns true if wc is an alphabetic character (a letter). If iswlower or iswupper is true of a character, then iswalpha is also true. In some locales, there may be additional characters for which iswalpha is true--letters which are neither upper case nor lower case. But in the standard "C" locale, there are no such additional characters. This function can be implemented using
iswctype (wc, wctype ("alpha"))
It is declared in `wctype.h'.
Function: int iswcntrl (wint_t wc)
Returns true if wc is a control character (that is, a character that is not a printing character). This function can be implemented using
iswctype (wc, wctype ("cntrl"))
It is declared in `wctype.h'.
Function: int iswdigit (wint_t wc)
Returns true if wc is a digit (e.g., `0' through `9'). Please note that this function does not only return a nonzero value for decimal digits, but for all kinds of digits. A consequence is that code like the following will not work unconditionally for wide characters:
n = 0;
while (iswdigit (*wc))
  {
    n *= 10;
    n += *wc++ - L'0';
  }
This function can be implemented using
iswctype (wc, wctype ("digit"))
It is declared in `wctype.h'.
Function: int iswgraph (wint_t wc)
Returns true if wc is a graphic character; that is, a character that has a glyph associated with it. The whitespace characters are not considered graphic. This function can be implemented using
iswctype (wc, wctype ("graph"))
It is declared in `wctype.h'.
Function: int iswlower (wint_t wc)
Returns true if wc is a lower-case letter. The letter need not be from the Latin alphabet, any alphabet representable is valid. This function can be implemented using
iswctype (wc, wctype ("lower"))
It is declared in `wctype.h'.
Function: int iswprint (wint_t wc)
Returns true if wc is a printing character. Printing characters include all the graphic characters, plus the space (` ') character. This function can be implemented using
iswctype (wc, wctype ("print"))
It is declared in `wctype.h'.
Function: int iswpunct (wint_t wc)
Returns true if wc is a punctuation character. This means any printing character that is not alphanumeric or a space character. This function can be implemented using
iswctype (wc, wctype ("punct"))
It is declared in `wctype.h'.
Function: int iswspace (wint_t wc)
Returns true if wc is a whitespace character. In the standard "C" locale, iswspace returns true for only the standard whitespace characters:
L' '
space
L'\f'
formfeed
L'\n'
newline
L'\r'
carriage return
L'\t'
horizontal tab
L'\v'
vertical tab This function can be implemented using
iswctype (wc, wctype ("space"))
It is declared in `wctype.h'.
Function: int iswupper (wint_t wc)
Returns true if wc is an upper-case letter. The letter need not be from the Latin alphabet, any alphabet representable is valid. This function can be implemented using
iswctype (wc, wctype ("upper"))
It is declared in `wctype.h'.
Function: int iswxdigit (wint_t wc)
Returns true if wc is a hexadecimal digit. Hexadecimal digits include the normal decimal digits `0' through `9' and the letters `A' through `F' and `a' through `f'. This function can be implemented using
iswctype (wc, wctype ("xdigit"))
It is declared in `wctype.h'. The GNU C library also provides a function which is not defined in the ISO C standard but which is available as a version for single byte characters as well.
Function: int iswblank (wint_t wc)
Returns true if wc is a blank character; that is, a space or a tab. This function is a GNU extension. It is declared in `wchar.h'.
Notes on using the wide character classes

The first note is probably not astonishing but still occasionally a cause of problems. The iswXXX functions can be implemented using macros and in fact, the GNU C library does this. They are still available as real functions but when the `wctype.h' header is included the macros will be used. This is the same as the char type versions of these functions.

The second note covers something new. It can be best illustrated by a (real-world) example. The first piece of code is an excerpt from the original code. It is truncated a bit but the intention should be clear.
int
is_in_class (int c, const char *class)
{
  if (strcmp (class, "alnum") == 0)
    return isalnum (c);
  if (strcmp (class, "alpha") == 0)
    return isalpha (c);
  if (strcmp (class, "cntrl") == 0)
    return iscntrl (c);
  ...
  return 0;
}
Now, with the wctype and iswctype you can avoid the if cascades, but rewriting the code as follows is wrong:
int
is_in_class (int c, const char *class)
{
  wctype_t desc = wctype (class);
  return desc ? iswctype ((wint_t) c, desc) : 0;
}
The problem is that it is not guaranteed that the wide character representation of a single-byte character can be found using casting. In fact, usually this fails miserably. The correct solution to this problem is to write the code as follows:
int
is_in_class (int c, const char *class)
{
  wctype_t desc = wctype (class);
  return desc ? iswctype (btowc (c), desc) : 0;
}
See section Converting Single Characters, for more information on btowc. Note that this change probably does not improve the performance of the program a lot since the wctype function still has to make the string comparisons. It gets really interesting if the is_in_class function is called more than once for the same class name. In this case the variable desc could be computed once and reused for all the calls. Therefore the above form of the function is probably not the final one.

Mapping of wide characters.

The classification functions are also generalized by the ISO C standard. Instead of just allowing the two standard mappings, a locale can contain others. Again, the localedef program already supports generating such locale data files.

Data Type: wctrans_t
This data type is defined as a scalar type which can hold a value representing the locale-dependent character mapping. There is no way to construct such a value apar from using the return value of the wctrans function.

This type is defined in `wctype.h'.

Function: wctrans_t wctrans (const char *property)
The wctrans function has to be used to find out whether a named mapping is defined in the current locale selected for the LC_CTYPE category. If the returned value is non-zero, you can use it afterwards in calls to towctrans. If the return value is zero no such mapping is known in the current locale.

Beside locale-specific mappings there are two mappings which are guaranteed to be available in every locale:

@multitable @columnfractions .5 .5
"tolower" @tab "toupper" These functions are declared in `wctype.h'.
Function: wint_t towctrans (wint_t wc, wctrans_t desc)
towctrans maps the input character wc according to the rules of the mapping for which desc is a descriptor, and returns the value it finds. desc must be obtained by a successful call to wctrans. This function is declared in `wctype.h'. For the generally available mappings, the ISO C standard defines convenient shortcuts so that it is not necessary to call wctrans for them.
Function: wint_t towlower (wint_t wc)
If wc is an upper-case letter, towlower returns the corresponding lower-case letter. If wc is not an upper-case letter, wc is returned unchanged. towlower can be implemented using
towctrans (wc, wctrans ("tolower"))
This function is declared in `wctype.h'.
Function: wint_t towupper (wint_t wc)
If wc is a lower-case letter, towupper returns the corresponding upper-case letter. Otherwise wc is returned unchanged. towupper can be implemented using
towctrans (wc, wctrans ("toupper"))
This function is declared in `wctype.h'. The same warnings given in the last section for the use of the wide character classification functions apply here. It is not possible to simply cast a char type value to a wint_t and use it as an argument to towctrans calls.
String and Array Utilities

Operations on strings (or arrays of characters) are an important part of many programs. The GNU C library provides an extensive set of string utility functions, including functions for copying, concatenating, comparing, and searching strings. Many of these functions can also operate on arbitrary regions of storage; for example, the memcpy function can be used to copy the contents of any kind of array.

It's fairly common for beginning C programmers to "reinvent the wheel" by duplicating this functionality in their own code, but it pays to become familiar with the library functions and to make use of them, since this offers benefits in maintenance, efficiency, and portability.

For instance, you could easily compare one string to another in two lines of C code, but if you use the built-in strcmp function, you're less likely to make a mistake. And, since these library functions are typically highly optimized, your program may run faster too.

Representation of Strings

This section is a quick summary of string concepts for beginning C programmers. It describes how character strings are represented in C and some common pitfalls. If you are already familiar with this material, you can skip this section.

A string is an array of char objects. But string-valued variables are usually declared to be pointers of type char *. Such variables do not include space for the text of a string; that has to be stored somewhere else--in an array variable, a string constant, or dynamically allocated memory (see section Allocating Storage For Program Data). It's up to you to store the address of the chosen memory space into the pointer variable. Alternatively you can store a null pointer in the pointer variable. The null pointer does not point anywhere, so attempting to reference the string it points to gets an error.

"string" normally refers to multibyte character strings as opposed to wide character strings. Wide character strings are arrays of type wchar_t and as for multibyte character strings usually pointers of type wchar_t * are used.

By convention, a null character, '\0', marks the end of a multibyte character string and the null wide character, L'\0', marks the end of a wide character string. For example, in testing to see whether the char * variable p points to a null character marking the end of a string, you can write !*p or *p == '\0'.

A null character is quite different conceptually from a null pointer, although both are represented by the integer 0.

String literals appear in C program source as strings of characters between double-quote characters (`"') where the initial double-quote character is immediately preceded by a capital `L' (ell) character (as in L"foo"). In ISO C, string literals can also be formed by string concatenation: "a" "b" is the same as "ab". For wide character strings one can either use L"a" L"b" or L"a" "b". Modification of string literals is not allowed by the GNU C compiler, because literals are placed in read-only storage.

Character arrays that are declared const cannot be modified either. It's generally good style to declare non-modifiable string pointers to be of type const char *, since this often allows the C compiler to detect accidental modifications as well as providing some amount of documentation about what your program intends to do with the string.

The amount of memory allocated for the character array may extend past the null character that normally marks the end of the string. In this document, the term allocated size is always used to refer to the total amount of memory allocated for the string, while the term length refers to the number of characters up to (but not including) the terminating null character.

A notorious source of program bugs is trying to put more characters in a string than fit in its allocated size. When writing code that extends strings or moves characters into a pre-allocated array, you should be very careful to keep track of the length of the text and make explicit checks for overflowing the array. Many of the library functions do not do this for you! Remember also that you need to allocate an extra byte to hold the null character that marks the end of the string.

Originally strings were sequences of bytes where each byte represents a single character. This is still true today if the strings are encoded using a single-byte character encoding. Things are different if the strings are encoded using a multibyte encoding (for more information on encodings see section Introduction to Extended Characters). There is no difference in the programming interface for these two kind of strings; the programmer has to be aware of this and interpret the byte sequences accordingly.

But since there is no separate interface taking care of these differences the byte-based string functions are sometimes hard to use. Since the count parameters of these functions specify bytes a call to strncpy could cut a multibyte character in the middle and put an incomplete (and therefore unusable) byte sequence in the target buffer.

To avoid these problems later versions of the ISO C standard introduce a second set of functions which are operating on wide characters (see section Introduction to Extended Characters). These functions don't have the problems the single-byte versions have since every wide character is a legal, interpretable value. This does not mean that cutting wide character strings at arbitrary points is without problems. It normally is for alphabet-based languages (except for non-normalized text) but languages based on syllables still have the problem that more than one wide character is necessary to complete a logical unit. This is a higher level problem which the C library functions are not designed to solve. But it is at least good that no invalid byte sequences can be created. Also, the higher level functions can also much easier operate on wide character than on multibyte characters so that a general advise is to use wide characters internally whenever text is more than simply copied.

The remaining of this chapter will discuss the functions for handling wide character strings in parallel with the discussion of the multibyte character strings since there is almost always an exact equivalent available.

String and Array Conventions

This chapter describes both functions that work on arbitrary arrays or blocks of memory, and functions that are specific to null-terminated arrays of characters and wide characters.

Functions that operate on arbitrary blocks of memory have names beginning with `mem' and `wmem' (such as memcpy and wmemcpy) and invariably take an argument which specifies the size (in bytes and wide characters respectively) of the block of memory to operate on. The array arguments and return values for these functions have type void * or wchar_t. As a matter of style, the elements of the arrays used with the `mem' functions are referred to as "bytes". You can pass any kind of pointer to these functions, and the sizeof operator is useful in computing the value for the size argument. Parameters to the `wmem' functions must be of type wchar_t *. These functions are not really usable with anything but arrays of this type.

In contrast, functions that operate specifically on strings and wide character strings have names beginning with `str' and `wcs' respectively (such as strcpy and wcscpy) and look for a null character to terminate the string instead of requiring an explicit size argument to be passed. (Some of these functions accept a specified maximum length, but they also check for premature termination with a null character.) The array arguments and return values for these functions have type char * and wchar_t * respectively, and the array elements are referred to as "characters" and "wide characters".

In many cases, there are both `mem' and `str'/`wcs' versions of a function. The one that is more appropriate to use depends on the exact situation. When your program is manipulating arbitrary arrays or blocks of storage, then you should always use the `mem' functions. On the other hand, when you are manipulating null-terminated strings it is usually more convenient to use the `str'/`wcs' functions, unless you already know the length of the string in advance. The `wmem' functions should be used for wide character arrays with known size.

Some of the memory and string functions take single characters as arguments. Since a value of type char is automatically promoted into an value of type int when used as a parameter, the functions are declared with int as the type of the parameter in question. In case of the wide character function the situation is similarly: the parameter type for a single wide character is wint_t and not wchar_t. This would for many implementations not be necessary since the wchar_t is large enough to not be automatically promoted, but since the ISO C standard does not require such a choice of types the wint_t type is used.

String Length

You can get the length of a string using the strlen function. This function is declared in the header file `string.h'.

Function: size_t strlen (const char *s)
The strlen function returns the length of the null-terminated string s in bytes. (In other words, it returns the offset of the terminating null character within the array.)

For example,
strlen ("hello, world")
    => 12
When applied to a character array, the strlen function returns the length of the string stored there, not its allocated size. You can get the allocated size of the character array that holds a string using the sizeof operator:
char string[32] = "hello, world";
sizeof (string)
    => 32
strlen (string)
    => 12
But beware, this will not work unless string is the character array itself, not a pointer to it. For example:
char string[32] = "hello, world";
char *ptr = string;
sizeof (string)
    => 32
sizeof (ptr)
    => 4  /* (on a machine with 4 byte pointers) */
This is an easy mistake to make when you are working with functions that take string arguments; those arguments are always pointers, not arrays.

It must also be noted that for multibyte encoded strings the return value does not have to correspond to the number of characters in the string. To get this value the string can be converted to wide characters and wcslen can be used or something like the following code can be used:
/* The input is in string.
   The length is expected in n.  */
{
  mbstate_t t;
  char *scopy = string;
  /* In initial state.  */
  memset (&t, '\0', sizeof (t));
  /* Determine number of characters.  */
  n = mbsrtowcs (NULL, &scopy, strlen (scopy), &t);
}
This is cumbersome to do so if the number of characters (as opposed to bytes) is needed often it is better to work with wide characters.

The wide character equivalent is declared in `wchar.h'.

Function: size_t wcslen (const wchar_t *ws)
The wcslen function is the wide character equivalent to strlen. The return value is the number of wide characters in the wide character string pointed to by ws (this is also the offset of the terminating null wide character of ws).

Since there are no multi wide character sequences making up one character the return value is not only the offset in the array, it is also the number of wide characters.

This function was introduced in Amendment 1 to ISO C90.

Function: size_t strnlen (const char *s, size_t maxlen)
The strnlen function returns the length of the string s in bytes if this length is smaller than maxlen bytes. Otherwise it returns maxlen. Therefore this function is equivalent to (strlen (s) < n ? strlen (s) : maxlen) but it is more efficient and works even if the string s is not null-terminated.
char string[32] = "hello, world";
strnlen (string, 32)
    => 12
strnlen (string, 5)
    => 5
This function is a GNU extension and is declared in `string.h'.

Function: size_t wcsnlen (const wchar_t *ws, size_t maxlen)
wcsnlen is the wide character equivalent to strnlen. The maxlen parameter specifies the maximum number of wide characters.

This function is a GNU extension and is declared in `wchar.h'.

Copying and Concatenation

You can use the functions described in this section to copy the contents of strings and arrays, or to append the contents of one string to another. The `str' and `mem' functions are declared in the header file `string.h' while the `wstr' and `wmem' functions are declared in the file `wchar.h'.

A helpful way to remember the ordering of the arguments to the functions in this section is that it corresponds to an assignment expression, with the destination array specified to the left of the source array. All of these functions return the address of the destination array.

Most of these functions do not work properly if the source and destination arrays overlap. For example, if the beginning of the destination array overlaps the end of the source array, the original contents of that part of the source array may get overwritten before it is copied. Even worse, in the case of the string functions, the null character marking the end of the string may be lost, and the copy function might get stuck in a loop trashing all the memory allocated to your program.

All functions that have problems copying between overlapping arrays are explicitly identified in this manual. In addition to functions in this section, there are a few others like sprintf (see section Formatted Output Functions) and scanf (see section Formatted Input Functions).

Function: void * memcpy (void *restrict to, const void *restrict from, size_t size)
The memcpy function copies size bytes from the object beginning at from into the object beginning at to. The behavior of this function is undefined if the two arrays to and from overlap; use memmove instead if overlapping is possible.

The value returned by memcpy is the value of to.

Here is an example of how you might use memcpy to copy the contents of an array:
struct foo *oldarray, *newarray;
int arraysize;
...
memcpy (new, old, arraysize * sizeof (struct foo));
Function: wchar_t * wmemcpy (wchar_t *restrict wto, const wchar_t *restruct wfrom, size_t size)
The wmemcpy function copies size wide characters from the object beginning at wfrom into the object beginning at wto. The behavior of this function is undefined if the two arrays wto and wfrom overlap; use wmemmove instead if overlapping is possible.

The following is a possible implementation of wmemcpy but there are more optimizations possible.
wchar_t *
wmemcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
         size_t size)
{
  return (wchar_t *) memcpy (wto, wfrom, size * sizeof (wchar_t));
}
The value returned by wmemcpy is the value of wto.

This function was introduced in Amendment 1 to ISO C90.

Function: void * mempcpy (void *restrict to, const void *restrict from, size_t size)
The mempcpy function is nearly identical to the memcpy function. It copies size bytes from the object beginning at from into the object pointed to by to. But instead of returning the value of to it returns a pointer to the byte following the last written byte in the object beginning at to. I.e., the value is ((void *) ((char *) to + size)).

This function is useful in situations where a number of objects shall be copied to consecutive memory positions.
void *
combine (void *o1, size_t s1, void *o2, size_t s2)
{
  void *result = malloc (s1 + s2);
  if (result != NULL)
    mempcpy (mempcpy (result, o1, s1), o2, s2);
  return result;
}
This function is a GNU extension.

Function: wchar_t * wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size)
The wmempcpy function is nearly identical to the wmemcpy function. It copies size wide characters from the object beginning at wfrom into the object pointed to by wto. But instead of returning the value of wto it returns a pointer to the wide character following the last written wide character in the object beginning at wto. I.e., the value is wto + size.

This function is useful in situations where a number of objects shall be copied to consecutive memory positions.

The following is a possible implementation of wmemcpy but there are more optimizations possible.
wchar_t *
wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
          size_t size)
{
  return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));
}
This function is a GNU extension.

Function: void * memmove (void *to, const void *from, size_t size)
memmove copies the size bytes at from into the size bytes at to, even if those two blocks of space overlap. In the case of overlap, memmove is careful to copy the original values of the bytes in the block at from, including those bytes which also belong to the block at to.

The value returned by memmove is the value of to.

Function: wchar_t * wmemmove (wchar *wto, const wchar_t *wfrom, size_t size)
wmemmove copies the size wide characters at wfrom into the size wide characters at wto, even if those two blocks of space overlap. In the case of overlap, memmove is careful to copy the original values of the wide characters in the block at wfrom, including those wide characters which also belong to the block at wto.

The following is a possible implementation of wmemcpy but there are more optimizations possible.
wchar_t *
wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
          size_t size)
{
  return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));
}
The value returned by wmemmove is the value of wto.

This function is a GNU extension.

Function: void * memccpy (void *restrict to, const void *restrict from, int c, size_t size)
This function copies no more than size bytes from from to to, stopping if a byte matching c is found. The return value is a pointer into to one byte past where c was copied, or a null pointer if no byte matching c appeared in the first size bytes of from.

Function: void * memset (void *block, int c, size_t size)
This function copies the value of c (converted to an unsigned char) into each of the first size bytes of the object beginning at block. It returns the value of block.

Function: wchar_t * wmemset (wchar_t *block, wchar_t wc, size_t size)
This function copies the value of wc into each of the first size wide characters of the object beginning at block. It returns the value of block.

Function: char * strcpy (char *restrict to, const char *restrict from)
This copies characters from the string from (up to and including the terminating null character) into the string to. Like memcpy, this function has undefined results if the strings overlap. The return value is the value of to.

Function: wchar_t * wcscpy (wchar_t *restrict wto, const wchar_t *restrict wfrom)
This copies wide characters from the string wfrom (up to and including the terminating null wide character) into the string wto. Like wmemcpy, this function has undefined results if the strings overlap. The return value is the value of wto.

Function: char * strncpy (char *restrict to, const char *restrict from, size_t size)
This function is similar to strcpy but always copies exactly size characters into to.

If the length of from is more than size, then strncpy copies just the first size characters. Note that in this case there is no null terminator written into to.

If the length of from is less than size, then strncpy copies all of from, followed by enough null characters to add up to size characters in all. This behavior is rarely useful, but it is specified by the ISO C standard.

The behavior of strncpy is undefined if the strings overlap.

Using strncpy as opposed to strcpy is a way to avoid bugs relating to writing past the end of the allocated space for to. However, it can also make your program much slower in one common case: copying a string which is probably small into a potentially large buffer. In this case, size may be large, and when it is, strncpy will waste a considerable amount of time copying null characters.

Function: wchar_t * wcsncpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size)
This function is similar to wcscpy but always copies exactly size wide characters into wto.

If the length of wfrom is more than size, then wcsncpy copies just the first size wide characters. Note that in this case there is no null terminator written into wto.

If the length of wfrom is less than size, then wcsncpy copies all of wfrom, followed by enough null wide characters to add up to size wide characters in all. This behavior is rarely useful, but it is specified by the ISO C standard.

The behavior of wcsncpy is undefined if the strings overlap.

Using wcsncpy as opposed to wcscpy is a way to avoid bugs relating to writing past the end of the allocated space for wto. However, it can also make your program much slower in one common case: copying a string which is probably small into a potentially large buffer. In this case, size may be large, and when it is, wcsncpy will waste a considerable amount of time copying null wide characters.

Function: char * strdup (const char *s)
This function copies the null-terminated string s into a newly allocated string. The string is allocated using malloc; see section Unconstrained Allocation. If malloc cannot allocate space for the new string, strdup returns a null pointer. Otherwise it returns a pointer to the new string.

Function: wchar_t * wcsdup (const wchar_t *ws)
This function copies the null-terminated wide character string ws into a newly allocated string. The string is allocated using malloc; see section Unconstrained Allocation. If malloc cannot allocate space for the new string, wcsdup returns a null pointer. Otherwise it returns a pointer to the new wide character string.

This function is a GNU extension.

Function: char * strndup (const char *s, size_t size)
This function is similar to strdup but always copies at most size characters into the newly allocated string.

If the length of s is more than size, then strndup copies just the first size characters and adds a closing null terminator. Otherwise all characters are copied and the string is terminated.

This function is different to strncpy in that it always terminates the destination string.

strndup is a GNU extension.

Function: char * stpcpy (char *restrict to, const char *restrict from)
This function is like strcpy, except that it returns a pointer to the end of the string to (that is, the address of the terminating null character to + strlen (from)) rather than the beginning.

For example, this program uses stpcpy to concatenate `foo' and `bar' to produce `foobar', which it then prints.
#include <string.h>
#include <stdio.h>

int
main (void)
{
  char buffer[10];
  char *to = buffer;
  to = stpcpy (to, "foo");
  to = stpcpy (to, "bar");
  puts (buffer);
  return 0;
}
This function is not part of the ISO or POSIX standards, and is not customary on Unix systems, but we did not invent it either. Perhaps it comes from MS-DOG.

Its behavior is undefined if the strings overlap. The function is declared in `string.h'.

Function: wchar_t * wcpcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom)
This function is like wcscpy, except that it returns a pointer to the end of the string wto (that is, the address of the terminating null character wto + strlen (wfrom)) rather than the beginning.

This function is not part of ISO or POSIX but was found useful while developing the GNU C Library itself.

The behavior of wcpcpy is undefined if the strings overlap.

wcpcpy is a GNU extension and is declared in `wchar.h'.

Function: char * stpncpy (char *restrict to, const char *restrict from, size_t size)
This function is similar to stpcpy but copies always exactly size characters into to.

If the length of from is more then size, then stpncpy copies just the first size characters and returns a pointer to the character directly following the one which was copied last. Note that in this case there is no null terminator written into to.

If the length of from is less than size, then stpncpy copies all of from, followed by enough null characters to add up to size characters in all. This behaviour is rarely useful, but it is implemented to be useful in contexts where this behaviour of the strncpy is used. stpncpy returns a pointer to the first written null character.

This function is not part of ISO or POSIX but was found useful while developing the GNU C Library itself.

Its behaviour is undefined if the strings overlap. The function is declared in `string.h'.

Function: wchar_t * wcpncpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size)
This function is similar to wcpcpy but copies always exactly wsize characters into wto.

If the length of wfrom is more then size, then wcpncpy copies just the first size wide characters and returns a pointer to the wide character directly following the one which was copied last. Note that in this case there is no null terminator written into wto.

If the length of wfrom is less than size, then wcpncpy copies all of wfrom, followed by enough null characters to add up to size characters in all. This behaviour is rarely useful, but it is implemented to be useful in contexts where this behaviour of the wcsncpy is used. wcpncpy returns a pointer to the first written null character.

This function is not part of ISO or POSIX but was found useful while developing the GNU C Library itself.

Its behaviour is undefined if the strings overlap.

wcpncpy is a GNU extension and is declared in `wchar.h'.

Macro: char * strdupa (const char *s)
This macro is similar to strdup but allocates the new string using alloca instead of malloc (see section Automatic Storage with Variable Size). This means of course the returned string has the same limitations as any block of memory allocated using alloca.

For obvious reasons strdupa is implemented only as a macro; you cannot get the address of this function. Despite this limitation it is a useful function. The following code shows a situation where using malloc would be a lot more expensive.
#include <paths.h>
#include <string.h>
#include <stdio.h>

const char path[] = _PATH_STDPATH;

int
main (void)
{
  char *wr_path = strdupa (path);
  char *cp = strtok (wr_path, ":");

  while (cp != NULL)
    {
      puts (cp);
      cp = strtok (NULL, ":");
    }
  return 0;
}
Please note that calling strtok using path directly is invalid. It is also not allowed to call strdupa in the argument list of strtok since strdupa uses alloca (see section Automatic Storage with Variable Size) can interfere with the parameter passing.

This function is only available if GNU CC is used.

Macro: char * strndupa (const char *s, size_t size)
This function is similar to strndup but like strdupa it allocates the new string using alloca see section Automatic Storage with Variable Size. The same advantages and limitations of strdupa are valid for strndupa, too.

This function is implemented only as a macro, just like strdupa. Just as strdupa this macro also must not be used inside the parameter list in a function call.

strndupa is only available if GNU CC is used.

Function: char * strcat (char *restrict to, const char *restrict from)
The strcat function is similar to strcpy, except that the characters from from are concatenated or appended to the end of to, instead of overwriting it. That is, the first character from from overwrites the null character marking the end of to.

An equivalent definition for strcat would be:
char *
strcat (char *restrict to, const char *restrict from)
{
  strcpy (to + strlen (to), from);
  return to;
}
This function has undefined results if the strings overlap.

Function: wchar_t * wcscat (wchar_t *restrict wto, const wchar_t *restrict wfrom)
The wcscat function is similar to wcscpy, except that the characters from wfrom are concatenated or appended to the end of wto, instead of overwriting it. That is, the first character from wfrom overwrites the null character marking the end of wto.

An equivalent definition for wcscat would be:
wchar_t *
wcscat (wchar_t *wto, const wchar_t *wfrom)
{
  wcscpy (wto + wcslen (wto), wfrom);
  return wto;
}
This function has undefined results if the strings overlap.

Programmers using the strcat or wcscat function (or the following strncat or wcsncar functions for that matter) can easily be recognized as lazy and reckless. In almost all situations the lengths of the participating strings are known (it better should be since how can one otherwise ensure the allocated size of the buffer is sufficient?) Or at least, one could know them if one keeps track of the results of the various function calls. But then it is very inefficient to use strcat/wcscat. A lot of time is wasted finding the end of the destination string so that the actual copying can start. This is a common example:
/* This function concatenates arbitrarily many strings.  The last
   parameter must be NULL.  */
char *
concat (const char *str, ...)
{
  va_list ap, ap2;
  size_t total = 1;
  const char *s;
  char *result;

  va_start (ap, str);
  /* Actually va_copy, but this is the name more gcc versions
     understand.  */
  __va_copy (ap2, ap);

  /* Determine how much space we need.  */
  for (s = str; s != NULL; s = va_arg (ap, const char *))
    total += strlen (s);

  va_end (ap);

  result = (char *) malloc (total);
  if (result != NULL)
    {
      result[0] = '\0';

      /* Copy the strings.  */
      for (s = str; s != NULL; s = va_arg (ap2, const char *))
        strcat (result, s);
    }

  va_end (ap2);

  return result;
}
This looks quite simple, especially the second loop where the strings are actually copied. But these innocent lines hide a major performance penalty. Just imagine that ten strings of 100 bytes each have to be concatenated. For the second string we search the already stored 100 bytes for the end of the string so that we can append the next string. For all strings in total the comparisons necessary to find the end of the intermediate results sums up to 5500! If we combine the copying with the search for the allocation we can write this function more efficient:
char *
concat (const char *str, ...)
{
  va_list ap;
  size_t allocated = 100;
  char *result = (char *) malloc (allocated);
  char *wp;

  if (allocated != NULL)
    {
      char *newp;

      va_start (ap, atr);

      wp = result;
      for (s = str; s != NULL; s = va_arg (ap, const char *))
        {
          size_t len = strlen (s);

          /* Resize the allocated memory if necessary.  */
          if (wp + len + 1 > result + allocated)
            {
              allocated = (allocated + len) * 2;
              newp = (char *) realloc (result, allocated);
              if (newp == NULL)
                {
                  free (result);
                  return NULL;
                }
              wp = newp + (wp - result);
              result = newp;
            }

          wp = mempcpy (wp, s, len);
        }

      /* Terminate the result string.  */
      *wp++ = '\0';

      /* Resize memory to the optimal size.  */
      newp = realloc (result, wp - result);
      if (newp != NULL)
        result = newp;

      va_end (ap);
    }

  return result;
}
With a bit more knowledge about the input strings one could fine-tune the memory allocation. The difference we are pointing to here is that we don't use strcat anymore. We always keep track of the length of the current intermediate result so we can safe us the search for the end of the string and use mempcpy. Please note that we also don't use stpcpy which might seem more natural since we handle with strings. But this is not necessary since we already know the length of the string and therefore can use the faster memory copying function. The example would work for wide characters the same way.

Whenever a programmer feels the need to use strcat she or he should think twice and look through the program whether the code cannot be rewritten to take advantage of already calculated results. Again: it is almost always unnecessary to use strcat.

Function: char * strncat (char *restrict to, const char *restrict from, size_t size)
This function is like strcat except that not more than size characters from from are appended to the end of to. A single null character is also always appended to to, so the total allocated size of to must be at least size + 1 bytes longer than its initial length.

The strncat function could be implemented like this:
char *
strncat (char *to, const char *from, size_t size)
{
  to[strlen (to) + size] = '\0';
  strncpy (to + strlen (to), from, size);
  return to;
}
The behavior of strncat is undefined if the strings overlap.

Function: wchar_t * wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size)
This function is like wcscat except that not more than size characters from from are appended to the end of to. A single null character is also always appended to to, so the total allocated size of to must be at least size + 1 bytes longer than its initial length.

The wcsncat function could be implemented like this:
wchar_t *
wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom,
         size_t size)
{
  wto[wcslen (to) + size] = L'\0';
  wcsncpy (wto + wcslen (wto), wfrom, size);
  return wto;
}
The behavior of wcsncat is undefined if the strings overlap.

Here is an example showing the use of strncpy and strncat (the wide character version is equivalent). Notice how, in the call to strncat, the size parameter is computed to avoid overflowing the character array buffer.
#include <string.h>
#include <stdio.h>

#define SIZE 10

static char buffer[SIZE];

main ()
{
  strncpy (buffer, "hello", SIZE);
  puts (buffer);
  strncat (buffer, ", world", SIZE - strlen (buffer) - 1);
  puts (buffer);
}
The output produced by this program looks like:
hello
hello, wo
Function: void bcopy (const void *from, void *to, size_t size)
This is a partially obsolete alternative for memmove, derived from BSD. Note that it is not quite equivalent to memmove, because the arguments are not in the same order and there is no return value.

Function: void bzero (void *block, size_t size)
This is a partially obsolete alternative for memset, derived from BSD. Note that it is not as general as memset, because the only value it can store is zero.

String/Array Comparison

You can use the functions in this section to perform comparisons on the contents of strings and arrays. As well as checking for equality, these functions can also be used as the ordering functions for sorting operations. See section Searching and Sorting, for an example of this.

Unlike most comparison operations in C, the string comparison functions return a nonzero value if the strings are not equivalent rather than if they are. The sign of the value indicates the relative ordering of the first characters in the strings that are not equivalent: a negative value indicates that the first string is "less" than the second, while a positive value indicates that the first string is "greater".

The most common use of these functions is to check only for equality. This is canonically done with an expression like `! strcmp (s1, s2)'.

All of these functions are declared in the header file `string.h'.

Function: int memcmp (const void *a1, const void *a2, size_t size)
The function memcmp compares the size bytes of memory beginning at a1 against the size bytes of memory beginning at a2. The value returned has the same sign as the difference between the first differing pair of bytes (interpreted as unsigned char objects, then promoted to int).

If the contents of the two blocks are equal, memcmp returns 0.

Function: int wmemcmp (const wchar_t *a1, const wchar_t *a2, size_t size)
The function wmemcmp compares the size wide characters beginning at a1 against the size wide characters beginning at a2. The value returned is smaller than or larger than zero depending on whether the first differing wide character is a1 is smaller or larger than the corresponding character in a2.

If the contents of the two blocks are equal, wmemcmp returns 0.

On arbitrary arrays, the memcmp function is mostly useful for testing equality. It usually isn't meaningful to do byte-wise ordering comparisons on arrays of things other than bytes. For example, a byte-wise comparison on the bytes that make up floating-point numbers isn't likely to tell you anything about the relationship between the values of the floating-point numbers.

wmemcmp is really only useful to compare arrays of type wchar_t since the function looks at sizeof (wchar_t) bytes at a time and this number of bytes is system dependent.

You should also be careful about using memcmp to compare objects that can contain "holes", such as the padding inserted into structure objects to enforce alignment requirements, extra space at the end of unions, and extra characters at the ends of strings whose length is less than their allocated size. The contents of these "holes" are indeterminate and may cause strange behavior when performing byte-wise comparisons. For more predictable results, perform an explicit component-wise comparison.

For example, given a structure type definition like:
struct foo
  {
    unsigned char tag;
    union
      {
        double f;
        long i;
        char *p;
      } value;
  };
you are better off writing a specialized comparison function to compare struct foo objects instead of comparing them with memcmp.

Function: int strcmp (const char *s1, const char *s2)
The strcmp function compares the string s1 against s2, returning a value that has the same sign as the difference between the first differing pair of characters (interpreted as unsigned char objects, then promoted to int).

If the two strings are equal, strcmp returns 0.

A consequence of the ordering used by strcmp is that if s1 is an initial substring of s2, then s1 is considered to be "less than" s2.

strcmp does not take sorting conventions of the language the strings are written in into account. To get that one has to use strcoll.

Function: int wcscmp (const wchar_t *ws1, const wchar_t *ws2)

The wcscmp function compares the wide character string ws1 against ws2. The value returned is smaller than or larger than zero depending on whether the first differing wide character is ws1 is smaller or larger than the corresponding character in ws2.

If the two strings are equal, wcscmp returns 0.

A consequence of the ordering used by wcscmp is that if ws1 is an initial substring of ws2, then ws1 is considered to be "less than" ws2.

wcscmp does not take sorting conventions of the language the strings are written in into account. To get that one has to use wcscoll.

Function: int strcasecmp (const char *s1, const char *s2)
This function is like strcmp, except that differences in case are ignored. How uppercase and lowercase characters are related is determined by the currently selected locale. In the standard "C" locale the characters @"A and @"a do not match but in a locale which regards these characters as parts of the alphabet they do match.

strcasecmp is derived from BSD.

Function: int wcscasecmp (const wchar_t *ws1, const wchar_T *ws2)
This function is like wcscmp, except that differences in case are ignored. How uppercase and lowercase characters are related is determined by the currently selected locale. In the standard "C" locale the characters @"A and @"a do not match but in a locale which regards these characters as parts of the alphabet they do match.

wcscasecmp is a GNU extension.

Function: int strncmp (const char *s1, const char *s2, size_t size)
This function is the similar to strcmp, except that no more than size wide characters are compared. In other words, if the two strings are the same in their first size wide characters, the return value is zero.

Function: int wcsncmp (const wchar_t *ws1, const wchar_t *ws2, size_t size)
This function is the similar to wcscmp, except that no more than size wide characters are compared. In other words, if the two strings are the same in their first size wide characters, the return value is zero.

Function: int strncasecmp (const char *s1, const char *s2, size_t n)
This function is like strncmp, except that differences in case are ignored. Like strcasecmp, it is locale dependent how uppercase and lowercase characters are related.

strncasecmp is a GNU extension.

Function: int wcsncasecmp (const wchar_t *ws1, const wchar_t *s2, size_t n)
This function is like wcsncmp, except that differences in case are ignored. Like wcscasecmp, it is locale dependent how uppercase and lowercase characters are related.

wcsncasecmp is a GNU extension.

Here are some examples showing the use of strcmp and strncmp (equivalent examples can be constructed for the wide character functions). These examples assume the use of the ASCII character set. (If some other character set--say, EBCDIC--is used instead, then the glyphs are associated with different numeric codes, and the return values and ordering may differ.)
strcmp ("hello", "hello")
    => 0    /* These two strings are the same. */
strcmp ("hello", "Hello")
    => 32   /* Comparisons are case-sensitive. */
strcmp ("hello", "world")
    => -15  /* The character 'h' comes before 'w'. */
strcmp ("hello", "hello, world")
    => -44  /* Comparing a null character against a comma. */
strncmp ("hello", "hello, world", 5)
    => 0    /* The initial 5 characters are the same. */
strncmp ("hello, world", "hello, stupid world!!!", 5)
    => 0    /* The initial 5 characters are the same. */
Function: int strverscmp (const char *s1, const char *s2)
The strverscmp function compares the string s1 against s2, considering them as holding indices/version numbers. Return value follows the same conventions as found in the strverscmp function. In fact, if s1 and s2 contain no digits, strverscmp behaves like strcmp.

Basically, we compare strings normally (character by character), until we find a digit in each string - then we enter a special comparison mode, where each sequence of digits is taken as a whole. If we reach the end of these two parts without noticing a difference, we return to the standard comparison mode. There are two types of numeric parts: "integral" and "fractional" (those begin with a '0'). The types of the numeric parts affect the way we sort them:

integral/integral: we compare values as you would expect.
fractional/integral: the fractional part is less than the integral one. Again, no surprise.
fractional/fractional: the things become a bit more complex. If the common prefix contains only leading zeroes, the longest part is less than the other one; else the comparison behaves normally.
strverscmp ("no digit", "no digit")
    => 0    /* same behaviour as strcmp. */
strverscmp ("item#99", "item#100")
    => <0   /* same prefix, but 99 < 100. */
strverscmp ("alpha1", "alpha001")
    => >0   /* fractional part inferior to integral one. */
strverscmp ("part1_f012", "part1_f01")
    => >0   /* two fractional parts. */
strverscmp ("foo.009", "foo.0")
    => <0   /* idem, but with leading zeroes only. */
This function is especially useful when dealing with filename sorting, because filenames frequently hold indices/version numbers.

strverscmp is a GNU extension.

Function: int bcmp (const void *a1, const void *a2, size_t size)
This is an obsolete alias for memcmp, derived from BSD.

Collation Functions

In some locales, the conventions for lexicographic ordering differ from the strict numeric ordering of character codes. For example, in Spanish most glyphs with diacritical marks such as accents are not considered distinct letters for the purposes of collation. On the other hand, the two-character sequence `ll' is treated as a single letter that is collated immediately after `l'.

You can use the functions strcoll and strxfrm (declared in the headers file `string.h') and wcscoll and wcsxfrm (declared in the headers file `wchar') to compare strings using a collation ordering appropriate for the current locale. The locale used by these functions in particular can be specified by setting the locale for the LC_COLLATE category; see section Locales and Internationalization.

In the standard C locale, the collation sequence for strcoll is the same as that for strcmp. Similarly, wcscoll and wcscmp are the same in this situation.

Effectively, the way these functions work is by applying a mapping to transform the characters in a string to a byte sequence that represents the string's position in the collating sequence of the current locale. Comparing two such byte sequences in a simple fashion is equivalent to comparing the strings with the locale's collating sequence.

The functions strcoll and wcscoll perform this translation implicitly, in order to do one comparison. By contrast, strxfrm and wcsxfrm perform the mapping explicitly. If you are making multiple comparisons using the same string or set of strings, it is likely to be more efficient to use strxfrm or wcsxfrm to transform all the strings just once, and subsequently compare the transformed strings with strcmp or wcscmp.

Function: int strcoll (const char *s1, const char *s2)
The strcoll function is similar to strcmp but uses the collating sequence of the current locale for collation (the LC_COLLATE locale).

Function: int wcscoll (const wchar_t *ws1, const wchar_t *ws2)
The wcscoll function is similar to wcscmp but uses the collating sequence of the current locale for collation (the LC_COLLATE locale).

Here is an example of sorting an array of strings, using strcoll to compare them. The actual sort algorithm is not written here; it comes from qsort (see section Array Sort Function). The job of the code shown here is to say how to compare the strings while sorting them. (Later on in this section, we will show a way to do this more efficiently using strxfrm.)
/* This is the comparison function used with qsort. */

int
compare_elements (char **p1, char **p2)
{
  return strcoll (*p1, *p2);
}

/* This is the entry point--the function to sort
   strings using the locale's collating sequence. */

void
sort_strings (char **array, int nstrings)
{
  /* Sort temp_array by comparing the strings. */
  qsort (array, nstrings,
         sizeof (char *), compare_elements);
}
Function: size_t strxfrm (char *restrict to, const char *restrict from, size_t size)
The function strxfrm transforms the string from using the collation transformation determined by the locale currently selected for collation, and stores the transformed string in the array to. Up to size characters (including a terminating null character) are stored.

The behavior is undefined if the strings to and from overlap; see section Copying and Concatenation.

The return value is the length of the entire transformed string. This value is not affected by the value of size, but if it is greater or equal than size, it means that the transformed string did not entirely fit in the array to. In this case, only as much of the string as actually fits was stored. To get the whole transformed string, call strxfrm again with a bigger output array.

The transformed string may be longer than the original string, and it may also be shorter.

If size is zero, no characters are stored in to. In this case, strxfrm simply returns the number of characters that would be the length of the transformed string. This is useful for determining what size the allocated array should be. It does not matter what to is if size is zero; to may even be a null pointer.

Function: size_t wcsxfrm (wchar_t *restrict wto, const wchar_t *wfrom, size_t size)
The function wcsxfrm transforms wide character string wfrom using the collation transformation determined by the locale currently selected for collation, and stores the transformed string in the array wto. Up to size wide characters (including a terminating null character) are stored.

The behavior is undefined if the strings wto and wfrom overlap; see section Copying and Concatenation.

The return value is the length of the entire transformed wide character string. This value is not affected by the value of size, but if it is greater or equal than size, it means that the transformed wide character string did not entirely fit in the array wto. In this case, only as much of the wide character string as actually fits was stored. To get the whole transformed wide character string, call wcsxfrm again with a bigger output array.

The transformed wide character string may be longer than the original wide character string, and it may also be shorter.

If size is zero, no characters are stored in to. In this case, wcsxfrm simply returns the number of wide characters that would be the length of the transformed wide character string. This is useful for determining what size the allocated array should be (remember to multiply with sizeof (wchar_t)). It does not matter what wto is if size is zero; wto may even be a null pointer.

Here is an example of how you can use strxfrm when you plan to do many comparisons. It does the same thing as the previous example, but much faster, because it has to transform each string only once, no matter how many times it is compared with other strings. Even the time needed to allocate and free storage is much less than the time we save, when there are many strings.
struct sorter { char *input; char *transformed; };

/* This is the comparison function used with qsort
   to sort an array of struct sorter. */

int
compare_elements (struct sorter *p1, struct sorter *p2)
{
  return strcmp (p1->transformed, p2->transformed);
}

/* This is the entry point--the function to sort
   strings using the locale's collating sequence. */

void
sort_strings_fast (char **array, int nstrings)
{
  struct sorter temp_array[nstrings];
  int i;

  /* Set up temp_array.  Each element contains
     one input string and its transformed string. */
  for (i = 0; i < nstrings; i++)
    {
      size_t length = strlen (array[i]) * 2;
      char *transformed;
      size_t transformed_length;

      temp_array[i].input = array[i];

      /* First try a buffer perhaps big enough.  */
      transformed = (char *) xmalloc (length);

      /* Transform array[i].  */
      transformed_length = strxfrm (transformed, array[i], length);

      /* If the buffer was not large enough, resize it
         and try again.  */
      if (transformed_length >= length)
        {
          /* Allocate the needed space. +1 for terminating
             NUL character.  */
          transformed = (char *) xrealloc (transformed,
                                           transformed_length + 1);

          /* The return value is not interesting because we know
             how long the transformed string is.  */
          (void) strxfrm (transformed, array[i],
                          transformed_length + 1);
        }

      temp_array[i].transformed = transformed;
    }

  /* Sort temp_array by comparing transformed strings. */
  qsort (temp_array, sizeof (struct sorter),
         nstrings, compare_elements);

  /* Put the elements back in the permanent array
     in their sorted order. */
  for (i = 0; i < nstrings; i++)
    array[i] = temp_array[i].input;

  /* Free the strings we allocated. */
  for (i = 0; i < nstrings; i++)
    free (temp_array[i].transformed);
}
The interesting part of this code for the wide character version would look like this:
void
sort_strings_fast (wchar_t **array, int nstrings)
{
  ...
      /* Transform array[i].  */
      transformed_length = wcsxfrm (transformed, array[i], length);

      /* If the buffer was not large enough, resize it
         and try again.  */
      if (transformed_length >= length)
        {
          /* Allocate the needed space. +1 for terminating
             NUL character.  */
          transformed = (wchar_t *) xrealloc (transformed,
                                              (transformed_length + 1)
                                              * sizeof (wchar_t));

          /* The return value is not interesting because we know
             how long the transformed string is.  */
          (void) wcsxfrm (transformed, array[i],
                          transformed_length + 1);
        }
  ...
Note the additional multiplication with sizeof (wchar_t) in the realloc call.

Compatibility Note: The string collation functions are a new feature of ISO C90. Older C dialects have no equivalent feature. The wide character versions were introduced in Amendment 1 to ISO C90.

Search Functions

This section describes library functions which perform various kinds of searching operations on strings and arrays. These functions are declared in the header file `string.h'.

Function: void * memchr (const void *block, int c, size_t size)
This function finds the first occurrence of the byte c (converted to an unsigned char) in the initial size bytes of the object beginning at block. The return value is a pointer to the located byte, or a null pointer if no match was found.

Function: wchar_t * wmemchr (const wchar_t *block, wchar_t wc, size_t size)
This function finds the first occurrence of the wide character wc in the initial size wide characters of the object beginning at block. The return value is a pointer to the located wide character, or a null pointer if no match was found.

Function: void * rawmemchr (const void *block, int c)
Often the memchr function is used with the knowledge that the byte c is available in the memory block specified by the parameters. But this means that the size parameter is not really needed and that the tests performed with it at runtime (to check whether the end of the block is reached) are not needed.

The rawmemchr function exists for just this situation which is surprisingly frequent. The interface is similar to memchr except that the size parameter is missing. The function will look beyond the end of the block pointed to by block in case the programmer made an error in assuming that the byte c is present in the block. In this case the result is unspecified. Otherwise the return value is a pointer to the located byte.

This function is of special interest when looking for the end of a string. Since all strings are terminated by a null byte a call like
   rawmemchr (str, '\0')
will never go beyond the end of the string.

This function is a GNU extension.

Function: void * memrchr (const void *block, int c, size_t size)
The function memrchr is like memchr, except that it searches backwards from the end of the block defined by block and size (instead of forwards from the front).

Function: char * strchr (const char *string, int c)
The strchr function finds the first occurrence of the character c (converted to a char) in the null-terminated string beginning at string. The return value is a pointer to the located character, or a null pointer if no match was found.

For example,
strchr ("hello, world", 'l')
    => "llo, world"
strchr ("hello, world", '?')
    => NULL
The terminating null character is considered to be part of the string, so you can use this function get a pointer to the end of a string by specifying a null character as the value of the c argument. It would be better (but less portable) to use strchrnul in this case, though.

Function: wchar_t * wcschr (const wchar_t *wstring, int wc)
The wcschr function finds the first occurrence of the wide character wc in the null-terminated wide character string beginning at wstring. The return value is a pointer to the located wide character, or a null pointer if no match was found.

The terminating null character is considered to be part of the wide character string, so you can use this function get a pointer to the end of a wide character string by specifying a null wude character as the value of the wc argument. It would be better (but less portable) to use wcschrnul in this case, though.

Function: char * strchrnul (const char *string, int c)
strchrnul is the same as strchr except that if it does not find the character, it returns a pointer to string's terminating null character rather than a null pointer.

This function is a GNU extension.

Function: wchar_t * wcschrnul (const wchar_t *wstring, wchar_t wc)
wcschrnul is the same as wcschr except that if it does not find the wide character, it returns a pointer to wide character string's terminating null wide character rather than a null pointer.

This function is a GNU extension.

One useful, but unusual, use of the strchr function is when one wants to have a pointer pointing to the NUL byte terminating a string. This is often written in this way:
  s += strlen (s);
This is almost optimal but the addition operation duplicated a bit of the work already done in the strlen function. A better solution is this:
  s = strchr (s, '\0');
There is no restriction on the second parameter of strchr so it could very well also be the NUL character. Those readers thinking very hard about this might now point out that the strchr function is more expensive than the strlen function since we have two abort criteria. This is right. But in the GNU C library the implementation of strchr is optimized in a special way so that strchr actually is faster.

Function: char * strrchr (const char *string, int c)
The function strrchr is like strchr, except that it searches backwards from the end of the string string (instead of forwards from the front).

For example,
strrchr ("hello, world", 'l')
    => "ld"
Function: wchar_t * wcsrchr (const wchar_t *wstring, wchar_t c)
The function wcsrchr is like wcschr, except that it searches backwards from the end of the string wstring (instead of forwards from the front).

Function: char * strstr (const char *haystack, const char *needle)
This is like strchr, except that it searches haystack for a substring needle rather than just a single character. It returns a pointer into the string haystack that is the first character of the substring, or a null pointer if no match was found. If needle is an empty string, the function returns haystack.

For example,
strstr ("hello, world", "l")
    => "llo, world"
strstr ("hello, world", "wo")
    => "world"
Function: wchar_t * wcsstr (const wchar_t *haystack, const wchar_t *needle)
This is like wcschr, except that it searches haystack for a substring needle rather than just a single wide character. It returns a pointer into the string haystack that is the first wide character of the substring, or a null pointer if no match was found. If needle is an empty string, the function returns haystack.

Function: wchar_t * wcswcs (const wchar_t *haystack, const wchar_t *needle)
wcsstr is an depricated alias for wcsstr. This is the name originally used in the X/Open Portability Guide before the Amendment 1 to ISO C90 was published.

Function: char * strcasestr (const char *haystack, const char *needle)
This is like strstr, except that it ignores case in searching for the substring. Like strcasecmp, it is locale dependent how uppercase and lowercase characters are related.

For example,
strstr ("hello, world", "L")
    => "llo, world"
strstr ("hello, World", "wo")
    => "World"
Function: void * memmem (const void *haystack, size_t haystack-len,
const void *needle, size_t needle-len)
This is like strstr, but needle and haystack are byte arrays rather than null-terminated strings. needle-len is the length of needle and haystack-len is the length of haystack.

This function is a GNU extension.

Function: size_t strspn (const char *string, const char *skipset)
The strspn ("string span") function returns the length of the initial substring of string that consists entirely of characters that are members of the set specified by the string skipset. The order of the characters in skipset is not important.

For example,
strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
    => 5
Note that "character" is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale-dependent.

Function: size_t wcsspn (const wchar_t *wstring, const wchar_t *skipset)
The wcsspn ("wide character string span") function returns the length of the initial substring of wstring that consists entirely of wide characters that are members of the set specified by the string skipset. The order of the wide characters in skipset is not important.

Function: size_t strcspn (const char *string, const char *stopset)
The strcspn ("string complement span") function returns the length of the initial substring of string that consists entirely of characters that are not members of the set specified by the string stopset. (In other words, it returns the offset of the first character in string that is a member of the set stopset.)

For example,
strcspn ("hello, world", " \t\n,.;!?")
    => 5
Note that "character" is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale-dependent.

Function: size_t wcscspn (const wchar_t *wstring, const wchar_t *stopset)
The wcscspn ("wide character string complement span") function returns the length of the initial substring of wstring that consists entirely of wide characters that are not members of the set specified by the string stopset. (In other words, it returns the offset of the first character in string that is a member of the set stopset.)

Function: char * strpbrk (const char *string, const char *stopset)
The strpbrk ("string pointer break") function is related to strcspn, except that it returns a pointer to the first character in string that is a member of the set stopset instead of the length of the initial substring. It returns a null pointer if no such character from stopset is found.

For example,
strpbrk ("hello, world", " \t\n,.;!?")
    => ", world"
Note that "character" is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale-dependent.

Function: wchar_t * wcspbrk (const wchar_t *wstring, const wchar_t *stopset)
The wcspbrk ("wide character string pointer break") function is related to wcscspn, except that it returns a pointer to the first wide character in wstring that is a member of the set stopset instead of the length of the initial substring. It returns a null pointer if no such character from stopset is found.

Compatibility String Search Functions

Function: char * index (const char *string, int c)
index is another name for strchr; they are exactly the same. New code should always use strchr since this name is defined in ISO C while index is a BSD invention which never was available on System V derived systems.

Function: char * rindex (const char *string, int c)
rindex is another name for strrchr; they are exactly the same. New code should always use strrchr since this name is defined in ISO C while rindex is a BSD invention which never was available on System V derived systems.

Finding Tokens in a String

It's fairly common for programs to have a need to do some simple kinds of lexical analysis and parsing, such as splitting a command string up into tokens. You can do this with the strtok function, declared in the header file `string.h'.

Function: char * strtok (char *restrict newstring, const char *restrict delimiters)
A string can be split into tokens by making a series of calls to the function strtok.

The string to be split up is passed as the newstring argument on the first call only. The strtok function uses this to set up some internal state information. Subsequent calls to get additional tokens from the same string are indicated by passing a null pointer as the newstring argument. Calling strtok with another non-null newstring argument reinitializes the state information. It is guaranteed that no other library function ever calls strtok behind your back (which would mess up this internal state information).

The delimiters argument is a string that specifies a set of delimiters that may surround the token being extracted. All the initial characters that are members of this set are discarded. The first character that is not a member of this set of delimiters marks the beginning of the next token. The end of the token is found by looking for the next character that is a member of the delimiter set. This character in the original string newstring is overwritten by a null character, and the pointer to the beginning of the token in newstring is returned.

On the next call to strtok, the searching begins at the next character beyond the one that marked the end of the previous token. Note that the set of delimiters delimiters do not have to be the same on every call in a series of calls to strtok.

If the end of the string newstring is reached, or if the remainder of string consists only of delimiter characters, strtok returns a null pointer.

Note that "character" is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale-dependent.

Note that "character" is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale-dependent.

Function: wchar_t * wcstok (wchar_t *newstring, const char *delimiters)
A string can be split into tokens by making a series of calls to the function wcstok.

The string to be split up is passed as the newstring argument on the first call only. The wcstok function uses this to set up some internal state information. Subsequent calls to get additional tokens from the same wide character string are indicated by passing a null pointer as the newstring argument. Calling wcstok with another non-null newstring argument reinitializes the state information. It is guaranteed that no other library function ever calls wcstok behind your back (which would mess up this internal state information).

The delimiters argument is a wide character string that specifies a set of delimiters that may surround the token being extracted. All the initial wide characters that are members of this set are discarded. The first wide character that is not a member of this set of delimiters marks the beginning of the next token. The end of the token is found by looking for the next wide character that is a member of the delimiter set. This wide character in the original wide character string newstring is overwritten by a null wide character, and the pointer to the beginning of the token in newstring is returned.

On the next call to wcstok, the searching begins at the next wide character beyond the one that marked the end of the previous token. Note that the set of delimiters delimiters do not have to be the same on every call in a series of calls to wcstok.

If the end of the wide character string newstring is reached, or if the remainder of string consists only of delimiter wide characters, wcstok returns a null pointer.

Note that "character" is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale-dependent.

Warning: Since strtok and wcstok alter the string they is parsing, you should always copy the string to a temporary buffer before parsing it with strtok/wcstok (see section Copying and Concatenation). If you allow strtok or wcstok to modify a string that came from another part of your program, you are asking for trouble; that string might be used for other purposes after strtok or wcstok has modified it, and it would not have the expected value.

The string that you are operating on might even be a constant. Then when strtok or wcstok tries to modify it, your program will get a fatal signal for writing in read-only memory. See section Program Error Signals. Even if the operation of strtok or wcstok would not require a modification of the string (e.g., if there is exactly one token) the string can (and in the GNU libc case will) be modified.

This is a special case of a general principle: if a part of a program does not have as its purpose the modification of a certain data structure, then it is error-prone to modify the data structure temporarily.

The functions strtok and wcstok are not reentrant. See section Signal Handling and Nonreentrant Functions, for a discussion of where and why reentrancy is important.

Here is a simple example showing the use of strtok.
#include <string.h>
#include <stddef.h>

...

const char string[] = "words separated by spaces -- and, punctuation!";
const char delimiters[] = " .,;:!-";
char *token, *cp;

...

cp = strdupa (string);                /* Make writable copy.  */
token = strtok (cp, delimiters);      /* token => "words" */
token = strtok (NULL, delimiters);    /* token => "separated" */
token = strtok (NULL, delimiters);    /* token => "by" */
token = strtok (NULL, delimiters);    /* token => "spaces" */
token = strtok (NULL, delimiters);    /* token => "and" */
token = strtok (NULL, delimiters);    /* token => "punctuation" */
token = strtok (NULL, delimiters);    /* token => NULL */
The GNU C library contains two more functions for tokenizing a string which overcome the limitation of non-reentrancy. They are only available for multibyte character strings.

Function: char * strtok_r (char *newstring, const char *delimiters, char **save_ptr)
Just like strtok, this function splits the string into several tokens which can be accessed by successive calls to strtok_r. The difference is that the information about the next token is stored in the space pointed to by the third argument, save_ptr, which is a pointer to a string pointer. Calling strtok_r with a null pointer for newstring and leaving save_ptr between the calls unchanged does the job without hindering reentrancy.

This function is defined in POSIX.1 and can be found on many systems which support multi-threading.

Function: char * strsep (char **string_ptr, const char *delimiter)
This function has a similar functionality as strtok_r with the newstring argument replaced by the save_ptr argument. The initialization of the moving pointer has to be done by the user. Successive calls to strsep move the pointer along the tokens separated by delimiter, returning the address of the next token and updating string_ptr to point to the beginning of the next token.

One difference between strsep and strtok_r is that if the input string contains more than one character from delimiter in a row strsep returns an empty string for each pair of characters from delimiter. This means that a program normally should test for strsep returning an empty string before processing it.

This function was introduced in 4.3BSD and therefore is widely available.

Here is how the above example looks like when strsep is used.
#include <string.h>
#include <stddef.h>

...

const char string[] = "words separated by spaces -- and, punctuation!";
const char delimiters[] = " .,;:!-";
char *running;
char *token;

...

running = strdupa (string);
token = strsep (&running, delimiters);    /* token => "words" */
token = strsep (&running, delimiters);    /* token => "separated" */
token = strsep (&running, delimiters);    /* token => "by" */
token = strsep (&running, delimiters);    /* token => "spaces" */
token = strsep (&running, delimiters);    /* token => "" */
token = strsep (&running, delimiters);    /* token => "" */
token = strsep (&running, delimiters);    /* token => "" */
token = strsep (&running, delimiters);    /* token => "and" */
token = strsep (&running, delimiters);    /* token => "" */
token = strsep (&running, delimiters);    /* token => "punctuation" */
token = strsep (&running, delimiters);    /* token => "" */
token = strsep (&running, delimiters);    /* token => NULL */
Function: char * basename (const char *filename)
The GNU version of the basename function returns the last component of the path in filename. This function is the prefered usage, since it does not modify the argument, filename, and respects trailing slashes. The prototype for basename can be found in `string.h'. Note, this function is overriden by the XPG version, if `libgen.h' is included.

Example of using GNU basename:
#include <string.h>

int
main (int argc, char *argv[])
{
  char *prog = basename (argv[0]);

  if (argc < 2)
    {
      fprintf (stderr, "Usage %s <arg>\n", prog);
      exit (1);
    }

  ...
}
Portability Note: This function may produce different results on different systems.

Function: char * basename (char *path)
This is the standard XPG defined basename. It is similar in spirit to the GNU version, but may modify the path by removing trailing '/' characters. If the path is made up entirely of '/' characters, then "/" will be returned. Also, if path is NULL or an empty string, then "." is returned. The prototype for the XPG version can be found in `libgen.h'.

Example of using XPG basename:
#include <libgen.h>

int
main (int argc, char *argv[])
{
  char *prog;
  char *path = strdupa (argv[0]);

  prog = basename (path);

  if (argc < 2)
    {
      fprintf (stderr, "Usage %s <arg>\n", prog);
      exit (1);
    }

  ...

}
Function: char * dirname (char *path)
The dirname function is the compliment to the XPG version of basename. It returns the parent directory of the file specified by path. If path is NULL, an empty string, or contains no '/' characters, then "." is returned. The prototype for this function can be found in `libgen.h'.

strfry

The function below addresses the perennial programming quandary: "How do I take good data in string form and painlessly turn it into garbage?" This is actually a fairly simple task for C programmers who do not use the GNU C library string functions, but for programs based on the GNU C library, the strfry function is the preferred method for destroying string data.

The prototype for this function is in `string.h'.

Function: char * strfry (char *string)

strfry creates a pseudorandom anagram of a string, replacing the input with the anagram in place. For each position in the string, strfry swaps it with a position in the string selected at random (from a uniform distribution). The two positions may be the same.

The return value of strfry is always string.

Portability Note: This function is unique to the GNU C library.

Trivial Encryption

The memfrob function converts an array of data to something unrecognizable and back again. It is not encryption in its usual sense since it is easy for someone to convert the encrypted data back to clear text. The transformation is analogous to Usenet's "Rot13" encryption method for obscuring offensive jokes from sensitive eyes and such. Unlike Rot13, memfrob works on arbitrary binary data, not just text.

For true encryption, See section DES Encryption and Password Handling.

This function is declared in `string.h'.

Function: void * memfrob (void *mem, size_t length)

memfrob transforms (frobnicates) each byte of the data structure at mem, which is length bytes long, by bitwise exclusive oring it with binary 00101010. It does the transformation in place and its return value is always mem.

Note that memfrob a second time on the same data structure returns it to its original state.

This is a good function for hiding information from someone who doesn't want to see it or doesn't want to see it very much. To really prevent people from retrieving the information, use stronger encryption such as that described in See section DES Encryption and Password Handling.

Portability Note: This function is unique to the GNU C library.

Encode Binary Data

To store or transfer binary data in environments which only support text one has to encode the binary data by mapping the input bytes to characters in the range allowed for storing or transfering. SVID systems (and nowadays XPG compliant systems) provide minimal support for this task.

Function: char * l64a (long int n)
This function encodes a 32-bit input value using characters from the basic character set. It returns a pointer to a 6 character buffer which contains an encoded version of n. To encode a series of bytes the user must copy the returned string to a destination buffer. It returns the empty string if n is zero, which is somewhat bizarre but mandated by the standard.
Warning: Since a static buffer is used this function should not be used in multi-threaded programs. There is no thread-safe alternative to this function in the C library.
Compatibility Note: The XPG standard states that the return value of l64a is undefined if n is negative. In the GNU implementation, l64a treats its argument as unsigned, so it will return a sensible encoding for any nonzero n; however, portable programs should not rely on this.

To encode a large buffer l64a must be called in a loop, once for each 32-bit word of the buffer. For example, one could do something like this:
char *
encode (const void *buf, size_t len)
{
  /* We know in advance how long the buffer has to be. */
  unsigned char *in = (unsigned char *) buf;
  char *out = malloc (6 + ((len + 3) / 4) * 6 + 1);
  char *cp = out;

  /* Encode the length. */
  /* Using `htonl' is necessary so that the data can be
     decoded even on machines with different byte order. */

  cp = mempcpy (cp, l64a (htonl (len)), 6);

  while (len > 3)
    {
      unsigned long int n = *in++;
      n = (n << 8) | *in++;
      n = (n << 8) | *in++;
      n = (n << 8) | *in++;
      len -= 4;
      if (n)
        cp = mempcpy (cp, l64a (htonl (n)), 6);
      else
            /* `l64a' returns the empty string for n==0, so we
               must generate its encoding ("......") by hand. */
        cp = stpcpy (cp, "......");
    }
  if (len > 0)
    {
      unsigned long int n = *in++;
      if (--len > 0)
        {
          n = (n << 8) | *in++;
          if (--len > 0)
            n = (n << 8) | *in;
        }
      memcpy (cp, l64a (htonl (n)), 6);
      cp += 6;
    }
  *cp = '\0';
  return out;
}
It is strange that the library does not provide the complete functionality needed but so be it.

To decode data produced with l64a the following function should be used.

Function: long int a64l (const char *string)
The parameter string should contain a string which was produced by a call to l64a. The function processes at least 6 characters of this string, and decodes the characters it finds according to the table below. It stops decoding when it finds a character not in the table, rather like atoi; if you have a buffer which has been broken into lines, you must be careful to skip over the end-of-line characters.

The decoded number is returned as a long int value.

The l64a and a64l functions use a base 64 encoding, in which each character of an encoded string represents six bits of an input word. These symbols are used for the base 64 digits:

@multitable {xxxxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx}
@tab 0 @tab 1 @tab 2 @tab 3 @tab 4 @tab 5 @tab 6 @tab 7
0 @tab . @tab / @tab 0 @tab 1 @tab 2 @tab 3 @tab 4 @tab 5
8 @tab 6 @tab 7 @tab 8 @tab 9 @tab A @tab B @tab C @tab D
16 @tab E @tab F @tab G @tab H @tab I @tab J @tab K @tab L
24 @tab M @tab N @tab O @tab P @tab Q @tab R @tab S @tab T
32 @tab U @tab V @tab W @tab X @tab Y @tab Z @tab a @tab b
40 @tab c @tab d @tab e @tab f @tab g @tab h @tab i @tab j
48 @tab k @tab l @tab m @tab n @tab o @tab p @tab q @tab r
56 @tab s @tab t @tab u @tab v @tab w @tab x @tab y @tab z This encoding scheme is not standard. There are some other encoding methods which are much more widely used (UU encoding, MIME encoding). Generally, it is better to use one of these encodings.
Argz and Envz Vectors

argz vectors are vectors of strings in a contiguous block of memory, each element separated from its neighbors by null-characters ('\0').

Envz vectors are an extension of argz vectors where each element is a name-value pair, separated by a '=' character (as in a Unix environment).

Argz Functions

Each argz vector is represented by a pointer to the first element, of type char *, and a size, of type size_t, both of which can be initialized to 0 to represent an empty argz vector. All argz functions accept either a pointer and a size argument, or pointers to them, if they will be modified.

The argz functions use malloc/realloc to allocate/grow argz vectors, and so any argz vector creating using these functions may be freed by using free; conversely, any argz function that may grow a string expects that string to have been allocated using malloc (those argz functions that only examine their arguments or modify them in place will work on any sort of memory). See section Unconstrained Allocation.

All argz functions that do memory allocation have a return type of error_t, and return 0 for success, and ENOMEM if an allocation error occurs.

These functions are declared in the standard include file `argz.h'.

Function: error_t argz_create (char *const argv[], char **argz, size_t *argz_len)
The argz_create function converts the Unix-style argument vector argv (a vector of pointers to normal C strings, terminated by (char *)0; see section Program Arguments) into an argz vector with the same elements, which is returned in argz and argz_len.

Function: error_t argz_create_sep (const char *string, int sep, char **argz, size_t *argz_len)
The argz_create_sep function converts the null-terminated string string into an argz vector (returned in argz and argz_len) by splitting it into elements at every occurrence of the character sep.

Function: size_t argz_count (const char *argz, size_t arg_len)
Returns the number of elements in the argz vector argz and argz_len.

Function: void argz_extract (char *argz, size_t argz_len, char **argv)
The argz_extract function converts the argz vector argz and argz_len into a Unix-style argument vector stored in argv, by putting pointers to every element in argz into successive positions in argv, followed by a terminator of 0. Argv must be pre-allocated with enough space to hold all the elements in argz plus the terminating (char *)0 ((argz_count (argz, argz_len) + 1) * sizeof (char *) bytes should be enough). Note that the string pointers stored into argv point into argz---they are not copies--and so argz must be copied if it will be changed while argv is still active. This function is useful for passing the elements in argz to an exec function (see section Executing a File).

Function: void argz_stringify (char *argz, size_t len, int sep)
The argz_stringify converts argz into a normal string with the elements separated by the character sep, by replacing each '\0' inside argz (except the last one, which terminates the string) with sep. This is handy for printing argz in a readable manner.

Function: error_t argz_add (char **argz, size_t *argz_len, const char *str)
The argz_add function adds the string str to the end of the argz vector *argz, and updates *argz and *argz_len accordingly.

Function: error_t argz_add_sep (char **argz, size_t *argz_len, const char *str, int delim)
The argz_add_sep function is similar to argz_add, but str is split into separate elements in the result at occurrences of the character delim. This is useful, for instance, for adding the components of a Unix search path to an argz vector, by using a value of ':' for delim.

Function: error_t argz_append (char **argz, size_t *argz_len, const char *buf, size_t buf_len)
The argz_append function appends buf_len bytes starting at buf to the argz vector *argz, reallocating *argz to accommodate it, and adding buf_len to *argz_len.

Function: error_t argz_delete (char **argz, size_t *argz_len, char *entry)
If entry points to the beginning of one of the elements in the argz vector *argz, the argz_delete function will remove this entry and reallocate *argz, modifying *argz and *argz_len accordingly. Note that as destructive argz functions usually reallocate their argz argument, pointers into argz vectors such as entry will then become invalid.

Function: error_t argz_insert (char **argz, size_t *argz_len, char *before, const char *entry)
The argz_insert function inserts the string entry into the argz vector *argz at a point just before the existing element pointed to by before, reallocating *argz and updating *argz and *argz_len. If before is 0, entry is added to the end instead (as if by argz_add). Since the first element is in fact the same as *argz, passing in *argz as the value of before will result in entry being inserted at the beginning.

Function: char * argz_next (char *argz, size_t argz_len, const char *entry)
The argz_next function provides a convenient way of iterating over the elements in the argz vector argz. It returns a pointer to the next element in argz after the element entry, or 0 if there are no elements following entry. If entry is 0, the first element of argz is returned.

This behavior suggests two styles of iteration:
    char *entry = 0;
    while ((entry = argz_next (argz, argz_len, entry)))
      action;
(the double parentheses are necessary to make some C compilers shut up about what they consider a questionable while-test) and:
    char *entry;
    for (entry = argz;
         entry;
         entry = argz_next (argz, argz_len, entry))
      action;
Note that the latter depends on argz having a value of 0 if it is empty (rather than a pointer to an empty block of memory); this invariant is maintained for argz vectors created by the functions here.

Function: error_t argz_replace (char **argz, size_t *argz_len, const char *str, const char *with, unsigned *replace_count)
Replace any occurrences of the string str in argz with with, reallocating argz as necessary. If replace_count is non-zero, *replace_count will be incremented by number of replacements performed.

Envz Functions

Envz vectors are just argz vectors with additional constraints on the form of each element; as such, argz functions can also be used on them, where it makes sense.

Each element in an envz vector is a name-value pair, separated by a '=' character; if multiple '=' characters are present in an element, those after the first are considered part of the value, and treated like all other non-'\0' characters.

If no '=' characters are present in an element, that element is considered the name of a "null" entry, as distinct from an entry with an empty value: envz_get will return 0 if given the name of null entry, whereas an entry with an empty value would result in a value of ""; envz_entry will still find such entries, however. Null entries can be removed with envz_strip function.

As with argz functions, envz functions that may allocate memory (and thus fail) have a return type of error_t, and return either 0 or ENOMEM.

These functions are declared in the standard include file `envz.h'.

Function: char * envz_entry (const char *envz, size_t envz_len, const char *name)
The envz_entry function finds the entry in envz with the name name, and returns a pointer to the whole entry--that is, the argz element which begins with name followed by a '=' character. If there is no entry with that name, 0 is returned.

Function: char * envz_get (const char *envz, size_t envz_len, const char *name)
The envz_get function finds the entry in envz with the name name (like envz_entry), and returns a pointer to the value portion of that entry (following the '='). If there is no entry with that name (or only a null entry), 0 is returned.

Function: error_t envz_add (char **envz, size_t *envz_len, const char *name, const char *value)
The envz_add function adds an entry to *envz (updating *envz and *envz_len) with the name name, and value value. If an entry with the same name already exists in envz, it is removed first. If value is 0, then the new entry will the special null type of entry (mentioned above).

Function: error_t envz_merge (char **envz, size_t *envz_len, const char *envz2, size_t envz2_len, int override)
The envz_merge function adds each entry in envz2 to envz, as if with envz_add, updating *envz and *envz_len. If override is true, then values in envz2 will supersede those with the same name in envz, otherwise not.

Null entries are treated just like other entries in this respect, so a null entry in envz can prevent an entry of the same name in envz2 from being added to envz, if override is false.

Function: void envz_strip (char **envz, size_t *envz_len)
The envz_strip function removes any null entries from envz, updating *envz and *envz_len.
Character Set Handling

@ifnottex @macro cal{text} \text\

Character sets used in the early days of computing had only six, seven, or eight bits for each character: there was never a case where more than eight bits (one byte) were used to represent a single character. The limitations of this approach became more apparent as more people grappled with non-Roman character sets, where not all the characters that make up a language's character set can be represented by @math{2^8} choices. This chapter shows the functionality which was added to the C library to support multiple character sets.

Introduction to Extended Characters

A variety of solutions to overcome the differences between character sets with a 1:1 relation between bytes and characters and character sets with ratios of 2:1 or 4:1 exist. The remainder of this section gives a few examples to help understand the design decisions made while developing the functionality of the C library.

A distinction we have to make right away is between internal and external representation. Internal representation means the representation used by a program while keeping the text in memory. External representations are used when text is stored or transmitted through whatever communication channel. Examples of external representations include files lying in a directory that are going to be read and parsed.

Traditionally there has been no difference between the two representations. It was equally comfortable and useful to use the same single-byte representation internally and externally. This changes with more and larger character sets.

One of the problems to overcome with the internal representation is handling text that is externally encoded using different character sets. Assume a program which reads two texts and compares them using some metric. The comparison can be usefully done only if the texts are internally kept in a common format.

For such a common format (@math{=} character set) eight bits are certainly no longer enough. So the smallest entity will have to grow: wide characters will now be used. Instead of one byte, two or four will be used instead. (Three are not good to address in memory and more than four bytes seem not to be necessary).

As shown in some other part of this manual, there exists a completely new family of functions which can handle texts of this kind in memory. The most commonly used character sets for such internal wide character representations are Unicode and ISO 10646 (also known as UCS for Universal Character Set). Unicode was originally planned as a 16-bit character set, whereas ISO 10646 was designed to be a 31-bit large code space. The two standards are practically identical. They have the same character repertoire and code table, but Unicode specifies added semantics. At the moment, only characters in the first 0x10000 code positions (the so-called Basic Multilingual Plane, BMP) have been assigned, but the assignment of more specialized characters outside this 16-bit space is already in progress. A number of encodings have been defined for Unicode and ISO 10646 characters: UCS-2 is a 16-bit word that can only represent characters from the BMP, UCS-4 is a 32-bit word than can represent any Unicode and ISO 10646 character, UTF-8 is an ASCII compatible encoding where ASCII characters are represented by ASCII bytes and non-ASCII characters by sequences of 2-6 non-ASCII bytes, and finally UTF-16 is an extension of UCS-2 in which pairs of certain UCS-2 words can be used to encode non-BMP characters up to 0x10ffff.

To represent wide characters the char type is not suitable. For this reason the ISO C standard introduces a new type which is designed to keep one character of a wide character string. To maintain the similarity there is also a type corresponding to int for those functions which take a single wide character.

Data type: wchar_t
This data type is used as the base type for wide character strings. I.e., arrays of objects of this type are the equivalent of char[] for multibyte character strings. The type is defined in `stddef.h'.

The ISO C90 standard, where this type was introduced, does not say anything specific about the representation. It only requires that this type is capable of storing all elements of the basic character set. Therefore it would be legitimate to define wchar_t as char. This might make sense for embedded systems.

But for GNU systems this type is always 32 bits wide. It is therefore capable of representing all UCS-4 values and therefore covering all of ISO 10646. Some Unix systems define wchar_t as a 16-bit type and thereby follow Unicode very strictly. This is perfectly fine with the standard but it also means that to represent all characters from Unicode and ISO 10646 one has to use UTF-16 surrogate characters which is in fact a multi-wide-character encoding. But this contradicts the purpose of the wchar_t type.

Data type: wint_t
wint_t is a data type used for parameters and variables which contain a single wide character. As the name already suggests it is the equivalent to int when using the normal char strings. The types wchar_t and wint_t have often the same representation if their size if 32 bits wide but if wchar_t is defined as char the type wint_t must be defined as int due to the parameter promotion.

This type is defined in `wchar.h' and got introduced in Amendment 1 to ISO C90.

As there are for the char data type there also exist macros specifying the minimum and maximum value representable in an object of type wchar_t.

Macro: wint_t WCHAR_MIN
The macro WCHAR_MIN evaluates to the minimum value representable by an object of type wint_t.

This macro got introduced in Amendment 1 to ISO C90.

Macro: wint_t WCHAR_MAX
The macro WCHAR_MAX evaluates to the maximum value representable by an object of type wint_t.

This macro got introduced in Amendment 1 to ISO C90.

Another special wide character value is the equivalent to EOF.

Macro: wint_t WEOF
The macro WEOF evaluates to a constant expression of type wint_t whose value is different from any member of the extended character set.

WEOF need not be the same value as EOF and unlike EOF it also need not be negative. I.e., sloppy code like
{
  int c;
  ...
  while ((c = getc (fp)) < 0)
    ...
}
has to be rewritten to explicitly use WEOF when wide characters are used.
{
  wint_t c;
  ...
  while ((c = wgetc (fp)) != WEOF)
    ...
}
This macro was introduced in Amendment 1 to ISO C90 and is defined in `wchar.h'.

These internal representations present problems when it comes to storing and transmittal, since a single wide character consists of more than one byte they are effected by byte-ordering. I.e., machines with different endianesses would see different value accessing the same data. This also applies for communication protocols which are all byte-based and therefore the sender has to decide about splitting the wide character in bytes. A last (but not least important) point is that wide characters often require more storage space than an customized byte oriented character set.

For all the above reasons, an external encoding which is different from the internal encoding is often used if the latter is UCS-2 or UCS-4. The external encoding is byte-based and can be chosen appropriately for the environment and for the texts to be handled. There exist a variety of different character sets which can be used for this external encoding. Information which will not be exhaustively presented here--instead, a description of the major groups will suffice. All of the ASCII-based character sets [_bkoz_: do you mean Roman character sets? If not, what do you mean here?] fulfill one requirement: they are "filesystem safe". This means that the character '/' is used in the encoding only to represent itself. Things are a bit different for character sets like EBCDIC (Extended Binary Coded Decimal Interchange Code, a character set family used by IBM) but if the operation system does not understand EBCDIC directly the parameters to system calls have to be converted first anyhow.

The simplest character sets are single-byte character sets. There can be only up to 256 characters (for 8 bit character sets) which is not sufficient to cover all languages but might be sufficient to handle a specific text. Another reason to choose this is because of constraints from interaction with other programs (which might not be 8-bit clean).
The ISO 2022 standard defines a mechanism for extended character sets where one character can be represented by more than one byte. This is achieved by associating a state with the text. Embedded in the text can be characters which can be used to change the state. Each byte in the text might have a different interpretation in each state. The state might even influence whether a given byte stands for a character on its own or whether it has to be combined with some more bytes. In most uses of ISO 2022 the defined character sets do not allow state changes which cover more than the next character. This has the big advantage that whenever one can identify the beginning of the byte sequence of a character one can interpret a text correctly. Examples of character sets using this policy are the various EUC character sets (used by Sun's operations systems, EUC-JP, EUC-KR, EUC-TW, and EUC-CN) or SJIS (Shift-JIS, a Japanese encoding). But there are also character sets using a state which is valid for more than one character and has to be changed by another byte sequence. Examples for this are ISO-2022-JP, ISO-2022-KR, and ISO-2022-CN.
Early attempts to fix 8 bit character sets for other languages using the Roman alphabet lead to character sets like ISO 6937. Here bytes representing characters like the acute accent do not produce output themselves: one has to combine them with other characters to get the desired result. E.g., the byte sequence 0xc2 0x61 (non-spacing acute accent, following by lower-case `a') to get the "small a with acute" character. To get the acute accent character on its own, one has to write 0xc2 0x20 (the non-spacing acute followed by a space). This type of character set is used in some embedded systems such as teletex.
Instead of converting the Unicode or ISO 10646 text used internally, it is often also sufficient to simply use an encoding different than UCS-2/UCS-4. The Unicode and ISO 10646 standards even specify such an encoding: UTF-8. This encoding is able to represent all of ISO 10464 31 bits in a byte string of length one to six. There were a few other attempts to encode ISO 10646 such as UTF-7 but UTF-8 is today the only encoding which should be used. In fact, UTF-8 will hopefully soon be the only external encoding that has to be supported. It proves to be universally usable and the only disadvantage is that it favors Roman languages by making the byte string representation of other scripts (Cyrillic, Greek, Asian scripts) longer than necessary if using a specific character set for these scripts. Methods like the Unicode compression scheme can alleviate these problems.

The question remaining is: how to select the character set or encoding to use. The answer: you cannot decide about it yourself, it is decided by the developers of the system or the majority of the users. Since the goal is interoperability one has to use whatever the other people one works with use. If there are no constraints the selection is based on the requirements the expected circle of users will have. I.e., if a project is expected to only be used in, say, Russia it is fine to use KOI8-R or a similar character set. But if at the same time people from, say, Greece are participating one should use a character set which allows all people to collaborate.

The most widely useful solution seems to be: go with the most general character set, namely ISO 10646. Use UTF-8 as the external encoding and problems about users not being able to use their own language adequately are a thing of the past.

One final comment about the choice of the wide character representation is necessary at this point. We have said above that the natural choice is using Unicode or ISO 10646. This is not required, but at least encouraged, by the ISO C standard. The standard defines at least a macro __STDC_ISO_10646__ that is only defined on systems where the wchar_t type encodes ISO 10646 characters. If this symbol is not defined one should as much as possible avoid making assumption about the wide character representation. If the programmer uses only the functions provided by the C library to handle wide character strings there should not be any compatibility problems with other systems.

Overview about Character Handling Functions

A Unix C library contains three different sets of functions in two families to handle character set conversion. The one function family is specified in the ISO C standard and therefore is portable even beyond the Unix world.

The most commonly known set of functions, coming from the ISO C90 standard, is unfortunately the least useful one. In fact, these functions should be avoided whenever possible, especially when developing libraries (as opposed to applications).

The second family of functions got introduced in the early Unix standards (XPG2) and is still part of the latest and greatest Unix standard: Unix 98. It is also the most powerful and useful set of functions. But we will start with the functions defined in Amendment 1 to ISO C90.

Restartable Multibyte Conversion Functions

The ISO C standard defines functions to convert strings from a multibyte representation to wide character strings. There are a number of peculiarities:

The character set assumed for the multibyte encoding is not specified as an argument to the functions. Instead the character set specified by the LC_CTYPE category of the current locale is used; see section Categories of Activities that Locales Affect.
The functions handling more than one character at a time require NUL terminated strings as the argument. I.e., converting blocks of text does not work unless one can add a NUL byte at an appropriate place. The GNU C library contains some extensions the standard which allow specifying a size but basically they also expect terminated strings.

Despite these limitations the ISO C functions can very well be used in many contexts. In graphical user interfaces, for instance, it is not uncommon to have functions which require text to be displayed in a wide character string if it is not simple ASCII. The text itself might come from a file with translations and the user should decide about the current locale which determines the translation and therefore also the external encoding used. In such a situation (and many others) the functions described here are perfect. If more freedom while performing the conversion is necessary take a look at the iconv functions (see section Generic Charset Conversion).

Selecting the conversion and its properties

We already said above that the currently selected locale for the LC_CTYPE category decides about the conversion which is performed by the functions we are about to describe. Each locale uses its own character set (given as an argument to localedef) and this is the one assumed as the external multibyte encoding. The wide character character set always is UCS-4, at least on GNU systems.

A characteristic of each multibyte character set is the maximum number of bytes which can be necessary to represent one character. This information is quite important when writing code which uses the conversion functions. In the examples below we will see some examples. The ISO C standard defines two macros which provide this information.

Macro: int MB_LEN_MAX
This macro specifies the maximum number of bytes in the multibyte sequence for a single character in any of the supported locales. It is a compile-time constant and it is defined in `limits.h'.

Macro: int MB_CUR_MAX
MB_CUR_MAX expands into a positive integer expression that is the maximum number of bytes in a multibyte character in the current locale. The value is never greater than MB_LEN_MAX. Unlike MB_LEN_MAX this macro need not be a compile-time constant and in fact, in the GNU C library it is not.

MB_CUR_MAX is defined in `stdlib.h'.

Two different macros are necessary since strictly ISO C90 compilers do not allow variable length array definitions but still it is desirable to avoid dynamic allocation. This incomplete piece of code shows the problem:
{
  char buf[MB_LEN_MAX];
  ssize_t len = 0;

  while (! feof (fp))
    {
      fread (&buf[len], 1, MB_CUR_MAX - len, fp);
      /* ... process buf */
      len -= used;
    }
}
The code in the inner loop is expected to have always enough bytes in the array buf to convert one multibyte character. The array buf has to be sized statically since many compilers do not allow a variable size. The fread call makes sure that always MB_CUR_MAX bytes are available in buf. Note that it isn't a problem if MB_CUR_MAX is not a compile-time constant.

Representing the state of the conversion

In the introduction of this chapter it was said that certain character sets use a stateful encoding. I.e., the encoded values depend in some way on the previous bytes in the text.

Since the conversion functions allow converting a text in more than one step we must have a way to pass this information from one call of the functions to another.

Data type: mbstate_t
A variable of type mbstate_t can contain all the information about the shift state needed from one call to a conversion function to another.

This type is defined in `wchar.h'. It got introduced in Amendment 1 to ISO C90.

To use objects of this type the programmer has to define such objects (normally as local variables on the stack) and pass a pointer to the object to the conversion functions. This way the conversion function can update the object if the current multibyte character set is stateful.

There is no specific function or initializer to put the state object in any specific state. The rules are that the object should always represent the initial state before the first use and this is achieved by clearing the whole variable with code such as follows:
{
  mbstate_t state;
  memset (&state, '\0', sizeof (state));
  /* from now on state can be used.  */
  ...
}
When using the conversion functions to generate output it is often necessary to test whether the current state corresponds to the initial state. This is necessary, for example, to decide whether or not to emit escape sequences to set the state to the initial state at certain sequence points. Communication protocols often require this.

Function: int mbsinit (const mbstate_t *ps)
This function determines whether the state object pointed to by ps is in the initial state or not. If ps is a null pointer or the object is in the initial state the return value is nonzero. Otherwise it is zero.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

Code using this function often looks similar to this:
{
  mbstate_t state;
  memset (&state, '\0', sizeof (state));
  /* Use state.  */
  ...
  if (! mbsinit (&state))
    {
      /* Emit code to return to initial state.  */
      const wchar_t empty[] = L"";
      const wchar_t *srcp = empty;
      wcsrtombs (outbuf, &srcp, outbuflen, &state);
    }
  ...
}
The code to emit the escape sequence to get back to the initial state is interesting. The wcsrtombs function can be used to determine the necessary output code (see section Converting Multibyte and Wide Character Strings). Please note that on GNU systems it is not necessary to perform this extra action for the conversion from multibyte text to wide character text since the wide character encoding is not stateful. But there is nothing mentioned in any standard which prohibits making wchar_t using a stateful encoding.

Converting Single Characters

The most fundamental of the conversion functions are those dealing with single characters. Please note that this does not always mean single bytes. But since there is very often a subset of the multibyte character set which consists of single byte sequences there are functions to help with converting bytes. One very important and often applicable scenario is where ASCII is a subpart of the multibyte character set. I.e., all ASCII characters stand for itself and all other characters have at least a first byte which is beyond the range @math{0} to @math{127}.

Function: wint_t btowc (int c)
The btowc function ("byte to wide character") converts a valid single byte character c in the initial shift state into the wide character equivalent using the conversion rules from the currently selected locale of the LC_CTYPE category.

If (unsigned char) c is no valid single byte multibyte character or if c is EOF the function returns WEOF.

Please note the restriction of c being tested for validity only in the initial shift state. There is no mbstate_t object used from which the state information is taken and the function also does not use any static state.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

Despite the limitation that the single byte value always is interpreted in the initial state this function is actually useful most of the time. Most characters are either entirely single-byte character sets or they are extension to ASCII. But then it is possible to write code like this (not that this specific example is very useful):
wchar_t *
itow (unsigned long int val)
{
  static wchar_t buf[30];
  wchar_t *wcp = &buf[29];
  *wcp = L'\0';
  while (val != 0)
    {
      *--wcp = btowc ('0' + val % 10);
      val /= 10;
    }
  if (wcp == &buf[29])
    *--wcp = L'0';
  return wcp;
}
Why is it necessary to use such a complicated implementation and not simply cast '0' + val % 10 to a wide character? The answer is that there is no guarantee that one can perform this kind of arithmetic on the character of the character set used for wchar_t representation. In other situations the bytes are not constant at compile time and so the compiler cannot do the work. In situations like this it is necessary btowc.

There also is a function for the conversion in the other direction.

Function: int wctob (wint_t c)
The wctob function ("wide character to byte") takes as the parameter a valid wide character. If the multibyte representation for this character in the initial state is exactly one byte long the return value of this function is this character. Otherwise the return value is EOF.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

There are more general functions to convert single character from multibyte representation to wide characters and vice versa. These functions pose no limit on the length of the multibyte representation and they also do not require it to be in the initial state.

Function: size_t mbrtowc (wchar_t *restrict pwc, const char *restrict s, size_t n, mbstate_t *restrict ps)
The mbrtowc function ("multibyte restartable to wide character") converts the next multibyte character in the string pointed to by s into a wide character and stores it in the wide character string pointed to by pwc. The conversion is performed according to the locale currently selected for the LC_CTYPE category. If the conversion for the character set used in the locale requires a state the multibyte string is interpreted in the state represented by the object pointed to by ps. If ps is a null pointer, a static, internal state variable used only by the mbrtowc function is used.

If the next multibyte character corresponds to the NUL wide character the return value of the function is @math{0} and the state object is afterwards in the initial state. If the next n or fewer bytes form a correct multibyte character the return value is the number of bytes starting from s which form the multibyte character. The conversion state is updated according to the bytes consumed in the conversion. In both cases the wide character (either the L'\0' or the one found in the conversion) is stored in the string pointer to by pwc iff pwc is not null.

If the first n bytes of the multibyte string possibly form a valid multibyte character but there are more than n bytes needed to complete it the return value of the function is (size_t) -2 and no value is stored. Please note that this can happen even if n has a value greater or equal to MB_CUR_MAX since the input might contain redundant shift sequences.

If the first n bytes of the multibyte string cannot possibly form a valid multibyte character also no value is stored, the global variable errno is set to the value EILSEQ and the function returns (size_t) -1. The conversion state is afterwards undefined.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

Using this function is straight forward. A function which copies a multibyte string into a wide character string while at the same time converting all lowercase character into uppercase could look like this (this is not the final version, just an example; it has no error checking, and leaks sometimes memory):
wchar_t *
mbstouwcs (const char *s)
{
  size_t len = strlen (s);
  wchar_t *result = malloc ((len + 1) * sizeof (wchar_t));
  wchar_t *wcp = result;
  wchar_t tmp[1];
  mbstate_t state;
  size_t nbytes;

  memset (&state, '\0', sizeof (state));
  while ((nbytes = mbrtowc (tmp, s, len, &state)) > 0)
    {
      if (nbytes >= (size_t) -2)
        /* Invalid input string.  */
        return NULL;
      *result++ = towupper (tmp[0]);
      len -= nbytes;
      s += nbytes;
    }
  return result;
}
The use of mbrtowc should be clear. A single wide character is stored in tmp[0] and the number of consumed bytes is stored in the variable nbytes. In case the the conversion was successful the uppercase variant of the wide character is stored in the result array and the pointer to the input string and the number of available bytes is adjusted.

The only non-obvious thing about the function might be the way memory is allocated for the result. The above code uses the fact that there can never be more wide characters in the converted results than there are bytes in the multibyte input string. This method yields to a pessimistic guess about the size of the result and if many wide character strings have to be constructed this way or the strings are long, the extra memory required allocated because the input string contains multibyte characters might be significant. It would be possible to resize the allocated memory block to the correct size before returning it. A better solution might be to allocate just the right amount of space for the result right away. Unfortunately there is no function to compute the length of the wide character string directly from the multibyte string. But there is a function which does part of the work.

Function: size_t mbrlen (const char *restrict s, size_t n, mbstate_t *ps)
The mbrlen function ("multibyte restartable length") computes the number of at most n bytes starting at s which form the next valid and complete multibyte character.

If the next multibyte character corresponds to the NUL wide character the return value is @math{0}. If the next n bytes form a valid multibyte character the number of bytes belonging to this multibyte character byte sequence is returned.

If the the first n bytes possibly form a valid multibyte character but it is incomplete the return value is (size_t) -2. Otherwise the multibyte character sequence is invalid and the return value is (size_t) -1.

The multibyte sequence is interpreted in the state represented by the object pointed to by ps. If ps is a null pointer, a state object local to mbrlen is used.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

The tentative reader now will of course note that mbrlen can be implemented as
mbrtowc (NULL, s, n, ps != NULL ? ps : &internal)
This is true and in fact is mentioned in the official specification. Now, how can this function be used to determine the length of the wide character string created from a multibyte character string? It is not directly usable but we can define a function mbslen using it:
size_t
mbslen (const char *s)
{
  mbstate_t state;
  size_t result = 0;
  size_t nbytes;
  memset (&state, '\0', sizeof (state));
  while ((nbytes = mbrlen (s, MB_LEN_MAX, &state)) > 0)
    {
      if (nbytes >= (size_t) -2)
        /* Something is wrong.  */
        return (size_t) -1;
      s += nbytes;
      ++result;
    }
  return result;
}
This function simply calls mbrlen for each multibyte character in the string and counts the number of function calls. Please note that we here use MB_LEN_MAX as the size argument in the mbrlen call. This is OK since a) this value is larger then the length of the longest multibyte character sequence and b) because we know that the string s ends with a NUL byte which cannot be part of any other multibyte character sequence but the one representing the NUL wide character. Therefore the mbrlen function will never read invalid memory.

Now that this function is available (just to make this clear, this function is not part of the GNU C library) we can compute the number of wide character required to store the converted multibyte character string s using
wcs_bytes = (mbslen (s) + 1) * sizeof (wchar_t);
Please note that the mbslen function is quite inefficient. The implementation of mbstouwcs implemented using mbslen would have to perform the conversion of the multibyte character input string twice and this conversion might be quite expensive. So it is necessary to think about the consequences of using the easier but imprecise method before doing the work twice.

Function: size_t wcrtomb (char *restrict s, wchar_t wc, mbstate_t *restrict ps)
The wcrtomb function ("wide character restartable to multibyte") converts a single wide character into a multibyte string corresponding to that wide character.

If s is a null pointer the function resets the the state stored in the objects pointer to by ps (or the internal mbstate_t object) to the initial state. This can also be achieved by a call like this:
wcrtombs (temp_buf, L'\0', ps)
since if s is a null pointer wcrtomb performs as if it writes into an internal buffer which is guaranteed to be large enough.

If wc is the NUL wide character wcrtomb emits, if necessary, a shift sequence to get the state ps into the initial state followed by a single NUL byte is stored in the string s.

Otherwise a byte sequence (possibly including shift sequences) is written into the string s. This of only happens if wc is a valid wide character, i.e., it has a multibyte representation in the character set selected by locale of the LC_CTYPE category. If wc is no valid wide character nothing is stored in the strings s, errno is set to EILSEQ, the conversion state in ps is undefined and the return value is (size_t) -1.

If no error occurred the function returns the number of bytes stored in the string s. This includes all byte representing shift sequences.

One word about the interface of the function: there is no parameter specifying the length of the array s. Instead the function assumes that there are at least MB_CUR_MAX bytes available since this is the maximum length of any byte sequence representing a single character. So the caller has to make sure that there is enough space available, otherwise buffer overruns can occur.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

Using this function is as easy as using mbrtowc. The following example appends a wide character string to a multibyte character string. Again, the code is not really useful (and correct), it is simply here to demonstrate the use and some problems.
char *
mbscatwcs (char *s, size_t len, const wchar_t *ws)
{
  mbstate_t state;
  /* Find the end of the existing string.  */
  char *wp = strchr (s, '\0');
  len -= wp - s;
  memset (&state, '\0', sizeof (state));
  do
    {
      size_t nbytes;
      if (len < MB_CUR_LEN)
        {
          /* We cannot guarantee that the next
             character fits into the buffer, so
             return an error.  */
          errno = E2BIG;
          return NULL;
        }
      nbytes = wcrtomb (wp, *ws, &state);
      if (nbytes == (size_t) -1)
        /* Error in the conversion.  */
        return NULL;
      len -= nbytes;
      wp += nbytes;
    }
  while (*ws++ != L'\0');
  return s;
}
First the function has to find the end of the string currently in the array s. The strchr call does this very efficiently since a requirement for multibyte character representations is that the NUL byte never is used except to represent itself (and in this context, the end of the string).

After initializing the state object the loop is entered where the first task is to make sure there is enough room in the array s. We abort if there are not at least MB_CUR_LEN bytes available. This is not always optimal but we have no other choice. We might have less than MB_CUR_LEN bytes available but the next multibyte character might also be only one byte long. At the time the wcrtomb call returns it is too late to decide whether the buffer was large enough or not. If this solution is really unsuitable there is a very slow but more accurate solution.
  ...
  if (len < MB_CUR_LEN)
    {
      mbstate_t temp_state;
      memcpy (&temp_state, &state, sizeof (state));
      if (wcrtomb (NULL, *ws, &temp_state) > len)
        {
          /* We cannot guarantee that the next
             character fits into the buffer, so
             return an error.  */
          errno = E2BIG;
          return NULL;
        }
    }
  ...
Here we do perform the conversion which might overflow the buffer so that we are afterwards in the position to make an exact decision about the buffer size. Please note the NULL argument for the destination buffer in the new wcrtomb call; since we are not interested in the converted text at this point this is a nice way to express this. The most unusual thing about this piece of code certainly is the duplication of the conversion state object. But think about this: if a change of the state is necessary to emit the next multibyte character we want to have the same shift state change performed in the real conversion. Therefore we have to preserve the initial shift state information.

There are certainly many more and even better solutions to this problem. This example is only meant for educational purposes.

Converting Multibyte and Wide Character Strings

The functions described in the previous section only convert a single character at a time. Most operations to be performed in real-world programs include strings and therefore the ISO C standard also defines conversions on entire strings. However, the defined set of functions is quite limited, thus the GNU C library contains a few extensions which can help in some important situations.

Function: size_t mbsrtowcs (wchar_t *restrict dst, const char **restrict src, size_t len, mbstate_t *restrict ps)
The mbsrtowcs function ("multibyte string restartable to wide character string") converts an NUL terminated multibyte character string at *src into an equivalent wide character string, including the NUL wide character at the end. The conversion is started using the state information from the object pointed to by ps or from an internal object of mbsrtowcs if ps is a null pointer. Before returning the state object to match the state after the last converted character. The state is the initial state if the terminating NUL byte is reached and converted.

If dst is not a null pointer the result is stored in the array pointed to by dst, otherwise the conversion result is not available since it is stored in an internal buffer.

If len wide characters are stored in the array dst before reaching the end of the input string the conversion stops and len is returned. If dst is a null pointer len is never checked.

Another reason for a premature return from the function call is if the input string contains an invalid multibyte sequence. In this case the global variable errno is set to EILSEQ and the function returns (size_t) -1.

In all other cases the function returns the number of wide characters converted during this call. If dst is not null mbsrtowcs stores in the pointer pointed to by src a null pointer (if the NUL byte in the input string was reached) or the address of the byte following the last converted multibyte character.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

The definition of this function has one limitation which has to be understood. The requirement that dst has to be a NUL terminated string provides problems if one wants to convert buffers with text. A buffer is normally no collection of NUL terminated strings but instead a continuous collection of lines, separated by newline characters. Now assume a function to convert one line from a buffer is needed. Since the line is not NUL terminated the source pointer cannot directly point into the unmodified text buffer. This means, either one inserts the NUL byte at the appropriate place for the time of the mbsrtowcs function call (which is not doable for a read-only buffer or in a multi-threaded application) or one copies the line in an extra buffer where it can be terminated by a NUL byte. Note that it is not in general possible to limit the number of characters to convert by setting the parameter len to any specific value. Since it is not known how many bytes each multibyte character sequence is in length one always could do only a guess.

There is still a problem with the method of NUL-terminating a line right after the newline character which could lead to very strange results. As said in the description of the mbsrtowcs function above the conversion state is guaranteed to be in the initial shift state after processing the NUL byte at the end of the input string. But this NUL byte is not really part of the text. I.e., the conversion state after the newline in the original text could be something different than the initial shift state and therefore the first character of the next line is encoded using this state. But the state in question is never accessible to the user since the conversion stops after the NUL byte (which resets the state). Most stateful character sets in use today require that the shift state after a newline is the initial state--but this is not a strict guarantee. Therefore simply NUL terminating a piece of a running text is not always an adequate solution and therefore never should be used in generally used code.

The generic conversion interface (see section Generic Charset Conversion) does not have this limitation (it simply works on buffers, not strings), and the GNU C library contains a set of functions which take additional parameters specifying the maximal number of bytes which are consumed from the input string. This way the problem of mbsrtowcs's example above could be solved by determining the line length and passing this length to the function.

Function: size_t wcsrtombs (char *restrict dst, const wchar_t **restrict src, size_t len, mbstate_t *restrict ps)
The wcsrtombs function ("wide character string restartable to multibyte string") converts the NUL terminated wide character string at *src into an equivalent multibyte character string and stores the result in the array pointed to by dst. The NUL wide character is also converted. The conversion starts in the state described in the object pointed to by ps or by a state object locally to wcsrtombs in case ps is a null pointer. If dst is a null pointer the conversion is performed as usual but the result is not available. If all characters of the input string were successfully converted and if dst is not a null pointer the pointer pointed to by src gets assigned a null pointer.

If one of the wide characters in the input string has no valid multibyte character equivalent the conversion stops early, sets the global variable errno to EILSEQ, and returns (size_t) -1.

Another reason for a premature stop is if dst is not a null pointer and the next converted character would require more than len bytes in total to the array dst. In this case (and if dest is not a null pointer) the pointer pointed to by src is assigned a value pointing to the wide character right after the last one successfully converted.

Except in the case of an encoding error the return value of the function is the number of bytes in all the multibyte character sequences stored in dst. Before returning the state in the object pointed to by ps (or the internal object in case ps is a null pointer) is updated to reflect the state after the last conversion. The state is the initial shift state in case the terminating NUL wide character was converted.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

The restriction mentions above for the mbsrtowcs function applies also here. There is no possibility to directly control the number of input characters. One has to place the NUL wide character at the correct place or control the consumed input indirectly via the available output array size (the len parameter).

Function: size_t mbsnrtowcs (wchar_t *restrict dst, const char **restrict src, size_t nmc, size_t len, mbstate_t *restrict ps)
The mbsnrtowcs function is very similar to the mbsrtowcs function. All the parameters are the same except for nmc which is new. The return value is the same as for mbsrtowcs.

This new parameter specifies how many bytes at most can be used from the multibyte character string. I.e., the multibyte character string *src need not be NUL terminated. But if a NUL byte is found within the nmc first bytes of the string the conversion stops here.

This function is a GNU extensions. It is meant to work around the problems mentioned above. Now it is possible to convert buffer with multibyte character text piece for piece without having to care about inserting NUL bytes and the effect of NUL bytes on the conversion state.

A function to convert a multibyte string into a wide character string and display it could be written like this (this is not a really useful example):
void
showmbs (const char *src, FILE *fp)
{
  mbstate_t state;
  int cnt = 0;
  memset (&state, '\0', sizeof (state));
  while (1)
    {
      wchar_t linebuf[100];
      const char *endp = strchr (src, '\n');
      size_t n;

      /* Exit if there is no more line.  */
      if (endp == NULL)
        break;

      n = mbsnrtowcs (linebuf, &src, endp - src, 99, &state);
      linebuf[n] = L'\0';
      fprintf (fp, "line %d: \"%S\"\n", linebuf);
    }
}
There is no problem with the state after a call to mbsnrtowcs. Since we don't insert characters in the strings which were not in there right from the beginning and we use state only for the conversion of the given buffer there is no problem with altering the state.

Function: size_t wcsnrtombs (char *restrict dst, const wchar_t **restrict src, size_t nwc, size_t len, mbstate_t *restrict ps)
The wcsnrtombs function implements the conversion from wide character strings to multibyte character strings. It is similar to wcsrtombs but it takes, just like mbsnrtowcs, an extra parameter which specifies the length of the input string.

No more than nwc wide characters from the input string *src are converted. If the input string contains a NUL wide character in the first nwc character to conversion stops at this place.

This function is a GNU extension and just like mbsnrtowcs is helps in situations where no NUL terminated input strings are available.

A Complete Multibyte Conversion Example

The example programs given in the last sections are only brief and do not contain all the error checking etc. Presented here is a complete and documented example. It features the mbrtowc function but it should be easy to derive versions using the other functions.
int
file_mbsrtowcs (int input, int output)
{
  /* Note the use of MB_LEN_MAX.
     MB_CUR_MAX cannot portably be used here.  */
  char buffer[BUFSIZ + MB_LEN_MAX];
  mbstate_t state;
  int filled = 0;
  int eof = 0;

  /* Initialize the state.  */
  memset (&state, '\0', sizeof (state));

  while (!eof)
    {
      ssize_t nread;
      ssize_t nwrite;
      char *inp = buffer;
      wchar_t outbuf[BUFSIZ];
      wchar_t *outp = outbuf;

      /* Fill up the buffer from the input file.  */
      nread = read (input, buffer + filled, BUFSIZ);
      if (nread < 0)
        {
          perror ("read");
          return 0;
        }
      /* If we reach end of file, make a note to read no more. */
      if (nread == 0)
        eof = 1;

      /* filled is now the number of bytes in buffer. */
      filled += nread;

      /* Convert those bytes to wide characters--as many as we can. */
      while (1)
        {
          size_t thislen = mbrtowc (outp, inp, filled, &state);
          /* Stop converting at invalid character;
             this can mean we have read just the first part
             of a valid character.  */
          if (thislen == (size_t) -1)
            break;
          /* We want to handle embedded NUL bytes
             but the return value is 0.  Correct this.  */
          if (thislen == 0)
            thislen = 1;
          /* Advance past this character. */
          inp += thislen;
          filled -= thislen;
          ++outp;
        }

      /* Write the wide characters we just made.  */
      nwrite = write (output, outbuf,
                      (outp - outbuf) * sizeof (wchar_t));
      if (nwrite < 0)
        {
          perror ("write");
          return 0;
        }

      /* See if we have a real invalid character. */
      if ((eof && filled > 0) || filled >= MB_CUR_MAX)
        {
          error (0, 0, "invalid multibyte character");
          return 0;
        }

      /* If any characters must be carried forward,
         put them at the beginning of buffer. */
      if (filled > 0)
        memmove (inp, buffer, filled);
    }

  return 1;
}
Non-reentrant Conversion Function

The functions described in the last chapter are defined in Amendment 1 to ISO C90. But the original ISO C90 standard also contained functions for character set conversion. The reason that they are not described in the first place is that they are almost entirely useless.

The problem is that all the functions for conversion defined in ISO C90 use a local state. This implies that multiple conversions at the same time (not only when using threads) cannot be done, and that you cannot first convert single characters and then strings since you cannot tell the conversion functions which state to use.

These functions are therefore usable only in a very limited set of situations. One must complete converting the entire string before starting a new one and each string/text must be converted with the same function (there is no problem with the library itself; it is guaranteed that no library function changes the state of any of these functions). For the above reasons it is highly requested that the functions from the last section are used in place of non-reentrant conversion functions.

Non-reentrant Conversion of Single Characters

Function: int mbtowc (wchar_t *restrict result, const char *restrict string, size_t size)
The mbtowc ("multibyte to wide character") function when called with non-null string converts the first multibyte character beginning at string to its corresponding wide character code. It stores the result in *result.

mbtowc never examines more than size bytes. (The idea is to supply for size the number of bytes of data you have in hand.)

mbtowc with non-null string distinguishes three possibilities: the first size bytes at string start with valid multibyte character, they start with an invalid byte sequence or just part of a character, or string points to an empty string (a null character).

For a valid multibyte character, mbtowc converts it to a wide character and stores that in *result, and returns the number of bytes in that character (always at least @math{1}, and never more than size).

For an invalid byte sequence, mbtowc returns @math{-1}. For an empty string, it returns @math{0}, also storing '\0' in *result.

If the multibyte character code uses shift characters, then mbtowc maintains and updates a shift state as it scans. If you call mbtowc with a null pointer for string, that initializes the shift state to its standard initial value. It also returns nonzero if the multibyte character code in use actually has a shift state. See section States in Non-reentrant Functions.

Function: int wctomb (char *string, wchar_t wchar)
The wctomb ("wide character to multibyte") function converts the wide character code wchar to its corresponding multibyte character sequence, and stores the result in bytes starting at string. At most MB_CUR_MAX characters are stored.

wctomb with non-null string distinguishes three possibilities for wchar: a valid wide character code (one that can be translated to a multibyte character), an invalid code, and L'\0'.

Given a valid code, wctomb converts it to a multibyte character, storing the bytes starting at string. Then it returns the number of bytes in that character (always at least @math{1}, and never more than MB_CUR_MAX).

If wchar is an invalid wide character code, wctomb returns @math{-1}. If wchar is L'\0', it returns 0, also storing '\0' in *string.

If the multibyte character code uses shift characters, then wctomb maintains and updates a shift state as it scans. If you call wctomb with a null pointer for string, that initializes the shift state to its standard initial value. It also returns nonzero if the multibyte character code in use actually has a shift state. See section States in Non-reentrant Functions.

Calling this function with a wchar argument of zero when string is not null has the side-effect of reinitializing the stored shift state as well as storing the multibyte character '\0' and returning @math{0}.

Similar to mbrlen there is also a non-reentrant function which computes the length of a multibyte character. It can be defined in terms of mbtowc.

Function: int mblen (const char *string, size_t size)
The mblen function with a non-null string argument returns the number of bytes that make up the multibyte character beginning at string, never examining more than size bytes. (The idea is to supply for size the number of bytes of data you have in hand.)

The return value of mblen distinguishes three possibilities: the first size bytes at string start with valid multibyte character, they start with an invalid byte sequence or just part of a character, or string points to an empty string (a null character).

For a valid multibyte character, mblen returns the number of bytes in that character (always at least 1, and never more than size). For an invalid byte sequence, mblen returns @math{-1}. For an empty string, it returns @math{0}.

If the multibyte character code uses shift characters, then mblen maintains and updates a shift state as it scans. If you call mblen with a null pointer for string, that initializes the shift state to its standard initial value. It also returns a nonzero value if the multibyte character code in use actually has a shift state. See section States in Non-reentrant Functions.

The function mblen is declared in `stdlib.h'.

Non-reentrant Conversion of Strings

For convenience reasons the ISO C90 standard defines also functions to convert entire strings instead of single characters. These functions suffer from the same problems as their reentrant counterparts from Amendment 1 to ISO C90; see section Converting Multibyte and Wide Character Strings.

Function: size_t mbstowcs (wchar_t *wstring, const char *string, size_t size)
The mbstowcs ("multibyte string to wide character string") function converts the null-terminated string of multibyte characters string to an array of wide character codes, storing not more than size wide characters into the array beginning at wstring. The terminating null character counts towards the size, so if size is less than the actual number of wide characters resulting from string, no terminating null character is stored.

The conversion of characters from string begins in the initial shift state.

If an invalid multibyte character sequence is found, this function returns a value of @math{-1}. Otherwise, it returns the number of wide characters stored in the array wstring. This number does not include the terminating null character, which is present if the number is less than size.

Here is an example showing how to convert a string of multibyte characters, allocating enough space for the result.
wchar_t *
mbstowcs_alloc (const char *string)
{
  size_t size = strlen (string) + 1;
  wchar_t *buf = xmalloc (size * sizeof (wchar_t));

  size = mbstowcs (buf, string, size);
  if (size == (size_t) -1)
    return NULL;
  buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
  return buf;
}
Function: size_t wcstombs (char *string, const wchar_t *wstring, size_t size)
The wcstombs ("wide character string to multibyte string") function converts the null-terminated wide character array wstring into a string containing multibyte characters, storing not more than size bytes starting at string, followed by a terminating null character if there is room. The conversion of characters begins in the initial shift state.

The terminating null character counts towards the size, so if size is less than or equal to the number of bytes needed in wstring, no terminating null character is stored.

If a code that does not correspond to a valid multibyte character is found, this function returns a value of @math{-1}. Otherwise, the return value is the number of bytes stored in the array string. This number does not include the terminating null character, which is present if the number is less than size.

States in Non-reentrant Functions

In some multibyte character codes, the meaning of any particular byte sequence is not fixed; it depends on what other sequences have come earlier in the same string. Typically there are just a few sequences that can change the meaning of other sequences; these few are called shift sequences and we say that they set the shift state for other sequences that follow.

To illustrate shift state and shift sequences, suppose we decide that the sequence 0200 (just one byte) enters Japanese mode, in which pairs of bytes in the range from 0240 to 0377 are single characters, while 0201 enters Latin-1 mode, in which single bytes in the range from 0240 to 0377 are characters, and interpreted according to the ISO Latin-1 character set. This is a multibyte code which has two alternative shift states ("Japanese mode" and "Latin-1 mode"), and two shift sequences that specify particular shift states.

When the multibyte character code in use has shift states, then mblen, mbtowc and wctomb must maintain and update the current shift state as they scan the string. To make this work properly, you must follow these rules:

Before starting to scan a string, call the function with a null pointer for the multibyte character address--for example, mblen (NULL, 0). This initializes the shift state to its standard initial value.
Scan the string one character at a time, in order. Do not "back up" and rescan characters already scanned, and do not intersperse the processing of different strings.

Here is an example of using mblen following these rules:
void
scan_string (char *s)
{
  int length = strlen (s);

  /* Initialize shift state.  */
  mblen (NULL, 0);

  while (1)
    {
      int thischar = mblen (s, length);
      /* Deal with end of string and invalid characters.  */
      if (thischar == 0)
        break;
      if (thischar == -1)
        {
          error ("invalid multibyte character");
          break;
        }
      /* Advance past this character.  */
      s += thischar;
      length -= thischar;
    }
}
The functions mblen, mbtowc and wctomb are not reentrant when using a multibyte code that uses a shift state. However, no other library functions call these functions, so you don't have to worry that the shift state will be changed mysteriously.

Generic Charset Conversion

The conversion functions mentioned so far in this chapter all had in common that they operate on character sets which are not directly specified by the functions. The multibyte encoding used is specified by the currently selected locale for the LC_CTYPE category. The wide character set is fixed by the implementation (in the case of GNU C library it always is UCS-4 encoded ISO 10646.

This has of course several problems when it comes to general character conversion:

For every conversion where neither the source or destination character set is the character set of the locale for the LC_CTYPE category, one has to change the LC_CTYPE locale using setlocale. This introduces major problems for the rest of the programs since several more functions (e.g., the character classification functions, see section Classification of Characters) use the LC_CTYPE category.
Parallel conversions to and from different character sets are not possible since the LC_CTYPE selection is global and shared by all threads.
If neither the source nor the destination character set is the character set used for wchar_t representation there is at least a two-step process necessary to convert a text using the functions above. One would have to select the source character set as the multibyte encoding, convert the text into a wchar_t text, select the destination character set as the multibyte encoding and convert the wide character text to the multibyte (@math{=} destination) character set. Even if this is possible (which is not guaranteed) it is a very tiring work. Plus it suffers from the other two raised points even more due to the steady changing of the locale.

The XPG2 standard defines a completely new set of functions which has none of these limitations. They are not at all coupled to the selected locales and they but no constraints on the character sets selected for source and destination. Only the set of available conversions is limiting them. The standard does not specify that any conversion at all must be available. It is a measure of the quality of the implementation.

In the following text first the interface to iconv, the conversion function, will be described. Comparisons with other implementations will show what pitfalls lie on the way of portable applications. At last, the implementation is described as far as interesting to the advanced user who wants to extend the conversion capabilities.

Generic Character Set Conversion Interface

This set of functions follows the traditional cycle of using a resource: open--use--close. The interface consists of three functions, each of which implement one step.

Before the interfaces are described it is necessary to introduce a datatype. Just like other open--use--close interface the functions introduced here work using a handles and the `iconv.h' header defines a special type for the handles used.

Data Type: iconv_t
This data type is an abstract type defined in `iconv.h'. The user must not assume anything about the definition of this type, it must be completely opaque.

Objects of this type can get assigned handles for the conversions using the iconv functions. The objects themselves need not be freed but the conversions for which the handles stand for have to.

The first step is the function to create a handle.

Function: iconv_t iconv_open (const char *tocode, const char *fromcode)
The iconv_open function has to be used before starting a conversion. The two parameters this function takes determine the source and destination character set for the conversion and if the implementation has the possibility to perform such a conversion the function returns a handle.

If the wanted conversion is not available the function returns (iconv_t) -1. In this case the global variable errno can have the following values:

EMFILE
The process already has OPEN_MAX file descriptors open.
ENFILE
The system limit of open file is reached.
ENOMEM
Not enough memory to carry out the operation.
EINVAL
The conversion from fromcode to tocode is not supported.
It is not possible to use the same descriptor in different threads to perform independent conversions. Within the data structures associated with the descriptor there is information about the conversion state. This must not be messed up by using it in different conversions.

An iconv descriptor is like a file descriptor as for every use a new descriptor must be created. The descriptor does not stand for all of the conversions from fromset to toset.

The GNU C library implementation of iconv_open has one significant extension to other implementations. To ease the extension of the set of available conversions the implementation allows storing the necessary files with data and code in arbitrarily many directories. How this extension has to be written will be explained below (see section The iconv Implementation in the GNU C library). Here it is only important to say that all directories mentioned in the GCONV_PATH environment variable are considered if they contain a file `gconv-modules'. These directories need not necessarily be created by the system administrator. In fact, this extension is introduced to help users writing and using their own, new conversions. Of course this does not work for security reasons in SUID binaries; in this case only the system directory is considered and this normally is `prefix/lib/gconv'. The GCONV_PATH environment variable is examined exactly once at the first call of the iconv_open function. Later modifications of the variable have no effect.

This function got introduced early in the X/Open Portability Guide, version 2. It is supported by all commercial Unices as it is required for the Unix branding. However, the quality and completeness of the implementation varies widely. The function is declared in `iconv.h'.

The iconv implementation can associate large data structure with the handle returned by iconv_open. Therefore it is crucial to free all the resources once all conversions are carried out and the conversion is not needed anymore.

Function: int iconv_close (iconv_t cd)
The iconv_close function frees all resources associated with the handle cd which must have been returned by a successful call to the iconv_open function.

If the function call was successful the return value is @math{0}. Otherwise it is @math{-1} and errno is set appropriately. Defined error are:

EBADF
The conversion descriptor is invalid.
This function was introduced together with the rest of the iconv functions in XPG2 and it is declared in `iconv.h'.

The standard defines only one actual conversion function. This has therefore the most general interface: it allows conversion from one buffer to another. Conversion from a file to a buffer, vice versa, or even file to file can be implemented on top of it.

Function: size_t iconv (iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft)
The iconv function converts the text in the input buffer according to the rules associated with the descriptor cd and stores the result in the output buffer. It is possible to call the function for the same text several times in a row since for stateful character sets the necessary state information is kept in the data structures associated with the descriptor.

The input buffer is specified by *inbuf and it contains *inbytesleft bytes. The extra indirection is necessary for communicating the used input back to the caller (see below). It is important to note that the buffer pointer is of type char and the length is measured in bytes even if the input text is encoded in wide characters.

The output buffer is specified in a similar way. *outbuf points to the beginning of the buffer with at least *outbytesleft bytes room for the result. The buffer pointer again is of type char and the length is measured in bytes. If outbuf or *outbuf is a null pointer the conversion is performed but no output is available.

If inbuf is a null pointer the iconv function performs the necessary action to put the state of the conversion into the initial state. This is obviously a no-op for non-stateful encodings, but if the encoding has a state such a function call might put some byte sequences in the output buffer which perform the necessary state changes. The next call with inbuf not being a null pointer then simply goes on from the initial state. It is important that the programmer never makes any assumption on whether the conversion has to deal with states or not. Even if the input and output character sets are not stateful the implementation might still have to keep states. This is due to the implementation chosen for the GNU C library as it is described below. Therefore an iconv call to reset the state should always be performed if some protocol requires this for the output text.

The conversion stops for three reasons. The first is that all characters from the input buffer are converted. This actually can mean two things: really all bytes from the input buffer are consumed or there are some bytes at the end of the buffer which possibly can form a complete character but the input is incomplete. The second reason for a stop is when the output buffer is full. And the third reason is that the input contains invalid characters.

In all these cases the buffer pointers after the last successful conversion, for input and output buffer, are stored in inbuf and outbuf and the available room in each buffer is stored in inbytesleft and outbytesleft.

Since the character sets selected in the iconv_open call can be almost arbitrary there can be situations where the input buffer contains valid characters which have no identical representation in the output character set. The behavior in this situation is undefined. The current behavior of the GNU C library in this situation is to return with an error immediately. This certainly is not the most desirable solution. Therefore future versions will provide better ones but they are not yet finished.

If all input from the input buffer is successfully converted and stored in the output buffer the function returns the number of non-reversible conversions performed. In all other cases the return value is (size_t) -1 and errno is set appropriately. In this case the value pointed to by inbytesleft is nonzero.

EILSEQ
The conversion stopped because of an invalid byte sequence in the input. After the call *inbuf points at the first byte of the invalid byte sequence.
E2BIG
The conversion stopped because it ran out of space in the output buffer.
EINVAL
The conversion stopped because of an incomplete byte sequence at the end of the input buffer.
EBADF
The cd argument is invalid.
This function was introduced in the XPG2 standard and is declared in the `iconv.h' header.

The definition of the iconv function is quite good overall. It provides quite flexible functionality. The only problems lie in the boundary cases which are incomplete byte sequences at the end of the input buffer and invalid input. A third problem, which is not really a design problem, is the way conversions are selected. The standard does not say anything about the legitimate names, a minimal set of available conversions. We will see how this negatively impacts other implementations, as is demonstrated below.

A complete iconv example

The example below features a solution for a common problem. Given that one knows the internal encoding used by the system for wchar_t strings one often is in the position to read text from a file and store it in wide character buffers. One can do this using mbsrtowcs but then we run into the problems discussed above.
int
file2wcs (int fd, const char *charset, wchar_t *outbuf, size_t avail)
{
  char inbuf[BUFSIZ];
  size_t insize = 0;
  char *wrptr = (char *) outbuf;
  int result = 0;
  iconv_t cd;

  cd = iconv_open ("WCHAR_T", charset);
  if (cd == (iconv_t) -1)
    {
      /* Something went wrong.  */
      if (errno == EINVAL)
        error (0, 0, "conversion from '%s' to wchar_t not available",
               charset);
      else
        perror ("iconv_open");

      /* Terminate the output string.  */
      *outbuf = L'\0';

      return -1;
    }

  while (avail > 0)
    {
      size_t nread;
      size_t nconv;
      char *inptr = inbuf;

      /* Read more input.  */
      nread = read (fd, inbuf + insize, sizeof (inbuf) - insize);
      if (nread == 0)
        {
          /* When we come here the file is completely read.
             This still could mean there are some unused
             characters in the inbuf.  Put them back.  */
          if (lseek (fd, -insize, SEEK_CUR) == -1)
            result = -1;

          /* Now write out the byte sequence to get into the
             initial state if this is necessary.  */
          iconv (cd, NULL, NULL, &wrptr, &avail);

          break;
        }
      insize += nread;

      /* Do the conversion.  */
      nconv = iconv (cd, &inptr, &insize, &wrptr, &avail);
      if (nconv == (size_t) -1)
        {
          /* Not everything went right.  It might only be
             an unfinished byte sequence at the end of the
             buffer.  Or it is a real problem.  */
          if (errno == EINVAL)
            /* This is harmless.  Simply move the unused
               bytes to the beginning of the buffer so that
               they can be used in the next round.  */
            memmove (inbuf, inptr, insize);
          else
            {
              /* It is a real problem.  Maybe we ran out of
                 space in the output buffer or we have invalid
                 input.  In any case back the file pointer to
                 the position of the last processed byte.  */
              lseek (fd, -insize, SEEK_CUR);
              result = -1;
              break;
            }
        }
    }

  /* Terminate the output string.  */
  if (avail >= sizeof (wchar_t))
    *((wchar_t *) wrptr) = L'\0';

  if (iconv_close (cd) != 0)
    perror ("iconv_close");

  return (wchar_t *) wrptr - outbuf;
}
This example shows the most important aspects of using the iconv functions. It shows how successive calls to iconv can be used to convert large amounts of text. The user does not have to care about stateful encodings as the functions take care of everything.

An interesting point is the case where iconv return an error and errno is set to EINVAL. This is not really an error in the transformation. It can happen whenever the input character set contains byte sequences of more than one byte for some character and texts are not processed in one piece. In this case there is a chance that a multibyte sequence is cut. The caller than can simply read the remainder of the takes and feed the offending bytes together with new character from the input to iconv and continue the work. The internal state kept in the descriptor is not unspecified after such an event as it is the case with the conversion functions from the ISO C standard.

The example also shows the problem of using wide character strings with iconv. As explained in the description of the iconv function above the function always takes a pointer to a char array and the available space is measured in bytes. In the example the output buffer is a wide character buffer. Therefore we use a local variable wrptr of type char * which is used in the iconv calls.

This looks rather innocent but can lead to problems on platforms which have tight restriction on alignment. Therefore the caller of iconv has to make sure that the pointers passed are suitable for access of characters from the appropriate character set. Since in the above case the input parameter to the function is a wchar_t pointer this is the case (unless the user violates alignment when computing the parameter). But in other situations, especially when writing generic functions where one does not know what type of character set one uses and therefore treats text as a sequence of bytes, it might become tricky.

Some Details about other iconv Implementations

This is not really the place to discuss the iconv implementation of other systems but it is necessary to know a bit about them to write portable programs. The above mentioned problems with the specification of the iconv functions can lead to portability issues.

The first thing to notice is that due to the large number of character sets in use it is certainly not practical to encode the conversions directly in the C library. Therefore the conversion information must come from files outside the C library. This is usually done in one or both of the following ways:

The C library contains a set of generic conversion functions which can read the needed conversion tables and other information from data files. These files get loaded when necessary. This solution is problematic as it requires a great deal of effort to apply to all character sets (potentially an infinite set). The differences in the structure of the different character sets is so large that many different variants of the table processing functions must be developed. On top of this the generic nature of these functions make them slower than specifically implemented functions.
The C library only contains a framework which can dynamically load object files and execute the therein contained conversion functions. This solution provides much more flexibility. The C library itself contains only very little code and therefore reduces the general memory footprint. Also, with a documented interface between the C library and the loadable modules it is possible for third parties to extend the set of available conversion modules. A drawback of this solution is that dynamic loading must be available.

Some implementations in commercial Unices implement a mixture of these these possibilities, the majority only the second solution. Using loadable modules moves the code out of the library itself and keeps the door open for extensions and improvements. But this design is also limiting on some platforms since not many platforms support dynamic loading in statically linked programs. On platforms without his capability it is therefore not possible to use this interface in statically linked programs. The GNU C library has on ELF platforms no problems with dynamic loading in in these situations and therefore this point is moot. The danger is that one gets acquainted with this and forgets about the restrictions on other systems.

A second thing to know about other iconv implementations is that the number of available conversions is often very limited. Some implementations provide in the standard release (not special international or developer releases) at most 100 to 200 conversion possibilities. This does not mean 200 different character sets are supported. E.g., conversions from one character set to a set of, say, 10 others counts as 10 conversion. Together with the other direction this makes already 20. One can imagine the thin coverage these platform provide. Some Unix vendors even provide only a handful of conversions which renders them useless for almost all uses.

This directly leads to a third and probably the most problematic point. The way the iconv conversion functions are implemented on all known Unix system and the availability of the conversion functions from character set @math{@cal{A}} to @math{@cal{B}} and the conversion from @math{@cal{B}} to @math{@cal{C}} does not imply that the conversion from @math{@cal{A}} to @math{@cal{C}} is available.

This might not seem unreasonable and problematic at first but it is a quite big problem as one will notice shortly after hitting it. To show the problem we assume to write a program which has to convert from @math{@cal{A}} to @math{@cal{C}}. A call like
cd = iconv_open ("@math{@cal{C}}", "@math{@cal{A}}");
does fail according to the assumption above. But what does the program do now? The conversion is really necessary and therefore simply giving up is no possibility.

This is a nuisance. The iconv function should take care of this. But how should the program proceed from here on? If it would try to convert to character set @math{@cal{B}} first the two iconv_open calls
cd1 = iconv_open ("@math{@cal{B}}", "@math{@cal{A}}");
and
cd2 = iconv_open ("@math{@cal{C}}", "@math{@cal{B}}");
will succeed but how to find @math{@cal{B}}?

Unfortunately, the answer is: there is no general solution. On some systems guessing might help. On those systems most character sets can convert to and from UTF-8 encoded ISO 10646 or Unicode text. Beside this only some very system-specific methods can help. Since the conversion functions come from loadable modules and these modules must be stored somewhere in the filesystem, one could try to find them and determine from the available file which conversions are available and whether there is an indirect route from @math{@cal{A}} to @math{@cal{C}}.

This shows one of the design errors of iconv mentioned above. It should at least be possible to determine the list of available conversion programmatically so that if iconv_open says there is no such conversion, one could make sure this also is true for indirect routes.

The iconv Implementation in the GNU C library

After reading about the problems of iconv implementations in the last section it is certainly good to note that the implementation in the GNU C library has none of the problems mentioned above. What follows is a step-by-step analysis of the points raised above. The evaluation is based on the current state of the development (as of January 1999). The development of the iconv functions is not complete, but basic functionality has solidified.

The GNU C library's iconv implementation uses shared loadable modules to implement the conversions. A very small number of conversions are built into the library itself but these are only rather trivial conversions.

All the benefits of loadable modules are available in the GNU C library implementation. This is especially appealing since the interface is well documented (see below) and it therefore is easy to write new conversion modules. The drawback of using loadable objects is not a problem in the GNU C library, at least on ELF systems. Since the library is able to load shared objects even in statically linked binaries this means that static linking needs not to be forbidden in case one wants to use iconv.

The second mentioned problem is the number of supported conversions. Currently, the GNU C library supports more than 150 character sets. The way the implementation is designed the number of supported conversions is greater than 22350 (@math{150} times @math{149}). If any conversion from or to a character set is missing it can easily be added.

Particularly impressive as it may be, this high number is due to the fact that the GNU C library implementation of iconv does not have the third problem mentioned above. I.e., whenever there is a conversion from a character set @math{@cal{A}} to @math{@cal{B}} and from @math{@cal{B}} to @math{@cal{C}} it is always possible to convert from @math{@cal{A}} to @math{@cal{C}} directly. If the iconv_open returns an error and sets errno to EINVAL this really means there is no known way, directly or indirectly, to perform the wanted conversion.

This is achieved by providing for each character set a conversion from and to UCS-4 encoded ISO 10646. Using ISO 10646 as an intermediate representation it is possible to triangulate, i.e., converting with an intermediate representation.

There is no inherent requirement to provide a conversion to ISO 10646 for a new character set and it is also possible to provide other conversions where neither source nor destination character set is ISO 10646. The currently existing set of conversions is simply meant to cover all conversions which might be of interest.

All currently available conversions use the triangulation method above, making conversion run unnecessarily slow. If, e.g., somebody often needs the conversion from ISO-2022-JP to EUC-JP, a quicker solution would involve direct conversion between the two character sets, skipping the input to ISO 10646 first. The two character sets of interest are much more similar to each other than to ISO 10646.

In such a situation one can easy write a new conversion and provide it as a better alternative. The GNU C library iconv implementation would automatically use the module implementing the conversion if it is specified to be more efficient.

Format of `gconv-modules' files

All information about the available conversions comes from a file named `gconv-modules' which can be found in any of the directories along the GCONV_PATH. The `gconv-modules' files are line-oriented text files, where each of the lines has one of the following formats:

If the first non-whitespace character is a # the line contains only comments and is ignored.
Lines starting with alias define an alias name for a character set. There are two more words expected on the line. The first one defines the alias name and the second defines the original name of the character set. The effect is that it is possible to use the alias name in the fromset or toset parameters of iconv_open and achieve the same result as when using the real character set name. This is quite important as a character set has often many different names. There is normally always an official name but this need not correspond to the most popular name. Beside this many character sets have special names which are somehow constructed. E.g., all character sets specified by the ISO have an alias of the form ISO-IR-nnn where nnn is the registration number. This allows programs which know about the registration number to construct character set names and use them in iconv_open calls. More on the available names and aliases follows below.
Lines starting with module introduce an available conversion module. These lines must contain three or four more words. The first word specifies the source character set, the second word the destination character set of conversion implemented in this module. The third word is the name of the loadable module. The filename is constructed by appending the usual shared object suffix (normally `.so') and this file is then supposed to be found in the same directory the `gconv-modules' file is in. The last word on the line, which is optional, is a numeric value representing the cost of the conversion. If this word is missing a cost of @math{1} is assumed. The numeric value itself does not matter that much; what counts are the relative values of the sums of costs for all possible conversion paths. Below is a more precise description of the use of the cost value.

Returning to the example above where one has written a module to directly convert from ISO-2022-JP to EUC-JP and back. All what has to be done is to put the new module, be its name ISO2022JP-EUCJP.so, in a directory and add a file `gconv-modules' with the following content in the same directory:
module  ISO-2022-JP//   EUC-JP//        ISO2022JP-EUCJP    1
module  EUC-JP//        ISO-2022-JP//   ISO2022JP-EUCJP    1
To see why this is sufficient, it is necessary to understand how the conversion used by iconv (and described in the descriptor) is selected. The approach to this problem is quite simple.

At the first call of the iconv_open function the program reads all available `gconv-modules' files and builds up two tables: one containing all the known aliases and another which contains the information about the conversions and which shared object implements them.

Finding the conversion path in iconv

The set of available conversions form a directed graph with weighted edges. The weights on the edges are the costs specified in the `gconv-modules' files. The iconv_open function uses an algorithm suitable for search for the best path in such a graph and so constructs a list of conversions which must be performed in succession to get the transformation from the source to the destination character set.

Explaining why the above `gconv-modules' files allows the iconv implementation to resolve the specific ISO-2022-JP to EUC-JP conversion module instead of the conversion coming with the library itself is straightforward. Since the latter conversion takes two steps (from ISO-2022-JP to ISO 10646 and then from ISO 10646 to EUC-JP) the cost is @math{1+1 = 2}. But the above `gconv-modules' file specifies that the new conversion modules can perform this conversion with only the cost of @math{1}.

A mysterious piece about the `gconv-modules' file above (and also the file coming with the GNU C library) are the names of the character sets specified in the module lines. Why do almost all the names end in //? And this is not all: the names can actually be regular expressions. At this point of time this mystery should not be revealed, unless you have the relevant spell-casting materials: ashes from an original DOS 6.2 boot disk burnt in effigy, a crucifix blessed by St. Emacs, assorted herbal roots from Central America, sand from Cebu, etc. Sorry! The part of the implementation where this is used is not yet finished. For now please simply follow the existing examples. It'll become clearer once it is. --drepper

A last remark about the `gconv-modules' is about the names not ending with //. There often is a character set named INTERNAL mentioned. From the discussion above and the chosen name it should have become clear that this is the name for the representation used in the intermediate step of the triangulation. We have said that this is UCS-4 but actually it is not quite right. The UCS-4 specification also includes the specification of the byte ordering used. Since a UCS-4 value consists of four bytes a stored value is effected by byte ordering. The internal representation is not the same as UCS-4 in case the byte ordering of the processor (or at least the running process) is not the same as the one required for UCS-4. This is done for performance reasons as one does not want to perform unnecessary byte-swapping operations if one is not interested in actually seeing the result in UCS-4. To avoid trouble with endianess the internal representation consistently is named INTERNAL even on big-endian systems where the representations are identical.

iconv module data structures

So far this section described how modules are located and considered to be used. What remains to be described is the interface of the modules so that one can write new ones. This section describes the interface as it is in use in January 1999. The interface will change in future a bit but hopefully only in an upward compatible way.

The definitions necessary to write new modules are publicly available in the non-standard header `gconv.h'. The following text will therefore describe the definitions from this header file. But first it is necessary to get an overview.

From the perspective of the user of iconv the interface is quite simple: the iconv_open function returns a handle which can be used in calls to iconv and finally the handle is freed with a call to iconv_close. The problem is: the handle has to be able to represent the possibly long sequences of conversion steps and also the state of each conversion since the handle is all which is passed to the iconv function. Therefore the data structures are really the elements to understanding the implementation.

We need two different kinds of data structures. The first describes the conversion and the second describes the state etc. There are really two type definitions like this in `gconv.h'.

Data type: struct __gconv_step
This data structure describes one conversion a module can perform. For each function in a loaded module with conversion functions there is exactly one object of this type. This object is shared by all users of the conversion. I.e., this object does not contain any information corresponding to an actual conversion. It only describes the conversion itself.

struct __gconv_loaded_object *__shlib_handle

const char *__modname

int __counter
All these elements of the structure are used internally in the C library to coordinate loading and unloading the shared. One must not expect any of the other elements be available or initialized.
const char *__from_name

const char *__to_name
__from_name and __to_name contain the names of the source and destination character sets. They can be used to identify the actual conversion to be carried out since one module might implement conversions for more than one character set and/or direction.
gconv_fct __fct

gconv_init_fct __init_fct

gconv_end_fct __end_fct
These elements contain pointers to the functions in the loadable module. The interface will be explained below.
int __min_needed_from

int __max_needed_from

int __min_needed_to

int __max_needed_to;
These values have to be filled in the init function of the module. The __min_needed_from value specifies how many bytes a character of the source character set at least needs. The __max_needed_from specifies the maximum value which also includes possible shift sequences. The __min_needed_to and __max_needed_to values serve the same purpose but this time for the destination character set. It is crucial that these values are accurate since otherwise the conversion functions will have problems or not work at all.
int __stateful
This element must also be initialized by the init function. It is nonzero if the source character set is stateful. Otherwise it is zero.
void *__data
This element can be used freely by the conversion functions in the module. It can be used to communicate extra information from one call to another. It need not be initialized if not needed at all. If this element gets assigned a pointer to dynamically allocated memory (presumably in the init function) it has to be made sure that the end function deallocates the memory. Otherwise the application will leak memory. It is important to be aware that this data structure is shared by all users of this specification conversion and therefore the __data element must not contain data specific to one specific use of the conversion function.

Data type: struct __gconv_step_data
This is the data structure which contains the information specific to each use of the conversion functions.

char *__outbuf

char *__outbufend
These elements specify the output buffer for the conversion step. The __outbuf element points to the beginning of the buffer and __outbufend points to the byte following the last byte in the buffer. The conversion function must not assume anything about the size of the buffer but it can be safely assumed the there is room for at least one complete character in the output buffer. Once the conversion is finished and the conversion is the last step the __outbuf element must be modified to point after last last byte written into the buffer to signal how much output is available. If this conversion step is not the last one the element must not be modified. The __outbufend element must not be modified.
int __is_last
This element is nonzero if this conversion step is the last one. This information is necessary for the recursion. See the description of the conversion function internals below. This element must never be modified.
int __invocation_counter
The conversion function can use this element to see how many calls of the conversion function already happened. Some character sets require when generating output a certain prolog and by comparing this value with zero one can find out whether it is the first call and therefore the prolog should be emitted or not. This element must never be modified.
int __internal_use
This element is another one rarely used but needed in certain situations. It got assigned a nonzero value in case the conversion functions are used to implement mbsrtowcs et.al. I.e., the function is not used directly through the iconv interface. This sometimes makes a difference as it is expected that the iconv functions are used to translate entire texts while the mbsrtowcs functions are normally only used to convert single strings and might be used multiple times to convert entire texts. But in this situation we would have problem complying with some rules of the character set specification. Some character sets require a prolog which must appear exactly once for an entire text. If a number of mbsrtowcs calls are used to convert the text only the first call must add the prolog. But since there is no communication between the different calls of mbsrtowcs the conversion functions have no possibility to find this out. The situation is different for sequences of iconv calls since the handle allows access to the needed information. This element is mostly used together with __invocation_counter in a way like this:
if (!data->__internal_use
     && data->__invocation_counter == 0)
  /* Emit prolog.  */
  ...
This element must never be modified.
mbstate_t *__statep
The __statep element points to an object of type mbstate_t (see section Representing the state of the conversion). The conversion of an stateful character set must use the object pointed to by this element to store information about the conversion state. The __statep element itself must never be modified.
mbstate_t __state
This element never must be used directly. It is only part of this structure to have the needed space allocated.
iconv module interfaces

With the knowledge about the data structures we now can describe the conversion functions itself. To understand the interface a bit of knowledge about the functionality in the C library which loads the objects with the conversions is necessary.

It is often the case that one conversion is used more than once. I.e., there are several iconv_open calls for the same set of character sets during one program run. The mbsrtowcs et.al. functions in the GNU C library also use the iconv functionality which increases the number of uses of the same functions even more.

For this reason the modules do not get loaded exclusively for one conversion. Instead a module once loaded can be used by arbitrarily many iconv or mbsrtowcs calls at the same time. The splitting of the information between conversion function specific information and conversion data makes this possible. The last section showed the two data structures used to do this.

This is of course also reflected in the interface and semantics of the functions the modules must provide. There are three functions which must have the following names:

gconv_init
The gconv_init function initializes the conversion function specific data structure. This very same object is shared by all conversion which use this conversion and therefore no state information about the conversion itself must be stored in here. If a module implements more than one conversion the gconv_init function will be called multiple times.
gconv_end
The gconv_end function is responsible to free all resources allocated by the gconv_init function. If there is nothing to do this function can be missing. Special care must be taken if the module implements more than one conversion and the gconv_init function does not allocate the same resources for all conversions.
gconv
This is the actual conversion function. It is called to convert one block of text. It gets passed the conversion step information initialized by gconv_init and the conversion data, specific to this use of the conversion functions.
There are three data types defined for the three module interface function and these define the interface.

Data type: int (*__gconv_init_fct) (struct __gconv_step *)
This specifies the interface of the initialization function of the module. It is called exactly once for each conversion the module implements.

As explained int the description of the struct __gconv_step data structure above the initialization function has to initialize parts of it.

__min_needed_from

__max_needed_from

__min_needed_to

__max_needed_to
These elements must be initialized to the exact numbers of the minimum and maximum number of bytes used by one character in the source and destination character set respectively. If the characters all have the same size the minimum and maximum values are the same.
__stateful
This element must be initialized to an nonzero value if the source character set is stateful. Otherwise it must be zero.
If the initialization function needs to communication some information to the conversion function this can happen using the __data element of the __gconv_step structure. But since this data is shared by all the conversion is must not be modified by the conversion function. How this can be used is shown in the example below.
#define MIN_NEEDED_FROM         1
#define MAX_NEEDED_FROM         4
#define MIN_NEEDED_TO           4
#define MAX_NEEDED_TO           4

int
gconv_init (struct __gconv_step *step)
{
  /* Determine which direction.  */
  struct iso2022jp_data *new_data;
  enum direction dir = illegal_dir;
  enum variant var = illegal_var;
  int result;

  if (__strcasecmp (step->__from_name, "ISO-2022-JP//") == 0)
    {
      dir = from_iso2022jp;
      var = iso2022jp;
    }
  else if (__strcasecmp (step->__to_name, "ISO-2022-JP//") == 0)
    {
      dir = to_iso2022jp;
      var = iso2022jp;
    }
  else if (__strcasecmp (step->__from_name, "ISO-2022-JP-2//") == 0)
    {
      dir = from_iso2022jp;
      var = iso2022jp2;
    }
  else if (__strcasecmp (step->__to_name, "ISO-2022-JP-2//") == 0)
    {
      dir = to_iso2022jp;
      var = iso2022jp2;
    }

  result = __GCONV_NOCONV;
  if (dir != illegal_dir)
    {
      new_data = (struct iso2022jp_data *)
        malloc (sizeof (struct iso2022jp_data));

      result = __GCONV_NOMEM;
      if (new_data != NULL)
        {
          new_data->dir = dir;
          new_data->var = var;
          step->__data = new_data;

          if (dir == from_iso2022jp)
        {
              step->__min_needed_from = MIN_NEEDED_FROM;
              step->__max_needed_from = MAX_NEEDED_FROM;
              step->__min_needed_to = MIN_NEEDED_TO;
              step->__max_needed_to = MAX_NEEDED_TO;
        }
          else
            {
              step->__min_needed_from = MIN_NEEDED_TO;
              step->__max_needed_from = MAX_NEEDED_TO;
              step->__min_needed_to = MIN_NEEDED_FROM;
              step->__max_needed_to = MAX_NEEDED_FROM + 2;
            }

          /* Yes, this is a stateful encoding.  */
          step->__stateful = 1;

          result = __GCONV_OK;
        }
    }

  return result;
}
The function first checks which conversion is wanted. The module from which this function is taken implements four different conversion and which one is selected can be determined by comparing the names. The comparison should always be done without paying attention to the case.

Then a data structure is allocated which contains the necessary information about which conversion is selected. The data structure struct iso2022jp_data is locally defined since outside the module this data is not used at all. Please note that if all four conversions this modules supports are requested there are four data blocks.

One interesting thing is the initialization of the __min_ and __max_ elements of the step data object. A single ISO-2022-JP character can consist of one to four bytes. Therefore the MIN_NEEDED_FROM and MAX_NEEDED_FROM macros are defined this way. The output is always the INTERNAL character set (aka UCS-4) and therefore each character consists of exactly four bytes. For the conversion from INTERNAL to ISO-2022-JP we have to take into account that escape sequences might be necessary to switch the character sets. Therefore the __max_needed_to element for this direction gets assigned MAX_NEEDED_FROM + 2. This takes into account the two bytes needed for the escape sequences to single the switching. The asymmetry in the maximum values for the two directions can be explained easily: when reading ISO-2022-JP text escape sequences can be handled alone. I.e., it is not necessary to process a real character since the effect of the escape sequence can be recorded in the state information. The situation is different for the other direction. Since it is in general not known which character comes next one cannot emit escape sequences to change the state in advance. This means the escape sequences which have to be emitted together with the next character. Therefore one needs more room then only for the character itself.

The possible return values of the initialization function are:

__GCONV_OK
The initialization succeeded
__GCONV_NOCONV
The requested conversion is not supported in the module. This can happen if the `gconv-modules' file has errors.
__GCONV_NOMEM
Memory required to store additional information could not be allocated.
The functions called before the module is unloaded is significantly easier. It often has nothing at all to do in which case it can be left out completely.

Data type: void (*__gconv_end_fct) (struct gconv_step *)
The task of this function is it to free all resources allocated in the initialization function. Therefore only the __data element of the object pointed to by the argument is of interest. Continuing the example from the initialization function, the finalization function looks like this:
void
gconv_end (struct __gconv_step *data)
{
  free (data->__data);
}
The most important function is the conversion function itself. It can get quite complicated for complex character sets. But since this is not of interest here we will only describe a possible skeleton for the conversion function.

Data type: int (*__gconv_fct) (struct __gconv_step *, struct __gconv_step_data *, const char **, const char *, size_t *, int)
The conversion function can be called for two basic reason: to convert text or to reset the state. From the description of the iconv function it can be seen why the flushing mode is necessary. What mode is selected is determined by the sixth argument, an integer. If it is nonzero it means that flushing is selected.

Common to both mode is where the output buffer can be found. The information about this buffer is stored in the conversion step data. A pointer to this is passed as the second argument to this function. The description of the struct __gconv_step_data structure has more information on this.

What has to be done for flushing depends on the source character set. If it is not stateful nothing has to be done. Otherwise the function has to emit a byte sequence to bring the state object in the initial state. Once this all happened the other conversion modules in the chain of conversions have to get the same chance. Whether another step follows can be determined from the __is_last element of the step data structure to which the first parameter points.

The more interesting mode is when actually text has to be converted. The first step in this case is to convert as much text as possible from the input buffer and store the result in the output buffer. The start of the input buffer is determined by the third argument which is a pointer to a pointer variable referencing the beginning of the buffer. The fourth argument is a pointer to the byte right after the last byte in the buffer.

The conversion has to be performed according to the current state if the character set is stateful. The state is stored in an object pointed to by the __statep element of the step data (second argument). Once either the input buffer is empty or the output buffer is full the conversion stops. At this point the pointer variable referenced by the third parameter must point to the byte following the last processed byte. I.e., if all of the input is consumed this pointer and the fourth parameter have the same value.

What now happens depends on whether this step is the last one or not. If it is the last step the only thing which has to be done is to update the __outbuf element of the step data structure to point after the last written byte. This gives the caller the information on how much text is available in the output buffer. Beside this the variable pointed to by the fifth parameter, which is of type size_t, must be incremented by the number of characters (not bytes) which were converted in a non-reversible way. Then the function can return.

In case the step is not the last one the later conversion functions have to get a chance to do their work. Therefore the appropriate conversion function has to be called. The information about the functions is stored in the conversion data structures, passed as the first parameter. This information and the step data are stored in arrays so the next element in both cases can be found by simple pointer arithmetic:
int
gconv (struct __gconv_step *step, struct __gconv_step_data *data,
       const char **inbuf, const char *inbufend, size_t *written,
       int do_flush)
{
  struct __gconv_step *next_step = step + 1;
  struct __gconv_step_data *next_data = data + 1;
  ...
The next_step pointer references the next step information and next_data the next data record. The call of the next function therefore will look similar to this:
  next_step->__fct (next_step, next_data, &outerr, outbuf,
                    written, 0)
But this is not yet all. Once the function call returns the conversion function might have some more to do. If the return value of the function is __GCONV_EMPTY_INPUT this means there is more room in the output buffer. Unless the input buffer is empty the conversion functions start all over again and processes the rest of the input buffer. If the return value is not __GCONV_EMPTY_INPUT something went wrong and we have to recover from this.

A requirement for the conversion function is that the input buffer pointer (the third argument) always points to the last character which was put in the converted form in the output buffer. This is trivially true after the conversion performed in the current step. But if the conversion functions deeper down the stream stop prematurely not all characters from the output buffer are consumed and therefore the input buffer pointers must be backed of to the right position.

This is easy to do if the input and output character sets have a fixed width for all characters. In this situation we can compute how many characters are left in the output buffer and therefore can correct the input buffer pointer appropriate with a similar computation. Things are getting tricky if either character set has character represented with variable length byte sequences and it gets even more complicated if the conversion has to take care of the state. In these cases the conversion has to be performed once again, from the known state before the initial conversion. I.e., if necessary the state of the conversion has to be reset and the conversion loop has to be executed again. The difference now is that it is known how much input must be created and the conversion can stop before converting the first unused character. Once this is done the input buffer pointers must be updated again and the function can return.

One final thing should be mentioned. If it is necessary for the conversion to know whether it is the first invocation (in case a prolog has to be emitted) the conversion function should just before returning to the caller increment the __invocation_counter element of the step data structure. See the description of the struct __gconv_step_data structure above for more information on how this can be used.

The return value must be one of the following values:

__GCONV_EMPTY_INPUT
All input was consumed and there is room left in the output buffer.
__GCONV_FULL_OUTPUT
No more room in the output buffer. In case this is not the last step this value is propagated down from the call of the next conversion function in the chain.
__GCONV_INCOMPLETE_INPUT
The input buffer is not entirely empty since it contains an incomplete character sequence.
The following example provides a framework for a conversion function. In case a new conversion has to be written the holes in this implementation have to be filled and that is it.
int
gconv (struct __gconv_step *step, struct __gconv_step_data *data,
       const char **inbuf, const char *inbufend, size_t *written,
       int do_flush)
{
  struct __gconv_step *next_step = step + 1;
  struct __gconv_step_data *next_data = data + 1;
  gconv_fct fct = next_step->__fct;
  int status;

  /* If the function is called with no input this means we have
     to reset to the initial state.  The possibly partly
     converted input is dropped.  */
  if (do_flush)
    {
      status = __GCONV_OK;

      /* Possible emit a byte sequence which put the state object
         into the initial state.  */

      /* Call the steps down the chain if there are any but only
         if we successfully emitted the escape sequence.  */
      if (status == __GCONV_OK && ! data->__is_last)
        status = fct (next_step, next_data, NULL, NULL,
                      written, 1);
    }
  else
    {
      /* We preserve the initial values of the pointer variables.  */
      const char *inptr = *inbuf;
      char *outbuf = data->__outbuf;
      char *outend = data->__outbufend;
      char *outptr;

      do
        {
          /* Remember the start value for this round.  */
          inptr = *inbuf;
          /* The outbuf buffer is empty.  */
          outptr = outbuf;

          /* For stateful encodings the state must be safe here.  */

          /* Run the conversion loop.  status is set
             appropriately afterwards.  */

          /* If this is the last step leave the loop, there is
             nothing we can do.  */
          if (data->__is_last)
            {
              /* Store information about how many bytes are
                 available.  */
              data->__outbuf = outbuf;

             /* If any non-reversible conversions were performed,
                add the number to *written.  */

             break;
           }

          /* Write out all output which was produced.  */
          if (outbuf > outptr)
            {
              const char *outerr = data->__outbuf;
              int result;

              result = fct (next_step, next_data, &outerr,
                            outbuf, written, 0);

              if (result != __GCONV_EMPTY_INPUT)
                {
                  if (outerr != outbuf)
                    {
                      /* Reset the input buffer pointer.  We
                         document here the complex case.  */
                      size_t nstatus;

                      /* Reload the pointers.  */
                      *inbuf = inptr;
                      outbuf = outptr;

                      /* Possibly reset the state.  */

                      /* Redo the conversion, but this time
                         the end of the output buffer is at
                         outerr.  */
                    }

                  /* Change the status.  */
                  status = result;
                }
              else
                /* All the output is consumed, we can make
                    another run if everything was ok.  */
                if (status == __GCONV_FULL_OUTPUT)
                  status = __GCONV_OK;
           }
        }
      while (status == __GCONV_OK);

      /* We finished one use of this step.  */
      ++data->__invocation_counter;
    }

  return status;
}
This information should be sufficient to write new modules. Anybody doing so should also take a look at the available source code in the GNU C library sources. It contains many examples of working and optimized modules.
Locales and Internationalization

Different countries and cultures have varying conventions for how to communicate. These conventions range from very simple ones, such as the format for representing dates and times, to very complex ones, such as the language spoken.

Internationalization of software means programming it to be able to adapt to the user's favorite conventions. In ISO C, internationalization works by means of locales. Each locale specifies a collection of conventions, one convention for each purpose. The user chooses a set of conventions by specifying a locale (via environment variables).

All programs inherit the chosen locale as part of their environment. Provided the programs are written to obey the choice of locale, they will follow the conventions preferred by the user.

What Effects a Locale Has

Each locale specifies conventions for several purposes, including the following:

What multibyte character sequences are valid, and how they are interpreted (see section Character Set Handling).
Classification of which characters in the local character set are considered alphabetic, and upper- and lower-case conversion conventions (see section Character Handling).
The collating sequence for the local language and character set (see section Collation Functions).
Formatting of numbers and currency amounts (see section Generic Numeric Formatting Parameters).
Formatting of dates and times (see section Formatting Calendar Time).
What language to use for output, including error messages (see section Message Translation).
What language to use for user answers to yes-or-no questions.
What language to use for more complex user input. (The C library doesn't yet help you implement this.)

Some aspects of adapting to the specified locale are handled automatically by the library subroutines. For example, all your program needs to do in order to use the collating sequence of the chosen locale is to use strcoll or strxfrm to compare strings.

Other aspects of locales are beyond the comprehension of the library. For example, the library can't automatically translate your program's output messages into other languages. The only way you can support output in the user's favorite language is to program this more or less by hand. The C library provides functions to handle translations for multiple languages easily.

This chapter discusses the mechanism by which you can modify the current locale. The effects of the current locale on specific library functions are discussed in more detail in the descriptions of those functions.

Choosing a Locale

The simplest way for the user to choose a locale is to set the environment variable LANG. This specifies a single locale to use for all purposes. For example, a user could specify a hypothetical locale named `espana-castellano' to use the standard conventions of most of Spain.

The set of locales supported depends on the operating system you are using, and so do their names. We can't make any promises about what locales will exist, except for one standard locale called `C' or `POSIX'. Later we will describe how to construct locales.

A user also has the option of specifying different locales for different purposes--in effect, choosing a mixture of multiple locales.

For example, the user might specify the locale `espana-castellano' for most purposes, but specify the locale `usa-english' for currency formatting. This might make sense if the user is a Spanish-speaking American, working in Spanish, but representing monetary amounts in US dollars.

Note that both locales `espana-castellano' and `usa-english', like all locales, would include conventions for all of the purposes to which locales apply. However, the user can choose to use each locale for a particular subset of those purposes.

Categories of Activities that Locales Affect

The purposes that locales serve are grouped into categories, so that a user or a program can choose the locale for each category independently. Here is a table of categories; each name is both an environment variable that a user can set, and a macro name that you can use as an argument to setlocale.

LC_COLLATE
This category applies to collation of strings (functions strcoll and strxfrm); see section Collation Functions.
LC_CTYPE
This category applies to classification and conversion of characters, and to multibyte and wide characters; see section Character Handling, and section Character Set Handling.
LC_MONETARY
This category applies to formatting monetary values; see section Generic Numeric Formatting Parameters.
LC_NUMERIC
This category applies to formatting numeric values that are not monetary; see section Generic Numeric Formatting Parameters.
LC_TIME
This category applies to formatting date and time values; see section Formatting Calendar Time.
LC_MESSAGES
This category applies to selecting the language used in the user interface for message translation (see section The Uniforum approach to Message Translation; see section X/Open Message Catalog Handling).
LC_ALL
This is not an environment variable; it is only a macro that you can use with setlocale to set a single locale for all purposes. Setting this environment variable overwrites all selections by the other LC_* variables or LANG.
LANG
If this environment variable is defined, its value specifies the locale to use for all purposes except as overridden by the variables above.
When developing the message translation functions it was felt that the functionality provided by the variables above is not sufficient. For example, it should be possible to specify more than one locale name. Take a Swedish user who better speaks German than English, and a program whose messages are output in English by default. It should be possible to specify that the first choice of language is Swedish, the second German, and if this also fails to use English. This is possible with the variable LANGUAGE. For further description of this GNU extension see section User influence on gettext.

How Programs Set the Locale

A C program inherits its locale environment variables when it starts up. This happens automatically. However, these variables do not automatically control the locale used by the library functions, because ISO C says that all programs start by default in the standard `C' locale. To use the locales specified by the environment, you must call setlocale. Call it as follows:
setlocale (LC_ALL, "");
to select a locale based on the user choice of the appropriate environment variables.

You can also use setlocale to specify a particular locale, for general use or for a specific category.

The symbols in this section are defined in the header file `locale.h'.

Function: char * setlocale (int category, const char *locale)
The function setlocale sets the current locale for category category to locale. A list of all the locales the system provides can be created by running
  locale -a
If category is LC_ALL, this specifies the locale for all purposes. The other possible values of category specify an single purpose (see section Categories of Activities that Locales Affect).

You can also use this function to find out the current locale by passing a null pointer as the locale argument. In this case, setlocale returns a string that is the name of the locale currently selected for category category.

The string returned by setlocale can be overwritten by subsequent calls, so you should make a copy of the string (see section Copying and Concatenation) if you want to save it past any further calls to setlocale. (The standard library is guaranteed never to call setlocale itself.)

You should not modify the string returned by setlocale. It might be the same string that was passed as an argument in a previous call to setlocale. One requirement is that the category must be the same in the call the string was returned and the one when the string is passed in as locale parameter.

When you read the current locale for category LC_ALL, the value encodes the entire combination of selected locales for all categories. In this case, the value is not just a single locale name. In fact, we don't make any promises about what it looks like. But if you specify the same "locale name" with LC_ALL in a subsequent call to setlocale, it restores the same combination of locale selections.

To be sure you can use the returned string encoding the currently selected locale at a later time, you must make a copy of the string. It is not guaranteed that the returned pointer remains valid over time.

When the locale argument is not a null pointer, the string returned by setlocale reflects the newly-modified locale.

If you specify an empty string for locale, this means to read the appropriate environment variable and use its value to select the locale for category.

If a nonempty string is given for locale, then the locale of that name is used if possible.

If you specify an invalid locale name, setlocale returns a null pointer and leaves the current locale unchanged.

Here is an example showing how you might use setlocale to temporarily switch to a new locale.
#include <stddef.h>
#include <locale.h>
#include <stdlib.h>
#include <string.h>

void
with_other_locale (char *new_locale,
                   void (*subroutine) (int),
                   int argument)
{
  char *old_locale, *saved_locale;

  /* Get the name of the current locale.  */
  old_locale = setlocale (LC_ALL, NULL);

  /* Copy the name so it won't be clobbered by setlocale. */
  saved_locale = strdup (old_locale);
  if (saved_locale == NULL)
    fatal ("Out of memory");

  /* Now change the locale and do some stuff with it. */
  setlocale (LC_ALL, new_locale);
  (*subroutine) (argument);

  /* Restore the original locale. */
  setlocale (LC_ALL, saved_locale);
  free (saved_locale);
}
Portability Note: Some ISO C systems may define additional locale categories, and future versions of the library will do so. For portability, assume that any symbol beginning with `LC_' might be defined in `locale.h'.

Standard Locales

The only locale names you can count on finding on all operating systems are these three standard ones:

"C"
This is the standard C locale. The attributes and behavior it provides are specified in the ISO C standard. When your program starts up, it initially uses this locale by default.
"POSIX"
This is the standard POSIX locale. Currently, it is an alias for the standard C locale.
""
The empty name says to select a locale based on environment variables. See section Categories of Activities that Locales Affect.
Defining and installing named locales is normally a responsibility of the system administrator at your site (or the person who installed the GNU C library). It is also possible for the user to create private locales. All this will be discussed later when describing the tool to do so.

If your program needs to use something other than the `C' locale, it will be more portable if you use whatever locale the user specifies with the environment, rather than trying to specify some non-standard locale explicitly by name. Remember, different machines might have different sets of locales installed.

Accessing Locale Information

There are several ways to access locale information. The simplest way is to let the C library itself do the work. Several of the functions in this library implicitly access the locale data, and use what information is provided by the currently selected locale. This is how the locale model is meant to work normally.

As an example take the strftime function, which is meant to nicely format date and time information (see section Formatting Calendar Time). Part of the standard information contained in the LC_TIME category is the names of the months. Instead of requiring the programmer to take care of providing the translations the strftime function does this all by itself. %A in the format string is replaced by the appropriate weekday name of the locale currently selected by LC_TIME. This is an easy example, and wherever possible functions do things automatically in this way.

But there are quite often situations when there is simply no function to perform the task, or it is simply not possible to do the work automatically. For these cases it is necessary to access the information in the locale directly. To do this the C library provides two functions: localeconv and nl_langinfo. The former is part of ISO C and therefore portable, but has a brain-damaged interface. The second is part of the Unix interface and is portable in as far as the system follows the Unix standards.

localeconv: It is portable but ...

Together with the setlocale function the ISO C people invented the localeconv function. It is a masterpiece of poor design. It is expensive to use, not extendable, and not generally usable as it provides access to only LC_MONETARY and LC_NUMERIC related information. Nevertheless, if it is applicable to a given situation it should be used since it is very portable. The function strfmon formats monetary amounts according to the selected locale using this information.

Function: struct lconv * localeconv (void)
The localeconv function returns a pointer to a structure whose components contain information about how numeric and monetary values should be formatted in the current locale.

You should not modify the structure or its contents. The structure might be overwritten by subsequent calls to localeconv, or by calls to setlocale, but no other function in the library overwrites this value.

Data Type: struct lconv
localeconv's return value is of this data type. Its elements are described in the following subsections.

If a member of the structure struct lconv has type char, and the value is CHAR_MAX, it means that the current locale has no value for that parameter.

Generic Numeric Formatting Parameters

These are the standard members of struct lconv; there may be others.

char *decimal_point

char *mon_decimal_point
These are the decimal-point separators used in formatting non-monetary and monetary quantities, respectively. In the `C' locale, the value of decimal_point is ".", and the value of mon_decimal_point is "".
char *thousands_sep

char *mon_thousands_sep
These are the separators used to delimit groups of digits to the left of the decimal point in formatting non-monetary and monetary quantities, respectively. In the `C' locale, both members have a value of "" (the empty string).
char *grouping

char *mon_grouping
These are strings that specify how to group the digits to the left of the decimal point. grouping applies to non-monetary quantities and mon_grouping applies to monetary quantities. Use either thousands_sep or mon_thousands_sep to separate the digit groups. Each member of these strings is to be interpreted as an integer value of type char. Successive numbers (from left to right) give the sizes of successive groups (from right to left, starting at the decimal point.) The last member is either 0, in which case the previous member is used over and over again for all the remaining groups, or CHAR_MAX, in which case there is no more grouping--or, put another way, any remaining digits form one large group without separators. For example, if grouping is "\04\03\02", the correct grouping for the number 123456787654321 is `12', `34', `56', `78', `765', `4321'. This uses a group of 4 digits at the end, preceded by a group of 3 digits, preceded by groups of 2 digits (as many as needed). With a separator of `,', the number would be printed as `12,34,56,78,765,4321'. A value of "\03" indicates repeated groups of three digits, as normally used in the U.S. In the standard `C' locale, both grouping and mon_grouping have a value of "". This value specifies no grouping at all.
char int_frac_digits

char frac_digits
These are small integers indicating how many fractional digits (to the right of the decimal point) should be displayed in a monetary value in international and local formats, respectively. (Most often, both members have the same value.) In the standard `C' locale, both of these members have the value CHAR_MAX, meaning "unspecified". The ISO standard doesn't say what to do when you find this value; we recommend printing no fractional digits. (This locale also specifies the empty string for mon_decimal_point, so printing any fractional digits would be confusing!)
Printing the Currency Symbol

These members of the struct lconv structure specify how to print the symbol to identify a monetary value--the international analog of `$' for US dollars.

Each country has two standard currency symbols. The local currency symbol is used commonly within the country, while the international currency symbol is used internationally to refer to that country's currency when it is necessary to indicate the country unambiguously.

For example, many countries use the dollar as their monetary unit, and when dealing with international currencies it's important to specify that one is dealing with (say) Canadian dollars instead of U.S. dollars or Australian dollars. But when the context is known to be Canada, there is no need to make this explicit--dollar amounts are implicitly assumed to be in Canadian dollars.

char *currency_symbol
The local currency symbol for the selected locale. In the standard `C' locale, this member has a value of "" (the empty string), meaning "unspecified". The ISO standard doesn't say what to do when you find this value; we recommend you simply print the empty string as you would print any other string pointed to by this variable.
char *int_curr_symbol
The international currency symbol for the selected locale. The value of int_curr_symbol should normally consist of a three-letter abbreviation determined by the international standard ISO 4217 Codes for the Representation of Currency and Funds, followed by a one-character separator (often a space). In the standard `C' locale, this member has a value of "" (the empty string), meaning "unspecified". We recommend you simply print the empty string as you would print any other string pointed to by this variable.
char p_cs_precedes

char n_cs_precedes

char int_p_cs_precedes

char int_n_cs_precedes
These members are 1 if the currency_symbol or int_curr_symbol strings should precede the value of a monetary amount, or 0 if the strings should follow the value. The p_cs_precedes and int_p_cs_precedes members apply to positive amounts (or zero), and the n_cs_precedes and int_n_cs_precedes members apply to negative amounts. In the standard `C' locale, all of these members have a value of CHAR_MAX, meaning "unspecified". The ISO standard doesn't say what to do when you find this value. We recommend printing the currency symbol before the amount, which is right for most countries. In other words, treat all nonzero values alike in these members. The members with the int_ prefix apply to the int_curr_symbol while the other two apply to currency_symbol.
char p_sep_by_space

char n_sep_by_space

char int_p_sep_by_space

char int_n_sep_by_space
These members are 1 if a space should appear between the currency_symbol or int_curr_symbol strings and the amount, or 0 if no space should appear. The p_sep_by_space and int_p_sep_by_space members apply to positive amounts (or zero), and the n_sep_by_space and int_n_sep_by_space members apply to negative amounts. In the standard `C' locale, all of these members have a value of CHAR_MAX, meaning "unspecified". The ISO standard doesn't say what you should do when you find this value; we suggest you treat it as 1 (print a space). In other words, treat all nonzero values alike in these members. The members with the int_ prefix apply to the int_curr_symbol while the other two apply to currency_symbol. There is one specialty with the int_curr_symbol, though. Since all legal values contain a space at the end the string one either printf this space (if the currency symbol must appear in front and must be separated) or one has to avoid printing this character at all (especially when at the end of the string).
Printing the Sign of a Monetary Amount

These members of the struct lconv structure specify how to print the sign (if any) of a monetary value.

char *positive_sign

char *negative_sign
These are strings used to indicate positive (or zero) and negative monetary quantities, respectively. In the standard `C' locale, both of these members have a value of "" (the empty string), meaning "unspecified". The ISO standard doesn't say what to do when you find this value; we recommend printing positive_sign as you find it, even if it is empty. For a negative value, print negative_sign as you find it unless both it and positive_sign are empty, in which case print `-' instead. (Failing to indicate the sign at all seems rather unreasonable.)
char p_sign_posn

char n_sign_posn

char int_p_sign_posn

char int_n_sign_posn
These members are small integers that indicate how to position the sign for nonnegative and negative monetary quantities, respectively. (The string used by the sign is what was specified with positive_sign or negative_sign.) The possible values are as follows:
0
The currency symbol and quantity should be surrounded by parentheses.
1
Print the sign string before the quantity and currency symbol.
2
Print the sign string after the quantity and currency symbol.
3
Print the sign string right before the currency symbol.
4
Print the sign string right after the currency symbol.
CHAR_MAX
"Unspecified". Both members have this value in the standard `C' locale. The ISO standard doesn't say what you should do when the value is CHAR_MAX. We recommend you print the sign after the currency symbol. The members with the int_ prefix apply to the int_curr_symbol while the other two apply to currency_symbol.
Pinpoint Access to Locale Data

When writing the X/Open Portability Guide the authors realized that the localeconv function is not enough to provide reasonable access to locale information. The information which was meant to be available in the locale (as later specified in the POSIX.1 standard) requires more ways to access it. Therefore the nl_langinfo function was introduced.

Function: char * nl_langinfo (nl_item item)
The nl_langinfo function can be used to access individual elements of the locale categories. Unlike the localeconv function, which returns all the information, nl_langinfo lets the caller select what information it requires. This is very fast and it is not a problem to call this function multiple times.

A second advantage is that in addition to the numeric and monetary formatting information, information from the LC_TIME and LC_MESSAGES categories is available.

The type nl_type is defined in `nl_types.h'. The argument item is a numeric value defined in the header `langinfo.h'. The X/Open standard defines the following values:

CODESET
nl_langinfo returns a string with the name of the coded character set used in the selected locale.
ABDAY_1

ABDAY_2

ABDAY_3

ABDAY_4

ABDAY_5

ABDAY_6

ABDAY_7
nl_langinfo returns the abbreviated weekday name. ABDAY_1 corresponds to Sunday.
DAY_1

DAY_2

DAY_3

DAY_4

DAY_5

DAY_6

DAY_7
Similar to ABDAY_1 etc., but here the return value is the unabbreviated weekday name.
ABMON_1

ABMON_2

ABMON_3

ABMON_4

ABMON_5

ABMON_6

ABMON_7

ABMON_8

ABMON_9

ABMON_10

ABMON_11

ABMON_12
The return value is abbreviated name of the month. ABMON_1 corresponds to January.
MON_1

MON_2

MON_3

MON_4

MON_5

MON_6

MON_7

MON_8

MON_9

MON_10

MON_11

MON_12
Similar to ABMON_1 etc., but here the month names are not abbreviated. Here the first value MON_1 also corresponds to January.
AM_STR

PM_STR
The return values are strings which can be used in the representation of time as an hour from 1 to 12 plus an am/pm specifier. Note that in locales which do not use this time representation these strings might be empty, in which case the am/pm format cannot be used at all.
D_T_FMT
The return value can be used as a format string for strftime to represent time and date in a locale-specific way.
D_FMT
The return value can be used as a format string for strftime to represent a date in a locale-specific way.
T_FMT
The return value can be used as a format string for strftime to represent time in a locale-specific way.
T_FMT_AMPM
The return value can be used as a format string for strftime to represent time in the am/pm format. Note that if the am/pm format does not make any sense for the selected locale, the return value might be the same as the one for T_FMT.
ERA
The return value represents the era used in the current locale. Most locales do not define this value. An example of a locale which does define this value is the Japanese one. In Japan, the traditional representation of dates includes the name of the era corresponding to the then-emperor's reign. Normally it should not be necessary to use this value directly. Specifying the E modifier in their format strings causes the strftime functions to use this information. The format of the returned string is not specified, and therefore you should not assume knowledge of it on different systems.
ERA_YEAR
The return value gives the year in the relevant era of the locale. As for ERA it should not be necessary to use this value directly.
ERA_D_T_FMT
This return value can be used as a format string for strftime to represent dates and times in a locale-specific era-based way.
ERA_D_FMT
This return value can be used as a format string for strftime to represent a date in a locale-specific era-based way.
ERA_T_FMT
This return value can be used as a format string for strftime to represent time in a locale-specific era-based way.
ALT_DIGITS
The return value is a representation of up to @math{100} values used to represent the values @math{0} to @math{99}. As for ERA this value is not intended to be used directly, but instead indirectly through the strftime function. When the modifier O is used in a format which would otherwise use numerals to represent hours, minutes, seconds, weekdays, months, or weeks, the appropriate value for the locale is used instead.
INT_CURR_SYMBOL
The same as the value returned by localeconv in the int_curr_symbol element of the struct lconv.
CURRENCY_SYMBOL

CRNCYSTR
The same as the value returned by localeconv in the currency_symbol element of the struct lconv. CRNCYSTR is a deprecated alias still required by Unix98.
MON_DECIMAL_POINT
The same as the value returned by localeconv in the mon_decimal_point element of the struct lconv.
MON_THOUSANDS_SEP
The same as the value returned by localeconv in the mon_thousands_sep element of the struct lconv.
MON_GROUPING
The same as the value returned by localeconv in the mon_grouping element of the struct lconv.
POSITIVE_SIGN
The same as the value returned by localeconv in the positive_sign element of the struct lconv.
NEGATIVE_SIGN
The same as the value returned by localeconv in the negative_sign element of the struct lconv.
INT_FRAC_DIGITS
The same as the value returned by localeconv in the int_frac_digits element of the struct lconv.
FRAC_DIGITS
The same as the value returned by localeconv in the frac_digits element of the struct lconv.
P_CS_PRECEDES
The same as the value returned by localeconv in the p_cs_precedes element of the struct lconv.
P_SEP_BY_SPACE
The same as the value returned by localeconv in the p_sep_by_space element of the struct lconv.
N_CS_PRECEDES
The same as the value returned by localeconv in the n_cs_precedes element of the struct lconv.
N_SEP_BY_SPACE
The same as the value returned by localeconv in the n_sep_by_space element of the struct lconv.
P_SIGN_POSN
The same as the value returned by localeconv in the p_sign_posn element of the struct lconv.
N_SIGN_POSN
The same as the value returned by localeconv in the n_sign_posn element of the struct lconv.
INT_P_CS_PRECEDES
The same as the value returned by localeconv in the int_p_cs_precedes element of the struct lconv.
INT_P_SEP_BY_SPACE
The same as the value returned by localeconv in the int_p_sep_by_space element of the struct lconv.
INT_N_CS_PRECEDES
The same as the value returned by localeconv in the int_n_cs_precedes element of the struct lconv.
INT_N_SEP_BY_SPACE
The same as the value returned by localeconv in the int_n_sep_by_space element of the struct lconv.
INT_P_SIGN_POSN
The same as the value returned by localeconv in the int_p_sign_posn element of the struct lconv.
INT_N_SIGN_POSN
The same as the value returned by localeconv in the int_n_sign_posn element of the struct lconv.
DECIMAL_POINT

RADIXCHAR
The same as the value returned by localeconv in the decimal_point element of the struct lconv. The name RADIXCHAR is a deprecated alias still used in Unix98.
THOUSANDS_SEP

THOUSEP
The same as the value returned by localeconv in the thousands_sep element of the struct lconv. The name THOUSEP is a deprecated alias still used in Unix98.
GROUPING
The same as the value returned by localeconv in the grouping element of the struct lconv.
YESEXPR
The return value is a regular expression which can be used with the regex function to recognize a positive response to a yes/no question.
NOEXPR
The return value is a regular expression which can be used with the regex function to recognize a negative response to a yes/no question.
YESSTR
The return value is a locale-specific translation of the positive response to a yes/no question. Using this value is deprecated since it is a very special case of message translation, and is better handled by the message translation functions (see section Message Translation). The use of this symbol is deprecated. Instead message translation should be used.
NOSTR
The return value is a locale-specific translation of the negative response to a yes/no question. What is said for YESSTR is also true here. The use of this symbol is deprecated. Instead message translation should be used.
The file `langinfo.h' defines a lot more symbols but none of them is official. Using them is not portable, and the format of the return values might change. Therefore we recommended you not use them.

Note that the return value for any valid argument can be used for in all situations (with the possible exception of the am/pm time formatting codes). If the user has not selected any locale for the appropriate category, nl_langinfo returns the information from the "C" locale. It is therefore possible to use this function as shown in the example below.

If the argument item is not valid, a pointer to an empty string is returned.

An example of nl_langinfo usage is a function which has to print a given date and time in a locale-specific way. At first one might think that, since strftime internally uses the locale information, writing something like the following is enough:
size_t
i18n_time_n_data (char *s, size_t len, const struct tm *tp)
{
  return strftime (s, len, "%X %D", tp);
}
The format contains no weekday or month names and therefore is internationally usable. Wrong! The output produced is something like "hh:mm:ss MM/DD/YY". This format is only recognizable in the USA. Other countries use different formats. Therefore the function should be rewritten like this:
size_t
i18n_time_n_data (char *s, size_t len, const struct tm *tp)
{
  return strftime (s, len, nl_langinfo (D_T_FMT), tp);
}
Now it uses the date and time format of the locale selected when the program runs. If the user selects the locale correctly there should never be a misunderstanding over the time and date format.

A dedicated function to format numbers

We have seen that the structure returned by localeconv as well as the values given to nl_langinfo allow you to retrieve the various pieces of locale-specific information to format numbers and monetary amounts. We have also seen that the underlying rules are quite complex.

Therefore the X/Open standards introduce a function which uses such locale information, making it easier for the user to format numbers according to these rules.

Function: ssize_t strfmon (char *s, size_t maxsize, const char *format, ...)
The strfmon function is similar to the strftime function in that it takes a buffer, its size, a format string, and values to write into the buffer as text in a form specified by the format string. Like strftime, the function also returns the number of bytes written into the buffer.

There are two differences: strfmon can take more than one argument, and, of course, the format specification is different. Like strftime, the format string consists of normal text, which is output as is, and format specifiers, which are indicated by a `%'. Immediately after the `%', you can optionally specify various flags and formatting information before the main formatting character, in a similar way to printf:

Immediately following the `%' there can be one or more of the following flags:
`=f'
The single byte character f is used for this field as the numeric fill character. By default this character is a space character. Filling with this character is only performed if a left precision is specified. It is not just to fill to the given field width.
`^'
The number is printed without grouping the digits according to the rules of the current locale. By default grouping is enabled.
`+', `('
At most one of these flags can be used. They select which format to represent the sign of a currency amount. By default, and if `+' is given, the locale equivalent of @math{+}/@math{-} is used. If `(' is given, negative amounts are enclosed in parentheses. The exact format is determined by the values of the LC_MONETARY category of the locale selected at program runtime.
`!'
The output will not contain the currency symbol.
`-'
The output will be formatted left-justified instead of right-justified if it does not fill the entire field width.

The next part of a specification is an optional field width. If no width is specified @math{0} is taken. During output, the function first determines how much space is required. If it requires at least as many characters as given by the field width, it is output using as much space as necessary. Otherwise, it is extended to use the full width by filling with the space character. The presence or absence of the `-' flag determines the side at which such padding occurs. If present, the spaces are added at the right making the output left-justified, and vice versa.

So far the format looks familiar, being similar to the printf and strftime formats. However, the next two optional fields introduce something new. The first one is a `#' character followed by a decimal digit string. The value of the digit string specifies the number of digit positions to the left of the decimal point (or equivalent). This does not include the grouping character when the `^' flag is not given. If the space needed to print the number does not fill the whole width, the field is padded at the left side with the fill character, which can be selected using the `=' flag and by default is a space. For example, if the field width is selected as 6 and the number is @math{123}, the fill character is `*' the result will be `***123'.

The second optional field starts with a `.' (period) and consists of another decimal digit string. Its value describes the number of characters printed after the decimal point. The default is selected from the current locale (frac_digits, int_frac_digits, see see section Generic Numeric Formatting Parameters). If the exact representation needs more digits than given by the field width, the displayed value is rounded. If the number of fractional digits is selected to be zero, no decimal point is printed.

As a GNU extension, the strfmon implementation in the GNU libc allows an optional `L' next as a format modifier. If this modifier is given, the argument is expected to be a long double instead of a double value.

Finally, the last component is a format specifier. There are three specifiers defined:

`i'
Use the locale's rules for formatting an international currency value.
`n'
Use the locale's rules for formatting a national currency value.
`%'
Place a `%' in the output. There must be no flag, width specifier or modifier given, only `%%' is allowed.
As for printf, the function reads the format string from left to right and uses the values passed to the function following the format string. The values are expected to be either of type double or long double, depending on the presence of the modifier `L'. The result is stored in the buffer pointed to by s. At most maxsize characters are stored.

The return value of the function is the number of characters stored in s, including the terminating NULL byte. If the number of characters stored would exceed maxsize, the function returns @math{-1} and the content of the buffer s is unspecified. In this case errno is set to E2BIG.

A few examples should make clear how the function works. It is assumed that all the following pieces of code are executed in a program which uses the USA locale (en_US). The simplest form of the format is this:
strfmon (buf, 100, "@%n@%n@%n@", 123.45, -567.89, 12345.678);
The output produced is
"@$123.45@-$567.89@$12,345.68@"
We can notice several things here. First, the widths of the output numbers are different. We have not specified a width in the format string, and so this is no wonder. Second, the third number is printed using thousands separators. The thousands separator for the en_US locale is a comma. The number is also rounded. @math{.678} is rounded to @math{.68} since the format does not specify a precision and the default value in the locale is @math{2}. Finally, note that the national currency symbol is printed since `%n' was used, not `i'. The next example shows how we can align the output.
strfmon (buf, 100, "@%=*11n@%=*11n@%=*11n@", 123.45, -567.89, 12345.678);
The output this time is:
"@    $123.45@   -$567.89@ $12,345.68@"
Two things stand out. Firstly, all fields have the same width (eleven characters) since this is the width given in the format and since no number required more characters to be printed. The second important point is that the fill character is not used. This is correct since the white space was not used to achieve a precision given by a `#' modifier, but instead to fill to the given width. The difference becomes obvious if we now add a width specification.
strfmon (buf, 100, "@%=*11#5n@%=*11#5n@%=*11#5n@",
         123.45, -567.89, 12345.678);
The output is
"@ $***123.45@-$***567.89@ $12,456.68@"
Here we can see that all the currency symbols are now aligned, and that the space between the currency sign and the number is filled with the selected fill character. Note that although the width is selected to be @math{5} and @math{123.45} has three digits left of the decimal point, the space is filled with three asterisks. This is correct since, as explained above, the width does not include the positions used to store thousands separators. One last example should explain the remaining functionality.
strfmon (buf, 100, "@%=0(16#5.3i@%=0(16#5.3i@%=0(16#5.3i@",
         123.45, -567.89, 12345.678);
This rather complex format string produces the following output:
"@ USD 000123,450 @(USD 000567.890)@ USD 12,345.678 @"
The most noticeable change is the alternative way of representing negative numbers. In financial circles this is often done using parentheses, and this is what the `(' flag selected. The fill character is now `0'. Note that this `0' character is not regarded as a numeric zero, and therefore the first and second numbers are not printed using a thousands separator. Since we used the format specifier `i' instead of `n', the international form of the currency symbol is used. This is a four letter string, in this case "USD ". The last point is that since the precision right of the decimal point is selected to be three, the first and second numbers are printed with an extra zero at the end and the third number is printed without rounding.
Message Translation

The program's interface with the human should be designed in a way to ease the human the task. One of the possibilities is to use messages in whatever language the user prefers.

Printing messages in different languages can be implemented in different ways. One could add all the different languages in the source code and add among the variants every time a message has to be printed. This is certainly no good solution since extending the set of languages is difficult (the code must be changed) and the code itself can become really big with dozens of message sets.

A better solution is to keep the message sets for each language are kept in separate files which are loaded at runtime depending on the language selection of the user.

The GNU C Library provides two different sets of functions to support message translation. The problem is that neither of the interfaces is officially defined by the POSIX standard. The catgets family of functions is defined in the X/Open standard but this is derived from industry decisions and therefore not necessarily based on reasonable decisions.

As mentioned above the message catalog handling provides easy extendibility by using external data files which contain the message translations. I.e., these files contain for each of the messages used in the program a translation for the appropriate language. So the tasks of the message handling functions are

locate the external data file with the appropriate translations.
load the data and make it possible to address the messages
map a given key to the translated message

The two approaches mainly differ in the implementation of this last step. The design decisions made for this influences the whole rest.

X/Open Message Catalog Handling

The catgets functions are based on the simple scheme:

Associate every message to translate in the source code with a unique identifier. To retrieve a message from a catalog file solely the identifier is used.

This means for the author of the program that s/he will have to make sure the meaning of the identifier in the program code and in the message catalogs are always the same.

Before a message can be translated the catalog file must be located. The user of the program must be able to guide the responsible function to find whatever catalog the user wants. This is separated from what the programmer had in mind.

All the types, constants and functions for the catgets functions are defined/declared in the `nl_types.h' header file.

The catgets function family

Function: nl_catd catopen (const char *cat_name, int flag)
The catgets function tries to locate the message data file names cat_name and loads it when found. The return value is of an opaque type and can be used in calls to the other functions to refer to this loaded catalog.

The return value is (nl_catd) -1 in case the function failed and no catalog was loaded. The global variable errno contains a code for the error causing the failure. But even if the function call succeeded this does not mean that all messages can be translated.

Locating the catalog file must happen in a way which lets the user of the program influence the decision. It is up to the user to decide about the language to use and sometimes it is useful to use alternate catalog files. All this can be specified by the user by setting some environment variables.

The first problem is to find out where all the message catalogs are stored. Every program could have its own place to keep all the different files but usually the catalog files are grouped by languages and the catalogs for all programs are kept in the same place.

To tell the catopen function where the catalog for the program can be found the user can set the environment variable NLSPATH to a value which describes her/his choice. Since this value must be usable for different languages and locales it cannot be a simple string. Instead it is a format string (similar to printf's). An example is
/usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N
First one can see that more than one directory can be specified (with the usual syntax of separating them by colons). The next things to observe are the format string, %L and %N in this case. The catopen function knows about several of them and the replacement for all of them is of course different.

%N
This format element is substituted with the name of the catalog file. This is the value of the cat_name argument given to catgets.
%L
This format element is substituted with the name of the currently selected locale for translating messages. How this is determined is explained below.
%l
(This is the lowercase ell.) This format element is substituted with the language element of the locale name. The string describing the selected locale is expected to have the form lang[_terr[.codeset]] and this format uses the first part lang.
%t
This format element is substituted by the territory part terr of the name of the currently selected locale. See the explanation of the format above.
%c
This format element is substituted by the codeset part codeset of the name of the currently selected locale. See the explanation of the format above.
%%
Since % is used in a meta character there must be a way to express the % character in the result itself. Using %% does this just like it works for printf.
Using NLSPATH allows arbitrary directories to be searched for message catalogs while still allowing different languages to be used. If the NLSPATH environment variable is not set, the default value is
prefix/share/locale/%L/%N:prefix/share/locale/%L/LC_MESSAGES/%N
where prefix is given to configure while installing the GNU C Library (this value is in many cases /usr or the empty string).

The remaining problem is to decide which must be used. The value decides about the substitution of the format elements mentioned above. First of all the user can specify a path in the message catalog name (i.e., the name contains a slash character). In this situation the NLSPATH environment variable is not used. The catalog must exist as specified in the program, perhaps relative to the current working directory. This situation in not desirable and catalogs names never should be written this way. Beside this, this behavior is not portable to all other platforms providing the catgets interface.

Otherwise the values of environment variables from the standard environment are examined (see section Standard Environment Variables). Which variables are examined is decided by the flag parameter of catopen. If the value is NL_CAT_LOCALE (which is defined in `nl_types.h') then the catopen function use the name of the locale currently selected for the LC_MESSAGES category.

If flag is zero the LANG environment variable is examined. This is a left-over from the early days where the concept of the locales had not even reached the level of POSIX locales.

The environment variable and the locale name should have a value of the form lang[_terr[.codeset]] as explained above. If no environment variable is set the "C" locale is used which prevents any translation.

The return value of the function is in any case a valid string. Either it is a translation from a message catalog or it is the same as the string parameter. So a piece of code to decide whether a translation actually happened must look like this:
{
  char *trans = catgets (desc, set, msg, input_string);
  if (trans == input_string)
    {
      /* Something went wrong.  */
    }
}
When an error occurred the global variable errno is set to

EBADF
The catalog does not exist.
ENOMSG
The set/message tuple does not name an existing element in the message catalog.
While it sometimes can be useful to test for errors programs normally will avoid any test. If the translation is not available it is no big problem if the original, untranslated message is printed. Either the user understands this as well or s/he will look for the reason why the messages are not translated.

Please note that the currently selected locale does not depend on a call to the setlocale function. It is not necessary that the locale data files for this locale exist and calling setlocale succeeds. The catopen function directly reads the values of the environment variables.

Function: char * catgets (nl_catd catalog_desc, int set, int message, const char *string)
The function catgets has to be used to access the massage catalog previously opened using the catopen function. The catalog_desc parameter must be a value previously returned by catopen.

The next two parameters, set and message, reflect the internal organization of the message catalog files. This will be explained in detail below. For now it is interesting to know that a catalog can consists of several set and the messages in each thread are individually numbered using numbers. Neither the set number nor the message number must be consecutive. They can be arbitrarily chosen. But each message (unless equal to another one) must have its own unique pair of set and message number.

Since it is not guaranteed that the message catalog for the language selected by the user exists the last parameter string helps to handle this case gracefully. If no matching string can be found string is returned. This means for the programmer that

the string parameters should contain reasonable text (this also helps to understand the program seems otherwise there would be no hint on the string which is expected to be returned.
all string arguments should be written in the same language.

It is somewhat uncomfortable to write a program using the catgets functions if no supporting functionality is available. Since each set/message number tuple must be unique the programmer must keep lists of the messages at the same time the code is written. And the work between several people working on the same project must be coordinated. We will see some how these problems can be relaxed a bit (see section How to use the catgets interface).

Function: int catclose (nl_catd catalog_desc)
The catclose function can be used to free the resources associated with a message catalog which previously was opened by a call to catopen. If the resources can be successfully freed the function returns 0. Otherwise it return -1 and the global variable errno is set. Errors can occur if the catalog descriptor catalog_desc is not valid in which case errno is set to EBADF.

Format of the message catalog files

The only reasonable way the translate all the messages of a function and store the result in a message catalog file which can be read by the catopen function is to write all the message text to the translator and let her/him translate them all. I.e., we must have a file with entries which associate the set/message tuple with a specific translation. This file format is specified in the X/Open standard and is as follows:

Lines containing only whitespace characters or empty lines are ignored.
Lines which contain as the first non-whitespace character a $ followed by a whitespace character are comment and are also ignored.
If a line contains as the first non-whitespace characters the sequence $set followed by a whitespace character an additional argument is required to follow. This argument can either be:

a number. In this case the value of this number determines the set to which the following messages are added.
an identifier consisting of alphanumeric characters plus the underscore character. In this case the set get automatically a number assigned. This value is one added to the largest set number which so far appeared. How to use the symbolic names is explained in section section How to use the catgets interface. It is an error if a symbol name appears more than once. All following messages are placed in a set with this number.

If a line contains as the first non-whitespace characters the sequence $delset followed by a whitespace character an additional argument is required to follow. This argument can either be:

a number. In this case the value of this number determines the set which will be deleted.
an identifier consisting of alphanumeric characters plus the underscore character. This symbolic identifier must match a name for a set which previously was defined. It is an error if the name is unknown.
In both cases all messages in the specified set will be removed. They will not appear in the output. But if this set is later again selected with a $set command again messages could be added and these messages will appear in the output.
If a line contains after leading whitespaces the sequence $quote, the quoting character used for this input file is changed to the first non-whitespace character following the $quote. If no non-whitespace character is present before the line ends quoting is disable. By default no quoting character is used. In this mode strings are terminated with the first unescaped line break. If there is a $quote sequence present newline need not be escaped. Instead a string is terminated with the first unescaped appearance of the quote character. A common usage of this feature would be to set the quote character to ". Then any appearance of the " in the strings must be escaped using the backslash (i.e., \" must be written).
Any other line must start with a number or an alphanumeric identifier (with the underscore character included). The following characters (starting after the first whitespace character) will form the string which gets associated with the currently selected set and the message number represented by the number and identifier respectively. If the start of the line is a number the message number is obvious. It is an error if the same message number already appeared for this set. If the leading token was an identifier the message number gets automatically assigned. The value is the current maximum messages number for this set plus one. It is an error if the identifier was already used for a message in this set. It is OK to reuse the identifier for a message in another thread. How to use the symbolic identifiers will be explained below (see section How to use the catgets interface). There is one limitation with the identifier: it must not be Set. The reason will be explained below. The text of the messages can contain escape characters. The usual bunch of characters known from the ISO C language are recognized (\n, \t, \v, \b, \r, \f, \\, and \nnn, where nnn is the octal coding of a character code).

Important: The handling of identifiers instead of numbers for the set and messages is a GNU extension. Systems strictly following the X/Open specification do not have this feature. An example for a message catalog file is this:
$ This is a leading comment.
$quote "

$set SetOne
1 Message with ID 1.
two "   Message with ID \"two\", which gets the value 2 assigned"

$set SetTwo
$ Since the last set got the number 1 assigned this set has number 2.
4000 "The numbers can be arbitrary, they need not start at one."
This small example shows various aspects:

Lines 1 and 9 are comments since they start with $ followed by a whitespace.
The quoting character is set to ". Otherwise the quotes in the message definition would have to be left away and in this case the message with the identifier two would loose its leading whitespace.
Mixing numbered messages with message having symbolic names is no problem and the numbering happens automatically.

While this file format is pretty easy it is not the best possible for use in a running program. The catopen function would have to parser the file and handle syntactic errors gracefully. This is not so easy and the whole process is pretty slow. Therefore the catgets functions expect the data in another more compact and ready-to-use file format. There is a special program gencat which is explained in detail in the next section.

Files in this other format are not human readable. To be easy to use by programs it is a binary file. But the format is byte order independent so translation files can be shared by systems of arbitrary architecture (as long as they use the GNU C Library).

Details about the binary file format are not important to know since these files are always created by the gencat program. The sources of the GNU C Library also provide the sources for the gencat program and so the interested reader can look through these source files to learn about the file format.

Generate Message Catalogs files

The gencat program is specified in the X/Open standard and the GNU implementation follows this specification and so processes all correctly formed input files. Additionally some extension are implemented which help to work in a more reasonable way with the catgets functions.

The gencat program can be invoked in two ways:
`gencat [Option]... [Output-File [Input-File]...]`
This is the interface defined in the X/Open standard. If no Input-File parameter is given input will be read from standard input. Multiple input files will be read as if they are concatenated. If Output-File is also missing, the output will be written to standard output. To provide the interface one is used to from other programs a second interface is provided.
`gencat [Option]... -o Output-File [Input-File]...`
The option `-o' is used to specify the output file and all file arguments are used as input files.

Beside this one can use `-' or `/dev/stdin' for Input-File to denote the standard input. Corresponding one can use `-' and `/dev/stdout' for Output-File to denote standard output. Using `-' as a file name is allowed in X/Open while using the device names is a GNU extension.

The gencat program works by concatenating all input files and then merge the resulting collection of message sets with a possibly existing output file. This is done by removing all messages with set/message number tuples matching any of the generated messages from the output file and then adding all the new messages. To regenerate a catalog file while ignoring the old contents therefore requires to remove the output file if it exists. If the output is written to standard output no merging takes place.

The following table shows the options understood by the gencat program. The X/Open standard does not specify any option for the program so all of these are GNU extensions.

`-V'

`--version'
Print the version information and exit.
`-h'

`--help'
Print a usage message listing all available options, then exit successfully.
`--new'
Do never merge the new messages from the input files with the old content of the output files. The old content of the output file is discarded.
`-H'

`--header=name'
This option is used to emit the symbolic names given to sets and messages in the input files for use in the program. Details about how to use this are given in the next section. The name parameter to this option specifies the name of the output file. It will contain a number of C preprocessor #defines to associate a name with a number. Please note that the generated file only contains the symbols from the input files. If the output is merged with the previous content of the output file the possibly existing symbols from the file(s) which generated the old output files are not in the generated header file.
How to use the catgets interface

The catgets functions can be used in two different ways. By following slavishly the X/Open specs and not relying on the extension and by using the GNU extensions. We will take a look at the former method first to understand the benefits of extensions.

Not using symbolic names

Since the X/Open format of the message catalog files does not allow symbol names we have to work with numbers all the time. When we start writing a program we have to replace all appearances of translatable strings with something like
catgets (catdesc, set, msg, "string")
catgets is retrieved from a call to catopen which is normally done once at the program start. The "string" is the string we want to translate. The problems start with the set and message numbers.

In a bigger program several programmers usually work at the same time on the program and so coordinating the number allocation is crucial. Though no two different strings must be indexed by the same tuple of numbers it is highly desirable to reuse the numbers for equal strings with equal translations (please note that there might be strings which are equal in one language but have different translations due to difference contexts).

The allocation process can be relaxed a bit by different set numbers for different parts of the program. So the number of developers who have to coordinate the allocation can be reduced. But still lists must be keep track of the allocation and errors can easily happen. These errors cannot be discovered by the compiler or the catgets functions. Only the user of the program might see wrong messages printed. In the worst cases the messages are so irritating that they cannot be recognized as wrong. Think about the translations for "true" and "false" being exchanged. This could result in a disaster.

Using symbolic names

The problems mentioned in the last section derive from the fact that:

the numbers are allocated once and due to the possibly frequent use of them it is difficult to change a number later.
the numbers do not allow to guess anything about the string and therefore collisions can easily happen.

By constantly using symbolic names and by providing a method which maps the string content to a symbolic name (however this will happen) one can prevent both problems above. The cost of this is that the programmer has to write a complete message catalog file while s/he is writing the program itself.

This is necessary since the symbolic names must be mapped to numbers before the program sources can be compiled. In the last section it was described how to generate a header containing the mapping of the names. E.g., for the example message file given in the last section we could call the gencat program as follow (assume `ex.msg' contains the sources).
gencat -H ex.h -o ex.cat ex.msg
This generates a header file with the following content:
#define SetTwoSet 0x2   /* ex.msg:8 */

#define SetOneSet 0x1   /* ex.msg:4 */
#define SetOnetwo 0x2   /* ex.msg:6 */
As can be seen the various symbols given in the source file are mangled to generate unique identifiers and these identifiers get numbers assigned. Reading the source file and knowing about the rules will allow to predict the content of the header file (it is deterministic) but this is not necessary. The gencat program can take care for everything. All the programmer has to do is to put the generated header file in the dependency list of the source files of her/his project and to add a rules to regenerate the header of any of the input files change.

One word about the symbol mangling. Every symbol consists of two parts: the name of the message set plus the name of the message or the special string Set. So SetOnetwo means this macro can be used to access the translation with identifier two in the message set SetOne.

The other names denote the names of the message sets. The special string Set is used in the place of the message identifier.

If in the code the second string of the set SetOne is used the C code should look like this:
catgets (catdesc, SetOneSet, SetOnetwo,
         "   Message with ID \"two\", which gets the value 2 assigned")
Writing the function this way will allow to change the message number and even the set number without requiring any change in the C source code. (The text of the string is normally not the same; this is only for this example.)

How does to this allow to develop

To illustrate the usual way to work with the symbolic version numbers here is a little example. Assume we want to write the very complex and famous greeting program. We start by writing the code as usual:
#include <stdio.h>
int
main (void)
{
  printf ("Hello, world!\n");
  return 0;
}
Now we want to internationalize the message and therefore replace the message with whatever the user wants.
#include <nl_types.h>
#include <stdio.h>
#include "msgnrs.h"
int
main (void)
{
  nl_catd catdesc = catopen ("hello.cat", NL_CAT_LOCALE);
  printf (catgets (catdesc, SetMainSet, SetMainHello,
                   "Hello, world!\n"));
  catclose (catdesc);
  return 0;
}
We see how the catalog object is opened and the returned descriptor used in the other function calls. It is not really necessary to check for failure of any of the functions since even in these situations the functions will behave reasonable. They simply will be return a translation.

What remains unspecified here are the constants SetMainSet and SetMainHello. These are the symbolic names describing the message. To get the actual definitions which match the information in the catalog file we have to create the message catalog source file and process it using the gencat program.
$ Messages for the famous greeting program.
$quote "

$set Main
Hello "Hallo, Welt!\n"
Now we can start building the program (assume the message catalog source file is named `hello.msg' and the program source file `hello.c'):
% gencat -H msgnrs.h -o hello.cat hello.msg
% cat msgnrs.h
#define MainSet 0x1     /* hello.msg:4 */
#define MainHello 0x1   /* hello.msg:5 */
% gcc -o hello hello.c -I.
% cp hello.cat /usr/share/locale/de/LC_MESSAGES
% echo $LC_ALL
de
% ./hello
Hallo, Welt!
%
The call of the gencat program creates the missing header file `msgnrs.h' as well as the message catalog binary. The former is used in the compilation of `hello.c' while the later is placed in a directory in which the catopen function will try to locate it. Please check the LC_ALL environment variable and the default path for catopen presented in the description above.

The Uniforum approach to Message Translation

Sun Microsystems tried to standardize a different approach to message translation in the Uniforum group. There never was a real standard defined but still the interface was used in Sun's operation systems. Since this approach fits better in the development process of free software it is also used throughout the GNU project and the GNU `gettext' package provides support for this outside the GNU C Library.

The code of the `libintl' from GNU `gettext' is the same as the code in the GNU C Library. So the documentation in the GNU `gettext' manual is also valid for the functionality here. The following text will describe the library functions in detail. But the numerous helper programs are not described in this manual. Instead people should read the GNU `gettext' manual (see section `GNU gettext utilities' in Native Language Support Library and Tools). We will only give a short overview.

Though the catgets functions are available by default on more systems the gettext interface is at least as portable as the former. The GNU `gettext' package can be used wherever the functions are not available.

The gettext family of functions

The paradigms underlying the gettext approach to message translations is different from that of the catgets functions the basic functionally is equivalent. There are functions of the following categories:

What has to be done to translate a message?

The gettext functions have a very simple interface. The most basic function just takes the string which shall be translated as the argument and it returns the translation. This is fundamentally different from the catgets approach where an extra key is necessary and the original string is only used for the error case.

If the string which has to be translated is the only argument this of course means the string itself is the key. I.e., the translation will be selected based on the original string. The message catalogs must therefore contain the original strings plus one translation for any such string. The task of the gettext function is it to compare the argument string with the available strings in the catalog and return the appropriate translation. Of course this process is optimized so that this process is not more expensive than an access using an atomic key like in catgets.

The gettext approach has some advantages but also some disadvantages. Please see the GNU `gettext' manual for a detailed discussion of the pros and cons.

All the definitions and declarations for gettext can be found in the `libintl.h' header file. On systems where these functions are not part of the C library they can be found in a separate library named `libintl.a' (or accordingly different for shared libraries).

Function: char * gettext (const char *msgid)
The gettext function searches the currently selected message catalogs for a string which is equal to msgid. If there is such a string available it is returned. Otherwise the argument string msgid is returned.

Please note that all though the return value is char * the returned string must not be changed. This broken type results from the history of the function and does not reflect the way the function should be used.

Please note that above we wrote "message catalogs" (plural). This is a specialty of the GNU implementation of these functions and we will say more about this when we talk about the ways message catalogs are selected (see section How to determine which catalog to be used).

The gettext function does not modify the value of the global errno variable. This is necessary to make it possible to write something like
  printf (gettext ("Operation failed: %m\n"));
Here the errno value is used in the printf function while processing the %m format element and if the gettext function would change this value (it is called before printf is called) we would get a wrong message.

So there is no easy way to detect a missing message catalog beside comparing the argument string with the result. But it is normally the task of the user to react on missing catalogs. The program cannot guess when a message catalog is really necessary since for a user who speaks the language the program was developed in does not need any translation.

The remaining two functions to access the message catalog add some functionality to select a message catalog which is not the default one. This is important if parts of the program are developed independently. Every part can have its own message catalog and all of them can be used at the same time. The C library itself is an example: internally it uses the gettext functions but since it must not depend on a currently selected default message catalog it must specify all ambiguous information.

Function: char * dgettext (const char *domainname, const char *msgid)
The dgettext functions acts just like the gettext function. It only takes an additional first argument domainname which guides the selection of the message catalogs which are searched for the translation. If the domainname parameter is the null pointer the dgettext function is exactly equivalent to gettext since the default value for the domain name is used.

As for gettext the return value type is char * which is an anachronism. The returned string must never be modified.

Function: char * dcgettext (const char *domainname, const char *msgid, int category)
The dcgettext adds another argument to those which dgettext takes. This argument category specifies the last piece of information needed to localize the message catalog. I.e., the domain name and the locale category exactly specify which message catalog has to be used (relative to a given directory, see below).

The dgettext function can be expressed in terms of dcgettext by using
dcgettext (domain, string, LC_MESSAGES)
instead of
dgettext (domain, string)
This also shows which values are expected for the third parameter. One has to use the available selectors for the categories available in `locale.h'. Normally the available values are LC_CTYPE, LC_COLLATE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME. Please note that LC_ALL must not be used and even though the names might suggest this, there is no relation to the environments variables of this name.

The dcgettext function is only implemented for compatibility with other systems which have gettext functions. There is not really any situation where it is necessary (or useful) to use a different value but LC_MESSAGES in for the category parameter. We are dealing with messages here and any other choice can only be irritating.

As for gettext the return value type is char * which is an anachronism. The returned string must never be modified.

When using the three functions above in a program it is a frequent case that the msgid argument is a constant string. So it is worth to optimize this case. Thinking shortly about this one will realize that as long as no new message catalog is loaded the translation of a message will not change. This optimization is actually implemented by the gettext, dgettext and dcgettext functions.

How to determine which catalog to be used

The functions to retrieve the translations for a given message have a remarkable simple interface. But to provide the user of the program still the opportunity to select exactly the translation s/he wants and also to provide the programmer the possibility to influence the way to locate the search for catalogs files there is a quite complicated underlying mechanism which controls all this. The code is complicated the use is easy.

Basically we have two different tasks to perform which can also be performed by the catgets functions:

Locate the set of message catalogs. There are a number of files for different languages and which all belong to the package. Usually they are all stored in the filesystem below a certain directory. There can be arbitrary many packages installed and they can follow different guidelines for the placement of their files.
Relative to the location specified by the package the actual translation files must be searched, based on the wishes of the user. I.e., for each language the user selects the program should be able to locate the appropriate file.

This is the functionality required by the specifications for gettext and this is also what the catgets functions are able to do. But there are some problems unresolved:

The language to be used can be specified in several different ways. There is no generally accepted standard for this and the user always expects the program understand what s/he means. E.g., to select the German translation one could write de, german, or deutsch and the program should always react the same.
Sometimes the specification of the user is too detailed. If s/he, e.g., specifies de_DE.ISO-8859-1 which means German, spoken in Germany, coded using the ISO 8859-1 character set there is the possibility that a message catalog matching this exactly is not available. But there could be a catalog matching de and if the character set used on the machine is always ISO 8859-1 there is no reason why this later message catalog should not be used. (We call this message inheritance.)
If a catalog for a wanted language is not available it is not always the second best choice to fall back on the language of the developer and simply not translate any message. Instead a user might be better able to read the messages in another language and so the user of the program should be able to define an precedence order of languages.

We can divide the configuration actions in two parts: the one is performed by the programmer, the other by the user. We will start with the functions the programmer can use since the user configuration will be based on this.

As the functions described in the last sections already mention separate sets of messages can be selected by a domain name. This is a simple string which should be unique for each program part with uses a separate domain. It is possible to use in one program arbitrary many domains at the same time. E.g., the GNU C Library itself uses a domain named libc while the program using the C Library could use a domain named foo. The important point is that at any time exactly one domain is active. This is controlled with the following function.

Function: char * textdomain (const char *domainname)
The textdomain function sets the default domain, which is used in all future gettext calls, to domainname. Please note that dgettext and dcgettext calls are not influenced if the domainname parameter of these functions is not the null pointer.

Before the first call to textdomain the default domain is messages. This is the name specified in the specification of the gettext API. This name is as good as any other name. No program should ever really use a domain with this name since this can only lead to problems.

The function returns the value which is from now on taken as the default domain. If the system went out of memory the returned value is NULL and the global variable errno is set to ENOMEM. Despite the return value type being char * the return string must not be changed. It is allocated internally by the textdomain function.

If the domainname parameter is the null pointer no new default domain is set. Instead the currently selected default domain is returned.

If the domainname parameter is the empty string the default domain is reset to its initial value, the domain with the name messages. This possibility is questionable to use since the domain messages really never should be used.

Function: char * bindtextdomain (const char *domainname, const char *dirname)
The bindtextdomain function can be used to specify the directory which contains the message catalogs for domain domainname for the different languages. To be correct, this is the directory where the hierarchy of directories is expected. Details are explained below.

For the programmer it is important to note that the translations which come with the program have be placed in a directory hierarchy starting at, say, `/foo/bar'. Then the program should make a bindtextdomain call to bind the domain for the current program to this directory. So it is made sure the catalogs are found. A correctly running program does not depend on the user setting an environment variable.

The bindtextdomain function can be used several times and if the domainname argument is different the previously bound domains will not be overwritten.

If the program which wish to use bindtextdomain at some point of time use the chdir function to change the current working directory it is important that the dirname strings ought to be an absolute pathname. Otherwise the addressed directory might vary with the time.

If the dirname parameter is the null pointer bindtextdomain returns the currently selected directory for the domain with the name domainname.

The bindtextdomain function returns a pointer to a string containing the name of the selected directory name. The string is allocated internally in the function and must not be changed by the user. If the system went out of core during the execution of bindtextdomain the return value is NULL and the global variable errno is set accordingly.

Additional functions for more complicated situations

The functions of the gettext family described so far (and all the catgets functions as well) have one problem in the real world which have been neglected completely in all existing approaches. What is meant here is the handling of plural forms.

Looking through Unix source code before the time anybody thought about internationalization (and, sadly, even afterwards) one can often find code similar to the following:
   printf ("%d file%s deleted", n, n == 1 ? "" : "s");
After the first complaints from people internationalizing the code people either completely avoided formulations like this or used strings like "file(s)". Both look unnatural and should be avoided. First tries to solve the problem correctly looked like this:
   if (n == 1)
     printf ("%d file deleted", n);
   else
     printf ("%d files deleted", n);
But this does not solve the problem. It helps languages where the plural form of a noun is not simply constructed by adding an `s' but that is all. Once again people fell into the trap of believing the rules their language is using are universal. But the handling of plural forms differs widely between the language families. There are two things we can differ between (and even inside language families);

The form how plural forms are build differs. This is a problem with language which have many irregularities. German, for instance, is a drastic case. Though English and German are part of the same language family (Germanic), the almost regular forming of plural noun forms (appending an `s') is hardly found in German.
The number of plural forms differ. This is somewhat surprising for those who only have experiences with Romanic and Germanic languages since here the number is the same (there are two). But other language families have only one form or many forms. More information on this in an extra section.

The consequence of this is that application writers should not try to solve the problem in their code. This would be localization since it is only usable for certain, hardcoded language environments. Instead the extended gettext interface should be used.

These extra functions are taking instead of the one key string two strings and an numerical argument. The idea behind this is that using the numerical argument and the first string as a key, the implementation can select using rules specified by the translator the right plural form. The two string arguments then will be used to provide a return value in case no message catalog is found (similar to the normal gettext behavior). In this case the rules for Germanic language is used and it is assumed that the first string argument is the singular form, the second the plural form.

This has the consequence that programs without language catalogs can display the correct strings only if the program itself is written using a Germanic language. This is a limitation but since the GNU C library (as well as the GNU gettext package) are written as part of the GNU package and the coding standards for the GNU project require program being written in English, this solution nevertheless fulfills its purpose.

Function: char * ngettext (const char *msgid1, const char *msgid2, unsigned long int n)
The ngettext function is similar to the gettext function as it finds the message catalogs in the same way. But it takes two extra arguments. The msgid1 parameter must contain the singular form of the string to be converted. It is also used as the key for the search in the catalog. The msgid2 parameter is the plural form. The parameter n is used to determine the plural form. If no message catalog is found msgid1 is returned if n == 1, otherwise msgid2.

An example for the us of this function is:
  printf (ngettext ("%d file removed", "%d files removed", n), n);
Please note that the numeric value n has to be passed to the printf function as well. It is not sufficient to pass it only to ngettext.

Function: char * dngettext (const char *domain, const char *msgid1, const char *msgid2, unsigned long int n)
The dngettext is similar to the dgettext function in the way the message catalog is selected. The difference is that it takes two extra parameter to provide the correct plural form. These two parameters are handled in the same way ngettext handles them.

Function: char * dcngettext (const char *domain, const char *msgid1, const char *msgid2, unsigned long int n, int category)
The dcngettext is similar to the dcgettext function in the way the message catalog is selected. The difference is that it takes two extra parameter to provide the correct plural form. These two parameters are handled in the same way ngettext handles them.

The problem of plural forms

A description of the problem can be found at the beginning of the last section. Now there is the question how to solve it. Without the input of linguists (which was not available) it was not possible to determine whether there are only a few different forms in which plural forms are formed or whether the number can increase with every new supported language.

Therefore the solution implemented is to allow the translator to specify the rules of how to select the plural form. Since the formula varies with every language this is the only viable solution except for hardcoding the information in the code (which still would require the possibility of extensions to not prevent the use of new languages). The details are explained in the GNU gettext manual. Here only a a bit of information is provided.

The information about the plural form selection has to be stored in the header entry (the one with the empty (msgid string). It looks like this:
Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
The nplurals value must be a decimal number which specifies how many different plural forms exist for this language. The string following plural is an expression which is using the C language syntax. Exceptions are that no negative number are allowed, numbers must be decimal, and the only variable allowed is n. This expression will be evaluated whenever one of the functions ngettext, dngettext, or dcngettext is called. The numeric value passed to these functions is then substituted for all uses of the variable n in the expression. The resulting value then must be greater or equal to zero and smaller than the value given as the value of nplurals.

The following rules are known at this point. The language with families are listed. But this does not necessarily mean the information can be generalized for the whole family (as can be easily seen in the table below).(1).}

Only one form:
Some languages only require one single form. There is no distinction between the singular and plural form. An appropriate header entry would look like this:
Plural-Forms: nplurals=1; plural=0;
Languages with this property include:
Finno-Ugric family
Hungarian
Asian family
Japanese
Turkic/Altaic family
Turkish
Two forms, singular used for one only
This is the form used in most existing programs since it is what English is using. A header entry would look like this:
Plural-Forms: nplurals=2; plural=n != 1;
(Note: this uses the feature of C expressions that boolean expressions have to value zero or one.) Languages with this property include:
Germanic family
Danish, Dutch, English, German, Norwegian, Swedish
Finno-Ugric family
Estonian, Finnish
Latin/Greek family
Greek
Semitic family
Hebrew
Romance family
Italian, Spanish
Artificial
Esperanto
Two forms, singular used for zero and one
Exceptional case in the language family. The header entry would be:
Plural-Forms: nplurals=2; plural=n>1;
Languages with this property include:
Romanic family
French
Three forms, special cases for one and two
The header entry would be:
Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
Languages with this property include:
Celtic
Gaeilge
Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
The header entry would look like this:
Plural-Forms: nplurals=3; \
    plural=n%100/10==1 ? 2 : n%10==1 ? 0 : (n+9)%10>3 ? 2 : 1;
Languages with this property include:
Slavic family
Czech, Russian, Slovak
Three forms, special case for one and some numbers ending in 2, 3, or 4
The header entry would look like this:
Plural-Forms: nplurals=3; \
    plural=n==1 ? 0 : \
           n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
(Continuation in the next line is possible.) Languages with this property include:
Slavic family
Polish
Four forms, special case for one and all numbers ending in 2, 3, or 4
The header entry would look like this:
Plural-Forms: nplurals=4; \
    plural=n==1 ? 0 : n%10==2 ? 1 : n%10==3 || n%10==4 ? 2 : 3;
Languages with this property include:
Slavic family
Slovenian
How to specify the output character set gettext uses

gettext not only looks up a translation in a message catalog. It also converts the translation on the fly to the desired output character set. This is useful if the user is working in a different character set than the translator who created the message catalog, because it avoids distributing variants of message catalogs which differ only in the character set.

The output character set is, by default, the value of nl_langinfo (CODESET), which depends on the LC_CTYPE part of the current locale. But programs which store strings in a locale independent way (e.g. UTF-8) can request that gettext and related functions return the translations in that encoding, by use of the bind_textdomain_codeset function.

Note that the msgid argument to gettext is not subject to character set conversion. Also, when gettext does not find a translation for msgid, it returns msgid unchanged -- independently of the current output character set. It is therefore recommended that all msgids be US-ASCII strings.

Function: char * bind_textdomain_codeset (const char *domainname, const char *codeset)
The bind_textdomain_codeset function can be used to specify the output character set for message catalogs for domain domainname. The codeset argument must be a valid codeset name which can be used for the iconv_open function, or a null pointer.

If the codeset parameter is the null pointer, bind_textdomain_codeset returns the currently selected codeset for the domain with the name domainname. It returns NULL if no codeset has yet been selected.

The bind_textdomain_codeset function can be used several times. If used multiple times with the same domainname argument, the later call overrides the settings made by the earlier one.

The bind_textdomain_codeset function returns a pointer to a string containing the name of the selected codeset. The string is allocated internally in the function and must not be changed by the user. If the system went out of core during the execution of bind_textdomain_codeset, the return value is NULL and the global variable errno is set accordingly. @end deftypefun

How to use gettext in GUI programs

One place where the gettext functions, if used normally, have big problems is within programs with graphical user interfaces (GUIs). The problem is that many of the strings which have to be translated are very short. They have to appear in pull-down menus which restricts the length. But strings which are not containing entire sentences or at least large fragments of a sentence may appear in more than one situation in the program but might have different translations. This is especially true for the one-word strings which are frequently used in GUI programs.

As a consequence many people say that the gettext approach is wrong and instead catgets should be used which indeed does not have this problem. But there is a very simple and powerful method to handle these kind of problems with the gettext functions.

As as example consider the following fictional situation. A GUI program has a menu bar with the following entries:
+------------+------------+--------------------------------------+
| File       | Printer    |                                      |
+------------+------------+--------------------------------------+
| Open     | | Select   |
| New      | | Open     |
+----------+ | Connect  |
             +----------+
To have the strings File, Printer, Open, New, Select, and Connect translated there has to be at some point in the code a call to a function of the gettext family. But in two places the string passed into the function would be Open. The translations might not be the same and therefore we are in the dilemma described above.

One solution to this problem is to artificially enlengthen the strings to make them unambiguous. But what would the program do if no translation is available? The enlengthened string is not what should be printed. So we should use a little bit modified version of the functions.

To enlengthen the strings a uniform method should be used. E.g., in the example above the strings could be chosen as
Menu|File
Menu|Printer
Menu|File|Open
Menu|File|New
Menu|Printer|Select
Menu|Printer|Open
Menu|Printer|Connect
Now all the strings are different and if now instead of gettext the following little wrapper function is used, everything works just fine:
  char *
  sgettext (const char *msgid)
  {
    char *msgval = gettext (msgid);
    if (msgval == msgid)
      msgval = strrchr (msgid, '|') + 1;
    return msgval;
  }
What this little function does is to recognize the case when no translation is available. This can be done very efficiently by a pointer comparison since the return value is the input value. If there is no translation we know that the input string is in the format we used for the Menu entries and therefore contains a | character. We simply search for the last occurrence of this character and return a pointer to the character following it. That's it!

If one now consistently uses the enlengthened string form and replaces the gettext calls with calls to sgettext (this is normally limited to very few places in the GUI implementation) then it is possible to produce a program which can be internationalized.

With advanced compilers (such as GNU C) one can write the sgettext functions as an inline function or as a macro like this:
#define sgettext(msgid) \
  ({ const char *__msgid = (msgid);            \
     char *__msgstr = gettext (__msgid);       \
     if (__msgval == __msgid)                  \
       __msgval = strrchr (__msgid, '|') + 1;  \
     __msgval; })
The other gettext functions (dgettext, dcgettext and the ngettext equivalents) can and should have corresponding functions as well which look almost identical, except for the parameters and the call to the underlying function.

Now there is of course the question why such functions do not exist in the GNU C library? There are two parts of the answer to this question.

They are easy to write and therefore can be provided by the project they are used in. This is not an answer by itself and must be seen together with the second part which is:
There is no way the C library can contain a version which can work everywhere. The problem is the selection of the character to separate the prefix from the actual string in the enlenghtened string. The examples above used | which is a quite good choice because it resembles a notation frequently used in this context and it also is a character not often used in message strings. But what if the character is used in message strings. Or if the chose character is not available in the character set on the machine one compiles (e.g., | is not required to exist for ISO C; this is why the `iso646.h' file exists in ISO C programming environments).

There is only one more comment to make left. The wrapper function above require that the translations strings are not enlengthened themselves. This is only logical. There is no need to disambiguate the strings (since they are never used as keys for a search) and one also saves quite some memory and disk space by doing this.

User influence on gettext

The last sections described what the programmer can do to internationalize the messages of the program. But it is finally up to the user to select the message s/he wants to see. S/He must understand them.

The POSIX locale model uses the environment variables LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, NUMERIC, and LC_TIME to select the locale which is to be used. This way the user can influence lots of functions. As we mentioned above the gettext functions also take advantage of this.

To understand how this happens it is necessary to take a look at the various components of the filename which gets computed to locate a message catalog. It is composed as follows:
dir_name/locale/LC_category/domain_name.mo
The default value for dir_name is system specific. It is computed from the value given as the prefix while configuring the C library. This value normally is `/usr' or `/'. For the former the complete dir_name is:
/usr/share/locale
We can use `/usr/share' since the `.mo' files containing the message catalogs are system independent, so all systems can use the same files. If the program executed the bindtextdomain function for the message domain that is currently handled, the dir_name component is exactly the value which was given to the function as the second parameter. I.e., bindtextdomain allows overwriting the only system dependent and fixed value to make it possible to address files anywhere in the filesystem.

The category is the name of the locale category which was selected in the program code. For gettext and dgettext this is always LC_MESSAGES, for dcgettext this is selected by the value of the third parameter. As said above it should be avoided to ever use a category other than LC_MESSAGES.

The locale component is computed based on the category used. Just like for the setlocale function here comes the user selection into the play. Some environment variables are examined in a fixed order and the first environment variable set determines the return value of the lookup process. In detail, for the category LC_xxx the following variables in this order are examined:

LANGUAGE

LC_ALL

LC_xxx

LANG

This looks very familiar. With the exception of the LANGUAGE environment variable this is exactly the lookup order the setlocale function uses. But why introducing the LANGUAGE variable?

The reason is that the syntax of the values these variables can have is different to what is expected by the setlocale function. If we would set LC_ALL to a value following the extended syntax that would mean the setlocale function will never be able to use the value of this variable as well. An additional variable removes this problem plus we can select the language independently of the locale setting which sometimes is useful.

While for the LC_xxx variables the value should consist of exactly one specification of a locale the LANGUAGE variable's value can consist of a colon separated list of locale names. The attentive reader will realize that this is the way we manage to implement one of our additional demands above: we want to be able to specify an ordered list of language.

Back to the constructed filename we have only one component missing. The domain_name part is the name which was either registered using the textdomain function or which was given to dgettext or dcgettext as the first parameter. Now it becomes obvious that a good choice for the domain name in the program code is a string which is closely related to the program/package name. E.g., for the GNU C Library the domain name is libc.

A limit piece of example code should show how the programmer is supposed to work:
{
  setlocale (LC_ALL, "");
  textdomain ("test-package");
  bindtextdomain ("test-package", "/usr/local/share/locale");
  puts (gettext ("Hello, world!"));
}
At the program start the default domain is messages, and the default locale is "C". The setlocale call sets the locale according to the user's environment variables; remember that correct functioning of gettext relies on the correct setting of the LC_MESSAGES locale (for looking up the message catalog) and of the LC_CTYPE locale (for the character set conversion). The textdomain call changes the default domain to test-package. The bindtextdomain call specifies that the message catalogs for the domain test-package can be found below the directory `/usr/local/share/locale'.

If now the user set in her/his environment the variable LANGUAGE to de the gettext function will try to use the translations from the file
/usr/local/share/locale/de/LC_MESSAGES/test-package.mo
From the above descriptions it should be clear which component of this filename is determined by which source.

In the above example we assumed that the LANGUAGE environment variable to de. This might be an appropriate selection but what happens if the user wants to use LC_ALL because of the wider usability and here the required value is de_DE.ISO-8859-1? We already mentioned above that a situation like this is not infrequent. E.g., a person might prefer reading a dialect and if this is not available fall back on the standard language.

The gettext functions know about situations like this and can handle them gracefully. The functions recognize the format of the value of the environment variable. It can split the value is different pieces and by leaving out the only or the other part it can construct new values. This happens of course in a predictable way. To understand this one must know the format of the environment variable value. There are two more or less standardized forms:

X/Open Format
language[_territory[.codeset]][@modifier]
CEN Format (European Community Standard)
language[_territory][+audience][+special][,[sponsor][_revision]]
The functions will automatically recognize which format is used. Less specific locale names will be stripped of in the order of the following list:

revision
sponsor
special
codeset
normalized codeset
territory
audience/modifier

From the last entry one can see that the meaning of the modifier field in the X/Open format and the audience format have the same meaning. Beside one can see that the language field for obvious reasons never will be dropped.

The only new thing is the normalized codeset entry. This is another goodie which is introduced to help reducing the chaos which derives from the inability of the people to standardize the names of character sets. Instead of ISO-8859-1 one can often see 8859-1, 88591, iso8859-1, or iso_8859-1. The normalized codeset value is generated from the user-provided character set name by applying the following rules:

Remove all characters beside numbers and letters.
Fold letters to lowercase.
If the same only contains digits prepend the string "iso".

So all of the above name will be normalized to iso88591. This allows the program user much more freely choosing the locale name.

Even this extended functionality still does not help to solve the problem that completely different names can be used to denote the same locale (e.g., de and german). To be of help in this situation the locale implementation and also the gettext functions know about aliases.

The file `/usr/share/locale/locale.alias' (replace `/usr' with whatever prefix you used for configuring the C library) contains a mapping of alternative names to more regular names. The system manager is free to add new entries to fill her/his own needs. The selected locale from the environment is compared with the entries in the first column of this file ignoring the case. If they match the value of the second column is used instead for the further handling.

In the description of the format of the environment variables we already mentioned the character set as a factor in the selection of the message catalog. In fact, only catalogs which contain text written using the character set of the system/program can be used (directly; there will come a solution for this some day). This means for the user that s/he will always have to take care for this. If in the collection of the message catalogs there are files for the same language but coded using different character sets the user has to be careful.

Programs to handle message catalogs for gettext

The GNU C Library does not contain the source code for the programs to handle message catalogs for the gettext functions. As part of the GNU project the GNU gettext package contains everything the developer needs. The functionality provided by the tools in this package by far exceeds the abilities of the gencat program described above for the catgets functions.

There is a program msgfmt which is the equivalent program to the gencat program. It generates from the human-readable and -editable form of the message catalog a binary file which can be used by the gettext functions. But there are several more programs available.

The xgettext program can be used to automatically extract the translatable messages from a source file. I.e., the programmer need not take care for the translations and the list of messages which have to be translated. S/He will simply wrap the translatable string in calls to gettext et.al and the rest will be done by xgettext. This program has a lot of option which help to customize the output or do help to understand the input better.

Other programs help to manage development cycle when new messages appear in the source files or when a new translation of the messages appear. here it should only be noted that using all the tools in GNU gettext it is possible to completely automize the handling of message catalog. Beside marking the translatable string in the source code and generating the translations the developers do not have anything to do themselves.
Searching and Sorting

This chapter describes functions for searching and sorting arrays of arbitrary objects. You pass the appropriate comparison function to be applied as an argument, along with the size of the objects in the array and the total number of elements.

Defining the Comparison Function

In order to use the sorted array library functions, you have to describe how to compare the elements of the array.

To do this, you supply a comparison function to compare two elements of the array. The library will call this function, passing as arguments pointers to two array elements to be compared. Your comparison function should return a value the way strcmp (see section String/Array Comparison) does: negative if the first argument is "less" than the second, zero if they are "equal", and positive if the first argument is "greater".

Here is an example of a comparison function which works with an array of numbers of type double:
int
compare_doubles (const void *a, const void *b)
{
  const double *da = (const double *) a;
  const double *db = (const double *) b;

  return (*da > *db) - (*da < *db);
}
The header file `stdlib.h' defines a name for the data type of comparison functions. This type is a GNU extension.
int comparison_fn_t (const void *, const void *);
Array Search Function

Generally searching for a specific element in an array means that potentially all elements must be checked. The GNU C library contains functions to perform linear search. The prototypes for the following two functions can be found in `search.h'.

Function: void * lfind (const void *key, void *base, size_t *nmemb, size_t size, comparison_fn_t compar)
The lfind function searches in the array with *nmemb elements of size bytes pointed to by base for an element which matches the one pointed to by key. The function pointed to by compar is used decide whether two elements match.

The return value is a pointer to the matching element in the array starting at base if it is found. If no matching element is available NULL is returned.

The mean runtime of this function is *nmemb/2. This function should only be used elements often get added to or deleted from the array in which case it might not be useful to sort the array before searching.

Function: void * lsearch (const void *key, void *base, size_t *nmemb, size_t size, comparison_fn_t compar)
The lsearch function is similar to the lfind function. It searches the given array for an element and returns it if found. The difference is that if no matching element is found the lsearch function adds the object pointed to by key (with a size of size bytes) at the end of the array and it increments the value of *nmemb to reflect this addition.

This means for the caller that if it is not sure that the array contains the element one is searching for the memory allocated for the array starting at base must have room for at least size more bytes. If one is sure the element is in the array it is better to use lfind so having more room in the array is always necessary when calling lsearch.

To search a sorted array for an element matching the key, use the bsearch function. The prototype for this function is in the header file `stdlib.h'.

Function: void * bsearch (const void *key, const void *array, size_t count, size_t size, comparison_fn_t compare)
The bsearch function searches the sorted array array for an object that is equivalent to key. The array contains count elements, each of which is of size size bytes.

The compare function is used to perform the comparison. This function is called with two pointer arguments and should return an integer less than, equal to, or greater than zero corresponding to whether its first argument is considered less than, equal to, or greater than its second argument. The elements of the array must already be sorted in ascending order according to this comparison function.

The return value is a pointer to the matching array element, or a null pointer if no match is found. If the array contains more than one element that matches, the one that is returned is unspecified.

This function derives its name from the fact that it is implemented using the binary search algorithm.

Array Sort Function

To sort an array using an arbitrary comparison function, use the qsort function. The prototype for this function is in `stdlib.h'.

Function: void qsort (void *array, size_t count, size_t size, comparison_fn_t compare)
The qsort function sorts the array array. The array contains count elements, each of which is of size size.

The compare function is used to perform the comparison on the array elements. This function is called with two pointer arguments and should return an integer less than, equal to, or greater than zero corresponding to whether its first argument is considered less than, equal to, or greater than its second argument.

Warning: If two objects compare as equal, their order after sorting is unpredictable. That is to say, the sorting is not stable. This can make a difference when the comparison considers only part of the elements. Two elements with the same sort key may differ in other respects.

If you want the effect of a stable sort, you can get this result by writing the comparison function so that, lacking other reason distinguish between two elements, it compares them by their addresses. Note that doing this may make the sorting algorithm less efficient, so do it only if necessary.

Here is a simple example of sorting an array of doubles in numerical order, using the comparison function defined above (see section Defining the Comparison Function):
{
  double *array;
  int size;
  ...
  qsort (array, size, sizeof (double), compare_doubles);
}
The qsort function derives its name from the fact that it was originally implemented using the "quick sort" algorithm.

The implementation of qsort in this library might not be an in-place sort and might thereby use an extra amount of memory to store the array.

Searching and Sorting Example

Here is an example showing the use of qsort and bsearch with an array of structures. The objects in the array are sorted by comparing their name fields with the strcmp function. Then, we can look up individual objects based on their names.
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

/* Define an array of critters to sort. */

struct critter
  {
    const char *name;
    const char *species;
  };

struct critter muppets[] =
  {
    {"Kermit", "frog"},
    {"Piggy", "pig"},
    {"Gonzo", "whatever"},
    {"Fozzie", "bear"},
    {"Sam", "eagle"},
    {"Robin", "frog"},
    {"Animal", "animal"},
    {"Camilla", "chicken"},
    {"Sweetums", "monster"},
    {"Dr. Strangepork", "pig"},
    {"Link Hogthrob", "pig"},
    {"Zoot", "human"},
    {"Dr. Bunsen Honeydew", "human"},
    {"Beaker", "human"},
    {"Swedish Chef", "human"}
  };

int count = sizeof (muppets) / sizeof (struct critter);

/* This is the comparison function used for sorting and searching. */

int
critter_cmp (const struct critter *c1, const struct critter *c2)
{
  return strcmp (c1->name, c2->name);
}

/* Print information about a critter. */

void
print_critter (const struct critter *c)
{
  printf ("%s, the %s\n", c->name, c->species);
}

/* Do the lookup into the sorted array. */

void
find_critter (const char *name)
{
  struct critter target, *result;
  target.name = name;
  result = bsearch (&target, muppets, count, sizeof (struct critter),
                    critter_cmp);
  if (result)
    print_critter (result);
  else
    printf ("Couldn't find %s.\n", name);
}

/* Main program. */

int
main (void)
{
  int i;

  for (i = 0; i < count; i++)
    print_critter (&muppets[i]);
  printf ("\n");

  qsort (muppets, count, sizeof (struct critter), critter_cmp);

  for (i = 0; i < count; i++)
    print_critter (&muppets[i]);
  printf ("\n");

  find_critter ("Kermit");
  find_critter ("Gonzo");
  find_critter ("Janice");

  return 0;
}
The output from this program looks like:
Kermit, the frog
Piggy, the pig
Gonzo, the whatever
Fozzie, the bear
Sam, the eagle
Robin, the frog
Animal, the animal
Camilla, the chicken
Sweetums, the monster
Dr. Strangepork, the pig
Link Hogthrob, the pig
Zoot, the human
Dr. Bunsen Honeydew, the human
Beaker, the human
Swedish Chef, the human

Animal, the animal
Beaker, the human
Camilla, the chicken
Dr. Bunsen Honeydew, the human
Dr. Strangepork, the pig
Fozzie, the bear
Gonzo, the whatever
Kermit, the frog
Link Hogthrob, the pig
Piggy, the pig
Robin, the frog
Sam, the eagle
Swedish Chef, the human
Sweetums, the monster
Zoot, the human

Kermit, the frog
Gonzo, the whatever
Couldn't find Janice.
The hsearch function.

The functions mentioned so far in this chapter are searching in a sorted or unsorted array. There are other methods to organize information which later should be searched. The costs of insert, delete and search differ. One possible implementation is using hashing tables.

Function: int hcreate (size_t nel)
The hcreate function creates a hashing table which can contain at least nel elements. There is no possibility to grow this table so it is necessary to choose the value for nel wisely. The used methods to implement this function might make it necessary to make the number of elements in the hashing table larger than the expected maximal number of elements. Hashing tables usually work inefficient if they are filled 80% or more. The constant access time guaranteed by hashing can only be achieved if few collisions exist. See Knuth's "The Art of Computer Programming, Part 3: Searching and Sorting" for more information.

The weakest aspect of this function is that there can be at most one hashing table used through the whole program. The table is allocated in local memory out of control of the programmer. As an extension the GNU C library provides an additional set of functions with an reentrant interface which provide a similar interface but which allow to keep arbitrarily many hashing tables.

It is possible to use more than one hashing table in the program run if the former table is first destroyed by a call to hdestroy.

The function returns a non-zero value if successful. If it return zero something went wrong. This could either mean there is already a hashing table in use or the program runs out of memory.

Function: void hdestroy (void)
The hdestroy function can be used to free all the resources allocated in a previous call of hcreate. After a call to this function it is again possible to call hcreate and allocate a new table with possibly different size.

It is important to remember that the elements contained in the hashing table at the time hdestroy is called are not freed by this function. It is the responsibility of the program code to free those strings (if necessary at all). Freeing all the element memory is not possible without extra, separately kept information since there is no function to iterate through all available elements in the hashing table. If it is really necessary to free a table and all elements the programmer has to keep a list of all table elements and before calling hdestroy s/he has to free all element's data using this list. This is a very unpleasant mechanism and it also shows that this kind of hashing tables is mainly meant for tables which are created once and used until the end of the program run.

Entries of the hashing table and keys for the search are defined using this type:

Data type: struct ENTRY
Both elements of this structure are pointers to zero-terminated strings. This is a limiting restriction of the functionality of the hsearch functions. They can only be used for data sets which use the NUL character always and solely to terminate the records. It is not possible to handle general binary data.

char *key
Pointer to a zero-terminated string of characters describing the key for the search or the element in the hashing table.
char *data
Pointer to a zero-terminated string of characters describing the data. If the functions will be called only for searching an existing entry this element might stay undefined since it is not used.

Function: ENTRY * hsearch (ENTRY item, ACTION action)
To search in a hashing table created using hcreate the hsearch function must be used. This function can perform simple search for an element (if action has the FIND) or it can alternatively insert the key element into the hashing table, possibly replacing a previous value (if action is ENTER).

The key is denoted by a pointer to an object of type ENTRY. For locating the corresponding position in the hashing table only the key element of the structure is used.

The return value depends on the action parameter value. If it is FIND the value is a pointer to the matching element in the hashing table or NULL if no matching element exists. If action is ENTER the return value is only NULL if the programs runs out of memory while adding the new element to the table. Otherwise the return value is a pointer to the element in the hashing table which contains newly added element based on the data in key.

As mentioned before the hashing table used by the functions described so far is global and there can be at any time at most one hashing table in the program. A solution is to use the following functions which are a GNU extension. All have in common that they operate on a hashing table which is described by the content of an object of the type struct hsearch_data. This type should be treated as opaque, none of its members should be changed directly.

Function: int hcreate_r (size_t nel, struct hsearch_data *htab)
The hcreate_r function initializes the object pointed to by htab to contain a hashing table with at least nel elements. So this function is equivalent to the hcreate function except that the initialized data structure is controlled by the user.

This allows having more than one hashing table at one time. The memory necessary for the struct hsearch_data object can be allocated dynamically.

The return value is non-zero if the operation were successful. if the return value is zero something went wrong which probably means the programs runs out of memory.

Function: void hdestroy_r (struct hsearch_data *htab)
The hdestroy_r function frees all resources allocated by the hcreate_r function for this very same object htab. As for hdestroy it is the programs responsibility to free the strings for the elements of the table.

Function: int hsearch_r (ENTRY item, ACTION action, ENTRY **retval, struct hsearch_data *htab)
The hsearch_r function is equivalent to hsearch. The meaning of the first two arguments is identical. But instead of operating on a single global hashing table the function works on the table described by the object pointed to by htab (which is initialized by a call to hcreate_r).

Another difference to hcreate is that the pointer to the found entry in the table is not the return value of the functions. It is returned by storing it in a pointer variables pointed to by the retval parameter. The return value of the function is an integer value indicating success if it is non-zero and failure if it is zero. In the latter case the global variable errno signals the reason for the failure.

ENOMEM
The table is filled and hsearch_r was called with an so far unknown key and action set to ENTER.
ESRCH
The action parameter is FIND and no corresponding element is found in the table.
The tsearch function.

Another common form to organize data for efficient search is to use trees. The tsearch function family provides a nice interface to functions to organize possibly large amounts of data by providing a mean access time proportional to the logarithm of the number of elements. The GNU C library implementation even guarantees that this bound is never exceeded even for input data which cause problems for simple binary tree implementations.

The functions described in the chapter are all described in the System V and X/Open specifications and are therefore quite portable.

In contrast to the hsearch functions the tsearch functions can be used with arbitrary data and not only zero-terminated strings.

The tsearch functions have the advantage that no function to initialize data structures is necessary. A simple pointer of type void * initialized to NULL is a valid tree and can be extended or searched.

Function: void * tsearch (const void *key, void **rootp, comparison_fn_t compar)
The tsearch function searches in the tree pointed to by *rootp for an element matching key. The function pointed to by compar is used to determine whether two elements match. See section Defining the Comparison Function, for a specification of the functions which can be used for the compar parameter.

If the tree does not contain a matching entry the key value will be added to the tree. tsearch does not make a copy of the object pointed to by key (how could it since the size is unknown). Instead it adds a reference to this object which means the object must be available as long as the tree data structure is used.

The tree is represented by a pointer to a pointer since it is sometimes necessary to change the root node of the tree. So it must not be assumed that the variable pointed to by rootp has the same value after the call. This also shows that it is not safe to call the tsearch function more than once at the same time using the same tree. It is no problem to run it more than once at a time on different trees.

The return value is a pointer to the matching element in the tree. If a new element was created the pointer points to the new data (which is in fact key). If an entry had to be created and the program ran out of space NULL is returned.

Function: void * tfind (const void *key, void *const *rootp, comparison_fn_t compar)
The tfind function is similar to the tsearch function. It locates an element matching the one pointed to by key and returns a pointer to this element. But if no matching element is available no new element is entered (note that the rootp parameter points to a constant pointer). Instead the function returns NULL.

Another advantage of the tsearch function in contrast to the hsearch functions is that there is an easy way to remove elements.

Function: void * tdelete (const void *key, void **rootp, comparison_fn_t compar)
To remove a specific element matching key from the tree tdelete can be used. It locates the matching element using the same method as tfind. The corresponding element is then removed and a pointer to the parent of the deleted node is returned by the function. If there is no matching entry in the tree nothing can be deleted and the function returns NULL. If the root of the tree is deleted tdelete returns some unspecified value not equal to NULL.

Function: void tdestroy (void *vroot, __free_fn_t freefct)
If the complete search tree has to be removed one can use tdestroy. It frees all resources allocated by the tsearch function to generate the tree pointed to by vroot.

For the data in each tree node the function freefct is called. The pointer to the data is passed as the argument to the function. If no such work is necessary freefct must point to a function doing nothing. It is called in any case.

This function is a GNU extension and not covered by the System V or X/Open specifications.

In addition to the function to create and destroy the tree data structure, there is another function which allows you to apply a function to all elements of the tree. The function must have this type:
void __action_fn_t (const void *nodep, VISIT value, int level);
The nodep is the data value of the current node (once given as the key argument to tsearch). level is a numeric value which corresponds to the depth of the current node in the tree. The root node has the depth @math{0} and its children have a depth of @math{1} and so on. The VISIT type is an enumeration type.

Data Type: VISIT
The VISIT value indicates the status of the current node in the tree and how the function is called. The status of a node is either `leaf' or `internal node'. For each leaf node the function is called exactly once, for each internal node it is called three times: before the first child is processed, after the first child is processed and after both children are processed. This makes it possible to handle all three methods of tree traversal (or even a combination of them).

preorder
The current node is an internal node and the function is called before the first child was processed.
postorder
The current node is an internal node and the function is called after the first child was processed.
endorder
The current node is an internal node and the function is called after the second child was processed.
leaf
The current node is a leaf.

Function: void twalk (const void *root, __action_fn_t action)
For each node in the tree with a node pointed to by root, the twalk function calls the function provided by the parameter action. For leaf nodes the function is called exactly once with value set to leaf. For internal nodes the function is called three times, setting the value parameter or action to the appropriate value. The level argument for the action function is computed while descending the tree with increasing the value by one for the descend to a child, starting with the value @math{0} for the root node.

Since the functions used for the action parameter to twalk must not modify the tree data, it is safe to run twalk in more than one thread at the same time, working on the same tree. It is also safe to call tfind in parallel. Functions which modify the tree must not be used, otherwise the behaviour is undefined.
Pattern Matching

The GNU C Library provides pattern matching facilities for two kinds of patterns: regular expressions and file-name wildcards. The library also provides a facility for expanding variable and command references and parsing text into words in the way the shell does.

Wildcard Matching

This section describes how to match a wildcard pattern against a particular string. The result is a yes or no answer: does the string fit the pattern or not. The symbols described here are all declared in `fnmatch.h'.

Function: int fnmatch (const char *pattern, const char *string, int flags)
This function tests whether the string string matches the pattern pattern. It returns 0 if they do match; otherwise, it returns the nonzero value FNM_NOMATCH. The arguments pattern and string are both strings.

The argument flags is a combination of flag bits that alter the details of matching. See below for a list of the defined flags.

In the GNU C Library, fnmatch cannot experience an "error"---it always returns an answer for whether the match succeeds. However, other implementations of fnmatch might sometimes report "errors". They would do so by returning nonzero values that are not equal to FNM_NOMATCH.

These are the available flags for the flags argument:

FNM_FILE_NAME
Treat the `/' character specially, for matching file names. If this flag is set, wildcard constructs in pattern cannot match `/' in string. Thus, the only way to match `/' is with an explicit `/' in pattern.
FNM_PATHNAME
This is an alias for FNM_FILE_NAME; it comes from POSIX.2. We don't recommend this name because we don't use the term "pathname" for file names.
FNM_PERIOD
Treat the `.' character specially if it appears at the beginning of string. If this flag is set, wildcard constructs in pattern cannot match `.' as the first character of string. If you set both FNM_PERIOD and FNM_FILE_NAME, then the special treatment applies to `.' following `/' as well as to `.' at the beginning of string. (The shell uses the FNM_PERIOD and FNM_FILE_NAME flags together for matching file names.)
FNM_NOESCAPE
Don't treat the `\' character specially in patterns. Normally, `\' quotes the following character, turning off its special meaning (if any) so that it matches only itself. When quoting is enabled, the pattern `\?' matches only the string `?', because the question mark in the pattern acts like an ordinary character. If you use FNM_NOESCAPE, then `\' is an ordinary character.
FNM_LEADING_DIR
Ignore a trailing sequence of characters starting with a `/' in string; that is to say, test whether string starts with a directory name that pattern matches. If this flag is set, either `foo*' or `foobar' as a pattern would match the string `foobar/frobozz'.
FNM_CASEFOLD
Ignore case in comparing string to pattern.
FNM_EXTMATCH
Recognize beside the normal patterns also the extended patterns introduced in `ksh'. The patterns are written in the form explained in the following table where pattern-list is a | separated list of patterns.
?(pattern-list)
The pattern matches if zero or one occurences of any of the patterns in the pattern-list allow matching the input string.
*(pattern-list)
The pattern matches if zero or more occurences of any of the patterns in the pattern-list allow matching the input string.
+(pattern-list)
The pattern matches if one or more occurences of any of the patterns in the pattern-list allow matching the input string.
@(pattern-list)
The pattern matches if exactly one occurence of any of the patterns in the pattern-list allows matching the input string.
!(pattern-list)
The pattern matches if the input string cannot be matched with any of the patterns in the pattern-list.
Globbing

The archetypal use of wildcards is for matching against the files in a directory, and making a list of all the matches. This is called globbing.

You could do this using fnmatch, by reading the directory entries one by one and testing each one with fnmatch. But that would be slow (and complex, since you would have to handle subdirectories by hand).

The library provides a function glob to make this particular use of wildcards convenient. glob and the other symbols in this section are declared in `glob.h'.

Calling glob

The result of globbing is a vector of file names (strings). To return this vector, glob uses a special data type, glob_t, which is a structure. You pass glob the address of the structure, and it fills in the structure's fields to tell you about the results.

Data Type: glob_t
This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size. The GNU implementation contains some more fields which are non-standard extensions.

gl_pathc
The number of elements in the vector, excluding the initial null entries if the GLOB_DOOFFS flag is used (see gl_offs below).
gl_pathv
The address of the vector. This field has type char **.
gl_offs
The offset of the first real element of the vector, from its nominal address in the gl_pathv field. Unlike the other fields, this is always an input to glob, rather than an output from it. If you use a nonzero offset, then that many elements at the beginning of the vector are left empty. (The glob function fills them with null pointers.) The gl_offs field is meaningful only if you use the GLOB_DOOFFS flag. Otherwise, the offset is always zero regardless of what is in this field, and the first real element comes at the beginning of the vector.
gl_closedir
The address of an alternative implementation of the closedir function. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is void (*) (void *). This is a GNU extension.
gl_readdir
The address of an alternative implementation of the readdir function used to read the contents of a directory. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is struct dirent *(*) (void *). This is a GNU extension.
gl_opendir
The address of an alternative implementation of the opendir function. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is void *(*) (const char *). This is a GNU extension.
gl_stat
The address of an alternative implementation of the stat function to get information about an object in the filesystem. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is int (*) (const char *, struct stat *). This is a GNU extension.
gl_lstat
The address of an alternative implementation of the lstat function to get information about an object in the filesystems, not following symbolic links. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is int (*) (const char *, struct stat *). This is a GNU extension.
For use in the glob64 function `glob.h' contains another definition for a very similar type. glob64_t differs from glob_t only in the types of the members gl_readdir, gl_stat, and gl_lstat.

Data Type: glob64_t
This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size. The GNU implementation contains some more fields which are non-standard extensions.

gl_pathc
The number of elements in the vector, excluding the initial null entries if the GLOB_DOOFFS flag is used (see gl_offs below).
gl_pathv
The address of the vector. This field has type char **.
gl_offs
The offset of the first real element of the vector, from its nominal address in the gl_pathv field. Unlike the other fields, this is always an input to glob, rather than an output from it. If you use a nonzero offset, then that many elements at the beginning of the vector are left empty. (The glob function fills them with null pointers.) The gl_offs field is meaningful only if you use the GLOB_DOOFFS flag. Otherwise, the offset is always zero regardless of what is in this field, and the first real element comes at the beginning of the vector.
gl_closedir
The address of an alternative implementation of the closedir function. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is void (*) (void *). This is a GNU extension.
gl_readdir
The address of an alternative implementation of the readdir64 function used to read the contents of a directory. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is struct dirent64 *(*) (void *). This is a GNU extension.
gl_opendir
The address of an alternative implementation of the opendir function. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is void *(*) (const char *). This is a GNU extension.
gl_stat
The address of an alternative implementation of the stat64 function to get information about an object in the filesystem. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is int (*) (const char *, struct stat64 *). This is a GNU extension.
gl_lstat
The address of an alternative implementation of the lstat64 function to get information about an object in the filesystems, not following symbolic links. It is used if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The type of this field is int (*) (const char *, struct stat64 *). This is a GNU extension.

Function: int glob (const char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob_t *vector-ptr)
The function glob does globbing using the pattern pattern in the current directory. It puts the result in a newly allocated vector, and stores the size and address of this vector into *vector-ptr. The argument flags is a combination of bit flags; see section Flags for Globbing, for details of the flags.

The result of globbing is a sequence of file names. The function glob allocates a string for each resulting word, then allocates a vector of type char ** to store the addresses of these strings. The last element of the vector is a null pointer. This vector is called the word vector.

To return this vector, glob stores both its address and its length (number of elements, not counting the terminating null pointer) into *vector-ptr.

Normally, glob sorts the file names alphabetically before returning them. You can turn this off with the flag GLOB_NOSORT if you want to get the information as fast as possible. Usually it's a good idea to let glob sort them--if you process the files in alphabetical order, the users will have a feel for the rate of progress that your application is making.

If glob succeeds, it returns 0. Otherwise, it returns one of these error codes:

GLOB_ABORTED
There was an error opening a directory, and you used the flag GLOB_ERR or your specified errfunc returned a nonzero value. See below for an explanation of the GLOB_ERR flag and errfunc.
GLOB_NOMATCH
The pattern didn't match any existing files. If you use the GLOB_NOCHECK flag, then you never get this error code, because that flag tells glob to pretend that the pattern matched at least one file.
GLOB_NOSPACE
It was impossible to allocate memory to hold the result.
In the event of an error, glob stores information in *vector-ptr about all the matches it has found so far.

It is important to notive that the glob function will not fail if it encounters directories or files which cannot be handled without the LFS interfaces. The implementation of glob is supposed to use these functions internally. This at least is the assumptions made by the Unix standard. The GNU extension of allowing the user to provide own directory handling and stat functions complicates things a bit. If these callback functions are used and a large file or directory is encountered glob can fail.

Function: int glob64 (const char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob64_t *vector-ptr)
The glob64 function was added as part of the Large File Summit extensions but is not part of the original LFS proposal. The reason for this is simple: it is not necessary. The necessity for a glob64 function is added by the extensions of the GNU glob implementation which allows the user to provide own directory handling and stat functions. The readdir and stat functions do depend on the choice of _FILE_OFFSET_BITS since the definition of the types struct dirent and struct stat will change depending on the choice.

Beside this difference the glob64 works just like glob in all aspects.

This function is a GNU extension.

Flags for Globbing

This section describes the flags that you can specify in the flags argument to glob. Choose the flags you want, and combine them with the C bitwise OR operator |.

GLOB_APPEND
Append the words from this expansion to the vector of words produced by previous calls to glob. This way you can effectively expand several words as if they were concatenated with spaces between them. In order for appending to work, you must not modify the contents of the word vector structure between calls to glob. And, if you set GLOB_DOOFFS in the first call to glob, you must also set it when you append to the results. Note that the pointer stored in gl_pathv may no longer be valid after you call glob the second time, because glob might have relocated the vector. So always fetch gl_pathv from the glob_t structure after each glob call; never save the pointer across calls.
GLOB_DOOFFS
Leave blank slots at the beginning of the vector of words. The gl_offs field says how many slots to leave. The blank slots contain null pointers.
GLOB_ERR
Give up right away and report an error if there is any difficulty reading the directories that must be read in order to expand pattern fully. Such difficulties might include a directory in which you don't have the requisite access. Normally, glob tries its best to keep on going despite any errors, reading whatever directories it can. You can exercise even more control than this by specifying an error-handler function errfunc when you call glob. If errfunc is not a null pointer, then glob doesn't give up right away when it can't read a directory; instead, it calls errfunc with two arguments, like this:
(*errfunc) (filename, error-code)
The argument filename is the name of the directory that glob couldn't open or couldn't read, and error-code is the errno value that was reported to glob. If the error handler function returns nonzero, then glob gives up right away. Otherwise, it continues.
GLOB_MARK
If the pattern matches the name of a directory, append `/' to the directory's name when returning it.
GLOB_NOCHECK
If the pattern doesn't match any file names, return the pattern itself as if it were a file name that had been matched. (Normally, when the pattern doesn't match anything, glob returns that there were no matches.)
GLOB_NOSORT
Don't sort the file names; return them in no particular order. (In practice, the order will depend on the order of the entries in the directory.) The only reason not to sort is to save time.
GLOB_NOESCAPE
Don't treat the `\' character specially in patterns. Normally, `\' quotes the following character, turning off its special meaning (if any) so that it matches only itself. When quoting is enabled, the pattern `\?' matches only the string `?', because the question mark in the pattern acts like an ordinary character. If you use GLOB_NOESCAPE, then `\' is an ordinary character. glob does its work by calling the function fnmatch repeatedly. It handles the flag GLOB_NOESCAPE by turning on the FNM_NOESCAPE flag in calls to fnmatch.
More Flags for Globbing

Beside the flags described in the last section, the GNU implementation of glob allows a few more flags which are also defined in the `glob.h' file. Some of the extensions implement functionality which is available in modern shell implementations.

GLOB_PERIOD
The . character (period) is treated special. It cannot be matched by wildcards. See section Wildcard Matching, FNM_PERIOD.
GLOB_MAGCHAR
The GLOB_MAGCHAR value is not to be given to glob in the flags parameter. Instead, glob sets this bit in the gl_flags element of the glob_t structure provided as the result if the pattern used for matching contains any wildcard character.
GLOB_ALTDIRFUNC
Instead of the using the using the normal functions for accessing the filesystem the glob implementation uses the user-supplied functions specified in the structure pointed to by pglob parameter. For more information about the functions refer to the sections about directory handling see section Accessing Directories, and section Reading the Attributes of a File.
GLOB_BRACE
If this flag is given the handling of braces in the pattern is changed. It is now required that braces appear correctly grouped. I.e., for each opening brace there must be a closing one. Braces can be used recursively. So it is possible to define one brace expression in another one. It is important to note that the range of each brace expression is completely contained in the outer brace expression (if there is one). The string between the matching braces is separated into single expressions by splitting at , (comma) characters. The commas themself are discarded. Please note what we said above about recursive brace expressions. The commas used to separate the subexpressions must be at the same level. Commas in brace subexpressions are not matched. They are used during expansion of the brace expression of the deeper level. The example below shows this
glob ("{foo/{,bar,biz},baz}", GLOB_BRACE, NULL, &result)
is equivalent to the sequence
glob ("foo/", GLOB_BRACE, NULL, &result)
glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)
glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
if we leave aside error handling.
GLOB_NOMAGIC
If the pattern contains no wildcard constructs (it is a literal file name), return it as the sole "matching" word, even if no file exists by that name.
GLOB_TILDE
If this flag is used the character ~ (tilde) is handled special if it appears at the beginning of the pattern. Instead of being taken verbatim it is used to represent the home directory of a known user. If ~ is the only character in pattern or it is followed by a / (slash), the home directory of the process owner is substituted. Using getlogin and getpwnam the information is read from the system databases. As an example take user bart with his home directory at `/home/bart'. For him a call like
glob ("~/bin/*", GLOB_TILDE, NULL, &result)
would return the contents of the directory `/home/bart/bin'. Instead of referring to the own home directory it is also possible to name the home directory of other users. To do so one has to append the user name after the tilde character. So the contents of user homer's `bin' directory can be retrieved by
glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)
If the user name is not valid or the home directory cannot be determined for some reason the pattern is left untouched and itself used as the result. I.e., if in the last example home is not available the tilde expansion yields to "~homer/bin/*" and glob is not looking for a directory named ~homer. This functionality is equivalent to what is available in C-shells if the nonomatch flag is set.
GLOB_TILDE_CHECK
If this flag is used glob behaves like as if GLOB_TILDE is given. The only difference is that if the user name is not available or the home directory cannot be determined for other reasons this leads to an error. glob will return GLOB_NOMATCH instead of using the pattern itself as the name. This functionality is equivalent to what is available in C-shells if nonomatch flag is not set.
GLOB_ONLYDIR
If this flag is used the globbing function takes this as a hint that the caller is only interested in directories matching the pattern. If the information about the type of the file is easily available non-directories will be rejected but no extra work will be done to determine the information for each file. I.e., the caller must still be able to filter directories out. This functionality is only available with the GNU glob implementation. It is mainly used internally to increase the performance but might be useful for a user as well and therefore is documented here.
Calling glob will in most cases allocate resources which are used to represent the result of the function call. If the same object of type glob_t is used in multiple call to glob the resources are freed or reused so that no leaks appear. But this does not include the time when all glob calls are done.

Function: void globfree (glob_t *pglob)
The globfree function frees all resources allocated by previous calls to glob associated with the object pointed to by pglob. This function should be called whenever the currently used glob_t typed object isn't used anymore.

Function: void globfree64 (glob64_t *pglob)
This function is equivalent to globfree but it frees records of type glob64_t which were allocated by glob64.

Regular Expression Matching

The GNU C library supports two interfaces for matching regular expressions. One is the standard POSIX.2 interface, and the other is what the GNU system has had for many years.

Both interfaces are declared in the header file `regex.h'. If you define _POSIX_C_SOURCE, then only the POSIX.2 functions, structures, and constants are declared.

POSIX Regular Expression Compilation

Before you can actually match a regular expression, you must compile it. This is not true compilation--it produces a special data structure, not machine instructions. But it is like ordinary compilation in that its purpose is to enable you to "execute" the pattern fast. (See section Matching a Compiled POSIX Regular Expression, for how to use the compiled regular expression for matching.)

There is a special data type for compiled regular expressions:

Data Type: regex_t
This type of object holds a compiled regular expression. It is actually a structure. It has just one field that your programs should look at:

re_nsub
This field holds the number of parenthetical subexpressions in the regular expression that was compiled.
There are several other fields, but we don't describe them here, because only the functions in the library should use them.

After you create a regex_t object, you can compile a regular expression into it by calling regcomp.

Function: int regcomp (regex_t *compiled, const char *pattern, int cflags)
The function regcomp "compiles" a regular expression into a data structure that you can use with regexec to match against a string. The compiled regular expression format is designed for efficient matching. regcomp stores it into *compiled.

It's up to you to allocate an object of type regex_t and pass its address to regcomp.

The argument cflags lets you specify various options that control the syntax and semantics of regular expressions. See section Flags for POSIX Regular Expressions.

If you use the flag REG_NOSUB, then regcomp omits from the compiled regular expression the information necessary to record how subexpressions actually match. In this case, you might as well pass 0 for the matchptr and nmatch arguments when you call regexec.

If you don't use REG_NOSUB, then the compiled regular expression does have the capacity to record how subexpressions match. Also, regcomp tells you how many subexpressions pattern has, by storing the number in compiled->re_nsub. You can use that value to decide how long an array to allocate to hold information about subexpression matches.

regcomp returns 0 if it succeeds in compiling the regular expression; otherwise, it returns a nonzero error code (see the table below). You can use regerror to produce an error message string describing the reason for a nonzero value; see section POSIX Regexp Matching Cleanup.

Here are the possible nonzero values that regcomp can return:

REG_BADBR
There was an invalid `\{...\}' construct in the regular expression. A valid `\{...\}' construct must contain either a single number, or two numbers in increasing order separated by a comma.
REG_BADPAT
There was a syntax error in the regular expression.
REG_BADRPT
A repetition operator such as `?' or `*' appeared in a bad position (with no preceding subexpression to act on).
REG_ECOLLATE
The regular expression referred to an invalid collating element (one not defined in the current locale for string collation). See section Categories of Activities that Locales Affect.
REG_ECTYPE
The regular expression referred to an invalid character class name.
REG_EESCAPE
The regular expression ended with `\'.
REG_ESUBREG
There was an invalid number in the `\digit' construct.
REG_EBRACK
There were unbalanced square brackets in the regular expression.
REG_EPAREN
An extended regular expression had unbalanced parentheses, or a basic regular expression had unbalanced `\(' and `\)'.
REG_EBRACE
The regular expression had unbalanced `\{' and `\}'.
REG_ERANGE
One of the endpoints in a range expression was invalid.
REG_ESPACE
regcomp ran out of memory.
Flags for POSIX Regular Expressions

These are the bit flags that you can use in the cflags operand when compiling a regular expression with regcomp.

REG_EXTENDED
Treat the pattern as an extended regular expression, rather than as a basic regular expression.
REG_ICASE
Ignore case when matching letters.
REG_NOSUB
Don't bother storing the contents of the matches-ptr array.
REG_NEWLINE
Treat a newline in string as dividing string into multiple lines, so that `$' can match before the newline and `^' can match after. Also, don't permit `.' to match a newline, and don't permit `[^...]' to match a newline. Otherwise, newline acts like any other ordinary character.
Matching a Compiled POSIX Regular Expression

Once you have compiled a regular expression, as described in section POSIX Regular Expression Compilation, you can match it against strings using regexec. A match anywhere inside the string counts as success, unless the regular expression contains anchor characters (`^' or `$').

Function: int regexec (regex_t *compiled, char *string, size_t nmatch, regmatch_t matchptr [], int eflags)
This function tries to match the compiled regular expression *compiled against string.

regexec returns 0 if the regular expression matches; otherwise, it returns a nonzero value. See the table below for what nonzero values mean. You can use regerror to produce an error message string describing the reason for a nonzero value; see section POSIX Regexp Matching Cleanup.

The argument eflags is a word of bit flags that enable various options.

If you want to get information about what part of string actually matched the regular expression or its subexpressions, use the arguments matchptr and nmatch. Otherwise, pass 0 for nmatch, and NULL for matchptr. See section Match Results with Subexpressions.

You must match the regular expression with the same set of current locales that were in effect when you compiled the regular expression.

The function regexec accepts the following flags in the eflags argument:

REG_NOTBOL
Do not regard the beginning of the specified string as the beginning of a line; more generally, don't make any assumptions about what text might precede it.
REG_NOTEOL
Do not regard the end of the specified string as the end of a line; more generally, don't make any assumptions about what text might follow it.
Here are the possible nonzero values that regexec can return:

REG_NOMATCH
The pattern didn't match the string. This isn't really an error.
REG_ESPACE
regexec ran out of memory.
Match Results with Subexpressions

When regexec matches parenthetical subexpressions of pattern, it records which parts of string they match. It returns that information by storing the offsets into an array whose elements are structures of type regmatch_t. The first element of the array (index 0) records the part of the string that matched the entire regular expression. Each other element of the array records the beginning and end of the part that matched a single parenthetical subexpression.

Data Type: regmatch_t
This is the data type of the matcharray array that you pass to regexec. It contains two structure fields, as follows:

rm_so
The offset in string of the beginning of a substring. Add this value to string to get the address of that part.
rm_eo
The offset in string of the end of the substring.

Data Type: regoff_t
regoff_t is an alias for another signed integer type. The fields of regmatch_t have type regoff_t.

The regmatch_t elements correspond to subexpressions positionally; the first element (index 1) records where the first subexpression matched, the second element records the second subexpression, and so on. The order of the subexpressions is the order in which they begin.

When you call regexec, you specify how long the matchptr array is, with the nmatch argument. This tells regexec how many elements to store. If the actual regular expression has more than nmatch subexpressions, then you won't get offset information about the rest of them. But this doesn't alter whether the pattern matches a particular string or not.

If you don't want regexec to return any information about where the subexpressions matched, you can either supply 0 for nmatch, or use the flag REG_NOSUB when you compile the pattern with regcomp.

Complications in Subexpression Matching

Sometimes a subexpression matches a substring of no characters. This happens when `f\(o*\)' matches the string `fum'. (It really matches just the `f'.) In this case, both of the offsets identify the point in the string where the null substring was found. In this example, the offsets are both 1.

Sometimes the entire regular expression can match without using some of its subexpressions at all--for example, when `ba\(na\)*' matches the string `ba', the parenthetical subexpression is not used. When this happens, regexec stores -1 in both fields of the element for that subexpression.

Sometimes matching the entire regular expression can match a particular subexpression more than once--for example, when `ba\(na\)*' matches the string `bananana', the parenthetical subexpression matches three times. When this happens, regexec usually stores the offsets of the last part of the string that matched the subexpression. In the case of `bananana', these offsets are 6 and 8.

But the last match is not always the one that is chosen. It's more accurate to say that the last opportunity to match is the one that takes precedence. What this means is that when one subexpression appears within another, then the results reported for the inner subexpression reflect whatever happened on the last match of the outer subexpression. For an example, consider `\(ba\(na\)*s \)*' matching the string `bananas bas '. The last time the inner expression actually matches is near the end of the first word. But it is considered again in the second word, and fails to match there. regexec reports nonuse of the "na" subexpression.

Another place where this rule applies is when the regular expression
\(ba\(na\)*s \|nefer\(ti\)* \)*
matches `bananas nefertiti'. The "na" subexpression does match in the first word, but it doesn't match in the second word because the other alternative is used there. Once again, the second repetition of the outer subexpression overrides the first, and within that second repetition, the "na" subexpression is not used. So regexec reports nonuse of the "na" subexpression.

POSIX Regexp Matching Cleanup

When you are finished using a compiled regular expression, you can free the storage it uses by calling regfree.

Function: void regfree (regex_t *compiled)
Calling regfree frees all the storage that *compiled points to. This includes various internal fields of the regex_t structure that aren't documented in this manual.

regfree does not free the object *compiled itself.

You should always free the space in a regex_t structure with regfree before using the structure to compile another regular expression.

When regcomp or regexec reports an error, you can use the function regerror to turn it into an error message string.

Function: size_t regerror (int errcode, regex_t *compiled, char *buffer, size_t length)
This function produces an error message string for the error code errcode, and stores the string in length bytes of memory starting at buffer. For the compiled argument, supply the same compiled regular expression structure that regcomp or regexec was working with when it got the error. Alternatively, you can supply NULL for compiled; you will still get a meaningful error message, but it might not be as detailed.

If the error message can't fit in length bytes (including a terminating null character), then regerror truncates it. The string that regerror stores is always null-terminated even if it has been truncated.

The return value of regerror is the minimum length needed to store the entire error message. If this is less than length, then the error message was not truncated, and you can use it. Otherwise, you should call regerror again with a larger buffer.

Here is a function which uses regerror, but always dynamically allocates a buffer for the error message:
char *get_regerror (int errcode, regex_t *compiled)
{
  size_t length = regerror (errcode, compiled, NULL, 0);
  char *buffer = xmalloc (length);
  (void) regerror (errcode, compiled, buffer, length);
  return buffer;
}
Shell-Style Word Expansion

Word expansion means the process of splitting a string into words and substituting for variables, commands, and wildcards just as the shell does.

For example, when you write `ls -l foo.c', this string is split into three separate words---`ls', `-l' and `foo.c'. This is the most basic function of word expansion.

When you write `ls *.c', this can become many words, because the word `*.c' can be replaced with any number of file names. This is called wildcard expansion, and it is also a part of word expansion.

When you use `echo $PATH' to print your path, you are taking advantage of variable substitution, which is also part of word expansion.

Ordinary programs can perform word expansion just like the shell by calling the library function wordexp.

The Stages of Word Expansion

When word expansion is applied to a sequence of words, it performs the following transformations in the order shown here:

Tilde expansion: Replacement of `~foo' with the name of the home directory of `foo'.
Next, three different transformations are applied in the same step, from left to right:

Variable substitution: Environment variables are substituted for references such as `$foo'.
Command substitution: Constructs such as ``cat foo`' and the equivalent `$(cat foo)' are replaced with the output from the inner command.
Arithmetic expansion: Constructs such as `$(($x-1))' are replaced with the result of the arithmetic computation.

Field splitting: subdivision of the text into words.
Wildcard expansion: The replacement of a construct such as `*.c' with a list of `.c' file names. Wildcard expansion applies to an entire word at a time, and replaces that word with 0 or more file names that are themselves words.
Quote removal: The deletion of string-quotes, now that they have done their job by inhibiting the above transformations when appropriate.

For the details of these transformations, and how to write the constructs that use them, see The BASH Manual (to appear).

Calling wordexp

All the functions, constants and data types for word expansion are declared in the header file `wordexp.h'.

Word expansion produces a vector of words (strings). To return this vector, wordexp uses a special data type, wordexp_t, which is a structure. You pass wordexp the address of the structure, and it fills in the structure's fields to tell you about the results.

Data Type: wordexp_t
This data type holds a pointer to a word vector. More precisely, it records both the address of the word vector and its size.

we_wordc
The number of elements in the vector.
we_wordv
The address of the vector. This field has type char **.
we_offs
The offset of the first real element of the vector, from its nominal address in the we_wordv field. Unlike the other fields, this is always an input to wordexp, rather than an output from it. If you use a nonzero offset, then that many elements at the beginning of the vector are left empty. (The wordexp function fills them with null pointers.) The we_offs field is meaningful only if you use the WRDE_DOOFFS flag. Otherwise, the offset is always zero regardless of what is in this field, and the first real element comes at the beginning of the vector.

Function: int wordexp (const char *words, wordexp_t *word-vector-ptr, int flags)
Perform word expansion on the string words, putting the result in a newly allocated vector, and store the size and address of this vector into *word-vector-ptr. The argument flags is a combination of bit flags; see section Flags for Word Expansion, for details of the flags.

You shouldn't use any of the characters `|&;<>' in the string words unless they are quoted; likewise for newline. If you use these characters unquoted, you will get the WRDE_BADCHAR error code. Don't use parentheses or braces unless they are quoted or part of a word expansion construct. If you use quotation characters `'"`', they should come in pairs that balance.

The results of word expansion are a sequence of words. The function wordexp allocates a string for each resulting word, then allocates a vector of type char ** to store the addresses of these strings. The last element of the vector is a null pointer. This vector is called the word vector.

To return this vector, wordexp stores both its address and its length (number of elements, not counting the terminating null pointer) into *word-vector-ptr.

If wordexp succeeds, it returns 0. Otherwise, it returns one of these error codes:

WRDE_BADCHAR
The input string words contains an unquoted invalid character such as `|'.
WRDE_BADVAL
The input string refers to an undefined shell variable, and you used the flag WRDE_UNDEF to forbid such references.
WRDE_CMDSUB
The input string uses command substitution, and you used the flag WRDE_NOCMD to forbid command substitution.
WRDE_NOSPACE
It was impossible to allocate memory to hold the result. In this case, wordexp can store part of the results--as much as it could allocate room for.
WRDE_SYNTAX
There was a syntax error in the input string. For example, an unmatched quoting character is a syntax error.

Function: void wordfree (wordexp_t *word-vector-ptr)
Free the storage used for the word-strings and vector that *word-vector-ptr points to. This does not free the structure *word-vector-ptr itself--only the other data it points to.

Flags for Word Expansion

This section describes the flags that you can specify in the flags argument to wordexp. Choose the flags you want, and combine them with the C operator |.

WRDE_APPEND
Append the words from this expansion to the vector of words produced by previous calls to wordexp. This way you can effectively expand several words as if they were concatenated with spaces between them. In order for appending to work, you must not modify the contents of the word vector structure between calls to wordexp. And, if you set WRDE_DOOFFS in the first call to wordexp, you must also set it when you append to the results.
WRDE_DOOFFS
Leave blank slots at the beginning of the vector of words. The we_offs field says how many slots to leave. The blank slots contain null pointers.
WRDE_NOCMD
Don't do command substitution; if the input requests command substitution, report an error.
WRDE_REUSE
Reuse a word vector made by a previous call to wordexp. Instead of allocating a new vector of words, this call to wordexp will use the vector that already exists (making it larger if necessary). Note that the vector may move, so it is not safe to save an old pointer and use it again after calling wordexp. You must fetch we_pathv anew after each call.
WRDE_SHOWERR
Do show any error messages printed by commands run by command substitution. More precisely, allow these commands to inherit the standard error output stream of the current process. By default, wordexp gives these commands a standard error stream that discards all output.
WRDE_UNDEF
If the input refers to a shell variable that is not defined, report an error.
wordexp Example

Here is an example of using wordexp to expand several strings and use the results to run a shell command. It also shows the use of WRDE_APPEND to concatenate the expansions and of wordfree to free the space allocated by wordexp.
int
expand_and_execute (const char *program, const char *options)
{
  wordexp_t result;
  pid_t pid
  int status, i;

  /* Expand the string for the program to run.  */
  switch (wordexp (program, &result, 0))
    {
    case 0:			/* Successful.  */
      break;
    case WRDE_NOSPACE:
      /* If the error was WRDE_NOSPACE,
         then perhaps part of the result was allocated.  */
      wordfree (&result);
    default:                    /* Some other error.  */
      return -1;
    }

  /* Expand the strings specified for the arguments.  */
  for (i = 0; args[i]; i++)
    {
      if (wordexp (options, &result, WRDE_APPEND))
        {
          wordfree (&result);
          return -1;
        }
    }

  pid = fork ();
  if (pid == 0)
    {
      /* This is the child process.  Execute the command. */
      execv (result.we_wordv[0], result.we_wordv);
      exit (EXIT_FAILURE);
    }
  else if (pid < 0)
    /* The fork failed.  Report failure.  */
    status = -1;
  else
    /* This is the parent process.  Wait for the child to complete.  */
    if (waitpid (pid, &status, 0) != pid)
      status = -1;

  wordfree (&result);
  return status;
}
Details of Tilde Expansion

It's a standard part of shell syntax that you can use `~' at the beginning of a file name to stand for your own home directory. You can use `~user' to stand for user's home directory.

Tilde expansion is the process of converting these abbreviations to the directory names that they stand for.

Tilde expansion applies to the `~' plus all following characters up to whitespace or a slash. It takes place only at the beginning of a word, and only if none of the characters to be transformed is quoted in any way.

Plain `~' uses the value of the environment variable HOME as the proper home directory name. `~' followed by a user name uses getpwname to look up that user in the user database, and uses whatever directory is recorded there. Thus, `~' followed by your own name can give different results from plain `~', if the value of HOME is not really your home directory.

Details of Variable Substitution

Part of ordinary shell syntax is the use of `$variable' to substitute the value of a shell variable into a command. This is called variable substitution, and it is one part of doing word expansion.

There are two basic ways you can write a variable reference for substitution:

${variable}
If you write braces around the variable name, then it is completely unambiguous where the variable name ends. You can concatenate additional letters onto the end of the variable value by writing them immediately after the close brace. For example, `${foo}s' expands into `tractors'.
$variable
If you do not put braces around the variable name, then the variable name consists of all the alphanumeric characters and underscores that follow the `$'. The next punctuation character ends the variable name. Thus, `$foo-bar' refers to the variable foo and expands into `tractor-bar'.
When you use braces, you can also use various constructs to modify the value that is substituted, or test it in various ways.

${variable:-default}
Substitute the value of variable, but if that is empty or undefined, use default instead.
${variable:=default}
Substitute the value of variable, but if that is empty or undefined, use default instead and set the variable to default.
${variable:?message}
If variable is defined and not empty, substitute its value. Otherwise, print message as an error message on the standard error stream, and consider word expansion a failure.
${variable:+replacement}
Substitute replacement, but only if variable is defined and nonempty. Otherwise, substitute nothing for this construct.
${#variable}
Substitute a numeral which expresses in base ten the number of characters in the value of variable. `${#foo}' stands for `7', because `tractor' is seven characters.
These variants of variable substitution let you remove part of the variable's value before substituting it. The prefix and suffix are not mere strings; they are wildcard patterns, just like the patterns that you use to match multiple file names. But in this context, they match against parts of the variable value rather than against file names.

${variable%%suffix}
Substitute the value of variable, but first discard from that variable any portion at the end that matches the pattern suffix. If there is more than one alternative for how to match against suffix, this construct uses the longest possible match. Thus, `${foo%%r*}' substitutes `t', because the largest match for `r*' at the end of `tractor' is `ractor'.
${variable%suffix}
Substitute the value of variable, but first discard from that variable any portion at the end that matches the pattern suffix. If there is more than one alternative for how to match against suffix, this construct uses the shortest possible alternative. Thus, `${foo%%r*}' substitutes `tracto', because the shortest match for `r*' at the end of `tractor' is just `r'.
${variable##prefix}
Substitute the value of variable, but first discard from that variable any portion at the beginning that matches the pattern prefix. If there is more than one alternative for how to match against prefix, this construct uses the longest possible match. Thus, `${foo%%r*}' substitutes `t', because the largest match for `r*' at the end of `tractor' is `ractor'.
${variable#prefix}
Substitute the value of variable, but first discard from that variable any portion at the beginning that matches the pattern prefix. If there is more than one alternative for how to match against prefix, this construct uses the shortest possible alternative. Thus, `${foo%%r*}' substitutes `tracto', because the shortest match for `r*' at the end of `tractor' is just `r'.
Input/Output Overview

Most programs need to do either input (reading data) or output (writing data), or most frequently both, in order to do anything useful. The GNU C library provides such a large selection of input and output functions that the hardest part is often deciding which function is most appropriate!

This chapter introduces concepts and terminology relating to input and output. Other chapters relating to the GNU I/O facilities are:

section Input/Output on Streams, which covers the high-level functions that operate on streams, including formatted input and output.
section Low-Level Input/Output, which covers the basic I/O and control functions on file descriptors.
section File System Interface, which covers functions for operating on directories and for manipulating file attributes such as access modes and ownership.
section Pipes and FIFOs, which includes information on the basic interprocess communication facilities.
section Sockets, which covers a more complicated interprocess communication facility with support for networking.
section Low-Level Terminal Interface, which covers functions for changing how input and output to terminals or other serial devices are processed.

Input/Output Concepts

Before you can read or write the contents of a file, you must establish a connection or communications channel to the file. This process is called opening the file. You can open a file for reading, writing, or both.

The connection to an open file is represented either as a stream or as a file descriptor. You pass this as an argument to the functions that do the actual read or write operations, to tell them which file to operate on. Certain functions expect streams, and others are designed to operate on file descriptors.

When you have finished reading to or writing from the file, you can terminate the connection by closing the file. Once you have closed a stream or file descriptor, you cannot do any more input or output operations on it.

Streams and File Descriptors

When you want to do input or output to a file, you have a choice of two basic mechanisms for representing the connection between your program and the file: file descriptors and streams. File descriptors are represented as objects of type int, while streams are represented as FILE * objects.

File descriptors provide a primitive, low-level interface to input and output operations. Both file descriptors and streams can represent a connection to a device (such as a terminal), or a pipe or socket for communicating with another process, as well as a normal file. But, if you want to do control operations that are specific to a particular kind of device, you must use a file descriptor; there are no facilities to use streams in this way. You must also use file descriptors if your program needs to do input or output in special modes, such as nonblocking (or polled) input (see section File Status Flags).

Streams provide a higher-level interface, layered on top of the primitive file descriptor facilities. The stream interface treats all kinds of files pretty much alike--the sole exception being the three styles of buffering that you can choose (see section Stream Buffering).

The main advantage of using the stream interface is that the set of functions for performing actual input and output operations (as opposed to control operations) on streams is much richer and more powerful than the corresponding facilities for file descriptors. The file descriptor interface provides only simple functions for transferring blocks of characters, but the stream interface also provides powerful formatted input and output functions (printf and scanf) as well as functions for character- and line-oriented input and output.

Since streams are implemented in terms of file descriptors, you can extract the file descriptor from a stream and perform low-level operations directly on the file descriptor. You can also initially open a connection as a file descriptor and then make a stream associated with that file descriptor.

In general, you should stick with using streams rather than file descriptors, unless there is some specific operation you want to do that can only be done on a file descriptor. If you are a beginning programmer and aren't sure what functions to use, we suggest that you concentrate on the formatted input functions (see section Formatted Input) and formatted output functions (see section Formatted Output).

If you are concerned about portability of your programs to systems other than GNU, you should also be aware that file descriptors are not as portable as streams. You can expect any system running ISO C to support streams, but non-GNU systems may not support file descriptors at all, or may only implement a subset of the GNU functions that operate on file descriptors. Most of the file descriptor functions in the GNU library are included in the POSIX.1 standard, however.

File Position

One of the attributes of an open file is its file position that keeps track of where in the file the next character is to be read or written. In the GNU system, and all POSIX.1 systems, the file position is simply an integer representing the number of bytes from the beginning of the file.

The file position is normally set to the beginning of the file when it is opened, and each time a character is read or written, the file position is incremented. In other words, access to the file is normally sequential.

Ordinary files permit read or write operations at any position within the file. Some other kinds of files may also permit this. Files which do permit this are sometimes referred to as random-access files. You can change the file position using the fseek function on a stream (see section File Positioning) or the lseek function on a file descriptor (see section Input and Output Primitives). If you try to change the file position on a file that doesn't support random access, you get the ESPIPE error.

Streams and descriptors that are opened for append access are treated specially for output: output to such files is always appended sequentially to the end of the file, regardless of the file position. However, the file position is still used to control where in the file reading is done.

If you think about it, you'll realize that several programs can read a given file at the same time. In order for each program to be able to read the file at its own pace, each program must have its own file pointer, which is not affected by anything the other programs do.

In fact, each opening of a file creates a separate file position. Thus, if you open a file twice even in the same program, you get two streams or descriptors with independent file positions.

By contrast, if you open a descriptor and then duplicate it to get another descriptor, these two descriptors share the same file position: changing the file position of one descriptor will affect the other.

File Names

In order to open a connection to a file, or to perform other operations such as deleting a file, you need some way to refer to the file. Nearly all files have names that are strings--even files which are actually devices such as tape drives or terminals. These strings are called file names. You specify the file name to say which file you want to open or operate on.

This section describes the conventions for file names and how the operating system works with them.

Directories

In order to understand the syntax of file names, you need to understand how the file system is organized into a hierarchy of directories.

A directory is a file that contains information to associate other files with names; these associations are called links or directory entries. Sometimes, people speak of "files in a directory", but in reality, a directory only contains pointers to files, not the files themselves.

The name of a file contained in a directory entry is called a file name component. In general, a file name consists of a sequence of one or more such components, separated by the slash character (`/'). A file name which is just one component names a file with respect to its directory. A file name with multiple components names a directory, and then a file in that directory, and so on.

Some other documents, such as the POSIX standard, use the term pathname for what we call a file name, and either filename or pathname component for what this manual calls a file name component. We don't use this terminology because a "path" is something completely different (a list of directories to search), and we think that "pathname" used for something else will confuse users. We always use "file name" and "file name component" (or sometimes just "component", where the context is obvious) in GNU documentation. Some macros use the POSIX terminology in their names, such as PATH_MAX. These macros are defined by the POSIX standard, so we cannot change their names.

You can find more detailed information about operations on directories in section File System Interface.

File Name Resolution

A file name consists of file name components separated by slash (`/') characters. On the systems that the GNU C library supports, multiple successive `/' characters are equivalent to a single `/' character.

The process of determining what file a file name refers to is called file name resolution. This is performed by examining the components that make up a file name in left-to-right order, and locating each successive component in the directory named by the previous component. Of course, each of the files that are referenced as directories must actually exist, be directories instead of regular files, and have the appropriate permissions to be accessible by the process; otherwise the file name resolution fails.

If a file name begins with a `/', the first component in the file name is located in the root directory of the process (usually all processes on the system have the same root directory). Such a file name is called an absolute file name.

Otherwise, the first component in the file name is located in the current working directory (see section Working Directory). This kind of file name is called a relative file name.

The file name components `.' ("dot") and `..' ("dot-dot") have special meanings. Every directory has entries for these file name components. The file name component `.' refers to the directory itself, while the file name component `..' refers to its parent directory (the directory that contains the link for the directory in question). As a special case, `..' in the root directory refers to the root directory itself, since it has no parent; thus `/..' is the same as `/'.

Here are some examples of file names:

`/a'
The file named `a', in the root directory.
`/a/b'
The file named `b', in the directory named `a' in the root directory.
`a'
The file named `a', in the current working directory.
`/a/./b'
This is the same as `/a/b'.
`./a'
The file named `a', in the current working directory.
`../a'
The file named `a', in the parent directory of the current working directory.
A file name that names a directory may optionally end in a `/'. You can specify a file name of `/' to refer to the root directory, but the empty string is not a meaningful file name. If you want to refer to the current working directory, use a file name of `.' or `./'.

Unlike some other operating systems, the GNU system doesn't have any built-in support for file types (or extensions) or file versions as part of its file name syntax. Many programs and utilities use conventions for file names--for example, files containing C source code usually have names suffixed with `.c'---but there is nothing in the file system itself that enforces this kind of convention.

File Name Errors

Functions that accept file name arguments usually detect these errno error conditions relating to the file name syntax or trouble finding the named file. These errors are referred to throughout this manual as the usual file name errors.

EACCES
The process does not have search permission for a directory component of the file name.
ENAMETOOLONG
This error is used when either the total length of a file name is greater than PATH_MAX, or when an individual file name component has a length greater than NAME_MAX. See section Limits on File System Capacity. In the GNU system, there is no imposed limit on overall file name length, but some file systems may place limits on the length of a component.
ENOENT
This error is reported when a file referenced as a directory component in the file name doesn't exist, or when a component is a symbolic link whose target file does not exist. See section Symbolic Links.
ENOTDIR
A file that is referenced as a directory component in the file name exists, but it isn't a directory.
ELOOP
Too many symbolic links were resolved while trying to look up the file name. The system has an arbitrary limit on the number of symbolic links that may be resolved in looking up a single file name, as a primitive way to detect loops. See section Symbolic Links.
Portability of File Names

The rules for the syntax of file names discussed in section File Names, are the rules normally used by the GNU system and by other POSIX systems. However, other operating systems may use other conventions.

There are two reasons why it can be important for you to be aware of file name portability issues:

If your program makes assumptions about file name syntax, or contains embedded literal file name strings, it is more difficult to get it to run under other operating systems that use different syntax conventions.
Even if you are not concerned about running your program on machines that run other operating systems, it may still be possible to access files that use different naming conventions. For example, you may be able to access file systems on another computer running a different operating system over a network, or read and write disks in formats used by other operating systems.

The ISO C standard says very little about file name syntax, only that file names are strings. In addition to varying restrictions on the length of file names and what characters can validly appear in a file name, different operating systems use different conventions and syntax for concepts such as structured directories and file types or extensions. Some concepts such as file versions might be supported in some operating systems and not by others.

The POSIX.1 standard allows implementations to put additional restrictions on file name syntax, concerning what characters are permitted in file names and on the length of file name and file name component strings. However, in the GNU system, you do not need to worry about these restrictions; any character except the null character is permitted in a file name string, and there are no limits on the length of file name strings.
Input/Output on Streams

This chapter describes the functions for creating streams and performing input and output operations on them. As discussed in section Input/Output Overview, a stream is a fairly abstract, high-level concept representing a communications channel to a file, device, or process.

Streams

For historical reasons, the type of the C data structure that represents a stream is called FILE rather than "stream". Since most of the library functions deal with objects of type FILE *, sometimes the term file pointer is also used to mean "stream". This leads to unfortunate confusion over terminology in many books on C. This manual, however, is careful to use the terms "file" and "stream" only in the technical sense.

The FILE type is declared in the header file `stdio.h'.

Data Type: FILE
This is the data type used to represent stream objects. A FILE object holds all of the internal state information about the connection to the associated file, including such things as the file position indicator and buffering information. Each stream also has error and end-of-file status indicators that can be tested with the ferror and feof functions; see section End-Of-File and Errors.

FILE objects are allocated and managed internally by the input/output library functions. Don't try to create your own objects of type FILE; let the library do it. Your programs should deal only with pointers to these objects (that is, FILE * values) rather than the objects themselves.

Standard Streams

When the main function of your program is invoked, it already has three predefined streams open and available for use. These represent the "standard" input and output channels that have been established for the process.

These streams are declared in the header file `stdio.h'.

Variable: FILE * stdin
The standard input stream, which is the normal source of input for the program.

Variable: FILE * stdout
The standard output stream, which is used for normal output from the program.

Variable: FILE * stderr
The standard error stream, which is used for error messages and diagnostics issued by the program.

In the GNU system, you can specify what files or processes correspond to these streams using the pipe and redirection facilities provided by the shell. (The primitives shells use to implement these facilities are described in section File System Interface.) Most other operating systems provide similar mechanisms, but the details of how to use them can vary.

In the GNU C library, stdin, stdout, and stderr are normal variables which you can set just like any others. For example, to redirect the standard output to a file, you could do:
fclose (stdout);
stdout = fopen ("standard-output-file", "w");
Note however, that in other systems stdin, stdout, and stderr are macros that you cannot assign to in the normal way. But you can use freopen to get the effect of closing one and reopening it. See section Opening Streams.

The three streams stdin, stdout, and stderr are not unoriented at program start (see section Streams in Internationalized Applications).

Opening Streams

Opening a file with the fopen function creates a new stream and establishes a connection between the stream and a file. This may involve creating a new file.

Everything described in this section is declared in the header file `stdio.h'.

Function: FILE * fopen (const char *filename, const char *opentype)
The fopen function opens a stream for I/O to the file filename, and returns a pointer to the stream.

The opentype argument is a string that controls how the file is opened and specifies attributes of the resulting stream. It must begin with one of the following sequences of characters:

`r'
Open an existing file for reading only.
`w'
Open the file for writing only. If the file already exists, it is truncated to zero length. Otherwise a new file is created.
`a'
Open a file for append access; that is, writing at the end of file only. If the file already exists, its initial contents are unchanged and output to the stream is appended to the end of the file. Otherwise, a new, empty file is created.
`r+'
Open an existing file for both reading and writing. The initial contents of the file are unchanged and the initial file position is at the beginning of the file.
`w+'
Open a file for both reading and writing. If the file already exists, it is truncated to zero length. Otherwise, a new file is created.
`a+'
Open or create file for both reading and appending. If the file exists, its initial contents are unchanged. Otherwise, a new file is created. The initial file position for reading is at the beginning of the file, but output is always appended to the end of the file.
As you can see, `+' requests a stream that can do both input and output. The ISO standard says that when using such a stream, you must call fflush (see section Stream Buffering) or a file positioning function such as fseek (see section File Positioning) when switching from reading to writing or vice versa. Otherwise, internal buffers might not be emptied properly. The GNU C library does not have this limitation; you can do arbitrary reading and writing operations on a stream in whatever order.

Additional characters may appear after these to specify flags for the call. Always put the mode (`r', `w+', etc.) first; that is the only part you are guaranteed will be understood by all systems.

The GNU C library defines one additional character for use in opentype: the character `x' insists on creating a new file--if a file filename already exists, fopen fails rather than opening it. If you use `x' you are guaranteed that you will not clobber an existing file. This is equivalent to the O_EXCL option to the open function (see section Opening and Closing Files).

The character `b' in opentype has a standard meaning; it requests a binary stream rather than a text stream. But this makes no difference in POSIX systems (including the GNU system). If both `+' and `b' are specified, they can appear in either order. See section Text and Binary Streams.

If the opentype string contains the sequence ,ccs=STRING then STRING is taken as the name of a coded character set and fopen will mark the stream as wide-oriented which appropriate conversion functions in place to convert from and to the character set STRING is place. Any other stream is opened initially unoriented and the orientation is decided with the first file operation. If the first operation is a wide character operation, the stream is not only marked as wide-oriented, also the conversion functions to convert to the coded character set used for the current locale are loaded. This will not change anymore from this point on even if the locale selected for the LC_CTYPE category is changed.

Any other characters in opentype are simply ignored. They may be meaningful in other systems.

If the open fails, fopen returns a null pointer.

When the sources are compiling with _FILE_OFFSET_BITS == 64 on a 32 bit machine this function is in fact fopen64 since the LFS interface replaces transparently the old interface.

You can have multiple streams (or file descriptors) pointing to the same file open at the same time. If you do only input, this works straightforwardly, but you must be careful if any output streams are included. See section Dangers of Mixing Streams and Descriptors. This is equally true whether the streams are in one program (not usual) or in several programs (which can easily happen). It may be advantageous to use the file locking facilities to avoid simultaneous access. See section File Locks.

Function: FILE * fopen64 (const char *filename, const char *opentype)
This function is similar to fopen but the stream it returns a pointer for is opened using open64. Therefore this stream can be used even on files larger then @math{2^31} bytes on 32 bit machines.

Please note that the return type is still FILE *. There is no special FILE type for the LFS interface.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name fopen and so transparently replaces the old interface.

Macro: int FOPEN_MAX
The value of this macro is an integer constant expression that represents the minimum number of streams that the implementation guarantees can be open simultaneously. You might be able to open more than this many streams, but that is not guaranteed. The value of this constant is at least eight, which includes the three standard streams stdin, stdout, and stderr. In POSIX.1 systems this value is determined by the OPEN_MAX parameter; see section General Capacity Limits. In BSD and GNU, it is controlled by the RLIMIT_NOFILE resource limit; see section Limiting Resource Usage.

Function: FILE * freopen (const char *filename, const char *opentype, FILE *stream)
This function is like a combination of fclose and fopen. It first closes the stream referred to by stream, ignoring any errors that are detected in the process. (Because errors are ignored, you should not use freopen on an output stream if you have actually done any output using the stream.) Then the file named by filename is opened with mode opentype as for fopen, and associated with the same stream object stream.

If the operation fails, a null pointer is returned; otherwise, freopen returns stream.

freopen has traditionally been used to connect a standard stream such as stdin with a file of your own choice. This is useful in programs in which use of a standard stream for certain purposes is hard-coded. In the GNU C library, you can simply close the standard streams and open new ones with fopen. But other systems lack this ability, so using freopen is more portable.

When the sources are compiling with _FILE_OFFSET_BITS == 64 on a 32 bit machine this function is in fact freopen64 since the LFS interface replaces transparently the old interface.

Function: FILE * freopen64 (const char *filename, const char *opentype, FILE *stream)
This function is similar to freopen. The only difference is that on 32 bit machine the stream returned is able to read beyond the @math{2^31} bytes limits imposed by the normal interface. It should be noted that the stream pointed to by stream need not be opened using fopen64 or freopen64 since its mode is not important for this function.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name freopen and so transparently replaces the old interface.

In some situations it is useful to know whether a given stream is available for reading or writing. This information is normally not available and would have to be remembered separately. Solaris introduced a few functions to get this information from the stream descriptor and these functions are also available in the GNU C library.

Function: int __freadable (FILE *stream)
The __freadable function determines whether the stream stream was opened to allow reading. In this case the return value is nonzero. For write-only streams the function returns zero.

This function is declared in `stdio_ext.h'.

Function: int __fwritable (FILE *stream)
The __fwritable function determines whether the stream stream was opened to allow writing. In this case the return value is nonzero. For read-only streams the function returns zero.

This function is declared in `stdio_ext.h'.

For slightly different kind of problems there are two more functions. They provide even finer-grained information.

Function: int __freading (FILE *stream)
The __freading function determines whether the stream stream was last read from or whether it is opened read-only. In this case the return value is nonzero, otherwise it is zero. Determining whether a stream opened for reading and writing was last used for writing allows to draw conclusions about the content about the buffer, among other things.

This function is declared in `stdio_ext.h'.

Function: int __fwriting (FILE *stream)
The __fwriting function determines whether the stream stream was last written to or whether it is opened write-only. In this case the return value is nonzero, otherwise it is zero.

This function is declared in `stdio_ext.h'.

Closing Streams

When a stream is closed with fclose, the connection between the stream and the file is cancelled. After you have closed a stream, you cannot perform any additional operations on it.

Function: int fclose (FILE *stream)
This function causes stream to be closed and the connection to the corresponding file to be broken. Any buffered output is written and any buffered input is discarded. The fclose function returns a value of 0 if the file was closed successfully, and EOF if an error was detected.

It is important to check for errors when you call fclose to close an output stream, because real, everyday errors can be detected at this time. For example, when fclose writes the remaining buffered output, it might get an error because the disk is full. Even if you know the buffer is empty, errors can still occur when closing a file if you are using NFS.

The function fclose is declared in `stdio.h'.

To close all streams currently available the GNU C Library provides another function.

Function: int fcloseall (void)
This function causes all open streams of the process to be closed and the connection to corresponding files to be broken. All buffered data is written and any buffered input is discarded. The fcloseall function returns a value of 0 if all the files were closed successfully, and EOF if an error was detected.

This function should be used only in special situations, e.g., when an error occurred and the program must be aborted. Normally each single stream should be closed separately so that problems with individual streams can be identified. It is also problematic since the standard streams (see section Standard Streams) will also be closed.

The function fcloseall is declared in `stdio.h'.

If the main function to your program returns, or if you call the exit function (see section Normal Termination), all open streams are automatically closed properly. If your program terminates in any other manner, such as by calling the abort function (see section Aborting a Program) or from a fatal signal (see section Signal Handling), open streams might not be closed properly. Buffered output might not be flushed and files may be incomplete. For more information on buffering of streams, see section Stream Buffering.

Streams and Threads

Streams can be used in multi-threaded applications in the same way they are used in single-threaded applications. But the programmer must be aware of a the possible complications. It is important to know about these also if the program one writes never use threads since the design and implementation of many stream functions is heavily influenced by the requirements added by multi-threaded programming.

The POSIX standard requires that by default the stream operations are atomic. I.e., issueing two stream operations for the same stream in two threads at the same time will cause the operations to be executed as if they were issued sequentially. The buffer operations performed while reading or writing are protected from other uses of the same stream. To do this each stream has an internal lock object which has to be (implicitly) acquired before any work can be done.

But there are situations where this is not enough and there are also situations where this is not wanted. The implicit locking is not enough if the program requires more than one stream function call to happen atomically. One example would be if an output line a program wants to generate is created by several function calls. The functions by themselves would ensure only atomicity of their own operation, but not atomicity over all the function calls. For this it is necessary to perform the stream locking in the application code.

Function: void flockfile (FILE *stream)
The flockfile function acquires the internal locking object associated with the stream stream. This ensures that no other thread can explicitly through flockfile/ftrylockfile or implicit through a call of a stream function lock the stream. The thread will block until the lock is acquired. An explicit call to funlockfile has to be used to release the lock.

Function: int ftrylockfile (FILE *stream)
The ftrylockfile function tries to acquire the internal locking object associated with the stream stream just like flockfile. But unlike flockfile this function does not block if the lock is not available. ftrylockfile returns zero if the lock was successfully acquired. Otherwise the stream is locked by another thread.

Function: void funlockfile (FILE *stream)
The funlockfile function releases the internal locking object of the stream stream. The stream must have been locked before by a call to flockfile or a successful call of ftrylockfile. The implicit locking performed by the stream operations do not count. The funlockfile function does not return an error status and the behavior of a call for a stream which is not locked by the current thread is undefined.

The following example shows how the functions above can be used to generate an output line atomically even in multi-threaded applications (yes, the same job could be done with one fprintf call but it is sometimes not possible):
FILE *fp;
{
   ...
   flockfile (fp);
   fputs ("This is test number ", fp);
   fprintf (fp, "%d\n", test);
   funlockfile (fp)
}
Without the explicit locking it would be possible for another thread to use the stream fp after the fputs call return and before fprintf was called with the result that the number does not follow the word `number'.

From this description it might already be clear that the locking objects in streams are no simple mutexes. Since locking the same stream twice in the same thread is allowed the locking objects must be equivalent to recursive mutexes. These mutexes keep track of the owner and the number of times the lock is acquired. The same number of funlockfile calls by the same threads is necessary to unlock the stream completely. For instance:
void
foo (FILE *fp)
{
  ftrylockfile (fp);
  fputs ("in foo\n", fp);
  /* This is very wrong!!!  */
  funlockfile (fp);
}
It is important here that the funlockfile function is only called if the ftrylockfile function succeeded in locking the stream. It is therefore always wrong to ignore the result of ftrylockfile. And it makes no sense since otherwise one would use flockfile. The result of code like that above is that either funlockfile tries to free a stream that hasn't been locked by the current thread or it frees the stream prematurely. The code should look like this:
void
foo (FILE *fp)
{
  if (ftrylockfile (fp) == 0)
    {
      fputs ("in foo\n", fp);
      funlockfile (fp);
    }
}
Now that we covered why it is necessary to have these locking it is necessary to talk about situations when locking is unwanted and what can be done. The locking operations (explicit or implicit) don't come for free. Even if a lock is not taken the cost is not zero. The operations which have to be performed require memory operations which are save in multi-processor environments. With the many local caches involved in such systems this is quite costly. So it is best to avoid the locking completely if it is known that the code using the stream is never used in a context where more than one thread can use the stream at one time. This can be determined most of the time for application code; for library code which can be used in many contexts one should default to be conservative and use locking.

There are two basic mechanisms to avoid locking. The first is to use the _unlocked variants of the stream operations. The POSIX standard defines quite a few of those and the GNU library adds a few more. These variants of the functions behave just like the functions with the name without the suffix except that they are not locking the stream. Using these functions is very desirable since they are potentially much faster. This is not only because the locking operation itself is avoided. More importantly, functions like putc and getc are very simple and tradionally (before the introduction of threads) were implemented as macros which are very fast if the buffer is not empty. With locking required these functions are now no macros anymore (the code generated would be too much). But these macros are still available with the same functionality under the new names putc_unlocked and getc_unlocked. This possibly huge difference of speed also suggests the use of the _unlocked functions even if locking is required. The difference is that the locking then has to be performed in the program:
void
foo (FILE *fp, char *buf)
{
  flockfile (fp);
  while (*buf != '/')
    putc_unlocked (*buf++, fp);
  funlockfile (fp);
}
If in this example the putc function would be used and the explicit locking would be missing the putc function would have to acquire the lock in every call, potentially many times depending on when the loop terminates. Writing it the way illustrated above allows the putc_unlocked macro to be used which means no locking and direct manipulation of the buffer of the stream.

A second way to avoid locking is by using a non-standard function which was introduced in Solaris and is available in the GNU C library as well.

Function: int __fsetlocking (FILE *stream, int type)

The __fsetlocking function can be used to select whether the stream operations will implicitly acquire the locking object of the stream stream. By default this is done but it can be disabled and reinstated using this function. There are three values defined for the type parameter.

FSETLOCKING_INTERNAL
The stream stream will from now on use the default internal locking. Every stream operation with exception of the _unlocked variants will implicitly lock the stream.
FSETLOCKING_BYCALLER
After the __fsetlocking function returns the user is responsible for locking the stream. None of the stream operations will implicitly do this anymore until the state is set back to FSETLOCKING_INTERNAL.
FSETLOCKING_QUERY
__fsetlocking only queries the current locking state of the stream. The return value will be FSETLOCKING_INTERNAL or FSETLOCKING_BYCALLER depending on the state.
The return value of __fsetlocking is either FSETLOCKING_INTERNAL or FSETLOCKING_BYCALLER depending on the state of the stream before the call.

This function and the values for the type parameter are declared in `stdio_ext.h'.

This function is especially useful when program code has to be used which is written without knowledge about the _unlocked functions (or if the programmer was to lazy to use them).

Streams in Internationalized Applications

ISO C90 introduced the new type wchar_t to allow handling larger character sets. What was missing was a possibility to output strings of wchar_t directly. One had to convert them into multibyte strings using mbstowcs (there was no mbsrtowcs yet) and then use the normal stream functions. While this is doable it is very cumbersome since performing the conversions is not trivial and greatly increases program complexity and size.

The Unix standard early on (I think in XPG4.2) introduced two additional format specifiers for the printf and scanf families of functions. Printing and reading of single wide characters was made possible using the %C specifier and wide character strings can be handled with %S. These modifiers behave just like %c and %s only that they expect the corresponding argument to have the wide character type and that the wide character and string are transformed into/from multibyte strings before being used.

This was a beginning but it is still not good enough. Not always is it desirable to use printf and scanf. The other, smaller and faster functions cannot handle wide characters. Second, it is not possible to have a format string for printf and scanf consisting of wide characters. The result is that format strings would have to be generated if they have to contain non-basic characters.

In the Amendment 1 to ISO C90 a whole new set of functions was added to solve the problem. Most of the stream functions got a counterpart which take a wide character or wide character string instead of a character or string respectively. The new functions operate on the same streams (like stdout). This is different from the model of the C++ runtime library where separate streams for wide and normal I/O are used.

Being able to use the same stream for wide and normal operations comes with a restriction: a stream can be used either for wide operations or for normal operations. Once it is decided there is no way back. Only a call to freopen or freopen64 can reset the orientation. The orientation can be decided in three ways:

If any of the normal character functions is used (this includes the fread and fwrite functions) the stream is marked as not wide oriented.
If any of the wide character functions is used the stream is marked as wide oriented.
The fwide function can be used to set the orientation either way.

It is important to never mix the use of wide and not wide operations on a stream. There are no diagnostics issued. The application behavior will simply be strange or the application will simply crash. The fwide function can help avoiding this.

Function: int fwide (FILE *stream, int mode)

The fwide function can be used to set and query the state of the orientation of the stream stream. If the mode parameter has a positive value the streams get wide oriented, for negative values narrow oriented. It is not possible to overwrite previous orientations with fwide. I.e., if the stream stream was already oriented before the call nothing is done.

If mode is zero the current orientation state is queried and nothing is changed.

The fwide function returns a negative value, zero, or a positive value if the stream is narrow, not at all, or wide oriented respectively.

This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.

It is generally a good idea to orient a stream as early as possible. This can prevent surprise especially for the standard streams stdin, stdout, and stderr. If some library function in some situations uses one of these streams and this use orients the stream in a different way the rest of the application expects it one might end up with hard to reproduce errors. Remember that no errors are signal if the streams are used incorrectly. Leaving a stream unoriented after creation is normally only necessary for library functions which create streams which can be used in different contexts.

When writing code which uses streams and which can be used in different contexts it is important to query the orientation of the stream before using it (unless the rules of the library interface demand a specific orientation). The following little, silly function illustrates this.
void
print_f (FILE *fp)
{
  if (fwide (fp, 0) > 0)
    /* Positive return value means wide orientation.  */
    fputwc (L'f', fp);
  else
    fputc ('f', fp);
}
Note that in this case the function print_f decides about the orientation of the stream if it was unoriented before (will not happen if the advise above is followed).

The encoding used for the wchar_t values is unspecified and the user must not make any assumptions about it. For I/O of wchar_t values this means that it is impossible to write these values directly to the stream. This is not what follows from the ISO C locale model either. What happens instead is that the bytes read from or written to the underlying media are first converted into the internal encoding chosen by the implementation for wchar_t. The external encoding is determined by the LC_CTYPE category of the current locale or by the `ccs' part of the mode specification given to fopen, fopen64, freopen, or freopen64. How and when the conversion happens is unspecified and it happens invisible to the user.

Since a stream is created in the unoriented state it has at that point no conversion associated with it. The conversion which will be used is determined by the LC_CTYPE category selected at the time the stream is oriented. If the locales are changed at the runtime this might produce surprising results unless one pays attention. This is just another good reason to orient the stream explicitly as soon as possible, perhaps with a call to fwide.

Simple Output by Characters or Lines

This section describes functions for performing character- and line-oriented output.

These narrow streams functions are declared in the header file `stdio.h' and the wide stream functions in `wchar.h'.

Function: int fputc (int c, FILE *stream)
The fputc function converts the character c to type unsigned char, and writes it to the stream stream. EOF is returned if a write error occurs; otherwise the character c is returned.

Function: wint_t fputwc (wchar_t wc, FILE *stream)
The fputwc function writes the wide character wc to the stream stream. WEOF is returned if a write error occurs; otherwise the character wc is returned.

Function: int fputc_unlocked (int c, FILE *stream)
The fputc_unlocked function is equivalent to the fputc function except that it does not implicitly lock the stream.

Function: wint_t fputwc_unlocked (wint_t wc, FILE *stream)
The fputwc_unlocked function is equivalent to the fputwc function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: int putc (int c, FILE *stream)
This is just like fputc, except that most systems implement it as a macro, making it faster. One consequence is that it may evaluate the stream argument more than once, which is an exception to the general rule for macros. putc is usually the best function to use for writing a single character.

Function: wint_t putwc (wchar_t wc, FILE *stream)
This is just like fputwc, except that it can be implement as a macro, making it faster. One consequence is that it may evaluate the stream argument more than once, which is an exception to the general rule for macros. putwc is usually the best function to use for writing a single wide character.

Function: int putc_unlocked (int c, FILE *stream)
The putc_unlocked function is equivalent to the putc function except that it does not implicitly lock the stream.

Function: wint_t putwc_unlocked (wchar_t wc, FILE *stream)
The putwc_unlocked function is equivalent to the putwc function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: int putchar (int c)
The putchar function is equivalent to putc with stdout as the value of the stream argument.

Function: wint_t putwchar (wchar_t wc)
The putwchar function is equivalent to putwc with stdout as the value of the stream argument.

Function: int putchar_unlocked (int c)
The putchar_unlocked function is equivalent to the putchar function except that it does not implicitly lock the stream.

Function: wint_t putwchar_unlocked (wchar_t wc)
The putwchar_unlocked function is equivalent to the putwchar function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: int fputs (const char *s, FILE *stream)
The function fputs writes the string s to the stream stream. The terminating null character is not written. This function does not add a newline character, either. It outputs only the characters in the string.

This function returns EOF if a write error occurs, and otherwise a non-negative value.

For example:
fputs ("Are ", stdout);
fputs ("you ", stdout);
fputs ("hungry?\n", stdout);
outputs the text `Are you hungry?' followed by a newline.

Function: int fputws (const wchar_t *ws, FILE *stream)
The function fputws writes the wide character string ws to the stream stream. The terminating null character is not written. This function does not add a newline character, either. It outputs only the characters in the string.

This function returns WEOF if a write error occurs, and otherwise a non-negative value.

Function: int fputs_unlocked (const char *s, FILE *stream)
The fputs_unlocked function is equivalent to the fputs function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: int fputws_unlocked (const wchar_t *ws, FILE *stream)
The fputws_unlocked function is equivalent to the fputws function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: int puts (const char *s)
The puts function writes the string s to the stream stdout followed by a newline. The terminating null character of the string is not written. (Note that fputs does not write a newline as this function does.)

puts is the most convenient function for printing simple messages. For example:
puts ("This is a message.");
outputs the text `This is a message.' followed by a newline.

Function: int putw (int w, FILE *stream)
This function writes the word w (that is, an int) to stream. It is provided for compatibility with SVID, but we recommend you use fwrite instead (see section Block Input/Output).

Character Input

This section describes functions for performing character-oriented input. These narrow streams functions are declared in the header file `stdio.h' and the wide character functions are declared in `wchar.h'.

These functions return an int or wint_t value (for narrow and wide stream functions respectively) that is either a character of input, or the special value EOF/WEOF (usually -1). For the narrow stream functions it is important to store the result of these functions in a variable of type int instead of char, even when you plan to use it only as a character. Storing EOF in a char variable truncates its value to the size of a character, so that it is no longer distinguishable from the valid character `(char) -1'. So always use an int for the result of getc and friends, and check for EOF after the call; once you've verified that the result is not EOF, you can be sure that it will fit in a `char' variable without loss of information.

Function: int fgetc (FILE *stream)
This function reads the next character as an unsigned char from the stream stream and returns its value, converted to an int. If an end-of-file condition or read error occurs, EOF is returned instead.

Function: wint_t fgetwc (FILE *stream)
This function reads the next wide character from the stream stream and returns its value. If an end-of-file condition or read error occurs, WEOF is returned instead.

Function: int fgetc_unlocked (FILE *stream)
The fgetc_unlocked function is equivalent to the fgetc function except that it does not implicitly lock the stream.

Function: wint_t fgetwc_unlocked (FILE *stream)
The fgetwc_unlocked function is equivalent to the fgetwc function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: int getc (FILE *stream)
This is just like fgetc, except that it is permissible (and typical) for it to be implemented as a macro that evaluates the stream argument more than once. getc is often highly optimized, so it is usually the best function to use to read a single character.

Function: wint_t getwc (FILE *stream)
This is just like fgetwc, except that it is permissible for it to be implemented as a macro that evaluates the stream argument more than once. getwc can be highly optimized, so it is usually the best function to use to read a single wide character.

Function: int getc_unlocked (FILE *stream)
The getc_unlocked function is equivalent to the getc function except that it does not implicitly lock the stream.

Function: wint_t getwc_unlocked (FILE *stream)
The getwc_unlocked function is equivalent to the getwc function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: int getchar (void)
The getchar function is equivalent to getc with stdin as the value of the stream argument.

Function: wint_t getwchar (void)
The getwchar function is equivalent to getwc with stdin as the value of the stream argument.

Function: int getchar_unlocked (void)
The getchar_unlocked function is equivalent to the getchar function except that it does not implicitly lock the stream.

Function: wint_t getwchar_unlocked (void)
The getwchar_unlocked function is equivalent to the getwchar function except that it does not implicitly lock the stream.

This function is a GNU extension.

Here is an example of a function that does input using fgetc. It would work just as well using getc instead, or using getchar () instead of fgetc (stdin). The code would also work the same for the wide character stream functions.
int
y_or_n_p (const char *question)
{
  fputs (question, stdout);
  while (1)
    {
      int c, answer;
      /* Write a space to separate answer from question. */
      fputc (' ', stdout);
      /* Read the first character of the line.
         This should be the answer character, but might not be. */
      c = tolower (fgetc (stdin));
      answer = c;
      /* Discard rest of input line. */
      while (c != '\n' && c != EOF)
        c = fgetc (stdin);
      /* Obey the answer if it was valid. */
      if (answer == 'y')
        return 1;
      if (answer == 'n')
        return 0;
      /* Answer was invalid: ask for valid answer. */
      fputs ("Please answer y or n:", stdout);
    }
}
Function: int getw (FILE *stream)
This function reads a word (that is, an int) from stream. It's provided for compatibility with SVID. We recommend you use fread instead (see section Block Input/Output). Unlike getc, any int value could be a valid result. getw returns EOF when it encounters end-of-file or an error, but there is no way to distinguish this from an input word with value -1.

Line-Oriented Input

Since many programs interpret input on the basis of lines, it is convenient to have functions to read a line of text from a stream.

Standard C has functions to do this, but they aren't very safe: null characters and even (for gets) long lines can confuse them. So the GNU library provides the nonstandard getline function that makes it easy to read lines reliably.

Another GNU extension, getdelim, generalizes getline. It reads a delimited record, defined as everything through the next occurrence of a specified delimiter character.

All these functions are declared in `stdio.h'.

Function: ssize_t getline (char **lineptr, size_t *n, FILE *stream)
This function reads an entire line from stream, storing the text (including the newline and a terminating null character) in a buffer and storing the buffer address in *lineptr.

Before calling getline, you should place in *lineptr the address of a buffer *n bytes long, allocated with malloc. If this buffer is long enough to hold the line, getline stores the line in this buffer. Otherwise, getline makes the buffer bigger using realloc, storing the new buffer address back in *lineptr and the increased size back in *n. See section Unconstrained Allocation.

If you set *lineptr to a null pointer, and *n to zero, before the call, then getline allocates the initial buffer for you by calling malloc.

In either case, when getline returns, *lineptr is a char * which points to the text of the line.

When getline is successful, it returns the number of characters read (including the newline, but not including the terminating null). This value enables you to distinguish null characters that are part of the line from the null character inserted as a terminator.

This function is a GNU extension, but it is the recommended way to read lines from a stream. The alternative standard functions are unreliable.

If an error occurs or end of file is reached without any bytes read, getline returns -1.

Function: ssize_t getdelim (char **lineptr, size_t *n, int delimiter, FILE *stream)
This function is like getline except that the character which tells it to stop reading is not necessarily newline. The argument delimiter specifies the delimiter character; getdelim keeps reading until it sees that character (or end of file).

The text is stored in lineptr, including the delimiter character and a terminating null. Like getline, getdelim makes lineptr bigger if it isn't big enough.

getline is in fact implemented in terms of getdelim, just like this:
ssize_t
getline (char **lineptr, size_t *n, FILE *stream)
{
  return getdelim (lineptr, n, '\n', stream);
}
Function: char * fgets (char *s, int count, FILE *stream)
The fgets function reads characters from the stream stream up to and including a newline character and stores them in the string s, adding a null character to mark the end of the string. You must supply count characters worth of space in s, but the number of characters read is at most count - 1. The extra character space is used to hold the null character at the end of the string.

If the system is already at end of file when you call fgets, then the contents of the array s are unchanged and a null pointer is returned. A null pointer is also returned if a read error occurs. Otherwise, the return value is the pointer s.

Warning: If the input data has a null character, you can't tell. So don't use fgets unless you know the data cannot contain a null. Don't use it to read files edited by the user because, if the user inserts a null character, you should either handle it properly or print a clear error message. We recommend using getline instead of fgets.

Function: wchar_t * fgetws (wchar_t *ws, int count, FILE *stream)
The fgetws function reads wide characters from the stream stream up to and including a newline character and stores them in the string ws, adding a null wide character to mark the end of the string. You must supply count wide characters worth of space in ws, but the number of characters read is at most count - 1. The extra character space is used to hold the null wide character at the end of the string.

If the system is already at end of file when you call fgetws, then the contents of the array ws are unchanged and a null pointer is returned. A null pointer is also returned if a read error occurs. Otherwise, the return value is the pointer ws.

Warning: If the input data has a null wide character (which are null bytes in the input stream), you can't tell. So don't use fgetws unless you know the data cannot contain a null. Don't use it to read files edited by the user because, if the user inserts a null character, you should either handle it properly or print a clear error message.

Function: char * fgets_unlocked (char *s, int count, FILE *stream)
The fgets_unlocked function is equivalent to the fgets function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: wchar_t * fgetws_unlocked (wchar_t *ws, int count, FILE *stream)
The fgetws_unlocked function is equivalent to the fgetws function except that it does not implicitly lock the stream.

This function is a GNU extension.

Deprecated function: char * gets (char *s)
The function gets reads characters from the stream stdin up to the next newline character, and stores them in the string s. The newline character is discarded (note that this differs from the behavior of fgets, which copies the newline character into the string). If gets encounters a read error or end-of-file, it returns a null pointer; otherwise it returns s.

Warning: The gets function is very dangerous because it provides no protection against overflowing the string s. The GNU library includes it for compatibility only. You should always use fgets or getline instead. To remind you of this, the linker (if using GNU ld) will issue a warning whenever you use gets.

Unreading

In parser programs it is often useful to examine the next character in the input stream without removing it from the stream. This is called "peeking ahead" at the input because your program gets a glimpse of the input it will read next.

Using stream I/O, you can peek ahead at input by first reading it and then unreading it (also called pushing it back on the stream). Unreading a character makes it available to be input again from the stream, by the next call to fgetc or other input function on that stream.

What Unreading Means

Here is a pictorial explanation of unreading. Suppose you have a stream reading a file that contains just six characters, the letters `foobar'. Suppose you have read three characters so far. The situation looks like this:
f  o  o  b  a  r
         ^
so the next input character will be `b'.

If instead of reading `b' you unread the letter `o', you get a situation like this:
f  o  o  b  a  r
         |
      o--
      ^
so that the next input characters will be `o' and `b'.

If you unread `9' instead of `o', you get this situation:
f  o  o  b  a  r
         |
      9--
      ^
so that the next input characters will be `9' and `b'.

Using ungetc To Do Unreading

The function to unread a character is called ungetc, because it reverses the action of getc.

Function: int ungetc (int c, FILE *stream)
The ungetc function pushes back the character c onto the input stream stream. So the next input from stream will read c before anything else.

If c is EOF, ungetc does nothing and just returns EOF. This lets you call ungetc with the return value of getc without needing to check for an error from getc.

The character that you push back doesn't have to be the same as the last character that was actually read from the stream. In fact, it isn't necessary to actually read any characters from the stream before unreading them with ungetc! But that is a strange way to write a program; usually ungetc is used only to unread a character that was just read from the same stream.

The GNU C library only supports one character of pushback--in other words, it does not work to call ungetc twice without doing input in between. Other systems might let you push back multiple characters; then reading from the stream retrieves the characters in the reverse order that they were pushed.

Pushing back characters doesn't alter the file; only the internal buffering for the stream is affected. If a file positioning function (such as fseek, fseeko or rewind; see section File Positioning) is called, any pending pushed-back characters are discarded.

Unreading a character on a stream that is at end of file clears the end-of-file indicator for the stream, because it makes the character of input available. After you read that character, trying to read again will encounter end of file.

Function: wint_t ungetwc (wint_t wc, FILE *stream)
The ungetwc function behaves just like ungetc just that it pushes back a wide character.

Here is an example showing the use of getc and ungetc to skip over whitespace characters. When this function reaches a non-whitespace character, it unreads that character to be seen again on the next read operation on the stream.
#include <stdio.h>
#include <ctype.h>

void
skip_whitespace (FILE *stream)
{
  int c;
  do
    /* No need to check for EOF because it is not
       isspace, and ungetc ignores EOF.  */
    c = getc (stream);
  while (isspace (c));
  ungetc (c, stream);
}
Block Input/Output

This section describes how to do input and output operations on blocks of data. You can use these functions to read and write binary data, as well as to read and write text in fixed-size blocks instead of by characters or lines.

Binary files are typically used to read and write blocks of data in the same format as is used to represent the data in a running program. In other words, arbitrary blocks of memory--not just character or string objects--can be written to a binary file, and meaningfully read in again by the same program.

Storing data in binary form is often considerably more efficient than using the formatted I/O functions. Also, for floating-point numbers, the binary form avoids possible loss of precision in the conversion process. On the other hand, binary files can't be examined or modified easily using many standard file utilities (such as text editors), and are not portable between different implementations of the language, or different kinds of computers.

These functions are declared in `stdio.h'.

Function: size_t fread (void *data, size_t size, size_t count, FILE *stream)
This function reads up to count objects of size size into the array data, from the stream stream. It returns the number of objects actually read, which might be less than count if a read error occurs or the end of the file is reached. This function returns a value of zero (and doesn't read anything) if either size or count is zero.

If fread encounters end of file in the middle of an object, it returns the number of complete objects read, and discards the partial object. Therefore, the stream remains at the actual end of the file.

Function: size_t fread_unlocked (void *data, size_t size, size_t count, FILE *stream)
The fread_unlocked function is equivalent to the fread function except that it does not implicitly lock the stream.

This function is a GNU extension.

Function: size_t fwrite (const void *data, size_t size, size_t count, FILE *stream)
This function writes up to count objects of size size from the array data, to the stream stream. The return value is normally count, if the call succeeds. Any other value indicates some sort of error, such as running out of space.

Function: size_t fwrite_unlocked (const void *data, size_t size, size_t count, FILE *stream)
The fwrite_unlocked function is equivalent to the fwrite function except that it does not implicitly lock the stream.

This function is a GNU extension.

Formatted Output

The functions described in this section (printf and related functions) provide a convenient way to perform formatted output. You call printf with a format string or template string that specifies how to format the values of the remaining arguments.

Unless your program is a filter that specifically performs line- or character-oriented processing, using printf or one of the other related functions described in this section is usually the easiest and most concise way to perform output. These functions are especially useful for printing error messages, tables of data, and the like.

Formatted Output Basics

The printf function can be used to print any number of arguments. The template string argument you supply in a call provides information not only about the number of additional arguments, but also about their types and what style should be used for printing them.

Ordinary characters in the template string are simply written to the output stream as-is, while conversion specifications introduced by a `%' character in the template cause subsequent arguments to be formatted and written to the output stream. For example,
int pct = 37;
char filename[] = "foo.txt";
printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
        filename, pct);
produces output like
Processing of `foo.txt' is 37% finished.
Please be patient.
This example shows the use of the `%d' conversion to specify that an int argument should be printed in decimal notation, the `%s' conversion to specify printing of a string argument, and the `%%' conversion to print a literal `%' character.

There are also conversions for printing an integer argument as an unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or `%x', respectively); or as a character value (`%c').

Floating-point numbers can be printed in normal, fixed-point notation using the `%f' conversion or in exponential notation using the `%e' conversion. The `%g' conversion uses either `%e' or `%f' format, depending on what is more appropriate for the magnitude of the particular number.

You can control formatting more precisely by writing modifiers between the `%' and the character that indicates which conversion to apply. These slightly alter the ordinary behavior of the conversion. For example, most conversion specifications permit you to specify a minimum field width and a flag indicating whether you want the result left- or right-justified within the field.

The specific flags and modifiers that are permitted and their interpretation vary depending on the particular conversion. They're all described in more detail in the following sections. Don't worry if this all seems excessively complicated at first; you can almost always get reasonable free-format output without using any of the modifiers at all. The modifiers are mostly used to make the output look "prettier" in tables.

Output Conversion Syntax

This section provides details about the precise syntax of conversion specifications that can appear in a printf template string.

Characters in the template string that are not part of a conversion specification are printed as-is to the output stream. Multibyte character sequences (see section Character Set Handling) are permitted in a template string.

The conversion specifications in a printf template string have the general form:
% [ param-no $] flags width [ . precision ] type conversion
For example, in the conversion specifier `%-10.8ld', the `-' is a flag, `10' specifies the field width, the precision is `8', the letter `l' is a type modifier, and `d' specifies the conversion style. (This particular type specifier says to print a long int argument in decimal notation, with a minimum of 8 digits left-justified in a field at least 10 characters wide.)

In more detail, output conversion specifications consist of an initial `%' character followed in sequence by:

An optional specification of the parameter used for this format. Normally the parameters to the printf function are assigned to the formats in the order of appearance in the format string. But in some situations (such as message translation) this is not desirable and this extension allows an explicit parameter to be specified. The param-no part of the format must be an integer in the range of 1 to the maximum number of arguments present to the function call. Some implementations limit this number to a certainly upper bound. The exact limit can be retrieved by the following constant.
Macro: NL_ARGMAX
The value of ARGMAX is the maximum value allowed for the specification of an positional parameter in a printf call. The actual value in effect at runtime can be retrieved by using sysconf using the _SC_NL_ARGMAX parameter see section Definition of sysconf. Some system have a quite low limit such as @math{9} for System V systems. The GNU C library has no real limit. If any of the formats has a specification for the parameter position all of them in the format string shall have one. Otherwise the behaviour is undefined.
Zero or more flag characters that modify the normal behavior of the conversion specification.
An optional decimal integer specifying the minimum field width. If the normal conversion produces fewer characters than this, the field is padded with spaces to the specified width. This is a minimum value; if the normal conversion produces more characters than this, the field is not truncated. Normally, the output is right-justified within the field. You can also specify a field width of `*'. This means that the next argument in the argument list (before the actual value to be printed) is used as the field width. The value must be an int. If the value is negative, this means to set the `-' flag (see below) and to use the absolute value as the field width.
An optional precision to specify the number of digits to be written for the numeric conversions. If the precision is specified, it consists of a period (`.') followed optionally by a decimal integer (which defaults to zero if omitted). You can also specify a precision of `*'. This means that the next argument in the argument list (before the actual value to be printed) is used as the precision. The value must be an int, and is ignored if it is negative. If you specify `*' for both the field width and precision, the field width argument precedes the precision argument. Other C library versions may not recognize this syntax.
An optional type modifier character, which is used to specify the data type of the corresponding argument if it differs from the default type. (For example, the integer conversions assume a type of int, but you can specify `h', `l', or `L' for other integer types.)
A character that specifies the conversion to be applied.

The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they use.

With the `-Wformat' option, the GNU C compiler checks calls to printf and related functions. It examines the format string and verifies that the correct number and types of arguments are supplied. There is also a GNU C syntax to tell the compiler that a function you write uses a printf-style format string. See section `Declaring Attributes of Functions' in Using GNU CC, for more information.

Table of Output Conversions

Here is a table summarizing what all the different conversions do:

`%d', `%i'
Print an integer as a signed decimal number. See section Integer Conversions, for details. `%d' and `%i' are synonymous for output, but are different when used with scanf for input (see section Table of Input Conversions).
`%o'
Print an integer as an unsigned octal number. See section Integer Conversions, for details.
`%u'
Print an integer as an unsigned decimal number. See section Integer Conversions, for details.
`%x', `%X'
Print an integer as an unsigned hexadecimal number. `%x' uses lower-case letters and `%X' uses upper-case. See section Integer Conversions, for details.
`%f'
Print a floating-point number in normal (fixed-point) notation. See section Floating-Point Conversions, for details.
`%e', `%E'
Print a floating-point number in exponential notation. `%e' uses lower-case letters and `%E' uses upper-case. See section Floating-Point Conversions, for details.
`%g', `%G'
Print a floating-point number in either normal or exponential notation, whichever is more appropriate for its magnitude. `%g' uses lower-case letters and `%G' uses upper-case. See section Floating-Point Conversions, for details.
`%a', `%A'
Print a floating-point number in a hexadecimal fractional notation which the exponent to base 2 represented in decimal digits. `%a' uses lower-case letters and `%A' uses upper-case. See section Floating-Point Conversions, for details.
`%c'
Print a single character. See section Other Output Conversions.
`%C'
This is an alias for `%lc' which is supported for compatibility with the Unix standard.
`%s'
Print a string. See section Other Output Conversions.
`%S'
This is an alias for `%ls' which is supported for compatibility with the Unix standard.
`%p'
Print the value of a pointer. See section Other Output Conversions.
`%n'
Get the number of characters printed so far. See section Other Output Conversions. Note that this conversion specification never produces any output.
`%m'
Print the string corresponding to the value of errno. (This is a GNU extension.) See section Other Output Conversions.
`%%'
Print a literal `%' character. See section Other Output Conversions.
If the syntax of a conversion specification is invalid, unpredictable things will happen, so don't do this. If there aren't enough function arguments provided to supply values for all the conversion specifications in the template string, or if the arguments are not of the correct types, the results are unpredictable. If you supply more arguments than conversion specifications, the extra argument values are simply ignored; this is sometimes useful.

Integer Conversions

This section describes the options for the `%d', `%i', `%o', `%u', `%x', and `%X' conversion specifications. These conversions print integers in various formats.

The `%d' and `%i' conversion specifications both print an int argument as a signed decimal number; while `%o', `%u', and `%x' print the argument as an unsigned octal, decimal, or hexadecimal number (respectively). The `%X' conversion specification is just like `%x' except that it uses the characters `ABCDEF' as digits instead of `abcdef'.

The following flags are meaningful:

`-'
Left-justify the result in the field (instead of the normal right-justification).
`+'
For the signed `%d' and `%i' conversions, print a plus sign if the value is positive.
` '
For the signed `%d' and `%i' conversions, if the result doesn't start with a plus or minus sign, prefix it with a space character instead. Since the `+' flag ensures that the result includes a sign, this flag is ignored if you supply both of them.
`#'
For the `%o' conversion, this forces the leading digit to be `0', as if by increasing the precision. For `%x' or `%X', this prefixes a leading `0x' or `0X' (respectively) to the result. This doesn't do anything useful for the `%d', `%i', or `%u' conversions. Using this flag produces output which can be parsed by the strtoul function (see section Parsing of Integers) and scanf with the `%i' conversion (see section Numeric Input Conversions).
`''
Separate the digits into groups as specified by the locale specified for the LC_NUMERIC category; see section Generic Numeric Formatting Parameters. This flag is a GNU extension.
`0'
Pad the field with zeros instead of spaces. The zeros are placed after any indication of sign or base. This flag is ignored if the `-' flag is also specified, or if a precision is specified.
If a precision is supplied, it specifies the minimum number of digits to appear; leading zeros are produced if necessary. If you don't specify a precision, the number is printed with as many digits as it needs. If you convert a value of zero with an explicit precision of zero, then no characters at all are produced.

Without a type modifier, the corresponding argument is treated as an int (for the signed conversions `%i' and `%d') or unsigned int (for the unsigned conversions `%o', `%u', `%x', and `%X'). Recall that since printf and friends are variadic, any char and short arguments are automatically converted to int by the default argument promotions. For arguments of other integer types, you can use these modifiers:

`hh'
Specifies that the argument is a signed char or unsigned char, as appropriate. A char argument is converted to an int or unsigned int by the default argument promotions anyway, but the `h' modifier says to convert it back to a char again. This modifier was introduced in ISO C99.
`h'
Specifies that the argument is a short int or unsigned short int, as appropriate. A short argument is converted to an int or unsigned int by the default argument promotions anyway, but the `h' modifier says to convert it back to a short again.
`j'
Specifies that the argument is a intmax_t or uintmax_t, as appropriate. This modifier was introduced in ISO C99.
`l'
Specifies that the argument is a long int or unsigned long int, as appropriate. Two `l' characters is like the `L' modifier, below. If used with `%c' or `%s' the corresponding parameter is considered as a wide character or wide character string respectively. This use of `l' was introduced in Amendment 1 to ISO C90.
`L'

`ll'

`q'
Specifies that the argument is a long long int. (This type is an extension supported by the GNU C compiler. On systems that don't support extra-long integers, this is the same as long int.) The `q' modifier is another name for the same thing, which comes from 4.4 BSD; a long long int is sometimes called a "quad" int.
`t'
Specifies that the argument is a ptrdiff_t. This modifier was introduced in ISO C99.
`z'

`Z'
Specifies that the argument is a size_t. `z' was introduced in ISO C99. `Z' is a GNU extension predating this addition and should not be used in new code.
Here is an example. Using the template string:
"|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
to print numbers using the different options for the `%d' conversion gives results like:
|    0|0    |   +0|+0   |    0|00000|     |   00|0|
|    1|1    |   +1|+1   |    1|00001|    1|   01|1|
|   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
|100000|100000|+100000| 100000|100000|100000|100000|100000|
In particular, notice what happens in the last case where the number is too large to fit in the minimum field width specified.

Here are some more examples showing how unsigned integers print under various format options, using the template string:
"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
|    0|    0|    0|    0|    0|  0x0|  0X0|0x00000000|
|    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
|100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
Floating-Point Conversions

This section discusses the conversion specifications for floating-point numbers: the `%f', `%e', `%E', `%g', and `%G' conversions.

The `%f' conversion prints its argument in fixed-point notation, producing output of the form [-]ddd.ddd, where the number of digits following the decimal point is controlled by the precision you specify.

The `%e' conversion prints its argument in exponential notation, producing output of the form [-]d.ddd e[+|-]dd. Again, the number of digits following the decimal point is controlled by the precision. The exponent always contains at least two digits. The `%E' conversion is similar but the exponent is marked with the letter `E' instead of `e'.

The `%g' and `%G' conversions print the argument in the style of `%e' or `%E' (respectively) if the exponent would be less than -4 or greater than or equal to the precision; otherwise they use the `%f' style. Trailing zeros are removed from the fractional portion of the result and a decimal-point character appears only if it is followed by a digit.

The `%a' and `%A' conversions are meant for representing floating-point numbers exactly in textual form so that they can be exchanged as texts between different programs and/or machines. The numbers are represented is the form [-]0x h.hhh p[+|-]dd. At the left of the decimal-point character exactly one digit is print. This character is only 0 if the number is denormalized. Otherwise the value is unspecified; it is implementation dependent how many bits are used. The number of hexadecimal digits on the right side of the decimal-point character is equal to the precision. If the precision is zero it is determined to be large enough to provide an exact representation of the number (or it is large enough to distinguish two adjacent values if the FLT_RADIX is not a power of 2, see section Floating Point Parameters). For the `%a' conversion lower-case characters are used to represent the hexadecimal number and the prefix and exponent sign are printed as 0x and p respectively. Otherwise upper-case characters are used and 0X and P are used for the representation of prefix and exponent string. The exponent to the base of two is printed as a decimal number using at least one digit but at most as many digits as necessary to represent the value exactly.

If the value to be printed represents infinity or a NaN, the output is [-]inf or nan respectively if the conversion specifier is `%a', `%e', `%f', or `%g' and it is [-]INF or NAN respectively if the conversion is `%A', `%E', or `%G'.

The following flags can be used to modify the behavior:

`-'
Left-justify the result in the field. Normally the result is right-justified.
`+'
Always include a plus or minus sign in the result.
` '
If the result doesn't start with a plus or minus sign, prefix it with a space instead. Since the `+' flag ensures that the result includes a sign, this flag is ignored if you supply both of them.
`#'
Specifies that the result should always include a decimal point, even if no digits follow it. For the `%g' and `%G' conversions, this also forces trailing zeros after the decimal point to be left in place where they would otherwise be removed.
`''
Separate the digits of the integer part of the result into groups as specified by the locale specified for the LC_NUMERIC category; see section Generic Numeric Formatting Parameters. This flag is a GNU extension.
`0'
Pad the field with zeros instead of spaces; the zeros are placed after any sign. This flag is ignored if the `-' flag is also specified.
The precision specifies how many digits follow the decimal-point character for the `%f', `%e', and `%E' conversions. For these conversions, the default precision is 6. If the precision is explicitly 0, this suppresses the decimal point character entirely. For the `%g' and `%G' conversions, the precision specifies how many significant digits to print. Significant digits are the first digit before the decimal point, and all the digits after it. If the precision is 0 or not specified for `%g' or `%G', it is treated like a value of 1. If the value being printed cannot be expressed accurately in the specified number of digits, the value is rounded to the nearest number that fits.

Without a type modifier, the floating-point conversions use an argument of type double. (By the default argument promotions, any float arguments are automatically converted to double.) The following type modifier is supported:

`L'
An uppercase `L' specifies that the argument is a long double.
Here are some examples showing how numbers print using the various floating-point conversions. All of the numbers were printed using this template string:
"|%13.4a|%13.4f|%13.4e|%13.4g|\n"
Here is the output:
|  0x0.0000p+0|       0.0000|   0.0000e+00|            0|
|  0x1.0000p-1|       0.5000|   5.0000e-01|          0.5|
|  0x1.0000p+0|       1.0000|   1.0000e+00|            1|
| -0x1.0000p+0|      -1.0000|  -1.0000e+00|           -1|
|  0x1.9000p+6|     100.0000|   1.0000e+02|          100|
|  0x1.f400p+9|    1000.0000|   1.0000e+03|         1000|
| 0x1.3880p+13|   10000.0000|   1.0000e+04|        1e+04|
| 0x1.81c8p+13|   12345.0000|   1.2345e+04|    1.234e+04|
| 0x1.86a0p+16|  100000.0000|   1.0000e+05|        1e+05|
| 0x1.e240p+16|  123456.0000|   1.2346e+05|    1.235e+05|
Notice how the `%g' conversion drops trailing zeros.

Other Output Conversions

This section describes miscellaneous conversions for printf.

The `%c' conversion prints a single character. In case there is no `l' modifier the int argument is first converted to an unsigned char. Then, if used in a wide stream function, the character is converted into the corresponding wide character. The `-' flag can be used to specify left-justification in the field, but no other flags are defined, and no precision or type modifier can be given. For example:
printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
prints `hello'.

If there is a `l' modifier present the argument is expected to be of type wint_t. If used in a multibyte function the wide character is converted into a multibyte character before being added to the output. In this case more than one output byte can be produced.

The `%s' conversion prints a string. If no `l' modifier is present the corresponding argument must be of type char * (or const char *). If used in a wide stream function the string is first converted in a wide character string. A precision can be specified to indicate the maximum number of characters to write; otherwise characters in the string up to but not including the terminating null character are written to the output stream. The `-' flag can be used to specify left-justification in the field, but no other flags or type modifiers are defined for this conversion. For example:
printf ("%3s%-6s", "no", "where");
prints ` nowhere '.

If there is a `l' modifier present the argument is expected to be of type wchar_t (or const wchar_t *).

If you accidentally pass a null pointer as the argument for a `%s' conversion, the GNU library prints it as `(null)'. We think this is more useful than crashing. But it's not good practice to pass a null argument intentionally.

The `%m' conversion prints the string corresponding to the error code in errno. See section Error Messages. Thus:
fprintf (stderr, "can't open `%s': %m\n", filename);
is equivalent to:
fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
The `%m' conversion is a GNU C library extension.

The `%p' conversion prints a pointer value. The corresponding argument must be of type void *. In practice, you can use any type of pointer.

In the GNU system, non-null pointers are printed as unsigned integers, as if a `%#x' conversion were used. Null pointers print as `(nil)'. (Pointers might print differently in other systems.)

For example:
printf ("%p", "testing");
prints `0x' followed by a hexadecimal number--the address of the string constant "testing". It does not print the word `testing'.

You can supply the `-' flag with the `%p' conversion to specify left-justification, but no other flags, precision, or type modifiers are defined.

The `%n' conversion is unlike any of the other output conversions. It uses an argument which must be a pointer to an int, but instead of printing anything it stores the number of characters printed so far by this call at that location. The `h' and `l' type modifiers are permitted to specify that the argument is of type short int * or long int * instead of int *, but no flags, field width, or precision are permitted.

For example,
int nchar;
printf ("%d %s%n\n", 3, "bears", &nchar);
prints:
3 bears
and sets nchar to 7, because `3 bears' is seven characters.

The `%%' conversion prints a literal `%' character. This conversion doesn't use an argument, and no flags, field width, precision, or type modifiers are permitted.

Formatted Output Functions

This section describes how to call printf and related functions. Prototypes for these functions are in the header file `stdio.h'. Because these functions take a variable number of arguments, you must declare prototypes for them before using them. Of course, the easiest way to make sure you have all the right prototypes is to just include `stdio.h'.

Function: int printf (const char *template, ...)
The printf function prints the optional arguments under the control of the template string template to the stream stdout. It returns the number of characters printed, or a negative value if there was an output error.

Function: int wprintf (const wchar_t *template, ...)
The wprintf function prints the optional arguments under the control of the wide template string template to the stream stdout. It returns the number of wide characters printed, or a negative value if there was an output error.

Function: int fprintf (FILE *stream, const char *template, ...)
This function is just like printf, except that the output is written to the stream stream instead of stdout.

Function: int fwprintf (FILE *stream, const wchar_t *template, ...)
This function is just like wprintf, except that the output is written to the stream stream instead of stdout.

Function: int sprintf (char *s, const char *template, ...)
This is like printf, except that the output is stored in the character array s instead of written to a stream. A null character is written to mark the end of the string.

The sprintf function returns the number of characters stored in the array s, not including the terminating null character.

The behavior of this function is undefined if copying takes place between objects that overlap--for example, if s is also given as an argument to be printed under control of the `%s' conversion. See section Copying and Concatenation.

Warning: The sprintf function can be dangerous because it can potentially output more characters than can fit in the allocation size of the string s. Remember that the field width given in a conversion specification is only a minimum value.

To avoid this problem, you can use snprintf or asprintf, described below.

Function: int swprintf (wchar_t *s, size_t size, const wchar_t *template, ...)
This is like wprintf, except that the output is stored in the wide character array ws instead of written to a stream. A null wide character is written to mark the end of the string. The size argument specifies the maximum number of characters to produce. The trailing null character is counted towards this limit, so you should allocate at least size wide characters for the string ws.

The return value is the number of characters which would be generated for the given input, excluding the trailing null. If this value is greater or equal to size, not all characters from the result have been stored in ws. You should try again with a bigger output string.

Note that the corresponding narrow stream function takes fewer parameters. swprintf in fact corresponds to the snprintf function. Since the sprintf function can be dangerous and should be avoided the ISO C committee refused to make the same mistake again and decided to not define an function exactly corresponding to sprintf.

Function: int snprintf (char *s, size_t size, const char *template, ...)
The snprintf function is similar to sprintf, except that the size argument specifies the maximum number of characters to produce. The trailing null character is counted towards this limit, so you should allocate at least size characters for the string s.

The return value is the number of characters which would be generated for the given input, excluding the trailing null. If this value is greater or equal to size, not all characters from the result have been stored in s. You should try again with a bigger output string. Here is an example of doing this:
/* Construct a message describing the value of a variable
   whose name is name and whose value is value. */
char *
make_message (char *name, char *value)
{
  /* Guess we need no more than 100 chars of space. */
  int size = 100;
  char *buffer = (char *) xmalloc (size);
  int nchars;
  if (buffer == NULL)
    return NULL;

 /* Try to print in the allocated space. */
  nchars = snprintf (buffer, size, "value of %s is %s",
                     name, value);
  if (nchars >= size)
    {
      /* Reallocate buffer now that we know
         how much space is needed. */
      buffer = (char *) xrealloc (buffer, nchars + 1);

      if (buffer != NULL)
        /* Try again. */
        snprintf (buffer, size, "value of %s is %s",
                  name, value);
    }
  /* The last call worked, return the string. */
  return buffer;
}
In practice, it is often easier just to use asprintf, below.

Attention: In versions of the GNU C library prior to 2.1 the return value is the number of characters stored, not including the terminating null; unless there was not enough space in s to store the result in which case -1 is returned. This was changed in order to comply with the ISO C99 standard.

Dynamically Allocating Formatted Output

The functions in this section do formatted output and place the results in dynamically allocated memory.

Function: int asprintf (char **ptr, const char *template, ...)
This function is similar to sprintf, except that it dynamically allocates a string (as with malloc; see section Unconstrained Allocation) to hold the output, instead of putting the output in a buffer you allocate in advance. The ptr argument should be the address of a char * object, and asprintf stores a pointer to the newly allocated string at that location.

The return value is the number of characters allocated for the buffer, or less than zero if an error occured. Usually this means that the buffer could not be allocated.

Here is how to use asprintf to get the same result as the snprintf example, but more easily:
/* Construct a message describing the value of a variable
   whose name is name and whose value is value. */
char *
make_message (char *name, char *value)
{
  char *result;
  if (asprintf (&result, "value of %s is %s", name, value) < 0)
    return NULL;
  return result;
}
Function: int obstack_printf (struct obstack *obstack, const char *template, ...)
This function is similar to asprintf, except that it uses the obstack obstack to allocate the space. See section Obstacks.

The characters are written onto the end of the current object. To get at them, you must finish the object with obstack_finish (see section Growing Objects).

Variable Arguments Output Functions

The functions vprintf and friends are provided so that you can define your own variadic printf-like functions that make use of the same internals as the built-in formatted output functions.

The most natural way to define such functions would be to use a language construct to say, "Call printf and pass this template plus all of my arguments after the first five." But there is no way to do this in C, and it would be hard to provide a way, since at the C language level there is no way to tell how many arguments your function received.

Since that method is impossible, we provide alternative functions, the vprintf series, which lets you pass a va_list to describe "all of my arguments after the first five."

When it is sufficient to define a macro rather than a real function, the GNU C compiler provides a way to do this much more easily with macros. For example:
#define myprintf(a, b, c, d, e, rest...) \
            printf (mytemplate , ## rest...)
See section `Macros with Variable Numbers of Arguments' in Using GNU CC, for details. But this is limited to macros, and does not apply to real functions at all.

Before calling vprintf or the other functions listed in this section, you must call va_start (see section Variadic Functions) to initialize a pointer to the variable arguments. Then you can call va_arg to fetch the arguments that you want to handle yourself. This advances the pointer past those arguments.

Once your va_list pointer is pointing at the argument of your choice, you are ready to call vprintf. That argument and all subsequent arguments that were passed to your function are used by vprintf along with the template that you specified separately.

In some other systems, the va_list pointer may become invalid after the call to vprintf, so you must not use va_arg after you call vprintf. Instead, you should call va_end to retire the pointer from service. However, you can safely call va_start on another pointer variable and begin fetching the arguments again through that pointer. Calling vprintf does not destroy the argument list of your function, merely the particular pointer that you passed to it.

GNU C does not have such restrictions. You can safely continue to fetch arguments from a va_list pointer after passing it to vprintf, and va_end is a no-op. (Note, however, that subsequent va_arg calls will fetch the same arguments which vprintf previously used.)

Prototypes for these functions are declared in `stdio.h'.

Function: int vprintf (const char *template, va_list ap)
This function is similar to printf except that, instead of taking a variable number of arguments directly, it takes an argument list pointer ap.

Function: int vwprintf (const wchar_t *template, va_list ap)
This function is similar to wprintf except that, instead of taking a variable number of arguments directly, it takes an argument list pointer ap.

Function: int vfprintf (FILE *stream, const char *template, va_list ap)
This is the equivalent of fprintf with the variable argument list specified directly as for vprintf.

Function: int vfwprintf (FILE *stream, const wchar_t *template, va_list ap)
This is the equivalent of fwprintf with the variable argument list specified directly as for vwprintf.

Function: int vsprintf (char *s, const char *template, va_list ap)
This is the equivalent of sprintf with the variable argument list specified directly as for vprintf.

Function: int vswprintf (wchar_t *s, size_t size, const wchar_t *template, va_list ap)
This is the equivalent of swprintf with the variable argument list specified directly as for vwprintf.

Function: int vsnprintf (char *s, size_t size, const char *template, va_list ap)
This is the equivalent of snprintf with the variable argument list specified directly as for vprintf.

Function: int vasprintf (char **ptr, const char *template, va_list ap)
The vasprintf function is the equivalent of asprintf with the variable argument list specified directly as for vprintf.

Function: int obstack_vprintf (struct obstack *obstack, const char *template, va_list ap)
The obstack_vprintf function is the equivalent of obstack_printf with the variable argument list specified directly as for vprintf.

Here's an example showing how you might use vfprintf. This is a function that prints error messages to the stream stderr, along with a prefix indicating the name of the program (see section Error Messages, for a description of program_invocation_short_name).
#include <stdio.h>
#include <stdarg.h>

void
eprintf (const char *template, ...)
{
  va_list ap;
  extern char *program_invocation_short_name;

  fprintf (stderr, "%s: ", program_invocation_short_name);
  va_start (ap, template);
  vfprintf (stderr, template, ap);
  va_end (ap);
}
You could call eprintf like this:
eprintf ("file `%s' does not exist\n", filename);
In GNU C, there is a special construct you can use to let the compiler know that a function uses a printf-style format string. Then it can check the number and types of arguments in each call to the function, and warn you when they do not match the format string. For example, take this declaration of eprintf:
void eprintf (const char *template, ...)
        __attribute__ ((format (printf, 1, 2)));
This tells the compiler that eprintf uses a format string like printf (as opposed to scanf; see section Formatted Input); the format string appears as the first argument; and the arguments to satisfy the format begin with the second. See section `Declaring Attributes of Functions' in Using GNU CC, for more information.

Parsing a Template String

You can use the function parse_printf_format to obtain information about the number and types of arguments that are expected by a given template string. This function permits interpreters that provide interfaces to printf to avoid passing along invalid arguments from the user's program, which could cause a crash.

All the symbols described in this section are declared in the header file `printf.h'.

Function: size_t parse_printf_format (const char *template, size_t n, int *argtypes)
This function returns information about the number and types of arguments expected by the printf template string template. The information is stored in the array argtypes; each element of this array describes one argument. This information is encoded using the various `PA_' macros, listed below.

The argument n specifies the number of elements in the array argtypes. This is the maximum number of elements that parse_printf_format will try to write.

parse_printf_format returns the total number of arguments required by template. If this number is greater than n, then the information returned describes only the first n arguments. If you want information about additional arguments, allocate a bigger array and call parse_printf_format again.

The argument types are encoded as a combination of a basic type and modifier flag bits.

Macro: int PA_FLAG_MASK
This macro is a bitmask for the type modifier flag bits. You can write the expression (argtypes[i] & PA_FLAG_MASK) to extract just the flag bits for an argument, or (argtypes[i] & ~PA_FLAG_MASK) to extract just the basic type code.

Here are symbolic constants that represent the basic types; they stand for integer values.

PA_INT
This specifies that the base type is int.
PA_CHAR
This specifies that the base type is int, cast to char.
PA_STRING
This specifies that the base type is char *, a null-terminated string.
PA_POINTER
This specifies that the base type is void *, an arbitrary pointer.
PA_FLOAT
This specifies that the base type is float.
PA_DOUBLE
This specifies that the base type is double.
PA_LAST
You can define additional base types for your own programs as offsets from PA_LAST. For example, if you have data types `foo' and `bar' with their own specialized printf conversions, you could define encodings for these types as:
#define PA_FOO  PA_LAST
#define PA_BAR  (PA_LAST + 1)
Here are the flag bits that modify a basic type. They are combined with the code for the basic type using inclusive-or.

PA_FLAG_PTR
If this bit is set, it indicates that the encoded type is a pointer to the base type, rather than an immediate value. For example, `PA_INT|PA_FLAG_PTR' represents the type `int *'.
PA_FLAG_SHORT
If this bit is set, it indicates that the base type is modified with short. (This corresponds to the `h' type modifier.)
PA_FLAG_LONG
If this bit is set, it indicates that the base type is modified with long. (This corresponds to the `l' type modifier.)
PA_FLAG_LONG_LONG
If this bit is set, it indicates that the base type is modified with long long. (This corresponds to the `L' type modifier.)
PA_FLAG_LONG_DOUBLE
This is a synonym for PA_FLAG_LONG_LONG, used by convention with a base type of PA_DOUBLE to indicate a type of long double.
Example of Parsing a Template String

Here is an example of decoding argument types for a format string. We assume this is part of an interpreter which contains arguments of type NUMBER, CHAR, STRING and STRUCTURE (and perhaps others which are not valid here).
/* Test whether the nargs specified objects
   in the vector args are valid
   for the format string format:
   if so, return 1.
   If not, return 0 after printing an error message.  */

int
validate_args (char *format, int nargs, OBJECT *args)
{
  int *argtypes;
  int nwanted;

  /* Get the information about the arguments.
     Each conversion specification must be at least two characters
     long, so there cannot be more specifications than half the
     length of the string.  */

  argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
  nwanted = parse_printf_format (string, nelts, argtypes);

  /* Check the number of arguments.  */
  if (nwanted > nargs)
    {
      error ("too few arguments (at least %d required)", nwanted);
      return 0;
    }

  /* Check the C type wanted for each argument
     and see if the object given is suitable.  */
  for (i = 0; i < nwanted; i++)
    {
      int wanted;

      if (argtypes[i] & PA_FLAG_PTR)
        wanted = STRUCTURE;
      else
        switch (argtypes[i] & ~PA_FLAG_MASK)
          {
          case PA_INT:
          case PA_FLOAT:
          case PA_DOUBLE:
            wanted = NUMBER;
            break;
          case PA_CHAR:
            wanted = CHAR;
            break;
          case PA_STRING:
            wanted = STRING;
            break;
          case PA_POINTER:
            wanted = STRUCTURE;
            break;
          }
      if (TYPE (args[i]) != wanted)
        {
          error ("type mismatch for arg number %d", i);
          return 0;
        }
    }
  return 1;
}
Customizing printf

The GNU C library lets you define your own custom conversion specifiers for printf template strings, to teach printf clever ways to print the important data structures of your program.

The way you do this is by registering the conversion with the function register_printf_function; see section Registering New Conversions. One of the arguments you pass to this function is a pointer to a handler function that produces the actual output; see section Defining the Output Handler, for information on how to write this function.

You can also install a function that just returns information about the number and type of arguments expected by the conversion specifier. See section Parsing a Template String, for information about this.

The facilities of this section are declared in the header file `printf.h'.

Portability Note: The ability to extend the syntax of printf template strings is a GNU extension. ISO standard C has nothing similar.

Registering New Conversions

The function to register a new output conversion is register_printf_function, declared in `printf.h'.

Function: int register_printf_function (int spec, printf_function handler-function, printf_arginfo_function arginfo-function)
This function defines the conversion specifier character spec. Thus, if spec is 'Y', it defines the conversion `%Y'. You can redefine the built-in conversions like `%s', but flag characters like `#' and type modifiers like `l' can never be used as conversions; calling register_printf_function for those characters has no effect. It is advisable not to use lowercase letters, since the ISO C standard warns that additional lowercase letters may be standardized in future editions of the standard.

The handler-function is the function called by printf and friends when this conversion appears in a template string. See section Defining the Output Handler, for information about how to define a function to pass as this argument. If you specify a null pointer, any existing handler function for spec is removed.

The arginfo-function is the function called by parse_printf_format when this conversion appears in a template string. See section Parsing a Template String, for information about this.

Attention: In the GNU C library versions before 2.0 the arginfo-function function did not need to be installed unless the user used the parse_printf_format function. This has changed. Now a call to any of the printf functions will call this function when this format specifier appears in the format string.

The return value is 0 on success, and -1 on failure (which occurs if spec is out of range).

You can redefine the standard output conversions, but this is probably not a good idea because of the potential for confusion. Library routines written by other people could break if you do this.

Conversion Specifier Options

If you define a meaning for `%A', what if the template contains `%+23A' or `%-#A'? To implement a sensible meaning for these, the handler when called needs to be able to get the options specified in the template.

Both the handler-function and arginfo-function accept an argument that points to a struct printf_info, which contains information about the options appearing in an instance of the conversion specifier. This data type is declared in the header file `printf.h'.

Type: struct printf_info
This structure is used to pass information about the options appearing in an instance of a conversion specifier in a printf template string to the handler and arginfo functions for that specifier. It contains the following members:

int prec
This is the precision specified. The value is -1 if no precision was specified. If the precision was given as `*', the printf_info structure passed to the handler function contains the actual value retrieved from the argument list. But the structure passed to the arginfo function contains a value of INT_MIN, since the actual value is not known.
int width
This is the minimum field width specified. The value is 0 if no width was specified. If the field width was given as `*', the printf_info structure passed to the handler function contains the actual value retrieved from the argument list. But the structure passed to the arginfo function contains a value of INT_MIN, since the actual value is not known.
wchar_t spec
This is the conversion specifier character specified. It's stored in the structure so that you can register the same handler function for multiple characters, but still have a way to tell them apart when the handler function is called.
unsigned int is_long_double
This is a boolean that is true if the `L', `ll', or `q' type modifier was specified. For integer conversions, this indicates long long int, as opposed to long double for floating point conversions.
unsigned int is_char
This is a boolean that is true if the `hh' type modifier was specified.
unsigned int is_short
This is a boolean that is true if the `h' type modifier was specified.
unsigned int is_long
This is a boolean that is true if the `l' type modifier was specified.
unsigned int alt
This is a boolean that is true if the `#' flag was specified.
unsigned int space
This is a boolean that is true if the ` ' flag was specified.
unsigned int left
This is a boolean that is true if the `-' flag was specified.
unsigned int showsign
This is a boolean that is true if the `+' flag was specified.
unsigned int group
This is a boolean that is true if the `'' flag was specified.
unsigned int extra
This flag has a special meaning depending on the context. It could be used freely by the user-defined handlers but when called from the printf function this variable always contains the value 0.
unsigned int wide
This flag is set if the stream is wide oriented.
wchar_t pad
This is the character to use for padding the output to the minimum field width. The value is '0' if the `0' flag was specified, and ' ' otherwise.
Defining the Output Handler

Now let's look at how to define the handler and arginfo functions which are passed as arguments to register_printf_function.

Compatibility Note: The interface changed in GNU libc version 2.0. Previously the third argument was of type va_list *.

You should define your handler functions with a prototype like:
int function (FILE *stream, const struct printf_info *info,
                    const void *const *args)
The stream argument passed to the handler function is the stream to which it should write output.

The info argument is a pointer to a structure that contains information about the various options that were included with the conversion in the template string. You should not modify this structure inside your handler function. See section Conversion Specifier Options, for a description of this data structure.

The args is a vector of pointers to the arguments data. The number of arguments was determined by calling the argument information function provided by the user.

Your handler function should return a value just like printf does: it should return the number of characters it has written, or a negative value to indicate an error.

Data Type: printf_function
This is the data type that a handler function should have.

If you are going to use parse_printf_format in your application, you must also define a function to pass as the arginfo-function argument for each new conversion you install with register_printf_function.

You have to define these functions with a prototype like:
int function (const struct printf_info *info,
                    size_t n, int *argtypes)
The return value from the function should be the number of arguments the conversion expects. The function should also fill in no more than n elements of the argtypes array with information about the types of each of these arguments. This information is encoded using the various `PA_' macros. (You will notice that this is the same calling convention parse_printf_format itself uses.)

Data Type: printf_arginfo_function
This type is used to describe functions that return information about the number and type of arguments used by a conversion specifier.

printf Extension Example

Here is an example showing how to define a printf handler function. This program defines a data structure called a Widget and defines the `%W' conversion to print information about Widget * arguments, including the pointer value and the name stored in the data structure. The `%W' conversion supports the minimum field width and left-justification options, but ignores everything else.
#include <stdio.h>
#include <stdlib.h>
#include <printf.h>

typedef struct
{
  char *name;
}
Widget;

int
print_widget (FILE *stream,
              const struct printf_info *info,
              const void *const *args)
{
  const Widget *w;
  char *buffer;
  int len;

  /* Format the output into a string. */
  w = *((const Widget **) (args[0]));
  len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
  if (len == -1)
    return -1;

  /* Pad to the minimum field width and print to the stream. */
  len = fprintf (stream, "%*s",
                 (info->left ? -info->width : info->width),
                 buffer);

  /* Clean up and return. */
  free (buffer);
  return len;
}

int
print_widget_arginfo (const struct printf_info *info, size_t n,
                      int *argtypes)
{
  /* We always take exactly one argument and this is a pointer to the
     structure.. */
  if (n > 0)
    argtypes[0] = PA_POINTER;
  return 1;
}

int
main (void)
{
  /* Make a widget to print. */
  Widget mywidget;
  mywidget.name = "mywidget";

  /* Register the print function for widgets. */
  register_printf_function ('W', print_widget, print_widget_arginfo);

  /* Now print the widget. */
  printf ("|%W|\n", &mywidget);
  printf ("|%35W|\n", &mywidget);
  printf ("|%-35W|\n", &mywidget);

  return 0;
}
The output produced by this program looks like:
|<Widget 0xffeffb7c: mywidget>|
|      <Widget 0xffeffb7c: mywidget>|
|<Widget 0xffeffb7c: mywidget>      |
Predefined printf Handlers

The GNU libc also contains a concrete and useful application of the printf handler extension. There are two functions available which implement a special way to print floating-point numbers.

Function: int printf_size (FILE *fp, const struct printf_info *info, const void *const *args)
Print a given floating point number as for the format %f except that there is a postfix character indicating the divisor for the number to make this less than 1000. There are two possible divisors: powers of 1024 or powers of 1000. Which one is used depends on the format character specified while registered this handler. If the character is of lower case, 1024 is used. For upper case characters, 1000 is used.

The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes, etc. The full table is:

The default precision is 3, i.e., 1024 is printed with a lower-case format character as if it were %.3fk and will yield 1.000k.

Due to the requirements of register_printf_function we must also provide the function which returns information about the arguments.

Function: int printf_size_info (const struct printf_info *info, size_t n, int *argtypes)
This function will return in argtypes the information about the used parameters in the way the vfprintf implementation expects it. The format always takes one argument.

To use these functions both functions must be registered with a call like
register_printf_function ('B', printf_size, printf_size_info);
Here we register the functions to print numbers as powers of 1000 since the format character 'B' is an upper-case character. If we would additionally use 'b' in a line like
register_printf_function ('b', printf_size, printf_size_info);
we could also print using a power of 1024. Please note that all that is different in these two lines is the format specifier. The printf_size function knows about the difference between lower and upper case format specifiers.

The use of 'B' and 'b' is no coincidence. Rather it is the preferred way to use this functionality since it is available on some other systems which also use format specifiers.

Formatted Input

The functions described in this section (scanf and related functions) provide facilities for formatted input analogous to the formatted output facilities. These functions provide a mechanism for reading arbitrary values under the control of a format string or template string.

Formatted Input Basics

Calls to scanf are superficially similar to calls to printf in that arbitrary arguments are read under the control of a template string. While the syntax of the conversion specifications in the template is very similar to that for printf, the interpretation of the template is oriented more towards free-format input and simple pattern matching, rather than fixed-field formatting. For example, most scanf conversions skip over any amount of "white space" (including spaces, tabs, and newlines) in the input file, and there is no concept of precision for the numeric input conversions as there is for the corresponding output conversions. Ordinarily, non-whitespace characters in the template are expected to match characters in the input stream exactly, but a matching failure is distinct from an input error on the stream.

Another area of difference between scanf and printf is that you must remember to supply pointers rather than immediate values as the optional arguments to scanf; the values that are read are stored in the objects that the pointers point to. Even experienced programmers tend to forget this occasionally, so if your program is getting strange errors that seem to be related to scanf, you might want to double-check this.

When a matching failure occurs, scanf returns immediately, leaving the first non-matching character as the next character to be read from the stream. The normal return value from scanf is the number of values that were assigned, so you can use this to determine if a matching error happened before all the expected values were read.

The scanf function is typically used for things like reading in the contents of tables. For example, here is a function that uses scanf to initialize an array of double:
void
readarray (double *array, int n)
{
  int i;
  for (i=0; i<n; i++)
    if (scanf (" %lf", &(array[i])) != 1)
      invalid_input_error ();
}
The formatted input functions are not used as frequently as the formatted output functions. Partly, this is because it takes some care to use them properly. Another reason is that it is difficult to recover from a matching error.

If you are trying to read input that doesn't match a single, fixed pattern, you may be better off using a tool such as Flex to generate a lexical scanner, or Bison to generate a parser, rather than using scanf. For more information about these tools, see section `' in Flex: The Lexical Scanner Generator, and section `' in The Bison Reference Manual.

Input Conversion Syntax

A scanf template string is a string that contains ordinary multibyte characters interspersed with conversion specifications that start with `%'.

Any whitespace character (as defined by the isspace function; see section Classification of Characters) in the template causes any number of whitespace characters in the input stream to be read and discarded. The whitespace characters that are matched need not be exactly the same whitespace characters that appear in the template string. For example, write ` , ' in the template to recognize a comma with optional whitespace before and after.

Other characters in the template string that are not part of conversion specifications must match characters in the input stream exactly; if this is not the case, a matching failure occurs.

The conversion specifications in a scanf template string have the general form:
% flags width type conversion
In more detail, an input conversion specification consists of an initial `%' character followed in sequence by:

An optional flag character `*', which says to ignore the text read for this specification. When scanf finds a conversion specification that uses this flag, it reads input as directed by the rest of the conversion specification, but it discards this input, does not use a pointer argument, and does not increment the count of successful assignments.
An optional flag character `a' (valid with string conversions only) which requests allocation of a buffer long enough to store the string in. (This is a GNU extension.) See section Dynamically Allocating String Conversions.
An optional decimal integer that specifies the maximum field width. Reading of characters from the input stream stops either when this maximum is reached or when a non-matching character is found, whichever happens first. Most conversions discard initial whitespace characters (those that don't are explicitly documented), and these discarded characters don't count towards the maximum field width. String input conversions store a null character to mark the end of the input; the maximum field width does not include this terminator.
An optional type modifier character. For example, you can specify a type modifier of `l' with integer conversions such as `%d' to specify that the argument is a pointer to a long int rather than a pointer to an int.
A character that specifies the conversion to be applied.

The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they allow.

With the `-Wformat' option, the GNU C compiler checks calls to scanf and related functions. It examines the format string and verifies that the correct number and types of arguments are supplied. There is also a GNU C syntax to tell the compiler that a function you write uses a scanf-style format string. See section `Declaring Attributes of Functions' in Using GNU CC, for more information.

Table of Input Conversions

Here is a table that summarizes the various conversion specifications:

`%d'
Matches an optionally signed integer written in decimal. See section Numeric Input Conversions.
`%i'
Matches an optionally signed integer in any of the formats that the C language defines for specifying an integer constant. See section Numeric Input Conversions.
`%o'
Matches an unsigned integer written in octal radix. See section Numeric Input Conversions.
`%u'
Matches an unsigned integer written in decimal radix. See section Numeric Input Conversions.
`%x', `%X'
Matches an unsigned integer written in hexadecimal radix. See section Numeric Input Conversions.
`%e', `%f', `%g', `%E', `%G'
Matches an optionally signed floating-point number. See section Numeric Input Conversions.
`%s'
Matches a string containing only non-whitespace characters. See section String Input Conversions. The presence of the `l' modifier determines whether the output is stored as a wide character string or a multibyte string. If `%s' is used in a wide character function the string is converted as with multiple calls to wcrtomb into a multibyte string. This means that the buffer must provide room for MB_CUR_MAX bytes for each wide character read. In case `%ls' is used in a multibyte function the result is converted into wide characters as with multiple calls of mbrtowc before being stored in the user provided buffer.
`%S'
This is an alias for `%ls' which is supported for compatibility with the Unix standard.
`%['
Matches a string of characters that belong to a specified set. See section String Input Conversions. The presence of the `l' modifier determines whether the output is stored as a wide character string or a multibyte string. If `%[' is used in a wide character function the string is converted as with multiple calls to wcrtomb into a multibyte string. This means that the buffer must provide room for MB_CUR_MAX bytes for each wide character read. In case `%l[' is used in a multibyte function the result is converted into wide characters as with multiple calls of mbrtowc before being stored in the user provided buffer.
`%c'
Matches a string of one or more characters; the number of characters read is controlled by the maximum field width given for the conversion. See section String Input Conversions. If the `%c' is used in a wide stream function the read value is converted from a wide character to the corresponding multibyte character before storing it. Note that this conversion can produce more than one byte of output and therefore the provided buffer be large enough for up to MB_CUR_MAX bytes for each character. If `%lc' is used in a multibyte function the input is treated as a multibyte sequence (and not bytes) and the result is converted as with calls to mbrtowc.
`%C'
This is an alias for `%lc' which is supported for compatibility with the Unix standard.
`%p'
Matches a pointer value in the same implementation-defined format used by the `%p' output conversion for printf. See section Other Input Conversions.
`%n'
This conversion doesn't read any characters; it records the number of characters read so far by this call. See section Other Input Conversions.
`%%'
This matches a literal `%' character in the input stream. No corresponding argument is used. See section Other Input Conversions.
If the syntax of a conversion specification is invalid, the behavior is undefined. If there aren't enough function arguments provided to supply addresses for all the conversion specifications in the template strings that perform assignments, or if the arguments are not of the correct types, the behavior is also undefined. On the other hand, extra arguments are simply ignored.

Numeric Input Conversions

This section describes the scanf conversions for reading numeric values.

The `%d' conversion matches an optionally signed integer in decimal radix. The syntax that is recognized is the same as that for the strtol function (see section Parsing of Integers) with the value 10 for the base argument.

The `%i' conversion matches an optionally signed integer in any of the formats that the C language defines for specifying an integer constant. The syntax that is recognized is the same as that for the strtol function (see section Parsing of Integers) with the value 0 for the base argument. (You can print integers in this syntax with printf by using the `#' flag character with the `%x', `%o', or `%d' conversion. See section Integer Conversions.)

For example, any of the strings `10', `0xa', or `012' could be read in as integers under the `%i' conversion. Each of these specifies a number with decimal value 10.

The `%o', `%u', and `%x' conversions match unsigned integers in octal, decimal, and hexadecimal radices, respectively. The syntax that is recognized is the same as that for the strtoul function (see section Parsing of Integers) with the appropriate value (8, 10, or 16) for the base argument.

The `%X' conversion is identical to the `%x' conversion. They both permit either uppercase or lowercase letters to be used as digits.

The default type of the corresponding argument for the %d and %i conversions is int *, and unsigned int * for the other integer conversions. You can use the following type modifiers to specify other sizes of integer:

`hh'
Specifies that the argument is a signed char * or unsigned char *. This modifier was introduced in ISO C99.
`h'
Specifies that the argument is a short int * or unsigned short int *.
`j'
Specifies that the argument is a intmax_t * or uintmax_t *. This modifier was introduced in ISO C99.
`l'
Specifies that the argument is a long int * or unsigned long int *. Two `l' characters is like the `L' modifier, below. If used with `%c' or `%s' the corresponding parameter is considered as a pointer to a wide character or wide character string respectively. This use of `l' was introduced in Amendment 1 to ISO C90.
`ll'

`L'

`q'
Specifies that the argument is a long long int * or unsigned long long int *. (The long long type is an extension supported by the GNU C compiler. For systems that don't provide extra-long integers, this is the same as long int.) The `q' modifier is another name for the same thing, which comes from 4.4 BSD; a long long int is sometimes called a "quad" int.
`t'
Specifies that the argument is a ptrdiff_t *. This modifier was introduced in ISO C99.
`z'
Specifies that the argument is a size_t *. This modifier was introduced in ISO C99.
All of the `%e', `%f', `%g', `%E', and `%G' input conversions are interchangeable. They all match an optionally signed floating point number, in the same syntax as for the strtod function (see section Parsing of Floats).

For the floating-point input conversions, the default argument type is float *. (This is different from the corresponding output conversions, where the default type is double; remember that float arguments to printf are converted to double by the default argument promotions, but float * arguments are not promoted to double *.) You can specify other sizes of float using these type modifiers:

`l'
Specifies that the argument is of type double *.
`L'
Specifies that the argument is of type long double *.
For all the above number parsing formats there is an additional optional flag `''. When this flag is given the scanf function expects the number represented in the input string to be formatted according to the grouping rules of the currently selected locale (see section Generic Numeric Formatting Parameters).

If the "C" or "POSIX" locale is selected there is no difference. But for a locale which specifies values for the appropriate fields in the locale the input must have the correct form in the input. Otherwise the longest prefix with a correct form is processed.

String Input Conversions

This section describes the scanf input conversions for reading string and character values: `%s', `%S', `%[', `%c', and `%C'.

You have two options for how to receive the input from these conversions:

Provide a buffer to store it in. This is the default. You should provide an argument of type char * or wchar_t * (the latter of the `l' modifier is present). Warning: To make a robust program, you must make sure that the input (plus its terminating null) cannot possibly exceed the size of the buffer you provide. In general, the only way to do this is to specify a maximum field width one less than the buffer size. If you provide the buffer, always specify a maximum field width to prevent overflow.
Ask scanf to allocate a big enough buffer, by specifying the `a' flag character. This is a GNU extension. You should provide an argument of type char ** for the buffer address to be stored in. See section Dynamically Allocating String Conversions.

The `%c' conversion is the simplest: it matches a fixed number of characters, always. The maximum field width says how many characters to read; if you don't specify the maximum, the default is 1. This conversion doesn't append a null character to the end of the text it reads. It also does not skip over initial whitespace characters. It reads precisely the next n characters, and fails if it cannot get that many. Since there is always a maximum field width with `%c' (whether specified, or 1 by default), you can always prevent overflow by making the buffer long enough.

If the format is `%lc' or `%C' the function stores wide characters which are converted using the conversion determined at the time the stream was opened from the external byte stream. The number of bytes read from the medium is limited by MB_CUR_LEN * n but at most n wide character get stored in the output string.

The `%s' conversion matches a string of non-whitespace characters. It skips and discards initial whitespace, but stops when it encounters more whitespace after having read something. It stores a null character at the end of the text that it reads.

For example, reading the input:
 hello, world
with the conversion `%10c' produces " hello, wo", but reading the same input with the conversion `%10s' produces "hello,".

Warning: If you do not specify a field width for `%s', then the number of characters read is limited only by where the next whitespace character appears. This almost certainly means that invalid input can make your program crash--which is a bug.

The `%ls' and `%S' format are handled just like `%s' except that the external byte sequence is converted using the conversion associated with the stream to wide characters with their own encoding. A width or precision specified with the format do not directly determine how many bytes are read from the stream since they measure wide characters. But an upper limit can be computed by multiplying the value of the width or precision by MB_CUR_MAX.

To read in characters that belong to an arbitrary set of your choice, use the `%[' conversion. You specify the set between the `[' character and a following `]' character, using the same syntax used in regular expressions. As special cases:

A literal `]' character can be specified as the first character of the set.
An embedded `-' character (that is, one that is not the first or last character of the set) is used to specify a range of characters.
If a caret character `^' immediately follows the initial `[', then the set of allowed input characters is the everything except the characters listed.

The `%[' conversion does not skip over initial whitespace characters.

Here are some examples of `%[' conversions and what they mean:

`%25[1234567890]'
Matches a string of up to 25 digits.
`%25[][]'
Matches a string of up to 25 square brackets.
`%25[^ \f\n\r\t\v]'
Matches a string up to 25 characters long that doesn't contain any of the standard whitespace characters. This is slightly different from `%s', because if the input begins with a whitespace character, `%[' reports a matching failure while `%s' simply discards the initial whitespace.
`%25[a-z]'
Matches up to 25 lowercase characters.
As for `%c' and `%s' the `%[' format is also modified to produce wide characters if the `l' modifier is present. All what is said about `%ls' above is true for `%l['.

One more reminder: the `%s' and `%[' conversions are dangerous if you don't specify a maximum width or use the `a' flag, because input too long would overflow whatever buffer you have provided for it. No matter how long your buffer is, a user could supply input that is longer. A well-written program reports invalid input with a comprehensible error message, not with a crash.

Dynamically Allocating String Conversions

A GNU extension to formatted input lets you safely read a string with no maximum size. Using this feature, you don't supply a buffer; instead, scanf allocates a buffer big enough to hold the data and gives you its address. To use this feature, write `a' as a flag character, as in `%as' or `%a[0-9a-z]'.

The pointer argument you supply for where to store the input should have type char **. The scanf function allocates a buffer and stores its address in the word that the argument points to. You should free the buffer with free when you no longer need it.

Here is an example of using the `a' flag with the `%[...]' conversion specification to read a "variable assignment" of the form `variable = value'.
{
  char *variable, *value;

  if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
                 &variable, &value))
    {
      invalid_input_error ();
      return 0;
    }

  ...
}
Other Input Conversions

This section describes the miscellaneous input conversions.

The `%p' conversion is used to read a pointer value. It recognizes the same syntax used by the `%p' output conversion for printf (see section Other Output Conversions); that is, a hexadecimal number just as the `%x' conversion accepts. The corresponding argument should be of type void **; that is, the address of a place to store a pointer.

The resulting pointer value is not guaranteed to be valid if it was not originally written during the same program execution that reads it in.

The `%n' conversion produces the number of characters read so far by this call. The corresponding argument should be of type int *. This conversion works in the same way as the `%n' conversion for printf; see section Other Output Conversions, for an example.

The `%n' conversion is the only mechanism for determining the success of literal matches or conversions with suppressed assignments. If the `%n' follows the locus of a matching failure, then no value is stored for it since scanf returns before processing the `%n'. If you store -1 in that argument slot before calling scanf, the presence of -1 after scanf indicates an error occurred before the `%n' was reached.

Finally, the `%%' conversion matches a literal `%' character in the input stream, without using an argument. This conversion does not permit any flags, field width, or type modifier to be specified.

Formatted Input Functions

Here are the descriptions of the functions for performing formatted input. Prototypes for these functions are in the header file `stdio.h'.

Function: int scanf (const char *template, ...)
The scanf function reads formatted input from the stream stdin under the control of the template string template. The optional arguments are pointers to the places which receive the resulting values.

The return value is normally the number of successful assignments. If an end-of-file condition is detected before any matches are performed, including matches against whitespace and literal characters in the template, then EOF is returned.

Function: int wscanf (const wchar_t *template, ...)
The wscanf function reads formatted input from the stream stdin under the control of the template string template. The optional arguments are pointers to the places which receive the resulting values.

The return value is normally the number of successful assignments. If an end-of-file condition is detected before any matches are performed, including matches against whitespace and literal characters in the template, then WEOF is returned.

Function: int fscanf (FILE *stream, const char *template, ...)
This function is just like scanf, except that the input is read from the stream stream instead of stdin.

Function: int fwscanf (FILE *stream, const wchar_t *template, ...)
This function is just like wscanf, except that the input is read from the stream stream instead of stdin.

Function: int sscanf (const char *s, const char *template, ...)
This is like scanf, except that the characters are taken from the null-terminated string s instead of from a stream. Reaching the end of the string is treated as an end-of-file condition.

The behavior of this function is undefined if copying takes place between objects that overlap--for example, if s is also given as an argument to receive a string read under control of the `%s', `%S', or `%[' conversion.

Function: int swscanf (const wchar_t *ws, const char *template, ...)
This is like wscanf, except that the characters are taken from the null-terminated string ws instead of from a stream. Reaching the end of the string is treated as an end-of-file condition.

The behavior of this function is undefined if copying takes place between objects that overlap--for example, if ws is also given as an argument to receive a string read under control of the `%s', `%S', or `%[' conversion.

Variable Arguments Input Functions

The functions vscanf and friends are provided so that you can define your own variadic scanf-like functions that make use of the same internals as the built-in formatted output functions. These functions are analogous to the vprintf series of output functions. See section Variable Arguments Output Functions, for important information on how to use them.

Portability Note: The functions listed in this section were introduced in ISO C99 and were before available as GNU extensions.

Function: int vscanf (const char *template, va_list ap)
This function is similar to scanf, but instead of taking a variable number of arguments directly, it takes an argument list pointer ap of type va_list (see section Variadic Functions).

Function: int vwscanf (const wchar_t *template, va_list ap)
This function is similar to wscanf, but instead of taking a variable number of arguments directly, it takes an argument list pointer ap of type va_list (see section Variadic Functions).

Function: int vfscanf (FILE *stream, const char *template, va_list ap)
This is the equivalent of fscanf with the variable argument list specified directly as for vscanf.

Function: int vfwscanf (FILE *stream, const wchar_t *template, va_list ap)
This is the equivalent of fwscanf with the variable argument list specified directly as for vwscanf.

Function: int vsscanf (const char *s, const char *template, va_list ap)
This is the equivalent of sscanf with the variable argument list specified directly as for vscanf.

Function: int vswscanf (const wchar_t *s, const wchar_t *template, va_list ap)
This is the equivalent of swscanf with the variable argument list specified directly as for vwscanf.

In GNU C, there is a special construct you can use to let the compiler know that a function uses a scanf-style format string. Then it can check the number and types of arguments in each call to the function, and warn you when they do not match the format string. For details, See section `Declaring Attributes of Functions' in Using GNU CC.

End-Of-File and Errors

Many of the functions described in this chapter return the value of the macro EOF to indicate unsuccessful completion of the operation. Since EOF is used to report both end of file and random errors, it's often better to use the feof function to check explicitly for end of file and ferror to check for errors. These functions check indicators that are part of the internal state of the stream object, indicators set if the appropriate condition was detected by a previous I/O operation on that stream.

Macro: int EOF
This macro is an integer value that is returned by a number of narrow stream functions to indicate an end-of-file condition, or some other error situation. With the GNU library, EOF is -1. In other libraries, its value may be some other negative number.

This symbol is declared in `stdio.h'.

Macro: int WEOF
This macro is an integer value that is returned by a number of wide stream functions to indicate an end-of-file condition, or some other error situation. With the GNU library, WEOF is -1. In other libraries, its value may be some other negative number.

This symbol is declared in `wchar.h'.

Function: int feof (FILE *stream)
The feof function returns nonzero if and only if the end-of-file indicator for the stream stream is set.

This symbol is declared in `stdio.h'.

Function: int feof_unlocked (FILE *stream)
The feof_unlocked function is equivalent to the feof function except that it does not implicitly lock the stream.

This function is a GNU extension.

This symbol is declared in `stdio.h'.

Function: int ferror (FILE *stream)
The ferror function returns nonzero if and only if the error indicator for the stream stream is set, indicating that an error has occurred on a previous operation on the stream.

This symbol is declared in `stdio.h'.

Function: int ferror_unlocked (FILE *stream)
The ferror_unlocked function is equivalent to the ferror function except that it does not implicitly lock the stream.

This function is a GNU extension.

This symbol is declared in `stdio.h'.

In addition to setting the error indicator associated with the stream, the functions that operate on streams also set errno in the same way as the corresponding low-level functions that operate on file descriptors. For example, all of the functions that perform output to a stream--such as fputc, printf, and fflush---are implemented in terms of write, and all of the errno error conditions defined for write are meaningful for these functions. For more information about the descriptor-level I/O functions, see section Low-Level Input/Output.

Recovering from errors

You may explicitly clear the error and EOF flags with the clearerr function.

Function: void clearerr (FILE *stream)
This function clears the end-of-file and error indicators for the stream stream.

The file positioning functions (see section File Positioning) also clear the end-of-file indicator for the stream.

Function: void clearerr_unlocked (FILE *stream)
The clearerr_unlocked function is equivalent to the clearerr function except that it does not implicitly lock the stream.

This function is a GNU extension.

Note that it is not correct to just clear the error flag and retry a failed stream operation. After a failed write, any number of characters since the last buffer flush may have been committed to the file, while some buffered data may have been discarded. Merely retrying can thus cause lost or repeated data.

A failed read may leave the file pointer in an inappropriate position for a second try. In both cases, you should seek to a known position before retrying.

Most errors that can happen are not recoverable -- a second try will always fail again in the same way. So usually it is best to give up and report the error to the user, rather than install complicated recovery logic.

One important exception is EINTR (see section Primitives Interrupted by Signals). Many stream I/O implementations will treat it as an ordinary error, which can be quite inconvenient. You can avoid this hassle by installing all signals with the SA_RESTART flag.

For similar reasons, setting nonblocking I/O on a stream's file descriptor is not usually advisable.

Text and Binary Streams

The GNU system and other POSIX-compatible operating systems organize all files as uniform sequences of characters. However, some other systems make a distinction between files containing text and files containing binary data, and the input and output facilities of ISO C provide for this distinction. This section tells you how to write programs portable to such systems.

When you open a stream, you can specify either a text stream or a binary stream. You indicate that you want a binary stream by specifying the `b' modifier in the opentype argument to fopen; see section Opening Streams. Without this option, fopen opens the file as a text stream.

Text and binary streams differ in several ways:

The data read from a text stream is divided into lines which are terminated by newline ('\n') characters, while a binary stream is simply a long series of characters. A text stream might on some systems fail to handle lines more than 254 characters long (including the terminating newline character).
On some systems, text files can contain only printing characters, horizontal tab characters, and newlines, and so text streams may not support other characters. However, binary streams can handle any character value.
Space characters that are written immediately preceding a newline character in a text stream may disappear when the file is read in again.
More generally, there need not be a one-to-one mapping between characters that are read from or written to a text stream, and the characters in the actual file.

Since a binary stream is always more capable and more predictable than a text stream, you might wonder what purpose text streams serve. Why not simply always use binary streams? The answer is that on these operating systems, text and binary streams use different file formats, and the only way to read or write "an ordinary file of text" that can work with other text-oriented programs is through a text stream.

In the GNU library, and on all POSIX systems, there is no difference between text streams and binary streams. When you open a stream, you get the same kind of stream regardless of whether you ask for binary. This stream can handle any file content, and has none of the restrictions that text streams sometimes have.

File Positioning

The file position of a stream describes where in the file the stream is currently reading or writing. I/O on the stream advances the file position through the file. In the GNU system, the file position is represented as an integer, which counts the number of bytes from the beginning of the file. See section File Position.

During I/O to an ordinary disk file, you can change the file position whenever you wish, so as to read or write any portion of the file. Some other kinds of files may also permit this. Files which support changing the file position are sometimes referred to as random-access files.

You can use the functions in this section to examine or modify the file position indicator associated with a stream. The symbols listed below are declared in the header file `stdio.h'.

Function: long int ftell (FILE *stream)
This function returns the current file position of the stream stream.

This function can fail if the stream doesn't support file positioning, or if the file position can't be represented in a long int, and possibly for other reasons as well. If a failure occurs, a value of -1 is returned.

Function: off_t ftello (FILE *stream)
The ftello function is similar to ftell, except that it returns a value of type off_t. Systems which support this type use it to describe all file positions, unlike the POSIX specification which uses a long int. The two are not necessarily the same size. Therefore, using ftell can lead to problems if the implementation is written on top of a POSIX compliant low-level I/O implementation, and using ftello is preferable whenever it is available.

If this function fails it returns (off_t) -1. This can happen due to missing support for file positioning or internal errors. Otherwise the return value is the current file position.

The function is an extension defined in the Unix Single Specification version 2.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bit system this function is in fact ftello64. I.e., the LFS interface transparently replaces the old interface.

Function: off64_t ftello64 (FILE *stream)
This function is similar to ftello with the only difference that the return value is of type off64_t. This also requires that the stream stream was opened using either fopen64, freopen64, or tmpfile64 since otherwise the underlying file operations to position the file pointer beyond the @math{2^31} bytes limit might fail.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name ftello and so transparently replaces the old interface.

Function: int fseek (FILE *stream, long int offset, int whence)
The fseek function is used to change the file position of the stream stream. The value of whence must be one of the constants SEEK_SET, SEEK_CUR, or SEEK_END, to indicate whether the offset is relative to the beginning of the file, the current file position, or the end of the file, respectively.

This function returns a value of zero if the operation was successful, and a nonzero value to indicate failure. A successful call also clears the end-of-file indicator of stream and discards any characters that were "pushed back" by the use of ungetc.

fseek either flushes any buffered output before setting the file position or else remembers it so it will be written later in its proper place in the file.

Function: int fseeko (FILE *stream, off_t offset, int whence)
This function is similar to fseek but it corrects a problem with fseek in a system with POSIX types. Using a value of type long int for the offset is not compatible with POSIX. fseeko uses the correct type off_t for the offset parameter.

For this reason it is a good idea to prefer ftello whenever it is available since its functionality is (if different at all) closer the underlying definition.

The functionality and return value is the same as for fseek.

The function is an extension defined in the Unix Single Specification version 2.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bit system this function is in fact fseeko64. I.e., the LFS interface transparently replaces the old interface.

Function: int fseeko64 (FILE *stream, off64_t offset, int whence)
This function is similar to fseeko with the only difference that the offset parameter is of type off64_t. This also requires that the stream stream was opened using either fopen64, freopen64, or tmpfile64 since otherwise the underlying file operations to position the file pointer beyond the @math{2^31} bytes limit might fail.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name fseeko and so transparently replaces the old interface.

Portability Note: In non-POSIX systems, ftell, ftello, fseek and fseeko might work reliably only on binary streams. See section Text and Binary Streams.

The following symbolic constants are defined for use as the whence argument to fseek. They are also used with the lseek function (see section Input and Output Primitives) and to specify offsets for file locks (see section Control Operations on Files).

Macro: int SEEK_SET
This is an integer constant which, when used as the whence argument to the fseek or fseeko function, specifies that the offset provided is relative to the beginning of the file.

Macro: int SEEK_CUR
This is an integer constant which, when used as the whence argument to the fseek or fseeko function, specifies that the offset provided is relative to the current file position.

Macro: int SEEK_END
This is an integer constant which, when used as the whence argument to the fseek or fseeko function, specifies that the offset provided is relative to the end of the file.

Function: void rewind (FILE *stream)
The rewind function positions the stream stream at the beginning of the file. It is equivalent to calling fseek or fseeko on the stream with an offset argument of 0L and a whence argument of SEEK_SET, except that the return value is discarded and the error indicator for the stream is reset.

These three aliases for the `SEEK_...' constants exist for the sake of compatibility with older BSD systems. They are defined in two different header files: `fcntl.h' and `sys/file.h'.

L_SET
An alias for SEEK_SET.
L_INCR
An alias for SEEK_CUR.
L_XTND
An alias for SEEK_END.
Portable File-Position Functions

On the GNU system, the file position is truly a character count. You can specify any character count value as an argument to fseek or fseeko and get reliable results for any random access file. However, some ISO C systems do not represent file positions in this way.

On some systems where text streams truly differ from binary streams, it is impossible to represent the file position of a text stream as a count of characters from the beginning of the file. For example, the file position on some systems must encode both a record offset within the file, and a character offset within the record.

As a consequence, if you want your programs to be portable to these systems, you must observe certain rules:

The value returned from ftell on a text stream has no predictable relationship to the number of characters you have read so far. The only thing you can rely on is that you can use it subsequently as the offset argument to fseek or fseeko to move back to the same file position.
In a call to fseek or fseeko on a text stream, either the offset must be zero, or whence must be SEEK_SET and and the offset must be the result of an earlier call to ftell on the same stream.
The value of the file position indicator of a text stream is undefined while there are characters that have been pushed back with ungetc that haven't been read or discarded. See section Unreading.

But even if you observe these rules, you may still have trouble for long files, because ftell and fseek use a long int value to represent the file position. This type may not have room to encode all the file positions in a large file. Using the ftello and fseeko functions might help here since the off_t type is expected to be able to hold all file position values but this still does not help to handle additional information which must be associated with a file position.

So if you do want to support systems with peculiar encodings for the file positions, it is better to use the functions fgetpos and fsetpos instead. These functions represent the file position using the data type fpos_t, whose internal representation varies from system to system.

These symbols are declared in the header file `stdio.h'.

Data Type: fpos_t
This is the type of an object that can encode information about the file position of a stream, for use by the functions fgetpos and fsetpos.

In the GNU system, fpos_t is equivalent to off_t or long int. In other systems, it might have a different internal representation.

When compiling with _FILE_OFFSET_BITS == 64 on a 32 bit machine this type is in fact equivalent to off64_t since the LFS interface transparently replaced the old interface.

Data Type: fpos64_t
This is the type of an object that can encode information about the file position of a stream, for use by the functions fgetpos64 and fsetpos64.

In the GNU system, fpos64_t is equivalent to off64_t or long long int. In other systems, it might have a different internal representation.

Function: int fgetpos (FILE *stream, fpos_t *position)
This function stores the value of the file position indicator for the stream stream in the fpos_t object pointed to by position. If successful, fgetpos returns zero; otherwise it returns a nonzero value and stores an implementation-defined positive value in errno.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bit system the function is in fact fgetpos64. I.e., the LFS interface transparently replaced the old interface.

Function: int fgetpos64 (FILE *stream, fpos64_t *position)
This function is similar to fgetpos but the file position is returned in a variable of type fpos64_t to which position points.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name fgetpos and so transparently replaces the old interface.

Function: int fsetpos (FILE *stream, const fpos_t *position)
This function sets the file position indicator for the stream stream to the position position, which must have been set by a previous call to fgetpos on the same stream. If successful, fsetpos clears the end-of-file indicator on the stream, discards any characters that were "pushed back" by the use of ungetc, and returns a value of zero. Otherwise, fsetpos returns a nonzero value and stores an implementation-defined positive value in errno.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bit system the function is in fact fsetpos64. I.e., the LFS interface transparently replaced the old interface.

Function: int fsetpos64 (FILE *stream, const fpos64_t *position)
This function is similar to fsetpos but the file position used for positioning is provided in a variable of type fpos64_t to which position points.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name fsetpos and so transparently replaces the old interface.

Stream Buffering

Characters that are written to a stream are normally accumulated and transmitted asynchronously to the file in a block, instead of appearing as soon as they are output by the application program. Similarly, streams often retrieve input from the host environment in blocks rather than on a character-by-character basis. This is called buffering.

If you are writing programs that do interactive input and output using streams, you need to understand how buffering works when you design the user interface to your program. Otherwise, you might find that output (such as progress or prompt messages) doesn't appear when you intended it to, or displays some other unexpected behavior.

This section deals only with controlling when characters are transmitted between the stream and the file or device, and not with how things like echoing, flow control, and the like are handled on specific classes of devices. For information on common control operations on terminal devices, see section Low-Level Terminal Interface.

You can bypass the stream buffering facilities altogether by using the low-level input and output functions that operate on file descriptors instead. See section Low-Level Input/Output.

Buffering Concepts

There are three different kinds of buffering strategies:

Characters written to or read from an unbuffered stream are transmitted individually to or from the file as soon as possible.
Characters written to a line buffered stream are transmitted to the file in blocks when a newline character is encountered.
Characters written to or read from a fully buffered stream are transmitted to or from the file in blocks of arbitrary size.

Newly opened streams are normally fully buffered, with one exception: a stream connected to an interactive device such as a terminal is initially line buffered. See section Controlling Which Kind of Buffering, for information on how to select a different kind of buffering. Usually the automatic selection gives you the most convenient kind of buffering for the file or device you open.

The use of line buffering for interactive devices implies that output messages ending in a newline will appear immediately--which is usually what you want. Output that doesn't end in a newline might or might not show up immediately, so if you want them to appear immediately, you should flush buffered output explicitly with fflush, as described in section Flushing Buffers.

Flushing Buffers

Flushing output on a buffered stream means transmitting all accumulated characters to the file. There are many circumstances when buffered output on a stream is flushed automatically:

When you try to do output and the output buffer is full.
When the stream is closed. See section Closing Streams.
When the program terminates by calling exit. See section Normal Termination.
When a newline is written, if the stream is line buffered.
Whenever an input operation on any stream actually reads data from its file.

If you want to flush the buffered output at another time, call fflush, which is declared in the header file `stdio.h'.

Function: int fflush (FILE *stream)
This function causes any buffered output on stream to be delivered to the file. If stream is a null pointer, then fflush causes buffered output on all open output streams to be flushed.

This function returns EOF if a write error occurs, or zero otherwise.

Function: int fflush_unlocked (FILE *stream)
The fflush_unlocked function is equivalent to the fflush function except that it does not implicitly lock the stream.

The fflush function can be used to flush all streams currently opened. While this is useful in some situations it does often more than necessary since it might be done in situations when terminal input is required and the program wants to be sure that all output is visible on the terminal. But this means that only line buffered streams have to be flushed. Solaris introduced a function especially for this. It was always available in the GNU C library in some form but never officially exported.

Function: void _flushlbf (void)
The _flushlbf function flushes all line buffered streams currently opened.

This function is declared in the `stdio_ext.h' header.

Compatibility Note: Some brain-damaged operating systems have been known to be so thoroughly fixated on line-oriented input and output that flushing a line buffered stream causes a newline to be written! Fortunately, this "feature" seems to be becoming less common. You do not need to worry about this in the GNU system.

In some situations it might be useful to not flush the output pending for a stream but instead simply forget it. If transmission is costly and the output is not needed anymore this is valid reasoning. In this situation a non-standard function introduced in Solaris and available in the GNU C library can be used.

Function: void __fpurge (FILE *stream)
The __fpurge function causes the buffer of the stream stream to be emptied. If the stream is currently in read mode all input in the buffer is lost. If the stream is in output mode the buffered output is not written to the device (or whatever other underlying storage) and the buffer the cleared.

This function is declared in `stdio_ext.h'.

Controlling Which Kind of Buffering

After opening a stream (but before any other operations have been performed on it), you can explicitly specify what kind of buffering you want it to have using the setvbuf function.

The facilities listed in this section are declared in the header file `stdio.h'.

Function: int setvbuf (FILE *stream, char *buf, int mode, size_t size)
This function is used to specify that the stream stream should have the buffering mode mode, which can be either _IOFBF (for full buffering), _IOLBF (for line buffering), or _IONBF (for unbuffered input/output).

If you specify a null pointer as the buf argument, then setvbuf allocates a buffer itself using malloc. This buffer will be freed when you close the stream.

Otherwise, buf should be a character array that can hold at least size characters. You should not free the space for this array as long as the stream remains open and this array remains its buffer. You should usually either allocate it statically, or malloc (see section Unconstrained Allocation) the buffer. Using an automatic array is not a good idea unless you close the file before exiting the block that declares the array.

While the array remains a stream buffer, the stream I/O functions will use the buffer for their internal purposes. You shouldn't try to access the values in the array directly while the stream is using it for buffering.

The setvbuf function returns zero on success, or a nonzero value if the value of mode is not valid or if the request could not be honored.

Macro: int _IOFBF
The value of this macro is an integer constant expression that can be used as the mode argument to the setvbuf function to specify that the stream should be fully buffered.

Macro: int _IOLBF
The value of this macro is an integer constant expression that can be used as the mode argument to the setvbuf function to specify that the stream should be line buffered.

Macro: int _IONBF
The value of this macro is an integer constant expression that can be used as the mode argument to the setvbuf function to specify that the stream should be unbuffered.

Macro: int BUFSIZ
The value of this macro is an integer constant expression that is good to use for the size argument to setvbuf. This value is guaranteed to be at least 256.

The value of BUFSIZ is chosen on each system so as to make stream I/O efficient. So it is a good idea to use BUFSIZ as the size for the buffer when you call setvbuf.

Actually, you can get an even better value to use for the buffer size by means of the fstat system call: it is found in the st_blksize field of the file attributes. See section The meaning of the File Attributes.

Sometimes people also use BUFSIZ as the allocation size of buffers used for related purposes, such as strings used to receive a line of input with fgets (see section Character Input). There is no particular reason to use BUFSIZ for this instead of any other integer, except that it might lead to doing I/O in chunks of an efficient size.

Function: void setbuf (FILE *stream, char *buf)
If buf is a null pointer, the effect of this function is equivalent to calling setvbuf with a mode argument of _IONBF. Otherwise, it is equivalent to calling setvbuf with buf, and a mode of _IOFBF and a size argument of BUFSIZ.

The setbuf function is provided for compatibility with old code; use setvbuf in all new programs.

Function: void setbuffer (FILE *stream, char *buf, size_t size)
If buf is a null pointer, this function makes stream unbuffered. Otherwise, it makes stream fully buffered using buf as the buffer. The size argument specifies the length of buf.

This function is provided for compatibility with old BSD code. Use setvbuf instead.

Function: void setlinebuf (FILE *stream)
This function makes stream be line buffered, and allocates the buffer for you.

This function is provided for compatibility with old BSD code. Use setvbuf instead.

It is possible to query whether a given stream is line buffered or not using a non-standard function introduced in Solaris and available in the GNU C library.

Function: int __flbf (FILE *stream)
The __flbf function will return a nonzero value in case the stream stream is line buffered. Otherwise the return value is zero.

This function is declared in the `stdio_ext.h' header.

Two more extensions allow to determine the size of the buffer and how much of it is used. These functions were also introduced in Solaris.

Function: size_t __fbufsize (FILE *stream)
The __fbufsize function return the size of the buffer in the stream stream. This value can be used to optimize the use of the stream.

This function is declared in the `stdio_ext.h' header.

Function: size_t __fpending (FILE *stream) The __fpending
function returns the number of bytes currently in the output buffer. For wide-oriented stream the measuring unit is wide characters. This function should not be used on buffers in read mode or opened read-only.

This function is declared in the `stdio_ext.h' header.

Other Kinds of Streams

The GNU library provides ways for you to define additional kinds of streams that do not necessarily correspond to an open file.

One such type of stream takes input from or writes output to a string. These kinds of streams are used internally to implement the sprintf and sscanf functions. You can also create such a stream explicitly, using the functions described in section String Streams.

More generally, you can define streams that do input/output to arbitrary objects using functions supplied by your program. This protocol is discussed in section Programming Your Own Custom Streams.

Portability Note: The facilities described in this section are specific to GNU. Other systems or C implementations might or might not provide equivalent functionality.

String Streams

The fmemopen and open_memstream functions allow you to do I/O to a string or memory buffer. These facilities are declared in `stdio.h'.

Function: FILE * fmemopen (void *buf, size_t size, const char *opentype)
This function opens a stream that allows the access specified by the opentype argument, that reads from or writes to the buffer specified by the argument buf. This array must be at least size bytes long.

If you specify a null pointer as the buf argument, fmemopen dynamically allocates an array size bytes long (as with malloc; see section Unconstrained Allocation). This is really only useful if you are going to write things to the buffer and then read them back in again, because you have no way of actually getting a pointer to the buffer (for this, try open_memstream, below). The buffer is freed when the stream is open.

The argument opentype is the same as in fopen (see section Opening Streams). If the opentype specifies append mode, then the initial file position is set to the first null character in the buffer. Otherwise the initial file position is at the beginning of the buffer.

When a stream open for writing is flushed or closed, a null character (zero byte) is written at the end of the buffer if it fits. You should add an extra byte to the size argument to account for this. Attempts to write more than size bytes to the buffer result in an error.

For a stream open for reading, null characters (zero bytes) in the buffer do not count as "end of file". Read operations indicate end of file only when the file position advances past size bytes. So, if you want to read characters from a null-terminated string, you should supply the length of the string as the size argument.

Here is an example of using fmemopen to create a stream for reading from a string:
#include <stdio.h>

static char buffer[] = "foobar";

int
main (void)
{
  int ch;
  FILE *stream;

  stream = fmemopen (buffer, strlen (buffer), "r");
  while ((ch = fgetc (stream)) != EOF)
    printf ("Got %c\n", ch);
  fclose (stream);

  return 0;
}
This program produces the following output:
Got f
Got o
Got o
Got b
Got a
Got r
Function: FILE * open_memstream (char **ptr, size_t *sizeloc)
This function opens a stream for writing to a buffer. The buffer is allocated dynamically (as with malloc; see section Unconstrained Allocation) and grown as necessary.

When the stream is closed with fclose or flushed with fflush, the locations ptr and sizeloc are updated to contain the pointer to the buffer and its size. The values thus stored remain valid only as long as no further output on the stream takes place. If you do more output, you must flush the stream again to store new values before you use them again.

A null character is written at the end of the buffer. This null character is not included in the size value stored at sizeloc.

You can move the stream's file position with fseek or fseeko (see section File Positioning). Moving the file position past the end of the data already written fills the intervening space with zeroes.

Here is an example of using open_memstream:
#include <stdio.h>

int
main (void)
{
  char *bp;
  size_t size;
  FILE *stream;

  stream = open_memstream (&bp, &size);
  fprintf (stream, "hello");
  fflush (stream);
  printf ("buf = `%s', size = %d\n", bp, size);
  fprintf (stream, ", world");
  fclose (stream);
  printf ("buf = `%s', size = %d\n", bp, size);

  return 0;
}
This program produces the following output:
buf = `hello', size = 5
buf = `hello, world', size = 12
Obstack Streams

You can open an output stream that puts it data in an obstack. See section Obstacks.

Function: FILE * open_obstack_stream (struct obstack *obstack)
This function opens a stream for writing data into the obstack obstack. This starts an object in the obstack and makes it grow as data is written (see section Growing Objects).

Calling fflush on this stream updates the current size of the object to match the amount of data that has been written. After a call to fflush, you can examine the object temporarily.

You can move the file position of an obstack stream with fseek or fseeko (see section File Positioning). Moving the file position past the end of the data written fills the intervening space with zeros.

To make the object permanent, update the obstack with fflush, and then use obstack_finish to finalize the object and get its address. The following write to the stream starts a new object in the obstack, and later writes add to that object until you do another fflush and obstack_finish.

But how do you find out how long the object is? You can get the length in bytes by calling obstack_object_size (see section Status of an Obstack), or you can null-terminate the object like this:
obstack_1grow (obstack, 0);
Whichever one you do, you must do it before calling obstack_finish. (You can do both if you wish.)

Here is a sample function that uses open_obstack_stream:
char *
make_message_string (const char *a, int b)
{
  FILE *stream = open_obstack_stream (&message_obstack);
  output_task (stream);
  fprintf (stream, ": ");
  fprintf (stream, a, b);
  fprintf (stream, "\n");
  fclose (stream);
  obstack_1grow (&message_obstack, 0);
  return obstack_finish (&message_obstack);
}
Programming Your Own Custom Streams

This section describes how you can make a stream that gets input from an arbitrary data source or writes output to an arbitrary data sink programmed by you. We call these custom streams. The functions and types described here are all GNU extensions.

Custom Streams and Cookies

Inside every custom stream is a special object called the cookie. This is an object supplied by you which records where to fetch or store the data read or written. It is up to you to define a data type to use for the cookie. The stream functions in the library never refer directly to its contents, and they don't even know what the type is; they record its address with type void *.

To implement a custom stream, you must specify how to fetch or store the data in the specified place. You do this by defining hook functions to read, write, change "file position", and close the stream. All four of these functions will be passed the stream's cookie so they can tell where to fetch or store the data. The library functions don't know what's inside the cookie, but your functions will know.

When you create a custom stream, you must specify the cookie pointer, and also the four hook functions stored in a structure of type cookie_io_functions_t.

These facilities are declared in `stdio.h'.

Data Type: cookie_io_functions_t
This is a structure type that holds the functions that define the communications protocol between the stream and its cookie. It has the following members:

cookie_read_function_t *read
This is the function that reads data from the cookie. If the value is a null pointer instead of a function, then read operations on this stream always return EOF.
cookie_write_function_t *write
This is the function that writes data to the cookie. If the value is a null pointer instead of a function, then data written to the stream is discarded.
cookie_seek_function_t *seek
This is the function that performs the equivalent of file positioning on the cookie. If the value is a null pointer instead of a function, calls to fseek or fseeko on this stream can only seek to locations within the buffer; any attempt to seek outside the buffer will return an ESPIPE error.
cookie_close_function_t *close
This function performs any appropriate cleanup on the cookie when closing the stream. If the value is a null pointer instead of a function, nothing special is done to close the cookie when the stream is closed.

Function: FILE * fopencookie (void *cookie, const char *opentype, cookie_io_functions_t io-functions)
This function actually creates the stream for communicating with the cookie using the functions in the io-functions argument. The opentype argument is interpreted as for fopen; see section Opening Streams. (But note that the "truncate on open" option is ignored.) The new stream is fully buffered.

The fopencookie function returns the newly created stream, or a null pointer in case of an error.

Custom Stream Hook Functions

Here are more details on how you should define the four hook functions that a custom stream needs.

You should define the function to read data from the cookie as:
ssize_t reader (void *cookie, char *buffer, size_t size)
This is very similar to the read function; see section Input and Output Primitives. Your function should transfer up to size bytes into the buffer, and return the number of bytes read, or zero to indicate end-of-file. You can return a value of -1 to indicate an error.

You should define the function to write data to the cookie as:
ssize_t writer (void *cookie, const char *buffer, size_t size)
This is very similar to the write function; see section Input and Output Primitives. Your function should transfer up to size bytes from the buffer, and return the number of bytes written. You can return a value of -1 to indicate an error.

You should define the function to perform seek operations on the cookie as:
int seeker (void *cookie, fpos_t *position, int whence)
For this function, the position and whence arguments are interpreted as for fgetpos; see section Portable File-Position Functions. In the GNU library, fpos_t is equivalent to off_t or long int, and simply represents the number of bytes from the beginning of the file.

After doing the seek operation, your function should store the resulting file position relative to the beginning of the file in position. Your function should return a value of 0 on success and -1 to indicate an error.

You should define the function to do cleanup operations on the cookie appropriate for closing the stream as:
int cleaner (void *cookie)
Your function should return -1 to indicate an error, and 0 otherwise.

Data Type: cookie_read_function
This is the data type that the read function for a custom stream should have. If you declare the function as shown above, this is the type it will have.

Data Type: cookie_write_function
The data type of the write function for a custom stream.

Data Type: cookie_seek_function
The data type of the seek function for a custom stream.

Data Type: cookie_close_function
The data type of the close function for a custom stream.

Formatted Messages

On systems which are based on System V messages of programs (especially the system tools) are printed in a strict form using the fmtmsg function. The uniformity sometimes helps the user to interpret messages and the strictness tests of the fmtmsg function ensure that the programmer follows some minimal requirements.

Printing Formatted Messages

Messages can be printed to standard error and/or to the console. To select the destination the programmer can use the following two values, bitwise OR combined if wanted, for the classification parameter of fmtmsg:

MM_PRINT
Display the message in standard error.
MM_CONSOLE
Display the message on the system console.
The erroneous piece of the system can be signalled by exactly one of the following values which also is bitwise ORed with the classification parameter to fmtmsg:

MM_HARD
The source of the condition is some hardware.
MM_SOFT
The source of the condition is some software.
MM_FIRM
The source of the condition is some firmware.
A third component of the classification parameter to fmtmsg can describe the part of the system which detects the problem. This is done by using exactly one of the following values:

MM_APPL
The erroneous condition is detected by the application.
MM_UTIL
The erroneous condition is detected by a utility.
MM_OPSYS
The erroneous condition is detected by the operating system.
A last component of classification can signal the results of this message. Exactly one of the following values can be used:

MM_RECOVER
It is a recoverable error.
MM_NRECOV
It is a non-recoverable error.

Function: int fmtmsg (long int classification, const char *label, int severity, const char *text, const char *action, const char *tag)
Display a message described by its parameters on the device(s) specified in the classification parameter. The label parameter identifies the source of the message. The string should consist of two colon separated parts where the first part has not more than 10 and the second part not more than 14 characters. The text parameter describes the condition of the error, the action parameter possible steps to recover from the error and the tag parameter is a reference to the online documentation where more information can be found. It should contain the label value and a unique identification number.

Each of the parameters can be a special value which means this value is to be omitted. The symbolic names for these values are:

MM_NULLLBL
Ignore label parameter.
MM_NULLSEV
Ignore severity parameter.
MM_NULLMC
Ignore classification parameter. This implies that nothing is actually printed.
MM_NULLTXT
Ignore text parameter.
MM_NULLACT
Ignore action parameter.
MM_NULLTAG
Ignore tag parameter.
There is another way certain fields can be omitted from the output to standard error. This is described below in the description of environment variables influencing the behaviour.

The severity parameter can have one of the values in the following table:

MM_NOSEV
Nothing is printed, this value is the same as MM_NULLSEV.
MM_HALT
This value is printed as HALT.
MM_ERROR
This value is printed as ERROR.
MM_WARNING
This value is printed as WARNING.
MM_INFO
This value is printed as INFO.
The numeric value of these five macros are between 0 and 4. Using the environment variable SEV_LEVEL or using the addseverity function one can add more severity levels with their corresponding string to print. This is described below (see section Adding Severity Classes).

If no parameter is ignored the output looks like this:
label: severity-string: text
TO FIX: action tag
The colons, new line characters and the TO FIX string are inserted if necessary, i.e., if the corresponding parameter is not ignored.

This function is specified in the X/Open Portability Guide. It is also available on all systems derived from System V.

The function returns the value MM_OK if no error occurred. If only the printing to standard error failed, it returns MM_NOMSG. If printing to the console fails, it returns MM_NOCON. If nothing is printed MM_NOTOK is returned. Among situations where all outputs fail this last value is also returned if a parameter value is incorrect.

There are two environment variables which influence the behaviour of fmtmsg. The first is MSGVERB. It is used to control the output actually happening on standard error (not the console output). Each of the five fields can explicitly be enabled. To do this the user has to put the MSGVERB variable with a format like the following in the environment before calling the fmtmsg function the first time:
MSGVERB=keyword[:keyword[:...]]
Valid keywords are label, severity, text, action, and tag. If the environment variable is not given or is the empty string, a not supported keyword is given or the value is somehow else invalid, no part of the message is masked out.

The second environment variable which influences the behaviour of fmtmsg is SEV_LEVEL. This variable and the change in the behaviour of fmtmsg is not specified in the X/Open Portability Guide. It is available in System V systems, though. It can be used to introduce new severity levels. By default, only the five severity levels described above are available. Any other numeric value would make fmtmsg print nothing.

If the user puts SEV_LEVEL with a format like
SEV_LEVEL=[description[:description[:...]]]
in the environment of the process before the first call to fmtmsg, where description has a value of the form
severity-keyword,level,printstring
The severity-keyword part is not used by fmtmsg but it has to be present. The level part is a string representation of a number. The numeric value must be a number greater than 4. This value must be used in the severity parameter of fmtmsg to select this class. It is not possible to overwrite any of the predefined classes. The printstring is the string printed when a message of this class is processed by fmtmsg (see above, fmtsmg does not print the numeric value but instead the string representation).

Adding Severity Classes

There is another possibility to introduce severity classes besides using the environment variable SEV_LEVEL. This simplifies the task of introducing new classes in a running program. One could use the setenv or putenv function to set the environment variable, but this is toilsome.

Function: int addseverity (int severity, const char *string)
This function allows the introduction of new severity classes which can be addressed by the severity parameter of the fmtmsg function. The severity parameter of addseverity must match the value for the parameter with the same name of fmtmsg, and string is the string printed in the actual messages instead of the numeric value.

If string is NULL the severity class with the numeric value according to severity is removed.

It is not possible to overwrite or remove one of the default severity classes. All calls to addseverity with severity set to one of the values for the default classes will fail.

The return value is MM_OK if the task was successfully performed. If the return value is MM_NOTOK something went wrong. This could mean that no more memory is available or a class is not available when it has to be removed.

This function is not specified in the X/Open Portability Guide although the fmtsmg function is. It is available on System V systems.

How to use fmtmsg and addseverity

Here is a simple example program to illustrate the use of the both functions described in this section.
#include <fmtmsg.h>

int
main (void)
{
  addseverity (5, "NOTE2");
  fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2");
  fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual",
          "UX:cat:001");
  fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag");
  return 0;
}
The second call to fmtmsg illustrates a use of this function as it usually occurs on System V systems, which heavily use this function. It seems worthwhile to give a short explanation here of how this system works on System V. The value of the label field (UX:cat) says that the error occured in the Unix program cat. The explanation of the error follows and the value for the action parameter is "refer to manual". One could be more specific here, if necessary. The tag field contains, as proposed above, the value of the string given for the label parameter, and additionally a unique ID (001 in this case). For a GNU environment this string could contain a reference to the corresponding node in the Info page for the program.

Running this program without specifying the MSGVERB and SEV_LEVEL function produces the following output:
UX:cat: NOTE2: invalid syntax
TO FIX: refer to manual UX:cat:001
We see the different fields of the message and how the extra glue (the colons and the TO FIX string) are printed. But only one of the three calls to fmtmsg produced output. The first call does not print anything because the label parameter is not in the correct form. The string must contain two fields, separated by a colon (see section Printing Formatted Messages). The third fmtmsg call produced no output since the class with the numeric value 6 is not defined. Although a class with numeric value 5 is also not defined by default, the call to addseverity introduces it and the second call to fmtmsg produces the above output.

When we change the environment of the program to contain SEV_LEVEL=XXX,6,NOTE when running it we get a different result:
UX:cat: NOTE2: invalid syntax
TO FIX: refer to manual UX:cat:001
label:foo: NOTE: text
TO FIX: action tag
Now the third call to fmtmsg produced some output and we see how the string NOTE from the environment variable appears in the message.

Now we can reduce the output by specifying which fields we are interested in. If we additionally set the environment variable MSGVERB to the value severity:label:action we get the following output:
UX:cat: NOTE2
TO FIX: refer to manual
label:foo: NOTE
TO FIX: action
I.e., the output produced by the text and the tag parameters to fmtmsg vanished. Please also note that now there is no colon after the NOTE and NOTE2 strings in the output. This is not necessary since there is no more output on this line because the text is missing.
Low-Level Input/Output

This chapter describes functions for performing low-level input/output operations on file descriptors. These functions include the primitives for the higher-level I/O functions described in section Input/Output on Streams, as well as functions for performing low-level control operations for which there are no equivalents on streams.

Stream-level I/O is more flexible and usually more convenient; therefore, programmers generally use the descriptor-level functions only when necessary. These are some of the usual reasons:

For reading binary files in large chunks.
For reading an entire file into core before parsing it.
To perform operations other than data transfer, which can only be done with a descriptor. (You can use fileno to get the descriptor corresponding to a stream.)
To pass descriptors to a child process. (The child can create its own stream to use a descriptor that it inherits, but cannot inherit a stream directly.)

Opening and Closing Files

This section describes the primitives for opening and closing files using file descriptors. The open and creat functions are declared in the header file `fcntl.h', while close is declared in `unistd.h'.

Function: int open (const char *filename, int flags[, mode_t mode])
The open function creates and returns a new file descriptor for the file named by filename. Initially, the file position indicator for the file is at the beginning of the file. The argument mode is used only when a file is created, but it doesn't hurt to supply the argument in any case.

The flags argument controls how the file is to be opened. This is a bit mask; you create the value by the bitwise OR of the appropriate parameters (using the `|' operator in C). See section File Status Flags, for the parameters available.

The normal return value from open is a non-negative integer file descriptor. In the case of an error, a value of @math{-1} is returned instead. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES
The file exists but is not readable/writeable as requested by the flags argument, the file does not exist and the directory is unwriteable so it cannot be created.
EEXIST
Both O_CREAT and O_EXCL are set, and the named file already exists.
EINTR
The open operation was interrupted by a signal. See section Primitives Interrupted by Signals.
EISDIR
The flags argument specified write access, and the file is a directory.
EMFILE
The process has too many files open. The maximum number of file descriptors is controlled by the RLIMIT_NOFILE resource limit; see section Limiting Resource Usage.
ENFILE
The entire system, or perhaps the file system which contains the directory, cannot support any additional open files at the moment. (This problem cannot happen on the GNU system.)
ENOENT
The named file does not exist, and O_CREAT is not specified.
ENOSPC
The directory or file system that would contain the new file cannot be extended, because there is no disk space left.
ENXIO
O_NONBLOCK and O_WRONLY are both set in the flags argument, the file named by filename is a FIFO (see section Pipes and FIFOs), and no process has the file open for reading.
EROFS
The file resides on a read-only file system and any of O_WRONLY, O_RDWR, and O_TRUNC are set in the flags argument, or O_CREAT is set and the file does not already exist.
If on a 32 bit machine the sources are translated with _FILE_OFFSET_BITS == 64 the function open returns a file descriptor opened in the large file mode which enables the file handling functions to use files up to @math{2^63} bytes in size and offset from @math{-2^63} to @math{2^63}. This happens transparently for the user since all of the lowlevel file handling functions are equally replaced.

This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time open is called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this calls to open should be protected using cancellation handlers.

The open function is the underlying primitive for the fopen and freopen functions, that create streams.

Function: int open64 (const char *filename, int flags[, mode_t mode])
This function is similar to open. It returns a file descriptor which can be used to access the file named by filename. The only difference is that on 32 bit systems the file is opened in the large file mode. I.e., file length and file offsets can exceed 31 bits.

When the sources are translated with _FILE_OFFSET_BITS == 64 this function is actually available under the name open. I.e., the new, extended API using 64 bit file sizes and offsets transparently replaces the old API.

Obsolete function: int creat (const char *filename, mode_t mode)
This function is obsolete. The call:
creat (filename, mode)
is equivalent to:
open (filename, O_WRONLY | O_CREAT | O_TRUNC, mode)
If on a 32 bit machine the sources are translated with _FILE_OFFSET_BITS == 64 the function creat returns a file descriptor opened in the large file mode which enables the file handling functions to use files up to @math{2^63} in size and offset from @math{-2^63} to @math{2^63}. This happens transparently for the user since all of the lowlevel file handling functions are equally replaced.

Obsolete function: int creat64 (const char *filename, mode_t mode)
This function is similar to creat. It returns a file descriptor which can be used to access the file named by filename. The only the difference is that on 32 bit systems the file is opened in the large file mode. I.e., file length and file offsets can exceed 31 bits.

To use this file descriptor one must not use the normal operations but instead the counterparts named *64, e.g., read64.

When the sources are translated with _FILE_OFFSET_BITS == 64 this function is actually available under the name open. I.e., the new, extended API using 64 bit file sizes and offsets transparently replaces the old API.

Function: int close (int filedes)
The function close closes the file descriptor filedes. Closing a file has the following consequences:

The file descriptor is deallocated.
Any record locks owned by the process on the file are unlocked.
When all file descriptors associated with a pipe or FIFO have been closed, any unread data is discarded.

This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time close is called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this, calls to close should be protected using cancellation handlers.

The normal return value from close is @math{0}; a value of @math{-1} is returned in case of failure. The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
EINTR
The close call was interrupted by a signal. See section Primitives Interrupted by Signals. Here is an example of how to handle EINTR properly:
TEMP_FAILURE_RETRY (close (desc));
ENOSPC

EIO

EDQUOT
When the file is accessed by NFS, these errors from write can sometimes not be detected until close. See section Input and Output Primitives, for details on their meaning.
Please note that there is no separate close64 function. This is not necessary since this function does not determine nor depend on the mode of the file. The kernel which performs the close operation knows which mode the descriptor is used for and can handle this situation.

To close a stream, call fclose (see section Closing Streams) instead of trying to close its underlying file descriptor with close. This flushes any buffered output and updates the stream object to indicate that it is closed.

Input and Output Primitives

This section describes the functions for performing primitive input and output operations on file descriptors: read, write, and lseek. These functions are declared in the header file `unistd.h'.

Data Type: ssize_t
This data type is used to represent the sizes of blocks that can be read or written in a single operation. It is similar to size_t, but must be a signed type.

Function: ssize_t read (int filedes, void *buffer, size_t size)
The read function reads up to size bytes from the file with descriptor filedes, storing the results in the buffer. (This is not necessarily a character string, and no terminating null character is added.)

The return value is the number of bytes actually read. This might be less than size; for example, if there aren't that many bytes left in the file or if there aren't that many bytes immediately available. The exact behavior depends on what kind of file it is. Note that reading less than size bytes is not an error.

A value of zero indicates end-of-file (except if the value of the size argument is also zero). This is not considered an error. If you keep calling read while at end-of-file, it will keep returning zero and doing nothing else.

If read returns at least one character, there is no way you can tell whether end-of-file was reached. But if you did reach the end, the next read will return zero.

In case of an error, read returns @math{-1}. The following errno error conditions are defined for this function:

EAGAIN
Normally, when no input is immediately available, read waits for some input. But if the O_NONBLOCK flag is set for the file (see section File Status Flags), read returns immediately without reading any data, and reports this error. Compatibility Note: Most versions of BSD Unix use a different error code for this: EWOULDBLOCK. In the GNU library, EWOULDBLOCK is an alias for EAGAIN, so it doesn't matter which name you use. On some systems, reading a large amount of data from a character special file can also fail with EAGAIN if the kernel cannot find enough physical memory to lock down the user's pages. This is limited to devices that transfer with direct memory access into the user's memory, which means it does not include terminals, since they always use separate buffers inside the kernel. This problem never happens in the GNU system. Any condition that could result in EAGAIN can instead result in a successful read which returns fewer bytes than requested. Calling read again immediately would result in EAGAIN.
EBADF
The filedes argument is not a valid file descriptor, or is not open for reading.
EINTR
read was interrupted by a signal while it was waiting for input. See section Primitives Interrupted by Signals. A signal will not necessary cause read to return EINTR; it may instead result in a successful read which returns fewer bytes than requested.
EIO
For many devices, and for disk files, this error code indicates a hardware error. EIO also occurs when a background process tries to read from the controlling terminal, and the normal action of stopping the process by sending it a SIGTTIN signal isn't working. This might happen if the signal is being blocked or ignored, or because the process group is orphaned. See section Job Control, for more information about job control, and section Signal Handling, for information about signals.
Please note that there is no function named read64. This is not necessary since this function does not directly modify or handle the possibly wide file offset. Since the kernel handles this state internally, the read function can be used for all cases.

This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time read is called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this, calls to read should be protected using cancellation handlers.

The read function is the underlying primitive for all of the functions that read from streams, such as fgetc.

Function: ssize_t pread (int filedes, void *buffer, size_t size, off_t offset)
The pread function is similar to the read function. The first three arguments are identical, and the return values and error codes also correspond.

The difference is the fourth argument and its handling. The data block is not read from the current position of the file descriptor filedes. Instead the data is read from the file starting at position offset. The position of the file descriptor itself is not affected by the operation. The value is the same as before the call.

When the source file is compiled with _FILE_OFFSET_BITS == 64 the pread function is in fact pread64 and the type off_t has 64 bits, which makes it possible to handle files up to @math{2^63} bytes in length.

The return value of pread describes the number of bytes read. In the error case it returns @math{-1} like read does and the error codes are also the same, with these additions:

EINVAL
The value given for offset is negative and therefore illegal.
ESPIPE
The file descriptor filedes is associate with a pipe or a FIFO and this device does not allow positioning of the file pointer.
The function is an extension defined in the Unix Single Specification version 2.

Function: ssize_t pread64 (int filedes, void *buffer, size_t size, off64_t offset)
This function is similar to the pread function. The difference is that the offset parameter is of type off64_t instead of off_t which makes it possible on 32 bit machines to address files larger than @math{2^31} bytes and up to @math{2^63} bytes. The file descriptor filedes must be opened using open64 since otherwise the large offsets possible with off64_t will lead to errors with a descriptor in small file mode.

When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bit machine this function is actually available under the name pread and so transparently replaces the 32 bit interface.

Function: ssize_t write (int filedes, const void *buffer, size_t size)
The write function writes up to size bytes from buffer to the file with descriptor filedes. The data in buffer is not necessarily a character string and a null character is output like any other character.

The return value is the number of bytes actually written. This may be size, but can always be smaller. Your program should always call write in a loop, iterating until all the data is written.

Once write returns, the data is enqueued to be written and can be read back right away, but it is not necessarily written out to permanent storage immediately. You can use fsync when you need to be sure your data has been permanently stored before continuing. (It is more efficient for the system to batch up consecutive writes and do them all at once when convenient. Normally they will always be written to disk within a minute or less.) Modern systems provide another function fdatasync which guarantees integrity only for the file data and is therefore faster. You can use the O_FSYNC open mode to make write always store the data to disk before returning; see section I/O Operating Modes.

In the case of an error, write returns @math{-1}. The following errno error conditions are defined for this function:

EAGAIN
Normally, write blocks until the write operation is complete. But if the O_NONBLOCK flag is set for the file (see section Control Operations on Files), it returns immediately without writing any data and reports this error. An example of a situation that might cause the process to block on output is writing to a terminal device that supports flow control, where output has been suspended by receipt of a STOP character. Compatibility Note: Most versions of BSD Unix use a different error code for this: EWOULDBLOCK. In the GNU library, EWOULDBLOCK is an alias for EAGAIN, so it doesn't matter which name you use. On some systems, writing a large amount of data from a character special file can also fail with EAGAIN if the kernel cannot find enough physical memory to lock down the user's pages. This is limited to devices that transfer with direct memory access into the user's memory, which means it does not include terminals, since they always use separate buffers inside the kernel. This problem does not arise in the GNU system.
EBADF
The filedes argument is not a valid file descriptor, or is not open for writing.
EFBIG
The size of the file would become larger than the implementation can support.
EINTR
The write operation was interrupted by a signal while it was blocked waiting for completion. A signal will not necessarily cause write to return EINTR; it may instead result in a successful write which writes fewer bytes than requested. See section Primitives Interrupted by Signals.
EIO
For many devices, and for disk files, this error code indicates a hardware error.
ENOSPC
The device containing the file is full.
EPIPE
This error is returned when you try to write to a pipe or FIFO that isn't open for reading by any process. When this happens, a SIGPIPE signal is also sent to the process; see section Signal Handling.
Unless you have arranged to prevent EINTR failures, you should check errno after each failing call to write, and if the error was EINTR, you should simply repeat the call. See section Primitives Interrupted by Signals. The easy way to do this is with the macro TEMP_FAILURE_RETRY, as follows:
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
Please note that there is no function named write64. This is not necessary since this function does not directly modify or handle the possibly wide file offset. Since the kernel handles this state internally the write function can be used for all cases.

This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time write is called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this, calls to write should be protected using cancellation handlers.

The write function is the underlying primitive for all of the functions that write to streams, such as fputc.

Function: ssize_t pwrite (int filedes, const void *buffer, size_t size, off_t offset)
The pwrite function is similar to the write function. The first three arguments are identical, and the return values and error codes also correspond.

The difference is the fourth argument and its handling. The data block is not written to the current position of the file descriptor filedes. Instead the data is written to the file starting at position offset. The position of the file descriptor itself is not affected by the operation. The value is the same as before the call.

When the source file is compiled with _FILE_OFFSET_BITS == 64 the pwrite function is in fact pwrite64 and the type off_t has 64 bits, which makes it possible to handle files up to @math{2^63} bytes in length.

The return value of pwrite describes the number of written bytes. In the error case it returns @math{-1} like write does and the error codes are also the same, with these additions:

EINVAL
The value given for offset is negative and therefore illegal.
ESPIPE
The file descriptor filedes is associated with a pipe or a FIFO and this device does not allow positioning of the file pointer.
The function is an extension defined in the Unix Single Specification version 2.

Function: ssize_t pwrite64 (int filedes, const void *buffer, size_t size, off64_t offset)
This function is similar to the pwrite function. The difference is that the offset parameter is of type off64_t instead of off_t which makes it possible on 32 bit machines to address files larger than @math{2^31} bytes and up to @math{2^63} bytes. The file descriptor filedes must be opened using open64 since otherwise the large offsets possible with off64_t will lead to errors with a descriptor in small file mode.

When the source file is compiled using _FILE_OFFSET_BITS == 64 on a 32 bit machine this function is actually available under the name pwrite and so transparently replaces the 32 bit interface.

Setting the File Position of a Descriptor

Just as you can set the file position of a stream with fseek, you can set the file position of a descriptor with lseek. This specifies the position in the file for the next read or write operation. See section File Positioning, for more information on the file position and what it means.

To read the current file position value from a descriptor, use lseek (desc, 0, SEEK_CUR).

Function: off_t lseek (int filedes, off_t offset, int whence)
The lseek function is used to change the file position of the file with descriptor filedes.

The whence argument specifies how the offset should be interpreted, in the same way as for the fseek function, and it must be one of the symbolic constants SEEK_SET, SEEK_CUR, or SEEK_END.

SEEK_SET
Specifies that whence is a count of characters from the beginning of the file.
SEEK_CUR
Specifies that whence is a count of characters from the current file position. This count may be positive or negative.
SEEK_END
Specifies that whence is a count of characters from the end of the file. A negative count specifies a position within the current extent of the file; a positive count specifies a position past the current end. If you set the position past the current end, and actually write data, you will extend the file with zeros up to that position.
The return value from lseek is normally the resulting file position, measured in bytes from the beginning of the file. You can use this feature together with SEEK_CUR to read the current file position.

If you want to append to the file, setting the file position to the current end of file with SEEK_END is not sufficient. Another process may write more data after you seek but before you write, extending the file so the position you write onto clobbers their data. Instead, use the O_APPEND operating mode; see section I/O Operating Modes.

You can set the file position past the current end of the file. This does not by itself make the file longer; lseek never changes the file. But subsequent output at that position will extend the file. Characters between the previous end of file and the new position are filled with zeros. Extending the file in this way can create a "hole": the blocks of zeros are not actually allocated on disk, so the file takes up less space than it appears to; it is then called a "sparse file".

If the file position cannot be changed, or the operation is in some way invalid, lseek returns a value of @math{-1}. The following errno error conditions are defined for this function:

EBADF
The filedes is not a valid file descriptor.
EINVAL
The whence argument value is not valid, or the resulting file offset is not valid. A file offset is invalid.
ESPIPE
The filedes corresponds to an object that cannot be positioned, such as a pipe, FIFO or terminal device. (POSIX.1 specifies this error only for pipes and FIFOs, but in the GNU system, you always get ESPIPE if the object is not seekable.)
When the source file is compiled with _FILE_OFFSET_BITS == 64 the lseek function is in fact lseek64 and the type off_t has 64 bits which makes it possible to handle files up to @math{2^63} bytes in length.

This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time lseek is called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this calls to lseek should be protected using cancellation handlers.

The lseek function is the underlying primitive for the fseek, fseeko, ftell, ftello and rewind functions, which operate on streams instead of file descriptors.

Function: off64_t lseek64 (int filedes, off64_t offset, int whence)
This function is similar to the lseek function. The difference is that the offset parameter is of type off64_t instead of off_t which makes it possible on 32 bit machines to address files larger than @math{2^31} bytes and up to @math{2^63} bytes. The file descriptor filedes must be opened using open64 since otherwise the large offsets possible with off64_t will lead to errors with a descriptor in small file mode.

When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name lseek and so transparently replaces the 32 bit interface.

You can have multiple descriptors for the same file if you open the file more than once, or if you duplicate a descriptor with dup. Descriptors that come from separate calls to open have independent file positions; using lseek on one descriptor has no effect on the other. For example,
{
  int d1, d2;
  char buf[4];
  d1 = open ("foo", O_RDONLY);
  d2 = open ("foo", O_RDONLY);
  lseek (d1, 1024, SEEK_SET);
  read (d2, buf, 4);
}
will read the first four characters of the file `foo'. (The error-checking code necessary for a real program has been omitted here for brevity.)

By contrast, descriptors made by duplication share a common file position with the original descriptor that was duplicated. Anything which alters the file position of one of the duplicates, including reading or writing data, affects all of them alike. Thus, for example,
{
  int d1, d2, d3;
  char buf1[4], buf2[4];
  d1 = open ("foo", O_RDONLY);
  d2 = dup (d1);
  d3 = dup (d2);
  lseek (d3, 1024, SEEK_SET);
  read (d1, buf1, 4);
  read (d2, buf2, 4);
}
will read four characters starting with the 1024'th character of `foo', and then four more characters starting with the 1028'th character.

Data Type: off_t
This is an arithmetic data type used to represent file sizes. In the GNU system, this is equivalent to fpos_t or long int.

If the source is compiled with _FILE_OFFSET_BITS == 64 this type is transparently replaced by off64_t.

Data Type: off64_t
This type is used similar to off_t. The difference is that even on 32 bit machines, where the off_t type would have 32 bits, off64_t has 64 bits and so is able to address files up to @math{2^63} bytes in length.

When compiling with _FILE_OFFSET_BITS == 64 this type is available under the name off_t.

These aliases for the `SEEK_...' constants exist for the sake of compatibility with older BSD systems. They are defined in two different header files: `fcntl.h' and `sys/file.h'.

L_SET
An alias for SEEK_SET.
L_INCR
An alias for SEEK_CUR.
L_XTND
An alias for SEEK_END.
Descriptors and Streams

Given an open file descriptor, you can create a stream for it with the fdopen function. You can get the underlying file descriptor for an existing stream with the fileno function. These functions are declared in the header file `stdio.h'.

Function: FILE * fdopen (int filedes, const char *opentype)
The fdopen function returns a new stream for the file descriptor filedes.

The opentype argument is interpreted in the same way as for the fopen function (see section Opening Streams), except that the `b' option is not permitted; this is because GNU makes no distinction between text and binary files. Also, "w" and "w+" do not cause truncation of the file; these have an effect only when opening a file, and in this case the file has already been opened. You must make sure that the opentype argument matches the actual mode of the open file descriptor.

The return value is the new stream. If the stream cannot be created (for example, if the modes for the file indicated by the file descriptor do not permit the access specified by the opentype argument), a null pointer is returned instead.

In some other systems, fdopen may fail to detect that the modes for file descriptor do not permit the access specified by opentype. The GNU C library always checks for this.

For an example showing the use of the fdopen function, see section Creating a Pipe.

Function: int fileno (FILE *stream)
This function returns the file descriptor associated with the stream stream. If an error is detected (for example, if the stream is not valid) or if stream does not do I/O to a file, fileno returns @math{-1}.

Function: int fileno_unlocked (FILE *stream)
The fileno_unlocked function is equivalent to the fileno function except that it does not implicitly lock the stream if the state is FSETLOCKING_INTERNAL.

This function is a GNU extension.

There are also symbolic constants defined in `unistd.h' for the file descriptors belonging to the standard streams stdin, stdout, and stderr; see section Standard Streams.

STDIN_FILENO
This macro has value 0, which is the file descriptor for standard input.
STDOUT_FILENO
This macro has value 1, which is the file descriptor for standard output.
STDERR_FILENO
This macro has value 2, which is the file descriptor for standard error output.

Dangers of Mixing Streams and Descriptors

You can have multiple file descriptors and streams (let's call both streams and descriptors "channels" for short) connected to the same file, but you must take care to avoid confusion between channels. There are two cases to consider: linked channels that share a single file position value, and independent channels that have their own file positions.

It's best to use just one channel in your program for actual data transfer to any given file, except when all the access is for input. For example, if you open a pipe (something you can only do at the file descriptor level), either do all I/O with the descriptor, or construct a stream from the descriptor with fdopen and then do all I/O with the stream.

Linked Channels

Channels that come from a single opening share the same file position; we call them linked channels. Linked channels result when you make a stream from a descriptor using fdopen, when you get a descriptor from a stream with fileno, when you copy a descriptor with dup or dup2, and when descriptors are inherited during fork. For files that don't support random access, such as terminals and pipes, all channels are effectively linked. On random-access files, all append-type output streams are effectively linked to each other.

If you have been using a stream for I/O, and you want to do I/O using another channel (either a stream or a descriptor) that is linked to it, you must first clean up the stream that you have been using. See section Cleaning Streams.

Terminating a process, or executing a new program in the process, destroys all the streams in the process. If descriptors linked to these streams persist in other processes, their file positions become undefined as a result. To prevent this, you must clean up the streams before destroying them.

Independent Channels

When you open channels (streams or descriptors) separately on a seekable file, each channel has its own file position. These are called independent channels.

The system handles each channel independently. Most of the time, this is quite predictable and natural (especially for input): each channel can read or write sequentially at its own place in the file. However, if some of the channels are streams, you must take these precautions:

You should clean an output stream after use, before doing anything else that might read or write from the same part of the file.
You should clean an input stream before reading data that may have been modified using an independent channel. Otherwise, you might read obsolete data that had been in the stream's buffer.

If you do output to one channel at the end of the file, this will certainly leave the other independent channels positioned somewhere before the new end. You cannot reliably set their file positions to the new end of file before writing, because the file can always be extended by another process between when you set the file position and when you write the data. Instead, use an append-type descriptor or stream; they always output at the current end of the file. In order to make the end-of-file position accurate, you must clean the output channel you were using, if it is a stream.

It's impossible for two channels to have separate file pointers for a file that doesn't support random access. Thus, channels for reading or writing such files are always linked, never independent. Append-type channels are also always linked. For these channels, follow the rules for linked channels; see section Linked Channels.

Cleaning Streams

On the GNU system, you can clean up any stream with fclean:

Function: int fclean (FILE *stream)
Clean up the stream stream so that its buffer is empty. If stream is doing output, force it out. If stream is doing input, give the data in the buffer back to the system, arranging to reread it.

On other systems, you can use fflush to clean a stream in most cases.

You can skip the fclean or fflush if you know the stream is already clean. A stream is clean whenever its buffer is empty. For example, an unbuffered stream is always clean. An input stream that is at end-of-file is clean. A line-buffered stream is clean when the last character output was a newline.

There is one case in which cleaning a stream is impossible on most systems. This is when the stream is doing input from a file that is not random-access. Such streams typically read ahead, and when the file is not random access, there is no way to give back the excess data already read. When an input stream reads from a random-access file, fflush does clean the stream, but leaves the file pointer at an unpredictable place; you must set the file pointer before doing any further I/O. On the GNU system, using fclean avoids both of these problems.

Closing an output-only stream also does fflush, so this is a valid way of cleaning an output stream. On the GNU system, closing an input stream does fclean.

You need not clean a stream before using its descriptor for control operations such as setting terminal modes; these operations don't affect the file position and are not affected by it. You can use any descriptor for these operations, and all channels are affected simultaneously. However, text already "output" to a stream but still buffered by the stream will be subject to the new terminal modes when subsequently flushed. To make sure "past" output is covered by the terminal settings that were in effect at the time, flush the output streams for that terminal before setting the modes. See section Terminal Modes.

Fast Scatter-Gather I/O

Some applications may need to read or write data to multiple buffers, which are separated in memory. Although this can be done easily enough with multiple calls to read and write, it is inefficent because there is overhead associated with each kernel call.

Instead, many platforms provide special high-speed primitives to perform these scatter-gather operations in a single kernel call. The GNU C library will provide an emulation on any system that lacks these primitives, so they are not a portability threat. They are defined in sys/uio.h.

These functions are controlled with arrays of iovec structures, which describe the location and size of each buffer.

Data Type: struct iovec

The iovec structure describes a buffer. It contains two fields:

void *iov_base
Contains the address of a buffer.
size_t iov_len
Contains the length of the buffer.

Function: ssize_t readv (int filedes, const struct iovec *vector, int count)

The readv function reads data from filedes and scatters it into the buffers described in vector, which is taken to be count structures long. As each buffer is filled, data is sent to the next.

Note that readv is not guaranteed to fill all the buffers. It may stop at any point, for the same reasons read would.

The return value is a count of bytes (not buffers) read, @math{0} indicating end-of-file, or @math{-1} indicating an error. The possible errors are the same as in read.

Function: ssize_t writev (int filedes, const struct iovec *vector, int count)

The writev function gathers data from the buffers described in vector, which is taken to be count structures long, and writes them to filedes. As each buffer is written, it moves on to the next.

Like readv, writev may stop midstream under the same conditions write would.

The return value is a count of bytes written, or @math{-1} indicating an error. The possible errors are the same as in write.

Note that if the buffers are small (under about 1kB), high-level streams may be easier to use than these functions. However, readv and writev are more efficient when the individual buffers themselves (as opposed to the total output), are large. In that case, a high-level stream would not be able to cache the data effectively.

Memory-mapped I/O

On modern operating systems, it is possible to mmap (pronounced "em-map") a file to a region of memory. When this is done, the file can be accessed just like an array in the program.

This is more efficent than read or write, as only the regions of the file that a program actually accesses are loaded. Accesses to not-yet-loaded parts of the mmapped region are handled in the same way as swapped out pages.

Since mmapped pages can be stored back to their file when physical memory is low, it is possible to mmap files orders of magnitude larger than both the physical memory and swap space. The only limit is address space. The theoretical limit is 4GB on a 32-bit machine - however, the actual limit will be smaller since some areas will be reserved for other purposes. If the LFS interface is used the file size on 32-bit systems is not limited to 2GB (offsets are signed which reduces the addressable area of 4GB by half); the full 64-bit are available.

Memory mapping only works on entire pages of memory. Thus, addresses for mapping must be page-aligned, and length values will be rounded up. To determine the size of a page the machine uses one should use
size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
These functions are declared in `sys/mman.h'.

Function: void * mmap (void *address, size_t length,int protect, int flags, int filedes, off_t offset)

The mmap function creates a new mapping, connected to bytes (offset) to (offset + length) in the file open on filedes.

address gives a preferred starting address for the mapping. NULL expresses no preference. Any previous mapping at that address is automatically removed. The address you give may still be changed, unless you use the MAP_FIXED flag.

protect contains flags that control what kind of access is permitted. They include PROT_READ, PROT_WRITE, and PROT_EXEC, which permit reading, writing, and execution, respectively. Inappropriate access will cause a segfault (see section Program Error Signals).

Note that most hardware designs cannot support write permission without read permission, and many do not distinguish read and execute permission. Thus, you may receive wider permissions than you ask for, and mappings of write-only files may be denied even if you do not use PROT_READ.

flags contains flags that control the nature of the map. One of MAP_SHARED or MAP_PRIVATE must be specified.

They include:

MAP_PRIVATE
This specifies that writes to the region should never be written back to the attached file. Instead, a copy is made for the process, and the region will be swapped normally if memory runs low. No other process will see the changes. Since private mappings effectively revert to ordinary memory when written to, you must have enough virtual memory for a copy of the entire mmapped region if you use this mode with PROT_WRITE.
MAP_SHARED
This specifies that writes to the region will be written back to the file. Changes made will be shared immediately with other processes mmaping the same file. Note that actual writing may take place at any time. You need to use msync, described below, if it is important that other processes using conventional I/O get a consistent view of the file.
MAP_FIXED
This forces the system to use the exact mapping address specified in address and fail if it can't.
MAP_ANONYMOUS

MAP_ANON
This flag tells the system to create an anonymous mapping, not connected to a file. filedes and off are ignored, and the region is initialized with zeros. Anonymous maps are used as the basic primitive to extend the heap on some systems. They are also useful to share data between multiple tasks without creating a file. On some systems using private anonymous mmaps is more efficient than using malloc for large blocks. This is not an issue with the GNU C library, as the included malloc automatically uses mmap where appropriate.
mmap returns the address of the new mapping, or @math{-1} for an error.

Possible errors include:

EINVAL
Either address was unusable, or inconsistent flags were given.
EACCES
filedes was not open for the type of access specified in protect.
ENOMEM
Either there is not enough memory for the operation, or the process is out of address space.
ENODEV
This file is of a type that doesn't support mapping.
ENOEXEC
The file is on a filesystem that doesn't support mapping.

Function: void * mmap64 (void *address, size_t length,int protect, int flags, int filedes, off64_t offset)
The mmap64 function is equivalent to the mmap function but the offset parameter is of type off64_t. On 32-bit systems this allows the file associated with the filedes descriptor to be larger than 2GB. filedes must be a descriptor returned from a call to open64 or fopen64 and freopen64 where the descriptor is retrieved with fileno.

When the sources are translated with _FILE_OFFSET_BITS == 64 this function is actually available under the name mmap. I.e., the new, extended API using 64 bit file sizes and offsets transparently replaces the old API.

Function: int munmap (void *addr, size_t length)

munmap removes any memory maps from (addr) to (addr + length). length should be the length of the mapping.

It is safe to unmap multiple mappings in one command, or include unmapped space in the range. It is also possible to unmap only part of an existing mapping. However, only entire pages can be removed. If length is not an even number of pages, it will be rounded up.

It returns @math{0} for success and @math{-1} for an error.

One error is possible:

EINVAL
The memory range given was outside the user mmap range or wasn't page aligned.

Function: int msync (void *address, size_t length, int flags)

When using shared mappings, the kernel can write the file at any time before the mapping is removed. To be certain data has actually been written to the file and will be accessible to non-memory-mapped I/O, it is necessary to use this function.

It operates on the region address to (address + length). It may be used on part of a mapping or multiple mappings, however the region given should not contain any unmapped space.

flags can contain some options:

MS_SYNC
This flag makes sure the data is actually written to disk. Normally msync only makes sure that accesses to a file with conventional I/O reflect the recent changes.
MS_ASYNC
This tells msync to begin the synchronization, but not to wait for it to complete.
msync returns @math{0} for success and @math{-1} for error. Errors include:

EINVAL
An invalid region was given, or the flags were invalid.
EFAULT
There is no existing mapping in at least part of the given region.

Function: void * mremap (void *address, size_t length, size_t new_length, int flag)

This function can be used to change the size of an existing memory area. address and length must cover a region entirely mapped in the same mmap statement. A new mapping with the same characteristics will be returned with the length new_length.

One option is possible, MREMAP_MAYMOVE. If it is given in flags, the system may remove the existing mapping and create a new one of the desired length in another location.

The address of the resulting mapping is returned, or @math{-1}. Possible error codes include:

EFAULT
There is no existing mapping in at least part of the original region, or the region covers two or more distinct mappings.
EINVAL
The address given is misaligned or inappropriate.
EAGAIN
The region has pages locked, and if extended it would exceed the process's resource limit for locked pages. See section Limiting Resource Usage.
ENOMEM
The region is private writeable, and insufficent virtual memory is available to extend it. Also, this error will occur if MREMAP_MAYMOVE is not given and the extension would collide with another mapped region.
This function is only available on a few systems. Except for performing optional optimizations one should not rely on this function.

Not all file descriptors may be mapped. Sockets, pipes, and most devices only allow sequential access and do not fit into the mapping abstraction. In addition, some regular files may not be mmapable, and older kernels may not support mapping at all. Thus, programs using mmap should have a fallback method to use should it fail. See section `Mmap' in GNU Coding Standards.

Waiting for Input or Output

Sometimes a program needs to accept input on multiple input channels whenever input arrives. For example, some workstations may have devices such as a digitizing tablet, function button box, or dial box that are connected via normal asynchronous serial interfaces; good user interface style requires responding immediately to input on any device. Another example is a program that acts as a server to several other processes via pipes or sockets.

You cannot normally use read for this purpose, because this blocks the program until input is available on one particular file descriptor; input on other channels won't wake it up. You could set nonblocking mode and poll each file descriptor in turn, but this is very inefficient.

A better solution is to use the select function. This blocks the program until input or output is ready on a specified set of file descriptors, or until a timer expires, whichever comes first. This facility is declared in the header file `sys/types.h'.

In the case of a server socket (see section Listening for Connections), we say that "input" is available when there are pending connections that could be accepted (see section Accepting Connections). accept for server sockets blocks and interacts with select just as read does for normal input.

The file descriptor sets for the select function are specified as fd_set objects. Here is the description of the data type and some macros for manipulating these objects.

Data Type: fd_set
The fd_set data type represents file descriptor sets for the select function. It is actually a bit array.

Macro: int FD_SETSIZE
The value of this macro is the maximum number of file descriptors that a fd_set object can hold information about. On systems with a fixed maximum number, FD_SETSIZE is at least that number. On some systems, including GNU, there is no absolute limit on the number of descriptors open, but this macro still has a constant value which controls the number of bits in an fd_set; if you get a file descriptor with a value as high as FD_SETSIZE, you cannot put that descriptor into an fd_set.

Macro: void FD_ZERO (fd_set *set)
This macro initializes the file descriptor set set to be the empty set.

Macro: void FD_SET (int filedes, fd_set *set)
This macro adds filedes to the file descriptor set set.

Macro: void FD_CLR (int filedes, fd_set *set)
This macro removes filedes from the file descriptor set set.

Macro: int FD_ISSET (int filedes, fd_set *set)
This macro returns a nonzero value (true) if filedes is a member of the file descriptor set set, and zero (false) otherwise.

Next, here is the description of the select function itself.

Function: int select (int nfds, fd_set *read-fds, fd_set *write-fds, fd_set *except-fds, struct timeval *timeout)
The select function blocks the calling process until there is activity on any of the specified sets of file descriptors, or until the timeout period has expired.

The file descriptors specified by the read-fds argument are checked to see if they are ready for reading; the write-fds file descriptors are checked to see if they are ready for writing; and the except-fds file descriptors are checked for exceptional conditions. You can pass a null pointer for any of these arguments if you are not interested in checking for that kind of condition.

A file descriptor is considered ready for reading if it is not at end of file. A server socket is considered ready for reading if there is a pending connection which can be accepted with accept; see section Accepting Connections. A client socket is ready for writing when its connection is fully established; see section Making a Connection.

"Exceptional conditions" does not mean errors--errors are reported immediately when an erroneous system call is executed, and do not constitute a state of the descriptor. Rather, they include conditions such as the presence of an urgent message on a socket. (See section Sockets, for information on urgent messages.)

The select function checks only the first nfds file descriptors. The usual thing is to pass FD_SETSIZE as the value of this argument.

The timeout specifies the maximum time to wait. If you pass a null pointer for this argument, it means to block indefinitely until one of the file descriptors is ready. Otherwise, you should provide the time in struct timeval format; see section High-Resolution Calendar. Specify zero as the time (a struct timeval containing all zeros) if you want to find out which descriptors are ready without waiting if none are ready.

The normal return value from select is the total number of ready file descriptors in all of the sets. Each of the argument sets is overwritten with information about the descriptors that are ready for the corresponding operation. Thus, to see if a particular descriptor desc has input, use FD_ISSET (desc, read-fds) after select returns.

If select returns because the timeout period expires, it returns a value of zero.

Any signal will cause select to return immediately. So if your program uses signals, you can't rely on select to keep waiting for the full time specified. If you want to be sure of waiting for a particular amount of time, you must check for EINTR and repeat the select with a newly calculated timeout based on the current time. See the example below. See also section Primitives Interrupted by Signals.

If an error occurs, select returns -1 and does not modify the argument file descriptor sets. The following errno error conditions are defined for this function:

EBADF
One of the file descriptor sets specified an invalid file descriptor.
EINTR
The operation was interrupted by a signal. See section Primitives Interrupted by Signals.
EINVAL
The timeout argument is invalid; one of the components is negative or too large.
Portability Note: The select function is a BSD Unix feature.

Here is an example showing how you can use select to establish a timeout period for reading from a file descriptor. The input_timeout function blocks the calling process until input is available on the file descriptor, or until the timeout period expires.
#include <stdio.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/time.h>

int
input_timeout (int filedes, unsigned int seconds)
{
  fd_set set;
  struct timeval timeout;

  /* Initialize the file descriptor set. */
  FD_ZERO (&set);
  FD_SET (filedes, &set);

  /* Initialize the timeout data structure. */
  timeout.tv_sec = seconds;
  timeout.tv_usec = 0;

  /* select returns 0 if timeout, 1 if input available, -1 if error. */
  return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
                                     &set, NULL, NULL,
                                     &timeout));
}

int
main (void)
{
  fprintf (stderr, "select returned %d.\n",
           input_timeout (STDIN_FILENO, 5));
  return 0;
}
There is another example showing the use of select to multiplex input from multiple sockets in section Byte Stream Connection Server Example.

Synchronizing I/O operations

In most modern operating systems the normal I/O operations are not executed synchronously. I.e., even if a write system call returns this does not mean the data is actually written to the media, e.g., the disk.

In situations where synchronization points are necessary,you can use special functions which ensure that all operations finish before they return.

Function: int sync (void)
A call to this function will not return as long as there is data which has not been written to the device. All dirty buffers in the kernel will be written and so an overall consistent system can be achieved (if no other process in parallel writes data).

A prototype for sync can be found in `unistd.h'.

The return value is zero to indicate no error.

Programs more often want to ensure that data written to a given file is committed, rather than all data in the system. For this, sync is overkill.

Function: int fsync (int fildes)
The fsync can be used to make sure all data associated with the open file fildes is written to the device associated with the descriptor. The function call does not return unless all actions have finished.

A prototype for fsync can be found in `unistd.h'.

This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time fsync is called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this, calls to fsync should be protected using cancellation handlers.

The return value of the function is zero if no error occurred. Otherwise it is @math{-1} and the global variable errno is set to the following values:
EBADF
The descriptor fildes is not valid.
EINVAL
No synchronization is possible since the system does not implement this.
Sometimes it is not even necessary to write all data associated with a file descriptor. E.g., in database files which do not change in size it is enough to write all the file content data to the device. Meta-information like the modification time etc. are not that important and leaving such information uncommitted does not prevent a successful recovering of the file in case of a problem.

Function: int fdatasync (int fildes)
When a call to the fdatasync function returns, it is ensured that all of the file data is written to the device. For all pending I/O operations, the parts guaranteeing data integrity finished.

Not all systems implement the fdatasync operation. On systems missing this functionality fdatasync is emulated by a call to fsync since the performed actions are a superset of those required by fdatasyn.

The prototype for fdatasync is in `unistd.h'.

The return value of the function is zero if no error occurred. Otherwise it is @math{-1} and the global variable errno is set to the following values:
EBADF
The descriptor fildes is not valid.
EINVAL
No synchronization is possible since the system does not implement this.
Perform I/O Operations in Parallel

The POSIX.1b standard defines a new set of I/O operations which can significantly reduce the time an application spends waiting at I/O. The new functions allow a program to initiate one or more I/O operations and then immediately resume normal work while the I/O operations are executed in parallel. This functionality is available if the `unistd.h' file defines the symbol _POSIX_ASYNCHRONOUS_IO.

These functions are part of the library with realtime functions named `librt'. They are not actually part of the `libc' binary. The implementation of these functions can be done using support in the kernel (if available) or using an implementation based on threads at userlevel. In the latter case it might be necessary to link applications with the thread library `libpthread' in addition to `librt'.

All AIO operations operate on files which were opened previously. There might be arbitrarily many operations running for one file. The asynchronous I/O operations are controlled using a data structure named struct aiocb (AIO control block). It is defined in `aio.h' as follows.

Data Type: struct aiocb
The POSIX.1b standard mandates that the struct aiocb structure contains at least the members described in the following table. There might be more elements which are used by the implementation, but depending on these elements is not portable and is highly deprecated.

int aio_fildes
This element specifies the file descriptor which is used for the operation. It must be a legal descriptor since otherwise the operation fails. The device on which the file is opened must allow the seek operation. I.e., it is not possible to use any of the AIO operations on devices like terminals where an lseek call would lead to an error.
off_t aio_offset
This element specifies at which offset in the file the operation (input or output) is performed. Since the operations are carried out in arbitrary order and more than one operation for one file descriptor can be started, one cannot expect a current read/write position of the file descriptor.
volatile void *aio_buf
This is a pointer to the buffer with the data to be written or the place where the read data is stored.
size_t aio_nbytes
This element specifies the length of the buffer pointed to by aio_buf.
int aio_reqprio
If the platform has defined _POSIX_PRIORITIZED_IO and _POSIX_PRIORITY_SCHEDULING the AIO requests are processed based on the current scheduling priority. The aio_reqprio element can then be used to lower the priority of the AIO operation.
struct sigevent aio_sigevent
This element specifies how the calling process is notified once the operation terminates. If the sigev_notify element is SIGEV_NONE no notification is send. If it is SIGEV_SIGNAL the signal determined by sigev_signo is send. Otherwise sigev_notify must be SIGEV_THREAD. In this case a thread is created which starts executing the function pointed to by sigev_notify_function.
int aio_lio_opcode
This element is only used by the lio_listio and lio_listio64 functions. Since these functions allow an arbitrary number of operations to start at once, and each operation can be input or output (or nothing), the information must be stored in the control block. The possible values are:
LIO_READ
Start a read operation. Read from the file at position aio_offset and store the next aio_nbytes bytes in the buffer pointed to by aio_buf.
LIO_WRITE
Start a write operation. Write aio_nbytes bytes starting at aio_buf into the file starting at position aio_offset.
LIO_NOP
Do nothing for this control block. This value is useful sometimes when an array of struct aiocb values contains holes, i.e., some of the values must not be handled although the whole array is presented to the lio_listio function.
When the sources are compiled using _FILE_OFFSET_BITS == 64 on a 32 bit machine this type is in fact struct aiocb64 since the LFS interface transparently replaces the struct aiocb definition.

For use with the AIO functions defined in the LFS there is a similar type defined which replaces the types of the appropriate members with larger types but otherwise is equivalent to struct aiocb. Particularly, all member names are the same.

Data Type: struct aiocb64

int aio_fildes
This element specifies the file descriptor which is used for the operation. It must be a legal descriptor since otherwise the operation fails for obvious reasons. The device on which the file is opened must allow the seek operation. I.e., it is not possible to use any of the AIO operations on devices like terminals where an lseek call would lead to an error.
off64_t aio_offset
This element specifies at which offset in the file the operation (input or output) is performed. Since the operation are carried in arbitrary order and more than one operation for one file descriptor can be started, one cannot expect a current read/write position of the file descriptor.
volatile void *aio_buf
This is a pointer to the buffer with the data to be written or the place where the ead data is stored.
size_t aio_nbytes
This element specifies the length of the buffer pointed to by aio_buf.
int aio_reqprio
If for the platform _POSIX_PRIORITIZED_IO and _POSIX_PRIORITY_SCHEDULING are defined the AIO requests are processed based on the current scheduling priority. The aio_reqprio element can then be used to lower the priority of the AIO operation.
struct sigevent aio_sigevent
This element specifies how the calling process is notified once the operation terminates. If the sigev_notify element is SIGEV_NONE no notification is sent. If it is SIGEV_SIGNAL the signal determined by sigev_signo is sent. Otherwise sigev_notify must be SIGEV_THREAD in which case a thread which starts executing the function pointed to by sigev_notify_function.
int aio_lio_opcode
This element is only used by the lio_listio and [lio_listio64 functions. Since these functions allow an arbitrary number of operations to start at once, and since each operation can be input or output (or nothing), the information must be stored in the control block. See the description of struct aiocb for a description of the possible values.
When the sources are compiled using _FILE_OFFSET_BITS == 64 on a 32 bit machine this type is available under the name struct aiocb64 since the LFS replaces transparently the old interface.

Asynchronous Read and Write Operations

Function: int aio_read (struct aiocb *aiocbp)
This function initiates an asynchronous read operation. It immediately returns after the operation was enqueued or when an error was encountered.

The first aiocbp->aio_nbytes bytes of the file for which aiocbp->aio_fildes is a descriptor are written to the buffer starting at aiocbp->aio_buf. Reading starts at the absolute position aiocbp->aio_offset in the file.

If prioritized I/O is supported by the platform the aiocbp->aio_reqprio value is used to adjust the priority before the request is actually enqueued.

The calling process is notified about the termination of the read request according to the aiocbp->aio_sigevent value.

When aio_read returns, the return value is zero if no error occurred that can be found before the process is enqueued. If such an early error is found, the function returns @math{-1} and sets errno to one of the following values:

EAGAIN
The request was not enqueued due to (temporarily) exceeded resource limitations.
ENOSYS
The aio_read function is not implemented.
EBADF
The aiocbp->aio_fildes descriptor is not valid. This condition need not be recognized before enqueueing the request and so this error might also be signaled asynchronously.
EINVAL
The aiocbp->aio_offset or aiocbp->aio_reqpiro value is invalid. This condition need not be recognized before enqueueing the request and so this error might also be signaled asynchronously.
If aio_read returns zero, the current status of the request can be queried using aio_error and aio_return functions. As long as the value returned by aio_error is EINPROGRESS the operation has not yet completed. If aio_error returns zero, the operation successfully terminated, otherwise the value is to be interpreted as an error code. If the function terminated, the result of the operation can be obtained using a call to aio_return. The returned value is the same as an equivalent call to read would have returned. Possible error codes returned by aio_error are:

EBADF
The aiocbp->aio_fildes descriptor is not valid.
ECANCELED
The operation was cancelled before the operation was finished (see section Cancellation of AIO Operations)
EINVAL
The aiocbp->aio_offset value is invalid.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact aio_read64 since the LFS interface transparently replaces the normal implementation.

Function: int aio_read64 (struct aiocb *aiocbp)
This function is similar to the aio_read function. The only difference is that on 32 bit machines the file descriptor should be opened in the large file mode. Internally aio_read64 uses functionality equivalent to lseek64 (see section Setting the File Position of a Descriptor) to position the file descriptor correctly for the reading, as opposed to lseek functionality used in aio_read.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name aio_read and so transparently replaces the interface for small files on 32 bit machines.

To write data asynchronously to a file there exists an equivalent pair of functions with a very similar interface.

Function: int aio_write (struct aiocb *aiocbp)
This function initiates an asynchronous write operation. The function call immediately returns after the operation was enqueued or if before this happens an error was encountered.

The first aiocbp->aio_nbytes bytes from the buffer starting at aiocbp->aio_buf are written to the file for which aiocbp->aio_fildes is an descriptor, starting at the absolute position aiocbp->aio_offset in the file.

If prioritized I/O is supported by the platform the aiocbp->aio_reqprio value is used to adjust the priority before the request is actually enqueued.

The calling process is notified about the termination of the read request according to the aiocbp->aio_sigevent value.

When aio_write returns the return value is zero if no error occurred that can be found before the process is enqueued. If such an early error is found the function returns @math{-1} and sets errno to one of the following values.

EAGAIN
The request was not enqueued due to (temporarily) exceeded resource limitations.
ENOSYS
The aio_write function is not implemented.
EBADF
The aiocbp->aio_fildes descriptor is not valid. This condition needs not be recognized before enqueueing the request and so this error might also be signaled asynchronously.
EINVAL
The aiocbp->aio_offset or aiocbp->aio_reqpiro value is invalid. This condition needs not be recognized before enqueueing the request and so this error might also be signaled asynchronously.
In the case aio_write returns zero the current status of the request can be queried using aio_error and aio_return functions. As long as the value returned by aio_error is EINPROGRESS the operation has not yet completed. If aio_error returns zero the operation successfully terminated, otherwise the value is to be interpreted as an error code. If the function terminated the result of the operation can be get using a call to aio_return. The returned value is the same as an equivalent call to read would have returned. Possible error code returned by aio_error are:

EBADF
The aiocbp->aio_fildes descriptor is not valid.
ECANCELED
The operation was cancelled before the operation was finished (see section Cancellation of AIO Operations)
EINVAL
The aiocbp->aio_offset value is invalid.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact aio_write64 since the LFS interface transparently replaces the normal implementation.

Function: int aio_write64 (struct aiocb *aiocbp)
This function is similar to the aio_write function. The only difference is that on 32 bit machines the file descriptor should be opened in the large file mode. Internally aio_write64 uses functionality equivalent to lseek64 (see section Setting the File Position of a Descriptor) to position the file descriptor correctly for the writing, as opposed to lseek functionality used in aio_write.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name aio_write and so transparently replaces the interface for small files on 32 bit machines.

Beside these functions with the more or less traditional interface POSIX.1b also defines a function with can initiate more than one operation at once and which can handled freely mixed read and write operation. It is therefore similar to a combination of readv and writev.

Function: int lio_listio (int mode, struct aiocb *const list[], int nent, struct sigevent *sig)
The lio_listio function can be used to enqueue an arbitrary number of read and write requests at one time. The requests can all be meant for the same file, all for different files or every solution in between.

lio_listio gets the nent requests from the array pointed to by list. What operation has to be performed is determined by the aio_lio_opcode member in each element of list. If this field is LIO_READ an read operation is queued, similar to a call of aio_read for this element of the array (except that the way the termination is signalled is different, as we will see below). If the aio_lio_opcode member is LIO_WRITE an write operation is enqueued. Otherwise the aio_lio_opcode must be LIO_NOP in which case this element of list is simply ignored. This "operation" is useful in situations where one has a fixed array of struct aiocb elements from which only a few need to be handled at a time. Another situation is where the lio_listio call was cancelled before all requests are processed (see section Cancellation of AIO Operations) and the remaining requests have to be reissued.

The other members of each element of the array pointed to by list must have values suitable for the operation as described in the documentation for aio_read and aio_write above.

The mode argument determines how lio_listio behaves after having enqueued all the requests. If mode is LIO_WAIT it waits until all requests terminated. Otherwise mode must be LIO_NOWAIT and in this case the function returns immediately after having enqueued all the requests. In this case the caller gets a notification of the termination of all requests according to the sig parameter. If sig is NULL no notification is send. Otherwise a signal is sent or a thread is started, just as described in the description for aio_read or aio_write.

If mode is LIO_WAIT the return value of lio_listio is @math{0} when all requests completed successfully. Otherwise the function return @math{-1} and errno is set accordingly. To find out which request or requests failed one has to use the aio_error function on all the elements of the array list.

In case mode is LIO_NOWAIT the function return @math{0} if all requests were enqueued correctly. The current state of the requests can be found using aio_error and aio_return as described above. In case lio_listio returns @math{-1} in this mode the global variable errno is set accordingly. If a request did not yet terminate a call to aio_error returns EINPROGRESS. If the value is different the request is finished and the error value (or @math{0}) is returned and the result of the operation can be retrieved using aio_return.

Possible values for errno are:

EAGAIN
The resources necessary to queue all the requests are not available in the moment. The error status for each element of list must be checked which request failed. Another reason could be that the system wide limit of AIO requests is exceeded. This cannot be the case for the implementation on GNU systems since no arbitrary limits exist.
EINVAL
The mode parameter is invalid or nent is larger than AIO_LISTIO_MAX.
EIO
One or more of the request's I/O operations failed. The error status of each request should be checked for which one failed.
ENOSYS
The lio_listio function is not supported.
If the mode parameter is LIO_NOWAIT and the caller cancels an request the error status for this request returned by aio_error is ECANCELED.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact lio_listio64 since the LFS interface transparently replaces the normal implementation.

Function: int lio_listio64 (int mode, struct aiocb *const list, int nent, struct sigevent *sig)
This function is similar to the aio_listio function. The only difference is that only 32 bit machines the file descriptor should be opened in the large file mode. Internally lio_listio64 uses functionality equivalent to lseek64 (see section Setting the File Position of a Descriptor) to position the file descriptor correctly for the reading or writing, as opposed to lseek functionality used in lio_listio.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name lio_listio and so transparently replaces the interface for small files on 32 bit machines.

Getting the Status of AIO Operations

As already described in the documentation of the functions in the last section, it must be possible to get information about the status of an I/O request. When the operation is performed truly asynchronously (as with aio_read and aio_write and with aio_listio when the mode is LIO_NOWAIT) one sometimes needs to know whether a specific request already terminated and if yes, what the result was. The following two functions allow you to get this kind of information.

Function: int aio_error (const struct aiocb *aiocbp)
This function determines the error state of the request described by the struct aiocb variable pointed to by aiocbp. If the request has not yet terminated the value returned is always EINPROGRESS. Once the request has terminated the value aio_error returns is either @math{0} if the request completed successfully or it returns the value which would be stored in the errno variable if the request would have been done using read, write, or fsync.

The function can return ENOSYS if it is not implemented. It could also return EINVAL if the aiocbp parameter does not refer to an asynchronous operation whose return status is not yet known.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact aio_error64 since the LFS interface transparently replaces the normal implementation.

Function: int aio_error64 (const struct aiocb64 *aiocbp)
This function is similar to aio_error with the only difference that the argument is a reference to a variable of type struct aiocb64.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name aio_error and so transparently replaces the interface for small files on 32 bit machines.

Function: ssize_t aio_return (const struct aiocb *aiocbp)
This function can be used to retrieve the return status of the operation carried out by the request described in the variable pointed to by aiocbp. As long as the error status of this request as returned by aio_error is EINPROGRESS the return of this function is undefined.

Once the request is finished this function can be used exactly once to retrieve the return value. Following calls might lead to undefined behaviour. The return value itself is the value which would have been returned by the read, write, or fsync call.

The function can return ENOSYS if it is not implemented. It could also return EINVAL if the aiocbp parameter does not refer to an asynchronous operation whose return status is not yet known.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact aio_return64 since the LFS interface transparently replaces the normal implementation.

Function: int aio_return64 (const struct aiocb64 *aiocbp)
This function is similar to aio_return with the only difference that the argument is a reference to a variable of type struct aiocb64.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name aio_return and so transparently replaces the interface for small files on 32 bit machines.

Getting into a Consistent State

When dealing with asynchronous operations it is sometimes necessary to get into a consistent state. This would mean for AIO that one wants to know whether a certain request or a group of request were processed. This could be done by waiting for the notification sent by the system after the operation terminated, but this sometimes would mean wasting resources (mainly computation time). Instead POSIX.1b defines two functions which will help with most kinds of consistency.

The aio_fsync and aio_fsync64 functions are only available if in `unistd.h' the symbol _POSIX_SYNCHRONIZED_IO is defined.

Function: int aio_fsync (int op, struct aiocb *aiocbp)
Calling this function forces all I/O operations operating queued at the time of the function call operating on the file descriptor aiocbp->aio_fildes into the synchronized I/O completion state (see section Synchronizing I/O operations). The aio_fsync function returns immediately but the notification through the method described in aiocbp->aio_sigevent will happen only after all requests for this file descriptor have terminated and the file is synchronized. This also means that requests for this very same file descriptor which are queued after the synchronization request are not affected.

If op is O_DSYNC the synchronization happens as with a call to fdatasync. Otherwise op should be O_SYNC and the synchronization happens as with fsync.

As long as the synchronization has not happened a call to aio_error with the reference to the object pointed to by aiocbp returns EINPROGRESS. Once the synchronization is done aio_error return @math{0} if the synchronization was not successful. Otherwise the value returned is the value to which the fsync or fdatasync function would have set the errno variable. In this case nothing can be assumed about the consistency for the data written to this file descriptor.

The return value of this function is @math{0} if the request was successfully filed. Otherwise the return value is @math{-1} and errno is set to one of the following values:

EAGAIN
The request could not be enqueued due to temporary lack of resources.
EBADF
The file descriptor aiocbp->aio_fildes is not valid or not open for writing.
EINVAL
The implementation does not support I/O synchronization or the op parameter is other than O_DSYNC and O_SYNC.
ENOSYS
This function is not implemented.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact aio_return64 since the LFS interface transparently replaces the normal implementation.

Function: int aio_fsync64 (int op, struct aiocb64 *aiocbp)
This function is similar to aio_fsync with the only difference that the argument is a reference to a variable of type struct aiocb64.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name aio_fsync and so transparently replaces the interface for small files on 32 bit machines.

Another method of synchronization is to wait until one or more requests of a specific set terminated. This could be achieved by the aio_* functions to notify the initiating process about the termination but in some situations this is not the ideal solution. In a program which constantly updates clients somehow connected to the server it is not always the best solution to go round robin since some connections might be slow. On the other hand letting the aio_* function notify the caller might also be not the best solution since whenever the process works on preparing data for on client it makes no sense to be interrupted by a notification since the new client will not be handled before the current client is served. For situations like this aio_suspend should be used.

Function: int aio_suspend (const struct aiocb *const list[], int nent, const struct timespec *timeout)
When calling this function the calling thread is suspended until at least one of the requests pointed to by the nent elements of the array list has completed. If any of the requests already has completed at the time aio_suspend is called the function returns immediately. Whether a request has terminated or not is done by comparing the error status of the request with EINPROGRESS. If an element of list is NULL the entry is simply ignored.

If no request has finished the calling process is suspended. If timeout is NULL the process is not waked until a request finished. If timeout is not NULL the process remains suspended at as long as specified in timeout. In this case aio_suspend returns with an error.

The return value of the function is @math{0} if one or more requests from the list have terminated. Otherwise the function returns @math{-1} and errno is set to one of the following values:

EAGAIN
None of the requests from the list completed in the time specified by timeout.
EINTR
A signal interrupted the aio_suspend function. This signal might also be sent by the AIO implementation while signalling the termination of one of the requests.
ENOSYS
The aio_suspend function is not implemented.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact aio_suspend64 since the LFS interface transparently replaces the normal implementation.

Function: int aio_suspend64 (const struct aiocb64 *const list[], int nent, const struct timespec *timeout)
This function is similar to aio_suspend with the only difference that the argument is a reference to a variable of type struct aiocb64.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name aio_suspend and so transparently replaces the interface for small files on 32 bit machines.

Cancellation of AIO Operations

When one or more requests are asynchronously processed it might be useful in some situations to cancel a selected operation, e.g., if it becomes obvious that the written data is not anymore accurate and would have to be overwritten soon. As an example assume an application, which writes data in files in a situation where new incoming data would have to be written in a file which will be updated by an enqueued request. The POSIX AIO implementation provides such a function but this function is not capable to force the cancellation of the request. It is up to the implementation to decide whether it is possible to cancel the operation or not. Therefore using this function is merely a hint.

Function: int aio_cancel (int fildes, struct aiocb *aiocbp)
The aio_cancel function can be used to cancel one or more outstanding requests. If the aiocbp parameter is NULL the function tries to cancel all outstanding requests which would process the file descriptor fildes (i.e.,, whose aio_fildes member is fildes). If aiocbp is not NULL the very specific request pointed to by aiocbp is tried to be cancelled.

For requests which were successfully cancelled the normal notification about the termination of the request should take place. I.e., depending on the struct sigevent object which controls this, nothing happens, a signal is sent or a thread is started. If the request cannot be cancelled it terminates the usual way after performing te operation.

After a request is successfully cancelled a call to aio_error with a reference to this request as the parameter will return ECANCELED and a call to aio_return will return @math{-1}. If the request wasn't cancelled and is still running the error status is still EINPROGRESS.

The return value of the function is AIO_CANCELED if there were requests which haven't terminated and which successfully were cancelled. If there is one or more request left which couldn't be cancelled the return value is AIO_NOTCANCELED. In this case aio_error must be used to find out which of the perhaps multiple requests (in aiocbp is NULL) wasn't successfully cancelled. If all requests already terminated at the time aio_cancel is called the return value is AIO_ALLDONE.

If an error occurred during the execution of aio_cancel the function returns @math{-1} and sets errno to one of the following values.

EBADF
The file descriptor fildes is not valid.
ENOSYS
aio_cancel is not implemented.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact aio_cancel64 since the LFS interface transparently replaces the normal implementation.

Function: int aio_cancel64 (int fildes, struct aiocb *aiocbp)
This function is similar to aio_cancel with the only difference that the argument is a reference to a variable of type struct aiocb64.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name aio_cancel and so transparently replaces the interface for small files on 32 bit machines.

How to optimize the AIO implementation

The POSIX standard does not specify how the AIO functions are implemented. They could be system calls but it is also possible to emulate them at userlevel.

At least the available implementation at the point of this writing is a userlevel implementation which uses threads for handling the enqueued requests. This implementation requires to make some decisions about limitations but hard limitations are something which better should be avoided the GNU C library implementation provides a mean to tune the AIO implementation individually for each use.

Data Type: struct aioinit
This data type is used to pass the configuration or tunable parameters to the implementation. The program has to initialize the members of this struct and pass it to the implementation using the aio_init function.

int aio_threads
This member specifies the maximal number of threads which must be used at any one time.
int aio_num
This number provides an estimate on the maximal number of simultaneously enqueued requests.
int aio_locks

int aio_usedba

int aio_debug

int aio_numusers

int aio_reserved[2]

Function: void aio_init (const struct aioinit *init)
This function must be called before any other AIO function. Calling it is completely voluntarily since it only is meant to help the AIO implementation to perform better.

Before calling the aio_init function the members of a variable of type struct aioinit must be initialized. Then a reference to this variable is passed as the parameter to aio_init which itself may or may not pay attention to the hints.

The function has no return value and no error cases are defined. It is a extension which follows a proposal from the SGI implementation in Irix 6. It is not covered by POSIX.1b or Unix98.

Control Operations on Files

This section describes how you can perform various other operations on file descriptors, such as inquiring about or setting flags describing the status of the file descriptor, manipulating record locks, and the like. All of these operations are performed by the function fcntl.

The second argument to the fcntl function is a command that specifies which operation to perform. The function and macros that name various flags that are used with it are declared in the header file `fcntl.h'. Many of these flags are also used by the open function; see section Opening and Closing Files.

Function: int fcntl (int filedes, int command, ...)
The fcntl function performs the operation specified by command on the file descriptor filedes. Some commands require additional arguments to be supplied. These additional arguments and the return value and error conditions are given in the detailed descriptions of the individual commands.

Briefly, here is a list of what the various commands are.

F_DUPFD
Duplicate the file descriptor (return another file descriptor pointing to the same open file). See section Duplicating Descriptors.
F_GETFD
Get flags associated with the file descriptor. See section File Descriptor Flags.
F_SETFD
Set flags associated with the file descriptor. See section File Descriptor Flags.
F_GETFL
Get flags associated with the open file. See section File Status Flags.
F_SETFL
Set flags associated with the open file. See section File Status Flags.
F_GETLK
Get a file lock. See section File Locks.
F_SETLK
Set or clear a file lock. See section File Locks.
F_SETLKW
Like F_SETLK, but wait for completion. See section File Locks.
F_GETOWN
Get process or process group ID to receive SIGIO signals. See section Interrupt-Driven Input.
F_SETOWN
Set process or process group ID to receive SIGIO signals. See section Interrupt-Driven Input.
This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time fcntl is called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this calls to fcntl should be protected using cancellation handlers.

Duplicating Descriptors

You can duplicate a file descriptor, or allocate another file descriptor that refers to the same open file as the original. Duplicate descriptors share one file position and one set of file status flags (see section File Status Flags), but each has its own set of file descriptor flags (see section File Descriptor Flags).

The major use of duplicating a file descriptor is to implement redirection of input or output: that is, to change the file or pipe that a particular file descriptor corresponds to.

You can perform this operation using the fcntl function with the F_DUPFD command, but there are also convenient functions dup and dup2 for duplicating descriptors.

The fcntl function and flags are declared in `fcntl.h', while prototypes for dup and dup2 are in the header file `unistd.h'.

Function: int dup (int old)
This function copies descriptor old to the first available descriptor number (the first number not currently open). It is equivalent to fcntl (old, F_DUPFD, 0).

Function: int dup2 (int old, int new)
This function copies the descriptor old to descriptor number new.

If old is an invalid descriptor, then dup2 does nothing; it does not close new. Otherwise, the new duplicate of old replaces any previous meaning of descriptor new, as if new were closed first.

If old and new are different numbers, and old is a valid descriptor number, then dup2 is equivalent to:
close (new);
fcntl (old, F_DUPFD, new)
However, dup2 does this atomically; there is no instant in the middle of calling dup2 at which new is closed and not yet a duplicate of old.

Macro: int F_DUPFD
This macro is used as the command argument to fcntl, to copy the file descriptor given as the first argument.

The form of the call in this case is:
fcntl (old, F_DUPFD, next-filedes)
The next-filedes argument is of type int and specifies that the file descriptor returned should be the next available one greater than or equal to this value.

The return value from fcntl with this command is normally the value of the new file descriptor. A return value of @math{-1} indicates an error. The following errno error conditions are defined for this command:

EBADF
The old argument is invalid.
EINVAL
The next-filedes argument is invalid.
EMFILE
There are no more file descriptors available--your program is already using the maximum. In BSD and GNU, the maximum is controlled by a resource limit that can be changed; see section Limiting Resource Usage, for more information about the RLIMIT_NOFILE limit.
ENFILE is not a possible error code for dup2 because dup2 does not create a new opening of a file; duplicate descriptors do not count toward the limit which ENFILE indicates. EMFILE is possible because it refers to the limit on distinct descriptor numbers in use in one process.

Here is an example showing how to use dup2 to do redirection. Typically, redirection of the standard streams (like stdin) is done by a shell or shell-like program before calling one of the exec functions (see section Executing a File) to execute a new program in a child process. When the new program is executed, it creates and initializes the standard streams to point to the corresponding file descriptors, before its main function is invoked.

So, to redirect standard input to a file, the shell could do something like:
pid = fork ();
if (pid == 0)
  {
    char *filename;
    char *program;
    int file;
    ...
    file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
    dup2 (file, STDIN_FILENO);
    TEMP_FAILURE_RETRY (close (file));
    execv (program, NULL);
  }
There is also a more detailed example showing how to implement redirection in the context of a pipeline of processes in section Launching Jobs.

File Descriptor Flags

File descriptor flags are miscellaneous attributes of a file descriptor. These flags are associated with particular file descriptors, so that if you have created duplicate file descriptors from a single opening of a file, each descriptor has its own set of flags.

Currently there is just one file descriptor flag: FD_CLOEXEC, which causes the descriptor to be closed if you use any of the exec... functions (see section Executing a File).

The symbols in this section are defined in the header file `fcntl.h'.

Macro: int F_GETFD
This macro is used as the command argument to fcntl, to specify that it should return the file descriptor flags associated with the filedes argument.

The normal return value from fcntl with this command is a nonnegative number which can be interpreted as the bitwise OR of the individual flags (except that currently there is only one flag to use).

In case of an error, fcntl returns @math{-1}. The following errno error conditions are defined for this command:

EBADF
The filedes argument is invalid.

Macro: int F_SETFD
This macro is used as the command argument to fcntl, to specify that it should set the file descriptor flags associated with the filedes argument. This requires a third int argument to specify the new flags, so the form of the call is:
fcntl (filedes, F_SETFD, new-flags)
The normal return value from fcntl with this command is an unspecified value other than @math{-1}, which indicates an error. The flags and error conditions are the same as for the F_GETFD command.

The following macro is defined for use as a file descriptor flag with the fcntl function. The value is an integer constant usable as a bit mask value.

Macro: int FD_CLOEXEC
This flag specifies that the file descriptor should be closed when an exec function is invoked; see section Executing a File. When a file descriptor is allocated (as with open or dup), this bit is initially cleared on the new file descriptor, meaning that descriptor will survive into the new program after exec.

If you want to modify the file descriptor flags, you should get the current flags with F_GETFD and modify the value. Don't assume that the flags listed here are the only ones that are implemented; your program may be run years from now and more flags may exist then. For example, here is a function to set or clear the flag FD_CLOEXEC without altering any other flags:
/* Set the FD_CLOEXEC flag of desc if value is nonzero,
   or clear the flag if value is 0.
   Return 0 on success, or -1 on error with errno set. */

int
set_cloexec_flag (int desc, int value)
{
  int oldflags = fcntl (desc, F_GETFD, 0);
  /* If reading the flags failed, return error indication now.
  if (oldflags < 0)
    return oldflags;
  /* Set just the flag we want to set. */
  if (value != 0)
    oldflags |= FD_CLOEXEC;
  else
    oldflags &= ~FD_CLOEXEC;
  /* Store modified flag word in the descriptor. */
  return fcntl (desc, F_SETFD, oldflags);
}
File Status Flags

File status flags are used to specify attributes of the opening of a file. Unlike the file descriptor flags discussed in section File Descriptor Flags, the file status flags are shared by duplicated file descriptors resulting from a single opening of the file. The file status flags are specified with the flags argument to open; see section Opening and Closing Files.

File status flags fall into three categories, which are described in the following sections.

section File Access Modes, specify what type of access is allowed to the file: reading, writing, or both. They are set by open and are returned by fcntl, but cannot be changed.
section Open-time Flags, control details of what open will do. These flags are not preserved after the open call.
section I/O Operating Modes, affect how operations such as read and write are done. They are set by open, and can be fetched or changed with fcntl.

The symbols in this section are defined in the header file `fcntl.h'.

File Access Modes

The file access modes allow a file descriptor to be used for reading, writing, or both. (In the GNU system, they can also allow none of these, and allow execution of the file as a program.) The access modes are chosen when the file is opened, and never change.

Macro: int O_RDONLY
Open the file for read access.

Macro: int O_WRONLY
Open the file for write access.

Macro: int O_RDWR
Open the file for both reading and writing.

In the GNU system (and not in other systems), O_RDONLY and O_WRONLY are independent bits that can be bitwise-ORed together, and it is valid for either bit to be set or clear. This means that O_RDWR is the same as O_RDONLY|O_WRONLY. A file access mode of zero is permissible; it allows no operations that do input or output to the file, but does allow other operations such as fchmod. On the GNU system, since "read-only" or "write-only" is a misnomer, `fcntl.h' defines additional names for the file access modes. These names are preferred when writing GNU-specific code. But most programs will want to be portable to other POSIX.1 systems and should use the POSIX.1 names above instead.

Macro: int O_READ
Open the file for reading. Same as O_RDWR; only defined on GNU.

Macro: int O_WRITE
Open the file for reading. Same as O_WRONLY; only defined on GNU.

Macro: int O_EXEC
Open the file for executing. Only defined on GNU.

To determine the file access mode with fcntl, you must extract the access mode bits from the retrieved file status flags. In the GNU system, you can just test the O_READ and O_WRITE bits in the flags word. But in other POSIX.1 systems, reading and writing access modes are not stored as distinct bit flags. The portable way to extract the file access mode bits is with O_ACCMODE.

Macro: int O_ACCMODE
This macro stands for a mask that can be bitwise-ANDed with the file status flag value to produce a value representing the file access mode. The mode will be O_RDONLY, O_WRONLY, or O_RDWR. (In the GNU system it could also be zero, and it never includes the O_EXEC bit.)

Open-time Flags

The open-time flags specify options affecting how open will behave. These options are not preserved once the file is open. The exception to this is O_NONBLOCK, which is also an I/O operating mode and so it is saved. See section Opening and Closing Files, for how to call open.

There are two sorts of options specified by open-time flags.

File name translation flags affect how open looks up the file name to locate the file, and whether the file can be created.
Open-time action flags specify extra operations that open will perform on the file once it is open.

Here are the file name translation flags.

Macro: int O_CREAT
If set, the file will be created if it doesn't already exist.

Macro: int O_EXCL
If both O_CREAT and O_EXCL are set, then open fails if the specified file already exists. This is guaranteed to never clobber an existing file.

Macro: int O_NONBLOCK
This prevents open from blocking for a "long time" to open the file. This is only meaningful for some kinds of files, usually devices such as serial ports; when it is not meaningful, it is harmless and ignored. Often opening a port to a modem blocks until the modem reports carrier detection; if O_NONBLOCK is specified, open will return immediately without a carrier.

Note that the O_NONBLOCK flag is overloaded as both an I/O operating mode and a file name translation flag. This means that specifying O_NONBLOCK in open also sets nonblocking I/O mode; see section I/O Operating Modes. To open the file without blocking but do normal I/O that blocks, you must call open with O_NONBLOCK set and then call fcntl to turn the bit off.

Macro: int O_NOCTTY
If the named file is a terminal device, don't make it the controlling terminal for the process. See section Job Control, for information about what it means to be the controlling terminal.

In the GNU system and 4.4 BSD, opening a file never makes it the controlling terminal and O_NOCTTY is zero. However, other systems may use a nonzero value for O_NOCTTY and set the controlling terminal when you open a file that is a terminal device; so to be portable, use O_NOCTTY when it is important to avoid this.

The following three file name translation flags exist only in the GNU system.

Macro: int O_IGNORE_CTTY
Do not recognize the named file as the controlling terminal, even if it refers to the process's existing controlling terminal device. Operations on the new file descriptor will never induce job control signals. See section Job Control.

Macro: int O_NOLINK
If the named file is a symbolic link, open the link itself instead of the file it refers to. (fstat on the new file descriptor will return the information returned by lstat on the link's name.)

Macro: int O_NOTRANS
If the named file is specially translated, do not invoke the translator. Open the bare file the translator itself sees.

The open-time action flags tell open to do additional operations which are not really related to opening the file. The reason to do them as part of open instead of in separate calls is that open can do them atomically.

Macro: int O_TRUNC
Truncate the file to zero length. This option is only useful for regular files, not special files such as directories or FIFOs. POSIX.1 requires that you open the file for writing to use O_TRUNC. In BSD and GNU you must have permission to write the file to truncate it, but you need not open for write access.

This is the only open-time action flag specified by POSIX.1. There is no good reason for truncation to be done by open, instead of by calling ftruncate afterwards. The O_TRUNC flag existed in Unix before ftruncate was invented, and is retained for backward compatibility.

The remaining operating modes are BSD extensions. They exist only on some systems. On other systems, these macros are not defined.

Macro: int O_SHLOCK
Acquire a shared lock on the file, as with flock. See section File Locks.

If O_CREAT is specified, the locking is done atomically when creating the file. You are guaranteed that no other process will get the lock on the new file first.

Macro: int O_EXLOCK
Acquire an exclusive lock on the file, as with flock. See section File Locks. This is atomic like O_SHLOCK.

I/O Operating Modes

The operating modes affect how input and output operations using a file descriptor work. These flags are set by open and can be fetched and changed with fcntl.

Macro: int O_APPEND
The bit that enables append mode for the file. If set, then all write operations write the data at the end of the file, extending it, regardless of the current file position. This is the only reliable way to append to a file. In append mode, you are guaranteed that the data you write will always go to the current end of the file, regardless of other processes writing to the file. Conversely, if you simply set the file position to the end of file and write, then another process can extend the file after you set the file position but before you write, resulting in your data appearing someplace before the real end of file.

Macro: int O_NONBLOCK
The bit that enables nonblocking mode for the file. If this bit is set, read requests on the file can return immediately with a failure status if there is no input immediately available, instead of blocking. Likewise, write requests can also return immediately with a failure status if the output can't be written immediately.

Note that the O_NONBLOCK flag is overloaded as both an I/O operating mode and a file name translation flag; see section Open-time Flags.

Macro: int O_NDELAY
This is an obsolete name for O_NONBLOCK, provided for compatibility with BSD. It is not defined by the POSIX.1 standard.

The remaining operating modes are BSD and GNU extensions. They exist only on some systems. On other systems, these macros are not defined.

Macro: int O_ASYNC
The bit that enables asynchronous input mode. If set, then SIGIO signals will be generated when input is available. See section Interrupt-Driven Input.

Asynchronous input mode is a BSD feature.

Macro: int O_FSYNC
The bit that enables synchronous writing for the file. If set, each write call will make sure the data is reliably stored on disk before returning.

Synchronous writing is a BSD feature.

Macro: int O_SYNC
This is another name for O_FSYNC. They have the same value.

Macro: int O_NOATIME
If this bit is set, read will not update the access time of the file. See section File Times. This is used by programs that do backups, so that backing a file up does not count as reading it. Only the owner of the file or the superuser may use this bit.

This is a GNU extension.

Getting and Setting File Status Flags

The fcntl function can fetch or change file status flags.

Macro: int F_GETFL
This macro is used as the command argument to fcntl, to read the file status flags for the open file with descriptor filedes.

The normal return value from fcntl with this command is a nonnegative number which can be interpreted as the bitwise OR of the individual flags. Since the file access modes are not single-bit values, you can mask off other bits in the returned flags with O_ACCMODE to compare them.

In case of an error, fcntl returns @math{-1}. The following errno error conditions are defined for this command:

EBADF
The filedes argument is invalid.

Macro: int F_SETFL
This macro is used as the command argument to fcntl, to set the file status flags for the open file corresponding to the filedes argument. This command requires a third int argument to specify the new flags, so the call looks like this:
fcntl (filedes, F_SETFL, new-flags)
You can't change the access mode for the file in this way; that is, whether the file descriptor was opened for reading or writing.

The normal return value from fcntl with this command is an unspecified value other than @math{-1}, which indicates an error. The error conditions are the same as for the F_GETFL command.

If you want to modify the file status flags, you should get the current flags with F_GETFL and modify the value. Don't assume that the flags listed here are the only ones that are implemented; your program may be run years from now and more flags may exist then. For example, here is a function to set or clear the flag O_NONBLOCK without altering any other flags:
/* Set the O_NONBLOCK flag of desc if value is nonzero,
   or clear the flag if value is 0.
   Return 0 on success, or -1 on error with errno set. */

int
set_nonblock_flag (int desc, int value)
{
  int oldflags = fcntl (desc, F_GETFL, 0);
  /* If reading the flags failed, return error indication now. */
  if (oldflags == -1)
    return -1;
  /* Set just the flag we want to set. */
  if (value != 0)
    oldflags |= O_NONBLOCK;
  else
    oldflags &= ~O_NONBLOCK;
  /* Store modified flag word in the descriptor. */
  return fcntl (desc, F_SETFL, oldflags);
}
File Locks

The remaining fcntl commands are used to support record locking, which permits multiple cooperating programs to prevent each other from simultaneously accessing parts of a file in error-prone ways.

An exclusive or write lock gives a process exclusive access for writing to the specified part of the file. While a write lock is in place, no other process can lock that part of the file.

A shared or read lock prohibits any other process from requesting a write lock on the specified part of the file. However, other processes can request read locks.

The read and write functions do not actually check to see whether there are any locks in place. If you want to implement a locking protocol for a file shared by multiple processes, your application must do explicit fcntl calls to request and clear locks at the appropriate points.

Locks are associated with processes. A process can only have one kind of lock set for each byte of a given file. When any file descriptor for that file is closed by the process, all of the locks that process holds on that file are released, even if the locks were made using other descriptors that remain open. Likewise, locks are released when a process exits, and are not inherited by child processes created using fork (see section Creating a Process).

When making a lock, use a struct flock to specify what kind of lock and where. This data type and the associated macros for the fcntl function are declared in the header file `fcntl.h'.

Data Type: struct flock
This structure is used with the fcntl function to describe a file lock. It has these members:

short int l_type
Specifies the type of the lock; one of F_RDLCK, F_WRLCK, or F_UNLCK.
short int l_whence
This corresponds to the whence argument to fseek or lseek, and specifies what the offset is relative to. Its value can be one of SEEK_SET, SEEK_CUR, or SEEK_END.
off_t l_start
This specifies the offset of the start of the region to which the lock applies, and is given in bytes relative to the point specified by l_whence member.
off_t l_len
This specifies the length of the region to be locked. A value of 0 is treated specially; it means the region extends to the end of the file.
pid_t l_pid
This field is the process ID (see section Process Creation Concepts) of the process holding the lock. It is filled in by calling fcntl with the F_GETLK command, but is ignored when making a lock.

Macro: int F_GETLK
This macro is used as the command argument to fcntl, to specify that it should get information about a lock. This command requires a third argument of type struct flock * to be passed to fcntl, so that the form of the call is:
fcntl (filedes, F_GETLK, lockp)
If there is a lock already in place that would block the lock described by the lockp argument, information about that lock overwrites *lockp. Existing locks are not reported if they are compatible with making a new lock as specified. Thus, you should specify a lock type of F_WRLCK if you want to find out about both read and write locks, or F_RDLCK if you want to find out about write locks only.

There might be more than one lock affecting the region specified by the lockp argument, but fcntl only returns information about one of them. The l_whence member of the lockp structure is set to SEEK_SET and the l_start and l_len fields set to identify the locked region.

If no lock applies, the only change to the lockp structure is to update the l_type to a value of F_UNLCK.

The normal return value from fcntl with this command is an unspecified value other than @math{-1}, which is reserved to indicate an error. The following errno error conditions are defined for this command:

EBADF
The filedes argument is invalid.
EINVAL
Either the lockp argument doesn't specify valid lock information, or the file associated with filedes doesn't support locks.

Macro: int F_SETLK
This macro is used as the command argument to fcntl, to specify that it should set or clear a lock. This command requires a third argument of type struct flock * to be passed to fcntl, so that the form of the call is:
fcntl (filedes, F_SETLK, lockp)
If the process already has a lock on any part of the region, the old lock on that part is replaced with the new lock. You can remove a lock by specifying a lock type of F_UNLCK.

If the lock cannot be set, fcntl returns immediately with a value of @math{-1}. This function does not block waiting for other processes to release locks. If fcntl succeeds, it return a value other than @math{-1}.

The following errno error conditions are defined for this function:

EAGAIN

EACCES
The lock cannot be set because it is blocked by an existing lock on the file. Some systems use EAGAIN in this case, and other systems use EACCES; your program should treat them alike, after F_SETLK. (The GNU system always uses EAGAIN.)
EBADF
Either: the filedes argument is invalid; you requested a read lock but the filedes is not open for read access; or, you requested a write lock but the filedes is not open for write access.
EINVAL
Either the lockp argument doesn't specify valid lock information, or the file associated with filedes doesn't support locks.
ENOLCK
The system has run out of file lock resources; there are already too many file locks in place. Well-designed file systems never report this error, because they have no limitation on the number of locks. However, you must still take account of the possibility of this error, as it could result from network access to a file system on another machine.

Macro: int F_SETLKW
This macro is used as the command argument to fcntl, to specify that it should set or clear a lock. It is just like the F_SETLK command, but causes the process to block (or wait) until the request can be specified.

This command requires a third argument of type struct flock *, as for the F_SETLK command.

The fcntl return values and errors are the same as for the F_SETLK command, but these additional errno error conditions are defined for this command:

EINTR
The function was interrupted by a signal while it was waiting. See section Primitives Interrupted by Signals.
EDEADLK
The specified region is being locked by another process. But that process is waiting to lock a region which the current process has locked, so waiting for the lock would result in deadlock. The system does not guarantee that it will detect all such conditions, but it lets you know if it notices one.
The following macros are defined for use as values for the l_type member of the flock structure. The values are integer constants.

F_RDLCK
This macro is used to specify a read (or shared) lock.
F_WRLCK
This macro is used to specify a write (or exclusive) lock.
F_UNLCK
This macro is used to specify that the region is unlocked.
As an example of a situation where file locking is useful, consider a program that can be run simultaneously by several different users, that logs status information to a common file. One example of such a program might be a game that uses a file to keep track of high scores. Another example might be a program that records usage or accounting information for billing purposes.

Having multiple copies of the program simultaneously writing to the file could cause the contents of the file to become mixed up. But you can prevent this kind of problem by setting a write lock on the file before actually writing to the file.

If the program also needs to read the file and wants to make sure that the contents of the file are in a consistent state, then it can also use a read lock. While the read lock is set, no other process can lock that part of the file for writing.

Remember that file locks are only a voluntary protocol for controlling access to a file. There is still potential for access to the file by programs that don't use the lock protocol.

Interrupt-Driven Input

If you set the O_ASYNC status flag on a file descriptor (see section File Status Flags), a SIGIO signal is sent whenever input or output becomes possible on that file descriptor. The process or process group to receive the signal can be selected by using the F_SETOWN command to the fcntl function. If the file descriptor is a socket, this also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket; see section Out-of-Band Data. (SIGURG is sent in any situation where select would report the socket as having an "exceptional condition". See section Waiting for Input or Output.)

If the file descriptor corresponds to a terminal device, then SIGIO signals are sent to the foreground process group of the terminal. See section Job Control.

The symbols in this section are defined in the header file `fcntl.h'.

Macro: int F_GETOWN
This macro is used as the command argument to fcntl, to specify that it should get information about the process or process group to which SIGIO signals are sent. (For a terminal, this is actually the foreground process group ID, which you can get using tcgetpgrp; see section Functions for Controlling Terminal Access.)

The return value is interpreted as a process ID; if negative, its absolute value is the process group ID.

The following errno error condition is defined for this command:

EBADF
The filedes argument is invalid.

Macro: int F_SETOWN
This macro is used as the command argument to fcntl, to specify that it should set the process or process group to which SIGIO signals are sent. This command requires a third argument of type pid_t to be passed to fcntl, so that the form of the call is:
fcntl (filedes, F_SETOWN, pid)
The pid argument should be a process ID. You can also pass a negative number whose absolute value is a process group ID.

The return value from fcntl with this command is @math{-1} in case of error and some other value if successful. The following errno error conditions are defined for this command:

EBADF
The filedes argument is invalid.
ESRCH
There is no process or process group corresponding to pid.
Generic I/O Control operations

The GNU system can handle most input/output operations on many different devices and objects in terms of a few file primitives - read, write and lseek. However, most devices also have a few peculiar operations which do not fit into this model. Such as:

Changing the character font used on a terminal.
Telling a magnetic tape system to rewind or fast forward. (Since they cannot move in byte increments, lseek is inapplicable).
Ejecting a disk from a drive.
Playing an audio track from a CD-ROM drive.
Maintaining routing tables for a network.

Although some such objects such as sockets and terminals (2) have special functions of their own, it would not be practical to create functions for all these cases.

Instead these minor operations, known as IOCTLs, are assigned code numbers and multiplexed through the ioctl function, defined in sys/ioctl.h. The code numbers themselves are defined in many different headers.

Function: int ioctl (int filedes, int command, ...)

The ioctl function performs the generic I/O operation command on filedes.

A third argument is usually present, either a single number or a pointer to a structure. The meaning of this argument, the returned value, and any error codes depends upon the command used. Often @math{-1} is returned for a failure.

On some systems, IOCTLs used by different devices share the same numbers. Thus, although use of an inappropriate IOCTL usually only produces an error, you should not attempt to use device-specific IOCTLs on an unknown device.

Most IOCTLs are OS-specific and/or only used in special system utilities, and are thus beyond the scope of this document. For an example of the use of an IOCTL, see section Out-of-Band Data.
File System Interface

This chapter describes the GNU C library's functions for manipulating files. Unlike the input and output functions (see section Input/Output on Streams; see section Low-Level Input/Output), these functions are concerned with operating on the files themselves rather than on their contents.

Among the facilities described in this chapter are functions for examining or modifying directories, functions for renaming and deleting files, and functions for examining and setting file attributes such as access permissions and modification times.

Working Directory

Each process has associated with it a directory, called its current working directory or simply working directory, that is used in the resolution of relative file names (see section File Name Resolution).

When you log in and begin a new session, your working directory is initially set to the home directory associated with your login account in the system user database. You can find any user's home directory using the getpwuid or getpwnam functions; see section User Database.

Users can change the working directory using shell commands like cd. The functions described in this section are the primitives used by those commands and by other programs for examining and changing the working directory.

Prototypes for these functions are declared in the header file `unistd.h'.

Function: char * getcwd (char *buffer, size_t size)
The getcwd function returns an absolute file name representing the current working directory, storing it in the character array buffer that you provide. The size argument is how you tell the system the allocation size of buffer.

The GNU library version of this function also permits you to specify a null pointer for the buffer argument. Then getcwd allocates a buffer automatically, as with malloc (see section Unconstrained Allocation). If the size is greater than zero, then the buffer is that large; otherwise, the buffer is as large as necessary to hold the result.

The return value is buffer on success and a null pointer on failure. The following errno error conditions are defined for this function:

EINVAL
The size argument is zero and buffer is not a null pointer.
ERANGE
The size argument is less than the length of the working directory name. You need to allocate a bigger array and try again.
EACCES
Permission to read or search a component of the file name was denied.
You could implement the behavior of GNU's getcwd (NULL, 0) using only the standard behavior of getcwd:
char *
gnu_getcwd ()
{
  size_t size = 100;

  while (1)
    {
      char *buffer = (char *) xmalloc (size);
      if (getcwd (buffer, size) == buffer)
    return buffer;
      free (buffer);
      if (errno != ERANGE)
        return 0;
      size *= 2;
    }
}
See section Examples of malloc, for information about xmalloc, which is not a library function but is a customary name used in most GNU software.

Deprecated Function: char * getwd (char *buffer)
This is similar to getcwd, but has no way to specify the size of the buffer. The GNU library provides getwd only for backwards compatibility with BSD.

The buffer argument should be a pointer to an array at least PATH_MAX bytes long (see section Limits on File System Capacity). In the GNU system there is no limit to the size of a file name, so this is not necessarily enough space to contain the directory name. That is why this function is deprecated.

Function: char * get_current_dir_name (void)
This get_current_dir_name function is bascially equivalent to getcwd (NULL, 0). The only difference is that the value of the PWD variable is returned if this value is correct. This is a subtle difference which is visible if the path described by the PWD value is using one or more symbol links in which case the value returned by getcwd can resolve the symbol links and therefore yield a different result.

This function is a GNU extension.

Function: int chdir (const char *filename)
This function is used to set the process's working directory to filename.

The normal, successful return value from chdir is 0. A value of -1 is returned to indicate an error. The errno error conditions defined for this function are the usual file name syntax errors (see section File Name Errors), plus ENOTDIR if the file filename is not a directory.

Function: int fchdir (int filedes)
This function is used to set the process's working directory to directory associated with the file descriptor filedes.

The normal, successful return value from fchdir is 0. A value of -1 is returned to indicate an error. The following errno error conditions are defined for this function:

EACCES
Read permission is denied for the directory named by dirname.
EBADF
The filedes argument is not a valid file descriptor.
ENOTDIR
The file descriptor filedes is not associated with a directory.
EINTR
The function call was interrupt by a signal.
EIO
An I/O error occurred.
Accessing Directories

The facilities described in this section let you read the contents of a directory file. This is useful if you want your program to list all the files in a directory, perhaps as part of a menu.

The opendir function opens a directory stream whose elements are directory entries. You use the readdir function on the directory stream to retrieve these entries, represented as struct dirent objects. The name of the file for each entry is stored in the d_name member of this structure. There are obvious parallels here to the stream facilities for ordinary files, described in section Input/Output on Streams.

Format of a Directory Entry

This section describes what you find in a single directory entry, as you might obtain it from a directory stream. All the symbols are declared in the header file `dirent.h'.

Data Type: struct dirent
This is a structure type used to return information about directory entries. It contains the following fields:

char d_name[]
This is the null-terminated file name component. This is the only field you can count on in all POSIX systems.
ino_t d_fileno
This is the file serial number. For BSD compatibility, you can also refer to this member as d_ino. In the GNU system and most POSIX systems, for most files this the same as the st_ino member that stat will return for the file. See section File Attributes.
unsigned char d_namlen
This is the length of the file name, not including the terminating null character. Its type is unsigned char because that is the integer type of the appropriate size
unsigned char d_type
This is the type of the file, possibly unknown. The following constants are defined for its value:
DT_UNKNOWN
The type is unknown. On some systems this is the only value returned.
DT_REG
A regular file.
DT_DIR
A directory.
DT_FIFO
A named pipe, or FIFO. See section FIFO Special Files.
DT_SOCK
A local-domain socket.
DT_CHR
A character device.
DT_BLK
A block device. This member is a BSD extension. The symbol _DIRENT_HAVE_D_TYPE is defined if this member is available. On systems where it is used, it corresponds to the file type bits in the st_mode member of struct statbuf. If the value cannot be determine the member value is DT_UNKNOWN. These two macros convert between d_type values and st_mode values:
Function: int IFTODT (mode_t mode)
This returns the d_type value corresponding to mode.
Function: mode_t DTTOIF (int dtype)
This returns the st_mode value corresponding to dtype.
This structure may contain additional members in the future. Their availability is always announced in the compilation environment by a macro names _DIRENT_HAVE_D_xxx where xxx is replaced by the name of the new member. For instance, the member d_reclen available on some systems is announced through the macro _DIRENT_HAVE_D_RECLEN.

When a file has multiple names, each name has its own directory entry. The only way you can tell that the directory entries belong to a single file is that they have the same value for the d_fileno field.

File attributes such as size, modification times etc., are part of the file itself, not of any particular directory entry. See section File Attributes.

Opening a Directory Stream

This section describes how to open a directory stream. All the symbols are declared in the header file `dirent.h'.

Data Type: DIR
The DIR data type represents a directory stream.

You shouldn't ever allocate objects of the struct dirent or DIR data types, since the directory access functions do that for you. Instead, you refer to these objects using the pointers returned by the following functions.

Function: DIR * opendir (const char *dirname)
The opendir function opens and returns a directory stream for reading the directory whose file name is dirname. The stream has type DIR *.

If unsuccessful, opendir returns a null pointer. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES
Read permission is denied for the directory named by dirname.
EMFILE
The process has too many files open.
ENFILE
The entire system, or perhaps the file system which contains the directory, cannot support any additional open files at the moment. (This problem cannot happen on the GNU system.)
The DIR type is typically implemented using a file descriptor, and the opendir function in terms of the open function. See section Low-Level Input/Output. Directory streams and the underlying file descriptors are closed on exec (see section Executing a File).

In some situations it can be desirable to get hold of the file descriptor which is created by the opendir call. For instance, to switch the current working directory to the directory just read the fchdir function could be used. Historically the DIR type was exposed and programs could access the fields. This does not happen in the GNU C library. Instead a separate function is provided to allow access.

Function: int dirfd (DIR *dirstream)
The function dirfd returns the file descriptor associated with the directory stream dirstream. This descriptor can be used until the directory is closed with closedir. If the directory stream implementation is not using file descriptors the return value is -1.

Reading and Closing a Directory Stream

This section describes how to read directory entries from a directory stream, and how to close the stream when you are done with it. All the symbols are declared in the header file `dirent.h'.

Function: struct dirent * readdir (DIR *dirstream)
This function reads the next entry from the directory. It normally returns a pointer to a structure containing information about the file. This structure is statically allocated and can be rewritten by a subsequent call.

Portability Note: On some systems readdir may not return entries for `.' and `..', even though these are always valid file names in any directory. See section File Name Resolution.

If there are no more entries in the directory or an error is detected, readdir returns a null pointer. The following errno error conditions are defined for this function:

EBADF
The dirstream argument is not valid.
readdir is not thread safe. Multiple threads using readdir on the same dirstream may overwrite the return value. Use readdir_r when this is critical.

Function: int readdir_r (DIR *dirstream, struct dirent *entry, struct dirent **result)
This function is the reentrant version of readdir. Like readdir it returns the next entry from the directory. But to prevent conflicts between simultaneously running threads the result is not stored in statically allocated memory. Instead the argument entry points to a place to store the result.

The return value is 0 in case the next entry was read successfully. In this case a pointer to the result is returned in *result. It is not required that *result is the same as entry. If something goes wrong while executing readdir_r the function returns a value indicating the error (as described for readdir).

If there are no more directory entries, readdir_r's return value is 0, and *result is set to NULL.

Portability Note: On some systems readdir_r may not return a NUL terminated string for the file name, even when there is no d_reclen field in struct dirent and the file name is the maximum allowed size. Modern systems all have the d_reclen field, and on old systems multi-threading is not critical. In any case there is no such problem with the readdir function, so that even on systems without the d_reclen member one could use multiple threads by using external locking.

It is also important to look at the definition of the struct dirent type. Simply passing a pointer to an object of this type for the second parameter of readdir_r might not be enough. Some systems don't define the d_name element sufficiently long. In this case the user has to provide additional space. There must be room for at least NAME_MAX + 1 characters in the d_name array. Code to call readdir_r could look like this:
  union
  {
    struct dirent d;
    char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
  } u;

  if (readdir_r (dir, &u.d, &res) == 0)
    ...
To support large filesystems on 32-bit machines there are LFS variants of the last two functions.

Function: struct dirent64 * readdir64 (DIR *dirstream)
The readdir64 function is just like the readdir function except that it returns a pointer to a record of type struct dirent64. Some of the members of this data type (notably d_ino) might have a different size to allow large filesystems.

In all other aspects this function is equivalent to readdir.

Function: int readdir64_r (DIR *dirstream, struct dirent64 *entry, struct dirent64 **result)
The readdir64_r function is equivalent to the readdir_r function except that it takes parameters of base type struct dirent64 instead of struct dirent in the second and third position. The same precautions mentioned in the documentation of readdir_r also apply here.

Function: int closedir (DIR *dirstream)
This function closes the directory stream dirstream. It returns 0 on success and -1 on failure.

The following errno error conditions are defined for this function:

EBADF
The dirstream argument is not valid.
Simple Program to List a Directory

Here's a simple program that prints the names of the files in the current working directory:
#include <stddef.h>
#include <stdio.h>
#include <sys/types.h>
#include <dirent.h>

int
main (void)
{
  DIR *dp;
  struct dirent *ep;

  dp = opendir ("./");
  if (dp != NULL)
    {
      while (ep = readdir (dp))
        puts (ep->d_name);
      (void) closedir (dp);
    }
  else
    puts ("Couldn't open the directory.");

  return 0;
}
The order in which files appear in a directory tends to be fairly random. A more useful program would sort the entries (perhaps by alphabetizing them) before printing them; see section Scanning the Content of a Directory, and section Array Sort Function.

Random Access in a Directory Stream

This section describes how to reread parts of a directory that you have already read from an open directory stream. All the symbols are declared in the header file `dirent.h'.

Function: void rewinddir (DIR *dirstream)
The rewinddir function is used to reinitialize the directory stream dirstream, so that if you call readdir it returns information about the first entry in the directory again. This function also notices if files have been added or removed to the directory since it was opened with opendir. (Entries for these files might or might not be returned by readdir if they were added or removed since you last called opendir or rewinddir.)

Function: off_t telldir (DIR *dirstream)
The telldir function returns the file position of the directory stream dirstream. You can use this value with seekdir to restore the directory stream to that position.

Function: void seekdir (DIR *dirstream, off_t pos)
The seekdir function sets the file position of the directory stream dirstream to pos. The value pos must be the result of a previous call to telldir on this particular stream; closing and reopening the directory can invalidate values returned by telldir.

Scanning the Content of a Directory

A higher-level interface to the directory handling functions is the scandir function. With its help one can select a subset of the entries in a directory, possibly sort them and get a list of names as the result.

Function: int scandir (const char *dir, struct dirent ***namelist, int (*selector) (const struct dirent *), int (*cmp) (const void *, const void *))

The scandir function scans the contents of the directory selected by dir. The result in *namelist is an array of pointers to structure of type struct dirent which describe all selected directory entries and which is allocated using malloc. Instead of always getting all directory entries returned, the user supplied function selector can be used to decide which entries are in the result. Only the entries for which selector returns a non-zero value are selected.

Finally the entries in *namelist are sorted using the user-supplied function cmp. The arguments passed to the cmp function are of type struct dirent **, therefore one cannot directly use the strcmp or strcoll functions; instead see the functions alphasort and versionsort below.

The return value of the function is the number of entries placed in *namelist. If it is -1 an error occurred (either the directory could not be opened for reading or the malloc call failed) and the global variable errno contains more information on the error.

As described above the fourth argument to the scandir function must be a pointer to a sorting function. For the convenience of the programmer the GNU C library contains implementations of functions which are very helpful for this purpose.

Function: int alphasort (const void *a, const void *b)
The alphasort function behaves like the strcoll function (see section String/Array Comparison). The difference is that the arguments are not string pointers but instead they are of type struct dirent **.

The return value of alphasort is less than, equal to, or greater than zero depending on the order of the two entries a and b.

Function: int versionsort (const void *a, const void *b)
The versionsort function is like alphasort except that it uses the strverscmp function internally.

If the filesystem supports large files we cannot use the scandir anymore since the dirent structure might not able to contain all the information. The LFS provides the new type struct dirent64. To use this we need a new function.

Function: int scandir64 (const char *dir, struct dirent64 ***namelist, int (*selector) (const struct dirent64 *), int (*cmp) (const void *, const void *))
The scandir64 function works like the scandir function except that the directory entries it returns are described by elements of type struct dirent64. The function pointed to by selector is again used to select the desired entries, except that selector now must point to a function which takes a struct dirent64 * parameter.

Similarly the cmp function should expect its two arguments to be of type struct dirent64 **.

As cmp is now a function of a different type, the functions alphasort and versionsort cannot be supplied for that argument. Instead we provide the two replacement functions below.

Function: int alphasort64 (const void *a, const void *b)
The alphasort64 function behaves like the strcoll function (see section String/Array Comparison). The difference is that the arguments are not string pointers but instead they are of type struct dirent64 **.

Return value of alphasort64 is less than, equal to, or greater than zero depending on the order of the two entries a and b.

Function: int versionsort64 (const void *a, const void *b)
The versionsort64 function is like alphasort64, excepted that it uses the strverscmp function internally.

It is important not to mix the use of scandir and the 64-bit comparison functions or vice versa. There are systems on which this works but on others it will fail miserably.

Simple Program to List a Directory, Mark II

Here is a revised version of the directory lister found above (see section Simple Program to List a Directory). Using the scandir function we can avoid the functions which work directly with the directory contents. After the call the returned entries are available for direct use.
#include <stdio.h>
#include <dirent.h>

static int
one (struct dirent *unused)
{
  return 1;
}

int
main (void)
{
  struct dirent **eps;
  int n;

  n = scandir ("./", &eps, one, alphasort);
  if (n >= 0)
    {
      int cnt;
      for (cnt = 0; cnt < n; ++cnt)
        puts (eps[cnt]->d_name);
    }
  else
    perror ("Couldn't open the directory");

  return 0;
}
Note the simple selector function in this example. Since we want to see all directory entries we always return 1.

Working with Directory Trees

The functions described so far for handling the files in a directory have allowed you to either retrieve the information bit by bit, or to process all the files as a group (see scandir). Sometimes it is useful to process whole hierarchies of directories and their contained files. The X/Open specification defines two functions to do this. The simpler form is derived from an early definition in System V systems and therefore this function is available on SVID-derived systems. The prototypes and required definitions can be found in the `ftw.h' header.

There are four functions in this family: ftw, nftw and their 64-bit counterparts ftw64 and nftw64. These functions take as one of their arguments a pointer to a callback function of the appropriate type.

Data Type: __ftw_func_t
int (*) (const char *, const struct stat *, int)
The type of callback functions given to the ftw function. The first parameter points to the file name, the second parameter to an object of type struct stat which is filled in for the file named in the first parameter.

The last parameter is a flag giving more information about the current file. It can have the following values:

FTW_F
The item is either a normal file or a file which does not fit into one of the following categories. This could be special files, sockets etc.
FTW_D
The item is a directory.
FTW_NS
The stat call failed and so the information pointed to by the second paramater is invalid.
FTW_DNR
The item is a directory which cannot be read.
FTW_SL
The item is a symbolic link. Since symbolic links are normally followed seeing this value in a ftw callback function means the referenced file does not exist. The situation for nftw is different. This value is only available if the program is compiled with _BSD_SOURCE or _XOPEN_EXTENDED defined before including the first header. The original SVID systems do not have symbolic links.
If the sources are compiled with _FILE_OFFSET_BITS == 64 this type is in fact __ftw64_func_t since this mode changes struct stat to be struct stat64.

For the LFS interface and for use in the function ftw64, the header `ftw.h' defines another function type.

Data Type: __ftw64_func_t
int (*) (const char *, const struct stat64 *, int)
This type is used just like __ftw_func_t for the callback function, but this time is called from ftw64. The second parameter to the function is a pointer to a variable of type struct stat64 which is able to represent the larger values.

Data Type: __nftw_func_t
int (*) (const char *, const struct stat *, int, struct FTW *)
The first three arguments are the same as for the __ftw_func_t type. However for the third argument some additional values are defined to allow finer differentiation:
FTW_DP
The current item is a directory and all subdirectories have already been visited and reported. This flag is returned instead of FTW_D if the FTW_DEPTH flag is passed to nftw (see below).
FTW_SLN
The current item is a stale symbolic link. The file it points to does not exist.
The last parameter of the callback function is a pointer to a structure with some extra information as described below.

If the sources are compiled with _FILE_OFFSET_BITS == 64 this type is in fact __nftw64_func_t since this mode changes struct stat to be struct stat64.

For the LFS interface there is also a variant of this data type available which has to be used with the nftw64 function.

Data Type: __nftw64_func_t
int (*) (const char *, const struct stat64 *, int, struct FTW *)
This type is used just like __nftw_func_t for the callback function, but this time is called from nftw64. The second parameter to the function is this time a pointer to a variable of type struct stat64 which is able to represent the larger values.

Data Type: struct FTW
The information contained in this structure helps in interpreting the name parameter and gives some information about the current state of the traversal of the directory hierarchy.

int base
The value is the offset into the string passed in the first parameter to the callback function of the beginning of the file name. The rest of the string is the path of the file. This information is especially important if the FTW_CHDIR flag was set in calling nftw since then the current directory is the one the current item is found in.
int level
Whilst processing, the code tracks how many directories down it has gone to find the current file. This nesting level starts at @math{0} for files in the initial directory (or is zero for the initial file if a file was passed).

Function: int ftw (const char *filename, __ftw_func_t func, int descriptors)
The ftw function calls the callback function given in the parameter func for every item which is found in the directory specified by filename and all directories below. The function follows symbolic links if necessary but does not process an item twice. If filename is not a directory then it itself is the only object returned to the callback function.

The file name passed to the callback function is constructed by taking the filename parameter and appending the names of all passed directories and then the local file name. So the callback function can use this parameter to access the file. ftw also calls stat for the file and passes that information on to the callback function. If this stat call was not successful the failure is indicated by setting the third argument of the callback function to FTW_NS. Otherwise it is set according to the description given in the account of __ftw_func_t above.

The callback function is expected to return @math{0} to indicate that no error occurred and that processing should continue. If an error occurred in the callback function or it wants ftw to return immediately, the callback function can return a value other than @math{0}. This is the only correct way to stop the function. The program must not use setjmp or similar techniques to continue from another place. This would leave resources allocated by the ftw function unfreed.

The descriptors parameter to ftw specifies how many file descriptors it is allowed to consume. The function runs faster the more descriptors it can use. For each level in the directory hierarchy at most one descriptor is used, but for very deep ones any limit on open file descriptors for the process or the system may be exceeded. Moreover, file descriptor limits in a multi-threaded program apply to all the threads as a group, and therefore it is a good idea to supply a reasonable limit to the number of open descriptors.

The return value of the ftw function is @math{0} if all callback function calls returned @math{0} and all actions performed by the ftw succeeded. If a function call failed (other than calling stat on an item) the function returns @math{-1}. If a callback function returns a value other than @math{0} this value is returned as the return value of ftw.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact ftw64, i.e. the LFS interface transparently replaces the old interface.

Function: int ftw64 (const char *filename, __ftw64_func_t func, int descriptors)
This function is similar to ftw but it can work on filesystems with large files. File information is reported using a variable of type struct stat64 which is passed by reference to the callback function.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is available under the name ftw and transparently replaces the old implementation.

Function: int nftw (const char *filename, __nftw_func_t func, int descriptors, int flag)
The nftw function works like the ftw functions. They call the callback function func for all items found in the directory filename and below. At most descriptors file descriptors are consumed during the nftw call.

One difference is that the callback function is of a different type. It is of type struct FTW * and provides the callback function with the extra information described above.

A second difference is that nftw takes a fourth argument, which is @math{0} or a bitwise-OR combination of any of the following values.

FTW_PHYS
While traversing the directory symbolic links are not followed. Instead symbolic links are reported using the FTW_SL value for the type parameter to the callback function. If the file referenced by a symbolic link does not exist FTW_SLN is returned instead.
FTW_MOUNT
The callback function is only called for items which are on the same mounted filesystem as the directory given by the filename parameter to nftw.
FTW_CHDIR
If this flag is given the current working directory is changed to the directory of the reported object before the callback function is called. When ntfw finally returns the current directory is restored to its original value.
FTW_DEPTH
If this option is specified then all subdirectories and files within them are processed before processing the top directory itself (depth-first processing). This also means the type flag given to the callback function is FTW_DP and not FTW_D.
The return value is computed in the same way as for ftw. nftw returns @math{0} if no failures occurred and all callback functions returned @math{0}. In case of internal errors, such as memory problems, the return value is @math{-1} and errno is set accordingly. If the return value of a callback invocation was non-zero then that value is returned.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact nftw64, i.e. the LFS interface transparently replaces the old interface.

Function: int nftw64 (const char *filename, __nftw64_func_t func, int descriptors, int flag)
This function is similar to nftw but it can work on filesystems with large files. File information is reported using a variable of type struct stat64 which is passed by reference to the callback function.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is available under the name nftw and transparently replaces the old implementation.

Hard Links

In POSIX systems, one file can have many names at the same time. All of the names are equally real, and no one of them is preferred to the others.

To add a name to a file, use the link function. (The new name is also called a hard link to the file.) Creating a new link to a file does not copy the contents of the file; it simply makes a new name by which the file can be known, in addition to the file's existing name or names.

One file can have names in several directories, so the organization of the file system is not a strict hierarchy or tree.

In most implementations, it is not possible to have hard links to the same file in multiple file systems. link reports an error if you try to make a hard link to the file from another file system when this cannot be done.

The prototype for the link function is declared in the header file `unistd.h'.

Function: int link (const char *oldname, const char *newname)
The link function makes a new link to the existing file named by oldname, under the new name newname.

This function returns a value of 0 if it is successful and -1 on failure. In addition to the usual file name errors (see section File Name Errors) for both oldname and newname, the following errno error conditions are defined for this function:

EACCES
You are not allowed to write to the directory in which the new link is to be written.
EEXIST
There is already a file named newname. If you want to replace this link with a new link, you must remove the old link explicitly first.
EMLINK
There are already too many links to the file named by oldname. (The maximum number of links to a file is LINK_MAX; see section Limits on File System Capacity.)
ENOENT
The file named by oldname doesn't exist. You can't make a link to a file that doesn't exist.
ENOSPC
The directory or file system that would contain the new link is full and cannot be extended.
EPERM
In the GNU system and some others, you cannot make links to directories. Many systems allow only privileged users to do so. This error is used to report the problem.
EROFS
The directory containing the new link can't be modified because it's on a read-only file system.
EXDEV
The directory specified in newname is on a different file system than the existing file.
EIO
A hardware error occurred while trying to read or write the to filesystem.
Symbolic Links

The GNU system supports soft links or symbolic links. This is a kind of "file" that is essentially a pointer to another file name. Unlike hard links, symbolic links can be made to directories or across file systems with no restrictions. You can also make a symbolic link to a name which is not the name of any file. (Opening this link will fail until a file by that name is created.) Likewise, if the symbolic link points to an existing file which is later deleted, the symbolic link continues to point to the same file name even though the name no longer names any file.

The reason symbolic links work the way they do is that special things happen when you try to open the link. The open function realizes you have specified the name of a link, reads the file name contained in the link, and opens that file name instead. The stat function likewise operates on the file that the symbolic link points to, instead of on the link itself.

By contrast, other operations such as deleting or renaming the file operate on the link itself. The functions readlink and lstat also refrain from following symbolic links, because their purpose is to obtain information about the link. link, the function that makes a hard link, does too. It makes a hard link to the symbolic link, which one rarely wants.

Some systems have for some functions operating on files have a limit on how many symbolic links are followed when resolving a path name. The limit if it exists is published in the `sys/param.h' header file.

Macro: int MAXSYMLINKS

The macro MAXSYMLINKS specifies how many symlinks some function will follow before returning ELOOP. Not all functions behave the same and this value is not the same a that returned for _SC_SYMLOOP by sysconf. In fact, the sysconf result can indicate that there is no fixed limit although MAXSYMLINKS exists and has a finite value.

Prototypes for most of the functions listed in this section are in `unistd.h'.

Function: int symlink (const char *oldname, const char *newname)
The symlink function makes a symbolic link to oldname named newname.

The normal return value from symlink is 0. A return value of -1 indicates an error. In addition to the usual file name syntax errors (see section File Name Errors), the following errno error conditions are defined for this function:

EEXIST
There is already an existing file named newname.
EROFS
The file newname would exist on a read-only file system.
ENOSPC
The directory or file system cannot be extended to make the new link.
EIO
A hardware error occurred while reading or writing data on the disk.

Function: int readlink (const char *filename, char *buffer, size_t size)
The readlink function gets the value of the symbolic link filename. The file name that the link points to is copied into buffer. This file name string is not null-terminated; readlink normally returns the number of characters copied. The size argument specifies the maximum number of characters to copy, usually the allocation size of buffer.

If the return value equals size, you cannot tell whether or not there was room to return the entire name. So make a bigger buffer and call readlink again. Here is an example:
char *
readlink_malloc (char *filename)
{
  int size = 100;

  while (1)
    {
      char *buffer = (char *) xmalloc (size);
      int nchars = readlink (filename, buffer, size);
      if (nchars < size)
        return buffer;
      free (buffer);
      size *= 2;
    }
}
A value of -1 is returned in case of error. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EINVAL
The named file is not a symbolic link.
EIO
A hardware error occurred while reading or writing data on the disk.
In some situations it is desirable to resolve all the to get the real name of a file where no prefix names a symbolic link which is followed and no filename in the path is . or ... This is for instance desirable if files have to be compare in which case different names can refer to the same inode.

Function: char * canonicalize_file_name (const char *name)

The canonicalize_file_name function returns the absolute name of the file named by name which contains no ., .. components nor any repeated path separators (/) or symlinks. The result is passed back as the return value of the function in a block of memory allocated with malloc. If the result is not used anymore the memory should be freed with a call to free.

In any of the path components except the last one is missing the function returns a NULL pointer. This is also what is returned if the length of the path reaches or exceeds PATH_MAX characters. In any case errno is set accordingly.

ENAMETOOLONG
The resulting path is too long. This error only occurs on systems which have a limit on the file name length.
EACCES
At least one of the path components is not readable.
ENOENT
The input file name is empty.
ENOENT
At least one of the path components does not exist.
ELOOP
More than MAXSYMLINKS many symlinks have been followed.
This function is a GNU extension and is declared in `stdlib.h'.

The Unix standard includes a similar function which differs from canonicalize_file_name in that the user has to provide the buffer where the result is placed in.

Function: char * realpath (const char *restrict name, char *restrict resolved)

The realpath function behaves just like canonicalize_file_name but instead of allocating a buffer for the result it is placed in the buffer pointed to by resolved.

One other difference is that the buffer resolved will contain the part of the path component which does not exist or is not readable if the function returns NULL and errno is set to EACCES or ENOENT.

This function is declared in `stdlib.h'.

The advantage of using this function is that it is more widely available. The drawback is that it reports failures for long path on systems which have no limits on the file name length.

Deleting Files

You can delete a file with unlink or remove.

Deletion actually deletes a file name. If this is the file's only name, then the file is deleted as well. If the file has other remaining names (see section Hard Links), it remains accessible under those names.

Function: int unlink (const char *filename)
The unlink function deletes the file name filename. If this is a file's sole name, the file itself is also deleted. (Actually, if any process has the file open when this happens, deletion is postponed until all processes have closed the file.)

The function unlink is declared in the header file `unistd.h'.

This function returns 0 on successful completion, and -1 on error. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES
Write permission is denied for the directory from which the file is to be removed, or the directory has the sticky bit set and you do not own the file.
EBUSY
This error indicates that the file is being used by the system in such a way that it can't be unlinked. For example, you might see this error if the file name specifies the root directory or a mount point for a file system.
ENOENT
The file name to be deleted doesn't exist.
EPERM
On some systems unlink cannot be used to delete the name of a directory, or at least can only be used this way by a privileged user. To avoid such problems, use rmdir to delete directories. (In the GNU system unlink can never delete the name of a directory.)
EROFS
The directory containing the file name to be deleted is on a read-only file system and can't be modified.

Function: int rmdir (const char *filename)
The rmdir function deletes a directory. The directory must be empty before it can be removed; in other words, it can only contain entries for `.' and `..'.

In most other respects, rmdir behaves like unlink. There are two additional errno error conditions defined for rmdir:

ENOTEMPTY

EEXIST
The directory to be deleted is not empty.
These two error codes are synonymous; some systems use one, and some use the other. The GNU system always uses ENOTEMPTY.

The prototype for this function is declared in the header file `unistd.h'.

Function: int remove (const char *filename)
This is the ISO C function to remove a file. It works like unlink for files and like rmdir for directories. remove is declared in `stdio.h'.

Renaming Files

The rename function is used to change a file's name.

Function: int rename (const char *oldname, const char *newname)
The rename function renames the file oldname to newname. The file formerly accessible under the name oldname is afterwards accessible as newname instead. (If the file had any other names aside from oldname, it continues to have those names.)

The directory containing the name newname must be on the same file system as the directory containing the name oldname.

One special case for rename is when oldname and newname are two names for the same file. The consistent way to handle this case is to delete oldname. However, in this case POSIX requires that rename do nothing and report success--which is inconsistent. We don't know what your operating system will do.

If oldname is not a directory, then any existing file named newname is removed during the renaming operation. However, if newname is the name of a directory, rename fails in this case.

If oldname is a directory, then either newname must not exist or it must name a directory that is empty. In the latter case, the existing directory named newname is deleted first. The name newname must not specify a subdirectory of the directory oldname which is being renamed.

One useful feature of rename is that the meaning of newname changes "atomically" from any previously existing file by that name to its new meaning (i.e. the file that was called oldname). There is no instant at which newname is non-existent "in between" the old meaning and the new meaning. If there is a system crash during the operation, it is possible for both names to still exist; but newname will always be intact if it exists at all.

If rename fails, it returns -1. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES
One of the directories containing newname or oldname refuses write permission; or newname and oldname are directories and write permission is refused for one of them.
EBUSY
A directory named by oldname or newname is being used by the system in a way that prevents the renaming from working. This includes directories that are mount points for filesystems, and directories that are the current working directories of processes.
ENOTEMPTY

EEXIST
The directory newname isn't empty. The GNU system always returns ENOTEMPTY for this, but some other systems return EEXIST.
EINVAL
oldname is a directory that contains newname.
EISDIR
newname is a directory but the oldname isn't.
EMLINK
The parent directory of newname would have too many links (entries).
ENOENT
The file oldname doesn't exist.
ENOSPC
The directory that would contain newname has no room for another entry, and there is no space left in the file system to expand it.
EROFS
The operation would involve writing to a directory on a read-only file system.
EXDEV
The two file names newname and oldname are on different file systems.
Creating Directories

Directories are created with the mkdir function. (There is also a shell command mkdir which does the same thing.)

Function: int mkdir (const char *filename, mode_t mode)
The mkdir function creates a new, empty directory with name filename.

The argument mode specifies the file permissions for the new directory file. See section The Mode Bits for Access Permission, for more information about this.

A return value of 0 indicates successful completion, and -1 indicates failure. In addition to the usual file name syntax errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES
Write permission is denied for the parent directory in which the new directory is to be added.
EEXIST
A file named filename already exists.
EMLINK
The parent directory has too many links (entries). Well-designed file systems never report this error, because they permit more links than your disk could possibly hold. However, you must still take account of the possibility of this error, as it could result from network access to a file system on another machine.
ENOSPC
The file system doesn't have enough room to create the new directory.
EROFS
The parent directory of the directory being created is on a read-only file system and cannot be modified.
To use this function, your program should include the header file `sys/stat.h'.

File Attributes

When you issue an `ls -l' shell command on a file, it gives you information about the size of the file, who owns it, when it was last modified, etc. These are called the file attributes, and are associated with the file itself and not a particular one of its names.

This section contains information about how you can inquire about and modify the attributes of a file.

The meaning of the File Attributes

When you read the attributes of a file, they come back in a structure called struct stat. This section describes the names of the attributes, their data types, and what they mean. For the functions to read the attributes of a file, see section Reading the Attributes of a File.

The header file `sys/stat.h' declares all the symbols defined in this section.

Data Type: struct stat
The stat structure type is used to return information about the attributes of a file. It contains at least the following members:

mode_t st_mode
Specifies the mode of the file. This includes file type information (see section Testing the Type of a File) and the file permission bits (see section The Mode Bits for Access Permission).
ino_t st_ino
The file serial number, which distinguishes this file from all other files on the same device.
dev_t st_dev
Identifies the device containing the file. The st_ino and st_dev, taken together, uniquely identify the file. The st_dev value is not necessarily consistent across reboots or system crashes, however.
nlink_t st_nlink
The number of hard links to the file. This count keeps track of how many directories have entries for this file. If the count is ever decremented to zero, then the file itself is discarded as soon as no process still holds it open. Symbolic links are not counted in the total.
uid_t st_uid
The user ID of the file's owner. See section File Owner.
gid_t st_gid
The group ID of the file. See section File Owner.
off_t st_size
This specifies the size of a regular file in bytes. For files that are really devices this field isn't usually meaningful. For symbolic links this specifies the length of the file name the link refers to.
time_t st_atime
This is the last access time for the file. See section File Times.
unsigned long int st_atime_usec
This is the fractional part of the last access time for the file. See section File Times.
time_t st_mtime
This is the time of the last modification to the contents of the file. See section File Times.
unsigned long int st_mtime_usec
This is the fractional part of the time of the last modification to the contents of the file. See section File Times.
time_t st_ctime
This is the time of the last modification to the attributes of the file. See section File Times.
unsigned long int st_ctime_usec
This is the fractional part of the time of the last modification to the attributes of the file. See section File Times.
blkcnt_t st_blocks
This is the amount of disk space that the file occupies, measured in units of 512-byte blocks. The number of disk blocks is not strictly proportional to the size of the file, for two reasons: the file system may use some blocks for internal record keeping; and the file may be sparse--it may have "holes" which contain zeros but do not actually take up space on the disk. You can tell (approximately) whether a file is sparse by comparing this value with st_size, like this:
(st.st_blocks * 512 < st.st_size)
This test is not perfect because a file that is just slightly sparse might not be detected as sparse at all. For practical applications, this is not a problem.
unsigned int st_blksize
The optimal block size for reading of writing this file, in bytes. You might use this size for allocating the buffer space for reading of writing the file. (This is unrelated to st_blocks.)
The extensions for the Large File Support (LFS) require, even on 32-bit machines, types which can handle file sizes up to @math{2^63}. Therefore a new definition of struct stat is necessary.

Data Type: struct stat64
The members of this type are the same and have the same names as those in struct stat. The only difference is that the members st_ino, st_size, and st_blocks have a different type to support larger values.

mode_t st_mode
Specifies the mode of the file. This includes file type information (see section Testing the Type of a File) and the file permission bits (see section The Mode Bits for Access Permission).
ino64_t st_ino
The file serial number, which distinguishes this file from all other files on the same device.
dev_t st_dev
Identifies the device containing the file. The st_ino and st_dev, taken together, uniquely identify the file. The st_dev value is not necessarily consistent across reboots or system crashes, however.
nlink_t st_nlink
The number of hard links to the file. This count keeps track of how many directories have entries for this file. If the count is ever decremented to zero, then the file itself is discarded as soon as no process still holds it open. Symbolic links are not counted in the total.
uid_t st_uid
The user ID of the file's owner. See section File Owner.
gid_t st_gid
The group ID of the file. See section File Owner.
off64_t st_size
This specifies the size of a regular file in bytes. For files that are really devices this field isn't usually meaningful. For symbolic links this specifies the length of the file name the link refers to.
time_t st_atime
This is the last access time for the file. See section File Times.
unsigned long int st_atime_usec
This is the fractional part of the last access time for the file. See section File Times.
time_t st_mtime
This is the time of the last modification to the contents of the file. See section File Times.
unsigned long int st_mtime_usec
This is the fractional part of the time of the last modification to the contents of the file. See section File Times.
time_t st_ctime
This is the time of the last modification to the attributes of the file. See section File Times.
unsigned long int st_ctime_usec
This is the fractional part of the time of the last modification to the attributes of the file. See section File Times.
blkcnt64_t st_blocks
This is the amount of disk space that the file occupies, measured in units of 512-byte blocks.
unsigned int st_blksize
The optimal block size for reading of writing this file, in bytes. You might use this size for allocating the buffer space for reading of writing the file. (This is unrelated to st_blocks.)
Some of the file attributes have special data type names which exist specifically for those attributes. (They are all aliases for well-known integer types that you know and love.) These typedef names are defined in the header file `sys/types.h' as well as in `sys/stat.h'. Here is a list of them.

Data Type: mode_t
This is an integer data type used to represent file modes. In the GNU system, this is equivalent to unsigned int.

Data Type: ino_t
This is an arithmetic data type used to represent file serial numbers. (In Unix jargon, these are sometimes called inode numbers.) In the GNU system, this type is equivalent to unsigned long int.

If the source is compiled with _FILE_OFFSET_BITS == 64 this type is transparently replaced by ino64_t.

Data Type: ino64_t
This is an arithmetic data type used to represent file serial numbers for the use in LFS. In the GNU system, this type is equivalent to unsigned long longint.

When compiling with _FILE_OFFSET_BITS == 64 this type is available under the name ino_t.

Data Type: dev_t
This is an arithmetic data type used to represent file device numbers. In the GNU system, this is equivalent to int.

Data Type: nlink_t
This is an arithmetic data type used to represent file link counts. In the GNU system, this is equivalent to unsigned short int.

Data Type: blkcnt_t
This is an arithmetic data type used to represent block counts. In the GNU system, this is equivalent to unsigned long int.

If the source is compiled with _FILE_OFFSET_BITS == 64 this type is transparently replaced by blkcnt64_t.

Data Type: blkcnt64_t
This is an arithmetic data type used to represent block counts for the use in LFS. In the GNU system, this is equivalent to unsigned long long int.

When compiling with _FILE_OFFSET_BITS == 64 this type is available under the name blkcnt_t.

Reading the Attributes of a File

To examine the attributes of files, use the functions stat, fstat and lstat. They return the attribute information in a struct stat object. All three functions are declared in the header file `sys/stat.h'.

Function: int stat (const char *filename, struct stat *buf)
The stat function returns information about the attributes of the file named by filename in the structure pointed to by buf.

If filename is the name of a symbolic link, the attributes you get describe the file that the link points to. If the link points to a nonexistent file name, then stat fails reporting a nonexistent file.

The return value is 0 if the operation is successful, or -1 on failure. In addition to the usual file name errors (see section File Name Errors, the following errno error conditions are defined for this function:

ENOENT
The file named by filename doesn't exist.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact stat64 since the LFS interface transparently replaces the normal implementation.

Function: int stat64 (const char *filename, struct stat64 *buf)
This function is similar to stat but it is also able to work on files larger then @math{2^31} bytes on 32-bit systems. To be able to do this the result is stored in a variable of type struct stat64 to which buf must point.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name stat and so transparently replaces the interface for small files on 32-bit machines.

Function: int fstat (int filedes, struct stat *buf)
The fstat function is like stat, except that it takes an open file descriptor as an argument instead of a file name. See section Low-Level Input/Output.

Like stat, fstat returns 0 on success and -1 on failure. The following errno error conditions are defined for fstat:

EBADF
The filedes argument is not a valid file descriptor.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact fstat64 since the LFS interface transparently replaces the normal implementation.

Function: int fstat64 (int filedes, struct stat64 *buf)
This function is similar to fstat but is able to work on large files on 32-bit platforms. For large files the file descriptor filedes should be obtained by open64 or creat64. The buf pointer points to a variable of type struct stat64 which is able to represent the larger values.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name fstat and so transparently replaces the interface for small files on 32-bit machines.

Function: int lstat (const char *filename, struct stat *buf)
The lstat function is like stat, except that it does not follow symbolic links. If filename is the name of a symbolic link, lstat returns information about the link itself; otherwise lstat works like stat. See section Symbolic Links.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact lstat64 since the LFS interface transparently replaces the normal implementation.

Function: int lstat64 (const char *filename, struct stat64 *buf)
This function is similar to lstat but it is also able to work on files larger then @math{2^31} bytes on 32-bit systems. To be able to do this the result is stored in a variable of type struct stat64 to which buf must point.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name lstat and so transparently replaces the interface for small files on 32-bit machines.

Testing the Type of a File

The file mode, stored in the st_mode field of the file attributes, contains two kinds of information: the file type code, and the access permission bits. This section discusses only the type code, which you can use to tell whether the file is a directory, socket, symbolic link, and so on. For details about access permissions see section The Mode Bits for Access Permission.

There are two ways you can access the file type information in a file mode. Firstly, for each file type there is a predicate macro which examines a given file mode and returns whether it is of that type or not. Secondly, you can mask out the rest of the file mode to leave just the file type code, and compare this against constants for each of the supported file types.

All of the symbols listed in this section are defined in the header file `sys/stat.h'.

The following predicate macros test the type of a file, given the value m which is the st_mode field returned by stat on that file:

Macro: int S_ISDIR (mode_t m)
This macro returns non-zero if the file is a directory.

Macro: int S_ISCHR (mode_t m)
This macro returns non-zero if the file is a character special file (a device like a terminal).

Macro: int S_ISBLK (mode_t m)
This macro returns non-zero if the file is a block special file (a device like a disk).

Macro: int S_ISREG (mode_t m)
This macro returns non-zero if the file is a regular file.

Macro: int S_ISFIFO (mode_t m)
This macro returns non-zero if the file is a FIFO special file, or a pipe. See section Pipes and FIFOs.

Macro: int S_ISLNK (mode_t m)
This macro returns non-zero if the file is a symbolic link. See section Symbolic Links.

Macro: int S_ISSOCK (mode_t m)
This macro returns non-zero if the file is a socket. See section Sockets.

An alternate non-POSIX method of testing the file type is supported for compatibility with BSD. The mode can be bitwise AND-ed with S_IFMT to extract the file type code, and compared to the appropriate constant. For example,
S_ISCHR (mode)
is equivalent to:
((mode & S_IFMT) == S_IFCHR)
Macro: int S_IFMT
This is a bit mask used to extract the file type code from a mode value.

These are the symbolic names for the different file type codes:

S_IFDIR
This is the file type constant of a directory file.
S_IFCHR
This is the file type constant of a character-oriented device file.
S_IFBLK
This is the file type constant of a block-oriented device file.
S_IFREG
This is the file type constant of a regular file.
S_IFLNK
This is the file type constant of a symbolic link.
S_IFSOCK
This is the file type constant of a socket.
S_IFIFO
This is the file type constant of a FIFO or pipe.
The POSIX.1b standard introduced a few more objects which possibly can be implemented as object in the filesystem. These are message queues, semaphores, and shared memory objects. To allow differentiating these objects from other files the POSIX standard introduces three new test macros. But unlike the other macros it does not take the value of the st_mode field as the parameter. Instead they expect a pointer to the whole struct stat structure.

Macro: int S_TYPEISMQ (struct stat *s)
If the system implement POSIX message queues as distinct objects and the file is a message queue object, this macro returns a non-zero value. In all other cases the result is zero.

Macro: int S_TYPEISSEM (struct stat *s)
If the system implement POSIX semaphores as distinct objects and the file is a semaphore object, this macro returns a non-zero value. In all other cases the result is zero.

Macro: int S_TYPEISSHM (struct stat *s)
If the system implement POSIX shared memory objects as distinct objects and the file is an shared memory object, this macro returns a non-zero value. In all other cases the result is zero.

File Owner

Every file has an owner which is one of the registered user names defined on the system. Each file also has a group which is one of the defined groups. The file owner can often be useful for showing you who edited the file (especially when you edit with GNU Emacs), but its main purpose is for access control.

The file owner and group play a role in determining access because the file has one set of access permission bits for the owner, another set that applies to users who belong to the file's group, and a third set of bits that applies to everyone else. See section How Your Access to a File is Decided, for the details of how access is decided based on this data.

When a file is created, its owner is set to the effective user ID of the process that creates it (see section The Persona of a Process). The file's group ID may be set to either the effective group ID of the process, or the group ID of the directory that contains the file, depending on the system where the file is stored. When you access a remote file system, it behaves according to its own rules, not according to the system your program is running on. Thus, your program must be prepared to encounter either kind of behavior no matter what kind of system you run it on.

You can change the owner and/or group owner of an existing file using the chown function. This is the primitive for the chown and chgrp shell commands.

The prototype for this function is declared in `unistd.h'.

Function: int chown (const char *filename, uid_t owner, gid_t group)
The chown function changes the owner of the file filename to owner, and its group owner to group.

Changing the owner of the file on certain systems clears the set-user-ID and set-group-ID permission bits. (This is because those bits may not be appropriate for the new owner.) Other file permission bits are not changed.

The return value is 0 on success and -1 on failure. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EPERM
This process lacks permission to make the requested change. Only privileged users or the file's owner can change the file's group. On most file systems, only privileged users can change the file owner; some file systems allow you to change the owner if you are currently the owner. When you access a remote file system, the behavior you encounter is determined by the system that actually holds the file, not by the system your program is running on. See section Optional Features in File Support, for information about the _POSIX_CHOWN_RESTRICTED macro.
EROFS
The file is on a read-only file system.

Function: int fchown (int filedes, int owner, int group)
This is like chown, except that it changes the owner of the open file with descriptor filedes.

The return value from fchown is 0 on success and -1 on failure. The following errno error codes are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
EINVAL
The filedes argument corresponds to a pipe or socket, not an ordinary file.
EPERM
This process lacks permission to make the requested change. For details see chmod above.
EROFS
The file resides on a read-only file system.
The Mode Bits for Access Permission

The file mode, stored in the st_mode field of the file attributes, contains two kinds of information: the file type code, and the access permission bits. This section discusses only the access permission bits, which control who can read or write the file. See section Testing the Type of a File, for information about the file type code.

All of the symbols listed in this section are defined in the header file `sys/stat.h'.

These symbolic constants are defined for the file mode bits that control access permission for the file:

S_IRUSR

S_IREAD
Read permission bit for the owner of the file. On many systems this bit is 0400. S_IREAD is an obsolete synonym provided for BSD compatibility.
S_IWUSR

S_IWRITE
Write permission bit for the owner of the file. Usually 0200. S_IWRITE is an obsolete synonym provided for BSD compatibility.
S_IXUSR

S_IEXEC
Execute (for ordinary files) or search (for directories) permission bit for the owner of the file. Usually 0100. S_IEXEC is an obsolete synonym provided for BSD compatibility.
S_IRWXU
This is equivalent to `(S_IRUSR | S_IWUSR | S_IXUSR)'.
S_IRGRP
Read permission bit for the group owner of the file. Usually 040.
S_IWGRP
Write permission bit for the group owner of the file. Usually 020.
S_IXGRP
Execute or search permission bit for the group owner of the file. Usually 010.
S_IRWXG
This is equivalent to `(S_IRGRP | S_IWGRP | S_IXGRP)'.
S_IROTH
Read permission bit for other users. Usually 04.
S_IWOTH
Write permission bit for other users. Usually 02.
S_IXOTH
Execute or search permission bit for other users. Usually 01.
S_IRWXO
This is equivalent to `(S_IROTH | S_IWOTH | S_IXOTH)'.
S_ISUID
This is the set-user-ID on execute bit, usually 04000. See section How an Application Can Change Persona.
S_ISGID
This is the set-group-ID on execute bit, usually 02000. See section How an Application Can Change Persona.
S_ISVTX
This is the sticky bit, usually 01000. For a directory it gives permission to delete a file in that directory only if you own that file. Ordinarily, a user can either delete all the files in a directory or cannot delete any of them (based on whether the user has write permission for the directory). The same restriction applies--you must have both write permission for the directory and own the file you want to delete. The one exception is that the owner of the directory can delete any file in the directory, no matter who owns it (provided the owner has given himself write permission for the directory). This is commonly used for the `/tmp' directory, where anyone may create files but not delete files created by other users. Originally the sticky bit on an executable file modified the swapping policies of the system. Normally, when a program terminated, its pages in core were immediately freed and reused. If the sticky bit was set on the executable file, the system kept the pages in core for a while as if the program were still running. This was advantageous for a program likely to be run many times in succession. This usage is obsolete in modern systems. When a program terminates, its pages always remain in core as long as there is no shortage of memory in the system. When the program is next run, its pages will still be in core if no shortage arose since the last run. On some modern systems where the sticky bit has no useful meaning for an executable file, you cannot set the bit at all for a non-directory. If you try, chmod fails with EFTYPE; see section Assigning File Permissions. Some systems (particularly SunOS) have yet another use for the sticky bit. If the sticky bit is set on a file that is not executable, it means the opposite: never cache the pages of this file at all. The main use of this is for the files on an NFS server machine which are used as the swap area of diskless client machines. The idea is that the pages of the file will be cached in the client's memory, so it is a waste of the server's memory to cache them a second time. With this usage the sticky bit also implies that the filesystem may fail to record the file's modification time onto disk reliably (the idea being that no-one cares for a swap file). This bit is only available on BSD systems (and those derived from them). Therefore one has to use the _BSD_SOURCE feature select macro to get the definition (see section Feature Test Macros).
The actual bit values of the symbols are listed in the table above so you can decode file mode values when debugging your programs. These bit values are correct for most systems, but they are not guaranteed.

Warning: Writing explicit numbers for file permissions is bad practice. Not only is it not portable, it also requires everyone who reads your program to remember what the bits mean. To make your program clean use the symbolic names.

How Your Access to a File is Decided

Recall that the operating system normally decides access permission for a file based on the effective user and group IDs of the process and its supplementary group IDs, together with the file's owner, group and permission bits. These concepts are discussed in detail in section The Persona of a Process.

If the effective user ID of the process matches the owner user ID of the file, then permissions for read, write, and execute/search are controlled by the corresponding "user" (or "owner") bits. Likewise, if any of the effective group ID or supplementary group IDs of the process matches the group owner ID of the file, then permissions are controlled by the "group" bits. Otherwise, permissions are controlled by the "other" bits.

Privileged users, like `root', can access any file regardless of its permission bits. As a special case, for a file to be executable even by a privileged user, at least one of its execute bits must be set.

Assigning File Permissions

The primitive functions for creating files (for example, open or mkdir) take a mode argument, which specifies the file permissions to give the newly created file. This mode is modified by the process's file creation mask, or umask, before it is used.

The bits that are set in the file creation mask identify permissions that are always to be disabled for newly created files. For example, if you set all the "other" access bits in the mask, then newly created files are not accessible at all to processes in the "other" category, even if the mode argument passed to the create function would permit such access. In other words, the file creation mask is the complement of the ordinary access permissions you want to grant.

Programs that create files typically specify a mode argument that includes all the permissions that make sense for the particular file. For an ordinary file, this is typically read and write permission for all classes of users. These permissions are then restricted as specified by the individual user's own file creation mask.

To change the permission of an existing file given its name, call chmod. This function uses the specified permission bits and ignores the file creation mask.

In normal use, the file creation mask is initialized by the user's login shell (using the umask shell command), and inherited by all subprocesses. Application programs normally don't need to worry about the file creation mask. It will automatically do what it is supposed to do.

When your program needs to create a file and bypass the umask for its access permissions, the easiest way to do this is to use fchmod after opening the file, rather than changing the umask. In fact, changing the umask is usually done only by shells. They use the umask function.

The functions in this section are declared in `sys/stat.h'.

Function: mode_t umask (mode_t mask)
The umask function sets the file creation mask of the current process to mask, and returns the previous value of the file creation mask.

Here is an example showing how to read the mask with umask without changing it permanently:
mode_t
read_umask (void)
{
  mode_t mask = umask (0);
  umask (mask);
  return mask;
}
However, it is better to use getumask if you just want to read the mask value, because it is reentrant (at least if you use the GNU operating system).

Function: mode_t getumask (void)
Return the current value of the file creation mask for the current process. This function is a GNU extension.

Function: int chmod (const char *filename, mode_t mode)
The chmod function sets the access permission bits for the file named by filename to mode.

If filename is a symbolic link, chmod changes the permissions of the file pointed to by the link, not those of the link itself.

This function returns 0 if successful and -1 if not. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

ENOENT
The named file doesn't exist.
EPERM
This process does not have permission to change the access permissions of this file. Only the file's owner (as judged by the effective user ID of the process) or a privileged user can change them.
EROFS
The file resides on a read-only file system.
EFTYPE
mode has the S_ISVTX bit (the "sticky bit") set, and the named file is not a directory. Some systems do not allow setting the sticky bit on non-directory files, and some do (and only some of those assign a useful meaning to the bit for non-directory files). You only get EFTYPE on systems where the sticky bit has no useful meaning for non-directory files, so it is always safe to just clear the bit in mode and call chmod again. See section The Mode Bits for Access Permission, for full details on the sticky bit.

Function: int fchmod (int filedes, int mode)
This is like chmod, except that it changes the permissions of the currently open file given by filedes.

The return value from fchmod is 0 on success and -1 on failure. The following errno error codes are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
EINVAL
The filedes argument corresponds to a pipe or socket, or something else that doesn't really have access permissions.
EPERM
This process does not have permission to change the access permissions of this file. Only the file's owner (as judged by the effective user ID of the process) or a privileged user can change them.
EROFS
The file resides on a read-only file system.
Testing Permission to Access a File

In some situations it is desirable to allow programs to access files or devices even if this is not possible with the permissions granted to the user. One possible solution is to set the setuid-bit of the program file. If such a program is started the effective user ID of the process is changed to that of the owner of the program file. So to allow write access to files like `/etc/passwd', which normally can be written only by the super-user, the modifying program will have to be owned by root and the setuid-bit must be set.

But beside the files the program is intended to change the user should not be allowed to access any file to which s/he would not have access anyway. The program therefore must explicitly check whether the user would have the necessary access to a file, before it reads or writes the file.

To do this, use the function access, which checks for access permission based on the process's real user ID rather than the effective user ID. (The setuid feature does not alter the real user ID, so it reflects the user who actually ran the program.)

There is another way you could check this access, which is easy to describe, but very hard to use. This is to examine the file mode bits and mimic the system's own access computation. This method is undesirable because many systems have additional access control features; your program cannot portably mimic them, and you would not want to try to keep track of the diverse features that different systems have. Using access is simple and automatically does whatever is appropriate for the system you are using.

access is only only appropriate to use in setuid programs. A non-setuid program will always use the effective ID rather than the real ID.

The symbols in this section are declared in `unistd.h'.

Function: int access (const char *filename, int how)
The access function checks to see whether the file named by filename can be accessed in the way specified by the how argument. The how argument either can be the bitwise OR of the flags R_OK, W_OK, X_OK, or the existence test F_OK.

This function uses the real user and group IDs of the calling process, rather than the effective IDs, to check for access permission. As a result, if you use the function from a setuid or setgid program (see section How an Application Can Change Persona), it gives information relative to the user who actually ran the program.

The return value is 0 if the access is permitted, and -1 otherwise. (In other words, treated as a predicate function, access returns true if the requested access is denied.)

In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES
The access specified by how is denied.
ENOENT
The file doesn't exist.
EROFS
Write permission was requested for a file on a read-only file system.
These macros are defined in the header file `unistd.h' for use as the how argument to the access function. The values are integer constants.

Macro: int R_OK
Flag meaning test for read permission.

Macro: int W_OK
Flag meaning test for write permission.

Macro: int X_OK
Flag meaning test for execute/search permission.

Macro: int F_OK
Flag meaning test for existence of the file.

File Times

Each file has three time stamps associated with it: its access time, its modification time, and its attribute modification time. These correspond to the st_atime, st_mtime, and st_ctime members of the stat structure; see section File Attributes.

All of these times are represented in calendar time format, as time_t objects. This data type is defined in `time.h'. For more information about representation and manipulation of time values, see section Calendar Time.

Reading from a file updates its access time attribute, and writing updates its modification time. When a file is created, all three time stamps for that file are set to the current time. In addition, the attribute change time and modification time fields of the directory that contains the new entry are updated.

Adding a new name for a file with the link function updates the attribute change time field of the file being linked, and both the attribute change time and modification time fields of the directory containing the new name. These same fields are affected if a file name is deleted with unlink, remove or rmdir. Renaming a file with rename affects only the attribute change time and modification time fields of the two parent directories involved, and not the times for the file being renamed.

Changing the attributes of a file (for example, with chmod) updates its attribute change time field.

You can also change some of the time stamps of a file explicitly using the utime function--all except the attribute change time. You need to include the header file `utime.h' to use this facility.

Data Type: struct utimbuf
The utimbuf structure is used with the utime function to specify new access and modification times for a file. It contains the following members:

time_t actime
This is the access time for the file.
time_t modtime
This is the modification time for the file.

Function: int utime (const char *filename, const struct utimbuf *times)
This function is used to modify the file times associated with the file named filename.

If times is a null pointer, then the access and modification times of the file are set to the current time. Otherwise, they are set to the values from the actime and modtime members (respectively) of the utimbuf structure pointed to by times.

The attribute modification time for the file is set to the current time in either case (since changing the time stamps is itself a modification of the file attributes).

The utime function returns 0 if successful and -1 on failure. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EACCES
There is a permission problem in the case where a null pointer was passed as the times argument. In order to update the time stamp on the file, you must either be the owner of the file, have write permission for the file, or be a privileged user.
ENOENT
The file doesn't exist.
EPERM
If the times argument is not a null pointer, you must either be the owner of the file or be a privileged user.
EROFS
The file lives on a read-only file system.
Each of the three time stamps has a corresponding microsecond part, which extends its resolution. These fields are called st_atime_usec, st_mtime_usec, and st_ctime_usec; each has a value between 0 and 999,999, which indicates the time in microseconds. They correspond to the tv_usec field of a timeval structure; see section High-Resolution Calendar.

The utimes function is like utime, but also lets you specify the fractional part of the file times. The prototype for this function is in the header file `sys/time.h'.

Function: int utimes (const char *filename, struct timeval tvp[2])
This function sets the file access and modification times of the file filename. The new file access time is specified by tvp[0], and the new modification time by tvp[1]. This function comes from BSD.

The return values and error conditions are the same as for the utime function.

File Size

Normally file sizes are maintained automatically. A file begins with a size of @math{0} and is automatically extended when data is written past its end. It is also possible to empty a file completely by an open or fopen call.

However, sometimes it is necessary to reduce the size of a file. This can be done with the truncate and ftruncate functions. They were introduced in BSD Unix. ftruncate was later added to POSIX.1.

Some systems allow you to extend a file (creating holes) with these functions. This is useful when using memory-mapped I/O (see section Memory-mapped I/O), where files are not automatically extended. However, it is not portable but must be implemented if mmap allows mapping of files (i.e., _POSIX_MAPPED_FILES is defined).

Using these functions on anything other than a regular file gives undefined results. On many systems, such a call will appear to succeed, without actually accomplishing anything.

Function: int truncate (const char *filename, off_t length)

The truncate function changes the size of filename to length. If length is shorter than the previous length, data at the end will be lost. The file must be writable by the user to perform this operation.

If length is longer, holes will be added to the end. However, some systems do not support this feature and will leave the file unchanged.

When the source file is compiled with _FILE_OFFSET_BITS == 64 the truncate function is in fact truncate64 and the type off_t has 64 bits which makes it possible to handle files up to @math{2^63} bytes in length.

The return value is @math{0} for success, or @math{-1} for an error. In addition to the usual file name errors, the following errors may occur:

EACCES
The file is a directory or not writable.
EINVAL
length is negative.
EFBIG
The operation would extend the file beyond the limits of the operating system.
EIO
A hardware I/O error occurred.
EPERM
The file is "append-only" or "immutable".
EINTR
The operation was interrupted by a signal.

Function: int truncate64 (const char *name, off64_t length)
This function is similar to the truncate function. The difference is that the length argument is 64 bits wide even on 32 bits machines, which allows the handling of files with sizes up to @math{2^63} bytes.

When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name truncate and so transparently replaces the 32 bits interface.

Function: int ftruncate (int fd, off_t length)

This is like truncate, but it works on a file descriptor fd for an opened file instead of a file name to identify the object. The file must be opened for writing to successfully carry out the operation.

The POSIX standard leaves it implementation defined what happens if the specified new length of the file is bigger than the original size. The ftruncate function might simply leave the file alone and do nothing or it can increase the size to the desired size. In this later case the extended area should be zero-filled. So using ftruncate is no reliable way to increase the file size but if it is possible it is probably the fastest way. The function also operates on POSIX shared memory segments if these are implemented by the system.

ftruncate is especially useful in combination with mmap. Since the mapped region must have a fixed size one cannot enlarge the file by writing something beyond the last mapped page. Instead one has to enlarge the file itself and then remap the file with the new size. The example below shows how this works.

When the source file is compiled with _FILE_OFFSET_BITS == 64 the ftruncate function is in fact ftruncate64 and the type off_t has 64 bits which makes it possible to handle files up to @math{2^63} bytes in length.

The return value is @math{0} for success, or @math{-1} for an error. The following errors may occur:

EBADF
fd does not correspond to an open file.
EACCES
fd is a directory or not open for writing.
EINVAL
length is negative.
EFBIG
The operation would extend the file beyond the limits of the operating system.
EIO
A hardware I/O error occurred.
EPERM
The file is "append-only" or "immutable".
EINTR
The operation was interrupted by a signal.

Function: int ftruncate64 (int id, off64_t length)
This function is similar to the ftruncate function. The difference is that the length argument is 64 bits wide even on 32 bits machines which allows the handling of files with sizes up to @math{2^63} bytes.

When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name ftruncate and so transparently replaces the 32 bits interface.

As announced here is a little example of how to use ftruncate in combination with mmap:
int fd;
void *start;
size_t len;

int
add (off_t at, void *block, size_t size)
{
  if (at + size > len)
    {
      /* Resize the file and remap.  */
      size_t ps = sysconf (_SC_PAGESIZE);
      size_t ns = (at + size + ps - 1) & ~(ps - 1);
      void *np;
      if (ftruncate (fd, ns) < 0)
        return -1;
      np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
      if (np == MAP_FAILED)
        return -1;
      start = np;
      len = ns;
    }
  memcpy ((char *) start + at, block, size);
  return 0;
}
The function add writes a block of memory at an arbitrary position in the file. If the current size of the file is too small it is extended. Note the it is extended by a round number of pages. This is a requirement of mmap. The program has to keep track of the real size, and when it has finished a final ftruncate call should set the real size of the file.

Making Special Files

The mknod function is the primitive for making special files, such as files that correspond to devices. The GNU library includes this function for compatibility with BSD.

The prototype for mknod is declared in `sys/stat.h'.

Function: int mknod (const char *filename, int mode, int dev)
The mknod function makes a special file with name filename. The mode specifies the mode of the file, and may include the various special file bits, such as S_IFCHR (for a character special file) or S_IFBLK (for a block special file). See section Testing the Type of a File.

The dev argument specifies which device the special file refers to. Its exact interpretation depends on the kind of special file being created.

The return value is 0 on success and -1 on error. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EPERM
The calling process is not privileged. Only the superuser can create special files.
ENOSPC
The directory or file system that would contain the new file is full and cannot be extended.
EROFS
The directory containing the new file can't be modified because it's on a read-only file system.
EEXIST
There is already a file named filename. If you want to replace this file, you must remove the old file explicitly first.
Temporary Files

If you need to use a temporary file in your program, you can use the tmpfile function to open it. Or you can use the tmpnam (better: tmpnam_r) function to provide a name for a temporary file and then you can open it in the usual way with fopen.

The tempnam function is like tmpnam but lets you choose what directory temporary files will go in, and something about what their file names will look like. Important for multi-threaded programs is that tempnam is reentrant, while tmpnam is not since it returns a pointer to a static buffer.

These facilities are declared in the header file `stdio.h'.

Function: FILE * tmpfile (void)
This function creates a temporary binary file for update mode, as if by calling fopen with mode "wb+". The file is deleted automatically when it is closed or when the program terminates. (On some other ISO C systems the file may fail to be deleted if the program terminates abnormally).

This function is reentrant.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact tmpfile64, i.e. the LFS interface transparently replaces the old interface.

Function: FILE * tmpfile64 (void)
This function is similar to tmpfile, but the stream it returns a pointer to was opened using tmpfile64. Therefore this stream can be used for files larger then @math{2^31} bytes on 32-bit machines.

Please note that the return type is still FILE *. There is no special FILE type for the LFS interface.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name tmpfile and so transparently replaces the old interface.

Function: char * tmpnam (char *result)
This function constructs and returns a valid file name that does not refer to any existing file. If the result argument is a null pointer, the return value is a pointer to an internal static string, which might be modified by subsequent calls and therefore makes this function non-reentrant. Otherwise, the result argument should be a pointer to an array of at least L_tmpnam characters, and the result is written into that array.

It is possible for tmpnam to fail if you call it too many times without removing previously-created files. This is because the limited length of the temporary file names gives room for only a finite number of different names. If tmpnam fails it returns a null pointer.

Warning: Between the time the pathname is constructed and the file is created another process might have created a file with the same name using tmpnam, leading to a possible security hole. The implementation generates names which can hardly be predicted, but when opening the file you should use the O_EXCL flag. Using tmpfile or mkstemp is a safe way to avoid this problem.

Function: char * tmpnam_r (char *result)
This function is nearly identical to the tmpnam function, except that if result is a null pointer it returns a null pointer.

This guarantees reentrancy because the non-reentrant situation of tmpnam cannot happen here.

Warning: This function has the same security problems as tmpnam.

Macro: int L_tmpnam
The value of this macro is an integer constant expression that represents the minimum size of a string large enough to hold a file name generated by the tmpnam function.

Macro: int TMP_MAX
The macro TMP_MAX is a lower bound for how many temporary names you can create with tmpnam. You can rely on being able to call tmpnam at least this many times before it might fail saying you have made too many temporary file names.

With the GNU library, you can create a very large number of temporary file names. If you actually created the files, you would probably run out of disk space before you ran out of names. Some other systems have a fixed, small limit on the number of temporary files. The limit is never less than 25.

Function: char * tempnam (const char *dir, const char *prefix)
This function generates a unique temporary file name. If prefix is not a null pointer, up to five characters of this string are used as a prefix for the file name. The return value is a string newly allocated with malloc, so you should release its storage with free when it is no longer needed.

Because the string is dynamically allocated this function is reentrant.

The directory prefix for the temporary file name is determined by testing each of the following in sequence. The directory must exist and be writable.

The environment variable TMPDIR, if it is defined. For security reasons this only happens if the program is not SUID or SGID enabled.
The dir argument, if it is not a null pointer.
The value of the P_tmpdir macro.
The directory `/tmp'.

This function is defined for SVID compatibility.

Warning: Between the time the pathname is constructed and the file is created another process might have created a file with the same name using tempnam, leading to a possible security hole. The implementation generates names which can hardly be predicted, but when opening the file you should use the O_EXCL flag. Using tmpfile or mkstemp is a safe way to avoid this problem.

SVID Macro: char * P_tmpdir
This macro is the name of the default directory for temporary files.

Older Unix systems did not have the functions just described. Instead they used mktemp and mkstemp. Both of these functions work by modifying a file name template string you pass. The last six characters of this string must be `XXXXXX'. These six `X's are replaced with six characters which make the whole string a unique file name. Usually the template string is something like `/tmp/prefixXXXXXX', and each program uses a unique prefix.

Note: Because mktemp and mkstemp modify the template string, you must not pass string constants to them. String constants are normally in read-only storage, so your program would crash when mktemp or mkstemp tried to modify the string.

Function: char * mktemp (char *template)
The mktemp function generates a unique file name by modifying template as described above. If successful, it returns template as modified. If mktemp cannot find a unique file name, it makes template an empty string and returns that. If template does not end with `XXXXXX', mktemp returns a null pointer.

Warning: Between the time the pathname is constructed and the file is created another process might have created a file with the same name using mktemp, leading to a possible security hole. The implementation generates names which can hardly be predicted, but when opening the file you should use the O_EXCL flag. Using mkstemp is a safe way to avoid this problem.

Function: int mkstemp (char *template)
The mkstemp function generates a unique file name just as mktemp does, but it also opens the file for you with open (see section Opening and Closing Files). If successful, it modifies template in place and returns a file descriptor for that file open for reading and writing. If mkstemp cannot create a uniquely-named file, it returns -1. If template does not end with `XXXXXX', mkstemp returns -1 and does not modify template.

The file is opened using mode 0600. If the file is meant to be used by other users this mode must be changed explicitly.

Unlike mktemp, mkstemp is actually guaranteed to create a unique file that cannot possibly clash with any other program trying to create a temporary file. This is because it works by calling open with the O_EXCL flag, which says you want to create a new file and get an error if the file already exists.

Function: char * mkdtemp (char *template)
The mkdtemp function creates a directory with a unique name. If it succeeds, it overwrites template with the name of the directory, and returns template. As with mktemp and mkstemp, template should be a string ending with `XXXXXX'.

If mkdtemp cannot create an uniquely named directory, it returns NULL and sets errno appropriately. If template does not end with `XXXXXX', mkdtemp returns NULL and does not modify template. errno will be set to EINVAL in this case.

The directory is created using mode 0700.

The directory created by mkdtemp cannot clash with temporary files or directories created by other users. This is because directory creation always works like open with O_EXCL. See section Creating Directories.

The mkdtemp function comes from OpenBSD.
Pipes and FIFOs

A pipe is a mechanism for interprocess communication; data written to the pipe by one process can be read by another process. The data is handled in a first-in, first-out (FIFO) order. The pipe has no name; it is created for one use and both ends must be inherited from the single process which created the pipe.

A FIFO special file is similar to a pipe, but instead of being an anonymous, temporary connection, a FIFO has a name or names like any other file. Processes open the FIFO by name in order to communicate through it.

A pipe or FIFO has to be open at both ends simultaneously. If you read from a pipe or FIFO file that doesn't have any processes writing to it (perhaps because they have all closed the file, or exited), the read returns end-of-file. Writing to a pipe or FIFO that doesn't have a reading process is treated as an error condition; it generates a SIGPIPE signal, and fails with error code EPIPE if the signal is handled or blocked.

Neither pipes nor FIFO special files allow file positioning. Both reading and writing operations happen sequentially; reading from the beginning of the file and writing at the end.

Creating a Pipe

The primitive for creating a pipe is the pipe function. This creates both the reading and writing ends of the pipe. It is not very useful for a single process to use a pipe to talk to itself. In typical use, a process creates a pipe just before it forks one or more child processes (see section Creating a Process). The pipe is then used for communication either between the parent or child processes, or between two sibling processes.

The pipe function is declared in the header file `unistd.h'.

Function: int pipe (int filedes[2])
The pipe function creates a pipe and puts the file descriptors for the reading and writing ends of the pipe (respectively) into filedes[0] and filedes[1].

An easy way to remember that the input end comes first is that file descriptor 0 is standard input, and file descriptor 1 is standard output.

If successful, pipe returns a value of 0. On failure, -1 is returned. The following errno error conditions are defined for this function:

EMFILE
The process has too many files open.
ENFILE
There are too many open files in the entire system. See section Error Codes, for more information about ENFILE. This error never occurs in the GNU system.
Here is an example of a simple program that creates a pipe. This program uses the fork function (see section Creating a Process) to create a child process. The parent process writes data to the pipe, which is read by the child process.
#include <sys/types.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>

/* Read characters from the pipe and echo them to stdout. */

void
read_from_pipe (int file)
{
  FILE *stream;
  int c;
  stream = fdopen (file, "r");
  while ((c = fgetc (stream)) != EOF)
    putchar (c);
  fclose (stream);
}

/* Write some random text to the pipe. */

void
write_to_pipe (int file)
{
  FILE *stream;
  stream = fdopen (file, "w");
  fprintf (stream, "hello, world!\n");
  fprintf (stream, "goodbye, world!\n");
  fclose (stream);
}

int
main (void)
{
  pid_t pid;
  int mypipe[2];

  /* Create the pipe. */
  if (pipe (mypipe))
    {
      fprintf (stderr, "Pipe failed.\n");
      return EXIT_FAILURE;
    }

  /* Create the child process. */
  pid = fork ();
  if (pid == (pid_t) 0)
    {
      /* This is the child process.
         Close other end first. */
      close (mypipe[1]);
      read_from_pipe (mypipe[0]);
      return EXIT_SUCCESS;
    }
  else if (pid < (pid_t) 0)
    {
      /* The fork failed. */
      fprintf (stderr, "Fork failed.\n");
      return EXIT_FAILURE;
    }
  else
    {
      /* This is the parent process.
         Close other end first. */
      close (mypipe[0]);
      write_to_pipe (mypipe[1]);
      return EXIT_SUCCESS;
    }
}
Pipe to a Subprocess

A common use of pipes is to send data to or receive data from a program being run as a subprocess. One way of doing this is by using a combination of pipe (to create the pipe), fork (to create the subprocess), dup2 (to force the subprocess to use the pipe as its standard input or output channel), and exec (to execute the new program). Or, you can use popen and pclose.

The advantage of using popen and pclose is that the interface is much simpler and easier to use. But it doesn't offer as much flexibility as using the low-level functions directly.

Function: FILE * popen (const char *command, const char *mode)
The popen function is closely related to the system function; see section Running a Command. It executes the shell command command as a subprocess. However, instead of waiting for the command to complete, it creates a pipe to the subprocess and returns a stream that corresponds to that pipe.

If you specify a mode argument of "r", you can read from the stream to retrieve data from the standard output channel of the subprocess. The subprocess inherits its standard input channel from the parent process.

Similarly, if you specify a mode argument of "w", you can write to the stream to send data to the standard input channel of the subprocess. The subprocess inherits its standard output channel from the parent process.

In the event of an error popen returns a null pointer. This might happen if the pipe or stream cannot be created, if the subprocess cannot be forked, or if the program cannot be executed.

Function: int pclose (FILE *stream)
The pclose function is used to close a stream created by popen. It waits for the child process to terminate and returns its status value, as for the system function.

Here is an example showing how to use popen and pclose to filter output through another program, in this case the paging program more.
#include <stdio.h>
#include <stdlib.h>

void
write_data (FILE * stream)
{
  int i;
  for (i = 0; i < 100; i++)
    fprintf (stream, "%d\n", i);
  if (ferror (stream))
    {
      fprintf (stderr, "Output to stream failed.\n");
      exit (EXIT_FAILURE);
    }
}

int
main (void)
{
  FILE *output;

  output = popen ("more", "w");
  if (!output)
    {
      fprintf (stderr,
               "incorrect parameters or too many files.\n");
      return EXIT_FAILURE;
    }
  write_data (output);
  if (pclose (output) != 0)
    {
      fprintf (stderr,
               "Could not run more or other error.\n");
    }
  return EXIT_SUCCESS;
}
FIFO Special Files

A FIFO special file is similar to a pipe, except that it is created in a different way. Instead of being an anonymous communications channel, a FIFO special file is entered into the file system by calling mkfifo.

Once you have created a FIFO special file in this way, any process can open it for reading or writing, in the same way as an ordinary file. However, it has to be open at both ends simultaneously before you can proceed to do any input or output operations on it. Opening a FIFO for reading normally blocks until some other process opens the same FIFO for writing, and vice versa.

The mkfifo function is declared in the header file `sys/stat.h'.

Function: int mkfifo (const char *filename, mode_t mode)
The mkfifo function makes a FIFO special file with name filename. The mode argument is used to set the file's permissions; see section Assigning File Permissions.

The normal, successful return value from mkfifo is 0. In the case of an error, -1 is returned. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EEXIST
The named file already exists.
ENOSPC
The directory or file system cannot be extended.
EROFS
The directory that would contain the file resides on a read-only file system.
Atomicity of Pipe I/O

Reading or writing pipe data is atomic if the size of data written is not greater than PIPE_BUF. This means that the data transfer seems to be an instantaneous unit, in that nothing else in the system can observe a state in which it is partially complete. Atomic I/O may not begin right away (it may need to wait for buffer space or for data), but once it does begin it finishes immediately.

Reading or writing a larger amount of data may not be atomic; for example, output data from other processes sharing the descriptor may be interspersed. Also, once PIPE_BUF characters have been written, further writes will block until some characters are read.

See section Limits on File System Capacity, for information about the PIPE_BUF parameter.
Sockets

This chapter describes the GNU facilities for interprocess communication using sockets.

A socket is a generalized interprocess communication channel. Like a pipe, a socket is represented as a file descriptor. Unlike pipes sockets support communication between unrelated processes, and even between processes running on different machines that communicate over a network. Sockets are the primary means of communicating with other machines; telnet, rlogin, ftp, talk and the other familiar network programs use sockets.

Not all operating systems support sockets. In the GNU library, the header file `sys/socket.h' exists regardless of the operating system, and the socket functions always exist, but if the system does not really support sockets these functions always fail.

Incomplete: We do not currently document the facilities for broadcast messages or for configuring Internet interfaces. The reentrant functions and some newer functions that are related to IPv6 aren't documented either so far.

Socket Concepts

When you create a socket, you must specify the style of communication you want to use and the type of protocol that should implement it. The communication style of a socket defines the user-level semantics of sending and receiving data on the socket. Choosing a communication style specifies the answers to questions such as these:

What are the units of data transmission? Some communication styles regard the data as a sequence of bytes with no larger structure; others group the bytes into records (which are known in this context as packets).
Can data be lost during normal operation? Some communication styles guarantee that all the data sent arrives in the order it was sent (barring system or network crashes); other styles occasionally lose data as a normal part of operation, and may sometimes deliver packets more than once or in the wrong order. Designing a program to use unreliable communication styles usually involves taking precautions to detect lost or misordered packets and to retransmit data as needed.
Is communication entirely with one partner? Some communication styles are like a telephone call--you make a connection with one remote socket and then exchange data freely. Other styles are like mailing letters--you specify a destination address for each message you send.

You must also choose a namespace for naming the socket. A socket name ("address") is meaningful only in the context of a particular namespace. In fact, even the data type to use for a socket name may depend on the namespace. Namespaces are also called "domains", but we avoid that word as it can be confused with other usage of the same term. Each namespace has a symbolic name that starts with `PF_'. A corresponding symbolic name starting with `AF_' designates the address format for that namespace.

Finally you must choose the protocol to carry out the communication. The protocol determines what low-level mechanism is used to transmit and receive data. Each protocol is valid for a particular namespace and communication style; a namespace is sometimes called a protocol family because of this, which is why the namespace names start with `PF_'.

The rules of a protocol apply to the data passing between two programs, perhaps on different computers; most of these rules are handled by the operating system and you need not know about them. What you do need to know about protocols is this:

In order to have communication between two sockets, they must specify the same protocol.
Each protocol is meaningful with particular style/namespace combinations and cannot be used with inappropriate combinations. For example, the TCP protocol fits only the byte stream style of communication and the Internet namespace.
For each combination of style and namespace there is a default protocol, which you can request by specifying 0 as the protocol number. And that's what you should normally do--use the default.

Throughout the following description at various places variables/parameters to denote sizes are required. And here the trouble starts. In the first implementations the type of these variables was simply int. On most machines at that time an int was 32 bits wide, which created a de facto standard requiring 32-bit variables. This is important since references to variables of this type are passed to the kernel.

Then the POSIX people came and unified the interface with the words "all size values are of type size_t". On 64-bit machines size_t is 64 bits wide, so pointers to variables were no longer possible.

The Unix98 specification provides a solution by introducing a type socklen_t. This type is used in all of the cases that POSIX changed to use size_t. The only requirement of this type is that it be an unsigned type of at least 32 bits. Therefore, implementations which require that references to 32-bit variables be passed can be as happy as implementations which use 64-bit values.

Communication Styles

The GNU library includes support for several different kinds of sockets, each with different characteristics. This section describes the supported socket types. The symbolic constants listed here are defined in `sys/socket.h'.

Macro: int SOCK_STREAM
The SOCK_STREAM style is like a pipe (see section Pipes and FIFOs). It operates over a connection with a particular remote socket and transmits data reliably as a stream of bytes.

Use of this style is covered in detail in section Using Sockets with Connections.

Macro: int SOCK_DGRAM
The SOCK_DGRAM style is used for sending individually-addressed packets unreliably. It is the diametrical opposite of SOCK_STREAM.

Each time you write data to a socket of this kind, that data becomes one packet. Since SOCK_DGRAM sockets do not have connections, you must specify the recipient address with each packet.

The only guarantee that the system makes about your requests to transmit data is that it will try its best to deliver each packet you send. It may succeed with the sixth packet after failing with the fourth and fifth packets; the seventh packet may arrive before the sixth, and may arrive a second time after the sixth.

The typical use for SOCK_DGRAM is in situations where it is acceptable to simply re-send a packet if no response is seen in a reasonable amount of time.

See section Datagram Socket Operations, for detailed information about how to use datagram sockets.

Macro: int SOCK_RAW
This style provides access to low-level network protocols and interfaces. Ordinary user programs usually have no need to use this style.

Socket Addresses

The name of a socket is normally called an address. The functions and symbols for dealing with socket addresses were named inconsistently, sometimes using the term "name" and sometimes using "address". You can regard these terms as synonymous where sockets are concerned.

A socket newly created with the socket function has no address. Other processes can find it for communication only if you give it an address. We call this binding the address to the socket, and the way to do it is with the bind function.

You need be concerned with the address of a socket if other processes are to find it and start communicating with it. You can specify an address for other sockets, but this is usually pointless; the first time you send data from a socket, or use it to initiate a connection, the system assigns an address automatically if you have not specified one.

Occasionally a client needs to specify an address because the server discriminates based on address; for example, the rsh and rlogin protocols look at the client's socket address and only bypass password checking if it is less than IPPORT_RESERVED (see section Internet Ports).

The details of socket addresses vary depending on what namespace you are using. See section The Local Namespace, or section The Internet Namespace, for specific information.

Regardless of the namespace, you use the same functions bind and getsockname to set and examine a socket's address. These functions use a phony data type, struct sockaddr *, to accept the address. In practice, the address lives in a structure of some other data type appropriate to the address format you are using, but you cast its address to struct sockaddr * when you pass it to bind.

Address Formats

The functions bind and getsockname use the generic data type struct sockaddr * to represent a pointer to a socket address. You can't use this data type effectively to interpret an address or construct one; for that, you must use the proper data type for the socket's namespace.

Thus, the usual practice is to construct an address of the proper namespace-specific type, then cast a pointer to struct sockaddr * when you call bind or getsockname.

The one piece of information that you can get from the struct sockaddr data type is the address format designator. This tells you which data type to use to understand the address fully.

The symbols in this section are defined in the header file `sys/socket.h'.

Data Type: struct sockaddr
The struct sockaddr type itself has the following members:

short int sa_family
This is the code for the address format of this address. It identifies the format of the data which follows.
char sa_data[14]
This is the actual socket address data, which is format-dependent. Its length also depends on the format, and may well be more than 14. The length 14 of sa_data is essentially arbitrary.
Each address format has a symbolic name which starts with `AF_'. Each of them corresponds to a `PF_' symbol which designates the corresponding namespace. Here is a list of address format names:

AF_LOCAL
This designates the address format that goes with the local namespace. (PF_LOCAL is the name of that namespace.) See section Details of Local Namespace, for information about this address format.
AF_UNIX
This is a synonym for AF_LOCAL. Although AF_LOCAL is mandated by POSIX.1g, AF_UNIX is portable to more systems. AF_UNIX was the traditional name stemming from BSD, so even most POSIX systems support it. It is also the name of choice in the Unix98 specification. (The same is true for PF_UNIX vs. PF_LOCAL).
AF_FILE
This is another synonym for AF_LOCAL, for compatibility. (PF_FILE is likewise a synonym for PF_LOCAL.)
AF_INET
This designates the address format that goes with the Internet namespace. (PF_INET is the name of that namespace.) See section Internet Socket Address Formats.
AF_INET6
This is similar to AF_INET, but refers to the IPv6 protocol. (PF_INET6 is the name of the corresponding namespace.)
AF_UNSPEC
This designates no particular address format. It is used only in rare cases, such as to clear out the default destination address of a "connected" datagram socket. See section Sending Datagrams. The corresponding namespace designator symbol PF_UNSPEC exists for completeness, but there is no reason to use it in a program.
`sys/socket.h' defines symbols starting with `AF_' for many different kinds of networks, most or all of which are not actually implemented. We will document those that really work as we receive information about how to use them.

Setting the Address of a Socket

Use the bind function to assign an address to a socket. The prototype for bind is in the header file `sys/socket.h'. For examples of use, see section Example of Local-Namespace Sockets, or see section Internet Socket Example.

Function: int bind (int socket, struct sockaddr *addr, socklen_t length)
The bind function assigns an address to the socket socket. The addr and length arguments specify the address; the detailed format of the address depends on the namespace. The first part of the address is always the format designator, which specifies a namespace, and says that the address is in the format of that namespace.

The return value is 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EBADF
The socket argument is not a valid file descriptor.
ENOTSOCK
The descriptor socket is not a socket.
EADDRNOTAVAIL
The specified address is not available on this machine.
EADDRINUSE
Some other socket is already using the specified address.
EINVAL
The socket socket already has an address.
EACCES
You do not have permission to access the requested address. (In the Internet domain, only the super-user is allowed to specify a port number in the range 0 through IPPORT_RESERVED minus one; see section Internet Ports.)
Additional conditions may be possible depending on the particular namespace of the socket.

Reading the Address of a Socket

Use the function getsockname to examine the address of an Internet socket. The prototype for this function is in the header file `sys/socket.h'.

Function: int getsockname (int socket, struct sockaddr *addr, socklen_t *length-ptr)
The getsockname function returns information about the address of the socket socket in the locations specified by the addr and length-ptr arguments. Note that the length-ptr is a pointer; you should initialize it to be the allocation size of addr, and on return it contains the actual size of the address data.

The format of the address data depends on the socket namespace. The length of the information is usually fixed for a given namespace, so normally you can know exactly how much space is needed and can provide that much. The usual practice is to allocate a place for the value using the proper data type for the socket's namespace, then cast its address to struct sockaddr * to pass it to getsockname.

The return value is 0 on success and -1 on error. The following errno error conditions are defined for this function:

EBADF
The socket argument is not a valid file descriptor.
ENOTSOCK
The descriptor socket is not a socket.
ENOBUFS
There are not enough internal buffers available for the operation.
You can't read the address of a socket in the file namespace. This is consistent with the rest of the system; in general, there's no way to find a file's name from a descriptor for that file.

Interface Naming

Each network interface has a name. This usually consists of a few letters that relate to the type of interface, which may be followed by a number if there is more than one interface of that type. Examples might be lo (the loopback interface) and eth0 (the first Ethernet interface).

Although such names are convenient for humans, it would be clumsy to have to use them whenever a program needs to refer to an interface. In such situations an interface is referred to by its index, which is an arbitrarily-assigned small positive integer.

The following functions, constants and data types are declared in the header file `net/if.h'.

Constant: size_t IFNAMSIZ
This constant defines the maximum buffer size needed to hold an interface name, including its terminating zero byte.

Function: unsigned int if_nametoindex (const char *ifname)
This function yields the interface index corresponding to a particular name. If no interface exists with the name given, it returns 0.

Function: char * if_indextoname (unsigned int ifindex, char *ifname)
This function maps an interface index to its corresponding name. The returned name is placed in the buffer pointed to by ifname, which must be at least IFNAMSIZ bytes in length. If the index was invalid, the function's return value is a null pointer, otherwise it is ifname.

Data Type: struct if_nameindex
This data type is used to hold the information about a single interface. It has the following members:

unsigned int if_index;
This is the interface index.
char *if_name
This is the null-terminated index name.

Function: struct if_nameindex * if_nameindex (void)
This function returns an array of if_nameindex structures, one for every interface that is present. The end of the list is indicated by a structure with an interface of 0 and a null name pointer. If an error occurs, this function returns a null pointer.

The returned structure must be freed with if_freenameindex after use.

Function: void if_freenameindex (struct if_nameindex *ptr)
This function frees the structure returned by an earlier call to if_nameindex.

The Local Namespace

This section describes the details of the local namespace, whose symbolic name (required when you create a socket) is PF_LOCAL. The local namespace is also known as "Unix domain sockets". Another name is file namespace since socket addresses are normally implemented as file names.

Local Namespace Concepts

In the local namespace socket addresses are file names. You can specify any file name you want as the address of the socket, but you must have write permission on the directory containing it. It's common to put these files in the `/tmp' directory.

One peculiarity of the local namespace is that the name is only used when opening the connection; once open the address is not meaningful and may not exist.

Another peculiarity is that you cannot connect to such a socket from another machine--not even if the other machine shares the file system which contains the name of the socket. You can see the socket in a directory listing, but connecting to it never succeeds. Some programs take advantage of this, such as by asking the client to send its own process ID, and using the process IDs to distinguish between clients. However, we recommend you not use this method in protocols you design, as we might someday permit connections from other machines that mount the same file systems. Instead, send each new client an identifying number if you want it to have one.

After you close a socket in the local namespace, you should delete the file name from the file system. Use unlink or remove to do this; see section Deleting Files.

The local namespace supports just one protocol for any communication style; it is protocol number 0.

Details of Local Namespace

To create a socket in the local namespace, use the constant PF_LOCAL as the namespace argument to socket or socketpair. This constant is defined in `sys/socket.h'.

Macro: int PF_LOCAL
This designates the local namespace, in which socket addresses are local names, and its associated family of protocols. PF_Local is the macro used by Posix.1g.

Macro: int PF_UNIX
This is a synonym for PF_LOCAL, for compatibility's sake.

Macro: int PF_FILE
This is a synonym for PF_LOCAL, for compatibility's sake.

The structure for specifying socket names in the local namespace is defined in the header file `sys/un.h':

Data Type: struct sockaddr_un
This structure is used to specify local namespace socket addresses. It has the following members:

short int sun_family
This identifies the address family or format of the socket address. You should store the value AF_LOCAL to designate the local namespace. See section Socket Addresses.
char sun_path[108]
This is the file name to use. Incomplete: Why is 108 a magic number? RMS suggests making this a zero-length array and tweaking the following example to use alloca to allocate an appropriate amount of storage based on the length of the filename.
You should compute the length parameter for a socket address in the local namespace as the sum of the size of the sun_family component and the string length (not the allocation size!) of the file name string. This can be done using the macro SUN_LEN:

Macro: int SUN_LEN (struct sockaddr_un * ptr)
The macro computes the length of socket address in the local namespace.

Example of Local-Namespace Sockets

Here is an example showing how to create and name a socket in the local namespace.
#include <stddef.h>
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <sys/socket.h>
#include <sys/un.h>

int
make_named_socket (const char *filename)
{
  struct sockaddr_un name;
  int sock;
  size_t size;

  /* Create the socket. */
  sock = socket (PF_LOCAL, SOCK_DGRAM, 0);
  if (sock < 0)
    {
      perror ("socket");
      exit (EXIT_FAILURE);
    }

  /* Bind a name to the socket. */
  name.sun_family = AF_LOCAL;
  strncpy (name.sun_path, filename, sizeof (name.sun_path));

  /* The size of the address is
     the offset of the start of the filename,
     plus its length,
     plus one for the terminating null byte.
     Alternatively you can just do:
     size = SUN_LEN (&name);
 */
  size = (offsetof (struct sockaddr_un, sun_path)
          + strlen (name.sun_path) + 1);

  if (bind (sock, (struct sockaddr *) &name, size) < 0)
    {
      perror ("bind");
      exit (EXIT_FAILURE);
    }

  return sock;
}
The Internet Namespace

This section describes the details of the protocols and socket naming conventions used in the Internet namespace.

Originally the Internet namespace used only IP version 4 (IPv4). With the growing number of hosts on the Internet, a new protocol with a larger address space was necessary: IP version 6 (IPv6). IPv6 introduces 128-bit addresses (IPv4 has 32-bit addresses) and other features, and will eventually replace IPv4.

To create a socket in the IPv4 Internet namespace, use the symbolic name PF_INET of this namespace as the namespace argument to socket or socketpair. For IPv6 addresses you need the macro PF_INET6. These macros are defined in `sys/socket.h'.

Macro: int PF_INET
This designates the IPv4 Internet namespace and associated family of protocols.

Macro: int PF_INET6
This designates the IPv6 Internet namespace and associated family of protocols.

A socket address for the Internet namespace includes the following components:

The address of the machine you want to connect to. Internet addresses can be specified in several ways; these are discussed in section Internet Socket Address Formats, section Host Addresses and section Host Names.
A port number for that machine. See section Internet Ports.

You must ensure that the address and port number are represented in a canonical format called network byte order. See section Byte Order Conversion, for information about this.

Internet Socket Address Formats

In the Internet namespace, for both IPv4 (AF_INET) and IPv6 (AF_INET6), a socket address consists of a host address and a port on that host. In addition, the protocol you choose serves effectively as a part of the address because local port numbers are meaningful only within a particular protocol.

The data types for representing socket addresses in the Internet namespace are defined in the header file `netinet/in.h'.

Data Type: struct sockaddr_in
This is the data type used to represent socket addresses in the Internet namespace. It has the following members:

sa_family_t sin_family
This identifies the address family or format of the socket address. You should store the value AF_INET in this member. See section Socket Addresses.
struct in_addr sin_addr
This is the Internet address of the host machine. See section Host Addresses, and section Host Names, for how to get a value to store here.
unsigned short int sin_port
This is the port number. See section Internet Ports.
When you call bind or getsockname, you should specify sizeof (struct sockaddr_in) as the length parameter if you are using an IPv4 Internet namespace socket address.

Data Type: struct sockaddr_in6
This is the data type used to represent socket addresses in the IPv6 namespace. It has the following members:

sa_family_t sin6_family
This identifies the address family or format of the socket address. You should store the value of AF_INET6 in this member. See section Socket Addresses.
struct in6_addr sin6_addr
This is the IPv6 address of the host machine. See section Host Addresses, and section Host Names, for how to get a value to store here.
uint32_t sin6_flowinfo
This is a currently unimplemented field.
uint16_t sin6_port
This is the port number. See section Internet Ports.
Host Addresses

Each computer on the Internet has one or more Internet addresses, numbers which identify that computer among all those on the Internet. Users typically write IPv4 numeric host addresses as sequences of four numbers, separated by periods, as in `128.52.46.32', and IPv6 numeric host addresses as sequences of up to eight numbers separated by colons, as in `5f03:1200:836f:c100::1'.

Each computer also has one or more host names, which are strings of words separated by periods, as in `mescaline.gnu.org'.

Programs that let the user specify a host typically accept both numeric addresses and host names. To open a connection a program needs a numeric address, and so must convert a host name to the numeric address it stands for.

Internet Host Addresses

An IPv4 Internet host address is a number containing four bytes of data. Historically these are divided into two parts, a network number and a local network address number within that network. In the mid-1990s classless addresses were introduced which changed this behaviour. Since some functions implicitly expect the old definitions, we first describe the class-based network and will then describe classless addresses. IPv6 uses only classless addresses and therefore the following paragraphs don't apply.

The class-based IPv4 network number consists of the first one, two or three bytes; the rest of the bytes are the local address.

IPv4 network numbers are registered with the Network Information Center (NIC), and are divided into three classes--A, B and C. The local network address numbers of individual machines are registered with the administrator of the particular network.

Class A networks have single-byte numbers in the range 0 to 127. There are only a small number of Class A networks, but they can each support a very large number of hosts. Medium-sized Class B networks have two-byte network numbers, with the first byte in the range 128 to 191. Class C networks are the smallest; they have three-byte network numbers, with the first byte in the range 192-255. Thus, the first 1, 2, or 3 bytes of an Internet address specify a network. The remaining bytes of the Internet address specify the address within that network.

The Class A network 0 is reserved for broadcast to all networks. In addition, the host number 0 within each network is reserved for broadcast to all hosts in that network. These uses are obsolete now but for compatibility reasons you shouldn't use network 0 and host number 0.

The Class A network 127 is reserved for loopback; you can always use the Internet address `127.0.0.1' to refer to the host machine.

Since a single machine can be a member of multiple networks, it can have multiple Internet host addresses. However, there is never supposed to be more than one machine with the same host address.

There are four forms of the standard numbers-and-dots notation for Internet addresses:

a.b.c.d
This specifies all four bytes of the address individually and is the commonly used representation.
a.b.c
The last part of the address, c, is interpreted as a 2-byte quantity. This is useful for specifying host addresses in a Class B network with network address number a.b.
a.b
The last part of the address, b, is interpreted as a 3-byte quantity. This is useful for specifying host addresses in a Class A network with network address number a.
a
If only one part is given, this corresponds directly to the host address number.
Within each part of the address, the usual C conventions for specifying the radix apply. In other words, a leading `0x' or `0X' implies hexadecimal radix; a leading `0' implies octal; and otherwise decimal radix is assumed.

Classless Addresses

IPv4 addresses (and IPv6 addresses also) are now considered classless; the distinction between classes A, B and C can be ignored. Instead an IPv4 host address consists of a 32-bit address and a 32-bit mask. The mask contains set bits for the network part and cleared bits for the host part. The network part is contiguous from the left, with the remaining bits representing the host. As a consequence, the netmask can simply be specified as the number of set bits. Classes A, B and C are just special cases of this general rule. For example, class A addresses have a netmask of `255.0.0.0' or a prefix length of 8.

Classless IPv4 network addresses are written in numbers-and-dots notation with the prefix length appended and a slash as separator. For example the class A network 10 is written as `10.0.0.0/8'.

IPv6 Addresses

IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host address is usually written as eight 16-bit hexadecimal numbers that are separated by colons. Two colons are used to abbreviate strings of consecutive zeros. For example, the IPv6 loopback address `0:0:0:0:0:0:0:1' can just be written as `::1'.

Host Address Data Type

IPv4 Internet host addresses are represented in some contexts as integers (type uint32_t). In other contexts, the integer is packaged inside a structure of type struct in_addr. It would be better if the usage were made consistent, but it is not hard to extract the integer from the structure or put the integer into a structure.

You will find older code that uses unsigned long int for IPv4 Internet host addresses instead of uint32_t or struct in_addr. Historically unsigned long int was a 32-bit number but with 64-bit machines this has changed. Using unsigned long int might break the code if it is used on machines where this type doesn't have 32 bits. uint32_t is specified by Unix98 and guaranteed to have 32 bits.

IPv6 Internet host addresses have 128 bits and are packaged inside a structure of type struct in6_addr.

The following basic definitions for Internet addresses are declared in the header file `netinet/in.h':

Data Type: struct in_addr
This data type is used in certain contexts to contain an IPv4 Internet host address. It has just one field, named s_addr, which records the host address number as an uint32_t.

Macro: uint32_t INADDR_LOOPBACK
You can use this constant to stand for "the address of this machine," instead of finding its actual address. It is the IPv4 Internet address `127.0.0.1', which is usually called `localhost'. This special constant saves you the trouble of looking up the address of your own machine. Also, the system usually implements INADDR_LOOPBACK specially, avoiding any network traffic for the case of one machine talking to itself.

Macro: uint32_t INADDR_ANY
You can use this constant to stand for "any incoming address" when binding to an address. See section Setting the Address of a Socket. This is the usual address to give in the sin_addr member of struct sockaddr_in when you want to accept Internet connections.

Macro: uint32_t INADDR_BROADCAST
This constant is the address you use to send a broadcast message.

Macro: uint32_t INADDR_NONE
This constant is returned by some functions to indicate an error.

Data Type: struct in6_addr
This data type is used to store an IPv6 address. It stores 128 bits of data, which can be accessed (via a union) in a variety of ways.

Constant: struct in6_addr in6addr_loopback
This constant is the IPv6 address `::1', the loopback address. See above for a description of what this means. The macro IN6ADDR_LOOPBACK_INIT is provided to allow you to initialize your own variables to this value.

Constant: struct in6_addr in6addr_any
This constant is the IPv6 address `::', the unspecified address. See above for a description of what this means. The macro IN6ADDR_ANY_INIT is provided to allow you to initialize your own variables to this value.

Host Address Functions

These additional functions for manipulating Internet addresses are declared in the header file `arpa/inet.h'. They represent Internet addresses in network byte order, and network numbers and local-address-within-network numbers in host byte order. See section Byte Order Conversion, for an explanation of network and host byte order.

Function: int inet_aton (const char *name, struct in_addr *addr)
This function converts the IPv4 Internet host address name from the standard numbers-and-dots notation into binary data and stores it in the struct in_addr that addr points to. inet_aton returns nonzero if the address is valid, zero if not.

Function: uint32_t inet_addr (const char *name)
This function converts the IPv4 Internet host address name from the standard numbers-and-dots notation into binary data. If the input is not valid, inet_addr returns INADDR_NONE. This is an obsolete interface to inet_aton, described immediately above. It is obsolete because INADDR_NONE is a valid address (255.255.255.255), and inet_aton provides a cleaner way to indicate error return.

Function: uint32_t inet_network (const char *name)
This function extracts the network number from the address name, given in the standard numbers-and-dots notation. The returned address is in host order. If the input is not valid, inet_network returns -1.

The function works only with traditional IPv4 class A, B and C network types. It doesn't work with classless addresses and shouldn't be used anymore.

Function: char * inet_ntoa (struct in_addr addr)
This function converts the IPv4 Internet host address addr to a string in the standard numbers-and-dots notation. The return value is a pointer into a statically-allocated buffer. Subsequent calls will overwrite the same buffer, so you should copy the string if you need to save it.

In multi-threaded programs each thread has an own statically-allocated buffer. But still subsequent calls of inet_ntoa in the same thread will overwrite the result of the last call.

Instead of inet_ntoa the newer function inet_ntop which is described below should be used since it handles both IPv4 and IPv6 addresses.

Function: struct in_addr inet_makeaddr (uint32_t net, uint32_t local)
This function makes an IPv4 Internet host address by combining the network number net with the local-address-within-network number local.

Function: uint32_t inet_lnaof (struct in_addr addr)
This function returns the local-address-within-network part of the Internet host address addr.

The function works only with traditional IPv4 class A, B and C network types. It doesn't work with classless addresses and shouldn't be used anymore.

Function: uint32_t inet_netof (struct in_addr addr)
This function returns the network number part of the Internet host address addr.

The function works only with traditional IPv4 class A, B and C network types. It doesn't work with classless addresses and shouldn't be used anymore.

Function: int inet_pton (int af, const char *cp, void *buf)
This function converts an Internet address (either IPv4 or IPv6) from presentation (textual) to network (binary) format. af should be either AF_INET or AF_INET6, as appropriate for the type of address being converted. cp is a pointer to the input string, and buf is a pointer to a buffer for the result. It is the caller's responsibility to make sure the buffer is large enough.

Function: const char * inet_ntop (int af, const void *cp, char *buf, size_t len)
This function converts an Internet address (either IPv4 or IPv6) from network (binary) to presentation (textual) form. af should be either AF_INET or AF_INET6, as appropriate. cp is a pointer to the address to be converted. buf should be a pointer to a buffer to hold the result, and len is the length of this buffer. The return value from the function will be this buffer address.

Host Names

Besides the standard numbers-and-dots notation for Internet addresses, you can also refer to a host by a symbolic name. The advantage of a symbolic name is that it is usually easier to remember. For example, the machine with Internet address `158.121.106.19' is also known as `alpha.gnu.org'; and other machines in the `gnu.org' domain can refer to it simply as `alpha'.

Internally, the system uses a database to keep track of the mapping between host names and host numbers. This database is usually either the file `/etc/hosts' or an equivalent provided by a name server. The functions and other symbols for accessing this database are declared in `netdb.h'. They are BSD features, defined unconditionally if you include `netdb.h'.

Data Type: struct hostent
This data type is used to represent an entry in the hosts database. It has the following members:

char *h_name
This is the "official" name of the host.
char **h_aliases
These are alternative names for the host, represented as a null-terminated vector of strings.
int h_addrtype
This is the host address type; in practice, its value is always either AF_INET or AF_INET6, with the latter being used for IPv6 hosts. In principle other kinds of addresses could be represented in the database as well as Internet addresses; if this were done, you might find a value in this field other than AF_INET or AF_INET6. See section Socket Addresses.
int h_length
This is the length, in bytes, of each address.
char **h_addr_list
This is the vector of addresses for the host. (Recall that the host might be connected to multiple networks and have different addresses on each one.) The vector is terminated by a null pointer.
char *h_addr
This is a synonym for h_addr_list[0]; in other words, it is the first host address.
As far as the host database is concerned, each address is just a block of memory h_length bytes long. But in other contexts there is an implicit assumption that you can convert IPv4 addresses to a struct in_addr or an uint32_t. Host addresses in a struct hostent structure are always given in network byte order; see section Byte Order Conversion.

You can use gethostbyname, gethostbyname2 or gethostbyaddr to search the hosts database for information about a particular host. The information is returned in a statically-allocated structure; you must copy the information if you need to save it across calls. You can also use getaddrinfo and getnameinfo to obtain this information.

Function: struct hostent * gethostbyname (const char *name)
The gethostbyname function returns information about the host named name. If the lookup fails, it returns a null pointer.

Function: struct hostent * gethostbyname2 (const char *name, int af)
The gethostbyname2 function is like gethostbyname, but allows the caller to specify the desired address family (e.g. AF_INET or AF_INET6) of the result.

Function: struct hostent * gethostbyaddr (const char *addr, size_t length, int format)
The gethostbyaddr function returns information about the host with Internet address addr. The parameter addr is not really a pointer to char - it can be a pointer to an IPv4 or an IPv6 address. The length argument is the size (in bytes) of the address at addr. format specifies the address format; for an IPv4 Internet address, specify a value of AF_INET; for an IPv6 Internet address, use AF_INET6.

If the lookup fails, gethostbyaddr returns a null pointer.

If the name lookup by gethostbyname or gethostbyaddr fails, you can find out the reason by looking at the value of the variable h_errno. (It would be cleaner design for these functions to set errno, but use of h_errno is compatible with other systems.)

Here are the error codes that you may find in h_errno:

HOST_NOT_FOUND
No such host is known in the database.
TRY_AGAIN
This condition happens when the name server could not be contacted. If you try again later, you may succeed then.
NO_RECOVERY
A non-recoverable error occurred.
NO_ADDRESS
The host database contains an entry for the name, but it doesn't have an associated Internet address.
The lookup functions above all have one in common: they are not reentrant and therefore unusable in multi-threaded applications. Therefore provides the GNU C library a new set of functions which can be used in this context.

Function: int gethostbyname_r (const char *restrict name, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop)
The gethostbyname_r function returns information about the host named name. The caller must pass a pointer to an object of type struct hostent in the result_buf parameter. In addition the function may need extra buffer space and the caller must pass an pointer and the size of the buffer in the buf and buflen parameters.

A pointer to the buffer, in which the result is stored, is available in *result after the function call successfully returned. If an error occurs or if no entry is found, the pointer *result is a null pointer. Success is signalled by a zero return value. If the function failed the return value is an error number. In addition to the errors defined for gethostbyname it can also be ERANGE. In this case the call should be repeated with a larger buffer. Additional error information is not stored in the global variable h_errno but instead in the object pointed to by h_errnop.

Here's a small example:
struct hostent *
gethostname (char *host)
{
  struct hostent hostbuf, *hp;
  size_t hstbuflen;
  char *tmphstbuf;
  int res;
  int herr;

  hstbuflen = 1024;
  /* Allocate buffer, remember to free it to avoid a memory leakage.  */
  tmphstbuf = malloc (hstbuflen);

  while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen,
                                 &hp, &herr)) == ERANGE)
    {
      /* Enlarge the buffer.  */
      hstbuflen *= 2;
      tmphstbuf = realloc (tmphstbuf, hstbuflen);
    }
  /*  Check for errors.  */
  if (res || hp == NULL)
    return NULL;
  return hp;
}
Function: int gethostbyname2_r (const char *name, int af, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop)
The gethostbyname2_r function is like gethostbyname_r, but allows the caller to specify the desired address family (e.g. AF_INET or AF_INET6) for the result.

Function: int gethostbyaddr_r (const char *addr, size_t length, int format, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop)
The gethostbyaddr_r function returns information about the host with Internet address addr. The parameter addr is not really a pointer to char - it can be a pointer to an IPv4 or an IPv6 address. The length argument is the size (in bytes) of the address at addr. format specifies the address format; for an IPv4 Internet address, specify a value of AF_INET; for an IPv6 Internet address, use AF_INET6.

Similar to the gethostbyname_r function, the caller must provide buffers for the result and memory used internally. In case of success the function returns zero. Otherwise the value is an error number where ERANGE has the special meaning that the caller-provided buffer is too small.

You can also scan the entire hosts database one entry at a time using sethostent, gethostent and endhostent. Be careful when using these functions because they are not reentrant.

Function: void sethostent (int stayopen)
This function opens the hosts database to begin scanning it. You can then call gethostent to read the entries.

If the stayopen argument is nonzero, this sets a flag so that subsequent calls to gethostbyname or gethostbyaddr will not close the database (as they usually would). This makes for more efficiency if you call those functions several times, by avoiding reopening the database for each call.

Function: struct hostent * gethostent (void)
This function returns the next entry in the hosts database. It returns a null pointer if there are no more entries.

Function: void endhostent (void)
This function closes the hosts database.

Internet Ports

A socket address in the Internet namespace consists of a machine's Internet address plus a port number which distinguishes the sockets on a given machine (for a given protocol). Port numbers range from 0 to 65,535.

Port numbers less than IPPORT_RESERVED are reserved for standard servers, such as finger and telnet. There is a database that keeps track of these, and you can use the getservbyname function to map a service name onto a port number; see section The Services Database.

If you write a server that is not one of the standard ones defined in the database, you must choose a port number for it. Use a number greater than IPPORT_USERRESERVED; such numbers are reserved for servers and won't ever be generated automatically by the system. Avoiding conflicts with servers being run by other users is up to you.

When you use a socket without specifying its address, the system generates a port number for it. This number is between IPPORT_RESERVED and IPPORT_USERRESERVED.

On the Internet, it is actually legitimate to have two different sockets with the same port number, as long as they never both try to communicate with the same socket address (host address plus port number). You shouldn't duplicate a port number except in special circumstances where a higher-level protocol requires it. Normally, the system won't let you do it; bind normally insists on distinct port numbers. To reuse a port number, you must set the socket option SO_REUSEADDR. See section Socket-Level Options.

These macros are defined in the header file `netinet/in.h'.

Macro: int IPPORT_RESERVED
Port numbers less than IPPORT_RESERVED are reserved for superuser use.

Macro: int IPPORT_USERRESERVED
Port numbers greater than or equal to IPPORT_USERRESERVED are reserved for explicit use; they will never be allocated automatically.

The Services Database

The database that keeps track of "well-known" services is usually either the file `/etc/services' or an equivalent from a name server. You can use these utilities, declared in `netdb.h', to access the services database.

Data Type: struct servent
This data type holds information about entries from the services database. It has the following members:

char *s_name
This is the "official" name of the service.
char **s_aliases
These are alternate names for the service, represented as an array of strings. A null pointer terminates the array.
int s_port
This is the port number for the service. Port numbers are given in network byte order; see section Byte Order Conversion.
char *s_proto
This is the name of the protocol to use with this service. See section Protocols Database.
To get information about a particular service, use the getservbyname or getservbyport functions. The information is returned in a statically-allocated structure; you must copy the information if you need to save it across calls.

Function: struct servent * getservbyname (const char *name, const char *proto)
The getservbyname function returns information about the service named name using protocol proto. If it can't find such a service, it returns a null pointer.

This function is useful for servers as well as for clients; servers use it to determine which port they should listen on (see section Listening for Connections).

Function: struct servent * getservbyport (int port, const char *proto)
The getservbyport function returns information about the service at port port using protocol proto. If it can't find such a service, it returns a null pointer.

You can also scan the services database using setservent, getservent and endservent. Be careful when using these functions because they are not reentrant.

Function: void setservent (int stayopen)
This function opens the services database to begin scanning it.

If the stayopen argument is nonzero, this sets a flag so that subsequent calls to getservbyname or getservbyport will not close the database (as they usually would). This makes for more efficiency if you call those functions several times, by avoiding reopening the database for each call.

Function: struct servent * getservent (void)
This function returns the next entry in the services database. If there are no more entries, it returns a null pointer.

Function: void endservent (void)
This function closes the services database.

Byte Order Conversion

Different kinds of computers use different conventions for the ordering of bytes within a word. Some computers put the most significant byte within a word first (this is called "big-endian" order), and others put it last ("little-endian" order).

So that machines with different byte order conventions can communicate, the Internet protocols specify a canonical byte order convention for data transmitted over the network. This is known as network byte order.

When establishing an Internet socket connection, you must make sure that the data in the sin_port and sin_addr members of the sockaddr_in structure are represented in network byte order. If you are encoding integer data in the messages sent through the socket, you should convert this to network byte order too. If you don't do this, your program may fail when running on or talking to other kinds of machines.

If you use getservbyname and gethostbyname or inet_addr to get the port number and host address, the values are already in network byte order, and you can copy them directly into the sockaddr_in structure.

Otherwise, you have to convert the values explicitly. Use htons and ntohs to convert values for the sin_port member. Use htonl and ntohl to convert IPv4 addresses for the sin_addr member. (Remember, struct in_addr is equivalent to uint32_t.) These functions are declared in `netinet/in.h'.

Function: uint16_t htons (uint16_t hostshort)
This function converts the uint16_t integer hostshort from host byte order to network byte order.

Function: uint16_t ntohs (uint16_t netshort)
This function converts the uint16_t integer netshort from network byte order to host byte order.

Function: uint32_t htonl (uint32_t hostlong)
This function converts the uint32_t integer hostlong from host byte order to network byte order.

This is used for IPv4 Internet addresses.

Function: uint32_t ntohl (uint32_t netlong)
This function converts the uint32_t integer netlong from network byte order to host byte order.

This is used for IPv4 Internet addresses.

Protocols Database

The communications protocol used with a socket controls low-level details of how data are exchanged. For example, the protocol implements things like checksums to detect errors in transmissions, and routing instructions for messages. Normal user programs have little reason to mess with these details directly.

The default communications protocol for the Internet namespace depends on the communication style. For stream communication, the default is TCP ("transmission control protocol"). For datagram communication, the default is UDP ("user datagram protocol"). For reliable datagram communication, the default is RDP ("reliable datagram protocol"). You should nearly always use the default.

Internet protocols are generally specified by a name instead of a number. The network protocols that a host knows about are stored in a database. This is usually either derived from the file `/etc/protocols', or it may be an equivalent provided by a name server. You look up the protocol number associated with a named protocol in the database using the getprotobyname function.

Here are detailed descriptions of the utilities for accessing the protocols database. These are declared in `netdb.h'.

Data Type: struct protoent
This data type is used to represent entries in the network protocols database. It has the following members:

char *p_name
This is the official name of the protocol.
char **p_aliases
These are alternate names for the protocol, specified as an array of strings. The last element of the array is a null pointer.
int p_proto
This is the protocol number (in host byte order); use this member as the protocol argument to socket.
You can use getprotobyname and getprotobynumber to search the protocols database for a specific protocol. The information is returned in a statically-allocated structure; you must copy the information if you need to save it across calls.

Function: struct protoent * getprotobyname (const char *name)
The getprotobyname function returns information about the network protocol named name. If there is no such protocol, it returns a null pointer.

Function: struct protoent * getprotobynumber (int protocol)
The getprotobynumber function returns information about the network protocol with number protocol. If there is no such protocol, it returns a null pointer.

You can also scan the whole protocols database one protocol at a time by using setprotoent, getprotoent and endprotoent. Be careful when using these functions because they are not reentrant.

Function: void setprotoent (int stayopen)
This function opens the protocols database to begin scanning it.

If the stayopen argument is nonzero, this sets a flag so that subsequent calls to getprotobyname or getprotobynumber will not close the database (as they usually would). This makes for more efficiency if you call those functions several times, by avoiding reopening the database for each call.

Function: struct protoent * getprotoent (void)
This function returns the next entry in the protocols database. It returns a null pointer if there are no more entries.

Function: void endprotoent (void)
This function closes the protocols database.

Internet Socket Example

Here is an example showing how to create and name a socket in the Internet namespace. The newly created socket exists on the machine that the program is running on. Rather than finding and using the machine's Internet address, this example specifies INADDR_ANY as the host address; the system replaces that with the machine's actual address.
#include <stdio.h>
#include <stdlib.h>
#include <sys/socket.h>
#include <netinet/in.h>

int
make_socket (uint16_t port)
{
  int sock;
  struct sockaddr_in name;

  /* Create the socket. */
  sock = socket (PF_INET, SOCK_STREAM, 0);
  if (sock < 0)
    {
      perror ("socket");
      exit (EXIT_FAILURE);
    }

  /* Give the socket a name. */
  name.sin_family = AF_INET;
  name.sin_port = htons (port);
  name.sin_addr.s_addr = htonl (INADDR_ANY);
  if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0)
    {
      perror ("bind");
      exit (EXIT_FAILURE);
    }

  return sock;
}
Here is another example, showing how you can fill in a sockaddr_in structure, given a host name string and a port number:
#include <stdio.h>
#include <stdlib.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>

void
init_sockaddr (struct sockaddr_in *name,
               const char *hostname,
               uint16_t port)
{
  struct hostent *hostinfo;

  name->sin_family = AF_INET;
  name->sin_port = htons (port);
  hostinfo = gethostbyname (hostname);
  if (hostinfo == NULL)
    {
      fprintf (stderr, "Unknown host %s.\n", hostname);
      exit (EXIT_FAILURE);
    }
  name->sin_addr = *(struct in_addr *) hostinfo->h_addr;
}
Other Namespaces

Certain other namespaces and associated protocol families are supported but not documented yet because they are not often used. PF_NS refers to the Xerox Network Software protocols. PF_ISO stands for Open Systems Interconnect. PF_CCITT refers to protocols from CCITT. `socket.h' defines these symbols and others naming protocols not actually implemented.

PF_IMPLINK is used for communicating between hosts and Internet Message Processors. For information on this and PF_ROUTE, an occasionally-used local area routing protocol, see the GNU Hurd Manual (to appear in the future).

Opening and Closing Sockets

This section describes the actual library functions for opening and closing sockets. The same functions work for all namespaces and connection styles.

Creating a Socket

The primitive for creating a socket is the socket function, declared in `sys/socket.h'.

Function: int socket (int namespace, int style, int protocol)
This function creates a socket and specifies communication style style, which should be one of the socket styles listed in section Communication Styles. The namespace argument specifies the namespace; it must be PF_LOCAL (see section The Local Namespace) or PF_INET (see section The Internet Namespace). protocol designates the specific protocol (see section Socket Concepts); zero is usually right for protocol.

The return value from socket is the file descriptor for the new socket, or -1 in case of error. The following errno error conditions are defined for this function:

EPROTONOSUPPORT
The protocol or style is not supported by the namespace specified.
EMFILE
The process already has too many file descriptors open.
ENFILE
The system already has too many file descriptors open.
EACCESS
The process does not have the privilege to create a socket of the specified style or protocol.
ENOBUFS
The system ran out of internal buffer space.
The file descriptor returned by the socket function supports both read and write operations. However, like pipes, sockets do not support file positioning operations.

For examples of how to call the socket function, see section Example of Local-Namespace Sockets, or section Internet Socket Example.

Closing a Socket

When you have finished using a socket, you can simply close its file descriptor with close; see section Opening and Closing Files. If there is still data waiting to be transmitted over the connection, normally close tries to complete this transmission. You can control this behavior using the SO_LINGER socket option to specify a timeout period; see section Socket Options.

You can also shut down only reception or transmission on a connection by calling shutdown, which is declared in `sys/socket.h'.

Function: int shutdown (int socket, int how)
The shutdown function shuts down the connection of socket socket. The argument how specifies what action to perform:

0
Stop receiving data for this socket. If further data arrives, reject it.
1
Stop trying to transmit data from this socket. Discard any data waiting to be sent. Stop looking for acknowledgement of data already sent; don't retransmit it if it is lost.
2
Stop both reception and transmission.
The return value is 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EBADF
socket is not a valid file descriptor.
ENOTSOCK
socket is not a socket.
ENOTCONN
socket is not connected.
Socket Pairs

A socket pair consists of a pair of connected (but unnamed) sockets. It is very similar to a pipe and is used in much the same way. Socket pairs are created with the socketpair function, declared in `sys/socket.h'. A socket pair is much like a pipe; the main difference is that the socket pair is bidirectional, whereas the pipe has one input-only end and one output-only end (see section Pipes and FIFOs).

Function: int socketpair (int namespace, int style, int protocol, int filedes[2])
This function creates a socket pair, returning the file descriptors in filedes[0] and filedes[1]. The socket pair is a full-duplex communications channel, so that both reading and writing may be performed at either end.

The namespace, style and protocol arguments are interpreted as for the socket function. style should be one of the communication styles listed in section Communication Styles. The namespace argument specifies the namespace, which must be AF_LOCAL (see section The Local Namespace); protocol specifies the communications protocol, but zero is the only meaningful value.

If style specifies a connectionless communication style, then the two sockets you get are not connected, strictly speaking, but each of them knows the other as the default destination address, so they can send packets to each other.

The socketpair function returns 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EMFILE
The process has too many file descriptors open.
EAFNOSUPPORT
The specified namespace is not supported.
EPROTONOSUPPORT
The specified protocol is not supported.
EOPNOTSUPP
The specified protocol does not support the creation of socket pairs.
Using Sockets with Connections

The most common communication styles involve making a connection to a particular other socket, and then exchanging data with that socket over and over. Making a connection is asymmetric; one side (the client) acts to request a connection, while the other side (the server) makes a socket and waits for the connection request.

section Making a Connection, describes what the client program must do to initiate a connection with a server.
section Listening for Connections and section Accepting Connections describe what the server program must do to wait for and act upon connection requests from clients.
section Transferring Data, describes how data are transferred through the connected socket.

Making a Connection

In making a connection, the client makes a connection while the server waits for and accepts the connection. Here we discuss what the client program must do with the connect function, which is declared in `sys/socket.h'.

Function: int connect (int socket, struct sockaddr *addr, socklen_t length)
The connect function initiates a connection from the socket with file descriptor socket to the socket whose address is specified by the addr and length arguments. (This socket is typically on another machine, and it must be already set up as a server.) See section Socket Addresses, for information about how these arguments are interpreted.

Normally, connect waits until the server responds to the request before it returns. You can set nonblocking mode on the socket socket to make connect return immediately without waiting for the response. See section File Status Flags, for information about nonblocking mode.

The normal return value from connect is 0. If an error occurs, connect returns -1. The following errno error conditions are defined for this function:

EBADF
The socket socket is not a valid file descriptor.
ENOTSOCK
File descriptor socket is not a socket.
EADDRNOTAVAIL
The specified address is not available on the remote machine.
EAFNOSUPPORT
The namespace of the addr is not supported by this socket.
EISCONN
The socket socket is already connected.
ETIMEDOUT
The attempt to establish the connection timed out.
ECONNREFUSED
The server has actively refused to establish the connection.
ENETUNREACH
The network of the given addr isn't reachable from this host.
EADDRINUSE
The socket address of the given addr is already in use.
EINPROGRESS
The socket socket is non-blocking and the connection could not be established immediately. You can determine when the connection is completely established with select; see section Waiting for Input or Output. Another connect call on the same socket, before the connection is completely established, will fail with EALREADY.
EALREADY
The socket socket is non-blocking and already has a pending connection in progress (see EINPROGRESS above).
This function is defined as a cancellation point in multi-threaded programs, so one has to be prepared for this and make sure that allocated resources (like memory, files descriptors, semaphores or whatever) are freed even if the thread is canceled.

Listening for Connections

Now let us consider what the server process must do to accept connections on a socket. First it must use the listen function to enable connection requests on the socket, and then accept each incoming connection with a call to accept (see section Accepting Connections). Once connection requests are enabled on a server socket, the select function reports when the socket has a connection ready to be accepted (see section Waiting for Input or Output).

The listen function is not allowed for sockets using connectionless communication styles.

You can write a network server that does not even start running until a connection to it is requested. See section inetd Servers.

In the Internet namespace, there are no special protection mechanisms for controlling access to a port; any process on any machine can make a connection to your server. If you want to restrict access to your server, make it examine the addresses associated with connection requests or implement some other handshaking or identification protocol.

In the local namespace, the ordinary file protection bits control who has access to connect to the socket.

Function: int listen (int socket, unsigned int n)
The listen function enables the socket socket to accept connections, thus making it a server socket.

The argument n specifies the length of the queue for pending connections. When the queue fills, new clients attempting to connect fail with ECONNREFUSED until the server calls accept to accept a connection from the queue.

The listen function returns 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EBADF
The argument socket is not a valid file descriptor.
ENOTSOCK
The argument socket is not a socket.
EOPNOTSUPP
The socket socket does not support this operation.
Accepting Connections

When a server receives a connection request, it can complete the connection by accepting the request. Use the function accept to do this.

A socket that has been established as a server can accept connection requests from multiple clients. The server's original socket does not become part of the connection; instead, accept makes a new socket which participates in the connection. accept returns the descriptor for this socket. The server's original socket remains available for listening for further connection requests.

The number of pending connection requests on a server socket is finite. If connection requests arrive from clients faster than the server can act upon them, the queue can fill up and additional requests are refused with an ECONNREFUSED error. You can specify the maximum length of this queue as an argument to the listen function, although the system may also impose its own internal limit on the length of this queue.

Function: int accept (int socket, struct sockaddr *addr, socklen_t *length_ptr)
This function is used to accept a connection request on the server socket socket.

The accept function waits if there are no connections pending, unless the socket socket has nonblocking mode set. (You can use select to wait for a pending connection, with a nonblocking socket.) See section File Status Flags, for information about nonblocking mode.

The addr and length-ptr arguments are used to return information about the name of the client socket that initiated the connection. See section Socket Addresses, for information about the format of the information.

Accepting a connection does not make socket part of the connection. Instead, it creates a new socket which becomes connected. The normal return value of accept is the file descriptor for the new socket.

After accept, the original socket socket remains open and unconnected, and continues listening until you close it. You can accept further connections with socket by calling accept again.

If an error occurs, accept returns -1. The following errno error conditions are defined for this function:

EBADF
The socket argument is not a valid file descriptor.
ENOTSOCK
The descriptor socket argument is not a socket.
EOPNOTSUPP
The descriptor socket does not support this operation.
EWOULDBLOCK
socket has nonblocking mode set, and there are no pending connections immediately available.
This function is defined as a cancellation point in multi-threaded programs, so one has to be prepared for this and make sure that allocated resources (like memory, files descriptors, semaphores or whatever) are freed even if the thread is canceled.

The accept function is not allowed for sockets using connectionless communication styles.

Who is Connected to Me?

Function: int getpeername (int socket, struct sockaddr *addr, socklen_t *length-ptr)
The getpeername function returns the address of the socket that socket is connected to; it stores the address in the memory space specified by addr and length-ptr. It stores the length of the address in *length-ptr.

See section Socket Addresses, for information about the format of the address. In some operating systems, getpeername works only for sockets in the Internet domain.

The return value is 0 on success and -1 on error. The following errno error conditions are defined for this function:

EBADF
The argument socket is not a valid file descriptor.
ENOTSOCK
The descriptor socket is not a socket.
ENOTCONN
The socket socket is not connected.
ENOBUFS
There are not enough internal buffers available.
Transferring Data

Once a socket has been connected to a peer, you can use the ordinary read and write operations (see section Input and Output Primitives) to transfer data. A socket is a two-way communications channel, so read and write operations can be performed at either end.

There are also some I/O modes that are specific to socket operations. In order to specify these modes, you must use the recv and send functions instead of the more generic read and write functions. The recv and send functions take an additional argument which you can use to specify various flags to control special I/O modes. For example, you can specify the MSG_OOB flag to read or write out-of-band data, the MSG_PEEK flag to peek at input, or the MSG_DONTROUTE flag to control inclusion of routing information on output.

Sending Data

The send function is declared in the header file `sys/socket.h'. If your flags argument is zero, you can just as well use write instead of send; see section Input and Output Primitives. If the socket was connected but the connection has broken, you get a SIGPIPE signal for any use of send or write (see section Miscellaneous Signals).

Function: int send (int socket, void *buffer, size_t size, int flags)
The send function is like write, but with the additional flags flags. The possible values of flags are described in section Socket Data Options.

This function returns the number of bytes transmitted, or -1 on failure. If the socket is nonblocking, then send (like write) can return after sending just part of the data. See section File Status Flags, for information about nonblocking mode.

Note, however, that a successful return value merely indicates that the message has been sent without error, not necessarily that it has been received without error.

The following errno error conditions are defined for this function:

EBADF
The socket argument is not a valid file descriptor.
EINTR
The operation was interrupted by a signal before any data was sent. See section Primitives Interrupted by Signals.
ENOTSOCK
The descriptor socket is not a socket.
EMSGSIZE
The socket type requires that the message be sent atomically, but the message is too large for this to be possible.
EWOULDBLOCK
Nonblocking mode has been set on the socket, and the write operation would block. (Normally send blocks until the operation can be completed.)
ENOBUFS
There is not enough internal buffer space available.
ENOTCONN
You never connected this socket.
EPIPE
This socket was connected but the connection is now broken. In this case, send generates a SIGPIPE signal first; if that signal is ignored or blocked, or if its handler returns, then send fails with EPIPE.
This function is defined as a cancellation point in multi-threaded programs, so one has to be prepared for this and make sure that allocated resources (like memory, files descriptors, semaphores or whatever) are freed even if the thread is canceled.

Receiving Data

The recv function is declared in the header file `sys/socket.h'. If your flags argument is zero, you can just as well use read instead of recv; see section Input and Output Primitives.

Function: int recv (int socket, void *buffer, size_t size, int flags)
The recv function is like read, but with the additional flags flags. The possible values of flags are described in section Socket Data Options.

If nonblocking mode is set for socket, and no data are available to be read, recv fails immediately rather than waiting. See section File Status Flags, for information about nonblocking mode.

This function returns the number of bytes received, or -1 on failure. The following errno error conditions are defined for this function:

EBADF
The socket argument is not a valid file descriptor.
ENOTSOCK
The descriptor socket is not a socket.
EWOULDBLOCK
Nonblocking mode has been set on the socket, and the read operation would block. (Normally, recv blocks until there is input available to be read.)
EINTR
The operation was interrupted by a signal before any data was read. See section Primitives Interrupted by Signals.
ENOTCONN
You never connected this socket.
This function is defined as a cancellation point in multi-threaded programs, so one has to be prepared for this and make sure that allocated resources (like memory, files descriptors, semaphores or whatever) are freed even if the thread is canceled.

Socket Data Options

The flags argument to send and recv is a bit mask. You can bitwise-OR the values of the following macros together to obtain a value for this argument. All are defined in the header file `sys/socket.h'.

Macro: int MSG_OOB
Send or receive out-of-band data. See section Out-of-Band Data.

Macro: int MSG_PEEK
Look at the data but don't remove it from the input queue. This is only meaningful with input functions such as recv, not with send.

Macro: int MSG_DONTROUTE
Don't include routing information in the message. This is only meaningful with output operations, and is usually only of interest for diagnostic or routing programs. We don't try to explain it here.

Byte Stream Socket Example

Here is an example client program that makes a connection for a byte stream socket in the Internet namespace. It doesn't do anything particularly interesting once it has connected to the server; it just sends a text string to the server and exits.

This program uses init_sockaddr to set up the socket address; see section Internet Socket Example.
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>

#define PORT            5555
#define MESSAGE         "Yow!!! Are we having fun yet?!?"
#define SERVERHOST      "mescaline.gnu.org"

void
write_to_server (int filedes)
{
  int nbytes;

  nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
  if (nbytes < 0)
    {
      perror ("write");
      exit (EXIT_FAILURE);
    }
}

int
main (void)
{
  extern void init_sockaddr (struct sockaddr_in *name,
                             const char *hostname,
                             uint16_t port);
  int sock;
  struct sockaddr_in servername;

  /* Create the socket. */
  sock = socket (PF_INET, SOCK_STREAM, 0);
  if (sock < 0)
    {
      perror ("socket (client)");
      exit (EXIT_FAILURE);
    }

  /* Connect to the server. */
  init_sockaddr (&servername, SERVERHOST, PORT);
  if (0 > connect (sock,
                   (struct sockaddr *) &servername,
                   sizeof (servername)))
    {
      perror ("connect (client)");
      exit (EXIT_FAILURE);
    }

  /* Send data to the server. */
  write_to_server (sock);
  close (sock);
  exit (EXIT_SUCCESS);
}
Byte Stream Connection Server Example

The server end is much more complicated. Since we want to allow multiple clients to be connected to the server at the same time, it would be incorrect to wait for input from a single client by simply calling read or recv. Instead, the right thing to do is to use select (see section Waiting for Input or Output) to wait for input on all of the open sockets. This also allows the server to deal with additional connection requests.

This particular server doesn't do anything interesting once it has gotten a message from a client. It does close the socket for that client when it detects an end-of-file condition (resulting from the client shutting down its end of the connection).

This program uses make_socket to set up the socket address; see section Internet Socket Example.
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>

#define PORT    5555
#define MAXMSG  512

int
read_from_client (int filedes)
{
  char buffer[MAXMSG];
  int nbytes;

  nbytes = read (filedes, buffer, MAXMSG);
  if (nbytes < 0)
    {
      /* Read error. */
      perror ("read");
      exit (EXIT_FAILURE);
    }
  else if (nbytes == 0)
    /* End-of-file. */
    return -1;
  else
    {
      /* Data read. */
      fprintf (stderr, "Server: got message: `%s'\n", buffer);
      return 0;
    }
}

int
main (void)
{
  extern int make_socket (uint16_t port);
  int sock;
  fd_set active_fd_set, read_fd_set;
  int i;
  struct sockaddr_in clientname;
  size_t size;

  /* Create the socket and set it up to accept connections. */
  sock = make_socket (PORT);
  if (listen (sock, 1) < 0)
    {
      perror ("listen");
      exit (EXIT_FAILURE);
    }

  /* Initialize the set of active sockets. */
  FD_ZERO (&active_fd_set);
  FD_SET (sock, &active_fd_set);

  while (1)
    {
      /* Block until input arrives on one or more active sockets. */
      read_fd_set = active_fd_set;
      if (select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL) < 0)
        {
          perror ("select");
          exit (EXIT_FAILURE);
        }

      /* Service all the sockets with input pending. */
      for (i = 0; i < FD_SETSIZE; ++i)
        if (FD_ISSET (i, &read_fd_set))
          {
            if (i == sock)
              {
                /* Connection request on original socket. */
                int new;
                size = sizeof (clientname);
                new = accept (sock,
                              (struct sockaddr *) &clientname,
                              &size);
                if (new < 0)
                  {
                    perror ("accept");
                    exit (EXIT_FAILURE);
                  }
                fprintf (stderr,
                         "Server: connect from host %s, port %hd.\n",
                         inet_ntoa (clientname.sin_addr),
                         ntohs (clientname.sin_port));
                FD_SET (new, &active_fd_set);
              }
            else
              {
                /* Data arriving on an already-connected socket. */
                if (read_from_client (i) < 0)
                  {
                    close (i);
                    FD_CLR (i, &active_fd_set);
                  }
              }
          }
    }
}
Out-of-Band Data

Streams with connections permit out-of-band data that is delivered with higher priority than ordinary data. Typically the reason for sending out-of-band data is to send notice of an exceptional condition. To send out-of-band data use send, specifying the flag MSG_OOB (see section Sending Data).

Out-of-band data are received with higher priority because the receiving process need not read it in sequence; to read the next available out-of-band data, use recv with the MSG_OOB flag (see section Receiving Data). Ordinary read operations do not read out-of-band data; they read only ordinary data.

When a socket finds that out-of-band data are on their way, it sends a SIGURG signal to the owner process or process group of the socket. You can specify the owner using the F_SETOWN command to the fcntl function; see section Interrupt-Driven Input. You must also establish a handler for this signal, as described in section Signal Handling, in order to take appropriate action such as reading the out-of-band data.

Alternatively, you can test for pending out-of-band data, or wait until there is out-of-band data, using the select function; it can wait for an exceptional condition on the socket. See section Waiting for Input or Output, for more information about select.

Notification of out-of-band data (whether with SIGURG or with select) indicates that out-of-band data are on the way; the data may not actually arrive until later. If you try to read the out-of-band data before it arrives, recv fails with an EWOULDBLOCK error.

Sending out-of-band data automatically places a "mark" in the stream of ordinary data, showing where in the sequence the out-of-band data "would have been". This is useful when the meaning of out-of-band data is "cancel everything sent so far". Here is how you can test, in the receiving process, whether any ordinary data was sent before the mark:
success = ioctl (socket, SIOCATMARK, &atmark);
The integer variable atmark is set to a nonzero value if the socket's read pointer has reached the "mark".

Here's a function to discard any ordinary data preceding the out-of-band mark:
int
discard_until_mark (int socket)
{
  while (1)
    {
      /* This is not an arbitrary limit; any size will do.  */
      char buffer[1024];
      int atmark, success;

      /* If we have reached the mark, return.  */
      success = ioctl (socket, SIOCATMARK, &atmark);
      if (success < 0)
        perror ("ioctl");
      if (result)
        return;

      /* Otherwise, read a bunch of ordinary data and discard it.
         This is guaranteed not to read past the mark
         if it starts before the mark.  */
      success = read (socket, buffer, sizeof buffer);
      if (success < 0)
        perror ("read");
    }
}
If you don't want to discard the ordinary data preceding the mark, you may need to read some of it anyway, to make room in internal system buffers for the out-of-band data. If you try to read out-of-band data and get an EWOULDBLOCK error, try reading some ordinary data (saving it so that you can use it when you want it) and see if that makes room. Here is an example:
struct buffer
{
  char *buf;
  int size;
  struct buffer *next;
};

/* Read the out-of-band data from SOCKET and return it
   as a `struct buffer', which records the address of the data
   and its size.

   It may be necessary to read some ordinary data
   in order to make room for the out-of-band data.
   If so, the ordinary data are saved as a chain of buffers
   found in the `next' field of the value.  */

struct buffer *
read_oob (int socket)
{
  struct buffer *tail = 0;
  struct buffer *list = 0;

  while (1)
    {
      /* This is an arbitrary limit.
         Does anyone know how to do this without a limit?  */
#define BUF_SZ 1024
      char *buf = (char *) xmalloc (BUF_SZ);
      int success;
      int atmark;

      /* Try again to read the out-of-band data.  */
      success = recv (socket, buf, BUF_SZ, MSG_OOB);
      if (success >= 0)
        {
          /* We got it, so return it.  */
          struct buffer *link
            = (struct buffer *) xmalloc (sizeof (struct buffer));
          link->buf = buf;
          link->size = success;
          link->next = list;
          return link;
        }

      /* If we fail, see if we are at the mark.  */
      success = ioctl (socket, SIOCATMARK, &atmark);
      if (success < 0)
        perror ("ioctl");
      if (atmark)
        {
          /* At the mark; skipping past more ordinary data cannot help.
             So just wait a while.  */
          sleep (1);
          continue;
        }

      /* Otherwise, read a bunch of ordinary data and save it.
         This is guaranteed not to read past the mark
         if it starts before the mark.  */
      success = read (socket, buf, BUF_SZ);
      if (success < 0)
        perror ("read");

      /* Save this data in the buffer list.  */
      {
        struct buffer *link
          = (struct buffer *) xmalloc (sizeof (struct buffer));
        link->buf = buf;
        link->size = success;

        /* Add the new link to the end of the list.  */
        if (tail)
          tail->next = link;
        else
          list = link;
        tail = link;
      }
    }
}
Datagram Socket Operations

This section describes how to use communication styles that don't use connections (styles SOCK_DGRAM and SOCK_RDM). Using these styles, you group data into packets and each packet is an independent communication. You specify the destination for each packet individually.

Datagram packets are like letters: you send each one independently with its own destination address, and they may arrive in the wrong order or not at all.

The listen and accept functions are not allowed for sockets using connectionless communication styles.

Sending Datagrams

The normal way of sending data on a datagram socket is by using the sendto function, declared in `sys/socket.h'.

You can call connect on a datagram socket, but this only specifies a default destination for further data transmission on the socket. When a socket has a default destination you can use send (see section Sending Data) or even write (see section Input and Output Primitives) to send a packet there. You can cancel the default destination by calling connect using an address format of AF_UNSPEC in the addr argument. See section Making a Connection, for more information about the connect function.

Function: int sendto (int socket, void *buffer. size_t size, int flags, struct sockaddr *addr, socklen_t length)
The sendto function transmits the data in the buffer through the socket socket to the destination address specified by the addr and length arguments. The size argument specifies the number of bytes to be transmitted.

The flags are interpreted the same way as for send; see section Socket Data Options.

The return value and error conditions are also the same as for send, but you cannot rely on the system to detect errors and report them; the most common error is that the packet is lost or there is no-one at the specified address to receive it, and the operating system on your machine usually does not know this.

It is also possible for one call to sendto to report an error owing to a problem related to a previous call.

This function is defined as a cancellation point in multi-threaded programs, so one has to be prepared for this and make sure that allocated resources (like memory, files descriptors, semaphores or whatever) are freed even if the thread is canceled.

Receiving Datagrams

The recvfrom function reads a packet from a datagram socket and also tells you where it was sent from. This function is declared in `sys/socket.h'.

Function: int recvfrom (int socket, void *buffer, size_t size, int flags, struct sockaddr *addr, socklen_t *length-ptr)
The recvfrom function reads one packet from the socket socket into the buffer buffer. The size argument specifies the maximum number of bytes to be read.

If the packet is longer than size bytes, then you get the first size bytes of the packet and the rest of the packet is lost. There's no way to read the rest of the packet. Thus, when you use a packet protocol, you must always know how long a packet to expect.

The addr and length-ptr arguments are used to return the address where the packet came from. See section Socket Addresses. For a socket in the local domain the address information won't be meaningful, since you can't read the address of such a socket (see section The Local Namespace). You can specify a null pointer as the addr argument if you are not interested in this information.

The flags are interpreted the same way as for recv (see section Socket Data Options). The return value and error conditions are also the same as for recv.

This function is defined as a cancellation point in multi-threaded programs, so one has to be prepared for this and make sure that allocated resources (like memory, files descriptors, semaphores or whatever) are freed even if the thread is canceled.

You can use plain recv (see section Receiving Data) instead of recvfrom if you don't need to find out who sent the packet (either because you know where it should come from or because you treat all possible senders alike). Even read can be used if you don't want to specify flags (see section Input and Output Primitives).

Datagram Socket Example

Here is a set of example programs that send messages over a datagram stream in the local namespace. Both the client and server programs use the make_named_socket function that was presented in section Example of Local-Namespace Sockets, to create and name their sockets.

First, here is the server program. It sits in a loop waiting for messages to arrive, bouncing each message back to the sender. Obviously this isn't a particularly useful program, but it does show the general ideas involved.
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <sys/socket.h>
#include <sys/un.h>

#define SERVER  "/tmp/serversocket"
#define MAXMSG  512

int
main (void)
{
  int sock;
  char message[MAXMSG];
  struct sockaddr_un name;
  size_t size;
  int nbytes;

  /* Remove the filename first, it's ok if the call fails */
  unlink (SERVER);

  /* Make the socket, then loop endlessly. */
  sock = make_named_socket (SERVER);
  while (1)
    {
      /* Wait for a datagram. */
      size = sizeof (name);
      nbytes = recvfrom (sock, message, MAXMSG, 0,
                         (struct sockaddr *) & name, &size);
      if (nbytes < 0)
        {
          perror ("recfrom (server)");
          exit (EXIT_FAILURE);
        }

      /* Give a diagnostic message. */
      fprintf (stderr, "Server: got message: %s\n", message);

      /* Bounce the message back to the sender. */
      nbytes = sendto (sock, message, nbytes, 0,
                       (struct sockaddr *) & name, size);
      if (nbytes < 0)
        {
          perror ("sendto (server)");
          exit (EXIT_FAILURE);
        }
    }
}
Example of Reading Datagrams

Here is the client program corresponding to the server above.

It sends a datagram to the server and then waits for a reply. Notice that the socket for the client (as well as for the server) in this example has to be given a name. This is so that the server can direct a message back to the client. Since the socket has no associated connection state, the only way the server can do this is by referencing the name of the client.
#include <stdio.h>
#include <errno.h>
#include <unistd.h>
#include <stdlib.h>
#include <sys/socket.h>
#include <sys/un.h>

#define SERVER  "/tmp/serversocket"
#define CLIENT  "/tmp/mysocket"
#define MAXMSG  512
#define MESSAGE "Yow!!! Are we having fun yet?!?"

int
main (void)
{
  extern int make_named_socket (const char *name);
  int sock;
  char message[MAXMSG];
  struct sockaddr_un name;
  size_t size;
  int nbytes;

  /* Make the socket. */
  sock = make_named_socket (CLIENT);

  /* Initialize the server socket address. */
  name.sun_family = AF_LOCAL;
  strcpy (name.sun_path, SERVER);
  size = strlen (name.sun_path) + sizeof (name.sun_family);

  /* Send the datagram. */
  nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
                   (struct sockaddr *) & name, size);
  if (nbytes < 0)
    {
      perror ("sendto (client)");
      exit (EXIT_FAILURE);
    }

  /* Wait for a reply. */
  nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
  if (nbytes < 0)
    {
      perror ("recfrom (client)");
      exit (EXIT_FAILURE);
    }

  /* Print a diagnostic message. */
  fprintf (stderr, "Client: got message: %s\n", message);

  /* Clean up. */
  remove (CLIENT);
  close (sock);
}
Keep in mind that datagram socket communications are unreliable. In this example, the client program waits indefinitely if the message never reaches the server or if the server's response never comes back. It's up to the user running the program to kill and restart it if desired. A more automatic solution could be to use select (see section Waiting for Input or Output) to establish a timeout period for the reply, and in case of timeout either re-send the message or shut down the socket and exit.

The inetd Daemon

We've explained above how to write a server program that does its own listening. Such a server must already be running in order for anyone to connect to it.

Another way to provide a service on an Internet port is to let the daemon program inetd do the listening. inetd is a program that runs all the time and waits (using select) for messages on a specified set of ports. When it receives a message, it accepts the connection (if the socket style calls for connections) and then forks a child process to run the corresponding server program. You specify the ports and their programs in the file `/etc/inetd.conf'.

inetd Servers

Writing a server program to be run by inetd is very simple. Each time someone requests a connection to the appropriate port, a new server process starts. The connection already exists at this time; the socket is available as the standard input descriptor and as the standard output descriptor (descriptors 0 and 1) in the server process. Thus the server program can begin reading and writing data right away. Often the program needs only the ordinary I/O facilities; in fact, a general-purpose filter program that knows nothing about sockets can work as a byte stream server run by inetd.

You can also use inetd for servers that use connectionless communication styles. For these servers, inetd does not try to accept a connection since no connection is possible. It just starts the server program, which can read the incoming datagram packet from descriptor 0. The server program can handle one request and then exit, or you can choose to write it to keep reading more requests until no more arrive, and then exit. You must specify which of these two techniques the server uses when you configure inetd.

Configuring inetd

The file `/etc/inetd.conf' tells inetd which ports to listen to and what server programs to run for them. Normally each entry in the file is one line, but you can split it onto multiple lines provided all but the first line of the entry start with whitespace. Lines that start with `#' are comments.

Here are two standard entries in `/etc/inetd.conf':
ftp	stream	tcp	nowait	root	/libexec/ftpd	ftpd
talk	dgram	udp	wait	root	/libexec/talkd	talkd
An entry has this format:
service style protocol wait username program arguments
The service field says which service this program provides. It should be the name of a service defined in `/etc/services'. inetd uses service to decide which port to listen on for this entry.

The fields style and protocol specify the communication style and the protocol to use for the listening socket. The style should be the name of a communication style, converted to lower case and with `SOCK_' deleted--for example, `stream' or `dgram'. protocol should be one of the protocols listed in `/etc/protocols'. The typical protocol names are `tcp' for byte stream connections and `udp' for unreliable datagrams.

The wait field should be either `wait' or `nowait'. Use `wait' if style is a connectionless style and the server, once started, handles multiple requests as they come in. Use `nowait' if inetd should start a new process for each message or request that comes in. If style uses connections, then wait must be `nowait'.

user is the user name that the server should run as. inetd runs as root, so it can set the user ID of its children arbitrarily. It's best to avoid using `root' for user if you can; but some servers, such as Telnet and FTP, read a username and password themselves. These servers need to be root initially so they can log in as commanded by the data coming over the network.

program together with arguments specifies the command to run to start the server. program should be an absolute file name specifying the executable file to run. arguments consists of any number of whitespace-separated words, which become the command-line arguments of program. The first word in arguments is argument zero, which should by convention be the program name itself (sans directories).

If you edit `/etc/inetd.conf', you can tell inetd to reread the file and obey its new contents by sending the inetd process the SIGHUP signal. You'll have to use ps to determine the process ID of the inetd process as it is not fixed.

Socket Options

This section describes how to read or set various options that modify the behavior of sockets and their underlying communications protocols.

When you are manipulating a socket option, you must specify which level the option pertains to. This describes whether the option applies to the socket interface, or to a lower-level communications protocol interface.

Socket Option Functions

Here are the functions for examining and modifying socket options. They are declared in `sys/socket.h'.

Function: int getsockopt (int socket, int level, int optname, void *optval, socklen_t *optlen-ptr)
The getsockopt function gets information about the value of option optname at level level for socket socket.

The option value is stored in a buffer that optval points to. Before the call, you should supply in *optlen-ptr the size of this buffer; on return, it contains the number of bytes of information actually stored in the buffer.

Most options interpret the optval buffer as a single int value.

The actual return value of getsockopt is 0 on success and -1 on failure. The following errno error conditions are defined:

EBADF
The socket argument is not a valid file descriptor.
ENOTSOCK
The descriptor socket is not a socket.
ENOPROTOOPT
The optname doesn't make sense for the given level.

Function: int setsockopt (int socket, int level, int optname, void *optval, socklen_t optlen)
This function is used to set the socket option optname at level level for socket socket. The value of the option is passed in the buffer optval of size optlen.

@hfuzz 6pt The return value and error codes for setsockopt are the same as for getsockopt.

Socket-Level Options

Constant: int SOL_SOCKET
Use this constant as the level argument to getsockopt or setsockopt to manipulate the socket-level options described in this section.

Here is a table of socket-level option names; all are defined in the header file `sys/socket.h'.

SO_DEBUG
This option toggles recording of debugging information in the underlying protocol modules. The value has type int; a nonzero value means "yes".
SO_REUSEADDR
This option controls whether bind (see section Setting the Address of a Socket) should permit reuse of local addresses for this socket. If you enable this option, you can actually have two sockets with the same Internet port number; but the system won't allow you to use the two identically-named sockets in a way that would confuse the Internet. The reason for this option is that some higher-level Internet protocols, including FTP, require you to keep reusing the same port number. The value has type int; a nonzero value means "yes".
SO_KEEPALIVE
This option controls whether the underlying protocol should periodically transmit messages on a connected socket. If the peer fails to respond to these messages, the connection is considered broken. The value has type int; a nonzero value means "yes".
SO_DONTROUTE
This option controls whether outgoing messages bypass the normal message routing facilities. If set, messages are sent directly to the network interface instead. The value has type int; a nonzero value means "yes".
SO_LINGER
This option specifies what should happen when the socket of a type that promises reliable delivery still has untransmitted messages when it is closed; see section Closing a Socket. The value has type struct linger.
Data Type: struct linger
This structure type has the following members:
int l_onoff
This field is interpreted as a boolean. If nonzero, close blocks until the data are transmitted or the timeout period has expired.
int l_linger
This specifies the timeout period, in seconds.
SO_BROADCAST
This option controls whether datagrams may be broadcast from the socket. The value has type int; a nonzero value means "yes".
SO_OOBINLINE
If this option is set, out-of-band data received on the socket is placed in the normal input queue. This permits it to be read using read or recv without specifying the MSG_OOB flag. See section Out-of-Band Data. The value has type int; a nonzero value means "yes".
SO_SNDBUF
This option gets or sets the size of the output buffer. The value is a size_t, which is the size in bytes.
SO_RCVBUF
This option gets or sets the size of the input buffer. The value is a size_t, which is the size in bytes.
SO_STYLE

SO_TYPE
This option can be used with getsockopt only. It is used to get the socket's communication style. SO_TYPE is the historical name, and SO_STYLE is the preferred name in GNU. The value has type int and its value designates a communication style; see section Communication Styles.
SO_ERROR
This option can be used with getsockopt only. It is used to reset the error status of the socket. The value is an int, which represents the previous error status.
Networks Database

Many systems come with a database that records a list of networks known to the system developer. This is usually kept either in the file `/etc/networks' or in an equivalent from a name server. This data base is useful for routing programs such as route, but it is not useful for programs that simply communicate over the network. We provide functions to access this database, which are declared in `netdb.h'.

Data Type: struct netent
This data type is used to represent information about entries in the networks database. It has the following members:

char *n_name
This is the "official" name of the network.
char **n_aliases
These are alternative names for the network, represented as a vector of strings. A null pointer terminates the array.
int n_addrtype
This is the type of the network number; this is always equal to AF_INET for Internet networks.
unsigned long int n_net
This is the network number. Network numbers are returned in host byte order; see section Byte Order Conversion.
Use the getnetbyname or getnetbyaddr functions to search the networks database for information about a specific network. The information is returned in a statically-allocated structure; you must copy the information if you need to save it.

Function: struct netent * getnetbyname (const char *name)
The getnetbyname function returns information about the network named name. It returns a null pointer if there is no such network.

Function: struct netent * getnetbyaddr (unsigned long int net, int type)
The getnetbyaddr function returns information about the network of type type with number net. You should specify a value of AF_INET for the type argument for Internet networks.

getnetbyaddr returns a null pointer if there is no such network.

You can also scan the networks database using setnetent, getnetent and endnetent. Be careful when using these functions because they are not reentrant.

Function: void setnetent (int stayopen)
This function opens and rewinds the networks database.

If the stayopen argument is nonzero, this sets a flag so that subsequent calls to getnetbyname or getnetbyaddr will not close the database (as they usually would). This makes for more efficiency if you call those functions several times, by avoiding reopening the database for each call.

Function: struct netent * getnetent (void)
This function returns the next entry in the networks database. It returns a null pointer if there are no more entries.

Function: void endnetent (void)
This function closes the networks database.
Low-Level Terminal Interface

This chapter describes functions that are specific to terminal devices. You can use these functions to do things like turn off input echoing; set serial line characteristics such as line speed and flow control; and change which characters are used for end-of-file, command-line editing, sending signals, and similar control functions.

Most of the functions in this chapter operate on file descriptors. See section Low-Level Input/Output, for more information about what a file descriptor is and how to open a file descriptor for a terminal device.

Identifying Terminals

The functions described in this chapter only work on files that correspond to terminal devices. You can find out whether a file descriptor is associated with a terminal by using the isatty function.

Prototypes for the functions in this section are declared in the header file `unistd.h'.

Function: int isatty (int filedes)
This function returns 1 if filedes is a file descriptor associated with an open terminal device, and @math{0} otherwise.

If a file descriptor is associated with a terminal, you can get its associated file name using the ttyname function. See also the ctermid function, described in section Identifying the Controlling Terminal.

Function: char * ttyname (int filedes)
If the file descriptor filedes is associated with a terminal device, the ttyname function returns a pointer to a statically-allocated, null-terminated string containing the file name of the terminal file. The value is a null pointer if the file descriptor isn't associated with a terminal, or the file name cannot be determined.

Function: int ttyname_r (int filedes, char *buf, size_t len)
The ttyname_r function is similar to the ttyname function except that it places its result into the user-specified buffer starting at buf with length len.

The normal return value from ttyname_r is @math{0}. Otherwise an error number is returned to indicate the error. The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
ENOTTY
The filedes is not associated with a terminal.
ERANGE
The buffer length len is too small to store the string to be returned.
I/O Queues

Many of the remaining functions in this section refer to the input and output queues of a terminal device. These queues implement a form of buffering within the kernel independent of the buffering implemented by I/O streams (see section Input/Output on Streams).

The terminal input queue is also sometimes referred to as its typeahead buffer. It holds the characters that have been received from the terminal but not yet read by any process.

The size of the input queue is described by the MAX_INPUT and _POSIX_MAX_INPUT parameters; see section Limits on File System Capacity. You are guaranteed a queue size of at least MAX_INPUT, but the queue might be larger, and might even dynamically change size. If input flow control is enabled by setting the IXOFF input mode bit (see section Input Modes), the terminal driver transmits STOP and START characters to the terminal when necessary to prevent the queue from overflowing. Otherwise, input may be lost if it comes in too fast from the terminal. In canonical mode, all input stays in the queue until a newline character is received, so the terminal input queue can fill up when you type a very long line. See section Two Styles of Input: Canonical or Not.

The terminal output queue is like the input queue, but for output; it contains characters that have been written by processes, but not yet transmitted to the terminal. If output flow control is enabled by setting the IXON input mode bit (see section Input Modes), the terminal driver obeys START and STOP characters sent by the terminal to stop and restart transmission of output.

Clearing the terminal input queue means discarding any characters that have been received but not yet read. Similarly, clearing the terminal output queue means discarding any characters that have been written but not yet transmitted.

Two Styles of Input: Canonical or Not

POSIX systems support two basic modes of input: canonical and noncanonical.

In canonical input processing mode, terminal input is processed in lines terminated by newline ('\n'), EOF, or EOL characters. No input can be read until an entire line has been typed by the user, and the read function (see section Input and Output Primitives) returns at most a single line of input, no matter how many bytes are requested.

In canonical input mode, the operating system provides input editing facilities: some characters are interpreted specially to perform editing operations within the current line of text, such as ERASE and KILL. See section Characters for Input Editing.

The constants _POSIX_MAX_CANON and MAX_CANON parameterize the maximum number of bytes which may appear in a single line of canonical input. See section Limits on File System Capacity. You are guaranteed a maximum line length of at least MAX_CANON bytes, but the maximum might be larger, and might even dynamically change size.

In noncanonical input processing mode, characters are not grouped into lines, and ERASE and KILL processing is not performed. The granularity with which bytes are read in noncanonical input mode is controlled by the MIN and TIME settings. See section Noncanonical Input.

Most programs use canonical input mode, because this gives the user a way to edit input line by line. The usual reason to use noncanonical mode is when the program accepts single-character commands or provides its own editing facilities.

The choice of canonical or noncanonical input is controlled by the ICANON flag in the c_lflag member of struct termios. See section Local Modes.

Terminal Modes

This section describes the various terminal attributes that control how input and output are done. The functions, data structures, and symbolic constants are all declared in the header file `termios.h'.

Don't confuse terminal attributes with file attributes. A device special file which is associated with a terminal has file attributes as described in section File Attributes. These are unrelated to the attributes of the terminal device itself, which are discussed in this section.

Terminal Mode Data Types

The entire collection of attributes of a terminal is stored in a structure of type struct termios. This structure is used with the functions tcgetattr and tcsetattr to read and set the attributes.

Data Type: struct termios
Structure that records all the I/O attributes of a terminal. The structure includes at least the following members:

tcflag_t c_iflag
A bit mask specifying flags for input modes; see section Input Modes.
tcflag_t c_oflag
A bit mask specifying flags for output modes; see section Output Modes.
tcflag_t c_cflag
A bit mask specifying flags for control modes; see section Control Modes.
tcflag_t c_lflag
A bit mask specifying flags for local modes; see section Local Modes.
cc_t c_cc[NCCS]
An array specifying which characters are associated with various control functions; see section Special Characters.
The struct termios structure also contains members which encode input and output transmission speeds, but the representation is not specified. See section Line Speed, for how to examine and store the speed values.

The following sections describe the details of the members of the struct termios structure.

Data Type: tcflag_t
This is an unsigned integer type used to represent the various bit masks for terminal flags.

Data Type: cc_t
This is an unsigned integer type used to represent characters associated with various terminal control functions.

Macro: int NCCS
The value of this macro is the number of elements in the c_cc array.

Terminal Mode Functions

Function: int tcgetattr (int filedes, struct termios *termios-p)
This function is used to examine the attributes of the terminal device with file descriptor filedes. The attributes are returned in the structure that termios-p points to.

If successful, tcgetattr returns @math{0}. A return value of @math{-1} indicates an error. The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
ENOTTY
The filedes is not associated with a terminal.

Function: int tcsetattr (int filedes, int when, const struct termios *termios-p)
This function sets the attributes of the terminal device with file descriptor filedes. The new attributes are taken from the structure that termios-p points to.

The when argument specifies how to deal with input and output already queued. It can be one of the following values:

TCSANOW
Make the change immediately.
TCSADRAIN
Make the change after waiting until all queued output has been written. You should usually use this option when changing parameters that affect output.
TCSAFLUSH
This is like TCSADRAIN, but also discards any queued input.
TCSASOFT
This is a flag bit that you can add to any of the above alternatives. Its meaning is to inhibit alteration of the state of the terminal hardware. It is a BSD extension; it is only supported on BSD systems and the GNU system. Using TCSASOFT is exactly the same as setting the CIGNORE bit in the c_cflag member of the structure termios-p points to. See section Control Modes, for a description of CIGNORE.
If this function is called from a background process on its controlling terminal, normally all processes in the process group are sent a SIGTTOU signal, in the same way as if the process were trying to write to the terminal. The exception is if the calling process itself is ignoring or blocking SIGTTOU signals, in which case the operation is performed and no signal is sent. See section Job Control.

If successful, tcsetattr returns @math{0}. A return value of @math{-1} indicates an error. The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
ENOTTY
The filedes is not associated with a terminal.
EINVAL
Either the value of the when argument is not valid, or there is something wrong with the data in the termios-p argument.
Although tcgetattr and tcsetattr specify the terminal device with a file descriptor, the attributes are those of the terminal device itself and not of the file descriptor. This means that the effects of changing terminal attributes are persistent; if another process opens the terminal file later on, it will see the changed attributes even though it doesn't have anything to do with the open file descriptor you originally specified in changing the attributes.

Similarly, if a single process has multiple or duplicated file descriptors for the same terminal device, changing the terminal attributes affects input and output to all of these file descriptors. This means, for example, that you can't open one file descriptor or stream to read from a terminal in the normal line-buffered, echoed mode; and simultaneously have another file descriptor for the same terminal that you use to read from it in single-character, non-echoed mode. Instead, you have to explicitly switch the terminal back and forth between the two modes.

Setting Terminal Modes Properly

When you set terminal modes, you should call tcgetattr first to get the current modes of the particular terminal device, modify only those modes that you are really interested in, and store the result with tcsetattr.

It's a bad idea to simply initialize a struct termios structure to a chosen set of attributes and pass it directly to tcsetattr. Your program may be run years from now, on systems that support members not documented in this manual. The way to avoid setting these members to unreasonable values is to avoid changing them.

What's more, different terminal devices may require different mode settings in order to function properly. So you should avoid blindly copying attributes from one terminal device to another.

When a member contains a collection of independent flags, as the c_iflag, c_oflag and c_cflag members do, even setting the entire member is a bad idea, because particular operating systems have their own flags. Instead, you should start with the current value of the member and alter only the flags whose values matter in your program, leaving any other flags unchanged.

Here is an example of how to set one flag (ISTRIP) in the struct termios structure while properly preserving all the other data in the structure:
int
set_istrip (int desc, int value)
{
  struct termios settings;
  int result;

  result = tcgetattr (desc, &settings);
  if (result < 0)
    {
      perror ("error in tcgetattr");
      return 0;
    }
  settings.c_iflag &= ~ISTRIP;
  if (value)
    settings.c_iflag |= ISTRIP;
  result = tcsetattr (desc, TCSANOW, &settings);
  if (result < 0)
    {
      perror ("error in tcgetattr");
      return;
   }
  return 1;
}
Input Modes

This section describes the terminal attribute flags that control fairly low-level aspects of input processing: handling of parity errors, break signals, flow control, and RET and LFD characters.

All of these flags are bits in the c_iflag member of the struct termios structure. The member is an integer, and you change flags using the operators &, | and ^. Don't try to specify the entire value for c_iflag---instead, change only specific flags and leave the rest untouched (see section Setting Terminal Modes Properly).

Macro: tcflag_t INPCK
If this bit is set, input parity checking is enabled. If it is not set, no checking at all is done for parity errors on input; the characters are simply passed through to the application.

Parity checking on input processing is independent of whether parity detection and generation on the underlying terminal hardware is enabled; see section Control Modes. For example, you could clear the INPCK input mode flag and set the PARENB control mode flag to ignore parity errors on input, but still generate parity on output.

If this bit is set, what happens when a parity error is detected depends on whether the IGNPAR or PARMRK bits are set. If neither of these bits are set, a byte with a parity error is passed to the application as a '\0' character.

Macro: tcflag_t IGNPAR
If this bit is set, any byte with a framing or parity error is ignored. This is only useful if INPCK is also set.

Macro: tcflag_t PARMRK
If this bit is set, input bytes with parity or framing errors are marked when passed to the program. This bit is meaningful only when INPCK is set and IGNPAR is not set.

The way erroneous bytes are marked is with two preceding bytes, 377 and 0. Thus, the program actually reads three bytes for one erroneous byte received from the terminal.

If a valid byte has the value 0377, and ISTRIP (see below) is not set, the program might confuse it with the prefix that marks a parity error. So a valid byte 0377 is passed to the program as two bytes, 0377 0377, in this case.

Macro: tcflag_t ISTRIP
If this bit is set, valid input bytes are stripped to seven bits; otherwise, all eight bits are available for programs to read.

Macro: tcflag_t IGNBRK
If this bit is set, break conditions are ignored.

A break condition is defined in the context of asynchronous serial data transmission as a series of zero-value bits longer than a single byte.

Macro: tcflag_t BRKINT
If this bit is set and IGNBRK is not set, a break condition clears the terminal input and output queues and raises a SIGINT signal for the foreground process group associated with the terminal.

If neither BRKINT nor IGNBRK are set, a break condition is passed to the application as a single '\0' character if PARMRK is not set, or otherwise as a three-character sequence '\377', '\0', '\0'.

Macro: tcflag_t IGNCR
If this bit is set, carriage return characters ('\r') are discarded on input. Discarding carriage return may be useful on terminals that send both carriage return and linefeed when you type the RET key.

Macro: tcflag_t ICRNL
If this bit is set and IGNCR is not set, carriage return characters ('\r') received as input are passed to the application as newline characters ('\n').

Macro: tcflag_t INLCR
If this bit is set, newline characters ('\n') received as input are passed to the application as carriage return characters ('\r').

Macro: tcflag_t IXOFF
If this bit is set, start/stop control on input is enabled. In other words, the computer sends STOP and START characters as necessary to prevent input from coming in faster than programs are reading it. The idea is that the actual terminal hardware that is generating the input data responds to a STOP character by suspending transmission, and to a START character by resuming transmission. See section Special Characters for Flow Control.

Macro: tcflag_t IXON
If this bit is set, start/stop control on output is enabled. In other words, if the computer receives a STOP character, it suspends output until a START character is received. In this case, the STOP and START characters are never passed to the application program. If this bit is not set, then START and STOP can be read as ordinary characters. See section Special Characters for Flow Control.

Macro: tcflag_t IXANY
If this bit is set, any input character restarts output when output has been suspended with the STOP character. Otherwise, only the START character restarts output.

This is a BSD extension; it exists only on BSD systems and the GNU system.

Macro: tcflag_t IMAXBEL
If this bit is set, then filling up the terminal input buffer sends a BEL character (code 007) to the terminal to ring the bell.

This is a BSD extension.

Output Modes

This section describes the terminal flags and fields that control how output characters are translated and padded for display. All of these are contained in the c_oflag member of the struct termios structure.

The c_oflag member itself is an integer, and you change the flags and fields using the operators &, |, and ^. Don't try to specify the entire value for c_oflag---instead, change only specific flags and leave the rest untouched (see section Setting Terminal Modes Properly).

Macro: tcflag_t OPOST
If this bit is set, output data is processed in some unspecified way so that it is displayed appropriately on the terminal device. This typically includes mapping newline characters ('\n') onto carriage return and linefeed pairs.

If this bit isn't set, the characters are transmitted as-is.

The following three bits are BSD features, and they exist only BSD systems and the GNU system. They are effective only if OPOST is set.

Macro: tcflag_t ONLCR
If this bit is set, convert the newline character on output into a pair of characters, carriage return followed by linefeed.

Macro: tcflag_t OXTABS
If this bit is set, convert tab characters on output into the appropriate number of spaces to emulate a tab stop every eight columns.

Macro: tcflag_t ONOEOT
If this bit is set, discard C-d characters (code 004) on output. These characters cause many dial-up terminals to disconnect.

Control Modes

This section describes the terminal flags and fields that control parameters usually associated with asynchronous serial data transmission. These flags may not make sense for other kinds of terminal ports (such as a network connection pseudo-terminal). All of these are contained in the c_cflag member of the struct termios structure.

The c_cflag member itself is an integer, and you change the flags and fields using the operators &, |, and ^. Don't try to specify the entire value for c_cflag---instead, change only specific flags and leave the rest untouched (see section Setting Terminal Modes Properly).

Macro: tcflag_t CLOCAL
If this bit is set, it indicates that the terminal is connected "locally" and that the modem status lines (such as carrier detect) should be ignored.

On many systems if this bit is not set and you call open without the O_NONBLOCK flag set, open blocks until a modem connection is established.

If this bit is not set and a modem disconnect is detected, a SIGHUP signal is sent to the controlling process group for the terminal (if it has one). Normally, this causes the process to exit; see section Signal Handling. Reading from the terminal after a disconnect causes an end-of-file condition, and writing causes an EIO error to be returned. The terminal device must be closed and reopened to clear the condition.

Macro: tcflag_t HUPCL
If this bit is set, a modem disconnect is generated when all processes that have the terminal device open have either closed the file or exited.

Macro: tcflag_t CREAD
If this bit is set, input can be read from the terminal. Otherwise, input is discarded when it arrives.

Macro: tcflag_t CSTOPB
If this bit is set, two stop bits are used. Otherwise, only one stop bit is used.

Macro: tcflag_t PARENB
If this bit is set, generation and detection of a parity bit are enabled. See section Input Modes, for information on how input parity errors are handled.

If this bit is not set, no parity bit is added to output characters, and input characters are not checked for correct parity.

Macro: tcflag_t PARODD
This bit is only useful if PARENB is set. If PARODD is set, odd parity is used, otherwise even parity is used.

The control mode flags also includes a field for the number of bits per character. You can use the CSIZE macro as a mask to extract the value, like this: settings.c_cflag & CSIZE.

Macro: tcflag_t CSIZE
This is a mask for the number of bits per character.

Macro: tcflag_t CS5
This specifies five bits per byte.

Macro: tcflag_t CS6
This specifies six bits per byte.

Macro: tcflag_t CS7
This specifies seven bits per byte.

Macro: tcflag_t CS8
This specifies eight bits per byte.

The following four bits are BSD extensions; this exist only on BSD systems and the GNU system.

Macro: tcflag_t CCTS_OFLOW
If this bit is set, enable flow control of output based on the CTS wire (RS232 protocol).

Macro: tcflag_t CRTS_IFLOW
If this bit is set, enable flow control of input based on the RTS wire (RS232 protocol).

Macro: tcflag_t MDMBUF
If this bit is set, enable carrier-based flow control of output.

Macro: tcflag_t CIGNORE
If this bit is set, it says to ignore the control modes and line speed values entirely. This is only meaningful in a call to tcsetattr.

The c_cflag member and the line speed values returned by cfgetispeed and cfgetospeed will be unaffected by the call. CIGNORE is useful if you want to set all the software modes in the other members, but leave the hardware details in c_cflag unchanged. (This is how the TCSASOFT flag to tcsettattr works.)

This bit is never set in the structure filled in by tcgetattr.

Local Modes

This section describes the flags for the c_lflag member of the struct termios structure. These flags generally control higher-level aspects of input processing than the input modes flags described in section Input Modes, such as echoing, signals, and the choice of canonical or noncanonical input.

The c_lflag member itself is an integer, and you change the flags and fields using the operators &, |, and ^. Don't try to specify the entire value for c_lflag---instead, change only specific flags and leave the rest untouched (see section Setting Terminal Modes Properly).

Macro: tcflag_t ICANON
This bit, if set, enables canonical input processing mode. Otherwise, input is processed in noncanonical mode. See section Two Styles of Input: Canonical or Not.

Macro: tcflag_t ECHO
If this bit is set, echoing of input characters back to the terminal is enabled.

Macro: tcflag_t ECHOE
If this bit is set, echoing indicates erasure of input with the ERASE character by erasing the last character in the current line from the screen. Otherwise, the character erased is re-echoed to show what has happened (suitable for a printing terminal).

This bit only controls the display behavior; the ICANON bit by itself controls actual recognition of the ERASE character and erasure of input, without which ECHOE is simply irrelevant.

Macro: tcflag_t ECHOPRT
This bit is like ECHOE, enables display of the ERASE character in a way that is geared to a hardcopy terminal. When you type the ERASE character, a `\' character is printed followed by the first character erased. Typing the ERASE character again just prints the next character erased. Then, the next time you type a normal character, a `/' character is printed before the character echoes.

This is a BSD extension, and exists only in BSD systems and the GNU system.

Macro: tcflag_t ECHOK
This bit enables special display of the KILL character by moving to a new line after echoing the KILL character normally. The behavior of ECHOKE (below) is nicer to look at.

If this bit is not set, the KILL character echoes just as it would if it were not the KILL character. Then it is up to the user to remember that the KILL character has erased the preceding input; there is no indication of this on the screen.

This bit only controls the display behavior; the ICANON bit by itself controls actual recognition of the KILL character and erasure of input, without which ECHOK is simply irrelevant.

Macro: tcflag_t ECHOKE
This bit is similar to ECHOK. It enables special display of the KILL character by erasing on the screen the entire line that has been killed. This is a BSD extension, and exists only in BSD systems and the GNU system.

Macro: tcflag_t ECHONL
If this bit is set and the ICANON bit is also set, then the newline ('\n') character is echoed even if the ECHO bit is not set.

Macro: tcflag_t ECHOCTL
If this bit is set and the ECHO bit is also set, echo control characters with `^' followed by the corresponding text character. Thus, control-A echoes as `^A'. This is usually the preferred mode for interactive input, because echoing a control character back to the terminal could have some undesired effect on the terminal.

This is a BSD extension, and exists only in BSD systems and the GNU system.

Macro: tcflag_t ISIG
This bit controls whether the INTR, QUIT, and SUSP characters are recognized. The functions associated with these characters are performed if and only if this bit is set. Being in canonical or noncanonical input mode has no affect on the interpretation of these characters.

You should use caution when disabling recognition of these characters. Programs that cannot be interrupted interactively are very user-unfriendly. If you clear this bit, your program should provide some alternate interface that allows the user to interactively send the signals associated with these characters, or to escape from the program.

See section Characters that Cause Signals.

Macro: tcflag_t IEXTEN
POSIX.1 gives IEXTEN implementation-defined meaning, so you cannot rely on this interpretation on all systems.

On BSD systems and the GNU system, it enables the LNEXT and DISCARD characters. See section Other Special Characters.

Macro: tcflag_t NOFLSH
Normally, the INTR, QUIT, and SUSP characters cause input and output queues for the terminal to be cleared. If this bit is set, the queues are not cleared.

Macro: tcflag_t TOSTOP
If this bit is set and the system supports job control, then SIGTTOU signals are generated by background processes that attempt to write to the terminal. See section Access to the Controlling Terminal.

The following bits are BSD extensions; they exist only in BSD systems and the GNU system.

Macro: tcflag_t ALTWERASE
This bit determines how far the WERASE character should erase. The WERASE character erases back to the beginning of a word; the question is, where do words begin?

If this bit is clear, then the beginning of a word is a nonwhitespace character following a whitespace character. If the bit is set, then the beginning of a word is an alphanumeric character or underscore following a character which is none of those.

See section Characters for Input Editing, for more information about the WERASE character.

Macro: tcflag_t FLUSHO
This is the bit that toggles when the user types the DISCARD character. While this bit is set, all output is discarded. See section Other Special Characters.

Macro: tcflag_t NOKERNINFO
Setting this bit disables handling of the STATUS character. See section Other Special Characters.

Macro: tcflag_t PENDIN
If this bit is set, it indicates that there is a line of input that needs to be reprinted. Typing the REPRINT character sets this bit; the bit remains set until reprinting is finished. See section Characters for Input Editing.

Line Speed

The terminal line speed tells the computer how fast to read and write data on the terminal.

If the terminal is connected to a real serial line, the terminal speed you specify actually controls the line--if it doesn't match the terminal's own idea of the speed, communication does not work. Real serial ports accept only certain standard speeds. Also, particular hardware may not support even all the standard speeds. Specifying a speed of zero hangs up a dialup connection and turns off modem control signals.

If the terminal is not a real serial line (for example, if it is a network connection), then the line speed won't really affect data transmission speed, but some programs will use it to determine the amount of padding needed. It's best to specify a line speed value that matches the actual speed of the actual terminal, but you can safely experiment with different values to vary the amount of padding.

There are actually two line speeds for each terminal, one for input and one for output. You can set them independently, but most often terminals use the same speed for both directions.

The speed values are stored in the struct termios structure, but don't try to access them in the struct termios structure directly. Instead, you should use the following functions to read and store them:

Function: speed_t cfgetospeed (const struct termios *termios-p)
This function returns the output line speed stored in the structure *termios-p.

Function: speed_t cfgetispeed (const struct termios *termios-p)
This function returns the input line speed stored in the structure *termios-p.

Function: int cfsetospeed (struct termios *termios-p, speed_t speed)
This function stores speed in *termios-p as the output speed. The normal return value is @math{0}; a value of @math{-1} indicates an error. If speed is not a speed, cfsetospeed returns @math{-1}.

Function: int cfsetispeed (struct termios *termios-p, speed_t speed)
This function stores speed in *termios-p as the input speed. The normal return value is @math{0}; a value of @math{-1} indicates an error. If speed is not a speed, cfsetospeed returns @math{-1}.

Function: int cfsetspeed (struct termios *termios-p, speed_t speed)
This function stores speed in *termios-p as both the input and output speeds. The normal return value is @math{0}; a value of @math{-1} indicates an error. If speed is not a speed, cfsetspeed returns @math{-1}. This function is an extension in 4.4 BSD.

Data Type: speed_t
The speed_t type is an unsigned integer data type used to represent line speeds.

The functions cfsetospeed and cfsetispeed report errors only for speed values that the system simply cannot handle. If you specify a speed value that is basically acceptable, then those functions will succeed. But they do not check that a particular hardware device can actually support the specified speeds--in fact, they don't know which device you plan to set the speed for. If you use tcsetattr to set the speed of a particular device to a value that it cannot handle, tcsetattr returns @math{-1}.

Portability note: In the GNU library, the functions above accept speeds measured in bits per second as input, and return speed values measured in bits per second. Other libraries require speeds to be indicated by special codes. For POSIX.1 portability, you must use one of the following symbols to represent the speed; their precise numeric values are system-dependent, but each name has a fixed meaning: B110 stands for 110 bps, B300 for 300 bps, and so on. There is no portable way to represent any speed but these, but these are the only speeds that typical serial lines can support.
B0  B50  B75  B110  B134  B150  B200
B300  B600  B1200  B1800  B2400  B4800
B9600  B19200  B38400  B57600  B115200
B230400  B460800
BSD defines two additional speed symbols as aliases: EXTA is an alias for B19200 and EXTB is an alias for B38400. These aliases are obsolete.

Special Characters

In canonical input, the terminal driver recognizes a number of special characters which perform various control functions. These include the ERASE character (usually DEL) for editing input, and other editing characters. The INTR character (normally C-c) for sending a SIGINT signal, and other signal-raising characters, may be available in either canonical or noncanonical input mode. All these characters are described in this section.

The particular characters used are specified in the c_cc member of the struct termios structure. This member is an array; each element specifies the character for a particular role. Each element has a symbolic constant that stands for the index of that element--for example, VINTR is the index of the element that specifies the INTR character, so storing '=' in termios.c_cc[VINTR] specifies `=' as the INTR character.

On some systems, you can disable a particular special character function by specifying the value _POSIX_VDISABLE for that role. This value is unequal to any possible character code. See section Optional Features in File Support, for more information about how to tell whether the operating system you are using supports _POSIX_VDISABLE.

Characters for Input Editing

These special characters are active only in canonical input mode. See section Two Styles of Input: Canonical or Not.

Macro: int VEOF
This is the subscript for the EOF character in the special control character array. termios.c_cc[VEOF] holds the character itself.

The EOF character is recognized only in canonical input mode. It acts as a line terminator in the same way as a newline character, but if the EOF character is typed at the beginning of a line it causes read to return a byte count of zero, indicating end-of-file. The EOF character itself is discarded.

Usually, the EOF character is C-d.

Macro: int VEOL
This is the subscript for the EOL character in the special control character array. termios.c_cc[VEOL] holds the character itself.

The EOL character is recognized only in canonical input mode. It acts as a line terminator, just like a newline character. The EOL character is not discarded; it is read as the last character in the input line.

You don't need to use the EOL character to make RET end a line. Just set the ICRNL flag. In fact, this is the default state of affairs.

Macro: int VEOL2
This is the subscript for the EOL2 character in the special control character array. termios.c_cc[VEOL2] holds the character itself.

The EOL2 character works just like the EOL character (see above), but it can be a different character. Thus, you can specify two characters to terminate an input line, by setting EOL to one of them and EOL2 to the other.

The EOL2 character is a BSD extension; it exists only on BSD systems and the GNU system.

Macro: int VERASE
This is the subscript for the ERASE character in the special control character array. termios.c_cc[VERASE] holds the character itself.

The ERASE character is recognized only in canonical input mode. When the user types the erase character, the previous character typed is discarded. (If the terminal generates multibyte character sequences, this may cause more than one byte of input to be discarded.) This cannot be used to erase past the beginning of the current line of text. The ERASE character itself is discarded.

Usually, the ERASE character is DEL.

Macro: int VWERASE
This is the subscript for the WERASE character in the special control character array. termios.c_cc[VWERASE] holds the character itself.

The WERASE character is recognized only in canonical mode. It erases an entire word of prior input, and any whitespace after it; whitespace characters before the word are not erased.

The definition of a "word" depends on the setting of the ALTWERASE mode; see section Local Modes.

If the ALTWERASE mode is not set, a word is defined as a sequence of any characters except space or tab.

If the ALTWERASE mode is set, a word is defined as a sequence of characters containing only letters, numbers, and underscores, optionally followed by one character that is not a letter, number, or underscore.

The WERASE character is usually C-w.

This is a BSD extension.

Macro: int VKILL
This is the subscript for the KILL character in the special control character array. termios.c_cc[VKILL] holds the character itself.

The KILL character is recognized only in canonical input mode. When the user types the kill character, the entire contents of the current line of input are discarded. The kill character itself is discarded too.

The KILL character is usually C-u.

Macro: int VREPRINT
This is the subscript for the REPRINT character in the special control character array. termios.c_cc[VREPRINT] holds the character itself.

The REPRINT character is recognized only in canonical mode. It reprints the current input line. If some asynchronous output has come while you are typing, this lets you see the line you are typing clearly again.

The REPRINT character is usually C-r.

This is a BSD extension.

Characters that Cause Signals

These special characters may be active in either canonical or noncanonical input mode, but only when the ISIG flag is set (see section Local Modes).

Macro: int VINTR
This is the subscript for the INTR character in the special control character array. termios.c_cc[VINTR] holds the character itself.

The INTR (interrupt) character raises a SIGINT signal for all processes in the foreground job associated with the terminal. The INTR character itself is then discarded. See section Signal Handling, for more information about signals.

Typically, the INTR character is C-c.

Macro: int VQUIT
This is the subscript for the QUIT character in the special control character array. termios.c_cc[VQUIT] holds the character itself.

The QUIT character raises a SIGQUIT signal for all processes in the foreground job associated with the terminal. The QUIT character itself is then discarded. See section Signal Handling, for more information about signals.

Typically, the QUIT character is C-\.

Macro: int VSUSP
This is the subscript for the SUSP character in the special control character array. termios.c_cc[VSUSP] holds the character itself.

The SUSP (suspend) character is recognized only if the implementation supports job control (see section Job Control). It causes a SIGTSTP signal to be sent to all processes in the foreground job associated with the terminal. The SUSP character itself is then discarded. See section Signal Handling, for more information about signals.

Typically, the SUSP character is C-z.

Few applications disable the normal interpretation of the SUSP character. If your program does this, it should provide some other mechanism for the user to stop the job. When the user invokes this mechanism, the program should send a SIGTSTP signal to the process group of the process, not just to the process itself. See section Signaling Another Process.

Macro: int VDSUSP
This is the subscript for the DSUSP character in the special control character array. termios.c_cc[VDSUSP] holds the character itself.

The DSUSP (suspend) character is recognized only if the implementation supports job control (see section Job Control). It sends a SIGTSTP signal, like the SUSP character, but not right away--only when the program tries to read it as input. Not all systems with job control support DSUSP; only BSD-compatible systems (including the GNU system).

See section Signal Handling, for more information about signals.

Typically, the DSUSP character is C-y.

Special Characters for Flow Control

These special characters may be active in either canonical or noncanonical input mode, but their use is controlled by the flags IXON and IXOFF (see section Input Modes).

Macro: int VSTART
This is the subscript for the START character in the special control character array. termios.c_cc[VSTART] holds the character itself.

The START character is used to support the IXON and IXOFF input modes. If IXON is set, receiving a START character resumes suspended output; the START character itself is discarded. If IXANY is set, receiving any character at all resumes suspended output; the resuming character is not discarded unless it is the START character. IXOFF is set, the system may also transmit START characters to the terminal.

The usual value for the START character is C-q. You may not be able to change this value--the hardware may insist on using C-q regardless of what you specify.

Macro: int VSTOP
This is the subscript for the STOP character in the special control character array. termios.c_cc[VSTOP] holds the character itself.

The STOP character is used to support the IXON and IXOFF input modes. If IXON is set, receiving a STOP character causes output to be suspended; the STOP character itself is discarded. If IXOFF is set, the system may also transmit STOP characters to the terminal, to prevent the input queue from overflowing.

The usual value for the STOP character is C-s. You may not be able to change this value--the hardware may insist on using C-s regardless of what you specify.

Other Special Characters

These special characters exist only in BSD systems and the GNU system.

Macro: int VLNEXT
This is the subscript for the LNEXT character in the special control character array. termios.c_cc[VLNEXT] holds the character itself.

The LNEXT character is recognized only when IEXTEN is set, but in both canonical and noncanonical mode. It disables any special significance of the next character the user types. Even if the character would normally perform some editing function or generate a signal, it is read as a plain character. This is the analogue of the C-q command in Emacs. "LNEXT" stands for "literal next."

The LNEXT character is usually C-v.

Macro: int VDISCARD
This is the subscript for the DISCARD character in the special control character array. termios.c_cc[VDISCARD] holds the character itself.

The DISCARD character is recognized only when IEXTEN is set, but in both canonical and noncanonical mode. Its effect is to toggle the discard-output flag. When this flag is set, all program output is discarded. Setting the flag also discards all output currently in the output buffer. Typing any other character resets the flag.

Macro: int VSTATUS
This is the subscript for the STATUS character in the special control character array. termios.c_cc[VSTATUS] holds the character itself.

The STATUS character's effect is to print out a status message about how the current process is running.

The STATUS character is recognized only in canonical mode, and only if NOKERNINFO is not set.

Noncanonical Input

In noncanonical input mode, the special editing characters such as ERASE and KILL are ignored. The system facilities for the user to edit input are disabled in noncanonical mode, so that all input characters (unless they are special for signal or flow-control purposes) are passed to the application program exactly as typed. It is up to the application program to give the user ways to edit the input, if appropriate.

Noncanonical mode offers special parameters called MIN and TIME for controlling whether and how long to wait for input to be available. You can even use them to avoid ever waiting--to return immediately with whatever input is available, or with no input.

The MIN and TIME are stored in elements of the c_cc array, which is a member of the struct termios structure. Each element of this array has a particular role, and each element has a symbolic constant that stands for the index of that element. VMIN and VMAX are the names for the indices in the array of the MIN and TIME slots.

Macro: int VMIN
This is the subscript for the MIN slot in the c_cc array. Thus, termios.c_cc[VMIN] is the value itself.

The MIN slot is only meaningful in noncanonical input mode; it specifies the minimum number of bytes that must be available in the input queue in order for read to return.

Macro: int VTIME
This is the subscript for the TIME slot in the c_cc array. Thus, termios.c_cc[VTIME] is the value itself.

The TIME slot is only meaningful in noncanonical input mode; it specifies how long to wait for input before returning, in units of 0.1 seconds.

The MIN and TIME values interact to determine the criterion for when read should return; their precise meanings depend on which of them are nonzero. There are four possible cases:

Both TIME and MIN are nonzero. In this case, TIME specifies how long to wait after each input character to see if more input arrives. After the first character received, read keeps waiting until either MIN bytes have arrived in all, or TIME elapses with no further input. read always blocks until the first character arrives, even if TIME elapses first. read can return more than MIN characters if more than MIN happen to be in the queue.
Both MIN and TIME are zero. In this case, read always returns immediately with as many characters as are available in the queue, up to the number requested. If no input is immediately available, read returns a value of zero.
MIN is zero but TIME has a nonzero value. In this case, read waits for time TIME for input to become available; the availability of a single byte is enough to satisfy the read request and cause read to return. When it returns, it returns as many characters as are available, up to the number requested. If no input is available before the timer expires, read returns a value of zero.
TIME is zero but MIN has a nonzero value. In this case, read waits until at least MIN bytes are available in the queue. At that time, read returns as many characters as are available, up to the number requested. read can return more than MIN characters if more than MIN happen to be in the queue.

What happens if MIN is 50 and you ask to read just 10 bytes? Normally, read waits until there are 50 bytes in the buffer (or, more generally, the wait condition described above is satisfied), and then reads 10 of them, leaving the other 40 buffered in the operating system for a subsequent call to read.

Portability note: On some systems, the MIN and TIME slots are actually the same as the EOF and EOL slots. This causes no serious problem because the MIN and TIME slots are used only in noncanonical input and the EOF and EOL slots are used only in canonical input, but it isn't very clean. The GNU library allocates separate slots for these uses.

Function: int cfmakeraw (struct termios *termios-p)
This function provides an easy way to set up *termios-p for what has traditionally been called "raw mode" in BSD. This uses noncanonical input, and turns off most processing to give an unmodified channel to the terminal.

It does exactly this:
  termios-p->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
                                |INLCR|IGNCR|ICRNL|IXON);
  termios-p->c_oflag &= ~OPOST;
  termios-p->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
  termios-p->c_cflag &= ~(CSIZE|PARENB);
  termios-p->c_cflag |= CS8;
BSD Terminal Modes

The usual way to get and set terminal modes is with the functions described in section Terminal Modes. However, on some systems you can use the BSD-derived functions in this section to do some of the same thing. On many systems, these functions do not exist. Even with the GNU C library, the functions simply fail with errno = ENOSYS with many kernels, including Linux.

The symbols used in this section are declared in `sgtty.h'.

Data Type: struct sgttyb
This structure is an input or output parameter list for gtty and stty.

char sg_ispeed
Line speed for input
char sg_ospeed
Line speed for output
char sg_erase
Erase character
char sg_kill
Kill character
int sg_flags
Various flags

Function: int gtty (int filedes, struct sgttyb *attributes)
This function gets the attributes of a terminal.

gtty sets *attributes to describe the terminal attributes of the terminal which is open with file descriptor filedes.

Function: int stty (int filedes, struct sgttyb * attributes)

This function sets the attributes of a terminal.

stty sets the terminal attributes of the terminal which is open with file descriptor filedes to those described by *filedes.

Line Control Functions

These functions perform miscellaneous control actions on terminal devices. As regards terminal access, they are treated like doing output: if any of these functions is used by a background process on its controlling terminal, normally all processes in the process group are sent a SIGTTOU signal. The exception is if the calling process itself is ignoring or blocking SIGTTOU signals, in which case the operation is performed and no signal is sent. See section Job Control.

Function: int tcsendbreak (int filedes, int duration)
This function generates a break condition by transmitting a stream of zero bits on the terminal associated with the file descriptor filedes. The duration of the break is controlled by the duration argument. If zero, the duration is between 0.25 and 0.5 seconds. The meaning of a nonzero value depends on the operating system.

This function does nothing if the terminal is not an asynchronous serial data port.

The return value is normally zero. In the event of an error, a value of @math{-1} is returned. The following errno error conditions are defined for this function:

EBADF
The filedes is not a valid file descriptor.
ENOTTY
The filedes is not associated with a terminal device.

Function: int tcdrain (int filedes)
The tcdrain function waits until all queued output to the terminal filedes has been transmitted.

This function is a cancelation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time tcdrain is called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls to tcdrain should be protected using cancelation handlers.

The return value is normally zero. In the event of an error, a value of @math{-1} is returned. The following errno error conditions are defined for this function:

EBADF
The filedes is not a valid file descriptor.
ENOTTY
The filedes is not associated with a terminal device.
EINTR
The operation was interrupted by delivery of a signal. See section Primitives Interrupted by Signals.

Function: int tcflush (int filedes, int queue)
The tcflush function is used to clear the input and/or output queues associated with the terminal file filedes. The queue argument specifies which queue(s) to clear, and can be one of the following values:

TCIFLUSH
Clear any input data received, but not yet read.
TCOFLUSH
Clear any output data written, but not yet transmitted.
TCIOFLUSH
Clear both queued input and output.
The return value is normally zero. In the event of an error, a value of @math{-1} is returned. The following errno error conditions are defined for this function:

EBADF
The filedes is not a valid file descriptor.
ENOTTY
The filedes is not associated with a terminal device.
EINVAL
A bad value was supplied as the queue argument.
It is unfortunate that this function is named tcflush, because the term "flush" is normally used for quite another operation--waiting until all output is transmitted--and using it for discarding input or output would be confusing. Unfortunately, the name tcflush comes from POSIX and we cannot change it.

Function: int tcflow (int filedes, int action)
The tcflow function is used to perform operations relating to XON/XOFF flow control on the terminal file specified by filedes.

The action argument specifies what operation to perform, and can be one of the following values:

TCOOFF
Suspend transmission of output.
TCOON
Restart transmission of output.
TCIOFF
Transmit a STOP character.
TCION
Transmit a START character.
For more information about the STOP and START characters, see section Special Characters.

The return value is normally zero. In the event of an error, a value of @math{-1} is returned. The following errno error conditions are defined for this function:

EBADF
The filedes is not a valid file descriptor.
ENOTTY
The filedes is not associated with a terminal device.
EINVAL
A bad value was supplied as the action argument.
Noncanonical Mode Example

Here is an example program that shows how you can set up a terminal device to read single characters in noncanonical input mode, without echo.
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>

/* Use this variable to remember original terminal attributes. */

struct termios saved_attributes;

void
reset_input_mode (void)
{
  tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes);
}

void
set_input_mode (void)
{
  struct termios tattr;
  char *name;

  /* Make sure stdin is a terminal. */
  if (!isatty (STDIN_FILENO))
    {
      fprintf (stderr, "Not a terminal.\n");
      exit (EXIT_FAILURE);
    }

  /* Save the terminal attributes so we can restore them later. */
  tcgetattr (STDIN_FILENO, &saved_attributes);
  atexit (reset_input_mode);

  /* Set the funny terminal modes. */
  tcgetattr (STDIN_FILENO, &tattr);
  tattr.c_lflag &= ~(ICANON|ECHO); /* Clear ICANON and ECHO. */
  tattr.c_cc[VMIN] = 1;
  tattr.c_cc[VTIME] = 0;
  tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr);
}

int
main (void)
{
  char c;

  set_input_mode ();

  while (1)
    {
      read (STDIN_FILENO, &c, 1);
      if (c == '\004')          /* C-d */
        break;
      else
        putchar (c);
    }

  return EXIT_SUCCESS;
}
This program is careful to restore the original terminal modes before exiting or terminating with a signal. It uses the atexit function (see section Cleanups on Exit) to make sure this is done by exit.

The shell is supposed to take care of resetting the terminal modes when a process is stopped or continued; see section Job Control. But some existing shells do not actually do this, so you may wish to establish handlers for job control signals that reset terminal modes. The above example does so.

Pseudo-Terminals

A pseudo-terminal is a special interprocess communication channel that acts like a terminal. One end of the channel is called the master side or master pseudo-terminal device, the other side is called the slave side. Data written to the master side is received by the slave side as if it was the result of a user typing at an ordinary terminal, and data written to the slave side is sent to the master side as if it was written on an ordinary terminal.

Pseudo terminals are the way programs like xterm and emacs implement their terminal emulation functionality.

Allocating Pseudo-Terminals

This subsection describes functions for allocating a pseudo-terminal, and for making this pseudo-terminal available for actual use. These functions are declared in the header file `stdlib.h'.

Function: int getpt (void)
The getpt function returns a new file descriptor for the next available master pseudo-terminal. The normal return value from getpt is a non-negative integer file descriptor. In the case of an error, a value of @math{-1} is returned instead. The following errno conditions are defined for this function:

ENOENT
There are no free master pseudo-terminals available.
This function is a GNU extension.

Function: int grantpt (int filedes)
The grantpt function changes the ownership and access permission of the slave pseudo-terminal device corresponding to the master pseudo-terminal device associated with the file descriptor filedes. The owner is set from the real user ID of the calling process (see section The Persona of a Process), and the group is set to a special group (typically tty) or from the real group ID of the calling process. The access permission is set such that the file is both readable and writable by the owner and only writable by the group.

On some systems this function is implemented by invoking a special setuid root program (see section How an Application Can Change Persona). As a consequence, installing a signal handler for the SIGCHLD signal (see section Job Control Signals) may interfere with a call to grantpt.

The normal return value from grantpt is @math{0}; a value of @math{-1} is returned in case of failure. The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
ENINVAL
The filedes argument is not associated with a master pseudo-terminal device.
EACCESS
The slave pseudo-terminal device corresponding to the master associated with filedes could not be accessed.

Function: int unlockpt (int filedes)
The unlockpt function unlocks the slave pseudo-terminal device corresponding to the master pseudo-terminal device associated with the file descriptor filedes. On many systems, the slave can only be opened after unlocking, so portable applications should always call unlockpt before trying to open the slave.

The normal return value from unlockpt is @math{0}; a value of @math{-1} is returned in case of failure. The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
EINVAL
The filedes argument is not associated with a master pseudo-terminal device.

Function: char * ptsname (int filedes)
If the file descriptor filedes is associated with a master pseudo-terminal device, the ptsname function returns a pointer to a statically-allocated, null-terminated string containing the file name of the associated slave pseudo-terminal file. This string might be overwritten by subsequent calls to ptsname.

Function: int ptsname_r (int filedes, char *buf, size_t len)
The ptsname_r function is similar to the ptsname function except that it places its result into the user-specified buffer starting at buf with length len.

This function is a GNU extension.

Portability Note: On System V derived systems, the file returned by the ptsname and ptsname_r functions may be STREAMS-based, and therefore require additional processing after opening before it actually behaves as a pseudo terminal.

Typical usage of these functions is illustrated by the following example:
int
open_pty_pair (int *amaster, int *aslave)
{
  int master, slave;
  char *name;

  master = getpt ();
  if (master < 0)
    return 0;

  if (grantpt (master) < 0 || unlockpt (master) < 0)
    goto close_master;
  name = ptsname (master);
  if (name == NULL)
    goto close_master;

  slave = open (name, O_RDWR);
  if (slave == -1)
    goto close_master;

  if (isastream (slave))
    {
      if (ioctl (slave, I_PUSH, "ptem") < 0
          || ioctl (slave, I_PUSH, "ldterm") < 0)
        goto close_slave;
    }

  *amaster = master;
  *aslave = slave;
  return 1;

close_slave:
  close (slave);

close_master:
  close (master);
  return 0;
}
Opening a Pseudo-Terminal Pair

These functions, derived from BSD, are available in the separate `libutil' library, and declared in `pty.h'.

Function: int openpty (int *amaster, int *aslave, char *name, struct termios *termp, struct winsize *winp)
This function allocates and opens a pseudo-terminal pair, returning the file descriptor for the master in *amaster, and the file descriptor for the slave in *aslave. If the argument name is not a null pointer, the file name of the slave pseudo-terminal device is stored in *name. If termp is not a null pointer, the terminal attributes of the slave are set to the ones specified in the structure that termp points to (see section Terminal Modes). Likewise, if the winp is not a null pointer, the screen size of the slave is set to the values specified in the structure that winp points to.

The normal return value from openpty is @math{0}; a value of @math{-1} is returned in case of failure. The following errno conditions are defined for this function:

ENOENT
There are no free pseudo-terminal pairs available.
Warning: Using the openpty function with name not set to NULL is very dangerous because it provides no protection against overflowing the string name. You should use the ttyname function on the file descriptor returned in *slave to find out the file name of the slave pseudo-terminal device instead.

Function: int forkpty (int *amaster, char *name, struct termios *termp, struct winsize *winp)
This function is similar to the openpty function, but in addition, forks a new process (see section Creating a Process) and makes the newly opened slave pseudo-terminal device the controlling terminal (see section Controlling Terminal of a Process) for the child process.

If the operation is successful, there are then both parent and child processes and both see forkpty return, but with different values: it returns a value of @math{0} in the child process and returns the child's process ID in the parent process.

If the allocation of a pseudo-terminal pair or the process creation failed, forkpty returns a value of @math{-1} in the parent process.

Warning: The forkpty function has the same problems with respect to the name argument as openpty.
Syslog

This chapter describes facilities for issuing and logging messages of system administration interest. This chapter has nothing to do with programs issuing messages to their own users or keeping private logs (One would typically do that with the facilities described in section Input/Output on Streams).

Most systems have a facility called "Syslog" that allows programs to submit messages of interest to system administrators and can be configured to pass these messages on in various ways, such as printing on the console, mailing to a particular person, or recording in a log file for future reference.

A program uses the facilities in this chapter to submit such messages.

Overview of Syslog

System administrators have to deal with lots of different kinds of messages from a plethora of subsystems within each system, and usually lots of systems as well. For example, an FTP server might report every connection it gets. The kernel might report hardware failures on a disk drive. A DNS server might report usage statistics at regular intervals.

Some of these messages need to be brought to a system administrator's attention immediately. And it may not be just any system administrator -- there may be a particular system administrator who deals with a particular kind of message. Other messages just need to be recorded for future reference if there is a problem. Still others may need to have information extracted from them by an automated process that generates monthly reports.

To deal with these messages, most Unix systems have a facility called "Syslog." It is generally based on a daemon called "Syslogd" Syslogd listens for messages on a Unix domain socket named `/dev/log'. Based on classification information in the messages and its configuration file (usually `/etc/syslog.conf'), Syslogd routes them in various ways. Some of the popular routings are:

Write to the system console
Mail to a specific user
Write to a log file
Pass to another daemon
Discard

Syslogd can also handle messages from other systems. It listens on the syslog UDP port as well as the local socket for messages.

Syslog can handle messages from the kernel itself. But the kernel doesn't write to `/dev/log'; rather, another daemon (sometimes called "Klogd") extracts messages from the kernel and passes them on to Syslog as any other process would (and it properly identifies them as messages from the kernel).

Syslog can even handle messages that the kernel issued before Syslogd or Klogd was running. A Linux kernel, for example, stores startup messages in a kernel message ring and they are normally still there when Klogd later starts up. Assuming Syslogd is running by the time Klogd starts, Klogd then passes everything in the message ring to it.

In order to classify messages for disposition, Syslog requires any process that submits a message to it to provide two pieces of classification information with it:

facility
This identifies who submitted the message. There are a small number of facilities defined. The kernel, the mail subsystem, and an FTP server are examples of recognized facilities. For the complete list, See section syslog, vsyslog. Keep in mind that these are essentially arbitrary classifications. "Mail subsystem" doesn't have any more meaning than the system administrator gives to it.
priority
This tells how important the content of the message is. Examples of defined priority values are: debug, informational, warning, critical. For the complete list, See section syslog, vsyslog. Except for the fact that the priorities have a defined order, the meaning of each of these priorities is entirely determined by the system administrator.
A "facility/priority" is a number that indicates both the facility and the priority.

Warning: This terminology is not universal. Some people use "level" to refer to the priority and "priority" to refer to the combination of facility and priority. A Linux kernel has a concept of a message "level," which corresponds both to a Syslog priority and to a Syslog facility/priority (It can be both because the facility code for the kernel is zero, and that makes priority and facility/priority the same value).

The GNU C library provides functions to submit messages to Syslog. They do it by writing to the `/dev/log' socket. See section Submitting Syslog Messages.

The GNU C library functions only work to submit messages to the Syslog facility on the same system. To submit a message to the Syslog facility on another system, use the socket I/O functions to write a UDP datagram to the syslog UDP port on that system. See section Sockets.

Submitting Syslog Messages

The GNU C library provides functions to submit messages to the Syslog facility:

These functions only work to submit messages to the Syslog facility on the same system. To submit a message to the Syslog facility on another system, use the socket I/O functions to write a UDP datagram to the syslog UDP port on that system. See section Sockets.

openlog

The symbols referred to in this section are declared in the file `syslog.h'.

Function: void openlog (char *ident, int option,
int facility)

openlog opens or reopens a connection to Syslog in preparation for submitting messages.

ident is an arbitrary identification string which future syslog invocations will prefix to each message. This is intended to identify the source of the message, and people conventionally set it to the name of the program that will submit the messages.

openlog may or may not open the `/dev/log' socket, depending on option. If it does, it tries to open it and connect it as a stream socket. If that doesn't work, it tries to open it and connect it as a datagram socket. The socket has the "Close on Exec" attribute, so the kernel will close it if the process performs an exec.

You don't have to use openlog. If you call syslog without having called openlog, syslog just opens the connection implicitly and uses defaults for the information in ident and options.

options is a bit string, with the bits as defined by the following single bit masks:

LOG_PERROR
If on, openlog sets up the connection so that any syslog on this connection writes its message to the calling process' Standard Error stream in addition to submitting it to Syslog. If off, syslog does not write the message to Standard Error.
LOG_CONS
If on, openlog sets up the connection so that a syslog on this connection that fails to submit a message to Syslog writes the message instead to system console. If off, syslog does not write to the system console (but of course Syslog may write messages it receives to the console).
LOG_PID
When on, openlog sets up the connection so that a syslog on this connection inserts the calling process' Process ID (PID) into the message. When off, openlog does not insert the PID.
LOG_NDELAY
When on, openlog opens and connects the `/dev/log' socket. When off, a future syslog call must open and connect the socket. Portability note: In early systems, the sense of this bit was exactly the opposite.
LOG_ODELAY
This bit does nothing. It exists for backward compatibility.
If any other bit in options is on, the result is undefined.

facility is the default facility code for this connection. A syslog on this connection that specifies default facility causes this facility to be associated with the message. See syslog for possible values. A value of zero means the default default, which is LOG_USER.

If a Syslog connection is already open when you call openlog, openlog "reopens" the connection. Reopening is like opening except that if you specify zero for the default facility code, the default facility code simply remains unchanged and if you specify LOG_NDELAY and the socket is already open and connected, openlog just leaves it that way.

syslog, vsyslog

The symbols referred to in this section are declared in the file `syslog.h'.

Function: void syslog (int facility_priority, char *format, ...)

syslog submits a message to the Syslog facility. It does this by writing to the Unix domain socket /dev/log.

syslog submits the message with the facility and priority indicated by facility_priority. The macro LOG_MAKEPRI generates a facility/priority from a facility and a priority, as in the following example:
LOG_MAKEPRI(LOG_USER, LOG_WARNING)
The possible values for the facility code are (macros):

LOG_USER
A miscellaneous user process
LOG_MAIL
Mail
LOG_DAEMON
A miscellaneous system daemon
LOG_AUTH
Security (authorization)
LOG_SYSLOG
Syslog
LOG_LPR
Central printer
LOG_NEWS
Network news (e.g. Usenet)
LOG_UUCP
UUCP
LOG_CRON
Cron and At
LOG_AUTHPRIV
Private security (authorization)
LOG_FTP
Ftp server
LOG_LOCAL0
Locally defined
LOG_LOCAL1
Locally defined
LOG_LOCAL2
Locally defined
LOG_LOCAL3
Locally defined
LOG_LOCAL4
Locally defined
LOG_LOCAL5
Locally defined
LOG_LOCAL6
Locally defined
LOG_LOCAL7
Locally defined
Results are undefined if the facility code is anything else.

note: syslog recognizes one other facility code: that of the kernel. But you can't specify that facility code with these functions. If you try, it looks the same to syslog as if you are requesting the default facility. But you wouldn't want to anyway, because any program that uses the GNU C library is not the kernel.

You can use just a priority code as facility_priority. In that case, syslog assumes the default facility established when the Syslog connection was opened. See section Syslog Example.

The possible values for the priority code are (macros):

LOG_EMERG
The message says the system is unusable.
LOG_ALERT
Action on the message must be taken immediately.
LOG_CRIT
The message states a critical condition.
LOG_ERR
The message describes an error.
LOG_WARNING
The message is a warning.
LOG_NOTICE
The message describes a normal but important event.
LOG_INFO
The message is purely informational.
LOG_DEBUG
The message is only for debugging purposes.
Results are undefined if the priority code is anything else.

If the process does not presently have a Syslog connection open (i.e. it did not call openlog), syslog implicitly opens the connection the same as openlog would, with the following defaults for information that would otherwise be included in an openlog call: The default identification string is the program name. The default default facility is LOG_USER. The default for all the connection options in options is as if those bits were off. syslog leaves the Syslog connection open.

If the `dev/log' socket is not open and connected, syslog opens and connects it, the same as openlog with the LOG_NDELAY option would.

syslog leaves `/dev/log' open and connected unless its attempt to send the message failed, in which case syslog closes it (with the hope that a future implicit open will restore the Syslog connection to a usable state).

Example:
#include <syslog.h>
syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR),
        "Unable to make network connection to %s.  Error=%m", host);
Function: void vsyslog (int facility_priority, char *format, va_list arglist)

This is functionally identical to syslog, with the BSD style variable length argument.

closelog

The symbols referred to in this section are declared in the file `syslog.h'.

Function: void closelog (void)

closelog closes the current Syslog connection, if there is one. This include closing the `dev/log' socket, if it is open.

There is very little reason to use this function. It does not flush any buffers; you can reopen a Syslog connection without closing it first; The connection gets closed automatically on exec or exit. closelog has primarily aesthetic value.

setlogmask

The symbols referred to in this section are declared in the file `syslog.h'.

Function: int setlogmask (int mask)

setlogmask sets a mask (the "logmask") that determines which future syslog calls shall be ignored. If a program has not called setlogmask, syslog doesn't ignore any calls. You can use setlogmask to specify that messages of particular priorities shall be ignored in the future.

A setlogmask call overrides any previous setlogmask call.

Note that the logmask exists entirely independently of opening and closing of Syslog connections.

Setting the logmask has a similar effect to, but is not the same as, configuring Syslog. The Syslog configuration may cause Syslog to discard certain messages it receives, but the logmask causes certain messages never to get submitted to Syslog in the first place.

mask is a bit string with one bit corresponding to each of the possible message priorities. If the bit is on, syslog handles messages of that priority normally. If it is off, syslog discards messages of that priority. Use the message priority macros described in section syslog, vsyslog and the LOG_MASK to construct an appropriate mask value, as in this example:
LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR)
or
~(LOG_MASK(LOG_INFO))
There is also a LOG_UPTO macro, which generates a mask with the bits on for a certain priority and all priorities above it:
LOG_UPTO(LOG_ERROR)
The unfortunate naming of the macro is due to the fact that internally, higher numbers are used for lower message priorities.

Syslog Example

Here is an example of openlog, syslog, and closelog:

This example sets the logmask so that debug and informational messages get discarded without ever reaching Syslog. So the second syslog in the example does nothing.
#include <syslog.h>

setlogmask (LOG_UPTO (LOG_NOTICE));

openlog ("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);

syslog (LOG_NOTICE, "Program started by User %d", getuid ());
syslog (LOG_INFO, "A tree falls in a forest");

closelog ();
@set mult · @set infty ∞ @set pie π
@macro mul @cdot @macro infinity @infty @ifnottex @macro pi

Mathematics

This chapter contains information about functions for performing mathematical computations, such as trigonometric functions. Most of these functions have prototypes declared in the header file `math.h'. The complex-valued functions are defined in `complex.h'.

All mathematical functions which take a floating-point argument have three variants, one each for double, float, and long double arguments. The double versions are mostly defined in ISO C89. The float and long double versions are from the numeric extensions to C included in ISO C99.

Which of the three versions of a function should be used depends on the situation. For most calculations, the float functions are the fastest. On the other hand, the long double functions have the highest precision. double is somewhere in between. It is usually wise to pick the narrowest type that can accommodate your data. Not all machines have a distinct long double type; it may be the same as double.

Predefined Mathematical Constants

The header `math.h' defines several useful mathematical constants. All values are defined as preprocessor macros starting with M_. The values provided are:

M_E
The base of natural logarithms.
M_LOG2E
The logarithm to base 2 of M_E.
M_LOG10E
The logarithm to base 10 of M_E.
M_LN2
The natural logarithm of 2.
M_LN10
The natural logarithm of 10.
M_PI
Pi, the ratio of a circle's circumference to its diameter.
M_PI_2
Pi divided by two.
M_PI_4
Pi divided by four.
M_1_PI
The reciprocal of pi (1/pi)
M_2_PI
Two times the reciprocal of pi.
M_2_SQRTPI
Two times the reciprocal of the square root of pi.
M_SQRT2
The square root of two.
M_SQRT1_2
The reciprocal of the square root of two (also the square root of 1/2).
These constants come from the Unix98 standard and were also available in 4.4BSD; therefore they are only defined if _BSD_SOURCE or _XOPEN_SOURCE=500, or a more general feature select macro, is defined. The default set of features includes these constants. See section Feature Test Macros.

All values are of type double. As an extension, the GNU C library also defines these constants with type long double. The long double macros have a lowercase `l' appended to their names: M_El, M_PIl, and so forth. These are only available if _GNU_SOURCE is defined.

Note: Some programs use a constant named PI which has the same value as M_PI. This constant is not standard; it may have appeared in some old AT&T headers, and is mentioned in Stroustrup's book on C++. It infringes on the user's name space, so the GNU C library does not define it. Fixing programs written to expect it is simple: replace PI with M_PI throughout, or put `-DPI=M_PI' on the compiler command line.

Trigonometric Functions

These are the familiar sin, cos, and tan functions. The arguments to all of these functions are in units of radians; recall that pi radians equals 180 degrees.

The math library normally defines M_PI to a double approximation of pi. If strict ISO and/or POSIX compliance are requested this constant is not defined, but you can easily define it yourself:
#define M_PI 3.14159265358979323846264338327
You can also compute the value of pi with the expression acos (-1.0).

Function: double sin (double x)

Function: float sinf (float x)

Function: long double sinl (long double x)
These functions return the sine of x, where x is given in radians. The return value is in the range -1 to 1.

Function: double cos (double x)

Function: float cosf (float x)

Function: long double cosl (long double x)
These functions return the cosine of x, where x is given in radians. The return value is in the range -1 to 1.

Function: double tan (double x)

Function: float tanf (float x)

Function: long double tanl (long double x)
These functions return the tangent of x, where x is given in radians.

Mathematically, the tangent function has singularities at odd multiples of pi/2. If the argument x is too close to one of these singularities, tan will signal overflow.

In many applications where sin and cos are used, the sine and cosine of the same angle are needed at the same time. It is more efficient to compute them simultaneously, so the library provides a function to do that.

Function: void sincos (double x, double *sinx, double *cosx)

Function: void sincosf (float x, float *sinx, float *cosx)

Function: void sincosl (long double x, long double *sinx, long double *cosx)
These functions return the sine of x in *sinx and the cosine of x in *cos, where x is given in radians. Both values, *sinx and *cosx, are in the range of -1 to 1.

This function is a GNU extension. Portable programs should be prepared to cope with its absence.

ISO C99 defines variants of the trig functions which work on complex numbers. The GNU C library provides these functions, but they are only useful if your compiler supports the new complex types defined by the standard. (As of this writing GCC supports complex numbers, but there are bugs in the implementation.)

Function: complex double csin (complex double z)

Function: complex float csinf (complex float z)

Function: complex long double csinl (complex long double z)
These functions return the complex sine of z. The mathematical definition of the complex sine is

@ifnottex @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.

Function: complex double ccos (complex double z)

Function: complex float ccosf (complex float z)

Function: complex long double ccosl (complex long double z)
These functions return the complex cosine of z. The mathematical definition of the complex cosine is

@ifnottex @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}

Function: complex double ctan (complex double z)

Function: complex float ctanf (complex float z)

Function: complex long double ctanl (complex long double z)
These functions return the complex tangent of z. The mathematical definition of the complex tangent is

@ifnottex @math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}

The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an integer. ctan may signal overflow if z is too close to a pole.

Inverse Trigonometric Functions

These are the usual arc sine, arc cosine and arc tangent functions, which are the inverses of the sine, cosine and tangent functions respectively.

Function: double asin (double x)

Function: float asinf (float x)

Function: long double asinl (long double x)
These functions compute the arc sine of x---that is, the value whose sine is x. The value is in units of radians. Mathematically, there are infinitely many such values; the one actually returned is the one between -pi/2 and pi/2 (inclusive).

The arc sine function is defined mathematically only over the domain -1 to 1. If x is outside the domain, asin signals a domain error.

Function: double acos (double x)

Function: float acosf (float x)

Function: long double acosl (long double x)
These functions compute the arc cosine of x---that is, the value whose cosine is x. The value is in units of radians. Mathematically, there are infinitely many such values; the one actually returned is the one between 0 and pi (inclusive).

The arc cosine function is defined mathematically only over the domain -1 to 1. If x is outside the domain, acos signals a domain error.

Function: double atan (double x)

Function: float atanf (float x)

Function: long double atanl (long double x)
These functions compute the arc tangent of x---that is, the value whose tangent is x. The value is in units of radians. Mathematically, there are infinitely many such values; the one actually returned is the one between -pi/2 and pi/2 (inclusive).

Function: double atan2 (double y, double x)

Function: float atan2f (float y, float x)

Function: long double atan2l (long double y, long double x)
This function computes the arc tangent of y/x, but the signs of both arguments are used to determine the quadrant of the result, and x is permitted to be zero. The return value is given in radians and is in the range -pi to pi, inclusive.

If x and y are coordinates of a point in the plane, atan2 returns the signed angle between the line from the origin to that point and the x-axis. Thus, atan2 is useful for converting Cartesian coordinates to polar coordinates. (To compute the radial coordinate, use hypot; see section Exponentiation and Logarithms.)

If both x and y are zero, atan2 returns zero.

ISO C99 defines complex versions of the inverse trig functions.

Function: complex double casin (complex double z)

Function: complex float casinf (complex float z)

Function: complex long double casinl (complex long double z)
These functions compute the complex arc sine of z---that is, the value whose sine is z. The value returned is in radians.

Unlike the real-valued functions, casin is defined for all values of z.

Function: complex double cacos (complex double z)

Function: complex float cacosf (complex float z)

Function: complex long double cacosl (complex long double z)
These functions compute the complex arc cosine of z---that is, the value whose cosine is z. The value returned is in radians.

Unlike the real-valued functions, cacos is defined for all values of z.

Function: complex double catan (complex double z)

Function: complex float catanf (complex float z)

Function: complex long double catanl (complex long double z)
These functions compute the complex arc tangent of z---that is, the value whose tangent is z. The value is in units of radians.

Exponentiation and Logarithms

Function: double exp (double x)

Function: float expf (float x)

Function: long double expl (long double x)
These functions compute e (the base of natural logarithms) raised to the power x.

If the magnitude of the result is too large to be representable, exp signals overflow.

Function: double exp2 (double x)

Function: float exp2f (float x)

Function: long double exp2l (long double x)
These functions compute 2 raised to the power x. Mathematically, exp2 (x) is the same as exp (x * log (2)).

Function: double exp10 (double x)

Function: float exp10f (float x)

Function: long double exp10l (long double x)

Function: double pow10 (double x)

Function: float pow10f (float x)

Function: long double pow10l (long double x)
These functions compute 10 raised to the power x. Mathematically, exp10 (x) is the same as exp (x * log (10)).

These functions are GNU extensions. The name exp10 is preferred, since it is analogous to exp and exp2.

Function: double log (double x)

Function: float logf (float x)

Function: long double logl (long double x)
These functions compute the natural logarithm of x. exp (log (x)) equals x, exactly in mathematics and approximately in C.

If x is negative, log signals a domain error. If x is zero, it returns negative infinity; if x is too close to zero, it may signal overflow.

Function: double log10 (double x)

Function: float log10f (float x)

Function: long double log10l (long double x)
These functions return the base-10 logarithm of x. log10 (x) equals log (x) / log (10).

Function: double log2 (double x)

Function: float log2f (float x)

Function: long double log2l (long double x)
These functions return the base-2 logarithm of x. log2 (x) equals log (x) / log (2).

Function: double logb (double x)

Function: float logbf (float x)

Function: long double logbl (long double x)
These functions extract the exponent of x and return it as a floating-point value. If FLT_RADIX is two, logb is equal to floor (log2 (x)), except it's probably faster.

If x is de-normalized, logb returns the exponent x would have if it were normalized. If x is infinity (positive or negative), logb returns @math{@infinity{}}. If x is zero, logb returns @math{@infinity{}}. It does not signal.

Function: int ilogb (double x)

Function: int ilogbf (float x)

Function: int ilogbl (long double x)
These functions are equivalent to the corresponding logb functions except that they return signed integer values.

Since integers cannot represent infinity and NaN, ilogb instead returns an integer that can't be the exponent of a normal floating-point number. `math.h' defines constants so you can check for this.

Macro: int FP_ILOGB0
ilogb returns this value if its argument is 0. The numeric value is either INT_MIN or -INT_MAX.

This macro is defined in ISO C99.

Macro: int FP_ILOGBNAN
ilogb returns this value if its argument is NaN. The numeric value is either INT_MIN or INT_MAX.

This macro is defined in ISO C99.

These values are system specific. They might even be the same. The proper way to test the result of ilogb is as follows:
i = ilogb (f);
if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
  {
    if (isnan (f))
      {
        /* Handle NaN.  */
      }
    else if (f  == 0.0)
      {
        /* Handle 0.0.  */
      }
    else
      {
        /* Some other value with large exponent,
           perhaps +Inf.  */
      }
  }
Function: double pow (double base, double power)

Function: float powf (float base, float power)

Function: long double powl (long double base, long double power)
These are general exponentiation functions, returning base raised to power.

Mathematically, pow would return a complex number when base is negative and power is not an integral value. pow can't do that, so instead it signals a domain error. pow may also underflow or overflow the destination type.

Function: double sqrt (double x)

Function: float sqrtf (float x)

Function: long double sqrtl (long double x)
These functions return the nonnegative square root of x.

If x is negative, sqrt signals a domain error. Mathematically, it should return a complex number.

Function: double cbrt (double x)

Function: float cbrtf (float x)

Function: long double cbrtl (long double x)
These functions return the cube root of x. They cannot fail; every representable real value has a representable real cube root.

Function: double hypot (double x, double y)

Function: float hypotf (float x, float y)

Function: long double hypotl (long double x, long double y)
These functions return sqrt (x*x + y*y). This is the length of the hypotenuse of a right triangle with sides of length x and y, or the distance of the point (x, y) from the origin. Using this function instead of the direct formula is wise, since the error is much smaller. See also the function cabs in section Absolute Value.

Function: double expm1 (double x)

Function: float expm1f (float x)

Function: long double expm1l (long double x)
These functions return a value equivalent to exp (x) - 1. They are computed in a way that is accurate even if x is near zero--a case where exp (x) - 1 would be inaccurate owing to subtraction of two numbers that are nearly equal.

Function: double log1p (double x)

Function: float log1pf (float x)

Function: long double log1pl (long double x)
These functions returns a value equivalent to log (1 + x). They are computed in a way that is accurate even if x is near zero.

ISO C99 defines complex variants of some of the exponentiation and logarithm functions.

Function: complex double cexp (complex double z)

Function: complex float cexpf (complex float z)

Function: complex long double cexpl (complex long double z)
These functions return e (the base of natural logarithms) raised to the power of z. Mathematically, this corresponds to the value

@ifnottex @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}

Function: complex double clog (complex double z)

Function: complex float clogf (complex float z)

Function: complex long double clogl (complex long double z)
These functions return the natural logarithm of z. Mathematically, this corresponds to the value

@ifnottex @math{log (z) = log (cabs (z)) + I * carg (z)}

clog has a pole at 0, and will signal overflow if z equals or is very close to 0. It is well-defined for all other values of z.

Function: complex double clog10 (complex double z)

Function: complex float clog10f (complex float z)

Function: complex long double clog10l (complex long double z)
These functions return the base 10 logarithm of the complex value z. Mathematically, this corresponds to the value

@ifnottex @math{log (z) = log10 (cabs (z)) + I * carg (z)}

These functions are GNU extensions.

Function: complex double csqrt (complex double z)

Function: complex float csqrtf (complex float z)

Function: complex long double csqrtl (complex long double z)
These functions return the complex square root of the argument z. Unlike the real-valued functions, they are defined for all values of z.

Function: complex double cpow (complex double base, complex double power)

Function: complex float cpowf (complex float base, complex float power)

Function: complex long double cpowl (complex long double base, complex long double power)
These functions return base raised to the power of power. This is equivalent to cexp (y * clog (x))

Hyperbolic Functions

The functions in this section are related to the exponential functions; see section Exponentiation and Logarithms.

Function: double sinh (double x)

Function: float sinhf (float x)

Function: long double sinhl (long double x)
These functions return the hyperbolic sine of x, defined mathematically as (exp (x) - exp (-x)) / 2. They may signal overflow if x is too large.

Function: double cosh (double x)

Function: float coshf (float x)

Function: long double coshl (long double x)
These function return the hyperbolic cosine of x, defined mathematically as (exp (x) + exp (-x)) / 2. They may signal overflow if x is too large.

Function: double tanh (double x)

Function: float tanhf (float x)

Function: long double tanhl (long double x)
These functions return the hyperbolic tangent of x, defined mathematically as sinh (x) / cosh (x). They may signal overflow if x is too large.

There are counterparts for the hyperbolic functions which take complex arguments.

Function: complex double csinh (complex double z)

Function: complex float csinhf (complex float z)

Function: complex long double csinhl (complex long double z)
These functions return the complex hyperbolic sine of z, defined mathematically as (exp (z) - exp (-z)) / 2.

Function: complex double ccosh (complex double z)

Function: complex float ccoshf (complex float z)

Function: complex long double ccoshl (complex long double z)
These functions return the complex hyperbolic cosine of z, defined mathematically as (exp (z) + exp (-z)) / 2.

Function: complex double ctanh (complex double z)

Function: complex float ctanhf (complex float z)

Function: complex long double ctanhl (complex long double z)
These functions return the complex hyperbolic tangent of z, defined mathematically as csinh (z) / ccosh (z).

Function: double asinh (double x)

Function: float asinhf (float x)

Function: long double asinhl (long double x)
These functions return the inverse hyperbolic sine of x---the value whose hyperbolic sine is x.

Function: double acosh (double x)

Function: float acoshf (float x)

Function: long double acoshl (long double x)
These functions return the inverse hyperbolic cosine of x---the value whose hyperbolic cosine is x. If x is less than 1, acosh signals a domain error.

Function: double atanh (double x)

Function: float atanhf (float x)

Function: long double atanhl (long double x)
These functions return the inverse hyperbolic tangent of x---the value whose hyperbolic tangent is x. If the absolute value of x is greater than 1, atanh signals a domain error; if it is equal to 1, atanh returns infinity.

Function: complex double casinh (complex double z)

Function: complex float casinhf (complex float z)

Function: complex long double casinhl (complex long double z)
These functions return the inverse complex hyperbolic sine of z---the value whose complex hyperbolic sine is z.

Function: complex double cacosh (complex double z)

Function: complex float cacoshf (complex float z)

Function: complex long double cacoshl (complex long double z)
These functions return the inverse complex hyperbolic cosine of z---the value whose complex hyperbolic cosine is z. Unlike the real-valued functions, there are no restrictions on the value of z.

Function: complex double catanh (complex double z)

Function: complex float catanhf (complex float z)

Function: complex long double catanhl (complex long double z)
These functions return the inverse complex hyperbolic tangent of z---the value whose complex hyperbolic tangent is z. Unlike the real-valued functions, there are no restrictions on the value of z.

Special Functions

These are some more exotic mathematical functions which are sometimes useful. Currently they only have real-valued versions.

Function: double erf (double x)

Function: float erff (float x)

Function: long double erfl (long double x)
erf returns the error function of x. The error function is defined as @ifnottex
erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
Function: double erfc (double x)

Function: float erfcf (float x)

Function: long double erfcl (long double x)
erfc returns 1.0 - erf(x), but computed in a fashion that avoids round-off error when x is large.

Function: double lgamma (double x)

Function: float lgammaf (float x)

Function: long double lgammal (long double x)
lgamma returns the natural logarithm of the absolute value of the gamma function of x. The gamma function is defined as @ifnottex
gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
The sign of the gamma function is stored in the global variable signgam, which is declared in `math.h'. It is 1 if the intermediate result was positive or zero, or -1 if it was negative.

To compute the real gamma function you can use the tgamma function or you can compute the values as follows:
lgam = lgamma(x);
gam  = signgam*exp(lgam);
The gamma function has singularities at the non-positive integers. lgamma will raise the zero divide exception if evaluated at a singularity.

Function: double lgamma_r (double x, int *signp)

Function: float lgammaf_r (float x, int *signp)

Function: long double lgammal_r (long double x, int *signp)
lgamma_r is just like lgamma, but it stores the sign of the intermediate result in the variable pointed to by signp instead of in the signgam global. This means it is reentrant.

Function: double gamma (double x)

Function: float gammaf (float x)

Function: long double gammal (long double x)
These functions exist for compatibility reasons. They are equivalent to lgamma etc. It is better to use lgamma since for one the name reflects better the actual computation, moreover lgamma is standardized in ISO C99 while gamma is not.

Function: double tgamma (double x)

Function: float tgammaf (float x)

Function: long double tgammal (long double x)
tgamma applies the gamma function to x. The gamma function is defined as @ifnottex
gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
This function was introduced in ISO C99.

Function: double j0 (double x)

Function: float j0f (float x)

Function: long double j0l (long double x)
j0 returns the Bessel function of the first kind of order 0 of x. It may signal underflow if x is too large.

Function: double j1 (double x)

Function: float j1f (float x)

Function: long double j1l (long double x)
j1 returns the Bessel function of the first kind of order 1 of x. It may signal underflow if x is too large.

Function: double jn (int n, double x)

Function: float jnf (int n, float x)

Function: long double jnl (int n, long double x)
jn returns the Bessel function of the first kind of order n of x. It may signal underflow if x is too large.

Function: double y0 (double x)

Function: float y0f (float x)

Function: long double y0l (long double x)
y0 returns the Bessel function of the second kind of order 0 of x. It may signal underflow if x is too large. If x is negative, y0 signals a domain error; if it is zero, y0 signals overflow and returns @math{-@infinity}.

Function: double y1 (double x)

Function: float y1f (float x)

Function: long double y1l (long double x)
y1 returns the Bessel function of the second kind of order 1 of x. It may signal underflow if x is too large. If x is negative, y1 signals a domain error; if it is zero, y1 signals overflow and returns @math{-@infinity}.

Function: double yn (int n, double x)

Function: float ynf (int n, float x)

Function: long double ynl (int n, long double x)
yn returns the Bessel function of the second kind of order n of x. It may signal underflow if x is too large. If x is negative, yn signals a domain error; if it is zero, yn signals overflow and returns @math{-@infinity}.

Known Maximum Errors in Math Functions

This section lists the known errors of the functions in the math library. Errors are measured in "units of the last place". This is a measure for the relative error. For a number @math{z} with the representation @math{d.d...d@mul{}2^e} (we assume IEEE floating-point numbers with base 2) the ULP is represented by

@ifnottex
|d.d...d - (z / 2^e)| / 2^(p - 1)
where @math{p} is the number of bits in the mantissa of the floating-point number representation. Ideally the error for all functions is always less than 0.5ulps. Using rounding bits this is also possible and normally implemented for the basic operations. To achieve the same for the complex math functions requires a lot more work and this was not spend so far.

Therefore many of the functions in the math library have errors. The table lists the maximum error for each function which is exposed by one of the existing tests in the test suite. It is tried to cover as much as possible and really list the maximum error (or at least a ballpark figure) but this is often not achieved due to the large search space.

The table lists the ULP values for different architectures. Different architectures have different results since their hardware support for floating-point operations varies and also the existing hardware support is different.

@multitable {nexttowardf} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000} {1000 + i 1000}
Function @tab s390/fpu @tab sh/sh4/fpu @tab ia64/fpu @tab sparc/sparc64/fpu @tab sparc/sparc32/fpu @tab powerpc/fpu @tab mips/fpu @tab m68k/fpu @tab ix86 @tab Generic @tab arm @tab alpha/fpu
acosf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
acos @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
acosl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab 1 @tab 1150 @tab - @tab - @tab -
acoshf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
acosh @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
acoshl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab 1 @tab 1 @tab - @tab - @tab -
asinf @tab 2 @tab 2 @tab - @tab 2 @tab 2 @tab 2 @tab 2 @tab - @tab - @tab - @tab 2 @tab 2
asin @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
asinl @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab 1 @tab 1 @tab - @tab - @tab -
asinhf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
asinh @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
asinhl @tab - @tab - @tab 656 @tab - @tab - @tab - @tab - @tab 14 @tab 656 @tab - @tab - @tab -
atanf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
atan @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
atanl @tab - @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab 549 @tab - @tab - @tab -
atanhf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
atanh @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
atanhl @tab - @tab - @tab 1605 @tab - @tab - @tab - @tab - @tab - @tab 1605 @tab - @tab - @tab -
atan2f @tab 4 @tab 4 @tab - @tab 4.0000 @tab 4.0000 @tab 4 @tab 4 @tab - @tab - @tab - @tab - @tab 4
atan2 @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
atan2l @tab - @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab 549 @tab - @tab - @tab -
cabsf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
cabs @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab - @tab 1 @tab 1
cabsl @tab - @tab - @tab 560 @tab - @tab - @tab - @tab - @tab 1 @tab 560 @tab - @tab - @tab -
cacosf @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 2 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 2 @tab 1 + i 2 @tab - @tab 1 + i 1 @tab 1 + i 1
cacos @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab - @tab 1 + i 0 @tab 1 + i 0
cacosl @tab - @tab - @tab 151 + i 329 @tab 0 + i 3 @tab - @tab - @tab - @tab 1 + i 1 @tab 151 + i 329 @tab - @tab - @tab -
cacoshf @tab 7 + i 3 @tab 7 + i 3 @tab 7 + i 3 @tab 7 + i 3 @tab 7 + i 3 @tab 7 + i 3 @tab 7 + i 3 @tab 7 + i 0 @tab 4 + i 4 @tab - @tab 7 + i 3 @tab 7 + i 3
cacosh @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab - @tab 1 + i 1 @tab 1 + i 1
cacoshl @tab - @tab - @tab 328 + i 151 @tab 5 + i 1 @tab - @tab - @tab - @tab 6 + i 2 @tab 328 + i 151 @tab - @tab - @tab -
cargf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
carg @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cargl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
casinf @tab 2 + i 1 @tab 2 + i 1 @tab 2 + i 2 @tab 2 + i 1 @tab 2 + i 1 @tab 2 + i 1 @tab 2 + i 1 @tab 2 + i 2 @tab 2 + i 2 @tab - @tab 2 + i 1 @tab 2 + i 1
casin @tab 3 + i 0 @tab 3 + i 0 @tab 3 + i 0 @tab 3 + i 0 @tab 3 + i 0 @tab 3 + i 0 @tab 3 + i 0 @tab 3 + i 0 @tab 3 + i 0 @tab - @tab 3 + i 0 @tab 3 + i 0
casinl @tab - @tab - @tab 603 + i 329 @tab 1 + i 3 @tab - @tab - @tab - @tab 1 + i 1 @tab 603 + i 329 @tab - @tab - @tab -
casinhf @tab 1 + i 6 @tab 1 + i 6 @tab 1 + i 6 @tab 1 + i 6 @tab 1 + i 6 @tab 1 + i 6 @tab 1 + i 6 @tab 19 + i 2 @tab 1 + i 6 @tab - @tab 1 + i 6 @tab 1 + i 6
casinh @tab 5 + i 3 @tab 5 + i 3 @tab 5 + i 3 @tab 5 + i 3 @tab 5 + i 3 @tab 5 + i 3 @tab 5 + i 3 @tab 6 + i 13 @tab 5 + i 3 @tab - @tab 5 + i 3 @tab 5 + i 3
casinhl @tab - @tab - @tab 892 + i 12 @tab 4 + i 2 @tab - @tab - @tab - @tab 6 + i 7 @tab 892 + i 12 @tab - @tab - @tab -
catanf @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab - @tab 4 + i 1 @tab 4 + i 1
catan @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab - @tab 0 + i 1 @tab 0 + i 1
catanl @tab - @tab - @tab 251 + i 474 @tab 0 + i 1 @tab - @tab - @tab - @tab 1 + i 7 @tab 251 + i 474 @tab - @tab - @tab -
catanhf @tab 1 + i 6 @tab 1 + i 6 @tab 0 + i 6 @tab 1 + i 6 @tab 1 + i 6 @tab 0 + i 6 @tab 1 + i 6 @tab - @tab 1 + i 0 @tab - @tab 1 + i 6 @tab 1 + i 6
catanh @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab 4 + i 1 @tab - @tab 2 + i 0 @tab - @tab 4 + i 1 @tab 4 + i 1
catanhl @tab - @tab - @tab 66 + i 447 @tab - @tab - @tab - @tab - @tab 2 + i 2 @tab 66 + i 447 @tab - @tab - @tab -
cbrtf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cbrt @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
cbrtl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab 948 @tab 716 @tab - @tab - @tab -
ccosf @tab 0 + i 1 @tab 0 + i 1 @tab 1 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab - @tab 0 + i 1 @tab 0 + i 1
ccos @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 0 + i 1 @tab 1 + i 1 @tab - @tab 1 + i 1 @tab 1 + i 1
ccosl @tab - @tab - @tab 5 + i 1901 @tab - @tab - @tab - @tab - @tab 0 + i 1 @tab 5 + i 1901 @tab - @tab - @tab -
ccoshf @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 3 + i 1 @tab 1 + i 1 @tab - @tab 1 + i 1 @tab 1 + i 1
ccosh @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 0 @tab 1 + i 1 @tab - @tab 1 + i 1 @tab 1 + i 1
ccoshl @tab - @tab - @tab 1467 + i 1183 @tab - @tab - @tab - @tab - @tab 1 + i 2 @tab 1467 + i 1183 @tab - @tab - @tab -
ceilf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
ceil @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
ceill @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cexpf @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 3 + i 2 @tab 1 + i 0 @tab - @tab 1 + i 1 @tab 1 + i 1
cexp @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab - @tab - @tab - @tab 1 + i 0 @tab 1 + i 0
cexpl @tab - @tab - @tab 940 + i 1067 @tab 1 + i 1 @tab - @tab - @tab - @tab 2 + i 0 @tab 940 + i 1067 @tab - @tab - @tab -
cimagf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cimag @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cimagl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
clogf @tab 0 + i 3 @tab 0 + i 3 @tab 0 + i 3 @tab 0 + i 3 @tab 0 + i 3 @tab 0 + i 3 @tab 0 + i 3 @tab - @tab - @tab - @tab 0 + i 3 @tab 0 + i 3
clog @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab - @tab - @tab - @tab 0 + i 1 @tab 0 + i 1
clogl @tab - @tab - @tab 0 + i 1 @tab - @tab - @tab - @tab - @tab 0 + i 1 @tab 0 + i 1 @tab - @tab - @tab -
clog10f @tab 1 + i 5 @tab 1 + i 5 @tab 1 + i 5 @tab 1 + i 5 @tab 1 + i 5 @tab 1 + i 5 @tab 1 + i 5 @tab 1 + i 1 @tab 1 + i 1 @tab - @tab 1 + i 5 @tab 1 + i 5
clog10 @tab 1 + i 1 @tab 1 + i 1 @tab 2 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 2 + i 1 @tab - @tab 1 + i 1 @tab 1 + i 1
clog10l @tab - @tab - @tab 1402 + i 186 @tab - @tab - @tab - @tab - @tab 1 + i 3 @tab 1403 + i 186 @tab - @tab - @tab -
conjf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
conj @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
conjl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
copysignf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
copysign @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
copysignl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cosf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
cos @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab - @tab 2 @tab 2
cosl @tab - @tab - @tab 529 @tab 1 @tab - @tab - @tab - @tab 1 @tab 529 @tab - @tab - @tab -
coshf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cosh @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
coshl @tab - @tab - @tab 2 @tab - @tab - @tab - @tab - @tab 2 @tab 309 @tab - @tab - @tab -
cpowf @tab 4 + i 2 @tab 4 + i 2 @tab 5 + i 2.5333 @tab 4 + i 2 @tab 4 + i 2 @tab 4 + i 2 @tab 4 + i 2 @tab 1 + i 6 @tab 4 + i 2.5333 @tab - @tab 4 + i 2 @tab 4 + i 2
cpow @tab 1 + i 1.1031 @tab 1 + i 1.1031 @tab 1 + i 1.104 @tab 1 + i 1.1031 @tab 1 + i 1.1031 @tab 1 + i 2 @tab 1 + i 1.1031 @tab 1 + i 1.103 @tab 1 + i 1.104 @tab - @tab 1 + i 1.1031 @tab 1 + i 1.1031
cpowl @tab - @tab - @tab 1 + i 4 @tab 3 + i 0.9006 @tab - @tab - @tab - @tab 5 + i 2 @tab 2 + i 9 @tab - @tab - @tab -
cprojf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cproj @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
cprojl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
crealf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
creal @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
creall @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
csinf @tab 0 + i 1 @tab 0 + i 1 @tab 1 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 1 + i 1 @tab - @tab - @tab 0 + i 1 @tab 0 + i 1
csin @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
csinl @tab - @tab - @tab 966 + i 168 @tab - @tab - @tab - @tab - @tab - @tab 966 + i 168 @tab - @tab - @tab -
csinhf @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab - @tab 1 + i 1 @tab 1 + i 1
csinh @tab 0 + i 1 @tab 0 + i 1 @tab 1 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab 0 + i 1 @tab - @tab 1 + i 1 @tab - @tab 0 + i 1 @tab 0 + i 1
csinhl @tab - @tab - @tab 413 + i 477 @tab - @tab - @tab - @tab - @tab 1 + i 2 @tab 413 + i 477 @tab - @tab - @tab -
csqrtf @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 2 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 0 @tab - @tab - @tab 1 + i 1 @tab 1 + i 1
csqrt @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab 1 + i 0 @tab - @tab 1 + i 0 @tab - @tab 1 + i 0 @tab 1 + i 0
csqrtl @tab - @tab - @tab 237 + i 128 @tab 1 + i 1 @tab - @tab - @tab - @tab - @tab 237 + i 128 @tab - @tab - @tab -
ctanf @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 0 @tab 1 + i 1 @tab - @tab 1 + i 1 @tab 1 + i 1
ctan @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 1 @tab 1 + i 0 @tab 1 + i 1 @tab - @tab 1 + i 1 @tab 1 + i 1
ctanl @tab - @tab - @tab 690 + i 367 @tab - @tab - @tab - @tab - @tab 439 + i 2 @tab 690 + i 367 @tab - @tab - @tab -
ctanhf @tab 2 + i 1 @tab 2 + i 1 @tab 2 + i 2 @tab 2 + i 1 @tab 2 + i 1 @tab 2 + i 1 @tab 2 + i 1 @tab 1 + i 0 @tab 1 + i 1 @tab - @tab 2 + i 1 @tab 2 + i 1
ctanh @tab 2 + i 2 @tab 2 + i 2 @tab 2 + i 2 @tab 2 + i 2 @tab 2 + i 2 @tab 2 + i 2 @tab 2 + i 2 @tab 0 + i 1 @tab 0 + i 1 @tab - @tab 2 + i 2 @tab 2 + i 2
ctanhl @tab - @tab - @tab 286 + i 3074 @tab - @tab - @tab - @tab - @tab 2 + i 25 @tab 286 + i 3074 @tab - @tab - @tab -
erff @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
erf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
erfl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
erfcf @tab 12 @tab 12 @tab 12 @tab 12 @tab 12 @tab 12 @tab 12 @tab 11 @tab 12 @tab - @tab 12 @tab 12
erfc @tab 24 @tab 24 @tab 24 @tab 24 @tab 24 @tab 24 @tab 24 @tab 24 @tab 24 @tab - @tab 24 @tab 24
erfcl @tab - @tab - @tab 12 @tab - @tab - @tab - @tab - @tab 12 @tab 36 @tab - @tab - @tab -
expf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
exp @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
expl @tab - @tab - @tab 412 @tab - @tab - @tab - @tab - @tab - @tab 412 @tab - @tab - @tab -
exp10f @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab - @tab - @tab - @tab 2 @tab 2
exp10 @tab 6 @tab 6 @tab 6 @tab 6 @tab 6 @tab 6 @tab 6 @tab 1 @tab 1 @tab - @tab 6 @tab 6
exp10l @tab - @tab - @tab 1182 @tab 1 @tab - @tab - @tab - @tab 1 @tab 1182 @tab - @tab - @tab -
exp2f @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
exp2 @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
exp2l @tab - @tab - @tab 462 @tab - @tab - @tab - @tab - @tab - @tab 462 @tab - @tab - @tab -
expm1f @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab - @tab - @tab 1 @tab 1
expm1 @tab - @tab - @tab 1 @tab 1 @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
expm1l @tab - @tab - @tab 825 @tab - @tab - @tab - @tab - @tab 1 @tab 825 @tab - @tab - @tab -
fabsf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fabs @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fabsl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fdimf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fdim @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fdiml @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
floorf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
floor @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
floorl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fmaf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fma @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fmal @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fmaxf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fmax @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fmaxl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fminf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fmin @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fminl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
fmodf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
fmod @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab - @tab 2 @tab 2
fmodl @tab - @tab - @tab 4096 @tab 2 @tab - @tab - @tab - @tab 1 @tab 4096 @tab - @tab - @tab -
frexpf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
frexp @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
frexpl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
gammaf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
gamma @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab - @tab 1 @tab - @tab - @tab -
gammal @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab 1 @tab 1 @tab - @tab - @tab -
hypotf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
hypot @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab - @tab 1 @tab 1
hypotl @tab - @tab - @tab 560 @tab - @tab - @tab - @tab - @tab 1 @tab 560 @tab - @tab - @tab -
ilogbf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
ilogb @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
ilogbl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
j0f @tab 2 @tab 2 @tab 1 @tab 2 @tab 2 @tab 1 @tab 2 @tab 1 @tab 1 @tab - @tab 2 @tab 2
j0 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 1 @tab 2 @tab - @tab 2 @tab 2
j0l @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
j1f @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 1 @tab - @tab 2 @tab 2
j1 @tab 1 @tab 1 @tab 2 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 2 @tab - @tab 1 @tab 1
j1l @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab 2 @tab 2 @tab - @tab - @tab -
jnf @tab 4 @tab 4 @tab 4 @tab 4 @tab 4 @tab 4 @tab 4 @tab 11 @tab 2 @tab - @tab 4 @tab 4
jn @tab 6 @tab 6 @tab 6 @tab 6 @tab 6 @tab 6 @tab 6 @tab 4 @tab 4 @tab - @tab 6 @tab 6
jnl @tab - @tab - @tab 2 @tab - @tab - @tab - @tab - @tab 2 @tab 2 @tab - @tab - @tab -
lgammaf @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab - @tab 2 @tab 2
lgamma @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
lgammal @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab 1 @tab 1 @tab - @tab - @tab -
lrintf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
lrint @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
lrintl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
llrintf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
llrint @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
llrintl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
logf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
log @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
logl @tab - @tab - @tab 2341 @tab 1 @tab - @tab - @tab - @tab 2 @tab 2341 @tab - @tab - @tab -
log10f @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
log10 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
log10l @tab - @tab - @tab 2033 @tab - @tab - @tab - @tab - @tab 1 @tab 2033 @tab - @tab - @tab -
log1pf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
log1p @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
log1pl @tab - @tab - @tab 585 @tab - @tab - @tab - @tab - @tab 2 @tab 585 @tab - @tab - @tab -
log2f @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
log2 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
log2l @tab - @tab - @tab 1688 @tab - @tab - @tab - @tab - @tab 1 @tab 1688 @tab - @tab - @tab -
logbf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
logb @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
logbl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
lroundf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
lround @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
lroundl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
llroundf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
llround @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
llroundl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
modff @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
modf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
modfl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nearbyintf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nearbyint @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nearbyintl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nextafterf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nextafter @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nextafterl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nexttowardf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nexttoward @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
nexttowardl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
powf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
pow @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
powl @tab - @tab - @tab 725 @tab - @tab - @tab - @tab - @tab 1 @tab 725 @tab - @tab - @tab -
remainderf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
remainder @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
remainderl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
remquof @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
remquo @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
remquol @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
rintf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
rint @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
rintl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
roundf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
round @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
roundl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalbf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalb @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalbl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalbnf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalbn @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalbnl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalblnf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalbln @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
scalblnl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
sinf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
sin @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
sinl @tab - @tab - @tab 627 @tab - @tab - @tab - @tab - @tab 1 @tab 627 @tab - @tab - @tab -
sincosf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
sincos @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
sincosl @tab - @tab - @tab 627 @tab 1 @tab - @tab - @tab - @tab 1 @tab 627 @tab - @tab - @tab -
sinhf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
sinh @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab - @tab - @tab 1 @tab 1
sinhl @tab - @tab - @tab 1029 @tab - @tab - @tab - @tab - @tab - @tab 1029 @tab - @tab - @tab -
sqrtf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
sqrt @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
sqrtl @tab - @tab - @tab 489 @tab 1 @tab - @tab - @tab - @tab - @tab 489 @tab - @tab - @tab -
tanf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
tan @tab 0.5 @tab 0.5 @tab 0.5 @tab 0.5 @tab 0.5 @tab 1 @tab 0.5 @tab 0.5 @tab 0.5 @tab - @tab 0.5 @tab 0.5
tanl @tab - @tab - @tab 1401 @tab 1 @tab - @tab - @tab - @tab 1 @tab 1401 @tab - @tab - @tab -
tanhf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab - @tab - @tab 1 @tab 1
tanh @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab - @tab - @tab 1 @tab 1
tanhl @tab - @tab - @tab 521 @tab - @tab - @tab - @tab - @tab - @tab 521 @tab - @tab - @tab -
tgammaf @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab - @tab 1 @tab 1
tgamma @tab 1 @tab 1 @tab 2 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 2 @tab - @tab 1 @tab 1
tgammal @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab 1 @tab 2 @tab - @tab - @tab -
truncf @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
trunc @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
truncl @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab - @tab -
y0f @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 1 @tab 2 @tab 1 @tab - @tab 1 @tab 1
y0 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 3 @tab - @tab 2 @tab 2
y0l @tab - @tab - @tab 2 @tab - @tab - @tab - @tab - @tab 2 @tab 2 @tab - @tab - @tab -
y1f @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab - @tab 2 @tab 2
y1 @tab 3 @tab 3 @tab 3 @tab 3 @tab 3 @tab 3 @tab 3 @tab 1 @tab 3 @tab - @tab 3 @tab 3
y1l @tab - @tab - @tab 1 @tab - @tab - @tab - @tab - @tab 2 @tab 2 @tab - @tab - @tab -
ynf @tab 2 @tab 2 @tab 3 @tab 2 @tab 2 @tab 2 @tab 2 @tab 2 @tab 3 @tab - @tab 2 @tab 2
yn @tab 3 @tab 3 @tab 6 @tab 3 @tab 3 @tab 3 @tab 3 @tab 6 @tab 6 @tab - @tab 3 @tab 3
ynl @tab - @tab - @tab 7 @tab - @tab - @tab - @tab - @tab 7 @tab 7 @tab - @tab - @tab -
Pseudo-Random Numbers

This section describes the GNU facilities for generating a series of pseudo-random numbers. The numbers generated are not truly random; typically, they form a sequence that repeats periodically, with a period so large that you can ignore it for ordinary purposes. The random number generator works by remembering a seed value which it uses to compute the next random number and also to compute a new seed.

Although the generated numbers look unpredictable within one run of a program, the sequence of numbers is exactly the same from one run to the next. This is because the initial seed is always the same. This is convenient when you are debugging a program, but it is unhelpful if you want the program to behave unpredictably. If you want a different pseudo-random series each time your program runs, you must specify a different seed each time. For ordinary purposes, basing the seed on the current time works well.

You can obtain repeatable sequences of numbers on a particular machine type by specifying the same initial seed value for the random number generator. There is no standard meaning for a particular seed value; the same seed, used in different C libraries or on different CPU types, will give you different random numbers.

The GNU library supports the standard ISO C random number functions plus two other sets derived from BSD and SVID. The BSD and ISO C functions provide identical, somewhat limited functionality. If only a small number of random bits are required, we recommend you use the ISO C interface, rand and srand. The SVID functions provide a more flexible interface, which allows better random number generator algorithms, provides more random bits (up to 48) per call, and can provide random floating-point numbers. These functions are required by the XPG standard and therefore will be present in all modern Unix systems.

ISO C Random Number Functions

This section describes the random number functions that are part of the ISO C standard.

To use these facilities, you should include the header file `stdlib.h' in your program.

Macro: int RAND_MAX
The value of this macro is an integer constant representing the largest value the rand function can return. In the GNU library, it is 2147483647, which is the largest signed integer representable in 32 bits. In other libraries, it may be as low as 32767.

Function: int rand (void)
The rand function returns the next pseudo-random number in the series. The value ranges from 0 to RAND_MAX.

Function: void srand (unsigned int seed)
This function establishes seed as the seed for a new series of pseudo-random numbers. If you call rand before a seed has been established with srand, it uses the value 1 as a default seed.

To produce a different pseudo-random series each time your program is run, do srand (time (0)).

POSIX.1 extended the C standard functions to support reproducible random numbers in multi-threaded programs. However, the extension is badly designed and unsuitable for serious work.

Function: int rand_r (unsigned int *seed)
This function returns a random number in the range 0 to RAND_MAX just as rand does. However, all its state is stored in the seed argument. This means the RNG's state can only have as many bits as the type unsigned int has. This is far too few to provide a good RNG.

If your program requires a reentrant RNG, we recommend you use the reentrant GNU extensions to the SVID random number generator. The POSIX.1 interface should only be used when the GNU extensions are not available.

BSD Random Number Functions

This section describes a set of random number generation functions that are derived from BSD. There is no advantage to using these functions with the GNU C library; we support them for BSD compatibility only.

The prototypes for these functions are in `stdlib.h'.

Function: long int random (void)
This function returns the next pseudo-random number in the sequence. The value returned ranges from 0 to RAND_MAX.

Note: Temporarily this function was defined to return a int32_t value to indicate that the return value always contains 32 bits even if long int is wider. The standard demands it differently. Users must always be aware of the 32-bit limitation, though.

Function: void srandom (unsigned int seed)
The srandom function sets the state of the random number generator based on the integer seed. If you supply a seed value of 1, this will cause random to reproduce the default set of random numbers.

To produce a different set of pseudo-random numbers each time your program runs, do srandom (time (0)).

Function: void * initstate (unsigned int seed, void *state, size_t size)
The initstate function is used to initialize the random number generator state. The argument state is an array of size bytes, used to hold the state information. It is initialized based on seed. The size must be between 8 and 256 bytes, and should be a power of two. The bigger the state array, the better.

The return value is the previous value of the state information array. You can use this value later as an argument to setstate to restore that state.

Function: void * setstate (void *state)
The setstate function restores the random number state information state. The argument must have been the result of a previous call to initstate or setstate.

The return value is the previous value of the state information array. You can use this value later as an argument to setstate to restore that state.

If the function fails the return value is NULL.

The four functions described so far in this section all work on a state which is shared by all threads. The state is not directly accessible to the user and can only be modified by these functions. This makes it hard to deal with situations where each thread should have its own pseudo-random number generator.

The GNU C library contains four additional functions which contain the state as an explicit parameter and therefore make it possible to handle thread-local PRNGs. Beside this there are no difference. In fact, the four functions already discussed are implemented internally using the following interfaces.

The `stdlib.h' header contains a definition of the following type:

Data Type: struct random_data

Objects of type struct random_data contain the information necessary to represent the state of the PRNG. Although a complete definition of the type is present the type should be treated as opaque.

The functions modifying the state follow exactly the already described functions.

Function: int random_r (struct random_data *restrict buf, int32_t *restrict result)
The random_r function behaves exactly like the random function except that it uses and modifies the state in the object pointed to by the first parameter instead of the global state.

Function: int srandom_r (unsigned int seed, struct random_data *buf)
The srandom_r function behaves exactly like the srandom function except that it uses and modifies the state in the object pointed to by the second parameter instead of the global state.

Function: int initstate_r (unsigned int seed, char *restrict statebuf, size_t statelen, struct random_data *restrict buf)
The initstate_r function behaves exactly like the initstate function except that it uses and modifies the state in the object pointed to by the fourth parameter instead of the global state.

Function: int setstate_r (char *restrict statebuf, struct random_data *restrict buf)
The setstate_r function behaves exactly like the setstate function except that it uses and modifies the state in the object pointed to by the first parameter instead of the global state.

SVID Random Number Function

The C library on SVID systems contains yet another kind of random number generator functions. They use a state of 48 bits of data. The user can choose among a collection of functions which return the random bits in different forms.

Generally there are two kinds of function. The first uses a state of the random number generator which is shared among several functions and by all threads of the process. The second requires the user to handle the state.

All functions have in common that they use the same congruential formula with the same constants. The formula is
Y = (a * X + c) mod m
where X is the state of the generator at the beginning and Y the state at the end. a and c are constants determining the way the generator works. By default they are
a = 0x5DEECE66D = 25214903917
c = 0xb = 11
but they can also be changed by the user. m is of course 2^48 since the state consists of a 48-bit array.

The prototypes for these functions are in `stdlib.h'.

Function: double drand48 (void)
This function returns a double value in the range of 0.0 to 1.0 (exclusive). The random bits are determined by the global state of the random number generator in the C library.

Since the double type according to IEEE 754 has a 52-bit mantissa this means 4 bits are not initialized by the random number generator. These are (of course) chosen to be the least significant bits and they are initialized to 0.

Function: double erand48 (unsigned short int xsubi[3])
This function returns a double value in the range of 0.0 to 1.0 (exclusive), similarly to drand48. The argument is an array describing the state of the random number generator.

This function can be called subsequently since it updates the array to guarantee random numbers. The array should have been initialized before initial use to obtain reproducible results.

Function: long int lrand48 (void)
The lrand48 function returns an integer value in the range of 0 to 2^31 (exclusive). Even if the size of the long int type can take more than 32 bits, no higher numbers are returned. The random bits are determined by the global state of the random number generator in the C library.

Function: long int nrand48 (unsigned short int xsubi[3])
This function is similar to the lrand48 function in that it returns a number in the range of 0 to 2^31 (exclusive) but the state of the random number generator used to produce the random bits is determined by the array provided as the parameter to the function.

The numbers in the array are updated afterwards so that subsequent calls to this function yield different results (as is expected of a random number generator). The array should have been initialized before the first call to obtain reproducible results.

Function: long int mrand48 (void)
The mrand48 function is similar to lrand48. The only difference is that the numbers returned are in the range -2^31 to 2^31 (exclusive).

Function: long int jrand48 (unsigned short int xsubi[3])
The jrand48 function is similar to nrand48. The only difference is that the numbers returned are in the range -2^31 to 2^31 (exclusive). For the xsubi parameter the same requirements are necessary.

The internal state of the random number generator can be initialized in several ways. The methods differ in the completeness of the information provided.

Function: void srand48 (long int seedval)
The srand48 function sets the most significant 32 bits of the internal state of the random number generator to the least significant 32 bits of the seedval parameter. The lower 16 bits are initialized to the value 0x330E. Even if the long int type contains more than 32 bits only the lower 32 bits are used.

Owing to this limitation, initialization of the state of this function is not very useful. But it makes it easy to use a construct like srand48 (time (0)).

A side-effect of this function is that the values a and c from the internal state, which are used in the congruential formula, are reset to the default values given above. This is of importance once the user has called the lcong48 function (see below).

Function: unsigned short int * seed48 (unsigned short int seed16v[3])
The seed48 function initializes all 48 bits of the state of the internal random number generator from the contents of the parameter seed16v. Here the lower 16 bits of the first element of see16v initialize the least significant 16 bits of the internal state, the lower 16 bits of seed16v[1] initialize the mid-order 16 bits of the state and the 16 lower bits of seed16v[2] initialize the most significant 16 bits of the state.

Unlike srand48 this function lets the user initialize all 48 bits of the state.

The value returned by seed48 is a pointer to an array containing the values of the internal state before the change. This might be useful to restart the random number generator at a certain state. Otherwise the value can simply be ignored.

As for srand48, the values a and c from the congruential formula are reset to the default values.

There is one more function to initialize the random number generator which enables you to specify even more information by allowing you to change the parameters in the congruential formula.

Function: void lcong48 (unsigned short int param[7])
The lcong48 function allows the user to change the complete state of the random number generator. Unlike srand48 and seed48, this function also changes the constants in the congruential formula.

From the seven elements in the array param the least significant 16 bits of the entries param[0] to param[2] determine the initial state, the least significant 16 bits of param[3] to param[5] determine the 48 bit constant a and param[6] determines the 16-bit value c.

All the above functions have in common that they use the global parameters for the congruential formula. In multi-threaded programs it might sometimes be useful to have different parameters in different threads. For this reason all the above functions have a counterpart which works on a description of the random number generator in the user-supplied buffer instead of the global state.

Please note that it is no problem if several threads use the global state if all threads use the functions which take a pointer to an array containing the state. The random numbers are computed following the same loop but if the state in the array is different all threads will obtain an individual random number generator.

The user-supplied buffer must be of type struct drand48_data. This type should be regarded as opaque and not manipulated directly.

Function: int drand48_r (struct drand48_data *buffer, double *result)
This function is equivalent to the drand48 function with the difference that it does not modify the global random number generator parameters but instead the parameters in the buffer supplied through the pointer buffer. The random number is returned in the variable pointed to by result.

The return value of the function indicates whether the call succeeded. If the value is less than 0 an error occurred and errno is set to indicate the problem.

This function is a GNU extension and should not be used in portable programs.

Function: int erand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, double *result)
The erand48_r function works like erand48, but in addition it takes an argument buffer which describes the random number generator. The state of the random number generator is taken from the xsubi array, the parameters for the congruential formula from the global random number generator data. The random number is returned in the variable pointed to by result.

The return value is non-negative if the call succeeded.

This function is a GNU extension and should not be used in portable programs.

Function: int lrand48_r (struct drand48_data *buffer, double *result)
This function is similar to lrand48, but in addition it takes a pointer to a buffer describing the state of the random number generator just like drand48.

If the return value of the function is non-negative the variable pointed to by result contains the result. Otherwise an error occurred.

This function is a GNU extension and should not be used in portable programs.

Function: int nrand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, long int *result)
The nrand48_r function works like nrand48 in that it produces a random number in the range 0 to 2^31. But instead of using the global parameters for the congruential formula it uses the information from the buffer pointed to by buffer. The state is described by the values in xsubi.

If the return value is non-negative the variable pointed to by result contains the result.

This function is a GNU extension and should not be used in portable programs.

Function: int mrand48_r (struct drand48_data *buffer, double *result)
This function is similar to mrand48 but like the other reentrant functions it uses the random number generator described by the value in the buffer pointed to by buffer.

If the return value is non-negative the variable pointed to by result contains the result.

This function is a GNU extension and should not be used in portable programs.

Function: int jrand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, long int *result)
The jrand48_r function is similar to jrand48. Like the other reentrant functions of this function family it uses the congruential formula parameters from the buffer pointed to by buffer.

If the return value is non-negative the variable pointed to by result contains the result.

This function is a GNU extension and should not be used in portable programs.

Before any of the above functions are used the buffer of type struct drand48_data should be initialized. The easiest way to do this is to fill the whole buffer with null bytes, e.g. by
memset (buffer, '\0', sizeof (struct drand48_data));
Using any of the reentrant functions of this family now will automatically initialize the random number generator to the default values for the state and the parameters of the congruential formula.

The other possibility is to use any of the functions which explicitly initialize the buffer. Though it might be obvious how to initialize the buffer from looking at the parameter to the function, it is highly recommended to use these functions since the result might not always be what you expect.

Function: int srand48_r (long int seedval, struct drand48_data *buffer)
The description of the random number generator represented by the information in buffer is initialized similarly to what the function srand48 does. The state is initialized from the parameter seedval and the parameters for the congruential formula are initialized to their default values.

If the return value is non-negative the function call succeeded.

This function is a GNU extension and should not be used in portable programs.

Function: int seed48_r (unsigned short int seed16v[3], struct drand48_data *buffer)
This function is similar to srand48_r but like seed48 it initializes all 48 bits of the state from the parameter seed16v.

If the return value is non-negative the function call succeeded. It does not return a pointer to the previous state of the random number generator like the seed48 function does. If the user wants to preserve the state for a later re-run s/he can copy the whole buffer pointed to by buffer.

This function is a GNU extension and should not be used in portable programs.

Function: int lcong48_r (unsigned short int param[7], struct drand48_data *buffer)
This function initializes all aspects of the random number generator described in buffer with the data in param. Here it is especially true that the function does more than just copying the contents of param and buffer. More work is required and therefore it is important to use this function rather than initializing the random number generator directly.

If the return value is non-negative the function call succeeded.

This function is a GNU extension and should not be used in portable programs.

Is Fast Code or Small Code preferred?

If an application uses many floating point functions it is often the case that the cost of the function calls themselves is not negligible. Modern processors can often execute the operations themselves very fast, but the function call disrupts the instruction pipeline.

For this reason the GNU C Library provides optimizations for many of the frequently-used math functions. When GNU CC is used and the user activates the optimizer, several new inline functions and macros are defined. These new functions and macros have the same names as the library functions and so are used instead of the latter. In the case of inline functions the compiler will decide whether it is reasonable to use them, and this decision is usually correct.

This means that no calls to the library functions may be necessary, and can increase the speed of generated code significantly. The drawback is that code size will increase, and the increase is not always negligible.

There are two kind of inline functions: Those that give the same result as the library functions and others that might not set errno and might have a reduced precision and/or argument range in comparison with the library functions. The latter inline functions are only available if the flag -ffast-math is given to GNU CC.

In cases where the inline functions and macros are not wanted the symbol __NO_MATH_INLINES should be defined before any system header is included. This will ensure that only library functions are used. Of course, it can be determined for each file in the project whether giving this option is preferable or not.

Not all hardware implements the entire IEEE 754 standard, and even if it does there may be a substantial performance penalty for using some of its features. For example, enabling traps on some processors forces the FPU to run un-pipelined, which can more than double calculation time.
Arithmetic Functions

This chapter contains information about functions for doing basic arithmetic operations, such as splitting a float into its integer and fractional parts or retrieving the imaginary part of a complex value. These functions are declared in the header files `math.h' and `complex.h'.

Integers

The C language defines several integer data types: integer, short integer, long integer, and character, all in both signed and unsigned varieties. The GNU C compiler extends the language to contain long long integers as well.

The C integer types were intended to allow code to be portable among machines with different inherent data sizes (word sizes), so each type may have different ranges on different machines. The problem with this is that a program often needs to be written for a particular range of integers, and sometimes must be written for a particular size of storage, regardless of what machine the program runs on.

To address this problem, the GNU C library contains C type definitions you can use to declare integers that meet your exact needs. Because the GNU C library header files are customized to a specific machine, your program source code doesn't have to be.

These typedefs are in `stdint.h'.

If you require that an integer be represented in exactly N bits, use one of the following types, with the obvious mapping to bit size and signedness:

int8_t
int16_t
int32_t
int64_t
uint8_t
uint16_t
uint32_t
uint64_t

If your C compiler and target machine do not allow integers of a certain size, the corresponding above type does not exist.

If you don't need a specific storage size, but want the smallest data structure with at least N bits, use one of these:

int_least8_t
int_least16_t
int_least32_t
int_least64_t
uint_least8_t
uint_least16_t
uint_least32_t
uint_least64_t

If you don't need a specific storage size, but want the data structure that allows the fastest access while having at least N bits (and among data structures with the same access speed, the smallest one), use one of these:

int_fast8_t
int_fast16_t
int_fast32_t
int_fast64_t
uint_fast8_t
uint_fast16_t
uint_fast32_t
uint_fast64_t

If you want an integer with the widest range possible on the platform on which it is being used, use one of the following. If you use these, you should write code that takes into account the variable size and range of the integer.

intmax_t
uintmax_t

The GNU C library also provides macros that tell you the maximum and minimum possible values for each integer data type. The macro names follow these examples: INT32_MAX, UINT8_MAX, INT_FAST32_MIN, INT_LEAST64_MIN, UINTMAX_MAX, INTMAX_MAX, INTMAX_MIN. Note that there are no macros for unsigned integer minima. These are always zero.

There are similar macros for use with C's built in integer types which should come with your C compiler. These are described in section Data Type Measurements.

Don't forget you can use the C sizeof function with any of these data types to get the number of bytes of storage each uses.

Integer Division

This section describes functions for performing integer division. These functions are redundant when GNU CC is used, because in GNU C the `/' operator always rounds towards zero. But in other C implementations, `/' may round differently with negative arguments. div and ldiv are useful because they specify how to round the quotient: towards zero. The remainder has the same sign as the numerator.

These functions are specified to return a result r such that the value r.quot*denominator + r.rem equals numerator.

To use these facilities, you should include the header file `stdlib.h' in your program.

Data Type: div_t
This is a structure type used to hold the result returned by the div function. It has the following members:

int quot
The quotient from the division.
int rem
The remainder from the division.

Function: div_t div (int numerator, int denominator)
This function div computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type div_t.

If the result cannot be represented (as in a division by zero), the behavior is undefined.

Here is an example, albeit not a very useful one.
div_t result;
result = div (20, -6);
Now result.quot is -3 and result.rem is 2.

Data Type: ldiv_t
This is a structure type used to hold the result returned by the ldiv function. It has the following members:

long int quot
The quotient from the division.
long int rem
The remainder from the division.
(This is identical to div_t except that the components are of type long int rather than int.)

Function: ldiv_t ldiv (long int numerator, long int denominator)
The ldiv function is similar to div, except that the arguments are of type long int and the result is returned as a structure of type ldiv_t.

Data Type: lldiv_t
This is a structure type used to hold the result returned by the lldiv function. It has the following members:

long long int quot
The quotient from the division.
long long int rem
The remainder from the division.
(This is identical to div_t except that the components are of type long long int rather than int.)

Function: lldiv_t lldiv (long long int numerator, long long int denominator)
The lldiv function is like the div function, but the arguments are of type long long int and the result is returned as a structure of type lldiv_t.

The lldiv function was added in ISO C99.

Data Type: imaxdiv_t
This is a structure type used to hold the result returned by the imaxdiv function. It has the following members:

intmax_t quot
The quotient from the division.
intmax_t rem
The remainder from the division.
(This is identical to div_t except that the components are of type intmax_t rather than int.)

See section Integers for a description of the intmax_t type.

Function: imaxdiv_t imaxdiv (intmax_t numerator, intmax_t denominator)
The imaxdiv function is like the div function, but the arguments are of type intmax_t and the result is returned as a structure of type imaxdiv_t.

See section Integers for a description of the intmax_t type.

The imaxdiv function was added in ISO C99.

Floating Point Numbers

Most computer hardware has support for two different kinds of numbers: integers (@math{...-3, -2, -1, 0, 1, 2, 3...}) and floating-point numbers. Floating-point numbers have three parts: the mantissa, the exponent, and the sign bit. The real number represented by a floating-point value is given by @ifnottex @math{(s ? -1 : 1) @mul{} 2^e @mul{} M} where @math{s} is the sign bit, @math{e} the exponent, and @math{M} the mantissa. See section Floating Point Representation Concepts, for details. (It is possible to have a different base for the exponent, but all modern hardware uses @math{2}.)

Floating-point numbers can represent a finite subset of the real numbers. While this subset is large enough for most purposes, it is important to remember that the only reals that can be represented exactly are rational numbers that have a terminating binary expansion shorter than the width of the mantissa. Even simple fractions such as @math{1/5} can only be approximated by floating point.

Mathematical operations and functions frequently need to produce values that are not representable. Often these values can be approximated closely enough for practical purposes, but sometimes they can't. Historically there was no way to tell when the results of a calculation were inaccurate. Modern computers implement the IEEE 754 standard for numerical computations, which defines a framework for indicating to the program when the results of calculation are not trustworthy. This framework consists of a set of exceptions that indicate why a result could not be represented, and the special values infinity and not a number (NaN).

Floating-Point Number Classification Functions

ISO C99 defines macros that let you determine what sort of floating-point number a variable holds.

Macro: int fpclassify (float-type x)
This is a generic macro which works on all floating-point types and which returns a value of type int. The possible values are:

FP_NAN
The floating-point number x is "Not a Number" (see section Infinity and NaN)
FP_INFINITE
The value of x is either plus or minus infinity (see section Infinity and NaN)
FP_ZERO
The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.
FP_SUBNORMAL
Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.
FP_NORMAL
This value is returned for all other values of x. It indicates that there is nothing special about the number.
fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)
This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to
(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)
isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)
This macro returns a nonzero value if x is finite and normalized. It is equivalent to
(fpclassify (x) == FP_NORMAL)
Macro: int isnan (float-type x)
This macro returns a nonzero value if x is NaN. It is equivalent to
(fpclassify (x) == FP_NAN)
Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)
This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)
This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write
(isnan) (x)
Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)
This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Function: double infnan (int error)
This function is provided for compatibility with BSD. Its argument is an error code, EDOM or ERANGE; infnan returns the value that a math function would return if it set errno to that value. See section Error Reporting by Mathematical Functions. -ERANGE is also acceptable as an argument, and corresponds to -HUGE_VAL as a value.

In the BSD library, on certain machines, infnan raises a fatal signal in all cases. The GNU library does not do likewise, because that does not fit the ISO C specification.

Portability Note: The functions listed in this section are BSD extensions.

Errors in Floating-Point Calculations

FP Exceptions

The IEEE 754 standard defines five exceptions that can occur during a calculation. Each corresponds to a particular sort of error, such as overflow.

When exceptions occur (when exceptions are raised, in the language of the standard), one of two things can happen. By default the exception is simply noted in the floating-point status word, and the program continues as if nothing had happened. The operation produces a default value, which depends on the exception (see the table below). Your program can check the status word to find out which exceptions happened.

Alternatively, you can enable traps for exceptions. In that case, when an exception is raised, your program will receive the SIGFPE signal. The default action for this signal is to terminate the program. See section Signal Handling, for how you can change the effect of the signal.

In the System V math library, the user-defined function matherr is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in new programs.

The exceptions defined in IEEE 754 are:

`Invalid Operation'
This exception is raised if the given operands are invalid for the operation to be performed. Examples are (see IEEE 754, section 7):

Addition or subtraction: @math{@infinity{} - @infinity{}}. (But @math{@infinity{} + @infinity{} = @infinity{}}).
Multiplication: @math{0 @mul{} @infinity{}}.
Division: @math{0/0} or @math{@infinity{}/@infinity{}}.
Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is infinite.
Square root if the operand is less then zero. More generally, any mathematical function evaluated outside its domain produces this exception.
Conversion of a floating-point number to an integer or decimal string, when the number cannot be represented in the target format (due to overflow, infinity, or NaN).
Conversion of an unrecognizable input string.
Comparison via predicates involving @math{<} or @math{>}, when one or other of the operands is NaN. You can prevent this exception by using the unordered comparison functions instead; see section Floating-Point Comparison Functions.
If the exception does not trap, the result of the operation is NaN.
`Division by Zero'
This exception is raised when a finite nonzero number is divided by zero. If no trap occurs the result is either @math{+@infinity{}} or @math{-@infinity{}}, depending on the signs of the operands.
`Overflow'
This exception is raised whenever the result cannot be represented as a finite value in the precision format of the destination. If no trap occurs the result depends on the sign of the intermediate result and the current rounding mode (IEEE 754, section 7.3):

Round to nearest carries all overflows to @math{@infinity{}} with the sign of the intermediate result.
Round toward @math{0} carries all overflows to the largest representable finite number with the sign of the intermediate result.
Round toward @math{-@infinity{}} carries positive overflows to the largest representable finite number and negative overflows to @math{-@infinity{}}.
Round toward @math{@infinity{}} carries negative overflows to the most negative representable finite number and positive overflows to @math{@infinity{}}.
Whenever the overflow exception is raised, the inexact exception is also raised.
`Underflow'
The underflow exception is raised when an intermediate result is too small to be calculated accurately, or if the operation's result rounded to the destination precision is too small to be normalized. When no trap is installed for the underflow exception, underflow is signaled (via the underflow flag) only when both tininess and loss of accuracy have been detected. If no trap handler is installed the operation continues with an imprecise small value, or zero if the destination precision cannot hold the small exact result.
`Inexact'
This exception is signalled if a rounded result is not exact (such as when calculating the square root of two) or a result overflows without an overflow trap.
Infinity and NaN

IEEE 754 floating point numbers can represent positive or negative infinity, and NaN (not a number). These three values arise from calculations whose result is undefined or cannot be represented accurately. You can also deliberately set a floating-point variable to any of them, which is sometimes useful. Some examples of calculations that produce infinity or NaN:

@ifnottex
@math{1/0 = @infinity{}}
@math{log (0) = -@infinity{}}
@math{sqrt (-1) = NaN}
When a calculation produces any of these values, an exception also occurs; see section FP Exceptions.

The basic operations and math functions all accept infinity and NaN and produce sensible output. Infinities propagate through calculations as one would expect: for example, @math{2 + @infinity{} = @infinity{}}, @math{4/@infinity{} = 0}, atan @math{(@infinity{}) = @pi{}/2}. NaN, on the other hand, infects any calculation that involves it. Unless the calculation would produce the same result no matter what real value replaced NaN, the result is NaN.

In comparison operations, positive infinity is larger than all values except itself and NaN, and negative infinity is smaller than all values except itself and NaN. NaN is unordered: it is not equal to, greater than, or less than anything, including itself. x == x is false if the value of x is NaN. You can use this to test whether a value is NaN or not, but the recommended way to test for NaN is with the isnan function (see section Floating-Point Number Classification Functions). In addition, <, >, <=, and >= will raise an exception when applied to NaNs.

`math.h' defines macros that allow you to explicitly set a variable to infinity or NaN.

Macro: float INFINITY
An expression representing positive infinity. It is equal to the value produced by mathematical operations like 1.0 / 0.0. -INFINITY represents negative infinity.

You can test whether a floating-point value is infinite by comparing it to this macro. However, this is not recommended; you should use the isfinite macro instead. See section Floating-Point Number Classification Functions.

This macro was introduced in the ISO C99 standard.

Macro: float NAN
An expression representing a value which is "not a number". This macro is a GNU extension, available only on machines that support the "not a number" value--that is to say, on all machines that support IEEE floating point.

You can use `#ifdef NAN' to test whether the machine supports NaN. (Of course, you must arrange for GNU extensions to be visible, such as by defining _GNU_SOURCE, and then you must include `math.h'.)

IEEE 754 also allows for another unusual value: negative zero. This value is produced when you divide a positive number by negative infinity, or when a negative result is smaller than the limits of representation. Negative zero behaves identically to zero in all calculations, unless you explicitly test the sign bit with signbit or copysign.

Examining the FPU status word

ISO C99 defines functions to query and manipulate the floating-point status word. You can use these functions to check for untrapped exceptions when it's convenient, rather than worrying about them in the middle of a calculation.

These constants represent the various IEEE 754 exceptions. Not all FPUs report all the different exceptions. Each constant is defined if and only if the FPU you are compiling for supports that exception, so you can test for FPU support with `#ifdef'. They are defined in `fenv.h'.

FE_INEXACT
The inexact exception.
FE_DIVBYZERO
The divide by zero exception.
FE_UNDERFLOW
The underflow exception.
FE_OVERFLOW
The overflow exception.
FE_INVALID
The invalid exception.
The macro FE_ALL_EXCEPT is the bitwise OR of all exception macros which are supported by the FP implementation.

These functions allow you to clear exception flags, test for exceptions, and save and restore the set of exceptions flagged.

Function: int feclearexcept (int excepts)
This function clears all of the supported exception flags indicated by excepts.

The function returns zero in case the operation was successful, a non-zero value otherwise.

Function: int feraiseexcept (int excepts)
This function raises the supported exceptions indicated by excepts. If more than one exception bit in excepts is set the order in which the exceptions are raised is undefined except that overflow (FE_OVERFLOW) or underflow (FE_UNDERFLOW) are raised before inexact (FE_INEXACT). Whether for overflow or underflow the inexact exception is also raised is also implementation dependent.

The function returns zero in case the operation was successful, a non-zero value otherwise.

Function: int fetestexcept (int excepts)
Test whether the exception flags indicated by the parameter except are currently set. If any of them are, a nonzero value is returned which specifies which exceptions are set. Otherwise the result is zero.

To understand these functions, imagine that the status word is an integer variable named status. feclearexcept is then equivalent to `status &= ~excepts' and fetestexcept is equivalent to `(status & excepts)'. The actual implementation may be very different, of course.

Exception flags are only cleared when the program explicitly requests it, by calling feclearexcept. If you want to check for exceptions from a set of calculations, you should clear all the flags first. Here is a simple example of the way to use fetestexcept:
{
  double f;
  int raised;
  feclearexcept (FE_ALL_EXCEPT);
  f = compute ();
  raised = fetestexcept (FE_OVERFLOW | FE_INVALID);
  if (raised & FE_OVERFLOW) { /* ... */ }
  if (raised & FE_INVALID) { /* ... */ }
  /* ... */
}
You cannot explicitly set bits in the status word. You can, however, save the entire status word and restore it later. This is done with the following functions:

Function: int fegetexceptflag (fexcept_t *flagp, int excepts)
This function stores in the variable pointed to by flagp an implementation-defined value representing the current setting of the exception flags indicated by excepts.

The function returns zero in case the operation was successful, a non-zero value otherwise.

Function: int fesetexceptflag (const fexcept_t *flagp, int
excepts) This function restores the flags for the exceptions indicated by excepts to the values stored in the variable pointed to by flagp.

The function returns zero in case the operation was successful, a non-zero value otherwise.

Note that the value stored in fexcept_t bears no resemblance to the bit mask returned by fetestexcept. The type may not even be an integer. Do not attempt to modify an fexcept_t variable.

Error Reporting by Mathematical Functions

Many of the math functions are defined only over a subset of the real or complex numbers. Even if they are mathematically defined, their result may be larger or smaller than the range representable by their return type. These are known as domain errors, overflows, and underflows, respectively. Math functions do several things when one of these errors occurs. In this manual we will refer to the complete response as signalling a domain error, overflow, or underflow.

When a math function suffers a domain error, it raises the invalid exception and returns NaN. It also sets errno to EDOM; this is for compatibility with old systems that do not support IEEE 754 exception handling. Likewise, when overflow occurs, math functions raise the overflow exception and return @math{@infinity{}} or @math{-@infinity{}} as appropriate. They also set errno to ERANGE. When underflow occurs, the underflow exception is raised, and zero (appropriately signed) is returned. errno may be set to ERANGE, but this is not guaranteed.

Some of the math functions are defined mathematically to result in a complex value over parts of their domains. The most familiar example of this is taking the square root of a negative number. The complex math functions, such as csqrt, will return the appropriate complex value in this case. The real-valued functions, such as sqrt, will signal a domain error.

Some older hardware does not support infinities. On that hardware, overflows instead return a particular very large number (usually the largest representable number). `math.h' defines macros you can use to test for overflow on both old and new hardware.

Macro: double HUGE_VAL

Macro: float HUGE_VALF

Macro: long double HUGE_VALL
An expression representing a particular very large number. On machines that use IEEE 754 floating point format, HUGE_VAL is infinity. On other machines, it's typically the largest positive number that can be represented.

Mathematical functions return the appropriately typed version of HUGE_VAL or -HUGE_VAL when the result is too large to be represented.

Rounding Modes

Floating-point calculations are carried out internally with extra precision, and then rounded to fit into the destination type. This ensures that results are as precise as the input data. IEEE 754 defines four possible rounding modes:

Round to nearest.
This is the default mode. It should be used unless there is a specific need for one of the others. In this mode results are rounded to the nearest representable value. If the result is midway between two representable values, the even representable is chosen. Even here means the lowest-order bit is zero. This rounding mode prevents statistical bias and guarantees numeric stability: round-off errors in a lengthy calculation will remain smaller than half of FLT_EPSILON.
Round toward plus Infinity.
All results are rounded to the smallest representable value which is greater than the result.
Round toward minus Infinity.
All results are rounded to the largest representable value which is less than the result.
Round toward zero.
All results are rounded to the largest representable value whose magnitude is less than that of the result. In other words, if the result is negative it is rounded up; if it is positive, it is rounded down.
`fenv.h' defines constants which you can use to refer to the various rounding modes. Each one will be defined if and only if the FPU supports the corresponding rounding mode.

FE_TONEAREST
Round to nearest.
FE_UPWARD
Round toward @math{+@infinity{}}.
FE_DOWNWARD
Round toward @math{-@infinity{}}.
FE_TOWARDZERO
Round toward zero.
Underflow is an unusual case. Normally, IEEE 754 floating point numbers are always normalized (see section Floating Point Representation Concepts). Numbers smaller than @math{2^r} (where @math{r} is the minimum exponent, FLT_MIN_RADIX-1 for float) cannot be represented as normalized numbers. Rounding all such numbers to zero or @math{2^r} would cause some algorithms to fail at 0. Therefore, they are left in denormalized form. That produces loss of precision, since some bits of the mantissa are stolen to indicate the decimal point.

If a result is too small to be represented as a denormalized number, it is rounded to zero. However, the sign of the result is preserved; if the calculation was negative, the result is negative zero. Negative zero can also result from some operations on infinity, such as @math{4/-@infinity{}}. Negative zero behaves identically to zero except when the copysign or signbit functions are used to check the sign bit directly.

At any time one of the above four rounding modes is selected. You can find out which one with this function:

Function: int fegetround (void)
Returns the currently selected rounding mode, represented by one of the values of the defined rounding mode macros.

To change the rounding mode, use this function:

Function: int fesetround (int round)
Changes the currently selected rounding mode to round. If round does not correspond to one of the supported rounding modes nothing is changed. fesetround returns zero if it changed the rounding mode, a nonzero value if the mode is not supported.

You should avoid changing the rounding mode if possible. It can be an expensive operation; also, some hardware requires you to compile your program differently for it to work. The resulting code may run slower. See your compiler documentation for details.

Floating-Point Control Functions

IEEE 754 floating-point implementations allow the programmer to decide whether traps will occur for each of the exceptions, by setting bits in the control word. In C, traps result in the program receiving the SIGFPE signal; see section Signal Handling.

Note: IEEE 754 says that trap handlers are given details of the exceptional situation, and can set the result value. C signals do not provide any mechanism to pass this information back and forth. Trapping exceptions in C is therefore not very useful.

It is sometimes necessary to save the state of the floating-point unit while you perform some calculation. The library provides functions which save and restore the exception flags, the set of exceptions that generate traps, and the rounding mode. This information is known as the floating-point environment.

The functions to save and restore the floating-point environment all use a variable of type fenv_t to store information. This type is defined in `fenv.h'. Its size and contents are implementation-defined. You should not attempt to manipulate a variable of this type directly.

To save the state of the FPU, use one of these functions:

Function: int fegetenv (fenv_t *envp)
Store the floating-point environment in the variable pointed to by envp.

The function returns zero in case the operation was successful, a non-zero value otherwise.

Function: int feholdexcept (fenv_t *envp)
Store the current floating-point environment in the object pointed to by envp. Then clear all exception flags, and set the FPU to trap no exceptions. Not all FPUs support trapping no exceptions; if feholdexcept cannot set this mode, it returns nonzero value. If it succeeds, it returns zero.

The functions which restore the floating-point environment can take these kinds of arguments:

Pointers to fenv_t objects, which were initialized previously by a call to fegetenv or feholdexcept.
The special macro FE_DFL_ENV which represents the floating-point environment as it was available at program start.
Implementation defined macros with names starting with FE_ and having type fenv_t *. If possible, the GNU C Library defines a macro FE_NOMASK_ENV which represents an environment where every exception raised causes a trap to occur. You can test for this macro using #ifdef. It is only defined if _GNU_SOURCE is defined. Some platforms might define other predefined environments.

To set the floating-point environment, you can use either of these functions:

Function: int fesetenv (const fenv_t *envp)
Set the floating-point environment to that described by envp.

The function returns zero in case the operation was successful, a non-zero value otherwise.

Function: int feupdateenv (const fenv_t *envp)
Like fesetenv, this function sets the floating-point environment to that described by envp. However, if any exceptions were flagged in the status word before feupdateenv was called, they remain flagged after the call. In other words, after feupdateenv is called, the status word is the bitwise OR of the previous status word and the one saved in envp.

The function returns zero in case the operation was successful, a non-zero value otherwise.

To control for individual exceptions if raising them causes a trap to occur, you can use the following two functions.

Portability Note: These functions are all GNU extensions.

Function: int feenableexcept (int excepts)
This functions enables traps for each of the exceptions as indicated by the parameter except. The individual excepetions are described in section Examining the FPU status word. Only the specified exceptions are enabled, the status of the other exceptions is not changed.

The function returns the previous enabled exceptions in case the operation was successful, -1 otherwise.

Function: int fedisableexcept (int excepts)
This functions disables traps for each of the exceptions as indicated by the parameter except. The individual excepetions are described in section Examining the FPU status word. Only the specified exceptions are disabled, the status of the other exceptions is not changed.

The function returns the previous enabled exceptions in case the operation was successful, -1 otherwise.

Function: int fegetexcept (int excepts)
The function returns a bitmask of all currently enabled exceptions. It returns -1 in case of failure.

Arithmetic Functions

The C library provides functions to do basic operations on floating-point numbers. These include absolute value, maximum and minimum, normalization, bit twiddling, rounding, and a few others.

Absolute Value

These functions are provided for obtaining the absolute value (or magnitude) of a number. The absolute value of a real number x is x if x is positive, -x if x is negative. For a complex number z, whose real part is x and whose imaginary part is y, the absolute value is sqrt (x*x + y*y).

Prototypes for abs, labs and llabs are in `stdlib.h'; imaxabs is declared in `inttypes.h'; fabs, fabsf and fabsl are declared in `math.h'. cabs, cabsf and cabsl are declared in `complex.h'.

Function: int abs (int number)

Function: long int labs (long int number)

Function: long long int llabs (long long int number)

Function: intmax_t imaxabs (intmax_t number)
These functions return the absolute value of number.

Most computers use a two's complement integer representation, in which the absolute value of INT_MIN (the smallest possible int) cannot be represented; thus, abs (INT_MIN) is not defined.

llabs and imaxdiv are new to ISO C99.

See section Integers for a description of the intmax_t type.

Function: double fabs (double number)

Function: float fabsf (float number)

Function: long double fabsl (long double number)
This function returns the absolute value of the floating-point number number.

Function: double cabs (complex double z)

Function: float cabsf (complex float z)

Function: long double cabsl (complex long double z)
These functions return the absolute value of the complex number z (see section Complex Numbers). The absolute value of a complex number is:
sqrt (creal (z) * creal (z) + cimag (z) * cimag (z))
This function should always be used instead of the direct formula because it takes special care to avoid losing precision. It may also take advantage of hardware support for this operation. See hypot in section Exponentiation and Logarithms.

Normalization Functions

The functions described in this section are primarily provided as a way to efficiently perform certain low-level manipulations on floating point numbers that are represented internally using a binary radix; see section Floating Point Representation Concepts. These functions are required to have equivalent behavior even if the representation does not use a radix of 2, but of course they are unlikely to be particularly efficient in those cases.

All these functions are declared in `math.h'.

Function: double frexp (double value, int *exponent)

Function: float frexpf (float value, int *exponent)

Function: long double frexpl (long double value, int *exponent)
These functions are used to split the number value into a normalized fraction and an exponent.

If the argument value is not zero, the return value is value times a power of two, and is always in the range 1/2 (inclusive) to 1 (exclusive). The corresponding exponent is stored in *exponent; the return value multiplied by 2 raised to this exponent equals the original number value.

For example, frexp (12.8, &exponent) returns 0.8 and stores 4 in exponent.

If value is zero, then the return value is zero and zero is stored in *exponent.

Function: double ldexp (double value, int exponent)

Function: float ldexpf (float value, int exponent)

Function: long double ldexpl (long double value, int exponent)
These functions return the result of multiplying the floating-point number value by 2 raised to the power exponent. (It can be used to reassemble floating-point numbers that were taken apart by frexp.)

For example, ldexp (0.8, 4) returns 12.8.

The following functions, which come from BSD, provide facilities equivalent to those of ldexp and frexp.

Function: double logb (double x)

Function: float logbf (float x)

Function: long double logbl (long double x)
These functions return the integer part of the base-2 logarithm of x, an integer value represented in type double. This is the highest integer power of 2 contained in x. The sign of x is ignored. For example, logb (3.5) is 1.0 and logb (4.0) is 2.0.

When 2 raised to this power is divided into x, it gives a quotient between 1 (inclusive) and 2 (exclusive).

If x is zero, the return value is minus infinity if the machine supports infinities, and a very small number if it does not. If x is infinity, the return value is infinity.

For finite x, the value returned by logb is one less than the value that frexp would store into *exponent.

Function: double scalb (double value, int exponent)

Function: float scalbf (float value, int exponent)

Function: long double scalbl (long double value, int exponent)
The scalb function is the BSD name for ldexp.

Function: long long int scalbn (double x, int n)

Function: long long int scalbnf (float x, int n)

Function: long long int scalbnl (long double x, int n)
scalbn is identical to scalb, except that the exponent n is an int instead of a floating-point number.

Function: long long int scalbln (double x, long int n)

Function: long long int scalblnf (float x, long int n)

Function: long long int scalblnl (long double x, long int n)
scalbln is identical to scalb, except that the exponent n is a long int instead of a floating-point number.

Function: long long int significand (double x)

Function: long long int significandf (float x)

Function: long long int significandl (long double x)
significand returns the mantissa of x scaled to the range @math{[1, 2)}. It is equivalent to scalb (x, (double) -ilogb (x)).

This function exists mainly for use in certain standardized tests of IEEE 754 conformance.

Rounding Functions

The functions listed here perform operations such as rounding and truncation of floating-point values. Some of these functions convert floating point numbers to integer values. They are all declared in `math.h'.

You can also convert floating-point numbers to integers simply by casting them to int. This discards the fractional part, effectively rounding towards zero. However, this only works if the result can actually be represented as an int---for very large numbers, this is impossible. The functions listed here return the result as a double instead to get around this problem.

Function: double ceil (double x)

Function: float ceilf (float x)

Function: long double ceill (long double x)
These functions round x upwards to the nearest integer, returning that value as a double. Thus, ceil (1.5) is 2.0.

Function: double floor (double x)

Function: float floorf (float x)

Function: long double floorl (long double x)
These functions round x downwards to the nearest integer, returning that value as a double. Thus, floor (1.5) is 1.0 and floor (-1.5) is -2.0.

Function: double trunc (double x)

Function: float truncf (float x)

Function: long double truncl (long double x)
The trunc functions round x towards zero to the nearest integer (returned in floating-point format). Thus, trunc (1.5) is 1.0 and trunc (-1.5) is -1.0.

Function: double rint (double x)

Function: float rintf (float x)

Function: long double rintl (long double x)
These functions round x to an integer value according to the current rounding mode. See section Floating Point Parameters, for information about the various rounding modes. The default rounding mode is to round to the nearest integer; some machines support other modes, but round-to-nearest is always used unless you explicitly select another.

If x was not initially an integer, these functions raise the inexact exception.

Function: double nearbyint (double x)

Function: float nearbyintf (float x)

Function: long double nearbyintl (long double x)
These functions return the same value as the rint functions, but do not raise the inexact exception if x is not an integer.

Function: double round (double x)

Function: float roundf (float x)

Function: long double roundl (long double x)
These functions are similar to rint, but they round halfway cases away from zero instead of to the nearest even integer.

Function: long int lrint (double x)

Function: long int lrintf (float x)

Function: long int lrintl (long double x)
These functions are just like rint, but they return a long int instead of a floating-point number.

Function: long long int llrint (double x)

Function: long long int llrintf (float x)

Function: long long int llrintl (long double x)
These functions are just like rint, but they return a long long int instead of a floating-point number.

Function: long int lround (double x)

Function: long int lroundf (float x)

Function: long int lroundl (long double x)
These functions are just like round, but they return a long int instead of a floating-point number.

Function: long long int llround (double x)

Function: long long int llroundf (float x)

Function: long long int llroundl (long double x)
These functions are just like round, but they return a long long int instead of a floating-point number.

Function: double modf (double value, double *integer-part)

Function: float modff (float value, float *integer-part)

Function: long double modfl (long double value, long double *integer-part)
These functions break the argument value into an integer part and a fractional part (between -1 and 1, exclusive). Their sum equals value. Each of the parts has the same sign as value, and the integer part is always rounded toward zero.

modf stores the integer part in *integer-part, and returns the fractional part. For example, modf (2.5, &intpart) returns 0.5 and stores 2.0 into intpart.

Remainder Functions

The functions in this section compute the remainder on division of two floating-point numbers. Each is a little different; pick the one that suits your problem.

Function: double fmod (double numerator, double denominator)

Function: float fmodf (float numerator, float denominator)

Function: long double fmodl (long double numerator, long double denominator)
These functions compute the remainder from the division of numerator by denominator. Specifically, the return value is numerator - n * denominator, where n is the quotient of numerator divided by denominator, rounded towards zero to an integer. Thus, fmod (6.5, 2.3) returns 1.9, which is 6.5 minus 4.6.

The result has the same sign as the numerator and has magnitude less than the magnitude of the denominator.

If denominator is zero, fmod signals a domain error.

Function: double drem (double numerator, double denominator)

Function: float dremf (float numerator, float denominator)

Function: long double dreml (long double numerator, long double denominator)
These functions are like fmod except that they rounds the internal quotient n to the nearest integer instead of towards zero to an integer. For example, drem (6.5, 2.3) returns -0.4, which is 6.5 minus 6.9.

The absolute value of the result is less than or equal to half the absolute value of the denominator. The difference between fmod (numerator, denominator) and drem (numerator, denominator) is always either denominator, minus denominator, or zero.

If denominator is zero, drem signals a domain error.

Function: double remainder (double numerator, double denominator)

Function: float remainderf (float numerator, float denominator)

Function: long double remainderl (long double numerator, long double denominator)
This function is another name for drem.

Setting and modifying single bits of FP values

There are some operations that are too complicated or expensive to perform by hand on floating-point numbers. ISO C99 defines functions to do these operations, which mostly involve changing single bits.

Function: double copysign (double x, double y)

Function: float copysignf (float x, float y)

Function: long double copysignl (long double x, long double y)
These functions return x but with the sign of y. They work even if x or y are NaN or zero. Both of these can carry a sign (although not all implementations support it) and this is one of the few operations that can tell the difference.

copysign never raises an exception.

This function is defined in IEC 559 (and the appendix with recommended functions in IEEE 754/IEEE 854).

Function: int signbit (float-type x)
signbit is a generic macro which can work on all floating-point types. It returns a nonzero value if the value of x has its sign bit set.

This is not the same as x < 0.0, because IEEE 754 floating point allows zero to be signed. The comparison -0.0 < 0.0 is false, but signbit (-0.0) will return a nonzero value.

Function: double nextafter (double x, double y)

Function: float nextafterf (float x, float y)

Function: long double nextafterl (long double x, long double y)
The nextafter function returns the next representable neighbor of x in the direction towards y. The size of the step between x and the result depends on the type of the result. If @math{x = y} the function simply returns y. If either value is NaN, NaN is returned. Otherwise a value corresponding to the value of the least significant bit in the mantissa is added or subtracted, depending on the direction. nextafter will signal overflow or underflow if the result goes outside of the range of normalized numbers.

This function is defined in IEC 559 (and the appendix with recommended functions in IEEE 754/IEEE 854).

Function: double nexttoward (double x, long double y)

Function: float nexttowardf (float x, long double y)

Function: long double nexttowardl (long double x, long double y)
These functions are identical to the corresponding versions of nextafter except that their second argument is a long double.

Function: double nan (const char *tagp)

Function: float nanf (const char *tagp)

Function: long double nanl (const char *tagp)
The nan function returns a representation of NaN, provided that NaN is supported by the target platform. nan ("n-char-sequence") is equivalent to strtod ("NAN(n-char-sequence)").

The argument tagp is used in an unspecified manner. On IEEE 754 systems, there are many representations of NaN, and tagp selects one. On other systems it may do nothing.

Floating-Point Comparison Functions

The standard C comparison operators provoke exceptions when one or other of the operands is NaN. For example,
int v = a < 1.0;
will raise an exception if a is NaN. (This does not happen with == and !=; those merely return false and true, respectively, when NaN is examined.) Frequently this exception is undesirable. ISO C99 therefore defines comparison functions that do not raise exceptions when NaN is examined. All of the functions are implemented as macros which allow their arguments to be of any floating-point type. The macros are guaranteed to evaluate their arguments only once.

Macro: int isgreater (real-floating x, real-floating y)
This macro determines whether the argument x is greater than y. It is equivalent to (x) > (y), but no exception is raised if x or y are NaN.

Macro: int isgreaterequal (real-floating x, real-floating y)
This macro determines whether the argument x is greater than or equal to y. It is equivalent to (x) >= (y), but no exception is raised if x or y are NaN.

Macro: int isless (real-floating x, real-floating y)
This macro determines whether the argument x is less than y. It is equivalent to (x) < (y), but no exception is raised if x or y are NaN.

Macro: int islessequal (real-floating x, real-floating y)
This macro determines whether the argument x is less than or equal to y. It is equivalent to (x) <= (y), but no exception is raised if x or y are NaN.

Macro: int islessgreater (real-floating x, real-floating y)
This macro determines whether the argument x is less or greater than y. It is equivalent to (x) < (y) || (x) > (y) (although it only evaluates x and y once), but no exception is raised if x or y are NaN.

This macro is not equivalent to x != y, because that expression is true if x or y are NaN.

Macro: int isunordered (real-floating x, real-floating y)
This macro determines whether its arguments are unordered. In other words, it is true if x or y are NaN, and false otherwise.

Not all machines provide hardware support for these operations. On machines that don't, the macros can be very slow. Therefore, you should not use these functions when NaN is not a concern.

Note: There are no macros isequal or isunequal. They are unnecessary, because the == and != operators do not throw an exception if one or both of the operands are NaN.

Miscellaneous FP arithmetic functions

The functions in this section perform miscellaneous but common operations that are awkward to express with C operators. On some processors these functions can use special machine instructions to perform these operations faster than the equivalent C code.

Function: double fmin (double x, double y)

Function: float fminf (float x, float y)

Function: long double fminl (long double x, long double y)
The fmin function returns the lesser of the two values x and y. It is similar to the expression
((x) < (y) ? (x) : (y))
except that x and y are only evaluated once.

If an argument is NaN, the other argument is returned. If both arguments are NaN, NaN is returned.

Function: double fmax (double x, double y)

Function: float fmaxf (float x, float y)

Function: long double fmaxl (long double x, long double y)
The fmax function returns the greater of the two values x and y.

If an argument is NaN, the other argument is returned. If both arguments are NaN, NaN is returned.

Function: double fdim (double x, double y)

Function: float fdimf (float x, float y)

Function: long double fdiml (long double x, long double y)
The fdim function returns the positive difference between x and y. The positive difference is @math{x - y} if x is greater than y, and @math{0} otherwise.

If x, y, or both are NaN, NaN is returned.

Function: double fma (double x, double y, double z)

Function: float fmaf (float x, float y, float z)

Function: long double fmal (long double x, long double y, long double z)
The fma function performs floating-point multiply-add. This is the operation @math{(x @mul{} y) + z}, but the intermediate result is not rounded to the destination type. This can sometimes improve the precision of a calculation.

This function was introduced because some processors have a special instruction to perform multiply-add. The C compiler cannot use it directly, because the expression `x*y + z' is defined to round the intermediate result. fma lets you choose when you want to round only once.

On processors which do not implement multiply-add in hardware, fma can be very slow since it must avoid intermediate rounding. `math.h' defines the symbols FP_FAST_FMA, FP_FAST_FMAF, and FP_FAST_FMAL when the corresponding version of fma is no slower than the expression `x*y + z'. In the GNU C library, this always means the operation is implemented in hardware.

Complex Numbers

ISO C99 introduces support for complex numbers in C. This is done with a new type qualifier, complex. It is a keyword if and only if `complex.h' has been included. There are three complex types, corresponding to the three real types: float complex, double complex, and long double complex.

To construct complex numbers you need a way to indicate the imaginary part of a number. There is no standard notation for an imaginary floating point constant. Instead, `complex.h' defines two macros that can be used to create complex numbers.

Macro: const float complex _Complex_I
This macro is a representation of the complex number "@math{0+1i}". Multiplying a real floating-point value by _Complex_I gives a complex number whose value is purely imaginary. You can use this to construct complex constants:
@math{3.0 + 4.0i} = 3.0 + 4.0 * _Complex_I
Note that _Complex_I * _Complex_I has the value -1, but the type of that value is complex.

_Complex_I is a bit of a mouthful. `complex.h' also defines a shorter name for the same constant.

Macro: const float complex I
This macro has exactly the same value as _Complex_I. Most of the time it is preferable. However, it causes problems if you want to use the identifier I for something else. You can safely write
#include <complex.h>
#undef I
if you need I for your own purposes. (In that case we recommend you also define some other short name for _Complex_I, such as J.)

Projections, Conjugates, and Decomposing of Complex Numbers

ISO C99 also defines functions that perform basic operations on complex numbers, such as decomposition and conjugation. The prototypes for all these functions are in `complex.h'. All functions are available in three variants, one for each of the three complex types.

Function: double creal (complex double z)

Function: float crealf (complex float z)

Function: long double creall (complex long double z)
These functions return the real part of the complex number z.

Function: double cimag (complex double z)

Function: float cimagf (complex float z)

Function: long double cimagl (complex long double z)
These functions return the imaginary part of the complex number z.

Function: complex double conj (complex double z)

Function: complex float conjf (complex float z)

Function: complex long double conjl (complex long double z)
These functions return the conjugate value of the complex number z. The conjugate of a complex number has the same real part and a negated imaginary part. In other words, `conj(a + bi) = a + -bi'.

Function: double carg (complex double z)

Function: float cargf (complex float z)

Function: long double cargl (complex long double z)
These functions return the argument of the complex number z. The argument of a complex number is the angle in the complex plane between the positive real axis and a line passing through zero and the number. This angle is measured in the usual fashion and ranges from @math{0} to @math{2@pi{}}.

carg has a branch cut along the positive real axis.

Function: complex double cproj (complex double z)

Function: complex float cprojf (complex float z)

Function: complex long double cprojl (complex long double z)
These functions return the projection of the complex value z onto the Riemann sphere. Values with a infinite imaginary part are projected to positive infinity on the real axis, even if the real part is NaN. If the real part is infinite, the result is equivalent to
INFINITY + I * copysign (0.0, cimag (z))
Parsing of Numbers

This section describes functions for "reading" integer and floating-point numbers from a string. It may be more convenient in some cases to use sscanf or one of the related functions; see section Formatted Input. But often you can make a program more robust by finding the tokens in the string by hand, then converting the numbers one by one.

Parsing of Integers

The `str' functions are declared in `stdlib.h' and those beginning with `wcs' are declared in `wchar.h'. One might wonder about the use of restrict in the prototypes of the functions in this section. It is seemingly useless but the ISO C standard uses it (for the functions defined there) so we have to do it as well.

Function: long int strtol (const char *restrict string, char **restrict tailptr, int base)
The strtol ("string-to-long") function converts the initial part of string to a signed integer, which is returned as a value of type long int.

This function attempts to decompose string as follows:

A (possibly empty) sequence of whitespace characters. Which characters are whitespace is determined by the isspace function (see section Classification of Characters). These are discarded.
An optional plus or minus sign (`+' or `-').
A nonempty sequence of digits in the radix specified by base. If base is zero, decimal radix is assumed unless the series of digits begins with `0' (specifying octal radix), or `0x' or `0X' (specifying hexadecimal radix); in other words, the same syntax used for integer constants in C. Otherwise base must have a value between 2 and 36. If base is 16, the digits may optionally be preceded by `0x' or `0X'. If base has no legal value the value returned is 0l and the global variable errno is set to EINVAL.
Any remaining characters in the string. If tailptr is not a null pointer, strtol stores a pointer to this tail in *tailptr.

If the string is empty, contains only whitespace, or does not contain an initial substring that has the expected syntax for an integer in the specified base, no conversion is performed. In this case, strtol returns a value of zero and the value stored in *tailptr is the value of string.

In a locale other than the standard "C" locale, this function may recognize additional implementation-dependent syntax.

If the string has valid syntax for an integer but the value is not representable because of overflow, strtol returns either LONG_MAX or LONG_MIN (see section Range of an Integer Type), as appropriate for the sign of the value. It also sets errno to ERANGE to indicate there was overflow.

You should not check for errors by examining the return value of strtol, because the string might be a valid representation of 0l, LONG_MAX, or LONG_MIN. Instead, check whether tailptr points to what you expect after the number (e.g. '\0' if the string should end after the number). You also need to clear errno before the call and check it afterward, in case there was overflow.

There is an example at the end of this section.

Function: long int wcstol (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
The wcstol function is equivalent to the strtol function in nearly all aspects but handles wide character strings.

The wcstol function was introduced in Amendment 1 of ISO C90.

Function: unsigned long int strtoul (const char *retrict string, char **restrict tailptr, int base)
The strtoul ("string-to-unsigned-long") function is like strtol except it converts to an unsigned long int value. The syntax is the same as described above for strtol. The value returned on overflow is ULONG_MAX (see section Range of an Integer Type).

If string depicts a negative number, strtoul acts the same as strtol but casts the result to an unsigned integer. That means for example that strtoul on "-1" returns ULONG_MAX and an input more negative than LONG_MIN returns (ULONG_MAX + 1) / 2.

strtoul sets errno to EINVAL if base is out of range, or ERANGE on overflow.

Function: unsigned long int wcstoul (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
The wcstoul function is equivalent to the strtoul function in nearly all aspects but handles wide character strings.

The wcstoul function was introduced in Amendment 1 of ISO C90.

Function: long long int strtoll (const char *restrict string, char **restrict tailptr, int base)
The strtoll function is like strtol except that it returns a long long int value, and accepts numbers with a correspondingly larger range.

If the string has valid syntax for an integer but the value is not representable because of overflow, strtoll returns either LONG_LONG_MAX or LONG_LONG_MIN (see section Range of an Integer Type), as appropriate for the sign of the value. It also sets errno to ERANGE to indicate there was overflow.

The strtoll function was introduced in ISO C99.

Function: long long int wcstoll (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
The wcstoll function is equivalent to the strtoll function in nearly all aspects but handles wide character strings.

The wcstoll function was introduced in Amendment 1 of ISO C90.

Function: long long int strtoq (const char *restrict string, char **restrict tailptr, int base)
strtoq ("string-to-quad-word") is the BSD name for strtoll.

Function: long long int wcstoq (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
The wcstoq function is equivalent to the strtoq function in nearly all aspects but handles wide character strings.

The wcstoq function is a GNU extension.

Function: unsigned long long int strtoull (const char *restrict string, char **restrict tailptr, int base)
The strtoull function is related to strtoll the same way strtoul is related to strtol.

The strtoull function was introduced in ISO C99.

Function: unsigned long long int wcstoull (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
The wcstoull function is equivalent to the strtoull function in nearly all aspects but handles wide character strings.

The wcstoull function was introduced in Amendment 1 of ISO C90.

Function: unsigned long long int strtouq (const char *restrict string, char **restrict tailptr, int base)
strtouq is the BSD name for strtoull.

Function: unsigned long long int wcstouq (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
The wcstouq function is equivalent to the strtouq function in nearly all aspects but handles wide character strings.

The wcstoq function is a GNU extension.

Function: intmax_t strtoimax (const char *restrict string, char **restrict tailptr, int base)
The strtoimax function is like strtol except that it returns a intmax_t value, and accepts numbers of a corresponding range.

If the string has valid syntax for an integer but the value is not representable because of overflow, strtoimax returns either INTMAX_MAX or INTMAX_MIN (see section Integers), as appropriate for the sign of the value. It also sets errno to ERANGE to indicate there was overflow.

See section Integers for a description of the intmax_t type. The strtoimax function was introduced in ISO C99.

Function: intmax_t wcstoimax (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
The wcstoimax function is equivalent to the strtoimax function in nearly all aspects but handles wide character strings.

The wcstoimax function was introduced in ISO C99.

Function: uintmax_t strtoumax (const char *restrict string, char **restrict tailptr, int base)
The strtoumax function is related to strtoimax the same way that strtoul is related to strtol.

See section Integers for a description of the intmax_t type. The strtoumax function was introduced in ISO C99.

Function: uintmax_t wcstoumax (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
The wcstoumax function is equivalent to the strtoumax function in nearly all aspects but handles wide character strings.

The wcstoumax function was introduced in ISO C99.

Function: long int atol (const char *string)
This function is similar to the strtol function with a base argument of 10, except that it need not detect overflow errors. The atol function is provided mostly for compatibility with existing code; using strtol is more robust.

Function: int atoi (const char *string)
This function is like atol, except that it returns an int. The atoi function is also considered obsolete; use strtol instead.

Function: long long int atoll (const char *string)
This function is similar to atol, except it returns a long long int.

The atoll function was introduced in ISO C99. It too is obsolete (despite having just been added); use strtoll instead.

All the functions mentioned in this section so far do not handle alternative representations of characters as described in the locale data. Some locales specify thousands separator and the way they have to be used which can help to make large numbers more readable. To read such numbers one has to use the scanf functions with the `'' flag.

Here is a function which parses a string as a sequence of integers and returns the sum of them:
int
sum_ints_from_string (char *string)
{
  int sum = 0;

  while (1) {
    char *tail;
    int next;

    /* Skip whitespace by hand, to detect the end.  */
    while (isspace (*string)) string++;
    if (*string == 0)
      break;

    /* There is more nonwhitespace,  */
    /* so it ought to be another number.  */
    errno = 0;
    /* Parse it.  */
    next = strtol (string, &tail, 0);
    /* Add it in, if not overflow.  */
    if (errno)
      printf ("Overflow\n");
    else
      sum += next;
    /* Advance past it.  */
    string = tail;
  }

  return sum;
}
Parsing of Floats

The `str' functions are declared in `stdlib.h' and those beginning with `wcs' are declared in `wchar.h'. One might wonder about the use of restrict in the prototypes of the functions in this section. It is seemingly useless but the ISO C standard uses it (for the functions defined there) so we have to do it as well.

Function: double strtod (const char *restrict string, char **restrict tailptr)
The strtod ("string-to-double") function converts the initial part of string to a floating-point number, which is returned as a value of type double.

This function attempts to decompose string as follows:

A (possibly empty) sequence of whitespace characters. Which characters are whitespace is determined by the isspace function (see section Classification of Characters). These are discarded.
An optional plus or minus sign (`+' or `-').
A floating point number in decimal or hexadecimal format. The decimal format is:

A nonempty sequence of digits optionally containing a decimal-point character--normally `.', but it depends on the locale (see section Generic Numeric Formatting Parameters).
An optional exponent part, consisting of a character `e' or `E', an optional sign, and a sequence of digits.
The hexadecimal format is as follows:

A 0x or 0X followed by a nonempty sequence of hexadecimal digits optionally containing a decimal-point character--normally `.', but it depends on the locale (see section Generic Numeric Formatting Parameters).
An optional binary-exponent part, consisting of a character `p' or `P', an optional sign, and a sequence of digits.

Any remaining characters in the string. If tailptr is not a null pointer, a pointer to this tail of the string is stored in *tailptr.

If the string is empty, contains only whitespace, or does not contain an initial substring that has the expected syntax for a floating-point number, no conversion is performed. In this case, strtod returns a value of zero and the value returned in *tailptr is the value of string.

In a locale other than the standard "C" or "POSIX" locales, this function may recognize additional locale-dependent syntax.

If the string has valid syntax for a floating-point number but the value is outside the range of a double, strtod will signal overflow or underflow as described in section Error Reporting by Mathematical Functions.

strtod recognizes four special input strings. The strings "inf" and "infinity" are converted to @math{@infinity{}}, or to the largest representable value if the floating-point format doesn't support infinities. You can prepend a "+" or "-" to specify the sign. Case is ignored when scanning these strings.

The strings "nan" and "nan(chars...)" are converted to NaN. Again, case is ignored. If chars... are provided, they are used in some unspecified fashion to select a particular representation of NaN (there can be several).

Since zero is a valid result as well as the value returned on error, you should check for errors in the same way as for strtol, by examining errno and tailptr.

Function: float strtof (const char *string, char **tailptr)

Function: long double strtold (const char *string, char **tailptr)
These functions are analogous to strtod, but return float and long double values respectively. They report errors in the same way as strtod. strtof can be substantially faster than strtod, but has less precision; conversely, strtold can be much slower but has more precision (on systems where long double is a separate type).

These functions have been GNU extensions and are new to ISO C99.

Function: double wcstod (const wchar_t *restrict string, wchar_t **restrict tailptr)

Function: float wcstof (const wchar_t *string, wchar_t **tailptr)

Function: long double wcstold (const wchar_t *string, wchar_t **tailptr)
The wcstod, wcstof, and wcstol functions are equivalent in nearly all aspect to the strtod, strtof, and strtold functions but it handles wide character string.

The wcstod function was introduced in Amendment 1 of ISO C90. The wcstof and wcstold functions were introduced in ISO C99.

Function: double atof (const char *string)
This function is similar to the strtod function, except that it need not detect overflow and underflow errors. The atof function is provided mostly for compatibility with existing code; using strtod is more robust.

The GNU C library also provides `_l' versions of these functions, which take an additional argument, the locale to use in conversion. See section Parsing of Integers.

Old-fashioned System V number-to-string functions

The old System V C library provided three functions to convert numbers to strings, with unusual and hard-to-use semantics. The GNU C library also provides these functions and some natural extensions.

These functions are only available in glibc and on systems descended from AT&T Unix. Therefore, unless these functions do precisely what you need, it is better to use sprintf, which is standard.

All these functions are defined in `stdlib.h'.

Function: char * ecvt (double value, int ndigit, int *decpt, int *neg)
The function ecvt converts the floating-point number value to a string with at most ndigit decimal digits. The returned string contains no decimal point or sign. The first digit of the string is non-zero (unless value is actually zero) and the last digit is rounded to nearest. *decpt is set to the index in the string of the first digit after the decimal point. *neg is set to a nonzero value if value is negative, zero otherwise.

If ndigit decimal digits would exceed the precision of a double it is reduced to a system-specific value.

The returned string is statically allocated and overwritten by each call to ecvt.

If value is zero, it is implementation defined whether *decpt is 0 or 1.

For example: ecvt (12.3, 5, &d, &n) returns "12300" and sets d to 2 and n to 0.

Function: char * fcvt (double value, int ndigit, int *decpt, int *neg)
The function fcvt is like ecvt, but ndigit specifies the number of digits after the decimal point. If ndigit is less than zero, value is rounded to the @math{ndigit+1}'th place to the left of the decimal point. For example, if ndigit is -1, value will be rounded to the nearest 10. If ndigit is negative and larger than the number of digits to the left of the decimal point in value, value will be rounded to one significant digit.

If ndigit decimal digits would exceed the precision of a double it is reduced to a system-specific value.

The returned string is statically allocated and overwritten by each call to fcvt.

Function: char * gcvt (double value, int ndigit, char *buf)
gcvt is functionally equivalent to `sprintf(buf, "%*g", ndigit, value'. It is provided only for compatibility's sake. It returns buf.

If ndigit decimal digits would exceed the precision of a double it is reduced to a system-specific value.

As extensions, the GNU C library provides versions of these three functions that take long double arguments.

Function: char * qecvt (long double value, int ndigit, int *decpt, int *neg)
This function is equivalent to ecvt except that it takes a long double for the first parameter and that ndigit is restricted by the precision of a long double.

Function: char * qfcvt (long double value, int ndigit, int *decpt, int *neg)
This function is equivalent to fcvt except that it takes a long double for the first parameter and that ndigit is restricted by the precision of a long double.

Function: char * qgcvt (long double value, int ndigit, char *buf)
This function is equivalent to gcvt except that it takes a long double for the first parameter and that ndigit is restricted by the precision of a long double.

The ecvt and fcvt functions, and their long double equivalents, all return a string located in a static buffer which is overwritten by the next call to the function. The GNU C library provides another set of extended functions which write the converted string into a user-supplied buffer. These have the conventional _r suffix.

gcvt_r is not necessary, because gcvt already uses a user-supplied buffer.

Function: char * ecvt_r (double value, int ndigit, int *decpt, int *neg, char *buf, size_t len)
The ecvt_r function is the same as ecvt, except that it places its result into the user-specified buffer pointed to by buf, with length len.

This function is a GNU extension.

Function: char * fcvt_r (double value, int ndigit, int *decpt, int *neg, char *buf, size_t len)
The fcvt_r function is the same as fcvt, except that it places its result into the user-specified buffer pointed to by buf, with length len.

This function is a GNU extension.

Function: char * qecvt_r (long double value, int ndigit, int *decpt, int *neg, char *buf, size_t len)
The qecvt_r function is the same as qecvt, except that it places its result into the user-specified buffer pointed to by buf, with length len.

This function is a GNU extension.

Function: char * qfcvt_r (long double value, int ndigit, int *decpt, int *neg, char *buf, size_t len)
The qfcvt_r function is the same as qfcvt, except that it places its result into the user-specified buffer pointed to by buf, with length len.

This function is a GNU extension.
Date and Time

This chapter describes functions for manipulating dates and times, including functions for determining what time it is and conversion between different time representations.

Time Basics

Discussing time in a technical manual can be difficult because the word "time" in English refers to lots of different things. In this manual, we use a rigorous terminology to avoid confusion, and the only thing we use the simple word "time" for is to talk about the abstract concept.

A calendar time is a point in the time continuum, for example November 4, 1990 at 18:02.5 UTC. Sometimes this is called "absolute time".

We don't speak of a "date", because that is inherent in a calendar time.

An interval is a contiguous part of the time continuum between two calendar times, for example the hour between 9:00 and 10:00 on July 4, 1980.

An elapsed time is the length of an interval, for example, 35 minutes. People sometimes sloppily use the word "interval" to refer to the elapsed time of some interval.

An amount of time is a sum of elapsed times, which need not be of any specific intervals. For example, the amount of time it takes to read a book might be 9 hours, independently of when and in how many sittings it is read.

A period is the elapsed time of an interval between two events, especially when they are part of a sequence of regularly repeating events.

CPU time is like calendar time, except that it is based on the subset of the time continuum when a particular process is actively using a CPU. CPU time is, therefore, relative to a process.

Processor time is an amount of time that a CPU is in use. In fact, it's a basic system resource, since there's a limit to how much can exist in any given interval (that limit is the elapsed time of the interval times the number of CPUs in the processor). People often call this CPU time, but we reserve the latter term in this manual for the definition above.

Elapsed Time

One way to represent an elapsed time is with a simple arithmetic data type, as with the following function to compute the elapsed time between two calendar times. This function is declared in `time.h'.

Function: double difftime (time_t time1, time_t time0)
The difftime function returns the number of seconds of elapsed time between calendar time time1 and calendar time time0, as a value of type double. The difference ignores leap seconds unless leap second support is enabled.

In the GNU system, you can simply subtract time_t values. But on other systems, the time_t data type might use some other encoding where subtraction doesn't work directly.

The GNU C library provides two data types specifically for representing an elapsed time. They are used by various GNU C library functions, and you can use them for your own purposes too. They're exactly the same except that one has a resolution in microseconds, and the other, newer one, is in nanoseconds.

Data Type: struct timeval
The struct timeval structure represents an elapsed time. It is declared in `sys/time.h' and has the following members:

long int tv_sec
This represents the number of whole seconds of elapsed time.
long int tv_usec
This is the rest of the elapsed time (a fraction of a second), represented as the number of microseconds. It is always less than one million.

Data Type: struct timespec
The struct timespec structure represents an elapsed time. It is declared in `time.h' and has the following members:

long int tv_sec
This represents the number of whole seconds of elapsed time.
long int tv_nsec
This is the rest of the elapsed time (a fraction of a second), represented as the number of nanoseconds. It is always less than one billion.
It is often necessary to subtract two values of type struct timeval or struct timespec. Here is the best way to do this. It works even on some peculiar operating systems where the tv_sec member has an unsigned type.
/* Subtract the `struct timeval' values X and Y,
   storing the result in RESULT.
   Return 1 if the difference is negative, otherwise 0.  */

int
timeval_subtract (result, x, y)
     struct timeval *result, *x, *y;
{
  /* Perform the carry for the later subtraction by updating y. */
  if (x->tv_usec < y->tv_usec) {
    int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
    y->tv_usec -= 1000000 * nsec;
    y->tv_sec += nsec;
  }
  if (x->tv_usec - y->tv_usec > 1000000) {
    int nsec = (x->tv_usec - y->tv_usec) / 1000000;
    y->tv_usec += 1000000 * nsec;
    y->tv_sec -= nsec;
  }

  /* Compute the time remaining to wait.
     tv_usec is certainly positive. */
  result->tv_sec = x->tv_sec - y->tv_sec;
  result->tv_usec = x->tv_usec - y->tv_usec;

  /* Return 1 if result is negative. */
  return x->tv_sec < y->tv_sec;
}
Common functions that use struct timeval are gettimeofday and settimeofday.

There are no GNU C library functions specifically oriented toward dealing with elapsed times, but the calendar time, processor time, and alarm and sleeping functions have a lot to do with them.

Processor And CPU Time

If you're trying to optimize your program or measure its efficiency, it's very useful to know how much processor time it uses. For that, calendar time and elapsed times are useless because a process may spend time waiting for I/O or for other processes to use the CPU. However, you can get the information with the functions in this section.

CPU time (see section Time Basics) is represented by the data type clock_t, which is a number of clock ticks. It gives the total amount of time a process has actively used a CPU since some arbitrary event. On the GNU system, that event is the creation of the process. While arbitrary in general, the event is always the same event for any particular process, so you can always measure how much time on the CPU a particular computation takes by examinining the process' CPU time before and after the computation.

In the GNU system, clock_t is equivalent to long int and CLOCKS_PER_SEC is an integer value. But in other systems, both clock_t and the macro CLOCKS_PER_SEC can be either integer or floating-point types. Casting CPU time values to double, as in the example above, makes sure that operations such as arithmetic and printing work properly and consistently no matter what the underlying representation is.

Note that the clock can wrap around. On a 32bit system with CLOCKS_PER_SEC set to one million this function will return the same value approximately every 72 minutes.

For additional functions to examine a process' use of processor time, and to control it, See section Resource Usage And Limitation.

CPU Time Inquiry

To get a process' CPU time, you can use the clock function. This facility is declared in the header file `time.h'.

In typical usage, you call the clock function at the beginning and end of the interval you want to time, subtract the values, and then divide by CLOCKS_PER_SEC (the number of clock ticks per second) to get processor time, like this:
#include <time.h>

clock_t start, end;
double cpu_time_used;

start = clock();
... /* Do the work. */
end = clock();
cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;
Do not use a single CPU time as an amount of time; it doesn't work that way. Either do a subtraction as shown above or query processor time directly. See section Processor Time Inquiry.

Different computers and operating systems vary wildly in how they keep track of CPU time. It's common for the internal processor clock to have a resolution somewhere between a hundredth and millionth of a second.

Macro: int CLOCKS_PER_SEC
The value of this macro is the number of clock ticks per second measured by the clock function. POSIX requires that this value be one million independent of the actual resolution.

Macro: int CLK_TCK
This is an obsolete name for CLOCKS_PER_SEC.

Data Type: clock_t
This is the type of the value returned by the clock function. Values of type clock_t are numbers of clock ticks.

Function: clock_t clock (void)
This function returns the calling process' current CPU time. If the CPU time is not available or cannot be represented, clock returns the value (clock_t)(-1).

Processor Time Inquiry

The times function returns information about a process' consumption of processor time in a struct tms object, in addition to the process' CPU time. See section Time Basics. You should include the header file `sys/times.h' to use this facility.

Data Type: struct tms
The tms structure is used to return information about process times. It contains at least the following members:

clock_t tms_utime
This is the total processor time the calling process has used in executing the instructions of its program.
clock_t tms_stime
This is the processor time the system has used on behalf of the calling process.
clock_t tms_cutime
This is the sum of the tms_utime values and the tms_cutime values of all terminated child processes of the calling process, whose status has been reported to the parent process by wait or waitpid; see section Process Completion. In other words, it represents the total processor time used in executing the instructions of all the terminated child processes of the calling process, excluding child processes which have not yet been reported by wait or waitpid.
clock_t tms_cstime
This is similar to tms_cutime, but represents the total processor time system has used on behalf of all the terminated child processes of the calling process.
All of the times are given in numbers of clock ticks. Unlike CPU time, these are the actual amounts of time; not relative to any event. See section Creating a Process.

Function: clock_t times (struct tms *buffer)
The times function stores the processor time information for the calling process in buffer.

The return value is the calling process' CPU time (the same value you get from clock(). times returns (clock_t)(-1) to indicate failure.

Portability Note: The clock function described in section CPU Time Inquiry is specified by the ISO C standard. The times function is a feature of POSIX.1. In the GNU system, the CPU time is defined to be equivalent to the sum of the tms_utime and tms_stime fields returned by times.

Calendar Time

This section describes facilities for keeping track of calendar time. See section Time Basics.

The GNU C library represents calendar time three ways:

Simple time (the time_t data type) is a compact representation, typically giving the number of seconds of elapsed time since some implementation-specific base time.
There is also a "high-resolution time" representation. Like simple time, this represents a calendar time as an elapsed time since a base time, but instead of measuring in whole seconds, it uses a struct timeval data type, which includes fractions of a second. Use this time representation instead of simple time when you need greater precision.
Local time or broken-down time (the struct tm data type) represents a calendar time as a set of components specifying the year, month, and so on in the Gregorian calendar, for a specific time zone. This calendar time representation is usually used only to communicate with people.

Simple Calendar Time

This section describes the time_t data type for representing calendar time as simple time, and the functions which operate on simple time objects. These facilities are declared in the header file `time.h'.

Data Type: time_t
This is the data type used to represent simple time. Sometimes, it also represents an elapsed time. When interpreted as a calendar time value, it represents the number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time. (This calendar time is sometimes referred to as the epoch.) POSIX requires that this count not include leap seconds, but on some systems this count includes leap seconds if you set TZ to certain values (see section Specifying the Time Zone with TZ).

Note that a simple time has no concept of local time zone. Calendar Time T is the same instant in time regardless of where on the globe the computer is.

In the GNU C library, time_t is equivalent to long int. In other systems, time_t might be either an integer or floating-point type.

The function difftime tells you the elapsed time between two simple calendar times, which is not always as easy to compute as just subtracting. See section Elapsed Time.

Function: time_t time (time_t *result)
The time function returns the current calendar time as a value of type time_t. If the argument result is not a null pointer, the calendar time value is also stored in *result. If the current calendar time is not available, the value (time_t)(-1) is returned.

Function: int stime (time_t *newtime)
stime sets the system clock, i.e. it tells the system that the current calendar time is newtime, where newtime is interpreted as described in the above definition of time_t.

settimeofday is a newer function which sets the system clock to better than one second precision. settimeofday is generally a better choice than stime. See section High-Resolution Calendar.

Only the superuser can set the system clock.

If the function succeeds, the return value is zero. Otherwise, it is -1 and errno is set accordingly:

EPERM
The process is not superuser.
High-Resolution Calendar

The time_t data type used to represent simple times has a resolution of only one second. Some applications need more precision.

So, the GNU C library also contains functions which are capable of representing calendar times to a higher resolution than one second. The functions and the associated data types described in this section are declared in `sys/time.h'.

Data Type: struct timezone
The struct timezone structure is used to hold minimal information about the local time zone. It has the following members:

int tz_minuteswest
This is the number of minutes west of UTC.
int tz_dsttime
If nonzero, Daylight Saving Time applies during some part of the year.
The struct timezone type is obsolete and should never be used. Instead, use the facilities described in section Functions and Variables for Time Zones.

Function: int gettimeofday (struct timeval *tp, struct timezone *tzp)
The gettimeofday function returns the current calendar time as the elapsed time since the epoch in the struct timeval structure indicated by tp. (see section Elapsed Time for a description of struct timespec). Information about the time zone is returned in the structure pointed at tzp. If the tzp argument is a null pointer, time zone information is ignored.

The return value is 0 on success and -1 on failure. The following errno error condition is defined for this function:

ENOSYS
The operating system does not support getting time zone information, and tzp is not a null pointer. The GNU operating system does not support using struct timezone to represent time zone information; that is an obsolete feature of 4.3 BSD. Instead, use the facilities described in section Functions and Variables for Time Zones.

Function: int settimeofday (const struct timeval *tp, const struct timezone *tzp)
The settimeofday function sets the current calendar time in the system clock according to the arguments. As for gettimeofday, the calendar time is represented as the elapsed time since the epoch. As for gettimeofday, time zone information is ignored if tzp is a null pointer.

You must be a privileged user in order to use settimeofday.

Some kernels automatically set the system clock from some source such as a hardware clock when they start up. Others, including Linux, place the system clock in an "invalid" state (in which attempts to read the clock fail). A call of stime removes the system clock from an invalid state, and system startup scripts typically run a program that calls stime.

settimeofday causes a sudden jump forwards or backwards, which can cause a variety of problems in a system. Use adjtime (below) to make a smooth transition from one time to another by temporarily speeding up or slowing down the clock.

With a Linux kernel, adjtimex does the same thing and can also make permanent changes to the speed of the system clock so it doesn't need to be corrected as often.

The return value is 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EPERM
This process cannot set the clock because it is not privileged.
ENOSYS
The operating system does not support setting time zone information, and tzp is not a null pointer.

Function: int adjtime (const struct timeval *delta, struct timeval *olddelta)
This function speeds up or slows down the system clock in order to make a gradual adjustment. This ensures that the calendar time reported by the system clock is always monotonically increasing, which might not happen if you simply set the clock.

The delta argument specifies a relative adjustment to be made to the clock time. If negative, the system clock is slowed down for a while until it has lost this much elapsed time. If positive, the system clock is speeded up for a while.

If the olddelta argument is not a null pointer, the adjtime function returns information about any previous time adjustment that has not yet completed.

This function is typically used to synchronize the clocks of computers in a local network. You must be a privileged user to use it.

With a Linux kernel, you can use the adjtimex function to permanently change the clock speed.

The return value is 0 on success and -1 on failure. The following errno error condition is defined for this function:

EPERM
You do not have privilege to set the time.
Portability Note: The gettimeofday, settimeofday, and adjtime functions are derived from BSD.

Symbols for the following function are declared in `sys/timex.h'.

Function: int adjtimex (struct timex *timex)

adjtimex is functionally identical to ntp_adjtime. See section High Accuracy Clock.

This function is present only with a Linux kernel.

Broken-down Time

Calendar time is represented by the usual GNU C library functions as an elapsed time since a fixed base calendar time. This is convenient for computation, but has no relation to the way people normally think of calendar time. By contrast, broken-down time is a binary representation of calendar time separated into year, month, day, and so on. Broken-down time values are not useful for calculations, but they are useful for printing human readable time information.

A broken-down time value is always relative to a choice of time zone, and it also indicates which time zone that is.

The symbols in this section are declared in the header file `time.h'.

Data Type: struct tm
This is the data type used to represent a broken-down time. The structure contains at least the following members, which can appear in any order.

int tm_sec
This is the number of full seconds since the top of the minute (normally in the range 0 through 59, but the actual upper limit is 60, to allow for leap seconds if leap second support is available).
int tm_min
This is the number of full minutes since the top of the hour (in the range 0 through 59).
int tm_hour
This is the number of full hours past midnight (in the range 0 through 23).
int tm_mday
This is the ordinal day of the month (in the range 1 through 31). Watch out for this one! As the only ordinal number in the structure, it is inconsistent with the rest of the structure.
int tm_mon
This is the number of full calendar months since the beginning of the year (in the range 0 through 11). Watch out for this one! People usually use ordinal numbers for month-of-year (where January = 1).
int tm_year
This is the number of full calendar years since 1900.
int tm_wday
This is the number of full days since Sunday (in the range 0 through 6).
int tm_yday
This is the number of full days since the beginning of the year (in the range 0 through 365).
int tm_isdst
This is a flag that indicates whether Daylight Saving Time is (or was, or will be) in effect at the time described. The value is positive if Daylight Saving Time is in effect, zero if it is not, and negative if the information is not available.
long int tm_gmtoff
This field describes the time zone that was used to compute this broken-down time value, including any adjustment for daylight saving; it is the number of seconds that you must add to UTC to get local time. You can also think of this as the number of seconds east of UTC. For example, for U.S. Eastern Standard Time, the value is -5*60*60. The tm_gmtoff field is derived from BSD and is a GNU library extension; it is not visible in a strict ISO C environment.
const char *tm_zone
This field is the name for the time zone that was used to compute this broken-down time value. Like tm_gmtoff, this field is a BSD and GNU extension, and is not visible in a strict ISO C environment.

Function: struct tm * localtime (const time_t *time)
The localtime function converts the simple time pointed to by time to broken-down time representation, expressed relative to the user's specified time zone.

The return value is a pointer to a static broken-down time structure, which might be overwritten by subsequent calls to ctime, gmtime, or localtime. (But no other library function overwrites the contents of this object.)

The return value is the null pointer if time cannot be represented as a broken-down time; typically this is because the year cannot fit into an int.

Calling localtime has one other effect: it sets the variable tzname with information about the current time zone. See section Functions and Variables for Time Zones.

Using the localtime function is a big problem in multi-threaded programs. The result is returned in a static buffer and this is used in all threads. POSIX.1c introduced a variant of this function.

Function: struct tm * localtime_r (const time_t *time, struct tm *resultp)
The localtime_r function works just like the localtime function. It takes a pointer to a variable containing a simple time and converts it to the broken-down time format.

But the result is not placed in a static buffer. Instead it is placed in the object of type struct tm to which the parameter resultp points.

If the conversion is successful the function returns a pointer to the object the result was written into, i.e., it returns resultp.

Function: struct tm * gmtime (const time_t *time)
This function is similar to localtime, except that the broken-down time is expressed as Coordinated Universal Time (UTC) (formerly called Greenwich Mean Time (GMT)) rather than relative to a local time zone.

As for the localtime function we have the problem that the result is placed in a static variable. POSIX.1c also provides a replacement for gmtime.

Function: struct tm * gmtime_r (const time_t *time, struct tm *resultp)
This function is similar to localtime_r, except that it converts just like gmtime the given time as Coordinated Universal Time.

If the conversion is successful the function returns a pointer to the object the result was written into, i.e., it returns resultp.

Function: time_t mktime (struct tm *brokentime)
The mktime function is used to convert a broken-down time structure to a simple time representation. It also "normalizes" the contents of the broken-down time structure, by filling in the day of week and day of year based on the other date and time components.

The mktime function ignores the specified contents of the tm_wday and tm_yday members of the broken-down time structure. It uses the values of the other components to determine the calendar time; it's permissible for these components to have unnormalized values outside their normal ranges. The last thing that mktime does is adjust the components of the brokentime structure (including the tm_wday and tm_yday).

If the specified broken-down time cannot be represented as a simple time, mktime returns a value of (time_t)(-1) and does not modify the contents of brokentime.

Calling mktime also sets the variable tzname with information about the current time zone. See section Functions and Variables for Time Zones.

Function: time_t timelocal (struct tm *brokentime)

timelocal is functionally identical to mktime, but more mnemonically named. Note that it is the inverse of the localtime function.

Portability note: mktime is essentially universally available. timelocal is rather rare.

Function: time_t timegm (struct tm *brokentime)

timegm is functionally identical to mktime except it always takes the input values to be Coordinated Universal Time (UTC) regardless of any local time zone setting.

Note that timegm is the inverse of gmtime.

Portability note: mktime is essentially universally available. timegm is rather rare. For the most portable conversion from a UTC broken-down time to a simple time, set the TZ environment variable to UTC, call mktime, then set TZ back.

High Accuracy Clock

The ntp_gettime and ntp_adjtime functions provide an interface to monitor and manipulate the system clock to maintain high accuracy time. For example, you can fine tune the speed of the clock or synchronize it with another time source.

A typical use of these functions is by a server implementing the Network Time Protocol to synchronize the clocks of multiple systems and high precision clocks.

These functions are declared in `sys/timex.h'.

Data Type: struct ntptimeval
This structure is used for information about the system clock. It contains the following members:
struct timeval time
This is the current calendar time, expressed as the elapsed time since the epoch. The struct timeval data type is described in section Elapsed Time.
long int maxerror
This is the maximum error, measured in microseconds. Unless updated via ntp_adjtime periodically, this value will reach some platform-specific maximum value.
long int esterror
This is the estimated error, measured in microseconds. This value can be set by ntp_adjtime to indicate the estimated offset of the system clock from the true calendar time.

Function: int ntp_gettime (struct ntptimeval *tptr)
The ntp_gettime function sets the structure pointed to by tptr to current values. The elements of the structure afterwards contain the values the timer implementation in the kernel assumes. They might or might not be correct. If they are not a ntp_adjtime call is necessary.

The return value is 0 on success and other values on failure. The following errno error conditions are defined for this function:

TIME_ERROR
The precision clock model is not properly set up at the moment, thus the clock must be considered unsynchronized, and the values should be treated with care.

Data Type: struct timex
This structure is used to control and monitor the system clock. It contains the following members:
unsigned int modes
This variable controls whether and which values are set. Several symbolic constants have to be combined with binary or to specify the effective mode. These constants start with MOD_.
long int offset
This value indicates the current offset of the system clock from the true calendar time. The value is given in microseconds. If bit MOD_OFFSET is set in modes, the offset (and possibly other dependent values) can be set. The offset's absolute value must not exceed MAXPHASE.
long int frequency
This value indicates the difference in frequency between the true calendar time and the system clock. The value is expressed as scaled PPM (parts per million, 0.0001%). The scaling is 1 << SHIFT_USEC. The value can be set with bit MOD_FREQUENCY, but the absolute value must not exceed MAXFREQ.
long int maxerror
This is the maximum error, measured in microseconds. A new value can be set using bit MOD_MAXERROR. Unless updated via ntp_adjtime periodically, this value will increase steadily and reach some platform-specific maximum value.
long int esterror
This is the estimated error, measured in microseconds. This value can be set using bit MOD_ESTERROR.
int status
This variable reflects the various states of the clock machinery. There are symbolic constants for the significant bits, starting with STA_. Some of these flags can be updated using the MOD_STATUS bit.
long int constant
This value represents the bandwidth or stiffness of the PLL (phase locked loop) implemented in the kernel. The value can be changed using bit MOD_TIMECONST.
long int precision
This value represents the accuracy or the maximum error when reading the system clock. The value is expressed in microseconds.
long int tolerance
This value represents the maximum frequency error of the system clock in scaled PPM. This value is used to increase the maxerror every second.
struct timeval time
The current calendar time.
long int tick
The elapsed time between clock ticks in microseconds. A clock tick is a periodic timer interrupt on which the system clock is based.
long int ppsfreq
This is the first of a few optional variables that are present only if the system clock can use a PPS (pulse per second) signal to discipline the system clock. The value is expressed in scaled PPM and it denotes the difference in frequency between the system clock and the PPS signal.
long int jitter
This value expresses a median filtered average of the PPS signal's dispersion in microseconds.
int shift
This value is a binary exponent for the duration of the PPS calibration interval, ranging from PPS_SHIFT to PPS_SHIFTMAX.
long int stabil
This value represents the median filtered dispersion of the PPS frequency in scaled PPM.
long int jitcnt
This counter represents the number of pulses where the jitter exceeded the allowed maximum MAXTIME.
long int calcnt
This counter reflects the number of successful calibration intervals.
long int errcnt
This counter represents the number of calibration errors (caused by large offsets or jitter).
long int stbcnt
This counter denotes the number of of calibrations where the stability exceeded the threshold.

Function: int ntp_adjtime (struct timex *tptr)
The ntp_adjtime function sets the structure specified by tptr to current values.

In addition, ntp_adjtime updates some settings to match what you pass to it in *tptr. Use the modes element of *tptr to select what settings to update. You can set offset, freq, maxerror, esterror, status, constant, and tick.

modes = zero means set nothing.

Only the superuser can update settings.

The return value is 0 on success and other values on failure. The following errno error conditions are defined for this function:

TIME_ERROR
The high accuracy clock model is not properly set up at the moment, thus the clock must be considered unsynchronized, and the values should be treated with care. Another reason could be that the specified new values are not allowed.
EPERM
The process specified a settings update, but is not superuser.
For more details see RFC1305 (Network Time Protocol, Version 3) and related documents.

Portability note: Early versions of the GNU C library did not have this function but did have the synonymous adjtimex.

Formatting Calendar Time

The functions described in this section format calendar time values as strings. These functions are declared in the header file `time.h'.

Function: char * asctime (const struct tm *brokentime)
The asctime function converts the broken-down time value that brokentime points to into a string in a standard format:
"Tue May 21 13:46:22 1991\n"
The abbreviations for the days of week are: `Sun', `Mon', `Tue', `Wed', `Thu', `Fri', and `Sat'.

The abbreviations for the months are: `Jan', `Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and `Dec'.

The return value points to a statically allocated string, which might be overwritten by subsequent calls to asctime or ctime. (But no other library function overwrites the contents of this string.)

Function: char * asctime_r (const struct tm *brokentime, char *buffer)
This function is similar to asctime but instead of placing the result in a static buffer it writes the string in the buffer pointed to by the parameter buffer. This buffer should have room for at least 26 bytes, including the terminating null.

If no error occurred the function returns a pointer to the string the result was written into, i.e., it returns buffer. Otherwise return NULL.

Function: char * ctime (const time_t *time)
The ctime function is similar to asctime, except that you specify the calendar time argument as a time_t simple time value rather than in broken-down local time format. It is equivalent to
asctime (localtime (time))
ctime sets the variable tzname, because localtime does so. See section Functions and Variables for Time Zones.

Function: char * ctime_r (const time_t *time, char *buffer)
This function is similar to ctime, but places the result in the string pointed to by buffer. It is equivalent to (written using gcc extensions, see section `Statement Exprs' in Porting and Using gcc):
({ struct tm tm; asctime_r (localtime_r (time, &tm), buf); })
If no error occurred the function returns a pointer to the string the result was written into, i.e., it returns buffer. Otherwise return NULL.

Function: size_t strftime (char *s, size_t size, const char *template, const struct tm *brokentime)
This function is similar to the sprintf function (see section Formatted Input), but the conversion specifications that can appear in the format template template are specialized for printing components of the date and time brokentime according to the locale currently specified for time conversion (see section Locales and Internationalization).

Ordinary characters appearing in the template are copied to the output string s; this can include multibyte character sequences. Conversion specifiers are introduced by a `%' character, followed by an optional flag which can be one of the following. These flags are all GNU extensions. The first three affect only the output of numbers:

_
The number is padded with spaces.
-
The number is not padded at all.
0
The number is padded with zeros even if the format specifies padding with spaces.
^
The output uses uppercase characters, but only if this is possible (see section Case Conversion).
The default action is to pad the number with zeros to keep it a constant width. Numbers that do not have a range indicated below are never padded, since there is no natural width for them.

Following the flag an optional specification of the width is possible. This is specified in decimal notation. If the natural size of the output is of the field has less than the specified number of characters, the result is written right adjusted and space padded to the given size.

An optional modifier can follow the optional flag and width specification. The modifiers, which are POSIX.2 extensions, are:

E
Use the locale's alternate representation for date and time. This modifier applies to the %c, %C, %x, %X, %y and %Y format specifiers. In a Japanese locale, for example, %Ex might yield a date format based on the Japanese Emperors' reigns.
O
Use the locale's alternate numeric symbols for numbers. This modifier applies only to numeric format specifiers.
If the format supports the modifier but no alternate representation is available, it is ignored.

The conversion specifier ends with a format specifier taken from the following list. The whole `%' sequence is replaced in the output string as follows:

%a
The abbreviated weekday name according to the current locale.
%A
The full weekday name according to the current locale.
%b
The abbreviated month name according to the current locale.
%B
The full month name according to the current locale.
%c
The preferred calendar time representation for the current locale.
%C
The century of the year. This is equivalent to the greatest integer not greater than the year divided by 100. This format is a POSIX.2 extension and also appears in ISO C99.
%d
The day of the month as a decimal number (range 01 through 31).
%D
The date using the format %m/%d/%y. This format is a POSIX.2 extension and also appears in ISO C99.
%e
The day of the month like with %d, but padded with blank (range 1 through 31). This format is a POSIX.2 extension and also appears in ISO C99.
%F
The date using the format %Y-%m-%d. This is the form specified in the ISO 8601 standard and is the preferred form for all uses. This format is a ISO C99 extension.
%g
The year corresponding to the ISO week number, but without the century (range 00 through 99). This has the same format and value as %y, except that if the ISO week number (see %V) belongs to the previous or next year, that year is used instead. This format was introduced in ISO C99.
%G
The year corresponding to the ISO week number. This has the same format and value as %Y, except that if the ISO week number (see %V) belongs to the previous or next year, that year is used instead. This format was introduced in ISO C99 but was previously available as a GNU extension.
%h
The abbreviated month name according to the current locale. The action is the same as for %b. This format is a POSIX.2 extension and also appears in ISO C99.
%H
The hour as a decimal number, using a 24-hour clock (range 00 through 23).
%I
The hour as a decimal number, using a 12-hour clock (range 01 through 12).
%j
The day of the year as a decimal number (range 001 through 366).
%k
The hour as a decimal number, using a 24-hour clock like %H, but padded with blank (range 0 through 23). This format is a GNU extension.
%l
The hour as a decimal number, using a 12-hour clock like %I, but padded with blank (range 1 through 12). This format is a GNU extension.
%m
The month as a decimal number (range 01 through 12).
%M
The minute as a decimal number (range 00 through 59).
%n
A single `\n' (newline) character. This format is a POSIX.2 extension and also appears in ISO C99.
%p
Either `AM' or `PM', according to the given time value; or the corresponding strings for the current locale. Noon is treated as `PM' and midnight as `AM'.
%P
Either `am' or `pm', according to the given time value; or the corresponding strings for the current locale, printed in lowercase characters. Noon is treated as `pm' and midnight as `am'. This format was introduced in ISO C99 but was previously available as a GNU extension.
%r
The complete calendar time using the AM/PM format of the current locale. This format is a POSIX.2 extension and also appears in ISO C99.
%R
The hour and minute in decimal numbers using the format %H:%M. This format was introduced in ISO C99 but was previously available as a GNU extension.
%s
The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. Leap seconds are not counted unless leap second support is available. This format is a GNU extension.
%S
The seconds as a decimal number (range 00 through 60).
%t
A single `\t' (tabulator) character. This format is a POSIX.2 extension and also appears in ISO C99.
%T
The time of day using decimal numbers using the format %H:%M:%S. This format is a POSIX.2 extension.
%u
The day of the week as a decimal number (range 1 through 7), Monday being 1. This format is a POSIX.2 extension and also appears in ISO C99.
%U
The week number of the current year as a decimal number (range 00 through 53), starting with the first Sunday as the first day of the first week. Days preceding the first Sunday in the year are considered to be in week 00.
%V
The ISO 8601:1988 week number as a decimal number (range 01 through 53). ISO weeks start with Monday and end with Sunday. Week 01 of a year is the first week which has the majority of its days in that year; this is equivalent to the week containing the year's first Thursday, and it is also equivalent to the week containing January 4. Week 01 of a year can contain days from the previous year. The week before week 01 of a year is the last week (52 or 53) of the previous year even if it contains days from the new year. This format is a POSIX.2 extension and also appears in ISO C99.
%w
The day of the week as a decimal number (range 0 through 6), Sunday being 0.
%W
The week number of the current year as a decimal number (range 00 through 53), starting with the first Monday as the first day of the first week. All days preceding the first Monday in the year are considered to be in week 00.
%x
The preferred date representation for the current locale.
%X
The preferred time of day representation for the current locale.
%y
The year without a century as a decimal number (range 00 through 99). This is equivalent to the year modulo 100.
%Y
The year as a decimal number, using the Gregorian calendar. Years before the year 1 are numbered 0, -1, and so on.
%z
RFC 822/ISO 8601:1988 style numeric time zone (e.g., -0600 or +0100), or nothing if no time zone is determinable. This format was introduced in ISO C99 but was previously available as a GNU extension. A full RFC 822 timestamp is generated by the format `"%a, %d %b %Y %H:%M:%S %z"' (or the equivalent `"%a, %d %b %Y %T %z"').
%Z
The time zone abbreviation (empty if the time zone can't be determined).
%%
A literal `%' character.
The size parameter can be used to specify the maximum number of characters to be stored in the array s, including the terminating null character. If the formatted time requires more than size characters, strftime returns zero and the contents of the array s are undefined. Otherwise the return value indicates the number of characters placed in the array s, not including the terminating null character.

Warning: This convention for the return value which is prescribed in ISO C can lead to problems in some situations. For certain format strings and certain locales the output really can be the empty string and this cannot be discovered by testing the return value only. E.g., in most locales the AM/PM time format is not supported (most of the world uses the 24 hour time representation). In such locales "%p" will return the empty string, i.e., the return value is zero. To detect situations like this something similar to the following code should be used:
buf[0] = '\1';
len = strftime (buf, bufsize, format, tp);
if (len == 0 && buf[0] != '\0')
  {
    /* Something went wrong in the strftime call.  */
    ...
  }
If s is a null pointer, strftime does not actually write anything, but instead returns the number of characters it would have written.

According to POSIX.1 every call to strftime implies a call to tzset. So the contents of the environment variable TZ is examined before any output is produced.

For an example of strftime, see section Time Functions Example.

Function: size_t wcsftime (wchar_t *s, size_t size, const wchar_t *template, const struct tm *brokentime)
The wcsftime function is equivalent to the strftime function with the difference that it operates on wide character strings. The buffer where the result is stored, pointed to by s, must be an array of wide characters. The parameter size which specifies the size of the output buffer gives the number of wide character, not the number of bytes.

Also the format string template is a wide character string. Since all characters needed to specify the format string are in the basic character set it is portably possible to write format strings in the C source code using the L"..." notation. The parameter brokentime has the same meaning as in the strftime call.

The wcsftime function supports the same flags, modifiers, and format specifiers as the strftime function.

The return value of wcsftime is the number of wide characters stored in s. When more characters would have to be written than can be placed in the buffer s the return value is zero, with the same problems indicated in the strftime documentation.

Convert textual time and date information back

The ISO C standard does not specify any functions which can convert the output of the strftime function back into a binary format. This led to a variety of more-or-less successful implementations with different interfaces over the years. Then the Unix standard was extended by the addition of two functions: strptime and getdate. Both have strange interfaces but at least they are widely available.

Interpret string according to given format

he first function is rather low-level. It is nevertheless frequently used in software since it is better known. Its interface and implementation are heavily influenced by the getdate function, which is defined and implemented in terms of calls to strptime.

Function: char * strptime (const char *s, const char *fmt, struct tm *tp)
The strptime function parses the input string s according to the format string fmt and stores its results in the structure tp.

The input string could be generated by a strftime call or obtained any other way. It does not need to be in a human-recognizable format; e.g. a date passed as "02:1999:9" is acceptable, even though it is ambiguous without context. As long as the format string fmt matches the input string the function will succeed.

The format string consists of the same components as the format string of the strftime function. The only difference is that the flags _, -, 0, and ^ are not allowed. Several of the distinct formats of strftime do the same work in strptime since differences like case of the input do not matter. For reasons of symmetry all formats are supported, though.

The modifiers E and O are also allowed everywhere the strftime function allows them.

The formats are:

%a

%A
The weekday name according to the current locale, in abbreviated form or the full name.
%b

%B

%h
The month name according to the current locale, in abbreviated form or the full name.
%c
The date and time representation for the current locale.
%Ec
Like %c but the locale's alternative date and time format is used.
%C
The century of the year. It makes sense to use this format only if the format string also contains the %y format.
%EC
The locale's representation of the period. Unlike %C it sometimes makes sense to use this format since some cultures represent years relative to the beginning of eras instead of using the Gregorian years.
%d

%e
The day of the month as a decimal number (range 1 through 31). Leading zeroes are permitted but not required.
%Od

%Oe
Same as %d but using the locale's alternative numeric symbols. Leading zeroes are permitted but not required.
%D
Equivalent to %m/%d/%y.
%F
Equivalent to %Y-%m-%d, which is the ISO 8601 date format. This is a GNU extension following an ISO C99 extension to strftime.
%g
The year corresponding to the ISO week number, but without the century (range 00 through 99). Note: Currently, this is not fully implemented. The format is recognized, input is consumed but no field in tm is set. This format is a GNU extension following a GNU extension of strftime.
%G
The year corresponding to the ISO week number. Note: Currently, this is not fully implemented. The format is recognized, input is consumed but no field in tm is set. This format is a GNU extension following a GNU extension of strftime.
%H

%k
The hour as a decimal number, using a 24-hour clock (range 00 through 23). %k is a GNU extension following a GNU extension of strftime.
%OH
Same as %H but using the locale's alternative numeric symbols.
%I

%l
The hour as a decimal number, using a 12-hour clock (range 01 through 12). %l is a GNU extension following a GNU extension of strftime.
%OI
Same as %I but using the locale's alternative numeric symbols.
%j
The day of the year as a decimal number (range 1 through 366). Leading zeroes are permitted but not required.
%m
The month as a decimal number (range 1 through 12). Leading zeroes are permitted but not required.
%Om
Same as %m but using the locale's alternative numeric symbols.
%M
The minute as a decimal number (range 0 through 59). Leading zeroes are permitted but not required.
%OM
Same as %M but using the locale's alternative numeric symbols.
%n

%t
Matches any white space.
%p

%P
The locale-dependent equivalent to `AM' or `PM'. This format is not useful unless %I or %l is also used. Another complication is that the locale might not define these values at all and therefore the conversion fails. %P is a GNU extension following a GNU extension to strftime.
%r
The complete time using the AM/PM format of the current locale. A complication is that the locale might not define this format at all and therefore the conversion fails.
%R
The hour and minute in decimal numbers using the format %H:%M. %R is a GNU extension following a GNU extension to strftime.
%s
The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. Leap seconds are not counted unless leap second support is available. %s is a GNU extension following a GNU extension to strftime.
%S
The seconds as a decimal number (range 0 through 60). Leading zeroes are permitted but not required. Note: The Unix specification says the upper bound on this value is 61, a result of a decision to allow double leap seconds. You will not see the value 61 because no minute has more than one leap second, but the myth persists.
%OS
Same as %S but using the locale's alternative numeric symbols.
%T
Equivalent to the use of %H:%M:%S in this place.
%u
The day of the week as a decimal number (range 1 through 7), Monday being 1. Leading zeroes are permitted but not required. Note: Currently, this is not fully implemented. The format is recognized, input is consumed but no field in tm is set.
%U
The week number of the current year as a decimal number (range 0 through 53). Leading zeroes are permitted but not required.
%OU
Same as %U but using the locale's alternative numeric symbols.
%V
The ISO 8601:1988 week number as a decimal number (range 1 through 53). Leading zeroes are permitted but not required. Note: Currently, this is not fully implemented. The format is recognized, input is consumed but no field in tm is set.
%w
The day of the week as a decimal number (range 0 through 6), Sunday being 0. Leading zeroes are permitted but not required. Note: Currently, this is not fully implemented. The format is recognized, input is consumed but no field in tm is set.
%Ow
Same as %w but using the locale's alternative numeric symbols.
%W
The week number of the current year as a decimal number (range 0 through 53). Leading zeroes are permitted but not required. Note: Currently, this is not fully implemented. The format is recognized, input is consumed but no field in tm is set.
%OW
Same as %W but using the locale's alternative numeric symbols.
%x
The date using the locale's date format.
%Ex
Like %x but the locale's alternative data representation is used.
%X
The time using the locale's time format.
%EX
Like %X but the locale's alternative time representation is used.
%y
The year without a century as a decimal number (range 0 through 99). Leading zeroes are permitted but not required. Note that it is questionable to use this format without the %C format. The strptime function does regard input values in the range @math{68} to @math{99} as the years @math{1969} to @math{1999} and the values @math{0} to @math{68} as the years @math{2000} to @math{2068}. But maybe this heuristic fails for some input data. Therefore it is best to avoid %y completely and use %Y instead.
%Ey
The offset from %EC in the locale's alternative representation.
%Oy
The offset of the year (from %C) using the locale's alternative numeric symbols.
%Y
The year as a decimal number, using the Gregorian calendar.
%EY
The full alternative year representation.
%z
Equivalent to the use of %a, %d %b %Y %H:%M:%S %z in this place. This is the full ISO 8601 date and time format.
%Z
The timezone name. Note: Currently, this is not fully implemented. The format is recognized, input is consumed but no field in tm is set.
%%
A literal `%' character.
All other characters in the format string must have a matching character in the input string. Exceptions are white spaces in the input string which can match zero or more white space characters in the format string.

The strptime function processes the input string from right to left. Each of the three possible input elements (white space, literal, or format) are handled one after the other. If the input cannot be matched to the format string the function stops. The remainder of the format and input strings are not processed.

The function returns a pointer to the first character it was unable to process. If the input string contains more characters than required by the format string the return value points right after the last consumed input character. If the whole input string is consumed the return value points to the NULL byte at the end of the string. If an error occurs, i.e. strptime fails to match all of the format string, the function returns NULL.

The specification of the function in the XPG standard is rather vague, leaving out a few important pieces of information. Most importantly, it does not specify what happens to those elements of tm which are not directly initialized by the different formats. The implementations on different Unix systems vary here.

The GNU libc implementation does not touch those fields which are not directly initialized. Exceptions are the tm_wday and tm_yday elements, which are recomputed if any of the year, month, or date elements changed. This has two implications:

Before calling the strptime function for a new input string, you should prepare the tm structure you pass. Normally this will mean initializing all values are to zero. Alternatively, you can set all fields to values like INT_MAX, allowing you to determine which elements were set by the function call. Zero does not work here since it is a valid value for many of the fields. Careful initialization is necessary if you want to find out whether a certain field in tm was initialized by the function call.
You can construct a struct tm value with several consecutive strptime calls. A useful application of this is e.g. the parsing of two separate strings, one containing date information and the other time information. By parsing one after the other without clearing the structure in-between, you can construct a complete broken-down time.

The following example shows a function which parses a string which is contains the date information in either US style or ISO 8601 form:
const char *
parse_date (const char *input, struct tm *tm)
{
  const char *cp;

  /* First clear the result structure.  */
  memset (tm, '\0', sizeof (*tm));

  /* Try the ISO format first.  */
  cp = strptime (input, "%F", tm);
  if (cp == NULL)
    {
      /* Does not match.  Try the US form.  */
      cp = strptime (input, "%D", tm);
    }

  return cp;
}
A More User-friendly Way to Parse Times and Dates

The Unix standard defines another function for parsing date strings. The interface is weird, but if the function happens to suit your application it is just fine. It is problematic to use this function in multi-threaded programs or libraries, since it returns a pointer to a static variable, and uses a global variable and global state (an environment variable).

Variable: getdate_err
This variable of type int contains the error code of the last unsuccessful call to getdate. Defined values are:

@math{1}
The environment variable DATEMSK is not defined or null.
@math{2}
The template file denoted by the DATEMSK environment variable cannot be opened.
@math{3}
Information about the template file cannot retrieved.
@math{4}
The template file is not a regular file.
@math{5}
An I/O error occurred while reading the template file.
@math{6}
Not enough memory available to execute the function.
@math{7}
The template file contains no matching template.
@math{8}
The input date is invalid, but would match a template otherwise. This includes dates like February 31st, and dates which cannot be represented in a time_t variable.

Function: struct tm * getdate (const char *string)
The interface to getdate is the simplest possible for a function to parse a string and return the value. string is the input string and the result is returned in a statically-allocated variable.

The details about how the string is processed are hidden from the user. In fact, they can be outside the control of the program. Which formats are recognized is controlled by the file named by the environment variable DATEMSK. This file should contain lines of valid format strings which could be passed to strptime.

The getdate function reads these format strings one after the other and tries to match the input string. The first line which completely matches the input string is used.

Elements not initialized through the format string retain the values present at the time of the getdate function call.

The formats recognized by getdate are the same as for strptime. See above for an explanation. There are only a few extensions to the strptime behavior:

If the %Z format is given the broken-down time is based on the current time of the timezone matched, not of the current timezone of the runtime environment. Note: This is not implemented (currently). The problem is that timezone names are not unique. If a fixed timezone is assumed for a given string (say EST meaning US East Coast time), then uses for countries other than the USA will fail. So far we have found no good solution to this.
If only the weekday is specified the selected day depends on the current date. If the current weekday is greater or equal to the tm_wday value the current week's day is chosen, otherwise the day next week is chosen.
A similar heuristic is used when only the month is given and not the year. If the month is greater than or equal to the current month, then the current year is used. Otherwise it wraps to next year. The first day of the month is assumed if one is not explicitly specified.
The current hour, minute, and second are used if the appropriate value is not set through the format.
If no date is given tomorrow's date is used if the time is smaller than the current time. Otherwise today's date is taken.

It should be noted that the format in the template file need not only contain format elements. The following is a list of possible format strings (taken from the Unix standard):
%m
%A %B %d, %Y %H:%M:%S
%A
%B
%m/%d/%y %I %p
%d,%m,%Y %H:%M
at %A the %dst of %B in %Y
run job at %I %p,%B %dnd
%A den %d. %B %Y %H.%M Uhr
As you can see, the template list can contain very specific strings like run job at %I %p,%B %dnd. Using the above list of templates and assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can obtain the following results for the given input.

@multitable {xxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
Input @tab Match @tab Result
Mon @tab %a @tab Mon Sep 22 12:19:47 EDT 1986
Sun @tab %a @tab Sun Sep 28 12:19:47 EDT 1986
Fri @tab %a @tab Fri Sep 26 12:19:47 EDT 1986
September @tab %B @tab Mon Sep 1 12:19:47 EDT 1986
January @tab %B @tab Thu Jan 1 12:19:47 EST 1987
December @tab %B @tab Mon Dec 1 12:19:47 EST 1986
Sep Mon @tab %b %a @tab Mon Sep 1 12:19:47 EDT 1986
Jan Fri @tab %b %a @tab Fri Jan 2 12:19:47 EST 1987
Dec Mon @tab %b %a @tab Mon Dec 1 12:19:47 EST 1986
Jan Wed 1989 @tab %b %a %Y @tab Wed Jan 4 12:19:47 EST 1989
Fri 9 @tab %a %H @tab Fri Sep 26 09:00:00 EDT 1986
Feb 10:30 @tab %b %H:%S @tab Sun Feb 1 10:00:30 EST 1987
10:30 @tab %H:%M @tab Tue Sep 23 10:30:00 EDT 1986
13:30 @tab %H:%M @tab Mon Sep 22 13:30:00 EDT 1986 The return value of the function is a pointer to a static variable of type struct tm, or a null pointer if an error occurred. The result is only valid until the next getdate call, making this function unusable in multi-threaded applications. The errno variable is not changed. Error conditions are stored in the global variable getdate_err. See the description above for a list of the possible error values. Warning: The getdate function should never be used in SUID-programs. The reason is obvious: using the DATEMSK environment variable you can get the function to open any arbitrary file and chances are high that with some bogus input (such as a binary file) the program will crash.
Function: int getdate_r (const char *string, struct tm *tp)
The getdate_r function is the reentrant counterpart of getdate. It does not use the global variable getdate_err to signal an error, but instead returns an error code. The same error codes as described in the getdate_err documentation above are used, with 0 meaning success. Moreover, getdate_r stores the broken-down time in the variable of type struct tm pointed to by the second argument, rather than in a static variable. This function is not defined in the Unix standard. Nevertheless it is available on some other Unix systems as well. The warning against using getdate in SUID-programs applies to getdate_r as well.
Specifying the Time Zone with TZ

In POSIX systems, a user can specify the time zone by means of the TZ environment variable. For information about how to set environment variables, see section Environment Variables. The functions for accessing the time zone are declared in `time.h'.

You should not normally need to set TZ. If the system is configured properly, the default time zone will be correct. You might set TZ if you are using a computer over a network from a different time zone, and would like times reported to you in the time zone local to you, rather than what is local to the computer.

In POSIX.1 systems the value of the TZ variable can be in one of three formats. With the GNU C library, the most common format is the last one, which can specify a selection from a large database of time zone information for many regions of the world. The first two formats are used to describe the time zone information directly, which is both more cumbersome and less precise. But the POSIX.1 standard only specifies the details of the first two formats, so it is good to be familiar with them in case you come across a POSIX.1 system that doesn't support a time zone information database.

The first format is used when there is no Daylight Saving Time (or summer time) in the local time zone:
std offset
The std string specifies the name of the time zone. It must be three or more characters long and must not contain a leading colon, embedded digits, commas, nor plus and minus signs. There is no space character separating the time zone name from the offset, so these restrictions are necessary to parse the specification correctly.

The offset specifies the time value you must add to the local time to get a Coordinated Universal Time value. It has syntax like [+|-]hh[:mm[:ss]]. This is positive if the local time zone is west of the Prime Meridian and negative if it is east. The hour must be between 0 and 23, and the minute and seconds between 0 and 59.

For example, here is how we would specify Eastern Standard Time, but without any Daylight Saving Time alternative:
EST+5
The second format is used when there is Daylight Saving Time:
std offset dst [offset],start[/time],end[/time]
The initial std and offset specify the standard time zone, as described above. The dst string and offset specify the name and offset for the corresponding Daylight Saving Time zone; if the offset is omitted, it defaults to one hour ahead of standard time.

The remainder of the specification describes when Daylight Saving Time is in effect. The start field is when Daylight Saving Time goes into effect and the end field is when the change is made back to standard time. The following formats are recognized for these fields:

Jn
This specifies the Julian day, with n between 1 and 365. February 29 is never counted, even in leap years.
n
This specifies the Julian day, with n between 0 and 365. February 29 is counted in leap years.
Mm.w.d
This specifies day d of week w of month m. The day d must be between 0 (Sunday) and 6. The week w must be between 1 and 5; week 1 is the first week in which day d occurs, and week 5 specifies the last d day in the month. The month m should be between 1 and 12.
The time fields specify when, in the local time currently in effect, the change to the other time occurs. If omitted, the default is 02:00:00.

For example, here is how you would specify the Eastern time zone in the United States, including the appropriate Daylight Saving Time and its dates of applicability. The normal offset from UTC is 5 hours; since this is west of the prime meridian, the sign is positive. Summer time begins on the first Sunday in April at 2:00am, and ends on the last Sunday in October at 2:00am.
EST+5EDT,M4.1.0/2,M10.5.0/2
The schedule of Daylight Saving Time in any particular jurisdiction has changed over the years. To be strictly correct, the conversion of dates and times in the past should be based on the schedule that was in effect then. However, this format has no facilities to let you specify how the schedule has changed from year to year. The most you can do is specify one particular schedule--usually the present day schedule--and this is used to convert any date, no matter when. For precise time zone specifications, it is best to use the time zone information database (see below).

The third format looks like this:
:characters
Each operating system interprets this format differently; in the GNU C library, characters is the name of a file which describes the time zone.

If the TZ environment variable does not have a value, the operation chooses a time zone by default. In the GNU C library, the default time zone is like the specification `TZ=:/etc/localtime' (or `TZ=:/usr/local/etc/localtime', depending on how GNU C library was configured; see section Installing the GNU C Library). Other C libraries use their own rule for choosing the default time zone, so there is little we can say about them.

If characters begins with a slash, it is an absolute file name; otherwise the library looks for the file `/share/lib/zoneinfo/characters'. The `zoneinfo' directory contains data files describing local time zones in many different parts of the world. The names represent major cities, with subdirectories for geographical areas; for example, `America/New_York', `Europe/London', `Asia/Hong_Kong'. These data files are installed by the system administrator, who also sets `/etc/localtime' to point to the data file for the local time zone. The GNU C library comes with a large database of time zone information for most regions of the world, which is maintained by a community of volunteers and put in the public domain.

Functions and Variables for Time Zones

Variable: char * tzname [2]
The array tzname contains two strings, which are the standard names of the pair of time zones (standard and Daylight Saving) that the user has selected. tzname[0] is the name of the standard time zone (for example, "EST"), and tzname[1] is the name for the time zone when Daylight Saving Time is in use (for example, "EDT"). These correspond to the std and dst strings (respectively) from the TZ environment variable. If Daylight Saving Time is never used, tzname[1] is the empty string.

The tzname array is initialized from the TZ environment variable whenever tzset, ctime, strftime, mktime, or localtime is called. If multiple abbreviations have been used (e.g. "EWT" and "EDT" for U.S. Eastern War Time and Eastern Daylight Time), the array contains the most recent abbreviation.

The tzname array is required for POSIX.1 compatibility, but in GNU programs it is better to use the tm_zone member of the broken-down time structure, since tm_zone reports the correct abbreviation even when it is not the latest one.

Though the strings are declared as char * the user must refrain from modifying these strings. Modifying the strings will almost certainly lead to trouble.

Function: void tzset (void)
The tzset function initializes the tzname variable from the value of the TZ environment variable. It is not usually necessary for your program to call this function, because it is called automatically when you use the other time conversion functions that depend on the time zone.

The following variables are defined for compatibility with System V Unix. Like tzname, these variables are set by calling tzset or the other time conversion functions.

Variable: long int timezone
This contains the difference between UTC and the latest local standard time, in seconds west of UTC. For example, in the U.S. Eastern time zone, the value is 5*60*60. Unlike the tm_gmtoff member of the broken-down time structure, this value is not adjusted for daylight saving, and its sign is reversed. In GNU programs it is better to use tm_gmtoff, since it contains the correct offset even when it is not the latest one.

Variable: int daylight
This variable has a nonzero value if Daylight Saving Time rules apply. A nonzero value does not necessarily mean that Daylight Saving Time is now in effect; it means only that Daylight Saving Time is sometimes in effect.

Time Functions Example

Here is an example program showing the use of some of the calendar time functions.
#include <time.h>
#include <stdio.h>

#define SIZE 256

int
main (void)
{
  char buffer[SIZE];
  time_t curtime;
  struct tm *loctime;

  /* Get the current time. */
  curtime = time (NULL);

  /* Convert it to local time representation. */
  loctime = localtime (&curtime);

  /* Print out the date and time in the standard format. */
  fputs (asctime (loctime), stdout);

  /* Print it out in a nice format. */
  strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
  fputs (buffer, stdout);
  strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
  fputs (buffer, stdout);

  return 0;
}
It produces output like this:
Wed Jul 31 13:02:36 1991
Today is Wednesday, July 31.
The time is 01:02 PM.
Setting an Alarm

The alarm and setitimer functions provide a mechanism for a process to interrupt itself in the future. They do this by setting a timer; when the timer expires, the process receives a signal.

Each process has three independent interval timers available:

A real-time timer that counts elapsed time. This timer sends a SIGALRM signal to the process when it expires.
A virtual timer that counts processor time used by the process. This timer sends a SIGVTALRM signal to the process when it expires.
A profiling timer that counts both processor time used by the process, and processor time spent in system calls on behalf of the process. This timer sends a SIGPROF signal to the process when it expires. This timer is useful for profiling in interpreters. The interval timer mechanism does not have the fine granularity necessary for profiling native code.

You can only have one timer of each kind set at any given time. If you set a timer that has not yet expired, that timer is simply reset to the new value.

You should establish a handler for the appropriate alarm signal using signal or sigaction before issuing a call to setitimer or alarm. Otherwise, an unusual chain of events could cause the timer to expire before your program establishes the handler. In this case it would be terminated, since termination is the default action for the alarm signals. See section Signal Handling.

The setitimer function is the primary means for setting an alarm. This facility is declared in the header file `sys/time.h'. The alarm function, declared in `unistd.h', provides a somewhat simpler interface for setting the real-time timer.

Data Type: struct itimerval
This structure is used to specify when a timer should expire. It contains the following members:
struct timeval it_interval
This is the period between successive timer interrupts. If zero, the alarm will only be sent once.
struct timeval it_value
This is the period between now and the first timer interrupt. If zero, the alarm is disabled.
The struct timeval data type is described in section Elapsed Time.

Function: int setitimer (int which, struct itimerval *new, struct itimerval *old)
The setitimer function sets the timer specified by which according to new. The which argument can have a value of ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF.

If old is not a null pointer, setitimer returns information about any previous unexpired timer of the same kind in the structure it points to.

The return value is 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EINVAL
The timer period is too large.

Function: int getitimer (int which, struct itimerval *old)
The getitimer function stores information about the timer specified by which in the structure pointed at by old.

The return value and error conditions are the same as for setitimer.

ITIMER_REAL
This constant can be used as the which argument to the setitimer and getitimer functions to specify the real-time timer.
ITIMER_VIRTUAL
This constant can be used as the which argument to the setitimer and getitimer functions to specify the virtual timer.
ITIMER_PROF
This constant can be used as the which argument to the setitimer and getitimer functions to specify the profiling timer.

Function: unsigned int alarm (unsigned int seconds)
The alarm function sets the real-time timer to expire in seconds seconds. If you want to cancel any existing alarm, you can do this by calling alarm with a seconds argument of zero.

The return value indicates how many seconds remain before the previous alarm would have been sent. If there is no previous alarm, alarm returns zero.

The alarm function could be defined in terms of setitimer like this:
unsigned int
alarm (unsigned int seconds)
{
  struct itimerval old, new;
  new.it_interval.tv_usec = 0;
  new.it_interval.tv_sec = 0;
  new.it_value.tv_usec = 0;
  new.it_value.tv_sec = (long int) seconds;
  if (setitimer (ITIMER_REAL, &new, &old) < 0)
    return 0;
  else
    return old.it_value.tv_sec;
}
There is an example showing the use of the alarm function in section Signal Handlers that Return.

If you simply want your process to wait for a given number of seconds, you should use the sleep function. See section Sleeping.

You shouldn't count on the signal arriving precisely when the timer expires. In a multiprocessing environment there is typically some amount of delay involved.

Portability Note: The setitimer and getitimer functions are derived from BSD Unix, while the alarm function is specified by the POSIX.1 standard. setitimer is more powerful than alarm, but alarm is more widely used.

Sleeping

The function sleep gives a simple way to make the program wait for a short interval. If your program doesn't use signals (except to terminate), then you can expect sleep to wait reliably throughout the specified interval. Otherwise, sleep can return sooner if a signal arrives; if you want to wait for a given interval regardless of signals, use select (see section Waiting for Input or Output) and don't specify any descriptors to wait for.

Function: unsigned int sleep (unsigned int seconds)
The sleep function waits for seconds or until a signal is delivered, whichever happens first.

If sleep function returns because the requested interval is over, it returns a value of zero. If it returns because of delivery of a signal, its return value is the remaining time in the sleep interval.

The sleep function is declared in `unistd.h'.

Resist the temptation to implement a sleep for a fixed amount of time by using the return value of sleep, when nonzero, to call sleep again. This will work with a certain amount of accuracy as long as signals arrive infrequently. But each signal can cause the eventual wakeup time to be off by an additional second or so. Suppose a few signals happen to arrive in rapid succession by bad luck--there is no limit on how much this could shorten or lengthen the wait.

Instead, compute the calendar time at which the program should stop waiting, and keep trying to wait until that calendar time. This won't be off by more than a second. With just a little more work, you can use select and make the waiting period quite accurate. (Of course, heavy system load can cause additional unavoidable delays--unless the machine is dedicated to one application, there is no way you can avoid this.)

On some systems, sleep can do strange things if your program uses SIGALRM explicitly. Even if SIGALRM signals are being ignored or blocked when sleep is called, sleep might return prematurely on delivery of a SIGALRM signal. If you have established a handler for SIGALRM signals and a SIGALRM signal is delivered while the process is sleeping, the action taken might be just to cause sleep to return instead of invoking your handler. And, if sleep is interrupted by delivery of a signal whose handler requests an alarm or alters the handling of SIGALRM, this handler and sleep will interfere.

On the GNU system, it is safe to use sleep and SIGALRM in the same program, because sleep does not work by means of SIGALRM.

Function: int nanosleep (const struct timespec *requested_time, struct timespec *remaining)
If resolution to seconds is not enough the nanosleep function can be used. As the name suggests the sleep interval can be specified in nanoseconds. The actual elapsed time of the sleep interval might be longer since the system rounds the elapsed time you request up to the next integer multiple of the actual resolution the system can deliver.

*requested_time is the elapsed time of the interval you want to sleep.

The function returns as *remaining the elapsed time left in the interval for which you requested to sleep. If the interval completed without getting interrupted by a signal, this is zero.

struct timespec is described in See section Elapsed Time.

If the function returns because the interval is over the return value is zero. If the function returns @math{-1} the global variable errno is set to the following values:

EINTR
The call was interrupted because a signal was delivered to the thread. If the remaining parameter is not the null pointer the structure pointed to by remaining is updated to contain the remaining elapsed time.
EINVAL
The nanosecond value in the requested_time parameter contains an illegal value. Either the value is negative or greater than or equal to 1000 million.
This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time nanosleep is called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls to nanosleep should be protected using cancellation handlers.

The nanosleep function is declared in `time.h'.
Resource Usage And Limitation

This chapter describes functions for examining how much of various kinds of resources (CPU time, memory, etc.) a process has used and getting and setting limits on future usage.

Resource Usage

The function getrusage and the data type struct rusage are used to examine the resource usage of a process. They are declared in `sys/resource.h'.

Function: int getrusage (int processes, struct rusage *rusage)
This function reports resource usage totals for processes specified by processes, storing the information in *rusage.

In most systems, processes has only two valid values:

RUSAGE_SELF
Just the current process.
RUSAGE_CHILDREN
All child processes (direct and indirect) that have already terminated.
In the GNU system, you can also inquire about a particular child process by specifying its process ID.

The return value of getrusage is zero for success, and -1 for failure.

EINVAL
The argument processes is not valid.
One way of getting resource usage for a particular child process is with the function wait4, which returns totals for a child when it terminates. See section BSD Process Wait Functions.

Data Type: struct rusage
This data type stores various resource usage statistics. It has the following members, and possibly others:

struct timeval ru_utime
Time spent executing user instructions.
struct timeval ru_stime
Time spent in operating system code on behalf of processes.
long int ru_maxrss
The maximum resident set size used, in kilobytes. That is, the maximum number of kilobytes of physical memory that processes used simultaneously.
long int ru_ixrss
An integral value expressed in kilobytes times ticks of execution, which indicates the amount of memory used by text that was shared with other processes.
long int ru_idrss
An integral value expressed the same way, which is the amount of unshared memory used for data.
long int ru_isrss
An integral value expressed the same way, which is the amount of unshared memory used for stack space.
long int ru_minflt
The number of page faults which were serviced without requiring any I/O.
long int ru_majflt
The number of page faults which were serviced by doing I/O.
long int ru_nswap
The number of times processes was swapped entirely out of main memory.
long int ru_inblock
The number of times the file system had to read from the disk on behalf of processes.
long int ru_oublock
The number of times the file system had to write to the disk on behalf of processes.
long int ru_msgsnd
Number of IPC messages sent.
long int ru_msgrcv
Number of IPC messages received.
long int ru_nsignals
Number of signals received.
long int ru_nvcsw
The number of times processes voluntarily invoked a context switch (usually to wait for some service).
long int ru_nivcsw
The number of times an involuntary context switch took place (because a time slice expired, or another process of higher priority was scheduled).
vtimes is a historical function that does some of what getrusage does. getrusage is a better choice.

vtimes and its vtimes data structure are declared in `sys/vtimes.h'.

Function: int vtimes (struct vtimes current, struct vtimes child)

vtimes reports resource usage totals for a process.

If current is non-null, vtimes stores resource usage totals for the invoking process alone in the structure to which it points. If child is non-null, vtimes stores resource usage totals for all past children (which have terminated) of the invoking process in the structure to which it points.

Data Type: struct vtimes
This data type contains information about the resource usage of a process. Each member corresponds to a member of the struct rusage data type described above.

vm_utime
User CPU time. Analogous to ru_utime in struct rusage
vm_stime
System CPU time. Analogous to ru_stime in struct rusage
vm_idsrss
Data and stack memory. The sum of the values that would be reported as ru_idrss and ru_isrss in struct rusage
vm_ixrss
Shared memory. Analogous to ru_ixrss in struct rusage
vm_maxrss
Maximent resident set size. Analogous to ru_maxrss in struct rusage
vm_majflt
Major page faults. Analogous to ru_majflt in struct rusage
vm_minflt
Minor page faults. Analogous to ru_minflt in struct rusage
vm_nswap
Swap count. Analogous to ru_nswap in struct rusage
vm_inblk
Disk reads. Analogous to ru_inblk in struct rusage
vm_oublk
Disk writes. Analogous to ru_oublk in struct rusage
The return value is zero if the function succeeds; -1 otherwise.

An additional historical function for examining resource usage, vtimes, is supported but not documented here. It is declared in `sys/vtimes.h'.

Limiting Resource Usage

You can specify limits for the resource usage of a process. When the process tries to exceed a limit, it may get a signal, or the system call by which it tried to do so may fail, depending on the resource. Each process initially inherits its limit values from its parent, but it can subsequently change them.

There are two per-process limits associated with a resource:

current limit
The current limit is the value the system will not allow usage to exceed. It is also called the "soft limit" because the process being limited can generally raise the current limit at will.
maximum limit
The maximum limit is the maximum value to which a process is allowed to set its current limit. It is also called the "hard limit" because there is no way for a process to get around it. A process may lower its own maximum limit, but only the superuser may increase a maximum limit.
The symbols for use with getrlimit, setrlimit, getrlimit64, and seterlimit64 are defined in `sys/resource.h'.

Function: int getrlimit (int resource, struct rlimit *rlp)
Read the current and maximum limits for the resource resource and store them in *rlp.

The return value is 0 on success and -1 on failure. The only possible errno error condition is EFAULT.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact getrlimit64. Thus, the LFS interface transparently replaces the old interface.

Function: int getrlimit64 (int resource, struct rlimit64 *rlp)
This function is similar to getrlimit but its second parameter is a pointer to a variable of type struct rlimit64, which allows it to read values which wouldn't fit in the member of a struct rlimit.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit machine, this function is available under the name getrlimit and so transparently replaces the old interface.

Function: int setrlimit (int resource, const struct rlimit *rlp)
Store the current and maximum limits for the resource resource in *rlp.

The return value is 0 on success and -1 on failure. The following errno error condition is possible:

EPERM

The process tried to raise a current limit beyond the maximum limit.
The process tried to raise a maximum limit, but is not superuser.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact setrlimit64. Thus, the LFS interface transparently replaces the old interface.

Function: int setrlimit64 (int resource, const struct rlimit64 *rlp)
This function is similar to setrlimit but its second parameter is a pointer to a variable of type struct rlimit64 which allows it to set values which wouldn't fit in the member of a struct rlimit.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit machine this function is available under the name setrlimit and so transparently replaces the old interface.

Data Type: struct rlimit
This structure is used with getrlimit to receive limit values, and with setrlimit to specify limit values for a particular process and resource. It has two fields:

rlim_t rlim_cur
The current limit
rlim_t rlim_max
The maximum limit.
For getrlimit, the structure is an output; it receives the current values. For setrlimit, it specifies the new values.

For the LFS functions a similar type is defined in `sys/resource.h'.

Data Type: struct rlimit64
This structure is analogous to the rlimit structure above, but its components have wider ranges. It has two fields:

rlim64_t rlim_cur
This is analogous to rlimit.rlim_cur, but with a different type.
rlim64_t rlim_max
This is analogous to rlimit.rlim_max, but with a different type.
Here is a list of resources for which you can specify a limit. Memory and file sizes are measured in bytes.

RLIMIT_CPU
The maximum amount of CPU time the process can use. If it runs for longer than this, it gets a signal: SIGXCPU. The value is measured in seconds. See section Operation Error Signals.
RLIMIT_FSIZE
The maximum size of file the process can create. Trying to write a larger file causes a signal: SIGXFSZ. See section Operation Error Signals.
RLIMIT_DATA
The maximum size of data memory for the process. If the process tries to allocate data memory beyond this amount, the allocation function fails.
RLIMIT_STACK
The maximum stack size for the process. If the process tries to extend its stack past this size, it gets a SIGSEGV signal. See section Program Error Signals.
RLIMIT_CORE
The maximum size core file that this process can create. If the process terminates and would dump a core file larger than this, then no core file is created. So setting this limit to zero prevents core files from ever being created.
RLIMIT_RSS
The maximum amount of physical memory that this process should get. This parameter is a guide for the system's scheduler and memory allocator; the system may give the process more memory when there is a surplus.
RLIMIT_MEMLOCK
The maximum amount of memory that can be locked into physical memory (so it will never be paged out).
RLIMIT_NPROC
The maximum number of processes that can be created with the same user ID. If you have reached the limit for your user ID, fork will fail with EAGAIN. See section Creating a Process.
RLIMIT_NOFILE

RLIMIT_OFILE
The maximum number of files that the process can open. If it tries to open more files than this, its open attempt fails with errno EMFILE. See section Error Codes. Not all systems support this limit; GNU does, and 4.4 BSD does.
RLIMIT_AS
The maximum size of total memory that this process should get. If the process tries to allocate more memory beyond this amount with, for example, brk, malloc, mmap or sbrk, the allocation function fails.
RLIM_NLIMITS
The number of different resource limits. Any valid resource operand must be less than RLIM_NLIMITS.

Constant: int RLIM_INFINITY
This constant stands for a value of "infinity" when supplied as the limit value in setrlimit.

The following are historical functions to do some of what the functions above do. The functions above are better choices.

ulimit and the command symbols are declared in `ulimit.h'.

Function: int ulimit (int cmd, ...)

ulimit gets the current limit or sets the current and maximum limit for a particular resource for the calling process according to the command cmd.a

If you are getting a limit, the command argument is the only argument. If you are setting a limit, there is a second argument: long int limit which is the value to which you are setting the limit.

The cmd values and the operations they specify are:
GETFSIZE
Get the current limit on the size of a file, in units of 512 bytes.
SETFSIZE
Set the current and maximum limit on the size of a file to limit * 512 bytes.
There are also some other cmd values that may do things on some systems, but they are not supported.

Only the superuser may increase a maximum limit.

When you successfully get a limit, the return value of ulimit is that limit, which is never negative. When you successfully set a limit, the return value is zero. When the function fails, the return value is -1 and errno is set according to the reason:

EPERM
A process tried to increase a maximum limit, but is not superuser.
vlimit and its resource symbols are declared in `sys/vlimit.h'.

Function: int vlimit (int resource, int limit)

vlimit sets the current limit for a resource for a process.

resource identifies the resource:

LIM_CPU
Maximum CPU time. Same as RLIMIT_CPU for setrlimit.
LIM_FSIZE
Maximum file size. Same as RLIMIT_FSIZE for setrlimit.
LIM_DATA
Maximum data memory. Same as RLIMIT_DATA for setrlimit.
LIM_STACK
Maximum stack size. Same as RLIMIT_STACK for setrlimit.
LIM_CORE
Maximum core file size. Same as RLIMIT_COR for setrlimit.
LIM_MAXRSS
Maximum physical memory. Same as RLIMIT_RSS for setrlimit.
The return value is zero for success, and -1 with errno set accordingly for failure:

EPERM
The process tried to set its current limit beyond its maximum limit.
Process CPU Priority And Scheduling

When multiple processes simultaneously require CPU time, the system's scheduling policy and process CPU priorities determine which processes get it. This section describes how that determination is made and GNU C library functions to control it.

It is common to refer to CPU scheduling simply as scheduling and a process' CPU priority simply as the process' priority, with the CPU resource being implied. Bear in mind, though, that CPU time is not the only resource a process uses or that processes contend for. In some cases, it is not even particularly important. Giving a process a high "priority" may have very little effect on how fast a process runs with respect to other processes. The priorities discussed in this section apply only to CPU time.

CPU scheduling is a complex issue and different systems do it in wildly different ways. New ideas continually develop and find their way into the intricacies of the various systems' scheduling algorithms. This section discusses the general concepts, some specifics of systems that commonly use the GNU C library, and some standards.

For simplicity, we talk about CPU contention as if there is only one CPU in the system. But all the same principles apply when a processor has multiple CPUs, and knowing that the number of processes that can run at any one time is equal to the number of CPUs, you can easily extrapolate the information.

The functions described in this section are all defined by the POSIX.1 and POSIX.1b standards (the sched... functions are POSIX.1b). However, POSIX does not define any semantics for the values that these functions get and set. In this chapter, the semantics are based on the Linux kernel's implementation of the POSIX standard. As you will see, the Linux implementation is quite the inverse of what the authors of the POSIX syntax had in mind.

Absolute Priority

Every process has an absolute priority, and it is represented by a number. The higher the number, the higher the absolute priority.

On systems of the past, and most systems today, all processes have absolute priority 0 and this section is irrelevant. In that case, See section Traditional Scheduling. Absolute priorities were invented to accomodate realtime systems, in which it is vital that certain processes be able to respond to external events happening in real time, which means they cannot wait around while some other process that wants to, but doesn't need to run occupies the CPU.

When two processes are in contention to use the CPU at any instant, the one with the higher absolute priority always gets it. This is true even if the process with the lower priority is already using the CPU (i.e. the scheduling is preemptive). Of course, we're only talking about processes that are running or "ready to run," which means they are ready to execute instructions right now. When a process blocks to wait for something like I/O, its absolute priority is irrelevant.

Note: The term "runnable" is a synonym for "ready to run."

When two processes are running or ready to run and both have the same absolute priority, it's more interesting. In that case, who gets the CPU is determined by the scheduling policy. If the processeses have absolute priority 0, the traditional scheduling policy described in section Traditional Scheduling applies. Otherwise, the policies described in section Realtime Scheduling apply.

You normally give an absolute priority above 0 only to a process that can be trusted not to hog the CPU. Such processes are designed to block (or terminate) after relatively short CPU runs.

A process begins life with the same absolute priority as its parent process. Functions described in section Basic Scheduling Functions can change it.

Only a privileged process can change a process' absolute priority to something other than 0. Only a privileged process or the target process' owner can change its absolute priority at all.

POSIX requires absolute priority values used with the realtime scheduling policies to be consecutive with a range of at least 32. On Linux, they are 1 through 99. The functions sched_get_priority_max and sched_set_priority_min portably tell you what the range is on a particular system.

Using Absolute Priority

One thing you must keep in mind when designing real time applications is that having higher absolute priority than any other process doesn't guarantee the process can run continuously. Two things that can wreck a good CPU run are interrupts and page faults.

Interrupt handlers live in that limbo between processes. The CPU is executing instructions, but they aren't part of any process. An interrupt will stop even the highest priority process. So you must allow for slight delays and make sure that no device in the system has an interrupt handler that could cause too long a delay between instructions for your process.

Similarly, a page fault causes what looks like a straightforward sequence of instructions to take a long time. The fact that other processes get to run while the page faults in is of no consequence, because as soon as the I/O is complete, the high priority process will kick them out and run again, but the wait for the I/O itself could be a problem. To neutralize this threat, use mlock or mlockall.

There are a few ramifications of the absoluteness of this priority on a single-CPU system that you need to keep in mind when you choose to set a priority and also when you're working on a program that runs with high absolute priority. Consider a process that has higher absolute priority than any other process in the system and due to a bug in its program, it gets into an infinite loop. It will never cede the CPU. You can't run a command to kill it because your command would need to get the CPU in order to run. The errant program is in complete control. It controls the vertical, it controls the horizontal.

There are two ways to avoid this: 1) keep a shell running somewhere with a higher absolute priority. 2) keep a controlling terminal attached to the high priority process group. All the priority in the world won't stop an interrupt handler from running and delivering a signal to the process if you hit Control-C.

Some systems use absolute priority as a means of allocating a fixed per centage of CPU time to a process. To do this, a super high priority privileged process constantly monitors the process' CPU usage and raises its absolute priority when the process isn't getting its entitled share and lowers it when the process is exceeding it.

Note: The absolute priority is sometimes called the "static priority." We don't use that term in this manual because it misses the most important feature of the absolute priority: its absoluteness.

Realtime Scheduling

Whenever two processes with the same absolute priority are ready to run, the kernel has a decision to make, because only one can run at a time. If the processes have absolute priority 0, the kernel makes this decision as described in section Traditional Scheduling. Otherwise, the decision is as described in this section.

If two processes are ready to run but have different absolute priorities, the decision is much simpler, and is described in section Absolute Priority.

Each process has a scheduling policy. For processes with absolute priority other than zero, there are two available:

First Come First Served
Round Robin

The most sensible case is where all the processes with a certain absolute priority have the same scheduling policy. We'll discuss that first.

In Round Robin, processes share the CPU, each one running for a small quantum of time ("time slice") and then yielding to another in a circular fashion. Of course, only processes that are ready to run and have the same absolute priority are in this circle.

In First Come First Served, the process that has been waiting the longest to run gets the CPU, and it keeps it until it voluntarily relinquishes the CPU, runs out of things to do (blocks), or gets preempted by a higher priority process.

First Come First Served, along with maximal absolute priority and careful control of interrupts and page faults, is the one to use when a process absolutely, positively has to run at full CPU speed or not at all.

Judicious use of sched_yield function invocations by processes with First Come First Served scheduling policy forms a good compromise between Round Robin and First Come First Served.

To understand how scheduling works when processes of different scheduling policies occupy the same absolute priority, you have to know the nitty gritty details of how processes enter and exit the ready to run list:

In both cases, the ready to run list is organized as a true queue, where a process gets pushed onto the tail when it becomes ready to run and is popped off the head when the scheduler decides to run it. Note that ready to run and running are two mutually exclusive states. When the scheduler runs a process, that process is no longer ready to run and no longer in the ready to run list. When the process stops running, it may go back to being ready to run again.

The only difference between a process that is assigned the Round Robin scheduling policy and a process that is assigned First Come First Serve is that in the former case, the process is automatically booted off the CPU after a certain amount of time. When that happens, the process goes back to being ready to run, which means it enters the queue at the tail. The time quantum we're talking about is small. Really small. This is not your father's timesharing. For example, with the Linux kernel, the round robin time slice is a thousand times shorter than its typical time slice for traditional scheduling.

A process begins life with the same scheduling policy as its parent process. Functions described in section Basic Scheduling Functions can change it.

Only a privileged process can set the scheduling policy of a process that has absolute priority higher than 0.

Basic Scheduling Functions

This section describes functions in the GNU C library for setting the absolute priority and scheduling policy of a process.

Portability Note: On systems that have the functions in this section, the macro _POSIX_PRIORITY_SCHEDULING is defined in `<unistd.h>'.

For the case that the scheduling policy is traditional scheduling, more functions to fine tune the scheduling are in section Traditional Scheduling.

Don't try to make too much out of the naming and structure of these functions. They don't match the concepts described in this manual because the functions are as defined by POSIX.1b, but the implementation on systems that use the GNU C library is the inverse of what the POSIX structure contemplates. The POSIX scheme assumes that the primary scheduling parameter is the scheduling policy and that the priority value, if any, is a parameter of the scheduling policy. In the implementation, though, the priority value is king and the scheduling policy, if anything, only fine tunes the effect of that priority.

The symbols in this section are declared by including file `sched.h'.

Data Type: struct sched_param
This structure describes an absolute priority.
int sched_priority
absolute priority value

Function: int sched_setscheduler (pid_t pid, int policy, const struct sched_param *param)

This function sets both the absolute priority and the scheduling policy for a process.

It assigns the absolute priority value given by param and the scheduling policy policy to the process with Process ID pid, or the calling process if pid is zero. If policy is negative, sched_setschedule keeps the existing scheduling policy.

The following macros represent the valid values for policy:

SCHED_OTHER
Traditional Scheduling
SCHED_FIFO
First In First Out
SCHED_RR
Round Robin
On success, the return value is 0. Otherwise, it is -1 and ERRNO is set accordingly. The errno values specific to this function are:

EPERM

The calling process does not have CAP_SYS_NICE permission and policy is not SCHED_OTHER (or it's negative and the existing policy is not SCHED_OTHER.
The calling process does not have CAP_SYS_NICE permission and its owner is not the target process' owner. I.e. the effective uid of the calling process is neither the effective nor the real uid of process pid.

ESRCH
There is no process with pid pid and pid is not zero.
EINVAL

policy does not identify an existing scheduling policy.
The absolute priority value identified by *param is outside the valid range for the scheduling policy policy (or the existing scheduling policy if policy is negative) or param is null. sched_get_priority_max and sched_get_priority_min tell you what the valid range is.
pid is negative.

Function: int sched_getscheduler (pid_t pid)

This function returns the scheduling policy assigned to the process with Process ID (pid) pid, or the calling process if pid is zero.

The return value is the scheduling policy. See sched_setscheduler for the possible values.

If the function fails, the return value is instead -1 and errno is set accordingly.

The errno values specific to this function are:

ESRCH
There is no process with pid pid and it is not zero.
EINVAL
pid is negative.
Note that this function is not an exact mate to sched_setscheduler because while that function sets the scheduling policy and the absolute priority, this function gets only the scheduling policy. To get the absolute priority, use sched_getparam.

Function: int sched_setparam (pid_t pid, const struct sched_param *param)

This function sets a process' absolute priority.

It is functionally identical to sched_setscheduler with policy = -1.

Function: int sched_getparam (pid_t pid, const struct sched_param *param)

This function returns a process' absolute priority.

pid is the Process ID (pid) of the process whose absolute priority you want to know.

param is a pointer to a structure in which the function stores the absolute priority of the process.

On success, the return value is 0. Otherwise, it is -1 and ERRNO is set accordingly. The errno values specific to this function are:

ESRCH
There is no process with pid pid and it is not zero.
EINVAL
pid is negative.

Function: int sched_get_priority_min (int *policy);

This function returns the lowest absolute priority value that is allowable for a process with scheduling policy policy.

On Linux, it is 0 for SCHED_OTHER and 1 for everything else.

On success, the return value is 0. Otherwise, it is -1 and ERRNO is set accordingly. The errno values specific to this function are:

EINVAL
policy does not identify an existing scheduling policy.

Function: int sched_get_priority_max (int *policy);

This function returns the highest absolute priority value that is allowable for a process that with scheduling policy policy.

On Linux, it is 0 for SCHED_OTHER and 99 for everything else.

On success, the return value is 0. Otherwise, it is -1 and ERRNO is set accordingly. The errno values specific to this function are:

EINVAL
policy does not identify an existing scheduling policy.

Function: int sched_rr_get_interval (pid_t pid, struct timespec *interval)

This function returns the length of the quantum (time slice) used with the Round Robin scheduling policy, if it is used, for the process with Process ID pid.

It returns the length of time as interval.

With a Linux kernel, the round robin time slice is always 150 microseconds, and pid need not even be a real pid.

The return value is 0 on success and in the pathological case that it fails, the return value is -1 and errno is set accordingly. There is nothing specific that can go wrong with this function, so there are no specific errno values.

Function: int sched_yield (void)

This function voluntarily gives up the process' claim on the CPU.

Technically, sched_yield causes the calling process to be made immediately ready to run (as opposed to running, which is what it was before). This means that if it has absolute priority higher than 0, it gets pushed onto the tail of the queue of processes that share its absolute priority and are ready to run, and it will run again when its turn next arrives. If its absolute priority is 0, it is more complicated, but still has the effect of yielding the CPU to other processes.

If there are no other processes that share the calling process' absolute priority, this function doesn't have any effect.

To the extent that the containing program is oblivious to what other processes in the system are doing and how fast it executes, this function appears as a no-op.

The return value is 0 on success and in the pathological case that it fails, the return value is -1 and errno is set accordingly. There is nothing specific that can go wrong with this function, so there are no specific errno values.

Traditional Scheduling

This section is about the scheduling among processes whose absolute priority is 0. When the system hands out the scraps of CPU time that are left over after the processes with higher absolulte priority have taken all they want, the scheduling described herein determines who among the great unwashed processes gets them.

Introduction To Traditional Scheduling

Long before there was absolute priority (See section Absolute Priority), Unix systems were scheduling the CPU using this system. When Posix came in like the Romans and imposed absolute priorities to accomodate the needs of realtime processing, it left the indigenous Absolute Priority Zero processes to govern themselves by their own familiar scheduling policy.

Indeed, absolute priorities higher than zero are not available on many systems today and are not typically used when they are, being intended mainly for computers that do realtime processing. So this section describes the only scheduling many programmers need to be concerned about.

But just to be clear about the scope of this scheduling: Any time a process with a absolute priority of 0 and a process with an absolute priority higher than 0 are ready to run at the same time, the one with absolute priority 0 does not run. If it's already running when the higher priority ready-to-run process comes into existence, it stops immediately.

In addition to its absolute priority of zero, every process has another priority, which we will refer to as "dynamic priority" because it changes over time. The dynamic priority is meaningless for processes with an absolute priority higher than zero.

The dynamic priority sometimes determines who gets the next turn on the CPU. Sometimes it determines how long turns last. Sometimes it determines whether a process can kick another off the CPU.

In Linux, the value is a combination of these things, but mostly it is just determines the length of the time slice. The higher a process' dynamic priority, the longer a shot it gets on the CPU when it gets one. If it doesn't use up its time slice before giving up the CPU to do something like wait for I/O, it is favored for getting the CPU back when it's ready for it, to finish out its time slice. Other than that, selection of processes for new time slices is basically round robin. But the scheduler does throw a bone to the low priority processes: A process' dynamic priority rises every time it is snubbed in the scheduling process. In Linux, even the fat kid gets to play.

The fluctuation of a process' dynamic priority is regulated by another value: The "nice" value. The nice value is an integer, usually in the range -20 to 20, and represents an upper limit on a process' dynamic priority. The higher the nice number, the lower that limit.

On a typical Linux system, for example, a process with a nice value of 20 can get only 10 milliseconds on the CPU at a time, whereas a process with a nice value of -20 can achieve a high enough priority to get 400 milliseconds.

The idea of the nice value is deferential courtesy. In the beginning, in the Unix garden of Eden, all processes shared equally in the bounty of the computer system. But not all processes really need the same share of CPU time, so the nice value gave a courteous process the ability to refuse its equal share of CPU time that others might prosper. Hence, the higher a process' nice value, the nicer the process is. (Then a snake came along and offered some process a negative nice value and the system became the crass resource allocation system we know today).

Dynamic priorities tend upward and downward with an objective of smoothing out allocation of CPU time and giving quick response time to infrequent requests. But they never exceed their nice limits, so on a heavily loaded CPU, the nice value effectively determines how fast a process runs.

In keeping with the socialistic heritage of Unix process priority, a process begins life with the same nice value as its parent process and can raise it at will. A process can also raise the nice value of any other process owned by the same user (or effective user). But only a privileged process can lower its nice value. A privileged process can also raise or lower another process' nice value.

GNU C Library functions for getting and setting nice values are described in See section Functions For Traditional Scheduling.

Functions For Traditional Scheduling

This section describes how you can read and set the nice value of a process. All these symbols are declared in `sys/resource.h'.

The function and macro names are defined by POSIX, and refer to "priority," but the functions actually have to do with nice values, as the terms are used both in the manual and POSIX.

The range of valid nice values depends on the kernel, but typically it runs from -20 to 20. A lower nice value corresponds to higher priority for the process. These constants describe the range of priority values:

PRIO_MIN
The lowest valid nice value.
PRIO_MAX
The highest valid nice value.

Function: int getpriority (int class, int id)
Return the nice value of a set of processes; class and id specify which ones (see below). If the processes specified do not all have the same nice value, this returns the lowest value that any of them has.

On success, the return value is 0. Otherwise, it is -1 and ERRNO is set accordingly. The errno values specific to this function are:

ESRCH
The combination of class and id does not match any existing process.
EINVAL
The value of class is not valid.
If the return value is -1, it could indicate failure, or it could be the nice value. The only way to make certain is to set errno = 0 before calling getpriority, then use errno != 0 afterward as the criterion for failure.

Function: int setpriority (int class, int id, int niceval)
Set the nice value of a set of processes to niceval; class and id specify which ones (see below).

The return value is the nice value on success, and -1 on failure. The following errno error condition are possible for this function:

ESRCH
The combination of class and id does not match any existing process.
EINVAL
The value of class is not valid.
EPERM
The call would set the nice value of a process which is owned by a different user than the calling process (i.e. the target process' real or effective uid does not match the calling process' effective uid) and the calling process does not have CAP_SYS_NICE permission.
EACCES
The call would lower the process' nice value and the process does not have CAP_SYS_NICE permission.
The arguments class and id together specify a set of processes in which you are interested. These are the possible values of class:

PRIO_PROCESS
One particular process. The argument id is a process ID (pid).
PRIO_PGRP
All the processes in a particular process group. The argument id is a process group ID (pgid).
PRIO_USER
All the processes owned by a particular user (i.e. whose real uid indicates the user). The argument id is a user ID (uid).
If the argument id is 0, it stands for the calling process, its process group, or its owner (real uid), according to class.

Function: int nice (int increment)
Increment the nice value of the calling process by increment. The return value is the same as for setpriority.

Here is an equivalent definition of nice:
int
nice (int increment)
{
  int old = getpriority (PRIO_PROCESS, 0);
  return setpriority (PRIO_PROCESS, 0, old + increment);
}
Querying memory available resources

The amount of memory available in the system and the way it is organized determines oftentimes the way programs can and have to work. For functions like mmap it is necessary to know about the size of individual memory pages and knowing how much memory is available enables a program to select appropriate sizes for, say, caches. Before we get into these details a few words about memory subsystems in traditional Unix systems will be given.

Overview about traditional Unix memory handling

Unix systems normally provide processes virtual address spaces. This means that the addresses of the memory regions do not have to correspond directly to the addresses of the actual physical memory which stores the data. An extra level of indirection is introduced which translates virtual addresses into physical addresses. This is normally done by the hardware of the processor.

Using a virtual address space has several advantage. The most important is process isolation. The different processes running on the system cannot interfere directly with each other. No process can write into the address space of another process (except when shared memory is used but then it is wanted and controlled).

Another advantage of virtual memory is that the address space the processes see can actually be larger than the physical memory available. The physical memory can be extended by storage on an external media where the content of currently unused memory regions is stored. The address translation can then intercept accesses to these memory regions and make memory content available again by loading the data back into memory. This concept makes it necessary that programs which have to use lots of memory know the difference between available virtual address space and available physical memory. If the working set of virtual memory of all the processes is larger than the available physical memory the system will slow down dramatically due to constant swapping of memory content from the memory to the storage media and back. This is called "thrashing".

A final aspect of virtual memory which is important and follows from what is said in the last paragraph is the granularity of the virtual address space handling. When we said that the virtual address handling stores memory content externally it cannot do this on a byte-by-byte basis. The administrative overhead does not allow this (leaving alone the processor hardware). Instead several thousand bytes are handled together and form a page. The size of each page is always a power of two byte. The smallest page size in use today is 4096, with 8192, 16384, and 65536 being other popular sizes.

How to get information about the memory subsystem?

The page size of the virtual memory the process sees is essential to know in several situations. Some programming interface (e.g., mmap, see section Memory-mapped I/O) require the user to provide information adjusted to the page size. In the case of mmap is it necessary to provide a length argument which is a multiple of the page size. Another place where the knowledge about the page size is useful is in memory allocation. If one allocates pieces of memory in larger chunks which are then subdivided by the application code it is useful to adjust the size of the larger blocks to the page size. If the total memory requirement for the block is close (but not larger) to a multiple of the page size the kernel's memory handling can work more effectively since it only has to allocate memory pages which are fully used. (To do this optimization it is necessary to know a bit about the memory allocator which will require a bit of memory itself for each block and this overhead must not push the total size over the page size multiple.

The page size traditionally was a compile time constant. But recent development of processors changed this. Processors now support different page sizes and they can possibly even vary among different processes on the same system. Therefore the system should be queried at runtime about the current page size and no assumptions (except about it being a power of two) should be made.

The correct interface to query about the page size is sysconf (see section Definition of sysconf) with the parameter _SC_PAGESIZE. There is a much older interface available, too.

Function: int getpagesize (void)
The getpagesize function returns the page size of the process. This value is fixed for the runtime of the process but can vary in different runs of the application.

The function is declared in `unistd.h'.

Widely available on System V derived systems is a method to get information about the physical memory the system has. The call
  sysconf (_SC_PHYS_PAGES)
returns the total number of pages of physical the system has. This does not mean all this memory is available. This information can be found using
  sysconf (_SC_AVPHYS_PAGES)
These two values help to optimize applications. The value returned for _SC_AVPHYS_PAGES is the amount of memory the application can use without hindering any other process (given that no other process increases its memory usage). The value returned for _SC_PHYS_PAGES is more or less a hard limit for the working set. If all applications together constantly use more than that amount of memory the system is in trouble.

The GNU C library provides in addition to these already described way to get this information two functions. They are declared in the file `sys/sysinfo.h'. Programmers should prefer to use the sysconf method described above.

Function: long int get_phys_pages (void)
The get_phys_pages function returns the total number of pages of physical the system has. To get the amount of memory this number has to be multiplied by the page size.

This function is a GNU extension.

Function: long int get_avphys_pages (void)
The get_phys_pages function returns the number of available pages of physical the system has. To get the amount of memory this number has to be multiplied by the page size.

This function is a GNU extension.

Learn about the processors available

The use of threads or processes with shared memory allows an application to take advantage of all the processing power a system can provide. If the task can be parallelized the optimal way to write an application is to have at any time as many processes running as there are processors. To determine the number of processors available to the system one can run
  sysconf (_SC_NPROCESSORS_CONF)
which returns the number of processors the operating system configured. But it might be possible for the operating system to disable individual processors and so the call
  sysconf (_SC_NPROCESSORS_ONLN)
returns the number of processors which are currently inline (i.e., available).

For these two pieces of information the GNU C library also provides functions to get the information directly. The functions are declared in `sys/sysinfo.h'.

Function: int get_nprocs_conf (void)
The get_nprocs_conf function returns the number of processors the operating system configured.

This function is a GNU extension.

Function: int get_nprocs (void)
The get_nprocs function returns the number of available processors.

This function is a GNU extension.

Before starting more threads it should be checked whether the processors are not already overused. Unix systems calculate something called the load average. This is a number indicating how many processes were running. This number is average over different periods of times (normally 1, 5, and 15 minutes).

Function: int getloadavg (double loadavg[], int nelem)
This function gets the 1, 5 and 15 minute load averages of the system. The values are placed in loadavg. getloadavg will place at most nelem elements into the array but never more than three elements. The return value is the number of elements written to loadavg, or -1 on error.

This function is declared in `stdlib.h'.
Non-Local Exits

Sometimes when your program detects an unusual situation inside a deeply nested set of function calls, you would like to be able to immediately return to an outer level of control. This section describes how you can do such non-local exits using the setjmp and longjmp functions.

Introduction to Non-Local Exits

As an example of a situation where a non-local exit can be useful, suppose you have an interactive program that has a "main loop" that prompts for and executes commands. Suppose the "read" command reads input from a file, doing some lexical analysis and parsing of the input while processing it. If a low-level input error is detected, it would be useful to be able to return immediately to the "main loop" instead of having to make each of the lexical analysis, parsing, and processing phases all have to explicitly deal with error situations initially detected by nested calls.

(On the other hand, if each of these phases has to do a substantial amount of cleanup when it exits--such as closing files, deallocating buffers or other data structures, and the like--then it can be more appropriate to do a normal return and have each phase do its own cleanup, because a non-local exit would bypass the intervening phases and their associated cleanup code entirely. Alternatively, you could use a non-local exit but do the cleanup explicitly either before or after returning to the "main loop".)

In some ways, a non-local exit is similar to using the `return' statement to return from a function. But while `return' abandons only a single function call, transferring control back to the point at which it was called, a non-local exit can potentially abandon many levels of nested function calls.

You identify return points for non-local exits by calling the function setjmp. This function saves information about the execution environment in which the call to setjmp appears in an object of type jmp_buf. Execution of the program continues normally after the call to setjmp, but if an exit is later made to this return point by calling longjmp with the corresponding jmp_buf object, control is transferred back to the point where setjmp was called. The return value from setjmp is used to distinguish between an ordinary return and a return made by a call to longjmp, so calls to setjmp usually appear in an `if' statement.

Here is how the example program described above might be set up:
#include <setjmp.h>
#include <stdlib.h>
#include <stdio.h>

jmp_buf main_loop;

void
abort_to_main_loop (int status)
{
  longjmp (main_loop, status);
}

int
main (void)
{
  while (1)
    if (setjmp (main_loop))
      puts ("Back at main loop....");
    else
      do_command ();
}

void
do_command (void)
{
  char buffer[128];
  if (fgets (buffer, 128, stdin) == NULL)
    abort_to_main_loop (-1);
  else
    exit (EXIT_SUCCESS);
}
The function abort_to_main_loop causes an immediate transfer of control back to the main loop of the program, no matter where it is called from.

The flow of control inside the main function may appear a little mysterious at first, but it is actually a common idiom with setjmp. A normal call to setjmp returns zero, so the "else" clause of the conditional is executed. If abort_to_main_loop is called somewhere within the execution of do_command, then it actually appears as if the same call to setjmp in main were returning a second time with a value of -1.

So, the general pattern for using setjmp looks something like:
if (setjmp (buffer))
  /* Code to clean up after premature return. */
  ...
else
  /* Code to be executed normally after setting up the return point. */
  ...
Details of Non-Local Exits

Here are the details on the functions and data structures used for performing non-local exits. These facilities are declared in `setjmp.h'.

Data Type: jmp_buf
Objects of type jmp_buf hold the state information to be restored by a non-local exit. The contents of a jmp_buf identify a specific place to return to.

Macro: int setjmp (jmp_buf state)
When called normally, setjmp stores information about the execution state of the program in state and returns zero. If longjmp is later used to perform a non-local exit to this state, setjmp returns a nonzero value.

Function: void longjmp (jmp_buf state, int value)
This function restores current execution to the state saved in state, and continues execution from the call to setjmp that established that return point. Returning from setjmp by means of longjmp returns the value argument that was passed to longjmp, rather than 0. (But if value is given as 0, setjmp returns 1).

There are a lot of obscure but important restrictions on the use of setjmp and longjmp. Most of these restrictions are present because non-local exits require a fair amount of magic on the part of the C compiler and can interact with other parts of the language in strange ways.

The setjmp function is actually a macro without an actual function definition, so you shouldn't try to `#undef' it or take its address. In addition, calls to setjmp are safe in only the following contexts:

As the test expression of a selection or iteration statement (such as `if', `switch', or `while').
As one operand of a equality or comparison operator that appears as the test expression of a selection or iteration statement. The other operand must be an integer constant expression.
As the operand of a unary `!' operator, that appears as the test expression of a selection or iteration statement.
By itself as an expression statement.

Return points are valid only during the dynamic extent of the function that called setjmp to establish them. If you longjmp to a return point that was established in a function that has already returned, unpredictable and disastrous things are likely to happen.

You should use a nonzero value argument to longjmp. While longjmp refuses to pass back a zero argument as the return value from setjmp, this is intended as a safety net against accidental misuse and is not really good programming style.

When you perform a non-local exit, accessible objects generally retain whatever values they had at the time longjmp was called. The exception is that the values of automatic variables local to the function containing the setjmp call that have been changed since the call to setjmp are indeterminate, unless you have declared them volatile.

Non-Local Exits and Signals

In BSD Unix systems, setjmp and longjmp also save and restore the set of blocked signals; see section Blocking Signals. However, the POSIX.1 standard requires setjmp and longjmp not to change the set of blocked signals, and provides an additional pair of functions (sigsetjmp and siglongjmp) to get the BSD behavior.

The behavior of setjmp and longjmp in the GNU library is controlled by feature test macros; see section Feature Test Macros. The default in the GNU system is the POSIX.1 behavior rather than the BSD behavior.

The facilities in this section are declared in the header file `setjmp.h'.

Data Type: sigjmp_buf
This is similar to jmp_buf, except that it can also store state information about the set of blocked signals.

Function: int sigsetjmp (sigjmp_buf state, int savesigs)
This is similar to setjmp. If savesigs is nonzero, the set of blocked signals is saved in state and will be restored if a siglongjmp is later performed with this state.

Function: void siglongjmp (sigjmp_buf state, int value)
This is similar to longjmp except for the type of its state argument. If the sigsetjmp call that set this state used a nonzero savesigs flag, siglongjmp also restores the set of blocked signals.

Complete Context Control

The Unix standard one more set of function to control the execution path and these functions are more powerful than those discussed in this chapter so far. These function were part of the original System V API and by this route were added to the Unix API. Beside on branded Unix implementations these interfaces are not widely available. Not all platforms and/or architectures the GNU C Library is available on provide this interface. Use `configure' to detect the availability.

Similar to the jmp_buf and sigjmp_buf types used for the variables to contain the state of the longjmp functions the interfaces of interest here have an appropriate type as well. Objects of this type are normally much larger since more information is contained. The type is also used in a few more places as we will see. The types and functions described in this section are all defined and declared respectively in the `ucontext.h' header file.

Data Type: ucontext_t

The ucontext_t type is defined as a structure with as least the following elements:

ucontext_t *uc_link
This is a pointer to the next context structure which is used if the context described in the current structure returns.
sigset_t uc_sigmask
Set of signals which are blocked when this context is used.
stack_t uc_stack
Stack used for this context. The value need not be (and normally is not) the stack pointer. See section Using a Separate Signal Stack.
mcontext_t uc_mcontext
This element contains the actual state of the process. The mcontext_t type is also defined in this header but the definition should be treated as opaque. Any use of knowledge of the type makes applications less portable.
Objects of this type have to be created by the user. The initialization and modification happens through one of the following functions:

Function: int getcontext (ucontext_t *ucp)
The getcontext function initializes the variable pointed to by ucp with the context of the calling thread. The context contains the content of the registers, the signal mask, and the current stack. Executing the contents would start at the point where the getcontext call just returned.

The function returns 0 if succesful. Otherwise it returns -1 and sets errno accordingly.

The getcontext function is similar to setjmp but it does not provide an indication of whether the function returns for the first time or whether the initialized context was used and the execution is resumed at just that point. If this is necessary the user has to take determine this herself. This must be done carefully since the context contains registers which might contain register variables. This is a good situation to define variables with volatile.

Once the context variable is initialized it can be used as is or it can be modified. The latter is normally done to implement co-routines or similar constructs. The makecontext function is what has to be used to do that.

Function: void makecontext (ucontext_t *ucp, void (*func) (void), int argc, ...)

The ucp parameter passed to the makecontext shall be initialized by a call to getcontext. The context will be modified to in a way so that if the context is resumed it will start by calling the function func which gets argc integer arguments passed. The integer arguments which are to be passed should follow the argc parameter in the call to makecontext.

Before the call to this function the uc_stack and uc_link element of the ucp structure should be initialized. The uc_stack element describes the stack which is used for this context. No two contexts which are used at the same time should use the same memory region for a stack.

The uc_link element of the object pointed to by ucp should be a pointer to the context to be executed when the function func returns or it should be a null pointer. See setcontext for more information about the exact use.

While allocating the memory for the stack one has to be careful. Most modern processors keep track of whether a certain memory region is allowed to contain code which is executed or not. Data segments and heap memory is normally not tagged to allow this. The result is that programs would fail. Examples for such code include the calling sequences the GNU C compiler generates for calls to nested functions. Safe ways to allocate stacks correctly include using memory on the original threads stack or explicitly allocate memory tagged for execution using (see section Memory-mapped I/O).

Compatibility note: The current Unix standard is very imprecise about the way the stack is allocated. All implementations seem to agree that the uc_stack element must be used but the values stored in the elements of the stack_t value are unclear. The GNU C library and most other Unix implementations require the ss_sp value of the uc_stack element to point to the base of the memory region allocated for the stack and the size of the memory region is stored in ss_size. There are implements out there which require ss_sp to be set to the value the stack pointer will have (which can depending on the direction the stack grows be different). This difference makes the makecontext function hard to use and it requires detection of the platform at compile time.

Function: int setcontext (const ucontext_t *ucp)

The setcontext function restores the context described by ucp. The context is not modified and can be reused as often as wanted.

If the context was created by getcontext execution resumes with the registers filled with the same values and the same stack as if the getcontext call just returned.

If the context was modified with a call to makecontext execution continues with the function passed to makecontext which gets the specified parameters passed. If this function returns execution is resumed in the context which was referenced by the uc_link element of the context structure passed to makecontext at the time of the call. If uc_link was a null pointer the application terminates in this case.

Since the context contains information about the stack no two threads should use the same context at the same time. The result in most cases would be disastrous.

The setcontext function does not return unless an error occurred in which case it returns -1.

The setcontext function simply replaces the current context with the one described by the ucp parameter. This is often useful but there are situations where the current context has to be preserved.

Function: int swapcontext (ucontext_t *restrict oucp, const ucontext_t *restrict ucp)

The swapcontext function is similar to setcontext but instead of just replacing the current context the latter is first saved in the object pointed to by oucp as if this was a call to getcontext. The saved context would resume after the call to swapcontext.

Once the current context is saved the context described in ucp is installed and execution continues as described in this context.

If swapcontext succeeds the function does not return unless the context oucp is used without prior modification by makecontext. The return value in this case is 0. If the function fails it returns -1 and set errno accordingly.

Example for SVID Context Handling

The easiest way to use the context handling functions is as a replacement for setjmp and longjmp. The context contains on most platforms more information which might lead to less surprises but this also means using these functions is more expensive (beside being less portable).
int
random_search (int n, int (*fp) (int, ucontext_t *))
{
  volatile int cnt = 0;
  ucontext_t uc;

  /* Safe current context.  */
  if (getcontext (&uc) < 0)
    return -1;

  /* If we have not tried n times try again.  */
  if (cnt++ < n)
    /* Call the function with a new random number
       and the context.  */
    if (fp (rand (), &uc) != 0)
      /* We found what we were looking for.  */
      return 1;

  /* Not found.  */
  return 0;
}
Using contexts in such a way enables emulating exception handling. The search functions passed in the fp parameter could be very large, nested, and complex which would make it complicated (or at least would require a lot of code) to leave the function with an error value which has to be passed down to the caller. By using the context it is possible to leave the search function in one step and allow restarting the search which also has the nice side effect that it can be significantly faster.

Something which is harder to implement with setjmp and longjmp is to switch temporarily to a different execution path and then resume where execution was stopped.
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <ucontext.h>
#include <sys/time.h>

/* Set by the signal handler. */
static volatile int expired;

/* The contexts. */
static ucontext_t uc[3];

/* We do only a certain number of switches. */
static int switches;

/* This is the function doing the work.  It is just a
   skeleton, real code has to be filled in. */
static void
f (int n)
{
  int m = 0;
  while (1)
    {
      /* This is where the work would be done. */
      if (++m % 100 == 0)
        {
          putchar ('.');
          fflush (stdout);
        }

      /* Regularly the expire variable must be checked. */
      if (expired)
        {
          /* We do not want the program to run forever. */
          if (++switches == 20)
            return;

          printf ("\nswitching from %d to %d\n", n, 3 - n);
          expired = 0;
          /* Switch to the other context, saving the current one. */
          swapcontext (&uc[n], &uc[3 - n]);
        }
    }
}

/* This is the signal handler which simply set the variable. */
void
handler (int signal)
{
  expired = 1;
}

int
main (void)
{
  struct sigaction sa;
  struct itimerval it;
  char st1[8192];
  char st2[8192];

  /* Initialize the data structures for the interval timer. */
  sa.sa_flags = SA_RESTART;
  sigfillset (&sa.sa_mask);
  sa.sa_handler = handler;
  it.it_interval.tv_sec = 0;
  it.it_interval.tv_usec = 1;
  it.it_value = it.it_interval;

  /* Install the timer and get the context we can manipulate. */
  if (sigaction (SIGPROF, &sa, NULL) < 0
      || setitimer (ITIMER_PROF, &it, NULL) < 0
      || getcontext (&uc[1]) == -1
      || getcontext (&uc[2]) == -1)
    abort ();

  /* Create a context with a separate stack which causes the
     function f to be call with the parameter 1.
     Note that the uc_link points to the main context
     which will cause the program to terminate once the function
     return. */
  uc[1].uc_link = &uc[0];
  uc[1].uc_stack.ss_sp = st1;
  uc[1].uc_stack.ss_size = sizeof st1;
  makecontext (&uc[1], (void (*) (void)) f, 1, 1);

  /* Similarly, but 2 is passed as the parameter to f. */
  uc[2].uc_link = &uc[0];
  uc[2].uc_stack.ss_sp = st2;
  uc[2].uc_stack.ss_size = sizeof st2;
  makecontext (&uc[2], (void (*) (void)) f, 1, 2);

  /* Start running. */
  swapcontext (&uc[0], &uc[1]);
  putchar ('\n');

  return 0;
}
This an example how the context functions can be used to implement co-routines or cooperative multi-threading. All that has to be done is to call every once in a while swapcontext to continue running a different context. It is not allowed to do the context switching from the signal handler directly since neither setcontext nor swapcontext are functions which can be called from a signal handler. But setting a variable in the signal handler and checking it in the body of the functions which are executed. Since swapcontext is saving the current context it is possible to have multiple different scheduling points in the code. Execution will always resume where it was left.
Signal Handling

A signal is a software interrupt delivered to a process. The operating system uses signals to report exceptional situations to an executing program. Some signals report errors such as references to invalid memory addresses; others report asynchronous events, such as disconnection of a phone line.

The GNU C library defines a variety of signal types, each for a particular kind of event. Some kinds of events make it inadvisable or impossible for the program to proceed as usual, and the corresponding signals normally abort the program. Other kinds of signals that report harmless events are ignored by default.

If you anticipate an event that causes signals, you can define a handler function and tell the operating system to run it when that particular type of signal arrives.

Finally, one process can send a signal to another process; this allows a parent process to abort a child, or two related processes to communicate and synchronize.

Basic Concepts of Signals

This section explains basic concepts of how signals are generated, what happens after a signal is delivered, and how programs can handle signals.

Some Kinds of Signals

A signal reports the occurrence of an exceptional event. These are some of the events that can cause (or generate, or raise) a signal:

A program error such as dividing by zero or issuing an address outside the valid range.
A user request to interrupt or terminate the program. Most environments are set up to let a user suspend the program by typing C-z, or terminate it with C-c. Whatever key sequence is used, the operating system sends the proper signal to interrupt the process.
The termination of a child process.
Expiration of a timer or alarm.
A call to kill or raise by the same process.
A call to kill from another process. Signals are a limited but useful form of interprocess communication.
An attempt to perform an I/O operation that cannot be done. Examples are reading from a pipe that has no writer (see section Pipes and FIFOs), and reading or writing to a terminal in certain situations (see section Job Control).

Each of these kinds of events (excepting explicit calls to kill and raise) generates its own particular kind of signal. The various kinds of signals are listed and described in detail in section Standard Signals.

Concepts of Signal Generation

In general, the events that generate signals fall into three major categories: errors, external events, and explicit requests.

An error means that a program has done something invalid and cannot continue execution. But not all kinds of errors generate signals--in fact, most do not. For example, opening a nonexistent file is an error, but it does not raise a signal; instead, open returns -1. In general, errors that are necessarily associated with certain library functions are reported by returning a value that indicates an error. The errors which raise signals are those which can happen anywhere in the program, not just in library calls. These include division by zero and invalid memory addresses.

An external event generally has to do with I/O or other processes. These include the arrival of input, the expiration of a timer, and the termination of a child process.

An explicit request means the use of a library function such as kill whose purpose is specifically to generate a signal.

Signals may be generated synchronously or asynchronously. A synchronous signal pertains to a specific action in the program, and is delivered (unless blocked) during that action. Most errors generate signals synchronously, and so do explicit requests by a process to generate a signal for that same process. On some machines, certain kinds of hardware errors (usually floating-point exceptions) are not reported completely synchronously, but may arrive a few instructions later.

Asynchronous signals are generated by events outside the control of the process that receives them. These signals arrive at unpredictable times during execution. External events generate signals asynchronously, and so do explicit requests that apply to some other process.

A given type of signal is either typically synchronous or typically asynchronous. For example, signals for errors are typically synchronous because errors generate signals synchronously. But any type of signal can be generated synchronously or asynchronously with an explicit request.

How Signals Are Delivered

When a signal is generated, it becomes pending. Normally it remains pending for just a short period of time and then is delivered to the process that was signaled. However, if that kind of signal is currently blocked, it may remain pending indefinitely--until signals of that kind are unblocked. Once unblocked, it will be delivered immediately. See section Blocking Signals.

When the signal is delivered, whether right away or after a long delay, the specified action for that signal is taken. For certain signals, such as SIGKILL and SIGSTOP, the action is fixed, but for most signals, the program has a choice: ignore the signal, specify a handler function, or accept the default action for that kind of signal. The program specifies its choice using functions such as signal or sigaction (see section Specifying Signal Actions). We sometimes say that a handler catches the signal. While the handler is running, that particular signal is normally blocked.

If the specified action for a kind of signal is to ignore it, then any such signal which is generated is discarded immediately. This happens even if the signal is also blocked at the time. A signal discarded in this way will never be delivered, not even if the program subsequently specifies a different action for that kind of signal and then unblocks it.

If a signal arrives which the program has neither handled nor ignored, its default action takes place. Each kind of signal has its own default action, documented below (see section Standard Signals). For most kinds of signals, the default action is to terminate the process. For certain kinds of signals that represent "harmless" events, the default action is to do nothing.

When a signal terminates a process, its parent process can determine the cause of termination by examining the termination status code reported by the wait or waitpid functions. (This is discussed in more detail in section Process Completion.) The information it can get includes the fact that termination was due to a signal and the kind of signal involved. If a program you run from a shell is terminated by a signal, the shell typically prints some kind of error message.

The signals that normally represent program errors have a special property: when one of these signals terminates the process, it also writes a core dump file which records the state of the process at the time of termination. You can examine the core dump with a debugger to investigate what caused the error.

If you raise a "program error" signal by explicit request, and this terminates the process, it makes a core dump file just as if the signal had been due directly to an error.

Standard Signals

This section lists the names for various standard kinds of signals and describes what kind of event they mean. Each signal name is a macro which stands for a positive integer--the signal number for that kind of signal. Your programs should never make assumptions about the numeric code for a particular kind of signal, but rather refer to them always by the names defined here. This is because the number for a given kind of signal can vary from system to system, but the meanings of the names are standardized and fairly uniform.

The signal names are defined in the header file `signal.h'.

Macro: int NSIG
The value of this symbolic constant is the total number of signals defined. Since the signal numbers are allocated consecutively, NSIG is also one greater than the largest defined signal number.

Program Error Signals

The following signals are generated when a serious program error is detected by the operating system or the computer itself. In general, all of these signals are indications that your program is seriously broken in some way, and there's usually no way to continue the computation which encountered the error.

Some programs handle program error signals in order to tidy up before terminating; for example, programs that turn off echoing of terminal input should handle program error signals in order to turn echoing back on. The handler should end by specifying the default action for the signal that happened and then reraising it; this will cause the program to terminate with that signal, as if it had not had a handler. (See section Handlers That Terminate the Process.)

Termination is the sensible ultimate outcome from a program error in most programs. However, programming systems such as Lisp that can load compiled user programs might need to keep executing even if a user program incurs an error. These programs have handlers which use longjmp to return control to the command level.

The default action for all of these signals is to cause the process to terminate. If you block or ignore these signals or establish handlers for them that return normally, your program will probably break horribly when such signals happen, unless they are generated by raise or kill instead of a real error.

When one of these program error signals terminates a process, it also writes a core dump file which records the state of the process at the time of termination. The core dump file is named `core' and is written in whichever directory is current in the process at the time. (On the GNU system, you can specify the file name for core dumps with the environment variable COREFILE.) The purpose of core dump files is so that you can examine them with a debugger to investigate what caused the error.

Macro: int SIGFPE
The SIGFPE signal reports a fatal arithmetic error. Although the name is derived from "floating-point exception", this signal actually covers all arithmetic errors, including division by zero and overflow. If a program stores integer data in a location which is then used in a floating-point operation, this often causes an "invalid operation" exception, because the processor cannot recognize the data as a floating-point number.

Actual floating-point exceptions are a complicated subject because there are many types of exceptions with subtly different meanings, and the SIGFPE signal doesn't distinguish between them. The IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985 and ANSI/IEEE Std 854-1987) defines various floating-point exceptions and requires conforming computer systems to report their occurrences. However, this standard does not specify how the exceptions are reported, or what kinds of handling and control the operating system can offer to the programmer.

BSD systems provide the SIGFPE handler with an extra argument that distinguishes various causes of the exception. In order to access this argument, you must define the handler to accept two arguments, which means you must cast it to a one-argument function type in order to establish the handler. The GNU library does provide this extra argument, but the value is meaningful only on operating systems that provide the information (BSD systems and GNU systems).

FPE_INTOVF_TRAP
Integer overflow (impossible in a C program unless you enable overflow trapping in a hardware-specific fashion).
FPE_INTDIV_TRAP
Integer division by zero.
FPE_SUBRNG_TRAP
Subscript-range (something that C programs never check for).
FPE_FLTOVF_TRAP
Floating overflow trap.
FPE_FLTDIV_TRAP
Floating/decimal division by zero.
FPE_FLTUND_TRAP
Floating underflow trap. (Trapping on floating underflow is not normally enabled.)
FPE_DECOVF_TRAP
Decimal overflow trap. (Only a few machines have decimal arithmetic and C never uses it.)

Macro: int SIGILL
The name of this signal is derived from "illegal instruction"; it usually means your program is trying to execute garbage or a privileged instruction. Since the C compiler generates only valid instructions, SIGILL typically indicates that the executable file is corrupted, or that you are trying to execute data. Some common ways of getting into the latter situation are by passing an invalid object where a pointer to a function was expected, or by writing past the end of an automatic array (or similar problems with pointers to automatic variables) and corrupting other data on the stack such as the return address of a stack frame.

SIGILL can also be generated when the stack overflows, or when the system has trouble running the handler for a signal.

Macro: int SIGSEGV
This signal is generated when a program tries to read or write outside the memory that is allocated for it, or to write memory that can only be read. (Actually, the signals only occur when the program goes far enough outside to be detected by the system's memory protection mechanism.) The name is an abbreviation for "segmentation violation".

Common ways of getting a SIGSEGV condition include dereferencing a null or uninitialized pointer, or when you use a pointer to step through an array, but fail to check for the end of the array. It varies among systems whether dereferencing a null pointer generates SIGSEGV or SIGBUS.

Macro: int SIGBUS
This signal is generated when an invalid pointer is dereferenced. Like SIGSEGV, this signal is typically the result of dereferencing an uninitialized pointer. The difference between the two is that SIGSEGV indicates an invalid access to valid memory, while SIGBUS indicates an access to an invalid address. In particular, SIGBUS signals often result from dereferencing a misaligned pointer, such as referring to a four-word integer at an address not divisible by four. (Each kind of computer has its own requirements for address alignment.)

The name of this signal is an abbreviation for "bus error".

Macro: int SIGABRT
This signal indicates an error detected by the program itself and reported by calling abort. See section Aborting a Program.

Macro: int SIGIOT
Generated by the PDP-11 "iot" instruction. On most machines, this is just another name for SIGABRT.

Macro: int SIGTRAP
Generated by the machine's breakpoint instruction, and possibly other trap instructions. This signal is used by debuggers. Your program will probably only see SIGTRAP if it is somehow executing bad instructions.

Macro: int SIGEMT
Emulator trap; this results from certain unimplemented instructions which might be emulated in software, or the operating system's failure to properly emulate them.

Macro: int SIGSYS
Bad system call; that is to say, the instruction to trap to the operating system was executed, but the code number for the system call to perform was invalid.

Termination Signals

These signals are all used to tell a process to terminate, in one way or another. They have different names because they're used for slightly different purposes, and programs might want to handle them differently.

The reason for handling these signals is usually so your program can tidy up as appropriate before actually terminating. For example, you might want to save state information, delete temporary files, or restore the previous terminal modes. Such a handler should end by specifying the default action for the signal that happened and then reraising it; this will cause the program to terminate with that signal, as if it had not had a handler. (See section Handlers That Terminate the Process.)

The (obvious) default action for all of these signals is to cause the process to terminate.

Macro: int SIGTERM
The SIGTERM signal is a generic signal used to cause program termination. Unlike SIGKILL, this signal can be blocked, handled, and ignored. It is the normal way to politely ask a program to terminate.

The shell command kill generates SIGTERM by default.

Macro: int SIGINT
The SIGINT ("program interrupt") signal is sent when the user types the INTR character (normally C-c). See section Special Characters, for information about terminal driver support for C-c.

Macro: int SIGQUIT
The SIGQUIT signal is similar to SIGINT, except that it's controlled by a different key--the QUIT character, usually C-\---and produces a core dump when it terminates the process, just like a program error signal. You can think of this as a program error condition "detected" by the user.

See section Program Error Signals, for information about core dumps. See section Special Characters, for information about terminal driver support.

Certain kinds of cleanups are best omitted in handling SIGQUIT. For example, if the program creates temporary files, it should handle the other termination requests by deleting the temporary files. But it is better for SIGQUIT not to delete them, so that the user can examine them in conjunction with the core dump.

Macro: int SIGKILL
The SIGKILL signal is used to cause immediate program termination. It cannot be handled or ignored, and is therefore always fatal. It is also not possible to block this signal.

This signal is usually generated only by explicit request. Since it cannot be handled, you should generate it only as a last resort, after first trying a less drastic method such as C-c or SIGTERM. If a process does not respond to any other termination signals, sending it a SIGKILL signal will almost always cause it to go away.

In fact, if SIGKILL fails to terminate a process, that by itself constitutes an operating system bug which you should report.

The system will generate SIGKILL for a process itself under some unusual conditions where the program cannot possibly continue to run (even to run a signal handler).

Macro: int SIGHUP
The SIGHUP ("hang-up") signal is used to report that the user's terminal is disconnected, perhaps because a network or telephone connection was broken. For more information about this, see section Control Modes.

This signal is also used to report the termination of the controlling process on a terminal to jobs associated with that session; this termination effectively disconnects all processes in the session from the controlling terminal. For more information, see section Termination Internals.

Alarm Signals

These signals are used to indicate the expiration of timers. See section Setting an Alarm, for information about functions that cause these signals to be sent.

The default behavior for these signals is to cause program termination. This default is rarely useful, but no other default would be useful; most of the ways of using these signals would require handler functions in any case.

Macro: int SIGALRM
This signal typically indicates expiration of a timer that measures real or clock time. It is used by the alarm function, for example.

Macro: int SIGVTALRM
This signal typically indicates expiration of a timer that measures CPU time used by the current process. The name is an abbreviation for "virtual time alarm".

Macro: int SIGPROF
This signal typically indicates expiration of a timer that measures both CPU time used by the current process, and CPU time expended on behalf of the process by the system. Such a timer is used to implement code profiling facilities, hence the name of this signal.

Asynchronous I/O Signals

The signals listed in this section are used in conjunction with asynchronous I/O facilities. You have to take explicit action by calling fcntl to enable a particular file descriptor to generate these signals (see section Interrupt-Driven Input). The default action for these signals is to ignore them.

Macro: int SIGIO
This signal is sent when a file descriptor is ready to perform input or output.

On most operating systems, terminals and sockets are the only kinds of files that can generate SIGIO; other kinds, including ordinary files, never generate SIGIO even if you ask them to.

In the GNU system SIGIO will always be generated properly if you successfully set asynchronous mode with fcntl.

Macro: int SIGURG
This signal is sent when "urgent" or out-of-band data arrives on a socket. See section Out-of-Band Data.

Macro: int SIGPOLL
This is a System V signal name, more or less similar to SIGIO. It is defined only for compatibility.

Job Control Signals

These signals are used to support job control. If your system doesn't support job control, then these macros are defined but the signals themselves can't be raised or handled.

You should generally leave these signals alone unless you really understand how job control works. See section Job Control.

Macro: int SIGCHLD
This signal is sent to a parent process whenever one of its child processes terminates or stops.

The default action for this signal is to ignore it. If you establish a handler for this signal while there are child processes that have terminated but not reported their status via wait or waitpid (see section Process Completion), whether your new handler applies to those processes or not depends on the particular operating system.

Macro: int SIGCLD
This is an obsolete name for SIGCHLD.

Macro: int SIGCONT
You can send a SIGCONT signal to a process to make it continue. This signal is special--it always makes the process continue if it is stopped, before the signal is delivered. The default behavior is to do nothing else. You cannot block this signal. You can set a handler, but SIGCONT always makes the process continue regardless.

Most programs have no reason to handle SIGCONT; they simply resume execution without realizing they were ever stopped. You can use a handler for SIGCONT to make a program do something special when it is stopped and continued--for example, to reprint a prompt when it is suspended while waiting for input.

Macro: int SIGSTOP
The SIGSTOP signal stops the process. It cannot be handled, ignored, or blocked.

Macro: int SIGTSTP
The SIGTSTP signal is an interactive stop signal. Unlike SIGSTOP, this signal can be handled and ignored.

Your program should handle this signal if you have a special need to leave files or system tables in a secure state when a process is stopped. For example, programs that turn off echoing should handle SIGTSTP so they can turn echoing back on before stopping.

This signal is generated when the user types the SUSP character (normally C-z). For more information about terminal driver support, see section Special Characters.

Macro: int SIGTTIN
A process cannot read from the user's terminal while it is running as a background job. When any process in a background job tries to read from the terminal, all of the processes in the job are sent a SIGTTIN signal. The default action for this signal is to stop the process. For more information about how this interacts with the terminal driver, see section Access to the Controlling Terminal.

Macro: int SIGTTOU
This is similar to SIGTTIN, but is generated when a process in a background job attempts to write to the terminal or set its modes. Again, the default action is to stop the process. SIGTTOU is only generated for an attempt to write to the terminal if the TOSTOP output mode is set; see section Output Modes.

While a process is stopped, no more signals can be delivered to it until it is continued, except SIGKILL signals and (obviously) SIGCONT signals. The signals are marked as pending, but not delivered until the process is continued. The SIGKILL signal always causes termination of the process and can't be blocked, handled or ignored. You can ignore SIGCONT, but it always causes the process to be continued anyway if it is stopped. Sending a SIGCONT signal to a process causes any pending stop signals for that process to be discarded. Likewise, any pending SIGCONT signals for a process are discarded when it receives a stop signal.

When a process in an orphaned process group (see section Orphaned Process Groups) receives a SIGTSTP, SIGTTIN, or SIGTTOU signal and does not handle it, the process does not stop. Stopping the process would probably not be very useful, since there is no shell program that will notice it stop and allow the user to continue it. What happens instead depends on the operating system you are using. Some systems may do nothing; others may deliver another signal instead, such as SIGKILL or SIGHUP. In the GNU system, the process dies with SIGKILL; this avoids the problem of many stopped, orphaned processes lying around the system.

Operation Error Signals

These signals are used to report various errors generated by an operation done by the program. They do not necessarily indicate a programming error in the program, but an error that prevents an operating system call from completing. The default action for all of them is to cause the process to terminate.

Macro: int SIGPIPE
Broken pipe. If you use pipes or FIFOs, you have to design your application so that one process opens the pipe for reading before another starts writing. If the reading process never starts, or terminates unexpectedly, writing to the pipe or FIFO raises a SIGPIPE signal. If SIGPIPE is blocked, handled or ignored, the offending call fails with EPIPE instead.

Pipes and FIFO special files are discussed in more detail in section Pipes and FIFOs.

Another cause of SIGPIPE is when you try to output to a socket that isn't connected. See section Sending Data.

Macro: int SIGLOST
Resource lost. This signal is generated when you have an advisory lock on an NFS file, and the NFS server reboots and forgets about your lock.

In the GNU system, SIGLOST is generated when any server program dies unexpectedly. It is usually fine to ignore the signal; whatever call was made to the server that died just returns an error.

Macro: int SIGXCPU
CPU time limit exceeded. This signal is generated when the process exceeds its soft resource limit on CPU time. See section Limiting Resource Usage.

Macro: int SIGXFSZ
File size limit exceeded. This signal is generated when the process attempts to extend a file so it exceeds the process's soft resource limit on file size. See section Limiting Resource Usage.

Miscellaneous Signals

These signals are used for various other purposes. In general, they will not affect your program unless it explicitly uses them for something.

Macro: int SIGUSR1

Macro: int SIGUSR2
The SIGUSR1 and SIGUSR2 signals are set aside for you to use any way you want. They're useful for simple interprocess communication, if you write a signal handler for them in the program that receives the signal.

There is an example showing the use of SIGUSR1 and SIGUSR2 in section Signaling Another Process.

The default action is to terminate the process.

Macro: int SIGWINCH
Window size change. This is generated on some systems (including GNU) when the terminal driver's record of the number of rows and columns on the screen is changed. The default action is to ignore it.

If a program does full-screen display, it should handle SIGWINCH. When the signal arrives, it should fetch the new screen size and reformat its display accordingly.

Macro: int SIGINFO
Information request. In 4.4 BSD and the GNU system, this signal is sent to all the processes in the foreground process group of the controlling terminal when the user types the STATUS character in canonical mode; see section Characters that Cause Signals.

If the process is the leader of the process group, the default action is to print some status information about the system and what the process is doing. Otherwise the default is to do nothing.

Signal Messages

We mentioned above that the shell prints a message describing the signal that terminated a child process. The clean way to print a message describing a signal is to use the functions strsignal and psignal. These functions use a signal number to specify which kind of signal to describe. The signal number may come from the termination status of a child process (see section Process Completion) or it may come from a signal handler in the same process.

Function: char * strsignal (int signum)
This function returns a pointer to a statically-allocated string containing a message describing the signal signum. You should not modify the contents of this string; and, since it can be rewritten on subsequent calls, you should save a copy of it if you need to reference it later.

This function is a GNU extension, declared in the header file `string.h'.

Function: void psignal (int signum, const char *message)
This function prints a message describing the signal signum to the standard error output stream stderr; see section Standard Streams.

If you call psignal with a message that is either a null pointer or an empty string, psignal just prints the message corresponding to signum, adding a trailing newline.

If you supply a non-null message argument, then psignal prefixes its output with this string. It adds a colon and a space character to separate the message from the string corresponding to signum.

This function is a BSD feature, declared in the header file `signal.h'.

There is also an array sys_siglist which contains the messages for the various signal codes. This array exists on BSD systems, unlike strsignal.

Specifying Signal Actions

The simplest way to change the action for a signal is to use the signal function. You can specify a built-in action (such as to ignore the signal), or you can establish a handler.

The GNU library also implements the more versatile sigaction facility. This section describes both facilities and gives suggestions on which to use when.

Basic Signal Handling

The signal function provides a simple interface for establishing an action for a particular signal. The function and associated macros are declared in the header file `signal.h'.

Data Type: sighandler_t
This is the type of signal handler functions. Signal handlers take one integer argument specifying the signal number, and have return type void. So, you should define handler functions like this:
void handler (int signum) { ... }
The name sighandler_t for this data type is a GNU extension.

Function: sighandler_t signal (int signum, sighandler_t action)
The signal function establishes action as the action for the signal signum.

The first argument, signum, identifies the signal whose behavior you want to control, and should be a signal number. The proper way to specify a signal number is with one of the symbolic signal names (see section Standard Signals)---don't use an explicit number, because the numerical code for a given kind of signal may vary from operating system to operating system.

The second argument, action, specifies the action to use for the signal signum. This can be one of the following:

SIG_DFL
SIG_DFL specifies the default action for the particular signal. The default actions for various kinds of signals are stated in section Standard Signals.
SIG_IGN
SIG_IGN specifies that the signal should be ignored. Your program generally should not ignore signals that represent serious events or that are normally used to request termination. You cannot ignore the SIGKILL or SIGSTOP signals at all. You can ignore program error signals like SIGSEGV, but ignoring the error won't enable the program to continue executing meaningfully. Ignoring user requests such as SIGINT, SIGQUIT, and SIGTSTP is unfriendly. When you do not wish signals to be delivered during a certain part of the program, the thing to do is to block them, not ignore them. See section Blocking Signals.
handler
Supply the address of a handler function in your program, to specify running this handler as the way to deliver the signal. For more information about defining signal handler functions, see section Defining Signal Handlers.
If you set the action for a signal to SIG_IGN, or if you set it to SIG_DFL and the default action is to ignore that signal, then any pending signals of that type are discarded (even if they are blocked). Discarding the pending signals means that they will never be delivered, not even if you subsequently specify another action and unblock this kind of signal.

The signal function returns the action that was previously in effect for the specified signum. You can save this value and restore it later by calling signal again.

If signal can't honor the request, it returns SIG_ERR instead. The following errno error conditions are defined for this function:

EINVAL
You specified an invalid signum; or you tried to ignore or provide a handler for SIGKILL or SIGSTOP.
Compatibility Note: A problem encountered when working with the signal function is that it has different semantics on BSD and SVID systems. The difference is that on SVID systems the signal handler is deinstalled after signal delivery. On BSD systems the handler must be explicitly deinstalled. In the GNU C Library we use the BSD version by default. To use the SVID version you can either use the function sysv_signal (see below) or use the _XOPEN_SOURCE feature select macro (see section Feature Test Macros). In general, use of these functions should be avoided because of compatibility problems. It is better to use sigaction if it is available since the results are much more reliable.

Here is a simple example of setting up a handler to delete temporary files when certain fatal signals happen:
#include <signal.h>

void
termination_handler (int signum)
{
  struct temp_file *p;

  for (p = temp_file_list; p; p = p->next)
    unlink (p->name);
}

int
main (void)
{
  ...
  if (signal (SIGINT, termination_handler) == SIG_IGN)
    signal (SIGINT, SIG_IGN);
  if (signal (SIGHUP, termination_handler) == SIG_IGN)
    signal (SIGHUP, SIG_IGN);
  if (signal (SIGTERM, termination_handler) == SIG_IGN)
    signal (SIGTERM, SIG_IGN);
  ...
}
Note that if a given signal was previously set to be ignored, this code avoids altering that setting. This is because non-job-control shells often ignore certain signals when starting children, and it is important for the children to respect this.

We do not handle SIGQUIT or the program error signals in this example because these are designed to provide information for debugging (a core dump), and the temporary files may give useful information.

Function: sighandler_t sysv_signal (int signum, sighandler_t action)
The sysv_signal implements the behaviour of the standard signal function as found on SVID systems. The difference to BSD systems is that the handler is deinstalled after a delivery of a signal.

Compatibility Note: As said above for signal, this function should be avoided when possible. sigaction is the preferred method.

Function: sighandler_t ssignal (int signum, sighandler_t action)
The ssignal function does the same thing as signal; it is provided only for compatibility with SVID.

Macro: sighandler_t SIG_ERR
The value of this macro is used as the return value from signal to indicate an error.

Advanced Signal Handling

The sigaction function has the same basic effect as signal: to specify how a signal should be handled by the process. However, sigaction offers more control, at the expense of more complexity. In particular, sigaction allows you to specify additional flags to control when the signal is generated and how the handler is invoked.

The sigaction function is declared in `signal.h'.

Data Type: struct sigaction
Structures of type struct sigaction are used in the sigaction function to specify all the information about how to handle a particular signal. This structure contains at least the following members:

sighandler_t sa_handler
This is used in the same way as the action argument to the signal function. The value can be SIG_DFL, SIG_IGN, or a function pointer. See section Basic Signal Handling.
sigset_t sa_mask
This specifies a set of signals to be blocked while the handler runs. Blocking is explained in section Blocking Signals for a Handler. Note that the signal that was delivered is automatically blocked by default before its handler is started; this is true regardless of the value in sa_mask. If you want that signal not to be blocked within its handler, you must write code in the handler to unblock it.
int sa_flags
This specifies various flags which can affect the behavior of the signal. These are described in more detail in section Flags for sigaction.

Function: int sigaction (int signum, const struct sigaction *restrict action, struct sigaction *restrict old-action)
The action argument is used to set up a new action for the signal signum, while the old-action argument is used to return information about the action previously associated with this symbol. (In other words, old-action has the same purpose as the signal function's return value--you can check to see what the old action in effect for the signal was, and restore it later if you want.)

Either action or old-action can be a null pointer. If old-action is a null pointer, this simply suppresses the return of information about the old action. If action is a null pointer, the action associated with the signal signum is unchanged; this allows you to inquire about how a signal is being handled without changing that handling.

The return value from sigaction is zero if it succeeds, and -1 on failure. The following errno error conditions are defined for this function:

EINVAL
The signum argument is not valid, or you are trying to trap or ignore SIGKILL or SIGSTOP.
Interaction of signal and sigaction

It's possible to use both the signal and sigaction functions within a single program, but you have to be careful because they can interact in slightly strange ways.

The sigaction function specifies more information than the signal function, so the return value from signal cannot express the full range of sigaction possibilities. Therefore, if you use signal to save and later reestablish an action, it may not be able to reestablish properly a handler that was established with sigaction.

To avoid having problems as a result, always use sigaction to save and restore a handler if your program uses sigaction at all. Since sigaction is more general, it can properly save and reestablish any action, regardless of whether it was established originally with signal or sigaction.

On some systems if you establish an action with signal and then examine it with sigaction, the handler address that you get may not be the same as what you specified with signal. It may not even be suitable for use as an action argument with signal. But you can rely on using it as an argument to sigaction. This problem never happens on the GNU system.

So, you're better off using one or the other of the mechanisms consistently within a single program.

Portability Note: The basic signal function is a feature of ISO C, while sigaction is part of the POSIX.1 standard. If you are concerned about portability to non-POSIX systems, then you should use the signal function instead.

sigaction Function Example

In section Basic Signal Handling, we gave an example of establishing a simple handler for termination signals using signal. Here is an equivalent example using sigaction:
#include <signal.h>

void
termination_handler (int signum)
{
  struct temp_file *p;

  for (p = temp_file_list; p; p = p->next)
    unlink (p->name);
}

int
main (void)
{
  ...
  struct sigaction new_action, old_action;

  /* Set up the structure to specify the new action. */
  new_action.sa_handler = termination_handler;
  sigemptyset (&new_action.sa_mask);
  new_action.sa_flags = 0;

  sigaction (SIGINT, NULL, &old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGINT, &new_action, NULL);
  sigaction (SIGHUP, NULL, &old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGHUP, &new_action, NULL);
  sigaction (SIGTERM, NULL, &old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGTERM, &new_action, NULL);
  ...
}
The program just loads the new_action structure with the desired parameters and passes it in the sigaction call. The usage of sigemptyset is described later; see section Blocking Signals.

As in the example using signal, we avoid handling signals previously set to be ignored. Here we can avoid altering the signal handler even momentarily, by using the feature of sigaction that lets us examine the current action without specifying a new one.

Here is another example. It retrieves information about the current action for SIGINT without changing that action.
struct sigaction query_action;

if (sigaction (SIGINT, NULL, &query_action) < 0)
  /* sigaction returns -1 in case of error. */
else if (query_action.sa_handler == SIG_DFL)
  /* SIGINT is handled in the default, fatal manner. */
else if (query_action.sa_handler == SIG_IGN)
  /* SIGINT is ignored. */
else
  /* A programmer-defined signal handler is in effect. */
Flags for sigaction

The sa_flags member of the sigaction structure is a catch-all for special features. Most of the time, SA_RESTART is a good value to use for this field.

The value of sa_flags is interpreted as a bit mask. Thus, you should choose the flags you want to set, OR those flags together, and store the result in the sa_flags member of your sigaction structure.

Each signal number has its own set of flags. Each call to sigaction affects one particular signal number, and the flags that you specify apply only to that particular signal.

In the GNU C library, establishing a handler with signal sets all the flags to zero except for SA_RESTART, whose value depends on the settings you have made with siginterrupt. See section Primitives Interrupted by Signals, to see what this is about.

These macros are defined in the header file `signal.h'.

Macro: int SA_NOCLDSTOP
This flag is meaningful only for the SIGCHLD signal. When the flag is set, the system delivers the signal for a terminated child process but not for one that is stopped. By default, SIGCHLD is delivered for both terminated children and stopped children.

Setting this flag for a signal other than SIGCHLD has no effect.

Macro: int SA_ONSTACK
If this flag is set for a particular signal number, the system uses the signal stack when delivering that kind of signal. See section Using a Separate Signal Stack. If a signal with this flag arrives and you have not set a signal stack, the system terminates the program with SIGILL.

Macro: int SA_RESTART
This flag controls what happens when a signal is delivered during certain primitives (such as open, read or write), and the signal handler returns normally. There are two alternatives: the library function can resume, or it can return failure with error code EINTR.

The choice is controlled by the SA_RESTART flag for the particular kind of signal that was delivered. If the flag is set, returning from a handler resumes the library function. If the flag is clear, returning from a handler makes the function fail. See section Primitives Interrupted by Signals.

Initial Signal Actions

When a new process is created (see section Creating a Process), it inherits handling of signals from its parent process. However, when you load a new process image using the exec function (see section Executing a File), any signals that you've defined your own handlers for revert to their SIG_DFL handling. (If you think about it a little, this makes sense; the handler functions from the old program are specific to that program, and aren't even present in the address space of the new program image.) Of course, the new program can establish its own handlers.

When a program is run by a shell, the shell normally sets the initial actions for the child process to SIG_DFL or SIG_IGN, as appropriate. It's a good idea to check to make sure that the shell has not set up an initial action of SIG_IGN before you establish your own signal handlers.

Here is an example of how to establish a handler for SIGHUP, but not if SIGHUP is currently ignored:
...
struct sigaction temp;

sigaction (SIGHUP, NULL, &temp);

if (temp.sa_handler != SIG_IGN)
  {
    temp.sa_handler = handle_sighup;
    sigemptyset (&temp.sa_mask);
    sigaction (SIGHUP, &temp, NULL);
  }
Defining Signal Handlers

This section describes how to write a signal handler function that can be established with the signal or sigaction functions.

A signal handler is just a function that you compile together with the rest of the program. Instead of directly invoking the function, you use signal or sigaction to tell the operating system to call it when a signal arrives. This is known as establishing the handler. See section Specifying Signal Actions.

There are two basic strategies you can use in signal handler functions:

You can have the handler function note that the signal arrived by tweaking some global data structures, and then return normally.
You can have the handler function terminate the program or transfer control to a point where it can recover from the situation that caused the signal.

You need to take special care in writing handler functions because they can be called asynchronously. That is, a handler might be called at any point in the program, unpredictably. If two signals arrive during a very short interval, one handler can run within another. This section describes what your handler should do, and what you should avoid.

Signal Handlers that Return

Handlers which return normally are usually used for signals such as SIGALRM and the I/O and interprocess communication signals. But a handler for SIGINT might also return normally after setting a flag that tells the program to exit at a convenient time.

It is not safe to return normally from the handler for a program error signal, because the behavior of the program when the handler function returns is not defined after a program error. See section Program Error Signals.

Handlers that return normally must modify some global variable in order to have any effect. Typically, the variable is one that is examined periodically by the program during normal operation. Its data type should be sig_atomic_t for reasons described in section Atomic Data Access and Signal Handling.

Here is a simple example of such a program. It executes the body of the loop until it has noticed that a SIGALRM signal has arrived. This technique is useful because it allows the iteration in progress when the signal arrives to complete before the loop exits.
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>

/* This flag controls termination of the main loop. */
volatile sig_atomic_t keep_going = 1;

/* The signal handler just clears the flag and re-enables itself. */
void
catch_alarm (int sig)
{
  keep_going = 0;
  signal (sig, catch_alarm);
}

void
do_stuff (void)
{
  puts ("Doing stuff while waiting for alarm....");
}

int
main (void)
{
  /* Establish a handler for SIGALRM signals. */
  signal (SIGALRM, catch_alarm);

  /* Set an alarm to go off in a little while. */
  alarm (2);

  /* Check the flag once in a while to see when to quit. */
  while (keep_going)
    do_stuff ();

  return EXIT_SUCCESS;
}
Handlers That Terminate the Process

Handler functions that terminate the program are typically used to cause orderly cleanup or recovery from program error signals and interactive interrupts.

The cleanest way for a handler to terminate the process is to raise the same signal that ran the handler in the first place. Here is how to do this:
volatile sig_atomic_t fatal_error_in_progress = 0;

void
fatal_error_signal (int sig)
{
  /* Since this handler is established for more than one kind of signal,
     it might still get invoked recursively by delivery of some other kind
     of signal.  Use a static variable to keep track of that. */
  if (fatal_error_in_progress)
    raise (sig);
  fatal_error_in_progress = 1;

  /* Now do the clean up actions:
     - reset terminal modes
     - kill child processes
     - remove lock files */
  ...

  /* Now reraise the signal.  We reactivate the signal's
     default handling, which is to terminate the process.
     We could just call exit or abort,
     but reraising the signal sets the return status
     from the process correctly. */
  signal (sig, SIG_DFL);
  raise (sig);
}
Nonlocal Control Transfer in Handlers

You can do a nonlocal transfer of control out of a signal handler using the setjmp and longjmp facilities (see section Non-Local Exits).

When the handler does a nonlocal control transfer, the part of the program that was running will not continue. If this part of the program was in the middle of updating an important data structure, the data structure will remain inconsistent. Since the program does not terminate, the inconsistency is likely to be noticed later on.

There are two ways to avoid this problem. One is to block the signal for the parts of the program that update important data structures. Blocking the signal delays its delivery until it is unblocked, once the critical updating is finished. See section Blocking Signals.

The other way to re-initialize the crucial data structures in the signal handler, or make their values consistent.

Here is a rather schematic example showing the reinitialization of one global variable.
#include <signal.h>
#include <setjmp.h>

jmp_buf return_to_top_level;

volatile sig_atomic_t waiting_for_input;

void
handle_sigint (int signum)
{
  /* We may have been waiting for input when the signal arrived,
     but we are no longer waiting once we transfer control. */
  waiting_for_input = 0;
  longjmp (return_to_top_level, 1);
}

int
main (void)
{
  ...
  signal (SIGINT, sigint_handler);
  ...
  while (1) {
    prepare_for_command ();
    if (setjmp (return_to_top_level) == 0)
      read_and_execute_command ();
  }
}

/* Imagine this is a subroutine used by various commands. */
char *
read_data ()
{
  if (input_from_terminal) {
    waiting_for_input = 1;
    ...
    waiting_for_input = 0;
  } else {
    ...
  }
}
Signals Arriving While a Handler Runs

What happens if another signal arrives while your signal handler function is running?

When the handler for a particular signal is invoked, that signal is automatically blocked until the handler returns. That means that if two signals of the same kind arrive close together, the second one will be held until the first has been handled. (The handler can explicitly unblock the signal using sigprocmask, if you want to allow more signals of this type to arrive; see section Process Signal Mask.)

However, your handler can still be interrupted by delivery of another kind of signal. To avoid this, you can use the sa_mask member of the action structure passed to sigaction to explicitly specify which signals should be blocked while the signal handler runs. These signals are in addition to the signal for which the handler was invoked, and any other signals that are normally blocked by the process. See section Blocking Signals for a Handler.

When the handler returns, the set of blocked signals is restored to the value it had before the handler ran. So using sigprocmask inside the handler only affects what signals can arrive during the execution of the handler itself, not what signals can arrive once the handler returns.

Portability Note: Always use sigaction to establish a handler for a signal that you expect to receive asynchronously, if you want your program to work properly on System V Unix. On this system, the handling of a signal whose handler was established with signal automatically sets the signal's action back to SIG_DFL, and the handler must re-establish itself each time it runs. This practice, while inconvenient, does work when signals cannot arrive in succession. However, if another signal can arrive right away, it may arrive before the handler can re-establish itself. Then the second signal would receive the default handling, which could terminate the process.

Signals Close Together Merge into One

If multiple signals of the same type are delivered to your process before your signal handler has a chance to be invoked at all, the handler may only be invoked once, as if only a single signal had arrived. In effect, the signals merge into one. This situation can arise when the signal is blocked, or in a multiprocessing environment where the system is busy running some other processes while the signals are delivered. This means, for example, that you cannot reliably use a signal handler to count signals. The only distinction you can reliably make is whether at least one signal has arrived since a given time in the past.

Here is an example of a handler for SIGCHLD that compensates for the fact that the number of signals received may not equal the number of child processes that generate them. It assumes that the program keeps track of all the child processes with a chain of structures as follows:
struct process
{
  struct process *next;
  /* The process ID of this child.  */
  int pid;
  /* The descriptor of the pipe or pseudo terminal
     on which output comes from this child.  */
  int input_descriptor;
  /* Nonzero if this process has stopped or terminated.  */
  sig_atomic_t have_status;
  /* The status of this child; 0 if running,
     otherwise a status value from waitpid.  */
  int status;
};

struct process *process_list;
This example also uses a flag to indicate whether signals have arrived since some time in the past--whenever the program last cleared it to zero.
/* Nonzero means some child's status has changed
   so look at process_list for the details.  */
int process_status_change;
Here is the handler itself:
void
sigchld_handler (int signo)
{
  int old_errno = errno;

  while (1) {
    register int pid;
    int w;
    struct process *p;

    /* Keep asking for a status until we get a definitive result.  */
    do
      {
        errno = 0;
        pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED);
      }
    while (pid <= 0 && errno == EINTR);

    if (pid <= 0) {
      /* A real failure means there are no more
         stopped or terminated child processes, so return.  */
      errno = old_errno;
      return;
    }

    /* Find the process that signaled us, and record its status.  */

    for (p = process_list; p; p = p->next)
      if (p->pid == pid) {
        p->status = w;
        /* Indicate that the status field
           has data to look at.  We do this only after storing it.  */
        p->have_status = 1;

        /* If process has terminated, stop waiting for its output.  */
        if (WIFSIGNALED (w) || WIFEXITED (w))
          if (p->input_descriptor)
            FD_CLR (p->input_descriptor, &input_wait_mask);

        /* The program should check this flag from time to time
           to see if there is any news in process_list.  */
        ++process_status_change;
      }

    /* Loop around to handle all the processes
       that have something to tell us.  */
  }
}
Here is the proper way to check the flag process_status_change:
if (process_status_change) {
  struct process *p;
  process_status_change = 0;
  for (p = process_list; p; p = p->next)
    if (p->have_status) {
      ... Examine p->status ...
    }
}
It is vital to clear the flag before examining the list; otherwise, if a signal were delivered just before the clearing of the flag, and after the appropriate element of the process list had been checked, the status change would go unnoticed until the next signal arrived to set the flag again. You could, of course, avoid this problem by blocking the signal while scanning the list, but it is much more elegant to guarantee correctness by doing things in the right order.

The loop which checks process status avoids examining p->status until it sees that status has been validly stored. This is to make sure that the status cannot change in the middle of accessing it. Once p->have_status is set, it means that the child process is stopped or terminated, and in either case, it cannot stop or terminate again until the program has taken notice. See section Atomic Usage Patterns, for more information about coping with interruptions during accesses of a variable.

Here is another way you can test whether the handler has run since the last time you checked. This technique uses a counter which is never changed outside the handler. Instead of clearing the count, the program remembers the previous value and sees whether it has changed since the previous check. The advantage of this method is that different parts of the program can check independently, each part checking whether there has been a signal since that part last checked.
sig_atomic_t process_status_change;

sig_atomic_t last_process_status_change;

...
{
  sig_atomic_t prev = last_process_status_change;
  last_process_status_change = process_status_change;
  if (last_process_status_change != prev) {
    struct process *p;
    for (p = process_list; p; p = p->next)
      if (p->have_status) {
        ... Examine p->status ...
      }
  }
}
Signal Handling and Nonreentrant Functions

Handler functions usually don't do very much. The best practice is to write a handler that does nothing but set an external variable that the program checks regularly, and leave all serious work to the program. This is best because the handler can be called asynchronously, at unpredictable times--perhaps in the middle of a primitive function, or even between the beginning and the end of a C operator that requires multiple instructions. The data structures being manipulated might therefore be in an inconsistent state when the handler function is invoked. Even copying one int variable into another can take two instructions on most machines.

This means you have to be very careful about what you do in a signal handler.

If your handler needs to access any global variables from your program, declare those variables volatile. This tells the compiler that the value of the variable might change asynchronously, and inhibits certain optimizations that would be invalidated by such modifications.
If you call a function in the handler, make sure it is reentrant with respect to signals, or else make sure that the signal cannot interrupt a call to a related function.

A function can be non-reentrant if it uses memory that is not on the stack.

If a function uses a static variable or a global variable, or a dynamically-allocated object that it finds for itself, then it is non-reentrant and any two calls to the function can interfere. For example, suppose that the signal handler uses gethostbyname. This function returns its value in a static object, reusing the same object each time. If the signal happens to arrive during a call to gethostbyname, or even after one (while the program is still using the value), it will clobber the value that the program asked for. However, if the program does not use gethostbyname or any other function that returns information in the same object, or if it always blocks signals around each use, then you are safe. There are a large number of library functions that return values in a fixed object, always reusing the same object in this fashion, and all of them cause the same problem. Function descriptions in this manual always mention this behavior.
If a function uses and modifies an object that you supply, then it is potentially non-reentrant; two calls can interfere if they use the same object. This case arises when you do I/O using streams. Suppose that the signal handler prints a message with fprintf. Suppose that the program was in the middle of an fprintf call using the same stream when the signal was delivered. Both the signal handler's message and the program's data could be corrupted, because both calls operate on the same data structure--the stream itself. However, if you know that the stream that the handler uses cannot possibly be used by the program at a time when signals can arrive, then you are safe. It is no problem if the program uses some other stream.
On most systems, malloc and free are not reentrant, because they use a static data structure which records what memory blocks are free. As a result, no library functions that allocate or free memory are reentrant. This includes functions that allocate space to store a result. The best way to avoid the need to allocate memory in a handler is to allocate in advance space for signal handlers to use. The best way to avoid freeing memory in a handler is to flag or record the objects to be freed, and have the program check from time to time whether anything is waiting to be freed. But this must be done with care, because placing an object on a chain is not atomic, and if it is interrupted by another signal handler that does the same thing, you could "lose" one of the objects.
Any function that modifies errno is non-reentrant, but you can correct for this: in the handler, save the original value of errno and restore it before returning normally. This prevents errors that occur within the signal handler from being confused with errors from system calls at the point the program is interrupted to run the handler. This technique is generally applicable; if you want to call in a handler a function that modifies a particular object in memory, you can make this safe by saving and restoring that object.
Merely reading from a memory object is safe provided that you can deal with any of the values that might appear in the object at a time when the signal can be delivered. Keep in mind that assignment to some data types requires more than one instruction, which means that the handler could run "in the middle of" an assignment to the variable if its type is not atomic. See section Atomic Data Access and Signal Handling.
Merely writing into a memory object is safe as long as a sudden change in the value, at any time when the handler might run, will not disturb anything.

Atomic Data Access and Signal Handling

Whether the data in your application concerns atoms, or mere text, you have to be careful about the fact that access to a single datum is not necessarily atomic. This means that it can take more than one instruction to read or write a single object. In such cases, a signal handler might be invoked in the middle of reading or writing the object.

There are three ways you can cope with this problem. You can use data types that are always accessed atomically; you can carefully arrange that nothing untoward happens if an access is interrupted, or you can block all signals around any access that had better not be interrupted (see section Blocking Signals).

Problems with Non-Atomic Access

Here is an example which shows what can happen if a signal handler runs in the middle of modifying a variable. (Interrupting the reading of a variable can also lead to paradoxical results, but here we only show writing.)
#include <signal.h>
#include <stdio.h>

struct two_words { int a, b; } memory;

void
handler(int signum)
{
   printf ("%d,%d\n", memory.a, memory.b);
   alarm (1);
}

int
main (void)
{
   static struct two_words zeros = { 0, 0 }, ones = { 1, 1 };
   signal (SIGALRM, handler);
   memory = zeros;
   alarm (1);
   while (1)
     {
       memory = zeros;
       memory = ones;
     }
}
This program fills memory with zeros, ones, zeros, ones, alternating forever; meanwhile, once per second, the alarm signal handler prints the current contents. (Calling printf in the handler is safe in this program because it is certainly not being called outside the handler when the signal happens.)

Clearly, this program can print a pair of zeros or a pair of ones. But that's not all it can do! On most machines, it takes several instructions to store a new value in memory, and the value is stored one word at a time. If the signal is delivered in between these instructions, the handler might find that memory.a is zero and memory.b is one (or vice versa).

On some machines it may be possible to store a new value in memory with just one instruction that cannot be interrupted. On these machines, the handler will always print two zeros or two ones.

Atomic Types

To avoid uncertainty about interrupting access to a variable, you can use a particular data type for which access is always atomic: sig_atomic_t. Reading and writing this data type is guaranteed to happen in a single instruction, so there's no way for a handler to run "in the middle" of an access.

The type sig_atomic_t is always an integer data type, but which one it is, and how many bits it contains, may vary from machine to machine.

Data Type: sig_atomic_t
This is an integer data type. Objects of this type are always accessed atomically.

In practice, you can assume that int and other integer types no longer than int are atomic. You can also assume that pointer types are atomic; that is very convenient. Both of these assumptions are true on all of the machines that the GNU C library supports and on all POSIX systems we know of.

Atomic Usage Patterns

Certain patterns of access avoid any problem even if an access is interrupted. For example, a flag which is set by the handler, and tested and cleared by the main program from time to time, is always safe even if access actually requires two instructions. To show that this is so, we must consider each access that could be interrupted, and show that there is no problem if it is interrupted.

An interrupt in the middle of testing the flag is safe because either it's recognized to be nonzero, in which case the precise value doesn't matter, or it will be seen to be nonzero the next time it's tested.

An interrupt in the middle of clearing the flag is no problem because either the value ends up zero, which is what happens if a signal comes in just before the flag is cleared, or the value ends up nonzero, and subsequent events occur as if the signal had come in just after the flag was cleared. As long as the code handles both of these cases properly, it can also handle a signal in the middle of clearing the flag. (This is an example of the sort of reasoning you need to do to figure out whether non-atomic usage is safe.)

Sometimes you can insure uninterrupted access to one object by protecting its use with another object, perhaps one whose type guarantees atomicity. See section Signals Close Together Merge into One, for an example.

Primitives Interrupted by Signals

A signal can arrive and be handled while an I/O primitive such as open or read is waiting for an I/O device. If the signal handler returns, the system faces the question: what should happen next?

POSIX specifies one approach: make the primitive fail right away. The error code for this kind of failure is EINTR. This is flexible, but usually inconvenient. Typically, POSIX applications that use signal handlers must check for EINTR after each library function that can return it, in order to try the call again. Often programmers forget to check, which is a common source of error.

The GNU library provides a convenient way to retry a call after a temporary failure, with the macro TEMP_FAILURE_RETRY:

Macro: TEMP_FAILURE_RETRY (expression)
This macro evaluates expression once. If it fails and reports error code EINTR, TEMP_FAILURE_RETRY evaluates it again, and over and over until the result is not a temporary failure.

The value returned by TEMP_FAILURE_RETRY is whatever value expression produced.

BSD avoids EINTR entirely and provides a more convenient approach: to restart the interrupted primitive, instead of making it fail. If you choose this approach, you need not be concerned with EINTR.

You can choose either approach with the GNU library. If you use sigaction to establish a signal handler, you can specify how that handler should behave. If you specify the SA_RESTART flag, return from that handler will resume a primitive; otherwise, return from that handler will cause EINTR. See section Flags for sigaction.

Another way to specify the choice is with the siginterrupt function. See section BSD Function to Establish a Handler.

When you don't specify with sigaction or siginterrupt what a particular handler should do, it uses a default choice. The default choice in the GNU library depends on the feature test macros you have defined. If you define _BSD_SOURCE or _GNU_SOURCE before calling signal, the default is to resume primitives; otherwise, the default is to make them fail with EINTR. (The library contains alternate versions of the signal function, and the feature test macros determine which one you really call.) See section Feature Test Macros.

The description of each primitive affected by this issue lists EINTR among the error codes it can return.

There is one situation where resumption never happens no matter which choice you make: when a data-transfer function such as read or write is interrupted by a signal after transferring part of the data. In this case, the function returns the number of bytes already transferred, indicating partial success.

This might at first appear to cause unreliable behavior on record-oriented devices (including datagram sockets; see section Datagram Socket Operations), where splitting one read or write into two would read or write two records. Actually, there is no problem, because interruption after a partial transfer cannot happen on such devices; they always transfer an entire record in one burst, with no waiting once data transfer has started.

Generating Signals

Besides signals that are generated as a result of a hardware trap or interrupt, your program can explicitly send signals to itself or to another process.

Signaling Yourself

A process can send itself a signal with the raise function. This function is declared in `signal.h'.

Function: int raise (int signum)
The raise function sends the signal signum to the calling process. It returns zero if successful and a nonzero value if it fails. About the only reason for failure would be if the value of signum is invalid.

Function: int gsignal (int signum)
The gsignal function does the same thing as raise; it is provided only for compatibility with SVID.

One convenient use for raise is to reproduce the default behavior of a signal that you have trapped. For instance, suppose a user of your program types the SUSP character (usually C-z; see section Special Characters) to send it an interactive stop signal (SIGTSTP), and you want to clean up some internal data buffers before stopping. You might set this up like this:
#include <signal.h>

/* When a stop signal arrives, set the action back to the default
   and then resend the signal after doing cleanup actions. */

void
tstp_handler (int sig)
{
  signal (SIGTSTP, SIG_DFL);
  /* Do cleanup actions here. */
  ...
  raise (SIGTSTP);
}

/* When the process is continued again, restore the signal handler. */

void
cont_handler (int sig)
{
  signal (SIGCONT, cont_handler);
  signal (SIGTSTP, tstp_handler);
}

/* Enable both handlers during program initialization. */

int
main (void)
{
  signal (SIGCONT, cont_handler);
  signal (SIGTSTP, tstp_handler);
  ...
}
Portability note: raise was invented by the ISO C committee. Older systems may not support it, so using kill may be more portable. See section Signaling Another Process.

Signaling Another Process

The kill function can be used to send a signal to another process. In spite of its name, it can be used for a lot of things other than causing a process to terminate. Some examples of situations where you might want to send signals between processes are:

A parent process starts a child to perform a task--perhaps having the child running an infinite loop--and then terminates the child when the task is no longer needed.
A process executes as part of a group, and needs to terminate or notify the other processes in the group when an error or other event occurs.
Two processes need to synchronize while working together.

This section assumes that you know a little bit about how processes work. For more information on this subject, see section Processes.

The kill function is declared in `signal.h'.

Function: int kill (pid_t pid, int signum)
The kill function sends the signal signum to the process or process group specified by pid. Besides the signals listed in section Standard Signals, signum can also have a value of zero to check the validity of the pid.

The pid specifies the process or process group to receive the signal:

pid > 0
The process whose identifier is pid.
pid == 0
All processes in the same process group as the sender.
pid < -1
The process group whose identifier is -pid.
pid == -1
If the process is privileged, send the signal to all processes except for some special system processes. Otherwise, send the signal to all processes with the same effective user ID.
A process can send a signal to itself with a call like kill (getpid(), signum). If kill is used by a process to send a signal to itself, and the signal is not blocked, then kill delivers at least one signal (which might be some other pending unblocked signal instead of the signal signum) to that process before it returns.

The return value from kill is zero if the signal can be sent successfully. Otherwise, no signal is sent, and a value of -1 is returned. If pid specifies sending a signal to several processes, kill succeeds if it can send the signal to at least one of them. There's no way you can tell which of the processes got the signal or whether all of them did.

The following errno error conditions are defined for this function:

EINVAL
The signum argument is an invalid or unsupported number.
EPERM
You do not have the privilege to send a signal to the process or any of the processes in the process group named by pid.
ESCRH
The pid argument does not refer to an existing process or group.

Function: int killpg (int pgid, int signum)
This is similar to kill, but sends signal signum to the process group pgid. This function is provided for compatibility with BSD; using kill to do this is more portable.

As a simple example of kill, the call kill (getpid (), sig) has the same effect as raise (sig).

Permission for using kill

There are restrictions that prevent you from using kill to send signals to any random process. These are intended to prevent antisocial behavior such as arbitrarily killing off processes belonging to another user. In typical use, kill is used to pass signals between parent, child, and sibling processes, and in these situations you normally do have permission to send signals. The only common exception is when you run a setuid program in a child process; if the program changes its real UID as well as its effective UID, you may not have permission to send a signal. The su program does this.

Whether a process has permission to send a signal to another process is determined by the user IDs of the two processes. This concept is discussed in detail in section The Persona of a Process.

Generally, for a process to be able to send a signal to another process, either the sending process must belong to a privileged user (like `root'), or the real or effective user ID of the sending process must match the real or effective user ID of the receiving process. If the receiving process has changed its effective user ID from the set-user-ID mode bit on its process image file, then the owner of the process image file is used in place of its current effective user ID. In some implementations, a parent process might be able to send signals to a child process even if the user ID's don't match, and other implementations might enforce other restrictions.

The SIGCONT signal is a special case. It can be sent if the sender is part of the same session as the receiver, regardless of user IDs.

Using kill for Communication

Here is a longer example showing how signals can be used for interprocess communication. This is what the SIGUSR1 and SIGUSR2 signals are provided for. Since these signals are fatal by default, the process that is supposed to receive them must trap them through signal or sigaction.

In this example, a parent process forks a child process and then waits for the child to complete its initialization. The child process tells the parent when it is ready by sending it a SIGUSR1 signal, using the kill function.
#include <signal.h>
#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>

/* When a SIGUSR1 signal arrives, set this variable. */
volatile sig_atomic_t usr_interrupt = 0;

void
synch_signal (int sig)
{
  usr_interrupt = 1;
}

/* The child process executes this function. */
void
child_function (void)
{
  /* Perform initialization. */
  printf ("I'm here!!!  My pid is %d.\n", (int) getpid ());

  /* Let parent know you're done. */
  kill (getppid (), SIGUSR1);

  /* Continue with execution. */
  puts ("Bye, now....");
  exit (0);
}

int
main (void)
{
  struct sigaction usr_action;
  sigset_t block_mask;
  pid_t child_id;

  /* Establish the signal handler. */
  sigfillset (&block_mask);
  usr_action.sa_handler = synch_signal;
  usr_action.sa_mask = block_mask;
  usr_action.sa_flags = 0;
  sigaction (SIGUSR1, &usr_action, NULL);

  /* Create the child process. */
  child_id = fork ();
  if (child_id == 0)
    child_function ();          /* Does not return. */

  /* Busy wait for the child to send a signal. */
  while (!usr_interrupt)
    ;

  /* Now continue execution. */
  puts ("That's all, folks!");

  return 0;
}
This example uses a busy wait, which is bad, because it wastes CPU cycles that other programs could otherwise use. It is better to ask the system to wait until the signal arrives. See the example in section Waiting for a Signal.

Blocking Signals

Blocking a signal means telling the operating system to hold it and deliver it later. Generally, a program does not block signals indefinitely--it might as well ignore them by setting their actions to SIG_IGN. But it is useful to block signals briefly, to prevent them from interrupting sensitive operations. For instance:

You can use the sigprocmask function to block signals while you modify global variables that are also modified by the handlers for these signals.
You can set sa_mask in your sigaction call to block certain signals while a particular signal handler runs. This way, the signal handler can run without being interrupted itself by signals.

Why Blocking Signals is Useful

Temporary blocking of signals with sigprocmask gives you a way to prevent interrupts during critical parts of your code. If signals arrive in that part of the program, they are delivered later, after you unblock them.

One example where this is useful is for sharing data between a signal handler and the rest of the program. If the type of the data is not sig_atomic_t (see section Atomic Data Access and Signal Handling), then the signal handler could run when the rest of the program has only half finished reading or writing the data. This would lead to confusing consequences.

To make the program reliable, you can prevent the signal handler from running while the rest of the program is examining or modifying that data--by blocking the appropriate signal around the parts of the program that touch the data.

Blocking signals is also necessary when you want to perform a certain action only if a signal has not arrived. Suppose that the handler for the signal sets a flag of type sig_atomic_t; you would like to test the flag and perform the action if the flag is not set. This is unreliable. Suppose the signal is delivered immediately after you test the flag, but before the consequent action: then the program will perform the action even though the signal has arrived.

The only way to test reliably for whether a signal has yet arrived is to test while the signal is blocked.

Signal Sets

All of the signal blocking functions use a data structure called a signal set to specify what signals are affected. Thus, every activity involves two stages: creating the signal set, and then passing it as an argument to a library function.

These facilities are declared in the header file `signal.h'.

Data Type: sigset_t
The sigset_t data type is used to represent a signal set. Internally, it may be implemented as either an integer or structure type.

For portability, use only the functions described in this section to initialize, change, and retrieve information from sigset_t objects--don't try to manipulate them directly.

There are two ways to initialize a signal set. You can initially specify it to be empty with sigemptyset and then add specified signals individually. Or you can specify it to be full with sigfillset and then delete specified signals individually.

You must always initialize the signal set with one of these two functions before using it in any other way. Don't try to set all the signals explicitly because the sigset_t object might include some other information (like a version field) that needs to be initialized as well. (In addition, it's not wise to put into your program an assumption that the system has no signals aside from the ones you know about.)

Function: int sigemptyset (sigset_t *set)
This function initializes the signal set set to exclude all of the defined signals. It always returns 0.

Function: int sigfillset (sigset_t *set)
This function initializes the signal set set to include all of the defined signals. Again, the return value is 0.

Function: int sigaddset (sigset_t *set, int signum)
This function adds the signal signum to the signal set set. All sigaddset does is modify set; it does not block or unblock any signals.

The return value is 0 on success and -1 on failure. The following errno error condition is defined for this function:

EINVAL
The signum argument doesn't specify a valid signal.

Function: int sigdelset (sigset_t *set, int signum)
This function removes the signal signum from the signal set set. All sigdelset does is modify set; it does not block or unblock any signals. The return value and error conditions are the same as for sigaddset.

Finally, there is a function to test what signals are in a signal set:

Function: int sigismember (const sigset_t *set, int signum)
The sigismember function tests whether the signal signum is a member of the signal set set. It returns 1 if the signal is in the set, 0 if not, and -1 if there is an error.

The following errno error condition is defined for this function:

EINVAL
The signum argument doesn't specify a valid signal.
Process Signal Mask

The collection of signals that are currently blocked is called the signal mask. Each process has its own signal mask. When you create a new process (see section Creating a Process), it inherits its parent's mask. You can block or unblock signals with total flexibility by modifying the signal mask.

The prototype for the sigprocmask function is in `signal.h'.

Function: int sigprocmask (int how, const sigset_t *restrict set, sigset_t *restrict oldset)
The sigprocmask function is used to examine or change the calling process's signal mask. The how argument determines how the signal mask is changed, and must be one of the following values:

SIG_BLOCK
Block the signals in set---add them to the existing mask. In other words, the new mask is the union of the existing mask and set.
SIG_UNBLOCK
Unblock the signals in set---remove them from the existing mask.
SIG_SETMASK
Use set for the mask; ignore the previous value of the mask.
The last argument, oldset, is used to return information about the old process signal mask. If you just want to change the mask without looking at it, pass a null pointer as the oldset argument. Similarly, if you want to know what's in the mask without changing it, pass a null pointer for set (in this case the how argument is not significant). The oldset argument is often used to remember the previous signal mask in order to restore it later. (Since the signal mask is inherited over fork and exec calls, you can't predict what its contents are when your program starts running.)

If invoking sigprocmask causes any pending signals to be unblocked, at least one of those signals is delivered to the process before sigprocmask returns. The order in which pending signals are delivered is not specified, but you can control the order explicitly by making multiple sigprocmask calls to unblock various signals one at a time.

The sigprocmask function returns 0 if successful, and -1 to indicate an error. The following errno error conditions are defined for this function:

EINVAL
The how argument is invalid.
You can't block the SIGKILL and SIGSTOP signals, but if the signal set includes these, sigprocmask just ignores them instead of returning an error status.

Remember, too, that blocking program error signals such as SIGFPE leads to undesirable results for signals generated by an actual program error (as opposed to signals sent with raise or kill). This is because your program may be too broken to be able to continue executing to a point where the signal is unblocked again. See section Program Error Signals.

Blocking to Test for Delivery of a Signal

Now for a simple example. Suppose you establish a handler for SIGALRM signals that sets a flag whenever a signal arrives, and your main program checks this flag from time to time and then resets it. You can prevent additional SIGALRM signals from arriving in the meantime by wrapping the critical part of the code with calls to sigprocmask, like this:
/* This variable is set by the SIGALRM signal handler. */
volatile sig_atomic_t flag = 0;

int
main (void)
{
  sigset_t block_alarm;

  ...

  /* Initialize the signal mask. */
  sigemptyset (&block_alarm);
  sigaddset (&block_alarm, SIGALRM);

  while (1)
    {
      /* Check if a signal has arrived; if so, reset the flag. */
      sigprocmask (SIG_BLOCK, &block_alarm, NULL);
      if (flag)
        {
          actions-if-not-arrived
          flag = 0;
        }
      sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);

      ...
    }
}
Blocking Signals for a Handler

When a signal handler is invoked, you usually want it to be able to finish without being interrupted by another signal. From the moment the handler starts until the moment it finishes, you must block signals that might confuse it or corrupt its data.

When a handler function is invoked on a signal, that signal is automatically blocked (in addition to any other signals that are already in the process's signal mask) during the time the handler is running. If you set up a handler for SIGTSTP, for instance, then the arrival of that signal forces further SIGTSTP signals to wait during the execution of the handler.

However, by default, other kinds of signals are not blocked; they can arrive during handler execution.

The reliable way to block other kinds of signals during the execution of the handler is to use the sa_mask member of the sigaction structure.

Here is an example:
#include <signal.h>
#include <stddef.h>

void catch_stop ();

void
install_handler (void)
{
  struct sigaction setup_action;
  sigset_t block_mask;

  sigemptyset (&block_mask);
  /* Block other terminal-generated signals while handler runs. */
  sigaddset (&block_mask, SIGINT);
  sigaddset (&block_mask, SIGQUIT);
  setup_action.sa_handler = catch_stop;
  setup_action.sa_mask = block_mask;
  setup_action.sa_flags = 0;
  sigaction (SIGTSTP, &setup_action, NULL);
}
This is more reliable than blocking the other signals explicitly in the code for the handler. If you block signals explicitly in the handler, you can't avoid at least a short interval at the beginning of the handler where they are not yet blocked.

You cannot remove signals from the process's current mask using this mechanism. However, you can make calls to sigprocmask within your handler to block or unblock signals as you wish.

In any case, when the handler returns, the system restores the mask that was in place before the handler was entered. If any signals that become unblocked by this restoration are pending, the process will receive those signals immediately, before returning to the code that was interrupted.

Checking for Pending Signals

You can find out which signals are pending at any time by calling sigpending. This function is declared in `signal.h'.

Function: int sigpending (sigset_t *set)
The sigpending function stores information about pending signals in set. If there is a pending signal that is blocked from delivery, then that signal is a member of the returned set. (You can test whether a particular signal is a member of this set using sigismember; see section Signal Sets.)

The return value is 0 if successful, and -1 on failure.

Testing whether a signal is pending is not often useful. Testing when that signal is not blocked is almost certainly bad design.

Here is an example.
#include <signal.h>
#include <stddef.h>

sigset_t base_mask, waiting_mask;

sigemptyset (&base_mask);
sigaddset (&base_mask, SIGINT);
sigaddset (&base_mask, SIGTSTP);

/* Block user interrupts while doing other processing. */
sigprocmask (SIG_SETMASK, &base_mask, NULL);
...

/* After a while, check to see whether any signals are pending. */
sigpending (&waiting_mask);
if (sigismember (&waiting_mask, SIGINT)) {
  /* User has tried to kill the process. */
}
else if (sigismember (&waiting_mask, SIGTSTP)) {
  /* User has tried to stop the process. */
}
Remember that if there is a particular signal pending for your process, additional signals of that same type that arrive in the meantime might be discarded. For example, if a SIGINT signal is pending when another SIGINT signal arrives, your program will probably only see one of them when you unblock this signal.

Portability Note: The sigpending function is new in POSIX.1. Older systems have no equivalent facility.

Remembering a Signal to Act On Later

Instead of blocking a signal using the library facilities, you can get almost the same results by making the handler set a flag to be tested later, when you "unblock". Here is an example:
/* If this flag is nonzero, don't handle the signal right away. */
volatile sig_atomic_t signal_pending;

/* This is nonzero if a signal arrived and was not handled. */
volatile sig_atomic_t defer_signal;

void
handler (int signum)
{
  if (defer_signal)
    signal_pending = signum;
  else
    ... /* "Really" handle the signal. */
}

...

void
update_mumble (int frob)
{
  /* Prevent signals from having immediate effect. */
  defer_signal++;
  /* Now update mumble, without worrying about interruption. */
  mumble.a = 1;
  mumble.b = hack ();
  mumble.c = frob;
  /* We have updated mumble.  Handle any signal that came in. */
  defer_signal--;
  if (defer_signal == 0 && signal_pending != 0)
    raise (signal_pending);
}
Note how the particular signal that arrives is stored in signal_pending. That way, we can handle several types of inconvenient signals with the same mechanism.

We increment and decrement defer_signal so that nested critical sections will work properly; thus, if update_mumble were called with signal_pending already nonzero, signals would be deferred not only within update_mumble, but also within the caller. This is also why we do not check signal_pending if defer_signal is still nonzero.

The incrementing and decrementing of defer_signal each require more than one instruction; it is possible for a signal to happen in the middle. But that does not cause any problem. If the signal happens early enough to see the value from before the increment or decrement, that is equivalent to a signal which came before the beginning of the increment or decrement, which is a case that works properly.

It is absolutely vital to decrement defer_signal before testing signal_pending, because this avoids a subtle bug. If we did these things in the other order, like this,
  if (defer_signal == 1 && signal_pending != 0)
    raise (signal_pending);
  defer_signal--;
then a signal arriving in between the if statement and the decrement would be effectively "lost" for an indefinite amount of time. The handler would merely set defer_signal, but the program having already tested this variable, it would not test the variable again.

Bugs like these are called timing errors. They are especially bad because they happen only rarely and are nearly impossible to reproduce. You can't expect to find them with a debugger as you would find a reproducible bug. So it is worth being especially careful to avoid them.

(You would not be tempted to write the code in this order, given the use of defer_signal as a counter which must be tested along with signal_pending. After all, testing for zero is cleaner than testing for one. But if you did not use defer_signal as a counter, and gave it values of zero and one only, then either order might seem equally simple. This is a further advantage of using a counter for defer_signal: it will reduce the chance you will write the code in the wrong order and create a subtle bug.)

Waiting for a Signal

If your program is driven by external events, or uses signals for synchronization, then when it has nothing to do it should probably wait until a signal arrives.

Using pause

The simple way to wait until a signal arrives is to call pause. Please read about its disadvantages, in the following section, before you use it.

Function: int pause ()
The pause function suspends program execution until a signal arrives whose action is either to execute a handler function, or to terminate the process.

If the signal causes a handler function to be executed, then pause returns. This is considered an unsuccessful return (since "successful" behavior would be to suspend the program forever), so the return value is -1. Even if you specify that other primitives should resume when a system handler returns (see section Primitives Interrupted by Signals), this has no effect on pause; it always fails when a signal is handled.

The following errno error conditions are defined for this function:

EINTR
The function was interrupted by delivery of a signal.
If the signal causes program termination, pause doesn't return (obviously).

This function is a cancellation point in multithreaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time pause is called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this calls to pause should be protected using cancellation handlers.

The pause function is declared in `unistd.h'.

Problems with pause

The simplicity of pause can conceal serious timing errors that can make a program hang mysteriously.

It is safe to use pause if the real work of your program is done by the signal handlers themselves, and the "main program" does nothing but call pause. Each time a signal is delivered, the handler will do the next batch of work that is to be done, and then return, so that the main loop of the program can call pause again.

You can't safely use pause to wait until one more signal arrives, and then resume real work. Even if you arrange for the signal handler to cooperate by setting a flag, you still can't use pause reliably. Here is an example of this problem:
/* usr_interrupt is set by the signal handler.  */
if (!usr_interrupt)
  pause ();

/* Do work once the signal arrives.  */
...
This has a bug: the signal could arrive after the variable usr_interrupt is checked, but before the call to pause. If no further signals arrive, the process would never wake up again.

You can put an upper limit on the excess waiting by using sleep in a loop, instead of using pause. (See section Sleeping, for more about sleep.) Here is what this looks like:
/* usr_interrupt is set by the signal handler.
while (!usr_interrupt)
  sleep (1);

/* Do work once the signal arrives.  */
...
For some purposes, that is good enough. But with a little more complexity, you can wait reliably until a particular signal handler is run, using sigsuspend.

Using sigsuspend

The clean and reliable way to wait for a signal to arrive is to block it and then use sigsuspend. By using sigsuspend in a loop, you can wait for certain kinds of signals, while letting other kinds of signals be handled by their handlers.

Function: int sigsuspend (const sigset_t *set)
This function replaces the process's signal mask with set and then suspends the process until a signal is delivered whose action is either to terminate the process or invoke a signal handling function. In other words, the program is effectively suspended until one of the signals that is not a member of set arrives.

If the process is woken up by delivery of a signal that invokes a handler function, and the handler function returns, then sigsuspend also returns.

The mask remains set only as long as sigsuspend is waiting. The function sigsuspend always restores the previous signal mask when it returns.

The return value and error conditions are the same as for pause.

With sigsuspend, you can replace the pause or sleep loop in the previous section with something completely reliable:
sigset_t mask, oldmask;

...

/* Set up the mask of signals to temporarily block. */
sigemptyset (&mask);
sigaddset (&mask, SIGUSR1);

...

/* Wait for a signal to arrive. */
sigprocmask (SIG_BLOCK, &mask, &oldmask);
while (!usr_interrupt)
  sigsuspend (&oldmask);
sigprocmask (SIG_UNBLOCK, &mask, NULL);
This last piece of code is a little tricky. The key point to remember here is that when sigsuspend returns, it resets the process's signal mask to the original value, the value from before the call to sigsuspend---in this case, the SIGUSR1 signal is once again blocked. The second call to sigprocmask is necessary to explicitly unblock this signal.

One other point: you may be wondering why the while loop is necessary at all, since the program is apparently only waiting for one SIGUSR1 signal. The answer is that the mask passed to sigsuspend permits the process to be woken up by the delivery of other kinds of signals, as well--for example, job control signals. If the process is woken up by a signal that doesn't set usr_interrupt, it just suspends itself again until the "right" kind of signal eventually arrives.

This technique takes a few more lines of preparation, but that is needed just once for each kind of wait criterion you want to use. The code that actually waits is just four lines.

Using a Separate Signal Stack

A signal stack is a special area of memory to be used as the execution stack during signal handlers. It should be fairly large, to avoid any danger that it will overflow in turn; the macro SIGSTKSZ is defined to a canonical size for signal stacks. You can use malloc to allocate the space for the stack. Then call sigaltstack or sigstack to tell the system to use that space for the signal stack.

You don't need to write signal handlers differently in order to use a signal stack. Switching from one stack to the other happens automatically. (Some non-GNU debuggers on some machines may get confused if you examine a stack trace while a handler that uses the signal stack is running.)

There are two interfaces for telling the system to use a separate signal stack. sigstack is the older interface, which comes from 4.2 BSD. sigaltstack is the newer interface, and comes from 4.4 BSD. The sigaltstack interface has the advantage that it does not require your program to know which direction the stack grows, which depends on the specific machine and operating system.

Data Type: stack_t
This structure describes a signal stack. It contains the following members:

void *ss_sp
This points to the base of the signal stack.
size_t ss_size
This is the size (in bytes) of the signal stack which `ss_sp' points to. You should set this to however much space you allocated for the stack. There are two macros defined in `signal.h' that you should use in calculating this size:
SIGSTKSZ
This is the canonical size for a signal stack. It is judged to be sufficient for normal uses.
MINSIGSTKSZ
This is the amount of signal stack space the operating system needs just to implement signal delivery. The size of a signal stack must be greater than this. For most cases, just using SIGSTKSZ for ss_size is sufficient. But if you know how much stack space your program's signal handlers will need, you may want to use a different size. In this case, you should allocate MINSIGSTKSZ additional bytes for the signal stack and increase ss_size accordingly.
int ss_flags
This field contains the bitwise OR of these flags:
SS_DISABLE
This tells the system that it should not use the signal stack.
SS_ONSTACK
This is set by the system, and indicates that the signal stack is currently in use. If this bit is not set, then signals will be delivered on the normal user stack.

Function: int sigaltstack (const stack_t *restrict stack, stack_t *restrict oldstack)
The sigaltstack function specifies an alternate stack for use during signal handling. When a signal is received by the process and its action indicates that the signal stack is used, the system arranges a switch to the currently installed signal stack while the handler for that signal is executed.

If oldstack is not a null pointer, information about the currently installed signal stack is returned in the location it points to. If stack is not a null pointer, then this is installed as the new stack for use by signal handlers.

The return value is 0 on success and -1 on failure. If sigaltstack fails, it sets errno to one of these values:

EINVAL
You tried to disable a stack that was in fact currently in use.
ENOMEM
The size of the alternate stack was too small. It must be greater than MINSIGSTKSZ.
Here is the older sigstack interface. You should use sigaltstack instead on systems that have it.

Data Type: struct sigstack
This structure describes a signal stack. It contains the following members:

void *ss_sp
This is the stack pointer. If the stack grows downwards on your machine, this should point to the top of the area you allocated. If the stack grows upwards, it should point to the bottom.
int ss_onstack
This field is true if the process is currently using this stack.

Function: int sigstack (const struct sigstack *stack, struct sigstack *oldstack)
The sigstack function specifies an alternate stack for use during signal handling. When a signal is received by the process and its action indicates that the signal stack is used, the system arranges a switch to the currently installed signal stack while the handler for that signal is executed.

If oldstack is not a null pointer, information about the currently installed signal stack is returned in the location it points to. If stack is not a null pointer, then this is installed as the new stack for use by signal handlers.

The return value is 0 on success and -1 on failure.

BSD Signal Handling

This section describes alternative signal handling functions derived from BSD Unix. These facilities were an advance, in their time; today, they are mostly obsolete, and supported mainly for compatibility with BSD Unix.

There are many similarities between the BSD and POSIX signal handling facilities, because the POSIX facilities were inspired by the BSD facilities. Besides having different names for all the functions to avoid conflicts, the main differences between the two are:

BSD Unix represents signal masks as an int bit mask, rather than as a sigset_t object.
The BSD facilities use a different default for whether an interrupted primitive should fail or resume. The POSIX facilities make system calls fail unless you specify that they should resume. With the BSD facility, the default is to make system calls resume unless you say they should fail. See section Primitives Interrupted by Signals.

The BSD facilities are declared in `signal.h'.

BSD Function to Establish a Handler

Data Type: struct sigvec
This data type is the BSD equivalent of struct sigaction (see section Advanced Signal Handling); it is used to specify signal actions to the sigvec function. It contains the following members:

sighandler_t sv_handler
This is the handler function.
int sv_mask
This is the mask of additional signals to be blocked while the handler function is being called.
int sv_flags
This is a bit mask used to specify various flags which affect the behavior of the signal. You can also refer to this field as sv_onstack.
These symbolic constants can be used to provide values for the sv_flags field of a sigvec structure. This field is a bit mask value, so you bitwise-OR the flags of interest to you together.

Macro: int SV_ONSTACK
If this bit is set in the sv_flags field of a sigvec structure, it means to use the signal stack when delivering the signal.

Macro: int SV_INTERRUPT
If this bit is set in the sv_flags field of a sigvec structure, it means that system calls interrupted by this kind of signal should not be restarted if the handler returns; instead, the system calls should return with a EINTR error status. See section Primitives Interrupted by Signals.

Macro: int SV_RESETHAND
If this bit is set in the sv_flags field of a sigvec structure, it means to reset the action for the signal back to SIG_DFL when the signal is received.

Function: int sigvec (int signum, const struct sigvec *action,struct sigvec *old-action)
This function is the equivalent of sigaction (see section Advanced Signal Handling); it installs the action action for the signal signum, returning information about the previous action in effect for that signal in old-action.

Function: int siginterrupt (int signum, int failflag)
This function specifies which approach to use when certain primitives are interrupted by handling signal signum. If failflag is false, signal signum restarts primitives. If failflag is true, handling signum causes these primitives to fail with error code EINTR. See section Primitives Interrupted by Signals.

BSD Functions for Blocking Signals

Macro: int sigmask (int signum)
This macro returns a signal mask that has the bit for signal signum set. You can bitwise-OR the results of several calls to sigmask together to specify more than one signal. For example,
(sigmask (SIGTSTP) | sigmask (SIGSTOP)
 | sigmask (SIGTTIN) | sigmask (SIGTTOU))
specifies a mask that includes all the job-control stop signals.

Function: int sigblock (int mask)
This function is equivalent to sigprocmask (see section Process Signal Mask) with a how argument of SIG_BLOCK: it adds the signals specified by mask to the calling process's set of blocked signals. The return value is the previous set of blocked signals.

Function: int sigsetmask (int mask)
This function equivalent to sigprocmask (see section Process Signal Mask) with a how argument of SIG_SETMASK: it sets the calling process's signal mask to mask. The return value is the previous set of blocked signals.

Function: int sigpause (int mask)
This function is the equivalent of sigsuspend (see section Waiting for a Signal): it sets the calling process's signal mask to mask, and waits for a signal to arrive. On return the previous set of blocked signals is restored.
The Basic Program/System Interface

Processes are the primitive units for allocation of system resources. Each process has its own address space and (usually) one thread of control. A process executes a program; you can have multiple processes executing the same program, but each process has its own copy of the program within its own address space and executes it independently of the other copies. Though it may have multiple threads of control within the same program and a program may be composed of multiple logically separate modules, a process always executes exactly one program.

Note that we are using a specific definition of "program" for the purposes of this manual, which corresponds to a common definition in the context of Unix system. In popular usage, "program" enjoys a much broader definition; it can refer for example to a system's kernel, an editor macro, a complex package of software, or a discrete section of code executing within a process.

Writing the program is what this manual is all about. This chapter explains the most basic interface between your program and the system that runs, or calls, it. This includes passing of parameters (arguments and environment) from the system, requesting basic services from the system, and telling the system the program is done.

A program starts another program with the exec family of system calls. This chapter looks at program startup from the execee's point of view. To see the event from the execor's point of view, See section Executing a File.

Program Arguments

The system starts a C program by calling the function main. It is up to you to write a function named main---otherwise, you won't even be able to link your program without errors.

In ISO C you can define main either to take no arguments, or to take two arguments that represent the command line arguments to the program, like this:
int main (int argc, char *argv[])
The command line arguments are the whitespace-separated tokens given in the shell command used to invoke the program; thus, in `cat foo bar', the arguments are `foo' and `bar'. The only way a program can look at its command line arguments is via the arguments of main. If main doesn't take arguments, then you cannot get at the command line.

The value of the argc argument is the number of command line arguments. The argv argument is a vector of C strings; its elements are the individual command line argument strings. The file name of the program being run is also included in the vector as the first element; the value of argc counts this element. A null pointer always follows the last element: argv[argc] is this null pointer.

For the command `cat foo bar', argc is 3 and argv has three elements, "cat", "foo" and "bar".

In Unix systems you can define main a third way, using three arguments:
int main (int argc, char *argv[], char *envp[])
The first two arguments are just the same. The third argument envp gives the program's environment; it is the same as the value of environ. See section Environment Variables. POSIX.1 does not allow this three-argument form, so to be portable it is best to write main to take two arguments, and use the value of environ.

Program Argument Syntax Conventions

POSIX recommends these conventions for command line arguments. getopt (see section Parsing program options using getopt) and argp_parse (see section Parsing Program Options with Argp) make it easy to implement them.

Arguments are options if they begin with a hyphen delimiter (`-').
Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, `-abc' is equivalent to `-a -b -c'.
Option names are single alphanumeric characters (as for isalnum; see section Classification of Characters).
Certain options require an argument. For example, the `-o' command of the ld command requires an argument--an output file name.
An option and its argument may or may not appear as separate tokens. (In other words, the whitespace separating them is optional.) Thus, `-o foo' and `-ofoo' are equivalent.
Options typically precede other non-option arguments. The implementations of getopt and argp_parse in the GNU C library normally make it appear as if all the option arguments were specified before all the non-option arguments for the purposes of parsing, even if the user of your program intermixed option and non-option arguments. They do this by reordering the elements of the argv array. This behavior is nonstandard; if you want to suppress it, define the _POSIX_OPTION_ORDER environment variable. See section Standard Environment Variables.
The argument `--' terminates all options; any following arguments are treated as non-option arguments, even if they begin with a hyphen.
A token consisting of a single hyphen character is interpreted as an ordinary non-option argument. By convention, it is used to specify input from or output to the standard input and output streams.
Options may be supplied in any order, or appear multiple times. The interpretation is left up to the particular application program.

GNU adds long options to these conventions. Long options consist of `--' followed by a name made of alphanumeric characters and dashes. Option names are typically one to three words long, with hyphens to separate words. Users can abbreviate the option names as long as the abbreviations are unique.

To specify an argument for a long option, write `--name=value'. This syntax enables a long option to accept an argument that is itself optional.

Eventually, the GNU system will provide completion for long option names in the shell.

Parsing Program Arguments

If the syntax for the command line arguments to your program is simple enough, you can simply pick the arguments off from argv by hand. But unless your program takes a fixed number of arguments, or all of the arguments are interpreted in the same way (as file names, for example), you are usually better off using getopt (see section Parsing program options using getopt) or argp_parse (see section Parsing Program Options with Argp) to do the parsing.

getopt is more standard (the short-option only version of it is a part of the POSIX standard), but using argp_parse is often easier, both for very simple and very complex option structures, because it does more of the dirty work for you.

Parsing program options using getopt

The getopt and getopt_long functions automate some of the chore involved in parsing typical unix command line options.

Using the getopt function

Here are the details about how to call the getopt function. To use this facility, your program must include the header file `unistd.h'.

Variable: int opterr
If the value of this variable is nonzero, then getopt prints an error message to the standard error stream if it encounters an unknown option character or an option with a missing required argument. This is the default behavior. If you set this variable to zero, getopt does not print any messages, but it still returns the character ? to indicate an error.

Variable: int optopt
When getopt encounters an unknown option character or an option with a missing required argument, it stores that option character in this variable. You can use this for providing your own diagnostic messages.

Variable: int optind
This variable is set by getopt to the index of the next element of the argv array to be processed. Once getopt has found all of the option arguments, you can use this variable to determine where the remaining non-option arguments begin. The initial value of this variable is 1.

Variable: char * optarg
This variable is set by getopt to point at the value of the option argument, for those options that accept arguments.

Function: int getopt (int argc, char **argv, const char *options)
The getopt function gets the next option argument from the argument list specified by the argv and argc arguments. Normally these values come directly from the arguments received by main.

The options argument is a string that specifies the option characters that are valid for this program. An option character in this string can be followed by a colon (`:') to indicate that it takes a required argument. If an option character is followed by two colons (`::'), its argument is optional; this is a GNU extension.

getopt has three ways to deal with options that follow non-options argv elements. The special argument `--' forces in all cases the end of option scanning.

The default is to permute the contents of argv while scanning it so that eventually all the non-options are at the end. This allows options to be given in any order, even with programs that were not written to expect this.
If the options argument string begins with a hyphen (`-'), this is treated specially. It permits arguments that are not options to be returned as if they were associated with option character `\1'.
POSIX demands the following behaviour: The first non-option stops option processing. This mode is selected by either setting the environment variable POSIXLY_CORRECT or beginning the options argument string with a plus sign (`+').

The getopt function returns the option character for the next command line option. When no more option arguments are available, it returns -1. There may still be more non-option arguments; you must compare the external variable optind against the argc parameter to check this.

If the option has an argument, getopt returns the argument by storing it in the variable optarg. You don't ordinarily need to copy the optarg string, since it is a pointer into the original argv array, not into a static area that might be overwritten.

If getopt finds an option character in argv that was not included in options, or a missing option argument, it returns `?' and sets the external variable optopt to the actual option character. If the first character of options is a colon (`:'), then getopt returns `:' instead of `?' to indicate a missing option argument. In addition, if the external variable opterr is nonzero (which is the default), getopt prints an error message.

Example of Parsing Arguments with getopt

Here is an example showing how getopt is typically used. The key points to notice are:

Normally, getopt is called in a loop. When getopt returns -1, indicating no more options are present, the loop terminates.
A switch statement is used to dispatch on the return value from getopt. In typical use, each case just sets a variable that is used later in the program.
A second loop is used to process the remaining non-option arguments.
#include <unistd.h>
#include <stdio.h>

int
main (int argc, char **argv)
{
  int aflag = 0;
  int bflag = 0;
  char *cvalue = NULL;
  int index;
  int c;

  opterr = 0;

  while ((c = getopt (argc, argv, "abc:")) != -1)
    switch (c)
      {
      case 'a':
        aflag = 1;
        break;
      case 'b':
        bflag = 1;
        break;
      case 'c':
        cvalue = optarg;
        break;
      case '?':
        if (isprint (optopt))
          fprintf (stderr, "Unknown option `-%c'.\n", optopt);
        else
          fprintf (stderr,
                   "Unknown option character `\\x%x'.\n",
                   optopt);
        return 1;
      default:
        abort ();
      }

  printf ("aflag = %d, bflag = %d, cvalue = %s\n",
          aflag, bflag, cvalue);

  for (index = optind; index < argc; index++)
    printf ("Non-option argument %s\n", argv[index]);
  return 0;
}
Here are some examples showing what this program prints with different combinations of arguments:
% testopt
aflag = 0, bflag = 0, cvalue = (null)

% testopt -a -b
aflag = 1, bflag = 1, cvalue = (null)

% testopt -ab
aflag = 1, bflag = 1, cvalue = (null)

% testopt -c foo
aflag = 0, bflag = 0, cvalue = foo

% testopt -cfoo
aflag = 0, bflag = 0, cvalue = foo

% testopt arg1
aflag = 0, bflag = 0, cvalue = (null)
Non-option argument arg1

% testopt -a arg1
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument arg1

% testopt -c foo arg1
aflag = 0, bflag = 0, cvalue = foo
Non-option argument arg1

% testopt -a -- -b
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument -b

% testopt -a -
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument -
Parsing Long Options with getopt_long

To accept GNU-style long options as well as single-character options, use getopt_long instead of getopt. This function is declared in `getopt.h', not `unistd.h'. You should make every program accept long options if it uses any options, for this takes little extra work and helps beginners remember how to use the program.

Data Type: struct option
This structure describes a single long option name for the sake of getopt_long. The argument longopts must be an array of these structures, one for each long option. Terminate the array with an element containing all zeros.

The struct option structure has these fields:

const char *name
This field is the name of the option. It is a string.
int has_arg
This field says whether the option takes an argument. It is an integer, and there are three legitimate values: no_argument, required_argument and optional_argument.
int *flag

int val
These fields control how to report or act on the option when it occurs. If flag is a null pointer, then the val is a value which identifies this option. Often these values are chosen to uniquely identify particular long options. If flag is not a null pointer, it should be the address of an int variable which is the flag for this option. The value in val is the value to store in the flag to indicate that the option was seen.

Function: int getopt_long (int argc, char *const *argv, const char *shortopts, struct option *longopts, int *indexptr)
Decode options from the vector argv (whose length is argc). The argument shortopts describes the short options to accept, just as it does in getopt. The argument longopts describes the long options to accept (see above).

When getopt_long encounters a short option, it does the same thing that getopt would do: it returns the character code for the option, and stores the options argument (if it has one) in optarg.

When getopt_long encounters a long option, it takes actions based on the flag and val fields of the definition of that option.

If flag is a null pointer, then getopt_long returns the contents of val to indicate which option it found. You should arrange distinct values in the val field for options with different meanings, so you can decode these values after getopt_long returns. If the long option is equivalent to a short option, you can use the short option's character code in val.

If flag is not a null pointer, that means this option should just set a flag in the program. The flag is a variable of type int that you define. Put the address of the flag in the flag field. Put in the val field the value you would like this option to store in the flag. In this case, getopt_long returns 0.

For any long option, getopt_long tells you the index in the array longopts of the options definition, by storing it into *indexptr. You can get the name of the option with longopts[*indexptr].name. So you can distinguish among long options either by the values in their val fields or by their indices. You can also distinguish in this way among long options that set flags.

When a long option has an argument, getopt_long puts the argument value in the variable optarg before returning. When the option has no argument, the value in optarg is a null pointer. This is how you can tell whether an optional argument was supplied.

When getopt_long has no more options to handle, it returns -1, and leaves in the variable optind the index in argv of the next remaining argument.

Since long option names were used before before the getopt_long options was invented there are program interfaces which require programs to recognize options like `-option value' instead of `--option value'. To enable these programs to use the GNU getopt functionality there is one more function available.

Function: int getopt_long_only (int argc, char *const *argv, const char *shortopts, struct option *longopts, int *indexptr)

The getopt_long_only function is equivalent to the getopt_long function but it allows to specify the user of the application to pass long options with only `-' instead of `--'. The `--' prefix is still recognized but instead of looking through the short options if a `-' is seen it is first tried whether this parameter names a long option. If not, it is parsed as a short option.

Assuming getopt_long_only is used starting an application with
  app -foo
the getopt_long_only will first look for a long option named `foo'. If this is not found, the short options `f', `o', and again `o' are recognized.

Example of Parsing Long Options with getopt_long
#include <stdio.h>
#include <stdlib.h>
#include <getopt.h>

/* Flag set by `--verbose'. */
static int verbose_flag;

int
main (argc, argv)
     int argc;
     char **argv;
{
  int c;

  while (1)
    {
      static struct option long_options[] =
        {
          /* These options set a flag. */
          {"verbose", no_argument,       &verbose_flag, 1},
          {"brief",   no_argument,       &verbose_flag, 0},
          /* These options don't set a flag.
             We distinguish them by their indices. */
          {"add",     required_argument, 0, 'a'},
          {"append",  no_argument,       0, 'b'},
          {"delete",  required_argument, 0, 'd'},
          {"create",  no_argument,       0, 'c'},
          {"file",    required_argument, 0, 'f'},
          {0, 0, 0, 0}
        };
      /* getopt_long stores the option index here. */
      int option_index = 0;

      c = getopt_long (argc, argv, "abc:d:f:",
                       long_options, &option_index);

      /* Detect the end of the options. */
      if (c == -1)
        break;

      switch (c)
        {
        case 0:
          /* If this option set a flag, do nothing else now. */
          if (long_options[option_index].flag != 0)
            break;
          printf ("option %s", long_options[option_index].name);
          if (optarg)
            printf (" with arg %s", optarg);
          printf ("\n");
          break;

        case 'a':
          puts ("option -a\n");
          break;

        case 'b':
          puts ("option -b\n");
          break;

        case 'c':
          printf ("option -c with value `%s'\n", optarg);
          break;

        case 'd':
          printf ("option -d with value `%s'\n", optarg);
          break;

        case 'f':
          printf ("option -f with value `%s'\n", optarg);
          break;

        case '?':
          /* getopt_long already printed an error message. */
          break;

        default:
          abort ();
        }
    }

  /* Instead of reporting `--verbose'
     and `--brief' as they are encountered,
     we report the final status resulting from them. */
  if (verbose_flag)
    puts ("verbose flag is set");

  /* Print any remaining command line arguments (not options). */
  if (optind < argc)
    {
      printf ("non-option ARGV-elements: ");
      while (optind < argc)
        printf ("%s ", argv[optind++]);
      putchar ('\n');
    }

  exit (0);
}
Parsing Program Options with Argp

Argp is an interface for parsing unix-style argument vectors (see section Program Arguments).

Unlike the more common getopt interface, it provides many related convenience features in addition to parsing options, such as automatically producing output in response to `--help' and `--version' options (as defined by the GNU coding standards). Doing these things in argp results in a more consistent look for programs that use it, and makes less likely that implementors will neglect to implement them or keep them up-to-date.

Argp also provides the ability to merge several independently defined option parsers into one, mediating conflicts between them, and making the result appear seamless. A library can export an argp option parser, which programs can easily use in conjunction with their own option parser. This results in less work for user programs (indeed, some may use only argument parsers exported by libraries, and have no options of their own), and more consistent option-parsing for the abstractions implemented by the library.

The header file `<argp.h>' should be included to use argp.

The argp_parse Function

The main interface to argp is the argp_parse function; often, a call to argp_parse is the only argument-parsing code needed in main (see section Program Arguments).

Function: error_t argp_parse (const struct argp *argp, int argc, char **argv, unsigned flags, int *arg_index, void *input)
The argp_parse function parses the arguments in argv, of length argc, using the argp parser argp (see section Specifying Argp Parsers); a value of zero is the same as a struct argp containing all zeros. flags is a set of flag bits that modify the parsing behavior (see section Flags for argp_parse). input is passed through to the argp parser argp, and has meaning defined by it; a typical usage is to pass a pointer to a structure which can be used for specifying parameters to the parser and passing back results from it.

Unless the ARGP_NO_EXIT or ARGP_NO_HELP flags are included in flags, calling argp_parse may result in the program exiting--for instance when an unknown option is encountered. See section Program Termination.

If arg_index is non-null, the index of the first unparsed option in argv is returned in it.

The return value is zero for successful parsing, or an error code (see section Error Codes) if an error was detected. Different argp parsers may return arbitrary error codes, but standard ones are ENOMEM if a memory allocation error occurred, or EINVAL if an unknown option or option argument was encountered.

Argp Global Variables

These variables make it very easy for every user program to implement the `--version' option and provide a bug-reporting address in the `--help' output (which is implemented by argp regardless).

Variable: const char * argp_program_version
If defined or set by the user program to a non-zero value, then a `--version' option is added when parsing with argp_parse (unless the ARGP_NO_HELP flag is used), which will print this string followed by a newline and exit (unless the ARGP_NO_EXIT flag is used).

Variable: const char * argp_program_bug_address
If defined or set by the user program to a non-zero value, argp_program_bug_address should point to a string that is the bug-reporting address for the program. It will be printed at the end of the standard output for the `--help' option, embedded in a sentence that says something like `Report bugs to address.'.

Variable: argp_program_version_hook
If defined or set by the user program to a non-zero value, then a `--version' option is added when parsing with argp_parse (unless the ARGP_NO_HELP flag is used), which calls this function to print the version, and then exits with a status of 0 (unless the ARGP_NO_EXIT flag is used). It should point to a function with the following type signature:
void print-version (FILE *stream, struct argp_state *state)
See section Argp Parsing State, for an explanation of state.

This variable takes precedent over argp_program_version, and is useful if a program has version information that cannot be easily specified as a simple string.

Variable: error_t argp_err_exit_status
The exit status that argp will use when exiting due to a parsing error. If not defined or set by the user program, this defaults to EX_USAGE from `<sysexits.h>'.

Specifying Argp Parsers

The first argument to the argp_parse function is a pointer to a struct argp, which known as an argp parser:

Data Type: struct argp
This structure specifies how to parse a given set of options and arguments, perhaps in conjunction with other argp parsers. It has the following fields:

const struct argp_option *options
A pointer to a vector of argp_option structures specifying which options this argp parser understands; it may be zero if there are no options at all. See section Specifying Options in an Argp Parser.
argp_parser_t parser
A pointer to a function that defines actions for this parser; it is called for each option parsed, and at other well-defined points in the parsing process. A value of zero is the same as a pointer to a function that always returns ARGP_ERR_UNKNOWN. See section Argp Parser Functions.
const char *args_doc
If non-zero, a string describing what non-option arguments are wanted by this parser; it is only used to print the `Usage:' message. If it contains newlines, the strings separated by them are considered alternative usage patterns, and printed on separate lines (lines after the first are prefixed by ` or: ' instead of `Usage:').
const char *doc
If non-zero, a string containing extra text to be printed before and after the options in a long help message, with the two sections separated by a vertical tab ('\v', '\013') character. By convention, the documentation before the options is just a short string saying what the program does, and that afterwards is longer, describing the behavior in more detail.
const struct argp_child *children
A pointer to a vector of argp_children structures specifying additional argp parsers that should be combined with this one. See section Combining Multiple Argp Parsers.
char *(*help_filter)(int key, const char *text, void *input)
If non-zero, a pointer to a function to filter the output of help messages. See section Customizing Argp Help Output.
const char *argp_domain
If non-zero, the strings used in the argp library are translated using the domain described by this string. Otherwise the currently installed default domain is used.
The options, parser, args_doc, and doc fields are usually all that are needed. If an argp parser is defined as an initialized C variable, only the used fields need be specified in the initializer--the rest will default to zero due to the way C structure initialization works (this fact is exploited for most argp structures, grouping the most-used fields near the beginning, so that unused fields can simply be left unspecified).

Specifying Options in an Argp Parser

The options field in a struct argp points to a vector of struct argp_option structures, each of which specifies an option that argp parser supports (actually, sometimes multiple entries may used for a single option if it has many names). It should be terminated by an entry with zero in all fields (note that when using an initialized C array for options, writing { 0 } is enough to achieve this).

Data Type: struct argp_option
This structure specifies a single option that an argp parser understands, and how to parse and document it. It has the following fields:

const char *name
The long name for this option, corresponding to the long option `--name'; this field can be zero if this option only has a short name. To specify multiple names for an option, additional entries may follow this one, with the OPTION_ALIAS flag set (see section Flags for Argp Options).
int key
The integer key that is provided to the argp parser's parsing function when this option is being parsed. Also, if key has a value that is a printable ASCII character (i.e., isascii (key) is true), it also specifies a short option `-char', where char is the ASCII character with the code key.
const char *arg
If non-zero, this is the name of an argument associated with this option, which must be provided (e.g., with the `--name=value' or `-char value' syntaxes) unless the OPTION_ARG_OPTIONAL flag (see section Flags for Argp Options) is set, in which case it may be provided.
int flags
Flags associated with this option (some of which are referred to above). See section Flags for Argp Options.
const char *doc
A documentation string for this option, for printing in help messages. If both the name and key fields are zero, this string will be printed out-dented from the normal option column, making it useful as a group header (it will be the first thing printed in its group); in this usage, it's conventional to end the string with a `:' character.
int group
The group this option is in. In a long help message, options are sorted alphabetically within each group, and the groups presented in the order 0, 1, 2, ..., n, -m, ..., -2, -1. Every entry in an options array with this field 0 will inherit the group number of the previous entry, or zero if it's the first one, unless its a group header (name and key fields both zero), in which case, the previous entry + 1 is the default. Automagic options such as `--help' are put into group -1. Note that because of C structure initialization rules, this field often need not be specified, because 0 is the right value.
Flags for Argp Options

The following flags may be or'd together in the flags field of a struct argp_option, and control various aspects of how that option is parsed or displayed in help messages:

OPTION_ARG_OPTIONAL
The argument associated with this option is optional.
OPTION_HIDDEN
This option isn't displayed in any help messages.
OPTION_ALIAS
This option is an alias for the closest previous non-alias option. This means that it will be displayed in the same help entry, and will inherit fields other than name and key from the aliased option.
OPTION_DOC
This option isn't actually an option (and so should be ignored by the actual option parser), but rather an arbitrary piece of documentation that should be displayed in much the same manner as the options (known as a documentation option). If this flag is set, then the option name field is displayed unmodified (e.g., no `--' prefix is added) at the left-margin (where a short option would normally be displayed), and the documentation string in the normal place. For purposes of sorting, any leading whitespace and punctuation is ignored, except that if the first non-whitespace character is not `-', this entry is displayed after all options (and OPTION_DOC entries with a leading `-') in the same group.
OPTION_NO_USAGE
This option shouldn't be included in `long' usage messages (but is still included in help messages). This is mainly intended for options that are completely documented in an argp's args_doc field (see section Specifying Argp Parsers), in which case including the option in the generic usage list would be redundant. For instance, if args_doc is "FOO BAR\n-x BLAH", and the `-x' option's purpose is to distinguish these two cases, `-x' should probably be marked OPTION_NO_USAGE.
Argp Parser Functions

The function pointed to by the parser field in a struct argp (see section Specifying Argp Parsers) defines what actions take place in response to each option or argument that is parsed, and is also used as a hook, to allow a parser to do something at certain other points during parsing.

Argp parser functions have the following type signature:
error_t parser (int key, char *arg, struct argp_state *state)
where the arguments are as follows:

key
For each option that is parsed, parser is called with a value of key from that option's key field in the option vector (see section Specifying Options in an Argp Parser). parser is also called at other times with special reserved keys, such as ARGP_KEY_ARG for non-option arguments. See section Special Keys for Argp Parser Functions.
arg
If key is an option, arg is the value given for it, or zero if no value was specified. Only options that have a non-zero arg field can ever have a value, and those must always have a value, unless the OPTION_ARG_OPTIONAL flag was specified (if the input being parsed specifies a value for an option that doesn't allow one, an error results before parser ever gets called). If key is ARGP_KEY_ARG, arg is a non-option argument; other special keys always have a zero arg.
state
state points to a struct argp_state, containing useful information about the current parsing state for use by parser. See section Argp Parsing State.
When parser is called, it should perform whatever action is appropriate for key, and return either 0 for success, ARGP_ERR_UNKNOWN, if the value of key is not handled by this parser function, or a unix error code if a real error occurred (see section Error Codes).

Macro: int ARGP_ERR_UNKNOWN
Argp parser functions should return ARGP_ERR_UNKNOWN for any key value they do not recognize, or for non-option arguments (key == ARGP_KEY_ARG) that they do not wish to handle.

A typical parser function uses a switch statement on key:
error_t
parse_opt (int key, char *arg, struct argp_state *state)
{
  switch (key)
    {
    case option_key:
      action
      break;
    ...
    default:
      return ARGP_ERR_UNKNOWN;
    }
  return 0;
}
Special Keys for Argp Parser Functions

In addition to key values corresponding to user options, the key argument to argp parser functions may have a number of other special values (arg and state refer to parser function arguments; see section Argp Parser Functions):

ARGP_KEY_ARG
This is not an option at all, but rather a command line argument, whose value is pointed to by arg. When there are multiple parser functions (due to argp parsers being combined), it's impossible to know which one wants to handle an argument, so each is called in turn, until one returns 0 or an error other than ARGP_ERR_UNKNOWN; if an argument is handled by no one, argp_parse immediately returns success, without parsing any more arguments. Once a parser function returns success for this key, that fact is recorded, and the ARGP_KEY_NO_ARGS case won't be used. However, if while processing the argument, a parser function decrements the next field of its state argument, the option won't be considered processed; this is to allow you to actually modify the argument (perhaps into an option), and have it processed again.
ARGP_KEY_ARGS
If a parser function returns ARGP_ERR_UNKNOWN for ARGP_KEY_ARG, it is immediately called again with the key ARGP_KEY_ARGS, which has a similar meaning, but is slightly more convenient for consuming all remaining arguments. arg is 0, and the tail of the argument vector may be found at state->argv + state->next. If success is returned for this key, and state->next is unchanged, then all remaining arguments are considered to have been consumed, otherwise, the amount by which state->next has been adjust indicates how many were used. For instance, here's an example that uses both, for different args:
...
case ARGP_KEY_ARG:
  if (state->arg_num == 0)
    /* First argument */
    first_arg = arg;
  else
    /* Let the next case parse it.  */
    return ARGP_KEY_UNKNOWN;
  break;
case ARGP_KEY_ARGS:
  remaining_args = state->argv + state->next;
  num_remaining_args = state->argc - state->next;
  break;
ARGP_KEY_END
There are no more command line arguments at all. The parser functions are called in different order (means children first) for this value which allows each parser to clean up its state for the parent.
ARGP_KEY_NO_ARGS
Because it's common to want to do some special processing if there aren't any non-option args, parser functions are called with this key if they didn't successfully process any non-option arguments. Called just before ARGP_KEY_END (where more general validity checks on previously parsed arguments can take place).
ARGP_KEY_INIT
Passed in before any parsing is done. Afterwards, the values of each element of the child_input field of state, if any, are copied to each child's state to be the initial value of the input when their parsers are called.
ARGP_KEY_SUCCESS
Passed in when parsing has successfully been completed (even if there are still arguments remaining).
ARGP_KEY_ERROR
Passed in if an error has occurred, and parsing terminated (in which case a call with a key of ARGP_KEY_SUCCESS is never made).
ARGP_KEY_FINI
The final key ever seen by any parser (even after ARGP_KEY_SUCCESS and ARGP_KEY_ERROR). Any resources allocated by ARGP_KEY_INIT may be freed here (although sometimes certain resources allocated there are to be returned to the caller after a successful parse; in that case, those particular resources can be freed in the ARGP_KEY_ERROR case).
In all cases, ARGP_KEY_INIT is the first key seen by parser functions, and ARGP_KEY_FINI the last (unless an error was returned by the parser for ARGP_KEY_INIT). Other keys can occur in one the following orders (opt refers to an arbitrary option key):

opt... ARGP_KEY_NO_ARGS ARGP_KEY_END ARGP_KEY_SUCCESS
The arguments being parsed contained no non-option arguments at all.
( opt | ARGP_KEY_ARG )... ARGP_KEY_END ARGP_KEY_SUCCESS
All non-option arguments were successfully handled by a parser function (there may be multiple parser functions if multiple argp parsers were combined).
( opt | ARGP_KEY_ARG )... ARGP_KEY_SUCCESS
Some non-option argument was unrecognized. This occurs when every parser function returns ARGP_KEY_UNKNOWN for an argument, in which case parsing stops at that argument. If arg_index is a null pointer otherwise an error occurs.
In all cases, if a non-null value for arg_index was passed to argp_parse, the index of the first unparsed command-line argument is passed back in it.

If an error occurs (either detected by argp, or because a parser function returned an error value), then each parser is called with ARGP_KEY_ERROR, and no further calls are made except the final call with ARGP_KEY_FINI.

Functions For Use in Argp Parsers

Argp provides a number of functions for the user of argp parser functions (see section Argp Parser Functions), mostly for producing error messages. These take as their first argument the state argument to the parser function (see section Argp Parsing State).

Function: void argp_usage (const struct argp_state *state)
Output the standard usage message for the argp parser referred to by state to state->err_stream and terminate the program with exit (argp_err_exit_status) (see section Argp Global Variables).

Function: void argp_error (const struct argp_state *state, const char *fmt, ...)
Print the printf format string fmt and following args, preceded by the program name and `:', and followed by a `Try ... --help' message, and terminate the program with an exit status of argp_err_exit_status (see section Argp Global Variables).

Function: void argp_failure (const struct argp_state *state, int status, int errnum, const char *fmt, ...)
Similarly to the standard gnu error-reporting function error, print the printf format string fmt and following args, preceded by the program name and `:', and followed by the standard unix error text for errnum if it is non-zero; then if status is non-zero, terminate the program with that as its exit status.

The difference between this function and argp_error is that argp_error is for parsing errors, whereas argp_failure is for other problems that occur during parsing but don't reflect a syntactic problem with the input--such as illegal values for options, bad phase of the moon, etc.

Function: void argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)
Output a help message for the argp parser referred to by state to stream. The flags argument determines what sort of help message is produced. See section Flags for the argp_help Function.

Error output is sent to state->err_stream, and the program name printed is state->name.

The output or program termination behavior of these functions may be suppressed if the ARGP_NO_EXIT or ARGP_NO_ERRS flags, respectively, were passed to argp_parse. See section Flags for argp_parse.

This behavior is useful if an argp parser is exported for use by other programs (e.g., by a library), and may be used in a context where it is not desirable to terminate the program in response to parsing errors. In argp parsers intended for such general use, calls to any of these functions should be followed by code return of an appropriate error code for the case where the program doesn't terminate; for example:
if (bad argument syntax)
  {
     argp_usage (state);
     return EINVAL;
  }
If it's known that a parser function will only be used when ARGP_NO_EXIT is not set, the return may be omitted.

Argp Parsing State

The third argument to argp parser functions (see section Argp Parser Functions) is a pointer to a struct argp_state, which contains information about the state of the option parsing.

Data Type: struct argp_state
This structure has the following fields, which may be modified as noted:

const struct argp *const root_argp
The top level argp parser being parsed. Note that this is often not the same struct argp passed into argp_parse by the invoking program (see section Parsing Program Options with Argp), but instead an internal argp parser that contains options implemented by argp_parse itself (such as `--help').
int argc

char **argv
The argument vector being parsed. May be modified.
int next
The index in argv of the next argument to be parsed. May be modified. One way to consume all remaining arguments in the input is to set state->next = state->argc (perhaps after recording the value of the next field to find the consumed arguments). Also, you can cause the current option to be re-parsed by decrementing this field, and then modifying state->argv[state->next] to be the option that should be reexamined.
unsigned flags
The flags supplied to argp_parse. May be modified, although some flags may only take effect when argp_parse is first invoked. See section Flags for argp_parse.
unsigned arg_num
While calling a parsing function with the key argument ARGP_KEY_ARG, this is the number of the current arg, starting at 0, and incremented after each such call returns. At all other times, this is the number of such arguments that have been processed.
int quoted
If non-zero, the index in argv of the first argument following a special `--' argument (which prevents anything following being interpreted as an option). Only set once argument parsing has proceeded past this point.
void *input
An arbitrary pointer passed in from the caller of argp_parse, in the input argument.
void **child_inputs
Values to pass to child parsers. This vector will be the same length as the number of children in the current parser, and each child parser will be given the value of state->child_inputs[i] as its state->input field, where i is the index of the child in the this parser's children field. See section Combining Multiple Argp Parsers.
void *hook
For the parser function's use. Initialized to 0, but otherwise ignored by argp.
char *name
The name used when printing messages. This is initialized to argv[0], or program_invocation_name if that is unavailable.
FILE *err_stream

FILE *out_stream
Stdio streams used when argp prints something; error messages are printed to err_stream, and all other output (such as `--help' output) to out_stream. These are initialized to stderr and stdout respectively (see section Standard Streams).
void *pstate
Private, for use by the argp implementation.
Combining Multiple Argp Parsers

The children field in a struct argp allows other argp parsers to be combined with the referencing one to parse a single set of arguments. It should point to a vector of struct argp_child, terminated by an entry having a value of zero in the argp field.

Where conflicts between combined parsers arise (for instance, if two specify an option with the same name), they are resolved in favor of the parent argp parsers, or earlier argp parsers in the list of children.

Data Type: struct argp_child
An entry in the list of subsidiary argp parsers pointed to by the children field in a struct argp. The fields are as follows:

const struct argp *argp
The child argp parser, or zero to end the list.
int flags
Flags for this child.
const char *header
If non-zero, an optional header to be printed in help output before the child options. As a side-effect, a non-zero value forces the child options to be grouped together; to achieve this effect without actually printing a header string, use a value of "". As with header strings specified in an option entry, the value conventionally has `:' as the last character. See section Specifying Options in an Argp Parser.
int group
Where to group the child options relative to the other (`consolidated') options in the parent argp parser. The values are the same as the group field in struct argp_option (see section Specifying Options in an Argp Parser), but all child-groupings follow parent options at a particular group level. If both this field and header are zero, then the child's options aren't grouped together at all, but rather merged with the parent options (merging the child's grouping levels with the parents).
Flags for argp_parse

The default behavior of argp_parse is designed to be convenient for the most common case of parsing program command line argument. To modify these defaults, the following flags may be or'd together in the flags argument to argp_parse:

ARGP_PARSE_ARGV0
Don't ignore the first element of the argv argument to argp_parse. Normally (and always unless ARGP_NO_ERRS is set) the first element of the argument vector is skipped for option parsing purposes, as it corresponds to the program name in a command line.
ARGP_NO_ERRS
Don't print error messages for unknown options to stderr; unless this flag is set, ARGP_PARSE_ARGV0 is ignored, as argv[0] is used as the program name in the error messages. This flag implies ARGP_NO_EXIT (on the assumption that silent exiting upon errors is bad behaviour).
ARGP_NO_ARGS
Don't parse any non-option args. Normally non-option args are parsed by calling the parse functions with a key of ARGP_KEY_ARG, and the actual arg as the value. This flag needn't normally be set, as the normal behavior is to stop parsing as soon as some argument isn't accepted by a parsing function. See section Argp Parser Functions.
ARGP_IN_ORDER
Parse options and arguments in the same order they occur on the command line--normally they're rearranged so that all options come first
ARGP_NO_HELP
Don't provide the standard long option `--help', which ordinarily causes usage and option help information to be output to stdout, and exit (0) called.
ARGP_NO_EXIT
Don't exit on errors (they may still result in error messages).
ARGP_LONG_ONLY
Use the gnu getopt `long-only' rules for parsing arguments. This allows long-options to be recognized with only a single `-' (for instances, `-help'), but results in a generally somewhat less useful interface, that conflicts with the way most GNU programs work. For this reason, its use is discouraged.
ARGP_SILENT
Turns off any message-printing/exiting options, specifically ARGP_NO_EXIT, ARGP_NO_ERRS, and ARGP_NO_HELP.
Customizing Argp Help Output

The help_filter field in a struct argp is a pointer to a function to filter the text of help messages before displaying them. They have a function signature like:
char *help-filter (int key, const char *text, void *input)
where key is either a key from an option, in which case text is that option's help text (see section Specifying Options in an Argp Parser), or one of the special keys with names beginning with `ARGP_KEY_HELP_', describing which other help text text is (see section Special Keys for Argp Help Filter Functions).

The function should return either text, if it should be used as-is, a replacement string, which should be allocated using malloc, and will be freed by argp, or zero, meaning `print nothing'. The value of text supplied is after any translation has been done, so if any of the replacement text also needs translation, that should be done by the filter function. input is either the input supplied to argp_parse, or zero, if argp_help was called directly by the user.

Special Keys for Argp Help Filter Functions

The following special values may be passed to an argp help filter function as the first argument, in addition to key values for user options, and specify which help text the text argument contains:

ARGP_KEY_HELP_PRE_DOC
Help text preceding options.
ARGP_KEY_HELP_POST_DOC
Help text following options.
ARGP_KEY_HELP_HEADER
Option header string.
ARGP_KEY_HELP_EXTRA
After all other documentation; text is zero for this key.
ARGP_KEY_HELP_DUP_ARGS_NOTE
The explanatory note emitted when duplicate option arguments have been suppressed.
ARGP_KEY_HELP_ARGS_DOC
The argument doc string (the args_doc field from the argp parser; see section Specifying Argp Parsers).
The argp_help Function

Normally programs using argp need not worry too much about printing argument-usage-type help messages, because the standard `--help' option is handled automatically by argp, and the typical error cases can be handled using argp_usage and argp_error (see section Functions For Use in Argp Parsers).

However, if it's desirable to print a standard help message in some context other than parsing the program options, argp offers the argp_help interface.

Function: void argp_help (const struct argp *argp, FILE *stream, unsigned flags, char *name)
Output a help message for the argp parser argp to stream. What sort of messages is printed is determined by flags.

Any options such as `--help' that are implemented automatically by argp itself will not be present in the help output; for this reason, it is better to use argp_state_help if calling from within an argp parser function. See section Functions For Use in Argp Parsers.

Flags for the argp_help Function

When calling argp_help (see section The argp_help Function), or argp_state_help (see section Functions For Use in Argp Parsers), exactly what is output is determined by the flags argument, which should consist of any of the following flags, or'd together:

ARGP_HELP_USAGE
A unix `Usage:' message that explicitly lists all options.
ARGP_HELP_SHORT_USAGE
A unix `Usage:' message that displays only an appropriate placeholder to indicate where the options go; useful for showing the non-option argument syntax.
ARGP_HELP_SEE
A `Try ... for more help' message; `...' contains the program name and `--help'.
ARGP_HELP_LONG
A verbose option help message that gives each option understood along with its documentation string.
ARGP_HELP_PRE_DOC
The part of the argp parser doc string that precedes the verbose option help.
ARGP_HELP_POST_DOC
The part of the argp parser doc string that follows the verbose option help.
ARGP_HELP_DOC
(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)
ARGP_HELP_BUG_ADDR
A message saying where to report bugs for this program, if the argp_program_bug_address variable contains one.
ARGP_HELP_LONG_ONLY
Modify any output appropriately to reflect ARGP_LONG_ONLY mode.
The following flags are only understood when used with argp_state_help, and control whether the function returns after printing its output, or terminates the program:

ARGP_HELP_EXIT_ERR
Terminate the program with exit (argp_err_exit_status).
ARGP_HELP_EXIT_OK
Terminate the program with exit (0).
The following flags are combinations of the basic ones for printing standard messages:

ARGP_HELP_STD_ERR
Assuming an error message for a parsing error has already printed, prints a note on how to get help, and terminates the program with an error.
ARGP_HELP_STD_USAGE
Prints a standard usage message and terminates the program with an error. This is used when no more specific error message is appropriate.
ARGP_HELP_STD_HELP
Prints the standard response for a `--help' option, and terminates the program successfully.
Argp Examples

These example programs demonstrate the basic usage of argp.

A Minimal Program Using Argp

This is (probably) the smallest possible program that uses argp. It won't do much except give an error messages and exit when there are any arguments, and print a (rather pointless) message for `--help'.
/* Argp example #1 -- a minimal program using argp */

/* This is (probably) the smallest possible program that
   uses argp.  It won't do much except give an error
   messages and exit when there are any arguments, and print
   a (rather pointless) messages for --help. */

#include <argp.h>

int main (int argc, char **argv)
{
  argp_parse (0, argc, argv, 0, 0, 0);
  exit (0);
}
A Program Using Argp with Only Default Options

This program doesn't use any options or arguments, but uses argp to be compliant with the GNU standard command line format.

In addition to making sure no arguments are given, and implementing a `--help' option, this example will have a `--version' option, and will put the given documentation string and bug address in the `--help' output, as per GNU standards.

The variable argp contains the argument parser specification; adding fields to this structure is the way most parameters are passed to argp_parse (the first three fields are usually used, but not in this small program). There are also two global variables that argp knows about defined here, argp_program_version and argp_program_bug_address (they are global variables because they will almost always be constant for a given program, even if it uses different argument parsers for various tasks).
/* Argp example #2 -- a pretty minimal program using argp */

/* This program doesn't use any options or arguments, but uses
   argp to be compliant with the GNU standard command line
   format.

   In addition to making sure no arguments are given, and
   implementing a --help option, this example will have a
   --version option, and will put the given documentation string
   and bug address in the --help output, as per GNU standards.

   The variable ARGP contains the argument parser specification;
   adding fields to this structure is the way most parameters are
   passed to argp_parse (the first three fields are usually used,
   but not in this small program).  There are also two global
   variables that argp knows about defined here,
   ARGP_PROGRAM_VERSION and ARGP_PROGRAM_BUG_ADDRESS (they are
   global variables becuase they will almost always be constant
   for a given program, even if it uses different argument
   parsers for various tasks). */

#include <argp.h>

const char *argp_program_version =
  "argp-ex2 1.0";
const char *argp_program_bug_address =
  "<bug-gnu-utils@gnu.org>";

/* Program documentation. */
static char doc[] =
  "Argp example #2 -- a pretty minimal program using argp";

/* Our argument parser.  The options, parser, and
   args_doc fields are zero because we have neither options or
   arguments; doc and argp_program_bug_address will be
   used in the output for `--help', and the `--version'
   option will print out argp_program_version. */
static struct argp argp = { 0, 0, 0, doc };

int main (int argc, char **argv)
{
  argp_parse (&argp, argc, argv, 0, 0, 0);
  exit (0);
}
A Program Using Argp with User Options

This program uses the same features as example 2, and adds user options and arguments.

We now use the first four fields in argp (see section Specifying Argp Parsers), and specifies parse_opt as the parser function (see section Argp Parser Functions).

Note that in this example, main uses a structure to communicate with the parse_opt function, a pointer to which it passes in the input argument to argp_parse (see section Parsing Program Options with Argp), and is retrieved by parse_opt through the input field in its state argument (see section Argp Parsing State). Of course, it's also possible to use global variables instead, but using a structure like this is somewhat more flexible and clean.
/* Argp example #3 -- a program with options and arguments using argp */

/* This program uses the same features as example 2, and uses options and
   arguments.

   We now use the first four fields in ARGP, so here's a description of them:
     OPTIONS  -- A pointer to a vector of struct argp_option (see below)
     PARSER   -- A function to parse a single option, called by argp
     ARGS_DOC -- A string describing how the non-option arguments should look
     DOC      -- A descriptive string about this program; if it contains a
                 vertical tab character (\v), the part after it will be
                 printed *following* the options

   The function PARSER takes the following arguments:
     KEY  -- An integer specifying which option this is (taken
             from the KEY field in each struct argp_option), or
             a special key specifying something else; the only
             special keys we use here are ARGP_KEY_ARG, meaning
             a non-option argument, and ARGP_KEY_END, meaning
             that all arguments have been parsed
     ARG  -- For an option KEY, the string value of its
             argument, or NULL if it has none
     STATE-- A pointer to a struct argp_state, containing
             various useful information about the parsing state; used here
             are the INPUT field, which reflects the INPUT argument to
             argp_parse, and the ARG_NUM field, which is the number of the
             current non-option argument being parsed
   It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the
   given KEY wasn't recognized, or an errno value indicating some other
   error.

   Note that in this example, main uses a structure to communicate with the
   parse_opt function, a pointer to which it passes in the INPUT argument to
   argp_parse.  Of course, it's also possible to use global variables
   instead, but this is somewhat more flexible.

   The OPTIONS field contains a pointer to a vector of struct argp_option's;
   that structure has the following fields (if you assign your option
   structures using array initialization like this example, unspecified
   fields will be defaulted to 0, and need not be specified):
     NAME   -- The name of this option's long option (may be zero)
     KEY    -- The KEY to pass to the PARSER function when parsing this option,
               *and* the name of this option's short option, if it is a
               printable ascii character
     ARG    -- The name of this option's argument, if any
     FLAGS  -- Flags describing this option; some of them are:
                 OPTION_ARG_OPTIONAL -- The argument to this option is optional
                 OPTION_ALIAS        -- This option is an alias for the
                                        previous option
                 OPTION_HIDDEN       -- Don't show this option in --help output
     DOC    -- A documentation string for this option, shown in --help output

   An options vector should be terminated by an option with all fields zero. */

#include <argp.h>

const char *argp_program_version =
  "argp-ex3 1.0";
const char *argp_program_bug_address =
  "<bug-gnu-utils@gnu.org>";

/* Program documentation. */
static char doc[] =
  "Argp example #3 -- a program with options and arguments using argp";

/* A description of the arguments we accept. */
static char args_doc[] = "ARG1 ARG2";

/* The options we understand. */
static struct argp_option options[] = {
  {"verbose",  'v', 0,      0,  "Produce verbose output" },
  {"quiet",    'q', 0,      0,  "Don't produce any output" },
  {"silent",   's', 0,      OPTION_ALIAS },
  {"output",   'o', "FILE", 0,
   "Output to FILE instead of standard output" },
  { 0 }
};

/* Used by main to communicate with parse_opt. */
struct arguments
{
  char *args[2];                /* arg1 & arg2 */
  int silent, verbose;
  char *output_file;
};

/* Parse a single option. */
static error_t
parse_opt (int key, char *arg, struct argp_state *state)
{
  /* Get the input argument from argp_parse, which we
     know is a pointer to our arguments structure. */
  struct arguments *arguments = state->input;

  switch (key)
    {
    case 'q': case 's':
      arguments->silent = 1;
      break;
    case 'v':
      arguments->verbose = 1;
      break;
    case 'o':
      arguments->output_file = arg;
      break;

    case ARGP_KEY_ARG:
      if (state->arg_num >= 2)
        /* Too many arguments. */
        argp_usage (state);

      arguments->args[state->arg_num] = arg;

      break;

    case ARGP_KEY_END:
      if (state->arg_num < 2)
        /* Not enough arguments. */
        argp_usage (state);
      break;

    default:
      return ARGP_ERR_UNKNOWN;
    }
  return 0;
}

/* Our argp parser. */
static struct argp argp = { options, parse_opt, args_doc, doc };

int main (int argc, char **argv)
{
  struct arguments arguments;

  /* Default values. */
  arguments.silent = 0;
  arguments.verbose = 0;
  arguments.output_file = "-";

  /* Parse our arguments; every option seen by parse_opt will
     be reflected in arguments. */
  argp_parse (&argp, argc, argv, 0, 0, &arguments);

  printf ("ARG1 = %s\nARG2 = %s\nOUTPUT_FILE = %s\n"
          "VERBOSE = %s\nSILENT = %s\n",
          arguments.args[0], arguments.args[1],
          arguments.output_file,
          arguments.verbose ? "yes" : "no",
          arguments.silent ? "yes" : "no");

  exit (0);
}
A Program Using Multiple Combined Argp Parsers

This program uses the same features as example 3, but has more options, and somewhat more structure in the `--help' output. It also shows how you can `steal' the remainder of the input arguments past a certain point, for programs that accept a list of items, and the special key value ARGP_KEY_NO_ARGS, which is only given if no non-option arguments were supplied to the program (see section Special Keys for Argp Parser Functions).

For structuring the help output, two features are used: headers, which are entries in the options vector (see section Specifying Options in an Argp Parser) with the first four fields being zero, and a two part documentation string (in the variable doc), which allows documentation both before and after the options (see section Specifying Argp Parsers); the two parts of doc are separated by a vertical-tab character ('\v', or '\013'). By convention, the documentation before the options is just a short string saying what the program does, and that afterwards is longer, describing the behavior in more detail. All documentation strings are automatically filled for output, although newlines may be included to force a line break at a particular point. All documentation strings are also passed to the gettext function, for possible translation into the current locale.
/* Argp example #4 -- a program with somewhat more complicated options */

/* This program uses the same features as example 3, but has more
   options, and somewhat more structure in the -help output.  It
   also shows how you can `steal' the remainder of the input
   arguments past a certain point, for programs that accept a
   list of items.  It also shows the special argp KEY value
   ARGP_KEY_NO_ARGS, which is only given if no non-option
   arguments were supplied to the program.

   For structuring the help output, two features are used,
   *headers* which are entries in the options vector with the
   first four fields being zero, and a two part documentation
   string (in the variable DOC), which allows documentation both
   before and after the options; the two parts of DOC are
   separated by a vertical-tab character ('\v', or '\013').  By
   convention, the documentation before the options is just a
   short string saying what the program does, and that afterwards
   is longer, describing the behavior in more detail.  All
   documentation strings are automatically filled for output,
   although newlines may be included to force a line break at a
   particular point.  All documentation strings are also passed to
   the `gettext' function, for possible translation into the
   current locale. */

#include <stdlib.h>
#include <error.h>
#include <argp.h>

const char *argp_program_version =
  "argp-ex4 1.0";
const char *argp_program_bug_address =
  "<bug-gnu-utils@prep.ai.mit.edu>";

/* Program documentation. */
static char doc[] =
  "Argp example #4 -- a program with somewhat more complicated\
options\
\vThis part of the documentation comes *after* the options;\
 note that the text is automatically filled, but it's possible\
 to force a line-break, e.g.\n<-- here.";

/* A description of the arguments we accept. */
static char args_doc[] = "ARG1 [STRING...]";

/* Keys for options without short-options. */
#define OPT_ABORT  1            /* --abort */

/* The options we understand. */
static struct argp_option options[] = {
  {"verbose",  'v', 0,       0, "Produce verbose output" },
  {"quiet",    'q', 0,       0, "Don't produce any output" },
  {"silent",   's', 0,       OPTION_ALIAS },
  {"output",   'o', "FILE",  0,
   "Output to FILE instead of standard output" },

  {0,0,0,0, "The following options should be grouped together:" },
  {"repeat",   'r', "COUNT", OPTION_ARG_OPTIONAL,
   "Repeat the output COUNT (default 10) times"},
  {"abort",    OPT_ABORT, 0, 0, "Abort before showing any output"},

  { 0 }
};

/* Used by main to communicate with parse_opt. */
struct arguments
{
  char *arg1;                   /* arg1 */
  char **strings;               /* [string...] */
  int silent, verbose, abort;   /* `-s', `-v', `--abort' */
  char *output_file;            /* file arg to `--output' */
  int repeat_count;             /* count arg to `--repeat' */
};

/* Parse a single option. */
static error_t
parse_opt (int key, char *arg, struct argp_state *state)
{
  /* Get the input argument from argp_parse, which we
     know is a pointer to our arguments structure. */
  struct arguments *arguments = state->input;

  switch (key)
    {
    case 'q': case 's':
      arguments->silent = 1;
      break;
    case 'v':
      arguments->verbose = 1;
      break;
    case 'o':
      arguments->output_file = arg;
      break;
    case 'r':
      arguments->repeat_count = arg ? atoi (arg) : 10;
      break;
    case OPT_ABORT:
      arguments->abort = 1;
      break;

    case ARGP_KEY_NO_ARGS:
      argp_usage (state);

    case ARGP_KEY_ARG:
      /* Here we know that state->arg_num == 0, since we
         force argument parsing to end before any more arguments can
         get here. */
      arguments->arg1 = arg;

      /* Now we consume all the rest of the arguments.
         state->next is the index in state->argv of the
         next argument to be parsed, which is the first string
         we're interested in, so we can just use
         &state->argv[state->next] as the value for
         arguments->strings.

         In addition, by setting state->next to the end
         of the arguments, we can force argp to stop parsing here and
         return. */
      arguments->strings = &state->argv[state->next];
      state->next = state->argc;

      break;

    default:
      return ARGP_ERR_UNKNOWN;
    }
  return 0;
}

/* Our argp parser. */
static struct argp argp = { options, parse_opt, args_doc, doc };

int main (int argc, char **argv)
{
  int i, j;
  struct arguments arguments;

  /* Default values. */
  arguments.silent = 0;
  arguments.verbose = 0;
  arguments.output_file = "-";
  arguments.repeat_count = 1;
  arguments.abort = 0;

  /* Parse our arguments; every option seen by parse_opt will be
     reflected in arguments. */
  argp_parse (&argp, argc, argv, 0, 0, &arguments);

  if (arguments.abort)
    error (10, 0, "ABORTED");

  for (i = 0; i < arguments.repeat_count; i++)
    {
      printf ("ARG1 = %s\n", arguments.arg1);
      printf ("STRINGS = ");
      for (j = 0; arguments.strings[j]; j++)
        printf (j == 0 ? "%s" : ", %s", arguments.strings[j]);
      printf ("\n");
      printf ("OUTPUT_FILE = %s\nVERBOSE = %s\nSILENT = %s\n",
              arguments.output_file,
              arguments.verbose ? "yes" : "no",
              arguments.silent ? "yes" : "no");
    }

  exit (0);
}
Argp User Customization

The way formatting of argp `--help' output may be controlled to some extent by a program's users, by setting the ARGP_HELP_FMT environment variable to a comma-separated list (whitespace is ignored) of the following tokens:

`dup-args'

`no-dup-args'
Turn duplicate-argument-mode on or off. In duplicate argument mode, if an option which accepts an argument has multiple names, the argument is shown for each name; otherwise, it is only shown for the first long option, and a note is emitted later so the user knows that it applies to the other names as well. The default is `no-dup-args', which is less consistent, but prettier.
`dup-args-note'

`no-dup-args-note'
Enable or disable the note informing the user of suppressed option argument duplication. The default is `dup-args-note'.
`short-opt-col=n'
Show the first short option in column n (default 2).
`long-opt-col=n'
Show the first long option in column n (default 6).
`doc-opt-col=n'
Show `documentation options' (see section Flags for Argp Options) in column n (default 2).
`opt-doc-col=n'
Show the documentation for options starting in column n (default 29).
`header-col=n'
Indent group headers (which document groups of options) to column n (default 1).
`usage-indent=n'
Indent continuation lines in `Usage:' messages to column n (default 12).
`rmargin=n'
Word wrap help output at or before column n (default 79).
Parsing of Suboptions

Having a single level of options is sometimes not enough. There might be too many options which have to be available or a set of options is closely related.

For this case some programs use suboptions. One of the most prominent programs is certainly mount(8). The -o option take one argument which itself is a comma separated list of options. To ease the programming of code like this the function getsubopt is available.

Function: int getsubopt (char **optionp, const char* const *tokens, char **valuep)

The optionp parameter must be a pointer to a variable containing the address of the string to process. When the function returns the reference is updated to point to the next suboption or to the terminating `\0' character if there is no more suboption available.

The tokens parameter references an array of strings containing the known suboptions. All strings must be `\0' terminated and to mark the end a null pointer must be stored. When getsubopt finds a possible legal suboption it compares it with all strings available in the tokens array and returns the index in the string as the indicator.

In case the suboption has an associated value introduced by a `=' character, a pointer to the value is returned in valuep. The string is `\0' terminated. If no argument is available valuep is set to the null pointer. By doing this the caller can check whether a necessary value is given or whether no unexpected value is present.

In case the next suboption in the string is not mentioned in the tokens array the starting address of the suboption including a possible value is returned in valuep and the return value of the function is `-1'.

Parsing of Suboptions Example

The code which might appear in the mount(8) program is a perfect example of the use of getsubopt:
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

int do_all;
const char *type;
int read_size;
int write_size;
int read_only;

enum
{
  RO_OPTION = 0,
  RW_OPTION,
  READ_SIZE_OPTION,
  WRITE_SIZE_OPTION,
  THE_END
};

const char *mount_opts[] =
{
  [RO_OPTION] = "ro",
  [RW_OPTION] = "rw",
  [READ_SIZE_OPTION] = "rsize",
  [WRITE_SIZE_OPTION] = "wsize",
  [THE_END] = NULL
};

int
main (int argc, char *argv[])
{
  char *subopts, *value;
  int opt;

  while ((opt = getopt (argc, argv, "at:o:")) != -1)
    switch (opt)
      {
      case 'a':
        do_all = 1;
        break;
      case 't':
        type = optarg;
        break;
      case 'o':
        subopts = optarg;
        while (*subopts != '\0')
          switch (getsubopt (&subopts, mount_opts, &value))
            {
            case RO_OPTION:
              read_only = 1;
              break;
            case RW_OPTION:
              read_only = 0;
              break;
            case READ_SIZE_OPTION:
              if (value == NULL)
                abort ();
              read_size = atoi (value);
              break;
            case WRITE_SIZE_OPTION:
              if (value == NULL)
                abort ();
              write_size = atoi (value);
              break;
            default:
              /* Unknown suboption. */
              printf ("Unknown suboption `%s'\n", value);
              break;
            }
        break;
      default:
        abort ();
      }

  /* Do the real work. */

  return 0;
}
Environment Variables

When a program is executed, it receives information about the context in which it was invoked in two ways. The first mechanism uses the argv and argc arguments to its main function, and is discussed in section Program Arguments. The second mechanism uses environment variables and is discussed in this section.

The argv mechanism is typically used to pass command-line arguments specific to the particular program being invoked. The environment, on the other hand, keeps track of information that is shared by many programs, changes infrequently, and that is less frequently used.

The environment variables discussed in this section are the same environment variables that you set using assignments and the export command in the shell. Programs executed from the shell inherit all of the environment variables from the shell.

Standard environment variables are used for information about the user's home directory, terminal type, current locale, and so on; you can define additional variables for other purposes. The set of all environment variables that have values is collectively known as the environment.

Names of environment variables are case-sensitive and must not contain the character `='. System-defined environment variables are invariably uppercase.

The values of environment variables can be anything that can be represented as a string. A value must not contain an embedded null character, since this is assumed to terminate the string.

Environment Access

The value of an environment variable can be accessed with the getenv function. This is declared in the header file `stdlib.h'. All of the following functions can be safely used in multi-threaded programs. It is made sure that concurrent modifications to the environment do not lead to errors.

Function: char * getenv (const char *name)
This function returns a string that is the value of the environment variable name. You must not modify this string. In some non-Unix systems not using the GNU library, it might be overwritten by subsequent calls to getenv (but not by any other library function). If the environment variable name is not defined, the value is a null pointer.

Function: int putenv (char *string)
The putenv function adds or removes definitions from the environment. If the string is of the form `name=value', the definition is added to the environment. Otherwise, the string is interpreted as the name of an environment variable, and any definition for this variable in the environment is removed.

The difference to the setenv function is that the exact string given as the parameter string is put into the environment. If the user should change the string after the putenv call this will reflect in automatically in the environment. This also requires that string is no automatic variable which scope is left before the variable is removed from the environment. The same applies of course to dynamically allocated variables which are freed later.

This function is part of the extended Unix interface. Since it was also available in old SVID libraries you should define either _XOPEN_SOURCE or _SVID_SOURCE before including any header.

Function: int setenv (const char *name, const char *value, int replace)
The setenv function can be used to add a new definition to the environment. The entry with the name name is replaced by the value `name=value'. Please note that this is also true if value is the empty string. To do this a new string is created and the strings name and value are copied. A null pointer for the value parameter is illegal. If the environment already contains an entry with key name the replace parameter controls the action. If replace is zero, nothing happens. Otherwise the old entry is replaced by the new one.

Please note that you cannot remove an entry completely using this function.

This function was originally part of the BSD library but is now part of the Unix standard.

Function: int unsetenv (const char *name)
Using this function one can remove an entry completely from the environment. If the environment contains an entry with the key name this whole entry is removed. A call to this function is equivalent to a call to putenv when the value part of the string is empty.

The function return -1 if name is a null pointer, points to an empty string, or points to a string containing a = character. It returns 0 if the call succeeded.

This function was originall part of the BSD library but is now part of the Unix standard. The BSD version had no return value, though.

There is one more function to modify the whole environment. This function is said to be used in the POSIX.9 (POSIX bindings for Fortran 77) and so one should expect it did made it into POSIX.1. But this never happened. But we still provide this function as a GNU extension to enable writing standard compliant Fortran environments.

Function: int clearenv (void)
The clearenv function removes all entries from the environment. Using putenv and setenv new entries can be added again later.

If the function is successful it returns 0. Otherwise the return value is nonzero.

You can deal directly with the underlying representation of environment objects to add more variables to the environment (for example, to communicate with another program you are about to execute; see section Executing a File).

Variable: char ** environ
The environment is represented as an array of strings. Each string is of the format `name=value'. The order in which strings appear in the environment is not significant, but the same name must not appear more than once. The last element of the array is a null pointer.

This variable is declared in the header file `unistd.h'.

If you just want to get the value of an environment variable, use getenv.

Unix systems, and the GNU system, pass the initial value of environ as the third argument to main. See section Program Arguments.

Standard Environment Variables

These environment variables have standard meanings. This doesn't mean that they are always present in the environment; but if these variables are present, they have these meanings. You shouldn't try to use these environment variable names for some other purpose.

HOME
This is a string representing the user's home directory, or initial default working directory. The user can set HOME to any value. If you need to make sure to obtain the proper home directory for a particular user, you should not use HOME; instead, look up the user's name in the user database (see section User Database). For most purposes, it is better to use HOME, precisely because this lets the user specify the value.
LOGNAME
This is the name that the user used to log in. Since the value in the environment can be tweaked arbitrarily, this is not a reliable way to identify the user who is running a program; a function like getlogin (see section Identifying Who Logged In) is better for that purpose. For most purposes, it is better to use LOGNAME, precisely because this lets the user specify the value.
PATH
A path is a sequence of directory names which is used for searching for a file. The variable PATH holds a path used for searching for programs to be run. The execlp and execvp functions (see section Executing a File) use this environment variable, as do many shells and other utilities which are implemented in terms of those functions. The syntax of a path is a sequence of directory names separated by colons. An empty string instead of a directory name stands for the current directory (see section Working Directory). A typical value for this environment variable might be a string like:
:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
This means that if the user tries to execute a program named foo, the system will look for files named `foo', `/bin/foo', `/etc/foo', and so on. The first of these files that exists is the one that is executed.
TERM
This specifies the kind of terminal that is receiving program output. Some programs can make use of this information to take advantage of special escape sequences or terminal modes supported by particular kinds of terminals. Many programs which use the termcap library (see section `Finding a Terminal Description' in The Termcap Library Manual) use the TERM environment variable, for example.
TZ
This specifies the time zone. See section Specifying the Time Zone with TZ, for information about the format of this string and how it is used.
LANG
This specifies the default locale to use for attribute categories where neither LC_ALL nor the specific environment variable for that category is set. See section Locales and Internationalization, for more information about locales.
LC_ALL
If this environment variable is set it overrides the selection for all the locales done using the other LC_* environment variables. The value of the other LC_* environment variables is simply ignored in this case.
LC_COLLATE
This specifies what locale to use for string sorting.
LC_CTYPE
This specifies what locale to use for character sets and character classification.
LC_MESSAGES
This specifies what locale to use for printing messages and to parse responses.
LC_MONETARY
This specifies what locale to use for formatting monetary values.
LC_NUMERIC
This specifies what locale to use for formatting numbers.
LC_TIME
This specifies what locale to use for formatting date/time values.
NLSPATH
This specifies the directories in which the catopen function looks for message translation catalogs.
_POSIX_OPTION_ORDER
If this environment variable is defined, it suppresses the usual reordering of command line arguments by getopt and argp_parse. See section Program Argument Syntax Conventions.
System Calls

A system call is a request for service that a program makes of the kernel. The service is generally something that only the kernel has the privilege to do, such as doing I/O. Programmers don't normally need to be concerned with system calls because there are functions in the GNU C library to do virtually everything that system calls do. These functions work by making system calls themselves. For example, there is a system call that changes the permissions of a file, but you don't need to know about it because you can just use the GNU C library's chmod function.

System calls are sometimes called kernel calls.

However, there are times when you want to make a system call explicitly, and for that, the GNU C library provides the syscall function. syscall is harder to use and less portable than functions like chmod, but easier and more portable than coding the system call in assembler instructions.

syscall is most useful when you are working with a system call which is special to your system or is newer than the GNU C library you are using. syscall is implemented in an entirely generic way; the function does not know anything about what a particular system call does or even if it is valid.

The description of syscall in this section assumes a certain protocol for system calls on the various platforms on which the GNU C library runs. That protocol is not defined by any strong authority, but we won't describe it here either because anyone who is coding syscall probably won't accept anything less than kernel and C library source code as a specification of the interface between them anyway.

syscall is declared in `unistd.h'.

Function: long int syscall (long int sysno, ...)

syscall performs a generic system call.

sysno is the system call number. Each kind of system call is identified by a number. Macros for all the possible system call numbers are defined in `sys/syscall.h'

The remaining arguments are the arguments for the system call, in order, and their meanings depend on the kind of system call. Each kind of system call has a definite number of arguments, from zero to five. If you code more arguments than the system call takes, the extra ones to the right are ignored.

The return value is the return value from the system call, unless the system call failed. In that case, syscall returns -1 and sets errno to an error code that the system call returned. Note that system calls do not return -1 when they succeed.

If you specify an invalid sysno, syscall returns -1 with errno = ENOSYS.

Example:
#include <unistd.h>
#include <sys/syscall.h>
#include <errno.h>

...

int rc;

rc = syscall(SYS_chmod, "/etc/passwd", 0444);

if (rc == -1)
   fprintf(stderr, "chmod failed, errno = %d\n", errno);
This, if all the compatibility stars are aligned, is equivalent to the following preferable code:
#include <sys/types.h>
#include <sys/stat.h>
#include <errno.h>

...

int rc;

rc = chmod("/etc/passwd", 0444);
if (rc == -1)
   fprintf(stderr, "chmod failed, errno = %d\n", errno);
Program Termination

The usual way for a program to terminate is simply for its main function to return. The exit status value returned from the main function is used to report information back to the process's parent process or shell.

A program can also terminate normally by calling the exit function.

In addition, programs can be terminated by signals; this is discussed in more detail in section Signal Handling. The abort function causes a signal that kills the program.

Normal Termination

A process terminates normally when its program signals it is done by calling exit. Returning from main is equivalent to calling exit, and the value that main returns is used as the argument to exit.

Function: void exit (int status)
The exit function tells the system that the program is done, which causes it to terminate the process.

status is the program's exit status, which becomes part of the process' termination status. This function does not return.

Normal termination causes the following actions:

Functions that were registered with the atexit or on_exit functions are called in the reverse order of their registration. This mechanism allows your application to specify its own "cleanup" actions to be performed at program termination. Typically, this is used to do things like saving program state information in a file, or unlocking locks in shared data bases.
All open streams are closed, writing out any buffered output data. See section Closing Streams. In addition, temporary files opened with the tmpfile function are removed; see section Temporary Files.
_exit is called, terminating the program. See section Termination Internals.

Exit Status

When a program exits, it can return to the parent process a small amount of information about the cause of termination, using the exit status. This is a value between 0 and 255 that the exiting process passes as an argument to exit.

Normally you should use the exit status to report very broad information about success or failure. You can't provide a lot of detail about the reasons for the failure, and most parent processes would not want much detail anyway.

There are conventions for what sorts of status values certain programs should return. The most common convention is simply 0 for success and 1 for failure. Programs that perform comparison use a different convention: they use status 1 to indicate a mismatch, and status 2 to indicate an inability to compare. Your program should follow an existing convention if an existing convention makes sense for it.

A general convention reserves status values 128 and up for special purposes. In particular, the value 128 is used to indicate failure to execute another program in a subprocess. This convention is not universally obeyed, but it is a good idea to follow it in your programs.

Warning: Don't try to use the number of errors as the exit status. This is actually not very useful; a parent process would generally not care how many errors occurred. Worse than that, it does not work, because the status value is truncated to eight bits. Thus, if the program tried to report 256 errors, the parent would receive a report of 0 errors--that is, success.

For the same reason, it does not work to use the value of errno as the exit status--these can exceed 255.

Portability note: Some non-POSIX systems use different conventions for exit status values. For greater portability, you can use the macros EXIT_SUCCESS and EXIT_FAILURE for the conventional status value for success and failure, respectively. They are declared in the file `stdlib.h'.

Macro: int EXIT_SUCCESS
This macro can be used with the exit function to indicate successful program completion.

On POSIX systems, the value of this macro is 0. On other systems, the value might be some other (possibly non-constant) integer expression.

Macro: int EXIT_FAILURE
This macro can be used with the exit function to indicate unsuccessful program completion in a general sense.

On POSIX systems, the value of this macro is 1. On other systems, the value might be some other (possibly non-constant) integer expression. Other nonzero status values also indicate failures. Certain programs use different nonzero status values to indicate particular kinds of "non-success". For example, diff uses status value 1 to mean that the files are different, and 2 or more to mean that there was difficulty in opening the files.

Don't confuse a program's exit status with a process' termination status. There are lots of ways a process can terminate besides having it's program finish. In the event that the process termination is caused by program termination (i.e. exit), though, the program's exit status becomes part of the process' termination status.

Cleanups on Exit

Your program can arrange to run its own cleanup functions if normal termination happens. If you are writing a library for use in various application programs, then it is unreliable to insist that all applications call the library's cleanup functions explicitly before exiting. It is much more robust to make the cleanup invisible to the application, by setting up a cleanup function in the library itself using atexit or on_exit.

Function: int atexit (void (*function) (void))
The atexit function registers the function function to be called at normal program termination. The function is called with no arguments.

The return value from atexit is zero on success and nonzero if the function cannot be registered.

Function: int on_exit (void (*function)(int status, void *arg), void *arg)
This function is a somewhat more powerful variant of atexit. It accepts two arguments, a function function and an arbitrary pointer arg. At normal program termination, the function is called with two arguments: the status value passed to exit, and the arg.

This function is included in the GNU C library only for compatibility for SunOS, and may not be supported by other implementations.

Here's a trivial program that illustrates the use of exit and atexit:
#include <stdio.h>
#include <stdlib.h>

void
bye (void)
{
  puts ("Goodbye, cruel world....");
}

int
main (void)
{
  atexit (bye);
  exit (EXIT_SUCCESS);
}
When this program is executed, it just prints the message and exits.

Aborting a Program

You can abort your program using the abort function. The prototype for this function is in `stdlib.h'.

Function: void abort (void)
The abort function causes abnormal program termination. This does not execute cleanup functions registered with atexit or on_exit.

This function actually terminates the process by raising a SIGABRT signal, and your program can include a handler to intercept this signal; see section Signal Handling.

Future Change Warning: Proposed Federal censorship regulations may prohibit us from giving you information about the possibility of calling this function. We would be required to say that this is not an acceptable way of terminating a program.

Termination Internals

The _exit function is the primitive used for process termination by exit. It is declared in the header file `unistd.h'.

Function: void _exit (int status)
The _exit function is the primitive for causing a process to terminate with status status. Calling this function does not execute cleanup functions registered with atexit or on_exit.

Function: void _Exit (int status)
The _Exit function is the ISO C equivalent to _exit. The ISO C committee members were not sure whether the definitions of _exit and _Exit were compatible so they have not used the POSIX name.

This function was introduced in ISO C99 and is declared in `stdlib.h'.

When a process terminates for any reason--either because the program terminates, or as a result of a signal--the following things happen:

All open file descriptors in the process are closed. See section Low-Level Input/Output. Note that streams are not flushed automatically when the process terminates; see section Input/Output on Streams.
A process exit status is saved to be reported back to the parent process via wait or waitpid; see section Process Completion. If the program exited, this status includes as its low-order 8 bits the program exit status.
Any child processes of the process being terminated are assigned a new parent process. (On most systems, including GNU, this is the init process, with process ID 1.)
A SIGCHLD signal is sent to the parent process.
If the process is a session leader that has a controlling terminal, then a SIGHUP signal is sent to each process in the foreground job, and the controlling terminal is disassociated from that session. See section Job Control.
If termination of a process causes a process group to become orphaned, and any member of that process group is stopped, then a SIGHUP signal and a SIGCONT signal are sent to each process in the group. See section Job Control.

Processes

Processes are the primitive units for allocation of system resources. Each process has its own address space and (usually) one thread of control. A process executes a program; you can have multiple processes executing the same program, but each process has its own copy of the program within its own address space and executes it independently of the other copies.

Processes are organized hierarchically. Each process has a parent process which explicitly arranged to create it. The processes created by a given parent are called its child processes. A child inherits many of its attributes from the parent process.

This chapter describes how a program can create, terminate, and control child processes. Actually, there are three distinct operations involved: creating a new child process, causing the new process to execute a program, and coordinating the completion of the child process with the original program.

The system function provides a simple, portable mechanism for running another program; it does all three steps automatically. If you need more control over the details of how this is done, you can use the primitive functions to do each step individually instead.

Running a Command

The easy way to run another program is to use the system function. This function does all the work of running a subprogram, but it doesn't give you much control over the details: you have to wait until the subprogram terminates before you can do anything else.

Function: int system (const char *command)
This function executes command as a shell command. In the GNU C library, it always uses the default shell sh to run the command. In particular, it searches the directories in PATH to find programs to execute. The return value is -1 if it wasn't possible to create the shell process, and otherwise is the status of the shell process. See section Process Completion, for details on how this status code can be interpreted.

If the command argument is a null pointer, a return value of zero indicates that no command processor is available.

This function is a cancelation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time system is called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls to system should be protected using cancelation handlers.

The system function is declared in the header file `stdlib.h'.

Portability Note: Some C implementations may not have any notion of a command processor that can execute other programs. You can determine whether a command processor exists by executing system (NULL); if the return value is nonzero, a command processor is available.

The popen and pclose functions (see section Pipe to a Subprocess) are closely related to the system function. They allow the parent process to communicate with the standard input and output channels of the command being executed.

Process Creation Concepts

This section gives an overview of processes and of the steps involved in creating a process and making it run another program.

Each process is named by a process ID number. A unique process ID is allocated to each process when it is created. The lifetime of a process ends when its termination is reported to its parent process; at that time, all of the process resources, including its process ID, are freed.

Processes are created with the fork system call (so the operation of creating a new process is sometimes called forking a process). The child process created by fork is a copy of the original parent process, except that it has its own process ID.

After forking a child process, both the parent and child processes continue to execute normally. If you want your program to wait for a child process to finish executing before continuing, you must do this explicitly after the fork operation, by calling wait or waitpid (see section Process Completion). These functions give you limited information about why the child terminated--for example, its exit status code.

A newly forked child process continues to execute the same program as its parent process, at the point where the fork call returns. You can use the return value from fork to tell whether the program is running in the parent process or the child.

Having several processes run the same program is only occasionally useful. But the child can execute another program using one of the exec functions; see section Executing a File. The program that the process is executing is called its process image. Starting execution of a new program causes the process to forget all about its previous process image; when the new program exits, the process exits too, instead of returning to the previous process image.

Process Identification

The pid_t data type represents process IDs. You can get the process ID of a process by calling getpid. The function getppid returns the process ID of the parent of the current process (this is also known as the parent process ID). Your program should include the header files `unistd.h' and `sys/types.h' to use these functions.

Data Type: pid_t
The pid_t data type is a signed integer type which is capable of representing a process ID. In the GNU library, this is an int.

Function: pid_t getpid (void)
The getpid function returns the process ID of the current process.

Function: pid_t getppid (void)
The getppid function returns the process ID of the parent of the current process.

Creating a Process

The fork function is the primitive for creating a process. It is declared in the header file `unistd.h'.

Function: pid_t fork (void)
The fork function creates a new process.

If the operation is successful, there are then both parent and child processes and both see fork return, but with different values: it returns a value of 0 in the child process and returns the child's process ID in the parent process.

If process creation failed, fork returns a value of -1 in the parent process. The following errno error conditions are defined for fork:

EAGAIN
There aren't enough system resources to create another process, or the user already has too many processes running. This means exceeding the RLIMIT_NPROC resource limit, which can usually be increased; see section Limiting Resource Usage.
ENOMEM
The process requires more space than the system can supply.
The specific attributes of the child process that differ from the parent process are:

The child process has its own unique process ID.
The parent process ID of the child process is the process ID of its parent process.
The child process gets its own copies of the parent process's open file descriptors. Subsequently changing attributes of the file descriptors in the parent process won't affect the file descriptors in the child, and vice versa. See section Control Operations on Files. However, the file position associated with each descriptor is shared by both processes; see section File Position.
The elapsed processor times for the child process are set to zero; see section Processor Time Inquiry.
The child doesn't inherit file locks set by the parent process. See section Control Operations on Files.
The child doesn't inherit alarms set by the parent process. See section Setting an Alarm.
The set of pending signals (see section How Signals Are Delivered) for the child process is cleared. (The child process inherits its mask of blocked signals and signal actions from the parent process.)

Function: pid_t vfork (void)
The vfork function is similar to fork but on some systems it is more efficient; however, there are restrictions you must follow to use it safely.

While fork makes a complete copy of the calling process's address space and allows both the parent and child to execute independently, vfork does not make this copy. Instead, the child process created with vfork shares its parent's address space until it calls _exit or one of the exec functions. In the meantime, the parent process suspends execution.

You must be very careful not to allow the child process created with vfork to modify any global data or even local variables shared with the parent. Furthermore, the child process cannot return from (or do a long jump out of) the function that called vfork! This would leave the parent process's control information very confused. If in doubt, use fork instead.

Some operating systems don't really implement vfork. The GNU C library permits you to use vfork on all systems, but actually executes fork if vfork isn't available. If you follow the proper precautions for using vfork, your program will still work even if the system uses fork instead.

Executing a File

This section describes the exec family of functions, for executing a file as a process image. You can use these functions to make a child process execute a new program after it has been forked.

To see the effects of exec from the point of view of the called program, See section The Basic Program/System Interface.

The functions in this family differ in how you specify the arguments, but otherwise they all do the same thing. They are declared in the header file `unistd.h'.

Function: int execv (const char *filename, char *const argv[])
The execv function executes the file named by filename as a new process image.

The argv argument is an array of null-terminated strings that is used to provide a value for the argv argument to the main function of the program to be executed. The last element of this array must be a null pointer. By convention, the first element of this array is the file name of the program sans directory names. See section Program Arguments, for full details on how programs can access these arguments.

The environment for the new process image is taken from the environ variable of the current process image; see section Environment Variables, for information about environments.

Function: int execl (const char *filename, const char *arg0, ...)
This is similar to execv, but the argv strings are specified individually instead of as an array. A null pointer must be passed as the last such argument.

Function: int execve (const char *filename, char *const argv[], char *const env[])
This is similar to execv, but permits you to specify the environment for the new program explicitly as the env argument. This should be an array of strings in the same format as for the environ variable; see section Environment Access.

Function: int execle (const char *filename, const char *arg0, char *const env[], ...)
This is similar to execl, but permits you to specify the environment for the new program explicitly. The environment argument is passed following the null pointer that marks the last argv argument, and should be an array of strings in the same format as for the environ variable.

Function: int execvp (const char *filename, char *const argv[])
The execvp function is similar to execv, except that it searches the directories listed in the PATH environment variable (see section Standard Environment Variables) to find the full file name of a file from filename if filename does not contain a slash.

This function is useful for executing system utility programs, because it looks for them in the places that the user has chosen. Shells use it to run the commands that users type.

Function: int execlp (const char *filename, const char *arg0, ...)
This function is like execl, except that it performs the same file name searching as the execvp function.

The size of the argument list and environment list taken together must not be greater than ARG_MAX bytes. See section General Capacity Limits. In the GNU system, the size (which compares against ARG_MAX) includes, for each string, the number of characters in the string, plus the size of a char *, plus one, rounded up to a multiple of the size of a char *. Other systems may have somewhat different rules for counting.

These functions normally don't return, since execution of a new program causes the currently executing program to go away completely. A value of -1 is returned in the event of a failure. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for these functions:

E2BIG
The combined size of the new program's argument list and environment list is larger than ARG_MAX bytes. The GNU system has no specific limit on the argument list size, so this error code cannot result, but you may get ENOMEM instead if the arguments are too big for available memory.
ENOEXEC
The specified file can't be executed because it isn't in the right format.
ENOMEM
Executing the specified file requires more storage than is available.
If execution of the new file succeeds, it updates the access time field of the file as if the file had been read. See section File Times, for more details about access times of files.

The point at which the file is closed again is not specified, but is at some point before the process exits or before another process image is executed.

Executing a new process image completely changes the contents of memory, copying only the argument and environment strings to new locations. But many other attributes of the process are unchanged:

The process ID and the parent process ID. See section Process Creation Concepts.
Session and process group membership. See section Concepts of Job Control.
Real user ID and group ID, and supplementary group IDs. See section The Persona of a Process.
Pending alarms. See section Setting an Alarm.
Current working directory and root directory. See section Working Directory. In the GNU system, the root directory is not copied when executing a setuid program; instead the system default root directory is used for the new program.
File mode creation mask. See section Assigning File Permissions.
Process signal mask; see section Process Signal Mask.
Pending signals; see section Blocking Signals.
Elapsed processor time associated with the process; see section Processor Time Inquiry.

If the set-user-ID and set-group-ID mode bits of the process image file are set, this affects the effective user ID and effective group ID (respectively) of the process. These concepts are discussed in detail in section The Persona of a Process.

Signals that are set to be ignored in the existing process image are also set to be ignored in the new process image. All other signals are set to the default action in the new process image. For more information about signals, see section Signal Handling.

File descriptors open in the existing process image remain open in the new process image, unless they have the FD_CLOEXEC (close-on-exec) flag set. The files that remain open inherit all attributes of the open file description from the existing process image, including file locks. File descriptors are discussed in section Low-Level Input/Output.

Streams, by contrast, cannot survive through exec functions, because they are located in the memory of the process itself. The new process image has no streams except those it creates afresh. Each of the streams in the pre-exec process image has a descriptor inside it, and these descriptors do survive through exec (provided that they do not have FD_CLOEXEC set). The new process image can reconnect these to new streams using fdopen (see section Descriptors and Streams).

Process Completion

The functions described in this section are used to wait for a child process to terminate or stop, and determine its status. These functions are declared in the header file `sys/wait.h'.

Function: pid_t waitpid (pid_t pid, int *status-ptr, int options)
The waitpid function is used to request status information from a child process whose process ID is pid. Normally, the calling process is suspended until the child process makes status information available by terminating.

Other values for the pid argument have special interpretations. A value of -1 or WAIT_ANY requests status information for any child process; a value of 0 or WAIT_MYPGRP requests information for any child process in the same process group as the calling process; and any other negative value - pgid requests information for any child process whose process group ID is pgid.

If status information for a child process is available immediately, this function returns immediately without waiting. If more than one eligible child process has status information available, one of them is chosen randomly, and its status is returned immediately. To get the status from the other eligible child processes, you need to call waitpid again.

The options argument is a bit mask. Its value should be the bitwise OR (that is, the `|' operator) of zero or more of the WNOHANG and WUNTRACED flags. You can use the WNOHANG flag to indicate that the parent process shouldn't wait; and the WUNTRACED flag to request status information from stopped processes as well as processes that have terminated.

The status information from the child process is stored in the object that status-ptr points to, unless status-ptr is a null pointer.

This function is a cancelation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time waitpid is called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls to waitpid should be protected using cancelation handlers.

The return value is normally the process ID of the child process whose status is reported. If there are child processes but none of them is waiting to be noticed, waitpid will block until one is. However, if the WNOHANG option was specified, waitpid will return zero instead of blocking.

If a specific PID to wait for was given to waitpid, it will ignore all other children (if any). Therefore if there are children waiting to be noticed but the child whose PID was specified is not one of them, waitpid will block or return zero as described above.

A value of -1 is returned in case of error. The following errno error conditions are defined for this function:

EINTR
The function was interrupted by delivery of a signal to the calling process. See section Primitives Interrupted by Signals.
ECHILD
There are no child processes to wait for, or the specified pid is not a child of the calling process.
EINVAL
An invalid value was provided for the options argument.
These symbolic constants are defined as values for the pid argument to the waitpid function.

WAIT_ANY
This constant macro (whose value is -1) specifies that waitpid should return status information about any child process.
WAIT_MYPGRP
This constant (with value 0) specifies that waitpid should return status information about any child process in the same process group as the calling process.
These symbolic constants are defined as flags for the options argument to the waitpid function. You can bitwise-OR the flags together to obtain a value to use as the argument.

WNOHANG
This flag specifies that waitpid should return immediately instead of waiting, if there is no child process ready to be noticed.
WUNTRACED
This flag specifies that waitpid should report the status of any child processes that have been stopped as well as those that have terminated.

Function: pid_t wait (int *status-ptr)
This is a simplified version of waitpid, and is used to wait until any one child process terminates. The call:
wait (&status)
is exactly equivalent to:
waitpid (-1, &status, 0)
This function is a cancelation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time wait is called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls to wait should be protected using cancelation handlers.

Function: pid_t wait4 (pid_t pid, int *status-ptr, int options, struct rusage *usage)
If usage is a null pointer, wait4 is equivalent to waitpid (pid, status-ptr, options).

If usage is not null, wait4 stores usage figures for the child process in *rusage (but only if the child has terminated, not if it has stopped). See section Resource Usage.

This function is a BSD extension.

Here's an example of how to use waitpid to get the status from all child processes that have terminated, without ever waiting. This function is designed to be a handler for SIGCHLD, the signal that indicates that at least one child process has terminated.
void
sigchld_handler (int signum)
{
  int pid, status, serrno;
  serrno = errno;
  while (1)
    {
      pid = waitpid (WAIT_ANY, &status, WNOHANG);
      if (pid < 0)
        {
          perror ("waitpid");
          break;
        }
      if (pid == 0)
        break;
      notice_termination (pid, status);
    }
  errno = serrno;
}
Process Completion Status

If the exit status value (see section Program Termination) of the child process is zero, then the status value reported by waitpid or wait is also zero. You can test for other kinds of information encoded in the returned status value using the following macros. These macros are defined in the header file `sys/wait.h'.

Macro: int WIFEXITED (int status)
This macro returns a nonzero value if the child process terminated normally with exit or _exit.

Macro: int WEXITSTATUS (int status)
If WIFEXITED is true of status, this macro returns the low-order 8 bits of the exit status value from the child process. See section Exit Status.

Macro: int WIFSIGNALED (int status)
This macro returns a nonzero value if the child process terminated because it received a signal that was not handled. See section Signal Handling.

Macro: int WTERMSIG (int status)
If WIFSIGNALED is true of status, this macro returns the signal number of the signal that terminated the child process.

Macro: int WCOREDUMP (int status)
This macro returns a nonzero value if the child process terminated and produced a core dump.

Macro: int WIFSTOPPED (int status)
This macro returns a nonzero value if the child process is stopped.

Macro: int WSTOPSIG (int status)
If WIFSTOPPED is true of status, this macro returns the signal number of the signal that caused the child process to stop.

BSD Process Wait Functions

The GNU library also provides these related facilities for compatibility with BSD Unix. BSD uses the union wait data type to represent status values rather than an int. The two representations are actually interchangeable; they describe the same bit patterns. The GNU C Library defines macros such as WEXITSTATUS so that they will work on either kind of object, and the wait function is defined to accept either type of pointer as its status-ptr argument.

These functions are declared in `sys/wait.h'.

Data Type: union wait
This data type represents program termination status values. It has the following members:

int w_termsig
The value of this member is the same as that of the WTERMSIG macro.
int w_coredump
The value of this member is the same as that of the WCOREDUMP macro.
int w_retcode
The value of this member is the same as that of the WEXITSTATUS macro.
int w_stopsig
The value of this member is the same as that of the WSTOPSIG macro.
Instead of accessing these members directly, you should use the equivalent macros.

The wait3 function is the predecessor to wait4, which is more flexible. wait3 is now obsolete.

Function: pid_t wait3 (union wait *status-ptr, int options, struct rusage *usage)
If usage is a null pointer, wait3 is equivalent to waitpid (-1, status-ptr, options).

If usage is not null, wait3 stores usage figures for the child process in *rusage (but only if the child has terminated, not if it has stopped). See section Resource Usage.

Process Creation Example

Here is an example program showing how you might write a function similar to the built-in system. It executes its command argument using the equivalent of `sh -c command'.
#include <stddef.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/wait.h>

/* Execute the command using this shell program.  */
#define SHELL "/bin/sh"

int
my_system (const char *command)
{
  int status;
  pid_t pid;

  pid = fork ();
  if (pid == 0)
    {
      /* This is the child process.  Execute the shell command. */
      execl (SHELL, SHELL, "-c", command, NULL);
      _exit (EXIT_FAILURE);
    }
  else if (pid < 0)
    /* The fork failed.  Report failure.  */
    status = -1;
  else
    /* This is the parent process.  Wait for the child to complete.  */
    if (waitpid (pid, &status, 0) != pid)
      status = -1;
  return status;
}
There are a couple of things you should pay attention to in this example.

Remember that the first argv argument supplied to the program represents the name of the program being executed. That is why, in the call to execl, SHELL is supplied once to name the program to execute and a second time to supply a value for argv[0].

The execl call in the child process doesn't return if it is successful. If it fails, you must do something to make the child process terminate. Just returning a bad status code with return would leave two processes running the original program. Instead, the right behavior is for the child process to report failure to its parent process.

Call _exit to accomplish this. The reason for using _exit instead of exit is to avoid flushing fully buffered streams such as stdout. The buffers of these streams probably contain data that was copied from the parent process by the fork, data that will be output eventually by the parent process. Calling exit in the child would output the data twice. See section Termination Internals.
Job Control

Job control refers to the protocol for allowing a user to move between multiple process groups (or jobs) within a single login session. The job control facilities are set up so that appropriate behavior for most programs happens automatically and they need not do anything special about job control. So you can probably ignore the material in this chapter unless you are writing a shell or login program.

You need to be familiar with concepts relating to process creation (see section Process Creation Concepts) and signal handling (see section Signal Handling) in order to understand this material presented in this chapter.

Concepts of Job Control

The fundamental purpose of an interactive shell is to read commands from the user's terminal and create processes to execute the programs specified by those commands. It can do this using the fork (see section Creating a Process) and exec (see section Executing a File) functions.

A single command may run just one process--but often one command uses several processes. If you use the `|' operator in a shell command, you explicitly request several programs in their own processes. But even if you run just one program, it can use multiple processes internally. For example, a single compilation command such as `cc -c foo.c' typically uses four processes (though normally only two at any given time). If you run make, its job is to run other programs in separate processes.

The processes belonging to a single command are called a process group or job. This is so that you can operate on all of them at once. For example, typing C-c sends the signal SIGINT to terminate all the processes in the foreground process group.

A session is a larger group of processes. Normally all the processes that stem from a single login belong to the same session.

Every process belongs to a process group. When a process is created, it becomes a member of the same process group and session as its parent process. You can put it in another process group using the setpgid function, provided the process group belongs to the same session.

The only way to put a process in a different session is to make it the initial process of a new session, or a session leader, using the setsid function. This also puts the session leader into a new process group, and you can't move it out of that process group again.

Usually, new sessions are created by the system login program, and the session leader is the process running the user's login shell.

A shell that supports job control must arrange to control which job can use the terminal at any time. Otherwise there might be multiple jobs trying to read from the terminal at once, and confusion about which process should receive the input typed by the user. To prevent this, the shell must cooperate with the terminal driver using the protocol described in this chapter.

The shell can give unlimited access to the controlling terminal to only one process group at a time. This is called the foreground job on that controlling terminal. Other process groups managed by the shell that are executing without such access to the terminal are called background jobs.

If a background job needs to read from its controlling terminal, it is stopped by the terminal driver; if the TOSTOP mode is set, likewise for writing. The user can stop a foreground job by typing the SUSP character (see section Special Characters) and a program can stop any job by sending it a SIGSTOP signal. It's the responsibility of the shell to notice when jobs stop, to notify the user about them, and to provide mechanisms for allowing the user to interactively continue stopped jobs and switch jobs between foreground and background.

See section Access to the Controlling Terminal, for more information about I/O to the controlling terminal,

Job Control is Optional

Not all operating systems support job control. The GNU system does support job control, but if you are using the GNU library on some other system, that system may not support job control itself.

You can use the _POSIX_JOB_CONTROL macro to test at compile-time whether the system supports job control. See section Overall System Options.

If job control is not supported, then there can be only one process group per session, which behaves as if it were always in the foreground. The functions for creating additional process groups simply fail with the error code ENOSYS.

The macros naming the various job control signals (see section Job Control Signals) are defined even if job control is not supported. However, the system never generates these signals, and attempts to send a job control signal or examine or specify their actions report errors or do nothing.

Controlling Terminal of a Process

One of the attributes of a process is its controlling terminal. Child processes created with fork inherit the controlling terminal from their parent process. In this way, all the processes in a session inherit the controlling terminal from the session leader. A session leader that has control of a terminal is called the controlling process of that terminal.

You generally do not need to worry about the exact mechanism used to allocate a controlling terminal to a session, since it is done for you by the system when you log in.

An individual process disconnects from its controlling terminal when it calls setsid to become the leader of a new session. See section Process Group Functions.

Access to the Controlling Terminal

Processes in the foreground job of a controlling terminal have unrestricted access to that terminal; background processes do not. This section describes in more detail what happens when a process in a background job tries to access its controlling terminal.

When a process in a background job tries to read from its controlling terminal, the process group is usually sent a SIGTTIN signal. This normally causes all of the processes in that group to stop (unless they handle the signal and don't stop themselves). However, if the reading process is ignoring or blocking this signal, then read fails with an EIO error instead.

Similarly, when a process in a background job tries to write to its controlling terminal, the default behavior is to send a SIGTTOU signal to the process group. However, the behavior is modified by the TOSTOP bit of the local modes flags (see section Local Modes). If this bit is not set (which is the default), then writing to the controlling terminal is always permitted without sending a signal. Writing is also permitted if the SIGTTOU signal is being ignored or blocked by the writing process.

Most other terminal operations that a program can do are treated as reading or as writing. (The description of each operation should say which.)

For more information about the primitive read and write functions, see section Input and Output Primitives.

Orphaned Process Groups

When a controlling process terminates, its terminal becomes free and a new session can be established on it. (In fact, another user could log in on the terminal.) This could cause a problem if any processes from the old session are still trying to use that terminal.

To prevent problems, process groups that continue running even after the session leader has terminated are marked as orphaned process groups.

When a process group becomes an orphan, its processes are sent a SIGHUP signal. Ordinarily, this causes the processes to terminate. However, if a program ignores this signal or establishes a handler for it (see section Signal Handling), it can continue running as in the orphan process group even after its controlling process terminates; but it still cannot access the terminal any more.

Implementing a Job Control Shell

This section describes what a shell must do to implement job control, by presenting an extensive sample program to illustrate the concepts involved.

section Data Structures for the Shell, introduces the example and presents its primary data structures.
section Initializing the Shell, discusses actions which the shell must perform to prepare for job control.
section Launching Jobs, includes information about how to create jobs to execute commands.
section Foreground and Background, discusses what the shell should do differently when launching a job in the foreground as opposed to a background job.
section Stopped and Terminated Jobs, discusses reporting of job status back to the shell.
section Continuing Stopped Jobs, tells you how to continue jobs that have been stopped.
section The Missing Pieces, discusses other parts of the shell.

Data Structures for the Shell

All of the program examples included in this chapter are part of a simple shell program. This section presents data structures and utility functions which are used throughout the example.

The sample shell deals mainly with two data structures. The job type contains information about a job, which is a set of subprocesses linked together with pipes. The process type holds information about a single subprocess. Here are the relevant data structure declarations:
/* A process is a single process.  */
typedef struct process
{
  struct process *next;       /* next process in pipeline */
  char **argv;                /* for exec */
  pid_t pid;                  /* process ID */
  char completed;             /* true if process has completed */
  char stopped;               /* true if process has stopped */
  int status;                 /* reported status value */
} process;

/* A job is a pipeline of processes.  */
typedef struct job
{
  struct job *next;           /* next active job */
  char *command;              /* command line, used for messages */
  process *first_process;     /* list of processes in this job */
  pid_t pgid;                 /* process group ID */
  char notified;              /* true if user told about stopped job */
  struct termios tmodes;      /* saved terminal modes */
  int stdin, stdout, stderr;  /* standard i/o channels */
} job;

/* The active jobs are linked into a list.  This is its head.   */
job *first_job = NULL;
Here are some utility functions that are used for operating on job objects.
/* Find the active job with the indicated pgid.  */
job *
find_job (pid_t pgid)
{
  job *j;

  for (j = first_job; j; j = j->next)
    if (j->pgid == pgid)
      return j;
  return NULL;
}

/* Return true if all processes in the job have stopped or completed.  */
int
job_is_stopped (job *j)
{
  process *p;

  for (p = j->first_process; p; p = p->next)
    if (!p->completed && !p->stopped)
      return 0;
  return 1;
}

/* Return true if all processes in the job have completed.  */
int
job_is_completed (job *j)
{
  process *p;

  for (p = j->first_process; p; p = p->next)
    if (!p->completed)
      return 0;
  return 1;
}
Initializing the Shell

When a shell program that normally performs job control is started, it has to be careful in case it has been invoked from another shell that is already doing its own job control.

A subshell that runs interactively has to ensure that it has been placed in the foreground by its parent shell before it can enable job control itself. It does this by getting its initial process group ID with the getpgrp function, and comparing it to the process group ID of the current foreground job associated with its controlling terminal (which can be retrieved using the tcgetpgrp function).

If the subshell is not running as a foreground job, it must stop itself by sending a SIGTTIN signal to its own process group. It may not arbitrarily put itself into the foreground; it must wait for the user to tell the parent shell to do this. If the subshell is continued again, it should repeat the check and stop itself again if it is still not in the foreground.

Once the subshell has been placed into the foreground by its parent shell, it can enable its own job control. It does this by calling setpgid to put itself into its own process group, and then calling tcsetpgrp to place this process group into the foreground.

When a shell enables job control, it should set itself to ignore all the job control stop signals so that it doesn't accidentally stop itself. You can do this by setting the action for all the stop signals to SIG_IGN.

A subshell that runs non-interactively cannot and should not support job control. It must leave all processes it creates in the same process group as the shell itself; this allows the non-interactive shell and its child processes to be treated as a single job by the parent shell. This is easy to do--just don't use any of the job control primitives--but you must remember to make the shell do it.

Here is the initialization code for the sample shell that shows how to do all of this.
/* Keep track of attributes of the shell.  */

#include <sys/types.h>
#include <termios.h>
#include <unistd.h>

pid_t shell_pgid;
struct termios shell_tmodes;
int shell_terminal;
int shell_is_interactive;

/* Make sure the shell is running interactively as the foreground job
   before proceeding. */

void
init_shell ()
{

  /* See if we are running interactively.  */
  shell_terminal = STDIN_FILENO;
  shell_is_interactive = isatty (shell_terminal);

  if (shell_is_interactive)
    {
      /* Loop until we are in the foreground.  */
      while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))
        kill (- shell_pgid, SIGTTIN);

      /* Ignore interactive and job-control signals.  */
      signal (SIGINT, SIG_IGN);
      signal (SIGQUIT, SIG_IGN);
      signal (SIGTSTP, SIG_IGN);
      signal (SIGTTIN, SIG_IGN);
      signal (SIGTTOU, SIG_IGN);
      signal (SIGCHLD, SIG_IGN);

      /* Put ourselves in our own process group.  */
      shell_pgid = getpid ();
      if (setpgid (shell_pgid, shell_pgid) < 0)
        {
          perror ("Couldn't put the shell in its own process group");
          exit (1);
        }

      /* Grab control of the terminal.  */
      tcsetpgrp (shell_terminal, shell_pgid);

      /* Save default terminal attributes for shell.  */
      tcgetattr (shell_terminal, &shell_tmodes);
    }
}
Launching Jobs

Once the shell has taken responsibility for performing job control on its controlling terminal, it can launch jobs in response to commands typed by the user.

To create the processes in a process group, you use the same fork and exec functions described in section Process Creation Concepts. Since there are multiple child processes involved, though, things are a little more complicated and you must be careful to do things in the right order. Otherwise, nasty race conditions can result.

You have two choices for how to structure the tree of parent-child relationships among the processes. You can either make all the processes in the process group be children of the shell process, or you can make one process in group be the ancestor of all the other processes in that group. The sample shell program presented in this chapter uses the first approach because it makes bookkeeping somewhat simpler.

As each process is forked, it should put itself in the new process group by calling setpgid; see section Process Group Functions. The first process in the new group becomes its process group leader, and its process ID becomes the process group ID for the group.

The shell should also call setpgid to put each of its child processes into the new process group. This is because there is a potential timing problem: each child process must be put in the process group before it begins executing a new program, and the shell depends on having all the child processes in the group before it continues executing. If both the child processes and the shell call setpgid, this ensures that the right things happen no matter which process gets to it first.

If the job is being launched as a foreground job, the new process group also needs to be put into the foreground on the controlling terminal using tcsetpgrp. Again, this should be done by the shell as well as by each of its child processes, to avoid race conditions.

The next thing each child process should do is to reset its signal actions.

During initialization, the shell process set itself to ignore job control signals; see section Initializing the Shell. As a result, any child processes it creates also ignore these signals by inheritance. This is definitely undesirable, so each child process should explicitly set the actions for these signals back to SIG_DFL just after it is forked.

Since shells follow this convention, applications can assume that they inherit the correct handling of these signals from the parent process. But every application has a responsibility not to mess up the handling of stop signals. Applications that disable the normal interpretation of the SUSP character should provide some other mechanism for the user to stop the job. When the user invokes this mechanism, the program should send a SIGTSTP signal to the process group of the process, not just to the process itself. See section Signaling Another Process.

Finally, each child process should call exec in the normal way. This is also the point at which redirection of the standard input and output channels should be handled. See section Duplicating Descriptors, for an explanation of how to do this.

Here is the function from the sample shell program that is responsible for launching a program. The function is executed by each child process immediately after it has been forked by the shell, and never returns.
void
launch_process (process *p, pid_t pgid,
                int infile, int outfile, int errfile,
                int foreground)
{
  pid_t pid;

  if (shell_is_interactive)
    {
      /* Put the process into the process group and give the process group
         the terminal, if appropriate.
         This has to be done both by the shell and in the individual
         child processes because of potential race conditions.  */
      pid = getpid ();
      if (pgid == 0) pgid = pid;
      setpgid (pid, pgid);
      if (foreground)
        tcsetpgrp (shell_terminal, pgid);

      /* Set the handling for job control signals back to the default.  */
      signal (SIGINT, SIG_DFL);
      signal (SIGQUIT, SIG_DFL);
      signal (SIGTSTP, SIG_DFL);
      signal (SIGTTIN, SIG_DFL);
      signal (SIGTTOU, SIG_DFL);
      signal (SIGCHLD, SIG_DFL);
    }

  /* Set the standard input/output channels of the new process.  */
  if (infile != STDIN_FILENO)
    {
      dup2 (infile, STDIN_FILENO);
      close (infile);
    }
  if (outfile != STDOUT_FILENO)
    {
      dup2 (outfile, STDOUT_FILENO);
      close (outfile);
    }
  if (errfile != STDERR_FILENO)
    {
      dup2 (errfile, STDERR_FILENO);
      close (errfile);
    }

  /* Exec the new process.  Make sure we exit.  */
  execvp (p->argv[0], p->argv);
  perror ("execvp");
  exit (1);
}
If the shell is not running interactively, this function does not do anything with process groups or signals. Remember that a shell not performing job control must keep all of its subprocesses in the same process group as the shell itself.

Next, here is the function that actually launches a complete job. After creating the child processes, this function calls some other functions to put the newly created job into the foreground or background; these are discussed in section Foreground and Background.
void
launch_job (job *j, int foreground)
{
  process *p;
  pid_t pid;
  int mypipe[2], infile, outfile;

  infile = j->stdin;
  for (p = j->first_process; p; p = p->next)
    {
      /* Set up pipes, if necessary.  */
      if (p->next)
        {
          if (pipe (mypipe) < 0)
            {
              perror ("pipe");
              exit (1);
            }
          outfile = mypipe[1];
        }
      else
        outfile = j->stdout;

      /* Fork the child processes.  */
      pid = fork ();
      if (pid == 0)
        /* This is the child process.  */
        launch_process (p, j->pgid, infile,
                        outfile, j->stderr, foreground);
      else if (pid < 0)
        {
          /* The fork failed.  */
          perror ("fork");
          exit (1);
        }
      else
        {
          /* This is the parent process.  */
          p->pid = pid;
          if (shell_is_interactive)
            {
              if (!j->pgid)
                j->pgid = pid;
              setpgid (pid, j->pgid);
            }
        }

      /* Clean up after pipes.  */
      if (infile != j->stdin)
        close (infile);
      if (outfile != j->stdout)
        close (outfile);
      infile = mypipe[0];
    }

  format_job_info (j, "launched");

  if (!shell_is_interactive)
    wait_for_job (j);
  else if (foreground)
    put_job_in_foreground (j, 0);
  else
    put_job_in_background (j, 0);
}
Foreground and Background

Now let's consider what actions must be taken by the shell when it launches a job into the foreground, and how this differs from what must be done when a background job is launched.

When a foreground job is launched, the shell must first give it access to the controlling terminal by calling tcsetpgrp. Then, the shell should wait for processes in that process group to terminate or stop. This is discussed in more detail in section Stopped and Terminated Jobs.

When all of the processes in the group have either completed or stopped, the shell should regain control of the terminal for its own process group by calling tcsetpgrp again. Since stop signals caused by I/O from a background process or a SUSP character typed by the user are sent to the process group, normally all the processes in the job stop together.

The foreground job may have left the terminal in a strange state, so the shell should restore its own saved terminal modes before continuing. In case the job is merely stopped, the shell should first save the current terminal modes so that it can restore them later if the job is continued. The functions for dealing with terminal modes are tcgetattr and tcsetattr; these are described in section Terminal Modes.

Here is the sample shell's function for doing all of this.
/* Put job j in the foreground.  If cont is nonzero,
   restore the saved terminal modes and send the process group a
   SIGCONT signal to wake it up before we block.  */

void
put_job_in_foreground (job *j, int cont)
{
  /* Put the job into the foreground.  */
  tcsetpgrp (shell_terminal, j->pgid);

  /* Send the job a continue signal, if necessary.  */
  if (cont)
    {
      tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes);
      if (kill (- j->pgid, SIGCONT) < 0)
        perror ("kill (SIGCONT)");
    }

  /* Wait for it to report.  */
  wait_for_job (j);

  /* Put the shell back in the foreground.  */
  tcsetpgrp (shell_terminal, shell_pgid);

  /* Restore the shell's terminal modes.  */
  tcgetattr (shell_terminal, &j->tmodes);
  tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes);
}
If the process group is launched as a background job, the shell should remain in the foreground itself and continue to read commands from the terminal.

In the sample shell, there is not much that needs to be done to put a job into the background. Here is the function it uses:
/* Put a job in the background.  If the cont argument is true, send
   the process group a SIGCONT signal to wake it up.  */

void
put_job_in_background (job *j, int cont)
{
  /* Send the job a continue signal, if necessary.  */
  if (cont)
    if (kill (-j->pgid, SIGCONT) < 0)
      perror ("kill (SIGCONT)");
}
Stopped and Terminated Jobs

When a foreground process is launched, the shell must block until all of the processes in that job have either terminated or stopped. It can do this by calling the waitpid function; see section Process Completion. Use the WUNTRACED option so that status is reported for processes that stop as well as processes that terminate.

The shell must also check on the status of background jobs so that it can report terminated and stopped jobs to the user; this can be done by calling waitpid with the WNOHANG option. A good place to put a such a check for terminated and stopped jobs is just before prompting for a new command.

The shell can also receive asynchronous notification that there is status information available for a child process by establishing a handler for SIGCHLD signals. See section Signal Handling.

In the sample shell program, the SIGCHLD signal is normally ignored. This is to avoid reentrancy problems involving the global data structures the shell manipulates. But at specific times when the shell is not using these data structures--such as when it is waiting for input on the terminal--it makes sense to enable a handler for SIGCHLD. The same function that is used to do the synchronous status checks (do_job_notification, in this case) can also be called from within this handler.

Here are the parts of the sample shell program that deal with checking the status of jobs and reporting the information to the user.
/* Store the status of the process pid that was returned by waitpid.
   Return 0 if all went well, nonzero otherwise.  */

int
mark_process_status (pid_t pid, int status)
{
  job *j;
  process *p;

  if (pid > 0)
    {
      /* Update the record for the process.  */
      for (j = first_job; j; j = j->next)
        for (p = j->first_process; p; p = p->next)
          if (p->pid == pid)
            {
              p->status = status;
              if (WIFSTOPPED (status))
                p->stopped = 1;
              else
                {
                  p->completed = 1;
                  if (WIFSIGNALED (status))
                    fprintf (stderr, "%d: Terminated by signal %d.\n",
                             (int) pid, WTERMSIG (p->status));
                }
              return 0;
             }
      fprintf (stderr, "No child process %d.\n", pid);
      return -1;
    }
  else if (pid == 0 || errno == ECHILD)
    /* No processes ready to report.  */
    return -1;
  else {
    /* Other weird errors.  */
    perror ("waitpid");
    return -1;
  }
}

/* Check for processes that have status information available,
   without blocking.  */

void
update_status (void)
{
  int status;
  pid_t pid;

  do
    pid = waitpid (WAIT_ANY, &status, WUNTRACED|WNOHANG);
  while (!mark_process_status (pid, status));
}

/* Check for processes that have status information available,
   blocking until all processes in the given job have reported.  */

void
wait_for_job (job *j)
{
  int status;
  pid_t pid;

  do
    pid = waitpid (WAIT_ANY, &status, WUNTRACED);
  while (!mark_process_status (pid, status)
         && !job_is_stopped (j)
         && !job_is_completed (j));
}

/* Format information about job status for the user to look at.  */

void
format_job_info (job *j, const char *status)
{
  fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command);
}

/* Notify the user about stopped or terminated jobs.
   Delete terminated jobs from the active job list.  */

void
do_job_notification (void)
{
  job *j, *jlast, *jnext;
  process *p;

  /* Update status information for child processes.  */
  update_status ();

  jlast = NULL;
  for (j = first_job; j; j = jnext)
    {
      jnext = j->next;

      /* If all processes have completed, tell the user the job has
         completed and delete it from the list of active jobs.  */
      if (job_is_completed (j)) {
        format_job_info (j, "completed");
        if (jlast)
          jlast->next = jnext;
        else
          first_job = jnext;
        free_job (j);
      }

      /* Notify the user about stopped jobs,
         marking them so that we won't do this more than once.  */
      else if (job_is_stopped (j) && !j->notified) {
        format_job_info (j, "stopped");
        j->notified = 1;
        jlast = j;
      }

      /* Don't say anything about jobs that are still running.  */
      else
        jlast = j;
    }
}
Continuing Stopped Jobs

The shell can continue a stopped job by sending a SIGCONT signal to its process group. If the job is being continued in the foreground, the shell should first invoke tcsetpgrp to give the job access to the terminal, and restore the saved terminal settings. After continuing a job in the foreground, the shell should wait for the job to stop or complete, as if the job had just been launched in the foreground.

The sample shell program handles both newly created and continued jobs with the same pair of functions, put_job_in_foreground and put_job_in_background. The definitions of these functions were given in section Foreground and Background. When continuing a stopped job, a nonzero value is passed as the cont argument to ensure that the SIGCONT signal is sent and the terminal modes reset, as appropriate.

This leaves only a function for updating the shell's internal bookkeeping about the job being continued:
/* Mark a stopped job J as being running again.  */

void
mark_job_as_running (job *j)
{
  Process *p;

  for (p = j->first_process; p; p = p->next)
    p->stopped = 0;
  j->notified = 0;
}

/* Continue the job J.  */

void
continue_job (job *j, int foreground)
{
  mark_job_as_running (j);
  if (foreground)
    put_job_in_foreground (j, 1);
  else
    put_job_in_background (j, 1);
}
The Missing Pieces

The code extracts for the sample shell included in this chapter are only a part of the entire shell program. In particular, nothing at all has been said about how job and program data structures are allocated and initialized.

Most real shells provide a complex user interface that has support for a command language; variables; abbreviations, substitutions, and pattern matching on file names; and the like. All of this is far too complicated to explain here! Instead, we have concentrated on showing how to implement the core process creation and job control functions that can be called from such a shell.

Here is a table summarizing the major entry points we have presented:

void init_shell (void)
Initialize the shell's internal state. See section Initializing the Shell.
void launch_job (job *j, int foreground)
Launch the job j as either a foreground or background job. See section Launching Jobs.
void do_job_notification (void)
Check for and report any jobs that have terminated or stopped. Can be called synchronously or within a handler for SIGCHLD signals. See section Stopped and Terminated Jobs.
void continue_job (job *j, int foreground)
Continue the job j. See section Continuing Stopped Jobs.
Of course, a real shell would also want to provide other functions for managing jobs. For example, it would be useful to have commands to list all active jobs or to send a signal (such as SIGKILL) to a job.

Functions for Job Control

This section contains detailed descriptions of the functions relating to job control.

Identifying the Controlling Terminal

You can use the ctermid function to get a file name that you can use to open the controlling terminal. In the GNU library, it returns the same string all the time: "/dev/tty". That is a special "magic" file name that refers to the controlling terminal of the current process (if it has one). To find the name of the specific terminal device, use ttyname; see section Identifying Terminals.

The function ctermid is declared in the header file `stdio.h'.

Function: char * ctermid (char *string)
The ctermid function returns a string containing the file name of the controlling terminal for the current process. If string is not a null pointer, it should be an array that can hold at least L_ctermid characters; the string is returned in this array. Otherwise, a pointer to a string in a static area is returned, which might get overwritten on subsequent calls to this function.

An empty string is returned if the file name cannot be determined for any reason. Even if a file name is returned, access to the file it represents is not guaranteed.

Macro: int L_ctermid
The value of this macro is an integer constant expression that represents the size of a string large enough to hold the file name returned by ctermid.

See also the isatty and ttyname functions, in section Identifying Terminals.

Process Group Functions

Here are descriptions of the functions for manipulating process groups. Your program should include the header files `sys/types.h' and `unistd.h' to use these functions.

Function: pid_t setsid (void)
The setsid function creates a new session. The calling process becomes the session leader, and is put in a new process group whose process group ID is the same as the process ID of that process. There are initially no other processes in the new process group, and no other process groups in the new session.

This function also makes the calling process have no controlling terminal.

The setsid function returns the new process group ID of the calling process if successful. A return value of -1 indicates an error. The following errno error conditions are defined for this function:

EPERM
The calling process is already a process group leader, or there is already another process group around that has the same process group ID.

Function: pid_t getsid (pid_t pid)

The getsid function returns the process group ID of the session leader of the specified process. If a pid is 0, the process group ID of the session leader of the current process is returned.

In case of error -1 is returned and errno is set. The following errno error conditions are defined for this function:

ESRCH
There is no process with the given process ID pid.
EPERM
The calling process and the process specified by pid are in different sessions, and the implementation doesn't allow to access the process group ID of the session leader of the process with ID pid from the calling process.
The getpgrp function has two definitions: one derived from BSD Unix, and one from the POSIX.1 standard. The feature test macros you have selected (see section Feature Test Macros) determine which definition you get. Specifically, you get the BSD version if you define _BSD_SOURCE; otherwise, you get the POSIX version if you define _POSIX_SOURCE or _GNU_SOURCE. Programs written for old BSD systems will not include `unistd.h', which defines getpgrp specially under _BSD_SOURCE. You must link such programs with the -lbsd-compat option to get the BSD definition.

POSIX.1 Function: pid_t getpgrp (void)
The POSIX.1 definition of getpgrp returns the process group ID of the calling process.

BSD Function: pid_t getpgrp (pid_t pid)
The BSD definition of getpgrp returns the process group ID of the process pid. You can supply a value of 0 for the pid argument to get information about the calling process.

System V Function: int getpgid (pid_t pid)

getpgid is the same as the BSD function getpgrp. It returns the process group ID of the process pid. You can supply a value of 0 for the pid argument to get information about the calling process.

In case of error -1 is returned and errno is set. The following errno error conditions are defined for this function:

ESRCH
There is no process with the given process ID pid. The calling process and the process specified by pid are in different sessions, and the implementation doesn't allow to access the process group ID of the process with ID pid from the calling process.

Function: int setpgid (pid_t pid, pid_t pgid)
The setpgid function puts the process pid into the process group pgid. As a special case, either pid or pgid can be zero to indicate the process ID of the calling process.

This function fails on a system that does not support job control. See section Job Control is Optional, for more information.

If the operation is successful, setpgid returns zero. Otherwise it returns -1. The following errno error conditions are defined for this function:

EACCES
The child process named by pid has executed an exec function since it was forked.
EINVAL
The value of the pgid is not valid.
ENOSYS
The system doesn't support job control.
EPERM
The process indicated by the pid argument is a session leader, or is not in the same session as the calling process, or the value of the pgid argument doesn't match a process group ID in the same session as the calling process.
ESRCH
The process indicated by the pid argument is not the calling process or a child of the calling process.

Function: int setpgrp (pid_t pid, pid_t pgid)
This is the BSD Unix name for setpgid. Both functions do exactly the same thing.

Functions for Controlling Terminal Access

These are the functions for reading or setting the foreground process group of a terminal. You should include the header files `sys/types.h' and `unistd.h' in your application to use these functions.

Although these functions take a file descriptor argument to specify the terminal device, the foreground job is associated with the terminal file itself and not a particular open file descriptor.

Function: pid_t tcgetpgrp (int filedes)
This function returns the process group ID of the foreground process group associated with the terminal open on descriptor filedes.

If there is no foreground process group, the return value is a number greater than 1 that does not match the process group ID of any existing process group. This can happen if all of the processes in the job that was formerly the foreground job have terminated, and no other job has yet been moved into the foreground.

In case of an error, a value of -1 is returned. The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
ENOSYS
The system doesn't support job control.
ENOTTY
The terminal file associated with the filedes argument isn't the controlling terminal of the calling process.

Function: int tcsetpgrp (int filedes, pid_t pgid)
This function is used to set a terminal's foreground process group ID. The argument filedes is a descriptor which specifies the terminal; pgid specifies the process group. The calling process must be a member of the same session as pgid and must have the same controlling terminal.

For terminal access purposes, this function is treated as output. If it is called from a background process on its controlling terminal, normally all processes in the process group are sent a SIGTTOU signal. The exception is if the calling process itself is ignoring or blocking SIGTTOU signals, in which case the operation is performed and no signal is sent.

If successful, tcsetpgrp returns 0. A return value of -1 indicates an error. The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
EINVAL
The pgid argument is not valid.
ENOSYS
The system doesn't support job control.
ENOTTY
The filedes isn't the controlling terminal of the calling process.
EPERM
The pgid isn't a process group in the same session as the calling process.

Function: pid_t tcgetsid (int fildes)
This function is used to obtain the process group ID of the session for which the terminal specified by fildes is the controlling terminal. If the call is successful the group ID is returned. Otherwise the return value is (pid_t) -1 and the global variable errno is set to the following value:
EBADF
The filedes argument is not a valid file descriptor.
ENOTTY
The calling process does not have a controlling terminal, or the file is not the controlling terminal.
System Databases and Name Service Switch

Various functions in the C Library need to be configured to work correctly in the local environment. Traditionally, this was done by using files (e.g., `/etc/passwd'), but other nameservices (like the Network Information Service (NIS) and the Domain Name Service (DNS)) became popular, and were hacked into the C library, usually with a fixed search order (see section `frobnicate' in The Jargon File).

The GNU C Library contains a cleaner solution of this problem. It is designed after a method used by Sun Microsystems in the C library of Solaris 2. GNU C Library follows their name and calls this scheme Name Service Switch (NSS).

Though the interface might be similar to Sun's version there is no common code. We never saw any source code of Sun's implementation and so the internal interface is incompatible. This also manifests in the file names we use as we will see later.

NSS Basics

The basic idea is to put the implementation of the different services offered to access the databases in separate modules. This has some advantages:

Contributors can add new services without adding them to GNU C Library.
The modules can be updated separately.
The C library image is smaller.

To fulfill the first goal above the ABI of the modules will be described below. For getting the implementation of a new service right it is important to understand how the functions in the modules get called. They are in no way designed to be used by the programmer directly. Instead the programmer should only use the documented and standardized functions to access the databases.

The databases available in the NSS are

aliases
Mail aliases
ethers
Ethernet numbers,
group
Groups of users, see section Group Database.
hosts
Host names and numbers, see section Host Names.
netgroup
Network wide list of host and users, see section Netgroup Database.
networks
Network names and numbers, see section Networks Database.
protocols
Network protocols, see section Protocols Database.
passwd
User passwords, see section User Database.
rpc
Remote procedure call names and numbers,
services
Network services, see section The Services Database.
shadow
Shadow user passwords,
There will be some more added later (automount, bootparams, netmasks, and publickey).

The NSS Configuration File

Somehow the NSS code must be told about the wishes of the user. For this reason there is the file `/etc/nsswitch.conf'. For each database this file contain a specification how the lookup process should work. The file could look like this:
# /etc/nsswitch.conf
#
# Name Service Switch configuration file.
#

passwd:     db files nis
shadow:     files
group:      db files nis

hosts:      files nisplus nis dns
networks:   nisplus [NOTFOUND=return] files

ethers:     nisplus [NOTFOUND=return] db files
protocols:  nisplus [NOTFOUND=return] db files
rpc:        nisplus [NOTFOUND=return] db files
services:   nisplus [NOTFOUND=return] db files
The first column is the database as you can guess from the table above. The rest of the line specifies how the lookup process works. Please note that you specify the way it works for each database individually. This cannot be done with the old way of a monolithic implementation.

The configuration specification for each database can contain two different items:

the service specification like files, db, or nis.
the reaction on lookup result like [NOTFOUND=return].

Services in the NSS configuration File

The above example file mentions four different services: files, db, nis, and nisplus. This does not mean these services are available on all sites and it does also not mean these are all the services which will ever be available.

In fact, these names are simply strings which the NSS code uses to find the implicitly addressed functions. The internal interface will be described later. Visible to the user are the modules which implement an individual service.

Assume the service name shall be used for a lookup. The code for this service is implemented in a module called `libnss_name'. On a system supporting shared libraries this is in fact a shared library with the name (for example) `libnss_name.so.2'. The number at the end is the currently used version of the interface which will not change frequently. Normally the user should not have to be cognizant of these files since they should be placed in a directory where they are found automatically. Only the names of all available services are important.

Actions in the NSS configuration

The second item in the specification gives the user much finer control on the lookup process. Action items are placed between two service names and are written within brackets. The general form is
[ ( !? status = action )+ ]
where
status => success | notfound | unavail | tryagain
action => return | continue
The case of the keywords is insignificant. The status values are the results of a call to a lookup function of a specific service. They mean

`success'
No error occurred and the wanted entry is returned. The default action for this is return.
`notfound'
The lookup process works ok but the needed value was not found. The default action is continue.
`unavail'
The service is permanently unavailable. This can either mean the needed file is not available, or, for DNS, the server is not available or does not allow queries. The default action is continue.
`tryagain'
The service is temporarily unavailable. This could mean a file is locked or a server currently cannot accept more connections. The default action is continue.
If we have a line like
ethers: nisplus [NOTFOUND=return] db files
this is equivalent to
ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
                 TRYAGAIN=continue]
        db      [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
                 TRYAGAIN=continue]
        files
(except that it would have to be written on one line). The default value for the actions are normally what you want, and only need to be changed in exceptional cases.

If the optional ! is placed before the status this means the following action is used for all statuses but status itself. I.e., ! is negation as in the C language (and others).

Before we explain the exception which makes this action item necessary one more remark: obviously it makes no sense to add another action item after the files service. Since there is no other service following the action always is return.

Now, why is this [NOTFOUND=return] action useful? To understand this we should know that the nisplus service is often complete; i.e., if an entry is not available in the NIS+ tables it is not available anywhere else. This is what is expressed by this action item: it is useless to examine further services since they will not give us a result.

The situation would be different if the NIS+ service is not available because the machine is booting. In this case the return value of the lookup function is not notfound but instead unavail. And as you can see in the complete form above: in this situation the db and files services are used. Neat, isn't it? The system administrator need not pay special care for the time the system is not completely ready to work (while booting or shutdown or network problems).

Notes on the NSS Configuration File

Finally a few more hints. The NSS implementation is not completely helpless if `/etc/nsswitch.conf' does not exist. For all supported databases there is a default value so it should normally be possible to get the system running even if the file is corrupted or missing.

For the hosts and networks databases the default value is dns [!UNAVAIL=return] files. I.e., the system is prepared for the DNS service not to be available but if it is available the answer it returns is definitive.

The passwd, group, and shadow databases are traditionally handled in a special way. The appropriate files in the `/etc' directory are read but if an entry with a name starting with a + character is found NIS is used. This kind of lookup remains possible by using the special lookup service compat and the default value for the three databases above is compat [NOTFOUND=return] files.

For all other databases the default value is nis [NOTFOUND=return] files. This solution give the best chance to be correct since NIS and file based lookup is used.

A second point is that the user should try to optimize the lookup process. The different service have different response times. A simple file look up on a local file could be fast, but if the file is long and the needed entry is near the end of the file this may take quite some time. In this case it might be better to use the db service which allows fast local access to large data sets.

Often the situation is that some global information like NIS must be used. So it is unavoidable to use service entries like nis etc. But one should avoid slow services like this if possible.

NSS Module Internals

Now it is time to describe what the modules look like. The functions contained in a module are identified by their names. I.e., there is no jump table or the like. How this is done is of no interest here; those interested in this topic should read about Dynamic Linking.

The Naming Scheme of the NSS Modules

The name of each function consist of various parts:

_nss_service_function

service of course corresponds to the name of the module this function is found in.(3) The function part is derived from the interface function in the C library itself. If the user calls the function gethostbyname and the service used is files the function
       _nss_files_gethostbyname_r
in the module
       libnss_files.so.2
is used. You see, what is explained above in not the whole truth. In fact the NSS modules only contain reentrant versions of the lookup functions. I.e., if the user would call the gethostbyname_r function this also would end in the above function. For all user interface functions the C library maps this call to a call to the reentrant function. For reentrant functions this is trivial since the interface is (nearly) the same. For the non-reentrant version The library keeps internal buffers which are used to replace the user supplied buffer.

I.e., the reentrant functions can have counterparts. No service module is forced to have functions for all databases and all kinds to access them. If a function is not available it is simply treated as if the function would return unavail (see section Actions in the NSS configuration).

The file name `libnss_files.so.2' would be on a Solaris 2 system `nss_files.so.2'. This is the difference mentioned above. Sun's NSS modules are usable as modules which get indirectly loaded only.

The NSS modules in the GNU C Library are prepared to be used as normal libraries themselves. This is not true at the moment, though. However, the organization of the name space in the modules does not make it impossible like it is for Solaris. Now you can see why the modules are still libraries.(4)

The Interface of the Function in NSS Modules

Now we know about the functions contained in the modules. It is now time to describe the types. When we mentioned the reentrant versions of the functions above, this means there are some additional arguments (compared with the standard, non-reentrant version). The prototypes for the non-reentrant and reentrant versions of our function above are:
struct hostent *gethostbyname (const char *name)

int gethostbyname_r (const char *name, struct hostent *result_buf,
                     char *buf, size_t buflen, struct hostent **result,
                     int *h_errnop)
The actual prototype of the function in the NSS modules in this case is
enum nss_status _nss_files_gethostbyname_r (const char *name,
                                            struct hostent *result_buf,
                                            char *buf, size_t buflen,
                                            int *errnop, int *h_errnop)
I.e., the interface function is in fact the reentrant function with the change of the return value and the omission of the result parameter. While the user-level function returns a pointer to the result the reentrant function return an enum nss_status value:

NSS_STATUS_TRYAGAIN
numeric value -2
NSS_STATUS_UNAVAIL
numeric value -1
NSS_STATUS_NOTFOUND
numeric value 0
NSS_STATUS_SUCCESS
numeric value 1
Now you see where the action items of the `/etc/nsswitch.conf' file are used.

If you study the source code you will find there is a fifth value: NSS_STATUS_RETURN. This is an internal use only value, used by a few functions in places where none of the above value can be used. If necessary the source code should be examined to learn about the details.

In case the interface function has to return an error it is important that the correct error code is stored in *errnop. Some return status value have only one associated error code, others have more.

@multitable @columnfractions .3 .2 .50
NSS_STATUS_TRYAGAIN @tab EAGAIN @tab One of the functions used ran temporarily out of resources or a service is currently not available.
@tab ERANGE @tab The provided buffer is not large enough. The function should be called again with a larger buffer.
NSS_STATUS_UNAVAIL @tab ENOENT @tab A necessary input file cannot be found.
NSS_STATUS_NOTFOUND @tab ENOENT @tab The requested entry is not available. These are proposed values. There can be other error codes and the described error codes can have different meaning. With one exception: when returning NSS_STATUS_TRYAGAIN the error code ERANGE must mean that the user provided buffer is too small. Everything is non-critical. The above function has something special which is missing for almost all the other module functions. There is an argument h_errnop. This points to a variable which will be filled with the error code in case the execution of the function fails for some reason. The reentrant function cannot use the global variable h_errno; gethostbyname calls gethostbyname_r with the last argument set to &h_errno. The getXXXbyYYY functions are the most important functions in the NSS modules. But there are others which implement the other ways to access system databases (say for the password database, there are setpwent, getpwent, and endpwent). These will be described in more detail later. Here we give a general way to determine the signature of the module function:

the return value is int;
the name is as explained in see section The Naming Scheme of the NSS Modules;
the first arguments are identical to the arguments of the non-reentrant function;
the next three arguments are:
STRUCT_TYPE *result_buf
pointer to buffer where the result is stored. STRUCT_TYPE is normally a struct which corresponds to the database.
char *buffer
pointer to a buffer where the function can store additional adata for the result etc.
size_t buflen
length of the buffer pointed to by buffer.
possibly a last argument h_errnop, for the host name and network name lookup functions.
This table is correct for all functions but the set...ent and end...ent functions.
Extending NSS

One of the advantages of NSS mentioned above is that it can be extended quite easily. There are two ways in which the extension can happen: adding another database or adding another service. The former is normally done only by the C library developers. It is here only important to remember that adding another database is independent from adding another service because a service need not support all databases or lookup functions.

A designer/implementor of a new service is therefore free to choose the databases s/he is interested in and leave the rest for later (or completely aside).

Adding another Service to NSS

The sources for a new service need not (and should not) be part of the GNU C Library itself. The developer retains complete control over the sources and its development. The links between the C library and the new service module consists solely of the interface functions.

Each module is designed following a specific interface specification. For now the version is 2 (the interface in version 1 was not adequate) and this manifests in the version number of the shared library object of the NSS modules: they have the extension .2. If the interface changes again in an incompatible way, this number will be increased. Modules using the old interface will still be usable.

Developers of a new service will have to make sure that their module is created using the correct interface number. This means the file itself must have the correct name and on ElF systems the soname (Shared Object Name) must also have this number. Building a module from a bunch of object files on an ELF system using GNU CC could be done like this:
gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS
section `Link Options' in GNU CC, to learn more about this command line.

To use the new module the library must be able to find it. This can be achieved by using options for the dynamic linker so that it will search the directory where the binary is placed. For an ELF system this could be done by adding the wanted directory to the value of LD_LIBRARY_PATH.

But this is not always possible since some programs (those which run under IDs which do not belong to the user) ignore this variable. Therefore the stable version of the module should be placed into a directory which is searched by the dynamic linker. Normally this should be the directory `$prefix/lib', where `$prefix' corresponds to the value given to configure using the --prefix option. But be careful: this should only be done if it is clear the module does not cause any harm. System administrators should be careful.

Internals of the NSS Module Functions

Until now we only provided the syntactic interface for the functions in the NSS module. In fact there is not much more we can say since the implementation obviously is different for each function. But a few general rules must be followed by all functions.

In fact there are four kinds of different functions which may appear in the interface. All derive from the traditional ones for system databases. db in the following table is normally an abbreviation for the database (e.g., it is pw for the password database).

enum nss_status _nss_database_setdbent (void)
This function prepares the service for following operations. For a simple file based lookup this means files could be opened, for other services this function simply is a noop. One special case for this function is that it takes an additional argument for some databases (i.e., the interface is int setdbent (int)). section Host Names, which describes the sethostent function. The return value should be NSS_STATUS_SUCCESS or according to the table above in case of an error (see section The Interface of the Function in NSS Modules).
enum nss_status _nss_database_enddbent (void)
This function simply closes all files which are still open or removes buffer caches. If there are no files or buffers to remove this is again a simple noop. There normally is no return value different to NSS_STATUS_SUCCESS.
enum nss_status _nss_database_getdbent_r (STRUCTURE *result, char *buffer, size_t buflen, int *errnop)
Since this function will be called several times in a row to retrieve one entry after the other it must keep some kind of state. But this also means the functions are not really reentrant. They are reentrant only in that simultaneous calls to this function will not try to write the retrieved data in the same place (as it would be the case for the non-reentrant functions); instead, it writes to the structure pointed to by the result parameter. But the calls share a common state and in the case of a file access this means they return neighboring entries in the file. The buffer of length buflen pointed to by buffer can be used for storing some additional data for the result. It is not guaranteed that the same buffer will be passed for the next call of this function. Therefore one must not misuse this buffer to save some state information from one call to another. Before the function returns the implementation should store the value of the local errno variable in the variable pointed to be errnop. This is important to guarantee the module working in statically linked programs. As explained above this function could also have an additional last argument. This depends on the database used; it happens only for host and networks. The function shall return NSS_STATUS_SUCCESS as long as there are more entries. When the last entry was read it should return NSS_STATUS_NOTFOUND. When the buffer given as an argument is too small for the data to be returned NSS_STATUS_TRYAGAIN should be returned. When the service was not formerly initialized by a call to _nss_DATABASE_setdbent all return value allowed for this function can also be returned here.
enum nss_status _nss_DATABASE_getdbbyXX_r (PARAMS, STRUCTURE *result, char *buffer, size_t buflen, int *errnop)
This function shall return the entry from the database which is addressed by the PARAMS. The type and number of these arguments vary. It must be individually determined by looking to the user-level interface functions. All arguments given to the non-reentrant version are here described by PARAMS. The result must be stored in the structure pointed to by result. If there is additional data to return (say strings, where the result structure only contains pointers) the function must use the buffer or length buflen. There must not be any references to non-constant global data. The implementation of this function should honour the stayopen flag set by the setDBent function whenever this makes sense. Before the function returns the implementation should store the value of the local errno variable in the variable pointed to be errnop. This is important to guarantee the module working in statically linked programs. Again, this function takes an additional last argument for the host and networks database. The return value should as always follow the rules given above (see section The Interface of the Function in NSS Modules).
Users and Groups

Every user who can log in on the system is identified by a unique number called the user ID. Each process has an effective user ID which says which user's access permissions it has.

Users are classified into groups for access control purposes. Each process has one or more group ID values which say which groups the process can use for access to files.

The effective user and group IDs of a process collectively form its persona. This determines which files the process can access. Normally, a process inherits its persona from the parent process, but under special circumstances a process can change its persona and thus change its access permissions.

Each file in the system also has a user ID and a group ID. Access control works by comparing the user and group IDs of the file with those of the running process.

The system keeps a database of all the registered users, and another database of all the defined groups. There are library functions you can use to examine these databases.

User and Group IDs

Each user account on a computer system is identified by a user name (or login name) and user ID. Normally, each user name has a unique user ID, but it is possible for several login names to have the same user ID. The user names and corresponding user IDs are stored in a data base which you can access as described in section User Database.

Users are classified in groups. Each user name belongs to one default group and may also belong to any number of supplementary groups. Users who are members of the same group can share resources (such as files) that are not accessible to users who are not a member of that group. Each group has a group name and group ID. See section Group Database, for how to find information about a group ID or group name.

The Persona of a Process

At any time, each process has an effective user ID, a effective group ID, and a set of supplementary group IDs. These IDs determine the privileges of the process. They are collectively called the persona of the process, because they determine "who it is" for purposes of access control.

Your login shell starts out with a persona which consists of your user ID, your default group ID, and your supplementary group IDs (if you are in more than one group). In normal circumstances, all your other processes inherit these values.

A process also has a real user ID which identifies the user who created the process, and a real group ID which identifies that user's default group. These values do not play a role in access control, so we do not consider them part of the persona. But they are also important.

Both the real and effective user ID can be changed during the lifetime of a process. See section Why Change the Persona of a Process?.

For details on how a process's effective user ID and group IDs affect its permission to access files, see section How Your Access to a File is Decided.

The effective user ID of a process also controls permissions for sending signals using the kill function. See section Signaling Another Process.

Finally, there are many operations which can only be performed by a process whose effective user ID is zero. A process with this user ID is a privileged process. Commonly the user name root is associated with user ID 0, but there may be other user names with this ID.

Why Change the Persona of a Process?

The most obvious situation where it is necessary for a process to change its user and/or group IDs is the login program. When login starts running, its user ID is root. Its job is to start a shell whose user and group IDs are those of the user who is logging in. (To accomplish this fully, login must set the real user and group IDs as well as its persona. But this is a special case.)

The more common case of changing persona is when an ordinary user program needs access to a resource that wouldn't ordinarily be accessible to the user actually running it.

For example, you may have a file that is controlled by your program but that shouldn't be read or modified directly by other users, either because it implements some kind of locking protocol, or because you want to preserve the integrity or privacy of the information it contains. This kind of restricted access can be implemented by having the program change its effective user or group ID to match that of the resource.

Thus, imagine a game program that saves scores in a file. The game program itself needs to be able to update this file no matter who is running it, but if users can write the file without going through the game, they can give themselves any scores they like. Some people consider this undesirable, or even reprehensible. It can be prevented by creating a new user ID and login name (say, games) to own the scores file, and make the file writable only by this user. Then, when the game program wants to update this file, it can change its effective user ID to be that for games. In effect, the program must adopt the persona of games so it can write the scores file.

How an Application Can Change Persona

The ability to change the persona of a process can be a source of unintentional privacy violations, or even intentional abuse. Because of the potential for problems, changing persona is restricted to special circumstances.

You can't arbitrarily set your user ID or group ID to anything you want; only privileged processes can do that. Instead, the normal way for a program to change its persona is that it has been set up in advance to change to a particular user or group. This is the function of the setuid and setgid bits of a file's access mode. See section The Mode Bits for Access Permission.

When the setuid bit of an executable file is on, executing that file gives the process a third user ID: the file user ID. This ID is set to the owner ID of the file. The system then changes the effective user ID to the file user ID. The real user ID remains as it was. Likewise, if the setgid bit is on, the process is given a file group ID equal to the group ID of the file, and its effective group ID is changed to the file group ID.

If a process has a file ID (user or group), then it can at any time change its effective ID to its real ID and back to its file ID. Programs use this feature to relinquish their special privileges except when they actually need them. This makes it less likely that they can be tricked into doing something inappropriate with their privileges.

Portability Note: Older systems do not have file IDs. To determine if a system has this feature, you can test the compiler define _POSIX_SAVED_IDS. (In the POSIX standard, file IDs are known as saved IDs.)

See section File Attributes, for a more general discussion of file modes and accessibility.

Reading the Persona of a Process

Here are detailed descriptions of the functions for reading the user and group IDs of a process, both real and effective. To use these facilities, you must include the header files `sys/types.h' and `unistd.h'.

Data Type: uid_t
This is an integer data type used to represent user IDs. In the GNU library, this is an alias for unsigned int.

Data Type: gid_t
This is an integer data type used to represent group IDs. In the GNU library, this is an alias for unsigned int.

Function: uid_t getuid (void)
The getuid function returns the real user ID of the process.

Function: gid_t getgid (void)
The getgid function returns the real group ID of the process.

Function: uid_t geteuid (void)
The geteuid function returns the effective user ID of the process.

Function: gid_t getegid (void)
The getegid function returns the effective group ID of the process.

Function: int getgroups (int count, gid_t *groups)
The getgroups function is used to inquire about the supplementary group IDs of the process. Up to count of these group IDs are stored in the array groups; the return value from the function is the number of group IDs actually stored. If count is smaller than the total number of supplementary group IDs, then getgroups returns a value of -1 and errno is set to EINVAL.

If count is zero, then getgroups just returns the total number of supplementary group IDs. On systems that do not support supplementary groups, this will always be zero.

Here's how to use getgroups to read all the supplementary group IDs:
gid_t *
read_all_groups (void)
{
  int ngroups = getgroups (0, NULL);
  gid_t *groups
    = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
  int val = getgroups (ngroups, groups);
  if (val < 0)
    {
      free (groups);
      return NULL;
    }
  return groups;
}
Setting the User ID

This section describes the functions for altering the user ID (real and/or effective) of a process. To use these facilities, you must include the header files `sys/types.h' and `unistd.h'.

Function: int seteuid (uid_t neweuid)
This function sets the effective user ID of a process to newuid, provided that the process is allowed to change its effective user ID. A privileged process (effective user ID zero) can change its effective user ID to any legal value. An unprivileged process with a file user ID can change its effective user ID to its real user ID or to its file user ID. Otherwise, a process may not change its effective user ID at all.

The seteuid function returns a value of 0 to indicate successful completion, and a value of -1 to indicate an error. The following errno error conditions are defined for this function:

EINVAL
The value of the newuid argument is invalid.
EPERM
The process may not change to the specified ID.
Older systems (those without the _POSIX_SAVED_IDS feature) do not have this function.

Function: int setuid (uid_t newuid)
If the calling process is privileged, this function sets both the real and effective user ID of the process to newuid. It also deletes the file user ID of the process, if any. newuid may be any legal value. (Once this has been done, there is no way to recover the old effective user ID.)

If the process is not privileged, and the system supports the _POSIX_SAVED_IDS feature, then this function behaves like seteuid.

The return values and error conditions are the same as for seteuid.

Function: int setreuid (uid_t ruid, uid_t euid)
This function sets the real user ID of the process to ruid and the effective user ID to euid. If ruid is -1, it means not to change the real user ID; likewise if euid is -1, it means not to change the effective user ID.

The setreuid function exists for compatibility with 4.3 BSD Unix, which does not support file IDs. You can use this function to swap the effective and real user IDs of the process. (Privileged processes are not limited to this particular usage.) If file IDs are supported, you should use that feature instead of this function. See section Enabling and Disabling Setuid Access.

The return value is 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EPERM
The process does not have the appropriate privileges; you do not have permission to change to the specified ID.
Setting the Group IDs

This section describes the functions for altering the group IDs (real and effective) of a process. To use these facilities, you must include the header files `sys/types.h' and `unistd.h'.

Function: int setegid (gid_t newgid)
This function sets the effective group ID of the process to newgid, provided that the process is allowed to change its group ID. Just as with seteuid, if the process is privileged it may change its effective group ID to any value; if it isn't, but it has a file group ID, then it may change to its real group ID or file group ID; otherwise it may not change its effective group ID.

Note that a process is only privileged if its effective user ID is zero. The effective group ID only affects access permissions.

The return values and error conditions for setegid are the same as those for seteuid.

This function is only present if _POSIX_SAVED_IDS is defined.

Function: int setgid (gid_t newgid)
This function sets both the real and effective group ID of the process to newgid, provided that the process is privileged. It also deletes the file group ID, if any.

If the process is not privileged, then setgid behaves like setegid.

The return values and error conditions for setgid are the same as those for seteuid.

Function: int setregid (gid_t rgid, gid_t egid)
This function sets the real group ID of the process to rgid and the effective group ID to egid. If rgid is -1, it means not to change the real group ID; likewise if egid is -1, it means not to change the effective group ID.

The setregid function is provided for compatibility with 4.3 BSD Unix, which does not support file IDs. You can use this function to swap the effective and real group IDs of the process. (Privileged processes are not limited to this usage.) If file IDs are supported, you should use that feature instead of using this function. See section Enabling and Disabling Setuid Access.

The return values and error conditions for setregid are the same as those for setreuid.

setuid and setgid behave differently depending on whether the effective user ID at the time is zero. If it is not zero, they behave like seteuid and setegid. If it is, they change both effective and real IDs and delete the file ID. To avoid confusion, we recommend you always use seteuid and setegid except when you know the effective user ID is zero and your intent is to change the persona permanently. This case is rare--most of the programs that need it, such as login and su, have already been written.

Note that if your program is setuid to some user other than root, there is no way to drop privileges permanently.

The system also lets privileged processes change their supplementary group IDs. To use setgroups or initgroups, your programs should include the header file `grp.h'.

Function: int setgroups (size_t count, gid_t *groups)
This function sets the process's supplementary group IDs. It can only be called from privileged processes. The count argument specifies the number of group IDs in the array groups.

This function returns 0 if successful and -1 on error. The following errno error conditions are defined for this function:

EPERM
The calling process is not privileged.

Function: int initgroups (const char *user, gid_t gid)
The initgroups function sets the process's supplementary group IDs to be the normal default for the user name user. If gid is not -1, it includes that group also.

This function works by scanning the group database for all the groups user belongs to. It then calls setgroups with the list it has constructed.

The return values and error conditions are the same as for setgroups.

Enabling and Disabling Setuid Access

A typical setuid program does not need its special access all of the time. It's a good idea to turn off this access when it isn't needed, so it can't possibly give unintended access.

If the system supports the _POSIX_SAVED_IDS feature, you can accomplish this with seteuid. When the game program starts, its real user ID is jdoe, its effective user ID is games, and its saved user ID is also games. The program should record both user ID values once at the beginning, like this:
user_user_id = getuid ();
game_user_id = geteuid ();
Then it can turn off game file access with
seteuid (user_user_id);
and turn it on with
seteuid (game_user_id);
Throughout this process, the real user ID remains jdoe and the file user ID remains games, so the program can always set its effective user ID to either one.

On other systems that don't support file user IDs, you can turn setuid access on and off by using setreuid to swap the real and effective user IDs of the process, as follows:
setreuid (geteuid (), getuid ());
This special case is always allowed--it cannot fail.

Why does this have the effect of toggling the setuid access? Suppose a game program has just started, and its real user ID is jdoe while its effective user ID is games. In this state, the game can write the scores file. If it swaps the two uids, the real becomes games and the effective becomes jdoe; now the program has only jdoe access. Another swap brings games back to the effective user ID and restores access to the scores file.

In order to handle both kinds of systems, test for the saved user ID feature with a preprocessor conditional, like this:
#ifdef _POSIX_SAVED_IDS
  setuid (user_user_id);
#else
  setreuid (geteuid (), getuid ());
#endif
Setuid Program Example

Here's an example showing how to set up a program that changes its effective user ID.

This is part of a game program called caber-toss that manipulates a file `scores' that should be writable only by the game program itself. The program assumes that its executable file will be installed with the setuid bit set and owned by the same user as the `scores' file. Typically, a system administrator will set up an account like games for this purpose.

The executable file is given mode 4755, so that doing an `ls -l' on it produces output like:
-rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss
The setuid bit shows up in the file modes as the `s'.

The scores file is given mode 644, and doing an `ls -l' on it shows:
-rw-r--r--  1 games           0 Jul 31 15:33 scores
Here are the parts of the program that show how to set up the changed user ID. This program is conditionalized so that it makes use of the file IDs feature if it is supported, and otherwise uses setreuid to swap the effective and real user IDs.
#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>

/* Remember the effective and real UIDs. */

static uid_t euid, ruid;

/* Restore the effective UID to its original value. */

void
do_setuid (void)
{
  int status;

#ifdef _POSIX_SAVED_IDS
  status = seteuid (euid);
#else
  status = setreuid (ruid, euid);
#endif
  if (status < 0) {
    fprintf (stderr, "Couldn't set uid.\n");
    exit (status);
    }
}

/* Set the effective UID to the real UID. */

void
undo_setuid (void)
{
  int status;

#ifdef _POSIX_SAVED_IDS
  status = seteuid (ruid);
#else
  status = setreuid (euid, ruid);
#endif
  if (status < 0) {
    fprintf (stderr, "Couldn't set uid.\n");
    exit (status);
    }
}

/* Main program. */

int
main (void)
{
  /* Remember the real and effective user IDs.  */
  ruid = getuid ();
  euid = geteuid ();
  undo_setuid ();

  /* Do the game and record the score.  */
  ...
}
Notice how the first thing the main function does is to set the effective user ID back to the real user ID. This is so that any other file accesses that are performed while the user is playing the game use the real user ID for determining permissions. Only when the program needs to open the scores file does it switch back to the file user ID, like this:
/* Record the score. */

int
record_score (int score)
{
  FILE *stream;
  char *myname;

  /* Open the scores file. */
  do_setuid ();
  stream = fopen (SCORES_FILE, "a");
  undo_setuid ();

  /* Write the score to the file. */
  if (stream)
    {
      myname = cuserid (NULL);
      if (score < 0)
        fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
      else
        fprintf (stream, "%10s: %d feet.\n", myname, score);
      fclose (stream);
      return 0;
    }
  else
    return -1;
}
Tips for Writing Setuid Programs

It is easy for setuid programs to give the user access that isn't intended--in fact, if you want to avoid this, you need to be careful. Here are some guidelines for preventing unintended access and minimizing its consequences when it does occur:

Don't have setuid programs with privileged user IDs such as root unless it is absolutely necessary. If the resource is specific to your particular program, it's better to define a new, nonprivileged user ID or group ID just to manage that resource. It's better if you can write your program to use a special group than a special user.
Be cautious about using the exec functions in combination with changing the effective user ID. Don't let users of your program execute arbitrary programs under a changed user ID. Executing a shell is especially bad news. Less obviously, the execlp and execvp functions are a potential risk (since the program they execute depends on the user's PATH environment variable). If you must exec another program under a changed ID, specify an absolute file name (see section File Name Resolution) for the executable, and make sure that the protections on that executable and all containing directories are such that ordinary users cannot replace it with some other program. You should also check the arguments passed to the program to make sure they do not have unexpected effects. Likewise, you should examine the environment variables. Decide which arguments and variables are safe, and reject all others. You should never use system in a privileged program, because it invokes a shell.
Only use the user ID controlling the resource in the part of the program that actually uses that resource. When you're finished with it, restore the effective user ID back to the actual user's user ID. See section Enabling and Disabling Setuid Access.
If the setuid part of your program needs to access other files besides the controlled resource, it should verify that the real user would ordinarily have permission to access those files. You can use the access function (see section How Your Access to a File is Decided) to check this; it uses the real user and group IDs, rather than the effective IDs.

Identifying Who Logged In

You can use the functions listed in this section to determine the login name of the user who is running a process, and the name of the user who logged in the current session. See also the function getuid and friends (see section Reading the Persona of a Process). How this information is collected by the system and how to control/add/remove information from the background storage is described in section The User Accounting Database.

The getlogin function is declared in `unistd.h', while cuserid and L_cuserid are declared in `stdio.h'.

Function: char * getlogin (void)
The getlogin function returns a pointer to a string containing the name of the user logged in on the controlling terminal of the process, or a null pointer if this information cannot be determined. The string is statically allocated and might be overwritten on subsequent calls to this function or to cuserid.

Function: char * cuserid (char *string)
The cuserid function returns a pointer to a string containing a user name associated with the effective ID of the process. If string is not a null pointer, it should be an array that can hold at least L_cuserid characters; the string is returned in this array. Otherwise, a pointer to a string in a static area is returned. This string is statically allocated and might be overwritten on subsequent calls to this function or to getlogin.

The use of this function is deprecated since it is marked to be withdrawn in XPG4.2 and has already been removed from newer revisions of POSIX.1.

Macro: int L_cuserid
An integer constant that indicates how long an array you might need to store a user name.

These functions let your program identify positively the user who is running or the user who logged in this session. (These can differ when setuid programs are involved; see section The Persona of a Process.) The user cannot do anything to fool these functions.

For most purposes, it is more useful to use the environment variable LOGNAME to find out who the user is. This is more flexible precisely because the user can set LOGNAME arbitrarily. See section Standard Environment Variables.

The User Accounting Database

Most Unix-like operating systems keep track of logged in users by maintaining a user accounting database. This user accounting database stores for each terminal, who has logged on, at what time, the process ID of the user's login shell, etc., etc., but also stores information about the run level of the system, the time of the last system reboot, and possibly more.

The user accounting database typically lives in `/etc/utmp', `/var/adm/utmp' or `/var/run/utmp'. However, these files should never be accessed directly. For reading information from and writing information to the user accounting database, the functions described in this section should be used.

Manipulating the User Accounting Database

These functions and the corresponding data structures are declared in the header file `utmp.h'.

Data Type: struct exit_status
The exit_status data structure is used to hold information about the exit status of processes marked as DEAD_PROCESS in the user accounting database.

short int e_termination
The exit status of the process.
short int e_exit
The exit status of the process.

Data Type: struct utmp
The utmp data structure is used to hold information about entries in the user accounting database. On the GNU system it has the following members:

short int ut_type
Specifies the type of login; one of EMPTY, RUN_LVL, BOOT_TIME, OLD_TIME, NEW_TIME, INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, DEAD_PROCESS or ACCOUNTING.
pid_t ut_pid
The process ID number of the login process.
char ut_line[]
The device name of the tty (without `/dev/').
char ut_id[]
The inittab ID of the process.
char ut_user[]
The user's login name.
char ut_host[]
The name of the host from which the user logged in.
struct exit_status ut_exit
The exit status of a process marked as DEAD_PROCESS.
long ut_session
The Session ID, used for windowing.
struct timeval ut_tv
Time the entry was made. For entries of type OLD_TIME this is the time when the system clock changed, and for entries of type NEW_TIME this is the time the system clock was set to.
int32_t ut_addr_v6[4]
The Internet address of a remote host.
The ut_type, ut_pid, ut_id, ut_tv, and ut_host fields are not available on all systems. Portable applications therefore should be prepared for these situations. To help doing this the `utmp.h' header provides macros _HAVE_UT_TYPE, _HAVE_UT_PID, _HAVE_UT_ID, _HAVE_UT_TV, and _HAVE_UT_HOST if the respective field is available. The programmer can handle the situations by using #ifdef in the program code.

The following macros are defined for use as values for the ut_type member of the utmp structure. The values are integer constants.

EMPTY
This macro is used to indicate that the entry contains no valid user accounting information.
RUN_LVL
This macro is used to identify the systems runlevel.
BOOT_TIME
This macro is used to identify the time of system boot.
OLD_TIME
This macro is used to identify the time when the system clock changed.
NEW_TIME
This macro is used to identify the time after the system changed.
INIT_PROCESS
This macro is used to identify a process spawned by the init process.
LOGIN_PROCESS
This macro is used to identify the session leader of a logged in user.
USER_PROCESS
This macro is used to identify a user process.
DEAD_PROCESS
This macro is used to identify a terminated process.
ACCOUNTING
???
The size of the ut_line, ut_id, ut_user and ut_host arrays can be found using the sizeof operator.

Many older systems have, instead of an ut_tv member, an ut_time member, usually of type time_t, for representing the time associated with the entry. Therefore, for backwards compatibility only, `utmp.h' defines ut_time as an alias for ut_tv.tv_sec.

Function: void setutent (void)
This function opens the user accounting database to begin scanning it. You can then call getutent, getutid or getutline to read entries and pututline to write entries.

If the database is already open, it resets the input to the beginning of the database.

Function: struct utmp * getutent (void)
The getutent function reads the next entry from the user accounting database. It returns a pointer to the entry, which is statically allocated and may be overwritten by subsequent calls to getutent. You must copy the contents of the structure if you wish to save the information or you can use the getutent_r function which stores the data in a user-provided buffer.

A null pointer is returned in case no further entry is available.

Function: void endutent (void)
This function closes the user accounting database.

Function: struct utmp * getutid (const struct utmp *id)
This function searches forward from the current point in the database for an entry that matches id. If the ut_type member of the id structure is one of RUN_LVL, BOOT_TIME, OLD_TIME or NEW_TIME the entries match if the ut_type members are identical. If the ut_type member of the id structure is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS or DEAD_PROCESS, the entries match if the ut_type member of the entry read from the database is one of these four, and the ut_id members match. However if the ut_id member of either the id structure or the entry read from the database is empty it checks if the ut_line members match instead. If a matching entry is found, getutid returns a pointer to the entry, which is statically allocated, and may be overwritten by a subsequent call to getutent, getutid or getutline. You must copy the contents of the structure if you wish to save the information.

A null pointer is returned in case the end of the database is reached without a match.

The getutid function may cache the last read entry. Therefore, if you are using getutid to search for multiple occurrences, it is necessary to zero out the static data after each call. Otherwise getutid could just return a pointer to the same entry over and over again.

Function: struct utmp * getutline (const struct utmp *line)
This function searches forward from the current point in the database until it finds an entry whose ut_type value is LOGIN_PROCESS or USER_PROCESS, and whose ut_line member matches the ut_line member of the line structure. If it finds such an entry, it returns a pointer to the entry which is statically allocated, and may be overwritten by a subsequent call to getutent, getutid or getutline. You must copy the contents of the structure if you wish to save the information.

A null pointer is returned in case the end of the database is reached without a match.

The getutline function may cache the last read entry. Therefore if you are using getutline to search for multiple occurrences, it is necessary to zero out the static data after each call. Otherwise getutline could just return a pointer to the same entry over and over again.

Function: struct utmp * pututline (const struct utmp *utmp)
The pututline function inserts the entry *utmp at the appropriate place in the user accounting database. If it finds that it is not already at the correct place in the database, it uses getutid to search for the position to insert the entry, however this will not modify the static structure returned by getutent, getutid and getutline. If this search fails, the entry is appended to the database.

The pututline function returns a pointer to a copy of the entry inserted in the user accounting database, or a null pointer if the entry could not be added. The following errno error conditions are defined for this function:

EPERM
The process does not have the appropriate privileges; you cannot modify the user accounting database.
All the get* functions mentioned before store the information they return in a static buffer. This can be a problem in multi-threaded programs since the data returned for the request is overwritten by the return value data in another thread. Therefore the GNU C Library provides as extensions three more functions which return the data in a user-provided buffer.

Function: int getutent_r (struct utmp *buffer, struct utmp **result)
The getutent_r is equivalent to the getutent function. It returns the next entry from the database. But instead of storing the information in a static buffer it stores it in the buffer pointed to by the parameter buffer.

If the call was successful, the function returns 0 and the pointer variable pointed to by the parameter result contains a pointer to the buffer which contains the result (this is most probably the same value as buffer). If something went wrong during the execution of getutent_r the function returns -1.

This function is a GNU extension.

Function: int getutid_r (const struct utmp *id, struct utmp *buffer, struct utmp **result)
This function retrieves just like getutid the next entry matching the information stored in id. But the result is stored in the buffer pointed to by the parameter buffer.

If successful the function returns 0 and the pointer variable pointed to by the parameter result contains a pointer to the buffer with the result (probably the same as result. If not successful the function return -1.

This function is a GNU extension.

Function: int getutline_r (const struct utmp *line, struct utmp *buffer, struct utmp **result)
This function retrieves just like getutline the next entry matching the information stored in line. But the result is stored in the buffer pointed to by the parameter buffer.

If successful the function returns 0 and the pointer variable pointed to by the parameter result contains a pointer to the buffer with the result (probably the same as result. If not successful the function return -1.

This function is a GNU extension.

In addition to the user accounting database, most systems keep a number of similar databases. For example most systems keep a log file with all previous logins (usually in `/etc/wtmp' or `/var/log/wtmp').

For specifying which database to examine, the following function should be used.

Function: int utmpname (const char *file)
The utmpname function changes the name of the database to be examined to file, and closes any previously opened database. By default getutent, getutid, getutline and pututline read from and write to the user accounting database.

The following macros are defined for use as the file argument:

Macro: char * _PATH_UTMP
This macro is used to specify the user accounting database.

Macro: char * _PATH_WTMP
This macro is used to specify the user accounting log file.

The utmpname function returns a value of 0 if the new name was successfully stored, and a value of -1 to indicate an error. Note that utmpname does not try to open the database, and that therefore the return value does not say anything about whether the database can be successfully opened.

Specially for maintaining log-like databases the GNU C Library provides the following function:

Function: void updwtmp (const char *wtmp_file, const struct utmp *utmp)
The updwtmp function appends the entry *utmp to the database specified by wtmp_file. For possible values for the wtmp_file argument see the utmpname function.

Portability Note: Although many operating systems provide a subset of these functions, they are not standardized. There are often subtle differences in the return types, and there are considerable differences between the various definitions of struct utmp. When programming for the GNU system, it is probably best to stick with the functions described in this section. If however, you want your program to be portable, consider using the XPG functions described in section XPG User Accounting Database Functions, or take a look at the BSD compatible functions in section Logging In and Out.

XPG User Accounting Database Functions

These functions, described in the X/Open Portability Guide, are declared in the header file `utmpx.h'.

Data Type: struct utmpx
The utmpx data structure contains at least the following members:

short int ut_type
Specifies the type of login; one of EMPTY, RUN_LVL, BOOT_TIME, OLD_TIME, NEW_TIME, INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS or DEAD_PROCESS.
pid_t ut_pid
The process ID number of the login process.
char ut_line[]
The device name of the tty (without `/dev/').
char ut_id[]
The inittab ID of the process.
char ut_user[]
The user's login name.
struct timeval ut_tv
Time the entry was made. For entries of type OLD_TIME this is the time when the system clock changed, and for entries of type NEW_TIME this is the time the system clock was set to.
On the GNU system, struct utmpx is identical to struct utmp except for the fact that including `utmpx.h' does not make visible the declaration of struct exit_status.

The following macros are defined for use as values for the ut_type member of the utmpx structure. The values are integer constants and are, on the GNU system, identical to the definitions in `utmp.h'.

EMPTY
This macro is used to indicate that the entry contains no valid user accounting information.
RUN_LVL
This macro is used to identify the systems runlevel.
BOOT_TIME
This macro is used to identify the time of system boot.
OLD_TIME
This macro is used to identify the time when the system clock changed.
NEW_TIME
This macro is used to identify the time after the system changed.
INIT_PROCESS
This macro is used to identify a process spawned by the init process.
LOGIN_PROCESS
This macro is used to identify the session leader of a logged in user.
USER_PROCESS
This macro is used to identify a user process.
DEAD_PROCESS
This macro is used to identify a terminated process.
The size of the ut_line, ut_id and ut_user arrays can be found using the sizeof operator.

Function: void setutxent (void)
This function is similar to setutent. On the GNU system it is simply an alias for setutent.

Function: struct utmpx * getutxent (void)
The getutxent function is similar to getutent, but returns a pointer to a struct utmpx instead of struct utmp. On the GNU system it simply is an alias for getutent.

Function: void endutxent (void)
This function is similar to endutent. On the GNU system it is simply an alias for endutent.

Function: struct utmpx * getutxid (const struct utmpx *id)
This function is similar to getutid, but uses struct utmpx instead of struct utmp. On the GNU system it is simply an alias for getutid.

Function: struct utmpx * getutxline (const struct utmpx *line)
This function is similar to getutid, but uses struct utmpx instead of struct utmp. On the GNU system it is simply an alias for getutline.

Function: struct utmpx * pututxline (const struct utmpx *utmp)
The pututxline function is functionally identical to pututline, but uses struct utmpx instead of struct utmp. On the GNU system, pututxline is simply an alias for pututline.

Function: int utmpxname (const char *file)
The utmpxname function is functionally identical to utmpname. On the GNU system, utmpxname is simply an alias for utmpname.

You can translate between a traditional struct utmp and an XPG struct utmpx with the following functions. On the GNU system, these functions are merely copies, since the two structures are identical.

Function: int getutmp (const struct utmpx *utmpx, struct utmp *utmp)
getutmp copies the information, insofar as the structures are compatible, from utmpx to utmp.

Function: int getutmpx (const struct utmp *utmp, struct utmpx *utmpx)
getutmpx copies the information, insofar as the structures are compatible, from utmp to utmpx.

Logging In and Out

These functions, derived from BSD, are available in the separate `libutil' library, and declared in `utmp.h'.

Note that the ut_user member of struct utmp is called ut_name in BSD. Therefore, ut_name is defined as an alias for ut_user in `utmp.h'.

Function: int login_tty (int filedes)
This function makes filedes the controlling terminal of the current process, redirects standard input, standard output and standard error output to this terminal, and closes filedes.

This function returns 0 on successful completion, and -1 on error.

Function: void login (const struct utmp *entry)
The login functions inserts an entry into the user accounting database. The ut_line member is set to the name of the terminal on standard input. If standard input is not a terminal login uses standard output or standard error output to determine the name of the terminal. If struct utmp has a ut_type member, login sets it to USER_PROCESS, and if there is an ut_pid member, it will be set to the process ID of the current process. The remaining entries are copied from entry.

A copy of the entry is written to the user accounting log file.

Function: int logout (const char *ut_line)
This function modifies the user accounting database to indicate that the user on ut_line has logged out.

The logout function returns 1 if the entry was successfully written to the database, or 0 on error.

Function: void logwtmp (const char *ut_line, const char *ut_name, const char *ut_host)
The logwtmp function appends an entry to the user accounting log file, for the current time and the information provided in the ut_line, ut_name and ut_host arguments.

Portability Note: The BSD struct utmp only has the ut_line, ut_name, ut_host and ut_time members. Older systems do not even have the ut_host member.

User Database

This section describes how to search and scan the database of registered users. The database itself is kept in the file `/etc/passwd' on most systems, but on some systems a special network server gives access to it.

The Data Structure that Describes a User

The functions and data structures for accessing the system user database are declared in the header file `pwd.h'.

Data Type: struct passwd
The passwd data structure is used to hold information about entries in the system user data base. It has at least the following members:

char *pw_name
The user's login name.
char *pw_passwd.
The encrypted password string.
uid_t pw_uid
The user ID number.
gid_t pw_gid
The user's default group ID number.
char *pw_gecos
A string typically containing the user's real name, and possibly other information such as a phone number.
char *pw_dir
The user's home directory, or initial working directory. This might be a null pointer, in which case the interpretation is system-dependent.
char *pw_shell
The user's default shell, or the initial program run when the user logs in. This might be a null pointer, indicating that the system default should be used.
Looking Up One User

You can search the system user database for information about a specific user using getpwuid or getpwnam. These functions are declared in `pwd.h'.

Function: struct passwd * getpwuid (uid_t uid)
This function returns a pointer to a statically-allocated structure containing information about the user whose user ID is uid. This structure may be overwritten on subsequent calls to getpwuid.

A null pointer value indicates there is no user in the data base with user ID uid.

Function: int getpwuid_r (uid_t uid, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result)
This function is similar to getpwuid in that it returns information about the user whose user ID is uid. However, it fills the user supplied structure pointed to by result_buf with the information instead of using a static buffer. The first buflen bytes of the additional buffer pointed to by buffer are used to contain additional information, normally strings which are pointed to by the elements of the result structure.

If a user with ID uid is found, the pointer returned in result points to the record which contains the wanted data (i.e., result contains the value result_buf). If no user is found or if an error occurred, the pointer returned in result is a null pointer. The function returns zero or an error code. If the buffer buffer is too small to contain all the needed information, the error code ERANGE is returned and errno is set to ERANGE.

Function: struct passwd * getpwnam (const char *name)
This function returns a pointer to a statically-allocated structure containing information about the user whose user name is name. This structure may be overwritten on subsequent calls to getpwnam.

A null pointer return indicates there is no user named name.

Function: int getpwnam_r (const char *name, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result)
This function is similar to getpwnam in that is returns information about the user whose user name is name. However, like getpwuid_r, it fills the user supplied buffers in result_buf and buffer with the information instead of using a static buffer.

The return values are the same as for getpwuid_r.

Scanning the List of All Users

This section explains how a program can read the list of all users in the system, one user at a time. The functions described here are declared in `pwd.h'.

You can use the fgetpwent function to read user entries from a particular file.

Function: struct passwd * fgetpwent (FILE *stream)
This function reads the next user entry from stream and returns a pointer to the entry. The structure is statically allocated and is rewritten on subsequent calls to fgetpwent. You must copy the contents of the structure if you wish to save the information.

The stream must correspond to a file in the same format as the standard password database file.

Function: int fgetpwent_r (FILE *stream, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result)
This function is similar to fgetpwent in that it reads the next user entry from stream. But the result is returned in the structure pointed to by result_buf. The first buflen bytes of the additional buffer pointed to by buffer are used to contain additional information, normally strings which are pointed to by the elements of the result structure.

The stream must correspond to a file in the same format as the standard password database file.

If the function returns zero result points to the structure with the wanted data (normally this is in result_buf). If errors occurred the return value is nonzero and result contains a null pointer.

The way to scan all the entries in the user database is with setpwent, getpwent, and endpwent.

Function: void setpwent (void)
This function initializes a stream which getpwent and getpwent_r use to read the user database.

Function: struct passwd * getpwent (void)
The getpwent function reads the next entry from the stream initialized by setpwent. It returns a pointer to the entry. The structure is statically allocated and is rewritten on subsequent calls to getpwent. You must copy the contents of the structure if you wish to save the information.

A null pointer is returned when no more entries are available.

Function: int getpwent_r (struct passwd *result_buf, char *buffer, int buflen, struct passwd **result)
This function is similar to getpwent in that it returns the next entry from the stream initialized by setpwent. Like fgetpwent_r, it uses the user-supplied buffers in result_buf and buffer to return the information requested.

The return values are the same as for fgetpwent_r.

Function: void endpwent (void)
This function closes the internal stream used by getpwent or getpwent_r.

Writing a User Entry

Function: int putpwent (const struct passwd *p, FILE *stream)
This function writes the user entry *p to the stream stream, in the format used for the standard user database file. The return value is zero on success and nonzero on failure.

This function exists for compatibility with SVID. We recommend that you avoid using it, because it makes sense only on the assumption that the struct passwd structure has no members except the standard ones; on a system which merges the traditional Unix data base with other extended information about users, adding an entry using this function would inevitably leave out much of the important information.

The function putpwent is declared in `pwd.h'.

Group Database

This section describes how to search and scan the database of registered groups. The database itself is kept in the file `/etc/group' on most systems, but on some systems a special network service provides access to it.

The Data Structure for a Group

The functions and data structures for accessing the system group database are declared in the header file `grp.h'.

Data Type: struct group
The group structure is used to hold information about an entry in the system group database. It has at least the following members:

char *gr_name
The name of the group.
gid_t gr_gid
The group ID of the group.
char **gr_mem
A vector of pointers to the names of users in the group. Each user name is a null-terminated string, and the vector itself is terminated by a null pointer.
Looking Up One Group

You can search the group database for information about a specific group using getgrgid or getgrnam. These functions are declared in `grp.h'.

Function: struct group * getgrgid (gid_t gid)
This function returns a pointer to a statically-allocated structure containing information about the group whose group ID is gid. This structure may be overwritten by subsequent calls to getgrgid.

A null pointer indicates there is no group with ID gid.

Function: int getgrgid_r (gid_t gid, struct group *result_buf, char *buffer, size_t buflen, struct group **result)
This function is similar to getgrgid in that it returns information about the group whose group ID is gid. However, it fills the user supplied structure pointed to by result_buf with the information instead of using a static buffer. The first buflen bytes of the additional buffer pointed to by buffer are used to contain additional information, normally strings which are pointed to by the elements of the result structure.

If a group with ID gid is found, the pointer returned in result points to the record which contains the wanted data (i.e., result contains the value result_buf). If no group is found or if an error occurred, the pointer returned in result is a null pointer. The function returns zero or an error code. If the buffer buffer is too small to contain all the needed information, the error code ERANGE is returned and errno is set to ERANGE.

Function: struct group * getgrnam (const char *name)
This function returns a pointer to a statically-allocated structure containing information about the group whose group name is name. This structure may be overwritten by subsequent calls to getgrnam.

A null pointer indicates there is no group named name.

Function: int getgrnam_r (const char *name, struct group *result_buf, char *buffer, size_t buflen, struct group **result)
This function is similar to getgrnam in that is returns information about the group whose group name is name. Like getgrgid_r, it uses the user supplied buffers in result_buf and buffer, not a static buffer.

The return values are the same as for getgrgid_r ERANGE.

Scanning the List of All Groups

This section explains how a program can read the list of all groups in the system, one group at a time. The functions described here are declared in `grp.h'.

You can use the fgetgrent function to read group entries from a particular file.

Function: struct group * fgetgrent (FILE *stream)
The fgetgrent function reads the next entry from stream. It returns a pointer to the entry. The structure is statically allocated and is overwritten on subsequent calls to fgetgrent. You must copy the contents of the structure if you wish to save the information.

The stream must correspond to a file in the same format as the standard group database file.

Function: int fgetgrent_r (FILE *stream, struct group *result_buf, char *buffer, size_t buflen, struct group **result)
This function is similar to fgetgrent in that it reads the next user entry from stream. But the result is returned in the structure pointed to by result_buf. The first buflen bytes of the additional buffer pointed to by buffer are used to contain additional information, normally strings which are pointed to by the elements of the result structure.

This stream must correspond to a file in the same format as the standard group database file.

If the function returns zero result points to the structure with the wanted data (normally this is in result_buf). If errors occurred the return value is non-zero and result contains a null pointer.

The way to scan all the entries in the group database is with setgrent, getgrent, and endgrent.

Function: void setgrent (void)
This function initializes a stream for reading from the group data base. You use this stream by calling getgrent or getgrent_r.

Function: struct group * getgrent (void)
The getgrent function reads the next entry from the stream initialized by setgrent. It returns a pointer to the entry. The structure is statically allocated and is overwritten on subsequent calls to getgrent. You must copy the contents of the structure if you wish to save the information.

Function: int getgrent_r (struct group *result_buf, char *buffer, size_t buflen, struct group **result)
This function is similar to getgrent in that it returns the next entry from the stream initialized by setgrent. Like fgetgrent_r, it places the result in user-supplied buffers pointed to result_buf and buffer.

If the function returns zero result contains a pointer to the data (normally equal to result_buf). If errors occurred the return value is non-zero and result contains a null pointer.

Function: void endgrent (void)
This function closes the internal stream used by getgrent or getgrent_r.

User and Group Database Example

Here is an example program showing the use of the system database inquiry functions. The program prints some information about the user running the program.
#include <grp.h>
#include <pwd.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>

int
main (void)
{
  uid_t me;
  struct passwd *my_passwd;
  struct group *my_group;
  char **members;

  /* Get information about the user ID. */
  me = getuid ();
  my_passwd = getpwuid (me);
  if (!my_passwd)
    {
      printf ("Couldn't find out about user %d.\n", (int) me);
      exit (EXIT_FAILURE);
    }

  /* Print the information. */
  printf ("I am %s.\n", my_passwd->pw_gecos);
  printf ("My login name is %s.\n", my_passwd->pw_name);
  printf ("My uid is %d.\n", (int) (my_passwd->pw_uid));
  printf ("My home directory is %s.\n", my_passwd->pw_dir);
  printf ("My default shell is %s.\n", my_passwd->pw_shell);

  /* Get information about the default group ID. */
  my_group = getgrgid (my_passwd->pw_gid);
  if (!my_group)
    {
      printf ("Couldn't find out about group %d.\n",
              (int) my_passwd->pw_gid);
      exit (EXIT_FAILURE);
    }

  /* Print the information. */
  printf ("My default group is %s (%d).\n",
          my_group->gr_name, (int) (my_passwd->pw_gid));
  printf ("The members of this group are:\n");
  members = my_group->gr_mem;
  while (*members)
    {
      printf ("  %s\n", *(members));
      members++;
    }

  return EXIT_SUCCESS;
}
Here is some output from this program:
I am Throckmorton Snurd.
My login name is snurd.
My uid is 31093.
My home directory is /home/fsg/snurd.
My default shell is /bin/sh.
My default group is guest (12).
The members of this group are:
  friedman
  tami
Netgroup Database

Netgroup Data

Sometimes it is useful to group users according to other criteria (see section Group Database). E.g., it is useful to associate a certain group of users with a certain machine. On the other hand grouping of host names is not supported so far.

In Sun Microsystems SunOS appeared a new kind of database, the netgroup database. It allows grouping hosts, users, and domains freely, giving them individual names. To be more concrete, a netgroup is a list of triples consisting of a host name, a user name, and a domain name where any of the entries can be a wildcard entry matching all inputs. A last possibility is that names of other netgroups can also be given in the list specifying a netgroup. So one can construct arbitrary hierarchies without loops.

Sun's implementation allows netgroups only for the nis or nisplus service, see section Services in the NSS configuration File. The implementation in the GNU C library has no such restriction. An entry in either of the input services must have the following form:
groupname ( groupname | (hostname,username,domainname) )+
Any of the fields in the triple can be empty which means anything matches. While describing the functions we will see that the opposite case is useful as well. I.e., there may be entries which will not match any input. For entries like this, a name consisting of the single character - shall be used.

Looking up one Netgroup

The lookup functions for netgroups are a bit different to all other system database handling functions. Since a single netgroup can contain many entries a two-step process is needed. First a single netgroup is selected and then one can iterate over all entries in this netgroup. These functions are declared in `netdb.h'.

Function: int setnetgrent (const char *netgroup)
A call to this function initializes the internal state of the library to allow following calls of the getnetgrent to iterate over all entries in the netgroup with name netgroup.

When the call is successful (i.e., when a netgroup with this name exists) the return value is 1. When the return value is 0 no netgroup of this name is known or some other error occurred.

It is important to remember that there is only one single state for iterating the netgroups. Even if the programmer uses the getnetgrent_r function the result is not really reentrant since always only one single netgroup at a time can be processed. If the program needs to process more than one netgroup simultaneously she must protect this by using external locking. This problem was introduced in the original netgroups implementation in SunOS and since we must stay compatible it is not possible to change this.

Some other functions also use the netgroups state. Currently these are the innetgr function and parts of the implementation of the compat service part of the NSS implementation.

Function: int getnetgrent (char **hostp, char **userp, char **domainp)
This function returns the next unprocessed entry of the currently selected netgroup. The string pointers, in which addresses are passed in the arguments hostp, userp, and domainp, will contain after a successful call pointers to appropriate strings. If the string in the next entry is empty the pointer has the value NULL. The returned string pointers are only valid if none of the netgroup related functions are called.

The return value is 1 if the next entry was successfully read. A value of 0 means no further entries exist or internal errors occurred.

Function: int getnetgrent_r (char **hostp, char **userp, char **domainp, char *buffer, int buflen)
This function is similar to getnetgrent with only one exception: the strings the three string pointers hostp, userp, and domainp point to, are placed in the buffer of buflen bytes starting at buffer. This means the returned values are valid even after other netgroup related functions are called.

The return value is 1 if the next entry was successfully read and the buffer contains enough room to place the strings in it. 0 is returned in case no more entries are found, the buffer is too small, or internal errors occurred.

This function is a GNU extension. The original implementation in the SunOS libc does not provide this function.

Function: void endnetgrent (void)
This function frees all buffers which were allocated to process the last selected netgroup. As a result all string pointers returned by calls to getnetgrent are invalid afterwards.

Testing for Netgroup Membership

It is often not necessary to scan the whole netgroup since often the only interesting question is whether a given entry is part of the selected netgroup.

Function: int innetgr (const char *netgroup, const char *host, const char *user, const char *domain)
This function tests whether the triple specified by the parameters hostp, userp, and domainp is part of the netgroup netgroup. Using this function has the advantage that

no other netgroup function can use the global netgroup state since internal locking is used and
the function is implemented more efficiently than successive calls to the other set/get/endnetgrent functions.

Any of the pointers hostp, userp, and domainp can be NULL which means any value is accepted in this position. This is also true for the name - which should not match any other string otherwise.

The return value is 1 if an entry matching the given triple is found in the netgroup. The return value is 0 if the netgroup itself is not found, the netgroup does not contain the triple or internal errors occurred.
System Management

This chapter describes facilities for controlling the system that underlies a process (including the operating system and hardware) and for getting information about it. Anyone can generally use the informational facilities, but usually only a properly privileged process can make changes.

To get information on parameters of the system that are built into the system, such as the maximum length of a filename, section System Configuration Parameters.

Host Identification

This section explains how to identify the particular system on which your program is running. First, let's review the various ways computer systems are named, which is a little complicated because of the history of the development of the Internet.

Every Unix system (also known as a host) has a host name, whether it's connected to a network or not. In its simplest form, as used before computer networks were an issue, it's just a word like `chicken'.

But any system attached to the Internet or any network like it conforms to a more rigorous naming convention as part of the Domain Name System (DNS). In DNS, every host name is composed of two parts:

hostname
domain name

You will note that "hostname" looks a lot like "host name", but is not the same thing, and that people often incorrectly refer to entire host names as "domain names."

In DNS, the full host name is properly called the FQDN (Fully Qualified Domain Name) and consists of the hostname, then a period, then the domain name. The domain name itself usually has multiple components separated by periods. So for example, a system's hostname may be `chicken' and its domain name might be `ai.mit.edu', so its FQDN (which is its host name) is `chicken.ai.mit.edu'.

Adding to the confusion, though, is that DNS is not the only name space in which a computer needs to be known. Another name space is the NIS (aka YP) name space. For NIS purposes, there is another domain name, which is called the NIS domain name or the YP domain name. It need not have anything to do with the DNS domain name.

Confusing things even more is the fact that in DNS, it is possible for multiple FQDNs to refer to the same system. However, there is always exactly one of them that is the true host name, and it is called the canonical FQDN.

In some contexts, the host name is called a "node name."

For more information on DNS host naming, See section Host Names.

Prototypes for these functions appear in `unistd.h'.

The programs hostname, hostid, and domainname work by calling these functions.

Function: int gethostname (char *name, size_t size)
This function returns the host name of the system on which it is called, in the array name. The size argument specifies the size of this array, in bytes. Note that this is not the DNS hostname. If the system participates in DNS, this is the FQDN (see above).

The return value is 0 on success and -1 on failure. In the GNU C library, gethostname fails if size is not large enough; then you can try again with a larger array. The following errno error condition is defined for this function:

ENAMETOOLONG
The size argument is less than the size of the host name plus one.
On some systems, there is a symbol for the maximum possible host name length: MAXHOSTNAMELEN. It is defined in `sys/param.h'. But you can't count on this to exist, so it is cleaner to handle failure and try again.

gethostname stores the beginning of the host name in name even if the host name won't entirely fit. For some purposes, a truncated host name is good enough. If it is, you can ignore the error code.

Function: int sethostname (const char *name, size_t length)
The sethostname function sets the host name of the system that calls it to name, a string with length length. Only privileged processes are permitted to do this.

Usually sethostname gets called just once, at system boot time. Often, the program that calls it sets it to the value it finds in the file /etc/hostname.

Be sure to set the host name to the full host name, not just the DNS hostname (see above).

The return value is 0 on success and -1 on failure. The following errno error condition is defined for this function:

EPERM
This process cannot set the host name because it is not privileged.

Function: int getdomainnname (char *name, size_t length)

getdomainname returns the NIS (aka YP) domain name of the system on which it is called. Note that this is not the more popular DNS domain name. Get that with gethostname.

The specifics of this function are analogous to gethostname, above.

Function: int setdomainname (const char *name, size_t length)

getdomainname sets the NIS (aka YP) domain name of the system on which it is called. Note that this is not the more popular DNS domain name. Set that with sethostname.

The specifics of this function are analogous to sethostname, above.

Function: long int gethostid (void)
This function returns the "host ID" of the machine the program is running on. By convention, this is usually the primary Internet IP address of that machine, converted to a long int. However, on some systems it is a meaningless but unique number which is hard-coded for each machine.

This is not widely used. It arose in BSD 4.2, but was dropped in BSD 4.4. It is not required by POSIX.

The proper way to query the IP address is to use gethostbyname on the results of gethostname. For more information on IP addresses, See section Host Addresses.

Function: int sethostid (long int id)
The sethostid function sets the "host ID" of the host machine to id. Only privileged processes are permitted to do this. Usually it happens just once, at system boot time.

The proper way to establish the primary IP address of a system is to configure the IP address resolver to associate that IP address with the system's host name as returned by gethostname. For example, put a record for the system in `/etc/hosts'.

See gethostid above for more information on host ids.

The return value is 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EPERM
This process cannot set the host name because it is not privileged.
ENOSYS
The operating system does not support setting the host ID. On some systems, the host ID is a meaningless but unique number hard-coded for each machine.
Platform Type Identification

You can use the uname function to find out some information about the type of computer your program is running on. This function and the associated data type are declared in the header file `sys/utsname.h'.

As a bonus, uname also gives some information identifying the particular system your program is running on. This is the same information which you can get with functions targetted to this purpose described in section Host Identification.

Data Type: struct utsname
The utsname structure is used to hold information returned by the uname function. It has the following members:

char sysname[]
This is the name of the operating system in use.
char release[]
This is the current release level of the operating system implementation.
char version[]
This is the current version level within the release of the operating system.
char machine[]
This is a description of the type of hardware that is in use. Some systems provide a mechanism to interrogate the kernel directly for this information. On systems without such a mechanism, the GNU C library fills in this field based on the configuration name that was specified when building and installing the library. GNU uses a three-part name to describe a system configuration; the three parts are cpu, manufacturer and system-type, and they are separated with dashes. Any possible combination of three names is potentially meaningful, but most such combinations are meaningless in practice and even the meaningful ones are not necessarily supported by any particular GNU program. Since the value in machine is supposed to describe just the hardware, it consists of the first two parts of the configuration name: `cpu-manufacturer'. For example, it might be one of these:

"sparc-sun", "i386-anything", "m68k-hp", "m68k-sony", "m68k-sun", "mips-dec"

char nodename[]
This is the host name of this particular computer. In the GNU C library, the value is the same as that returned by gethostname; see section Host Identification. gethostname() is implemented with a call to uname().
char domainname[]
This is the NIS or YP domain name. It is the same value returned by getdomainname; see section Host Identification. This element is a relatively recent invention and use of it is not as portable as use of the rest of the structure.

Function: int uname (struct utsname *info)
The uname function fills in the structure pointed to by info with information about the operating system and host machine. A non-negative value indicates that the data was successfully stored.

-1 as the value indicates an error. The only error possible is EFAULT, which we normally don't mention as it is always a possibility.

Controlling and Querying Mounts

All files are in filesystems, and before you can access any file, its filesystem must be mounted. Because of Unix's concept of Everything is a file, mounting of filesystems is central to doing almost anything. This section explains how to find out what filesystems are currently mounted and what filesystems are available for mounting, and how to change what is mounted.

The classic filesystem is the contents of a disk drive. The concept is considerably more abstract, though, and lots of things other than disk drives can be mounted.

Some block devices don't correspond to traditional devices like disk drives. For example, a loop device is a block device whose driver uses a regular file in another filesystem as its medium. So if that regular file contains appropriate data for a filesystem, you can by mounting the loop device essentially mount a regular file.

Some filesystems aren't based on a device of any kind. The "proc" filesystem, for example, contains files whose data is made up by the filesystem driver on the fly whenever you ask for it. And when you write to it, the data you write causes changes in the system. No data gets stored.

Mount Information

For some programs it is desirable and necessary to access information about whether a certain filesystem is mounted and, if it is, where, or simply to get lists of all the available filesystems. The GNU libc provides some functions to retrieve this information portably.

Traditionally Unix systems have a file named `/etc/fstab' which describes all possibly mounted filesystems. The mount program uses this file to mount at startup time of the system all the necessary filesystems. The information about all the filesystems actually mounted is normally kept in a file named `/etc/mtab'. Both files share the same syntax and it is crucial that this syntax is followed all the time. Therefore it is best to never directly write the files. The functions described in this section can do this and they also provide the functionality to convert the external textual representation to the internal representation.

Note that the `fstab' and `mtab' files are maintained on a system by convention. It is possible for the files not to exist or not to be consistent with what is really mounted or available to mount, if the system's administration policy allows it. But programs that mount and unmount filesystems typically maintain and use these files as described herein.

The filenames given above should never be used directly. The portable way to handle these file is to use the macros _PATH_FSTAB, defined in `fstab.h' and _PATH_MNTTAB, defined in `mntent.h', respectively. There are also two alternate macro names FSTAB and _PATH_MOUNTED defined but both names are deprecated and kept only for backward compatibility. The two former names should always be used.

The `fstab' file

The internal representation for entries of the file is struct fstab, defined in `fstab.h'.

Data Type: struct fstab
This structure is used with the getfsent, getfsspec, and getfsfile functions.

char *fs_spec
This element describes the device from which the filesystem is mounted. Normally this is the name of a special device, such as a hard disk partition, but it could also be a more or less generic string. For NFS it would be a hostname and directory name combination. Even though the element is not declared const it shouldn't be modified. The missing const has historic reasons, since this function predates ISO C. The same is true for the other string elements of this structure.
char *fs_file
This describes the mount point on the local system. I.e., accessing any file in this filesystem has implicitly or explicitly this string as a prefix.
char *fs_vfstype
This is the type of the filesystem. Depending on what the underlying kernel understands it can be any string.
char *fs_mntops
This is a string containing options passed to the kernel with the mount call. Again, this can be almost anything. There can be more than one option, separated from the others by a comma. Each option consists of a name and an optional value part, introduced by an = character. If the value of this element must be processed it should ideally be done using the getsubopt function; see section Parsing of Suboptions.
const char *fs_type
This name is poorly chosen. This element points to a string (possibly in the fs_mntops string) which describes the modes with which the filesystem is mounted. `fstab' defines five macros to describe the possible values:
FSTAB_RW
The filesystems gets mounted with read and write enabled.
FSTAB_RQ
The filesystems gets mounted with read and write enabled. Write access is restricted by quotas.
FSTAB_RO
The filesystem gets mounted read-only.
FSTAB_SW
This is not a real filesystem, it is a swap device.
FSTAB_XX
This entry from the `fstab' file is totally ignored. Testing for equality with these value must happen using strcmp since these are all strings. Comparing the pointer will probably always fail.
int fs_freq
This element describes the dump frequency in days.
int fs_passno
This element describes the pass number on parallel dumps. It is closely related to the dump utility used on Unix systems.
To read the entire content of the of the `fstab' file the GNU libc contains a set of three functions which are designed in the usual way.

Function: int setfsent (void)
This function makes sure that the internal read pointer for the `fstab' file is at the beginning of the file. This is done by either opening the file or resetting the read pointer.

Since the file handle is internal to the libc this function is not thread-safe.

This function returns a non-zero value if the operation was successful and the getfs* functions can be used to read the entries of the file.

Function: void endfsent (void)
This function makes sure that all resources acquired by a prior call to setfsent (explicitly or implicitly by calling getfsent) are freed.

Function: struct fstab * getfsent (void)
This function returns the next entry of the `fstab' file. If this is the first call to any of the functions handling `fstab' since program start or the last call of endfsent, the file will be opened.

The function returns a pointer to a variable of type struct fstab. This variable is shared by all threads and therefore this function is not thread-safe. If an error occurred getfsent returns a NULL pointer.

Function: struct fstab * getfsspec (const char *name)
This function returns the next entry of the `fstab' file which has a string equal to name pointed to by the fs_spec element. Since there is normally exactly one entry for each special device it makes no sense to call this function more than once for the same argument. If this is the first call to any of the functions handling `fstab' since program start or the last call of endfsent, the file will be opened.

The function returns a pointer to a variable of type struct fstab. This variable is shared by all threads and therefore this function is not thread-safe. If an error occurred getfsent returns a NULL pointer.

Function: struct fstab * getfsfile (const char *name)
This function returns the next entry of the `fstab' file which has a string equal to name pointed to by the fs_file element. Since there is normally exactly one entry for each mount point it makes no sense to call this function more than once for the same argument. If this is the first call to any of the functions handling `fstab' since program start or the last call of endfsent, the file will be opened.

The function returns a pointer to a variable of type struct fstab. This variable is shared by all threads and therefore this function is not thread-safe. If an error occurred getfsent returns a NULL pointer.

The `mtab' file

The following functions and data structure access the `mtab' file.

Data Type: struct mntent
This structure is used with the getmntent, getmntent_t, addmntent, and hasmntopt functions.

char *mnt_fsname
This element contains a pointer to a string describing the name of the special device from which the filesystem is mounted. It corresponds to the fs_spec element in struct fstab.
char *mnt_dir
This element points to a string describing the mount point of the filesystem. It corresponds to the fs_file element in struct fstab.
char *mnt_type
mnt_type describes the filesystem type and is therefore equivalent to fs_vfstype in struct fstab. `mntent.h' defines a few symbolic names for some of the values this string can have. But since the kernel can support arbitrary filesystems it does not make much sense to give them symbolic names. If one knows the symbol name one also knows the filesystem name. Nevertheless here follows the list of the symbols provided in `mntent.h'.
MNTTYPE_IGNORE
This symbol expands to "ignore". The value is sometime used in `fstab' files to make sure entries are not used without removing them.
MNTTYPE_NFS
Expands to "nfs". Using this macro sometimes could make sense since it names the default NFS implementation, in case both version 2 and 3 are supported.
MNTTYPE_SWAP
This symbol expands to "swap". It names the special `fstab' entry which names one of the possibly multiple swap partitions.
char *mnt_opts
The element contains a string describing the options used while mounting the filesystem. As for the equivalent element fs_mntops of struct fstab it is best to use the function getsubopt (see section Parsing of Suboptions) to access the parts of this string. The `mntent.h' file defines a number of macros with string values which correspond to some of the options understood by the kernel. There might be many more options which are possible so it doesn't make much sense to rely on these macros but to be consistent here is the list:
MNTOPT_DEFAULTS
Expands to "defaults". This option should be used alone since it indicates all values for the customizable values are chosen to be the default.
MNTOPT_RO
Expands to "ro". See the FSTAB_RO value, it means the filesystem is mounted read-only.
MNTOPT_RW
Expand to "rw". See the FSTAB_RW value, it means the filesystem is mounted with read and write permissions.
MNTOPT_SUID
Expands to "suid". This means that the SUID bit (see section How an Application Can Change Persona) is respected when a program from the filesystem is started.
MNTOPT_NOSUID
Expands to "nosuid". This is the opposite of MNTOPT_SUID, the SUID bit for all files from the filesystem is ignored.
MNTOPT_NOAUTO
Expands to "noauto". At startup time the mount program will ignore this entry if it is started with the -a option to mount all filesystems mentioned in the `fstab' file. As for the FSTAB_* entries introduced above it is important to use strcmp to check for equality.
mnt_freq
This elements corresponds to fs_freq and also specifies the frequency in days in which dumps are made.
mnt_passno
This element is equivalent to fs_passno with the same meaning which is uninteresting for all programs beside dump.
For accessing the `mtab' file there is again a set of three functions to access all entries in a row. Unlike the functions to handle `fstab' these functions do not access a fixed file and there is even a thread safe variant of the get function. Beside this the GNU libc contains functions to alter the file and test for specific options.

Function: FILE * setmntent (const char *file, const char *mode)
The setmntent function prepares the file named FILE which must be in the format of a `fstab' and `mtab' file for the upcoming processing through the other functions of the family. The mode parameter can be chosen in the way the opentype parameter for fopen (see section Opening Streams) can be chosen. If the file is opened for writing the file is also allowed to be empty.

If the file was successfully opened setmntent returns a file descriptor for future use. Otherwise the return value is NULL and errno is set accordingly.

Function: int endmntent (FILE *stream)
This function takes for the stream parameter a file handle which previously was returned from the setmntent call. endmntent closes the stream and frees all resources.

The return value is @math{1} unless an error occurred in which case it is @math{0}.

Function: struct mntent * getmntent (FILE *stream)
The getmntent function takes as the parameter a file handle previously returned by successful call to setmntent. It returns a pointer to a static variable of type struct mntent which is filled with the information from the next entry from the file currently read.

The file format used prescribes the use of spaces or tab characters to separate the fields. This makes it harder to use name containing one of these characters (e.g., mount points using spaces). Therefore these characters are encoded in the files and the getmntent function takes care of the decoding while reading the entries back in. '\040' is used to encode a space character, '\012' to encode a tab character and '\\' to encode a backslash.

If there was an error or the end of the file is reached the return value is NULL.

This function is not thread-safe since all calls to this function return a pointer to the same static variable. getmntent_r should be used in situations where multiple threads access the file.

Function: struct mntent * getmntent_r (FILE *stream, struct mentent *result, char *buffer, int bufsize)
The getmntent_r function is the reentrant variant of getmntent. It also returns the next entry from the file and returns a pointer. The actual variable the values are stored in is not static, though. Instead the function stores the values in the variable pointed to by the result parameter. Additional information (e.g., the strings pointed to by the elements of the result) are kept in the buffer of size bufsize pointed to by buffer.

Escaped characters (space, tab, backslash) are converted back in the same way as it happens for getmentent.

The function returns a NULL pointer in error cases. Errors could be:

error while reading the file,
end of file reached,
bufsize is too small for reading a complete new entry.

Function: int addmntent (FILE *stream, const struct mntent *mnt)
The addmntent function allows adding a new entry to the file previously opened with setmntent. The new entries are always appended. I.e., even if the position of the file descriptor is not at the end of the file this function does not overwrite an existing entry following the current position.

The implication of this is that to remove an entry from a file one has to create a new file while leaving out the entry to be removed and after closing the file remove the old one and rename the new file to the chosen name.

This function takes care of spaces and tab characters in the names to be written to the file. It converts them and the backslash character into the format describe in the getmntent description above.

This function returns @math{0} in case the operation was successful. Otherwise the return value is @math{1} and errno is set appropriately.

Function: char * hasmntopt (const struct mntent *mnt, const char *opt)
This function can be used to check whether the string pointed to by the mnt_opts element of the variable pointed to by mnt contains the option opt. If this is true a pointer to the beginning of the option in the mnt_opts element is returned. If no such option exists the function returns NULL.

This function is useful to test whether a specific option is present but when all options have to be processed one is better off with using the getsubopt function to iterate over all options in the string.

Other (Non-libc) Sources of Mount Information

On a system with a Linux kernel and the proc filesystem, you can get information on currently mounted filesystems from the file `mounts' in the proc filesystem. Its format is similar to that of the `mtab' file, but represents what is truly mounted without relying on facilities outside the kernel to keep `mtab' up to date.

Mount, Unmount, Remount

This section describes the functions for mounting, unmounting, and remounting filesystems.

Only the superuser can mount, unmount, or remount a filesystem.

These functions do not access the `fstab' and `mtab' files. You should maintain and use these separately. See section Mount Information.

The symbols in this section are declared in `sys/mount.h'.

Function: int mount (const char *special_file, const char *dir, const char *fstype, unsigned long int options, const void *data)

mount mounts or remounts a filesystem. The two operations are quite different and are merged rather unnnaturally into this one function. The MS_REMOUNT option, explained below, determines whether mount mounts or remounts.

For a mount, the filesystem on the block device represented by the device special file named special_file gets mounted over the mount point dir. This means that the directory dir (along with any files in it) is no longer visible; in its place (and still with the name dir) is the root directory of the filesystem on the device.

As an exception, if the filesystem type (see below) is one which is not based on a device (e.g. "proc"), mount instantiates a filesystem and mounts it over dir and ignores special_file.

For a remount, dir specifies the mount point where the filesystem to be remounted is (and remains) mounted and special_file is ignored. Remounting a filesystem means changing the options that control operations on the filesystem while it is mounted. It does not mean unmounting and mounting again.

For a mount, you must identify the type of the filesystem as fstype. This type tells the kernel how to access the filesystem and can be thought of as the name of a filesystem driver. The acceptable values are system dependent. On a system with a Linux kernel and the proc filesystem, the list of possible values is in the file `filesystems' in the proc filesystem (e.g. type cat /proc/filesystems to see the list). With a Linux kernel, the types of filesystems that mount can mount, and their type names, depends on what filesystem drivers are configured into the kernel or loaded as loadable kernel modules. An example of a common value for fstype is ext2.

For a remount, mount ignores fstype.

options specifies a variety of options that apply until the filesystem is unmounted or remounted. The precise meaning of an option depends on the filesystem and with some filesystems, an option may have no effect at all. Furthermore, for some filesystems, some of these options (but never MS_RDONLY) can be overridden for individual file accesses via ioctl.

options is a bit string with bit fields defined using the following mask and masked value macros:

MS_MGC_MASK
This multibit field contains a magic number. If it does not have the value MS_MGC_VAL, mount assumes all the following bits are zero and the data argument is a null string, regardless of their actual values.
MS_REMOUNT
This bit on means to remount the filesystem. Off means to mount it.
MS_RDONLY
This bit on specifies that no writing to the filesystem shall be allowed while it is mounted. This cannot be overridden by ioctl. This option is available on nearly all filesystems.
S_IMMUTABLE
This bit on specifies that no writing to the files in the filesystem shall be allowed while it is mounted. This can be overridden for a particular file access by a properly privileged call to ioctl. This option is a relatively new invention and is not available on many filesystems.
S_APPEND
This bit on specifies that the only file writing that shall be allowed while the filesystem is mounted is appending. Some filesystems allow this to be overridden for a particular process by a properly privileged call to ioctl. This is a relatively new invention and is not available on many filesystems.
MS_NOSUID
This bit on specifies that Setuid and Setgid permissions on files in the filesystem shall be ignored while it is mounted.
MS_NOEXEC
This bit on specifies that no files in the filesystem shall be executed while the filesystem is mounted.
MS_NODEV
This bit on specifies that no device special files in the filesystem shall be accessible while the filesystem is mounted.
MS_SYNCHRONOUS
This bit on specifies that all writes to the filesystem while it is mounted shall be synchronous; i.e. data shall be synced before each write completes rather than held in the buffer cache.
MS_MANDLOCK
This bit on specifies that mandatory locks on files shall be permitted while the filesystem is mounted.
MS_NOATIME
This bit on specifies that access times of files shall not be updated when the files are accessed while the filesystem is mounted.
MS_NODIRATIME
This bit on specifies that access times of directories shall not be updated when the directories are accessed while the filesystem in mounted.
Any bits not covered by the above masks should be set off; otherwise, results are undefined.

The meaning of data depends on the filesystem type and is controlled entirely by the filesystem driver in the kernel.

Example:
#include <sys/mount.h>

mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");

mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");
Appropriate arguments for mount are conventionally recorded in the `fstab' table. See section Mount Information.

The return value is zero if the mount or remount is successful. Otherwise, it is -1 and errno is set appropriately. The values of errno are filesystem dependent, but here is a general list:

EPERM
The process is not superuser.
ENODEV
The file system type fstype is not known to the kernel.
ENOTBLK
The file dev is not a block device special file.
EBUSY

The device is already mounted.
The mount point is busy. (E.g. it is some process' working directory or has a filesystem mounted on it already).
The request is to remount read-only, but there are files open for write.

EINVAL

A remount was attempted, but there is no filesystem mounted over the specified mount point.
The supposed filesystem has an invalid superblock.

EACCESS

The filesystem is inherently read-only (possibly due to a switch on the device) and the process attempted to mount it read/write (by setting the MS_RDONLY bit off).
special_file or dir is not accessible due to file permissions.
special_file is not accessible because it is in a filesystem that is mounted with the MS_NODEV option.

EM_FILE
The table of dummy devices is full. mount needs to create a dummy device (aka "unnamed" device) if the filesystem being mounted is not one that uses a device.

Function: int umount2 (const char *file, int flags)

umount2 unmounts a filesystem.

You can identify the filesystem to unmount either by the device special file that contains the filesystem or by the mount point. The effect is the same. Specify either as the string file.

flags contains the one-bit field identified by the following mask macro:

MNT_FORCE
This bit on means to force the unmounting even if the filesystem is busy, by making it unbusy first. If the bit is off and the filesystem is busy, umount2 fails with errno = EBUSY. Depending on the filesystem, this may override all, some, or no busy conditions.
All other bits in flags should be set to zero; otherwise, the result is undefined.

Example:
#include <sys/mount.h>

umount2("/mnt", MNT_FORCE);

umount2("/dev/hdd1", 0);
After the filesystem is unmounted, the directory that was the mount point is visible, as are any files in it.

As part of unmounting, umount2 syncs the filesystem.

If the unmounting is successful, the return value is zero. Otherwise, it is -1 and errno is set accordingly:

EPERM
The process is not superuser.
EBUSY
The filesystem cannot be unmounted because it is busy. E.g. it contains a directory that is some process's working directory or a file that some process has open. With some filesystems in some cases, you can avoid this failure with the MNT_FORCE option.
EINVAL
file validly refers to a file, but that file is neither a mount point nor a device special file of a currently mounted filesystem.
This function is not available on all systems.

Function: int umount (const char *file)

umount does the same thing as umount2 with flags set to zeroes. It is more widely available than umount2 but since it lacks the possibility to forcefully unmount a filesystem is deprecated when umount2 is also available.

System Parameters

This section describes the sysctl function, which gets and sets a variety of system parameters.

The symbols used in this section are declared in the file `sysctl.h'.

Function: int sysctl (int *names, int nlen, void *oldval,
size_t *oldlenp, void *newval, size_t newlen)

sysctl gets or sets a specified system parameter. There are so many of these parameters that it is not practical to list them all here, but here are some examples:

network domain name
paging parameters
network Address Resolution Protocol timeout time
maximum number of files that may be open
root filesystem device
when kernel was built

The set of available parameters depends on the kernel configuration and can change while the system is running, particularly when you load and unload loadable kernel modules.

The system parameters with which syslog is concerned are arranged in a hierarchical structure like a hierarchical filesystem. To identify a particular parameter, you specify a path through the structure in a way analogous to specifying the pathname of a file. Each component of the path is specified by an integer and each of these integers has a macro defined for it by `sysctl.h'. names is the path, in the form of an array of integers. Each component of the path is one element of the array, in order. nlen is the number of components in the path.

For example, the first component of the path for all the paging parameters is the value CTL_VM. For the free page thresholds, the second component of the path is VM_FREEPG. So to get the free page threshold values, make names an array containing the two elements CTL_VM and VM_FREEPG and make nlen = 2.

The format of the value of a parameter depends on the parameter. Sometimes it is an integer; sometimes it is an ASCII string; sometimes it is an elaborate structure. In the case of the free page thresholds used in the example above, the parameter value is a structure containing several integers.

In any case, you identify a place to return the parameter's value with oldval and specify the amount of storage available at that location as *oldlenp. *oldlenp does double duty because it is also the output location that contains the actual length of the returned value.

If you don't want the parameter value returned, specify a null pointer for oldval.

To set the parameter, specify the address and length of the new value as newval and newlen. If you don't want to set the parameter, specify a null pointer as newval.

If you get and set a parameter in the same sysctl call, the value returned is the value of the parameter before it was set.

Each system parameter has a set of permissions similar to the permissions for a file (including the permissions on directories in its path) that determine whether you may get or set it. For the purposes of these permissions, every parameter is considered to be owned by the superuser and Group 0 so processes with that effective uid or gid may have more access to system parameters. Unlike with files, the superuser does not invariably have full permission to all system parameters, because some of them are designed not to be changed ever.

sysctl returns a zero return value if it succeeds. Otherwise, it returns -1 and sets errno appropriately. Besides the failures that apply to all system calls, the following are the errno codes for all possible failures:

EPERM
The process is not permitted to access one of the components of the path of the system parameter or is not permitted to access the system parameter itself in the way (read or write) that it requested.
ENOTDIR
There is no system parameter corresponding to name.
EFAULT
oldval is not null, which means the process wanted to read the parameter, but *oldlenp is zero, so there is no place to return it.
EINVAL

The process attempted to set a system parameter to a value that is not valid for that parameter.
The space provided for the return of the system parameter is not the right size for that parameter.

ENOMEM
This value may be returned instead of the more correct EINVAL in some cases where the space provided for the return of the system parameter is too small.
If you have a Linux kernel with the proc filesystem, you can get and set most of the same parameters by reading and writing to files in the sys directory of the proc filesystem. In the sys directory, the directory structure represents the hierarchical structure of the parameters. E.g. you can display the free page thresholds with
cat /proc/sys/vm/freepages
Some more traditional and more widely available, though less general, GNU C library functions for getting and setting some of the same system parameters are:

getdomainname, setdomainname
gethostname, sethostname (See section Host Identification.)
uname (See section Platform Type Identification.)
bdflush

System Configuration Parameters

The functions and macros listed in this chapter give information about configuration parameters of the operating system--for example, capacity limits, presence of optional POSIX features, and the default path for executable files (see section String-Valued Parameters).

General Capacity Limits

The POSIX.1 and POSIX.2 standards specify a number of parameters that describe capacity limitations of the system. These limits can be fixed constants for a given operating system, or they can vary from machine to machine. For example, some limit values may be configurable by the system administrator, either at run time or by rebuilding the kernel, and this should not require recompiling application programs.

Each of the following limit parameters has a macro that is defined in `limits.h' only if the system has a fixed, uniform limit for the parameter in question. If the system allows different file systems or files to have different limits, then the macro is undefined; use sysconf to find out the limit that applies at a particular time on a particular machine. See section Using sysconf.

Each of these parameters also has another macro, with a name starting with `_POSIX', which gives the lowest value that the limit is allowed to have on any POSIX system. See section Minimum Values for General Capacity Limits.

Macro: int ARG_MAX
If defined, the unvarying maximum combined length of the argv and environ arguments that can be passed to the exec functions.

Macro: int CHILD_MAX
If defined, the unvarying maximum number of processes that can exist with the same real user ID at any one time. In BSD and GNU, this is controlled by the RLIMIT_NPROC resource limit; see section Limiting Resource Usage.

Macro: int OPEN_MAX
If defined, the unvarying maximum number of files that a single process can have open simultaneously. In BSD and GNU, this is controlled by the RLIMIT_NOFILE resource limit; see section Limiting Resource Usage.

Macro: int STREAM_MAX
If defined, the unvarying maximum number of streams that a single process can have open simultaneously. See section Opening Streams.

Macro: int TZNAME_MAX
If defined, the unvarying maximum length of a time zone name. See section Functions and Variables for Time Zones.

These limit macros are always defined in `limits.h'.

Macro: int NGROUPS_MAX
The maximum number of supplementary group IDs that one process can have.

The value of this macro is actually a lower bound for the maximum. That is, you can count on being able to have that many supplementary group IDs, but a particular machine might let you have even more. You can use sysconf to see whether a particular machine will let you have more (see section Using sysconf).

Macro: int SSIZE_MAX
The largest value that can fit in an object of type ssize_t. Effectively, this is the limit on the number of bytes that can be read or written in a single operation.

This macro is defined in all POSIX systems because this limit is never configurable.

Macro: int RE_DUP_MAX
The largest number of repetitions you are guaranteed is allowed in the construct `\{min,max\}' in a regular expression.

The value of this macro is actually a lower bound for the maximum. That is, you can count on being able to have that many repetitions, but a particular machine might let you have even more. You can use sysconf to see whether a particular machine will let you have more (see section Using sysconf). And even the value that sysconf tells you is just a lower bound--larger values might work.

This macro is defined in all POSIX.2 systems, because POSIX.2 says it should always be defined even if there is no specific imposed limit.

Overall System Options

POSIX defines certain system-specific options that not all POSIX systems support. Since these options are provided in the kernel, not in the library, simply using the GNU C library does not guarantee any of these features is supported; it depends on the system you are using.

You can test for the availability of a given option using the macros in this section, together with the function sysconf. The macros are defined only if you include `unistd.h'.

For the following macros, if the macro is defined in `unistd.h', then the option is supported. Otherwise, the option may or may not be supported; use sysconf to find out. See section Using sysconf.

Macro: int _POSIX_JOB_CONTROL
If this symbol is defined, it indicates that the system supports job control. Otherwise, the implementation behaves as if all processes within a session belong to a single process group. See section Job Control.

Macro: int _POSIX_SAVED_IDS
If this symbol is defined, it indicates that the system remembers the effective user and group IDs of a process before it executes an executable file with the set-user-ID or set-group-ID bits set, and that explicitly changing the effective user or group IDs back to these values is permitted. If this option is not defined, then if a nonprivileged process changes its effective user or group ID to the real user or group ID of the process, it can't change it back again. See section Enabling and Disabling Setuid Access.

For the following macros, if the macro is defined in `unistd.h', then its value indicates whether the option is supported. A value of -1 means no, and any other value means yes. If the macro is not defined, then the option may or may not be supported; use sysconf to find out. See section Using sysconf.

Macro: int _POSIX2_C_DEV
If this symbol is defined, it indicates that the system has the POSIX.2 C compiler command, c89. The GNU C library always defines this as 1, on the assumption that you would not have installed it if you didn't have a C compiler.

Macro: int _POSIX2_FORT_DEV
If this symbol is defined, it indicates that the system has the POSIX.2 Fortran compiler command, fort77. The GNU C library never defines this, because we don't know what the system has.

Macro: int _POSIX2_FORT_RUN
If this symbol is defined, it indicates that the system has the POSIX.2 asa command to interpret Fortran carriage control. The GNU C library never defines this, because we don't know what the system has.

Macro: int _POSIX2_LOCALEDEF
If this symbol is defined, it indicates that the system has the POSIX.2 localedef command. The GNU C library never defines this, because we don't know what the system has.

Macro: int _POSIX2_SW_DEV
If this symbol is defined, it indicates that the system has the POSIX.2 commands ar, make, and strip. The GNU C library always defines this as 1, on the assumption that you had to have ar and make to install the library, and it's unlikely that strip would be absent when those are present.

Which Version of POSIX is Supported

Macro: long int _POSIX_VERSION
This constant represents the version of the POSIX.1 standard to which the implementation conforms. For an implementation conforming to the 1995 POSIX.1 standard, the value is the integer 199506L.

_POSIX_VERSION is always defined (in `unistd.h') in any POSIX system.

Usage Note: Don't try to test whether the system supports POSIX by including `unistd.h' and then checking whether _POSIX_VERSION is defined. On a non-POSIX system, this will probably fail because there is no `unistd.h'. We do not know of any way you can reliably test at compilation time whether your target system supports POSIX or whether `unistd.h' exists.

The GNU C compiler predefines the symbol __POSIX__ if the target system is a POSIX system. Provided you do not use any other compilers on POSIX systems, testing defined (__POSIX__) will reliably detect such systems.

Macro: long int _POSIX2_C_VERSION
This constant represents the version of the POSIX.2 standard which the library and system kernel support. We don't know what value this will be for the first version of the POSIX.2 standard, because the value is based on the year and month in which the standard is officially adopted.

The value of this symbol says nothing about the utilities installed on the system.

Usage Note: You can use this macro to tell whether a POSIX.1 system library supports POSIX.2 as well. Any POSIX.1 system contains `unistd.h', so include that file and then test defined (_POSIX2_C_VERSION).

Using sysconf

When your system has configurable system limits, you can use the sysconf function to find out the value that applies to any particular machine. The function and the associated parameter constants are declared in the header file `unistd.h'.

Definition of sysconf

Function: long int sysconf (int parameter)
This function is used to inquire about runtime system parameters. The parameter argument should be one of the `_SC_' symbols listed below.

The normal return value from sysconf is the value you requested. A value of -1 is returned both if the implementation does not impose a limit, and in case of an error.

The following errno error conditions are defined for this function:

EINVAL
The value of the parameter is invalid.
Constants for sysconf Parameters

Here are the symbolic constants for use as the parameter argument to sysconf. The values are all integer constants (more specifically, enumeration type values).

_SC_ARG_MAX
Inquire about the parameter corresponding to ARG_MAX.
_SC_CHILD_MAX
Inquire about the parameter corresponding to CHILD_MAX.
_SC_OPEN_MAX
Inquire about the parameter corresponding to OPEN_MAX.
_SC_STREAM_MAX
Inquire about the parameter corresponding to STREAM_MAX.
_SC_TZNAME_MAX
Inquire about the parameter corresponding to TZNAME_MAX.
_SC_NGROUPS_MAX
Inquire about the parameter corresponding to NGROUPS_MAX.
_SC_JOB_CONTROL
Inquire about the parameter corresponding to _POSIX_JOB_CONTROL.
_SC_SAVED_IDS
Inquire about the parameter corresponding to _POSIX_SAVED_IDS.
_SC_VERSION
Inquire about the parameter corresponding to _POSIX_VERSION.
_SC_CLK_TCK
Inquire about the parameter corresponding to CLOCKS_PER_SEC; see section CPU Time Inquiry.
_SC_CHARCLASS_NAME_MAX
Inquire about the parameter corresponding to maximal length allowed for a character class name in an extended locale specification. These extensions are not yet standardized and so this option is not standardized as well.
_SC_REALTIME_SIGNALS
Inquire about the parameter corresponding to _POSIX_REALTIME_SIGNALS.
_SC_PRIORITY_SCHEDULING
Inquire about the parameter corresponding to _POSIX_PRIORITY_SCHEDULING.
_SC_TIMERS
Inquire about the parameter corresponding to _POSIX_TIMERS.
_SC_ASYNCHRONOUS_IO
Inquire about the parameter corresponding to _POSIX_ASYNCHRONOUS_IO.
_SC_PRIORITIZED_IO
Inquire about the parameter corresponding to _POSIX_PRIORITIZED_IO.
_SC_SYNCHRONIZED_IO
Inquire about the parameter corresponding to _POSIX_SYNCHRONIZED_IO.
_SC_FSYNC
Inquire about the parameter corresponding to _POSIX_FSYNC.
_SC_MAPPED_FILES
Inquire about the parameter corresponding to _POSIX_MAPPED_FILES.
_SC_MEMLOCK
Inquire about the parameter corresponding to _POSIX_MEMLOCK.
_SC_MEMLOCK_RANGE
Inquire about the parameter corresponding to _POSIX_MEMLOCK_RANGE.
_SC_MEMORY_PROTECTION
Inquire about the parameter corresponding to _POSIX_MEMORY_PROTECTION.
_SC_MESSAGE_PASSING
Inquire about the parameter corresponding to _POSIX_MESSAGE_PASSING.
_SC_SEMAPHORES
Inquire about the parameter corresponding to _POSIX_SEMAPHORES.
_SC_SHARED_MEMORY_OBJECTS
Inquire about the parameter corresponding to
_POSIX_SHARED_MEMORY_OBJECTS.
_SC_AIO_LISTIO_MAX
Inquire about the parameter corresponding to _POSIX_AIO_LISTIO_MAX.
_SC_AIO_MAX
Inquire about the parameter corresponding to _POSIX_AIO_MAX.
_SC_AIO_PRIO_DELTA_MAX
Inquire the value by which a process can decrease its asynchronous I/O priority level from its own scheduling priority. This corresponds to the run-time invariant value AIO_PRIO_DELTA_MAX.
_SC_DELAYTIMER_MAX
Inquire about the parameter corresponding to _POSIX_DELAYTIMER_MAX.
_SC_MQ_OPEN_MAX
Inquire about the parameter corresponding to _POSIX_MQ_OPEN_MAX.
_SC_MQ_PRIO_MAX
Inquire about the parameter corresponding to _POSIX_MQ_PRIO_MAX.
_SC_RTSIG_MAX
Inquire about the parameter corresponding to _POSIX_RTSIG_MAX.
_SC_SEM_NSEMS_MAX
Inquire about the parameter corresponding to _POSIX_SEM_NSEMS_MAX.
_SC_SEM_VALUE_MAX
Inquire about the parameter corresponding to _POSIX_SEM_VALUE_MAX.
_SC_SIGQUEUE_MAX
Inquire about the parameter corresponding to _POSIX_SIGQUEUE_MAX.
_SC_TIMER_MAX
Inquire about the parameter corresponding to _POSIX_TIMER_MAX.
_SC_PII
Inquire about the parameter corresponding to _POSIX_PII.
_SC_PII_XTI
Inquire about the parameter corresponding to _POSIX_PII_XTI.
_SC_PII_SOCKET
Inquire about the parameter corresponding to _POSIX_PII_SOCKET.
_SC_PII_INTERNET
Inquire about the parameter corresponding to _POSIX_PII_INTERNET.
_SC_PII_OSI
Inquire about the parameter corresponding to _POSIX_PII_OSI.
_SC_SELECT
Inquire about the parameter corresponding to _POSIX_SELECT.
_SC_UIO_MAXIOV
Inquire about the parameter corresponding to _POSIX_UIO_MAXIOV.
_SC_PII_INTERNET_STREAM
Inquire about the parameter corresponding to _POSIX_PII_INTERNET_STREAM.
_SC_PII_INTERNET_DGRAM
Inquire about the parameter corresponding to _POSIX_PII_INTERNET_DGRAM.
_SC_PII_OSI_COTS
Inquire about the parameter corresponding to _POSIX_PII_OSI_COTS.
_SC_PII_OSI_CLTS
Inquire about the parameter corresponding to _POSIX_PII_OSI_CLTS.
_SC_PII_OSI_M
Inquire about the parameter corresponding to _POSIX_PII_OSI_M.
_SC_T_IOV_MAX
Inquire the value of the value associated with the T_IOV_MAX variable.
_SC_THREADS
Inquire about the parameter corresponding to _POSIX_THREADS.
_SC_THREAD_SAFE_FUNCTIONS
Inquire about the parameter corresponding to
_POSIX_THREAD_SAFE_FUNCTIONS.
_SC_GETGR_R_SIZE_MAX
Inquire about the parameter corresponding to _POSIX_GETGR_R_SIZE_MAX.
_SC_GETPW_R_SIZE_MAX
Inquire about the parameter corresponding to _POSIX_GETPW_R_SIZE_MAX.
_SC_LOGIN_NAME_MAX
Inquire about the parameter corresponding to _POSIX_LOGIN_NAME_MAX.
_SC_TTY_NAME_MAX
Inquire about the parameter corresponding to _POSIX_TTY_NAME_MAX.
_SC_THREAD_DESTRUCTOR_ITERATIONS
Inquire about the parameter corresponding to _POSIX_THREAD_DESTRUCTOR_ITERATIONS.
_SC_THREAD_KEYS_MAX
Inquire about the parameter corresponding to _POSIX_THREAD_KEYS_MAX.
_SC_THREAD_STACK_MIN
Inquire about the parameter corresponding to _POSIX_THREAD_STACK_MIN.
_SC_THREAD_THREADS_MAX
Inquire about the parameter corresponding to _POSIX_THREAD_THREADS_MAX.
_SC_THREAD_ATTR_STACKADDR
Inquire about the parameter corresponding to
a _POSIX_THREAD_ATTR_STACKADDR.
_SC_THREAD_ATTR_STACKSIZE
Inquire about the parameter corresponding to
_POSIX_THREAD_ATTR_STACKSIZE.
_SC_THREAD_PRIORITY_SCHEDULING
Inquire about the parameter corresponding to _POSIX_THREAD_PRIORITY_SCHEDULING.
_SC_THREAD_PRIO_INHERIT
Inquire about the parameter corresponding to _POSIX_THREAD_PRIO_INHERIT.
_SC_THREAD_PRIO_PROTECT
Inquire about the parameter corresponding to _POSIX_THREAD_PRIO_PROTECT.
_SC_THREAD_PROCESS_SHARED
Inquire about the parameter corresponding to _POSIX_THREAD_PROCESS_SHARED.
_SC_2_C_DEV
Inquire about whether the system has the POSIX.2 C compiler command, c89.
_SC_2_FORT_DEV
Inquire about whether the system has the POSIX.2 Fortran compiler command, fort77.
_SC_2_FORT_RUN
Inquire about whether the system has the POSIX.2 asa command to interpret Fortran carriage control.
_SC_2_LOCALEDEF
Inquire about whether the system has the POSIX.2 localedef command.
_SC_2_SW_DEV
Inquire about whether the system has the POSIX.2 commands ar, make, and strip.
_SC_BC_BASE_MAX
Inquire about the maximum value of obase in the bc utility.
_SC_BC_DIM_MAX
Inquire about the maximum size of an array in the bc utility.
_SC_BC_SCALE_MAX
Inquire about the maximum value of scale in the bc utility.
_SC_BC_STRING_MAX
Inquire about the maximum size of a string constant in the bc utility.
_SC_COLL_WEIGHTS_MAX
Inquire about the maximum number of weights that can necessarily be used in defining the collating sequence for a locale.
_SC_EXPR_NEST_MAX
Inquire about the maximum number of expressions nested within parentheses when using the expr utility.
_SC_LINE_MAX
Inquire about the maximum size of a text line that the POSIX.2 text utilities can handle.
_SC_EQUIV_CLASS_MAX
Inquire about the maximum number of weights that can be assigned to an entry of the LC_COLLATE category `order' keyword in a locale definition. The GNU C library does not presently support locale definitions.
_SC_VERSION
Inquire about the version number of POSIX.1 that the library and kernel support.
_SC_2_VERSION
Inquire about the version number of POSIX.2 that the system utilities support.
_SC_PAGESIZE
Inquire about the virtual memory page size of the machine. getpagesize returns the same value (see section How to get information about the memory subsystem?).
_SC_NPROCESSORS_CONF
Inquire about the number of configured processors.
_SC_NPROCESSORS_ONLN
Inquire about the number of processors online.
_SC_PHYS_PAGES
Inquire about the number of physical pages in the system.
_SC_AVPHYS_PAGES
Inquire about the number of available physical pages in the system.
_SC_ATEXIT_MAX
Inquire about the number of functions which can be registered as termination functions for atexit; see section Cleanups on Exit.
_SC_XOPEN_VERSION
Inquire about the parameter corresponding to _XOPEN_VERSION.
_SC_XOPEN_XCU_VERSION
Inquire about the parameter corresponding to _XOPEN_XCU_VERSION.
_SC_XOPEN_UNIX
Inquire about the parameter corresponding to _XOPEN_UNIX.
_SC_XOPEN_REALTIME
Inquire about the parameter corresponding to _XOPEN_REALTIME.
_SC_XOPEN_REALTIME_THREADS
Inquire about the parameter corresponding to _XOPEN_REALTIME_THREADS.
_SC_XOPEN_LEGACY
Inquire about the parameter corresponding to _XOPEN_LEGACY.
_SC_XOPEN_CRYPT
Inquire about the parameter corresponding to _XOPEN_CRYPT.
_SC_XOPEN_ENH_I18N
Inquire about the parameter corresponding to _XOPEN_ENH_I18N.
_SC_XOPEN_SHM
Inquire about the parameter corresponding to _XOPEN_SHM.
_SC_XOPEN_XPG2
Inquire about the parameter corresponding to _XOPEN_XPG2.
_SC_XOPEN_XPG3
Inquire about the parameter corresponding to _XOPEN_XPG3.
_SC_XOPEN_XPG4
Inquire about the parameter corresponding to _XOPEN_XPG4.
_SC_CHAR_BIT
Inquire about the number of bits in a variable of type char.
_SC_CHAR_MAX
Inquire about the maximum value which can be stored in a variable of type char.
_SC_CHAR_MIN
Inquire about the minimum value which can be stored in a variable of type char.
_SC_INT_MAX
Inquire about the maximum value which can be stored in a variable of type int.
_SC_INT_MIN
Inquire about the minimum value which can be stored in a variable of type int.
_SC_LONG_BIT
Inquire about the number of bits in a variable of type long int.
_SC_WORD_BIT
Inquire about the number of bits in a variable of a register word.
_SC_MB_LEN_MAX
Inquire the maximum length of a multi-byte representation of a wide character value.
_SC_NZERO
Inquire about the value used to internally represent the zero priority level for the process execution.
SC_SSIZE_MAX
Inquire about the maximum value which can be stored in a variable of type ssize_t.
_SC_SCHAR_MAX
Inquire about the maximum value which can be stored in a variable of type signed char.
_SC_SCHAR_MIN
Inquire about the minimum value which can be stored in a variable of type signed char.
_SC_SHRT_MAX
Inquire about the maximum value which can be stored in a variable of type short int.
_SC_SHRT_MIN
Inquire about the minimum value which can be stored in a variable of type short int.
_SC_UCHAR_MAX
Inquire about the maximum value which can be stored in a variable of type unsigned char.
_SC_UINT_MAX
Inquire about the maximum value which can be stored in a variable of type unsigned int.
_SC_ULONG_MAX
Inquire about the maximum value which can be stored in a variable of type unsigned long int.
_SC_USHRT_MAX
Inquire about the maximum value which can be stored in a variable of type unsigned short int.
_SC_NL_ARGMAX
Inquire about the parameter corresponding to NL_ARGMAX.
_SC_NL_LANGMAX
Inquire about the parameter corresponding to NL_LANGMAX.
_SC_NL_MSGMAX
Inquire about the parameter corresponding to NL_MSGMAX.
_SC_NL_NMAX
Inquire about the parameter corresponding to NL_NMAX.
_SC_NL_SETMAX
Inquire about the parameter corresponding to NL_SETMAX.
_SC_NL_TEXTMAX
Inquire about the parameter corresponding to NL_TEXTMAX.
Examples of sysconf

We recommend that you first test for a macro definition for the parameter you are interested in, and call sysconf only if the macro is not defined. For example, here is how to test whether job control is supported:
int
have_job_control (void)
{
#ifdef _POSIX_JOB_CONTROL
  return 1;
#else
  int value = sysconf (_SC_JOB_CONTROL);
  if (value < 0)
    /* If the system is that badly wedged,
       there's no use trying to go on.  */
    fatal (strerror (errno));
  return value;
#endif
}
Here is how to get the value of a numeric limit:
int
get_child_max ()
{
#ifdef CHILD_MAX
  return CHILD_MAX;
#else
  int value = sysconf (_SC_CHILD_MAX);
  if (value < 0)
    fatal (strerror (errno));
  return value;
#endif
}
Minimum Values for General Capacity Limits

Here are the names for the POSIX minimum upper bounds for the system limit parameters. The significance of these values is that you can safely push to these limits without checking whether the particular system you are using can go that far.

_POSIX_AIO_LISTIO_MAX
The most restrictive limit permitted by POSIX for the maximum number of I/O operations that can be specified in a list I/O call. The value of this constant is 2; thus you can add up to two new entries of the list of outstanding operations.
_POSIX_AIO_MAX
The most restrictive limit permitted by POSIX for the maximum number of outstanding asynchronous I/O operations. The value of this constant is 1. So you cannot expect that you can issue more than one operation and immediately continue with the normal work, receiving the notifications asynchronously.
_POSIX_ARG_MAX
The value of this macro is the most restrictive limit permitted by POSIX for the maximum combined length of the argv and environ arguments that can be passed to the exec functions. Its value is 4096.
_POSIX_CHILD_MAX
The value of this macro is the most restrictive limit permitted by POSIX for the maximum number of simultaneous processes per real user ID. Its value is 6.
_POSIX_NGROUPS_MAX
The value of this macro is the most restrictive limit permitted by POSIX for the maximum number of supplementary group IDs per process. Its value is 0.
_POSIX_OPEN_MAX
The value of this macro is the most restrictive limit permitted by POSIX for the maximum number of files that a single process can have open simultaneously. Its value is 16.
_POSIX_SSIZE_MAX
The value of this macro is the most restrictive limit permitted by POSIX for the maximum value that can be stored in an object of type ssize_t. Its value is 32767.
_POSIX_STREAM_MAX
The value of this macro is the most restrictive limit permitted by POSIX for the maximum number of streams that a single process can have open simultaneously. Its value is 8.
_POSIX_TZNAME_MAX
The value of this macro is the most restrictive limit permitted by POSIX for the maximum length of a time zone name. Its value is 3.
_POSIX2_RE_DUP_MAX
The value of this macro is the most restrictive limit permitted by POSIX for the numbers used in the `\{min,max\}' construct in a regular expression. Its value is 255.
Limits on File System Capacity

The POSIX.1 standard specifies a number of parameters that describe the limitations of the file system. It's possible for the system to have a fixed, uniform limit for a parameter, but this isn't the usual case. On most systems, it's possible for different file systems (and, for some parameters, even different files) to have different maximum limits. For example, this is very likely if you use NFS to mount some of the file systems from other machines.

Each of the following macros is defined in `limits.h' only if the system has a fixed, uniform limit for the parameter in question. If the system allows different file systems or files to have different limits, then the macro is undefined; use pathconf or fpathconf to find out the limit that applies to a particular file. See section Using pathconf.

Each parameter also has another macro, with a name starting with `_POSIX', which gives the lowest value that the limit is allowed to have on any POSIX system. See section Minimum Values for File System Limits.

Macro: int LINK_MAX
The uniform system limit (if any) for the number of names for a given file. See section Hard Links.

Macro: int MAX_CANON
The uniform system limit (if any) for the amount of text in a line of input when input editing is enabled. See section Two Styles of Input: Canonical or Not.

Macro: int MAX_INPUT
The uniform system limit (if any) for the total number of characters typed ahead as input. See section I/O Queues.

Macro: int NAME_MAX
The uniform system limit (if any) for the length of a file name component.

Macro: int PATH_MAX
The uniform system limit (if any) for the length of an entire file name (that is, the argument given to system calls such as open).

Macro: int PIPE_BUF
The uniform system limit (if any) for the number of bytes that can be written atomically to a pipe. If multiple processes are writing to the same pipe simultaneously, output from different processes might be interleaved in chunks of this size. See section Pipes and FIFOs.

These are alternative macro names for some of the same information.

Macro: int MAXNAMLEN
This is the BSD name for NAME_MAX. It is defined in `dirent.h'.

Macro: int FILENAME_MAX
The value of this macro is an integer constant expression that represents the maximum length of a file name string. It is defined in `stdio.h'.

Unlike PATH_MAX, this macro is defined even if there is no actual limit imposed. In such a case, its value is typically a very large number. This is always the case on the GNU system.

Usage Note: Don't use FILENAME_MAX as the size of an array in which to store a file name! You can't possibly make an array that big! Use dynamic allocation (see section Allocating Storage For Program Data) instead.

Optional Features in File Support

POSIX defines certain system-specific options in the system calls for operating on files. Some systems support these options and others do not. Since these options are provided in the kernel, not in the library, simply using the GNU C library does not guarantee that any of these features is supported; it depends on the system you are using. They can also vary between file systems on a single machine.

This section describes the macros you can test to determine whether a particular option is supported on your machine. If a given macro is defined in `unistd.h', then its value says whether the corresponding feature is supported. (A value of -1 indicates no; any other value indicates yes.) If the macro is undefined, it means particular files may or may not support the feature.

Since all the machines that support the GNU C library also support NFS, one can never make a general statement about whether all file systems support the _POSIX_CHOWN_RESTRICTED and _POSIX_NO_TRUNC features. So these names are never defined as macros in the GNU C library.

Macro: int _POSIX_CHOWN_RESTRICTED
If this option is in effect, the chown function is restricted so that the only changes permitted to nonprivileged processes is to change the group owner of a file to either be the effective group ID of the process, or one of its supplementary group IDs. See section File Owner.

Macro: int _POSIX_NO_TRUNC
If this option is in effect, file name components longer than NAME_MAX generate an ENAMETOOLONG error. Otherwise, file name components that are too long are silently truncated.

Macro: unsigned char _POSIX_VDISABLE
This option is only meaningful for files that are terminal devices. If it is enabled, then handling for special control characters can be disabled individually. See section Special Characters.

If one of these macros is undefined, that means that the option might be in effect for some files and not for others. To inquire about a particular file, call pathconf or fpathconf. See section Using pathconf.

Minimum Values for File System Limits

Here are the names for the POSIX minimum upper bounds for some of the above parameters. The significance of these values is that you can safely push to these limits without checking whether the particular system you are using can go that far. In most cases GNU systems do not have these strict limitations. The actual limit should be requested if necessary.

_POSIX_LINK_MAX
The most restrictive limit permitted by POSIX for the maximum value of a file's link count. The value of this constant is 8; thus, you can always make up to eight names for a file without running into a system limit.
_POSIX_MAX_CANON
The most restrictive limit permitted by POSIX for the maximum number of bytes in a canonical input line from a terminal device. The value of this constant is 255.
_POSIX_MAX_INPUT
The most restrictive limit permitted by POSIX for the maximum number of bytes in a terminal device input queue (or typeahead buffer). See section Input Modes. The value of this constant is 255.
_POSIX_NAME_MAX
The most restrictive limit permitted by POSIX for the maximum number of bytes in a file name component. The value of this constant is 14.
_POSIX_PATH_MAX
The most restrictive limit permitted by POSIX for the maximum number of bytes in a file name. The value of this constant is 256.
_POSIX_PIPE_BUF
The most restrictive limit permitted by POSIX for the maximum number of bytes that can be written atomically to a pipe. The value of this constant is 512.
SYMLINK_MAX
Maximum number of bytes in a symbolic link.
POSIX_REC_INCR_XFER_SIZE
Recommended increment for file transfer sizes between the POSIX_REC_MIN_XFER_SIZE and POSIX_REC_MAX_XFER_SIZE values.
POSIX_REC_MAX_XFER_SIZE
Maximum recommended file transfer size.
POSIX_REC_MIN_XFER_SIZE
Minimum recommended file transfer size.
POSIX_REC_XFER_ALIGN
Recommended file transfer buffer alignment.
Using pathconf

When your machine allows different files to have different values for a file system parameter, you can use the functions in this section to find out the value that applies to any particular file.

These functions and the associated constants for the parameter argument are declared in the header file `unistd.h'.

Function: long int pathconf (const char *filename, int parameter)
This function is used to inquire about the limits that apply to the file named filename.

The parameter argument should be one of the `_PC_' constants listed below.

The normal return value from pathconf is the value you requested. A value of -1 is returned both if the implementation does not impose a limit, and in case of an error. In the former case, errno is not set, while in the latter case, errno is set to indicate the cause of the problem. So the only way to use this function robustly is to store 0 into errno just before calling it.

Besides the usual file name errors (see section File Name Errors), the following error condition is defined for this function:

EINVAL
The value of parameter is invalid, or the implementation doesn't support the parameter for the specific file.

Function: long int fpathconf (int filedes, int parameter)
This is just like pathconf except that an open file descriptor is used to specify the file for which information is requested, instead of a file name.

The following errno error conditions are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.
EINVAL
The value of parameter is invalid, or the implementation doesn't support the parameter for the specific file.
Here are the symbolic constants that you can use as the parameter argument to pathconf and fpathconf. The values are all integer constants.

_PC_LINK_MAX
Inquire about the value of LINK_MAX.
_PC_MAX_CANON
Inquire about the value of MAX_CANON.
_PC_MAX_INPUT
Inquire about the value of MAX_INPUT.
_PC_NAME_MAX
Inquire about the value of NAME_MAX.
_PC_PATH_MAX
Inquire about the value of PATH_MAX.
_PC_PIPE_BUF
Inquire about the value of PIPE_BUF.
_PC_CHOWN_RESTRICTED
Inquire about the value of _POSIX_CHOWN_RESTRICTED.
_PC_NO_TRUNC
Inquire about the value of _POSIX_NO_TRUNC.
_PC_VDISABLE
Inquire about the value of _POSIX_VDISABLE.
_PC_SYNC_IO
Inquire about the value of _POSIX_SYNC_IO.
_PC_ASYNC_IO
Inquire about the value of _POSIX_ASYNC_IO.
_PC_PRIO_IO
Inquire about the value of _POSIX_PRIO_IO.
_PC_SOCK_MAXBUF
Inquire about the value of _POSIX_PIPE_BUF.
_PC_FILESIZEBITS
Inquire about the availability of large files on the filesystem.
_PC_REC_INCR_XFER_SIZE
Inquire about the value of POSIX_REC_INCR_XFER_SIZE.
_PC_REC_MAX_XFER_SIZE
Inquire about the value of POSIX_REC_MAX_XFER_SIZE.
_PC_REC_MIN_XFER_SIZE
Inquire about the value of POSIX_REC_MIN_XFER_SIZE.
_PC_REC_XFER_ALIGN
Inquire about the value of POSIX_REC_XFER_ALIGN.
Utility Program Capacity Limits

The POSIX.2 standard specifies certain system limits that you can access through sysconf that apply to utility behavior rather than the behavior of the library or the operating system.

The GNU C library defines macros for these limits, and sysconf returns values for them if you ask; but these values convey no meaningful information. They are simply the smallest values that POSIX.2 permits.

Macro: int BC_BASE_MAX
The largest value of obase that the bc utility is guaranteed to support.

Macro: int BC_DIM_MAX
The largest number of elements in one array that the bc utility is guaranteed to support.

Macro: int BC_SCALE_MAX
The largest value of scale that the bc utility is guaranteed to support.

Macro: int BC_STRING_MAX
The largest number of characters in one string constant that the bc utility is guaranteed to support.

Macro: int COLL_WEIGHTS_MAX
The largest number of weights that can necessarily be used in defining the collating sequence for a locale.

Macro: int EXPR_NEST_MAX
The maximum number of expressions that can be nested within parenthesis by the expr utility.

Macro: int LINE_MAX
The largest text line that the text-oriented POSIX.2 utilities can support. (If you are using the GNU versions of these utilities, then there is no actual limit except that imposed by the available virtual memory, but there is no way that the library can tell you this.)

Macro: int EQUIV_CLASS_MAX
The maximum number of weights that can be assigned to an entry of the LC_COLLATE category `order' keyword in a locale definition. The GNU C library does not presently support locale definitions.

Minimum Values for Utility Limits

_POSIX2_BC_BASE_MAX
The most restrictive limit permitted by POSIX.2 for the maximum value of obase in the bc utility. Its value is 99.
_POSIX2_BC_DIM_MAX
The most restrictive limit permitted by POSIX.2 for the maximum size of an array in the bc utility. Its value is 2048.
_POSIX2_BC_SCALE_MAX
The most restrictive limit permitted by POSIX.2 for the maximum value of scale in the bc utility. Its value is 99.
_POSIX2_BC_STRING_MAX
The most restrictive limit permitted by POSIX.2 for the maximum size of a string constant in the bc utility. Its value is 1000.
_POSIX2_COLL_WEIGHTS_MAX
The most restrictive limit permitted by POSIX.2 for the maximum number of weights that can necessarily be used in defining the collating sequence for a locale. Its value is 2.
_POSIX2_EXPR_NEST_MAX
The most restrictive limit permitted by POSIX.2 for the maximum number of expressions nested within parenthesis when using the expr utility. Its value is 32.
_POSIX2_LINE_MAX
The most restrictive limit permitted by POSIX.2 for the maximum size of a text line that the text utilities can handle. Its value is 2048.
_POSIX2_EQUIV_CLASS_MAX
The most restrictive limit permitted by POSIX.2 for the maximum number of weights that can be assigned to an entry of the LC_COLLATE category `order' keyword in a locale definition. Its value is 2. The GNU C library does not presently support locale definitions.
String-Valued Parameters

POSIX.2 defines a way to get string-valued parameters from the operating system with the function confstr:

Function: size_t confstr (int parameter, char *buf, size_t len)
This function reads the value of a string-valued system parameter, storing the string into len bytes of memory space starting at buf. The parameter argument should be one of the `_CS_' symbols listed below.

The normal return value from confstr is the length of the string value that you asked for. If you supply a null pointer for buf, then confstr does not try to store the string; it just returns its length. A value of 0 indicates an error.

If the string you asked for is too long for the buffer (that is, longer than len - 1), then confstr stores just that much (leaving room for the terminating null character). You can tell that this has happened because confstr returns a value greater than or equal to len.

The following errno error conditions are defined for this function:

EINVAL
The value of the parameter is invalid.
Currently there is just one parameter you can read with confstr:

_CS_PATH
This parameter's value is the recommended default path for searching for executable files. This is the path that a user has by default just after logging in.
_CS_LFS_CFLAGS
The returned string specifies which additional flags must be given to the C compiler if a source is compiled using the _LARGEFILE_SOURCE feature select macro; see section Feature Test Macros.
_CS_LFS_LDFLAGS
The returned string specifies which additional flags must be given to the linker if a source is compiled using the _LARGEFILE_SOURCE feature select macro; see section Feature Test Macros.
_CS_LFS_LIBS
The returned string specifies which additional libraries must be linked to the application if a source is compiled using the _LARGEFILE_SOURCE feature select macro; see section Feature Test Macros.
_CS_LFS_LINTFLAGS
The returned string specifies which additional flags must be given to the lint tool if a source is compiled using the _LARGEFILE_SOURCE feature select macro; see section Feature Test Macros.
_CS_LFS64_CFLAGS
The returned string specifies which additional flags must be given to the C compiler if a source is compiled using the _LARGEFILE64_SOURCE feature select macro; see section Feature Test Macros.
_CS_LFS64_LDFLAGS
The returned string specifies which additional flags must be given to the linker if a source is compiled using the _LARGEFILE64_SOURCE feature select macro; see section Feature Test Macros.
_CS_LFS64_LIBS
The returned string specifies which additional libraries must be linked to the application if a source is compiled using the _LARGEFILE64_SOURCE feature select macro; see section Feature Test Macros.
_CS_LFS64_LINTFLAGS
The returned string specifies which additional flags must be given to the lint tool if a source is compiled using the _LARGEFILE64_SOURCE feature select macro; see section Feature Test Macros.
The way to use confstr without any arbitrary limit on string size is to call it twice: first call it to get the length, allocate the buffer accordingly, and then call confstr again to fill the buffer, like this:
char *
get_default_path (void)
{
  size_t len = confstr (_CS_PATH, NULL, 0);
  char *buffer = (char *) xmalloc (len);

  if (confstr (_CS_PATH, buf, len + 1) == 0)
    {
      free (buffer);
      return NULL;
    }

  return buffer;
}
DES Encryption and Password Handling

On many systems, it is unnecessary to have any kind of user authentication; for instance, a workstation which is not connected to a network probably does not need any user authentication, because to use the machine an intruder must have physical access.

Sometimes, however, it is necessary to be sure that a user is authorised to use some service a machine provides--for instance, to log in as a particular user id (see section Users and Groups). One traditional way of doing this is for each user to choose a secret password; then, the system can ask someone claiming to be a user what the user's password is, and if the person gives the correct password then the system can grant the appropriate privileges.

If all the passwords are just stored in a file somewhere, then this file has to be very carefully protected. To avoid this, passwords are run through a one-way function, a function which makes it difficult to work out what its input was by looking at its output, before storing in the file.

The GNU C library already provides a one-way function based on MD5 and for compatibility with Unix systems the standard one-way function based on the Data Encryption Standard.

It also provides support for Secure RPC, and some library functions that can be used to perform normal DES encryption.

Legal Problems

Because of the continuously changing state of the law, it's not possible to provide a definitive survey of the laws affecting cryptography. Instead, this section warns you of some of the known trouble spots; this may help you when you try to find out what the laws of your country are.

Some countries require that you have a licence to use, posess, or import cryptography. These countries are believed to include Byelorussia, Burma, India, Indonesia, Israel, Kazakhstan, Pakistan, Russia, and Saudi Arabia.

Some countries restrict the transmission of encrypted messages by radio; some telecommunications carriers restrict the transmission of encrypted messages over their network.

Many countries have some form of export control for encryption software. The Wassenaar Arrangement is a multilateral agreement between 33 countries (Argentina, Australia, Austria, Belgium, Bulgaria, Canada, the Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway, Poland, Portugal, the Republic of Korea, Romania, the Russian Federation, the Slovak Republic, Spain, Sweden, Switzerland, Turkey, Ukraine, the United Kingdom and the United States) which restricts some kinds of encryption exports. Different countries apply the arrangement in different ways; some do not allow the exception for certain kinds of "public domain" software (which would include this library), some only restrict the export of software in tangible form, and others impose significant additional restrictions.

The United States has additional rules. This software would generally be exportable under 15 CFR 740.13(e), which permits exports of "encryption source code" which is "publicly available" and which is "not subject to an express agreement for the payment of a licensing fee or royalty for commercial production or sale of any product developed with the source code" to most countries.

The rules in this area are continuously changing. If you know of any information in this manual that is out-of-date, please report it using the glibcbug script. See section Reporting Bugs.

Reading Passwords

When reading in a password, it is desirable to avoid displaying it on the screen, to help keep it secret. The following function handles this in a convenient way.

Function: char * getpass (const char *prompt)

getpass outputs prompt, then reads a string in from the terminal without echoing it. It tries to connect to the real terminal, `/dev/tty', if possible, to encourage users not to put plaintext passwords in files; otherwise, it uses stdin and stderr. getpass also disables the INTR, QUIT, and SUSP characters on the terminal using the ISIG terminal attribute (see section Local Modes). The terminal is flushed before and after getpass, so that characters of a mistyped password are not accidentally visible.

In other C libraries, getpass may only return the first PASS_MAX bytes of a password. The GNU C library has no limit, so PASS_MAX is undefined.

The prototype for this function is in `unistd.h'. PASS_MAX would be defined in `limits.h'.

This precise set of operations may not suit all possible situations. In this case, it is recommended that users write their own getpass substitute. For instance, a very simple substitute is as follows:
#include <termios.h>
#include <stdio.h>

ssize_t
my_getpass (char **lineptr, size_t *n, FILE *stream)
{
  struct termios old, new;
  int nread;

  /* Turn echoing off and fail if we can't. */
  if (tcgetattr (fileno (stream), &old) != 0)
    return -1;
  new = old;
  new.c_lflag &= ~ECHO;
  if (tcsetattr (fileno (stream), TCSAFLUSH, &new) != 0)
    return -1;

  /* Read the password. */
  nread = getline (lineptr, n, stream);

  /* Restore terminal. */
  (void) tcsetattr (fileno (stream), TCSAFLUSH, &old);

  return nread;
}
The substitute takes the same parameters as getline (see section Line-Oriented Input); the user must print any prompt desired.

Encrypting Passwords

Function: char * crypt (const char *key, const char *salt)

The crypt function takes a password, key, as a string, and a salt character array which is described below, and returns a printable ASCII string which starts with another salt. It is believed that, given the output of the function, the best way to find a key that will produce that output is to guess values of key until the original value of key is found.

The salt parameter does two things. Firstly, it selects which algorithm is used, the MD5-based one or the DES-based one. Secondly, it makes life harder for someone trying to guess passwords against a file containing many passwords; without a salt, an intruder can make a guess, run crypt on it once, and compare the result with all the passwords. With a salt, the intruder must run crypt once for each different salt.

For the MD5-based algorithm, the salt should consist of the string $1$, followed by up to 8 characters, terminated by either another $ or the end of the string. The result of crypt will be the salt, followed by a $ if the salt didn't end with one, followed by 22 characters from the alphabet ./0-9A-Za-z, up to 34 characters total. Every character in the key is significant.

For the DES-based algorithm, the salt should consist of two characters from the alphabet ./0-9A-Za-z, and the result of crypt will be those two characters followed by 11 more from the same alphabet, 13 in total. Only the first 8 characters in the key are significant.

The MD5-based algorithm has no limit on the useful length of the password used, and is slightly more secure. It is therefore preferred over the DES-based algorithm.

When the user enters their password for the first time, the salt should be set to a new string which is reasonably random. To verify a password against the result of a previous call to crypt, pass the result of the previous call as the salt.

The following short program is an example of how to use crypt the first time a password is entered. Note that the salt generation is just barely acceptable; in particular, it is not unique between machines, and in many applications it would not be acceptable to let an attacker know what time the user's password was last set.
#include <stdio.h>
#include <time.h>
#include <unistd.h>
#include <crypt.h>

int
main(void)
{
  unsigned long seed[2];
  char salt[] = "$1$........";
  const char *const seedchars =
    "./0123456789ABCDEFGHIJKLMNOPQRST"
    "UVWXYZabcdefghijklmnopqrstuvwxyz";
  char *password;
  int i;

  /* Generate a (not very) random seed.
     You should do it better than this... */
  seed[0] = time(NULL);
  seed[1] = getpid() ^ (seed[0] >> 14 & 0x30000);

  /* Turn it into printable characters from `seedchars'. */
  for (i = 0; i < 8; i++)
    salt[3+i] = seedchars[(seed[i/5] >> (i%5)*6) & 0x3f];

  /* Read in the user's password and encrypt it. */
  password = crypt(getpass("Password:"), salt);

  /* Print the results. */
  puts(password);
  return 0;
}
The next program shows how to verify a password. It prompts the user for a password and prints "Access granted." if the user types GNU libc manual.
#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <crypt.h>

int
main(void)
{
  /* Hashed form of "GNU libc manual". */
  const char *const pass = "$1$/iSaq7rB$EoUw5jJPPvAPECNaaWzMK/";

  char *result;
  int ok;

  /* Read in the user's password and encrypt it,
     passing the expected password in as the salt. */
  result = crypt(getpass("Password:"), pass);

  /* Test the result. */
  ok = strcmp (result, pass) == 0;

  puts(ok ? "Access granted." : "Access denied.");
  return ok ? 0 : 1;
}
Function: char * crypt_r (const char *key, const char *salt, {struct crypt_data *} data)

The crypt_r function does the same thing as crypt, but takes an extra parameter which includes space for its result (among other things), so it can be reentrant. data->initialized must be cleared to zero before the first time crypt_r is called.

The crypt_r function is a GNU extension.

The crypt and crypt_r functions are prototyped in the header `crypt.h'.

DES Encryption

The Data Encryption Standard is described in the US Government Federal Information Processing Standards (FIPS) 46-3 published by the National Institute of Standards and Technology. The DES has been very thoroughly analysed since it was developed in the late 1970s, and no new significant flaws have been found.

However, the DES uses only a 56-bit key (plus 8 parity bits), and a machine has been built in 1998 which can search through all possible keys in about 6 days, which cost about US$200000; faster searches would be possible with more money. This makes simple DES unsecure for most purposes, and NIST no longer permits new US government systems to use simple DES.

For serious encryption functionality, it is recommended that one of the many free encryption libraries be used instead of these routines.

The DES is a reversible operation which takes a 64-bit block and a 64-bit key, and produces another 64-bit block. Usually the bits are numbered so that the most-significant bit, the first bit, of each block is numbered 1.

Under that numbering, every 8th bit of the key (the 8th, 16th, and so on) is not used by the encryption algorithm itself. But the key must have odd parity; that is, out of bits 1 through 8, and 9 through 16, and so on, there must be an odd number of `1' bits, and this completely specifies the unused bits.

Function: void setkey (const char *key)

The setkey function sets an internal data structure to be an expanded form of key. key is specified as an array of 64 bits each stored in a char, the first bit is key[0] and the 64th bit is key[63]. The key should have the correct parity.

Function: void encrypt (char *block, int edflag)

The encrypt function encrypts block if edflag is 0, otherwise it decrypts block, using a key previously set by setkey. The result is placed in block.

Like setkey, block is specified as an array of 64 bits each stored in a char, but there are no parity bits in block.

Function: void setkey_r (const char *key, {struct crypt_data *} data)

Function: void encrypt_r (char *block, int edflag, {struct crypt_data *} data)

These are reentrant versions of setkey and encrypt. The only difference is the extra parameter, which stores the expanded version of key. Before calling setkey_r the first time, data->initialised must be cleared to zero.

The setkey_r and encrypt_r functions are GNU extensions. setkey, encrypt, setkey_r, and encrypt_r are defined in `crypt.h'.

Function: int ecb_crypt (char *key, char *blocks, unsigned len, unsigned mode)

The function ecb_crypt encrypts or decrypts one or more blocks using DES. Each block is encrypted independently.

The blocks and the key are stored packed in 8-bit bytes, so that the first bit of the key is the most-significant bit of key[0] and the 63rd bit of the key is stored as the least-significant bit of key[7]. The key should have the correct parity.

len is the number of bytes in blocks. It should be a multiple of 8 (so that there is a whole number of blocks to encrypt). len is limited to a maximum of DES_MAXDATA bytes.

The result of the encryption replaces the input in blocks.

The mode parameter is the bitwise OR of two of the following:

DES_ENCRYPT
This constant, used in the mode parameter, specifies that blocks is to be encrypted.
DES_DECRYPT
This constant, used in the mode parameter, specifies that blocks is to be decrypted.
DES_HW
This constant, used in the mode parameter, asks to use a hardware device. If no hardware device is available, encryption happens anyway, but in software.
DES_SW
This constant, used in the mode parameter, specifies that no hardware device is to be used.
The result of the function will be one of these values:

DESERR_NONE
The encryption succeeded.
DESERR_NOHWDEVICE
The encryption succeeded, but there was no hardware device available.
DESERR_HWERROR
The encryption failed because of a hardware problem.
DESERR_BADPARAM
The encryption failed because of a bad parameter, for instance len is not a multiple of 8 or len is larger than DES_MAXDATA.

Function: int DES_FAILED (int err)
This macro returns 1 if err is a `success' result code from ecb_crypt or cbc_crypt, and 0 otherwise.

Function: int cbc_crypt (char *key, char *blocks, unsigned len, unsigned mode, char *ivec)

The function cbc_crypt encrypts or decrypts one or more blocks using DES in Cipher Block Chaining mode.

For encryption in CBC mode, each block is exclusive-ored with ivec before being encrypted, then ivec is replaced with the result of the encryption, then the next block is processed. Decryption is the reverse of this process.

This has the advantage that blocks which are the same before being encrypted are very unlikely to be the same after being encrypted, making it much harder to detect patterns in the data.

Usually, ivec is set to 8 random bytes before encryption starts. Then the 8 random bytes are transmitted along with the encrypted data (without themselves being encrypted), and passed back in as ivec for decryption. Another possibility is to set ivec to 8 zeroes initially, and have the first the block encrypted consist of 8 random bytes.

Otherwise, all the parameters are similar to those for ecb_crypt.

Function: void des_setparity (char *key)

The function des_setparity changes the 64-bit key, stored packed in 8-bit bytes, to have odd parity by altering the low bits of each byte.

The ecb_crypt, cbc_crypt, and des_setparity functions and their accompanying macros are all defined in the header `rpc/des_crypt.h'.
Debugging support

Applications are usually debugged using dedicated debugger programs. But sometimes this is not possible and, in any case, it is useful to provide the developer with as much information as possible at the time the problems are experienced. For this reason a few functions are provided which a program can use to help the developer more easily locate the problem.

Backtraces

A backtrace is a list of the function calls that are currently active in a thread. The usual way to inspect a backtrace of a program is to use an external debugger such as gdb. However, sometimes it is useful to obtain a backtrace programatically from within a program, e.g., for the purposes of logging or diagnostics.

The header file `execinfo.h' declares three functions that obtain and manipulate backtraces of the current thread.

Function: int backtrace (void **buffer, int size)
The backtrace function obtains a backtrace for the current thread, as a list of pointers, and places the information into buffer. The argument size should be the number of void * elements that will fit into buffer. The return value is the actual number of entries of buffer that are obtained, and is at most size.

The pointers placed in buffer are actually return addresses obtained by inspecting the stack, one return address per stack frame.

Note that certain compiler optimisations may interfere with obtaining a valid backtrace. Function inlining causes the inlined function to not have a stack frame; tail call optimisation replaces one stack frame with another; frame pointer elimination will stop backtrace from interpreting the stack contents correctly.

Function: char ** backtrace_symbols (void *const *buffer, int size)
The backtrace_symbols function translates the information obtained from the backtrace function into an array of strings. The argument buffer should be a pointer to an array of addresses obtained via the backtrace function, and size is the number of entries in that array (the return value of backtrace).

The return value is a pointer to an array of strings, which has size entries just like the array buffer. Each string contains a printable representation of the corresponding element of buffer. It includes the function name (if this can be determined), an offset into the function, and the actual return address (in hexadecimal).

Currently, the function name and offset only be obtained on systems that use the ELF binary format for programs and libraries. On other systems, only the hexadecimal return address will be present. Also, you may need to pass additional flags to the linker to make the function names available to the program. (For example, on systems using GNU ld, you must pass (-rdynamic.)

The return value of backtrace_symbols is a pointer obtained via the malloc function, and it is the responsibility of the caller to free that pointer. Note that only the return value need be freed, not the individual strings.

The return value is NULL if sufficient memory for the strings cannot be obtained.

Function: void backtrace_symbols_fd (void *const *buffer, int size, int fd)
The backtrace_symbols_fd function performs the same translation as the function backtrace_symbols function. Instead of returning the strings to the caller, it writes the strings to the file descriptor fd, one per line. It does not use the malloc function, and can therefore be used in situations where that function might fail.

The following program illustrates the use of these functions. Note that the array to contain the return addresses returned by backtrace is allocated on the stack. Therefore code like this can be used in situations where the memory handling via malloc does not work anymore (in which case the backtrace_symbols has to be replaced by a backtrace_symbols_fd call as well). The number of return addresses is normally not very large. Even complicated programs rather seldom have a nesting level of more than, say, 50 and with 200 possible entries probably all programs should be covered.
#include <execinfo.h>
#include <stdio.h>
#include <stdlib.h>

/* Obtain a backtrace and print it to stdout. */
void
print_trace (void)
{
  void *array[10];
  size_t size;
  char **strings;
  size_t i;

  size = backtrace (array, 10);
  strings = backtrace_symbols (array, size);

  printf ("Obtained %zd stack frames.\n", size);

  for (i = 0; i < size; i++)
     printf ("%s\n", strings[i]);

  free (strings);
}

/* A dummy function to make the backtrace more interesting. */
void
dummy_function (void)
{
  print_trace ();
}

int
main (void)
{
  dummy_function ();
  return 0;
}
C Language Facilities in the Library

Some of the facilities implemented by the C library really should be thought of as parts of the C language itself. These facilities ought to be documented in the C Language Manual, not in the library manual; but since we don't have the language manual yet, and documentation for these features has been written, we are publishing it here.

Explicitly Checking Internal Consistency

When you're writing a program, it's often a good idea to put in checks at strategic places for "impossible" errors or violations of basic assumptions. These kinds of checks are helpful in debugging problems with the interfaces between different parts of the program, for example.

The assert macro, defined in the header file `assert.h', provides a convenient way to abort the program while printing a message about where in the program the error was detected.

Once you think your program is debugged, you can disable the error checks performed by the assert macro by recompiling with the macro NDEBUG defined. This means you don't actually have to change the program source code to disable these checks.

But disabling these consistency checks is undesirable unless they make the program significantly slower. All else being equal, more error checking is good no matter who is running the program. A wise user would rather have a program crash, visibly, than have it return nonsense without indicating anything might be wrong.

Macro: void assert (int expression)
Verify the programmer's belief that expression is nonzero at this point in the program.

If NDEBUG is not defined, assert tests the value of expression. If it is false (zero), assert aborts the program (see section Aborting a Program) after printing a message of the form:
`file':linenum: function: Assertion `expression' failed.
on the standard error stream stderr (see section Standard Streams). The filename and line number are taken from the C preprocessor macros __FILE__ and __LINE__ and specify where the call to assert was made. When using the GNU C compiler, the name of the function which calls assert is taken from the built-in variable __PRETTY_FUNCTION__; with older compilers, the function name and following colon are omitted.

If the preprocessor macro NDEBUG is defined before `assert.h' is included, the assert macro is defined to do absolutely nothing.

Warning: Even the argument expression expression is not evaluated if NDEBUG is in effect. So never use assert with arguments that involve side effects. For example, assert (++i > 0); is a bad idea, because i will not be incremented if NDEBUG is defined.

Sometimes the "impossible" condition you want to check for is an error return from an operating system function. Then it is useful to display not only where the program crashes, but also what error was returned. The assert_perror macro makes this easy.

Macro: void assert_perror (int errnum)
Similar to assert, but verifies that errnum is zero.

If NDEBUG is defined, assert_perror tests the value of errnum. If it is nonzero, assert_perror aborts the program after printing a message of the form:
`file':linenum: function: error text
on the standard error stream. The file name, line number, and function name are as for assert. The error text is the result of strerror (errnum). See section Error Messages.

Like assert, if NDEBUG is defined before `assert.h' is included, the assert_perror macro does absolutely nothing. It does not evaluate the argument, so errnum should not have any side effects. It is best for errnum to be just a simple variable reference; often it will be errno.

This macro is a GNU extension.

Usage note: The assert facility is designed for detecting internal inconsistency; it is not suitable for reporting invalid input or improper usage by the user of the program.

The information in the diagnostic messages printed by the assert and assert_perror macro is intended to help you, the programmer, track down the cause of a bug, but is not really useful for telling a user of your program why his or her input was invalid or why a command could not be carried out. What's more, your program should not abort when given invalid input, as assert would do--it should exit with nonzero status (see section Exit Status) after printing its error messages, or perhaps read another command or move on to the next input file.

See section Error Messages, for information on printing error messages for problems that do not represent bugs in the program.

Variadic Functions

ISO C defines a syntax for declaring a function to take a variable number or type of arguments. (Such functions are referred to as varargs functions or variadic functions.) However, the language itself provides no mechanism for such functions to access their non-required arguments; instead, you use the variable arguments macros defined in `stdarg.h'.

This section describes how to declare variadic functions, how to write them, and how to call them properly.

Compatibility Note: Many older C dialects provide a similar, but incompatible, mechanism for defining functions with variable numbers of arguments, using `varargs.h'.

Why Variadic Functions are Used

Ordinary C functions take a fixed number of arguments. When you define a function, you specify the data type for each argument. Every call to the function should supply the expected number of arguments, with types that can be converted to the specified ones. Thus, if the function `foo' is declared with int foo (int, char *); then you must call it with two arguments, a number (any kind will do) and a string pointer.

But some functions perform operations that can meaningfully accept an unlimited number of arguments.

In some cases a function can handle any number of values by operating on all of them as a block. For example, consider a function that allocates a one-dimensional array with malloc to hold a specified set of values. This operation makes sense for any number of values, as long as the length of the array corresponds to that number. Without facilities for variable arguments, you would have to define a separate function for each possible array size.

The library function printf (see section Formatted Output) is an example of another class of function where variable arguments are useful. This function prints its arguments (which can vary in type as well as number) under the control of a format template string.

These are good reasons to define a variadic function which can handle as many arguments as the caller chooses to pass.

Some functions such as open take a fixed set of arguments, but occasionally ignore the last few. Strict adherence to ISO C requires these functions to be defined as variadic; in practice, however, the GNU C compiler and most other C compilers let you define such a function to take a fixed set of arguments--the most it can ever use--and then only declare the function as variadic (or not declare its arguments at all!).

How Variadic Functions are Defined and Used

Defining and using a variadic function involves three steps:

Define the function as variadic, using an ellipsis (`...') in the argument list, and using special macros to access the variable arguments. See section Receiving the Argument Values.
Declare the function as variadic, using a prototype with an ellipsis (`...'), in all the files which call it. See section Syntax for Variable Arguments.
Call the function by writing the fixed arguments followed by the additional variable arguments. See section Calling Variadic Functions.

Syntax for Variable Arguments

A function that accepts a variable number of arguments must be declared with a prototype that says so. You write the fixed arguments as usual, and then tack on `...' to indicate the possibility of additional arguments. The syntax of ISO C requires at least one fixed argument before the `...'. For example,
int
func (const char *a, int b, ...)
{
  ...
}
defines a function func which returns an int and takes two required arguments, a const char * and an int. These are followed by any number of anonymous arguments.

Portability note: For some C compilers, the last required argument must not be declared register in the function definition. Furthermore, this argument's type must be self-promoting: that is, the default promotions must not change its type. This rules out array and function types, as well as float, char (whether signed or not) and short int (whether signed or not). This is actually an ISO C requirement.

Receiving the Argument Values

Ordinary fixed arguments have individual names, and you can use these names to access their values. But optional arguments have no names--nothing but `...'. How can you access them?

The only way to access them is sequentially, in the order they were written, and you must use special macros from `stdarg.h' in the following three step process:

You initialize an argument pointer variable of type va_list using va_start. The argument pointer when initialized points to the first optional argument.
You access the optional arguments by successive calls to va_arg. The first call to va_arg gives you the first optional argument, the next call gives you the second, and so on. You can stop at any time if you wish to ignore any remaining optional arguments. It is perfectly all right for a function to access fewer arguments than were supplied in the call, but you will get garbage values if you try to access too many arguments.
You indicate that you are finished with the argument pointer variable by calling va_end. (In practice, with most C compilers, calling va_end does nothing. This is always true in the GNU C compiler. But you might as well call va_end just in case your program is someday compiled with a peculiar compiler.)

See section Argument Access Macros, for the full definitions of va_start, va_arg and va_end.

Steps 1 and 3 must be performed in the function that accepts the optional arguments. However, you can pass the va_list variable as an argument to another function and perform all or part of step 2 there.

You can perform the entire sequence of three steps multiple times within a single function invocation. If you want to ignore the optional arguments, you can do these steps zero times.

You can have more than one argument pointer variable if you like. You can initialize each variable with va_start when you wish, and then you can fetch arguments with each argument pointer as you wish. Each argument pointer variable will sequence through the same set of argument values, but at its own pace.

Portability note: With some compilers, once you pass an argument pointer value to a subroutine, you must not keep using the same argument pointer value after that subroutine returns. For full portability, you should just pass it to va_end. This is actually an ISO C requirement, but most ANSI C compilers work happily regardless.

How Many Arguments Were Supplied

There is no general way for a function to determine the number and type of the optional arguments it was called with. So whoever designs the function typically designs a convention for the caller to specify the number and type of arguments. It is up to you to define an appropriate calling convention for each variadic function, and write all calls accordingly.

One kind of calling convention is to pass the number of optional arguments as one of the fixed arguments. This convention works provided all of the optional arguments are of the same type.

A similar alternative is to have one of the required arguments be a bit mask, with a bit for each possible purpose for which an optional argument might be supplied. You would test the bits in a predefined sequence; if the bit is set, fetch the value of the next argument, otherwise use a default value.

A required argument can be used as a pattern to specify both the number and types of the optional arguments. The format string argument to printf is one example of this (see section Formatted Output Functions).

Another possibility is to pass an "end marker" value as the last optional argument. For example, for a function that manipulates an arbitrary number of pointer arguments, a null pointer might indicate the end of the argument list. (This assumes that a null pointer isn't otherwise meaningful to the function.) The execl function works in just this way; see section Executing a File.

Calling Variadic Functions

You don't have to do anything special to call a variadic function. Just put the arguments (required arguments, followed by optional ones) inside parentheses, separated by commas, as usual. But you must declare the function with a prototype and know how the argument values are converted.

In principle, functions that are defined to be variadic must also be declared to be variadic using a function prototype whenever you call them. (See section Syntax for Variable Arguments, for how.) This is because some C compilers use a different calling convention to pass the same set of argument values to a function depending on whether that function takes variable arguments or fixed arguments.

In practice, the GNU C compiler always passes a given set of argument types in the same way regardless of whether they are optional or required. So, as long as the argument types are self-promoting, you can safely omit declaring them. Usually it is a good idea to declare the argument types for variadic functions, and indeed for all functions. But there are a few functions which it is extremely convenient not to have to declare as variadic--for example, open and printf.

Since the prototype doesn't specify types for optional arguments, in a call to a variadic function the default argument promotions are performed on the optional argument values. This means the objects of type char or short int (whether signed or not) are promoted to either int or unsigned int, as appropriate; and that objects of type float are promoted to type double. So, if the caller passes a char as an optional argument, it is promoted to an int, and the function can access it with va_arg (ap, int).

Conversion of the required arguments is controlled by the function prototype in the usual way: the argument expression is converted to the declared argument type as if it were being assigned to a variable of that type.

Argument Access Macros

Here are descriptions of the macros used to retrieve variable arguments. These macros are defined in the header file `stdarg.h'.

Data Type: va_list
The type va_list is used for argument pointer variables.

Macro: void va_start (va_list ap, last-required)
This macro initializes the argument pointer variable ap to point to the first of the optional arguments of the current function; last-required must be the last required argument to the function.

See section Old-Style Variadic Functions, for an alternate definition of va_start found in the header file `varargs.h'.

Macro: type va_arg (va_list ap, type)
The va_arg macro returns the value of the next optional argument, and modifies the value of ap to point to the subsequent argument. Thus, successive uses of va_arg return successive optional arguments.

The type of the value returned by va_arg is type as specified in the call. type must be a self-promoting type (not char or short int or float) that matches the type of the actual argument.

Macro: void va_end (va_list ap)
This ends the use of ap. After a va_end call, further va_arg calls with the same ap may not work. You should invoke va_end before returning from the function in which va_start was invoked with the same ap argument.

In the GNU C library, va_end does nothing, and you need not ever use it except for reasons of portability.

Sometimes it is necessary to parse the list of parameters more than once or one wants to remember a certain position in the parameter list. To do this, one will have to make a copy of the current value of the argument. But va_list is an opaque type and one cannot necessarily assign the value of one variable of type va_list to another variable of the same type.

Macro: void __va_copy (va_list dest, va_list src)
The __va_copy macro allows copying of objects of type va_list even if this is not an integral type. The argument pointer in dest is initialized to point to the same argument as the pointer in src.

This macro is a GNU extension but it will hopefully also be available in the next update of the ISO C standard.

If you want to use __va_copy you should always be prepared for the possibility that this macro will not be available. On architectures where a simple assignment is invalid, hopefully __va_copy will be available, so one should always write something like this:
{
  va_list ap, save;
  ...
#ifdef __va_copy
  __va_copy (save, ap);
#else
  save = ap;
#endif
  ...
}
Example of a Variadic Function

Here is a complete sample function that accepts a variable number of arguments. The first argument to the function is the count of remaining arguments, which are added up and the result returned. While trivial, this function is sufficient to illustrate how to use the variable arguments facility.
#include <stdarg.h>
#include <stdio.h>

int
add_em_up (int count,...)
{
  va_list ap;
  int i, sum;

  va_start (ap, count);         /* Initialize the argument list. */

  sum = 0;
  for (i = 0; i < count; i++)
    sum += va_arg (ap, int);    /* Get the next argument value. */

  va_end (ap);                  /* Clean up. */
  return sum;
}

int
main (void)
{
  /* This call prints 16. */
  printf ("%d\n", add_em_up (3, 5, 5, 6));

  /* This call prints 55. */
  printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));

  return 0;
}
Old-Style Variadic Functions

Before ISO C, programmers used a slightly different facility for writing variadic functions. The GNU C compiler still supports it; currently, it is more portable than the ISO C facility, since support for ISO C is still not universal. The header file which defines the old-fashioned variadic facility is called `varargs.h'.

Using `varargs.h' is almost the same as using `stdarg.h'. There is no difference in how you call a variadic function; see section Calling Variadic Functions. The only difference is in how you define them. First of all, you must use old-style non-prototype syntax, like this:
tree
build (va_alist)
     va_dcl
{
Secondly, you must give va_start only one argument, like this:
  va_list p;
  va_start (p);
These are the special macros used for defining old-style variadic functions:

Macro: va_alist
This macro stands for the argument name list required in a variadic function.

Macro: va_dcl
This macro declares the implicit argument or arguments for a variadic function.

Macro: void va_start (va_list ap)
This macro, as defined in `varargs.h', initializes the argument pointer variable ap to point to the first argument of the current function.

The other argument macros, va_arg and va_end, are the same in `varargs.h' as in `stdarg.h'; see section Argument Access Macros, for details.

It does not work to include both `varargs.h' and `stdarg.h' in the same compilation; they define va_start in conflicting ways.

Null Pointer Constant

The null pointer constant is guaranteed not to point to any real object. You can assign it to any pointer variable since it has type void *. The preferred way to write a null pointer constant is with NULL.

Macro: void * NULL
This is a null pointer constant.

You can also use 0 or (void *)0 as a null pointer constant, but using NULL is cleaner because it makes the purpose of the constant more evident.

If you use the null pointer constant as a function argument, then for complete portability you should make sure that the function has a prototype declaration. Otherwise, if the target machine has two different pointer representations, the compiler won't know which representation to use for that argument. You can avoid the problem by explicitly casting the constant to the proper pointer type, but we recommend instead adding a prototype for the function you are calling.

Important Data Types

The result of subtracting two pointers in C is always an integer, but the precise data type varies from C compiler to C compiler. Likewise, the data type of the result of sizeof also varies between compilers. ISO defines standard aliases for these two types, so you can refer to them in a portable fashion. They are defined in the header file `stddef.h'.

Data Type: ptrdiff_t
This is the signed integer type of the result of subtracting two pointers. For example, with the declaration char *p1, *p2;, the expression p2 - p1 is of type ptrdiff_t. This will probably be one of the standard signed integer types (short int, int or long int), but might be a nonstandard type that exists only for this purpose.

Data Type: size_t
This is an unsigned integer type used to represent the sizes of objects. The result of the sizeof operator is of this type, and functions such as malloc (see section Unconstrained Allocation) and memcpy (see section Copying and Concatenation) accept arguments of this type to specify object sizes.

Usage Note: size_t is the preferred way to declare any arguments or variables that hold the size of an object.

In the GNU system size_t is equivalent to either unsigned int or unsigned long int. These types have identical properties on the GNU system and, for most purposes, you can use them interchangeably. However, they are distinct as data types, which makes a difference in certain contexts.

For example, when you specify the type of a function argument in a function prototype, it makes a difference which one you use. If the system header files declare malloc with an argument of type size_t and you declare malloc with an argument of type unsigned int, you will get a compilation error if size_t happens to be unsigned long int on your system. To avoid any possibility of error, when a function argument or value is supposed to have type size_t, never declare its type in any other way.

Compatibility Note: Implementations of C before the advent of ISO C generally used unsigned int for representing object sizes and int for pointer subtraction results. They did not necessarily define either size_t or ptrdiff_t. Unix systems did define size_t, in `sys/types.h', but the definition was usually a signed type.

Data Type Measurements

Most of the time, if you choose the proper C data type for each object in your program, you need not be concerned with just how it is represented or how many bits it uses. When you do need such information, the C language itself does not provide a way to get it. The header files `limits.h' and `float.h' contain macros which give you this information in full detail.

Computing the Width of an Integer Data Type

The most common reason that a program needs to know how many bits are in an integer type is for using an array of long int as a bit vector. You can access the bit at index n with
vector[n / LONGBITS] & (1 << (n % LONGBITS))
provided you define LONGBITS as the number of bits in a long int.

There is no operator in the C language that can give you the number of bits in an integer data type. But you can compute it from the macro CHAR_BIT, defined in the header file `limits.h'.

CHAR_BIT
This is the number of bits in a char---eight, on most systems. The value has type int. You can compute the number of bits in any data type type like this:
sizeof (type) * CHAR_BIT
Range of an Integer Type

Suppose you need to store an integer value which can range from zero to one million. Which is the smallest type you can use? There is no general rule; it depends on the C compiler and target machine. You can use the `MIN' and `MAX' macros in `limits.h' to determine which type will work.

Each signed integer type has a pair of macros which give the smallest and largest values that it can hold. Each unsigned integer type has one such macro, for the maximum value; the minimum value is, of course, zero.

The values of these macros are all integer constant expressions. The `MAX' and `MIN' macros for char and short int types have values of type int. The `MAX' and `MIN' macros for the other types have values of the same type described by the macro--thus, ULONG_MAX has type unsigned long int.

SCHAR_MIN
This is the minimum value that can be represented by a signed char.
SCHAR_MAX

UCHAR_MAX
These are the maximum values that can be represented by a signed char and unsigned char, respectively.
CHAR_MIN
This is the minimum value that can be represented by a char. It's equal to SCHAR_MIN if char is signed, or zero otherwise.
CHAR_MAX
This is the maximum value that can be represented by a char. It's equal to SCHAR_MAX if char is signed, or UCHAR_MAX otherwise.
SHRT_MIN
This is the minimum value that can be represented by a signed short int. On most machines that the GNU C library runs on, short integers are 16-bit quantities.
SHRT_MAX

USHRT_MAX
These are the maximum values that can be represented by a signed short int and unsigned short int, respectively.
INT_MIN
This is the minimum value that can be represented by a signed int. On most machines that the GNU C system runs on, an int is a 32-bit quantity.
INT_MAX

UINT_MAX
These are the maximum values that can be represented by, respectively, the type signed int and the type unsigned int.
LONG_MIN
This is the minimum value that can be represented by a signed long int. On most machines that the GNU C system runs on, long integers are 32-bit quantities, the same size as int.
LONG_MAX

ULONG_MAX
These are the maximum values that can be represented by a signed long int and unsigned long int, respectively.
LONG_LONG_MIN
This is the minimum value that can be represented by a signed long long int. On most machines that the GNU C system runs on, long long integers are 64-bit quantities.
LONG_LONG_MAX

ULONG_LONG_MAX
These are the maximum values that can be represented by a signed long long int and unsigned long long int, respectively.
WCHAR_MAX
This is the maximum value that can be represented by a wchar_t. See section Introduction to Extended Characters.
The header file `limits.h' also defines some additional constants that parameterize various operating system and file system limits. These constants are described in section System Configuration Parameters.

Floating Type Macros

The specific representation of floating point numbers varies from machine to machine. Because floating point numbers are represented internally as approximate quantities, algorithms for manipulating floating point data often need to take account of the precise details of the machine's floating point representation.

Some of the functions in the C library itself need this information; for example, the algorithms for printing and reading floating point numbers (see section Input/Output on Streams) and for calculating trigonometric and irrational functions (see section Mathematics) use it to avoid round-off error and loss of accuracy. User programs that implement numerical analysis techniques also often need this information in order to minimize or compute error bounds.

The header file `float.h' describes the format used by your machine.

Floating Point Representation Concepts

This section introduces the terminology for describing floating point representations.

You are probably already familiar with most of these concepts in terms of scientific or exponential notation for floating point numbers. For example, the number 123456.0 could be expressed in exponential notation as 1.23456e+05, a shorthand notation indicating that the mantissa 1.23456 is multiplied by the base 10 raised to power 5.

More formally, the internal representation of a floating point number can be characterized in terms of the following parameters:

The sign is either -1 or 1.
The base or radix for exponentiation, an integer greater than 1. This is a constant for a particular representation.
The exponent to which the base is raised. The upper and lower bounds of the exponent value are constants for a particular representation. Sometimes, in the actual bits representing the floating point number, the exponent is biased by adding a constant to it, to make it always be represented as an unsigned quantity. This is only important if you have some reason to pick apart the bit fields making up the floating point number by hand, which is something for which the GNU library provides no support. So this is ignored in the discussion that follows.
The mantissa or significand is an unsigned integer which is a part of each floating point number.
The precision of the mantissa. If the base of the representation is b, then the precision is the number of base-b digits in the mantissa. This is a constant for a particular representation. Many floating point representations have an implicit hidden bit in the mantissa. This is a bit which is present virtually in the mantissa, but not stored in memory because its value is always 1 in a normalized number. The precision figure (see above) includes any hidden bits. Again, the GNU library provides no facilities for dealing with such low-level aspects of the representation.

The mantissa of a floating point number represents an implicit fraction whose denominator is the base raised to the power of the precision. Since the largest representable mantissa is one less than this denominator, the value of the fraction is always strictly less than 1. The mathematical value of a floating point number is then the product of this fraction, the sign, and the base raised to the exponent.

We say that the floating point number is normalized if the fraction is at least 1/b, where b is the base. In other words, the mantissa would be too large to fit if it were multiplied by the base. Non-normalized numbers are sometimes called denormal; they contain less precision than the representation normally can hold.

If the number is not normalized, then you can subtract 1 from the exponent while multiplying the mantissa by the base, and get another floating point number with the same value. Normalization consists of doing this repeatedly until the number is normalized. Two distinct normalized floating point numbers cannot be equal in value.

(There is an exception to this rule: if the mantissa is zero, it is considered normalized. Another exception happens on certain machines where the exponent is as small as the representation can hold. Then it is impossible to subtract 1 from the exponent, so a number may be normalized even if its fraction is less than 1/b.)

Floating Point Parameters

These macro definitions can be accessed by including the header file `float.h' in your program.

Macro names starting with `FLT_' refer to the float type, while names beginning with `DBL_' refer to the double type and names beginning with `LDBL_' refer to the long double type. (If GCC does not support long double as a distinct data type on a target machine then the values for the `LDBL_' constants are equal to the corresponding constants for the double type.)

Of these macros, only FLT_RADIX is guaranteed to be a constant expression. The other macros listed here cannot be reliably used in places that require constant expressions, such as `#if' preprocessing directives or in the dimensions of static arrays.

Although the ISO C standard specifies minimum and maximum values for most of these parameters, the GNU C implementation uses whatever values describe the floating point representation of the target machine. So in principle GNU C actually satisfies the ISO C requirements only if the target machine is suitable. In practice, all the machines currently supported are suitable.

FLT_ROUNDS
This value characterizes the rounding mode for floating point addition. The following values indicate standard rounding modes:
-1
The mode is indeterminable.
0
Rounding is towards zero.
1
Rounding is to the nearest number.
2
Rounding is towards positive infinity.
3
Rounding is towards negative infinity. Any other value represents a machine-dependent nonstandard rounding mode. On most machines, the value is 1, in accordance with the IEEE standard for floating point. Here is a table showing how certain values round for each possible value of FLT_ROUNDS, if the other aspects of the representation match the IEEE single-precision standard.
                0      1             2             3
 1.00000003    1.0    1.0           1.00000012    1.0
 1.00000007    1.0    1.00000012    1.00000012    1.0
-1.00000003   -1.0   -1.0          -1.0          -1.00000012
-1.00000007   -1.0   -1.00000012   -1.0          -1.00000012
FLT_RADIX
This is the value of the base, or radix, of the exponent representation. This is guaranteed to be a constant expression, unlike the other macros described in this section. The value is 2 on all machines we know of except the IBM 360 and derivatives.
FLT_MANT_DIG
This is the number of base-FLT_RADIX digits in the floating point mantissa for the float data type. The following expression yields 1.0 (even though mathematically it should not) due to the limited number of mantissa digits:
float radix = FLT_RADIX;

1.0f + 1.0f / radix / radix / ... / radix
where radix appears FLT_MANT_DIG times.
DBL_MANT_DIG

LDBL_MANT_DIG
This is the number of base-FLT_RADIX digits in the floating point mantissa for the data types double and long double, respectively.
FLT_DIG
This is the number of decimal digits of precision for the float data type. Technically, if p and b are the precision and base (respectively) for the representation, then the decimal precision q is the maximum number of decimal digits such that any floating point number with q base 10 digits can be rounded to a floating point number with p base b digits and back again, without change to the q decimal digits. The value of this macro is supposed to be at least 6, to satisfy ISO C.
DBL_DIG

LDBL_DIG
These are similar to FLT_DIG, but for the data types double and long double, respectively. The values of these macros are supposed to be at least 10.
FLT_MIN_EXP
This is the smallest possible exponent value for type float. More precisely, is the minimum negative integer such that the value FLT_RADIX raised to this power minus 1 can be represented as a normalized floating point number of type float.
DBL_MIN_EXP

LDBL_MIN_EXP
These are similar to FLT_MIN_EXP, but for the data types double and long double, respectively.
FLT_MIN_10_EXP
This is the minimum negative integer such that 10 raised to this power minus 1 can be represented as a normalized floating point number of type float. This is supposed to be -37 or even less.
DBL_MIN_10_EXP

LDBL_MIN_10_EXP
These are similar to FLT_MIN_10_EXP, but for the data types double and long double, respectively.
FLT_MAX_EXP
This is the largest possible exponent value for type float. More precisely, this is the maximum positive integer such that value FLT_RADIX raised to this power minus 1 can be represented as a floating point number of type float.
DBL_MAX_EXP

LDBL_MAX_EXP
These are similar to FLT_MAX_EXP, but for the data types double and long double, respectively.
FLT_MAX_10_EXP
This is the maximum positive integer such that 10 raised to this power minus 1 can be represented as a normalized floating point number of type float. This is supposed to be at least 37.
DBL_MAX_10_EXP

LDBL_MAX_10_EXP
These are similar to FLT_MAX_10_EXP, but for the data types double and long double, respectively.
FLT_MAX
The value of this macro is the maximum number representable in type float. It is supposed to be at least 1E+37. The value has type float. The smallest representable number is - FLT_MAX.
DBL_MAX

LDBL_MAX
These are similar to FLT_MAX, but for the data types double and long double, respectively. The type of the macro's value is the same as the type it describes.
FLT_MIN
The value of this macro is the minimum normalized positive floating point number that is representable in type float. It is supposed to be no more than 1E-37.
DBL_MIN

LDBL_MIN
These are similar to FLT_MIN, but for the data types double and long double, respectively. The type of the macro's value is the same as the type it describes.
FLT_EPSILON
This is the maximum positive floating point number of type float such that 1.0 + FLT_EPSILON != 1.0 is true. It's supposed to be no greater than 1E-5.
DBL_EPSILON

LDBL_EPSILON
These are similar to FLT_EPSILON, but for the data types double and long double, respectively. The type of the macro's value is the same as the type it describes. The values are not supposed to be greater than 1E-9.
IEEE Floating Point

Here is an example showing how the floating type measurements come out for the most common floating point representation, specified by the IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std 754-1985). Nearly all computers designed since the 1980s use this format.

The IEEE single-precision float representation uses a base of 2. There is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total precision is 24 base-2 digits), and an 8-bit exponent that can represent values in the range -125 to 128, inclusive.

So, for an implementation that uses this representation for the float data type, appropriate values for the corresponding parameters are:
FLT_RADIX                             2
FLT_MANT_DIG                         24
FLT_DIG                               6
FLT_MIN_EXP                        -125
FLT_MIN_10_EXP                      -37
FLT_MAX_EXP                         128
FLT_MAX_10_EXP                      +38
FLT_MIN                 1.17549435E-38F
FLT_MAX                 3.40282347E+38F
FLT_EPSILON             1.19209290E-07F
Here are the values for the double data type:
DBL_MANT_DIG                         53
DBL_DIG                              15
DBL_MIN_EXP                       -1021
DBL_MIN_10_EXP                     -307
DBL_MAX_EXP                        1024
DBL_MAX_10_EXP                      308
DBL_MAX         1.7976931348623157E+308
DBL_MIN         2.2250738585072014E-308
DBL_EPSILON     2.2204460492503131E-016
Structure Field Offset Measurement

You can use offsetof to measure the location within a structure type of a particular structure member.

Macro: size_t offsetof (type, member)
This expands to a integer constant expression that is the offset of the structure member named member in a the structure type type. For example, offsetof (struct s, elem) is the offset, in bytes, of the member elem in a struct s.

This macro won't work if member is a bit field; you get an error from the C compiler in that case.
Summary of Library Facilities

This appendix is a complete list of the facilities declared within the header files supplied with the GNU C library. Each entry also lists the standard or other source from which each facility is derived, and tells you where in the manual you can find more information about how to use it.

@smallfonts @rm
long int a64l (const char *string)
`stdlib.h' (XPG): section Encode Binary Data.
void abort (void)
`stdlib.h' (ISO): section Aborting a Program.
int abs (int number)
`stdlib.h' (ISO): section Absolute Value.
int accept (int socket, struct sockaddr *addr, socklen_t *length_ptr)
`sys/socket.h' (BSD): section Accepting Connections.
int access (const char *filename, int how)
`unistd.h' (POSIX.1): section Testing Permission to Access a File.
ACCOUNTING
`utmp.h' (SVID): section Manipulating the User Accounting Database.
double acos (double x)
`math.h' (ISO): section Inverse Trigonometric Functions.
float acosf (float x)
`math.h' (ISO): section Inverse Trigonometric Functions.
double acosh (double x)
`math.h' (ISO): section Hyperbolic Functions.
float acoshf (float x)
`math.h' (ISO): section Hyperbolic Functions.
long double acoshl (long double x)
`math.h' (ISO): section Hyperbolic Functions.
long double acosl (long double x)
`math.h' (ISO): section Inverse Trigonometric Functions.
int addmntent (FILE *stream, const struct mntent *mnt)
`mntent.h' (BSD): section The `mtab' file.
int adjtime (const struct timeval *delta, struct timeval *olddelta)
`sys/time.h' (BSD): section High-Resolution Calendar.
int adjtimex (struct timex *timex)
`sys/timex.h' (GNU): section High-Resolution Calendar.
AF_FILE
`sys/socket.h' (GNU): section Address Formats.
AF_INET
`sys/socket.h' (BSD): section Address Formats.
AF_INET6
`sys/socket.h' (IPv6 Basic API): section Address Formats.
AF_LOCAL
`sys/socket.h' (POSIX): section Address Formats.
AF_UNIX
`sys/socket.h' (BSD, Unix98): section Address Formats.
AF_UNSPEC
`sys/socket.h' (BSD): section Address Formats.
int aio_cancel (int fildes, struct aiocb *aiocbp)
`aio.h' (POSIX.1b): section Cancellation of AIO Operations.
int aio_cancel64 (int fildes, struct aiocb *aiocbp)
`aio.h' (Unix98): section Cancellation of AIO Operations.
int aio_error (const struct aiocb *aiocbp)
`aio.h' (POSIX.1b): section Getting the Status of AIO Operations.
int aio_error64 (const struct aiocb64 *aiocbp)
`aio.h' (Unix98): section Getting the Status of AIO Operations.
int aio_fsync (int op, struct aiocb *aiocbp)
`aio.h' (POSIX.1b): section Getting into a Consistent State.
int aio_fsync64 (int op, struct aiocb64 *aiocbp)
`aio.h' (Unix98): section Getting into a Consistent State.
void aio_init (const struct aioinit *init)
`aio.h' (GNU): section How to optimize the AIO implementation.
int aio_read (struct aiocb *aiocbp)
`aio.h' (POSIX.1b): section Asynchronous Read and Write Operations.
int aio_read64 (struct aiocb *aiocbp)
`aio.h' (Unix98): section Asynchronous Read and Write Operations.
ssize_t aio_return (const struct aiocb *aiocbp)
`aio.h' (POSIX.1b): section Getting the Status of AIO Operations.
int aio_return64 (const struct aiocb64 *aiocbp)
`aio.h' (Unix98): section Getting the Status of AIO Operations.
int aio_suspend (const struct aiocb *const list[], int nent, const struct timespec *timeout)
`aio.h' (POSIX.1b): section Getting into a Consistent State.
int aio_suspend64 (const struct aiocb64 *const list[], int nent, const struct timespec *timeout)
`aio.h' (Unix98): section Getting into a Consistent State.
int aio_write (struct aiocb *aiocbp)
`aio.h' (POSIX.1b): section Asynchronous Read and Write Operations.
int aio_write64 (struct aiocb *aiocbp)
`aio.h' (Unix98): section Asynchronous Read and Write Operations.
unsigned int alarm (unsigned int seconds)
`unistd.h' (POSIX.1): section Setting an Alarm.
void * alloca (size_t size);
`stdlib.h' (GNU, BSD): section Automatic Storage with Variable Size.
int alphasort (const void *a, const void *b)
`dirent.h' (BSD/SVID): section Scanning the Content of a Directory.
int alphasort64 (const void *a, const void *b)
`dirent.h' (GNU): section Scanning the Content of a Directory.
tcflag_t ALTWERASE
`termios.h' (BSD): section Local Modes.
int ARG_MAX
`limits.h' (POSIX.1): section General Capacity Limits.
error_t argp_err_exit_status
`argp.h' (GNU): section Argp Global Variables.
void argp_error (const struct argp_state *state, const char *fmt, ...)
`argp.h' (GNU): section Functions For Use in Argp Parsers.
int ARGP_ERR_UNKNOWN
`argp.h' (GNU): section Argp Parser Functions.
void argp_failure (const struct argp_state *state, int status, int errnum, const char *fmt, ...)
`argp.h' (GNU): section Functions For Use in Argp Parsers.
void argp_help (const struct argp *argp, FILE *stream, unsigned flags, char *name)
`argp.h' (GNU): section The argp_help Function.
ARGP_IN_ORDER
`argp.h' (GNU): section Flags for argp_parse.
ARGP_KEY_ARG
`argp.h' (GNU): section Special Keys for Argp Parser Functions.
ARGP_KEY_ARGS
`argp.h' (GNU): section Special Keys for Argp Parser Functions.
ARGP_KEY_END
`argp.h' (GNU): section Special Keys for Argp Parser Functions.
ARGP_KEY_ERROR
`argp.h' (GNU): section Special Keys for Argp Parser Functions.
ARGP_KEY_FINI
`argp.h' (GNU): section Special Keys for Argp Parser Functions.
ARGP_KEY_HELP_ARGS_DOC
`argp.h' (GNU): section Special Keys for Argp Help Filter Functions.
ARGP_KEY_HELP_DUP_ARGS_NOTE
`argp.h' (GNU): section Special Keys for Argp Help Filter Functions.
ARGP_KEY_HELP_EXTRA
`argp.h' (GNU): section Special Keys for Argp Help Filter Functions.
ARGP_KEY_HELP_HEADER
`argp.h' (GNU): section Special Keys for Argp Help Filter Functions.
ARGP_KEY_HELP_POST_DOC
`argp.h' (GNU): section Special Keys for Argp Help Filter Functions.
ARGP_KEY_HELP_PRE_DOC
`argp.h' (GNU): section Special Keys for Argp Help Filter Functions.
ARGP_KEY_INIT
`argp.h' (GNU): section Special Keys for Argp Parser Functions.
ARGP_KEY_NO_ARGS
`argp.h' (GNU): section Special Keys for Argp Parser Functions.
ARGP_KEY_SUCCESS
`argp.h' (GNU): section Special Keys for Argp Parser Functions.
ARGP_LONG_ONLY
`argp.h' (GNU): section Flags for argp_parse.
ARGP_NO_ARGS
`argp.h' (GNU): section Flags for argp_parse.
ARGP_NO_ERRS
`argp.h' (GNU): section Flags for argp_parse.
ARGP_NO_EXIT
`argp.h' (GNU): section Flags for argp_parse.
ARGP_NO_HELP
`argp.h' (GNU): section Flags for argp_parse.
error_t argp_parse (const struct argp *argp, int argc, char **argv, unsigned flags, int *arg_index, void *input)
`argp.h' (GNU): section Parsing Program Options with Argp.
ARGP_PARSE_ARGV0
`argp.h' (GNU): section Flags for argp_parse.
const char * argp_program_bug_address
`argp.h' (GNU): section Argp Global Variables.
const char * argp_program_version
`argp.h' (GNU): section Argp Global Variables.
argp_program_version_hook
`argp.h' (GNU): section Argp Global Variables.
ARGP_SILENT
`argp.h' (GNU): section Flags for argp_parse.
void argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)
`argp.h' (GNU): section Functions For Use in Argp Parsers.
void argp_usage (const struct argp_state *state)
`argp.h' (GNU): section Functions For Use in Argp Parsers.
error_t argz_add (char **argz, size_t *argz_len, const char *str)
`argz.h' (GNU): section Argz Functions.
error_t argz_add_sep (char **argz, size_t *argz_len, const char *str, int delim)
`argz.h' (GNU): section Argz Functions.
error_t argz_append (char **argz, size_t *argz_len, const char *buf, size_t buf_len)
`argz.h' (GNU): section Argz Functions.
size_t argz_count (const char *argz, size_t arg_len)
`argz.h' (GNU): section Argz Functions.
error_t argz_create (char *const argv[], char **argz, size_t *argz_len)
`argz.h' (GNU): section Argz Functions.
error_t argz_create_sep (const char *string, int sep, char **argz, size_t *argz_len)
`argz.h' (GNU): section Argz Functions.
error_t argz_delete (char **argz, size_t *argz_len, char *entry)
`argz.h' (GNU): section Argz Functions.
void argz_extract (char *argz, size_t argz_len, char **argv)
`argz.h' (GNU): section Argz Functions.
error_t argz_insert (char **argz, size_t *argz_len, char *before, const char *entry)
`argz.h' (GNU): section Argz Functions.
char * argz_next (char *argz, size_t argz_len, const char *entry)
`argz.h' (GNU): section Argz Functions.
error_t argz_replace (char **argz, size_t *argz_len, const char *str, const char *with, unsigned *replace_count)
`argz.h' (GNU): section Argz Functions.
void argz_stringify (char *argz, size_t len, int sep)
`argz.h' (GNU): section Argz Functions.
char * asctime (const struct tm *brokentime)
`time.h' (ISO): section Formatting Calendar Time.
char * asctime_r (const struct tm *brokentime, char *buffer)
`time.h' (POSIX.1c): section Formatting Calendar Time.
double asin (double x)
`math.h' (ISO): section Inverse Trigonometric Functions.
float asinf (float x)
`math.h' (ISO): section Inverse Trigonometric Functions.
double asinh (double x)
`math.h' (ISO): section Hyperbolic Functions.
float asinhf (float x)
`math.h' (ISO): section Hyperbolic Functions.
long double asinhl (long double x)
`math.h' (ISO): section Hyperbolic Functions.
long double asinl (long double x)
`math.h' (ISO): section Inverse Trigonometric Functions.
int asprintf (char **ptr, const char *template, ...)
`stdio.h' (GNU): section Dynamically Allocating Formatted Output.
void assert (int expression)
`assert.h' (ISO): section Explicitly Checking Internal Consistency.
void assert_perror (int errnum)
`assert.h' (GNU): section Explicitly Checking Internal Consistency.
double atan (double x)
`math.h' (ISO): section Inverse Trigonometric Functions.
double atan2 (double y, double x)
`math.h' (ISO): section Inverse Trigonometric Functions.
float atan2f (float y, float x)
`math.h' (ISO): section Inverse Trigonometric Functions.
long double atan2l (long double y, long double x)
`math.h' (ISO): section Inverse Trigonometric Functions.
float atanf (float x)
`math.h' (ISO): section Inverse Trigonometric Functions.
double atanh (double x)
`math.h' (ISO): section Hyperbolic Functions.
float atanhf (float x)
`math.h' (ISO): section Hyperbolic Functions.
long double atanhl (long double x)
`math.h' (ISO): section Hyperbolic Functions.
long double atanl (long double x)
`math.h' (ISO): section Inverse Trigonometric Functions.
int atexit (void (*function) (void))
`stdlib.h' (ISO): section Cleanups on Exit.
double atof (const char *string)
`stdlib.h' (ISO): section Parsing of Floats.
int atoi (const char *string)
`stdlib.h' (ISO): section Parsing of Integers.
long int atol (const char *string)
`stdlib.h' (ISO): section Parsing of Integers.
long long int atoll (const char *string)
`stdlib.h' (ISO): section Parsing of Integers.
B0
`termios.h' (POSIX.1): section Line Speed.
B110
`termios.h' (POSIX.1): section Line Speed.
B115200
`termios.h' (GNU): section Line Speed.
B1200
`termios.h' (POSIX.1): section Line Speed.
B134
`termios.h' (POSIX.1): section Line Speed.
B150
`termios.h' (POSIX.1): section Line Speed.
B1800
`termios.h' (POSIX.1): section Line Speed.
B19200
`termios.h' (POSIX.1): section Line Speed.
B200
`termios.h' (POSIX.1): section Line Speed.
B230400
`termios.h' (GNU): section Line Speed.
B2400
`termios.h' (POSIX.1): section Line Speed.
B300
`termios.h' (POSIX.1): section Line Speed.
B38400
`termios.h' (POSIX.1): section Line Speed.
B460800
`termios.h' (GNU): section Line Speed.
B4800
`termios.h' (POSIX.1): section Line Speed.
B50
`termios.h' (POSIX.1): section Line Speed.
B57600
`termios.h' (GNU): section Line Speed.
B600
`termios.h' (POSIX.1): section Line Speed.
B75
`termios.h' (POSIX.1): section Line Speed.
B9600
`termios.h' (POSIX.1): section Line Speed.
int backtrace (void **buffer, int size)
`execinfo.h' (GNU): section Backtraces.
char ** backtrace_symbols (void *const *buffer, int size)
`execinfo.h' (GNU): section Backtraces.
void backtrace_symbols_fd (void *const *buffer, int size, int fd)
`execinfo.h' (GNU): section Backtraces.
char * basename (char *path)
`libgen.h' (XPG): section Finding Tokens in a String.
char * basename (const char *filename)
`string.h' (GNU): section Finding Tokens in a String.
int BC_BASE_MAX
`limits.h' (POSIX.2): section Utility Program Capacity Limits.
int BC_DIM_MAX
`limits.h' (POSIX.2): section Utility Program Capacity Limits.
int bcmp (const void *a1, const void *a2, size_t size)
`string.h' (BSD): section String/Array Comparison.
void bcopy (const void *from, void *to, size_t size)
`string.h' (BSD): section Copying and Concatenation.
int BC_SCALE_MAX
`limits.h' (POSIX.2): section Utility Program Capacity Limits.
int BC_STRING_MAX
`limits.h' (POSIX.2): section Utility Program Capacity Limits.
int bind (int socket, struct sockaddr *addr, socklen_t length)
`sys/socket.h' (BSD): section Setting the Address of a Socket.
char * bindtextdomain (const char *domainname, const char *dirname)
`libintl.h' (GNU): section How to determine which catalog to be used.
char * bind_textdomain_codeset (const char *domainname, const char *codeset)
`libintl.h' (GNU): section How to specify the output character set gettext uses.
blkcnt64_t
`sys/types.h' (Unix98): section The meaning of the File Attributes.
blkcnt_t
`sys/types.h' (Unix98): section The meaning of the File Attributes.
BOOT_TIME
`utmp.h' (SVID): section Manipulating the User Accounting Database.
BOOT_TIME
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
int brk (void *addr)
`unistd.h' (BSD): section Resizing the Data Segment.
tcflag_t BRKINT
`termios.h' (POSIX.1): section Input Modes.
_BSD_SOURCE
(GNU): section Feature Test Macros.
void * bsearch (const void *key, const void *array, size_t count, size_t size, comparison_fn_t compare)
`stdlib.h' (ISO): section Array Search Function.
wint_t btowc (int c)
`wchar.h' (ISO): section Converting Single Characters.
int BUFSIZ
`stdio.h' (ISO): section Controlling Which Kind of Buffering.
void bzero (void *block, size_t size)
`string.h' (BSD): section Copying and Concatenation.
double cabs (complex double z)
`complex.h' (ISO): section Absolute Value.
float cabsf (complex float z)
`complex.h' (ISO): section Absolute Value.
long double cabsl (complex long double z)
`complex.h' (ISO): section Absolute Value.
complex double cacos (complex double z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
complex float cacosf (complex float z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
complex double cacosh (complex double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex float cacoshf (complex float z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double cacoshl (complex long double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double cacosl (complex long double z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
void * calloc (size_t count, size_t eltsize)
`malloc.h', `stdlib.h' (ISO): section Allocating Cleared Space.
char * canonicalize_file_name (const char *name)
`stdlib.h' (GNU): section Symbolic Links.
double carg (complex double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
float cargf (complex float z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
long double cargl (complex long double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
complex double casin (complex double z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
complex float casinf (complex float z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
complex double casinh (complex double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex float casinhf (complex float z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double casinhl (complex long double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double casinl (complex long double z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
complex double catan (complex double z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
complex float catanf (complex float z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
complex double catanh (complex double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex float catanhf (complex float z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double catanhl (complex long double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double catanl (complex long double z)
`complex.h' (ISO): section Inverse Trigonometric Functions.
nl_catd catopen (const char *cat_name, int flag)
`nl_types.h' (X/Open): section The catgets function family.
int cbc_crypt (char *key, char *blocks, unsigned len, unsigned mode, char *ivec)
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
double cbrt (double x)
`math.h' (BSD): section Exponentiation and Logarithms.
float cbrtf (float x)
`math.h' (BSD): section Exponentiation and Logarithms.
long double cbrtl (long double x)
`math.h' (BSD): section Exponentiation and Logarithms.
complex double ccos (complex double z)
`complex.h' (ISO): section Trigonometric Functions.
complex float ccosf (complex float z)
`complex.h' (ISO): section Trigonometric Functions.
complex double ccosh (complex double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex float ccoshf (complex float z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double ccoshl (complex long double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double ccosl (complex long double z)
`complex.h' (ISO): section Trigonometric Functions.
cc_t
`termios.h' (POSIX.1): section Terminal Mode Data Types.
tcflag_t CCTS_OFLOW
`termios.h' (BSD): section Control Modes.
double ceil (double x)
`math.h' (ISO): section Rounding Functions.
float ceilf (float x)
`math.h' (ISO): section Rounding Functions.
long double ceill (long double x)
`math.h' (ISO): section Rounding Functions.
complex double cexp (complex double z)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex float cexpf (complex float z)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex long double cexpl (complex long double z)
`complex.h' (ISO): section Exponentiation and Logarithms.
speed_t cfgetispeed (const struct termios *termios-p)
`termios.h' (POSIX.1): section Line Speed.
speed_t cfgetospeed (const struct termios *termios-p)
`termios.h' (POSIX.1): section Line Speed.
int cfmakeraw (struct termios *termios-p)
`termios.h' (BSD): section Noncanonical Input.
void cfree (void *ptr)
`stdlib.h' (Sun): section Freeing Memory Allocated with malloc.
int cfsetispeed (struct termios *termios-p, speed_t speed)
`termios.h' (POSIX.1): section Line Speed.
int cfsetospeed (struct termios *termios-p, speed_t speed)
`termios.h' (POSIX.1): section Line Speed.
int cfsetspeed (struct termios *termios-p, speed_t speed)
`termios.h' (BSD): section Line Speed.
CHAR_BIT
`limits.h' (ISO): section Computing the Width of an Integer Data Type.
CHAR_MAX
`limits.h' (ISO): section Range of an Integer Type.
CHAR_MIN
`limits.h' (ISO): section Range of an Integer Type.
int chdir (const char *filename)
`unistd.h' (POSIX.1): section Working Directory.
int CHILD_MAX
`limits.h' (POSIX.1): section General Capacity Limits.
int chmod (const char *filename, mode_t mode)
`sys/stat.h' (POSIX.1): section Assigning File Permissions.
int chown (const char *filename, uid_t owner, gid_t group)
`unistd.h' (POSIX.1): section File Owner.
tcflag_t CIGNORE
`termios.h' (BSD): section Control Modes.
double cimag (complex double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
float cimagf (complex float z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
long double cimagl (complex long double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
int clearenv (void)
`stdlib.h' (GNU): section Environment Access.
void clearerr (FILE *stream)
`stdio.h' (ISO): section Recovering from errors.
void clearerr_unlocked (FILE *stream)
`stdio.h' (GNU): section Recovering from errors.
int CLK_TCK
`time.h' (POSIX.1): section CPU Time Inquiry.
tcflag_t CLOCAL
`termios.h' (POSIX.1): section Control Modes.
clock_t clock (void)
`time.h' (ISO): section CPU Time Inquiry.
int CLOCKS_PER_SEC
`time.h' (ISO): section CPU Time Inquiry.
clock_t
`time.h' (ISO): section CPU Time Inquiry.
complex double clog (complex double z)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex double clog10 (complex double z)
`complex.h' (GNU): section Exponentiation and Logarithms.
complex float clog10f (complex float z)
`complex.h' (GNU): section Exponentiation and Logarithms.
complex long double clog10l (complex long double z)
`complex.h' (GNU): section Exponentiation and Logarithms.
complex float clogf (complex float z)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex long double clogl (complex long double z)
`complex.h' (ISO): section Exponentiation and Logarithms.
int close (int filedes)
`unistd.h' (POSIX.1): section Opening and Closing Files.
int closedir (DIR *dirstream)
`dirent.h' (POSIX.1): section Reading and Closing a Directory Stream.
void closelog (void)
`syslog.h' (BSD): section closelog.
int COLL_WEIGHTS_MAX
`limits.h' (POSIX.2): section Utility Program Capacity Limits.
size_t confstr (int parameter, char *buf, size_t len)
`unistd.h' (POSIX.2): section String-Valued Parameters.
complex double conj (complex double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
complex float conjf (complex float z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
complex long double conjl (complex long double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
int connect (int socket, struct sockaddr *addr, socklen_t length)
`sys/socket.h' (BSD): section Making a Connection.
cookie_close_function
`stdio.h' (GNU): section Custom Stream Hook Functions.
cookie_io_functions_t
`stdio.h' (GNU): section Custom Streams and Cookies.
cookie_read_function
`stdio.h' (GNU): section Custom Stream Hook Functions.
cookie_seek_function
`stdio.h' (GNU): section Custom Stream Hook Functions.
cookie_write_function
`stdio.h' (GNU): section Custom Stream Hook Functions.
double copysign (double x, double y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
float copysignf (float x, float y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
long double copysignl (long double x, long double y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
double cos (double x)
`math.h' (ISO): section Trigonometric Functions.
float cosf (float x)
`math.h' (ISO): section Trigonometric Functions.
double cosh (double x)
`math.h' (ISO): section Hyperbolic Functions.
float coshf (float x)
`math.h' (ISO): section Hyperbolic Functions.
long double coshl (long double x)
`math.h' (ISO): section Hyperbolic Functions.
long double cosl (long double x)
`math.h' (ISO): section Trigonometric Functions.
complex double cpow (complex double base, complex double power)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex float cpowf (complex float base, complex float power)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex long double cpowl (complex long double base, complex long double power)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex double cproj (complex double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
complex float cprojf (complex float z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
complex long double cprojl (complex long double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
tcflag_t CREAD
`termios.h' (POSIX.1): section Control Modes.
double creal (complex double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
float crealf (complex float z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
long double creall (complex long double z)
`complex.h' (ISO): section Projections, Conjugates, and Decomposing of Complex Numbers.
int creat (const char *filename, mode_t mode)
`fcntl.h' (POSIX.1): section Opening and Closing Files.
int creat64 (const char *filename, mode_t mode)
`fcntl.h' (Unix98): section Opening and Closing Files.
tcflag_t CRTS_IFLOW
`termios.h' (BSD): section Control Modes.
char * crypt (const char *key, const char *salt)
`crypt.h' (BSD, SVID): section Encrypting Passwords.
char * crypt_r (const char *key, const char *salt, struct crypt_data * data)
`crypt.h' (GNU): section Encrypting Passwords.
tcflag_t CS5
`termios.h' (POSIX.1): section Control Modes.
tcflag_t CS6
`termios.h' (POSIX.1): section Control Modes.
tcflag_t CS7
`termios.h' (POSIX.1): section Control Modes.
tcflag_t CS8
`termios.h' (POSIX.1): section Control Modes.
complex double csin (complex double z)
`complex.h' (ISO): section Trigonometric Functions.
complex float csinf (complex float z)
`complex.h' (ISO): section Trigonometric Functions.
complex double csinh (complex double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex float csinhf (complex float z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double csinhl (complex long double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double csinl (complex long double z)
`complex.h' (ISO): section Trigonometric Functions.
tcflag_t CSIZE
`termios.h' (POSIX.1): section Control Modes.
_CS_LFS64_CFLAGS
`unistd.h' (Unix98): section String-Valued Parameters.
_CS_LFS64_LDFLAGS
`unistd.h' (Unix98): section String-Valued Parameters.
_CS_LFS64_LIBS
`unistd.h' (Unix98): section String-Valued Parameters.
_CS_LFS64_LINTFLAGS
`unistd.h' (Unix98): section String-Valued Parameters.
_CS_LFS_CFLAGS
`unistd.h' (Unix98): section String-Valued Parameters.
_CS_LFS_LDFLAGS
`unistd.h' (Unix98): section String-Valued Parameters.
_CS_LFS_LIBS
`unistd.h' (Unix98): section String-Valued Parameters.
_CS_LFS_LINTFLAGS
`unistd.h' (Unix98): section String-Valued Parameters.
_CS_PATH
`unistd.h' (POSIX.2): section String-Valued Parameters.
complex double csqrt (complex double z)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex float csqrtf (complex float z)
`complex.h' (ISO): section Exponentiation and Logarithms.
complex long double csqrtl (complex long double z)
`complex.h' (ISO): section Exponentiation and Logarithms.
tcflag_t CSTOPB
`termios.h' (POSIX.1): section Control Modes.
complex double ctan (complex double z)
`complex.h' (ISO): section Trigonometric Functions.
complex float ctanf (complex float z)
`complex.h' (ISO): section Trigonometric Functions.
complex double ctanh (complex double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex float ctanhf (complex float z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double ctanhl (complex long double z)
`complex.h' (ISO): section Hyperbolic Functions.
complex long double ctanl (complex long double z)
`complex.h' (ISO): section Trigonometric Functions.
char * ctermid (char *string)
`stdio.h' (POSIX.1): section Identifying the Controlling Terminal.
char * ctime (const time_t *time)
`time.h' (ISO): section Formatting Calendar Time.
char * ctime_r (const time_t *time, char *buffer)
`time.h' (POSIX.1c): section Formatting Calendar Time.
char * cuserid (char *string)
`stdio.h' (POSIX.1): section Identifying Who Logged In.
int daylight
`time.h' (SVID): section Functions and Variables for Time Zones.
DBL_DIG
`float.h' (ISO): section Floating Point Parameters.
DBL_EPSILON
`float.h' (ISO): section Floating Point Parameters.
DBL_MANT_DIG
`float.h' (ISO): section Floating Point Parameters.
DBL_MAX
`float.h' (ISO): section Floating Point Parameters.
DBL_MAX_10_EXP
`float.h' (ISO): section Floating Point Parameters.
DBL_MAX_EXP
`float.h' (ISO): section Floating Point Parameters.
DBL_MIN
`float.h' (ISO): section Floating Point Parameters.
DBL_MIN_10_EXP
`float.h' (ISO): section Floating Point Parameters.
DBL_MIN_EXP
`float.h' (ISO): section Floating Point Parameters.
char * dcgettext (const char *domainname, const char *msgid, int category)
`libintl.h' (GNU): section What has to be done to translate a message?.
char * dcngettext (const char *domain, const char *msgid1, const char *msgid2, unsigned long int n, int category)
`libintl.h' (GNU): section Additional functions for more complicated situations.
DEAD_PROCESS
`utmp.h' (SVID): section Manipulating the User Accounting Database.
DEAD_PROCESS
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
DES_DECRYPT
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
DES_ENCRYPT
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
DESERR_BADPARAM
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
DESERR_HWERROR
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
DESERR_NOHWDEVICE
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
DESERR_NONE
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
int DES_FAILED (int err)
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
DES_HW
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
void des_setparity (char *key)
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
DES_SW
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
dev_t
`sys/types.h' (POSIX.1): section The meaning of the File Attributes.
char * dgettext (const char *domainname, const char *msgid)
`libintl.h' (GNU): section What has to be done to translate a message?.
double difftime (time_t time1, time_t time0)
`time.h' (ISO): section Elapsed Time.
DIR
`dirent.h' (POSIX.1): section Opening a Directory Stream.
int dirfd (DIR *dirstream)
`dirent.h' (GNU): section Opening a Directory Stream.
char * dirname (char *path)
`libgen.h' (XPG): section Finding Tokens in a String.
div_t div (int numerator, int denominator)
`stdlib.h' (ISO): section Integer Division.
div_t
`stdlib.h' (ISO): section Integer Division.
char * dngettext (const char *domain, const char *msgid1, const char *msgid2, unsigned long int n)
`libintl.h' (GNU): section Additional functions for more complicated situations.
double drand48 (void)
`stdlib.h' (SVID): section SVID Random Number Function.
int drand48_r (struct drand48_data *buffer, double *result)
`stdlib.h' (GNU): section SVID Random Number Function.
double drem (double numerator, double denominator)
`math.h' (BSD): section Remainder Functions.
float dremf (float numerator, float denominator)
`math.h' (BSD): section Remainder Functions.
long double dreml (long double numerator, long double denominator)
`math.h' (BSD): section Remainder Functions.
mode_t DTTOIF (int dtype)
`dirent.h' (BSD): section Format of a Directory Entry.
int dup (int old)
`unistd.h' (POSIX.1): section Duplicating Descriptors.
int dup2 (int old, int new)
`unistd.h' (POSIX.1): section Duplicating Descriptors.
int E2BIG
`errno.h' (POSIX.1: Argument list too long): section Error Codes.
int EACCES
`errno.h' (POSIX.1: Permission denied): section Error Codes.
int EADDRINUSE
`errno.h' (BSD: Address already in use): section Error Codes.
int EADDRNOTAVAIL
`errno.h' (BSD: Cannot assign requested address): section Error Codes.
int EADV
`errno.h' (Linux???: Advertise error): section Error Codes.
int EAFNOSUPPORT
`errno.h' (BSD: Address family not supported by protocol): section Error Codes.
int EAGAIN
`errno.h' (POSIX.1: Resource temporarily unavailable): section Error Codes.
int EALREADY
`errno.h' (BSD: Operation already in progress): section Error Codes.
int EAUTH
`errno.h' (BSD: Authentication error): section Error Codes.
int EBACKGROUND
`errno.h' (GNU: Inappropriate operation for background process): section Error Codes.
int EBADE
`errno.h' (Linux???: Invalid exchange): section Error Codes.
int EBADF
`errno.h' (POSIX.1: Bad file descriptor): section Error Codes.
int EBADFD
`errno.h' (Linux???: File descriptor in bad state): section Error Codes.
int EBADMSG
`errno.h' (XOPEN: Bad message): section Error Codes.
int EBADR
`errno.h' (Linux???: Invalid request descriptor): section Error Codes.
int EBADRPC
`errno.h' (BSD: RPC struct is bad): section Error Codes.
int EBADRQC
`errno.h' (Linux???: Invalid request code): section Error Codes.
int EBADSLT
`errno.h' (Linux???: Invalid slot): section Error Codes.
int EBFONT
`errno.h' (Linux???: Bad font file format): section Error Codes.
int EBUSY
`errno.h' (POSIX.1: Device or resource busy): section Error Codes.
int ecb_crypt (char *key, char *blocks, unsigned len, unsigned mode)
`rpc/des_crypt.h' (SUNRPC): section DES Encryption.
int ECHILD
`errno.h' (POSIX.1: No child processes): section Error Codes.
tcflag_t ECHO
`termios.h' (POSIX.1): section Local Modes.
tcflag_t ECHOCTL
`termios.h' (BSD): section Local Modes.
tcflag_t ECHOE
`termios.h' (POSIX.1): section Local Modes.
tcflag_t ECHOK
`termios.h' (POSIX.1): section Local Modes.
tcflag_t ECHOKE
`termios.h' (BSD): section Local Modes.
tcflag_t ECHONL
`termios.h' (POSIX.1): section Local Modes.
tcflag_t ECHOPRT
`termios.h' (BSD): section Local Modes.
int ECHRNG
`errno.h' (Linux???: Channel number out of range): section Error Codes.
int ECOMM
`errno.h' (Linux???: Communication error on send): section Error Codes.
int ECONNABORTED
`errno.h' (BSD: Software caused connection abort): section Error Codes.
int ECONNREFUSED
`errno.h' (BSD: Connection refused): section Error Codes.
int ECONNRESET
`errno.h' (BSD: Connection reset by peer): section Error Codes.
char * ecvt (double value, int ndigit, int *decpt, int *neg)
`stdlib.h' (SVID, Unix98): section Old-fashioned System V number-to-string functions.
char * ecvt_r (double value, int ndigit, int *decpt, int *neg, char *buf, size_t len)
`stdlib.h' (GNU): section Old-fashioned System V number-to-string functions.
int ED
`errno.h' (GNU: ?): section Error Codes.
int EDEADLK
`errno.h' (POSIX.1: Resource deadlock avoided): section Error Codes.
int EDEADLOCK
`errno.h' (Linux???: File locking deadlock error): section Error Codes.
int EDESTADDRREQ
`errno.h' (BSD: Destination address required): section Error Codes.
int EDIED
`errno.h' (GNU: Translator died): section Error Codes.
int EDOM
`errno.h' (ISO: Numerical argument out of domain): section Error Codes.
int EDOTDOT
`errno.h' (Linux???: RFS specific error): section Error Codes.
int EDQUOT
`errno.h' (BSD: Disk quota exceeded): section Error Codes.
int EEXIST
`errno.h' (POSIX.1: File exists): section Error Codes.
int EFAULT
`errno.h' (POSIX.1: Bad address): section Error Codes.
int EFBIG
`errno.h' (POSIX.1: File too large): section Error Codes.
int EFTYPE
`errno.h' (BSD: Inappropriate file type or format): section Error Codes.
int EGRATUITOUS
`errno.h' (GNU: Gratuitous error): section Error Codes.
int EGREGIOUS
`errno.h' (GNU: You really blew it this time): section Error Codes.
int EHOSTDOWN
`errno.h' (BSD: Host is down): section Error Codes.
int EHOSTUNREACH
`errno.h' (BSD: No route to host): section Error Codes.
int EIDRM
`errno.h' (XOPEN: Identifier removed): section Error Codes.
int EIEIO
`errno.h' (GNU: Computer bought the farm): section Error Codes.
int EILSEQ
`errno.h' (ISO: Invalid or incomplete multibyte or wide character): section Error Codes.
int EINPROGRESS
`errno.h' (BSD: Operation now in progress): section Error Codes.
int EINTR
`errno.h' (POSIX.1: Interrupted system call): section Error Codes.
int EINVAL
`errno.h' (POSIX.1: Invalid argument): section Error Codes.
int EIO
`errno.h' (POSIX.1: Input/output error): section Error Codes.
int EISCONN
`errno.h' (BSD: Transport endpoint is already connected): section Error Codes.
int EISDIR
`errno.h' (POSIX.1: Is a directory): section Error Codes.
int EISNAM
`errno.h' (Linux???: Is a named type file): section Error Codes.
int EL2HLT
`errno.h' (Obsolete: Level 2 halted): section Error Codes.
int EL2NSYNC
`errno.h' (Obsolete: Level 2 not synchronized): section Error Codes.
int EL3HLT
`errno.h' (Obsolete: Level 3 halted): section Error Codes.
int EL3RST
`errno.h' (Obsolete: Level 3 reset): section Error Codes.
int ELIBACC
`errno.h' (Linux???: Can not access a needed shared library): section Error Codes.
int ELIBBAD
`errno.h' (Linux???: Accessing a corrupted shared library): section Error Codes.
int ELIBEXEC
`errno.h' (Linux???: Cannot exec a shared library directly): section Error Codes.
int ELIBMAX
`errno.h' (Linux???: Attempting to link in too many shared libraries): section Error Codes.
int ELIBSCN
`errno.h' (Linux???: .lib section in a.out corrupted): section Error Codes.
int ELNRNG
`errno.h' (Linux???: Link number out of range): section Error Codes.
int ELOOP
`errno.h' (BSD: Too many levels of symbolic links): section Error Codes.
int EMEDIUMTYPE
`errno.h' (Linux???: Wrong medium type): section Error Codes.
int EMFILE
`errno.h' (POSIX.1: Too many open files): section Error Codes.
int EMLINK
`errno.h' (POSIX.1: Too many links): section Error Codes.
EMPTY
`utmp.h' (SVID): section Manipulating the User Accounting Database.
EMPTY
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
int EMSGSIZE
`errno.h' (BSD: Message too long): section Error Codes.
int EMULTIHOP
`errno.h' (XOPEN: Multihop attempted): section Error Codes.
int ENAMETOOLONG
`errno.h' (POSIX.1: File name too long): section Error Codes.
int ENAVAIL
`errno.h' (Linux???: No XENIX semaphores available): section Error Codes.
void encrypt (char *block, int edflag)
`crypt.h' (BSD, SVID): section DES Encryption.
void encrypt_r (char *block, int edflag, struct crypt_data * data)
`crypt.h' (GNU): section DES Encryption.
void endfsent (void)
`fstab.h' (BSD): section The `fstab' file.
void endgrent (void)
`grp.h' (SVID, BSD): section Scanning the List of All Groups.
void endhostent (void)
`netdb.h' (BSD): section Host Names.
int endmntent (FILE *stream)
`mntent.h' (BSD): section The `mtab' file.
void endnetent (void)
`netdb.h' (BSD): section Networks Database.
void endnetgrent (void)
`netdb.h' (BSD): section Looking up one Netgroup.
void endprotoent (void)
`netdb.h' (BSD): section Protocols Database.
void endpwent (void)
`pwd.h' (SVID, BSD): section Scanning the List of All Users.
void endservent (void)
`netdb.h' (BSD): section The Services Database.
void endutent (void)
`utmp.h' (SVID): section Manipulating the User Accounting Database.
void endutxent (void)
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
int ENEEDAUTH
`errno.h' (BSD: Need authenticator): section Error Codes.
int ENETDOWN
`errno.h' (BSD: Network is down): section Error Codes.
int ENETRESET
`errno.h' (BSD: Network dropped connection on reset): section Error Codes.
int ENETUNREACH
`errno.h' (BSD: Network is unreachable): section Error Codes.
int ENFILE
`errno.h' (POSIX.1: Too many open files in system): section Error Codes.
int ENOANO
`errno.h' (Linux???: No anode): section Error Codes.
int ENOBUFS
`errno.h' (BSD: No buffer space available): section Error Codes.
int ENOCSI
`errno.h' (Linux???: No CSI structure available): section Error Codes.
int ENODATA
`errno.h' (XOPEN: No data available): section Error Codes.
int ENODEV
`errno.h' (POSIX.1: No such device): section Error Codes.
int ENOENT
`errno.h' (POSIX.1: No such file or directory): section Error Codes.
int ENOEXEC
`errno.h' (POSIX.1: Exec format error): section Error Codes.
int ENOLCK
`errno.h' (POSIX.1: No locks available): section Error Codes.
int ENOLINK
`errno.h' (XOPEN: Link has been severed): section Error Codes.
int ENOMEDIUM
`errno.h' (Linux???: No medium found): section Error Codes.
int ENOMEM
`errno.h' (POSIX.1: Cannot allocate memory): section Error Codes.
int ENOMSG
`errno.h' (XOPEN: No message of desired type): section Error Codes.
int ENONET
`errno.h' (Linux???: Machine is not on the network): section Error Codes.
int ENOPKG
`errno.h' (Linux???: Package not installed): section Error Codes.
int ENOPROTOOPT
`errno.h' (BSD: Protocol not available): section Error Codes.
int ENOSPC
`errno.h' (POSIX.1: No space left on device): section Error Codes.
int ENOSR
`errno.h' (XOPEN: Out of streams resources): section Error Codes.
int ENOSTR
`errno.h' (XOPEN: Device not a stream): section Error Codes.
int ENOSYS
`errno.h' (POSIX.1: Function not implemented): section Error Codes.
int ENOTBLK
`errno.h' (BSD: Block device required): section Error Codes.
int ENOTCONN
`errno.h' (BSD: Transport endpoint is not connected): section Error Codes.
int ENOTDIR
`errno.h' (POSIX.1: Not a directory): section Error Codes.
int ENOTEMPTY
`errno.h' (POSIX.1: Directory not empty): section Error Codes.
int ENOTNAM
`errno.h' (Linux???: Not a XENIX named type file): section Error Codes.
int ENOTSOCK
`errno.h' (BSD: Socket operation on non-socket): section Error Codes.
int ENOTSUP
`errno.h' (POSIX.1: Not supported): section Error Codes.
int ENOTTY
`errno.h' (POSIX.1: Inappropriate ioctl for device): section Error Codes.
int ENOTUNIQ
`errno.h' (Linux???: Name not unique on network): section Error Codes.
char ** environ
`unistd.h' (POSIX.1): section Environment Access.
error_t envz_add (char **envz, size_t *envz_len, const char *name, const char *value)
`envz.h' (GNU): section Envz Functions.
char * envz_entry (const char *envz, size_t envz_len, const char *name)
`envz.h' (GNU): section Envz Functions.
char * envz_get (const char *envz, size_t envz_len, const char *name)
`envz.h' (GNU): section Envz Functions.
error_t envz_merge (char **envz, size_t *envz_len, const char *envz2, size_t envz2_len, int override)
`envz.h' (GNU): section Envz Functions.
void envz_strip (char **envz, size_t *envz_len)
`envz.h' (GNU): section Envz Functions.
int ENXIO
`errno.h' (POSIX.1: No such device or address): section Error Codes.
int EOF
`stdio.h' (ISO): section End-Of-File and Errors.
int EOPNOTSUPP
`errno.h' (BSD: Operation not supported): section Error Codes.
int EOVERFLOW
`errno.h' (XOPEN: Value too large for defined data type): section Error Codes.
int EPERM
`errno.h' (POSIX.1: Operation not permitted): section Error Codes.
int EPFNOSUPPORT
`errno.h' (BSD: Protocol family not supported): section Error Codes.
int EPIPE
`errno.h' (POSIX.1: Broken pipe): section Error Codes.
int EPROCLIM
`errno.h' (BSD: Too many processes): section Error Codes.
int EPROCUNAVAIL
`errno.h' (BSD: RPC bad procedure for program): section Error Codes.
int EPROGMISMATCH
`errno.h' (BSD: RPC program version wrong): section Error Codes.
int EPROGUNAVAIL
`errno.h' (BSD: RPC program not available): section Error Codes.
int EPROTO
`errno.h' (XOPEN: Protocol error): section Error Codes.
int EPROTONOSUPPORT
`errno.h' (BSD: Protocol not supported): section Error Codes.
int EPROTOTYPE
`errno.h' (BSD: Protocol wrong type for socket): section Error Codes.
int EQUIV_CLASS_MAX
`limits.h' (POSIX.2): section Utility Program Capacity Limits.
double erand48 (unsigned short int xsubi[3])
`stdlib.h' (SVID): section SVID Random Number Function.
int erand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, double *result)
`stdlib.h' (GNU): section SVID Random Number Function.
int ERANGE
`errno.h' (ISO: Numerical result out of range): section Error Codes.
int EREMCHG
`errno.h' (Linux???: Remote address changed): section Error Codes.
int EREMOTE
`errno.h' (BSD: Object is remote): section Error Codes.
int EREMOTEIO
`errno.h' (Linux???: Remote I/O error): section Error Codes.
int ERESTART
`errno.h' (Linux???: Interrupted system call should be restarted): section Error Codes.
double erf (double x)
`math.h' (SVID): section Special Functions.
double erfc (double x)
`math.h' (SVID): section Special Functions.
float erfcf (float x)
`math.h' (SVID): section Special Functions.
long double erfcl (long double x)
`math.h' (SVID): section Special Functions.
float erff (float x)
`math.h' (SVID): section Special Functions.
long double erfl (long double x)
`math.h' (SVID): section Special Functions.
int EROFS
`errno.h' (POSIX.1: Read-only file system): section Error Codes.
int ERPCMISMATCH
`errno.h' (BSD: RPC version wrong): section Error Codes.
volatile int errno
`errno.h' (ISO): section Checking for Errors.
int ESHUTDOWN
`errno.h' (BSD: Cannot send after transport endpoint shutdown): section Error Codes.
int ESOCKTNOSUPPORT
`errno.h' (BSD: Socket type not supported): section Error Codes.
int ESPIPE
`errno.h' (POSIX.1: Illegal seek): section Error Codes.
int ESRCH
`errno.h' (POSIX.1: No such process): section Error Codes.
int ESRMNT
`errno.h' (Linux???: Srmount error): section Error Codes.
int ESTALE
`errno.h' (BSD: Stale NFS file handle): section Error Codes.
int ESTRPIPE
`errno.h' (Linux???: Streams pipe error): section Error Codes.
int ETIME
`errno.h' (XOPEN: Timer expired): section Error Codes.
int ETIMEDOUT
`errno.h' (BSD: Connection timed out): section Error Codes.
int ETOOMANYREFS
`errno.h' (BSD: Too many references: cannot splice): section Error Codes.
int ETXTBSY
`errno.h' (BSD: Text file busy): section Error Codes.
int EUCLEAN
`errno.h' (Linux???: Structure needs cleaning): section Error Codes.
int EUNATCH
`errno.h' (Linux???: Protocol driver not attached): section Error Codes.
int EUSERS
`errno.h' (BSD: Too many users): section Error Codes.
int EWOULDBLOCK
`errno.h' (BSD: Operation would block): section Error Codes.
int EXDEV
`errno.h' (POSIX.1: Invalid cross-device link): section Error Codes.
int execl (const char *filename, const char *arg0, ...)
`unistd.h' (POSIX.1): section Executing a File.
int execle (const char *filename, const char *arg0, char *const env[], ...)
`unistd.h' (POSIX.1): section Executing a File.
int execlp (const char *filename, const char *arg0, ...)
`unistd.h' (POSIX.1): section Executing a File.
int execv (const char *filename, char *const argv[])
`unistd.h' (POSIX.1): section Executing a File.
int execve (const char *filename, char *const argv[], char *const env[])
`unistd.h' (POSIX.1): section Executing a File.
int execvp (const char *filename, char *const argv[])
`unistd.h' (POSIX.1): section Executing a File.
int EXFULL
`errno.h' (Linux???: Exchange full): section Error Codes.
void _Exit (int status)
`stdlib.h' (ISO): section Termination Internals.
void _exit (int status)
`unistd.h' (POSIX.1): section Termination Internals.
void exit (int status)
`stdlib.h' (ISO): section Normal Termination.
int EXIT_FAILURE
`stdlib.h' (ISO): section Exit Status.
int EXIT_SUCCESS
`stdlib.h' (ISO): section Exit Status.
double exp (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
double exp10 (double x)
`math.h' (GNU): section Exponentiation and Logarithms.
float exp10f (float x)
`math.h' (GNU): section Exponentiation and Logarithms.
long double exp10l (long double x)
`math.h' (GNU): section Exponentiation and Logarithms.
double exp2 (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float exp2f (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
long double exp2l (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float expf (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
long double expl (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
double expm1 (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float expm1f (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
long double expm1l (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
int EXPR_NEST_MAX
`limits.h' (POSIX.2): section Utility Program Capacity Limits.
double fabs (double number)
`math.h' (ISO): section Absolute Value.
float fabsf (float number)
`math.h' (ISO): section Absolute Value.
long double fabsl (long double number)
`math.h' (ISO): section Absolute Value.
size_t __fbufsize (FILE *stream)
`stdio_ext.h' (GNU): section Controlling Which Kind of Buffering.
int fchdir (int filedes)
`unistd.h' (XPG): section Working Directory.
int fchmod (int filedes, int mode)
`sys/stat.h' (BSD): section Assigning File Permissions.
int fchown (int filedes, int owner, int group)
`unistd.h' (BSD): section File Owner.
int fclean (FILE *stream)
`stdio.h' (GNU): section Cleaning Streams.
int fclose (FILE *stream)
`stdio.h' (ISO): section Closing Streams.
int fcloseall (void)
`stdio.h' (GNU): section Closing Streams.
int fcntl (int filedes, int command, ...)
`fcntl.h' (POSIX.1): section Control Operations on Files.
char * fcvt (double value, int ndigit, int *decpt, int *neg)
`stdlib.h' (SVID, Unix98): section Old-fashioned System V number-to-string functions.
char * fcvt_r (double value, int ndigit, int *decpt, int *neg, char *buf, size_t len)
`stdlib.h' (SVID, Unix98): section Old-fashioned System V number-to-string functions.
int fdatasync (int fildes)
`unistd.h' (POSIX): section Synchronizing I/O operations.
int FD_CLOEXEC
`fcntl.h' (POSIX.1): section File Descriptor Flags.
void FD_CLR (int filedes, fd_set *set)
`sys/types.h' (BSD): section Waiting for Input or Output.
double fdim (double x, double y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
float fdimf (float x, float y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
long double fdiml (long double x, long double y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
int FD_ISSET (int filedes, fd_set *set)
`sys/types.h' (BSD): section Waiting for Input or Output.
FILE * fdopen (int filedes, const char *opentype)
`stdio.h' (POSIX.1): section Descriptors and Streams.
void FD_SET (int filedes, fd_set *set)
`sys/types.h' (BSD): section Waiting for Input or Output.
fd_set
`sys/types.h' (BSD): section Waiting for Input or Output.
int FD_SETSIZE
`sys/types.h' (BSD): section Waiting for Input or Output.
int F_DUPFD
`fcntl.h' (POSIX.1): section Duplicating Descriptors.
void FD_ZERO (fd_set *set)
`sys/types.h' (BSD): section Waiting for Input or Output.
int feclearexcept (int excepts)
`fenv.h' (ISO): section Examining the FPU status word.
int fedisableexcept (int excepts)
`fenv.h' (GNU): section Floating-Point Control Functions.
FE_DIVBYZERO
`fenv.h' (ISO): section Examining the FPU status word.
FE_DOWNWARD
`fenv.h' (ISO): section Rounding Modes.
int feenableexcept (int excepts)
`fenv.h' (GNU): section Floating-Point Control Functions.
int fegetenv (fenv_t *envp)
`fenv.h' (ISO): section Floating-Point Control Functions.
int fegetexcept (int excepts)
`fenv.h' (GNU): section Floating-Point Control Functions.
int fegetexceptflag (fexcept_t *flagp, int excepts)
`fenv.h' (ISO): section Examining the FPU status word.
int fegetround (void)
`fenv.h' (ISO): section Rounding Modes.
int feholdexcept (fenv_t *envp)
`fenv.h' (ISO): section Floating-Point Control Functions.
FE_INEXACT
`fenv.h' (ISO): section Examining the FPU status word.
FE_INVALID
`fenv.h' (ISO): section Examining the FPU status word.
int feof (FILE *stream)
`stdio.h' (ISO): section End-Of-File and Errors.
int feof_unlocked (FILE *stream)
`stdio.h' (GNU): section End-Of-File and Errors.
FE_OVERFLOW
`fenv.h' (ISO): section Examining the FPU status word.
int feraiseexcept (int excepts)
`fenv.h' (ISO): section Examining the FPU status word.
int ferror (FILE *stream)
`stdio.h' (ISO): section End-Of-File and Errors.
int ferror_unlocked (FILE *stream)
`stdio.h' (GNU): section End-Of-File and Errors.
int fesetenv (const fenv_t *envp)
`fenv.h' (ISO): section Floating-Point Control Functions.
int fesetexceptflag (const fexcept_t *flagp, int
`fenv.h' (ISO): section Examining the FPU status word.
int fesetround (int round)
`fenv.h' (ISO): section Rounding Modes.
int fetestexcept (int excepts)
`fenv.h' (ISO): section Examining the FPU status word.
FE_TONEAREST
`fenv.h' (ISO): section Rounding Modes.
FE_TOWARDZERO
`fenv.h' (ISO): section Rounding Modes.
FE_UNDERFLOW
`fenv.h' (ISO): section Examining the FPU status word.
int feupdateenv (const fenv_t *envp)
`fenv.h' (ISO): section Floating-Point Control Functions.
FE_UPWARD
`fenv.h' (ISO): section Rounding Modes.
int fflush (FILE *stream)
`stdio.h' (ISO): section Flushing Buffers.
int fflush_unlocked (FILE *stream)
`stdio.h' (POSIX): section Flushing Buffers.
int fgetc (FILE *stream)
`stdio.h' (ISO): section Character Input.
int fgetc_unlocked (FILE *stream)
`stdio.h' (POSIX): section Character Input.
int F_GETFD
`fcntl.h' (POSIX.1): section File Descriptor Flags.
int F_GETFL
`fcntl.h' (POSIX.1): section Getting and Setting File Status Flags.
struct group * fgetgrent (FILE *stream)
`grp.h' (SVID): section Scanning the List of All Groups.
int fgetgrent_r (FILE *stream, struct group *result_buf, char *buffer, size_t buflen, struct group **result)
`grp.h' (GNU): section Scanning the List of All Groups.
int F_GETLK
`fcntl.h' (POSIX.1): section File Locks.
int F_GETOWN
`fcntl.h' (BSD): section Interrupt-Driven Input.
int fgetpos (FILE *stream, fpos_t *position)
`stdio.h' (ISO): section Portable File-Position Functions.
int fgetpos64 (FILE *stream, fpos64_t *position)
`stdio.h' (Unix98): section Portable File-Position Functions.
struct passwd * fgetpwent (FILE *stream)
`pwd.h' (SVID): section Scanning the List of All Users.
int fgetpwent_r (FILE *stream, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result)
`pwd.h' (GNU): section Scanning the List of All Users.
char * fgets (char *s, int count, FILE *stream)
`stdio.h' (ISO): section Line-Oriented Input.
char * fgets_unlocked (char *s, int count, FILE *stream)
`stdio.h' (GNU): section Line-Oriented Input.
wint_t fgetwc (FILE *stream)
`wchar.h' (ISO): section Character Input.
wint_t fgetwc_unlocked (FILE *stream)
`wchar.h' (GNU): section Character Input.
wchar_t * fgetws (wchar_t *ws, int count, FILE *stream)
`wchar.h' (ISO): section Line-Oriented Input.
wchar_t * fgetws_unlocked (wchar_t *ws, int count, FILE *stream)
`wchar.h' (GNU): section Line-Oriented Input.
FILE
`stdio.h' (ISO): section Streams.
int FILENAME_MAX
`stdio.h' (ISO): section Limits on File System Capacity.
int fileno (FILE *stream)
`stdio.h' (POSIX.1): section Descriptors and Streams.
int fileno_unlocked (FILE *stream)
`stdio.h' (GNU): section Descriptors and Streams.
int finite (double x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int finitef (float x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int finitel (long double x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int __flbf (FILE *stream)
`stdio_ext.h' (GNU): section Controlling Which Kind of Buffering.
void flockfile (FILE *stream)
`stdio.h' (POSIX): section Streams and Threads.
double floor (double x)
`math.h' (ISO): section Rounding Functions.
float floorf (float x)
`math.h' (ISO): section Rounding Functions.
long double floorl (long double x)
`math.h' (ISO): section Rounding Functions.
FLT_DIG
`float.h' (ISO): section Floating Point Parameters.
FLT_EPSILON
`float.h' (ISO): section Floating Point Parameters.
FLT_MANT_DIG
`float.h' (ISO): section Floating Point Parameters.
FLT_MAX
`float.h' (ISO): section Floating Point Parameters.
FLT_MAX_10_EXP
`float.h' (ISO): section Floating Point Parameters.
FLT_MAX_EXP
`float.h' (ISO): section Floating Point Parameters.
FLT_MIN
`float.h' (ISO): section Floating Point Parameters.
FLT_MIN_10_EXP
`float.h' (ISO): section Floating Point Parameters.
FLT_MIN_EXP
`float.h' (ISO): section Floating Point Parameters.
FLT_RADIX
`float.h' (ISO): section Floating Point Parameters.
FLT_ROUNDS
`float.h' (ISO): section Floating Point Parameters.
void _flushlbf (void)
`stdio_ext.h' (GNU): section Flushing Buffers.
tcflag_t FLUSHO
`termios.h' (BSD): section Local Modes.
double fma (double x, double y, double z)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
float fmaf (float x, float y, float z)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
long double fmal (long double x, long double y, long double z)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
double fmax (double x, double y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
float fmaxf (float x, float y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
long double fmaxl (long double x, long double y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
FILE * fmemopen (void *buf, size_t size, const char *opentype)
`stdio.h' (GNU): section String Streams.
double fmin (double x, double y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
float fminf (float x, float y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
long double fminl (long double x, long double y)
`math.h' (ISO): section Miscellaneous FP arithmetic functions.
double fmod (double numerator, double denominator)
`math.h' (ISO): section Remainder Functions.
float fmodf (float numerator, float denominator)
`math.h' (ISO): section Remainder Functions.
long double fmodl (long double numerator, long double denominator)
`math.h' (ISO): section Remainder Functions.
int fmtmsg (long int classification, const char *label, int severity, const char *text, const char *action, const char *tag)
`fmtmsg.h' (XPG): section Printing Formatted Messages.
int fnmatch (const char *pattern, const char *string, int flags)
`fnmatch.h' (POSIX.2): section Wildcard Matching.
FNM_CASEFOLD
`fnmatch.h' (GNU): section Wildcard Matching.
FNM_EXTMATCH
`fnmatch.h' (GNU): section Wildcard Matching.
FNM_FILE_NAME
`fnmatch.h' (GNU): section Wildcard Matching.
FNM_LEADING_DIR
`fnmatch.h' (GNU): section Wildcard Matching.
FNM_NOESCAPE
`fnmatch.h' (POSIX.2): section Wildcard Matching.
FNM_PATHNAME
`fnmatch.h' (POSIX.2): section Wildcard Matching.
FNM_PERIOD
`fnmatch.h' (POSIX.2): section Wildcard Matching.
int F_OK
`unistd.h' (POSIX.1): section Testing Permission to Access a File.
FILE * fopen (const char *filename, const char *opentype)
`stdio.h' (ISO): section Opening Streams.
FILE * fopen64 (const char *filename, const char *opentype)
`stdio.h' (Unix98): section Opening Streams.
FILE * fopencookie (void *cookie, const char *opentype, cookie_io_functions_t io-functions)
`stdio.h' (GNU): section Custom Streams and Cookies.
int FOPEN_MAX
`stdio.h' (ISO): section Opening Streams.
pid_t fork (void)
`unistd.h' (POSIX.1): section Creating a Process.
int forkpty (int *amaster, char *name, struct termios *termp, struct winsize *winp)
`pty.h' (BSD): section Opening a Pseudo-Terminal Pair.
long int fpathconf (int filedes, int parameter)
`unistd.h' (POSIX.1): section Using pathconf.
int fpclassify (float-type x)
`math.h' (ISO): section Floating-Point Number Classification Functions.
FPE_DECOVF_TRAP
`signal.h' (BSD): section Program Error Signals.
FPE_FLTDIV_FAULT
`signal.h' (BSD): section Program Error Signals.
FPE_FLTDIV_TRAP
`signal.h' (BSD): section Program Error Signals.
FPE_FLTOVF_FAULT
`signal.h' (BSD): section Program Error Signals.
FPE_FLTOVF_TRAP
`signal.h' (BSD): section Program Error Signals.
FPE_FLTUND_FAULT
`signal.h' (BSD): section Program Error Signals.
FPE_FLTUND_TRAP
`signal.h' (BSD): section Program Error Signals.
FPE_INTDIV_TRAP
`signal.h' (BSD): section Program Error Signals.
FPE_INTOVF_TRAP
`signal.h' (BSD): section Program Error Signals.
size_t __fpending (FILE *stream) The __fpending
`stdio_ext.h' (GNU): section Controlling Which Kind of Buffering.
FPE_SUBRNG_TRAP
`signal.h' (BSD): section Program Error Signals.
int FP_ILOGB0
`math.h' (ISO): section Exponentiation and Logarithms.
int FP_ILOGBNAN
`math.h' (ISO): section Exponentiation and Logarithms.
fpos64_t
`stdio.h' (Unix98): section Portable File-Position Functions.
fpos_t
`stdio.h' (ISO): section Portable File-Position Functions.
int fprintf (FILE *stream, const char *template, ...)
`stdio.h' (ISO): section Formatted Output Functions.
void __fpurge (FILE *stream)
`stdio_ext.h' (GNU): section Flushing Buffers.
int fputc (int c, FILE *stream)
`stdio.h' (ISO): section Simple Output by Characters or Lines.
int fputc_unlocked (int c, FILE *stream)
`stdio.h' (POSIX): section Simple Output by Characters or Lines.
int fputs (const char *s, FILE *stream)
`stdio.h' (ISO): section Simple Output by Characters or Lines.
int fputs_unlocked (const char *s, FILE *stream)
`stdio.h' (GNU): section Simple Output by Characters or Lines.
wint_t fputwc (wchar_t wc, FILE *stream)
`wchar.h' (ISO): section Simple Output by Characters or Lines.
wint_t fputwc_unlocked (wint_t wc, FILE *stream)
`wchar.h' (POSIX): section Simple Output by Characters or Lines.
int fputws (const wchar_t *ws, FILE *stream)
`wchar.h' (ISO): section Simple Output by Characters or Lines.
int fputws_unlocked (const wchar_t *ws, FILE *stream)
`wchar.h' (GNU): section Simple Output by Characters or Lines.
F_RDLCK
`fcntl.h' (POSIX.1): section File Locks.
size_t fread (void *data, size_t size, size_t count, FILE *stream)
`stdio.h' (ISO): section Block Input/Output.
int __freadable (FILE *stream)
`stdio_ext.h' (GNU): section Opening Streams.
int __freading (FILE *stream)
`stdio_ext.h' (GNU): section Opening Streams.
size_t fread_unlocked (void *data, size_t size, size_t count, FILE *stream)
`stdio.h' (GNU): section Block Input/Output.
void free (void *ptr)
`malloc.h', `stdlib.h' (ISO): section Freeing Memory Allocated with malloc.
__free_hook
`malloc.h' (GNU): section Memory Allocation Hooks.
FILE * freopen (const char *filename, const char *opentype, FILE *stream)
`stdio.h' (ISO): section Opening Streams.
FILE * freopen64 (const char *filename, const char *opentype, FILE *stream)
`stdio.h' (Unix98): section Opening Streams.
double frexp (double value, int *exponent)
`math.h' (ISO): section Normalization Functions.
float frexpf (float value, int *exponent)
`math.h' (ISO): section Normalization Functions.
long double frexpl (long double value, int *exponent)
`math.h' (ISO): section Normalization Functions.
int fscanf (FILE *stream, const char *template, ...)
`stdio.h' (ISO): section Formatted Input Functions.
int fseek (FILE *stream, long int offset, int whence)
`stdio.h' (ISO): section File Positioning.
int fseeko (FILE *stream, off_t offset, int whence)
`stdio.h' (Unix98): section File Positioning.
int fseeko64 (FILE *stream, off64_t offset, int whence)
`stdio.h' (Unix98): section File Positioning.
int F_SETFD
`fcntl.h' (POSIX.1): section File Descriptor Flags.
int F_SETFL
`fcntl.h' (POSIX.1): section Getting and Setting File Status Flags.
int F_SETLK
`fcntl.h' (POSIX.1): section File Locks.
int F_SETLKW
`fcntl.h' (POSIX.1): section File Locks.
int __fsetlocking (FILE *stream, int type)
`stdio_ext.h' (GNU): section Streams and Threads.
int F_SETOWN
`fcntl.h' (BSD): section Interrupt-Driven Input.
int fsetpos (FILE *stream, const fpos_t *position)
`stdio.h' (ISO): section Portable File-Position Functions.
int fsetpos64 (FILE *stream, const fpos64_t *position)
`stdio.h' (Unix98): section Portable File-Position Functions.
int fstat (int filedes, struct stat *buf)
`sys/stat.h' (POSIX.1): section Reading the Attributes of a File.
int fstat64 (int filedes, struct stat64 *buf)
`sys/stat.h' (Unix98): section Reading the Attributes of a File.
int fsync (int fildes)
`unistd.h' (POSIX): section Synchronizing I/O operations.
long int ftell (FILE *stream)
`stdio.h' (ISO): section File Positioning.
off_t ftello (FILE *stream)
`stdio.h' (Unix98): section File Positioning.
off64_t ftello64 (FILE *stream)
`stdio.h' (Unix98): section File Positioning.
int ftruncate (int fd, off_t length)
`unistd.h' (POSIX): section File Size.
int ftruncate64 (int id, off64_t length)
`unistd.h' (Unix98): section File Size.
int ftrylockfile (FILE *stream)
`stdio.h' (POSIX): section Streams and Threads.
int ftw (const char *filename, __ftw_func_t func, int descriptors)
`ftw.h' (SVID): section Working with Directory Trees.
int ftw64 (const char *filename, __ftw64_func_t func, int descriptors)
`ftw.h' (Unix98): section Working with Directory Trees.
__ftw64_func_t
`ftw.h' (GNU): section Working with Directory Trees.
__ftw_func_t
`ftw.h' (GNU): section Working with Directory Trees.
F_UNLCK
`fcntl.h' (POSIX.1): section File Locks.
void funlockfile (FILE *stream)
`stdio.h' (POSIX): section Streams and Threads.
int fwide (FILE *stream, int mode)
`wchar.h' (ISO): section Streams in Internationalized Applications.
int fwprintf (FILE *stream, const wchar_t *template, ...)
`wchar.h' (ISO): section Formatted Output Functions.
int __fwritable (FILE *stream)
`stdio_ext.h' (GNU): section Opening Streams.
size_t fwrite (const void *data, size_t size, size_t count, FILE *stream)
`stdio.h' (ISO): section Block Input/Output.
size_t fwrite_unlocked (const void *data, size_t size, size_t count, FILE *stream)
`stdio.h' (GNU): section Block Input/Output.
int __fwriting (FILE *stream)
`stdio_ext.h' (GNU): section Opening Streams.
F_WRLCK
`fcntl.h' (POSIX.1): section File Locks.
int fwscanf (FILE *stream, const wchar_t *template, ...)
`wchar.h' (ISO): section Formatted Input Functions.
double gamma (double x)
`math.h' (SVID): section Special Functions.
float gammaf (float x)
`math.h' (SVID): section Special Functions.
long double gammal (long double x)
`math.h' (SVID): section Special Functions.
void (*__gconv_end_fct) (struct gconv_step *)
`gconv.h' (GNU): section The iconv Implementation in the GNU C library.
int (*__gconv_fct) (struct __gconv_step *, struct __gconv_step_data *, const char **, const char *, size_t *, int)
`gconv.h' (GNU): section The iconv Implementation in the GNU C library.
int (*__gconv_init_fct) (struct __gconv_step *)
`gconv.h' (GNU): section The iconv Implementation in the GNU C library.
char * gcvt (double value, int ndigit, char *buf)
`stdlib.h' (SVID, Unix98): section Old-fashioned System V number-to-string functions.
long int get_avphys_pages (void)
`sys/sysinfo.h' (GNU): section How to get information about the memory subsystem?.
int getc (FILE *stream)
`stdio.h' (ISO): section Character Input.
int getchar (void)
`stdio.h' (ISO): section Character Input.
int getchar_unlocked (void)
`stdio.h' (POSIX): section Character Input.
int getcontext (ucontext_t *ucp)
`ucontext.h' (SVID): section Complete Context Control.
int getc_unlocked (FILE *stream)
`stdio.h' (POSIX): section Character Input.
char * get_current_dir_name (void)
`unistd.h' (GNU): section Working Directory.
char * getcwd (char *buffer, size_t size)
`unistd.h' (POSIX.1): section Working Directory.
struct tm * getdate (const char *string)
`time.h' (Unix98): section A More User-friendly Way to Parse Times and Dates.
getdate_err
`time.h' (Unix98): section A More User-friendly Way to Parse Times and Dates.
int getdate_r (const char *string, struct tm *tp)
`time.h' (GNU): section A More User-friendly Way to Parse Times and Dates.
ssize_t getdelim (char **lineptr, size_t *n, int delimiter, FILE *stream)
`stdio.h' (GNU): section Line-Oriented Input.
int getdomainnname (char *name, size_t length)
`unistd.h' (???): section Host Identification.
gid_t getegid (void)
`unistd.h' (POSIX.1): section Reading the Persona of a Process.
char * getenv (const char *name)
`stdlib.h' (ISO): section Environment Access.
uid_t geteuid (void)
`unistd.h' (POSIX.1): section Reading the Persona of a Process.
struct fstab * getfsent (void)
`fstab.h' (BSD): section The `fstab' file.
struct fstab * getfsfile (const char *name)
`fstab.h' (BSD): section The `fstab' file.
struct fstab * getfsspec (const char *name)
`fstab.h' (BSD): section The `fstab' file.
gid_t getgid (void)
`unistd.h' (POSIX.1): section Reading the Persona of a Process.
struct group * getgrent (void)
`grp.h' (SVID, BSD): section Scanning the List of All Groups.
int getgrent_r (struct group *result_buf, char *buffer, size_t buflen, struct group **result)
`grp.h' (GNU): section Scanning the List of All Groups.
struct group * getgrgid (gid_t gid)
`grp.h' (POSIX.1): section Looking Up One Group.
int getgrgid_r (gid_t gid, struct group *result_buf, char *buffer, size_t buflen, struct group **result)
`grp.h' (POSIX.1c): section Looking Up One Group.
struct group * getgrnam (const char *name)
`grp.h' (SVID, BSD): section Looking Up One Group.
int getgrnam_r (const char *name, struct group *result_buf, char *buffer, size_t buflen, struct group **result)
`grp.h' (POSIX.1c): section Looking Up One Group.
int getgroups (int count, gid_t *groups)
`unistd.h' (POSIX.1): section Reading the Persona of a Process.
struct hostent * gethostbyaddr (const char *addr, size_t length, int format)
`netdb.h' (BSD): section Host Names.
int gethostbyaddr_r (const char *addr, size_t length, int format, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop)
`netdb.h' (GNU): section Host Names.
struct hostent * gethostbyname (const char *name)
`netdb.h' (BSD): section Host Names.
struct hostent * gethostbyname2 (const char *name, int af)
`netdb.h' (IPv6 Basic API): section Host Names.
int gethostbyname2_r (const char *name, int af, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop)
`netdb.h' (GNU): section Host Names.
int gethostbyname_r (const char *restrict name, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop)
`netdb.h' (GNU): section Host Names.
struct hostent * gethostent (void)
`netdb.h' (BSD): section Host Names.
long int gethostid (void)
`unistd.h' (BSD): section Host Identification.
int gethostname (char *name, size_t size)
`unistd.h' (BSD): section Host Identification.
int getitimer (int which, struct itimerval *old)
`sys/time.h' (BSD): section Setting an Alarm.
ssize_t getline (char **lineptr, size_t *n, FILE *stream)
`stdio.h' (GNU): section Line-Oriented Input.
int getloadavg (double loadavg[], int nelem)
`stdlib.h' (BSD): section Learn about the processors available.
char * getlogin (void)
`unistd.h' (POSIX.1): section Identifying Who Logged In.
struct mntent * getmntent (FILE *stream)
`mntent.h' (BSD): section The `mtab' file.
struct mntent * getmntent_r (FILE *stream, struct mentent *result, char *buffer, int bufsize)
`mntent.h' (BSD): section The `mtab' file.
struct netent * getnetbyaddr (unsigned long int net, int type)
`netdb.h' (BSD): section Networks Database.
struct netent * getnetbyname (const char *name)
`netdb.h' (BSD): section Networks Database.
struct netent * getnetent (void)
`netdb.h' (BSD): section Networks Database.
int getnetgrent (char **hostp, char **userp, char **domainp)
`netdb.h' (BSD): section Looking up one Netgroup.
int getnetgrent_r (char **hostp, char **userp, char **domainp, char *buffer, int buflen)
`netdb.h' (GNU): section Looking up one Netgroup.
int get_nprocs (void)
`sys/sysinfo.h' (GNU): section Learn about the processors available.
int get_nprocs_conf (void)
`sys/sysinfo.h' (GNU): section Learn about the processors available.
int getopt (int argc, char **argv, const char *options)
`unistd.h' (POSIX.2): section Using the getopt function.
int getopt_long (int argc, char *const *argv, const char *shortopts, struct option *longopts, int *indexptr)
`getopt.h' (GNU): section Parsing Long Options with getopt_long.
int getopt_long_only (int argc, char *const *argv, const char *shortopts, struct option *longopts, int *indexptr)
`getopt.h' (GNU): section Parsing Long Options with getopt_long.
int getpagesize (void)
`unistd.h' (BSD): section How to get information about the memory subsystem?.
char * getpass (const char *prompt)
`unistd.h' (BSD): section Reading Passwords.
int getpeername (int socket, struct sockaddr *addr, socklen_t *length-ptr)
`sys/socket.h' (BSD): section Who is Connected to Me?.
int getpgid (pid_t pid)
`unistd.h' (SVID): section Process Group Functions.
pid_t getpgrp (pid_t pid)
`unistd.h' (BSD): section Process Group Functions.
pid_t getpgrp (void)
`unistd.h' (POSIX.1): section Process Group Functions.
long int get_phys_pages (void)
`sys/sysinfo.h' (GNU): section How to get information about the memory subsystem?.
pid_t getpid (void)
`unistd.h' (POSIX.1): section Process Identification.
pid_t getppid (void)
`unistd.h' (POSIX.1): section Process Identification.
int getpriority (int class, int id)
`sys/resource.h' (BSD,POSIX): section Functions For Traditional Scheduling.
struct protoent * getprotobyname (const char *name)
`netdb.h' (BSD): section Protocols Database.
struct protoent * getprotobynumber (int protocol)
`netdb.h' (BSD): section Protocols Database.
struct protoent * getprotoent (void)
`netdb.h' (BSD): section Protocols Database.
int getpt (void)
`stdlib.h' (GNU): section Allocating Pseudo-Terminals.
struct passwd * getpwent (void)
`pwd.h' (POSIX.1): section Scanning the List of All Users.
int getpwent_r (struct passwd *result_buf, char *buffer, int buflen, struct passwd **result)
`pwd.h' (GNU): section Scanning the List of All Users.
struct passwd * getpwnam (const char *name)
`pwd.h' (POSIX.1): section Looking Up One User.
int getpwnam_r (const char *name, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result)
`pwd.h' (POSIX.1c): section Looking Up One User.
struct passwd * getpwuid (uid_t uid)
`pwd.h' (POSIX.1): section Looking Up One User.
int getpwuid_r (uid_t uid, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **result)
`pwd.h' (POSIX.1c): section Looking Up One User.
int getrlimit (int resource, struct rlimit *rlp)
`sys/resource.h' (BSD): section Limiting Resource Usage.
int getrlimit64 (int resource, struct rlimit64 *rlp)
`sys/resource.h' (Unix98): section Limiting Resource Usage.
int getrusage (int processes, struct rusage *rusage)
`sys/resource.h' (BSD): section Resource Usage.
char * gets (char *s)
`stdio.h' (ISO): section Line-Oriented Input.
struct servent * getservbyname (const char *name, const char *proto)
`netdb.h' (BSD): section The Services Database.
struct servent * getservbyport (int port, const char *proto)
`netdb.h' (BSD): section The Services Database.
struct servent * getservent (void)
`netdb.h' (BSD): section The Services Database.
pid_t getsid (pid_t pid)
`unistd.h' (SVID): section Process Group Functions.
int getsockname (int socket, struct sockaddr *addr, socklen_t *length-ptr)
`sys/socket.h' (BSD): section Reading the Address of a Socket.
int getsockopt (int socket, int level, int optname, void *optval, socklen_t *optlen-ptr)
`sys/socket.h' (BSD): section Socket Option Functions.
int getsubopt (char **optionp, const char* const *tokens, char **valuep)
`stdlib.h' (stdlib.h): section Parsing of Suboptions.
char * gettext (const char *msgid)
`libintl.h' (GNU): section What has to be done to translate a message?.
int gettimeofday (struct timeval *tp, struct timezone *tzp)
`sys/time.h' (BSD): section High-Resolution Calendar.
uid_t getuid (void)
`unistd.h' (POSIX.1): section Reading the Persona of a Process.
mode_t getumask (void)
`sys/stat.h' (GNU): section Assigning File Permissions.
struct utmp * getutent (void)
`utmp.h' (SVID): section Manipulating the User Accounting Database.
int getutent_r (struct utmp *buffer, struct utmp **result)
`utmp.h' (GNU): section Manipulating the User Accounting Database.
struct utmp * getutid (const struct utmp *id)
`utmp.h' (SVID): section Manipulating the User Accounting Database.
int getutid_r (const struct utmp *id, struct utmp *buffer, struct utmp **result)
`utmp.h' (GNU): section Manipulating the User Accounting Database.
struct utmp * getutline (const struct utmp *line)
`utmp.h' (SVID): section Manipulating the User Accounting Database.
int getutline_r (const struct utmp *line, struct utmp *buffer, struct utmp **result)
`utmp.h' (GNU): section Manipulating the User Accounting Database.
int getutmp (const struct utmpx *utmpx, struct utmp *utmp)
`utmp.h' (GNU): section XPG User Accounting Database Functions.
int getutmpx (const struct utmp *utmp, struct utmpx *utmpx)
`utmp.h' (GNU): section XPG User Accounting Database Functions.
struct utmpx * getutxent (void)
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
struct utmpx * getutxid (const struct utmpx *id)
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
struct utmpx * getutxline (const struct utmpx *line)
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
int getw (FILE *stream)
`stdio.h' (SVID): section Character Input.
wint_t getwc (FILE *stream)
`wchar.h' (ISO): section Character Input.
wint_t getwchar (void)
`wchar.h' (ISO): section Character Input.
wint_t getwchar_unlocked (void)
`wchar.h' (GNU): section Character Input.
wint_t getwc_unlocked (FILE *stream)
`wchar.h' (GNU): section Character Input.
char * getwd (char *buffer)
`unistd.h' (BSD): section Working Directory.
gid_t
`sys/types.h' (POSIX.1): section Reading the Persona of a Process.
int glob (const char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob_t *vector-ptr)
`glob.h' (POSIX.2): section Calling glob.
int glob64 (const char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob64_t *vector-ptr)
`glob.h' (GNU): section Calling glob.
glob64_t
`glob.h' (GNU): section Calling glob.
GLOB_ABORTED
`glob.h' (POSIX.2): section Calling glob.
GLOB_ALTDIRFUNC
`glob.h' (GNU): section More Flags for Globbing.
GLOB_APPEND
`glob.h' (POSIX.2): section Flags for Globbing.
GLOB_BRACE
`glob.h' (GNU): section More Flags for Globbing.
GLOB_DOOFFS
`glob.h' (POSIX.2): section Flags for Globbing.
GLOB_ERR
`glob.h' (POSIX.2): section Flags for Globbing.
void globfree (glob_t *pglob)
`glob.h' (POSIX.2): section More Flags for Globbing.
void globfree64 (glob64_t *pglob)
`glob.h' (GNU): section More Flags for Globbing.
GLOB_MAGCHAR
`glob.h' (GNU): section More Flags for Globbing.
GLOB_MARK
`glob.h' (POSIX.2): section Flags for Globbing.
GLOB_NOCHECK
`glob.h' (POSIX.2): section Flags for Globbing.
GLOB_NOESCAPE
`glob.h' (POSIX.2): section Flags for Globbing.
GLOB_NOMAGIC
`glob.h' (GNU): section More Flags for Globbing.
GLOB_NOMATCH
`glob.h' (POSIX.2): section Calling glob.
GLOB_NOSORT
`glob.h' (POSIX.2): section Flags for Globbing.
GLOB_NOSPACE
`glob.h' (POSIX.2): section Calling glob.
GLOB_ONLYDIR
`glob.h' (GNU): section More Flags for Globbing.
GLOB_PERIOD
`glob.h' (GNU): section More Flags for Globbing.
glob_t
`glob.h' (POSIX.2): section Calling glob.
GLOB_TILDE
`glob.h' (GNU): section More Flags for Globbing.
GLOB_TILDE_CHECK
`glob.h' (GNU): section More Flags for Globbing.
struct tm * gmtime (const time_t *time)
`time.h' (ISO): section Broken-down Time.
struct tm * gmtime_r (const time_t *time, struct tm *resultp)
`time.h' (POSIX.1c): section Broken-down Time.
_GNU_SOURCE
(GNU): section Feature Test Macros.
int grantpt (int filedes)
`stdlib.h' (SVID, XPG4.2): section Allocating Pseudo-Terminals.
int gsignal (int signum)
`signal.h' (SVID): section Signaling Yourself.
int gtty (int filedes, struct sgttyb *attributes)
`sgtty.h' (BSD): section BSD Terminal Modes.
char * hasmntopt (const struct mntent *mnt, const char *opt)
`mntent.h' (BSD): section The `mtab' file.
int hcreate (size_t nel)
`search.h' (SVID): section The hsearch function..
int hcreate_r (size_t nel, struct hsearch_data *htab)
`search.h' (GNU): section The hsearch function..
void hdestroy (void)
`search.h' (SVID): section The hsearch function..
void hdestroy_r (struct hsearch_data *htab)
`search.h' (GNU): section The hsearch function..
HOST_NOT_FOUND
`netdb.h' (BSD): section Host Names.
ENTRY * hsearch (ENTRY item, ACTION action)
`search.h' (SVID): section The hsearch function..
int hsearch_r (ENTRY item, ACTION action, ENTRY **retval, struct hsearch_data *htab)
`search.h' (GNU): section The hsearch function..
uint32_t htonl (uint32_t hostlong)
`netinet/in.h' (BSD): section Byte Order Conversion.
uint16_t htons (uint16_t hostshort)
`netinet/in.h' (BSD): section Byte Order Conversion.
double HUGE_VAL
`math.h' (ISO): section Error Reporting by Mathematical Functions.
float HUGE_VALF
`math.h' (ISO): section Error Reporting by Mathematical Functions.
long double HUGE_VALL
`math.h' (ISO): section Error Reporting by Mathematical Functions.
tcflag_t HUPCL
`termios.h' (POSIX.1): section Control Modes.
double hypot (double x, double y)
`math.h' (ISO): section Exponentiation and Logarithms.
float hypotf (float x, float y)
`math.h' (ISO): section Exponentiation and Logarithms.
long double hypotl (long double x, long double y)
`math.h' (ISO): section Exponentiation and Logarithms.
tcflag_t ICANON
`termios.h' (POSIX.1): section Local Modes.
size_t iconv (iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft)
`iconv.h' (XPG2): section Generic Character Set Conversion Interface.
int iconv_close (iconv_t cd)
`iconv.h' (XPG2): section Generic Character Set Conversion Interface.
iconv_t iconv_open (const char *tocode, const char *fromcode)
`iconv.h' (XPG2): section Generic Character Set Conversion Interface.
iconv_t
`iconv.h' (XPG2): section Generic Character Set Conversion Interface.
tcflag_t ICRNL
`termios.h' (POSIX.1): section Input Modes.
tcflag_t IEXTEN
`termios.h' (POSIX.1): section Local Modes.
void if_freenameindex (struct if_nameindex *ptr)
`net/if.h' (IPv6 basic API): section Interface Naming.
char * if_indextoname (unsigned int ifindex, char *ifname)
`net/if.h' (IPv6 basic API): section Interface Naming.
struct if_nameindex * if_nameindex (void)
`net/if.h' (IPv6 basic API): section Interface Naming.
unsigned int if_nametoindex (const char *ifname)
`net/if.h' (IPv6 basic API): section Interface Naming.
size_t IFNAMSIZ
`net/if.h' (net/if.h): section Interface Naming.
int IFTODT (mode_t mode)
`dirent.h' (BSD): section Format of a Directory Entry.
tcflag_t IGNBRK
`termios.h' (POSIX.1): section Input Modes.
tcflag_t IGNCR
`termios.h' (POSIX.1): section Input Modes.
tcflag_t IGNPAR
`termios.h' (POSIX.1): section Input Modes.
int ilogb (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
int ilogbf (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
int ilogbl (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
intmax_t imaxabs (intmax_t number)
`inttypes.h' (ISO): section Absolute Value.
tcflag_t IMAXBEL
`termios.h' (BSD): section Input Modes.
imaxdiv_t imaxdiv (intmax_t numerator, intmax_t denominator)
`inttypes.h' (ISO): section Integer Division.
imaxdiv_t
`inttypes.h' (ISO): section Integer Division.
struct in6_addr in6addr_any
`netinet/in.h' (IPv6 basic API): section Host Address Data Type.
struct in6_addr in6addr_loopback
`netinet/in.h' (IPv6 basic API): section Host Address Data Type.
uint32_t INADDR_ANY
`netinet/in.h' (BSD): section Host Address Data Type.
uint32_t INADDR_BROADCAST
`netinet/in.h' (BSD): section Host Address Data Type.
uint32_t INADDR_LOOPBACK
`netinet/in.h' (BSD): section Host Address Data Type.
uint32_t INADDR_NONE
`netinet/in.h' (BSD): section Host Address Data Type.
char * index (const char *string, int c)
`string.h' (BSD): section Search Functions.
uint32_t inet_addr (const char *name)
`arpa/inet.h' (BSD): section Host Address Functions.
int inet_aton (const char *name, struct in_addr *addr)
`arpa/inet.h' (BSD): section Host Address Functions.
uint32_t inet_lnaof (struct in_addr addr)
`arpa/inet.h' (BSD): section Host Address Functions.
struct in_addr inet_makeaddr (uint32_t net, uint32_t local)
`arpa/inet.h' (BSD): section Host Address Functions.
uint32_t inet_netof (struct in_addr addr)
`arpa/inet.h' (BSD): section Host Address Functions.
uint32_t inet_network (const char *name)
`arpa/inet.h' (BSD): section Host Address Functions.
char * inet_ntoa (struct in_addr addr)
`arpa/inet.h' (BSD): section Host Address Functions.
const char * inet_ntop (int af, const void *cp, char *buf, size_t len)
`arpa/inet.h' (IPv6 basic API): section Host Address Functions.
int inet_pton (int af, const char *cp, void *buf)
`arpa/inet.h' (IPv6 basic API): section Host Address Functions.
float INFINITY
`math.h' (ISO): section Infinity and NaN.
double infnan (int error)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int initgroups (const char *user, gid_t gid)
`grp.h' (BSD): section Setting the Group IDs.
INIT_PROCESS
`utmp.h' (SVID): section Manipulating the User Accounting Database.
INIT_PROCESS
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
void * initstate (unsigned int seed, void *state, size_t size)
`stdlib.h' (BSD): section BSD Random Number Functions.
int initstate_r (unsigned int seed, char *restrict statebuf, size_t statelen, struct random_data *restrict buf)
`stdlib.h' (GNU): section BSD Random Number Functions.
tcflag_t INLCR
`termios.h' (POSIX.1): section Input Modes.
int innetgr (const char *netgroup, const char *host, const char *user, const char *domain)
`netdb.h' (BSD): section Testing for Netgroup Membership.
ino64_t
`sys/types.h' (Unix98): section The meaning of the File Attributes.
ino_t
`sys/types.h' (POSIX.1): section The meaning of the File Attributes.
tcflag_t INPCK
`termios.h' (POSIX.1): section Input Modes.
INT_MAX
`limits.h' (ISO): section Range of an Integer Type.
INT_MIN
`limits.h' (ISO): section Range of an Integer Type.
int _IOFBF
`stdio.h' (ISO): section Controlling Which Kind of Buffering.
int _IOLBF
`stdio.h' (ISO): section Controlling Which Kind of Buffering.
int _IONBF
`stdio.h' (ISO): section Controlling Which Kind of Buffering.
int IPPORT_RESERVED
`netinet/in.h' (BSD): section Internet Ports.
int IPPORT_USERRESERVED
`netinet/in.h' (BSD): section Internet Ports.
int isalnum (int c)
`ctype.h' (ISO): section Classification of Characters.
int isalpha (int c)
`ctype.h' (ISO): section Classification of Characters.
int isascii (int c)
`ctype.h' (SVID, BSD): section Classification of Characters.
int isatty (int filedes)
`unistd.h' (POSIX.1): section Identifying Terminals.
int isblank (int c)
`ctype.h' (GNU): section Classification of Characters.
int iscntrl (int c)
`ctype.h' (ISO): section Classification of Characters.
int isdigit (int c)
`ctype.h' (ISO): section Classification of Characters.
int isfinite (float-type x)
`math.h' (ISO): section Floating-Point Number Classification Functions.
int isgraph (int c)
`ctype.h' (ISO): section Classification of Characters.
int isgreater (real-floating x, real-floating y)
`math.h' (ISO): section Floating-Point Comparison Functions.
int isgreaterequal (real-floating x, real-floating y)
`math.h' (ISO): section Floating-Point Comparison Functions.
tcflag_t ISIG
`termios.h' (POSIX.1): section Local Modes.
int isinf (double x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int isinff (float x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int isinfl (long double x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int isless (real-floating x, real-floating y)
`math.h' (ISO): section Floating-Point Comparison Functions.
int islessequal (real-floating x, real-floating y)
`math.h' (ISO): section Floating-Point Comparison Functions.
int islessgreater (real-floating x, real-floating y)
`math.h' (ISO): section Floating-Point Comparison Functions.
int islower (int c)
`ctype.h' (ISO): section Classification of Characters.
int isnan (float-type x)
`math.h' (ISO): section Floating-Point Number Classification Functions.
int isnan (double x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int isnanf (float x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int isnanl (long double x)
`math.h' (BSD): section Floating-Point Number Classification Functions.
int isnormal (float-type x)
`math.h' (ISO): section Floating-Point Number Classification Functions.
_ISOC99_SOURCE
(GNU): section Feature Test Macros.
int isprint (int c)
`ctype.h' (ISO): section Classification of Characters.
int ispunct (int c)
`ctype.h' (ISO): section Classification of Characters.
int isspace (int c)
`ctype.h' (ISO): section Classification of Characters.
tcflag_t ISTRIP
`termios.h' (POSIX.1): section Input Modes.
int isunordered (real-floating x, real-floating y)
`math.h' (ISO): section Floating-Point Comparison Functions.
int isupper (int c)
`ctype.h' (ISO): section Classification of Characters.
int iswalnum (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswalpha (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswblank (wint_t wc)
`wctype.h' (GNU): section Character class determination for wide characters.
int iswcntrl (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswctype (wint_t wc, wctype_t desc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswdigit (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswgraph (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswlower (wint_t wc)
`ctype.h' (ISO): section Character class determination for wide characters.
int iswprint (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswpunct (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswspace (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswupper (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int iswxdigit (wint_t wc)
`wctype.h' (ISO): section Character class determination for wide characters.
int isxdigit (int c)
`ctype.h' (ISO): section Classification of Characters.
ITIMER_PROF
`sys/time.h' (BSD): section Setting an Alarm.
ITIMER_REAL
`sys/time.h' (BSD): section Setting an Alarm.
ITIMER_VIRTUAL
`sys/time.h' (BSD): section Setting an Alarm.
tcflag_t IXANY
`termios.h' (BSD): section Input Modes.
tcflag_t IXOFF
`termios.h' (POSIX.1): section Input Modes.
tcflag_t IXON
`termios.h' (POSIX.1): section Input Modes.
double j0 (double x)
`math.h' (SVID): section Special Functions.
float j0f (float x)
`math.h' (SVID): section Special Functions.
long double j0l (long double x)
`math.h' (SVID): section Special Functions.
double j1 (double x)
`math.h' (SVID): section Special Functions.
float j1f (float x)
`math.h' (SVID): section Special Functions.
long double j1l (long double x)
`math.h' (SVID): section Special Functions.
jmp_buf
`setjmp.h' (ISO): section Details of Non-Local Exits.
double jn (int n, double x)
`math.h' (SVID): section Special Functions.
float jnf (int n, float x)
`math.h' (SVID): section Special Functions.
long double jnl (int n, long double x)
`math.h' (SVID): section Special Functions.
long int jrand48 (unsigned short int xsubi[3])
`stdlib.h' (SVID): section SVID Random Number Function.
int jrand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, long int *result)
`stdlib.h' (GNU): section SVID Random Number Function.
int kill (pid_t pid, int signum)
`signal.h' (POSIX.1): section Signaling Another Process.
int killpg (int pgid, int signum)
`signal.h' (BSD): section Signaling Another Process.
char * l64a (long int n)
`stdlib.h' (XPG): section Encode Binary Data.
long int labs (long int number)
`stdlib.h' (ISO): section Absolute Value.
LANG
`locale.h' (ISO): section Categories of Activities that Locales Affect.
LC_ALL
`locale.h' (ISO): section Categories of Activities that Locales Affect.
LC_COLLATE
`locale.h' (ISO): section Categories of Activities that Locales Affect.
LC_CTYPE
`locale.h' (ISO): section Categories of Activities that Locales Affect.
LC_MESSAGES
`locale.h' (XOPEN): section Categories of Activities that Locales Affect.
LC_MONETARY
`locale.h' (ISO): section Categories of Activities that Locales Affect.
LC_NUMERIC
`locale.h' (ISO): section Categories of Activities that Locales Affect.
void lcong48 (unsigned short int param[7])
`stdlib.h' (SVID): section SVID Random Number Function.
int lcong48_r (unsigned short int param[7], struct drand48_data *buffer)
`stdlib.h' (GNU): section SVID Random Number Function.
int L_ctermid
`stdio.h' (POSIX.1): section Identifying the Controlling Terminal.
LC_TIME
`locale.h' (ISO): section Categories of Activities that Locales Affect.
int L_cuserid
`stdio.h' (POSIX.1): section Identifying Who Logged In.
double ldexp (double value, int exponent)
`math.h' (ISO): section Normalization Functions.
float ldexpf (float value, int exponent)
`math.h' (ISO): section Normalization Functions.
long double ldexpl (long double value, int exponent)
`math.h' (ISO): section Normalization Functions.
ldiv_t ldiv (long int numerator, long int denominator)
`stdlib.h' (ISO): section Integer Division.
ldiv_t
`stdlib.h' (ISO): section Integer Division.
void * lfind (const void *key, void *base, size_t *nmemb, size_t size, comparison_fn_t compar)
`search.h' (SVID): section Array Search Function.
double lgamma (double x)
`math.h' (SVID): section Special Functions.
float lgammaf (float x)
`math.h' (SVID): section Special Functions.
float lgammaf_r (float x, int *signp)
`math.h' (XPG): section Special Functions.
long double lgammal (long double x)
`math.h' (SVID): section Special Functions.
long double lgammal_r (long double x, int *signp)
`math.h' (XPG): section Special Functions.
double lgamma_r (double x, int *signp)
`math.h' (XPG): section Special Functions.
L_INCR
`sys/file.h' (BSD): section File Positioning.
int LINE_MAX
`limits.h' (POSIX.2): section Utility Program Capacity Limits.
int link (const char *oldname, const char *newname)
`unistd.h' (POSIX.1): section Hard Links.
int LINK_MAX
`limits.h' (POSIX.1): section Limits on File System Capacity.
int lio_listio (int mode, struct aiocb *const list[], int nent, struct sigevent *sig)
`aio.h' (POSIX.1b): section Asynchronous Read and Write Operations.
int lio_listio64 (int mode, struct aiocb *const list, int nent, struct sigevent *sig)
`aio.h' (Unix98): section Asynchronous Read and Write Operations.
int listen (int socket, unsigned int n)
`sys/socket.h' (BSD): section Listening for Connections.
long long int llabs (long long int number)
`stdlib.h' (ISO): section Absolute Value.
lldiv_t lldiv (long long int numerator, long long int denominator)
`stdlib.h' (ISO): section Integer Division.
lldiv_t
`stdlib.h' (ISO): section Integer Division.
long long int llrint (double x)
`math.h' (ISO): section Rounding Functions.
long long int llrintf (float x)
`math.h' (ISO): section Rounding Functions.
long long int llrintl (long double x)
`math.h' (ISO): section Rounding Functions.
long long int llround (double x)
`math.h' (ISO): section Rounding Functions.
long long int llroundf (float x)
`math.h' (ISO): section Rounding Functions.
long long int llroundl (long double x)
`math.h' (ISO): section Rounding Functions.
struct lconv * localeconv (void)
`locale.h' (ISO): section localeconv: It is portable but ....
struct tm * localtime (const time_t *time)
`time.h' (ISO): section Broken-down Time.
struct tm * localtime_r (const time_t *time, struct tm *resultp)
`time.h' (POSIX.1c): section Broken-down Time.
double log (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
double log10 (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float log10f (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
long double log10l (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
double log1p (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float log1pf (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
long double log1pl (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
double log2 (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float log2f (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
long double log2l (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
double logb (double x)
`math.h' (BSD): section Normalization Functions.
double logb (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float logbf (float x)
`math.h' (BSD): section Normalization Functions.
float logbf (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
long double logbl (long double x)
`math.h' (BSD): section Normalization Functions.
long double logbl (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float logf (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
void login (const struct utmp *entry)
`utmp.h' (BSD): section Logging In and Out.
LOGIN_PROCESS
`utmp.h' (SVID): section Manipulating the User Accounting Database.
LOGIN_PROCESS
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
int login_tty (int filedes)
`utmp.h' (BSD): section Logging In and Out.
long double logl (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
int logout (const char *ut_line)
`utmp.h' (BSD): section Logging In and Out.
void logwtmp (const char *ut_line, const char *ut_name, const char *ut_host)
`utmp.h' (BSD): section Logging In and Out.
void longjmp (jmp_buf state, int value)
`setjmp.h' (ISO): section Details of Non-Local Exits.
LONG_LONG_MAX
`limits.h' (GNU): section Range of an Integer Type.
LONG_LONG_MIN
`limits.h' (GNU): section Range of an Integer Type.
LONG_MAX
`limits.h' (ISO): section Range of an Integer Type.
LONG_MIN
`limits.h' (ISO): section Range of an Integer Type.
long int lrand48 (void)
`stdlib.h' (SVID): section SVID Random Number Function.
int lrand48_r (struct drand48_data *buffer, double *result)
`stdlib.h' (GNU): section SVID Random Number Function.
long int lrint (double x)
`math.h' (ISO): section Rounding Functions.
long int lrintf (float x)
`math.h' (ISO): section Rounding Functions.
long int lrintl (long double x)
`math.h' (ISO): section Rounding Functions.
long int lround (double x)
`math.h' (ISO): section Rounding Functions.
long int lroundf (float x)
`math.h' (ISO): section Rounding Functions.
long int lroundl (long double x)
`math.h' (ISO): section Rounding Functions.
void * lsearch (const void *key, void *base, size_t *nmemb, size_t size, comparison_fn_t compar)
`search.h' (SVID): section Array Search Function.
off_t lseek (int filedes, off_t offset, int whence)
`unistd.h' (POSIX.1): section Setting the File Position of a Descriptor.
off64_t lseek64 (int filedes, off64_t offset, int whence)
`unistd.h' (Unix98): section Setting the File Position of a Descriptor.
L_SET
`sys/file.h' (BSD): section File Positioning.
int lstat (const char *filename, struct stat *buf)
`sys/stat.h' (BSD): section Reading the Attributes of a File.
int lstat64 (const char *filename, struct stat64 *buf)
`sys/stat.h' (Unix98): section Reading the Attributes of a File.
int L_tmpnam
`stdio.h' (ISO): section Temporary Files.
L_XTND
`sys/file.h' (BSD): section File Positioning.
void makecontext (ucontext_t *ucp, void (*func) (void), int argc, ...)
`ucontext.h' (SVID): section Complete Context Control.
struct mallinfo mallinfo (void)
`malloc.h' (SVID): section Statistics for Memory Allocation with malloc.
void * malloc (size_t size)
`malloc.h', `stdlib.h' (ISO): section Basic Memory Allocation.
__malloc_hook
`malloc.h' (GNU): section Memory Allocation Hooks.
__malloc_initialize_hook
`malloc.h' (GNU): section Memory Allocation Hooks.
int MAX_CANON
`limits.h' (POSIX.1): section Limits on File System Capacity.
int MAX_INPUT
`limits.h' (POSIX.1): section Limits on File System Capacity.
int MAXNAMLEN
`dirent.h' (BSD): section Limits on File System Capacity.
int MAXSYMLINKS
`sys/param.h' (BSD): section Symbolic Links.
int MB_CUR_MAX
`stdlib.h' (ISO): section Selecting the conversion and its properties.
int mblen (const char *string, size_t size)
`stdlib.h' (ISO): section Non-reentrant Conversion of Single Characters.
int MB_LEN_MAX
`limits.h' (ISO): section Selecting the conversion and its properties.
size_t mbrlen (const char *restrict s, size_t n, mbstate_t *ps)
`wchar.h' (ISO): section Converting Single Characters.
size_t mbrtowc (wchar_t *restrict pwc, const char *restrict s, size_t n, mbstate_t *restrict ps)
`wchar.h' (ISO): section Converting Single Characters.
int mbsinit (const mbstate_t *ps)
`wchar.h' (ISO): section Representing the state of the conversion.
size_t mbsnrtowcs (wchar_t *restrict dst, const char **restrict src, size_t nmc, size_t len, mbstate_t *restrict ps)
`wchar.h' (GNU): section Converting Multibyte and Wide Character Strings.
size_t mbsrtowcs (wchar_t *restrict dst, const char **restrict src, size_t len, mbstate_t *restrict ps)
`wchar.h' (ISO): section Converting Multibyte and Wide Character Strings.
mbstate_t
`wchar.h' (ISO): section Representing the state of the conversion.
size_t mbstowcs (wchar_t *wstring, const char *string, size_t size)
`stdlib.h' (ISO): section Non-reentrant Conversion of Strings.
int mbtowc (wchar_t *restrict result, const char *restrict string, size_t size)
`stdlib.h' (ISO): section Non-reentrant Conversion of Single Characters.
int mcheck (void (*abortfn) (enum mcheck_status status))
`mcheck.h' (GNU): section Heap Consistency Checking.
tcflag_t MDMBUF
`termios.h' (BSD): section Control Modes.
void * memalign (size_t boundary, size_t size)
`malloc.h', `stdlib.h' (BSD): section Allocating Aligned Memory Blocks.
__memalign_hook
`malloc.h' (GNU): section Memory Allocation Hooks.
void * memccpy (void *restrict to, const void *restrict from, int c, size_t size)
`string.h' (SVID): section Copying and Concatenation.
void * memchr (const void *block, int c, size_t size)
`string.h' (ISO): section Search Functions.
int memcmp (const void *a1, const void *a2, size_t size)
`string.h' (ISO): section String/Array Comparison.
void * memcpy (void *restrict to, const void *restrict from, size_t size)
`string.h' (ISO): section Copying and Concatenation.
void * memfrob (void *mem, size_t length)
`string.h' (GNU): section Trivial Encryption.
void * memmem (const void *haystack, size_t haystack-len,
const void *needle, size_t needle-len)
`string.h' (GNU): section Search Functions.
void * memmove (void *to, const void *from, size_t size)
`string.h' (ISO): section Copying and Concatenation.
void * mempcpy (void *restrict to, const void *restrict from, size_t size)
`string.h' (GNU): section Copying and Concatenation.
void * memrchr (const void *block, int c, size_t size)
`string.h' (GNU): section Search Functions.
void * memset (void *block, int c, size_t size)
`string.h' (ISO): section Copying and Concatenation.
int mkdir (const char *filename, mode_t mode)
`sys/stat.h' (POSIX.1): section Creating Directories.
char * mkdtemp (char *template)
`stdlib.h' (BSD): section Temporary Files.
int mkfifo (const char *filename, mode_t mode)
`sys/stat.h' (POSIX.1): section FIFO Special Files.
int mknod (const char *filename, int mode, int dev)
`sys/stat.h' (BSD): section Making Special Files.
int mkstemp (char *template)
`stdlib.h' (BSD): section Temporary Files.
char * mktemp (char *template)
`stdlib.h' (Unix): section Temporary Files.
time_t mktime (struct tm *brokentime)
`time.h' (ISO): section Broken-down Time.
int mlock (const void *addr, size_t len)
`sys/mman.h' (POSIX.1b): section Functions To Lock And Unlock Pages.
int mlockall (int flags)
`sys/mman.h' (POSIX.1b): section Functions To Lock And Unlock Pages.
void * mmap (void *address, size_t length,int protect, int flags, int filedes, off_t offset)
`sys/mman.h' (POSIX): section Memory-mapped I/O.
void * mmap64 (void *address, size_t length,int protect, int flags, int filedes, off64_t offset)
`sys/mman.h' (LFS): section Memory-mapped I/O.
mode_t
`sys/types.h' (POSIX.1): section The meaning of the File Attributes.
double modf (double value, double *integer-part)
`math.h' (ISO): section Rounding Functions.
float modff (float value, float *integer-part)
`math.h' (ISO): section Rounding Functions.
long double modfl (long double value, long double *integer-part)
`math.h' (ISO): section Rounding Functions.
int mount (const char *special_file, const char *dir, const char *fstype, unsigned long int options, const void *data)
`sys/mount.h' (SVID, BSD): section Mount, Unmount, Remount.
long int mrand48 (void)
`stdlib.h' (SVID): section SVID Random Number Function.
int mrand48_r (struct drand48_data *buffer, double *result)
`stdlib.h' (GNU): section SVID Random Number Function.
void * mremap (void *address, size_t length, size_t new_length, int flag)
`sys/mman.h' (GNU): section Memory-mapped I/O.
int MSG_DONTROUTE
`sys/socket.h' (BSD): section Socket Data Options.
int MSG_OOB
`sys/socket.h' (BSD): section Socket Data Options.
int MSG_PEEK
`sys/socket.h' (BSD): section Socket Data Options.
int msync (void *address, size_t length, int flags)
`sys/mman.h' (POSIX): section Memory-mapped I/O.
void mtrace (void)
`mcheck.h' (GNU): section How to install the tracing functionality.
int munlock (const void *addr, size_t len)
`sys/mman.h' (POSIX.1b): section Functions To Lock And Unlock Pages.
int munlockall (void)
`sys/mman.h' (POSIX.1b): section Functions To Lock And Unlock Pages.
int munmap (void *addr, size_t length)
`sys/mman.h' (POSIX): section Memory-mapped I/O.
void muntrace (void)
`mcheck.h' (GNU): section How to install the tracing functionality.
int NAME_MAX
`limits.h' (POSIX.1): section Limits on File System Capacity.
float NAN
`math.h' (GNU): section Infinity and NaN.
double nan (const char *tagp)
`math.h' (ISO): section Setting and modifying single bits of FP values.
float nanf (const char *tagp)
`math.h' (ISO): section Setting and modifying single bits of FP values.
long double nanl (const char *tagp)
`math.h' (ISO): section Setting and modifying single bits of FP values.
int nanosleep (const struct timespec *requested_time, struct timespec *remaining)
`time.h' (POSIX.1): section Sleeping.
int NCCS
`termios.h' (POSIX.1): section Terminal Mode Data Types.
double nearbyint (double x)
`math.h' (ISO): section Rounding Functions.
float nearbyintf (float x)
`math.h' (ISO): section Rounding Functions.
long double nearbyintl (long double x)
`math.h' (ISO): section Rounding Functions.
NEW_TIME
`utmp.h' (SVID): section Manipulating the User Accounting Database.
NEW_TIME
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
double nextafter (double x, double y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
float nextafterf (float x, float y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
long double nextafterl (long double x, long double y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
double nexttoward (double x, long double y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
float nexttowardf (float x, long double y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
long double nexttowardl (long double x, long double y)
`math.h' (ISO): section Setting and modifying single bits of FP values.
int nftw (const char *filename, __nftw_func_t func, int descriptors, int flag)
`ftw.h' (XPG4.2): section Working with Directory Trees.
int nftw64 (const char *filename, __nftw64_func_t func, int descriptors, int flag)
`ftw.h' (Unix98): section Working with Directory Trees.
__nftw64_func_t
`ftw.h' (GNU): section Working with Directory Trees.
__nftw_func_t
`ftw.h' (GNU): section Working with Directory Trees.
char * ngettext (const char *msgid1, const char *msgid2, unsigned long int n)
`libintl.h' (GNU): section Additional functions for more complicated situations.
int NGROUPS_MAX
`limits.h' (POSIX.1): section General Capacity Limits.
int nice (int increment)
`unistd.h' (BSD): section Functions For Traditional Scheduling.
nlink_t
`sys/types.h' (POSIX.1): section The meaning of the File Attributes.
char * nl_langinfo (nl_item item)
`langinfo.h' (XOPEN): section Pinpoint Access to Locale Data.
NO_ADDRESS
`netdb.h' (BSD): section Host Names.
tcflag_t NOFLSH
`termios.h' (POSIX.1): section Local Modes.
tcflag_t NOKERNINFO
`termios.h' (BSD): section Local Modes.
NO_RECOVERY
`netdb.h' (BSD): section Host Names.
long int nrand48 (unsigned short int xsubi[3])
`stdlib.h' (SVID): section SVID Random Number Function.
int nrand48_r (unsigned short int xsubi[3], struct drand48_data *buffer, long int *result)
`stdlib.h' (GNU): section SVID Random Number Function.
int NSIG
`signal.h' (BSD): section Standard Signals.
uint32_t ntohl (uint32_t netlong)
`netinet/in.h' (BSD): section Byte Order Conversion.
uint16_t ntohs (uint16_t netshort)
`netinet/in.h' (BSD): section Byte Order Conversion.
int ntp_adjtime (struct timex *tptr)
`sys/timex.h' (GNU): section High Accuracy Clock.
int ntp_gettime (struct ntptimeval *tptr)
`sys/timex.h' (GNU): section High Accuracy Clock.
void * NULL
`stddef.h' (ISO): section Null Pointer Constant.
int O_ACCMODE
`fcntl.h' (POSIX.1): section File Access Modes.
int O_APPEND
`fcntl.h' (POSIX.1): section I/O Operating Modes.
int O_ASYNC
`fcntl.h' (BSD): section I/O Operating Modes.
void obstack_1grow (struct obstack *obstack-ptr, char c)
`obstack.h' (GNU): section Growing Objects.
void obstack_1grow_fast (struct obstack *obstack-ptr, char c)
`obstack.h' (GNU): section Extra Fast Growing Objects.
int obstack_alignment_mask (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Alignment of Data in Obstacks.
void * obstack_alloc (struct obstack *obstack-ptr, int size)
`obstack.h' (GNU): section Allocation in an Obstack.
obstack_alloc_failed_handler
`obstack.h' (GNU): section Preparing for Using Obstacks.
void * obstack_base (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Status of an Obstack.
void obstack_blank (struct obstack *obstack-ptr, int size)
`obstack.h' (GNU): section Growing Objects.
void obstack_blank_fast (struct obstack *obstack-ptr, int size)
`obstack.h' (GNU): section Extra Fast Growing Objects.
int obstack_chunk_size (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Obstack Chunks.
void * obstack_copy (struct obstack *obstack-ptr, void *address, int size)
`obstack.h' (GNU): section Allocation in an Obstack.
void * obstack_copy0 (struct obstack *obstack-ptr, void *address, int size)
`obstack.h' (GNU): section Allocation in an Obstack.
void * obstack_finish (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Growing Objects.
void obstack_free (struct obstack *obstack-ptr, void *object)
`obstack.h' (GNU): section Freeing Objects in an Obstack.
void obstack_grow (struct obstack *obstack-ptr, void *data, int size)
`obstack.h' (GNU): section Growing Objects.
void obstack_grow0 (struct obstack *obstack-ptr, void *data, int size)
`obstack.h' (GNU): section Growing Objects.
int obstack_init (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Preparing for Using Obstacks.
void obstack_int_grow (struct obstack *obstack-ptr, int data)
`obstack.h' (GNU): section Growing Objects.
void obstack_int_grow_fast (struct obstack *obstack-ptr, int data)
`obstack.h' (GNU): section Extra Fast Growing Objects.
void * obstack_next_free (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Status of an Obstack.
int obstack_object_size (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Growing Objects.
int obstack_object_size (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Status of an Obstack.
int obstack_printf (struct obstack *obstack, const char *template, ...)
`stdio.h' (GNU): section Dynamically Allocating Formatted Output.
void obstack_ptr_grow (struct obstack *obstack-ptr, void *data)
`obstack.h' (GNU): section Growing Objects.
void obstack_ptr_grow_fast (struct obstack *obstack-ptr, void *data)
`obstack.h' (GNU): section Extra Fast Growing Objects.
int obstack_room (struct obstack *obstack-ptr)
`obstack.h' (GNU): section Extra Fast Growing Objects.
int obstack_vprintf (struct obstack *obstack, const char *template, va_list ap)
`stdio.h' (GNU): section Variable Arguments Output Functions.
int O_CREAT
`fcntl.h' (POSIX.1): section Open-time Flags.
int O_EXCL
`fcntl.h' (POSIX.1): section Open-time Flags.
int O_EXEC
`fcntl.h' (GNU): section File Access Modes.
int O_EXLOCK
`fcntl.h' (BSD): section Open-time Flags.
off64_t
`sys/types.h' (Unix98): section Setting the File Position of a Descriptor.
size_t offsetof (type, member)
`stddef.h' (ISO): section Structure Field Offset Measurement.
off_t
`sys/types.h' (POSIX.1): section Setting the File Position of a Descriptor.
int O_FSYNC
`fcntl.h' (BSD): section I/O Operating Modes.
int O_IGNORE_CTTY
`fcntl.h' (GNU): section Open-time Flags.
OLD_TIME
`utmp.h' (SVID): section Manipulating the User Accounting Database.
OLD_TIME
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
int O_NDELAY
`fcntl.h' (BSD): section I/O Operating Modes.
int on_exit (void (*function)(int status, void *arg), void *arg)
`stdlib.h' (SunOS): section Cleanups on Exit.
tcflag_t ONLCR
`termios.h' (BSD): section Output Modes.
int O_NOATIME
`fcntl.h' (GNU): section I/O Operating Modes.
int O_NOCTTY
`fcntl.h' (POSIX.1): section Open-time Flags.
tcflag_t ONOEOT
`termios.h' (BSD): section Output Modes.
int O_NOLINK
`fcntl.h' (GNU): section Open-time Flags.
int O_NONBLOCK
`fcntl.h' (POSIX.1): section Open-time Flags.
int O_NONBLOCK
`fcntl.h' (POSIX.1): section I/O Operating Modes.
int O_NOTRANS
`fcntl.h' (GNU): section Open-time Flags.
int open (const char *filename, int flags[, mode_t mode])
`fcntl.h' (POSIX.1): section Opening and Closing Files.
int open64 (const char *filename, int flags[, mode_t mode])
`fcntl.h' (Unix98): section Opening and Closing Files.
DIR * opendir (const char *dirname)
`dirent.h' (POSIX.1): section Opening a Directory Stream.
void openlog (char *ident, int option,
`syslog.h' (BSD): section openlog.
int OPEN_MAX
`limits.h' (POSIX.1): section General Capacity Limits.
FILE * open_memstream (char **ptr, size_t *sizeloc)
`stdio.h' (GNU): section String Streams.
FILE * open_obstack_stream (struct obstack *obstack)
`stdio.h' (GNU): section Obstack Streams.
int openpty (int *amaster, int *aslave, char *name, struct termios *termp, struct winsize *winp)
`pty.h' (BSD): section Opening a Pseudo-Terminal Pair.
tcflag_t OPOST
`termios.h' (POSIX.1): section Output Modes.
char * optarg
`unistd.h' (POSIX.2): section Using the getopt function.
int opterr
`unistd.h' (POSIX.2): section Using the getopt function.
int optind
`unistd.h' (POSIX.2): section Using the getopt function.
OPTION_ALIAS
`argp.h' (GNU): section Flags for Argp Options.
OPTION_ARG_OPTIONAL
`argp.h' (GNU): section Flags for Argp Options.
OPTION_DOC
`argp.h' (GNU): section Flags for Argp Options.
OPTION_HIDDEN
`argp.h' (GNU): section Flags for Argp Options.
OPTION_NO_USAGE
`argp.h' (GNU): section Flags for Argp Options.
int optopt
`unistd.h' (POSIX.2): section Using the getopt function.
int O_RDONLY
`fcntl.h' (POSIX.1): section File Access Modes.
int O_RDWR
`fcntl.h' (POSIX.1): section File Access Modes.
int O_READ
`fcntl.h' (GNU): section File Access Modes.
int O_SHLOCK
`fcntl.h' (BSD): section Open-time Flags.
int O_SYNC
`fcntl.h' (BSD): section I/O Operating Modes.
int O_TRUNC
`fcntl.h' (POSIX.1): section Open-time Flags.
int O_WRITE
`fcntl.h' (GNU): section File Access Modes.
int O_WRONLY
`fcntl.h' (POSIX.1): section File Access Modes.
tcflag_t OXTABS
`termios.h' (BSD): section Output Modes.
PA_CHAR
`printf.h' (GNU): section Parsing a Template String.
PA_DOUBLE
`printf.h' (GNU): section Parsing a Template String.
PA_FLAG_LONG
`printf.h' (GNU): section Parsing a Template String.
PA_FLAG_LONG_DOUBLE
`printf.h' (GNU): section Parsing a Template String.
PA_FLAG_LONG_LONG
`printf.h' (GNU): section Parsing a Template String.
int PA_FLAG_MASK
`printf.h' (GNU): section Parsing a Template String.
PA_FLAG_PTR
`printf.h' (GNU): section Parsing a Template String.
PA_FLAG_SHORT
`printf.h' (GNU): section Parsing a Template String.
PA_FLOAT
`printf.h' (GNU): section Parsing a Template String.
PA_INT
`printf.h' (GNU): section Parsing a Template String.
PA_LAST
`printf.h' (GNU): section Parsing a Template String.
PA_POINTER
`printf.h' (GNU): section Parsing a Template String.
tcflag_t PARENB
`termios.h' (POSIX.1): section Control Modes.
tcflag_t PARMRK
`termios.h' (POSIX.1): section Input Modes.
tcflag_t PARODD
`termios.h' (POSIX.1): section Control Modes.
size_t parse_printf_format (const char *template, size_t n, int *argtypes)
`printf.h' (GNU): section Parsing a Template String.
PA_STRING
`printf.h' (GNU): section Parsing a Template String.
long int pathconf (const char *filename, int parameter)
`unistd.h' (POSIX.1): section Using pathconf.
int PATH_MAX
`limits.h' (POSIX.1): section Limits on File System Capacity.
int pause ()
`unistd.h' (POSIX.1): section Using pause.
_PC_ASYNC_IO
`unistd.h' (POSIX.1): section Using pathconf.
_PC_CHOWN_RESTRICTED
`unistd.h' (POSIX.1): section Using pathconf.
_PC_FILESIZEBITS
`unistd.h' (LFS): section Using pathconf.
_PC_LINK_MAX
`unistd.h' (POSIX.1): section Using pathconf.
int pclose (FILE *stream)
`stdio.h' (POSIX.2, SVID, BSD): section Pipe to a Subprocess.
_PC_MAX_CANON
`unistd.h' (POSIX.1): section Using pathconf.
_PC_MAX_INPUT
`unistd.h' (POSIX.1): section Using pathconf.
_PC_NAME_MAX
`unistd.h' (POSIX.1): section Using pathconf.
_PC_NO_TRUNC
`unistd.h' (POSIX.1): section Using pathconf.
_PC_PATH_MAX
`unistd.h' (POSIX.1): section Using pathconf.
_PC_PIPE_BUF
`unistd.h' (POSIX.1): section Using pathconf.
_PC_PRIO_IO
`unistd.h' (POSIX.1): section Using pathconf.
_PC_REC_INCR_XFER_SIZE
`unistd.h' (POSIX.1): section Using pathconf.
_PC_REC_MAX_XFER_SIZE
`unistd.h' (POSIX.1): section Using pathconf.
_PC_REC_MIN_XFER_SIZE
`unistd.h' (POSIX.1): section Using pathconf.
_PC_REC_XFER_ALIGN
`unistd.h' (POSIX.1): section Using pathconf.
_PC_SOCK_MAXBUF
`unistd.h' (POSIX.1g): section Using pathconf.
_PC_SYNC_IO
`unistd.h' (POSIX.1): section Using pathconf.
_PC_VDISABLE
`unistd.h' (POSIX.1): section Using pathconf.
tcflag_t PENDIN
`termios.h' (BSD): section Local Modes.
void perror (const char *message)
`stdio.h' (ISO): section Error Messages.
int PF_FILE
`sys/socket.h' (GNU): section Details of Local Namespace.
int PF_INET
`sys/socket.h' (BSD): section The Internet Namespace.
int PF_INET6
`sys/socket.h' (X/Open): section The Internet Namespace.
int PF_LOCAL
`sys/socket.h' (POSIX): section Details of Local Namespace.
int PF_UNIX
`sys/socket.h' (BSD): section Details of Local Namespace.
pid_t
`sys/types.h' (POSIX.1): section Process Identification.
int pipe (int filedes[2])
`unistd.h' (POSIX.1): section Creating a Pipe.
int PIPE_BUF
`limits.h' (POSIX.1): section Limits on File System Capacity.
FILE * popen (const char *command, const char *mode)
`stdio.h' (POSIX.2, SVID, BSD): section Pipe to a Subprocess.
_POSIX2_BC_BASE_MAX
`limits.h' (POSIX.2): section Minimum Values for Utility Limits.
_POSIX2_BC_DIM_MAX
`limits.h' (POSIX.2): section Minimum Values for Utility Limits.
_POSIX2_BC_SCALE_MAX
`limits.h' (POSIX.2): section Minimum Values for Utility Limits.
_POSIX2_BC_STRING_MAX
`limits.h' (POSIX.2): section Minimum Values for Utility Limits.
int _POSIX2_C_DEV
`unistd.h' (POSIX.2): section Overall System Options.
_POSIX2_COLL_WEIGHTS_MAX
`limits.h' (POSIX.2): section Minimum Values for Utility Limits.
long int _POSIX2_C_VERSION
`unistd.h' (POSIX.2): section Which Version of POSIX is Supported.
_POSIX2_EQUIV_CLASS_MAX
`limits.h' (POSIX.2): section Minimum Values for Utility Limits.
_POSIX2_EXPR_NEST_MAX
`limits.h' (POSIX.2): section Minimum Values for Utility Limits.
int _POSIX2_FORT_DEV
`unistd.h' (POSIX.2): section Overall System Options.
int _POSIX2_FORT_RUN
`unistd.h' (POSIX.2): section Overall System Options.
_POSIX2_LINE_MAX
`limits.h' (POSIX.2): section Minimum Values for Utility Limits.
int _POSIX2_LOCALEDEF
`unistd.h' (POSIX.2): section Overall System Options.
_POSIX2_RE_DUP_MAX
`limits.h' (POSIX.2): section Minimum Values for General Capacity Limits.
int _POSIX2_SW_DEV
`unistd.h' (POSIX.2): section Overall System Options.
_POSIX_AIO_LISTIO_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
_POSIX_AIO_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
_POSIX_ARG_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
_POSIX_CHILD_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
int _POSIX_CHOWN_RESTRICTED
`unistd.h' (POSIX.1): section Optional Features in File Support.
_POSIX_C_SOURCE
(POSIX.2): section Feature Test Macros.
int _POSIX_JOB_CONTROL
`unistd.h' (POSIX.1): section Overall System Options.
_POSIX_LINK_MAX
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
_POSIX_MAX_CANON
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
_POSIX_MAX_INPUT
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
int posix_memalign (void **memptr, size_t alignment, size_t size)
`stdlib.h' (POSIX): section Allocating Aligned Memory Blocks.
_POSIX_NAME_MAX
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
_POSIX_NGROUPS_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
int _POSIX_NO_TRUNC
`unistd.h' (POSIX.1): section Optional Features in File Support.
_POSIX_OPEN_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
_POSIX_PATH_MAX
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
_POSIX_PIPE_BUF
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
POSIX_REC_INCR_XFER_SIZE
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
POSIX_REC_MAX_XFER_SIZE
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
POSIX_REC_MIN_XFER_SIZE
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
POSIX_REC_XFER_ALIGN
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
int _POSIX_SAVED_IDS
`unistd.h' (POSIX.1): section Overall System Options.
_POSIX_SOURCE
(POSIX.1): section Feature Test Macros.
_POSIX_SSIZE_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
_POSIX_STREAM_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
_POSIX_TZNAME_MAX
`limits.h' (POSIX.1): section Minimum Values for General Capacity Limits.
unsigned char _POSIX_VDISABLE
`unistd.h' (POSIX.1): section Optional Features in File Support.
long int _POSIX_VERSION
`unistd.h' (POSIX.1): section Which Version of POSIX is Supported.
double pow (double base, double power)
`math.h' (ISO): section Exponentiation and Logarithms.
double pow10 (double x)
`math.h' (GNU): section Exponentiation and Logarithms.
float pow10f (float x)
`math.h' (GNU): section Exponentiation and Logarithms.
long double pow10l (long double x)
`math.h' (GNU): section Exponentiation and Logarithms.
float powf (float base, float power)
`math.h' (ISO): section Exponentiation and Logarithms.
long double powl (long double base, long double power)
`math.h' (ISO): section Exponentiation and Logarithms.
ssize_t pread (int filedes, void *buffer, size_t size, off_t offset)
`unistd.h' (Unix98): section Input and Output Primitives.
ssize_t pread64 (int filedes, void *buffer, size_t size, off64_t offset)
`unistd.h' (Unix98): section Input and Output Primitives.
int printf (const char *template, ...)
`stdio.h' (ISO): section Formatted Output Functions.
printf_arginfo_function
`printf.h' (GNU): section Defining the Output Handler.
printf_function
`printf.h' (GNU): section Defining the Output Handler.
int printf_size (FILE *fp, const struct printf_info *info, const void *const *args)
`printf.h' (GNU): section Predefined printf Handlers.
int printf_size_info (const struct printf_info *info, size_t n, int *argtypes)
`printf.h' (GNU): section Predefined printf Handlers.
PRIO_MAX
`sys/resource.h' (BSD): section Functions For Traditional Scheduling.
PRIO_MIN
`sys/resource.h' (BSD): section Functions For Traditional Scheduling.
PRIO_PGRP
`sys/resource.h' (BSD): section Functions For Traditional Scheduling.
PRIO_PROCESS
`sys/resource.h' (BSD): section Functions For Traditional Scheduling.
PRIO_USER
`sys/resource.h' (BSD): section Functions For Traditional Scheduling.
char * program_invocation_name
`errno.h' (GNU): section Error Messages.
char * program_invocation_short_name
`errno.h' (GNU): section Error Messages.
void psignal (int signum, const char *message)
`signal.h' (BSD): section Signal Messages.
char * P_tmpdir
`stdio.h' (SVID): section Temporary Files.
ptrdiff_t
`stddef.h' (ISO): section Important Data Types.
char * ptsname (int filedes)
`stdlib.h' (SVID, XPG4.2): section Allocating Pseudo-Terminals.
int ptsname_r (int filedes, char *buf, size_t len)
`stdlib.h' (GNU): section Allocating Pseudo-Terminals.
int putc (int c, FILE *stream)
`stdio.h' (ISO): section Simple Output by Characters or Lines.
int putchar (int c)
`stdio.h' (ISO): section Simple Output by Characters or Lines.
int putchar_unlocked (int c)
`stdio.h' (POSIX): section Simple Output by Characters or Lines.
int putc_unlocked (int c, FILE *stream)
`stdio.h' (POSIX): section Simple Output by Characters or Lines.
int putenv (char *string)
`stdlib.h' (SVID): section Environment Access.
int putpwent (const struct passwd *p, FILE *stream)
`pwd.h' (SVID): section Writing a User Entry.
int puts (const char *s)
`stdio.h' (ISO): section Simple Output by Characters or Lines.
struct utmp * pututline (const struct utmp *utmp)
`utmp.h' (SVID): section Manipulating the User Accounting Database.
struct utmpx * pututxline (const struct utmpx *utmp)
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
int putw (int w, FILE *stream)
`stdio.h' (SVID): section Simple Output by Characters or Lines.
wint_t putwc (wchar_t wc, FILE *stream)
`wchar.h' (ISO): section Simple Output by Characters or Lines.
wint_t putwchar (wchar_t wc)
`wchar.h' (ISO): section Simple Output by Characters or Lines.
wint_t putwchar_unlocked (wchar_t wc)
`wchar.h' (GNU): section Simple Output by Characters or Lines.
wint_t putwc_unlocked (wchar_t wc, FILE *stream)
`wchar.h' (GNU): section Simple Output by Characters or Lines.
ssize_t pwrite (int filedes, const void *buffer, size_t size, off_t offset)
`unistd.h' (Unix98): section Input and Output Primitives.
ssize_t pwrite64 (int filedes, const void *buffer, size_t size, off64_t offset)
`unistd.h' (Unix98): section Input and Output Primitives.
char * qecvt (long double value, int ndigit, int *decpt, int *neg)
`stdlib.h' (GNU): section Old-fashioned System V number-to-string functions.
char * qecvt_r (long double value, int ndigit, int *decpt, int *neg, char *buf, size_t len)
`stdlib.h' (GNU): section Old-fashioned System V number-to-string functions.
char * qfcvt (long double value, int ndigit, int *decpt, int *neg)
`stdlib.h' (GNU): section Old-fashioned System V number-to-string functions.
char * qfcvt_r (long double value, int ndigit, int *decpt, int *neg, char *buf, size_t len)
`stdlib.h' (GNU): section Old-fashioned System V number-to-string functions.
char * qgcvt (long double value, int ndigit, char *buf)
`stdlib.h' (GNU): section Old-fashioned System V number-to-string functions.
void qsort (void *array, size_t count, size_t size, comparison_fn_t compare)
`stdlib.h' (ISO): section Array Sort Function.
int raise (int signum)
`signal.h' (ISO): section Signaling Yourself.
int rand (void)
`stdlib.h' (ISO): section ISO C Random Number Functions.
int RAND_MAX
`stdlib.h' (ISO): section ISO C Random Number Functions.
long int random (void)
`stdlib.h' (BSD): section BSD Random Number Functions.
int random_r (struct random_data *restrict buf, int32_t *restrict result)
`stdlib.h' (GNU): section BSD Random Number Functions.
int rand_r (unsigned int *seed)
`stdlib.h' (POSIX.1): section ISO C Random Number Functions.
void * rawmemchr (const void *block, int c)
`string.h' (GNU): section Search Functions.
ssize_t read (int filedes, void *buffer, size_t size)
`unistd.h' (POSIX.1): section Input and Output Primitives.
struct dirent * readdir (DIR *dirstream)
`dirent.h' (POSIX.1): section Reading and Closing a Directory Stream.
struct dirent64 * readdir64 (DIR *dirstream)
`dirent.h' (LFS): section Reading and Closing a Directory Stream.
int readdir64_r (DIR *dirstream, struct dirent64 *entry, struct dirent64 **result)
`dirent.h' (LFS): section Reading and Closing a Directory Stream.
int readdir_r (DIR *dirstream, struct dirent *entry, struct dirent **result)
`dirent.h' (GNU): section Reading and Closing a Directory Stream.
int readlink (const char *filename, char *buffer, size_t size)
`unistd.h' (BSD): section Symbolic Links.
ssize_t readv (int filedes, const struct iovec *vector, int count)
`sys/uio.h' (BSD): section Fast Scatter-Gather I/O.
void * realloc (void *ptr, size_t newsize)
`malloc.h', `stdlib.h' (ISO): section Changing the Size of a Block.
__realloc_hook
`malloc.h' (GNU): section Memory Allocation Hooks.
char * realpath (const char *restrict name, char *restrict resolved)
`stdlib.h' (XPG): section Symbolic Links.
int recv (int socket, void *buffer, size_t size, int flags)
`sys/socket.h' (BSD): section Receiving Data.
int recvfrom (int socket, void *buffer, size_t size, int flags, struct sockaddr *addr, socklen_t *length-ptr)
`sys/socket.h' (BSD): section Receiving Datagrams.
int recvmsg (int socket, struct msghdr *message, int flags)
`sys/socket.h' (BSD): section Receiving Datagrams.
int RE_DUP_MAX
`limits.h' (POSIX.2): section General Capacity Limits.
_REENTRANT
(GNU): section Feature Test Macros.
REG_BADBR
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_BADPAT
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_BADRPT
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
int regcomp (regex_t *compiled, const char *pattern, int cflags)
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_EBRACE
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_EBRACK
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_ECOLLATE
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_ECTYPE
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_EESCAPE
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_EPAREN
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_ERANGE
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
size_t regerror (int errcode, regex_t *compiled, char *buffer, size_t length)
`regex.h' (POSIX.2): section POSIX Regexp Matching Cleanup.
REG_ESPACE
`regex.h' (POSIX.2): section Matching a Compiled POSIX Regular Expression.
REG_ESPACE
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_ESUBREG
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
int regexec (regex_t *compiled, char *string, size_t nmatch, regmatch_t matchptr [], int eflags)
`regex.h' (POSIX.2): section Matching a Compiled POSIX Regular Expression.
regex_t
`regex.h' (POSIX.2): section POSIX Regular Expression Compilation.
REG_EXTENDED
`regex.h' (POSIX.2): section Flags for POSIX Regular Expressions.
void regfree (regex_t *compiled)
`regex.h' (POSIX.2): section POSIX Regexp Matching Cleanup.
REG_ICASE
`regex.h' (POSIX.2): section Flags for POSIX Regular Expressions.
int register_printf_function (int spec, printf_function handler-function, printf_arginfo_function arginfo-function)
`printf.h' (GNU): section Registering New Conversions.
regmatch_t
`regex.h' (POSIX.2): section Match Results with Subexpressions.
REG_NEWLINE
`regex.h' (POSIX.2): section Flags for POSIX Regular Expressions.
REG_NOMATCH
`regex.h' (POSIX.2): section Matching a Compiled POSIX Regular Expression.
REG_NOSUB
`regex.h' (POSIX.2): section Flags for POSIX Regular Expressions.
REG_NOTBOL
`regex.h' (POSIX.2): section Matching a Compiled POSIX Regular Expression.
REG_NOTEOL
`regex.h' (POSIX.2): section Matching a Compiled POSIX Regular Expression.
regoff_t
`regex.h' (POSIX.2): section Match Results with Subexpressions.
double remainder (double numerator, double denominator)
`math.h' (BSD): section Remainder Functions.
float remainderf (float numerator, float denominator)
`math.h' (BSD): section Remainder Functions.
long double remainderl (long double numerator, long double denominator)
`math.h' (BSD): section Remainder Functions.
int remove (const char *filename)
`stdio.h' (ISO): section Deleting Files.
int rename (const char *oldname, const char *newname)
`stdio.h' (ISO): section Renaming Files.
void rewind (FILE *stream)
`stdio.h' (ISO): section File Positioning.
void rewinddir (DIR *dirstream)
`dirent.h' (POSIX.1): section Random Access in a Directory Stream.
char * rindex (const char *string, int c)
`string.h' (BSD): section Search Functions.
double rint (double x)
`math.h' (ISO): section Rounding Functions.
float rintf (float x)
`math.h' (ISO): section Rounding Functions.
long double rintl (long double x)
`math.h' (ISO): section Rounding Functions.
int RLIM_INFINITY
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_AS
`sys/resource.h' (Unix98): section Limiting Resource Usage.
RLIMIT_CORE
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_CPU
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_DATA
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_FSIZE
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_MEMLOCK
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_NOFILE
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_NPROC
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_RSS
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIMIT_STACK
`sys/resource.h' (BSD): section Limiting Resource Usage.
RLIM_NLIMITS
`sys/resource.h' (BSD): section Limiting Resource Usage.
int rmdir (const char *filename)
`unistd.h' (POSIX.1): section Deleting Files.
int R_OK
`unistd.h' (POSIX.1): section Testing Permission to Access a File.
double round (double x)
`math.h' (ISO): section Rounding Functions.
float roundf (float x)
`math.h' (ISO): section Rounding Functions.
long double roundl (long double x)
`math.h' (ISO): section Rounding Functions.
RUN_LVL
`utmp.h' (SVID): section Manipulating the User Accounting Database.
RUN_LVL
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
RUSAGE_CHILDREN
`sys/resource.h' (BSD): section Resource Usage.
RUSAGE_SELF
`sys/resource.h' (BSD): section Resource Usage.
int SA_NOCLDSTOP
`signal.h' (POSIX.1): section Flags for sigaction.
int SA_ONSTACK
`signal.h' (BSD): section Flags for sigaction.
int SA_RESTART
`signal.h' (BSD): section Flags for sigaction.
int sbrk (ptrdiff_t delta)
`unistd.h' (BSD): section Resizing the Data Segment.
_SC_2_C_DEV
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_2_FORT_DEV
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_2_FORT_RUN
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_2_LOCALEDEF
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_2_SW_DEV
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_2_VERSION
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_AIO_LISTIO_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_AIO_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_AIO_PRIO_DELTA_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
double scalb (double value, int exponent)
`math.h' (BSD): section Normalization Functions.
float scalbf (float value, int exponent)
`math.h' (BSD): section Normalization Functions.
long double scalbl (long double value, int exponent)
`math.h' (BSD): section Normalization Functions.
long long int scalbln (double x, long int n)
`math.h' (BSD): section Normalization Functions.
long long int scalblnf (float x, long int n)
`math.h' (BSD): section Normalization Functions.
long long int scalblnl (long double x, long int n)
`math.h' (BSD): section Normalization Functions.
long long int scalbn (double x, int n)
`math.h' (BSD): section Normalization Functions.
long long int scalbnf (float x, int n)
`math.h' (BSD): section Normalization Functions.
long long int scalbnl (long double x, int n)
`math.h' (BSD): section Normalization Functions.
int scandir (const char *dir, struct dirent ***namelist, int (*selector) (const struct dirent *), int (*cmp) (const void *, const void *))
`dirent.h' (BSD/SVID): section Scanning the Content of a Directory.
int scandir64 (const char *dir, struct dirent64 ***namelist, int (*selector) (const struct dirent64 *), int (*cmp) (const void *, const void *))
`dirent.h' (GNU): section Scanning the Content of a Directory.
int scanf (const char *template, ...)
`stdio.h' (ISO): section Formatted Input Functions.
_SC_ARG_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_ASYNCHRONOUS_IO
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_ATEXIT_MAX
`unistd.h' (GNU): section Constants for sysconf Parameters.
_SC_AVPHYS_PAGES
`unistd.h' (GNU): section Constants for sysconf Parameters.
_SC_BC_BASE_MAX
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_BC_DIM_MAX
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_BC_SCALE_MAX
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_BC_STRING_MAX
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_CHAR_BIT
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_CHARCLASS_NAME_MAX
`unistd.h' (GNU): section Constants for sysconf Parameters.
_SC_CHAR_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_CHAR_MIN
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_CHILD_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_CLK_TCK
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_COLL_WEIGHTS_MAX
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_DELAYTIMER_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_EQUIV_CLASS_MAX
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_EXPR_NEST_MAX
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_FSYNC
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_GETGR_R_SIZE_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_GETPW_R_SIZE_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
SCHAR_MAX
`limits.h' (ISO): section Range of an Integer Type.
SCHAR_MIN
`limits.h' (ISO): section Range of an Integer Type.
int sched_getparam (pid_t pid, const struct sched_param *param)
`sched.h' (POSIX): section Basic Scheduling Functions.
int sched_get_priority_max (int *policy);
`sched.h' (POSIX): section Basic Scheduling Functions.
int sched_get_priority_min (int *policy);
`sched.h' (POSIX): section Basic Scheduling Functions.
int sched_getscheduler (pid_t pid)
`sched.h' (POSIX): section Basic Scheduling Functions.
int sched_rr_get_interval (pid_t pid, struct timespec *interval)
`sched.h' (POSIX): section Basic Scheduling Functions.
int sched_setparam (pid_t pid, const struct sched_param *param)
`sched.h' (POSIX): section Basic Scheduling Functions.
int sched_setscheduler (pid_t pid, int policy, const struct sched_param *param)
`sched.h' (POSIX): section Basic Scheduling Functions.
int sched_yield (void)
`sched.h' (POSIX): section Basic Scheduling Functions.
_SC_INT_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_INT_MIN
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_JOB_CONTROL
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_LINE_MAX
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_LOGIN_NAME_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_LONG_BIT
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_MAPPED_FILES
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_MB_LEN_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_MEMLOCK
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_MEMLOCK_RANGE
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_MEMORY_PROTECTION
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_MESSAGE_PASSING
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_MQ_OPEN_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_MQ_PRIO_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_NGROUPS_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_NL_ARGMAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_NL_LANGMAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_NL_MSGMAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_NL_NMAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_NL_SETMAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_NL_TEXTMAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_NPROCESSORS_CONF
`unistd.h' (GNU): section Constants for sysconf Parameters.
_SC_NPROCESSORS_ONLN
`unistd.h' (GNU): section Constants for sysconf Parameters.
_SC_NZERO
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_OPEN_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_PAGESIZE
`unistd.h' (GNU): section Constants for sysconf Parameters.
_SC_PHYS_PAGES
`unistd.h' (GNU): section Constants for sysconf Parameters.
_SC_PII
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_INTERNET
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_INTERNET_DGRAM
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_INTERNET_STREAM
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_OSI
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_OSI_CLTS
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_OSI_COTS
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_OSI_M
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_SOCKET
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PII_XTI
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_PRIORITIZED_IO
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_PRIORITY_SCHEDULING
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_REALTIME_SIGNALS
`unistdh.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_RTSIG_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_SAVED_IDS
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_SCHAR_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_SCHAR_MIN
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_SELECT
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_SEMAPHORES
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_SEM_NSEMS_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_SEM_VALUE_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_SHARED_MEMORY_OBJECTS
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_SHRT_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_SHRT_MIN
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_SIGQUEUE_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
SC_SSIZE_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_STREAM_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_SYNCHRONIZED_IO
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_ATTR_STACKADDR
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_ATTR_STACKSIZE
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_DESTRUCTOR_ITERATIONS
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_KEYS_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_PRIO_INHERIT
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_PRIO_PROTECT
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_PRIORITY_SCHEDULING
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_PROCESS_SHARED
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREADS
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_SAFE_FUNCTIONS
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_STACK_MIN
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_THREAD_THREADS_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_TIMER_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_TIMERS
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_T_IOV_MAX
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_TTY_NAME_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_TZNAME_MAX
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_UCHAR_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_UINT_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_UIO_MAXIOV
`unistd.h' (POSIX.1g): section Constants for sysconf Parameters.
_SC_ULONG_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_USHRT_MAX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_VERSION
`unistd.h' (POSIX.1): section Constants for sysconf Parameters.
_SC_VERSION
`unistd.h' (POSIX.2): section Constants for sysconf Parameters.
_SC_WORD_BIT
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_CRYPT
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_ENH_I18N
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_LEGACY
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_REALTIME
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_REALTIME_THREADS
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_SHM
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_UNIX
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_VERSION
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_XCU_VERSION
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_XPG2
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_XPG3
`unistd.h' (X/Open): section Constants for sysconf Parameters.
_SC_XOPEN_XPG4
`unistd.h' (X/Open): section Constants for sysconf Parameters.
unsigned short int * seed48 (unsigned short int seed16v[3])
`stdlib.h' (SVID): section SVID Random Number Function.
int seed48_r (unsigned short int seed16v[3], struct drand48_data *buffer)
`stdlib.h' (GNU): section SVID Random Number Function.
int SEEK_CUR
`stdio.h' (ISO): section File Positioning.
void seekdir (DIR *dirstream, off_t pos)
`dirent.h' (BSD): section Random Access in a Directory Stream.
int SEEK_END
`stdio.h' (ISO): section File Positioning.
int SEEK_SET
`stdio.h' (ISO): section File Positioning.
int select (int nfds, fd_set *read-fds, fd_set *write-fds, fd_set *except-fds, struct timeval *timeout)
`sys/types.h' (BSD): section Waiting for Input or Output.
int send (int socket, void *buffer, size_t size, int flags)
`sys/socket.h' (BSD): section Sending Data.
int sendmsg (int socket, const struct msghdr *message, int flags)
`sys/socket.h' (BSD): section Receiving Datagrams.
int sendto (int socket, void *buffer. size_t size, int flags, struct sockaddr *addr, socklen_t length)
`sys/socket.h' (BSD): section Sending Datagrams.
void setbuf (FILE *stream, char *buf)
`stdio.h' (ISO): section Controlling Which Kind of Buffering.
void setbuffer (FILE *stream, char *buf, size_t size)
`stdio.h' (BSD): section Controlling Which Kind of Buffering.
int setcontext (const ucontext_t *ucp)
`ucontext.h' (SVID): section Complete Context Control.
int setdomainname (const char *name, size_t length)
`unistd.h' (???): section Host Identification.
int setegid (gid_t newgid)
`unistd.h' (POSIX.1): section Setting the Group IDs.
int setenv (const char *name, const char *value, int replace)
`stdlib.h' (BSD): section Environment Access.
int seteuid (uid_t neweuid)
`unistd.h' (POSIX.1): section Setting the User ID.
int setfsent (void)
`fstab.h' (BSD): section The `fstab' file.
int setgid (gid_t newgid)
`unistd.h' (POSIX.1): section Setting the Group IDs.
void setgrent (void)
`grp.h' (SVID, BSD): section Scanning the List of All Groups.
int setgroups (size_t count, gid_t *groups)
`grp.h' (BSD): section Setting the Group IDs.
void sethostent (int stayopen)
`netdb.h' (BSD): section Host Names.
int sethostid (long int id)
`unistd.h' (BSD): section Host Identification.
int sethostname (const char *name, size_t length)
`unistd.h' (BSD): section Host Identification.
int setitimer (int which, struct itimerval *new, struct itimerval *old)
`sys/time.h' (BSD): section Setting an Alarm.
int setjmp (jmp_buf state)
`setjmp.h' (ISO): section Details of Non-Local Exits.
void setkey (const char *key)
`crypt.h' (BSD, SVID): section DES Encryption.
void setkey_r (const char *key, struct crypt_data * data)
`crypt.h' (GNU): section DES Encryption.
void setlinebuf (FILE *stream)
`stdio.h' (BSD): section Controlling Which Kind of Buffering.
char * setlocale (int category, const char *locale)
`locale.h' (ISO): section How Programs Set the Locale.
int setlogmask (int mask)
`syslog.h' (BSD): section setlogmask.
FILE * setmntent (const char *file, const char *mode)
`mntent.h' (BSD): section The `mtab' file.
void setnetent (int stayopen)
`netdb.h' (BSD): section Networks Database.
int setnetgrent (const char *netgroup)
`netdb.h' (BSD): section Looking up one Netgroup.
int setpgid (pid_t pid, pid_t pgid)
`unistd.h' (POSIX.1): section Process Group Functions.
int setpgrp (pid_t pid, pid_t pgid)
`unistd.h' (BSD): section Process Group Functions.
int setpriority (int class, int id, int niceval)
`sys/resource.h' (BSD,POSIX): section Functions For Traditional Scheduling.
void setprotoent (int stayopen)
`netdb.h' (BSD): section Protocols Database.
void setpwent (void)
`pwd.h' (SVID, BSD): section Scanning the List of All Users.
int setregid (gid_t rgid, gid_t egid)
`unistd.h' (BSD): section Setting the Group IDs.
int setreuid (uid_t ruid, uid_t euid)
`unistd.h' (BSD): section Setting the User ID.
int setrlimit (int resource, const struct rlimit *rlp)
`sys/resource.h' (BSD): section Limiting Resource Usage.
int setrlimit64 (int resource, const struct rlimit64 *rlp)
`sys/resource.h' (Unix98): section Limiting Resource Usage.
void setservent (int stayopen)
`netdb.h' (BSD): section The Services Database.
pid_t setsid (void)
`unistd.h' (POSIX.1): section Process Group Functions.
int setsockopt (int socket, int level, int optname, void *optval, socklen_t optlen)
`sys/socket.h' (BSD): section Socket Option Functions.
void * setstate (void *state)
`stdlib.h' (BSD): section BSD Random Number Functions.
int setstate_r (char *restrict statebuf, struct random_data *restrict buf)
`stdlib.h' (GNU): section BSD Random Number Functions.
int settimeofday (const struct timeval *tp, const struct timezone *tzp)
`sys/time.h' (BSD): section High-Resolution Calendar.
int setuid (uid_t newuid)
`unistd.h' (POSIX.1): section Setting the User ID.
void setutent (void)
`utmp.h' (SVID): section Manipulating the User Accounting Database.
void setutxent (void)
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
int setvbuf (FILE *stream, char *buf, int mode, size_t size)
`stdio.h' (ISO): section Controlling Which Kind of Buffering.
SHRT_MAX
`limits.h' (ISO): section Range of an Integer Type.
SHRT_MIN
`limits.h' (ISO): section Range of an Integer Type.
int shutdown (int socket, int how)
`sys/socket.h' (BSD): section Closing a Socket.
S_IEXEC
`sys/stat.h' (BSD): section The Mode Bits for Access Permission.
S_IFBLK
`sys/stat.h' (BSD): section Testing the Type of a File.
S_IFCHR
`sys/stat.h' (BSD): section Testing the Type of a File.
S_IFDIR
`sys/stat.h' (BSD): section Testing the Type of a File.
S_IFIFO
`sys/stat.h' (BSD): section Testing the Type of a File.
S_IFLNK
`sys/stat.h' (BSD): section Testing the Type of a File.
int S_IFMT
`sys/stat.h' (BSD): section Testing the Type of a File.
S_IFREG
`sys/stat.h' (BSD): section Testing the Type of a File.
S_IFSOCK
`sys/stat.h' (BSD): section Testing the Type of a File.
int SIGABRT
`signal.h' (ISO): section Program Error Signals.
int sigaction (int signum, const struct sigaction *restrict action, struct sigaction *restrict old-action)
`signal.h' (POSIX.1): section Advanced Signal Handling.
int sigaddset (sigset_t *set, int signum)
`signal.h' (POSIX.1): section Signal Sets.
int SIGALRM
`signal.h' (POSIX.1): section Alarm Signals.
int sigaltstack (const stack_t *restrict stack, stack_t *restrict oldstack)
`signal.h' (XPG): section Using a Separate Signal Stack.
sig_atomic_t
`signal.h' (ISO): section Atomic Types.
SIG_BLOCK
`signal.h' (POSIX.1): section Process Signal Mask.
int sigblock (int mask)
`signal.h' (BSD): section BSD Functions for Blocking Signals.
int SIGBUS
`signal.h' (BSD): section Program Error Signals.
int SIGCHLD
`signal.h' (POSIX.1): section Job Control Signals.
int SIGCLD
`signal.h' (SVID): section Job Control Signals.
int SIGCONT
`signal.h' (POSIX.1): section Job Control Signals.
int sigdelset (sigset_t *set, int signum)
`signal.h' (POSIX.1): section Signal Sets.
int sigemptyset (sigset_t *set)
`signal.h' (POSIX.1): section Signal Sets.
int SIGEMT
`signal.h' (BSD): section Program Error Signals.
sighandler_t SIG_ERR
`signal.h' (ISO): section Basic Signal Handling.
int sigfillset (sigset_t *set)
`signal.h' (POSIX.1): section Signal Sets.
int SIGFPE
`signal.h' (ISO): section Program Error Signals.
sighandler_t
`signal.h' (GNU): section Basic Signal Handling.
int SIGHUP
`signal.h' (POSIX.1): section Termination Signals.
int SIGILL
`signal.h' (ISO): section Program Error Signals.
int SIGINFO
`signal.h' (BSD): section Miscellaneous Signals.
int SIGINT
`signal.h' (ISO): section Termination Signals.
int siginterrupt (int signum, int failflag)
`signal.h' (BSD): section BSD Function to Establish a Handler.
int SIGIO
`signal.h' (BSD): section Asynchronous I/O Signals.
int SIGIOT
`signal.h' (Unix): section Program Error Signals.
int sigismember (const sigset_t *set, int signum)
`signal.h' (POSIX.1): section Signal Sets.
sigjmp_buf
`setjmp.h' (POSIX.1): section Non-Local Exits and Signals.
int SIGKILL
`signal.h' (POSIX.1): section Termination Signals.
void siglongjmp (sigjmp_buf state, int value)
`setjmp.h' (POSIX.1): section Non-Local Exits and Signals.
int SIGLOST
`signal.h' (GNU): section Operation Error Signals.
int sigmask (int signum)
`signal.h' (BSD): section BSD Functions for Blocking Signals.
sighandler_t signal (int signum, sighandler_t action)
`signal.h' (ISO): section Basic Signal Handling.
int signbit (float-type x)
`math.h' (ISO): section Setting and modifying single bits of FP values.
long long int significand (double x)
`math.h' (BSD): section Normalization Functions.
long long int significandf (float x)
`math.h' (BSD): section Normalization Functions.
long long int significandl (long double x)
`math.h' (BSD): section Normalization Functions.
int sigpause (int mask)
`signal.h' (BSD): section BSD Functions for Blocking Signals.
int sigpending (sigset_t *set)
`signal.h' (POSIX.1): section Checking for Pending Signals.
int SIGPIPE
`signal.h' (POSIX.1): section Operation Error Signals.
int SIGPOLL
`signal.h' (SVID): section Asynchronous I/O Signals.
int sigprocmask (int how, const sigset_t *restrict set, sigset_t *restrict oldset)
`signal.h' (POSIX.1): section Process Signal Mask.
int SIGPROF
`signal.h' (BSD): section Alarm Signals.
int SIGQUIT
`signal.h' (POSIX.1): section Termination Signals.
int SIGSEGV
`signal.h' (ISO): section Program Error Signals.
int sigsetjmp (sigjmp_buf state, int savesigs)
`setjmp.h' (POSIX.1): section Non-Local Exits and Signals.
SIG_SETMASK
`signal.h' (POSIX.1): section Process Signal Mask.
int sigsetmask (int mask)
`signal.h' (BSD): section BSD Functions for Blocking Signals.
sigset_t
`signal.h' (POSIX.1): section Signal Sets.
int sigstack (const struct sigstack *stack, struct sigstack *oldstack)
`signal.h' (BSD): section Using a Separate Signal Stack.
int SIGSTOP
`signal.h' (POSIX.1): section Job Control Signals.
int sigsuspend (const sigset_t *set)
`signal.h' (POSIX.1): section Using sigsuspend.
int SIGSYS
`signal.h' (Unix): section Program Error Signals.
int SIGTERM
`signal.h' (ISO): section Termination Signals.
int SIGTRAP
`signal.h' (BSD): section Program Error Signals.
int SIGTSTP
`signal.h' (POSIX.1): section Job Control Signals.
int SIGTTIN
`signal.h' (POSIX.1): section Job Control Signals.
int SIGTTOU
`signal.h' (POSIX.1): section Job Control Signals.
SIG_UNBLOCK
`signal.h' (POSIX.1): section Process Signal Mask.
int SIGURG
`signal.h' (BSD): section Asynchronous I/O Signals.
int SIGUSR1
`signal.h' (POSIX.1): section Miscellaneous Signals.
int SIGUSR2
`signal.h' (POSIX.1): section Miscellaneous Signals.
int sigvec (int signum, const struct sigvec *action,struct sigvec *old-action)
`signal.h' (BSD): section BSD Function to Establish a Handler.
int SIGVTALRM
`signal.h' (BSD): section Alarm Signals.
int SIGWINCH
`signal.h' (BSD): section Miscellaneous Signals.
int SIGXCPU
`signal.h' (BSD): section Operation Error Signals.
int SIGXFSZ
`signal.h' (BSD): section Operation Error Signals.
double sin (double x)
`math.h' (ISO): section Trigonometric Functions.
void sincos (double x, double *sinx, double *cosx)
`math.h' (GNU): section Trigonometric Functions.
void sincosf (float x, float *sinx, float *cosx)
`math.h' (GNU): section Trigonometric Functions.
void sincosl (long double x, long double *sinx, long double *cosx)
`math.h' (GNU): section Trigonometric Functions.
float sinf (float x)
`math.h' (ISO): section Trigonometric Functions.
double sinh (double x)
`math.h' (ISO): section Hyperbolic Functions.
float sinhf (float x)
`math.h' (ISO): section Hyperbolic Functions.
long double sinhl (long double x)
`math.h' (ISO): section Hyperbolic Functions.
long double sinl (long double x)
`math.h' (ISO): section Trigonometric Functions.
S_IREAD
`sys/stat.h' (BSD): section The Mode Bits for Access Permission.
S_IRGRP
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IROTH
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IRUSR
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IRWXG
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IRWXO
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IRWXU
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
int S_ISBLK (mode_t m)
`sys/stat.h' (POSIX): section Testing the Type of a File.
int S_ISCHR (mode_t m)
`sys/stat.h' (POSIX): section Testing the Type of a File.
int S_ISDIR (mode_t m)
`sys/stat.h' (POSIX): section Testing the Type of a File.
int S_ISFIFO (mode_t m)
`sys/stat.h' (POSIX): section Testing the Type of a File.
S_ISGID
`sys/stat.h' (POSIX): section The Mode Bits for Access Permission.
int S_ISLNK (mode_t m)
`sys/stat.h' (GNU): section Testing the Type of a File.
int S_ISREG (mode_t m)
`sys/stat.h' (POSIX): section Testing the Type of a File.
int S_ISSOCK (mode_t m)
`sys/stat.h' (GNU): section Testing the Type of a File.
S_ISUID
`sys/stat.h' (POSIX): section The Mode Bits for Access Permission.
S_ISVTX
`sys/stat.h' (BSD): section The Mode Bits for Access Permission.
S_IWGRP
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IWOTH
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IWRITE
`sys/stat.h' (BSD): section The Mode Bits for Access Permission.
S_IWUSR
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IXGRP
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IXOTH
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
S_IXUSR
`sys/stat.h' (POSIX.1): section The Mode Bits for Access Permission.
size_t
`stddef.h' (ISO): section Important Data Types.
unsigned int sleep (unsigned int seconds)
`unistd.h' (POSIX.1): section Sleeping.
int snprintf (char *s, size_t size, const char *template, ...)
`stdio.h' (GNU): section Formatted Output Functions.
SO_BROADCAST
`sys/socket.h' (BSD): section Socket-Level Options.
int SOCK_DGRAM
`sys/socket.h' (BSD): section Communication Styles.
int socket (int namespace, int style, int protocol)
`sys/socket.h' (BSD): section Creating a Socket.
int socketpair (int namespace, int style, int protocol, int filedes[2])
`sys/socket.h' (BSD): section Socket Pairs.
int SOCK_RAW
`sys/socket.h' (BSD): section Communication Styles.
int SOCK_RDM
`sys/socket.h' (BSD): section Communication Styles.
int SOCK_SEQPACKET
`sys/socket.h' (BSD): section Communication Styles.
int SOCK_STREAM
`sys/socket.h' (BSD): section Communication Styles.
SO_DEBUG
`sys/socket.h' (BSD): section Socket-Level Options.
SO_DONTROUTE
`sys/socket.h' (BSD): section Socket-Level Options.
SO_ERROR
`sys/socket.h' (BSD): section Socket-Level Options.
SO_KEEPALIVE
`sys/socket.h' (BSD): section Socket-Level Options.
SO_LINGER
`sys/socket.h' (BSD): section Socket-Level Options.
int SOL_SOCKET
`sys/socket.h' (BSD): section Socket-Level Options.
SO_OOBINLINE
`sys/socket.h' (BSD): section Socket-Level Options.
SO_RCVBUF
`sys/socket.h' (BSD): section Socket-Level Options.
SO_REUSEADDR
`sys/socket.h' (BSD): section Socket-Level Options.
SO_SNDBUF
`sys/socket.h' (BSD): section Socket-Level Options.
SO_STYLE
`sys/socket.h' (GNU): section Socket-Level Options.
SO_TYPE
`sys/socket.h' (BSD): section Socket-Level Options.
speed_t
`termios.h' (POSIX.1): section Line Speed.
int sprintf (char *s, const char *template, ...)
`stdio.h' (ISO): section Formatted Output Functions.
double sqrt (double x)
`math.h' (ISO): section Exponentiation and Logarithms.
float sqrtf (float x)
`math.h' (ISO): section Exponentiation and Logarithms.
long double sqrtl (long double x)
`math.h' (ISO): section Exponentiation and Logarithms.
void srand (unsigned int seed)
`stdlib.h' (ISO): section ISO C Random Number Functions.
void srand48 (long int seedval)
`stdlib.h' (SVID): section SVID Random Number Function.
int srand48_r (long int seedval, struct drand48_data *buffer)
`stdlib.h' (GNU): section SVID Random Number Function.
void srandom (unsigned int seed)
`stdlib.h' (BSD): section BSD Random Number Functions.
int srandom_r (unsigned int seed, struct random_data *buf)
`stdlib.h' (GNU): section BSD Random Number Functions.
int sscanf (const char *s, const char *template, ...)
`stdio.h' (ISO): section Formatted Input Functions.
sighandler_t ssignal (int signum, sighandler_t action)
`signal.h' (SVID): section Basic Signal Handling.
int SSIZE_MAX
`limits.h' (POSIX.1): section General Capacity Limits.
ssize_t
`unistd.h' (POSIX.1): section Input and Output Primitives.
stack_t
`signal.h' (XPG): section Using a Separate Signal Stack.
int stat (const char *filename, struct stat *buf)
`sys/stat.h' (POSIX.1): section Reading the Attributes of a File.
int stat64 (const char *filename, struct stat64 *buf)
`sys/stat.h' (Unix98): section Reading the Attributes of a File.
FILE * stderr
`stdio.h' (ISO): section Standard Streams.
STDERR_FILENO
`unistd.h' (POSIX.1): section Descriptors and Streams.
FILE * stdin
`stdio.h' (ISO): section Standard Streams.
STDIN_FILENO
`unistd.h' (POSIX.1): section Descriptors and Streams.
FILE * stdout
`stdio.h' (ISO): section Standard Streams.
STDOUT_FILENO
`unistd.h' (POSIX.1): section Descriptors and Streams.
int stime (time_t *newtime)
`time.h' (SVID, XPG): section Simple Calendar Time.
char * stpcpy (char *restrict to, const char *restrict from)
`string.h' (Unknown origin): section Copying and Concatenation.
char * stpncpy (char *restrict to, const char *restrict from, size_t size)
`string.h' (GNU): section Copying and Concatenation.
int strcasecmp (const char *s1, const char *s2)
`string.h' (BSD): section String/Array Comparison.
char * strcasestr (const char *haystack, const char *needle)
`string.h' (GNU): section Search Functions.
char * strcat (char *restrict to, const char *restrict from)
`string.h' (ISO): section Copying and Concatenation.
char * strchr (const char *string, int c)
`string.h' (ISO): section Search Functions.
char * strchrnul (const char *string, int c)
`string.h' (GNU): section Search Functions.
int strcmp (const char *s1, const char *s2)
`string.h' (ISO): section String/Array Comparison.
int strcoll (const char *s1, const char *s2)
`string.h' (ISO): section Collation Functions.
char * strcpy (char *restrict to, const char *restrict from)
`string.h' (ISO): section Copying and Concatenation.
size_t strcspn (const char *string, const char *stopset)
`string.h' (ISO): section Search Functions.
char * strdup (const char *s)
`string.h' (SVID): section Copying and Concatenation.
char * strdupa (const char *s)
`string.h' (GNU): section Copying and Concatenation.
int STREAM_MAX
`limits.h' (POSIX.1): section General Capacity Limits.
char * strerror (int errnum)
`string.h' (ISO): section Error Messages.
char * strerror_r (int errnum, char *buf, size_t n)
`string.h' (GNU): section Error Messages.
char * strfry (char *string)
`string.h' (GNU): section strfry.
size_t strftime (char *s, size_t size, const char *template, const struct tm *brokentime)
`time.h' (ISO): section Formatting Calendar Time.
size_t strlen (const char *s)
`string.h' (ISO): section String Length.
int strncasecmp (const char *s1, const char *s2, size_t n)
`string.h' (BSD): section String/Array Comparison.
char * strncat (char *restrict to, const char *restrict from, size_t size)
`string.h' (ISO): section Copying and Concatenation.
int strncmp (const char *s1, const char *s2, size_t size)
`string.h' (ISO): section String/Array Comparison.
char * strncpy (char *restrict to, const char *restrict from, size_t size)
`string.h' (ISO): section Copying and Concatenation.
char * strndup (const char *s, size_t size)
`string.h' (GNU): section Copying and Concatenation.
char * strndupa (const char *s, size_t size)
`string.h' (GNU): section Copying and Concatenation.
size_t strnlen (const char *s, size_t maxlen)
`string.h' (GNU): section String Length.
char * strpbrk (const char *string, const char *stopset)
`string.h' (ISO): section Search Functions.
char * strptime (const char *s, const char *fmt, struct tm *tp)
`time.h' (XPG4): section Interpret string according to given format.
char * strrchr (const char *string, int c)
`string.h' (ISO): section Search Functions.
char * strsep (char **string_ptr, const char *delimiter)
`string.h' (BSD): section Finding Tokens in a String.
char * strsignal (int signum)
`string.h' (GNU): section Signal Messages.
size_t strspn (const char *string, const char *skipset)
`string.h' (ISO): section Search Functions.
char * strstr (const char *haystack, const char *needle)
`string.h' (ISO): section Search Functions.
double strtod (const char *restrict string, char **restrict tailptr)
`stdlib.h' (ISO): section Parsing of Floats.
float strtof (const char *string, char **tailptr)
`stdlib.h' (ISO): section Parsing of Floats.
intmax_t strtoimax (const char *restrict string, char **restrict tailptr, int base)
`inttypes.h' (ISO): section Parsing of Integers.
char * strtok (char *restrict newstring, const char *restrict delimiters)
`string.h' (ISO): section Finding Tokens in a String.
char * strtok_r (char *newstring, const char *delimiters, char **save_ptr)
`string.h' (POSIX): section Finding Tokens in a String.
long int strtol (const char *restrict string, char **restrict tailptr, int base)
`stdlib.h' (ISO): section Parsing of Integers.
long double strtold (const char *string, char **tailptr)
`stdlib.h' (ISO): section Parsing of Floats.
long long int strtoll (const char *restrict string, char **restrict tailptr, int base)
`stdlib.h' (ISO): section Parsing of Integers.
long long int strtoq (const char *restrict string, char **restrict tailptr, int base)
`stdlib.h' (BSD): section Parsing of Integers.
unsigned long int strtoul (const char *retrict string, char **restrict tailptr, int base)
`stdlib.h' (ISO): section Parsing of Integers.
unsigned long long int strtoull (const char *restrict string, char **restrict tailptr, int base)
`stdlib.h' (ISO): section Parsing of Integers.
uintmax_t strtoumax (const char *restrict string, char **restrict tailptr, int base)
`inttypes.h' (ISO): section Parsing of Integers.
unsigned long long int strtouq (const char *restrict string, char **restrict tailptr, int base)
`stdlib.h' (BSD): section Parsing of Integers.
struct aiocb
`aio.h' (POSIX.1b): section Perform I/O Operations in Parallel.
struct aiocb64
`aio.h' (POSIX.1b): section Perform I/O Operations in Parallel.
struct aioinit
`aio.h' (GNU): section How to optimize the AIO implementation.
struct argp
`argp.h' (GNU): section Specifying Argp Parsers.
struct argp_child
`argp.h' (GNU): section Combining Multiple Argp Parsers.
struct argp_option
`argp.h' (GNU): section Specifying Options in an Argp Parser.
struct argp_state
`argp.h' (GNU): section Argp Parsing State.
struct dirent
`dirent.h' (POSIX.1): section Format of a Directory Entry.
struct exit_status
`utmp.h' (SVID): section Manipulating the User Accounting Database.
struct flock
`fcntl.h' (POSIX.1): section File Locks.
struct fstab
`fstab.h' (BSD): section The `fstab' file.
struct FTW
`ftw.h' (XPG4.2): section Working with Directory Trees.
struct __gconv_step
`gconv.h' (GNU): section The iconv Implementation in the GNU C library.
struct __gconv_step_data
`gconv.h' (GNU): section The iconv Implementation in the GNU C library.
struct group
`grp.h' (POSIX.1): section The Data Structure for a Group.
struct hostent
`netdb.h' (BSD): section Host Names.
struct if_nameindex
`net/if.h' (IPv6 basic API): section Interface Naming.
struct in6_addr
`netinet/in.h' (IPv6 basic API): section Host Address Data Type.
struct in_addr
`netinet/in.h' (BSD): section Host Address Data Type.
struct iovec
`sys/uio.h' (BSD): section Fast Scatter-Gather I/O.
struct itimerval
`sys/time.h' (BSD): section Setting an Alarm.
struct lconv
`locale.h' (ISO): section localeconv: It is portable but ....
struct linger
`sys/socket.h' (BSD): section Socket-Level Options.
struct mallinfo
`malloc.h' (GNU): section Statistics for Memory Allocation with malloc.
struct mntent
`mntent.h' (BSD): section The `mtab' file.
struct msghdr
`sys/socket.h' (BSD): section Receiving Datagrams.
struct netent
`netdb.h' (BSD): section Networks Database.
struct obstack
`obstack.h' (GNU): section Creating Obstacks.
struct option
`getopt.h' (GNU): section Parsing Long Options with getopt_long.
struct passwd
`pwd.h' (POSIX.1): section The Data Structure that Describes a User.
struct printf_info
`printf.h' (GNU): section Conversion Specifier Options.
struct protoent
`netdb.h' (BSD): section Protocols Database.
struct random_data
`stdlib.h' (GNU): section BSD Random Number Functions.
struct rlimit
`sys/resource.h' (BSD): section Limiting Resource Usage.
struct rlimit64
`sys/resource.h' (Unix98): section Limiting Resource Usage.
struct rusage
`sys/resource.h' (BSD): section Resource Usage.
struct sched_param
`sched.h' (POSIX): section Basic Scheduling Functions.
struct servent
`netdb.h' (BSD): section The Services Database.
struct sgttyb
`termios.h' (BSD): section BSD Terminal Modes.
struct sigaction
`signal.h' (POSIX.1): section Advanced Signal Handling.
struct sigstack
`signal.h' (BSD): section Using a Separate Signal Stack.
struct sigvec
`signal.h' (BSD): section BSD Function to Establish a Handler.
struct sockaddr
`sys/socket.h' (BSD): section Address Formats.
struct sockaddr_in
`netinet/in.h' (BSD): section Internet Socket Address Formats.
struct sockaddr_un
`sys/un.h' (BSD): section Details of Local Namespace.
struct stat
`sys/stat.h' (POSIX.1): section The meaning of the File Attributes.
struct stat64
`sys/stat.h' (LFS): section The meaning of the File Attributes.
struct termios
`termios.h' (POSIX.1): section Terminal Mode Data Types.
struct timespec
`sys/time.h' (POSIX.1): section Elapsed Time.
struct timeval
`sys/time.h' (BSD): section Elapsed Time.
struct timezone
`sys/time.h' (BSD): section High-Resolution Calendar.
struct tm
`time.h' (ISO): section Broken-down Time.
struct tms
`sys/times.h' (POSIX.1): section Processor Time Inquiry.
struct utimbuf
`time.h' (POSIX.1): section File Times.
struct utsname
`sys/utsname.h' (POSIX.1): section Platform Type Identification.
int strverscmp (const char *s1, const char *s2)
`string.h' (GNU): section String/Array Comparison.
size_t strxfrm (char *restrict to, const char *restrict from, size_t size)
`string.h' (ISO): section Collation Functions.
int stty (int filedes, struct sgttyb * attributes)
`sgtty.h' (BSD): section BSD Terminal Modes.
int S_TYPEISMQ (struct stat *s)
`sys/stat.h' (POSIX): section Testing the Type of a File.
int S_TYPEISSEM (struct stat *s)
`sys/stat.h' (POSIX): section Testing the Type of a File.
int S_TYPEISSHM (struct stat *s)
`sys/stat.h' (POSIX): section Testing the Type of a File.
int SUN_LEN (struct sockaddr_un * ptr)
`sys/un.h' (BSD): section Details of Local Namespace.
_SVID_SOURCE
(GNU): section Feature Test Macros.
int SV_INTERRUPT
`signal.h' (BSD): section BSD Function to Establish a Handler.
int SV_ONSTACK
`signal.h' (BSD): section BSD Function to Establish a Handler.
int SV_RESETHAND
`signal.h' (Sun): section BSD Function to Establish a Handler.
int swapcontext (ucontext_t *restrict oucp, const ucontext_t *restrict ucp)
`ucontext.h' (SVID): section Complete Context Control.
int swprintf (wchar_t *s, size_t size, const wchar_t *template, ...)
`wchar.h' (GNU): section Formatted Output Functions.
int swscanf (const wchar_t *ws, const char *template, ...)
`wchar.h' (ISO): section Formatted Input Functions.
int symlink (const char *oldname, const char *newname)
`unistd.h' (BSD): section Symbolic Links.
SYMLINK_MAX
`limits.h' (POSIX.1): section Minimum Values for File System Limits.
int sync (void)
`unistd.h' (X/Open): section Synchronizing I/O operations.
long int syscall (long int sysno, ...)
`unistd.h' (???): section System Calls.
long int sysconf (int parameter)
`unistd.h' (POSIX.1): section Definition of sysconf.
int sysctl (int *names, int nlen, void *oldval,
`sysctl.h' (BSD): section System Parameters.
void syslog (int facility_priority, char *format, ...)
`syslog.h' (BSD): section syslog, vsyslog.
int system (const char *command)
`stdlib.h' (ISO): section Running a Command.
sighandler_t sysv_signal (int signum, sighandler_t action)
`signal.h' (GNU): section Basic Signal Handling.
double tan (double x)
`math.h' (ISO): section Trigonometric Functions.
float tanf (float x)
`math.h' (ISO): section Trigonometric Functions.
double tanh (double x)
`math.h' (ISO): section Hyperbolic Functions.
float tanhf (float x)
`math.h' (ISO): section Hyperbolic Functions.
long double tanhl (long double x)
`math.h' (ISO): section Hyperbolic Functions.
long double tanl (long double x)
`math.h' (ISO): section Trigonometric Functions.
int tcdrain (int filedes)
`termios.h' (POSIX.1): section Line Control Functions.
tcflag_t
`termios.h' (POSIX.1): section Terminal Mode Data Types.
int tcflow (int filedes, int action)
`termios.h' (POSIX.1): section Line Control Functions.
int tcflush (int filedes, int queue)
`termios.h' (POSIX.1): section Line Control Functions.
int tcgetattr (int filedes, struct termios *termios-p)
`termios.h' (POSIX.1): section Terminal Mode Functions.
pid_t tcgetpgrp (int filedes)
`unistd.h' (POSIX.1): section Functions for Controlling Terminal Access.
pid_t tcgetsid (int fildes)
`termios.h' (Unix98): section Functions for Controlling Terminal Access.
TCSADRAIN
`termios.h' (POSIX.1): section Terminal Mode Functions.
TCSAFLUSH
`termios.h' (POSIX.1): section Terminal Mode Functions.
TCSANOW
`termios.h' (POSIX.1): section Terminal Mode Functions.
TCSASOFT
`termios.h' (BSD): section Terminal Mode Functions.
int tcsendbreak (int filedes, int duration)
`termios.h' (POSIX.1): section Line Control Functions.
int tcsetattr (int filedes, int when, const struct termios *termios-p)
`termios.h' (POSIX.1): section Terminal Mode Functions.
int tcsetpgrp (int filedes, pid_t pgid)
`unistd.h' (POSIX.1): section Functions for Controlling Terminal Access.
void * tdelete (const void *key, void **rootp, comparison_fn_t compar)
`search.h' (SVID): section The tsearch function..
void tdestroy (void *vroot, __free_fn_t freefct)
`search.h' (GNU): section The tsearch function..
off_t telldir (DIR *dirstream)
`dirent.h' (BSD): section Random Access in a Directory Stream.
TEMP_FAILURE_RETRY (expression)
`unistd.h' (GNU): section Primitives Interrupted by Signals.
char * tempnam (const char *dir, const char *prefix)
`stdio.h' (SVID): section Temporary Files.
char * textdomain (const char *domainname)
`libintl.h' (GNU): section How to determine which catalog to be used.
void * tfind (const void *key, void *const *rootp, comparison_fn_t compar)
`search.h' (SVID): section The tsearch function..
double tgamma (double x)
`math.h' (XPG, ISO): section Special Functions.
float tgammaf (float x)
`math.h' (XPG, ISO): section Special Functions.
long double tgammal (long double x)
`math.h' (XPG, ISO): section Special Functions.
time_t time (time_t *result)
`time.h' (ISO): section Simple Calendar Time.
time_t timegm (struct tm *brokentime)
`time.h' (???): section Broken-down Time.
time_t timelocal (struct tm *brokentime)
`time.h' (???): section Broken-down Time.
clock_t times (struct tms *buffer)
`sys/times.h' (POSIX.1): section Processor Time Inquiry.
time_t
`time.h' (ISO): section Simple Calendar Time.
long int timezone
`time.h' (SVID): section Functions and Variables for Time Zones.
FILE * tmpfile (void)
`stdio.h' (ISO): section Temporary Files.
FILE * tmpfile64 (void)
`stdio.h' (Unix98): section Temporary Files.
int TMP_MAX
`stdio.h' (ISO): section Temporary Files.
char * tmpnam (char *result)
`stdio.h' (ISO): section Temporary Files.
char * tmpnam_r (char *result)
`stdio.h' (GNU): section Temporary Files.
int toascii (int c)
`ctype.h' (SVID, BSD): section Case Conversion.
int _tolower (int c)
`ctype.h' (SVID): section Case Conversion.
int tolower (int c)
`ctype.h' (ISO): section Case Conversion.
tcflag_t TOSTOP
`termios.h' (POSIX.1): section Local Modes.
int _toupper (int c)
`ctype.h' (SVID): section Case Conversion.
int toupper (int c)
`ctype.h' (ISO): section Case Conversion.
wint_t towctrans (wint_t wc, wctrans_t desc)
`wctype.h' (ISO): section Mapping of wide characters..
wint_t towlower (wint_t wc)
`wctype.h' (ISO): section Mapping of wide characters..
wint_t towupper (wint_t wc)
`wctype.h' (ISO): section Mapping of wide characters..
double trunc (double x)
`math.h' (ISO): section Rounding Functions.
int truncate (const char *filename, off_t length)
`unistd.h' (X/Open): section File Size.
int truncate64 (const char *name, off64_t length)
`unistd.h' (Unix98): section File Size.
float truncf (float x)
`math.h' (ISO): section Rounding Functions.
long double truncl (long double x)
`math.h' (ISO): section Rounding Functions.
TRY_AGAIN
`netdb.h' (BSD): section Host Names.
void * tsearch (const void *key, void **rootp, comparison_fn_t compar)
`search.h' (SVID): section The tsearch function..
char * ttyname (int filedes)
`unistd.h' (POSIX.1): section Identifying Terminals.
int ttyname_r (int filedes, char *buf, size_t len)
`unistd.h' (POSIX.1): section Identifying Terminals.
void twalk (const void *root, __action_fn_t action)
`search.h' (SVID): section The tsearch function..
char * tzname [2]
`time.h' (POSIX.1): section Functions and Variables for Time Zones.
int TZNAME_MAX
`limits.h' (POSIX.1): section General Capacity Limits.
void tzset (void)
`time.h' (POSIX.1): section Functions and Variables for Time Zones.
UCHAR_MAX
`limits.h' (ISO): section Range of an Integer Type.
ucontext_t
`ucontext.h' (SVID): section Complete Context Control.
uid_t
`sys/types.h' (POSIX.1): section Reading the Persona of a Process.
UINT_MAX
`limits.h' (ISO): section Range of an Integer Type.
int ulimit (int cmd, ...)
`ulimit.h' (BSD): section Limiting Resource Usage.
ULONG_LONG_MAX
`limits.h' (ISO): section Range of an Integer Type.
ULONG_MAX
`limits.h' (ISO): section Range of an Integer Type.
mode_t umask (mode_t mask)
`sys/stat.h' (POSIX.1): section Assigning File Permissions.
int umount (const char *file)
`sys/mount.h' (SVID, GNU): section Mount, Unmount, Remount.
int umount2 (const char *file, int flags)
`sys/mount.h' (GNU): section Mount, Unmount, Remount.
int uname (struct utsname *info)
`sys/utsname.h' (POSIX.1): section Platform Type Identification.
int ungetc (int c, FILE *stream)
`stdio.h' (ISO): section Using ungetc To Do Unreading.
wint_t ungetwc (wint_t wc, FILE *stream)
`wchar.h' (ISO): section Using ungetc To Do Unreading.
union wait
`sys/wait.h' (BSD): section BSD Process Wait Functions.
int unlink (const char *filename)
`unistd.h' (POSIX.1): section Deleting Files.
int unlockpt (int filedes)
`stdlib.h' (SVID, XPG4.2): section Allocating Pseudo-Terminals.
int unsetenv (const char *name)
`stdlib.h' (BSD): section Environment Access.
void updwtmp (const char *wtmp_file, const struct utmp *utmp)
`utmp.h' (SVID): section Manipulating the User Accounting Database.
USER_PROCESS
`utmp.h' (SVID): section Manipulating the User Accounting Database.
USER_PROCESS
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
USHRT_MAX
`limits.h' (ISO): section Range of an Integer Type.
int utime (const char *filename, const struct utimbuf *times)
`time.h' (POSIX.1): section File Times.
int utimes (const char *filename, struct timeval tvp[2])
`sys/time.h' (BSD): section File Times.
int utmpname (const char *file)
`utmp.h' (SVID): section Manipulating the User Accounting Database.
int utmpxname (const char *file)
`utmpx.h' (XPG4.2): section XPG User Accounting Database Functions.
va_alist
`varargs.h' (Unix): section Old-Style Variadic Functions.
type va_arg (va_list ap, type)
`stdarg.h' (ISO): section Argument Access Macros.
void __va_copy (va_list dest, va_list src)
`stdarg.h' (GNU): section Argument Access Macros.
va_dcl
`varargs.h' (Unix): section Old-Style Variadic Functions.
void va_end (va_list ap)
`stdarg.h' (ISO): section Argument Access Macros.
va_list
`stdarg.h' (ISO): section Argument Access Macros.
void * valloc (size_t size)
`malloc.h', `stdlib.h' (BSD): section Allocating Aligned Memory Blocks.
int vasprintf (char **ptr, const char *template, va_list ap)
`stdio.h' (GNU): section Variable Arguments Output Functions.
void va_start (va_list ap)
`varargs.h' (Unix): section Old-Style Variadic Functions.
void va_start (va_list ap, last-required)
`stdarg.h' (ISO): section Argument Access Macros.
int VDISCARD
`termios.h' (BSD): section Other Special Characters.
int VDSUSP
`termios.h' (BSD): section Characters that Cause Signals.
int VEOF
`termios.h' (POSIX.1): section Characters for Input Editing.
int VEOL
`termios.h' (POSIX.1): section Characters for Input Editing.
int VEOL2
`termios.h' (BSD): section Characters for Input Editing.
int VERASE
`termios.h' (POSIX.1): section Characters for Input Editing.
int versionsort (const void *a, const void *b)
`dirent.h' (GNU): section Scanning the Content of a Directory.
int versionsort64 (const void *a, const void *b)
`dirent.h' (GNU): section Scanning the Content of a Directory.
pid_t vfork (void)
`unistd.h' (BSD): section Creating a Process.
int vfprintf (FILE *stream, const char *template, va_list ap)
`stdio.h' (ISO): section Variable Arguments Output Functions.
int vfscanf (FILE *stream, const char *template, va_list ap)
`stdio.h' (ISO): section Variable Arguments Input Functions.
int vfwprintf (FILE *stream, const wchar_t *template, va_list ap)
`wchar.h' (ISO): section Variable Arguments Output Functions.
int vfwscanf (FILE *stream, const wchar_t *template, va_list ap)
`wchar.h' (ISO): section Variable Arguments Input Functions.
int VINTR
`termios.h' (POSIX.1): section Characters that Cause Signals.
int VKILL
`termios.h' (POSIX.1): section Characters for Input Editing.
int vlimit (int resource, int limit)
`sys/vlimit.h' (BSD): section Limiting Resource Usage.
int VLNEXT
`termios.h' (BSD): section Other Special Characters.
int VMIN
`termios.h' (POSIX.1): section Noncanonical Input.
int vprintf (const char *template, va_list ap)
`stdio.h' (ISO): section Variable Arguments Output Functions.
int VQUIT
`termios.h' (POSIX.1): section Characters that Cause Signals.
int VREPRINT
`termios.h' (BSD): section Characters for Input Editing.
int vscanf (const char *template, va_list ap)
`stdio.h' (ISO): section Variable Arguments Input Functions.
int vsnprintf (char *s, size_t size, const char *template, va_list ap)
`stdio.h' (GNU): section Variable Arguments Output Functions.
int vsprintf (char *s, const char *template, va_list ap)
`stdio.h' (ISO): section Variable Arguments Output Functions.
int vsscanf (const char *s, const char *template, va_list ap)
`stdio.h' (ISO): section Variable Arguments Input Functions.
int VSTART
`termios.h' (POSIX.1): section Special Characters for Flow Control.
int VSTATUS
`termios.h' (BSD): section Other Special Characters.
int VSTOP
`termios.h' (POSIX.1): section Special Characters for Flow Control.
int VSUSP
`termios.h' (POSIX.1): section Characters that Cause Signals.
int vswprintf (wchar_t *s, size_t size, const wchar_t *template, va_list ap)
`wchar.h' (GNU): section Variable Arguments Output Functions.
int vswscanf (const wchar_t *s, const wchar_t *template, va_list ap)
`wchar.h' (ISO): section Variable Arguments Input Functions.
void vsyslog (int facility_priority, char *format, va_list arglist)
`syslog.h' (BSD): section syslog, vsyslog.
int VTIME
`termios.h' (POSIX.1): section Noncanonical Input.
int vtimes (struct vtimes current, struct vtimes child)
`vtimes.h' (vtimes.h): section Resource Usage.
int VWERASE
`termios.h' (BSD): section Characters for Input Editing.
int vwprintf (const wchar_t *template, va_list ap)
`wchar.h' (ISO): section Variable Arguments Output Functions.
int vwscanf (const wchar_t *template, va_list ap)
`wchar.h' (ISO): section Variable Arguments Input Functions.
pid_t wait (int *status-ptr)
`sys/wait.h' (POSIX.1): section Process Completion.
pid_t wait3 (union wait *status-ptr, int options, struct rusage *usage)
`sys/wait.h' (BSD): section BSD Process Wait Functions.
pid_t wait4 (pid_t pid, int *status-ptr, int options, struct rusage *usage)
`sys/wait.h' (BSD): section Process Completion.
pid_t waitpid (pid_t pid, int *status-ptr, int options)
`sys/wait.h' (POSIX.1): section Process Completion.
WCHAR_MAX
`limits.h' (GNU): section Range of an Integer Type.
wint_t WCHAR_MAX
`wchar.h' (ISO): section Introduction to Extended Characters.
wint_t WCHAR_MIN
`wchar.h' (ISO): section Introduction to Extended Characters.
wchar_t
`stddef.h' (ISO): section Introduction to Extended Characters.
int WCOREDUMP (int status)
`sys/wait.h' (BSD): section Process Completion Status.
wchar_t * wcpcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom)
`wchar.h' (GNU): section Copying and Concatenation.
wchar_t * wcpncpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size)
`wchar.h' (GNU): section Copying and Concatenation.
size_t wcrtomb (char *restrict s, wchar_t wc, mbstate_t *restrict ps)
`wchar.h' (ISO): section Converting Single Characters.
int wcscasecmp (const wchar_t *ws1, const wchar_T *ws2)
`wchar.h' (GNU): section String/Array Comparison.
wchar_t * wcscat (wchar_t *restrict wto, const wchar_t *restrict wfrom)
`wchar.h' (ISO): section Copying and Concatenation.
wchar_t * wcschr (const wchar_t *wstring, int wc)
`wchar.h' (ISO): section Search Functions.
wchar_t * wcschrnul (const wchar_t *wstring, wchar_t wc)
`wchar.h' (GNU): section Search Functions.
int wcscmp (const wchar_t *ws1, const wchar_t *ws2)
`wchar.h' (ISO): section String/Array Comparison.
int wcscoll (const wchar_t *ws1, const wchar_t *ws2)
`wchar.h' (ISO): section Collation Functions.
wchar_t * wcscpy (wchar_t *restrict wto, const wchar_t *restrict wfrom)
`wchar.h' (ISO): section Copying and Concatenation.
size_t wcscspn (const wchar_t *wstring, const wchar_t *stopset)
`wchar.h' (ISO): section Search Functions.
wchar_t * wcsdup (const wchar_t *ws)
`wchar.h' (GNU): section Copying and Concatenation.
size_t wcsftime (wchar_t *s, size_t size, const wchar_t *template, const struct tm *brokentime)
`time.h' (ISO/Amend1): section Formatting Calendar Time.
size_t wcslen (const wchar_t *ws)
`wchar.h' (ISO): section String Length.
int wcsncasecmp (const wchar_t *ws1, const wchar_t *s2, size_t n)
`wchar.h' (GNU): section String/Array Comparison.
wchar_t * wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size)
`wchar.h' (ISO): section Copying and Concatenation.
int wcsncmp (const wchar_t *ws1, const wchar_t *ws2, size_t size)
`wchar.h' (ISO): section String/Array Comparison.
wchar_t * wcsncpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size)
`wchar.h' (ISO): section Copying and Concatenation.
size_t wcsnlen (const wchar_t *ws, size_t maxlen)
`wchar.h' (GNU): section String Length.
size_t wcsnrtombs (char *restrict dst, const wchar_t **restrict src, size_t nwc, size_t len, mbstate_t *restrict ps)
`wchar.h' (GNU): section Converting Multibyte and Wide Character Strings.
wchar_t * wcspbrk (const wchar_t *wstring, const wchar_t *stopset)
`wchar.h' (ISO): section Search Functions.
wchar_t * wcsrchr (const wchar_t *wstring, wchar_t c)
`wchar.h' (ISO): section Search Functions.
size_t wcsrtombs (char *restrict dst, const wchar_t **restrict src, size_t len, mbstate_t *restrict ps)
`wchar.h' (ISO): section Converting Multibyte and Wide Character Strings.
size_t wcsspn (const wchar_t *wstring, const wchar_t *skipset)
`wchar.h' (ISO): section Search Functions.
wchar_t * wcsstr (const wchar_t *haystack, const wchar_t *needle)
`wchar.h' (ISO): section Search Functions.
double wcstod (const wchar_t *restrict string, wchar_t **restrict tailptr)
`wchar.h' (ISO): section Parsing of Floats.
float wcstof (const wchar_t *string, wchar_t **tailptr)
`stdlib.h' (ISO): section Parsing of Floats.
intmax_t wcstoimax (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
`wchar.h' (ISO): section Parsing of Integers.
wchar_t * wcstok (wchar_t *newstring, const char *delimiters)
`wchar.h' (ISO): section Finding Tokens in a String.
long int wcstol (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
`wchar.h' (ISO): section Parsing of Integers.
long double wcstold (const wchar_t *string, wchar_t **tailptr)
`stdlib.h' (ISO): section Parsing of Floats.
long long int wcstoll (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
`wchar.h' (ISO): section Parsing of Integers.
size_t wcstombs (char *string, const wchar_t *wstring, size_t size)
`stdlib.h' (ISO): section Non-reentrant Conversion of Strings.
long long int wcstoq (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
`wchar.h' (GNU): section Parsing of Integers.
unsigned long int wcstoul (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
`wchar.h' (ISO): section Parsing of Integers.
unsigned long long int wcstoull (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
`wchar.h' (ISO): section Parsing of Integers.
uintmax_t wcstoumax (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
`wchar.h' (ISO): section Parsing of Integers.
unsigned long long int wcstouq (const wchar_t *restrict string, wchar_t **restrict tailptr, int base)
`wchar.h' (GNU): section Parsing of Integers.
wchar_t * wcswcs (const wchar_t *haystack, const wchar_t *needle)
`wchar.h' (XPG): section Search Functions.
size_t wcsxfrm (wchar_t *restrict wto, const wchar_t *wfrom, size_t size)
`wchar.h' (ISO): section Collation Functions.
int wctob (wint_t c)
`wchar.h' (ISO): section Converting Single Characters.
int wctomb (char *string, wchar_t wchar)
`stdlib.h' (ISO): section Non-reentrant Conversion of Single Characters.
wctrans_t wctrans (const char *property)
`wctype.h' (ISO): section Mapping of wide characters..
wctrans_t
`wctype.h' (ISO): section Mapping of wide characters..
wctype_t wctype (const char *property)
`wctype.h' (ISO): section Character class determination for wide characters.
wctype_t
`wctype.h' (ISO): section Character class determination for wide characters.
int WEOF
`wchar.h' (ISO): section End-Of-File and Errors.
wint_t WEOF
`wchar.h' (ISO): section Introduction to Extended Characters.
int WEXITSTATUS (int status)
`sys/wait.h' (POSIX.1): section Process Completion Status.
int WIFEXITED (int status)
`sys/wait.h' (POSIX.1): section Process Completion Status.
int WIFSIGNALED (int status)
`sys/wait.h' (POSIX.1): section Process Completion Status.
int WIFSTOPPED (int status)
`sys/wait.h' (POSIX.1): section Process Completion Status.
wint_t
`wchar.h' (ISO): section Introduction to Extended Characters.
wchar_t * wmemchr (const wchar_t *block, wchar_t wc, size_t size)
`wchar.h' (ISO): section Search Functions.
int wmemcmp (const wchar_t *a1, const wchar_t *a2, size_t size)
`wcjar.h' (ISO): section String/Array Comparison.
wchar_t * wmemcpy (wchar_t *restrict wto, const wchar_t *restruct wfrom, size_t size)
`wchar.h' (ISO): section Copying and Concatenation.
wchar_t * wmemmove (wchar *wto, const wchar_t *wfrom, size_t size)
`wchar.h' (ISO): section Copying and Concatenation.
wchar_t * wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size)
`wchar.h' (GNU): section Copying and Concatenation.
wchar_t * wmemset (wchar_t *block, wchar_t wc, size_t size)
`wchar.h' (ISO): section Copying and Concatenation.
int W_OK
`unistd.h' (POSIX.1): section Testing Permission to Access a File.
int wordexp (const char *words, wordexp_t *word-vector-ptr, int flags)
`wordexp.h' (POSIX.2): section Calling wordexp.
wordexp_t
`wordexp.h' (POSIX.2): section Calling wordexp.
void wordfree (wordexp_t *word-vector-ptr)
`wordexp.h' (POSIX.2): section Calling wordexp.
int wprintf (const wchar_t *template, ...)
`wchar.h' (ISO): section Formatted Output Functions.
WRDE_APPEND
`wordexp.h' (POSIX.2): section Flags for Word Expansion.
WRDE_BADCHAR
`wordexp.h' (POSIX.2): section Calling wordexp.
WRDE_BADVAL
`wordexp.h' (POSIX.2): section Calling wordexp.
WRDE_CMDSUB
`wordexp.h' (POSIX.2): section Calling wordexp.
WRDE_DOOFFS
`wordexp.h' (POSIX.2): section Flags for Word Expansion.
WRDE_NOCMD
`wordexp.h' (POSIX.2): section Flags for Word Expansion.
WRDE_NOSPACE
`wordexp.h' (POSIX.2): section Calling wordexp.
WRDE_REUSE
`wordexp.h' (POSIX.2): section Flags for Word Expansion.
WRDE_SHOWERR
`wordexp.h' (POSIX.2): section Flags for Word Expansion.
WRDE_SYNTAX
`wordexp.h' (POSIX.2): section Calling wordexp.
WRDE_UNDEF
`wordexp.h' (POSIX.2): section Flags for Word Expansion.
ssize_t write (int filedes, const void *buffer, size_t size)
`unistd.h' (POSIX.1): section Input and Output Primitives.
ssize_t writev (int filedes, const struct iovec *vector, int count)
`sys/uio.h' (BSD): section Fast Scatter-Gather I/O.
int wscanf (const wchar_t *template, ...)
`wchar.h' (ISO): section Formatted Input Functions.
int WSTOPSIG (int status)
`sys/wait.h' (POSIX.1): section Process Completion Status.
int WTERMSIG (int status)
`sys/wait.h' (POSIX.1): section Process Completion Status.
int X_OK
`unistd.h' (POSIX.1): section Testing Permission to Access a File.
_XOPEN_SOURCE
(X/Open): section Feature Test Macros.
_XOPEN_SOURCE_EXTENDED
(X/Open): section Feature Test Macros.
double y0 (double x)
`math.h' (SVID): section Special Functions.
float y0f (float x)
`math.h' (SVID): section Special Functions.
long double y0l (long double x)
`math.h' (SVID): section Special Functions.
double y1 (double x)
`math.h' (SVID): section Special Functions.
float y1f (float x)
`math.h' (SVID): section Special Functions.
long double y1l (long double x)
`math.h' (SVID): section Special Functions.
double yn (int n, double x)
`math.h' (SVID): section Special Functions.
float ynf (int n, float x)
`math.h' (SVID): section Special Functions.
long double ynl (int n, long double x)
`math.h' (SVID): section Special Functions.
@textfonts @rm

Installing the GNU C Library

Before you do anything else, you should read the file `FAQ' found at the top level of the source tree. This file answers common questions and describes problems you may experience with compilation and installation. It is updated more frequently than this manual.

Features can be added to GNU Libc via add-on bundles. These are separate tarfiles which you unpack into the top level of the source tree. Then you give configure the `--enable-add-ons' option to activate them, and they will be compiled into the library. As of the 2.2 release, one important component of glibc is distributed as "official" add-ons: the linuxthreads add-on. Unless you are doing an unusual installation, you should get this.

Support for POSIX threads is maintained by someone else, so it's in a separate package. It is only available for Linux systems, but this will change in the future. Get it from the same place you got the main bundle; the file is `glibc-linuxthreads-VERSION.tar.gz'.

You will need recent versions of several GNU tools: definitely GCC and GNU Make, and possibly others. See section Recommended Tools for Compilation, below.

Configuring and compiling GNU Libc

GNU libc can be compiled in the source directory, but we strongly advise to build it in a separate build directory. For example, if you have unpacked the glibc sources in `/src/gnu/glibc-2.2.0', create a directory `/src/gnu/glibc-build' to put the object files in. This allows removing the whole build directory in case an error occurs, which is the safest way to get a fresh start and should always be done.

From your object directory, run the shell script `configure' found at the top level of the source tree. In the scenario above, you'd type
$ ../glibc-2.2.0/configure args...
Please note that even if you're building in a separate build directory, the compilation needs to modify a few files in the source directory, especially some files in the manual subdirectory.

configure takes many options, but you can get away with knowing only two: `--prefix' and `--enable-add-ons'. The --prefix option tells configure where you want glibc installed. This defaults to `/usr/local'. The `--enable-add-ons' option tells configure to use all the add-on bundles it finds in the source directory. Since important functionality is provided in add-ons, you should always specify this option.

It may also be useful to set the CC and CFLAGS variables in the environment when running configure. CC selects the C compiler that will be used, and CFLAGS sets optimization options for the compiler.

The following list describes all of the available options for configure:

`--prefix=directory'
Install machine-independent data files in subdirectories of `directory'. The default is to install in `/usr/local'.
`--exec-prefix=directory'
Install the library and other machine-dependent files in subdirectories of `directory'. The default is to the `--prefix' directory if that option is specified, or `/usr/local' otherwise.
`--with-headers=directory'
Look for kernel header files in directory, not `/usr/include'. Glibc needs information from the kernel's private header files. It will normally look in `/usr/include' for them, but if you specify this option, it will look in DIRECTORY instead. This option is primarily of use on a system where the headers in `/usr/include' come from an older version of glibc. Conflicts can occasionally happen in this case. Note that Linux libc5 qualifies as an older version of glibc. You can also use this option if you want to compile glibc with a newer set of kernel headers than the ones found in `/usr/include'.
`--enable-add-ons[=list]'
Enable add-on packages in your source tree. If this option is specified with no list, it enables all the add-on packages it finds. If you do not wish to use some add-on package that you have present in your source tree, give this option a list of the add-ons that you do want used, like this: `--enable-add-ons=linuxthreads'
`--enable-kernel=version'
This option is currently only useful on Linux systems. The version parameter should have the form X.Y.Z and describes the smallest version of the Linux kernel the generated library is expected to support. The higher the version number is, the less compatibility code is added, and the faster the code gets.
`--with-binutils=directory'
Use the binutils (assembler and linker) in `directory', not the ones the C compiler would default to. You could use this option if the default binutils on your system cannot deal with all the constructs in the GNU C library. In that case, configure will detect the problem and suppress these constructs, so that the library will still be usable, but functionality may be lost--for example, you can't build a shared libc with old binutils.
`--without-fp'
Use this option if your computer lacks hardware floating-point support and your operating system does not emulate an FPU.
`--disable-shared'
Don't build shared libraries even if it is possible. Not all systems support shared libraries; you need ELF support and (currently) the GNU linker.
`--disable-profile'
Don't build libraries with profiling information. You may want to use this option if you don't plan to do profiling.
`--enable-omitfp'
Use maximum optimization for the normal (static and shared) libraries, and compile separate static libraries with debugging information and no optimisation. We recommend against this. The extra optimization doesn't gain you much, it may provoke compiler bugs, and you won't be able to trace bugs through the C library.
`--disable-versioning'
Don't compile the shared libraries with symbol version information. Doing this will make the resulting library incompatible with old binaries, so it's not recommended.
`--enable-static-nss'
Compile static versions of the NSS (Name Service Switch) libraries. This is not recommended because it defeats the purpose of NSS; a program linked statically with the NSS libraries cannot be dynamically reconfigured to use a different name database.
`--build=build-system'

`--host=host-system'
These options are for cross-compiling. If you specify both options and build-system is different from host-system, configure will prepare to cross-compile glibc from build-system to be used on host-system. You'll probably need the `--with-headers' option too, and you may have to override configure's selection of the compiler and/or binutils. If you only specify `--host', configure will prepare for a native compile but use what you specify instead of guessing what your system is. This is most useful to change the CPU submodel. For example, if configure guesses your machine as i586-pc-linux-gnu but you want to compile a library for 386es, give `--host=i386-pc-linux-gnu' or just `--host=i386-linux' and add the appropriate compiler flags (`-mcpu=i386' will do the trick) to CFLAGS. If you specify just `--build', configure will get confused.
To build the library and related programs, type make. This will produce a lot of output, some of which may look like errors from make but isn't. Look for error messages from make containing `***'. Those indicate that something is really wrong.

The compilation process takes several hours even on fast hardware. Expect at least two hours for the default configuration on i586 for Linux. For Hurd times are much longer. Except for EGCS 1.1 and GCC 2.95 (and later versions of GCC), all supported versions of GCC have a problem which causes them to take several minutes to compile certain files in the iconvdata directory. Do not panic if the compiler appears to hang.

If you want to run a parallel make, you can't just give make the `-j' option, because it won't be passed down to the sub-makes. Instead, edit the generated `Makefile' and uncomment the line
# PARALLELMFLAGS = -j 4
You can change the `4' to some other number as appropriate for your system. Instead of changing the `Makefile', you could give this option directly to make and call it as, for example, make PARALLELMFLAGS=-j4. If you're building in the source directory, you must use the latter approach since in this case no new `Makefile' is generated for you to change.

To build and run test programs which exercise some of the library facilities, type make check. If it does not complete successfully, do not use the built library, and report a bug after verifying that the problem is not already known. See section Reporting Bugs, for instructions on reporting bugs. Note that some of the tests assume they are not being run by root. We recommend you compile and test glibc as an unprivileged user.

To format the GNU C Library Reference Manual for printing, type make dvi. You need a working TeX installation to do this. The distribution already includes the on-line formatted version of the manual, as Info files. You can regenerate those with make info, but it shouldn't be necessary.

The library has a number of special-purpose configuration parameters which you can find in `Makeconfig'. These can be overwritten with the file `configparms'. To change them, create a `configparms' in your build directory and add values as appropriate for your system. The file is included and parsed by make and has to follow the conventions for makefiles.

It is easy to configure the GNU C library for cross-compilation by setting a few variables in `configparms'. Set CC to the cross-compiler for the target you configured the library for; it is important to use this same CC value when running configure, like this: `CC=target-gcc configure target'. Set BUILD_CC to the compiler to use for for programs run on the build system as part of compiling the library. You may need to set AR and RANLIB to cross-compiling versions of ar and ranlib if the native tools are not configured to work with object files for the target you configured for.

Installing the C Library

To install the library and its header files, and the Info files of the manual, type env LANGUAGE=C LC_ALL=C make install. This will build things if necessary, before installing them. However, you should still compile everything first. If you are installing glibc as your primary C library, we recommend that you shut the system down to single-user mode first, and reboot afterward. This minimizes the risk of breaking things when the library changes out from underneath.

If you're upgrading from Linux libc5 or some other C library, you need to replace the `/usr/include' with a fresh directory before installing it. The new `/usr/include' should contain the Linux headers, but nothing else.

You must first build the library (`make'), optionally check it (`make check'), switch the include directories and then install (`make install'). The steps must be done in this order. Not moving the directory before install will result in an unusable mixture of header files from both libraries, but configuring, building, and checking the library requires the ability to compile and run programs against the old library.

If you are upgrading from a previous installation of glibc 2.0 or 2.1, `make install' will do the entire job. You do not need to remove the old includes -- if you want to do so anyway you must then follow the order given above.

You may also need to reconfigure GCC to work with the new library. The easiest way to do that is to figure out the compiler switches to make it work again (`-Wl,--dynamic-linker=/lib/ld-linux.so.2' should work on Linux systems) and use them to recompile gcc. You can also edit the specs file (`/usr/lib/gcc-lib/TARGET/VERSION/specs'), but that is a bit of a black art.

You can install glibc somewhere other than where you configured it to go by setting the install_root variable on the command line for `make install'. The value of this variable is prepended to all the paths for installation. This is useful when setting up a chroot environment or preparing a binary distribution. The directory should be specified with an absolute file name.

Glibc 2.2 includes a daemon called nscd, which you may or may not want to run. nscd caches name service lookups; it can dramatically improve performance with NIS+, and may help with DNS as well.

One auxiliary program, `/usr/libexec/pt_chown', is installed setuid root. This program is invoked by the grantpt function; it sets the permissions on a pseudoterminal so it can be used by the calling process. This means programs like xterm and screen do not have to be setuid to get a pty. (There may be other reasons why they need privileges.) If you are using a 2.1 or newer Linux kernel with the devptsfs or devfs filesystems providing pty slaves, you don't need this program; otherwise you do. The source for `pt_chown' is in `login/programs/pt_chown.c'.

After installation you might want to configure the timezone and locale installation of your system. The GNU C library comes with a locale database which gets configured with localedef. For example, to set up a German locale with name de_DE, simply issue the command `localedef -i de_DE -f ISO-8859-1 de_DE'. To configure all locales that are supported by glibc, you can issue from your build directory the command `make localedata/install-locales'.

To configure the locally used timezone, you can either set the TZ environment variable. The script tzselect helps you to select the right value. As an example for Germany, tzselect would tell you to use `TZ='Europe/Berlin''. For a system wide installation (the given paths are for an installation with `--prefix=/usr'), link the timezone file which is in `/usr/share/zoneinfo' to the file `/etc/localtime'. For Germany, you might execute `ln -s /usr/share/zoneinfo/Europe/Berlin /etc/localtime'.

Recommended Tools for Compilation

We recommend installing the following GNU tools before attempting to build the GNU C library:

GNU make 3.79 or newer You need the latest version of GNU make. Modifying the GNU C Library to work with other make programs would be so difficult that we recommend you port GNU make instead. Really. We recommend version GNU make version 3.79. All earlier versions have severe bugs or lack features.
GCC 2.95 or newer The GNU C library can only be compiled with the GNU C compiler family. As of the 2.2 release, GCC 2.95.2 or higher is required. As of this writing, GCC 2.95.3 is the compiler we advise to use. You can use whatever compiler you like to compile programs that use GNU libc, but be aware that both GCC 2.7 and 2.8 have bugs in their floating-point support that may be triggered by the math library. For PPC you might need some patches even on top of the last GCC version. See the FAQ.
GNU binutils 2.10.1 or later You must use GNU binutils (as and ld) if you want to build a shared library. Even if you don't, we recommend you use them anyway. No one has tested compilation with non-GNU binutils in a long time. The quality of binutils releases has varied a bit recently. The bugs are in obscure features, but glibc uses quite a few of those. 2.10.1 and later releases are known to work. Versions after 2.8.1.0.23 may or may not work. Older versions definitely don't. For PPC you might need some patches even on top of the last binutils version. See the FAQ.
GNU texinfo 3.12f To correctly translate and install the Texinfo documentation you need this version of the texinfo package. Earlier versions do not understand all the tags used in the document, and the installation mechanism for the info files is not present or works differently.
GNU awk 3.0, or some other POSIX awk Awk is used in several places to generate files. The scripts should work with any POSIX-compliant awk implementation; gawk 3.0 and mawk 1.3 are known to work.
Perl 5 Perl is not required, but it is used if present to test the installation. We may decide to use it elsewhere in the future.
GNU sed 3.02 or newer Sed is used in several places to generate files. Most scripts work with any version of sed. The known exception is the script po2test.sed in the intl subdirectory which is used to generate msgs.h for the testsuite. This script works correctly only with GNU sed 3.02. If you like to run the testsuite, you should definitely upgrade sed.

If you change any of the `configure.in' files you will also need

GNU autoconf 2.12 or higher

and if you change any of the message translation files you will need

GNU gettext 0.10.36 or later

You may also need these packages if you upgrade your source tree using patches, although we try to avoid this.

Supported Configurations

The GNU C Library currently supports configurations that match the following patterns:
alpha*-*-linux
arm-*-linux
cris-*-linux
hppa-*-linux
ix86-*-gnu
ix86-*-linux
ia64-*-linux
m68k-*-linux
mips*-*-linux
powerpc-*-linux
s390-*-linux
s390x-*-linux
sparc-*-linux
sparc64-*-linux
Former releases of this library (version 2.1 and/or 2.0) used to run on the following configurations:
arm-*-linuxaout
arm-*-none
Very early releases (version 1.09.1 and perhaps earlier versions) used to run on the following configurations:
alpha-dec-osf1
alpha-*-linuxecoff
ix86-*-bsd4.3
ix86-*-isc2.2
ix86-*-isc3.n
ix86-*-sco3.2
ix86-*-sco3.2v4
ix86-*-sysv
ix86-*-sysv4
ix86-force_cpu386-none
ix86-sequent-bsd
i960-nindy960-none
m68k-hp-bsd4.3
m68k-mvme135-none
m68k-mvme136-none
m68k-sony-newsos3
m68k-sony-newsos4
m68k-sun-sunos4.n
mips-dec-ultrix4.n
mips-sgi-irix4.n
sparc-sun-solaris2.n
sparc-sun-sunos4.n
Since no one has volunteered to test and fix these configurations, they are not supported at the moment. They probably don't compile; they definitely don't work anymore. Porting the library is not hard. If you are interested in doing a port, please contact the glibc maintainers by sending electronic mail to @email{bug-glibc@gnu.org}.

Valid cases of `ix86' include `i386', `i486', `i586', and `i686'. All of those configurations produce a library that can run on this processor and newer processors. The GCC compiler by default generates code that's optimized for the machine it's configured for and will use the instructions available on that machine. For example if your GCC is configured for `i686', gcc will optimize for `i686' and might issue some `i686' specific instructions. To generate code for other models, you have to configure for that model and give GCC the appropriate `-march=' and `-mcpu=' compiler switches via CFLAGS.

Specific advice for Linux systems

If you are installing GNU libc on a Linux system, you need to have the header files from a 2.2 kernel around for reference. You do not need to use the 2.2 kernel, just have its headers where glibc can access at them. The easiest way to do this is to unpack it in a directory such as `/usr/src/linux-2.2.1'. In that directory, run `make config' and accept all the defaults. Then run `make include/linux/version.h'. Finally, configure glibc with the option `--with-headers=/usr/src/linux-2.2.1/include'. Use the most recent kernel you can get your hands on.

An alternate tactic is to unpack the 2.2 kernel and run `make config' as above. Then rename or delete `/usr/include', create a new `/usr/include', and make the usual symbolic links of `/usr/include/linux' and `/usr/include/asm' into the 2.2 kernel sources. You can then configure glibc with no special options. This tactic is recommended if you are upgrading from libc5, since you need to get rid of the old header files anyway.

Note that `/usr/include/net' and `/usr/include/scsi' should not be symlinks into the kernel sources. GNU libc provides its own versions of these files.

Linux expects some components of the libc installation to be in `/lib' and some in `/usr/lib'. This is handled automatically if you configure glibc with `--prefix=/usr'. If you set some other prefix or allow it to default to `/usr/local', then all the components are installed there.

If you are upgrading from libc5, you need to recompile every shared library on your system against the new library for the sake of new code, but keep the old libraries around for old binaries to use. This is complicated and difficult. Consult the Glibc2 HOWTO at @url{http://www.imaxx.net/~thrytis/glibc} for details.

You cannot use nscd with 2.0 kernels, due to bugs in the kernel-side thread support. nscd happens to hit these bugs particularly hard, but you might have problems with any threaded program.

Reporting Bugs

There are probably bugs in the GNU C library. There are certainly errors and omissions in this manual. If you report them, they will get fixed. If you don't, no one will ever know about them and they will remain unfixed for all eternity, if not longer.

It is a good idea to verify that the problem has not already been reported. Bugs are documented in two places: The file `BUGS' describes a number of well known bugs and the bug tracking system has a WWW interface at @url{http://www-gnats.gnu.org:8080/cgi-bin/wwwgnats.pl}. The WWW interface gives you access to open and closed reports. The closed reports normally include a patch or a hint on solving the problem.

To report a bug, first you must find it. Hopefully, this will be the hard part. Once you've found a bug, make sure it's really a bug. A good way to do this is to see if the GNU C library behaves the same way some other C library does. If so, probably you are wrong and the libraries are right (but not necessarily). If not, one of the libraries is probably wrong. It might not be the GNU library. Many historical Unix C libraries permit things that we don't, such as closing a file twice.

If you think you have found some way in which the GNU C library does not conform to the ISO and POSIX standards (see section Standards and Portability), that is definitely a bug. Report it!

Once you're sure you've found a bug, try to narrow it down to the smallest test case that reproduces the problem. In the case of a C library, you really only need to narrow it down to one library function call, if possible. This should not be too difficult.

The final step when you have a simple test case is to report the bug. Do this using the glibcbug script. It is installed with libc, or if you haven't installed it, will be in your build directory. Send your test case, the results you got, the results you expected, and what you think the problem might be (if you've thought of anything). glibcbug will insert the configuration information we need to see, and ship the report off to @email{bugs@gnu.org}. Don't send a message there directly; it is fed to a program that expects mail to be formatted in a particular way. Use the script.

If you are not sure how a function should behave, and this manual doesn't tell you, that's a bug in the manual. Report that too! If the function's behavior disagrees with the manual, then either the library or the manual has a bug, so report the disagreement. If you find any errors or omissions in this manual, please report them to the Internet address @email{bug-glibc-manual@gnu.org}. If you refer to specific sections of the manual, please include the section names for easier identification.
Library Maintenance

Adding New Functions

The process of building the library is driven by the makefiles, which make heavy use of special features of GNU make. The makefiles are very complex, and you probably don't want to try to understand them. But what they do is fairly straightforward, and only requires that you define a few variables in the right places.

The library sources are divided into subdirectories, grouped by topic.

The `string' subdirectory has all the string-manipulation functions, `math' has all the mathematical functions, etc.

Each subdirectory contains a simple makefile, called `Makefile', which defines a few make variables and then includes the global makefile `Rules' with a line like:
include ../Rules
The basic variables that a subdirectory makefile defines are:

subdir
The name of the subdirectory, for example `stdio'. This variable must be defined.
headers
The names of the header files in this section of the library, such as `stdio.h'.
routines

aux
The names of the modules (source files) in this section of the library. These should be simple names, such as `strlen' (rather than complete file names, such as `strlen.c'). Use routines for modules that define functions in the library, and aux for auxiliary modules containing things like data definitions. But the values of routines and aux are just concatenated, so there really is no practical difference.
tests
The names of test programs for this section of the library. These should be simple names, such as `tester' (rather than complete file names, such as `tester.c'). `make tests' will build and run all the test programs. If a test program needs input, put the test data in a file called `test-program.input'; it will be given to the test program on its standard input. If a test program wants to be run with arguments, put the arguments (all on a single line) in a file called `test-program.args'. Test programs should exit with zero status when the test passes, and nonzero status when the test indicates a bug in the library or error in building.
others
The names of "other" programs associated with this section of the library. These are programs which are not tests per se, but are other small programs included with the library. They are built by `make others'.
install-lib

install-data

install
Files to be installed by `make install'. Files listed in `install-lib' are installed in the directory specified by `libdir' in `configparms' or `Makeconfig' (see section Installing the GNU C Library). Files listed in install-data are installed in the directory specified by `datadir' in `configparms' or `Makeconfig'. Files listed in install are installed in the directory specified by `bindir' in `configparms' or `Makeconfig'.
distribute
Other files from this subdirectory which should be put into a distribution tar file. You need not list here the makefile itself or the source and header files listed in the other standard variables. Only define distribute if there are files used in an unusual way that should go into the distribution.
generated
Files which are generated by `Makefile' in this subdirectory. These files will be removed by `make clean', and they will never go into a distribution.
extra-objs
Extra object files which are built by `Makefile' in this subdirectory. This should be a list of file names like `foo.o'; the files will actually be found in whatever directory object files are being built in. These files will be removed by `make clean'. This variable is used for secondary object files needed to build others or tests.
Porting the GNU C Library

The GNU C library is written to be easily portable to a variety of machines and operating systems. Machine- and operating system-dependent functions are well separated to make it easy to add implementations for new machines or operating systems. This section describes the layout of the library source tree and explains the mechanisms used to select machine-dependent code to use.

All the machine-dependent and operating system-dependent files in the library are in the subdirectory `sysdeps' under the top-level library source directory. This directory contains a hierarchy of subdirectories (see section Layout of the `sysdeps' Directory Hierarchy).

Each subdirectory of `sysdeps' contains source files for a particular machine or operating system, or for a class of machine or operating system (for example, systems by a particular vendor, or all machines that use IEEE 754 floating-point format). A configuration specifies an ordered list of these subdirectories. Each subdirectory implicitly appends its parent directory to the list. For example, specifying the list `unix/bsd/vax' is equivalent to specifying the list `unix/bsd/vax unix/bsd unix'. A subdirectory can also specify that it implies other subdirectories which are not directly above it in the directory hierarchy. If the file `Implies' exists in a subdirectory, it lists other subdirectories of `sysdeps' which are appended to the list, appearing after the subdirectory containing the `Implies' file. Lines in an `Implies' file that begin with a `#' character are ignored as comments. For example, `unix/bsd/Implies' contains:
# BSD has Internet-related things.
unix/inet
and `unix/Implies' contains:
posix
So the final list is `unix/bsd/vax unix/bsd unix/inet unix posix'.

`sysdeps' has a "special" subdirectory called `generic'. It is always implicitly appended to the list of subdirectories, so you needn't put it in an `Implies' file, and you should not create any subdirectories under it intended to be new specific categories. `generic' serves two purposes. First, the makefiles do not bother to look for a system-dependent version of a file that's not in `generic'. This means that any system-dependent source file must have an analogue in `generic', even if the routines defined by that file are not implemented on other platforms. Second. the `generic' version of a system-dependent file is used if the makefiles do not find a version specific to the system you're compiling for.

If it is possible to implement the routines in a `generic' file in machine-independent C, using only other machine-independent functions in the C library, then you should do so. Otherwise, make them stubs. A stub function is a function which cannot be implemented on a particular machine or operating system. Stub functions always return an error, and set errno to ENOSYS (Function not implemented). See section Error Reporting. If you define a stub function, you must place the statement stub_warning(function), where function is the name of your function, after its definition; also, you must include the file <stub-tag.h> into your file. This causes the function to be listed in the installed <gnu/stubs.h>, and makes GNU ld warn when the function is used.

Some rare functions are only useful on specific systems and aren't defined at all on others; these do not appear anywhere in the system-independent source code or makefiles (including the `generic' directory), only in the system-dependent `Makefile' in the specific system's subdirectory.

If you come across a file that is in one of the main source directories (`string', `stdio', etc.), and you want to write a machine- or operating system-dependent version of it, move the file into `sysdeps/generic' and write your new implementation in the appropriate system-specific subdirectory. Note that if a file is to be system-dependent, it must not appear in one of the main source directories.

There are a few special files that may exist in each subdirectory of `sysdeps':

`Makefile'
A makefile for this machine or operating system, or class of machine or operating system. This file is included by the library makefile `Makerules', which is used by the top-level makefile and the subdirectory makefiles. It can change the variables set in the including makefile or add new rules. It can use GNU make conditional directives based on the variable `subdir' (see above) to select different sets of variables and rules for different sections of the library. It can also set the make variable `sysdep-routines', to specify extra modules to be included in the library. You should use `sysdep-routines' rather than adding modules to `routines' because the latter is used in determining what to distribute for each subdirectory of the main source tree. Each makefile in a subdirectory in the ordered list of subdirectories to be searched is included in order. Since several system-dependent makefiles may be included, each should append to `sysdep-routines' rather than simply setting it:
sysdep-routines := $(sysdep-routines) foo bar
`Subdirs'
This file contains the names of new whole subdirectories under the top-level library source tree that should be included for this system. These subdirectories are treated just like the system-independent subdirectories in the library source tree, such as `stdio' and `math'. Use this when there are completely new sets of functions and header files that should go into the library for the system this subdirectory of `sysdeps' implements. For example, `sysdeps/unix/inet/Subdirs' contains `inet'; the `inet' directory contains various network-oriented operations which only make sense to put in the library on systems that support the Internet.
`Dist'
This file contains the names of files (relative to the subdirectory of `sysdeps' in which it appears) which should be included in the distribution. List any new files used by rules in the `Makefile' in the same directory, or header files used by the source files in that directory. You don't need to list files that are implementations (either C or assembly source) of routines whose names are given in the machine-independent makefiles in the main source tree.
`configure'
This file is a shell script fragment to be run at configuration time. The top-level `configure' script uses the shell . command to read the `configure' file in each system-dependent directory chosen, in order. The `configure' files are often generated from `configure.in' files using Autoconf. A system-dependent `configure' script will usually add things to the shell variables `DEFS' and `config_vars'; see the top-level `configure' script for details. The script can check for `--with-package' options that were passed to the top-level `configure'. For an option `--with-package=value' `configure' sets the shell variable `with_package' (with any dashes in package converted to underscores) to value; if the option is just `--with-package' (no argument), then it sets `with_package' to `yes'.
`configure.in'
This file is an Autoconf input fragment to be processed into the file `configure' in this subdirectory. See section `Introduction' in Autoconf: Generating Automatic Configuration Scripts, for a description of Autoconf. You should write either `configure' or `configure.in', but not both. The first line of `configure.in' should invoke the m4 macro `GLIBC_PROVIDES'. This macro does several AC_PROVIDE calls for Autoconf macros which are used by the top-level `configure' script; without this, those macros might be invoked again unnecessarily by Autoconf.
That is the general system for how system-dependencies are isolated. The next section explains how to decide what directories in `sysdeps' to use. section Porting the GNU C Library to Unix Systems, has some tips on porting the library to Unix variants.

Layout of the `sysdeps' Directory Hierarchy

A GNU configuration name has three parts: the CPU type, the manufacturer's name, and the operating system. `configure' uses these to pick the list of system-dependent directories to look for. If the `--nfp' option is not passed to `configure', the directory `machine/fpu' is also used. The operating system often has a base operating system; for example, if the operating system is `Linux', the base operating system is `unix/sysv'. The algorithm used to pick the list of directories is simple: `configure' makes a list of the base operating system, manufacturer, CPU type, and operating system, in that order. It then concatenates all these together with slashes in between, to produce a directory name; for example, the configuration `i686-linux-gnu' results in `unix/sysv/linux/i386/i686'. `configure' then tries removing each element of the list in turn, so `unix/sysv/linux' and `unix/sysv' are also tried, among others. Since the precise version number of the operating system is often not important, and it would be very inconvenient, for example, to have identical `irix6.2' and `irix6.3' directories, `configure' tries successively less specific operating system names by removing trailing suffixes starting with a period.

As an example, here is the complete list of directories that would be tried for the configuration `i686-linux-gnu' (with the `crypt' and `linuxthreads' add-on):
sysdeps/i386/elf
crypt/sysdeps/unix
linuxthreads/sysdeps/unix/sysv/linux
linuxthreads/sysdeps/pthread
linuxthreads/sysdeps/unix/sysv
linuxthreads/sysdeps/unix
linuxthreads/sysdeps/i386/i686
linuxthreads/sysdeps/i386
linuxthreads/sysdeps/pthread/no-cmpxchg
sysdeps/unix/sysv/linux/i386
sysdeps/unix/sysv/linux
sysdeps/gnu
sysdeps/unix/common
sysdeps/unix/mman
sysdeps/unix/inet
sysdeps/unix/sysv/i386/i686
sysdeps/unix/sysv/i386
sysdeps/unix/sysv
sysdeps/unix/i386
sysdeps/unix
sysdeps/posix
sysdeps/i386/i686
sysdeps/i386/i486
sysdeps/libm-i387/i686
sysdeps/i386/fpu
sysdeps/libm-i387
sysdeps/i386
sysdeps/wordsize-32
sysdeps/ieee754
sysdeps/libm-ieee754
sysdeps/generic
Different machine architectures are conventionally subdirectories at the top level of the `sysdeps' directory tree. For example, `sysdeps/sparc' and `sysdeps/m68k'. These contain files specific to those machine architectures, but not specific to any particular operating system. There might be subdirectories for specializations of those architectures, such as `sysdeps/m68k/68020'. Code which is specific to the floating-point coprocessor used with a particular machine should go in `sysdeps/machine/fpu'.

There are a few directories at the top level of the `sysdeps' hierarchy that are not for particular machine architectures.

`generic'
As described above (see section Porting the GNU C Library), this is the subdirectory that every configuration implicitly uses after all others.
`ieee754'
This directory is for code using the IEEE 754 floating-point format, where the C type float is IEEE 754 single-precision format, and double is IEEE 754 double-precision format. Usually this directory is referred to in the `Implies' file in a machine architecture-specific directory, such as `m68k/Implies'.
`libm-ieee754'
This directory contains an implementation of a mathematical library usable on platforms which use IEEE 754 conformant floating-point arithmetic.
`libm-i387'
This is a special case. Ideally the code should be in `sysdeps/i386/fpu' but for various reasons it is kept aside.
`posix'
This directory contains implementations of things in the library in terms of POSIX.1 functions. This includes some of the POSIX.1 functions themselves. Of course, POSIX.1 cannot be completely implemented in terms of itself, so a configuration using just `posix' cannot be complete.
`unix'
This is the directory for Unix-like things. See section Porting the GNU C Library to Unix Systems. `unix' implies `posix'. There are some special-purpose subdirectories of `unix':
`unix/common'
This directory is for things common to both BSD and System V release 4. Both `unix/bsd' and `unix/sysv/sysv4' imply `unix/common'.
`unix/inet'
This directory is for socket and related functions on Unix systems. `unix/inet/Subdirs' enables the `inet' top-level subdirectory. `unix/common' implies `unix/inet'.
`mach'
This is the directory for things based on the Mach microkernel from CMU (including the GNU operating system). Other basic operating systems (VMS, for example) would have their own directories at the top level of the `sysdeps' hierarchy, parallel to `unix' and `mach'.
Porting the GNU C Library to Unix Systems

Most Unix systems are fundamentally very similar. There are variations between different machines, and variations in what facilities are provided by the kernel. But the interface to the operating system facilities is, for the most part, pretty uniform and simple.

The code for Unix systems is in the directory `unix', at the top level of the `sysdeps' hierarchy. This directory contains subdirectories (and subdirectory trees) for various Unix variants.

The functions which are system calls in most Unix systems are implemented in assembly code, which is generated automatically from specifications in files named `syscalls.list'. There are several such files, one in `sysdeps/unix' and others in its subdirectories. Some special system calls are implemented in files that are named with a suffix of `.S'; for example, `_exit.S'. Files ending in `.S' are run through the C preprocessor before being fed to the assembler.

These files all use a set of macros that should be defined in `sysdep.h'. The `sysdep.h' file in `sysdeps/unix' partially defines them; a `sysdep.h' file in another directory must finish defining them for the particular machine and operating system variant. See `sysdeps/unix/sysdep.h' and the machine-specific `sysdep.h' implementations to see what these macros are and what they should do.

The system-specific makefile for the `unix' directory (`sysdeps/unix/Makefile') gives rules to generate several files from the Unix system you are building the library on (which is assumed to be the target system you are building the library for). All the generated files are put in the directory where the object files are kept; they should not affect the source tree itself. The files generated are `ioctls.h', `errnos.h', `sys/param.h', and `errlist.c' (for the `stdio' section of the library).

Contributors to the GNU C Library

The GNU C library was written originally by Roland McGrath, and is currently maintained by Ulrich Drepper. Some parts of the library were contributed or worked on by other people.

The getopt function and related code was written by Richard Stallman, David J. MacKenzie, and Roland McGrath.
The merge sort function qsort was written by Michael J. Haertel.
The quick sort function used as a fallback by qsort was written by Douglas C. Schmidt.
The memory allocation functions malloc, realloc and free and related code were written by Michael J. Haertel, Wolfram Gloger, and Doug Lea.
Fast implementations of many of the string functions (memcpy, strlen, etc.) were written by Torbj@"orn Granlund.
The `tar.h' header file was written by David J. MacKenzie.
The port to the MIPS DECStation running Ultrix 4 (mips-dec-ultrix4) was contributed by Brendan Kehoe and Ian Lance Taylor.
The DES encryption function crypt and related functions were contributed by Michael Glad.
The ftw and nftw functions were contributed by Ulrich Drepper.
The startup code to support SunOS shared libraries was contributed by Tom Quinn.
The mktime function was contributed by Paul Eggert.
The port to the Sequent Symmetry running Dynix version 3 (i386-sequent-bsd) was contributed by Jason Merrill.
The timezone support code is derived from the public-domain timezone package by Arthur David Olson and his many contributors.
The port to the DEC Alpha running OSF/1 (alpha-dec-osf1) was contributed by Brendan Kehoe, using some code written by Roland McGrath.
The port to SGI machines running Irix 4 (mips-sgi-irix4) was contributed by Tom Quinn.
The port of the Mach and Hurd code to the MIPS architecture (mips-anything-gnu) was contributed by Kazumoto Kojima.
The floating-point printing function used by printf and friends and the floating-point reading function used by scanf, strtod and friends were written by Ulrich Drepper. The multi-precision integer functions used in those functions are taken from GNU MP, which was contributed by Torbj@"orn Granlund.
The internationalization support in the library, and the support programs locale and localedef, were written by Ulrich Drepper. Ulrich Drepper adapted the support code for message catalogs (`libintl.h', etc.) from the GNU gettext package, which he also wrote. He also contributed the catgets support and the entire suite of multi-byte and wide-character support functions (`wctype.h', `wchar.h', etc.).
The implementations of the `nsswitch.conf' mechanism and the files and DNS backends for it were designed and written by Ulrich Drepper and Roland McGrath, based on a backend interface defined by Peter Eriksson.
The port to Linux i386/ELF (i386-anything-linux) was contributed by Ulrich Drepper, based in large part on work done in Hongjiu Lu's Linux version of the GNU C Library.
The port to Linux/m68k (m68k-anything-linux) was contributed by Andreas Schwab.
The ports to Linux/ARM (arm-ANYTHING-linuxaout) and ARM standalone (arm-ANYTHING-none), as well as parts of the IPv6 support code, were contributed by Philip Blundell.
Richard Henderson contributed the ELF dynamic linking code and other support for the Alpha processor.
David Mosberger-Tang contributed the port to Linux/Alpha (alpha-anything-linux).
The port to Linux on PowerPC (powerpc-anything-linux) was contributed by Geoffrey Keating.
Miles Bader wrote the argp argument-parsing package, and the argz/envz interfaces.
Stephen R. van den Berg contributed a highly-optimized strstr function.
Ulrich Drepper contributed the hsearch and drand48 families of functions; reentrant `..._r' versions of the random family; System V shared memory and IPC support code; and several highly-optimized string functions for ix86 processors.
The math functions are taken from fdlibm-5.1 by Sun Microsystems, as modified by J.T. Conklin, Ian Lance Taylor, Ulrich Drepper, Andreas Schwab, and Roland McGrath.
The libio library used to implement stdio functions on some platforms was written by Per Bothner and modified by Ulrich Drepper.
Eric Youngdale and Ulrich Drepper implemented versioning of objects on symbol level.
Thorsten Kukuk provided an implementation for NIS (YP) and NIS+, securelevel 0, 1 and 2.
Andreas Jaeger provided a test suite for the math library.
Mark Kettenis implemented the utmpx interface and an utmp daemon.
Ulrich Drepper added character conversion functions (iconv).
Thorsten Kukuk provided an implementation for a caching daemon for NSS (nscd).
Tim Waugh provided an implementation of the POSIX.2 wordexp function family.
Mark Kettenis provided a Hesiod NSS module.
The Internet-related code (most of the `inet' subdirectory) and several other miscellaneous functions and header files have been included from 4.4 BSD with little or no modification. All code incorporated from 4.4 BSD is under the following copyright:
Copyright (C) 1991 Regents of the University of California.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
[This condition was removed.]
Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The random number generation functions random, srandom, setstate and initstate, which are also the basis for the rand and srand functions, were written by Earl T. Cohen for the University of California at Berkeley and are copyrighted by the Regents of the University of California. They have undergone minor changes to fit into the GNU C library and to fit the ISO C standard, but the functional code is Berkeley's.
The DNS resolver code is taken directly from BIND 4.9.5, which is under both the Berkeley copyright above and also:

Portions Copyright (C) 1993 by Digital Equipment Corporation.

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies, and that the name of Digital Equipment Corporation not be used in advertising or publicity pertaining to distribution of the document or software without specific, written prior permission.

THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL DIGITAL EQUIPMENT CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

The code to support Sun RPC is taken verbatim from Sun's RPCSRC-4.0 distribution, and is covered by this copyright:
Copyright (C) 1984, Sun Microsystems, Inc.
Sun RPC is a product of Sun Microsystems, Inc. and is provided for unrestricted use provided that this legend is included on all tape media and as a part of the software program in whole or part. Users may copy or modify Sun RPC without charge, but are not authorized to license or distribute it to anyone else except as part of a product or program developed by the user.

SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.

Sun RPC is provided with no support and without any obligation on the part of Sun Microsystems, Inc. to assist in its use, correction, modification or enhancement.

SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC OR ANY PART THEREOF.

In no event will Sun Microsystems, Inc. be liable for any lost revenue or profits or other special, indirect and consequential damages, even if Sun has been advised of the possibility of such damages.
Sun Microsystems, Inc.
2550 Garcia Avenue
Mountain View, California  94043
Some of the support code for Mach is taken from Mach 3.0 by CMU, and is under the following copyright terms:
Mach Operating System
Copyright (C) 1991,1990,1989 Carnegie Mellon University
All Rights Reserved.
Permission to use, copy, modify and distribute this software and its documentation is hereby granted, provided that both the copyright notice and this permission notice appear in all copies of the software, derivative works or modified versions, and any portions thereof, and that both notices appear in supporting documentation.

CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.

Carnegie Mellon requests users of this software to return to
 Software Distribution Coordinator
 School of Computer Science
 Carnegie Mellon University
 Pittsburgh PA 15213-3890
or @email{Software.Distribution@CS.CMU.EDU} any improvements or extensions that they make and grant Carnegie Mellon the rights to redistribute these changes.

The code for the database library `libdb' comes from the 2.3 release of Berkeley DB. That code is under the same copyright as 4.4 BSD and also:
Copyright (C) 1990, 1993, 1994, 1995, 1996, 1997
Sleepycat Software.  All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Redistributions in any form must be accompanied by information on how to obtain complete source code for the DB software and any accompanying software that uses the DB software. The source code must either be included in the distribution or be available for no more than the cost of distribution plus a nominal fee, and must be freely redistributable under reasonable conditions. For an executable file, complete source code means the source code for all modules it contains. It does not mean source code for modules or files that typically accompany the operating system on which the executable file runs, e.g., standard library modules or system header files.

THIS SOFTWARE IS PROVIDED BY SLEEPYCAT SOFTWARE "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SLEEPYCAT SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Portions copyright (C) 1995, 1996
The President and Fellows of Harvard University.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
All advertising materials mentioning features or use of this software must display the following acknowledgement:

This product includes software developed by Harvard University and its contributors.

Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY HARVARD AND ITS CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL HARVARD OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

For a license to use, redistribute or sell DB software under conditions other than those described above, or to purchase support for this software, please contact Sleepycat Software at
 Sleepycat Software
 394 E. Riding Dr.
 Carlisle, MA 01741
 USA
 +1-508-287-4781
or @email{db@sleepycat.com}.

GNU LIBRARY GENERAL PUBLIC LICENSE

Version 2, June 1991
Copyright (C) 1991 Free Software Foundation, Inc.
59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

[This is the first released version of the library GPL.  It is
 numbered 2 because it goes with version 2 of the ordinary GPL.]
Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.

This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it.

For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights.

Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library.

Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license.

The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such.

Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better.

However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries.

The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library.

Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one.

TERMS AND CONDITIONS FOR COPYING,
DISTRIBUTION AND MODIFICATION

This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you". A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.
You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

The modified work must itself be a software library.
You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.
You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.
If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. This option is useful when you wish to copy part of the code of the Library into a program that is not a library.
You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.
A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.
As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:

Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)
Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution.
If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.
Verify that the user has already received a copy of these materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.
You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:

Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.
Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.

You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.
Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.
If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY

BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries

If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).

To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the library's name and an idea of what it does.
Copyright (C) year  name of author

This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published
by the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the library
`Frob' (a library for tweaking knobs) written by James Random Hacker.

signature of Ty Coon, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!

Concept Index

/

/etc/hostname
`/etc/nsswitch.conf'
4

4.n BSD Unix
_

__va_copy
_POSIX_OPTION_ORDER environment variable.
_POSIX_SAVED_IDS
a

abort signal
aborting a program
absolute file name
absolute priority
absolute value functions
accepting connections
access permission for a file
access, testing for
accessing directories
address of socket
address space, address space
alarm signal
alarms, setting
alignment (in obstacks)
alignment (with malloc)
alloca disadvantages
alloca function
allocating pseudo-terminals
allocation (obstacks)
allocation debugging
allocation hooks, for malloc
allocation of memory with malloc
allocation size of string
allocation statistics
alphabetic character, alphabetic character
alphanumeric character, alphanumeric character
append-access files
argc (program argument count)
argp (program argument parser)
argp parser functions
ARGP_HELP_FMT environment variable
argument parsing with argp
argument promotion
argument vectors, null-character separated
arguments (variadic functions)
arguments, how many
arguments, to program
argv (program argument vector)
argz vectors (string vectors)
arithmetic expansion
array comparison functions
array copy functions
array search function
array sort function
ASCII character
assertions
attributes of a file
automatic freeing
automatic memory allocation
automatic storage class
automatic storage with variable size
b

background job
background job, launching
backtrace
backtrace_fd
backtrace_symbols
base (of floating point number)
baud rate
Berkeley Unix
Bessel functions
bias (of floating point number exponent)
big-endian
binary I/O to a stream
binary search function (for arrays)
binary stream
binding a socket address
blank character, blank character
block I/O to a stream
blocked signals
blocked signals, checking for
blocking signals
blocking signals, in a handler
bootstrapping, and services
break condition, detecting
break condition, generating
breaking a string into tokens
broken pipe signal
broken-down time, broken-down time
BSD compatibility library
BSD compatibility library.
BSD Unix
buffering of streams
buffering, controlling
bugs, reporting
bus error
butterfly
byte order conversion, for socket
byte stream
c

C++ streams
calendar time
calendar time and broken-down time
calendar, Gregorian
calling variadic functions
canonical input processing
capacity limits, POSIX
carrier detect
case conversion of characters
catching signals
categories for locales
change working directory
changing the locale
changing the size of a block (malloc)
changing the size of a block (obstacks)
channels
character case conversion
character predicates
character testing
checking for pending signals
child process, child process, child process
child process signal
chunks
classes, floating-point
classification of characters
cleaning up a stream
clearing terminal input queue
client
clock ticks
clock, high accuracy
close-on-exec (file descriptor flag)
closing a file descriptor
closing a socket
closing a stream
collating strings
combining locales
command argument syntax
command arguments, parsing
command line arguments
command substitution
communication style (of a socket)
comparing strings and arrays
Comparison Function
compiling
complex exponentiation functions
complex logarithm functions
complex numbers
complex trigonometric functions
concatenating strings
configurations, all supported
configuring
conjugate complex numbers
connecting a socket
connection
consistency checking
consistency checking, of heap
constants, constants
continue signal
control character, control character
control operations on files
controlling process
controlling terminal
controlling terminal, access to
controlling terminal, determining
controlling terminal, setting
conversion specifications (printf)
conversion specifications (scanf)
converting byte order
converting case of characters
converting file descriptor to stream
converting floats to integers
converting group ID to group name
converting group name to group ID
converting host address to name
converting host name to address
converting network name to network number
converting network number to network name
converting port number to service name
converting service name to port number
converting string to collation order
converting strings to numbers
converting user ID to user name
converting user name to user ID
cookie, for custom stream
copy-on-write page fault
copying strings and arrays
cpu priority
CPU time, CPU time, CPU time
create on open (file status flag)
creating a directory
creating a FIFO special file
creating a pipe
creating a pipe to a subprocess
creating a process
creating a socket
creating a socket pair
creating special files
cube root function
currency symbols
current limit
current working directory
custom streams
customizing printf
d

data loss on sockets
databases
datagram socket
datagrams, transmitting
date
Daylight Saving Time
decimal digit character
decimal-point separator
declaration (compared to definition)
declaring variadic functions
decompose complex numbers
default action (for a signal)
default action for a signal
default argument promotions
default value, and NSS
defining new printf conversions
definition (compared to declaration)
delayed suspend character
deleting a directory
deleting a file
delivery of signals
descriptors and streams
digit character, digit character
directories, accessing
directories, creating
directories, deleting
directory
directory entry
directory hierarchy
directory stream
disadvantages of alloca
DISCARD character
division by zero
DNS
DNS server unavailable
domain (of socket)
domain error
domain name
Domain Name System
dot notation, for Internet addresses
DSUSP character
duplicating file descriptors
dynamic memory allocation, dynamic memory allocation
e

EBCDIC
echo of terminal input
effective group ID
effective user ID
efficiency and malloc
efficiency and obstacks
efficiency of chunks
EINTR, and restarting interrupted primitives
elapsed time, elapsed time
encryption
end of file, on a stream
end-of-file, on a file descriptor
environment
environment access
environment representation
environment variable
environment vectors, null-character separated
envz vectors (environment vectors)
EOF character
EOL character
EOL2 character
epoch
ERASE character
errno
error codes
error messages, in argp
error reporting
errors, mathematical
establishing a handler
ethers
EUC
EUC-JP
exception, exception
exclusive lock
exec functions
execing a program
executable
executing a file
exit status
exit status value
exiting a program
expansion of shell words
exponent (of floating point number)
exponentiation functions
extending printf
extracting file descriptor from stream
f

fcntl function
feature test macros
field splitting
FIFO special file
file access permission
file access time
file attribute modification time
file attributes
file creation mask
file descriptor flags
file descriptor sets, for select
file descriptors, standard
file locks
file modification time
file name
file name component
file name errors
file name resolution
file name translation flags
file names, multiple
file owner
file permission bits
file pointer
file position
file positioning on a file descriptor
file positioning on a stream
file status flags
files, accessing
filtering i/o through subprocess
flag character (printf)
flag character (scanf)
flags for sigaction
flags, file name translation
flags, open-time action
floating point
floating point, IEEE
floating type measurements
floating-point classes
floating-point exception
flow control, terminal
flushing a stream
flushing terminal output queue
foreground job
foreground job, launching
forking a process
format string, for printf
format string, for scanf
formatted input from a stream
formatted messages
formatted output to a stream
FP arithmetic
FQDN
frame, real memory
freeing (obstacks)
freeing memory
freeing memory allocated with malloc
fully buffered stream
function prototypes (variadic)
g

gamma function
gcvt_r
gencat
generation of signals
generic i/o control operations
globbing
graphic character, graphic character
Gregorian calendar
group
group database
group ID
group name
group owner of a file
grouping of digits
growing objects (in obstacks)
h

handling multiple signals
hangup signal
hard limit
hard link
header files
heap consistency checking
heap, dynamic allocation from
heap, freeing memory from
hexadecimal digit character, hexadecimal digit character
hidden bit (of floating point number mantissa)
hierarchy, directory
high-priority data
high-resolution time
holes in files
home directory
HOME environment variable
hook functions (of custom streams)
host address, Internet
host name
hostname
hosts
hosts database
how many arguments
hyperbolic functions, hyperbolic functions
i

identifying terminals
IEEE 754
IEEE floating point
IEEE floating point representation
IEEE Std 1003.1
IEEE Std 1003.2
ignore action for a signal
illegal instruction
impossible events
independent channels
inexact exception
infinity
initial signal actions
inode number
input available signal
input conversions, for scanf
input from multiple files
installation tools
installing
integer
integer division functions
integer type range
integer type width
interactive signals, from terminal
interactive stop signal
internal representation
internationalization
Internet host address
Internet namespace, for sockets
interprocess communication, with FIFO
interprocess communication, with pipes
interprocess communication, with signals
interprocess communication, with sockets
interrupt character
interrupt signal
interrupt-driven input
interrupting primitives
interval
interval timer, setting
INTR character
invalid exception
inverse complex hyperbolic functions
inverse complex trigonometric functions
inverse hyperbolic functions
inverse trigonometric functions
invocation of program
IOCTLs
ISO 10646
ISO 2022
ISO 6937
ISO C
ISO-2022-JP
ISO/IEC 9945-1
ISO/IEC 9945-2
j

job
job control
job control functions
job control is optional
job control signals
job control, enabling, job control, enabling
k

Kermit the frog
kernel call
kernel header files
KILL character
kill signal
killing a process
Korn Shell
l

LANG environment variable
LANG environment variable
launching jobs
LC_ALL environment variable
LC_ALL environment variable
LC_COLLATE environment variable
LC_CTYPE environment variable
LC_MESSAGES environment variable
LC_MESSAGES environment variable
LC_MONETARY environment variable
LC_NUMERIC environment variable
LC_TIME environment variable
leap second
length of string
level, for socket options
library
limit
limits on resource usage
limits, file name length
limits, floating types
limits, integer types
limits, link count of files
limits, number of open files
limits, number of processes
limits, number of supplementary group IDs
limits, pipe buffer size
limits, POSIX
limits, program argument size
limits, terminal input queue
limits, time zone name length
line buffered stream
line speed
lines (in a text file)
link
link, hard
link, soft
link, symbolic
linked channels
listening (sockets)
literals
little-endian
LNEXT character
load average
local namespace, for sockets
local network address number
local time
locale categories
locale, changing
locales
locking pages
logarithm functions
login name
login name, determining
LOGNAME environment variable
long jumps
long-named options
longjmp
loss of data on sockets
lost resource signal
lower-case character, lower-case character
m

macros
main function
malloc debugger
malloc function
mantissa (of floating point number)
matching failure, in scanf
math errors
mathematical constants
maximum
maximum field width (scanf)
maximum limit
maximum possible integer
measurements of floating types
memory allocation
memory lock
memory mapped file
memory mapped I/O
memory page
merging of signals
MIN termios slot
minimum
minimum field width (printf)
mininum possible integer
mixing descriptors and streams
modem disconnect
modem status lines
monetary value formatting
multi-threaded application
multibyte character
multibyte character string
multibyte string
multiple names for one file
multiplexing input
multiply-add
n

name of running program
name of socket
Name Service Switch
name space
names of signals
namespace (of socket)
NaN, NaN
Netgroup
netgroup
network byte order
network number
network protocol
networks
networks database
NIS
NIS domain name, NIS domain name, NIS domain name
nisplus, and booting
nisplus, and completeness
NLSPATH environment variable
NLSPATH environment variable
non-blocking open
non-local exit, from signal handler
non-local exits
noncanonical input processing
normalization functions (floating-point)
normalized floating point number
not a number
NSS
`nsswitch.conf'
null character
null pointer constant
null wide character
number of arguments passed
number syntax, parsing
numeric value formatting
o

obstack status
obstacks
open-time action flags
opening a file
opening a file descriptor
opening a pipe
opening a pseudo-terminal pair
opening a socket
opening a socket pair
opening a stream
Optimization
optimizing NSS
option parsing with argp
optional arguments
optional POSIX features
orientation, stream, orientation, stream
orphaned process group
out-of-band data
output conversions, for printf
output possible signal
overflow exception
owner of a file
p

packet
page boundary
page fault
page fault, copy-on-write
page frame
page, memory
page, virtual memory
paging, paging
parameter promotion
parent directory
parent process, parent process
parity checking
parsing a template string
parsing numbers (in formatted input)
parsing program arguments
parsing tokens from a string
passwd
password database
PATH environment variable
pause function
peeking at input
pending signals
pending signals, checking for
period of time
permission to access a file
persona
physical address
physical memory
pi (trigonometric constant)
pipe
pipe signal
pipe to a subprocess
port number
positioning a file descriptor
positioning a stream
positive difference
POSIX
POSIX capacity limits
POSIX optional features
POSIX.1
POSIX.2
power functions
precision (of floating point number)
precision (printf)
predicates on arrays
predicates on characters
predicates on strings
preemptive scheduling
primitives, interrupting
printing character, printing character
priority of a process
priority, absolute
process, process
process completion
process group functions
process group ID
process group leader
process groups
process ID
process image
process lifetime
process priority
process signal mask
process termination
processor time, processor time
profiling alarm signal
profiling timer
program
program argument syntax
program arguments
program arguments, parsing
program error signals
program name
program startup
program termination
program termination signals
programming your own streams
project complex numbers
protocol (of socket)
protocol family
protocols
protocols database
prototypes for variadic functions
pseudo-random numbers
pseudo-terminals
punctuation character, punctuation character
pushing input back
q

quick sort function (for arrays)
QUIT character
quit signal, quit signal
quote removal
r

race conditions, relating to job control
race conditions, relating to signals
radix (of floating point number)
raising signals
random numbers
random-access files
range error
range of integer type
read lock
reading from a directory
reading from a file descriptor
reading from a socket
reading from a stream, by blocks
reading from a stream, by characters
reading from a stream, formatted
ready to run
real group ID
real user ID
real-time timer
realtime CPU scheduling
realtime processing
realtime scheduling
receiving datagrams
record locking
redirecting input and output
reentrant functions
reentrant NSS functions
relative file name
removal of quotes
removing a file
removing macros that shadow functions
renaming a file
reporting bugs
reporting errors
REPRINT character
reserved names
resource limits
restarting interrupted primitives
restrictions on signal handler functions
root directory
Rot13
rpc
runnable process
running a command
s

saved set-group-ID
saved set-user-ID
scanning the group list
scanning the user list
scatter-gather
scheduling, traditional
search function (for arrays)
search functions (for strings)
seed (for random numbers)
seeking on a file descriptor
seeking on a stream
segmentation violation
sending a datagram
sending signals
sequential-access files
server
services
services database
session, session
session leader
setting an alarm
setuid programs
setuid programs and file access
severity class, severity class
sgettext, sgettext
shadow
shadowing functions with macros
shared lock
shared memory
shell
shift state
shrinking objects
shutting down a socket
sigaction flags
sigaction function
SIGCHLD, handling of
sign (of floating point number)
signal, signal
signal action
signal actions
signal flags
signal function
signal handler function
signal mask
signal messages
signal names
signal number
signal set
signals, generating
signedness
significand (of floating point number)
SIGTTIN, from background job
SIGTTOU, from background job
simple time
single-byte string
size of string
SJIS
socket
socket address (name) binding
socket domain
socket namespace
socket option level
socket options
socket pair
socket protocol
socket shutdown
socket, client actions
socket, closing
socket, connecting
socket, creating
socket, initiating a connection
sockets, accepting connections
sockets, listening
sockets, server actions
soft limit
soft link
sort function (for arrays)
sparse files
special files
special functions
specified action (for a signal)
speed of execution
square root function
stable sorting
standard dot notation, for Internet addresses
standard environment variables
standard error file descriptor
standard error stream
standard file descriptors
standard input file descriptor
standard input stream
standard output file descriptor
standard output stream
standard streams
standards
START character
startup of program
stateful, stateful, stateful, stateful, stateful, stateful
static memory allocation
static storage class
STATUS character
status codes
status of a file
status of obstack
sticky bit
STOP character
stop signal
stopped job
stopped jobs, continuing
stopped jobs, detecting
storage allocation
stream (sockets)
stream orientation, stream orientation
stream, for I/O to a string
streams and descriptors
streams, and file descriptors
streams, C++
streams, standard
string
string allocation
string collation functions
string comparison functions
string concatenation functions
string copy functions
string length
string literal
string search functions
string stream
string vectors, null-character separated
string, representation of
style of communication (of a socket)
subshell
substitution of variables and commands
successive signals
summer time
SunOS
supplementary group IDs
SUSP character
suspend character
SVID
swap space
symbolic link
symbolic link, opening
synchronizing, synchronizing
syntax error messages, in argp
syntax, for program arguments
syntax, for reading numbers
sysconf, sysconf, sysconf, sysconf
system call
system call number
System V Unix
t

TCP (Internet protocol)
template, for printf
template, for scanf
TERM environment variable
terminal flow control
terminal identification
terminal input queue
terminal input queue, clearing
terminal input signal
terminal line control functions
terminal line speed, terminal line speed
terminal mode data types
terminal mode functions
terminal modes, BSD
terminal output queue
terminal output queue, flushing
terminal output signal
terminated jobs, detecting
termination signal
testing access permission
testing exit status of child process
text stream
thrashing
thread of control
threads
ticks, clock
tilde expansion
time
TIME termios slot
time zone
time zone database
time, elapsed
time, high precision
timer, profiling
timer, real-time
timer, virtual
timers, setting
timespec
timeval
timing error in signal handling
TMPDIR environment variable
tokenizing strings
tools, for installing library
transmitting datagrams
tree, directory
triangulation
trigonometric functions
type measurements, floating
type measurements, integer
type modifier character (printf)
type modifier character (scanf)
typeahead buffer
TZ environment variable
u

UCS-2
UCS-4
ulps
umask
unbuffered stream
unconstrained memory allocation
undefining macros that shadow functions
underflow exception
Unicode
Unix, Berkeley
Unix, System V
unlinking a file
unordered comparison
unreading characters
upgrading from libc5
upper-case character, upper-case character
urgent data signal
urgent socket condition
usage limits
usage messages, in argp
user accounting database
user database
user ID
user ID, determining
user name
user signals
usual file name errors
UTF-16
UTF-7
UTF-8, UTF-8
v

va_copy
variable number of arguments
variable substitution
variable-sized arrays
variadic function argument access
variadic function prototypes
variadic functions
variadic functions, calling
virtual time alarm signal
virtual timer
volatile declarations
w

waiting for a signal
waiting for completion of child process
waiting for input or output
WERASE character
whitespace character, whitespace character
wide character
wide character string, wide character string
width of integer type
wildcard expansion
wint_t
word expansion
working directory
write lock
writing to a file descriptor
writing to a socket
writing to a stream, by blocks
writing to a stream, by characters
writing to a stream, formatted
y

YP
YP domain name, YP domain name, YP domain name
z

zero divide

Type Index

_

__ftw64_func_t
__ftw_func_t
__nftw64_func_t
__nftw_func_t
b

blkcnt64_t
blkcnt_t
c

cc_t
clock_t
comparison_fn_t
cookie_close_function
cookie_io_functions_t
cookie_read_function
cookie_seek_function
cookie_write_function
d

dev_t
DIR
div_t
e

enum mcheck_status
f

fd_set
FILE
fpos64_t
fpos_t
g

gid_t
glob64_t
glob_t
i

iconv_t
imaxdiv_t
ino64_t
ino_t
j

jmp_buf
l

ldiv_t
lldiv_t
m

mbstate_t
mode_t
n

nlink_t
o

off64_t
off_t
p

pid_t
printf_arginfo_function
printf_function
ptrdiff_t
r

regex_t
regmatch_t
regoff_t
s

sig_atomic_t
sighandler_t
sigjmp_buf
sigset_t
size_t
speed_t
ssize_t
stack_t
struct __gconv_step
struct __gconv_step_data
struct aiocb
struct aiocb64
struct aioinit
struct argp
struct argp_child
struct argp_option
struct argp_state
struct dirent
struct ENTRY
struct exit_status
struct flock
struct fstab
struct FTW
struct group
struct hostent
struct if_nameindex
struct in6_addr
struct in_addr
struct iovec
struct itimerval
struct lconv
struct linger
struct mallinfo
struct mntent
struct netent
struct ntptimeval, struct ntptimeval
struct obstack
struct option
struct passwd
struct printf_info
struct protoent
struct random_data
struct rlimit
struct rlimit64
struct rusage
struct sched_param
struct servent
struct sgttyb
struct sigaction
struct sigstack
struct sigvec
struct sockaddr
struct sockaddr_in
struct sockaddr_in6
struct sockaddr_un
struct stat
struct stat64
struct termios
struct timespec
struct timeval
struct timex, struct timex
struct timezone
struct tm
struct tms
struct utimbuf
struct utmp
struct utmpx
struct utsname
struct vtimes
t

tcflag_t
time_t
u

ucontext_t
uid_t
union wait
v

va_list
VISIT
w

wchar_t
wctrans_t
wctype_t
wint_t
wordexp_t

Function and Macro Index

_

__fbufsize
__flbf
__fpending
__fpurge
__freadable
__freading
__fsetlocking
__fwritable
__fwriting
__va_copy
_Exit
_exit
_flushlbf
_tolower
_toupper
a

a64l
abort
abs
accept
access
acos
acosf
acosh
acoshf
acoshl
acosl
addmntent
addseverity
adjtime
adjtimex
aio_cancel
aio_cancel64
aio_error
aio_error64
aio_fsync
aio_fsync64
aio_init
aio_read
aio_read64
aio_return
aio_return64
aio_suspend
aio_suspend64
aio_write
aio_write64
alarm
alloca
alphasort
alphasort64
argp_error
argp_failure
argp_help
argp_parse
argp_state_help
argp_usage
argz_add
argz_add_sep
argz_append
argz_count
argz_create
argz_create_sep
argz_delete
argz_extract
argz_insert
argz_next
argz_replace
argz_stringify
asctime
asctime_r
asin
asinf
asinh
asinhf
asinhl
asinl
asprintf
assert
assert_perror
atan
atan2
atan2f
atan2l
atanf
atanh
atanhf
atanhl
atanl
atexit
atof
atoi
atol
atoll
b

backtrace
backtrace_symbols
backtrace_symbols_fd
basename, basename
bcmp
bcopy
bind
bind_textdomain_codeset
bindtextdomain
brk
bsearch
btowc
bzero
c

cabs
cabsf
cabsl
cacos
cacosf
cacosh
cacoshf
cacoshl
cacosl
calloc
canonicalize_file_name
carg
cargf
cargl
casin
casinf
casinh
casinhf
casinhl
casinl
catan
catanf
catanh
catanhf
catanhl
catanl
catclose
catgets
catopen
cbc_crypt
cbrt
cbrtf
cbrtl
ccos
ccosf
ccosh
ccoshf
ccoshl
ccosl
ceil
ceilf
ceill
cexp
cexpf
cexpl
cfgetispeed
cfgetospeed
cfmakeraw
cfree
cfsetispeed
cfsetospeed
cfsetspeed
chdir
chmod, chmod
chown
cimag
cimagf
cimagl
clearenv
clearerr
clearerr_unlocked
clock
clog
clog10
clog10f
clog10l
clogf
clogl
close
closedir
closelog
confstr
conj
conjf
conjl
connect
copysign
copysignf
copysignl
cos
cosf
cosh
coshf
coshl
cosl
cpow
cpowf
cpowl
cproj
cprojf
cprojl
creal
crealf
creall
creat
creat64
crypt
crypt_r
csin
csinf
csinh
csinhf
csinhl
csinl
csqrt
csqrtf
csqrtl
ctan
ctanf
ctanh
ctanhf
ctanhl
ctanl
ctermid
ctime
ctime_r
cuserid
d

dcgettext
dcngettext
DES_FAILED
des_setparity
dgettext
difftime
dirfd
dirname
div
dngettext
drand48
drand48_r
drem
dremf
dreml
DTTOIF
dup
dup2
e

ecb_crypt
ecvt
ecvt_r
encrypt
encrypt_r
endfsent
endgrent
endhostent
endmntent
endnetent
endnetgrent
endprotoent
endpwent
endservent
endutent
endutxent
envz_add
envz_entry
envz_get
envz_merge
envz_strip
erand48
erand48_r
erf
erfc
erfcf
erfcl
erff
erfl
execl
execle
execlp
execv
execve
execvp
exit
exp
exp10
exp10f
exp10l
exp2
exp2f
exp2l
expf
expl
expm1
expm1f
expm1l
f

fabs
fabsf
fabsl
fchdir
fchmod
fchown
fclean
fclose
fcloseall
fcntl
fcvt
fcvt_r
FD_CLR
FD_ISSET
FD_SET
FD_ZERO
fdatasync
fdim
fdimf
fdiml
fdopen
feclearexcept
fedisableexcept
feenableexcept
fegetenv
fegetexcept
fegetexceptflag
fegetround
feholdexcept
feof
feof_unlocked
feraiseexcept
ferror
ferror_unlocked
fesetenv
fesetexceptflag
fesetround
fetestexcept
feupdateenv
fflush
fflush_unlocked
fgetc
fgetc_unlocked
fgetgrent
fgetgrent_r
fgetpos
fgetpos64
fgetpwent
fgetpwent_r
fgets
fgets_unlocked
fgetwc
fgetwc_unlocked
fgetws
fgetws_unlocked
fileno
fileno_unlocked
finite
finitef
finitel
flockfile
floor
floorf
floorl
fma
fmaf
fmal
fmax
fmaxf
fmaxl
fmemopen
fmin
fminf
fminl
fmod
fmodf
fmodl
fmtmsg
fnmatch
fopen
fopen64
fopencookie
fork
forkpty
fpathconf
fpclassify
fprintf
fputc
fputc_unlocked
fputs
fputs_unlocked
fputwc
fputwc_unlocked
fputws
fputws_unlocked
fread
fread_unlocked
free
freopen
freopen64
frexp
frexpf
frexpl
fscanf
fseek
fseeko
fseeko64
fsetpos
fsetpos64
fstat
fstat64
fsync
ftell
ftello
ftello64
ftruncate
ftruncate64
ftrylockfile
ftw
ftw64
funlockfile
fwide
fwprintf
fwrite
fwrite_unlocked
fwscanf
g

gamma
gammaf
gammal
gcvt
get_avphys_pages
get_current_dir_name
get_nprocs
get_nprocs_conf
get_phys_pages
getc
getc_unlocked
getchar
getchar_unlocked
getcontext
getcwd
getdate
getdate_r
getdelim
getdomainnname
getegid
getenv
geteuid
getfsent
getfsfile
getfsspec
getgid
getgrent
getgrent_r
getgrgid
getgrgid_r
getgrnam
getgrnam_r
getgroups
gethostbyaddr
gethostbyaddr_r
gethostbyname
gethostbyname2
gethostbyname2_r
gethostbyname_r
gethostent
gethostid
gethostname
getitimer
getline
getloadavg
getlogin
getmntent
getmntent_r
getnetbyaddr
getnetbyname
getnetent
getnetgrent
getnetgrent_r
getopt
getopt_long
getopt_long_only
getpagesize
getpass
getpeername
getpgid
getpgrp, getpgrp
getpid
getppid
getpriority
getprotobyname
getprotobynumber
getprotoent
getpt
getpwent
getpwent_r
getpwnam
getpwnam_r
getpwuid
getpwuid_r
getrlimit
getrlimit64
getrusage
gets
getservbyname
getservbyport
getservent
getsid
getsockname
getsockopt
getsubopt
gettext
gettimeofday
getuid
getumask
getutent
getutent_r
getutid
getutid_r
getutline
getutline_r
getutmp
getutmpx
getutxent
getutxid
getutxline
getw
getwc
getwc_unlocked
getwchar
getwchar_unlocked
getwd
glob
glob64
globfree
globfree64
gmtime
gmtime_r
grantpt
gsignal
gtty
h

hasmntopt
hcreate
hcreate_r
hdestroy
hdestroy_r
hsearch
hsearch_r
htonl
htons
hypot
hypotf
hypotl
i

iconv
iconv_close
iconv_open
if_freenameindex
if_indextoname
if_nameindex
if_nametoindex
IFTODT
ilogb
ilogbf
ilogbl
imaxabs
imaxdiv
index
inet_addr
inet_aton
inet_lnaof
inet_makeaddr
inet_netof
inet_network
inet_ntoa
inet_ntop
inet_pton
infnan
initgroups
initstate
initstate_r
innetgr
ioctl
isalnum
isalpha
isascii
isatty
isblank
iscntrl
isdigit
isfinite
isgraph
isgreater
isgreaterequal
isinf
isinff
isinfl
isless
islessequal
islessgreater
islower
isnan, isnan
isnanf
isnanl
isnormal
isprint
ispunct
isspace
isunordered
isupper
iswalnum
iswalpha
iswblank
iswcntrl
iswctype
iswdigit
iswgraph
iswlower
iswprint
iswpunct
iswspace
iswupper
iswxdigit
isxdigit
j

j0
j0f
j0l
j1
j1f
j1l
jn
jnf
jnl
jrand48
jrand48_r
k

kill
killpg
l

l64a
labs
lcong48
lcong48_r
ldexp
ldexpf
ldexpl
ldiv
lfind
lgamma
lgamma_r
lgammaf
lgammaf_r
lgammal
lgammal_r
link
lio_listio
lio_listio64
listen
llabs
lldiv
llrint
llrintf
llrintl
llround
llroundf
llroundl
localeconv
localtime
localtime_r
log
log10
log10f
log10l
log1p
log1pf
log1pl
log2
log2f
log2l
logb, logb
logbf, logbf
logbl, logbl
logf
login
login_tty
logl
logout
logwtmp
longjmp
lrand48
lrand48_r
lrint
lrintf
lrintl
lround
lroundf
lroundl
lsearch
lseek
lseek64
lstat
lstat64
m

main
makecontext
mallinfo
malloc
mallopt
matherr
mblen
mbrlen
mbrtowc
mbsinit
mbsnrtowcs
mbsrtowcs
mbstowcs
mbtowc
mcheck
memalign
memccpy
memchr
memcmp
memcpy
memfrob
memmem
memmove
mempcpy
memrchr
memset
mkdir
mkdtemp
mkfifo
mknod
mkstemp
mktemp
mktime
mlock
mlockall
mmap
mmap64
modf
modff
modfl
mount
mprobe
mrand48
mrand48_r
mremap
msync
mtrace
munlock
munlockall
munmap
muntrace
n

nan
nanf
nanl
nanosleep
nearbyint
nearbyintf
nearbyintl
nextafter
nextafterf
nextafterl
nexttoward
nexttowardf
nexttowardl
nftw
nftw64
ngettext
nice
nl_langinfo
notfound
nrand48
nrand48_r
ntohl
ntohs
ntp_adjtime
ntp_gettime
o

obstack_1grow
obstack_1grow_fast
obstack_alignment_mask
obstack_alloc
obstack_base
obstack_blank
obstack_blank_fast
obstack_chunk_alloc
obstack_chunk_free
obstack_chunk_size
obstack_copy
obstack_copy0
obstack_finish
obstack_free
obstack_grow
obstack_grow0
obstack_init
obstack_int_grow
obstack_int_grow_fast
obstack_next_free
obstack_object_size, obstack_object_size
obstack_printf
obstack_ptr_grow
obstack_ptr_grow_fast
obstack_room
obstack_vprintf
offsetof
on_exit
open
open64
open_memstream
open_obstack_stream
opendir
openlog
openpty
p

parse_printf_format
pathconf
pause
pclose
perror
pipe
popen
posix_memalign
pow
pow10
pow10f
pow10l
powf
powl
pread
pread64
printf
printf_size
printf_size_info
psignal
ptsname
ptsname_r
putc
putc_unlocked
putchar
putchar_unlocked
putenv
putpwent
puts
pututline
pututxline
putw
putwc
putwc_unlocked
putwchar
putwchar_unlocked
pwrite
pwrite64
q

qecvt
qecvt_r
qfcvt
qfcvt_r
qgcvt
qsort
r

raise
rand
rand_r
random
random_r
rawmemchr
read
readdir
readdir64
readdir64_r
readdir_r
readlink
readv
realloc
realpath
recv
recvfrom
regcomp
regerror
regexec
regfree
register_printf_function
remainder
remainderf
remainderl
remove
rename
rewind
rewinddir
rindex
rint
rintf
rintl
rmdir
round
roundf
roundl
s

S_ISBLK
S_ISCHR
S_ISDIR
S_ISFIFO
S_ISLNK
S_ISREG
S_ISSOCK
S_TYPEISMQ
S_TYPEISSEM
S_TYPEISSHM
sbrk
scalb
scalbf
scalbl
scalbln
scalblnf
scalblnl
scalbn
scalbnf
scalbnl
scandir
scandir64
scanf
sched_get_priority_max
sched_get_priority_min
sched_getparam
sched_getscheduler
sched_rr_get_interval
sched_setparam
sched_setscheduler
sched_yield
seed48
seed48_r
seekdir
select
send
sendto
setbuf
setbuffer
setcontext
setdomainname
setegid
setenv
seteuid
setfsent
setgid
setgrent
setgroups
sethostent
sethostid
sethostname
setitimer
setjmp
setkey
setkey_r
setlinebuf
setlocale
setlogmask
setmntent
setnetent
setnetgrent
setpgid
setpgrp
setpriority
setprotoent
setpwent
setregid
setreuid
setrlimit
setrlimit64
setservent
setsid
setsockopt
setstate
setstate_r
settimeofday
setuid
setutent
setutxent
setvbuf
shutdown
sigaction
sigaddset
sigaltstack
sigblock
sigdelset
sigemptyset
sigfillset
siginterrupt
sigismember
siglongjmp
sigmask
signal
signbit
significand
significandf
significandl
sigpause
sigpending
sigprocmask
sigsetjmp
sigsetmask
sigstack
sigsuspend
sigvec
sin
sincos
sincosf
sincosl
sinf
sinh
sinhf
sinhl
sinl
sleep
snprintf
socket
socketpair
sprintf
sqrt
sqrtf
sqrtl
srand
srand48
srand48_r
srandom
srandom_r
sscanf
ssignal
stat
stat64
stime
stpcpy
stpncpy
strcasecmp
strcasestr
strcat
strchr
strchrnul
strcmp
strcoll
strcpy
strcspn
strdup
strdupa
strerror
strerror_r
strfmon
strfry
strftime
strlen
strncasecmp
strncat
strncmp
strncpy
strndup
strndupa
strnlen
strpbrk
strptime
strrchr
strsep
strsignal
strspn
strstr
strtod
strtof
strtoimax
strtok
strtok_r
strtol
strtold
strtoll
strtoq
strtoul
strtoull
strtoumax
strtouq
strverscmp
strxfrm
stty
success
SUN_LEN
swapcontext
swprintf
swscanf
symlink
sync
syscall
sysconf
sysctl
syslog
system
sysv_signal
t

tan
tanf
tanh
tanhf
tanhl
tanl
tcdrain
tcflow
tcflush
tcgetattr
tcgetpgrp
tcgetsid
tcsendbreak
tcsetattr
tcsetpgrp
tdelete
tdestroy
telldir
TEMP_FAILURE_RETRY
tempnam
textdomain
tfind
tgamma
tgammaf
tgammal
time
timegm
timelocal
times
tmpfile
tmpfile64
tmpnam
tmpnam_r
toascii
tolower
toupper
towctrans
towlower
towupper
trunc
truncate
truncate64
truncf
truncl
tryagain
tsearch
ttyname
ttyname_r
twalk
tzset
u

ulimit
umask
umount
umount2
uname
unavail
ungetc
ungetwc
unlink
unlockpt
unsetenv
updwtmp
utime
utimes
utmpname
utmpxname
v

va_alist
va_arg
va_dcl
va_end
va_start, va_start
valloc
vasprintf
versionsort
versionsort64
vfork
vfprintf
vfscanf
vfwprintf
vfwscanf
vlimit
vprintf
vscanf
vsnprintf
vsprintf
vsscanf
vswprintf
vswscanf
vsyslog
vtimes
vwprintf
vwscanf
w

wait
wait3
wait4
waitpid
WCOREDUMP
wcpcpy
wcpncpy
wcrtomb
wcscasecmp
wcscat
wcschr
wcschrnul
wcscmp
wcscoll
wcscpy
wcscspn
wcsdup
wcsftime
wcslen
wcsncasecmp
wcsncat
wcsncmp
wcsncpy
wcsnlen
wcsnrtombs
wcspbrk
wcsrchr
wcsrtombs
wcsspn
wcsstr
wcstod
wcstof
wcstoimax
wcstok
wcstol
wcstold
wcstoll
wcstombs
wcstoq
wcstoul
wcstoull
wcstoumax
wcstouq
wcswcs
wcsxfrm
wctob
wctomb
wctrans
wctype
WEXITSTATUS
WIFEXITED
WIFSIGNALED
WIFSTOPPED
wmemchr
wmemcmp
wmemcpy
wmemmove
wmempcpy
wmemset
wordexp
wordfree
wprintf
write
writev
wscanf
WSTOPSIG
WTERMSIG
y

y0
y0f
y0l
y1
y1f
y1l
yn
ynf
ynl

Variable and Constant Macro Index

(

(*__gconv_end_fct)
(*__gconv_fct)
(*__gconv_init_fct)
_

__free_hook
__malloc_hook
__malloc_initialize_hook
__memalign_hook
__realloc_hook
_BSD_SOURCE
_Complex_I
_FILE_OFFSET_BITS
_GNU_SOURCE
_IOFBF
_IOLBF
_IONBF
_ISOC99_SOURCE
_LARGEFILE64_SOURCE
_LARGEFILE_SOURCE
_PATH_FSTAB
_PATH_MNTTAB
_PATH_MOUNTED
_PATH_UTMP
_PATH_WTMP
_POSIX2_C_DEV
_POSIX2_C_VERSION
_POSIX2_FORT_DEV
_POSIX2_FORT_RUN
_POSIX2_LOCALEDEF
_POSIX2_SW_DEV
_POSIX_C_SOURCE
_POSIX_CHOWN_RESTRICTED
_POSIX_JOB_CONTROL
_POSIX_NO_TRUNC
_POSIX_SAVED_IDS
_POSIX_SOURCE
_POSIX_VDISABLE, _POSIX_VDISABLE
_POSIX_VERSION
_REENTRANT
_SC_2_C_DEV
_SC_2_FORT_DEV
_SC_2_FORT_RUN
_SC_2_LOCALEDEF
_SC_2_SW_DEV
_SC_2_VERSION
_SC_AIO_LISTIO_MAX
_SC_AIO_MAX
_SC_AIO_PRIO_DELTA_MAX
_SC_ARG_MAX
_SC_ASYNCHRONOUS_IO
_SC_ATEXIT_MAX
_SC_AVPHYS_PAGES, _SC_AVPHYS_PAGES
_SC_BC_BASE_MAX
_SC_BC_DIM_MAX
_SC_BC_SCALE_MAX
_SC_BC_STRING_MAX
_SC_CHAR_BIT
_SC_CHAR_MAX
_SC_CHAR_MIN
_SC_CHARCLASS_NAME_MAX
_SC_CHILD_MAX
_SC_CLK_TCK
_SC_COLL_WEIGHTS_MAX
_SC_DELAYTIMER_MAX
_SC_EQUIV_CLASS_MAX
_SC_EXPR_NEST_MAX
_SC_FSYNC
_SC_GETGR_R_SIZE_MAX
_SC_GETPW_R_SIZE_MAX
_SC_INT_MAX
_SC_INT_MIN
_SC_JOB_CONTROL
_SC_LINE_MAX
_SC_LOGIN_NAME_MAX
_SC_LONG_BIT
_SC_MAPPED_FILES
_SC_MB_LEN_MAX
_SC_MEMLOCK
_SC_MEMLOCK_RANGE
_SC_MEMORY_PROTECTION
_SC_MESSAGE_PASSING
_SC_MQ_OPEN_MAX
_SC_MQ_PRIO_MAX
_SC_NGROUPS_MAX
_SC_NL_ARGMAX
_SC_NL_LANGMAX
_SC_NL_MSGMAX
_SC_NL_NMAX
_SC_NL_SETMAX
_SC_NL_TEXTMAX
_SC_NPROCESSORS_CONF, _SC_NPROCESSORS_CONF
_SC_NPROCESSORS_ONLN, _SC_NPROCESSORS_ONLN
_SC_NZERO
_SC_OPEN_MAX
_SC_PAGESIZE, _SC_PAGESIZE, _SC_PAGESIZE
_SC_PHYS_PAGES, _SC_PHYS_PAGES
_SC_PII
_SC_PII_INTERNET
_SC_PII_INTERNET_DGRAM
_SC_PII_INTERNET_STREAM
_SC_PII_OSI
_SC_PII_OSI_CLTS
_SC_PII_OSI_COTS
_SC_PII_OSI_M
_SC_PII_SOCKET
_SC_PII_XTI
_SC_PRIORITIZED_IO
_SC_PRIORITY_SCHEDULING
_SC_REALTIME_SIGNALS
_SC_RTSIG_MAX
_SC_SAVED_IDS
_SC_SCHAR_MAX
_SC_SCHAR_MIN
_SC_SELECT
_SC_SEM_NSEMS_MAX
_SC_SEM_VALUE_MAX
_SC_SEMAPHORES
_SC_SHARED_MEMORY_OBJECTS
_SC_SHRT_MAX
_SC_SHRT_MIN
_SC_SIGQUEUE_MAX
_SC_STREAM_MAX
_SC_SYNCHRONIZED_IO
_SC_T_IOV_MAX
_SC_THREAD_ATTR_STACKADDR
_SC_THREAD_ATTR_STACKSIZE
_SC_THREAD_DESTRUCTOR_ITERATIONS
_SC_THREAD_KEYS_MAX
_SC_THREAD_PRIO_INHERIT
_SC_THREAD_PRIO_PROTECT
_SC_THREAD_PRIORITY_SCHEDULING
_SC_THREAD_PROCESS_SHARED
_SC_THREAD_SAFE_FUNCTIONS
_SC_THREAD_STACK_MIN
_SC_THREAD_THREADS_MAX
_SC_THREADS
_SC_TIMER_MAX
_SC_TIMERS
_SC_TTY_NAME_MAX
_SC_TZNAME_MAX
_SC_UCHAR_MAX
_SC_UINT_MAX
_SC_UIO_MAXIOV
_SC_ULONG_MAX
_SC_USHRT_MAX
_SC_VERSION, _SC_VERSION
_SC_WORD_BIT
_SC_XOPEN_CRYPT
_SC_XOPEN_ENH_I18N
_SC_XOPEN_LEGACY
_SC_XOPEN_REALTIME
_SC_XOPEN_REALTIME_THREADS
_SC_XOPEN_SHM
_SC_XOPEN_UNIX
_SC_XOPEN_VERSION
_SC_XOPEN_XCU_VERSION
_SC_XOPEN_XPG2
_SC_XOPEN_XPG3
_SC_XOPEN_XPG4
_SVID_SOURCE
_THREAD_SAFE
_XOPEN_SOURCE
_XOPEN_SOURCE_EXTENDED
a

ABDAY_1
ABDAY_2
ABDAY_3
ABDAY_4
ABDAY_5
ABDAY_6
ABDAY_7
ABMON_1
ABMON_10
ABMON_11
ABMON_12
ABMON_2
ABMON_3
ABMON_4
ABMON_5
ABMON_6
ABMON_7
ABMON_8
ABMON_9
ACCOUNTING
AF_FILE
AF_INET
AF_LOCAL
AF_UNIX
AF_UNSPEC
aliases
ALT_DIGITS
ALTWERASE
AM_STR
ARG_MAX
argp_err_exit_status
ARGP_ERR_UNKNOWN
ARGP_HELP_BUG_ADDR
ARGP_HELP_DOC
ARGP_HELP_EXIT_ERR
ARGP_HELP_EXIT_OK
ARGP_HELP_LONG
ARGP_HELP_LONG_ONLY
ARGP_HELP_POST_DOC
ARGP_HELP_PRE_DOC
ARGP_HELP_SEE
ARGP_HELP_SHORT_USAGE
ARGP_HELP_STD_ERR
ARGP_HELP_STD_HELP
ARGP_HELP_STD_USAGE
ARGP_HELP_USAGE
ARGP_IN_ORDER
ARGP_KEY_ARG
ARGP_KEY_ARGS
ARGP_KEY_END
ARGP_KEY_ERROR
ARGP_KEY_FINI
ARGP_KEY_HELP_ARGS_DOC
ARGP_KEY_HELP_DUP_ARGS_NOTE
ARGP_KEY_HELP_EXTRA
ARGP_KEY_HELP_HEADER
ARGP_KEY_HELP_POST_DOC
ARGP_KEY_HELP_PRE_DOC
ARGP_KEY_INIT
ARGP_KEY_NO_ARGS
ARGP_KEY_SUCCESS
ARGP_LONG_ONLY
ARGP_NO_ARGS
ARGP_NO_ERRS
ARGP_NO_EXIT
ARGP_NO_HELP
ARGP_PARSE_ARGV0
argp_program_bug_address
argp_program_version
argp_program_version_hook
ARGP_SILENT
b

B0
B110
B115200
B1200
B134
B150
B1800
B19200
B200
B230400
B2400
B300
B38400
B460800
B4800
B50
B57600
B600
B75
B9600
BC_BASE_MAX
BC_DIM_MAX
BC_SCALE_MAX
BC_STRING_MAX
BOOT_TIME, BOOT_TIME
BRKINT
BUFSIZ
c

CCTS_OFLOW
CHAR_MAX
CHAR_MIN
CHILD_MAX
CIGNORE
CLK_TCK
CLOCAL
CLOCKS_PER_SEC
CODESET
COLL_WEIGHTS_MAX
COREFILE
CREAD
CRNCYSTR
CRTS_IFLOW
CS5
CS6
CS7
CS8
CSIZE
CSTOPB
CURRENCY_SYMBOL
d

D_FMT
D_T_FMT
DAY_1
DAY_2
DAY_3
DAY_4
DAY_5
DAY_6
DAY_7
daylight
DBL_DIG
DBL_EPSILON
DBL_MANT_DIG
DBL_MAX
DBL_MAX_10_EXP
DBL_MAX_EXP
DBL_MIN
DBL_MIN_10_EXP
DBL_MIN_EXP
DEAD_PROCESS, DEAD_PROCESS
DECIMAL_POINT
DES_DECRYPT
DES_ENCRYPT
DES_HW
DES_SW
DESERR_BADPARAM
DESERR_HWERROR
DESERR_NOHWDEVICE
DESERR_NONE
DT_BLK
DT_CHR
DT_DIR
DT_FIFO
DT_REG
DT_SOCK
DT_UNKNOWN
e

E2BIG
EACCES
EADDRINUSE
EADDRNOTAVAIL
EADV
EAFNOSUPPORT
EAGAIN
EALREADY
EAUTH
EBACKGROUND
EBADE
EBADF, EBADF
EBADFD
EBADMSG
EBADR
EBADRPC
EBADRQC
EBADSLT
EBFONT
EBUSY
ECHILD
ECHO
ECHOCTL
ECHOE
ECHOK
ECHOKE
ECHONL
ECHOPRT
ECHRNG
ECOMM
ECONNABORTED
ECONNREFUSED
ECONNRESET
ED
EDEADLK
EDEADLOCK
EDESTADDRREQ
EDIED
EDOM
EDOTDOT
EDQUOT
EEXIST
EFAULT
EFBIG
EFTYPE
EGRATUITOUS
EGREGIOUS
EHOSTDOWN
EHOSTUNREACH
EIDRM
EIEIO
EILSEQ
EINPROGRESS
EINTR
EINVAL, EINVAL
EIO
EISCONN
EISDIR
EISNAM
EL2HLT
EL2NSYNC
EL3HLT
EL3RST
ELIBACC
ELIBBAD
ELIBEXEC
ELIBMAX
ELIBSCN
ELNRNG
ELOOP
EMEDIUMTYPE
EMFILE
EMLINK
EMPTY, EMPTY
EMSGSIZE
EMULTIHOP
ENAMETOOLONG
ENAVAIL
ENEEDAUTH
ENETDOWN
ENETRESET
ENETUNREACH
ENFILE
ENOANO
ENOBUFS
ENOCSI
ENODATA
ENODEV
ENOENT
ENOEXEC
ENOLCK
ENOLINK
ENOMEDIUM
ENOMEM
ENOMSG
ENONET
ENOPKG
ENOPROTOOPT
ENOSPC
ENOSR
ENOSTR
ENOSYS
ENOTBLK
ENOTCONN
ENOTDIR
ENOTEMPTY
ENOTNAM
ENOTSOCK
ENOTSUP
ENOTTY, ENOTTY
ENOTUNIQ
environ
ENXIO
EOF
EOPNOTSUPP
EOVERFLOW
EPERM
EPFNOSUPPORT
EPIPE
EPROCLIM
EPROCUNAVAIL
EPROGMISMATCH
EPROGUNAVAIL
EPROTO
EPROTONOSUPPORT
EPROTOTYPE
EQUIV_CLASS_MAX
ERA
ERA_D_FMT
ERA_D_T_FMT
ERA_T_FMT
ERA_YEAR
ERANGE
EREMCHG
EREMOTE
EREMOTEIO
ERESTART
EROFS
ERPCMISMATCH
errno
ESHUTDOWN
ESOCKTNOSUPPORT
ESPIPE
ESRCH
ESRMNT
ESTALE
ESTRPIPE
ethers
ETIME
ETIMEDOUT
ETOOMANYREFS
ETXTBSY
EUCLEAN
EUNATCH
EUSERS
EWOULDBLOCK
EXDEV
EXFULL
EXIT_FAILURE
EXIT_SUCCESS
EXPR_NEST_MAX
EXTA
EXTB
f

F_DUPFD
F_GETFD
F_GETFL
F_GETLK
F_GETOWN
F_OK
F_RDLCK
F_SETFD
F_SETFL
F_SETLK
F_SETLKW
F_SETOWN
F_UNLCK
F_WRLCK
FD_CLOEXEC
FD_SETSIZE
FE_DFL_ENV
FE_DIVBYZERO
FE_DOWNWARD
FE_INEXACT
FE_INVALID
FE_NOMASK_ENV
FE_OVERFLOW
FE_TONEAREST
FE_TOWARDZERO
FE_UNDERFLOW
FE_UPWARD
FILENAME_MAX
FLT_DIG
FLT_EPSILON
FLT_MANT_DIG
FLT_MAX
FLT_MAX_10_EXP
FLT_MAX_EXP
FLT_MIN
FLT_MIN_10_EXP
FLT_MIN_EXP
FLT_RADIX
FLT_ROUNDS
FLUSHO
FOPEN_MAX
FP_FAST_FMA
FP_ILOGB0
FP_ILOGBNAN
FP_INFINITE
FP_NAN
FP_NORMAL
FP_SUBNORMAL
FP_ZERO
FPE_DECOVF_TRAP
FPE_FLTDIV_TRAP
FPE_FLTOVF_TRAP
FPE_FLTUND_TRAP
FPE_INTDIV_TRAP
FPE_INTOVF_TRAP
FPE_SUBRNG_TRAP
FRAC_DIGITS
FSETLOCKING_BYCALLER
FSETLOCKING_INTERNAL
FSETLOCKING_QUERY
FSTAB
FSTAB_RO
FSTAB_RQ
FSTAB_RW
FSTAB_SW
FSTAB_XX
FTW_CHDIR
FTW_D
FTW_DEPTH
FTW_DNR
FTW_DP
FTW_F
FTW_MOUNT
FTW_NS
FTW_PHYS
FTW_SL
FTW_SLN
g

getdate_err
GLOB_ABORTED
GLOB_ALTDIRFUNC
GLOB_APPEND
GLOB_BRACE
GLOB_DOOFFS
GLOB_ERR
GLOB_MAGCHAR
GLOB_MARK
GLOB_NOCHECK
GLOB_NOESCAPE
GLOB_NOMAGIC
GLOB_NOMATCH
GLOB_NOSORT
GLOB_NOSPACE
GLOB_ONLYDIR
GLOB_PERIOD
GLOB_TILDE
GLOB_TILDE_CHECK
group
GROUPING
h

h_errno
HOST_NOT_FOUND
hosts
HUGE_VAL
HUGE_VALF
HUGE_VALL
HUPCL
i

I
ICANON
ICRNL
IEXTEN
IFNAMSIZ
IGNBRK
IGNCR
IGNPAR
IMAXBEL
in6addr_any
in6addr_loopback
INADDR_ANY
INADDR_BROADCAST
INADDR_LOOPBACK
INADDR_NONE
INFINITY
INIT_PROCESS, INIT_PROCESS
INLCR
INPCK
INT_CURR_SYMBOL
INT_FRAC_DIGITS
INT_MAX
INT_MIN
INT_N_CS_PRECEDES
INT_N_SEP_BY_SPACE
INT_N_SIGN_POSN
INT_P_CS_PRECEDES
INT_P_SEP_BY_SPACE
INT_P_SIGN_POSN
IPPORT_RESERVED
IPPORT_USERRESERVED
ISIG
ISTRIP
ITIMER_PROF
ITIMER_REAL
ITIMER_VIRTUAL
IXANY
IXOFF
IXON
l

L_ctermid
L_cuserid
L_INCR
L_SET
L_tmpnam
L_XTND
LANG
LANGUAGE
LC_ALL
LC_COLLATE
LC_CTYPE
LC_MESSAGES
LC_MONETARY
LC_NUMERIC
LC_TIME
LDBL_DIG
LDBL_EPSILON
LDBL_MANT_DIG
LDBL_MAX
LDBL_MAX_10_EXP
LDBL_MAX_EXP
LDBL_MIN
LDBL_MIN_10_EXP
LDBL_MIN_EXP
LINE_MAX
LINK_MAX
LIO_NOP
LIO_READ
LIO_WRITE
LOG_ALERT
LOG_AUTH
LOG_AUTHPRIV
LOG_CRIT
LOG_CRON
LOG_DAEMON
LOG_DEBUG
LOG_EMERG
LOG_ERR
LOG_FTP
LOG_INFO
LOG_LOCAL0
LOG_LOCAL1
LOG_LOCAL2
LOG_LOCAL3
LOG_LOCAL4
LOG_LOCAL5
LOG_LOCAL6
LOG_LOCAL7
LOG_LPR
LOG_MAIL
LOG_NEWS
LOG_NOTICE
LOG_SYSLOG
LOG_USER
LOG_UUCP
LOG_WARNING
LOGIN_PROCESS, LOGIN_PROCESS
LONG_LONG_MAX
LONG_LONG_MIN
LONG_MAX
LONG_MIN
m

M_1_PI
M_2_PI
M_2_SQRTPI
M_E
M_LN10
M_LN2
M_LOG10E
M_LOG2E
M_PI
M_PI_2
M_PI_4
M_SQRT1_2
M_SQRT2
MAP_ANON
MAP_ANONYMOUS
MAP_FIXED
MAP_PRIVATE
MAP_SHARED
MAX_CANON
MAX_INPUT
MAXNAMLEN
MAXSYMLINKS
MB_CUR_MAX
MB_LEN_MAX
MDMBUF
MINSIGSTKSZ
MM_APPL
MM_CONSOLE
MM_ERROR
MM_FIRM
MM_HALT
MM_HARD
MM_INFO
MM_NOSEV
MM_NRECOV
MM_NULLACT
MM_NULLLBL
MM_NULLMC
MM_NULLSEV
MM_NULLTAG
MM_NULLTXT
MM_OPSYS
MM_PRINT
MM_RECOVER
MM_SOFT
MM_UTIL
MM_WARNING
MNTOPT_DEFAULTS
MNTOPT_NOAUTO
MNTOPT_NOSUID
MNTOPT_RO
MNTOPT_RW
MNTOPT_SUID
MNTTYPE_IGNORE
MNTTYPE_NFS
MNTTYPE_SWAP
MON_1
MON_10
MON_11
MON_12
MON_2
MON_3
MON_4
MON_5
MON_6
MON_7
MON_8
MON_9
MON_DECIMAL_POINT
MON_GROUPING
MON_THOUSANDS_SEP
MS_ASYNC
MS_SYNC
MSG_DONTROUTE
MSG_OOB
MSG_PEEK
n

N_CS_PRECEDES
N_SEP_BY_SPACE
N_SIGN_POSN
NAME_MAX
NAN
NCCS
NDEBUG
NEGATIVE_SIGN
netgroup
networks
NEW_TIME, NEW_TIME
NGROUPS_MAX
NL_ARGMAX
NO_ADDRESS
NO_RECOVERY
NOEXPR
NOFLSH
NOKERNINFO
NOSTR
NSIG
NSS_STATUS_NOTFOUND
NSS_STATUS_SUCCESS
NSS_STATUS_TRYAGAIN
NSS_STATUS_UNAVAIL
NULL
o

O_ACCMODE
O_APPEND
O_ASYNC
O_CREAT
O_EXCL
O_EXEC
O_EXLOCK
O_FSYNC
O_IGNORE_CTTY
O_NDELAY
O_NOATIME
O_NOCTTY
O_NOLINK
O_NONBLOCK, O_NONBLOCK
O_NOTRANS
O_RDONLY
O_RDWR
O_READ
O_SHLOCK
O_SYNC
O_TRUNC
O_WRITE
O_WRONLY
obstack_alloc_failed_handler
OLD_TIME, OLD_TIME
ONLCR
ONOEOT
OPEN_MAX
OPOST
optarg
opterr
optind
OPTION_ALIAS
OPTION_ARG_OPTIONAL
OPTION_DOC
OPTION_HIDDEN
OPTION_NO_USAGE
optopt
OXTABS
p

P_CS_PRECEDES
P_SEP_BY_SPACE
P_SIGN_POSN
P_tmpdir
PA_CHAR
PA_DOUBLE
PA_FLAG_LONG
PA_FLAG_LONG_DOUBLE
PA_FLAG_LONG_LONG
PA_FLAG_MASK
PA_FLAG_PTR
PA_FLAG_SHORT
PA_FLOAT
PA_INT
PA_LAST
PA_POINTER
PA_STRING
PARENB
PARMRK
PARODD
passwd
PATH_MAX
PENDIN
PF_CCITT
PF_FILE
PF_IMPLINK
PF_INET
PF_INET6
PF_ISO
PF_LOCAL
PF_NS
PF_ROUTE
PF_UNIX
PI
PIPE_BUF
PM_STR
POSITIVE_SIGN
PRIO_MAX
PRIO_MIN
PRIO_PGRP
PRIO_PROCESS
PRIO_USER
program_invocation_name
program_invocation_short_name
PROT_EXEC
PROT_READ
PROT_WRITE
protocols
PWD
r

R_OK
RADIXCHAR
RAND_MAX
RE_DUP_MAX
RLIM_INFINITY
RLIM_NLIMITS
RLIMIT_AS
RLIMIT_CORE
RLIMIT_CPU
RLIMIT_DATA
RLIMIT_FSIZE
RLIMIT_NOFILE
RLIMIT_OFILE
RLIMIT_RSS
RLIMIT_STACK
rpc
RUN_LVL, RUN_LVL
s

S_IEXEC
S_IFBLK
S_IFCHR
S_IFDIR
S_IFIFO
S_IFLNK
S_IFMT
S_IFREG
S_IFSOCK
S_IREAD
S_IRGRP
S_IROTH
S_IRUSR
S_IRWXG
S_IRWXO
S_IRWXU
S_ISGID
S_ISUID
S_ISVTX
S_IWGRP
S_IWOTH
S_IWRITE
S_IWUSR
S_IXGRP
S_IXOTH
S_IXUSR
SA_NOCLDSTOP
SA_ONSTACK
SA_RESTART
SC_SSIZE_MAX
SCHAR_MAX
SCHAR_MIN
SEEK_CUR
SEEK_END
SEEK_SET
services
shadow
SHRT_MAX
SHRT_MIN
SIG_BLOCK
SIG_DFL
SIG_ERR
SIG_IGN
SIG_SETMASK
SIG_UNBLOCK
SIGABRT
SIGALRM
SIGBUS
SIGCHLD
SIGCLD
SIGCONT
SIGEMT
SIGFPE
SIGHUP
SIGILL
SIGINFO
SIGINT
SIGIO
SIGIOT
SIGKILL
SIGLOST
signgam
SIGPIPE
SIGPOLL
SIGPROF
SIGQUIT
SIGSEGV
SIGSTKSZ
SIGSTOP
SIGSYS
SIGTERM
SIGTRAP
SIGTSTP
SIGTTIN
SIGTTOU
SIGURG
SIGUSR1
SIGUSR2
SIGVTALRM
SIGWINCH
SIGXCPU
SIGXFSZ
SOCK_DGRAM
SOCK_RAW
SOCK_STREAM
SOL_SOCKET
SS_DISABLE
SS_ONSTACK
SSIZE_MAX
stderr
STDERR_FILENO
stdin
STDIN_FILENO
stdout
STDOUT_FILENO
STREAM_MAX
SV_INTERRUPT
SV_ONSTACK
SV_RESETHAND
sys_siglist
t

T_FMT
T_FMT_AMPM
TCIFLUSH
TCIOFF
TCIOFLUSH
TCION
TCOFLUSH
TCOOFF
TCOON
TCSADRAIN
TCSAFLUSH
TCSANOW
TCSASOFT
THOUSANDS_SEP
THOUSEP
timezone
TMP_MAX
TOSTOP
TRY_AGAIN
tzname
TZNAME_MAX
u

UCHAR_MAX
UINT_MAX
ULONG_LONG_MAX
ULONG_MAX
USER_PROCESS, USER_PROCESS
USHRT_MAX
v

VDISCARD
VDSUSP
VEOF
VEOL
VEOL2
VERASE
VINTR
VKILL
VLNEXT
VMIN
VQUIT
VREPRINT
VSTART
VSTATUS
VSTOP
VSUSP
VTIME
VWERASE
w

W_OK
WCHAR_MAX, WCHAR_MAX
WCHAR_MIN
WEOF, WEOF
x

X_OK
y

YESEXPR
YESSTR

Program and File Index

-

-lbsd-compat, -lbsd-compat
/

/etc/group
/etc/hosts
/etc/localtime
/etc/networks
/etc/passwd
/etc/protocols
/etc/services
/share/lib/zoneinfo
a

argp.h
argz.h
arpa/inet.h
assert.h
b

bsd-compat, bsd-compat
c

cd
chgrp
chown
complex.h, complex.h, complex.h
ctype.h, ctype.h, ctype.h
d

dirent.h, dirent.h, dirent.h, dirent.h, dirent.h
e

envz.h
errno.h, errno.h, errno.h, errno.h
execinfo.h
f

fcntl.h, fcntl.h, fcntl.h, fcntl.h, fcntl.h, fcntl.h, fcntl.h, fcntl.h
float.h
fnmatch.h
g

gcc
gconv.h
grp.h, grp.h, grp.h
h

hostid
hostname
i

iconv.h, iconv.h, iconv.h
k

kill
ksh
l

langinfo.h
limits.h, limits.h, limits.h, limits.h, limits.h
locale
locale.h, locale.h
localtime
ls
m

malloc.h, malloc.h, malloc.h
math.h, math.h, math.h, math.h, math.h
mcheck.h
mkdir
n

netdb.h, netdb.h, netdb.h, netdb.h
netinet/in.h, netinet/in.h, netinet/in.h, netinet/in.h
o

obstack.h
p

printf.h, printf.h
pwd.h, pwd.h
s

setjmp.h, setjmp.h
sh
signal.h, signal.h, signal.h, signal.h, signal.h, signal.h, signal.h, signal.h, signal.h, signal.h, signal.h
stdarg.h, stdarg.h
stddef.h
stdint.h
stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h, stdio.h
stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h, stdlib.h
string.h, string.h, string.h, string.h, string.h, string.h, string.h, string.h
sys/param.h
sys/resource.h, sys/resource.h, sys/resource.h
sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h, sys/socket.h
sys/stat.h, sys/stat.h, sys/stat.h, sys/stat.h, sys/stat.h, sys/stat.h, sys/stat.h, sys/stat.h
sys/time.h, sys/time.h, sys/time.h
sys/times.h, sys/times.h
sys/timex.h
sys/types.h, sys/types.h, sys/types.h, sys/types.h, sys/types.h, sys/types.h, sys/types.h
sys/un.h
sys/utsname.h
sys/vlimit.h
sys/vtimes.h
sys/wait.h, sys/wait.h, sys/wait.h
t

termios.h, termios.h
time.h, time.h, time.h, time.h, time.h
u

ulimit.h
umask
unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h, unistd.h
utime.h
utmp.h, utmp.h
utmpx.h
v

varargs.h
w

wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h, wchar.h
wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h, wctype.h
z

zoneinfo

Footnotes

(1)

Additions are welcome. Send appropriate information to @email{bug-glibc-manual@gnu.org
(2)

Actually, the terminal-specific functions are implemented with IOCTLs on many platforms.
(3)

Now you might ask why this information is duplicated. The answer is that we want to make it possible to link directly with these shared objects.
(4)

There is a second explanation: we were too lazy to change the Makefiles to allow the generation of shared objects not starting with `lib' but don't tell this to anybody.

This document was generated on 2 May 2001 using the texi2html translator version 1.51.


Accounting Utilities Manual

GNU Accounting Utilities

Version 6.3.2

10 March 1998

Noel Cragg (noel@gnu.ai.mit.edu)

Table of Contents

  • Preface
    • A Note on File Names and Locations
    • History of the Accounting Utilities
  • ac
    • Flags
    • Problems
        • The FTP Problem
        • The Shutdown/Reboot Problem
        • Stupid System V Machines
  • accton
    • Flags
  • last
    • Flags
    • Problems
        • The Clock Change Problem
        • The Ftp Problem
  • lastcomm
    • Flags
  • sa
    • Flags
    • Problems
      • mips sa

Copyright (C) 1993, 1996, 1997 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

Preface

Way back a long time ago, Thompson and Ritchie were sitting opposite one another at the commissary, sipping coffees and discussing their evolving behemoth.

"This behemoth of ours," said Ken, "is becoming rather popular, wouldn't you say?" "Yes," said Dennis. "Every time I want to do a compilation, I have to wait for hours and hours. It's infuriating." They both agreed that the load on their system was too great. Both sighed, picked up their mugs, and went back to the workbench. Little did they know that an upper-management type was sitting just within earshot of their conversation.

"We are AT&T Bell Laboratories, aren't we?" the upper-management type thought to himself. "Well, what is our organization best known for?" The brill-cream in his hair glistened. "Screwing people out of lots of money, of course! If there were some way that we could keep tabs on users and charge them through the nose for their CPU time..."

The accounting utilities were born.

Seriously though, the accouting utilities can provide a system administrator with useful information about system usage--connections, programs executed, and utilization of system resources.

Information about users--their connect time, location, programs executed, and the like--is automatically recored in files by init and login. Four of them are of interest to us: wtmp, which has records for each login and logout; acct, which records each command that was run; usracct and savacct, which contain summaries of the information in acct by user and command, respectively. Each of the accounting utilities reports or summarizes information stored in these files.

ac
prints statistics about users' connect time. ac can tell you how long a particular user or group of users were connected to your system, printing totals by day or for all of the entries in the wtmp file.
accton
turns accounting on or off.
last
lists the logins on the system, most recent first. With last, you can search the wtmp file for a particular user or terminal name (to which the user was connected). Of special interest are two fake users, `reboot' and `shutdown', which are recorded when the system is shut down or reboots.
lastcomm
lists the commands executed on the system, most recent first, showing the run state of each command. With last, you can search the acct file for a particular user, terminal, or command.
sa
summarizes the information in the acct file into the savacct and usracct file. It also generates reports about commands, giving the number of invocations, cpu time used, average core usage, etc.
dump-acct
dump-utmp
display acct and utmp files in a human-readable format.

For more detailed information on any of these programs, check the chapter with the program title.

A Note on File Names and Locations

The wtmp and acct files seem to live in different places and have different names for every variant of u*x that exists. The name wtmp seems to be standard for the login accounting file, but the process accounting file might be acct or pacct on your system. To find the actual locations and names of these files on your system, specify the --help flag to any of the programs in this package and the information will dumped to standard output.

Regardless of the names and locations of files on your system, this manual will refer to the login accounting file as wtmp and the process accounting files as acct, savacct, and usracct.

History of the Accounting Utilities

I don't have any idea who originally wrote these utilities. If anybody does, please send some mail to noel@gnu.ai.mit.edu and I'll add your information here!

Since the first alpha versions of this software in late 1993, many people have contributed to the package. They are (in alphabetical order):

Eric Backus <ericb@lsid.hp.com>
Suggested fixes for HP-UX 9.05 using /bin/cc: configure assumed you were using gcc and tacked on -Wall etc. He also noticed that file_rd.c was doing pointer arithmetic on a void * pointer (non-ANSI).
Christoph Badura <bad@flatlin.ka.sub.org>
Christoph was a BIG HELP in computing statistics, most notably k*sec stuff! He also did Xenix testing and contributed some Makefile fixes and output optimizations.
Michael Calwas <calwas@ttd.teradyne.com>
Fixed bugs in mktime.c.
Alan Cox <iiitac@pyr.swan.ac.uk>
Original Linux kernel accounting patches.
Scott Crosby <root@hypercube.res.cmu.edu>
Suggested idea behind --sort-real-time for sa.
Solar Designer <solar@false.com>
Fixed off-by one error in allocations in sa.
Dirk Eddelbuettel <edd@miles.econ.queensu.ca>
Managed bug-fixes & etc. for Debian distribution, as well as the architect of merge of GNU + Debian distributions. A big thanks to Dirk for kicking me back into gear again after a long period of no work on this project.
Jason Grant <jamalcol@pc-5530.bc.rogers.wave.ca>
Identified a buffer-overrun bug in sa.
Kaveh R. Ghazi <ghazi@caip.rutgers.edu>
Tested the package on many systems with compilers other than gcc. Fixed K&R C support.
Susan Kleinmann <sgk@sgk.tiac.net>
Contributed excellent man pages!
Marek Michalkiewicz <marekm@i17linuxb.ists.pwr.wroc.pl>
Suggested the --ip-address flag for last.
David S. Miller <davem@caip.rutgers.edu>
Noticed missing GNU-standard makefile rules.
Walter Mueller <walt@pi4.informatik.uni-mannheim.de>
Noticed install target was missing, and corrected a typo for prefix in Makefile.in.
Ian Murdock <imurdock@gnu.ai.mit.edu>
Tracked down miscellaneous bugs in sa.c under Linux. Added Debian package maintenance files.
Luc I. Suryo <root@patriots.nl.mugnet.org>
Suggested the --user flag for lastcomm.
Pedro A M Vazquez <vazquez@iqm.unicamp.br>
Fixed bugs in sa.c and tested under FreeBSD.
Marco van Wieringen <Marco.van.Wieringen@mcs.nl.mugnet.org>
Modified (wrote?) Linux kernel accounting patches.

ac

The ac command prints out a report of connect time (in hours) based on the logins/logouts in the current wtmp file. A total is also printed out.

The accounting file wtmp is maintained by init and login. Neither of these programs creates the file; if the file is not there, no accounting is done. To begin accounting, create the file with a length of zero. NOTE: the wtmp file can get really big, really fast. You might want to trim it every once and a while.

GNU ac works nearly the same u*x ac, though it's a little smarter in its printing out of daily totals--it actually prints every day, rather than skipping to the date of the next entry in the wtmp file.

Flags

All of the original ac's options have been implemented, and a few have been added. Normally, when ac is invoked, the output looks like this:

        total 93867.14

where total is the number of hours of connect time for every entry in the wtmp file. The rest of the flags modify the output in one way or another.

-d
--daily-totals
Print totals for each day rather than just one big total at the end. The output looks like this:
Jul  3  total     1.17
Jul  4  total     2.10
Jul  5  total     8.23
Jul  6  total     2.10
Jul  7  total     0.30
-p
--individual-totals
Print time totals for each user in addition to the usual everything-lumped-into-one value. It looks like:
        bob       8.06
        goff      0.60
        maley     7.37
        root      0.12
        total    16.15
people
Print out the sum total of the connect time used by all of the users included in people. Note that people is a space separated list of valid user names; wildcards are not allowed.
-f filename
--file filename
Read from the file filename instead of the system's wtmp file.
--complain
When the wtmp file has a problem (a time-warp, missing record, or whatever), print out an appropriate error.
--reboots
Reboot records are not written at the time of a reboot, but when the system restarts; therefore, it is impossible to know exactly when the reboot occurred. Users may have been logged into the system at the time of the reboot, and many ac's automatically count the time between the login and the reboot record against the user (even though all of that time shouldn't be, perhaps, if the system is down for a long time, for instance). If you want to count this time, include the flag. To make ac behave like the one that was distributed with your OS, include this flag.
--supplants
Sometimes a logout record is not written for a specific terminal, so the time that the last user accrued cannot be calculated. If you want to include the time from the user's login to the next login on the terminal (though probably incorrect), include this flag. To make ac behave like the one that was distributed with your OS, include this flag.
--timewarps
Sometimes, entries in a wtmp file will suddenly jump back into the past without a clock change record occurring. It is impossible to know how long a user was logged in when this occurs. If you want to count the time between the login and the time warp against the user, include this flag. To make ac behave like the one that was distributed with your OS, include this flag.
--compatibility
This is shorthand for typing out the three above options.
-a
--all-days
If we're printing daily totals, print a record for every day instead of skipping intervening days where there is no login activity. Without this flag, time accrued during those intervening days gets listed under the next day where there is login activity.
-y
--print-year
Print out the year when displaying dates.
--print-zeros
If a total for any category (save the grand total) is zero, print it. The default is to suppress printing.
--debug
Print verbose internal information.
--tw-leniency value
Set the time warp leniency value (in seconds). Records in wtmp files might be slightly out of order (most notably when two logins occur within a one-second period -- the second one gets written first). By default, this value is set to 1 second. Some wtmp's are really screwed up (Suns) and require a larger value here. If the program notices this problem, time is not assigned to users unless the --timewarps flag is used. See the Problems section for more information.
--tw-suspicious value
Set the time warp suspicious value (in seconds). If two records in the wtmp file are farther than this number of seconds apart, there is a problem with the wtmp file (or your machine hasn't been used in a year). If the program notices this problem, time is not assigned to users unless the --timewarps flag is used.
-V
--version
Print ac's version number.
-h
--help
Print ac's usage string and default locations of system files to standard output.

Problems

For no fault of ac's, if two logins occur at the same time (within a second of each other), each login process will try to write an entry to the wtmp file. With file system overhead, it is forseeable that the entries would get written in the wrong order. GNU ac automatically compensates for this, but some other acs may not... beware.

The FTP Problem

I've tested the standard ac in Ultrix 4.2 (DECstation/DECsystem), SunOS 4.1.1 (Sun3, Sun4, Sparc), Mach 2.5 (Omron/Luna), and DomainOS 10.3 (DN3500). All of these acs have trouble parsing entries in which the line is ftp xxxx (xxxx being some number). Whenever these acs see one of these entries, they log everyone out at the time of the entry.

HOW IT HAPPENS: if there is a user logged into the machine when an ftp connection occurs, (minimally) you'll get a login record for the user, a login record for the ftp connection, and the logouts for both afterwards (in either order).

TANGIBLE RESULT: the user who was logged in gets 'logged out' at the time the ftp connection begins, and none of the time spent during or after the ftp connection. Therefore, when you run GNU ac, the totals will most likely be greater than those of your system's ac (provided you specify the other flags that will make GNU ac behave like the system's).

The Shutdown/Reboot Problem

On Suns, init is a little screwed up. For some reason, after a shutdown record is written, a reboot record is written with a time-stamp before the shutdown (less than 30 seconds, usually).

TANGIBLE RESULT: GNU ac will notice the problem, log everyone out (you can specify if you want the time to be added to the user's total) and begin a new day entry based on the time of the out-of-sync record. If you try to print out daily totals, you'll notice that some days might have two or more entries.

SOLUTION: To fix this, a timewarp leniency value has been implemented. If any record is out of order by this number of seconds (defaults to 60) it gets ignored. If you need to change this value (if you think the totals are off because the value is too high), you can change it using the `--timewarp-value' flag. The rationale for the 60 second default is that of all of the machines with this problem, the largest timewarp was 45.

Stupid System V Machines

Some ac's on System V machines (I've tried SGI Indigo & SGI Indy) forget to pay attention to the ut_type field in a struct utmp. As such, they chalk up a lot of time to non-existant processes called LOGIN or runlevel.

TANGIBLE RESULT: The amount of total time reported by the system's ac is really off. Often, it's several times greater than what it should be.

SOLUTION: GNU ac always pays attention to the ut_type record, so there's no possibility of chalking up time to anything but user processes.

accton

accton turns process accounting on or off. To save process accounting information in accountingfile, use:

accton accountingfile

If called with no arguments, it will, by default, stop process accounting.

Flags

-V
--version
Print accton's version number.
-h
--help
Print accton's usage string and default locations of system files to standard output.

last

last looks through the wtmp file (which records all logins/logouts) and prints information about connect times of users. Records are printed from most recent to least recent. Records can be specified by tty and username. tty names can be abbreviated: `last 0' is equivalent to `last tty0'.

Multiple arguments can be specified: `last root console' will print all of the entries for the user root and all entries logged in on the console tty.

The special users reboot and shutdown log in when the system reboots or (surprise) shuts down. `last reboot' will produce a record of reboot times.

If last is interrupted by a quit signal, it prints out how far its search in the wtmp file had reached and then quits:

weerapan  ttyq6    132.162.32.37    Mon Feb 15 19:07 - 19:21  (00:13)
weerapan  ttyq6    132.162.32.37    Mon Feb 15 19:07 - 19:21  (00:13)

interrupted at Mon Feb 15 19:07:52 1993

Flags

This program implements the features of regular u*x last with a few extra flags. When last is invoked with no arguments, the output looks like this:

gr151     ttyp2    ray.cs.oberlin.e Tue Feb 16 17:40   still logged in
jhoggard  ttyp2    csts.cs.oberlin. Tue Feb 16 17:39 - 17:39  (00:00)
jstarr    ttyp1    UNIX5.ANDREW.CMU Tue Feb 16 17:38   still logged in
jberman   ttypb    132.162.32.25    Tue Feb 16 17:34   still logged in
alee      ttyp7    csts.cs.oberlin. Tue Feb 16 17:34   still logged in
jbrick    ttyp2    ocvaxa.cc.oberli Tue Feb 16 17:33 - 17:36  (00:03)
mbastedo  ttypc    ocvaxa.cc.oberli Tue Feb 16 17:25 - 17:26  (00:01)
rgoodste  ttypb    ocvaxa.cc.oberli Tue Feb 16 17:22 - 17:26  (00:03)
huttar    ttyp9    lobby.ti.com     Tue Feb 16 17:19   still logged in
klutz     ttyp3    132.162.32.25    Tue Feb 16 17:14   still logged in
--no-truncate-ftp-entries
When printing out the information, don't chop the number part off of ftp xxxx entries.
-number
-n number
--lines number
Limit the number of lines that last prints.
-f filename
--file filename
Read from the file filename instead of the system's wtmp file.
-y
--print-year
Print out the year when displaying dates.
-s
--print-seconds
Print out seconds when displaying dates and durations.
--complain
When the wtmp file has a problem (a time-warp, missing record, or whatever), print out an appropriate error.
-x
--more-records
Print out run level changes, shutdowns, and time changes in addition to the normal records.
-a
--all-records
Print out all records in the wtmp file.
-i
--ip-address
Some machines store the IP address of a connection in a utmp record. Enabling this option makes last print the IP address instead of the hostname.
--tw-leniency value
Set the time warp leniency value (in seconds). See the ac chapter for information.
--tw-suspicious value
Set the time warp suspicious value (in seconds). See the ac chapter for information.
--debug
Print verbose internal information.
-V
--version
Print last's version number.
-h
--help
Print last's usage string and default locations of system files to standard output.

Problems

The Clock Change Problem

Of the lasts I've tried, all of them have had problems parsing a system clock change. Instead of modifying the entries that have been read, they just ignore the change and give you incorrect values. GNU last knows about clock changes and prints the correct times.

TANGIBLE RESULT: if you diff the output of your last and GNU last, entries after (before, rather) a clock change will be off by the amount of the clock change.

The Ftp Problem

Most lasts that I've examined have the same problem here as ac does--they log everyone out as soon as they see an ftp entry.

TANGIBLE RESULT: GNU last will reflect the correct time spent in an ftp session, so the totals that it gives will most likely be greater than those given by the system last.

lastcomm

lastcomm prints out information about previously executed commands. If no arguments are specified, lastcomm will print info about all of the commands in the acct file (the record file). If called with a command name, user name, or tty name, only records containing those items will be displayed. For example, to find out which users used command `a.out' and which users were logged into `tty0', type:

lastcomm a.out tty0

This will print any entry for which `a.out' or `tty0' matches in any of the record's fields (command, name, or tty). If you want to find only items that match ALL of the arguments on the command line, you must use the '--strict-match' option. For example, to list all of the executions of command `a.out' by user `root' on terminal `tty0', type:

lastcomm --strict-match a.out root tty0

The order of the arguments is not important.

For each entry the following information is printed:

  • command name of the process
  • flags, as recorded by the system accounting routines:
    • S command executed by super-user
    • F command executed after a fork but without a following exec
    • C command run in PDP-11 compatibility mode (VAX only)
    • D command terminated with the generation of a core file
    • X command was terminated with the signal SIGTERM
  • the name of the user who ran the process
  • time the process exited

Flags

This program implements the features of regular u*x lastcomm with a few extra flags. When lastcomm is invoked without arguments, the output looks like this:

nslookup         jberman  ttypb      0.03 secs Tue Feb 16 19:23
comsat           root     __         0.03 secs Tue Feb 16 19:19
uptime           ctilburg __         0.11 secs Tue Feb 16 19:23
sh          F    ctilburg __         0.02 secs Tue Feb 16 19:23
sleep            ctilburg __         0.02 secs Tue Feb 16 19:22
ls               noel     ttyp4      0.19 secs Tue Feb 16 19:23
--strict-match
Print only entries that match all of the arguments on the command line.
--user name
List records for user with name. This is useful if you're trying to match a username that happens to be the same as a command (e.g., ed).
--command name
List records for command name.
--tty name
List records for tty name.
-f filename
--file filename
Read from the file filename instead of the system's acct file.
--debug
Print verbose internal information.
--version
Print lastcomm's version number.
--help
Print lastcomm's usage string and default locations of system files to standard output.

sa

sa summarizes information about previously executed commands as recorded in the acct file. In addition, it condenses this data into the savacct summary file, which contains the number of times the command was called and the system resources used. The information can also be summarized on a per-user basis; sa will save this information into usracct. Usage:

sa [opts] [file]

If no arguments are specified, sa will print information about all of the commands in the acct file. If command names have unprintable characters, or are only called once, sa will sort them into a group called ***other.

If called with a file name as the last argument, sa will use that file instead of acct.

By default, sa will sort the output by sum of user and system time.

The output fields are labeled as follows:

cpu
sum of system and user time in cpu seconds
re
"real time" in cpu seconds
k
cpu-time averaged core usage, in 1k units
avio
average number of I/O operations per execution
tio
total number of I/O operations
k*sec
cpu storage integral (kilo-core seconds)
u
user cpu time in cpu seconds
s
system time in cpu seconds

An asterisk will appear after the name of commands that forked but didn't call exec.

Flags

-a
--list-all-names
Force sa not to sort those command names with unprintable characters and those used only once into the `***other' group.
-b
--sort-sys-user-div-calls
Sort the output by the sum of user and system time divided by the number of calls.
-c
--percentages
Print percentages of total time for the command's user, system, and real time values.
-d
--sort-avio
Sort the output by the average number of disk I/O operations.
-D
--sort-tio
Print and sort the output by the total number of disk I/O operations.
-f
--not-interactive
When using the --threshold option, assume that all answers to interactive queries will be affirmative.
-i
--dont-read-summary-file
Don't read the information in savacct.
-j
--print-seconds
Instead of printing total minutes for each category, print seconds per call.
-k
--sort-cpu-avmem
Sort the output by cpu time average memory usage.
-K
--sort-ksec
Print and sort the output by the cpu-storage integral.
-l
--separate-times
Print separate columns for system and user time; usually the two are added together and listed as cpu.
-m
--user-summary
Print the number of processes and number of CPU minutes on a per-user basis.
-n
--sort-num-calls
Sort the output by the number of calls. This is the default sorting method.
-r
--reverse-sort
Sort output items in reverse order.
-s
--merge
Merge the summarized accounting data into the summary files savacct and usracct.
-t
--print-ratio
For each entry, print the ratio of real time to the sum of system and user times. If the sum of system and user times is too small to report--the sum is zero---*ignore* will appear in this field.
-u
--print-users
For each command in the accounting file, print the userid and command name. After printing all entries, quit. Note: this flag supersedes all others.
-v num
--threshold num
Print commands which were executed num times or fewer and await a reply from the terminal. If the response begins with y, add the command to the **junk** group.
--separate-forks
It really doesn't make any sense to me that the stock version of sa separates statistics for a particular executable depending on whether or not that command forked. Therefore, GNU sa lumps this information together unless this option is specified.
--sort-real-time
Sort the output by the "real time" (elapsed time) for each command.
--debug
Print verbose internal information.
-V
--version
Print sa's version number.
-h
--help
Print sa's usage string and default locations of system files to standard output.

Note: if more than one sorting option is specified, the list will be sorted by the one specified last on the command line.

Problems

I haven't been able to test this on many different machines because the data files grow so big in a short time; our sysadmin would rather save the disk space.

Most versions of sa that I've tested don't pay attention to flags like --print-seconds and --sort-num-calls when printing out commands when combined with the --user-summary or --print-users flags. GNU sa pays attention to these flags if they are applicable.

mips sa

The average memory use is stored as a short rather than a double, so we suffer from round-off errors. GNU sa uses double the whole way through.

This document was generated on 7 November 1998 using the texi2html translator version 1.52.


Using as

The GNU Assembler

January 1994

Dean Elsner, Jay Fenlason & friends

Table of Contents

  • Overview
    • Structure of this Manual
    • The GNU Assembler
    • Object File Formats
    • Command Line
    • Input Files
    • Output (Object) File
    • Error and Warning Messages
  • Command-Line Options
    • Enable Listings: -a[cdhlns]
    • -D
    • Work Faster: -f
    • .include search path: -I path
    • Difference Tables: -K
    • Include Local Labels: -L
    • Assemble in MRI Compatibility Mode: -M
    • Dependency tracking: --MD
    • Name the Object File: -o
    • Join Data and Text Sections: -R
    • Display Assembly Statistics: --statistics
    • Compatible output: --traditional-format
    • Announce Version: -v
    • Suppress Warnings: -W
    • Generate Object File in Spite of Errors: -Z
  • Syntax
    • Preprocessing
    • Whitespace
    • Comments
    • Symbols
    • Statements
    • Constants
      • Character Constants
        • Strings
        • Characters
      • Number Constants
        • Integers
        • Bignums
        • Flonums
  • Sections and Relocation
    • Background
    • Linker Sections
    • Assembler Internal Sections
    • Sub-Sections
    • bss Section
  • Symbols
    • Labels
    • Giving Symbols Other Values
    • Symbol Names
    • The Special Dot Symbol
    • Symbol Attributes
      • Value
      • Type
      • Symbol Attributes: a.out
        • Descriptor
        • Other
      • Symbol Attributes for COFF
        • Primary Attributes
        • Auxiliary Attributes
      • Symbol Attributes for SOM
  • Expressions
    • Empty Expressions
    • Integer Expressions
      • Arguments
      • Operators
      • Prefix Operator
      • Infix Operators
  • Assembler Directives
    • .abort
    • .ABORT
    • .align abs-expr, abs-expr, abs-expr
    • .app-file string
    • .ascii "string"...
    • .asciz "string"...
    • .balign[wl] abs-expr, abs-expr, abs-expr
    • .byte expressions
    • .comm symbol , length
    • .data subsection
    • .def name
    • .desc symbol, abs-expression
    • .dim
    • .double flonums
    • .eject
    • .else
    • .endef
    • .endif
    • .equ symbol, expression
    • .equiv symbol, expression
    • .err
    • .extern
    • .file string
    • .fill repeat , size , value
    • .float flonums
    • .global symbol, .globl symbol
    • .hword expressions
    • .ident
    • .if absolute expression
    • .include "file"
    • .int expressions
    • .irp symbol,values...
    • .irpc symbol,values...
    • .lcomm symbol , length
    • .lflags
    • .line line-number
    • .linkonce [type]
    • .ln line-number
    • .mri val
    • .list
    • .long expressions
    • .macro
    • .nolist
    • .octa bignums
    • .org new-lc , fill
    • .p2align[wl] abs-expr, abs-expr, abs-expr
    • .psize lines , columns
    • .quad bignums
    • .rept count
    • .sbttl "subheading"
    • .scl class
    • .section name
    • .set symbol, expression
    • .short expressions
    • .single flonums
    • .size
    • .sleb128 expressions
    • .skip size , fill
    • .space size , fill
    • .stabd, .stabn, .stabs
    • .string "str"
    • .symver
    • .tag structname
    • .text subsection
    • .title "heading"
    • .type int
    • .val addr
    • .uleb128 expressions
    • .word expressions
    • Deprecated Directives
  • Machine Dependent Features
  • ARC Dependent Features
    • Options
    • Floating Point
    • ARC Machine Directives
  • AMD 29K Dependent Features
    • Options
    • Syntax
      • Macros
      • Special Characters
      • Register Names
    • Floating Point
    • AMD 29K Machine Directives
    • Opcodes
  • ARM Dependent Features
    • Options
    • Syntax
      • Special Characters
      • Register Names
    • Floating Point
    • ARM Machine Directives
    • Opcodes
  • D10V Dependent Features
    • D10V Options
    • Syntax
      • Size Modifiers
      • Sub-Instructions
      • Special Characters
      • Register Names
      • Addressing Modes
      • @WORD Modifier
    • Floating Point
    • Opcodes
  • H8/300 Dependent Features
    • Options
    • Syntax
      • Special Characters
      • Register Names
      • Addressing Modes
    • Floating Point
    • H8/300 Machine Directives
    • Opcodes
  • H8/500 Dependent Features
    • Options
    • Syntax
      • Special Characters
      • Register Names
      • Addressing Modes
    • Floating Point
    • H8/500 Machine Directives
    • Opcodes
  • HPPA Dependent Features
    • Notes
    • Options
    • Syntax
    • Floating Point
    • HPPA Assembler Directives
    • Opcodes
  • 80386 Dependent Features
    • Options
    • AT&T Syntax versus Intel Syntax
    • Opcode Naming
    • Register Naming
    • Opcode Prefixes
    • Memory References
    • Handling of Jump Instructions
    • Floating Point
    • Writing 16-bit Code
    • Notes
  • Intel 80960 Dependent Features
    • i960 Command-line Options
    • Floating Point
    • i960 Machine Directives
    • i960 Opcodes
      • callj
      • Compare-and-Branch
  • M680x0 Dependent Features
    • M680x0 Options
    • Syntax
    • Motorola Syntax
    • Floating Point
    • 680x0 Machine Directives
    • Opcodes
      • Branch Improvement
      • Special Characters
  • MIPS Dependent Features
    • Assembler options
    • MIPS ECOFF object code
    • Directives for debugging information
    • Directives to override the ISA level
    • Directives for extending MIPS 16 bit instructions
    • Directive to mark data as an instruction
    • Directives to save and restore options
  • Hitachi SH Dependent Features
    • Options
    • Syntax
      • Special Characters
      • Register Names
      • Addressing Modes
    • Floating Point
    • SH Machine Directives
    • Opcodes
  • SPARC Dependent Features
    • Options
    • Enforcing aligned data
    • Floating Point
    • Sparc Machine Directives
  • Z8000 Dependent Features
    • Options
    • Syntax
      • Special Characters
      • Register Names
      • Addressing Modes
    • Assembler Directives for the Z8000
    • Opcodes
  • VAX Dependent Features
    • VAX Command-Line Options
    • VAX Floating Point
    • Vax Machine Directives
    • VAX Opcodes
    • VAX Branch Improvement
    • VAX Operands
    • Not Supported on VAX
  • v850 Dependent Features
    • Options
    • Syntax
      • Special Characters
      • Register Names
    • Floating Point
    • V850 Machine Directives
    • Opcodes
  • Reporting Bugs
    • Have you found a bug?
    • How to report bugs
  • Acknowledgements
  • Index

The Free Software Foundation Inc. thanks The Nice Computer Company of Australia for loaning Dean Elsner to write the first (Vax) version of as for Project GNU. The proprietors, management and staff of TNCCA thank FSF for distracting the boss while they got some work done.

Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Overview

This manual is a user guide to the GNU assembler as.

Here is a brief summary of how to invoke as. For details, see section Command-Line Options.

as [ -a[cdhlns][=file] ] [ -D ]  [ --defsym sym=val ]
 [ -f ] [ --gstabs ] [ --help ] [ -I dir ] [ -J ] [ -K ] [ -L ]
 [ --keep-locals ] [ -o objfile ] [ -R ] [ --statistics ] [ -v ]
 [ -version ] [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ]
 [ -mbig-endian | -mlittle-endian ]
 [ -m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]7[t][[d]m[i]] ]
 [ -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t ]
 [ -mthumb | -mall ]
 [ -mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu ]
 [ -EB | -EL ]
 [ -mapcs-32 | -mapcs-26 ]
 [ -O ]
 [ -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
   -Av8plus | -Av8plusa | -Av9 | -Av9a ]
 [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] [ -32 | -64 ]
 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ]
 [ -b ] [ -no-relax ]
 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ]
 [ -nocpp ] [ -EL ] [ -EB ] [ -G num ] [ -mcpu=CPU ]
 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ]
 [ --trap ] [ --break ]
 [ --emulation=name ]
 [ -- | files ... ]
-a[cdhlmns]
Turn on listings, in any of a variety of ways:
-ac
omit false conditionals
-ad
omit debugging directives
-ah
include high-level source
-al
include assembly
-am
include macro expansions
-an
omit forms processing
-as
include symbols
=file
set the name of the listing file
You may combine these options; for example, use `-aln' for assembly listing without forms processing. The `=file' option, if used, must be the last one. By itself, `-a' defaults to `-ahls'.
-D
Ignored. This option is accepted for script compatibility with calls to other assemblers.
--defsym sym=value
Define the symbol sym to be value before assembling the input file. value must be an integer constant. As in C, a leading `0x' indicates a hexadecimal value, and a leading `0' indicates an octal value.
-f
"fast"---skip whitespace and comment preprocessing (assume source is compiler output).
--gstabs
Generate stabs debugging information for each assembler line. This may help debugging assembler code, if the debugger can handle it.
--help
Print a summary of the command line options and exit.
-I dir
Add directory dir to the search list for .include directives.
-J
Don't warn about signed overflow.
-K
Issue warnings when difference tables altered for long displacements.
-L
--keep-locals
Keep (in the symbol table) local symbols. On traditional a.out systems these start with `L', but different systems have different local label prefixes.
-o objfile
Name the object-file output from as objfile.
-R
Fold the data section into the text section.
--statistics
Print the maximum space (in bytes) and total time (in seconds) used by assembly.
--strip-local-absolute
Remove local absolute symbols from the outgoing symbol table.
-v
-version
Print the as version.
--version
Print the as version and exit.
-W
Suppress warning messages.
-w
Ignored.
-x
Ignored.
-Z
Generate an object file even after errors.
-- | files ...
Standard input, or source files to assemble.

The following options are available when as is configured for an ARC processor.

-mbig-endian
Generate "big endian" format output.
-mlittle-endian
Generate "little endian" format output.

The following options are available when as is configured for the ARM processor family.

-m[arm]1 | -m[arm]2 | -m[arm]250 | -m[arm]3 | -m[arm]6 | -m[arm]7[t][[d]m] | -m[arm]v2 | -m[arm]v2a | -m[arm]v3 | -m[arm]v3m | -m[arm]v4 | -m[arm]v4t
Specify which variant of the ARM architecture is the target.
-mthumb | -mall
Enable or disable Thumb only instruction decoding.
-mfpa10 | -mfpa11 | -mfpe-old | -mno-fpu
Select which Floating Point architcture is the target.
-mapcs-32 | -mapcs-26
Select which procedure calling convention is in use.
-EB | -EL
Select either big-endian (-EB) or little-endian (-EL) output.

The following options are available when as is configured for a D10V processor.

-O
Optimize output by parallelizing instructions.

The following options are available when as is configured for the Intel 80960 processor.

-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
Specify which variant of the 960 architecture is the target.
-b
Add code to collect statistics about branches taken.
-no-relax
Do not alter compare-and-branch instructions for long displacements; error if necessary.

The following options are available when as is configured for the Motorola 68000 series.

-l
Shorten references to undefined symbols, to one word instead of two.
-m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060
| -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200
Specify what processor in the 68000 family is the target. The default is normally the 68020, but this can be changed at configuration time.
-m68881 | -m68882 | -mno-68881 | -mno-68882
The target machine does (or does not) have a floating-point coprocessor. The default is to assume a coprocessor for 68020, 68030, and cpu32. Although the basic 68000 is not compatible with the 68881, a combination of the two can be specified, since it's possible to do emulation of the coprocessor instructions with the main processor.
-m68851 | -mno-68851
The target machine does (or does not) have a memory-management unit coprocessor. The default is to assume an MMU for 68020 and up.

The following options are available when as is configured for the SPARC architecture:

-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
-Av8plus | -Av8plusa | -Av9 | -Av9a
Explicitly select a variant of the SPARC architecture. `-Av8plus' and `-Av8plusa' select a 32 bit environment. `-Av9' and `-Av9a' select a 64 bit environment. `-Av8plusa' and `-Av9a' enable the SPARC V9 instruction set with UltraSPARC extensions.
-xarch=v8plus | -xarch=v8plusa
For compatibility with the Solaris v9 assembler. These options are equivalent to -Av8plus and -Av8plusa, respectively.
-bump
Warn when the assembler switches to another architecture.

The following options are available when as is configured for a MIPS processor.

-G num
This option sets the largest size of an object that can be referenced implicitly with the gp register. It is only accepted for targets that use ECOFF format, such as a DECstation running Ultrix. The default value is 8.
-EB
Generate "big endian" format output.
-EL
Generate "little endian" format output.
-mips1
-mips2
-mips3
Generate code for a particular MIPS Instruction Set Architecture level. `-mips1' corresponds to the R2000 and R3000 processors, `-mips2' to the R6000 processor, and `-mips3' to the R4000 processor.
-m4650
-no-m4650
Generate code for the MIPS R4650 chip. This tells the assembler to accept the `mad' and `madu' instruction, and to not schedule `nop' instructions around accesses to the `HI' and `LO' registers. `-no-m4650' turns off this option.
-mcpu=CPU
Generate code for a particular MIPS cpu. This has little effect on the assembler, but it is passed by gcc.
--emulation=name
This option causes as to emulate as configured for some other target, in all respects, including output format (choosing between ELF and ECOFF only), handling of pseudo-opcodes which may generate debugging information or store symbol table information, and default endianness. The available configuration names are: `mipsecoff', `mipself', `mipslecoff', `mipsbecoff', `mipslelf', `mipsbelf'. The first two do not alter the default endianness from that of the primary target for which the assembler was configured; the others change the default to little- or big-endian as indicated by the `b' or `l' in the name. Using `-EB' or `-EL' will override the endianness selection in any case. This option is currently supported only when the primary target as is configured for is a MIPS ELF or ECOFF target. Furthermore, the primary target or others specified with `--enable-targets=...' at configuration time must include support for the other format, if both are to be available. For example, the Irix 5 configuration includes support for both. Eventually, this option will support more configurations, with more fine-grained control over the assembler's behavior, and will be supported for more processors.
-nocpp
as ignores this option. It is accepted for compatibility with the native tools.
--trap
--no-trap
--break
--no-break
Control how to deal with multiplication overflow and division by zero. `--trap' or `--no-break' (which are synonyms) take a trap exception (and only work for Instruction Set Architecture level 2 and higher); `--break' or `--no-trap' (also synonyms, and the default) take a break exception.

Structure of this Manual

This manual is intended to describe what you need to know to use GNU as. We cover the syntax expected in source files, including notation for symbols, constants, and expressions; the directives that as understands; and of course how to invoke as.

This manual also describes some of the machine-dependent features of various flavors of the assembler.

On the other hand, this manual is not intended as an introduction to programming in assembly language--let alone programming in general! In a similar vein, we make no attempt to introduce the machine architecture; we do not describe the instruction set, standard mnemonics, registers or addressing modes that are standard to a particular architecture. You may want to consult the manufacturer's machine architecture manual for this information.

The GNU Assembler

GNU as is really a family of assemblers. If you use (or have used) the GNU assembler on one architecture, you should find a fairly similar environment when you use it on another architecture. Each version has much in common with the others, including object file formats, most assembler directives (often called pseudo-ops) and assembler syntax.

as is primarily intended to assemble the output of the GNU C compiler gcc for use by the linker ld. Nevertheless, we've tried to make as assemble correctly everything that other assemblers for the same machine would assemble. Any exceptions are documented explicitly (see section Machine Dependent Features). This doesn't mean as always uses the same syntax as another assembler for the same architecture; for example, we know of several incompatible versions of 680x0 assembly language syntax.

Unlike older assemblers, as is designed to assemble a source program in one pass of the source file. This has a subtle impact on the .org directive (see section .org new-lc , fill).

Object File Formats

The GNU assembler can be configured to produce several alternative object file formats. For the most part, this does not affect how you write assembly language programs; but directives for debugging symbols are typically different in different file formats. See section Symbol Attributes. On the machine specific, as can be configured to produce either a.out or COFF format object files. On the machine specific, as can be configured to produce either b.out or COFF format object files. On the machine specific, as can be configured to produce either SOM or ELF format object files.

Command Line

After the program name as, the command line may contain options and file names. Options may appear in any order, and may be before, after, or between file names. The order of file names is significant.

`--' (two hyphens) by itself names the standard input file explicitly, as one of the files for as to assemble.

Except for `--' any command line argument that begins with a hyphen (`-') is an option. Each option changes the behavior of as. No option changes the way another option works. An option is a `-' followed by one or more letters; the case of the letter is important. All options are optional.

Some options expect exactly one file name to follow them. The file name may either immediately follow the option's letter (compatible with older assemblers) or it may be the next command argument (GNU standard). These two command lines are equivalent:

as -o my-object-file.o mumble.s
as -omy-object-file.o mumble.s

Input Files

We use the phrase source program, abbreviated source, to describe the program input to one run of as. The program may be in one or more files; how the source is partitioned into files doesn't change the meaning of the source.

The source program is a concatenation of the text in all the files, in the order specified.

Each time you run as it assembles exactly one source program. The source program is made up of one or more files. (The standard input is also a file.)

You give as a command line that has zero or more input file names. The input files are read (from left file name to right). A command line argument (in any position) that has no special meaning is taken to be an input file name.

If you give as no file names it attempts to read one input file from the as standard input, which is normally your terminal. You may have to type ctl-D to tell as there is no more program to assemble.

Use `--' if you need to explicitly name the standard input file in your command line.

If the source is empty, as produces a small, empty object file.

Filenames and Line-numbers

There are two ways of locating a line in the input file (or files) and either may be used in reporting error messages. One way refers to a line number in a physical file; the other refers to a line number in a "logical" file. See section Error and Warning Messages.

Physical files are those files named in the command line given to as.

Logical files are simply names declared explicitly by assembler directives; they bear no relation to physical files. Logical file names help error messages reflect the original source file, when as source is itself synthesized from other files. See section .app-file string.

Output (Object) File

Every time you run as it produces an output file, which is your assembly language program translated into numbers. This file is the object file. Its default name is a.out, or b.out when as is configured for the Intel 80960. You can give it another name by using the -o option. Conventionally, object file names end with `.o'. The default name is used for historical reasons: older assemblers were capable of assembling self-contained programs directly into a runnable program. (For some formats, this isn't currently possible, but it can be done for the a.out format.)

The object file is meant for input to the linker ld. It contains assembled program code, information to help ld integrate the assembled program into a runnable file, and (optionally) symbolic information for the debugger.

Error and Warning Messages

as may write warnings and error messages to the standard error file (usually your terminal). This should not happen when a compiler runs as automatically. Warnings report an assumption made so that as could keep assembling a flawed program; errors report a grave problem that stops the assembly.

Warning messages have the format

file_name:NNN:Warning Message Text

(where NNN is a line number). If a logical file name has been given (see section .app-file string) it is used for the filename, otherwise the name of the current input file is used. If a logical line number was given (see section .line line-number) (see section .ln line-number) then it is used to calculate the number printed, otherwise the actual line in the current source file is printed. The message text is intended to be self explanatory (in the grand Unix tradition).

Error messages have the format

file_name:NNN:FATAL:Error Message Text

The file name and line number are derived as for warning messages. The actual message text may be rather less explanatory because many of them aren't supposed to happen.

Command-Line Options

This chapter describes command-line options available in all versions of the GNU assembler; see section Machine Dependent Features, for options specific to particular machine architectures.

If you are invoking as via the GNU C compiler (version 2), you can use the `-Wa' option to pass arguments through to the assembler. The assembler arguments must be separated from each other (and the `-Wa') by commas. For example:

gcc -c -g -O -Wa,-alh,-L file.c

emits a listing to standard output with high-level and assembly source.

Usually you do not need to use this `-Wa' mechanism, since many compiler command-line options are automatically passed to the assembler by the compiler. (You can call the GNU compiler driver with the `-v' option to see precisely what options it passes to each compilation pass, including the assembler.)

Enable Listings: -a[cdhlns]

These options enable listing output from the assembler. By itself, `-a' requests high-level, assembly, and symbols listing. You can use other letters to select specific options for the list: `-ah' requests a high-level language listing, `-al' requests an output-program assembly listing, and `-as' requests a symbol table listing. High-level listings require that a compiler debugging option like `-g' be used, and that assembly listings (`-al') be requested also.

Use the `-ac' option to omit false conditionals from a listing. Any lines which are not assembled because of a false .if (or .ifdef, or any other conditional), or a true .if followed by an .else, will be omitted from the listing.

Use the `-ad' option to omit debugging directives from the listing.

Once you have specified one of these options, you can further control listing output and its appearance using the directives .list, .nolist, .psize, .eject, .title, and .sbttl. The `-an' option turns off all forms processing. If you do not request listing output with one of the `-a' options, the listing-control directives have no effect.

The letters after `-a' may be combined into one option, e.g., `-aln'.

-D

This option has no effect whatsoever, but it is accepted to make it more likely that scripts written for other assemblers also work with as.

Work Faster: -f

`-f' should only be used when assembling programs written by a (trusted) compiler. `-f' stops the assembler from doing whitespace and comment preprocessing on the input file(s) before assembling them. See section Preprocessing.

Warning: if you use `-f' when the files actually need to be preprocessed (if they contain comments, for example), as does not work correctly.

.include search path: -I path

Use this option to add a path to the list of directories as searches for files specified in .include directives (see section .include "file"). You may use -I as many times as necessary to include a variety of paths. The current working directory is always searched first; after that, as searches any `-I' directories in the same order as they were specified (left to right) on the command line.

Difference Tables: -K

as sometimes alters the code emitted for directives of the form `.word sym1-sym2'; see section .word expressions. You can use the `-K' option if you want a warning issued when this is done.

Include Local Labels: -L

Labels beginning with `L' (upper case only) are called local labels. See section Symbol Names. Normally you do not see such labels when debugging, because they are intended for the use of programs (like compilers) that compose assembler programs, not for your notice. Normally both as and ld discard such labels, so you do not normally debug with them.

This option tells as to retain those `L...' symbols in the object file. Usually if you do this you also tell the linker ld to preserve symbols whose names begin with `L'.

By default, a local label is any label beginning with `L', but each target is allowed to redefine the local label prefix. On the HPPA local labels begin with `L$'. `;' for the ARM family;

Assemble in MRI Compatibility Mode: -M

The -M or --mri option selects MRI compatibility mode. This changes the syntax and pseudo-op handling of as to make it compatible with the ASM68K or the ASM960 (depending upon the configured target) assembler from Microtec Research. The exact nature of the MRI syntax will not be documented here; see the MRI manuals for more information. Note in particular that the handling of macros and macro arguments is somewhat different. The purpose of this option is to permit assembling existing MRI assembler code using as.

The MRI compatibility is not complete. Certain operations of the MRI assembler depend upon its object file format, and can not be supported using other object file formats. Supporting these would require enhancing each object file format individually. These are:

  • global symbols in common section The m68k MRI assembler supports common sections which are merged by the linker. Other object file formats do not support this. as handles common sections by treating them as a single common symbol. It permits local symbols to be defined within a common section, but it can not support global symbols, since it has no way to describe them.
  • complex relocations The MRI assemblers support relocations against a negated section address, and relocations which combine the start addresses of two or more sections. These are not support by other object file formats.
  • END pseudo-op specifying start address The MRI END pseudo-op permits the specification of a start address. This is not supported by other object file formats. The start address may instead be specified using the -e option to the linker, or in a linker script.
  • IDNT, .ident and NAME pseudo-ops The MRI IDNT, .ident and NAME pseudo-ops assign a module name to the output file. This is not supported by other object file formats.
  • ORG pseudo-op The m68k MRI ORG pseudo-op begins an absolute section at a given address. This differs from the usual as .org pseudo-op, which changes the location within the current section. Absolute sections are not supported by other object file formats. The address of a section may be assigned within a linker script.

There are some other features of the MRI assembler which are not supported by as, typically either because they are difficult or because they seem of little consequence. Some of these may be supported in future releases.

  • EBCDIC strings EBCDIC strings are not supported.
  • packed binary coded decimal Packed binary coded decimal is not supported. This means that the DC.P and DCB.P pseudo-ops are not supported.
  • FEQU pseudo-op The m68k FEQU pseudo-op is not supported.
  • NOOBJ pseudo-op The m68k NOOBJ pseudo-op is not supported.
  • OPT branch control options The m68k OPT branch control options---B, BRS, BRB, BRL, and BRW---are ignored. as automatically relaxes all branches, whether forward or backward, to an appropriate size, so these options serve no purpose.
  • OPT list control options The following m68k OPT list control options are ignored: C, CEX, CL, CRE, E, G, I, M, MEX, MC, MD, X.
  • other OPT options The following m68k OPT options are ignored: NEST, O, OLD, OP, P, PCO, PCR, PCS, R.
  • OPT D option is default The m68k OPT D option is the default, unlike the MRI assembler. OPT NOD may be used to turn it off.
  • XREF pseudo-op. The m68k XREF pseudo-op is ignored.
  • .debug pseudo-op The i960 .debug pseudo-op is not supported.
  • .extended pseudo-op The i960 .extended pseudo-op is not supported.
  • .list pseudo-op. The various options of the i960 .list pseudo-op are not supported.
  • .optimize pseudo-op The i960 .optimize pseudo-op is not supported.
  • .output pseudo-op The i960 .output pseudo-op is not supported.
  • .setreal pseudo-op The i960 .setreal pseudo-op is not supported.

Dependency tracking: --MD

as can generate a dependency file for the file it creates. This file consists of a single rule suitable for make describing the dependencies of the main source file.

The rule is written to the file named in its argument.

This feature is used in the automatic updating of makefiles.

Name the Object File: -o

There is always one object file output when you run as. By default it has the name `a.out' (or `b.out', for Intel 960 targets only). You use this option (which takes exactly one filename) to give the object file a different name.

Whatever the object file is called, as overwrites any existing file of the same name.

Join Data and Text Sections: -R

-R tells as to write the object file as if all data-section data lives in the text section. This is only done at the very last moment: your binary data are the same, but data section parts are relocated differently. The data section part of your object file is zero bytes long because all its bytes are appended to the text section. (See section Sections and Relocation.)

When you specify -R it would be possible to generate shorter address displacements (because we do not have to cross between text and data section). We refrain from doing this simply for compatibility with older versions of as. In future, -R may work this way.

When as is configured for COFF output, this option is only useful if you use sections named `.text' and `.data'.

-R is not supported for any of the HPPA targets. Using -R generates a warning from as.

Display Assembly Statistics: --statistics

Use `--statistics' to display two statistics about the resources used by as: the maximum amount of space allocated during the assembly (in bytes), and the total execution time taken for the assembly (in CPU seconds).

Compatible output: --traditional-format

For some targets, the output of as is different in some ways from the output of some existing assembler. This switch requests as to use the traditional format instead.

For example, it disables the exception frame optimizations which as normally does by default on gcc output.

Announce Version: -v

You can find out what version of as is running by including the option `-v' (which you can also spell as `-version') on the command line.

Suppress Warnings: -W

as should never give a warning or error message when assembling compiler output. But programs written by people often cause as to give a warning that a particular assumption was made. All such warnings are directed to the standard error file. If you use this option, no warnings are issued. This option only affects the warning messages: it does not change any particular of how as assembles your file. Errors, which stop the assembly, are still reported.

Generate Object File in Spite of Errors: -Z

After an error message, as normally produces no output. If for some reason you are interested in object file output even after as gives an error message on your program, use the `-Z' option. If there are any errors, as continues anyways, and writes an object file after a final warning message of the form `n errors, m warnings, generating bad object file.'

Syntax

This chapter describes the machine-independent syntax allowed in a source file. as syntax is similar to what many other assemblers use; it is inspired by the BSD 4.2 assembler, except that as does not assemble Vax bit-fields.

Preprocessing

The as internal preprocessor:

  • adjusts and removes extra whitespace. It leaves one space or tab before the keywords on a line, and turns any other whitespace on the line into a single space.
  • removes all comments, replacing them with a single space, or an appropriate number of newlines.
  • converts character constants into the appropriate numeric values.

It does not do macro processing, include file handling, or anything else you may get from your C compiler's preprocessor. You can do include file processing with the .include directive (see section .include "file"). You can use the GNU C compiler driver to get other "CPP" style preprocessing, by giving the input file a `.S' suffix. See section `Options Controlling the Kind of Output' in Using GNU CC.

Excess whitespace, comments, and character constants cannot be used in the portions of the input text that are not preprocessed.

If the first line of an input file is #NO_APP or if you use the `-f' option, whitespace and comments are not removed from the input file. Within an input file, you can ask for whitespace and comment removal in specific portions of the by putting a line that says #APP before the text that may contain whitespace or comments, and putting a line that says #NO_APP after this text. This feature is mainly intend to support asm statements in compilers whose output is otherwise free of comments and whitespace.

Whitespace

Whitespace is one or more blanks or tabs, in any order. Whitespace is used to separate symbols, and to make programs neater for people to read. Unless within character constants (see section Character Constants), any whitespace means the same as exactly one space.

Comments

There are two ways of rendering comments to as. In both cases the comment is equivalent to one space.

Anything from `/*' through the next `*/' is a comment. This means you may not nest these comments.

/*
  The only way to include a newline ('\n') in a comment
  is to use this sort of comment.
*/

/* This sort of comment does not nest. */

Anything from the line comment character to the next newline
is considered a comment and is ignored.  The line comment character is
`;' for the AMD 29K family;
`;' on the ARC;
`;' for the H8/300 family;
`!' for the H8/500 family;
`;' for the HPPA;
`#' on the i960;
`!' for the Hitachi SH;
`!' on the SPARC;
`#' on the m32r;
`|' on the 680x0;
`#' on the Vax;
`!' for the Z8000;
`#' on the V850;
see section Machine Dependent Features.

On some machines there are two different line comment characters. One character only begins a comment if it is the first non-whitespace character on a line, while the other always begins a comment.

The V850 assembler also supports a double dash as starting a comment that extends to the end of the line.

`--';

To be compatible with past assemblers, lines that begin with `#' have a special interpretation. Following the `#' should be an absolute expression (see section Expressions): the logical line number of the next line. Then a string (see section Strings) is allowed: if present it is a new logical file name. The rest of the line, if any, should be whitespace.

If the first non-whitespace characters on the line are not numeric, the line is ignored. (Just like a comment.)

                          # This is an ordinary comment.
# 42-6 "new_file_name"    # New logical file name
                          # This is logical line # 36.

This feature is deprecated, and may disappear from future versions of as.

Symbols

A symbol is one or more characters chosen from the set of all letters (both upper and lower case), digits and the three characters `_.$'. On most machines, you can also use $ in symbol names; exceptions are noted in section Machine Dependent Features. No symbol may begin with a digit. Case is significant. There is no length limit: all characters are significant. Symbols are delimited by characters not in that set, or by the beginning of a file (since the source program must end with a newline, the end of a file is not a possible symbol delimiter). See section Symbols.

Statements

A statement ends at a newline character (`\n') or an "at" sign (`@'). The newline or at sign is considered part of the preceding statement. Newlines and at signs within character constants are an exception: they do not end statements. A statement ends at a newline character (`\n') or an exclamation point (`!'). The newline or exclamation point is considered part of the preceding statement. Newlines and exclamation points within character constants are an exception: they do not end statements. A statement ends at a newline character (`\n'); or (for the H8/300) a dollar sign (`$'); or (for the Hitachi-SH or the H8/500) a semicolon (`;'). The newline or separator character is considered part of the preceding statement. Newlines and separators within character constants are an exception: they do not end statements. A statement ends at a newline character (`\n') or line separator character. (The line separator is usually `;', unless this conflicts with the comment character; see section Machine Dependent Features.) The newline or separator character is considered part of the preceding statement. Newlines and separators within character constants are an exception: they do not end statements.

It is an error to end any statement with end-of-file: the last character of any input file should be a newline.

You may write a statement on more than one line if you put a backslash (\) immediately in front of any newlines within the statement. When as reads a backslashed newline both characters are ignored. You can even put backslashed newlines in the middle of symbol names without changing the meaning of your source program.

An empty statement is allowed, and may include whitespace. It is ignored.

A statement begins with zero or more labels, optionally followed by a key symbol which determines what kind of statement it is. The key symbol determines the syntax of the rest of the statement. If the symbol begins with a dot `.' then the statement is an assembler directive: typically valid for any computer. If the symbol begins with a letter the statement is an assembly language instruction: it assembles into a machine language instruction. Different versions of as for different computers recognize different instructions. In fact, the same symbol may represent a different instruction in a different computer's assembly language.

A label is a symbol immediately followed by a colon (:). Whitespace before a label or after a colon is permitted, but you may not have whitespace between a label's symbol and its colon. See section Labels.

For HPPA targets, labels need not be immediately followed by a colon, but the definition of a label must begin in column zero. This also implies that only one label may be defined on each line.

label:     .directive    followed by something
another_label:           # This is an empty statement.
           instruction   operand_1, operand_2, ...

Constants

A constant is a number, written so that its value is known by inspection, without knowing any context. Like this:

.byte  74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value.
.ascii "Ring the bell\7"                  # A string constant.
.octa  0x123456789abcdef0123456789ABCDEF0 # A bignum.
.float 0f-314159265358979323846264338327\
95028841971.693993751E-40                 # - pi, a flonum.

Character Constants

There are two kinds of character constants. A character stands for one character in one byte and its value may be used in numeric expressions. String constants (properly called string literals) are potentially many bytes and their values may not be used in arithmetic expressions.

Strings

A string is written between double-quotes. It may contain double-quotes or null characters. The way to get special characters into a string is to escape these characters: precede them with a backslash `\' character. For example `\\' represents one backslash: the first \ is an escape which tells as to interpret the second character literally as a backslash (which prevents as from recognizing the second \ as an escape character). The complete list of escapes follows.

\b
Mnemonic for backspace; for ASCII this is octal code 010.
\f
Mnemonic for FormFeed; for ASCII this is octal code 014.
\n
Mnemonic for newline; for ASCII this is octal code 012.
\r
Mnemonic for carriage-Return; for ASCII this is octal code 015.
\t
Mnemonic for horizontal Tab; for ASCII this is octal code 011.
\ digit digit digit
An octal character code. The numeric code is 3 octal digits. For compatibility with other Unix systems, 8 and 9 are accepted as digits: for example, \008 has the value 010, and \009 the value 011.
\x hex-digits...
A hex character code. All trailing hex digits are combined. Either upper or lower case x works.
\\
Represents one `\' character.
\"
Represents one `"' character. Needed in strings to represent this character, because an unescaped `"' would end the string.
\ anything-else
Any other character when escaped by \ gives a warning, but assembles as if the `\' was not present. The idea is that if you used an escape sequence you clearly didn't want the literal interpretation of the following character. However as has no other interpretation, so as knows it is giving you the wrong code and warns you of the fact.

Which characters are escapable, and what those escapes represent, varies widely among assemblers. The current set is what we think the BSD 4.2 assembler recognizes, and is a subset of what most C compilers recognize. If you are in doubt, do not use an escape sequence.

Characters

A single character may be written as a single quote immediately followed by that character. The same escapes apply to characters as to strings. So if you want to write the character backslash, you must write '\\ where the first \ escapes the second \. As you can see, the quote is an acute accent, not a grave accent. A newline (or at sign `@') (or dollar sign `$', for the H8/300; or semicolon `;' for the Hitachi SH or H8/500) immediately following an acute accent is taken as a literal character and does not count as the end of a statement. The value of a character constant in a numeric expression is the machine's byte-wide code for that character. as assumes your character code is ASCII: 'A means 65, 'B means 66, and so on.

Number Constants

as distinguishes three kinds of numbers according to how they are stored in the target machine. Integers are numbers that would fit into an int in the C language. Bignums are integers, but they are stored in more than 32 bits. Flonums are floating point numbers, described below.

Integers

A binary integer is `0b' or `0B' followed by zero or more of the binary digits `01'.

An octal integer is `0' followed by zero or more of the octal digits (`01234567').

A decimal integer starts with a non-zero digit followed by zero or more digits (`0123456789').

A hexadecimal integer is `0x' or `0X' followed by one or more hexadecimal digits chosen from `0123456789abcdefABCDEF'.

Integers have the usual values. To denote a negative integer, use the prefix operator `-' discussed under expressions (see section Prefix Operator).

Bignums

A bignum has the same syntax and semantics as an integer except that the number (or its negative) takes more than 32 bits to represent in binary. The distinction is made because in some places integers are permitted while bignums are not.

Flonums

A flonum represents a floating point number. The translation is indirect: a decimal floating point number from the text is converted by as to a generic binary floating point number of more than sufficient precision. This generic floating point number is converted to a particular computer's floating point format (or formats) by a portion of as specialized to that computer.

A flonum is written by writing (in order)

  • The digit `0'. (`0' is optional on the HPPA.)
  • A letter, to tell as the rest of the number is a flonum. e is recommended. Case is not important. On the H8/300, H8/500, Hitachi SH, and AMD 29K architectures, the letter must be one of the letters `DFPRSX' (in upper or lower case). On the ARC, the letter must be one of the letters `DFRS' (in upper or lower case). On the Intel 960 architecture, the letter must be one of the letters `DFT' (in upper or lower case). On the HPPA architecture, the letter must be `E' (upper case only).
  • An optional sign: either `+' or `-'.
  • An optional integer part: zero or more decimal digits.
  • An optional fractional part: `.' followed by zero or more decimal digits.
  • An optional exponent, consisting of:
    • An `E' or `e'.
    • Optional sign: either `+' or `-'.
    • One or more decimal digits.

At least one of the integer part or the fractional part must be present. The floating point number has the usual base-10 value.

as does all processing using integers. Flonums are computed independently of any floating point hardware in the computer running as.

Sections and Relocation

Background

Roughly, a section is a range of addresses, with no gaps; all data "in" those addresses is treated the same for some particular purpose. For example there may be a "read only" section.

The linker ld reads many object files (partial programs) and combines their contents to form a runnable program. When as emits an object file, the partial program is assumed to start at address 0. ld assigns the final addresses for the partial program, so that different partial programs do not overlap. This is actually an oversimplification, but it suffices to explain how as uses sections.

ld moves blocks of bytes of your program to their run-time addresses. These blocks slide to their run-time addresses as rigid units; their length does not change and neither does the order of bytes within them. Such a rigid unit is called a section. Assigning run-time addresses to sections is called relocation. It includes the task of adjusting mentions of object-file addresses so they refer to the proper run-time addresses. For the H8/300 and H8/500, and for the Hitachi SH, as pads sections if needed to ensure they end on a word (sixteen bit) boundary.

An object file written by as has at least three sections, any of which may be empty. These are named text, data and bss sections.

When it generates COFF output, as can also generate whatever other named sections you specify using the `.section' directive (see section .section name). If you do not use any directives that place output in the `.text' or `.data' sections, these sections still exist, but are empty.

When as generates SOM or ELF output for the HPPA, as can also generate whatever other named sections you specify using the `.space' and `.subspace' directives. See HP9000 Series 800 Assembly Language Reference Manual (HP 92432-90001) for details on the `.space' and `.subspace' assembler directives.

Additionally, as uses different names for the standard text, data, and bss sections when generating SOM output. Program text is placed into the `$CODE$' section, data into `$DATA$', and BSS into `$BSS$'.

Within the object file, the text section starts at address 0, the data section follows, and the bss section follows the data section.

When generating either SOM or ELF output files on the HPPA, the text section starts at address 0, the data section at address 0x4000000, and the bss section follows the data section.

To let ld know which data changes when the sections are relocated, and how to change that data, as also writes to the object file details of the relocation needed. To perform relocation ld must know, each time an address in the object file is mentioned:

  • Where in the object file is the beginning of this reference to an address?
  • How long (in bytes) is this reference?
  • Which section does the address refer to? What is the numeric value of
    (address) - (start-address of section)?
  • Is the reference to an address "Program-Counter relative"?

In fact, every address as ever uses is expressed as

(section) + (offset into section)

Further, most expressions as computes have this section-relative nature. (For some object formats, such as SOM for the HPPA, some expressions are symbol-relative instead.)

In this manual we use the notation {secname N} to mean "offset N into section secname."

Apart from text, data and bss sections you need to know about the absolute section. When ld mixes partial programs, addresses in the absolute section remain unchanged. For example, address {absolute 0} is "relocated" to run-time address 0 by ld. Although the linker never arranges two partial programs' data sections with overlapping addresses after linking, by definition their absolute sections must overlap. Address {absolute 239} in one part of a program is always the same address when the program is running as address {absolute 239} in any other part of the program.

The idea of sections is extended to the undefined section. Any address whose section is unknown at assembly time is by definition rendered {undefined U}---where U is filled in later. Since numbers are always defined, the only way to generate an undefined address is to mention an undefined symbol. A reference to a named common block would be such a symbol: its value is unknown at assembly time so it has section undefined.

By analogy the word section is used to describe groups of sections in the linked program. ld puts all partial programs' text sections in contiguous addresses in the linked program. It is customary to refer to the text section of a program, meaning all the addresses of all partial programs' text sections. Likewise for data and bss sections.

Some sections are manipulated by ld; others are invented for use of as and have no meaning except during assembly.

Linker Sections

ld deals with just four kinds of sections, summarized below.

named sections
text section
data section
These sections hold your program. as and ld treat them as separate but equal sections. Anything you can say of one section is true another. When the program is running, however, it is customary for the text section to be unalterable. The text section is often shared among processes: it contains instructions, constants and the like. The data section of a running program is usually alterable: for example, C variables would be stored in the data section.
bss section
This section contains zeroed bytes when your program begins running. It is used to hold unitialized variables or common storage. The length of each partial program's bss section is important, but because it starts out containing zeroed bytes there is no need to store explicit zero bytes in the object file. The bss section was invented to eliminate those explicit zeros from object files.
absolute section
Address 0 of this section is always "relocated" to runtime address 0. This is useful if you want to refer to an address that ld must not change when relocating. In this sense we speak of absolute addresses being "unrelocatable": they do not change during relocation.
undefined section
This "section" is a catch-all for address references to objects not in the preceding sections.

An idealized example of three relocatable sections follows. The example uses the traditional section names `.text' and `.data'. Memory addresses are on the horizontal axis.

Assembler Internal Sections

These sections are meant only for the internal use of as. They have no meaning at run-time. You do not really need to know about these sections for most purposes; but they can be mentioned in as warning messages, so it might be helpful to have an idea of their meanings to as. These sections are used to permit the value of every expression in your assembly language program to be a section-relative address.

ASSEMBLER-INTERNAL-LOGIC-ERROR!
An internal assembler logic error has been found. This means there is a bug in the assembler.
expr section
The assembler stores complex expression internally as combinations of symbols. When it needs to represent an expression as a symbol, it puts it in the expr section.

Sub-Sections

Assembled bytes conventionally fall into two sections: text and data. You may have separate groups of data in named sections text or data that you want to end up near to each other in the object file, even though they are not contiguous in the assembler source. as allows you to use subsections for this purpose. Within each section, there can be numbered subsections with values from 0 to 8192. Objects assembled into the same subsection go into the object file together with other objects in the same subsection. For example, a compiler might want to store constants in the text section, but might not want to have them interspersed with the program being assembled. In this case, the compiler could issue a `.text 0' before each section of code being output, and a `.text 1' before each group of constants being output.

Subsections are optional. If you do not use subsections, everything goes in subsection number zero.

Each subsection is zero-padded up to a multiple of four bytes. (Subsections may be padded a different amount on different flavors of as.)

Subsections appear in your object file in numeric order, lowest numbered to highest. (All this to be compatible with other people's assemblers.) The object file contains no representation of subsections; ld and other programs that manipulate object files see no trace of them. They just see all your text subsections as a text section, and all your data subsections as a data section.

To specify which subsection you want subsequent statements assembled into, use a numeric argument to specify it, in a `.text expression' or a `.data expression' statement. When generating COFF output, you can also use an extra subsection argument with arbitrary named sections: `.section name, expression'. Expression should be an absolute expression. (See section Expressions.) If you just say `.text' then `.text 0' is assumed. Likewise `.data' means `.data 0'. Assembly begins in text 0. For instance:

.text 0     # The default subsection is text 0 anyway.
.ascii "This lives in the first text subsection. *"
.text 1
.ascii "But this lives in the second text subsection."
.data 0
.ascii "This lives in the data section,"
.ascii "in the first data subsection."
.text 0
.ascii "This lives in the first text section,"
.ascii "immediately following the asterisk (*)."

Each section has a location counter incremented by one for every byte assembled into that section. Because subsections are merely a convenience restricted to as there is no concept of a subsection location counter. There is no way to directly manipulate a location counter--but the .align directive changes it, and any label definition captures its current value. The location counter of the section where statements are being assembled is said to be the active location counter.

bss Section

The bss section is used for local common variable storage. You may allocate address space in the bss section, but you may not dictate data to load into it before your program executes. When your program starts running, all the contents of the bss section are zeroed bytes.

The .lcomm pseudo-op defines a symbol in the bss section; see section .lcomm symbol , length.

The .comm pseudo-op may be used to declare a common symbol, which is another form of uninitialized symbol; see See section .comm symbol , length .

When assembling for a target which supports multiple sections, such as ELF or COFF, you may switch into the .bss section and define symbols as usual; see section .section name. You may only assemble zero values into the section. Typically the section will only contain symbol definitions and .skip directives (see section .skip size , fill).

Symbols

Symbols are a central concept: the programmer uses symbols to name things, the linker uses symbols to link, and the debugger uses symbols to debug.

Warning: as does not place symbols in the object file in the same order they were declared. This may break some debuggers.

Labels

A label is written as a symbol immediately followed by a colon `:'. The symbol then represents the current value of the active location counter, and is, for example, a suitable instruction operand. You are warned if you use the same symbol to represent two different locations: the first definition overrides any other definitions.

On the HPPA, the usual form for a label need not be immediately followed by a colon, but instead must start in column zero. Only one label may be defined on a single line. To work around this, the HPPA version of as also provides a special directive .label for defining labels more flexibly.

Giving Symbols Other Values

A symbol can be given an arbitrary value by writing a symbol, followed by an equals sign `=', followed by an expression (see section Expressions). This is equivalent to using the .set directive. See section .set symbol, expression.

Symbol Names

Symbol names begin with a letter or with one of `._'. On most machines, you can also use $ in symbol names; exceptions are noted in section Machine Dependent Features. That character may be followed by any string of digits, letters, dollar signs (unless otherwise noted in section Machine Dependent Features), and underscores. For the AMD 29K family, `?' is also allowed in the body of a symbol name, though not at its beginning.

Case of letters is significant: foo is a different symbol name than Foo.

Each symbol has exactly one name. Each name in an assembly language program refers to exactly one symbol. You may use that symbol name any number of times in a program.

Local Symbol Names

Local symbols help compilers and programmers use names temporarily. There are ten local symbol names, which are re-used throughout the program. You may refer to them using the names `0' `1' ... `9'. To define a local symbol, write a label of the form `N:' (where N represents any digit). To refer to the most recent previous definition of that symbol write `Nb', using the same digit as when you defined the label. To refer to the next definition of a local label, write `Nf'---where N gives you a choice of 10 forward references. The `b' stands for "backwards" and the `f' stands for "forwards".

Local symbols are not emitted by the current GNU C compiler.

There is no restriction on how you can use these labels, but remember that at any point in the assembly you can refer to at most 10 prior local labels and to at most 10 forward local labels.

Local symbol names are only a notation device. They are immediately transformed into more conventional symbol names before the assembler uses them. The symbol names stored in the symbol table, appearing in error messages and optionally emitted to the object file have these parts:

L
All local labels begin with `L'. Normally both as and ld forget symbols that start with `L'. These labels are used for symbols you are never intended to see. If you use the `-L' option then as retains these symbols in the object file. If you also instruct ld to retain these symbols, you may use them in debugging.
digit
If the label is written `0:' then the digit is `0'. If the label is written `1:' then the digit is `1'. And so on up through `9:'.
C-A
This unusual character is included so you do not accidentally invent a symbol of the same name. The character has ASCII value `\001'.
ordinal number
This is a serial number to keep the labels distinct. The first `0:' gets the number `1'; The 15th `0:' gets the number `15'; etc.. Likewise for the other labels `1:' through `9:'.

For instance, the first 1: is named L1C-A1, the 44th 3: is named L3C-A44.

The Special Dot Symbol

The special symbol `.' refers to the current address that as is assembling into. Thus, the expression `melvin: .long .' defines melvin to contain its own address. Assigning a value to . is treated the same as a .org directive. Thus, the expression `.=.+4' is the same as saying `.space 4'.

Symbol Attributes

Every symbol has, as well as its name, the attributes "Value" and "Type". Depending on output format, symbols can also have auxiliary attributes.

If you use a symbol without defining it, as assumes zero for all these attributes, and probably won't warn you. This makes the symbol an externally defined symbol, which is generally what you would want.

Value

The value of a symbol is (usually) 32 bits. For a symbol which labels a location in the text, data, bss or absolute sections the value is the number of addresses from the start of that section to the label. Naturally for text, data and bss sections the value of a symbol changes as ld changes section base addresses during linking. Absolute symbols' values do not change during linking: that is why they are called absolute.

The value of an undefined symbol is treated in a special way. If it is 0 then the symbol is not defined in this assembler source file, and ld tries to determine its value from other files linked into the same program. You make this kind of symbol simply by mentioning a symbol name without defining it. A non-zero value represents a .comm common declaration. The value is how much common storage to reserve, in bytes (addresses). The symbol refers to the first address of the allocated storage.

Type

The type attribute of a symbol contains relocation (section) information, any flag settings indicating that a symbol is external, and (optionally), other information for linkers and debuggers. The exact format depends on the object-code output format in use.

Symbol Attributes: a.out

Descriptor

This is an arbitrary 16-bit value. You may establish a symbol's descriptor value by using a .desc statement (see section .desc symbol, abs-expression). A descriptor value means nothing to as.

Other

This is an arbitrary 8-bit value. It means nothing to as.

Symbol Attributes for COFF

The COFF format supports a multitude of auxiliary symbol attributes; like the primary symbol attributes, they are set between .def and .endef directives.

Primary Attributes

The symbol name is set with .def; the value and type, respectively, with .val and .type.

Auxiliary Attributes

The as directives .dim, .line, .scl, .size, and .tag can generate auxiliary symbol table information for COFF.

Symbol Attributes for SOM

The SOM format for the HPPA supports a multitude of symbol attributes set with the .EXPORT and .IMPORT directives.

The attributes are described in HP9000 Series 800 Assembly Language Reference Manual (HP 92432-90001) under the IMPORT and EXPORT assembler directive documentation.

Expressions

An expression specifies an address or numeric value. Whitespace may precede and/or follow an expression.

The result of an expression must be an absolute number, or else an offset into a particular section. If an expression is not absolute, and there is not enough information when as sees the expression to know its section, a second pass over the source program might be necessary to interpret the expression--but the second pass is currently not implemented. as aborts with an error message in this situation.

Empty Expressions

An empty expression has no value: it is just whitespace or null. Wherever an absolute expression is required, you may omit the expression, and as assumes a value of (absolute) 0. This is compatible with other assemblers.

Integer Expressions

An integer expression is one or more arguments delimited by operators.

Arguments

Arguments are symbols, numbers or subexpressions. In other contexts arguments are sometimes called "arithmetic operands". In this manual, to avoid confusing them with the "instruction operands" of the machine language, we use the term "argument" to refer to parts of expressions only, reserving the word "operand" to refer only to machine instruction operands.

Symbols are evaluated to yield {section NNN} where section is one of text, data, bss, absolute, or undefined. NNN is a signed, 2's complement 32 bit integer.

Numbers are usually integers.

A number can be a flonum or bignum. In this case, you are warned that only the low order 32 bits are used, and as pretends these 32 bits are an integer. You may write integer-manipulating instructions that act on exotic constants, compatible with other assemblers.

Subexpressions are a left parenthesis `(' followed by an integer expression, followed by a right parenthesis `)'; or a prefix operator followed by an argument.

Operators

Operators are arithmetic functions, like + or %. Prefix operators are followed by an argument. Infix operators appear between their arguments. Operators may be preceded and/or followed by whitespace.

Prefix Operator

as has the following prefix operators. They each take one argument, which must be absolute.

-
Negation. Two's complement negation.
~
Complementation. Bitwise not.

Infix Operators

Infix operators take two arguments, one on either side. Operators have precedence, but operations with equal precedence are performed left to right. Apart from + or -, both arguments must be absolute, and the result is absolute.

  1. Highest Precedence
    *
    Multiplication.
    /
    Division. Truncation is the same as the C operator `/'
    %
    Remainder.
    <
    <<
    Shift Left. Same as the C operator `<<'.
    >
    >>
    Shift Right. Same as the C operator `>>'.
  2. Intermediate precedence
    |
    Bitwise Inclusive Or.
    &
    Bitwise And.
    ^
    Bitwise Exclusive Or.
    !
    Bitwise Or Not.
  3. Lowest Precedence
    +
    Addition. If either argument is absolute, the result has the section of the other argument. You may not add together arguments from different sections.
    -
    Subtraction. If the right argument is absolute, the result has the section of the left argument. If both arguments are in the same section, the result is absolute. You may not subtract arguments from different sections.

In short, it's only meaningful to add or subtract the offsets in an address; you can only have a defined section in one of the two arguments.

Assembler Directives

All assembler directives have names that begin with a period (`.'). The rest of the name is letters, usually in lower case.

This chapter discusses directives that are available regardless of the target machine configuration for the GNU assembler. Some machine configurations provide additional directives. See section Machine Dependent Features.

.abort

This directive stops the assembly immediately. It is for compatibility with other assemblers. The original idea was that the assembly language source would be piped into the assembler. If the sender of the source quit, it could use this directive tells as to quit also. One day .abort will not be supported.

.ABORT

When producing COFF output, as accepts this directive as a synonym for `.abort'.

When producing b.out output, as accepts this directive, but ignores it.

.align abs-expr, abs-expr, abs-expr

Pad the location counter (in the current subsection) to a particular storage boundary. The first expression (which must be absolute) is the alignment required, as described below.

The second expression (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the padding bytes are normally zero. However, on some systems, if the section is marked as containing code and the fill value is omitted, the space is filled with no-op instructions.

The third expression is also absolute, and is also optional. If it is present, it is the maximum number of bytes that should be skipped by this alignment directive. If doing the alignment would require skipping more bytes than the specified maximum, then the alignment is not done at all. You can omit the fill value (the second argument) entirely by simply using two commas after the required alignment; this can be useful if you want the alignment to be filled with no-op instructions when appropriate.

The way the required alignment is specified varies from system to system. For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF format, the first expression is the alignment request in bytes. For example `.align 8' advances the location counter until it is a multiple of 8. If the location counter is already a multiple of 8, no change is needed.

For other systems, including the i386 using a.out format, it is the number of low-order zero bits the location counter must have after advancement. For example `.align 3' advances the location counter until it a multiple of 8. If the location counter is already a multiple of 8, no change is needed.

This inconsistency is due to the different behaviors of the various native assemblers for these systems which GAS must emulate. GAS also provides .balign and .p2align directives, described later, which have a consistent behavior across all architectures (but are specific to GAS).

.app-file string

.app-file (which may also be spelled `.file') tells as that we are about to start a new logical file. string is the new file name. In general, the filename is recognized whether or not it is surrounded by quotes `"'; but if you wish to specify an empty file name is permitted, you must give the quotes--"". This statement may go away in future: it is only recognized to be compatible with old as programs.

.ascii "string"...

.ascii expects zero or more string literals (see section Strings) separated by commas. It assembles each string (with no automatic trailing zero byte) into consecutive addresses.

.asciz "string"...

.asciz is just like .ascii, but each string is followed by a zero byte. The "z" in `.asciz' stands for "zero".

.balign[wl] abs-expr, abs-expr, abs-expr

Pad the location counter (in the current subsection) to a particular storage boundary. The first expression (which must be absolute) is the alignment request in bytes. For example `.balign 8' advances the location counter until it is a multiple of 8. If the location counter is already a multiple of 8, no change is needed.

The second expression (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the padding bytes are normally zero. However, on some systems, if the section is marked as containing code and the fill value is omitted, the space is filled with no-op instructions.

The third expression is also absolute, and is also optional. If it is present, it is the maximum number of bytes that should be skipped by this alignment directive. If doing the alignment would require skipping more bytes than the specified maximum, then the alignment is not done at all. You can omit the fill value (the second argument) entirely by simply using two commas after the required alignment; this can be useful if you want the alignment to be filled with no-op instructions when appropriate.

The .balignw and .balignl directives are variants of the .balign directive. The .balignw directive treats the fill pattern as a two byte word value. The .balignl directives treats the fill pattern as a four byte longword value. For example, .balignw 4,0x368d will align to a multiple of 4. If it skips two bytes, they will be filled in with the value 0x368d (the exact placement of the bytes depends upon the endianness of the processor). If it skips 1 or 3 bytes, the fill value is undefined.

.byte expressions

.byte expects zero or more expressions, separated by commas. Each expression is assembled into the next byte.

.comm symbol , length

.comm declares a common symbol named symbol. When linking, a common symbol in one object file may be merged with a defined or common symbol of the same name in another object file. If ld does not see a definition for the symbol--just one or more common symbols--then it will allocate length bytes of uninitialized memory. length must be an absolute expression. If ld sees multiple common symbols with the same name, and they do not all have the same size, it will allocate space using the largest size.

When using ELF, the .comm directive takes an optional third argument. This is the desired alignment of the symbol, specified as a byte boundary (for example, an alignment of 16 means that the least significant 4 bits of the address should be zero). The alignment must be an absolute expression, and it must be a power of two. If ld allocates uninitialized memory for the common symbol, it will use the alignment when placing the symbol. If no alignment is specified, as will set the alignment to the largest power of two less than or equal to the size of the symbol, up to a maximum of 16.

The syntax for .comm differs slightly on the HPPA. The syntax is `symbol .comm, length'; symbol is optional.

.data subsection

.data tells as to assemble the following statements onto the end of the data subsection numbered subsection (which is an absolute expression). If subsection is omitted, it defaults to zero.

.def name

Begin defining debugging information for a symbol name; the definition extends until the .endef directive is encountered.

This directive is only observed when as is configured for COFF format output; when producing b.out, `.def' is recognized, but ignored.

.desc symbol, abs-expression

This directive sets the descriptor of the symbol (see section Symbol Attributes) to the low 16 bits of an absolute expression.

The `.desc' directive is not available when as is configured for COFF output; it is only for a.out or b.out object format. For the sake of compatibility, as accepts it, but produces no output, when configured for COFF.

.dim

This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside .def/.endef pairs.

`.dim' is only meaningful when generating COFF format output; when as is generating b.out, it accepts this directive but ignores it.

.double flonums

.double expects zero or more flonums, separated by commas. It assembles floating point numbers. The exact kind of floating point numbers emitted depends on how as is configured. See section Machine Dependent Features.

.eject

Force a page break at this point, when generating assembly listings.

.else

.else is part of the as support for conditional assembly; see section .if absolute expression. It marks the beginning of a section of code to be assembled if the condition for the preceding .if was false.

.endef

This directive flags the end of a symbol definition begun with .def.

`.endef' is only meaningful when generating COFF format output; if as is configured to generate b.out, it accepts this directive but ignores it.

.endif

.endif is part of the as support for conditional assembly; it marks the end of a block of code that is only assembled conditionally. See section .if absolute expression.

.equ symbol, expression

This directive sets the value of symbol to expression. It is synonymous with `.set'; see section .set symbol, expression.

The syntax for equ on the HPPA is `symbol .equ expression'.

.equiv symbol, expression

The .equiv directive is like .equ and .set, except that the assembler will signal an error if symbol is already defined.

Except for the contents of the error message, this is roughly equivalent to

.ifdef SYM
.err
.endif
.equ SYM,VAL

.err

If as assembles a .err directive, it will print an error message and, unless the -Z option was used, it will not generate an object file. This can be used to signal error an conditionally compiled code.

.extern

.extern is accepted in the source program--for compatibility with other assemblers--but it is ignored. as treats all undefined symbols as external.

.file string

.file (which may also be spelled `.app-file') tells as that we are about to start a new logical file. string is the new file name. In general, the filename is recognized whether or not it is surrounded by quotes `"'; but if you wish to specify an empty file name, you must give the quotes--"". This statement may go away in future: it is only recognized to be compatible with old as programs. In some configurations of as, .file has already been removed to avoid conflicts with other assemblers. See section Machine Dependent Features.

.fill repeat , size , value

result, size and value are absolute expressions. This emits repeat copies of size bytes. Repeat may be zero or more. Size may be zero or more, but if it is more than 8, then it is deemed to have the value 8, compatible with other people's assemblers. The contents of each repeat bytes is taken from an 8-byte number. The highest order 4 bytes are zero. The lowest order 4 bytes are value rendered in the byte-order of an integer on the computer as is assembling for. Each size bytes in a repetition is taken from the lowest order size bytes of this number. Again, this bizarre behavior is compatible with other people's assemblers.

size and value are optional. If the second comma and value are absent, value is assumed zero. If the first comma and following tokens are absent, size is assumed to be 1.

.float flonums

This directive assembles zero or more flonums, separated by commas. It has the same effect as .single. The exact kind of floating point numbers emitted depends on how as is configured. See section Machine Dependent Features.

.global symbol, .globl symbol

.global makes the symbol visible to ld. If you define symbol in your partial program, its value is made available to other partial programs that are linked with it. Otherwise, symbol takes its attributes from a symbol of the same name from another file linked into the same program.

Both spellings (`.globl' and `.global') are accepted, for compatibility with other assemblers.

On the HPPA, .global is not always enough to make it accessible to other partial programs. You may need the HPPA-only .EXPORT directive as well. See section HPPA Assembler Directives.

.hword expressions

This expects zero or more expressions, and emits a 16 bit number for each.

This directive is a synonym for `.short'; depending on the target architecture, it may also be a synonym for `.word'.

.ident

This directive is used by some assemblers to place tags in object files. as simply accepts the directive for source-file compatibility with such assemblers, but does not actually emit anything for it.

.if absolute expression

.if marks the beginning of a section of code which is only considered part of the source program being assembled if the argument (which must be an absolute expression) is non-zero. The end of the conditional section of code must be marked by .endif (see section .endif); optionally, you may include code for the alternative condition, flagged by .else (see section .else).

The following variants of .if are also supported:

.ifdef symbol
Assembles the following section of code if the specified symbol has been defined.
.ifndef symbol
.ifnotdef symbol
Assembles the following section of code if the specified symbol has not been defined. Both spelling variants are equivalent.

.include "file"

This directive provides a way to include supporting files at specified points in your source program. The code from file is assembled as if it followed the point of the .include; when the end of the included file is reached, assembly of the original file continues. You can control the search paths used with the `-I' command-line option (see section Command-Line Options). Quotation marks are required around file.

.int expressions

Expect zero or more expressions, of any section, separated by commas. For each expression, emit a number that, at run time, is the value of that expression. The byte order and bit size of the number depends on what kind of target the assembly is for.

.irp symbol,values...

Evaluate a sequence of statements assigning different values to symbol. The sequence of statements starts at the .irp directive, and is terminated by an .endr directive. For each value, symbol is set to value, and the sequence of statements is assembled. If no value is listed, the sequence of statements is assembled once, with symbol set to the null string. To refer to symbol within the sequence of statements, use \symbol.

For example, assembling

        .irp    param,1,2,3
        move    d\param,sp@-
        .endr

is equivalent to assembling

        move    d1,sp@-
        move    d2,sp@-
        move    d3,sp@-

.irpc symbol,values...

Evaluate a sequence of statements assigning different values to symbol. The sequence of statements starts at the .irpc directive, and is terminated by an .endr directive. For each character in value, symbol is set to the character, and the sequence of statements is assembled. If no value is listed, the sequence of statements is assembled once, with symbol set to the null string. To refer to symbol within the sequence of statements, use \symbol.

For example, assembling

        .irpc    param,123
        move    d\param,sp@-
        .endr

is equivalent to assembling

        move    d1,sp@-
        move    d2,sp@-
        move    d3,sp@-

.lcomm symbol , length

Reserve length (an absolute expression) bytes for a local common denoted by symbol. The section and value of symbol are those of the new local common. The addresses are allocated in the bss section, so that at run-time the bytes start off zeroed. Symbol is not declared global (see section .global symbol, .globl symbol), so is normally not visible to ld.

Some targets permit a third argument to be used with .lcomm. This argument specifies the desired alignment of the symbol in the bss section.

The syntax for .lcomm differs slightly on the HPPA. The syntax is `symbol .lcomm, length'; symbol is optional.

.lflags

as accepts this directive, for compatibility with other assemblers, but ignores it.

.line line-number

Change the logical line number. line-number must be an absolute expression. The next line has that logical line number. Therefore any other statements on the current line (after a statement separator character) are reported as on logical line number line-number - 1. One day as will no longer support this directive: it is recognized only for compatibility with existing assembler programs.

Warning: In the AMD29K configuration of as, this command is not available; use the synonym .ln in that context.

Even though this is a directive associated with the a.out or b.out object-code formats, as still recognizes it when producing COFF output, and treats `.line' as though it were the COFF `.ln' if it is found outside a .def/.endef pair.

Inside a .def, `.line' is, instead, one of the directives used by compilers to generate auxiliary symbol information for debugging.

.linkonce [type]

Mark the current section so that the linker only includes a single copy of it. This may be used to include the same section in several different object files, but ensure that the linker will only include it once in the final output file. The .linkonce pseudo-op must be used for each instance of the section. Duplicate sections are detected based on the section name, so it should be unique.

This directive is only supported by a few object file formats; as of this writing, the only object file format which supports it is the Portable Executable format used on Windows NT.

The type argument is optional. If specified, it must be one of the following strings. For example:

.linkonce same_size

Not all types may be supported on all object file formats.

discard
Silently discard duplicate sections. This is the default.
one_only
Warn if there are duplicate sections, but still keep only one copy.
same_size
Warn if any of the duplicates have different sizes.
same_contents
Warn if any of the duplicates do not have exactly the same contents.

.ln line-number

`.ln' is a synonym for `.line'.

.mri val

If val is non-zero, this tells as to enter MRI mode. If val is zero, this tells as to exit MRI mode. This change affects code assembled until the next .mri directive, or until the end of the file. See section Assemble in MRI Compatibility Mode: -M.

.list

Control (in conjunction with the .nolist directive) whether or not assembly listings are generated. These two directives maintain an internal counter (which is zero initially). .list increments the counter, and .nolist decrements it. Assembly listings are generated whenever the counter is greater than zero.

By default, listings are disabled. When you enable them (with the `-a' command line option; see section Command-Line Options), the initial value of the listing counter is one.

.long expressions

.long is the same as `.int', see section .int expressions.

.macro

The commands .macro and .endm allow you to define macros that generate assembly output. For example, this definition specifies a macro sum that puts a sequence of numbers into memory:

        .macro  sum from=0, to=5
        .long   \from
        .if     \to-\from
        sum     "(\from+1)",\to
        .endif
        .endm

With that definition, `SUM 0,5' is equivalent to this assembly input:

        .long   0
        .long   1
        .long   2
        .long   3
        .long   4
        .long   5
.macro macname
.macro macname macargs ...
Begin the definition of a macro called macname. If your macro definition requires arguments, specify their names after the macro name, separated by commas or spaces. You can supply a default value for any macro argument by following the name with `=deflt'. For example, these are all valid .macro statements:
.macro comm
Begin the definition of a macro called comm, which takes no arguments.
.macro plus1 p, p1
.macro plus1 p p1
Either statement begins the definition of a macro called plus1, which takes two arguments; within the macro definition, write `\p' or `\p1' to evaluate the arguments.
.macro reserve_str p1=0 p2
Begin the definition of a macro called reserve_str, with two arguments. The first argument has a default value, but not the second. After the definition is complete, you can call the macro either as `reserve_str a,b' (with `\p1' evaluating to a and `\p2' evaluating to b), or as `reserve_str ,b' (with `\p1' evaluating as the default, in this case `0', and `\p2' evaluating to b).
When you call a macro, you can specify the argument values either by position, or by keyword. For example, `sum 9,17' is equivalent to `sum to=17, from=9'.
.endm
Mark the end of a macro definition.
.exitm
Exit early from the current macro definition.
\@
as maintains a counter of how many macros it has executed in this pseudo-variable; you can copy that number to your output with `\@', but only within a macro definition.

.nolist

Control (in conjunction with the .list directive) whether or not assembly listings are generated. These two directives maintain an internal counter (which is zero initially). .list increments the counter, and .nolist decrements it. Assembly listings are generated whenever the counter is greater than zero.

.octa bignums

This directive expects zero or more bignums, separated by commas. For each bignum, it emits a 16-byte integer.

The term "octa" comes from contexts in which a "word" is two bytes; hence octa-word for 16 bytes.

.org new-lc , fill

Advance the location counter of the current section to new-lc. new-lc is either an absolute expression or an expression with the same section as the current subsection. That is, you can't use .org to cross sections: if new-lc has the wrong section, the .org directive is ignored. To be compatible with former assemblers, if the section of new-lc is absolute, as issues a warning, then pretends the section of new-lc is the same as the current subsection.

.org may only increase the location counter, or leave it unchanged; you cannot use .org to move the location counter backwards.

Because as tries to assemble programs in one pass, new-lc may not be undefined. If you really detest this restriction we eagerly await a chance to share your improved assembler.

Beware that the origin is relative to the start of the section, not to the start of the subsection. This is compatible with other people's assemblers.

When the location counter (of the current subsection) is advanced, the intervening bytes are filled with fill which should be an absolute expression. If the comma and fill are omitted, fill defaults to zero.

.p2align[wl] abs-expr, abs-expr, abs-expr

Pad the location counter (in the current subsection) to a particular storage boundary. The first expression (which must be absolute) is the number of low-order zero bits the location counter must have after advancement. For example `.p2align 3' advances the location counter until it a multiple of 8. If the location counter is already a multiple of 8, no change is needed.

The second expression (also absolute) gives the fill value to be stored in the padding bytes. It (and the comma) may be omitted. If it is omitted, the padding bytes are normally zero. However, on some systems, if the section is marked as containing code and the fill value is omitted, the space is filled with no-op instructions.

The third expression is also absolute, and is also optional. If it is present, it is the maximum number of bytes that should be skipped by this alignment directive. If doing the alignment would require skipping more bytes than the specified maximum, then the alignment is not done at all. You can omit the fill value (the second argument) entirely by simply using two commas after the required alignment; this can be useful if you want the alignment to be filled with no-op instructions when appropriate.

The .p2alignw and .p2alignl directives are variants of the .p2align directive. The .p2alignw directive treats the fill pattern as a two byte word value. The .p2alignl directives treats the fill pattern as a four byte longword value. For example, .p2alignw 2,0x368d will align to a multiple of 4. If it skips two bytes, they will be filled in with the value 0x368d (the exact placement of the bytes depends upon the endianness of the processor). If it skips 1 or 3 bytes, the fill value is undefined.

.psize lines , columns

Use this directive to declare the number of lines--and, optionally, the number of columns--to use for each page, when generating listings.

If you do not use .psize, listings use a default line-count of 60. You may omit the comma and columns specification; the default width is 200 columns.

as generates formfeeds whenever the specified number of lines is exceeded (or whenever you explicitly request one, using .eject).

If you specify lines as 0, no formfeeds are generated save those explicitly specified with .eject.

.quad bignums

.quad expects zero or more bignums, separated by commas. For each bignum, it emits an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a warning message; and just takes the lowest order 8 bytes of the bignum.

The term "quad" comes from contexts in which a "word" is two bytes; hence quad-word for 8 bytes.

.rept count

Repeat the sequence of lines between the .rept directive and the next .endr directive count times.

For example, assembling

        .rept   3
        .long   0
        .endr

is equivalent to assembling

        .long   0
        .long   0
        .long   0

.sbttl "subheading"

Use subheading as the title (third line, immediately after the title line) when generating assembly listings.

This directive affects subsequent pages, as well as the current page if it appears within ten lines of the top of a page.

.scl class

Set the storage-class value for a symbol. This directive may only be used inside a .def/.endef pair. Storage class may flag whether a symbol is static or external, or it may record further symbolic debugging information.

The `.scl' directive is primarily associated with COFF output; when configured to generate b.out output format, as accepts this directive but ignores it.

.section name

Use the .section directive to assemble the following code into a section named name.

This directive is only supported for targets that actually support arbitrarily named sections; on a.out targets, for example, it is not accepted, even with a standard a.out section name.

For COFF targets, the .section directive is used in one of the following ways:

.section name[, "flags"]
.section name[, subsegment]

If the optional argument is quoted, it is taken as flags to use for the section. Each flag is a single character. The following flags are recognized:

b
bss section (uninitialized data)
n
section is not loaded
w
writable section
d
data section
r
read-only section
x
executable section

If no flags are specified, the default flags depend upon the section name. If the section name is not recognized, the default will be for the section to be loaded and writable.

If the optional argument to the .section directive is not quoted, it is taken as a subsegment number (see section Sub-Sections).

For ELF targets, the .section directive is used like this:

.section name[, "flags"[, @type]]

The optional flags argument is a quoted string which may contain any combintion of the following characters:

a
section is allocatable
w
section is writable
x
section is executable

The optional type argument may contain one of the following constants:

@progbits
section contains data
@nobits
section does not contain data (i.e., section only occupies space)

If no flags are specified, the default flags depend upon the section name. If the section name is not recognized, the default will be for the section to have none of the above flags: it will not be allocated in memory, nor writable, nor executable. The section will contain data.

For ELF targets, the assembler supports another type of .section directive for compatibility with the Solaris assembler:

.section "name"[, flags...]

Note that the section name is quoted. There may be a sequence of comma separated flags:

#alloc
section is allocatable
#write
section is writable
#execinstr
section is executable

.set symbol, expression

Set the value of symbol to expression. This changes symbol's value and type to conform to expression. If symbol was flagged as external, it remains flagged (see section Symbol Attributes).

You may .set a symbol many times in the same assembly.

If you .set a global symbol, the value stored in the object file is the last value stored into it.

The syntax for set on the HPPA is `symbol .set expression'.

.short expressions

.short is normally the same as `.word'. See section .word expressions.

In some configurations, however, .short and .word generate numbers of different lengths; see section Machine Dependent Features.

.single flonums

This directive assembles zero or more flonums, separated by commas. It has the same effect as .float. The exact kind of floating point numbers emitted depends on how as is configured. See section Machine Dependent Features.

.size

This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside .def/.endef pairs.

`.size' is only meaningful when generating COFF format output; when as is generating b.out, it accepts this directive but ignores it.

.sleb128 expressions

sleb128 stands for "signed little endian base 128." This is a compact, variable length representation of numbers used by the DWARF symbolic debugging format. See section .uleb128 expressions.

.skip size , fill

This directive emits size bytes, each of value fill. Both size and fill are absolute expressions. If the comma and fill are omitted, fill is assumed to be zero. This is the same as `.space'.

.space size , fill

This directive emits size bytes, each of value fill. Both size and fill are absolute expressions. If the comma and fill are omitted, fill is assumed to be zero. This is the same as `.skip'.

Warning: .space has a completely different meaning for HPPA targets; use .block as a substitute. See HP9000 Series 800 Assembly Language Reference Manual (HP 92432-90001) for the meaning of the .space directive. See section HPPA Assembler Directives, for a summary.

On the AMD 29K, this directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.

Warning: In most versions of the GNU assembler, the directive .space has the effect of .block See section Machine Dependent Features.

.stabd, .stabn, .stabs

There are three directives that begin `.stab'. All emit symbols (see section Symbols), for use by symbolic debuggers. The symbols are not entered in the as hash table: they cannot be referenced elsewhere in the source file. Up to five fields are required:

string
This is the symbol's name. It may contain any character except `\000', so is more general than ordinary symbol names. Some debuggers used to code arbitrarily complex structures into symbol names using this field.
type
An absolute expression. The symbol's type is set to the low 8 bits of this expression. Any bit pattern is permitted, but ld and debuggers choke on silly bit patterns.
other
An absolute expression. The symbol's "other" attribute is set to the low 8 bits of this expression.
desc
An absolute expression. The symbol's descriptor is set to the low 16 bits of this expression.
value
An absolute expression which becomes the symbol's value.

If a warning is detected while reading a .stabd, .stabn, or .stabs statement, the symbol has probably already been created; you get a half-formed symbol in your object file. This is compatible with earlier assemblers!

.stabd type , other , desc
The "name" of the symbol generated is not even an empty string. It is a null pointer, for compatibility. Older assemblers used a null pointer so they didn't waste space in object files with empty strings. The symbol's value is set to the location counter, relocatably. When your program is linked, the value of this symbol is the address of the location counter when the .stabd was assembled.
.stabn type , other , desc , value
The name of the symbol is set to the empty string "".
.stabs string , type , other , desc , value
All five fields are specified.

.string "str"

Copy the characters in str to the object file. You may specify more than one string to copy, separated by commas. Unless otherwise specified for a particular machine, the assembler marks the end of each string with a 0 byte. You can use any of the escape sequences described in section Strings.

.symver

Use the .symver directive to bind symbols to specific version nodes within a source file. This is only supported on ELF platforms, and is typically used when assembling files to be linked into a shared library. There are cases where it may make sense to use this in objects to be bound into an application itself so as to override a versioned symbol from a shared library.

For ELF targets, the .symver directive is used like this:

.symver name, name2@nodename

In this case, the symbol name must exist and be defined within the file being assembled. The .versym directive effectively creates a symbol alias with the name name2@nodename, and in fact the main reason that we just don't try and create a regular alias is that the @ character isn't permitted in symbol names. The name2 part of the name is the actual name of the symbol by which it will be externally referenced. The name name itself is merely a name of convenience that is used so that it is possible to have definitions for multiple versions of a function within a single source file, and so that the compiler can unambiguously know which version of a function is being mentioned. The nodename portion of the alias should be the name of a node specified in the version script supplied to the linker when building a shared library. If you are attempting to override a versioned symbol from a shared library, then nodename should correspond to the nodename of the symbol you are trying to override.

.tag structname

This directive is generated by compilers to include auxiliary debugging information in the symbol table. It is only permitted inside .def/.endef pairs. Tags are used to link structure definitions in the symbol table with instances of those structures.

`.tag' is only used when generating COFF format output; when as is generating b.out, it accepts this directive but ignores it.

.text subsection

Tells as to assemble the following statements onto the end of the text subsection numbered subsection, which is an absolute expression. If subsection is omitted, subsection number zero is used.

.title "heading"

Use heading as the title (second line, immediately after the source file name and pagenumber) when generating assembly listings.

This directive affects subsequent pages, as well as the current page if it appears within ten lines of the top of a page.

.type int

This directive, permitted only within .def/.endef pairs, records the integer int as the type attribute of a symbol table entry.

`.type' is associated only with COFF format output; when as is configured for b.out output, it accepts this directive but ignores it.

.val addr

This directive, permitted only within .def/.endef pairs, records the address addr as the value attribute of a symbol table entry.

`.val' is used only for COFF output; when as is configured for b.out, it accepts this directive but ignores it.

.uleb128 expressions

uleb128 stands for "unsigned little endian base 128." This is a compact, variable length representation of numbers used by the DWARF symbolic debugging format. See section .sleb128 expressions.

.word expressions

This directive expects zero or more expressions, of any section, separated by commas.

The size of the number emitted, and its byte order, depend on what target computer the assembly is for.

Warning: Special Treatment to support Compilers

Machines with a 32-bit address space, but that do less than 32-bit addressing, require the following special treatment. If the machine of interest to you does 32-bit addressing (or doesn't require it; see section Machine Dependent Features), you can ignore this issue.

In order to assemble compiler output into something that works, as occasionlly does strange things to `.word' directives. Directives of the form `.word sym1-sym2' are often emitted by compilers as part of jump tables. Therefore, when as assembles a directive of the form `.word sym1-sym2', and the difference between sym1 and sym2 does not fit in 16 bits, as creates a secondary jump table, immediately before the next label. This secondary jump table is preceded by a short-jump to the first byte after the secondary table. This short-jump prevents the flow of control from accidentally falling into the new table. Inside the table is a long-jump to sym2. The original `.word' contains sym1 minus the address of the long-jump to sym2.

If there were several occurrences of `.word sym1-sym2' before the secondary jump table, all of them are adjusted. If there was a `.word sym3-sym4', that also did not fit in sixteen bits, a long-jump to sym4 is included in the secondary jump table, and the .word directives are adjusted to contain sym3 minus the address of the long-jump to sym4; and so on, for as many entries in the original jump table as necessary.

Deprecated Directives

One day these directives won't work. They are included for compatibility with older assemblers.

.abort
.app-file
.line

Machine Dependent Features

The machine instruction sets are (almost by definition) different on each machine where as runs. Floating point representations vary as well, and as often supports a few additional directives or command-line options for compatibility with other assemblers on a particular platform. Finally, some versions of as support special pseudo-instructions for branch optimization.

This chapter discusses most of these differences, though it does not include details on any machine's instruction set. For details on that subject, see the hardware manufacturer's manual.

@lowersections

ARC Dependent Features

Options

The ARC chip family includes several successive levels (or other variants) of chip, using the same core instruction set, but including a few additional instructions at each level.

By default, as assumes the core instruction set (ARC base). The .cpu pseudo-op is intended to be used to select the variant.

-mbig-endian
-mlittle-endian
Any ARC configuration of as can select big-endian or little-endian output at run time (unlike most other GNU development tools, which must be configured for one or the other). Use `-mbig-endian' to select big-endian output, and `-mlittle-endian' for little-endian.

Floating Point

The ARC cpu family currently does not have hardware floating point support. Software floating point support is provided by GCC and uses IEEE floating-point numbers.

ARC Machine Directives

The ARC version of as supports the following additional machine directives:

.cpu
This must be followed by the desired cpu. The ARC is intended to be customizable, .cpu is used to select the desired variant [though currently there are none].

AMD 29K Dependent Features

Options

as has no additional command-line options for the AMD 29K family.

Syntax

Macros

The macro syntax used on the AMD 29K is like that described in the AMD 29K Family Macro Assembler Specification. Normal as macros should still work.

Special Characters

`;' is the line comment character.

The character `?' is permitted in identifiers (but may not begin an identifier).

Register Names

General-purpose registers are represented by predefined symbols of the form `GRnnn' (for global registers) or `LRnnn' (for local registers), where nnn represents a number between 0 and 127, written with no leading zeros. The leading letters may be in either upper or lower case; for example, `gr13' and `LR7' are both valid register names.

You may also refer to general-purpose registers by specifying the register number as the result of an expression (prefixed with `%%' to flag the expression as a register number):

%%expression

---where expression must be an absolute expression evaluating to a number between 0 and 255. The range [0, 127] refers to global registers, and the range [128, 255] to local registers.

In addition, as understands the following protected special-purpose register names for the AMD 29K family:

  vab    chd    pc0
  ops    chc    pc1
  cps    rbp    pc2
  cfg    tmc    mmu
  cha    tmr    lru

These unprotected special-purpose register names are also recognized:

  ipc    alu    fpe
  ipa    bp     inte
  ipb    fc     fps
  q      cr     exop

Floating Point

The AMD 29K family uses IEEE floating-point numbers.

AMD 29K Machine Directives

.block size , fill
This directive emits size bytes, each of value fill. Both size and fill are absolute expressions. If the comma and fill are omitted, fill is assumed to be zero. In other versions of the GNU assembler, this directive is called `.space'.
.cputype
This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.
.file
This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.

Warning: in other versions of the GNU assembler, .file is used for the directive called .app-file in the AMD 29K support.

.line
This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.
.sect
This directive is ignored; it is accepted for compatibility with other AMD 29K assemblers.
.use section name
Establishes the section and subsection for the following code; section name may be one of .text, .data, .data1, or .lit. With one of the first three section name options, `.use' is equivalent to the machine directive section name; the remaining case, `.use .lit', is the same as `.data 200'.

Opcodes

as implements all the standard AMD 29K opcodes. No additional pseudo-instructions are needed on this family.

For information on the 29K machine instruction set, see Am29000 User's Manual, Advanced Micro Devices, Inc.

ARM Dependent Features

Options

-marm [2|250|3|6|60|600|610|620|7|7m|7d|7dm|7di|7dmi|70|700|700i|710|710c|7100|7500|7500fe|7tdmi|8|strongarm|strongarm110]
This option specifies the target processor. The assembler will issue an error message if an attempt is made to assemble an instruction which will not execute on the target processor.
-marmv [2|2a|3|3m|4|4t]
This option specifies the target architecture. The assembler will issue an error message if an attempt is made to assemble an instruction which will not execute on the target architecture.
-mthumb
This option specifies that only Thumb instructions should be assembled.
-mall
This option specifies that any Arm or Thumb instruction should be assembled.
-mfpa [10|11]
This option specifies the floating point architecture in use on the target processor.
-mfpe-old
Do not allow the assemble of floating point multiple instructions.
-mno-fpu
Do not allow the assembly of any floating point instructions.
-mthumb-interwork
This option specifies that the output generated by the assembler should be marked as supporting interworking.
-mapcs [26|32]
This option specifies that the output generated by the assembler should be marked as supporting the indicated version of the Arm Procedure. Calling Standard.
-EB
This option specifies that the output generated by the assembler should be marked as being encoded for a big-endian processor.
-EL
This option specifies that the output generated by the assembler should be marked as being encoded for a little-endian processor.

Syntax

Special Characters

`;' is the line comment character.

*TODO* Explain about /data modifier on symbols.

Register Names

*TODO* Explain about ARM register naming, and the predefined names.

Floating Point

The ARM family uses IEEE floating-point numbers.

ARM Machine Directives

.code [16|32]
This directive selects the instruction set being generated. The value 16 selects Thumb, with the value 32 selecting ARM.
.thumb
This performs the same action as .code 16.
.arm
This performs the same action as .code 32.
.force_thumb
This directive forces the selection of Thumb instructions, even if the target processor does not support those instructions
.thumb_func
This directive specifies that the following symbol is the name of a Thumb encoded function. This information is necessary in order to allow the assembler and linker to generate correct code for interworking between Arm and Thumb instructions and should be used even if interworking is not going to be performed.

Opcodes

as implements all the standard ARM opcodes.

*TODO* Document the pseudo-ops (adr, nop)

For information on the ARM or Thumb instruction sets, see ARM Software Development Toolkit Reference Manual, Advanced RISC Machines Ltd.

D10V Dependent Features

D10V Options

The Mitsubishi D10V version of as has a few machine dependent options.

`-O'
The D10V can often execute two sub-instructions in parallel. When this option is used, as will attempt to optimize its output by detecting when instructions can be executed in parallel.
`--nowarnswap'
To optimize execution performance, as will sometimes swap the order of instructions. Normally this generates a warning. When this option is used, no warning will be generated when instructions are swapped.

Syntax

The D10V syntax is based on the syntax in Mitsubishi's D10V architecture manual. The differences are detailed below.

Size Modifiers

The D10V version of as uses the instruction names in the D10V Architecture Manual. However, the names in the manual are sometimes ambiguous. There are instruction names that can assemble to a short or long form opcode. How does the assembler pick the correct form? as will always pick the smallest form if it can. When dealing with a symbol that is not defined yet when a line is being assembled, it will always use the long form. If you need to force the assembler to use either the short or long form of the instruction, you can append either `.s' (short) or `.l' (long) to it. For example, if you are writing an assembly program and you want to do a branch to a symbol that is defined later in your program, you can write `bra.s foo'. Objdump and GDB will always append `.s' or `.l' to instructions which have both short and long forms.

Sub-Instructions

The D10V assembler takes as input a series of instructions, either one-per-line, or in the special two-per-line format described in the next section. Some of these instructions will be short-form or sub-instructions. These sub-instructions can be packed into a single instruction. The assembler will do this automatically. It will also detect when it should not pack instructions. For example, when a label is defined, the next instruction will never be packaged with the previous one. Whenever a branch and link instruction is called, it will not be packaged with the next instruction so the return address will be valid. Nops are automatically inserted when necessary.

If you do not want the assembler automatically making these decisions, you can control the packaging and execution type (parallel or sequential) with the special execution symbols described in the next section.

Special Characters

`;' and `#' are the line comment characters. Sub-instructions may be executed in order, in reverse-order, or in parallel. Instructions listed in the standard one-per-line format will be executed sequentially. To specify the executing order, use the following symbols:

`->'
Sequential with instruction on the left first.
`<-'
Sequential with instruction on the right first.
`||'
Parallel

The D10V syntax allows either one instruction per line, one instruction per line with the execution symbol, or two instructions per line. For example

abs a1 -> abs r0
Execute these sequentially. The instruction on the right is in the right container and is executed second.
abs r0 <- abs a1
Execute these reverse-sequentially. The instruction on the right is in the right container, and is executed first.
ld2w r2,@r8+ || mac a0,r0,r7
Execute these in parallel.
ld2w r2,@r8+ ||
mac a0,r0,r7
Two-line format. Execute these in parallel.
ld2w r2,@r8+
mac a0,r0,r7
Two-line format. Execute these sequentially. Assembler will put them in the proper containers.
ld2w r2,@r8+ ->
mac a0,r0,r7
Two-line format. Execute these sequentially. Same as above but second instruction will always go into right container.

Since `$' has no special meaning, you may use it in symbol names.

Register Names

You can use the predefined symbols `r0' through `r15' to refer to the D10V registers. You can also use `sp' as an alias for `r15'. The accumulators are `a0' and `a1'. There are special register-pair names that may optionally be used in opcodes that require even-numbered registers. Register names are not case sensitive.

Register Pairs

r0-r1
r2-r3
r4-r5
r6-r7
r8-r9
r10-r11
r12-r13
r14-r15

The D10V also has predefined symbols for these control registers and status bits:

psw
Processor Status Word
bpsw
Backup Processor Status Word
pc
Program Counter
bpc
Backup Program Counter
rpt_c
Repeat Count
rpt_s
Repeat Start address
rpt_e
Repeat End address
mod_s
Modulo Start address
mod_e
Modulo End address
iba
Instruction Break Address
f0
Flag 0
f1
Flag 1
c
Carry flag

Addressing Modes

as understands the following addressing modes for the D10V. Rn in the following refers to any of the numbered registers, but not the control registers.

Rn
Register direct
@Rn
Register indirect
@Rn+
Register indirect with post-increment
@Rn-
Register indirect with post-decrement
@-SP
Register indirect with pre-decrement
@(disp, Rn)
Register indirect with displacement
addr
PC relative address (for branch or rep).
#imm
Immediate data (the `#' is optional and ignored)

@WORD Modifier

Any symbol followed by @word will be replaced by the symbol's value shifted right by 2. This is used in situations such as loading a register with the address of a function (or any other code fragment). For example, if you want to load a register with the location of the function main then jump to that function, you could do it as follws:

ldi     r2, main@word
jmp     r2

Floating Point

The D10V has no hardware floating point, but the .float and .double directives generates IEEE floating-point numbers for compatibility with other development tools.

Opcodes

For detailed information on the D10V machine instruction set, see D10V Architecture: A VLIW Microprocessor for Multimedia Applications (Mitsubishi Electric Corp.). as implements all the standard D10V opcodes. The only changes are those described in the section on size modifiers

H8/300 Dependent Features

Options

as has no additional command-line options for the Hitachi H8/300 family.

Syntax

Special Characters

`;' is the line comment character.

`$' can be used instead of a newline to separate statements. Therefore you may not use `$' in symbol names on the H8/300.

Register Names

You can use predefined symbols of the form `rnh' and `rnl' to refer to the H8/300 registers as sixteen 8-bit general-purpose registers. n is a digit from `0' to `7'); for instance, both `r0h' and `r7l' are valid register names.

You can also use the eight predefined symbols `rn' to refer to the H8/300 registers as 16-bit registers (you must use this form for addressing).

On the H8/300H, you can also use the eight predefined symbols `ern' (`er0' ... `er7') to refer to the 32-bit general purpose registers.

The two control registers are called pc (program counter; a 16-bit register, except on the H8/300H where it is 24 bits) and ccr (condition code register; an 8-bit register). r7 is used as the stack pointer, and can also be called sp.

Addressing Modes

as understands the following addressing modes for the H8/300:

rn
Register direct
@rn
Register indirect
@(d, rn)
@(d:16, rn)
@(d:24, rn)
Register indirect: 16-bit or 24-bit displacement d from register n. (24-bit displacements are only meaningful on the H8/300H.)
@rn+
Register indirect with post-increment
@-rn
Register indirect with pre-decrement
@aa
@aa:8
@aa:16
@aa:24
Absolute address aa. (The address size `:24' only makes sense on the H8/300H.)
#xx
#xx:8
#xx:16
#xx:32
Immediate data xx. You may specify the `:8', `:16', or `:32' for clarity, if you wish; but as neither requires this nor uses it--the data size required is taken from context.
@@aa
@@aa:8
Memory indirect. You may specify the `:8' for clarity, if you wish; but as neither requires this nor uses it.

Floating Point

The H8/300 family has no hardware floating point, but the .float directive generates IEEE floating-point numbers for compatibility with other development tools.

H8/300 Machine Directives

as has only one machine-dependent directive for the H8/300:

.h8300h
Recognize and emit additional instructions for the H8/300H variant, and also make .int emit 32-bit numbers rather than the usual (16-bit) for the H8/300 family.

On the H8/300 family (including the H8/300H) `.word' directives generate 16-bit numbers.

Opcodes

For detailed information on the H8/300 machine instruction set, see H8/300 Series Programming Manual (Hitachi ADE--602--025). For information specific to the H8/300H, see H8/300H Series Programming Manual (Hitachi).

as implements all the standard H8/300 opcodes. No additional pseudo-instructions are needed on this family.

Four H8/300 instructions (add, cmp, mov, sub) are defined with variants using the suffixes `.b', `.w', and `.l' to specify the size of a memory operand. as supports these suffixes, but does not require them; since one of the operands is always a register, as can deduce the correct size.

For example, since r0 refers to a 16-bit register,

mov    r0,@foo
is equivalent to
mov.w  r0,@foo

If you use the size suffixes, as issues a warning when the suffix and the register size do not match.

H8/500 Dependent Features

Options

as has no additional command-line options for the Hitachi H8/500 family.

Syntax

Special Characters

`!' is the line comment character.

`;' can be used instead of a newline to separate statements.

Since `$' has no special meaning, you may use it in symbol names.

Register Names

You can use the predefined symbols `r0', `r1', `r2', `r3', `r4', `r5', `r6', and `r7' to refer to the H8/500 registers.

The H8/500 also has these control registers:

cp
code pointer
dp
data pointer
bp
base pointer
tp
stack top pointer
ep
extra pointer
sr
status register
ccr
condition code register

All registers are 16 bits long. To represent 32 bit numbers, use two adjacent registers; for distant memory addresses, use one of the segment pointers (cp for the program counter; dp for r0--r3; ep for r4 and r5; and tp for r6 and r7.

Addressing Modes

as understands the following addressing modes for the H8/500:

Rn
Register direct
@Rn
Register indirect
@(d:8, Rn)
Register indirect with 8 bit signed displacement
@(d:16, Rn)
Register indirect with 16 bit signed displacement
@-Rn
Register indirect with pre-decrement
@Rn+
Register indirect with post-increment
@aa:8
8 bit absolute address
@aa:16
16 bit absolute address
#xx:8
8 bit immediate
#xx:16
16 bit immediate

Floating Point

The H8/500 family has no hardware floating point, but the .float directive generates IEEE floating-point numbers for compatibility with other development tools.

H8/500 Machine Directives

as has no machine-dependent directives for the H8/500. However, on this platform the `.int' and `.word' directives generate 16-bit numbers.

Opcodes

For detailed information on the H8/500 machine instruction set, see H8/500 Series Programming Manual (Hitachi M21T001).

as implements all the standard H8/500 opcodes. No additional pseudo-instructions are needed on this family.

HPPA Dependent Features

Notes

As a back end for GNU CC as has been throughly tested and should work extremely well. We have tested it only minimally on hand written assembly code and no one has tested it much on the assembly output from the HP compilers.

The format of the debugging sections has changed since the original as port (version 1.3X) was released; therefore, you must rebuild all HPPA objects and libraries with the new assembler so that you can debug the final executable.

The HPPA as port generates a small subset of the relocations available in the SOM and ELF object file formats. Additional relocation support will be added as it becomes necessary.

Options

as has no machine-dependent command-line options for the HPPA.

Syntax

The assembler syntax closely follows the HPPA instruction set reference manual; assembler directives and general syntax closely follow the HPPA assembly language reference manual, with a few noteworthy differences.

First, a colon may immediately follow a label definition. This is simply for compatibility with how most assembly language programmers write code.

Some obscure expression parsing problems may affect hand written code which uses the spop instructions, or code which makes significant use of the ! line separator.

as is much less forgiving about missing arguments and other similar oversights than the HP assembler. as notifies you of missing arguments as syntax errors; this is regarded as a feature, not a bug.

Finally, as allows you to use an external symbol without explicitly importing the symbol. Warning: in the future this will be an error for HPPA targets.

Special characters for HPPA targets include:

`;' is the line comment character.

`!' can be used instead of a newline to separate statements.

Since `$' has no special meaning, you may use it in symbol names.

Floating Point

The HPPA family uses IEEE floating-point numbers.

HPPA Assembler Directives

as for the HPPA supports many additional directives for compatibility with the native assembler. This section describes them only briefly. For detailed information on HPPA-specific assembler directives, see HP9000 Series 800 Assembly Language Reference Manual (HP 92432-90001).

as does not support the following assembler directives described in the HP manual:

.endm           .liston
.enter          .locct
.leave          .macro
.listoff

Beyond those implemented for compatibility, as supports one additional assembler directive for the HPPA: .param. It conveys register argument locations for static functions. Its syntax closely follows the .export directive.

These are the additional directives in as for the HPPA:

.block n
.blockz n
Reserve n bytes of storage, and initialize them to zero.
.call
Mark the beginning of a procedure call. Only the special case with no arguments is allowed.
.callinfo [ param=value, ... ] [ flag, ... ]
Specify a number of parameters and flags that define the environment for a procedure. param may be any of `frame' (frame size), `entry_gr' (end of general register range), `entry_fr' (end of float register range), `entry_sr' (end of space register range). The values for flag are `calls' or `caller' (proc has subroutines), `no_calls' (proc does not call subroutines), `save_rp' (preserve return pointer), `save_sp' (proc preserves stack pointer), `no_unwind' (do not unwind this proc), `hpux_int' (proc is interrupt routine).
.code
Assemble into the standard section called `$TEXT$', subsection `$CODE$'.
.copyright "string"
In the SOM object format, insert string into the object code, marked as a copyright string.
.copyright "string"
In the ELF object format, insert string into the object code, marked as a version string.
.enter
Not yet supported; the assembler rejects programs containing this directive.
.entry
Mark the beginning of a procedure.
.exit
Mark the end of a procedure.
.export name [ ,typ ] [ ,param=r ]
Make a procedure name available to callers. typ, if present, must be one of `absolute', `code' (ELF only, not SOM), `data', `entry', `data', `entry', `millicode', `plabel', `pri_prog', or `sec_prog'. param, if present, provides either relocation information for the procedure arguments and result, or a privilege level. param may be `argwn' (where n ranges from 0 to 3, and indicates one of four one-word arguments); `rtnval' (the procedure's result); or `priv_lev' (privilege level). For arguments or the result, r specifies how to relocate, and must be one of `no' (not relocatable), `gr' (argument is in general register), `fr' (in floating point register), or `fu' (upper half of float register). For `priv_lev', r is an integer.
.half n
Define a two-byte integer constant n; synonym for the portable as directive .short.
.import name [ ,typ ]
Converse of .export; make a procedure available to call. The arguments use the same conventions as the first two arguments for .export.
.label name
Define name as a label for the current assembly location.
.leave
Not yet supported; the assembler rejects programs containing this directive.
.origin lc
Advance location counter to lc. Synonym for the portable directive .org.
.param name [ ,typ ] [ ,param=r ]
Similar to .export, but used for static procedures.
.proc
Use preceding the first statement of a procedure.
.procend
Use following the last statement of a procedure.
label .reg expr
Synonym for .equ; define label with the absolute expression expr as its value.
.space secname [ ,params ]
Switch to section secname, creating a new section by that name if necessary. You may only use params when creating a new section, not when switching to an existing one. secname may identify a section by number rather than by name. If specified, the list params declares attributes of the section, identified by keywords. The keywords recognized are `spnum=exp' (identify this section by the number exp, an absolute expression), `sort=exp' (order sections according to this sort key when linking; exp is an absolute expression), `unloadable' (section contains no loadable data), `notdefined' (this section defined elsewhere), and `private' (data in this section not available to other programs).
.spnum secnam
Allocate four bytes of storage, and initialize them with the section number of the section named secnam. (You can define the section number with the HPPA .space directive.)
.string "str"
Copy the characters in the string str to the object file. See section Strings, for information on escape sequences you can use in as strings. Warning! The HPPA version of .string differs from the usual as definition: it does not write a zero byte after copying str.
.stringz "str"
Like .string, but appends a zero byte after copying str to object file.
.subspa name [ ,params ]
.nsubspa name [ ,params ]
Similar to .space, but selects a subsection name within the current section. You may only specify params when you create a subsection (in the first instance of .subspa for this name). If specified, the list params declares attributes of the subsection, identified by keywords. The keywords recognized are `quad=expr' ("quadrant" for this subsection), `align=expr' (alignment for beginning of this subsection; a power of two), `access=expr' (value for "access rights" field), `sort=expr' (sorting order for this subspace in link), `code_only' (subsection contains only code), `unloadable' (subsection cannot be loaded into memory), `common' (subsection is common block), `dup_comm' (initialized data may have duplicate names), or `zero' (subsection is all zeros, do not write in object file). .nsubspa always creates a new subspace with the given name, even if one with the same name already exists.
.version "str"
Write str as version identifier in object code.

Opcodes

For detailed information on the HPPA machine instruction set, see PA-RISC Architecture and Instruction Set Reference Manual (HP 09740-90039).

80386 Dependent Features

Options

The 80386 has no machine dependent options.

AT&T Syntax versus Intel Syntax

In order to maintain compatibility with the output of gcc, as supports AT&T System V/386 assembler syntax. This is quite different from Intel syntax. We mention these differences because almost all 80386 documents used only Intel syntax. Notable differences between the two syntaxes are:

  • AT&T immediate operands are preceded by `$'; Intel immediate operands are undelimited (Intel `push 4' is AT&T `pushl $4'). AT&T register operands are preceded by `%'; Intel register operands are undelimited. AT&T absolute (as opposed to PC relative) jump/call operands are prefixed by `*'; they are undelimited in Intel syntax.
  • AT&T and Intel syntax use the opposite order for source and destination operands. Intel `add eax, 4' is `addl $4, %eax'. The `source, dest' convention is maintained for compatibility with previous Unix assemblers.
  • In AT&T syntax the size of memory operands is determined from the last character of the opcode name. Opcode suffixes of `b', `w', and `l' specify byte (8-bit), word (16-bit), and long (32-bit) memory references. Intel syntax accomplishes this by prefixes memory operands (not the opcodes themselves) with `byte ptr', `word ptr', and `dword ptr'. Thus, Intel `mov al, byte ptr foo' is `movb foo, %al' in AT&T syntax.
  • Immediate form long jumps and calls are `lcall/ljmp $section, $offset' in AT&T syntax; the Intel syntax is `call/jmp far section:offset'. Also, the far return instruction is `lret $stack-adjust' in AT&T syntax; Intel syntax is `ret far stack-adjust'.
  • The AT&T assembler does not provide support for multiple section programs. Unix style systems expect all programs to be single sections.

Opcode Naming

Opcode names are suffixed with one character modifiers which specify the size of operands. The letters `b', `w', and `l' specify byte, word, and long operands. If no suffix is specified by an instruction and it contains no memory operands then as tries to fill in the missing suffix based on the destination register operand (the last one by convention). Thus, `mov %ax, %bx' is equivalent to `movw %ax, %bx'; also, `mov $1, %bx' is equivalent to `movw $1, %bx'. Note that this is incompatible with the AT&T Unix assembler which assumes that a missing opcode suffix implies long operand size. (This incompatibility does not affect compiler output since compilers always explicitly specify the opcode suffix.)

Almost all opcodes have the same names in AT&T and Intel format. There are a few exceptions. The sign extend and zero extend instructions need two sizes to specify them. They need a size to sign/zero extend from and a size to zero extend to. This is accomplished by using two opcode suffixes in AT&T syntax. Base names for sign extend and zero extend are `movs...' and `movz...' in AT&T syntax (`movsx' and `movzx' in Intel syntax). The opcode suffixes are tacked on to this base name, the from suffix before the to suffix. Thus, `movsbl %al, %edx' is AT&T syntax for "move sign extend from %al to %edx." Possible suffixes, thus, are `bl' (from byte to long), `bw' (from byte to word), and `wl' (from word to long).

The Intel-syntax conversion instructions

  • `cbw' -- sign-extend byte in `%al' to word in `%ax',
  • `cwde' -- sign-extend word in `%ax' to long in `%eax',
  • `cwd' -- sign-extend word in `%ax' to long in `%dx:%ax',
  • `cdq' -- sign-extend dword in `%eax' to quad in `%edx:%eax',

are called `cbtw', `cwtl', `cwtd', and `cltd' in AT&T naming. as accepts either naming for these instructions.

Far call/jump instructions are `lcall' and `ljmp' in AT&T syntax, but are `call far' and `jump far' in Intel convention.

Register Naming

Register operands are always prefixes with `%'. The 80386 registers consist of

  • the 8 32-bit registers `%eax' (the accumulator), `%ebx', `%ecx', `%edx', `%edi', `%esi', `%ebp' (the frame pointer), and `%esp' (the stack pointer).
  • the 8 16-bit low-ends of these: `%ax', `%bx', `%cx', `%dx', `%di', `%si', `%bp', and `%sp'.
  • the 8 8-bit registers: `%ah', `%al', `%bh', `%bl', `%ch', `%cl', `%dh', and `%dl' (These are the high-bytes and low-bytes of `%ax', `%bx', `%cx', and `%dx')
  • the 6 section registers `%cs' (code section), `%ds' (data section), `%ss' (stack section), `%es', `%fs', and `%gs'.
  • the 3 processor control registers `%cr0', `%cr2', and `%cr3'.
  • the 6 debug registers `%db0', `%db1', `%db2', `%db3', `%db6', and `%db7'.
  • the 2 test registers `%tr6' and `%tr7'.
  • the 8 floating point register stack `%st' or equivalently `%st(0)', `%st(1)', `%st(2)', `%st(3)', `%st(4)', `%st(5)', `%st(6)', and `%st(7)'.

Opcode Prefixes

Opcode prefixes are used to modify the following opcode. They are used to repeat string instructions, to provide section overrides, to perform bus lock operations, and to give operand and address size (16-bit operands are specified in an instruction by prefixing what would normally be 32-bit operands with a "operand size" opcode prefix). Opcode prefixes are usually given as single-line instructions with no operands, and must directly precede the instruction they act upon. For example, the `scas' (scan string) instruction is repeated with:

        repne
        scas

Here is a list of opcode prefixes:

  • Section override prefixes `cs', `ds', `ss', `es', `fs', `gs'. These are automatically added by specifying using the section:memory-operand form for memory references.
  • Operand/Address size prefixes `data16' and `addr16' change 32-bit operands/addresses into 16-bit operands/addresses. Note that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes) are not supported (yet).
  • The bus lock prefix `lock' inhibits interrupts during execution of the instruction it precedes. (This is only valid with certain instructions; see a 80386 manual for details).
  • The wait for coprocessor prefix `wait' waits for the coprocessor to complete the current instruction. This should never be needed for the 80386/80387 combination.
  • The `rep', `repe', and `repne' prefixes are added to string instructions to make them repeat `%ecx' times.

Memory References

An Intel syntax indirect memory reference of the form

section:[base + index*scale + disp]

is translated into the AT&T syntax

section:disp(base, index, scale)

where base and index are the optional 32-bit base and index registers, disp is the optional displacement, and scale, taking the values 1, 2, 4, and 8, multiplies index to calculate the address of the operand. If no scale is specified, scale is taken to be 1. section specifies the optional section register for the memory operand, and may override the default section register (see a 80386 manual for section register defaults). Note that section overrides in AT&T syntax must have be preceded by a `%'. If you specify a section override which coincides with the default section register, as does not output any section register override prefixes to assemble the given instruction. Thus, section overrides can be specified to emphasize which section register is used for a given memory operand.

Here are some examples of Intel and AT&T style memory references:

AT&T: `-4(%ebp)', Intel: `[ebp - 4]'
base is `%ebp'; disp is `-4'. section is missing, and the default section is used (`%ss' for addressing with `%ebp' as the base register). index, scale are both missing.
AT&T: `foo(,%eax,4)', Intel: `[foo + eax*4]'
index is `%eax' (scaled by a scale 4); disp is `foo'. All other fields are missing. The section register here defaults to `%ds'.
AT&T: `foo(,1)'; Intel `[foo]'
This uses the value pointed to by `foo' as a memory operand. Note that base and index are both missing, but there is only one `,'. This is a syntactic exception.
AT&T: `%gs:foo'; Intel `gs:foo'
This selects the contents of the variable `foo' with section register section being `%gs'.

Absolute (as opposed to PC relative) call and jump operands must be prefixed with `*'. If no `*' is specified, as always chooses PC relative addressing for jump/call labels.

Any instruction that has a memory operand must specify its size (byte, word, or long) with an opcode suffix (`b', `w', or `l', respectively).

Handling of Jump Instructions

Jump instructions are always optimized to use the smallest possible displacements. This is accomplished by using byte (8-bit) displacement jumps whenever the target is sufficiently close. If a byte displacement is insufficient a long (32-bit) displacement is used. We do not support word (16-bit) displacement jumps (i.e. prefixing the jump instruction with the `addr16' opcode prefix), since the 80386 insists upon masking `%eip' to 16 bits after the word displacement is added.

Note that the `jcxz', `jecxz', `loop', `loopz', `loope', `loopnz' and `loopne' instructions only come in byte displacements, so that if you use these instructions (gcc does not use them) you may get an error message (and incorrect code). The AT&T 80386 assembler tries to get around this problem by expanding `jcxz foo' to

         jcxz cx_zero
         jmp cx_nonzero
cx_zero: jmp foo
cx_nonzero:

Floating Point

All 80387 floating point types except packed BCD are supported. (BCD support may be added without much difficulty). These data types are 16-, 32-, and 64- bit integers, and single (32-bit), double (64-bit), and extended (80-bit) precision floating point. Each supported type has an opcode suffix and a constructor associated with it. Opcode suffixes specify operand's data types. Constructors build these data types into memory.

  • Floating point constructors are `.float' or `.single', `.double', and `.tfloat' for 32-, 64-, and 80-bit formats. These correspond to opcode suffixes `s', `l', and `t'. `t' stands for temporary real, and that the 80387 only supports this format via the `fldt' (load temporary real to stack top) and `fstpt' (store temporary real and pop stack) instructions.
  • Integer constructors are `.word', `.long' or `.int', and `.quad' for the 16-, 32-, and 64-bit integer formats. The corresponding opcode suffixes are `s' (single), `l' (long), and `q' (quad). As with the temporary real format the 64-bit `q' format is only present in the `fildq' (load quad integer to stack top) and `fistpq' (store quad integer and pop stack) instructions.

Register to register operations do not require opcode suffixes, so that `fst %st, %st(1)' is equivalent to `fstl %st, %st(1)'.

Writing 16-bit Code

While GAS normally writes only "pure" 32-bit i386 code, it has limited support for writing code to run in real mode or in 16-bit protected mode code segments. To do this, insert a `.code16' directive before the assembly language instructions to be run in 16-bit mode. You can switch GAS back to writing normal 32-bit code with the `.code32' directive.

GAS understands exactly the same assembly language syntax in 16-bit mode as in 32-bit mode. The function of any given instruction is exactly the same regardless of mode, as long as the resulting object code is executed in the mode for which GAS wrote it. So, for example, the `ret' mnemonic produces a 32-bit return instruction regardless of whether it is to be run in 16-bit or 32-bit mode. (If GAS is in 16-bit mode, it will add an operand size prefix to the instruction to force it to be a 32-bit return.)

This means, for one thing, that you can use GNU CC to write code to be run in real mode or 16-bit protected mode. Just insert the statement `asm(".code16");' at the beginning of your C source file, and while GNU CC will still be generating 32-bit code, GAS will automatically add all the necessary size prefixes to make that code run in 16-bit mode. Of course, since GNU CC only writes small-model code (it doesn't know how to attach segment selectors to pointers like native x86 compilers do), any 16-bit code you write with GNU CC will essentially be limited to a 64K address space. Also, there will be a code size and performance penalty due to all the extra address and operand size prefixes GAS has to add to the instructions.

Note that placing GAS in 16-bit mode does not mean that the resulting code will necessarily run on a 16-bit pre-80386 processor. To write code that runs on such a processor, you would have to refrain from using any 32-bit constructs which require GAS to output address or operand size prefixes. At the moment this would be rather difficult, because GAS currently supports only 32-bit addressing modes: when writing 16-bit code, it always outputs address size prefixes for any instruction that uses a non-register addressing mode. So you can write code that runs on 16-bit processors, but only if that code never references memory.

Notes

There is some trickery concerning the `mul' and `imul' instructions that deserves mention. The 16-, 32-, and 64-bit expanding multiplies (base opcode `0xf6'; extension 4 for `mul' and 5 for `imul') can be output only in the one operand form. Thus, `imul %ebx, %eax' does not select the expanding multiply; the expanding multiply would clobber the `%edx' register, and this would confuse gcc output. Use `imul %ebx' to get the 64-bit product in `%edx:%eax'.

We have added a two operand form of `imul' when the first operand is an immediate mode expression and the second operand is a register. This is just a shorthand, so that, multiplying `%eax' by 69, for example, can be done with `imul $69, %eax' rather than `imul $69, %eax, %eax'.

Intel 80960 Dependent Features

i960 Command-line Options

-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC
Select the 80960 architecture. Instructions or features not supported by the selected architecture cause fatal errors. `-ACA' is equivalent to `-ACA_A'; `-AKC' is equivalent to `-AMC'. Synonyms are provided for compatibility with other tools. If you do not specify any of these options, as generates code for any instruction or feature that is supported by some version of the 960 (even if this means mixing architectures!). In principle, as attempts to deduce the minimal sufficient processor type if none is specified; depending on the object code format, the processor type may be recorded in the object file. If it is critical that the as output match a specific architecture, specify that architecture explicitly.
-b
Add code to collect information about conditional branches taken, for later optimization using branch prediction bits. (The conditional branch instructions have branch prediction bits in the CA, CB, and CC architectures.) If BR represents a conditional branch instruction, the following represents the code generated by the assembler when `-b' is specified:
        call    increment routine
        .word   0       # pre-counter
Label:  BR
        call    increment routine
        .word   0       # post-counter
The counter following a branch records the number of times that branch was not taken; the differenc between the two counters is the number of times the branch was taken. A table of every such Label is also generated, so that the external postprocessor gbr960 (supplied by Intel) can locate all the counters. This table is always labelled `__BRANCH_TABLE__'; this is a local symbol to permit collecting statistics for many separate object files. The table is word aligned, and begins with a two-word header. The first word, initialized to 0, is used in maintaining linked lists of branch tables. The second word is a count of the number of entries in the table, which follow immediately: each is a word, pointing to one of the labels illustrated above. The first word of the header is used to locate multiple branch tables, since each object file may contain one. Normally the links are maintained with a call to an initialization routine, placed at the beginning of each function in the file. The GNU C compiler generates these calls automatically when you give it a `-b' option. For further details, see the documentation of `gbr960'.
-no-relax
Normally, Compare-and-Branch instructions with targets that require displacements greater than 13 bits (or that have external targets) are replaced with the corresponding compare (or `chkbit') and branch instructions. You can use the `-no-relax' option to specify that as should generate errors instead, if the target displacement is larger than 13 bits. This option does not affect the Compare-and-Jump instructions; the code emitted for them is always adjusted when necessary (depending on displacement size), regardless of whether you use `-no-relax'.

Floating Point

as generates IEEE floating-point numbers for the directives `.float', `.double', `.extended', and `.single'.

i960 Machine Directives

.bss symbol, length, align
Reserve length bytes in the bss section for a local symbol, aligned to the power of two specified by align. length and align must be positive absolute expressions. This directive differs from `.lcomm' only in that it permits you to specify an alignment. See section .lcomm symbol , length.
.extended flonums
.extended expects zero or more flonums, separated by commas; for each flonum, `.extended' emits an IEEE extended-format (80-bit) floating-point number.
.leafproc call-lab, bal-lab
You can use the `.leafproc' directive in conjunction with the optimized callj instruction to enable faster calls of leaf procedures. If a procedure is known to call no other procedures, you may define an entry point that skips procedure prolog code (and that does not depend on system-supplied saved context), and declare it as the bal-lab using `.leafproc'. If the procedure also has an entry point that goes through the normal prolog, you can specify that entry point as call-lab. A `.leafproc' declaration is meant for use in conjunction with the optimized call instruction `callj'; the directive records the data needed later to choose between converting the `callj' into a bal or a call. call-lab is optional; if only one argument is present, or if the two arguments are identical, the single argument is assumed to be the bal entry point.
.sysproc name, index
The `.sysproc' directive defines a name for a system procedure. After you define it using `.sysproc', you can use name to refer to the system procedure identified by index when calling procedures with the optimized call instruction `callj'. Both arguments are required; index must be between 0 and 31 (inclusive).

i960 Opcodes

All Intel 960 machine instructions are supported; see section i960 Command-line Options for a discussion of selecting the instruction subset for a particular 960 architecture.

Some opcodes are processed beyond simply emitting a single corresponding instruction: `callj', and Compare-and-Branch or Compare-and-Jump instructions with target displacements larger than 13 bits.

callj

You can write callj to have the assembler or the linker determine the most appropriate form of subroutine call: `call', `bal', or `calls'. If the assembly source contains enough information--a `.leafproc' or `.sysproc' directive defining the operand--then as translates the callj; if not, it simply emits the callj, leaving it for the linker to resolve.

Compare-and-Branch

The 960 architectures provide combined Compare-and-Branch instructions that permit you to store the branch target in the lower 13 bits of the instruction word itself. However, if you specify a branch target far enough away that its address won't fit in 13 bits, the assembler can either issue an error, or convert your Compare-and-Branch instruction into separate instructions to do the compare and the branch.

Whether as gives an error or expands the instruction depends on two choices you can make: whether you use the `-no-relax' option, and whether you use a "Compare and Branch" instruction or a "Compare and Jump" instruction. The "Jump" instructions are always expanded if necessary; the "Branch" instructions are expanded when necessary unless you specify -no-relax---in which case as gives an error instead.

These are the Compare-and-Branch instructions, their "Jump" variants, and the instruction pairs they may expand into:

M680x0 Dependent Features

M680x0 Options

The Motorola 680x0 version of as has a few machine dependent options.

You can use the `-l' option to shorten the size of references to undefined symbols. If you do not use the `-l' option, references to undefined symbols are wide enough for a full long (32 bits). (Since as cannot know where these symbols end up, as can only allocate space for the linker to fill in later. Since as does not know how far away these symbols are, it allocates as much space as it can.) If you use this option, the references are only one word wide (16 bits). This may be useful if you want the object file to be as small as possible, and you know that the relevant symbols are always less than 17 bits away.

For some configurations, especially those where the compiler normally does not prepend an underscore to the names of user variables, the assembler requires a `%' before any use of a register name. This is intended to let the assembler distinguish between C variables and functions named `a0' through `a7', and so on. The `%' is always accepted, but is not required for certain configurations, notably `sun3'. The `--register-prefix-optional' option may be used to permit omitting the `%' even for configurations for which it is normally required. If this is done, it will generally be impossible to refer to C variables and functions with the same names as register names.

Normally the character `|' is treated as a comment character, which means that it can not be used in expressions. The `--bitwise-or' option turns `|' into a normal character. In this mode, you must either use C style comments, or start comments with a `#' character at the beginning of a line.

If you use an addressing mode with a base register without specifying the size, as will normally use the full 32 bit value. For example, the addressing mode `%a0@(%d0)' is equivalent to `%a0@(%d0:l)'. You may use the `--base-size-default-16' option to tell as to default to using the 16 bit value. In this case, `%a0@(%d0)' is equivalent to `%a0@(%d0:w)'. You may use the `--base-size-default-32' option to restore the default behaviour.

If you use an addressing mode with a displacement, and the value of the displacement is not known, as will normally assume that the value is 32 bits. For example, if the symbol `disp' has not been defined, as will assemble the addressing mode `%a0@(disp,%d0)' as though `disp' is a 32 bit value. You may use the `--disp-size-default-16' option to tell as to instead assume that the displacement is 16 bits. In this case, as will assemble `%a0@(disp,%d0)' as though `disp' is a 16 bit value. You may use the `--disp-size-default-32' option to restore the default behaviour.

as can assemble code for several different members of the Motorola 680x0 family. The default depends upon how as was configured when it was built; normally, the default is to assemble code for the 68020 microprocessor. The following options may be used to change the default. These options control which instructions and addressing modes are permitted. The members of the 680x0 family are very similar. For detailed information about the differences, see the Motorola manuals.

`-m68000'
`-m68ec000'
`-m68hc000'
`-m68hc001'
`-m68008'
`-m68302'
`-m68306'
`-m68307'
`-m68322'
`-m68356'
Assemble for the 68000. `-m68008', `-m68302', and so on are synonyms for `-m68000', since the chips are the same from the point of view of the assembler.
`-m68010'
Assemble for the 68010.
`-m68020'
`-m68ec020'
Assemble for the 68020. This is normally the default.
`-m68030'
`-m68ec030'
Assemble for the 68030.
`-m68040'
`-m68ec040'
Assemble for the 68040.
`-m68060'
`-m68ec060'
Assemble for the 68060.
`-mcpu32'
`-m68330'
`-m68331'
`-m68332'
`-m68333'
`-m68334'
`-m68336'
`-m68340'
`-m68341'
`-m68349'
`-m68360'
Assemble for the CPU32 family of chips.
`-m5200'
Assemble for the ColdFire family of chips.
`-m68881'
`-m68882'
Assemble 68881 floating point instructions. This is the default for the 68020, 68030, and the CPU32. The 68040 and 68060 always support floating point instructions.
`-mno-68881'
Do not assemble 68881 floating point instructions. This is the default for 68000 and the 68010. The 68040 and 68060 always support floating point instructions, even if this option is used.
`-m68851'
Assemble 68851 MMU instructions. This is the default for the 68020, 68030, and 68060. The 68040 accepts a somewhat different set of MMU instructions; `-m68851' and `-m68040' should not be used together.
`-mno-68851'
Do not assemble 68851 MMU instructions. This is the default for the 68000, 68010, and the CPU32. The 68040 accepts a somewhat different set of MMU instructions.

Syntax

This syntax for the Motorola 680x0 was developed at MIT.

The 680x0 version of as uses instructions names and syntax compatible with the Sun assembler. Intervening periods are ignored; for example, `movl' is equivalent to `mov.l'.

In the following table apc stands for any of the address registers (`%a0' through `%a7'), the program counter (`%pc'), the zero-address relative to the program counter (`%zpc'), a suppressed address register (`%za0' through `%za7'), or it may be omitted entirely. The use of size means one of `w' or `l', and it may be omitted, along with the leading colon, unless a scale is also specified. The use of scale means one of `1', `2', `4', or `8', and it may always be omitted along with the leading colon.

The following addressing modes are understood:

Immediate
`#number'
Data Register
`%d0' through `%d7'
Address Register
`%a0' through `%a7'
`%a7' is also known as `%sp', i.e. the Stack Pointer. %a6 is also known as `%fp', the Frame Pointer.
Address Register Indirect
`%a0@' through `%a7@'
Address Register Postincrement
`%a0@+' through `%a7@+'
Address Register Predecrement
`%a0@-' through `%a7@-'
Indirect Plus Offset
`apc@(number)'
Index
`apc@(number,register:size:scale)' The number may be omitted.
Postindex
`apc@(number)@(onumber,register:size:scale)' The onumber or the register, but not both, may be omitted.
Preindex
`apc@(number,register:size:scale)@(onumber)' The number may be omitted. Omitting the register produces the Postindex addressing mode.
Absolute
`symbol', or `digits', optionally followed by `:b', `:w', or `:l'.

Motorola Syntax

The standard Motorola syntax for this chip differs from the syntax already discussed (see section Syntax). as can accept Motorola syntax for operands, even if MIT syntax is used for other operands in the same instruction. The two kinds of syntax are fully compatible.

In the following table apc stands for any of the address registers (`%a0' through `%a7'), the program counter (`%pc'), the zero-address relative to the program counter (`%zpc'), or a suppressed address register (`%za0' through `%za7'). The use of size means one of `w' or `l', and it may always be omitted along with the leading dot. The use of scale means one of `1', `2', `4', or `8', and it may always be omitted along with the leading asterisk.

The following additional addressing modes are understood:

Address Register Indirect
`(%a0)' through `(%a7)'
`%a7' is also known as `%sp', i.e. the Stack Pointer. %a6 is also known as `%fp', the Frame Pointer.
Address Register Postincrement
`(%a0)+' through `(%a7)+'
Address Register Predecrement
`-(%a0)' through `-(%a7)'
Indirect Plus Offset
`number(%a0)' through `number(%a7)', or `number(%pc)'. The number may also appear within the parentheses, as in `(number,%a0)'. When used with the pc, the number may be omitted (with an address register, omitting the number produces Address Register Indirect mode).
Index
`number(apc,register.size*scale)' The number may be omitted, or it may appear within the parentheses. The apc may be omitted. The register and the apc may appear in either order. If both apc and register are address registers, and the size and scale are omitted, then the first register is taken as the base register, and the second as the index register.
Postindex
`([number,apc],register.size*scale,onumber)' The onumber, or the register, or both, may be omitted. Either the number or the apc may be omitted, but not both.
Preindex
`([number,apc,register.size*scale],onumber)' The number, or the apc, or the register, or any two of them, may be omitted. The onumber may be omitted. The register and the apc may appear in either order. If both apc and register are address registers, and the size and scale are omitted, then the first register is taken as the base register, and the second as the index register.

Floating Point

Packed decimal (P) format floating literals are not supported. Feel free to add the code!

The floating point formats generated by directives are these.

.float
Single precision floating point constants.
.double
Double precision floating point constants.
.extend
.ldouble
Extended precision (long double) floating point constants.

680x0 Machine Directives

In order to be compatible with the Sun assembler the 680x0 assembler understands the following directives.

.data1
This directive is identical to a .data 1 directive.
.data2
This directive is identical to a .data 2 directive.
.even
This directive is a special case of the .align directive; it aligns the output to an even byte boundary.
.skip
This directive is identical to a .space directive.

Opcodes

Branch Improvement

Certain pseudo opcodes are permitted for branch instructions. They expand to the shortest branch instruction that reach the target. Generally these mnemonics are made by substituting `j' for `b' at the start of a Motorola mnemonic.

The following table summarizes the pseudo-operations. A * flags cases that are more fully described after the table:

          Displacement
          +-------------------------------------------------
          |                68020   68000/10
Pseudo-Op |BYTE    WORD    LONG    LONG      non-PC relative
          +-------------------------------------------------
     jbsr |bsrs    bsr     bsrl    jsr       jsr
      jra |bras    bra     bral    jmp       jmp
*     jXX |bXXs    bXX     bXXl    bNXs;jmpl bNXs;jmp
*    dbXX |dbXX    dbXX        dbXX; bra; jmpl
*    fjXX |fbXXw   fbXXw   fbXXl             fbNXw;jmp

XX: condition
NX: negative of condition XX

*---see full description below

jbsr
jra
These are the simplest jump pseudo-operations; they always map to one particular machine instruction, depending on the displacement to the branch target.
jXX
Here, `jXX' stands for an entire family of pseudo-operations, where XX is a conditional branch or condition-code test. The full list of pseudo-ops in this family is:
 jhi   jls   jcc   jcs   jne   jeq   jvc
 jvs   jpl   jmi   jge   jlt   jgt   jle
For the cases of non-PC relative displacements and long displacements on the 68000 or 68010, as issues a longer code fragment in terms of NX, the opposite condition to XX. For example, for the non-PC relative case:
    jXX foo
gives
     bNXs oof
     jmp foo
 oof:
dbXX
The full family of pseudo-operations covered here is
 dbhi   dbls   dbcc   dbcs   dbne   dbeq   dbvc
 dbvs   dbpl   dbmi   dbge   dblt   dbgt   dble
 dbf    dbra   dbt
Other than for word and byte displacements, when the source reads `dbXX foo', as emits
     dbXX oo1
     bra oo2
 oo1:jmpl foo
 oo2:
fjXX
This family includes
 fjne   fjeq   fjge   fjlt   fjgt   fjle   fjf
 fjt    fjgl   fjgle  fjnge  fjngl  fjngle fjngt
 fjnle  fjnlt  fjoge  fjogl  fjogt  fjole  fjolt
 fjor   fjseq  fjsf   fjsne  fjst   fjueq  fjuge
 fjugt  fjule  fjult  fjun
For branch targets that are not PC relative, as emits
     fbNX oof
     jmp foo
 oof:
when it encounters `fjXX foo'.

Special Characters

The immediate character is `#' for Sun compatibility. The line-comment character is `|' (unless the `--bitwise-or' option is used). If a `#' appears at the beginning of a line, it is treated as a comment unless it looks like `# line file', in which case it is treated normally.

MIPS Dependent Features

GNU as for MIPS architectures supports several different MIPS processors, and MIPS ISA levels I through IV. For information about the MIPS instruction set, see MIPS RISC Architecture, by Kane and Heindrich (Prentice-Hall). For an overview of MIPS assembly conventions, see "Appendix D: Assembly Language Programming" in the same work.

Assembler options

The MIPS configurations of GNU as support these special options:

-G num
This option sets the largest size of an object that can be referenced implicitly with the gp register. It is only accepted for targets that use ECOFF format. The default value is 8.
-EB
-EL
Any MIPS configuration of as can select big-endian or little-endian output at run time (unlike the other GNU development tools, which must be configured for one or the other). Use `-EB' to select big-endian output, and `-EL' for little-endian.
-mips1
-mips2
-mips3
-mips4
Generate code for a particular MIPS Instruction Set Architecture level. `-mips1' corresponds to the R2000 and R3000 processors, `-mips2' to the R6000 processor, `-mips3' to the R4000 processor, and `-mips4' to the R8000 and R10000 processors. You can also switch instruction sets during the assembly; see section Directives to override the ISA level.
-mips16
-no-mips16
Generate code for the MIPS 16 processor. This is equivalent to putting `.set mips16' at the start of the assembly file. `-no-mips16' turns off this option.
-m4650
-no-m4650
Generate code for the MIPS R4650 chip. This tells the assembler to accept the `mad' and `madu' instruction, and to not schedule `nop' instructions around accesses to the `HI' and `LO' registers. `-no-m4650' turns off this option.
-m4010
-no-m4010
Generate code for the LSI R4010 chip. This tells the assembler to accept the R4010 specific instructions (`addciu', `ffc', etc.), and to not schedule `nop' instructions around accesses to the `HI' and `LO' registers. `-no-m4010' turns off this option.
-mcpu=CPU
Generate code for a particular MIPS cpu. This has little effect on the assembler, but it is passed by gcc.
-nocpp
This option is ignored. It is accepted for command-line compatibility with other assemblers, which use it to turn off C style preprocessing. With GNU as, there is no need for `-nocpp', because the GNU assembler itself never runs the C preprocessor.
--trap
--no-break
as automatically macro expands certain division and multiplication instructions to check for overflow and division by zero. This option causes as to generate code to take a trap exception rather than a break exception when an error is detected. The trap instructions are only supported at Instruction Set Architecture level 2 and higher.
--break
--no-trap
Generate code to take a break exception rather than a trap exception when an error is detected. This is the default.

MIPS ECOFF object code

Assembling for a MIPS ECOFF target supports some additional sections besides the usual .text, .data and .bss. The additional sections are .rdata, used for read-only data, .sdata, used for small data, and .sbss, used for small common objects.

When assembling for ECOFF, the assembler uses the $gp ($28) register to form the address of a "small object". Any object in the .sdata or .sbss sections is considered "small" in this sense. For external objects, or for objects in the .bss section, you can use the gcc `-G' option to control the size of objects addressed via $gp; the default value is 8, meaning that a reference to any object eight bytes or smaller uses $gp. Passing `-G 0' to as prevents it from using the $gp register on the basis of object size (but the assembler uses $gp for objects in .sdata or sbss in any case). The size of an object in the .bss section is set by the .comm or .lcomm directive that defines it. The size of an external object may be set with the .extern directive. For example, `.extern sym,4' declares that the object at sym is 4 bytes in length, whie leaving sym otherwise undefined.

Using small ECOFF objects requires linker support, and assumes that the $gp register is correctly initialized (normally done automatically by the startup code). MIPS ECOFF assembly code must not modify the $gp register.

Directives for debugging information

MIPS ECOFF as supports several directives used for generating debugging information which are not support by traditional MIPS assemblers. These are .def, .endef, .dim, .file, .scl, .size, .tag, .type, .val, .stabd, .stabn, and .stabs. The debugging information generated by the three .stab directives can only be read by GDB, not by traditional MIPS debuggers (this enhancement is required to fully support C++ debugging). These directives are primarily used by compilers, not assembly language programmers!

Directives to override the ISA level

GNU as supports an additional directive to change the MIPS Instruction Set Architecture level on the fly: .set mipsn. n should be a number from 0 to 4. A value from 1 to 4 makes the assembler accept instructions for the corresponding ISA level, from that point on in the assembly. .set mipsn affects not only which instructions are permitted, but also how certain macros are expanded. .set mips0 restores the ISA level to its original level: either the level you selected with command line options, or the default for your configuration. You can use this feature to permit specific R4000 instructions while assembling in 32 bit mode. Use this directive with care!

The directive `.set mips16' puts the assembler into MIPS 16 mode, in which it will assemble instructions for the MIPS 16 processor. Use `.set nomips16' to return to normal 32 bit mode.

Traditional MIPS assemblers do not support this directive.

Directives for extending MIPS 16 bit instructions

By default, MIPS 16 instructions are automatically extended to 32 bits when necessary. The directive `.set noautoextend' will turn this off. When `.set noautoextend' is in effect, any 32 bit instruction must be explicitly extended with the `.e' modifier (e.g., `li.e $4,1000'). The directive `.set autoextend' may be used to once again automatically extend instructions when necessary.

This directive is only meaningful when in MIPS 16 mode. Traditional MIPS assemblers do not support this directive.

Directive to mark data as an instruction

The .insn directive tells as that the following data is actually instructions. This makes a difference in MIPS 16 mode: when loading the address of a label which precedes instructions, as automatically adds 1 to the value, so that jumping to the loaded address will do the right thing.

Directives to save and restore options

The directives .set push and .set pop may be used to save and restore the current settings for all the options which are controlled by .set. The .set push directive saves the current settings on a stack. The .set pop directive pops the stack and restores the settings.

These directives can be useful inside an macro which must change an option such as the ISA level or instruction reordering but does not want to change the state of the code which invoked the macro.

Traditional MIPS assemblers do not support these directives.

Hitachi SH Dependent Features

Options

as has no additional command-line options for the Hitachi SH family.

Syntax

Special Characters

`!' is the line comment character.

You can use `;' instead of a newline to separate statements.

Since `$' has no special meaning, you may use it in symbol names.

Register Names

You can use the predefined symbols `r0', `r1', `r2', `r3', `r4', `r5', `r6', `r7', `r8', `r9', `r10', `r11', `r12', `r13', `r14', and `r15' to refer to the SH registers.

The SH also has these control registers:

pr
procedure register (holds return address)
pc
program counter
mach
macl
high and low multiply accumulator registers
sr
status register
gbr
global base register
vbr
vector base register (for interrupt vectors)

Addressing Modes

as understands the following addressing modes for the SH. Rn in the following refers to any of the numbered registers, but not the control registers.

Rn
Register direct
@Rn
Register indirect
@-Rn
Register indirect with pre-decrement
@Rn+
Register indirect with post-increment
@(disp, Rn)
Register indirect with displacement
@(R0, Rn)
Register indexed
@(disp, GBR)
GBR offset
@(R0, GBR)
GBR indexed
addr
@(disp, PC)
PC relative address (for branch or for addressing memory). The as implementation allows you to use the simpler form addr anywhere a PC relative address is called for; the alternate form is supported for compatibility with other assemblers.
#imm
Immediate data

Floating Point

The SH family has no hardware floating point, but the .float directive generates IEEE floating-point numbers for compatibility with other development tools.

SH Machine Directives

uaword
ualong
as will issue a warning when a misaligned .word or .long directive is used. You may use .uaword or .ualong to indicate that the value is intentionally misaligned.

Opcodes

For detailed information on the SH machine instruction set, see SH-Microcomputer User's Manual (Hitachi Micro Systems, Inc.).

as implements all the standard SH opcodes. No additional pseudo-instructions are needed on this family. Note, however, that because as supports a simpler form of PC-relative addressing, you may simply write (for example)

mov.l  bar,r0

where other assemblers might require an explicit displacement to bar from the program counter:

mov.l  @(disp, PC)

SPARC Dependent Features

Options

The SPARC chip family includes several successive levels, using the same core instruction set, but including a few additional instructions at each level. There are exceptions to this however. For details on what instructions each variant supports, please see the chip's architecture reference manual.

By default, as assumes the core instruction set (SPARC v6), but "bumps" the architecture level as needed: it switches to successively higher architectures as it encounters instructions that only exist in the higher levels.

If not configured for SPARC v9 (sparc64-*-*) GAS will not bump passed sparclite by default, an option must be passed to enable the v9 instructions.

GAS treats sparclite as being compatible with v8, unless an architecture is explicitly requested. SPARC v9 is always incompatible with sparclite.

-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite
-Av8plus | -Av8plusa | -Av9 | -Av9a
Use one of the `-A' options to select one of the SPARC architectures explicitly. If you select an architecture explicitly, as reports a fatal error if it encounters an instruction or feature requiring an incompatible or higher level. `-Av8plus' and `-Av8plusa' select a 32 bit environment. `-Av9' and `-Av9a' select a 64 bit environment and are not available unless GAS is explicitly configured with 64 bit environment support. `-Av8plusa' and `-Av9a' enable the SPARC V9 instruction set with UltraSPARC extensions.
-xarch=v8plus | -xarch=v8plusa
For compatibility with the Solaris v9 assembler. These options are equivalent to -Av8plus and -Av8plusa, respectively.
-bump
Warn whenever it is necessary to switch to another level. If an architecture level is explicitly requested, GAS will not issue warnings until that level is reached, and will then bump the level as required (except between incompatible levels).
-32 | -64
Select the word size, either 32 bits or 64 bits. These options are only available with the ELF object file format, and require that the necessary BFD support has been included.

Enforcing aligned data

SPARC GAS normally permits data to be misaligned. For example, it permits the .long pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris assemblers issue an error when they see misaligned data.

You can use the --enforce-aligned-data option to make SPARC GAS also issue an error about misaligned data, just as the SunOS and Solaris assemblers do.

The --enforce-aligned-data option is not the default because gcc issues misaligned data pseudo-ops when it initializes certain packed data structures (structures defined using the packed attribute). You may have to assemble with GAS in order to initialize packed data structures in your own code.

Floating Point

The Sparc uses IEEE floating-point numbers.

Sparc Machine Directives

The Sparc version of as supports the following additional machine directives:

.align
This must be followed by the desired alignment in bytes.
.common
This must be followed by a symbol name, a positive number, and "bss". This behaves somewhat like .comm, but the syntax is different.
.half
This is functionally identical to .short.
.proc
This directive is ignored. Any text following it on the same line is also ignored.
.reserve
This must be followed by a symbol name, a positive number, and "bss". This behaves somewhat like .lcomm, but the syntax is different.
.seg
This must be followed by "text", "data", or "data1". It behaves like .text, .data, or .data 1.
.skip
This is functionally identical to the .space directive.
.word
On the Sparc, the .word directive produces 32 bit values, instead of the 16 bit values it produces on many other machines.
.xword
On the Sparc V9 processor, the .xword directive produces 64 bit values.

Z8000 Dependent Features

The Z8000 as supports both members of the Z8000 family: the unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with 24 bit addresses.

When the assembler is in unsegmented mode (specified with the unsegm directive), an address takes up one word (16 bit) sized register. When the assembler is in segmented mode (specified with the segm directive), a 24-bit address takes up a long (32 bit) register. See section Assembler Directives for the Z8000, for a list of other Z8000 specific assembler directives.

Options

as has no additional command-line options for the Zilog Z8000 family.

Syntax

Special Characters

`!' is the line comment character.

You can use `;' instead of a newline to separate statements.

Register Names

The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer to different sized groups of registers by register number, with the prefix `r' for 16 bit registers, `rr' for 32 bit registers and `rq' for 64 bit registers. You can also refer to the contents of the first eight (of the sixteen 16 bit registers) by bytes. They are named `rnh' and `rnl'.

byte registers
r0l r0h r1h r1l r2h r2l r3h r3l
r4h r4l r5h r5l r6h r6l r7h r7l

word registers
r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15

long word registers
rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14

quad word registers
rq0 rq4 rq8 rq12

Addressing Modes

as understands the following addressing modes for the Z8000:

rn
Register direct
@rn
Indirect register
addr
Direct: the 16 bit or 24 bit address (depending on whether the assembler is in segmented or unsegmented mode) of the operand is in the instruction.
address(rn)
Indexed: the 16 or 24 bit address is added to the 16 bit register to produce the final address in memory of the operand.
rn(#imm)
Base Address: the 16 or 24 bit register is added to the 16 bit sign extended immediate displacement to produce the final address in memory of the operand.
rn(rm)
Base Index: the 16 or 24 bit register rn is added to the sign extended 16 bit index register rm to produce the final address in memory of the operand.
#xx
Immediate data xx.

Assembler Directives for the Z8000

The Z8000 port of as includes these additional assembler directives, for compatibility with other Z8000 assemblers. As shown, these do not begin with `.' (unlike the ordinary as directives).

segm
Generates code for the segmented Z8001.
unsegm
Generates code for the unsegmented Z8002.
name
Synonym for .file
global
Synonym for .global
wval
Synonym for .word
lval
Synonym for .long
bval
Synonym for .byte
sval
Assemble a string. sval expects one string literal, delimited by single quotes. It assembles each byte of the string into consecutive addresses. You can use the escape sequence `%xx' (where xx represents a two-digit hexadecimal number) to represent the character whose ASCII value is xx. Use this feature to describe single quote and other characters that may not appear in string literals as themselves. For example, the C statement `char *a = "he said \"it's 50% off\"";' is represented in Z8000 assembly language (shown with the assembler output in hex at the left) as @begingroup @let@nonarrowing=@comment
68652073    sval    'he said %22it%27s 50%25 off%22%00'
61696420
22697427
73203530
25206F66
662200
@endgroup
rsect
synonym for .section
block
synonym for .space
even
special case of .align; aligns output to even byte boundary.

Opcodes

For detailed information on the Z8000 machine instruction set, see Z8000 Technical Manual.

VAX Dependent Features

VAX Command-Line Options

The Vax version of as accepts any of the following options, gives a warning message that the option was ignored and proceeds. These options are for compatibility with scripts designed for other people's assemblers.

-D (Debug)
-S (Symbol Table)
-T (Token Trace)
These are obsolete options used to debug old assemblers.
-d (Displacement size for JUMPs)
This option expects a number following the `-d'. Like options that expect filenames, the number may immediately follow the `-d' (old standard) or constitute the whole of the command line argument that follows `-d' (GNU standard).
-V (Virtualize Interpass Temporary File)
Some other assemblers use a temporary file. This option commanded them to keep the information in active memory rather than in a disk file. as always does this, so this option is redundant.
-J (JUMPify Longer Branches)
Many 32-bit computers permit a variety of branch instructions to do the same job. Some of these instructions are short (and fast) but have a limited range; others are long (and slow) but can branch anywhere in virtual memory. Often there are 3 flavors of branch: short, medium and long. Some other assemblers would emit short and medium branches, unless told by this option to emit short and long branches.
-t (Temporary File Directory)
Some other assemblers may use a temporary file, and this option takes a filename being the directory to site the temporary file. Since as does not use a temporary disk file, this option makes no difference. `-t' needs exactly one filename.

The Vax version of the assembler accepts two options when compiled for VMS. They are `-h', and `-+'. The `-h' option prevents as from modifying the symbol-table entries for symbols that contain lowercase characters (I think). The `-+' option causes as to print warning messages if the FILENAME part of the object file, or any symbol name is larger than 31 characters. The `-+' option also inserts some code following the `_main' symbol so that the object file is compatible with Vax-11 "C".

VAX Floating Point

Conversion of flonums to floating point is correct, and compatible with previous assemblers. Rounding is towards zero if the remainder is exactly half the least significant bit.

D, F, G and H floating point formats are understood.

Immediate floating literals (e.g. `S`$6.9') are rendered correctly. Again, rounding is towards zero in the boundary case.

The .float directive produces f format numbers. The .double directive produces d format numbers.

Vax Machine Directives

The Vax version of the assembler supports four directives for generating Vax floating point constants. They are described in the table below.

.dfloat
This expects zero or more flonums, separated by commas, and assembles Vax d format 64-bit floating point constants.
.ffloat
This expects zero or more flonums, separated by commas, and assembles Vax f format 32-bit floating point constants.
.gfloat
This expects zero or more flonums, separated by commas, and assembles Vax g format 64-bit floating point constants.
.hfloat
This expects zero or more flonums, separated by commas, and assembles Vax h format 128-bit floating point constants.

VAX Opcodes

All DEC mnemonics are supported. Beware that case... instructions have exactly 3 operands. The dispatch table that follows the case... instruction should be made with .word statements. This is compatible with all unix assemblers we know of.

VAX Branch Improvement

Certain pseudo opcodes are permitted. They are for branch instructions. They expand to the shortest branch instruction that reaches the target. Generally these mnemonics are made by substituting `j' for `b' at the start of a DEC mnemonic. This feature is included both for compatibility and to help compilers. If you do not need this feature, avoid these opcodes. Here are the mnemonics, and the code they can expand into.

jbsb
`Jsb' is already an instruction mnemonic, so we chose `jbsb'.
(byte displacement)
bsbb ...
(word displacement)
bsbw ...
(long displacement)
jsb ...
jbr
jr
Unconditional branch.
(byte displacement)
brb ...
(word displacement)
brw ...
(long displacement)
jmp ...
jCOND
COND may be any one of the conditional branches neq, nequ, eql, eqlu, gtr, geq, lss, gtru, lequ, vc, vs, gequ, cc, lssu, cs. COND may also be one of the bit tests bs, bc, bss, bcs, bsc, bcc, bssi, bcci, lbs, lbc. NOTCOND is the opposite condition to COND.
(byte displacement)
bCOND ...
(word displacement)
bNOTCOND foo ; brw ... ; foo:
(long displacement)
bNOTCOND foo ; jmp ... ; foo:
jacbX
X may be one of b d f g h l w.
(word displacement)
OPCODE ...
(long displacement)
OPCODE ..., foo ;
brb bar ;
foo: jmp ... ;
bar:
jaobYYY
YYY may be one of lss leq.
jsobZZZ
ZZZ may be one of geq gtr.
(byte displacement)
OPCODE ...
(word displacement)
OPCODE ..., foo ;
brb bar ;
foo: brw destination ;
bar:
(long displacement)
OPCODE ..., foo ;
brb bar ;
foo: jmp destination ;
bar:
aobleq
aoblss
sobgeq
sobgtr
(byte displacement)
OPCODE ...
(word displacement)
OPCODE ..., foo ;
brb bar ;
foo: brw destination ;
bar:
(long displacement)
OPCODE ..., foo ;
brb bar ;
foo: jmp destination ;
bar:

VAX Operands

The immediate character is `$' for Unix compatibility, not `#' as DEC writes it.

The indirect character is `*' for Unix compatibility, not `@' as DEC writes it.

The displacement sizing character is ``' (an accent grave) for Unix compatibility, not `^' as DEC writes it. The letter preceding ``' may have either case. `G' is not understood, but all other letters (b i l s w) are understood.

Register names understood are r0 r1 r2 ... r15 ap fp sp pc. Upper and lower case letters are equivalent.

For instance

tstb *w`$4(r5)

Any expression is permitted in an operand. Operands are comma separated.

Not Supported on VAX

Vax bit fields can not be assembled with as. Someone can add the required code if they really need it.

v850 Dependent Features

Options

as supports the following additional command-line options for the V850 processor family:

-wsigned_overflow
Causes warnings to be produced when signed immediate values overflow the space available for then within their opcodes. By default this option is disabled as it is possible to receive spurious warnings due to using exact bit patterns as immediate constants.
-wunsigned_overflow
Causes warnings to be produced when unsigned immediate values overflow the space available for then within their opcodes. By default this option is disabled as it is possible to receive spurious warnings due to using exact bit patterns as immediate constants.
-mv850
Specifies that the assembled code should be marked as being targeted at the V850 processor. This allows the linker to detect attempts to link such code with code assembled for other processors.

Syntax

Special Characters

`#' is the line comment character.

Register Names

as supports the following names for registers:

general register 0
r0, zero
general register 1
r1
general register 2
r2, hp
general register 3
r3, sp
general register 4
r4, gp
general register 5
r5, tp
general register 6
r6
general register 7
r7
general register 8
r8
general register 9
r9
general register 10
r10
general register 11
r11
general register 12
r12
general register 13
r13
general register 14
r14
general register 15
r15
general register 16
r16
general register 17
r17
general register 18
r18
general register 19
r19
general register 20
r20
general register 21
r21
general register 22
r22
general register 23
r23
general register 24
r24
general register 25
r25
general register 26
r26
general register 27
r27
general register 28
r28
general register 29
r29
general register 30
r30, ep
general register 31
r31, lp
system register 0
eipc
system register 1
eipsw
system register 2
fepc
system register 3
fepsw
system register 4
ecr
system register 5
psw

Floating Point

The V850 family uses IEEE floating-point numbers.

V850 Machine Directives

.offset <expression>
Moves the offset into the current section to the specified amount.
.section "name", <type>
This is an extension to the standard .section directive. It sets the current section to be <type> and creates an alias for this section called "name".
.v850
Specifies that the assembled code should be marked as being targeted at the V850 processor. This allows the linker to detect attempts to link such code with code assembled for other processors.

Opcodes

as implements all the standard V850 opcodes.

as also implements the following pseudo ops:

hi0()
Computes the higher 16 bits of the given expression and stores it into the immediate operand field of the given instruction. For example: `mulhi hi0(here - there), r5, r6' computes the difference between the address of labels 'here' and 'there', takes the upper 16 bits of this difference, shifts it down 16 bits and then mutliplies it by the lower 16 bits in register 5, putting the result into register 6.
lo()
Computes the lower 16 bits of the given expression and stores it into the immediate operand field of the given instruction. For example: `addi lo(here - there), r5, r6' computes the difference between the address of labels 'here' and 'there', takes the lower 16 bits of this difference and adds it to register 5, putting the result into register 6.
hi()
Computes the higher 16 bits of the given expression and then adds the value of the most significant bit of the lower 16 bits of the expression and stores the result into the immediate operand field of the given instruction. For example the following code can be used to compute the address of the label 'here' and store it into register 6: `movhi hi(here), r0, r6' `movea lo(here), r6, r6' The reason for this special behaviour is that movea performs a sign extention on its immediate operand. So for example if the address of 'here' was 0xFFFFFFFF then without the special behaviour of the hi() pseudo-op the movhi instruction would put 0xFFFF0000 into r6, then the movea instruction would takes its immediate operand, 0xFFFF, sign extend it to 32 bits, 0xFFFFFFFF, and then add it into r6 giving 0xFFFEFFFF which is wrong (the fifth nibble is E). With the hi() pseudo op adding in the top bit of the lo() pseudo op, the movhi instruction actually stores 0 into r6 (0xFFFF + 1 = 0x0000), so that the movea instruction stores 0xFFFFFFFF into r6 - the right value.
sdaoff()
Computes the offset of the named variable from the start of the Small Data Area (whoes address is held in register 4, the GP register) and stores the result as a 16 bit signed value in the immediate operand field of the given instruction. For example: `ld.w sdaoff(_a_variable)[gp],r6' loads the contents of the location pointed to by the label '_a_variable' into register 6, provided that the label is located somewhere within +/- 32K of the address held in the GP register. [Note the linker assumes that the GP register contains a fixed address set to the address of the label called '__gp'. This can either be set up automatically by the linker, or specifically set by using the `--defsym __gp=<value>' command line option].
tdaoff()
Computes the offset of the named variable from the start of the Tiny Data Area (whoes address is held in register 30, the EP register) and stores the result as a 7 or 8 bit unsigned value in the immediate operand field of the given instruction. For example: `sld.w tdaoff(_a_variable)[ep],r6' loads the contents of the location pointed to by the label '_a_variable' into register 6, provided that the label is located somewhere within +256 bytes of the address held in the EP register. [Note the linker assumes that the EP register contains a fixed address set to the address of the label called '__ep'. This can either be set up automatically by the linker, or specifically set by using the `--defsym __ep=<value>' command line option].
zdaoff()
Computes the offset of the named variable from address 0 and stores the result as a 16 bit signed value in the immediate operand field of the given instruction. For example: `movea zdaoff(_a_variable),zero,r6' puts the address of the label '_a_variable' into register 6, assuming that the label is somewhere within the first 32K of memory. (Strictly speaking it also possible to access the last 32K of memory as well, as the offsets are signed).

For information on the V850 instruction set, see V850 Family 32-/16-Bit single-Chip Microcontroller Architecture Manual from NEC. Ltd.

@raisesections

Reporting Bugs

Your bug reports play an essential role in making as reliable.

Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of as work better. Bug reports are your contribution to the maintenance of as.

In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug.

Have you found a bug?

If you are not sure whether you have found a bug, here are some guidelines:

  • If the assembler gets a fatal signal, for any input whatever, that is a as bug. Reliable assemblers never crash.
  • If as produces an error message for valid input, that is a bug.
  • If as does not produce an error message for invalid input, that is a bug. However, you should note that your idea of "invalid input" might be our idea of "an extension" or "support for traditional practice".
  • If you are an experienced user of assemblers, your suggestions for improvement of as are welcome in any case.

How to report bugs

A number of companies and individuals offer support for GNU products. If you obtained as from a support organization, we recommend you contact that organization first.

You can find contact information for many support companies and individuals in the file `etc/SERVICE' in the GNU Emacs distribution.

In any event, we also recommend that you send bug reports for as to `bug-gnu-utils@gnu.org'.

The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!

Often people omit facts because they think they know what causes the problem and assume that some details do not matter. Thus, you might assume that the name of a symbol you use in an example does not matter. Well, probably it does not, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that name is stored in memory; perhaps, if the name were different, the contents of that location would fool the assembler into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable us to fix the bug if it is new to us. Therefore, always write your bug reports on the assumption that the bug has not been reported previously.

Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" Those bug reports are useless, and we urge everyone to refuse to respond to them except to chide the sender to report bugs properly.

To enable us to fix the bug, you should include all these things:

  • The version of as. as announces it if you start it with the `--version' argument. Without this, we will not know whether there is any point in looking for the bug in the current version of as.
  • Any patches you may have applied to the as source.
  • The type of machine you are using, and the operating system name and version number.
  • What compiler (and its version) was used to compile as---e.g. "gcc-2.7".
  • The command arguments you gave the assembler to assemble your example and observe the bug. To guarantee you will not omit something important, list them all. A copy of the Makefile (or the output from make) is sufficient. If we were to try to guess the arguments, we would probably guess wrong and then we might not encounter the bug.
  • A complete input file that will reproduce the bug. If the bug is observed when the assembler is invoked via a compiler, send the assembler source, not the high level language source. Most compilers will produce the assembler source when run with the `-S' option. If you are using gcc, use the options `-v --save-temps'; this will save the assembler source in a file with an extension of `.s', and also show you exactly how as is being run.
  • A description of what behavior you observe that you believe is incorrect. For example, "It gets a fatal signal." Of course, if the bug is that as gets a fatal signal, then we will certainly notice it. But if the bug is incorrect output, we might not notice unless it is glaringly wrong. You might as well not give us a chance to make a mistake. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of as is out of synch, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations.
  • If you wish to suggest changes to the as source, send us context diffs, as generated by diff with the `-u', `-c', or `-p' option. Always send diffs from the old file to the new file. If you even discuss something in the as source, refer to it by context, not by line number. The line numbers in our development sources will not match those in your sources. Your line numbers would convey no useful information to us.

Here are some things that are not necessary:

  • A description of the envelope of the bug. Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it. This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. We recommend that you save your time for something else. Of course, if you can find a simpler example to report instead of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take less time, and so on. However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used.
  • A patch for the bug. A patch for the bug does help us if it is a good one. But do not omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. Sometimes with a program as complicated as as it is very hard to construct an example that will make the program follow a certain path through the code. If you do not send us the example, we will not be able to construct one, so we will not be able to verify that the bug is fixed. And if we cannot understand what bug you are trying to fix, or why your patch should be an improvement, we will not install it. A test case will help us to understand.
  • A guess about what the bug is or what it depends on. Such guesses are usually wrong. Even we cannot guess right about such things without first using the debugger to find the facts.

Acknowledgements

If you have contributed to as and your name isn't listed here, it is not meant as a slight. We just don't know about it. Send mail to the maintainer, and we'll correct the situation. Currently the maintainer is Ken Raeburn (email address raeburn@cygnus.com).

Dean Elsner wrote the original GNU assembler for the VAX.(1)

Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug information and the 68k series machines, most of the preprocessing pass, and extensive changes in `messages.c', `input-file.c', `write.c'.

K. Richard Pixley maintained GAS for a while, adding various enhancements and many bug fixes, including merging support for several processors, breaking GAS up to handle multiple object file format back ends (including heavy rewrite, testing, an integration of the coff and b.out back ends), adding configuration including heavy testing and verification of cross assemblers and file splits and renaming, converted GAS to strictly ANSI C including full prototypes, added support for m680[34]0 and cpu32, did considerable work on i960 including a COFF port (including considerable amounts of reverse engineering), a SPARC opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated "know" assertions and made them work, much other reorganization, cleanup, and lint.

Ken Raeburn wrote the high-level BFD interface code to replace most of the code in format-specific I/O modules.

The original VMS support was contributed by David L. Kashtan. Eric Youngdale has done much work with it since.

The Intel 80386 machine description was written by Eliot Dresselhaus.

Minh Tran-Le at IntelliCorp contributed some AIX 386 support.

The Motorola 88k machine description was contributed by Devon Bowen of Buffalo University and Torbjorn Granlund of the Swedish Institute of Computer Science.

Keith Knowles at the Open Software Foundation wrote the original MIPS back end (`tc-mips.c', `tc-mips.h'), and contributed Rose format support (which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to support a.out format.

Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k, tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to use BFD for some low-level operations, for use with the H8/300 and AMD 29k targets.

John Gilmore built the AMD 29000 support, added .include support, and simplified the configuration of which versions accept which directives. He updated the 68k machine description so that Motorola's opcodes always produced fixed-size instructions (e.g. jsr), while synthetic instructions remained shrinkable (jbsr). John fixed many bugs, including true tested cross-compilation support, and one bug in relaxation that took a week and required the proverbial one-bit fix.

Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and PowerPC assembler, and made a few other minor patches.

Steve Chamberlain made as able to generate listings.

Hewlett-Packard contributed support for the HP9000/300.

Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF object formats). This work was supported by both the Center for Software Science at the University of Utah and Cygnus Support.

Support for ELF format files has been worked on by Mark Eichin of Cygnus Support (original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, and some initial 64-bit support).

Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD support for openVMS/Alpha.

Several engineers at Cygnus Support have also provided many small bug fixes and configuration enhancements.

Many others have contributed large or small bugfixes and enhancements. If you have contributed significant work and are not mentioned on this list, and want to be, let us know. Some of the history has been lost; we are not intentionally leaving anyone out.

Index

Jump to: # - $ - - - . - 1 - 2 - : - @ - \ - a - b - c - d - e - f - g - h - i - j - l - m - n - o - p - q - r - s - t - u - v - w - x - z

#

  • #
  • #APP
  • #NO_APP

    • $

  • $ in symbol names, $ in symbol names, $ in symbol names

    • -

  • -+ option, VAX/VMS
  • --
  • `--base-size-default-16'
  • `--base-size-default-32'
  • `--bitwise-or' option, M680x0
  • `--disp-size-default-16'
  • `--disp-size-default-32'
  • --enforce-aligned-data
  • --MD
  • `--register-prefix-optional' option, M680x0
  • --statistics
  • --traditional-format
  • -a
  • -A options, i960
  • -ac
  • -ad
  • -ah
  • -al
  • -an
  • -as
  • -Asparclet
  • -Asparclite
  • -Av6
  • -Av8
  • -Av9
  • -Av9a
  • -b option, i960
  • -D
  • -D, ignored on VAX
  • -d, VAX option
  • -EB command line option, ARM
  • -EB option (MIPS)
  • -EL command line option, ARM
  • -EL option (MIPS)
  • -f
  • -G option (MIPS)
  • -h option, VAX/VMS
  • -I path
  • -J, ignored on VAX
  • -K
  • -L
  • `-l' option, M680x0
  • -M
  • `-m68000' and related options
  • -mall command line option, ARM
  • -mapcs command line option, ARM
  • -marm command line option, ARM
  • -marmv command line option, ARM
  • -mbig-endian option (ARC)
  • -mfpa command line option, ARM
  • -mfpe-old command line option, ARM
  • -mlittle-endian option (ARC)
  • -mno-fpu command line option, ARM
  • -mthumb command line option, ARM
  • -mthumb-interwork command line option, ARM
  • -mv850 command line option, V850
  • -no-relax option, i960
  • -nocpp ignored (MIPS)
  • -o
  • -R
  • -S, ignored on VAX
  • -T, ignored on VAX
  • -t, ignored on VAX
  • -v
  • -V, redundant on VAX
  • -version
  • -W
  • -wsigned_overflow command line option, V850
  • -wunsigned_overflow command line option, V850

    • .

  • . (symbol)
  • .insn
  • .o
  • .param on HPPA
  • .set autoextend
  • .set mipsn
  • .set noautoextend
  • .set pop
  • .set push
  • .v850 directive, V850

    • 1

  • 16-bit code, i386

    • 2

  • 29K support

    • :

  • : (label)

    • @

  • @word modifier, D10V

    • \

  • \" (doublequote character)
  • \\ (`\' character)
  • \b (backspace character)
  • \ddd (octal character code)
  • \f (formfeed character)
  • \n (newline character)
  • \r (carriage return character)
  • \t (tab)
  • \xd... (hex character code)

    • a

  • a.out
  • a.out symbol attributes
  • ABORT directive
  • abort directive
  • absolute section
  • addition, permitted arguments
  • addresses
  • addresses, format of
  • addressing modes, D10V
  • addressing modes, H8/300
  • addressing modes, H8/500
  • addressing modes, M680x0
  • addressing modes, SH
  • addressing modes, Z8000
  • advancing location counter
  • align directive
  • align directive, SPARC
  • altered difference tables
  • alternate syntax for the 680x0
  • AMD 29K floating point (IEEE)
  • AMD 29K identifiers
  • AMD 29K line comment character
  • AMD 29K machine directives
  • AMD 29K macros
  • AMD 29K opcodes
  • AMD 29K options (none)
  • AMD 29K protected registers
  • AMD 29K register names
  • AMD 29K special purpose registers
  • AMD 29K support
  • app-file directive
  • ARC architectures
  • ARC big-endian output
  • ARC endianness
  • ARC floating point (IEEE)
  • ARC little-endian output
  • ARC machine directives
  • ARC options
  • ARC support
  • architecture options, i960
  • architecture options, M680x0
  • architectures, ARC
  • architectures, SPARC
  • arguments for addition
  • arguments for subtraction
  • arguments in expressions
  • arithmetic functions
  • arithmetic operands
  • arm directive, ARM
  • ARM floating point (IEEE)
  • ARM identifiers
  • ARM line comment character
  • ARM machine directives
  • ARM opcodes
  • ARM options (none)
  • ARM register names
  • ARM support
  • ascii directive
  • asciz directive
  • assembler bugs, reporting
  • assembler crash
  • assembler internal logic error
  • assembler version
  • assembler, and linker
  • assembly listings, enabling
  • assigning values to symbols, assigning values to symbols
  • attributes, symbol
  • auxiliary attributes, COFF symbols
  • auxiliary symbol information, COFF
  • Av7

    • b

  • backslash (\\)
  • backspace (\b)
  • balign directive
  • balignl directive
  • balignw directive
  • big endian output, ARC
  • big endian output, MIPS
  • big-endian output, ARC
  • big-endian output, MIPS
  • bignums
  • binary integers
  • bitfields, not supported on VAX
  • block
  • block directive, AMD 29K
  • branch improvement, M680x0
  • branch improvement, VAX
  • branch recording, i960
  • branch statistics table, i960
  • bss directive, i960
  • bss section, bss section
  • bug criteria
  • bug reports
  • bugs in assembler
  • bus lock prefixes, i386
  • bval
  • byte directive

    • c

  • call instructions, i386
  • callj, i960 pseudo-opcode
  • carriage return (\r)
  • character constants
  • character escape codes
  • character, single
  • characters used in symbols
  • code directive, ARM
  • code16 directive, i386
  • code32 directive, i386
  • COFF auxiliary symbol information
  • COFF structure debugging
  • COFF symbol attributes
  • COFF symbol descriptor
  • COFF symbol storage class
  • COFF symbol type
  • COFF symbols, debugging
  • COFF value attribute
  • COMDAT
  • comm directive
  • command line conventions
  • command line options, V850
  • command-line options ignored, VAX
  • comments
  • comments, M680x0
  • comments, removed by preprocessor
  • common directive, SPARC
  • common sections
  • common variable storage
  • compare and jump expansions, i960
  • compare/branch instructions, i960
  • conditional assembly
  • constant, single character
  • constants
  • constants, bignum
  • constants, character
  • constants, converted by preprocessor
  • constants, floating point
  • constants, integer
  • constants, number
  • constants, string
  • continuing statements
  • conversion instructions, i386
  • coprocessor wait, i386
  • cpu directive, SPARC
  • cputype directive, AMD 29K
  • crash of assembler
  • current address
  • current address, advancing

    • d

  • D10V @word modifier
  • D10V addressing modes
  • D10V floating point
  • D10V line comment character
  • D10V opcode summary
  • D10V optimization
  • D10V options
  • D10V registers
  • D10V size modifiers
  • D10V sub-instruction ordering
  • D10V sub-instructions
  • D10V support
  • D10V syntax
  • data alignment on SPARC
  • data and text sections, joining
  • data directive
  • data section
  • data1 directive, M680x0
  • data2 directive, M680x0
  • debuggers, and symbol order
  • debugging COFF symbols
  • decimal integers
  • def directive
  • dependency tracking
  • deprecated directives
  • desc directive
  • descriptor, of a.out symbol
  • dfloat directive, VAX
  • difference tables altered
  • difference tables, warning
  • dim directive
  • directives and instructions
  • directives, M680x0
  • directives, machine independent
  • directives, Z8000
  • displacement sizing character, VAX
  • dot (symbol)
  • double directive
  • double directive, i386
  • double directive, M680x0
  • double directive, VAX
  • doublequote (\")

    • e

  • ECOFF sections
  • ecr register, V850
  • eight-byte integer
  • eipc register, V850
  • eipsw register, V850
  • eject directive
  • else directive
  • empty expressions
  • emulation
  • endef directive
  • endianness, ARC
  • endianness, MIPS
  • endif directive
  • endm directive
  • EOF, newline must precede
  • ep register, V850
  • equ directive
  • equiv directive
  • err directive
  • error messsages
  • error on valid input
  • errors, continuing after
  • escape codes, character
  • even
  • even directive, M680x0
  • exitm directive
  • expr (internal section)
  • expression arguments
  • expressions
  • expressions, empty
  • expressions, integer
  • extend directive M680x0
  • extended directive, i960
  • extern directive

    • f

  • faster processing (-f)
  • fatal signal
  • fepc register, V850
  • fepsw register, V850
  • ffloat directive, VAX
  • file directive
  • file directive, AMD 29K
  • file name, logical, file name, logical
  • files, including
  • files, input
  • fill directive
  • filling memory, filling memory
  • float directive
  • float directive, i386
  • float directive, M680x0
  • float directive, VAX
  • floating point numbers
  • floating point numbers (double)
  • floating point numbers (single), floating point numbers (single)
  • floating point, AMD 29K (IEEE)
  • floating point, ARC (IEEE)
  • floating point, ARM (IEEE)
  • floating point, D10V
  • floating point, H8/300 (IEEE)
  • floating point, H8/500 (IEEE)
  • floating point, HPPA (IEEE)
  • floating point, i386
  • floating point, i960 (IEEE)
  • floating point, M680x0
  • floating point, SH (IEEE)
  • floating point, SPARC (IEEE)
  • floating point, V850 (IEEE)
  • floating point, VAX
  • flonums
  • force_thumb directive, ARM
  • format of error messages
  • format of warning messages
  • formfeed (\f)
  • functions, in expressions

    • g

  • gbr960, i960 postprocessor
  • gfloat directive, VAX
  • global
  • global directive
  • gp register, MIPS
  • gp register, V850
  • grouping data

    • h

  • H8/300 addressing modes
  • H8/300 floating point (IEEE)
  • H8/300 line comment character
  • H8/300 line separator
  • H8/300 machine directives (none)
  • H8/300 opcode summary
  • H8/300 options (none)
  • H8/300 registers
  • H8/300 size suffixes
  • H8/300 support
  • H8/300H, assembling for
  • H8/500 addressing modes
  • H8/500 floating point (IEEE)
  • H8/500 line comment character
  • H8/500 line separator
  • H8/500 machine directives (none)
  • H8/500 opcode summary
  • H8/500 options (none)
  • H8/500 registers
  • H8/500 support
  • half directive, SPARC
  • hex character code (\xd...)
  • hexadecimal integers
  • hfloat directive, VAX
  • hi pseudo-op, V850
  • hi0 pseudo-op, V850
  • HPPA directives not supported
  • HPPA floating point (IEEE)
  • HPPA Syntax
  • HPPA-only directives
  • hword directive

    • i

  • i386 16-bit code
  • i386 conversion instructions
  • i386 floating point
  • i386 immediate operands
  • i386 jump optimization
  • i386 jump, call, return
  • i386 jump/call operands
  • i386 memory references
  • i386 mul, imul instructions
  • i386 opcode naming
  • i386 opcode prefixes
  • i386 options (none)
  • i386 register operands
  • i386 registers
  • i386 sections
  • i386 size suffixes
  • i386 source, destination operands
  • i386 support
  • i386 syntax compatibility
  • i80306 support
  • i960 architecture options
  • i960 branch recording
  • i960 callj pseudo-opcode
  • i960 compare and jump expansions
  • i960 compare/branch instructions
  • i960 floating point (IEEE)
  • i960 machine directives
  • i960 opcodes
  • i960 options
  • i960 support
  • ident directive
  • identifiers, AMD 29K
  • identifiers, ARM
  • if directive
  • ifdef directive
  • ifndef directive
  • ifnotdef directive
  • immediate character, M680x0
  • immediate character, VAX
  • immediate operands, i386
  • imul instruction, i386
  • include directive
  • include directive search path
  • indirect character, VAX
  • infix operators
  • inhibiting interrupts, i386
  • input
  • input file linenumbers
  • instruction set, M680x0
  • instruction summary, D10V
  • instruction summary, H8/300
  • instruction summary, H8/500
  • instruction summary, SH
  • instruction summary, Z8000
  • instructions and directives
  • int directive
  • int directive, H8/300
  • int directive, H8/500
  • int directive, i386
  • integer expressions
  • integer, 16-byte
  • integer, 8-byte
  • integers
  • integers, 16-bit
  • integers, 32-bit
  • integers, binary
  • integers, decimal
  • integers, hexadecimal
  • integers, octal
  • integers, one byte
  • internal assembler sections
  • invalid input
  • invocation summary
  • irp directive
  • irpc directive

    • j

  • joining text and data sections
  • jump instructions, i386
  • jump optimization, i386
  • jump/call operands, i386

    • l

  • label (:)
  • labels
  • lcomm directive
  • ld
  • ldouble directive M680x0
  • leafproc directive, i960
  • length of symbols
  • lflags directive (ignored)
  • line comment character
  • line comment character, AMD 29K
  • line comment character, ARM
  • line comment character, D10V
  • line comment character, H8/300
  • line comment character, H8/500
  • line comment character, M680x0
  • line comment character, SH
  • line comment character, V850
  • line comment character, Z8000
  • line directive
  • line directive, AMD 29K
  • line numbers, in input files
  • line numbers, in warnings/errors
  • line separator character
  • line separator, H8/300
  • line separator, H8/500
  • line separator, SH
  • line separator, Z8000
  • lines starting with #
  • linker
  • linker, and assembler
  • linkonce directive
  • list directive
  • listing control, turning off
  • listing control, turning on
  • listing control: new page
  • listing control: paper size
  • listing control: subtitle
  • listing control: title line
  • listings, enabling
  • little endian output, ARC
  • little endian output, MIPS
  • little-endian output, ARC
  • little-endian output, MIPS
  • ln directive
  • lo pseudo-op, V850
  • local common symbols
  • local labels, retaining in output
  • local symbol names
  • location counter
  • location counter, advancing
  • logical file name, logical file name
  • logical line number
  • logical line numbers
  • long directive
  • long directive, i386
  • lp register, V850
  • lval

    • m

  • M680x0 addressing modes
  • M680x0 architecture options
  • M680x0 branch improvement
  • M680x0 directives
  • M680x0 floating point
  • M680x0 immediate character
  • M680x0 line comment character
  • M680x0 opcodes
  • M680x0 options
  • M680x0 pseudo-opcodes
  • M680x0 size modifiers
  • M680x0 support
  • M680x0 syntax
  • machine dependencies
  • machine directives, AMD 29K
  • machine directives, ARC
  • machine directives, ARM
  • machine directives, H8/300 (none)
  • machine directives, H8/500 (none)
  • machine directives, i960
  • machine directives, SH
  • machine directives, SPARC
  • machine directives, V850
  • machine directives, VAX
  • machine independent directives
  • machine instructions (not covered)
  • machine-independent syntax
  • macro directive
  • macros
  • Macros, AMD 29K
  • macros, count executed
  • make rules
  • manual, structure and purpose
  • memory references, i386
  • merging text and data sections
  • messages from assembler
  • minus, permitted arguments
  • MIPS architecture options
  • MIPS big-endian output
  • MIPS debugging directives
  • MIPS ECOFF sections
  • MIPS endianness
  • MIPS ISA
  • MIPS ISA override
  • MIPS little-endian output
  • MIPS option stack
  • MIPS processor
  • MIT
  • mnemonics for opcodes, VAX
  • mnemonics, D10V
  • mnemonics, H8/300
  • mnemonics, H8/500
  • mnemonics, SH
  • mnemonics, Z8000
  • Motorola syntax for the 680x0
  • MRI compatibility mode
  • mri directive
  • MRI mode, temporarily
  • mul instruction, i386
  • multi-line statements

    • n

  • name
  • named section
  • named sections
  • names, symbol
  • naming object file
  • new page, in listings
  • newline (\n)
  • newline, required at file end
  • nolist directive
  • null-terminated strings
  • number constants
  • number of macros executed
  • numbered subsections
  • numbers, 16-bit
  • numeric values

    • o

  • object file
  • object file format
  • object file name
  • object file, after errors
  • obsolescent directives
  • octa directive
  • octal character code (\ddd)
  • octal integers
  • offset directive, V850
  • opcode mnemonics, VAX
  • opcode naming, i386
  • opcode prefixes, i386
  • opcode suffixes, i386
  • opcode summary, D10V
  • opcode summary, H8/300
  • opcode summary, H8/500
  • opcode summary, SH
  • opcode summary, Z8000
  • opcodes for AMD 29K
  • opcodes for ARM
  • opcodes for V850
  • opcodes, i960
  • opcodes, M680x0
  • operand delimiters, i386
  • operand notation, VAX
  • operands in expressions
  • operator precedence
  • operators, in expressions
  • operators, permitted arguments
  • optimization, D10V
  • option summary
  • options for AMD29K (none)
  • options for ARC
  • options for ARM (none)
  • options for i386 (none)
  • options for SPARC
  • options for V850 (none)
  • options for VAX/VMS
  • options, all versions of assembler
  • options, command line
  • options, D10V
  • options, H8/300 (none)
  • options, H8/500 (none)
  • options, i960
  • options, M680x0
  • options, SH (none)
  • options, Z8000
  • org directive
  • other attribute, of a.out symbol
  • output file

    • p

  • p2align directive
  • p2alignl directive
  • p2alignw directive
  • padding the location counter
  • padding the location counter given a power of two
  • padding the location counter given number of bytes
  • page, in listings
  • paper size, for listings
  • paths for .include
  • patterns, writing in memory
  • plus, permitted arguments
  • precedence of operators
  • precision, floating point
  • prefix operators
  • prefixes, i386
  • preprocessing
  • preprocessing, turning on and off
  • primary attributes, COFF symbols
  • proc directive, SPARC
  • protected registers, AMD 29K
  • pseudo-opcodes, M680x0
  • pseudo-ops for branch, VAX
  • pseudo-ops, machine independent
  • psize directive
  • psw register, V850
  • purpose of GNU assembler

    • q

  • quad directive
  • quad directive, i386

    • r

  • real-mode code, i386
  • register names, AMD 29K
  • register names, ARM
  • register names, H8/300
  • register names, V850
  • register names, VAX
  • register operands, i386
  • registers, D10V
  • registers, H8/500
  • registers, i386
  • registers, SH
  • registers, Z8000
  • relocation
  • relocation example
  • repeat prefixes, i386
  • reporting bugs in assembler
  • rept directive
  • reserve directive, SPARC
  • return instructions, i386
  • rsect

    • s

  • sbttl directive
  • scl directive
  • sdaoff pseudo-op, V850
  • search path for .include
  • sect directive, AMD 29K
  • section directive
  • section directive, V850
  • section override prefixes, i386
  • section-relative addressing
  • sections
  • sections in messages, internal
  • sections, i386
  • sections, named
  • seg directive, SPARC
  • segm
  • set directive
  • SH addressing modes
  • SH floating point (IEEE)
  • SH line comment character
  • SH line separator
  • SH machine directives
  • SH opcode summary
  • SH options (none)
  • SH registers
  • SH support
  • short directive
  • single character constant
  • single directive
  • single directive, i386
  • sixteen bit integers
  • sixteen byte integer
  • size directive
  • size modifiers, D10V
  • size modifiers, M680x0
  • size prefixes, i386
  • size suffixes, H8/300
  • sizes operands, i386
  • skip directive
  • skip directive, M680x0
  • skip directive, SPARC
  • sleb128 directive
  • small objects, MIPS ECOFF
  • SOM symbol attributes
  • source program
  • source, destination operands; i386
  • sp register, V850
  • space directive
  • space used, maximum for assembly
  • SPARC architectures
  • SPARC data alignment
  • SPARC floating point (IEEE)
  • SPARC machine directives
  • SPARC options
  • SPARC support
  • special characters, M680x0
  • special purpose registers, AMD 29K
  • stabd directive
  • stabn directive
  • stabs directive
  • stabx directives
  • standard assembler sections
  • standard input, as input file
  • statement on multiple lines
  • statement separator character
  • statement separator, H8/300
  • statement separator, H8/500
  • statement separator, SH
  • statement separator, Z8000
  • statements, structure of
  • statistics, about assembly
  • stopping the assembly
  • string constants
  • string directive
  • string directive on HPPA
  • string literals
  • string, copying to object file
  • structure debugging, COFF
  • sub-instruction ordering, D10V
  • sub-instructions, D10V
  • subexpressions
  • subtitles for listings
  • subtraction, permitted arguments
  • summary of options
  • support
  • supporting files, including
  • suppressing warnings
  • sval
  • symbol attributes
  • symbol attributes, a.out
  • symbol attributes, COFF
  • symbol attributes, SOM
  • symbol descriptor, COFF
  • symbol names
  • symbol names, `$' in, symbol names, `$' in, symbol names, `$' in
  • symbol names, local
  • symbol names, temporary
  • symbol storage class (COFF)
  • symbol type
  • symbol type, COFF
  • symbol value
  • symbol value, setting
  • symbol values, assigning
  • symbol versioning
  • symbol, common
  • symbol, making visible to linker
  • symbolic debuggers, information for
  • symbols
  • symbols with lowercase, VAX/VMS
  • symbols, assigning values to
  • symbols, local common
  • symver directive
  • syntax compatibility, i386
  • syntax, D10V
  • syntax, M680x0
  • syntax, machine-independent
  • sysproc directive, i960

    • t

  • tab (\t)
  • tag directive
  • tdaoff pseudo-op, V850
  • temporary symbol names
  • text and data sections, joining
  • text directive
  • text section
  • tfloat directive, i386
  • thumb directive, ARM
  • Thumb support
  • thumb_func directive, ARM
  • time, total for assembly
  • title directive
  • tp register, V850
  • trusted compiler
  • turning preprocessing on and off
  • type directive
  • type of a symbol

    • u

  • ualong directive, SH
  • uaword directive, SH
  • uleb128 directive
  • undefined section
  • unsegm
  • use directive, AMD 29K

    • v

  • V850 command line options
  • V850 floating point (IEEE)
  • V850 line comment character
  • V850 machine directives
  • V850 opcodes
  • V850 options (none)
  • V850 register names
  • V850 support
  • val directive
  • value attribute, COFF
  • value of a symbol
  • VAX bitfields not supported
  • VAX branch improvement
  • VAX command-line options ignored
  • VAX displacement sizing character
  • VAX floating point
  • VAX immediate character
  • VAX indirect character
  • VAX machine directives
  • VAX opcode mnemonics
  • VAX operand notation
  • VAX register names
  • VAX support
  • Vax-11 C compatibility
  • VAX/VMS options
  • version of assembler
  • versions of symbols
  • VMS (VAX) options

    • w

  • warning for altered difference tables
  • warning messages
  • warnings, suppressing
  • whitespace
  • whitespace, removed by preprocessor
  • wide floating point directives, VAX
  • word directive
  • word directive, H8/300
  • word directive, H8/500
  • word directive, i386
  • word directive, SPARC
  • writing patterns in memory
  • wval

    • x

  • xword directive, SPARC

    • z

  • Z800 addressing modes
  • Z8000 directives
  • Z8000 line comment character
  • Z8000 line separator
  • Z8000 opcode summary
  • Z8000 options
  • Z8000 registers
  • Z8000 support
  • zdaoff pseudo-op, V850
  • zero register, V850
  • zero-terminated strings

    • Footnotes

    (1)

    Any more details?

    This document was generated on 24 April 1999 using the texi2html translator version 1.52.


Autoconf

This file documents the GNU Autoconf package for creating scripts to configure source code packages using templates and the GNU M4 macro package. This is edition 2.52, for Autoconf version 2.52.

1. Introduction | Autoconf's purpose, strengths, and weaknesses
2. The GNU build system | A set of tools for portable software packages
3. Making configure Scripts | How to organize and produce Autoconf scripts
4. Initialization and Output Files | Initialization and output
5. Existing Tests | Macros that check for particular features
6. Writing Tests | How to write new feature checks
7. Results of Tests | What to do with results from feature checks
8. Programming in M4 | Layers on top of which Autoconf is written
9. Writing Autoconf Macros | Adding new macros to Autoconf
10. Portable Shell Programming | Shell script portability pitfalls
11. Manual Configuration | Selecting features that can't be guessed
12. Site Configuration | Local defaults for configure
13. Running configure Scripts | How to use the Autoconf output
14. Recreating a Configuration | Recreating a configuration
15. Obsolete Constructs | Kept for backward compatibility
16. Questions About Autoconf | Questions about Autoconf, with answers
17. History of Autoconf
Environment Variable Index | Index of environment variables used
Output Variable Index | Index of variables set in output files
Preprocessor Symbol Index | Index of C preprocessor symbols defined
Autoconf Macro Index | Index of Autoconf macros
M4 Macro Index | Index of M4, M4sugar, and M4sh macros
Concept Index | General index

The GNU build system

2.1 Automake | Escaping Makefile hell
2.2 Libtool | Building libraries portably
2.3 Pointers | More info on the GNU build system

Making configure Scripts

3.1 Writing `configure.ac' | What to put in an Autoconf input file
3.2 Using autoscan to Create `configure.ac' | Semi-automatic `configure.ac' writing
3.3 Using ifnames to List Conditionals | Listing the conditionals in source code
3.4 Using autoconf to Create configure | How to create configuration scripts
3.5 Using autoreconf to Update configure Scripts | Remaking multiple configure scripts

Writing `configure.ac'

3.1.1 A Shell Script Compiler | Autoconf as solution of a problem
3.1.2 The Autoconf Language | Programming in Autoconf
3.1.3 Standard `configure.ac' Layout | Standard organization of configure.ac

Initialization and Output Files

4.1 Notices in configure | Copyright, version numbers in configure
4.2 Finding configure Input | Where Autoconf should find files
4.3 Outputting Files | Outputting results from the configuration
4.4 Taking Configuration Actions | Preparing the output based on results
4.5 Creating Configuration Files | Creating output files
4.6 Substitutions in Makefiles | Using output variables in `Makefile's
4.7 Configuration Header Files | Creating a configuration header file
4.8 Running Arbitrary Configuration Commands | Running arbitrary instantiation commands
4.9 Creating Configuration Links | Links depending from the configuration
4.10 Configuring Other Packages in Subdirectories | Configuring independent packages together
4.11 Default Prefix | Changing the default installation prefix

Substitutions in Makefiles

4.6.1 Preset Output Variables | Output variables that are always set
4.6.2 Installation Directory Variables | Other preset output variables
4.6.3 Build Directories | Supporting multiple concurrent compiles
4.6.4 Automatic Remaking | Makefile rules for configuring

Configuration Header Files

4.7.1 Configuration Header Templates | Input for the configuration headers
4.7.2 Using autoheader to Create `config.h.in' | How to create configuration templates
4.7.3 Autoheader Macros | How to specify CPP templates

Existing Tests

5.1 Common Behavior | Macros' standard schemes
5.2 Alternative Programs | Selecting between alternative programs
5.3 Files | Checking for the existence of files
5.4 Library Files | Library archives that might be missing
5.5 Library Functions | C library functions that might be missing
5.6 Header Files | Header files that might be missing
5.7 Declarations | Declarations that may be missing
5.8 Structures | Structures or members that might be missing
5.9 Types | Types that might be missing
5.10 Compilers and Preprocessors | Checking for compiling programs
5.11 System Services | Operating system services
5.12 UNIX Variants | Special kludges for specific UNIX variants

Common Behavior

5.1.1 Standard Symbols | Symbols defined by the macros
5.1.2 Default Includes | Includes used by the generic macros

Alternative Programs

5.2.1 Particular Program Checks | Special handling to find certain programs
5.2.2 Generic Program and File Checks | How to find other programs

Library Functions

5.5.1 Portability of Classical Functions | Pitfalls with usual functions
5.5.2 Particular Function Checks | Special handling to find certain functions
5.5.3 Generic Function Checks | How to find other functions

Header Files

5.6.1 Particular Header Checks | Special handling to find certain headers
5.6.2 Generic Header Checks | How to find other headers

Declarations

5.7.1 Particular Declaration Checks | Macros to check for certain declarations
5.7.2 Generic Declaration Checks | How to find other declarations

Structures

5.8.1 Particular Structure Checks | Macros to check for certain structure members
5.8.2 Generic Structure Checks | How to find other structure members

Types

5.9.1 Particular Type Checks | Special handling to find certain types
5.9.2 Generic Type Checks | How to find other types

Compilers and Preprocessors

5.10.1 Generic Compiler Characteristics | Language independent tests
5.10.2 C Compiler Characteristics | Checking its characteristics
5.10.3 C++ Compiler Characteristics | Likewise
5.10.4 Fortran 77 Compiler Characteristics | Likewise

Writing Tests

6.1 Examining Declarations | Detecting header files and declarations
6.2 Examining Syntax | Detecting language syntax features
6.3 Examining Libraries | Detecting functions and global variables
6.4 Checking Run Time Behavior | Testing for run-time features
6.5 Systemology | A zoology of operating systems
6.6 Multiple Cases | Tests for several possible values
6.7 Language Choice | Selecting which language to use for testing

Checking Run Time Behavior

6.4.1 Running Test Programs | Running test programs
6.4.2 Guidelines for Test Programs | General rules for writing test programs
6.4.3 Test Functions | Avoiding pitfalls in test programs

Results of Tests

7.1 Defining C Preprocessor Symbols | Defining C preprocessor symbols
7.2 Setting Output Variables | Replacing variables in output files
7.3 Caching Results | Speeding up subsequent configure runs
7.4 Printing Messages | Notifying configure users

Caching Results

7.3.1 Cache Variable Names | Shell variables used in caches
7.3.2 Cache Files | Files configure uses for caching
7.3.3 Cache Checkpointing | Loading and saving the cache file

Programming in M4

8.1 M4 Quotation | Protecting macros from unwanted expansion
8.2 Programming in M4sugar | Convenient pure M4 macros

M4 Quotation

8.1.1 Active Characters | Characters that change the behavior of m4
8.1.2 One Macro Call | Quotation and one macro call
8.1.3 Quotation and Nested Macros | Macros calling macros
8.1.4 Quadrigraphs | Another way to escape special characters
8.1.5 Quotation Rule Of Thumb | One parenthesis, one quote

Programming in M4sugar

8.2.1 Redefined M4 Macros | M4 builtins changed in M4sugar
8.2.2 Forbidden Patterns | Catching unexpanded macros

Writing Autoconf Macros

9.1 Macro Definitions | Basic format of an Autoconf macro
9.2 Macro Names | What to call your new macros
9.3 Reporting Messages | Notifying autoconf users
9.4 Dependencies Between Macros | What to do when macros depend on other macros
9.5 Obsoleting Macros | Warning about old ways of doing things
9.6 Coding Style | Writing Autoconf macros à la Autoconf

Dependencies Between Macros

9.4.1 Prerequisite Macros | Ensuring required information
9.4.2 Suggested Ordering | Warning about possible ordering problems

Portable Shell Programming

10.1 Shellology | A zoology of shells
10.2 Here-Documents | Quirks and tricks
10.3 File Descriptors | FDs and redirections
10.4 File System Conventions | File- and pathnames
10.5 Shell Substitutions | Variable and command expansions
10.6 Assignments | Varying side effects of assignments
10.7 Special Shell Variables | Variables you should not change
10.8 Limitations of Shell Builtins | Portable use of not so portable /bin/sh
10.9 Limitations of Usual Tools | Portable use of portable tools
10.10 Limitations of Make | Portable Makefiles

Manual Configuration

11.1 Specifying the System Type | Specifying the system type
11.2 Getting the Canonical System Type | Getting the canonical system type
11.3 Using the System Type | What to do with the system type

Site Configuration

12.1 Working With External Software | Working with other optional software
12.2 Choosing Package Options | Selecting optional features
12.3 Making Your Help Strings Look Pretty | Formating help string
12.4 Configuring Site Details | Configuring site details
12.5 Transforming Program Names When Installing | Changing program names when installing
12.6 Setting Site Defaults | Giving configure local defaults

Transforming Program Names When Installing

12.5.1 Transformation Options | configure options to transform names
12.5.2 Transformation Examples | Sample uses of transforming names
12.5.3 Transformation Rules | `Makefile' uses of transforming names

Running configure Scripts

13.1 Basic Installation | Instructions for typical cases
13.2 Compilers and Options | Selecting compilers and optimization
13.3 Compiling For Multiple Architectures | Compiling for multiple architectures at once
13.4 Installation Names | Installing in different directories
13.5 Optional Features | Selecting optional features
13.6 Specifying the System Type | Specifying the system type
13.7 Sharing Defaults | Setting site-wide defaults for configure
13.8 Environment Variables | Defining environment variables.
13.9 configure Invocation | Changing how configure runs

Obsolete Constructs

15.1 Obsolete `config.status' Invocation | Different calling convention
15.2 `acconfig.h' | Additional entries in `config.h.in'
15.3 Using autoupdate to Modernize `configure.ac' | Automatic update of `configure.ac'
15.4 Obsolete Macros | Backward compatibility macros
15.5 Upgrading From Version 1 | Tips for upgrading your files
15.6 Upgrading From Version 2.13 | Some fresher tips

Upgrading From Version 1

15.5.1 Changed File Names | Files you might rename
15.5.2 Changed Makefiles | New things to put in `Makefile.in'
15.5.3 Changed Macros | Macro calls you might replace
15.5.4 Changed Results | Changes in how to check test results
15.5.5 Changed Macro Writing | Better ways to write your own macros

Upgrading From Version 2.13

15.6.1 Changed Quotation | Broken code which used to work
15.6.2 New Macros | Interaction with foreign macros

Questions About Autoconf

16.1 Distributing configure Scripts | Distributing configure scripts
16.2 Why Require GNU M4? | Why not use the standard M4?
16.3 How Can I Bootstrap? | Autoconf and GNU M4 require each other?
16.4 Why Not Imake? | Why GNU uses configure instead of Imake

History of Autoconf

17.1 Genesis | Prehistory and naming of configure
17.2 Exodus | The plagues of M4 and Perl
17.3 Leviticus | The priestly code of portability arrives
17.4 Numbers | Growth and contributors
17.5 Deuteronomy | Approaching the promises of easy configuration

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Introduction

A physicist, an engineer, and a computer scientist were discussing the
nature of God.  ``Surely a Physicist,'' said the physicist, ``because
early in the Creation, God made Light; and you know, Maxwell's
equations, the dual nature of electromagnetic waves, the relativistic
consequences...'' ``An Engineer!,'' said the engineer, ``because
before making Light, God split the Chaos into Land and Water; it takes a
hell of an engineer to handle that big amount of mud, and orderly
separation of solids from liquids...'' The computer scientist
shouted: ``And the Chaos, where do you think it was coming from, hmm?''

---Anonymous

Autoconf is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of UNIX-like systems. The configuration scripts produced by Autoconf are independent of Autoconf when they are run, so their users do not need to have Autoconf.

The configuration scripts produced by Autoconf require no manual user intervention when run; they do not normally even need an argument specifying the system type. Instead, they individually test for the presence of each feature that the software package they are for might need. (Before each check, they print a one-line message stating what they are checking for, so the user doesn't get too bored while waiting for the script to finish.) As a result, they deal well with systems that are hybrids or customized from the more common UNIX variants. There is no need to maintain files that list the features supported by each release of each variant of UNIX.

For each software package that Autoconf is used with, it creates a configuration script from a template file that lists the system features that the package needs or can use. After the shell code to recognize and respond to a system feature has been written, Autoconf allows it to be shared by many software packages that can use (or need) that feature. If it later turns out that the shell code needs adjustment for some reason, it needs to be changed in only one place; all of the configuration scripts can be regenerated automatically to take advantage of the updated code.

The Metaconfig package is similar in purpose to Autoconf, but the scripts it produces require manual user intervention, which is quite inconvenient when configuring large source trees. Unlike Metaconfig scripts, Autoconf scripts can support cross-compiling, if some care is taken in writing them.

Autoconf does not solve all problems related to making portable software packages--for a more complete solution, it should be used in concert with other GNU build tools like Automake and Libtool. These other tools take on jobs like the creation of a portable, recursive `Makefile' with all of the standard targets, linking of shared libraries, and so on. See section 2. The GNU build system, for more information.

Autoconf imposes some restrictions on the names of macros used with #if in C programs (see section Preprocessor Symbol Index).

Autoconf requires GNU M4 in order to generate the scripts. It uses features that some UNIX versions of M4, including GNU M4 1.3, do not have. You must use version 1.4 or later of GNU M4.

See section 15.5 Upgrading From Version 1, for information about upgrading from version 1. See section 17. History of Autoconf, for the story of Autoconf's development. See section 16. Questions About Autoconf, for answers to some common questions about Autoconf.

See the \title\{http://www.gnu.org/software/autoconf/autoconf.html, Autoconf web page} for up-to-date information, details on the mailing lists, pointers to a list of known bugs, etc.

Mail suggestions to the Autoconf mailing list.

Bug reports should be preferably submitted to the \title\{http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf, Autoconf Gnats database}, or sent to the Autoconf Bugs mailing list. If possible, first check that your bug is not already solved in current development versions, and that it has not been reported yet. Be sure to include all the needed information and a short `configure.ac' that demonstrates the problem.

Autoconf's development tree is accessible via CVS; see the Autoconf web page for details. There is also a CVSweb interface to the Autoconf development tree. Patches relative to the current CVS version can be sent for review to the Autoconf Patches mailing list.

Because of its mission, Autoconf includes only a set of often-used macros that have already demonstrated their usefulness. Nevertheless, if you wish to share your macros, or find existing ones, see the \title\{http://www.gnu.org/software/ac-archive/, Autoconf Macro Archive}, which is kindly run by Peter Simons.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. The GNU build system

Autoconf solves an important problem--reliable discovery of system-specific build and runtime information--but this is only one piece of the puzzle for the development of portable software. To this end, the GNU project has developed a suite of integrated utilities to finish the job Autoconf started: the GNU build system, whose most important components are Autoconf, Automake, and Libtool. In this chapter, we introduce you to those tools, point you to sources of more information, and try to convince you to use the entire GNU build system for your software.

2.1 Automake | Escaping Makefile hell
2.2 Libtool | Building libraries portably
2.3 Pointers | More info on the GNU build system

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 Automake

The ubiquity of make means that a Makefile is almost the only viable way to distribute automatic build rules for software, but one quickly runs into make's numerous limitations. Its lack of support for automatic dependency tracking, recursive builds in subdirectories, reliable timestamps (e.g. for network filesystems), and so on, mean that developers must painfully (and often incorrectly) reinvent the wheel for each project. Portability is non-trivial, thanks to the quirks of make on many systems. On top of all this is the manual labor required to implement the many standard targets that users have come to expect (make install, make distclean, make uninstall, etc.). Since you are, of course, using Autoconf, you also have to insert repetitive code in your Makefile.in to recognize @CC@, @CFLAGS@, and other substitutions provided by configure. Into this mess steps Automake.

Automake allows you to specify your build needs in a Makefile.am file with a vastly simpler and more powerful syntax than that of a plain Makefile, and then generates a portable Makefile.in for use with Autoconf. For example, the Makefile.am to build and install a simple "Hello world" program might look like:

bin_PROGRAMS = hello
hello_SOURCES = hello.c

The resulting Makefile.in (~400 lines) automatically supports all the standard targets, the substitutions provided by Autoconf, automatic dependency tracking, VPATH building, and so on. make will build the hello program, and make install will install it in `/usr/local/bin' (or whatever prefix was given to configure, if not `/usr/local').

Automake may require that additional tools be present on the developer's machine. For example, the Makefile.in that the developer works with may not be portable (e.g. it might use special features of your compiler to automatically generate dependency information). Running make dist, however, produces a `hello-1.0.tar.gz' package (or whatever the program/version is) with a Makefile.in that will work on any system.

The benefits of Automake increase for larger packages (especially ones with subdirectories), but even for small programs the added convenience and portability can be substantial. And that's not all...

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 Libtool

Very often, one wants to build not only programs, but libraries, so that other programs can benefit from the fruits of your labor. Ideally, one would like to produce shared (dynamically-linked) libraries, which can be used by multiple programs without duplication on disk or in memory and can be updated independently of the linked programs. Producing shared libraries portably, however, is the stuff of nightmares--each system has its own incompatible tools, compiler flags, and magic incantations. Fortunately, GNU provides a solution: Libtool.

Libtool handles all the requirements of building shared libraries for you, and at this time seems to be the only way to do so with any portability. It also handles many other headaches, such as: the interaction of Makefile rules with the variable suffixes of shared libraries, linking reliably to shared libraries before they are installed by the superuser, and supplying a consistent versioning system (so that different versions of a library can be installed or upgraded without breaking binary compatibility). Although Libtool, like Autoconf, can be used on its own, it is most simply utilized in conjunction with Automake--there, Libtool is used automatically whenever shared libraries are needed, and you need not know its syntax.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.3 Pointers

Developers who are used to the simplicity of make for small projects on a single system might be daunted at the prospect of learning to use Automake and Autoconf. As your software is distributed to more and more users, however, you will otherwise quickly find yourself putting lots of effort into reinventing the services that the GNU build tools provide, and making the same mistakes that they once made and overcame. (Besides, since you're already learning Autoconf, Automake will be a piece of cake.)

There are a number of places that you can go to for more information on the GNU build tools.

  • Web

    The home pages for Autoconf, Automake, and Libtool.

  • Automake Manual

    See section `Automake' in GNU Automake, for more information on Automake.

  • Books

    The book GNU Autoconf, Automake and Libtool (1) describes the complete GNU build environment. You can also find the entire book on-line at \title\{http://sources.redhat.com/autobook/,"The Goat Book" home page}.

  • Tutorials and Examples

    The Autoconf Developer Page maintains links to a number of Autoconf/Automake tutorials online, and also links to the \title\{http://www.gnu.org/software/ac-archive/, Autoconf Macro Archive}.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. Making configure Scripts

The configuration scripts that Autoconf produces are by convention called configure. When run, configure creates several files, replacing configuration parameters in them with appropriate values. The files that configure creates are:

  • one or more `Makefile' files, one in each subdirectory of the package (see section 4.6 Substitutions in Makefiles);

  • optionally, a C header file, the name of which is configurable, containing #define directives (see section 4.7 Configuration Header Files);

  • a shell script called `config.status' that, when run, will recreate the files listed above (see section 14. Recreating a Configuration);

  • an optional shell script normally called `config.cache' (created when using `configure --config-cache') that saves the results of running many of the tests (see section 7.3.2 Cache Files);

  • a file called `config.log' containing any messages produced by compilers, to help debugging if configure makes a mistake.

To create a configure script with Autoconf, you need to write an Autoconf input file `configure.ac' (or `configure.in') and run autoconf on it. If you write your own feature tests to supplement those that come with Autoconf, you might also write files called `aclocal.m4' and `acsite.m4'. If you use a C header file to contain #define directives, you might also run autoheader, and you will distribute the generated file `config.h.in' with the package.

Here is a diagram showing how the files that can be used in configuration are produced. Programs that are executed are suffixed by `*'. Optional files are enclosed in square brackets (`[]'). autoconf and autoheader also read the installed Autoconf macro files (by reading `autoconf.m4').

Files used in preparing a software package for distribution:
your source files --> [autoscan*] --> [configure.scan] --> configure.ac

configure.ac --.
               |   .------> autoconf* -----> configure
[aclocal.m4] --+---+
               |   `-----> [autoheader*] --> [config.h.in]
[acsite.m4] ---'

Makefile.in -------------------------------> Makefile.in

Files used in configuring a software package:
                       .-------------> [config.cache]
configure* ------------+-------------> config.log
                       |
[config.h.in] -.       v            .-> [config.h] -.
               +--> config.status* -+               +--> make*
Makefile.in ---'                    `-> Makefile ---'

3.1 Writing `configure.ac' | What to put in an Autoconf input file
3.2 Using autoscan to Create `configure.ac' | Semi-automatic `configure.ac' writing
3.3 Using ifnames to List Conditionals | Listing the conditionals in source code
3.4 Using autoconf to Create configure | How to create configuration scripts
3.5 Using autoreconf to Update configure Scripts | Remaking multiple configure scripts

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 Writing `configure.ac'

To produce a configure script for a software package, create a file called `configure.ac' that contains invocations of the Autoconf macros that test the system features your package needs or can use. Autoconf macros already exist to check for many features; see 5. Existing Tests, for their descriptions. For most other features, you can use Autoconf template macros to produce custom checks; see 6. Writing Tests, for information about them. For especially tricky or specialized features, `configure.ac' might need to contain some hand-crafted shell commands; see 10. Portable Shell Programming. The autoscan program can give you a good start in writing `configure.ac' (see section 3.2 Using autoscan to Create `configure.ac', for more information).

Previous versions of Autoconf promoted the name `configure.in', which is somewhat ambiguous (the tool needed to produce this file is not described by its extension), and introduces a slight confusion with `config.h.in' and so on (for which `.in' means "to be processed by configure"). Using `configure.ac' is now preferred.

3.1.1 A Shell Script Compiler | Autoconf as solution of a problem
3.1.2 The Autoconf Language | Programming in Autoconf
3.1.3 Standard `configure.ac' Layout | Standard organization of configure.ac

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.1 A Shell Script Compiler

Just as for any other computer language, in order to properly program `configure.ac' in Autoconf you must understand what problem the language tries to address and how it does so.

The problem Autoconf addresses is that the world is a mess. After all, you are using Autoconf in order to have your package compile easily on all sorts of different systems, some of them being extremely hostile. Autoconf itself bears the price for these differences: configure must run on all those systems, and thus configure must limit itself to their lowest common denominator of features.

Naturally, you might then think of shell scripts; who needs autoconf? A set of properly written shell functions is enough to make it easy to write configure scripts by hand. Sigh! Unfortunately, shell functions do not belong to the least common denominator; therefore, where you would like to define a function and use it ten times, you would instead need to copy its body ten times.

So, what is really needed is some kind of compiler, autoconf, that takes an Autoconf program, `configure.ac', and transforms it into a portable shell script, configure.

How does autoconf perform this task?

There are two obvious possibilities: creating a brand new language or extending an existing one. The former option is very attractive: all sorts of optimizations could easily be implemented in the compiler and many rigorous checks could be performed on the Autoconf program (e.g. rejecting any non-portable construct). Alternatively, you can extend an existing language, such as the sh (Bourne shell) language.

Autoconf does the latter: it is a layer on top of sh. It was therefore most convenient to implement autoconf as a macro expander: a program that repeatedly performs macro expansions on text input, replacing macro calls with macro bodies and producing a pure sh script in the end. Instead of implementing a dedicated Autoconf macro expander, it is natural to use an existing general-purpose macro language, such as M4, and implement the extensions as a set of M4 macros.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2 The Autoconf Language

The Autoconf language is very different from many other computer languages because it treats actual code the same as plain text. Whereas in C, for instance, data and instructions have very different syntactic status, in Autoconf their status is rigorously the same. Therefore, we need a means to distinguish literal strings from text to be expanded: quotation.

When calling macros that take arguments, there must not be any blank space between the macro name and the open parenthesis. Arguments should be enclosed within the M4 quote characters `[' and `]', and be separated by commas. Any leading spaces in arguments are ignored, unless they are quoted. You may safely leave out the quotes when the argument is simple text, but always quote complex arguments such as other macro calls. This rule applies recursively for every macro call, including macros called from other macros.

For instance:

AC_CHECK_HEADER([stdio.h],
                [AC_DEFINE([HAVE_STDIO_H])],
                [AC_MSG_ERROR([Sorry, can't do anything for you])])

is quoted properly. You may safely simplify its quotation to:

AC_CHECK_HEADER(stdio.h,
                [AC_DEFINE(HAVE_STDIO_H)],
                [AC_MSG_ERROR([Sorry, can't do anything for you])])

Notice that the argument of AC_MSG_ERROR is still quoted; otherwise, its comma would have been interpreted as an argument separator.

The following example is wrong and dangerous, as it is underquoted:

AC_CHECK_HEADER(stdio.h,
                AC_DEFINE(HAVE_STDIO_H),
                AC_MSG_ERROR([Sorry, can't do anything for you]))

In other cases, you may have to use text that also resembles a macro call. You must quote that text even when it is not passed as a macro argument:

echo "Hard rock was here!  --[AC_DC]"

which will result in

echo "Hard rock was here!  --AC_DC"

When you use the same text in a macro argument, you must therefore have an extra quotation level (since one is stripped away by the macro substitution). In general, then, it is a good idea to use double quoting for all literal string arguments:

AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])

You are now able to understand one of the constructs of Autoconf that has been continually misunderstood... The rule of thumb is that whenever you expect macro expansion, expect quote expansion; i.e., expect one level of quotes to be lost. For instance:

AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])

is incorrect: here, the first argument of AC_COMPILE_IFELSE is `char b[10];' and will be expanded once, which results in `char b10;'. (There was an idiom common in Autoconf's past to address this issue via the M4 changequote primitive, but do not use it!) Let's take a closer look: the author meant the first argument to be understood as a literal, and therefore it must be quoted twice:

AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])

Voilà, you actually produce `char b[10];' this time!

The careful reader will notice that, according to these guidelines, the "properly" quoted AC_CHECK_HEADER example above is actually lacking three pairs of quotes! Nevertheless, for the sake of readability, double quotation of literals is used only where needed in this manual.

Some macros take optional arguments, which this documentation represents as [arg] (not to be confused with the quote characters). You may just leave them empty, or use `[]' to make the emptiness of the argument explicit, or you may simply omit the trailing commas. The three lines below are equivalent:

AC_CHECK_HEADERS(stdio.h, [], [], [])
AC_CHECK_HEADERS(stdio.h,,,)
AC_CHECK_HEADERS(stdio.h)

It is best to put each macro call on its own line in `configure.ac'. Most of the macros don't add extra newlines; they rely on the newline after the macro call to terminate the commands. This approach makes the generated configure script a little easier to read by not inserting lots of blank lines. It is generally safe to set shell variables on the same line as a macro call, because the shell allows assignments without intervening newlines.

You can include comments in `configure.ac' files by starting them with the `#'. For example, it is helpful to begin `configure.ac' files with a line like this:

# Process this file with autoconf to produce a configure script.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.3 Standard `configure.ac' Layout

The order in which `configure.ac' calls the Autoconf macros is not important, with a few exceptions. Every `configure.ac' must contain a call to AC_INIT before the checks, and a call to AC_OUTPUT at the end (see section 4.3 Outputting Files). Additionally, some macros rely on other macros having been called first, because they check previously set values of some variables to decide what to do. These macros are noted in the individual descriptions (see section 5. Existing Tests), and they also warn you when configure is created if they are called out of order.

To encourage consistency, here is a suggested order for calling the Autoconf macros. Generally speaking, the things near the end of this list are those that could depend on things earlier in it. For example, library functions could be affected by types and libraries.

Autoconf requirements
AC_INIT(package, version, bug-report-address)
information on the package
checks for programs
checks for libraries
checks for header files
checks for types
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
AC_CONFIG_FILES([file...])
AC_OUTPUT

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 Using autoscan to Create `configure.ac'

The autoscan program can help you create and/or maintain a `configure.ac' file for a software package. autoscan examines source files in the directory tree rooted at a directory given as a command line argument, or the current directory if none is given. It searches the source files for common portability problems and creates a file `configure.scan' which is a preliminary `configure.ac' for that package, and checks a possibly existing `configure.ac' for completeness.

When using autoscan to create a `configure.ac', you should manually examine `configure.scan' before renaming it to `configure.ac'; it will probably need some adjustments. Occasionally, autoscan outputs a macro in the wrong order relative to another macro, so that autoconf produces a warning; you need to move such macros manually. Also, if you want the package to use a configuration header file, you must add a call to AC_CONFIG_HEADERS (see section 4.7 Configuration Header Files). You might also have to change or add some #if directives to your program in order to make it work with Autoconf (see section 3.3 Using ifnames to List Conditionals, for information about a program that can help with that job).

When using autoscan to maintain a `configure.ac', simply consider adding its suggestions. The file `autoscan.log' will contain detailed information on why a macro is requested.

autoscan uses several data files (installed along with Autoconf) to determine which macros to output when it finds particular symbols in a package's source files. These data files all have the same format: each line consists of a symbol, whitespace, and the Autoconf macro to output if that symbol is encountered. Lines starting with `#' are comments.

autoscan is only installed if you already have Perl installed. autoscan accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--verbose'
`-v'
Print the names of the files it examines and the potentially interesting symbols it finds in them. This output can be voluminous.

`--autoconf-dir=dir'
`-A dir'
Override the location where the installed Autoconf data files are looked for. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

This option is rarely needed and dangerous; it is only used when one plays with different versions of Autoconf simultaneously.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 Using ifnames to List Conditionals

ifnames can help you write `configure.ac' for a software package. It prints the identifiers that the package already uses in C preprocessor conditionals. If a package has already been set up to have some portability, ifnames can thus help you figure out what its configure needs to check for. It may help fill in some gaps in a `configure.ac' generated by autoscan (see section 3.2 Using autoscan to Create `configure.ac').

ifnames scans all of the C source files named on the command line (or the standard input, if none are given) and writes to the standard output a sorted list of all the identifiers that appear in those files in #if, #elif, #ifdef, or #ifndef directives. It prints each identifier on a line, followed by a space-separated list of the files in which that identifier occurs.

ifnames accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4 Using autoconf to Create configure

To create configure from `configure.ac', run the autoconf program with no arguments. autoconf processes `configure.ac' with the m4 macro processor, using the Autoconf macros. If you give autoconf an argument, it reads that file instead of `configure.ac' and writes the configuration script to the standard output instead of to configure. If you give autoconf the argument `-', it reads from the standard input instead of `configure.ac' and writes the configuration script to the standard output.

The Autoconf macros are defined in several files. Some of the files are distributed with Autoconf; autoconf reads them first. Then it looks for the optional file `acsite.m4' in the directory that contains the distributed Autoconf macro files, and for the optional file `aclocal.m4' in the current directory. Those files can contain your site's or the package's own Autoconf macro definitions (see section 9. Writing Autoconf Macros, for more information). If a macro is defined in more than one of the files that autoconf reads, the last definition it reads overrides the earlier ones.

autoconf accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--verbose'
`-v'
Report processing steps.

`--debug'
`-d'
Don't remove the temporary files.

`--autoconf-dir=dir'
`-A dir'
Override the location where the installed Autoconf data files are looked for. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

This option is rarely needed and dangerous; it is only used when one plays with different versions of Autoconf simultaneously.

`--localdir=dir'
`-l dir'
Look for the package file `aclocal.m4' in directory dir instead of in the current directory.

`--output=file'
`-o file'
Save output (script or trace) to file. The file `-' stands for the standard output.

`--warnings=category'
`-W category'
Report the warnings related to category (which can actually be a comma separated list). See section 9.3 Reporting Messages, macro AC_DIAGNOSE, for a comprehensive list of categories. Special values include:

`all'
report all the warnings

`none'
report none

`error'
treats warnings as errors

`no-category'
disable warnings falling into category

Warnings about `syntax' are enabled by default, and the environment variable WARNINGS, a comma separated list of categories, is honored. autoconf -W category will actually behave as if you had run:

autoconf --warnings=syntax,$WARNINGS,category

If you want to disable autoconf's defaults and WARNINGS, but (for example) enable the warnings about obsolete constructs, you would use `-W none,obsolete'.

autoconf displays a back trace for errors, but not for warnings; if you want them, just pass `-W error'. For instance, on this `configure.ac':

AC_DEFUN([INNER],
[AC_TRY_RUN([true])])

AC_DEFUN([OUTER],
[INNER])

AC_INIT
OUTER

you get:

$ autoconf -Wcross
configure.ac:8: warning: AC_TRY_RUN called without default \
to allow cross compiling
$ autoconf -Wcross,error
configure.ac:8: error: AC_TRY_RUN called without default \
to allow cross compiling
acgeneral.m4:3044: AC_TRY_RUN is expanded from...
configure.ac:2: INNER is expanded from...
configure.ac:5: OUTER is expanded from...
configure.ac:8: the top level

`--trace=macro[:format]'
`-t macro[:format]'
Do not create the configure script, but list the calls to macro according to the format. Multiple `--trace' arguments can be used to list several macros. Multiple `--trace' arguments for a single macro are not cumulative; instead, you should just make format as long as needed.

The format is a regular string, with newlines if desired, and several special escape codes. It defaults to `$f:$l:$n:$%'; see below for details on the format.

`--initialization'
`-i'
By default, `--trace' does not trace the initialization of the Autoconf macros (typically the AC_DEFUN definitions). This results in a noticeable speedup, but can be disabled by this option.

It is often necessary to check the content of a `configure.ac' file, but parsing it yourself is extremely fragile and error-prone. It is suggested that you rely upon `--trace' to scan `configure.ac'.

The format of `--trace' can use the following special escapes:

`$$'
The character `$'.

`$f'
The filename from which macro is called.

`$l'
The line number from which macro is called.

`$d'
The depth of the macro call. This is an M4 technical detail that you probably don't want to know about.

`$n'
The name of the macro.

`$num'
The numth argument of the call to macro.

`$@'
`$sep@'
`${separator}@'
All the arguments passed to macro, separated by the character sep or the string separator (`,' by default). Each argument is quoted, i.e. enclosed in a pair of square brackets.

`$*'
`$sep*'
`${separator}*'
As above, but the arguments are not quoted.

`$%'
`$sep%'
`${separator}%'
As above, but the arguments are not quoted, all new line characters in the arguments are smashed, and the default separator is `:'.

The escape `$%' produces single-line trace outputs (unless you put newlines in the `separator'), while `$@' and `$*' do not.

For instance, to find the list of variables that are substituted, use:

$ autoconf -t AC_SUBST
configure.ac:2:AC_SUBST:ECHO_C
configure.ac:2:AC_SUBST:ECHO_N
configure.ac:2:AC_SUBST:ECHO_T
More traces deleted

The example below highlights the difference between `$@', `$*', and $%.

$ cat configure.ac
AC_DEFINE(This, is, [an
[example]])
$ autoconf -t 'AC_DEFINE:@: $@
*: $*
$: $%'
@: [This],[is],[an
[example]]
*: This,is,an
[example]
$: This:is:an [example]

The format gives you a lot of freedom:

$ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";'
$ac_subst{"ECHO_C"} = "configure.ac:2";
$ac_subst{"ECHO_N"} = "configure.ac:2";
$ac_subst{"ECHO_T"} = "configure.ac:2";
More traces deleted

A long separator can be used to improve the readability of complex structures, and to ease its parsing (for instance when no single character is suitable as a separator)):

$ autoconf -t 'AM_MISSING_PROG:${|:::::|}*'
ACLOCAL|:::::|aclocal|:::::|$missing_dir
AUTOCONF|:::::|autoconf|:::::|$missing_dir
AUTOMAKE|:::::|automake|:::::|$missing_dir
More traces deleted

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5 Using autoreconf to Update configure Scripts

If you have a lot of Autoconf-generated configure scripts, the autoreconf program can save you some work. It runs autoconf (and autoheader, where appropriate) repeatedly to remake the Autoconf configure scripts and configuration header templates in the directory tree rooted at the current directory. By default, it only remakes those files that are older than their `configure.ac' or (if present) `aclocal.m4'. Since autoheader does not change the timestamp of its output file if the file wouldn't be changing, this is not necessarily the minimum amount of work. If you install a new version of Autoconf, you can make autoreconf remake all of the files by giving it the `--force' option.

If you give autoreconf the `--autoconf-dir=dir' or `--localdir=dir' options, it passes them down to autoconf and autoheader (with relative paths adjusted properly).

autoreconf does not support having, in the same directory tree, both directories that are parts of a larger package (sharing `aclocal.m4' and `acconfig.h') and directories that are independent packages (each with their own `aclocal.m4' and `acconfig.h'). It assumes that they are all part of the same package if you use `--localdir', or that each directory is a separate package if you don't use it. This restriction may be removed in the future.

See section 4.6.4 Automatic Remaking, for `Makefile' rules to automatically remake configure scripts when their source files change. That method handles the timestamps of configuration header templates properly, but does not pass `--autoconf-dir=dir' or `--localdir=dir'.

autoreconf accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--verbose'
Print the name of each directory where autoreconf runs autoconf (and autoheader, if appropriate).

`--debug'
`-d'
Don't remove the temporary files.

`--force'
`-f'
Remake even `configure' scripts and configuration headers that are newer than their input files (`configure.ac' and, if present, `aclocal.m4').

`--install'
`-i'
Copy missing auxiliary files. This option is similar to the option --add-missing in automake.

`--symlink'
`-s'
Instead of copying missing auxiliary files, install symbolic links.

`--localdir=dir'
`-l dir'
Have autoconf and autoheader look for the package files `aclocal.m4' and (autoheader only) `acconfig.h' (but not `file.top' and `file.bot') in directory dir instead of in the directory containing each `configure.ac'.

`--autoconf-dir=dir'
`-A dir'
Override the location where the installed Autoconf data files are looked for. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

This option is rarely needed and dangerous; it is only used when one plays with different versions of Autoconf simultaneously.

`--m4dir=dir'
`-M dir'
Specify location of additional macro files (`m4' by default).

Additionally, the following options are recognized and passed to automake:

`--cygnus'
Assume program is part of Cygnus-style tree.

`--foreign'
Set strictness to foreign.

`--gnits'
Set strictness to gnits.

`--gnu'
Set strictness to gnu.

`--include-deps'
Include generated dependencies in `Makefile.in'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Initialization and Output Files

Autoconf-generated configure scripts need some information about how to initialize, such as how to find the package's source files; and about the output files to produce. The following sections describe initialization and the creation of output files.

4.1 Notices in configure | Copyright, version numbers in configure
4.2 Finding configure Input | Where Autoconf should find files
4.3 Outputting Files | Outputting results from the configuration
4.4 Taking Configuration Actions | Preparing the output based on results
4.5 Creating Configuration Files | Creating output files
4.6 Substitutions in Makefiles | Using output variables in `Makefile's
4.7 Configuration Header Files | Creating a configuration header file
4.8 Running Arbitrary Configuration Commands | Running arbitrary instantiation commands
4.9 Creating Configuration Links | Links depending from the configuration
4.10 Configuring Other Packages in Subdirectories | Configuring independent packages together
4.11 Default Prefix | Changing the default installation prefix

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 Notices in configure

The following macros manage version numbers for configure scripts. Using them is optional.

Macro: AC_PREREQ (version)
Ensure that a recent enough version of Autoconf is being used. If the version of Autoconf being used to create configure is earlier than version, print an error message to the standard error output and do not create configure. For example:

AC_PREREQ(2.52)

This macro is the only macro that may be used before AC_INIT, but for consistency, you are invited not to do so.

Macro: AC_COPYRIGHT (copyright-notice)
State that, in addition to the Free Software Foundation's copyright on the Autoconf macros, parts of your configure are covered by the copyright-notice.

The copyright-notice will show up in both the head of configure and in `configure --version'.

Macro: AC_REVISION (revision-info)
Copy revision stamp revision-info into the configure script, with any dollar signs or double-quotes removed. This macro lets you put a revision stamp from `configure.ac' into configure without RCS or cvs changing it when you check in configure. That way, you can determine easily which revision of `configure.ac' a particular configure corresponds to.

For example, this line in `configure.ac':

AC_REVISION($Revision: 1.30 $)

produces this in configure:

#! /bin/sh
# From configure.ac Revision: 1.30

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2 Finding configure Input

Every configure script must call AC_INIT before doing anything else. The only other required macro is AC_OUTPUT (see section 4.3 Outputting Files).

Macro: AC_INIT (package, version, [bug-report-address])
Process any command-line arguments and perform various initializations and verifications. Set the name of the package and its version. The optional argument bug-report-address should be the email to which users should send bug reports.

Macro: AC_CONFIG_SRCDIR (unique-file-in-source-dir)
unique-file-in-source-dir is some file that is in the package's source directory; configure checks for this file's existence to make sure that the directory that it is told contains the source code in fact does. Occasionally people accidentally specify the wrong directory with `--srcdir'; this is a safety check. See section 13.9 configure Invocation, for more information.

Packages that do manual configuration or use the install program might need to tell configure where to find some other shell scripts by calling AC_CONFIG_AUX_DIR, though the default places it looks are correct for most cases.

Macro: AC_CONFIG_AUX_DIR (dir)
Use the auxiliary build tools (e.g., `install-sh', `config.sub', `config.guess', Cygnus configure, Automake and Libtool scripts etc.) that are in directory dir. These are auxiliary files used in configuration. dir can be either absolute or relative to `srcdir'. The default is `srcdir' or `srcdir/..' or `srcdir/../..', whichever is the first that contains `install-sh'. The other files are not checked for, so that using AC_PROG_INSTALL does not automatically require distributing the other auxiliary files. It checks for `install.sh' also, but that name is obsolete because some make have a rule that creates `install' from it if there is no `Makefile'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3 Outputting Files

Every Autoconf-generated configure script must finish by calling AC_OUTPUT. It is the macro that generates `config.status', which will create the `Makefile's and any other files resulting from configuration. The only other required macro is AC_INIT (see section 4.2 Finding configure Input).

Macro: AC_OUTPUT
Generate `config.status' and launch it. Call this macro once, at the end of `configure.ac'.

`config.status' will take all the configuration actions: all the output files (see 4.5 Creating Configuration Files, macro AC_CONFIG_FILES), header files (see 4.7 Configuration Header Files, macro AC_CONFIG_HEADERS), commands (see 4.8 Running Arbitrary Configuration Commands, macro AC_CONFIG_COMMANDS), links (see 4.9 Creating Configuration Links, macro AC_CONFIG_LINKS), subdirectories to configure (see 4.10 Configuring Other Packages in Subdirectories, macro AC_CONFIG_SUBDIRS) are honored.

Historically, the usage of AC_OUTPUT was somewhat different. See section 15.4 Obsolete Macros, for a description of the arguments that AC_OUTPUT used to support.

If you run make on subdirectories, you should run it using the make variable MAKE. Most versions of make set MAKE to the name of the make program plus any options it was given. (But many do not include in it the values of any variables set on the command line, so those are not passed on automatically.) Some old versions of make do not set this variable. The following macro allows you to use it even with those versions.

Macro: AC_PROG_MAKE_SET
If make predefines the variable MAKE, define output variable SET_MAKE to be empty. Otherwise, define SET_MAKE to contain `MAKE=make'. Calls AC_SUBST for SET_MAKE.

To use this macro, place a line like this in each `Makefile.in' that runs MAKE on other directories:

@SET_MAKE@

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4 Taking Configuration Actions

`configure' is designed so that it appears to do everything itself, but there is actually a hidden slave: `config.status'. `configure' is in charge of examining your system, but it is `config.status' that actually takes the proper actions based on the results of `configure'. The most typical task of `config.status' is to instantiate files.

This section describes the common behavior of the four standard instantiating macros: AC_CONFIG_FILES, AC_CONFIG_HEADERS, AC_CONFIG_COMMANDS and AC_CONFIG_LINKS. They all have this prototype:

AC_CONFIG_FOOS(tag..., [commands], [init-cmds])

where the arguments are:

tag...
A whitespace-separated list of tags, which are typically the names of the files to instantiate.

commands
Shell commands output literally into `config.status', and associated with a tag that the user can use to tell `config.status' which the commands to run. The commands are run each time a tag request is given to `config.status'; typically, each time the file `tag' is created.

init-cmds
Shell commands output unquoted near the beginning of `config.status', and executed each time `config.status' runs (regardless of the tag). Because they are unquoted, for example, `$var' will be output as the value of var. init-cmds is typically used by `configure' to give `config.status' some variables it needs to run the commands.

All these macros can be called multiple times, with different tags, of course!

You are encouraged to use literals as tags. In particular, you should avoid

... && my_foos="$my_foos fooo"
... && my_foos="$my_foos foooo"
AC_CONFIG_FOOS($my_foos)

and use this instead:

... && AC_CONFIG_FOOS(fooo)
... && AC_CONFIG_FOOS(foooo)

The macro AC_CONFIG_FILES and AC_CONFIG_HEADERS use specials tags: they may have the form `output' or `output:inputs'. The file output is instantiated from its templates, inputs if specified, defaulting to `output.in'.

For instance `AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)' asks for the creation of `Makefile' that will be the expansion of the output variables in the concatenation of `boiler/top.mk' and `boiler/bot.mk'.

The special value `-' might be used to denote the standard output when used in output, or the standard input when used in the inputs. You most probably don't need to use this in `configure.ac', but it is convenient when using the command line interface of `./config.status', see 14. Recreating a Configuration, for more details.

The inputs may be absolute or relative filenames. In the latter case they are first looked for in the build tree, and then in the source tree.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5 Creating Configuration Files

Be sure to read the previous section, 4.4 Taking Configuration Actions.

Macro: AC_CONFIG_FILES (file..., [cmds], [init-cmds])
Make AC_OUTPUT create each `file' by copying an input file (by default `file.in'), substituting the output variable values. This macro is one of the instantiating macros, see 4.4 Taking Configuration Actions. See section 4.6 Substitutions in Makefiles, for more information on using output variables. See section 7.2 Setting Output Variables, for more information on creating them. This macro creates the directory that the file is in if it doesn't exist. Usually, `Makefile's are created this way, but other files, such as `.gdbinit', can be specified as well.

Typical calls to AC_CONFIG_FILES look like this:

AC_CONFIG_FILES(Makefile src/Makefile man/Makefile X/Imakefile)
AC_CONFIG_FILES(autoconf, chmod +x autoconf)

You can override an input file name by appending to file a colon-separated list of input files. Examples:

AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk
                lib/Makefile:boiler/lib.mk)

Doing this allows you to keep your file names acceptable to MS-DOS, or to prepend and/or append boilerplate to the file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6 Substitutions in Makefiles

Each subdirectory in a distribution that contains something to be compiled or installed should come with a file `Makefile.in', from which configure will create a `Makefile' in that directory. To create a `Makefile', configure performs a simple variable substitution, replacing occurrences of `@variable@' in `Makefile.in' with the value that configure has determined for that variable. Variables that are substituted into output files in this way are called output variables. They are ordinary shell variables that are set in configure. To make configure substitute a particular variable into the output files, the macro AC_SUBST must be called with that variable name as an argument. Any occurrences of `@variable@' for other variables are left unchanged. See section 7.2 Setting Output Variables, for more information on creating output variables with AC_SUBST.

A software package that uses a configure script should be distributed with a file `Makefile.in', but no `Makefile'; that way, the user has to properly configure the package for the local system before compiling it.

See section `Makefile Conventions' in The GNU Coding Standards, for more information on what to put in `Makefile's.

4.6.1 Preset Output Variables | Output variables that are always set
4.6.2 Installation Directory Variables | Other preset output variables
4.6.3 Build Directories | Supporting multiple concurrent compiles
4.6.4 Automatic Remaking | Makefile rules for configuring

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.1 Preset Output Variables

Some output variables are preset by the Autoconf macros. Some of the Autoconf macros set additional output variables, which are mentioned in the descriptions for those macros. See section Output Variable Index, for a complete list of output variables. See section 4.6.2 Installation Directory Variables, for the list of the preset ones related to installation directories. Below are listed the other preset ones. They all are precious variables (see section 7.2 Setting Output Variables, AC_ARG_VAR).

Variable: CFLAGS
Debugging and optimization options for the C compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_CC (or empty if you don't). configure uses this variable when compiling programs to test for C features.

Variable: configure_input
A comment saying that the file was generated automatically by configure and giving the name of the input file. AC_OUTPUT adds a comment line containing this variable to the top of every `Makefile' it creates. For other files, you should reference this variable in a comment at the top of each input file. For example, an input shell script should begin like this:

#! /bin/sh
# @configure_input@

The presence of that line also reminds people editing the file that it needs to be processed by configure in order to be used.

Variable: CPPFLAGS
Header file search directory (`-Idir') and any other miscellaneous options for the C and C++ preprocessors and compilers. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when compiling or preprocessing programs to test for C and C++ features.

Variable: CXXFLAGS
Debugging and optimization options for the C++ compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_CXX (or empty if you don't). configure uses this variable when compiling programs to test for C++ features.

Variable: DEFS
`-D' options to pass to the C compiler. If AC_CONFIG_HEADERS is called, configure replaces `@DEFS@' with `-DHAVE_CONFIG_H' instead (see section 4.7 Configuration Header Files). This variable is not defined while configure is performing its tests, only when creating the output files. See section 7.2 Setting Output Variables, for how to check the results of previous tests.

Variable: ECHO_C
Variable: ECHO_N
Variable: ECHO_T
How does one suppress the trailing newline from echo for question-answer message pairs? These variables provide a way:

echo $ECHO_N "And the winner is... $ECHO_C"
sleep 100000000000
echo "${ECHO_T}dead."

Some old and uncommon echo implementations offer no means to achieve this, in which case ECHO_T is set to tab. You might not want to use it.

Variable: FFLAGS
Debugging and optimization options for the Fortran 77 compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_F77 (or empty if you don't). configure uses this variable when compiling programs to test for Fortran 77 features.

Variable: LDFLAGS
Stripping (`-s'), path (`-L'), and any other miscellaneous options for the linker. Don't use this variable to pass library names (`-l') to the linker, use LIBS instead. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when linking programs to test for C, C++ and Fortran 77 features.

Variable: LIBS
`-l' options to pass to the linker. The default value is empty, but some Autoconf macros may prepend extra libraries to this variable if those libraries are found and provide necessary functions, see 5.4 Library Files. configure uses this variable when linking programs to test for C, C++ and Fortran 77 features.

Variable: srcdir
The directory that contains the source code for that `Makefile'.

Variable: top_srcdir
The top-level source code directory for the package. In the top-level directory, this is the same as srcdir.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.2 Installation Directory Variables

The following variables specify the directories where the package will be installed, see section `Variables for Installation Directories' in The GNU Coding Standards, for more information. See the end of this section for details on when and how to use these variables.

Variable: bindir
The directory for installing executables that users run.

Variable: datadir
The directory for installing read-only architecture-independent data.

Variable: exec_prefix
The installation prefix for architecture-dependent files. By default it's the same as prefix. You should avoid installing anything directly to exec_prefix. However, the default value for directories containing architecture-dependent files should be relative to exec_prefix.

Variable: includedir
The directory for installing C header files.

Variable: infodir
The directory for installing documentation in Info format.

Variable: libdir
The directory for installing object code libraries.

Variable: libexecdir
The directory for installing executables that other programs run.

Variable: localstatedir
The directory for installing modifiable single-machine data.

Variable: mandir
The top-level directory for installing documentation in man format.

Variable: oldincludedir
The directory for installing C header files for non-gcc compilers.

Variable: prefix
The common installation prefix for all files. If exec_prefix is defined to a different value, prefix is used only for architecture-independent files.

Variable: sbindir
The directory for installing executables that system administrators run.

Variable: sharedstatedir
The directory for installing modifiable architecture-independent data.

Variable: sysconfdir
The directory for installing read-only single-machine data.

Most of these variables have values that rely on prefix or exec_prefix. It is on purpose that the directory output variables keep them unexpanded: typically `@datadir@' will be replaced by `${prefix}/share', not `/usr/local/share'.

This behavior is mandated by the GNU coding standards, so that when the user runs:

`make'
she can still specify a different prefix from the one specified to configure, in which case, if needed, the package shall hard code dependencies to her late desires.

`make install'
she can specify a different installation location, in which case the package must still depend on the location which was compiled in (i.e., never recompile when `make install' is run). This is an extremely important feature, as many people may decide to install all the files of a package grouped together, and then install links from the final locations to there.

In order to support these features, it is essential that datadir remains being defined as `${prefix}/share' to depend upon the current value of prefix.

A corollary is that you should not use these variables but in Makefiles. For instance, instead of trying to evaluate datadir in `configure' and hardcoding it in Makefiles using e.g. `AC_DEFINE_UNQUOTED(DATADIR, "$datadir")', you should add `-DDATADIR="$(datadir)"' to your CPPFLAGS.

Similarly you should not rely on AC_OUTPUT_FILES to replace datadir and friends in your shell scripts and other files, rather let make manage their replacement. For instance Autoconf ships templates of its shell scripts ending with `.sh', and uses this Makefile snippet:

.sh:
        rm -f $@ $@.tmp
        sed 's,@datadir\@,$(pkgdatadir),g' $< >$@.tmp
        chmod +x $@.tmp
        mv $@.tmp $@

Three things are noteworthy:

`@datadir\@'
The backslash prevents configure from replacing `@datadir@' in the sed expression itself.

`$(pkgdatadir)'
Don't use `@pkgdatadir@'! Use the matching makefile variable instead.

`,'
Don't use `/' in the sed expression(s) since most probably the variables you use, such as `$(pkgdatadir)', will contain some.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.3 Build Directories

You can support compiling a software package for several architectures simultaneously from the same copy of the source code. The object files for each architecture are kept in their own directory.

To support doing this, make uses the VPATH variable to find the files that are in the source directory. GNU make and most other recent make programs can do this. Older make programs do not support VPATH; when using them, the source code must be in the same directory as the object files.

To support VPATH, each `Makefile.in' should contain two lines that look like:

srcdir = @srcdir@
VPATH = @srcdir@

Do not set VPATH to the value of another variable, for example `VPATH = $(srcdir)', because some versions of make do not do variable substitutions on the value of VPATH.

configure substitutes in the correct value for srcdir when it produces `Makefile'.

Do not use the make variable $<, which expands to the file name of the file in the source directory (found with VPATH), except in implicit rules. (An implicit rule is one such as `.c.o', which tells how to create a `.o' file from a `.c' file.) Some versions of make do not set $< in explicit rules; they expand it to an empty value.

Instead, `Makefile' command lines should always refer to source files by prefixing them with `$(srcdir)/'. For example:

time.info: time.texinfo
        $(MAKEINFO) $(srcdir)/time.texinfo

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.4 Automatic Remaking

You can put rules like the following in the top-level `Makefile.in' for a package to automatically update the configuration information when you change the configuration files. This example includes all of the optional files, such as `aclocal.m4' and those related to configuration header files. Omit from the `Makefile.in' rules for any of these files that your package does not use.

The `$(srcdir)/' prefix is included because of limitations in the VPATH mechanism.

The `stamp-' files are necessary because the timestamps of `config.h.in' and `config.h' will not be changed if remaking them does not change their contents. This feature avoids unnecessary recompilation. You should include the file `stamp-h.in' your package's distribution, so make will consider `config.h.in' up to date. Don't use touch (see section 10.9 Limitations of Usual Tools), rather use echo (using date would cause needless differences, hence CVS conflicts etc.).

$(srcdir)/configure: configure.ac aclocal.m4
        cd $(srcdir) && autoconf

# autoheader might not change config.h.in, so touch a stamp file.
$(srcdir)/config.h.in: stamp-h.in
$(srcdir)/stamp-h.in: configure.ac aclocal.m4
        cd $(srcdir) && autoheader
        echo timestamp > $(srcdir)/stamp-h.in

config.h: stamp-h
stamp-h: config.h.in config.status
        ./config.status

Makefile: Makefile.in config.status
        ./config.status

config.status: configure
        ./config.status --recheck

(Be careful if you copy these lines directly into your Makefile, as you will need to convert the indented lines to start with the tab character.)

In addition, you should use `AC_CONFIG_FILES(stamp-h, echo timestamp > stamp-h)' so `config.status' will ensure that `config.h' is considered up to date. See section 4.3 Outputting Files, for more information about AC_OUTPUT.

See section 14. Recreating a Configuration, for more examples of handling configuration-related dependencies.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.7 Configuration Header Files

When a package tests more than a few C preprocessor symbols, the command lines to pass `-D' options to the compiler can get quite long. This causes two problems. One is that the make output is hard to visually scan for errors. More seriously, the command lines can exceed the length limits of some operating systems. As an alternative to passing `-D' options to the compiler, configure scripts can create a C header file containing `#define' directives. The AC_CONFIG_HEADERS macro selects this kind of output. It should be called right after AC_INIT.

The package should `#include' the configuration header file before any other header files, to prevent inconsistencies in declarations (for example, if it redefines const). Use `#include <config.h>' instead of `#include "config.h"', and pass the C compiler a `-I.' option (or `-I..'; whichever directory contains `config.h'). That way, even if the source directory is configured itself (perhaps to make a distribution), other build directories can also be configured without finding the `config.h' from the source directory.

Macro: AC_CONFIG_HEADERS (header ..., [cmds], [init-cmds])
This macro is one of the instantiating macros, see 4.4 Taking Configuration Actions. Make AC_OUTPUT create the file(s) in the whitespace-separated list header containing C preprocessor #define statements, and replace `@DEFS@' in generated files with `-DHAVE_CONFIG_H' instead of the value of DEFS. The usual name for header is `config.h'.

If header already exists and its contents are identical to what AC_OUTPUT would put in it, it is left alone. Doing this allows some changes in configuration without needlessly causing object files that depend on the header file to be recompiled.

Usually the input file is named `header.in'; however, you can override the input file name by appending to header, a colon-separated list of input files. Examples:

AC_CONFIG_HEADERS(config.h:config.hin)
AC_CONFIG_HEADERS(defines.h:defs.pre:defines.h.in:defs.post)

Doing this allows you to keep your file names acceptable to MS-DOS, or to prepend and/or append boilerplate to the file.

See section 4.4 Taking Configuration Actions, for more details on header.

4.7.1 Configuration Header Templates | Input for the configuration headers
4.7.2 Using autoheader to Create `config.h.in' | How to create configuration templates
4.7.3 Autoheader Macros | How to specify CPP templates

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.7.1 Configuration Header Templates

Your distribution should contain a template file that looks as you want the final header file to look, including comments, with #undef statements which are used as hooks. For example, suppose your `configure.ac' makes these calls:

AC_CONFIG_HEADERS(conf.h)
AC_CHECK_HEADERS(unistd.h)

Then you could have code like the following in `conf.h.in'. On systems that have `unistd.h', configure will `#define' `HAVE_UNISTD_H' to 1. On other systems, the whole line will be commented out (in case the system predefines that symbol).

/* Define as 1 if you have unistd.h.  */
#undef HAVE_UNISTD_H

You can then decode the configuration header using the preprocessor directives:

#include <conf.h>

#if HAVE_UNISTD_H
# include <unistd.h>
#else
/* We are in trouble. */
#endif

The use of old form templates, with `#define' instead of `#undef' is strongly discouraged.

Since it is a tedious task to keep a template header up to date, you may use autoheader to generate it, see 4.7.2 Using autoheader to Create `config.h.in'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.7.2 Using autoheader to Create `config.h.in'

The autoheader program can create a template file of C `#define' statements for configure to use. If `configure.ac' invokes AC_CONFIG_HEADERS(file), autoheader creates `file.in'; if multiple file arguments are given, the first one is used. Otherwise, autoheader creates `config.h.in'.

In order to do its job, autoheader needs you to document all of the symbols that you might use; i.e., there must be at least one AC_DEFINE or one AC_DEFINE_UNQUOTED using its third argument for each symbol (see section 7.1 Defining C Preprocessor Symbols). An additional constraint is that the first argument of AC_DEFINE must be a literal. Note that all symbols defined by Autoconf's built-in tests are already documented properly; you only need to document those that you define yourself.

You might wonder why autoheader is needed: after all, why would configure need to "patch" a `config.h.in' to produce a `config.h' instead of just creating `config.h' from scratch? Well, when everything rocks, the answer is just that we are wasting our time maintaining autoheader: generating `config.h' directly is all that is needed. When things go wrong, however, you'll be thankful for the existence of autoheader.

The fact that the symbols are documented is important in order to check that `config.h' makes sense. The fact that there is a well defined list of symbols that should be #define'd (or not) is also important for people who are porting packages to environments where configure cannot be run: they just have to fill in the blanks.

But let's come back to the point: autoheader's invocation...

If you give autoheader an argument, it uses that file instead of `configure.ac' and writes the header file to the standard output instead of to `config.h.in'. If you give autoheader an argument of `-', it reads the standard input instead of `configure.ac' and writes the header file to the standard output.

autoheader accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--debug'
`-d'
Don't remove the temporary files.

`--verbose'
`-v'
Report processing steps.

`--autoconf-dir=dir'
`-A dir'
Override the location where the installed Autoconf data files are looked for. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

This option is rarely needed and dangerous; it is only used when one plays with different versions of Autoconf simultaneously.

`--localdir=dir'
`-l dir'
Look for the package files `aclocal.m4' and `acconfig.h' (but not `file.top' and `file.bot') in directory dir instead of in the current directory.

`--warnings=category'
`-W category'
Report the warnings related to category (which can actually be a comma separated list). Current categories include:

`obsolete'
report the uses of obsolete constructs

`all'
report all the warnings

`none'
report none

`error'
treats warnings as errors

`no-category'
disable warnings falling into category

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.7.3 Autoheader Macros

autoheader scans `configure.ac' and figures out which C preprocessor symbols it might define. It knows how to generate templates for symbols defined by AC_CHECK_HEADERS, AC_CHECK_FUNCS etc., but if you AC_DEFINE any additional symbol, you must define a template for it. If there are missing templates, autoheader fails with an error message.

The simplest way to create a template for a symbol is to supply the description argument to an `AC_DEFINE(symbol)'; see 7.1 Defining C Preprocessor Symbols. You may also use one of the following macros.

Macro: AH_VERBATIM (key, template)
Tell autoheader to include the template as-is in the header template file. This template is associated with the key, which is used to sort all the different templates and guarantee their uniqueness. It should be the symbol that can be AC_DEFINE'd.

For example:

AH_VERBATIM([_GNU_SOURCE],
[/* Enable GNU extensions on systems that have them.  */
#ifndef _GNU_SOURCE
# define _GNU_SOURCE
#endif])

Macro: AH_TEMPLATE (key, description)
Tell autoheader to generate a template for key. This macro generates standard templates just like AC_DEFINE when a description is given.

For example:

AH_TEMPLATE([CRAY_STACKSEG_END],
            [Define to one of _getb67, GETB67, getb67
             for Cray-2 and Cray-YMP systems.  This
             function is required for alloca.c support
             on those systems.])

will generate the following template, with the description properly justified.

/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
   Cray-YMP systems. This function is required for alloca.c
   support on those systems. */
#undef CRAY_STACKSEG_END

Macro: AH_TOP (text)
Include text at the top of the header template file.

Macro: AH_BOTTOM (text)
Include text at the bottom of the header template file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.8 Running Arbitrary Configuration Commands

You execute arbitrary commands either before, during and after `config.status' is run. The three following macros accumulate the commands to run when they are called multiple times. AC_CONFIG_COMMANDS replaces the obsolete macro AC_OUTPUT_COMMANDS, see 15.4 Obsolete Macros, for details.

Macro: AC_CONFIG_COMMANDS (tag..., [cmds], [init-cmds])
Specify additional shell commands to run at the end of `config.status', and shell commands to initialize any variables from configure. Associate the commands to the tag. Since typically the cmds create a file, tag should naturally be the name of that file. This macro is one of the instantiating macros, see 4.4 Taking Configuration Actions.

Here is an unrealistic example:
fubar=42
AC_CONFIG_COMMANDS(fubar,
                   [echo this is extra $fubar, and so on.],
                   [fubar=$fubar])

Here is a better one:
AC_CONFIG_COMMANDS(time-stamp, [date >time-stamp])

Macro: AC_CONFIG_COMMANDS_PRE (cmds)
Execute the cmds right before creating `config.status'. A typical use is computing values derived from variables built during the execution of configure:

AC_CONFIG_COMMANDS_PRE(
[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'`
AC_SUBST(LTLIBOBJS)])

Macro: AC_CONFIG_COMMANDS_POST (cmds)
Execute the cmds right after creating `config.status'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.9 Creating Configuration Links

You may find it convenient to create links whose destinations depend upon results of tests. One can use AC_CONFIG_COMMANDS but the creation of relative symbolic links can be delicate when the package is built in another directory than its sources.

Macro: AC_CONFIG_LINKS (dest:source..., [cmds], [init-cmds])
Make AC_OUTPUT link each of the existing files source to the corresponding link name dest. Makes a symbolic link if possible, otherwise a hard link. The dest and source names should be relative to the top level source or build directory. This macro is one of the instantiating macros, see 4.4 Taking Configuration Actions.

For example, this call:

AC_CONFIG_LINKS(host.h:config/$machine.h
                object.h:config/$obj_format.h)

creates in the current directory `host.h' as a link to `srcdir/config/$machine.h', and `object.h' as a link to `srcdir/config/$obj_format.h'.

The tempting value `.' for dest is invalid: it makes it impossible for `config.status' to guess the links to establish.

One can then run:
./config.status host.h object.h
to create the links.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.10 Configuring Other Packages in Subdirectories

In most situations, calling AC_OUTPUT is sufficient to produce `Makefile's in subdirectories. However, configure scripts that control more than one independent package can use AC_CONFIG_SUBDIRS to run configure scripts for other packages in subdirectories.

Macro: AC_CONFIG_SUBDIRS (dir ...)
Make AC_OUTPUT run configure in each subdirectory dir in the given whitespace-separated list. Each dir should be a literal, i.e., please do not use:

if test "$package_foo_enabled" = yes; then
  $my_subdirs="$my_subdirs foo"
fi
AC_CONFIG_SUBDIRS($my_subdirs)

because this prevents `./configure --help=recursive' from displaying the options of the package foo. Rather, you should write:

if test "$package_foo_enabled" = yes then;
  AC_CONFIG_SUBDIRS(foo)
fi

If a given dir is not found, no error is reported, so a configure script can configure whichever parts of a large source tree are present. If a given dir contains configure.gnu, it is run instead of configure. This is for packages that might use a non-autoconf script Configure, which can't be called through a wrapper configure since it would be the same file on case-insensitive filesystems. Likewise, if a dir contains `configure.ac' but no configure, the Cygnus configure script found by AC_CONFIG_AUX_DIR is used.

The subdirectory configure scripts are given the same command line options that were given to this configure script, with minor changes if needed (e.g., to adjust a relative path for the cache file or source directory). This macro also sets the output variable subdirs to the list of directories `dir ...'. `Makefile' rules can use this variable to determine which subdirectories to recurse into. This macro may be called multiple times.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.11 Default Prefix

By default, configure sets the prefix for files it installs to `/usr/local'. The user of configure can select a different prefix using the `--prefix' and `--exec-prefix' options. There are two ways to change the default: when creating configure, and when running it.

Some software packages might want to install in a directory besides `/usr/local' by default. To accomplish that, use the AC_PREFIX_DEFAULT macro.

Macro: AC_PREFIX_DEFAULT (prefix)
Set the default installation prefix to prefix instead of `/usr/local'.

It may be convenient for users to have configure guess the installation prefix from the location of a related program that they have already installed. If you wish to do that, you can call AC_PREFIX_PROGRAM.

Macro: AC_PREFIX_PROGRAM (program)
If the user did not specify an installation prefix (using the `--prefix' option), guess a value for it by looking for program in PATH, the way the shell does. If program is found, set the prefix to the parent of the directory containing program; otherwise leave the prefix specified in `Makefile.in' unchanged. For example, if program is gcc and the PATH contains `/usr/local/gnu/bin/gcc', set the prefix to `/usr/local/gnu'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Existing Tests

These macros test for particular system features that packages might need or want to use. If you need to test for a kind of feature that none of these macros check for, you can probably do it by calling primitive test macros with appropriate arguments (see section 6. Writing Tests).

These tests print messages telling the user which feature they're checking for, and what they find. They cache their results for future configure runs (see section 7.3 Caching Results).

Some of these macros set output variables. See section 4.6 Substitutions in Makefiles, for how to get their values. The phrase "define name" is used below as a shorthand to mean "define C preprocessor symbol name to the value 1". See section 7.1 Defining C Preprocessor Symbols, for how to get those symbol definitions into your program.

5.1 Common Behavior | Macros' standard schemes
5.2 Alternative Programs | Selecting between alternative programs
5.3 Files | Checking for the existence of files
5.4 Library Files | Library archives that might be missing
5.5 Library Functions | C library functions that might be missing
5.6 Header Files | Header files that might be missing
5.7 Declarations | Declarations that may be missing
5.8 Structures | Structures or members that might be missing
5.9 Types | Types that might be missing
5.10 Compilers and Preprocessors | Checking for compiling programs
5.11 System Services | Operating system services
5.12 UNIX Variants | Special kludges for specific UNIX variants

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 Common Behavior

Much effort has been expended to make Autoconf easy to learn. The most obvious way to reach this goal is simply to enforce standard interfaces and behaviors, avoiding exceptions as much as possible. Because of history and inertia, unfortunately, there are still too many exceptions in Autoconf; nevertheless, this section describes some of the common rules.

5.1.1 Standard Symbols | Symbols defined by the macros
5.1.2 Default Includes | Includes used by the generic macros

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.1 Standard Symbols

All the generic macros that AC_DEFINE a symbol as a result of their test transform their arguments to a standard alphabet. First, argument is converted to upper case and any asterisks (`*') are each converted to `P'. Any remaining characters that are not alphanumeric are converted to underscores.

For instance,

AC_CHECK_TYPES(struct $Expensive*)

will define the symbol `HAVE_STRUCT__EXPENSIVEP' if the check succeeds.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.2 Default Includes

Several tests depend upon a set of header files. Since these headers are not universally available, tests actually have to provide a set of protected includes, such as:

#if TIME_WITH_SYS_TIME
# include <sys/time.h>
# include <time.h>
#else
# if HAVE_SYS_TIME_H
#  include <sys/time.h>
# else
#  include <time.h>
# endif
#endif

Unless you know exactly what you are doing, you should avoid using unconditional includes, and check the existence of the headers you include beforehand (see section 5.6 Header Files).

Most generic macros provide the following default set of includes:

#include <stdio.h>
#if HAVE_SYS_TYPES_H
# include <sys/types.h>
#endif
#if HAVE_SYS_STAT_H
# include <sys/stat.h>
#endif
#if STDC_HEADERS
# include <stdlib.h>
# include <stddef.h>
#else
# if HAVE_STDLIB_H
#  include <stdlib.h>
# endif
#endif
#if HAVE_STRING_H
# if !STDC_HEADERS && HAVE_MEMORY_H
#  include <memory.h>
# endif
# include <string.h>
#endif
#if HAVE_STRINGS_H
# include <strings.h>
#endif
#if HAVE_INTTYPES_H
# include <inttypes.h>
#else
# if HAVE_STDINT_H
#  include <stdint.h>
# endif
#endif
#if HAVE_UNISTD_H
# include <unistd.h>
#endif

If the default includes are used, then Autoconf will automatically check for the presence of these headers and their compatibility, i.e., you don't need to run AC_HEADERS_STDC, nor check for `stdlib.h' etc.

These headers are checked for in the same order as they are included. For instance, on some systems `string.h' and `strings.h' both exist, but conflict. Then HAVE_STRING_H will be defined, but HAVE_STRINGS_H won't.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 Alternative Programs

These macros check for the presence or behavior of particular programs. They are used to choose between several alternative programs and to decide what to do once one has been chosen. If there is no macro specifically defined to check for a program you need, and you don't need to check for any special properties of it, then you can use one of the general program-check macros.

5.2.1 Particular Program Checks | Special handling to find certain programs
5.2.2 Generic Program and File Checks | How to find other programs

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2.1 Particular Program Checks

These macros check for particular programs--whether they exist, and in some cases whether they support certain features.

Macro: AC_PROG_AWK
Check for mawk, gawk, nawk, and awk, in that order, and set output variable AWK to the first one that is found. It tries mawk first because that is reported to be the fastest implementation.

Macro: AC_PROG_INSTALL
Set output variable INSTALL to the path of a BSD compatible install program, if one is found in the current PATH. Otherwise, set INSTALL to `dir/install-sh -c', checking the directories specified to AC_CONFIG_AUX_DIR (or its default directories) to determine dir (see section 4.3 Outputting Files). Also set the variables INSTALL_PROGRAM and INSTALL_SCRIPT to `${INSTALL}' and INSTALL_DATA to `${INSTALL} -m 644'.

This macro screens out various instances of install known not to work. It prefers to find a C program rather than a shell script, for speed. Instead of `install-sh', it can also use `install.sh', but that name is obsolete because some make programs have a rule that creates `install' from it if there is no `Makefile'.

Autoconf comes with a copy of `install-sh' that you can use. If you use AC_PROG_INSTALL, you must include either `install-sh' or `install.sh' in your distribution, or configure will produce an error message saying it can't find them--even if the system you're on has a good install program. This check is a safety measure to prevent you from accidentally leaving that file out, which would prevent your package from installing on systems that don't have a BSD-compatible install program.

If you need to use your own installation program because it has features not found in standard install programs, there is no reason to use AC_PROG_INSTALL; just put the file name of your program into your `Makefile.in' files.

Macro: AC_PROG_LEX
If flex is found, set output variable LEX to `flex' and LEXLIB to `-lfl', if that library is in a standard place. Otherwise set LEX to `lex' and LEXLIB to `-ll'.

Define YYTEXT_POINTER if yytext is a `char *' instead of a `char []'. Also set output variable LEX_OUTPUT_ROOT to the base of the file name that the lexer generates; usually `lex.yy', but sometimes something else. These results vary according to whether lex or flex is being used.

You are encouraged to use Flex in your sources, since it is both more pleasant to use than plain Lex and the C source it produces is portable. In order to ensure portability, however, you must either provide a function yywrap or, if you don't use it (e.g., your scanner has no `#include'-like feature), simply include a `%noyywrap' statement in the scanner's source. Once this done, the scanner is portable (unless you felt free to use nonportable constructs) and does not depend on any library. In this case, and in this case only, it is suggested that you use this Autoconf snippet:

AC_PROG_LEX
if test "$LEX" != flex; then
  LEX="$SHELL $missing_dir/missing flex"
  AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
  AC_SUBST(LEXLIB, '')
fi

The shell script missing can be found in the Automake distribution.

To ensure backward compatibility, Automake's AM_PROG_LEX invokes (indirectly) this macro twice, which will cause an annoying but benign "AC_PROG_LEX invoked multiple times" warning. Future versions of Automake will fix this issue, meanwhile, just ignore this message.

Macro: AC_PROG_LN_S
If `ln -s' works on the current file system (the operating system and file system support symbolic links), set the output variable LN_S to `ln -s'; otherwise, if `ln' works, set LN_S to `ln' and otherwise set it to `cp -p'.

If you make a link a directory other than the current directory, its meaning depends on whether `ln' or `ln -s' is used. To safely create links using `$(LN_S)', either find out which form is used and adjust the arguments, or always invoke ln in the directory where the link is to be created.

In other words, it does not work to do:
$(LN_S) foo /x/bar

Instead, do:

(cd /x && $(LN_S) foo bar)

Macro: AC_PROG_RANLIB
Set output variable RANLIB to `ranlib' if ranlib is found, and otherwise to `:' (do nothing).

Macro: AC_PROG_YACC
If bison is found, set output variable YACC to `bison -y'. Otherwise, if byacc is found, set YACC to `byacc'. Otherwise set YACC to `yacc'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2.2 Generic Program and File Checks

These macros are used to find programs not covered by the "particular" test macros. If you need to check the behavior of a program as well as find out whether it is present, you have to write your own test for it (see section 6. Writing Tests). By default, these macros use the environment variable PATH. If you need to check for a program that might not be in the user's PATH, you can pass a modified path to use instead, like this:

AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd,
  $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc)

You are strongly encouraged to declare the variable passed to AC_CHECK_PROG etc. as precious, See section 7.2 Setting Output Variables, AC_ARG_VAR, for more details.

Macro: AC_CHECK_PROG (variable, prog-to-check-for, value-if-found, [value-if-not-found], [path], [reject])
Check whether program prog-to-check-for exists in PATH. If it is found, set variable to value-if-found, otherwise to value-if-not-found, if given. Always pass over reject (an absolute file name) even if it is the first found in the search path; in that case, set variable using the absolute file name of the prog-to-check-for found that is not reject. If variable was already set, do nothing. Calls AC_SUBST for variable.

Macro: AC_CHECK_PROGS (variable, progs-to-check-for, [value-if-not-found], [path])
Check for each program in the whitespace-separated list progs-to-check-for exists on the PATH. If it is found, set variable to the name of that program. Otherwise, continue checking the next program in the list. If none of the programs in the list are found, set variable to value-if-not-found; if value-if-not-found is not specified, the value of variable is not changed. Calls AC_SUBST for variable.

Macro: AC_CHECK_TOOL (variable, prog-to-check-for, [value-if-not-found], [path])
Like AC_CHECK_PROG, but first looks for prog-to-check-for with a prefix of the host type as determined by AC_CANONICAL_HOST, followed by a dash (see section 11.2 Getting the Canonical System Type). For example, if the user runs `configure --host=i386-gnu', then this call:
AC_CHECK_TOOL(RANLIB, ranlib, :)
sets RANLIB to `i386-gnu-ranlib' if that program exists in PATH, or otherwise to `ranlib' if that program exists in PATH, or to `:' if neither program exists.

Macro: AC_CHECK_TOOLS (variable, progs-to-check-for, [value-if-not-found], [path])
Like AC_CHECK_TOOL, each of the tools in the list progs-to-check-for are checked with a prefix of the host type as determined by AC_CANONICAL_HOST, followed by a dash (see section 11.2 Getting the Canonical System Type). If none of the tools can be found with a prefix, then the first one without a prefix is used. If a tool is found, set variable to the name of that program. If none of the tools in the list are found, set variable to value-if-not-found; if value-if-not-found is not specified, the value of variable is not changed. Calls AC_SUBST for variable.

Macro: AC_PATH_PROG (variable, prog-to-check-for, [value-if-not-found], [path])
Like AC_CHECK_PROG, but set variable to the entire path of prog-to-check-for if found.

Macro: AC_PATH_PROGS (variable, progs-to-check-for, [value-if-not-found], [path])
Like AC_CHECK_PROGS, but if any of progs-to-check-for are found, set variable to the entire path of the program found.

Macro: AC_PATH_TOOL (variable, prog-to-check-for, [value-if-not-found], [path])
Like AC_CHECK_TOOL, but set variable to the entire path of the program if it is found.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.3 Files

You might also need to check for the existence of files. Before using these macros, ask yourself whether a run time test might not be a better solution. Be aware that, like most Autoconf macros, they test a feature of the host machine, and therefore, they die when cross-compiling.

Macro: AC_CHECK_FILE (file, [action-if-found], [action-if-not-found])
Check whether file file exists on the native system. If it is found, execute action-if-found, otherwise do action-if-not-found, if given.

Macro: AC_CHECK_FILES (files, [action-if-found], [action-if-not-found])
Executes AC_CHECK_FILE once for each file listed in files. Additionally, defines `HAVE_file' (see section 5.1.1 Standard Symbols) for each file found.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4 Library Files

The following macros check for the presence of certain C, C++ or Fortran 77 library archive files.

Macro: AC_CHECK_LIB (library, function, [action-if-found], [action-if-not-found], [other-libraries])
Depending on the current language(see section 6.7 Language Choice), try to ensure that the C, C++, or Fortran 77 function function is available by checking whether a test program can be linked with the library library to get the function. library is the base name of the library; e.g., to check for `-lmp', use `mp' as the library argument.

action-if-found is a list of shell commands to run if the link with the library succeeds; action-if-not-found is a list of shell commands to run if the link fails. If action-if-found is not specified, the default action will prepend `-llibrary' to LIBS and define `HAVE_LIBlibrary' (in all capitals). This macro is intended to support building of LIBS in a right-to-left (least-dependent to most-dependent) fashion such that library dependencies are satisfied as a natural side-effect of consecutive tests. Some linkers are very sensitive to library ordering so the order in which LIBS is generated is important to reliable detection of libraries.

If linking with library results in unresolved symbols that would be resolved by linking with additional libraries, give those libraries as the other-libraries argument, separated by spaces: e.g. `-lXt -lX11'. Otherwise, this macro will fail to detect that library is present, because linking the test program will always fail with unresolved symbols. The other-libraries argument should be limited to cases where it is desirable to test for one library in the presence of another that is not already in LIBS.

Macro: AC_SEARCH_LIBS (function, search-libs, [action-if-found], [action-if-not-found], [other-libraries])
Search for a library defining function if it's not already available. This equates to calling AC_TRY_LINK_FUNC first with no libraries, then for each library listed in search-libs.

Add `-llibrary' to LIBS for the first library found to contain function, and run action-if-found. If the function is not found, run action-if-not-found.

If linking with library results in unresolved symbols that would be resolved by linking with additional libraries, give those libraries as the other-libraries argument, separated by spaces: e.g. `-lXt -lX11'. Otherwise, this macro will fail to detect that function is present, because linking the test program will always fail with unresolved symbols.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.5 Library Functions

The following macros check for particular C library functions. If there is no macro specifically defined to check for a function you need, and you don't need to check for any special properties of it, then you can use one of the general function-check macros.

5.5.1 Portability of Classical Functions | Pitfalls with usual functions
5.5.2 Particular Function Checks | Special handling to find certain functions
5.5.3 Generic Function Checks | How to find other functions

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.5.1 Portability of Classical Functions

Most usual functions can either be missing, or be buggy, or be limited on some architectures. This section tries to make an inventory of these portability issues. By definition, this list will always require additions, please help us keeping it as complete as possible

unlink
The POSIX spec says that unlink causes the given files to be removed only after there are no more open file handles for it. Not all OS's support this behaviour though. So even on systems that provide unlink, you cannot portably assume it is OK to call it on files that are open. For example, on Windows 9x and ME, such a call would fail; on DOS it could even lead to file system corruption, as the file might end up being written to after the OS has removed it.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.5.2 Particular Function Checks

These macros check for particular C functions--whether they exist, and in some cases how they respond when given certain arguments.

Macro: AC_FUNC_ALLOCA
Check how to get alloca. Tries to get a builtin version by checking for `alloca.h' or the predefined C preprocessor macros __GNUC__ and _AIX. If this macro finds `alloca.h', it defines HAVE_ALLOCA_H.

If those attempts fail, it looks for the function in the standard C library. If any of those methods succeed, it defines HAVE_ALLOCA. Otherwise, it sets the output variable ALLOCA to `alloca.o' and defines C_ALLOCA (so programs can periodically call `alloca(0)' to garbage collect). This variable is separate from LIBOBJS so multiple programs can share the value of ALLOCA without needing to create an actual library, in case only some of them use the code in LIBOBJS.

This macro does not try to get alloca from the System V R3 `libPW' or the System V R4 `libucb' because those libraries contain some incompatible functions that cause trouble. Some versions do not even contain alloca or contain a buggy version. If you still want to use their alloca, use ar to extract `alloca.o' from them instead of compiling `alloca.c'.

Source files that use alloca should start with a piece of code like the following, to declare it properly. In some versions of AIX, the declaration of alloca must precede everything else except for comments and preprocessor directives. The #pragma directive is indented so that pre-ANSI C compilers will ignore it, rather than choke on it.

/* AIX requires this to be the first thing in the file.  */
#ifndef __GNUC__
# if HAVE_ALLOCA_H
#  include <alloca.h>
# else
#  ifdef _AIX
 #pragma alloca
#  else
#   ifndef alloca /* predefined by HP cc +Olibcalls */
char *alloca ();
#   endif
#  endif
# endif
#endif

Macro: AC_FUNC_CHOWN
If the chown function is available and works (in particular, it should accept `-1' for uid and gid), define HAVE_CHOWN.

Macro: AC_FUNC_CLOSEDIR_VOID
If the closedir function does not return a meaningful value, define CLOSEDIR_VOID. Otherwise, callers ought to check its return value for an error indicator.

Macro: AC_FUNC_ERROR_AT_LINE
If the error_at_line function is not found, require an AC_LIBOBJ replacement of `error'.

Macro: AC_FUNC_FNMATCH
If the fnmatch function is available and works (unlike the one on Solaris 2.4), define HAVE_FNMATCH.

Macro: AC_FUNC_FORK
This macro checks for the fork and vfork functions. If a working fork is found, define HAVE_WORKING_FORK. This macro checks whether fork is just a stub by trying to run it.

If `vfork.h' is found, define HAVE_VFORK_H. If a working vfork is found, define HAVE_WORKING_VFORK. Otherwise, define vfork to be fork for backward compatibility with previous versions of autoconf. This macro checks for several known errors in implementations of vfork and considers the system to not have a working vfork if it detects any of them. It is not considered to be an implementation error if a child's invocation of signal modifies the parent's signal handler, since child processes rarely change their signal handlers.

Since this macro defines vfork only for backward compatibility with previous versions of autoconf you're encouraged to define it yourself in new code:
#if !HAVE_WORKING_VFORK
# define vfork fork
#endif

Macro: AC_FUNC_FSEEKO
If the fseeko function is available, define HAVE_FSEEKO. Define _LARGEFILE_SOURCE if necessary.

Macro: AC_FUNC_GETGROUPS
If the getgroups function is available and works (unlike on Ultrix 4.3, where `getgroups (0, 0)' always fails), define HAVE_GETGROUPS. Set GETGROUPS_LIBS to any libraries needed to get that function. This macro runs AC_TYPE_GETGROUPS.

Macro: AC_FUNC_GETLOADAVG
Check how to get the system load averages. If the system has the getloadavg function, define HAVE_GETLOADAVG, and set GETLOADAVG_LIBS to any libraries needed to get that function. Also add GETLOADAVG_LIBS to LIBS.

Otherwise, require an AC_LIBOBJ replacement (`getloadavg.c') of `getloadavg', and possibly define several other C preprocessor macros and output variables:

  1. Define C_GETLOADAVG.

  2. Define SVR4, DGUX, UMAX, or UMAX4_3 if on those systems.

  3. If `nlist.h' is found, define NLIST_STRUCT.

  4. If `struct nlist' has an `n_un.n_name' member, define HAVE_STRUCT_NLIST_N_UN_N_NAME. The obsolete symbol NLIST_NAME_UNION is still defined, but do not depend upon it.

  5. Programs may need to be installed setgid (or setuid) for getloadavg to work. In this case, define GETLOADAVG_PRIVILEGED, set the output variable NEED_SETGID to `true' (and otherwise to `false'), and set KMEM_GROUP to the name of the group that should own the installed program.

Macro: AC_FUNC_GETMNTENT
Check for getmntent in the `sun', `seq', and `gen' libraries, for Irix 4, PTX, and Unixware, respectively. Then, if getmntent is available, define HAVE_GETMNTENT.

Macro: AC_FUNC_GETPGRP
If getpgrp takes no argument (the POSIX.1 version), define GETPGRP_VOID. Otherwise, it is the BSD version, which takes a process ID as an argument. This macro does not check whether getpgrp exists at all; if you need to work in that situation, first call AC_CHECK_FUNC for getpgrp.

Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
If `link' is a symbolic link, then lstat should treat `link/' the same as `link/.'. However, many older lstat implementations incorrectly ignore trailing slashes.

It is safe to assume that if lstat incorrectly ignores trailing slashes, then other symbolic-link-aware functions like unlink and unlink also incorrectly ignore trailing slashes.

If lstat behaves properly, define LSTAT_FOLLOWS_SLASHED_SYMLINK, otherwise require an AC_LIBOBJ replacement of lstat.

Macro: AC_FUNC_MALLOC
If the malloc works correctly (`malloc (0)' returns a valid pointer), define HAVE_MALLOC.

Macro: AC_FUNC_MEMCMP
If the memcmp function is not available, or does not work on 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16 bytes or more and with at least one buffer not starting on a 4-byte boundary (such as the one on NeXT x86 OpenStep), require an AC_LIBOBJ replacement for `memcmp'.

Macro: AC_FUNC_MKTIME
If the mktime function is not available, or does not work correctly, require an AC_LIBOBJ replacement for `mktime'.

Macro: AC_FUNC_MMAP
If the mmap function exists and works correctly, define HAVE_MMAP. Only checks private fixed mapping of already-mapped memory.

Macro: AC_FUNC_OBSTACK
If the obstacks are found, define HAVE_OBSTACK, else require an AC_LIBOBJ replacement for `obstack'.

Macro: AC_FUNC_SELECT_ARGTYPES
Determines the correct type to be passed for each of the select function's arguments, and defines those types in SELECT_TYPE_ARG1, SELECT_TYPE_ARG234, and SELECT_TYPE_ARG5 respectively. SELECT_TYPE_ARG1 defaults to `int', SELECT_TYPE_ARG234 defaults to `int *', and SELECT_TYPE_ARG5 defaults to `struct timeval *'.

Macro: AC_FUNC_SETPGRP
If setpgrp takes no argument (the POSIX.1 version), define SETPGRP_VOID. Otherwise, it is the BSD version, which takes two process IDs as arguments. This macro does not check whether setpgrp exists at all; if you need to work in that situation, first call AC_CHECK_FUNC for setpgrp.

Macro: AC_FUNC_STAT
Macro: AC_FUNC_LSTAT
Determine whether stat or lstat have the bug that it succeeds when given the zero-length file name argument. The stat and lstat from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do this.

If it does, then define HAVE_STAT_EMPTY_STRING_BUG (or HAVE_LSTAT_EMPTY_STRING_BUG) and ask for an AC_LIBOBJ replacement of it.

Macro: AC_FUNC_SETVBUF_REVERSED
If setvbuf takes the buffering type as its second argument and the buffer pointer as the third, instead of the other way around, define SETVBUF_REVERSED.

Macro: AC_FUNC_STRCOLL
If the strcoll function exists and works correctly, define HAVE_STRCOLL. This does a bit more than `AC_CHECK_FUNCS(strcoll)', because some systems have incorrect definitions of strcoll that should not be used.

Macro: AC_FUNC_STRTOD
If the strtod function does not exist or doesn't work correctly, ask for an AC_LIBOBJ replacement of `strtod'. In this case, because `strtod.c' is likely to need `pow', set the output variable POW_LIB to the extra library needed.

Macro: AC_FUNC_STRERROR_R
If strerror_r is available, define HAVE_STRERROR_R. If its implementation correctly returns a char *, define HAVE_WORKING_STRERROR_R. On at least DEC UNIX 4.0[A-D] and HP-UX B.10.20, strerror_r returns int. Actually, this tests only whether it returns a scalar or an array, but that should be enough. This is used by the common `error.c'.

Macro: AC_FUNC_STRFTIME
Check for strftime in the `intl' library, for SCO UNIX. Then, if strftime is available, define HAVE_STRFTIME.

Macro: AC_FUNC_UTIME_NULL
If `utime(file, NULL)' sets file's timestamp to the present, define HAVE_UTIME_NULL.

Macro: AC_FUNC_VPRINTF
If vprintf is found, define HAVE_VPRINTF. Otherwise, if _doprnt is found, define HAVE_DOPRNT. (If vprintf is available, you may assume that vfprintf and vsprintf are also available.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.5.3 Generic Function Checks

These macros are used to find functions not covered by the "particular" test macros. If the functions might be in libraries other than the default C library, first call AC_CHECK_LIB for those libraries. If you need to check the behavior of a function as well as find out whether it is present, you have to write your own test for it (see section 6. Writing Tests).

Macro: AC_CHECK_FUNC (function, [action-if-found], [action-if-not-found])
If C function function is available, run shell commands action-if-found, otherwise action-if-not-found. If you just want to define a symbol if the function is available, consider using AC_CHECK_FUNCS instead. This macro checks for functions with C linkage even when AC_LANG(C++) has been called, since C is more standardized than C++. (see section 6.7 Language Choice, for more information about selecting the language for checks.)

Macro: AC_CHECK_FUNCS (function..., [action-if-found], [action-if-not-found])
For each function in the whitespace-separated argument list, define HAVE_function (in all capitals) if it is available. If action-if-found is given, it is additional shell code to execute when one of the functions is found. You can give it a value of `break' to break out of the loop on the first match. If action-if-not-found is given, it is executed when one of the functions is not found.

Autoconf follows a philosophy that was formed over the years by those who have struggled for portability: isolate the portability issues in specific files, and then program as if you were in a POSIX environment. Some functions may be missing or unfixable, and your package must be ready to replace them.

Use the first three of the following macros to specify a function to be replaced, and the last one (AC_REPLACE_FUNCS) to check for and replace the function if needed.

Macro: AC_LIBOBJ (function)
Specify that `function.c' must be included in the executables to replace a missing or broken implementation of function.

Technically, it adds `function.$ac_objext' to the output variable LIBOBJS and calls AC_LIBSOURCE for `function.c'. You should not directly change LIBOBJS, since this is not traceable.

Macro: AC_LIBSOURCE (file)
Specify that file might be needed to compile the project. If you need to know what files might be needed by a `configure.ac', you should trace AC_LIBSOURCE. file must be a literal.

This macro is called automatically from AC_LIBOBJ, but you must call it explicitly if you pass a shell variable to AC_LIBOBJ. In that case, since shell variables cannot be traced statically, you must pass to AC_LIBSOURCE any possible files that the shell variable might cause AC_LIBOBJ to need. For example, if you want to pass a variable $foo_or_bar to AC_LIBOBJ that holds either "foo" or "bar", you should do:

AC_LIBSOURCE(foo.c)
AC_LIBSOURCE(bar.c)
AC_LIBOBJ($foo_or_bar)

There is usually a way to avoid this, however, and you are encouraged to simply call AC_LIBOBJ with literal arguments.

Note that this macro replaces the obsolete AC_LIBOBJ_DECL, with slightly different semantics: the old macro took the function name, e.g. foo, as its argument rather than the file name.

Macro: AC_LIBSOURCES (files)
Like AC_LIBSOURCE, but accepts one or more files in a comma-separated M4 list. Thus, the above example might be rewritten:

AC_LIBSOURCES([foo.c, bar.c])
AC_LIBOBJ($foo_or_bar)

Macro: AC_REPLACE_FUNCS (function...)
Like AC_CHECK_FUNCS, but uses `AC_LIBOBJ(function)' as action-if-not-found. You can declare your replacement function by enclosing the prototype in `#if !HAVE_function'. If the system has the function, it probably declares it in a header file you should be including, so you shouldn't redeclare it lest your declaration conflict.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.6 Header Files

The following macros check for the presence of certain C header files. If there is no macro specifically defined to check for a header file you need, and you don't need to check for any special properties of it, then you can use one of the general header-file check macros.

5.6.1 Particular Header Checks | Special handling to find certain headers
5.6.2 Generic Header Checks | How to find other headers

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.6.1 Particular Header Checks

These macros check for particular system header files--whether they exist, and in some cases whether they declare certain symbols.

Macro: AC_HEADER_DIRENT
Check for the following header files. For the first one that is found and defines `DIR', define the listed C preprocessor macro:

`dirent.h' | HAVE_DIRENT_H
`sys/ndir.h' | HAVE_SYS_NDIR_H
`sys/dir.h' | HAVE_SYS_DIR_H
`ndir.h' | HAVE_NDIR_H

The directory-library declarations in your source code should look something like the following:

#if HAVE_DIRENT_H
# include <dirent.h>
# define NAMLEN(dirent) strlen((dirent)->d_name)
#else
# define dirent direct
# define NAMLEN(dirent) (dirent)->d_namlen
# if HAVE_SYS_NDIR_H
#  include <sys/ndir.h>
# endif
# if HAVE_SYS_DIR_H
#  include <sys/dir.h>
# endif
# if HAVE_NDIR_H
#  include <ndir.h>
# endif
#endif

Using the above declarations, the program would declare variables to be of type struct dirent, not struct direct, and would access the length of a directory entry name by passing a pointer to a struct dirent to the NAMLEN macro.

This macro also checks for the SCO Xenix `dir' and `x' libraries.

Macro: AC_HEADER_MAJOR
If `sys/types.h' does not define major, minor, and makedev, but `sys/mkdev.h' does, define MAJOR_IN_MKDEV; otherwise, if `sys/sysmacros.h' does, define MAJOR_IN_SYSMACROS.

Macro: AC_HEADER_STAT
If the macros S_ISDIR, S_ISREG et al. defined in `sys/stat.h' do not work properly (returning false positives), define STAT_MACROS_BROKEN. This is the case on Tektronix UTekV, Amdahl UTS and Motorola System V/88.

Macro: AC_HEADER_STDC
Define STDC_HEADERS if the system has ANSI C header files. Specifically, this macro checks for `stdlib.h', `stdarg.h', `string.h', and `float.h'; if the system has those, it probably has the rest of the ANSI C header files. This macro also checks whether `string.h' declares memchr (and thus presumably the other mem functions), whether `stdlib.h' declare free (and thus presumably malloc and other related functions), and whether the `ctype.h' macros work on characters with the high bit set, as ANSI C requires.

Use STDC_HEADERS instead of __STDC__ to determine whether the system has ANSI-compliant header files (and probably C library functions) because many systems that have GCC do not have ANSI C header files.

On systems without ANSI C headers, there is so much variation that it is probably easier to declare the functions you use than to figure out exactly what the system header files declare. Some systems contain a mix of functions ANSI and BSD; some are mostly ANSI but lack `memmove'; some define the BSD functions as macros in `string.h' or `strings.h'; some have only the BSD functions but `string.h'; some declare the memory functions in `memory.h', some in `string.h'; etc. It is probably sufficient to check for one string function and one memory function; if the library has the ANSI versions of those then it probably has most of the others. If you put the following in `configure.ac':

AC_HEADER_STDC
AC_CHECK_FUNCS(strchr memcpy)

then, in your code, you can put declarations like this:

#if STDC_HEADERS
# include <string.h>
#else
# if !HAVE_STRCHR
#  define strchr index
#  define strrchr rindex
# endif
char *strchr (), *strrchr ();
# if !HAVE_MEMCPY
#  define memcpy(d, s, n) bcopy ((s), (d), (n))
#  define memmove(d, s, n) bcopy ((s), (d), (n))
# endif
#endif

If you use a function like memchr, memset, strtok, or strspn, which have no BSD equivalent, then macros won't suffice; you must provide an implementation of each function. An easy way to incorporate your implementations only when needed (since the ones in system C libraries may be hand optimized) is to, taking memchr for example, put it in `memchr.c' and use `AC_REPLACE_FUNCS(memchr)'.

Macro: AC_HEADER_SYS_WAIT
If `sys/wait.h' exists and is compatible with POSIX.1, define HAVE_SYS_WAIT_H. Incompatibility can occur if `sys/wait.h' does not exist, or if it uses the old BSD union wait instead of int to store a status value. If `sys/wait.h' is not POSIX.1 compatible, then instead of including it, define the POSIX.1 macros with their usual interpretations. Here is an example:

#include <sys/types.h>
#if HAVE_SYS_WAIT_H
# include <sys/wait.h>
#endif
#ifndef WEXITSTATUS
# define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8)
#endif
#ifndef WIFEXITED
# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
#endif

_POSIX_VERSION is defined when `unistd.h' is included on POSIX.1 systems. If there is no `unistd.h', it is definitely not a POSIX.1 system. However, some non-POSIX.1 systems do have `unistd.h'.

The way to check if the system supports POSIX.1 is:

#if HAVE_UNISTD_H
# include <sys/types.h>
# include <unistd.h>
#endif

#ifdef _POSIX_VERSION
/* Code for POSIX.1 systems.  */
#endif

Macro: AC_HEADER_TIME
If a program may include both `time.h' and `sys/time.h', define TIME_WITH_SYS_TIME. On some older systems, `sys/time.h' includes `time.h', but `time.h' is not protected against multiple inclusion, so programs should not explicitly include both files. This macro is useful in programs that use, for example, struct timeval or struct timezone as well as struct tm. It is best used in conjunction with HAVE_SYS_TIME_H, which can be checked for using AC_CHECK_HEADERS(sys/time.h).

#if TIME_WITH_SYS_TIME
# include <sys/time.h>
# include <time.h>
#else
# if HAVE_SYS_TIME_H
#  include <sys/time.h>
# else
#  include <time.h>
# endif
#endif

Macro: AC_HEADER_TIOCGWINSZ
If the use of TIOCGWINSZ requires `<sys/ioctl.h>', then define GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can be found in `<termios.h>'.

Use:

#if HAVE_TERMIOS_H
# include <termios.h>
#endif

#if GWINSZ_IN_SYS_IOCTL
# include <sys/ioctl.h>
#endif

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.6.2 Generic Header Checks

These macros are used to find system header files not covered by the "particular" test macros. If you need to check the contents of a header as well as find out whether it is present, you have to write your own test for it (see section 6. Writing Tests).

Macro: AC_CHECK_HEADER (header-file, [action-if-found], [action-if-not-found], [includes])
If the system header file header-file is usable, execute shell commands action-if-found, otherwise execute action-if-not-found. If you just want to define a symbol if the header file is available, consider using AC_CHECK_HEADERS instead.

The meaning of "usable" depends upon the content of includes:

if includes is empty
check whether

header-file

can be preprocessed without error.

if include is set
Check whether

includes
#include <header-file>

can be compiled without error. You may use AC_CHECK_HEADER (and AC_CHECK_HEADERS) to check whether two headers are compatible.

You may pass any kind of dummy content for includes, such as a single space, a comment, to check whether header-file compiles with success.

Macro: AC_CHECK_HEADERS (header-file..., [action-if-found], [action-if-not-found], [includes])
For each given system header file header-file in the whitespace-separated argument list that exists, define HAVE_header-file (in all capitals). If action-if-found is given, it is additional shell code to execute when one of the header files is found. You can give it a value of `break' to break out of the loop on the first match. If action-if-not-found is given, it is executed when one of the header files is not found.

Be sure to read the documentation of AC_CHECK_HEADER to understand the influence of includes.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.7 Declarations

The following macros check for the declaration of variables and functions. If there is no macro specifically defined to check for a symbol you need, then you can use the general macros (see section 5.7.2 Generic Declaration Checks) or, for more complex tests, you may use AC_TRY_COMPILE (see section 6.2 Examining Syntax).

5.7.1 Particular Declaration Checks | Macros to check for certain declarations
5.7.2 Generic Declaration Checks | How to find other declarations

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.7.1 Particular Declaration Checks

The following macros check for certain declarations.

Macro: AC_DECL_SYS_SIGLIST
Define SYS_SIGLIST_DECLARED if the variable sys_siglist is declared in a system header file, either `signal.h' or `unistd.h'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.7.2 Generic Declaration Checks

These macros are used to find declarations not covered by the "particular" test macros.

Macro: AC_CHECK_DECL (symbol, [action-if-found], [action-if-not-found], [includes])
If symbol (a function or a variable) is not declared in includes and a declaration is needed, run the shell commands action-if-not-found, otherwise action-if-found. If no includes are specified, the default includes are used (see section 5.1.2 Default Includes).

This macro actually tests whether it is valid to use symbol as an r-value, not if it is really declared, because it is much safer to avoid introducing extra declarations when they are not needed.

Macro: AC_CHECK_DECLS (symbols, [action-if-found], [action-if-not-found], [includes])
For each of the symbols (comma-separated list), define HAVE_DECL_symbol (in all capitals) to `1' if symbol is declared, otherwise to `0'. If action-if-not-found is given, it is additional shell code to execute when one of the function declarations is needed, otherwise action-if-found is executed.

This macro uses an m4 list as first argument:
AC_CHECK_DECLS(strdup)
AC_CHECK_DECLS([strlen])
AC_CHECK_DECLS([malloc, realloc, calloc, free])

Unlike the other `AC_CHECK_*S' macros, when a symbol is not declared, HAVE_DECL_symbol is defined to `0' instead of leaving HAVE_DECL_symbol undeclared. When you are sure that the check was performed, use HAVE_DECL_symbol just like any other result of Autoconf:

#if !HAVE_DECL_SYMBOL
extern char *symbol;
#endif

If the test may have not been performed, however, because it is safer not to declare a symbol than to use a declaration that conflicts with the system's one, you should use:

#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
char *malloc (size_t *s);
#endif

You fall into the second category only in extreme situations: either your files may be used without being configured, or they are used during the configuration. In most cases the traditional approach is enough.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.8 Structures

The following macros check for the presence of certain members in C structures. If there is no macro specifically defined to check for a member you need, then you can use the general structure-member macro (see section 5.8.2 Generic Structure Checks) or, for more complex tests, you may use AC_TRY_COMPILE (see section 6.2 Examining Syntax).

5.8.1 Particular Structure Checks | Macros to check for certain structure members
5.8.2 Generic Structure Checks | How to find other structure members

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.8.1 Particular Structure Checks

The following macros check for certain structures or structure members.

Macro: AC_STRUCT_ST_BLKSIZE
If struct stat contains an st_blksize member, define HAVE_STRUCT_STAT_ST_BLKSIZE. The former name, HAVE_ST_BLKSIZE is to be avoided, as its support will cease in the future. This macro is obsoleted, and should be replaced by

AC_CHECK_MEMBERS([struct stat.st_blksize])

Macro: AC_STRUCT_ST_BLOCKS
If struct stat contains an st_blocks member, define HAVE_STRUCT STAT_ST_BLOCKS. Otherwise, require an AC_LIBOBJ replacement of `fileblocks'. The former name, HAVE_ST_BLOCKS is to be avoided, as its support will cease in the future.

Macro: AC_STRUCT_ST_RDEV
If struct stat contains an st_rdev member, define HAVE_STRUCT_STAT_ST_RDEV. The former name for this macro, HAVE_ST_RDEV, is to be avoided as it will cease to be supported in the future. Actually, even the new macro is obsolete, and should be replaced by:
AC_CHECK_MEMBERS([struct stat.st_rdev])

Macro: AC_STRUCT_TM
If `time.h' does not define struct tm, define TM_IN_SYS_TIME, which means that including `sys/time.h' had better define struct tm.

Macro: AC_STRUCT_TIMEZONE
Figure out how to get the current timezone. If struct tm has a tm_zone member, define HAVE_STRUCT_TM_TM_ZONE (and the obsoleted HAVE_TM_ZONE). Otherwise, if the external array tzname is found, define HAVE_TZNAME.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.8.2 Generic Structure Checks

These macros are used to find structure members not covered by the "particular" test macros.

Macro: AC_CHECK_MEMBER (aggregate.member, [action-if-found], [action-if-not-found], [includes])
Check whether member is a member of the aggregate aggregate. If no includes are specified, the default includes are used (see section 5.1.2 Default Includes).

AC_CHECK_MEMBER(struct passwd.pw_gecos,,
                [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
                [#include <pwd.h>])

You can use this macro for sub-members:

AC_CHECK_MEMBER(struct top.middle.bot)

Macro: AC_CHECK_MEMBERS (members, [action-if-found], [action-if-not-found], [includes])
Check for the existence of each `aggregate.member' of members using the previous macro. When member belongs to aggregate, define HAVE_aggregate_member (in all capitals, with spaces and dots replaced by underscores).

This macro uses m4 lists:
AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.9 Types

The following macros check for C types, either builtin or typedefs. If there is no macro specifically defined to check for a type you need, and you don't need to check for any special properties of it, then you can use a general type-check macro.

5.9.1 Particular Type Checks | Special handling to find certain types
5.9.2 Generic Type Checks | How to find other types

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.9.1 Particular Type Checks

These macros check for particular C types in `sys/types.h', `stdlib.h' and others, if they exist.

Macro: AC_TYPE_GETGROUPS
Define GETGROUPS_T to be whichever of gid_t or int is the base type of the array argument to getgroups.

Macro: AC_TYPE_MODE_T
Equivalent to `AC_CHECK_TYPE(mode_t, int)'.

Macro: AC_TYPE_OFF_T
Equivalent to `AC_CHECK_TYPE(off_t, long)'.

Macro: AC_TYPE_PID_T
Equivalent to `AC_CHECK_TYPE(pid_t, int)'.

Macro: AC_TYPE_SIGNAL
If `signal.h' declares signal as returning a pointer to a function returning void, define RETSIGTYPE to be void; otherwise, define it to be int.

Define signal handlers as returning type RETSIGTYPE:

RETSIGTYPE
hup_handler ()
{
...
}

Macro: AC_TYPE_SIZE_T
Equivalent to `AC_CHECK_TYPE(size_t, unsigned)'.

Macro: AC_TYPE_UID_T
If uid_t is not defined, define uid_t to be int and gid_t to be int.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.9.2 Generic Type Checks

These macros are used to check for types not covered by the "particular" test macros.

Macro: AC_CHECK_TYPE (type, [action-if-found], [action-if-not-found], [includes])
Check whether type is defined. It may be a compiler builtin type or defined by the [includes] (see section 5.1.2 Default Includes).

Macro: AC_CHECK_TYPES (types, [action-if-found], [action-if-not-found], [includes])
For each type of the types that is defined, define HAVE_type (in all capitals). If no includes are specified, the default includes are used (see section 5.1.2 Default Includes). If action-if-found is given, it is additional shell code to execute when one of the types is found. If action-if-not-found is given, it is executed when one of the types is not found.

This macro uses m4 lists:
AC_CHECK_TYPES(ptrdiff_t)
AC_CHECK_TYPES([unsigned long long, uintmax_t])

Autoconf, up to 2.13, used to provide to another version of AC_CHECK_TYPE, broken by design. In order to keep backward compatibility, a simple heuristics, quite safe but not totally, is implemented. In case of doubt, read the documentation of the former AC_CHECK_TYPE, see 15.4 Obsolete Macros.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.10 Compilers and Preprocessors

All the tests for compilers (AC_PROG_CC, AC_PROG_CXX, AC_PROG_F77) define the output variable EXEEXT based on the output of the compiler, typically to the empty string if Unix and `.exe' if Win32 or OS/2.

They also define the output variable OBJEXT based on the output of the compiler, after .c files have been excluded, typically to `o' if Unix, `obj' if Win32.

If the compiler being used does not produce executables, they fail. If the executables can't be run, and cross-compilation is not enabled, they fail too. See section 11. Manual Configuration, for more on support for cross compiling.

5.10.1 Generic Compiler Characteristics | Language independent tests
5.10.2 C Compiler Characteristics | Checking its characteristics
5.10.3 C++ Compiler Characteristics | Likewise
5.10.4 Fortran 77 Compiler Characteristics | Likewise

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.10.1 Generic Compiler Characteristics

Macro: AC_CHECK_SIZEOF (type, [unused], [includes])
Define SIZEOF_type (see section 5.1.1 Standard Symbols) to be the size in bytes of type. If `type' is unknown, it gets a size of 0. If no includes are specified, the default includes are used (see section 5.1.2 Default Includes). If you provide include, make sure to include `stdio.h' which is required for this macro to run.

This macro now works even when cross-compiling. The unused argument was used when cross-compiling.

For example, the call

AC_CHECK_SIZEOF(int *)

defines SIZEOF_INT_P to be 8 on DEC Alpha AXP systems.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.10.2 C Compiler Characteristics

Macro: AC_PROG_CC ([compiler-search-list])
Determine a C compiler to use. If CC is not already set in the environment, check for gcc and cc, then for other C compilers. Set output variable CC to the name of the compiler found.

This macro may, however, be invoked with an optional first argument which, if specified, must be a space separated list of C compilers to search for. This just gives the user an opportunity to specify an alternative search list for the C compiler. For example, if you didn't like the default order, then you could invoke AC_PROG_CC like this:

AC_PROG_CC(cl egcs gcc cc)

If using the GNU C compiler, set shell variable GCC to `yes'. If output variable CFLAGS was not already set, set it to `-g -O2' for the GNU C compiler (`-O2' on systems where GCC does not accept `-g'), or `-g' for other compilers.

Macro: AC_PROG_CC_C_O
If the C compiler does not accept the `-c' and `-o' options simultaneously, define NO_MINUS_C_MINUS_O. This macro actually tests both the compiler found by AC_PROG_CC, and, if different, the first cc in the path. The test fails if one fails. This macro was created for GNU Make to choose the default C compilation rule.

Macro: AC_PROG_CC_STDC
If the C compiler is not in ANSI C mode by default, try to add an option to output variable CC to make it so. This macro tries various options that select ANSI C on some system or another. It considers the compiler to be in ANSI C mode if it handles function prototypes correctly.

If you use this macro, you should check after calling it whether the C compiler has been set to accept ANSI C; if not, the shell variable ac_cv_prog_cc_stdc is set to `no'. If you wrote your source code in ANSI C, you can make an un-ANSIfied copy of it by using the program ansi2knr, which comes with Automake.

Macro: AC_PROG_CPP
Set output variable CPP to a command that runs the C preprocessor. If `$CC -E' doesn't work, `/lib/cpp' is used. It is only portable to run CPP on files with a `.c' extension.

If the current language is C (see section 6.7 Language Choice), many of the specific test macros use the value of CPP indirectly by calling AC_TRY_CPP, AC_CHECK_HEADER, AC_EGREP_HEADER, or AC_EGREP_CPP.

Some preprocessors don't indicate missing include files by the error status. For such preprocessors an internal variable is set that causes other macros to check the standard error from the preprocessor and consider the test failed if any warnings have been reported.

The following macros check for C compiler or machine architecture features. To check for characteristics not listed here, use AC_TRY_COMPILE (see section 6.2 Examining Syntax) or AC_TRY_RUN (see section 6.4 Checking Run Time Behavior)

Macro: AC_C_BIGENDIAN
If words are stored with the most significant byte first (like Motorola and SPARC, but not Intel and VAX, CPUs), define WORDS_BIGENDIAN.

Macro: AC_C_CONST
If the C compiler does not fully support the ANSI C qualifier const, define const to be empty. Some C compilers that do not define __STDC__ do support const; some compilers that define __STDC__ do not completely support const. Programs can simply use const as if every C compiler supported it; for those that don't, the `Makefile' or configuration header file will define it as empty.

Occasionally installers use a C++ compiler to compile C code, typically because they lack a C compiler. This causes problems with const, because C and C++ treat const differently. For example:

const int foo;

is valid in C but not in C++. These differences unfortunately cannot be papered over by defining const to be empty.

If autoconf detects this situation, it leaves const alone, as this generally yields better results in practice. However, using a C++ compiler to compile C code is not recommended or supported, and installers who run into trouble in this area should get a C compiler like GCC to compile their C code.

Macro: AC_C_VOLATILE
If the C compiler does not understand the keyword volatile, define volatile to be empty. Programs can simply use volatile as if every C compiler supported it; for those that do not, the `Makefile' or configuration header will define it as empty.

If the correctness of your program depends on the semantics of volatile, simply defining it to be empty does, in a sense, break your code. However, given that the compiler does not support volatile, you are at its mercy anyway. At least your program will compile, when it wouldn't before.

In general, the volatile keyword is a feature of ANSI C, so you might expect that volatile is available only when __STDC__ is defined. However, Ultrix 4.3's native compiler does support volatile, but does not defined __STDC__.

Macro: AC_C_INLINE
If the C compiler supports the keyword inline, do nothing. Otherwise define inline to __inline__ or __inline if it accepts one of those, otherwise define inline to be empty.

Macro: AC_C_CHAR_UNSIGNED
If the C type char is unsigned, define __CHAR_UNSIGNED__, unless the C compiler predefines it.

Macro: AC_C_LONG_DOUBLE
If the C compiler supports the long double type, define HAVE_LONG_DOUBLE. Some C compilers that do not define __STDC__ do support the long double type; some compilers that define __STDC__ do not support long double.

Macro: AC_C_STRINGIZE
If the C preprocessor supports the stringizing operator, define HAVE_STRINGIZE. The stringizing operator is `#' and is found in macros such as this:

#define x(y) #y

Macro: AC_C_PROTOTYPES
Check to see if function prototypes are understood by the compiler. If so, define `PROTOTYPES'. In the case the compiler does not handle prototypes, you should use ansi2knr, which comes with the Automake distribution, to unprotoize function definitions. For function prototypes, you should first define PARAMS:

#ifndef PARAMS
# if PROTOTYPES
#  define PARAMS(protos) protos
# else /* no PROTOTYPES */
#  define PARAMS(protos) ()
# endif /* no PROTOTYPES */
#endif

then use it this way:

size_t my_strlen PARAMS ((const char *));

Macro: AC_PROG_GCC_TRADITIONAL
Add `-traditional' to output variable CC if using the GNU C compiler and ioctl does not work properly without `-traditional'. That usually happens when the fixed header files have not been installed on an old system. Since recent versions of the GNU C compiler fix the header files automatically when installed, this is becoming a less prevalent problem.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.10.3 C++ Compiler Characteristics

Macro: AC_PROG_CXX ([compiler-search-list])
Determine a C++ compiler to use. Check if the environment variable CXX or CCC (in that order) is set; if so, then set output variable CXX to its value.

Otherwise, if the macro is invoked without an argument, then search for a C++ compiler under the likely names (first g++ and c++ then other names). If none of those checks succeed, then as a last resort set CXX to g++.

This macro may, however, be invoked with an optional first argument which, if specified, must be a space separated list of C++ compilers to search for. This just gives the user an opportunity to specify an alternative search list for the C++ compiler. For example, if you didn't like the default order, then you could invoke AC_PROG_CXX like this:

AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)

If using the GNU C++ compiler, set shell variable GXX to `yes'. If output variable CXXFLAGS was not already set, set it to `-g -O2' for the GNU C++ compiler (`-O2' on systems where G++ does not accept `-g'), or `-g' for other compilers.

Macro: AC_PROG_CXXCPP
Set output variable CXXCPP to a command that runs the C++ preprocessor. If `$CXX -E' doesn't work, `/lib/cpp' is used. It is only portable to run CXXCPP on files with a `.c', `.C', or `.cc' extension.

If the current language is C++ (see section 6.7 Language Choice), many of the specific test macros use the value of CXXCPP indirectly by calling AC_TRY_CPP, AC_CHECK_HEADER, AC_EGREP_HEADER, or AC_EGREP_CPP.

Some preprocessors don't indicate missing include files by the error status. For such preprocessors an internal variable is set that causes other macros to check the standard error from the preprocessor and consider the test failed if any warnings have been reported. However, it is not known whether such broken preprocessors exist for C++.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.10.4 Fortran 77 Compiler Characteristics

Macro: AC_PROG_F77 ([compiler-search-list])
Determine a Fortran 77 compiler to use. If F77 is not already set in the environment, then check for g77 and f77, and then some other names. Set the output variable F77 to the name of the compiler found.

This macro may, however, be invoked with an optional first argument which, if specified, must be a space separated list of Fortran 77 compilers to search for. This just gives the user an opportunity to specify an alternative search list for the Fortran 77 compiler. For example, if you didn't like the default order, then you could invoke AC_PROG_F77 like this:

AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90)

If using g77 (the GNU Fortran 77 compiler), then AC_PROG_F77 will set the shell variable G77 to `yes'. If the output variable FFLAGS was not already set in the environment, then set it to `-g -02' for g77 (or `-O2' where g77 does not accept `-g'). Otherwise, set FFLAGS to `-g' for all other Fortran 77 compilers.

Macro: AC_PROG_F77_C_O
Test if the Fortran 77 compiler accepts the options `-c' and `-o' simultaneously, and define F77_NO_MINUS_C_MINUS_O if it does not.

The following macros check for Fortran 77 compiler characteristics. To check for characteristics not listed here, use AC_TRY_COMPILE (see section 6.2 Examining Syntax) or AC_TRY_RUN (see section 6.4 Checking Run Time Behavior), making sure to first set the current language to Fortran 77 AC_LANG(Fortran 77) (see section 6.7 Language Choice).

Macro: AC_F77_LIBRARY_LDFLAGS
Determine the linker flags (e.g. `-L' and `-l') for the Fortran 77 intrinsic and run-time libraries that are required to successfully link a Fortran 77 program or shared library. The output variable FLIBS is set to these flags.

This macro is intended to be used in those situations when it is necessary to mix, e.g. C++ and Fortran 77 source code into a single program or shared library (see section `Mixing Fortran 77 With C and C++' in GNU Automake).

For example, if object files from a C++ and Fortran 77 compiler must be linked together, then the C++ compiler/linker must be used for linking (since special C++-ish things need to happen at link time like calling global constructors, instantiating templates, enabling exception support, etc.).

However, the Fortran 77 intrinsic and run-time libraries must be linked in as well, but the C++ compiler/linker doesn't know by default how to add these Fortran 77 libraries. Hence, the macro AC_F77_LIBRARY_LDFLAGS was created to determine these Fortran 77 libraries.

The macro AC_F77_DUMMY_MAIN or AC_F77_MAIN will probably also be necessary to link C/C++ with Fortran; see below.

Macro: AC_F77_DUMMY_MAIN ([action-if-found], [action-if-not-found])
With many compilers, the Fortran libraries detected by AC_F77_LIBRARY_LDFLAGS provide their own main entry function that initializes things like Fortran I/O, and which then calls a user-provided entry function named e.g. MAIN__ to run the user's program. The AC_F77_DUMMY_MAIN or AC_F77_MAIN macro figures out how to deal with this interaction.

When using Fortran for purely numerical functions (no I/O, etcetera), users often prefer to provide their own main and skip the Fortran library initializations. In this case, however, one may still need to provide a dummy MAIN__ routine in order to prevent linking errors on some systems. AC_F77_DUMMY_MAIN detects whether any such routine is required for linking, and what its name is; the shell variable F77_DUMMY_MAIN holds this name, unknown when no solution was found, and none when no such dummy main is needed.

By default, action-if-found defines F77_DUMMY_MAIN to the name of this routine (e.g. MAIN__) if it is required. [action-if-not-found] defaults to exiting with an error.

In order to link with Fortran routines, the user's C/C++ program should then include the following code to define the dummy main if it is needed:

#ifdef F77_DUMMY_MAIN
#  ifdef __cplusplus
     extern "C"
#  endif
   int F77_DUMMY_MAIN() { return 1; }
#endif

Note that AC_F77_DUMMY_MAIN is called automatically from AC_F77_WRAPPERS; there is generally no need to call it explicitly unless one wants to change the default actions.

Macro: AC_F77_MAIN
As discussed above for AC_F77_DUMMY_MAIN, many Fortran libraries allow you to provide an entry point called e.g. MAIN__ instead of the usual main, which is then called by a main function in the Fortran libraries that initializes things like Fortran I/O. The AC_F77_MAIN macro detects whether it is possible to utilize such an alternate main function, and defines F77_MAIN to the name of the function. (If no alternate main function name is found, F77_MAIN is simply defined to main.)

Thus, when calling Fortran routines from C that perform things like I/O, one should use this macro and name the "main" function F77_MAIN instead of main.

Macro: AC_F77_WRAPPERS
Defines C macros F77_FUNC(name,NAME) and F77_FUNC_(name,NAME) to properly mangle the names of C/C++ identifiers, and identifiers with underscores, respectively, so that they match the name-mangling scheme used by the Fortran 77 compiler.

Fortran 77 is case-insensitive, and in order to achieve this the Fortran 77 compiler converts all identifiers into a canonical case and format. To call a Fortran 77 subroutine from C or to write a C function that is callable from Fortran 77, the C program must explicitly use identifiers in the format expected by the Fortran 77 compiler. In order to do this, one simply wraps all C identifiers in one of the macros provided by AC_F77_WRAPPERS. For example, suppose you have the following Fortran 77 subroutine:

      subroutine foobar(x,y)
      double precision x, y
      y = 3.14159 * x
      return
      end

You would then declare its prototype in C or C++ as:

#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
#ifdef __cplusplus
extern "C"  /* prevent C++ name mangling */
#endif
void FOOBAR_F77(double *x, double *y);

Note that we pass both the lowercase and uppercase versions of the function name to F77_FUNC so that it can select the right one. Note also that all parameters to Fortran 77 routines are passed as pointers (see section `Mixing Fortran 77 With C and C++' in GNU Automake).

Although Autoconf tries to be intelligent about detecting the name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77 compilers that it doesn't support yet. In this case, the above code will generate a compile-time error, but some other behavior (e.g. disabling Fortran-related features) can be induced by checking whether the F77_FUNC macro is defined.

Now, to call that routine from a C program, we would do something like:

{
    double x = 2.7183, y;
    FOOBAR_F77(&x, &y);
}

If the Fortran 77 identifier contains an underscore (e.g. foo_bar), you should use F77_FUNC_ instead of F77_FUNC (with the same arguments). This is because some Fortran 77 compilers mangle names differently if they contain an underscore.

Macro: AC_F77_FUNC (name, [shellvar])
Given an identifier name, set the shell variable shellvar to hold the mangled version name according to the rules of the Fortran 77 linker (see also AC_F77_WRAPPERS). shellvar is optional; if it is not supplied, the shell variable will be simply name. The purpose of this macro is to give the caller a way to access the name-mangling information other than through the C preprocessor as above; for example, to call Fortran routines from some language other than C/C++.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.11 System Services

The following macros check for operating system services or capabilities.

Macro: AC_PATH_X
Try to locate the X Window System include files and libraries. If the user gave the command line options `--x-includes=dir' and `--x-libraries=dir', use those directories. If either or both were not given, get the missing values by running xmkmf on a trivial `Imakefile' and examining the `Makefile' that it produces. If that fails (such as if xmkmf is not present), look for them in several directories where they often reside. If either method is successful, set the shell variables x_includes and x_libraries to their locations, unless they are in directories the compiler searches by default.

If both methods fail, or the user gave the command line option `--without-x', set the shell variable no_x to `yes'; otherwise set it to the empty string.

Macro: AC_PATH_XTRA
An enhanced version of AC_PATH_X. It adds the C compiler flags that X needs to output variable X_CFLAGS, and the X linker flags to X_LIBS. Define X_DISPLAY_MISSING if X is not available.

This macro also checks for special libraries that some systems need in order to compile X programs. It adds any that the system needs to output variable X_EXTRA_LIBS. And it checks for special X11R6 libraries that need to be linked with before `-lX11', and adds any found to the output variable X_PRE_LIBS.

Macro: AC_SYS_INTERPRETER
Check whether the system supports starting scripts with a line of the form `#! /bin/csh' to select the interpreter to use for the script. After running this macro, shell code in configure.ac can check the shell variable interpval; it will be set to `yes' if the system supports `#!', `no' if not.

Macro: AC_SYS_LARGEFILE
Arrange for \title\{http://www.sas.com/standards/large.file/x_open.20Mar96.html, large-file support}. On some hosts, one must use special compiler options to build programs that can access large files. Append any such options to the output variable CC. Define _FILE_OFFSET_BITS and _LARGE_FILES if necessary.

Large-file support can be disabled by configuring with the `--disable-largefile' option.

If you use this macro, check that your program works even when off_t is longer than long, since this is common when large-file support is enabled. For example, it is not correct to print an arbitrary off_t value X with printf ("%ld", (long) X).

Macro: AC_SYS_LONG_FILE_NAMES
If the system supports file names longer than 14 characters, define HAVE_LONG_FILE_NAMES.

Macro: AC_SYS_POSIX_TERMIOS
Check to see if POSIX termios headers and functions are available on the system. If so, set the shell variable am_cv_sys_posix_termios to `yes'. If not, set the variable to `no'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.12 UNIX Variants

The following macros check for certain operating systems that need special treatment for some programs, due to exceptional oddities in their header files or libraries. These macros are warts; they will be replaced by a more systematic approach, based on the functions they make available or the environments they provide.

Macro: AC_AIX
If on AIX, define _ALL_SOURCE. Allows the use of some BSD functions. Should be called before any macros that run the C compiler.

Macro: AC_ISC_POSIX
If on a POSIXized ISC UNIX, define _POSIX_SOURCE and add `-posix' (for the GNU C compiler) or `-Xp' (for other C compilers) to output variable CC. This allows the use of POSIX facilities. Must be called after AC_PROG_CC and before any other macros that run the C compiler.

Macro: AC_MINIX
If on Minix, define _MINIX and _POSIX_SOURCE and define _POSIX_1_SOURCE to be 2. This allows the use of POSIX facilities. Should be called before any macros that run the C compiler.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Writing Tests

If the existing feature tests don't do something you need, you have to write new ones. These macros are the building blocks. They provide ways for other macros to check whether various kinds of features are available and report the results.

This chapter contains some suggestions and some of the reasons why the existing tests are written the way they are. You can also learn a lot about how to write Autoconf tests by looking at the existing ones. If something goes wrong in one or more of the Autoconf tests, this information can help you understand the assumptions behind them, which might help you figure out how to best solve the problem.

These macros check the output of the C compiler system. They do not cache the results of their tests for future use (see section 7.3 Caching Results), because they don't know enough about the information they are checking for to generate a cache variable name. They also do not print any messages, for the same reason. The checks for particular kinds of C features call these macros and do cache their results and print messages about what they're checking for.

When you write a feature test that could be applicable to more than one software package, the best thing to do is encapsulate it in a new macro. See section 9. Writing Autoconf Macros, for how to do that.

6.1 Examining Declarations | Detecting header files and declarations
6.2 Examining Syntax | Detecting language syntax features
6.3 Examining Libraries | Detecting functions and global variables
6.4 Checking Run Time Behavior | Testing for run-time features
6.5 Systemology | A zoology of operating systems
6.6 Multiple Cases | Tests for several possible values
6.7 Language Choice | Selecting which language to use for testing

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1 Examining Declarations

The macro AC_TRY_CPP is used to check whether particular header files exist. You can check for one at a time, or more than one if you need several header files to all exist for some purpose.

Macro: AC_TRY_CPP (includes, [action-if-true], [action-if-false])
includes is C or C++ #include statements and declarations, on which shell variable, back quote, and backslash substitutions are performed. (Actually, it can be any C program, but other statements are probably not useful.) If the preprocessor produces no error messages while processing it, run shell commands action-if-true. Otherwise run shell commands action-if-false.

This macro uses CPPFLAGS, but not CFLAGS, because `-g', `-O', etc. are not valid options to many C preprocessors.

Here is how to find out whether a header file contains a particular declaration, such as a typedef, a structure, a structure member, or a function. Use AC_EGREP_HEADER instead of running grep directly on the header file; on some systems the symbol might be defined in another header file that the file you are checking `#include's.

Macro: AC_EGREP_HEADER (pattern, header-file, action-if-found, [action-if-not-found])
If the output of running the preprocessor on the system header file header-file matches the egrep regular expression pattern, execute shell commands action-if-found, otherwise execute action-if-not-found.

To check for C preprocessor symbols, either defined by header files or predefined by the C preprocessor, use AC_EGREP_CPP. Here is an example of the latter:

AC_EGREP_CPP(yes,
[#ifdef _AIX
  yes
#endif
], is_aix=yes, is_aix=no)

Macro: AC_EGREP_CPP (pattern, program, [action-if-found], [action-if-not-found])
program is the text of a C or C++ program, on which shell variable, back quote, and backslash substitutions are performed. If the output of running the preprocessor on program matches the egrep regular expression pattern, execute shell commands action-if-found, otherwise execute action-if-not-found.

This macro calls AC_PROG_CPP or AC_PROG_CXXCPP (depending on which language is current, see section 6.7 Language Choice), if it hasn't been called already.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.2 Examining Syntax

To check for a syntax feature of the C, C++ or Fortran 77 compiler, such as whether it recognizes a certain keyword, use AC_TRY_COMPILE to try to compile a small program that uses that feature. You can also use it to check for structures and structure members that are not present on all systems.

Macro: AC_TRY_COMPILE (includes, function-body, [action-if-found], [action-if-not-found])
Create a C, C++ or Fortran 77 test program (depending on which language is current, see section 6.7 Language Choice), to see whether a function whose body consists of function-body can be compiled.

For C and C++, includes is any #include statements needed by the code in function-body (includes will be ignored if the currently selected language is Fortran 77). This macro also uses CFLAGS or CXXFLAGS if either C or C++ is the currently selected language, as well as CPPFLAGS, when compiling. If Fortran 77 is the currently selected language then FFLAGS will be used when compiling.

If the file compiles successfully, run shell commands action-if-found, otherwise run action-if-not-found.

This macro does not try to link; use AC_TRY_LINK if you need to do that (see section 6.3 Examining Libraries).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3 Examining Libraries

To check for a library, a function, or a global variable, Autoconf configure scripts try to compile and link a small program that uses it. This is unlike Metaconfig, which by default uses nm or ar on the C library to try to figure out which functions are available. Trying to link with the function is usually a more reliable approach because it avoids dealing with the variations in the options and output formats of nm and ar and in the location of the standard libraries. It also allows configuring for cross-compilation or checking a function's runtime behavior if needed. On the other hand, it can be slower than scanning the libraries once.

A few systems have linkers that do not return a failure exit status when there are unresolved functions in the link. This bug makes the configuration scripts produced by Autoconf unusable on those systems. However, some of them can be given options that make the exit status correct. This is a problem that Autoconf does not currently handle automatically. If users encounter this problem, they might be able to solve it by setting LDFLAGS in the environment to pass whatever options the linker needs (for example, `-Wl,-dn' on MIPS RISC/OS).

AC_TRY_LINK is used to compile test programs to test for functions and global variables. It is also used by AC_CHECK_LIB to check for libraries (see section 5.4 Library Files), by adding the library being checked for to LIBS temporarily and trying to link a small program.

Macro: AC_TRY_LINK (includes, function-body, [action-if-found], [action-if-not-found])
Depending on the current language (see section 6.7 Language Choice), create a test program to see whether a function whose body consists of function-body can be compiled and linked.

For C and C++, includes is any #include statements needed by the code in function-body (includes will be ignored if the currently selected language is Fortran 77). This macro also uses CFLAGS or CXXFLAGS if either C or C++ is the currently selected language, as well as CPPFLAGS, when compiling. If Fortran 77 is the currently selected language then FFLAGS will be used when compiling. However, both LDFLAGS and LIBS will be used during linking in all cases.

If the file compiles and links successfully, run shell commands action-if-found, otherwise run action-if-not-found.

Macro: AC_TRY_LINK_FUNC (function, [action-if-found], [action-if-not-found])
Depending on the current language (see section 6.7 Language Choice), create a test program to see whether a program whose body consists of a prototype of and a call to function can be compiled and linked.

If the file compiles and links successfully, run shell commands action-if-found, otherwise run action-if-not-found.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4 Checking Run Time Behavior

Sometimes you need to find out how a system performs at run time, such as whether a given function has a certain capability or bug. If you can, make such checks when your program runs instead of when it is configured. You can check for things like the machine's endianness when your program initializes itself.

If you really need to test for a run-time behavior while configuring, you can write a test program to determine the result, and compile and run it using AC_TRY_RUN. Avoid running test programs if possible, because this prevents people from configuring your package for cross-compiling.

6.4.1 Running Test Programs | Running test programs
6.4.2 Guidelines for Test Programs | General rules for writing test programs
6.4.3 Test Functions | Avoiding pitfalls in test programs

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4.1 Running Test Programs

Use the following macro if you need to test run-time behavior of the system while configuring.

Macro: AC_TRY_RUN (program, [action-if-true], [action-if-false], [action-if-cross-compiling])
program is the text of a C program, on which shell variable and back quote substitutions are performed. If it compiles and links successfully and returns an exit status of 0 when executed, run shell commands action-if-true. Otherwise, run shell commands action-if-false; the exit status of the program is available in the shell variable `$?'. This macro uses CFLAGS or CXXFLAGS, CPPFLAGS, LDFLAGS, and LIBS when compiling.

If the C compiler being used does not produce executables that run on the system where configure is being run, then the test program is not run. If the optional shell commands action-if-cross-compiling are given, they are run instead. Otherwise, configure prints an error message and exits.

Try to provide a pessimistic default value to use when cross-compiling makes run-time tests impossible. You do this by passing the optional last argument to AC_TRY_RUN. autoconf prints a warning message when creating configure each time it encounters a call to AC_TRY_RUN with no action-if-cross-compiling argument given. You may ignore the warning, though users will not be able to configure your package for cross-compiling. A few of the macros distributed with Autoconf produce this warning message.

To configure for cross-compiling you can also choose a value for those parameters based on the canonical system name (see section 11. Manual Configuration). Alternatively, set up a test results cache file with the correct values for the host system (see section 7.3 Caching Results).

To provide a default for calls of AC_TRY_RUN that are embedded in other macros, including a few of the ones that come with Autoconf, you can call AC_PROG_CC before running them. Then, if the shell variable cross_compiling is set to `yes', use an alternate method to get the results instead of calling the macros.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4.2 Guidelines for Test Programs

Test programs should not write anything to the standard output. They should return 0 if the test succeeds, nonzero otherwise, so that success can be distinguished easily from a core dump or other failure; segmentation violations and other failures produce a nonzero exit status. Test programs should exit, not return, from main, because on some systems (old Suns, at least) the argument to return in main is ignored.

Test programs can use #if or #ifdef to check the values of preprocessor macros defined by tests that have already run. For example, if you call AC_HEADER_STDC, then later on in `configure.ac' you can have a test program that includes an ANSI C header file conditionally:

#if STDC_HEADERS
# include <stdlib.h>
#endif

If a test program needs to use or create a data file, give it a name that starts with `conftest', such as `conftest.data'. The configure script cleans up by running `rm -rf conftest*' after running test programs and if the script is interrupted.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4.3 Test Functions

Function declarations in test programs should have a prototype conditionalized for C++. In practice, though, test programs rarely need functions that take arguments.

#ifdef __cplusplus
foo (int i)
#else
foo (i) int i;
#endif

Functions that test programs declare should also be conditionalized for C++, which requires `extern "C"' prototypes. Make sure to not include any header files containing clashing prototypes.

#ifdef __cplusplus
extern "C" void *malloc (size_t);
#else
char *malloc ();
#endif

If a test program calls a function with invalid parameters (just to see whether it exists), organize the program to ensure that it never invokes that function. You can do this by calling it in another function that is never invoked. You can't do it by putting it after a call to exit, because GCC version 2 knows that exit never returns and optimizes out any code that follows it in the same block.

If you include any header files, make sure to call the functions relevant to them with the correct number of arguments, even if they are just 0, to avoid compilation errors due to prototypes. GCC version 2 has internal prototypes for several functions that it automatically inlines; for example, memcpy. To avoid errors when checking for them, either pass them the correct number of arguments or redeclare them with a different return type (such as char).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.5 Systemology

This section aims at presenting some systems and pointers to documentation. It may help you addressing particular problems reported by users.

QNX 4.25
QNX is a realtime operating system running on Intel architecture meant to be scalable from the small embedded systems to hundred processor super-computer. It claims to be POSIX certified. More information is available on the QNX home page, including the QNX man pages.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.6 Multiple Cases

Some operations are accomplished in several possible ways, depending on the UNIX variant. Checking for them essentially requires a "case statement". Autoconf does not directly provide one; however, it is easy to simulate by using a shell variable to keep track of whether a way to perform the operation has been found yet.

Here is an example that uses the shell variable fstype to keep track of whether the remaining cases need to be checked.

AC_MSG_CHECKING([how to get file system type])
fstype=no
# The order of these tests is important.
AC_TRY_CPP([#include <sys/statvfs.h>
#include <sys/fstyp.h>],
           [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
if test $fstype = no; then
  AC_TRY_CPP([#include <sys/statfs.h>
#include <sys/fstyp.h>],
             [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
fi
if test $fstype = no; then
  AC_TRY_CPP([#include <sys/statfs.h>
#include <sys/vmount.h>],
             [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
fi
# (more cases omitted here)
AC_MSG_RESULT([$fstype])

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.7 Language Choice

Autoconf-generated configure scripts check for the C compiler and its features by default. Packages that use other programming languages (maybe more than one, e.g. C and C++) need to test features of the compilers for the respective languages. The following macros determine which programming language is used in the subsequent tests in `configure.ac'.

Macro: AC_LANG (language)
Do compilation tests using the compiler, preprocessor and file extensions for the specified language.

Supported languages are:

`C'
Do compilation tests using CC and CPP and use extension `.c' for test programs.

`C++'
Do compilation tests using CXX and CXXCPP and use extension `.C' for test programs.

`Fortran 77'
Do compilation tests using F77 and use extension `.f' for test programs.

Macro: AC_LANG_PUSH (language)
Remember the current language (as set by AC_LANG) on a stack, and then select the language. Use this macro and AC_LANG_POP in macros that need to temporarily switch to a particular language.

Macro: AC_LANG_POP ([language])
Select the language that is saved on the top of the stack, as set by AC_LANG_PUSH, and remove it from the stack.

If given, language specifies the language we just quit. It is a good idea to specify it when it's known (which should be the case...), since Autoconf will detect inconsistencies.

AC_LANG_PUSH(Fortran 77)
# Perform some tests on Fortran 77.
# ...
AC_LANG_POP(Fortran 77)

Macro: AC_REQUIRE_CPP
Ensure that whichever preprocessor would currently be used for tests has been found. Calls AC_REQUIRE (see section 9.4.1 Prerequisite Macros) with an argument of either AC_PROG_CPP or AC_PROG_CXXCPP, depending on which language is current.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. Results of Tests

Once configure has determined whether a feature exists, what can it do to record that information? There are four sorts of things it can do: define a C preprocessor symbol, set a variable in the output files, save the result in a cache file for future configure runs, and print a message letting the user know the result of the test.

7.1 Defining C Preprocessor Symbols | Defining C preprocessor symbols
7.2 Setting Output Variables | Replacing variables in output files
7.3 Caching Results | Speeding up subsequent configure runs
7.4 Printing Messages | Notifying configure users

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1 Defining C Preprocessor Symbols

A common action to take in response to a feature test is to define a C preprocessor symbol indicating the results of the test. That is done by calling AC_DEFINE or AC_DEFINE_UNQUOTED.

By default, AC_OUTPUT places the symbols defined by these macros into the output variable DEFS, which contains an option `-Dsymbol=value' for each symbol defined. Unlike in Autoconf version 1, there is no variable DEFS defined while configure is running. To check whether Autoconf macros have already defined a certain C preprocessor symbol, test the value of the appropriate cache variable, as in this example:

AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
if test "$ac_cv_func_vprintf" != yes; then
  AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
fi

If AC_CONFIG_HEADERS has been called, then instead of creating DEFS, AC_OUTPUT creates a header file by substituting the correct values into #define statements in a template file. See section 4.7 Configuration Header Files, for more information about this kind of output.

Macro: AC_DEFINE (variable, [value], [description])
Define C preprocessor variable variable. If value is given, set variable to that value (verbatim), otherwise set it to 1. value should not contain literal newlines, and if you are not using AC_CONFIG_HEADERS it should not contain any `#' characters, as make tends to eat them. To use a shell variable (which you need to do in order to define a value containing the M4 quote characters `[' or `]'), use AC_DEFINE_UNQUOTED instead. description is only useful if you are using AC_CONFIG_HEADERS. In this case, description is put into the generated `config.h.in' as the comment before the macro define. The following example defines the C preprocessor variable EQUATION to be the string constant `"$a > $b"':

AC_DEFINE(EQUATION, "$a > $b")

Macro: AC_DEFINE_UNQUOTED (variable, [value], [description])
Like AC_DEFINE, but three shell expansions are performed--once--on variable and value: variable expansion (`$'), command substitution (``'), and backslash escaping (`\'). Single and double quote characters in the value have no special meaning. Use this macro instead of AC_DEFINE when variable or value is a shell variable. Examples:

AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
AC_DEFINE_UNQUOTED($ac_tr_hdr)

Due to the syntactical bizarreness of the Bourne shell, do not use semicolons to separate AC_DEFINE or AC_DEFINE_UNQUOTED calls from other macro calls or shell code; that can cause syntax errors in the resulting configure script. Use either spaces or newlines. That is, do this:

AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])

or this:

AC_CHECK_HEADER(elf.h,
 [AC_DEFINE(SVR4)
  LIBS="$LIBS -lelf"])

instead of this:

AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2 Setting Output Variables

Another way to record the results of tests is to set output variables, which are shell variables whose values are substituted into files that configure outputs. The two macros below create new output variables. See section 4.6.1 Preset Output Variables, for a list of output variables that are always available.

Macro: AC_SUBST (variable, [value])
Create an output variable from a shell variable. Make AC_OUTPUT substitute the variable variable into output files (typically one or more `Makefile's). This means that AC_OUTPUT will replace instances of `@variable@' in input files with the value that the shell variable variable has when AC_OUTPUT is called. This value of variable should not contain literal newlines.

If value is given, in addition assign it to `variable'.

Macro: AC_SUBST_FILE (variable)
Another way to create an output variable from a shell variable. Make AC_OUTPUT insert (without substitutions) the contents of the file named by shell variable variable into output files. This means that AC_OUTPUT will replace instances of `@variable@' in output files (such as `Makefile.in') with the contents of the file that the shell variable variable names when AC_OUTPUT is called. Set the variable to `/dev/null' for cases that do not have a file to insert.

This macro is useful for inserting `Makefile' fragments containing special dependencies or other make directives for particular host or target types into `Makefile's. For example, `configure.ac' could contain:

AC_SUBST_FILE(host_frag)
host_frag=$srcdir/conf/sun4.mh

and then a `Makefile.in' could contain:

@host_frag@

Running configure in different environments can be extremely dangerous. If for instance the user runs `CC=bizarre-cc ./configure', then the cache, `config.h' and many other output files will depend upon bizarre-cc being the C compiler. If for some reason the user runs /configure again, or if it is run via `./config.status --recheck', (See section 4.6.4 Automatic Remaking, and see section 14. Recreating a Configuration), then the configuration can be inconsistent, composed of results depending upon two different compilers.

Such variables are named precious variables, and can be declared as such by AC_ARG_VAR.

Macro: AC_ARG_VAR (variable, description)
Declare variable is a precious variable, and include its description in the variable section of `./configure --help'.

Being precious means that

  • variable is AC_SUBST'd.

  • variable is kept in the cache including if it was not specified on the `./configure' command line. Indeed, while configure can notice the definition of CC in `./configure CC=bizarre-cc', it is impossible to notice it in `CC=bizarre-cc ./configure', which, unfortunately, is what most users do.

  • variable is checked for consistency between two configure runs. For instance:

    $ ./configure --silent --config-cache
$ CC=cc ./configure --silent --config-cache
configure: error: `CC' was not set in the previous run
configure: error: changes in the environment can compromise \
the build
configure: error: run `make distclean' and/or \
`rm config.cache' and start over

    and similarly if the variable is unset, or if its content is changed.

  • variable is kept during automatic reconfiguration (see section 14. Recreating a Configuration) as if it had been passed as a command line argument, including when no cache is used:

    $ CC=/usr/bin/cc ./configure undeclared_var=raboof --silent
$ ./config.status --recheck
running /bin/sh ./configure undeclared_var=raboof --silent \
  CC=/usr/bin/cc  --no-create --no-recursion

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3 Caching Results

To avoid checking for the same features repeatedly in various configure scripts (or in repeated runs of one script), configure can optionally save the results of many checks in a cache file (see section 7.3.2 Cache Files). If a configure script runs with caching enabled and finds a cache file, it reads the results of previous runs from the cache and avoids rerunning those checks. As a result, configure can then run much faster than if it had to perform all of the checks every time.

Macro: AC_CACHE_VAL (cache-id, commands-to-set-it)
Ensure that the results of the check identified by cache-id are available. If the results of the check were in the cache file that was read, and configure was not given the `--quiet' or `--silent' option, print a message saying that the result was cached; otherwise, run the shell commands commands-to-set-it. If the shell commands are run to determine the value, the value will be saved in the cache file just before configure creates its output files. See section 7.3.1 Cache Variable Names, for how to choose the name of the cache-id variable.

The commands-to-set-it must have no side effects except for setting the variable cache-id, see below.

Macro: AC_CACHE_CHECK (message, cache-id, commands-to-set-it)
A wrapper for AC_CACHE_VAL that takes care of printing the messages. This macro provides a convenient shorthand for the most common way to use these macros. It calls AC_MSG_CHECKING for message, then AC_CACHE_VAL with the cache-id and commands arguments, and AC_MSG_RESULT with cache-id.

The commands-to-set-it must have no side effects except for setting the variable cache-id, see below.

It is very common to find buggy macros using AC_CACHE_VAL or AC_CACHE_CHECK, because people are tempted to call AC_DEFINE in the commands-to-set-it. Instead, the code that follows the call to AC_CACHE_VAL should call AC_DEFINE, by examining the value of the cache variable. For instance, the following macro is broken:

AC_DEFUN([AC_SHELL_TRUE],
[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
                [ac_cv_shell_true_works=no
                 true && ac_cv_shell_true_works=yes
                 if test $ac_cv_shell_true_works = yes; then
                   AC_DEFINE([TRUE_WORKS], 1
                             [Define if `true(1)' works properly.])
                 fi])
])

This fails if the cache is enabled: the second time this macro is run, TRUE_WORKS will not be defined. The proper implementation is:

AC_DEFUN([AC_SHELL_TRUE],
[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
                [ac_cv_shell_true_works=no
                 true && ac_cv_shell_true_works=yes])
 if test $ac_cv_shell_true_works = yes; then
   AC_DEFINE([TRUE_WORKS], 1
             [Define if `true(1)' works properly.])
 fi
])

Also, commands-to-set-it should not print any messages, for example with AC_MSG_CHECKING; do that before calling AC_CACHE_VAL, so the messages are printed regardless of whether the results of the check are retrieved from the cache or determined by running the shell commands.

7.3.1 Cache Variable Names | Shell variables used in caches
7.3.2 Cache Files | Files configure uses for caching
7.3.3 Cache Checkpointing | Loading and saving the cache file

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3.1 Cache Variable Names

The names of cache variables should have the following format:

package-prefix_cv_value-type_specific-value_[additional-options]

for example, `ac_cv_header_stat_broken' or `ac_cv_prog_gcc_traditional'. The parts of the variable name are:

package-prefix
An abbreviation for your package or organization; the same prefix you begin local Autoconf macros with, except lowercase by convention. For cache values used by the distributed Autoconf macros, this value is `ac'.

_cv_
Indicates that this shell variable is a cache value. This string must be present in the variable name, including the leading underscore.

value-type
A convention for classifying cache values, to produce a rational naming system. The values used in Autoconf are listed in 9.2 Macro Names.

specific-value
Which member of the class of cache values this test applies to. For example, which function (`alloca'), program (`gcc'), or output variable (`INSTALL').

additional-options
Any particular behavior of the specific member that this test applies to. For example, `broken' or `set'. This part of the name may be omitted if it does not apply.

The values assigned to cache variables may not contain newlines. Usually, their values will be boolean (`yes' or `no') or the names of files or functions; so this is not an important restriction.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3.2 Cache Files

A cache file is a shell script that caches the results of configure tests run on one system so they can be shared between configure scripts and configure runs. It is not useful on other systems. If its contents are invalid for some reason, the user may delete or edit it.

By default, configure uses no cache file (technically, it uses `--cache-file=/dev/null'), to avoid problems caused by accidental use of stale cache files.

To enable caching, configure accepts `--config-cache' (or `-C') to cache results in the file `config.cache'. Alternatively, `--cache-file=file' specifies that file be the cache file. The cache file is created if it does not exist already. When configure calls configure scripts in subdirectories, it uses the `--cache-file' argument so that they share the same cache. See section 4.10 Configuring Other Packages in Subdirectories, for information on configuring subdirectories with the AC_CONFIG_SUBDIRS macro.

`config.status' only pays attention to the cache file if it is given the `--recheck' option, which makes it rerun configure.

It is wrong to try to distribute cache files for particular system types. There is too much room for error in doing that, and too much administrative overhead in maintaining them. For any features that can't be guessed automatically, use the standard method of the canonical system type and linking files (see section 11. Manual Configuration).

The site initialization script can specify a site-wide cache file to use, instead of the usual per-program cache. In this case, the cache file will gradually accumulate information whenever someone runs a new configure script. (Running configure merges the new cache results with the existing cache file.) This may cause problems, however, if the system configuration (e.g. the installed libraries or compilers) changes and the stale cache file is not deleted.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3.3 Cache Checkpointing

If your configure script, or a macro called from configure.ac, happens to abort the configure process, it may be useful to checkpoint the cache a few times at key points using AC_CACHE_SAVE. Doing so will reduce the amount of time it takes to re-run the configure script with (hopefully) the error that caused the previous abort corrected.

Macro: AC_CACHE_LOAD
Loads values from existing cache file, or creates a new cache file if a cache file is not found. Called automatically from AC_INIT.

Macro: AC_CACHE_SAVE
Flushes all cached values to the cache file. Called automatically from AC_OUTPUT, but it can be quite useful to call AC_CACHE_SAVE at key points in configure.ac.

For instance:

 ... AC_INIT, etc. ...
# Checks for programs.
AC_PROG_CC
AC_PROG_GCC_TRADITIONAL
 ... more program checks ...
AC_CACHE_SAVE

# Checks for libraries.
AC_CHECK_LIB(nsl, gethostbyname)
AC_CHECK_LIB(socket, connect)
 ... more lib checks ...
AC_CACHE_SAVE

# Might abort...
AM_PATH_GTK(1.0.2,, (exit 1); exit)
AM_PATH_GTKMM(0.9.5,, (exit 1); exit)
 ... AC_OUTPUT, etc. ...

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4 Printing Messages

configure scripts need to give users running them several kinds of information. The following macros print messages in ways appropriate for each kind. The arguments to all of them get enclosed in shell double quotes, so the shell performs variable and back-quote substitution on them.

These macros are all wrappers around the echo shell command. configure scripts should rarely need to run echo directly to print messages for the user. Using these macros makes it easy to change how and when each kind of message is printed; such changes need only be made to the macro definitions and all of the callers will change automatically.

To diagnose static issues, i.e., when autoconf is run, see 9.3 Reporting Messages.

Macro: AC_MSG_CHECKING (feature-description)
Notify the user that configure is checking for a particular feature. This macro prints a message that starts with `checking ' and ends with `...' and no newline. It must be followed by a call to AC_MSG_RESULT to print the result of the check and the newline. The feature-description should be something like `whether the Fortran compiler accepts C++ comments' or `for c89'.

This macro prints nothing if configure is run with the `--quiet' or `--silent' option.

Macro: AC_MSG_RESULT (result-description)
Notify the user of the results of a check. result-description is almost always the value of the cache variable for the check, typically `yes', `no', or a file name. This macro should follow a call to AC_MSG_CHECKING, and the result-description should be the completion of the message printed by the call to AC_MSG_CHECKING.

This macro prints nothing if configure is run with the `--quiet' or `--silent' option.

Macro: AC_MSG_NOTICE (message)
Deliver the message to the user. It is useful mainly to print a general description of the overall purpose of a group of feature checks, e.g.,

AC_MSG_NOTICE([checking if stack overflow is detectable])

This macro prints nothing if configure is run with the `--quiet' or `--silent' option.

Macro: AC_MSG_ERROR (error-description, [exit-status])
Notify the user of an error that prevents configure from completing. This macro prints an error message to the standard error output and exits configure with exit-status (1 by default). error-description should be something like `invalid value $HOME for \$HOME'.

The error-description should start with a lower-case letter, and "cannot" is preferred to "can't".

Macro: AC_MSG_WARN (problem-description)
Notify the configure user of a possible problem. This macro prints the message to the standard error output; configure continues running afterward, so macros that call AC_MSG_WARN should provide a default (back-up) behavior for the situations they warn about. problem-description should be something like `ln -s seems to make hard links'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. Programming in M4

Autoconf is written on top of two layers: M4sugar, which provides convenient macros for pure M4 programming, and M4sh, which provides macros dedicated to shell script generation.

As of this version of Autoconf, these two layers are still experimental, and their interface might change in the future. As a matter of fact, anything that is not documented must not be used.

8.1 M4 Quotation | Protecting macros from unwanted expansion
8.2 Programming in M4sugar | Convenient pure M4 macros

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1 M4 Quotation

The most common brokenness of existing macros is an improper quotation. This section, which users of Autoconf can skip, but which macro writers must read, first justifies the quotation scheme that was chosen for Autoconf and then ends with a rule of thumb. Understanding the former helps one to follow the latter.

8.1.1 Active Characters | Characters that change the behavior of m4
8.1.2 One Macro Call | Quotation and one macro call
8.1.3 Quotation and Nested Macros | Macros calling macros
8.1.4 Quadrigraphs | Another way to escape special characters
8.1.5 Quotation Rule Of Thumb | One parenthesis, one quote

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.1 Active Characters

To fully understand where proper quotation is important, you first need to know what are the special characters in Autoconf: `#' introduces a comment inside which no macro expansion is performed, `,' separates arguments, `[' and `]' are the quotes themselves, and finally `(' and `)' (which m4 tries to match by pairs).

In order to understand the delicate case of macro calls, we first have to present some obvious failures. Below they are "obvious-ified", although you find them in real life, they are usually in disguise.

Comments, introduced by a hash and running up to the newline, are opaque tokens to the top level: active characters are turned off, and there is no macro expansion:

# define([def], ine)
=># define([def], ine)

Each time there can be a macro expansion, there is a quotation expansion; i.e., one level of quotes is stripped:

int tab[10];
=>int tab10;
[int tab[10];]
=>int tab[10];

Without this in mind, the reader will try hopelessly to use her macro array:

define([array], [int tab[10];])
array
=>int tab10;
[array]
=>array

How can you correctly output the intended results(2)?

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.2 One Macro Call

Let's proceed on the interaction between active characters and macros with this small macro, which just returns its first argument:

define([car], [$1])

The two pairs of quotes above are not part of the arguments of define; rather, they are understood by the top level when it tries to find the arguments of define. Therefore, it is equivalent to write:

define(car, $1)

But, while it is acceptable for a `configure.ac' to avoid unneeded quotes, it is bad practice for Autoconf macros which must both be more robust and also advocate perfect style.

At the top level, there are only two possible quotings: either you quote or you don't:

car(foo, bar, baz)
=>foo
[car(foo, bar, baz)]
=>car(foo, bar, baz)

Let's pay attention to the special characters:

car(#)
error-->EOF in argument list

The closing parenthesis is hidden in the comment; with a hypothetical quoting, the top level understood it this way:

car([#)]

Proper quotation, of course, fixes the problem:

car([#])
=>#

The reader will easily understand the following examples:

car(foo, bar)
=>foo
car([foo, bar])
=>foo, bar
car((foo, bar))
=>(foo, bar)
car([(foo], [bar)])
=>(foo
car([], [])
=>
car([[]], [[]])
=>[]

With this in mind, we can explore the cases where macros invoke macros...

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.3 Quotation and Nested Macros

The examples below use the following macros:

define([car], [$1])
define([active], [ACT, IVE])
define([array], [int tab[10]])

Each additional embedded macro call introduces other possible interesting quotations:

car(active)
=>ACT
car([active])
=>ACT, IVE
car([[active]])
=>active

In the first case, the top level looks for the arguments of car, and finds `active'. Because m4 evaluates its arguments before applying the macro, `active' is expanded, which results in:

car(ACT, IVE)
=>ACT

In the second case, the top level gives `active' as first and only argument of car, which results in:

active
=>ACT, IVE

i.e., the argument is evaluated after the macro that invokes it. In the third case, car receives `[active]', which results in:

[active]
=>active

exactly as we already saw above.

The example above, applied to a more realistic example, gives:

car(int tab[10];)
=>int tab10;
car([int tab[10];])
=>int tab10;
car([[int tab[10];]])
=>int tab[10];

Huh? The first case is easily understood, but why is the second wrong, and the third right? To understand that, you must know that after m4 expands a macro, the resulting text is immediately subjected to macro expansion and quote removal. This means that the quote removal occurs twice--first before the argument is passed to the car macro, and second after the car macro expands to the first argument.

As the author of the Autoconf macro car, you then consider it to be incorrect that your users have to double-quote the arguments of car, so you "fix" your macro. Let's call it qar for quoted car:

define([qar], [[$1]])

and check that qar is properly fixed:

qar([int tab[10];])
=>int tab[10];

Ahhh! That's much better.

But note what you've done: now that the arguments are literal strings, if the user wants to use the results of expansions as arguments, she has to use an unquoted macro call:

qar(active)
=>ACT

where she wanted to reproduce what she used to do with car:

car([active])
=>ACT, IVE

Worse yet: she wants to use a macro that produces a set of cpp macros:

define([my_includes], [#include <stdio.h>])
car([my_includes])
=>#include <stdio.h>
qar(my_includes)
error-->EOF in argument list

This macro, qar, because it double quotes its arguments, forces its users to leave their macro calls unquoted, which is dangerous. Commas and other active symbols are interpreted by m4 before they are given to the macro, often not in the way the users expect. Also, because qar behaves differently from the other macros, it's an exception that should be avoided in Autoconf.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.4 Quadrigraphs

When writing an autoconf macro you may occasionally need to generate special characters that are difficult to express with the standard autoconf quoting rules. For example, you may need to output the regular expression `[^[]', which matches any character other than `['. This expression contains unbalanced brackets so it cannot be put easily into an M4 macro.

You can work around this problem by using one of the following quadrigraphs:

`@<:@'
`['
`@:>@'
`]'
`@S|@'
`$'
`@%:@'
`#'

Quadrigraphs are replaced at a late stage of the translation process, after m4 is run, so they do not get in the way of M4 quoting. For example, the string `[^@<:@]', if properly quoted, will appear as `[^[]' in the configure script.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.5 Quotation Rule Of Thumb

To conclude, the quotation rule of thumb is:

One pair of quotes per pair of parentheses.

Never over-quote, never under-quote, in particular in the definition of macros. In the few places where the macros need to use brackets (usually in C program text or regular expressions), properly quote the arguments!

It is common to read Autoconf programs with snippets like:

AC_TRY_LINK(
changequote(<<, >>)dnl
<<#include <time.h>
#ifndef tzname /* For SGI.  */
extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
#endif>>,
changequote([, ])dnl
[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)

which is incredibly useless since AC_TRY_LINK is already double quoting, so you just need:

AC_TRY_LINK(
[#include <time.h>
#ifndef tzname /* For SGI.  */
extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
#endif],
            [atoi (*tzname);],
            [ac_cv_var_tzname=yes],
            [ac_cv_var_tzname=no])

The M4-fluent reader will note that these two examples are rigorously equivalent, since m4 swallows both the `changequote(<<, >>)' and `<<' `>>' when it collects the arguments: these quotes are not part of the arguments!

Simplified, the example above is just doing this:

changequote(<<, >>)dnl
<<[]>>
changequote([, ])dnl

instead of simply:

[[]]

With macros that do not double quote their arguments (which is the rule), double-quote the (risky) literals:

AC_LINK_IFELSE([AC_LANG_PROGRAM(
[[#include <time.h>
#ifndef tzname /* For SGI.  */
extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
#endif]],
                                [atoi (*tzname);])],
               [ac_cv_var_tzname=yes],
               [ac_cv_var_tzname=no])

See See section 8.1.4 Quadrigraphs, for what to do if you run into a hopeless case where quoting does not suffice.

When you create a configure script using newly written macros, examine it carefully to check whether you need to add more quotes in your macros. If one or more words have disappeared in the m4 output, you need more quotes. When in doubt, quote.

However, it's also possible to put on too many layers of quotes. If this happens, the resulting configure script will contain unexpanded macros. The autoconf program checks for this problem by doing `grep AC_ configure'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2 Programming in M4sugar

M4 by itself provides only a small, but sufficient, set of all-purpose macros. M4sugar introduces additional generic macros. Its name was coined by Lars J. Aas: "Readability And Greater Understanding Stands 4 M4sugar".

8.2.1 Redefined M4 Macros | M4 builtins changed in M4sugar
8.2.2 Forbidden Patterns | Catching unexpanded macros

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.1 Redefined M4 Macros

All the M4 native macros are moved in the `m4_' pseudo-namespace, e.g., M4sugar renames define as m4_define etc. There is one exception: dnl kept its original name, and no m4_dnl is defined.

M4sugar redefines some M4 macros, and made them slightly incompatible with their native equivalent.

Macro: m4_defn (macro)
Contrary to the M4 builtin, this macro fails if macro is not defined. See m4_undefine.

Macro: m4_undefine (macro)
Contrary to the M4 builtin, this macro fails if macro is not defined. Use

m4_ifdef([macro], [m4_undefine([macro])])

to recover the behavior of the builtin.

Macro: m4_popdef (macro)
Contrary to the M4 builtin, this macro fails if macro is not defined. See m4_undefine.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.2 Forbidden Patterns

M4sugar provides a means to define suspicious patterns, patterns describing tokens which should not be found in the output. For instance, if an Autoconf `configure' script includes tokens such as `AC_DEFINE', or `dnl', then most probably something went wrong (typically a macro was not evaluated because of over quotation).

M4sugar forbids all the tokens matching `^m4_' and `^dnl$'.

Macro: m4_pattern_forbid (pattern)
Declare no token matching pattern must be found in the output. Comments are not checked; this can be a problem if, for instance, you have some macro left unexpanded after an `#include'. No consensus is currently found in the Autoconf community, as some people consider it should be valid to name macros in comments (which doesn't makes sense to the author of this documentation, as `#'-comments should document the output, not the input, documented vy `dnl'-comments).

Of course, you might encounter exceptions to these generic rules, for instance you might have to refer to `$m4_flags'.

Macro: m4_pattern_allow (pattern)
Any token matching pattern is allowed, including if it matches an m4_pattern_forbid pattern.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. Writing Autoconf Macros

When you write a feature test that could be applicable to more than one software package, the best thing to do is encapsulate it in a new macro. Here are some instructions and guidelines for writing Autoconf macros.

9.1 Macro Definitions | Basic format of an Autoconf macro
9.2 Macro Names | What to call your new macros
9.3 Reporting Messages | Notifying autoconf users
9.4 Dependencies Between Macros | What to do when macros depend on other macros
9.5 Obsoleting Macros | Warning about old ways of doing things
9.6 Coding Style | Writing Autoconf macros à la Autoconf

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1 Macro Definitions

Autoconf macros are defined using the AC_DEFUN macro, which is similar to the M4 builtin define macro. In addition to defining a macro, AC_DEFUN adds to it some code that is used to constrain the order in which macros are called (see section 9.4.1 Prerequisite Macros).

An Autoconf macro definition looks like this:

AC_DEFUN(macro-name, macro-body)

You can refer to any arguments passed to the macro as `$1', `$2', etc. See section `How to define new macros' in GNU m4, for more complete information on writing M4 macros.

Be sure to properly quote both the macro-body and the macro-name to avoid any problems if the macro happens to have been previously defined.

Each macro should have a header comment that gives its prototype, and a brief description. When arguments have default values, display them in the prototype. For example:

# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
# --------------------------------------
define([AC_MSG_ERROR],
[{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); }])

Comments about the macro should be left in the header comment. Most other comments will make their way into `configure', so just keep using `#' to introduce comments.

If you have some very special comments about pure M4 code, comments that make no sense in `configure' and in the header comment, then use the builtin dnl: it causes m4 to discard the text through the next newline.

Keep in mind that dnl is rarely needed to introduce comments; dnl is more useful to get rid of the newlines following macros that produce no output, such as AC_REQUIRE.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.2 Macro Names

All of the Autoconf macros have all-uppercase names starting with `AC_' to prevent them from accidentally conflicting with other text. All shell variables that they use for internal purposes have mostly-lowercase names starting with `ac_'. To ensure that your macros don't conflict with present or future Autoconf macros, you should prefix your own macro names and any shell variables they use with some other sequence. Possibilities include your initials, or an abbreviation for the name of your organization or software package.

Most of the Autoconf macros' names follow a structured naming convention that indicates the kind of feature check by the name. The macro names consist of several words, separated by underscores, going from most general to most specific. The names of their cache variables use the same convention (see section 7.3.1 Cache Variable Names, for more information on them).

The first word of the name after `AC_' usually tells the category of feature being tested. Here are the categories used in Autoconf for specific test macros, the kind of macro that you are more likely to write. They are also used for cache variables, in all-lowercase. Use them where applicable; where they're not, invent your own categories.

C
C language builtin features.
DECL
Declarations of C variables in header files.
FUNC
Functions in libraries.
GROUP
UNIX group owners of files.
HEADER
Header files.
LIB
C libraries.
PATH
The full path names to files, including programs.
PROG
The base names of programs.
MEMBER
Members of aggregates.
SYS
Operating system features.
TYPE
C builtin or declared types.
VAR
C variables in libraries.

After the category comes the name of the particular feature being tested. Any further words in the macro name indicate particular aspects of the feature. For example, AC_FUNC_UTIME_NULL checks the behavior of the utime function when called with a NULL pointer.

An internal macro should have a name that starts with an underscore; Autoconf internals should therefore start with `_AC_'. Additionally, a macro that is an internal subroutine of another macro should have a name that starts with an underscore and the name of that other macro, followed by one or more words saying what the internal macro does. For example, AC_PATH_X has internal macros _AC_PATH_X_XMKMF and _AC_PATH_X_DIRECT.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3 Reporting Messages

When macros statically diagnose abnormal situations, benign or fatal, they should report them using these macros. For dynamic issues, i.e., when configure is run, see 7.4 Printing Messages.

Macro: AC_DIAGNOSE (category, message)
Report message as a warning (or as an error if requested by the user) if it falls into the category. You are encouraged to use standard categories, which currently include:

`all'
messages that don't fall into one of the following category. Use of an empty category is equivalent.

`cross'
related to cross compilation issues.

`obsolete'
use of an obsolete construct.

`syntax'
dubious syntactic constructs, incorrectly ordered macro calls.

Macro: AC_WARNING (message)
Equivalent to `AC_DIAGNOSE([syntax], message)', but you are strongly encouraged to use a finer grained category.

Macro: AC_FATAL (message)
Report a severe error message, and have autoconf die.

When the user runs `autoconf -W error', warnings from AC_DIAGNOSE and AC_WARNING are reported as error, see 3.4 Using autoconf to Create configure.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.4 Dependencies Between Macros

Some Autoconf macros depend on other macros having been called first in order to work correctly. Autoconf provides a way to ensure that certain macros are called if needed and a way to warn the user if macros are called in an order that might cause incorrect operation.

9.4.1 Prerequisite Macros | Ensuring required information
9.4.2 Suggested Ordering | Warning about possible ordering problems

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.4.1 Prerequisite Macros

A macro that you write might need to use values that have previously been computed by other macros. For example, AC_DECL_YYTEXT examines the output of flex or lex, so it depends on AC_PROG_LEX having been called first to set the shell variable LEX.

Rather than forcing the user of the macros to keep track of the dependencies between them, you can use the AC_REQUIRE macro to do it automatically. AC_REQUIRE can ensure that a macro is only called if it is needed, and only called once.

Macro: AC_REQUIRE (macro-name)
If the M4 macro macro-name has not already been called, call it (without any arguments). Make sure to quote macro-name with square brackets. macro-name must have been defined using AC_DEFUN or else contain a call to AC_PROVIDE to indicate that it has been called.

AC_REQUIRE must be used inside an AC_DEFUN'd macro; it must not be called from the top level.

AC_REQUIRE is often misunderstood. It really implements dependencies between macros in the sense that if one macro depends upon another, the latter will be expanded before the body of the former. In particular, `AC_REQUIRE(FOO)' is not replaced with the body of FOO. For instance, this definition of macros:

AC_DEFUN([TRAVOLTA],
[test "$body_temparature_in_celsius" -gt "38" &&
  dance_floor=occupied])
AC_DEFUN([NEWTON_JOHN],
[test "$hair_style" = "curly" &&
  dance_floor=occupied])

AC_DEFUN([RESERVE_DANCE_FLOOR],
[if date | grep '^Sat.*pm' >/dev/null 2>&1; then
  AC_REQUIRE([TRAVOLTA])
  AC_REQUIRE([NEWTON_JOHN])
fi])

with this `configure.ac'

AC_INIT
RESERVE_DANCE_FLOOR
if test "$dance_floor" = occupied; then
  AC_MSG_ERROR([cannot pick up here, let's move])
fi

will not leave you with a better chance to meet a kindred soul at other times than Saturday night since it expands into:

test "$body_temperature_in_Celsius" -gt "38" &&
  dance_floor=occupied
test "$hair_style" = "curly" &&
  dance_floor=occupied
fi
if date | grep '^Sat.*pm' >/dev/null 2>&1; then

fi

This behavior was chosen on purpose: (i) it prevents messages in required macros from interrupting the messages in the requiring macros; (ii) it avoids bad surprises when shell conditionals are used, as in:

if ...; then
  AC_REQUIRE([SOME_CHECK])
fi
...
SOME_CHECK

You are encouraged to put all AC_REQUIREs at the beginning of a macro. You can use dnl to avoid the empty lines they leave.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.4.2 Suggested Ordering

Some macros should be run before another macro if both are called, but neither requires that the other be called. For example, a macro that changes the behavior of the C compiler should be called before any macros that run the C compiler. Many of these dependencies are noted in the documentation.

Autoconf provides the AC_BEFORE macro to warn users when macros with this kind of dependency appear out of order in a `configure.ac' file. The warning occurs when creating configure from `configure.ac', not when running configure.

For example, AC_PROG_CPP checks whether the C compiler can run the C preprocessor when given the `-E' option. It should therefore be called after any macros that change which C compiler is being used, such as AC_PROG_CC. So AC_PROG_CC contains:

AC_BEFORE([$0], [AC_PROG_CPP])dnl

This warns the user if a call to AC_PROG_CPP has already occurred when AC_PROG_CC is called.

Macro: AC_BEFORE (this-macro-name, called-macro-name)
Make m4 print a warning message to the standard error output if called-macro-name has already been called. this-macro-name should be the name of the macro that is calling AC_BEFORE. The macro called-macro-name must have been defined using AC_DEFUN or else contain a call to AC_PROVIDE to indicate that it has been called.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.5 Obsoleting Macros

Configuration and portability technology has evolved over the years. Often better ways of solving a particular problem are developed, or ad-hoc approaches are systematized. This process has occurred in many parts of Autoconf. One result is that some of the macros are now considered obsolete; they still work, but are no longer considered the best thing to do, hence they should be replaced with more modern macros. Ideally, autoupdate should substitute the old macro calls with their modern implementation.

Autoconf provides a simple means to obsolete a macro.

Macro: AU_DEFUN (old-macro, implementation, [message])
Define old-macro as implementation. The only difference with AC_DEFUN is that the user will be warned that old-macro is now obsolete.

If she then uses autoupdate, the call to old-macro will be replaced by the modern implementation. The additional message is then printed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.6 Coding Style

The Autoconf macros follow a strict coding style. You are encouraged to follow this style, especially if you intend to distribute your macro, either by contributing it to Autoconf itself, or via other means.

The first requirement is to pay great attention to the quotation, for more details, see 3.1.2 The Autoconf Language, and 8.1 M4 Quotation.

Do not try to invent new interfaces. It is likely that there is a macro in Autoconf that resembles the macro you are defining: try to stick to this existing interface (order of arguments, default values, etc.). We are conscious that some of these interfaces are not perfect; nevertheless, when harmless, homogeneity should be preferred over creativity.

Be careful about clashes both between M4 symbols and between shell variables.

If you stick to the suggested M4 naming scheme (see section 9.2 Macro Names), you are unlikely to generate conflicts. Nevertheless, when you need to set a special value, avoid using a regular macro name; rather, use an "impossible" name. For instance, up to version 2.13, the macro AC_SUBST used to remember what symbols were already defined by setting AC_SUBST_symbol, which is a regular macro name. But since there is a macro named AC_SUBST_FILE, it was just impossible to `AC_SUBST(FILE)'! In this case, AC_SUBST(symbol) or _AC_SUBST(symbol) should have been used (yes, with the parentheses)...or better yet, high-level macros such as AC_EXPAND_ONCE.

No Autoconf macro should ever enter the user-variable name space; i.e., except for the variables that are the actual result of running the macro, all shell variables should start with ac_. In addition, small macros or any macro that is likely to be embedded in other macros should be careful not to use obvious names.

Do not use dnl to introduce comments: most of the comments you are likely to write are either header comments which are not output anyway, or comments that should make their way into `configure'. There are exceptional cases where you do want to comment special M4 constructs, in which case dnl is right, but keep in mind that it is unlikely.

M4 ignores the leading spaces before each argument, use this feature to indent in such a way that arguments are (more or less) aligned with the opening parenthesis of the macro being called. For instance, instead of

AC_CACHE_CHECK(for EMX OS/2 environment,
ac_cv_emxos2,
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
[ac_cv_emxos2=yes], [ac_cv_emxos2=no])])

write

AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
                   [ac_cv_emxos2=yes],
                   [ac_cv_emxos2=no])])

or even

AC_CACHE_CHECK([for EMX OS/2 environment],
               [ac_cv_emxos2],
               [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
                                                   [return __EMX__;])],
                                  [ac_cv_emxos2=yes],
                                  [ac_cv_emxos2=no])])

When using AC_TRY_RUN or any macro that cannot work when cross-compiling, provide a pessimistic value (typically `no').

Feel free to use various tricks to prevent auxiliary tools, such as syntax-highlighting editors, from behaving improperly. For instance, instead of:

patsubst([$1], [$"])

use

patsubst([$1], [$""])

so that Emacsen do not open a endless "string" at the first quote. For the same reasons, avoid:

test $[#] != 0

and use:

test $[@%:@] != 0

Otherwise, the closing bracket would be hidden inside a `#'-comment, breaking the bracket-matching highlighting from Emacsen. Note the preferred style to escape from M4: `$[1]', `$[@]', etc. Do not escape when it is unneeded. Common examples of useless quotation are `[$]$1' (write `$$1'), `[$]var' (use `$var'), etc. If you add portability issues to the picture, you'll prefer `${1+"$[@]"}' to `"[$]@"', and you'll prefer do something better than hacking Autoconf :-).

When using sed, don't use `-e' except for indenting purpose. With the s command, the preferred separator is `/' unless `/' itself is used in the command, in which case you should use `,'.

See section 9.1 Macro Definitions, for details on how to define a macro. If a macro doesn't use AC_REQUIRE and it is expected to never be the object of an AC_REQUIRE directive, then use define. In case of doubt, use AC_DEFUN. All the AC_REQUIRE statements should be at the beginning of the macro, dnl'ed.

You should not rely on the number of arguments: instead of checking whether an argument is missing, test that it is not empty. It provides both a simpler and a more predictable interface to the user, and saves room for further arguments.

Unless the macro is short, try to leave the closing `])' at the beginning of a line, followed by a comment that repeats the name of the macro being defined. This introduces an additional newline in configure; normally, that is not a problem, but if you want to remove it you can use `[]dnl' on the last line. You can similarly use `[]dnl' after a macro call to remove its newline. `[]dnl' is recommended instead of `dnl' to ensure that M4 does not interpret the `dnl' as being attached to the preceding text or macro output. For example, instead of:

AC_DEFUN([AC_PATH_X],
[AC_MSG_CHECKING([for X])
AC_REQUIRE_CPP()
# ...omitted...
  AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
fi])

you would write:

AC_DEFUN([AC_PATH_X],
[AC_REQUIRE_CPP()[]dnl
AC_MSG_CHECKING([for X])
# ...omitted...
  AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
fi[]dnl
])# AC_PATH_X

If the macro is long, try to split it into logical chunks. Typically, macros that check for a bug in a function and prepare its AC_LIBOBJ replacement should have an auxiliary macro to perform this setup. Do not hesitate to introduce auxiliary macros to factor your code.

In order to highlight the recommended coding style, here is a macro written the old way:

dnl Check for EMX on OS/2.
dnl _AC_EMXOS2
AC_DEFUN(_AC_EMXOS2,
[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
ac_cv_emxos2=yes, ac_cv_emxos2=no)])
test "$ac_cv_emxos2" = yes && EMXOS2=yes])

and the new way:

# _AC_EMXOS2
# ----------
# Check for EMX on OS/2.
define([_AC_EMXOS2],
[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
                   [ac_cv_emxos2=yes],
                   [ac_cv_emxos2=no])])
test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
])# _AC_EMXOS2

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10. Portable Shell Programming

When writing your own checks, there are some shell-script programming techniques you should avoid in order to make your code portable. The Bourne shell and upward-compatible shells like the Korn shell and Bash have evolved over the years, but to prevent trouble, do not take advantage of features that were added after UNIX version 7, circa 1977. You should not use shell functions, aliases, negated character classes, or other features that are not found in all Bourne-compatible shells; restrict yourself to the lowest common denominator. Even unset is not supported by all shells! Also, include a space after the exclamation point in interpreter specifications, like this:

#! /usr/bin/perl

If you omit the space before the path, then 4.2BSD based systems (such as Sequent DYNIX) will ignore the line, because they interpret `#! /' as a 4-byte magic number.

The set of external programs you should run in a configure script is fairly small. See section `Utilities in Makefiles' in GNU Coding Standards, for the list. This restriction allows users to start out with a fairly small set of programs and build the rest, avoiding too many interdependencies between packages.

Some of these external utilities have a portable subset of features; see 10.9 Limitations of Usual Tools.

10.1 Shellology | A zoology of shells
10.2 Here-Documents | Quirks and tricks
10.3 File Descriptors | FDs and redirections
10.4 File System Conventions | File- and pathnames
10.5 Shell Substitutions | Variable and command expansions
10.6 Assignments | Varying side effects of assignments
10.7 Special Shell Variables | Variables you should not change
10.8 Limitations of Shell Builtins | Portable use of not so portable /bin/sh
10.9 Limitations of Usual Tools | Portable use of portable tools
10.10 Limitations of Make | Portable Makefiles

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.1 Shellology

There are several families of shells, most prominently the Bourne family and the C shell family which are deeply incompatible. If you want to write portable shell scripts, avoid members of the C shell family.

Below we describe some of the members of the Bourne shell family.

Ash
ash is often used on GNU/Linux and BSD systems as a light-weight Bourne-compatible shell. Ash 0.2 has some bugs that are fixed in the 0.3.x series, but portable shell scripts should workaround them, since version 0.2 is still shipped with many GNU/Linux distributions.

To be compatible with Ash 0.2:

  • don't use `$?' after expanding empty or unset variables:

    foo=
false
$foo
echo "Don't use it: $?"

  • don't use command substitution within variable expansion:

    cat ${FOO=`bar`}

  • beware that single builtin substitutions are not performed by a sub shell, hence their effect applies to the current shell! See section 10.5 Shell Substitutions, item "Command Substitution".

Bash
To detect whether you are running bash, test if BASH_VERSION is set. To disable its extensions and require POSIX compatibility, run `set -o posix'. See section `Bash POSIX Mode' in The GNU Bash Reference Manual, for details.

/usr/xpg4/bin/sh on Solaris
The POSIX-compliant Bourne shell on a Solaris system is /usr/xpg4/bin/sh and is part of an extra optional package. There is no extra charge for this package, but it is also not part of a minimal OS install and therefore some folks may not have it.

Zsh
To detect whether you are running zsh, test if ZSH_VERSION is set. By default zsh is not compatible with the Bourne shell: you have to run `emulate sh' and set NULLCMD to `:'. See section `Compatibility' in The Z Shell Manual, for details.

Zsh 3.0.8 is the native /bin/sh on Mac OS X 10.0.3.

The following discussion between Russ Allbery and Robert Lipe is worth reading:

Russ Allbery:

The GNU assumption that /bin/sh is the one and only shell leads to a permanent deadlock. Vendors don't want to break user's existant shell scripts, and there are some corner cases in the Bourne shell that are not completely compatible with a POSIX shell. Thus, vendors who have taken this route will never (OK..."never say never") replace the Bourne shell (as /bin/sh) with a POSIX shell.

Robert Lipe:

This is exactly the problem. While most (at least most System V's) do have a bourne shell that accepts shell functions most vendor /bin/sh programs are not the POSIX shell.

So while most modern systems do have a shell _somewhere_ that meets the POSIX standard, the challenge is to find it.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2 Here-Documents

Don't rely on `\' being preserved just because it has no special meaning together with the next symbol. in the native /bin/sh on OpenBSD 2.7 `\"' expands to `"' in here-documents with unquoted delimiter. As a general rule, if `\\' expands to `\' use `\\' to get `\'.

With OpenBSD 2.7's /bin/sh

$ cat <<EOF
> \" \\
> EOF
" \

and with Bash:

bash-2.04$ cat <<EOF
> \" \\
> EOF
\" \

Many older shells (including the Bourne shell) implement here-documents inefficiently. Users can generally speed things up by using a faster shell, e.g., by using the command `bash ./configure' rather than plain `./configure'.

Some shells can be extremely inefficient when there are a lot of here-documents inside a single statement. For instance if your `configure.ac' includes something like:

if <cross_compiling>; then
  assume this and that
else
  check this
  check that
  check something else
  ...
  on and on forever
  ...
fi

A shell parses the whole if/fi construct, creating temporary files for each here document in it. Some shells create links for such here-documents on every fork, so that the clean-up code they had installed correctly removes them. It is creating the links that the shell can take forever.

Moving the tests out of the if/fi, or creating multiple if/fi constructs, would improve the performance significantly. Anyway, this kind of construct is not exactly the typical use of Autoconf. In fact, it's even not recommended, because M4 macros can't look into shell conditionals, so we may fail to expand a macro when it was expanded before in a conditional path, and the condition turned out to be false at run-time, and we end up not executing the macro at all.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.3 File Descriptors

Some file descriptors shall not be used, since some systems, admittedly arcane, use them for special purpose:

3
some systems may open it to `/dev/tty'.

4
used on the Kubota Titan.

Don't redirect several times the same file descriptor, as you are doomed to failure under Ultrix.

ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
UWS V4.4 (Rev. 11)
$ eval 'echo matter >fullness' >void
illegal io
$ eval '(echo matter >fullness)' >void
illegal io
$ (eval '(echo matter >fullness)') >void
Ambiguous output redirect.

In each case the expected result is of course `fullness' containing `matter' and `void' being empty.

Don't try to redirect the standard error of a command substitution: it must be done inside the command substitution: when running `: `cd /zorglub` 2>/dev/null' expect the error message to escape, while `: `cd /zorglub 2>/dev/null`' works properly.

It is worth noting that Zsh (but not Ash nor Bash) makes it possible in assignments though: `foo=`cd /zorglub` 2>/dev/null'.

Most shells, if not all (including Bash, Zsh, Ash), output traces on stderr, even for sub-shells. This might result in undesired content if you meant to capture the standard-error output of the inner command:

$ ash -x -c '(eval "echo foo >&2") 2>stderr'
$ cat stderr
+ eval echo foo >&2
+ echo foo
foo
$ bash -x -c '(eval "echo foo >&2") 2>stderr'
$ cat stderr
+ eval 'echo foo >&2'
++ echo foo
foo
$ zsh -x -c '(eval "echo foo >&2") 2>stderr'
# Traces on startup files deleted here.
$ cat stderr
+zsh:1> eval echo foo >&2
+zsh:1> echo foo
foo

You'll appreciate the various levels of detail...

One workaround is to grep out uninteresting lines, hoping not to remove good ones...

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.4 File System Conventions

While autoconf and friends will usually be run on some Unix variety, it can and will be used on other systems, most notably DOS variants. This impacts several assumptions regarding file and path names.

For example, the following code:

case $foo_dir in
  /*) # Absolute
     ;;
  *)
     foo_dir=$dots$foo_dir ;;
esac

will fail to properly detect absolute paths on those systems, because they can use a drivespec, and will usually use a backslash as directory separator. The canonical way to check for absolute paths is:

case $foo_dir in
  [\\/]* | ?:[\\/]* ) # Absolute
     ;;
  *)
     foo_dir=$dots$foo_dir ;;
esac

Make sure you quote the brackets if appropriate and keep the backslash as first character (see section 10.8 Limitations of Shell Builtins).

Also, because the colon is used as part of a drivespec, these systems don't use it as path separator. When creating or accessing paths, use $ac_path_separator instead (or the PATH_SEPARATOR output variable). autoconf sets this to the appropriate value (`:' or `;') when it starts up.

File names need extra care as well. While DOS-based environments that are Unixy enough to run autoconf (such as DJGPP) will usually be able to handle long file names properly, there are still limitations that can seriously break packages. Several of these issues can be easily detected by the doschk package.

A short overview follows; problems are marked with SFN/LFN to indicate where they apply: SFN means the issues are only relevant to plain DOS, not to DOS boxes under Windows, while LFN identifies problems that exist even under Windows.

No multiple dots (SFN)
DOS cannot handle multiple dots in filenames. This is an especially important thing to remember when building a portable configure script, as autoconf uses a .in suffix for template files.

This is perfectly OK on Unices:

AC_CONFIG_HEADER(config.h)
AC_CONFIG_FILES([source.c foo.bar])
AC_OUTPUT

but it causes problems on DOS, as it requires `config.h.in', `source.c.in' and `foo.bar.in'. To make your package more portable to DOS-based environments, you should use this instead:

AC_CONFIG_HEADER(config.h:config.hin)
AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
AC_OUTPUT

No leading dot (SFN)
DOS cannot handle filenames that start with a dot. This is usually not a very important issue for autoconf.

Case insensitivity (LFN)
DOS is case insensitive, so you cannot, for example, have both a file called `INSTALL' and a directory called `install'. This also affects make; if there's a file called `INSTALL' in the directory, make install will do nothing (unless the `install' target is marked as PHONY).

The 8+3 limit (SFN)
Because the DOS file system only stores the first 8 characters of the filename and the first 3 of the extension, those must be unique. That means that `foobar-part1.c', `foobar-part2.c' and `foobar-prettybird.c' all resolve to the same filename (`FOOBAR-P.C'). The same goes for `foo.bar' and `foo.bartender'.

Note: This is not usually a problem under Windows, as it uses numeric tails in the short version of filenames to make them unique. However, a registry setting can turn this behaviour off. While this makes it possible to share file trees containing long file names between SFN and LFN environments, it also means the above problem applies there as well.

Invalid characters
Some characters are invalid in DOS filenames, and should therefore be avoided. In a LFN environment, these are `/', `\', `?', `*', `:', `<', `>', `|' and `"'. In a SFN environment, other characters are also invalid. These include `+', `,', `[' and `]'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.5 Shell Substitutions

Contrary to a persistent urban legend, the Bourne shell does not systematically split variables and backquoted expressions, in particular on the right-hand side of assignments and in the argument of case. For instance, the following code:

case "$given_srcdir" in
.)  top_srcdir="`echo "$dots" | sed 's,/$,,'`"
*)  top_srcdir="$dots$given_srcdir" ;;
esac

is more readable when written as:

case $given_srcdir in
.)  top_srcdir=`echo "$dots" | sed 's,/$,,'`
*)  top_srcdir=$dots$given_srcdir ;;
esac

and in fact it is even more portable: in the first case of the first attempt, the computation of top_srcdir is not portable, since not all shells properly understand "`..."..."...`". Worse yet, not all shells understand "`...\"...\"...`" the same way. There is just no portable way to use double-quoted strings inside double-quoted backquoted expressions (pfew!).

$@
One of the most famous shell-portability issues is related to `"$@"': when there are no positional arguments, it is supposed to be equivalent to nothing. But some shells, for instance under Digital Unix 4.0 and 5.0, will then replace it with an empty argument. To be portable, use `${1+"$@"}'.

${var:-value}
Old BSD shells, including the Ultrix sh, don't accept the colon for any shell substitution, and complain and die.

${var=literal}
Be sure to quote:

: ${var='Some words'}

otherwise some shells, such as on Digital Unix V 5.0, will die because of a "bad substitution".

Solaris' /bin/sh has a frightening bug in its interpretation of this. Imagine you need set a variable to a string containing `}'. This `}' character confuses Solaris' /bin/sh when the affected variable was already set. This bug can be exercised by running:

$ unset foo
$ foo=${foo='}'}
$ echo $foo
}
$ foo=${foo='}'   # no error; this hints to what the bug is
$ echo $foo
}
$ foo=${foo='}'}
$ echo $foo
}}
 ^ ugh!

It seems that `}' is interpreted as matching `${', even though it is enclosed in single quotes. The problem doesn't happen using double quotes.

${var=expanded-value}
On Ultrix, running

default="yu,yaa"
: ${var="$default"}

will set var to `M-yM-uM-,M-yM-aM-a', i.e., the 8th bit of each char will be set. You won't observe the phenomenon using a simple `echo $var' since apparently the shell resets the 8th bit when it expands $var. Here are two means to make this shell confess its sins:

$ cat -v <<EOF
$var
EOF

and

$ set | grep '^var=' | cat -v

One classic incarnation of this bug is:

default="a b c"
: ${list="$default"}
for c in $list; do
  echo $c
done

You'll get `a b c' on a single line. Why? Because there are no spaces in `$list': there are `M- ', i.e., spaces with the 8th bit set, hence no IFS splitting is performed!!!

One piece of good news is that Ultrix works fine with `: ${list=$default}'; i.e., if you don't quote. The bad news is then that QNX 4.25 then sets list to the last item of default!

The portable way out consists in using a double assignment, to switch the 8th bit twice on Ultrix:

list=${list="$default"}

...but beware of the `}' bug from Solaris (see above). For safety, use:

test "${var+set}" = set || var={value}

`commands`
While in general it makes no sense, do not substitute a single builtin with side effects as Ash 0.2, trying to optimize, does not fork a sub-shell to perform the command.

For instance, if you wanted to check that cd is silent, do not use `test -z "`cd /`"' because the following can happen:

$ pwd
/tmp
$ test -n "`cd /`" && pwd
/

The result of `foo=`exit 1`' is left as an exercise to the reader.

$(commands)
This construct is meant to replace ``commands`'; they can be nested while this is impossible to do portably with back quotes. Unfortunately it is not yet widely supported. Most notably, even recent releases of Solaris don't support it:

$ showrev -c /bin/sh | grep version
Command version: SunOS 5.8 Generic 109324-02 February 2001
$ echo $(echo blah)
syntax error: `(' unexpected

nor does IRIX 6.5's Bourne shell:
$ uname -a
IRIX firebird-image 6.5 07151432 IP22
$ echo $(echo blah)
$(echo blah)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.6 Assignments

When setting several variables in a row, be aware that the order of the evaluation is undefined. For instance `foo=1 foo=2; echo $foo' gives `1' with sh on Solaris, but `2' with Bash. You must use `;' to enforce the order: `foo=1; foo=2; echo $foo'.

Don't rely on the exit status of an assignment: Ash 0.2 does not change the status and propagates that of the last statement:

$ false || foo=bar; echo $?
1
$ false || foo=`:`; echo $?
0

and to make things even worse, QNX 4.25 just sets the exit status to 0 in any case:

$ foo=`exit 1`; echo $?
0

To assign default values, follow this algorithm:

  1. If the default value is a literal and does not contain any closing brace, use:

    : ${var='my literal'}

  2. If the default value contains no closing brace, has to be expanded, and the variable being initialized will never be IFS-split (i.e., it's not a list), then use:

    : ${var="$default"}

  3. If the default value contains no closing brace, has to be expanded, and the variable being initialized will be IFS-split (i.e., it's a list), then use:

    var=${var="$default"}

  4. If the default value contains a closing brace, then use:

    test "${var+set}" = set || var='${indirection}'

In most cases `var=${var="$default"}' is fine, but in case of doubt, just use the latter. See section 10.5 Shell Substitutions, items `${var:-value}' and `${var=value}' for the rationale.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.7 Special Shell Variables

Some shell variables should not be used, since they can have a deep influence on the behavior of the shell. In order to recover a sane behavior from the shell, some variables should be unset, but unset is not portable (see section 10.8 Limitations of Shell Builtins) and a fallback value is needed. We list these values below.

CDPATH
When this variable is set cd is verbose, so idioms such as `abs=`cd $rel && pwd`' break because abs receives the path twice.

Setting CDPATH to the empty value is not enough for most shells. A simple colon is enough except for zsh, which prefers a leading dot:

zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo)
/tmp/foo
zsh-3.1.6 % (CDPATH=:. cd foo)
/tmp/foo
zsh-3.1.6 % (CDPATH=.: cd foo)
zsh-3.1.6 %

(of course we could just unset CDPATH, since it also behaves properly if set to the empty string).

Life wouldn't be so much fun if bash and zsh had the same behavior:

bash-2.02 % (CDPATH=:. cd foo)
bash-2.02 % (CDPATH=.: cd foo)
/tmp/foo

Therefore, a portable solution to neutralize `CDPATH' is

CDPATH=${ZSH_VERSION+.}:

Note that since zsh supports unset, you may unset `CDPATH' using `:' as a fallback, see 10.8 Limitations of Shell Builtins.

IFS
Don't set the first character of IFS to backslash. Indeed, Bourne shells use the first character (backslash) when joining the components in `"$@"' and some shells then re-interpret (!) the backslash escapes, so you can end up with backspace and other strange characters.

LANG
LC_ALL
LC_TIME
LC_CTYPE
LANGUAGE
LC_COLLATE
LC_NUMERIC
LC_MESSAGES

These must not be set unconditionally because not all systems understand e.g. `LANG=C' (notably SCO). Fixing LC_MESSAGES prevents Solaris sh from translating var values in set! Non-C LC_CTYPE values break the ctype check. Fixing LC_COLLATE makes scripts more portable in some cases. For example, it causes the regular expression `[a-z]' to match only lower-case letters on ASCII platforms. However, `[a-z]' does not work in general even when LC_COLLATE is fixed; for example, it does not work for EBCDIC platforms. For maximum portability, you should use regular expressions like `[abcdefghijklmnopqrstuvwxyz]' that list characters explicitly instead of relying on ranges.

If one of these variables is set, you should try to unset it, using `C' as a fall back value. see 10.8 Limitations of Shell Builtins, builtin unset, for more details.

NULLCMD
When executing the command `>foo', zsh executes `$NULLCMD >foo'. The Bourne shell considers NULLCMD is `:', while zsh, even in Bourne shell compatibility mode, sets NULLCMD to `cat'. If you forgot to set NULLCMD, your script might be suspended waiting for data on its standard input.

status
This variable is an alias to `$?' for zsh (at least 3.1.6), hence read-only. Do not use it.

PATH_SEPARATOR
On DJGPP systems, the PATH_SEPARATOR variable can be set to either `:' or `;' to control the path separator bash uses to set up certain environment variables (such as PATH). Since this only works inside bash, you want autoconf to detect the regular DOS path separator `;', so it can be safely substituted in files that may not support `;' as path separator. So either unset this variable or set it to `;'.

RANDOM
Many shells provide RANDOM, a variable that returns a different integer when used. Most of the time, its value does not change when it is not used, but on IRIX 6.5 the value changes all the time. This can be observed by using set.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.8 Limitations of Shell Builtins

No, no, we are serious: some shells do have limitations! :)

You should always keep in mind that any built-in or command may support options, and therefore have a very different behavior with arguments starting with a dash. For instance, the innocent `echo "$word"' can give unexpected results when word starts with a dash. It is often possible to avoid this problem using `echo "x$word"', taking the `x' into account later in the pipe.

!
You can't use !, you'll have to rewrite your code.

break
The use of `break 2', etcetera, is safe.

case
You don't need to quote the argument; no splitting is performed.

You don't need the final `;;', but you should use it.

Because of a bug in its fnmatch, bash fails to properly handle backslashes in character classes:

bash-2.02$ case /tmp in [/\\]*) echo OK;; esac
bash-2.02$

This is extremely unfortunate, since you are likely to use this code to handle UNIX or MS-DOS absolute paths. To work around this bug, always put the backslash first:

bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac
OK
bash-2.02$ case /tmp in [\\/]*) echo OK;; esac
OK

echo
The simple echo is probably the most surprising source of portability troubles. It is not possible to use `echo' portably unless both options and escape sequences are omitted. New applications which are not aiming at portability should use `printf' instead of `echo'.

Don't expect any option. See section 4.6.1 Preset Output Variables, ECHO_N etc. for a means to simulate `-c'.

Do not use backslashes in the arguments, as there is no consensus on their handling. On `echo '\n' | wc -l', the sh of Digital Unix 4.0, MIPS RISC/OS 4.52, answer 2, but the Solaris' sh, Bash and Zsh (in sh emulation mode) report 1. Please note that the problem is truly echo: all the shells understand `'\n'' as the string composed of a backslash and an `n'.

Because of these problems, do not pass a string containing arbitrary characters to echo. For example, `echo "$foo"' is safe if you know that foo's value cannot contain backslashes and cannot start with `-', but otherwise you should use a here-document like this:

cat <<EOF
$foo
EOF

exit
The default value of exit is supposed to be $?; unfortunately, some shells, such as the DJGPP port of Bash 2.04, just perform `exit 0'.

bash-2.04$ foo=`exit 1` || echo fail
fail
bash-2.04$ foo=`(exit 1)` || echo fail
fail
bash-2.04$ foo=`(exit 1); exit` || echo fail
bash-2.04$

Using `exit $?' restores the expected behavior.

Some shell scripts, such as those generated by autoconf, use a trap to clean up before exiting. If the last shell command exited with nonzero status, the trap also exits with nonzero status so that the invoker can tell that an error occurred.

Unfortunately, in some shells, such as Solaris 8 sh, an exit trap ignores the exit command's status. In these shells, a trap cannot determine whether it was invoked by plain exit or by exit 1. Instead of calling exit directly, use the AC_MSG_ERROR macro that has a workaround for this problem.

export
The builtin export dubs environment variable a shell variable. Each update of exported variables corresponds to an update of the environment variables. Conversely, each environment variable received by the shell when it is launched should be imported as a shell variable marked as exported.

Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5 and DU 4.0, forget to export the environment variables they receive. As a result, two variables are coexisting: the environment variable and the shell variable. The following code demonstrates this failure:

#! /bin/sh
echo $FOO
FOO=bar
echo $FOO
exec /bin/sh $0

when run with `FOO=foo' in the environment, these shells will print alternately `foo' and `bar', although it should only print `foo' and then a sequence of `bar's.

Therefore you should export again each environment variable that you update.

false
Don't expect false to exit with status 1: in the native Bourne shell of Solaris 8, it exits with status 255.

for
To loop over positional arguments, use:

for arg
do
  echo "$arg"
done

You may not leave the do on the same line as for, since some shells improperly grok:

for arg; do
  echo "$arg"
done

If you want to explicitly refer to the positional arguments, given the `$@' bug (see section 10.5 Shell Substitutions), use:

for arg in ${1+"$@"}; do
  echo "$arg"
done

if
Using `!' is not portable. Instead of:

if ! cmp -s file file.new; then
  mv file.new file
fi

use:

if cmp -s file file.new; then :; else
  mv file.new file
fi

There are shells that do not reset the exit status from an if:

$ if (exit 42); then true; fi; echo $?
42

whereas a proper shell should have printed `0'. This is especially bad in Makefiles since it produces false failures. This is why properly written Makefiles, such as Automake's, have such hairy constructs:

if test -f "$file"; then
  install "$file" "$dest"
else
  :
fi

set
This builtin faces the usual problem with arguments starting with a dash. Modern shells such as Bash or Zsh understand `--' to specify the end of the options (any argument after `--' is a parameters, even `-x' for instance), but most shells simply stop the option processing as soon as a non-option argument is found. Therefore, use `dummy' or simply `x' to end the option processing, and use shift to pop it out:

set x $my_list; shift

shift
Not only is shifting a bad idea when there is nothing left to shift, but in addition it is not portable: the shell of MIPS RISC/OS 4.52 refuses to do it.

test
The test program is the way to perform many file and string tests. It is often invoked by the alternate name `[', but using that name in Autoconf code is asking for trouble since it is an M4 quote character.

If you need to make multiple checks using test, combine them with the shell operators `&&' and `||' instead of using the test operators `-a' and `-o'. On System V, the precedence of `-a' and `-o' is wrong relative to the unary operators; consequently, POSIX does not specify them, so using them is nonportable. If you combine `&&' and `||' in the same statement, keep in mind that they have equal precedence.

You may use `!' with test, but not with if: `test ! -r foo || exit 1'.

test (files)
To enable configure scripts to support cross-compilation, they shouldn't do anything that tests features of the build system instead of the host system. But occasionally you may find it necessary to check whether some arbitrary file exists. To do so, use `test -f' or `test -r'. Do not use `test -x', because 4.3BSD does not have it. Do not use `test -e' either, because Solaris 2.5 does not have it.

test (strings)
Avoid `test "string"', in particular if string might start with a dash, since test might interpret its argument as an option (e.g., `string = "-n"').

Contrary to a common belief, `test -n string' and `test -z string' are portable, nevertheless many shells (such as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have bizarre precedence and may be confused if string looks like an operator:

$ test -n =
test: argument expected

If there are risks, use `test "xstring" = x' or `test "xstring" != x' instead.

It is frequent to find variations of the following idiom:

test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
  action

to take an action when a token matches a given pattern. Such constructs should always be avoided by using:

echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
  action

Use case where possible since it is faster, being a shell builtin:

case $ac_feature in
  *[!-a-zA-Z0-9_]*) action;;
esac

Alas, negated character classes are probably not portable, although no shell is known to not support the POSIX.2 syntax `[!...]' (when in interactive mode, zsh is confused by the `[!...]' syntax and looks for an event in its history because of `!'). Many shells do not support the alternative syntax `[^...]' (Solaris, Digital Unix, etc.).

One solution can be:

expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
  action

or better yet

expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
  action

`expr "Xfoo" : "Xbar"' is more robust than `echo "Xfoo" | grep "^Xbar"', because it avoids problems when `foo' contains backslashes.

trap
It is safe to trap at least the signals 1, 2, 13 and 15. You can also trap 0, i.e., have the trap run when the script ends (either via an explicit exit, or the end of the script).

Although POSIX is not absolutely clear on this point, it is widely admitted that when entering the trap `$?' should be set to the exit status of the last command run before the trap. The ambiguity can be summarized as: "when the trap is launched by an exit, what is the last command run: that before exit, or exit itself?"

Bash considers exit to be the last command, while Zsh and Solaris 8 sh consider that when the trap is run it is still in the exit, hence it is the previous exit status that the trap receives:

$ cat trap.sh
trap 'echo $?' 0
(exit 42); exit 0
$ zsh trap.sh
42
$ bash trap.sh
0

The portable solution is then simple: when you want to `exit 42', run `(exit 42); exit 42', the first exit being used to set the exit status to 42 for Zsh, and the second to trigger the trap and pass 42 as exit status for Bash.

The shell in FreeBSD 4.0 has the following bug: `$?' is reset to 0 by empty lines if the code is inside trap.

$ trap 'false

echo $?' 0
$ exit
0

Fortunately, this bug only affects trap.

true
Don't worry: as far as we know true is portable. Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the portable shell community tends to prefer using :. This has a funny side effect: when asked whether false is more portable than true Alexandre Oliva answered:

In a sense, yes, because if it doesn't exist, the shell will produce an exit status of failure, which is correct for false, but not for true.

unset
You cannot assume the support of unset, nevertheless, because it is extremely useful to disable embarrassing variables such as CDPATH or LANG, you can test for its existence and use it provided you give a neutralizing value when unset is not supported:

if (unset FOO) >/dev/null 2>&1; then
  unset=unset
else
  unset=false
fi
$unset CDPATH || CDPATH=:

See section 10.7 Special Shell Variables, for some neutralizing values. Also, see 10.8 Limitations of Shell Builtins, documentation of export, for the case of environment variables.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.9 Limitations of Usual Tools

The small set of tools you can expect to find on any machine can still include some limitations you should be aware of.

awk
Don't leave white spaces before the parentheses in user functions calls, GNU awk will reject it:

$ gawk 'function die () { print "Aaaaarg!"  }
        BEGIN { die () }'
gawk: cmd. line:2:         BEGIN { die () }
gawk: cmd. line:2:                      ^ parse error
$ gawk 'function die () { print "Aaaaarg!"  }
        BEGIN { die() }'
Aaaaarg!

If you want your program to be deterministic, don't depend on for on arrays:

$ cat for.awk
END {
  arr["foo"] = 1
  arr["bar"] = 1
  for (i in arr)
    print i
}
$ gawk -f for.awk </dev/null
foo
bar
$ nawk -f for.awk </dev/null
bar
foo

Some AWK, such as HPUX 11.0's native one, have regex engines fragile to inner anchors:

$ echo xfoo | $AWK '/foo|^bar/ { print }'
$ echo bar | $AWK '/foo|^bar/ { print }'
bar
$ echo xfoo | $AWK '/^bar|foo/ { print }'
xfoo
$ echo bar | $AWK '/^bar|foo/ { print }'
bar

Either do not depend on such patterns (i.e., use `/^(.*foo|bar)/', or use a simple test to reject such AWK.

cat
Don't rely on any option. The option `-v', which displays non-printing characters, seems portable, though.

cc
When a compilation such as `cc foo.c -o foo' fails, some compilers (such as CDS on Reliant UNIX) leave a `foo.o'.

cmp
cmp performs a raw data comparison of two files, while diff compares two text files. Therefore, if you might compare DOS files, even if only checking whether two files are different, use diff to avoid spurious differences due to differences of newline encoding.

cp
SunOS cp does not support `-f', although its mv does. It's possible to deduce why mv and cp are different with respect to `-f'. mv prompts by default before overwriting a read-only file. cp does not. Therefore, mv requires a `-f' option, but cp does not. mv and cp behave differently with respect to read-only files because the simplest form of cp cannot overwrite a read-only file, but the simplest form of mv can. This is because cp opens the target for write access, whereas mv simply calls link (or, in newer systems, rename).

diff
Option `-u' is nonportable.

Some implementations, such as Tru64's, fail when comparing to `/dev/null'. Use an empty file instead.

dirname
Not all hosts have dirname, but it is reasonably easy to emulate, e.g.:

dir=`expr "x$file" : 'x\(.*\)/[^/]*' \|
          '.'      : '.'

But there are a few subtilities, e.g., under UN*X, should `//1' give `/'? Paul Eggert answers:

No, under some older flavors of Unix, leading `//' is a special path name: it refers to a "super-root" and is used to access other machines' files. Leading `///', `////', etc. are equivalent to `/'; but leading `//' is special. I think this tradition started with Apollo Domain/OS, an OS that is still in use on some older hosts.

POSIX.2 allows but does not require the special treatment for `//'. It says that the behavior of dirname on path names of the form `//([^/]+/*)?' is implementation defined. In these cases, GNU dirname returns `/', but it's more portable to return `//' as this works even on those older flavors of Unix.

I have heard rumors that this special treatment of `//' may be dropped in future versions of POSIX, but for now it's still the standard.

egrep
The empty alternative is not portable, use `?' instead. For instance with Digital Unix v5.0:

> printf "foo\n|foo\n" | egrep '^(|foo|bar)$'
|foo
> printf "bar\nbar|\n" | egrep '^(foo|bar|)$'
bar|
> printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$'
foo
|bar

egrep also suffers the limitations of grep.

expr
No expr keyword starts with `x', so use `expr x"word" : 'xregex'' to keep expr from misinterpreting word.

Don't use length, substr, match and index.

expr (`|')
You can use `|'. Although POSIX does require that `expr "' return the empty string, it does not specify the result when you `|' together the empty string (or zero) with the empty string. For example:

expr '' \| ''

GNU/Linux and POSIX.2-1992 return the empty string for this case, but traditional Unix returns `0' (Solaris is one such example). In the latest POSIX draft, the specification has been changed to match traditional Unix's behavior (which is bizarre, but it's too late to fix this). Please note that the same problem does arise when the empty string results from a computation, as in:

expr bar : foo \| foo : bar

Avoid this portability problem by avoiding the empty string.

expr (`:')
Don't use `\?', `\+' and `\|' in patterns, they are not supported on Solaris.

The POSIX.2-1992 standard is ambiguous as to whether `expr a : b' (and `expr 'a' : '\(b\)'') output `0' or the empty string. In practice, it outputs the empty string on most platforms, but portable scripts should not assume this. For instance, the QNX 4.25 native expr returns `0'.

You may believe that one means to get a uniform behavior would be to use the empty string as a default value:

expr a : b \| ''

unfortunately this behaves exactly as the original expression, see the `expr (`:')' entry for more information.

Older expr implementations (e.g. SunOS 4 expr and Solaris 8 /usr/ucb/expr) have a silly length limit that causes expr to fail if the matched substring is longer than 120 bytes. In this case, you might want to fall back on `echo|sed' if expr fails.

Don't leave, there is some more!

The QNX 4.25 expr, in addition of preferring `0' to the empty string, has a funny behavior in its exit status: it's always 1 when parentheses are used!

$ val=`expr 'a' : 'a'`; echo "$?: $val"
0: 1
$ val=`expr 'a' : 'b'`; echo "$?: $val"
1: 0

$ val=`expr 'a' : '\(a\)'`; echo "?: $val"
1: a
$ val=`expr 'a' : '\(b\)'`; echo "?: $val"
1: 0

In practice this can be a big problem if you are ready to catch failures of expr programs with some other method (such as using sed), since you may get twice the result. For instance

$ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'

will output `a' on most hosts, but `aa' on QNX 4.25. A simple work around consists in testing expr and use a variable set to expr or to false according to the result.

find
The option `-maxdepth' seems to be GNU specific. Tru64 v5.1, NetBSD 1.5 and Solaris 2.5 find commands do not understand it.

grep
Don't use `grep -s' to suppress output, because `grep -s' on System V does not suppress output, only error messages. Instead, redirect the standard output and standard error (in case the file doesn't exist) of grep to `/dev/null'. Check the exit status of grep to determine whether it found a match.

Don't use multiple regexps with `-e', as some grep will only honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway, Stardent Vistra SVR4 grep lacks `-e'... Instead, use alternation and egrep.

ln
Don't rely on ln having a `-f' option. Symbolic links are not available on old systems, use `ln' as a fall back.

For versions of the DJGPP before 2.04, ln emulates soft links for executables by generating a stub that in turn calls the real program. This feature also works with nonexistent files like in the Unix spec. So `ln -s file link' will generate `link.exe', which will attempt to call `file.exe' if run. But this feature only works for executables, so `cp -p' is used instead for these systems. DJGPP versions 2.04 and later have full symlink support.

mv
The only portable options are `-f' and `-i'.

Moving individual files between file systems is portable (it was in V6), but it is not always atomic: when doing `mv new existing', there's a critical section where neither the old nor the new version of `existing' actually exists.

Moving directories across mount points is not portable, use cp and rm.

sed
Patterns should not include the separator (unless escaped), even as part of a character class. In conformance with POSIX, the Cray sed will reject `s/[^/]*$//': use `s,[^/]*$,,'.

Sed scripts should not use branch labels longer than 8 characters and should not contain comments.

Don't include extra `;', as some sed, such as NetBSD 1.4.2's, try to interpret the second as a command:

$ echo a | sed 's/x/x/;;s/x/x/'
sed: 1: "s/x/x/;;s/x/x/": invalid command code ;

Input should have reasonably long lines, since some sed have an input buffer limited to 4000 bytes.

Alternation, `\|', is common but not portable. Anchors (`^' and `$') inside groups are not portable.

Nested groups are extremely portable, but there is at least one sed (System V/68 Base Operating System R3V7.1) that does not support it.

Of course the option `-e' is portable, but it is not needed. No valid Sed program can start with a dash, so it does not help disambiguating. Its sole usefulness is helping enforcing indenting as in:

sed -e instruction-1 \
    -e instruction-2

as opposed to

sed instruction-1;instruction-2

Contrary to yet another urban legend, you may portably use `&' in the replacement part of the s command to mean "what was matched".

sed (`t')
Some old systems have sed that "forget" to reset their `t' flag when starting a new cycle. For instance on MIPS RISC/OS, and on IRIX 5.3, if you run the following sed script (the line numbers are not actual part of the texts):

s/keep me/kept/g  # a
t end             # b
s/.*/deleted/g    # c
: end             # d

on

delete me         # 1
delete me         # 2
keep me           # 3
delete me         # 4

you get

deleted
delete me
kept
deleted

instead of

deleted
deleted
kept
deleted

Why? When processing 1, a matches, therefore sets the t flag, b jumps to d, and the output is produced. When processing line 2, the t flag is still set (this is the bug). Line a fails to match, but sed is not supposed to clear the t flag when a substitution fails. Line b sees that the flag is set, therefore it clears it, and jumps to d, hence you get `delete me' instead of `deleted'. When processing 3 t is clear, a matches, so the flag is set, hence b clears the flags and jumps. Finally, since the flag is clear, 4 is processed properly.

There are two things one should remind about `t' in sed. Firstly, always remember that `t' jumps if some substitution succeeded, not only the immediately preceding substitution, therefore, always use a fake `t clear; : clear' to reset the t flag where indeed.

Secondly, you cannot rely on sed to clear the flag at each new cycle.

One portable implementation of the script above is:

t clear
: clear
s/keep me/kept/g
t end
s/.*/deleted/g
: end

touch
On some old BSD systems, touch or any command that results in an empty file does not update the timestamps, so use a command like echo as a workaround.

GNU touch 3.16r (and presumably all before that) fails to work on SunOS 4.1.3 when the empty file is on an NFS-mounted 4.2 volume.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.10 Limitations of Make

Make itself suffers a great number of limitations, only a few of which being listed here. First of all, remember that since commands are executed by the shell, all its weaknesses are inherited...

Leading underscore in macro names
Some Make don't support leading underscores in macro names, such as on NEWS-OS 4.2R.

$ cat Makefile
_am_include = #
_am_quote =
all:; @echo this is test

% make
Make: Must be a separator on rules line 2.  Stop.

$ cat Makefile2
am_include = #
am_quote =
all:; @echo this is test

$ make -f Makefile2
this is test

VPATH
Don't use it! For instance any assignment to VPATH causes Sun make to only execute the first set of double-colon rules.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11. Manual Configuration

A few kinds of features can't be guessed automatically by running test programs. For example, the details of the object-file format, or special options that need to be passed to the compiler or linker. You can check for such features using ad-hoc means, such as having configure check the output of the uname program, or looking for libraries that are unique to particular systems. However, Autoconf provides a uniform method for handling unguessable features.

11.1 Specifying the System Type | Specifying the system type
11.2 Getting the Canonical System Type | Getting the canonical system type
11.3 Using the System Type | What to do with the system type

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.1 Specifying the System Type

Like other GNU configure scripts, Autoconf-generated configure scripts can make decisions based on a canonical name for the system type, which has the form: `cpu-vendor-os', where os can be `system' or `kernel-system'

configure can usually guess the canonical name for the type of system it's running on. To do so it runs a script called config.guess, which infers the name using the uname command or symbols predefined by the C preprocessor.

Alternately, the user can specify the system type with command line arguments to configure. Doing so is necessary when cross-compiling. In the most complex case of cross-compiling, three system types are involved. The options to specify them are(3):

`--build=build-type'
the type of system on which the package is being configured and compiled.

`--host=host-type'
the type of system on which the package will run.

`--target=target-type'
the type of system for which any compiler tools in the package will produce code (rarely needed). By default, it is the same as host.

They all default to the result of running config.guess, unless you specify either `--build' or `--host'. In this case, the default becomes the system type you specified. If you specify both, and they're different, configure will enter cross compilation mode, so it won't run any tests that require execution.

Hint: if you mean to override the result of config.guess, prefer `--build' over `--host'. In the future, `--host' will not override the name of the build system type. Also, if you specify `--host', but not `--build', when configure performs the first compiler test it will try to run an executable produced by the compiler. If the execution fails, it will enter cross-compilation mode. Note, however, that it won't guess the build-system type, since this may require running test programs. Moreover, by the time the compiler test is performed, it may be too late to modify the build-system type: other tests may have already been performed. Therefore, whenever you specify --host, be sure to specify --build too.

./configure --build=i686-pc-linux-gnu --host=m68k-coff

will enter cross-compilation mode, but configure will fail if it can't run the code generated by the specified compiler if you configure as follows:

./configure CC=m68k-coff-gcc

configure recognizes short aliases for many system types; for example, `decstation' can be used instead of `mips-dec-ultrix4.2'. configure runs a script called config.sub to canonicalize system type aliases.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.2 Getting the Canonical System Type

The following macros make the system type available to configure scripts.

The variables `build_alias', `host_alias', and `target_alias' are always exactly the arguments of `--build', `--host', and `--target'; in particular, they are left empty if the user did not use them, even if the corresponding AC_CANONICAL macro was run. Any configure script may use these variables anywhere. These are the variables that should be used when in interaction with the user.

If you need to recognize some special environments based on their system type, run the following macros to get canonical system names. These variables are not set before the macro call.

If you use these macros, you must distribute config.guess and config.sub along with your source code. See section 4.3 Outputting Files, for information about the AC_CONFIG_AUX_DIR macro which you can use to control in which directory configure looks for those scripts.

Macro: AC_CANONICAL_BUILD
Compute the canonical build-system type variable, build, and its three individual parts build_cpu, build_vendor, and build_os.

If `--build' was specified, then build is the canonicalization of build_alias by config.sub, otherwise it is determined by the shell script config.guess.

Macro: AC_CANONICAL_HOST
Compute the canonical host-system type variable, host, and its three individual parts host_cpu, host_vendor, and host_os.

If `--host' was specified, then host is the canonicalization of host_alias by config.sub, otherwise it defaults to build.

For temporary backward-compatibility, when `--host' is specified by `--build' isn't, the build system will be assumed to be the same as `--host', and `build_alias' will be set to that value. Eventually, this historically incorrect behavior will go away.

Macro: AC_CANONICAL_TARGET
Compute the canonical target-system type variable, target, and its three individual parts target_cpu, target_vendor, and target_os.

If `--target' was specified, then target is the canonicalization of target_alias by config.sub, otherwise it defaults to host.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.3 Using the System Type

How do you use a canonical system type? Usually, you use it in one or more case statements in `configure.ac' to select system-specific C files. Then, using AC_CONFIG_LINKS, link those files which have names based on the system name, to generic names, such as `host.h' or `target.c' (see section 4.9 Creating Configuration Links). The case statement patterns can use shell wild cards to group several cases together, like in this fragment:

case "$target" in
i386-*-mach* | i386-*-gnu*)
             obj_format=aout emulation=mach bfd_gas=yes ;;
i960-*-bout) obj_format=bout ;;
esac

and in `configure.ac', use:

AC_CONFIG_LINKS(host.h:config/$machine.h
                object.h:config/$obj_format.h)

You can also use the host system type to find cross-compilation tools. See section 5.2.2 Generic Program and File Checks, for information about the AC_CHECK_TOOL macro which does that.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12. Site Configuration

configure scripts support several kinds of local configuration decisions. There are ways for users to specify where external software packages are, include or exclude optional features, install programs under modified names, and set default values for configure options.

12.1 Working With External Software | Working with other optional software
12.2 Choosing Package Options | Selecting optional features
12.3 Making Your Help Strings Look Pretty | Formating help string
12.4 Configuring Site Details | Configuring site details
12.5 Transforming Program Names When Installing | Changing program names when installing
12.6 Setting Site Defaults | Giving configure local defaults

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.1 Working With External Software

Some packages require, or can optionally use, other software packages that are already installed. The user can give configure command line options to specify which such external software to use. The options have one of these forms:

--with-package=[arg]
--without-package

For example, `--with-gnu-ld' means work with the GNU linker instead of some other linker. `--with-x' means work with The X Window System.

The user can give an argument by following the package name with `=' and the argument. Giving an argument of `no' is for packages that are used by default; it says to not use the package. An argument that is neither `yes' nor `no' could include a name or number of a version of the other package, to specify more precisely which other package this program is supposed to work with. If no argument is given, it defaults to `yes'. `--without-package' is equivalent to `--with-package=no'.

configure scripts do not complain about `--with-package' options that they do not support. This behavior permits configuring a source tree containing multiple packages with a top-level configure script when the packages support different options, without spurious error messages about options that some of the packages support. An unfortunate side effect is that option spelling errors are not diagnosed. No better approach to this problem has been suggested so far.

For each external software package that may be used, `configure.ac' should call AC_ARG_WITH to detect whether the configure user asked to use it. Whether each package is used or not by default, and which arguments are valid, is up to you.

Macro: AC_ARG_WITH (package, help-string, [action-if-given], [action-if-not-given])
If the user gave configure the option `--with-package' or `--without-package', run shell commands action-if-given. If neither option was given, run shell commands action-if-not-given. The name package indicates another software package that this program should work with. It should consist only of alphanumeric characters and dashes.

The option's argument is available to the shell commands action-if-given in the shell variable withval, which is actually just the value of the shell variable with_package, with any `-' characters changed into `_'. You may use that variable instead, if you wish.

The argument help-string is a description of the option that looks like this:
  --with-readline         support fancy command line editing

help-string may be more than one line long, if more detail is needed. Just make sure the columns line up in `configure --help'. Avoid tabs in the help string. You'll need to enclose it in `[' and `]' in order to produce the leading spaces.

You should format your help-string with the macro AC_HELP_STRING (see section 12.3 Making Your Help Strings Look Pretty).

Macro: AC_WITH (package, action-if-given, [action-if-not-given])
This is an obsolete version of AC_ARG_WITH that does not support providing a help string.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.2 Choosing Package Options

If a software package has optional compile-time features, the user can give configure command line options to specify whether to compile them. The options have one of these forms:

--enable-feature=[arg]
--disable-feature

These options allow users to choose which optional features to build and install. `--enable-feature' options should never make a feature behave differently or cause one feature to replace another. They should only cause parts of the program to be built rather than left out.

The user can give an argument by following the feature name with `=' and the argument. Giving an argument of `no' requests that the feature not be made available. A feature with an argument looks like `--enable-debug=stabs'. If no argument is given, it defaults to `yes'. `--disable-feature' is equivalent to `--enable-feature=no'.

configure scripts do not complain about `--enable-feature' options that they do not support. This behavior permits configuring a source tree containing multiple packages with a top-level configure script when the packages support different options, without spurious error messages about options that some of the packages support. An unfortunate side effect is that option spelling errors are not diagnosed. No better approach to this problem has been suggested so far.

For each optional feature, `configure.ac' should call AC_ARG_ENABLE to detect whether the configure user asked to include it. Whether each feature is included or not by default, and which arguments are valid, is up to you.

Macro: AC_ARG_ENABLE (feature, help-string, [action-if-given], [action-if-not-given])
If the user gave configure the option `--enable-feature' or `--disable-feature', run shell commands action-if-given. If neither option was given, run shell commands action-if-not-given. The name feature indicates an optional user-level facility. It should consist only of alphanumeric characters and dashes.

The option's argument is available to the shell commands action-if-given in the shell variable enableval, which is actually just the value of the shell variable enable_feature, with any `-' characters changed into `_'. You may use that variable instead, if you wish. The help-string argument is like that of AC_ARG_WITH (see section 12.1 Working With External Software).

You should format your help-string with the macro AC_HELP_STRING (see section 12.3 Making Your Help Strings Look Pretty).

Macro: AC_ENABLE (feature, action-if-given, [action-if-not-given])
This is an obsolete version of AC_ARG_ENABLE that does not support providing a help string.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.3 Making Your Help Strings Look Pretty

Properly formatting the `help strings' which are used in AC_ARG_WITH (see section 12.1 Working With External Software) and AC_ARG_ENABLE (see section 12.2 Choosing Package Options) can be challenging. Specifically, you want your own `help strings' to line up in the appropriate columns of `configure --help' just like the standard Autoconf `help strings' do. This is the purpose of the AC_HELP_STRING macro.

Macro: AC_HELP_STRING (left-hand-side, right-hand-side)

Expands into an help string that looks pretty when the user executes `configure --help'. It is typically used in AC_ARG_WITH (see section 12.1 Working With External Software) or AC_ARG_ENABLE (see section 12.2 Choosing Package Options). The following example will make this clearer.

AC_DEFUN(TEST_MACRO,
[AC_ARG_WITH(foo,
             AC_HELP_STRING([--with-foo],
                            [use foo (default is NO)]),
             ac_cv_use_foo=$withval, ac_cv_use_foo=no),
AC_CACHE_CHECK(whether to use foo,
               ac_cv_use_foo, ac_cv_use_foo=no)])

Please note that the call to AC_HELP_STRING is unquoted. Then the last few lines of `configure --help' will appear like this:

--enable and --with options recognized:
  --with-foo              use foo (default is NO)

The AC_HELP_STRING macro is particularly helpful when the left-hand-side and/or right-hand-side are composed of macro arguments, as shown in the following example.

AC_DEFUN(MY_ARG_WITH,
[AC_ARG_WITH([$1],
             AC_HELP_STRING([--with-$1], [use $1 (default is $2)]),
             ac_cv_use_$1=$withval, ac_cv_use_$1=no),
AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4 Configuring Site Details

Some software packages require complex site-specific information. Some examples are host names to use for certain services, company names, and email addresses to contact. Since some configuration scripts generated by Metaconfig ask for such information interactively, people sometimes wonder how to get that information in Autoconf-generated configuration scripts, which aren't interactive.

Such site configuration information should be put in a file that is edited only by users, not by programs. The location of the file can either be based on the prefix variable, or be a standard location such as the user's home directory. It could even be specified by an environment variable. The programs should examine that file at run time, rather than at compile time. Run time configuration is more convenient for users and makes the configuration process simpler than getting the information while configuring. See section `Variables for Installation Directories' in GNU Coding Standards, for more information on where to put data files.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.5 Transforming Program Names When Installing

Autoconf supports changing the names of programs when installing them. In order to use these transformations, `configure.ac' must call the macro AC_ARG_PROGRAM.

Macro: AC_ARG_PROGRAM
Place in output variable program_transform_name a sequence of sed commands for changing the names of installed programs.

If any of the options described below are given to configure, program names are transformed accordingly. Otherwise, if AC_CANONICAL_TARGET has been called and a `--target' value is given that differs from the host type (specified with `--host'), the target type followed by a dash is used as a prefix. Otherwise, no program name transformation is done.

12.5.1 Transformation Options | configure options to transform names
12.5.2 Transformation Examples | Sample uses of transforming names
12.5.3 Transformation Rules | `Makefile' uses of transforming names

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.5.1 Transformation Options

You can specify name transformations by giving configure these command line options:

`--program-prefix=prefix'
prepend prefix to the names;

`--program-suffix=suffix'
append suffix to the names;

`--program-transform-name=expression'
perform sed substitution expression on the names.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.5.2 Transformation Examples

These transformations are useful with programs that can be part of a cross-compilation development environment. For example, a cross-assembler running on a Sun 4 configured with `--target=i960-vxworks' is normally installed as `i960-vxworks-as', rather than `as', which could be confused with a native Sun 4 assembler.

You can force a program name to begin with `g', if you don't want GNU programs installed on your system to shadow other programs with the same name. For example, if you configure GNU diff with `--program-prefix=g', then when you run `make install' it is installed as `/usr/local/bin/gdiff'.

As a more sophisticated example, you could use

--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'

to prepend `g' to most of the program names in a source tree, excepting those like gdb that already have one and those like less and lesskey that aren't GNU programs. (That is assuming that you have a source tree containing those programs that is set up to use this feature.)

One way to install multiple versions of some programs simultaneously is to append a version number to the name of one or both. For example, if you want to keep Autoconf version 1 around for awhile, you can configure Autoconf version 2 using `--program-suffix=2' to install the programs as `/usr/local/bin/autoconf2', `/usr/local/bin/autoheader2', etc. Nevertheless, pay attention that only the binaries are renamed, therefore you'd have problems with the library files which might overlap.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.5.3 Transformation Rules

Here is how to use the variable program_transform_name in a `Makefile.in':

transform = @program_transform_name@
install: all
        $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog | \
                                               sed '$(transform)'`

uninstall:
        rm -f $(bindir)/`echo myprog | sed '$(transform)'`

If you have more than one program to install, you can do it in a loop:

PROGRAMS = cp ls rm
install:
        for p in $(PROGRAMS); do \
          $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p | \
                                              sed '$(transform)'`; \
        done

uninstall:
        for p in $(PROGRAMS); do \
          rm -f $(bindir)/`echo $$p | sed '$(transform)'`; \
        done

It is guaranteed that program_transform_name is never empty, and that there are no useless separators. Therefore you may safely embed program_transform_name within a sed program using `;':

transform = @program_transform_name@
transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/

Whether to do the transformations on documentation files (Texinfo or man) is a tricky question; there seems to be no perfect answer, due to the several reasons for name transforming. Documentation is not usually particular to a specific architecture, and Texinfo files do not conflict with system documentation. But they might conflict with earlier versions of the same files, and man pages sometimes do conflict with system documentation. As a compromise, it is probably best to do name transformations on man pages but not on Texinfo manuals.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.6 Setting Site Defaults

Autoconf-generated configure scripts allow your site to provide default values for some configuration values. You do this by creating site- and system-wide initialization files.

If the environment variable CONFIG_SITE is set, configure uses its value as the name of a shell script to read. Otherwise, it reads the shell script `prefix/share/config.site' if it exists, then `prefix/etc/config.site' if it exists. Thus, settings in machine-specific files override those in machine-independent ones in case of conflict.

Site files can be arbitrary shell scripts, but only certain kinds of code are really appropriate to be in them. Because configure reads any cache file after it has read any site files, a site file can define a default cache file to be shared between all Autoconf-generated configure scripts run on that system (see section 7.3.2 Cache Files). If you set a default cache file in a site file, it is a good idea to also set the output variable CC in that site file, because the cache file is only valid for a particular compiler, but many systems have several available.

You can examine or override the value set by a command line option to configure in a site file; options set shell variables that have the same names as the options, with any dashes turned into underscores. The exceptions are that `--without-' and `--disable-' options are like giving the corresponding `--with-' or `--enable-' option and the value `no'. Thus, `--cache-file=localcache' sets the variable cache_file to the value `localcache'; `--enable-warnings=no' or `--disable-warnings' sets the variable enable_warnings to the value `no'; `--prefix=/usr' sets the variable prefix to the value `/usr'; etc.

Site files are also good places to set default values for other output variables, such as CFLAGS, if you need to give them non-default values: anything you would normally do, repetitively, on the command line. If you use non-default values for prefix or exec_prefix (wherever you locate the site file), you can set them in the site file if you specify it with the CONFIG_SITE environment variable.

You can set some cache values in the site file itself. Doing this is useful if you are cross-compiling, so it is impossible to check features that require running a test program. You could "prime the cache" by setting those values correctly for that system in `prefix/etc/config.site'. To find out the names of the cache variables you need to set, look for shell variables with `_cv_' in their names in the affected configure scripts, or in the Autoconf M4 source code for those macros.

The cache file is careful to not override any variables set in the site files. Similarly, you should not override command-line options in the site files. Your code should check that variables such as prefix and cache_file have their default values (as set near the top of configure) before changing them.

Here is a sample file `/usr/share/local/gnu/share/config.site'. The command `configure --prefix=/usr/share/local/gnu' would read this file (if CONFIG_SITE is not set to a different file).

# config.site for configure
#
# Change some defaults.
test "$prefix" = NONE && prefix=/usr/share/local/gnu
test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
test "$localstatedir" = '$prefix/var' && localstatedir=/var

# Give Autoconf 2.x generated configure scripts a shared default
# cache file for feature test results, architecture-specific.
if test "$cache_file" = /dev/null; then
  cache_file="$prefix/var/config.cache"
  # A cache file is only valid for one C compiler.
  CC=gcc
fi

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13. Running configure Scripts

Below are instructions on how to configure a package that uses a configure script, suitable for inclusion as an `INSTALL' file in the package. A plain-text version of `INSTALL' which you may use comes with Autoconf.

13.1 Basic Installation | Instructions for typical cases
13.2 Compilers and Options | Selecting compilers and optimization
13.3 Compiling For Multiple Architectures | Compiling for multiple architectures at once
13.4 Installation Names | Installing in different directories
13.5 Optional Features | Selecting optional features
13.6 Specifying the System Type | Specifying the system type
13.7 Sharing Defaults | Setting site-wide defaults for configure
13.8 Environment Variables | Defining environment variables.
13.9 configure Invocation | Changing how configure runs

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.1 Basic Installation

These are generic installation instructions.

The configure shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses those values to create a `Makefile' in each directory of the package. It may also create one or more `.h' files containing system-dependent definitions. Finally, it creates a shell script `config.status' that you can run in the future to recreate the current configuration, and a file `config.log' containing compiler output (useful mainly for debugging configure).

It can also use an optional file (typically called `config.cache' and enabled with `--cache-file=config.cache' or simply `-C') that saves the results of its tests to speed up reconfiguring. (Caching is disabled by default to prevent problems with accidental use of stale cache files.)

If you need to do unusual things to compile the package, please try to figure out how configure could check whether to do them, and mail diffs or instructions to the address given in the `README' so they can be considered for the next release. If you are using the cache, and at some point `config.cache' contains results you don't want to keep, you may remove or edit it.

The file `configure.ac' (or `configure.in') is used to create `configure' by a program called autoconf. You only need `configure.ac' if you want to change it or regenerate `configure' using a newer version of autoconf.

The simplest way to compile this package is:

  1. cd to the directory containing the package's source code and type `./configure' to configure the package for your system. If you're using csh on an old version of System V, you might need to type `sh ./configure' instead to prevent csh from trying to execute configure itself.

    Running configure takes awhile. While running, it prints some messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with the package.

  4. Type `make install' to install the programs and any data files and documentation.

  5. You can remove the program binaries and object files from the source code directory by typing `make clean'. To also remove the files that configure created (so you can compile the package for a different kind of computer), type `make distclean'. There is also a `make maintainer-clean' target, but that is intended mainly for the package's developers. If you use it, you may have to get all sorts of other programs in order to regenerate files that came with the distribution.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.2 Compilers and Options

Some systems require unusual options for compilation or linking that the configure script does not know about. Run `./configure --help' for details on some of the pertinent environment variables.

You can give configure initial values for variables by setting them in the environment. You can do that on the command line like this:

./configure CC=c89 CFLAGS=-O2 LIBS=-lposix

See section 13.8 Environment Variables, for more details.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.3 Compiling For Multiple Architectures

You can compile the package for more than one kind of computer at the same time, by placing the object files for each architecture in their own directory. To do this, you must use a version of make that supports the VPATH variable, such as GNU make. cd to the directory where you want the object files and executables to go and run the configure script. configure automatically checks for the source code in the directory that configure is in and in `..'.

If you have to use a make that does not support the VPATH variable, you have to compile the package for one architecture at a time in the source code directory. After you have installed the package for one architecture, use `make distclean' before reconfiguring for another architecture.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.4 Installation Names

By default, `make install' will install the package's files in `/usr/local/bin', `/usr/local/man', etc. You can specify an installation prefix other than `/usr/local' by giving configure the option `--prefix=path'.

You can specify separate installation prefixes for architecture-specific files and architecture-independent files. If you give configure the option `--exec-prefix=path', the package will use path as the prefix for installing programs and libraries. Documentation and other data files will still use the regular prefix.

In addition, if you use an unusual directory layout you can give options like `--bindir=path' to specify different values for particular kinds of files. Run `configure --help' for a list of the directories you can set and what kinds of files go in them.

If the package supports it, you can cause programs to be installed with an extra prefix or suffix on their names by giving configure the option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5 Optional Features

Some packages pay attention to `--enable-feature' options to configure, where feature indicates an optional part of the package. They may also pay attention to `--with-package' options, where package is something like `gnu-as' or `x' (for the X Window System). The `README' should mention any `--enable-' and `--with-' options that the package recognizes.

For packages that use the X Window System, configure can usually find the X include and library files automatically, but if it doesn't, you can use the configure options `--x-includes=dir' and `--x-libraries=dir' to specify their locations.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.6 Specifying the System Type

There may be some features configure cannot figure out automatically, but needs to determine by the type of host the package will run on. Usually configure can figure that out, but if it prints a message saying it cannot guess the host type, give it the `--build=type' option. type can either be a short name for the system type, such as `sun4', or a canonical name which has the form:

cpu-company-system

where system can have one of these forms:

os
kernel-os

See the file `config.sub' for the possible values of each field. If `config.sub' isn't included in this package, then this package doesn't need to know the host type.

If you are building compiler tools for cross-compiling, you should use the `--target=type' option to select the type of system they will produce code for.

If you want to use a cross compiler, that generates code for a platform different from the build platform, you should specify the host platform (i.e., that on which the generated programs will eventually be run) with `--host=type'. In this case, you should also specify the build platform with `--build=type', because, in this case, it may not be possible to guess the build platform (it sometimes involves compiling and running simple test programs, and this can't be done if the compiler is a cross compiler).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.7 Sharing Defaults

If you want to set default values for configure scripts to share, you can create a site shell script called `config.site' that gives default values for variables like CC, cache_file, and prefix. configure looks for `prefix/share/config.site' if it exists, then `prefix/etc/config.site' if it exists. Or, you can set the CONFIG_SITE environment variable to the location of the site script. A warning: not all configure scripts look for a site script.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.8 Environment Variables

Variables not defined in a site shell script can be set in the environment passed to configure. However, some packages may run configure again during the build, and the customized values of these variables may be lost. In order to avoid this problem, you should set them in the configure command line, using `VAR=value'. For example:

./configure CC=/usr/local2/bin/gcc

will cause the specified gcc to be used as the C compiler (unless it is overridden in the site shell script).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.9 configure Invocation

configure recognizes the following options to control how it operates.

`--help'
`-h'
Print a summary of the options to configure, and exit.

`--version'
`-V'
Print the version of Autoconf used to generate the configure script, and exit.

`--cache-file=file'
Enable the cache: use and save the results of the tests in file, traditionally `config.cache'. file defaults to `/dev/null' to disable caching.

`--config-cache'
`-C'
Alias for `--cache-file=config.cache'.

`--quiet'
`--silent'
`-q'
Do not print messages saying which checks are being made. To suppress all normal output, redirect it to `/dev/null' (any error messages will still be shown).

`--srcdir=dir'
Look for the package's source code in directory dir. Usually configure can determine that directory automatically.

configure also accepts some other, not widely useful, options. Run `configure --help' for more details.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

14. Recreating a Configuration

The configure script creates a file named `config.status', which actually configures, instantiates, the template files. It also records the configuration options that were specified when the package was last configured in case reconfiguring is needed.

Synopsis:
./config.status option... [file...]

It configures the files, if none are specified, all the templates are instantiated. The files must be specified without their dependencies, as in

./config.status foobar

not

./config.status foobar:foo.in:bar.in

The supported options are:

`--help'
`-h'
Print a summary of the command line options, the list of the template files and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--debug'
`-d'
Don't remove the temporary files.

`--file=file[:template]'
Require that file be instantiated as if `AC_CONFIG_FILES(file:template)' was used. Both file and template may be `-' in which case the standard output and/or standard input, respectively, is used. If a template filename is relative, it is first looked for in the build tree, and then in the source tree. See section 4.4 Taking Configuration Actions, for more details.

This option and the following ones provide one way for separately distributed packages to share the values computed by configure. Doing so can be useful if some of the packages need a superset of the features that one of them, perhaps a common library, does. These options allow a `config.status' file to create files other than the ones that its `configure.ac' specifies, so it can be used for a different package.

`--header=file[:template]'
Same as `--file' above, but with `AC_CONFIG_HEADERS'.

`--recheck'
Ask `config.status' to update itself and exit (no instantiation). This option is useful if you change configure, so that the results of some tests might be different from the previous run. The `--recheck' option re-runs configure with the same arguments you used before, plus the `--no-create' option, which prevents configure from running `config.status' and creating `Makefile' and other files, and the `--no-recursion' option, which prevents configure from running other configure scripts in subdirectories. (This is so other `Makefile' rules can run `config.status' when it changes; see section 4.6.4 Automatic Remaking, for an example).

`config.status' checks several optional environment variables that can alter its behavior:

Variable: CONFIG_SHELL
The shell with which to run configure for the `--recheck' option. It must be Bourne-compatible. The default is `/bin/sh'.

Variable: CONFIG_STATUS
The file name to use for the shell script that records the configuration. The default is `./config.status'. This variable is useful when one package uses parts of another and the configure scripts shouldn't be merged because they are maintained separately.

You can use `./config.status' in your Makefiles. For example, in the dependencies given above (see section 4.6.4 Automatic Remaking), `config.status' is run twice when `configure.ac' has changed. If that bothers you, you can make each run only regenerate the files for that rule:
config.h: stamp-h
stamp-h: config.h.in config.status
        ./config.status config.h
        echo > stamp-h

Makefile: Makefile.in config.status
        ./config.status Makefile

The calling convention of `config.status' has changed, see 15.1 Obsolete `config.status' Invocation, for details.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15. Obsolete Constructs

Autoconf changes, and throughout the years some constructs are obsoleted. Most of the changes involve the macros, but the tools themselves, or even some concepts, are now considered obsolete.

You may completely skip this chapter if you are new to Autoconf, its intention is mainly to help maintainers updating their packages by understanding how to move to more modern constructs.

15.1 Obsolete `config.status' Invocation | Different calling convention
15.2 `acconfig.h' | Additional entries in `config.h.in'
15.3 Using autoupdate to Modernize `configure.ac' | Automatic update of `configure.ac'
15.4 Obsolete Macros | Backward compatibility macros
15.5 Upgrading From Version 1 | Tips for upgrading your files
15.6 Upgrading From Version 2.13 | Some fresher tips

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.1 Obsolete `config.status' Invocation

`config.status' now supports arguments to specify the files to instantiate, see 14. Recreating a Configuration, for more details. Before, environment variables had to be used.

Variable: CONFIG_COMMANDS
The tags of the commands to execute. The default is the arguments given to AC_OUTPUT and AC_CONFIG_COMMANDS in `configure.ac'.

Variable: CONFIG_FILES
The files in which to perform `@variable@' substitutions. The default is the arguments given to AC_OUTPUT and AC_CONFIG_FILES in `configure.ac'.

Variable: CONFIG_HEADERS
The files in which to substitute C #define statements. The default is the arguments given to AC_CONFIG_HEADERS; if that macro was not called, `config.status' ignores this variable.

Variable: CONFIG_LINKS
The symbolic links to establish. The default is the arguments given to AC_CONFIG_LINKS; if that macro was not called, `config.status' ignores this variable.

In 14. Recreating a Configuration, using this old interface, the example would be:

config.h: stamp-h
stamp-h: config.h.in config.status
        CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
          CONFIG_HEADERS=config.h ./config.status
        echo > stamp-h

Makefile: Makefile.in config.status
        CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
          CONFIG_FILES=Makefile ./config.status

(If `configure.ac' does not call AC_CONFIG_HEADERS, there is no need to set CONFIG_HEADERS in the make rules, equally for CONFIG_COMMANDS etc.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.2 `acconfig.h'

In order to produce `config.h.in', autoheader needs to build or to find templates for each symbol. Modern releases of Autoconf use AH_VERBATIM and AH_TEMPLATE (see section 4.7.3 Autoheader Macros), but in older releases a file, `acconfig.h', contained the list of needed templates. autoheader copies comments and #define and #undef statements from `acconfig.h' in the current directory, if present. This file used to be mandatory if you AC_DEFINE any additional symbols.

Modern releases of Autoconf also provide AH_TOP and AH_BOTTOM if you need to prepend/append some information to `config.h.in'. Ancient versions of Autoconf had a similar feature: if `./acconfig.h' contains the string `@TOP@', autoheader copies the lines before the line containing `@TOP@' into the top of the file that it generates. Similarly, if `./acconfig.h' contains the string `@BOTTOM@', autoheader copies the lines after that line to the end of the file it generates. Either or both of those strings may be omitted. An even older alternate way to produce the same effect in jurasik versions of Autoconf is to create the files `file.top' (typically `config.h.top') and/or `file.bot' in the current directory. If they exist, autoheader copies them to the beginning and end, respectively, of its output.

In former versions of Autoconf, the files used in preparing a software package for distribution were:
configure.ac --.   .------> autoconf* -----> configure
               +---+
[aclocal.m4] --+   `---.
[acsite.m4] ---'       |
                       +--> [autoheader*] -> [config.h.in]
[acconfig.h] ----.     |
                 +-----'
[config.h.top] --+
[config.h.bot] --'

Use only the AH_ macros, `configure.ac' should be self-contained, and should not depend upon `acconfig.h' etc.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.3 Using autoupdate to Modernize `configure.ac'

The autoupdate program updates a `configure.ac' file that calls Autoconf macros by their old names to use the current macro names. In version 2 of Autoconf, most of the macros were renamed to use a more uniform and descriptive naming scheme. See section 9.2 Macro Names, for a description of the new scheme. Although the old names still work (see section 15.4 Obsolete Macros, for a list of the old macros and the corresponding new names), you can make your `configure.ac' files more readable and make it easier to use the current Autoconf documentation if you update them to use the new macro names.

If given no arguments, autoupdate updates `configure.ac', backing up the original version with the suffix `~' (or the value of the environment variable SIMPLE_BACKUP_SUFFIX, if that is set). If you give autoupdate an argument, it reads that file instead of `configure.ac' and writes the updated file to the standard output.

autoupdate accepts the following options:

`--help'
`-h'
Print a summary of the command line options and exit.

`--version'
`-V'
Print the version number of Autoconf and exit.

`--verbose'
`-v'
Report processing steps.

`--debug'
`-d'
Don't remove the temporary files.

`--autoconf-dir=dir'
`-A dir'
Override the location where the installed Autoconf data files are looked for. You can also set the AC_MACRODIR environment variable to a directory; this option overrides the environment variable.

This option is rarely needed and dangerous; it is only used when one plays with different versions of Autoconf simultaneously.

`--localdir=dir'
`-l dir'
Look for the package file `aclocal.m4' in directory dir instead of in the current directory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.4 Obsolete Macros

Several macros are obsoleted in Autoconf, for various reasons (typically they failed to quote properly, couldn't be extended for more recent issues etc.). They are still supported, but deprecated: their use should be avoided.

During the jump from Autoconf version 1 to version 2, most of the macros were renamed to use a more uniform and descriptive naming scheme, but their signature did not change. See section 9.2 Macro Names, for a description of the new naming scheme. Below, there is just the mapping from old names to new names for these macros, the reader is invited to refer to the definition of the new macro for the signature and the description.

Macro: AC_ALLOCA
AC_FUNC_ALLOCA

Macro: AC_ARG_ARRAY
removed because of limited usefulness

Macro: AC_C_CROSS
This macro is obsolete; it does nothing.

Macro: AC_CANONICAL_SYSTEM
Determine the system type and set output variables to the names of the canonical system types. See section 11.2 Getting the Canonical System Type, for details about the variables this macro sets.

The user is encouraged to use either AC_CANONICAL_BUILD, or AC_CANONICAL_HOST, or AC_CANONICAL_TARGET, depending on the needs. Using AC_CANONICAL_TARGET is enough to run the two other macros.

Macro: AC_CHAR_UNSIGNED
AC_C_CHAR_UNSIGNED

Macro: AC_CHECK_TYPE (type, default)
Autoconf, up to 2.13, used to provide this version of AC_CHECK_TYPE, deprecated because of its flaws. Firstly, although it is a member of the CHECK clan, singular sub-family, it does more than just checking. Second, missing types are not typedef'd, they are #define'd, which can lead to incompatible code in the case of pointer types.

This use of AC_CHECK_TYPE is obsolete and discouraged, see 5.9.2 Generic Type Checks, for the description of the current macro.

If the type type is not defined, define it to be the C (or C++) builtin type default; e.g., `short' or `unsigned'.

This macro is equivalent to:

AC_CHECK_TYPE([type],
              [AC_DEFINE([type], [default],
                         [Define to `default' if <sys/types.h>
                          does not define.])])

In order to keep backward compatibility, the two versions of AC_CHECK_TYPE are implemented, selected by a simple heuristics:

  1. If there are three or four arguments, the modern version is used.

  2. If the second argument appears to be a C or C++ type, then the obsolete version is used. This happens if the argument is a C or C++ builtin type or a C identifier ending in `_t', optionally followed by one of `[(* ' and then by a string of zero or more characters taken from the set `[]()* _a-zA-Z0-9'.

  3. If the second argument is spelled with the alphabet of valid C and C++ types, the user is warned and the modern version is used.

  4. Otherwise, the modern version is used.

You are encouraged either to use a valid builtin type, or to use the equivalent modern code (see above), or better yet, to use AC_CHECK_TYPES together with

#if !HAVE_LOFF_T
typedef loff_t off_t;
#endif

Macro: AC_CHECKING (feature-description)
Same as `AC_MSG_NOTICE([checking feature-description...]'.

Macro: AC_COMPILE_CHECK (echo-text, includes, function-body, action-if-found, [action-if-not-found])
This is an obsolete version of AC_TRY_LINK (see section 6.3 Examining Libraries), with the addition that it prints `checking for echo-text' to the standard output first, if echo-text is non-empty. Use AC_MSG_CHECKING and AC_MSG_RESULT instead to print messages (see section 7.4 Printing Messages).

Macro: AC_CONST
AC_C_CONST

Macro: AC_CROSS_CHECK
Same as AC_C_CROSS, which is obsolete too, and does nothing :-).

Macro: AC_CYGWIN
Check for the Cygwin environment in which case the shell variable CYGWIN is set to `yes'. Don't use this macro, the dignified means to check the nature of the host is using AC_CANONICAL_HOST. As a matter of fact this macro is defined as:

AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
case $host_os in
  *cygwin* ) CYGWIN=yes;;
         * ) CYGWIN=no;;
esac

Beware that the variable CYGWIN has a very special meaning when running CygWin32, and should not be changed. That's yet another reason not to use this macro.

Macro: AC_DECL_YYTEXT
Does nothing, now integrated in AC_PROG_LEX.

Macro: AC_DIR_HEADER
Like calling AC_FUNC_CLOSEDIR_VOID andAC_HEADER_DIRENT, but defines a different set of C preprocessor macros to indicate which header file is found:

Header | Old Symbol | New Symbol
`dirent.h' | DIRENT | HAVE_DIRENT_H
`sys/ndir.h' | SYSNDIR | HAVE_SYS_NDIR_H
`sys/dir.h' | SYSDIR | HAVE_SYS_DIR_H
`ndir.h' | NDIR | HAVE_NDIR_H

Macro: AC_DYNIX_SEQ
If on Dynix/PTX (Sequent UNIX), add `-lseq' to output variable LIBS. This macro used to be defined as

AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS")

now it is just AC_FUNC_GETMNTENT.

Macro: AC_EXEEXT
Defined the output variable EXEEXT based on the output of the compiler, which is now done automatically. Typically set to empty string if Unix and `.exe' if Win32 or OS/2.

Macro: AC_EMXOS2
Similar to AC_CYGWIN but checks for the EMX environment on OS/2 and sets EMXOS2.

Macro: AC_ERROR
AC_MSG_ERROR

Macro: AC_FIND_X
AC_PATH_X

Macro: AC_FIND_XTRA
AC_PATH_XTRA

Macro: AC_FUNC_CHECK
AC_CHECK_FUNC

Macro: AC_FUNC_WAIT3
If wait3 is found and fills in the contents of its third argument (a `struct rusage *'), which HP-UX does not do, define HAVE_WAIT3.

These days portable programs should use waitpid, not wait3, as wait3 is being removed from the Open Group standards, and will not appear in the next revision of POSIX.

Macro: AC_GCC_TRADITIONAL
AC_PROG_GCC_TRADITIONAL

Macro: AC_GETGROUPS_T
AC_TYPE_GETGROUPS

Macro: AC_GETLOADAVG
AC_FUNC_GETLOADAVG

Macro: AC_HAVE_FUNCS
AC_CHECK_FUNCS

Macro: AC_HAVE_HEADERS
AC_CHECK_HEADERS

Macro: AC_HAVE_LIBRARY (library, [action-if-found], [action-if-not-found], [other-libraries])
This macro is equivalent to calling AC_CHECK_LIB with a function argument of main. In addition, library can be written as any of `foo', `-lfoo', or `libfoo.a'. In all of those cases, the compiler is passed `-lfoo'. However, library cannot be a shell variable; it must be a literal name.

Macro: AC_HAVE_POUNDBANG
AC_SYS_INTERPRETER (different calling convention)

Macro: AC_HEADER_CHECK
AC_CHECK_HEADER

Macro: AC_HEADER_EGREP
AC_EGREP_HEADER

Macro: AC_INIT (unique-file-in-source-dir)
Formerly AC_INIT used to have a single argument, and was equivalent to:

AC_INIT
AC_CONFIG_SRCDIR(unique-file-in-source-dir)

Macro: AC_INLINE
AC_C_INLINE

Macro: AC_INT_16_BITS
If the C type int is 16 bits wide, define INT_16_BITS. Use `AC_CHECK_SIZEOF(int)' instead.

Macro: AC_IRIX_SUN
If on IRIX (Silicon Graphics UNIX), add `-lsun' to output LIBS. If you were using it to get getmntent, use AC_FUNC_GETMNTENT instead. If you used it for the NIS versions of the password and group functions, use `AC_CHECK_LIB(sun, getpwnam)'. Up to Autoconf 2.13, it used to be

AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS")

now it is defined as

AC_FUNC_GETMNTENT
AC_CHECK_LIB(sun, getpwnam)

Macro: AC_LANG_C
Same as `AC_LANG(C)'.

Macro: AC_LANG_CPLUSPLUS
Same as `AC_LANG(C++)'.

Macro: AC_LANG_FORTRAN77
Same as `AC_LANG(Fortran 77)'.

Macro: AC_LANG_RESTORE
Select the language that is saved on the top of the stack, as set by AC_LANG_SAVE, remove it from the stack, and call AC_LANG(language).

Macro: AC_LANG_SAVE
Remember the current language (as set by AC_LANG) on a stack. The current language does not change. AC_LANG_PUSH is preferred.

Macro: AC_LINK_FILES (source..., dest...)
This is an obsolete version of AC_CONFIG_LINKS. An updated version of:

AC_LINK_FILES(config/$machine.h config/$obj_format.h,
              host.h            object.h)

is:

AC_CONFIG_LINKS(host.h:config/$machine.h
                object.h:config/$obj_format.h)

Macro: AC_LN_S
AC_PROG_LN_S

Macro: AC_LONG_64_BITS
Define LONG_64_BITS if the C type long int is 64 bits wide. Use the generic macro `AC_CHECK_SIZEOF([long int])' instead.

Macro: AC_LONG_DOUBLE
AC_C_LONG_DOUBLE

Macro: AC_LONG_FILE_NAMES
AC_SYS_LONG_FILE_NAMES

Macro: AC_MAJOR_HEADER
AC_HEADER_MAJOR

Macro: AC_MEMORY_H
Used to define NEED_MEMORY_H if the mem functions were defined in `memory.h'. Today it is equivalent to `AC_CHECK_HEADERS(memory.h)'. Adjust your code to depend upon HAVE_MEMORY_H, not NEED_MEMORY_H, see See section 5.1.1 Standard Symbols.

Macro: AC_MINGW32
Similar to AC_CYGWIN but checks for the MingW32 compiler environment and sets MINGW32.

Macro: AC_MINUS_C_MINUS_O
AC_PROG_CC_C_O

Macro: AC_MMAP
AC_FUNC_MMAP

Macro: AC_MODE_T
AC_TYPE_MODE_T

Macro: AC_OBJEXT
Defined the output variable OBJEXT based on the output of the compiler, after .c files have been excluded. Typically set to `o' if Unix, `obj' if Win32. Now the compiler checking macros handle this automatically.

Macro: AC_OBSOLETE (this-macro-name, [suggestion])
Make m4 print a message to the standard error output warning that this-macro-name is obsolete, and giving the file and line number where it was called. this-macro-name should be the name of the macro that is calling AC_OBSOLETE. If suggestion is given, it is printed at the end of the warning message; for example, it can be a suggestion for what to use instead of this-macro-name.

For instance

AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl

You are encouraged to use AU_DEFUN instead, since it gives better services to the user.

Macro: AC_OFF_T
AC_TYPE_OFF_T

Macro: AC_OUTPUT ([file]..., [extra-cmds], [init-cmds])
The use of AC_OUTPUT with argument is deprecated, this obsoleted interface is equivalent to:

AC_CONFIG_FILES(file...)
AC_CONFIG_COMMANDS([default],
                   extra-cmds, init-cmds)
AC_OUTPUT

Macro: AC_OUTPUT_COMMANDS (extra-cmds, [init-cmds])
Specify additional shell commands to run at the end of `config.status', and shell commands to initialize any variables from configure. This macro may be called multiple times. It is obsolete, replaced by AC_CONFIG_COMMANDS.

Here is an unrealistic example:

fubar=27
AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
                   fubar=$fubar)
AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
                   [echo init bit])

Aside from the fact that AC_CONFIG_COMMANDS requires an additional key, an important difference is that AC_OUTPUT_COMMANDS is quoting its arguments twice, while AC_CONFIG_COMMANDS. This means that AC_CONFIG_COMMANDS can safely be given macro calls as arguments:

AC_CONFIG_COMMANDS(foo, [my_FOO()])

conversely, where one level of quoting was enough for literal strings with AC_OUTPUT_COMMANDS, you need two with AC_CONFIG_COMMANDS. The following lines are equivalent:

AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
AC_CONFIG_COMMANDS(default, [[echo "Square brackets: []"]])

Macro: AC_PID_T
AC_TYPE_PID_T

Macro: AC_PREFIX
AC_PREFIX_PROGRAM

Macro: AC_PROGRAMS_CHECK
AC_CHECK_PROGS

Macro: AC_PROGRAMS_PATH
AC_PATH_PROGS

Macro: AC_PROGRAM_CHECK
AC_CHECK_PROG

Macro: AC_PROGRAM_EGREP
AC_EGREP_CPP

Macro: AC_PROGRAM_PATH
AC_PATH_PROG

Macro: AC_REMOTE_TAPE
removed because of limited usefulness

Macro: AC_RESTARTABLE_SYSCALLS
AC_SYS_RESTARTABLE_SYSCALLS

Macro: AC_RETSIGTYPE
AC_TYPE_SIGNAL

Macro: AC_RSH
Removed because of limited usefulness.

Macro: AC_SCO_INTL
If on SCO UNIX, add `-lintl' to output variable LIBS. This macro used to

AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS")

now it just calls AC_FUNC_STRFTIME instead.

Macro: AC_SETVBUF_REVERSED
AC_FUNC_SETVBUF_REVERSED

Macro: AC_SET_MAKE
AC_PROG_MAKE_SET

Macro: AC_SIZEOF_TYPE
AC_CHECK_SIZEOF

Macro: AC_SIZE_T
AC_TYPE_SIZE_T

Macro: AC_STAT_MACROS_BROKEN
AC_HEADER_STAT

Macro: AC_STDC_HEADERS
AC_HEADER_STDC

Macro: AC_STRCOLL
AC_FUNC_STRCOLL

Macro: AC_ST_BLKSIZE
AC_STRUCT_ST_BLKSIZE

Macro: AC_ST_BLOCKS
AC_STRUCT_ST_BLOCKS

Macro: AC_ST_RDEV
AC_STRUCT_ST_RDEV

Macro: AC_SYS_RESTARTABLE_SYSCALLS
If the system automatically restarts a system call that is interrupted by a signal, define HAVE_RESTARTABLE_SYSCALLS. This macro does not check if system calls are restarted in general--it tests whether a signal handler installed with signal (but not sigaction) causes system calls to be restarted. It does not test if system calls can be restarted when interrupted by signals that have no handler.

These days portable programs should use sigaction with SA_RESTART if they want restartable system calls. They should not rely on HAVE_RESTARTABLE_SYSCALLS, since nowadays whether a system call is restartable is a dynamic issue, not a configuration-time issue.

Macro: AC_SYS_SIGLIST_DECLARED
AC_DECL_SYS_SIGLIST

Macro: AC_TEST_CPP
AC_TRY_CPP

Macro: AC_TEST_PROGRAM
AC_TRY_RUN

Macro: AC_TIMEZONE
AC_STRUCT_TIMEZONE

Macro: AC_TIME_WITH_SYS_TIME
AC_HEADER_TIME

Macro: AC_UID_T
AC_TYPE_UID_T

Macro: AC_UNISTD_H
Same as `AC_CHECK_HEADERS(unistd.h)'.

Macro: AC_USG
Define USG if the BSD string functions are defined in `strings.h'. You should no longer depend upon USG, but on HAVE_STRING_H, see See section 5.1.1 Standard Symbols.

Macro: AC_UTIME_NULL
AC_FUNC_UTIME_NULL

Macro: AC_VALIDATE_CACHED_SYSTEM_TUPLE ([cmd])
If the cache file is inconsistent with the current host, target and build system types, it used to execute cmd or print a default error message.

This is now handled by default.

Macro: AC_VERBOSE (result-description)
AC_MSG_RESULT.

Macro: AC_VFORK
AC_FUNC_VFORK

Macro: AC_VPRINTF
AC_FUNC_VPRINTF

Macro: AC_WAIT3
AC_FUNC_WAIT3

Macro: AC_WARN
AC_MSG_WARN

Macro: AC_WORDS_BIGENDIAN
AC_C_BIGENDIAN

Macro: AC_XENIX_DIR
This macro used to add `-lx' to output variable LIBS if on Xenix. Also, if `dirent.h' is being checked for, added `-ldir' to LIBS. Now it is merely an alias of AC_HEADER_DIRENT instead, plus some code to detect whether running XENIX on which you should not depend:

AC_MSG_CHECKING([for Xenix])
AC_EGREP_CPP(yes,
[#if defined M_XENIX && !defined M_UNIX
  yes
#endif],
             [AC_MSG_RESULT([yes]); XENIX=yes],
             [AC_MSG_RESULT([no]); XENIX=])

Macro: AC_YYTEXT_POINTER
AC_DECL_YYTEXT

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.5 Upgrading From Version 1

Autoconf version 2 is mostly backward compatible with version 1. However, it introduces better ways to do some things, and doesn't support some of the ugly things in version 1. So, depending on how sophisticated your `configure.ac' files are, you might have to do some manual work in order to upgrade to version 2. This chapter points out some problems to watch for when upgrading. Also, perhaps your configure scripts could benefit from some of the new features in version 2; the changes are summarized in the file `NEWS' in the Autoconf distribution.

15.5.1 Changed File Names | Files you might rename
15.5.2 Changed Makefiles | New things to put in `Makefile.in'
15.5.3 Changed Macros | Macro calls you might replace
15.5.4 Changed Results | Changes in how to check test results
15.5.5 Changed Macro Writing | Better ways to write your own macros

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.5.1 Changed File Names

If you have an `aclocal.m4' installed with Autoconf (as opposed to in a particular package's source directory), you must rename it to `acsite.m4'. See section 3.4 Using autoconf to Create configure.

If you distribute `install.sh' with your package, rename it to `install-sh' so make builtin rules won't inadvertently create a file called `install' from it. AC_PROG_INSTALL looks for the script under both names, but it is best to use the new name.

If you were using `config.h.top', `config.h.bot', or `acconfig.h', you still can, but you will have less clutter if you use the AH_ macros. See section 4.7.3 Autoheader Macros.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.5.2 Changed Makefiles

Add `@CFLAGS@', `@CPPFLAGS@', and `@LDFLAGS@' in your `Makefile.in' files, so they can take advantage of the values of those variables in the environment when configure is run. Doing this isn't necessary, but it's a convenience for users.

Also add `@configure_input@' in a comment to each input file for AC_OUTPUT, so that the output files will contain a comment saying they were produced by configure. Automatically selecting the right comment syntax for all the kinds of files that people call AC_OUTPUT on became too much work.

Add `config.log' and `config.cache' to the list of files you remove in distclean targets.

If you have the following in `Makefile.in':

prefix = /usr/local
exec_prefix = $(prefix)

you must change it to:

prefix = @prefix@
exec_prefix = @exec_prefix@

The old behavior of replacing those variables without `@' characters around them has been removed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.5.3 Changed Macros

Many of the macros were renamed in Autoconf version 2. You can still use the old names, but the new ones are clearer, and it's easier to find the documentation for them. See section 15.4 Obsolete Macros, for a table showing the new names for the old macros. Use the autoupdate program to convert your `configure.ac' to using the new macro names. See section 15.3 Using autoupdate to Modernize `configure.ac'.

Some macros have been superseded by similar ones that do the job better, but are not call-compatible. If you get warnings about calling obsolete macros while running autoconf, you may safely ignore them, but your configure script will generally work better if you follow the advice it prints about what to replace the obsolete macros with. In particular, the mechanism for reporting the results of tests has changed. If you were using echo or AC_VERBOSE (perhaps via AC_COMPILE_CHECK), your configure script's output will look better if you switch to AC_MSG_CHECKING and AC_MSG_RESULT. See section 7.4 Printing Messages. Those macros work best in conjunction with cache variables. See section 7.3 Caching Results.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.5.4 Changed Results

If you were checking the results of previous tests by examining the shell variable DEFS, you need to switch to checking the values of the cache variables for those tests. DEFS no longer exists while configure is running; it is only created when generating output files. This difference from version 1 is because properly quoting the contents of that variable turned out to be too cumbersome and inefficient to do every time AC_DEFINE is called. See section 7.3.1 Cache Variable Names.

For example, here is a `configure.ac' fragment written for Autoconf version 1:

AC_HAVE_FUNCS(syslog)
case "$DEFS" in
*-DHAVE_SYSLOG*) ;;
*) # syslog is not in the default libraries.  See if it's in some other.
  saved_LIBS="$LIBS"
  for lib in bsd socket inet; do
    AC_CHECKING(for syslog in -l$lib)
    LIBS="$saved_LIBS -l$lib"
    AC_HAVE_FUNCS(syslog)
    case "$DEFS" in
    *-DHAVE_SYSLOG*) break ;;
    *) ;;
    esac
    LIBS="$saved_LIBS"
  done ;;
esac

Here is a way to write it for version 2:

AC_CHECK_FUNCS(syslog)
if test $ac_cv_func_syslog = no; then
  # syslog is not in the default libraries.  See if it's in some other.
  for lib in bsd socket inet; do
    AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
      LIBS="$LIBS -l$lib"; break])
  done
fi

If you were working around bugs in AC_DEFINE_UNQUOTED by adding backslashes before quotes, you need to remove them. It now works predictably, and does not treat quotes (except back quotes) specially. See section 7.2 Setting Output Variables.

All of the boolean shell variables set by Autoconf macros now use `yes' for the true value. Most of them use `no' for false, though for backward compatibility some use the empty string instead. If you were relying on a shell variable being set to something like 1 or `t' for true, you need to change your tests.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.5.5 Changed Macro Writing

When defining your own macros, you should now use AC_DEFUN instead of define. AC_DEFUN automatically calls AC_PROVIDE and ensures that macros called via AC_REQUIRE do not interrupt other macros, to prevent nested `checking...' messages on the screen. There's no actual harm in continuing to use the older way, but it's less convenient and attractive. See section 9.1 Macro Definitions.

You probably looked at the macros that came with Autoconf as a guide for how to do things. It would be a good idea to take a look at the new versions of them, as the style is somewhat improved and they take advantage of some new features.

If you were doing tricky things with undocumented Autoconf internals (macros, variables, diversions), check whether you need to change anything to account for changes that have been made. Perhaps you can even use an officially supported technique in version 2 instead of kludging. Or perhaps not.

To speed up your locally written feature tests, add caching to them. See whether any of your tests are of general enough usefulness to encapsulate into macros that you can share.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.6 Upgrading From Version 2.13

The introduction of the previous section (see section 15.5 Upgrading From Version 1) perfectly suits this section...

Autoconf version 2.50 is mostly backward compatible with version 2.13. However, it introduces better ways to do some things, and doesn't support some of the ugly things in version 2.13. So, depending on how sophisticated your `configure.ac' files are, you might have to do some manual work in order to upgrade to version 2.50. This chapter points out some problems to watch for when upgrading. Also, perhaps your configure scripts could benefit from some of the new features in version 2.50; the changes are summarized in the file `NEWS' in the Autoconf distribution.

15.6.1 Changed Quotation | Broken code which used to work
15.6.2 New Macros | Interaction with foreign macros

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.6.1 Changed Quotation

The most important changes are invisible to you: the implementation of most macros have completely changed. This allowed more factorization of the code, better error messages, a higher uniformity of the user's interface etc. Unfortunately, as a side effect, some construct which used to (miraculously) work might break starting with Autoconf 2.50. The most common culprit is bad quotation.

For instance, in the following example, the message is not properly quoted:

AC_INIT
AC_CHECK_HEADERS(foo.h,,
AC_MSG_ERROR(cannot find foo.h, bailing out))
AC_OUTPUT

Autoconf 2.13 simply ignores it:

$ autoconf-2.13; ./configure --silent
creating cache ./config.cache
configure: error: cannot find foo.h
$

while Autoconf 2.50 will produce a broken `configure':

$ autoconf-2.50; ./configure --silent
configure: error: cannot find foo.h
./configure: exit: bad non-numeric arg `bailing'
./configure: exit: bad non-numeric arg `bailing'
$

The message needs to be quoted, and the AC_MSG_ERROR invocation too!

AC_INIT
AC_CHECK_HEADERS(foo.h,,
                 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
AC_OUTPUT

Many many (and many more) Autoconf macros were lacking proper quotation, including no less than... AC_DEFUN itself!

$ cat configure.in
AC_DEFUN([AC_PROG_INSTALL],
[# My own much better version
])
AC_INIT
AC_PROG_INSTALL
AC_OUTPUT
$ autoconf-2.13
autoconf: Undefined macros:
***BUG in Autoconf--please report*** AC_FD_MSG
***BUG in Autoconf--please report*** AC_EPI
configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
configure.in:5:AC_PROG_INSTALL
$ autoconf-2.50
$

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.6.2 New Macros

Because Autoconf has been dormant for years, Automake provided Autoconf-like macros for a while. Autoconf 2.50 now provides better versions of these macros, integrated in the AC_ namespace, instead of AM_. But in order to ease the upgrading via autoupdate, bindings to such AM_ macros are provided.

Unfortunately Automake did not quote the name of these macros! Therefore, when m4 find in `aclocal.m4' something like `AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)', AM_TYPE_PTRDIFF_T is expanded, replaced with its Autoconf definition.

Fortunately Autoconf catches pre-AC_INIT expansions, and will complain, in its own words:

$ cat configure.in
AC_INIT
AM_TYPE_PTRDIFF_T
$ aclocal-1.4
$ autoconf
./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from...
./aclocal.m4:17: the top level
$

Future versions of Automake will simply no longer define most of these macros, and will properly quote the names of the remaining macros. But you don't have to wait for it to happen to do the right thing right now: do not depend upon macros from Automake as it is simply not its job to provide macros (but the one it requires by itself):

$ cat configure.in
AC_INIT
AM_TYPE_PTRDIFF_T
$ rm aclocal.m4
$ autoupdate
autoupdate: `configure.in' is updated
$ cat configure.in
AC_INIT
AC_CHECK_TYPES([ptrdiff_t])
$ aclocal-1.4
$ autoconf
$

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16. Questions About Autoconf

Several questions about Autoconf come up occasionally. Here some of them are addressed.

16.1 Distributing configure Scripts | Distributing configure scripts
16.2 Why Require GNU M4? | Why not use the standard M4?
16.3 How Can I Bootstrap? | Autoconf and GNU M4 require each other?
16.4 Why Not Imake? | Why GNU uses configure instead of Imake

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1 Distributing configure Scripts

What are the restrictions on distributing configure
scripts that Autoconf generates?  How does that affect my
programs that use them?

There are no restrictions on how the configuration scripts that Autoconf produces may be distributed or used. In Autoconf version 1, they were covered by the GNU General Public License. We still encourage software authors to distribute their work under terms like those of the GPL, but doing so is not required to use Autoconf.

Of the other files that might be used with configure, `config.h.in' is under whatever copyright you use for your `configure.ac'. `config.sub' and `config.guess' have an exception to the GPL when they are used with an Autoconf-generated configure script, which permits you to distribute them under the same terms as the rest of your package. `install-sh' is from the X Consortium and is not copyrighted.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2 Why Require GNU M4?

Why does Autoconf require GNU M4?

Many M4 implementations have hard-coded limitations on the size and number of macros that Autoconf exceeds. They also lack several builtin macros that it would be difficult to get along without in a sophisticated application like Autoconf, including:

builtin
indir
patsubst
__file__
__line__

Autoconf requires version 1.4 or above of GNU M4 because it uses frozen state files.

Since only software maintainers need to use Autoconf, and since GNU M4 is simple to configure and install, it seems reasonable to require GNU M4 to be installed also. Many maintainers of GNU and other free software already have most of the GNU utilities installed, since they prefer them.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.3 How Can I Bootstrap?

If Autoconf requires GNU M4 and GNU M4 has an Autoconf
configure script, how do I bootstrap?  It seems like a chicken
and egg problem!

This is a misunderstanding. Although GNU M4 does come with a configure script produced by Autoconf, Autoconf is not required in order to run the script and install GNU M4. Autoconf is only required if you want to change the M4 configure script, which few people have to do (mainly its maintainer).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.4 Why Not Imake?

Why not use Imake instead of configure scripts?

Several people have written addressing this question, so I include adaptations of their explanations here.

The following answer is based on one written by Richard Pixley:

Autoconf generated scripts frequently work on machines that it has never been set up to handle before. That is, it does a good job of inferring a configuration for a new system. Imake cannot do this.

Imake uses a common database of host specific data. For X11, this makes sense because the distribution is made as a collection of tools, by one central authority who has control over the database.

GNU tools are not released this way. Each GNU tool has a maintainer; these maintainers are scattered across the world. Using a common database would be a maintenance nightmare. Autoconf may appear to be this kind of database, but in fact it is not. Instead of listing host dependencies, it lists program requirements.

If you view the GNU suite as a collection of native tools, then the problems are similar. But the GNU development tools can be configured as cross tools in almost any host+target permutation. All of these configurations can be installed concurrently. They can even be configured to share host independent files across hosts. Imake doesn't address these issues.

Imake templates are a form of standardization. The GNU coding standards address the same issues without necessarily imposing the same restrictions.

Here is some further explanation, written by Per Bothner:

One of the advantages of Imake is that it easy to generate large Makefiles using cpp's `#include' and macro mechanisms. However, cpp is not programmable: it has limited conditional facilities, and no looping. And cpp cannot inspect its environment.

All of these problems are solved by using sh instead of cpp. The shell is fully programmable, has macro substitution, can execute (or source) other shell scripts, and can inspect its environment.

Paul Eggert elaborates more:

With Autoconf, installers need not assume that Imake itself is already installed and working well. This may not seem like much of an advantage to people who are accustomed to Imake. But on many hosts Imake is not installed or the default installation is not working well, and requiring Imake to install a package hinders the acceptance of that package on those hosts. For example, the Imake template and configuration files might not be installed properly on a host, or the Imake build procedure might wrongly assume that all source files are in one big directory tree, or the Imake configuration might assume one compiler whereas the package or the installer needs to use another, or there might be a version mismatch between the Imake expected by the package and the Imake supported by the host. These problems are much rarer with Autoconf, where each package comes with its own independent configuration processor.

Also, Imake often suffers from unexpected interactions between make and the installer's C preprocessor. The fundamental problem here is that the C preprocessor was designed to preprocess C programs, not `Makefile's. This is much less of a problem with Autoconf, which uses the general-purpose preprocessor m4, and where the package's author (rather than the installer) does the preprocessing in a standard way.

Finally, Mark Eichin notes:

Imake isn't all that extensible, either. In order to add new features to Imake, you need to provide your own project template, and duplicate most of the features of the existing one. This means that for a sophisticated project, using the vendor-provided Imake templates fails to provide any leverage--since they don't cover anything that your own project needs (unless it is an X11 program).

On the other side, though:

The one advantage that Imake has over configure: `Imakefile's tend to be much shorter (likewise, less redundant) than `Makefile.in's. There is a fix to this, however--at least for the Kerberos V5 tree, we've modified things to call in common `post.in' and `pre.in' `Makefile' fragments for the entire tree. This means that a lot of common things don't have to be duplicated, even though they normally are in configure setups.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17. History of Autoconf

You may be wondering, Why was Autoconf originally written? How did it get into its present form? (Why does it look like gorilla spit?) If you're not wondering, then this chapter contains no information useful to you, and you might as well skip it. If you are wondering, then let there be light...

17.1 Genesis | Prehistory and naming of configure
17.2 Exodus | The plagues of M4 and Perl
17.3 Leviticus | The priestly code of portability arrives
17.4 Numbers | Growth and contributors
17.5 Deuteronomy | Approaching the promises of easy configuration

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17.1 Genesis

In June 1991 I was maintaining many of the GNU utilities for the Free Software Foundation. As they were ported to more platforms and more programs were added, the number of `-D' options that users had to select in the `Makefile' (around 20) became burdensome. Especially for me--I had to test each new release on a bunch of different systems. So I wrote a little shell script to guess some of the correct settings for the fileutils package, and released it as part of fileutils 2.0. That configure script worked well enough that the next month I adapted it (by hand) to create similar configure scripts for several other GNU utilities packages. Brian Berliner also adapted one of my scripts for his CVS revision control system.

Later that summer, I learned that Richard Stallman and Richard Pixley were developing similar scripts to use in the GNU compiler tools; so I adapted my configure scripts to support their evolving interface: using the file name `Makefile.in' as the templates; adding `+srcdir', the first option (of many); and creating `config.status' files.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17.2 Exodus

As I got feedback from users, I incorporated many improvements, using Emacs to search and replace, cut and paste, similar changes in each of the scripts. As I adapted more GNU utilities packages to use configure scripts, updating them all by hand became impractical. Rich Murphey, the maintainer of the GNU graphics utilities, sent me mail saying that the configure scripts were great, and asking if I had a tool for generating them that I could send him. No, I thought, but I should! So I started to work out how to generate them. And the journey from the slavery of hand-written configure scripts to the abundance and ease of Autoconf began.

Cygnus configure, which was being developed at around that time, is table driven; it is meant to deal mainly with a discrete number of system types with a small number of mainly unguessable features (such as details of the object file format). The automatic configuration system that Brian Fox had developed for Bash takes a similar approach. For general use, it seems to me a hopeless cause to try to maintain an up-to-date database of which features each variant of each operating system has. It's easier and more reliable to check for most features on the fly--especially on hybrid systems that people have hacked on locally or that have patches from vendors installed.

I considered using an architecture similar to that of Cygnus configure, where there is a single configure script that reads pieces of `configure.in' when run. But I didn't want to have to distribute all of the feature tests with every package, so I settled on having a different configure made from each `configure.in' by a preprocessor. That approach also offered more control and flexibility.

I looked briefly into using the Metaconfig package, by Larry Wall, Harlan Stenn, and Raphael Manfredi, but I decided not to for several reasons. The Configure scripts it produces are interactive, which I find quite inconvenient; I didn't like the ways it checked for some features (such as library functions); I didn't know that it was still being maintained, and the Configure scripts I had seen didn't work on many modern systems (such as System V R4 and NeXT); it wasn't very flexible in what it could do in response to a feature's presence or absence; I found it confusing to learn; and it was too big and complex for my needs (I didn't realize then how much Autoconf would eventually have to grow).

I considered using Perl to generate my style of configure scripts, but decided that M4 was better suited to the job of simple textual substitutions: it gets in the way less, because output is implicit. Plus, everyone already has it. (Initially I didn't rely on the GNU extensions to M4.) Also, some of my friends at the University of Maryland had recently been putting M4 front ends on several programs, including tvtwm, and I was interested in trying out a new language.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17.3 Leviticus

Since my configure scripts determine the system's capabilities automatically, with no interactive user intervention, I decided to call the program that generates them Autoconfig. But with a version number tacked on, that name would be too long for old UNIX file systems, so I shortened it to Autoconf.

In the fall of 1991 I called together a group of fellow questers after the Holy Grail of portability (er, that is, alpha testers) to give me feedback as I encapsulated pieces of my handwritten scripts in M4 macros and continued to add features and improve the techniques used in the checks. Prominent among the testers were Fran@,cois Pinard, who came up with the idea of making an `autoconf' shell script to run m4 and check for unresolved macro calls; Richard Pixley, who suggested running the compiler instead of searching the file system to find include files and symbols, for more accurate results; Karl Berry, who got Autoconf to configure TeX and added the macro index to the documentation; and Ian Lance Taylor, who added support for creating a C header file as an alternative to putting `-D' options in a `Makefile', so he could use Autoconf for his UUCP package. The alpha testers cheerfully adjusted their files again and again as the names and calling conventions of the Autoconf macros changed from release to release. They all contributed many specific checks, great ideas, and bug fixes.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17.4 Numbers

In July 1992, after months of alpha testing, I released Autoconf 1.0, and converted many GNU packages to use it. I was surprised by how positive the reaction to it was. More people started using it than I could keep track of, including people working on software that wasn't part of the GNU Project (such as TCL, FSP, and Kerberos V5). Autoconf continued to improve rapidly, as many people using the configure scripts reported problems they encountered.

Autoconf turned out to be a good torture test for M4 implementations. UNIX m4 started to dump core because of the length of the macros that Autoconf defined, and several bugs showed up in GNU m4 as well. Eventually, we realized that we needed to use some features that only GNU M4 has. 4.3BSD m4, in particular, has an impoverished set of builtin macros; the System V version is better, but still doesn't provide everything we need.

More development occurred as people put Autoconf under more stresses (and to uses I hadn't anticipated). Karl Berry added checks for X11. david zuhn contributed C++ support. Fran@,cois Pinard made it diagnose invalid arguments. Jim Blandy bravely coerced it into configuring GNU Emacs, laying the groundwork for several later improvements. Roland McGrath got it to configure the GNU C Library, wrote the autoheader script to automate the creation of C header file templates, and added a `--verbose' option to configure. Noah Friedman added the `--autoconf-dir' option and AC_MACRODIR environment variable. (He also coined the term autoconfiscate to mean "adapt a software package to use Autoconf".) Roland and Noah improved the quoting protection in AC_DEFINE and fixed many bugs, especially when I got sick of dealing with portability problems from February through June, 1993.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17.5 Deuteronomy

A long wish list for major features had accumulated, and the effect of several years of patching by various people had left some residual cruft. In April 1994, while working for Cygnus Support, I began a major revision of Autoconf. I added most of the features of the Cygnus configure that Autoconf had lacked, largely by adapting the relevant parts of Cygnus configure with the help of david zuhn and Ken Raeburn. These features include support for using `config.sub', `config.guess', `--host', and `--target'; making links to files; and running configure scripts in subdirectories. Adding these features enabled Ken to convert GNU as, and Rob Savoye to convert DejaGNU, to using Autoconf.

I added more features in response to other peoples' requests. Many people had asked for configure scripts to share the results of the checks between runs, because (particularly when configuring a large source tree, like Cygnus does) they were frustratingly slow. Mike Haertel suggested adding site-specific initialization scripts. People distributing software that had to unpack on MS-DOS asked for a way to override the `.in' extension on the file names, which produced file names like `config.h.in' containing two dots. Jim Avera did an extensive examination of the problems with quoting in AC_DEFINE and AC_SUBST; his insights led to significant improvements. Richard Stallman asked that compiler output be sent to `config.log' instead of `/dev/null', to help people debug the Emacs configure script.

I made some other changes because of my dissatisfaction with the quality of the program. I made the messages showing results of the checks less ambiguous, always printing a result. I regularized the names of the macros and cleaned up coding style inconsistencies. I added some auxiliary utilities that I had developed to help convert source code packages to use Autoconf. With the help of Fran@,cois Pinard, I made the macros not interrupt each others' messages. (That feature revealed some performance bottlenecks in GNU m4, which he hastily corrected!) I reorganized the documentation around problems people want to solve. And I began a test suite, because experience had shown that Autoconf has a pronounced tendency to regress when we change it.

Again, several alpha testers gave invaluable feedback, especially Fran@,cois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, and Mark Eichin.

Finally, version 2.0 was ready. And there was much rejoicing. (And I have free time again. I think. Yeah, right.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Environment Variable Index

This is an alphabetical list of the environment variables that Autoconf checks.

Jump to: A C I L N P R S W

 | Index Entry | Section
A |  |
 | AC_MACRODIR | 3.2 Using autoscan to Create `configure.ac'
 | AC_MACRODIR | 3.4 Using autoconf to Create configure
 | AC_MACRODIR | 3.5 Using autoreconf to Update configure Scripts
 | AC_MACRODIR | 4.7.2 Using autoheader to Create `config.h.in'
 | AC_MACRODIR | 15.3 Using autoupdate to Modernize `configure.ac'
C |  |
 | CDPATH | 10.7 Special Shell Variables
 | CONFIG_COMMANDS | 15.1 Obsolete `config.status' Invocation
 | CONFIG_FILES | 15.1 Obsolete `config.status' Invocation
 | CONFIG_HEADERS | 15.1 Obsolete `config.status' Invocation
 | CONFIG_LINKS | 15.1 Obsolete `config.status' Invocation
 | CONFIG_SHELL | 14. Recreating a Configuration
 | CONFIG_SITE | 12.6 Setting Site Defaults
 | CONFIG_STATUS | 14. Recreating a Configuration
I |  |
 | IFS | 10.7 Special Shell Variables
L |  |
 | LANG | 10.7 Special Shell Variables
 | LANGUAGE | 10.7 Special Shell Variables
 | LC_ALL | 10.7 Special Shell Variables
 | LC_COLLATE | 10.7 Special Shell Variables
 | LC_CTYPE | 10.7 Special Shell Variables
 | LC_MESSAGES | 10.7 Special Shell Variables
 | LC_NUMERIC | 10.7 Special Shell Variables
 | LC_TIME | 10.7 Special Shell Variables
N |  |
 | NULLCMD | 10.7 Special Shell Variables
P |  |
 | PATH_SEPARATOR | 10.7 Special Shell Variables
R |  |
 | RANDOM | 10.7 Special Shell Variables
S |  |
 | SIMPLE_BACKUP_SUFFIX | 15.3 Using autoupdate to Modernize `configure.ac'
 | status | 10.7 Special Shell Variables
W |  |
 | WARNINGS | 3.4 Using autoconf to Create configure
 | WARNINGS | 4.7.2 Using autoheader to Create `config.h.in'

Jump to: A C I L N P R S W

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Output Variable Index

This is an alphabetical list of the variables that Autoconf can substitute into files that it creates, typically one or more `Makefile's. See section 7.2 Setting Output Variables, for more information on how this is done.

Jump to: A B C D E F G H I K L M N O P R S T X Y

 | Index Entry | Section
A |  |
 | ALLOCA | 5.5.2 Particular Function Checks
 | AWK | 5.2.1 Particular Program Checks
B |  |
 | bindir | 4.6.2 Installation Directory Variables
 | build | 11.2 Getting the Canonical System Type
 | build_alias | 11.2 Getting the Canonical System Type
 | build_cpu | 11.2 Getting the Canonical System Type
 | build_os | 11.2 Getting the Canonical System Type
 | build_vendor | 11.2 Getting the Canonical System Type
C |  |
 | CC | 5.10.2 C Compiler Characteristics
 | CC | 5.10.2 C Compiler Characteristics
 | CC | 5.10.2 C Compiler Characteristics
 | CC | 5.11 System Services
 | CC | 5.12 UNIX Variants
 | CFLAGS | 4.6.1 Preset Output Variables
 | CFLAGS | 5.10.2 C Compiler Characteristics
 | configure_input | 4.6.1 Preset Output Variables
 | CPP | 5.10.2 C Compiler Characteristics
 | CPPFLAGS | 4.6.1 Preset Output Variables
 | cross_compiling | 11.1 Specifying the System Type
 | CXX | 5.10.3 C++ Compiler Characteristics
 | CXXCPP | 5.10.3 C++ Compiler Characteristics
 | CXXFLAGS | 4.6.1 Preset Output Variables
 | CXXFLAGS | 5.10.3 C++ Compiler Characteristics
D |  |
 | datadir | 4.6.2 Installation Directory Variables
 | DEFS | 4.6.1 Preset Output Variables
E |  |
 | ECHO_C | 4.6.1 Preset Output Variables
 | ECHO_N | 4.6.1 Preset Output Variables
 | ECHO_T | 4.6.1 Preset Output Variables
 | exec_prefix | 4.6.2 Installation Directory Variables
 | EXEEXT | 5.10 Compilers and Preprocessors
 | EXEEXT | 15.4 Obsolete Macros
F |  |
 | F77 | 5.10.4 Fortran 77 Compiler Characteristics
 | FFLAGS | 4.6.1 Preset Output Variables
 | FFLAGS | 5.10.4 Fortran 77 Compiler Characteristics
 | FLIBS | 5.10.4 Fortran 77 Compiler Characteristics
G |  |
 | GETGROUPS_LIBS | 5.5.2 Particular Function Checks
 | GETLOADAVG_LIBS | 5.5.2 Particular Function Checks
H |  |
 | host | 11.2 Getting the Canonical System Type
 | host_alias | 11.2 Getting the Canonical System Type
 | host_cpu | 11.2 Getting the Canonical System Type
 | host_os | 11.2 Getting the Canonical System Type
 | host_vendor | 11.2 Getting the Canonical System Type
I |  |
 | includedir | 4.6.2 Installation Directory Variables
 | infodir | 4.6.2 Installation Directory Variables
 | INSTALL | 5.2.1 Particular Program Checks
 | INSTALL_DATA | 5.2.1 Particular Program Checks
 | INSTALL_PROGRAM | 5.2.1 Particular Program Checks
 | INSTALL_SCRIPT | 5.2.1 Particular Program Checks
K |  |
 | KMEM_GROUP | 5.5.2 Particular Function Checks
L |  |
 | LDFLAGS | 4.6.1 Preset Output Variables
 | LEX | 5.2.1 Particular Program Checks
 | LEX_OUTPUT_ROOT | 5.2.1 Particular Program Checks
 | LEXLIB | 5.2.1 Particular Program Checks
 | libdir | 4.6.2 Installation Directory Variables
 | libexecdir | 4.6.2 Installation Directory Variables
 | LIBOBJS | 5.5.2 Particular Function Checks
 | LIBOBJS | 5.5.2 Particular Function Checks
 | LIBOBJS | 5.5.2 Particular Function Checks
 | LIBOBJS | 5.5.3 Generic Function Checks
 | LIBOBJS | 5.5.3 Generic Function Checks
 | LIBOBJS | 5.8.1 Particular Structure Checks
 | LIBS | 4.6.1 Preset Output Variables
 | LIBS | 15.4 Obsolete Macros
 | LIBS | 15.4 Obsolete Macros
 | LN_S | 5.2.1 Particular Program Checks
 | localstatedir | 4.6.2 Installation Directory Variables
M |  |
 | mandir | 4.6.2 Installation Directory Variables
N |  |
 | NEED_SETGID | 5.5.2 Particular Function Checks
O |  |
 | OBJEXT | 5.10 Compilers and Preprocessors
 | OBJEXT | 15.4 Obsolete Macros
 | oldincludedir | 4.6.2 Installation Directory Variables
P |  |
 | POW_LIB | 5.5.2 Particular Function Checks
 | prefix | 4.6.2 Installation Directory Variables
 | program_transform_name | 12.5 Transforming Program Names When Installing
R |  |
 | RANLIB | 5.2.1 Particular Program Checks
S |  |
 | sbindir | 4.6.2 Installation Directory Variables
 | SET_MAKE | 4.3 Outputting Files
 | sharedstatedir | 4.6.2 Installation Directory Variables
 | srcdir | 4.6.1 Preset Output Variables
 | subdirs | 4.10 Configuring Other Packages in Subdirectories
 | sysconfdir | 4.6.2 Installation Directory Variables
T |  |
 | target | 11.2 Getting the Canonical System Type
 | target_alias | 11.2 Getting the Canonical System Type
 | target_cpu | 11.2 Getting the Canonical System Type
 | target_os | 11.2 Getting the Canonical System Type
 | target_vendor | 11.2 Getting the Canonical System Type
 | top_srcdir | 4.6.1 Preset Output Variables
X |  |
 | X_CFLAGS | 5.11 System Services
 | X_EXTRA_LIBS | 5.11 System Services
 | X_LIBS | 5.11 System Services
 | X_PRE_LIBS | 5.11 System Services
Y |  |
 | YACC | 5.2.1 Particular Program Checks

Jump to: A B C D E F G H I K L M N O P R S T X Y

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Preprocessor Symbol Index

This is an alphabetical list of the C preprocessor symbols that the Autoconf macros define. To work with Autoconf, C source code needs to use these names in #if directives.

Jump to: _
C D F G H I L M N O P R S T U V W X Y

 | Index Entry | Section
_ |  |
 | __CHAR_UNSIGNED__ | 5.10.2 C Compiler Characteristics
 | _ALL_SOURCE | 5.12 UNIX Variants
 | _FILE_OFFSET_BITS | 5.11 System Services
 | _LARGE_FILES | 5.11 System Services
 | _LARGEFILE_SOURCE | 5.5.2 Particular Function Checks
 | _MINIX | 5.12 UNIX Variants
 | _POSIX_1_SOURCE | 5.12 UNIX Variants
 | _POSIX_SOURCE | 5.12 UNIX Variants
 | _POSIX_SOURCE | 5.12 UNIX Variants
 | _POSIX_VERSION | 5.6.1 Particular Header Checks
C |  |
 | C_ALLOCA | 5.5.2 Particular Function Checks
 | C_GETLOADAVG | 5.5.2 Particular Function Checks
 | CLOSEDIR_VOID | 5.5.2 Particular Function Checks
 | const | 5.10.2 C Compiler Characteristics
D |  |
 | DGUX | 5.5.2 Particular Function Checks
 | DIRENT | 15.4 Obsolete Macros
F |  |
 | F77_DUMMY_MAIN | 5.10.4 Fortran 77 Compiler Characteristics
 | F77_FUNC | 5.10.4 Fortran 77 Compiler Characteristics
 | F77_FUNC_ | 5.10.4 Fortran 77 Compiler Characteristics
 | F77_MAIN | 5.10.4 Fortran 77 Compiler Characteristics
 | F77_NO_MINUS_C_MINUS_O | 5.10.4 Fortran 77 Compiler Characteristics
G |  |
 | GETGROUPS_T | 5.9.1 Particular Type Checks
 | GETLODAVG_PRIVILEGED | 5.5.2 Particular Function Checks
 | GETPGRP_VOID | 5.5.2 Particular Function Checks
 | gid_t | 5.9.1 Particular Type Checks
 | GWINSZ_IN_SYS_IOCTL | 5.6.1 Particular Header Checks
H |  |
 | HAVE_ALLOCA_H | 5.5.2 Particular Function Checks
 | HAVE_CONFIG_H | 4.7 Configuration Header Files
 | HAVE_DECL_symbol | 5.7.2 Generic Declaration Checks
 | HAVE_DIRENT_H | 5.6.1 Particular Header Checks
 | HAVE_DOPRNT | 5.5.2 Particular Function Checks
 | HAVE_function | 5.5.3 Generic Function Checks
 | HAVE_GETMNTENT | 5.5.2 Particular Function Checks
 | HAVE_header | 5.6.2 Generic Header Checks
 | HAVE_LONG_DOUBLE | 5.10.2 C Compiler Characteristics
 | HAVE_LONG_FILE_NAMES | 5.11 System Services
 | HAVE_LSTAT_EMPTY_STRING_BUG | 5.5.2 Particular Function Checks
 | HAVE_MMAP | 5.5.2 Particular Function Checks
 | HAVE_NDIR_H | 5.6.1 Particular Header Checks
 | HAVE_OBSTACK | 5.5.2 Particular Function Checks
 | HAVE_RESTARTABLE_SYSCALLS | 15.4 Obsolete Macros
 | HAVE_ST_BLKSIZE | 5.8.1 Particular Structure Checks
 | HAVE_ST_BLOCKS | 5.8.1 Particular Structure Checks
 | HAVE_ST_RDEV | 5.8.1 Particular Structure Checks
 | HAVE_STAT_EMPTY_STRING_BUG | 5.5.2 Particular Function Checks
 | HAVE_STRCOLL | 5.5.2 Particular Function Checks
 | HAVE_STRERROR_R | 5.5.2 Particular Function Checks
 | HAVE_STRFTIME | 5.5.2 Particular Function Checks
 | HAVE_STRINGIZE | 5.10.2 C Compiler Characteristics
 | HAVE_STRUCT_STAT_ST_BLKSIZE | 5.8.1 Particular Structure Checks
 | HAVE_STRUCT_STAT_ST_BLOCKS | 5.8.1 Particular Structure Checks
 | HAVE_STRUCT_STAT_ST_RDEV | 5.8.1 Particular Structure Checks
 | HAVE_SYS_DIR_H | 5.6.1 Particular Header Checks
 | HAVE_SYS_NDIR_H | 5.6.1 Particular Header Checks
 | HAVE_SYS_WAIT_H | 5.6.1 Particular Header Checks
 | HAVE_TM_ZONE | 5.8.1 Particular Structure Checks
 | HAVE_TZNAME | 5.8.1 Particular Structure Checks
 | HAVE_UTIME_NULL | 5.5.2 Particular Function Checks
 | HAVE_VFORK_H | 5.5.2 Particular Function Checks
 | HAVE_VPRINTF | 5.5.2 Particular Function Checks
 | HAVE_WAIT3 | 15.4 Obsolete Macros
 | HAVE_WORKING_FORK | 5.5.2 Particular Function Checks
 | HAVE_WORKING_STRERROR_R | 5.5.2 Particular Function Checks
 | HAVE_WORKING_VFORK | 5.5.2 Particular Function Checks
I |  |
 | inline | 5.10.2 C Compiler Characteristics
 | INT_16_BITS | 15.4 Obsolete Macros
L |  |
 | LONG_64_BITS | 15.4 Obsolete Macros
 | LSTAT_FOLLOWS_SLASHED_SYMLINK | 5.5.2 Particular Function Checks
M |  |
 | MAJOR_IN_MKDEV | 5.6.1 Particular Header Checks
 | MAJOR_IN_SYSMACROS | 5.6.1 Particular Header Checks
 | mode_t | 5.9.1 Particular Type Checks
N |  |
 | NDIR | 15.4 Obsolete Macros
 | NEED_MEMORY_H | 15.4 Obsolete Macros
 | NEED_SETGID | 5.5.2 Particular Function Checks
 | NLIST_NAME_UNION | 5.5.2 Particular Function Checks
 | NLIST_STRUCT | 5.5.2 Particular Function Checks
 | NO_MINUS_C_MINUS_O | 5.10.2 C Compiler Characteristics
O |  |
 | off_t | 5.9.1 Particular Type Checks
P |  |
 | PARAMS | 5.10.2 C Compiler Characteristics
 | pid_t | 5.9.1 Particular Type Checks
 | PROTOTYPES | 5.10.2 C Compiler Characteristics
R |  |
 | RETSIGTYPE | 5.9.1 Particular Type Checks
S |  |
 | SELECT_TYPE_ARG1 | 5.5.2 Particular Function Checks
 | SELECT_TYPE_ARG234 | 5.5.2 Particular Function Checks
 | SELECT_TYPE_ARG5 | 5.5.2 Particular Function Checks
 | SETPGRP_VOID | 5.5.2 Particular Function Checks
 | SETVBUF_REVERSED | 5.5.2 Particular Function Checks
 | size_t | 5.9.1 Particular Type Checks
 | STDC_HEADERS | 5.6.1 Particular Header Checks
 | SVR4 | 5.5.2 Particular Function Checks
 | SYS_SIGLIST_DECLARED | 5.7.1 Particular Declaration Checks
 | SYSDIR | 15.4 Obsolete Macros
 | SYSNDIR | 15.4 Obsolete Macros
T |  |
 | TIME_WITH_SYS_TIME | 5.6.1 Particular Header Checks
 | TM_IN_SYS_TIME | 5.8.1 Particular Structure Checks
U |  |
 | uid_t | 5.9.1 Particular Type Checks
 | UMAX | 5.5.2 Particular Function Checks
 | UMAX4_3 | 5.5.2 Particular Function Checks
 | USG | 15.4 Obsolete Macros
V |  |
 | vfork | 5.5.2 Particular Function Checks
 | volatile | 5.10.2 C Compiler Characteristics
W |  |
 | WORDS_BIGENDIAN | 5.10.2 C Compiler Characteristics
X |  |
 | X_DISPLAY_MISSING | 5.11 System Services
Y |  |
 | YYTEXT_POINTER | 5.2.1 Particular Program Checks

Jump to: _
C D F G H I L M N O P R S T U V W X Y

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Autoconf Macro Index

This is an alphabetical list of the Autoconf macros. To make the list easier to use, the macros are listed without their preceding `AC_'.

Jump to: A B C D E F G H I L M O P R S T U V W X Y

 | Index Entry | Section
A |  |
 | AH_BOTTOM | 4.7.3 Autoheader Macros
 | AH_TEMPLATE | 4.7.3 Autoheader Macros
 | AH_TOP | 4.7.3 Autoheader Macros
 | AH_VERBATIM | 4.7.3 Autoheader Macros
 | AIX | 5.12 UNIX Variants
 | ALLOCA | 15.4 Obsolete Macros
 | ARG_ARRAY | 15.4 Obsolete Macros
 | ARG_ENABLE | 12.2 Choosing Package Options
 | ARG_PROGRAM | 12.5 Transforming Program Names When Installing
 | ARG_VAR | 7.2 Setting Output Variables
 | ARG_WITH | 12.1 Working With External Software
 | AU_DEFUN | 9.5 Obsoleting Macros
B |  |
 | BEFORE | 9.4.2 Suggested Ordering
 | BOTTOM | 4.7.3 Autoheader Macros
C |  |
 | C_BIGENDIAN | 5.10.2 C Compiler Characteristics
 | C_CHAR_UNSIGNED | 5.10.2 C Compiler Characteristics
 | C_CONST | 5.10.2 C Compiler Characteristics
 | C_CROSS | 15.4 Obsolete Macros
 | C_INLINE | 5.10.2 C Compiler Characteristics
 | C_LONG_DOUBLE | 5.10.2 C Compiler Characteristics
 | C_PROTOTYPES | 5.10.2 C Compiler Characteristics
 | C_STRINGIZE | 5.10.2 C Compiler Characteristics
 | C_VOLATILE | 5.10.2 C Compiler Characteristics
 | CACHE_CHECK | 7.3 Caching Results
 | CACHE_LOAD | 7.3.3 Cache Checkpointing
 | CACHE_SAVE | 7.3.3 Cache Checkpointing
 | CACHE_VAL | 7.3 Caching Results
 | CANONICAL_BUILD | 11.2 Getting the Canonical System Type
 | CANONICAL_HOST | 11.2 Getting the Canonical System Type
 | CANONICAL_SYSTEM | 15.4 Obsolete Macros
 | CANONICAL_TARGET | 11.2 Getting the Canonical System Type
 | CHAR_UNSIGNED | 15.4 Obsolete Macros
 | CHECK_DECL | 5.7.2 Generic Declaration Checks
 | CHECK_DECLS | 5.7.2 Generic Declaration Checks
 | CHECK_FILE | 5.3 Files
 | CHECK_FILES | 5.3 Files
 | CHECK_FUNC | 5.5.3 Generic Function Checks
 | CHECK_FUNCS | 5.5.3 Generic Function Checks
 | CHECK_HEADER | 5.6.2 Generic Header Checks
 | CHECK_HEADERS | 5.6.2 Generic Header Checks
 | CHECK_LIB | 5.4 Library Files
 | CHECK_MEMBER | 5.8.2 Generic Structure Checks
 | CHECK_MEMBERS | 5.8.2 Generic Structure Checks
 | CHECK_PROG | 5.2.2 Generic Program and File Checks
 | CHECK_PROGS | 5.2.2 Generic Program and File Checks
 | CHECK_SIZEOF | 5.10.1 Generic Compiler Characteristics
 | CHECK_TOOL | 5.2.2 Generic Program and File Checks
 | CHECK_TOOLS | 5.2.2 Generic Program and File Checks
 | CHECK_TYPE | 5.9.2 Generic Type Checks
 | CHECK_TYPE | 15.4 Obsolete Macros
 | CHECK_TYPES | 5.9.2 Generic Type Checks
 | CHECKING | 15.4 Obsolete Macros
 | COMPILE_CHECK | 15.4 Obsolete Macros
 | CONFIG_AUX_DIR | 4.2 Finding configure Input
 | CONFIG_COMMANDS | 4.8 Running Arbitrary Configuration Commands
 | CONFIG_FILES | 4.5 Creating Configuration Files
 | CONFIG_HEADERS | 4.7 Configuration Header Files
 | CONFIG_LINKS | 4.9 Creating Configuration Links
 | CONFIG_SRCDIR | 4.2 Finding configure Input
 | CONFIG_SUBDIRS | 4.10 Configuring Other Packages in Subdirectories
 | CONST | 15.4 Obsolete Macros
 | COPYRIGHT | 4.1 Notices in configure
 | CROSS_CHECK | 15.4 Obsolete Macros
 | CYGWIN | 15.4 Obsolete Macros
D |  |
 | DECL_SYS_SIGLIST | 5.7.1 Particular Declaration Checks
 | DECL_YYTEXT | 15.4 Obsolete Macros
 | DEFINE | 7.1 Defining C Preprocessor Symbols
 | DEFINE_UNQUOTED | 7.1 Defining C Preprocessor Symbols
 | DEFUN | 9.1 Macro Definitions
 | DEFUN | 9.5 Obsoleting Macros
 | DIAGNOSE | 9.3 Reporting Messages
 | DIR_HEADER | 15.4 Obsolete Macros
 | DYNIX_SEQ | 15.4 Obsolete Macros
E |  |
 | EGREP_CPP | 6.1 Examining Declarations
 | EGREP_HEADER | 6.1 Examining Declarations
 | EMXOS2 | 15.4 Obsolete Macros
 | ENABLE | 12.2 Choosing Package Options
 | ERROR | 15.4 Obsolete Macros
 | EXEEXT | 15.4 Obsolete Macros
F |  |
 | F77_DUMMY_MAIN | 5.10.4 Fortran 77 Compiler Characteristics
 | F77_FUNC | 5.10.4 Fortran 77 Compiler Characteristics
 | F77_LIBRARY_LDFLAGS | 5.10.4 Fortran 77 Compiler Characteristics
 | F77_MAIN | 5.10.4 Fortran 77 Compiler Characteristics
 | F77_WRAPPERS | 5.10.4 Fortran 77 Compiler Characteristics
 | FATAL | 9.3 Reporting Messages
 | FIND_X | 15.4 Obsolete Macros
 | FIND_XTRA | 15.4 Obsolete Macros
 | FUNC_ALLOCA | 5.5.2 Particular Function Checks
 | FUNC_CHECK | 15.4 Obsolete Macros
 | FUNC_CHOWN | 5.5.2 Particular Function Checks
 | FUNC_CLOSEDIR_VOID | 5.5.2 Particular Function Checks
 | FUNC_ERROR_AT_LINE | 5.5.2 Particular Function Checks
 | FUNC_FNMATCH | 5.5.2 Particular Function Checks
 | FUNC_FORK | 5.5.2 Particular Function Checks
 | FUNC_FSEEKO | 5.5.2 Particular Function Checks
 | FUNC_GETGROUPS | 5.5.2 Particular Function Checks
 | FUNC_GETLOADAVG | 5.5.2 Particular Function Checks
 | FUNC_GETMNTENT | 5.5.2 Particular Function Checks
 | FUNC_GETPGRP | 5.5.2 Particular Function Checks
 | FUNC_LSTAT | 5.5.2 Particular Function Checks
 | FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK | 5.5.2 Particular Function Checks
 | FUNC_MALLOC | 5.5.2 Particular Function Checks
 | FUNC_MEMCMP | 5.5.2 Particular Function Checks
 | FUNC_MKTIME | 5.5.2 Particular Function Checks
 | FUNC_MMAP | 5.5.2 Particular Function Checks
 | FUNC_OBSTACK | 5.5.2 Particular Function Checks
 | FUNC_SELECT_ARGTYPES | 5.5.2 Particular Function Checks
 | FUNC_SETPGRP | 5.5.2 Particular Function Checks
 | FUNC_SETVBUF_REVERSED | 5.5.2 Particular Function Checks
 | FUNC_STAT | 5.5.2 Particular Function Checks
 | FUNC_STRCOLL | 5.5.2 Particular Function Checks
 | FUNC_STRERROR_R | 5.5.2 Particular Function Checks
 | FUNC_STRFTIME | 5.5.2 Particular Function Checks
 | FUNC_STRTOD | 5.5.2 Particular Function Checks
 | FUNC_UTIME_NULL | 5.5.2 Particular Function Checks
 | FUNC_VPRINTF | 5.5.2 Particular Function Checks
 | FUNC_WAIT3 | 15.4 Obsolete Macros
G |  |
 | GCC_TRADITIONAL | 15.4 Obsolete Macros
 | GETGROUPS_T | 15.4 Obsolete Macros
 | GETLOADAVG | 15.4 Obsolete Macros
H |  |
 | HAVE_FUNCS | 15.4 Obsolete Macros
 | HAVE_HEADERS | 15.4 Obsolete Macros
 | HAVE_LIBRARY | 15.4 Obsolete Macros
 | HAVE_POUNDBANG | 15.4 Obsolete Macros
 | HEADER_CHECK | 15.4 Obsolete Macros
 | HEADER_DIRENT | 5.6.1 Particular Header Checks
 | HEADER_EGREP | 15.4 Obsolete Macros
 | HEADER_MAJOR | 5.6.1 Particular Header Checks
 | HEADER_STAT | 5.6.1 Particular Header Checks
 | HEADER_STDC | 5.6.1 Particular Header Checks
 | HEADER_SYS_WAIT | 5.6.1 Particular Header Checks
 | HEADER_TIME | 5.6.1 Particular Header Checks
 | HEADER_TIOCGWINSZ | 5.6.1 Particular Header Checks
 | HELP_STRING | 12.3 Making Your Help Strings Look Pretty
I |  |
 | INIT | 4.2 Finding configure Input
 | INIT | 15.4 Obsolete Macros
 | INLINE | 15.4 Obsolete Macros
 | INT_16_BITS | 15.4 Obsolete Macros
 | IRIX_SUN | 15.4 Obsolete Macros
 | ISC_POSIX | 5.12 UNIX Variants
L |  |
 | LANG_C | 15.4 Obsolete Macros
 | LANG_CPLUSPLUS | 15.4 Obsolete Macros
 | LANG_FORTRAN77 | 15.4 Obsolete Macros
 | LANG_POP | 6.7 Language Choice
 | LANG_PUSH | 6.7 Language Choice
 | LANG_RESTORE | 15.4 Obsolete Macros
 | LANG_SAVE | 15.4 Obsolete Macros
 | LIBOBJ | 5.5.3 Generic Function Checks
 | LIBSOURCE | 5.5.3 Generic Function Checks
 | LIBSOURCES | 5.5.3 Generic Function Checks
 | LINK_FILES | 15.4 Obsolete Macros
 | LN_S | 15.4 Obsolete Macros
 | LONG_64_BITS | 15.4 Obsolete Macros
 | LONG_DOUBLE | 15.4 Obsolete Macros
 | LONG_FILE_NAMES | 15.4 Obsolete Macros
M |  |
 | MAJOR_HEADER | 15.4 Obsolete Macros
 | MEMORY_H | 15.4 Obsolete Macros
 | MINGW32 | 15.4 Obsolete Macros
 | MINIX | 5.12 UNIX Variants
 | MINUS_C_MINUS_O | 15.4 Obsolete Macros
 | MMAP | 15.4 Obsolete Macros
 | MODE_T | 15.4 Obsolete Macros
 | MSG_CHECKING | 7.4 Printing Messages
 | MSG_ERROR | 7.4 Printing Messages
 | MSG_NOTICE | 7.4 Printing Messages
 | MSG_RESULT | 7.4 Printing Messages
 | MSG_WARN | 7.4 Printing Messages
O |  |
 | OBJEXT | 15.4 Obsolete Macros
 | OBSOLETE | 15.4 Obsolete Macros
 | OFF_T | 15.4 Obsolete Macros
 | OUTPUT | 4.3 Outputting Files
 | OUTPUT | 15.4 Obsolete Macros
 | OUTPUT_COMMANDS | 15.4 Obsolete Macros
 | OUTPUT_COMMANDS_POST | 4.8 Running Arbitrary Configuration Commands
 | OUTPUT_COMMANDS_PRE | 4.8 Running Arbitrary Configuration Commands
P |  |
 | PATH_PROG | 5.2.2 Generic Program and File Checks
 | PATH_PROGS | 5.2.2 Generic Program and File Checks
 | PATH_TOOL | 5.2.2 Generic Program and File Checks
 | PATH_X | 5.11 System Services
 | PATH_XTRA | 5.11 System Services
 | PID_T | 15.4 Obsolete Macros
 | PREFIX | 15.4 Obsolete Macros
 | PREFIX_DEFAULT | 4.11 Default Prefix
 | PREFIX_PROGRAM | 4.11 Default Prefix
 | PREREQ | 4.1 Notices in configure
 | PROG_AWK | 5.2.1 Particular Program Checks
 | PROG_CC | 5.10.2 C Compiler Characteristics
 | PROG_CC_C_O | 5.10.2 C Compiler Characteristics
 | PROG_CC_STDC | 5.10.2 C Compiler Characteristics
 | PROG_CPP | 5.10.2 C Compiler Characteristics
 | PROG_CXX | 5.10.3 C++ Compiler Characteristics
 | PROG_CXXCPP | 5.10.3 C++ Compiler Characteristics
 | PROG_F77_C_O | 5.10.4 Fortran 77 Compiler Characteristics
 | PROG_FORTRAN | 5.10.4 Fortran 77 Compiler Characteristics
 | PROG_GCC_TRADITIONAL | 5.10.2 C Compiler Characteristics
 | PROG_INSTALL | 5.2.1 Particular Program Checks
 | PROG_LEX | 5.2.1 Particular Program Checks
 | PROG_LN_S | 5.2.1 Particular Program Checks
 | PROG_MAKE_SET | 4.3 Outputting Files
 | PROG_RANLIB | 5.2.1 Particular Program Checks
 | PROG_YACC | 5.2.1 Particular Program Checks
 | PROGRAM_CHECK | 15.4 Obsolete Macros
 | PROGRAM_EGREP | 15.4 Obsolete Macros
 | PROGRAM_PATH | 15.4 Obsolete Macros
 | PROGRAMS_CHECK | 15.4 Obsolete Macros
 | PROGRAMS_PATH | 15.4 Obsolete Macros
R |  |
 | REMOTE_TAPE | 15.4 Obsolete Macros
 | REPLACE_FUNCS | 5.5.3 Generic Function Checks
 | REQUIRE | 9.4.1 Prerequisite Macros
 | REQUIRE_CPP | 6.7 Language Choice
 | RESTARTABLE_SYSCALLS | 15.4 Obsolete Macros
 | RETSIGTYPE | 15.4 Obsolete Macros
 | REVISION | 4.1 Notices in configure
 | RSH | 15.4 Obsolete Macros
S |  |
 | SCO_INTL | 15.4 Obsolete Macros
 | SEARCH_LIBS | 5.4 Library Files
 | SET_MAKE | 15.4 Obsolete Macros
 | SETVBUF_REVERSED | 15.4 Obsolete Macros
 | SIZE_T | 15.4 Obsolete Macros
 | SIZEOF_TYPE | 15.4 Obsolete Macros
 | ST_BLKSIZE | 15.4 Obsolete Macros
 | ST_BLOCKS | 15.4 Obsolete Macros
 | ST_RDEV | 15.4 Obsolete Macros
 | STAT_MACROS_BROKEN | 5.6.1 Particular Header Checks
 | STAT_MACROS_BROKEN | 15.4 Obsolete Macros
 | STDC_HEADERS | 15.4 Obsolete Macros
 | STRCOLL | 15.4 Obsolete Macros
 | STRUCT_ST_BLKSIZE | 5.8.1 Particular Structure Checks
 | STRUCT_ST_BLOCKS | 5.8.1 Particular Structure Checks
 | STRUCT_ST_RDEV | 5.8.1 Particular Structure Checks
 | STRUCT_TIMEZONE | 5.8.1 Particular Structure Checks
 | STRUCT_TM | 5.8.1 Particular Structure Checks
 | SUBST | 7.2 Setting Output Variables
 | SUBST_FILE | 7.2 Setting Output Variables
 | SYS_INTERPRETER | 5.11 System Services
 | SYS_LARGEFILE | 5.11 System Services
 | SYS_LONG_FILE_NAMES | 5.11 System Services
 | SYS_POSIX_TERMIOS | 5.11 System Services
 | SYS_RESTARTABLE_SYSCALLS | 15.4 Obsolete Macros
 | SYS_SIGLIST_DECLARED | 15.4 Obsolete Macros
T |  |
 | TEMPLATE | 4.7.3 Autoheader Macros
 | TEST_CPP | 15.4 Obsolete Macros
 | TEST_PROGRAM | 15.4 Obsolete Macros
 | TIME_WITH_SYS_TIME | 15.4 Obsolete Macros
 | TIMEZONE | 15.4 Obsolete Macros
 | TOP | 4.7.3 Autoheader Macros
 | TRY_COMPILE | 6.2 Examining Syntax
 | TRY_CPP | 6.1 Examining Declarations
 | TRY_LINK | 6.3 Examining Libraries
 | TRY_LINK_FUNC | 6.3 Examining Libraries
 | TRY_RUN | 6.4.1 Running Test Programs
 | TYPE_GETGROUPS | 5.9.1 Particular Type Checks
 | TYPE_MODE_T | 5.9.1 Particular Type Checks
 | TYPE_OFF_T | 5.9.1 Particular Type Checks
 | TYPE_PID_T | 5.9.1 Particular Type Checks
 | TYPE_SIGNAL | 5.9.1 Particular Type Checks
 | TYPE_SIZE_T | 5.9.1 Particular Type Checks
 | TYPE_UID_T | 5.9.1 Particular Type Checks
U |  |
 | UID_T | 15.4 Obsolete Macros
 | UNISTD_H | 15.4 Obsolete Macros
 | USG | 15.4 Obsolete Macros
 | UTIME_NULL | 15.4 Obsolete Macros
V |  |
 | VALIDATE_CACHED_SYSTEM_TUPLE | 15.4 Obsolete Macros
 | VERBATIM | 4.7.3 Autoheader Macros
 | VERBOSE | 15.4 Obsolete Macros
 | VFORK | 15.4 Obsolete Macros
 | VPRINTF | 15.4 Obsolete Macros
W |  |
 | WAIT3 | 15.4 Obsolete Macros
 | WARN | 15.4 Obsolete Macros
 | WARNING | 9.3 Reporting Messages
 | WITH | 12.1 Working With External Software
 | WORDS_BIGENDIAN | 15.4 Obsolete Macros
X |  |
 | XENIX_DIR | 15.4 Obsolete Macros
Y |  |
 | YYTEXT_POINTER | 15.4 Obsolete Macros

Jump to: A B C D E F G H I L M O P R S T U V W X Y

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

M4 Macro Index

This is an alphabetical list of the M4, M4sugar, and M4sh macros. To make the list easier to use, the macros are listed without their preceding `m4_' or `AS_'.

Jump to: D P U

 | Index Entry | Section
D |  |
 | defn | 8.2.1 Redefined M4 Macros
 | defn | 8.2.1 Redefined M4 Macros
P |  |
 | pattern_allow | 8.2.2 Forbidden Patterns
 | pattern_forbid | 8.2.2 Forbidden Patterns
U |  |
 | undefine | 8.2.1 Redefined M4 Macros

Jump to: D P U

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Concept Index

This is an alphabetical list of the files, tools, and concepts introduced in this document.

Jump to: ! " $ / : @ `
A B C D E F G H I L M O P Q R S T U V Z

 | Index Entry | Section
! |  |
 | ! | 10.8 Limitations of Shell Builtins
" |  |
 | `"$@"' | 10.5 Shell Substitutions
$ |  |
 | $(commands) | 10.5 Shell Substitutions
 | ${var:-value} | 10.5 Shell Substitutions
 | ${var=expanded-value} | 10.5 Shell Substitutions
 | ${var=literal} | 10.5 Shell Substitutions
/ |  |
 | /usr/xpg4/bin/sh on Solaris | 10.1 Shellology
: |  |
 | : | 10.8 Limitations of Shell Builtins
@ |  |
 | `@%:@' | 8.1.4 Quadrigraphs
 | `@:>@' | 8.1.4 Quadrigraphs
 | `@<:@' | 8.1.4 Quadrigraphs
 | `@S|@' | 8.1.4 Quadrigraphs
` |  |
 | `commands` | 10.5 Shell Substitutions
A |  |
 | `acconfig.h' | 15.2 `acconfig.h'
 | `aclocal.m4' | 3. Making configure Scripts
 | Ash | 10.1 Shellology
 | autoconf | 3.4 Using autoconf to Create configure
 | autoheader | 4.7.2 Using autoheader to Create `config.h.in'
 | Automake | 2.1 Automake
 | autoreconf | 3.5 Using autoreconf to Update configure Scripts
 | autoscan | 3.2 Using autoscan to Create `configure.ac'
 | autoupdate | 15.3 Using autoupdate to Modernize `configure.ac'
 | awk | 10.9 Limitations of Usual Tools
B |  |
 | Back trace | 3.4 Using autoconf to Create configure
 | Bash | 10.1 Shellology
 | break | 10.8 Limitations of Shell Builtins
C |  |
 | Cache | 7.3 Caching Results
 | Cache variable | 7.3.1 Cache Variable Names
 | Cache, enabling | 13.9 configure Invocation
 | case | 10.8 Limitations of Shell Builtins
 | cat | 10.9 Limitations of Usual Tools
 | cmp | 10.9 Limitations of Usual Tools
 | Command Substitution | 10.5 Shell Substitutions
 | `config.h' | 4.7 Configuration Header Files
 | `config.h.bot' | 15.2 `acconfig.h'
 | `config.h.in' | 4.7.1 Configuration Header Templates
 | `config.h.top' | 15.2 `acconfig.h'
 | config.status | 14. Recreating a Configuration
 | Configuration Header | 4.7 Configuration Header Files
 | Configuration Header Template | 4.7.1 Configuration Header Templates
 | configure | 3. Making configure Scripts
 | configure | 13. Running configure Scripts
 | `configure.ac' | 3. Making configure Scripts
 | `configure.in' | 3. Making configure Scripts
 | Copyright Notice | 4.1 Notices in configure
 | cp | 10.9 Limitations of Usual Tools
D |  |
 | Declaration, checking | 5.7 Declarations
 | diff | 10.9 Limitations of Usual Tools
 | dirname | 10.9 Limitations of Usual Tools
 | dnl | 9.1 Macro Definitions
 | dnl | 9.6 Coding Style
E |  |
 | echo | 10.8 Limitations of Shell Builtins
 | egrep | 10.9 Limitations of Usual Tools
 | Endianness | 5.10.2 C Compiler Characteristics
 | exit | 10.8 Limitations of Shell Builtins
 | export | 10.8 Limitations of Shell Builtins
 | expr | 10.9 Limitations of Usual Tools
 | expr | 10.9 Limitations of Usual Tools
 | expr (`|') | 10.9 Limitations of Usual Tools
F |  |
 | false | 10.8 Limitations of Shell Builtins
 | File, checking | 5.3 Files
 | for | 10.8 Limitations of Shell Builtins
 | Function, checking | 5.5.2 Particular Function Checks
G |  |
 | grep | 10.9 Limitations of Usual Tools
H |  |
 | Header, checking | 5.6 Header Files
I |  |
 | if | 10.8 Limitations of Shell Builtins
 | ifnames | 3.3 Using ifnames to List Conditionals
 | Includes, default | 5.1.2 Default Includes
 | Instantiation | 4.3 Outputting Files
L |  |
 | Language | 6.7 Language Choice
 | Library, checking | 5.4 Library Files
 | Libtool | 2.2 Libtool
 | Links | 4.9 Creating Configuration Links
 | ln | 10.9 Limitations of Usual Tools
M |  |
 | M4sugar | 8.2 Programming in M4sugar
 | Macro invocation stack | 3.4 Using autoconf to Create configure
 | Messages, from autoconf | 9.3 Reporting Messages
 | Messages, from configure | 7.4 Printing Messages
 | mv | 10.9 Limitations of Usual Tools
O |  |
 | obstack | 5.5.2 Particular Function Checks
P |  |
 | POSIX termios headers | 5.11 System Services
 | Previous Variable | 7.2 Setting Output Variables
 | Programs, checking | 5.2 Alternative Programs
Q |  |
 | QNX 4.25 | 6.5 Systemology
 | quadrigraphs | 8.1.4 Quadrigraphs
 | quotation | 3.1.2 The Autoconf Language
 | quotation | 8.1 M4 Quotation
R |  |
 | Revision | 4.1 Notices in configure
S |  |
 | sed | 10.9 Limitations of Usual Tools
 | sed (`t') | 10.9 Limitations of Usual Tools
 | set | 10.8 Limitations of Shell Builtins
 | shift | 10.8 Limitations of Shell Builtins
 | Structure, checking | 5.8 Structures
 | Symbolic links | 10.9 Limitations of Usual Tools
T |  |
 | termios POSIX headers | 5.11 System Services
 | test | 10.8 Limitations of Shell Builtins
 | touch | 10.9 Limitations of Usual Tools
 | trap | 10.8 Limitations of Shell Builtins
 | true | 10.8 Limitations of Shell Builtins
U |  |
 | undefined macro: _m4_divert_diversion | 15.6.2 New Macros
 | unset | 10.8 Limitations of Shell Builtins
V |  |
 | Variable, Precious | 7.2 Setting Output Variables
 | Version | 4.1 Notices in configure
 | VPATH | 10.10 Limitations of Make
Z |  |
 | Zsh | 10.1 Shellology

Jump to: ! " $ / : @ `
A B C D E F G H I L M O P Q R S T U V Z

[Top] [Contents] [Index] [ ? ]

Footnotes

(1)

GNU Autoconf, Automake and Libtool, by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN 1578701902.

(2)

Using defn.

(3)

For backward compatibility, configure will accept a system type as an option by itself. Such an option will override the defaults for build, host and target system types. The following configure statement will configure a cross toolchain that will run on NetBSD/alpha but generate code for GNU Hurd/sparc, which is also the build platform.

./configure --host=alpha-netbsd sparc-gnu

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Introduction
    2. The GNU build system
      2.1 Automake
      2.2 Libtool
      2.3 Pointers
    3. Making configure Scripts
      3.1 Writing `configure.ac'
        3.1.1 A Shell Script Compiler
        3.1.2 The Autoconf Language
        3.1.3 Standard `configure.ac' Layout
      3.2 Using autoscan to Create `configure.ac'
      3.3 Using ifnames to List Conditionals
      3.4 Using autoconf to Create configure
      3.5 Using autoreconf to Update configure Scripts
    4. Initialization and Output Files
      4.1 Notices in configure
      4.2 Finding configure Input
      4.3 Outputting Files
      4.4 Taking Configuration Actions
      4.5 Creating Configuration Files
      4.6 Substitutions in Makefiles
        4.6.1 Preset Output Variables
        4.6.2 Installation Directory Variables
        4.6.3 Build Directories
        4.6.4 Automatic Remaking
      4.7 Configuration Header Files
        4.7.1 Configuration Header Templates
        4.7.2 Using autoheader to Create `config.h.in'
        4.7.3 Autoheader Macros
      4.8 Running Arbitrary Configuration Commands
      4.9 Creating Configuration Links
      4.10 Configuring Other Packages in Subdirectories
      4.11 Default Prefix
    5. Existing Tests
      5.1 Common Behavior
        5.1.1 Standard Symbols
        5.1.2 Default Includes
      5.2 Alternative Programs
        5.2.1 Particular Program Checks
        5.2.2 Generic Program and File Checks
      5.3 Files
      5.4 Library Files
      5.5 Library Functions
        5.5.1 Portability of Classical Functions
        5.5.2 Particular Function Checks
        5.5.3 Generic Function Checks
      5.6 Header Files
        5.6.1 Particular Header Checks
        5.6.2 Generic Header Checks
      5.7 Declarations
        5.7.1 Particular Declaration Checks
        5.7.2 Generic Declaration Checks
      5.8 Structures
        5.8.1 Particular Structure Checks
        5.8.2 Generic Structure Checks
      5.9 Types
        5.9.1 Particular Type Checks
        5.9.2 Generic Type Checks
      5.10 Compilers and Preprocessors
        5.10.1 Generic Compiler Characteristics
        5.10.2 C Compiler Characteristics
        5.10.3 C++ Compiler Characteristics
        5.10.4 Fortran 77 Compiler Characteristics
      5.11 System Services
      5.12 UNIX Variants
    6. Writing Tests
      6.1 Examining Declarations
      6.2 Examining Syntax
      6.3 Examining Libraries
      6.4 Checking Run Time Behavior
        6.4.1 Running Test Programs
        6.4.2 Guidelines for Test Programs
        6.4.3 Test Functions
      6.5 Systemology
      6.6 Multiple Cases
      6.7 Language Choice
    7. Results of Tests
      7.1 Defining C Preprocessor Symbols
      7.2 Setting Output Variables
      7.3 Caching Results
        7.3.1 Cache Variable Names
        7.3.2 Cache Files
        7.3.3 Cache Checkpointing
      7.4 Printing Messages
    8. Programming in M4
      8.1 M4 Quotation
        8.1.1 Active Characters
        8.1.2 One Macro Call
        8.1.3 Quotation and Nested Macros
        8.1.4 Quadrigraphs
        8.1.5 Quotation Rule Of Thumb
      8.2 Programming in M4sugar
        8.2.1 Redefined M4 Macros
        8.2.2 Forbidden Patterns
    9. Writing Autoconf Macros
      9.1 Macro Definitions
      9.2 Macro Names
      9.3 Reporting Messages
      9.4 Dependencies Between Macros
        9.4.1 Prerequisite Macros
        9.4.2 Suggested Ordering
      9.5 Obsoleting Macros
      9.6 Coding Style
    10. Portable Shell Programming
      10.1 Shellology
      10.2 Here-Documents
      10.3 File Descriptors
      10.4 File System Conventions
      10.5 Shell Substitutions
      10.6 Assignments
      10.7 Special Shell Variables
      10.8 Limitations of Shell Builtins
      10.9 Limitations of Usual Tools
      10.10 Limitations of Make
    11. Manual Configuration
      11.1 Specifying the System Type
      11.2 Getting the Canonical System Type
      11.3 Using the System Type
    12. Site Configuration
      12.1 Working With External Software
      12.2 Choosing Package Options
      12.3 Making Your Help Strings Look Pretty
      12.4 Configuring Site Details
      12.5 Transforming Program Names When Installing
        12.5.1 Transformation Options
        12.5.2 Transformation Examples
        12.5.3 Transformation Rules
      12.6 Setting Site Defaults
    13. Running configure Scripts
      13.1 Basic Installation
      13.2 Compilers and Options
      13.3 Compiling For Multiple Architectures
      13.4 Installation Names
      13.5 Optional Features
      13.6 Specifying the System Type
      13.7 Sharing Defaults
      13.8 Environment Variables
      13.9 configure Invocation
    14. Recreating a Configuration
    15. Obsolete Constructs
      15.1 Obsolete `config.status' Invocation
      15.2 `acconfig.h'
      15.3 Using autoupdate to Modernize `configure.ac'
      15.4 Obsolete Macros
      15.5 Upgrading From Version 1
        15.5.1 Changed File Names
        15.5.2 Changed Makefiles
        15.5.3 Changed Macros
        15.5.4 Changed Results
        15.5.5 Changed Macro Writing
      15.6 Upgrading From Version 2.13
        15.6.1 Changed Quotation
        15.6.2 New Macros
    16. Questions About Autoconf
      16.1 Distributing configure Scripts
      16.2 Why Require GNU M4?
      16.3 How Can I Bootstrap?
      16.4 Why Not Imake?
    17. History of Autoconf
      17.1 Genesis
      17.2 Exodus
      17.3 Leviticus
      17.4 Numbers
      17.5 Deuteronomy
    Environment Variable Index
    Output Variable Index
    Preprocessor Symbol Index
    Autoconf Macro Index
    M4 Macro Index
    Concept Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Introduction
2. The GNU build system
3. Making configure Scripts
4. Initialization and Output Files
5. Existing Tests
6. Writing Tests
7. Results of Tests
8. Programming in M4
9. Writing Autoconf Macros
10. Portable Shell Programming
11. Manual Configuration
12. Site Configuration
13. Running configure Scripts
14. Recreating a Configuration
15. Obsolete Constructs
16. Questions About Autoconf
17. History of Autoconf
Environment Variable Index
Output Variable Index
Preprocessor Symbol Index
Autoconf Macro Index
M4 Macro Index
Concept Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on February 18, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on February 18, 2002 using texi2html


AutoGen

This file documents AutoGen version 5.3. It is a tool designed for generating program files that contain repetitive text with varied substitutions. This document is very long because it is intended as a reference document. For a quick start example, See section 1.2 A Simple Example. For a simple example of Automated Option processing, See section 7.3 Quick Start. For a full list of the Automated Option features, See section 7.1 AutoOpts Features.

This edition documents version 5.3, May 2002.

1. Introduction | AutoGen's Purpose
2. AutoGen Definitions File
3. AutoGen Template
4. Augmenting AutoGen Features
5. Invoking autogen | Invoking AutoGen
6. Configuring and Installing
7. Automated Option Processing
8. Add-on packages for AutoGen
9. Some ideas for the future.
Concept Index | General index
Function Index | Function index

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Introduction

AutoGen is a tool designed for generating program files that contain repetitive text with varied substitutions. Its goal is to simplify the maintenance of programs that contain large amounts of repetitious text. This is especially valuable if there are several blocks of such text that must be kept synchronized.

One common example is the problem of maintaining the code required for processing program options. Processing options requires a minimum of four different constructs be kept in proper order in different places in your program. You need at least:

  1. The flag character in the flag string,
  2. code to process the flag when it is encountered,
  3. a global state variable or two, and
  4. a line in the usage text.

You will need more things besides this if you choose to implement long option names, rc/ini file processing, environment variables and so on. All of this can be done mechanically; with the proper templates and this program. In fact, it has already been done and AutoGen itself uses it See section 7. Automated Option Processing. For a simple example of Automated Option processing, See section 7.3 Quick Start. For a full list of the Automated Option features, See section 7.1 AutoOpts Features.

1.1 The Purpose of AutoGen
1.2 A Simple Example
1.3 csh/zsh caveat
1.4 A User's Perspective

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.1 The Purpose of AutoGen

The idea of this program is to have a text file, a template if you will, that contains the general text of the desired output file. That file includes substitution expressions and sections of text that are replicated under the control of separate definition files.

AutoGen was designed with the following features:

  1. The definitions are completely separate from the template. By completely isolating the definitions from the template it greatly increases the flexibility of the template implementation. A secondary goal is that a template user only needs to specify those data that are necessary to describe his application of a template.

  2. Each datum in the definitions is named. Thus, the definitions can be rearranged, augmented and become obsolete without it being necessary to go back and clean up older definition files. Reduce incompatibilities!

  3. Every definition name defines an array of values, even when there is only one entry. These arrays of values are used to control the replication of sections of the template.

  4. There are named collections of definitions. They form a nested hierarchy. Associated values are collected and associated with a group name. These associated data are used collectively in sets of substitutions.

  5. The template has special markers to indicate where substitutions are required, much like the ${VAR} construct in a shell here doc. These markers are not fixed strings. They are specified at the start of each template. Template designers know best what fits into their syntax and can avoid marker conflicts.

    We did this because it is burdensome and difficult to avoid conflicts using either M4 tokenizaion or C preprocessor substitution rules. It also makes it easier to specify expressions that transform the value. Of course, our expressions are less cryptic than the shell methods.

  6. These same markers are used, in conjunction with enclosed keywords, to indicate sections of text that are to be skipped and for sections of text that are to be repeated. This is a major improvement over using C preprocessing macros. With the C preprocessor, you have no way of selecting output text because it is an unvarying, mechanical substitution process.

  7. Finally, we supply methods for carefully controlling the output. Sometimes, it is just simply easier and clearer to compute some text or a value in one context when its application needs to be later. So, functions are available for saving text or values for later use.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.2 A Simple Example

This is just one simple example that shows a few basic features. If you are interested, you also may run "make check" with the VERBOSE enviornment variable set and see a number of other examples in the `agen5/test/testdir' directory.

Assume you have an enumeration of names and you wish to associate some string with each name. Assume also, for the sake of this example, that it is either too complex or too large to maintain easily by hand. We will start by writing an abbreviated version of what the result is supposed to be. We will use that to construct our output templates.

In a header file, `list.h', you define the enumeration and the global array containing the associated strings:

typedef enum {
        IDX_ALPHA,
        IDX_BETA,
        IDX_OMEGA }  list_enum;

extern const char* az_name_list[ 3 ];

Then you also have `list.c' that defines the actual strings:

#include "list.h"
const char* az_name_list[] = {
        "some alpha stuff",
        "more beta stuff",
        "final omega stuff" };

First, we will define the information that is unique for each enumeration name/string pair. This would be placed in a file named, `list.def', for example.

autogen definitions list;
list = { list_element = alpha;
         list_info    = "some alpha stuff"; };
list = { list_info    = "more beta stuff";
         list_element = beta; };
list = { list_element = omega;
         list_info    = "final omega stuff"; };

The autogen definitions list; entry defines the file as an AutoGen definition file that uses a template named list. That is followed by three list entries that define the associations between the enumeration names and the strings. The order of the differently named elements inside of list is unimportant. They are reversed inside of the beta entry and the output is unaffected.

Now, to actually create the output, we need a template or two that can be expanded into the files you want. In this program, we use a single template that is capable of multiple output files. The definitions above refer to a `list' template, so it would normally be named, `list.tpl'.

It looks something like this. (For a full description, See section 3. AutoGen Template.)

[+ AutoGen5 template h c +]
[+ CASE (suffix) +][+
   ==  h  +]
typedef enum {[+
   FOR list "," +]
        IDX_[+ (string-upcase! (get "list_element")) +][+
   ENDFOR list +] }  list_enum;

extern const char* az_name_list[ [+ (count "list") +] ];
[+

   ==  c  +]
#include "list.h"
const char* az_name_list[] = {[+
  FOR list "," +]
        "[+list_info+]"[+
  ENDFOR list +] };[+

ESAC +]

The [+ AutoGen5 template h c +] text tells AutoGen that this is an AutoGen version 5 template file; that it is to be processed twice; that the start macro marker is [+; and the end marker is +]. The template will be processed first with a suffix value of h and then with c. Normally, the suffix values are appended to the `base-name' to create the output file name.

The [+ == h +] and [+ == c +] CASE selection clauses select different text for the two different passes. In this example, the output is nearly disjoint and could have been put in two separate templates. However, sometimes there are common sections and this is just an example.

The [+FOR list "," +] and [+ ENDFOR list +] clauses delimit a block of text that will be repeated for every definition of list. Inside of that block, the definition name-value pairs that are members of each list are available for substitutions.

The remainder of the macros are expressions. Some of these contain special expression functions that are dependent on AutoGen named values; others are simply Scheme expressions, the result of which will be inserted into the output text. Other expressions are names of AutoGen values. These values will be inserted into the output text. For example, [+list_info+] will result in the value associated with the name list_info being inserted between the double quotes and (string-upcase! (get "list_element")) will first "get" the value associated with the name list_element, then change the case of all the letters to upper case. The result will be inserted into the output document.

If you have compiled AutoGen, you can copy out the template and definitions as described above and run "autogen list.def". This will produce exactly the hypothesized desired output.

One more point, too. Lets say you decided it was too much trouble to figure out how to use AutoGen, so you created this enumeration and string list with thousands of entries. Now, requirements have changed and it has become necessary to map a string containing the enumeration name into the enumeration number. With AutoGen, you just alter the template to emit the table of names. It will be guaranteed to be in the correct order, missing none of the entries. If you want to do that by hand, well, good luck.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.3 csh/zsh caveat

AutoGen tries to use your normal shell so that you can supply shell code in a manner you are accustomed to using. If, however, you use csh or zsh, you cannot do this. Csh is sufficiently difficult to program that it is unsupported. Zsh, though largely programmable, also has some anomolies that make it incompatible with AutoGen usage. Therefore, when invoking AutoGen from these environments, you must be certain to set the SHELL environment variable to a Bourne-derived shell. e.g., sh, ksh or bash.

Any shell you choose for your own scripts need to follow these basic requirements:

  1. It handles trap $sig ":" without output to standard out. This is done when the server shell is first started. If your shell does not handle this, then it may be able to by loading functions from its start up files.
  2. At the beginning of each scriptlet, the command \\cd $PWD is inserted. This ensures that cd is not aliased to something peculiar and each scriptlet starts life in the execution directory.
  3. At the end of each scriptlet, the command echo mumble is appended. The program you use as a shell must emit the single argument mumble on a line by itself.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.4 A User's Perspective

Alexandre wrote:
>
> I'd appreciate opinions from others about advantages/disadvantages of
> each of these macro packages.

I am using AutoGen in my pet project, and find one of its best points to be that it separates the operational data from the implementation.

Indulge me for a few paragraphs, and all will be revealed: In the manual, Bruce cites the example of maintaining command line flags inside the source code; traditionally spreading usage information, flag names, letters and processing across several functions (if not files). Investing the time in writing a sort of boiler plate (a template in AutoGen terminology) pays by moving all of the option details (usage, flags names etc.) into a well structured table (a definition file if you will), so that adding a new command line option becomes a simple matter of adding a set of details to the table.

So far so good! Of course, now that there is a template, writing all of that tedious optargs processing and usage functions is no longer an issue. Creating a table of the options needed for the new project and running AutoGen generates all of the option processing code in C automatically from just the tabular data. AutoGen in fact already ships with such a template... AutoOpts.

One final consequence of the good separation in the design of AutoGen is that it is retargetable to a greater extent. The egcs/gcc/fixinc/inclhack.def can equally be used (with different templates) to create a shell script (inclhack.sh) or a c program (fixincl.c).

This is just the tip of the iceberg. AutoGen is far more powerful than these examples might indicate, and has many other varied uses. I am certain Bruce or I could supply you with many and varied examples, and I would heartily recommend that you try it for your project and see for yourself how it compares to m4.

As an aside, I would be interested to see whether someone might be persuaded to rationalise autoconf with AutoGen in place of m4... Ben, are you listening? autoconf-3.0! `kay? =)O|

Sincerely,
        Gary V. Vaughan

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. AutoGen Definitions File

This chapter describes the syntax and semantics of the AutoGen definition file. In order to instantiate a template, you normally must provide a definitions file that identifies itself and contains some value definitions. Consequently, we keep it very simple. For "advanced" users, there are preprocessing directives and comments that may be used as well.

The definitions file is used to associate values with names. Every value is implicitly an array of values, even if there is only one value. Values may be either simple strings or compound collections of name-value pairs. An array may not contain both simple and compound members. Fundamentally, it is as simple as:

prog_name = "autogen";
flag = {
    name      = templ_dirs;
    value     = L;
    descrip   = "Template search directory list";
};

For purposes of commenting and controlling the processing of the definitions, C-style comments and most C preprocessing directives are honored. The major exception is that the #if directive is ignored, along with all following text through the matching #endif directive. The C preprocessor is not actually invoked, so C macro substitution is not performed.

2.1 The Identification Definition
2.2 Named Definitions
2.3 Assigning an Index to a Definition
2.4 Dynamic Text
2.5 Controlling What Gets Processed
2.6 Pre-defined Names
2.7 Commenting Your Definitions
2.8 What it all looks like.
2.9 YACC Language Grammar
2.10 Alternate Definition Forms

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 The Identification Definition

The first definition in this file is used to identify it as a AutoGen file. It consists of the two keywords, `autogen' and `definitions' followed by the default template name and a terminating semi-colon (;). That is:

        AutoGen Definitions template-name;

Note that, other than the name template-name, the words `AutoGen' and `Definitions' are searched for without case sensitivity. Most lookups in this program are case insensitive.

Also, if the input contains more identification definitions, they will be ignored. This is done so that you may include (see section 2.5 Controlling What Gets Processed) other definition files without an identification conflict.

AutoGen uses the name of the template to find the corresponding template file. It searches for the file in the following way, stopping when it finds the file:

  1. It tries to open `./template-name'. If it fails,
  2. it tries `./template-name.tpl'.
  3. It searches for either of these files in the directories listed in the templ-dirs command line option.

If AutoGen fails to find the template file in one of these places, it prints an error message and exits.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 Named Definitions

Any name may have multiple values associated with it in the definition file. If there is more than one instance, the only way to expand all of the copies of it is by using the FOR (see section 3.6.13 FOR - Emit a template block multiple times) text function on it, as described in the next chapter.

There are two kinds of definitions, `simple' and `compound'. They are defined thus (see section 2.9 YACC Language Grammar):

compound_name '=' '{' definition-list '}' ';'

simple_name '=' string ';'

no_text_name ';'

No_text_name is a simple definition with a shorthand empty string value. The string values for definitions may be specified in any of several formation rules.

2.2.1 Definition List
2.2.2 Double Quote String
2.2.3 Single Quote String
2.2.5 An Unquoted String
2.2.4 Shell Output String
2.2.6 Scheme Result String
2.2.7 A Here String
2.2.8 Concatenated Strings

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2.1 Definition List

definition-list is a list of definitions that may or may not contain nested compound definitions. Any such definitions may only be expanded within a FOR block iterating over the containing compound definition. See section 3.6.13 FOR - Emit a template block multiple times.

Here is, again, the example definitions from the previous chapter, with three additional name value pairs. Two with an empty value assigned (first and last), and a "global" group_name.

autogen definitions list;
group_name = example;
list = { list_element = alpha;  first;
         list_info    = "some alpha stuff"; };
list = { list_info    = "more beta stuff";
         list_element = beta; };
list = { list_element = omega;  last;
         list_info    = "final omega stuff"; };

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2.2 Double Quote String

The string follows the C-style escaping (\, \n, \f, \v, etc.), plus octal character numbers specified as \ooo. The difference from "C" is that the string may span multiple lines. Like ANSI "C", a series of these strings, possibly intermixed with single quote strings, will be concatenated together.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2.3 Single Quote String

This is similar to the shell single-quote string. However, escapes \ are honored before another escape, single quotes ' and hash characters #. This latter is done specifically to disambiguate lines starting with a hash character inside of a quoted string. In other words,

fumble = '
#endif
';

could be misinterpreted by the definitions scanner, whereas this would not:

fumble = '
\#endif
';

As with the double quote string, a series of these, even intermixed with double quote strings, will be concatenated together.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2.4 Shell Output String

This is assembled according to the same rules as the double quote string, except that there is no concatenation of strings and the resulting string is written to a shell server process. The definition takes on the value of the output string.

NB The text is interpreted by a server shell. There may be left over state from previous ` processing and it may leave state for subsequent processing. However, a cd to the original directory is always issued before the new command is issued.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2.5 An Unquoted String

A simple string that does not contain white space may be left unquoted. The string must not contain any of the characters special to the definition text (i.e. ", #, ', (, ), ,, ;, <, =, >, [, ], `, {, or }). This list is subject to change, but it will never contain underscore (_), period (.), slash (/), colon (:), hyphen (-) or backslash (\\). Basically, if the string looks like it is a normal DOS or UNIX file or variable name, and it is not one of two keywords (`autogen' or `definitions') then it is OK to not quote it, otherwise you should.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2.6 Scheme Result String

A scheme result string must begin with an open parenthesis (. The scheme expression will be evaluated by Guile and the value will be the result. The AutoGen expression functions are disabled at this stage, so do not use them.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2.7 A Here String

A `here string' is formed in much the same way as a shell here doc. It is denoted with a doubled less than character and, optionally, a hyphen. This is followed by optional horizontal white space and an ending marker-identifier. This marker must follow the syntax rules for identifiers. Unlike the shell version, however, you must not quote this marker. The resulting string will start with the first character on the next line and continue up to but not including the newline that precedes the line that begins with the marker token. No backslash or any other kind of processing is done on this string. The characters are copied directly into the result string.

Here are two examples:
str1 = <<-  STR_END
        $quotes = " ' `
        STR_END;

str2 = <<   STR_END
        $quotes = " ' `
        STR_END;
STR_END;
The first string contains no new line characters. The first character is the dollar sign, the last the back quote.

The second string contains one new line character. The first character is the tab character preceeding the dollar sign. The last character is the semicolon after the STR_END. That STR_END does not end the string because it is not at the beginning of the line. In the preceeding case, the leading tab was stripped.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2.8 Concatenated Strings

If single or double quote characters are used, then you also have the option, a la ANSI-C syntax, of implicitly concatenating a series of them together, with intervening white space ignored.

NB You cannot use directives to alter the string content. That is,

str = "fumble"
#ifdef LATER
      "stumble"
#endif
      ;

will result in a syntax error. The preprocessing directives are not carried out by the C preprocessor. However,

str = '"fumble\n"
#ifdef LATER
"     stumble\n"
#endif
';

Will work. It will enclose the `#ifdef LATER' and `#endif' in the string. But it may also wreak havoc with the definition processing directives. The hash characters in the first column should be disambiguated with an escape \ or join them with previous lines: "fumble\n#ifdef LATER....

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.3 Assigning an Index to a Definition

In AutoGen, every name is implicitly an array of values. When assigning values, they are usually implicitly assiged to the next highest slot. They can also be specified explicitly:

mumble[9] = stumble;
mumble[0] = grumble;

If, subsequently, you assign a value to mumble without an index, its index will be 10, not 1. If indexes are specified, they must not cause conflicts.

#define-d names may also be used for index values. This is equivalent to the above:

#define FIRST 0
#define LAST  9
mumble[LAST]  = stumble;
mumble[FIRST] = grumble;

All values in a range do not have to be filled in. If you leave gaps, then you will have a sparse array. This is fine (see section 3.6.13 FOR - Emit a template block multiple times). You have your choice of iterating over all the defined values, or iterating over a range of slots. This:

[+ FOR mumble +][+ ENDFOR +]

iterates over all and only the defined entries, whereas this:

[+ FOR mumble (for-by 1) +][+ ENDFOR +]

will iterate over all 10 "slots". Your template will likely have to contain something like this:

[+ IF (exist? (sprintf "mumble[%d]" (for-index))) +]

or else "mumble" will have to be a compound value that, say, always contains a "grumble" value:

[+ IF (exist? "grumble") +]

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.4 Dynamic Text

There are several methods for including dynamic content inside a definitions file. Three of them are mentioned above (2.2.4 Shell Output String and see section 2.2.6 Scheme Result String) in the discussion of string formation rules. Another method uses the #shell processing directive. It will be discussed in the next section (see section 2.5 Controlling What Gets Processed). Guile/Scheme may also be used to yield to create definitions.

When the Scheme expression is preceeded by a backslash and single quote, then the expression is expected to be an alist of names and values that will be used to create AutoGen definitions.

This method can be be used as follows:

\'( (name  (value-expression))
    (name2 (another-expr))  )

This is entirely equivalent to:

name  = (value-expression);
name2 = (another-expr);

Under the covers, the expression gets handed off to a Guile function named alist->autogen-def in an expression that looks like this:

(alist->autogen-def
    ( (name (value-expression))  (name2 (another-expr)) ) )

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.5 Controlling What Gets Processed

Definition processing directives can only be processed if the '#' character is the first character on a line. Also, if you want a '#' as the first character of a line in one of your string assignments, you should either escape it by preceding it with a backslash `\', or by embedding it in the string as in "\n#".

All of the normal C preprocessing directives are recognized, though several are ignored. There is also an additional #shell - #endshell pair. Another minor difference is that AutoGen directives must have the hash character (#) in column 1.

The final tweak is that #! is treated as a comment line. Using this feature, you can use: `#! /usr/local/bin/autogen' as the first line of a definitons file, set the mode to executable and "run" the definitions file as if it were a direct invocation of AutoGen. This was done for its hack value.

The ignored directives are: `#assert', `#ident', `#pragma', and `#if'. Note that when ignoring the #if directive, all intervening text through its matching #endif is also ignored, including the #else clause.

The AutoGen directives that affect the processing of definitions are:

#define name [ <text> ]

Will add the name to the define list as if it were a DEFINE program argument. Its value will be the first non-whitespace token following the name. Quotes are not processed.

After the definitions file has been processed, any remaining entries in the define list will be added to the environment.

#elif

This must follow an #if otherwise it will generate an error. It will be ignored.

#else

This must follow an #if, #ifdef or #ifndef. If it follows the #if, then it will be ignored. Otherwise, it will change the processing state to the reverse of what it was.

#endif

This must follow an #if, #ifdef or #ifndef. In all cases, this will resume normal processing of text.

#endshell

Ends the text processed by a command shell into autogen definitions.

#error [ <descriptive text> ]

This directive will cause AutoGen to stop processing and exit with a status of EXIT_FAILURE.

#if [ <ignored conditional expression> ]

#if expressions are not analyzed. Everything from here to the matching #endif is skipped.

#ifdef name-to-test

The definitions that follow, up to the matching #endif will be processed only if there is a corresponding -Dname command line option.

#ifndef name-to-test

The definitions that follow, up to the matching #endif will be processed only if there is not a corresponding -Dname command line option or there was a canceling -Uname option.

#include unadorned-file-name

This directive will insert definitions from another file into the current collection. If the file name is adorned with double quotes or angle brackets (as in a C program), then the include is ignored.

#line

Alters the current line number and/or file name. You may wish to use this directive if you extract definition source from other files. getdefs uses this mechanism so AutoGen will report the correct file and approximate line number of any errors found in extracted definitions.

#shell

Invokes $SHELL or `/bin/sh' on a script that should generate AutoGen definitions. It does this using the same server process that handles the back-quoted ` text. CAUTION let not your $SHELL be csh.

#undef name-to-undefine

Will remove any entries from the define list that match the undef name pattern.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.6 Pre-defined Names

When AutoGen starts, it tries to determine several names from the operating environment and put them into environment variables for use in both #ifdef tests in the definitions files and in shell scripts with environment variable tests. __autogen__ is always defined. For other names, AutoGen will first try to use the POSIX version of the sysinfo(2) system call. Failing that, it will try for the POSIX uname(2) call. If neither is available, then only "__autogen__" will be inserted into the environment. In all cases, the associated names are converted to lower case, surrounded by doubled underscores and non-symbol characters are replaced with underscores.

With Solaris on a sparc platform, sysinfo(2) is available. The following strings are used:

  • SI_SYSNAME (e.g., "__sunos__")
  • SI_HOSTNAME (e.g., "__ellen__")
  • SI_ARCHITECTURE (e.g., "__sparc__")
  • SI_HW_PROVIDER (e.g., "__sun_microsystems__")
  • SI_PLATFORM (e.g., "__sun_ultra_5_10__")
  • SI_MACHINE (e.g., "__sun4u__")

For Linux and other operating systems that only support the uname(2) call, AutoGen will use these values:

  • sysname (e.g., "__linux__")
  • machine (e.g., "__i586__")
  • nodename (e.g., "__bach__")

By testing these pre-defines in my definitions, you can select pieces of the definitions without resorting to writing shell scripts that parse the output of uname(1). You can also segregate real C code from autogen definitions by testing for "__autogen__".

#ifdef __bach__
  location = home;
#else
  location = work;
#endif

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.7 Commenting Your Definitions

The definitions file may contain C and C++ style comments.

/*
 *  This is a comment.  It continues for several lines and closes
 *  when the characters '*' and '/' appear together.
 */
// this comment is a single line comment

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.8 What it all looks like.

This is an extended example:

autogen definitions `template-name';
/*
 *  This is a comment that describes what these
 *  definitions are all about.
 */
global = "value for a global text definition.";

/*
 *  Include a standard set of definitions
 */
#include standards.def

a_block = {
    a_field;
    a_subblock = {
        sub_name  = first;
        sub_field = "sub value.";
    };

#ifdef FEATURE
    a_subblock = {
        sub_name  = second;
    };
#endif

};

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.9 YACC Language Grammar

The preprocessing directives and comments are not part of the grammar. They are handled by the scanner/lexer. The following was extracted directly from the defParse.y source file:

definitions : identity def_list TK_END
            { $$ = (YYSTYPE)(rootDefCtx.pDefs = (tDefEntry*)$2); } ;

def_list    : definition           { $$ = $1; }
            | definition def_list  { $$ = addSibMacro( $1, $2 ); }
            | identity   def_list  { $$ = $2; }
            ;

identity    : TK_AUTOGEN TK_DEFINITIONS filename ';'
                { $$ = identify( $3 ); }
            ;

definition  : value_name ';'
                { $$ = makeMacro( $1, (YYSTYPE)"", VALTYP_TEXT ); }

            | value_name '=' text_list ';'
                { $$ = makeMacroList( $1, $3, VALTYP_TEXT ); }

            | value_name '=' block_list ';'
                { $$ = makeMacroList( $1, $3, VALTYP_BLOCK ); }
            ;

text_list   : anystring                { $$ = startList( $1 ); }
            | anystring ',' text_list  { $$ = appendList( $1, $3 ); }
            ;

block_list  : def_block                { $$ = startList( $1 ); }
            | def_block ',' block_list { $$ = appendList( $1, $3 ); }
            ;

def_block   : '{' def_list '}'         { $$ = $2; } ;

anystring   : filename      { $$ = $1; }
            | TK_NUMBER     { $$ = $1; } ;

filename    : TK_OTHER_NAME { $$ = $1; }
            | TK_STRING     { $$ = $1; }
            | TK_VAR_NAME   { $$ = $1; } ;

value_name  : TK_VAR_NAME
                { $$ = findPlace( (YYSTYPE)$1, (YYSTYPE)NULL ); }

            | TK_VAR_NAME '[' TK_NUMBER ']'
                { $$ = findPlace( (YYSTYPE)$1, (YYSTYPE)$3 ); }

            | TK_VAR_NAME '[' TK_VAR_NAME ']'
                { $$ = findPlace( (YYSTYPE)$1, (YYSTYPE)$3 ); }
            ;

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.10 Alternate Definition Forms

There are two other methods for supplying data values for templates and a third in the planning stages.

`no definitions'
It is entirely possible to write a template that does not depend upon external definitions. Such a template would likely have an unvarying output, but be convenient nonetheless because of an external library of either AutoGen or Scheme functions, or both. This can be accommodated by providing the --override-tpl and --no-definitions options on the command line. See section 5. Invoking autogen.

`CGI'
AutoGen behaves as a CGI server if the definitions input is from stdin and the environment variable REQUEST_METHOD is defined and set to either "GET" or "POST", See section 6.2 AutoGen as a CGI server. Obviously, all the values are constrained to strings because there is no way to represent nested values.

`XML'
Someday, I plan to map XML data directly into AutoGen definitions. This will enable you to extract information from arbitrary XML source and insert it into AutoGen templates.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. AutoGen Template

The AutoGen template file defines the content of the output text. It is composed of two parts. The first part consists of a pseudo macro invocation and commentary. It is followed by the template proper.

This pseudo macro is special. It is used to identify the file as a AutoGen template file, fixing the starting and ending marks for the macro invocations in the rest of the file, specifying the list of suffixes to be generated by the template and, optionally, the shell to use for processing shell commands embedded in the template.

AutoGen-ing a file consists of copying text from the template to the output file until a start macro marker is found. The text from the start marker to the end marker constitutes the macro text. AutoGen macros may cause sections of the template to be skipped or processed several times. The process continues until the end of the template is reached. The process is repeated once for each suffix specified in the pseudo macro.

This chapter describes the format of the AutoGen template macros and the usage of the AutoGen native macros. Users may augment these by defining their own macros. See section 3.6.4 DEFINE - Define a user AutoGen macro.

3.1 Format of the Pseudo Macro
3.2 Naming a value
3.3 Macro Expression Syntax
3.4 AutoGen Scheme Functions
3.5 Common Scheme Functions
3.6 AutoGen Native Macros
3.7 Redirecting Output

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 Format of the Pseudo Macro

The pseudo macro is used to tell AutoGen how to process a template. It tells autogen:

  1. The punctuation characters used to demarcate the start of a macro. It may be up to seven characters long and must be the first non-whitespace characters in the file.

  2. That start marker must be immediately followed by the marker strings "AutoGen5" and then "template", though capitalization is not important.

The next several components may be intermingled:

  1. Zero, one or more suffix specifications tell AutoGen how many times to process the template file. No suffix specifications mean that it is to be processed once and that the generated text is to be written to stdout. The current suffix for each pass can be determined with the (suffix) scheme function (see section 3.4.33 `suffix' - get the current suffix).

    The suffix specification consists of a sequence of POSIX compliant file name characters and, optionally, an equal sign and a file name "printf"-style formatting string. Two string arguments are allowed for that string: the base name of the definition file and the current suffix (that being the text to the left of the equal sign). (Note: "POSIX compliant file name characters" consist of alphanumerics plus the period (.), hyphen (-) and underscore (_) characters.)

  2. Comment lines: blank lines, lines starting with a hash mark [#]), and edit mode comments (text between pairs of -*- strings).

  3. Scheme expressions may be inserted in order to make configuration changes before template processing begins. It is used, for example, to allow the template writer to specify the shell program that must be used to interpret the shell commands in the template. It can have no effect on any shell commands in the definitions file, as that file will have been processed by the time the pseudo macro is interpreted.

    (setenv "SHELL" "/bin/sh")

    This is extremely useful to ensure that the shell used is the one the template was written to use. By default, AutoGen determines the shell to use by user preferences. Sometimes, that can be the "csh", though.

    The scheme expression can also be used to save a pre-existing output file for later text extraction (see section 3.5.4 `extract' - extract text from another file).

    (shellf "mv -f %1$s.c %1$s.sav" (base-name))

  4. Finally, the end-macro marker must be last. It must not begin with a POSIX file name character, and if it begins with an equal sign, then it must be separated from any suffix specification by white space.

It is generally a good idea to use some sort of opening bracket in the starting macro and closing bracket in the ending macro (e.g. {, (, [, or even < in the starting macro). It helps both visually and with editors capable of finding a balancing parenthesis. The closing marker may not begin with an open parenthesis, as that is used to enclose a scheme expression.

It is also helpful to avoid using the comment marker (#); the POSIXly acceptable file name characters period (.), hyphen (-) and underscore (_); and finally, it is advisable to avoid using any of the quote characters double, single or back-quote. But there is no special check for any of these advisories.

As an example, assume we want to use [+ and +] as the start and end macro markers, and we wish to produce a `.c' and a `.h' file, then the first macro invocation will look something like this:

[+ AutoGen5 template -*- Mode: emacs-mode-of-choice -*-
h=chk-%s.h
c
# make sure we don't use csh:
(setenv "SHELL" "/bin/sh")  +]

The template proper starts after the pseudo-macro. The starting character is either the first non-whitespace character or the first character after the newline that follows the end macro marker.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 Naming a value

When an AutoGen value is specified in a template, it is specified by name. The name may be a simple name, or a compound name of several components. Since each named value in AutoGen is implicitly an array of one or more values, each component may have an index associated with it.

It looks like this:

comp-name-1 . comp-name-2 [ 2 ]

Note that if there are multiple components to a name, each component name is separated by a dot (.). Indexes follow a component name, enclosed in square brackets ([ and ]). The index may be either an integer or an integer-valued define name. The first component of the name is searched for in the current definition level. If not found, higher levels will be searched until either a value is found, or there are no more definition levels. Subsequent components of the name must be found within the context of the newly-current definition level. Also, if the named value is prefixed by a dot (.), then the value search is started in the current context only. No higher levels are searched.

If someone rewrites this, I'll incorporate it. :-)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 Macro Expression Syntax

AutoGen has two types of expressions: full expressions and basic ones. A full AutoGen expression can appear by itself, or as the argument to certain AutoGen built-in macros: CASE, IF, ELIF, INCLUDE, INVOKE (explicit invocation, see section 3.6.16 INVOKE - Invoke a User Defined Macro), and WHILE. If it appears by itself, the result is inserted into the output. If it is an argument to one of these macros, the macro code will act on it sensibly.

You are constrained to basic expressions only when passing arguments to user defined macros, See section 3.6.4 DEFINE - Define a user AutoGen macro.

The syntax of a full AutoGen expression is:

[[ <apply-code> ] <value-name> ] [ <basic-expr-1> [ <basic-expr-2> ]]

How the expression is evaluated depends upon the presence or absence of the apply code and value name. The "value name" is the name of an AutoGen defined value, or not. If it does not name such a value, the expression result is generally the empty string. All expressions must contain either a value-name or a basic-expr.

3.3.1 Apply Code
3.3.2 Basic Expression

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.1 Apply Code

The "apply code" selected determines the method of evaluating the expression. There are five apply codes, including the non-use of an apply code.

`no apply code'
This is the most common expression type. Expressions of this sort come in three flavors:

`<value-name>'
The result is the value of value-name, if defined. Otherwise it is the empty string.

`<basic-expr>'
The result of the basic expression is the result of the full expression, See section 3.3.2 Basic Expression.

`<value-name> <basic-expr>'
If there is a defined value for value-name, then the basic-expr is evaluated. Otherwise, the result is the empty string.

`% <value-name> <basic-expr>'
If value-name is defined, use basic-expr as a format string for sprintf. Then, if the basic-expr is either a back-quoted string or a parenthesized expression, then hand the result to the appropriate interpreter for further evaluation. Otherwise, for single and double quote strings, the result is the result of the sprintf operation. Naturally, if value-name is not defined, the result is the empty string.

For example, assume that fumble had the string value, stumble:
[+ % fumble `printf '%%x\\n' $%s` +]
This would cause the shell to evaluate "printf '%x\n' $stumble". Assuming that the shell variable stumble had a numeric value, the expression result would be that number, in hex. Note the need for doubled percent characters and backslashes.

`? <value-name> <basic-expr-1> <basic-expr-2>'
Two basic-expr-s are required. If the value-name is defined, then the first basic-expr-1 is evaluated, otherwise basic-expr-2 is.

`- <value-name> <basic-expr>'
Evaluate basic-expr only if value-name is not defined.

`?% <value-name> <basic-expr-1> <basic-expr-2>'
This combines the functions of `?' and `%'. If value-name is defined, it behaves exactly like `%', above, using basic-expr-1. If not defined, then basic-expr-2 is evaluated.

For example, assume again that fumble had the string value, stumble:
[+ ?% fumble `cat $%s` `pwd` +]
This would cause the shell to evaluate "cat $stumble". If fumble were not defined, then the result would be the name of our current directory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.2 Basic Expression

A basic expression can have one of the following forms:

`'STRING''
A single quoted string. Backslashes can be used to protect single quotes ('), hash characters (#), or backslashes (\) in the string. All other characters of STRING are output as-is when the single quoted string is evaluated. Backslashes are processed before the hash character for consistency with the definition syntax. It is needed there to avoid preprocessing conflicts.

`"STRING"'
A double quoted string. This is a cooked text string as in C, except that they are not concatenated with adjacent strings. Evaluating "STRING" will output STRING with all backslash sequences interpreted.

``STRING`'
A back quoted string. When this expression is evaluated, STRING is first interpreted as a cooked string (as in `"STRING"') and evaluated as a shell expression by the AutoGen server shell. This expression is replaced by the stdout output of the shell.

`(STRING)'
A parenthesized expression. It will be passed to the Guile interpreter for evaluation and replaced by the resulting value.

Additionally, other than in the % and ?% expressions, the Guile expressions may be introduced with the Guile comment character (;) and you may put a series of Guile expressions within a single macro. They will be implicitly evaluated as if they were arguments to the (begin ...) expression. The result will be the the result of the last Guile expression evaluated.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4 AutoGen Scheme Functions

AutoGen uses Guile to interpret Scheme expressions within AutoGen macros. All of the normal Guile functions are available, plus several extensions (see section 3.5 Common Scheme Functions) have been added to augment the repertoire of string manipulation functions and manage the state of AutoGen processing.

This section describes those functions that are specific to AutoGen. Please take note that these AutoGen specific functions are not loaded and thus not made available until after the command line options have been processed and the AutoGen definitions have been loaded. They may, of course, be used in Scheme functions that get defined at those times, but they cannot be invoked.

3.4.1 `ag-function?' - test for function
3.4.2 `base-name' - base output name
3.4.3 `count' - definition count
3.4.4 `def-file' - definitions file name
3.4.5 `dne' - "Do Not Edit" warning
3.4.6 `error' - display message and exit
3.4.7 `exist?' - test for value name
3.4.8 `find-file' - locate a file in the search path
3.4.9 `first-for?' - detect first iteration
3.4.10 `for-by' - set iteration step
3.4.11 `for-from' - set initial index
3.4.12 `for-index' - get current loop index
3.4.13 `for-sep' - set loop separation string
3.4.14 `for-to' - set ending index
3.4.15 `get' - get named value
3.4.16 `high-lim' - get highest value index
3.4.17 `last-for?' - detect last iteration
3.4.18 `len' - get count of values
3.4.19 `low-lim' - get lowest value index
3.4.20 `match-value?' - test for matching value
3.4.21 `out-delete' - delete current output file
3.4.22 `out-depth' - output file stack depth
3.4.23 `out-move' - change name of output file
3.4.24 `out-name' - current output file name
3.4.25 `out-pop' - close current output file
3.4.26 `out-push-add' - append output to file
3.4.27 `out-push-new' - purge and create output file
3.4.28 `out-resume' - resume current output file
3.4.29 `out-suspend' - suspend current output file
3.4.30 `out-switch' - close and create new output
3.4.31 `set-writable' - Make the output file be writable
3.4.32 `stack' - make list of AutoGen values
3.4.33 `suffix' - get the current suffix
3.4.34 `tpl-file' - get the template file name
3.4.35 `tpl-file-line' - get the template file and line number

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.1 `ag-function?' - test for function

Usage: (ag-function? ag-name)
return SCM_BOOL_T if a specified name is a user-defined AutoGen macro, otherwise return SCM_BOOL_F.

Arguments:
ag-name - name of AutoGen macro

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.2 `base-name' - base output name

Usage: (base-name)
Returns a string containing the base name of the output file(s). Generally, this is also the base name of the definitions file.

This Scheme function takes no arguments.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.3 `count' - definition count

Usage: (count ag-name)
Count the number of entries for a definition. The input argument must be a string containing the name of the AutoGen values to be counted. If there is no value associated with the name, the result is an SCM immediate integer value of zero.

Arguments:
ag-name - name of AutoGen value

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.4 `def-file' - definitions file name

Usage: (def-file)
Get the name of the definitions file. Returns the name of the source file containing the AutoGen definitions.

This Scheme function takes no arguments.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.5 `dne' - "Do Not Edit" warning

Usage: (dne prefix [ first_prefix ])
Generate a "DO NOT EDIT" or "EDIT WITH CARE" warning string. Which depends on whether or not the --writable command line option was set. The first argument is a per-line string prefix. The optional second argument is a prefix for the first-line and, in read-only mode, activates the editor hints:
-*- buffer-read-only: t -*- vi: set ro:

Arguments:
prefix - string for starting each output line
first_prefix - Optional - for the first output line

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.6 `error' - display message and exit

Usage: (error message)
The argument is a string that printed out as part of an error message. The message is formed from the formatting string:

DEFINITIONS ERROR in %s line %d for %s:  %s\n

The first three arguments to this format are provided by the routine and are: The name of the template file, the line within the template where the error was found, and the current output file name.

After displaying the message, the current output file is removed and autogen exits with the EXIT_FAILURE error code. IF, however, the argument begins with the number 0 (zero), or the string is the empty string, then processing continues with the next suffix.

Arguments:
message - message to display before exiting

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.7 `exist?' - test for value name

Usage: (exist? ag-name)
return SCM_BOOL_T iff a specified name has an AutoGen value. The name may include indexes and/or member names. All but the last member name must be an aggregate definition. For example:
(exist? "foo[3].bar.baz")
will yield true if all of the following is true:
There is a member value of either group or string type named baz for some group value bar that is a member of the foo group with index 3. There may be multiple entries of bar within foo, only one needs to contain a value for baz.

Arguments:
ag-name - name of AutoGen value

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.8 `find-file' - locate a file in the search path

Usage: (find-file file-name [ suffix ])
AutoGen has a search path that it uses to locate template and definition files. This function will search the same list for `file-name', both with and without the `.suffix', if provided.

Arguments:
file-name - name of file with text
suffix - Optional - file suffix to try, too

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.9 `first-for?' - detect first iteration

Usage: (first-for? [ for_var ])
Returns SCM_BOOL_T if the named FOR loop (or, if not named, the current innermost loop) is on the first pass through the data. Outside of any FOR loop, it returns SCM_UNDEFINED. See section 3.6.13 FOR - Emit a template block multiple times.

Arguments:
for_var - Optional - which for loop

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.10 `for-by' - set iteration step

Usage: (for-by by)
This function records the "step by" information for an AutoGen FOR function. Outside of the FOR macro itself, this function will emit an error. See section 3.6.13 FOR - Emit a template block multiple times.

Arguments:
by - the iteration increment for the AutoGen FOR macro

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.11 `for-from' - set initial index

Usage: (for-from from)
This function records the initial index information for an AutoGen FOR function. Outside of the FOR macro itself, this function will emit an error. See section 3.6.13 FOR - Emit a template block multiple times.

Arguments:
from - the initial index for the AutoGen FOR macro

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.12 `for-index' - get current loop index

Usage: (for-index [ for_var ])
Returns the current index for the named FOR loop. If not named, then the index for the innermost loop. Outside of any FOR loop, it returns SCM_UNDEFINED. See section 3.6.13 FOR - Emit a template block multiple times.

Arguments:
for_var - Optional - which for loop

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.13 `for-sep' - set loop separation string

Usage: (for-sep separator)
This function records the separation string that is to be inserted between each iteration of an AutoGen FOR function. This is often nothing more than a comma. Outside of the FOR macro itself, this function will emit an error.

Arguments:
separator - the text to insert between the output of each FOR iteration

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.14 `for-to' - set ending index

Usage: (for-to to)
This function records the terminating value information for an AutoGen FOR function. Outside of the FOR macro itself, this function will emit an error. See section 3.6.13 FOR - Emit a template block multiple times.

Arguments:
to - the final index for the AutoGen FOR macro

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.15 `get' - get named value

Usage: (get ag-name)
Get the first string value associated with the name. It will always return either the associated string value, or the empty string.

Arguments:
ag-name - name of AutoGen value

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.16 `high-lim' - get highest value index

Usage: (high-lim ag-name)
Returns the highest index associated with an array of definitions. This is generally, but not necessarily, one less than the count value. (The indexes may be specified, rendering a non-zero based or sparse array of values.)

This is very useful for specifying the size of a zero-based array of values where not all values are present. For example:

tMyStruct myVals[ [+ (+ 1 (high-lim "my-val-list")) +] ];

Arguments:
ag-name - name of AutoGen value

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.17 `last-for?' - detect last iteration

Usage: (last-for? [ for_var ])
Returns SCM_BOOL_T if the named FOR loop (or, if not named, the current innermost loop) is on the last pass through the data. Outside of any FOR loop, it returns SCM_UNDEFINED. See section 3.6.13 FOR - Emit a template block multiple times.

Arguments:
for_var - Optional - which for loop

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.18 `len' - get count of values

Usage: (len ag-name)
If the named object is a group definition, then "len" is the same as "count". Otherwise, if it is one or more text definitions, then it is the sum of their string lengths. If it is a single text definition, then it is equivalent to (string-length (get "ag-name")).

Arguments:
ag-name - name of AutoGen value

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.19 `low-lim' - get lowest value index

Usage: (low-lim ag-name)
Returns the lowest index associated with an array of definitions.

Arguments:
ag-name - name of AutoGen value

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.20 `match-value?' - test for matching value

Usage: (match-value? op ag-name test-str)
This function answers the question, "Is there an AutoGen value named ag-name with a value that matches the pattern test-str using the match function op?" Return SCM_BOOL_T iff at least one occurrence of the specified name has such a value. The operator can be any function that takes two string arguments and yields a boolean. It is expected that you will use one of the string matching functions provided by AutoGen.
The value name must follow the same rules as the ag-name argument for exist? (see section 3.4.7 `exist?' - test for value name).

Arguments:
op - boolean result operator
ag-name - name of AutoGen value
test-str - string to test against

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.21 `out-delete' - delete current output file

Usage: (out-delete)
Remove the current output file. Cease processing the template for the current suffix. It is an error if there are push-ed output files. Use the (error "0") scheme function instead. See section 3.7 Redirecting Output.

This Scheme function takes no arguments.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.22 `out-depth' - output file stack depth

Usage: (out-depth)
Returns the depth of the output file stack. See section 3.7 Redirecting Output.

This Scheme function takes no arguments.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.23 `out-move' - change name of output file

Usage: (out-move new-name)
Rename current output file. See section 3.7 Redirecting Output. Please note: changing the name will not save a temporary file from being deleted. It may, however, be used on the root output file.

Arguments:
new-name - new name for the current output file

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.24 `out-name' - current output file name

Usage: (out-name)
Returns the name of the current output file. If the current file is a temporary, unnamed file, then it will scan up the chain until a real output file name is found. See section 3.7 Redirecting Output.

This Scheme function takes no arguments.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.25 `out-pop' - close current output file

Usage: (out-pop [ disp ])
If there has been a push on the output, then close that file and go back to the previously open file. It is an error if there has not been a push. See section 3.7 Redirecting Output.

If there is no argument, no further action is taken. Otherwise, the argument should be #t and the contents of the file are returned by the function.

Arguments:
disp - Optional - return contents of the file

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.26 `out-push-add' - append output to file

Usage: (out-push-add file-name)
Identical to push-new, except the contents are not purged, but appended to. See section 3.7 Redirecting Output.

Arguments:
file-name - name of the file to append text to

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.27 `out-push-new' - purge and create output file

Usage: (out-push-new [ file-name ])
Leave the current output file open, but purge and create a new file that will remain open until a pop delete or switch closes it. The file name is optional and, if omitted, the output will be sent to a temporary file that will be deleted when it is closed. See section 3.7 Redirecting Output.

Arguments:
file-name - Optional - name of the file to create

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.28 `out-resume' - resume current output file

Usage: (out-resume suspName)
If there has been a suspended output, then make that output descriptor current again. That output must have been suspended with the same tag name given to this routine as its argument.

Arguments:
suspName - A name tag for reactivating

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.29 `out-suspend' - suspend current output file

Usage: (out-suspend suspName)
If there has been a push on the output, then set aside the output descriptor for later reactiviation with (out-resume "xxx"). The tag name need not reflect the name of the output file. In fact, the output file may be an anonymous temporary file. You may also change the tag every time you suspend output to a file, because the tag names are forgotten as soon as the file has been "resumed".

Arguments:
suspName - A name tag for reactivating

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.30 `out-switch' - close and create new output

Usage: (out-switch file-name)
Switch output files - close current file and make the current file pointer refer to the new file. This is equivalent to out-pop followed by out-push-new, except that you may not pop the base level output file, but you may switch it. See section 3.7 Redirecting Output.

Arguments:
file-name - name of the file to create

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.31 `set-writable' - Make the output file be writable

Usage: (set-writable [ set? ])
This function will set the current output file to be writable (or not). This is only effective if neither the --writable nor --not-writable have been specified. This state is reset when the current suffix's output is complete.

Arguments:
set? - Optional - boolean arg, false to make output non-writable

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.32 `stack' - make list of AutoGen values

Usage: (stack ag-name)
Create a scheme list of all the strings that are associated with a name. They must all be text values or we choke.

Arguments:
ag-name - AutoGen value name

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.33 `suffix' - get the current suffix

Usage: (suffix)
Returns the current active suffix (see section 3.1 Format of the Pseudo Macro).

This Scheme function takes no arguments.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.34 `tpl-file' - get the template file name

Usage: (tpl-file)
Returns the name of the current template file.

This Scheme function takes no arguments.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.35 `tpl-file-line' - get the template file and line number

Usage: (tpl-file-line [ msg-fmt ])
Returns the file and line number of the current template macro using either the default format, "from %s line %d", or else the format you supply. For example, if you want to insert a "C" language file-line directive, you would supply the format "# %2$d %1$s".

Arguments:
msg-fmt - Optional - formatting for line message

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5 Common Scheme Functions

This section describes a number of general purpose functions that make the kind of string processing that AutoGen does a little easier. Unlike the AutoGen specific functions (see section 3.4 AutoGen Scheme Functions), these functions are available for direct use during definition load time.

3.5.1 `bsd' - BSD Public License
3.5.2 `c-string' - emit string for ANSI C
3.5.3 `error-source-line' - display of file & line
3.5.4 `extract' - extract text from another file
3.5.5 `fprintf' - format to a file
3.5.6 `gperf' - perform a perfect hash function
3.5.7 `gpl' - GNU General Public License
3.5.8 `in?' - test for string in list
3.5.9 `join' - join string list with separator
3.5.10 `kr-string' - emit string for K&R C
3.5.11 `lgpl' - GNU Library General Public License
3.5.12 `license' - an arbitrary license
3.5.13 `make-gperf' - build a perfect hash function program
3.5.14 `makefile-script' - create makefile script
3.5.15 `max' - maximum value in list
3.5.16 `min' - minimum value in list
3.5.17 `prefix' - prefix lines with a string
3.5.18 `printf' - format to stdout
3.5.19 `raw-shell-str' - single quote shell string
3.5.20 `shell' - invoke a shell script
3.5.21 `shell-str' - double quote shell string
3.5.22 `shellf' - format a string, run shell
3.5.23 `sprintf' - format a string
3.5.24 `string-capitalize' - capitalize a new string
3.5.25 `string-capitalize!' - capitalize a string
3.5.26 `string-contains-eqv?' - caseless substring
3.5.27 `string-contains?' - substring match
3.5.28 `string-downcase' - lower case a new string
3.5.29 `string-downcase!' - make a string be lower case
3.5.30 `string-end-eqv-match?' - caseless regex ending
3.5.31 `string-end-match?' - regex match end
3.5.32 `string-ends-eqv?' - caseless string ending
3.5.33 `string-ends-with?' - string ending
3.5.34 `string-equals?' - string matching
3.5.35 `string-eqv-match?' - caseless regex match
3.5.36 `string-eqv?' - caseless string match
3.5.37 `string-has-eqv-match?' - caseless regex contains
3.5.38 `string-has-match?' - contained regex match
3.5.39 `string-match?' - regex match
3.5.40 `string-start-eqv-match?' - caseless regex start
3.5.41 `string-start-match?' - regex match start
3.5.42 `string-starts-eqv?' - caseless string start
3.5.43 `string-starts-with?' - string starting
3.5.44 `string-substitute' - multiple global replacements
3.5.45 `string->c-name!' - map non-name chars to underscore
3.5.46 `string-tr' - convert characters with new result
3.5.47 `string-tr!' - convert characters
3.5.48 `string-upcase' - upper case a new string
3.5.49 `string-upcase!' - make a string be upper case
3.5.50 `sub-shell-str' - back quoted (sub-)shell string
3.5.51 `sum' - sum of values in list
3.5.52 `make-header-guard' - make self-inclusion guard
3.5.53 `autogen-version' - autogen version number

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.1 `bsd' - BSD Public License

Usage: (bsd prog_name owner prefix)
Emit a string that contains the Free BSD Public License. It takes three arguments: prefix contains the string to start each output line. owner contains the copyright owner. prog_name contains the name of the program the copyright is about.

Arguments:
prog_name - name of the program under the BSD
owner - Grantor of the BSD License
prefix - String for starting each output line

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.2 `c-string' - emit string for ANSI C

Usage: (c-string string)
Reform a string so that, when printed, the C compiler will be able to compile the data and construct a string that contains exactly what the current string contains. Many non-printing characters are replaced with escape sequences. Newlines are replaced with a backslash, an n, a closing quote, a newline, seven spaces and another re-opening quote. The compiler will implicitly concatenate them. The reader will see line breaks.

A K&R compiler will choke. Use kr-string for that compiler.

Arguments:
string - string to reformat

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.3 `error-source-line' - display of file & line

Usage: (error-source-line)
This function is only invoked just before Guile displays an error message. It displays the file name and line number that triggered the evaluation error. You should not need to invoke this routine directly. Guile will do it automatically.

This Scheme function takes no arguments.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.4 `extract' - extract text from another file

Usage: (extract file-name marker-fmt [ caveat ] [ default ])
This function is used to help construct output files that may contain text that is carried from one version of the output to the next.

The first two arguments are required, the second are optional:

  • The file-name argument is used to name the file that contains the demarcated text.
  • The marker-fmt is a formatting string that is used to construct the starting and ending demarcation strings. The sprintf function is given the marker-fmt with two arguments. The first is either "START" or "END". The second is either "DO NOT CHANGE THIS COMMENT" or the optional caveat argument.
  • caveat is presumed to be absent if it is the empty string (""). If absent, "DO NOT CHANGE THIS COMMENT" is used as the second string argument to the marker-fmt.
  • When a default argument is supplied and no pre-existing text is found, then this text will be inserted between the START and END markers.
The resulting strings are presumed to be unique within the subject file. As a simplified example:

[+ (extract "fname" "// %s - SOMETHING - %s" ""
"example default") +]
will result in the following text being inserted into the output:

// START - SOMETHING - DO NOT CHANGE THIS COMMENT
example default
// END   - SOMETHING - DO NOT CHANGE THIS COMMENT
The "example default" string can then be carried forward to the next generation of the output, provided the output is not named "fname" and the old output is renamed to "fname" before AutoGen-eration begins.

NOTE:
You can set aside previously generated source files inside the pseudo macro with a Guile/scheme function, extract the text you want to keep with this extract function. Just remember you should delete it at the end, too. Here is an example from my Finite State Machine generator:

[+ AutoGen5 Template  -*- Mode: text -*-
h=%s-fsm.h   c=%s-fsm.c
(shellf
"[ -f %1$s-fsm.h ] && mv -f %1$s-fsm.h .fsm.head
[ -f %1$s-fsm.c ] && mv -f %1$s-fsm.c .fsm.code" (base-name)) +]

This code will move the two previously produced output files to files named ".fsm.head" and ".fsm.code". At the end of the 'c' output processing, I delete them.

Arguments:
file-name - name of file with text
marker-fmt - format for marker text
caveat - Optional - warn about changing marker
default - Optional - default initial text

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.5 `fprintf' - format to a file

Usage: (fprintf port format [ format-arg ... ])
Format a string using arguments from the alist. Write to a specified port. The result will NOT appear in your output. Use this to print information messages to a template user.

Arguments:
port - Guile-scheme output port
format - formatting string
format-arg - Optional - list of arguments to formatting string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.6 `gperf' - perform a perfect hash function

Usage: (gperf name str)
Perform the perfect hash on the input string. This is only useful if you have previously created a gperf program with the make-gperf function See section 3.5.13 `make-gperf' - build a perfect hash function program. The name you supply here must match the name used to create the program and the string to hash must be one of the strings supplied in the make-gperf string list. The result will be a perfect hash index.

See the documentation for gperf(1GNU) for more details.

Arguments:
name - name of hash list
str - string to hash

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.7 `gpl' - GNU General Public License

Usage: (gpl prog-name prefix)
Emit a string that contains the GNU General Public License. It takes two arguments: prefix contains the string to start each output line, and prog_name contains the name of the program the copyright is about.

Arguments:
prog-name - name of the program under the GPL
prefix - String for starting each output line

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.8 `in?' - test for string in list

Usage: (in? test-string string-list ...)
Return SCM_BOOL_T if the first argument string is found in one of the entries in the second (list-of-strings) argument.

Arguments:
test-string - string to look for
string-list - list of strings to check

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.9 `join' - join string list with separator

Usage: (join separator list ...)
With the first argument as the separator string, joins together an a-list of strings into one long string. The list may contain nested lists, partly because you cannot always control that.

Arguments:
separator - string to insert between entries
list - list of strings to join

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.10 `kr-string' - emit string for K&R C

Usage: (kr-string string)
Reform a string so that, when printed, a K&R C compiler will be able to compile the data and construct a string that contains exactly what the current string contains. Many non-printing characters are replaced with escape sequences. New-lines are replaced with a backslash-n-backslash and newline sequence,

Arguments:
string - string to reformat

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.11 `lgpl' - GNU Library General Public License

Usage: (lgpl prog_name owner prefix)
Emit a string that contains the GNU Library General Public License. It takes three arguments: prefix contains the string to start each output line. owner contains the copyright owner. prog_name contains the name of the program the copyright is about.

Arguments:
prog_name - name of the program under the LGPL
owner - Grantor of the LGPL
prefix - String for starting each output line

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.12 `license' - an arbitrary license

Usage: (license lic_name prog_name owner prefix)
Emit a string that contains the named license. The license text is read from a file named, lic_name.lic, searching the standard directories. The file contents are used as a format argument to printf(3), with prog_name and owner as the two string formatting arguments. Each output line is automatically prefixed with the string prefix.

Arguments:
lic_name - file name of the license
prog_name - name of the licensed program or library
owner - Grantor of the License
prefix - String for starting each output line

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.13 `make-gperf' - build a perfect hash function program

Usage: (make-gperf name strings ...)
Build a program to perform perfect hashes of a known list of input strings. This function produces no output, but prepares a program named, `gperf_<name>' for use by the gperf function See section 3.5.6 `gperf' - perform a perfect hash function.

This program will be obliterated within a few seconds after AutoGen exits.

Arguments:
name - name of hash list
strings - list of strings to hash

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.14 `makefile-script' - create makefile script

Usage: (makefile-script text)
This function will take ordinary shell script text and reformat it so that it will work properly inside of a makefile shell script. Not every shell construct can be supported; the intent is to have most ordinary scripts work without much, if any, alteration.

The following transformations are performed on the source text:

  1. Trailing whitespace on each line is stripped.

  2. Except for the last line, the string, " ; \\" is appended to the end of every line that does not end with a backslash, semi-colon, conjunction operator or pipe. Note that this will mutilate multi-line quoted strings, but make renders it impossible to use multi-line constructs anyway.

  3. If the line ends with a backslash, it is left alone.

  4. If the line ends with one of the excepted operators, then a space and backslash is added.

  5. The dollar sign character is doubled, unless it immediately precedes an opening parenthesis or the single character make macros '*', '<', '@', '?' or '%'. Other single character make macros that do not have enclosing parentheses will fail. For shell usage of the "$@", "$?" and "$*" macros, you must enclose them with curly braces, e.g., "${?}". The ksh construct $(<command>) will not work. Though some makes accept ${var} constructs, this function will assume it is for shell interpretation and double the dollar character. You must use $(var) for all make substitutions.

  6. Double dollar signs are replaced by four before the next character is examined.

  7. Every line is prefixed with a tab, unless the first line already starts with a tab.

  8. The newline character on the last line, if present, is suppressed.

  9. Blank lines are stripped.

This function is intended to be used approximately as follows:

$(TARGET) : $(DEPENDENCIES)
<+ (out-push-new) +>
....mostly arbitrary shell script text....
<+ (makefile-script (out-pop #t)) +>

Arguments:
text - the text of the script

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.15 `max' - maximum value in list

Usage: (max list ...)
Return the maximum value in the list

Arguments:
list - list of values. Strings are converted to numbers

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.16 `min' - minimum value in list

Usage: (min list ...)
Return the minimum value in the list

Arguments:
list - list of values. Strings are converted to numbers

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.17 `prefix' - prefix lines with a string

Usage: (prefix prefix text)
Prefix every line in the second string with the first string.

For example, if the first string is "# " and the second contains:
two
lines
The result string will contain:
# two
# lines

Arguments:
prefix - string to insert at start of each line
text - multi-line block of text

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.18 `printf' - format to stdout

Usage: (printf format [ format-arg ... ])
Format a string using arguments from the alist. Write to the default output port. The result will NOT appear in your output. Use this to print information messages to a template user.

Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.19 `raw-shell-str' - single quote shell string

Usage: (raw-shell-str string)
Convert the text of the string into a singly quoted string that a normal shell will process into the original string. (It will not do macro expansion later, either.) Contained single quotes become tripled, with the middle quote escaped with a backslash. Normal shells will reconstitute the original string.

NOTE: some shells will not correctly handle unusual non-printing characters. This routine works for most reasonably conventional ASCII strings.

Arguments:
string - string to transform

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.20 `shell' - invoke a shell script

Usage: (shell command)
Generate a string by writing the value to a server shell and reading the output back in. The template programmer is responsible for ensuring that it completes within 10 seconds. If it does not, the server will be killed, the output tossed and a new server started.

Arguments:
command - shell command - the result value is stdout

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.21 `shell-str' - double quote shell string

Usage: (shell-str string)
Convert the text of the string into a double quoted string that a normal shell will process into the original string, almost. It will add the escape character \\ before two special characters to accomplish this: the backslash \\ and double quote ".

NOTE: some shells will not correctly handle unusual non-printing characters. This routine works for most reasonably conventional ASCII strings.

WARNING:
This function omits the extra backslash in front of a backslash, however, if it is followed by either a backquote or a dollar sign. It must do this because otherwise it would be impossible to protect the dollar sign or backquote from shell evaluation. Consequently, it is not possible to render the strings "\\$" or "\\`". The lesser of two evils.

All others characters are copied directly into the output.

The sub-shell-str variation of this routine behaves identically, except that the extra backslash is omitted in front of " instead of `. You have to think about it. I'm open to suggestions.

Meanwhile, the best way to document is with a detailed output example. If the backslashes make it through the text processing correctly, below you will see what happens with three example strings. The first example string contains a list of quoted foos, the second is the same with a single backslash before the quote characters and the last is with two backslash escapes. Below each is the result of the raw-shell-str, shell-str and sub-shell-str functions.

foo[0]       = 'foo' "foo" `foo` $foo
raw-shell-str: ''\''foo'\'' "foo" `foo` $foo'
shell-str:     "'foo' \"foo\" `foo` $foo"
sub-shell-str: `'foo' "foo" \`foo\` $foo`

foo[1]       = \'bar\' \"bar\" \`bar\` \$bar
raw-shell-str: '\'\''bar\'\'' \"bar\" \`bar\` \$bar'
shell-str:     "\\'bar\\' \\\"bar\\\" \`bar\` \$bar"
sub-shell-str: `\\'bar\\' \"bar\" \\\`bar\\\` \$bar`

foo[2]       = \\'BAZ\\' \\"BAZ\\" \\`BAZ\\` \\$BAZ
raw-shell-str: '\\'\''BAZ\\'\'' \\"BAZ\\" \\`BAZ\\` \\$BAZ'
shell-str:     "\\\\'BAZ\\\\' \\\\\"BAZ\\\\\" \\\`BAZ\\\` \\\$BAZ"
sub-shell-str: `\\\\'BAZ\\\\' \\\"BAZ\\\" \\\\\`BAZ\\\\\` \\\$BAZ`

There should be four, three, five and three backslashes for the four examples on the last line, respectively. The next to last line should have four, five, three and three backslashes. If this was not accurately reproduced, take a look at the agen5/test/shell.test test. Notice the backslashes in front of the dollar signs. It goes from zero to one to three for the "cooked" string examples.

Arguments:
string - string to transform

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.22 `shellf' - format a string, run shell

Usage: (shellf format [ format-arg ... ])
Format a string using arguments from the alist, then send the result to the shell for interpretation.

Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.23 `sprintf' - format a string

Usage: (sprintf format [ format-arg ... ])
Format a string using arguments from the alist.

Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.24 `string-capitalize' - capitalize a new string

Usage: (string-capitalize str)
Create a new SCM string containing the same text as the original, only all the first letter of each word is upper cased and all other letters are made lower case.

Arguments:
str - input string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.25 `string-capitalize!' - capitalize a string

Usage: (string-capitalize! str)
capitalize all the words in an SCM string.

Arguments:
str - input/output string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.26 `string-contains-eqv?' - caseless substring

Usage: (*=* text match)
string-contains-eqv?: Test to see if a string contains an equivalent string. `equivalent' means the strings match, but without regard to character case and certain characters are considered `equivalent'. Viz., '-', '_' and '^' are equivalent.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.27 `string-contains?' - substring match

Usage: (*==* text match)
string-contains?: Test to see if a string contains a substring. "strstr(3)" will find an address.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.28 `string-downcase' - lower case a new string

Usage: (string-downcase str)
Create a new SCM string containing the same text as the original, only all the upper case letters are changed to lower case.

Arguments:
str - input string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.29 `string-downcase!' - make a string be lower case

Usage: (string-downcase! str)
Change to lower case all the characters in an SCM string.

Arguments:
str - input/output string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.30 `string-end-eqv-match?' - caseless regex ending

Usage: (*~ text match)
string-end-eqv-match?: Test to see if a string ends with a pattern. Case is not significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.31 `string-end-match?' - regex match end

Usage: (*~~ text match)
string-end-match?: Test to see if a string ends with a pattern. Case is significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.32 `string-ends-eqv?' - caseless string ending

Usage: (*= text match)
string-ends-eqv?: Test to see if a string ends with an equivalent string.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.33 `string-ends-with?' - string ending

Usage: (*== text match)
string-ends-with?: Test to see if a string ends with a substring. strcmp(3) returns zero for comparing the string ends.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.34 `string-equals?' - string matching

Usage: (== text match)
string-equals?: Test to see if two strings exactly match.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.35 `string-eqv-match?' - caseless regex match

Usage: (~ text match)
string-eqv-match?: Test to see if a string fully matches a pattern. Case is not significant, but any character equivalences must be expressed in your regular expression.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.36 `string-eqv?' - caseless string match

Usage: (= text match)
string-eqv?: Test to see if two strings are equivalent. `equivalent' means the strings match, but without regard to character case and certain characters are considered `equivalent'. Viz., '-', '_' and '^' are equivalent. If the arguments are not strings, then the result of the numeric comparison is returned.

This is an overloaded operation. If the arguments are not both strings, then the query is passed through to scm_num_eq_p().

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.37 `string-has-eqv-match?' - caseless regex contains

Usage: (*~* text match)
string-has-eqv-match?: Test to see if a string contains a pattern. Case is not significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.38 `string-has-match?' - contained regex match

Usage: (*~~* text match)
string-has-match?: Test to see if a string contains a pattern. Case is significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.39 `string-match?' - regex match

Usage: (~~ text match)
string-match?: Test to see if a string fully matches a pattern. Case is significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.40 `string-start-eqv-match?' - caseless regex start

Usage: (~* text match)
string-start-eqv-match?: Test to see if a string starts with a pattern. Case is not significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.41 `string-start-match?' - regex match start

Usage: (~~* text match)
string-start-match?: Test to see if a string starts with a pattern. Case is significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.42 `string-starts-eqv?' - caseless string start

Usage: (=* text match)
string-starts-eqv?: Test to see if a string starts with an equivalent string.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.43 `string-starts-with?' - string starting

Usage: (==* text match)
string-starts-with?: Test to see if a string starts with a substring.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.44 `string-substitute' - multiple global replacements

Usage: (string-substitute source match repl)
match and repl may be either a single string or a list of strings. Either way, they must have the same structure and number of elements. For example, to replace all less than and all greater than characters, do something like this:

(string-substitute str '("<" ">") '("<" "&gt;"))

Arguments:
source - string to transform
match - substring or substring list to be replaced
repl - replacement strings or substrings

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.45 `string->c-name!' - map non-name chars to underscore

Usage: (string->c-name! str)
Change all the graphic characters that are invalid in a C name token into underscores. Whitespace characters are ignored. Any other character type (i.e. non-graphic and non-white) will cause a failure.

Arguments:
str - input/output string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.46 `string-tr' - convert characters with new result

Usage: (string-tr source match translation)
This is identical to string-tr!, except that it does not over-write the previous value.

Arguments:
source - string to transform
match - characters to be converted
translation - conversion list

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.47 `string-tr!' - convert characters

Usage: (string-tr! source match translation)
This is the same as the tr(1) program, except the string to transform is the first argument. The second and third arguments are used to construct mapping arrays for the transformation of the first argument.

It is too bad this little program has so many different and incompatible implementations!

Arguments:
source - string to transform
match - characters to be converted
translation - conversion list

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.48 `string-upcase' - upper case a new string

Usage: (string-upcase str)
Create a new SCM string containing the same text as the original, only all the lower case letters are changed to upper case.

Arguments:
str - input string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.49 `string-upcase!' - make a string be upper case

Usage: (string-upcase! str)
Change to upper case all the characters in an SCM string.

Arguments:
str - input/output string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.50 `sub-shell-str' - back quoted (sub-)shell string

Usage: (sub-shell-str string)
This function is substantially identical to shell-str, except that the quoting character is ` and the "leave the escape alone" character is ".

Arguments:
string - string to transform

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.51 `sum' - sum of values in list

Usage: (sum list ...)
Compute the sum of the list of expressions.

Arguments:
list - list of values. Strings are converted to numbers

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.52 `make-header-guard' - make self-inclusion guard

Usage: (make-header-guard prefix)
This function will insert the #ifndef and #define C preprocessing directives that will cause a header file to exclude itself once it has been sourced in a compilation. The #define name is composed as follows:

  1. The first element is the string argument and a separating underscore.
  2. That is followed by the name of the header file with illegal characters mapped to underscores.
  3. The end of the name is always, "_GUARD".
  4. Finally, the entire string is mapped to upper case.

The final #define name is stored in an SCM symbol named header-guard. Consequently, the concluding #endif for the file should read something like:

#endif /* [+ (. header-guard) +] */

The name of the header file (the current output file) is also stored in an SCM symbol, header-file. Therefore, if you are also generating a C file that uses the previously generated header file, you can put this into that generated file:

#include "[+ (. header-file) +]"

Obviously, if you are going to produce more than one header file from a particular template, you will need to be careful how these SCM symbols get handled.

Arguments:
prefix - prefix for #define name.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.53 `autogen-version' - autogen version number

This is a symbol defining the current AutoGen version number string. It was first defined in AutoGen-5.2.14.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6 AutoGen Native Macros

This section describes the various AutoGen natively defined macros. Unlike the Scheme functions, some of these macros are "block macros" with a scope that extends through a terminating macro. Block macros must not overlap. That is to say, a block macro started within the scope of an encompassing block macro must have its matching end macro appear before the encompassing block macro is either ended or subdivided.

The block macros are these:

CASE
This macro has scope through the ESAC macro. The scope is subdivided by SELECT macros. You must have at least one SELECT macro.

DEFINE
This macro has scope through the ENDDEF macro. The defined user macro can never be a block macro.

FOR
This macro has scope through the ENDFOR macro.

IF
This macro has scope through the ENDIF macro. The scope may be subdivided by ELIF and ELSE macros. Obviously, there may be only one ELSE macro and it must be the last of these subdivisions.

INCLUDE
This macro has the scope of the included file. It is a block macro in the sense that the included file must not contain any incomplete block macros.

WHILE
This macro has scope through the ENDWHILE macro.
3.6.1 AutoGen Macro Syntax
3.6.2 CASE - Select one of several template blocks
3.6.3 COMMENT - A block of comment to be ignored
3.6.4 DEFINE - Define a user AutoGen macro
3.6.5 ELIF - Alternate Conditional Template Block
3.6.6 ELSE - Alternate Template Block
3.6.7 ENDDEF - Ends a macro definition.
3.6.8 ENDFOR - Terminates the FOR function template block
3.6.9 ENDIF - Terminate the IF Template Block
3.6.10 ENDWHILE - Terminate the WHILE Template Block
3.6.11 ESAC - Terminate the CASE Template Block
3.6.12 EXPR - Evaluate and emit an Expression
3.6.13 FOR - Emit a template block multiple times
3.6.14 IF - Conditionally Emit a Template Block
3.6.15 INCLUDE - Read in and emit a template block
3.6.16 INVOKE - Invoke a User Defined Macro
3.6.17 SELECT - Selection block for CASE function
3.6.18 UNKNOWN - Either a user macro or a value name.
3.6.19 WHILE - Conditionally loop over a Template Block
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.1 AutoGen Macro Syntax

The general syntax is:

[ { <native-macro-name> | <user-defined-name> } ] [ <arg> ... ]

The syntax for <arg> depends on the particular macro, but is generally a full expression (see section 3.3 Macro Expression Syntax). Here are the exceptions to that general rule:

  1. INVOKE macros, implicit or explicit, must be followed by a list of name/string value pairs. The string values are simple expressions, as described above.

    That is, the INVOKE syntax is either:
    <user-macro-name> [ <name> [ = <expression> ] ... ]
    or
    INVOKE <name-expression> [ <name> [ = <expression> ] ... ]

  2. AutoGen FOR macros must be in one of two forms:

    FOR <name> [ <separator-string> ]
    or
    FOR <name> (...Scheme expression list)
    where <name> must be a simple name and the Scheme expression list is expected to contain one or more of the for-from, for-to, for-by, and for-sep functions. (See section 3.6.13 FOR - Emit a template block multiple times, and 3.4 AutoGen Scheme Functions)

  3. AutoGen DEFINE macros must be followed by a simple name. Anything after that is ignored. See section 3.6.4 DEFINE - Define a user AutoGen macro.

  4. The AutoGen COMMENT, ELSE, ESAC and the END* macros take no arguments and ignore everything after the macro name (e.g. see 3.6.3 COMMENT - A block of comment to be ignored)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.2 CASE - Select one of several template blocks

The arguments are evaluated and converted to a string, if necessary. (see section 3.6.12 EXPR - Evaluate and emit an Expression) The scope of the macro is up to the matching ESAC function. Within the scope of a CASE, this string is matched against case selection macros. There are sixteen match macros that are derived from four different ways the test may be performed, plus an "always true" match. The code for each selection expression is formed as follows:

  1. Must the match start matching from the beginning of the string? If not, then the match macro code starts with an asterisk (*).
  2. Must the match finish matching at the end of the string? If not, then the match macro code ends with an asterisk (*).
  3. Is the match a pattern match or a string comparison? If a comparison, use an equal sign (=). If a pattern match, use a tilde (~).
  4. Is the match case sensitive? If alphabetic case is important, double the tilde or equal sign.
  5. Do you need a default match when none of the others match? Use a single asterisk (*).

For example:

[+ CASE <full-expression> +]
[+ ~~*  "[Tt]est" +]reg exp must match at start, not at end
[+ ==   "TeSt"    +]a full-string, case sensitive compare
[+ =    "TEST"    +]a full-string, case insensitive compare
[+ *              +]always match - no testing
[+ ESAC +]

<full-expression> (see section 3.3 Macro Expression Syntax) may be any expression, including the use of apply-codes and value-names. If the expression yields a number, it is converted to a decimal string.

These case selection codes have also been implemented as Scheme expression functions using the same codes (see section 3.5 Common Scheme Functions).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.3 COMMENT - A block of comment to be ignored

If the native macro name code is #, then the entire macro function is treated as a comment and ignored.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.4 DEFINE - Define a user AutoGen macro

This function will define a new macro. You must provide a name for the macro. You do not specify any arguments, though the invocation may specify a set of name/value pairs that are to be active during the processing of the macro.

[+ define foo +]
... macro body with macro functions ...
[+ enddef +]
... [+ foo bar='raw text' baz=<<text expression>> +]

Once the macro has been defined, this new macro can be invoked by specifying the macro name as the first token after the start macro marker. Alternatively, you may make the invocation explicitly invoke a defined macro by specifying INVOKE in the macro invocation. If you do that, the macro name can be computed with an expression that gets evaluated every time the INVOKE macro is encountered. See section 3.6.16 INVOKE - Invoke a User Defined Macro.

Any remaining text in the macro invocation will be used to create new name/value pairs that only persist for the duration of the processing of the macro. The expressions are evaluated the same way basic expressions are evaluated. See section 3.3 Macro Expression Syntax.

The resulting definitions are handled much like regular definitions, except:

  1. The values may not be compound. That is, they may not contain nested name/value pairs.
  2. The bindings go away when the macro is complete.
  3. The name/value pairs are separated by whitespace instead of semi-colons.
  4. Sequences of strings are not concatenated.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.5 ELIF - Alternate Conditional Template Block

This macro must only appear after an IF function, and before any associated ELSE or ENDIF functions. It denotes the start of an alternate template block for the IF function. Its expression argument is evaluated as are the arguments to IF. For a complete description See section 3.6.14 IF - Conditionally Emit a Template Block.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.6 ELSE - Alternate Template Block

This macro must only appear after an IF function, and before the associated ENDIF function. It denotes the start of an alternate template block for the IF function. For a complete description See section 3.6.14 IF - Conditionally Emit a Template Block.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.7 ENDDEF - Ends a macro definition.

This macro ends the DEFINE function template block. For a complete description See section 3.6.4 DEFINE - Define a user AutoGen macro.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.8 ENDFOR - Terminates the FOR function template block

This macro ends the FOR function template block. For a complete description See section 3.6.13 FOR - Emit a template block multiple times.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.9 ENDIF - Terminate the IF Template Block

This macro ends the IF function template block. For a complete description See section 3.6.14 IF - Conditionally Emit a Template Block.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.10 ENDWHILE - Terminate the WHILE Template Block

This macro ends the WHILE function template block. For a complete description See section 3.6.19 WHILE - Conditionally loop over a Template Block.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.11 ESAC - Terminate the CASE Template Block

This macro ends the CASE function template block. For a complete description, See section 3.6.2 CASE - Select one of several template blocks.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.12 EXPR - Evaluate and emit an Expression

This macro does not have a name to cause it to be invoked explicitly, though if a macro starts with one of the apply codes or one of the simple expression markers, then an expression macro is inferred. The result of the expression evaluation (see section 3.3 Macro Expression Syntax) is written to the current output.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.13 FOR - Emit a template block multiple times

This macro has a slight variation on the standard syntax:
FOR <value-name> [ <separator-string> ]
or
FOR <value-name> (...Scheme expression list

The first argument must be the name of an AutoGen value. If there is no value associated with the name, the FOR loop block is skipped entirely. The scope of the FOR function extends to the corresponding ENDFOR macro.

If there are any further arguments, if the first character is either a semi-colon (;) or an opening parenthesis ((), then it is presumed to be a Scheme expression containing the FOR macro specific functions for-from, for-by, for-to, and/or for-sep. See section 3.4 AutoGen Scheme Functions. Otherwise, the remaining text is presumed to be a string for inserting between each iteration of the loop. This string will be emitted one time less than the number of iterations of the loop. That is, it is emitted after each loop, excepting for the last iteration.

If the from/by/to functions are invoked, they will specify which copies of the named value are to be processed. If there is no copy of the named value associated with a particular index, the FOR template block will be instantiated anyway. The template must use methods for detecting missing definitions and emitting default text. In this fashion, you can insert entries from a sparse or non-zero based array into a dense, zero based array.

NB: the for-from, for-to, for-by and for-sep functions are disabled outside of the context of the FOR macro. Likewise, the first-for, last-for and for-index functions are disabled outside of the range of a FOR block.

[+FOR var (for-from 0) (for-to <number>) (for-sep ",") +]
... text with various substitutions ...[+
ENDFOR var+]

this will repeat the ... text with various substitutions ... <number>+1 times. Each repetition, except for the last, will have a comma , after it.

[+FOR var ",\n" +]
... text with various substitutions ...[+
ENDFOR var +]

This will do the same thing, but only for the index values of var that have actually been defined.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.14 IF - Conditionally Emit a Template Block

Conditional block. Its arguments are evaluated (see section 3.6.12 EXPR - Evaluate and emit an Expression) and if the result is non-zero or a string with one or more bytes, then the condition is true and the text from that point until a matched ELIF, ELSE or ENDIF is emitted. ELIF introduces a conditional alternative if the IF clause evaluated FALSE and ELSE introduces an unconditional alternative.

[+IF <full-expression> +]
emit things that are for the true condition[+

ELIF <full-expression-2> +]
emit things that are true maybe[+

ELSE "This may be a comment" +]
emit this if all but else fails[+

ENDIF "This may *also* be a comment" +]

<full-expression> may be any expression described in the EXPR expression function, including the use of apply-codes and value-names. If the expression yields an empty string, it is interpreted as false.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.15 INCLUDE - Read in and emit a template block

The entire contents of the named file is inserted at this point. The contents of the file are processed for macro expansion. The arguments are eval-ed, so you may compute the name of the file to be included. The included file must not contain any incomplete function blocks. Function blocks are template text beginning with any of the macro functions `CASE', `DEFINE', `FOR', `IF' and `WHILE'; extending through their respective terminating macro functions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.16 INVOKE - Invoke a User Defined Macro

User defined macros may be invoked explicitly or implicitly. If you invoke one implicitly, the macro must begin with the name of the defined macro. Consequently, this may not be a computed value. If you explicitly invoke a user defined macro, the macro begins with the macro name INVOKE followed by a basic expression that must yield a known user defined macro. A macro name _must_ be found, or AutoGen will issue a diagnostic and exit.

Arguments are passed to the invoked macro by name. The text following the macro name must consist of a series of names each of which is followed by an equal sign (=) and a basic expression that yields a string.

The string values may contain template macros that are parsed the first time the macro is processed and evaluated again every time the macro is evaluated.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.17 SELECT - Selection block for CASE function

This macro selects a block of text by matching an expression against the sample text expression evaluated in the CASE macro. See section 3.6.2 CASE - Select one of several template blocks.

You do not specify a SELECT macro with the word "select". Instead, you must use one of the 17 match operators described in the CASE macro description.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.18 UNKNOWN - Either a user macro or a value name.

The macro text has started with a name not known to AutoGen. If, at run time, it turns out to be the name of a defined macro, then that macro is invoked. If it is not, then it is a conditional expression that is evaluated only if the name is defined at the time the macro is invoked.

You may not specify UNKNOWN explicitly.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.19 WHILE - Conditionally loop over a Template Block

Conditionally repeated block. Its arguments are evaluated (see section 3.6.12 EXPR - Evaluate and emit an Expression) and as long as the result is non-zero or a string with one or more bytes, then the condition is true and the text from that point until a matched ENDWHILE is emitted.

[+WHILE <full-expression> +]
emit things that are for the true condition[+

ENDWHILE +]

<full-expression> may be any expression described in the EXPR expression function, including the use of apply-codes and value-names. If the expression yields an empty string, it is interpreted as false.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7 Redirecting Output

AutoGen provides a means for redirecting the template output to different files. It is accomplished by providing a set of Scheme functions named out-* (see section 3.4 AutoGen Scheme Functions).

`out-push (see section 3.4.27 `out-push-new' - purge and create output file)'
This allows you to logically "push" output files onto a stack.

`out-pop (see section 3.4.25 `out-pop' - close current output file)'
This function closes the current output file and resumes output to the next one in the stack.

`out-suspend (see section 3.4.29 `out-suspend' - suspend current output file)'
This function does not close the current output, but instead sets it aside for resumption with

`out-resume (see section 3.4.28 `out-resume' - resume current output file)'
This will put a named file descriptor back onto the top of stack so that it becomes the current output again.

`out-switch (see section 3.4.30 `out-switch' - close and create new output)'
This closes the current output and creates a new file, purging any preexisting one. This is a shortcut for "pop" followed by "push", but can also be done at the base level.

`out-move (see section 3.4.23 `out-move' - change name of output file)'
Renames the current output file without closing it.

There are also several functions for determining the output status. See section 3.4 AutoGen Scheme Functions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Augmenting AutoGen Features

AutoGen was designed to be simple to enhance. You can do it by providing shell commands, Guile/Scheme macros or callout functions that can be invoked as a Guile macro. Here is how you do these.

4.1 Shell Output Commands
4.2 Guile Macros
4.3 Guile Callout Functions
4.4 AutoGen Macros

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 Shell Output Commands

Shell commands are run inside of a server process. This means that, unlike `make', context is kept from one command to the next. Consequently, you can define a shell function in one place inside of your template and invoke it in another. You may also store values in shell variables for later reference. If you load functions from a file containing shell functions, they will remain until AutoGen exits.

If your shell script should determine that AutoGen should stop processing, the recommended method for stopping AutoGen is:
echo "some error text" >&2
kill -2 ${AG_pid}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2 Guile Macros

Guile also maintains context from one command to the next. This means you may define functions and variables in one place and reference them elsewhere. You also may load Guile macro definitions from a Scheme file by using the --load-scheme command line option (see section 5.7 load-scheme option (-S)). Beware, however, that the AutoGen specific scheme functions have not been loaded at this time, so though you may define functions that reference them, do not invoke the AutoGen functions at this time.

If your Scheme script should determine that AutoGen should stop processing, the recommended method for stopping AutoGen is:
(error "some error text")

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3 Guile Callout Functions

Callout functions must be registered with Guile to work. This can be accomplished either by putting your routines into a shared library that contains a void scm_init( void ) routine that registers these routines, or by building them into AutoGen.

To build them into AutoGen, you must place your routines in the source directory and name the files `exp*.c'. You also must have a stylized comment that `getdefs' can find that conforms to the following:

/*=gfunc <function-name>
 *
 *  what:    <short one-liner>
 *  general_use:
 *  string:  <invocation-name-string>
 *  exparg:  <name>, <description> [, ['optional'] [, 'list']]
 *  doc:     A long description telling people how to use
 *           this function.
=*/
SCM
ag_scm_<function-name>( SCM arg_name[, ...] )
{ <code> }

`gfunc'
You must have this exactly thus.

`<function-name>'
This must follow C syntax for variable names

`<short one-liner>'
This should be about a half a line long. It is used as a subsection title in this document.

`general_use:'
You must supply this unless you are an AutoGen maintainer and are writing a function that queries or modifies the state of AutoGen.

`<invocation-name-string>'
Normally, the function-name string will be transformed into a reasonable invocation name. However, that is not always true. If the result does not suit your needs, then supply an alternate string.

`exparg:'
You must supply one for each argument to your function. All optional arguments must be last. The last of the optional arguments may be a list, if you choose.

`doc:'
Please say something meaningful.

`[, ...]'
Do not actually specify an ANSI ellipsis here. You must provide for all the arguments you specified with exparg.

See the Guile documentation for more details. More information is also available in a large comment at the beginning of the `agen5/snarf.tpl' template file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4 AutoGen Macros

There are two kinds those you define yourself and AutoGen native. The user-defined macros may be defined in your templates or loaded with the --lib-template option (See 3.6.4 DEFINE - Define a user AutoGen macro and 5.4 lib-template option (-l)).

As for AutoGen native macros, do not add any. It is easy to do, but I won't like it. The basic functions needed to accomplish looping over and selecting blocks of text have proven to be sufficient over a period of several years. New text transformations can be easily added via any of the AutoGen extension methods, as discussed above.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Invoking autogen

This chapter was generated by AutoGen, the aginfo template and the option descriptions for the autogen program. It documents the autogen usage text and option meanings.

This software is released under the GNU General Public License.

5.1 autogen usage help (-?)
5.5 base-name option (-b)
5.20 define option (-D)
5.6 definitions option
5.12 equate option
5.4 lib-template option (-l)
5.8 load-functions option (-F)
5.7 load-scheme option (-S)
5.14 loop-limit option
5.3 override-tpl option (-T)
5.10 select-suffix option (-o)
5.18 show-defs option
5.19 show-shell option
5.9 skip-suffix option (-s)
5.11 source-time option
5.2 templ-dirs option (-L)
5.15 timeout option (-t)
5.17 trace-out option
5.16 trace option
5.21 undefine option (-U)
5.13 writable option

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 autogen usage help (-?)

This is the automatically generated usage text for autogen:

@exampleindent 0
autogen - The Automated Program Generator - Ver. 5.3.7
USAGE:  autogen [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ]
  Flg Arg Option-Name    Description
   -L YES templ-dirs     Template search directory list
                                - may appear multiple times
   -T YES override-tpl   Override template file
                                - may not be preset
   -l YES lib-template   Library template file
                                - may appear multiple times
   -b YES base-name      Base name for output file(s)
                                - may not be preset
      YES definitions    Definitions input file
                                - disabled as --no-definitions
                                - enabled by default
                                - may not be preset
   -S YES load-scheme    Scheme code file to load
   -F YES load-functions Load scheme callout library
   -s YES skip-suffix    Omit the file with this suffix
                                - may not be preset
                                - may appear multiple times
   -o opt select-suffix  specify this output suffix
                                - may not be preset
                                - may appear multiple times
      no  source-time    set mod times to latest source
                                - disabled as --no-source-time
      YES equate         characters considered equivalent
      no  writable       Allow output files to be writable
                                - disabled as --not-writable
                                - may not be preset

The following options are often useful while debugging new templates:

  Flg Arg Option-Name    Description
      Num loop-limit     Limit on increment loops
                                  it must lie in one of the ranges:
                                  -1 exactly, or
                                  1 to 16777216
   -t Num timeout        Time limit for servers
                                  it must lie in the range: 0 to 3600
      KWd trace          tracing level of detail
      YES trace-out      tracing output file or filter

These options can be used to control what gets processed
in the definitions files and template files.

  Flg Arg Option-Name    Description
   -D YES define         name to add to definition list
                                - may appear multiple times
   -U YES undefine       definition list removal pattern
                                - an alternate for define

Auto-supported Options:

  Flg Arg Option-Name    Description
   -v opt version        Output version information and exit
   -? no  help           Display usage information and exit
   -! no  more-help      Extended usage information passed thru pager
   -> opt save-opts      Save the option state to an rc file
   -< YES load-opts      Load options from an rc file
                                - disabled as --no-load-opts
                                - may appear multiple times

Options may be specified by doubled hyphens and their name
or by a single hyphen and the flag character (option value).

AutoGen creates text files from templates using external definitions.

The following option preset mechanisms are supported:
 - reading file $HOME/.autogenrc
 - reading file ./.autogenrc
 - examining environment variables named AUTOGEN_*

The valid trace option keywords are:
        nothing
        templates
        block-macros
        expressions
        everything

The definitions file (`<def-file>') can be specified with the
`definitions' option or as the command argument, but not both.
Omitting it or specifying `-' will result in reading definitions from
standard input.

The output file names are based on the template, but generally use the
base name of the definition file.  If standard in is read for the
definitions, then `stdin' will be used for that base name.  The
suffixes to the base name are gotten from the template.  However, the
template file may specify the entire output file name.  The generated
files are always created in the current directory.  If you need to
place output in an alternate directory, `cd' to that directory and use
the `--templ_dirs' option to search the original directory.

`loop-limit' is used in debugging to stop runaway expansions.
@exampleindent 4

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 templ-dirs option (-L)

This is the "template search directory list" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.

Add a directory to the list of directories to search when opening a template, either as the primary template or an included one. The last entry has the highest priority in the search list. That is to say, they are searched in reverse order.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.3 override-tpl option (-T)

This is the "override template file" option.

This option has some usage constraints. It:

  • may not be preset with environment variables or in initialization (rc) files.

Definition files specify the standard template that is to be expanded. This option will override that name and expand a different template.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4 lib-template option (-l)

This is the "library template file" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.

DEFINE macros are saved from this template file for use in processing the main macro file. Template text aside from the DEFINE macros is is ignored.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.5 base-name option (-b)

This is the "base name for output file(s)" option.

This option has some usage constraints. It:

  • may not be preset with environment variables or in initialization (rc) files.

A template may specify the exact name of the output file. Normally, it does not. Instead, the name is composed of the base name of the definitions file with suffixes appended. This option will override the base name derived from the definitions file name. This is required if there is no definitions file and advisable if definitions are being read from stdin. If the definitions are being read from standard in, the base name defaults to `stdin'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.6 definitions option

This is the "definitions input file" option.

This option has some usage constraints. It:

  • is enabled by default.
  • may not be preset with environment variables or in initialization (rc) files.

Use this argument to specify the input definitions file with a command line option. If you do not specify this option, then there must be a command line argument that specifies the file, even if only to specify stdin with a hyphen (-). Specify, --no-definitions when you wish to process a template without any active AutoGen definitions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.7 load-scheme option (-S)

This is the "scheme code file to load" option. Use this option to pre-load Scheme scripts into the Guile interpreter before template processing begins. Please note that the AutoGen specific functions are not loaded until after argument processing. So, though they may be specified in lambda functions you define, they may not be invoked until after option processing is complete.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.8 load-functions option (-F)

This is the "load scheme callout library" option. This option is used to load Guile-scheme callout functions. The automatically called initialization routine scm_init must be used to register these routines or data. This routine can be generated by using the following command and the `snarf.tpl' template. Read the introductory comment in `snarf.tpl' to see what the `getdefs(1AG)' comment must contain.

GRP_NAME=whateveryoulike
eopt="subblock=exparg=arg_name,arg_desc,arg_optional,arg_list"
eopt="$eopt defs=gfunc templ=snarf srcfile"
eopt="assign=group=${GRP_NAME} assign=init=_init $eopt"
eopt="$eopt autogen=${AG} base-name=expr"
getdefs $eopt <<source-file-list>>

Note, however, that your functions must be named:

whateveryoulike_scm_<<function_name>>(...)

so you may wish to use a shorter group name.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.9 skip-suffix option (-s)

This is the "omit the file with this suffix" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.
  • may not be preset with environment variables or in initialization (rc) files.

Occasionally, it may not be desirable to produce all of the output files specified in the template. (For example, only the `.h' header file, but not the `.c' program text.) To do this specify --skip-suffix=c on the command line.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.10 select-suffix option (-o)

This is the "specify this output suffix" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.
  • may not be preset with environment variables or in initialization (rc) files.

If you wish to override the suffix specifications in the template, you can use one or more copies of this option. See the suffix specification in the 3.1 Format of the Pseudo Macro section of the info doc.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.11 source-time option

This is the "set mod times to latest source" option. If you stamp your output files with the `DNE' macro output, then your output files will always be different, even if the content has not really changed. If you use this option, then the modification time of the output files will change only if the input files change. This will help reduce unneeded builds.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.12 equate option

This is the "characters considered equivalent" option. This option will alter the list of characters considered equivalent. The default are the three characters, "_-^". (The latter is conventional on a Tandem, and I do a lot of work on the Tandem.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.13 writable option

This is the "allow output files to be writable" option.

This option has some usage constraints. It:

  • may not be preset with environment variables or in initialization (rc) files.

This option will leave output files writable.Normally, output files are read-only.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.14 loop-limit option

This is the "limit on increment loops" option. This option prevents runaway loops. For example, if you accidentally specify, "FOR x (for-from 1) (for-to -1) (for-by 1)", it will take a long time to finish. If you do have more than 256 entries in tables, you will need to specify a new limit with this option.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.15 timeout option (-t)

This is the "time limit for servers" option.

This option has some usage constraints. It:

  • must be compiled in by defining SHELL_ENABLED during the compilation.

AutoGen works with a shell server process. Most normal commands will complete in less than 10 seconds. If, however, your commands need more time than this, use this option.

The valid range is 0 to 3600 seconds (1 hour). Zero will disable the server time limit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.16 trace option

This is the "tracing level of detail" option. This option will cause AutoGen to display a trace of its template processing. There are five levels:

`nothing'
Does no tracing at all (default)

`templates'
Traces the invocation of DEFINEd macros and INCLUDEs

`block-macros'
Traces all block macros. The above, plus IF, FOR, CASE and WHILE.

`expressions'
Displays the results of expression evaluations

`everything'
Displays the invocation of every AutoGen macro, even TEXT macros.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.17 trace-out option

This is the "tracing output file or filter" option. The output specified may be either a file name, or, if the option argument begins with the pipe operator (|), a command that will receive the tracing output as standard in. For example, --traceout='| less' will run the trace output through the less program.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.18 show-defs option

This is the "show the definition tree" option.

This option has some usage constraints. It:

  • must be compiled in by defining DEBUG during the compilation.
  • may not be preset with environment variables or in initialization (rc) files.

This will print out the complete definition tree before processing the template.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.19 show-shell option

This is the "show shell commands" option.

This option has some usage constraints. It:

  • must be compiled in by defining DEBUG during the compilation.
  • may not be preset with environment variables or in initialization (rc) files.

This will cause set -x to be executed in the shell, with the resultant output printed to /dev/tty. This option will have no effect if `--disable-shell' was specified at configure time.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.20 define option (-D)

This is the "name to add to definition list" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.
  • is a member of the define class of options.

The AutoGen define names are used for the following purposes:

  1. Sections of the AutoGen definitions may be enabled or disabled by using C-style #ifdef and #ifndef directives.
  2. When defining a value for a name, you may specify the index for a particular value. That index may be a literal value, a define option or a value #define-d in the definitions themselves.
  3. The name of a file may be prefixed with $NAME. That part of the name string will be replaced with the define-d value for NAME.
  4. While processing a template, you may specify an index to retrieve a specific value. That index may also be a define-d value.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.21 undefine option (-U)

This is the "definition list removal pattern" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.
  • may not be preset with environment variables or in initialization (rc) files.
  • is a member of the define class of options.

Just like 'C', AutoGen uses #ifdef/#ifndef preprocessing directives. This option will cause the matching names to be removed from the list of defined values.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Configuring and Installing

6.1 Configuring AutoGen
6.2 AutoGen as a CGI server
6.3 Signal Names
6.4 Installing AutoGen

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1 Configuring AutoGen

AutoGen is configured and built using Libtool, Automake and Autoconf. Consequently, you can install it whereever you wish using the various `--prefix' options. To the various configuration options supplied by these tools, AutoGen adds a few of its own:

`--disable-shell'
AutoGen is now capable of acting as a CGI forms server, See section 6.2 AutoGen as a CGI server. As such, it will gather its definitions using either `GET' or `POST' methods. All you need to do is have a template named `cgi.tpl' handy or specify a different one with a command line option.

However, doing this without disabling the server shell brings considerable risk. If you were to pass user input to a script that contained, say, the classic "``rm -rf /`'", you might have a problem. This configuration option will cause shell template commands to simply return the command string as the result. No mistakes. Much safer. Strongly recommended. The default is to have server shell scripting enabled.

Disabling the shell will have some build side effects, too.

  • Many of the make check tests will fail, since they assume a working server shell.
  • The getdefs and columns programs are not built. The options are distributed as definition files and they cannot be expanded with a shell-disabled AutoGen.
  • Similarly, the documentation cannot be regenerated because the documentation templates depend on subshell functionality.

`--enable-debug'
Turning on AutoGen debugging enables very detailed inspection of the input definitions and monitoring shell script processing. These options are not particularly useful to anyone not directly involved in maintaining AutoGen. If you do choose to enable AutoGen debugging, be aware that the usage page was generated without these options, so when the build process reaches the documentation rebuild, there will be a failure. `cd' into the `agen5' build directory, `make' the `autogen.texi' file and all will be well thereafter.

`--with-regex-header'
`--with-header-path'
`--with-regex-lib'
These three work together to specify how to compile with and link to a particular POSIX regular expression library. The value for `--with-regex-header=value' must be the name of the relevant header file. The AutoGen sources will attempt to include that source with a #include <value> C preprocessing statement. The path from the `--with-header-path=path' will be added to CPPFLAGS as `-Ipath'. The lib-specs from `--with-regex-lib=lib-specs' will be added to LDFLAGS without any adornment.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.2 AutoGen as a CGI server

AutoGen is now capable of acting as a CGI forms server. It behaves as a CGI server if the definitions input is from stdin and the environment variable REQUEST_METHOD is defined and set to either "GET" or "POST". If set to anything else, AutoGen will exit with a failure message. When set to one of those values, the CGI data will be converted to AutoGen definitions (see section 2. AutoGen Definitions File) and the template named "cgi.tpl" will be processed.

This works by including the name of the real template to process in the form data and having the "cgi.tpl" template include that template for processing. I do this for processing the form http://autogen.sourceforge.net/conftest.html. The "cgi.tpl" looks approximately like this:

<? AutoGen5 Template ?>
<?
IF (not (exist? "template"))                       ?><?
  form-error                                       ?><?

ELIF (=* (get "template") "/")                     ?><?
  form-error                                       ?><?

ELIF (define tpl-file (string-append "cgi-tpl/"
                      (get "template")))
     (access? tpl-file R_OK)                       ?><?
  INCLUDE (. tpl-file)                             ?><?

ELIF (set! tpl-file (string-append tpl-file ".tpl"))
     (access? tpl-file R_OK)                       ?><?
  INCLUDE (. tpl-file)                             ?><?

ELSE                                               ?><?
  form-error                                       ?><?
ENDIF                                              ?>

This forces the template to be found in the "cgi-tpl/" directory. Note also that there is no suffix specified in the pseudo macro (see section 3.1 Format of the Pseudo Macro). That tells AutoGen to emit the output to stdout.

The output is actually spooled until it is complete so that, in the case of an error, the output can be discarded and a proper error message can be written in its stead.

Please also note that it is advisable, especially for network accessible machines, to configure AutoGen (see section 6.1 Configuring AutoGen) with shell processing disabled (--disable-shell). That will make it impossible for any referenced template to hand data to a subshell for interpretation.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3 Signal Names

When AutoGen is first built, it tries to use psignal(3), sys_siglist, strsigno(3) and strsignal(3) from the host operating system. If your system does not supply these, the AutoGen distribution will. However, it will use the distributed mapping and this mapping is unlikely to match what your system uses. This can be fixed. Once you have installed autogen, the mapping can be rebuilt on the host operating system. To do so, you must perform the following steps:

  1. Build and install AutoGen in a place where it will be found in your search path.

  2. cd ${top_srcdir}/compat

  3. autogen strsignal.def

  4. Verify the results by examining the `strsignal.h' file produced.

  5. Re-build and re-install AutoGen.

If you have any problems or peculiarities that cause this process to fail on your platform, please send me copies of the header files containing the signal names and numbers, along with the full path names of these files. I will endeavor to fix it. There is a shell script inside of `strsignal.def' that tries to hunt down the information.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4 Installing AutoGen

There are several files that get installed. The number depend whether or not both shared and archive libraries are to be installed. The following assumes that everything is installed relative to $prefix. You can, of course, use configure to place these files where you wish.

NB AutoGen does not contain any compiled-in path names. All support directories are located via option processing, the environment variable HOME or finding the directory where the executable came from.

The installed files are:

  1. The executables in `bin' (autogen, getdefs and columns).

  2. The AutoOpts link libraries as `lib/libopts.*'.

  3. An include file in `include/options.h', needed for Automated Option Processing (see next chapter).

  4. Several template files and a scheme script in `share/autogen', needed for Automated Option Processing (see section 7. Automated Option Processing), parsing definitions written with scheme syntax (see section 2.4 Dynamic Text), the templates for producing documentation for your program (see section 7.4.3 Man and Info doc Attributes), autoconf test macros, and AutoFSM.

  5. Info-style help files as `info/autogen.info*'. These files document AutoGen, the option processing library AutoOpts, and several add-on components.

  6. The three man pages for the three executables are installed in man/man1.

This program, library and supporting files can be installed with three commands:

  • <src-dir>/configure [ <configure-options> ]
  • make
  • make install

However, you may wish to insert make check before the make install command.

If you do perform a make check and there are any failures, you will find the results in <module>/test/FAILURES. Needless to say, I would be interested in seeing the contents of those files and any associated messages. If you choose to go on and analyze one of these failures, you will need to invoke the test scripts individually. You may do so by specifying the test (or list of test) in the TESTS make variable, thus:

gmake TESTS=test-name.test check

I specify gmake because most makes will not let you override internal definitions with command line arguments. gmake does.

All of the AutoGen tests are written to honor the contents of the VERBOSE environment variable. Normally, any commentary generated during a test run is discarded unless the VERBOSE environment variable is set. So, to see what is happening during the test, you might invoke the following with bash or ksh:

VERBOSE=1 gmake TESTS="for.test forcomma.test" check

Or equivalently with csh:

env VERBOSE=1 gmake TESTS="for.test forcomma.test" check

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. Automated Option Processing

AutoOpts 14.0 is bundled with AutoGen. It is a tool that virtually eliminates the hassle of processing options and keeping man pages, info docs and usage text up to date. This package allows you to specify several program attributes, up to a hundred option types and many option attributes. From this, it then produces all the code necessary to parse and handle the command line and initialization file options, and the documentation that should go with your program as well.

AutoOpts is distributed under The GNU General Public License with the Library extentions (LGPL). It is in no way a "lesser" license. You have greater license with it.

7.1 AutoOpts Features
7.2 Competitive Feature Analysis
7.3 Quick Start
7.4 Option Definitions
7.5 Programmatic Interface
7.6 Option Descriptor File
7.7 Using AutoOpts
7.8 AutoOpts for Shell Scripts
7.9 Automated Info Docs
7.10 Automated Man Pages

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1 AutoOpts Features

AutoOpts supports option processing; option state saving; and program documentation with innumerable features. Here, we list a few obvious ones and some important ones, but the full list is really defined by all the attributes defined in the 7.4 Option Definitions section.

  1. POSIX-compliant short (flag) option processing.

  2. GNU-style long options processing. Long options are recognized without case sensitivity, and they may be abbreviated.

  3. Environment variable initializations.

  4. Initialization from RC or INI files, and saving the option state back into one.

  5. Options may be marked as dis-abled with a disablement prefix. Such options may default to either an enabled or a disabled state. You may also provide an enablement prifix, too, e.g., --allow-mumble and --prevent-mumble.

  6. Verify that required options are present between the minimum and maximum number of times on the command line.

  7. Verify that conflicting options do not appear together, and that options that require the presence of other options are, in fact, used in the presence of other options.

  8. Provides a callable routine to parse a text string as if it were from one of the RC/INI files.

  9. --help and --version are automatically supported. --more-help will page the generated help.

  10. By adding a `doc' and `arg-name' attributes to each option, AutoGen will also be able to produce a man page and the `invoking' section of a texinfo document.

  11. Insert the option processing state into Scheme-defined variables. Thus, Guile based applications that are linked with private main() routines can take advantage of all of AutoOpts' functionality.

  12. If test-main is defined, the output `.c' file will contain a main routine that will be compiled when TEST_<prog-name>_OPTS is defined. See section 7.8 AutoOpts for Shell Scripts. If you choose to compile this program, it is currently capable of producing one of three results:

    1. A program that processes the arguments and writes to standard out portable shell commands containing the digested options.

    2. A program that will generate portable shell commands to parse the defined options. The expectation is that this result will be copied into a shell script and used there.

    3. test-main may specify a routine that will be called with a pointer to the option descriptions as the single argument. You must supply this routine and, obviously, you can cause it to do whatever you wish it to do.

  13. Library suppliers can specify command line options that their client programs will accept. They specify option definitions that get #include-d into the client option definitions and they specify an "anchor" option that has a callback and must be invoked. That will give the library access to the option state for their options.

Explanatory details:

loading rc files
saving rc files
process a text string for options

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

loading rc files

Initialization files are enabled by specifying the program attribute homerc (see section 7.4.1 Program Description Attributes). The initialization values are identified by the long option name followed by white space and any associated value. The value, if any, will continue through the end of the last line not continued with a backslash. Leading and trailing white space is stripped.

Initialization files are selected both by the homerc entries and, optionally, via an automatically supplied command line option. The first component of the homerc entry may be an environment variable such as $HOME, or it may also be $$ (two dollar sign characters) to specify the directory of the executable. For example:

homerc = "$$/../share/autogen";

will cause the AutoOpts library to look in the normal autogen datadir for an initialization file.

The initialization files are processed in the order they are specified by the homerc attribute, so that each new file will normally override the settings of the previous files. A few options may be marked for immediate action (see section 7.4.2.4 Immediate Action Attributes). Any such options are acted upon in reverse order. The disabled load-opts (--no-load-opts) option, for example, is an immediate action option. Its presence in the last homerc file will prevent the processing of any prior homerc files.

Further initialization file processing can be suppressed by specifying --no-load-opts on the command line, or PROGRAM_LOAD_OPTS=no in the environment, or no-load-opts in any of the specified homerc files.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

saving rc files

When initialization files are enabled for an application, the user is also provided with an automatically supplied --save-opts option. All of the known option state will be written to either the specified output file or, if it is not specified, then to the last specified homerc file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

process a text string for options

The optionLoadLine takes two arguments:

  1. The pointer to the option descriptor.
  2. A pointer to a NUL-terminated string that contains a long option name followed, optionally, by a string value.

Leading and trailing white space is trimmed from the value, but otherwise new lines are not discarded. The caller is expected to have NUL terminated the string at the correct point.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2 Competitive Feature Analysis

Here is a feature comparison of AutoOpts and six other command line parser generators. Nearly all of them share these characteristics:

  • They read a file that describes the program options and produce code to parse command line options. Each has their own format for describing options.
  • All versions support both short options (flags) and GNU-type long options. clig, however, is unique in that you must choose one or the other. Either way, clig options are introduced with a single hyphen. The other packages identify long options with doubled hyphens.
  • They produce tailored code for parsing the command line.
  • They support the C programming language.
  • The global option state is stored in a global structure.
  • They produce usage text.

The 7 parsers compared are:

  1. AutoOpts is a component of AutoGen. AutoGen has many capabilities, but here we concentrate on the portion called AutoOpts. AutoOpts is the most general of these programs, and has the most extensive documentation. It is the only one that supports shell and Scheme scripts as well as C programs.

  2. clig can generate either C or Tcl option parsing code. It can also process multiple arguments per single option.

  3. genparse generates a wrapper around getopts_long() to parse the command line options.

  4. gaa supports option input from a configuration file as well as the command line. NOTE HOWEVER: gaa is not maintained.

  5. gengetopt generates a C function that uses getopt_long function to parse the command line options, to validate them and fills a struct.

  6. opt is a subroutine library. Options are specified by calling a registration routine in the library, instead of using a separate option specification file. Global option state is stored in variables passed by address to the registration routine.

  7. wyg uses flex and bison to generate a configuration file parser, but uses getopt_long to parse the command line options.
Comparative Analysis of Differentiating Features

If a feature is present (or absent) in only one or two implementations, then the "yes" or "no" is upper cased for emphasis.

Feature \ Package # | 1 | 2 | 3 | 4 | 5 | 6 | 7
shell script app | YES | no | no | no | no | no | no
Scheme app | YES | no | no | no | no | no | no
Perl app | no | no | no | no | no | YES | no
config file input | yes | no | no | yes | no | yes | yes
environment input | YES | no | no | no | no | YES | no
config file output | YES | no | no | no | no | no | no
callback functions | yes | NO | yes | yes | yes | yes | NO
multiple occurrence | YES | YES | no | no | no | no | no
parameter types | [1] | 4 | 5 | 5 | 11 | [3] | 4
enumeration opts | YES | no | no | no | no | no | no
optional argument | YES | YES | no | no | no | no | no
default values | yes | yes | yes | yes | NO | yes | yes
interactive | no | no | no | no | no | YES | no
range checks | yes | yes | yes | no | no | no | no
consistency checks | YES | no | no | no | no | no | no
standard opts | YES | no | no | no | no | no | no
man page | YES | YES | no | no | no | no | no
texinfo invoking | YES | no | no | no | no | no | no
developer dependencies | Guile | tcl | none | none | none | none | bison,flex
user dependencies | [2] | none | none | none | none | none | none

"multiple occurrence" options may appear multiple times on the command line. Some of the parsers constrain options to appearing once only.

"optional argument" refers to the argument to an option. POSIX and most command line parsers require an option to either not have an argument or else the argument must be supplied on the command line. GNU's getopt_long and some of these parsers support the notion of letting the option argument be "optional".

"consistency checks" verify that conflicting options do not appear together, and options that require other options are allowed only if those other options are present.

"standard options" are pre-defined options that can be trivially incorporated into a user's set of options. They can also thereby be used for standardizing on the flag character and option name.

"interactive" means that the option processing package is able to interactively query the user for option state.

[1] See the list of features, 7.4.2.6 Option Argument Specification.

[2] There is a user-visible dependency iff the developer does a dynamic link to the libopts.so library. Developers are free to either link statically or ship libopts.so with their product. A Debian package would need only a dependency on the package supplying libopts (libopts11, at present). The Guile library is now generally pre-installed on all GNU/Linux systems.

[3] opt supports a different argument type for each fundamental type, plus booleans, inverted booleans, toggling options and a couple others.
-- James R. Van Zandt
-- Bruce Korb

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3 Quick Start

Since it is generally easier to start with a simple example than it is to look at the options that AutoGen uses itself, here is a very simple AutoOpts example. You can copy this example out of the Info file and into a source file to try it. You can then embellish it into what you really need. For more extensive examples, you can also examine the help output and option definitions for the commands columns, getdefs and autogen itself.

For our simple example, assume you have a program named check that takes two options:

  1. A list of directories to check over for whatever it is check does. You want this option available as a POSIX-style flag option and a GNU long option. You want to allow as many of these as the user wishes.
  2. An option to show or not show the definition tree being used. Only one occurrence is to be allowed, specifying one or the other.

First, specify your program attributes and its options to AutoOpts, as with the following example.

AutoGen Definitions options;
prog-name     = check;
prog-title    = "Checkout Automated Options";
long-opts;
test_main;

flag = {
    name      = check_dirs;
    value     = L;        /* flag style option character */
    arg_type  = string;   /* option argument indication  */
    max       = NOLIMIT;  /* occurrence limit (none)     */
    stack_arg;            /* save opt args in a stack    */
    descrip   = "Checkout directory list";
};

flag = {
    name      = show_defs;
    descrip   = "Show the definition tree";
    disable   = dont;     /* mark as enable/disable type */
                          /* option.  Disable as `dont-' */
};

Then perform the following steps:

  1. autogen -L $prefix/share/autogen checkopt.def
  2. cc -o check -DTEST_CHECK_OPTS -g checkopt.c -L $prefix/lib -lopts

And now, ./check --help yields:

check - Checkout Automated Options
USAGE:  check [-<flag> [<val>]]... [--<name>[{=| }<val>]]...
  Flg Arg Option-Name    Description
   -L YES check-dirs     Checkout directory list
                                - may appear without limit
      no  show-defs      Show the definition tree
                                - disabled as --dont-show-defs
   -? no  help           Display usage information and exit
   -! no  more-help      Extended usage information passed thru pager

Options may be specified by doubled markers and their name
or by a single marker and the flag character/option value.

Normally, however, you would compile `checkopt.c' as in:

cc -o checkopt.o -I$prefix/include -c checkopt.c

and link `checkopt.o' with the rest of your program. The main program causes the options to be processed by calling optionProcess:

main( int argc, char** argv )
{
  {
    int optct = optionProcess( &checkOptions, argc, argv );
    argc -= optct;
    argv += optct;
  }

The options are tested and used as in the following fragment:

  if (HAVE_OPT( SHOW_DEFS ) && HAVE_OPT( CHECK_DIRS )) {
    int    dirct = STACKCT_OPT( CHECK_DIRS );
    char** dirs  = STACKLST_OPT( CHECK_DIRS );
    while (dirct-- > 0) {
      char* dir = *dirs++;
      ...

A lot of magic happens to make this happen. The rest of this chapter will describe the myriad of option attributes supported by AutoOpts. However, keep in mind that, in general, you won't need much more than what was described in this "quick start" section.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4 Option Definitions

AutoOpts uses an AutoGen definitions file for the definitions of the program options and overall configuration attributes. The complete list of program and option attributes is quite extensive, so if you are reading to understand how to use AutoOpts, I recommend reading the "Quick Start" section (see section 7.3 Quick Start) and paying attention to the following:

  1. prog-name, prog-title, and argument, program attributes, See section 7.4.1 Program Description Attributes.
  2. name and descrip option attributes, See section 7.4.2.1 Required Attributes.
  3. value (flag character) and min (occurrence counts) option attributes, See section 7.4.2.2 Common Option Attributes.
  4. arg-type from the option argument specification section, See section 7.4.2.6 Option Argument Specification.
  5. Read the overall how to, See section 7.7 Using AutoOpts.
  6. Highly recommended, but not required, are the several "man" and "info" documentation attributes, See section 7.4.3 Man and Info doc Attributes.

Keep in mind that the majority are rarely used and can be safely ignored. However, when you have special option processing requirements, the flexibility is there.

7.4.1 Program Description Attributes
7.4.2 Option Attributes
7.4.3 Man and Info doc Attributes
7.4.4 Automatically Supported Options
7.4.5 Library of Standard Options

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.1 Program Description Attributes

The following global option definitions are used to define attributes of the entire program. The first two are required of every program. The rest have been alphabetized. Except as noted, there may be only one copy of each of these definitions:

`prog-name'
This attribute is required. Variable names derived from this name are derived using string->c_name! (see section 3.5.45 `string->c-name!' - map non-name chars to underscore).

`prog-title'
This attribute is required and may be any descriptive text.

`prog-desc and'
`opts-ptr'
These define global pointer variables that point to the program descriptor and the first option descriptor for a library option. This is intended for use by certain libraries that need command line and/or initialization file option processing. These definitions have no effect on the option template output, but are used for creating a library interface file. Normally, the first "option" for a library will be a documentation option that cannot be specified on the command line, but is marked as settable. The library client program will invoke the SET_OPTION macro which will invoke a handler function that will finally set these global variables.

`allow-errors'
The presence of this attribute indicates ignoring any command line option errors. This may also be turned on and off by invoking the macros ERRSKIP_OPTERR and ERRSTOP_OPTERR from the generated interface file.

`argument'
Specifies the syntax of the arguments that follow the options. It may not be empty, but if it is not supplied, then option processing must consume all the arguments. If it is supplied and starts with an open bracket ([), then there is no requirement on the presence or absence of command line argument following the options. Lastly, if it is supplied and does not start with an open bracket, then option processing must not consume all of the command line arguments.

`before-guile-boot'
If guile-main has been specified and if this is specified as well, then this code will be inserted into the actual main() procedure before gh_enter() is called.

`copyright'
The copyright is a structured value containing three to five values. If copyright is used, then the first three are required.

  1. `date' - the list of applicable dates for the copyright.
  2. `owner' - the name of the copyright holder.
  3. `type' - specifies the type of distribution license. AutoOpts/AutoGen will automatically support the text of the GNU Public License (`GPL'), the GNU General Public License with Library extensions (`LGPL'), the Free BSD license (`BSD'), and a write-it-yourself copyright notice (`NOTE'). Only these values are recognized.
  4. `text' - the text of the copyright notice. It is only needed if `type' is set to `NOTE'.
  5. `author' - in case the author name is to appear in the documentation and is different from the copyright owner.
  6. `eaddr' - email address of the author or copyright holder.

An example of this might be:
copyright = {
    date  = "1992-2001";
    owner = "Bruce Korb";
    eaddr = 'bkorb@gnu.org';
    type  = GPL;
};

`detail'
This string is added to the usage output when the HELP option is selected.

`environrc'
Indicates looking in the environment for values of variables named
PROGRAM_OPTNAME.
where PROGRAM is the upper cased C-name of the program and OPTNAME is the upper cased C-name of the option. The C-names are the regular names with all special characters converted to underscores (_).

If a particular option may be disabled, then its disabled state is indicated by setting the value to the disablement prefix. So, for example, if the disablement prefix were dont, then you can disable the optname option by setting the PROGRAM_OPTNAME environment variable to `dont'. See section 7.4.2.2 Common Option Attributes.

`explain'
Gives additional information whenever the usage routine is invoked..

`export'
This string is inserted into the .h interface file. Generally used for global variables or #include directives required by flag_code text and shared with other program text. Do not specify your configuration header (`config.h') in this attribute or the include attribute, however. Instead, use config-header, below.

`config-header'
The contents of this attribute should be just the name of the configuration file. A "#include" naming this file will be inserted at the top of the generated header.

`guile-main'
Creates a guile-style main and inner-main procedures. The inner main procedure will call optionProcess() and will invoke any code specified by this attribute. If this attribute does not specify any code, then calls to the AutoOpts library procedure export_options_to_guile() and then scm_shell() will be inserted into inner_main().

`homerc'
Specifies either a directory or a file using a specific path (like . or `/usr/local/share/progname') or an environment variable (like `$HOME/rc/' or `$PREFIX/share/progname') or the directory where the executable was found (`$$[/...]') to use to try to find the rcfile. Use as many as you like. The presence of this attribute activates the --save-opts and --load-opts options. See section loading rc files.

`include'
This string is inserted into the .c file. Generally used for global variables required only by flag_code program text.

`long-opts'
Presence indicates GNU-standard long option processing. If any options do not have an option value (flag character) specified, and least one does specify such a value, then you must specify long-opts. If none of your options specify an option value (flag character) and you do not specify long-opts, then command line arguments are processed in "named option mode". This means that:

  • Every command line argument must be a long option.
  • The flag markers - and -- are completely optional.
  • The argument program attribute is disallowed.
  • One of the options may be specified as the default (as long as it has a required option argument).

`prefix'
This value is inserted into all global names. This will disambiguate them if more than one set of options are to be compiled into a single program.

`rcfile'
Specifies the initialization file name. This is only useful if you have provided at least one homerc attribute. default: .<prog-name>rc

`preserve-case'
This attribute will not change anything except appearance. Normally, the option names are all documented in lower case. However, if you specify this attribute, then they will display in the case used in their specification. Command line options will still be matched without case sensitivity.

`rcsection'
If you have a collection of option descriptions that are intended to use the same RC/ini files, then you will likely want to partition that file. That will be possible by specifying this attribute with AutoOpts version 9.2 and later.

Every RC file will be considered partitioned by lines that commence with the square open bracket ([). All text before such a line is always processed. Once such a line is found, the upper-cased c-variable-syntax program name will be compared against the text following that bracket. If there is a match and the next character after that is a square close bracket (]), then the section is processed and the file closed. Otherwise, the section is ignored and a matching section is searched for.

For exampe, if the fumble-stumble options had a sectioned RC file, then a line containing [FUMBLE_STUMBLE] would be searched for.

`test-main'
Creates a test main procedure for testing option processing. The resulting program may also be used for several purposes.

  1. If the text of test-main is short (3 or fewer characters), the generated main() will call putBourneShell. That routine will emit Bourne shell commands that can be eval-ed by a Bourne-derived shell to incorporate the digested options into the shell's environment, See section 7.8 AutoOpts for Shell Scripts. You would use it thus:
    eval `./programopts $@`
if [ -z "${OPTION_CT}" ] ; then exit 1 ; fi
shift ${OPTION_CT}

  2. If the text of test-main contains putShellParse, the program will generate portable Bourne shell commands that will parse the command line options. The expectation is that this result will be copied into a shell script and used there, See section 7.8 AutoOpts for Shell Scripts.

  3. Any other text must be the name of a routine that you will write yourself. That routine will be called after processing the command line options and it will be passed the option processing descriptor pointer as its sole argument.

`usage'
Optionally names the usage procedure, if the library routine optionUsage() does not work for you. If you specify gnu_usage as the value of this attribute, for example, you will use a procedure by that name for displaying usage. Of course, you will need to provide that procedure.

`version'
Specifies the program version and activates the VERSION option.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2 Option Attributes

For each option you wish to specify, you must have a block macro named flag defined. It MUST contain at least two defined text values named name and descrip. If any options do not have a value macro, then the long-opts global text macro must be defined. As a special exception, if no options have a value and long-opts is not defined and argument is not defined, then all arguments to the program are named. In this case, the - and -- command line option markers are optional.

There are four categories of option attributes. The fifth section below describes what data are available for writing option processing code.

7.4.2.1 Required Attributes
7.4.2.2 Common Option Attributes
7.4.2.3 Special Option Handling
7.4.2.4 Immediate Action Attributes
7.4.2.5 Option Conflict Attributes
7.4.2.6 Option Argument Specification
7.4.2.7 Option Argument Handling

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2.1 Required Attributes

Every option must have exactly one copy of both of these attributes.

`name'
Long name for the option. Even if you are not accepting long options and are only accepting flags, it must be provided. AutoOpts generates private, named storage that require this name.

`descrip'
Except for documentation options, a very brief description of the option. About 40 characters on one line, maximum. It appears on the usage() output next to the option name. Documentation options appear on one or more lines by themselves, visually separating the usage options.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2.2 Common Option Attributes

These option attributes are optional. Any that do appear in the definition of a flag, may appear only once.

`value'
The flag character to specify for traditional option flags. e.g. -L.

`max'
Maximum occurrence count (invalid if disable present).

`min'
Minimum occurrence count. If present, then the option must appear on the command line. Preset values do not count towards the minimum occurrence count.

`must-set'
If an option must be specified, but it need not be specified on the command line, then specify this attribute for the option.

`enable'
Long-name prefix for enabling the option (invalid if disable not present). Only useful if long option names are being processed.

`disable'
Prefix for disabling (inverting sense of) the option. Only useful if long option names are being processed.

`enabled'
If default is for option being enabled. (Otherwise, the OPTST_DISABLED bit is set at compile time.) Only useful if the option can be disabled.

`ifdef'
`ifndef'
If an option is relevant on certain platforms or when certain features are enabled or disabled, you can specify the compile time flag used to indicate when the option should be compiled in or out. For example, if you have a configurable feature, mumble that is indicated with the compile time define, WITH_MUMBLING, then add:

ifdef = WITH_MUMBLING;

Note that case and spelling must match whatever you are using. Do not confuse these attributes with the AutoGen directives of the same names, See section 2.5 Controlling What Gets Processed. These cause C pre-processing directives to be inserted into the generated C text.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2.3 Special Option Handling

These option attributes do not fit well with other categories.

`no-preset'
If presetting this option is not allowed. (Thus, environment variables and values set in rc/ini files will be ignored.)

`settable'
If the option can be set outside of option processing. If this attribute is defined, special macros for setting this particular option will be inserted into the interface file. For example, TEMPL_DIRS is a settable option for AutoGen, so a macro named SET_OPT_TEMPL_DIRS(a) appears in the interface file. This attribute interacts with the documentation attribute.

`equivalence'
Generally, when several options are mutually exclusive and basically serve the purpose of selecting one of several processing modes, these options can be considered an equivalence class. Sometimes, it is just easier to deal with them as such.

For an option equivalence class, there is a single occurrence counter for all the members of the class. All members of the equivalence class must contain the same equivalenced-to option, including the equivalenced-to option itself. Thus, it must be a member.

As an example, cpio(1) has three options -o, -i, and -p that define the operational mode of the program (create, extract and pass-through, respectively). They form an equivalence class from which one and only one member must appear on the command line. If cpio were an AutoOpt-ed program, then each of these option definitions would contain:

equivalence = create;

and the program would be able to determine the operating mode with code that worked something like this:

switch (WHICH_IDX_CREATE) {
case INDEX_OPT_CREATE:       ...
case INDEX_OPT_EXTRACT:      ...
case INDEX_OPT_PASS_THROUGH: ...
default:    /* cannot happen */
}

`documentation'
This attribute means the option exists for the purpose of separating option description text in the usage output. Libraries may choose to make it settable so that the library can determine which command line option is the first one that pertains to the library.

If present, this option disables all other attributes except settable, call_proc and flag_code. settable must be and is only specified if call_proc or flag_code has been specified. When present, the descrip attribute will be displayed only when the --help option has been specified. It will be displayed flush to the left hand margin and may consist of one or more lines of text. The name of the option will not be printed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2.4 Immediate Action Attributes

Certain options may need to be processed early. For example, in order to suppress the processing of RC files, it is necessary to process the command line option --no-load-opts before the RC files are processed. To accommodate this, certain options may have their enabled or disabled forms marked for immediate processing. The consequence of this is that they are processed ahead of all other options in the reverse of normal order.

Normally, the first options processed are the options specified in the first homerc file, followed by then next homerc file through to the end of RC file processing. Next, environment variables are processed and finally, the command line options. The later options override settings processed earlier. That actually gives them higher priority. Command line immediate action options actually have the lowest priority of all. They would be used only if they are to have an effect on the processing of subsequent options.

`immediate'
Use this option attribute to specify that the enabled form of the option is to be processed immediately. The help and more-help options are so specified. They will also call exit() upon completion, so they do have an effect on the processing of the remaining options :-).

`immed-disable'
Use this option attribute to specify that the disabled form of the option is to be processed immediately. The load-opts option is so specified. The --no-load-opts command line option will suppress the processing of RC files and environment variables. Contrariwise, the --load-opts command line option is processed normally. That means that the options specified in that file will be processed after all the homerc files and, in fact, after options that precede it on the command line.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2.5 Option Conflict Attributes

These attributes may be used as many times as you need. They are used at the end of the option processing to verify that the context within which each option is found does not conflict with the presence or absence of other options.

This is not a complete cover of all possible conflicts and requirements, but it simple to implement and covers the more common situations.

`flags-must'
one entry for every option that must be present when this option is present

`flags-cant'
one entry for every option that cannot be present when this option is present

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2.6 Option Argument Specification

Several attributes relate to the handling of arguments to options. Each may appear only once, except for the arg-range attribute. It may appear as often as may be needed.

`arg-type'
This specifies the type of argument the option will take. If not present, the option cannot take an argument. If present, it must be one of the following four. The bracketed part of the name is optional.

`str[ing]'
The argument may be any arbitrary string.

`num[ber]'
The argument must be a correctly formed integer, without any trailing U's or L's. If you specify your own callback validation routine, read the arg-range section below for some considerations. AutoOpts contains a library procedure to convert the string to a number. If you specify range checking with arg-range, then AutoOpts produces a special purpose procedure for this option.

`bool[ean]'
The argument will be interpreted and always yield either AG_TRUE or AG_FALSE. False values are the empty string, the number zero, or a string that starts with f, F, n or N (representing False or No). Anything else will be interpreted as True.

`key[word]'
The argument must match a specified list of strings. Assuming you have named the option, optn-name, the strings will be converted into an enumeration of type te_Optn_Name with the values OPTN_NAME_KEYWORD. If you have not specified a default value, the value OPTN_NAME_UNDEFINED will be inserted with the value zero. The option will be initialized to that value. You may now use this in your code as follows:

te_Optn_Name opt = OPT_VALUE_OPTN_NAME;
switch (opt) {
case OPTN_NAME_UNDEFINED:  /* undefined things */ break;
case OPTN_NAME_KEYWORD:    /* `keyword' things */ break;
default: /* utterly impossible */ ;
}

AutoOpts produces a special purpose procedure for this option.

`keyword'
If the arg-type is keyword, then you must specify the list of keywords by a series of keyword entries. The interface file will contain an enumeration of <OPTN_NAME>_<KEYWORD> for each keyword entry.

`arg-optional'
This attribute indicates that the user does not have to supply an argument for the option. This is only valid if the arg-type is string or keyword. If it is keyword, then this attribute may also specify the default keyword to assume when the argument is not supplied. Without such a specification, the default keyword will be the zero-valued keyword.

`arg-default'
This specifies the default value to be used when the option is not specified or preset.

`default'
If your program processes its arguments in named option mode (See "long-opts" in 7.4.1 Program Description Attributes), then you may select one of your options to be the default option. Do so with this attribute. The option so specified must have an arg-type specified, but not the arg-optional attribute. That is to say, the option argument must be required.

If you have done this, then any arguments that do not match an option name and do not contain an equal sign (=) will be interpreted as an option argument to the default option.

`arg-range'
If the arg-type is number, then arg-ranges may be specified, too. If you specify one or more of these option attributes, then AutoOpts will create a callback procedure for handling it. The argument value supplied for the option must match one of the range entries. Each arg-range should consist of either an integer by itself or an integer range. The integer range is specified by one or two integers separated by the two character sequence, ->.

The generated procedure imposes some constraints:

  • A number by itself will match that one value.
  • The high end of the range may not be INT_MIN, both for obvious reasons and because that value is used to indicate a single-valued match.
  • An omitted lower value implies a lower bound of INT_MIN.
  • An omitted upper value implies a upper bound of INT_MAX.
  • The argument value is required. It may not be optional.

The usage procedure displays these ranges by calling the callback with the pOptDesc pointer set to NULL. Therefore, all callback procedures designed to handle options with numeric arguments must be prepared to handle a call with that pointer set NULL.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2.7 Option Argument Handling

AutoOpts will automatically generate a callback procedure for options with enumerated keyword arguments and numeric arguments with range checking. If you have specified such an option, you may not specify any of the attributes listed here.

Otherwise, you may pick zero or one of the following attributes. The first two attributes interact with the documentation and settable attributes, See section 7.4.2.3 Special Option Handling.

`flag-code'
statements to execute when the option is encountered. The generated procedure will look like this:

static void
doOpt<name>( tOptions* pOptions, tOptDesc* pOptDesc )
{
<flag_code>
}

Only certain fields within the tOptions and tOptDesc structures may be accessed. See section 7.5.1 Data for Option Processing.

`extract-code'
This is effectively identical to flag_code, except that the source is kept in the output file instead of the definitions file. A long comment is used to demarcate the code. You must not modify that marker. Before regenerating the option code file, the old file is renamed from MUMBLE.c to MUMBLE.c.save. The template will be looking there for the text to copy into the new output file.

`call-proc'
external procedure to call when option is encountered. The calling sequence must conform to the sequence defined above for the generated procedure, doOpt<name>. It has the same restrictions regarding the fields within the structures passed in as arguments. See section 7.5.1 Data for Option Processing.

`flag-proc'
Name of another option whose flag_code can be executed when this option is encountered.

`stack-arg'
Call a special library routine to stack the option's arguments. Special macros in the interface file are provided for determining how many of the options were found (STACKCT_OPT(NAME)) and to obtain a pointer to a list of pointers to the argument values (STACKLST_OPT(NAME)).

If two options are equivalenced (see section 7.4.2.3 Special Option Handling) and specify this attribute, then the "equivalenced-to" option will add entries to the stack, and the "equivalencing" option, if specified, will remove entries that match the regular expression argument. The pattern, ".*" will efficiently remove all the entries in the stack. It would not be useful to have more than two options in this equivalence class.

If the stacked option has a disablement prefix, then the entire stack of arguments will be cleared even more efficiently than the ".*" regular expression. A stacked, equivalencing option with a disablement prefix will cause undefined results.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.3 Man and Info doc Attributes

AutoOpts includes AutoGen templates for producing abbreviated man pages and for producing the invoking section of an info document. To take advantage of these templates, you must add several attributes to your option definitions.

`doc'
First, every flag definition must have a doc attribute defined and many will need an arg-name attribute as well. The doc text should be in plain sentences with minimal formatting. The Texinfo commands @code, and @var will have its enclosed text made into \fB entries in the man page, and the @file text will be made into \fI entries. The arg-name attribute is used to display the option's argument in the man page.

`arg-name'
If an option has an argument, the argument should have a name for documentation purposes. It will default to arg-type, but it will likely be clearer with something else like, file-name instead of string (the type).

`prog-man-descrip'
`prog-info-descrip'
Then, you need to supply a brief description of what your program does. If you already have a detail definition, this may be sufficient. If not, or if you need special formatting for one of the manual formats, then you will need either a definition for prog-man-descrip or prog-info-descrip or both. These will be inserted verbatim in the man page document and the info document, respectively.

`man-doc'
Finally, if you need to add man page sections like SEE ALSO or USAGE or other, put that text in a man-doc definition. This text will be inserted verbatim in the man page after the OPTIONS section and before the AUTHOR section.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.4 Automatically Supported Options

AutoOpts provides automated support for five options. help and more-help are always provided. version is provided if version is defined in the option definitions. save-opts and load-opts are provided if at least one homerc is defined.

Below are the option names and flag values. The flags are activated if and only if at least one user-defined option also uses a flag value. These flags may be deleted or changed to characters of your choosing by specifying xxx-value = "y";, where xxx is one of the five names below and y is either empty or the character of your choice. For example, to change the help flag from ? to h, specify help-value = "h";; and to require that save-opts be specified only with its long option name, specify save-opts-value = "";.

`help -?'
This option will immediately invoke the USAGE() procedure and display the usage line, a description of each option with its description and option usage information. This is followed by the contents of the definition of the detail text macro.

`more-help -!'
This option is identical to the help option, except that it also includes the contents of the detail-file file (if provided and found), plus the output is passed through a pager program. (more by default, or the program identified by the PAGER environment variable.)

`version -v'
This will print the program name, title and version. If it is followed by the letter c and a value for copyright and owner have been provided, then the copyright will be printed, too. If it is followed by the letter n, then the full copyright notice (if available) will be printed.

`save-opts ->'
This option will cause the option state to be printed in RC/INI file format when option processing is done but not yet verified for consistency. The program will terminate successfully without running when this has completed. Note that for most shells you will have to quote or escape the flag character to restrict special meanings to the shell.

The output file will be the RC/INI file name (default or provided by rcfile) in the last directory named in a homerc definition.

This option may be set from within your program by invoking the "SET_OPT_SAVE_OPTS(filename)" macro (see section 7.5.16 SET_OPT_name - Force an option to be set). Invoking this macro will set the file name for saving the option processing state, but the state will not actually be saved. You must call optionSaveFile to do that (see section 7.5.28.5 optionSaveFile). CAVEAT: if, after invoking this macro, you call optionProcess, the option processing state will be saved to this file and optionProcess will not return. You may wish to invoke CLEAR_OPT( SAVE_OPTS ) (see section 7.5.2 CLEAR_OPT( <NAME> ) - Clear Option Markings) beforehand.

`load-opts -<'
This option will load options from the named file. They will be treated exactly as if they were loaded from the normally found RC/INI files, but will not be loaded until the option is actually processed. This can also be used within an RC/INI file causing them to nest.

It is ultimately intended that specifying the option, no-load-opts will suppress the processing of rc/ini files and environment variables. To do this, AutoOpts must first implement pre-scanning of the options, environment and rc files.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.5 Library of Standard Options

AutoOpts has developed a set of standardized options. You may incorporate these options in your program simply by adding a #define for the options you want, and the line,

#include stdoptions.def

in your option definitions. The supported options are specified thus:

#define DEBUG
#define DIRECTORY
#define DRY_RUN
#define INPUT
#define INTERACTIVE
#define OUTPUT
#define WARN

#define SILENT
#define QUIET
#define BRIEF
#define VERBOSE

By default, only the long form of the option will be available. To specify the short (flag) form, suffix these names with _FLAG. e.g.,

#define DEBUG_FLAG

--silent, --quiet, --brief and --verbose are related in that they all indicate some level of diagnostic output. These options are all designed to conflict with each other. Instead of four different options, however, several levels can be incorporated by #define-ing VERBOSE_ENUM. In conjunction with VERBOSE, it incorporates the notion of 5 levels in an enumeration: silent, quiet, brief, informative and verbose; with the default being brief.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5 Programmatic Interface

The user interface for access to the argument information is completely defined in the generated header file and in the portions of the distributed file "options.h" that are marked "public".

In the following macros, text marked <NAME> or name is the name of the option in upper case and segmented with underscores _. The macros and enumerations defined in the options header (interface) file are used as follows:

To see how these #define macros are used in a program, the reader is referred to the several `opts.h' files included with the AutoGen sources.

7.5.1 Data for Option Processing
7.5.2 CLEAR_OPT( <NAME> ) - Clear Option Markings
7.5.3 COUNT_OPT( <NAME> ) - Definition Count
7.5.4 DESC( <NAME> ) - Option Descriptor
7.5.5 DISABLE_OPT_name - Disable an option
7.5.6 ENABLED( <NAME> ) - Is Option Enabled?
7.5.7 ERRSKIP_OPTERR - Ignore Option Errors
7.5.8 ERRSTOP_OPTERR - Stop on Errors
7.5.9 HAVE_OPT( <NAME> ) - Have this option?
7.5.10 ISSEL_OPT( <NAME> ) - Is Option Selected?
7.5.11 ISUNUSED_OPT( <NAME> ) - Never Specified?
7.5.12 OPTION_CT - Full Count of Options
7.5.13 OPT_ARG( <NAME> ) - Option Argument String
7.5.14 OPT_VALUE_name - Option Argument Value
7.5.15 RESTART_OPT( n ) - Resume Option Processing
7.5.16 SET_OPT_name - Force an option to be set
7.5.17 STACKCT_OPT( <NAME> ) - Stacked Arg Count
7.5.18 STACKLST_OPT( <NAME> ) - Argument Stack
7.5.19 START_OPT - Restart Option Processing
7.5.20 STATE_OPT( <NAME> ) - Option State
7.5.21 USAGE( exit-code ) - Usage invocation macro
7.5.22 VALUE_OPT_name - Option Flag Value
7.5.23 VERSION - Version and Full Version
7.5.24 WHICH_IDX_name - Which Equivalenced Index
7.5.25 WHICH_OPT_name - Which Equivalenced Option
7.5.26 teOptIndex - Option Index and Enumeration
7.5.27 OPTIONS_STRUCT_VERSION - active version
7.5.28 libopts External Procedures

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.1 Data for Option Processing

This section describes the data that may be accessed from within the option processing callback routines. The following fields may be used in the following ways and may be used for read only. The first set is addressed from the tOptDesc* pointer:

`optIndex'
`optValue'
These may be used by option procedures to determine which option they are working on (in case they handle several options).

`optActualIndex'
`optActualValue'
These may be used by option procedures to determine which option was used to set the current option. This may be different from the above if the options are members of an equivalence class.

`optOccCt'
If AutoOpts is processing command line arguments, then this value will contain the current occurrence count. During the option preset phase (reading rc/ini files and examining environment variables), the value is zero.

`fOptState'
The field may be tested for the following bit values (prefix each name with OPTST_, e.g. OPTST_INIT):

`INIT'
Initial compiled value. As a bit test, it will always yield FALSE.

`SET'
The option was set via the SET_OPT() macro.

`PRESET'
The option was set via an RC/INI file, or a call to the optionLoadLine() routine.

`DEFINED'
The option was set via a command line option.

`SET_MASK'
This is a mask of flags that show the set state, one of the above four values.

`EQUIVALENCE'
This bit is set when the option was selected by an equivalenced option.

`DISABLED'
This bit is set if the option is to be disabled. (Meaning it was a long option prefixed by the disablement prefix, or the option has not been specified yet and initializes as disabled.)

As an example of how this might be used, in AutoGen I want to allow template writers to specify that the template output can be left in a writable or read-only state. To support this, there is a Guile function named set-writable (see section 3.4.31 `set-writable' - Make the output file be writable). Also, I provide for command options --writable and --not-writable. I give precedence to command line and RC file options, thus:

switch (STATE_OPT( WRITABLE )) {
case OPTST_DEFINED:
case OPTST_PRESET:
    fprintf( stderr, zOverrideWarn, pCurTemplate->pzFileName,
             pCurMacro->lineNo );
    break;

default:
    if (gh_boolean_p( set ) && (set == SCM_BOOL_F))
        CLEAR_OPT( WRITABLE );
    else
        SET_OPT_WRITABLE;
}

`pzLastArg'
Pointer to the latest argument string. BEWARE If the argument type is numeric or an enumeration, then this will be the argument value and not a pointer to a string.

The following two fields are addressed from the tOptions* pointer:

`pzProgName'
Points to a NUL-terminated string containing the current program name, as retrieved from the argument vector.

`pzProgPath'
Points to a NUL-terminated string containing the full path of the current program, as retrieved from the argument vector. (If available on your system.)

Note these fields get filled in during the first call to optionProcess(). All other fields are private, for the exclusive use of AutoOpts code and is subject to change.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.2 CLEAR_OPT( <NAME> ) - Clear Option Markings

Make as if the option had never been specified. HAVE_OPT(<NAME>) will yield FALSE after invoking this macro.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.3 COUNT_OPT( <NAME> ) - Definition Count

This macro will tell you how many times the option was specified on the command line. It does not include counts of preset options.

if (COUNT_OPT( NAME ) != desired-count) {
    make-an-undesirable-message.
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.4 DESC( <NAME> ) - Option Descriptor

This macro is used internally by other AutoOpt macros. It is not for general use. It is used to obtain the option description corresponding to its UPPER CASED option name argument. This is primarily used in other macro definitions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.5 DISABLE_OPT_name - Disable an option

This macro is emitted if it is both settable and it can be disabled. If it cannot be disabled, it may always be CLEAR-ed (see above).

The form of the macro will actually depend on whether the option is equivalenced to another, and/or has an assigned handler procedure. Unlike the SET_OPT macro, this macro does not allow an option argument.

DISABLE_OPT_NAME;

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.6 ENABLED( <NAME> ) - Is Option Enabled?

Yields true if the option defaults to disabled and ISUNUSED_OPT() would yield true. It also yields true if the option has been specified with a disablement prefix, disablement value or the DISABLE_OPT_NAME macro was invoked.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.7 ERRSKIP_OPTERR - Ignore Option Errors

When it is necessary to continue (return to caller) on option errors, invoke this option. It is reversible. See section 7.5.8 ERRSTOP_OPTERR - Stop on Errors.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.8 ERRSTOP_OPTERR - Stop on Errors

After invoking this macro, if optionProcess() encounters an error, it will call exit(1) rather than return. This is the default processing mode. It can be overridden by specifying allow-errors in the definitions file, or invoking the macro See section 7.5.7 ERRSKIP_OPTERR - Ignore Option Errors.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.9 HAVE_OPT( <NAME> ) - Have this option?

This macro yields true if the option has been specified in any fashion at all. It is used thus:

if (HAVE_OPT( NAME )) {
    <do-things-associated-with-opt-name>;
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.10 ISSEL_OPT( <NAME> ) - Is Option Selected?

This macro yields true if the option has been specified either on the command line or via a SET/DISABLE macro.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.11 ISUNUSED_OPT( <NAME> ) - Never Specified?

This macro yields true if the option has never been specified, or has been cleared via the CLEAR_OPT() macro.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.12 OPTION_CT - Full Count of Options

The full count of all options, both those defined and those generated automatically by AutoOpts. This is primarily used to initialize the program option descriptor structure.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.13 OPT_ARG( <NAME> ) - Option Argument String

The option argument value as a pointer to string. Note that argument values that have been specified as numbers are stored as numbers or keywords. For such options, use instead the OPT_VALUE_name define. It is used thus:

if (HAVE_OPT( NAME )) {
    char* p = OPT_ARG( NAME );
    <do-things-with-opt-name-argument-string>;
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.14 OPT_VALUE_name - Option Argument Value

This macro gets emitted only for options that take numeric or keyword arguments. The macro yields a word-sized integer containing the enumeration or numeric value of the option argument.

int opt_val = OPT_VALUE_NAME;

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.15 RESTART_OPT( n ) - Resume Option Processing

If option processing has stopped (either because of an error or something was encountered that looked like a program argument), it can be resumed by providing this macro with the index n of the next option to process and calling optionProcess() again.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.16 SET_OPT_name - Force an option to be set

This macro gets emitted only when the given option has the settable attribute specified.

The form of the macro will actually depend on whether the option is equivalenced to another, has an option argument and/or has an assigned handler procedure. If the option has an argument, then this macro will too. Beware that the argument is not reallocated, so the value must not be on the stack or deallocated in any other way for as long as the value might get referenced.

If you have supplied at least one `homerc' file (@pxref{}), this macro will be emitted for the --save-opts option.

SET_OPT_SAVE_OPTS( "filename" );

See section 7.4.4 Automatically Supported Options for a discussion of the implications of using this particular example.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.17 STACKCT_OPT( <NAME> ) - Stacked Arg Count

When the option handling attribute is specified as stack_arg, this macro may be used to determine how many of them actually got stacked.

Do not use this on options that have not been stacked or has not been specified (the stack_arg attribute must have been specified, and HAVE_OPT(<NAME>) must yield TRUE). Otherwise, you will likely seg fault.

if (HAVE_OPT( NAME )) {
    int     ct = STACKCT_OPT(  NAME );
    char**  pp = STACKLST_OPT( NAME );

    do  {
        char* p = *pp++;
        do-things-with-p;
    } while (--ct > 0);
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.18 STACKLST_OPT( <NAME> ) - Argument Stack

The address of the list of pointers to the option arguments. The pointers are ordered by the order in which they were encountered in the option presets and command line processing.

Do not use this on options that have not been stacked or has not been specified (the stack_arg attribute must have been specified, and HAVE_OPT(<OPTION>) must yield TRUE). Otherwise, you will likely seg fault.

if (HAVE_OPT( NAME )) {
    int     ct = STACKCT_OPT(  NAME );
    char**  pp = STACKLST_OPT( NAME );

    do  {
        char* p = *pp++;
        do-things-with-p;
    } while (--ct > 0);
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.19 START_OPT - Restart Option Processing

This is just a shortcut for RESTART_OPT(1) (See section 7.5.15 RESTART_OPT( n ) - Resume Option Processing.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.20 STATE_OPT( <NAME> ) - Option State

If you need to know if an option was set because of presetting actions (RC/INI processing or environment variables), versus a command line entry versus one of the SET/DISABLE macros, then use this macro. It will yield one of four values: OPTST_INIT, OPTST_SET, OPTST_PRESET or OPTST_DEFINED. It is used thus:

switch (STATE_OPT( NAME )) {
    case OPTST_INIT:
        not-preset, set or on the command line.  (unless CLEAR-ed)

    case OPTST_SET:
        option set via the SET_OPT_NAME() macro.

    case OPTST_PRESET:
        option set via an RC/INI file or environment variable

    case OPTST_DEFINED:
        option set via a command line option.

    default:
        cannot happen :)
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.21 USAGE( exit-code ) - Usage invocation macro

This macro invokes the procedure registered to display the usage text. Normally, this will be optionUsage from the AutoOpts library, but you may select another procedure by specifying usage = "proc_name" program attribute. This procedure must take two arguments first, a pointer to the option descriptor, and second the exit code. The macro supplies the option descriptor automatically. This routine is expected to call exit(3) with the provided exit code.

The optionUsage routine also behaves differently depending on the exit code. If the exit code is zero, it is assumed that assistance has been requested. Consequently, a little more information is provided than when displaying usage and exiting with a non-zero exit code.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.22 VALUE_OPT_name - Option Flag Value

This is a #define for the flag character used to specify an option on the command line. If value was not specified for the option, then it is a unique number associated with the option. option value refers to this value, option argument refers to the (optional) argument to the option.

switch (WHICH_OPT_OTHER_OPT) {
case VALUE_OPT_NAME:
    this-option-was-really-opt-name;
case VALUE_OPT_OTHER_OPT:
    this-option-was-really-other-opt;
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.23 VERSION - Version and Full Version

If the version attribute is defined for the program, then a stringified version will be #defined as PROGRAM_VERSION and PROGRAM_FULL_VERSION. PROGRAM_FULL_VERSION is used for printing the program version in response to the version option. The version option is automatically supplied in response to this attribute, too.

You may access PROGRAM_VERSION via programOptions.pzFullVersion.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.24 WHICH_IDX_name - Which Equivalenced Index

This macro gets emitted only for equivalenced-to options. It is used to obtain the index for the one of the several equivalence class members set the equivalenced-to option.

switch (WHICH_IDX_OTHER_OPT) {
case INDEX_OPT_NAME:
    this-option-was-really-opt-name;
case INDEX_OPT_OTHER_OPT:
    this-option-was-really-other-opt;
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.25 WHICH_OPT_name - Which Equivalenced Option

This macro gets emitted only for equivalenced-to options. It is used to obtain the value code for the one of the several equivalence class members set the equivalenced-to option.

switch (WHICH_OPT_OTHER_OPT) {
case VALUE_OPT_NAME:
    this-option-was-really-opt-name;
case VALUE_OPT_OTHER_OPT:
    this-option-was-really-other-opt;
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.26 teOptIndex - Option Index and Enumeration

This enum defines the complete set of options, both user specified and automatically provided. This can be used, for example, to distinguish which of the equivalenced options was actually used.

switch (pOptDesc->optActualIndex) {
case INDEX_OPT_FIRST:
    stuff;
case INDEX_OPT_DIFFERENT:
    different-stuff;
default:
    unknown-things;
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.27 OPTIONS_STRUCT_VERSION - active version

You will not actually need to reference this value, but you need to be aware that it is there. It is the first value in the option descriptor that you pass to optionProcess. It contains a magic number and version information. Normally, you should be able to work with a more recent option library than the one you compiled with. However, if the library is changed incompatibly, then the library will detect the out of date magic marker, explain the difficulty and exit. You will then need to rebuild and recompile your option definitions. This has rarely been necessary.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.28 libopts External Procedures

These are the routines that libopts users may call directly from their code. There are several other routines that can be called by code generated by the libopts option templates, but they are not to be called from any other user code. The `options.h' is fairly clear about this, too.

7.5.28.1 optionFree
7.5.28.2 optionLoadLine
7.5.28.3 optionProcess
7.5.28.4 optionRestore
7.5.28.5 optionSaveFile
7.5.28.6 optionSaveState
7.5.28.7 optionVersion

This subsection was automatically generated by AutoGen using extracted information and the aginfo3.tpl template.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.28.1 optionFree

free allocated option processing memory

Usage:
optionFree( pOpts );
Where the arguments are:
Name | Type | Description
----- | ----- | -------------
pOpts | tOptions* | program options descriptor

AutoOpts sometimes allocates memory and puts pointers to it in the option state structures. This routine deallocates all such memory.

As long as memory has not been corrupted, this routine is always successful.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.28.2 optionLoadLine

process a string for an option name and value

Usage:
optionLoadLine( pOpts, pzLine );
Where the arguments are:
Name | Type | Description
----- | ----- | -------------
pOpts | tOptions* | program options descriptor
pzLine | const char* | NUL-terminated text

This is a user callable routine for setting options from, for example, the contents of a file that they read in. Only one option may appear in the text. It will be treated as a normal (non-preset) option.

When passed a pointer to the option struct and a string, it will find the option named by the first token on the string and set the option argument to the remainder of the string. The caller must NUL terminate the string. Any embedded new lines will be included in the option argument.

Invalid options are silently ignored. Invalid option arguments will cause a warning to print, but the function should return.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.28.3 optionProcess

this is the main option processing routine

Usage:
int res = optionProcess( pOpts, argc, argv );
Where the arguments are:
Name | Type | Description
----- | ----- | -------------
pOpts | tOptions* | program options descriptor
argc | int | program arg count
argv | char** | program arg vector
returns | int | the count of the arguments processed

This is the main entry point for processing options. It is intended that this procedure be called once at the beginning of the execution of a program. Depending on options selected earlier, it is sometimes necessary to stop and restart option processing, or to select completely different sets of options. This can be done easily, but you generally do not want to do this.

The number of arguments processed always includes the program name. If one of the arguments is "--", then it is counted and the processing stops. If an error was encountered and errors are to be tolerated, then the returned value is the index of the argument causing the error.

Errors will cause diagnostics to be printed. exit(3) may or may not be called. It depends upon whether or not the options were generated with the "allow-errors" attribute, or if the ERRSKIP_OPTERR or ERRSTOP_OPTERR macros were invoked.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.28.4 optionRestore

restore option state from memory copy

Usage:
optionRestore( pOpts );
Where the arguments are:
Name | Type | Description
----- | ----- | -------------
pOpts | tOptions* | program options descriptor

Copy back the option state from saved memory. The allocated memory is left intact, so this routine can be called repeatedly without having to call optionSaveState again.

If you have not called optionSaveState before, a diagnostic is printed to stderr and exit is called.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.28.5 optionSaveFile

saves the option state to a file

Usage:
optionSaveFile( pOpts );
Where the arguments are:
Name | Type | Description
----- | ----- | -------------
pOpts | tOptions* | program options descriptor

This routine will save the state of option processing to a file. The name of that file can be specified with the argument to the --save-opts option, or by appending the rcfile attribute to the last homerc attribute. If no rcfile attribute was specified, it will default to .programnamerc. If you wish to specify another file, you should invoke the SET_OPT_SAVE_OPTS( filename ) macro.

If no homerc file was specified, this routine will silently return and do nothing. If the output file cannot be created or updated, a message will be printed to stderr and the routine will return.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.28.6 optionSaveState

saves the option state to memory

Usage:
optionSaveState( pOpts );
Where the arguments are:
Name | Type | Description
----- | ----- | -------------
pOpts | tOptions* | program options descriptor

This routine will allocate enough memory to save the current option processing state. If this routine has been called before, that memory will be reused. You may only save one copy of the option state. This routine may be called before optionProcess(3).

If it fails to allocate the memory, it will print a message to stderr and exit. Otherwise, it will always succeed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.28.7 optionVersion

return the compiled AutoOpts version number

Usage:
const char* res = optionVersion();
Where the arguments are:
Name | Type | Description
----- | ----- | -------------
returns | const char* | the version string in constant memory

Returns the full version string compiled into the library. The returned string cannot be modified.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.6 Option Descriptor File

This is the module that is to be compiled and linked with your program. It contains internal data and procedures subject to change. Basically, it contains a single global data structure containing all the information provided in the option definitions, plus a number of static strings and any callout procedures that are specified or required. You should never have need for looking at this, except, perhaps, to examine the code generated for implementing the flag_code construct.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.7 Using AutoOpts

To use AutoOpts in your application:

  • Create a file `myopts.def', according to the documentation above. It is probably easiest to start with the example in 7.3 Quick Start and edit it into the form you need.

  • Run AutoGen to create the option interface file (myopts.h) and the option descriptor code (myopts.c):

    autogen -L $prefix/share/autogen myopts.def

  • In all your source files where you need to refer to option state, #include "myopts.h".
  • In your main routine, code something along the lines of:

    main( int argc, char** argv )
{
    {
        int arg_ct = optionProcess( &myprogOptions, argc, argv );
        argc -= arg_ct;
        if ((argc < ARGC_MIN) || (argc > ARGC_MAX)) {
            fprintf( stderr, "%s ERROR:  remaining args (%d) "
                     "out of range\n", myprogOptions.pzProgName,
                     argc );

            USAGE( EXIT_FAILURE );
        }
        argv += arg_ct;
    }
    if (HAVE_OPT(OPTN_NAME))
        respond_to_optn_name();
    ...
}

  • Compile `myopts.c' and link your program with the following additional arguments:

    myopts.o -L $prefix/lib -lopts

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8 AutoOpts for Shell Scripts

AutoOpts may be used with shell scripts by automatically creating a complete program that will process command line options and pass back the results to the invoking shell by issuing shell variable assignment commands. It may also be used to generate portable shell code that can be inserted into your script.

The functionality of these features, of course, is somewhat constrained compared with the normal program facilities. Specifically, you cannot invoke callout procedures with either of these methods. Additionally, if you generate a shell script:

  1. You cannot obtain options from RC/INI files.
  2. You cannot obtain options from environment variables.
  3. You cannot save the option state to an option file.
  4. Option conflict/requirement verification is disabled.

Both of these methods are enabled by running AutoGen on the definitions file with the additional global attribute:

test-main [ = proc-to-call ] ;

If you do not supply a proc-to-call, it will default to putBourneShell. That will produce a program that will process the options and generate shell text for the invoking shell to interpret. If you supply the name, putShellParse, then you will have a program that will generate a shell script that can parse the options. If you supply a different procedure name, you will have to provide that routine and it may do whatever you like.

In summary, you will need to issue approximately the following two commands to have a working program:

autogen -L <opt-template-dir> program.def
cc -o progopts -L <opt-lib-dir> -I <opt-include-dir> \
        -DTEST_program_OPTS program.c -lopts

The resulting program can be used within your shell script as follows:

eval `./progopts $@`
if [ -z "${OPTION_CT}" ] ; then exit 1 ; fi
shift ${OPTION_CT}

If you had used "test-main = putShellParse" instead, then you can, at this point, merely run the program and it will write the parsing script to standard out. You may also provide this program with command line options to specify the shell script file to create or edit, and you may specify the shell program to use on the first shell script line. That program's usage text would look something like this:

genshellopt - Generate Shell Option Processing Script - Ver. 1
USAGE:  genshellopt [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
  Flg Arg Option-Name    Description
   -o YES script         Output Script File
   -s YES shell          Shell name (follows "#!" magic)
                                - disabled as --no-shell
                                - enabled by default
   -v opt version        Output version information and exit
   -? no  help           Display usage information and exit
   -! no  more-help      Extended usage information passed thru pager

Options may be specified by doubled hyphens and their name
or by a single hyphen and the flag character (option value).

Note that `shell' is only useful if the output file does not already
exist.  If it does, then the shell name and optional first argument
will be extracted from the script file.

If the script file already exists and contains Automated Option Processing
text, the second line of the file through the ending tag will be replaced
by the newly generated text.  The first `#!' line will be regenerated.

= = = = = = = =

This incarnation of genshell will produce
a shell script to parse the options for getdefs:

getdefs - AutoGen Definition Extraction Tool - Ver. 1.3
USAGE:  getdefs { <option-name>[{=| }<val>] }...
   Arg Option-Name   Req?  Description
   YES defs-to-get    opt  Regexp to look for after the "/*="
   opt ordering       opt  Alphabetize or use named file
   Num first-index    opt  The first index to apply to groups
   YES input          YES  Input file to search for defs
   YES subblock       opt  subblock definition names
   YES listattr       opt  attribute with list of values
   opt filelist       opt  Insert source file names into defs
   YES assign         opt  Global assignments
   YES common-assign  opt  Assignments common to all blocks
   YES copy           opt  File(s) to copy into definitions
   opt srcfile        opt  Insert source file name into each def
   opt linenum        opt  Insert source line number into each def
   YES output         opt  Output file to open
   opt autogen        opt  Invoke AutoGen with defs
   YES template       opt  Template Name
   YES agarg          opt  AutoGen Argument
   YES base-name      opt  Base name for output file(s)
   opt version        opt  Output version information and exit
   no  help           opt  Display usage information and exit
   no  more-help      opt  Extended usage information passed thru pager
   opt save-opts      opt  Save the option state to an rc file
   YES load-opts      opt  Load options from an rc file

All arguments are named options.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.9 Automated Info Docs

AutoOpts provides two templates for producing `.texi' documentation. `aginfo.tpl' for the invoking section, and `aginfo3.tpl' for describing exported library functions and macros.

For both types of documents, the documentation level is selected by passing a `-DLEVEL=<level-name>' argument to AutoGen when you build the document. (See the example invocation below.)

Two files will be produced, a `.texi' file and a `.menu' file. You should include the `.menu' file in your document where you wish to reference the `invoking' chapter, section or subsection.

The `.texi' file will contain an introductory paragraph, a menu and a subordinate section for the invocation usage and for each documented option. The introductory paragraph is normally the boiler plate text, along the lines of:

This chapter documents the @file{AutoOpts} generated usage text
and option meanings for the @file{your-program} program.

or:

These are the publicly exported procedures from the libname library.
Any other functions mentioned in the header file are for the private use
of the library.

7.9.1 "invoking" info docs
7.9.2 library info docs

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.9.1 "invoking" info docs

Using the option definitions for an AutoOpt client program, the `aginfo.tpl' template will produce texinfo text that documents the invocation of your program. The text emitted is designed to be included in the full texinfo document for your product. It is not a stand-alone document. The usage text for the 5.1 autogen usage help (-?), 8.5.1 getdefs usage help and 8.4.1 columns usage help (-?) programs, are included in this document and are all generated using this template.

If your program's option definitions include a `prog-info-descrip' section, then that text will replace the boilerplate introductory paragraph.

These files are produced by invoking the following command:

autogen -L ${prefix}/share/autogen -T aginfo.tpl \
        -DLEVEL=section your-opts.def

Where `${prefix}' is the AutoGen installation prefix and `your-opts.def' is the name of your product's option definition file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.9.2 library info docs

The `texinfo' doc for libraries is derived from mostly the same information as is used for producing man pages See section 7.10.2 library man pages. The main difference is that there is only one output file and the individual functions are referenced from a .texi menu. There is also a small difference in the global attributes used:

lib_description | A description of the library. This text appears before the menu. If not provided, the standard boilerplate version will be inserted.
see_also | The SEE ALSO functionality is not supported for the `texinfo' documentation, so any see_also attribute will be ignored.

These files are produced by invoking the following commands:

getdefs linenum srcfile template=aginfo3.tpl output=libexport.def \
       <source-file-list>

autogen -L ${prefix}/share/autogen -DLEVEL=section libexport.def

Where `${prefix}' is the AutoGen installation prefix and `libexport.def' is some name that suits you.

An example of this can be seen in this document, See section 7.5.28 libopts External Procedures.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.10 Automated Man Pages

AutoOpts provides two templates for producing man pages. The command (`man1') pages are derived from the options definition file, and the library (`man3') pages are derived from stylized comments (see section 8.5 Invoking getdefs).

7.10.1 command line man pages
7.10.2 library man pages

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.10.1 command line man pages

Using the option definitions for an AutoOpt client program, the `agman1.tpl' template will produce an nroff document suitable for use as a `man(1)' page document for a command line command. The description section of the document is either the `prog-man-descrip' text, if present, or the `detail' text.

Each option in the option definitions file is fully documented in its usage. This includes all the information documented above for each option (see section 7.4.2 Option Attributes), plus the `doc' attribute is appended. Since the `doc' text is presumed to be designed for texinfo documentation, sed is used to convert some constructs from texi to nroff-for-man-pages. Specifically,

convert @code, @var and @samp into \fB...\fP phrases
convert @file into \fI...\fP phrases
Remove the '@' prefix from curly braces
Indent example regions
Delete the example commands
Replace `end example' command with ".br"
Replace the `@*' command with ".br"

This document is produced by invoking the following command:

AutoGen -L ${prefix}/share/autogen -T agman1.tpl options.def

Where `${prefix}' is the AutoGen installation prefix and `options.def' is the name of your product's option definition file. I do not use this very much, so any feedback or improvements would be greatly appreciated.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.10.2 library man pages

Two global definitions are required, and then one library man page is produced for each export_func definition that is found. It is generally convenient to place these definitions as `getdefs' comments (see section 8.5 Invoking getdefs) near the procedure definition, but they may also be a separate AutoGen definitions file (see section 2. AutoGen Definitions File). Each function will be cross referenced with their sister functions in a `SEE ALSO' section. A global see_also definition will be appended to this cross referencing text.

The two global definitions required are:

library | This is the name of your library, without the `lib' prefix. The AutoOpts library is named `libopts.so...', so the library attribute would have the value opts.
header | Generally, using a library with a compiled program entails #include-ing a header file. Name that header with this attribute. In the case of AutoOpts, it is generated and will vary based on the name of the option definition file. Consequently, `your-opts.h' is specified.

The export_func definition should contain the following attributes:

name | The name of the procedure the library user may call.
what | A brief sentence describing what the procedure does.
doc | A detailed description of what the procedure does. It may ramble on for as long as necessary to properly describe it.
err | A short description of how errors are handled.
ret_type | The data type returned by the procedure. Omit this for void procedures.
ret_desc | Describe what the returned value is, if needed.
private | If specified, the function will not be documented. This is used, for example, to produce external declarations for functions that are not available for public use, but are used in the generated text.
arg | This is a compound attribute that contains:
arg_type | The data type of the argument.
arg_name | A short name for it.
arg_desc | A brief description.

As a `getdefs' comment, this would appear something like this:

/*=--subblock=arg=arg_type,arg_name,arg_desc =*/
/*=*
 * library: opts
 * header:  your-opts.h
=*/
/*=export_func optionProcess
 *
 * what: this is the main option processing routine
 * arg:  + tOptions* + pOpts + program options descriptor +
 * arg:  + int       + argc  + program arg count  +
 * arg:  + char**    + argv  + program arg vector +
 * ret_type:  int
 * ret_desc:  the count of the arguments processed
 *
 * doc:  This is what it does.
 * err:  When it can't, it does this.
=*/

Note the subblock and library comments. subblock is an embedded `getdefs' option (see section 8.5.6 subblock option) that tells it how to parse the arg attribute. The library and header entries are global definitions that apply to all the documented functions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. Add-on packages for AutoGen

This chapter includes several programs that either work closely with AutoGen (extracting definitions or providing special formatting functions).

AutoOpts ought to appear in this list also, but since it is the primary reason why many people would even look into AutoGen at all, I decided to leave it in the list of chapters.

8.1 Automated Finite State Machine
8.2 Combined RPC Marshalling
8.3 Automated Event Management
8.4 Invoking columns
8.5 Invoking getdefs
8.6 Replacement for Stdio Formatting Library The extensible format printing library.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1 Automated Finite State Machine

The templates to generate a finite state machine in C or C++ is included with AutoGen. The documentation is not. The documentation is in HTML format for viewing, or you can download FSM.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2 Combined RPC Marshalling

The templates and NFSv4 definitions are not included with AutoGen in any way. The folks that designed NFSv4 noticed that much time and bandwidth was wasted sending queries and responses when many of them could be bundled. The protocol bundles the data, but there is no support for it in rpcgen. That means you have to write your own code to do that. Until now. Download this and you will have a large, complex example of how to use AutoXDR for generating the marshalling and unmarshalling of combined RPC calls. There is a brief example on the web, but you should download AutoXDR.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.3 Automated Event Management

Large software development projects invariably have a need to manage the distribution and display of state information and state changes. In other words, they need to manage their software events. Generally, each such project invents its own way of accomplishing this and then struggles to get all of its components to play the same way. It is a difficult process and not always completely successful. This project helps with that.

AutoEvents completely separates the tasks of supplying the data needed for a particular event from the methods used to manage the distribution and display of that event. Consequently, the programmer writing the code no longer has to worry about that part of the problem. Likewise the persons responsible for designing the event management and distribution no longer have to worry about getting programmers to write conforming code.

This is a work in progress. See my web page on the subject, if you are interested. I have some useful things put together, but it is not ready to call a product.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4 Invoking columns

This program was designed for the purpose of generating compact, columnized tables. It will read a list of text items from standard in or a specified input file and produce a columnized listing of all the non-blank lines. Leading white space on each line is preserved, but trailing white space is stripped. Methods of applying per-entry and per-line embellishments are provided. See the formatting and separation arguments below.

This program is used by AutoGen to help clean up and organize its output.

See `autogen/agen5/fsm.tpl' and the generated output `pseudo-fsm.h'.

This function was not implemented as an expression function because either it would have to be many expression functions, or a provision would have to be added to provide options to expression functions. Maybe not a bad idea, but it is not being implemented at the moment.

A side benefit is that you can use it outside of AutoGen to columnize input, a la the ls command.

This section was generated by AutoGen, the aginfo template and the option descriptions for the columns program. It documents the columns usage text and option meanings.

This software is released under the GNU General Public License.

8.4.1 columns usage help (-?)
8.4.13 by-columns option
8.4.4 col-width option (-w)
8.4.3 columns option (-c)
8.4.7 first-indent option
8.4.10 format option (-f)
8.4.6 indent option (-I)
8.4.14 input option (-i)
8.4.12 line-separation option
8.4.11 separation option (-S)
8.4.9 sort option (-s)
8.4.5 spread option
8.4.8 tab-width option
8.4.2 width option (-W)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.1 columns usage help (-?)

This is the automatically generated usage text for columns:

@exampleindent 0
columns - Columnize Input Text - Ver. 1.1
USAGE:  columns [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
  Flg Arg Option-Name    Description
   -W Num width          Maximum Line Width
   -c Num columns        Desired number of columns
   -w Num col-width      Set width of each column
      Num spread         maximum spread added to column width
   -I YES indent         Line prefix or indentation
      YES first-indent   First line prefix
                                - requires these options:
                                indent
      Num tab-width      tab width
   -s opt sort           Sort input text
   -f YES format         Formatting string for each input
   -S YES separation     Separation string - follows all but last
      YES line-separation string at end of all lines but last
      no  by-columns     Print entries in column order
   -i YES input          Input file (if not stdin)
   -v opt version        Output version information and exit
   -? no  help           Display usage information and exit
   -! no  more-help      Extended usage information passed thru pager

Options may be specified by doubled hyphens and their name
or by a single hyphen and the flag character (option value).

This program was designed for the purpose of generating compact,
columnized tables.  It will read a list of text items from standard
in or a specified input file and produce a columnized listing of
all the non-blank lines.  Leading white space on each line is
preserved, but trailing white space is stripped.  Methods of
applying per-entry and per-line embellishments are provided.
See the formatting and separation arguments below.

This program is used by AutoGen to help clean up and organize
its output.
@exampleindent 4

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.2 width option (-W)

This is the "maximum line width" option. This option specifies the full width of the output line, including any start-of-line indentation. The output will fill each line as completely as possible, unless the column width has been explicitly specified. If the maximum width is less than the length of the widest input, you will get a single column of output.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.3 columns option (-c)

This is the "desired number of columns" option. Use this option to specify exactly how many columns to produce. If that many columns will not fit within line_width, then the count will be reduced to the number that fit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.4 col-width option (-w)

This is the "set width of each column" option. Use this option to specify exactly how many characters are to be allocated for each column. If it is narrower than the widest entry, it will be over-ridden with the required width.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.5 spread option

This is the "maximum spread added to column width" option. Use this option to specify exactly how many characters may be added to each column. It allows you to prevent columns from becoming too far apart.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.6 indent option (-I)

This is the "line prefix or indentation" option. If a number, then this many spaces will be inserted at the start of every line. Otherwise, it is a line prefix that will be inserted at the start of every line.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.7 first-indent option

This is the "first line prefix" option.

This option has some usage constraints. It:

  • must appear in combination with the following options: indent.

If a number, then this many spaces will be inserted at the start of the first line. Otherwise, it is a line prefix that will be inserted at the start of that line.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.8 tab-width option

This is the "tab width" option. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.9 sort option (-s)

This is the "sort input text" option. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.10 format option (-f)

This is the "formatting string for each input" option. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.11 separation option (-S)

This is the "separation string - follows all but last" option. Use this option if, for example, you wish a comma to appear after each entry except the last.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.12 line-separation option

This is the "string at end of all lines but last" option. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.13 by-columns option

This is the "print entries in column order" option. Normally, the entries are printed out in order by rows and then columns. This option will cause the entries to be ordered within columns. The final column, instead of the final row, may be shorter than the others.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.14 input option (-i)

This is the "input file (if not stdin)" option. This program normally runs as a filter, reading from standard input, columnizing and writing to standard out. This option redirects input to a file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5 Invoking getdefs

This program extracts AutoGen definitions from a list of source files. Definitions are delimited by `/*=<entry-type> <entry-name>\n' and `=*/\n'. From that, this program creates a definition of the following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis "..." is filled in by text found between the two delimiters, using the following rules:

  1. Each entry is located by the pattern "\n[^*\n]*\\*[ \t]*([a-z][a-z0-9_]*):". Fundamentally, it finds a line that, after the first asterisk on the line, contains whitespace then a name and is immediately followed by a colon. The name becomes the name of the attribute and what follows, up to the next attribute, is its value.
  2. If the first character of the value is either a single or double quote, then you are responsible for quoting the text as it gets inserted into the output definitions.
  3. All the leading text on a line is stripped from the value. The leading text is everything before the first asterisk, the asterisk and all the whitespace characters that immediately follow it. If you want whitespace at the beginnings of the lines of text, you must do something like this:

     * mumble:
 * "  this is some\n"
 * "  indented text."

  4. If the `<entry-name>' is followed by a comma, the word `ifdef' (or 'ifndef') and a name `if_name', then the above entry will appear as:

    #ifdef if_name
#line nnn "source-file-name"
entry_type = {
    name = entry_name;
    ...
};
#endif

  5. If you use of the subblock option, you can specify a nested value, See section 8.5.6 subblock option. That is, this text:

     * arg:  int, this, what-it-is

    with the `--subblock=arg=type,name,doc' option would yield:

    arg = { type = int; name = this; doc = what-it-is; };

This section was generated by AutoGen, the aginfo template and the option descriptions for the getdefs program. It documents the getdefs usage text and option meanings.

This software is released under the GNU General Public License.

8.5.1 getdefs usage help
8.5.17 agarg option
8.5.9 assign option
8.5.15 autogen option
8.5.18 base-name option
8.5.10 common-assign option
8.5.11 copy option
8.5.2 defs-to-get option
8.5.8 filelist option
8.5.4 first-index option
8.5.5 input option
8.5.13 linenum option
8.5.7 listattr option
8.5.3 ordering option
8.5.14 output option
8.5.12 srcfile option
8.5.6 subblock option
8.5.16 template option

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.1 getdefs usage help

This is the automatically generated usage text for getdefs:

@exampleindent 0
getdefs - AutoGen Definition Extraction Tool - Ver. 1.3
USAGE:  getdefs { <option-name>[{=| }<val>] }...
   Arg Option-Name   Req?  Description
   YES defs-to-get    opt  Regexp to look for after the "/*="
   opt ordering       opt  Alphabetize or use named file
                                - disabled as --no-ordering
                                - enabled by default
   Num first-index    opt  The first index to apply to groups
   YES input          YES  Input file to search for defs
                                - may appear multiple times
                                - default option for unnamed options
   YES subblock       opt  subblock definition names
                                - may appear multiple times
   YES listattr       opt  attribute with list of values
                                - may appear multiple times
   opt filelist       opt  Insert source file names into defs

Definition insertion options

   Arg Option-Name   Req?  Description
   YES assign         opt  Global assignments
                                - may appear multiple times
   YES common-assign  opt  Assignments common to all blocks
                                - may appear multiple times
   YES copy           opt  File(s) to copy into definitions
                                - may appear multiple times
   opt srcfile        opt  Insert source file name into each def
   opt linenum        opt  Insert source line number into each def

Definition output disposition options:

   Arg Option-Name   Req?  Description
   YES output         opt  Output file to open
                                - an alternate for autogen
   opt autogen        opt  Invoke AutoGen with defs
                                - disabled as --no-autogen
                                - enabled by default
   YES template       opt  Template Name
   YES agarg          opt  AutoGen Argument
                                - prohibits these options:
                                output
                                - may appear multiple times
   YES base-name      opt  Base name for output file(s)
                                - prohibits these options:
                                output

Auto-supported Options:

   Arg Option-Name   Req?  Description
   opt version        opt  Output version information and exit
   no  help           opt  Display usage information and exit
   no  more-help      opt  Extended usage information passed thru pager
   opt save-opts      opt  Save the option state to an rc file
   YES load-opts      opt  Load options from an rc file
                                - disabled as --no-load-opts
                                - may appear multiple times

All arguments are named options.

The following option preset mechanisms are supported:
 - reading file /dev/null

This program extracts AutoGen definitions from a list of source files.
Definitions are delimited by `/*=<entry-type> <entry-name>\n' and
`=*/\n'.  From that, this program creates a definition of the
following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis '...' is filled in by text found between the two
delimiters, with everything up through the first sequence of
asterisks deleted on every line.

There are two special ``entry types'':

*  The entry_type enclosure and the name entry will be omitted
   and the ellipsis will become top-level definitions.

-- The contents of the comment must be a single getdefs option.
   The option name must follow the double hyphen and its argument
   will be everything following the name.  This is intended for use
   with the ``subblock'' and ``listattr'' options.
@exampleindent 4

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.2 defs-to-get option

This is the "regexp to look for after the "/*="" option. If you want definitions only from a particular category, or even with names matching particular patterns, then specify this regular expression for the text that must follow the /*=.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.3 ordering option

This is the "alphabetize or use named file" option.

This option has some usage constraints. It:

  • is enabled by default.

By default, ordering is alphabetical by the entry name. Use, no-ordering if order is unimportant. Use ordering with no argument to order without case sensitivity. Use ordering=<file-name> if chronological order is important. getdefs will maintain the text content of file-name. file-name need not exist.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.4 first-index option

This is the "the first index to apply to groups" option. By default, the first occurrance of a named definition will have an index of zero. Sometimes, that needs to be a reserved value. Provide this option to specify a different starting point.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.5 input option

This is the "input file to search for defs" option.

This option has some usage constraints. It:

  • is required to appear on the command line.
  • may appear an unlimited number of times.

All files that are to be searched for definitions must be named on the command line or read from stdin. If there is only one input option and it is the string, "-", then the input file list is read from stdin. If a command line argument is not an option name and does not contain an assignment operator (=), then it defaults to being an input file name. At least one input file must be specified.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.6 subblock option

This is the "subblock definition names" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.

This option is used to create shorthand entries for nested definitions. For example, with:

using subblock thus
--subblock=arg=argname,type,null
and defining an arg thus
arg: this, char *
will then expand to:
arg = { argname = this; type = "char *"; };
The "this, char *" string is separated at the commas, with the white space removed. You may use characters other than commas by starting the value string with a punctuation character other than a single or double quote character. You may also omit intermediate values by placing the commas next to each other with no intervening white space. For example, "+mumble++yes+" will expand to:
arg = { argname = mumble; null = "yes"; };.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.7 listattr option

This is the "attribute with list of values" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.

This option is used to create shorthand entries for definitions that generally appear several times. That is, they tend to be a list of values. For example, with:
listattr=foo defined, the text:
foo: this, is, a, multi-list will then expand to:
foo = 'this', 'is', 'a', 'multi-list';
The texts are separated by the commas, with the white space removed. You may use characters other than commas by starting the value string with a punctuation character other than a single or double quote character.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.8 filelist option

This is the "insert source file names into defs" option. Inserts the name of each input file into the output definitions. If no argument is supplied, the format will be:
infile = '%s';
If an argument is supplied, that string will be used for the entry name instead of infile.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.9 assign option

This is the "global assignments" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.

The argument to each copy of this option will be inserted into the output definitions, with only a semicolon attached.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.10 common-assign option

This is the "assignments common to all blocks" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.

The argument to each copy of this option will be inserted into each output definition, with only a semicolon attached.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.11 copy option

This is the "file(s) to copy into definitions" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.

The content of each file named by these options will be inserted into the output definitions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.12 srcfile option

This is the "insert source file name into each def" option. Inserts the name of the input file where a definition was found into the output definition. If no argument is supplied, the format will be:
srcfile = '%s';
If an argument is supplied, that string will be used for the entry name instead of srcfile.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.13 linenum option

This is the "insert source line number into each def" option. Inserts the line number in the input file where a definition was found into the output definition. If no argument is supplied, the format will be:
linenum = '%s';
If an argument is supplied, that string will be used for the entry name instead of linenum.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.14 output option

This is the "output file to open" option.

This option has some usage constraints. It:

  • is a member of the autogen class of options.

If you are not sending the output to an AutoGen process, you may name an output file instead.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.15 autogen option

This is the "invoke autogen with defs" option.

This option has some usage constraints. It:

  • is enabled by default.
  • is a member of the autogen class of options.

This is the default output mode. Specifying no-autogen is equivalent to output=-. If you supply an argument to this option, that program will be started as if it were AutoGen and its standard in will be set to the output definitions of this program.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.16 template option

This is the "template name" option. Specifies the template name to be used for generating the final output.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.17 agarg option

This is the "autogen argument" option.

This option has some usage constraints. It:

  • may appear an unlimited number of times.
  • must not appear in combination with any of the following options: output.

This is a pass-through argument. It allows you to specify any arbitrary argument to be passed to AutoGen.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5.18 base-name option

This is the "base name for output file(s)" option.

This option has some usage constraints. It:

  • must not appear in combination with any of the following options: output.

When output is going to AutoGen, a base name must either be supplied or derived. If this option is not supplied, then it is taken from the template option. If that is not provided either, then it is set to the base name of the current directory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.6 Replacement for Stdio Formatting Library

Using the `printf' formatting routines in a portable fashion has always been a pain, and this package has been way more pain than anyone ever imagined. Hopefully, with this release of snprintfv, the pain is now over for all time.

The issues with portable usage are these:

  1. Argument number specifiers are often either not implemented or are buggy. Even GNU libc, version 1 got it wrong.

  2. ANSI/ISO "forgot" to provide a mechanism for computing argument lists for vararg procedures.

  3. The argument array version of printf (`printfv()') is not generally available, does not work with the native printf, and does not have a working argument number specifier in the format specification. (Last I knew, anyway.)

  4. You cannot fake varargs by calling `vprintf()' with an array of arguments, because ANSI does not require such an implementation and some vendors play funny tricks because they are allowed to.

These four issues made it impossible for AutoGen to ship without its own implementation of the `printf' formatting routines. Since we were forced to do this, we decided to make the formatting routines both better and more complete :-). We addressed these issues and added the following features to the common printf API:

  1. The formatted output can be written to

    • a string allocated by the formatting function (`asprintf()').
    • a file descriptor instead of a file stream (`dprintf()').
    • a user specified stream (`stream_printf()').

  2. The formatting functions can be augmented with your own functions. These functions are allowed to consume more than one character from the format, but must commence with a unique character. For example,

    "%{struct stat}\n"

    might be used with '{' registered to a procedure that would look up "struct stat" in a symbol table and do appropriate things, consuming the format string through the '}' character.

Gary V. Vaughan was generous enough to supply this implementation. Many thanks!!

For further details, the reader is referred to the snprintfv documentation. These functions are also available in the template processing as `sprintf' (see section 3.5.23 `sprintf' - format a string), `printf' (see section 3.5.18 `printf' - format to stdout), `fprintf' (see section 3.5.5 `fprintf' - format to a file), and `shellf' (see section 3.5.22 `shellf' - format a string, run shell).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. Some ideas for the future.

Here are some things that might happen in the distant future.

  • Write code for "AutoGetopts" (GNU getopt), or possibly the new glibc argp parser.

  • Fix up current tools that contain miserably complex perl, shell, sed, awk and m4 scripts to instead use this tool.
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Concept Index

Jump to: # .
A B C D E F G H I K L M N O P Q R S T U V W X

 | Index Entry | Section
# |  |
 | #define | 2.5 Controlling What Gets Processed
 | #elif | 2.5 Controlling What Gets Processed
 | #else | 2.5 Controlling What Gets Processed
 | #endif | 2.5 Controlling What Gets Processed
 | #endshell | 2.5 Controlling What Gets Processed
 | #error | 2.5 Controlling What Gets Processed
 | #if | 2.5 Controlling What Gets Processed
 | #ifdef | 2.5 Controlling What Gets Processed
 | #ifndef | 2.5 Controlling What Gets Processed
 | #include | 2.5 Controlling What Gets Processed
 | #line | 2.5 Controlling What Gets Processed
 | #shell | 2.5 Controlling What Gets Processed
 | #undef | 2.5 Controlling What Gets Processed
. |  |
 | .def file | 2. AutoGen Definitions File
 | .tpl file | 3. AutoGen Template
 | .tpl, file name | 2.1 The Identification Definition
A |  |
 | allow-errors | 7.4.1 Program Description Attributes
 | Alternate Definition | 2.10 Alternate Definition Forms
 | arg-default | 7.4.2.6 Option Argument Specification
 | arg-optional | 7.4.2.6 Option Argument Specification
 | arg-range | 7.4.2.6 Option Argument Specification
 | arg-type | 7.4.2.6 Option Argument Specification
 | argument | 7.4.1 Program Description Attributes
 | Augmenting AutoGen | 4. Augmenting AutoGen Features
 | AutoEvents | 8.3 Automated Event Management
 | AutoFSM | 8.1 Automated Finite State Machine
 | autogen invocation | 5. Invoking autogen
 | autogen usage | 5.1 autogen usage help (-?)
 | autogen-base-name | 5.5 base-name option (-b)
 | autogen-define | 5.20 define option (-D)
 | autogen-definitions | 5.6 definitions option
 | autogen-equate | 5.12 equate option
 | autogen-lib-template | 5.4 lib-template option (-l)
 | autogen-load-functions | 5.8 load-functions option (-F)
 | autogen-load-scheme | 5.7 load-scheme option (-S)
 | autogen-loop-limit | 5.14 loop-limit option
 | autogen-override-tpl | 5.3 override-tpl option (-T)
 | autogen-select-suffix | 5.10 select-suffix option (-o)
 | autogen-show-defs | 5.18 show-defs option
 | autogen-show-shell | 5.19 show-shell option
 | autogen-skip-suffix | 5.9 skip-suffix option (-s)
 | autogen-source-time | 5.11 source-time option
 | autogen-templ-dirs | 5.2 templ-dirs option (-L)
 | autogen-timeout | 5.15 timeout option (-t)
 | autogen-trace | 5.16 trace option
 | autogen-trace-out | 5.17 trace-out option
 | autogen-undefine | 5.21 undefine option (-U)
 | autogen-writable | 5.13 writable option
 | AutoInfo | 7.9 Automated Info Docs
 | AutoMan pages | 7.10 Automated Man Pages
 | automatic options | 7.4.4 Automatically Supported Options
 | autoopts | 7. Automated Option Processing
 | AutoOpts API | 7.5 Programmatic Interface
 | AutoXDR | 8.2 Combined RPC Marshalling
B |  |
 | before-guile-boot | 7.4.1 Program Description Attributes
C |  |
 | call-proc | 7.4.2.7 Option Argument Handling
 | columns invocation | 8.4 Invoking columns
 | columns usage | 8.4.1 columns usage help (-?)
 | columns-by-columns | 8.4.13 by-columns option
 | columns-col-width | 8.4.4 col-width option (-w)
 | columns-columns | 8.4.3 columns option (-c)
 | columns-first-indent | 8.4.7 first-indent option
 | columns-format | 8.4.10 format option (-f)
 | columns-indent | 8.4.6 indent option (-I)
 | columns-input | 8.4.14 input option (-i)
 | columns-line-separation | 8.4.12 line-separation option
 | columns-separation | 8.4.11 separation option (-S)
 | columns-sort | 8.4.9 sort option (-s)
 | columns-spread | 8.4.5 spread option
 | columns-tab-width | 8.4.8 tab-width option
 | columns-width | 8.4.2 width option (-W)
 | comments | 2.7 Commenting Your Definitions
 | Common Option Attributes | 7.4.2.2 Common Option Attributes
 | compound definitions | 2.2 Named Definitions
 | concat-string | 2.2.8 Concatenated Strings
 | conditional emit | 3.6.14 IF - Conditionally Emit a Template Block
 | conditional emit | 3.6.19 WHILE - Conditionally loop over a Template Block
 | config-header | 7.4.1 Program Description Attributes
 | configuring | 6.1 Configuring AutoGen
 | copyright | 7.4.1 Program Description Attributes
D |  |
 | default | 7.4.2.6 Option Argument Specification
 | define directive | 2.5 Controlling What Gets Processed
 | define macro | 3.6.4 DEFINE - Define a user AutoGen macro
 | Definition Index | 2.3 Assigning an Index to a Definition
 | definitions | 2.2 Named Definitions
 | definitions file | 2. AutoGen Definitions File
 | descrip | 7.4.2.1 Required Attributes
 | design goals | 1.1 The Purpose of AutoGen
 | detail | 7.4.1 Program Description Attributes
 | directives | 2.5 Controlling What Gets Processed
 | disable | 7.4.2.2 Common Option Attributes
 | documentation | 7.4.2.3 Special Option Handling
 | documentation attributes | 7.4.3 Man and Info doc Attributes
 | Dynamic Definition Text | 2.4 Dynamic Text
E |  |
 | elif directive | 2.5 Controlling What Gets Processed
 | else directive | 2.5 Controlling What Gets Processed
 | enable | 7.4.2.2 Common Option Attributes
 | enabled | 7.4.2.2 Common Option Attributes
 | endif directive | 2.5 Controlling What Gets Processed
 | endshell directive | 2.5 Controlling What Gets Processed
 | environrc | 7.4.1 Program Description Attributes
 | equivalence | 7.4.2.3 Special Option Handling
 | error directive | 2.5 Controlling What Gets Processed
 | example, simple | 1.2 A Simple Example
 | explain | 7.4.1 Program Description Attributes
 | export | 7.4.1 Program Description Attributes
 | expression syntax | 3.3 Macro Expression Syntax
 | extract-code | 7.4.2.7 Option Argument Handling
F |  |
 | features | 7.1 AutoOpts Features
 | finite state machine | 8.1 Automated Finite State Machine
 | flag-code | 7.4.2.7 Option Argument Handling
 | flag-proc | 7.4.2.7 Option Argument Handling
 | flags-cant | 7.4.2.5 Option Conflict Attributes
 | flags-must | 7.4.2.5 Option Conflict Attributes
 | fOptState | 7.5.1 Data for Option Processing
 | for loop | 3.6.13 FOR - Emit a template block multiple times
 | futures | 9. Some ideas for the future.
G |  |
 | getdefs invocation | 8.5 Invoking getdefs
 | getdefs usage | 8.5.1 getdefs usage help
 | getdefs-agarg | 8.5.17 agarg option
 | getdefs-assign | 8.5.9 assign option
 | getdefs-autogen | 8.5.15 autogen option
 | getdefs-base-name | 8.5.18 base-name option
 | getdefs-common-assign | 8.5.10 common-assign option
 | getdefs-copy | 8.5.11 copy option
 | getdefs-defs-to-get | 8.5.2 defs-to-get option
 | getdefs-filelist | 8.5.8 filelist option
 | getdefs-first-index | 8.5.4 first-index option
 | getdefs-input | 8.5.5 input option
 | getdefs-linenum | 8.5.13 linenum option
 | getdefs-listattr | 8.5.7 listattr option
 | getdefs-ordering | 8.5.3 ordering option
 | getdefs-output | 8.5.14 output option
 | getdefs-srcfile | 8.5.12 srcfile option
 | getdefs-subblock | 8.5.6 subblock option
 | getdefs-template | 8.5.16 template option
 | guile-main | 7.4.1 Program Description Attributes
H |  |
 | here-string | 2.2.7 A Here String
 | homerc | 7.4.1 Program Description Attributes
I |  |
 | identification | 2.1 The Identification Definition
 | if directive | 2.5 Controlling What Gets Processed
 | if test | 3.6.14 IF - Conditionally Emit a Template Block
 | ifdef directive | 2.5 Controlling What Gets Processed
 | ifndef directive | 2.5 Controlling What Gets Processed
 | immed_disable | 7.4.2.4 Immediate Action Attributes
 | immediate | 7.4.2.4 Immediate Action Attributes
 | immediate action | 7.4.2.4 Immediate Action Attributes
 | include | 7.4.1 Program Description Attributes
 | include directive | 2.5 Controlling What Gets Processed
 | Installing | 6.4 Installing AutoGen
 | Introduction | 1. Introduction
K |  |
 | keyword | 7.4.2.6 Option Argument Specification
L |  |
 | line directive | 2.5 Controlling What Gets Processed
 | loading rc files | loading rc files
 | long-opts | 7.4.1 Program Description Attributes
 | looping, for | 3.6.13 FOR - Emit a template block multiple times
M |  |
 | m4 | 1.4 A User's Perspective
 | macro syntax | 3.6.1 AutoGen Macro Syntax
 | macro, pseudo | 3. AutoGen Template
 | man-doc | 7.4.3 Man and Info doc Attributes
 | max | 7.4.2.2 Common Option Attributes
 | min | 7.4.2.2 Common Option Attributes
 | must-set | 7.4.2.2 Common Option Attributes
N |  |
 | name | 7.4.2.1 Required Attributes
 | named option mode | 7.4.1 Program Description Attributes
 | naming values | 3.2 Naming a value
 | native macros | 3.6 AutoGen Native Macros
 | no-preset | 7.4.2.3 Special Option Handling
O |  |
 | optActualIndex | 7.5.1 Data for Option Processing
 | optActualValue | 7.5.1 Data for Option Processing
 | optIndex | 7.5.1 Data for Option Processing
 | Option Argument Handling | 7.4.2.7 Option Argument Handling
 | option argument name | 7.4.3 Man and Info doc Attributes
 | Option Arguments | 7.4.2.6 Option Argument Specification
 | option attributes | 7.4.2 Option Attributes
 | Option Conflict Attributes | 7.4.2.5 Option Conflict Attributes
 | Option Definitions | 7.4 Option Definitions
 | option descriptor | 7.6 Option Descriptor File
 | option documentation | 7.4.3 Man and Info doc Attributes
 | Option Processing Data | 7.5.1 Data for Option Processing
 | optionLoadLine | process a text string for options
 | optOccCt | 7.5.1 Data for Option Processing
 | opts-ptr | 7.4.1 Program Description Attributes
 | optValue | 7.5.1 Data for Option Processing
P |  |
 | predefines | 2.6 Pre-defined Names
 | prefix | 7.4.1 Program Description Attributes
 | preserve-case | 7.4.1 Program Description Attributes
 | prog-desc | 7.4.1 Program Description Attributes
 | prog-info-descrip | 7.4.3 Man and Info doc Attributes
 | prog-man-descrip | 7.4.3 Man and Info doc Attributes
 | prog-name | 7.4.1 Program Description Attributes
 | prog-title | 7.4.1 Program Description Attributes
 | program attributes | 7.4.1 Program Description Attributes
 | pseudo macro | 3. AutoGen Template
 | pseudo macro | 3.1 Format of the Pseudo Macro
 | pzLastArg | 7.5.1 Data for Option Processing
 | pzProgName | 7.5.1 Data for Option Processing
 | pzProgPath | 7.5.1 Data for Option Processing
Q |  |
 | Quick Start | 7.3 Quick Start
R |  |
 | rcfile | 7.4.1 Program Description Attributes
 | rcsection | 7.4.1 Program Description Attributes
 | Redirecting Output | 3.7 Redirecting Output
 | remote procedure call | 8.2 Combined RPC Marshalling
 | Required Attributes | 7.4.2.1 Required Attributes
 | RPC | 8.2 Combined RPC Marshalling
 | rpcgen | 8.2 Combined RPC Marshalling
S |  |
 | saving rc files | saving rc files
 | settable | 7.4.2.3 Special Option Handling
 | shell directive | 2.5 Controlling What Gets Processed
 | shell options | 7.8 AutoOpts for Shell Scripts
 | shell-generated string | 2.2.4 Shell Output String
 | Signal Names | 6.3 Signal Names
 | simple definitions | 2.2 Named Definitions
 | simple example | 1.2 A Simple Example
 | Special Option Handling | 7.4.2.3 Special Option Handling
 | stack-arg | 7.4.2.7 Option Argument Handling
 | standard options | 7.4.5 Library of Standard Options
 | string, double quote | 2.2.2 Double Quote String
 | string, shell output | 2.2.4 Shell Output String
 | string, single quote | 2.2.3 Single Quote String
T |  |
 | template file | 3. AutoGen Template
 | template, file name | 2.1 The Identification Definition
 | test-main | 7.4.1 Program Description Attributes
 | tpl, file name | 2.1 The Identification Definition
U |  |
 | undef directive | 2.5 Controlling What Gets Processed
 | usage | 7.4.1 Program Description Attributes
 | using AutoOpts | 7.7 Using AutoOpts
V |  |
 | value | 7.4.2.2 Common Option Attributes
 | version | 7.4.1 Program Description Attributes
W |  |
 | while test | 3.6.19 WHILE - Conditionally loop over a Template Block
X |  |
 | XDR | 8.2 Combined RPC Marshalling

Jump to: # .
A B C D E F G H I K L M N O P Q R S T U V W X

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Function Index

Jump to: * = ~
A B C D E F G H I J K L M O P R S T U V W

 | Index Entry | Section
* |  |
 | *= | 3.5.32 `string-ends-eqv?' - caseless string ending
 | *=* | 3.5.26 `string-contains-eqv?' - caseless substring
 | *== | 3.5.33 `string-ends-with?' - string ending
 | *==* | 3.5.27 `string-contains?' - substring match
 | *~ | 3.5.30 `string-end-eqv-match?' - caseless regex ending
 | *~* | 3.5.37 `string-has-eqv-match?' - caseless regex contains
 | *~~ | 3.5.31 `string-end-match?' - regex match end
 | *~~* | 3.5.38 `string-has-match?' - contained regex match
= |  |
 | = | 3.5.36 `string-eqv?' - caseless string match
 | =* | 3.5.42 `string-starts-eqv?' - caseless string start
 | == | 3.5.34 `string-equals?' - string matching
 | ==* | 3.5.43 `string-starts-with?' - string starting
~ |  |
 | ~ | 3.5.35 `string-eqv-match?' - caseless regex match
 | ~* | 3.5.40 `string-start-eqv-match?' - caseless regex start
 | ~~ | 3.5.39 `string-match?' - regex match
 | ~~* | 3.5.41 `string-start-match?' - regex match start
A |  |
 | ag-function? | 3.4.1 `ag-function?' - test for function
 | autogen-version | 3.5.53 `autogen-version' - autogen version number
B |  |
 | base-name | 3.4.2 `base-name' - base output name
 | bsd | 3.5.1 `bsd' - BSD Public License
C |  |
 | c-string | 3.5.2 `c-string' - emit string for ANSI C
 | CASE | 3.6.2 CASE - Select one of several template blocks
 | CLEAR_OPT | 7.5.2 CLEAR_OPT( <NAME> ) - Clear Option Markings
 | COMMENT | 3.6.3 COMMENT - A block of comment to be ignored
 | count | 3.4.3 `count' - definition count
 | COUNT_OPT | 7.5.3 COUNT_OPT( <NAME> ) - Definition Count
D |  |
 | def-file | 3.4.4 `def-file' - definitions file name
 | DEFINE | 3.6.4 DEFINE - Define a user AutoGen macro
 | DESC | 7.5.4 DESC( <NAME> ) - Option Descriptor
 | DISABLE_OPT_name | 7.5.5 DISABLE_OPT_name - Disable an option
 | dne | 3.4.5 `dne' - "Do Not Edit" warning
E |  |
 | ELIF | 3.6.5 ELIF - Alternate Conditional Template Block
 | ELSE | 3.6.6 ELSE - Alternate Template Block
 | ENABLED | 7.5.6 ENABLED( <NAME> ) - Is Option Enabled?
 | ENDDEF | 3.6.7 ENDDEF - Ends a macro definition.
 | ENDFOR | 3.6.8 ENDFOR - Terminates the FOR function template block
 | ENDIF | 3.6.9 ENDIF - Terminate the IF Template Block
 | ENDWHILE | 3.6.10 ENDWHILE - Terminate the WHILE Template Block
 | error | 3.4.6 `error' - display message and exit
 | error-source-line | 3.5.3 `error-source-line' - display of file & line
 | ERRSKIP_OPTERR | 7.5.7 ERRSKIP_OPTERR - Ignore Option Errors
 | ERRSTOP_OPTERR | 7.5.8 ERRSTOP_OPTERR - Stop on Errors
 | ESAC | 3.6.11 ESAC - Terminate the CASE Template Block
 | exist? | 3.4.7 `exist?' - test for value name
 | EXPR | 3.6.12 EXPR - Evaluate and emit an Expression
 | extract | 3.5.4 `extract' - extract text from another file
F |  |
 | find-file | 3.4.8 `find-file' - locate a file in the search path
 | first-for? | 3.4.9 `first-for?' - detect first iteration
 | FOR | 3.6.13 FOR - Emit a template block multiple times
 | for-by | 3.4.10 `for-by' - set iteration step
 | for-from | 3.4.11 `for-from' - set initial index
 | for-index | 3.4.12 `for-index' - get current loop index
 | for-sep | 3.4.13 `for-sep' - set loop separation string
 | for-to | 3.4.14 `for-to' - set ending index
 | fprintf | 3.5.5 `fprintf' - format to a file
G |  |
 | get | 3.4.15 `get' - get named value
 | gperf | 3.5.6 `gperf' - perform a perfect hash function
 | gpl | 3.5.7 `gpl' - GNU General Public License
H |  |
 | HAVE_OPT | 7.5.9 HAVE_OPT( <NAME> ) - Have this option?
 | header-file | 3.5.52 `make-header-guard' - make self-inclusion guard
 | header-guard | 3.5.52 `make-header-guard' - make self-inclusion guard
 | high-lim | 3.4.16 `high-lim' - get highest value index
I |  |
 | IF | 3.6.14 IF - Conditionally Emit a Template Block
 | in? | 3.5.8 `in?' - test for string in list
 | INCLUDE | 3.6.15 INCLUDE - Read in and emit a template block
 | INVOKE | 3.6.16 INVOKE - Invoke a User Defined Macro
 | ISSEL_OPT | 7.5.10 ISSEL_OPT( <NAME> ) - Is Option Selected?
 | ISUNUSED_OPT | 7.5.11 ISUNUSED_OPT( <NAME> ) - Never Specified?
J |  |
 | join | 3.5.9 `join' - join string list with separator
K |  |
 | kr-string | 3.5.10 `kr-string' - emit string for K&R C
L |  |
 | last-for? | 3.4.17 `last-for?' - detect last iteration
 | len | 3.4.18 `len' - get count of values
 | lgpl | 3.5.11 `lgpl' - GNU Library General Public License
 | license | 3.5.12 `license' - an arbitrary license
 | low-lim | 3.4.19 `low-lim' - get lowest value index
M |  |
 | make-gperf | 3.5.13 `make-gperf' - build a perfect hash function program
 | make-header-guard | 3.5.52 `make-header-guard' - make self-inclusion guard
 | makefile-script | 3.5.14 `makefile-script' - create makefile script
 | match-value? | 3.4.20 `match-value?' - test for matching value
 | max | 3.5.15 `max' - maximum value in list
 | min | 3.5.16 `min' - minimum value in list
O |  |
 | OPT_ARG | 7.5.13 OPT_ARG( <NAME> ) - Option Argument String
 | OPT_VALUE_name | 7.5.14 OPT_VALUE_name - Option Argument Value
 | OPTION_CT | 7.5.12 OPTION_CT - Full Count of Options
 | optionFree | 7.5.28.1 optionFree
 | optionLoadLine | 7.5.28.2 optionLoadLine
 | optionProcess | 7.5.28.3 optionProcess
 | optionRestore | 7.5.28.4 optionRestore
 | optionSaveFile | 7.5.28.5 optionSaveFile
 | optionSaveState | 7.5.28.6 optionSaveState
 | optionVersion | 7.5.28.7 optionVersion
 | out-delete | 3.4.21 `out-delete' - delete current output file
 | out-depth | 3.4.22 `out-depth' - output file stack depth
 | out-move | 3.4.23 `out-move' - change name of output file
 | out-name | 3.4.24 `out-name' - current output file name
 | out-pop | 3.4.25 `out-pop' - close current output file
 | out-push-add | 3.4.26 `out-push-add' - append output to file
 | out-push-new | 3.4.27 `out-push-new' - purge and create output file
 | out-resume | 3.4.28 `out-resume' - resume current output file
 | out-suspend | 3.4.29 `out-suspend' - suspend current output file
 | out-switch | 3.4.30 `out-switch' - close and create new output
P |  |
 | prefix | 3.5.17 `prefix' - prefix lines with a string
 | printf | 3.5.18 `printf' - format to stdout
R |  |
 | raw-shell-str | 3.5.19 `raw-shell-str' - single quote shell string
 | RESTART_OPT | 7.5.15 RESTART_OPT( n ) - Resume Option Processing
S |  |
 | SELECT | 3.6.17 SELECT - Selection block for CASE function
 | set-writable | 3.4.31 `set-writable' - Make the output file be writable
 | SET_OPT_name | 7.5.16 SET_OPT_name - Force an option to be set
 | shell | 3.5.20 `shell' - invoke a shell script
 | shell-str | 3.5.21 `shell-str' - double quote shell string
 | shellf | 3.5.22 `shellf' - format a string, run shell
 | sprintf | 3.5.23 `sprintf' - format a string
 | stack | 3.4.32 `stack' - make list of AutoGen values
 | STACKCT_OPT | 7.5.17 STACKCT_OPT( <NAME> ) - Stacked Arg Count
 | STACKLST_OPT | 7.5.18 STACKLST_OPT( <NAME> ) - Argument Stack
 | START_OPT | 7.5.19 START_OPT - Restart Option Processing
 | STATE_OPT | 7.5.20 STATE_OPT( <NAME> ) - Option State
 | string->c-name! | 3.5.45 `string->c-name!' - map non-name chars to underscore
 | string-capitalize | 3.5.24 `string-capitalize' - capitalize a new string
 | string-capitalize! | 3.5.25 `string-capitalize!' - capitalize a string
 | string-contains-eqv? | 3.5.26 `string-contains-eqv?' - caseless substring
 | string-contains? | 3.5.27 `string-contains?' - substring match
 | string-downcase | 3.5.28 `string-downcase' - lower case a new string
 | string-downcase! | 3.5.29 `string-downcase!' - make a string be lower case
 | string-end-eqv-match? | 3.5.30 `string-end-eqv-match?' - caseless regex ending
 | string-end-match? | 3.5.31 `string-end-match?' - regex match end
 | string-ends-eqv? | 3.5.32 `string-ends-eqv?' - caseless string ending
 | string-ends-with? | 3.5.33 `string-ends-with?' - string ending
 | string-equals? | 3.5.34 `string-equals?' - string matching
 | string-eqv-match? | 3.5.35 `string-eqv-match?' - caseless regex match
 | string-eqv? | 3.5.36 `string-eqv?' - caseless string match
 | string-has-eqv-match? | 3.5.37 `string-has-eqv-match?' - caseless regex contains
 | string-has-match? | 3.5.38 `string-has-match?' - contained regex match
 | string-match? | 3.5.39 `string-match?' - regex match
 | string-start-eqv-match? | 3.5.40 `string-start-eqv-match?' - caseless regex start
 | string-start-match? | 3.5.41 `string-start-match?' - regex match start
 | string-starts-eqv? | 3.5.42 `string-starts-eqv?' - caseless string start
 | string-starts-with? | 3.5.43 `string-starts-with?' - string starting
 | string-substitute | 3.5.44 `string-substitute' - multiple global replacements
 | string-tr | 3.5.46 `string-tr' - convert characters with new result
 | string-tr! | 3.5.47 `string-tr!' - convert characters
 | string-upcase | 3.5.48 `string-upcase' - upper case a new string
 | string-upcase! | 3.5.49 `string-upcase!' - make a string be upper case
 | sub-shell-str | 3.5.50 `sub-shell-str' - back quoted (sub-)shell string
 | suffix | 3.4.33 `suffix' - get the current suffix
 | sum | 3.5.51 `sum' - sum of values in list
T |  |
 | teOptIndex | 7.5.26 teOptIndex - Option Index and Enumeration
 | tpl-file | 3.4.34 `tpl-file' - get the template file name
 | tpl-file-line | 3.4.35 `tpl-file-line' - get the template file and line number
U |  |
 | UNKNOWN | 3.6.18 UNKNOWN - Either a user macro or a value name.
 | USAGE | 7.5.21 USAGE( exit-code ) - Usage invocation macro
V |  |
 | VALUE_OPT_name | 7.5.22 VALUE_OPT_name - Option Flag Value
 | VERSION | 7.5.23 VERSION - Version and Full Version
W |  |
 | WHICH_IDX_name | 7.5.24 WHICH_IDX_name - Which Equivalenced Index
 | WHICH_OPT_name | 7.5.25 WHICH_OPT_name - Which Equivalenced Option
 | WHILE | 3.6.19 WHILE - Conditionally loop over a Template Block

Jump to: * = ~
A B C D E F G H I J K L M O P R S T U V W

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Introduction
      1.1 The Purpose of AutoGen
      1.2 A Simple Example
      1.3 csh/zsh caveat
      1.4 A User's Perspective
    2. AutoGen Definitions File
      2.1 The Identification Definition
      2.2 Named Definitions
        2.2.1 Definition List
        2.2.2 Double Quote String
        2.2.3 Single Quote String
        2.2.4 Shell Output String
        2.2.5 An Unquoted String
        2.2.6 Scheme Result String
        2.2.7 A Here String
        2.2.8 Concatenated Strings
      2.3 Assigning an Index to a Definition
      2.4 Dynamic Text
      2.5 Controlling What Gets Processed
      2.6 Pre-defined Names
      2.7 Commenting Your Definitions
      2.8 What it all looks like.
      2.9 YACC Language Grammar
      2.10 Alternate Definition Forms
    3. AutoGen Template
      3.1 Format of the Pseudo Macro
      3.2 Naming a value
      3.3 Macro Expression Syntax
        3.3.1 Apply Code
        3.3.2 Basic Expression
      3.4 AutoGen Scheme Functions
        3.4.1 `ag-function?' - test for function
        3.4.2 `base-name' - base output name
        3.4.3 `count' - definition count
        3.4.4 `def-file' - definitions file name
        3.4.5 `dne' - "Do Not Edit" warning
        3.4.6 `error' - display message and exit
        3.4.7 `exist?' - test for value name
        3.4.8 `find-file' - locate a file in the search path
        3.4.9 `first-for?' - detect first iteration
        3.4.10 `for-by' - set iteration step
        3.4.11 `for-from' - set initial index
        3.4.12 `for-index' - get current loop index
        3.4.13 `for-sep' - set loop separation string
        3.4.14 `for-to' - set ending index
        3.4.15 `get' - get named value
        3.4.16 `high-lim' - get highest value index
        3.4.17 `last-for?' - detect last iteration
        3.4.18 `len' - get count of values
        3.4.19 `low-lim' - get lowest value index
        3.4.20 `match-value?' - test for matching value
        3.4.21 `out-delete' - delete current output file
        3.4.22 `out-depth' - output file stack depth
        3.4.23 `out-move' - change name of output file
        3.4.24 `out-name' - current output file name
        3.4.25 `out-pop' - close current output file
        3.4.26 `out-push-add' - append output to file
        3.4.27 `out-push-new' - purge and create output file
        3.4.28 `out-resume' - resume current output file
        3.4.29 `out-suspend' - suspend current output file
        3.4.30 `out-switch' - close and create new output
        3.4.31 `set-writable' - Make the output file be writable
        3.4.32 `stack' - make list of AutoGen values
        3.4.33 `suffix' - get the current suffix
        3.4.34 `tpl-file' - get the template file name
        3.4.35 `tpl-file-line' - get the template file and line number
      3.5 Common Scheme Functions
        3.5.1 `bsd' - BSD Public License
        3.5.2 `c-string' - emit string for ANSI C
        3.5.3 `error-source-line' - display of file & line
        3.5.4 `extract' - extract text from another file
        3.5.5 `fprintf' - format to a file
        3.5.6 `gperf' - perform a perfect hash function
        3.5.7 `gpl' - GNU General Public License
        3.5.8 `in?' - test for string in list
        3.5.9 `join' - join string list with separator
        3.5.10 `kr-string' - emit string for K&R C
        3.5.11 `lgpl' - GNU Library General Public License
        3.5.12 `license' - an arbitrary license
        3.5.13 `make-gperf' - build a perfect hash function program
        3.5.14 `makefile-script' - create makefile script
        3.5.15 `max' - maximum value in list
        3.5.16 `min' - minimum value in list
        3.5.17 `prefix' - prefix lines with a string
        3.5.18 `printf' - format to stdout
        3.5.19 `raw-shell-str' - single quote shell string
        3.5.20 `shell' - invoke a shell script
        3.5.21 `shell-str' - double quote shell string
        3.5.22 `shellf' - format a string, run shell
        3.5.23 `sprintf' - format a string
        3.5.24 `string-capitalize' - capitalize a new string
        3.5.25 `string-capitalize!' - capitalize a string
        3.5.26 `string-contains-eqv?' - caseless substring
        3.5.27 `string-contains?' - substring match
        3.5.28 `string-downcase' - lower case a new string
        3.5.29 `string-downcase!' - make a string be lower case
        3.5.30 `string-end-eqv-match?' - caseless regex ending
        3.5.31 `string-end-match?' - regex match end
        3.5.32 `string-ends-eqv?' - caseless string ending
        3.5.33 `string-ends-with?' - string ending
        3.5.34 `string-equals?' - string matching
        3.5.35 `string-eqv-match?' - caseless regex match
        3.5.36 `string-eqv?' - caseless string match
        3.5.37 `string-has-eqv-match?' - caseless regex contains
        3.5.38 `string-has-match?' - contained regex match
        3.5.39 `string-match?' - regex match
        3.5.40 `string-start-eqv-match?' - caseless regex start
        3.5.41 `string-start-match?' - regex match start
        3.5.42 `string-starts-eqv?' - caseless string start
        3.5.43 `string-starts-with?' - string starting
        3.5.44 `string-substitute' - multiple global replacements
        3.5.45 `string->c-name!' - map non-name chars to underscore
        3.5.46 `string-tr' - convert characters with new result
        3.5.47 `string-tr!' - convert characters
        3.5.48 `string-upcase' - upper case a new string
        3.5.49 `string-upcase!' - make a string be upper case
        3.5.50 `sub-shell-str' - back quoted (sub-)shell string
        3.5.51 `sum' - sum of values in list
        3.5.52 `make-header-guard' - make self-inclusion guard
        3.5.53 `autogen-version' - autogen version number
      3.6 AutoGen Native Macros
        3.6.1 AutoGen Macro Syntax
        3.6.2 CASE - Select one of several template blocks
        3.6.3 COMMENT - A block of comment to be ignored
        3.6.4 DEFINE - Define a user AutoGen macro
        3.6.5 ELIF - Alternate Conditional Template Block
        3.6.6 ELSE - Alternate Template Block
        3.6.7 ENDDEF - Ends a macro definition.
        3.6.8 ENDFOR - Terminates the FOR function template block
        3.6.9 ENDIF - Terminate the IF Template Block
        3.6.10 ENDWHILE - Terminate the WHILE Template Block
        3.6.11 ESAC - Terminate the CASE Template Block
        3.6.12 EXPR - Evaluate and emit an Expression
        3.6.13 FOR - Emit a template block multiple times
        3.6.14 IF - Conditionally Emit a Template Block
        3.6.15 INCLUDE - Read in and emit a template block
        3.6.16 INVOKE - Invoke a User Defined Macro
        3.6.17 SELECT - Selection block for CASE function
        3.6.18 UNKNOWN - Either a user macro or a value name.
        3.6.19 WHILE - Conditionally loop over a Template Block
      3.7 Redirecting Output
    4. Augmenting AutoGen Features
      4.1 Shell Output Commands
      4.2 Guile Macros
      4.3 Guile Callout Functions
      4.4 AutoGen Macros
    5. Invoking autogen
      5.1 autogen usage help (-?)
      5.2 templ-dirs option (-L)
      5.3 override-tpl option (-T)
      5.4 lib-template option (-l)
      5.5 base-name option (-b)
      5.6 definitions option
      5.7 load-scheme option (-S)
      5.8 load-functions option (-F)
      5.9 skip-suffix option (-s)
      5.10 select-suffix option (-o)
      5.11 source-time option
      5.12 equate option
      5.13 writable option
      5.14 loop-limit option
      5.15 timeout option (-t)
      5.16 trace option
      5.17 trace-out option
      5.18 show-defs option
      5.19 show-shell option
      5.20 define option (-D)
      5.21 undefine option (-U)
    6. Configuring and Installing
      6.1 Configuring AutoGen
      6.2 AutoGen as a CGI server
      6.3 Signal Names
      6.4 Installing AutoGen
    7. Automated Option Processing
      7.1 AutoOpts Features
        loading rc files
        saving rc files
        process a text string for options
      7.2 Competitive Feature Analysis
      7.3 Quick Start
      7.4 Option Definitions
        7.4.1 Program Description Attributes
        7.4.2 Option Attributes
          7.4.2.1 Required Attributes
          7.4.2.2 Common Option Attributes
          7.4.2.3 Special Option Handling
          7.4.2.4 Immediate Action Attributes
          7.4.2.5 Option Conflict Attributes
          7.4.2.6 Option Argument Specification
          7.4.2.7 Option Argument Handling
        7.4.3 Man and Info doc Attributes
        7.4.4 Automatically Supported Options
        7.4.5 Library of Standard Options
      7.5 Programmatic Interface
        7.5.1 Data for Option Processing
        7.5.2 CLEAR_OPT( <NAME> ) - Clear Option Markings
        7.5.3 COUNT_OPT( <NAME> ) - Definition Count
        7.5.4 DESC( <NAME> ) - Option Descriptor
        7.5.5 DISABLE_OPT_name - Disable an option
        7.5.6 ENABLED( <NAME> ) - Is Option Enabled?
        7.5.7 ERRSKIP_OPTERR - Ignore Option Errors
        7.5.8 ERRSTOP_OPTERR - Stop on Errors
        7.5.9 HAVE_OPT( <NAME> ) - Have this option?
        7.5.10 ISSEL_OPT( <NAME> ) - Is Option Selected?
        7.5.11 ISUNUSED_OPT( <NAME> ) - Never Specified?
        7.5.12 OPTION_CT - Full Count of Options
        7.5.13 OPT_ARG( <NAME> ) - Option Argument String
        7.5.14 OPT_VALUE_name - Option Argument Value
        7.5.15 RESTART_OPT( n ) - Resume Option Processing
        7.5.16 SET_OPT_name - Force an option to be set
        7.5.17 STACKCT_OPT( <NAME> ) - Stacked Arg Count
        7.5.18 STACKLST_OPT( <NAME> ) - Argument Stack
        7.5.19 START_OPT - Restart Option Processing
        7.5.20 STATE_OPT( <NAME> ) - Option State
        7.5.21 USAGE( exit-code ) - Usage invocation macro
        7.5.22 VALUE_OPT_name - Option Flag Value
        7.5.23 VERSION - Version and Full Version
        7.5.24 WHICH_IDX_name - Which Equivalenced Index
        7.5.25 WHICH_OPT_name - Which Equivalenced Option
        7.5.26 teOptIndex - Option Index and Enumeration
        7.5.27 OPTIONS_STRUCT_VERSION - active version
        7.5.28 libopts External Procedures
          7.5.28.1 optionFree
          7.5.28.2 optionLoadLine
          7.5.28.3 optionProcess
          7.5.28.4 optionRestore
          7.5.28.5 optionSaveFile
          7.5.28.6 optionSaveState
          7.5.28.7 optionVersion
      7.6 Option Descriptor File
      7.7 Using AutoOpts
      7.8 AutoOpts for Shell Scripts
      7.9 Automated Info Docs
        7.9.1 "invoking" info docs
        7.9.2 library info docs
      7.10 Automated Man Pages
        7.10.1 command line man pages
        7.10.2 library man pages
    8. Add-on packages for AutoGen
      8.1 Automated Finite State Machine
      8.2 Combined RPC Marshalling
      8.3 Automated Event Management
      8.4 Invoking columns
        8.4.1 columns usage help (-?)
        8.4.2 width option (-W)
        8.4.3 columns option (-c)
        8.4.4 col-width option (-w)
        8.4.5 spread option
        8.4.6 indent option (-I)
        8.4.7 first-indent option
        8.4.8 tab-width option
        8.4.9 sort option (-s)
        8.4.10 format option (-f)
        8.4.11 separation option (-S)
        8.4.12 line-separation option
        8.4.13 by-columns option
        8.4.14 input option (-i)
      8.5 Invoking getdefs
        8.5.1 getdefs usage help
        8.5.2 defs-to-get option
        8.5.3 ordering option
        8.5.4 first-index option
        8.5.5 input option
        8.5.6 subblock option
        8.5.7 listattr option
        8.5.8 filelist option
        8.5.9 assign option
        8.5.10 common-assign option
        8.5.11 copy option
        8.5.12 srcfile option
        8.5.13 linenum option
        8.5.14 output option
        8.5.15 autogen option
        8.5.16 template option
        8.5.17 agarg option
        8.5.18 base-name option
      8.6 Replacement for Stdio Formatting Library
    9. Some ideas for the future.
    Concept Index
    Function Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Introduction
2. AutoGen Definitions File
3. AutoGen Template
4. Augmenting AutoGen Features
5. Invoking autogen
6. Configuring and Installing
7. Automated Option Processing
8. Add-on packages for AutoGen
9. Some ideas for the future.
Concept Index
Function Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated by Bruce Korb on May, 12 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated by Bruce Korb on May, 12 2002 using texi2html


automake

This file documents the GNU Automake package. Automake is a program which creates GNU standards-compliant Makefiles from template files. This edition documents version 1.6.1.

1. Introduction | Automake's purpose
2. General ideas
3. Some example packages
4. Creating a `Makefile.in' | Creating a Makefile.in
5. Scanning `configure.in' | Scanning configure.ac or configure.in
6. The top-level `Makefile.am' | The top-level Makefile.am
7. An Alternative Approach to Subdirectories | An alternative approach to subdirectories
8. Rebuilding Makefiles | Automatic rebuilding of Makefile
9. Building Programs and Libraries | Building programs and libraries
10. Other Derived Objects | Other derived objects
11. Other GNU Tools
12. Building documentation
13. What Gets Installed | What gets installed
14. What Gets Cleaned | What gets cleaned
15. What Goes in a Distribution | What goes in a distribution
16. Support for test suites
17. Changing Automake's Behavior | Changing Automake's behavior
18. Miscellaneous Rules | Miscellaneous rules
19. Include | Including extra files in an Automake template.
20. Conditionals
21. The effect of --gnu and --gnits
22. The effect of --cygnus
23. When Automake Isn't Enough | Extending Automake
24. Distributing `Makefile.in's | Distributing the Makefile.in
25. Automake API versioning | About compatibility between Automake versions
Macro and Variable Index
General Index

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Introduction

Automake is a tool for automatically generating `Makefile.in's from files called `Makefile.am'. Each `Makefile.am' is basically a series of make macro definitions (with rules being thrown in occasionally). The generated `Makefile.in's are compliant with the GNU Makefile standards.

The GNU Makefile Standards Document (see section `Makefile Conventions' in The GNU Coding Standards) is long, complicated, and subject to change. The goal of Automake is to remove the burden of Makefile maintenance from the back of the individual GNU maintainer (and put it on the back of the Automake maintainer).

The typical Automake input file is simply a series of macro definitions. Each such file is processed to create a `Makefile.in'. There should generally be one `Makefile.am' per directory of a project.

Automake does constrain a project in certain ways; for instance it assumes that the project uses Autoconf (see section `Introduction' in The Autoconf Manual), and enforces certain restrictions on the `configure.in' contents(1).

Automake requires perl in order to generate the `Makefile.in's. However, the distributions created by Automake are fully GNU standards-compliant, and do not require perl in order to be built.

Mail suggestions and bug reports for Automake to bug-automake@gnu.org.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. General ideas

The following sections cover a few basic ideas that will help you understand how Automake works.

2.1 General Operation | General operation of Automake
2.2 Strictness | Standards conformance checking
2.3 The Uniform Naming Scheme
2.4 How derived variables are named
2.5 Variables reserved for the user
2.6 Programs automake might require

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 General Operation

Automake works by reading a `Makefile.am' and generating a `Makefile.in'. Certain macros and targets defined in the `Makefile.am' instruct Automake to generate more specialized code; for instance, a `bin_PROGRAMS' macro definition will cause targets for compiling and linking programs to be generated.

The macro definitions and targets in the `Makefile.am' are copied verbatim into the generated file. This allows you to add arbitrary code into the generated `Makefile.in'. For instance the Automake distribution includes a non-standard cvs-dist target, which the Automake maintainer uses to make distributions from his source control system.

Note that most GNU make extensions are not recognized by Automake. Using such extensions in a `Makefile.am' will lead to errors or confusing behavior.

A special exception is that the GNU make append operator, `+=', is supported. This operator appends its right hand argument to the macro specified on the left. Automake will translate the operator into an ordinary `=' operator; `+=' will thus work with any make program.

Note that it is only valid to append to a macro in the same conditional context as the macro was originally defined. See Conditional Append, for more information.

Automake tries to group comments with adjoining targets and macro definitions in an intelligent way.

A target defined in `Makefile.am' generally overrides any such target of a similar name that would be automatically generated by automake. Although this is a supported feature, it is generally best to avoid making use of it, as sometimes the generated rules are very particular.

Similarly, a macro defined in `Makefile.am' or AC_SUBST'ed from `configure.in' will override any definition of the macro that automake would ordinarily create. This feature is more often useful than the ability to override a target definition. Be warned that many of the macros generated by automake are considered to be for internal use only, and their names might change in future releases.

When examining a macro definition, Automake will recursively examine macros referenced in the definition. For example, if Automake is looking at the content of foo_SOURCES in this snippet

xs = a.c b.c
foo_SOURCES = c.c $(xs)

it would use the files `a.c', `b.c', and `c.c' as the contents of foo_SOURCES.

Automake also allows a form of comment which is not copied into the output; all lines beginning with `##' (leading spaces allowed) are completely ignored by Automake.

It is customary to make the first line of `Makefile.am' read:

## Process this file with automake to produce Makefile.in

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 Strictness

While Automake is intended to be used by maintainers of GNU packages, it does make some effort to accommodate those who wish to use it, but do not want to use all the GNU conventions.

To this end, Automake supports three levels of strictness---the strictness indicating how stringently Automake should check standards conformance.

The valid strictness levels are:

`foreign'
Automake will check for only those things which are absolutely required for proper operations. For instance, whereas GNU standards dictate the existence of a `NEWS' file, it will not be required in this mode. The name comes from the fact that Automake is intended to be used for GNU programs; these relaxed rules are not the standard mode of operation.

`gnu'
Automake will check--as much as possible--for compliance to the GNU standards for packages. This is the default.

`gnits'
Automake will check for compliance to the as-yet-unwritten Gnits standards. These are based on the GNU standards, but are even more detailed. Unless you are a Gnits standards contributor, it is recommended that you avoid this option until such time as the Gnits standard is actually published (which may never happen).

For more information on the precise implications of the strictness level, see 21. The effect of --gnu and --gnits.

Automake also has a special "cygnus" mode which is similar to strictness but handled differently. This mode is useful for packages which are put into a "Cygnus" style tree (e.g., the GCC tree). For more information on this mode, see 22. The effect of --cygnus.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.3 The Uniform Naming Scheme

Automake macros (from here on referred to as variables) generally follow a uniform naming scheme that makes it easy to decide how programs (and other derived objects) are built, and how they are installed. This scheme also supports configure time determination of what should be built.

At make time, certain variables are used to determine which objects are to be built. The variable names are made of several pieces which are concatenated together.

The piece which tells automake what is being built is commonly called the primary. For instance, the primary PROGRAMS holds a list of programs which are to be compiled and linked.

A different set of names is used to decide where the built objects should be installed. These names are prefixes to the primary which indicate which standard directory should be used as the installation directory. The standard directory names are given in the GNU standards (see section `Directory Variables' in The GNU Coding Standards). Automake extends this list with pkglibdir, pkgincludedir, and pkgdatadir; these are the same as the non-`pkg' versions, but with `@PACKAGE@' appended. For instance, pkglibdir is defined as $(libdir)/@PACKAGE@.

For each primary, there is one additional variable named by prepending `EXTRA_' to the primary name. This variable is used to list objects which may or may not be built, depending on what configure decides. This variable is required because Automake must statically know the entire list of objects that may be built in order to generate a `Makefile.in' that will work in all cases.

For instance, cpio decides at configure time which programs are built. Some of the programs are installed in bindir, and some are installed in sbindir:

EXTRA_PROGRAMS = mt rmt
bin_PROGRAMS = cpio pax
sbin_PROGRAMS = @MORE_PROGRAMS@

Defining a primary without a prefix as a variable, e.g., PROGRAMS, is an error.

Note that the common `dir' suffix is left off when constructing the variable names; thus one writes `bin_PROGRAMS' and not `bindir_PROGRAMS'.

Not every sort of object can be installed in every directory. Automake will flag those attempts it finds in error. Automake will also diagnose obvious misspellings in directory names.

Sometimes the standard directories--even as augmented by Automake--- are not enough. In particular it is sometimes useful, for clarity, to install objects in a subdirectory of some predefined directory. To this end, Automake allows you to extend the list of possible installation directories. A given prefix (e.g. `zar') is valid if a variable of the same name with `dir' appended is defined (e.g. zardir).

For instance, until HTML support is part of Automake, you could use this to install raw HTML documentation:

htmldir = $(prefix)/html
html_DATA = automake.html

The special prefix `noinst' indicates that the objects in question should be built but not installed at all. This is usually used for objects required to build the rest of your package, for instance static libraries (see section 9.2 Building a library), or helper scripts.

The special prefix `check' indicates that the objects in question should not be built until the make check command is run. Those objects are not installed either.

The current primary names are `PROGRAMS', `LIBRARIES', `LISP', `PYTHON', `JAVA', `SCRIPTS', `DATA', `HEADERS', `MANS', and `TEXINFOS'.

Some primaries also allow additional prefixes which control other aspects of automake's behavior. The currently defined prefixes are `dist_', `nodist_', and `nobase_'. These prefixes are explained later (see section 9.4 Program and Library Variables).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.4 How derived variables are named

Sometimes a Makefile variable name is derived from some text the maintainer supplies. For instance, a program name listed in `_PROGRAMS' is rewritten into the name of a `_SOURCES' variable. In cases like this, Automake canonicalizes the text, so that program names and the like do not have to follow Makefile macro naming rules. All characters in the name except for letters, numbers, the strudel (@), and the underscore are turned into underscores when making macro references.

For example, if your program is named sniff-glue, the derived variable name would be sniff_glue_SOURCES, not sniff-glue_SOURCES. Similarly the sources for a library named libmumble++.a should be listed in the libmumble___a_SOURCES variable.

The strudel is an addition, to make the use of Autoconf substitutions in macro names less obfuscating.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.5 Variables reserved for the user

Some Makefile variables are reserved by the GNU Coding Standards for the use of the "user" -- the person building the package. For instance, CFLAGS is one such variable.

Sometimes package developers are tempted to set user variables such as CFLAGS because it appears to make their job easier -- they don't have to introduce a second variable into every target.

However, the package itself should never set a user variable, particularly not to include switches which are required for proper compilation of the package. Since these variables are documented as being for the package builder, that person rightfully expects to be able to override any of these variables at build time.

To get around this problem, automake introduces an automake-specific shadow variable for each user flag variable. (Shadow variables are not introduced for variables like CC, where they would make no sense.) The shadow variable is named by prepending `AM_' to the user variable's name. For instance, the shadow variable for YFLAGS is AM_YFLAGS.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.6 Programs automake might require

Automake sometimes requires helper programs so that the generated `Makefile' can do its work properly. There are a fairly large number of them, and we list them here.

ansi2knr.c
ansi2knr.1
These two files are used by the automatic de-ANSI-fication support (see section 9.13 Automatic de-ANSI-fication).

compile
This is a wrapper for compilers which don't accept both `-c' and `-o' at the same time. It is only used when absolutely required. Such compilers are rare.

config.guess
config.sub
These programs compute the canonical triplets for the given build, host, or target architecture. These programs are updated regulary to support new architectures and fix probes broken by changes in new kernel versions. You are encouraged to fetch the latest versions of these files from ftp://ftp.gnu.org/gnu/config/ before making a release.

depcomp
This program understands how to run a compiler so that it will generate not only the desired output but also dependency information which is then used by the automatic dependency tracking feature.

elisp-comp
This program is used to byte-compile Emacs Lisp code.

install-sh
This is a replacement for the install program which works on platforms where install is unavailable or unusable.

mdate-sh
This script is used to generate a `version.texi' file. It examines a file and prints some date information about it.

missing
This wraps a number of programs which are typically only required by maintainers. If the program in question doesn't exist, missing prints an informative warning and attempts to fix things so that the build can continue.

mkinstalldirs
This works around the fact that mkdir -p is not portable.

py-compile
This is used to byte-compile Python scripts.

texinfo.tex
Not a program, this file is required for make dvi to work when Texinfo sources are in the package.

ylwrap
This program wraps lex and yacc and ensures that, for instance, multiple yacc instances can be invoked in a single directory in parallel.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. Some example packages

3.1 A simple example, start to finish
3.2 A classic program
3.3 Building etags and ctags

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 A simple example, start to finish

Let's suppose you just finished writing zardoz, a program to make your head float from vortex to vortex. You've been using Autoconf to provide a portability framework, but your `Makefile.in's have been ad-hoc. You want to make them bulletproof, so you turn to Automake.

The first step is to update your `configure.in' to include the commands that automake needs. The way to do this is to add an AM_INIT_AUTOMAKE call just after AC_INIT:

AC_INIT(zardoz, 1.0)
AM_INIT_AUTOMAKE
...

Since your program doesn't have any complicating factors (e.g., it doesn't use gettext, it doesn't want to build a shared library), you're done with this part. That was easy!

Now you must regenerate `configure'. But to do that, you'll need to tell autoconf how to find the new macro you've used. The easiest way to do this is to use the aclocal program to generate your `aclocal.m4' for you. But wait... maybe you already have an `aclocal.m4', because you had to write some hairy macros for your program. The aclocal program lets you put your own macros into `acinclude.m4', so simply rename and then run:

mv aclocal.m4 acinclude.m4
aclocal
autoconf

Now it is time to write your `Makefile.am' for zardoz. Since zardoz is a user program, you want to install it where the rest of the user programs go: bindir. Additionally, zardoz has some Texinfo documentation. Your `configure.in' script uses AC_REPLACE_FUNCS, so you need to link against `@LIBOBJS@'. So here's what you'd write:

bin_PROGRAMS = zardoz
zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
zardoz_LDADD = @LIBOBJS@

info_TEXINFOS = zardoz.texi

Now you can run automake --add-missing to generate your `Makefile.in' and grab any auxiliary files you might need, and you're done!

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 A classic program

GNU hello is renowned for its classic simplicity and versatility. This section shows how Automake could be used with the GNU Hello package. The examples below are from the latest beta version of GNU Hello, but with all of the maintainer-only code stripped out, as well as all copyright comments.

Of course, GNU Hello is somewhat more featureful than your traditional two-liner. GNU Hello is internationalized, does option processing, and has a manual and a test suite.

Here is the `configure.in' from GNU Hello:

dnl Process this file with autoconf to produce a configure script.
AC_INIT(src/hello.c)
AM_INIT_AUTOMAKE(hello, 1.3.11)
AM_CONFIG_HEADER(config.h)

dnl Set of available languages.
ALL_LINGUAS="de fr es ko nl no pl pt sl sv"

dnl Checks for programs.
AC_PROG_CC
AC_ISC_POSIX

dnl Checks for libraries.

dnl Checks for header files.
AC_STDC_HEADERS
AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)

dnl Checks for library functions.
AC_FUNC_ALLOCA

dnl Check for st_blksize in struct stat
AC_ST_BLKSIZE

dnl internationalization macros
AM_GNU_GETTEXT
AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
           src/Makefile tests/Makefile tests/hello],
   [chmod +x tests/hello])

The `AM_' macros are provided by Automake (or the Gettext library); the rest are standard Autoconf macros.

The top-level `Makefile.am':

EXTRA_DIST = BUGS ChangeLog.O
SUBDIRS = doc intl po src tests

As you can see, all the work here is really done in subdirectories.

The `po' and `intl' directories are automatically generated using gettextize; they will not be discussed here.

In `doc/Makefile.am' we see:

info_TEXINFOS = hello.texi
hello_TEXINFOS = gpl.texi

This is sufficient to build, install, and distribute the GNU Hello manual.

Here is `tests/Makefile.am':

TESTS = hello
EXTRA_DIST = hello.in testdata

The script `hello' is generated by configure, and is the only test case. make check will run this test.

Last we have `src/Makefile.am', where all the real work is done:

bin_PROGRAMS = hello
hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
hello_LDADD = @INTLLIBS@ @ALLOCA@
localedir = $(datadir)/locale
INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 Building etags and ctags

Here is another, trickier example. It shows how to generate two programs (ctags and etags) from the same source file (`etags.c'). The difficult part is that each compilation of `etags.c' requires different cpp flags.

bin_PROGRAMS = etags ctags
ctags_SOURCES =
ctags_LDADD = ctags.o

etags.o: etags.c
        $(COMPILE) -DETAGS_REGEXPS -c etags.c

ctags.o: etags.c
        $(COMPILE) -DCTAGS -o ctags.o -c etags.c

Note that there is no etags_SOURCES definition. Automake will implicitly assume that there is a source file named `etags.c', and define rules to compile `etags.o' and link `etags'. The etags.o: etags.c rule supplied by the above `Makefile.am', will override the Automake generated rule to build `etags.o'.

ctags_SOURCES is defined to be empty--that way no implicit value is substituted. Because we have not listed the source of `ctags', we have to tell Automake how to link the program. This is the purpose of the ctags_LDADD line. A ctags_DEPENDENCIES variable, holding the dependencies of the `ctags' target will be automatically generated by Automake from the contant of ctags_LDADD.

The above rules won't work if your compiler doesn't accept both `-c' and `-o'. The simplest fix for this is to introduce a bogus dependency (to avoid problems with a parallel make):

etags.o: etags.c ctags.o
        $(COMPILE) -DETAGS_REGEXPS -c etags.c

ctags.o: etags.c
        $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o

Also, these explicit rules do not work if the de-ANSI-fication feature is used (see section 9.13 Automatic de-ANSI-fication). Supporting de-ANSI-fication requires a little more work:

etags._o: etags._c ctags.o
        $(COMPILE) -DETAGS_REGEXPS -c etags.c

ctags._o: etags._c
        $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o

As it turns out, there is also a much easier way to do this same task. Some of the above techniques are useful enough that we've kept the example in the manual. However if you were to build etags and ctags in real life, you would probably use per-program compilation flags, like so:

bin_PROGRAMS = ctags etags

ctags_SOURCES = etags.c
ctags_CFLAGS = -DCTAGS

etags_SOURCES = etags.c
etags_CFLAGS = -DETAGS_REGEXPS

In this case Automake will cause `etags.c' to be compiled twice, with different flags. De-ANSI-fication will work automatically. In this instance, the names of the object files would be chosen by automake; they would be `ctags-etags.o' and `etags-etags.o'. (The name of the object files rarely matters.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Creating a `Makefile.in'

To create all the `Makefile.in's for a package, run the automake program in the top level directory, with no arguments. automake will automatically find each appropriate `Makefile.am' (by scanning `configure.in'; see section 5. Scanning `configure.in') and generate the corresponding `Makefile.in'. Note that automake has a rather simplistic view of what constitutes a package; it assumes that a package has only one `configure.in', at the top. If your package has multiple `configure.in's, then you must run automake in each directory holding a `configure.in'. (Alteratively, you may rely on Autoconf's autoreconf, which is able to recurse your package tree and run automake where appropriate.)

You can optionally give automake an argument; `.am' is appended to the argument and the result is used as the name of the input file. This feature is generally only used to automatically rebuild an out-of-date `Makefile.in'. Note that automake must always be run from the topmost directory of a project, even if being used to regenerate the `Makefile.in' in some subdirectory. This is necessary because automake must scan `configure.in', and because automake uses the knowledge that a `Makefile.in' is in a subdirectory to change its behavior in some cases.

automake accepts the following options:

`-a'
`--add-missing'
Automake requires certain common files to exist in certain situations; for instance `config.guess' is required if `configure.in' runs AC_CANONICAL_HOST. Automake is distributed with several of these files (see section 2.6 Programs automake might require); this option will cause the missing ones to be automatically added to the package, whenever possible. In general if Automake tells you a file is missing, try using this option. By default Automake tries to make a symbolic link pointing to its own copy of the missing file; this can be changed with --copy.

`--libdir=dir'
Look for Automake data files in directory dir instead of in the installation directory. This is typically used for debugging.

`-c'
`--copy'
When used with --add-missing, causes installed files to be copied. The default is to make a symbolic link.

`--cygnus'
Causes the generated `Makefile.in's to follow Cygnus rules, instead of GNU or Gnits rules. For more information, see 22. The effect of --cygnus.

`-f'
`--force-missing'
When used with --add-missing, causes standard files to be reinstalled even if they already exist in the source tree. This involves removing the file from the source tree before creating the new symlink (or, with --copy, copying the new file).

`--foreign'
Set the global strictness to `foreign'. For more information, see 2.2 Strictness.

`--gnits'
Set the global strictness to `gnits'. For more information, see 21. The effect of --gnu and --gnits.

`--gnu'
Set the global strictness to `gnu'. For more information, see 21. The effect of --gnu and --gnits. This is the default strictness.

`--help'
Print a summary of the command line options and exit.

`-i'
`--ignore-deps'
This disables the dependency tracking feature in generated `Makefile's; see 9.14 Automatic dependency tracking.

`--include-deps'
This enables the dependency tracking feature. This feature is enabled by default. This option is provided for historical reasons only and probably should not be used.

`--no-force'
Ordinarily automake creates all `Makefile.in's mentioned in `configure.in'. This option causes it to only update those `Makefile.in's which are out of date with respect to one of their dependents.

`-o dir'
`--output-dir=dir'
Put the generated `Makefile.in' in the directory dir. Ordinarily each `Makefile.in' is created in the directory of the corresponding `Makefile.am'. This option is deprecated and will be removed in a future release.

`-v'
`--verbose'
Cause Automake to print information about which files are being read or created.

`--version'
Print the version number of Automake and exit.

`--Werror'
`--Wno-error'
`--Werror' will cause all warnings issued by automake to become errors. Errors affect the exit status of automake, while warnings do not. `--Wno-error', the default, causes warnings to be treated as warnings only.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Scanning `configure.in'

Automake scans the package's `configure.in' to determine certain information about the package. Some autoconf macros are required and some variables must be defined in `configure.in'. Automake will also use information from `configure.in' to further tailor its output.

Automake also supplies some Autoconf macros to make the maintenance easier. These macros can automatically be put into your `aclocal.m4' using the aclocal program.

5.1 Configuration requirements
5.2 Other things Automake recognizes
5.3 Auto-generating aclocal.m4
5.4 Autoconf macros supplied with Automake
5.5 Writing your own aclocal macros

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 Configuration requirements

The one real requirement of Automake is that your `configure.in' call AM_INIT_AUTOMAKE. This macro does several things which are required for proper Automake operation (see section 5.4 Autoconf macros supplied with Automake).

Here are the other macros which Automake requires but which are not run by AM_INIT_AUTOMAKE:

AC_CONFIG_FILES
AC_OUTPUT
Automake uses these to determine which files to create (see section `Creating Output Files' in The Autoconf Manual). A listed file is considered to be an Automake generated `Makefile' if there exists a file with the same name and the `.am' extension appended. Typically, AC_CONFIG_FILES([foo/Makefile]) will cause Automake to generate `foo/Makefile.in' if `foo/Makefile.am' exists.

Other listed files are treated differently. Currently the only difference is that an Automake `Makefile' is removed by make distclean, while other files are removed by make clean.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 Other things Automake recognizes

Automake will also recognize the use of certain macros and tailor the generated `Makefile.in' appropriately. Currently recognized macros and their effects are:

AC_CONFIG_HEADER
Automake requires the use of AM_CONFIG_HEADER (see section 5.4 Autoconf macros supplied with Automake), which is similar to AC_CONFIG_HEADER (see section `Configuration Header Files' in The Autoconf Manual), but does some useful Automake-specific work.

AC_CONFIG_AUX_DIR
Automake will look for various helper scripts, such as `mkinstalldirs', in the directory named in this macro invocation. If not seen, the scripts are looked for in their `standard' locations (either the top source directory, or in the source directory corresponding to the current `Makefile.am', whichever is appropriate). See section `Finding `configure' Input' in The Autoconf Manual. FIXME: give complete list of things looked for in this directory

AC_PATH_XTRA
Automake will insert definitions for the variables defined by AC_PATH_XTRA into each `Makefile.in' that builds a C program or library. See section `System Services' in The Autoconf Manual.

AC_CANONICAL_HOST
Automake will ensure that `config.guess' and `config.sub' exist. Also, the `Makefile' variables `host_alias' and `host_triplet' are introduced. See section `Getting the Canonical System Type' in The Autoconf Manual.

AC_CANONICAL_SYSTEM
This is similar to AC_CANONICAL_HOST, but also defines the `Makefile' variables `build_alias' and `target_alias'. See section `Getting the Canonical System Type' in The Autoconf Manual.

AC_FUNC_ALLOCA
AC_FUNC_ERROR_AT_LINE
AC_FUNC_FNMATCH
AC_FUNC_GETLOADAVG
AC_FUNC_MEMCMP
AC_FUNC_MKTIME
AC_FUNC_OBSTACK
AC_FUNC_STRTOD
AC_REPLACE_FUNCS
AC_REPLACE_GNU_GETOPT
AC_STRUCT_ST_BLOCKS
AM_WITH_REGEX
Automake will ensure that the appropriate dependencies are generated for the objects corresponding to these macros. Also, Automake will verify that the appropriate source files are part of the distribution. Note that Automake does not come with any of the C sources required to use these macros, so automake -a will not install the sources. See section 9.2 Building a library, for more information. Also, see section `Particular Function Checks' in The Autoconf Manual.

AC_LIBOBJ
LIBOBJS
AC_LIBSOURCE
AC_LIBSOURCES
Automake will detect statements which put `.o' files into LIBOBJS, or pass `.o' files to AC_LIBOBJ, and will treat these additional files as if they were discovered via AC_REPLACE_FUNCS. Similarly, Automake will also distribute file listed in AC_LIBSOURCE and AC_LIBSOURCES.

Note that assignments to LIBOBJS is a construct which is being phased out; they will be ignored in a future release of Automake. You should call the AC_LIBOBJ macro instead. See section `Generic Function Checks' in The Autoconf Manual.

AC_PROG_RANLIB
This is required if any libraries are built in the package. See section `Particular Program Checks' in The Autoconf Manual.

AC_PROG_CXX
This is required if any C++ source is included. See section `Particular Program Checks' in The Autoconf Manual.

AC_PROG_F77
This is required if any Fortran 77 source is included. This macro is distributed with Autoconf version 2.13 and later. See section `Particular Program Checks' in The Autoconf Manual.

AC_F77_LIBRARY_LDFLAGS
This is required for programs and shared libraries that are a mixture of languages that include Fortran 77 (see section 9.10.3 Mixing Fortran 77 With C and C++). See section Autoconf macros supplied with Automake.

AC_PROG_LIBTOOL
Automake will turn on processing for libtool (see section `Introduction' in The Libtool Manual).

AC_PROG_YACC
If a Yacc source file is seen, then you must either use this macro or define the variable `YACC' in `configure.in'. The former is preferred (see section `Particular Program Checks' in The Autoconf Manual).

AC_PROG_LEX
If a Lex source file is seen, then this macro must be used. See section `Particular Program Checks' in The Autoconf Manual.

AM_C_PROTOTYPES
This is required when using automatic de-ANSI-fication; see 9.13 Automatic de-ANSI-fication.

AM_GNU_GETTEXT
This macro is required for packages which use GNU gettext (see section 11.2 Gettext). It is distributed with gettext. If Automake sees this macro it ensures that the package meets some of gettext's requirements.

AM_MAINTAINER_MODE
This macro adds a `--enable-maintainer-mode' option to configure. If this is used, automake will cause `maintainer-only' rules to be turned off by default in the generated `Makefile.in's. This macro is disallowed in `Gnits' mode (see section 21. The effect of --gnu and --gnits). This macro defines the `MAINTAINER_MODE' conditional, which you can use in your own `Makefile.am'.

AC_SUBST
AC_CHECK_TOOL
AC_CHECK_PROG
AC_CHECK_PROGS
AC_PATH_PROG
AC_PATH_PROGS
For each of these macros, the first argument is automatically defined as a variable in each generated `Makefile.in'. See section `Setting Output Variables' in The Autoconf Manual, and section `Generic Program Checks' in The Autoconf Manual.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros which can be used in your package; some of them are actually required by Automake in certain situations. These macros must be defined in your `aclocal.m4'; otherwise they will not be seen by autoconf.

The aclocal program will automatically generate `aclocal.m4' files based on the contents of `configure.in'. This provides a convenient way to get Automake-provided macros, without having to search around. Also, the aclocal mechanism allows other packages to supply their own macros.

At startup, aclocal scans all the `.m4' files it can find, looking for macro definitions. Then it scans `configure.in'. Any mention of one of the macros found in the first step causes that macro, and any macros it in turn requires, to be put into `aclocal.m4'.

The contents of `acinclude.m4', if it exists, are also automatically included in `aclocal.m4'. This is useful for incorporating local macros into `configure'.

aclocal tries to be smart about looking for new AC_DEFUNs in the files it scans. It also tries to copy the full text of the scanned file into `aclocal.m4', including both `#' and `dnl' comments. If you want to make a comment which will be completely ignored by aclocal, use `##' as the comment leader.

aclocal accepts the following options:

--acdir=dir
Look for the macro files in dir instead of the installation directory. This is typically used for debugging.

--help
Print a summary of the command line options and exit.

-I dir
Add the directory dir to the list of directories searched for `.m4' files.

--output=file
Cause the output to be put into file instead of `aclocal.m4'.

--print-ac-dir
Prints the name of the directory which aclocal will search to find third-party `.m4' files. When this option is given, normal processing is suppressed. This option can be used by a package to determine where to install a macro file.

--verbose
Print the names of the files it examines.

--version
Print the version number of Automake and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4 Autoconf macros supplied with Automake

Automake ships with several Autoconf macros that you can use from your `configure.in'. When you use one of them it will be included by aclocal in `aclocal.m4'.

5.4.1 Public macros | Macros that you can use.
5.4.2 Private macros | Macros that you should not use.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4.1 Public macros

AM_CONFIG_HEADER
Automake will generate rules to automatically regenerate the config header.

AM_ENABLE_MULTILIB
This is used when a "multilib" library is being built. The first optional argument is the name of the `Makefile' being generated; it defaults to `Makefile'. The second option argument is used to find the top source directory; it defaults to the empty string (generally this should not be used unless you are familiar with the internals). See section 18.3 Support for Multilibs.

AM_C_PROTOTYPES
Check to see if function prototypes are understood by the compiler. If so, define `PROTOTYPES' and set the output variables `U' and `ANSI2KNR' to the empty string. Otherwise, set `U' to `_' and `ANSI2KNR' to `./ansi2knr'. Automake uses these values to implement automatic de-ANSI-fication.

AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
If the use of TIOCGWINSZ requires `<sys/ioctl.h>', then define GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can be found in `<termios.h>'.

AM_INIT_AUTOMAKE([OPTIONS])
AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
Runs many macros required for proper operation of the generated Makefiles.

This macro has two forms, the second of which has two required arguments: the package and the version number. This latter form is obsolete because the package and version can be obtained from Autoconf's AC_INIT macro (which itself has an old and a new form).

If your `configure.in' has:
AC_INIT(src/foo.c)
AM_INIT_AUTOMAKE(mumble, 1.5)
you can modernize it as follow:
AC_INIT(mumble, 1.5)
AC_CONFIG_SRCDIR(src/foo.c)
AM_INIT_AUTOMAKE

Note that if you're upgrading your `configure.in' from an earlier version of Automake, it is not always correct to simply move the package and version arguments from AM_INIT_AUTOMAKE directly to AC_INIT, as in the example above. The first argument of AC_INIT is the name of your package (e.g. `GNU Automake'), not the tarball name (e.g. `automake') you used to pass to AM_INIT_AUTOMAKE. Autoconf's rule to derive a tarball name from the package name should work for most but not all packages. Especially, if your tarball name is not all lower case, you will have to use the four-argument form of AC_INIT (supported in Autoconf versions greater than 2.52g).

When AM_INIT_AUTOMAKE is called with a single argument, it is interpreted as a space-separated list of Automake options which should be applied to every `Makefile.am' in the tree. The effect is as if each option were listed in AUTOMAKE_OPTIONS.

By default this macro AC_DEFINE's `PACKAGE' and `VERSION'. This can be avoided by passing the `no-define' option, as in:
AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
or by passing a third non-empty argument to the obsolete form.

AM_PATH_LISPDIR
Searches for the program emacs, and, if found, sets the output variable lispdir to the full path to Emacs' site-lisp directory.

Note that this test assumes the emacs found to be a version that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other emacsen can cause this test to hang (some, like old versions of MicroEmacs, start up in interactive mode, requiring `C-x C-c' to exit, which is hardly obvious for a non-emacs user). In most cases, however, you should be able to use `C-c' to kill the test. In order to avoid problems, you can set EMACS to "no" in the environment, or use the `--with-lispdir' option to configure to explictly set the correct path (if you're sure you have an emacs that supports Emacs Lisp.

AM_PROG_AS
Use this macro when you have assembly code in your project. This will choose the assembler for you (by default the C compiler) and set CCAS, and will also set CCASFLAGS if required.

AM_PROG_CC_C_O
This is like AC_PROG_CC_C_O, but it generates its results in the manner required by automake. You must use this instead of AC_PROG_CC_C_O when you need this functionality.

AM_PROG_CC_STDC
If the C compiler is not in ANSI C mode by default, try to add an option to output variable CC to make it so. This macro tries various options that select ANSI C on some system or another. It considers the compiler to be in ANSI C mode if it handles function prototypes correctly.

If you use this macro, you should check after calling it whether the C compiler has been set to accept ANSI C; if not, the shell variable am_cv_prog_cc_stdc is set to `no'. If you wrote your source code in ANSI C, you can make an un-ANSIfied copy of it by using the ansi2knr option (see section 9.13 Automatic de-ANSI-fication).

AM_PROG_LEX
Like AC_PROG_LEX (see section `Particular Program Checks' in The Autoconf Manual), but uses the missing script on systems that do not have lex. `HP-UX 10' is one such system.

AM_PROG_GCJ
This macro finds the gcj program or causes an error. It sets `GCJ' and `GCJFLAGS'. gcj is the Java front-end to the GNU Compiler Collection.

AM_SYS_POSIX_TERMIOS
Check to see if POSIX termios headers and functions are available on the system. If so, set the shell variable am_cv_sys_posix_termios to `yes'. If not, set the variable to `no'.

AM_WITH_DMALLOC
Add support for the dmalloc package. If the user configures with `--with-dmalloc', then define WITH_DMALLOC and add `-ldmalloc' to LIBS.

AM_WITH_REGEX
Adds `--with-regex' to the configure command line. If specified (the default), then the `regex' regular expression library is used, `regex.o' is put into `LIBOBJS', and `WITH_REGEX' is defined. If `--without-regex' is given, then the `rx' regular expression library is used, and `rx.o' is put into `LIBOBJS'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4.2 Private macros

The following macros are private macros you should not call directly. They are called by the other public macros when appropriate. Do not rely on them, as they might be changed in a future version. Consider them as implementation details; or better, do not consider them at all: skip this section!

_AM_DEPENDENCIES
AM_SET_DEPDIR
AM_DEP_TRACK
AM_OUTPUT_DEPENDENCY_COMMANDS
These macros are used to implement automake's automatic dependency tracking scheme. They are called automatically by automake when required, and there should be no need to invoke them manually.

AM_MAKE_INCLUDE
This macro is used to discover how the user's make handles include statements. This macro is automatically invoked when needed; there should be no need to invoke it manually.

AM_PROG_INSTALL_STRIP
This is used to find a version of install which can be used to strip a program at installation time. This macro is automatically included when required.

AM_SANITY_CHECK
This checks to make sure that a file created in the build directory is newer than a file in the source directory. This can fail on systems where the clock is set incorrectly. This macro is automatically run from AM_INIT_AUTOMAKE.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.5 Writing your own aclocal macros

The aclocal program doesn't have any built-in knowledge of any macros, so it is easy to extend it with your own macros.

This is mostly used for libraries which want to supply their own Autoconf macros for use by other programs. For instance the gettext library supplies a macro AM_GNU_GETTEXT which should be used by any package using gettext. When the library is installed, it installs this macro so that aclocal will find it.

A file of macros should be a series of AC_DEFUN's. The aclocal programs also understands AC_REQUIRE, so it is safe to put each macro in a separate file. See section `Prerequisite Macros' in The Autoconf Manual, and section `Macro Definitions' in The Autoconf Manual.

A macro file's name should end in `.m4'. Such files should be installed in `aclocal --print-ac-dir` (which usually happens to be `$(datadir)/aclocal').

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. The top-level `Makefile.am'

In packages with subdirectories, the top level `Makefile.am' must tell Automake which subdirectories are to be built. This is done via the SUBDIRS variable.

The SUBDIRS macro holds a list of subdirectories in which building of various sorts can occur. Many targets (e.g. all) in the generated `Makefile' will run both locally and in all specified subdirectories. Note that the directories listed in SUBDIRS are not required to contain `Makefile.am's; only `Makefile's (after configuration). This allows inclusion of libraries from packages which do not use Automake (such as gettext). The directories mentioned in SUBDIRS must be direct children of the current directory. For instance, you cannot put `src/subdir' into SUBDIRS.

In packages that use subdirectories, the top-level `Makefile.am' is often very short. For instance, here is the `Makefile.am' from the GNU Hello distribution:

EXTRA_DIST = BUGS ChangeLog.O README-alpha
SUBDIRS = doc intl po src tests

It is possible to override the SUBDIRS variable if, like in the case of GNU Inetutils, you want to only build a subset of the entire package. In your `Makefile.am' include:

SUBDIRS = @MY_SUBDIRS@

Then in your `configure.in' you can specify:

MY_SUBDIRS="src doc lib po"
AC_SUBST(MY_SUBDIRS)

(Note that we don't use the variable name SUBDIRS in our `configure.in'; that would cause Automake to believe that every `Makefile.in' should recurse into the listed subdirectories.)

The upshot of this is that Automake is tricked into building the package to take the subdirs, but doesn't actually bind that list until configure is run.

Although the SUBDIRS macro can contain configure substitutions (e.g. `@DIRS@'); Automake itself does not actually examine the contents of this variable.

If SUBDIRS is defined, then your `configure.in' must include AC_PROG_MAKE_SET. When Automake invokes make in a subdirectory, it uses the value of the MAKE variable. It passes the value of the variable AM_MAKEFLAGS to the make invocation; this can be set in `Makefile.am' if there are flags you must always pass to make.

The use of SUBDIRS is not restricted to just the top-level `Makefile.am'. Automake can be used to construct packages of arbitrary depth.

By default, Automake generates `Makefiles' which work depth-first (`postfix'). However, it is possible to change this ordering. You can do this by putting `.' into SUBDIRS. For instance, putting `.' first will cause a `prefix' ordering of directories. All `clean' targets are run in reverse order of build targets.

Sometimes, such as when running make dist, you want all possible subdirectories to be examined. In this case Automake will use DIST_SUBDIRS, instead of SUBDIRS, to determine where to recurse. This variable will also be used when the user runs distclean or maintainer-clean. It should be set to the full list of subdirectories in the project. If this macro is not set, Automake will attempt to set it for you.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. An Alternative Approach to Subdirectories

If you've ever read Peter Miller's excellent paper, Recursive Make Considered Harmful, the preceding section on the use of subdirectories will probably come as unwelcome advice. For those who haven't read the paper, Miller's main thesis is that recursive make invocations are both slow and error-prone.

Automake provides sufficient cross-directory support (2) to enable you to write a single `Makefile.am' for a complex multi-directory package.

By default an installable file specified in a subdirectory will have its directory name stripped before installation. For instance, in this example, the header file will be installed as `$(includedir)/stdio.h':

include_HEADERS = inc/stdio.h

However, the `nobase_' prefix can be used to circumvent this path stripping. In this example, the header file will be installed as `$(includedir)/sys/types.h':

nobase_include_HEADERS = sys/types.h

`nobase_' should be specified first when used in conjonction with either `dist_' or `nodist_' (see section 15. What Goes in a Distribution). For instance:

nobase_dist_pkgdata_DATA = images/vortex.pgm

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. Rebuilding Makefiles

Automake generates rules to automatically rebuild `Makefile's, `configure', and other derived files like `Makefile.in'.

If you are using AM_MAINTAINER_MODE in `configure.in', then these automatic rebuilding rules are only enabled in maintainer mode.

Sometimes you need to run aclocal with an argument like -I to tell it where to find `.m4' files. Since sometimes make will automatically run aclocal, you need a way to specify these arguments. You can do this by defining ACLOCAL_AMFLAGS; this holds arguments which are passed verbatim to aclocal. This macro is only useful in the top-level `Makefile.am'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. Building Programs and Libraries

A large part of Automake's functionality is dedicated to making it easy to build programs and libraries.

9.1 Building a program
9.2 Building a library
9.3 Building a Shared Library | Building a Libtool library
9.4 Program and Library Variables | Variables controlling program and library builds
9.5 Special handling for LIBOBJS and ALLOCA
9.6 Variables used when building a program
9.7 Yacc and Lex support
9.8 C++ Support
9.9 Assembly Support
9.10 Fortran 77 Support
9.11 Java Support
9.12 Support for Other Languages
9.13 Automatic de-ANSI-fication
9.14 Automatic dependency tracking
9.15 Support for executable extensions

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1 Building a program

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1.1 Introductory blathering

In a directory containing source that gets built into a program (as opposed to a library or a script), the `PROGRAMS' primary is used. Programs can be installed in bindir, sbindir, libexecdir, pkglibdir, or not at all (`noinst'). They can also be built only for make check, in which case the prefix is `check'.

For instance:

bin_PROGRAMS = hello

In this simple case, the resulting `Makefile.in' will contain code to generate a program named hello.

Associated with each program are several assisting variables which are named after the program. These variables are all optional, and have reasonable defaults. Each variable, its use, and default is spelled out below; we use the "hello" example throughout.

The variable hello_SOURCES is used to specify which source files get built into an executable:

hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h

This causes each mentioned `.c' file to be compiled into the corresponding `.o'. Then all are linked to produce `hello'.

If `hello_SOURCES' is not specified, then it defaults to the single file `hello.c'; that is, the default is to compile a single C file whose base name is the name of the program itself. (This is a terrible default but we are stuck with it for historical reasons.)

Multiple programs can be built in a single directory. Multiple programs can share a single source file, which must be listed in each `_SOURCES' definition.

Header files listed in a `_SOURCES' definition will be included in the distribution but otherwise ignored. In case it isn't obvious, you should not include the header file generated by `configure' in a `_SOURCES' variable; this file should not be distributed. Lex (`.l') and Yacc (`.y') files can also be listed; see 9.7 Yacc and Lex support.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1.2 Conditional compilations

You can't put a configure substitution (e.g., `@FOO@') into a `_SOURCES' variable. The reason for this is a bit hard to explain, but suffice to say that it simply won't work. Automake will give an error if you try to do this.

Automake must know all the source files that could possibly go into a program, even if not all the files are built in every circumstance. Any files which are only conditionally built should be listed in the appropriate `EXTRA_' variable. For instance, if `hello-linux.c' were conditionally included in hello, the `Makefile.am' would contain:

EXTRA_hello_SOURCES = hello-linux.c

In this case, `hello-linux.o' would be added, via a `configure' substitution, to hello_LDADD in order to cause it to be built and linked in.

An often simpler way to compile source files conditionally is to use Automake conditionals. For instance, you could use this construct to conditionally use `hello-linux.c' or `hello-generic.c' as the basis for your program `hello':

if LINUX
hello_SOURCES = hello-linux.c
else
hello_SOURCES = hello-generic.c
endif

When using conditionals like this you don't need to use the `EXTRA_' variable, because Automake will examine the contents of each variable to construct the complete list of source files.

Sometimes it is useful to determine the programs that are to be built at configure time. For instance, GNU cpio only builds mt and rmt under special circumstances.

In this case, you must notify Automake of all the programs that can possibly be built, but at the same time cause the generated `Makefile.in' to use the programs specified by configure. This is done by having configure substitute values into each `_PROGRAMS' definition, while listing all optionally built programs in EXTRA_PROGRAMS.

Of course you can use Automake conditionals to determine the programs to be built.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1.3 Linking the program

If you need to link against libraries that are not found by configure, you can use LDADD to do so. This variable is used to specify additional objects or libraries to link with; it is inappropriate for specifying specific linker flags, you should use AM_LDFLAGS for this purpose.

Sometimes, multiple programs are built in one directory but do not share the same link-time requirements. In this case, you can use the `prog_LDADD' variable (where prog is the name of the program as it appears in some `_PROGRAMS' variable, and usually written in lowercase) to override the global LDADD. If this variable exists for a given program, then that program is not linked using LDADD.

For instance, in GNU cpio, pax, cpio and mt are linked against the library `libcpio.a'. However, rmt is built in the same directory, and has no such link requirement. Also, mt and rmt are only built on certain architectures. Here is what cpio's `src/Makefile.am' looks like (abridged):

bin_PROGRAMS = cpio pax @MT@
libexec_PROGRAMS = @RMT@
EXTRA_PROGRAMS = mt rmt

LDADD = ../lib/libcpio.a @INTLLIBS@
rmt_LDADD =

cpio_SOURCES = ...
pax_SOURCES = ...
mt_SOURCES = ...
rmt_SOURCES = ...

`prog_LDADD' is inappropriate for passing program-specific linker flags (except for `-l', `-L', `-dlopen' and `-dlpreopen'). So, use the `prog_LDFLAGS' variable for this purpose.

It is also occasionally useful to have a program depend on some other target which is not actually part of that program. This can be done using the `prog_DEPENDENCIES' variable. Each program depends on the contents of such a variable, but no further interpretation is done.

If `prog_DEPENDENCIES' is not supplied, it is computed by Automake. The automatically-assigned value is the contents of `prog_LDADD', with most configure substitutions, `-l', `-L', `-dlopen' and `-dlpreopen' options removed. The configure substitutions that are left in are only `@LIBOBJS@' and `@ALLOCA@'; these are left because it is known that they will not cause an invalid value for `prog_DEPENDENCIES' to be generated.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.2 Building a library

Building a library is much like building a program. In this case, the name of the primary is `LIBRARIES'. Libraries can be installed in libdir or pkglibdir.

See section 9.3 Building a Shared Library, for information on how to build shared libraries using Libtool and the `LTLIBRARIES' primary.

Each `_LIBRARIES' variable is a list of the libraries to be built. For instance to create a library named `libcpio.a', but not install it, you would write:

noinst_LIBRARIES = libcpio.a

The sources that go into a library are determined exactly as they are for programs, via the `_SOURCES' variables. Note that the library name is canonicalized (see section 2.4 How derived variables are named), so the `_SOURCES' variable corresponding to `liblob.a' is `liblob_a_SOURCES', not `liblob.a_SOURCES'.

Extra objects can be added to a library using the `library_LIBADD' variable. This should be used for objects determined by configure. Again from cpio:

libcpio_a_LIBADD = @LIBOBJS@ @ALLOCA@

In addition, sources for extra objects that will not exist until configure-time must be added to the BUILT_SOURCES variable (see section 10.4 Built sources).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3 Building a Shared Library

Building shared libraries is a relatively complex matter. For this reason, GNU Libtool (see section `Introduction' in The Libtool Manual) was created to help build shared libraries in a platform-independent way.

Automake uses Libtool to build libraries declared with the `LTLIBRARIES' primary. Each `_LTLIBRARIES' variable is a list of shared libraries to build. For instance, to create a library named `libgettext.a' and its corresponding shared libraries, and install them in `libdir', write:

lib_LTLIBRARIES = libgettext.la

Note that shared libraries must be installed in order to work properly, so check_LTLIBRARIES is not allowed. However, noinst_LTLIBRARIES is allowed. This feature should be used for libtool "convenience libraries".

For each library, the `library_LIBADD' variable contains the names of extra libtool objects (`.lo' files) to add to the shared library. The `library_LDFLAGS' variable contains any additional libtool flags, such as `-version-info' or `-static'.

Where an ordinary library might include @LIBOBJS@, a libtool library must use @LTLIBOBJS@. This is required because the object files that libtool operates on do not necessarily end in `.o'. The libtool manual contains more details on this topic.

For libraries installed in some directory, Automake will automatically supply the appropriate `-rpath' option. However, for libraries determined at configure time (and thus mentioned in EXTRA_LTLIBRARIES), Automake does not know the eventual installation directory; for such libraries you must add the `-rpath' option to the appropriate `_LDFLAGS' variable by hand.

Ordinarily, Automake requires that a shared library's name start with `lib'. However, if you are building a dynamically loadable module then you might wish to use a "nonstandard" name. In this case, put -module into the `_LDFLAGS' variable.

See section `The Libtool Manual' in The Libtool Manual, for more information.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.4 Program and Library Variables

Associated with each program are a collection of variables which can be used to modify how that program is built. There is a similar list of such variables for each library. The canonical name of the program (or library) is used as a base for naming these variables.

In the list below, we use the name "maude" to refer to the program or library. In your `Makefile.am' you would replace this with the canonical name of your program. This list also refers to "maude" as a program, but in general the same rules apply for both static and dynamic libraries; the documentation below notes situations where programs and libraries differ.

`maude_SOURCES'
This variable, if it exists, lists all the source files which are compiled to build the program. These files are added to the distribution by default. When building the program, Automake will cause each source file to be compiled to a single `.o' file (or `.lo' when using libtool). Normally these object files are named after the source file, but other factors can change this. If a file in the `_SOURCES' variable has an unrecognized extension, Automake will do one of two things with it. If a suffix rule exists for turning files with the unrecognized extension into `.o' files, then automake will treat this file as it will any other source file (see section 9.12 Support for Other Languages). Otherwise, the file will be ignored as though it were a header file.

The prefixes `dist_' and `nodist_' can be used to control whether files listed in a `_SOURCES' variable are distributed. `dist_' is redundant, as sources are distributed by default, but it can be specified for clarity if desired.

It is possible to have both `dist_' and `nodist_' variants of a given `_SOURCES' variable at once; this lets you easily distribute some files and not others, for instance:

nodist_maude_SOURCES = nodist.c
dist_maude_SOURCES = dist-me.c

By default the output file (on Unix systems, the `.o' file) will be put into the current build directory. However, if the option subdir-objects is in effect in the current directory then the `.o' file will be put into the subdirectory named after the source file. For instance, with subdir-objects enabled, `sub/dir/file.c' will be compiled to `sub/dir/file.o'. Some people prefer this mode of operation. You can specify subdir-objects in AUTOMAKE_OPTIONS (see section 17. Changing Automake's Behavior).

`EXTRA_maude_SOURCES'
Automake needs to know the list of files you intend to compile statically. For one thing, this is the only way Automake has of knowing what sort of language support a given `Makefile.in' requires. (3) This means that, for example, you can't put a configure substitution like `@my_sources@' into a `_SOURCES' variable. If you intend to conditionally compile source files and use `configure' to substitute the appropriate object names into, e.g., `_LDADD' (see below), then you should list the corresponding source files in the `EXTRA_' variable.

This variable also supports `dist_' and `nodist_' prefixes, e.g., `nodist_EXTRA_maude_SOURCES'.

`maude_AR'
A static library is created by default by invoking $(AR) cru followed by the name of the library and then the objects being put into the library. You can override this by setting the `_AR' variable. This is usually used with C++; some C++ compilers require a special invocation in order to instantiate all the templates which should go into a library. For instance, the SGI C++ compiler likes this macro set like so:
libmaude_a_AR = $(CXX) -ar -o

`maude_LIBADD'
Extra objects can be added to a static library using the `_LIBADD' variable. This should be used for objects determined by configure. Note that `_LIBADD' is not used for shared libraries; there you must use `_LDADD'.

`maude_LDADD'
Extra objects can be added to a shared library or a program by listing them in the `_LDADD' variable. This should be used for objects determined by configure.

`_LDADD' and `_LIBADD' are inappropriate for passing program-specific linker flags (except for `-l', `-L', `-dlopen' and `-dlpreopen'). Use the `_LDFLAGS' variable for this purpose.

For instance, if your `configure.in' uses AC_PATH_XTRA, you could link your program against the X libraries like so:

maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)

`maude_LDFLAGS'
This variable is used to pass extra flags to the link step of a program or a shared library.

`maude_LINK'
You can override the linker on a per-program basis. By default the linker is chosen according to the languages used by the program. For instance, a program that includes C++ source code would use the C++ compiler to link. The `_LINK' variable must hold the name of a command which can be passed all the `.o' file names as arguments. Note that the name of the underlying program is not passed to `_LINK'; typically one uses `$@':

maude_LINK = $(CCLD) -magic -o $@

`maude_CFLAGS'
Automake allows you to set compilation flags on a per-program (or per-library) basis. A single source file can be included in several programs, and it will potentially be compiled with different flags for each program. This works for any language directly supported by Automake. The flags are `_CFLAGS', `_CXXFLAGS', `_OBJCFLAGS', `_YFLAGS', `_CCASFLAGS', `_FFLAGS', `_RFLAGS', and `_GCJFLAGS'.

When using a per-program compilation flag, Automake will choose a different name for the intermediate object files. Ordinarily a file like `sample.c' will be compiled to produce `sample.o'. However, if the program's `_CFLAGS' variable is set, then the object file will be named, for instance, `maude-sample.o'.

In compilations with per-program flags, the ordinary `AM_' form of the flags variable is not automatically included in the compilation (however, the user form of the variable is included). So for instance, if you want the hypothetical `maude' compilations to also use the value of `AM_CFLAGS', you would need to write:

maude_CFLAGS = ... your flags ... $(AM_CFLAGS)

`maude_DEPENDENCIES'
It is also occasionally useful to have a program depend on some other target which is not actually part of that program. This can be done using the `_DEPENDENCIES' variable. Each program depends on the contents of such a variable, but no further interpretation is done.

If `_DEPENDENCIES' is not supplied, it is computed by Automake. The automatically-assigned value is the contents of `_LDADD' or `_LIBADD', with most configure substitutions, `-l', `-L', `-dlopen' and `-dlpreopen' options removed. The configure substitutions that are left in are only `@LIBOBJS@' and `@ALLOCA@'; these are left because it is known that they will not cause an invalid value for `_DEPENDENCIES' to be generated.

`maude_SHORTNAME'
On some platforms the allowable file names are very short. In order to support these systems and per-program compilation flags at the same time, Automake allows you to set a "short name" which will influence how intermediate object files are named. For instance, if you set `maude_SHORTNAME' to `m', then in the above per-program compilation flag example the object file would be named `m-sample.o' rather than `maude-sample.o'. This facility is rarely needed in practice, and we recommend avoiding it until you find it is required.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.5 Special handling for LIBOBJS and ALLOCA

Automake explicitly recognizes the use of @LIBOBJS@ and @ALLOCA@, and uses this information, plus the list of LIBOBJS files derived from `configure.in' to automatically include the appropriate source files in the distribution (see section 15. What Goes in a Distribution). These source files are also automatically handled in the dependency-tracking scheme; see See section 9.14 Automatic dependency tracking.

@LIBOBJS@ and @ALLOCA@ are specially recognized in any `_LDADD' or `_LIBADD' variable.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.6 Variables used when building a program

Occasionally it is useful to know which `Makefile' variables Automake uses for compilations; for instance you might need to do your own compilation in some special cases.

Some variables are inherited from Autoconf; these are CC, CFLAGS, CPPFLAGS, DEFS, LDFLAGS, and LIBS.

There are some additional variables which Automake itself defines:

AM_CPPFLAGS
The contents of this macro are passed to every compilation which invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance, `-I' and `-D' options should be listed here.

Automake already provides some `-I' options automatically. In particular it generates `-I$(srcdir)', `-I.', and a `-I' pointing to the directory holding `config.h' (if you've used AC_CONFIG_HEADER or AM_CONFIG_HEADER). You can disable the default `-I' options using the `nostdinc' option.

INCLUDES
This does the same job as `AM_CPPFLAGS'. It is an older name for the same functionality. This macro is deprecated; we suggest using `AM_CPPFLAGS' instead.

AM_CFLAGS
This is the variable which the `Makefile.am' author can use to pass in additional C compiler flags. It is more fully documented elsewhere. In some situations, this is not used, in preference to the per-executable (or per-library) _CFLAGS.

COMPILE
This is the command used to actually compile a C source file. The filename is appended to form the complete command line.

AM_LDFLAGS
This is the variable which the `Makefile.am' author can use to pass in additional linker flags. In some situations, this is not used, in preference to the per-executable (or per-library) _LDFLAGS.

LINK
This is the command used to actually link a C program. It already includes `-o $@' and the usual variable references (for instance, CFLAGS); it takes as "arguments" the names of the object files and libraries to link in.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.7 Yacc and Lex support

Automake has somewhat idiosyncratic support for Yacc and Lex.

Automake assumes that the `.c' file generated by yacc (or lex) should be named using the basename of the input file. That is, for a yacc source file `foo.y', Automake will cause the intermediate file to be named `foo.c' (as opposed to `y.tab.c', which is more traditional).

The extension of a yacc source file is used to determine the extension of the resulting `C' or `C++' file. Files with the extension `.y' will be turned into `.c' files; likewise, `.yy' will become `.cc'; `.y++', `c++'; and `.yxx', `.cxx'.

Likewise, lex source files can be used to generate `C' or `C++'; the extensions `.l', `.ll', `.l++', and `.lxx' are recognized.

You should never explicitly mention the intermediate (`C' or `C++') file in any `SOURCES' variable; only list the source file.

The intermediate files generated by yacc (or lex) will be included in any distribution that is made. That way the user doesn't need to have yacc or lex.

If a yacc source file is seen, then your `configure.in' must define the variable `YACC'. This is most easily done by invoking the macro `AC_PROG_YACC' (see section `Particular Program Checks' in The Autoconf Manual).

When yacc is invoked, it is passed `YFLAGS' and `AM_YFLAGS'. The former is a user variable and the latter is intended for the `Makefile.am' author.

Similarly, if a lex source file is seen, then your `configure.in' must define the variable `LEX'. You can use `AC_PROG_LEX' to do this (see section `Particular Program Checks' in The Autoconf Manual), but using AM_PROG_LEX macro (see section 5.4 Autoconf macros supplied with Automake) is recommended.

When lex is invoked, it is passed `LFLAGS' and `AM_LFLAGS'. The former is a user variable and the latter is intended for the `Makefile.am' author.

Automake makes it possible to include multiple yacc (or lex) source files in a single program. Automake uses a small program called ylwrap to run yacc (or lex) in a subdirectory. This is necessary because yacc's output filename is fixed, and a parallel make could conceivably invoke more than one instance of yacc simultaneously. The ylwrap program is distributed with Automake. It should appear in the directory specified by `AC_CONFIG_AUX_DIR' (see section `Finding `configure' Input' in The Autoconf Manual), or the current directory if that macro is not used in `configure.in'.

For yacc, simply managing locking is insufficient. The output of yacc always uses the same symbol names internally, so it isn't possible to link two yacc parsers into the same executable.

We recommend using the following renaming hack used in gdb:
#define	yymaxdepth c_maxdepth
#define	yyparse	c_parse
#define	yylex	c_lex
#define	yyerror	c_error
#define	yylval	c_lval
#define	yychar	c_char
#define	yydebug	c_debug
#define	yypact	c_pact
#define	yyr1	c_r1
#define	yyr2	c_r2
#define	yydef	c_def
#define	yychk	c_chk
#define	yypgo	c_pgo
#define	yyact	c_act
#define	yyexca	c_exca
#define yyerrflag c_errflag
#define yynerrs	c_nerrs
#define	yyps	c_ps
#define	yypv	c_pv
#define	yys	c_s
#define	yy_yys	c_yys
#define	yystate	c_state
#define	yytmp	c_tmp
#define	yyv	c_v
#define	yy_yyv	c_yyv
#define	yyval	c_val
#define	yylloc	c_lloc
#define yyreds	c_reds
#define yytoks	c_toks
#define yylhs	c_yylhs
#define yylen	c_yylen
#define yydefred c_yydefred
#define yydgoto	c_yydgoto
#define yysindex c_yysindex
#define yyrindex c_yyrindex
#define yygindex c_yygindex
#define yytable	 c_yytable
#define yycheck	 c_yycheck
#define yyname   c_yyname
#define yyrule   c_yyrule

For each define, replace the `c_' prefix with whatever you like. These defines work for bison, byacc, and traditional yaccs. If you find a parser generator that uses a symbol not covered here, please report the new name so it can be added to the list.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.8 C++ Support

Automake includes full support for C++.

Any package including C++ code must define the output variable `CXX' in `configure.in'; the simplest way to do this is to use the AC_PROG_CXX macro (see section `Particular Program Checks' in The Autoconf Manual).

A few additional variables are defined when a C++ source file is seen:

CXX
The name of the C++ compiler.

CXXFLAGS
Any flags to pass to the C++ compiler.

AM_CXXFLAGS
The maintainer's variant of CXXFLAGS.

CXXCOMPILE
The command used to actually compile a C++ source file. The file name is appended to form the complete command line.

CXXLINK
The command used to actually link a C++ program.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.9 Assembly Support

Automake includes some support for assembly code.

The variable CCAS holds the name of the compiler used to build assembly code. This compiler must work a bit like a C compiler; in particular it must accept `-c' and `-o'. The value of CCASFLAGS is passed to the compilation.

You are required to set CCAS and CCASFLAGS via `configure.in'. The autoconf macro AM_PROG_AS will do this for you. Unless they are already set, it simply sets CCAS to the C compiler and CCASFLAGS to the C compiler flags.

Only the suffixes `.s' and `.S' are recognized by automake as being files containing assembly code.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.10 Fortran 77 Support

Automake includes full support for Fortran 77.

Any package including Fortran 77 code must define the output variable `F77' in `configure.in'; the simplest way to do this is to use the AC_PROG_F77 macro (see section `Particular Program Checks' in The Autoconf Manual). See section 9.10.4 Fortran 77 and Autoconf.

A few additional variables are defined when a Fortran 77 source file is seen:

F77
The name of the Fortran 77 compiler.

FFLAGS
Any flags to pass to the Fortran 77 compiler.

AM_FFLAGS
The maintainer's variant of FFLAGS.

RFLAGS
Any flags to pass to the Ratfor compiler.

AM_RFLAGS
The maintainer's variant of RFLAGS.

F77COMPILE
The command used to actually compile a Fortran 77 source file. The file name is appended to form the complete command line.

FLINK
The command used to actually link a pure Fortran 77 program or shared library.

Automake can handle preprocessing Fortran 77 and Ratfor source files in addition to compiling them(4). Automake also contains some support for creating programs and shared libraries that are a mixture of Fortran 77 and other languages (see section 9.10.3 Mixing Fortran 77 With C and C++).

These issues are covered in the following sections.

9.10.1 Preprocessing Fortran 77
9.10.2 Compiling Fortran 77 Files
9.10.3 Mixing Fortran 77 With C and C++
9.10.4 Fortran 77 and Autoconf

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.10.1 Preprocessing Fortran 77

`N.f' is made automatically from `N.F' or `N.r'. This rule runs just the preprocessor to convert a preprocessable Fortran 77 or Ratfor source file into a strict Fortran 77 source file. The precise command used is as follows:

`.F'
$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)

`.r'
$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.10.2 Compiling Fortran 77 Files

`N.o' is made automatically from `N.f', `N.F' or `N.r' by running the Fortran 77 compiler. The precise command used is as follows:

`.f'
$(F77) -c $(AM_FFLAGS) $(FFLAGS)

`.F'
$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)

`.r'
$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.10.3 Mixing Fortran 77 With C and C++

Automake currently provides limited support for creating programs and shared libraries that are a mixture of Fortran 77 and C and/or C++. However, there are many other issues related to mixing Fortran 77 with other languages that are not (currently) handled by Automake, but that are handled by other packages(5).

Automake can help in two ways:

  1. Automatic selection of the linker depending on which combinations of source code.

  2. Automatic selection of the appropriate linker flags (e.g. `-L' and `-l') to pass to the automatically selected linker in order to link in the appropriate Fortran 77 intrinsic and run-time libraries.

    These extra Fortran 77 linker flags are supplied in the output variable FLIBS by the AC_F77_LIBRARY_LDFLAGS Autoconf macro supplied with newer versions of Autoconf (Autoconf version 2.13 and later). See section `Fortran 77 Compiler Characteristics' in The Autoconf.

If Automake detects that a program or shared library (as mentioned in some _PROGRAMS or _LTLIBRARIES primary) contains source code that is a mixture of Fortran 77 and C and/or C++, then it requires that the macro AC_F77_LIBRARY_LDFLAGS be called in `configure.in', and that either $(FLIBS) or @FLIBS@ appear in the appropriate _LDADD (for programs) or _LIBADD (for shared libraries) variables. It is the responsibility of the person writing the `Makefile.am' to make sure that $(FLIBS) or @FLIBS@ appears in the appropriate _LDADD or _LIBADD variable.

For example, consider the following `Makefile.am':

bin_PROGRAMS = foo
foo_SOURCES  = main.cc foo.f
foo_LDADD    = libfoo.la @FLIBS@

pkglib_LTLIBRARIES = libfoo.la
libfoo_la_SOURCES  = bar.f baz.c zardoz.cc
libfoo_la_LIBADD   = $(FLIBS)

In this case, Automake will insist that AC_F77_LIBRARY_LDFLAGS is mentioned in `configure.in'. Also, if @FLIBS@ hadn't been mentioned in foo_LDADD and libfoo_la_LIBADD, then Automake would have issued a warning.

9.10.3.1 How the Linker is Chosen

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.10.3.1 How the Linker is Chosen

The following diagram demonstrates under what conditions a particular linker is chosen by Automake.

For example, if Fortran 77, C and C++ source code were to be compiled into a program, then the C++ linker will be used. In this case, if the C or Fortran 77 linkers required any special libraries that weren't included by the C++ linker, then they must be manually added to an _LDADD or _LIBADD variable by the user writing the `Makefile.am'.

                     \              Linker
          source      \
           code        \     C        C++     Fortran
     -----------------  +---------+---------+---------+
                        |         |         |         |
     C                  |    x    |         |         |
                        |         |         |         |
                        +---------+---------+---------+
                        |         |         |         |
         C++            |         |    x    |         |
                        |         |         |         |
                        +---------+---------+---------+
                        |         |         |         |
               Fortran  |         |         |    x    |
                        |         |         |         |
                        +---------+---------+---------+
                        |         |         |         |
     C + C++            |         |    x    |         |
                        |         |         |         |
                        +---------+---------+---------+
                        |         |         |         |
     C +       Fortran  |         |         |    x    |
                        |         |         |         |
                        +---------+---------+---------+
                        |         |         |         |
         C++ + Fortran  |         |    x    |         |
                        |         |         |         |
                        +---------+---------+---------+
                        |         |         |         |
     C + C++ + Fortran  |         |    x    |         |
                        |         |         |         |
                        +---------+---------+---------+

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.10.4 Fortran 77 and Autoconf

The current Automake support for Fortran 77 requires a recent enough version of Autoconf that also includes support for Fortran 77. Full Fortran 77 support was added to Autoconf 2.13, so you will want to use that version of Autoconf or later.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.11 Java Support

Automake includes support for compiled Java, using gcj, the Java front end to the GNU Compiler Collection.

Any package including Java code to be compiled must define the output variable `GCJ' in `configure.in'; the variable `GCJFLAGS' must also be defined somehow (either in `configure.in' or `Makefile.am'). The simplest way to do this is to use the AM_PROG_GCJ macro.

By default, programs including Java source files are linked with gcj.

As always, the contents of `AM_GCJFLAGS' are passed to every compilation invoking gcj (in its role as an ahead-of-time compiler -- when invoking it to create `.class' files, `AM_JAVACFLAGS' is used instead). If it is necessary to pass options to gcj from `Makefile.am', this macro, and not the user macro `GCJFLAGS', should be used.

gcj can be used to compile `.java', `.class', `.zip', or `.jar' files.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.12 Support for Other Languages

Automake currently only includes full support for C, C++ (see section 9.8 C++ Support), Fortran 77 (see section 9.10 Fortran 77 Support), and Java (see section 9.11 Java Support). There is only rudimentary support for other languages, support for which will be improved based on user demand.

Some limited support for adding your own languages is available via the suffix rule handling; see 18.2 Handling new file extensions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.13 Automatic de-ANSI-fication

Although the GNU standards allow the use of ANSI C, this can have the effect of limiting portability of a package to some older compilers (notably the SunOS C compiler).

Automake allows you to work around this problem on such machines by de-ANSI-fying each source file before the actual compilation takes place.

If the `Makefile.am' variable AUTOMAKE_OPTIONS (see section 17. Changing Automake's Behavior) contains the option ansi2knr then code to handle de-ANSI-fication is inserted into the generated `Makefile.in'.

This causes each C source file in the directory to be treated as ANSI C. If an ANSI C compiler is available, it is used. If no ANSI C compiler is available, the ansi2knr program is used to convert the source files into K&R C, which is then compiled.

The ansi2knr program is simple-minded. It assumes the source code will be formatted in a particular way; see the ansi2knr man page for details.

Support for de-ANSI-fication requires the source files `ansi2knr.c' and `ansi2knr.1' to be in the same package as the ANSI C source; these files are distributed with Automake. Also, the package `configure.in' must call the macro AM_C_PROTOTYPES (see section 5.4 Autoconf macros supplied with Automake).

Automake also handles finding the ansi2knr support files in some other directory in the current package. This is done by prepending the relative path to the appropriate directory to the ansi2knr option. For instance, suppose the package has ANSI C code in the `src' and `lib' subdirs. The files `ansi2knr.c' and `ansi2knr.1' appear in `lib'. Then this could appear in `src/Makefile.am':

AUTOMAKE_OPTIONS = ../lib/ansi2knr

If no directory prefix is given, the files are assumed to be in the current directory.

Files mentioned in LIBOBJS which need de-ANSI-fication will not be automatically handled. That's because configure will generate an object name like `regex.o', while make will be looking for `regex_.o' (when de-ANSI-fying). Eventually this problem will be fixed via autoconf magic, but for now you must put this code into your `configure.in', just before the AC_OUTPUT call:

# This is necessary so that .o files in LIBOBJS are also built via
# the ANSI2KNR-filtering rules.
LIBOBJS=`echo $LIBOBJS|sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`

Note that automatic de-ANSI-fication will not work when the package is being built for a different host architecture. That is because automake currently has no way to build ansi2knr for the build machine.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.14 Automatic dependency tracking

As a developer it is often painful to continually update the `Makefile.in' whenever the include-file dependencies change in a project. Automake supplies a way to automatically track dependency changes.

Automake always uses complete dependencies for a compilation, including system headers. Automake's model is that dependency computation should be a side effect of the build. To this end, dependencies are computed by running all compilations through a special wrapper program called depcomp. depcomp understands how to coax many different C and C++ compilers into generating dependency information in the format it requires. automake -a will install depcomp into your source tree for you. If depcomp can't figure out how to properly invoke your compiler, dependency tracking will simply be disabled for your build.

Experience with earlier versions of Automake (6) taught us that it is not reliable to generate dependencies only on the maintainer's system, as configurations vary too much. So instead Automake implements dependency tracking at build time.

Automatic dependency tracking can be suppressed by putting no-dependencies in the variable AUTOMAKE_OPTIONS, or passing no-dependencies as an argument to AM_INIT_AUTOMAKE (this should be the prefered way). Or, you can invoke automake with the -i option. Dependency tracking is enabled by default.

The person building your package also can choose to disable dependency tracking by configuring with --disable-dependency-tracking.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.15 Support for executable extensions

On some platforms, such as Windows, executables are expected to have an extension such as `.exe'. On these platforms, some compilers (GCC among them) will automatically generate `foo.exe' when asked to generate `foo'.

Automake provides mostly-transparent support for this. Unfortunately mostly doesn't yet mean fully. Until the English dictionary is revised, you will have to assist Automake if your package must support those platforms.

One thing you must be aware of is that, internally, Automake rewrites something like this:

bin_PROGRAMS = liver

to this:

bin_PROGRAMS = liver$(EXEEXT)

The targets Automake generates are likewise given the `$(EXEEXT)' extension. EXEEXT

However, Automake cannot apply this rewriting to configure substitutions. This means that if you are conditionally building a program using such a substitution, then your `configure.in' must take care to add `$(EXEEXT)' when constructing the output variable.

With Autoconf 2.13 and earlier, you must explicitly use AC_EXEEXT to get this support. With Autoconf 2.50, AC_EXEEXT is run automatically if you configure a compiler (say, through AC_PROG_CC).

Sometimes maintainers like to write an explicit link rule for their program. Without executable extension support, this is easy--you simply write a target with the same name as the program. However, when executable extension support is enabled, you must instead add the `$(EXEEXT)' suffix.

Unfortunately, due to the change in Autoconf 2.50, this means you must always add this extension. However, this is a problem for maintainers who know their package will never run on a platform that has executable extensions. For those maintainers, the no-exeext option (see section 17. Changing Automake's Behavior) will disable this feature. This works in a fairly ugly way; if no-exeext is seen, then the presence of a target named foo in `Makefile.am' will override an automake-generated target of the form foo$(EXEEXT). Without the no-exeext option, this use will give an error.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10. Other Derived Objects

Automake can handle derived objects which are not C programs. Sometimes the support for actually building such objects must be explicitly supplied, but Automake will still automatically handle installation and distribution.

10.1 Executable Scripts | Executable scripts
10.2 Header files
10.3 Architecture-independent data files
10.4 Built sources | Derived sources

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.1 Executable Scripts

It is possible to define and install programs which are scripts. Such programs are listed using the `SCRIPTS' primary name. Automake doesn't define any dependencies for scripts; the `Makefile.am' should include the appropriate rules.

Automake does not assume that scripts are derived objects; such objects must be deleted by hand (see section 14. What Gets Cleaned).

The automake program itself is a Perl script that is generated at configure time from `automake.in'. Here is how this is handled:

bin_SCRIPTS = automake

Since automake appears in the AC_OUTPUT macro, a target for it is automatically generated, and it is also automatically cleaned (despite the fact it's a script).

Script objects can be installed in bindir, sbindir, libexecdir, or pkgdatadir.

Scripts that need not being installed can be listed in noinst_SCRIPTS, and among them, those which are needed only by make check should go in check_SCRIPTS.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2 Header files

Header files are specified by the `HEADERS' family of variables. Generally header files are not installed, so the noinst_HEADERS variable will be the most used. (7)

All header files must be listed somewhere; missing ones will not appear in the distribution. Often it is clearest to list uninstalled headers with the rest of the sources for a program. See section 9.1 Building a program. Headers listed in a `_SOURCES' variable need not be listed in any `_HEADERS' variable.

Headers can be installed in includedir, oldincludedir, or pkgincludedir.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.3 Architecture-independent data files

Automake supports the installation of miscellaneous data files using the `DATA' family of variables.

Such data can be installed in the directories datadir, sysconfdir, sharedstatedir, localstatedir, or pkgdatadir.

By default, data files are not included in a distribution. Of course, you can use the `dist_' prefix to change this on a per-variable basis.

Here is how Automake declares its auxiliary data files:

dist_pkgdata_DATA = clean-kr.am clean.am ...

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.4 Built sources

Occasionally a file which would otherwise be called `source' (e.g. a C `.h' file) is actually derived from some other file. Such files should be listed in the BUILT_SOURCES variable.

BUILT_SOURCES is actually a bit of a misnomer, as any file which must be created early in the build process can be listed in this variable.

A source file listed in BUILT_SOURCES is created before the other all targets are made. However, such a source file is not compiled unless explicitly requested by mentioning it in some other `_SOURCES' variable.

So, for instance, if you had header files which were created by a script run at build time, then you would list these headers in BUILT_SOURCES, to ensure that they would be built before any other compilations (perhaps ones using these headers) were started.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11. Other GNU Tools

Since Automake is primarily intended to generate `Makefile.in's for use in GNU programs, it tries hard to interoperate with other GNU tools.

11.1 Emacs Lisp
11.2 Gettext
11.3 Libtool
11.4 Java
11.5 Python

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.1 Emacs Lisp

Automake provides some support for Emacs Lisp. The `LISP' primary is used to hold a list of `.el' files. Possible prefixes for this primary are `lisp_' and `noinst_'. Note that if lisp_LISP is defined, then `configure.in' must run AM_PATH_LISPDIR (see section 5.4 Autoconf macros supplied with Automake).

By default Automake will byte-compile all Emacs Lisp source files using the Emacs found by AM_PATH_LISPDIR. If you wish to avoid byte-compiling, simply define the variable ELCFILES to be empty. Byte-compiled Emacs Lisp files are not portable among all versions of Emacs, so it makes sense to turn this off if you expect sites to have more than one version of Emacs installed. Furthermore, many packages don't actually benefit from byte-compilation. Still, we recommend that you leave it enabled by default. It is probably better for sites with strange setups to cope for themselves than to make the installation less nice for everybody else.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.2 Gettext

If AM_GNU_GETTEXT is seen in `configure.in', then Automake turns on support for GNU gettext, a message catalog system for internationalization (see section `GNU Gettext' in GNU gettext utilities).

The gettext support in Automake requires the addition of two subdirectories to the package, `intl' and `po'. Automake insures that these directories exist and are mentioned in SUBDIRS.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.3 Libtool

Automake provides support for GNU Libtool (see section `Introduction' in The Libtool Manual) with the `LTLIBRARIES' primary. See section 9.3 Building a Shared Library.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.4 Java

Automake provides some minimal support for Java compilation with the `JAVA' primary.

Any `.java' files listed in a `_JAVA' variable will be compiled with JAVAC at build time. By default, `.class' files are not included in the distribution.

Currently Automake enforces the restriction that only one `_JAVA' primary can be used in a given `Makefile.am'. The reason for this restriction is that, in general, it isn't possible to know which `.class' files were generated from which `.java' files -- so it would be impossible to know which files to install where. For instance, a `.java' file can define multiple classes; the resulting `.class' file names cannot be predicted without parsing the `.java' file.

There are a few variables which are used when compiling Java sources:

JAVAC
The name of the Java compiler. This defaults to `javac'.

JAVACFLAGS
The flags to pass to the compiler. This is considered to be a user variable (see section 2.5 Variables reserved for the user).

AM_JAVACFLAGS
More flags to pass to the Java compiler. This, and not JAVACFLAGS, should be used when it is necessary to put Java compiler flags into `Makefile.am'.

JAVAROOT
The value of this variable is passed to the `-d' option to javac. It defaults to `$(top_builddir)'.

CLASSPATH_ENV
This variable is an sh expression which is used to set the CLASSPATH environment variable on the javac command line. (In the future we will probably handle class path setting differently.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.5 Python

Automake provides support for Python compilation with the `PYTHON' primary.

Any files listed in a `_PYTHON' variable will be byte-compiled with py-compile at install time. py-compile actually creates both standard (`.pyc') and byte-compiled (`.pyo') versions of the source files. Note that because byte-compilation occurs at install time, any files listed in `noinst_PYTHON' will not be compiled. Python source files are included in the distribution by default.

Automake ships with an Autoconf macro called AM_PATH_PYTHON which will determine some Python-related directory variables (see below). If have called AM_PATH_PYTHON from you `configure.in', then you may use the following variables to list you Python source files in your variables: `python_PYTHON', `pkgpython_PYTHON', `pkgpython_PYTHON', `pyexecdir_PYTHON', `pkgpyexecdir_PYTHON', depending where you want your files installed.

AM_PATH_PYTHON takes a single optional argument. This argument, if present, is the minimum version of Python which can be used for this package. If the version of Python found on the system is older than the required version, then AM_PATH_PYTHON will cause an error.

AM_PATH_PYTHON creates several output variables based on the Python installation found during configuration.

PYTHON
The name of the Python executable.

PYTHON_VERSION
The Python version number, in the form major.minor (e.g. `1.5'). This is currently the value of sys.version[:3].

PYTHON_PREFIX
The string $prefix. This term may be used in future work which needs the contents of Python's sys.prefix, but general consensus is to always use the value from configure.

PYTHON_EXEC_PREFIX
The string $exec_prefix. This term may be used in future work which needs the contents of Python's sys.exec_prefix, but general consensus is to always use the value from configure.

PYTHON_PLATFORM
The canonical name used by Python to describe the operating system, as given by sys.platform. This value is sometimes needed when building Python extensions.

pythondir
The directory name for the `site-packages' subdirectory of the standard Python install tree.

pkgpythondir
This is is the directory under pythondir which is named after the package. That is, it is `$(pythondir)/$(PACKAGE)'. It is provided as a convenience.

pyexecdir
This is the directory where Python extension modules (shared libraries) should be installed.

pkgpyexecdir
This is a convenience variable which is defined as `$(pyexecdir)/$(PACKAGE)'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12. Building documentation

Currently Automake provides support for Texinfo and man pages.

12.1 Texinfo
12.2 Man pages

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.1 Texinfo

If the current directory contains Texinfo source, you must declare it with the `TEXINFOS' primary. Generally Texinfo files are converted into info, and thus the info_TEXINFOS macro is most commonly used here. Any Texinfo source file must end in the `.texi', `.txi', or `.texinfo' extension. We recommend `.texi' for new manuals.

If the `.texi' file @includes `version.texi', then that file will be automatically generated. The file `version.texi' defines four Texinfo macros you can reference:

EDITION
VERSION
Both of these macros hold the version number of your program. They are kept separate for clarity.

UPDATED
This holds the date the primary `.texi' file was last modified.

UPDATED-MONTH
This holds the name of the month in which the primary `.texi' file was last modified.

The `version.texi' support requires the mdate-sh program; this program is supplied with Automake and automatically included when automake is invoked with the --add-missing option.

If you have multiple Texinfo files, and you want to use the `version.texi' feature, then you have to have a separate version file for each Texinfo file. Automake will treat any include in a Texinfo file that matches `vers*.texi' just as an automatically generated version file.

When an info file is rebuilt, the program named by the MAKEINFO variable is used to invoke it. If the makeinfo program is found on the system then it will be used by default; otherwise missing will be used instead. The flags in the variables MAKEINFOFLAGS and AM_MAKEINFOFLAGS will be passed to the makeinfo invocation; the first of these is intended for use by the user (see section 2.5 Variables reserved for the user) and the second by the `Makefile.am' writer.

Sometimes an info file actually depends on more than one `.texi' file. For instance, in GNU Hello, `hello.texi' includes the file `gpl.texi'. You can tell Automake about these dependencies using the texi_TEXINFOS variable. Here is how GNU Hello does it:

info_TEXINFOS = hello.texi
hello_TEXINFOS = gpl.texi

By default, Automake requires the file `texinfo.tex' to appear in the same directory as the Texinfo source. However, if you used AC_CONFIG_AUX_DIR in `configure.in' (see section `Finding `configure' Input' in The Autoconf Manual), then `texinfo.tex' is looked for there. Automake supplies `texinfo.tex' if `--add-missing' is given.

If your package has Texinfo files in many directories, you can use the variable TEXINFO_TEX to tell Automake where to find the canonical `texinfo.tex' for your package. The value of this variable should be the relative path from the current `Makefile.am' to `texinfo.tex':

TEXINFO_TEX = ../doc/texinfo.tex

The option `no-texinfo.tex' can be used to eliminate the requirement for `texinfo.tex'. Use of the variable TEXINFO_TEX is preferable, however, because that allows the dvi target to still work.

Automake generates an install-info target; some people apparently use this. By default, info pages are installed by `make install'. This can be prevented via the no-installinfo option.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.2 Man pages

A package can also include man pages (but see the GNU standards on this matter, section `Man Pages' in The GNU Coding Standards.) Man pages are declared using the `MANS' primary. Generally the man_MANS macro is used. Man pages are automatically installed in the correct subdirectory of mandir, based on the file extension.

File extensions such as `.1c' are handled by looking for the valid part of the extension and using that to determine the correct subdirectory of mandir. Valid section names are the digits `0' through `9', and the letters `l' and `n'.

Sometimes developers prefer to name a man page something like `foo.man' in the source, and then rename it to have the correct suffix, e.g. `foo.1', when installing the file. Automake also supports this mode. For a valid section named SECTION, there is a corresponding directory named `manSECTIONdir', and a corresponding `_MANS' variable. Files listed in such a variable are installed in the indicated section. If the file already has a valid suffix, then it is installed as-is; otherwise the file suffix is changed to match the section.

For instance, consider this example:
man1_MANS = rename.man thesame.1 alsothesame.1c

In this case, `rename.man' will be renamed to `rename.1' when installed, but the other files will keep their names.

By default, man pages are installed by `make install'. However, since the GNU project does not require man pages, many maintainers do not expend effort to keep the man pages up to date. In these cases, the no-installman option will prevent the man pages from being installed by default. The user can still explicitly install them via `make install-man'.

Here is how the man pages are handled in GNU cpio (which includes both Texinfo documentation and man pages):

man_MANS = cpio.1 mt.1
EXTRA_DIST = $(man_MANS)

Man pages are not currently considered to be source, because it is not uncommon for man pages to be automatically generated. Therefore they are not automatically included in the distribution. However, this can be changed by use of the `dist_' prefix.

The `nobase_' prefix is meaningless for man pages and is disallowed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13. What Gets Installed

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.1 Basics of installation

Naturally, Automake handles the details of actually installing your program once it has been built. All files named by the various primaries are automatically installed in the appropriate places when the user runs make install.

A file named in a primary is installed by copying the built file into the appropriate directory. The base name of the file is used when installing.

bin_PROGRAMS = hello subdir/goodbye

In this example, both `hello' and `goodbye' will be installed in $(bindir).

Sometimes it is useful to avoid the basename step at install time. For instance, you might have a number of header files in subdirectories of the source tree which are laid out precisely how you want to install them. In this situation you can use the `nobase_' prefix to suppress the base name step. For example:

nobase_include_HEADERS = stdio.h sys/types.h

Will install `stdio.h' in $(includedir) and `types.h' in $(includedir)/sys.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.2 The two parts of install

Automake generates separate install-data and install-exec targets, in case the installer is installing on multiple machines which share directory structure--these targets allow the machine-independent parts to be installed only once. install-exec installs platform-dependent files, and install-data installs platform-independent files. The install target depends on both of these targets. While Automake tries to automatically segregate objects into the correct category, the `Makefile.am' author is, in the end, responsible for making sure this is done correctly.

Variables using the standard directory prefixes `data', `info', `man', `include', `oldinclude', `pkgdata', or `pkginclude' (e.g. `data_DATA') are installed by `install-data'.

Variables using the standard directory prefixes `bin', `sbin', `libexec', `sysconf', `localstate', `lib', or `pkglib' (e.g. `bin_PROGRAMS') are installed by `install-exec'.

Any variable using a user-defined directory prefix with `exec' in the name (e.g. `myexecbin_PROGRAMS' is installed by `install-exec'. All other user-defined prefixes are installed by `install-data'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.3 Extending installation

It is possible to extend this mechanism by defining an install-exec-local or install-data-local target. If these targets exist, they will be run at `make install' time. These rules can do almost anything; care is required.

Automake also supports two install hooks, install-exec-hook and install-data-hook. These hooks are run after all other install rules of the appropriate type, exec or data, have completed. So, for instance, it is possible to perform post-installation modifications using an install hook.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.4 Staged installs

Automake generates support for the `DESTDIR' variable in all install rules. `DESTDIR' is used during the `make install' step to relocate install objects into a staging area. Each object and path is prefixed with the value of `DESTDIR' before being copied into the install area. Here is an example of typical DESTDIR usage:

make DESTDIR=/tmp/staging install

This places install objects in a directory tree built under `/tmp/staging'. If `/gnu/bin/foo' and `/gnu/share/aclocal/foo.m4' are to be installed, the above command would install `/tmp/staging/gnu/bin/foo' and `/tmp/staging/gnu/share/aclocal/foo.m4'.

This feature is commonly used to build install images and packages. For more information, see section `Makefile Conventions' in The GNU Coding Standards.

Support for `DESTDIR' is implemented by coding it directly into the install rules. If your `Makefile.am' uses a local install rule (e.g., install-exec-local) or an install hook, then you must write that code to respect `DESTDIR'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5 Rules for the user

Automake also generates an uninstall target, an installdirs target, and an install-strip target.

Automake supports uninstall-local and uninstall-hook. There is no notion of separate uninstalls for "exec" and "data", as these features would not provide additional functionality.

Note that uninstall is not meant as a replacement for a real packaging tool.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

14. What Gets Cleaned

The GNU Makefile Standards specify a number of different clean rules. See See section `Standard Targets for Users' in The GNU Coding Standards.

Generally the files that can be cleaned are determined automatically by Automake. Of course, Automake also recognizes some variables that can be defined to specify additional files to clean. These variables are MOSTLYCLEANFILES, CLEANFILES, DISTCLEANFILES, and MAINTAINERCLEANFILES.

As the GNU Standards aren't always explicit as to which files should be removed by which target, we've adopted a heuristic which we believe was first formulated by François Pinard:

  • If make built it, and it is commonly something that one would want to rebuild (for instance, a `.o' file), then mostlyclean should delete it.

  • Otherwise, if make built it, then clean should delete it.

  • If configure built it, then distclean should delete it

  • If the maintainer built it, then maintainer-clean should delete it.

We recommend that you follow this same set of heuristics in your `Makefile.am'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15. What Goes in a Distribution

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.1 Basics of distribution

The dist target in the generated `Makefile.in' can be used to generate a gzip'd tar file and other flavors of archive for distribution. The files is named based on the `PACKAGE' and `VERSION' variables defined by AM_INIT_AUTOMAKE (see section 5.4 Autoconf macros supplied with Automake); more precisely the gzip'd tar file is named `package-version.tar.gz'. You can use the make variable `GZIP_ENV' to control how gzip is run. The default setting is `--best'.

For the most part, the files to distribute are automatically found by Automake: all source files are automatically included in a distribution, as are all `Makefile.am's and `Makefile.in's. Automake also has a built-in list of commonly used files which are automatically included if they are found in the current directory (either physically, or as the target of a `Makefile.am' rule). This list is printed by `automake --help'. Also, files which are read by configure (i.e. the source files corresponding to the files specified in various Autoconf macros such as AC_CONFIG_FILES and siblings) are automatically distributed.

Still, sometimes there are files which must be distributed, but which are not covered in the automatic rules. These files should be listed in the EXTRA_DIST variable. You can mention files from subdirectories in EXTRA_DIST.

You can also mention a directory in EXTRA_DIST; in this case the entire directory will be recursively copied into the distribution. Please note that this will also copy everything in the directory, including CVS/RCS version control files. We recommend against using this feature.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.2 Fine-grained distribution control

Sometimes you need tighter control over what does not go into the distribution; for instance you might have source files which are generated and which you do not want to distribute. In this case Automake gives fine-grained control using the `dist' and `nodist' prefixes. Any primary or `_SOURCES' variable can be prefixed with `dist_' to add the listed files to the distribution. Similarly, `nodist_' can be used to omit the files from the distribution.

As an example, here is how you would cause some data to be distributed while leaving some source code out of the distribution:

dist_data_DATA = distribute-this
bin_PROGRAMS = foo
nodist_foo_SOURCES = do-not-distribute.c

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.3 The dist hook

Another way to to use this is for removing unnecessary files that get recursively included by specifying a directory in EXTRA_DIST:

EXTRA_DIST = doc

dist-hook:
    rm -rf `find $(distdir)/doc -name CVS`

If you define SUBDIRS, Automake will recursively include the subdirectories in the distribution. If SUBDIRS is defined conditionally (see section 20. Conditionals), Automake will normally include all directories that could possibly appear in SUBDIRS in the distribution. If you need to specify the set of directories conditionally, you can set the variable DIST_SUBDIRS to the exact list of subdirectories to include in the distribution.

Occasionally it is useful to be able to change the distribution before it is packaged up. If the dist-hook target exists, it is run after the distribution directory is filled, but before the actual tar (or shar) file is created. One way to use this is for distributing files in subdirectories for which a new `Makefile.am' is overkill:

dist-hook:
        mkdir $(distdir)/random
        cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.4 Checking the distribution

Automake also generates a distcheck target which can be of help to ensure that a given distribution will actually work. distcheck makes a distribution, then tries to do a VPATH build, run the testsuite, and finally make another tarfile to ensure the distribution is self-contained.

Building the package involves running ./configure. If you need to supply additional flags to configure, define them in the DISTCHECK_CONFIGURE_FLAGS variable, either in your top-level `Makefile.am', or on the commande line when invoking make.

If the target distcheck-hook is defined in your `Makefile.am', then it will be invoked by distcheck after the new distribution has been unpacked, but before the unpacked copy is configured and built. Your distcheck-hook can do almost anything, though as always caution is advised. Generally this hook is used to check for potential distribution errors not caught by the standard mechanism.

Speaking about potential distribution errors, distcheck will also ensure that the distclean target actually removes all built files. This is done by running make distcleancheck at the end of the VPATH build. By default, distcleancheck will run distclean and then make sure the build tree has been emptied by running $(distcleancheck_listfiles). Usually this check will find generated files that you forgot to add to the DISTCLEANFILES variable (see section 14. What Gets Cleaned).

The distcleancheck behaviour should be ok for most packages, otherwise you have the possibility to override the definitition of either the distcleancheck target, or the $(distcleancheck_listfiles) variable. For instance to disable distcleancheck completely, add the following rule to your top-level `Makefile.am':

distcleancheck:
        @:

If you want distcleancheck to ignore built files which have not been cleaned because they are also part of the distribution, add the following definition instead:

distcleancheck_listfiles = \
  find -type f -exec sh -c 'test -f $(scrdir)/{} || echo {}'

The above definition is not the default because it's usually an error if your Makefiles cause some distributed files to be rebuilt when the user build the package. (Think about the user missing the tool required to build the file; or if the required tool is built by your package, consider the cross-compilation case where it can't be run.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.5 The types of distributions

Automake generates a `.tar.gz' file when asked to create a distribution and other archives formats, 17. Changing Automake's Behavior. The target dist-gzip generates the `.tar.gz' file only.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16. Support for test suites

Automake supports two forms of test suites.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1 Simple Tests

If the variable TESTS is defined, its value is taken to be a list of programs to run in order to do the testing. The programs can either be derived objects or source objects; the generated rule will look both in srcdir and `.'. Programs needing data files should look for them in srcdir (which is both an environment variable and a make variable) so they work when building in a separate directory (see section `Build Directories' in The Autoconf Manual), and in particular for the distcheck target (see section 15. What Goes in a Distribution).

The number of failures will be printed at the end of the run. If a given test program exits with a status of 77, then its result is ignored in the final count. This feature allows non-portable tests to be ignored in environments where they don't make sense.

The variable TESTS_ENVIRONMENT can be used to set environment variables for the test run; the environment variable srcdir is set in the rule. If all your test programs are scripts, you can also set TESTS_ENVIRONMENT to an invocation of the shell (e.g. `$(SHELL) -x'); this can be useful for debugging the tests.

You may define the variable XFAIL_TESTS to a list of tests (usually a subset of TESTS) that are expected to fail. This will reverse the result of those tests.

Automake ensures that each program listed in TESTS is built before any tests are run; you can list both source and derived programs in TESTS. For instance, you might want to run a C program as a test. To do this you would list its name in TESTS and also in check_PROGRAMS, and then specify it as you would any other program.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2 DejaGNU Tests

If `dejagnu' appears in AUTOMAKE_OPTIONS, then a dejagnu-based test suite is assumed. The variable DEJATOOL is a list of names which are passed, one at a time, as the --tool argument to runtest invocations; it defaults to the name of the package.

The variable RUNTESTDEFAULTFLAGS holds the --tool and --srcdir flags that are passed to dejagnu by default; this can be overridden if necessary.

The variables EXPECT and RUNTEST can also be overridden to provide project-specific values. For instance, you will need to do this if you are testing a compiler toolchain, because the default values do not take into account host and target names.

The contents of the variable RUNTESTFLAGS are passed to the runtest invocation. This is considered a "user variable" (see section 2.5 Variables reserved for the user). If you need to set runtest flags in `Makefile.am', you can use AM_RUNTESTFLAGS instead.

In either case, the testing is done via `make check'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.3 Install Tests

The installcheck target is available to the user as a way to run any tests after the package has been installed. You can add tests to this by writing an installcheck-local target.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17. Changing Automake's Behavior

Various features of Automake can be controlled by options in the `Makefile.am'. Such options are applied on a per-`Makefile' basis when listed in a special `Makefile' variable named AUTOMAKE_OPTIONS. They are applied globally to all processed `Makefiles' when listed in the first argument of AM_INIT_AUTOMAKE in `configure.in'. Currently understood options are:

gnits
gnu
foreign
cygnus

Set the strictness as appropriate. The gnits option also implies readme-alpha and check-news.

ansi2knr
path/ansi2knr
Turn on automatic de-ANSI-fication. See section 9.13 Automatic de-ANSI-fication. If preceded by a path, the generated `Makefile.in' will look in the specified directory to find the `ansi2knr' program. The path should be a relative path to another directory in the same distribution (Automake currently does not check this).

check-news
Cause make dist to fail unless the current version number appears in the first few lines of the `NEWS' file.

dejagnu
Cause dejagnu-specific rules to be generated. See section 16. Support for test suites.

dist-bzip2
Generate a dist-bzip2 target, creating a bzip2 tar archive of the distribution. dist will create it in addition to the other formats. bzip2 archives are frequently smaller than gzipped archives.

dist-shar
Generate a dist-shar target, creating a shar archive of the distribution. dist will create it in addition to the other formats.

dist-zip
Generate a dist-zip target, creating a zip archive of the distribution. dist will create it in addition to the other formats.

dist-tarZ
Generate a dist-tarZ target, creating a compressed tar archive of the distribution. dist will create it in addition to the other formats.

no-define
This options is meaningful only when passed as an argument to AM_INIT_AUTOMAKE. It will prevent the PACKAGE and VERSION variable to be AC_DEFINEd.

no-dependencies
This is similar to using `--include-deps' on the command line, but is useful for those situations where you don't have the necessary bits to make automatic dependency tracking work See section 9.14 Automatic dependency tracking. In this case the effect is to effectively disable automatic dependency tracking.

no-exeext
If your `Makefile.am' defines a target `foo', it will override a target named `foo$(EXEEXT)'. This is necessary when EXEEXT is found to be empty. However, by default automake will generate an error for this use. The no-exeext option will disable this error. This is intended for use only where it is known in advance that the package will not be ported to Windows, or any other operating system using extensions on executables.

no-installinfo
The generated `Makefile.in' will not cause info pages to be built or installed by default. However, info and install-info targets will still be available. This option is disallowed at `GNU' strictness and above.

no-installman
The generated `Makefile.in' will not cause man pages to be installed by default. However, an install-man target will still be available for optional installation. This option is disallowed at `GNU' strictness and above.

nostdinc
This option can be used to disable the standard `-I' options which are ordinarily automatically provided by Automake.

no-texinfo.tex
Don't require `texinfo.tex', even if there are texinfo files in this directory.

readme-alpha
If this release is an alpha release, and the file `README-alpha' exists, then it will be added to the distribution. If this option is given, version numbers are expected to follow one of two forms. The first form is `MAJOR.MINOR.ALPHA', where each element is a number; the final period and number should be left off for non-alpha releases. The second form is `MAJOR.MINORALPHA', where ALPHA is a letter; it should be omitted for non-alpha releases.

subdir-objects
If this option is specified, then objects are placed into the subdirectory of the build directory corresponding to the subdirectory of the source file. For instance if the source file is `subdir/file.cxx', then the output file would be `subdir/file.o'.

version
A version number (e.g. `0.30') can be specified. If Automake is not newer than the version specified, creation of the `Makefile.in' will be suppressed.

Unrecognized options are diagnosed by automake.

If you want an option to apply to all the files in the tree, you can use the AM_AUTOMAKE_OPTIONS macro in `configure.in'. See section 5.4 Autoconf macros supplied with Automake.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

18. Miscellaneous Rules

There are a few rules and variables that didn't fit anywhere else.

18.1 Interfacing to etags | Interfacing to etags and mkid
18.2 Handling new file extensions
18.3 Support for Multilibs | Support for multilibbing.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

18.1 Interfacing to etags

Automake will generate rules to generate `TAGS' files for use with GNU Emacs under some circumstances.

If any C, C++ or Fortran 77 source code or headers are present, then tags and TAGS targets will be generated for the directory.

At the topmost directory of a multi-directory package, a tags target file will be generated which, when run, will generate a `TAGS' file that includes by reference all `TAGS' files from subdirectories.

The tags target will also be generated if the variable ETAGS_ARGS is defined. This variable is intended for use in directories which contain taggable source that etags does not understand. The user can use the ETAGSFLAGS to pass additional flags to etags; AM_ETAGSFLAGS is also available for use in `Makefile.am'.

Here is how Automake generates tags for its source, and for nodes in its Texinfo file:

ETAGS_ARGS = automake.in --lang=none \
 --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi

If you add filenames to `ETAGS_ARGS', you will probably also want to set `TAGS_DEPENDENCIES'. The contents of this variable are added directly to the dependencies for the tags target.

Automake will also generate an ID target which will run mkid on the source. This is only supported on a directory-by-directory basis.

Automake also supports the GNU Global Tags program. The GTAGS target runs Global Tags automatically and puts the result in the top build directory. The variable GTAGS_ARGS holds arguments which are passed to gtags.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

18.2 Handling new file extensions

It is sometimes useful to introduce a new implicit rule to handle a file type that Automake does not know about.

For instance, suppose you had a compiler which could compile `.foo' files to `.o' files. You would simply define an suffix rule for your language:

.foo.o:
        foocc -c -o $@ $<

Then you could directly use a `.foo' file in a `_SOURCES' variable and expect the correct results:

bin_PROGRAMS = doit
doit_SOURCES = doit.foo

This was the simpler and more common case. In other cases, you will have to help Automake to figure which extensions you are defining your suffix rule for. This usually happens when your extensions does not start with a dot. Then, all you have to do is to put a list of new suffixes in the SUFFIXES variable before you define your implicit rule.

For instance the following definition prevents Automake to misinterpret `.idlC.cpp:' as an attemp to transform `.idlC' into `.cpp'.

SUFFIXES = .idl C.cpp
.idlC.cpp:
        # whatever

As you may have noted, the SUFFIXES macro behaves like the .SUFFIXES special target of make. You should not touch .SUFFIXES yourself, but use SUFFIXES instead and let Automake generate the suffix list for .SUFFIXES. Any given SUFFIXES go at the start of the generated suffixes list, followed by Automake generated suffixes not already in the list.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

18.3 Support for Multilibs

Automake has support for an obscure feature called multilibs. A multilib is a library which is built for multiple different ABIs at a single time; each time the library is built with a different target flag combination. This is only useful when the library is intended to be cross-compiled, and it is almost exclusively used for compiler support libraries.

The multilib support is still experimental. Only use it if you are familiar with multilibs and can debug problems you might encounter.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

19. Include

Automake supports an include directive which can be used to include other `Makefile' fragments when automake is run. Note that these fragments are read and interpreted by automake, not by make. As with conditionals, make has no idea that include is in use.

There are two forms of include:

include $(srcdir)/file
Include a fragment which is found relative to the current source directory.

include $(top_srcdir)/file
Include a fragment which is found relative to the top source directory.

Note that if a fragment is included inside a conditional, then the condition applies to the entire contents of that fragment.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

20. Conditionals

Automake supports a simple type of conditionals.

Before using a conditional, you must define it by using AM_CONDITIONAL in the configure.in file (see section 5.4 Autoconf macros supplied with Automake).

Macro: AM_CONDITIONAL (conditional, condition)
The conditional name, conditional, should be a simple string starting with a letter and containing only letters, digits, and underscores. It must be different from `TRUE' and `FALSE' which are reserved by Automake.

The shell condition (suitable for use in a shell if statement) is evaluated when configure is run. Note that you must arrange for every AM_CONDITIONAL to be invoked every time configure is run -- if AM_CONDITIONAL is run conditionally (e.g., in a shell if statement), then the result will confuse automake.

Conditionals typically depend upon options which the user provides to the configure script. Here is an example of how to write a conditional which is true if the user uses the `--enable-debug' option.

AC_ARG_ENABLE(debug,
[  --enable-debug    Turn on debugging],
[case "${enableval}" in
  yes) debug=true ;;
  no)  debug=false ;;
  *) AC_MSG_ERROR(bad value ${enableval} for --enable-debug) ;;
esac],[debug=false])
AM_CONDITIONAL(DEBUG, test x$debug = xtrue)

Here is an example of how to use that conditional in `Makefile.am':

if DEBUG
DBG = debug
else
DBG =
endif
noinst_PROGRAMS = $(DBG)

This trivial example could also be handled using EXTRA_PROGRAMS (see section 9.1 Building a program).

You may only test a single variable in an if statement, possibly negated using `!'. The else statement may be omitted. Conditionals may be nested to any depth. You may specify an argument to else in which case it must be the negation of the condition used for the current if. Similarly you may specify the condition which is closed by an end:

if DEBUG
DBG = debug
else !DEBUG
DBG =
endif !DEBUG

Unbalanced conditions are errors.

Conditionals do not interact very smoothly with the append operator. In particular, an append must happen in the same conditional context as the original assignment. This means that the following will not work:

DBG = foo
if DEBUG
DBG += bar
endif DEBUG

The behaviour which is probably desired in this situation can be obtained using a temporary variable:

if DEBUG
TMP_DBG = bar
endif DEBUG
DBG = foo $(TMP_DBG)

This restriction may be lifted in future versions of automake.

Note that conditionals in Automake are not the same as conditionals in GNU Make. Automake conditionals are checked at configure time by the `configure' script, and affect the translation from `Makefile.in' to `Makefile'. They are based on options passed to `configure' and on results that `configure' has discovered about the host system. GNU Make conditionals are checked at make time, and are based on variables passed to the make program or defined in the `Makefile'.

Automake conditionals will work with any make program.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

21. The effect of --gnu and --gnits

The `--gnu' option (or `gnu' in the `AUTOMAKE_OPTIONS' variable) causes automake to check the following:

  • The files `INSTALL', `NEWS', `README', `COPYING', `AUTHORS', and `ChangeLog' are required at the topmost directory of the package.

  • The options `no-installman' and `no-installinfo' are prohibited.

Note that this option will be extended in the future to do even more checking; it is advisable to be familiar with the precise requirements of the GNU standards. Also, `--gnu' can require certain non-standard GNU programs to exist for use by various maintainer-only targets; for instance in the future pathchk might be required for `make dist'.

The `--gnits' option does everything that `--gnu' does, and checks the following as well:

  • `make dist' will check to make sure the `NEWS' file has been updated to the current version.

  • `VERSION' is checked to make sure its format complies with Gnits standards.

  • If `VERSION' indicates that this is an alpha release, and the file `README-alpha' appears in the topmost directory of a package, then it is included in the distribution. This is done in `--gnits' mode, and no other, because this mode is the only one where version number formats are constrained, and hence the only mode where Automake can automatically determine whether `README-alpha' should be included.

  • The file `THANKS' is required.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

22. The effect of --cygnus

Some packages, notably GNU GCC and GNU gdb, have a build environment originally written at Cygnus Support (subsequently renamed Cygnus Solutions, and then later purchased by Red Hat). Packages with this ancestry are sometimes referred to as "Cygnus" trees.

A Cygnus tree has slightly different rules for how a `Makefile.in' is to be constructed. Passing `--cygnus' to automake will cause any generated `Makefile.in' to comply with Cygnus rules.

Here are the precise effects of `--cygnus':

  • Info files are always created in the build directory, and not in the source directory.

  • `texinfo.tex' is not required if a Texinfo source file is specified. The assumption is that the file will be supplied, but in a place that Automake cannot find. This assumption is an artifact of how Cygnus packages are typically bundled.

  • `make dist' is not supported, and the rules for it are not generated. Cygnus-style trees use their own distribution mechanism.

  • Certain tools will be searched for in the build tree as well as in the user's `PATH'. These tools are runtest, expect, makeinfo and texi2dvi.

  • --foreign is implied.

  • The options `no-installinfo' and `no-dependencies' are implied.

  • The macros `AM_MAINTAINER_MODE' and `AM_CYGWIN32' are required.

  • The check target doesn't depend on all.

GNU maintainers are advised to use `gnu' strictness in preference to the special Cygnus mode. Some day, perhaps, the differences between Cygnus trees and GNU trees will disappear (for instance, as GCC is made more standards compliant). At that time the special Cygnus mode will be removed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

23. When Automake Isn't Enough

Automake's implicit copying semantics means that many problems can be worked around by simply adding some make targets and rules to `Makefile.in'. Automake will ignore these additions.

There are some caveats to doing this. Although you can overload a target already used by Automake, it is often inadvisable, particularly in the topmost directory of a package with subdirectories. However, various useful targets have a `-local' version you can specify in your `Makefile.in'. Automake will supplement the standard target with these user-supplied targets.

The targets that support a local version are all, info, dvi, check, install-data, install-exec, uninstall, installdirs, installcheck and the various clean targets (mostlyclean, clean, distclean, and maintainer-clean). Note that there are no uninstall-exec-local or uninstall-data-local targets; just use uninstall-local. It doesn't make sense to uninstall just data or just executables.

For instance, here is one way to install a file in `/etc':

install-data-local:
        $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile

Some targets also have a way to run another target, called a hook, after their work is done. The hook is named after the principal target, with `-hook' appended. The targets allowing hooks are install-data, install-exec, uninstall, dist, and distcheck.

For instance, here is how to create a hard link to an installed program:

install-exec-hook:
        ln $(DESTDIR)$(bindir)/program $(DESTDIR)$(bindir)/proglink

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

24. Distributing `Makefile.in's

Automake places no restrictions on the distribution of the resulting `Makefile.in's. We still encourage software authors to distribute their work under terms like those of the GPL, but doing so is not required to use Automake.

Some of the files that can be automatically installed via the --add-missing switch do fall under the GPL. However, these also have a special exception allowing you to distribute them with your package, regardless of the licensing you choose.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

25. Automake API versioning

New Automake releases usually include bug fixes and new features. Unfortunately they may also introduce new bugs and incompatibilities. This make four reasons why a package may require a particular Automake version.

Things get worse when maintaining a large tree of packages, each one requiring a different version of Automake. In the past, this meant that any developer (and sometime users) had to install several versions of Automake in different places, and switch `$PATH' appropriately for each package.

Starting with version 1.6, Automake installs versioned binaries. This means you can install several versions of Automake in the same `$prefix', and can select an arbitrary Automake version by running `automake-1.6' or `automake-1.7' without juggling with `$PATH'. Furthermore, `Makefile''s generated by Automake 1.6 will use `automake-1.6' explicitely in their rebuild rules.

Note that `1.6' in `automake-1.6' is Automake's API version, not Automake's version. If a bug fix release is made, for instance Automake 1.6.1, the API version will remain 1.6. This means that a package which work with Automake 1.6 should also work with 1.6.1; after all, this is what people expect from bug fix releases.

Note that if your package relies on a feature or a bug fix introduced in a release, you can pass this version as an option to Automake to ensure older releases will not be used. For instance, use this in your `configure.in':

  AM_INIT_AUTOMAKE(1.6.1)    dnl Require Automake 1.6.1 or better.
or, in a particular `Makefile.am':

  AUTOMAKE_OPTIONS = 1.6.1   # Require Automake 1.6.1 or better.
Automake will print an error message if its version is older than the requested version.

What is in the API

Automake's programing interface is not easy to define. Basically it should include at least all documented variables and targets that a `Makefile.am' authors can use, the behaviours associated to them (e.g. the places where `-hook''s are run), the command line interface of `automake' and `aclocal', ...

What is not in the API

Every undocumented variable, target, or command line option, is not part of the API. You should avoid using them, as they could change from one version to the other (even in bug fix releases, if this helps to fix a bug).

If it turns out you need to use such a undocumented feature, contact automake@gnu.org and try to get it documented and exercised by the test-suite.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Macro and Variable Index

Jump to: _
A B C D E F G H I J L M N O P R S T V W X Y

 | Index Entry | Section
_ |  |
 | _LDADD | 9.1.3 Linking the program
 | _LDFLAGS | 9.1.3 Linking the program
 | _LIBADD | 9.2 Building a library
 | _SOURCES | 9.1.1 Introductory blathering
 | _TEXINFOS | 12.1 Texinfo
A |  |
 | AC_CANONICAL_HOST | 5.2 Other things Automake recognizes
 | AC_CANONICAL_SYSTEM | 5.2 Other things Automake recognizes
 | AC_CHECK_PROG | 5.2 Other things Automake recognizes
 | AC_CHECK_PROGS | 5.2 Other things Automake recognizes
 | AC_CHECK_TOOL | 5.2 Other things Automake recognizes
 | AC_CONFIG_AUX_DIR | 5.2 Other things Automake recognizes
 | AC_CONFIG_HEADER | 5.2 Other things Automake recognizes
 | AC_F77_LIBRARY_LDFLAGS | 5.2 Other things Automake recognizes
 | AC_FUNC_ALLOCA | 5.2 Other things Automake recognizes
 | AC_FUNC_ERROR_AT_LINE | 5.2 Other things Automake recognizes
 | AC_FUNC_FNMATCH | 5.2 Other things Automake recognizes
 | AC_FUNC_GETLOADAVG | 5.2 Other things Automake recognizes
 | AC_FUNC_MEMCMP | 5.2 Other things Automake recognizes
 | AC_FUNC_MKTIME | 5.2 Other things Automake recognizes
 | AC_FUNC_OBSTACK | 5.2 Other things Automake recognizes
 | AC_FUNC_STRTOD | 5.2 Other things Automake recognizes
 | AC_LIBOBJ | 5.2 Other things Automake recognizes
 | AC_LIBSOURCE | 5.2 Other things Automake recognizes
 | AC_LIBSOURCES | 5.2 Other things Automake recognizes
 | AC_OUTPUT | 5.1 Configuration requirements
 | AC_PATH_PROG | 5.2 Other things Automake recognizes
 | AC_PATH_PROGS | 5.2 Other things Automake recognizes
 | AC_PATH_XTRA | 5.2 Other things Automake recognizes
 | AC_PROG_CXX | 5.2 Other things Automake recognizes
 | AC_PROG_F77 | 5.2 Other things Automake recognizes
 | AC_PROG_LEX | 5.2 Other things Automake recognizes
 | AC_PROG_LIBTOOL | 5.2 Other things Automake recognizes
 | AC_PROG_RANLIB | 5.2 Other things Automake recognizes
 | AC_PROG_YACC | 5.2 Other things Automake recognizes
 | AC_REPLACE_FUNCS | 5.2 Other things Automake recognizes
 | AC_REPLACE_GNU_GETOPT | 5.2 Other things Automake recognizes
 | AC_STRUCT_ST_BLOCKS | 5.2 Other things Automake recognizes
 | AC_SUBST | 5.2 Other things Automake recognizes
 | ACLOCAL_AMFLAGS | 8. Rebuilding Makefiles
 | AM_C_PROTOTYPES | 5.2 Other things Automake recognizes
 | AM_C_PROTOTYPES | 5.4.1 Public macros
 | AM_C_PROTOTYPES | 9.13 Automatic de-ANSI-fication
 | AM_CFLAGS | 9.6 Variables used when building a program
 | AM_CFLAGS | 9.6 Variables used when building a program
 | AM_CONDITIONAL | 20. Conditionals
 | AM_CONFIG_HEADER | 5.4.1 Public macros
 | AM_CPPFLAGS | 9.6 Variables used when building a program
 | AM_CPPFLAGS | 9.6 Variables used when building a program
 | am_cv_sys_posix_termios | 5.4.1 Public macros
 | AM_CXXFLAGS | 9.8 C++ Support
 | AM_CXXFLAGS | 9.8 C++ Support
 | AM_ETAGSFLAGS | 18.1 Interfacing to etags
 | AM_FFLAGS | 9.10 Fortran 77 Support
 | AM_FFLAGS | 9.10 Fortran 77 Support
 | AM_GCJFLAGS | 9.11 Java Support
 | AM_GNU_GETTEXT | 5.2 Other things Automake recognizes
 | AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL | 5.4.1 Public macros
 | AM_INIT_AUTOMAKE | 5.1 Configuration requirements
 | AM_JAVACFLAGS | 11.4 Java
 | AM_JAVACFLAGS | 11.4 Java
 | AM_LDFLAGS | 9.1.3 Linking the program
 | AM_LDFLAGS | 9.6 Variables used when building a program
 | AM_LDFLAGS | 9.6 Variables used when building a program
 | AM_MAINTAINER_MODE | 5.2 Other things Automake recognizes
 | AM_MAKEINFOFLAGS | 12.1 Texinfo
 | AM_PATH_LISPDIR | 5.4.1 Public macros
 | AM_PROG_GCJ | 5.4.1 Public macros
 | AM_RFLAGS | 9.10 Fortran 77 Support
 | AM_RFLAGS | 9.10 Fortran 77 Support
 | AM_RUNTESTFLAGS | 16.2 DejaGNU Tests
 | AM_WITH_REGEX | 5.2 Other things Automake recognizes
 | AUTOMAKE_OPTIONS | 9.13 Automatic de-ANSI-fication
 | AUTOMAKE_OPTIONS | 9.14 Automatic dependency tracking
 | AUTOMAKE_OPTIONS | 17. Changing Automake's Behavior
B |  |
 | bin_PROGRAMS | 9.1.1 Introductory blathering
 | bin_SCRIPTS | 10.1 Executable Scripts
 | build_alias | 5.2 Other things Automake recognizes
 | BUILT_SOURCES | 10.4 Built sources
C |  |
 | CC | 9.6 Variables used when building a program
 | CCAS | 9.9 Assembly Support
 | CCASFLAGS | 9.9 Assembly Support
 | CFLAGS | 9.6 Variables used when building a program
 | check_LTLIBRARIES | 9.3 Building a Shared Library
 | check_PROGRAMS | 9.1.1 Introductory blathering
 | check_SCRIPTS | 10.1 Executable Scripts
 | CLASSPATH_ENV | 11.4 Java
 | CLASSPATH_ENV | 11.4 Java
 | CLEANFILES | 14. What Gets Cleaned
 | COMPILE | 9.6 Variables used when building a program
 | COMPILE | 9.6 Variables used when building a program
 | CPPFLAGS | 9.6 Variables used when building a program
 | CXX | 9.8 C++ Support
 | CXX | 9.8 C++ Support
 | CXXCOMPILE | 9.8 C++ Support
 | CXXCOMPILE | 9.8 C++ Support
 | CXXFLAGS | 9.8 C++ Support
 | CXXFLAGS | 9.8 C++ Support
 | CXXLINK | 9.8 C++ Support
 | CXXLINK | 9.8 C++ Support
D |  |
 | DATA | 2.3 The Uniform Naming Scheme
 | DATA | 10.3 Architecture-independent data files
 | data_DATA | 10.3 Architecture-independent data files
 | DEFS | 9.6 Variables used when building a program
 | DEJATOOL | 16.2 DejaGNU Tests
 | DESTDIR | 13.4 Staged installs
 | dist_ | 15.2 Fine-grained distribution control
 | DIST_SUBDIRS | 15.3 The dist hook
 | DISTCHECK_CONFIGURE_FLAGS | 15.4 Checking the distribution
 | distcleancheck_listfiles | 15.4 Checking the distribution
 | distcleancheck_listfiles | 15.4 Checking the distribution
 | DISTCLEANFILES | 14. What Gets Cleaned
E |  |
 | ELCFILES | 11.1 Emacs Lisp
 | ETAGS_ARGS | 18.1 Interfacing to etags
 | ETAGSFLAGS | 18.1 Interfacing to etags
 | EXPECT | 16.2 DejaGNU Tests
 | EXTRA_DIST | 15.1 Basics of distribution
 | EXTRA_PROGRAMS | 9.1.2 Conditional compilations
F |  |
 | F77 | 9.10 Fortran 77 Support
 | F77 | 9.10 Fortran 77 Support
 | F77COMPILE | 9.10 Fortran 77 Support
 | F77COMPILE | 9.10 Fortran 77 Support
 | FFLAGS | 9.10 Fortran 77 Support
 | FFLAGS | 9.10 Fortran 77 Support
 | FLINK | 9.10 Fortran 77 Support
 | FLINK | 9.10 Fortran 77 Support
G |  |
 | GCJFLAGS | 9.11 Java Support
 | GTAGS_ARGS | 18.1 Interfacing to etags
H |  |
 | HEADERS | 2.3 The Uniform Naming Scheme
 | HEADERS | 10.2 Header files
 | host_alias | 5.2 Other things Automake recognizes
 | host_triplet | 5.2 Other things Automake recognizes
I |  |
 | include_HEADERS | 10.2 Header files
 | INCLUDES | 9.6 Variables used when building a program
 | INCLUDES | 9.6 Variables used when building a program
 | info_TEXINFOS | 12.1 Texinfo
J |  |
 | JAVA | 2.3 The Uniform Naming Scheme
 | JAVAC | 11.4 Java
 | JAVAC | 11.4 Java
 | JAVACFLAGS | 11.4 Java
 | JAVACFLAGS | 11.4 Java
 | JAVAROOT | 11.4 Java
 | JAVAROOT | 11.4 Java
L |  |
 | LDADD | 9.1.3 Linking the program
 | LDFLAGS | 9.6 Variables used when building a program
 | lib_LIBRARIES | 9.2 Building a library
 | lib_LTLIBRARIES | 9.3 Building a Shared Library
 | LIBADD | 9.2 Building a library
 | libexec_PROGRAMS | 9.1.1 Introductory blathering
 | libexec_SCRIPTS | 10.1 Executable Scripts
 | LIBOBJS | 5.2 Other things Automake recognizes
 | LIBRARIES | 2.3 The Uniform Naming Scheme
 | LIBS | 9.6 Variables used when building a program
 | LINK | 9.6 Variables used when building a program
 | LINK | 9.6 Variables used when building a program
 | LISP | 2.3 The Uniform Naming Scheme
 | LISP | 11.1 Emacs Lisp
 | lisp_LISP | 11.1 Emacs Lisp
 | localstate_DATA | 10.3 Architecture-independent data files
M |  |
 | MAINTAINERCLEANFILES | 14. What Gets Cleaned
 | MAKE | 6. The top-level `Makefile.am'
 | MAKEFLAGS | 6. The top-level `Makefile.am'
 | MAKEINFO | 12.1 Texinfo
 | MAKEINFOFLAGS | 12.1 Texinfo
 | man_MANS | 12.2 Man pages
 | MANS | 2.3 The Uniform Naming Scheme
 | MANS | 12.2 Man pages
 | MOSTLYCLEANFILES | 14. What Gets Cleaned
N |  |
 | nodist_ | 15.2 Fine-grained distribution control
 | noinst_HEADERS | 10.2 Header files
 | noinst_LIBRARIES | 9.2 Building a library
 | noinst_LISP | 11.1 Emacs Lisp
 | noinst_LTLIBRARIES | 9.3 Building a Shared Library
 | noinst_PROGRAMS | 9.1.1 Introductory blathering
 | noinst_SCRIPTS | 10.1 Executable Scripts
O |  |
 | oldinclude_HEADERS | 10.2 Header files
P |  |
 | PACKAGE | 15.1 Basics of distribution
 | PACKAGE, directory | 2.3 The Uniform Naming Scheme
 | PACKAGE, prevent definition | 5.4.1 Public macros
 | pkgdata_DATA | 10.3 Architecture-independent data files
 | pkgdata_SCRIPTS | 10.1 Executable Scripts
 | pkgdatadir | 2.3 The Uniform Naming Scheme
 | pkginclude_HEADERS | 10.2 Header files
 | pkgincludedir | 2.3 The Uniform Naming Scheme
 | pkglib_LIBRARIES | 9.2 Building a library
 | pkglib_LTLIBRARIES | 9.3 Building a Shared Library
 | pkglib_PROGRAMS | 9.1.1 Introductory blathering
 | pkglibdir | 2.3 The Uniform Naming Scheme
 | pkgpyexecdir | 11.5 Python
 | pkgpyexecdir | 11.5 Python
 | pkgpythondir | 11.5 Python
 | pkgpythondir | 11.5 Python
 | PROGRAMS | 2.3 The Uniform Naming Scheme
 | PROGRAMS | 2.3 The Uniform Naming Scheme
 | pyexecdir | 11.5 Python
 | pyexecdir | 11.5 Python
 | PYTHON | 2.3 The Uniform Naming Scheme
 | PYTHON | 11.5 Python
 | PYTHON | 11.5 Python
 | PYTHON_EXEC_PREFIX | 11.5 Python
 | PYTHON_EXEC_PREFIX | 11.5 Python
 | PYTHON_PLATFORM | 11.5 Python
 | PYTHON_PLATFORM | 11.5 Python
 | PYTHON_PREFIX | 11.5 Python
 | PYTHON_PREFIX | 11.5 Python
 | PYTHON_VERSION | 11.5 Python
 | PYTHON_VERSION | 11.5 Python
 | pythondir | 11.5 Python
 | pythondir | 11.5 Python
R |  |
 | RFLAGS | 9.10 Fortran 77 Support
 | RFLAGS | 9.10 Fortran 77 Support
 | RUNTEST | 16.2 DejaGNU Tests
 | RUNTESTDEFAULTFLAGS | 16.2 DejaGNU Tests
 | RUNTESTFLAGS | 16.2 DejaGNU Tests
S |  |
 | sbin_PROGRAMS | 9.1.1 Introductory blathering
 | sbin_SCRIPTS | 10.1 Executable Scripts
 | SCRIPTS | 2.3 The Uniform Naming Scheme
 | SCRIPTS | 10.1 Executable Scripts
 | sharedstate_DATA | 10.3 Architecture-independent data files
 | SOURCES | 9.1.1 Introductory blathering
 | SUBDIRS | 6. The top-level `Makefile.am'
 | SUFFIXES | 18.2 Handling new file extensions
 | sysconf_DATA | 10.3 Architecture-independent data files
T |  |
 | TAGS_DEPENDENCIES | 18.1 Interfacing to etags
 | target_alias | 5.2 Other things Automake recognizes
 | TESTS | 16.1 Simple Tests
 | TESTS_ENVIRONMENT | 16.1 Simple Tests
 | TEXINFO_TEX | 12.1 Texinfo
 | TEXINFOS | 2.3 The Uniform Naming Scheme
 | TEXINFOS | 12.1 Texinfo
 | TEXINFOS | 12.1 Texinfo
V |  |
 | VERSION | 15.1 Basics of distribution
 | VERSION, prevent definition | 5.4.1 Public macros
W |  |
 | WITH_DMALLOC | 5.4.1 Public macros
 | WITH_REGEX | 5.4.1 Public macros
X |  |
 | XFAIL_TESTS | 16.1 Simple Tests
Y |  |
 | YACC | 5.2 Other things Automake recognizes

Jump to: _
A B C D E F G H I J L M N O P R S T V W X Y

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

General Index

Jump to: # - @ _
A B C D E F G H I J L M N O P R S T U V W Y Z

 | Index Entry | Section
# |  |
 | ## (special Automake comment) | 2.1 General Operation
- |  |
 | --acdir | 5.3 Auto-generating aclocal.m4
 | --add-missing | 4. Creating a `Makefile.in'
 | --copy | 4. Creating a `Makefile.in'
 | --cygnus | 4. Creating a `Makefile.in'
 | --enable-debug, example | 20. Conditionals
 | --enable-maintainer-mode | 5.2 Other things Automake recognizes
 | --force-missing | 4. Creating a `Makefile.in'
 | --foreign | 4. Creating a `Makefile.in'
 | --gnits | 4. Creating a `Makefile.in'
 | --gnits, complete description | 21. The effect of --gnu and --gnits
 | --gnu | 4. Creating a `Makefile.in'
 | --gnu, complete description | 21. The effect of --gnu and --gnits
 | --gnu, required files | 21. The effect of --gnu and --gnits
 | --help | 4. Creating a `Makefile.in'
 | --help | 5.3 Auto-generating aclocal.m4
 | --include-deps | 4. Creating a `Makefile.in'
 | --libdir | 4. Creating a `Makefile.in'
 | --no-force | 4. Creating a `Makefile.in'
 | --output | 5.3 Auto-generating aclocal.m4
 | --output-dir | 4. Creating a `Makefile.in'
 | --print-ac-dir | 5.3 Auto-generating aclocal.m4
 | --verbose | 4. Creating a `Makefile.in'
 | --verbose | 5.3 Auto-generating aclocal.m4
 | --version | 4. Creating a `Makefile.in'
 | --version | 5.3 Auto-generating aclocal.m4
 | --Werror | 4. Creating a `Makefile.in'
 | --with-dmalloc | 5.4.1 Public macros
 | --with-regex | 5.4.1 Public macros
 | --Wno-error | 4. Creating a `Makefile.in'
 | -a | 4. Creating a `Makefile.in'
 | -c | 4. Creating a `Makefile.in'
 | -f | 4. Creating a `Makefile.in'
 | -hook targets | 23. When Automake Isn't Enough
 | -I | 5.3 Auto-generating aclocal.m4
 | -i | 4. Creating a `Makefile.in'
 | -local targets | 23. When Automake Isn't Enough
 | -o | 4. Creating a `Makefile.in'
 | -v | 4. Creating a `Makefile.in'
@ |  |
 | @ALLOCA@, special handling | 9.5 Special handling for LIBOBJS and ALLOCA
 | @LIBOBJS@, special handling | 9.5 Special handling for LIBOBJS and ALLOCA
 | @LTLIBOBJS@, special handling | 9.3 Building a Shared Library
_ |  |
 | _DATA primary, defined | 10.3 Architecture-independent data files
 | _DEPENDENCIES, defined | 9.1.3 Linking the program
 | _HEADERS primary, defined | 10.2 Header files
 | _JAVA primary, defined | 11.4 Java
 | _LDFLAGS, defined | 9.1.3 Linking the program
 | _LIBADD primary, defined | 9.2 Building a library
 | _LIBRARIES primary, defined | 9.2 Building a library
 | _LISP primary, defined | 11.1 Emacs Lisp
 | _LTLIBRARIES primary, defined | 9.3 Building a Shared Library
 | _MANS primary, defined | 12.2 Man pages
 | _PROGRAMS primary variable | 2.3 The Uniform Naming Scheme
 | _PYTHON primary, defined | 11.5 Python
 | _SCRIPTS primary, defined | 10.1 Executable Scripts
 | _SOURCES and header files | 9.1.1 Introductory blathering
 | _SOURCES primary, defined | 9.1.1 Introductory blathering
 | _TEXINFOS primary, defined | 12.1 Texinfo
A |  |
 | AC_OUTPUT, scanning | 5.1 Configuration requirements
 | acinclude.m4, defined | 3.1 A simple example, start to finish
 | aclocal program, introduction | 3.1 A simple example, start to finish
 | aclocal, extending | 5.5 Writing your own aclocal macros
 | aclocal, Invoking | 5.3 Auto-generating aclocal.m4
 | aclocal.m4, preexisting | 3.1 A simple example, start to finish
 | Adding new SUFFIXES | 18.2 Handling new file extensions
 | all | 23. When Automake Isn't Enough
 | all-local | 23. When Automake Isn't Enough
 | AM_INIT_AUTOMAKE, example use | 3.1 A simple example, start to finish
 | ansi2knr | 9.13 Automatic de-ANSI-fication
 | Append operator | 2.1 General Operation
 | Automake constraints | 1. Introduction
 | Automake options | 4. Creating a `Makefile.in'
 | Automake requirements | 1. Introduction
 | Automake requirements | 5.1 Configuration requirements
 | Automake, invoking | 4. Creating a `Makefile.in'
 | Automake, recursive operation | 2.1 General Operation
 | Automatic dependency tracking | 9.14 Automatic dependency tracking
 | Automatic linker selection | 9.10.3.1 How the Linker is Chosen
 | Auxiliary programs | 2.6 Programs automake might require
 | Avoiding path stripping | 7. An Alternative Approach to Subdirectories
B |  |
 | BUGS, reporting | 1. Introduction
 | BUILT_SOURCES, defined | 10.4 Built sources
C |  |
 | C++ support | 9.8 C++ Support
 | canonicalizing Automake macros | 2.4 How derived variables are named
 | cfortran | 9.10.3 Mixing Fortran 77 With C and C++
 | check | 23. When Automake Isn't Enough
 | check primary prefix, definition | 2.3 The Uniform Naming Scheme
 | check-local | 23. When Automake Isn't Enough
 | check_LTLIBRARIES, not allowed | 9.3 Building a Shared Library
 | clean-local | 23. When Automake Isn't Enough
 | Comment, special to Automake | 2.1 General Operation
 | Complete example | 3.1 A simple example, start to finish
 | Conditional example, --enable-debug | 20. Conditionals
 | Conditionals | 20. Conditionals
 | config.guess | 4. Creating a `Makefile.in'
 | configure.in, from GNU Hello | 3.2 A classic program
 | configure.in, scanning | 5. Scanning `configure.in'
 | Constraints of Automake | 1. Introduction
 | cpio example | 2.3 The Uniform Naming Scheme
 | ctags Example | 3.3 Building etags and ctags
 | cvs-dist | 2.1 General Operation
 | cvs-dist, non-standard example | 2.1 General Operation
 | Cygnus strictness | 22. The effect of --cygnus
D |  |
 | DATA primary, defined | 10.3 Architecture-independent data files
 | de-ANSI-fication, defined | 9.13 Automatic de-ANSI-fication
 | dejagnu | 16.2 DejaGNU Tests
 | depcomp | 9.14 Automatic dependency tracking
 | Dependency tracking | 9.14 Automatic dependency tracking
 | Dependency tracking, disabling | 9.14 Automatic dependency tracking
 | Disabling dependency tracking | 9.14 Automatic dependency tracking
 | dist | 15.1 Basics of distribution
 | dist-bzip2 | 17. Changing Automake's Behavior
 | dist-gzip | 15.5 The types of distributions
 | dist-hook | 15.3 The dist hook
 | dist-hook | 23. When Automake Isn't Enough
 | dist-shar | 17. Changing Automake's Behavior
 | dist-tarZ | 17. Changing Automake's Behavior
 | dist-zip | 17. Changing Automake's Behavior
 | dist_ and nobase_ | 7. An Alternative Approach to Subdirectories
 | distcheck | 15.4 Checking the distribution
 | distclean-local | 23. When Automake Isn't Enough
 | distcleancheck | 15.4 Checking the distribution
 | dmalloc, support for | 5.4.1 Public macros
 | dvi | 23. When Automake Isn't Enough
 | dvi-local | 23. When Automake Isn't Enough
E |  |
 | E-mail, bug reports | 1. Introduction
 | EDITION Texinfo macro | 12.1 Texinfo
 | else | 20. Conditionals
 | endif | 20. Conditionals
 | etags Example | 3.3 Building etags and ctags
 | Example conditional --enable-debug | 20. Conditionals
 | Example of recursive operation | 2.1 General Operation
 | Example of shared libraries | 9.3 Building a Shared Library
 | Example, ctags and etags | 3.3 Building etags and ctags
 | Example, EXTRA_PROGRAMS | 2.3 The Uniform Naming Scheme
 | Example, GNU Hello | 3.2 A classic program
 | Example, handling Texinfo files | 3.2 A classic program
 | Example, mixed language | 9.10.3 Mixing Fortran 77 With C and C++
 | Example, regression test | 3.2 A classic program
 | Executable extension | 9.15 Support for executable extensions
 | Exit status 77, special interpretation | 16.1 Simple Tests
 | Expected test failure | 16.1 Simple Tests
 | Extending aclocal | 5.5 Writing your own aclocal macros
 | Extending list of installation directories | 2.3 The Uniform Naming Scheme
 | Extension, executable | 9.15 Support for executable extensions
 | Extra files distributed with Automake | 4. Creating a `Makefile.in'
 | EXTRA_, prepending | 2.3 The Uniform Naming Scheme
 | EXTRA_prog_SOURCES, defined | 9.1.2 Conditional compilations
 | EXTRA_PROGRAMS, defined | 2.3 The Uniform Naming Scheme
 | EXTRA_PROGRAMS, defined | 9.1.2 Conditional compilations
F |  |
 | Files distributed with Automake | 4. Creating a `Makefile.in'
 | First line of Makefile.am | 2.1 General Operation
 | FLIBS, defined | 9.10.3 Mixing Fortran 77 With C and C++
 | foreign strictness | 2.2 Strictness
 | Fortran 77 support | 9.10 Fortran 77 Support
 | Fortran 77, mixing with C and C++ | 9.10.3 Mixing Fortran 77 With C and C++
 | Fortran 77, Preprocessing | 9.10.1 Preprocessing Fortran 77
G |  |
 | Gettext support | 11.2 Gettext
 | gnits strictness | 2.2 Strictness
 | GNU Gettext support | 11.2 Gettext
 | GNU Hello, configure.in | 3.2 A classic program
 | GNU Hello, example | 3.2 A classic program
 | GNU make extensions | 2.1 General Operation
 | GNU Makefile standards | 1. Introduction
 | gnu strictness | 2.2 Strictness
H |  |
 | Header files in _SOURCES | 9.1.1 Introductory blathering
 | HEADERS primary, defined | 10.2 Header files
 | HEADERS, installation directories | 10.2 Header files
 | Hello example | 3.2 A classic program
 | Hello, configure.in | 3.2 A classic program
 | hook targets | 23. When Automake Isn't Enough
 | HP-UX 10, lex problems | 5.4.1 Public macros
 | HTML support, example | 2.3 The Uniform Naming Scheme
I |  |
 | id | 18.1 Interfacing to etags
 | if | 20. Conditionals
 | include | 19. Include
 | INCLUDES, example usage | 3.2 A classic program
 | Including Makefile fragment | 19. Include
 | info | 17. Changing Automake's Behavior
 | info | 23. When Automake Isn't Enough
 | info-local | 23. When Automake Isn't Enough
 | install | 13.2 The two parts of install
 | Install hook | 13.3 Extending installation
 | Install, two parts of | 13.2 The two parts of install
 | install-data | 13.2 The two parts of install
 | install-data | 23. When Automake Isn't Enough
 | install-data-hook | 23. When Automake Isn't Enough
 | install-data-local | 13.3 Extending installation
 | install-data-local | 23. When Automake Isn't Enough
 | install-exec | 13.2 The two parts of install
 | install-exec | 23. When Automake Isn't Enough
 | install-exec-hook | 23. When Automake Isn't Enough
 | install-exec-local | 13.3 Extending installation
 | install-exec-local | 23. When Automake Isn't Enough
 | install-info | 12.1 Texinfo
 | install-info | 17. Changing Automake's Behavior
 | install-info target | 12.1 Texinfo
 | install-man | 12.2 Man pages
 | install-man | 17. Changing Automake's Behavior
 | install-man target | 12.2 Man pages
 | install-strip | 13.5 Rules for the user
 | Installation directories, extending list | 2.3 The Uniform Naming Scheme
 | Installation support | 13. What Gets Installed
 | installcheck-local | 23. When Automake Isn't Enough
 | installdirs | 13.5 Rules for the user
 | installdirs-local | 23. When Automake Isn't Enough
 | Installing headers | 10.2 Header files
 | Installing scripts | 10.1 Executable Scripts
 | Invoking aclocal | 5.3 Auto-generating aclocal.m4
 | Invoking Automake | 4. Creating a `Makefile.in'
J |  |
 | JAVA primary, defined | 11.4 Java
 | JAVA restrictions | 11.4 Java
 | Java support | 9.11 Java Support
L |  |
 | lex problems with HP-UX 10 | 5.4.1 Public macros
 | lex, multiple lexers | 9.7 Yacc and Lex support
 | LIBADD primary, defined | 9.2 Building a library
 | LIBRARIES primary, defined | 9.2 Building a library
 | Linking Fortran 77 with C and C++ | 9.10.3 Mixing Fortran 77 With C and C++
 | LISP primary, defined | 11.1 Emacs Lisp
 | local targets | 23. When Automake Isn't Enough
 | LTLIBRARIES primary, defined | 9.3 Building a Shared Library
M |  |
 | Macros Automake recognizes | 5.2 Other things Automake recognizes
 | Macros, overriding | 2.1 General Operation
 | make check | 16. Support for test suites
 | make clean support | 14. What Gets Cleaned
 | make dist | 15.1 Basics of distribution
 | make distcheck | 15.4 Checking the distribution
 | make distcleancheck | 15.4 Checking the distribution
 | make install support | 13. What Gets Installed
 | Make targets, overriding | 2.1 General Operation
 | Makefile fragment, including | 19. Include
 | Makefile.am, first line | 2.1 General Operation
 | MANS primary, defined | 12.2 Man pages
 | mdate-sh | 12.1 Texinfo
 | Mixed language example | 9.10.3 Mixing Fortran 77 With C and C++
 | Mixing Fortran 77 with C and C++ | 9.10.3 Mixing Fortran 77 With C and C++
 | Mixing Fortran 77 with C and/or C++ | 9.10.3 Mixing Fortran 77 With C and C++
 | mostlyclean-local | 23. When Automake Isn't Enough
 | Multiple configure.in files | 4. Creating a `Makefile.in'
 | Multiple lex lexers | 9.7 Yacc and Lex support
 | Multiple yacc parsers | 9.7 Yacc and Lex support
N |  |
 | no-dependencies | 9.14 Automatic dependency tracking
 | no-installinfo | 12.1 Texinfo
 | no-installman | 12.2 Man pages
 | no-texinfo.tex | 12.1 Texinfo
 | nobase_ | 7. An Alternative Approach to Subdirectories
 | nobase_ and dist_ or nodist_ | 7. An Alternative Approach to Subdirectories
 | nodist_ and nobase_ | 7. An Alternative Approach to Subdirectories
 | noinst primary prefix, definition | 2.3 The Uniform Naming Scheme
 | noinstall-info target | 12.1 Texinfo
 | noinstall-man target | 12.2 Man pages
 | Non-GNU packages | 2.2 Strictness
 | Non-standard targets | 2.1 General Operation
O |  |
 | Objects in subdirectory | 9.4 Program and Library Variables
 | Option, ansi2knr | 17. Changing Automake's Behavior
 | Option, check-news | 17. Changing Automake's Behavior
 | Option, cygnus | 17. Changing Automake's Behavior
 | Option, dejagnu | 17. Changing Automake's Behavior
 | Option, dist-bzip2 | 17. Changing Automake's Behavior
 | Option, dist-shar | 17. Changing Automake's Behavior
 | Option, dist-tarZ | 17. Changing Automake's Behavior
 | Option, dist-zip | 17. Changing Automake's Behavior
 | Option, foreign | 17. Changing Automake's Behavior
 | Option, gnits | 17. Changing Automake's Behavior
 | Option, gnu | 17. Changing Automake's Behavior
 | Option, no-define | 17. Changing Automake's Behavior
 | Option, no-dependencies | 17. Changing Automake's Behavior
 | Option, no-exeext | 17. Changing Automake's Behavior
 | Option, no-installinfo | 17. Changing Automake's Behavior
 | Option, no-installman | 17. Changing Automake's Behavior
 | Option, no-texinfo | 17. Changing Automake's Behavior
 | Option, nostdinc | 17. Changing Automake's Behavior
 | Option, readme-alpha | 17. Changing Automake's Behavior
 | Option, version | 17. Changing Automake's Behavior
 | Options, Automake | 4. Creating a `Makefile.in'
 | Overriding make macros | 2.1 General Operation
 | Overriding make targets | 2.1 General Operation
 | Overriding SUBDIRS | 6. The top-level `Makefile.am'
P |  |
 | Path stripping, avoiding | 7. An Alternative Approach to Subdirectories
 | pkgdatadir, defined | 2.3 The Uniform Naming Scheme
 | pkgincludedir, defined | 2.3 The Uniform Naming Scheme
 | pkglibdir, defined | 2.3 The Uniform Naming Scheme
 | POSIX termios headers | 5.4.1 Public macros
 | Preprocessing Fortran 77 | 9.10.1 Preprocessing Fortran 77
 | Primary variable, DATA | 10.3 Architecture-independent data files
 | Primary variable, defined | 2.3 The Uniform Naming Scheme
 | Primary variable, HEADERS | 10.2 Header files
 | Primary variable, JAVA | 11.4 Java
 | Primary variable, LIBADD | 9.2 Building a library
 | Primary variable, LIBRARIES | 9.2 Building a library
 | Primary variable, LISP | 11.1 Emacs Lisp
 | Primary variable, LTLIBRARIES | 9.3 Building a Shared Library
 | Primary variable, MANS | 12.2 Man pages
 | Primary variable, PROGRAMS | 2.3 The Uniform Naming Scheme
 | Primary variable, PYTHON | 11.5 Python
 | Primary variable, SCRIPTS | 10.1 Executable Scripts
 | Primary variable, SOURCES | 9.1.1 Introductory blathering
 | Primary variable, TEXINFOS | 12.1 Texinfo
 | prog_LDADD, defined | 9.1.3 Linking the program
 | PROGRAMS primary variable | 2.3 The Uniform Naming Scheme
 | Programs, auxiliary | 2.6 Programs automake might require
 | PROGRAMS, bindir | 9.1.1 Introductory blathering
 | PYTHON primary, defined | 11.5 Python
R |  |
 | Ratfor programs | 9.10.1 Preprocessing Fortran 77
 | README-alpha | 21. The effect of --gnu and --gnits
 | Recognized macros by Automake | 5.2 Other things Automake recognizes
 | Recursive operation of Automake | 2.1 General Operation
 | regex package | 5.4.1 Public macros
 | Regression test example | 3.2 A classic program
 | Reporting BUGS | 1. Introduction
 | Requirements of Automake | 5.1 Configuration requirements
 | Requirements, Automake | 1. Introduction
 | Restrictions for JAVA | 11.4 Java
 | rx package | 5.4.1 Public macros
S |  |
 | Scanning configure.in | 5. Scanning `configure.in'
 | SCRIPTS primary, defined | 10.1 Executable Scripts
 | SCRIPTS, installation directories | 10.1 Executable Scripts
 | Selecting the linker automatically | 9.10.3.1 How the Linker is Chosen
 | Shared libraries, support for | 9.3 Building a Shared Library
 | SOURCES primary, defined | 9.1.1 Introductory blathering
 | Special Automake comment | 2.1 General Operation
 | Strictness, command line | 4. Creating a `Makefile.in'
 | Strictness, defined | 2.2 Strictness
 | Strictness, foreign | 2.2 Strictness
 | Strictness, gnits | 2.2 Strictness
 | Strictness, gnu | 2.2 Strictness
 | Subdirectory, objects in | 9.4 Program and Library Variables
 | SUBDIRS, explained | 6. The top-level `Makefile.am'
 | SUBDIRS, overriding | 6. The top-level `Makefile.am'
 | suffix .la, defined | 9.3 Building a Shared Library
 | suffix .lo, defined | 9.3 Building a Shared Library
 | SUFFIXES, adding | 18.2 Handling new file extensions
 | Support for C++ | 9.8 C++ Support
 | Support for Fortran 77 | 9.10 Fortran 77 Support
 | Support for GNU Gettext | 11.2 Gettext
 | Support for Java | 9.11 Java Support
T |  |
 | tags | 18.1 Interfacing to etags
 | TAGS support | 18.1 Interfacing to etags
 | Target, install-info | 12.1 Texinfo
 | Target, install-man | 12.2 Man pages
 | Target, noinstall-info | 12.1 Texinfo
 | Target, noinstall-man | 12.2 Man pages
 | termios POSIX headers | 5.4.1 Public macros
 | Test suites | 16. Support for test suites
 | Tests, expected failure | 16.1 Simple Tests
 | Texinfo file handling example | 3.2 A classic program
 | Texinfo macro, EDITION | 12.1 Texinfo
 | Texinfo macro, UPDATED | 12.1 Texinfo
 | Texinfo macro, UPDATED-MONTH | 12.1 Texinfo
 | Texinfo macro, VERSION | 12.1 Texinfo
 | texinfo.tex | 12.1 Texinfo
 | TEXINFOS primary, defined | 12.1 Texinfo
U |  |
 | Uniform naming scheme | 2.3 The Uniform Naming Scheme
 | uninstall | 13.5 Rules for the user
 | uninstall | 23. When Automake Isn't Enough
 | uninstall-hook | 23. When Automake Isn't Enough
 | uninstall-local | 23. When Automake Isn't Enough
 | UPDATED Texinfo macro | 12.1 Texinfo
 | UPDATED-MONTH Texinfo macro | 12.1 Texinfo
 | user variables | 2.5 Variables reserved for the user
V |  |
 | variables, reserved for the user | 2.5 Variables reserved for the user
 | VERSION Texinfo macro | 12.1 Texinfo
W |  |
 | Windows | 9.15 Support for executable extensions
Y |  |
 | yacc, multiple parsers | 9.7 Yacc and Lex support
 | ylwrap | 9.7 Yacc and Lex support
Z |  |
 | zardoz example | 3.1 A simple example, start to finish

Jump to: # - @ _
A B C D E F G H I J L M N O P R S T U V W Y Z

[Top] [Contents] [Index] [ ? ]

Footnotes

(1)

Autoconf 2.50 promotes `configure.ac' over `configure.in'. The rest of this documentation will refer to `configure.in' as this use is not yet spread, but Automake supports `configure.ac' too.

(2)

We believe. This work is new and there are probably warts. See section 1. Introduction, for information on reporting bugs.

(3)

There are other, more obscure reasons reasons for this limitation as well.

(4)

Much, if not most, of the information in the following sections pertaining to preprocessing Fortran 77 programs was taken almost verbatim from section `Catalogue of Rules' in The GNU Make Manual.

(5)

For example, the cfortran package addresses all of these inter-language issues, and runs under nearly all Fortran 77, C and C++ compilers on nearly all platforms. However, cfortran is not yet Free Software, but it will be in the next major release.

(6)

See http://sources.redhat.com/automake/dependencies.html for more information on the history and experiences with automatic dependency tracking in Automake

(7)

However, for the case of a non-installed header file that is actually used by a particular program, we recommend listing it in the program's `_SOURCES' variable instead of in noinst_HEADERS. We believe this is more clear.

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Introduction
    2. General ideas
      2.1 General Operation
      2.2 Strictness
      2.3 The Uniform Naming Scheme
      2.4 How derived variables are named
      2.5 Variables reserved for the user
      2.6 Programs automake might require
    3. Some example packages
      3.1 A simple example, start to finish
      3.2 A classic program
      3.3 Building etags and ctags
    4. Creating a `Makefile.in'
    5. Scanning `configure.in'
      5.1 Configuration requirements
      5.2 Other things Automake recognizes
      5.3 Auto-generating aclocal.m4
      5.4 Autoconf macros supplied with Automake
        5.4.1 Public macros
        5.4.2 Private macros
      5.5 Writing your own aclocal macros
    6. The top-level `Makefile.am'
    7. An Alternative Approach to Subdirectories
    8. Rebuilding Makefiles
    9. Building Programs and Libraries
      9.1 Building a program
        9.1.1 Introductory blathering
        9.1.2 Conditional compilations
        9.1.3 Linking the program
      9.2 Building a library
      9.3 Building a Shared Library
      9.4 Program and Library Variables
      9.5 Special handling for LIBOBJS and ALLOCA
      9.6 Variables used when building a program
      9.7 Yacc and Lex support
      9.8 C++ Support
      9.9 Assembly Support
      9.10 Fortran 77 Support
        9.10.1 Preprocessing Fortran 77
        9.10.2 Compiling Fortran 77 Files
        9.10.3 Mixing Fortran 77 With C and C++
          9.10.3.1 How the Linker is Chosen
        9.10.4 Fortran 77 and Autoconf
      9.11 Java Support
      9.12 Support for Other Languages
      9.13 Automatic de-ANSI-fication
      9.14 Automatic dependency tracking
      9.15 Support for executable extensions
    10. Other Derived Objects
      10.1 Executable Scripts
      10.2 Header files
      10.3 Architecture-independent data files
      10.4 Built sources
    11. Other GNU Tools
      11.1 Emacs Lisp
      11.2 Gettext
      11.3 Libtool
      11.4 Java
      11.5 Python
    12. Building documentation
      12.1 Texinfo
      12.2 Man pages
    13. What Gets Installed
      13.1 Basics of installation
      13.2 The two parts of install
      13.3 Extending installation
      13.4 Staged installs
      13.5 Rules for the user
    14. What Gets Cleaned
    15. What Goes in a Distribution
      15.1 Basics of distribution
      15.2 Fine-grained distribution control
      15.3 The dist hook
      15.4 Checking the distribution
      15.5 The types of distributions
    16. Support for test suites
      16.1 Simple Tests
      16.2 DejaGNU Tests
      16.3 Install Tests
    17. Changing Automake's Behavior
    18. Miscellaneous Rules
      18.1 Interfacing to etags
      18.2 Handling new file extensions
      18.3 Support for Multilibs
    19. Include
    20. Conditionals
    21. The effect of --gnu and --gnits
    22. The effect of --cygnus
    23. When Automake Isn't Enough
    24. Distributing `Makefile.in's
    25. Automake API versioning
    Macro and Variable Index
    General Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Introduction
2. General ideas
3. Some example packages
4. Creating a `Makefile.in'
5. Scanning `configure.in'
6. The top-level `Makefile.am'
7. An Alternative Approach to Subdirectories
8. Rebuilding Makefiles
9. Building Programs and Libraries
10. Other Derived Objects
11. Other GNU Tools
12. Building documentation
13. What Gets Installed
14. What Gets Cleaned
15. What Goes in a Distribution
16. Support for test suites
17. Changing Automake's Behavior
18. Miscellaneous Rules
19. Include
20. Conditionals
21. The effect of --gnu and --gnits
22. The effect of --cygnus
23. When Automake Isn't Enough
24. Distributing `Makefile.in's
25. Automake API versioning
Macro and Variable Index
General Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on May 3, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on May 3, 2002 using texi2html


Bash Reference Manual:

[Top] [Contents] [Index] [ ? ]

Bash Reference Manual

This text is a brief description of the features that are present in the Bash shell.

This is Edition 2.5a, last updated 13 November 2001, of The GNU Bash Reference Manual, for Bash, Version 2.05a.

Copyright (C) 1991, 1993, 1996 Free Software Foundation, Inc.

Bash contains features that appear in other popular shells, and some features that only appear in Bash. Some of the shells that Bash has borrowed concepts from are the Bourne Shell (`sh'), the Korn Shell (`ksh'), and the C-shell (`csh' and its successor, `tcsh'). The following menu breaks the features up into categories based upon which one of these other shells inspired the feature.

This manual is meant as a brief introduction to features found in Bash. The Bash manual page should be used as the definitive reference on shell behavior.

1. Introduction An introduction to the shell.

2. Definitions Some definitions used in the rest of this manual.

3. Basic Shell Features The shell "building blocks".

4. Shell Builtin Commands Commands that are a part of the shell.

5. Shell Variables Variables used or set by Bash.

6. Bash Features Features found only in Bash.

7. Job Control A chapter describing what job control is and how Bash allows you to use it.

9. Using History Interactively Chapter dealing with history expansion rules.

8. Command Line Editing Chapter describing the command line editing features.

10. Installing Bash How to build and install Bash on your system.

A. Reporting Bugs How to report bugs in Bash.

B. Major Differences From The Bourne Shell A terse list of the differences between Bash and historical versions of /bin/sh.

Index of Shell Builtin Commands Index of Bash builtin commands.

Index of Shell Reserved Words Index of Bash reserved words.

Parameter and Variable Index Quick reference helps you find the variable you want.

Function Index Index of bindable Readline functions.

Concept Index General index for concepts described in this manual.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Introduction

1.1 What is Bash? A short description of Bash.

1.2 What is a shell? A brief introduction to shells.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.1 What is Bash?

Bash is the shell, or command language interpreter, for the GNU operating system. The name is an acronym for the `Bourne-Again SHell', a pun on Stephen Bourne, the author of the direct ancestor of the current Unix shell /bin/sh, which appeared in the Seventh Edition Bell Labs Research version of Unix.

Bash is largely compatible with sh and incorporates useful features from the Korn shell ksh and the C shell csh. It is intended to be a conformant implementation of the IEEE POSIX Shell and Tools specification (IEEE Working Group 1003.2). It offers functional improvements over sh for both interactive and programming use.

While the GNU operating system provides other shells, including a version of csh, Bash is the default shell. Like other GNU software, Bash is quite portable. It currently runs on nearly every version of Unix and a few other operating systems - independently-supported ports exist for MS-DOS, OS/2, Windows 95/98, and Windows NT.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.2 What is a shell?

At its base, a shell is simply a macro processor that executes commands. A Unix shell is both a command interpreter, which provides the user interface to the rich set of GNU utilities, and a programming language, allowing these utilitites to be combined. Files containing commands can be created, and become commands themselves. These new commands have the same status as system commands in directories such as `/bin', allowing users or groups to establish custom environments.

A shell allows execution of GNU commands, both synchronously and asynchronously. The shell waits for synchronous commands to complete before accepting more input; asynchronous commands continue to execute in parallel with the shell while it reads and executes additional commands. The redirection constructs permit fine-grained control of the input and output of those commands. Moreover, the shell allows control over the contents of commands' environments. Shells may be used interactively or non-interactively: they accept input typed from the keyboard or from a file.

Shells also provide a small set of built-in commands (builtins) implementing functionality impossible or inconvenient to obtain via separate utilities. For example, cd, break, continue, and exec) cannot be implemented outside of the shell because they directly manipulate the shell itself. The history, getopts, kill, or pwd builtins, among others, could be implemented in separate utilities, but they are more convenient to use as builtin commands. All of the shell builtins are described in subsequent sections.

While executing commands is essential, most of the power (and complexity) of shells is due to their embedded programming languages. Like any high-level language, the shell provides variables, flow control constructs, quoting, and functions.

Shells offer features geared specifically for interactive use rather than to augment the programming language. These interactive features include job control, command line editing, history and aliases. Each of these features is described in this manual.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. Definitions

These definitions are used throughout the remainder of this manual.

POSIX
A family of open system standards based on Unix. Bash is concerned with POSIX 1003.2, the Shell and Tools Standard.

blank
A space or tab character.

builtin
A command that is implemented internally by the shell itself, rather than by an executable program somewhere in the file system.

control operator
A word that performs a control function. It is a newline or one of the following: `||', `&&', `&', `;', `;;', `|', `(', or `)'.

exit status
The value returned by a command to its caller. The value is restricted to eight bits, so the maximum value is 255.

field
A unit of text that is the result of one of the shell expansions. After expansion, when executing a command, the resulting fields are used as the command name and arguments.

filename
A string of characters used to identify a file.

job
A set of processes comprising a pipeline, and any processes descended from it, that are all in the same process group.

job control
A mechanism by which users can selectively stop (suspend) and restart (resume) execution of processes.

metacharacter
A character that, when unquoted, separates words. A metacharacter is a blank or one of the following characters: `|', `&', `;', `(', `)', `<', or `>'.

name
A word consisting solely of letters, numbers, and underscores, and beginning with a letter or underscore. Names are used as shell variable and function names. Also referred to as an identifier.

operator
A control operator or a redirection operator. See section 3.6 Redirections, for a list of redirection operators.

process group
A collection of related processes each having the same process group ID.

process group ID
A unique identifer that represents a process group during its lifetime.

reserved word
A word that has a special meaning to the shell. Most reserved words introduce shell flow control constructs, such as for and while.

return status
A synonym for exit status.

signal
A mechanism by which a process may be notified by the kernel of an event occurring in the system.

special builtin
A shell builtin command that has been classified as special by the POSIX 1003.2 standard.

token
A sequence of characters considered a single unit by the shell. It is either a word or an operator.

word
A token that is not an operator.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. Basic Shell Features

Bash is an acronym for `Bourne-Again SHell'. The Bourne shell is the traditional Unix shell originally written by Stephen Bourne. All of the Bourne shell builtin commands are available in Bash, and the rules for evaluation and quoting are taken from the POSIX 1003.2 specification for the `standard' Unix shell.

This chapter briefly summarizes the shell's `building blocks': commands, control structures, shell functions, shell parameters, shell expansions, redirections, which are a way to direct input and output from and to named files, and how the shell executes commands.

3.1 Shell Syntax | What your input means to the shell.
3.2 Shell Commands | The types of commands you can use.
3.3 Shell Functions | Grouping commands by name.
3.4 Shell Parameters | Special shell variables.
3.5 Shell Expansions | How Bash expands variables and the various expansions available.
3.6 Redirections | A way to control where input and output go.
3.7 Executing Commands | What happens when you run a command.
3.8 Shell Scripts | Executing files of shell commands.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 Shell Syntax

3.1.1 Shell Operation The basic operation of the shell.

3.1.2 Quoting How to remove the special meaning from characters.

3.1.3 Comments How to specify comments.

When the shell reads input, it proceeds through a sequence of operations. If the input indicates the beginning of a comment, the shell ignores the comment symbol (`#'), and the rest of that line. Otherwise, roughly speaking, the shell reads its input and divides the input into words and operators, employing the quoting rules to select which meanings to assign various words and characters.

The shell then parses these tokens into commands and other constructs, removes the special meaning of certain words or characters, expands others, redirects input and output as needed, executes the specified command, waits for the command's exit status, and makes that exit status available for further inspection or processing.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.1 Shell Operation

The following is a brief description of the shell's operation when it reads and executes a command. Basically, the shell does the following:

  1. Reads its input from a file (see section 3.8 Shell Scripts), from a string supplied as an argument to the `-c' invocation option (see section 6.1 Invoking Bash), or from the user's terminal.

  2. Breaks the input into words and operators, obeying the quoting rules described in 3.1.2 Quoting. These tokens are separated by metacharacters. Alias expansion is performed by this step (see section 6.6 Aliases).

  3. Parses the tokens into simple and compound commands (see section 3.2 Shell Commands).

  4. Performs the various shell expansions (see section 3.5 Shell Expansions), breaking the expanded tokens into lists of filenames (see section 3.5.8 Filename Expansion) and commands and arguments.

  5. Performs any necessary redirections (see section 3.6 Redirections) and removes the redirection operators and their operands from the argument list.

  6. Executes the command (see section 3.7 Executing Commands).

  7. Optionally waits for the command to complete and collects its exit status (see section 3.7.5 Exit Status).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2 Quoting

3.1.2.1 Escape Character | How to remove the special meaning from a single character.
3.1.2.2 Single Quotes | How to inhibit all interpretation of a sequence of characters.
3.1.2.3 Double Quotes | How to suppress most of the interpretation of a sequence of characters.
3.1.2.4 ANSI-C Quoting | How to expand ANSI-C sequences in quoted strings.

3.1.2.5 Locale-Specific Translation How to translate strings into different languages.

Quoting is used to remove the special meaning of certain characters or words to the shell. Quoting can be used to disable special treatment for special characters, to prevent reserved words from being recognized as such, and to prevent parameter expansion.

Each of the shell metacharacters (see section 2. Definitions) has special meaning to the shell and must be quoted if it is to represent itself. When the command history expansion facilities are being used, the history expansion character, usually `!', must be quoted to prevent history expansion. See section 9.1 Bash History Facilities, for more details concerning history expansion. There are three quoting mechanisms: the escape character, single quotes, and double quotes.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2.1 Escape Character

A non-quoted backslash `\' is the Bash escape character. It preserves the literal value of the next character that follows, with the exception of newline. If a \newline pair appears, and the backslash itself is not quoted, the \newline is treated as a line continuation (that is, it is removed from the input stream and effectively ignored).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2.2 Single Quotes

Enclosing characters in single quotes (`'') preserves the literal value of each character within the quotes. A single quote may not occur between single quotes, even when preceded by a backslash.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2.3 Double Quotes

Enclosing characters in double quotes (`"') preserves the literal value of all characters within the quotes, with the exception of `$', ``', and `\'. The characters `$' and ``' retain their special meaning within double quotes (see section 3.5 Shell Expansions). The backslash retains its special meaning only when followed by one of the following characters: `$', ``', `"', `\', or newline. Within double quotes, backslashes that are followed by one of these characters are removed. Backslashes preceding characters without a special meaning are left unmodified. A double quote may be quoted within double quotes by preceding it with a backslash.

The special parameters `*' and `@' have special meaning when in double quotes (see section 3.5.3 Shell Parameter Expansion).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2.4 ANSI-C Quoting

Words of the form $'string' are treated specially. The word expands to string, with backslash-escaped characters replaced as specified by the ANSI C standard. Backslash escape sequences, if present, are decoded as follows:

\a
alert (bell)
\b
backspace
\e
an escape character (not ANSI C)
\f
form feed
\n
newline
\r
carriage return
\t
horizontal tab
\v
vertical tab
\\
backslash
\'
single quote
\nnn
the eight-bit character whose value is the octal value nnn (one to three digits)
\xHH
the eight-bit character whose value is the hexadecimal value HH (one or two hex digits)

The expanded result is single-quoted, as if the dollar sign had not been present.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2.5 Locale-Specific Translation

A double-quoted string preceded by a dollar sign (`$') will cause the string to be translated according to the current locale. If the current locale is C or POSIX, the dollar sign is ignored. If the string is translated and replaced, the replacement is double-quoted.

Some systems use the message catalog selected by the LC_MESSAGES shell variable. Others create the name of the message catalog from the value of the TEXTDOMAIN shell variable, possibly adding a suffix of `.mo'. If you use the TEXTDOMAIN variable, you may need to set the TEXTDOMAINDIR variable to the location of the message catalog files. Still others use both variables in this fashion: TEXTDOMAINDIR/LC_MESSAGES/LC_MESSAGES/TEXTDOMAIN.mo.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.3 Comments

In a non-interactive shell, or an interactive shell in which the interactive_comments option to the shopt builtin is enabled (see section 4.2 Bash Builtin Commands), a word beginning with `#' causes that word and all remaining characters on that line to be ignored. An interactive shell without the interactive_comments option enabled does not allow comments. The interactive_comments option is on by default in interactive shells. See section 6.3 Interactive Shells, for a description of what makes a shell interactive.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 Shell Commands

A simple shell command such as echo a b c consists of the command itself followed by arguments, separated by spaces.

More complex shell commands are composed of simple commands arranged together in a variety of ways: in a pipeline in which the output of one command becomes the input of a second, in a loop or conditional construct, or in some other grouping.

3.2.1 Simple Commands | The most common type of command.
3.2.2 Pipelines | Connecting the input and output of several commands.
3.2.3 Lists of Commands | How to execute commands sequentially.
3.2.4 Looping Constructs | Shell commands for iterative action.
3.2.5 Conditional Constructs | Shell commands for conditional execution.
3.2.6 Grouping Commands | Ways to group commands.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.1 Simple Commands

A simple command is the kind of command encountered most often. It's just a sequence of words separated by blanks, terminated by one of the shell's control operators (see section 2. Definitions). The first word generally specifies a command to be executed, with the rest of the words being that command's arguments.

The return status (see section 3.7.5 Exit Status) of a simple command is its exit status as provided by the POSIX 1003.1 waitpid function, or 128+n if the command was terminated by signal n.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.2 Pipelines

A pipeline is a sequence of simple commands separated by `|'.

The format for a pipeline is
[time [-p]] [!] command1 [| command2 ...]

The output of each command in the pipeline is connected via a pipe to the input of the next command. That is, each command reads the previous command's output.

The reserved word time causes timing statistics to be printed for the pipeline once it finishes. The statistics currently consist of elapsed (wall-clock) time and user and system time consumed by the command's execution. The `-p' option changes the output format to that specified by POSIX. The TIMEFORMAT variable may be set to a format string that specifies how the timing information should be displayed. See section 5.2 Bash Variables, for a description of the available formats. The use of time as a reserved word permits the timing of shell builtins, shell functions, and pipelines. An external time command cannot time these easily.

If the pipeline is not executed asynchronously (see section 3.2.3 Lists of Commands), the shell waits for all commands in the pipeline to complete.

Each command in a pipeline is executed in its own subshell (see section 3.7.3 Command Execution Environment). The exit status of a pipeline is the exit status of the last command in the pipeline. If the reserved word `!' precedes the pipeline, the exit status is the logical negation of the exit status of the last command.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.3 Lists of Commands

A list is a sequence of one or more pipelines separated by one of the operators `;', `&', `&&', or `||', and optionally terminated by one of `;', `&', or a newline.

Of these list operators, `&&' and `||' have equal precedence, followed by `;' and `&', which have equal precedence.

If a command is terminated by the control operator `&', the shell executes the command asynchronously in a subshell. This is known as executing the command in the background. The shell does not wait for the command to finish, and the return status is 0 (true). When job control is not active (see section 7. Job Control), the standard input for asynchronous commands, in the absence of any explicit redirections, is redirected from /dev/null.

Commands separated by a `;' are executed sequentially; the shell waits for each command to terminate in turn. The return status is the exit status of the last command executed.

The control operators `&&' and `||' denote AND lists and OR lists, respectively. An AND list has the form
command1 && command2

command2 is executed if, and only if, command1 returns an exit status of zero.

An OR list has the form
command1 || command2

command2 is executed if, and only if, command1 returns a non-zero exit status.

The return status of AND and OR lists is the exit status of the last command executed in the list.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.4 Looping Constructs

Bash supports the following looping constructs.

Note that wherever a `;' appears in the description of a command's syntax, it may be replaced with one or more newlines.

until
The syntax of the until command is:
until test-commands; do consequent-commands; done
Execute consequent-commands as long as test-commands has an exit status which is not zero. The return status is the exit status of the last command executed in consequent-commands, or zero if none was executed.

while
The syntax of the while command is:
while test-commands; do consequent-commands; done

Execute consequent-commands as long as test-commands has an exit status of zero. The return status is the exit status of the last command executed in consequent-commands, or zero if none was executed.

for
The syntax of the for command is:

for name [in words ...]; do commands; done
Expand words, and execute commands once for each member in the resultant list, with name bound to the current member. If `in words' is not present, the for command executes the commands once for each positional parameter that is set, as if `in "$@"' had been specified (see section 3.4.2 Special Parameters). The return status is the exit status of the last command that executes. If there are no items in the expansion of words, no commands are executed, and the return status is zero.

An alternate form of the for command is also supported:

for (( expr1 ; expr2 ; expr3 )) ; do commands ; done
First, the arithmetic expression expr1 is evaluated according to the rules described below (see section 6.5 Shell Arithmetic). The arithmetic expression expr2 is then evaluated repeatedly until it evaluates to zero. Each time expr2 evaluates to a non-zero value, commands are executed and the arithmetic expression expr3 is evaluated. If any expression is omitted, it behaves as if it evaluates to 1. The return value is the exit status of the last command in list that is executed, or false if any of the expressions is invalid.

The break and continue builtins (see section 4.1 Bourne Shell Builtins) may be used to control loop execution.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.5 Conditional Constructs

if
The syntax of the if command is:

if test-commands; then
  consequent-commands;
[elif more-test-commands; then
  more-consequents;]
[else alternate-consequents;]
fi

The test-commands list is executed, and if its return status is zero, the consequent-commands list is executed. If test-commands returns a non-zero status, each elif list is executed in turn, and if its exit status is zero, the corresponding more-consequents is executed and the command completes. If `else alternate-consequents' is present, and the final command in the final if or elif clause has a non-zero exit status, then alternate-consequents is executed. The return status is the exit status of the last command executed, or zero if no condition tested true.

case
The syntax of the case command is:

case word in [ [(] pattern [| pattern]...) command-list ;;]... esac

case will selectively execute the command-list corresponding to the first pattern that matches word. The `|' is used to separate multiple patterns, and the `)' operator terminates a pattern list. A list of patterns and an associated command-list is known as a clause. Each clause must be terminated with `;;'. The word undergoes tilde expansion, parameter expansion, command substitution, arithmetic expansion, and quote removal before matching is attempted. Each pattern undergoes tilde expansion, parameter expansion, command substitution, and arithmetic expansion.

There may be an arbitrary number of case clauses, each terminated by a `;;'. The first pattern that matches determines the command-list that is executed.

Here is an example using case in a script that could be used to describe one interesting feature of an animal:

echo -n "Enter the name of an animal: "
read ANIMAL
echo -n "The $ANIMAL has "
case $ANIMAL in
  horse | dog | cat) echo -n "four";;
  man | kangaroo ) echo -n "two";;
  *) echo -n "an unknown number of";;
esac
echo " legs."

The return status is zero if no pattern is matched. Otherwise, the return status is the exit status of the command-list executed.

select

The select construct allows the easy generation of menus. It has almost the same syntax as the for command:

select name [in words ...]; do commands; done

The list of words following in is expanded, generating a list of items. The set of expanded words is printed on the standard error output stream, each preceded by a number. If the `in words' is omitted, the positional parameters are printed, as if `in "$@"' had been specifed. The PS3 prompt is then displayed and a line is read from the standard input. If the line consists of a number corresponding to one of the displayed words, then the value of name is set to that word. If the line is empty, the words and prompt are displayed again. If EOF is read, the select command completes. Any other value read causes name to be set to null. The line read is saved in the variable REPLY.

The commands are executed after each selection until a break command is executed, at which point the select command completes.

Here is an example that allows the user to pick a filename from the current directory, and displays the name and index of the file selected.

select fname in *;
do
    echo you picked $fname \($REPLY\)
    break;
done

((...))
(( expression ))

The arithmetic expression is evaluated according to the rules described below (see section 6.5 Shell Arithmetic). If the value of the expression is non-zero, the return status is 0; otherwise the return status is 1. This is exactly equivalent to
let "expression"
See section 4.2 Bash Builtin Commands, for a full description of the let builtin.

[[...]]
[[ expression ]]

Return a status of 0 or 1 depending on the evaluation of the conditional expression expression. Expressions are composed of the primaries described below in 6.4 Bash Conditional Expressions. Word splitting and filename expansion are not performed on the words between the `[[' and `]]'; tilde expansion, parameter and variable expansion, arithmetic expansion, command substitution, process substitution, and quote removal are performed.

When the `==' and `!=' operators are used, the string to the right of the operator is considered a pattern and matched according to the rules described below in 3.5.8.1 Pattern Matching. The return value is 0 if the string matches or does not match the pattern, respectively, and 1 otherwise. Any part of the pattern may be quoted to force it to be matched as a string.

Expressions may be combined using the following operators, listed in decreasing order of precedence:

( expression )
Returns the value of expression. This may be used to override the normal precedence of operators.

! expression
True if expression is false.

expression1 && expression2
True if both expression1 and expression2 are true.

expression1 || expression2
True if either expression1 or expression2 is true.
The && and || commands do not execute expression2 if the value of expression1 is sufficient to determine the return value of the entire conditional expression.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.6 Grouping Commands

Bash provides two ways to group a list of commands to be executed as a unit. When commands are grouped, redirections may be applied to the entire command list. For example, the output of all the commands in the list may be redirected to a single stream.

()
( list )

Placing a list of commands between parentheses causes a subshell to be created, and each of the commands in list to be executed in that subshell. Since the list is executed in a subshell, variable assignments do not remain in effect after the subshell completes.

{}
{ list; }

Placing a list of commands between curly braces causes the list to be executed in the current shell context. No subshell is created. The semicolon (or newline) following list is required.

In addition to the creation of a subshell, there is a subtle difference between these two constructs due to historical reasons. The braces are reserved words, so they must be separated from the list by blanks. The parentheses are operators, and are recognized as separate tokens by the shell even if they are not separated from the list by whitespace.

The exit status of both of these constructs is the exit status of list.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 Shell Functions

Shell functions are a way to group commands for later execution using a single name for the group. They are executed just like a "regular" command. When the name of a shell function is used as a simple command name, the list of commands associated with that function name is executed. Shell functions are executed in the current shell context; no new process is created to interpret them.

Functions are declared using this syntax:
[ function ] name () { command-list; }

This defines a shell function named name. The reserved word function is optional. If the function reserved word is supplied, the parentheses are optional. The body of the function is the command-list between { and }. This list is executed whenever name is specified as the name of a command. The exit status of a function is the exit status of the last command executed in the body.

Note that for historical reasons, the curly braces that surround the body of the function must be separated from the body by blanks or newlines. This is because the braces are reserved words and are only recognized as such when they are separated by whitespace. Also, the command-list must be terminated with a semicolon or a newline.

When a function is executed, the arguments to the function become the positional parameters during its execution (see section 3.4.1 Positional Parameters). The special parameter `#' that expands to the number of positional parameters is updated to reflect the change. Positional parameter 0 is unchanged. The FUNCNAME variable is set to the name of the function while the function is executing.

If the builtin command return is executed in a function, the function completes and execution resumes with the next command after the function call. When a function completes, the values of the positional parameters and the special parameter `#' are restored to the values they had prior to the function's execution. If a numeric argument is given to return, that is the function's return status; otherwise the function's return status is the exit status of the last command executed before the return.

Variables local to the function may be declared with the local builtin. These variables are visible only to the function and the commands it invokes.

Functions may be recursive. No limit is placed on the number of recursive calls.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4 Shell Parameters

3.4.1 Positional Parameters | The shell's command-line arguments.
3.4.2 Special Parameters | Parameters with special meanings.

A parameter is an entity that stores values. It can be a name, a number, or one of the special characters listed below. For the shell's purposes, a variable is a parameter denoted by a name. A variable has a value and zero or more attributes. Attributes are assigned using the declare builtin command (see the description of the declare builtin in 4.2 Bash Builtin Commands).

A parameter is set if it has been assigned a value. The null string is a valid value. Once a variable is set, it may be unset only by using the unset builtin command.

A variable may be assigned to by a statement of the form
name=[value]
If value is not given, the variable is assigned the null string. All values undergo tilde expansion, parameter and variable expansion, command substitution, arithmetic expansion, and quote removal (detailed below). If the variable has its integer attribute set, then value is subject to arithmetic expansion even if the $((...)) expansion is not used (see section 3.5.5 Arithmetic Expansion). Word splitting is not performed, with the exception of "$@" as explained below. Filename expansion is not performed. Assignment statements may also appear as arguments to the declare, typeset, export, readonly, and local builtin commands.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.1 Positional Parameters

A positional parameter is a parameter denoted by one or more digits, other than the single digit 0. Positional parameters are assigned from the shell's arguments when it is invoked, and may be reassigned using the set builtin command. Positional parameter N may be referenced as ${N}, or as $N when N consists of a single digit. Positional parameters may not be assigned to with assignment statements. The set and shift builtins are used to set and unset them (see section 4. Shell Builtin Commands). The positional parameters are temporarily replaced when a shell function is executed (see section 3.3 Shell Functions).

When a positional parameter consisting of more than a single digit is expanded, it must be enclosed in braces.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.2 Special Parameters

The shell treats several parameters specially. These parameters may only be referenced; assignment to them is not allowed.

*
Expands to the positional parameters, starting from one. When the expansion occurs within double quotes, it expands to a single word with the value of each parameter separated by the first character of the IFS special variable. That is, "$*" is equivalent to "$1c$2c...", where c is the first character of the value of the IFS variable. If IFS is unset, the parameters are separated by spaces. If IFS is null, the parameters are joined without intervening separators.

@
Expands to the positional parameters, starting from one. When the expansion occurs within double quotes, each parameter expands to a separate word. That is, "$@" is equivalent to "$1" "$2" .... When there are no positional parameters, "$@" and $@ expand to nothing (i.e., they are removed).

#
Expands to the number of positional parameters in decimal.

?
Expands to the exit status of the most recently executed foreground pipeline.

-
(A hyphen.) Expands to the current option flags as specified upon invocation, by the set builtin command, or those set by the shell itself (such as the `-i' option).

$
Expands to the process ID of the shell. In a () subshell, it expands to the process ID of the invoking shell, not the subshell.

!
Expands to the process ID of the most recently executed background (asynchronous) command.

0
Expands to the name of the shell or shell script. This is set at shell initialization. If Bash is invoked with a file of commands (see section 3.8 Shell Scripts), $0 is set to the name of that file. If Bash is started with the `-c' option (see section 6.1 Invoking Bash), then $0 is set to the first argument after the string to be executed, if one is present. Otherwise, it is set to the filename used to invoke Bash, as given by argument zero.

_
(An underscore.) At shell startup, set to the absolute filename of the shell or shell script being executed as passed in the argument list. Subsequently, expands to the last argument to the previous command, after expansion. Also set to the full pathname of each command executed and placed in the environment exported to that command. When checking mail, this parameter holds the name of the mail file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5 Shell Expansions

Expansion is performed on the command line after it has been split into tokens. There are seven kinds of expansion performed:

  • brace expansion
  • tilde expansion
  • parameter and variable expansion
  • command substitution
  • arithmetic expansion
  • word splitting
  • filename expansion

3.5.1 Brace Expansion | Expansion of expressions within braces.
3.5.2 Tilde Expansion | Expansion of the ~ character.
3.5.3 Shell Parameter Expansion | How Bash expands variables to their values.
3.5.4 Command Substitution | Using the output of a command as an argument.
3.5.5 Arithmetic Expansion | How to use arithmetic in shell expansions.
3.5.6 Process Substitution | A way to write and read to and from a command.
3.5.7 Word Splitting | How the results of expansion are split into separate arguments.
3.5.8 Filename Expansion | A shorthand for specifying filenames matching patterns.
3.5.9 Quote Removal | How and when quote characters are removed from words.

The order of expansions is: brace expansion, tilde expansion, parameter, variable, and arithmetic expansion and command substitution (done in a left-to-right fashion), word splitting, and filename expansion.

On systems that can support it, there is an additional expansion available: process substitution. This is performed at the same time as parameter, variable, and arithmetic expansion and command substitution.

Only brace expansion, word splitting, and filename expansion can change the number of words of the expansion; other expansions expand a single word to a single word. The only exceptions to this are the expansions of "$@" (see section 3.4.2 Special Parameters) and "${name[@]}" (see section 6.7 Arrays).

After all expansions, quote removal (see section 3.5.9 Quote Removal) is performed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.1 Brace Expansion

Brace expansion is a mechanism by which arbitrary strings may be generated. This mechanism is similar to filename expansion (see section 3.5.8 Filename Expansion), but the file names generated need not exist. Patterns to be brace expanded take the form of an optional preamble, followed by a series of comma-separated strings between a pair of braces, followed by an optional postscript. The preamble is prefixed to each string contained within the braces, and the postscript is then appended to each resulting string, expanding left to right.

Brace expansions may be nested. The results of each expanded string are not sorted; left to right order is preserved. For example,
bash$ echo a{d,c,b}e
ade ace abe

Brace expansion is performed before any other expansions, and any characters special to other expansions are preserved in the result. It is strictly textual. Bash does not apply any syntactic interpretation to the context of the expansion or the text between the braces. To avoid conflicts with parameter expansion, the string `${' is not considered eligible for brace expansion.

A correctly-formed brace expansion must contain unquoted opening and closing braces, and at least one unquoted comma. Any incorrectly formed brace expansion is left unchanged.

This construct is typically used as shorthand when the common prefix of the strings to be generated is longer than in the above example:
mkdir /usr/local/src/bash/{old,new,dist,bugs}
or
chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.2 Tilde Expansion

If a word begins with an unquoted tilde character (`~'), all of the characters up to the first unquoted slash (or all characters, if there is no unquoted slash) are considered a tilde-prefix. If none of the characters in the tilde-prefix are quoted, the characters in the tilde-prefix following the tilde are treated as a possible login name. If this login name is the null string, the tilde is replaced with the value of the HOME shell variable. If HOME is unset, the home directory of the user executing the shell is substituted instead. Otherwise, the tilde-prefix is replaced with the home directory associated with the specified login name.

If the tilde-prefix is `~+', the value of the shell variable PWD replaces the tilde-prefix. If the tilde-prefix is `~-', the value of the shell variable OLDPWD, if it is set, is substituted.

If the characters following the tilde in the tilde-prefix consist of a number N, optionally prefixed by a `+' or a `-', the tilde-prefix is replaced with the corresponding element from the directory stack, as it would be displayed by the dirs builtin invoked with the characters following tilde in the tilde-prefix as an argument (see section 6.8 The Directory Stack). If the tilde-prefix, sans the tilde, consists of a number without a leading `+' or `-', `+' is assumed.

If the login name is invalid, or the tilde expansion fails, the word is left unchanged.

Each variable assignment is checked for unquoted tilde-prefixes immediately following a `:' or `='. In these cases, tilde expansion is also performed. Consequently, one may use file names with tildes in assignments to PATH, MAILPATH, and CDPATH, and the shell assigns the expanded value.

The following table shows how Bash treats unquoted tilde-prefixes:

~
The value of $HOME
~/foo
`$HOME/foo'

~fred/foo
The subdirectory foo of the home directory of the user fred

~+/foo
`$PWD/foo'

~-/foo
`${OLDPWD-'~-'}/foo'

~N
The string that would be displayed by `dirs +N'

~+N
The string that would be displayed by `dirs +N'

~-N
The string that would be displayed by `dirs -N'

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.3 Shell Parameter Expansion

The `$' character introduces parameter expansion, command substitution, or arithmetic expansion. The parameter name or symbol to be expanded may be enclosed in braces, which are optional but serve to protect the variable to be expanded from characters immediately following it which could be interpreted as part of the name.

When braces are used, the matching ending brace is the first `}' not escaped by a backslash or within a quoted string, and not within an embedded arithmetic expansion, command substitution, or parameter expansion.

The basic form of parameter expansion is ${parameter}. The value of parameter is substituted. The braces are required when parameter is a positional parameter with more than one digit, or when parameter is followed by a character that is not to be interpreted as part of its name.

If the first character of parameter is an exclamation point, a level of variable indirection is introduced. Bash uses the value of the variable formed from the rest of parameter as the name of the variable; this variable is then expanded and that value is used in the rest of the substitution, rather than the value of parameter itself. This is known as indirect expansion. The exception to this is the expansion of ${!prefix*} described below.

In each of the cases below, word is subject to tilde expansion, parameter expansion, command substitution, and arithmetic expansion.

When not performing substring expansion, Bash tests for a parameter that is unset or null; omitting the colon results in a test only for a parameter that is unset. Put another way, if the colon is included, the operator tests for both existence and that the value is not null; if the colon is omitted, the operator tests only for existence.

${parameter:-word}
If parameter is unset or null, the expansion of word is substituted. Otherwise, the value of parameter is substituted.

${parameter:=word}
If parameter is unset or null, the expansion of word is assigned to parameter. The value of parameter is then substituted. Positional parameters and special parameters may not be assigned to in this way.

${parameter:?word}
If parameter is null or unset, the expansion of word (or a message to that effect if word is not present) is written to the standard error and the shell, if it is not interactive, exits. Otherwise, the value of parameter is substituted.

${parameter:+word}
If parameter is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

${parameter:offset}
${parameter:offset:length}
Expands to up to length characters of parameter starting at the character specified by offset. If length is omitted, expands to the substring of parameter starting at the character specified by offset. length and offset are arithmetic expressions (see section 6.5 Shell Arithmetic). This is referred to as Substring Expansion.

length must evaluate to a number greater than or equal to zero. If offset evaluates to a number less than zero, the value is used as an offset from the end of the value of parameter. If parameter is `@', the result is length positional parameters beginning at offset. If parameter is an array name indexed by `@' or `*', the result is the length members of the array beginning with ${parameter[offset]}. Substring indexing is zero-based unless the positional parameters are used, in which case the indexing starts at 1.

${!prefix*}
Expands to the names of variables whose names begin with prefix, separated by the first character of the IFS special variable.

${#parameter}
The length in characters of the expanded value of parameter is substituted. If parameter is `*' or `@', the value substituted is the number of positional parameters. If parameter is an array name subscripted by `*' or `@', the value substituted is the number of elements in the array.

${parameter#word}
${parameter##word}
The word is expanded to produce a pattern just as in filename expansion (see section 3.5.8 Filename Expansion). If the pattern matches the beginning of the expanded value of parameter, then the result of the expansion is the expanded value of parameter with the shortest matching pattern (the `#' case) or the longest matching pattern (the `##' case) deleted. If parameter is `@' or `*', the pattern removal operation is applied to each positional parameter in turn, and the expansion is the resultant list. If parameter is an array variable subscripted with `@' or `*', the pattern removal operation is applied to each member of the array in turn, and the expansion is the resultant list.

${parameter%word}
${parameter%%word}
The word is expanded to produce a pattern just as in filename expansion. If the pattern matches a trailing portion of the expanded value of parameter, then the result of the expansion is the value of parameter with the shortest matching pattern (the `%' case) or the longest matching pattern (the `%%' case) deleted. If parameter is `@' or `*', the pattern removal operation is applied to each positional parameter in turn, and the expansion is the resultant list. If parameter is an array variable subscripted with `@' or `*', the pattern removal operation is applied to each member of the array in turn, and the expansion is the resultant list.

${parameter/pattern/string}
${parameter//pattern/string}

The pattern is expanded to produce a pattern just as in filename expansion. Parameter is expanded and the longest match of pattern against its value is replaced with string. In the first form, only the first match is replaced. The second form causes all matches of pattern to be replaced with string. If pattern begins with `#', it must match at the beginning of the expanded value of parameter. If pattern begins with `%', it must match at the end of the expanded value of parameter. If string is null, matches of pattern are deleted and the / following pattern may be omitted. If parameter is `@' or `*', the substitution operation is applied to each positional parameter in turn, and the expansion is the resultant list. If parameter is an array variable subscripted with `@' or `*', the substitution operation is applied to each member of the array in turn, and the expansion is the resultant list.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.4 Command Substitution

Command substitution allows the output of a command to replace the command itself. Command substitution occurs when a command is enclosed as follows:
$(command)
or
`command`

Bash performs the expansion by executing command and replacing the command substitution with the standard output of the command, with any trailing newlines deleted. Embedded newlines are not deleted, but they may be removed during word splitting. The command substitution $(cat file) can be replaced by the equivalent but faster $(< file).

When the old-style backquote form of substitution is used, backslash retains its literal meaning except when followed by `$', ``', or `\'. The first backquote not preceded by a backslash terminates the command substitution. When using the $(command) form, all characters between the parentheses make up the command; none are treated specially.

Command substitutions may be nested. To nest when using the backquoted form, escape the inner backquotes with backslashes.

If the substitution appears within double quotes, word splitting and filename expansion are not performed on the results.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.5 Arithmetic Expansion

Arithmetic expansion allows the evaluation of an arithmetic expression and the substitution of the result. The format for arithmetic expansion is:

$(( expression ))

The expression is treated as if it were within double quotes, but a double quote inside the parentheses is not treated specially. All tokens in the expression undergo parameter expansion, command substitution, and quote removal. Arithmetic substitutions may be nested.

The evaluation is performed according to the rules listed below (see section 6.5 Shell Arithmetic). If the expression is invalid, Bash prints a message indicating failure to the standard error and no substitution occurs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.6 Process Substitution

Process substitution is supported on systems that support named pipes (FIFOs) or the `/dev/fd' method of naming open files. It takes the form of
<(list)
or
>(list)
The process list is run with its input or output connected to a FIFO or some file in `/dev/fd'. The name of this file is passed as an argument to the current command as the result of the expansion. If the >(list) form is used, writing to the file will provide input for list. If the <(list) form is used, the file passed as an argument should be read to obtain the output of list. Note that no space may appear between the < or > and the left parenthesis, otherwise the construct would be interpreted as a redirection.

When available, process substitution is performed simultaneously with parameter and variable expansion, command substitution, and arithmetic expansion.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.7 Word Splitting

The shell scans the results of parameter expansion, command substitution, and arithmetic expansion that did not occur within double quotes for word splitting.

The shell treats each character of $IFS as a delimiter, and splits the results of the other expansions into words on these characters. If IFS is unset, or its value is exactly <space><tab><newline>, the default, then any sequence of IFS characters serves to delimit words. If IFS has a value other than the default, then sequences of the whitespace characters space and tab are ignored at the beginning and end of the word, as long as the whitespace character is in the value of IFS (an IFS whitespace character). Any character in IFS that is not IFS whitespace, along with any adjacent IFS whitespace characters, delimits a field. A sequence of IFS whitespace characters is also treated as a delimiter. If the value of IFS is null, no word splitting occurs.

Explicit null arguments ("" or ") are retained. Unquoted implicit null arguments, resulting from the expansion of parameters that have no values, are removed. If a parameter with no value is expanded within double quotes, a null argument results and is retained.

Note that if no expansion occurs, no splitting is performed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.8 Filename Expansion

3.5.8.1 Pattern Matching How the shell matches patterns.

After word splitting, unless the `-f' option has been set (see section 4.3 The Set Builtin), Bash scans each word for the characters `*', `?', and `['. If one of these characters appears, then the word is regarded as a pattern, and replaced with an alphabetically sorted list of file names matching the pattern. If no matching file names are found, and the shell option nullglob is disabled, the word is left unchanged. If the nullglob option is set, and no matches are found, the word is removed. If the shell option nocaseglob is enabled, the match is performed without regard to the case of alphabetic characters.

When a pattern is used for filename generation, the character `.' at the start of a filename or immediately following a slash must be matched explicitly, unless the shell option dotglob is set. When matching a file name, the slash character must always be matched explicitly. In other cases, the `.' character is not treated specially.

See the description of shopt in 4.2 Bash Builtin Commands, for a description of the nocaseglob, nullglob, and dotglob options.

The GLOBIGNORE shell variable may be used to restrict the set of filenames matching a pattern. If GLOBIGNORE is set, each matching filename that also matches one of the patterns in GLOBIGNORE is removed from the list of matches. The filenames `.' and `..' are always ignored, even when GLOBIGNORE is set. However, setting GLOBIGNORE has the effect of enabling the dotglob shell option, so all other filenames beginning with a `.' will match. To get the old behavior of ignoring filenames beginning with a `.', make `.*' one of the patterns in GLOBIGNORE. The dotglob option is disabled when GLOBIGNORE is unset.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.8.1 Pattern Matching

Any character that appears in a pattern, other than the special pattern characters described below, matches itself. The NUL character may not occur in a pattern. The special pattern characters must be quoted if they are to be matched literally.

The special pattern characters have the following meanings:

*
Matches any string, including the null string.
?
Matches any single character.
[...]
Matches any one of the enclosed characters. A pair of characters separated by a hyphen denotes a range expression; any character that sorts between those two characters, inclusive, using the current locale's collating sequence and character set, is matched. If the first character following the `[' is a `!' or a `^' then any character not enclosed is matched. A `-' may be matched by including it as the first or last character in the set. A `]' may be matched by including it as the first character in the set. The sorting order of characters in range expressions is determined by the current locale and the value of the LC_COLLATE shell variable, if set.

For example, in the default C locale, `[a-dx-z]' is equivalent to `[abcdxyz]'. Many locales sort characters in dictionary order, and in these locales `[a-dx-z]' is typically not equivalent to `[abcdxyz]'; it might be equivalent to `[aBbCcDdxXyYz]', for example. To obtain the traditional interpretation of ranges in bracket expressions, you can force the use of the C locale by setting the LC_COLLATE or LC_ALL environment variable to the value `C'.

Within `[' and `]', character classes can be specified using the syntax [:class:], where class is one of the following classes defined in the POSIX 1003.2 standard:
alnum   alpha   ascii   blank   cntrl   digit   graph   lower
print   punct   space   upper   xdigit
A character class matches any character belonging to that class.

Within `[' and `]', an equivalence class can be specified using the syntax [=c=], which matches all characters with the same collation weight (as defined by the current locale) as the character c.

Within `[' and `]', the syntax [.symbol.] matches the collating symbol symbol.

If the extglob shell option is enabled using the shopt builtin, several extended pattern matching operators are recognized. In the following description, a pattern-list is a list of one or more patterns separated by a `|'. Composite patterns may be formed using one or more of the following sub-patterns:

?(pattern-list)
Matches zero or one occurrence of the given patterns.

*(pattern-list)
Matches zero or more occurrences of the given patterns.

+(pattern-list)
Matches one or more occurrences of the given patterns.

@(pattern-list)
Matches exactly one of the given patterns.

!(pattern-list)
Matches anything except one of the given patterns.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.9 Quote Removal

After the preceding expansions, all unquoted occurrences of the characters `\', `'', and `"' that did not result from one of the above expansions are removed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6 Redirections

Before a command is executed, its input and output may be redirected using a special notation interpreted by the shell. Redirection may also be used to open and close files for the current shell execution environment. The following redirection operators may precede or appear anywhere within a simple command or may follow a command. Redirections are processed in the order they appear, from left to right.

In the following descriptions, if the file descriptor number is omitted, and the first character of the redirection operator is `<', the redirection refers to the standard input (file descriptor 0). If the first character of the redirection operator is `>', the redirection refers to the standard output (file descriptor 1).

The word following the redirection operator in the following descriptions, unless otherwise noted, is subjected to brace expansion, tilde expansion, parameter expansion, command substitution, arithmetic expansion, quote removal, filename expansion, and word splitting. If it expands to more than one word, Bash reports an error.

Note that the order of redirections is significant. For example, the command
ls > dirlist 2>&1
directs both standard output (file descriptor 1) and standard error (file descriptor 2) to the file dirlist, while the command
ls 2>&1 > dirlist
directs only the standard output to file dirlist, because the standard error was duplicated as standard output before the standard output was redirected to dirlist.

Bash handles several filenames specially when they are used in redirections, as described in the following table:

/dev/fd/fd
If fd is a valid integer, file descriptor fd is duplicated.

/dev/stdin
File descriptor 0 is duplicated.

/dev/stdout
File descriptor 1 is duplicated.

/dev/stderr
File descriptor 2 is duplicated.

/dev/tcp/host/port
If host is a valid hostname or Internet address, and port is an integer port number or service name, Bash attempts to open a TCP connection to the corresponding socket.

/dev/udp/host/port
If host is a valid hostname or Internet address, and port is an integer port number or service name, Bash attempts to open a UDP connection to the corresponding socket.

A failure to open or create a file causes the redirection to fail.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.1 Redirecting Input

Redirection of input causes the file whose name results from the expansion of word to be opened for reading on file descriptor n, or the standard input (file descriptor 0) if n is not specified.

The general format for redirecting input is:
[n]<word

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.2 Redirecting Output

Redirection of output causes the file whose name results from the expansion of word to be opened for writing on file descriptor n, or the standard output (file descriptor 1) if n is not specified. If the file does not exist it is created; if it does exist it is truncated to zero size.

The general format for redirecting output is:
[n]>[|]word

If the redirection operator is `>', and the noclobber option to the set builtin has been enabled, the redirection will fail if the file whose name results from the expansion of word exists and is a regular file. If the redirection operator is `>|', or the redirection operator is `>' and the noclobber option is not enabled, the redirection is attempted even if the file named by word exists.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.3 Appending Redirected Output

Redirection of output in this fashion causes the file whose name results from the expansion of word to be opened for appending on file descriptor n, or the standard output (file descriptor 1) if n is not specified. If the file does not exist it is created.

The general format for appending output is:
[n]>>word

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.4 Redirecting Standard Output and Standard Error

Bash allows both the standard output (file descriptor 1) and the standard error output (file descriptor 2) to be redirected to the file whose name is the expansion of word with this construct.

There are two formats for redirecting standard output and standard error:
&>word
and
>&word
Of the two forms, the first is preferred. This is semantically equivalent to
>word 2>&1

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.5 Here Documents

This type of redirection instructs the shell to read input from the current source until a line containing only word (with no trailing blanks) is seen. All of the lines read up to that point are then used as the standard input for a command.

The format of here-documents is as follows:
<<[-]word
        here-document
delimiter

No parameter expansion, command substitution, arithmetic expansion, or filename expansion is performed on word. If any characters in word are quoted, the delimiter is the result of quote removal on word, and the lines in the here-document are not expanded. If word is unquoted, all lines of the here-document are subjected to parameter expansion, command substitution, and arithmetic expansion. In the latter case, the character sequence \newline is ignored, and `\' must be used to quote the characters `\', `$', and ``'.

If the redirection operator is `<<-', then all leading tab characters are stripped from input lines and the line containing delimiter. This allows here-documents within shell scripts to be indented in a natural fashion.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.6 Duplicating File Descriptors

The redirection operator
[n]<&word
is used to duplicate input file descriptors. If word expands to one or more digits, the file descriptor denoted by n is made to be a copy of that file descriptor. If the digits in word do not specify a file descriptor open for input, a redirection error occurs. If word evaluates to `-', file descriptor n is closed. If n is not specified, the standard input (file descriptor 0) is used.

The operator
[n]>&word
is used similarly to duplicate output file descriptors. If n is not specified, the standard output (file descriptor 1) is used. If the digits in word do not specify a file descriptor open for output, a redirection error occurs. As a special case, if n is omitted, and word does not expand to one or more digits, the standard output and standard error are redirected as described previously.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.7 Opening File Descriptors for Reading and Writing

The redirection operator
[n]<>word
causes the file whose name is the expansion of word to be opened for both reading and writing on file descriptor n, or on file descriptor 0 if n is not specified. If the file does not exist, it is created.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7 Executing Commands

3.7.1 Simple Command Expansion How Bash expands simple commands before executing them.

3.7.2 Command Search and Execution How Bash finds commands and runs them.

3.7.3 Command Execution Environment The environment in which Bash executes commands that are not shell builtins.

3.7.4 Environment The environment given to a command.

3.7.5 Exit Status The status returned by commands and how Bash interprets it.

3.7.6 Signals What happens when Bash or a command it runs receives a signal.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7.1 Simple Command Expansion

When a simple command is executed, the shell performs the following expansions, assignments, and redirections, from left to right.

  1. The words that the parser has marked as variable assignments (those preceding the command name) and redirections are saved for later processing.

  2. The words that are not variable assignments or redirections are expanded (see section 3.5 Shell Expansions). If any words remain after expansion, the first word is taken to be the name of the command and the remaining words are the arguments.

  3. Redirections are performed as described above (see section 3.6 Redirections).

  4. The text after the `=' in each variable assignment undergoes tilde expansion, parameter expansion, command substitution, arithmetic expansion, and quote removal before being assigned to the variable.

If no command name results, the variable assignments affect the current shell environment. Otherwise, the variables are added to the environment of the executed command and do not affect the current shell environment. If any of the assignments attempts to assign a value to a readonly variable, an error occurs, and the command exits with a non-zero status.

If no command name results, redirections are performed, but do not affect the current shell environment. A redirection error causes the command to exit with a non-zero status.

If there is a command name left after expansion, execution proceeds as described below. Otherwise, the command exits. If one of the expansions contained a command substitution, the exit status of the command is the exit status of the last command substitution performed. If there were no command substitutions, the command exits with a status of zero.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7.2 Command Search and Execution

After a command has been split into words, if it results in a simple command and an optional list of arguments, the following actions are taken.

  1. If the command name contains no slashes, the shell attempts to locate it. If there exists a shell function by that name, that function is invoked as described in 3.3 Shell Functions.

  2. If the name does not match a function, the shell searches for it in the list of shell builtins. If a match is found, that builtin is invoked.

  3. If the name is neither a shell function nor a builtin, and contains no slashes, Bash searches each element of $PATH for a directory containing an executable file by that name. Bash uses a hash table to remember the full pathnames of executable files to avoid multiple PATH searches (see the description of hash in 4.1 Bourne Shell Builtins). A full search of the directories in $PATH is performed only if the command is not found in the hash table. If the search is unsuccessful, the shell prints an error message and returns an exit status of 127.

  4. If the search is successful, or if the command name contains one or more slashes, the shell executes the named program in a separate execution environment. Argument 0 is set to the name given, and the remaining arguments to the command are set to the arguments supplied, if any.

  5. If this execution fails because the file is not in executable format, and the file is not a directory, it is assumed to be a shell script and the shell executes it as described in 3.8 Shell Scripts.

  6. If the command was not begun asynchronously, the shell waits for the command to complete and collects its exit status.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7.3 Command Execution Environment

The shell has an execution environment, which consists of the following:

  • open files inherited by the shell at invocation, as modified by redirections supplied to the exec builtin

  • the current working directory as set by cd, pushd, or popd, or inherited by the shell at invocation

  • the file creation mode mask as set by umask or inherited from the shell's parent

  • current traps set by trap

  • shell parameters that are set by variable assignment or with set or inherited from the shell's parent in the environment

  • shell functions defined during execution or inherited from the shell's parent in the environment

  • options enabled at invocation (either by default or with command-line arguments) or by set

  • options enabled by shopt

  • shell aliases defined with alias (see section 6.6 Aliases)

  • various process IDs, including those of background jobs (see section 3.2.3 Lists of Commands), the value of $$, and the value of $PPID

When a simple command other than a builtin or shell function is to be executed, it is invoked in a separate execution environment that consists of the following. Unless otherwise noted, the values are inherited from the shell.

  • the shell's open files, plus any modifications and additions specified by redirections to the command

  • the current working directory

  • the file creation mode mask

  • shell variables marked for export, along with variables exported for the command, passed in the environment (see section 3.7.4 Environment)

  • traps caught by the shell are reset to the values inherited from the shell's parent, and traps ignored by the shell are ignored

A command invoked in this separate environment cannot affect the shell's execution environment.

Command substitution and asynchronous commands are invoked in a subshell environment that is a duplicate of the shell environment, except that traps caught by the shell are reset to the values that the shell inherited from its parent at invocation. Builtin commands that are invoked as part of a pipeline are also executed in a subshell environment. Changes made to the subshell environment cannot affect the shell's execution environment.

If a command is followed by a `&' and job control is not active, the default standard input for the command is the empty file `/dev/null'. Otherwise, the invoked command inherits the file descriptors of the calling shell as modified by redirections.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7.4 Environment

When a program is invoked it is given an array of strings called the environment. This is a list of name-value pairs, of the form name=value.

Bash provides several ways to manipulate the environment. On invocation, the shell scans its own environment and creates a parameter for each name found, automatically marking it for export to child processes. Executed commands inherit the environment. The export and `declare -x' commands allow parameters and functions to be added to and deleted from the environment. If the value of a parameter in the environment is modified, the new value becomes part of the environment, replacing the old. The environment inherited by any executed command consists of the shell's initial environment, whose values may be modified in the shell, less any pairs removed by the unset and `export -n' commands, plus any additions via the export and `declare -x' commands.

The environment for any simple command or function may be augmented temporarily by prefixing it with parameter assignments, as described in 3.4 Shell Parameters. These assignment statements affect only the environment seen by that command.

If the `-k' option is set (see section 4.3 The Set Builtin), then all parameter assignments are placed in the environment for a command, not just those that precede the command name.

When Bash invokes an external command, the variable `$_' is set to the full path name of the command and passed to that command in its environment.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7.5 Exit Status

For the shell's purposes, a command which exits with a zero exit status has succeeded. A non-zero exit status indicates failure. This seemingly counter-intuitive scheme is used so there is one well-defined way to indicate success and a variety of ways to indicate various failure modes. When a command terminates on a fatal signal whose number is N, Bash uses the value 128+N as the exit status.

If a command is not found, the child process created to execute it returns a status of 127. If a command is found but is not executable, the return status is 126.

If a command fails because of an error during expansion or redirection, the exit status is greater than zero.

The exit status is used by the Bash conditional commands (see section 3.2.5 Conditional Constructs) and some of the list constructs (see section 3.2.3 Lists of Commands).

All of the Bash builtins return an exit status of zero if they succeed and a non-zero status on failure, so they may be used by the conditional and list constructs. All builtins return an exit status of 2 to indicate incorrect usage.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7.6 Signals

When Bash is interactive, in the absence of any traps, it ignores SIGTERM (so that `kill 0' does not kill an interactive shell), and SIGINT is caught and handled (so that the wait builtin is interruptible). When Bash receives a SIGINT, it breaks out of any executing loops. In all cases, Bash ignores SIGQUIT. If job control is in effect (see section 7. Job Control), Bash ignores SIGTTIN, SIGTTOU, and SIGTSTP.

Commands started by Bash have signal handlers set to the values inherited by the shell from its parent. When job control is not in effect, asynchronous commands ignore SIGINT and SIGQUIT as well. Commands run as a result of command substitution ignore the keyboard-generated job control signals SIGTTIN, SIGTTOU, and SIGTSTP.

The shell exits by default upon receipt of a SIGHUP. Before exiting, an interactive shell resends the SIGHUP to all jobs, running or stopped. Stopped jobs are sent SIGCONT to ensure that they receive the SIGHUP. To prevent the shell from sending the SIGHUP signal to a particular job, it should be removed from the jobs table with the disown builtin (see section 7.2 Job Control Builtins) or marked to not receive SIGHUP using disown -h.

If the huponexit shell option has been set with shopt (see section 4.2 Bash Builtin Commands), Bash sends a SIGHUP to all jobs when an interactive login shell exits.

When Bash receives a signal for which a trap has been set while waiting for a command to complete, the trap will not be executed until the command completes. When Bash is waiting for an asynchronous command via the wait builtin, the reception of a signal for which a trap has been set will cause the wait builtin to return immediately with an exit status greater than 128, immediately after which the trap is executed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.8 Shell Scripts

A shell script is a text file containing shell commands. When such a file is used as the first non-option argument when invoking Bash, and neither the `-c' nor `-s' option is supplied (see section 6.1 Invoking Bash), Bash reads and executes commands from the file, then exits. This mode of operation creates a non-interactive shell. The shell first searches for the file in the current directory, and looks in the directories in $PATH if not found there.

When Bash runs a shell script, it sets the special parameter 0 to the name of the file, rather than the name of the shell, and the positional parameters are set to the remaining arguments, if any are given. If no additional arguments are supplied, the positional parameters are unset.

A shell script may be made executable by using the chmod command to turn on the execute bit. When Bash finds such a file while searching the $PATH for a command, it spawns a subshell to execute it. In other words, executing
filename arguments
is equivalent to executing
bash filename arguments

if filename is an executable shell script. This subshell reinitializes itself, so that the effect is as if a new shell had been invoked to interpret the script, with the exception that the locations of commands remembered by the parent (see the description of hash in 4.1 Bourne Shell Builtins) are retained by the child.

Most versions of Unix make this a part of the operating system's command execution mechanism. If the first line of a script begins with the two characters `#!', the remainder of the line specifies an interpreter for the program. Thus, you can specify Bash, awk, Perl, or some other interpreter and write the rest of the script file in that language.

The arguments to the interpreter consist of a single optional argument following the interpreter name on the first line of the script file, followed by the name of the script file, followed by the rest of the arguments. Bash will perform this action on operating systems that do not handle it themselves. Note that some older versions of Unix limit the interpreter name and argument to a maximum of 32 characters.

Bash scripts often begin with #! /bin/bash (assuming that Bash has been installed in `/bin'), since this ensures that Bash will be used to interpret the script, even if it is executed under another shell.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Shell Builtin Commands

4.1 Bourne Shell Builtins | Builtin commands inherited from the Bourne Shell.
4.2 Bash Builtin Commands | Table of builtins specific to Bash.
4.3 The Set Builtin | This builtin is so overloaded it deserves its own section.
4.4 Special Builtins | Builtin commands classified specially by POSIX.2.

Builtin commands are contained within the shell itself. When the name of a builtin command is used as the first word of a simple command (see section 3.2.1 Simple Commands), the shell executes the command directly, without invoking another program. Builtin commands are necessary to implement functionality impossible or inconvenient to obtain with separate utilities.

This section briefly the builtins which Bash inherits from the Bourne Shell, as well as the builtin commands which are unique to or have been extended in Bash.

Several builtin commands are described in other chapters: builtin commands which provide the Bash interface to the job control facilities (see section 7.2 Job Control Builtins), the directory stack (see section 6.8.1 Directory Stack Builtins), the command history (see section 9.2 Bash History Builtins), and the programmable completion facilities (see section 8.7 Programmable Completion Builtins).

Many of the builtins have been extended by POSIX or Bash.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 Bourne Shell Builtins

The following shell builtin commands are inherited from the Bourne Shell. These commands are implemented as specified by the POSIX 1003.2 standard.

: (a colon)
: [arguments]
Do nothing beyond expanding arguments and performing redirections. The return status is zero.

. (a period)
. filename [arguments]
Read and execute commands from the filename argument in the current shell context. If filename does not contain a slash, the PATH variable is used to find filename. When Bash is not in POSIX mode, the current directory is searched if filename is not found in $PATH. If any arguments are supplied, they become the positional parameters when filename is executed. Otherwise the positional parameters are unchanged. The return status is the exit status of the last command executed, or zero if no commands are executed. If filename is not found, or cannot be read, the return status is non-zero. This builtin is equivalent to source.

break
break [n]
Exit from a for, while, until, or select loop. If n is supplied, the nth enclosing loop is exited. n must be greater than or equal to 1. The return status is zero unless n is not greater than or equal to 1.

cd
cd [-LP] [directory]
Change the current working directory to directory. If directory is not given, the value of the HOME shell variable is used. If the shell variable CDPATH exists, it is used as a search path. If directory begins with a slash, CDPATH is not used. The `-P' option means to not follow symbolic links; symbolic links are followed by default or with the `-L' option. If directory is `-', it is equivalent to $OLDPWD. The return status is zero if the directory is successfully changed, non-zero otherwise.

continue
continue [n]
Resume the next iteration of an enclosing for, while, until, or select loop. If n is supplied, the execution of the nth enclosing loop is resumed. n must be greater than or equal to 1. The return status is zero unless n is not greater than or equal to 1.

eval
eval [arguments]
The arguments are concatenated together into a single command, which is then read and executed, and its exit status returned as the exit status of eval. If there are no arguments or only empty arguments, the return status is zero.

exec
exec [-cl] [-a name] [command [arguments]]
If command is supplied, it replaces the shell without creating a new process. If the `-l' option is supplied, the shell places a dash at the beginning of the zeroth arg passed to command. This is what the login program does. The `-c' option causes command to be executed with an empty environment. If `-a' is supplied, the shell passes name as the zeroth argument to command. If no command is specified, redirections may be used to affect the current shell environment. If there are no redirection errors, the return status is zero; otherwise the return status is non-zero.

exit
exit [n]
Exit the shell, returning a status of n to the shell's parent. If n is omitted, the exit status is that of the last command executed. Any trap on EXIT is executed before the shell terminates.

export
export [-fn] [-p] [name[=value]]
Mark each name to be passed to child processes in the environment. If the `-f' option is supplied, the names refer to shell functions; otherwise the names refer to shell variables. The `-n' option means to no longer mark each name for export. If no names are supplied, or if the `-p' option is given, a list of exported names is displayed. The `-p' option displays output in a form that may be reused as input. The return status is zero unless an invalid option is supplied, one of the names is not a valid shell variable name, or `-f' is supplied with a name that is not a shell function.

getopts
getopts optstring name [args]
getopts is used by shell scripts to parse positional parameters. optstring contains the option characters to be recognized; if a character is followed by a colon, the option is expected to have an argument, which should be separated from it by white space. The colon (`:') and question mark (`?') may not be used as option characters. Each time it is invoked, getopts places the next option in the shell variable name, initializing name if it does not exist, and the index of the next argument to be processed into the variable OPTIND. OPTIND is initialized to 1 each time the shell or a shell script is invoked. When an option requires an argument, getopts places that argument into the variable OPTARG. The shell does not reset OPTIND automatically; it must be manually reset between multiple calls to getopts within the same shell invocation if a new set of parameters is to be used.

When the end of options is encountered, getopts exits with a return value greater than zero. OPTIND is set to the index of the first non-option argument, and name is set to `?'.

getopts normally parses the positional parameters, but if more arguments are given in args, getopts parses those instead.

getopts can report errors in two ways. If the first character of optstring is a colon, silent error reporting is used. In normal operation diagnostic messages are printed when invalid options or missing option arguments are encountered. If the variable OPTERR is set to 0, no error messages will be displayed, even if the first character of optstring is not a colon.

If an invalid option is seen, getopts places `?' into name and, if not silent, prints an error message and unsets OPTARG. If getopts is silent, the option character found is placed in OPTARG and no diagnostic message is printed.

If a required argument is not found, and getopts is not silent, a question mark (`?') is placed in name, OPTARG is unset, and a diagnostic message is printed. If getopts is silent, then a colon (`:') is placed in name and OPTARG is set to the option character found.

hash
hash [-r] [-p filename] [-t] [name]
Remember the full pathnames of commands specified as name arguments, so they need not be searched for on subsequent invocations. The commands are found by searching through the directories listed in $PATH. The `-p' option inhibits the path search, and filename is used as the location of name. The `-r' option causes the shell to forget all remembered locations. If the `-t' option is supplied, the full pathname to which each name corresponds is printed. If multiple name arguments are supplied with `-t' the name is printed before the hashed full pathname. If no arguments are given, information about remembered commands is printed. The return status is zero unless a name is not found or an invalid option is supplied.

pwd
pwd [-LP]
Print the absolute pathname of the current working directory. If the `-P' option is supplied, the pathname printed will not contain symbolic links. If the `-L' option is supplied, the pathname printed may contain symbolic links. The return status is zero unless an error is encountered while determining the name of the current directory or an invalid option is supplied.

readonly
readonly [-apf] [name] ...
Mark each name as readonly. The values of these names may not be changed by subsequent assignment. If the `-f' option is supplied, each name refers to a shell function. The `-a' option means each name refers to an array variable. If no name arguments are given, or if the `-p' option is supplied, a list of all readonly names is printed. The `-p' option causes output to be displayed in a format that may be reused as input. The return status is zero unless an invalid option is supplied, one of the name arguments is not a valid shell variable or function name, or the `-f' option is supplied with a name that is not a shell function.

return
return [n]
Cause a shell function to exit with the return value n. If n is not supplied, the return value is the exit status of the last command executed in the function. This may also be used to terminate execution of a script being executed with the . (or source) builtin, returning either n or the exit status of the last command executed within the script as the exit status of the script. The return status is non-zero if return is used outside a function and not during the execution of a script by . or source.

shift
shift [n]
Shift the positional parameters to the left by n. The positional parameters from n+1 ... $# are renamed to $1 ... $#-n+1. Parameters represented by the numbers $# to n+1 are unset. n must be a non-negative number less than or equal to $#. If n is zero or greater than $#, the positional parameters are not changed. If n is not supplied, it is assumed to be 1. The return status is zero unless n is greater than $# or less than zero, non-zero otherwise.

test
[
Evaluate a conditional expression expr. Each operator and operand must be a separate argument. Expressions are composed of the primaries described below in 6.4 Bash Conditional Expressions.

When the [ form is used, the last argument to the command must be a ].

Expressions may be combined using the following operators, listed in decreasing order of precedence.

! expr
True if expr is false.

( expr )
Returns the value of expr. This may be used to override the normal precedence of operators.

expr1 -a expr2
True if both expr1 and expr2 are true.

expr1 -o expr2
True if either expr1 or expr2 is true.

The test and [ builtins evaluate conditional expressions using a set of rules based on the number of arguments.

0 arguments
The expression is false.

1 argument
The expression is true if and only if the argument is not null.

2 arguments
If the first argument is `!', the expression is true if and only if the second argument is null. If the first argument is one of the unary conditional operators (see section 6.4 Bash Conditional Expressions), the expression is true if the unary test is true. If the first argument is not a valid unary operator, the expression is false.

3 arguments
If the second argument is one of the binary conditional operators (see section 6.4 Bash Conditional Expressions), the result of the expression is the result of the binary test using the first and third arguments as operands. If the first argument is `!', the value is the negation of the two-argument test using the second and third arguments. If the first argument is exactly `(' and the third argument is exactly `)', the result is the one-argument test of the second argument. Otherwise, the expression is false. The `-a' and `-o' operators are considered binary operators in this case.

4 arguments
If the first argument is `!', the result is the negation of the three-argument expression composed of the remaining arguments. Otherwise, the expression is parsed and evaluated according to precedence using the rules listed above.

5 or more arguments
The expression is parsed and evaluated according to precedence using the rules listed above.

times
times
Print out the user and system times used by the shell and its children. The return status is zero.

trap
trap [-lp] [arg] [sigspec ...]
The commands in arg are to be read and executed when the shell receives signal sigspec. If arg is absent or equal to `-', all specified signals are reset to the values they had when the shell was started. If arg is the null string, then the signal specified by each sigspec is ignored by the shell and commands it invokes. If arg is not present and `-p' has been supplied, the shell displays the trap commands associated with each sigspec. If no arguments are supplied, or only `-p' is given, trap prints the list of commands associated with each signal number in a form that may be reused as shell input. Each sigspec is either a signal name such as SIGINT (with or without the SIG prefix) or a signal number. If a sigspec is 0 or EXIT, arg is executed when the shell exits. If a sigspec is DEBUG, the command arg is executed after every simple command. If a sigspec is ERR, the command arg is executed whenever a simple command has a non-zero exit status. The ERR trap is not executed if the failed command is part of an until or while loop, part of an if statement, part of a && or || list, or if the command's return status is being inverted using !. The `-l' option causes the shell to print a list of signal names and their corresponding numbers.

Signals ignored upon entry to the shell cannot be trapped or reset. Trapped signals are reset to their original values in a child process when it is created.

The return status is zero unless a sigspec does not specify a valid signal.

umask
umask [-p] [-S] [mode]
Set the shell process's file creation mask to mode. If mode begins with a digit, it is interpreted as an octal number; if not, it is interpreted as a symbolic mode mask similar to that accepted by the chmod command. If mode is omitted, the current value of the mask is printed. If the `-S' option is supplied without a mode argument, the mask is printed in a symbolic format. If the `-p' option is supplied, and mode is omitted, the output is in a form that may be reused as input. The return status is zero if the mode is successfully changed or if no mode argument is supplied, and non-zero otherwise.

Note that when the mode is interpreted as an octal number, each number of the umask is subtracted from 7. Thus, a umask of 022 results in permissions of 755.

unset
unset [-fv] [name]
Each variable or function name is removed. If no options are supplied, or the `-v' option is given, each name refers to a shell variable. If the `-f' option is given, the names refer to shell functions, and the function definition is removed. Readonly variables and functions may not be unset. The return status is zero unless a name does not exist or is readonly.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2 Bash Builtin Commands

This section describes builtin commands which are unique to or have been extended in Bash. Some of these commands are specified in the POSIX 1003.2 standard.

alias
alias [-p] [name[=value] ...]

Without arguments or with the `-p' option, alias prints the list of aliases on the standard output in a form that allows them to be reused as input. If arguments are supplied, an alias is defined for each name whose value is given. If no value is given, the name and value of the alias is printed. Aliases are described in 6.6 Aliases.

bind
bind [-m keymap] [-lpsvPSV]
bind [-m keymap] [-q function] [-u function] [-r keyseq]
bind [-m keymap] -f filename
bind [-m keymap] -x keyseq:shell-command
bind [-m keymap] keyseq:function-name

Display current Readline (see section 8. Command Line Editing) key and function bindings, or bind a key sequence to a Readline function or macro. The binding syntax accepted is identical to that of a Readline initialization file (see section 8.3 Readline Init File), but each binding must be passed as a separate argument: e.g., `"\C-x\C-r":re-read-init-file'. Options, if supplied, have the following meanings:

-m keymap
Use keymap as the keymap to be affected by the subsequent bindings. Acceptable keymap names are emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. vi is equivalent to vi-command; emacs is equivalent to emacs-standard.

-l
List the names of all Readline functions.

-p
Display Readline function names and bindings in such a way that they can be used as input or in a Readline initialization file.

-P
List current Readline function names and bindings.

-v
Display Readline variable names and values in such a way that they can be used as input or in a Readline initialization file.

-V
List current Readline variable names and values.

-s
Display Readline key sequences bound to macros and the strings they output in such a way that they can be used as input or in a Readline initialization file.

-S
Display Readline key sequences bound to macros and the strings they output.

-f filename
Read key bindings from filename.

-q function
Query about which keys invoke the named function.

-u function
Unbind all keys bound to the named function.

-r keyseq
Remove any current binding for keyseq.

-x keyseq:shell-command
Cause shell-command to be executed whenever keyseq is entered.

The return status is zero unless an invalid option is supplied or an error occurs.

builtin
builtin [shell-builtin [args]]
Run a shell builtin, passing it args, and return its exit status. This is useful when defining a shell function with the same name as a shell builtin, retaining the functionality of the builtin within the function. The return status is non-zero if shell-builtin is not a shell builtin command.

command
command [-pVv] command [arguments ...]
Runs command with arguments ignoring any shell function named command. Only shell builtin commands or commands found by searching the PATH are executed. If there is a shell function named ls, running `command ls' within the function will execute the external command ls instead of calling the function recursively. The `-p' option means to use a default value for PATH that is guaranteed to find all of the standard utilities. The return status in this case is 127 if command cannot be found or an error occurred, and the exit status of command otherwise.

If either the `-V' or `-v' option is supplied, a description of command is printed. The `-v' option causes a single word indicating the command or file name used to invoke command to be displayed; the `-V' option produces a more verbose description. In this case, the return status is zero if command is found, and non-zero if not.

declare
declare [-afFrxi] [-p] [name[=value]]

Declare variables and give them attributes. If no names are given, then display the values of variables instead.

The `-p' option will display the attributes and values of each name. When `-p' is used, additional options are ignored. The `-F' option inhibits the display of function definitions; only the function name and attributes are printed. `-F' implies `-f'. The following options can be used to restrict output to variables with the specified attributes or to give variables attributes:

-a
Each name is an array variable (see section 6.7 Arrays).

-f
Use function names only.

-i
The variable is to be treated as an integer; arithmetic evaluation (see section 6.5 Shell Arithmetic) is performed when the variable is assigned a value.

-r
Make names readonly. These names cannot then be assigned values by subsequent assignment statements or unset.

-x
Mark each name for export to subsequent commands via the environment.

Using `+' instead of `-' turns off the attribute instead. When used in a function, declare makes each name local, as with the local command.

The return status is zero unless an invalid option is encountered, an attempt is made to define a function using `-f foo=bar', an attempt is made to assign a value to a readonly variable, an attempt is made to assign a value to an array variable without using the compound assignment syntax (see section 6.7 Arrays), one of the names is not a valid shell variable name, an attempt is made to turn off readonly status for a readonly variable, an attempt is made to turn off array status for an array variable, or an attempt is made to display a non-existent function with `-f'.

echo
echo [-neE] [arg ...]
Output the args, separated by spaces, terminated with a newline. The return status is always 0. If `-n' is specified, the trailing newline is suppressed. If the `-e' option is given, interpretation of the following backslash-escaped characters is enabled. The `-E' option disables the interpretation of these escape characters, even on systems where they are interpreted by default. The xpg_echo shell option may be used to dynamically determine whether or not echo expands these escape characters by default. echo interprets the following escape sequences:
\a
alert (bell)
\b
backspace
\c
suppress trailing newline
\e
escape
\f
form feed
\n
new line
\r
carriage return
\t
horizontal tab
\v
vertical tab
\\
backslash
\nnn
the eight-bit character whose value is the octal value nnn (one to three digits)
\xHH
the eight-bit character whose value is the hexadecimal value HH (one or two hex digits)

enable
enable [-n] [-p] [-f filename] [-ads] [name ...]
Enable and disable builtin shell commands. Disabling a builtin allows a disk command which has the same name as a shell builtin to be executed without specifying a full pathname, even though the shell normally searches for builtins before disk commands. If `-n' is used, the names become disabled. Otherwise names are enabled. For example, to use the test binary found via $PATH instead of the shell builtin version, type `enable -n test'.

If the `-p' option is supplied, or no name arguments appear, a list of shell builtins is printed. With no other arguments, the list consists of all enabled shell builtins. The `-a' option means to list each builtin with an indication of whether or not it is enabled.

The `-f' option means to load the new builtin command name from shared object filename, on systems that support dynamic loading. The `-d' option will delete a builtin loaded with `-f'.

If there are no options, a list of the shell builtins is displayed. The `-s' option restricts enable to the POSIX special builtins. If `-s' is used with `-f', the new builtin becomes a special builtin (see section 4.4 Special Builtins).

The return status is zero unless a name is not a shell builtin or there is an error loading a new builtin from a shared object.

help
help [-s] [pattern]
Display helpful information about builtin commands. If pattern is specified, help gives detailed help on all commands matching pattern, otherwise a list of the builtins is printed. The `-s' option restricts the information displayed to a short usage synopsis. The return status is zero unless no command matches pattern.

let
let expression [expression]
The let builtin allows arithmetic to be performed on shell variables. Each expression is evaluated according to the rules given below in 6.5 Shell Arithmetic. If the last expression evaluates to 0, let returns 1; otherwise 0 is returned.

local
local [option] name[=value]
For each argument, a local variable named name is created, and assigned value. The option can be any of the options accepted by declare. local can only be used within a function; it makes the variable name have a visible scope restricted to that function and its children. The return status is zero unless local is used outside a function, an invalid name is supplied, or name is a readonly variable.

logout
logout [n]
Exit a login shell, returning a status of n to the shell's parent.

printf
printf format [arguments]
Write the formatted arguments to the standard output under the control of the format. The format is a character string which contains three types of objects: plain characters, which are simply copied to standard output, character escape sequences, which are converted and copied to the standard output, and format specifications, each of which causes printing of the next successive argument. In addition to the standard printf(1) formats, `%b' causes printf to expand backslash escape sequences in the corresponding argument, and `%q' causes printf to output the corresponding argument in a format that can be reused as shell input.

The format is reused as necessary to consume all of the arguments. If the format requires more arguments than are supplied, the extra format specifications behave as if a zero value or null string, as appropriate, had been supplied. The return value is zero on success, non-zero on failure.

read
read [-ers] [-a aname] [-p prompt] [-t timeout] [-n nchars] [-d delim] [name ...]
One line is read from the standard input, and the first word is assigned to the first name, the second word to the second name, and so on, with leftover words and their intervening separators assigned to the last name. If there are fewer words read from the standard input than names, the remaining names are assigned empty values. The characters in the value of the IFS variable are used to split the line into words. The backslash character `\' may be used to remove any special meaning for the next character read and for line continuation. If no names are supplied, the line read is assigned to the variable REPLY. The return code is zero, unless end-of-file is encountered or read times out. Options, if supplied, have the following meanings:

-a aname
The words are assigned to sequential indices of the array variable aname, starting at 0. All elements are removed from aname before the assignment. Other name arguments are ignored.

-d delim
The first character of delim is used to terminate the input line, rather than newline.

-e
Readline (see section 8. Command Line Editing) is used to obtain the line.

-n nchars
read returns after reading nchars characters rather than waiting for a complete line of input.

-p prompt
Display prompt, without a trailing newline, before attempting to read any input. The prompt is displayed only if input is coming from a terminal.

-r
If this option is given, backslash does not act as an escape character. The backslash is considered to be part of the line. In particular, a backslash-newline pair may not be used as a line continuation.

-s
Silent mode. If input is coming from a terminal, characters are not echoed.

-t timeout
Cause read to time out and return failure if a complete line of input is not read within timeout seconds. This option has no effect if read is not reading input from the terminal or a pipe.

shopt
shopt [-pqsu] [-o] [optname ...]
Toggle the values of variables controlling optional shell behavior. With no options, or with the `-p' option, a list of all settable options is displayed, with an indication of whether or not each is set. The `-p' option causes output to be displayed in a form that may be reused as input. Other options have the following meanings:

-s
Enable (set) each optname.

-u
Disable (unset) each optname.

-q
Suppresses normal output; the return status indicates whether the optname is set or unset. If multiple optname arguments are given with `-q', the return status is zero if all optnames are enabled; non-zero otherwise.

-o
Restricts the values of optname to be those defined for the `-o' option to the set builtin (see section 4.3 The Set Builtin).

If either `-s' or `-u' is used with no optname arguments, the display is limited to those options which are set or unset, respectively.

Unless otherwise noted, the shopt options are disabled (off) by default.

The return status when listing options is zero if all optnames are enabled, non-zero otherwise. When setting or unsetting options, the return status is zero unless an optname is not a valid shell option.

The list of shopt options is:

cdable_vars
If this is set, an argument to the cd builtin command that is not a directory is assumed to be the name of a variable whose value is the directory to change to.

cdspell
If set, minor errors in the spelling of a directory component in a cd command will be corrected. The errors checked for are transposed characters, a missing character, and a character too many. If a correction is found, the corrected path is printed, and the command proceeds. This option is only used by interactive shells.

checkhash
If this is set, Bash checks that a command found in the hash table exists before trying to execute it. If a hashed command no longer exists, a normal path search is performed.

checkwinsize
If set, Bash checks the window size after each command and, if necessary, updates the values of LINES and COLUMNS.

cmdhist
If set, Bash attempts to save all lines of a multiple-line command in the same history entry. This allows easy re-editing of multi-line commands.

dotglob
If set, Bash includes filenames beginning with a `.' in the results of filename expansion.

execfail
If this is set, a non-interactive shell will not exit if it cannot execute the file specified as an argument to the exec builtin command. An interactive shell does not exit if exec fails.

expand_aliases
If set, aliases are expanded as described below under Aliases, 6.6 Aliases. This option is enabled by default for interactive shells.

extglob
If set, the extended pattern matching features described above (see section 3.5.8.1 Pattern Matching) are enabled.

histappend
If set, the history list is appended to the file named by the value of the HISTFILE variable when the shell exits, rather than overwriting the file.

histreedit
If set, and Readline is being used, a user is given the opportunity to re-edit a failed history substitution.

histverify
If set, and Readline is being used, the results of history substitution are not immediately passed to the shell parser. Instead, the resulting line is loaded into the Readline editing buffer, allowing further modification.

hostcomplete
If set, and Readline is being used, Bash will attempt to perform hostname completion when a word containing a `@' is being completed (see section 8.4.6 Letting Readline Type For You). This option is enabled by default.

huponexit
If set, Bash will send SIGHUP to all jobs when an interactive login shell exits (see section 3.7.6 Signals).

interactive_comments
Allow a word beginning with `#' to cause that word and all remaining characters on that line to be ignored in an interactive shell. This option is enabled by default.

lithist
If enabled, and the cmdhist option is enabled, multi-line commands are saved to the history with embedded newlines rather than using semicolon separators where possible.

login_shell
The shell sets this option if it is started as a login shell (see section 6.1 Invoking Bash). The value may not be changed.

mailwarn
If set, and a file that Bash is checking for mail has been accessed since the last time it was checked, the message "The mail in mailfile has been read" is displayed.

no_empty_cmd_completion
If set, and Readline is being used, Bash will not attempt to search the PATH for possible completions when completion is attempted on an empty line.

nocaseglob
If set, Bash matches filenames in a case-insensitive fashion when performing filename expansion.

nullglob
If set, Bash allows filename patterns which match no files to expand to a null string, rather than themselves.

progcomp
If set, the programmable completion facilities (see section 8.6 Programmable Completion) are enabled. This option is enabled by default.

promptvars
If set, prompt strings undergo variable and parameter expansion after being expanded (see section 6.9 Controlling the Prompt). This option is enabled by default.

restricted_shell
The shell sets this option if it is started in restricted mode (see section 6.10 The Restricted Shell). The value may not be changed. This is not reset when the startup files are executed, allowing the startup files to discover whether or not a shell is restricted.

shift_verbose
If this is set, the shift builtin prints an error message when the shift count exceeds the number of positional parameters.

sourcepath
If set, the source builtin uses the value of PATH to find the directory containing the file supplied as an argument. This option is enabled by default.

xpg_echo
If set, the echo builtin expands backslash-escape sequences by default.

The return status when listing options is zero if all optnames are enabled, non-zero otherwise. When setting or unsetting options, the return status is zero unless an optname is not a valid shell option.

source
source filename
A synonym for . (see section 4.1 Bourne Shell Builtins).

type
type [-atp] [name ...]
For each name, indicate how it would be interpreted if used as a command name.

If the `-t' option is used, type prints a single word which is one of `alias', `function', `builtin', `file' or `keyword', if name is an alias, shell function, shell builtin, disk file, or shell reserved word, respectively. If the name is not found, then nothing is printed, and type returns a failure status.

If the `-p' option is used, type either returns the name of the disk file that would be executed, or nothing if `-t' would not return `file'.

If the `-a' option is used, type returns all of the places that contain an executable named file. This includes aliases and functions, if and only if the `-p' option is not also used.

The return status is zero if any of the names are found, non-zero if none are found.

typeset
typeset [-afFrxi] [-p] [name[=value]]
The typeset command is supplied for compatibility with the Korn shell; however, it has been deprecated in favor of the declare builtin command.

ulimit
ulimit [-acdflmnpstuvSH] [limit]
ulimit provides control over the resources available to processes started by the shell, on systems that allow such control. If an option is given, it is interpreted as follows:
-S
Change and report the soft limit associated with a resource.

-H
Change and report the hard limit associated with a resource.

-a
All current limits are reported.

-c
The maximum size of core files created.

-d
The maximum size of a process's data segment.

-f
The maximum size of files created by the shell.

-l
The maximum size that may be locked into memory.

-m
The maximum resident set size.

-n
The maximum number of open file descriptors.

-p
The pipe buffer size.

-s
The maximum stack size.

-t
The maximum amount of cpu time in seconds.

-u
The maximum number of processes available to a single user.

-v
The maximum amount of virtual memory available to the process.

If limit is given, it is the new value of the specified resource; the special limit values hard, soft, and unlimited stand for the current hard limit, the current soft limit, and no limit, respectively. Otherwise, the current value of the soft limit for the specified resource is printed, unless the `-H' option is supplied. When setting new limits, if neither `-H' nor `-S' is supplied, both the hard and soft limits are set. If no option is given, then `-f' is assumed. Values are in 1024-byte increments, except for `-t', which is in seconds, `-p', which is in units of 512-byte blocks, and `-n' and `-u', which are unscaled values.

The return status is zero unless an invalid option or argument is supplied, or an error occurs while setting a new limit.

unalias
unalias [-a] [name ... ]

Remove each name from the list of aliases. If `-a' is supplied, all aliases are removed. Aliases are described in 6.6 Aliases.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3 The Set Builtin

This builtin is so complicated that it deserves its own section.

set
set [--abefhkmnptuvxBCHP] [-o option] [argument ...]

If no options or arguments are supplied, set displays the names and values of all shell variables and functions, sorted according to the current locale, in a format that may be reused as input.

When options are supplied, they set or unset shell attributes. Options, if specified, have the following meanings:

-a
Mark variables and function which are modified or created for export to the environment of subsequent commands.

-b
Cause the status of terminated background jobs to be reported immediately, rather than before printing the next primary prompt.

-e
Exit immediately if a simple command (see section 3.2.1 Simple Commands) exits with a non-zero status, unless the command that fails is part of an until or while loop, part of an if statement, part of a && or || list, or if the command's return status is being inverted using !. A trap on ERR, if set, is executed before the shell exits.

-f
Disable file name generation (globbing).

-h
Locate and remember (hash) commands as they are looked up for execution. This option is enabled by default.

-k
All arguments in the form of assignment statements are placed in the environment for a command, not just those that precede the command name.

-m
Job control is enabled (see section 7. Job Control).

-n
Read commands but do not execute them; this may be used to check a script for syntax errors. This option is ignored by interactive shells.

-o option-name

Set the option corresponding to option-name:

allexport
Same as -a.

braceexpand
Same as -B.

emacs
Use an emacs-style line editing interface (see section 8. Command Line Editing).

errexit
Same as -e.

hashall
Same as -h.

histexpand
Same as -H.

history
Enable command history, as described in 9.1 Bash History Facilities. This option is on by default in interactive shells.

ignoreeof
An interactive shell will not exit upon reading EOF.

keyword
Same as -k.

monitor
Same as -m.

noclobber
Same as -C.

noexec
Same as -n.

noglob
Same as -f.

nolog
Currently ignored.

notify
Same as -b.

nounset
Same as -u.

onecmd
Same as -t.

physical
Same as -P.

posix
Change the behavior of Bash where the default operation differs from the POSIX 1003.2 standard to match the standard (see section 6.11 Bash POSIX Mode). This is intended to make Bash behave as a strict superset of that standard.

privileged
Same as -p.

verbose
Same as -v.

vi
Use a vi-style line editing interface.

xtrace
Same as -x.

-p
Turn on privileged mode. In this mode, the $BASH_ENV and $ENV files are not processed, shell functions are not inherited from the environment, and the SHELLOPTS variable, if it appears in the environment, is ignored. If the shell is started with the effective user (group) id not equal to the real user (group) id, and the -p option is not supplied, these actions are taken and the effective user id is set to the real user id. If the -p option is supplied at startup, the effective user id is not reset. Turning this option off causes the effective user and group ids to be set to the real user and group ids.

-t
Exit after reading and executing one command.

-u
Treat unset variables as an error when performing parameter expansion. An error message will be written to the standard error, and a non-interactive shell will exit.

-v
Print shell input lines as they are read.

-x
Print a trace of simple commands and their arguments after they are expanded and before they are executed.

-B
The shell will perform brace expansion (see section 3.5.1 Brace Expansion). This option is on by default.

-C
Prevent output redirection using `>', `>&', and `<>' from overwriting existing files.

-H
Enable `!' style history substitution (see section 9.3 History Expansion). This option is on by default for interactive shells.

-P
If set, do not follow symbolic links when performing commands such as cd which change the current directory. The physical directory is used instead. By default, Bash follows the logical chain of directories when performing commands which change the current directory.

For example, if `/usr/sys' is a symbolic link to `/usr/local/sys' then:
$ cd /usr/sys; echo $PWD
/usr/sys
$ cd ..; pwd
/usr

If set -P is on, then:
$ cd /usr/sys; echo $PWD
/usr/local/sys
$ cd ..; pwd
/usr/local

--
If no arguments follow this option, then the positional parameters are unset. Otherwise, the positional parameters are set to the arguments, even if some of them begin with a `-'.

-
Signal the end of options, cause all remaining arguments to be assigned to the positional parameters. The `-x' and `-v' options are turned off. If there are no arguments, the positional parameters remain unchanged.

Using `+' rather than `-' causes these options to be turned off. The options can also be used upon invocation of the shell. The current set of options may be found in $-.

The remaining N arguments are positional parameters and are assigned, in order, to $1, $2, ... $N. The special parameter # is set to N.

The return status is always zero unless an invalid option is supplied.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4 Special Builtins

For historical reasons, the POSIX 1003.2 standard has classified several builtin commands as special. When Bash is executing in POSIX mode, the special builtins differ from other builtin commands in three respects:

  1. Special builtins are found before shell functions during command lookup.

  2. If a special builtin returns an error status, a non-interactive shell exits.

  3. Assignment statements preceding the command stay in effect in the shell environment after the command completes.

When Bash is not executing in POSIX mode, these builtins behave no differently than the rest of the Bash builtin commands. The Bash POSIX mode is described in 6.11 Bash POSIX Mode.

These are the POSIX special builtins:
break : . continue eval exec exit export readonly return set
shift trap unset

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Shell Variables

5.1 Bourne Shell Variables | Variables which Bash uses in the same way as the Bourne Shell.
5.2 Bash Variables | List of variables that exist in Bash.

This chapter describes the shell variables that Bash uses. Bash automatically assigns default values to a number of variables.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 Bourne Shell Variables

Bash uses certain shell variables in the same way as the Bourne shell. In some cases, Bash assigns a default value to the variable.

CDPATH
A colon-separated list of directories used as a search path for the cd builtin command.

HOME
The current user's home directory; the default for the cd builtin command. The value of this variable is also used by tilde expansion (see section 3.5.2 Tilde Expansion).

IFS
A list of characters that separate fields; used when the shell splits words as part of expansion.

MAIL
If this parameter is set to a filename and the MAILPATH variable is not set, Bash informs the user of the arrival of mail in the specified file.

MAILPATH
A colon-separated list of filenames which the shell periodically checks for new mail. Each list entry can specify the message that is printed when new mail arrives in the mail file by separating the file name from the message with a `?'. When used in the text of the message, $_ expands to the name of the current mail file.

OPTARG
The value of the last option argument processed by the getopts builtin.

OPTIND
The index of the last option argument processed by the getopts builtin.

PATH
A colon-separated list of directories in which the shell looks for commands.

PS1
The primary prompt string. The default value is `\s-\v\$ '. See section 6.9 Controlling the Prompt, for the complete list of escape sequences that are expanded before PS1 is displayed.

PS2
The secondary prompt string. The default value is `> '.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 Bash Variables

These variables are set or used by Bash, but other shells do not normally treat them specially.

A few variables used by Bash are described in different chapters: variables for controlling the job control facilities (see section 7.3 Job Control Variables).

BASH
The full pathname used to execute the current instance of Bash.

BASH_ENV
If this variable is set when Bash is invoked to execute a shell script, its value is expanded and used as the name of a startup file to read before executing the script. See section 6.2 Bash Startup Files.

BASH_VERSION
The version number of the current instance of Bash.

BASH_VERSINFO
A readonly array variable (see section 6.7 Arrays) whose members hold version information for this instance of Bash. The values assigned to the array members are as follows:

BASH_VERSINFO[0]
The major version number (the release).

BASH_VERSINFO[1]
The minor version number (the version).

BASH_VERSINFO[2]
The patch level.

BASH_VERSINFO[3]
The build version.

BASH_VERSINFO[4]
The release status (e.g., beta1).

BASH_VERSINFO[5]
The value of MACHTYPE.

COLUMNS
Used by the select builtin command to determine the terminal width when printing selection lists. Automatically set upon receipt of a SIGWINCH.

COMP_CWORD
An index into ${COMP_WORDS} of the word containing the current cursor position. This variable is available only in shell functions invoked by the programmable completion facilities (see section 8.6 Programmable Completion).

COMP_LINE
The current command line. This variable is available only in shell functions and external commands invoked by the programmable completion facilities (see section 8.6 Programmable Completion).

COMP_POINT
The index of the current cursor position relative to the beginning of the current command. If the current cursor position is at the end of the current command, the value of this variable is equal to ${#COMP_LINE}. This variable is available only in shell functions and external commands invoked by the programmable completion facilities (see section 8.6 Programmable Completion).

COMP_WORDS
An array variable consisting of the individual words in the current command line. This variable is available only in shell functions invoked by the programmable completion facilities (see section 8.6 Programmable Completion).

COMPREPLY
An array variable from which Bash reads the possible completions generated by a shell function invoked by the programmable completion facility (see section 8.6 Programmable Completion).

DIRSTACK
An array variable containing the current contents of the directory stack. Directories appear in the stack in the order they are displayed by the dirs builtin. Assigning to members of this array variable may be used to modify directories already in the stack, but the pushd and popd builtins must be used to add and remove directories. Assignment to this variable will not change the current directory. If DIRSTACK is unset, it loses its special properties, even if it is subsequently reset.

EUID
The numeric effective user id of the current user. This variable is readonly.

FCEDIT
The editor used as a default by the `-e' option to the fc builtin command.

FIGNORE
A colon-separated list of suffixes to ignore when performing filename completion. A file name whose suffix matches one of the entries in FIGNORE is excluded from the list of matched file names. A sample value is `.o:~'

FUNCNAME
The name of any currently-executing shell function. This variable exists only when a shell function is executing. Assignments to FUNCNAME have no effect and return an error status. If FUNCNAME is unset, it loses its special properties, even if it is subsequently reset.

GLOBIGNORE
A colon-separated list of patterns defining the set of filenames to be ignored by filename expansion. If a filename matched by a filename expansion pattern also matches one of the patterns in GLOBIGNORE, it is removed from the list of matches.

GROUPS
An array variable containing the list of groups of which the current user is a member. Assignments to GROUPS have no effect and return an error status. If GROUPS is unset, it loses its special properties, even if it is subsequently reset.

histchars
Up to three characters which control history expansion, quick substitution, and tokenization (see section 9.3 History Expansion). The first character is the history expansion character, that is, the character which signifies the start of a history expansion, normally `!'. The second character is the character which signifies `quick substitution' when seen as the first character on a line, normally `^'. The optional third character is the character which indicates that the remainder of the line is a comment when found as the first character of a word, usually `#'. The history comment character causes history substitution to be skipped for the remaining words on the line. It does not necessarily cause the shell parser to treat the rest of the line as a comment.

HISTCMD
The history number, or index in the history list, of the current command. If HISTCMD is unset, it loses its special properties, even if it is subsequently reset.

HISTCONTROL
A value of `ignorespace' means to not enter lines which begin with a space or tab into the history list. A value of `ignoredups' means to not enter lines which match the last entered line. A value of `ignoreboth' combines the two options. Unset, or set to any other value than those above, means to save all lines on the history list. The second and subsequent lines of a multi-line compound command are not tested, and are added to the history regardless of the value of HISTCONTROL.

HISTFILE
The name of the file to which the command history is saved. The default value is `~/.bash_history'.

HISTFILESIZE
The maximum number of lines contained in the history file. When this variable is assigned a value, the history file is truncated, if necessary, to contain no more than that number of lines. The history file is also truncated to this size after writing it when an interactive shell exits. The default value is 500.

HISTIGNORE
A colon-separated list of patterns used to decide which command lines should be saved on the history list. Each pattern is anchored at the beginning of the line and must match the complete line (no implicit `*' is appended). Each pattern is tested against the line after the checks specified by HISTCONTROL are applied. In addition to the normal shell pattern matching characters, `&' matches the previous history line. `&' may be escaped using a backslash; the backslash is removed before attempting a match. The second and subsequent lines of a multi-line compound command are not tested, and are added to the history regardless of the value of HISTIGNORE.

HISTIGNORE subsumes the function of HISTCONTROL. A pattern of `&' is identical to ignoredups, and a pattern of `[ ]*' is identical to ignorespace. Combining these two patterns, separating them with a colon, provides the functionality of ignoreboth.

HISTSIZE
The maximum number of commands to remember on the history list. The default value is 500.

HOSTFILE
Contains the name of a file in the same format as `/etc/hosts' that should be read when the shell needs to complete a hostname. The list of possible hostname completions may be changed while the shell is running; the next time hostname completion is attempted after the value is changed, Bash adds the contents of the new file to the existing list. If HOSTFILE is set, but has no value, Bash attempts to read `/etc/hosts' to obtain the list of possible hostname completions. When HOSTFILE is unset, the hostname list is cleared.

HOSTNAME
The name of the current host.

HOSTTYPE
A string describing the machine Bash is running on.

IGNOREEOF
Controls the action of the shell on receipt of an EOF character as the sole input. If set, the value denotes the number of consecutive EOF characters that can be read as the first character on an input line before the shell will exit. If the variable exists but does not have a numeric value (or has no value) then the default is 10. If the variable does not exist, then EOF signifies the end of input to the shell. This is only in effect for interactive shells.

INPUTRC
The name of the Readline initialization file, overriding the default of `~/.inputrc'.

LANG
Used to determine the locale category for any category not specifically selected with a variable starting with LC_.

LC_ALL
This variable overrides the value of LANG and any other LC_ variable specifying a locale category.

LC_COLLATE
This variable determines the collation order used when sorting the results of filename expansion, and determines the behavior of range expressions, equivalence classes, and collating sequences within filename expansion and pattern matching (see section 3.5.8 Filename Expansion).

LC_CTYPE
This variable determines the interpretation of characters and the behavior of character classes within filename expansion and pattern matching (see section 3.5.8 Filename Expansion).

LC_MESSAGES
This variable determines the locale used to translate double-quoted strings preceded by a `$' (see section 3.1.2.5 Locale-Specific Translation).

LC_NUMERIC
This variable determines the locale category used for number formatting.

LINENO
The line number in the script or shell function currently executing.

LINES
Used by the select builtin command to determine the column length for printing selection lists. Automatically set upon receipt of a SIGWINCH.

MACHTYPE
A string that fully describes the system type on which Bash is executing, in the standard GNU cpu-company-system format.

MAILCHECK
How often (in seconds) that the shell should check for mail in the files specified in the MAILPATH or MAIL variables. The default is 60 seconds. When it is time to check for mail, the shell does so before displaying the primary prompt. If this variable is unset, or set to a value that is not a number greater than or equal to zero, the shell disables mail checking.

OLDPWD
The previous working directory as set by the cd builtin.

OPTERR
If set to the value 1, Bash displays error messages generated by the getopts builtin command.

OSTYPE
A string describing the operating system Bash is running on.

PIPESTATUS
An array variable (see section 6.7 Arrays) containing a list of exit status values from the processes in the most-recently-executed foreground pipeline (which may contain only a single command).

POSIXLY_CORRECT
If this variable is in the environment when bash starts, the shell enters POSIX mode (see section 6.11 Bash POSIX Mode) before reading the startup files, as if the `--posix' invocation option had been supplied. If it is set while the shell is running, bash enables POSIX mode, as if the command
set -o posix
had been executed.

PPID
The process ID of the shell's parent process. This variable is readonly.

PROMPT_COMMAND
If set, the value is interpreted as a command to execute before the printing of each primary prompt ($PS1).

PS3
The value of this variable is used as the prompt for the select command. If this variable is not set, the select command prompts with `#? '

PS4
The value is the prompt printed before the command line is echoed when the `-x' option is set (see section 4.3 The Set Builtin). The first character of PS4 is replicated multiple times, as necessary, to indicate multiple levels of indirection. The default is `+ '.

PWD
The current working directory as set by the cd builtin.

RANDOM
Each time this parameter is referenced, a random integer between 0 and 32767 is generated. Assigning a value to this variable seeds the random number generator.

REPLY
The default variable for the read builtin.

SECONDS
This variable expands to the number of seconds since the shell was started. Assignment to this variable resets the count to the value assigned, and the expanded value becomes the value assigned plus the number of seconds since the assignment.

SHELLOPTS
A colon-separated list of enabled shell options. Each word in the list is a valid argument for the `-o' option to the set builtin command (see section 4.3 The Set Builtin). The options appearing in SHELLOPTS are those reported as `on' by `set -o'. If this variable is in the environment when Bash starts up, each shell option in the list will be enabled before reading any startup files. This variable is readonly.

SHLVL
Incremented by one each time a new instance of Bash is started. This is intended to be a count of how deeply your Bash shells are nested.

TIMEFORMAT
The value of this parameter is used as a format string specifying how the timing information for pipelines prefixed with the time reserved word should be displayed. The `%' character introduces an escape sequence that is expanded to a time value or other information. The escape sequences and their meanings are as follows; the braces denote optional portions.

%%
A literal `%'.

%[p][l]R
The elapsed time in seconds.

%[p][l]U
The number of CPU seconds spent in user mode.

%[p][l]S
The number of CPU seconds spent in system mode.

%P
The CPU percentage, computed as (%U + %S) / %R.

The optional p is a digit specifying the precision, the number of fractional digits after a decimal point. A value of 0 causes no decimal point or fraction to be output. At most three places after the decimal point may be specified; values of p greater than 3 are changed to 3. If p is not specified, the value 3 is used.

The optional l specifies a longer format, including minutes, of the form MMmSS.FFs. The value of p determines whether or not the fraction is included.

If this variable is not set, Bash acts as if it had the value
$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'
If the value is null, no timing information is displayed. A trailing newline is added when the format string is displayed.

TMOUT
If set to a value greater than zero, the value is interpreted as the number of seconds to wait for input after issuing the primary prompt when the shell is interactive. Bash terminates after that number of seconds if input does not arrive.

UID
The numeric real user id of the current user. This variable is readonly.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Bash Features

This section describes features unique to Bash.

6.1 Invoking Bash | Command line options that you can give to Bash.
6.2 Bash Startup Files | When and how Bash executes scripts.
6.3 Interactive Shells | What an interactive shell is.
6.4 Bash Conditional Expressions | Primitives used in composing expressions for the test builtin.
6.5 Shell Arithmetic | Arithmetic on shell variables.
6.6 Aliases | Substituting one command for another.
6.7 Arrays | Array Variables.
6.8 The Directory Stack | History of visited directories.
6.9 Controlling the Prompt | Controlling the PS1 string.
6.10 The Restricted Shell | A more controlled mode of shell execution.
6.11 Bash POSIX Mode | Making Bash behave more closely to what the POSIX standard specifies.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1 Invoking Bash

bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o option] [-O shopt_option] [argument ...]
bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o option] [-O shopt_option] -c string [argument ...]
bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o option] [-O shopt_option] [argument ...]

In addition to the single-character shell command-line options (see section 4.3 The Set Builtin), there are several multi-character options that you can use. These options must appear on the command line before the single-character options in order for them to be recognized.

--dump-po-strings
A list of all double-quoted strings preceded by `$' is printed on the standard ouput in the GNU gettext PO (portable object) file format. Equivalent to `-D' except for the output format.

--dump-strings
Equivalent to `-D'.

--help
Display a usage message on standard output and exit sucessfully.

--init-file filename
--rcfile filename
Execute commands from filename (instead of `~/.bashrc') in an interactive shell.

--login
Make this shell act as if it had been directly invoked by login. When the shell is interactive, this is equivalent to starting a login shell with `exec -l bash'. When the shell is not interactive, the login shell startup files will be executed. `exec bash --login' will replace the current shell with a Bash login shell. See section 6.2 Bash Startup Files, for a description of the special behavior of a login shell.

--noediting
Do not use the GNU Readline library (see section 8. Command Line Editing) to read command lines when the shell is interactive.

--noprofile
Don't load the system-wide startup file `/etc/profile' or any of the personal initialization files `~/.bash_profile', `~/.bash_login', or `~/.profile' when Bash is invoked as a login shell.

--norc
Don't read the `~/.bashrc' initialization file in an interactive shell. This is on by default if the shell is invoked as sh.

--posix
Change the behavior of Bash where the default operation differs from the POSIX 1003.2 standard to match the standard. This is intended to make Bash behave as a strict superset of that standard. See section 6.11 Bash POSIX Mode, for a description of the Bash POSIX mode.

--restricted
Make the shell a restricted shell (see section 6.10 The Restricted Shell).

--verbose
Equivalent to `-v'. Print shell input lines as they're read.

--version
Show version information for this instance of Bash on the standard output and exit successfully.

There are several single-character options that may be supplied at invocation which are not available with the set builtin.

-c string
Read and execute commands from string after processing the options, then exit. Any remaining arguments are assigned to the positional parameters, starting with $0.

-i
Force the shell to run interactively. Interactive shells are described in 6.3 Interactive Shells.

-r
Make the shell a restricted shell (see section 6.10 The Restricted Shell).

-s
If this option is present, or if no arguments remain after option processing, then commands are read from the standard input. This option allows the positional parameters to be set when invoking an interactive shell.

-D
A list of all double-quoted strings preceded by `$' is printed on the standard ouput. These are the strings that are subject to language translation when the current locale is not C or POSIX (see section 3.1.2.5 Locale-Specific Translation). This implies the `-n' option; no commands will be executed.

[-+]O [shopt_option]
shopt_option is one of the shell options accepted by the shopt builtin (see section 4. Shell Builtin Commands). If shopt_option is present, `-O' sets the value of that option; `+O' unsets it. If shopt_option is not supplied, the names and values of the shell options accepted by shopt are printed on the standard output. If the invocation option is `+O', the output is displayed in a format that may be reused as input.

--
A -- signals the end of options and disables further option processing. Any arguments after the -- are treated as filenames and arguments.

A login shell is one whose first character of argument zero is `-', or one invoked with the `--login' option.

An interactive shell is one started without non-option arguments, unless `-s' is specified, without specifying the `-c' option, and whose input and output are both connected to terminals (as determined by isatty(3)), or one started with the `-i' option. See section 6.3 Interactive Shells, for more information.

If arguments remain after option processing, and neither the `-c' nor the `-s' option has been supplied, the first argument is assumed to be the name of a file containing shell commands (see section 3.8 Shell Scripts). When Bash is invoked in this fashion, $0 is set to the name of the file, and the positional parameters are set to the remaining arguments. Bash reads and executes commands from this file, then exits. Bash's exit status is the exit status of the last command executed in the script. If no commands are executed, the exit status is 0.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.2 Bash Startup Files

This section describs how Bash executes its startup files. If any of the files exist but cannot be read, Bash reports an error. Tildes are expanded in file names as described above under Tilde Expansion (see section 3.5.2 Tilde Expansion).

Interactive shells are described in 6.3 Interactive Shells.

Invoked as an interactive login shell, or with `--login'

When Bash is invoked as an interactive login shell, or as a non-interactive shell with the `--login' option, it first reads and executes commands from the file `/etc/profile', if that file exists. After reading that file, it looks for `~/.bash_profile', `~/.bash_login', and `~/.profile', in that order, and reads and executes commands from the first one that exists and is readable. The `--noprofile' option may be used when the shell is started to inhibit this behavior.

When a login shell exits, Bash reads and executes commands from the file `~/.bash_logout', if it exists.

Invoked as an interactive non-login shell

When an interactive shell that is not a login shell is started, Bash reads and executes commands from `~/.bashrc', if that file exists. This may be inhibited by using the `--norc' option. The `--rcfile file' option will force Bash to read and execute commands from file instead of `~/.bashrc'.

So, typically, your `~/.bash_profile' contains the line
if [ -f ~/.bashrc ]; then . ~/.bashrc; fi
after (or before) any login-specific initializations.

Invoked non-interactively

When Bash is started non-interactively, to run a shell script, for example, it looks for the variable BASH_ENV in the environment, expands its value if it appears there, and uses the expanded value as the name of a file to read and execute. Bash behaves as if the following command were executed:
if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
but the value of the PATH variable is not used to search for the file name.

As noted above, if a non-interactive shell is invoked with the `--login' option, Bash attempts to read and execute commands from the login shell startup files.

Invoked with name sh

If Bash is invoked with the name sh, it tries to mimic the startup behavior of historical versions of sh as closely as possible, while conforming to the POSIX standard as well.

When invoked as an interactive login shell, or as a non-interactive shell with the `--login' option, it first attempts to read and execute commands from `/etc/profile' and `~/.profile', in that order. The `--noprofile' option may be used to inhibit this behavior. When invoked as an interactive shell with the name sh, Bash looks for the variable ENV, expands its value if it is defined, and uses the expanded value as the name of a file to read and execute. Since a shell invoked as sh does not attempt to read and execute commands from any other startup files, the `--rcfile' option has no effect. A non-interactive shell invoked with the name sh does not attempt to read any other startup files.

When invoked as sh, Bash enters POSIX mode after the startup files are read.

Invoked in POSIX mode

When Bash is started in POSIX mode, as with the `--posix' command line option, it follows the POSIX standard for startup files. In this mode, interactive shells expand the ENV variable and commands are read and executed from the file whose name is the expanded value. No other startup files are read.

Invoked by remote shell daemon

Bash attempts to determine when it is being run by the remote shell daemon, usually rshd. If Bash determines it is being run by rshd, it reads and executes commands from `~/.bashrc', if that file exists and is readable. It will not do this if invoked as sh. The `--norc' option may be used to inhibit this behavior, and the `--rcfile' option may be used to force another file to be read, but rshd does not generally invoke the shell with those options or allow them to be specified.

Invoked with unequal effective and real UID/GIDs

If Bash is started with the effective user (group) id not equal to the real user (group) id, and the -p option is not supplied, no startup files are read, shell functions are not inherited from the environment, the SHELLOPTS variable, if it appears in the environment, is ignored, and the effective user id is set to the real user id. If the -p option is supplied at invocation, the startup behavior is the same, but the effective user id is not reset.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3 Interactive Shells

6.3.1 What is an Interactive Shell? | What determines whether a shell is Interactive.
6.3.2 Is this Shell Interactive? | How to tell if a shell is interactive.
6.3.3 Interactive Shell Behavior | What changes in a interactive shell?

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3.1 What is an Interactive Shell?

An interactive shell is one started without non-option arguments, unless `-s' is specified, without specifiying the `-c' option, and whose input and output are both connected to terminals (as determined by isatty(3)), or one started with the `-i' option.

An interactive shell generally reads from and writes to a user's terminal.

The `-s' invocation option may be used to set the positional parameters when an interactive shell is started.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3.2 Is this Shell Interactive?

To determine within a startup script whether or not Bash is running interactively, test the value of the `-' special parameter. It contains i when the shell is interactive. For example:

case "$-" in
*i*)	echo This shell is interactive ;;
*)	echo This shell is not interactive ;;
esac

Alternatively, startup scripts may examine the variable PS1; it is unset in non-interactive shells, and set in interactive shells. Thus:

if [ -z "$PS1" ]; then
        echo This shell is not interactive
else
        echo This shell is interactive
fi

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3.3 Interactive Shell Behavior

When the shell is running interactively, it changes its behavior in several ways.

  1. Startup files are read and executed as described in 6.2 Bash Startup Files.

  2. Job Control (see section 7. Job Control) is enabled by default. When job control is in effect, Bash ignores the keyboard-generated job control signals SIGTTIN, SIGTTOU, and SIGTSTP.

  3. Bash expands and displays PS1 before reading the first line of a command, and expands and displays PS2 before reading the second and subsequent lines of a multi-line command.

  4. Bash executes the value of the PROMPT_COMMAND variable as a command before printing the primary prompt, $PS1 (see section 5.2 Bash Variables).

  5. Readline (see section 8. Command Line Editing) is used to read commands from the user's terminal.

  6. Bash inspects the value of the ignoreeof option to set -o instead of exiting immediately when it receives an EOF on its standard input when reading a command (see section 4.3 The Set Builtin).

  7. Command history (see section 9.1 Bash History Facilities) and history expansion (see section 9.3 History Expansion) are enabled by default. Bash will save the command history to the file named by $HISTFILE when an interactive shell exits.

  8. Alias expansion (see section 6.6 Aliases) is performed by default.

  9. In the absence of any traps, Bash ignores SIGTERM (see section 3.7.6 Signals).

  10. In the absence of any traps, SIGINT is caught and handled ((see section 3.7.6 Signals). SIGINT will interrupt some shell builtins.

  11. An interactive login shell sends a SIGHUP to all jobs on exit if the hupoxexit shell option has been enabled (see section 3.7.6 Signals).

  12. The `-n' invocation option is ignored, and `set -n' has no effect (see section 4.3 The Set Builtin).

  13. Bash will check for mail periodically, depending on the values of the MAIL, MAILPATH, and MAILCHECK shell variables (see section 5.2 Bash Variables).

  14. Expansion errors due to references to unbound shell variables after `set -u' has been enabled will not cause the shell to exit (see section 4.3 The Set Builtin).

  15. The shell will not exit on expansion errors caused by var being unset or null in ${var:?word} expansions (see section 3.5.3 Shell Parameter Expansion).

  16. Redirection errors encountered by shell builtins will not cause the shell to exit.

  17. When running in POSIX mode, a special builtin returning an error status will not cause the shell to exit (see section 6.11 Bash POSIX Mode).
  18. A failed exec will not cause the shell to exit (see section 4.1 Bourne Shell Builtins).

  19. Parser syntax errors will not cause the shell to exit.

  20. Simple spelling correction for directory arguments to the cd builtin is enabled by default (see the description of the cdspell option to the shopt builtin in 4.2 Bash Builtin Commands).

  21. The shell will check the value of the TMOUT variable and exit if a command is not read within the specified number of seconds after printing $PS1 (see section 5.2 Bash Variables).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4 Bash Conditional Expressions

Conditional expressions are used by the [[ compound command and the test and [ builtin commands.

Expressions may be unary or binary. Unary expressions are often used to examine the status of a file. There are string operators and numeric comparison operators as well. If the file argument to one of the primaries is of the form `/dev/fd/N', then file descriptor N is checked. If the file argument to one of the primaries is one of `/dev/stdin', `/dev/stdout', or `/dev/stderr', file descriptor 0, 1, or 2, respectively, is checked.

-a file
True if file exists.

-b file
True if file exists and is a block special file.

-c file
True if file exists and is a character special file.

-d file
True if file exists and is a directory.

-e file
True if file exists.

-f file
True if file exists and is a regular file.

-g file
True if file exists and its set-group-id bit is set.

-h file
True if file exists and is a symbolic link.

-k file
True if file exists and its "sticky" bit is set.

-p file
True if file exists and is a named pipe (FIFO).

-r file
True if file exists and is readable.

-s file
True if file exists and has a size greater than zero.

-t fd
True if file descriptor fd is open and refers to a terminal.

-u file
True if file exists and its set-user-id bit is set.

-w file
True if file exists and is writable.

-x file
True if file exists and is executable.

-O file
True if file exists and is owned by the effective user id.

-G file
True if file exists and is owned by the effective group id.

-L file
True if file exists and is a symbolic link.

-S file
True if file exists and is a socket.

-N file
True if file exists and has been modified since it was last read.

file1 -nt file2
True if file1 is newer (according to modification date) than file2.

file1 -ot file2
True if file1 is older than file2.

file1 -ef file2
True if file1 and file2 have the same device and inode numbers.

-o optname
True if shell option optname is enabled. The list of options appears in the description of the `-o' option to the set builtin (see section 4.3 The Set Builtin).

-z string
True if the length of string is zero.

-n string
string
True if the length of string is non-zero.

string1 == string2
True if the strings are equal. `=' may be used in place of `=='.

string1 != string2
True if the strings are not equal.

string1 < string2
True if string1 sorts before string2 lexicographically in the current locale.

string1 > string2
True if string1 sorts after string2 lexicographically in the current locale.

arg1 OP arg2
OP is one of `-eq', `-ne', `-lt', `-le', `-gt', or `-ge'. These arithmetic binary operators return true if arg1 is equal to, not equal to, less than, less than or equal to, greater than, or greater than or equal to arg2, respectively. Arg1 and arg2 may be positive or negative integers.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.5 Shell Arithmetic

The shell allows arithmetic expressions to be evaluated, as one of the shell expansions or by the let builtin.

Evaluation is done in long integers with no check for overflow, though division by 0 is trapped and flagged as an error. The operators and their precedence and associativity are the same as in the C language. The following list of operators is grouped into levels of equal-precedence operators. The levels are listed in order of decreasing precedence.

id++ id--
variable post-increment and post-decrement

++id --id
variable pre-increment and pre-decrement

- +
unary minus and plus

! ~
logical and bitwise negation

**
exponentiation

* / %
multiplication, division, remainder

+ -
addition, subtraction

<< >>
left and right bitwise shifts

<= >= < >
comparison

== !=
equality and inequality

&
bitwise AND

^
bitwise exclusive OR

|
bitwise OR

&&
logical AND

||
logical OR

expr ? expr : expr
conditional evaluation

= *= /= %= += -= <<= >>= &= ^= |=
assignment

expr1 , expr2
comma

Shell variables are allowed as operands; parameter expansion is performed before the expression is evaluated. Within an expression, shell variables may also be referenced by name without using the parameter expansion syntax. The value of a variable is evaluated as an arithmetic expression when it is referenced. A shell variable need not have its integer attribute turned on to be used in an expression.

Constants with a leading 0 are interpreted as octal numbers. A leading `0x' or `0X' denotes hexadecimal. Otherwise, numbers take the form [base#]n, where base is a decimal number between 2 and 64 representing the arithmetic base, and n is a number in that base. If base# is omitted, then base 10 is used. The digits greater than 9 are represented by the lowercase letters, the uppercase letters, `@', and `_', in that order. If base is less than or equal to 36, lowercase and uppercase letters may be used interchangably to represent numbers between 10 and 35.

Operators are evaluated in order of precedence. Sub-expressions in parentheses are evaluated first and may override the precedence rules above.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.6 Aliases

Aliases allow a string to be substituted for a word when it is used as the first word of a simple command. The shell maintains a list of aliases that may be set and unset with the alias and unalias builtin commands.

The first word of each simple command, if unquoted, is checked to see if it has an alias. If so, that word is replaced by the text of the alias. The alias name and the replacement text may contain any valid shell input, including shell metacharacters, with the exception that the alias name may not contain `='. The first word of the replacement text is tested for aliases, but a word that is identical to an alias being expanded is not expanded a second time. This means that one may alias ls to "ls -F", for instance, and Bash does not try to recursively expand the replacement text. If the last character of the alias value is a space or tab character, then the next command word following the alias is also checked for alias expansion.

Aliases are created and listed with the alias command, and removed with the unalias command.

There is no mechanism for using arguments in the replacement text, as in csh. If arguments are needed, a shell function should be used (see section 3.3 Shell Functions).

Aliases are not expanded when the shell is not interactive, unless the expand_aliases shell option is set using shopt (see section 4.2 Bash Builtin Commands).

The rules concerning the definition and use of aliases are somewhat confusing. Bash always reads at least one complete line of input before executing any of the commands on that line. Aliases are expanded when a command is read, not when it is executed. Therefore, an alias definition appearing on the same line as another command does not take effect until the next line of input is read. The commands following the alias definition on that line are not affected by the new alias. This behavior is also an issue when functions are executed. Aliases are expanded when a function definition is read, not when the function is executed, because a function definition is itself a compound command. As a consequence, aliases defined in a function are not available until after that function is executed. To be safe, always put alias definitions on a separate line, and do not use alias in compound commands.

For almost every purpose, shell functions are preferred over aliases.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.7 Arrays

Bash provides one-dimensional array variables. Any variable may be used as an array; the declare builtin will explicitly declare an array. There is no maximum limit on the size of an array, nor any requirement that members be indexed or assigned contiguously. Arrays are zero-based.

An array is created automatically if any variable is assigned to using the syntax
name[subscript]=value

The subscript is treated as an arithmetic expression that must evaluate to a number greater than or equal to zero. To explicitly declare an array, use
declare -a name
The syntax
declare -a name[subscript]
is also accepted; the subscript is ignored. Attributes may be specified for an array variable using the declare and readonly builtins. Each attribute applies to all members of an array.

Arrays are assigned to using compound assignments of the form
name=(value1 ... valuen)
where each value is of the form [[subscript]=]string. If the optional subscript is supplied, that index is assigned to; otherwise the index of the element assigned is the last index assigned to by the statement plus one. Indexing starts at zero. This syntax is also accepted by the declare builtin. Individual array elements may be assigned to using the name[subscript]=value syntax introduced above.

Any element of an array may be referenced using ${name[subscript]}. The braces are required to avoid conflicts with the shell's filename expansion operators. If the subscript is `@' or `*', the word expands to all members of the array name. These subscripts differ only when the word appears within double quotes. If the word is double-quoted, ${name[*]} expands to a single word with the value of each array member separated by the first character of the IFS variable, and ${name[@]} expands each element of name to a separate word. When there are no array members, ${name[@]} expands to nothing. This is analogous to the expansion of the special parameters `@' and `*'. ${#name[subscript]} expands to the length of ${name[subscript]}. If subscript is `@' or `*', the expansion is the number of elements in the array. Referencing an array variable without a subscript is equivalent to referencing element zero.

The unset builtin is used to destroy arrays. unset name[subscript] destroys the array element at index subscript. unset name, where name is an array, removes the entire array. A subscript of `*' or `@' also removes the entire array.

The declare, local, and readonly builtins each accept a `-a' option to specify an array. The read builtin accepts a `-a' option to assign a list of words read from the standard input to an array, and can read values from the standard input into individual array elements. The set and declare builtins display array values in a way that allows them to be reused as input.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.8 The Directory Stack

6.8.1 Directory Stack Builtins Bash builtin commands to manipulate the directory stack.

The directory stack is a list of recently-visited directories. The pushd builtin adds directories to the stack as it changes the current directory, and the popd builtin removes specified directories from the stack and changes the current directory to the directory removed. The dirs builtin displays the contents of the directory stack.

The contents of the directory stack are also visible as the value of the DIRSTACK shell variable.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.8.1 Directory Stack Builtins

dirs
dirs [+N | -N] [-clpv]
Display the list of currently remembered directories. Directories are added to the list with the pushd command; the popd command removes directories from the list.
+N
Displays the Nth directory (counting from the left of the list printed by dirs when invoked without options), starting with zero.
-N
Displays the Nth directory (counting from the right of the list printed by dirs when invoked without options), starting with zero.
-c
Clears the directory stack by deleting all of the elements.
-l
Produces a longer listing; the default listing format uses a tilde to denote the home directory.
-p
Causes dirs to print the directory stack with one entry per line.
-v
Causes dirs to print the directory stack with one entry per line, prefixing each entry with its index in the stack.

popd
popd [+N | -N] [-n]

Remove the top entry from the directory stack, and cd to the new top directory. When no arguments are given, popd removes the top directory from the stack and performs a cd to the new top directory. The elements are numbered from 0 starting at the first directory listed with dirs; i.e., popd is equivalent to popd +0.

+N
Removes the Nth directory (counting from the left of the list printed by dirs), starting with zero.
-N
Removes the Nth directory (counting from the right of the list printed by dirs), starting with zero.
-n
Suppresses the normal change of directory when removing directories from the stack, so that only the stack is manipulated.

pushd
pushd [dir | +N | -N] [-n]

Save the current directory on the top of the directory stack and then cd to dir. With no arguments, pushd exchanges the top two directories.

+N
Brings the Nth directory (counting from the left of the list printed by dirs, starting with zero) to the top of the list by rotating the stack.
-N
Brings the Nth directory (counting from the right of the list printed by dirs, starting with zero) to the top of the list by rotating the stack.
-n
Suppresses the normal change of directory when adding directories to the stack, so that only the stack is manipulated.
dir
Makes the current working directory be the top of the stack, and then executes the equivalent of `cd dir'. cds to dir.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.9 Controlling the Prompt

The value of the variable PROMPT_COMMAND is examined just before Bash prints each primary prompt. If PROMPT_COMMAND is set and has a non-null value, then the value is executed just as if it had been typed on the command line.

In addition, the following table describes the special characters which can appear in the prompt variables:

\a
A bell character.
\d
The date, in "Weekday Month Date" format (e.g., "Tue May 26").
\e
An escape character.
\h
The hostname, up to the first `.'.
\H
The hostname.
\j
The number of jobs currently managed by the shell.
\l
The basename of the shell's terminal device name.
\n
A newline.
\r
A carriage return.
\s
The name of the shell, the basename of $0 (the portion following the final slash).
\t
The time, in 24-hour HH:MM:SS format.
\T
The time, in 12-hour HH:MM:SS format.
\@
The time, in 12-hour am/pm format.
\A
The time, in 24-hour HH:MM format.
\u
The username of the current user.
\v
The version of Bash (e.g., 2.00)
\V
The release of Bash, version + patchlevel (e.g., 2.00.0)
\w
The current working directory.
\W
The basename of $PWD.
\!
The history number of this command.
\#
The command number of this command.
\$
If the effective uid is 0, #, otherwise $.
\nnn
The character whose ASCII code is the octal value nnn.
\\
A backslash.
\[
Begin a sequence of non-printing characters. This could be used to embed a terminal control sequence into the prompt.
\]
End a sequence of non-printing characters.

The command number and the history number are usually different: the history number of a command is its position in the history list, which may include commands restored from the history file (see section 9.1 Bash History Facilities), while the command number is the position in the sequence of commands executed during the current shell session.

After the string is decoded, it is expanded via parameter expansion, command substitution, arithmetic expansion, and quote removal, subject to the value of the promptvars shell option (see section 4.2 Bash Builtin Commands).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.10 The Restricted Shell

If Bash is started with the name rbash, or the `--restricted' option is supplied at invocation, the shell becomes restricted. A restricted shell is used to set up an environment more controlled than the standard shell. A restricted shell behaves identically to bash with the exception that the following are disallowed:

  • Changing directories with the cd builtin.
  • Setting or unsetting the values of the SHELL, PATH, ENV, or BASH_ENV variables.
  • Specifying command names containing slashes.
  • Specifying a filename containing a slash as an argument to the . builtin command.
  • Specifying a filename containing a slash as an argument to the `-p' option to the hash builtin command.
  • Importing function definitions from the shell environment at startup.
  • Parsing the value of SHELLOPTS from the shell environment at startup.
  • Redirecting output using the `>', `>|', `<>', `>&', `&>', and `>>' redirection operators.
  • Using the exec builtin to replace the shell with another command.
  • Adding or deleting builtin commands with the `-f' and `-d' options to the enable builtin.
  • Specifying the `-p' option to the command builtin.
  • Turning off restricted mode with `set +r' or `set +o restricted'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.11 Bash POSIX Mode

Starting Bash with the `--posix' command-line option or executing `set -o posix' while Bash is running will cause Bash to conform more closely to the POSIX 1003.2 standard by changing the behavior to match that specified by POSIX in areas where the Bash default differs.

The following list is what's changed when `POSIX mode' is in effect:

  1. When a command in the hash table no longer exists, Bash will re-search $PATH to find the new location. This is also available with `shopt -s checkhash'.

  2. The message printed by the job control code and builtins when a job exits with a non-zero status is `Done(status)'.

  3. The message printed by the job control code and builtins when a job is stopped is `Stopped(signame)', where signame is, for example, SIGTSTP.

  4. Reserved words may not be aliased.

  5. The POSIX 1003.2 PS1 and PS2 expansions of `!' to the history number and `!!' to `!' are enabled, and parameter expansion is performed on the values of PS1 and PS2 regardless of the setting of the promptvars option.

  6. Interactive comments are enabled by default. (Bash has them on by default anyway.)

  7. The POSIX 1003.2 startup files are executed ($ENV) rather than the normal Bash files.

  8. Tilde expansion is only performed on assignments preceding a command name, rather than on all assignment statements on the line.

  9. The default history file is `~/.sh_history' (this is the default value of $HISTFILE).

  10. The output of `kill -l' prints all the signal names on a single line, separated by spaces.

  11. Non-interactive shells exit if filename in . filename is not found.

  12. Non-interactive shells exit if a syntax error in an arithmetic expansion results in an invalid expression.

  13. Redirection operators do not perform filename expansion on the word in the redirection unless the shell is interactive.

  14. Redirection operators do not perform word splitting on the word in the redirection.

  15. Function names must be valid shell names. That is, they may not contain characters other than letters, digits, and underscores, and may not start with a digit. Declaring a function with an invalid name causes a fatal syntax error in non-interactive shells.

  16. POSIX 1003.2 `special' builtins are found before shell functions during command lookup.

  17. If a POSIX 1003.2 special builtin returns an error status, a non-interactive shell exits. The fatal errors are those listed in the POSIX.2 standard, and include things like passing incorrect options, redirection errors, variable assignment errors for assignments preceding the command name, and so on.

  18. If the cd builtin finds a directory to change to using $CDPATH, the value it assigns to the PWD variable does not contain any symbolic links, as if `cd -P' had been executed.

  19. If CDPATH is set, the cd builtin will not implicitly append the current directory to it. This means that cd will fail if no valid directory name can be constructed from any of the entries in $CDPATH, even if the a directory with the same name as the name given as an argument to cd exists in the current directory.

  20. A non-interactive shell exits with an error status if a variable assignment error occurs when no command name follows the assignment statements. A variable assignment error occurs, for example, when trying to assign a value to a readonly variable.

  21. A non-interactive shell exits with an error status if the iteration variable in a for statement or the selection variable in a select statement is a readonly variable.

  22. Process substitution is not available.

  23. Assignment statements preceding POSIX 1003.2 special builtins persist in the shell environment after the builtin completes.

  24. Assignment statements preceding shell function calls persist in the shell environment after the function returns, as if a POSIX special builtin command had been executed.

  25. The export and readonly builtin commands display their output in the format required by POSIX 1003.2.

  26. The trap builtin displays signal names without the leading SIG.

  27. The . and source builtins do not search the current directory for the filename argument if it is not found by searching PATH.

  28. Subshells spawned to execute command substitutions inherit the value of the `-e' option from the parent shell. When not in POSIX mode, Bash clears the `-e' option in such subshells.

  29. Alias expansion is always enabled, even in non-interactive shells.

  30. When the set builtin is invoked without options, it does not display shell function names and definitions.

  31. When the set builtin is invoked without options, it displays variable values without quotes, unless they contain shell metacharacters, even if the result contains nonprinting characters.

There is other POSIX 1003.2 behavior that Bash does not implement. Specifically:

  1. Assignment statements affect the execution environment of all builtins, not just special ones.

  2. When a subshell is created to execute a shell script with execute permission, but without a leading `#!', Bash sets $0 to the full pathname of the script as found by searching $PATH, rather than the command as typed by the user.

  3. When using `.' to source a shell script found in $PATH, bash checks execute permission bits rather than read permission bits, just as if it were searching for a command.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. Job Control

This chapter discusses what job control is, how it works, and how Bash allows you to access its facilities.

7.1 Job Control Basics | How job control works.
7.2 Job Control Builtins | Bash builtin commands used to interact with job control.
7.3 Job Control Variables | Variables Bash uses to customize job control.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1 Job Control Basics

Job control refers to the ability to selectively stop (suspend) the execution of processes and continue (resume) their execution at a later point. A user typically employs this facility via an interactive interface supplied jointly by the system's terminal driver and Bash.

The shell associates a job with each pipeline. It keeps a table of currently executing jobs, which may be listed with the jobs command. When Bash starts a job asynchronously, it prints a line that looks like:
[1] 25647
indicating that this job is job number 1 and that the process ID of the last process in the pipeline associated with this job is 25647. All of the processes in a single pipeline are members of the same job. Bash uses the job abstraction as the basis for job control.

To facilitate the implementation of the user interface to job control, the operating system maintains the notion of a current terminal process group ID. Members of this process group (processes whose process group ID is equal to the current terminal process group ID) receive keyboard-generated signals such as SIGINT. These processes are said to be in the foreground. Background processes are those whose process group ID differs from the terminal's; such processes are immune to keyboard-generated signals. Only foreground processes are allowed to read from or write to the terminal. Background processes which attempt to read from (write to) the terminal are sent a SIGTTIN (SIGTTOU) signal by the terminal driver, which, unless caught, suspends the process.

If the operating system on which Bash is running supports job control, Bash contains facilities to use it. Typing the suspend character (typically `^Z', Control-Z) while a process is running causes that process to be stopped and returns control to Bash. Typing the delayed suspend character (typically `^Y', Control-Y) causes the process to be stopped when it attempts to read input from the terminal, and control to be returned to Bash. The user then manipulates the state of this job, using the bg command to continue it in the background, the fg command to continue it in the foreground, or the kill command to kill it. A `^Z' takes effect immediately, and has the additional side effect of causing pending output and typeahead to be discarded.

There are a number of ways to refer to a job in the shell. The character `%' introduces a job name.

Job number n may be referred to as `%n'. The symbols `%%' and `%+' refer to the shell's notion of the current job, which is the last job stopped while it was in the foreground or started in the background. The previous job may be referenced using `%-'. In output pertaining to jobs (e.g., the output of the jobs command), the current job is always flagged with a `+', and the previous job with a `-'.

A job may also be referred to using a prefix of the name used to start it, or using a substring that appears in its command line. For example, `%ce' refers to a stopped ce job. Using `%?ce', on the other hand, refers to any job containing the string `ce' in its command line. If the prefix or substring matches more than one job, Bash reports an error.

Simply naming a job can be used to bring it into the foreground: `%1' is a synonym for `fg %1', bringing job 1 from the background into the foreground. Similarly, `%1 &' resumes job 1 in the background, equivalent to `bg %1'

The shell learns immediately whenever a job changes state. Normally, Bash waits until it is about to print a prompt before reporting changes in a job's status so as to not interrupt any other output. If the `-b' option to the set builtin is enabled, Bash reports such changes immediately (see section 4.3 The Set Builtin). Any trap on SIGCHLD is executed for each child process that exits.

If an attempt to exit Bash is while jobs are stopped, the shell prints a message warning that there are stopped jobs. The jobs command may then be used to inspect their status. If a second attempt to exit is made without an intervening command, Bash does not print another warning, and the stopped jobs are terminated.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2 Job Control Builtins

bg
bg [jobspec]
Resume the suspended job jobspec in the background, as if it had been started with `&'. If jobspec is not supplied, the current job is used. The return status is zero unless it is run when job control is not enabled, or, when run with job control enabled, if jobspec was not found or jobspec specifies a job that was started without job control.

fg
fg [jobspec]
Resume the job jobspec in the foreground and make it the current job. If jobspec is not supplied, the current job is used. The return status is that of the command placed into the foreground, or non-zero if run when job control is disabled or, when run with job control enabled, jobspec does not specify a valid job or jobspec specifies a job that was started without job control.

jobs
jobs [-lnprs] [jobspec]
jobs -x command [arguments]

The first form lists the active jobs. The options have the following meanings:

-l
List process IDs in addition to the normal information.

-n
Display information only about jobs that have changed status since the user was last notified of their status.

-p
List only the process ID of the job's process group leader.

-r
Restrict output to running jobs.

-s
Restrict output to stopped jobs.

If jobspec is given, output is restricted to information about that job. If jobspec is not supplied, the status of all jobs is listed.

If the `-x' option is supplied, jobs replaces any jobspec found in command or arguments with the corresponding process group ID, and executes command, passing it arguments, returning its exit status.

kill
kill [-s sigspec] [-n signum] [-sigspec] jobspec or pid
kill -l [exit_status]
Send a signal specified by sigspec or signum to the process named by job specification jobspec or process ID pid. sigspec is either a signal name such as SIGINT (with or without the SIG prefix) or a signal number; signum is a signal number. If sigspec and signum are not present, SIGTERM is used. The `-l' option lists the signal names. If any arguments are supplied when `-l' is given, the names of the signals corresponding to the arguments are listed, and the return status is zero. exit_status is a number specifying a signal number or the exit status of a process terminated by a signal. The return status is zero if at least one signal was successfully sent, or non-zero if an error occurs or an invalid option is encountered.

wait
wait [jobspec or pid]
Wait until the child process specified by process ID pid or job specification jobspec exits and return the exit status of the last command waited for. If a job spec is given, all processes in the job are waited for. If no arguments are given, all currently active child processes are waited for, and the return status is zero. If neither jobspec nor pid specifies an active child process of the shell, the return status is 127.

disown
disown [-ar] [-h] [jobspec ...]
Without options, each jobspec is removed from the table of active jobs. If the `-h' option is given, the job is not removed from the table, but is marked so that SIGHUP is not sent to the job if the shell receives a SIGHUP. If jobspec is not present, and neither the `-a' nor `-r' option is supplied, the current job is used. If no jobspec is supplied, the `-a' option means to remove or mark all jobs; the `-r' option without a jobspec argument restricts operation to running jobs.

suspend
suspend [-f]
Suspend the execution of this shell until it receives a SIGCONT signal. The `-f' option means to suspend even if the shell is a login shell.

When job control is not active, the kill and wait builtins do not accept jobspec arguments. They must be supplied process IDs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3 Job Control Variables

auto_resume
This variable controls how the shell interacts with the user and job control. If this variable exists then single word simple commands without redirections are treated as candidates for resumption of an existing job. There is no ambiguity allowed; if there is more than one job beginning with the string typed, then the most recently accessed job will be selected. The name of a stopped job, in this context, is the command line used to start it. If this variable is set to the value `exact', the string supplied must match the name of a stopped job exactly; if set to `substring', the string supplied needs to match a substring of the name of a stopped job. The `substring' value provides functionality analogous to the `%?' job ID (see section 7.1 Job Control Basics). If set to any other value, the supplied string must be a prefix of a stopped job's name; this provides functionality analogous to the `%' job ID.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. Command Line Editing

This chapter describes the basic features of the GNU command line editing interface. Command line editing is provided by the Readline library, which is used by several different programs, including Bash.

8.1 Introduction to Line Editing | Notation used in this text.
8.2 Readline Interaction | The minimum set of commands for editing a line.
8.3 Readline Init File | Customizing Readline from a user's view.
8.4 Bindable Readline Commands | A description of most of the Readline commands available for binding
8.5 Readline vi Mode | A short description of how to make Readline behave like the vi editor.
8.6 Programmable Completion | How to specify the possible completions for a specific command.
8.7 Programmable Completion Builtins | Builtin commands to specify how to complete arguments for a particular command.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1 Introduction to Line Editing

The following paragraphs describe the notation used to represent keystrokes.

The text C-k is read as `Control-K' and describes the character produced when the k key is pressed while the Control key is depressed.

The text M-k is read as `Meta-K' and describes the character produced when the Meta key (if you have one) is depressed, and the k key is pressed. The Meta key is labeled ALT on many keyboards. On keyboards with two keys labeled ALT (usually to either side of the space bar), the ALT on the left side is generally set to work as a Meta key. The ALT key on the right may also be configured to work as a Meta key or may be configured as some other modifier, such as a Compose key for typing accented characters.

If you do not have a Meta or ALT key, or another key working as a Meta key, the identical keystroke can be generated by typing ESC first, and then typing k. Either process is known as metafying the k key.

The text M-C-k is read as `Meta-Control-k' and describes the character produced by metafying C-k.

In addition, several keys have their own names. Specifically, DEL, ESC, LFD, SPC, RET, and TAB all stand for themselves when seen in this text, or in an init file (see section 8.3 Readline Init File). If your keyboard lacks a LFD key, typing C-j will produce the desired character. The RET key may be labeled Return or Enter on some keyboards.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2 Readline Interaction

Often during an interactive session you type in a long line of text, only to notice that the first word on the line is misspelled. The Readline library gives you a set of commands for manipulating the text as you type it in, allowing you to just fix your typo, and not forcing you to retype the majority of the line. Using these editing commands, you move the cursor to the place that needs correction, and delete or insert the text of the corrections. Then, when you are satisfied with the line, you simply press RET. You do not have to be at the end of the line to press RET; the entire line is accepted regardless of the location of the cursor within the line.

8.2.1 Readline Bare Essentials | The least you need to know about Readline.
8.2.2 Readline Movement Commands | Moving about the input line.
8.2.3 Readline Killing Commands | How to delete text, and how to get it back!
8.2.4 Readline Arguments | Giving numeric arguments to commands.
8.2.5 Searching for Commands in the History | Searching through previous lines.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.1 Readline Bare Essentials

In order to enter characters into the line, simply type them. The typed character appears where the cursor was, and then the cursor moves one space to the right. If you mistype a character, you can use your erase character to back up and delete the mistyped character.

Sometimes you may mistype a character, and not notice the error until you have typed several other characters. In that case, you can type C-b to move the cursor to the left, and then correct your mistake. Afterwards, you can move the cursor to the right with C-f.

When you add text in the middle of a line, you will notice that characters to the right of the cursor are `pushed over' to make room for the text that you have inserted. Likewise, when you delete text behind the cursor, characters to the right of the cursor are `pulled back' to fill in the blank space created by the removal of the text. A list of the bare essentials for editing the text of an input line follows.

C-b
Move back one character.
C-f
Move forward one character.
DEL or Backspace
Delete the character to the left of the cursor.
C-d
Delete the character underneath the cursor.
Printing characters
Insert the character into the line at the cursor.
C-_ or C-x C-u
Undo the last editing command. You can undo all the way back to an empty line.

(Depending on your configuration, the Backspace key be set to delete the character to the left of the cursor and the DEL key set to delete the character underneath the cursor, like C-d, rather than the character to the left of the cursor.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.2 Readline Movement Commands

The above table describes the most basic keystrokes that you need in order to do editing of the input line. For your convenience, many other commands have been added in addition to C-b, C-f, C-d, and DEL. Here are some commands for moving more rapidly about the line.

C-a
Move to the start of the line.
C-e
Move to the end of the line.
M-f
Move forward a word, where a word is composed of letters and digits.
M-b
Move backward a word.
C-l
Clear the screen, reprinting the current line at the top.

Notice how C-f moves forward a character, while M-f moves forward a word. It is a loose convention that control keystrokes operate on characters while meta keystrokes operate on words.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.3 Readline Killing Commands

Killing text means to delete the text from the line, but to save it away for later use, usually by yanking (re-inserting) it back into the line. (`Cut' and `paste' are more recent jargon for `kill' and `yank'.)

If the description for a command says that it `kills' text, then you can be sure that you can get the text back in a different (or the same) place later.

When you use a kill command, the text is saved in a kill-ring. Any number of consecutive kills save all of the killed text together, so that when you yank it back, you get it all. The kill ring is not line specific; the text that you killed on a previously typed line is available to be yanked back later, when you are typing another line.

Here is the list of commands for killing text.

C-k
Kill the text from the current cursor position to the end of the line.

M-d
Kill from the cursor to the end of the current word, or, if between words, to the end of the next word. Word boundaries are the same as those used by M-f.

M-DEL
Kill from the cursor the start of the current word, or, if between words, to the start of the previous word. Word boundaries are the same as those used by M-b.

C-w
Kill from the cursor to the previous whitespace. This is different than M-DEL because the word boundaries differ.

Here is how to yank the text back into the line. Yanking means to copy the most-recently-killed text from the kill buffer.

C-y
Yank the most recently killed text back into the buffer at the cursor.

M-y
Rotate the kill-ring, and yank the new top. You can only do this if the prior command is C-y or M-y.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.4 Readline Arguments

You can pass numeric arguments to Readline commands. Sometimes the argument acts as a repeat count, other times it is the sign of the argument that is significant. If you pass a negative argument to a command which normally acts in a forward direction, that command will act in a backward direction. For example, to kill text back to the start of the line, you might type `M-- C-k'.

The general way to pass numeric arguments to a command is to type meta digits before the command. If the first `digit' typed is a minus sign (`-'), then the sign of the argument will be negative. Once you have typed one meta digit to get the argument started, you can type the remainder of the digits, and then the command. For example, to give the C-d command an argument of 10, you could type `M-1 0 C-d', which will delete the next ten characters on the input line.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.5 Searching for Commands in the History

Readline provides commands for searching through the command history (see section 9.1 Bash History Facilities) for lines containing a specified string. There are two search modes: incremental and non-incremental.

Incremental searches begin before the user has finished typing the search string. As each character of the search string is typed, Readline displays the next entry from the history matching the string typed so far. An incremental search requires only as many characters as needed to find the desired history entry. To search backward in the history for a particular string, type C-r. Typing C-s searches forward through the history. The characters present in the value of the isearch-terminators variable are used to terminate an incremental search. If that variable has not been assigned a value, the ESC and C-J characters will terminate an incremental search. C-g will abort an incremental search and restore the original line. When the search is terminated, the history entry containing the search string becomes the current line.

To find other matching entries in the history list, type C-r or C-s as appropriate. This will search backward or forward in the history for the next entry matching the search string typed so far. Any other key sequence bound to a Readline command will terminate the search and execute that command. For instance, a RET will terminate the search and accept the line, thereby executing the command from the history list. A movement command will terminate the search, make the last line found the current line, and begin editing.

Readline remembers the last incremental search string. If two C-rs are typed without any intervening characters defining a new search string, any remembered search string is used.

Non-incremental searches read the entire search string before starting to search for matching history lines. The search string may be typed by the user or be part of the contents of the current line.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.3 Readline Init File

Although the Readline library comes with a set of Emacs-like keybindings installed by default, it is possible to use a different set of keybindings. Any user can customize programs that use Readline by putting commands in an inputrc file, conventionally in his home directory. The name of this file is taken from the value of the shell variable INPUTRC. If that variable is unset, the default is `~/.inputrc'.

When a program which uses the Readline library starts up, the init file is read, and the key bindings are set.

In addition, the C-x C-r command re-reads this init file, thus incorporating any changes that you might have made to it.

8.3.1 Readline Init File Syntax Syntax for the commands in the inputrc file.

8.3.2 Conditional Init Constructs Conditional key bindings in the inputrc file.

8.3.3 Sample Init File An example inputrc file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.3.1 Readline Init File Syntax

There are only a few basic constructs allowed in the Readline init file. Blank lines are ignored. Lines beginning with a `#' are comments. Lines beginning with a `$' indicate conditional constructs (see section 8.3.2 Conditional Init Constructs). Other lines denote variable settings and key bindings.

Variable Settings
You can modify the run-time behavior of Readline by altering the values of variables in Readline using the set command within the init file. The syntax is simple:

set variable value

Here, for example, is how to change from the default Emacs-like key binding to use vi line editing commands:

set editing-mode vi

Variable names and values, where appropriate, are recognized without regard to case.

The bind -V command lists the current Readline variable names and values. See section 4.2 Bash Builtin Commands.

A great deal of run-time behavior is changeable with the following variables.

bell-style
Controls what happens when Readline wants to ring the terminal bell. If set to `none', Readline never rings the bell. If set to `visible', Readline uses a visible bell if one is available. If set to `audible' (the default), Readline attempts to ring the terminal's bell.

comment-begin
The string to insert at the beginning of the line when the insert-comment command is executed. The default value is "#".

completion-ignore-case
If set to `on', Readline performs filename matching and completion in a case-insensitive fashion. The default value is `off'.

completion-query-items
The number of possible completions that determines when the user is asked whether he wants to see the list of possibilities. If the number of possible completions is greater than this value, Readline will ask the user whether or not he wishes to view them; otherwise, they are simply listed. This variable must be set to an integer value greater than or equal to 0. The default limit is 100.

convert-meta
If set to `on', Readline will convert characters with the eighth bit set to an ASCII key sequence by stripping the eighth bit and prefixing an ESC character, converting them to a meta-prefixed key sequence. The default value is `on'.

disable-completion
If set to `On', Readline will inhibit word completion. Completion characters will be inserted into the line as if they had been mapped to self-insert. The default is `off'.

editing-mode
The editing-mode variable controls which default set of key bindings is used. By default, Readline starts up in Emacs editing mode, where the keystrokes are most similar to Emacs. This variable can be set to either `emacs' or `vi'.

enable-keypad
When set to `on', Readline will try to enable the application keypad when it is called. Some systems need this to enable the arrow keys. The default is `off'.

expand-tilde
If set to `on', tilde expansion is performed when Readline attempts word completion. The default is `off'.

If set to `on', the history code attempts to place point at the same location on each history line retrived with previous-history or next-history.

horizontal-scroll-mode
This variable can be set to either `on' or `off'. Setting it to `on' means that the text of the lines being edited will scroll horizontally on a single screen line when they are longer than the width of the screen, instead of wrapping onto a new screen line. By default, this variable is set to `off'.

input-meta
If set to `on', Readline will enable eight-bit input (it will not clear the eighth bit in the characters it reads), regardless of what the terminal claims it can support. The default value is `off'. The name meta-flag is a synonym for this variable.

isearch-terminators
The string of characters that should terminate an incremental search without subsequently executing the character as a command (see section 8.2.5 Searching for Commands in the History). If this variable has not been given a value, the characters ESC and C-J will terminate an incremental search.

keymap
Sets Readline's idea of the current keymap for key binding commands. Acceptable keymap names are emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. vi is equivalent to vi-command; emacs is equivalent to emacs-standard. The default value is emacs. The value of the editing-mode variable also affects the default keymap.

mark-directories
If set to `on', completed directory names have a slash appended. The default is `on'.

mark-modified-lines
This variable, when set to `on', causes Readline to display an asterisk (`*') at the start of history lines which have been modified. This variable is `off' by default.

match-hidden-files
This variable, when set to `on', causes Readline to match files whose names begin with a `.' (hidden files) when performing filename completion, unless the leading `.' is supplied by the user in the filename to be completed. This variable is `on' by default.

output-meta
If set to `on', Readline will display characters with the eighth bit set directly rather than as a meta-prefixed escape sequence. The default is `off'.

print-completions-horizontally
If set to `on', Readline will display completions with matches sorted horizontally in alphabetical order, rather than down the screen. The default is `off'.

show-all-if-ambiguous
This alters the default behavior of the completion functions. If set to `on', words which have more than one possible completion cause the matches to be listed immediately instead of ringing the bell. The default value is `off'.

visible-stats
If set to `on', a character denoting a file's type is appended to the filename when listing possible completions. The default is `off'.

Key Bindings
The syntax for controlling key bindings in the init file is simple. First you need to find the name of the command that you want to change. The following sections contain tables of the command name, the default keybinding, if any, and a short description of what the command does.

Once you know the name of the command, simply place on a line in the init file the name of the key you wish to bind the command to, a colon, and then the name of the command. The name of the key can be expressed in different ways, depending on what you find most comfortable.

In addition to command names, readline allows keys to be bound to a string that is inserted when the key is pressed (a macro).

The bind -p command displays Readline function names and bindings in a format that can put directly into an initialization file. See section 4.2 Bash Builtin Commands.

keyname: function-name or macro
keyname is the name of a key spelled out in English. For example:
Control-u: universal-argument
Meta-Rubout: backward-kill-word
Control-o: "> output"

In the above example, C-u is bound to the function universal-argument, M-DEL is bound to the function backward-kill-word, and C-o is bound to run the macro expressed on the right hand side (that is, to insert the text `> output' into the line).

A number of symbolic character names are recognized while processing this key binding syntax: DEL, ESC, ESCAPE, LFD, NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.

"keyseq": function-name or macro
keyseq differs from keyname above in that strings denoting an entire key sequence can be specified, by placing the key sequence in double quotes. Some GNU Emacs style key escapes can be used, as in the following example, but the special character names are not recognized.

"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
"\e[11~": "Function Key 1"

In the above example, C-u is again bound to the function universal-argument (just as it was in the first example), `C-x C-r' is bound to the function re-read-init-file, and `ESC [ 1 1 ~' is bound to insert the text `Function Key 1'.

The following GNU Emacs style escape sequences are available when specifying key sequences:

\C-
control prefix
\M-
meta prefix
\e
an escape character
\\
backslash
\"
", a double quotation mark
\'
', a single quote or apostrophe

In addition to the GNU Emacs style escape sequences, a second set of backslash escapes is available:

\a
alert (bell)
\b
backspace
\d
delete
\f
form feed
\n
newline
\r
carriage return
\t
horizontal tab
\v
vertical tab
\nnn
the eight-bit character whose value is the octal value nnn (one to three digits)
\xHH
the eight-bit character whose value is the hexadecimal value HH (one or two hex digits)

When entering the text of a macro, single or double quotes must be used to indicate a macro definition. Unquoted text is assumed to be a function name. In the macro body, the backslash escapes described above are expanded. Backslash will quote any other character in the macro text, including `"' and `''. For example, the following binding will make `C-x \' insert a single `\' into the line:
"\C-x\\": "\\"

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.3.2 Conditional Init Constructs

Readline implements a facility similar in spirit to the conditional compilation features of the C preprocessor which allows key bindings and variable settings to be performed as the result of tests. There are four parser directives used.

$if
The $if construct allows bindings to be made based on the editing mode, the terminal being used, or the application using Readline. The text of the test extends to the end of the line; no characters are required to isolate it.

mode
The mode= form of the $if directive is used to test whether Readline is in emacs or vi mode. This may be used in conjunction with the `set keymap' command, for instance, to set bindings in the emacs-standard and emacs-ctlx keymaps only if Readline is starting out in emacs mode.

term
The term= form may be used to include terminal-specific key bindings, perhaps to bind the key sequences output by the terminal's function keys. The word on the right side of the `=' is tested against both the full name of the terminal and the portion of the terminal name before the first `-'. This allows sun to match both sun and sun-cmd, for instance.

application
The application construct is used to include application-specific settings. Each program using the Readline library sets the application name, and you can test for a particular value. This could be used to bind key sequences to functions useful for a specific program. For instance, the following command adds a key sequence that quotes the current or previous word in Bash:
$if Bash
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif

$endif
This command, as seen in the previous example, terminates an $if command.

$else
Commands in this branch of the $if directive are executed if the test fails.

$include
This directive takes a single filename as an argument and reads commands and bindings from that file. For example, the following directive reads from `/etc/inputrc':
$include /etc/inputrc

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.3.3 Sample Init File

Here is an example of an inputrc file. This illustrates key binding, variable assignment, and conditional syntax.

# This file controls the behaviour of line input editing for
# programs that use the Gnu Readline library.  Existing programs
# include FTP, Bash, and Gdb.
#
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
# First, include any systemwide bindings and variable assignments from
# /etc/Inputrc
$include /etc/Inputrc

#
# Set various bindings for emacs mode.

set editing-mode emacs

$if mode=emacs

Meta-Control-h:	backward-kill-word	Text after the function name is ignored

#
# Arrow keys in keypad mode
#
#"\M-OD":        backward-char
#"\M-OC":        forward-char
#"\M-OA":        previous-history
#"\M-OB":        next-history
#
# Arrow keys in ANSI mode
#
"\M-[D":        backward-char
"\M-[C":        forward-char
"\M-[A":        previous-history
"\M-[B":        next-history
#
# Arrow keys in 8 bit keypad mode
#
#"\M-\C-OD":       backward-char
#"\M-\C-OC":       forward-char
#"\M-\C-OA":       previous-history
#"\M-\C-OB":       next-history
#
# Arrow keys in 8 bit ANSI mode
#
#"\M-\C-[D":       backward-char
#"\M-\C-[C":       forward-char
#"\M-\C-[A":       previous-history
#"\M-\C-[B":       next-history

C-q: quoted-insert

$endif

# An old-style binding.  This happens to be the default.
TAB: complete

# Macros that are convenient for shell interaction
$if Bash
# edit the path
"\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
# prepare to type a quoted word -- insert open and close double quotes
# and move to just after the open quote
"\C-x\"": "\"\"\C-b"
# insert a backslash (testing backslash escapes in sequences and macros)
"\C-x\\": "\\"
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
# Add a binding to refresh the line, which is unbound
"\C-xr": redraw-current-line
# Edit variable on current line.
"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
$endif

# use a visible bell if one is available
set bell-style visible

# don't strip characters to 7 bits when reading
set input-meta on

# allow iso-latin1 characters to be inserted rather than converted to
# prefix-meta sequences
set convert-meta off

# display characters with the eighth bit set directly rather than
# as meta-prefixed characters
set output-meta on

# if there are more than 150 possible completions for a word, ask the
# user if he wants to see all of them
set completion-query-items 150

# For FTP
$if Ftp
"\C-xg": "get \M-?"
"\C-xt": "put \M-?"
"\M-.": yank-last-arg
$endif

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4 Bindable Readline Commands

8.4.1 Commands For Moving | Moving about the line.
8.4.2 Commands For Manipulating The History | Getting at previous lines.
8.4.3 Commands For Changing Text | Commands for changing text.
8.4.4 Killing And Yanking | Commands for killing and yanking.
8.4.5 Specifying Numeric Arguments | Specifying numeric arguments, repeat counts.
8.4.6 Letting Readline Type For You | Getting Readline to do the typing for you.
8.4.7 Keyboard Macros | Saving and re-executing typed characters
8.4.8 Some Miscellaneous Commands | Other miscellaneous commands.

This section describes Readline commands that may be bound to key sequences. You can list your key bindings by executing bind -P or, for a more terse format, suitable for an inputrc file, bind -p. (See section 4.2 Bash Builtin Commands.) Command names without an accompanying key sequence are unbound by default.

In the following descriptions, point refers to the current cursor position, and mark refers to a cursor position saved by the set-mark command. The text between the point and mark is referred to as the region.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.1 Commands For Moving

beginning-of-line (C-a)
Move to the start of the current line.

end-of-line (C-e)
Move to the end of the line.

forward-char (C-f)
Move forward a character.

backward-char (C-b)
Move back a character.

forward-word (M-f)
Move forward to the end of the next word. Words are composed of letters and digits.

backward-word (M-b)
Move back to the start of the current or previous word. Words are composed of letters and digits.

clear-screen (C-l)
Clear the screen and redraw the current line, leaving the current line at the top of the screen.

redraw-current-line ()
Refresh the current line. By default, this is unbound.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.2 Commands For Manipulating The History

accept-line (Newline or Return)
Accept the line regardless of where the cursor is. If this line is non-empty, add it to the history list according to the setting of the HISTCONTROL and HISTIGNORE variables. If this line is a modified history line, then restore the history line to its original state.

previous-history (C-p)
Move `back' through the history list, fetching the previous command.

next-history (C-n)
Move `forward' through the history list, fetching the next command.

beginning-of-history (M-<)
Move to the first line in the history.

end-of-history (M->)
Move to the end of the input history, i.e., the line currently being entered.

reverse-search-history (C-r)
Search backward starting at the current line and moving `up' through the history as necessary. This is an incremental search.

forward-search-history (C-s)
Search forward starting at the current line and moving `down' through the the history as necessary. This is an incremental search.

non-incremental-reverse-search-history (M-p)
Search backward starting at the current line and moving `up' through the history as necessary using a non-incremental search for a string supplied by the user.

non-incremental-forward-search-history (M-n)
Search forward starting at the current line and moving `down' through the the history as necessary using a non-incremental search for a string supplied by the user.

history-search-forward ()
Search forward through the history for the string of characters between the start of the current line and the point. This is a non-incremental search. By default, this command is unbound.

history-search-backward ()
Search backward through the history for the string of characters between the start of the current line and the point. This is a non-incremental search. By default, this command is unbound.

yank-nth-arg (M-C-y)
Insert the first argument to the previous command (usually the second word on the previous line) at point. With an argument n, insert the nth word from the previous command (the words in the previous command begin with word 0). A negative argument inserts the nth word from the end of the previous command.

yank-last-arg (M-. or M-_)
Insert last argument to the previous command (the last word of the previous history entry). With an argument, behave exactly like yank-nth-arg. Successive calls to yank-last-arg move back through the history list, inserting the last argument of each line in turn.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.3 Commands For Changing Text

delete-char (C-d)
Delete the character at point. If point is at the beginning of the line, there are no characters in the line, and the last character typed was not bound to delete-char, then return EOF.

backward-delete-char (Rubout)
Delete the character behind the cursor. A numeric argument means to kill the characters instead of deleting them.

forward-backward-delete-char ()
Delete the character under the cursor, unless the cursor is at the end of the line, in which case the character behind the cursor is deleted. By default, this is not bound to a key.

quoted-insert (C-q or C-v)
Add the next character typed to the line verbatim. This is how to insert key sequences like C-q, for example.

self-insert (a, b, A, 1, !, ...)
Insert yourself.

transpose-chars (C-t)
Drag the character before the cursor forward over the character at the cursor, moving the cursor forward as well. If the insertion point is at the end of the line, then this transposes the last two characters of the line. Negative arguments have no effect.

transpose-words (M-t)
Drag the word before point past the word after point, moving point past that word as well. If the insertion point is at the end of the line, this transposes the last two words on the line.

upcase-word (M-u)
Uppercase the current (or following) word. With a negative argument, uppercase the previous word, but do not move the cursor.

downcase-word (M-l)
Lowercase the current (or following) word. With a negative argument, lowercase the previous word, but do not move the cursor.

capitalize-word (M-c)
Capitalize the current (or following) word. With a negative argument, capitalize the previous word, but do not move the cursor.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.4 Killing And Yanking

kill-line (C-k)
Kill the text from point to the end of the line.

backward-kill-line (C-x Rubout)
Kill backward to the beginning of the line.

unix-line-discard (C-u)
Kill backward from the cursor to the beginning of the current line.

kill-whole-line ()
Kill all characters on the current line, no matter where point is. By default, this is unbound.

kill-word (M-d)
Kill from point to the end of the current word, or if between words, to the end of the next word. Word boundaries are the same as forward-word.

backward-kill-word (M-DEL)
Kill the word behind point. Word boundaries are the same as backward-word.

unix-word-rubout (C-w)
Kill the word behind point, using white space as a word boundary. The killed text is saved on the kill-ring.

delete-horizontal-space ()
Delete all spaces and tabs around point. By default, this is unbound.

kill-region ()
Kill the text in the current region. By default, this command is unbound.

copy-region-as-kill ()
Copy the text in the region to the kill buffer, so it can be yanked right away. By default, this command is unbound.

copy-backward-word ()
Copy the word before point to the kill buffer. The word boundaries are the same as backward-word. By default, this command is unbound.

copy-forward-word ()
Copy the word following point to the kill buffer. The word boundaries are the same as forward-word. By default, this command is unbound.

yank (C-y)
Yank the top of the kill ring into the buffer at point.

yank-pop (M-y)
Rotate the kill-ring, and yank the new top. You can only do this if the prior command is yank or yank-pop.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.5 Specifying Numeric Arguments

digit-argument (M-0, M-1, ... M--)
Add this digit to the argument already accumulating, or start a new argument. M-- starts a negative argument.

universal-argument ()
This is another way to specify an argument. If this command is followed by one or more digits, optionally with a leading minus sign, those digits define the argument. If the command is followed by digits, executing universal-argument again ends the numeric argument, but is otherwise ignored. As a special case, if this command is immediately followed by a character that is neither a digit or minus sign, the argument count for the next command is multiplied by four. The argument count is initially one, so executing this function the first time makes the argument count four, a second time makes the argument count sixteen, and so on. By default, this is not bound to a key.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.6 Letting Readline Type For You

complete (TAB)
Attempt to perform completion on the text before point. The actual completion performed is application-specific. Bash attempts completion treating the text as a variable (if the text begins with `$'), username (if the text begins with `~'), hostname (if the text begins with `@'), or command (including aliases and functions) in turn. If none of these produces a match, filename completion is attempted.

possible-completions (M-?)
List the possible completions of the text before point.

insert-completions (M-*)
Insert all completions of the text before point that would have been generated by possible-completions.

menu-complete ()
Similar to complete, but replaces the word to be completed with a single match from the list of possible completions. Repeated execution of menu-complete steps through the list of possible completions, inserting each match in turn. At the end of the list of completions, the bell is rung (subject to the setting of bell-style) and the original text is restored. An argument of n moves n positions forward in the list of matches; a negative argument may be used to move backward through the list. This command is intended to be bound to TAB, but is unbound by default.

delete-char-or-list ()
Deletes the character under the cursor if not at the beginning or end of the line (like delete-char). If at the end of the line, behaves identically to possible-completions. This command is unbound by default.

complete-filename (M-/)
Attempt filename completion on the text before point.

possible-filename-completions (C-x /)
List the possible completions of the text before point, treating it as a filename.

complete-username (M-~)
Attempt completion on the text before point, treating it as a username.

possible-username-completions (C-x ~)
List the possible completions of the text before point, treating it as a username.

complete-variable (M-$)
Attempt completion on the text before point, treating it as a shell variable.

possible-variable-completions (C-x $)
List the possible completions of the text before point, treating it as a shell variable.

complete-hostname (M-@)
Attempt completion on the text before point, treating it as a hostname.

possible-hostname-completions (C-x @)
List the possible completions of the text before point, treating it as a hostname.

complete-command (M-!)
Attempt completion on the text before point, treating it as a command name. Command completion attempts to match the text against aliases, reserved words, shell functions, shell builtins, and finally executable filenames, in that order.

possible-command-completions (C-x !)
List the possible completions of the text before point, treating it as a command name.

dynamic-complete-history (M-TAB)
Attempt completion on the text before point, comparing the text against lines from the history list for possible completion matches.

complete-into-braces (M-{)
Perform filename completion and insert the list of possible completions enclosed within braces so the list is available to the shell (see section 3.5.1 Brace Expansion).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.7 Keyboard Macros

start-kbd-macro (C-x ()
Begin saving the characters typed into the current keyboard macro.

end-kbd-macro (C-x ))
Stop saving the characters typed into the current keyboard macro and save the definition.

call-last-kbd-macro (C-x e)
Re-execute the last keyboard macro defined, by making the characters in the macro appear as if typed at the keyboard.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4.8 Some Miscellaneous Commands

re-read-init-file (C-x C-r)
Read in the contents of the inputrc file, and incorporate any bindings or variable assignments found there.

abort (C-g)
Abort the current editing command and ring the terminal's bell (subject to the setting of bell-style).

do-uppercase-version (M-a, M-b, M-x, ...)
If the metafied character x is lowercase, run the command that is bound to the corresponding uppercase character.

prefix-meta (ESC)
Metafy the next character typed. This is for keyboards without a meta key. Typing `ESC f' is equivalent to typing M-f.

undo (C-_ or C-x C-u)
Incremental undo, separately remembered for each line.

revert-line (M-r)
Undo all changes made to this line. This is like executing the undo command enough times to get back to the beginning.

tilde-expand (M-&)
Perform tilde expansion on the current word.

set-mark (C-@)
Set the mark to the point. If a numeric argument is supplied, the mark is set to that position.

exchange-point-and-mark (C-x C-x)
Swap the point with the mark. The current cursor position is set to the saved position, and the old cursor position is saved as the mark.

character-search (C-])
A character is read and point is moved to the next occurrence of that character. A negative count searches for previous occurrences.

character-search-backward (M-C-])
A character is read and point is moved to the previous occurrence of that character. A negative count searches for subsequent occurrences.

insert-comment (M-#)
The value of the comment-begin variable is inserted at the beginning of the current line, and the line is accepted as if a newline had been typed. The default value of comment-begin causes this command to make the current line a shell comment.

dump-functions ()
Print all of the functions and their key bindings to the Readline output stream. If a numeric argument is supplied, the output is formatted in such a way that it can be made part of an inputrc file. This command is unbound by default.

dump-variables ()
Print all of the settable variables and their values to the Readline output stream. If a numeric argument is supplied, the output is formatted in such a way that it can be made part of an inputrc file. This command is unbound by default.

dump-macros ()
Print all of the Readline key sequences bound to macros and the strings they output. If a numeric argument is supplied, the output is formatted in such a way that it can be made part of an inputrc file. This command is unbound by default.

glob-expand-word (C-x *)
The word before point is treated as a pattern for pathname expansion, and the list of matching file names is inserted, replacing the word.

glob-list-expansions (C-x g)
The list of expansions that would have been generated by glob-expand-word is displayed, and the line is redrawn.

display-shell-version (C-x C-v)
Display version information about the current instance of Bash.

shell-expand-line (M-C-e)
Expand the line as the shell does. This performs alias and history expansion as well as all of the shell word expansions (see section 3.5 Shell Expansions).

history-expand-line (M-^)
Perform history expansion on the current line.

magic-space ()
Perform history expansion on the current line and insert a space (see section 9.3 History Expansion).

alias-expand-line ()
Perform alias expansion on the current line (see section 6.6 Aliases).

history-and-alias-expand-line ()
Perform history and alias expansion on the current line.

insert-last-argument (M-. or M-_)
A synonym for yank-last-arg.

operate-and-get-next (C-o)
Accept the current line for execution and fetch the next line relative to the current line from the history for editing. Any argument is ignored.

emacs-editing-mode (C-e)
When in vi editing mode, this causes a switch back to emacs editing mode, as if the command `set -o emacs' had been executed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.5 Readline vi Mode

While the Readline library does not have a full set of vi editing functions, it does contain enough to allow simple editing of the line. The Readline vi mode behaves as specified in the POSIX 1003.2 standard.

In order to switch interactively between emacs and vi editing modes, use the `set -o emacs' and `set -o vi' commands (see section 4.3 The Set Builtin). The Readline default is emacs mode.

When you enter a line in vi mode, you are already placed in `insertion' mode, as if you had typed an `i'. Pressing ESC switches you into `command' mode, where you can edit the text of the line with the standard vi movement keys, move to previous history lines with `k' and subsequent lines with `j', and so forth.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.6 Programmable Completion

When word completion is attempted for an argument to a command for which a completion specification (a compspec) has been defined using the complete builtin (see section 8.7 Programmable Completion Builtins), the programmable completion facilities are invoked.

First, the command name is identified. If a compspec has been defined for that command, the compspec is used to generate the list of possible completions for the word. If the command word is a full pathname, a compspec for the full pathname is searched for first. If no compspec is found for the full pathname, an attempt is made to find a compspec for the portion following the final slash.

Once a compspec has been found, it is used to generate the list of matching words. If a compspec is not found, the default Bash completion described above (see section 8.4.6 Letting Readline Type For You) is performed.

First, the actions specified by the compspec are used. Only matches which are prefixed by the word being completed are returned. When the `-f' or `-d' option is used for filename or directory name completion, the shell variable FIGNORE is used to filter the matches. See section 5.2 Bash Variables, for a description of FIGNORE.

Any completions specified by a filename expansion pattern to the `-G' option are generated next. The words generated by the pattern need not match the word being completed. The GLOBIGNORE shell variable is not used to filter the matches, but the FIGNORE shell variable is used.

Next, the string specified as the argument to the `-W' option is considered. The string is first split using the characters in the IFS special variable as delimiters. Shell quoting is honored. Each word is then expanded using brace expansion, tilde expansion, parameter and variable expansion, command substitution, arithmetic expansion, and pathname expansion, as described above (see section 3.5 Shell Expansions). The results are split using the rules described above (see section 3.5.7 Word Splitting). The results of the expansion are prefix-matched against the word being completed, and the matching words become the possible completions.

After these matches have been generated, any shell function or command specified with the `-F' and `-C' options is invoked. When the command or function is invoked, the COMP_LINE and COMP_POINT variables are assigned values as described above (see section 5.2 Bash Variables). If a shell function is being invoked, the COMP_WORDS and COMP_CWORD variables are also set. When the function or command is invoked, the first argument is the name of the command whose arguments are being completed, the second argument is the word being completed, and the third argument is the word preceding the word being completed on the current command line. No filtering of the generated completions against the word being completed is performed; the function or command has complete freedom in generating the matches.

Any function specified with `-F' is invoked first. The function may use any of the shell facilities, including the compgen builtin described below (see section 8.7 Programmable Completion Builtins), to generate the matches. It must put the possible completions in the COMPREPLY array variable.

Next, any command specified with the `-C' option is invoked in an environment equivalent to command substitution. It should print a list of completions, one per line, to the standard output. Backslash may be used to escape a newline, if necessary.

After all of the possible completions are generated, any filter specified with the `-X' option is applied to the list. The filter is a pattern as used for pathname expansion; a `&' in the pattern is replaced with the text of the word being completed. A literal `&' may be escaped with a backslash; the backslash is removed before attempting a match. Any completion that matches the pattern will be removed from the list. A leading `!' negates the pattern; in this case any completion not matching the pattern will be removed.

Finally, any prefix and suffix specified with the `-P' and `-S' options are added to each member of the completion list, and the result is returned to the Readline completion code as the list of possible completions.

If the previously-applied actions do not generate any matches, and the `-o dirnames' option was supplied to complete when the compspec was defined, directory name completion is attempted.

By default, if a compspec is found, whatever it generates is returned to the completion code as the full set of possible completions. The default Bash completions are not attempted, and the Readline default of filename completion is disabled. If the `-o default' option was supplied to complete when the compspec was defined, Readline's default completion will be performed if the compspec generates no matches.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.7 Programmable Completion Builtins

Two builtin commands are available to manipulate the programmable completion facilities.

compgen
compgen [option] [word]

Generate possible completion matches for word according to the options, which may be any option accepted by the complete builtin with the exception of `-p' and `-r', and write the matches to the standard output. When using the `-F' or `-C' options, the various shell variables set by the programmable completion facilities, while available, will not have useful values.

The matches will be generated in the same way as if the programmable completion code had generated them directly from a completion specification with the same flags. If word is specified, only those completions matching word will be displayed.

The return value is true unless an invalid option is supplied, or no matches were generated.

complete
complete [-abcdefgjkvu] [-o comp-option] [-A action] [-G globpat] [-W wordlist]
[-P prefix] [-S suffix] [-X filterpat] [-F function]
[-C command] name [name ...]
complete -pr [name ...]

Specify how arguments to each name should be completed. If the `-p' option is supplied, or if no options are supplied, existing completion specifications are printed in a way that allows them to be reused as input. The `-r' option removes a completion specification for each name, or, if no names are supplied, all completion specifications.

The process of applying these completion specifications when word completion is attempted is described above (see section 8.6 Programmable Completion).

Other options, if specified, have the following meanings. The arguments to the `-G', `-W', and `-X' options (and, if necessary, the `-P' and `-S' options) should be quoted to protect them from expansion before the complete builtin is invoked.

-o comp-option
The comp-option controls several aspects of the compspec's behavior beyond the simple generation of completions. comp-option may be one of:

default
Use readline's default completion if the compspec generates no matches.

dirnames
Perform directory name completion if the compspec generates no matches.

filenames
Tell Readline that the compspec generates filenames, so it can perform any filename\-specific processing (like adding a slash to directory names or suppressing trailing spaces). This option is intended to be used with shell functions specified with `-F'.

-A action
The action may be one of the following to generate a list of possible completions:

alias
Alias names. May also be specified as `-a'.

arrayvar
Array variable names.

binding
Readline key binding names (see section 8.4 Bindable Readline Commands).

builtin
Names of shell builtin commands. May also be specified as `-b'.

command
Command names. May also be specified as `-c'.

directory
Directory names. May also be specified as `-d'.

disabled
Names of disabled shell builtins.

enabled
Names of enabled shell builtins.

export
Names of exported shell variables. May also be specified as `-e'.

file
File names. May also be specified as `-f'.

function
Names of shell functions.

group
Group names. May also be specified as `-g'.

helptopic
Help topics as accepted by the help builtin (see section 4.2 Bash Builtin Commands).

hostname
Hostnames, as taken from the file specified by the HOSTFILE shell variable (see section 5.2 Bash Variables).

job
Job names, if job control is active. May also be specified as `-j'.

keyword
Shell reserved words. May also be specified as `-k'.

running
Names of running jobs, if job control is active.

setopt
Valid arguments for the `-o' option to the set builtin (see section 4.3 The Set Builtin).

shopt
Shell option names as accepted by the shopt builtin (see section 4.2 Bash Builtin Commands).

signal
Signal names.

stopped
Names of stopped jobs, if job control is active.

user
User names. May also be specified as `-u'.

variable
Names of all shell variables. May also be specified as `-v'.

-G globpat
The filename expansion pattern globpat is expanded to generate the possible completions.

-W wordlist
The wordlist is split using the characters in the IFS special variable as delimiters, and each resultant word is expanded. The possible completions are the members of the resultant list which match the word being completed.

-C command
command is executed in a subshell environment, and its output is used as the possible completions.

-F function
The shell function function is executed in the current shell environment. When it finishes, the possible completions are retrieved from the value of the COMPREPLY array variable.

-X filterpat
filterpat is a pattern as used for filename expansion. It is applied to the list of possible completions generated by the preceding options and arguments, and each completion matching filterpat is removed from the list. A leading `!' in filterpat negates the pattern; in this case, any completion not matching filterpat is removed.

-P prefix
prefix is added at the beginning of each possible completion after all other options have been applied.

-S suffix
suffix is appended to each possible completion after all other options have been applied.

The return value is true unless an invalid option is supplied, an option other than `-p' or `-r' is supplied without a name argument, an attempt is made to remove a completion specification for a name for which no specification exists, or an error occurs adding a completion specification.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. Using History Interactively

This chapter describes how to use the GNU History Library interactively, from a user's standpoint. It should be considered a user's guide. For information on using the GNU History Library in other programs, see the GNU Readline Library Manual.

9.1 Bash History Facilities | How Bash lets you manipulate your command history.
9.2 Bash History Builtins | The Bash builtin commands that manipulate the command history.
9.3 History Expansion | What it feels like using History as a user.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1 Bash History Facilities

When the `-o history' option to the set builtin is enabled (see section 4.3 The Set Builtin), the shell provides access to the command history, the list of commands previously typed. The value of the HISTSIZE shell variable is used as the number of commands to save in a history list. The text of the last $HISTSIZE commands (default 500) is saved. The shell stores each command in the history list prior to parameter and variable expansion but after history expansion is performed, subject to the values of the shell variables HISTIGNORE and HISTCONTROL.

When the shell starts up, the history is initialized from the file named by the HISTFILE variable (default `~/.bash_history'). The file named by the value of HISTFILE is truncated, if necessary, to contain no more than the number of lines specified by the value of the HISTFILESIZE variable. When an interactive shell exits, the last $HISTSIZE lines are copied from the history list to the file named by $HISTFILE. If the histappend shell option is set (see section 4.2 Bash Builtin Commands), the lines are appended to the history file, otherwise the history file is overwritten. If HISTFILE is unset, or if the history file is unwritable, the history is not saved. After saving the history, the history file is truncated to contain no more than $HISTFILESIZE lines. If HISTFILESIZE is not set, no truncation is performed.

The builtin command fc may be used to list or edit and re-execute a portion of the history list. The history builtin may be used to display or modify the history list and manipulate the history file. When using command-line editing, search commands are available in each editing mode that provide access to the history list (see section 8.4.2 Commands For Manipulating The History).

The shell allows control over which commands are saved on the history list. The HISTCONTROL and HISTIGNORE variables may be set to cause the shell to save only a subset of the commands entered. The cmdhist shell option, if enabled, causes the shell to attempt to save each line of a multi-line command in the same history entry, adding semicolons where necessary to preserve syntactic correctness. The lithist shell option causes the shell to save the command with embedded newlines instead of semicolons. The shopt builtin is used to set these options. See section 4.2 Bash Builtin Commands, for a description of shopt.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.2 Bash History Builtins

Bash provides two builtin commands which manipulate the history list and history file.

fc
fc [-e ename] [-nlr] [first] [last]
fc -s [pat=rep] [command]

Fix Command. In the first form, a range of commands from first to last is selected from the history list. Both first and last may be specified as a string (to locate the most recent command beginning with that string) or as a number (an index into the history list, where a negative number is used as an offset from the current command number). If last is not specified it is set to first. If first is not specified it is set to the previous command for editing and -16 for listing. If the `-l' flag is given, the commands are listed on standard output. The `-n' flag suppresses the command numbers when listing. The `-r' flag reverses the order of the listing. Otherwise, the editor given by ename is invoked on a file containing those commands. If ename is not given, the value of the following variable expansion is used: ${FCEDIT:-${EDITOR:-vi}}. This says to use the value of the FCEDIT variable if set, or the value of the EDITOR variable if that is set, or vi if neither is set. When editing is complete, the edited commands are echoed and executed.

In the second form, command is re-executed after each instance of pat in the selected command is replaced by rep.

A useful alias to use with the fc command is r='fc -s', so that typing `r cc' runs the last command beginning with cc and typing `r' re-executes the last command (see section 6.6 Aliases).

history
history [n]
history -c
history -d offset
history [-anrw] [filename]
history -ps arg

With no options, display the history list with line numbers. Lines prefixed with a `*' have been modified. An argument of n lists only the last n lines. Options, if supplied, have the following meanings:

-c
Clear the history list. This may be combined with the other options to replace the history list completely.

-d offset
Delete the history entry at position offset. offset should be specified as it appears when the history is displayed.

-a
Append the new history lines (history lines entered since the beginning of the current Bash session) to the history file.

-n
Append the history lines not already read from the history file to the current history list. These are lines appended to the history file since the beginning of the current Bash session.

-r
Read the current history file and append its contents to the history list.

-w
Write out the current history to the history file.

-p
Perform history substitution on the args and display the result on the standard output, without storing the results in the history list.

-s
The args are added to the end of the history list as a single entry.

When any of the `-w', `-r', `-a', or `-n' options is used, if filename is given, then it is used as the history file. If not, then the value of the HISTFILE variable is used.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3 History Expansion

The History library provides a history expansion feature that is similar to the history expansion provided by csh. This section describes the syntax used to manipulate the history information.

History expansions introduce words from the history list into the input stream, making it easy to repeat commands, insert the arguments to a previous command into the current input line, or fix errors in previous commands quickly.

History expansion takes place in two parts. The first is to determine which line from the history list should be used during substitution. The second is to select portions of that line for inclusion into the current one. The line selected from the history is called the event, and the portions of that line that are acted upon are called words. Various modifiers are available to manipulate the selected words. The line is broken into words in the same fashion that Bash does, so that several words surrounded by quotes are considered one word. History expansions are introduced by the appearance of the history expansion character, which is `!' by default. Only `\' and `'' may be used to escape the history expansion character.

Several shell options settable with the shopt builtin (see section 4.2 Bash Builtin Commands) may be used to tailor the behavior of history expansion. If the histverify shell option is enabled, and Readline is being used, history substitutions are not immediately passed to the shell parser. Instead, the expanded line is reloaded into the Readline editing buffer for further modification. If Readline is being used, and the histreedit shell option is enabled, a failed history expansion will be reloaded into the Readline editing buffer for correction. The `-p' option to the history builtin command may be used to see what a history expansion will do before using it. The `-s' option to the history builtin may be used to add commands to the end of the history list without actually executing them, so that they are available for subsequent recall. This is most useful in conjunction with Readline.

The shell allows control of the various characters used by the history expansion mechanism with the histchars variable.

9.3.1 Event Designators | How to specify which history line to use.
9.3.2 Word Designators | Specifying which words are of interest.
9.3.3 Modifiers | Modifying the results of substitution.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3.1 Event Designators

An event designator is a reference to a command line entry in the history list.

!
Start a history substitution, except when followed by a space, tab, the end of the line, `=' or `('.

!n
Refer to command line n.

!-n
Refer to the command n lines back.

!!
Refer to the previous command. This is a synonym for `!-1'.

!string
Refer to the most recent command starting with string.

!?string[?]
Refer to the most recent command containing string. The trailing `?' may be omitted if the string is followed immediately by a newline.

^string1^string2^
Quick Substitution. Repeat the last command, replacing string1 with string2. Equivalent to !!:s/string1/string2/.

!#
The entire command line typed so far.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3.2 Word Designators

Word designators are used to select desired words from the event. A `:' separates the event specification from the word designator. It may be omitted if the word designator begins with a `^', `$', `*', `-', or `%'. Words are numbered from the beginning of the line, with the first word being denoted by 0 (zero). Words are inserted into the current line separated by single spaces.

For example,

!!
designates the preceding command. When you type this, the preceding command is repeated in toto.

!!:$
designates the last argument of the preceding command. This may be shortened to !$.

!fi:2
designates the second argument of the most recent command starting with the letters fi.

Here are the word designators:

0 (zero)
The 0th word. For many applications, this is the command word.

n
The nth word.

^
The first argument; that is, word 1.

$
The last argument.

%
The word matched by the most recent `?string?' search.

x-y
A range of words; `-y' abbreviates `0-y'.

*
All of the words, except the 0th. This is a synonym for `1-$'. It is not an error to use `*' if there is just one word in the event; the empty string is returned in that case.

x*
Abbreviates `x-$'

x-
Abbreviates `x-$' like `x*', but omits the last word.

If a word designator is supplied without an event specification, the previous command is used as the event.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3.3 Modifiers

After the optional word designator, you can add a sequence of one or more of the following modifiers, each preceded by a `:'.

h
Remove a trailing pathname component, leaving only the head.

t
Remove all leading pathname components, leaving the tail.

r
Remove a trailing suffix of the form `.suffix', leaving the basename.

e
Remove all but the trailing suffix.

p
Print the new command but do not execute it.

q
Quote the substituted words, escaping further substitutions.

x
Quote the substituted words as with `q', but break into words at spaces, tabs, and newlines.

s/old/new/
Substitute new for the first occurrence of old in the event line. Any delimiter may be used in place of `/'. The delimiter may be quoted in old and new with a single backslash. If `&' appears in new, it is replaced by old. A single backslash will quote the `&'. The final delimiter is optional if it is the last character on the input line.

&
Repeat the previous substitution.

g
Cause changes to be applied over the entire event line. Used in conjunction with `s', as in gs/old/new/, or with `&'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10. Installing Bash

This chapter provides basic instructions for installing Bash on the various supported platforms. The distribution supports the GNU operating systems, nearly every version of Unix, and several non-Unix systems such as BeOS and Interix. Other independent ports exist for MS-DOS, OS/2, Windows 95/98, and Windows NT.

10.1 Basic Installation Installation instructions.

10.2 Compilers and Options How to set special options for various systems.

10.3 Compiling For Multiple Architectures How to compile Bash for more than one kind of system from the same source tree.

10.4 Installation Names How to set the various paths used by the installation.

10.5 Specifying the System Type How to configure Bash for a particular system.

10.6 Sharing Defaults How to share default configuration values among GNU programs.

10.7 Operation Controls Options recognized by the configuration program.

10.8 Optional Features How to enable and disable optional features when building Bash.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.1 Basic Installation

These are installation instructions for Bash.

The simplest way to compile Bash is:

  1. cd to the directory containing the source code and type `./configure' to configure Bash for your system. If you're using csh on an old version of System V, you might need to type `sh ./configure' instead to prevent csh from trying to execute configure itself.

    Running configure takes some time. While running, it prints messages telling which features it is checking for.

  2. Type `make' to compile Bash and build the bashbug bug reporting script.

  3. Optionally, type `make tests' to run the Bash test suite.

  4. Type `make install' to install bash and bashbug. This will also install the manual pages and Info file.

The configure shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses those values to create a `Makefile' in each directory of the package (the top directory, the `builtins', `doc', and `support' directories, each directory under `lib', and several others). It also creates a `config.h' file containing system-dependent definitions. Finally, it creates a shell script named config.status that you can run in the future to recreate the current configuration, a file `config.cache' that saves the results of its tests to speed up reconfiguring, and a file `config.log' containing compiler output (useful mainly for debugging configure). If at some point `config.cache' contains results you don't want to keep, you may remove or edit it.

To find out more about the options and arguments that the configure script understands, type

bash-2.04$ ./configure --help

at the Bash prompt in your Bash source directory.

If you need to do unusual things to compile Bash, please try to figure out how configure could check whether or not to do them, and mail diffs or instructions to bash-maintainers@gnu.org so they can be considered for the next release.

The file `configure.in' is used to create configure by a program called Autoconf. You only need `configure.in' if you want to change it or regenerate configure using a newer version of Autoconf. If you do this, make sure you are using Autoconf version 2.50 or newer.

You can remove the program binaries and object files from the source code directory by typing `make clean'. To also remove the files that configure created (so you can compile Bash for a different kind of computer), type `make distclean'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2 Compilers and Options

Some systems require unusual options for compilation or linking that the configure script does not know about. You can give configure initial values for variables by setting them in the environment. Using a Bourne-compatible shell, you can do that on the command line like this:

CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

On systems that have the env program, you can do it like this:

env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

The configuration process uses GCC to build Bash if it is available.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.3 Compiling For Multiple Architectures

You can compile Bash for more than one kind of computer at the same time, by placing the object files for each architecture in their own directory. To do this, you must use a version of make that supports the VPATH variable, such as GNU make. cd to the directory where you want the object files and executables to go and run the configure script from the source directory. You may need to supply the `--srcdir=PATH' argument to tell configure where the source files are. configure automatically checks for the source code in the directory that configure is in and in `..'.

If you have to use a make that does not supports the VPATH variable, you can compile Bash for one architecture at a time in the source code directory. After you have installed Bash for one architecture, use `make distclean' before reconfiguring for another architecture.

Alternatively, if your system supports symbolic links, you can use the `support/mkclone' script to create a build tree which has symbolic links back to each file in the source directory. Here's an example that creates a build directory in the current directory from a source directory `/usr/gnu/src/bash-2.0':

bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .

The mkclone script requires Bash, so you must have already built Bash for at least one architecture before you can create build directories for other architectures.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.4 Installation Names

By default, `make install' will install into `/usr/local/bin', `/usr/local/man', etc. You can specify an installation prefix other than `/usr/local' by giving configure the option `--prefix=PATH', or by specifying a value for the DESTDIR `make' variable when running `make install'.

You can specify separate installation prefixes for architecture-specific files and architecture-independent files. If you give configure the option `--exec-prefix=PATH', `make install' will use PATH as the prefix for installing programs and libraries. Documentation and other data files will still use the regular prefix.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.5 Specifying the System Type

There may be some features configure can not figure out automatically, but need to determine by the type of host Bash will run on. Usually configure can figure that out, but if it prints a message saying it can not guess the host type, give it the `--host=TYPE' option. `TYPE' can either be a short name for the system type, such as `sun4', or a canonical name with three fields: `CPU-COMPANY-SYSTEM' (e.g., `i386-unknown-freebsd4.2').

See the file `support/config.sub' for the possible values of each field.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.6 Sharing Defaults

If you want to set default values for configure scripts to share, you can create a site shell script called config.site that gives default values for variables like CC, cache_file, and prefix. configure looks for `PREFIX/share/config.site' if it exists, then `PREFIX/etc/config.site' if it exists. Or, you can set the CONFIG_SITE environment variable to the location of the site script. A warning: the Bash configure looks for a site script, but not all configure scripts do.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.7 Operation Controls

configure recognizes the following options to control how it operates.

--cache-file=file
Use and save the results of the tests in file instead of `./config.cache'. Set file to `/dev/null' to disable caching, for debugging configure.

--help
Print a summary of the options to configure, and exit.

--quiet
--silent
-q
Do not print messages saying which checks are being made.

--srcdir=dir
Look for the Bash source code in directory dir. Usually configure can determine that directory automatically.

--version
Print the version of Autoconf used to generate the configure script, and exit.

configure also accepts some other, not widely used, boilerplate options. `configure --help' prints the complete list.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.8 Optional Features

The Bash configure has a number of `--enable-feature' options, where feature indicates an optional part of Bash. There are also several `--with-package' options, where package is something like `bash-malloc' or `purify'. To turn off the default use of a package, use `--without-package'. To configure Bash without a feature that is enabled by default, use `--disable-feature'.

Here is a complete list of the `--enable-' and `--with-' options that the Bash configure recognizes.

--with-afs
Define if you are using the Andrew File System from Transarc.

--with-bash-malloc
Use the Bash version of malloc in `lib/malloc/malloc.c'. This is not the same malloc that appears in GNU libc, but an older version derived from the 4.2 BSD malloc. This malloc is very fast, but wastes some space on each allocation. This option is enabled by default. The `NOTES' file contains a list of systems for which this should be turned off, and configure disables this option automatically for a number of systems.

--with-curses
Use the curses library instead of the termcap library. This should be supplied if your system has an inadequate or incomplete termcap database.

--with-gnu-malloc
A synonym for --with-bash-malloc.

--with-installed-readline[=PREFIX]
Define this to make Bash link with a locally-installed version of Readline rather than the version in `lib/readline'. This works only with Readline 4.2 and later versions. If PREFIX is yes or not supplied, configure uses the values of the make variables includedir and libdir, which are subdirectories of prefix by default, to find the installed version of Readline if it is not in the standard system include and library directories. If PREFIX is no, Bash links with the version in `lib/readline'. If PREFIX is set to any other value, configure treats it as a directory pathname and looks for the installed version of Readline in subdirectories of that directory (include files in PREFIX/include and the library in PREFIX/lib).

--with-purify
Define this to use the Purify memory allocation checker from Rational Software.

--enable-minimal-config
This produces a shell with minimal features, close to the historical Bourne shell.

There are several `--enable-' options that alter how Bash is compiled and linked, rather than changing run-time features.

--enable-largefile
Enable support for large files if the operating system requires special compiler options to build programs which can access large files.

--enable-profiling
This builds a Bash binary that produces profiling information to be processed by gprof each time it is executed.

--enable-static-link
This causes Bash to be linked statically, if gcc is being used. This could be used to build a version to use as root's shell.

The `minimal-config' option can be used to disable all of the following options, but it is processed first, so individual options may be enabled using `enable-feature'.

All of the following options except for `disabled-builtins' and `xpg-echo-default' are enabled by default, unless the operating system does not provide the necessary support.

--enable-alias
Allow alias expansion and include the alias and unalias builtins (see section 6.6 Aliases).

--enable-arith-for-command
Include support for the alternate form of the for command that behaves like the C language for statement (see section 3.2.4 Looping Constructs).

--enable-array-variables
Include support for one-dimensional array shell variables (see section 6.7 Arrays).

--enable-bang-history
Include support for csh-like history substitution (see section 9.3 History Expansion).

--enable-brace-expansion
Include csh-like brace expansion ( b{a,b}c ==> bac bbc ). See 3.5.1 Brace Expansion, for a complete description.

--enable-command-timing
Include support for recognizing time as a reserved word and for displaying timing statistics for the pipeline following time (see section 3.2.2 Pipelines). This allows pipelines as well as shell builtins and functions to be timed.

--enable-cond-command
Include support for the [[ conditional command (see section 3.2.5 Conditional Constructs).

--enable-directory-stack
Include support for a csh-like directory stack and the pushd, popd, and dirs builtins (see section 6.8 The Directory Stack).

--enable-disabled-builtins
Allow builtin commands to be invoked via `builtin xxx' even after xxx has been disabled using `enable -n xxx'. See 4.2 Bash Builtin Commands, for details of the builtin and enable builtin commands.

--enable-dparen-arithmetic
Include support for the ((...)) command (see section 3.2.5 Conditional Constructs).

--enable-extended-glob
Include support for the extended pattern matching features described above under 3.5.8.1 Pattern Matching.

--enable-help-builtin
Include the help builtin, which displays help on shell builtins and variables (see section 4.2 Bash Builtin Commands).

--enable-history
Include command history and the fc and history builtin commands (see section 9.1 Bash History Facilities).

--enable-job-control
This enables the job control features (see section 7. Job Control), if the operating system supports them.

--enable-net-redirections
This enables the special handling of filenames of the form /dev/tcp/host/port and /dev/udp/host/port when used in redirections (see section 3.6 Redirections).

--enable-process-substitution
This enables process substitution (see section 3.5.6 Process Substitution) if the operating system provides the necessary support.

--enable-prompt-string-decoding
Turn on the interpretation of a number of backslash-escaped characters in the $PS1, $PS2, $PS3, and $PS4 prompt strings. See 6.9 Controlling the Prompt, for a complete list of prompt string escape sequences.

--enable-progcomp
Enable the programmable completion facilities (see section 8.6 Programmable Completion). If Readline is not enabled, this option has no effect.

--enable-readline
Include support for command-line editing and history with the Bash version of the Readline library (see section 8. Command Line Editing).

--enable-restricted
Include support for a restricted shell. If this is enabled, Bash, when called as rbash, enters a restricted mode. See 6.10 The Restricted Shell, for a description of restricted mode.

--enable-select
Include the select builtin, which allows the generation of simple menus (see section 3.2.5 Conditional Constructs).

--enable-usg-echo-default
A synonym for --enable-xpg-echo-default.

--enable-xpg-echo-default
Make the echo builtin expand backslash-escaped characters by default, without requiring the `-e' option. This sets the default value of the xpg_echo shell option to on, which makes the Bash echo behave more like the version specified in the Single Unix Specification, version 2. See section 4.2 Bash Builtin Commands, for a description of the escape sequences that echo recognizes.

The file `config-top.h' contains C Preprocessor `#define' statements for options which are not settable from configure. Some of these are not meant to be changed; beware of the consequences if you do. Read the comments associated with each definition for more information about its effect.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

A. Reporting Bugs

Please report all bugs you find in Bash. But first, you should make sure that it really is a bug, and that it appears in the latest version of Bash that you have.

Once you have determined that a bug actually exists, use the bashbug command to submit a bug report. If you have a fix, you are encouraged to mail that as well! Suggestions and `philosophical' bug reports may be mailed to bug-bash@gnu.org or posted to the Usenet newsgroup gnu.bash.bug.

All bug reports should include:

  • The version number of Bash.
  • The hardware and operating system.
  • The compiler used to compile Bash.
  • A description of the bug behaviour.
  • A short script or `recipe' which exercises the bug and may be used to reproduce it.

bashbug inserts the first three items automatically into the template it provides for filing a bug report.

Please send all reports concerning this manual to chet@po.CWRU.Edu.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

B. Major Differences From The Bourne Shell

Bash implements essentially the same grammar, parameter and variable expansion, redirection, and quoting as the Bourne Shell. Bash uses the POSIX 1003.2 standard as the specification of how these features are to be implemented. There are some differences between the traditional Bourne shell and Bash; this section quickly details the differences of significance. A number of these differences are explained in greater depth in previous sections. This section uses the version of sh included in SVR4.2 as the baseline reference.

  • Bash is POSIX-conformant, even where the POSIX specification differs from traditional sh behavior (see section 6.11 Bash POSIX Mode).

  • Bash has multi-character invocation options (see section 6.1 Invoking Bash).

  • Bash has command-line editing (see section 8. Command Line Editing) and the bind builtin.

  • Bash provides a programmable word completion mechanism (see section 8.6 Programmable Completion), and two builtin commands, complete and compgen, to manipulate it.

  • Bash has command history (see section 9.1 Bash History Facilities) and the history and fc builtins to manipulate it.

  • Bash implements csh-like history expansion (see section 9.3 History Expansion).

  • Bash has one-dimensional array variables (see section 6.7 Arrays), and the appropriate variable expansions and assignment syntax to use them. Several of the Bash builtins take options to act on arrays. Bash provides a number of built-in array variables.

  • The $'...' quoting syntax, which expands ANSI-C backslash-escaped characters in the text between the single quotes, is supported (see section 3.1.2.4 ANSI-C Quoting).

  • Bash supports the $"..." quoting syntax to do locale-specific translation of the characters between the double quotes. The `-D', `--dump-strings', and `--dump-po-strings' invocation options list the translatable strings found in a script (see section 3.1.2.5 Locale-Specific Translation).

  • Bash implements the ! keyword to negate the return value of a pipeline (see section 3.2.2 Pipelines). Very useful when an if statement needs to act only if a test fails.

  • Bash has the time reserved word and command timing (see section 3.2.2 Pipelines). The display of the timing statistics may be controlled with the TIMEFORMAT variable.

  • Bash implements the for (( expr1 ; expr2 ; expr3 )) arithmetic for command, similar to the C language (see section 3.2.4 Looping Constructs).

  • Bash includes the select compound command, which allows the generation of simple menus (see section 3.2.5 Conditional Constructs).

  • Bash includes the [[ compound command, which makes conditional testing part of the shell grammar (see section 3.2.5 Conditional Constructs).

  • Bash includes brace expansion (see section 3.5.1 Brace Expansion) and tilde expansion (see section 3.5.2 Tilde Expansion).

  • Bash implements command aliases and the alias and unalias builtins (see section 6.6 Aliases).

  • Bash provides shell arithmetic, the (( compound command (see section 3.2.5 Conditional Constructs), and arithmetic expansion (see section 6.5 Shell Arithmetic).

  • Variables present in the shell's initial environment are automatically exported to child processes. The Bourne shell does not normally do this unless the variables are explicitly marked using the export command.

  • Bash includes the POSIX pattern removal `%', `#', `%%' and `##' expansions to remove leading or trailing substrings from variable values (see section 3.5.3 Shell Parameter Expansion).

  • The expansion ${#xx}, which returns the length of ${xx}, is supported (see section 3.5.3 Shell Parameter Expansion).

  • The expansion ${var:offset[:length]}, which expands to the substring of var's value of length length, beginning at offset, is present (see section 3.5.3 Shell Parameter Expansion).

  • The expansion ${var/[/]pattern[/replacement]}, which matches pattern and replaces it with replacement in the value of var, is available (see section 3.5.3 Shell Parameter Expansion).

  • The expansion ${!prefix}* expansion, which expands to the names of all shell variables whose names begin with prefix, is available (see section 3.5.3 Shell Parameter Expansion).

  • Bash has indirect variable expansion using ${!word} (see section 3.5.3 Shell Parameter Expansion).

  • Bash can expand positional parameters beyond $9 using ${num}.

  • The POSIX $() form of command substitution is implemented (see section 3.5.4 Command Substitution), and preferred to the Bourne shell's " (which is also implemented for backwards compatibility).

  • Bash has process substitution (see section 3.5.6 Process Substitution).

  • Bash automatically assigns variables that provide information about the current user (UID, EUID, and GROUPS), the current host (HOSTTYPE, OSTYPE, MACHTYPE, and HOSTNAME), and the instance of Bash that is running (BASH, BASH_VERSION, and BASH_VERSINFO). See section 5.2 Bash Variables, for details.

  • The IFS variable is used to split only the results of expansion, not all words (see section 3.5.7 Word Splitting). This closes a longstanding shell security hole.

  • Bash implements the full set of POSIX 1003.2 filename expansion operators, including character classes, equivalence classes, and collating symbols (see section 3.5.8 Filename Expansion).

  • Bash implements extended pattern matching features when the extglob shell option is enabled (see section 3.5.8.1 Pattern Matching).

  • It is possible to have a variable and a function with the same name; sh does not separate the two name spaces.

  • Bash functions are permitted to have local variables using the local builtin, and thus useful recursive functions may be written (see section 4.2 Bash Builtin Commands).

  • Variable assignments preceding commands affect only that command, even builtins and functions (see section 3.7.4 Environment). In sh, all variable assignments preceding commands are global unless the command is executed from the file system.

  • Bash performs filename expansion on filenames specified as operands to input and output redirection operators (see section 3.6 Redirections).

  • Bash contains the `<>' redirection operator, allowing a file to be opened for both reading and writing, and the `&>' redirection operator, for directing standard output and standard error to the same file (see section 3.6 Redirections).

  • Bash treats a number of filenames specially when they are used in redirection operators (see section 3.6 Redirections).

  • Bash can open network connections to arbitrary machines and services with the redirection operators (see section 3.6 Redirections).

  • The noclobber option is available to avoid overwriting existing files with output redirection (see section 4.3 The Set Builtin). The `>|' redirection operator may be used to override noclobber.

  • The Bash cd and pwd builtins (see section 4.1 Bourne Shell Builtins) each take `-L' and `-P' options to switch between logical and physical modes.

  • Bash allows a function to override a builtin with the same name, and provides access to that builtin's functionality within the function via the builtin and command builtins (see section 4.2 Bash Builtin Commands).

  • The command builtin allows selective disabling of functions when command lookup is performed (see section 4.2 Bash Builtin Commands).

  • Individual builtins may be enabled or disabled using the enable builtin (see section 4.2 Bash Builtin Commands).

  • The Bash exec builtin takes additional options that allow users to control the contents of the environment passed to the executed command, and what the zeroth argument to the command is to be (see section 4.1 Bourne Shell Builtins).

  • Shell functions may be exported to children via the environment using export -f (see section 3.3 Shell Functions).

  • The Bash export, readonly, and declare builtins can take a `-f' option to act on shell functions, a `-p' option to display variables with various attributes set in a format that can be used as shell input, a `-n' option to remove various variable attributes, and `name=value' arguments to set variable attributes and values simultaneously.

  • The Bash hash builtin allows a name to be associated with an arbitrary filename, even when that filename cannot be found by searching the $PATH, using `hash -p' (see section 4.1 Bourne Shell Builtins).

  • Bash includes a help builtin for quick reference to shell facilities (see section 4.2 Bash Builtin Commands).

  • The printf builtin is available to display formatted output (see section 4.2 Bash Builtin Commands).

  • The Bash read builtin (see section 4.2 Bash Builtin Commands) will read a line ending in `\' with the `-r' option, and will use the REPLY variable as a default if no non-option arguments are supplied. The Bash read builtin also accepts a prompt string with the `-p' option and will use Readline to obtain the line when given the `-e' option. The read builtin also has additional options to control input: the `-s' option will turn off echoing of input characters as they are read, the `-t' option will allow read to time out if input does not arrive within a specified number of seconds, the `-n' option will allow reading only a specified number of characters rather than a full line, and the `-d' option will read until a particular character rather than newline.

  • The return builtin may be used to abort execution of scripts executed with the . or source builtins (see section 4.1 Bourne Shell Builtins).

  • Bash includes the shopt builtin, for finer control of shell optional capabilities (see section 4.2 Bash Builtin Commands), and allows these options to be set and unset at shell invocation (see section 6.1 Invoking Bash).

  • Bash has much more optional behavior controllable with the set builtin (see section 4.3 The Set Builtin).

  • The test builtin (see section 4.1 Bourne Shell Builtins) is slightly different, as it implements the POSIX algorithm, which specifies the behavior based on the number of arguments.

  • The trap builtin (see section 4.1 Bourne Shell Builtins) allows a DEBUG pseudo-signal specification, similar to EXIT. Commands specified with a DEBUG trap are executed after every simple command. The DEBUG trap is not inherited by shell functions.

    The trap builtin (see section 4.1 Bourne Shell Builtins) allows an ERR pseudo-signal specification, similar to EXIT and DEBUG. Commands specified with an ERR trap are executed after a simple command fails, with a few exceptions. The ERR trap is not inherited by shell functions.

  • The Bash type builtin is more extensive and gives more information about the names it finds (see section 4.2 Bash Builtin Commands).

  • The Bash umask builtin permits a `-p' option to cause the output to be displayed in the form of a umask command that may be reused as input (see section 4.1 Bourne Shell Builtins).

  • Bash implements a csh-like directory stack, and provides the pushd, popd, and dirs builtins to manipulate it (see section 6.8 The Directory Stack). Bash also makes the directory stack visible as the value of the DIRSTACK shell variable.

  • Bash interprets special backslash-escaped characters in the prompt strings when interactive (see section 6.9 Controlling the Prompt).

  • The Bash restricted mode is more useful (see section 6.10 The Restricted Shell); the SVR4.2 shell restricted mode is too limited.

  • The disown builtin can remove a job from the internal shell job table (see section 7.2 Job Control Builtins) or suppress the sending of SIGHUP to a job when the shell exits as the result of a SIGHUP.

  • The SVR4.2 shell has two privilege-related builtins (mldmode and priv) not present in Bash.

  • Bash does not have the stop or newgrp builtins.

  • Bash does not use the SHACCT variable or perform shell accounting.

  • The SVR4.2 sh uses a TIMEOUT variable like Bash uses TMOUT.

More features unique to Bash may be found in 6. Bash Features.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

B.1 Implementation Differences From The SVR4.2 Shell

Since Bash is a completely new implementation, it does not suffer from many of the limitations of the SVR4.2 shell. For instance:

  • Bash does not fork a subshell when redirecting into or out of a shell control structure such as an if or while statement.

  • Bash does not allow unbalanced quotes. The SVR4.2 shell will silently insert a needed closing quote at EOF under certain circumstances. This can be the cause of some hard-to-find errors.

  • The SVR4.2 shell uses a baroque memory management scheme based on trapping SIGSEGV. If the shell is started from a process with SIGSEGV blocked (e.g., by using the system() C library function call), it misbehaves badly.

  • In a questionable attempt at security, the SVR4.2 shell, when invoked without the `-p' option, will alter its real and effective UID and GID if they are less than some magic threshold value, commonly 100. This can lead to unexpected results.

  • The SVR4.2 shell does not allow users to trap SIGSEGV, SIGALRM, or SIGCHLD.

  • The SVR4.2 shell does not allow the IFS, MAILCHECK, PATH, PS1, or PS2 variables to be unset.

  • The SVR4.2 shell treats `^' as the undocumented equivalent of `|'.

  • Bash allows multiple option arguments when it is invoked (-x -v); the SVR4.2 shell allows only one option argument (-xv). In fact, some versions of the shell dump core if the second argument begins with a `-'.

  • The SVR4.2 shell exits a script if any builtin fails; Bash exits a script only if one of the POSIX 1003.2 special builtins fails, and only for certain failures, as enumerated in the POSIX 1003.2 standard.

  • The SVR4.2 shell behaves differently when invoked as jsh (it turns on job control).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Index of Shell Builtin Commands

Jump to: . : [
A B C D E F G H J K L P R S T U W

 | Index Entry | Section
. |  |
 | . | 4.1 Bourne Shell Builtins
: |  |
 | : | 4.1 Bourne Shell Builtins
[ |  |
 | [ | 4.1 Bourne Shell Builtins
A |  |
 | alias | 4.2 Bash Builtin Commands
B |  |
 | bg | 7.2 Job Control Builtins
 | bind | 4.2 Bash Builtin Commands
 | break | 4.1 Bourne Shell Builtins
 | builtin | 4.2 Bash Builtin Commands
C |  |
 | cd | 4.1 Bourne Shell Builtins
 | command | 4.2 Bash Builtin Commands
 | compgen | 8.7 Programmable Completion Builtins
 | complete | 8.7 Programmable Completion Builtins
 | continue | 4.1 Bourne Shell Builtins
D |  |
 | declare | 4.2 Bash Builtin Commands
 | dirs | 6.8.1 Directory Stack Builtins
 | disown | 7.2 Job Control Builtins
E |  |
 | echo | 4.2 Bash Builtin Commands
 | enable | 4.2 Bash Builtin Commands
 | eval | 4.1 Bourne Shell Builtins
 | exec | 4.1 Bourne Shell Builtins
 | exit | 4.1 Bourne Shell Builtins
 | export | 4.1 Bourne Shell Builtins
F |  |
 | fc | 9.2 Bash History Builtins
 | fg | 7.2 Job Control Builtins
G |  |
 | getopts | 4.1 Bourne Shell Builtins
H |  |
 | hash | 4.1 Bourne Shell Builtins
 | help | 4.2 Bash Builtin Commands
 | history | 9.2 Bash History Builtins
J |  |
 | jobs | 7.2 Job Control Builtins
K |  |
 | kill | 7.2 Job Control Builtins
L |  |
 | let | 4.2 Bash Builtin Commands
 | local | 4.2 Bash Builtin Commands
 | logout | 4.2 Bash Builtin Commands
P |  |
 | popd | 6.8.1 Directory Stack Builtins
 | printf | 4.2 Bash Builtin Commands
 | pushd | 6.8.1 Directory Stack Builtins
 | pwd | 4.1 Bourne Shell Builtins
R |  |
 | read | 4.2 Bash Builtin Commands
 | readonly | 4.1 Bourne Shell Builtins
 | return | 4.1 Bourne Shell Builtins
S |  |
 | set | 4.3 The Set Builtin
 | shift | 4.1 Bourne Shell Builtins
 | shopt | 4.2 Bash Builtin Commands
 | source | 4.2 Bash Builtin Commands
 | suspend | 7.2 Job Control Builtins
T |  |
 | test | 4.1 Bourne Shell Builtins
 | times | 4.1 Bourne Shell Builtins
 | trap | 4.1 Bourne Shell Builtins
 | type | 4.2 Bash Builtin Commands
 | typeset | 4.2 Bash Builtin Commands
U |  |
 | ulimit | 4.2 Bash Builtin Commands
 | umask | 4.1 Bourne Shell Builtins
 | unalias | 4.2 Bash Builtin Commands
 | unset | 4.1 Bourne Shell Builtins
W |  |
 | wait | 7.2 Job Control Builtins

Jump to: . : [
A B C D E F G H J K L P R S T U W

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Index of Shell Reserved Words

Jump to: ! [ ] { }
C D E F I S T U W

 | Index Entry | Section
! |  |
 | ! | 3.2.2 Pipelines
[ |  |
 | [[ | 3.2.5 Conditional Constructs
] |  |
 | ]] | 3.2.5 Conditional Constructs
{ |  |
 | { | 3.2.6 Grouping Commands
} |  |
 | } | 3.2.6 Grouping Commands
C |  |
 | case | 3.2.5 Conditional Constructs
D |  |
 | do | 3.2.4 Looping Constructs
 | done | 3.2.4 Looping Constructs
E |  |
 | elif | 3.2.5 Conditional Constructs
 | else | 3.2.5 Conditional Constructs
 | esac | 3.2.5 Conditional Constructs
F |  |
 | fi | 3.2.5 Conditional Constructs
 | for | 3.2.4 Looping Constructs
 | function | 3.3 Shell Functions
I |  |
 | if | 3.2.5 Conditional Constructs
 | in | 3.2.5 Conditional Constructs
S |  |
 | select | 3.2.5 Conditional Constructs
T |  |
 | then | 3.2.5 Conditional Constructs
 | time | 3.2.2 Pipelines
U |  |
 | until | 3.2.4 Looping Constructs
W |  |
 | while | 3.2.4 Looping Constructs

Jump to: ! [ ] { }
C D E F I S T U W

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Parameter and Variable Index

Jump to: ! # $ * - 0 ? @ _
A B C D E F G H I K L M O P R S T U V

 | Index Entry | Section
! |  |
 | ! | 3.4.2 Special Parameters
 | ! | 3.4.2 Special Parameters
# |  |
 | # | 3.4.2 Special Parameters
 | # | 3.4.2 Special Parameters
$ |  |
 | $ | 3.4.2 Special Parameters
 | $ | 3.4.2 Special Parameters
* |  |
 | * | 3.4.2 Special Parameters
 | * | 3.4.2 Special Parameters
- |  |
 | - | 3.4.2 Special Parameters
 | - | 3.4.2 Special Parameters
0 |  |
 | 0 | 3.4.2 Special Parameters
 | 0 | 3.4.2 Special Parameters
? |  |
 | ? | 3.4.2 Special Parameters
 | ? | 3.4.2 Special Parameters
@ |  |
 | @ | 3.4.2 Special Parameters
 | @ | 3.4.2 Special Parameters
_ |  |
 | _ | 3.4.2 Special Parameters
 | _ | 3.4.2 Special Parameters
A |  |
 | auto_resume | 7.3 Job Control Variables
 | auto_resume | 7.3 Job Control Variables
B |  |
 | BASH | 5.2 Bash Variables
 | BASH | 5.2 Bash Variables
 | BASH_ENV | 5.2 Bash Variables
 | BASH_ENV | 5.2 Bash Variables
 | BASH_VERSINFO | 5.2 Bash Variables
 | BASH_VERSINFO | 5.2 Bash Variables
 | BASH_VERSION | 5.2 Bash Variables
 | BASH_VERSION | 5.2 Bash Variables
 | bell-style | 8.3.1 Readline Init File Syntax
C |  |
 | CDPATH | 5.1 Bourne Shell Variables
 | CDPATH | 5.1 Bourne Shell Variables
 | COLUMNS | 5.2 Bash Variables
 | COLUMNS | 5.2 Bash Variables
 | comment-begin | 8.3.1 Readline Init File Syntax
 | COMP_CWORD | 5.2 Bash Variables
 | COMP_CWORD | 5.2 Bash Variables
 | COMP_LINE | 5.2 Bash Variables
 | COMP_LINE | 5.2 Bash Variables
 | COMP_POINT | 5.2 Bash Variables
 | COMP_POINT | 5.2 Bash Variables
 | COMP_WORDS | 5.2 Bash Variables
 | COMP_WORDS | 5.2 Bash Variables
 | completion-query-items | 8.3.1 Readline Init File Syntax
 | COMPREPLY | 5.2 Bash Variables
 | COMPREPLY | 5.2 Bash Variables
 | convert-meta | 8.3.1 Readline Init File Syntax
D |  |
 | DIRSTACK | 5.2 Bash Variables
 | DIRSTACK | 5.2 Bash Variables
 | disable-completion | 8.3.1 Readline Init File Syntax
E |  |
 | editing-mode | 8.3.1 Readline Init File Syntax
 | enable-keypad | 8.3.1 Readline Init File Syntax
 | EUID | 5.2 Bash Variables
 | EUID | 5.2 Bash Variables
 | expand-tilde | 8.3.1 Readline Init File Syntax
F |  |
 | FCEDIT | 5.2 Bash Variables
 | FCEDIT | 5.2 Bash Variables
 | FIGNORE | 5.2 Bash Variables
 | FIGNORE | 5.2 Bash Variables
 | FUNCNAME | 5.2 Bash Variables
 | FUNCNAME | 5.2 Bash Variables
G |  |
 | GLOBIGNORE | 5.2 Bash Variables
 | GLOBIGNORE | 5.2 Bash Variables
 | GROUPS | 5.2 Bash Variables
 | GROUPS | 5.2 Bash Variables
H |  |
 | histchars | 5.2 Bash Variables
 | histchars | 5.2 Bash Variables
 | HISTCMD | 5.2 Bash Variables
 | HISTCMD | 5.2 Bash Variables
 | HISTCONTROL | 5.2 Bash Variables
 | HISTCONTROL | 5.2 Bash Variables
 | HISTFILE | 5.2 Bash Variables
 | HISTFILE | 5.2 Bash Variables
 | HISTFILESIZE | 5.2 Bash Variables
 | HISTFILESIZE | 5.2 Bash Variables
 | HISTIGNORE | 5.2 Bash Variables
 | HISTIGNORE | 5.2 Bash Variables
 | history-preserve-point | 8.3.1 Readline Init File Syntax
 | HISTSIZE | 5.2 Bash Variables
 | HISTSIZE | 5.2 Bash Variables
 | HOME | 5.1 Bourne Shell Variables
 | HOME | 5.1 Bourne Shell Variables
 | horizontal-scroll-mode | 8.3.1 Readline Init File Syntax
 | HOSTFILE | 5.2 Bash Variables
 | HOSTFILE | 5.2 Bash Variables
 | HOSTNAME | 5.2 Bash Variables
 | HOSTNAME | 5.2 Bash Variables
 | HOSTTYPE | 5.2 Bash Variables
 | HOSTTYPE | 5.2 Bash Variables
I |  |
 | IFS | 5.1 Bourne Shell Variables
 | IFS | 5.1 Bourne Shell Variables
 | IGNOREEOF | 5.2 Bash Variables
 | IGNOREEOF | 5.2 Bash Variables
 | input-meta | 8.3.1 Readline Init File Syntax
 | INPUTRC | 5.2 Bash Variables
 | INPUTRC | 5.2 Bash Variables
 | isearch-terminators | 8.3.1 Readline Init File Syntax
K |  |
 | keymap | 8.3.1 Readline Init File Syntax
L |  |
 | LANG | 5.2 Bash Variables
 | LANG | 5.2 Bash Variables
 | LC_ALL | 5.2 Bash Variables
 | LC_ALL | 5.2 Bash Variables
 | LC_COLLATE | 5.2 Bash Variables
 | LC_COLLATE | 5.2 Bash Variables
 | LC_CTYPE | 5.2 Bash Variables
 | LC_CTYPE | 5.2 Bash Variables
 | LC_MESSAGES | 3.1.2.5 Locale-Specific Translation
 | LC_MESSAGES | 5.2 Bash Variables
 | LC_MESSAGES | 5.2 Bash Variables
 | LC_NUMERIC | 5.2 Bash Variables
 | LC_NUMERIC | 5.2 Bash Variables
 | LINENO | 5.2 Bash Variables
 | LINENO | 5.2 Bash Variables
 | LINES | 5.2 Bash Variables
 | LINES | 5.2 Bash Variables
M |  |
 | MACHTYPE | 5.2 Bash Variables
 | MACHTYPE | 5.2 Bash Variables
 | MAIL | 5.1 Bourne Shell Variables
 | MAIL | 5.1 Bourne Shell Variables
 | MAILCHECK | 5.2 Bash Variables
 | MAILCHECK | 5.2 Bash Variables
 | MAILPATH | 5.1 Bourne Shell Variables
 | MAILPATH | 5.1 Bourne Shell Variables
 | mark-modified-lines | 8.3.1 Readline Init File Syntax
 | match-hidden-files | 8.3.1 Readline Init File Syntax
 | meta-flag | 8.3.1 Readline Init File Syntax
O |  |
 | OLDPWD | 5.2 Bash Variables
 | OLDPWD | 5.2 Bash Variables
 | OPTARG | 5.1 Bourne Shell Variables
 | OPTARG | 5.1 Bourne Shell Variables
 | OPTERR | 5.2 Bash Variables
 | OPTERR | 5.2 Bash Variables
 | OPTIND | 5.1 Bourne Shell Variables
 | OPTIND | 5.1 Bourne Shell Variables
 | OSTYPE | 5.2 Bash Variables
 | OSTYPE | 5.2 Bash Variables
 | output-meta | 8.3.1 Readline Init File Syntax
P |  |
 | PATH | 5.1 Bourne Shell Variables
 | PATH | 5.1 Bourne Shell Variables
 | PIPESTATUS | 5.2 Bash Variables
 | PIPESTATUS | 5.2 Bash Variables
 | POSIXLY_CORRECT | 5.2 Bash Variables
 | POSIXLY_CORRECT | 5.2 Bash Variables
 | PPID | 5.2 Bash Variables
 | PPID | 5.2 Bash Variables
 | PROMPT_COMMAND | 5.2 Bash Variables
 | PROMPT_COMMAND | 5.2 Bash Variables
 | PS1 | 5.1 Bourne Shell Variables
 | PS1 | 5.1 Bourne Shell Variables
 | PS2 | 5.1 Bourne Shell Variables
 | PS2 | 5.1 Bourne Shell Variables
 | PS3 | 5.2 Bash Variables
 | PS3 | 5.2 Bash Variables
 | PS4 | 5.2 Bash Variables
 | PS4 | 5.2 Bash Variables
 | PWD | 5.2 Bash Variables
 | PWD | 5.2 Bash Variables
R |  |
 | RANDOM | 5.2 Bash Variables
 | RANDOM | 5.2 Bash Variables
 | REPLY | 5.2 Bash Variables
 | REPLY | 5.2 Bash Variables
S |  |
 | SECONDS | 5.2 Bash Variables
 | SECONDS | 5.2 Bash Variables
 | SHELLOPTS | 5.2 Bash Variables
 | SHELLOPTS | 5.2 Bash Variables
 | SHLVL | 5.2 Bash Variables
 | SHLVL | 5.2 Bash Variables
 | show-all-if-ambiguous | 8.3.1 Readline Init File Syntax
T |  |
 | TEXTDOMAIN | 3.1.2.5 Locale-Specific Translation
 | TEXTDOMAINDIR | 3.1.2.5 Locale-Specific Translation
 | TIMEFORMAT | 5.2 Bash Variables
 | TIMEFORMAT | 5.2 Bash Variables
 | TMOUT | 5.2 Bash Variables
 | TMOUT | 5.2 Bash Variables
U |  |
 | UID | 5.2 Bash Variables
 | UID | 5.2 Bash Variables
V |  |
 | visible-stats | 8.3.1 Readline Init File Syntax

Jump to: ! # $ * - 0 ? @ _
A B C D E F G H I K L M O P R S T U V

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Function Index

Jump to: A B C D E F G H I K M N O P Q R S T U Y

 | Index Entry | Section
A |  |
 | abort (C-g) | 8.4.8 Some Miscellaneous Commands
 | abort (C-g) | 8.4.8 Some Miscellaneous Commands
 | accept-line (Newline or Return) | 8.4.2 Commands For Manipulating The History
 | accept-line (Newline or Return) | 8.4.2 Commands For Manipulating The History
 | alias-expand-line () | 8.4.8 Some Miscellaneous Commands
 | alias-expand-line () | 8.4.8 Some Miscellaneous Commands
B |  |
 | backward-char (C-b) | 8.4.1 Commands For Moving
 | backward-char (C-b) | 8.4.1 Commands For Moving
 | backward-delete-char (Rubout) | 8.4.3 Commands For Changing Text
 | backward-delete-char (Rubout) | 8.4.3 Commands For Changing Text
 | backward-kill-line (C-x Rubout) | 8.4.4 Killing And Yanking
 | backward-kill-line (C-x Rubout) | 8.4.4 Killing And Yanking
 | backward-kill-word (M-DEL) | 8.4.4 Killing And Yanking
 | backward-kill-word (M-DEL) | 8.4.4 Killing And Yanking
 | backward-word (M-b) | 8.4.1 Commands For Moving
 | backward-word (M-b) | 8.4.1 Commands For Moving
 | beginning-of-history (M-&#60;) | 8.4.2 Commands For Manipulating The History
 | beginning-of-history (M-&#60;) | 8.4.2 Commands For Manipulating The History
 | beginning-of-line (C-a) | 8.4.1 Commands For Moving
 | beginning-of-line (C-a) | 8.4.1 Commands For Moving
C |  |
 | call-last-kbd-macro (C-x e) | 8.4.7 Keyboard Macros
 | call-last-kbd-macro (C-x e) | 8.4.7 Keyboard Macros
 | capitalize-word (M-c) | 8.4.3 Commands For Changing Text
 | capitalize-word (M-c) | 8.4.3 Commands For Changing Text
 | character-search (C-]) | 8.4.8 Some Miscellaneous Commands
 | character-search (C-]) | 8.4.8 Some Miscellaneous Commands
 | character-search-backward (M-C-]) | 8.4.8 Some Miscellaneous Commands
 | character-search-backward (M-C-]) | 8.4.8 Some Miscellaneous Commands
 | clear-screen (C-l) | 8.4.1 Commands For Moving
 | clear-screen (C-l) | 8.4.1 Commands For Moving
 | complete (TAB) | 8.4.6 Letting Readline Type For You
 | complete (TAB) | 8.4.6 Letting Readline Type For You
 | complete-command (M-!) | 8.4.6 Letting Readline Type For You
 | complete-command (M-!) | 8.4.6 Letting Readline Type For You
 | complete-filename (M-/) | 8.4.6 Letting Readline Type For You
 | complete-filename (M-/) | 8.4.6 Letting Readline Type For You
 | complete-hostname (M-@) | 8.4.6 Letting Readline Type For You
 | complete-hostname (M-@) | 8.4.6 Letting Readline Type For You
 | complete-into-braces (M-{) | 8.4.6 Letting Readline Type For You
 | complete-into-braces (M-{) | 8.4.6 Letting Readline Type For You
 | complete-username (M-~) | 8.4.6 Letting Readline Type For You
 | complete-username (M-~) | 8.4.6 Letting Readline Type For You
 | complete-variable (M-$) | 8.4.6 Letting Readline Type For You
 | complete-variable (M-$) | 8.4.6 Letting Readline Type For You
 | copy-backward-word () | 8.4.4 Killing And Yanking
 | copy-backward-word () | 8.4.4 Killing And Yanking
 | copy-forward-word () | 8.4.4 Killing And Yanking
 | copy-forward-word () | 8.4.4 Killing And Yanking
 | copy-region-as-kill () | 8.4.4 Killing And Yanking
 | copy-region-as-kill () | 8.4.4 Killing And Yanking
D |  |
 | delete-char (C-d) | 8.4.3 Commands For Changing Text
 | delete-char (C-d) | 8.4.3 Commands For Changing Text
 | delete-char-or-list () | 8.4.6 Letting Readline Type For You
 | delete-char-or-list () | 8.4.6 Letting Readline Type For You
 | delete-horizontal-space () | 8.4.4 Killing And Yanking
 | delete-horizontal-space () | 8.4.4 Killing And Yanking
 | digit-argument (M-0, M-1, <small>...</small> M--) | 8.4.5 Specifying Numeric Arguments
 | digit-argument (M-0, M-1, <small>...</small> M--) | 8.4.5 Specifying Numeric Arguments
 | display-shell-version (C-x C-v) | 8.4.8 Some Miscellaneous Commands
 | display-shell-version (C-x C-v) | 8.4.8 Some Miscellaneous Commands
 | do-uppercase-version (M-a, M-b, M-x, <small>...</small>) | 8.4.8 Some Miscellaneous Commands
 | do-uppercase-version (M-a, M-b, M-x, <small>...</small>) | 8.4.8 Some Miscellaneous Commands
 | downcase-word (M-l) | 8.4.3 Commands For Changing Text
 | downcase-word (M-l) | 8.4.3 Commands For Changing Text
 | dump-functions () | 8.4.8 Some Miscellaneous Commands
 | dump-functions () | 8.4.8 Some Miscellaneous Commands
 | dump-macros () | 8.4.8 Some Miscellaneous Commands
 | dump-macros () | 8.4.8 Some Miscellaneous Commands
 | dump-variables () | 8.4.8 Some Miscellaneous Commands
 | dump-variables () | 8.4.8 Some Miscellaneous Commands
 | dynamic-complete-history (M-TAB) | 8.4.6 Letting Readline Type For You
 | dynamic-complete-history (M-TAB) | 8.4.6 Letting Readline Type For You
E |  |
 | emacs-editing-mode (C-e) | 8.4.8 Some Miscellaneous Commands
 | emacs-editing-mode (C-e) | 8.4.8 Some Miscellaneous Commands
 | end-kbd-macro (C-x )) | 8.4.7 Keyboard Macros
 | end-kbd-macro (C-x )) | 8.4.7 Keyboard Macros
 | end-of-history (M-&#62;) | 8.4.2 Commands For Manipulating The History
 | end-of-history (M-&#62;) | 8.4.2 Commands For Manipulating The History
 | end-of-line (C-e) | 8.4.1 Commands For Moving
 | end-of-line (C-e) | 8.4.1 Commands For Moving
 | exchange-point-and-mark (C-x C-x) | 8.4.8 Some Miscellaneous Commands
 | exchange-point-and-mark (C-x C-x) | 8.4.8 Some Miscellaneous Commands
F |  |
 | forward-backward-delete-char () | 8.4.3 Commands For Changing Text
 | forward-backward-delete-char () | 8.4.3 Commands For Changing Text
 | forward-char (C-f) | 8.4.1 Commands For Moving
 | forward-char (C-f) | 8.4.1 Commands For Moving
 | forward-search-history (C-s) | 8.4.2 Commands For Manipulating The History
 | forward-search-history (C-s) | 8.4.2 Commands For Manipulating The History
 | forward-word (M-f) | 8.4.1 Commands For Moving
 | forward-word (M-f) | 8.4.1 Commands For Moving
G |  |
 | glob-expand-word (C-x *) | 8.4.8 Some Miscellaneous Commands
 | glob-expand-word (C-x *) | 8.4.8 Some Miscellaneous Commands
 | glob-list-expansions (C-x g) | 8.4.8 Some Miscellaneous Commands
 | glob-list-expansions (C-x g) | 8.4.8 Some Miscellaneous Commands
H |  |
 | history-and-alias-expand-line () | 8.4.8 Some Miscellaneous Commands
 | history-and-alias-expand-line () | 8.4.8 Some Miscellaneous Commands
 | history-expand-line (M-^) | 8.4.8 Some Miscellaneous Commands
 | history-expand-line (M-^) | 8.4.8 Some Miscellaneous Commands
 | history-search-backward () | 8.4.2 Commands For Manipulating The History
 | history-search-backward () | 8.4.2 Commands For Manipulating The History
 | history-search-forward () | 8.4.2 Commands For Manipulating The History
 | history-search-forward () | 8.4.2 Commands For Manipulating The History
I |  |
 | insert-comment (M-#) | 8.4.8 Some Miscellaneous Commands
 | insert-comment (M-#) | 8.4.8 Some Miscellaneous Commands
 | insert-completions (M-*) | 8.4.6 Letting Readline Type For You
 | insert-completions (M-*) | 8.4.6 Letting Readline Type For You
 | insert-last-argument (M-. or M-_) | 8.4.8 Some Miscellaneous Commands
 | insert-last-argument (M-. or M-_) | 8.4.8 Some Miscellaneous Commands
K |  |
 | kill-line (C-k) | 8.4.4 Killing And Yanking
 | kill-line (C-k) | 8.4.4 Killing And Yanking
 | kill-region () | 8.4.4 Killing And Yanking
 | kill-region () | 8.4.4 Killing And Yanking
 | kill-whole-line () | 8.4.4 Killing And Yanking
 | kill-whole-line () | 8.4.4 Killing And Yanking
 | kill-word (M-d) | 8.4.4 Killing And Yanking
 | kill-word (M-d) | 8.4.4 Killing And Yanking
M |  |
 | magic-space () | 8.4.8 Some Miscellaneous Commands
 | magic-space () | 8.4.8 Some Miscellaneous Commands
 | menu-complete () | 8.4.6 Letting Readline Type For You
 | menu-complete () | 8.4.6 Letting Readline Type For You
N |  |
 | next-history (C-n) | 8.4.2 Commands For Manipulating The History
 | next-history (C-n) | 8.4.2 Commands For Manipulating The History
 | non-incremental-forward-search-history (M-n) | 8.4.2 Commands For Manipulating The History
 | non-incremental-forward-search-history (M-n) | 8.4.2 Commands For Manipulating The History
 | non-incremental-reverse-search-history (M-p) | 8.4.2 Commands For Manipulating The History
 | non-incremental-reverse-search-history (M-p) | 8.4.2 Commands For Manipulating The History
O |  |
 | operate-and-get-next (C-o) | 8.4.8 Some Miscellaneous Commands
 | operate-and-get-next (C-o) | 8.4.8 Some Miscellaneous Commands
P |  |
 | possible-command-completions (C-x !) | 8.4.6 Letting Readline Type For You
 | possible-command-completions (C-x !) | 8.4.6 Letting Readline Type For You
 | possible-completions (M-?) | 8.4.6 Letting Readline Type For You
 | possible-completions (M-?) | 8.4.6 Letting Readline Type For You
 | possible-filename-completions (C-x /) | 8.4.6 Letting Readline Type For You
 | possible-filename-completions (C-x /) | 8.4.6 Letting Readline Type For You
 | possible-hostname-completions (C-x @) | 8.4.6 Letting Readline Type For You
 | possible-hostname-completions (C-x @) | 8.4.6 Letting Readline Type For You
 | possible-username-completions (C-x ~) | 8.4.6 Letting Readline Type For You
 | possible-username-completions (C-x ~) | 8.4.6 Letting Readline Type For You
 | possible-variable-completions (C-x $) | 8.4.6 Letting Readline Type For You
 | possible-variable-completions (C-x $) | 8.4.6 Letting Readline Type For You
 | prefix-meta (ESC) | 8.4.8 Some Miscellaneous Commands
 | prefix-meta (ESC) | 8.4.8 Some Miscellaneous Commands
 | previous-history (C-p) | 8.4.2 Commands For Manipulating The History
 | previous-history (C-p) | 8.4.2 Commands For Manipulating The History
Q |  |
 | quoted-insert (C-q or C-v) | 8.4.3 Commands For Changing Text
 | quoted-insert (C-q or C-v) | 8.4.3 Commands For Changing Text
R |  |
 | re-read-init-file (C-x C-r) | 8.4.8 Some Miscellaneous Commands
 | re-read-init-file (C-x C-r) | 8.4.8 Some Miscellaneous Commands
 | redraw-current-line () | 8.4.1 Commands For Moving
 | redraw-current-line () | 8.4.1 Commands For Moving
 | reverse-search-history (C-r) | 8.4.2 Commands For Manipulating The History
 | reverse-search-history (C-r) | 8.4.2 Commands For Manipulating The History
 | revert-line (M-r) | 8.4.8 Some Miscellaneous Commands
 | revert-line (M-r) | 8.4.8 Some Miscellaneous Commands
S |  |
 | self-insert (a, b, A, 1, !, <small>...</small>) | 8.4.3 Commands For Changing Text
 | self-insert (a, b, A, 1, !, <small>...</small>) | 8.4.3 Commands For Changing Text
 | set-mark (C-@) | 8.4.8 Some Miscellaneous Commands
 | set-mark (C-@) | 8.4.8 Some Miscellaneous Commands
 | shell-expand-line (M-C-e) | 8.4.8 Some Miscellaneous Commands
 | shell-expand-line (M-C-e) | 8.4.8 Some Miscellaneous Commands
 | start-kbd-macro (C-x () | 8.4.7 Keyboard Macros
 | start-kbd-macro (C-x () | 8.4.7 Keyboard Macros
T |  |
 | tilde-expand (M-&#38;) | 8.4.8 Some Miscellaneous Commands
 | tilde-expand (M-&#38;) | 8.4.8 Some Miscellaneous Commands
 | transpose-chars (C-t) | 8.4.3 Commands For Changing Text
 | transpose-chars (C-t) | 8.4.3 Commands For Changing Text
 | transpose-words (M-t) | 8.4.3 Commands For Changing Text
 | transpose-words (M-t) | 8.4.3 Commands For Changing Text
U |  |
 | undo (C-_ or C-x C-u) | 8.4.8 Some Miscellaneous Commands
 | undo (C-_ or C-x C-u) | 8.4.8 Some Miscellaneous Commands
 | universal-argument () | 8.4.5 Specifying Numeric Arguments
 | universal-argument () | 8.4.5 Specifying Numeric Arguments
 | unix-line-discard (C-u) | 8.4.4 Killing And Yanking
 | unix-line-discard (C-u) | 8.4.4 Killing And Yanking
 | unix-word-rubout (C-w) | 8.4.4 Killing And Yanking
 | unix-word-rubout (C-w) | 8.4.4 Killing And Yanking
 | upcase-word (M-u) | 8.4.3 Commands For Changing Text
 | upcase-word (M-u) | 8.4.3 Commands For Changing Text
Y |  |
 | yank (C-y) | 8.4.4 Killing And Yanking
 | yank (C-y) | 8.4.4 Killing And Yanking
 | yank-last-arg (M-. or M-_) | 8.4.2 Commands For Manipulating The History
 | yank-last-arg (M-. or M-_) | 8.4.2 Commands For Manipulating The History
 | yank-nth-arg (M-C-y) | 8.4.2 Commands For Manipulating The History
 | yank-nth-arg (M-C-y) | 8.4.2 Commands For Manipulating The History
 | yank-pop (M-y) | 8.4.4 Killing And Yanking
 | yank-pop (M-y) | 8.4.4 Killing And Yanking

Jump to: A B C D E F G H I K M N O P Q R S T U Y

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Concept Index

Jump to: A B C D E F H I J K L M N O P Q R S T V W Y

 | Index Entry | Section
A |  |
 | alias expansion | 6.6 Aliases
 | arithmetic evaluation | 6.5 Shell Arithmetic
 | arithmetic expansion | 3.5.5 Arithmetic Expansion
 | arithmetic, shell | 6.5 Shell Arithmetic
 | arrays | 6.7 Arrays
B |  |
 | background | 7.1 Job Control Basics
 | Bash configuration | 10.1 Basic Installation
 | Bash installation | 10.1 Basic Installation
 | Bourne shell | 3. Basic Shell Features
 | brace expansion | 3.5.1 Brace Expansion
 | builtin | 2. Definitions
C |  |
 | command editing | 8.2.1 Readline Bare Essentials
 | command execution | 3.7.2 Command Search and Execution
 | command expansion | 3.7.1 Simple Command Expansion
 | command history | 9.1 Bash History Facilities
 | command search | 3.7.2 Command Search and Execution
 | command substitution | 3.5.4 Command Substitution
 | command timing | 3.2.2 Pipelines
 | commands, conditional | 3.2.5 Conditional Constructs
 | commands, grouping | 3.2.6 Grouping Commands
 | commands, lists | 3.2.3 Lists of Commands
 | commands, looping | 3.2.4 Looping Constructs
 | commands, pipelines | 3.2.2 Pipelines
 | commands, shell | 3.2 Shell Commands
 | commands, simple | 3.2.1 Simple Commands
 | comments, shell | 3.1.3 Comments
 | completion builtins | 8.7 Programmable Completion Builtins
 | configuration | 10.1 Basic Installation
 | control operator | 2. Definitions
D |  |
 | directory stack | 6.8 The Directory Stack
E |  |
 | editing command lines | 8.2.1 Readline Bare Essentials
 | environment | 3.7.4 Environment
 | evaluation, arithmetic | 6.5 Shell Arithmetic
 | event designators | 9.3.1 Event Designators
 | execution environment | 3.7.3 Command Execution Environment
 | exit status | 2. Definitions
 | exit status | 3.7.5 Exit Status
 | expansion | 3.5 Shell Expansions
 | expansion, arithmetic | 3.5.5 Arithmetic Expansion
 | expansion, brace | 3.5.1 Brace Expansion
 | expansion, filename | 3.5.8 Filename Expansion
 | expansion, parameter | 3.5.3 Shell Parameter Expansion
 | expansion, pathname | 3.5.8 Filename Expansion
 | expansion, tilde | 3.5.2 Tilde Expansion
 | expressions, arithmetic | 6.5 Shell Arithmetic
 | expressions, conditional | 6.4 Bash Conditional Expressions
F |  |
 | field | 2. Definitions
 | filename | 2. Definitions
 | filename expansion | 3.5.8 Filename Expansion
 | foreground | 7.1 Job Control Basics
 | functions, shell | 3.3 Shell Functions
H |  |
 | history builtins | 9.2 Bash History Builtins
 | history events | 9.3.1 Event Designators
 | history expansion | 9.3 History Expansion
 | history list | 9.1 Bash History Facilities
 | History, how to use | 8.7 Programmable Completion Builtins
I |  |
 | identifier | 2. Definitions
 | initialization file, readline | 8.3 Readline Init File
 | installation | 10.1 Basic Installation
 | interaction, readline | 8.2 Readline Interaction
 | interactive shell | 6.1 Invoking Bash
 | interactive shell | 6.3 Interactive Shells
 | internationalization | 3.1.2.5 Locale-Specific Translation
J |  |
 | job | 2. Definitions
 | job control | 2. Definitions
 | job control | 7.1 Job Control Basics
K |  |
 | kill ring | 8.2.3 Readline Killing Commands
 | killing text | 8.2.3 Readline Killing Commands
L |  |
 | localization | 3.1.2.5 Locale-Specific Translation
 | login shell | 6.1 Invoking Bash
M |  |
 | matching, pattern | 3.5.8.1 Pattern Matching
 | metacharacter | 2. Definitions
N |  |
 | name | 2. Definitions
 | native languages | 3.1.2.5 Locale-Specific Translation
 | notation, readline | 8.2.1 Readline Bare Essentials
O |  |
 | operator, shell | 2. Definitions
P |  |
 | parameter expansion | 3.5.3 Shell Parameter Expansion
 | parameters | 3.4 Shell Parameters
 | parameters, positional | 3.4.1 Positional Parameters
 | parameters, special | 3.4.2 Special Parameters
 | pathname expansion | 3.5.8 Filename Expansion
 | pattern matching | 3.5.8.1 Pattern Matching
 | pipeline | 3.2.2 Pipelines
 | POSIX | 2. Definitions
 | POSIX Mode | 6.11 Bash POSIX Mode
 | process group | 2. Definitions
 | process group ID | 2. Definitions
 | process substitution | 3.5.6 Process Substitution
 | programmable completion | 8.6 Programmable Completion
 | prompting | 6.9 Controlling the Prompt
Q |  |
 | quoting | 3.1.2 Quoting
 | quoting, ANSI | 3.1.2.4 ANSI-C Quoting
R |  |
 | Readline, how to use | 7.3 Job Control Variables
 | redirection | 3.6 Redirections
 | reserved word | 2. Definitions
 | restricted shell | 6.10 The Restricted Shell
 | return status | 2. Definitions
S |  |
 | shell arithmetic | 6.5 Shell Arithmetic
 | shell function | 3.3 Shell Functions
 | shell script | 3.8 Shell Scripts
 | shell variable | 3.4 Shell Parameters
 | shell, interactive | 6.3 Interactive Shells
 | signal | 2. Definitions
 | signal handling | 3.7.6 Signals
 | special builtin | 2. Definitions
 | special builtin | 4.4 Special Builtins
 | startup files | 6.2 Bash Startup Files
 | suspending jobs | 7.1 Job Control Basics
T |  |
 | tilde expansion | 3.5.2 Tilde Expansion
 | token | 2. Definitions
 | translation, native languages | 3.1.2.5 Locale-Specific Translation
V |  |
 | variable, shell | 3.4 Shell Parameters
 | variables, readline | 8.3.1 Readline Init File Syntax
W |  |
 | word | 2. Definitions
 | word splitting | 3.5.7 Word Splitting
Y |  |
 | yanking text | 8.2.3 Readline Killing Commands

Jump to: A B C D E F H I J K L M N O P Q R S T V W Y

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Introduction
      1.1 What is Bash?
      1.2 What is a shell?
    2. Definitions
    3. Basic Shell Features
      3.1 Shell Syntax
        3.1.1 Shell Operation
        3.1.2 Quoting
          3.1.2.1 Escape Character
          3.1.2.2 Single Quotes
          3.1.2.3 Double Quotes
          3.1.2.4 ANSI-C Quoting
          3.1.2.5 Locale-Specific Translation
        3.1.3 Comments
      3.2 Shell Commands
        3.2.1 Simple Commands
        3.2.2 Pipelines
        3.2.3 Lists of Commands
        3.2.4 Looping Constructs
        3.2.5 Conditional Constructs
        3.2.6 Grouping Commands
      3.3 Shell Functions
      3.4 Shell Parameters
        3.4.1 Positional Parameters
        3.4.2 Special Parameters
      3.5 Shell Expansions
        3.5.1 Brace Expansion
        3.5.2 Tilde Expansion
        3.5.3 Shell Parameter Expansion
        3.5.4 Command Substitution
        3.5.5 Arithmetic Expansion
        3.5.6 Process Substitution
        3.5.7 Word Splitting
        3.5.8 Filename Expansion
          3.5.8.1 Pattern Matching
        3.5.9 Quote Removal
      3.6 Redirections
        3.6.1 Redirecting Input
        3.6.2 Redirecting Output
        3.6.3 Appending Redirected Output
        3.6.4 Redirecting Standard Output and Standard Error
        3.6.5 Here Documents
        3.6.6 Duplicating File Descriptors
        3.6.7 Opening File Descriptors for Reading and Writing
      3.7 Executing Commands
        3.7.1 Simple Command Expansion
        3.7.2 Command Search and Execution
        3.7.3 Command Execution Environment
        3.7.4 Environment
        3.7.5 Exit Status
        3.7.6 Signals
      3.8 Shell Scripts
    4. Shell Builtin Commands
      4.1 Bourne Shell Builtins
      4.2 Bash Builtin Commands
      4.3 The Set Builtin
      4.4 Special Builtins
    5. Shell Variables
      5.1 Bourne Shell Variables
      5.2 Bash Variables
    6. Bash Features
      6.1 Invoking Bash
      6.2 Bash Startup Files
      6.3 Interactive Shells
        6.3.1 What is an Interactive Shell?
        6.3.2 Is this Shell Interactive?
        6.3.3 Interactive Shell Behavior
      6.4 Bash Conditional Expressions
      6.5 Shell Arithmetic
      6.6 Aliases
      6.7 Arrays
      6.8 The Directory Stack
        6.8.1 Directory Stack Builtins
      6.9 Controlling the Prompt
      6.10 The Restricted Shell
      6.11 Bash POSIX Mode
    7. Job Control
      7.1 Job Control Basics
      7.2 Job Control Builtins
      7.3 Job Control Variables
    8. Command Line Editing
      8.1 Introduction to Line Editing
      8.2 Readline Interaction
        8.2.1 Readline Bare Essentials
        8.2.2 Readline Movement Commands
        8.2.3 Readline Killing Commands
        8.2.4 Readline Arguments
        8.2.5 Searching for Commands in the History
      8.3 Readline Init File
        8.3.1 Readline Init File Syntax
        8.3.2 Conditional Init Constructs
        8.3.3 Sample Init File
      8.4 Bindable Readline Commands
        8.4.1 Commands For Moving
        8.4.2 Commands For Manipulating The History
        8.4.3 Commands For Changing Text
        8.4.4 Killing And Yanking
        8.4.5 Specifying Numeric Arguments
        8.4.6 Letting Readline Type For You
        8.4.7 Keyboard Macros
        8.4.8 Some Miscellaneous Commands
      8.5 Readline vi Mode
      8.6 Programmable Completion
      8.7 Programmable Completion Builtins
    9. Using History Interactively
      9.1 Bash History Facilities
      9.2 Bash History Builtins
      9.3 History Expansion
        9.3.1 Event Designators
        9.3.2 Word Designators
        9.3.3 Modifiers
    10. Installing Bash
      10.1 Basic Installation
      10.2 Compilers and Options
      10.3 Compiling For Multiple Architectures
      10.4 Installation Names
      10.5 Specifying the System Type
      10.6 Sharing Defaults
      10.7 Operation Controls
      10.8 Optional Features
    A. Reporting Bugs
    B. Major Differences From The Bourne Shell
      B.1 Implementation Differences From The SVR4.2 Shell
    Index of Shell Builtin Commands
    Index of Shell Reserved Words
    Parameter and Variable Index
    Function Index
    Concept Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Introduction
2. Definitions
3. Basic Shell Features
4. Shell Builtin Commands
5. Shell Variables
6. Bash Features
7. Job Control
8. Command Line Editing
9. Using History Interactively
10. Installing Bash
A. Reporting Bugs
B. Major Differences From The Bourne Shell
Index of Shell Builtin Commands
Index of Shell Reserved Words
Parameter and Variable Index
Function Index
Concept Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on May 3, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on May 3, 2002 using texi2html


bc Command Manual

bc

an arbitrary precision calculator language

version 1.06

Philip A. Nelson

Table of Contents

  • Introduction
    • Description
    • Command Line Options
  • Basic Elements
    • Numbers
    • Variables
    • Comments
  • Expressions
    • About Expressions and Special Variables
    • Basic Expressions
    • Relational Expressions
    • Boolean Expressions
    • Precedence
    • Special Expressions
  • Statements
    • Pseudo Statements
  • Functions
    • Math Library Functions
  • Examples
  • Readline and Libedit Options
  • GNU bc and Other Implementations
  • Limits
  • Environment Variables

Introduction

Description

bc [ -hlwsqv ] [long-options] [ file ... ]

bc is a language that supports arbitrary precision numbers with interactive execution of statements. There are some similarities in the syntax to the C programming language. A standard math library is available by command line option. If requested, the math library is defined before processing any files. bc starts by processing code from all the files listed on the command line in the order listed. After all files have been processed, bc reads from the standard input. All code is executed as it is read. (If a file contains a command to halt the processor, bc will never read from the standard input.)

This version of bc contains several extensions beyond traditional bc implementations and the POSIX draft standard. Command line options can cause these extensions to print a warning or to be rejected. This document describes the language accepted by this processor. Extensions will be identified as such.

The author would like to thank Steve Sommars (Steve.Sommars@att.com) for his extensive help in testing the implementation. Many great suggestions were given. This is a much better product due to his involvement.

Email bug reports to bug-bc@gnu.org. Be sure to include the word "bc" somewhere in the "Subject:" field.

Command Line Options

bc takes the following options from the command line:

-h, --help
Print the usage and exit.
-l, --mathlib
Define the standard math library.
-w, --warn
Give warnings for extensions to POSIX bc.
-s, --standard
Process exactly the POSIX bc language.
-q, --quiet
Do not print the normal GNU bc welcome.
-v, --version
Print the version number and copyright and quit.

Basic Elements

Numbers

The most basic element in bc is the number. Numbers are arbitrary precision numbers. This precision is both in the integer part and the fractional part. All numbers are represented internally in decimal and all computation is done in decimal. (This version truncates results from divide and multiply operations.) There are two attributes of numbers, the length and the scale. The length is the total number of significant decimal digits in a number and the scale is the total number of decimal digits after the decimal point. For example, .000001 has a length of 6 and scale of 6, while 1935.000 has a length of 7 and a scale of 3.

Variables

Numbers are stored in two types of variables, simple variables and arrays. Both simple variables and array variables are named. Names begin with a letter followed by any number of letters, digits and underscores. All letters must be lower case. (Full alphanumeric names are an extension. In POSIX bc all names are a single lower case letter.) The type of variable is clear by the context because all array variable names will be followed by brackets ( [ ] ).

There are four special variables, scale, ibase, obase, and last. scale defines how some operations use digits after the decimal point. The default value of scale is 0. ibase and obase define the conversion base for input and output numbers. The default for both input and output is base 10. last (an extension) is a variable that has the value of the last printed number. These will be discussed in further detail where appropriate. All of these variables may have values assigned to them as well as used in expressions.

Comments

Comments in bc start with the characters /* and end with the characters */. Comments may start anywhere and appear as a single space in the input. (This causes comments to delimit other input items. For example, a comment can not be found in the middle of a variable name.) Comments include any newlines (end of line) between the start and the end of the comment.

To support the use of scripts for bc, a single line comment has been added as an extension. A single line comment starts at a # character and continues to the next end of the line. The end of line character is not part of the comment and is processed normally.

Expressions

About Expressions and Special Variables

The numbers are manipulated by expressions and statements. Since the language was designed to be interactive, statements and expressions are executed as soon as possible. There is no main program. Instead, code is executed as it is encountered. (Functions, discussed in detail later, are defined when encountered.)

A simple expression is just a constant. bc converts constants into internal decimal numbers using the current input base, specified by the variable ibase. (There is an exception in functions.) The legal values of ibase are 2 through 16. Assigning a value outside this range to ibase will result in a value of 2 or 16. Input numbers may contain the characters 0-9 and A-F. (Note: They must be capitals. Lower case letters are variable names.) Single digit numbers always have the value of the digit regardless of the value of ibase. (i.e. A = 10.) For multi-digit numbers, bc changes all input digits greater or equal to ibase to the value of ibase-1. This makes the number FFF always be the largest 3 digit number of the input base.

Full expressions are similar to many other high level languages. Since there is only one kind of number, there are no rules for mixing types. Instead, there are rules on the scale of expressions. Every expression has a scale. This is derived from the scale of original numbers, the operation performed and in many cases, the value of the variable scale. Legal values of the variable scale are 0 to the maximum number representable by a C integer.

Basic Expressions

In the following descriptions of legal expressions, "expr" refers to a complete expression and "var" refers to a simple or an array variable. A simple variable is just a

name

and an array variable is specified as

name[expr]

Unless specifically mentioned the scale of the result is the maximum scale of the expressions involved.

- expr
The result is the negation of the expression.
++ var
The variable is incremented by one and the new value is the result of the expression.
-- var
The variable is decremented by one and the new value is the result of the expression.
var ++
The result of the expression is the value of the variable and then the variable is incremented by one.
var --
The result of the expression is the value of the variable and then the variable is decremented by one.
expr + expr
The result of the expression is the sum of the two expressions.
expr - expr
The result of the expression is the difference of the two expressions.
expr * expr
The result of the expression is the product of the two expressions.
expr / expr
The result of the expression is the quotient of the two expressions. The scale of the result is the value of the variable scale
expr % expr
The result of the expression is the "remainder" and it is computed in the following way. To compute a%b, first a/b is computed to scale digits. That result is used to compute a-(a/b)*b to the scale of the maximum of scale+scale(b) and scale(a). If scale is set to zero and both expressions are integers this expression is the integer remainder function.
expr ^ expr
The result of the expression is the value of the first raised to the second. The second expression must be an integer. (If the second expression is not an integer, a warning is generated and the expression is truncated to get an integer value.) The scale of the result is scale if the exponent is negative. If the exponent is positive the scale of the result is the minimum of the scale of the first expression times the value of the exponent and the maximum of scale and the scale of the first expression. (e.g. scale(a^b) = min(scale(a)*b, max(scale, scale(a))).) It should be noted that expr^0 will always return the value of 1.
( expr )
This alters the standard precedence to force the evaluation of the expression.
var = expr
The variable is assigned the value of the expression.
var <op>= expr
This is equivalent to "var = var <op> expr" with the exception that the "var" part is evaluated only once. This can make a difference if "var" is an array.

Relational Expressions

Relational expressions are a special kind of expression that always evaluate to 0 or 1, 0 if the relation is false and 1 if the relation is true. These may appear in any legal expression. (POSIX bc requires that relational expressions are used only in if, while, and for statements and that only one relational test may be done in them.) The relational operators are

expr1 < expr2
The result is 1 if expr1 is strictly less than expr2.
expr1 <= expr2
The result is 1 if expr1 is less than or equal to expr2.
expr1 > expr2
The result is 1 if expr1 is strictly greater than expr2.
expr1 >= expr2
The result is 1 if expr1 is greater than or equal to expr2.
expr1 == expr2
The result is 1 if expr1 is equal to expr2.
expr1 != expr2
The result is 1 if expr1 is not equal to expr2.

Boolean Expressions

Boolean operations are also legal. (POSIX bc does NOT have boolean operations). The result of all boolean operations are 0 and 1 (for false and true) as in relational expressions. The boolean operators are:

!expr
The result is 1 if expr is 0.
expr && expr
The result is 1 if both expressions are non-zero.
expr || expr
The result is 1 if either expression is non-zero.

Precedence

The expression precedence is as follows: (lowest to highest)

|| operator, left associative
&& operator, left associative
! operator, nonassociative
Relational operators, left associative
Assignment operator, right associative
+ and - operators, left associative
*, / and % operators, left associative
^ operator, right associative
unary - operator, nonassociative
++ and -- operators, nonassociative

This precedence was chosen so that POSIX compliant bc programs will run correctly. This will cause the use of the relational and logical operators to have some unusual behavior when used with assignment expressions. Consider the expression:

a = 3 < 5

Most C programmers would assume this would assign the result of "3 < 5" (the value 1) to the variable "a". What this does in bc is assign the value 3 to the variable "a" and then compare 3 to 5. It is best to use parentheses when using relational and logical operators with the assignment operators.

Special Expressions

There are a few more special expressions that are provided in bc. These have to do with user-defined functions and standard functions. They all appear as "name(parameters)". See section Functions, for user-defined functions. The standard functions are:

length ( expression )
The value of the length function is the number of significant digits in the expression.
read ( )
The read function (an extension) will read a number from the standard input, regardless of where the function occurs. Beware, this can cause problems with the mixing of data and program in the standard input. The best use for this function is in a previously written program that needs input from the user, but never allows program code to be input from the user. The value of the read function is the number read from the standard input using the current value of the variable ibase for the conversion base.
scale ( expression )
The value of the scale function is the number of digits after the decimal point in the expression.
sqrt ( expression )
The value of the sqrt function is the square root of the expression. If the expression is negative, a run time error is generated.

Statements

Statements (as in most algebraic languages) provide the sequencing of expression evaluation. In bc statements are executed "as soon as possible." Execution happens when a newline in encountered and there is one or more complete statements. Due to this immediate execution, newlines are very important in bc. In fact, both a semicolon and a newline are used as statement separators. An improperly placed newline will cause a syntax error. Because newlines are statement separators, it is possible to hide a newline by using the backslash character. The sequence "\<nl>", where <nl> is the newline appears to bc as whitespace instead of a newline. A statement list is a series of statements separated by semicolons and newlines. The following is a list of bc statements and what they do: (Things enclosed in brackets ( [ ] ) are optional parts of the statement.)

expression
This statement does one of two things. If the expression starts with "<variable> <assignment> ...", it is considered to be an assignment statement. If the expression is not an assignment statement, the expression is evaluated and printed to the output. After the number is printed, a newline is printed. For example, "a=1" is an assignment statement and "(a=1)" is an expression that has an embedded assignment. All numbers that are printed are printed in the base specified by the variable obase. The legal values for obase are 2 through BC_BASE_MAX (see section Environment Variables). For bases 2 through 16, the usual method of writing numbers is used. For bases greater than 16, bc uses a multi-character digit method of printing the numbers where each higher base digit is printed as a base 10 number. The multi-character digits are separated by spaces. Each digit contains the number of characters required to represent the base ten value of "obase -1". Since numbers are of arbitrary precision, some numbers may not be printable on a single output line. These long numbers will be split across lines using the "\" as the last character on a line. The maximum number of characters printed per line is 70. Due to the interactive nature of bc, printing a number causes the side effect of assigning the printed value to the special variable last. This allows the user to recover the last value printed without having to retype the expression that printed the number. Assigning to last is legal and will overwrite the last printed value with the assigned value. The newly assigned value will remain until the next number is printed or another value is assigned to last. (Some installations may allow the use of a single period (.) which is not part of a number as a short hand notation for for last.)
string
The string is printed to the output. Strings start with a double quote character and contain all characters until the next double quote character. All characters are taken literally, including any newline. No newline character is printed after the string.
print list
The print statement (an extension) provides another method of output. The list is a list of strings and expressions separated by commas. Each string or expression is printed in the order of the list. No terminating newline is printed. Expressions are evaluated and their value is printed and assigned to the variable last. Strings in the print statement are printed to the output and may contain special characters. Special characters start with the backslash character (\e). The special characters recognized by bc are "a" (alert or bell), "b" (backspace), "f" (form feed), "n" (newline), "r" (carriage return), "q" (double quote), "t" (tab), and "\e" (backslash). Any other character following the backslash will be ignored.
{ statement_list }
This is the compound statement. It allows multiple statements to be grouped together for execution.
if ( expression ) statement1 [else statement2]
The if statement evaluates the expression and executes statement1 or statement2 depending on the value of the expression. If the expression is non-zero, statement1 is executed. If statement2 is present and the value of the expression is 0, then statement2 is executed. (The else clause is an extension.)
while ( expression ) statement
The while statement will execute the statement while the expression is non-zero. It evaluates the expression before each execution of the statement. Termination of the loop is caused by a zero expression value or the execution of a break statement.
for ( [expression1] ; [expression2] ; [expression3] ) statement
The for statement controls repeated execution of the statement. Expression1 is evaluated before the loop. Expression2 is evaluated before each execution of the statement. If it is non-zero, the statement is evaluated. If it is zero, the loop is terminated. After each execution of the statement, expression3 is evaluated before the reevaluation of expression2. If expression1 or expression3 are missing, nothing is evaluated at the point they would be evaluated. If expression2 is missing, it is the same as substituting the value 1 for expression2. (The optional expressions are an extension. POSIX bc requires all three expressions.) The following is equivalent code for the for statement:
expression1;
while (expression2) {
   statement;
   expression3;
}
break
This statement causes a forced exit of the most recent enclosing while statement or for statement.
continue
The continue statement (an extension) causes the most recent enclosing for statement to start the next iteration.
halt
The halt statement (an extension) is an executed statement that causes the bc processor to quit only when it is executed. For example, "if (0 == 1) halt" will not cause bc to terminate because the halt is not executed.
return
Return the value 0 from a function. (See section Functions.)
return ( expression )
Return the value of the expression from a function. (See section Functions.) As an extension, the parenthesis are not required.

Pseudo Statements

These statements are not statements in the traditional sense. They are not executed statements. Their function is performed at "compile" time.

limits
Print the local limits enforced by the local version of bc. This is an extension.
quit
When the quit statement is read, the bc processor is terminated, regardless of where the quit statement is found. For example, "if (0 == 1) quit" will cause bc to terminate.
warranty
Print a longer warranty notice. This is an extension.

Functions

Functions provide a method of defining a computation that can be executed later. Functions in bc always compute a value and return it to the caller. Function definitions are "dynamic" in the sense that a function is undefined until a definition is encountered in the input. That definition is then used until another definition function for the same name is encountered. The new definition then replaces the older definition. A function is defined as follows:

define name ( parameters ) { newline
    auto_list   statement_list }

A function call is just an expression of the form "name (parameters)".

Parameters are numbers or arrays (an extension). In the function definition, zero or more parameters are defined by listing their names separated by commas. Numbers are only call by value parameters. Arrays are only call by variable. Arrays are specified in the parameter definition by the notation "name[ ]". In the function call, actual parameters are full expressions for number parameters. The same notation is used for passing arrays as for defining array parameters. The named array is passed by variable to the function. Since function definitions are dynamic, parameter numbers and types are checked when a function is called. Any mismatch in number or types of parameters will cause a runtime error. A runtime error will also occur for the call to an undefined function.

The auto_list is an optional list of variables that are for "local" use. The syntax of the auto list (if present) is "auto name, ... ;". (The semicolon is optional.) Each name is the name of an auto variable. Arrays may be specified by using the same notation as used in parameters. These variables have their values pushed onto a stack at the start of the function. The variables are then initialized to zero and used throughout the execution of the function. At function exit, these variables are popped so that the original value (at the time of the function call) of these variables are restored. The parameters are really auto variables that are initialized to a value provided in the function call. Auto variables are different than traditional local variables because if function A calls function B, B may access function A's auto variables by just using the same name, unless function B has called them auto variables. Due to the fact that auto variables and parameters are pushed onto a stack, bc supports recursive functions.

The function body is a list of bc statements. Again, statements are separated by semicolons or newlines. Return statements cause the termination of a function and the return of a value. There are two versions of the return statement. The first form, "return", returns the value 0 to the calling expression. The second form, "return ( expression )", computes the value of the expression and returns that value to the calling expression. There is an implied "return (0)" at the end of every function. This allows a function to terminate and return 0 without an explicit return statement.

Functions also change the usage of the variable ibase. All constants in the function body will be converted using the value of ibase at the time of the function call. Changes of ibase will be ignored during the execution of the function except for the standard function read, which will always use the current value of ibase for conversion of numbers.

As an extension, the format of the definition has been slightly relaxed. The standard requires the opening brace be on the same line as the define keyword and all other parts must be on following lines. This version of bc will allow any number of newlines before and after the opening brace of the function. For example, the following definitions are legal.

   define d (n) { return (2*n); }
   define d (n)
       { return (2*n); }

Math Library Functions

If bc is invoked with the -l option, a math library is preloaded and the default scale is set to 20. The math functions will calculate their results to the scale set at the time of their call. The math library defines the following functions:

s (x)
The sine of x, x is in radians.
c (x)
The cosine of x, x is in radians.
a (x)
The arctangent of x, arctangent returns radians.
l (x)
The natural logarithm of x.
e (x)
The exponential function of raising e to the value x.
j (n,x)
The bessel function of integer order n of x.

Examples

In /bin/sh, the following will assign the value of "pi" to the shell variable pi.

pi=$(echo "scale=10; 4*a(1)" | bc -l)

The following is the definition of the exponential function used in the math library. This function is written in POSIX bc.

scale = 20

/* Uses the fact that e^x = (e^(x/2))^2
   When x is small enough, we use the series:
     e^x = 1 + x + x^2/2! + x^3/3! + ...
*/

define e(x) {
  auto  a, d, e, f, i, m, v, z

  /* Check the sign of x. */
  if (x<0) {
    m = 1
    x = -x
  }

  /* Precondition x. */
  z = scale;
  scale = 4 + z + .44*x;
  while (x > 1) {
    f += 1;
    x /= 2;
  }

  /* Initialize the variables. */
  v = 1+x
  a = x
  d = 1

  for (i=2; 1; i++) {
    e = (a *= x) / (d *= i)
    if (e == 0) {
      if (f>0) while (f--)  v = v*v;
      scale = z
      if (m) return (1/v);
      return (v/1);
    }
    v += e
  }
}

The following is code that uses the extended features of bc to implement a simple program for calculating checkbook balances. This program is best kept in a file so that it can be used many times without having to retype it at every use.

scale=2
print "\nCheck book program\n!"
print "  Remember, deposits are negative transactions.\n"
print "  Exit by a 0 transaction.\n\n"

print "Initial balance? "; bal = read()
bal /= 1
print "\n"
while (1) {
  "current balance = "; bal
  "transaction? "; trans = read()
  if (trans == 0) break;
  bal -= trans
  bal /= 1
}
quit

The following is the definition of the recursive factorial function.

define f (x) {
  if (x <= 1) return (1);
  return (f(x-1) * x);
}

Readline and Libedit Options

GNU bc can be compiled (via a configure option) to use the GNU readline input editor library or the BSD libedit library. This allows the user to do more editing of lines before sending them to bc. It also allows for a history of previous lines typed. When this option is selected, bc has one more special variable. This special variable, history is the number of lines of history retained. A value of -1 means that an unlimited number of history lines are retained. This is the default value. Setting the value of history to a positive number restricts the number of history lines to the number given. The value of 0 disables the history feature. For more information, read the user manuals for the GNU readline, history and BSD libedit libraries. One can not enable both readline and libedit at the same time.

GNU bc and Other Implementations

This version of bc was implemented from the POSIX P1003.2/D11 draft and contains several differences and extensions relative to the draft and traditional implementations. It is not implemented in the traditional way using dc. This version is a single process which parses and runs a byte code translation of the program. There is an "undocumented" option (-c) that causes the program to output the byte code to the standard output instead of running it. It was mainly used for debugging the parser and preparing the math library.

A major source of differences is extensions, where a feature is extended to add more functionality and additions, where new features are added. The following is the list of differences and extensions.

LANG environment
This version does not conform to the POSIX standard in the processing of the LANG environment variable and all environment variables starting with LC_.
names
Traditional and POSIX bc have single letter names for functions, variables and arrays. They have been extended to be multi-character names that start with a letter and may contain letters, numbers and the underscore character.
Strings
Strings are not allowed to contain NUL characters. POSIX says all characters must be included in strings.
last
POSIX bc does not have a \fBlast variable. Some implementations of bc use the period (.) in a similar way.
comparisons
POSIX bc allows comparisons only in the if statement, the while statement, and the second expression of the for statement. Also, only one relational operation is allowed in each of those statements.
if statement, else clause
POSIX bc does not have an else clause.
for statement
POSIX bc requires all expressions to be present in the for statement.
&&, ||, !
POSIX bc does not have the logical operators.
read function
POSIX bc does not have a read function.
print statement
POSIX bc does not have a print statement.
continue statement
POSIX bc does not have a continue statement.
array parameters
POSIX bc does not (currently) support array parameters in full. The POSIX grammar allows for arrays in function definitions, but does not provide a method to specify an array as an actual parameter. (This is most likely an oversight in the grammar.) Traditional implementations of bc have only call by value array parameters.
function format
POSIX bc requires the opening brace on the same line as the define key word and the auto statement on the next line.
=+, =-, =*, =/, =%, =^
POSIX bc does not require these "old style" assignment operators to be defined. This version may allow these "old style" assignments. Use the limits statement to see if the installed version supports them. If it does support the "old style" assignment operators, the statement "a =- 1" will decrement a by 1 instead of setting a to the value -1.
spaces in numbers
Other implementations of bc allow spaces in numbers. For example, "x=1 3" would assign the value 13 to the variable x. The same statement would cause a syntax error in this version of bc.
errors and execution
This implementation varies from other implementations in terms of what code will be executed when syntax and other errors are found in the program. If a syntax error is found in a function definition, error recovery tries to find the beginning of a statement and continue to parse the function. Once a syntax error is found in the function, the function will not be callable and becomes undefined. Syntax errors in the interactive execution code will invalidate the current execution block. The execution block is terminated by an end of line that appears after a complete sequence of statements. For example,
a = 1
b = 2
has two execution blocks and
{ a = 1
  b = 2 }
has one execution block. Any runtime error will terminate the execution of the current execution block. A runtime warning will not terminate the current execution block.
Interrupts
During an interactive session, the SIGINT signal (usually generated by the control-C character from the terminal) will cause execution of the current execution block to be interrupted. It will display a "runtime" error indicating which function was interrupted. After all runtime structures have been cleaned up, a message will be printed to notify the user that bc is ready for more input. All previously defined functions remain defined and the value of all non-auto variables are the value at the point of interruption. All auto variables and function parameters are removed during the clean up process. During a non-interactive session, the SIGINT signal will terminate the entire run of bc.

Limits

The following are the limits currently in place for this bc processor. Some of them may have been changed by an installation. Use the limits statement to see the actual values.

BC_BASE_MAX
The maximum output base is currently set at 999. The maximum input base is 16.
BC_DIM_MAX
This is currently an arbitrary limit of 65535 as distributed. Your installation may be different.
BC_SCALE_MAX
The number of digits after the decimal point is limited to INT_MAX digits. Also, the number of digits before the decimal point is limited to INT_MAX digits.
BC_STRING_MAX
The limit on the number of characters in a string is INT_MAX characters.
exponent
The value of the exponent in the raise operation (^) is limited to LONG_MAX.
multiply
The multiply routine may yield incorrect results if a number has more than LONG_MAX / 90 total digits. For 32 bit longs, this number is 23,860,929 digits.
variable names
The current limit on the number of unique names is 32767 for each of simple variables, arrays and functions.

Environment Variables

The following environment variables are processed by bc:

POSIXLY_CORRECT
This is the same as the -s option (see section Command Line Options).
BC_ENV_ARGS
This is another mechanism to get arguments to bc. The format is the same as the command line arguments. These arguments are processed first, so any files listed in the environent arguments are processed before any command line argument files. This allows the user to set up "standard" options and files to be processed at every invocation of bc. The files in the environment variables would typically contain function definitions for functions the user wants defined every time bc is run.
BC_LINE_LENGTH
This should be an integer specifing the number of characters in an output line for numbers. This includes the backslash and newline characters for long numbers.

This document was generated on 20 March 2001 using texi2html 1.56k.


LIB BFD, the Binary File Descriptor Library

First Edition--BFD version < 3.0

April 1991

{Steve Chamberlain}
{Cygnus Support}

Table of Contents

  • Introduction
    • History
    • How To Use BFD
    • What BFD Version 2 Can Do
      • Information Loss
      • The BFD canonical object-file format
  • BFD front end
    • typedef bfd
    • Error reporting
      • Type bfd_error_type
        • bfd_get_error
        • bfd_set_error
        • bfd_errmsg
        • bfd_perror
      • BFD error handler
        • bfd_set_error_handler
        • bfd_set_error_program_name
        • bfd_get_error_handler
    • Symbols
        • bfd_get_reloc_upper_bound
        • bfd_canonicalize_reloc
        • bfd_set_reloc
        • bfd_set_file_flags
        • bfd_set_start_address
        • bfd_get_mtime
        • bfd_get_size
        • bfd_get_gp_size
        • bfd_set_gp_size
        • bfd_scan_vma
        • bfd_copy_private_bfd_data
        • bfd_merge_private_bfd_data
        • bfd_set_private_flags
        • stuff
    • Memory usage
    • Initialization
        • bfd_init
    • Sections
      • Section input
      • Section output
      • Link orders
      • typedef asection
      • Section prototypes
        • bfd_get_section_by_name
        • bfd_make_section_old_way
        • bfd_make_section_anyway
        • bfd_make_section
        • bfd_set_section_flags
        • bfd_map_over_sections
        • bfd_set_section_size
        • bfd_set_section_contents
        • bfd_get_section_contents
        • bfd_copy_private_section_data
    • Symbols
      • Reading symbols
      • Writing symbols
      • Mini Symbols
      • typedef asymbol
      • Symbol handling functions
        • bfd_get_symtab_upper_bound
        • bfd_is_local_label
        • bfd_is_local_label_name
        • bfd_canonicalize_symtab
        • bfd_set_symtab
        • bfd_print_symbol_vandf
        • bfd_make_empty_symbol
        • bfd_make_debug_symbol
        • bfd_decode_symclass
        • bfd_symbol_info
        • bfd_copy_private_symbol_data
    • Archives
        • bfd_get_next_mapent
        • bfd_set_archive_head
        • bfd_openr_next_archived_file
    • File formats
        • bfd_check_format
        • bfd_check_format_matches
        • bfd_set_format
        • bfd_format_string
    • Relocations
      • typedef arelent
        • enum complain_overflow
        • reloc_howto_type
        • The HOWTO Macro
        • bfd_get_reloc_size
        • arelent_chain
        • bfd_check_overflow
        • bfd_perform_relocation
        • bfd_install_relocation
    • The howto manager
        • bfd_reloc_code_type
        • bfd_reloc_type_lookup
        • bfd_default_reloc_type_lookup
        • bfd_get_reloc_code_name
        • bfd_generic_relax_section
        • bfd_generic_get_relocated_section_contents
    • Core files
        • bfd_core_file_failing_command
        • bfd_core_file_failing_signal
        • core_file_matches_executable_p
    • Targets
      • bfd_target
        • bfd_set_default_target
        • bfd_find_target
        • bfd_target_list
    • Architectures
      • bfd_architecture
      • bfd_arch_info
        • bfd_printable_name
        • bfd_scan_arch
        • bfd_arch_list
        • bfd_arch_get_compatible
        • bfd_default_arch_struct
        • bfd_set_arch_info
        • bfd_default_set_arch_mach
        • bfd_get_arch
        • bfd_get_mach
        • bfd_arch_bits_per_byte
        • bfd_arch_bits_per_address
        • bfd_default_compatible
        • bfd_default_scan
        • bfd_get_arch_info
        • bfd_lookup_arch
        • bfd_printable_arch_mach
    • Opening and closing BFDs
        • bfd_openr
        • bfd_fdopenr
        • bfd_openstreamr
        • bfd_openw
        • bfd_close
        • bfd_close_all_done
        • bfd_create
        • bfd_alloc
    • Internal functions
        • bfd_write_bigendian_4byte_int
        • bfd_put_size
        • bfd_get_size
        • bfd_h_put_size
        • bfd_log2
    • File caching
        • BFD_CACHE_MAX_OPEN macro
        • bfd_last_cache
        • bfd_cache_lookup
        • bfd_cache_init
        • bfd_cache_close
        • bfd_open_file
        • bfd_cache_lookup_worker
    • Linker Functions
      • Creating a linker hash table
      • Adding symbols to the hash table
        • Differing file formats
        • Adding symbols from an object file
        • Adding symbols from an archive
      • Performing the final link
        • Information provided by the linker
        • Relocating the section contents
        • Writing the symbol table
        • bfd_link_split_section
    • Hash Tables
      • Creating and freeing a hash table
      • Looking up or entering a string
      • Traversing a hash table
      • Deriving a new hash table type
        • Define the derived structures
        • Write the derived creation routine
        • Write other derived routines
  • BFD back ends
    • a.out backends
      • Relocations
      • Internal entry points
        • aout_size_swap_exec_header_in
        • aout_size_swap_exec_header_out
        • aout_size_some_aout_object_p
        • aout_size_mkobject
        • aout_size_machine_type
        • aout_size_set_arch_mach
        • aout_size_new_section_hook
    • coff backends
      • Porting to a new version of coff
      • How the coff backend works
        • File layout
        • Bit twiddling
        • Symbol reading
        • Symbol writing
        • coff_symbol_type
        • bfd_coff_backend_data
        • Writing relocations
        • Reading linenumbers
        • Reading relocations
    • ELF backends
        • bfd_elf_find_section
  • Index

Introduction

BFD is a package which allows applications to use the same routines to operate on object files whatever the object file format. A new object file format can be supported simply by creating a new BFD back end and adding it to the library.

BFD is split into two parts: the front end, and the back ends (one for each object file format).

  • The front end of BFD provides the interface to the user. It manages memory and various canonical data structures. The front end also decides which back end to use and when to call back end routines.
  • The back ends provide BFD its view of the real world. Each back end provides a set of calls which the BFD front end can use to maintain its canonical form. The back ends also may keep around information for their own use, for greater efficiency.

History

One spur behind BFD was the desire, on the part of the GNU 960 team at Intel Oregon, for interoperability of applications on their COFF and b.out file formats. Cygnus was providing GNU support for the team, and was contracted to provide the required functionality.

The name came from a conversation David Wallace was having with Richard Stallman about the library: RMS said that it would be quite hard--David said "BFD". Stallman was right, but the name stuck.

At the same time, Ready Systems wanted much the same thing, but for different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k coff.

BFD was first implemented by members of Cygnus Support; Steve Chamberlain (sac@cygnus.com), John Gilmore (gnu@cygnus.com), K. Richard Pixley (rich@cygnus.com) and David Henkel-Wallace (gumby@cygnus.com).

How To Use BFD

To use the library, include `bfd.h' and link with `libbfd.a'.

BFD provides a common interface to the parts of an object file for a calling application.

When an application sucessfully opens a target file (object, archive, or whatever), a pointer to an internal structure is returned. This pointer points to a structure called bfd, described in `bfd.h'. Our convention is to call this pointer a BFD, and instances of it within code abfd. All operations on the target object file are applied as methods to the BFD. The mapping is defined within bfd.h in a set of macros, all beginning with `bfd_' to reduce namespace pollution.

For example, this sequence does what you would probably expect: return the number of sections in an object file attached to a BFD abfd.

#include "bfd.h"

unsigned int number_of_sections(abfd)
bfd *abfd;
{
  return bfd_count_sections(abfd);
}

The abstraction used within BFD is that an object file has:

  • a header,
  • a number of sections containing raw data (see section Sections),
  • a set of relocations (see section Relocations), and
  • some symbol information (see section Symbols).

Also, BFDs opened for archives have the additional attribute of an index and contain subordinate BFDs. This approach is fine for a.out and coff, but loses efficiency when applied to formats such as S-records and IEEE-695.

What BFD Version 2 Can Do

When an object file is opened, BFD subroutines automatically determine the format of the input object file. They then build a descriptor in memory with pointers to routines that will be used to access elements of the object file's data structures.

As different information from the the object files is required, BFD reads from different sections of the file and processes them. For example, a very common operation for the linker is processing symbol tables. Each BFD back end provides a routine for converting between the object file's representation of symbols and an internal canonical format. When the linker asks for the symbol table of an object file, it calls through a memory pointer to the routine from the relevant BFD back end which reads and converts the table into a canonical form. The linker then operates upon the canonical form. When the link is finished and the linker writes the output file's symbol table, another BFD back end routine is called to take the newly created symbol table and convert it into the chosen output format.

Information Loss

Information can be lost during output. The output formats supported by BFD do not provide identical facilities, and information which can be described in one form has nowhere to go in another format. One example of this is alignment information in b.out. There is nowhere in an a.out format file to store alignment information on the contained data, so when a file is linked from b.out and an a.out image is produced, alignment information will not propagate to the output file. (The linker will still use the alignment information internally, so the link is performed correctly).

Another example is COFF section names. COFF files may contain an unlimited number of sections, each one with a textual section name. If the target of the link is a format which does not have many sections (e.g., a.out) or has sections without names (e.g., the Oasys format), the link cannot be done simply. You can circumvent this problem by describing the desired input-to-output section mapping with the linker command language.

Information can be lost during canonicalization. The BFD internal canonical form of the external formats is not exhaustive; there are structures in input formats for which there is no direct representation internally. This means that the BFD back ends cannot maintain all possible data richness through the transformation between external to internal and back to external formats.

This limitation is only a problem when an application reads one format and writes another. Each BFD back end is responsible for maintaining as much data as possible, and the internal BFD canonical form has structures which are opaque to the BFD core, and exported only to the back ends. When a file is read in one format, the canonical form is generated for BFD and the application. At the same time, the back end saves away any information which may otherwise be lost. If the data is then written back in the same format, the back end routine will be able to use the canonical form provided by the BFD core as well as the information it prepared earlier. Since there is a great deal of commonality between back ends, there is no information lost when linking or copying big endian COFF to little endian COFF, or a.out to b.out. When a mixture of formats is linked, the information is only lost from the files whose format differs from the destination.

The BFD canonical object-file format

The greatest potential for loss of information occurs when there is the least overlap between the information provided by the source format, that stored by the canonical format, and that needed by the destination format. A brief description of the canonical form may help you understand which kinds of data you can count on preserving across conversions.

files
Information stored on a per-file basis includes target machine architecture, particular implementation format type, a demand pageable bit, and a write protected bit. Information like Unix magic numbers is not stored here--only the magic numbers' meaning, so a ZMAGIC file would have both the demand pageable bit and the write protected text bit set. The byte order of the target is stored on a per-file basis, so that big- and little-endian object files may be used with one another.
sections
Each section in the input file contains the name of the section, the section's original address in the object file, size and alignment information, various flags, and pointers into other BFD data structures.
symbols
Each symbol contains a pointer to the information for the object file which originally defined it, its name, its value, and various flag bits. When a BFD back end reads in a symbol table, it relocates all symbols to make them relative to the base of the section where they were defined. Doing this ensures that each symbol points to its containing section. Each symbol also has a varying amount of hidden private data for the BFD back end. Since the symbol points to the original file, the private data format for that symbol is accessible. ld can operate on a collection of symbols of wildly different formats without problems. Normal global and simple local symbols are maintained on output, so an output file (no matter its format) will retain symbols pointing to functions and to global, static, and common variables. Some symbol information is not worth retaining; in a.out, type information is stored in the symbol table as long symbol names. This information would be useless to most COFF debuggers; the linker has command line switches to allow users to throw it away. There is one word of type information within the symbol, so if the format supports symbol type information within symbols (for example, COFF, IEEE, Oasys) and the type is simple enough to fit within one word (nearly everything but aggregates), the information will be preserved.
relocation level
Each canonical BFD relocation record contains a pointer to the symbol to relocate to, the offset of the data to relocate, the section the data is in, and a pointer to a relocation type descriptor. Relocation is performed by passing messages through the relocation type descriptor and the symbol pointer. Therefore, relocations can be performed on output data using a relocation method that is only available in one of the input formats. For instance, Oasys provides a byte relocation format. A relocation record requesting this relocation type would point indirectly to a routine to perform this, so the relocation may be performed on a byte being written to a 68k COFF file, even though 68k COFF has no such relocation type.
line numbers
Object formats can contain, for debugging purposes, some form of mapping between symbols, source line numbers, and addresses in the output file. These addresses have to be relocated along with the symbol information. Each symbol with an associated list of line number records points to the first record of the list. The head of a line number list consists of a pointer to the symbol, which allows finding out the address of the function whose line number is being described. The rest of the list is made up of pairs: offsets into the section and line numbers. Any format which can simply derive this information can pass it successfully between formats (COFF, IEEE and Oasys).

BFD front end

typedef bfd

A BFD has type bfd; objects of this type are the cornerstone of any application using BFD. Using BFD consists of making references though the BFD and to data in the BFD.

Here is the structure that defines the type bfd. It contains the major data about the file and pointers to the rest of the data.

struct _bfd
{
    /* The filename the application opened the BFD with.  */
    CONST char *filename;

    /* A pointer to the target jump table.             */
    const struct bfd_target *xvec;

    /* To avoid dragging too many header files into every file that
       includes `bfd.h', IOSTREAM has been declared as a "char
       *", and MTIME as a "long".  Their correct types, to which they
       are cast when used, are "FILE *" and "time_t".    The iostream
       is the result of an fopen on the filename.  However, if the
       BFD_IN_MEMORY flag is set, then iostream is actually a pointer
       to a bfd_in_memory struct.  */
    PTR iostream;

    /* Is the file descriptor being cached?  That is, can it be closed as
       needed, and re-opened when accessed later?  */

    boolean cacheable;

    /* Marks whether there was a default target specified when the
       BFD was opened. This is used to select which matching algorithm
       to use to choose the back end. */

    boolean target_defaulted;

    /* The caching routines use these to maintain a
       least-recently-used list of BFDs */

    struct _bfd *lru_prev, *lru_next;

    /* When a file is closed by the caching routines, BFD retains
       state information on the file here: */

    file_ptr where;

    /* and here: (``once'' means at least once) */

    boolean opened_once;

    /* Set if we have a locally maintained mtime value, rather than
       getting it from the file each time: */

    boolean mtime_set;

    /* File modified time, if mtime_set is true: */

    long mtime;

    /* Reserved for an unimplemented file locking extension.*/

    int ifd;

    /* The format which belongs to the BFD. (object, core, etc.) */

    bfd_format format;

    /* The direction the BFD was opened with*/

    enum bfd_direction {no_direction = 0,
                        read_direction = 1,
                        write_direction = 2,
                        both_direction = 3} direction;

    /* Format_specific flags*/

    flagword flags;

    /* Currently my_archive is tested before adding origin to
       anything. I believe that this can become always an add of
       origin, with origin set to 0 for non archive files.   */

    file_ptr origin;

    /* Remember when output has begun, to stop strange things
       from happening. */
    boolean output_has_begun;

    /* Pointer to linked list of sections*/
    struct sec  *sections;

    /* The number of sections */
    unsigned int section_count;

    /* Stuff only useful for object files:
       The start address. */
    bfd_vma start_address;

    /* Used for input and output*/
    unsigned int symcount;

    /* Symbol table for output BFD (with symcount entries) */
    struct symbol_cache_entry  **outsymbols;

    /* Pointer to structure which contains architecture information*/
    const struct bfd_arch_info *arch_info;

    /* Stuff only useful for archives:*/
    PTR arelt_data;
    struct _bfd *my_archive;     /* The containing archive BFD.  */
    struct _bfd *next;           /* The next BFD in the archive.  */
    struct _bfd *archive_head;   /* The first BFD in the archive.  */
    boolean has_armap;

    /* A chain of BFD structures involved in a link.  */
    struct _bfd *link_next;

    /* A field used by _bfd_generic_link_add_archive_symbols.  This will
       be used only for archive elements.  */
    int archive_pass;

    /* Used by the back end to hold private data. */

    union
      {
      struct aout_data_struct *aout_data;
      struct artdata *aout_ar_data;
      struct _oasys_data *oasys_obj_data;
      struct _oasys_ar_data *oasys_ar_data;
      struct coff_tdata *coff_obj_data;
      struct pe_tdata *pe_obj_data;
      struct xcoff_tdata *xcoff_obj_data;
      struct ecoff_tdata *ecoff_obj_data;
      struct ieee_data_struct *ieee_data;
      struct ieee_ar_data_struct *ieee_ar_data;
      struct srec_data_struct *srec_data;
      struct ihex_data_struct *ihex_data;
      struct tekhex_data_struct *tekhex_data;
      struct elf_obj_tdata *elf_obj_data;
      struct nlm_obj_tdata *nlm_obj_data;
      struct bout_data_struct *bout_data;
      struct sun_core_struct *sun_core_data;
      struct trad_core_struct *trad_core_data;
      struct som_data_struct *som_data;
      struct hpux_core_struct *hpux_core_data;
      struct hppabsd_core_struct *hppabsd_core_data;
      struct sgi_core_struct *sgi_core_data;
      struct lynx_core_struct *lynx_core_data;
      struct osf_core_struct *osf_core_data;
      struct cisco_core_struct *cisco_core_data;
      struct versados_data_struct *versados_data;
      struct netbsd_core_struct *netbsd_core_data;
      PTR any;
      } tdata;

    /* Used by the application to hold private data*/
    PTR usrdata;

  /* Where all the allocated stuff under this BFD goes.  This is a
     struct objalloc *, but we use PTR to avoid requiring the inclusion of
     objalloc.h.  */
    PTR memory;
};

Error reporting

Most BFD functions return nonzero on success (check their individual documentation for precise semantics). On an error, they call bfd_set_error to set an error condition that callers can check by calling bfd_get_error. If that returns bfd_error_system_call, then check errno.

The easiest way to report a BFD error to the user is to use bfd_perror.

Type bfd_error_type

The values returned by bfd_get_error are defined by the enumerated type bfd_error_type.

typedef enum bfd_error
{
  bfd_error_no_error = 0,
  bfd_error_system_call,
  bfd_error_invalid_target,
  bfd_error_wrong_format,
  bfd_error_invalid_operation,
  bfd_error_no_memory,
  bfd_error_no_symbols,
  bfd_error_no_armap,
  bfd_error_no_more_archived_files,
  bfd_error_malformed_archive,
  bfd_error_file_not_recognized,
  bfd_error_file_ambiguously_recognized,
  bfd_error_no_contents,
  bfd_error_nonrepresentable_section,
  bfd_error_no_debug_section,
  bfd_error_bad_value,
  bfd_error_file_truncated,
  bfd_error_file_too_big,
  bfd_error_invalid_error_code
} bfd_error_type;

bfd_get_error

Synopsis

bfd_error_type bfd_get_error (void);

Description
Return the current BFD error condition.

bfd_set_error

Synopsis

void bfd_set_error (bfd_error_type error_tag);

Description
Set the BFD error condition to be error_tag.

bfd_errmsg

Synopsis

CONST char *bfd_errmsg (bfd_error_type error_tag);

Description
Return a string describing the error error_tag, or the system error if error_tag is bfd_error_system_call.

bfd_perror

Synopsis

void bfd_perror (CONST char *message);

Description
Print to the standard error stream a string describing the last BFD error that occurred, or the last system error if the last BFD error was a system call failure. If message is non-NULL and non-empty, the error string printed is preceded by message, a colon, and a space. It is followed by a newline.

BFD error handler

Some BFD functions want to print messages describing the problem. They call a BFD error handler function. This function may be overriden by the program.

The BFD error handler acts like printf.

typedef void (*bfd_error_handler_type) PARAMS ((const char *, ...));

bfd_set_error_handler

Synopsis

bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type);

Description
Set the BFD error handler function. Returns the previous function.

bfd_set_error_program_name

Synopsis

void bfd_set_error_program_name (const char *);

Description
Set the program name to use when printing a BFD error. This is printed before the error message followed by a colon and space. The string must not be changed after it is passed to this function.

bfd_get_error_handler

Synopsis

bfd_error_handler_type bfd_get_error_handler (void);

Description
Return the BFD error handler function.

Symbols

bfd_get_reloc_upper_bound

Synopsis

long bfd_get_reloc_upper_bound(bfd *abfd, asection *sect);

Description
Return the number of bytes required to store the relocation information associated with section sect attached to bfd abfd. If an error occurs, return -1.

bfd_canonicalize_reloc

Synopsis

long bfd_canonicalize_reloc
   (bfd *abfd,
    asection *sec,
    arelent **loc,
    asymbol **syms);

Description
Call the back end associated with the open BFD abfd and translate the external form of the relocation information attached to sec into the internal canonical form. Place the table into memory at loc, which has been preallocated, usually by a call to bfd_get_reloc_upper_bound. Returns the number of relocs, or -1 on error.

The syms table is also needed for horrible internal magic reasons.

bfd_set_reloc

Synopsis

void bfd_set_reloc
   (bfd *abfd, asection *sec, arelent **rel, unsigned int count)

Description
Set the relocation pointer and count within section sec to the values rel and count. The argument abfd is ignored.

bfd_set_file_flags

Synopsis

boolean bfd_set_file_flags(bfd *abfd, flagword flags);

Description
Set the flag word in the BFD abfd to the value flags.

Possible errors are:

  • bfd_error_wrong_format - The target bfd was not of object format.
  • bfd_error_invalid_operation - The target bfd was open for reading.
  • bfd_error_invalid_operation - The flag word contained a bit which was not applicable to the type of file. E.g., an attempt was made to set the D_PAGED bit on a BFD format which does not support demand paging.

bfd_set_start_address

Synopsis

boolean bfd_set_start_address(bfd *abfd, bfd_vma vma);

Description
Make vma the entry point of output BFD abfd.

Returns
Returns true on success, false otherwise.

bfd_get_mtime

Synopsis

long bfd_get_mtime(bfd *abfd);

Description
Return the file modification time (as read from the file system, or from the archive header for archive members).

bfd_get_size

Synopsis

long bfd_get_size(bfd *abfd);

Description
Return the file size (as read from file system) for the file associated with BFD abfd.

The initial motivation for, and use of, this routine is not so we can get the exact size of the object the BFD applies to, since that might not be generally possible (archive members for example). It would be ideal if someone could eventually modify it so that such results were guaranteed.

Instead, we want to ask questions like "is this NNN byte sized object I'm about to try read from file offset YYY reasonable?" As as example of where we might do this, some object formats use string tables for which the first sizeof(long) bytes of the table contain the size of the table itself, including the size bytes. If an application tries to read what it thinks is one of these string tables, without some way to validate the size, and for some reason the size is wrong (byte swapping error, wrong location for the string table, etc.), the only clue is likely to be a read error when it tries to read the table, or a "virtual memory exhausted" error when it tries to allocate 15 bazillon bytes of space for the 15 bazillon byte table it is about to read. This function at least allows us to answer the quesion, "is the size reasonable?".

bfd_get_gp_size

Synopsis

int bfd_get_gp_size(bfd *abfd);

Description
Return the maximum size of objects to be optimized using the GP register under MIPS ECOFF. This is typically set by the -G argument to the compiler, assembler or linker.

bfd_set_gp_size

Synopsis

void bfd_set_gp_size(bfd *abfd, int i);

Description
Set the maximum size of objects to be optimized using the GP register under ECOFF or MIPS ELF. This is typically set by the -G argument to the compiler, assembler or linker.

bfd_scan_vma

Synopsis

bfd_vma bfd_scan_vma(CONST char *string, CONST char **end, int base);

Description
Convert, like strtoul, a numerical expression string into a bfd_vma integer, and return that integer. (Though without as many bells and whistles as strtoul.) The expression is assumed to be unsigned (i.e., positive). If given a base, it is used as the base for conversion. A base of 0 causes the function to interpret the string in hex if a leading "0x" or "0X" is found, otherwise in octal if a leading zero is found, otherwise in decimal.

Overflow is not detected.

bfd_copy_private_bfd_data

Synopsis

boolean bfd_copy_private_bfd_data(bfd *ibfd, bfd *obfd);

Description
Copy private BFD information from the BFD ibfd to the the BFD obfd. Return true on success, false on error. Possible error returns are:

  • bfd_error_no_memory - Not enough memory exists to create private data for obfd.
#define bfd_copy_private_bfd_data(ibfd, obfd) \
     BFD_SEND (obfd, _bfd_copy_private_bfd_data, \
               (ibfd, obfd))

bfd_merge_private_bfd_data

Synopsis

boolean bfd_merge_private_bfd_data(bfd *ibfd, bfd *obfd);

Description
Merge private BFD information from the BFD ibfd to the the output file BFD obfd when linking. Return true on success, false on error. Possible error returns are:

  • bfd_error_no_memory - Not enough memory exists to create private data for obfd.
#define bfd_merge_private_bfd_data(ibfd, obfd) \
     BFD_SEND (obfd, _bfd_merge_private_bfd_data, \
               (ibfd, obfd))

bfd_set_private_flags

Synopsis

boolean bfd_set_private_flags(bfd *abfd, flagword flags);

Description
Set private BFD flag information in the BFD abfd. Return true on success, false on error. Possible error returns are:

  • bfd_error_no_memory - Not enough memory exists to create private data for obfd.
#define bfd_set_private_flags(abfd, flags) \
     BFD_SEND (abfd, _bfd_set_private_flags, \
               (abfd, flags))

stuff

Description
Stuff which should be documented:

#define bfd_sizeof_headers(abfd, reloc) \
     BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc))

#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \
     BFD_SEND (abfd, _bfd_find_nearest_line,  (abfd, sec, syms, off, file, func, line))

        /* Do these three do anything useful at all, for any back end?  */
#define bfd_debug_info_start(abfd) \
        BFD_SEND (abfd, _bfd_debug_info_start, (abfd))

#define bfd_debug_info_end(abfd) \
        BFD_SEND (abfd, _bfd_debug_info_end, (abfd))

#define bfd_debug_info_accumulate(abfd, section) \
        BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section))

#define bfd_stat_arch_elt(abfd, stat) \
        BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat))

#define bfd_update_armap_timestamp(abfd) \
        BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd))

#define bfd_set_arch_mach(abfd, arch, mach)\
        BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach))

#define bfd_relax_section(abfd, section, link_info, again) \
       BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again))

#define bfd_link_hash_table_create(abfd) \
       BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd))

#define bfd_link_add_symbols(abfd, info) \
       BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info))

#define bfd_final_link(abfd, info) \
       BFD_SEND (abfd, _bfd_final_link, (abfd, info))

#define bfd_free_cached_info(abfd) \
       BFD_SEND (abfd, _bfd_free_cached_info, (abfd))

#define bfd_get_dynamic_symtab_upper_bound(abfd) \
       BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd))

#define bfd_print_private_bfd_data(abfd, file)\
       BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file))

#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \
       BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols))

#define bfd_get_dynamic_reloc_upper_bound(abfd) \
       BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd))

#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \
       BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms))

extern bfd_byte *bfd_get_relocated_section_contents
       PARAMS ((bfd *, struct bfd_link_info *,
                 struct bfd_link_order *, bfd_byte *,
                 boolean, asymbol **));

Memory usage

BFD keeps all of its internal structures in obstacks. There is one obstack per open BFD file, into which the current state is stored. When a BFD is closed, the obstack is deleted, and so everything which has been allocated by BFD for the closing file is thrown away.

BFD does not free anything created by an application, but pointers into bfd structures become invalid on a bfd_close; for example, after a bfd_close the vector passed to bfd_canonicalize_symtab is still around, since it has been allocated by the application, but the data that it pointed to are lost.

The general rule is to not close a BFD until all operations dependent upon data from the BFD have been completed, or all the data from within the file has been copied. To help with the management of memory, there is a function (bfd_alloc_size) which returns the number of bytes in obstacks associated with the supplied BFD. This could be used to select the greediest open BFD, close it to reclaim the memory, perform some operation and reopen the BFD again, to get a fresh copy of the data structures.

Initialization

These are the functions that handle initializing a BFD.

bfd_init

Synopsis

void bfd_init(void);

Description
This routine must be called before any other BFD function to initialize magical internal data structures.

Sections

The raw data contained within a BFD is maintained through the section abstraction. A single BFD may have any number of sections. It keeps hold of them by pointing to the first; each one points to the next in the list.

Sections are supported in BFD in section.c.

Section input

When a BFD is opened for reading, the section structures are created and attached to the BFD.

Each section has a name which describes the section in the outside world--for example, a.out would contain at least three sections, called .text, .data and .bss.

Names need not be unique; for example a COFF file may have several sections named .data.

Sometimes a BFD will contain more than the "natural" number of sections. A back end may attach other sections containing constructor data, or an application may add a section (using bfd_make_section) to the sections attached to an already open BFD. For example, the linker creates an extra section COMMON for each input file's BFD to hold information about common storage.

The raw data is not necessarily read in when the section descriptor is created. Some targets may leave the data in place until a bfd_get_section_contents call is made. Other back ends may read in all the data at once. For example, an S-record file has to be read once to determine the size of the data. An IEEE-695 file doesn't contain raw data in sections, but data and relocation expressions intermixed, so the data area has to be parsed to get out the data and relocations.

Section output

To write a new object style BFD, the various sections to be written have to be created. They are attached to the BFD in the same way as input sections; data is written to the sections using bfd_set_section_contents.

Any program that creates or combines sections (e.g., the assembler and linker) must use the asection fields output_section and output_offset to indicate the file sections to which each section must be written. (If the section is being created from scratch, output_section should probably point to the section itself and output_offset should probably be zero.)

The data to be written comes from input sections attached (via output_section pointers) to the output sections. The output section structure can be considered a filter for the input section: the output section determines the vma of the output data and the name, but the input section determines the offset into the output section of the data to be written.

E.g., to create a section "O", starting at 0x100, 0x123 long, containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and "B" at offset 0x20 (i.e., at vma 0x120) the asection structures would look like:

   section name          "A"
     output_offset   0x00
     size            0x20
     output_section ----------->  section name    "O"
                             |    vma             0x100
   section name          "B" |    size            0x123
     output_offset   0x20    |
     size            0x103   |
     output_section  --------|

Link orders

The data within a section is stored in a link_order. These are much like the fixups in gas. The link_order abstraction allows a section to grow and shrink within itself.

A link_order knows how big it is, and which is the next link_order and where the raw data for it is; it also points to a list of relocations which apply to it.

The link_order is used by the linker to perform relaxing on final code. The compiler creates code which is as big as necessary to make it work without relaxing, and the user can select whether to relax. Sometimes relaxing takes a lot of time. The linker runs around the relocations to see if any are attached to data which can be shrunk, if so it does it on a link_order by link_order basis.

typedef asection

Here is the section structure:

typedef struct sec
{
        /* The name of the section; the name isn't a copy, the pointer is
        the same as that passed to bfd_make_section. */

    CONST char *name;

        /* Which section is it; 0..nth.      */

   int index;

        /* The next section in the list belonging to the BFD, or NULL. */

    struct sec *next;

        /* The field flags contains attributes of the section. Some
           flags are read in from the object file, and some are
           synthesized from other information.  */

    flagword flags;

#define SEC_NO_FLAGS   0x000

        /* Tells the OS to allocate space for this section when loading.
           This is clear for a section containing debug information
           only. */
#define SEC_ALLOC      0x001

        /* Tells the OS to load the section from the file when loading.
           This is clear for a .bss section. */
#define SEC_LOAD       0x002

        /* The section contains data still to be relocated, so there is
           some relocation information too. */
#define SEC_RELOC      0x004

#if 0   /* Obsolete ? */
#define SEC_BALIGN     0x008
#endif

        /* A signal to the OS that the section contains read only
          data. */
#define SEC_READONLY   0x010

        /* The section contains code only. */
#define SEC_CODE       0x020

        /* The section contains data only. */
#define SEC_DATA       0x040

        /* The section will reside in ROM. */
#define SEC_ROM        0x080

        /* The section contains constructor information. This section
           type is used by the linker to create lists of constructors and
           destructors used by g++. When a back end sees a symbol
           which should be used in a constructor list, it creates a new
           section for the type of name (e.g., __CTOR_LIST__), attaches
           the symbol to it, and builds a relocation. To build the lists
           of constructors, all the linker has to do is catenate all the
           sections called __CTOR_LIST__ and relocate the data
           contained within - exactly the operations it would peform on
           standard data. */
#define SEC_CONSTRUCTOR 0x100

        /* The section is a constuctor, and should be placed at the
          end of the text, data, or bss section(?). */
#define SEC_CONSTRUCTOR_TEXT 0x1100
#define SEC_CONSTRUCTOR_DATA 0x2100
#define SEC_CONSTRUCTOR_BSS  0x3100

        /* The section has contents - a data section could be
           SEC_ALLOC | SEC_HAS_CONTENTS; a debug section could be
           SEC_HAS_CONTENTS */
#define SEC_HAS_CONTENTS 0x200

        /* An instruction to the linker to not output the section
           even if it has information which would normally be written. */
#define SEC_NEVER_LOAD 0x400

        /* The section is a COFF shared library section.  This flag is
           only for the linker.  If this type of section appears in
           the input file, the linker must copy it to the output file
           without changing the vma or size.  FIXME: Although this
           was originally intended to be general, it really is COFF
           specific (and the flag was renamed to indicate this).  It
           might be cleaner to have some more general mechanism to
           allow the back end to control what the linker does with
           sections. */
#define SEC_COFF_SHARED_LIBRARY 0x800

        /* The section contains common symbols (symbols may be defined
           multiple times, the value of a symbol is the amount of
           space it requires, and the largest symbol value is the one
           used).  Most targets have exactly one of these (which we
           translate to bfd_com_section_ptr), but ECOFF has two. */
#define SEC_IS_COMMON 0x8000

        /* The section contains only debugging information.  For
           example, this is set for ELF .debug and .stab sections.
           strip tests this flag to see if a section can be
           discarded. */
#define SEC_DEBUGGING 0x10000

        /* The contents of this section are held in memory pointed to
           by the contents field.  This is checked by
           bfd_get_section_contents, and the data is retrieved from
           memory if appropriate.  */
#define SEC_IN_MEMORY 0x20000

        /* The contents of this section are to be excluded by the
           linker for executable and shared objects unless those
           objects are to be further relocated.  */
#define SEC_EXCLUDE 0x40000

       /* The contents of this section are to be sorted by the
          based on the address specified in the associated symbol
          table.  */
#define SEC_SORT_ENTRIES 0x80000

       /* When linking, duplicate sections of the same name should be
          discarded, rather than being combined into a single section as
          is usually done.  This is similar to how common symbols are
          handled.  See SEC_LINK_DUPLICATES below.  */
#define SEC_LINK_ONCE 0x100000

       /* If SEC_LINK_ONCE is set, this bitfield describes how the linker
          should handle duplicate sections.  */
#define SEC_LINK_DUPLICATES 0x600000

       /* This value for SEC_LINK_DUPLICATES means that duplicate
          sections with the same name should simply be discarded. */
#define SEC_LINK_DUPLICATES_DISCARD 0x0

       /* This value for SEC_LINK_DUPLICATES means that the linker
          should warn if there are any duplicate sections, although
          it should still only link one copy.  */
#define SEC_LINK_DUPLICATES_ONE_ONLY 0x200000

       /* This value for SEC_LINK_DUPLICATES means that the linker
          should warn if any duplicate sections are a different size.  */
#define SEC_LINK_DUPLICATES_SAME_SIZE 0x400000

       /* This value for SEC_LINK_DUPLICATES means that the linker
          should warn if any duplicate sections contain different
          contents.  */
#define SEC_LINK_DUPLICATES_SAME_CONTENTS 0x600000

       /* This section was created by the linker as part of dynamic
          relocation or other arcane processing.  It is skipped when
          going through the first-pass output, trusting that someone
          else up the line will take care of it later.  */
#define SEC_LINKER_CREATED 0x800000

       /*  End of section flags.  */

       /* Some internal packed boolean fields.  */

       /* See the vma field.  */
       unsigned int user_set_vma : 1;

       /* Whether relocations have been processed.  */
       unsigned int reloc_done : 1;

       /* A mark flag used by some of the linker backends.  */
       unsigned int linker_mark : 1;

       /* End of internal packed boolean fields.  */

       /*  The virtual memory address of the section - where it will be
           at run time.  The symbols are relocated against this.  The
           user_set_vma flag is maintained by bfd; if it's not set, the
           backend can assign addresses (for example, in a.out, where
           the default address for .data is dependent on the specific
           target and various flags).  */

   bfd_vma vma;

       /*  The load address of the section - where it would be in a
           rom image; really only used for writing section header
           information. */

   bfd_vma lma;

        /* The size of the section in bytes, as it will be output.
           contains a value even if the section has no contents (e.g., the
           size of .bss). This will be filled in after relocation */

   bfd_size_type _cooked_size;

        /* The original size on disk of the section, in bytes.  Normally this
           value is the same as the size, but if some relaxing has
           been done, then this value will be bigger.  */

   bfd_size_type _raw_size;

        /* If this section is going to be output, then this value is the
           offset into the output section of the first byte in the input
           section. E.g., if this was going to start at the 100th byte in
           the output section, this value would be 100. */

   bfd_vma output_offset;

        /* The output section through which to map on output. */

   struct sec *output_section;

        /* The alignment requirement of the section, as an exponent of 2 -
           e.g., 3 aligns to 2^3 (or 8). */

   unsigned int alignment_power;

        /* If an input section, a pointer to a vector of relocation
           records for the data in this section. */

   struct reloc_cache_entry *relocation;

        /* If an output section, a pointer to a vector of pointers to
           relocation records for the data in this section. */

   struct reloc_cache_entry **orelocation;

        /* The number of relocation records in one of the above  */

   unsigned reloc_count;

        /* Information below is back end specific - and not always used
           or updated.  */

        /* File position of section data    */

   file_ptr filepos;

        /* File position of relocation info */

   file_ptr rel_filepos;

        /* File position of line data       */

   file_ptr line_filepos;

        /* Pointer to data for applications */

   PTR userdata;

        /* If the SEC_IN_MEMORY flag is set, this points to the actual
           contents.  */
   unsigned char *contents;

        /* Attached line number information */

   alent *lineno;

        /* Number of line number records   */

   unsigned int lineno_count;

        /* When a section is being output, this value changes as more
           linenumbers are written out */

   file_ptr moving_line_filepos;

        /* What the section number is in the target world  */

   int target_index;

   PTR used_by_bfd;

        /* If this is a constructor section then here is a list of the
           relocations created to relocate items within it. */

   struct relent_chain *constructor_chain;

        /* The BFD which owns the section. */

   bfd *owner;

        /* A symbol which points at this section only */
   struct symbol_cache_entry *symbol;
   struct symbol_cache_entry **symbol_ptr_ptr;

   struct bfd_link_order *link_order_head;
   struct bfd_link_order *link_order_tail;
} asection ;

    /* These sections are global, and are managed by BFD.  The application
       and target back end are not permitted to change the values in
       these sections.  New code should use the section_ptr macros rather
       than referring directly to the const sections.  The const sections
       may eventually vanish.  */
#define BFD_ABS_SECTION_NAME "*ABS*"
#define BFD_UND_SECTION_NAME "*UND*"
#define BFD_COM_SECTION_NAME "*COM*"
#define BFD_IND_SECTION_NAME "*IND*"

    /* the absolute section */
extern const asection bfd_abs_section;
#define bfd_abs_section_ptr ((asection *) &bfd_abs_section)
#define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr)
    /* Pointer to the undefined section */
extern const asection bfd_und_section;
#define bfd_und_section_ptr ((asection *) &bfd_und_section)
#define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr)
    /* Pointer to the common section */
extern const asection bfd_com_section;
#define bfd_com_section_ptr ((asection *) &bfd_com_section)
    /* Pointer to the indirect section */
extern const asection bfd_ind_section;
#define bfd_ind_section_ptr ((asection *) &bfd_ind_section)
#define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr)

extern const struct symbol_cache_entry * const bfd_abs_symbol;
extern const struct symbol_cache_entry * const bfd_com_symbol;
extern const struct symbol_cache_entry * const bfd_und_symbol;
extern const struct symbol_cache_entry * const bfd_ind_symbol;
#define bfd_get_section_size_before_reloc(section) \
     (section->reloc_done ? (abort(),1): (section)->_raw_size)
#define bfd_get_section_size_after_reloc(section) \
     ((section->reloc_done) ? (section)->_cooked_size: (abort(),1))

Section prototypes

These are the functions exported by the section handling part of BFD.

bfd_get_section_by_name

Synopsis

asection *bfd_get_section_by_name(bfd *abfd, CONST char *name);

Description
Run through abfd and return the one of the asections whose name matches name, otherwise NULL. See section Sections, for more information.

This should only be used in special cases; the normal way to process all sections of a given name is to use bfd_map_over_sections and strcmp on the name (or better yet, base it on the section flags or something else) for each section.

bfd_make_section_old_way

Synopsis

asection *bfd_make_section_old_way(bfd *abfd, CONST char *name);

Description
Create a new empty section called name and attach it to the end of the chain of sections for the BFD abfd. An attempt to create a section with a name which is already in use returns its pointer without changing the section chain.

It has the funny name since this is the way it used to be before it was rewritten....

Possible errors are:

  • bfd_error_invalid_operation - If output has already started for this BFD.
  • bfd_error_no_memory - If memory allocation fails.

bfd_make_section_anyway

Synopsis

asection *bfd_make_section_anyway(bfd *abfd, CONST char *name);

Description
Create a new empty section called name and attach it to the end of the chain of sections for abfd. Create a new section even if there is already a section with that name.

Return NULL and set bfd_error on error; possible errors are:

  • bfd_error_invalid_operation - If output has already started for abfd.
  • bfd_error_no_memory - If memory allocation fails.

bfd_make_section

Synopsis

asection *bfd_make_section(bfd *, CONST char *name);

Description
Like bfd_make_section_anyway, but return NULL (without calling bfd_set_error ()) without changing the section chain if there is already a section named name. If there is an error, return NULL and set bfd_error.

bfd_set_section_flags

Synopsis

boolean bfd_set_section_flags(bfd *abfd, asection *sec, flagword flags);

Description
Set the attributes of the section sec in the BFD abfd to the value flags. Return true on success, false on error. Possible error returns are:

  • bfd_error_invalid_operation - The section cannot have one or more of the attributes requested. For example, a .bss section in a.out may not have the SEC_HAS_CONTENTS field set.

bfd_map_over_sections

Synopsis

void bfd_map_over_sections(bfd *abfd,
    void (*func)(bfd *abfd,
    asection *sect,
    PTR obj),
    PTR obj);

Description
Call the provided function func for each section attached to the BFD abfd, passing obj as an argument. The function will be called as if by

       func(abfd, the_section, obj);

This is the prefered method for iterating over sections; an alternative would be to use a loop:

          section *p;
          for (p = abfd->sections; p != NULL; p = p->next)
             func(abfd, p, ...)

bfd_set_section_size

Synopsis

boolean bfd_set_section_size(bfd *abfd, asection *sec, bfd_size_type val);

Description
Set sec to the size val. If the operation is ok, then true is returned, else false.

Possible error returns:

  • bfd_error_invalid_operation - Writing has started to the BFD, so setting the size is invalid.

bfd_set_section_contents

Synopsis

boolean bfd_set_section_contents
   (bfd *abfd,
    asection *section,
    PTR data,
    file_ptr offset,
    bfd_size_type count);

Description
Sets the contents of the section section in BFD abfd to the data starting in memory at data. The data is written to the output section starting at offset offset for count bytes.

Normally true is returned, else false. Possible error returns are:

  • bfd_error_no_contents - The output section does not have the SEC_HAS_CONTENTS attribute, so nothing can be written to it.
  • and some more too

This routine is front end to the back end function _bfd_set_section_contents.

bfd_get_section_contents

Synopsis

boolean bfd_get_section_contents
   (bfd *abfd, asection *section, PTR location,
    file_ptr offset, bfd_size_type count);

Description
Read data from section in BFD abfd into memory starting at location. The data is read at an offset of offset from the start of the input section, and is read for count bytes.

If the contents of a constructor with the SEC_CONSTRUCTOR flag set are requested or if the section does not have the SEC_HAS_CONTENTS flag set, then the location is filled with zeroes. If no errors occur, true is returned, else false.

bfd_copy_private_section_data

Synopsis

boolean bfd_copy_private_section_data(bfd *ibfd, asection *isec, bfd *obfd, asection *osec);

Description
Copy private section information from isec in the BFD ibfd to the section osec in the BFD obfd. Return true on success, false on error. Possible error returns are:

  • bfd_error_no_memory - Not enough memory exists to create private data for osec.
#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \
     BFD_SEND (obfd, _bfd_copy_private_section_data, \
               (ibfd, isection, obfd, osection))

Symbols

BFD tries to maintain as much symbol information as it can when it moves information from file to file. BFD passes information to applications though the asymbol structure. When the application requests the symbol table, BFD reads the table in the native form and translates parts of it into the internal format. To maintain more than the information passed to applications, some targets keep some information "behind the scenes" in a structure only the particular back end knows about. For example, the coff back end keeps the original symbol table structure as well as the canonical structure when a BFD is read in. On output, the coff back end can reconstruct the output symbol table so that no information is lost, even information unique to coff which BFD doesn't know or understand. If a coff symbol table were read, but were written through an a.out back end, all the coff specific information would be lost. The symbol table of a BFD is not necessarily read in until a canonicalize request is made. Then the BFD back end fills in a table provided by the application with pointers to the canonical information. To output symbols, the application provides BFD with a table of pointers to pointers to asymbols. This allows applications like the linker to output a symbol as it was read, since the "behind the scenes" information will be still available.

Reading symbols

There are two stages to reading a symbol table from a BFD: allocating storage, and the actual reading process. This is an excerpt from an application which reads the symbol table:

         long storage_needed;
         asymbol **symbol_table;
         long number_of_symbols;
         long i;

         storage_needed = bfd_get_symtab_upper_bound (abfd);

         if (storage_needed < 0)
           FAIL

         if (storage_needed == 0) {
            return ;
         }
         symbol_table = (asymbol **) xmalloc (storage_needed);
           ...
         number_of_symbols =
            bfd_canonicalize_symtab (abfd, symbol_table);

         if (number_of_symbols < 0)
           FAIL

         for (i = 0; i < number_of_symbols; i++) {
            process_symbol (symbol_table[i]);
         }

All storage for the symbols themselves is in an objalloc connected to the BFD; it is freed when the BFD is closed.

Writing symbols

Writing of a symbol table is automatic when a BFD open for writing is closed. The application attaches a vector of pointers to pointers to symbols to the BFD being written, and fills in the symbol count. The close and cleanup code reads through the table provided and performs all the necessary operations. The BFD output code must always be provided with an "owned" symbol: one which has come from another BFD, or one which has been created using bfd_make_empty_symbol. Here is an example showing the creation of a symbol table with only one element:

       #include "bfd.h"
       main()
       {
         bfd *abfd;
         asymbol *ptrs[2];
         asymbol *new;

         abfd = bfd_openw("foo","a.out-sunos-big");
         bfd_set_format(abfd, bfd_object);
         new = bfd_make_empty_symbol(abfd);
         new->name = "dummy_symbol";
         new->section = bfd_make_section_old_way(abfd, ".text");
         new->flags = BSF_GLOBAL;
         new->value = 0x12345;

         ptrs[0] = new;
         ptrs[1] = (asymbol *)0;

         bfd_set_symtab(abfd, ptrs, 1);
         bfd_close(abfd);
       }

       ./makesym
       nm foo
       00012345 A dummy_symbol

Many formats cannot represent arbitary symbol information; for instance, the a.out object format does not allow an arbitary number of sections. A symbol pointing to a section which is not one of .text, .data or .bss cannot be described.

Mini Symbols

Mini symbols provide read-only access to the symbol table. They use less memory space, but require more time to access. They can be useful for tools like nm or objdump, which may have to handle symbol tables of extremely large executables.

The bfd_read_minisymbols function will read the symbols into memory in an internal form. It will return a void * pointer to a block of memory, a symbol count, and the size of each symbol. The pointer is allocated using malloc, and should be freed by the caller when it is no longer needed.

The function bfd_minisymbol_to_symbol will take a pointer to a minisymbol, and a pointer to a structure returned by bfd_make_empty_symbol, and return a asymbol structure. The return value may or may not be the same as the value from bfd_make_empty_symbol which was passed in.

typedef asymbol

An asymbol has the form:

typedef struct symbol_cache_entry
{
       /* A pointer to the BFD which owns the symbol. This information
          is necessary so that a back end can work out what additional
          information (invisible to the application writer) is carried
          with the symbol.

          This field is *almost* redundant, since you can use section->owner
          instead, except that some symbols point to the global sections
          bfd_{abs,com,und}_section.  This could be fixed by making
          these globals be per-bfd (or per-target-flavor).  FIXME. */

  struct _bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */

       /* The text of the symbol. The name is left alone, and not copied; the
          application may not alter it. */
  CONST char *name;

       /* The value of the symbol.  This really should be a union of a
          numeric value with a pointer, since some flags indicate that
          a pointer to another symbol is stored here.  */
  symvalue value;

       /* Attributes of a symbol: */

#define BSF_NO_FLAGS    0x00

       /* The symbol has local scope; static in C. The value
          is the offset into the section of the data. */
#define BSF_LOCAL      0x01

       /* The symbol has global scope; initialized data in C. The
          value is the offset into the section of the data. */
#define BSF_GLOBAL     0x02

       /* The symbol has global scope and is exported. The value is
          the offset into the section of the data. */
#define BSF_EXPORT     BSF_GLOBAL /* no real difference */

       /* A normal C symbol would be one of:
          BSF_LOCAL, BSF_FORT_COMM,  BSF_UNDEFINED or
          BSF_GLOBAL */

       /* The symbol is a debugging record. The value has an arbitary
          meaning. */
#define BSF_DEBUGGING  0x08

       /* The symbol denotes a function entry point.  Used in ELF,
          perhaps others someday.  */
#define BSF_FUNCTION    0x10

       /* Used by the linker. */
#define BSF_KEEP        0x20
#define BSF_KEEP_G      0x40

       /* A weak global symbol, overridable without warnings by
          a regular global symbol of the same name.  */
#define BSF_WEAK        0x80

       /* This symbol was created to point to a section, e.g. ELF's
          STT_SECTION symbols.  */
#define BSF_SECTION_SYM 0x100

       /* The symbol used to be a common symbol, but now it is
          allocated. */
#define BSF_OLD_COMMON  0x200

       /* The default value for common data. */
#define BFD_FORT_COMM_DEFAULT_VALUE 0

       /* In some files the type of a symbol sometimes alters its
          location in an output file - ie in coff a ISFCN symbol
          which is also C_EXT symbol appears where it was
          declared and not at the end of a section.  This bit is set
          by the target BFD part to convey this information. */

#define BSF_NOT_AT_END    0x400

       /* Signal that the symbol is the label of constructor section. */
#define BSF_CONSTRUCTOR   0x800

       /* Signal that the symbol is a warning symbol.  The name is a
          warning.  The name of the next symbol is the one to warn about;
          if a reference is made to a symbol with the same name as the next
          symbol, a warning is issued by the linker. */
#define BSF_WARNING       0x1000

       /* Signal that the symbol is indirect.  This symbol is an indirect
          pointer to the symbol with the same name as the next symbol. */
#define BSF_INDIRECT      0x2000

       /* BSF_FILE marks symbols that contain a file name.  This is used
          for ELF STT_FILE symbols.  */
#define BSF_FILE          0x4000

       /* Symbol is from dynamic linking information.  */
#define BSF_DYNAMIC       0x8000

       /* The symbol denotes a data object.  Used in ELF, and perhaps
          others someday.  */
#define BSF_OBJECT        0x10000

  flagword flags;

       /* A pointer to the section to which this symbol is
          relative.  This will always be non NULL, there are special
          sections for undefined and absolute symbols.  */
  struct sec *section;

       /* Back end special data.  */
  union
    {
      PTR p;
      bfd_vma i;
    } udata;

} asymbol;

Symbol handling functions

bfd_get_symtab_upper_bound

Description
Return the number of bytes required to store a vector of pointers to asymbols for all the symbols in the BFD abfd, including a terminal NULL pointer. If there are no symbols in the BFD, then return 0. If an error occurs, return -1.

#define bfd_get_symtab_upper_bound(abfd) \
     BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd))

bfd_is_local_label

Synopsis

boolean bfd_is_local_label(bfd *abfd, asymbol *sym);

Description
Return true if the given symbol sym in the BFD abfd is a compiler generated local label, else return false.

bfd_is_local_label_name

Synopsis

boolean bfd_is_local_label_name(bfd *abfd, const char *name);

Description
Return true if a symbol with the name name in the BFD abfd is a compiler generated local label, else return false. This just checks whether the name has the form of a local label.

#define bfd_is_local_label_name(abfd, name) \
     BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name))

bfd_canonicalize_symtab

Description
Read the symbols from the BFD abfd, and fills in the vector location with pointers to the symbols and a trailing NULL. Return the actual number of symbol pointers, not including the NULL.

#define bfd_canonicalize_symtab(abfd, location) \
     BFD_SEND (abfd, _bfd_canonicalize_symtab,\
                  (abfd, location))

bfd_set_symtab

Synopsis

boolean bfd_set_symtab (bfd *abfd, asymbol **location, unsigned int count);

Description
Arrange that when the output BFD abfd is closed, the table location of count pointers to symbols will be written.

bfd_print_symbol_vandf

Synopsis

void bfd_print_symbol_vandf(PTR file, asymbol *symbol);

Description
Print the value and flags of the symbol supplied to the stream file.

bfd_make_empty_symbol

Description
Create a new asymbol structure for the BFD abfd and return a pointer to it.

This routine is necessary because each back end has private information surrounding the asymbol. Building your own asymbol and pointing to it will not create the private information, and will cause problems later on.

#define bfd_make_empty_symbol(abfd) \
     BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd))

bfd_make_debug_symbol

Description
Create a new asymbol structure for the BFD abfd, to be used as a debugging symbol. Further details of its use have yet to be worked out.

#define bfd_make_debug_symbol(abfd,ptr,size) \
        BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size))

bfd_decode_symclass

Description
Return a character corresponding to the symbol class of symbol, or '?' for an unknown class.

Synopsis

int bfd_decode_symclass(asymbol *symbol);

bfd_symbol_info

Description
Fill in the basic info about symbol that nm needs. Additional info may be added by the back-ends after calling this function.

Synopsis

void bfd_symbol_info(asymbol *symbol, symbol_info *ret);

bfd_copy_private_symbol_data

Synopsis

boolean bfd_copy_private_symbol_data(bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym);

Description
Copy private symbol information from isym in the BFD ibfd to the symbol osym in the BFD obfd. Return true on success, false on error. Possible error returns are:

  • bfd_error_no_memory - Not enough memory exists to create private data for osec.
#define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \
     BFD_SEND (obfd, _bfd_copy_private_symbol_data, \
               (ibfd, isymbol, obfd, osymbol))

Archives

Description
An archive (or library) is just another BFD. It has a symbol table, although there's not much a user program will do with it.

The big difference between an archive BFD and an ordinary BFD is that the archive doesn't have sections. Instead it has a chain of BFDs that are considered its contents. These BFDs can be manipulated like any other. The BFDs contained in an archive opened for reading will all be opened for reading. You may put either input or output BFDs into an archive opened for output; they will be handled correctly when the archive is closed.

Use bfd_openr_next_archived_file to step through the contents of an archive opened for input. You don't have to read the entire archive if you don't want to! Read it until you find what you want.

Archive contents of output BFDs are chained through the next pointer in a BFD. The first one is findable through the archive_head slot of the archive. Set it with bfd_set_archive_head (q.v.). A given BFD may be in only one open output archive at a time.

As expected, the BFD archive code is more general than the archive code of any given environment. BFD archives may contain files of different formats (e.g., a.out and coff) and even different architectures. You may even place archives recursively into archives!

This can cause unexpected confusion, since some archive formats are more expressive than others. For instance, Intel COFF archives can preserve long filenames; SunOS a.out archives cannot. If you move a file from the first to the second format and back again, the filename may be truncated. Likewise, different a.out environments have different conventions as to how they truncate filenames, whether they preserve directory names in filenames, etc. When interoperating with native tools, be sure your files are homogeneous.

Beware: most of these formats do not react well to the presence of spaces in filenames. We do the best we can, but can't always handle this case due to restrictions in the format of archives. Many Unix utilities are braindead in regards to spaces and such in filenames anyway, so this shouldn't be much of a restriction.

Archives are supported in BFD in archive.c.

bfd_get_next_mapent

Synopsis

symindex bfd_get_next_mapent(bfd *abfd, symindex previous, carsym **sym);

Description
Step through archive abfd's symbol table (if it has one). Successively update sym with the next symbol's information, returning that symbol's (internal) index into the symbol table.

Supply BFD_NO_MORE_SYMBOLS as the previous entry to get the first one; returns BFD_NO_MORE_SYMBOLS when you've already got the last one.

A carsym is a canonical archive symbol. The only user-visible element is its name, a null-terminated string.

bfd_set_archive_head

Synopsis

boolean bfd_set_archive_head(bfd *output, bfd *new_head);

Description
Set the head of the chain of BFDs contained in the archive output to new_head.

bfd_openr_next_archived_file

Synopsis

bfd *bfd_openr_next_archived_file(bfd *archive, bfd *previous);

Description
Provided a BFD, archive, containing an archive and NULL, open an input BFD on the first contained element and returns that. Subsequent calls should pass the archive and the previous return value to return a created BFD to the next contained element. NULL is returned when there are no more.

File formats

A format is a BFD concept of high level file contents type. The formats supported by BFD are:

  • bfd_object

The BFD may contain data, symbols, relocations and debug info.

  • bfd_archive

The BFD contains other BFDs and an optional index.

  • bfd_core

The BFD contains the result of an executable core dump.

bfd_check_format

Synopsis

boolean bfd_check_format(bfd *abfd, bfd_format format);

Description
Verify if the file attached to the BFD abfd is compatible with the format format (i.e., one of bfd_object, bfd_archive or bfd_core).

If the BFD has been set to a specific target before the call, only the named target and format combination is checked. If the target has not been set, or has been set to default, then all the known target backends is interrogated to determine a match. If the default target matches, it is used. If not, exactly one target must recognize the file, or an error results.

The function returns true on success, otherwise false with one of the following error codes:

  • bfd_error_invalid_operation - if format is not one of bfd_object, bfd_archive or bfd_core.
  • bfd_error_system_call - if an error occured during a read - even some file mismatches can cause bfd_error_system_calls.
  • file_not_recognised - none of the backends recognised the file format.
  • bfd_error_file_ambiguously_recognized - more than one backend recognised the file format.

bfd_check_format_matches

Synopsis

boolean bfd_check_format_matches(bfd *abfd, bfd_format format, char ***matching);

Description
Like bfd_check_format, except when it returns false with bfd_errno set to bfd_error_file_ambiguously_recognized. In that case, if matching is not NULL, it will be filled in with a NULL-terminated list of the names of the formats that matched, allocated with malloc. Then the user may choose a format and try again.

When done with the list that matching points to, the caller should free it.

bfd_set_format

Synopsis

boolean bfd_set_format(bfd *abfd, bfd_format format);

Description
This function sets the file format of the BFD abfd to the format format. If the target set in the BFD does not support the format requested, the format is invalid, or the BFD is not open for writing, then an error occurs.

bfd_format_string

Synopsis

CONST char *bfd_format_string(bfd_format format);

Description
Return a pointer to a const string invalid, object, archive, core, or unknown, depending upon the value of format.

Relocations

BFD maintains relocations in much the same way it maintains symbols: they are left alone until required, then read in en-mass and translated into an internal form. A common routine bfd_perform_relocation acts upon the canonical form to do the fixup.

Relocations are maintained on a per section basis, while symbols are maintained on a per BFD basis.

All that a back end has to do to fit the BFD interface is to create a struct reloc_cache_entry for each relocation in a particular section, and fill in the right bits of the structures.

typedef arelent

This is the structure of a relocation entry:

typedef enum bfd_reloc_status
{
       /* No errors detected */
  bfd_reloc_ok,

       /* The relocation was performed, but there was an overflow. */
  bfd_reloc_overflow,

       /* The address to relocate was not within the section supplied. */
  bfd_reloc_outofrange,

       /* Used by special functions */
  bfd_reloc_continue,

       /* Unsupported relocation size requested. */
  bfd_reloc_notsupported,

       /* Unused */
  bfd_reloc_other,

       /* The symbol to relocate against was undefined. */
  bfd_reloc_undefined,

       /* The relocation was performed, but may not be ok - presently
          generated only when linking i960 coff files with i960 b.out
          symbols.  If this type is returned, the error_message argument
          to bfd_perform_relocation will be set.  */
  bfd_reloc_dangerous
 }
 bfd_reloc_status_type;

typedef struct reloc_cache_entry
{
       /* A pointer into the canonical table of pointers  */
  struct symbol_cache_entry **sym_ptr_ptr;

       /* offset in section */
  bfd_size_type address;

       /* addend for relocation value */
  bfd_vma addend;

       /* Pointer to how to perform the required relocation */
  reloc_howto_type *howto;

} arelent;

Description
Here is a description of each of the fields within an arelent:

  • sym_ptr_ptr

The symbol table pointer points to a pointer to the symbol associated with the relocation request. It is the pointer into the table returned by the back end's get_symtab action. See section Symbols. The symbol is referenced through a pointer to a pointer so that tools like the linker can fix up all the symbols of the same name by modifying only one pointer. The relocation routine looks in the symbol and uses the base of the section the symbol is attached to and the value of the symbol as the initial relocation offset. If the symbol pointer is zero, then the section provided is looked up.

  • address

The address field gives the offset in bytes from the base of the section data which owns the relocation record to the first byte of relocatable information. The actual data relocated will be relative to this point; for example, a relocation type which modifies the bottom two bytes of a four byte word would not touch the first byte pointed to in a big endian world.

  • addend

The addend is a value provided by the back end to be added (!) to the relocation offset. Its interpretation is dependent upon the howto. For example, on the 68k the code:

        char foo[];
        main()
                {
                return foo[0x12345678];
                }

Could be compiled into:

        linkw fp,#-4
        moveb @#12345678,d0
        extbl d0
        unlk fp
        rts

This could create a reloc pointing to foo, but leave the offset in the data, something like:

RELOCATION RECORDS FOR [.text]:
offset   type      value
00000006 32        _foo

00000000 4e56 fffc          ; linkw fp,#-4
00000004 1039 1234 5678     ; moveb @#12345678,d0
0000000a 49c0               ; extbl d0
0000000c 4e5e               ; unlk fp
0000000e 4e75               ; rts

Using coff and an 88k, some instructions don't have enough space in them to represent the full address range, and pointers have to be loaded in two parts. So you'd get something like:

        or.u     r13,r0,hi16(_foo+0x12345678)
        ld.b     r2,r13,lo16(_foo+0x12345678)
        jmp      r1

This should create two relocs, both pointing to _foo, and with 0x12340000 in their addend field. The data would consist of:

RELOCATION RECORDS FOR [.text]:
offset   type      value
00000002 HVRT16    _foo+0x12340000
00000006 LVRT16    _foo+0x12340000

00000000 5da05678           ; or.u r13,r0,0x5678
00000004 1c4d5678           ; ld.b r2,r13,0x5678
00000008 f400c001           ; jmp r1

The relocation routine digs out the value from the data, adds it to the addend to get the original offset, and then adds the value of _foo. Note that all 32 bits have to be kept around somewhere, to cope with carry from bit 15 to bit 16.

One further example is the sparc and the a.out format. The sparc has a similar problem to the 88k, in that some instructions don't have room for an entire offset, but on the sparc the parts are created in odd sized lumps. The designers of the a.out format chose to not use the data within the section for storing part of the offset; all the offset is kept within the reloc. Anything in the data should be ignored.

        save %sp,-112,%sp
        sethi %hi(_foo+0x12345678),%g2
        ldsb [%g2+%lo(_foo+0x12345678)],%i0
        ret
        restore

Both relocs contain a pointer to foo, and the offsets contain junk.

RELOCATION RECORDS FOR [.text]:
offset   type      value
00000004 HI22      _foo+0x12345678
00000008 LO10      _foo+0x12345678

00000000 9de3bf90     ; save %sp,-112,%sp
00000004 05000000     ; sethi %hi(_foo+0),%g2
00000008 f048a000     ; ldsb [%g2+%lo(_foo+0)],%i0
0000000c 81c7e008     ; ret
00000010 81e80000     ; restore
  • howto

The howto field can be imagined as a relocation instruction. It is a pointer to a structure which contains information on what to do with all of the other information in the reloc record and data section. A back end would normally have a relocation instruction set and turn relocations into pointers to the correct structure on input - but it would be possible to create each howto field on demand.

enum complain_overflow

Indicates what sort of overflow checking should be done when performing a relocation.

enum complain_overflow
{
       /* Do not complain on overflow. */
  complain_overflow_dont,

       /* Complain if the bitfield overflows, whether it is considered
          as signed or unsigned. */
  complain_overflow_bitfield,

       /* Complain if the value overflows when considered as signed
          number. */
  complain_overflow_signed,

       /* Complain if the value overflows when considered as an
          unsigned number. */
  complain_overflow_unsigned
};

reloc_howto_type

The reloc_howto_type is a structure which contains all the information that libbfd needs to know to tie up a back end's data.

struct symbol_cache_entry;             /* Forward declaration */

struct reloc_howto_struct
{
       /*  The type field has mainly a documentary use - the back end can
           do what it wants with it, though normally the back end's
           external idea of what a reloc number is stored
           in this field. For example, a PC relative word relocation
           in a coff environment has the type 023 - because that's
           what the outside world calls a R_PCRWORD reloc. */
  unsigned int type;

       /*  The value the final relocation is shifted right by. This drops
           unwanted data from the relocation.  */
  unsigned int rightshift;

       /*  The size of the item to be relocated.  This is *not* a
           power-of-two measure.  To get the number of bytes operated
           on by a type of relocation, use bfd_get_reloc_size.  */
  int size;

       /*  The number of bits in the item to be relocated.  This is used
           when doing overflow checking.  */
  unsigned int bitsize;

       /*  Notes that the relocation is relative to the location in the
           data section of the addend. The relocation function will
           subtract from the relocation value the address of the location
           being relocated. */
  boolean pc_relative;

       /*  The bit position of the reloc value in the destination.
           The relocated value is left shifted by this amount. */
  unsigned int bitpos;

       /* What type of overflow error should be checked for when
          relocating. */
  enum complain_overflow complain_on_overflow;

       /* If this field is non null, then the supplied function is
          called rather than the normal function. This allows really
          strange relocation methods to be accomodated (e.g., i960 callj
          instructions). */
  bfd_reloc_status_type (*special_function)
                                   PARAMS ((bfd *abfd,
                                            arelent *reloc_entry,
                                            struct symbol_cache_entry *symbol,
                                            PTR data,
                                            asection *input_section,
                                            bfd *output_bfd,
                                            char **error_message));

       /* The textual name of the relocation type. */
  char *name;

       /* When performing a partial link, some formats must modify the
          relocations rather than the data - this flag signals this.*/
  boolean partial_inplace;

       /* The src_mask selects which parts of the read in data
          are to be used in the relocation sum.  E.g., if this was an 8 bit
          bit of data which we read and relocated, this would be
          0x000000ff. When we have relocs which have an addend, such as
          sun4 extended relocs, the value in the offset part of a
          relocating field is garbage so we never use it. In this case
          the mask would be 0x00000000. */
  bfd_vma src_mask;

       /* The dst_mask selects which parts of the instruction are replaced
          into the instruction. In most cases src_mask == dst_mask,
          except in the above special case, where dst_mask would be
          0x000000ff, and src_mask would be 0x00000000.   */
  bfd_vma dst_mask;

       /* When some formats create PC relative instructions, they leave
          the value of the pc of the place being relocated in the offset
          slot of the instruction, so that a PC relative relocation can
          be made just by adding in an ordinary offset (e.g., sun3 a.out).
          Some formats leave the displacement part of an instruction
          empty (e.g., m88k bcs); this flag signals the fact.*/
  boolean pcrel_offset;

};

The HOWTO Macro

Description
The HOWTO define is horrible and will go away.

#define HOWTO(C, R,S,B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
  {(unsigned)C,R,S,B, P, BI, O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC}

Description
And will be replaced with the totally magic way. But for the moment, we are compatible, so do it this way.

#define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,complain_overflow_dont,FUNCTION, NAME,false,0,0,IN)

Description
Helper routine to turn a symbol into a relocation value.

#define HOWTO_PREPARE(relocation, symbol)      \
  {                                            \
  if (symbol != (asymbol *)NULL) {             \
    if (bfd_is_com_section (symbol->section)) { \
      relocation = 0;                          \
    }                                          \
    else {                                     \
      relocation = symbol->value;              \
    }                                          \
  }                                            \
}

bfd_get_reloc_size

Synopsis

unsigned int bfd_get_reloc_size (reloc_howto_type *);

Description
For a reloc_howto_type that operates on a fixed number of bytes, this returns the number of bytes operated on.

arelent_chain

Description
How relocs are tied together in an asection:

typedef struct relent_chain {
  arelent relent;
  struct   relent_chain *next;
} arelent_chain;

bfd_check_overflow

Synopsis

bfd_reloc_status_type
bfd_check_overflow
   (enum complain_overflow how,
    unsigned int bitsize,
    unsigned int rightshift,
    bfd_vma relocation);

Description
Perform overflow checking on relocation which has bitsize significant bits and will be shifted right by rightshift bits. The result is either of bfd_reloc_ok or bfd_reloc_overflow.

bfd_perform_relocation

Synopsis

bfd_reloc_status_type
bfd_perform_relocation
   (bfd *abfd,
    arelent *reloc_entry,
    PTR data,
    asection *input_section,
    bfd *output_bfd,
    char **error_message);

Description
If output_bfd is supplied to this function, the generated image will be relocatable; the relocations are copied to the output file after they have been changed to reflect the new state of the world. There are two ways of reflecting the results of partial linkage in an output file: by modifying the output data in place, and by modifying the relocation record. Some native formats (e.g., basic a.out and basic coff) have no way of specifying an addend in the relocation type, so the addend has to go in the output data. This is no big deal since in these formats the output data slot will always be big enough for the addend. Complex reloc types with addends were invented to solve just this problem. The error_message argument is set to an error message if this return bfd_reloc_dangerous.

bfd_install_relocation

Synopsis

bfd_reloc_status_type
bfd_install_relocation
   (bfd *abfd,
    arelent *reloc_entry,
    PTR data, bfd_vma data_start,
    asection *input_section,
    char **error_message);

Description
This looks remarkably like bfd_perform_relocation, except it does not expect that the section contents have been filled in. I.e., it's suitable for use when creating, rather than applying a relocation.

For now, this function should be considered reserved for the assembler.

The howto manager

When an application wants to create a relocation, but doesn't know what the target machine might call it, it can find out by using this bit of code.

bfd_reloc_code_type

Description
The insides of a reloc code. The idea is that, eventually, there will be one enumerator for every type of relocation we ever do. Pass one of these values to bfd_reloc_type_lookup, and it'll return a howto pointer.

This does mean that the application must determine the correct enumerator value; you can't get a howto pointer from a random set of attributes.

Here are the possible values for enum bfd_reloc_code_real:

: BFD_RELOC_64
: BFD_RELOC_32
: BFD_RELOC_26
: BFD_RELOC_24
: BFD_RELOC_16
: BFD_RELOC_14
: BFD_RELOC_8
Basic absolute relocations of N bits.
: BFD_RELOC_64_PCREL
: BFD_RELOC_32_PCREL
: BFD_RELOC_24_PCREL
: BFD_RELOC_16_PCREL
: BFD_RELOC_12_PCREL
: BFD_RELOC_8_PCREL
PC-relative relocations. Sometimes these are relative to the address of the relocation itself; sometimes they are relative to the start of the section containing the relocation. It depends on the specific target.

The 24-bit relocation is used in some Intel 960 configurations.

: BFD_RELOC_32_GOT_PCREL
: BFD_RELOC_16_GOT_PCREL
: BFD_RELOC_8_GOT_PCREL
: BFD_RELOC_32_GOTOFF
: BFD_RELOC_16_GOTOFF
: BFD_RELOC_LO16_GOTOFF
: BFD_RELOC_HI16_GOTOFF
: BFD_RELOC_HI16_S_GOTOFF
: BFD_RELOC_8_GOTOFF
: BFD_RELOC_32_PLT_PCREL
: BFD_RELOC_24_PLT_PCREL
: BFD_RELOC_16_PLT_PCREL
: BFD_RELOC_8_PLT_PCREL
: BFD_RELOC_32_PLTOFF
: BFD_RELOC_16_PLTOFF
: BFD_RELOC_LO16_PLTOFF
: BFD_RELOC_HI16_PLTOFF
: BFD_RELOC_HI16_S_PLTOFF
: BFD_RELOC_8_PLTOFF
For ELF.
: BFD_RELOC_68K_GLOB_DAT
: BFD_RELOC_68K_JMP_SLOT
: BFD_RELOC_68K_RELATIVE
Relocations used by 68K ELF.
: BFD_RELOC_32_BASEREL
: BFD_RELOC_16_BASEREL
: BFD_RELOC_LO16_BASEREL
: BFD_RELOC_HI16_BASEREL
: BFD_RELOC_HI16_S_BASEREL
: BFD_RELOC_8_BASEREL
: BFD_RELOC_RVA
Linkage-table relative.
: BFD_RELOC_8_FFnn
Absolute 8-bit relocation, but used to form an address like 0xFFnn.
: BFD_RELOC_32_PCREL_S2
: BFD_RELOC_16_PCREL_S2
: BFD_RELOC_23_PCREL_S2
These PC-relative relocations are stored as word displacements -- i.e., byte displacements shifted right two bits. The 30-bit word displacement (<<32_PCREL_S2>> -- 32 bits, shifted 2) is used on the SPARC. (SPARC tools generally refer to this as <<WDISP30>>.) The signed 16-bit displacement is used on the MIPS, and the 23-bit displacement is used on the Alpha.
: BFD_RELOC_HI22
: BFD_RELOC_LO10
High 22 bits and low 10 bits of 32-bit value, placed into lower bits of the target word. These are used on the SPARC.
: BFD_RELOC_GPREL16
: BFD_RELOC_GPREL32
For systems that allocate a Global Pointer register, these are displacements off that register. These relocation types are handled specially, because the value the register will have is decided relatively late.
: BFD_RELOC_I960_CALLJ
Reloc types used for i960/b.out.
: BFD_RELOC_NONE
: BFD_RELOC_SPARC_WDISP22
: BFD_RELOC_SPARC22
: BFD_RELOC_SPARC13
: BFD_RELOC_SPARC_GOT10
: BFD_RELOC_SPARC_GOT13
: BFD_RELOC_SPARC_GOT22
: BFD_RELOC_SPARC_PC10
: BFD_RELOC_SPARC_PC22
: BFD_RELOC_SPARC_WPLT30
: BFD_RELOC_SPARC_COPY
: BFD_RELOC_SPARC_GLOB_DAT
: BFD_RELOC_SPARC_JMP_SLOT
: BFD_RELOC_SPARC_RELATIVE
: BFD_RELOC_SPARC_UA32
SPARC ELF relocations. There is probably some overlap with other relocation types already defined.
: BFD_RELOC_SPARC_BASE13
: BFD_RELOC_SPARC_BASE22
I think these are specific to SPARC a.out (e.g., Sun 4).
: BFD_RELOC_SPARC_64
: BFD_RELOC_SPARC_10
: BFD_RELOC_SPARC_11
: BFD_RELOC_SPARC_OLO10
: BFD_RELOC_SPARC_HH22
: BFD_RELOC_SPARC_HM10
: BFD_RELOC_SPARC_LM22
: BFD_RELOC_SPARC_PC_HH22
: BFD_RELOC_SPARC_PC_HM10
: BFD_RELOC_SPARC_PC_LM22
: BFD_RELOC_SPARC_WDISP16
: BFD_RELOC_SPARC_WDISP19
: BFD_RELOC_SPARC_7
: BFD_RELOC_SPARC_6
: BFD_RELOC_SPARC_5
: BFD_RELOC_SPARC_DISP64
: BFD_RELOC_SPARC_PLT64
: BFD_RELOC_SPARC_HIX22
: BFD_RELOC_SPARC_LOX10
: BFD_RELOC_SPARC_H44
: BFD_RELOC_SPARC_M44
: BFD_RELOC_SPARC_L44
: BFD_RELOC_SPARC_REGISTER
SPARC64 relocations
: BFD_RELOC_ALPHA_GPDISP_HI16
Alpha ECOFF and ELF relocations. Some of these treat the symbol or "addend" in some special way. For GPDISP_HI16 ("gpdisp") relocations, the symbol is ignored when writing; when reading, it will be the absolute section symbol. The addend is the displacement in bytes of the "lda" instruction from the "ldah" instruction (which is at the address of this reloc).
: BFD_RELOC_ALPHA_GPDISP_LO16
For GPDISP_LO16 ("ignore") relocations, the symbol is handled as with GPDISP_HI16 relocs. The addend is ignored when writing the relocations out, and is filled in with the file's GP value on reading, for convenience.
: BFD_RELOC_ALPHA_GPDISP
The ELF GPDISP relocation is exactly the same as the GPDISP_HI16 relocation except that there is no accompanying GPDISP_LO16 relocation.
: BFD_RELOC_ALPHA_LITERAL
: BFD_RELOC_ALPHA_ELF_LITERAL
: BFD_RELOC_ALPHA_LITUSE
The Alpha LITERAL/LITUSE relocs are produced by a symbol reference; the assembler turns it into a LDQ instruction to load the address of the symbol, and then fills in a register in the real instruction.

The LITERAL reloc, at the LDQ instruction, refers to the .lita section symbol. The addend is ignored when writing, but is filled in with the file's GP value on reading, for convenience, as with the GPDISP_LO16 reloc.

The ELF_LITERAL reloc is somewhere between 16_GOTOFF and GPDISP_LO16. It should refer to the symbol to be referenced, as with 16_GOTOFF, but it generates output not based on the position within the .got section, but relative to the GP value chosen for the file during the final link stage.

The LITUSE reloc, on the instruction using the loaded address, gives information to the linker that it might be able to use to optimize away some literal section references. The symbol is ignored (read as the absolute section symbol), and the "addend" indicates the type of instruction using the register: 1 - "memory" fmt insn 2 - byte-manipulation (byte offset reg) 3 - jsr (target of branch)

The GNU linker currently doesn't do any of this optimizing.

: BFD_RELOC_ALPHA_HINT
The HINT relocation indicates a value that should be filled into the "hint" field of a jmp/jsr/ret instruction, for possible branch- prediction logic which may be provided on some processors.
: BFD_RELOC_ALPHA_LINKAGE
The LINKAGE relocation outputs a linkage pair in the object file, which is filled by the linker.
: BFD_RELOC_ALPHA_CODEADDR
The CODEADDR relocation outputs a STO_CA in the object file, which is filled by the linker.
: BFD_RELOC_MIPS_JMP
Bits 27..2 of the relocation address shifted right 2 bits; simple reloc otherwise.
: BFD_RELOC_MIPS16_JMP
The MIPS16 jump instruction.
: BFD_RELOC_MIPS16_GPREL
MIPS16 GP relative reloc.
: BFD_RELOC_HI16
High 16 bits of 32-bit value; simple reloc.
: BFD_RELOC_HI16_S
High 16 bits of 32-bit value but the low 16 bits will be sign extended and added to form the final result. If the low 16 bits form a negative number, we need to add one to the high value to compensate for the borrow when the low bits are added.
: BFD_RELOC_LO16
Low 16 bits.
: BFD_RELOC_PCREL_HI16_S
Like BFD_RELOC_HI16_S, but PC relative.
: BFD_RELOC_PCREL_LO16
Like BFD_RELOC_LO16, but PC relative.
: BFD_RELOC_MIPS_GPREL
Relocation relative to the global pointer.
: BFD_RELOC_MIPS_LITERAL
Relocation against a MIPS literal section.
: BFD_RELOC_MIPS_GOT16
: BFD_RELOC_MIPS_CALL16
: BFD_RELOC_MIPS_GPREL32
: BFD_RELOC_MIPS_GOT_HI16
: BFD_RELOC_MIPS_GOT_LO16
: BFD_RELOC_MIPS_CALL_HI16
: BFD_RELOC_MIPS_CALL_LO16
MIPS ELF relocations.
: BFD_RELOC_386_GOT32
: BFD_RELOC_386_PLT32
: BFD_RELOC_386_COPY
: BFD_RELOC_386_GLOB_DAT
: BFD_RELOC_386_JUMP_SLOT
: BFD_RELOC_386_RELATIVE
: BFD_RELOC_386_GOTOFF
: BFD_RELOC_386_GOTPC
i386/elf relocations
: BFD_RELOC_NS32K_IMM_8
: BFD_RELOC_NS32K_IMM_16
: BFD_RELOC_NS32K_IMM_32
: BFD_RELOC_NS32K_IMM_8_PCREL
: BFD_RELOC_NS32K_IMM_16_PCREL
: BFD_RELOC_NS32K_IMM_32_PCREL
: BFD_RELOC_NS32K_DISP_8
: BFD_RELOC_NS32K_DISP_16
: BFD_RELOC_NS32K_DISP_32
: BFD_RELOC_NS32K_DISP_8_PCREL
: BFD_RELOC_NS32K_DISP_16_PCREL
: BFD_RELOC_NS32K_DISP_32_PCREL
ns32k relocations
: BFD_RELOC_PPC_B26
: BFD_RELOC_PPC_BA26
: BFD_RELOC_PPC_TOC16
: BFD_RELOC_PPC_B16
: BFD_RELOC_PPC_B16_BRTAKEN
: BFD_RELOC_PPC_B16_BRNTAKEN
: BFD_RELOC_PPC_BA16
: BFD_RELOC_PPC_BA16_BRTAKEN
: BFD_RELOC_PPC_BA16_BRNTAKEN
: BFD_RELOC_PPC_COPY
: BFD_RELOC_PPC_GLOB_DAT
: BFD_RELOC_PPC_JMP_SLOT
: BFD_RELOC_PPC_RELATIVE
: BFD_RELOC_PPC_LOCAL24PC
: BFD_RELOC_PPC_EMB_NADDR32
: BFD_RELOC_PPC_EMB_NADDR16
: BFD_RELOC_PPC_EMB_NADDR16_LO
: BFD_RELOC_PPC_EMB_NADDR16_HI
: BFD_RELOC_PPC_EMB_NADDR16_HA
: BFD_RELOC_PPC_EMB_SDAI16
: BFD_RELOC_PPC_EMB_SDA2I16
: BFD_RELOC_PPC_EMB_SDA2REL
: BFD_RELOC_PPC_EMB_SDA21
: BFD_RELOC_PPC_EMB_MRKREF
: BFD_RELOC_PPC_EMB_RELSEC16
: BFD_RELOC_PPC_EMB_RELST_LO
: BFD_RELOC_PPC_EMB_RELST_HI
: BFD_RELOC_PPC_EMB_RELST_HA
: BFD_RELOC_PPC_EMB_BIT_FLD
: BFD_RELOC_PPC_EMB_RELSDA
Power(rs6000) and PowerPC relocations.
: BFD_RELOC_CTOR
The type of reloc used to build a contructor table - at the moment probably a 32 bit wide absolute relocation, but the target can choose. It generally does map to one of the other relocation types.
: BFD_RELOC_ARM_PCREL_BRANCH
ARM 26 bit pc-relative branch. The lowest two bits must be zero and are not stored in the instruction.
: BFD_RELOC_ARM_IMMEDIATE
: BFD_RELOC_ARM_OFFSET_IMM
: BFD_RELOC_ARM_SHIFT_IMM
: BFD_RELOC_ARM_SWI
: BFD_RELOC_ARM_MULTI
: BFD_RELOC_ARM_CP_OFF_IMM
: BFD_RELOC_ARM_ADR_IMM
: BFD_RELOC_ARM_LDR_IMM
: BFD_RELOC_ARM_LITERAL
: BFD_RELOC_ARM_IN_POOL
: BFD_RELOC_ARM_OFFSET_IMM8
: BFD_RELOC_ARM_HWLITERAL
: BFD_RELOC_ARM_THUMB_ADD
: BFD_RELOC_ARM_THUMB_IMM
: BFD_RELOC_ARM_THUMB_SHIFT
: BFD_RELOC_ARM_THUMB_OFFSET
These relocs are only used within the ARM assembler. They are not (at present) written to any object files.
: BFD_RELOC_SH_PCDISP8BY2
: BFD_RELOC_SH_PCDISP12BY2
: BFD_RELOC_SH_IMM4
: BFD_RELOC_SH_IMM4BY2
: BFD_RELOC_SH_IMM4BY4
: BFD_RELOC_SH_IMM8
: BFD_RELOC_SH_IMM8BY2
: BFD_RELOC_SH_IMM8BY4
: BFD_RELOC_SH_PCRELIMM8BY2
: BFD_RELOC_SH_PCRELIMM8BY4
: BFD_RELOC_SH_SWITCH16
: BFD_RELOC_SH_SWITCH32
: BFD_RELOC_SH_USES
: BFD_RELOC_SH_COUNT
: BFD_RELOC_SH_ALIGN
: BFD_RELOC_SH_CODE
: BFD_RELOC_SH_DATA
: BFD_RELOC_SH_LABEL
Hitachi SH relocs. Not all of these appear in object files.
: BFD_RELOC_THUMB_PCREL_BRANCH9
: BFD_RELOC_THUMB_PCREL_BRANCH12
: BFD_RELOC_THUMB_PCREL_BRANCH23
Thumb 23-, 12- and 9-bit pc-relative branches. The lowest bit must be zero and is not stored in the instruction.
: BFD_RELOC_ARC_B22_PCREL
Argonaut RISC Core (ARC) relocs. ARC 22 bit pc-relative branch. The lowest two bits must be zero and are not stored in the instruction. The high 20 bits are installed in bits 26 through 7 of the instruction.
: BFD_RELOC_ARC_B26
ARC 26 bit absolute branch. The lowest two bits must be zero and are not stored in the instruction. The high 24 bits are installed in bits 23 through 0.
: BFD_RELOC_D10V_10_PCREL_R
Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2 bits assumed to be 0.
: BFD_RELOC_D10V_10_PCREL_L
Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2 bits assumed to be 0. This is the same as the previous reloc except it is in the left container, i.e., shifted left 15 bits.
: BFD_RELOC_D10V_18
This is an 18-bit reloc with the right 2 bits assumed to be 0.
: BFD_RELOC_D10V_18_PCREL
This is an 18-bit reloc with the right 2 bits assumed to be 0.
: BFD_RELOC_M32R_24
Mitsubishi M32R relocs. This is a 24 bit absolute address.
: BFD_RELOC_M32R_10_PCREL
This is a 10-bit pc-relative reloc with the right 2 bits assumed to be 0.
: BFD_RELOC_M32R_18_PCREL
This is an 18-bit reloc with the right 2 bits assumed to be 0.
: BFD_RELOC_M32R_26_PCREL
This is a 26-bit reloc with the right 2 bits assumed to be 0.
: BFD_RELOC_M32R_HI16_ULO
This is a 16-bit reloc containing the high 16 bits of an address used when the lower 16 bits are treated as unsigned.
: BFD_RELOC_M32R_HI16_SLO
This is a 16-bit reloc containing the high 16 bits of an address used when the lower 16 bits are treated as signed.
: BFD_RELOC_M32R_LO16
This is a 16-bit reloc containing the lower 16 bits of an address.
: BFD_RELOC_M32R_SDA16
This is a 16-bit reloc containing the small data area offset for use in add3, load, and store instructions.
: BFD_RELOC_V850_9_PCREL
This is a 9-bit reloc
: BFD_RELOC_V850_22_PCREL
This is a 22-bit reloc
: BFD_RELOC_V850_SDA_16_16_OFFSET
This is a 16 bit offset from the short data area pointer.
: BFD_RELOC_V850_SDA_15_16_OFFSET
This is a 16 bit offset (of which only 15 bits are used) from the short data area pointer.
: BFD_RELOC_V850_ZDA_16_16_OFFSET
This is a 16 bit offset from the zero data area pointer.
: BFD_RELOC_V850_ZDA_15_16_OFFSET
This is a 16 bit offset (of which only 15 bits are used) from the zero data area pointer.
: BFD_RELOC_V850_TDA_6_8_OFFSET
This is an 8 bit offset (of which only 6 bits are used) from the tiny data area pointer.
: BFD_RELOC_V850_TDA_7_8_OFFSET
This is an 8bit offset (of which only 7 bits are used) from the tiny data area pointer.
: BFD_RELOC_V850_TDA_7_7_OFFSET
This is a 7 bit offset from the tiny data area pointer.
: BFD_RELOC_V850_TDA_16_16_OFFSET
This is a 16 bit offset from the tiny data area pointer.
: BFD_RELOC_MN10300_32_PCREL
This is a 32bit pcrel reloc for the mn10300, offset by two bytes in the instruction.
: BFD_RELOC_MN10300_16_PCREL
This is a 16bit pcrel reloc for the mn10300, offset by two bytes in the instruction.
: BFD_RELOC_TIC30_LDP
This is a 8bit DP reloc for the tms320c30, where the most significant 8 bits of a 24 bit word are placed into the least significant 8 bits of the opcode.

typedef enum bfd_reloc_code_real bfd_reloc_code_real_type;

bfd_reloc_type_lookup

Synopsis

reloc_howto_type *
bfd_reloc_type_lookup (bfd *abfd, bfd_reloc_code_real_type code);

Description
Return a pointer to a howto structure which, when invoked, will perform the relocation code on data from the architecture noted.

bfd_default_reloc_type_lookup

Synopsis

reloc_howto_type *bfd_default_reloc_type_lookup
   (bfd *abfd, bfd_reloc_code_real_type  code);

Description
Provides a default relocation lookup routine for any architecture.

bfd_get_reloc_code_name

Synopsis

const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code);

Description
Provides a printable name for the supplied relocation code. Useful mainly for printing error messages.

bfd_generic_relax_section

Synopsis

boolean bfd_generic_relax_section
   (bfd *abfd,
    asection *section,
    struct bfd_link_info *,
    boolean *);

Description
Provides default handling for relaxing for back ends which don't do relaxing -- i.e., does nothing.

bfd_generic_get_relocated_section_contents

Synopsis

bfd_byte *
bfd_generic_get_relocated_section_contents (bfd *abfd,
    struct bfd_link_info *link_info,
    struct bfd_link_order *link_order,
    bfd_byte *data,
    boolean relocateable,
    asymbol **symbols);

Description
Provides default handling of relocation effort for back ends which can't be bothered to do it efficiently.

Core files

Description
These are functions pertaining to core files.

bfd_core_file_failing_command

Synopsis

CONST char *bfd_core_file_failing_command(bfd *abfd);

Description
Return a read-only string explaining which program was running when it failed and produced the core file abfd.

bfd_core_file_failing_signal

Synopsis

int bfd_core_file_failing_signal(bfd *abfd);

Description
Returns the signal number which caused the core dump which generated the file the BFD abfd is attached to.

core_file_matches_executable_p

Synopsis

boolean core_file_matches_executable_p
   (bfd *core_bfd, bfd *exec_bfd);

Description
Return true if the core file attached to core_bfd was generated by a run of the executable file attached to exec_bfd, false otherwise.

Targets

Description
Each port of BFD to a different machine requries the creation of a target back end. All the back end provides to the root part of BFD is a structure containing pointers to functions which perform certain low level operations on files. BFD translates the applications's requests through a pointer into calls to the back end routines.

When a file is opened with bfd_openr, its format and target are unknown. BFD uses various mechanisms to determine how to interpret the file. The operations performed are:

  • Create a BFD by calling the internal routine _bfd_new_bfd, then call bfd_find_target with the target string supplied to bfd_openr and the new BFD pointer.
  • If a null target string was provided to bfd_find_target, look up the environment variable GNUTARGET and use that as the target string.
  • If the target string is still NULL, or the target string is default, then use the first item in the target vector as the target type, and set target_defaulted in the BFD to cause bfd_check_format to loop through all the targets. See section bfd_target. See section File formats.
  • Otherwise, inspect the elements in the target vector one by one, until a match on target name is found. When found, use it.
  • Otherwise return the error bfd_error_invalid_target to bfd_openr.
  • bfd_openr attempts to open the file using bfd_open_file, and returns the BFD.

Once the BFD has been opened and the target selected, the file format may be determined. This is done by calling bfd_check_format on the BFD with a suggested format. If target_defaulted has been set, each possible target type is tried to see if it recognizes the specified format. bfd_check_format returns true when the caller guesses right.

bfd_target

Description
This structure contains everything that BFD knows about a target. It includes things like its byte order, name, and which routines to call to do various operations.

Every BFD points to a target structure with its xvec member.

The macros below are used to dispatch to functions through the bfd_target vector. They are used in a number of macros further down in `bfd.h', and are also used when calling various routines by hand inside the BFD implementation. The arglist argument must be parenthesized; it contains all the arguments to the called function.

They make the documentation (more) unpleasant to read, so if someone wants to fix this and not break the above, please do.

#define BFD_SEND(bfd, message, arglist) \
               ((*((bfd)->xvec->message)) arglist)

#ifdef DEBUG_BFD_SEND
#undef BFD_SEND
#define BFD_SEND(bfd, message, arglist) \
  (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
    ((*((bfd)->xvec->message)) arglist) : \
    (bfd_assert (__FILE__,__LINE__), NULL))
#endif

For operations which index on the BFD format:

#define BFD_SEND_FMT(bfd, message, arglist) \
            (((bfd)->xvec->message[(int)((bfd)->format)]) arglist)

#ifdef DEBUG_BFD_SEND
#undef BFD_SEND_FMT
#define BFD_SEND_FMT(bfd, message, arglist) \
  (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
   (((bfd)->xvec->message[(int)((bfd)->format)]) arglist) : \
   (bfd_assert (__FILE__,__LINE__), NULL))
#endif

This is the structure which defines the type of BFD this is. The xvec member of the struct bfd itself points here. Each module that implements access to a different target under BFD, defines one of these.

FIXME, these names should be rationalised with the names of the entry points which call them. Too bad we can't have one macro to define them both!

enum bfd_flavour {
  bfd_target_unknown_flavour,
  bfd_target_aout_flavour,
  bfd_target_coff_flavour,
  bfd_target_ecoff_flavour,
  bfd_target_elf_flavour,
  bfd_target_ieee_flavour,
  bfd_target_nlm_flavour,
  bfd_target_oasys_flavour,
  bfd_target_tekhex_flavour,
  bfd_target_srec_flavour,
  bfd_target_ihex_flavour,
  bfd_target_som_flavour,
  bfd_target_os9k_flavour,
  bfd_target_versados_flavour,
  bfd_target_msdos_flavour,
  bfd_target_evax_flavour
};

enum bfd_endian { BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN };

 /* Forward declaration.  */
typedef struct bfd_link_info _bfd_link_info;

typedef struct bfd_target
{

Identifies the kind of target, e.g., SunOS4, Ultrix, etc.

  char *name;

The "flavour" of a back end is a general indication about the contents of a file.

  enum bfd_flavour flavour;

The order of bytes within the data area of a file.

  enum bfd_endian byteorder;

The order of bytes within the header parts of a file.

  enum bfd_endian header_byteorder;

A mask of all the flags which an executable may have set - from the set BFD_NO_FLAGS, HAS_RELOC, ...D_PAGED.

  flagword object_flags;

A mask of all the flags which a section may have set - from the set SEC_NO_FLAGS, SEC_ALLOC, ...SET_NEVER_LOAD.

  flagword section_flags;

The character normally found at the front of a symbol (if any), perhaps `_'.

  char symbol_leading_char;

The pad character for file names within an archive header.

  char ar_pad_char;

The maximum number of characters in an archive header.

  unsigned short ar_max_namelen;

Entries for byte swapping for data. These are different from the other entry points, since they don't take a BFD asthe first argument. Certain other handlers could do the same.

  bfd_vma      (*bfd_getx64) PARAMS ((const bfd_byte *));
  bfd_signed_vma (*bfd_getx_signed_64) PARAMS ((const bfd_byte *));
  void         (*bfd_putx64) PARAMS ((bfd_vma, bfd_byte *));
  bfd_vma      (*bfd_getx32) PARAMS ((const bfd_byte *));
  bfd_signed_vma (*bfd_getx_signed_32) PARAMS ((const bfd_byte *));
  void         (*bfd_putx32) PARAMS ((bfd_vma, bfd_byte *));
  bfd_vma      (*bfd_getx16) PARAMS ((const bfd_byte *));
  bfd_signed_vma (*bfd_getx_signed_16) PARAMS ((const bfd_byte *));
  void         (*bfd_putx16) PARAMS ((bfd_vma, bfd_byte *));

Byte swapping for the headers

  bfd_vma      (*bfd_h_getx64) PARAMS ((const bfd_byte *));
  bfd_signed_vma (*bfd_h_getx_signed_64) PARAMS ((const bfd_byte *));
  void         (*bfd_h_putx64) PARAMS ((bfd_vma, bfd_byte *));
  bfd_vma      (*bfd_h_getx32) PARAMS ((const bfd_byte *));
  bfd_signed_vma (*bfd_h_getx_signed_32) PARAMS ((const bfd_byte *));
  void         (*bfd_h_putx32) PARAMS ((bfd_vma, bfd_byte *));
  bfd_vma      (*bfd_h_getx16) PARAMS ((const bfd_byte *));
  bfd_signed_vma (*bfd_h_getx_signed_16) PARAMS ((const bfd_byte *));
  void         (*bfd_h_putx16) PARAMS ((bfd_vma, bfd_byte *));

Format dependent routines: these are vectors of entry points within the target vector structure, one for each format to check.

Check the format of a file being read. Return a bfd_target * or zero.

  const struct bfd_target *(*_bfd_check_format[bfd_type_end]) PARAMS ((bfd *));

Set the format of a file being written.

  boolean             (*_bfd_set_format[bfd_type_end]) PARAMS ((bfd *));

Write cached information into a file being written, at bfd_close.

  boolean             (*_bfd_write_contents[bfd_type_end]) PARAMS ((bfd *));

The general target vector.

   /* Generic entry points.  */
#define BFD_JUMP_TABLE_GENERIC(NAME)\
CAT(NAME,_close_and_cleanup),\
CAT(NAME,_bfd_free_cached_info),\
CAT(NAME,_new_section_hook),\
CAT(NAME,_get_section_contents),\
CAT(NAME,_get_section_contents_in_window)

   /* Called when the BFD is being closed to do any necessary cleanup.  */
  boolean       (*_close_and_cleanup) PARAMS ((bfd *));
   /* Ask the BFD to free all cached information.  */
  boolean (*_bfd_free_cached_info) PARAMS ((bfd *));
   /* Called when a new section is created.  */
  boolean       (*_new_section_hook) PARAMS ((bfd *, sec_ptr));
   /* Read the contents of a section.  */
  boolean       (*_bfd_get_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
                                            file_ptr, bfd_size_type));
  boolean       (*_bfd_get_section_contents_in_window)
                          PARAMS ((bfd *, sec_ptr, bfd_window *,
                                   file_ptr, bfd_size_type));

   /* Entry points to copy private data.  */
#define BFD_JUMP_TABLE_COPY(NAME)\
CAT(NAME,_bfd_copy_private_bfd_data),\
CAT(NAME,_bfd_merge_private_bfd_data),\
CAT(NAME,_bfd_copy_private_section_data),\
CAT(NAME,_bfd_copy_private_symbol_data),\
CAT(NAME,_bfd_set_private_flags),\
CAT(NAME,_bfd_print_private_bfd_data)\
   /* Called to copy BFD general private data from one object file
     to another.  */
  boolean       (*_bfd_copy_private_bfd_data) PARAMS ((bfd *, bfd *));
   /* Called to merge BFD general private data from one object file
     to a common output file when linking.  */
  boolean       (*_bfd_merge_private_bfd_data) PARAMS ((bfd *, bfd *));
   /* Called to copy BFD private section data from one object file
     to another.  */
  boolean       (*_bfd_copy_private_section_data) PARAMS ((bfd *, sec_ptr,
                                                       bfd *, sec_ptr));
   /* Called to copy BFD private symbol data from one symbol
     to another.  */
  boolean       (*_bfd_copy_private_symbol_data) PARAMS ((bfd *, asymbol *,
                                                          bfd *, asymbol *));
   /* Called to set private backend flags */
  boolean       (*_bfd_set_private_flags) PARAMS ((bfd *, flagword));

   /* Called to print private BFD data */
  boolean       (*_bfd_print_private_bfd_data) PARAMS ((bfd *, PTR));

   /* Core file entry points.  */
#define BFD_JUMP_TABLE_CORE(NAME)\
CAT(NAME,_core_file_failing_command),\
CAT(NAME,_core_file_failing_signal),\
CAT(NAME,_core_file_matches_executable_p)
  char *   (*_core_file_failing_command) PARAMS ((bfd *));
  int      (*_core_file_failing_signal) PARAMS ((bfd *));
  boolean  (*_core_file_matches_executable_p) PARAMS ((bfd *, bfd *));

   /* Archive entry points.  */
#define BFD_JUMP_TABLE_ARCHIVE(NAME)\
CAT(NAME,_slurp_armap),\
CAT(NAME,_slurp_extended_name_table),\
CAT(NAME,_construct_extended_name_table),\
CAT(NAME,_truncate_arname),\
CAT(NAME,_write_armap),\
CAT(NAME,_read_ar_hdr),\
CAT(NAME,_openr_next_archived_file),\
CAT(NAME,_get_elt_at_index),\
CAT(NAME,_generic_stat_arch_elt),\
CAT(NAME,_update_armap_timestamp)
  boolean  (*_bfd_slurp_armap) PARAMS ((bfd *));
  boolean  (*_bfd_slurp_extended_name_table) PARAMS ((bfd *));
  boolean  (*_bfd_construct_extended_name_table)
             PARAMS ((bfd *, char **, bfd_size_type *, const char **));
  void     (*_bfd_truncate_arname) PARAMS ((bfd *, CONST char *, char *));
  boolean  (*write_armap) PARAMS ((bfd *arch,
                              unsigned int elength,
                              struct orl *map,
                              unsigned int orl_count,
                              int stridx));
  PTR (*_bfd_read_ar_hdr_fn) PARAMS ((bfd *));
  bfd *    (*openr_next_archived_file) PARAMS ((bfd *arch, bfd *prev));
#define bfd_get_elt_at_index(b,i) BFD_SEND(b, _bfd_get_elt_at_index, (b,i))
  bfd *    (*_bfd_get_elt_at_index) PARAMS ((bfd *, symindex));
  int      (*_bfd_stat_arch_elt) PARAMS ((bfd *, struct stat *));
  boolean  (*_bfd_update_armap_timestamp) PARAMS ((bfd *));

   /* Entry points used for symbols.  */
#define BFD_JUMP_TABLE_SYMBOLS(NAME)\
CAT(NAME,_get_symtab_upper_bound),\
CAT(NAME,_get_symtab),\
CAT(NAME,_make_empty_symbol),\
CAT(NAME,_print_symbol),\
CAT(NAME,_get_symbol_info),\
CAT(NAME,_bfd_is_local_label_name),\
CAT(NAME,_get_lineno),\
CAT(NAME,_find_nearest_line),\
CAT(NAME,_bfd_make_debug_symbol),\
CAT(NAME,_read_minisymbols),\
CAT(NAME,_minisymbol_to_symbol)
  long  (*_bfd_get_symtab_upper_bound) PARAMS ((bfd *));
  long  (*_bfd_canonicalize_symtab) PARAMS ((bfd *,
                                             struct symbol_cache_entry **));
  struct symbol_cache_entry  *
                (*_bfd_make_empty_symbol) PARAMS ((bfd *));
  void          (*_bfd_print_symbol) PARAMS ((bfd *, PTR,
                                      struct symbol_cache_entry *,
                                      bfd_print_symbol_type));
#define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
  void          (*_bfd_get_symbol_info) PARAMS ((bfd *,
                                      struct symbol_cache_entry *,
                                      symbol_info *));
#define bfd_get_symbol_info(b,p,e) BFD_SEND(b, _bfd_get_symbol_info, (b,p,e))
  boolean       (*_bfd_is_local_label_name) PARAMS ((bfd *, const char *));

  alent *    (*_get_lineno) PARAMS ((bfd *, struct symbol_cache_entry *));
  boolean    (*_bfd_find_nearest_line) PARAMS ((bfd *abfd,
                    struct sec *section, struct symbol_cache_entry **symbols,
                    bfd_vma offset, CONST char **file, CONST char **func,
                    unsigned int *line));
  /* Back-door to allow format-aware applications to create debug symbols
    while using BFD for everything else.  Currently used by the assembler
    when creating COFF files.  */
  asymbol *  (*_bfd_make_debug_symbol) PARAMS ((
       bfd *abfd,
       void *ptr,
       unsigned long size));
#define bfd_read_minisymbols(b, d, m, s) \
  BFD_SEND (b, _read_minisymbols, (b, d, m, s))
  long  (*_read_minisymbols) PARAMS ((bfd *, boolean, PTR *,
                                      unsigned int *));
#define bfd_minisymbol_to_symbol(b, d, m, f) \
  BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
  asymbol *(*_minisymbol_to_symbol) PARAMS ((bfd *, boolean, const PTR,
                                             asymbol *));

   /* Routines for relocs.  */
#define BFD_JUMP_TABLE_RELOCS(NAME)\
CAT(NAME,_get_reloc_upper_bound),\
CAT(NAME,_canonicalize_reloc),\
CAT(NAME,_bfd_reloc_type_lookup)
  long  (*_get_reloc_upper_bound) PARAMS ((bfd *, sec_ptr));
  long  (*_bfd_canonicalize_reloc) PARAMS ((bfd *, sec_ptr, arelent **,
                                            struct symbol_cache_entry **));
   /* See documentation on reloc types.  */
  reloc_howto_type *
       (*reloc_type_lookup) PARAMS ((bfd *abfd,
                                     bfd_reloc_code_real_type code));

   /* Routines used when writing an object file.  */
#define BFD_JUMP_TABLE_WRITE(NAME)\
CAT(NAME,_set_arch_mach),\
CAT(NAME,_set_section_contents)
  boolean    (*_bfd_set_arch_mach) PARAMS ((bfd *, enum bfd_architecture,
                    unsigned long));
  boolean       (*_bfd_set_section_contents) PARAMS ((bfd *, sec_ptr, PTR,
                                            file_ptr, bfd_size_type));

   /* Routines used by the linker.  */
#define BFD_JUMP_TABLE_LINK(NAME)\
CAT(NAME,_sizeof_headers),\
CAT(NAME,_bfd_get_relocated_section_contents),\
CAT(NAME,_bfd_relax_section),\
CAT(NAME,_bfd_link_hash_table_create),\
CAT(NAME,_bfd_link_add_symbols),\
CAT(NAME,_bfd_final_link),\
CAT(NAME,_bfd_link_split_section)
  int        (*_bfd_sizeof_headers) PARAMS ((bfd *, boolean));
  bfd_byte * (*_bfd_get_relocated_section_contents) PARAMS ((bfd *,
                    struct bfd_link_info *, struct bfd_link_order *,
                    bfd_byte *data, boolean relocateable,
                    struct symbol_cache_entry **));

  boolean    (*_bfd_relax_section) PARAMS ((bfd *, struct sec *,
                    struct bfd_link_info *, boolean *again));

   /* Create a hash table for the linker.  Different backends store
     different information in this table.  */
  struct bfd_link_hash_table *(*_bfd_link_hash_table_create) PARAMS ((bfd *));

   /* Add symbols from this object file into the hash table.  */
  boolean (*_bfd_link_add_symbols) PARAMS ((bfd *, struct bfd_link_info *));

   /* Do a link based on the link_order structures attached to each
     section of the BFD.  */
  boolean (*_bfd_final_link) PARAMS ((bfd *, struct bfd_link_info *));

   /* Should this section be split up into smaller pieces during linking.  */
  boolean (*_bfd_link_split_section) PARAMS ((bfd *, struct sec *));

  /* Routines to handle dynamic symbols and relocs.  */
#define BFD_JUMP_TABLE_DYNAMIC(NAME)\
CAT(NAME,_get_dynamic_symtab_upper_bound),\
CAT(NAME,_canonicalize_dynamic_symtab),\
CAT(NAME,_get_dynamic_reloc_upper_bound),\
CAT(NAME,_canonicalize_dynamic_reloc)
   /* Get the amount of memory required to hold the dynamic symbols. */
  long  (*_bfd_get_dynamic_symtab_upper_bound) PARAMS ((bfd *));
   /* Read in the dynamic symbols.  */
  long  (*_bfd_canonicalize_dynamic_symtab)
    PARAMS ((bfd *, struct symbol_cache_entry **));
   /* Get the amount of memory required to hold the dynamic relocs.  */
  long  (*_bfd_get_dynamic_reloc_upper_bound) PARAMS ((bfd *));
   /* Read in the dynamic relocs.  */
  long  (*_bfd_canonicalize_dynamic_reloc)
    PARAMS ((bfd *, arelent **, struct symbol_cache_entry **));

Data for use by back-end routines, which isn't generic enough to belong in this structure.

 PTR backend_data;
} bfd_target;

bfd_set_default_target

Synopsis

boolean bfd_set_default_target (const char *name);

Description
Set the default target vector to use when recognizing a BFD. This takes the name of the target, which may be a BFD target name or a configuration triplet.

bfd_find_target

Synopsis

const bfd_target *bfd_find_target(CONST char *target_name, bfd *abfd);

Description
Return a pointer to the transfer vector for the object target named target_name. If target_name is NULL, choose the one in the environment variable GNUTARGET; if that is null or not defined, then choose the first entry in the target list. Passing in the string "default" or setting the environment variable to "default" will cause the first entry in the target list to be returned, and "target_defaulted" will be set in the BFD. This causes bfd_check_format to loop over all the targets to find the one that matches the file being read.

bfd_target_list

Synopsis

const char **bfd_target_list(void);

Description
Return a freshly malloced NULL-terminated vector of the names of all the valid BFD targets. Do not modify the names.

Architectures

BFD keeps one atom in a BFD describing the architecture of the data attached to the BFD: a pointer to a bfd_arch_info_type.

Pointers to structures can be requested independently of a BFD so that an architecture's information can be interrogated without access to an open BFD.

The architecture information is provided by each architecture package. The set of default architectures is selected by the macro SELECT_ARCHITECTURES. This is normally set up in the `config/target.mt' file of your choice. If the name is not defined, then all the architectures supported are included.

When BFD starts up, all the architectures are called with an initialize method. It is up to the architecture back end to insert as many items into the list of architectures as it wants to; generally this would be one for each machine and one for the default case (an item with a machine field of 0).

BFD's idea of an architecture is implemented in `archures.c'.

bfd_architecture

Description
This enum gives the object file's CPU architecture, in a global sense--i.e., what processor family does it belong to? Another field indicates which processor within the family is in use. The machine gives a number which distinguishes different versions of the architecture, containing, for example, 2 and 3 for Intel i960 KA and i960 KB, and 68020 and 68030 for Motorola 68020 and 68030.

enum bfd_architecture
{
  bfd_arch_unknown,    /* File arch not known */
  bfd_arch_obscure,    /* Arch known, not one of these */
  bfd_arch_m68k,       /* Motorola 68xxx */
#define bfd_mach_m68000 1
#define bfd_mach_m68008 2
#define bfd_mach_m68010 3
#define bfd_mach_m68020 4
#define bfd_mach_m68030 5
#define bfd_mach_m68040 6
#define bfd_mach_m68060 7
  bfd_arch_vax,        /* DEC Vax */
  bfd_arch_i960,       /* Intel 960 */
     /* The order of the following is important.
       lower number indicates a machine type that
       only accepts a subset of the instructions
       available to machines with higher numbers.
       The exception is the "ca", which is
       incompatible with all other machines except
       "core". */

#define bfd_mach_i960_core      1
#define bfd_mach_i960_ka_sa     2
#define bfd_mach_i960_kb_sb     3
#define bfd_mach_i960_mc        4
#define bfd_mach_i960_xa        5
#define bfd_mach_i960_ca        6
#define bfd_mach_i960_jx        7
#define bfd_mach_i960_hx        8

  bfd_arch_a29k,       /* AMD 29000 */
  bfd_arch_sparc,      /* SPARC */
#define bfd_mach_sparc                 1
 /* The difference between v8plus and v9 is that v9 is a true 64 bit env.  */
#define bfd_mach_sparc_sparclet        2
#define bfd_mach_sparc_sparclite       3
#define bfd_mach_sparc_v8plus          4
#define bfd_mach_sparc_v8plusa         5  /* with ultrasparc add'ns */
#define bfd_mach_sparc_v9              6
#define bfd_mach_sparc_v9a             7  /* with ultrasparc add'ns */
 /* Nonzero if MACH has the v9 instruction set.  */
#define bfd_mach_sparc_v9_p(mach) \
  ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9a)
  bfd_arch_mips,       /* MIPS Rxxxx */
#define bfd_mach_mips3000              3000
#define bfd_mach_mips3900              3900
#define bfd_mach_mips4000              4000
#define bfd_mach_mips4010              4010
#define bfd_mach_mips4100              4100
#define bfd_mach_mips4300              4300
#define bfd_mach_mips4400              4400
#define bfd_mach_mips4600              4600
#define bfd_mach_mips4650              4650
#define bfd_mach_mips5000              5000
#define bfd_mach_mips6000              6000
#define bfd_mach_mips8000              8000
#define bfd_mach_mips10000             10000
#define bfd_mach_mips16                16
  bfd_arch_i386,       /* Intel 386 */
#define bfd_mach_i386_i386 0
#define bfd_mach_i386_i8086 1
  bfd_arch_we32k,      /* AT&T WE32xxx */
  bfd_arch_tahoe,      /* CCI/Harris Tahoe */
  bfd_arch_i860,       /* Intel 860 */
  bfd_arch_romp,       /* IBM ROMP PC/RT */
  bfd_arch_alliant,    /* Alliant */
  bfd_arch_convex,     /* Convex */
  bfd_arch_m88k,       /* Motorola 88xxx */
  bfd_arch_pyramid,    /* Pyramid Technology */
  bfd_arch_h8300,      /* Hitachi H8/300 */
#define bfd_mach_h8300   1
#define bfd_mach_h8300h  2
#define bfd_mach_h8300s  3
  bfd_arch_powerpc,    /* PowerPC */
  bfd_arch_rs6000,     /* IBM RS/6000 */
  bfd_arch_hppa,       /* HP PA RISC */
  bfd_arch_d10v,       /* Mitsubishi D10V */
  bfd_arch_z8k,        /* Zilog Z8000 */
#define bfd_mach_z8001         1
#define bfd_mach_z8002         2
  bfd_arch_h8500,      /* Hitachi H8/500 */
  bfd_arch_sh,         /* Hitachi SH */
#define bfd_mach_sh            0
#define bfd_mach_sh3        0x30
#define bfd_mach_sh3e       0x3e
#define bfd_mach_sh4        0x40
  bfd_arch_alpha,      /* Dec Alpha */
  bfd_arch_arm,        /* Advanced Risc Machines ARM */
#define bfd_mach_arm_2         1
#define bfd_mach_arm_2a                2
#define bfd_mach_arm_3         3
#define bfd_mach_arm_3M        4
#define bfd_mach_arm_4                 5
#define bfd_mach_arm_4T        6
  bfd_arch_ns32k,      /* National Semiconductors ns32000 */
  bfd_arch_w65,        /* WDC 65816 */
  bfd_arch_tic30,      /* Texas Instruments TMS320C30 */
  bfd_arch_v850,       /* NEC V850 */
#define bfd_mach_v850          0
  bfd_arch_arc,        /* Argonaut RISC Core */
#define bfd_mach_arc_base 0
  bfd_arch_m32r,       /* Mitsubishi M32R/D */
#define bfd_mach_m32r          0  /* backwards compatibility */
  bfd_arch_mn10200,    /* Matsushita MN10200 */
  bfd_arch_mn10300,    /* Matsushita MN10300 */
  bfd_arch_last
  };

bfd_arch_info

Description
This structure contains information on architectures for use within BFD.

typedef struct bfd_arch_info
{
  int bits_per_word;
  int bits_per_address;
  int bits_per_byte;
  enum bfd_architecture arch;
  unsigned long mach;
  const char *arch_name;
  const char *printable_name;
  unsigned int section_align_power;
  /* true if this is the default machine for the architecture */
  boolean the_default;
  const struct bfd_arch_info * (*compatible)
       PARAMS ((const struct bfd_arch_info *a,
                const struct bfd_arch_info *b));

  boolean (*scan) PARAMS ((const struct bfd_arch_info *, const char *));

  const struct bfd_arch_info *next;
} bfd_arch_info_type;

bfd_printable_name

Synopsis

const char *bfd_printable_name(bfd *abfd);

Description
Return a printable string representing the architecture and machine from the pointer to the architecture info structure.

bfd_scan_arch

Synopsis

const bfd_arch_info_type *bfd_scan_arch(const char *string);

Description
Figure out if BFD supports any cpu which could be described with the name string. Return a pointer to an arch_info structure if a machine is found, otherwise NULL.

bfd_arch_list

Synopsis

const char **bfd_arch_list(void);

Description
Return a freshly malloced NULL-terminated vector of the names of all the valid BFD architectures. Do not modify the names.

bfd_arch_get_compatible

Synopsis

const bfd_arch_info_type *bfd_arch_get_compatible(
    const bfd *abfd,
    const bfd *bbfd);

Description
Determine whether two BFDs' architectures and machine types are compatible. Calculates the lowest common denominator between the two architectures and machine types implied by the BFDs and returns a pointer to an arch_info structure describing the compatible machine.

bfd_default_arch_struct

Description
The bfd_default_arch_struct is an item of bfd_arch_info_type which has been initialized to a fairly generic state. A BFD starts life by pointing to this structure, until the correct back end has determined the real architecture of the file.

extern const bfd_arch_info_type bfd_default_arch_struct;

bfd_set_arch_info

Synopsis

void bfd_set_arch_info(bfd *abfd, const bfd_arch_info_type *arg);

Description
Set the architecture info of abfd to arg.

bfd_default_set_arch_mach

Synopsis

boolean bfd_default_set_arch_mach(bfd *abfd,
    enum bfd_architecture arch,
    unsigned long mach);

Description
Set the architecture and machine type in BFD abfd to arch and mach. Find the correct pointer to a structure and insert it into the arch_info pointer.

bfd_get_arch

Synopsis

enum bfd_architecture bfd_get_arch(bfd *abfd);

Description
Return the enumerated type which describes the BFD abfd's architecture.

bfd_get_mach

Synopsis

unsigned long bfd_get_mach(bfd *abfd);

Description
Return the long type which describes the BFD abfd's machine.

bfd_arch_bits_per_byte

Synopsis

unsigned int bfd_arch_bits_per_byte(bfd *abfd);

Description
Return the number of bits in one of the BFD abfd's architecture's bytes.

bfd_arch_bits_per_address

Synopsis

unsigned int bfd_arch_bits_per_address(bfd *abfd);

Description
Return the number of bits in one of the BFD abfd's architecture's addresses.

bfd_default_compatible

Synopsis

const bfd_arch_info_type *bfd_default_compatible
   (const bfd_arch_info_type *a,
    const bfd_arch_info_type *b);

Description
The default function for testing for compatibility.

bfd_default_scan

Synopsis

boolean bfd_default_scan(const struct bfd_arch_info *info, const char *string);

Description
The default function for working out whether this is an architecture hit and a machine hit.

bfd_get_arch_info

Synopsis

const bfd_arch_info_type * bfd_get_arch_info(bfd *abfd);

Description
Return the architecture info struct in abfd.

bfd_lookup_arch

Synopsis

const bfd_arch_info_type *bfd_lookup_arch
   (enum bfd_architecture
    arch,
    unsigned long machine);

Description
Look for the architecure info structure which matches the arguments arch and machine. A machine of 0 matches the machine/architecture structure which marks itself as the default.

bfd_printable_arch_mach

Synopsis

const char *bfd_printable_arch_mach
   (enum bfd_architecture arch, unsigned long machine);

Description
Return a printable string representing the architecture and machine type.

This routine is depreciated.

Opening and closing BFDs

bfd_openr

Synopsis

bfd *bfd_openr(CONST char *filename, CONST char *target);

Description
Open the file filename (using fopen) with the target target. Return a pointer to the created BFD.

Calls bfd_find_target, so target is interpreted as by that function.

If NULL is returned then an error has occured. Possible errors are bfd_error_no_memory, bfd_error_invalid_target or system_call error.

bfd_fdopenr

Synopsis

bfd *bfd_fdopenr(CONST char *filename, CONST char *target, int fd);

Description
bfd_fdopenr is to bfd_fopenr much like fdopen is to fopen. It opens a BFD on a file already described by the fd supplied.

When the file is later bfd_closed, the file descriptor will be closed.

If the caller desires that this file descriptor be cached by BFD (opened as needed, closed as needed to free descriptors for other opens), with the supplied fd used as an initial file descriptor (but subject to closure at any time), call bfd_set_cacheable(bfd, 1) on the returned BFD. The default is to assume no cacheing; the file descriptor will remain open until bfd_close, and will not be affected by BFD operations on other files.

Possible errors are bfd_error_no_memory, bfd_error_invalid_target and bfd_error_system_call.

bfd_openstreamr

Synopsis

bfd *bfd_openstreamr(const char *, const char *, PTR);

Description
Open a BFD for read access on an existing stdio stream. When the BFD is passed to bfd_close, the stream will be closed.

bfd_openw

Synopsis

bfd *bfd_openw(CONST char *filename, CONST char *target);

Description
Create a BFD, associated with file filename, using the file format target, and return a pointer to it.

Possible errors are bfd_error_system_call, bfd_error_no_memory, bfd_error_invalid_target.

bfd_close

Synopsis

boolean bfd_close(bfd *abfd);

Description
Close a BFD. If the BFD was open for writing, then pending operations are completed and the file written out and closed. If the created file is executable, then chmod is called to mark it as such.

All memory attached to the BFD is released.

The file descriptor associated with the BFD is closed (even if it was passed in to BFD by bfd_fdopenr).

Returns
true is returned if all is ok, otherwise false.

bfd_close_all_done

Synopsis

boolean bfd_close_all_done(bfd *);

Description
Close a BFD. Differs from bfd_close since it does not complete any pending operations. This routine would be used if the application had just used BFD for swapping and didn't want to use any of the writing code.

If the created file is executable, then chmod is called to mark it as such.

All memory attached to the BFD is released.

Returns
true is returned if all is ok, otherwise false.

bfd_create

Synopsis

bfd *bfd_create(CONST char *filename, bfd *templ);

Description
Create a new BFD in the manner of bfd_openw, but without opening a file. The new BFD takes the target from the target used by template. The format is always set to bfd_object.

bfd_alloc

Synopsis

PTR bfd_alloc (bfd *abfd, size_t wanted);

Description
Allocate a block of wanted bytes of memory attached to abfd and return a pointer to it.

Internal functions

Description
These routines are used within BFD. They are not intended for export, but are documented here for completeness.

bfd_write_bigendian_4byte_int

Synopsis

void bfd_write_bigendian_4byte_int(bfd *abfd,  int i);

Description
Write a 4 byte integer i to the output BFD abfd, in big endian order regardless of what else is going on. This is useful in archives.

bfd_put_size

bfd_get_size

Description
These macros as used for reading and writing raw data in sections; each access (except for bytes) is vectored through the target format of the BFD and mangled accordingly. The mangling performs any necessary endian translations and removes alignment restrictions. Note that types accepted and returned by these macros are identical so they can be swapped around in macros--for example, `libaout.h' defines GET_WORD to either bfd_get_32 or bfd_get_64.

In the put routines, val must be a bfd_vma. If we are on a system without prototypes, the caller is responsible for making sure that is true, with a cast if necessary. We don't cast them in the macro definitions because that would prevent lint or gcc -Wall from detecting sins such as passing a pointer. To detect calling these with less than a bfd_vma, use gcc -Wconversion on a host with 64 bit bfd_vma's.

 /* Byte swapping macros for user section data.  */

#define bfd_put_8(abfd, val, ptr) \
                (*((unsigned char *)(ptr)) = (unsigned char)(val))
#define bfd_put_signed_8 \
               bfd_put_8
#define bfd_get_8(abfd, ptr) \
                (*(unsigned char *)(ptr))
#define bfd_get_signed_8(abfd, ptr) \
               ((*(unsigned char *)(ptr) ^ 0x80) - 0x80)

#define bfd_put_16(abfd, val, ptr) \
                BFD_SEND(abfd, bfd_putx16, ((val),(ptr)))
#define bfd_put_signed_16 \
                bfd_put_16
#define bfd_get_16(abfd, ptr) \
                BFD_SEND(abfd, bfd_getx16, (ptr))
#define bfd_get_signed_16(abfd, ptr) \
                BFD_SEND (abfd, bfd_getx_signed_16, (ptr))

#define bfd_put_32(abfd, val, ptr) \
                BFD_SEND(abfd, bfd_putx32, ((val),(ptr)))
#define bfd_put_signed_32 \
                bfd_put_32
#define bfd_get_32(abfd, ptr) \
                BFD_SEND(abfd, bfd_getx32, (ptr))
#define bfd_get_signed_32(abfd, ptr) \
                BFD_SEND(abfd, bfd_getx_signed_32, (ptr))

#define bfd_put_64(abfd, val, ptr) \
                BFD_SEND(abfd, bfd_putx64, ((val), (ptr)))
#define bfd_put_signed_64 \
                bfd_put_64
#define bfd_get_64(abfd, ptr) \
                BFD_SEND(abfd, bfd_getx64, (ptr))
#define bfd_get_signed_64(abfd, ptr) \
                BFD_SEND(abfd, bfd_getx_signed_64, (ptr))

bfd_h_put_size

Description
These macros have the same function as their bfd_get_x bretheren, except that they are used for removing information for the header records of object files. Believe it or not, some object files keep their header records in big endian order and their data in little endian order.

 /* Byte swapping macros for file header data.  */

#define bfd_h_put_8(abfd, val, ptr) \
               bfd_put_8 (abfd, val, ptr)
#define bfd_h_put_signed_8(abfd, val, ptr) \
               bfd_put_8 (abfd, val, ptr)
#define bfd_h_get_8(abfd, ptr) \
               bfd_get_8 (abfd, ptr)
#define bfd_h_get_signed_8(abfd, ptr) \
               bfd_get_signed_8 (abfd, ptr)

#define bfd_h_put_16(abfd, val, ptr) \
                BFD_SEND(abfd, bfd_h_putx16,(val,ptr))
#define bfd_h_put_signed_16 \
                bfd_h_put_16
#define bfd_h_get_16(abfd, ptr) \
                BFD_SEND(abfd, bfd_h_getx16,(ptr))
#define bfd_h_get_signed_16(abfd, ptr) \
                BFD_SEND(abfd, bfd_h_getx_signed_16, (ptr))

#define bfd_h_put_32(abfd, val, ptr) \
                BFD_SEND(abfd, bfd_h_putx32,(val,ptr))
#define bfd_h_put_signed_32 \
                bfd_h_put_32
#define bfd_h_get_32(abfd, ptr) \
                BFD_SEND(abfd, bfd_h_getx32,(ptr))
#define bfd_h_get_signed_32(abfd, ptr) \
                BFD_SEND(abfd, bfd_h_getx_signed_32, (ptr))

#define bfd_h_put_64(abfd, val, ptr) \
                BFD_SEND(abfd, bfd_h_putx64,(val, ptr))
#define bfd_h_put_signed_64 \
                bfd_h_put_64
#define bfd_h_get_64(abfd, ptr) \
                BFD_SEND(abfd, bfd_h_getx64,(ptr))
#define bfd_h_get_signed_64(abfd, ptr) \
                BFD_SEND(abfd, bfd_h_getx_signed_64, (ptr))

bfd_log2

Synopsis

unsigned int bfd_log2(bfd_vma x);

Description
Return the log base 2 of the value supplied, rounded up. E.g., an x of 1025 returns 11.

File caching

The file caching mechanism is embedded within BFD and allows the application to open as many BFDs as it wants without regard to the underlying operating system's file descriptor limit (often as low as 20 open files). The module in cache.c maintains a least recently used list of BFD_CACHE_MAX_OPEN files, and exports the name bfd_cache_lookup, which runs around and makes sure that the required BFD is open. If not, then it chooses a file to close, closes it and opens the one wanted, returning its file handle.

BFD_CACHE_MAX_OPEN macro

Description
The maximum number of files which the cache will keep open at one time.

#define BFD_CACHE_MAX_OPEN 10

bfd_last_cache

Synopsis

extern bfd *bfd_last_cache;

Description
Zero, or a pointer to the topmost BFD on the chain. This is used by the bfd_cache_lookup macro in `libbfd.h' to determine when it can avoid a function call.

bfd_cache_lookup

Description
Check to see if the required BFD is the same as the last one looked up. If so, then it can use the stream in the BFD with impunity, since it can't have changed since the last lookup; otherwise, it has to perform the complicated lookup function.

#define bfd_cache_lookup(x) \
    ((x)==bfd_last_cache? \
      (FILE*)(bfd_last_cache->iostream): \
       bfd_cache_lookup_worker(x))

bfd_cache_init

Synopsis

boolean bfd_cache_init (bfd *abfd);

Description
Add a newly opened BFD to the cache.

bfd_cache_close

Synopsis

boolean bfd_cache_close (bfd *abfd);

Description
Remove the BFD abfd from the cache. If the attached file is open, then close it too.

Returns
false is returned if closing the file fails, true is returned if all is well.

bfd_open_file

Synopsis

FILE* bfd_open_file(bfd *abfd);

Description
Call the OS to open a file for abfd. Return the FILE * (possibly NULL) that results from this operation. Set up the BFD so that future accesses know the file is open. If the FILE * returned is NULL, then it won't have been put in the cache, so it won't have to be removed from it.

bfd_cache_lookup_worker

Synopsis

FILE *bfd_cache_lookup_worker(bfd *abfd);

Description
Called when the macro bfd_cache_lookup fails to find a quick answer. Find a file descriptor for abfd. If necessary, it open it. If there are already more than BFD_CACHE_MAX_OPEN files open, it tries to close one first, to avoid running out of file descriptors.

Linker Functions

The linker uses three special entry points in the BFD target vector. It is not necessary to write special routines for these entry points when creating a new BFD back end, since generic versions are provided. However, writing them can speed up linking and make it use significantly less runtime memory.

The first routine creates a hash table used by the other routines. The second routine adds the symbols from an object file to the hash table. The third routine takes all the object files and links them together to create the output file. These routines are designed so that the linker proper does not need to know anything about the symbols in the object files that it is linking. The linker merely arranges the sections as directed by the linker script and lets BFD handle the details of symbols and relocs.

The second routine and third routines are passed a pointer to a struct bfd_link_info structure (defined in bfdlink.h) which holds information relevant to the link, including the linker hash table (which was created by the first routine) and a set of callback functions to the linker proper.

The generic linker routines are in linker.c, and use the header file genlink.h. As of this writing, the only back ends which have implemented versions of these routines are a.out (in aoutx.h) and ECOFF (in ecoff.c). The a.out routines are used as examples throughout this section.

Creating a linker hash table

The linker routines must create a hash table, which must be derived from struct bfd_link_hash_table described in bfdlink.c. See section Hash Tables for information on how to create a derived hash table. This entry point is called using the target vector of the linker output file.

The _bfd_link_hash_table_create entry point must allocate and initialize an instance of the desired hash table. If the back end does not require any additional information to be stored with the entries in the hash table, the entry point may simply create a struct bfd_link_hash_table. Most likely, however, some additional information will be needed.

For example, with each entry in the hash table the a.out linker keeps the index the symbol has in the final output file (this index number is used so that when doing a relocateable link the symbol index used in the output file can be quickly filled in when copying over a reloc). The a.out linker code defines the required structures and functions for a hash table derived from struct bfd_link_hash_table. The a.out linker hash table is created by the function NAME(aout,link_hash_table_create); it simply allocates space for the hash table, initializes it, and returns a pointer to it.

When writing the linker routines for a new back end, you will generally not know exactly which fields will be required until you have finished. You should simply create a new hash table which defines no additional fields, and then simply add fields as they become necessary.

Adding symbols to the hash table

The linker proper will call the _bfd_link_add_symbols entry point for each object file or archive which is to be linked (typically these are the files named on the command line, but some may also come from the linker script). The entry point is responsible for examining the file. For an object file, BFD must add any relevant symbol information to the hash table. For an archive, BFD must determine which elements of the archive should be used and adding them to the link.

The a.out version of this entry point is NAME(aout,link_add_symbols).

Differing file formats

Normally all the files involved in a link will be of the same format, but it is also possible to link together different format object files, and the back end must support that. The _bfd_link_add_symbols entry point is called via the target vector of the file to be added. This has an important consequence: the function may not assume that the hash table is the type created by the corresponding _bfd_link_hash_table_create vector. All the _bfd_link_add_symbols function can assume about the hash table is that it is derived from struct bfd_link_hash_table.

Sometimes the _bfd_link_add_symbols function must store some information in the hash table entry to be used by the _bfd_final_link function. In such a case the creator field of the hash table must be checked to make sure that the hash table was created by an object file of the same format.

The _bfd_final_link routine must be prepared to handle a hash entry without any extra information added by the _bfd_link_add_symbols function. A hash entry without extra information will also occur when the linker script directs the linker to create a symbol. Note that, regardless of how a hash table entry is added, all the fields will be initialized to some sort of null value by the hash table entry initialization function.

See ecoff_link_add_externals for an example of how to check the creator field before saving information (in this case, the ECOFF external symbol debugging information) in a hash table entry.

Adding symbols from an object file

When the _bfd_link_add_symbols routine is passed an object file, it must add all externally visible symbols in that object file to the hash table. The actual work of adding the symbol to the hash table is normally handled by the function _bfd_generic_link_add_one_symbol. The _bfd_link_add_symbols routine is responsible for reading all the symbols from the object file and passing the correct information to _bfd_generic_link_add_one_symbol.

The _bfd_link_add_symbols routine should not use bfd_canonicalize_symtab to read the symbols. The point of providing this routine is to avoid the overhead of converting the symbols into generic asymbol structures.

_bfd_generic_link_add_one_symbol handles the details of combining common symbols, warning about multiple definitions, and so forth. It takes arguments which describe the symbol to add, notably symbol flags, a section, and an offset. The symbol flags include such things as BSF_WEAK or BSF_INDIRECT. The section is a section in the object file, or something like bfd_und_section_ptr for an undefined symbol or bfd_com_section_ptr for a common symbol.

If the _bfd_final_link routine is also going to need to read the symbol information, the _bfd_link_add_symbols routine should save it somewhere attached to the object file BFD. However, the information should only be saved if the keep_memory field of the info argument is true, so that the -no-keep-memory linker switch is effective.

The a.out function which adds symbols from an object file is aout_link_add_object_symbols, and most of the interesting work is in aout_link_add_symbols. The latter saves pointers to the hash tables entries created by _bfd_generic_link_add_one_symbol indexed by symbol number, so that the _bfd_final_link routine does not have to call the hash table lookup routine to locate the entry.

Adding symbols from an archive

When the _bfd_link_add_symbols routine is passed an archive, it must look through the symbols defined by the archive and decide which elements of the archive should be included in the link. For each such element it must call the add_archive_element linker callback, and it must add the symbols from the object file to the linker hash table.

In most cases the work of looking through the symbols in the archive should be done by the _bfd_generic_link_add_archive_symbols function. This function builds a hash table from the archive symbol table and looks through the list of undefined symbols to see which elements should be included. _bfd_generic_link_add_archive_symbols is passed a function to call to make the final decision about adding an archive element to the link and to do the actual work of adding the symbols to the linker hash table.

The function passed to _bfd_generic_link_add_archive_symbols must read the symbols of the archive element and decide whether the archive element should be included in the link. If the element is to be included, the add_archive_element linker callback routine must be called with the element as an argument, and the elements symbols must be added to the linker hash table just as though the element had itself been passed to the _bfd_link_add_symbols function.

When the a.out _bfd_link_add_symbols function receives an archive, it calls _bfd_generic_link_add_archive_symbols passing aout_link_check_archive_element as the function argument. aout_link_check_archive_element calls aout_link_check_ar_symbols. If the latter decides to add the element (an element is only added if it provides a real, non-common, definition for a previously undefined or common symbol) it calls the add_archive_element callback and then aout_link_check_archive_element calls aout_link_add_symbols to actually add the symbols to the linker hash table.

The ECOFF back end is unusual in that it does not normally call _bfd_generic_link_add_archive_symbols, because ECOFF archives already contain a hash table of symbols. The ECOFF back end searches the archive itself to avoid the overhead of creating a new hash table.

Performing the final link

When all the input files have been processed, the linker calls the _bfd_final_link entry point of the output BFD. This routine is responsible for producing the final output file, which has several aspects. It must relocate the contents of the input sections and copy the data into the output sections. It must build an output symbol table including any local symbols from the input files and the global symbols from the hash table. When producing relocateable output, it must modify the input relocs and write them into the output file. There may also be object format dependent work to be done.

The linker will also call the write_object_contents entry point when the BFD is closed. The two entry points must work together in order to produce the correct output file.

The details of how this works are inevitably dependent upon the specific object file format. The a.out _bfd_final_link routine is NAME(aout,final_link).

Information provided by the linker

Before the linker calls the _bfd_final_link entry point, it sets up some data structures for the function to use.

The input_bfds field of the bfd_link_info structure will point to a list of all the input files included in the link. These files are linked through the link_next field of the bfd structure.

Each section in the output file will have a list of link_order structures attached to the link_order_head field (the link_order structure is defined in bfdlink.h). These structures describe how to create the contents of the output section in terms of the contents of various input sections, fill constants, and, eventually, other types of information. They also describe relocs that must be created by the BFD backend, but do not correspond to any input file; this is used to support -Ur, which builds constructors while generating a relocateable object file.

Relocating the section contents

The _bfd_final_link function should look through the link_order structures attached to each section of the output file. Each link_order structure should either be handled specially, or it should be passed to the function _bfd_default_link_order which will do the right thing (_bfd_default_link_order is defined in linker.c).

For efficiency, a link_order of type bfd_indirect_link_order whose associated section belongs to a BFD of the same format as the output BFD must be handled specially. This type of link_order describes part of an output section in terms of a section belonging to one of the input files. The _bfd_final_link function should read the contents of the section and any associated relocs, apply the relocs to the section contents, and write out the modified section contents. If performing a relocateable link, the relocs themselves must also be modified and written out.

The functions _bfd_relocate_contents and _bfd_final_link_relocate provide some general support for performing the actual relocations, notably overflow checking. Their arguments include information about the symbol the relocation is against and a reloc_howto_type argument which describes the relocation to perform. These functions are defined in reloc.c.

The a.out function which handles reading, relocating, and writing section contents is aout_link_input_section. The actual relocation is done in aout_link_input_section_std and aout_link_input_section_ext.

Writing the symbol table

The _bfd_final_link function must gather all the symbols in the input files and write them out. It must also write out all the symbols in the global hash table. This must be controlled by the strip and discard fields of the bfd_link_info structure.

The local symbols of the input files will not have been entered into the linker hash table. The _bfd_final_link routine must consider each input file and include the symbols in the output file. It may be convenient to do this when looking through the link_order structures, or it may be done by stepping through the input_bfds list.

The _bfd_final_link routine must also traverse the global hash table to gather all the externally visible symbols. It is possible that most of the externally visible symbols may be written out when considering the symbols of each input file, but it is still necessary to traverse the hash table since the linker script may have defined some symbols that are not in any of the input files.

The strip field of the bfd_link_info structure controls which symbols are written out. The possible values are listed in bfdlink.h. If the value is strip_some, then the keep_hash field of the bfd_link_info structure is a hash table of symbols to keep; each symbol should be looked up in this hash table, and only symbols which are present should be included in the output file.

If the strip field of the bfd_link_info structure permits local symbols to be written out, the discard field is used to further controls which local symbols are included in the output file. If the value is discard_l, then all local symbols which begin with a certain prefix are discarded; this is controlled by the bfd_is_local_label_name entry point.

The a.out backend handles symbols by calling aout_link_write_symbols on each input BFD and then traversing the global hash table with the function aout_link_write_other_symbol. It builds a string table while writing out the symbols, which is written to the output file at the end of NAME(aout,final_link).

bfd_link_split_section

Synopsis

boolean bfd_link_split_section(bfd *abfd, asection *sec);

Description
Return nonzero if sec should be split during a reloceatable or final link.

#define bfd_link_split_section(abfd, sec) \
       BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))

Hash Tables

BFD provides a simple set of hash table functions. Routines are provided to initialize a hash table, to free a hash table, to look up a string in a hash table and optionally create an entry for it, and to traverse a hash table. There is currently no routine to delete an string from a hash table.

The basic hash table does not permit any data to be stored with a string. However, a hash table is designed to present a base class from which other types of hash tables may be derived. These derived types may store additional information with the string. Hash tables were implemented in this way, rather than simply providing a data pointer in a hash table entry, because they were designed for use by the linker back ends. The linker may create thousands of hash table entries, and the overhead of allocating private data and storing and following pointers becomes noticeable.

The basic hash table code is in hash.c.

Creating and freeing a hash table

To create a hash table, create an instance of a struct bfd_hash_table (defined in bfd.h) and call bfd_hash_table_init (if you know approximately how many entries you will need, the function bfd_hash_table_init_n, which takes a size argument, may be used). bfd_hash_table_init returns false if some sort of error occurs.

The function bfd_hash_table_init take as an argument a function to use to create new entries. For a basic hash table, use the function bfd_hash_newfunc. See section Deriving a new hash table type for why you would want to use a different value for this argument.

bfd_hash_table_init will create an objalloc which will be used to allocate new entries. You may allocate memory on this objalloc using bfd_hash_allocate.

Use bfd_hash_table_free to free up all the memory that has been allocated for a hash table. This will not free up the struct bfd_hash_table itself, which you must provide.

Looking up or entering a string

The function bfd_hash_lookup is used both to look up a string in the hash table and to create a new entry.

If the create argument is false, bfd_hash_lookup will look up a string. If the string is found, it will returns a pointer to a struct bfd_hash_entry. If the string is not found in the table bfd_hash_lookup will return NULL. You should not modify any of the fields in the returns struct bfd_hash_entry.

If the create argument is true, the string will be entered into the hash table if it is not already there. Either way a pointer to a struct bfd_hash_entry will be returned, either to the existing structure or to a newly created one. In this case, a NULL return means that an error occurred.

If the create argument is true, and a new entry is created, the copy argument is used to decide whether to copy the string onto the hash table objalloc or not. If copy is passed as false, you must be careful not to deallocate or modify the string as long as the hash table exists.

Traversing a hash table

The function bfd_hash_traverse may be used to traverse a hash table, calling a function on each element. The traversal is done in a random order.

bfd_hash_traverse takes as arguments a function and a generic void * pointer. The function is called with a hash table entry (a struct bfd_hash_entry *) and the generic pointer passed to bfd_hash_traverse. The function must return a boolean value, which indicates whether to continue traversing the hash table. If the function returns false, bfd_hash_traverse will stop the traversal and return immediately.

Deriving a new hash table type

Many uses of hash tables want to store additional information which each entry in the hash table. Some also find it convenient to store additional information with the hash table itself. This may be done using a derived hash table.

Since C is not an object oriented language, creating a derived hash table requires sticking together some boilerplate routines with a few differences specific to the type of hash table you want to create.

An example of a derived hash table is the linker hash table. The structures for this are defined in bfdlink.h. The functions are in linker.c.

You may also derive a hash table from an already derived hash table. For example, the a.out linker backend code uses a hash table derived from the linker hash table.

Define the derived structures

You must define a structure for an entry in the hash table, and a structure for the hash table itself.

The first field in the structure for an entry in the hash table must be of the type used for an entry in the hash table you are deriving from. If you are deriving from a basic hash table this is struct bfd_hash_entry, which is defined in bfd.h. The first field in the structure for the hash table itself must be of the type of the hash table you are deriving from itself. If you are deriving from a basic hash table, this is struct bfd_hash_table.

For example, the linker hash table defines struct bfd_link_hash_entry (in bfdlink.h). The first field, root, is of type struct bfd_hash_entry. Similarly, the first field in struct bfd_link_hash_table, table, is of type struct bfd_hash_table.

Write the derived creation routine

You must write a routine which will create and initialize an entry in the hash table. This routine is passed as the function argument to bfd_hash_table_init.

In order to permit other hash tables to be derived from the hash table you are creating, this routine must be written in a standard way.

The first argument to the creation routine is a pointer to a hash table entry. This may be NULL, in which case the routine should allocate the right amount of space. Otherwise the space has already been allocated by a hash table type derived from this one.

After allocating space, the creation routine must call the creation routine of the hash table type it is derived from, passing in a pointer to the space it just allocated. This will initialize any fields used by the base hash table.

Finally the creation routine must initialize any local fields for the new hash table type.

Here is a boilerplate example of a creation routine. function_name is the name of the routine. entry_type is the type of an entry in the hash table you are creating. base_newfunc is the name of the creation routine of the hash table type your hash table is derived from.

struct bfd_hash_entry *
function_name (entry, table, string)
     struct bfd_hash_entry *entry;
     struct bfd_hash_table *table;
     const char *string;
{
  struct entry_type *ret = (entry_type *) entry;

 /* Allocate the structure if it has not already been allocated by a
    derived class.  */
  if (ret == (entry_type *) NULL)
    {
      ret = ((entry_type *)
             bfd_hash_allocate (table, sizeof (entry_type)));
      if (ret == (entry_type *) NULL)
        return NULL;
    }

 /* Call the allocation method of the base class.  */
  ret = ((entry_type *)
        base_newfunc ((struct bfd_hash_entry *) ret, table, string));

 /* Initialize the local fields here.  */

  return (struct bfd_hash_entry *) ret;
}

Description
The creation routine for the linker hash table, which is in linker.c, looks just like this example. function_name is _bfd_link_hash_newfunc. entry_type is struct bfd_link_hash_entry. base_newfunc is bfd_hash_newfunc, the creation routine for a basic hash table.

_bfd_link_hash_newfunc also initializes the local fields in a linker hash table entry: type, written and next.

Write other derived routines

You will want to write other routines for your new hash table, as well.

You will want an initialization routine which calls the initialization routine of the hash table you are deriving from and initializes any other local fields. For the linker hash table, this is _bfd_link_hash_table_init in linker.c.

You will want a lookup routine which calls the lookup routine of the hash table you are deriving from and casts the result. The linker hash table uses bfd_link_hash_lookup in linker.c (this actually takes an additional argument which it uses to decide how to return the looked up value).

You may want a traversal routine. This should just call the traversal routine of the hash table you are deriving from with appropriate casts. The linker hash table uses bfd_link_hash_traverse in linker.c.

These routines may simply be defined as macros. For example, the a.out backend linker hash table, which is derived from the linker hash table, uses macros for the lookup and traversal routines. These are aout_link_hash_lookup and aout_link_hash_traverse in aoutx.h.

BFD back ends

All of BFD lives in one directory.

a.out backends

Description
BFD supports a number of different flavours of a.out format, though the major differences are only the sizes of the structures on disk, and the shape of the relocation information.

The support is split into a basic support file `aoutx.h' and other files which derive functions from the base. One derivation file is `aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions support for sun3, sun4, 386 and 29k a.out files, to create a target jump vector for a specific target.

This information is further split out into more specific files for each machine, including `sunos.c' for sun3 and sun4, `newsos3.c' for the Sony NEWS, and `demo64.c' for a demonstration of a 64 bit a.out format.

The base file `aoutx.h' defines general mechanisms for reading and writing records to and from disk and various other methods which BFD requires. It is included by `aout32.c' and `aout64.c' to form the names aout_32_swap_exec_header_in, aout_64_swap_exec_header_in, etc.

As an example, this is what goes on to make the back end for a sun4, from `aout32.c':

       #define ARCH_SIZE 32
       #include "aoutx.h"

Which exports names:

       ...
       aout_32_canonicalize_reloc
       aout_32_find_nearest_line
       aout_32_get_lineno
       aout_32_get_reloc_upper_bound
       ...

from `sunos.c':

       #define TARGET_NAME "a.out-sunos-big"
       #define VECNAME    sunos_big_vec
       #include "aoutf1.h"

requires all the names from `aout32.c', and produces the jump vector

       sunos_big_vec

The file `host-aout.c' is a special case. It is for a large set of hosts that use "more or less standard" a.out files, and for which cross-debugging is not interesting. It uses the standard 32-bit a.out support routines, but determines the file offsets and addresses of the text, data, and BSS sections, the machine architecture and machine type, and the entry point address, in a host-dependent manner. Once these values have been determined, generic code is used to handle the object file.

When porting it to run on a new system, you must supply:

        HOST_PAGE_SIZE
        HOST_SEGMENT_SIZE
        HOST_MACHINE_ARCH       (optional)
        HOST_MACHINE_MACHINE    (optional)
        HOST_TEXT_START_ADDR
        HOST_STACK_END_ADDR

in the file `../include/sys/h-XXX.h' (for your host). These values, plus the structures and macros defined in `a.out.h' on your host system, will produce a BFD target that will access ordinary a.out files on your host. To configure a new machine to use `host-aout.c', specify:

       TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
       TDEPFILES= host-aout.o trad-core.o

in the `config/XXX.mt' file, and modify `configure.in' to use the `XXX.mt' file (by setting "bfd_target=XXX") when your configuration is selected.

Relocations

Description
The file `aoutx.h' provides for both the standard and extended forms of a.out relocation records.

The standard records contain only an address, a symbol index, and a type field. The extended records (used on 29ks and sparcs) also have a full integer for an addend.

Internal entry points

Description
`aoutx.h' exports several routines for accessing the contents of an a.out file, which are gathered and exported in turn by various format specific files (eg sunos.c).

aout_size_swap_exec_header_in

Synopsis

void aout_size_swap_exec_header_in,
   (bfd *abfd,
    struct external_exec *raw_bytes,
    struct internal_exec *execp);

Description
Swap the information in an executable header raw_bytes taken from a raw byte stream memory image into the internal exec header structure execp.

aout_size_swap_exec_header_out

Synopsis

void aout_size_swap_exec_header_out
   (bfd *abfd,
    struct internal_exec *execp,
    struct external_exec *raw_bytes);

Description
Swap the information in an internal exec header structure execp into the buffer raw_bytes ready for writing to disk.

aout_size_some_aout_object_p

Synopsis

const bfd_target *aout_size_some_aout_object_p
   (bfd *abfd,
    const bfd_target *(*callback_to_real_object_p)());

Description
Some a.out variant thinks that the file open in abfd checking is an a.out file. Do some more checking, and set up for access if it really is. Call back to the calling environment's "finish up" function just before returning, to handle any last-minute setup.

aout_size_mkobject

Synopsis

boolean aout_size_mkobject, (bfd *abfd);

Description
Initialize BFD abfd for use with a.out files.

aout_size_machine_type

Synopsis

enum machine_type  aout_size_machine_type
   (enum bfd_architecture arch,
    unsigned long machine));

Description
Keep track of machine architecture and machine type for a.out's. Return the machine_type for a particular architecture and machine, or M_UNKNOWN if that exact architecture and machine can't be represented in a.out format.

If the architecture is understood, machine type 0 (default) is always understood.

aout_size_set_arch_mach

Synopsis

boolean aout_size_set_arch_mach,
   (bfd *,
    enum bfd_architecture arch,
    unsigned long machine));

Description
Set the architecture and the machine of the BFD abfd to the values arch and machine. Verify that abfd's format can support the architecture required.

aout_size_new_section_hook

Synopsis

boolean aout_size_new_section_hook,
   (bfd *abfd,
    asection *newsect));

Description
Called by the BFD in response to a bfd_make_section request.

coff backends

BFD supports a number of different flavours of coff format. The major differences between formats are the sizes and alignments of fields in structures on disk, and the occasional extra field.

Coff in all its varieties is implemented with a few common files and a number of implementation specific files. For example, The 88k bcs coff format is implemented in the file `coff-m88k.c'. This file #includes `coff/m88k.h' which defines the external structure of the coff format for the 88k, and `coff/internal.h' which defines the internal structure. `coff-m88k.c' also defines the relocations used by the 88k format See section Relocations.

The Intel i960 processor version of coff is implemented in `coff-i960.c'. This file has the same structure as `coff-m88k.c', except that it includes `coff/i960.h' rather than `coff-m88k.h'.

Porting to a new version of coff

The recommended method is to select from the existing implementations the version of coff which is most like the one you want to use. For example, we'll say that i386 coff is the one you select, and that your coff flavour is called foo. Copy `i386coff.c' to `foocoff.c', copy `../include/coff/i386.h' to `../include/coff/foo.h', and add the lines to `targets.c' and `Makefile.in' so that your new back end is used. Alter the shapes of the structures in `../include/coff/foo.h' so that they match what you need. You will probably also have to add #ifdefs to the code in `coff/internal.h' and `coffcode.h' if your version of coff is too wild.

You can verify that your new BFD backend works quite simply by building `objdump' from the `binutils' directory, and making sure that its version of what's going on and your host system's idea (assuming it has the pretty standard coff dump utility, usually called att-dump or just dump) are the same. Then clean up your code, and send what you've done to Cygnus. Then your stuff will be in the next release, and you won't have to keep integrating it.

How the coff backend works

File layout

The Coff backend is split into generic routines that are applicable to any Coff target and routines that are specific to a particular target. The target-specific routines are further split into ones which are basically the same for all Coff targets except that they use the external symbol format or use different values for certain constants.

The generic routines are in `coffgen.c'. These routines work for any Coff target. They use some hooks into the target specific code; the hooks are in a bfd_coff_backend_data structure, one of which exists for each target.

The essentially similar target-specific routines are in `coffcode.h'. This header file includes executable C code. The various Coff targets first include the appropriate Coff header file, make any special defines that are needed, and then include `coffcode.h'.

Some of the Coff targets then also have additional routines in the target source file itself.

For example, `coff-i960.c' includes `coff/internal.h' and `coff/i960.h'. It then defines a few constants, such as I960, and includes `coffcode.h'. Since the i960 has complex relocation types, `coff-i960.c' also includes some code to manipulate the i960 relocs. This code is not in `coffcode.h' because it would not be used by any other target.

Bit twiddling

Each flavour of coff supported in BFD has its own header file describing the external layout of the structures. There is also an internal description of the coff layout, in `coff/internal.h'. A major function of the coff backend is swapping the bytes and twiddling the bits to translate the external form of the structures into the normal internal form. This is all performed in the bfd_swap_thing_direction routines. Some elements are different sizes between different versions of coff; it is the duty of the coff version specific include file to override the definitions of various packing routines in `coffcode.h'. E.g., the size of line number entry in coff is sometimes 16 bits, and sometimes 32 bits. #defineing PUT_LNSZ_LNNO and GET_LNSZ_LNNO will select the correct one. No doubt, some day someone will find a version of coff which has a varying field size not catered to at the moment. To port BFD, that person will have to add more #defines. Three of the bit twiddling routines are exported to gdb; coff_swap_aux_in, coff_swap_sym_in and coff_swap_linno_in. GDB reads the symbol table on its own, but uses BFD to fix things up. More of the bit twiddlers are exported for gas; coff_swap_aux_out, coff_swap_sym_out, coff_swap_lineno_out, coff_swap_reloc_out, coff_swap_filehdr_out, coff_swap_aouthdr_out, coff_swap_scnhdr_out. Gas currently keeps track of all the symbol table and reloc drudgery itself, thereby saving the internal BFD overhead, but uses BFD to swap things on the way out, making cross ports much safer. Doing so also allows BFD (and thus the linker) to use the same header files as gas, which makes one avenue to disaster disappear.

Symbol reading

The simple canonical form for symbols used by BFD is not rich enough to keep all the information available in a coff symbol table. The back end gets around this problem by keeping the original symbol table around, "behind the scenes".

When a symbol table is requested (through a call to bfd_canonicalize_symtab), a request gets through to coff_get_normalized_symtab. This reads the symbol table from the coff file and swaps all the structures inside into the internal form. It also fixes up all the pointers in the table (represented in the file by offsets from the first symbol in the table) into physical pointers to elements in the new internal table. This involves some work since the meanings of fields change depending upon context: a field that is a pointer to another structure in the symbol table at one moment may be the size in bytes of a structure at the next. Another pass is made over the table. All symbols which mark file names (C_FILE symbols) are modified so that the internal string points to the value in the auxent (the real filename) rather than the normal text associated with the symbol (".file").

At this time the symbol names are moved around. Coff stores all symbols less than nine characters long physically within the symbol table; longer strings are kept at the end of the file in the string table. This pass moves all strings into memory and replaces them with pointers to the strings.

The symbol table is massaged once again, this time to create the canonical table used by the BFD application. Each symbol is inspected in turn, and a decision made (using the sclass field) about the various flags to set in the asymbol. See section Symbols. The generated canonical table shares strings with the hidden internal symbol table.

Any linenumbers are read from the coff file too, and attached to the symbols which own the functions the linenumbers belong to.

Symbol writing

Writing a symbol to a coff file which didn't come from a coff file will lose any debugging information. The asymbol structure remembers the BFD from which the symbol was taken, and on output the back end makes sure that the same destination target as source target is present.

When the symbols have come from a coff file then all the debugging information is preserved.

Symbol tables are provided for writing to the back end in a vector of pointers to pointers. This allows applications like the linker to accumulate and output large symbol tables without having to do too much byte copying.

This function runs through the provided symbol table and patches each symbol marked as a file place holder (C_FILE) to point to the next file place holder in the list. It also marks each offset field in the list with the offset from the first symbol of the current symbol.

Another function of this procedure is to turn the canonical value form of BFD into the form used by coff. Internally, BFD expects symbol values to be offsets from a section base; so a symbol physically at 0x120, but in a section starting at 0x100, would have the value 0x20. Coff expects symbols to contain their final value, so symbols have their values changed at this point to reflect their sum with their owning section. This transformation uses the output_section field of the asymbol's asection See section Sections.

  • coff_mangle_symbols

This routine runs though the provided symbol table and uses the offsets generated by the previous pass and the pointers generated when the symbol table was read in to create the structured hierachy required by coff. It changes each pointer to a symbol into the index into the symbol table of the asymbol.

  • coff_write_symbols

This routine runs through the symbol table and patches up the symbols from their internal form into the coff way, calls the bit twiddlers, and writes out the table to the file.

coff_symbol_type

Description
The hidden information for an asymbol is described in a combined_entry_type:

typedef struct coff_ptr_struct
{

       /* Remembers the offset from the first symbol in the file for
          this symbol. Generated by coff_renumber_symbols. */
unsigned int offset;

       /* Should the value of this symbol be renumbered.  Used for
          XCOFF C_BSTAT symbols.  Set by coff_slurp_symbol_table.  */
unsigned int fix_value : 1;

       /* Should the tag field of this symbol be renumbered.
          Created by coff_pointerize_aux. */
unsigned int fix_tag : 1;

       /* Should the endidx field of this symbol be renumbered.
          Created by coff_pointerize_aux. */
unsigned int fix_end : 1;

       /* Should the x_csect.x_scnlen field be renumbered.
          Created by coff_pointerize_aux. */
unsigned int fix_scnlen : 1;

       /* Fix up an XCOFF C_BINCL/C_EINCL symbol.  The value is the
          index into the line number entries.  Set by
          coff_slurp_symbol_table.  */
unsigned int fix_line : 1;

       /* The container for the symbol structure as read and translated
           from the file. */

union {
   union internal_auxent auxent;
   struct internal_syment syment;
 } u;
} combined_entry_type;

/* Each canonical asymbol really looks like this: */

typedef struct coff_symbol_struct
{
   /* The actual symbol which the rest of BFD works with */
asymbol symbol;

   /* A pointer to the hidden information for this symbol */
combined_entry_type *native;

   /* A pointer to the linenumber information for this symbol */
struct lineno_cache_entry *lineno;

   /* Have the line numbers been relocated yet ? */
boolean done_lineno;
} coff_symbol_type;

bfd_coff_backend_data

Special entry points for gdb to swap in coff symbol table parts:

typedef struct
{
  void (*_bfd_coff_swap_aux_in) PARAMS ((
       bfd            *abfd,
       PTR             ext,
       int             type,
       int             class,
       int             indaux,
       int             numaux,
       PTR             in));

  void (*_bfd_coff_swap_sym_in) PARAMS ((
       bfd            *abfd ,
       PTR             ext,
       PTR             in));

  void (*_bfd_coff_swap_lineno_in) PARAMS ((
       bfd            *abfd,
       PTR            ext,
       PTR             in));

Special entry points for gas to swap out coff parts:

 unsigned int (*_bfd_coff_swap_aux_out) PARAMS ((
       bfd     *abfd,
       PTR     in,
       int     type,
       int     class,
       int     indaux,
       int     numaux,
       PTR     ext));

 unsigned int (*_bfd_coff_swap_sym_out) PARAMS ((
      bfd      *abfd,
      PTR      in,
      PTR      ext));

 unsigned int (*_bfd_coff_swap_lineno_out) PARAMS ((
       bfd     *abfd,
       PTR     in,
       PTR     ext));

 unsigned int (*_bfd_coff_swap_reloc_out) PARAMS ((
       bfd     *abfd,
       PTR     src,
       PTR     dst));

 unsigned int (*_bfd_coff_swap_filehdr_out) PARAMS ((
       bfd     *abfd,
       PTR     in,
       PTR     out));

 unsigned int (*_bfd_coff_swap_aouthdr_out) PARAMS ((
       bfd     *abfd,
       PTR     in,
       PTR     out));

 unsigned int (*_bfd_coff_swap_scnhdr_out) PARAMS ((
       bfd     *abfd,
       PTR     in,
       PTR     out));

Special entry points for generic COFF routines to call target dependent COFF routines:

 unsigned int _bfd_filhsz;
 unsigned int _bfd_aoutsz;
 unsigned int _bfd_scnhsz;
 unsigned int _bfd_symesz;
 unsigned int _bfd_auxesz;
 unsigned int _bfd_relsz;
 unsigned int _bfd_linesz;
 boolean _bfd_coff_long_filenames;
 boolean _bfd_coff_long_section_names;
 unsigned int _bfd_coff_default_section_alignment_power;
 void (*_bfd_coff_swap_filehdr_in) PARAMS ((
       bfd     *abfd,
       PTR     ext,
       PTR     in));
 void (*_bfd_coff_swap_aouthdr_in) PARAMS ((
       bfd     *abfd,
       PTR     ext,
       PTR     in));
 void (*_bfd_coff_swap_scnhdr_in) PARAMS ((
       bfd     *abfd,
       PTR     ext,
       PTR     in));
 void (*_bfd_coff_swap_reloc_in) PARAMS ((
       bfd     *abfd,
       PTR     ext,
       PTR     in));
 boolean (*_bfd_coff_bad_format_hook) PARAMS ((
       bfd     *abfd,
       PTR     internal_filehdr));
 boolean (*_bfd_coff_set_arch_mach_hook) PARAMS ((
       bfd     *abfd,
       PTR     internal_filehdr));
 PTR (*_bfd_coff_mkobject_hook) PARAMS ((
       bfd     *abfd,
       PTR     internal_filehdr,
       PTR     internal_aouthdr));
 flagword (*_bfd_styp_to_sec_flags_hook) PARAMS ((
       bfd     *abfd,
       PTR     internal_scnhdr,
       const char *name));
 void (*_bfd_set_alignment_hook) PARAMS ((
       bfd     *abfd,
       asection *sec,
       PTR     internal_scnhdr));
 boolean (*_bfd_coff_slurp_symbol_table) PARAMS ((
       bfd     *abfd));
 boolean (*_bfd_coff_symname_in_debug) PARAMS ((
       bfd     *abfd,
       struct internal_syment *sym));
 boolean (*_bfd_coff_pointerize_aux_hook) PARAMS ((
       bfd *abfd,
       combined_entry_type *table_base,
       combined_entry_type *symbol,
       unsigned int indaux,
       combined_entry_type *aux));
 boolean (*_bfd_coff_print_aux) PARAMS ((
       bfd *abfd,
       FILE *file,
       combined_entry_type *table_base,
       combined_entry_type *symbol,
       combined_entry_type *aux,
       unsigned int indaux));
 void (*_bfd_coff_reloc16_extra_cases) PARAMS ((
       bfd     *abfd,
       struct bfd_link_info *link_info,
       struct bfd_link_order *link_order,
       arelent *reloc,
       bfd_byte *data,
       unsigned int *src_ptr,
       unsigned int *dst_ptr));
 int (*_bfd_coff_reloc16_estimate) PARAMS ((
       bfd *abfd,
       asection *input_section,
       arelent *r,
       unsigned int shrink,
       struct bfd_link_info *link_info));
 boolean (*_bfd_coff_sym_is_global) PARAMS ((
       bfd *abfd,
       struct internal_syment *));
 boolean (*_bfd_coff_compute_section_file_positions) PARAMS ((
       bfd *abfd));
 boolean (*_bfd_coff_start_final_link) PARAMS ((
       bfd *output_bfd,
       struct bfd_link_info *info));
 boolean (*_bfd_coff_relocate_section) PARAMS ((
       bfd *output_bfd,
       struct bfd_link_info *info,
       bfd *input_bfd,
       asection *input_section,
       bfd_byte *contents,
       struct internal_reloc *relocs,
       struct internal_syment *syms,
       asection **sections));
 reloc_howto_type *(*_bfd_coff_rtype_to_howto) PARAMS ((
       bfd *abfd,
       asection *sec,
       struct internal_reloc *rel,
       struct coff_link_hash_entry *h,
       struct internal_syment *sym,
       bfd_vma *addendp));
 boolean (*_bfd_coff_adjust_symndx) PARAMS ((
       bfd *obfd,
       struct bfd_link_info *info,
       bfd *ibfd,
       asection *sec,
       struct internal_reloc *reloc,
       boolean *adjustedp));
 boolean (*_bfd_coff_link_add_one_symbol) PARAMS ((
       struct bfd_link_info *info,
       bfd *abfd,
       const char *name,
       flagword flags,
       asection *section,
       bfd_vma value,
       const char *string,
       boolean copy,
       boolean collect,
       struct bfd_link_hash_entry **hashp));

 boolean (*_bfd_coff_link_output_has_begun) PARAMS ((
       bfd * abfd ));
 boolean (*_bfd_coff_final_link_postscript) PARAMS ((
       bfd * abfd,
       struct coff_final_link_info * pfinfo));

} bfd_coff_backend_data;

#define coff_backend_info(abfd) ((bfd_coff_backend_data *) (abfd)->xvec->backend_data)

#define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \
        ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i))

#define bfd_coff_swap_sym_in(a,e,i) \
        ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i))

#define bfd_coff_swap_lineno_in(a,e,i) \
        ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i))

#define bfd_coff_swap_reloc_out(abfd, i, o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o))

#define bfd_coff_swap_lineno_out(abfd, i, o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o))

#define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \
        ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o))

#define bfd_coff_swap_sym_out(abfd, i,o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o))

#define bfd_coff_swap_scnhdr_out(abfd, i,o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o))

#define bfd_coff_swap_filehdr_out(abfd, i,o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o))

#define bfd_coff_swap_aouthdr_out(abfd, i,o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o))

#define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz)
#define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz)
#define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz)
#define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz)
#define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz)
#define bfd_coff_relsz(abfd)  (coff_backend_info (abfd)->_bfd_relsz)
#define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz)
#define bfd_coff_long_filenames(abfd) (coff_backend_info (abfd)->_bfd_coff_long_filenames)
#define bfd_coff_long_section_names(abfd) \
        (coff_backend_info (abfd)->_bfd_coff_long_section_names)
#define bfd_coff_default_section_alignment_power(abfd) \
        (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power)
#define bfd_coff_swap_filehdr_in(abfd, i,o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o))

#define bfd_coff_swap_aouthdr_in(abfd, i,o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o))

#define bfd_coff_swap_scnhdr_in(abfd, i,o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o))

#define bfd_coff_swap_reloc_in(abfd, i, o) \
        ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o))

#define bfd_coff_bad_format_hook(abfd, filehdr) \
        ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr))

#define bfd_coff_set_arch_mach_hook(abfd, filehdr)\
        ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr))
#define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\
        ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook) (abfd, filehdr, aouthdr))

#define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name)\
        ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook) (abfd, scnhdr, name))

#define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\
        ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr))

#define bfd_coff_slurp_symbol_table(abfd)\
        ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd))

#define bfd_coff_symname_in_debug(abfd, sym)\
        ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym))

#define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\
        ((coff_backend_info (abfd)->_bfd_coff_print_aux)\
         (abfd, file, base, symbol, aux, indaux))

#define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr)\
        ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\
         (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr))

#define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\
        ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\
         (abfd, section, reloc, shrink, link_info))

#define bfd_coff_sym_is_global(abfd, sym)\
        ((coff_backend_info (abfd)->_bfd_coff_sym_is_global)\
         (abfd, sym))

#define bfd_coff_compute_section_file_positions(abfd)\
        ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\
         (abfd))

#define bfd_coff_start_final_link(obfd, info)\
        ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\
         (obfd, info))
#define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\
        ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\
         (obfd, info, ibfd, o, con, rel, isyms, secs))
#define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\
        ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\
         (abfd, sec, rel, h, sym, addendp))
#define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\
        ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\
         (obfd, info, ibfd, sec, rel, adjustedp))
#define bfd_coff_link_add_one_symbol(info,abfd,name,flags,section,value,string,cp,coll,hashp)\
        ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\
         (info, abfd, name, flags, section, value, string, cp, coll, hashp))

#define bfd_coff_link_output_has_begun(a) \
        ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a))
#define bfd_coff_final_link_postscript(a,p) \
        ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a,p))

Writing relocations

To write relocations, the back end steps though the canonical relocation table and create an internal_reloc. The symbol index to use is removed from the offset field in the symbol table supplied. The address comes directly from the sum of the section base address and the relocation offset; the type is dug directly from the howto field. Then the internal_reloc is swapped into the shape of an external_reloc and written out to disk.

Reading linenumbers

Creating the linenumber table is done by reading in the entire coff linenumber table, and creating another table for internal use.

A coff linenumber table is structured so that each function is marked as having a line number of 0. Each line within the function is an offset from the first line in the function. The base of the line number information for the table is stored in the symbol associated with the function.

The information is copied from the external to the internal table, and each symbol which marks a function is marked by pointing its...

How does this work ?

Reading relocations

Coff relocations are easily transformed into the internal BFD form (arelent).

Reading a coff relocation table is done in the following stages:

  • Read the entire coff relocation table into memory.
  • Process each relocation in turn; first swap it from the external to the internal form.
  • Turn the symbol referenced in the relocation's symbol index into a pointer into the canonical symbol table. This table is the same as the one returned by a call to bfd_canonicalize_symtab. The back end will call that routine and save the result if a canonicalization hasn't been done.
  • The reloc index is turned into a pointer to a howto structure, in a back end specific way. For instance, the 386 and 960 use the r_type to directly produce an index into a howto table vector; the 88k subtracts a number from the r_type field and creates an addend field.

ELF backends

BFD support for ELF formats is being worked on. Currently, the best supported back ends are for sparc and i386 (running svr4 or Solaris 2).

Documentation of the internals of the support code still needs to be written. The code is changing quickly enough that we haven't bothered yet.

bfd_elf_find_section

Synopsis

struct elf_internal_shdr *bfd_elf_find_section (bfd *abfd, char *name);

Description
Helper functions for GDB to locate the string tables. Since BFD hides string tables from callers, GDB needs to use an internal hook to find them. Sun's .stabstr, in particular, isn't even pointed to by the .stab section, so ordinary mechanisms wouldn't work to find it, even if we had some.

Index

Jump to: _ - a - b - c - h - i - l - s - t - w

_

  • _bfd_final_link_relocate
  • _bfd_generic_link_add_archive_symbols
  • _bfd_generic_link_add_one_symbol
  • _bfd_link_add_symbols in target vector
  • _bfd_link_final_link in target vector
  • _bfd_link_hash_table_create in target vector
  • _bfd_relocate_contents

    • a

  • aout_size_machine_type
  • aout_size_mkobject
  • aout_size_new_section_hook
  • aout_size_set_arch_mach
  • aout_size_some_aout_object_p
  • aout_size_swap_exec_header_in
  • aout_size_swap_exec_header_out
  • arelent_chain

    • b

  • BFD
  • BFD canonical format
  • bfd_alloc
  • bfd_arch_bits_per_address
  • bfd_arch_bits_per_byte
  • bfd_arch_get_compatible
  • bfd_arch_list
  • bfd_cache_close
  • bfd_cache_init
  • bfd_cache_lookup
  • bfd_cache_lookup_worker
  • BFD_CACHE_MAX_OPEN macro
  • bfd_canonicalize_reloc
  • bfd_canonicalize_symtab
  • bfd_check_format
  • bfd_check_format_matches
  • bfd_check_overflow
  • bfd_close
  • bfd_close_all_done
  • bfd_coff_backend_data
  • bfd_copy_private_bfd_data
  • bfd_copy_private_section_data
  • bfd_copy_private_symbol_data
  • bfd_core_file_failing_command
  • bfd_core_file_failing_signal
  • bfd_create
  • bfd_decode_symclass
  • bfd_default_arch_struct
  • bfd_default_compatible
  • bfd_default_reloc_type_lookup
  • bfd_default_scan
  • bfd_default_set_arch_mach
  • bfd_elf_find_section
  • bfd_errmsg
  • bfd_fdopenr
  • bfd_find_target
  • bfd_format_string
  • bfd_generic_get_relocated_section_contents
  • bfd_generic_relax_section
  • bfd_get_arch
  • bfd_get_arch_info
  • bfd_get_error
  • bfd_get_error_handler
  • bfd_get_gp_size
  • bfd_get_mach
  • bfd_get_mtime
  • bfd_get_next_mapent
  • bfd_get_reloc_code_name
  • bfd_get_reloc_size
  • bfd_get_reloc_upper_bound
  • bfd_get_section_by_name
  • bfd_get_section_contents
  • bfd_get_size, bfd_get_size
  • bfd_get_symtab_upper_bound
  • bfd_h_put_size
  • bfd_hash_allocate
  • bfd_hash_lookup
  • bfd_hash_newfunc
  • bfd_hash_table_free
  • bfd_hash_table_init
  • bfd_hash_table_init_n
  • bfd_hash_traverse
  • bfd_init
  • bfd_install_relocation
  • bfd_is_local_label
  • bfd_is_local_label_name
  • bfd_last_cache
  • bfd_link_split_section
  • bfd_log2
  • bfd_lookup_arch
  • bfd_make_debug_symbol
  • bfd_make_empty_symbol
  • bfd_make_section
  • bfd_make_section_anyway
  • bfd_make_section_old_way
  • bfd_map_over_sections
  • bfd_merge_private_bfd_data
  • bfd_open_file
  • bfd_openr
  • bfd_openr_next_archived_file
  • bfd_openstreamr
  • bfd_openw
  • bfd_perform_relocation
  • bfd_perror
  • bfd_print_symbol_vandf
  • bfd_printable_arch_mach
  • bfd_printable_name
  • bfd_put_size
  • BFD_RELOC_12_PCREL
  • BFD_RELOC_14
  • BFD_RELOC_16
  • BFD_RELOC_16_BASEREL
  • BFD_RELOC_16_GOT_PCREL
  • BFD_RELOC_16_GOTOFF
  • BFD_RELOC_16_PCREL
  • BFD_RELOC_16_PCREL_S2
  • BFD_RELOC_16_PLT_PCREL
  • BFD_RELOC_16_PLTOFF
  • BFD_RELOC_23_PCREL_S2
  • BFD_RELOC_24
  • BFD_RELOC_24_PCREL
  • BFD_RELOC_24_PLT_PCREL
  • BFD_RELOC_26
  • BFD_RELOC_32
  • BFD_RELOC_32_BASEREL
  • BFD_RELOC_32_GOT_PCREL
  • BFD_RELOC_32_GOTOFF
  • BFD_RELOC_32_PCREL
  • BFD_RELOC_32_PCREL_S2
  • BFD_RELOC_32_PLT_PCREL
  • BFD_RELOC_32_PLTOFF
  • BFD_RELOC_386_COPY
  • BFD_RELOC_386_GLOB_DAT
  • BFD_RELOC_386_GOT32
  • BFD_RELOC_386_GOTOFF
  • BFD_RELOC_386_GOTPC
  • BFD_RELOC_386_JUMP_SLOT
  • BFD_RELOC_386_PLT32
  • BFD_RELOC_386_RELATIVE
  • BFD_RELOC_64
  • BFD_RELOC_64_PCREL
  • BFD_RELOC_68K_GLOB_DAT
  • BFD_RELOC_68K_JMP_SLOT
  • BFD_RELOC_68K_RELATIVE
  • BFD_RELOC_8
  • BFD_RELOC_8_BASEREL
  • BFD_RELOC_8_FFnn
  • BFD_RELOC_8_GOT_PCREL
  • BFD_RELOC_8_GOTOFF
  • BFD_RELOC_8_PCREL
  • BFD_RELOC_8_PLT_PCREL
  • BFD_RELOC_8_PLTOFF
  • BFD_RELOC_ALPHA_CODEADDR
  • BFD_RELOC_ALPHA_ELF_LITERAL
  • BFD_RELOC_ALPHA_GPDISP
  • BFD_RELOC_ALPHA_GPDISP_HI16
  • BFD_RELOC_ALPHA_GPDISP_LO16
  • BFD_RELOC_ALPHA_HINT
  • BFD_RELOC_ALPHA_LINKAGE
  • BFD_RELOC_ALPHA_LITERAL
  • BFD_RELOC_ALPHA_LITUSE
  • BFD_RELOC_ARC_B22_PCREL
  • BFD_RELOC_ARC_B26
  • BFD_RELOC_ARM_ADR_IMM
  • BFD_RELOC_ARM_CP_OFF_IMM
  • BFD_RELOC_ARM_HWLITERAL
  • BFD_RELOC_ARM_IMMEDIATE
  • BFD_RELOC_ARM_IN_POOL
  • BFD_RELOC_ARM_LDR_IMM
  • BFD_RELOC_ARM_LITERAL
  • BFD_RELOC_ARM_MULTI
  • BFD_RELOC_ARM_OFFSET_IMM
  • BFD_RELOC_ARM_OFFSET_IMM8
  • BFD_RELOC_ARM_PCREL_BRANCH
  • BFD_RELOC_ARM_SHIFT_IMM
  • BFD_RELOC_ARM_SWI
  • BFD_RELOC_ARM_THUMB_ADD
  • BFD_RELOC_ARM_THUMB_IMM
  • BFD_RELOC_ARM_THUMB_OFFSET
  • BFD_RELOC_ARM_THUMB_SHIFT
  • bfd_reloc_code_type
  • BFD_RELOC_CTOR
  • BFD_RELOC_D10V_10_PCREL_L
  • BFD_RELOC_D10V_10_PCREL_R
  • BFD_RELOC_D10V_18
  • BFD_RELOC_D10V_18_PCREL
  • BFD_RELOC_GPREL16
  • BFD_RELOC_GPREL32
  • BFD_RELOC_HI16
  • BFD_RELOC_HI16_BASEREL
  • BFD_RELOC_HI16_GOTOFF
  • BFD_RELOC_HI16_PLTOFF
  • BFD_RELOC_HI16_S
  • BFD_RELOC_HI16_S_BASEREL
  • BFD_RELOC_HI16_S_GOTOFF
  • BFD_RELOC_HI16_S_PLTOFF
  • BFD_RELOC_HI22
  • BFD_RELOC_I960_CALLJ
  • BFD_RELOC_LO10
  • BFD_RELOC_LO16
  • BFD_RELOC_LO16_BASEREL
  • BFD_RELOC_LO16_GOTOFF
  • BFD_RELOC_LO16_PLTOFF
  • BFD_RELOC_M32R_10_PCREL
  • BFD_RELOC_M32R_18_PCREL
  • BFD_RELOC_M32R_24
  • BFD_RELOC_M32R_26_PCREL
  • BFD_RELOC_M32R_HI16_SLO
  • BFD_RELOC_M32R_HI16_ULO
  • BFD_RELOC_M32R_LO16
  • BFD_RELOC_M32R_SDA16
  • BFD_RELOC_MIPS16_GPREL
  • BFD_RELOC_MIPS16_JMP
  • BFD_RELOC_MIPS_CALL16
  • BFD_RELOC_MIPS_CALL_HI16
  • BFD_RELOC_MIPS_CALL_LO16
  • BFD_RELOC_MIPS_GOT16
  • BFD_RELOC_MIPS_GOT_HI16
  • BFD_RELOC_MIPS_GOT_LO16
  • BFD_RELOC_MIPS_GPREL
  • BFD_RELOC_MIPS_GPREL32
  • BFD_RELOC_MIPS_JMP
  • BFD_RELOC_MIPS_LITERAL
  • BFD_RELOC_MN10300_16_PCREL
  • BFD_RELOC_MN10300_32_PCREL
  • BFD_RELOC_NONE
  • BFD_RELOC_NS32K_DISP_16
  • BFD_RELOC_NS32K_DISP_16_PCREL
  • BFD_RELOC_NS32K_DISP_32
  • BFD_RELOC_NS32K_DISP_32_PCREL
  • BFD_RELOC_NS32K_DISP_8
  • BFD_RELOC_NS32K_DISP_8_PCREL
  • BFD_RELOC_NS32K_IMM_16
  • BFD_RELOC_NS32K_IMM_16_PCREL
  • BFD_RELOC_NS32K_IMM_32
  • BFD_RELOC_NS32K_IMM_32_PCREL
  • BFD_RELOC_NS32K_IMM_8
  • BFD_RELOC_NS32K_IMM_8_PCREL
  • BFD_RELOC_PCREL_HI16_S
  • BFD_RELOC_PCREL_LO16
  • BFD_RELOC_PPC_B16
  • BFD_RELOC_PPC_B16_BRNTAKEN
  • BFD_RELOC_PPC_B16_BRTAKEN
  • BFD_RELOC_PPC_B26
  • BFD_RELOC_PPC_BA16
  • BFD_RELOC_PPC_BA16_BRNTAKEN
  • BFD_RELOC_PPC_BA16_BRTAKEN
  • BFD_RELOC_PPC_BA26
  • BFD_RELOC_PPC_COPY
  • BFD_RELOC_PPC_EMB_BIT_FLD
  • BFD_RELOC_PPC_EMB_MRKREF
  • BFD_RELOC_PPC_EMB_NADDR16
  • BFD_RELOC_PPC_EMB_NADDR16_HA
  • BFD_RELOC_PPC_EMB_NADDR16_HI
  • BFD_RELOC_PPC_EMB_NADDR16_LO
  • BFD_RELOC_PPC_EMB_NADDR32
  • BFD_RELOC_PPC_EMB_RELSDA
  • BFD_RELOC_PPC_EMB_RELSEC16
  • BFD_RELOC_PPC_EMB_RELST_HA
  • BFD_RELOC_PPC_EMB_RELST_HI
  • BFD_RELOC_PPC_EMB_RELST_LO
  • BFD_RELOC_PPC_EMB_SDA21
  • BFD_RELOC_PPC_EMB_SDA2I16
  • BFD_RELOC_PPC_EMB_SDA2REL
  • BFD_RELOC_PPC_EMB_SDAI16
  • BFD_RELOC_PPC_GLOB_DAT
  • BFD_RELOC_PPC_JMP_SLOT
  • BFD_RELOC_PPC_LOCAL24PC
  • BFD_RELOC_PPC_RELATIVE
  • BFD_RELOC_PPC_TOC16
  • BFD_RELOC_RVA
  • BFD_RELOC_SH_ALIGN
  • BFD_RELOC_SH_CODE
  • BFD_RELOC_SH_COUNT
  • BFD_RELOC_SH_DATA
  • BFD_RELOC_SH_IMM4
  • BFD_RELOC_SH_IMM4BY2
  • BFD_RELOC_SH_IMM4BY4
  • BFD_RELOC_SH_IMM8
  • BFD_RELOC_SH_IMM8BY2
  • BFD_RELOC_SH_IMM8BY4
  • BFD_RELOC_SH_LABEL
  • BFD_RELOC_SH_PCDISP12BY2
  • BFD_RELOC_SH_PCDISP8BY2
  • BFD_RELOC_SH_PCRELIMM8BY2
  • BFD_RELOC_SH_PCRELIMM8BY4
  • BFD_RELOC_SH_SWITCH16
  • BFD_RELOC_SH_SWITCH32
  • BFD_RELOC_SH_USES
  • BFD_RELOC_SPARC13
  • BFD_RELOC_SPARC22
  • BFD_RELOC_SPARC_10
  • BFD_RELOC_SPARC_11
  • BFD_RELOC_SPARC_5
  • BFD_RELOC_SPARC_6
  • BFD_RELOC_SPARC_64
  • BFD_RELOC_SPARC_7
  • BFD_RELOC_SPARC_BASE13
  • BFD_RELOC_SPARC_BASE22
  • BFD_RELOC_SPARC_COPY
  • BFD_RELOC_SPARC_DISP64
  • BFD_RELOC_SPARC_GLOB_DAT
  • BFD_RELOC_SPARC_GOT10
  • BFD_RELOC_SPARC_GOT13
  • BFD_RELOC_SPARC_GOT22
  • BFD_RELOC_SPARC_H44
  • BFD_RELOC_SPARC_HH22
  • BFD_RELOC_SPARC_HIX22
  • BFD_RELOC_SPARC_HM10
  • BFD_RELOC_SPARC_JMP_SLOT
  • BFD_RELOC_SPARC_L44
  • BFD_RELOC_SPARC_LM22
  • BFD_RELOC_SPARC_LOX10
  • BFD_RELOC_SPARC_M44
  • BFD_RELOC_SPARC_OLO10
  • BFD_RELOC_SPARC_PC10
  • BFD_RELOC_SPARC_PC22
  • BFD_RELOC_SPARC_PC_HH22
  • BFD_RELOC_SPARC_PC_HM10
  • BFD_RELOC_SPARC_PC_LM22
  • BFD_RELOC_SPARC_PLT64
  • BFD_RELOC_SPARC_REGISTER
  • BFD_RELOC_SPARC_RELATIVE
  • BFD_RELOC_SPARC_UA32
  • BFD_RELOC_SPARC_WDISP16
  • BFD_RELOC_SPARC_WDISP19
  • BFD_RELOC_SPARC_WDISP22
  • BFD_RELOC_SPARC_WPLT30
  • BFD_RELOC_THUMB_PCREL_BRANCH12
  • BFD_RELOC_THUMB_PCREL_BRANCH23
  • BFD_RELOC_THUMB_PCREL_BRANCH9
  • BFD_RELOC_TIC30_LDP
  • bfd_reloc_type_lookup
  • BFD_RELOC_V850_22_PCREL
  • BFD_RELOC_V850_9_PCREL
  • BFD_RELOC_V850_SDA_15_16_OFFSET
  • BFD_RELOC_V850_SDA_16_16_OFFSET
  • BFD_RELOC_V850_TDA_16_16_OFFSET
  • BFD_RELOC_V850_TDA_6_8_OFFSET
  • BFD_RELOC_V850_TDA_7_7_OFFSET
  • BFD_RELOC_V850_TDA_7_8_OFFSET
  • BFD_RELOC_V850_ZDA_15_16_OFFSET
  • BFD_RELOC_V850_ZDA_16_16_OFFSET
  • bfd_scan_arch
  • bfd_scan_vma
  • bfd_set_arch_info
  • bfd_set_archive_head
  • bfd_set_default_target
  • bfd_set_error
  • bfd_set_error_handler
  • bfd_set_error_program_name
  • bfd_set_file_flags
  • bfd_set_format
  • bfd_set_gp_size
  • bfd_set_private_flags
  • bfd_set_reloc
  • bfd_set_section_contents
  • bfd_set_section_flags
  • bfd_set_section_size
  • bfd_set_start_address
  • bfd_set_symtab
  • bfd_symbol_info
  • bfd_target_list
  • bfd_write_bigendian_4byte_int

    • c

  • coff_symbol_type
  • core_file_matches_executable_p

    • h

  • Hash tables

    • i

  • internal object-file format

    • l

  • Linker

    • s

  • stuff

    • t

  • target vector (_bfd_final_link)
  • target vector (_bfd_link_add_symbols)
  • target vector (_bfd_link_hash_table_create)
  • The HOWTO Macro

    • w

  • what is it?

    • This document was generated on 24 April 1999 using the texi2html translator version 1.52.


GNU Binary Utilities

This brief manual contains preliminary documentation for the GNU binary utilities (collectively version 2.12):

This document is distributed under the terms of the GNU Free Documentation License. A copy of the license is included in the section entitled "GNU Free Documentation License".

1. ar | Create, modify, and extract from archives
2. nm | List symbols from object files
3. objcopy | Copy and translate object files
4. objdump | Display information from object files
5. ranlib | Generate index to archive contents
14. readelf | Display the contents of ELF format files.
6. size | List section sizes and total size
7. strings | List printable strings from files
8. strip | Discard symbols
9. c++filt | Filter to demangle encoded C++ symbols
9. c++filt | MS-DOS name for c++filt
10. addr2line | Convert addresses to file and line
11. nlmconv | Converts object code into an NLM
12. windres | Manipulate Windows resources
13. Create files needed to build and use DLLs
15. Selecting the target system | How these utilities determine the target.
16. Reporting Bugs
17. GNU Free Documentation License
Index

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. ar

ar [-]p[mod [relpos] [count]] archive [member...]
ar -M [ <mri-script ]

The GNU ar program creates, modifies, and extracts from archives. An archive is a single file holding a collection of other files in a structure that makes it possible to retrieve the original individual files (called members of the archive).

The original files' contents, mode (permissions), timestamp, owner, and group are preserved in the archive, and can be restored on extraction.

GNU ar can maintain archives whose members have names of any length; however, depending on how ar is configured on your system, a limit on member-name length may be imposed for compatibility with archive formats maintained with other tools. If it exists, the limit is often 15 characters (typical of formats related to a.out) or 16 characters (typical of formats related to coff).

ar is considered a binary utility because archives of this sort are most often used as libraries holding commonly needed subroutines.

ar creates an index to the symbols defined in relocatable object modules in the archive when you specify the modifier `s'. Once created, this index is updated in the archive whenever ar makes a change to its contents (save for the `q' update operation). An archive with such an index speeds up linking to the library, and allows routines in the library to call each other without regard to their placement in the archive.

You may use `nm -s' or `nm --print-armap' to list this index table. If an archive lacks the table, another form of ar called ranlib can be used to add just the table.

GNU ar is designed to be compatible with two different facilities. You can control its activity using command-line options, like the different varieties of ar on Unix systems; or, if you specify the single command-line option `-M', you can control it with a script supplied via standard input, like the MRI "librarian" program.

1.1 Controlling ar on the command line
1.2 Controlling ar with a script

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.1 Controlling ar on the command line

ar [`-X32_64'] [`-']p[mod [relpos] [count]] archive [member...]

When you use ar in the Unix style, ar insists on at least two arguments to execute: one keyletter specifying the operation (optionally accompanied by other keyletters specifying modifiers), and the archive name to act on.

Most operations can also accept further member arguments, specifying particular files to operate on.

GNU ar allows you to mix the operation code p and modifier flags mod in any order, within the first command-line argument.

If you wish, you may begin the first command-line argument with a dash.

The p keyletter specifies what operation to execute; it may be any of the following, but you must specify only one of them:

`d'
Delete modules from the archive. Specify the names of modules to be deleted as member...; the archive is untouched if you specify no files to delete.

If you specify the `v' modifier, ar lists each module as it is deleted.

`m'
Use this operation to move members in an archive.

The ordering of members in an archive can make a difference in how programs are linked using the library, if a symbol is defined in more than one member.

If no modifiers are used with m, any members you name in the member arguments are moved to the end of the archive; you can use the `a', `b', or `i' modifiers to move them to a specified place instead.

`p'
Print the specified members of the archive, to the standard output file. If the `v' modifier is specified, show the member name before copying its contents to standard output.

If you specify no member arguments, all the files in the archive are printed.

`q'
Quick append; Historically, add the files member... to the end of archive, without checking for replacement.

The modifiers `a', `b', and `i' do not affect this operation; new members are always placed at the end of the archive.

The modifier `v' makes ar list each file as it is appended.

Since the point of this operation is speed, the archive's symbol table index is not updated, even if it already existed; you can use `ar s' or ranlib explicitly to update the symbol table index.

However, too many different systems assume quick append rebuilds the index, so GNU ar implements q as a synonym for r.

`r'
Insert the files member... into archive (with replacement). This operation differs from `q' in that any previously existing members are deleted if their names match those being added.

If one of the files named in member... does not exist, ar displays an error message, and leaves undisturbed any existing members of the archive matching that name.

By default, new members are added at the end of the file; but you may use one of the modifiers `a', `b', or `i' to request placement relative to some existing member.

The modifier `v' used with this operation elicits a line of output for each file inserted, along with one of the letters `a' or `r' to indicate whether the file was appended (no old member deleted) or replaced.

`t'
Display a table listing the contents of archive, or those of the files listed in member... that are present in the archive. Normally only the member name is shown; if you also want to see the modes (permissions), timestamp, owner, group, and size, you can request that by also specifying the `v' modifier.

If you do not specify a member, all files in the archive are listed.

If there is more than one file with the same name (say, `fie') in an archive (say `b.a'), `ar t b.a fie' lists only the first instance; to see them all, you must ask for a complete listing--in our example, `ar t b.a'.

`x'
Extract members (named member) from the archive. You can use the `v' modifier with this operation, to request that ar list each name as it extracts it.

If you do not specify a member, all files in the archive are extracted.

A number of modifiers (mod) may immediately follow the p keyletter, to specify variations on an operation's behavior:

`a'
Add new files after an existing member of the archive. If you use the modifier `a', the name of an existing archive member must be present as the relpos argument, before the archive specification.

`b'
Add new files before an existing member of the archive. If you use the modifier `b', the name of an existing archive member must be present as the relpos argument, before the archive specification. (same as `i').

`c'
Create the archive. The specified archive is always created if it did not exist, when you request an update. But a warning is issued unless you specify in advance that you expect to create it, by using this modifier.

`f'
Truncate names in the archive. GNU ar will normally permit file names of any length. This will cause it to create archives which are not compatible with the native ar program on some systems. If this is a concern, the `f' modifier may be used to truncate file names when putting them in the archive.

`i'
Insert new files before an existing member of the archive. If you use the modifier `i', the name of an existing archive member must be present as the relpos argument, before the archive specification. (same as `b').

`l'
This modifier is accepted but not used.

`N'
Uses the count parameter. This is used if there are multiple entries in the archive with the same name. Extract or delete instance count of the given name from the archive.

`o'
Preserve the original dates of members when extracting them. If you do not specify this modifier, files extracted from the archive are stamped with the time of extraction.

`P'
Use the full path name when matching names in the archive. GNU ar can not create an archive with a full path name (such archives are not POSIX complaint), but other archive creators can. This option will cause GNU ar to match file names using a complete path name, which can be convenient when extracting a single file from an archive created by another tool.

`s'
Write an object-file index into the archive, or update an existing one, even if no other change is made to the archive. You may use this modifier flag either with any operation, or alone. Running `ar s' on an archive is equivalent to running `ranlib' on it.

`S'
Do not generate an archive symbol table. This can speed up building a large library in several steps. The resulting archive can not be used with the linker. In order to build a symbol table, you must omit the `S' modifier on the last execution of `ar', or you must run `ranlib' on the archive.

`u'
Normally, `ar r'... inserts all files listed into the archive. If you would like to insert only those of the files you list that are newer than existing members of the same names, use this modifier. The `u' modifier is allowed only for the operation `r' (replace). In particular, the combination `qu' is not allowed, since checking the timestamps would lose any speed advantage from the operation `q'.

`v'
This modifier requests the verbose version of an operation. Many operations display additional information, such as filenames processed, when the modifier `v' is appended.

`V'
This modifier shows the version number of ar.

ar ignores an initial option spelt `-X32_64', for compatibility with AIX. The behaviour produced by this option is the default for GNU ar. ar does not support any of the other `-X' options; in particular, it does not support `-X32' which is the default for AIX ar.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.2 Controlling ar with a script

ar -M [ <script ]

If you use the single command-line option `-M' with ar, you can control its operation with a rudimentary command language. This form of ar operates interactively if standard input is coming directly from a terminal. During interactive use, ar prompts for input (the prompt is `AR >'), and continues executing even after errors. If you redirect standard input to a script file, no prompts are issued, and ar abandons execution (with a nonzero exit code) on any error.

The ar command language is not designed to be equivalent to the command-line options; in fact, it provides somewhat less control over archives. The only purpose of the command language is to ease the transition to GNU ar for developers who already have scripts written for the MRI "librarian" program.

The syntax for the ar command language is straightforward:

  • commands are recognized in upper or lower case; for example, LIST is the same as list. In the following descriptions, commands are shown in upper case for clarity.

  • a single command may appear on each line; it is the first word on the line.

  • empty lines are allowed, and have no effect.

  • comments are allowed; text after either of the characters `*' or `;' is ignored.

  • Whenever you use a list of names as part of the argument to an ar command, you can separate the individual names with either commas or blanks. Commas are shown in the explanations below, for clarity.

  • `+' is used as a line continuation character; if `+' appears at the end of a line, the text on the following line is considered part of the current command.

Here are the commands you can use in ar scripts, or when using ar interactively. Three of them have special significance:

OPEN or CREATE specify a current archive, which is a temporary file required for most of the other commands.

SAVE commits the changes so far specified by the script. Prior to SAVE, commands affect only the temporary copy of the current archive.

ADDLIB archive
ADDLIB archive (module, module, ... module)
Add all the contents of archive (or, if specified, each named module from archive) to the current archive.

Requires prior use of OPEN or CREATE.

ADDMOD member, member, ... member
Add each named member as a module in the current archive.

Requires prior use of OPEN or CREATE.

CLEAR
Discard the contents of the current archive, canceling the effect of any operations since the last SAVE. May be executed (with no effect) even if no current archive is specified.

CREATE archive
Creates an archive, and makes it the current archive (required for many other commands). The new archive is created with a temporary name; it is not actually saved as archive until you use SAVE. You can overwrite existing archives; similarly, the contents of any existing file named archive will not be destroyed until SAVE.

DELETE module, module, ... module
Delete each listed module from the current archive; equivalent to `ar -d archive module ... module'.

Requires prior use of OPEN or CREATE.

DIRECTORY archive (module, ... module)
DIRECTORY archive (module, ... module) outputfile
List each named module present in archive. The separate command VERBOSE specifies the form of the output: when verbose output is off, output is like that of `ar -t archive module...'. When verbose output is on, the listing is like `ar -tv archive module...'.

Output normally goes to the standard output stream; however, if you specify outputfile as a final argument, ar directs the output to that file.

END
Exit from ar, with a 0 exit code to indicate successful completion. This command does not save the output file; if you have changed the current archive since the last SAVE command, those changes are lost.

EXTRACT module, module, ... module
Extract each named module from the current archive, writing them into the current directory as separate files. Equivalent to `ar -x archive module...'.

Requires prior use of OPEN or CREATE.

LIST
Display full contents of the current archive, in "verbose" style regardless of the state of VERBOSE. The effect is like `ar tv archive'. (This single command is a GNU ar enhancement, rather than present for MRI compatibility.)

Requires prior use of OPEN or CREATE.

OPEN archive
Opens an existing archive for use as the current archive (required for many other commands). Any changes as the result of subsequent commands will not actually affect archive until you next use SAVE.

REPLACE module, module, ... module
In the current archive, replace each existing module (named in the REPLACE arguments) from files in the current working directory. To execute this command without errors, both the file, and the module in the current archive, must exist.

Requires prior use of OPEN or CREATE.

VERBOSE
Toggle an internal flag governing the output from DIRECTORY. When the flag is on, DIRECTORY output matches output from `ar -tv '....

SAVE
Commit your changes to the current archive, and actually save it as a file with the name specified in the last CREATE or OPEN command.

Requires prior use of OPEN or CREATE.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. nm

nm [`-a'|`--debug-syms'] [`-g'|`--extern-only']
   [`-B'] [`-C'|`--demangle'[=style]] [`-D'|`--dynamic']
   [`-s'|`--print-armap'] [`-A'|`-o'|`--print-file-name']
   [`-n'|`-v'|`--numeric-sort'] [`-p'|`--no-sort']
   [`-r'|`--reverse-sort'] [`--size-sort'] [`-u'|`--undefined-only']
   [`-t' radix|`--radix='radix] [`-P'|`--portability']
   [`--target='bfdname] [`-f'format|`--format='format]
   [`--defined-only'] [`-l'|`--line-numbers'] [`--no-demangle']
   [`-V'|`--version'] [`-X 32_64'] [`--help']  [objfile...]

GNU nm lists the symbols from object files objfile.... If no object files are listed as arguments, nm assumes the file `a.out'.

For each symbol, nm shows:

  • The symbol value, in the radix selected by options (see below), or hexadecimal by default.

  • The symbol type. At least the following types are used; others are, as well, depending on the object file format. If lowercase, the symbol is local; if uppercase, the symbol is global (external).

    A
    The symbol's value is absolute, and will not be changed by further linking.

    B
    The symbol is in the uninitialized data section (known as BSS).

    C
    The symbol is common. Common symbols are uninitialized data. When linking, multiple common symbols may appear with the same name. If the symbol is defined anywhere, the common symbols are treated as undefined references. For more details on common symbols, see the discussion of --warn-common in section `Linker options' in The GNU linker.

    D
    The symbol is in the initialized data section.

    G
    The symbol is in an initialized data section for small objects. Some object file formats permit more efficient access to small data objects, such as a global int variable as opposed to a large global array.

    I
    The symbol is an indirect reference to another symbol. This is a GNU extension to the a.out object file format which is rarely used.

    N
    The symbol is a debugging symbol.

    R
    The symbol is in a read only data section.

    S
    The symbol is in an uninitialized data section for small objects.

    T
    The symbol is in the text (code) section.

    U
    The symbol is undefined.

    V
    The symbol is a weak object. When a weak defined symbol is linked with a normal defined symbol, the normal defined symbol is used with no error. When a weak undefined symbol is linked and the symbol is not defined, the value of the weak symbol becomes zero with no error.

    W
    The symbol is a weak symbol that has not been specifically tagged as a weak object symbol. When a weak defined symbol is linked with a normal defined symbol, the normal defined symbol is used with no error. When a weak undefined symbol is linked and the symbol is not defined, the value of the weak symbol becomes zero with no error.

    -
    The symbol is a stabs symbol in an a.out object file. In this case, the next values printed are the stabs other field, the stabs desc field, and the stab type. Stabs symbols are used to hold debugging information. For more information, see section `Stabs Overview' in The "stabs" debug format.

    ?
    The symbol type is unknown, or object file format specific.

  • The symbol name.

The long and short forms of options, shown here as alternatives, are equivalent.

-A
-o
--print-file-name
Precede each symbol by the name of the input file (or archive member) in which it was found, rather than identifying the input file once only, before all of its symbols.

-a
--debug-syms
Display all symbols, even debugger-only symbols; normally these are not listed.

-B
The same as `--format=bsd' (for compatibility with the MIPS nm).

-C
--demangle[=style]
Decode (demangle) low-level symbol names into user-level names. Besides removing any initial underscore prepended by the system, this makes C++ function names readable. Different compilers have different mangling styles. The optional demangling style argument can be used to choose an appropriate demangling style for your compiler. See section 9. c++filt, for more information on demangling.

--no-demangle
Do not demangle low-level symbol names. This is the default.

-D
--dynamic
Display the dynamic symbols rather than the normal symbols. This is only meaningful for dynamic objects, such as certain types of shared libraries.

-f format
--format=format
Use the output format format, which can be bsd, sysv, or posix. The default is bsd. Only the first character of format is significant; it can be either upper or lower case.

-g
--extern-only
Display only external symbols.

-l
--line-numbers
For each symbol, use debugging information to try to find a filename and line number. For a defined symbol, look for the line number of the address of the symbol. For an undefined symbol, look for the line number of a relocation entry which refers to the symbol. If line number information can be found, print it after the other symbol information.

-n
-v
--numeric-sort
Sort symbols numerically by their addresses, rather than alphabetically by their names.

-p
--no-sort
Do not bother to sort the symbols in any order; print them in the order encountered.

-P
--portability
Use the POSIX.2 standard output format instead of the default format. Equivalent to `-f posix'.

-s
--print-armap
When listing symbols from archive members, include the index: a mapping (stored in the archive by ar or ranlib) of which modules contain definitions for which names.

-r
--reverse-sort
Reverse the order of the sort (whether numeric or alphabetic); let the last come first.

--size-sort
Sort symbols by size. The size is computed as the difference between the value of the symbol and the value of the symbol with the next higher value. The size of the symbol is printed, rather than the value.

-t radix
--radix=radix
Use radix as the radix for printing the symbol values. It must be `d' for decimal, `o' for octal, or `x' for hexadecimal.

--target=bfdname
Specify an object code format other than your system's default format. See section 15.1 Target Selection, for more information.

-u
--undefined-only
Display only undefined symbols (those external to each object file).

--defined-only
Display only defined symbols for each object file.

-V
--version
Show the version number of nm and exit.

-X
This option is ignored for compatibility with the AIX version of nm. It takes one parameter which must be the string `32_64'. The default mode of AIX nm corresponds to `-X 32', which is not supported by GNU nm.

--help
Show a summary of the options to nm and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. objcopy

objcopy [`-F' bfdname|`--target='bfdname]
        [`-I' bfdname|`--input-target='bfdname]
        [`-O' bfdname|`--output-target='bfdname]
        [`-B' bfdarch|`--binary-architecture='bfdarch]
        [`-S'|`--strip-all'] [`-g'|`--strip-debug']
        [`-K' symbolname|`--keep-symbol='symbolname]
        [`-N' symbolname|`--strip-symbol='symbolname]
        [`-G' symbolname|`--keep-global-symbol='symbolname]
        [`-L' symbolname|`--localize-symbol='symbolname]
        [`-W' symbolname|`--weaken-symbol='symbolname]
        [`-x'|`--discard-all'] [`-X'|`--discard-locals']
        [`-b' byte|`--byte='byte]
        [`-i' interleave|`--interleave='interleave]
        [`-j' sectionname|`--only-section='sectionname]
        [`-R' sectionname|`--remove-section='sectionname]
        [`-p'|`--preserve-dates']
        [`--debugging']
        [`--gap-fill='val] [`--pad-to='address]
        [`--set-start='val] [`--adjust-start='incr]
        [`--change-addresses='incr]
        [`--change-section-address' section{=,+,-}val]
        [`--change-section-lma' section{=,+,-}val]
        [`--change-section-vma' section{=,+,-}val]
        [`--change-warnings'] [`--no-change-warnings']
        [`--set-section-flags' section=flags]
        [`--add-section' sectionname=filename]
        [`--rename-section' oldname=newname[,flags]]
        [`--change-leading-char' ] [`--remove-leading-char']
        [`--srec-len='ival ] [`--srec-forceS3']
        [`--redefine-sym' old=new ]
        [`--weaken']
        [`--keep-symbols='filename]
        [`--strip-symbols='filename]
        [`--keep-global-symbols='filename]
        [`--localize-symbols='filename]
        [`--weaken-symbols='filename]
        [`--alt-machine-code=index']
        [`-v'|`--verbose']
        [`-V'|`--version']
        [`--help']
        infile [outfile]

The GNU objcopy utility copies the contents of an object file to another. objcopy uses the GNU BFD Library to read and write the object files. It can write the destination object file in a format different from that of the source object file. The exact behavior of objcopy is controlled by command-line options. Note that objcopy should be able to copy a fully linked file between any two formats. However, copying a relocatable object file between any two formats may not work as expected.

objcopy creates temporary files to do its translations and deletes them afterward. objcopy uses BFD to do all its translation work; it has access to all the formats described in BFD and thus is able to recognize most formats without being told explicitly. See section `BFD' in Using LD.

objcopy can be used to generate S-records by using an output target of `srec' (e.g., use `-O srec').

objcopy can be used to generate a raw binary file by using an output target of `binary' (e.g., use `-O binary'). When objcopy generates a raw binary file, it will essentially produce a memory dump of the contents of the input object file. All symbols and relocation information will be discarded. The memory dump will start at the load address of the lowest section copied into the output file.

When generating an S-record or a raw binary file, it may be helpful to use `-S' to remove sections containing debugging information. In some cases `-R' will be useful to remove sections which contain information that is not needed by the binary file.

Note - objcopy is not able to change the endianness of its input files. If the input format has an endianness, (some formats do not), objcopy can only copy the inputs into file formats that have the same endianness or which have no endianness (eg `srec').

infile
outfile
The input and output files, respectively. If you do not specify outfile, objcopy creates a temporary file and destructively renames the result with the name of infile.

-I bfdname
--input-target=bfdname
Consider the source file's object format to be bfdname, rather than attempting to deduce it. See section 15.1 Target Selection, for more information.

-O bfdname
--output-target=bfdname
Write the output file using the object format bfdname. See section 15.1 Target Selection, for more information.

-F bfdname
--target=bfdname
Use bfdname as the object format for both the input and the output file; i.e., simply transfer data from source to destination with no translation. See section 15.1 Target Selection, for more information.

-B bfdarch
--binary-architecture=bfdarch
Useful when transforming a raw binary input file into an object file. In this case the output architecture can be set to bfdarch. This option will be ignored if the input file has a known bfdarch. You can access this binary data inside a program by referencing the special symbols that are created by the conversion process. These symbols are called _binary_objfile_start, _binary_objfile_end and _binary_objfile_size. e.g. you can transform a picture file into an object file and then access it in your code using these symbols.

-j sectionname
--only-section=sectionname
Copy only the named section from the input file to the output file. This option may be given more than once. Note that using this option inappropriately may make the output file unusable.

-R sectionname
--remove-section=sectionname
Remove any section named sectionname from the output file. This option may be given more than once. Note that using this option inappropriately may make the output file unusable.

-S
--strip-all
Do not copy relocation and symbol information from the source file.

-g
--strip-debug
Do not copy debugging symbols from the source file.

--strip-unneeded
Strip all symbols that are not needed for relocation processing.

-K symbolname
--keep-symbol=symbolname
Copy only symbol symbolname from the source file. This option may be given more than once.

-N symbolname
--strip-symbol=symbolname
Do not copy symbol symbolname from the source file. This option may be given more than once.

-G symbolname
--keep-global-symbol=symbolname
Keep only symbol symbolname global. Make all other symbols local to the file, so that they are not visible externally. This option may be given more than once.

-L symbolname
--localize-symbol=symbolname
Make symbol symbolname local to the file, so that it is not visible externally. This option may be given more than once.

-W symbolname
--weaken-symbol=symbolname
Make symbol symbolname weak. This option may be given more than once.

-x
--discard-all
Do not copy non-global symbols from the source file.

-X
--discard-locals
Do not copy compiler-generated local symbols. (These usually start with `L' or `.'.)

-b byte
--byte=byte
Keep only every byteth byte of the input file (header data is not affected). byte can be in the range from 0 to interleave-1, where interleave is given by the `-i' or `--interleave' option, or the default of 4. This option is useful for creating files to program ROM. It is typically used with an srec output target.

-i interleave
--interleave=interleave
Only copy one out of every interleave bytes. Select which byte to copy with the `-b' or `--byte' option. The default is 4. objcopy ignores this option if you do not specify either `-b' or `--byte'.

-p
--preserve-dates
Set the access and modification dates of the output file to be the same as those of the input file.

--debugging
Convert debugging information, if possible. This is not the default because only certain debugging formats are supported, and the conversion process can be time consuming.

--gap-fill val
Fill gaps between sections with val. This operation applies to the load address (LMA) of the sections. It is done by increasing the size of the section with the lower address, and filling in the extra space created with val.

--pad-to address
Pad the output file up to the load address address. This is done by increasing the size of the last section. The extra space is filled in with the value specified by `--gap-fill' (default zero).

--set-start val
Set the start address of the new file to val. Not all object file formats support setting the start address.

--change-start incr
--adjust-start incr
Change the start address by adding incr. Not all object file formats support setting the start address.

--change-addresses incr
--adjust-vma incr
Change the VMA and LMA addresses of all sections, as well as the start address, by adding incr. Some object file formats do not permit section addresses to be changed arbitrarily. Note that this does not relocate the sections; if the program expects sections to be loaded at a certain address, and this option is used to change the sections such that they are loaded at a different address, the program may fail.

--change-section-address section{=,+,-}val
--adjust-section-vma section{=,+,-}val
Set or change both the VMA address and the LMA address of the named section. If `=' is used, the section address is set to val. Otherwise, val is added to or subtracted from the section address. See the comments under `--change-addresses', above. If section does not exist in the input file, a warning will be issued, unless `--no-change-warnings' is used.

--change-section-lma section{=,+,-}val
Set or change the LMA address of the named section. The LMA address is the address where the section will be loaded into memory at program load time. Normally this is the same as the VMA address, which is the address of the section at program run time, but on some systems, especially those where a program is held in ROM, the two can be different. If `=' is used, the section address is set to val. Otherwise, val is added to or subtracted from the section address. See the comments under `--change-addresses', above. If section does not exist in the input file, a warning will be issued, unless `--no-change-warnings' is used.

--change-section-vma section{=,+,-}val
Set or change the VMA address of the named section. The VMA address is the address where the section will be located once the program has started executing. Normally this is the same as the LMA address, which is the address where the section will be loaded into memory, but on some systems, especially those where a program is held in ROM, the two can be different. If `=' is used, the section address is set to val. Otherwise, val is added to or subtracted from the section address. See the comments under `--change-addresses', above. If section does not exist in the input file, a warning will be issued, unless `--no-change-warnings' is used.

--change-warnings
--adjust-warnings
If `--change-section-address' or `--change-section-lma' or `--change-section-vma' is used, and the named section does not exist, issue a warning. This is the default.

--no-change-warnings
--no-adjust-warnings
Do not issue a warning if `--change-section-address' or `--adjust-section-lma' or `--adjust-section-vma' is used, even if the named section does not exist.

--set-section-flags section=flags
Set the flags for the named section. The flags argument is a comma separated string of flag names. The recognized names are `alloc', `contents', `load', `noload', `readonly', `code', `data', `rom', `share', and `debug'. You can set the `contents' flag for a section which does not have contents, but it is not meaningful to clear the `contents' flag of a section which does have contents--just remove the section instead. Not all flags are meaningful for all object file formats.

--add-section sectionname=filename
Add a new section named sectionname while copying the file. The contents of the new section are taken from the file filename. The size of the section will be the size of the file. This option only works on file formats which can support sections with arbitrary names.

--rename-section oldname=newname[,flags]
Rename a section from oldname to newname, optionally changing the section's flags to flags in the process. This has the advantage over usng a linker script to perform the rename in that the output stays as an object file and does not become a linked executable.

This option is particularly helpful when the input format is binary, since this will always create a section called .data. If for example, you wanted instead to create a section called .rodata containing binary data you could use the following command line to achieve it:

  objcopy -I binary -O <output_format> -B <architecture> \
   --rename-section .data=.rodata,alloc,load,readonly,data,contents \
   <input_binary_file> <output_object_file>

--change-leading-char
Some object file formats use special characters at the start of symbols. The most common such character is underscore, which compilers often add before every symbol. This option tells objcopy to change the leading character of every symbol when it converts between object file formats. If the object file formats use the same leading character, this option has no effect. Otherwise, it will add a character, or remove a character, or change a character, as appropriate.

--remove-leading-char
If the first character of a global symbol is a special symbol leading character used by the object file format, remove the character. The most common symbol leading character is underscore. This option will remove a leading underscore from all global symbols. This can be useful if you want to link together objects of different file formats with different conventions for symbol names. This is different from `--change-leading-char' because it always changes the symbol name when appropriate, regardless of the object file format of the output file.

--srec-len=ival
Meaningful only for srec output. Set the maximum length of the Srecords being produced to ival. This length covers both address, data and crc fields.

--srec-forceS3
Meaningful only for srec output. Avoid generation of S1/S2 records, creating S3-only record format.

--redefine-sym old=new
Change the name of a symbol old, to new. This can be useful when one is trying link two things together for which you have no source, and there are name collisions.

--weaken
Change all global symbols in the file to be weak. This can be useful when building an object which will be linked against other objects using the `-R' option to the linker. This option is only effective when using an object file format which supports weak symbols.

--keep-symbols=filename
Apply `--keep-symbol' option to each symbol listed in the file filename. filename is simply a flat file, with one symbol name per line. Line comments may be introduced by the hash character. This option may be given more than once.

--strip-symbols=filename
Apply `--strip-symbol' option to each symbol listed in the file filename. filename is simply a flat file, with one symbol name per line. Line comments may be introduced by the hash character. This option may be given more than once.

--keep-global-symbols=filename
Apply `--keep-global-symbol' option to each symbol listed in the file filename. filename is simply a flat file, with one symbol name per line. Line comments may be introduced by the hash character. This option may be given more than once.

--localize-symbols=filename
Apply `--localize-symbol' option to each symbol listed in the file filename. filename is simply a flat file, with one symbol name per line. Line comments may be introduced by the hash character. This option may be given more than once.

--weaken-symbols=filename
Apply `--weaken-symbol' option to each symbol listed in the file filename. filename is simply a flat file, with one symbol name per line. Line comments may be introduced by the hash character. This option may be given more than once.

--alt-machine-code=index
If the output architecture has alternate machine codes, use the indexth code instead of the default one. This is useful in case a machine is assigned an official code and the tool-chain adopts the new code, but other applications still depend on the original code being used.

-V
--version
Show the version number of objcopy.

-v
--verbose
Verbose output: list all object files modified. In the case of archives, `objcopy -V' lists all members of the archive.

--help
Show a summary of the options to objcopy.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. objdump

objdump [`-a'|`--archive-headers']
        [`-b' bfdname|`--target=bfdname']
        [`-C'|`--demangle'[=style] ]
        [`-d'|`--disassemble']
        [`-D'|`--disassemble-all']
        [`-z'|`--disassemble-zeroes']
        [`-EB'|`-EL'|`--endian='{big | little }]
        [`-f'|`--file-headers']
        [`--file-start-context']
        [`-g'|`--debugging']
        [`-h'|`--section-headers'|`--headers']
        [`-i'|`--info']
        [`-j' section|`--section='section]
        [`-l'|`--line-numbers']
        [`-S'|`--source']
        [`-m' machine|`--architecture='machine]
        [`-M' options|`--disassembler-options='options]
        [`-p'|`--private-headers']
        [`-r'|`--reloc']
        [`-R'|`--dynamic-reloc']
        [`-s'|`--full-contents']
        [`-G'|`--stabs']
        [`-t'|`--syms']
        [`-T'|`--dynamic-syms']
        [`-x'|`--all-headers']
        [`-w'|`--wide']
        [`--start-address='address]
        [`--stop-address='address]
        [`--prefix-addresses']
        [`--[no-]show-raw-insn']
        [`--adjust-vma='offset]
        [`-V'|`--version']
        [`-H'|`--help']
        objfile...

objdump displays information about one or more object files. The options control what particular information to display. This information is mostly useful to programmers who are working on the compilation tools, as opposed to programmers who just want their program to compile and work.

objfile... are the object files to be examined. When you specify archives, objdump shows information on each of the member object files.

The long and short forms of options, shown here as alternatives, are equivalent. At least one option from the list `-a,-d,-D,-f,-g,-G,-h,-H,-p,-r,-R,-S,-t,-T,-V,-x' must be given.

-a
--archive-header
If any of the objfile files are archives, display the archive header information (in a format similar to `ls -l'). Besides the information you could list with `ar tv', `objdump -a' shows the object file format of each archive member.

--adjust-vma=offset
When dumping information, first add offset to all the section addresses. This is useful if the section addresses do not correspond to the symbol table, which can happen when putting sections at particular addresses when using a format which can not represent section addresses, such as a.out.

-b bfdname
--target=bfdname
Specify that the object-code format for the object files is bfdname. This option may not be necessary; objdump can automatically recognize many formats.

For example,
objdump -b oasys -m vax -h fu.o
displays summary information from the section headers (`-h') of `fu.o', which is explicitly identified (`-m') as a VAX object file in the format produced by Oasys compilers. You can list the formats available with the `-i' option. See section 15.1 Target Selection, for more information.

-C
--demangle[=style]
Decode (demangle) low-level symbol names into user-level names. Besides removing any initial underscore prepended by the system, this makes C++ function names readable. Different compilers have different mangling styles. The optional demangling style argument can be used to choose an appropriate demangling style for your compiler. See section 9. c++filt, for more information on demangling.

-G
--debugging
Display debugging information. This attempts to parse debugging information stored in the file and print it out using a C like syntax. Only certain types of debugging information have been implemented.

-d
--disassemble
Display the assembler mnemonics for the machine instructions from objfile. This option only disassembles those sections which are expected to contain instructions.

-D
--disassemble-all
Like `-d', but disassemble the contents of all sections, not just those expected to contain instructions.

--prefix-addresses
When disassembling, print the complete address on each line. This is the older disassembly format.

--disassemble-zeroes
Normally the disassembly output will skip blocks of zeroes. This option directs the disassembler to disassemble those blocks, just like any other data.

-EB
-EL
--endian={big|little}
Specify the endianness of the object files. This only affects disassembly. This can be useful when disassembling a file format which does not describe endianness information, such as S-records.

-f
--file-header
Display summary information from the overall header of each of the objfile files.

--file-start-context
Specify that when displaying interlisted source code/disassembly (assumes `-S') from a file that has not yet been displayed, extend the context to the start of the file.

-h
--section-header
--header
Display summary information from the section headers of the object file.

File segments may be relocated to nonstandard addresses, for example by using the `-Ttext', `-Tdata', or `-Tbss' options to ld. However, some object file formats, such as a.out, do not store the starting address of the file segments. In those situations, although ld relocates the sections correctly, using `objdump -h' to list the file section headers cannot show the correct addresses. Instead, it shows the usual addresses, which are implicit for the target.

--help
Print a summary of the options to objdump and exit.

-i
--info
Display a list showing all architectures and object formats available for specification with `-b' or `-m'.

-j name
--section=name
Display information only for section name.

-l
--line-numbers
Label the display (using debugging information) with the filename and source line numbers corresponding to the object code or relocs shown. Only useful with `-d', `-D', or `-r'.

-m machine
--architecture=machine
Specify the architecture to use when disassembling object files. This can be useful when disassembling object files which do not describe architecture information, such as S-records. You can list the available architectures with the `-i' option.

-M options
--disassembler-options=options
Pass target specific information to the disassembler. Only supported on some targets.

If the target is an ARM architecture then this switch can be used to select which register name set is used during disassembler. Specifying `-M reg-name-std' (the default) will select the register names as used in ARM's instruction set documentation, but with register 13 called 'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying `-M reg-names-apcs' will select the name set used by the ARM Procedure Call Standard, whilst specifying `-M reg-names-raw' will just use `r' followed by the register number.

There are also two variants on the APCS register naming scheme enabled by `-M reg-names-atpcs' and `-M reg-names-special-atpcs' which use the ARM/Thumb Procedure Call Standard naming conventions. (Either with the normal register name or the special register names).

This option can also be used for ARM architectures to force the disassembler to interpret all instructions as Thumb instructions by using the switch `--disassembler-options=force-thumb'. This can be useful when attempting to disassemble thumb code produced by other compilers.

For the x86, some of the options duplicate functions of the `-m' switch, but allow finer grained control. Multiple selections from the following may be specified as a comma separated string. `x86-64', `i386' and `i8086' select disassembly for the given architecture. `intel' and `att' select between intel syntax mode and AT&T syntax mode. `addr32', `addr16', `data32' and `data16' specify the default address size and operand size. These four options will be overridden if `x86-64', `i386' or `i8086' appear later in the option string. Lastly, `suffix', when in AT&T mode, instructs the dissassembler to print a mnemonic suffix even when the suffix could be inferred by the operands.

For PPC, `booke', `booke32' and `booke64' select disassembly of BookE instructions. `32' and `64' select PowerPC and PowerPC64 disassembly, respectively.

-p
--private-headers
Print information that is specific to the object file format. The exact information printed depends upon the object file format. For some object file formats, no additional information is printed.

-r
--reloc
Print the relocation entries of the file. If used with `-d' or `-D', the relocations are printed interspersed with the disassembly.

-R
--dynamic-reloc
Print the dynamic relocation entries of the file. This is only meaningful for dynamic objects, such as certain types of shared libraries.

-s
--full-contents
Display the full contents of any sections requested.

-S
--source
Display source code intermixed with disassembly, if possible. Implies `-d'.

--show-raw-insn
When disassembling instructions, print the instruction in hex as well as in symbolic form. This is the default except when `--prefix-addresses' is used.

--no-show-raw-insn
When disassembling instructions, do not print the instruction bytes. This is the default when `--prefix-addresses' is used.

-G
--stabs
Display the full contents of any sections requested. Display the contents of the .stab and .stab.index and .stab.excl sections from an ELF file. This is only useful on systems (such as Solaris 2.0) in which .stab debugging symbol-table entries are carried in an ELF section. In most other file formats, debugging symbol-table entries are interleaved with linkage symbols, and are visible in the `--syms' output. For more information on stabs symbols, see section `Stabs Overview' in The "stabs" debug format.

--start-address=address
Start displaying data at the specified address. This affects the output of the `-d', `-r' and `-s' options.

--stop-address=address
Stop displaying data at the specified address. This affects the output of the `-d', `-r' and `-s' options.

-t
--syms
Print the symbol table entries of the file. This is similar to the information provided by the `nm' program.

-T
--dynamic-syms
Print the dynamic symbol table entries of the file. This is only meaningful for dynamic objects, such as certain types of shared libraries. This is similar to the information provided by the `nm' program when given the `-D' (`--dynamic') option.

--version
Print the version number of objdump and exit.

-x
--all-header
Display all available header information, including the symbol table and relocation entries. Using `-x' is equivalent to specifying all of `-a -f -h -r -t'.

-w
--wide
Format some lines for output devices that have more than 80 columns. Also do not truncate symbol names when they are displayed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. ranlib

ranlib [`-vV'] archive

ranlib generates an index to the contents of an archive and stores it in the archive. The index lists each symbol defined by a member of an archive that is a relocatable object file.

You may use `nm -s' or `nm --print-armap' to list this index.

An archive with such an index speeds up linking to the library and allows routines in the library to call each other without regard to their placement in the archive.

The GNU ranlib program is another form of GNU ar; running ranlib is completely equivalent to executing `ar -s'. See section 1. ar.

-v
-V
--version
Show the version number of ranlib.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. size

size [`-A'|`-B'|`--format='compatibility]
     [`--help']
     [`-d'|`-o'|`-x'|`--radix='number]
     [`-t'|`--totals']
     [`--target='bfdname] [`-V'|`--version']
     [objfile...]

The GNU size utility lists the section sizes--and the total size--for each of the object or archive files objfile in its argument list. By default, one line of output is generated for each object file or each module in an archive.

objfile... are the object files to be examined. If none are specified, the file a.out will be used.

The command line options have the following meanings:

-A
-B
--format=compatibility
Using one of these options, you can choose whether the output from GNU size resembles output from System V size (using `-A', or `--format=sysv'), or Berkeley size (using `-B', or `--format=berkeley'). The default is the one-line format similar to Berkeley's.

Here is an example of the Berkeley (default) format of output from size:
$ size --format=Berkeley ranlib size
text    data    bss     dec     hex     filename
294880  81920   11592   388392  5ed28   ranlib
294880  81920   11888   388688  5ee50   size

This is the same data, but displayed closer to System V conventions:

$ size --format=SysV ranlib size
ranlib  :
section         size         addr
.text         294880         8192
.data          81920       303104
.bss           11592       385024
Total         388392

size  :
section         size         addr
.text         294880         8192
.data          81920       303104
.bss           11888       385024
Total         388688

--help
Show a summary of acceptable arguments and options.

-d
-o
-x
--radix=number
Using one of these options, you can control whether the size of each section is given in decimal (`-d', or `--radix=10'); octal (`-o', or `--radix=8'); or hexadecimal (`-x', or `--radix=16'). In `--radix=number', only the three values (8, 10, 16) are supported. The total size is always given in two radices; decimal and hexadecimal for `-d' or `-x' output, or octal and hexadecimal if you're using `-o'.

-t
--totals
Show totals of all objects listed (Berkeley format listing mode only).

--target=bfdname
Specify that the object-code format for objfile is bfdname. This option may not be necessary; size can automatically recognize many formats. See section 15.1 Target Selection, for more information.

-V
--version
Display the version number of size.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. strings

strings [`-afov'] [`-'min-len]
        [`-n' min-len] [`--bytes='min-len]
        [`-t' radix] [`--radix='radix]
        [`-e' encoding] [`--encoding='encoding]
        [`-'] [`--all'] [`--print-file-name']
        [`--target='bfdname]
        [`--help'] [`--version'] file...

For each file given, GNU strings prints the printable character sequences that are at least 4 characters long (or the number given with the options below) and are followed by an unprintable character. By default, it only prints the strings from the initialized and loaded sections of object files; for other types of files, it prints the strings from the whole file.

strings is mainly useful for determining the contents of non-text files.

-a
--all
-
Do not scan only the initialized and loaded sections of object files; scan the whole files.

-f
--print-file-name
Print the name of the file before each string.

--help
Print a summary of the program usage on the standard output and exit.

-min-len
-n min-len
--bytes=min-len
Print sequences of characters that are at least min-len characters long, instead of the default 4.

-o
Like `-t o'. Some other versions of strings have `-o' act like `-t d' instead. Since we can not be compatible with both ways, we simply chose one.

-t radix
--radix=radix
Print the offset within the file before each string. The single character argument specifies the radix of the offset---`o' for octal, `x' for hexadecimal, or `d' for decimal.

-e encoding
--encoding=encoding
Select the character encoding of the strings that are to be found. Possible values for encoding are: `s' = single-byte characters (ASCII, ISO 8859, etc., default), `b' = 16-bit Bigendian, `l' = 16-bit Littleendian, `B' = 32-bit Bigendian, `L' = 32-bit Littleendian. Useful for finding wide character strings.

--target=bfdname
Specify an object code format other than your system's default format. See section 15.1 Target Selection, for more information.

-v
--version
Print the program version number on the standard output and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. strip

strip [`-F' bfdname |`--target='bfdname ]
      [`-I' bfdname |`--input-target='bfdname ]
      [`-O' bfdname |`--output-target='bfdname ]
      [`-s'|`--strip-all'] [`-S'|`-g'|`-d'|`--strip-debug']
      [`-K' symbolname |`--keep-symbol='symbolname ]
      [`-N' symbolname |`--strip-symbol='symbolname ]
      [`-x'|`--discard-all' ] [`-X' |`--discard-locals']
      [`-R' sectionname |`--remove-section='sectionname ]
      [`-o' file ] [`-p'|`--preserve-dates']
      [`-v' |`--verbose']  [`-V'|`--version'] [`--help']
      objfile...

GNU strip discards all symbols from object files objfile. The list of object files may include archives. At least one object file must be given.

strip modifies the files named in its argument, rather than writing modified copies under different names.

-F bfdname
--target=bfdname
Treat the original objfile as a file with the object code format bfdname, and rewrite it in the same format. See section 15.1 Target Selection, for more information.

--help
Show a summary of the options to strip and exit.

-I bfdname
--input-target=bfdname
Treat the original objfile as a file with the object code format bfdname. See section 15.1 Target Selection, for more information.

-O bfdname
--output-target=bfdname
Replace objfile with a file in the output format bfdname. See section 15.1 Target Selection, for more information.

-R sectionname
--remove-section=sectionname
Remove any section named sectionname from the output file. This option may be given more than once. Note that using this option inappropriately may make the output file unusable.

-s
--strip-all
Remove all symbols.

-g
-S
-d
--strip-debug
Remove debugging symbols only.

--strip-unneeded
Remove all symbols that are not needed for relocation processing.

-K symbolname
--keep-symbol=symbolname
Keep only symbol symbolname from the source file. This option may be given more than once.

-N symbolname
--strip-symbol=symbolname
Remove symbol symbolname from the source file. This option may be given more than once, and may be combined with strip options other than `-K'.

-o file
Put the stripped output in file, rather than replacing the existing file. When this argument is used, only one objfile argument may be specified.

-p
--preserve-dates
Preserve the access and modification dates of the file.

-x
--discard-all
Remove non-global symbols.

-X
--discard-locals
Remove compiler-generated local symbols. (These usually start with `L' or `.'.)

-V
--version
Show the version number for strip.

-v
--verbose
Verbose output: list all object files modified. In the case of archives, `strip -v' lists all members of the archive.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. c++filt

c++filt [`-_'|`--strip-underscores']
        [`-j'|`--java']
        [`-n'|`--no-strip-underscores']
        [`-s' format|`--format='format]
        [`--help']  [`--version']  [symbol...]

The C++ and Java languages provides function overloading, which means that you can write many functions with the same name (providing each takes parameters of different types). All C++ and Java function names are encoded into a low-level assembly label (this process is known as mangling). The c++filt (1) program does the inverse mapping: it decodes (demangles) low-level names into user-level names so that the linker can keep these overloaded functions from clashing.

Every alphanumeric word (consisting of letters, digits, underscores, dollars, or periods) seen in the input is a potential label. If the label decodes into a C++ name, the C++ name replaces the low-level name in the output.

You can use c++filt to decipher individual symbols:

c++filt symbol

If no symbol arguments are given, c++filt reads symbol names from the standard input and writes the demangled names to the standard output. All results are printed on the standard output.

-_
--strip-underscores
On some systems, both the C and C++ compilers put an underscore in front of every name. For example, the C name foo gets the low-level name _foo. This option removes the initial underscore. Whether c++filt removes the underscore by default is target dependent.

-j
--java
Prints demangled names using Java syntax. The default is to use C++ syntax.

-n
--no-strip-underscores
Do not remove the initial underscore.

-s format
--format=format
GNU nm can decode three different methods of mangling, used by different C++ compilers. The argument to this option selects which method it uses:

gnu
the one used by the GNU compiler (the default method)
lucid
the one used by the Lucid compiler
arm
the one specified by the C++ Annotated Reference Manual
hp
the one used by the HP compiler
edg
the one used by the EDG compiler
gnu-new-abi
the one used by the GNU compiler with the new ABI.

--help
Print a summary of the options to c++filt and exit.

--version
Print the version number of c++filt and exit.

Warning: c++filt is a new utility, and the details of its user interface are subject to change in future releases. In particular, a command-line option may be required in the the future to decode a name passed as an argument on the command line; in other words,

c++filt symbol

may in a future release become

c++filt option symbol

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10. addr2line

addr2line [`-b' bfdname|`--target='bfdname]
          [`-C'|`--demangle'[=style]
          [`-e' filename|`--exe='filename]
          [`-f'|`--functions'] [`-s'|`--basename']
          [`-H'|`--help'] [`-V'|`--version']
          [addr addr ...]

addr2line translates program addresses into file names and line numbers. Given an address and an executable, it uses the debugging information in the executable to figure out which file name and line number are associated with a given address.

The executable to use is specified with the `-e' option. The default is the file `a.out'.

addr2line has two modes of operation.

In the first, hexadecimal addresses are specified on the command line, and addr2line displays the file name and line number for each address.

In the second, addr2line reads hexadecimal addresses from standard input, and prints the file name and line number for each address on standard output. In this mode, addr2line may be used in a pipe to convert dynamically chosen addresses.

The format of the output is `FILENAME:LINENO'. The file name and line number for each address is printed on a separate line. If the -f option is used, then each `FILENAME:LINENO' line is preceded by a `FUNCTIONNAME' line which is the name of the function containing the address.

If the file name or function name can not be determined, addr2line will print two question marks in their place. If the line number can not be determined, addr2line will print 0.

The long and short forms of options, shown here as alternatives, are equivalent.

-b bfdname
--target=bfdname
Specify that the object-code format for the object files is bfdname.

-C
--demangle[=style]
Decode (demangle) low-level symbol names into user-level names. Besides removing any initial underscore prepended by the system, this makes C++ function names readable. Different compilers have different mangling styles. The optional demangling style argument can be used to choose an appropriate demangling style for your compiler. See section 9. c++filt, for more information on demangling.

-e filename
--exe=filename
Specify the name of the executable for which addresses should be translated. The default file is `a.out'.

-f
--functions
Display function names as well as file and line number information.

-s
--basenames
Display only the base of each file name.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11. nlmconv

nlmconv converts a relocatable object file into a NetWare Loadable Module.

Warning: nlmconv is not always built as part of the binary utilities, since it is only useful for NLM targets.

nlmconv [`-I' bfdname|`--input-target='bfdname]
        [`-O' bfdname|`--output-target='bfdname]
        [`-T' headerfile|`--header-file='headerfile]
        [`-d'|`--debug'] [`-l' linker|`--linker='linker]
        [`-h'|`--help'] [`-V'|`--version']
        infile outfile

nlmconv converts the relocatable `i386' object file infile into the NetWare Loadable Module outfile, optionally reading headerfile for NLM header information. For instructions on writing the NLM command file language used in header files, see the `linkers' section, `NLMLINK' in particular, of the NLM Development and Tools Overview, which is part of the NLM Software Developer's Kit ("NLM SDK"), available from Novell, Inc. nlmconv uses the GNU Binary File Descriptor library to read infile; see section `BFD' in Using LD, for more information.

nlmconv can perform a link step. In other words, you can list more than one object file for input if you list them in the definitions file (rather than simply specifying one input file on the command line). In this case, nlmconv calls the linker for you.

-I bfdname
--input-target=bfdname
Object format of the input file. nlmconv can usually determine the format of a given file (so no default is necessary). See section 15.1 Target Selection, for more information.

-O bfdname
--output-target=bfdname
Object format of the output file. nlmconv infers the output format based on the input format, e.g. for a `i386' input file the output format is `nlm32-i386'. See section 15.1 Target Selection, for more information.

-T headerfile
--header-file=headerfile
Reads headerfile for NLM header information. For instructions on writing the NLM command file language used in header files, see see the `linkers' section, of the NLM Development and Tools Overview, which is part of the NLM Software Developer's Kit, available from Novell, Inc.

-d
--debug
Displays (on standard error) the linker command line used by nlmconv.

-l linker
--linker=linker
Use linker for any linking. linker can be an absolute or a relative pathname.

-h
--help
Prints a usage summary.

-V
--version
Prints the version number for nlmconv.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12. windres

windres may be used to manipulate Windows resources.

Warning: windres is not always built as part of the binary utilities, since it is only useful for Windows targets.

windres [options] [input-file] [output-file]

windres reads resources from an input file and copies them into an output file. Either file may be in one of three formats:

rc
A text format read by the Resource Compiler.

res
A binary format generated by the Resource Compiler.

coff
A COFF object or executable.

The exact description of these different formats is available in documentation from Microsoft.

When windres converts from the rc format to the res format, it is acting like the Windows Resource Compiler. When windres converts from the res format to the coff format, it is acting like the Windows CVTRES program.

When windres generates an rc file, the output is similar but not identical to the format expected for the input. When an input rc file refers to an external filename, an output rc file will instead include the file contents.

If the input or output format is not specified, windres will guess based on the file name, or, for the input file, the file contents. A file with an extension of `.rc' will be treated as an rc file, a file with an extension of `.res' will be treated as a res file, and a file with an extension of `.o' or `.exe' will be treated as a coff file.

If no output file is specified, windres will print the resources in rc format to standard output.

The normal use is for you to write an rc file, use windres to convert it to a COFF object file, and then link the COFF file into your application. This will make the resources described in the rc file available to Windows.

-i filename
--input filename
The name of the input file. If this option is not used, then windres will use the first non-option argument as the input file name. If there are no non-option arguments, then windres will read from standard input. windres can not read a COFF file from standard input.

-o filename
--output filename
The name of the output file. If this option is not used, then windres will use the first non-option argument, after any used for the input file name, as the output file name. If there is no non-option argument, then windres will write to standard output. windres can not write a COFF file to standard output.

-I format
--input-format format
The input format to read. format may be `res', `rc', or `coff'. If no input format is specified, windres will guess, as described above.

-O format
--output-format format
The output format to generate. format may be `res', `rc', or `coff'. If no output format is specified, windres will guess, as described above.

-F target
--target target
Specify the BFD format to use for a COFF file as input or output. This is a BFD target name; you can use the `--help' option to see a list of supported targets. Normally windres will use the default format, which is the first one listed by the `--help' option. 15.1 Target Selection.

--preprocessor program
When windres reads an rc file, it runs it through the C preprocessor first. This option may be used to specify the preprocessor to use, including any leading arguments. The default preprocessor argument is gcc -E -xc-header -DRC_INVOKED.

--include-dir directory
Specify an include directory to use when reading an rc file. windres will pass this to the preprocessor as an `-I' option. windres will also search this directory when looking for files named in the rc file.

-D target
--define sym[=val]
Specify a `-D' option to pass to the preprocessor when reading an rc file.

-v
Enable verbose mode. This tells you what the preprocessor is if you didn't specify one.

--language val
Specify the default language to use when reading an rc file. val should be a hexadecimal language code. The low eight bits are the language, and the high eight bits are the sublanguage.

--use-temp-file
Use a temporary file to instead of using popen to read the output of the preprocessor. Use this option if the popen implementation is buggy on the host (eg., certain non-English language versions of Windows 95 and Windows 98 are known to have buggy popen where the output will instead go the console).

--no-use-temp-file
Use popen, not a temporary file, to read the output of the preprocessor. This is the default behaviour.

--help
Prints a usage summary.

--version
Prints the version number for windres.

--yydebug
If windres is compiled with YYDEBUG defined as 1, this will turn on parser debugging.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13. Create files needed to build and use DLLs

dlltool may be used to create the files needed to build and use dynamic link libraries (DLLs).

Warning: dlltool is not always built as part of the binary utilities, since it is only useful for those targets which support DLLs.

dlltool [`-d'|`--input-def' def-file-name]
        [`-b'|`--base-file' base-file-name]
        [`-e'|`--output-exp' exports-file-name]
        [`-z'|`--output-def' def-file-name]
        [`-l'|`--output-lib' library-file-name]
        [`--export-all-symbols'] [`--no-export-all-symbols']
        [`--exclude-symbols' list]
        [`--no-default-excludes']
        [`-S'|`--as' path-to-assembler] [`-f'|`--as-flags' options]
        [`-D'|`--dllname' name] [`-m'|`--machine' machine]
        [`-a'|`--add-indirect'] [`-U'|`--add-underscore'] [`-k'|`--kill-at']
        [`-A'|`--add-stdcall-alias']
        [`-x'|`--no-idata4'] [`-c'|`--no-idata5'] [`-i'|`--interwork']
        [`-n'|`--nodelete'] [`-v'|`--verbose']
        [`-h'|`--help'] [`-V'|`--version']
        [object-file ...]

dlltool reads its inputs, which can come from the `-d' and `-b' options as well as object files specified on the command line. It then processes these inputs and if the `-e' option has been specified it creates a exports file. If the `-l' option has been specified it creates a library file and if the `-z' option has been specified it creates a def file. Any or all of the `-e', `-l' and `-z' options can be present in one invocation of dlltool.

When creating a DLL, along with the source for the DLL, it is necessary to have three other files. dlltool can help with the creation of these files.

The first file is a `.def' file which specifies which functions are exported from the DLL, which functions the DLL imports, and so on. This is a text file and can be created by hand, or dlltool can be used to create it using the `-z' option. In this case dlltool will scan the object files specified on its command line looking for those functions which have been specially marked as being exported and put entries for them in the .def file it creates.

In order to mark a function as being exported from a DLL, it needs to have an `-export:<name_of_function>' entry in the `.drectve' section of the object file. This can be done in C by using the asm() operator:

  asm (".section .drectve");
  asm (".ascii \"-export:my_func\"");

  int my_func (void) { ... }

The second file needed for DLL creation is an exports file. This file is linked with the object files that make up the body of the DLL and it handles the interface between the DLL and the outside world. This is a binary file and it can be created by giving the `-e' option to dlltool when it is creating or reading in a .def file.

The third file needed for DLL creation is the library file that programs will link with in order to access the functions in the DLL. This file can be created by giving the `-l' option to dlltool when it is creating or reading in a .def file.

dlltool builds the library file by hand, but it builds the exports file by creating temporary files containing assembler statements and then assembling these. The `-S' command line option can be used to specify the path to the assembler that dlltool will use, and the `-f' option can be used to pass specific flags to that assembler. The `-n' can be used to prevent dlltool from deleting these temporary assembler files when it is done, and if `-n' is specified twice then this will prevent dlltool from deleting the temporary object files it used to build the library.

Here is an example of creating a DLL from a source file `dll.c' and also creating a program (from an object file called `program.o') that uses that DLL:

  gcc -c dll.c
  dlltool -e exports.o -l dll.lib dll.o
  gcc dll.o exports.o -o dll.dll
  gcc program.o dll.lib -o program

The command line options have the following meanings:

-d filename
--input-def filename
Specifies the name of a .def file to be read in and processed.

-b filename
--base-file filename
Specifies the name of a base file to be read in and processed. The contents of this file will be added to the relocation section in the exports file generated by dlltool.

-e filename
--output-exp filename
Specifies the name of the export file to be created by dlltool.

-z filename
--output-def filename
Specifies the name of the .def file to be created by dlltool.

-l filename
--output-lib filename
Specifies the name of the library file to be created by dlltool.

--export-all-symbols
Treat all global and weak defined symbols found in the input object files as symbols to be exported. There is a small list of symbols which are not exported by default; see the `--no-default-excludes' option. You may add to the list of symbols to not export by using the `--exclude-symbols' option.

--no-export-all-symbols
Only export symbols explicitly listed in an input .def file or in `.drectve' sections in the input object files. This is the default behaviour. The `.drectve' sections are created by `dllexport' attributes in the source code.

--exclude-symbols list
Do not export the symbols in list. This is a list of symbol names separated by comma or colon characters. The symbol names should not contain a leading underscore. This is only meaningful when `--export-all-symbols' is used.

--no-default-excludes
When `--export-all-symbols' is used, it will by default avoid exporting certain special symbols. The current list of symbols to avoid exporting is `DllMain@12', `DllEntryPoint@0', `impure_ptr'. You may use the `--no-default-excludes' option to go ahead and export these special symbols. This is only meaningful when `--export-all-symbols' is used.

-S path
--as path
Specifies the path, including the filename, of the assembler to be used to create the exports file.

-f options
--as-flags options
Specifies any specific command line options to be passed to the assembler when building the exports file. This option will work even if the `-S' option is not used. This option only takes one argument, and if it occurs more than once on the command line, then later occurrences will override earlier occurrences. So if it is necessary to pass multiple options to the assembler they should be enclosed in double quotes.

-D name
--dll-name name
Specifies the name to be stored in the .def file as the name of the DLL when the `-e' option is used. If this option is not present, then the filename given to the `-e' option will be used as the name of the DLL.

-m machine
-machine machine
Specifies the type of machine for which the library file should be built. dlltool has a built in default type, depending upon how it was created, but this option can be used to override that. This is normally only useful when creating DLLs for an ARM processor, when the contents of the DLL are actually encode using Thumb instructions.

-a
--add-indirect
Specifies that when dlltool is creating the exports file it should add a section which allows the exported functions to be referenced without using the import library. Whatever the hell that means!

-U
--add-underscore
Specifies that when dlltool is creating the exports file it should prepend an underscore to the names of the exported functions.

-k
--kill-at
Specifies that when dlltool is creating the exports file it should not append the string `@ <number>'. These numbers are called ordinal numbers and they represent another way of accessing the function in a DLL, other than by name.

-A
--add-stdcall-alias
Specifies that when dlltool is creating the exports file it should add aliases for stdcall symbols without `@ <number>' in addition to the symbols with `@ <number>'.

-x
--no-idata4
Specifies that when dlltool is creating the exports and library files it should omit the .idata4 section. This is for compatibility with certain operating systems.

-c
--no-idata5
Specifies that when dlltool is creating the exports and library files it should omit the .idata5 section. This is for compatibility with certain operating systems.

-i
--interwork
Specifies that dlltool should mark the objects in the library file and exports file that it produces as supporting interworking between ARM and Thumb code.

-n
--nodelete
Makes dlltool preserve the temporary assembler files it used to create the exports file. If this option is repeated then dlltool will also preserve the temporary object files it uses to create the library file.

-v
--verbose
Make dlltool describe what it is doing.

-h
--help
Displays a list of command line options and then exits.

-V
--version
Displays dlltool's version number and then exits.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

14. readelf

readelf [`-a'|`--all']
        [`-h'|`--file-header']
        [`-l'|`--program-headers'|`--segments']
        [`-S'|`--section-headers'|`--sections']
        [`-e'|`--headers']
        [`-s'|`--syms'|`--symbols']
        [`-n'|`--notes']
        [`-r'|`--relocs']
        [`-u'|`--unwind']
        [`-d'|`--dynamic']
        [`-V'|`--version-info']
        [`-D'|`--use-dynamic']
        [`-x' <number>|`--hex-dump='<number>]
        [`-w[liaprmfs]'|`--debug-dump'[=line,=info,=abbrev,=pubnames,=ranges,=macro,=frames,=str]]
        [`-histogram']
        [`-v'|`--version']
        [`-W'|`--wide']
        [`-H'|`--help']
        elffile...

readelf displays information about one or more ELF format object files. The options control what particular information to display.

elffile... are the object files to be examined. At the moment, readelf does not support examining archives, nor does it support examing 64 bit ELF files.

The long and short forms of options, shown here as alternatives, are equivalent. At least one option besides `-v' or `-H' must be given.

-a
--all
Equivalent to specifiying `--file-header', `--program-headers', `--sections', `--symbols', `--relocs', `--dynamic', `--notes' and `--version-info'.

-h
--file-header
Displays the information contained in the ELF header at the start of the file.

-l
--program-headers
--segments
Displays the information contained in the file's segment headers, if it has any.

-S
--sections
--section-headers
Displays the information contained in the file's section headers, if it has any.

-s
--symbols
--syms
Displays the entries in symbol table section of the file, if it has one.

-e
--headers
Display all the headers in the file. Equivalent to `-h -l -S'.

-n
--notes
Displays the contents of the NOTE segment, if it exists.

-r
--relocs
Displays the contents of the file's relocation section, if it has one.

-u
--unwind
Displays the contents of the file's unwind section, if it has one. Only the unwind sections for IA64 ELF files are currently supported.

-d
--dynamic
Displays the contents of the file's dynamic section, if it has one.

-V
--version-info
Displays the contents of the version sections in the file, it they exist.

-D
--use-dynamic
When displaying symbols, this option makes readelf use the symbol table in the file's dynamic section, rather than the one in the symbols section.

-x <number>
--hex-dump=<number>
Displays the contents of the indicated section as a hexadecimal dump.

-w[liaprmfs]
--debug-dump[=line,=info,=abbrev,=pubnames,=ranges,=macro,=frames,=str]
Displays the contents of the debug sections in the file, if any are present. If one of the optional letters or words follows the switch then only data found in those specific sections will be dumped.

--histogram
Display a histogram of bucket list lengths when displaying the contents of the symbol tables.

-v
--version
Display the version number of readelf.

-W
--wide
Don't break output lines to fit into 80 columns. By default readelf breaks section header and segment listing lines for 64-bit ELF files, so that they fit into 80 columns. This option causes readelf to print each section header resp. each segment one a single line, which is far more readable on terminals wider than 80 columns.

-H
--help
Display the command line options understood by readelf.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15. Selecting the target system

You can specify three aspects of the target system to the GNU binary file utilities, each in several ways:

  • the target

  • the architecture

  • the linker emulation (which applies to the linker only)

In the following summaries, the lists of ways to specify values are in order of decreasing precedence. The ways listed first override those listed later.

The commands to list valid values only list the values for which the programs you are running were configured. If they were configured with `--enable-targets=all', the commands list most of the available values, but a few are left out; not all targets can be configured in at once because some of them can only be configured native (on hosts with the same type as the target system).

15.1 Target Selection
15.2 Architecture selection
15.3 Linker emulation selection

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.1 Target Selection

A target is an object file format. A given target may be supported for multiple architectures (see section 15.2 Architecture selection). A target selection may also have variations for different operating systems or architectures.

The command to list valid target values is `objdump -i' (the first column of output contains the relevant information).

Some sample values are: `a.out-hp300bsd', `ecoff-littlemips', `a.out-sunos-big'.

You can also specify a target using a configuration triplet. This is the same sort of name that is passed to `configure' to specify a target. When you use a configuration triplet as an argument, it must be fully canonicalized. You can see the canonical version of a triplet by running the shell script `config.sub' which is included with the sources.

Some sample configuration triplets are: `m68k-hp-bsd', `mips-dec-ultrix', `sparc-sun-sunos'.

objdump Target

Ways to specify:

  1. command line option: `-b' or `--target'

  2. environment variable GNUTARGET

  3. deduced from the input file

objcopy and strip Input Target

Ways to specify:

  1. command line options: `-I' or `--input-target', or `-F' or `--target'

  2. environment variable GNUTARGET

  3. deduced from the input file

objcopy and strip Output Target

Ways to specify:

  1. command line options: `-O' or `--output-target', or `-F' or `--target'

  2. the input target (see "objcopy and strip Input Target" above)

  3. environment variable GNUTARGET

  4. deduced from the input file

nm, size, and strings Target

Ways to specify:

  1. command line option: `--target'

  2. environment variable GNUTARGET

  3. deduced from the input file

Linker Input Target

Ways to specify:

  1. command line option: `-b' or `--format' (see section `Options' in Using LD)

  2. script command TARGET (see section `Format Commands' in Using LD)

  3. environment variable GNUTARGET (see section `Environment' in Using LD)

  4. the default target of the selected linker emulation (see section 15.3 Linker emulation selection)

Linker Output Target

Ways to specify:

  1. command line option: `-oformat' (see section `Options' in Using LD)

  2. script command OUTPUT_FORMAT (see section `Format Commands' in Using LD)

  3. the linker input target (see "Linker Input Target" above)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.2 Architecture selection

An architecture is a type of CPU on which an object file is to run. Its name may contain a colon, separating the name of the processor family from the name of the particular CPU.

The command to list valid architecture values is `objdump -i' (the second column contains the relevant information).

Sample values: `m68k:68020', `mips:3000', `sparc'.

objdump Architecture

Ways to specify:

  1. command line option: `-m' or `--architecture'

  2. deduced from the input file

objcopy, nm, size, strings Architecture

Ways to specify:

  1. deduced from the input file

Linker Input Architecture

Ways to specify:

  1. deduced from the input file

Linker Output Architecture

Ways to specify:

  1. script command OUTPUT_ARCH (see section `Miscellaneous Commands' in Using LD)

  2. the default architecture from the linker output target (see section 15.1 Target Selection)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15.3 Linker emulation selection

A linker emulation is a "personality" of the linker, which gives the linker default values for the other aspects of the target system. In particular, it consists of

  • the linker script

  • the target

  • several "hook" functions that are run at certain stages of the linking process to do special things that some targets require

The command to list valid linker emulation values is `ld -V'.

Sample values: `hp300bsd', `mipslit', `sun4'.

Ways to specify:

  1. command line option: `-m' (see section `Options' in Using LD)

  2. environment variable LDEMULATION

  3. compiled-in DEFAULT_EMULATION from `Makefile', which comes from EMUL in `config/target.mt'

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16. Reporting Bugs

Your bug reports play an essential role in making the binary utilities reliable.

Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of the binary utilities work better. Bug reports are your contribution to their maintenance.

In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug.

16.1 Have you found a bug?
16.2 How to report bugs

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1 Have you found a bug?

If you are not sure whether you have found a bug, here are some guidelines:

  • If a binary utility gets a fatal signal, for any input whatever, that is a bug. Reliable utilities never crash.

  • If a binary utility produces an error message for valid input, that is a bug.

  • If you are an experienced user of binary utilities, your suggestions for improvement are welcome in any case.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2 How to report bugs

A number of companies and individuals offer support for GNU products. If you obtained the binary utilities from a support organization, we recommend you contact that organization first.

You can find contact information for many support companies and individuals in the file `etc/SERVICE' in the GNU Emacs distribution.

In any event, we also recommend that you send bug reports for the binary utilities to `bug-binutils@gnu.org'.

The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!

Often people omit facts because they think they know what causes the problem and assume that some details do not matter. Thus, you might assume that the name of a file you use in an example does not matter. Well, probably it does not, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that pathname is stored in memory; perhaps, if the pathname were different, the contents of that location would fool the utility into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable us to fix the bug if it is new to us. Therefore, always write your bug reports on the assumption that the bug has not been reported previously.

Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" Those bug reports are useless, and we urge everyone to refuse to respond to them except to chide the sender to report bugs properly.

To enable us to fix the bug, you should include all these things:

  • The version of the utility. Each utility announces it if you start it with the `--version' argument.

    Without this, we will not know whether there is any point in looking for the bug in the current version of the binary utilities.

  • Any patches you may have applied to the source, including any patches made to the BFD library.

  • The type of machine you are using, and the operating system name and version number.

  • What compiler (and its version) was used to compile the utilities--e.g. "gcc-2.7".

  • The command arguments you gave the utility to observe the bug. To guarantee you will not omit something important, list them all. A copy of the Makefile (or the output from make) is sufficient.

    If we were to try to guess the arguments, we would probably guess wrong and then we might not encounter the bug.

  • A complete input file, or set of input files, that will reproduce the bug. If the utility is reading an object file or files, then it is generally most helpful to send the actual object files, uuencoded if necessary to get them through the mail system. Note that `bug-binutils@gnu.org' is a mailing list, so you should avoid sending very large files to it. Making the files available for anonymous FTP is OK.

    If the source files were produced exclusively using GNU programs (e.g., gcc, gas, and/or the GNU ld), then it may be OK to send the source files rather than the object files. In this case, be sure to say exactly what version of gcc, or whatever, was used to produce the object files. Also say how gcc, or whatever, was configured.

  • A description of what behavior you observe that you believe is incorrect. For example, "It gets a fatal signal."

    Of course, if the bug is that the utility gets a fatal signal, then we will certainly notice it. But if the bug is incorrect output, we might not notice unless it is glaringly wrong. You might as well not give us a chance to make a mistake.

    Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as your copy of the utility is out of synch, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations.

  • If you wish to suggest changes to the source, send us context diffs, as generated by diff with the `-u', `-c', or `-p' option. Always send diffs from the old file to the new file. If you wish to discuss something in the ld source, refer to it by context, not by line number.

    The line numbers in our development sources will not match those in your sources. Your line numbers would convey no useful information to us.

Here are some things that are not necessary:

  • A description of the envelope of the bug.

    Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it.

    This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. We recommend that you save your time for something else.

    Of course, if you can find a simpler example to report instead of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take less time, and so on.

    However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used.

  • A patch for the bug.

    A patch for the bug does help us if it is a good one. But do not omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all.

    Sometimes with programs as complicated as the binary utilities it is very hard to construct an example that will make the program follow a certain path through the code. If you do not send us the example, we will not be able to construct one, so we will not be able to verify that the bug is fixed.

    And if we cannot understand what bug you are trying to fix, or why your patch should be an improvement, we will not install it. A test case will help us to understand.

  • A guess about what the bug is or what it depends on.

    Such guesses are usually wrong. Even we cannot guess right about such things without first using the debugger to find the facts.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17. GNU Free Documentation License

GNU Free Documentation License Version 1.1, March 2000

Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

    Copyright (c)  YEAR  YOUR NAME.
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.1
    or any later version published by the Free Software Foundation;
    with the Invariant Sections being LIST THEIR TITLES, with the
    Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Index

Jump to: .
A B C D E F G H I L M N O P Q R S U V W

 | Index Entry | Section
. |  |
 | .stab | 4. objdump
A |  |
 | addr2line | 10. addr2line
 | address to file name and line number | 10. addr2line
 | all header information, object file | 4. objdump
 | ar | 1. ar
 | ar compatibility | 1. ar
 | architecture | 4. objdump
 | architectures available | 4. objdump
 | archive contents | 5. ranlib
 | archive headers | 4. objdump
 | archives | 1. ar
B |  |
 | base files | 13. Create files needed to build and use DLLs
 | bug criteria | 16.1 Have you found a bug?
 | bug reports | 16.2 How to report bugs
 | bugs | 16. Reporting Bugs
 | bugs, reporting | 16.2 How to report bugs
C |  |
 | c++filt | 9. c++filt
 | changing object addresses | 3. objcopy
 | changing section address | 3. objcopy
 | changing section LMA | 3. objcopy
 | changing section VMA | 3. objcopy
 | changing start address | 3. objcopy
 | collections of files | 1. ar
 | compatibility, ar | 1. ar
 | contents of archive | 1.1 Controlling ar on the command line
 | crash | 16.1 Have you found a bug?
 | creating archives | 1.1 Controlling ar on the command line
 | cxxfilt | 9. c++filt
D |  |
 | dates in archive | 1.1 Controlling ar on the command line
 | debug symbols | 4. objdump
 | debugging symbols | 2. nm
 | deleting from archive | 1.1 Controlling ar on the command line
 | demangling C++ symbols | 9. c++filt
 | demangling in nm | 2. nm
 | demangling in objdump | 4. objdump
 | demangling in objdump | 10. addr2line
 | disassembling object code | 4. objdump
 | disassembly architecture | 4. objdump
 | disassembly endianness | 4. objdump
 | disassembly, with source | 4. objdump
 | discarding symbols | 8. strip
 | DLL | 13. Create files needed to build and use DLLs
 | dlltool | 13. Create files needed to build and use DLLs
 | dynamic relocation entries, in object file | 4. objdump
 | dynamic symbol table entries, printing | 4. objdump
 | dynamic symbols | 2. nm
E |  |
 | ELF core notes | 14. readelf
 | ELF dynamic section information | 14. readelf
 | ELF file header information | 14. readelf
 | ELF file information | 14. readelf
 | ELF object file format | 4. objdump
 | ELF program header information | 14. readelf
 | ELF reloc information | 14. readelf
 | ELF section information | 14. readelf
 | ELF segment information | 14. readelf
 | ELF symbol table information | 14. readelf
 | ELF version sections informations | 14. readelf
 | endianness | 4. objdump
 | error on valid input | 16.1 Have you found a bug?
 | external symbols | 2. nm
 | external symbols | 2. nm
 | external symbols | 2. nm
 | extract from archive | 1.1 Controlling ar on the command line
F |  |
 | fatal signal | 16.1 Have you found a bug?
 | file name | 2. nm
G |  |
 | GNU Free Documentation License | 17. GNU Free Documentation License
H |  |
 | header information, all | 4. objdump
I |  |
 | input .def file | 13. Create files needed to build and use DLLs
 | input file name | 2. nm
L |  |
 | libraries | 1. ar
 | listings strings | 7. strings
M |  |
 | machine instructions | 4. objdump
 | moving in archive | 1.1 Controlling ar on the command line
 | MRI compatibility, ar | 1.2 Controlling ar with a script
N |  |
 | name duplication in archive | 1.1 Controlling ar on the command line
 | name length | 1. ar
 | nm | 2. nm
 | nm compatibility | 2. nm
 | nm compatibility | 2. nm
 | nm format | 2. nm
 | nm format | 2. nm
 | not writing archive index | 1.1 Controlling ar on the command line
O |  |
 | objdump | 4. objdump
 | object code format | 2. nm
 | object code format | 4. objdump
 | object code format | 6. size
 | object code format | 7. strings
 | object code format | 10. addr2line
 | object file header | 4. objdump
 | object file information | 4. objdump
 | object file sections | 4. objdump
 | object formats available | 4. objdump
 | operations on archive | 1.1 Controlling ar on the command line
P |  |
 | printing from archive | 1.1 Controlling ar on the command line
 | printing strings | 7. strings
Q |  |
 | quick append to archive | 1.1 Controlling ar on the command line
R |  |
 | radix for section sizes | 6. size
 | ranlib | 5. ranlib
 | readelf | 14. readelf
 | relative placement in archive | 1.1 Controlling ar on the command line
 | relocation entries, in object file | 4. objdump
 | removing symbols | 8. strip
 | repeated names in archive | 1.1 Controlling ar on the command line
 | replacement in archive | 1.1 Controlling ar on the command line
 | reporting bugs | 16. Reporting Bugs
S |  |
 | scripts, ar | 1.2 Controlling ar with a script
 | section addresses in objdump | 4. objdump
 | section headers | 4. objdump
 | section information | 4. objdump
 | section sizes | 6. size
 | sections, full contents | 4. objdump
 | size | 6. size
 | size display format | 6. size
 | size number format | 6. size
 | sorting symbols | 2. nm
 | source code context | 4. objdump
 | source disassembly | 4. objdump
 | source file name | 2. nm
 | source filenames for object files | 4. objdump
 | stab | 4. objdump
 | start-address | 4. objdump
 | stop-address | 4. objdump
 | strings | 7. strings
 | strings, printing | 7. strings
 | strip | 8. strip
 | symbol index | 1. ar
 | symbol index | 5. ranlib
 | symbol index, listing | 2. nm
 | symbol line numbers | 2. nm
 | symbol table entries, printing | 4. objdump
 | symbols | 2. nm
 | symbols, discarding | 8. strip
U |  |
 | undefined symbols | 2. nm
 | undefined symbols | 2. nm
 | Unix compatibility, ar | 1.1 Controlling ar on the command line
 | unwind information | 14. readelf
 | updating an archive | 1.1 Controlling ar on the command line
V |  |
 | version |
 | VMA in objdump | 4. objdump
W |  |
 | wide output, printing | 4. objdump
 | writing archive index | 1.1 Controlling ar on the command line

Jump to: .
A B C D E F G H I L M N O P Q R S U V W

[Top] [Contents] [Index] [ ? ]

Footnotes

(1)

MS-DOS does not allow + characters in file names, so on MS-DOS this program is named cxxfilt.

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. ar
      1.1 Controlling ar on the command line
      1.2 Controlling ar with a script
    2. nm
    3. objcopy
    4. objdump
    5. ranlib
    6. size
    7. strings
    8. strip
    9. c++filt
    10. addr2line
    11. nlmconv
    12. windres
    13. Create files needed to build and use DLLs
    14. readelf
    15. Selecting the target system
      15.1 Target Selection
      15.2 Architecture selection
      15.3 Linker emulation selection
    16. Reporting Bugs
      16.1 Have you found a bug?
      16.2 How to report bugs
    17. GNU Free Documentation License
    Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. ar
2. nm
3. objcopy
4. objdump
5. ranlib
6. size
7. strings
8. strip
9. c++filt
10. addr2line
11. nlmconv
12. windres
13. Create files needed to build and use DLLs
14. readelf
15. Selecting the target system
16. Reporting Bugs
17. GNU Free Documentation License
Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on May 3, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on May 3, 2002 using texi2html


Bison 1.35

Table of Contents

  • Bison
  • Introduction
  • Conditions for Using Bison
  • GNU GENERAL PUBLIC LICENSE
    • Preamble
    • Appendix: How to Apply These Terms to Your New Programs
  • The Concepts of Bison
    • Languages and Context-Free Grammars
    • From Formal Rules to Bison Input
    • Semantic Values
    • Semantic Actions
    • Locations
    • Bison Output: the Parser File
    • Stages in Using Bison
    • The Overall Layout of a Bison Grammar
  • Examples
    • Reverse Polish Notation Calculator
      • Declarations for rpcalc
      • Grammar Rules for rpcalc
        • Explanation of input
        • Explanation of line
        • Explanation of expr
      • The rpcalc Lexical Analyzer
      • The Controlling Function
      • The Error Reporting Routine
      • Running Bison to Make the Parser
      • Compiling the Parser File
    • Infix Notation Calculator: calc
    • Simple Error Recovery
    • Location Tracking Calculator: ltcalc
      • Declarations for ltcalc
      • Grammar Rules for ltcalc
      • The ltcalc Lexical Analyzer.
    • Multi-Function Calculator: mfcalc
      • Declarations for mfcalc
      • Grammar Rules for mfcalc
      • The mfcalc Symbol Table
    • Exercises
  • Bison Grammar Files
    • Outline of a Bison Grammar
      • The C Declarations Section
      • The Bison Declarations Section
      • The Grammar Rules Section
      • The Additional C Code Section
    • Symbols, Terminal and Nonterminal
    • Syntax of Grammar Rules
    • Recursive Rules
    • Defining Language Semantics
      • Data Types of Semantic Values
      • More Than One Value Type
      • Actions
      • Data Types of Values in Actions
      • Actions in Mid-Rule
    • Tracking Locations
      • Data Type of Locations
      • Actions and Locations
      • Default Action for Locations
    • Bison Declarations
      • Token Type Names
      • Operator Precedence
      • The Collection of Value Types
      • Nonterminal Symbols
      • Suppressing Conflict Warnings
      • The Start-Symbol
      • A Pure (Reentrant) Parser
      • Bison Declaration Summary
    • Multiple Parsers in the Same Program
  • Parser C-Language Interface
    • The Parser Function yyparse
    • The Lexical Analyzer Function yylex
      • Calling Convention for yylex
      • Semantic Values of Tokens
      • Textual Positions of Tokens
      • Calling Conventions for Pure Parsers
    • The Error Reporting Function yyerror
    • Special Features for Use in Actions
  • The Bison Parser Algorithm
    • Look-Ahead Tokens
    • Shift/Reduce Conflicts
    • Operator Precedence
      • When Precedence is Needed
      • Specifying Operator Precedence
      • Precedence Examples
      • How Precedence Works
    • Context-Dependent Precedence
    • Parser States
    • Reduce/Reduce Conflicts
    • Mysterious Reduce/Reduce Conflicts
    • Stack Overflow, and How to Avoid It
  • Error Recovery
  • Handling Context Dependencies
    • Semantic Info in Token Types
    • Lexical Tie-ins
    • Lexical Tie-ins and Error Recovery
  • Debugging Your Parser
  • Invoking Bison
    • Bison Options
    • Environment Variables
    • Option Cross Key
    • Extension Limitations under DOS
    • Invoking Bison under VMS
  • Bison Symbols
  • Glossary
  • Copying This Manual
    • GNU Free Documentation License
      • ADDENDUM: How to use this License for your documents
  • Index

Node:Top, Next:Introduction, Up:(dir)

Bison

This manual documents version 1.35 of Bison, updated 25 February 2002.

  • Introduction:
  • Conditions:
  • Copying: The GNU General Public License says how you can copy and share Bison

    Tutorial sections:

  • Concepts: Basic concepts for understanding Bison.
  • Examples: Three simple explained examples of using Bison.

    Reference sections:

  • Grammar File: Writing Bison declarations and rules.
  • Interface: C-language interface to the parser function yyparse.
  • Algorithm: How the Bison parser works at run-time.
  • Error Recovery: Writing rules for error recovery.
  • Context Dependency: What to do if your language syntax is too messy for Bison to handle straightforwardly.
  • Debugging: Debugging Bison parsers that parse wrong.
  • Invocation: How to run Bison (to produce the parser source file).
  • Table of Symbols: All the keywords of the Bison language are explained.
  • Glossary: Basic concepts are explained.
  • Copying This Manual: License for copying this manual.
  • Index: Cross-references to the text.

    The Concepts of Bison

  • Language and Grammar: Languages and context-free grammars, as mathematical ideas.
  • Grammar in Bison: How we represent grammars for Bison's sake.
  • Semantic Values: Each token or syntactic grouping can have a semantic value (the value of an integer, the name of an identifier, etc.).
  • Semantic Actions: Each rule can have an action containing C code.
  • Bison Parser: What are Bison's input and output, how is the output used?
  • Stages: Stages in writing and running Bison grammars.
  • Grammar Layout: Overall structure of a Bison grammar file.

    Examples

  • RPN Calc: Reverse polish notation calculator; a first example with no operator precedence.
  • Infix Calc: Infix (algebraic) notation calculator. Operator precedence is introduced.
  • Simple Error Recovery: Continuing after syntax errors.
  • Location Tracking Calc: Demonstrating the use of @n and @$.
  • Multi-function Calc: Calculator with memory and trig functions. It uses multiple data-types for semantic values.
  • Exercises: Ideas for improving the multi-function calculator.

    Reverse Polish Notation Calculator

  • Decls: Bison and C declarations for rpcalc.
  • Rules: Grammar Rules for rpcalc, with explanation.
  • Lexer: The lexical analyzer.
  • Main: The controlling function.
  • Error: The error reporting function.
  • Gen: Running Bison on the grammar file.
  • Comp: Run the C compiler on the output code.

    Grammar Rules for rpcalc

  • Rpcalc Input:
  • Rpcalc Line:
  • Rpcalc Expr:

    Location Tracking Calculator: ltcalc

  • Decls: Bison and C declarations for ltcalc.
  • Rules: Grammar rules for ltcalc, with explanations.
  • Lexer: The lexical analyzer.

    Multi-Function Calculator: mfcalc

  • Decl: Bison declarations for multi-function calculator.
  • Rules: Grammar rules for the calculator.
  • Symtab: Symbol table management subroutines.

    Bison Grammar Files

  • Grammar Outline: Overall layout of the grammar file.
  • Symbols: Terminal and nonterminal symbols.
  • Rules: How to write grammar rules.
  • Recursion: Writing recursive rules.
  • Semantics: Semantic values and actions.
  • Declarations: All kinds of Bison declarations are described here.
  • Multiple Parsers: Putting more than one Bison parser in one program.

    Outline of a Bison Grammar

  • C Declarations: Syntax and usage of the C declarations section.
  • Bison Declarations: Syntax and usage of the Bison declarations section.
  • Grammar Rules: Syntax and usage of the grammar rules section.
  • C Code: Syntax and usage of the additional C code section.

    Defining Language Semantics

  • Value Type: Specifying one data type for all semantic values.
  • Multiple Types: Specifying several alternative data types.
  • Actions: An action is the semantic definition of a grammar rule.
  • Action Types: Specifying data types for actions to operate on.
  • Mid-Rule Actions: Most actions go at the end of a rule. This says when, why and how to use the exceptional action in the middle of a rule.

    Bison Declarations

  • Token Decl: Declaring terminal symbols.
  • Precedence Decl: Declaring terminals with precedence and associativity.
  • Union Decl: Declaring the set of all semantic value types.
  • Type Decl: Declaring the choice of type for a nonterminal symbol.
  • Expect Decl: Suppressing warnings about shift/reduce conflicts.
  • Start Decl: Specifying the start symbol.
  • Pure Decl: Requesting a reentrant parser.
  • Decl Summary: Table of all Bison declarations.

    Parser C-Language Interface

  • Parser Function: How to call yyparse and what it returns.
  • Lexical: You must supply a function yylex which reads tokens.
  • Error Reporting: You must supply a function yyerror.
  • Action Features: Special features for use in actions.

    The Lexical Analyzer Function yylex

  • Calling Convention: How yyparse calls yylex.
  • Token Values: How yylex must return the semantic value of the token it has read.
  • Token Positions: How yylex must return the text position (line number, etc.) of the token, if the actions want that.
  • Pure Calling: How the calling convention differs in a pure parser (see A Pure (Reentrant) Parser).

    The Bison Parser Algorithm

  • Look-Ahead: Parser looks one token ahead when deciding what to do.
  • Shift/Reduce: Conflicts: when either shifting or reduction is valid.
  • Precedence: Operator precedence works by resolving conflicts.
  • Contextual Precedence: When an operator's precedence depends on context.
  • Parser States: The parser is a finite-state-machine with stack.
  • Reduce/Reduce: When two rules are applicable in the same situation.
  • Mystery Conflicts: Reduce/reduce conflicts that look unjustified.
  • Stack Overflow: What happens when stack gets full. How to avoid it.

    Operator Precedence

  • Why Precedence: An example showing why precedence is needed.
  • Using Precedence: How to specify precedence in Bison grammars.
  • Precedence Examples: How these features are used in the previous example.
  • How Precedence: How they work.

    Handling Context Dependencies

  • Semantic Tokens: Token parsing can depend on the semantic context.
  • Lexical Tie-ins: Token parsing can depend on the syntactic context.
  • Tie-in Recovery: Lexical tie-ins have implications for how error recovery rules must be written.

    Invoking Bison

  • Bison Options: All the options described in detail, in alphabetical order by short options.
  • Option Cross Key: Alphabetical list of long options.
  • Extension Limitations Under DOS: Bison output files extension differences depending on the DOS/Windows file system flavour used.
  • VMS Invocation: Bison command syntax on VMS.

    Copying This Manual

  • GNU Free Documentation License: License for copying this manual.

Node:Introduction, Next:Conditions, Previous:Top, Up:Top

Introduction

Bison is a general-purpose parser generator that converts a grammar description for an LALR(1) context-free grammar into a C program to parse that grammar. Once you are proficient with Bison, you may use it to develop a wide range of language parsers, from those used in simple desk calculators to complex programming languages.

Bison is upward compatible with Yacc: all properly-written Yacc grammars ought to work with Bison with no change. Anyone familiar with Yacc should be able to use Bison with little trouble. You need to be fluent in C programming in order to use Bison or to understand this manual.

We begin with tutorial chapters that explain the basic concepts of using Bison and show three explained examples, each building on the last. If you don't know Bison or Yacc, start by reading these chapters. Reference chapters follow which describe specific aspects of Bison in detail.

Bison was written primarily by Robert Corbett; Richard Stallman made it Yacc-compatible. Wilfred Hansen of Carnegie Mellon University added multi-character string literals and other features.

This edition corresponds to version 1.35 of Bison.

Node:Conditions, Next:Copying, Previous:Introduction, Up:Top

Conditions for Using Bison

As of Bison version 1.24, we have changed the distribution terms for yyparse to permit using Bison's output in nonfree programs. Formerly, Bison parsers could be used only in programs that were free software.

The other GNU programming tools, such as the GNU C compiler, have never had such a requirement. They could always be used for nonfree software. The reason Bison was different was not due to a special policy decision; it resulted from applying the usual General Public License to all of the Bison source code.

The output of the Bison utility--the Bison parser file--contains a verbatim copy of a sizable piece of Bison, which is the code for the yyparse function. (The actions from your grammar are inserted into this function at one point, but the rest of the function is not changed.) When we applied the GPL terms to the code for yyparse, the effect was to restrict the use of Bison output to free software.

We didn't change the terms because of sympathy for people who want to make software proprietary. Software should be free. But we concluded that limiting Bison's use to free software was doing little to encourage people to make other software free. So we decided to make the practical conditions for using Bison match the practical conditions for using the other GNU tools.

Node:Copying, Next:Concepts, Previous:Conditions, Up:Top

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Appendix: How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) yyyy  name of author

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

Node:Concepts, Next:Examples, Previous:Copying, Up:Top

The Concepts of Bison

This chapter introduces many of the basic concepts without which the details of Bison will not make sense. If you do not already know how to use Bison or Yacc, we suggest you start by reading this chapter carefully.

  • Language and Grammar: Languages and context-free grammars, as mathematical ideas.
  • Grammar in Bison: How we represent grammars for Bison's sake.
  • Semantic Values: Each token or syntactic grouping can have a semantic value (the value of an integer, the name of an identifier, etc.).
  • Semantic Actions: Each rule can have an action containing C code.
  • Locations Overview: Tracking Locations.
  • Bison Parser: What are Bison's input and output, how is the output used?
  • Stages: Stages in writing and running Bison grammars.
  • Grammar Layout: Overall structure of a Bison grammar file.

Node:Language and Grammar, Next:Grammar in Bison, Up:Concepts

Languages and Context-Free Grammars

In order for Bison to parse a language, it must be described by a context-free grammar. This means that you specify one or more syntactic groupings and give rules for constructing them from their parts. For example, in the C language, one kind of grouping is called an `expression'. One rule for making an expression might be, "An expression can be made of a minus sign and another expression". Another would be, "An expression can be an integer". As you can see, rules are often recursive, but there must be at least one rule which leads out of the recursion.

The most common formal system for presenting such rules for humans to read is Backus-Naur Form or "BNF", which was developed in order to specify the language Algol 60. Any grammar expressed in BNF is a context-free grammar. The input to Bison is essentially machine-readable BNF.

Not all context-free languages can be handled by Bison, only those that are LALR(1). In brief, this means that it must be possible to tell how to parse any portion of an input string with just a single token of look-ahead. Strictly speaking, that is a description of an LR(1) grammar, and LALR(1) involves additional restrictions that are hard to explain simply; but it is rare in actual practice to find an LR(1) grammar that fails to be LALR(1). See Mysterious Reduce/Reduce Conflicts, for more information on this.

In the formal grammatical rules for a language, each kind of syntactic unit or grouping is named by a symbol. Those which are built by grouping smaller constructs according to grammatical rules are called nonterminal symbols; those which can't be subdivided are called terminal symbols or token types. We call a piece of input corresponding to a single terminal symbol a token, and a piece corresponding to a single nonterminal symbol a grouping.

We can use the C language as an example of what symbols, terminal and nonterminal, mean. The tokens of C are identifiers, constants (numeric and string), and the various keywords, arithmetic operators and punctuation marks. So the terminal symbols of a grammar for C include `identifier', `number', `string', plus one symbol for each keyword, operator or punctuation mark: `if', `return', `const', `static', `int', `char', `plus-sign', `open-brace', `close-brace', `comma' and many more. (These tokens can be subdivided into characters, but that is a matter of lexicography, not grammar.)

Here is a simple C function subdivided into tokens:

int             /* keyword `int' */
square (int x)  /* identifier, open-paren, identifier, identifier, close-paren */
{               /* open-brace */
  return x * x; /* keyword `return', identifier, asterisk, identifier, semicolon */
}               /* close-brace */

The syntactic groupings of C include the expression, the statement, the declaration, and the function definition. These are represented in the grammar of C by nonterminal symbols `expression', `statement', `declaration' and `function definition'. The full grammar uses dozens of additional language constructs, each with its own nonterminal symbol, in order to express the meanings of these four. The example above is a function definition; it contains one declaration, and one statement. In the statement, each x is an expression and so is x * x.

Each nonterminal symbol must have grammatical rules showing how it is made out of simpler constructs. For example, one kind of C statement is the return statement; this would be described with a grammar rule which reads informally as follows:

A `statement' can be made of a `return' keyword, an `expression' and a `semicolon'.

There would be many other rules for `statement', one for each kind of statement in C.

One nonterminal symbol must be distinguished as the special one which defines a complete utterance in the language. It is called the start symbol. In a compiler, this means a complete input program. In the C language, the nonterminal symbol `sequence of definitions and declarations' plays this role.

For example, 1 + 2 is a valid C expression--a valid part of a C program--but it is not valid as an entire C program. In the context-free grammar of C, this follows from the fact that `expression' is not the start symbol.

The Bison parser reads a sequence of tokens as its input, and groups the tokens using the grammar rules. If the input is valid, the end result is that the entire token sequence reduces to a single grouping whose symbol is the grammar's start symbol. If we use a grammar for C, the entire input must be a `sequence of definitions and declarations'. If not, the parser reports a syntax error.

Node:Grammar in Bison, Next:Semantic Values, Previous:Language and Grammar, Up:Concepts

From Formal Rules to Bison Input

A formal grammar is a mathematical construct. To define the language for Bison, you must write a file expressing the grammar in Bison syntax: a Bison grammar file. See Bison Grammar Files.

A nonterminal symbol in the formal grammar is represented in Bison input as an identifier, like an identifier in C. By convention, it should be in lower case, such as expr, stmt or declaration.

The Bison representation for a terminal symbol is also called a token type. Token types as well can be represented as C-like identifiers. By convention, these identifiers should be upper case to distinguish them from nonterminals: for example, INTEGER, IDENTIFIER, IF or RETURN. A terminal symbol that stands for a particular keyword in the language should be named after that keyword converted to upper case. The terminal symbol error is reserved for error recovery. See Symbols.

A terminal symbol can also be represented as a character literal, just like a C character constant. You should do this whenever a token is just a single character (parenthesis, plus-sign, etc.): use that same character in a literal as the terminal symbol for that token.

A third way to represent a terminal symbol is with a C string constant containing several characters. See Symbols, for more information.

The grammar rules also have an expression in Bison syntax. For example, here is the Bison rule for a C return statement. The semicolon in quotes is a literal character token, representing part of the C syntax for the statement; the naked semicolon, and the colon, are Bison punctuation used in every rule.

stmt:   RETURN expr ';'
        ;

See Syntax of Grammar Rules.

Node:Semantic Values, Next:Semantic Actions, Previous:Grammar in Bison, Up:Concepts

Semantic Values

A formal grammar selects tokens only by their classifications: for example, if a rule mentions the terminal symbol `integer constant', it means that any integer constant is grammatically valid in that position. The precise value of the constant is irrelevant to how to parse the input: if x+4 is grammatical then x+1 or x+3989 is equally grammatical.

But the precise value is very important for what the input means once it is parsed. A compiler is useless if it fails to distinguish between 4, 1 and 3989 as constants in the program! Therefore, each token in a Bison grammar has both a token type and a semantic value. See Defining Language Semantics, for details.

The token type is a terminal symbol defined in the grammar, such as INTEGER, IDENTIFIER or ','. It tells everything you need to know to decide where the token may validly appear and how to group it with other tokens. The grammar rules know nothing about tokens except their types.

The semantic value has all the rest of the information about the meaning of the token, such as the value of an integer, or the name of an identifier. (A token such as ',' which is just punctuation doesn't need to have any semantic value.)

For example, an input token might be classified as token type INTEGER and have the semantic value 4. Another input token might have the same token type INTEGER but value 3989. When a grammar rule says that INTEGER is allowed, either of these tokens is acceptable because each is an INTEGER. When the parser accepts the token, it keeps track of the token's semantic value.

Each grouping can also have a semantic value as well as its nonterminal symbol. For example, in a calculator, an expression typically has a semantic value that is a number. In a compiler for a programming language, an expression typically has a semantic value that is a tree structure describing the meaning of the expression.

Node:Semantic Actions, Next:Locations Overview, Previous:Semantic Values, Up:Concepts

Semantic Actions

In order to be useful, a program must do more than parse input; it must also produce some output based on the input. In a Bison grammar, a grammar rule can have an action made up of C statements. Each time the parser recognizes a match for that rule, the action is executed. See Actions.

Most of the time, the purpose of an action is to compute the semantic value of the whole construct from the semantic values of its parts. For example, suppose we have a rule which says an expression can be the sum of two expressions. When the parser recognizes such a sum, each of the subexpressions has a semantic value which describes how it was built up. The action for this rule should create a similar sort of value for the newly recognized larger expression.

For example, here is a rule that says an expression can be the sum of two subexpressions:

expr: expr '+' expr   { $$ = $1 + $3; }
        ;

The action says how to produce the semantic value of the sum expression from the values of the two subexpressions.

Node:Locations Overview, Next:Bison Parser, Previous:Semantic Actions, Up:Concepts

Locations

Many applications, like interpreters or compilers, have to produce verbose and useful error messages. To achieve this, one must be able to keep track of the textual position, or location, of each syntactic construct. Bison provides a mechanism for handling these locations.

Each token has a semantic value. In a similar fashion, each token has an associated location, but the type of locations is the same for all tokens and groupings. Moreover, the output parser is equipped with a default data structure for storing locations (see Locations, for more details).

Like semantic values, locations can be reached in actions using a dedicated set of constructs. In the example above, the location of the whole grouping is @$, while the locations of the subexpressions are @1 and @3.

When a rule is matched, a default action is used to compute the semantic value of its left hand side (see Actions). In the same way, another default action is used for locations. However, the action for locations is general enough for most cases, meaning there is usually no need to describe for each rule how @$ should be formed. When building a new location for a given grouping, the default behavior of the output parser is to take the beginning of the first symbol, and the end of the last symbol.

Node:Bison Parser, Next:Stages, Previous:Locations Overview, Up:Concepts

Bison Output: the Parser File

When you run Bison, you give it a Bison grammar file as input. The output is a C source file that parses the language described by the grammar. This file is called a Bison parser. Keep in mind that the Bison utility and the Bison parser are two distinct programs: the Bison utility is a program whose output is the Bison parser that becomes part of your program.

The job of the Bison parser is to group tokens into groupings according to the grammar rules--for example, to build identifiers and operators into expressions. As it does this, it runs the actions for the grammar rules it uses.

The tokens come from a function called the lexical analyzer that you must supply in some fashion (such as by writing it in C). The Bison parser calls the lexical analyzer each time it wants a new token. It doesn't know what is "inside" the tokens (though their semantic values may reflect this). Typically the lexical analyzer makes the tokens by parsing characters of text, but Bison does not depend on this. See The Lexical Analyzer Function yylex.

The Bison parser file is C code which defines a function named yyparse which implements that grammar. This function does not make a complete C program: you must supply some additional functions. One is the lexical analyzer. Another is an error-reporting function which the parser calls to report an error. In addition, a complete C program must start with a function called main; you have to provide this, and arrange for it to call yyparse or the parser will never run. See Parser C-Language Interface.

Aside from the token type names and the symbols in the actions you write, all symbols defined in the Bison parser file itself begin with yy or YY. This includes interface functions such as the lexical analyzer function yylex, the error reporting function yyerror and the parser function yyparse itself. This also includes numerous identifiers used for internal purposes. Therefore, you should avoid using C identifiers starting with yy or YY in the Bison grammar file except for the ones defined in this manual.

In some cases the Bison parser file includes system headers, and in those cases your code should respect the identifiers reserved by those headers. On some non-GNU hosts, <alloca.h>, <stddef.h>, and <stdlib.h> are included as needed to declare memory allocators and related types. Other system headers may be included if you define YYDEBUG to a nonzero value (see Debugging Your Parser).

Node:Stages, Next:Grammar Layout, Previous:Bison Parser, Up:Concepts

Stages in Using Bison

The actual language-design process using Bison, from grammar specification to a working compiler or interpreter, has these parts:

  1. Formally specify the grammar in a form recognized by Bison (see Bison Grammar Files). For each grammatical rule in the language, describe the action that is to be taken when an instance of that rule is recognized. The action is described by a sequence of C statements.
  2. Write a lexical analyzer to process input and pass tokens to the parser. The lexical analyzer may be written by hand in C (see The Lexical Analyzer Function yylex). It could also be produced using Lex, but the use of Lex is not discussed in this manual.
  3. Write a controlling function that calls the Bison-produced parser.
  4. Write error-reporting routines.

To turn this source code as written into a runnable program, you must follow these steps:

  1. Run Bison on the grammar to produce the parser.
  2. Compile the code output by Bison, as well as any other source files.
  3. Link the object files to produce the finished product.

Node:Grammar Layout, Previous:Stages, Up:Concepts

The Overall Layout of a Bison Grammar

The input file for the Bison utility is a Bison grammar file. The general form of a Bison grammar file is as follows:

%{
C declarations
%}

Bison declarations

%%
Grammar rules
%%
Additional C code

The %%, %{ and %} are punctuation that appears in every Bison grammar file to separate the sections.

The C declarations may define types and variables used in the actions. You can also use preprocessor commands to define macros used there, and use #include to include header files that do any of these things.

The Bison declarations declare the names of the terminal and nonterminal symbols, and may also describe operator precedence and the data types of semantic values of various symbols.

The grammar rules define how to construct each nonterminal symbol from its parts.

The additional C code can contain any C code you want to use. Often the definition of the lexical analyzer yylex goes here, plus subroutines called by the actions in the grammar rules. In a simple program, all the rest of the program can go here.

Node:Examples, Next:Grammar File, Previous:Concepts, Up:Top

Examples

Now we show and explain three sample programs written using Bison: a reverse polish notation calculator, an algebraic (infix) notation calculator, and a multi-function calculator. All three have been tested under BSD Unix 4.3; each produces a usable, though limited, interactive desk-top calculator.

These examples are simple, but Bison grammars for real programming languages are written the same way.

  • RPN Calc: Reverse polish notation calculator; a first example with no operator precedence.
  • Infix Calc: Infix (algebraic) notation calculator. Operator precedence is introduced.
  • Simple Error Recovery: Continuing after syntax errors.
  • Location Tracking Calc: Demonstrating the use of @n and @$.
  • Multi-function Calc: Calculator with memory and trig functions. It uses multiple data-types for semantic values.
  • Exercises: Ideas for improving the multi-function calculator.

Node:RPN Calc, Next:Infix Calc, Up:Examples

Reverse Polish Notation Calculator

The first example is that of a simple double-precision reverse polish notation calculator (a calculator using postfix operators). This example provides a good starting point, since operator precedence is not an issue. The second example will illustrate how operator precedence is handled.

The source code for this calculator is named rpcalc.y. The .y extension is a convention used for Bison input files.

  • Decls: Bison and C declarations for rpcalc.
  • Rules: Grammar Rules for rpcalc, with explanation.
  • Lexer: The lexical analyzer.
  • Main: The controlling function.
  • Error: The error reporting function.
  • Gen: Running Bison on the grammar file.
  • Comp: Run the C compiler on the output code.

Node:Rpcalc Decls, Next:Rpcalc Rules, Up:RPN Calc

Declarations for rpcalc

Here are the C and Bison declarations for the reverse polish notation calculator. As in C, comments are placed between /*...*/.

/* Reverse polish notation calculator. */

%{
#define YYSTYPE double
#include <math.h>
%}

%token NUM

%% /* Grammar rules and actions follow */

The C declarations section (see The C Declarations Section) contains two preprocessor directives.

The #define directive defines the macro YYSTYPE, thus specifying the C data type for semantic values of both tokens and groupings (see Data Types of Semantic Values). The Bison parser will use whatever type YYSTYPE is defined as; if you don't define it, int is the default. Because we specify double, each token and each expression has an associated value, which is a floating point number.

The #include directive is used to declare the exponentiation function pow.

The second section, Bison declarations, provides information to Bison about the token types (see The Bison Declarations Section). Each terminal symbol that is not a single-character literal must be declared here. (Single-character literals normally don't need to be declared.) In this example, all the arithmetic operators are designated by single-character literals, so the only terminal symbol that needs to be declared is NUM, the token type for numeric constants.

Node:Rpcalc Rules, Next:Rpcalc Lexer, Previous:Rpcalc Decls, Up:RPN Calc

Grammar Rules for rpcalc

Here are the grammar rules for the reverse polish notation calculator.

input:    /* empty */
        | input line
;

line:     '\n'
        | exp '\n'  { printf ("\t%.10g\n", $1); }
;

exp:      NUM             { $$ = $1;         }
        | exp exp '+'     { $$ = $1 + $2;    }
        | exp exp '-'     { $$ = $1 - $2;    }
        | exp exp '*'     { $$ = $1 * $2;    }
        | exp exp '/'     { $$ = $1 / $2;    }
      /* Exponentiation */
        | exp exp '^'     { $$ = pow ($1, $2); }
      /* Unary minus    */
        | exp 'n'         { $$ = -$1;        }
;
%%

The groupings of the rpcalc "language" defined here are the expression (given the name exp), the line of input (line), and the complete input transcript (input). Each of these nonterminal symbols has several alternate rules, joined by the | punctuator which is read as "or". The following sections explain what these rules mean.

The semantics of the language is determined by the actions taken when a grouping is recognized. The actions are the C code that appears inside braces. See Actions.

You must specify these actions in C, but Bison provides the means for passing semantic values between the rules. In each action, the pseudo-variable $$ stands for the semantic value for the grouping that the rule is going to construct. Assigning a value to $$ is the main job of most actions. The semantic values of the components of the rule are referred to as $1, $2, and so on.

  • Rpcalc Input:
  • Rpcalc Line:
  • Rpcalc Expr:

Node:Rpcalc Input, Next:Rpcalc Line, Up:Rpcalc Rules
Explanation of input

Consider the definition of input:

input:    /* empty */
        | input line
;

This definition reads as follows: "A complete input is either an empty string, or a complete input followed by an input line". Notice that "complete input" is defined in terms of itself. This definition is said to be left recursive since input appears always as the leftmost symbol in the sequence. See Recursive Rules.

The first alternative is empty because there are no symbols between the colon and the first |; this means that input can match an empty string of input (no tokens). We write the rules this way because it is legitimate to type Ctrl-d right after you start the calculator. It's conventional to put an empty alternative first and write the comment /* empty */ in it.

The second alternate rule (input line) handles all nontrivial input. It means, "After reading any number of lines, read one more line if possible." The left recursion makes this rule into a loop. Since the first alternative matches empty input, the loop can be executed zero or more times.

The parser function yyparse continues to process input until a grammatical error is seen or the lexical analyzer says there are no more input tokens; we will arrange for the latter to happen at end of file.

Node:Rpcalc Line, Next:Rpcalc Expr, Previous:Rpcalc Input, Up:Rpcalc Rules
Explanation of line

Now consider the definition of line:

line:     '\n'
        | exp '\n'  { printf ("\t%.10g\n", $1); }
;

The first alternative is a token which is a newline character; this means that rpcalc accepts a blank line (and ignores it, since there is no action). The second alternative is an expression followed by a newline. This is the alternative that makes rpcalc useful. The semantic value of the exp grouping is the value of $1 because the exp in question is the first symbol in the alternative. The action prints this value, which is the result of the computation the user asked for.

This action is unusual because it does not assign a value to $$. As a consequence, the semantic value associated with the line is uninitialized (its value will be unpredictable). This would be a bug if that value were ever used, but we don't use it: once rpcalc has printed the value of the user's input line, that value is no longer needed.

Node:Rpcalc Expr, Previous:Rpcalc Line, Up:Rpcalc Rules
Explanation of expr

The exp grouping has several rules, one for each kind of expression. The first rule handles the simplest expressions: those that are just numbers. The second handles an addition-expression, which looks like two expressions followed by a plus-sign. The third handles subtraction, and so on.

exp:      NUM
        | exp exp '+'     { $$ = $1 + $2;    }
        | exp exp '-'     { $$ = $1 - $2;    }
        ...
        ;

We have used | to join all the rules for exp, but we could equally well have written them separately:

exp:      NUM ;
exp:      exp exp '+'     { $$ = $1 + $2;    } ;
exp:      exp exp '-'     { $$ = $1 - $2;    } ;
        ...

Most of the rules have actions that compute the value of the expression in terms of the value of its parts. For example, in the rule for addition, $1 refers to the first component exp and $2 refers to the second one. The third component, '+', has no meaningful associated semantic value, but if it had one you could refer to it as $3. When yyparse recognizes a sum expression using this rule, the sum of the two subexpressions' values is produced as the value of the entire expression. See Actions.

You don't have to give an action for every rule. When a rule has no action, Bison by default copies the value of $1 into $$. This is what happens in the first rule (the one that uses NUM).

The formatting shown here is the recommended convention, but Bison does not require it. You can add or change whitespace as much as you wish. For example, this:

exp   : NUM | exp exp '+' {$$ = $1 + $2; } | ...

means the same thing as this:

exp:      NUM
        | exp exp '+'    { $$ = $1 + $2; }
        | ...

The latter, however, is much more readable.

Node:Rpcalc Lexer, Next:Rpcalc Main, Previous:Rpcalc Rules, Up:RPN Calc

The rpcalc Lexical Analyzer

The lexical analyzer's job is low-level parsing: converting characters or sequences of characters into tokens. The Bison parser gets its tokens by calling the lexical analyzer. See The Lexical Analyzer Function yylex.

Only a simple lexical analyzer is needed for the RPN calculator. This lexical analyzer skips blanks and tabs, then reads in numbers as double and returns them as NUM tokens. Any other character that isn't part of a number is a separate token. Note that the token-code for such a single-character token is the character itself.

The return value of the lexical analyzer function is a numeric code which represents a token type. The same text used in Bison rules to stand for this token type is also a C expression for the numeric code for the type. This works in two ways. If the token type is a character literal, then its numeric code is the ASCII code for that character; you can use the same character literal in the lexical analyzer to express the number. If the token type is an identifier, that identifier is defined by Bison as a C macro whose definition is the appropriate number. In this example, therefore, NUM becomes a macro for yylex to use.

The semantic value of the token (if it has one) is stored into the global variable yylval, which is where the Bison parser will look for it. (The C data type of yylval is YYSTYPE, which was defined at the beginning of the grammar; see Declarations for rpcalc.)

A token type code of zero is returned if the end-of-file is encountered. (Bison recognizes any nonpositive value as indicating the end of the input.)

Here is the code for the lexical analyzer:

/* Lexical analyzer returns a double floating point
   number on the stack and the token NUM, or the ASCII
   character read if not a number.  Skips all blanks
   and tabs, returns 0 for EOF. */

#include <ctype.h>

int
yylex (void)
{
  int c;

  /* skip white space  */
  while ((c = getchar ()) == ' ' || c == '\t')
    ;
  /* process numbers   */
  if (c == '.' || isdigit (c))
    {
      ungetc (c, stdin);
      scanf ("%lf", &yylval);
      return NUM;
    }
  /* return end-of-file  */
  if (c == EOF)
    return 0;
  /* return single chars */
  return c;
}

Node:Rpcalc Main, Next:Rpcalc Error, Previous:Rpcalc Lexer, Up:RPN Calc

The Controlling Function

In keeping with the spirit of this example, the controlling function is kept to the bare minimum. The only requirement is that it call yyparse to start the process of parsing.

int
main (void)
{
  return yyparse ();
}

Node:Rpcalc Error, Next:Rpcalc Gen, Previous:Rpcalc Main, Up:RPN Calc

The Error Reporting Routine

When yyparse detects a syntax error, it calls the error reporting function yyerror to print an error message (usually but not always "parse error"). It is up to the programmer to supply yyerror (see Parser C-Language Interface), so here is the definition we will use:

#include <stdio.h>

void
yyerror (const char *s)  /* Called by yyparse on error */
{
  printf ("%s\n", s);
}

After yyerror returns, the Bison parser may recover from the error and continue parsing if the grammar contains a suitable error rule (see Error Recovery). Otherwise, yyparse returns nonzero. We have not written any error rules in this example, so any invalid input will cause the calculator program to exit. This is not clean behavior for a real calculator, but it is adequate for the first example.

Node:Rpcalc Gen, Next:Rpcalc Compile, Previous:Rpcalc Error, Up:RPN Calc

Running Bison to Make the Parser

Before running Bison to produce a parser, we need to decide how to arrange all the source code in one or more source files. For such a simple example, the easiest thing is to put everything in one file. The definitions of yylex, yyerror and main go at the end, in the "additional C code" section of the file (see The Overall Layout of a Bison Grammar).

For a large project, you would probably have several source files, and use make to arrange to recompile them.

With all the source in a single file, you use the following command to convert it into a parser file:

bison file_name.y

In this example the file was called rpcalc.y (for "Reverse Polish CALCulator"). Bison produces a file named file_name.tab.c, removing the .y from the original file name. The file output by Bison contains the source code for yyparse. The additional functions in the input file (yylex, yyerror and main) are copied verbatim to the output.

Node:Rpcalc Compile, Previous:Rpcalc Gen, Up:RPN Calc

Compiling the Parser File

Here is how to compile and run the parser file:

# List files in current directory.
$ ls
rpcalc.tab.c  rpcalc.y

# Compile the Bison parser.
# -lm tells compiler to search math library for pow.
$ cc rpcalc.tab.c -lm -o rpcalc

# List files again.
$ ls
rpcalc  rpcalc.tab.c  rpcalc.y

The file rpcalc now contains the executable code. Here is an example session using rpcalc.

$ rpcalc
4 9 +
13
3 7 + 3 4 5 *+-
-13
3 7 + 3 4 5 * + - n              Note the unary minus, n
13
5 6 / 4 n +
-3.166666667
3 4 ^                            Exponentiation
81
^D                               End-of-file indicator
$

Node:Infix Calc, Next:Simple Error Recovery, Previous:RPN Calc, Up:Examples

Infix Notation Calculator: calc

We now modify rpcalc to handle infix operators instead of postfix. Infix notation involves the concept of operator precedence and the need for parentheses nested to arbitrary depth. Here is the Bison code for calc.y, an infix desk-top calculator.

/* Infix notation calculator--calc */

%{
#define YYSTYPE double
#include <math.h>
%}

/* BISON Declarations */
%token NUM
%left '-' '+'
%left '*' '/'
%left NEG     /* negation--unary minus */
%right '^'    /* exponentiation        */

/* Grammar follows */
%%
input:    /* empty string */
        | input line
;

line:     '\n'
        | exp '\n'  { printf ("\t%.10g\n", $1); }
;

exp:      NUM                { $$ = $1;         }
        | exp '+' exp        { $$ = $1 + $3;    }
        | exp '-' exp        { $$ = $1 - $3;    }
        | exp '*' exp        { $$ = $1 * $3;    }
        | exp '/' exp        { $$ = $1 / $3;    }
        | '-' exp  %prec NEG { $$ = -$2;        }
        | exp '^' exp        { $$ = pow ($1, $3); }
        | '(' exp ')'        { $$ = $2;         }
;
%%

The functions yylex, yyerror and main can be the same as before.

There are two important new features shown in this code.

In the second section (Bison declarations), %left declares token types and says they are left-associative operators. The declarations %left and %right (right associativity) take the place of %token which is used to declare a token type name without associativity. (These tokens are single-character literals, which ordinarily don't need to be declared. We declare them here to specify the associativity.)

Operator precedence is determined by the line ordering of the declarations; the higher the line number of the declaration (lower on the page or screen), the higher the precedence. Hence, exponentiation has the highest precedence, unary minus (NEG) is next, followed by * and /, and so on. See Operator Precedence.

The other important new feature is the %prec in the grammar section for the unary minus operator. The %prec simply instructs Bison that the rule | '-' exp has the same precedence as NEG--in this case the next-to-highest. See Context-Dependent Precedence.

Here is a sample run of calc.y:

$ calc
4 + 4.5 - (34/(8*3+-3))
6.880952381
-56 + 2
-54
3 ^ 2
9

Node:Simple Error Recovery, Next:Location Tracking Calc, Previous:Infix Calc, Up:Examples

Simple Error Recovery

Up to this point, this manual has not addressed the issue of error recovery--how to continue parsing after the parser detects a syntax error. All we have handled is error reporting with yyerror. Recall that by default yyparse returns after calling yyerror. This means that an erroneous input line causes the calculator program to exit. Now we show how to rectify this deficiency.

The Bison language itself includes the reserved word error, which may be included in the grammar rules. In the example below it has been added to one of the alternatives for line:

line:     '\n'
        | exp '\n'   { printf ("\t%.10g\n", $1); }
        | error '\n' { yyerrok;                  }
;

This addition to the grammar allows for simple error recovery in the event of a parse error. If an expression that cannot be evaluated is read, the error will be recognized by the third rule for line, and parsing will continue. (The yyerror function is still called upon to print its message as well.) The action executes the statement yyerrok, a macro defined automatically by Bison; its meaning is that error recovery is complete (see Error Recovery). Note the difference between yyerrok and yyerror; neither one is a misprint.

This form of error recovery deals with syntax errors. There are other kinds of errors; for example, division by zero, which raises an exception signal that is normally fatal. A real calculator program must handle this signal and use longjmp to return to main and resume parsing input lines; it would also have to discard the rest of the current line of input. We won't discuss this issue further because it is not specific to Bison programs.

Node:Location Tracking Calc, Next:Multi-function Calc, Previous:Simple Error Recovery, Up:Examples

Location Tracking Calculator: ltcalc

This example extends the infix notation calculator with location tracking. This feature will be used to improve the error messages. For the sake of clarity, this example is a simple integer calculator, since most of the work needed to use locations will be done in the lexical analyser.

  • Decls: Bison and C declarations for ltcalc.
  • Rules: Grammar rules for ltcalc, with explanations.
  • Lexer: The lexical analyzer.

Node:Ltcalc Decls, Next:Ltcalc Rules, Up:Location Tracking Calc

Declarations for ltcalc

The C and Bison declarations for the location tracking calculator are the same as the declarations for the infix notation calculator.

/* Location tracking calculator.  */

%{
#define YYSTYPE int
#include <math.h>
%}

/* Bison declarations.  */
%token NUM

%left '-' '+'
%left '*' '/'
%left NEG
%right '^'

%% /* Grammar follows */

Note there are no declarations specific to locations. Defining a data type for storing locations is not needed: we will use the type provided by default (see Data Types of Locations), which is a four member structure with the following integer fields: first_line, first_column, last_line and last_column.

Node:Ltcalc Rules, Next:Ltcalc Lexer, Previous:Ltcalc Decls, Up:Location Tracking Calc

Grammar Rules for ltcalc

Whether handling locations or not has no effect on the syntax of your language. Therefore, grammar rules for this example will be very close to those of the previous example: we will only modify them to benefit from the new information.

Here, we will use locations to report divisions by zero, and locate the wrong expressions or subexpressions.

input   : /* empty */
        | input line
;

line    : '\n'
        | exp '\n' { printf ("%d\n", $1); }
;

exp     : NUM           { $$ = $1; }
        | exp '+' exp   { $$ = $1 + $3; }
        | exp '-' exp   { $$ = $1 - $3; }
        | exp '*' exp   { $$ = $1 * $3; }
        | exp '/' exp
            {
              if ($3)
                $$ = $1 / $3;
              else
                {
                  $$ = 1;
                  fprintf (stderr, "%d.%d-%d.%d: division by zero",
                           @3.first_line, @3.first_column,
                           @3.last_line, @3.last_column);
                }
            }
        | '-' exp %preg NEG     { $$ = -$2; }
        | exp '^' exp           { $$ = pow ($1, $3); }
        | '(' exp ')'           { $$ = $2; }

This code shows how to reach locations inside of semantic actions, by using the pseudo-variables @n for rule components, and the pseudo-variable @$ for groupings.

We don't need to assign a value to @$: the output parser does it automatically. By default, before executing the C code of each action, @$ is set to range from the beginning of @1 to the end of @n, for a rule with n components. This behavior can be redefined (see Default Action for Locations), and for very specific rules, @$ can be computed by hand.

Node:Ltcalc Lexer, Previous:Ltcalc Rules, Up:Location Tracking Calc

The ltcalc Lexical Analyzer.

Until now, we relied on Bison's defaults to enable location tracking. The next step is to rewrite the lexical analyser, and make it able to feed the parser with the token locations, as it already does for semantic values.

To this end, we must take into account every single character of the input text, to avoid the computed locations of being fuzzy or wrong:

int
yylex (void)
{
  int c;

  /* skip white space */
  while ((c = getchar ()) == ' ' || c == '\t')
    ++yylloc.last_column;

  /* step */
  yylloc.first_line = yylloc.last_line;
  yylloc.first_column = yylloc.last_column;

  /* process numbers */
  if (isdigit (c))
    {
      yylval = c - '0';
      ++yylloc.last_column;
      while (isdigit (c = getchar ()))
        {
          ++yylloc.last_column;
          yylval = yylval * 10 + c - '0';
        }
      ungetc (c, stdin);
      return NUM;
    }

  /* return end-of-file */
  if (c == EOF)
    return 0;

  /* return single chars and update location */
  if (c == '\n')
    {
      ++yylloc.last_line;
      yylloc.last_column = 0;
    }
  else
    ++yylloc.last_column;
  return c;
}

Basically, the lexical analyzer performs the same processing as before: it skips blanks and tabs, and reads numbers or single-character tokens. In addition, it updates yylloc, the global variable (of type YYLTYPE) containing the token's location.

Now, each time this function returns a token, the parser has its number as well as its semantic value, and its location in the text. The last needed change is to initialize yylloc, for example in the controlling function:

int
main (void)
{
  yylloc.first_line = yylloc.last_line = 1;
  yylloc.first_column = yylloc.last_column = 0;
  return yyparse ();
}

Remember that computing locations is not a matter of syntax. Every character must be associated to a location update, whether it is in valid input, in comments, in literal strings, and so on.

Node:Multi-function Calc, Next:Exercises, Previous:Location Tracking Calc, Up:Examples

Multi-Function Calculator: mfcalc

Now that the basics of Bison have been discussed, it is time to move on to a more advanced problem. The above calculators provided only five functions, +, -, *, / and ^. It would be nice to have a calculator that provides other mathematical functions such as sin, cos, etc.

It is easy to add new operators to the infix calculator as long as they are only single-character literals. The lexical analyzer yylex passes back all nonnumber characters as tokens, so new grammar rules suffice for adding a new operator. But we want something more flexible: built-in functions whose syntax has this form:

function_name (argument)

At the same time, we will add memory to the calculator, by allowing you to create named variables, store values in them, and use them later. Here is a sample session with the multi-function calculator:

$ mfcalc
pi = 3.141592653589
3.1415926536
sin(pi)
0.0000000000
alpha = beta1 = 2.3
2.3000000000
alpha
2.3000000000
ln(alpha)
0.8329091229
exp(ln(beta1))
2.3000000000
$

Note that multiple assignment and nested function calls are permitted.

  • Decl: Bison declarations for multi-function calculator.
  • Rules: Grammar rules for the calculator.
  • Symtab: Symbol table management subroutines.

Node:Mfcalc Decl, Next:Mfcalc Rules, Up:Multi-function Calc

Declarations for mfcalc

Here are the C and Bison declarations for the multi-function calculator.

%{
#include <math.h>  /* For math functions, cos(), sin(), etc. */
#include "calc.h"  /* Contains definition of `symrec'        */
%}
%union {
double     val;  /* For returning numbers.                   */
symrec  *tptr;   /* For returning symbol-table pointers      */
}

%token <val>  NUM        /* Simple double precision number   */
%token <tptr> VAR FNCT   /* Variable and Function            */
%type  <val>  exp

%right '='
%left '-' '+'
%left '*' '/'
%left NEG     /* Negation--unary minus */
%right '^'    /* Exponentiation        */

/* Grammar follows */

%%

The above grammar introduces only two new features of the Bison language. These features allow semantic values to have various data types (see More Than One Value Type).

The %union declaration specifies the entire list of possible types; this is instead of defining YYSTYPE. The allowable types are now double-floats (for exp and NUM) and pointers to entries in the symbol table. See The Collection of Value Types.

Since values can now have various types, it is necessary to associate a type with each grammar symbol whose semantic value is used. These symbols are NUM, VAR, FNCT, and exp. Their declarations are augmented with information about their data type (placed between angle brackets).

The Bison construct %type is used for declaring nonterminal symbols, just as %token is used for declaring token types. We have not used %type before because nonterminal symbols are normally declared implicitly by the rules that define them. But exp must be declared explicitly so we can specify its value type. See Nonterminal Symbols.

Node:Mfcalc Rules, Next:Mfcalc Symtab, Previous:Mfcalc Decl, Up:Multi-function Calc

Grammar Rules for mfcalc

Here are the grammar rules for the multi-function calculator. Most of them are copied directly from calc; three rules, those which mention VAR or FNCT, are new.

input:   /* empty */
        | input line
;

line:
          '\n'
        | exp '\n'   { printf ("\t%.10g\n", $1); }
        | error '\n' { yyerrok;                  }
;

exp:      NUM                { $$ = $1;                         }
        | VAR                { $$ = $1->value.var;              }
        | VAR '=' exp        { $$ = $3; $1->value.var = $3;     }
        | FNCT '(' exp ')'   { $$ = (*($1->value.fnctptr))($3); }
        | exp '+' exp        { $$ = $1 + $3;                    }
        | exp '-' exp        { $$ = $1 - $3;                    }
        | exp '*' exp        { $$ = $1 * $3;                    }
        | exp '/' exp        { $$ = $1 / $3;                    }
        | '-' exp  %prec NEG { $$ = -$2;                        }
        | exp '^' exp        { $$ = pow ($1, $3);               }
        | '(' exp ')'        { $$ = $2;                         }
;
/* End of grammar */
%%

Node:Mfcalc Symtab, Previous:Mfcalc Rules, Up:Multi-function Calc

The mfcalc Symbol Table

The multi-function calculator requires a symbol table to keep track of the names and meanings of variables and functions. This doesn't affect the grammar rules (except for the actions) or the Bison declarations, but it requires some additional C functions for support.

The symbol table itself consists of a linked list of records. Its definition, which is kept in the header calc.h, is as follows. It provides for either functions or variables to be placed in the table.

/* Fonctions type.                                   */
typedef double (*func_t) (double);

/* Data type for links in the chain of symbols.      */
struct symrec
{
  char *name;  /* name of symbol                     */
  int type;    /* type of symbol: either VAR or FNCT */
  union
  {
    double var;                  /* value of a VAR   */
    func_t fnctptr;              /* value of a FNCT  */
  } value;
  struct symrec *next;    /* link field              */
};

typedef struct symrec symrec;

/* The symbol table: a chain of `struct symrec'.     */
extern symrec *sym_table;

symrec *putsym (const char *, func_t);
symrec *getsym (const char *);

The new version of main includes a call to init_table, a function that initializes the symbol table. Here it is, and init_table as well:

#include <stdio.h>

int
main (void)
{
  init_table ();
  return yyparse ();
}

void
yyerror (const char *s)  /* Called by yyparse on error */
{
  printf ("%s\n", s);
}

struct init
{
  char *fname;
  double (*fnct)(double);
};

struct init arith_fncts[] =
{
  "sin",  sin,
  "cos",  cos,
  "atan", atan,
  "ln",   log,
  "exp",  exp,
  "sqrt", sqrt,
  0, 0
};

/* The symbol table: a chain of `struct symrec'.  */
symrec *sym_table = (symrec *) 0;

/* Put arithmetic functions in table. */
void
init_table (void)
{
  int i;
  symrec *ptr;
  for (i = 0; arith_fncts[i].fname != 0; i++)
    {
      ptr = putsym (arith_fncts[i].fname, FNCT);
      ptr->value.fnctptr = arith_fncts[i].fnct;
    }
}

By simply editing the initialization list and adding the necessary include files, you can add additional functions to the calculator.

Two important functions allow look-up and installation of symbols in the symbol table. The function putsym is passed a name and the type (VAR or FNCT) of the object to be installed. The object is linked to the front of the list, and a pointer to the object is returned. The function getsym is passed the name of the symbol to look up. If found, a pointer to that symbol is returned; otherwise zero is returned.

symrec *
putsym (char *sym_name, int sym_type)
{
  symrec *ptr;
  ptr = (symrec *) malloc (sizeof (symrec));
  ptr->name = (char *) malloc (strlen (sym_name) + 1);
  strcpy (ptr->name,sym_name);
  ptr->type = sym_type;
  ptr->value.var = 0; /* set value to 0 even if fctn.  */
  ptr->next = (struct symrec *)sym_table;
  sym_table = ptr;
  return ptr;
}

symrec *
getsym (const char *sym_name)
{
  symrec *ptr;
  for (ptr = sym_table; ptr != (symrec *) 0;
       ptr = (symrec *)ptr->next)
    if (strcmp (ptr->name,sym_name) == 0)
      return ptr;
  return 0;
}

The function yylex must now recognize variables, numeric values, and the single-character arithmetic operators. Strings of alphanumeric characters with a leading non-digit are recognized as either variables or functions depending on what the symbol table says about them.

The string is passed to getsym for look up in the symbol table. If the name appears in the table, a pointer to its location and its type (VAR or FNCT) is returned to yyparse. If it is not already in the table, then it is installed as a VAR using putsym. Again, a pointer and its type (which must be VAR) is returned to yyparse.

No change is needed in the handling of numeric values and arithmetic operators in yylex.

#include <ctype.h>

int
yylex (void)
{
  int c;

  /* Ignore whitespace, get first nonwhite character.  */
  while ((c = getchar ()) == ' ' || c == '\t');

  if (c == EOF)
    return 0;

  /* Char starts a number => parse the number.         */
  if (c == '.' || isdigit (c))
    {
      ungetc (c, stdin);
      scanf ("%lf", &yylval.val);
      return NUM;
    }

  /* Char starts an identifier => read the name.       */
  if (isalpha (c))
    {
      symrec *s;
      static char *symbuf = 0;
      static int length = 0;
      int i;

      /* Initially make the buffer long enough
         for a 40-character symbol name.  */
      if (length == 0)
        length = 40, symbuf = (char *)malloc (length + 1);

      i = 0;
      do
        {
          /* If buffer is full, make it bigger.        */
          if (i == length)
            {
              length *= 2;
              symbuf = (char *)realloc (symbuf, length + 1);
            }
          /* Add this character to the buffer.         */
          symbuf[i++] = c;
          /* Get another character.                    */
          c = getchar ();
        }
      while (c != EOF && isalnum (c));

      ungetc (c, stdin);
      symbuf[i] = '\0';

      s = getsym (symbuf);
      if (s == 0)
        s = putsym (symbuf, VAR);
      yylval.tptr = s;
      return s->type;
    }

  /* Any other character is a token by itself.        */
  return c;
}

This program is both powerful and flexible. You may easily add new functions, and it is a simple job to modify this code to install predefined variables such as pi or e as well.

Node:Exercises, Previous:Multi-function Calc, Up:Examples

Exercises

  1. Add some new functions from math.h to the initialization list.
  2. Add another array that contains constants and their values. Then modify init_table to add these constants to the symbol table. It will be easiest to give the constants type VAR.
  3. Make the program report an error if the user refers to an uninitialized variable in any way except to store a value in it.

Node:Grammar File, Next:Interface, Previous:Examples, Up:Top

Bison Grammar Files

Bison takes as input a context-free grammar specification and produces a C-language function that recognizes correct instances of the grammar.

The Bison grammar input file conventionally has a name ending in .y. See Invoking Bison.

  • Grammar Outline: Overall layout of the grammar file.
  • Symbols: Terminal and nonterminal symbols.
  • Rules: How to write grammar rules.
  • Recursion: Writing recursive rules.
  • Semantics: Semantic values and actions.
  • Locations: Locations and actions.
  • Declarations: All kinds of Bison declarations are described here.
  • Multiple Parsers: Putting more than one Bison parser in one program.

Node:Grammar Outline, Next:Symbols, Up:Grammar File

Outline of a Bison Grammar

A Bison grammar file has four main sections, shown here with the appropriate delimiters:

%{
C declarations
%}

Bison declarations

%%
Grammar rules
%%

Additional C code

Comments enclosed in /* ... */ may appear in any of the sections.

  • C Declarations: Syntax and usage of the C declarations section.
  • Bison Declarations: Syntax and usage of the Bison declarations section.
  • Grammar Rules: Syntax and usage of the grammar rules section.
  • C Code: Syntax and usage of the additional C code section.

Node:C Declarations, Next:Bison Declarations, Up:Grammar Outline

The C Declarations Section

The C declarations section contains macro definitions and declarations of functions and variables that are used in the actions in the grammar rules. These are copied to the beginning of the parser file so that they precede the definition of yyparse. You can use #include to get the declarations from a header file. If you don't need any C declarations, you may omit the %{ and %} delimiters that bracket this section.

Node:Bison Declarations, Next:Grammar Rules, Previous:C Declarations, Up:Grammar Outline

The Bison Declarations Section

The Bison declarations section contains declarations that define terminal and nonterminal symbols, specify precedence, and so on. In some simple grammars you may not need any declarations. See Bison Declarations.

Node:Grammar Rules, Next:C Code, Previous:Bison Declarations, Up:Grammar Outline

The Grammar Rules Section

The grammar rules section contains one or more Bison grammar rules, and nothing else. See Syntax of Grammar Rules.

There must always be at least one grammar rule, and the first %% (which precedes the grammar rules) may never be omitted even if it is the first thing in the file.

Node:C Code, Previous:Grammar Rules, Up:Grammar Outline

The Additional C Code Section

The additional C code section is copied verbatim to the end of the parser file, just as the C declarations section is copied to the beginning. This is the most convenient place to put anything that you want to have in the parser file but which need not come before the definition of yyparse. For example, the definitions of yylex and yyerror often go here. See Parser C-Language Interface.

If the last section is empty, you may omit the %% that separates it from the grammar rules.

The Bison parser itself contains many static variables whose names start with yy and many macros whose names start with YY. It is a good idea to avoid using any such names (except those documented in this manual) in the additional C code section of the grammar file.

Node:Symbols, Next:Rules, Previous:Grammar Outline, Up:Grammar File

Symbols, Terminal and Nonterminal

Symbols in Bison grammars represent the grammatical classifications of the language.

A terminal symbol (also known as a token type) represents a class of syntactically equivalent tokens. You use the symbol in grammar rules to mean that a token in that class is allowed. The symbol is represented in the Bison parser by a numeric code, and the yylex function returns a token type code to indicate what kind of token has been read. You don't need to know what the code value is; you can use the symbol to stand for it.

A nonterminal symbol stands for a class of syntactically equivalent groupings. The symbol name is used in writing grammar rules. By convention, it should be all lower case.

Symbol names can contain letters, digits (not at the beginning), underscores and periods. Periods make sense only in nonterminals.

There are three ways of writing terminal symbols in the grammar:

  • A named token type is written with an identifier, like an identifier in C. By convention, it should be all upper case. Each such name must be defined with a Bison declaration such as %token. See Token Type Names.
  • A character token type (or literal character token) is written in the grammar using the same syntax used in C for character constants; for example, '+' is a character token type. A character token type doesn't need to be declared unless you need to specify its semantic value data type (see Data Types of Semantic Values), associativity, or precedence (see Operator Precedence).

    By convention, a character token type is used only to represent a token that consists of that particular character. Thus, the token type '+' is used to represent the character + as a token. Nothing enforces this convention, but if you depart from it, your program will confuse other readers.

    All the usual escape sequences used in character literals in C can be used in Bison as well, but you must not use the null character as a character literal because its ASCII code, zero, is the code yylex returns for end-of-input (see Calling Convention for yylex).

  • A literal string token is written like a C string constant; for example, "<=" is a literal string token. A literal string token doesn't need to be declared unless you need to specify its semantic value data type (see Value Type), associativity, or precedence (see Precedence).

    You can associate the literal string token with a symbolic name as an alias, using the %token declaration (see Token Declarations). If you don't do that, the lexical analyzer has to retrieve the token number for the literal string token from the yytname table (see Calling Convention).

    WARNING: literal string tokens do not work in Yacc.

    By convention, a literal string token is used only to represent a token that consists of that particular string. Thus, you should use the token type "<=" to represent the string <= as a token. Bison does not enforce this convention, but if you depart from it, people who read your program will be confused.

    All the escape sequences used in string literals in C can be used in Bison as well. A literal string token must contain two or more characters; for a token containing just one character, use a character token (see above).

How you choose to write a terminal symbol has no effect on its grammatical meaning. That depends only on where it appears in rules and on when the parser function returns that symbol.

The value returned by yylex is always one of the terminal symbols (or 0 for end-of-input). Whichever way you write the token type in the grammar rules, you write it the same way in the definition of yylex. The numeric code for a character token type is simply the ASCII code for the character, so yylex can use the identical character constant to generate the requisite code. Each named token type becomes a C macro in the parser file, so yylex can use the name to stand for the code. (This is why periods don't make sense in terminal symbols.) See Calling Convention for yylex.

If yylex is defined in a separate file, you need to arrange for the token-type macro definitions to be available there. Use the -d option when you run Bison, so that it will write these macro definitions into a separate header file name.tab.h which you can include in the other source files that need it. See Invoking Bison.

The symbol error is a terminal symbol reserved for error recovery (see Error Recovery); you shouldn't use it for any other purpose. In particular, yylex should never return this value.

Node:Rules, Next:Recursion, Previous:Symbols, Up:Grammar File

Syntax of Grammar Rules

A Bison grammar rule has the following general form:

result: components...
        ;

where result is the nonterminal symbol that this rule describes, and components are various terminal and nonterminal symbols that are put together by this rule (see Symbols).

For example,

exp:      exp '+' exp
        ;

says that two groupings of type exp, with a + token in between, can be combined into a larger grouping of type exp.

Whitespace in rules is significant only to separate symbols. You can add extra whitespace as you wish.

Scattered among the components can be actions that determine the semantics of the rule. An action looks like this:

{C statements}

Usually there is only one action and it follows the components. See Actions.

Multiple rules for the same result can be written separately or can be joined with the vertical-bar character | as follows:

They are still considered distinct rules even when joined in this way.

If components in a rule is empty, it means that result can match the empty string. For example, here is how to define a comma-separated sequence of zero or more exp groupings:

expseq:   /* empty */
        | expseq1
        ;

expseq1:  exp
        | expseq1 ',' exp
        ;

It is customary to write a comment /* empty */ in each rule with no components.

Node:Recursion, Next:Semantics, Previous:Rules, Up:Grammar File

Recursive Rules

A rule is called recursive when its result nonterminal appears also on its right hand side. Nearly all Bison grammars need to use recursion, because that is the only way to define a sequence of any number of a particular thing. Consider this recursive definition of a comma-separated sequence of one or more expressions:

expseq1:  exp
        | expseq1 ',' exp
        ;

Since the recursive use of expseq1 is the leftmost symbol in the right hand side, we call this left recursion. By contrast, here the same construct is defined using right recursion:

expseq1:  exp
        | exp ',' expseq1
        ;

Any kind of sequence can be defined using either left recursion or right recursion, but you should always use left recursion, because it can parse a sequence of any number of elements with bounded stack space. Right recursion uses up space on the Bison stack in proportion to the number of elements in the sequence, because all the elements must be shifted onto the stack before the rule can be applied even once. See The Bison Parser Algorithm, for further explanation of this.

Indirect or mutual recursion occurs when the result of the rule does not appear directly on its right hand side, but does appear in rules for other nonterminals which do appear on its right hand side.

For example:

expr:     primary
        | primary '+' primary
        ;

primary:  constant
        | '(' expr ')'
        ;

defines two mutually-recursive nonterminals, since each refers to the other.

Node:Semantics, Next:Locations, Previous:Recursion, Up:Grammar File

Defining Language Semantics

The grammar rules for a language determine only the syntax. The semantics are determined by the semantic values associated with various tokens and groupings, and by the actions taken when various groupings are recognized.

For example, the calculator calculates properly because the value associated with each expression is the proper number; it adds properly because the action for the grouping x + y is to add the numbers associated with x and y.

  • Value Type: Specifying one data type for all semantic values.
  • Multiple Types: Specifying several alternative data types.
  • Actions: An action is the semantic definition of a grammar rule.
  • Action Types: Specifying data types for actions to operate on.
  • Mid-Rule Actions: Most actions go at the end of a rule. This says when, why and how to use the exceptional action in the middle of a rule.

Node:Value Type, Next:Multiple Types, Up:Semantics

Data Types of Semantic Values

In a simple program it may be sufficient to use the same data type for the semantic values of all language constructs. This was true in the RPN and infix calculator examples (see Reverse Polish Notation Calculator).

Bison's default is to use type int for all semantic values. To specify some other type, define YYSTYPE as a macro, like this:

#define YYSTYPE double

This macro definition must go in the C declarations section of the grammar file (see Outline of a Bison Grammar).

Node:Multiple Types, Next:Actions, Previous:Value Type, Up:Semantics

More Than One Value Type

In most programs, you will need different data types for different kinds of tokens and groupings. For example, a numeric constant may need type int or long, while a string constant needs type char *, and an identifier might need a pointer to an entry in the symbol table.

To use more than one data type for semantic values in one parser, Bison requires you to do two things:

  • Specify the entire collection of possible data types, with the %union Bison declaration (see The Collection of Value Types).
  • Choose one of those types for each symbol (terminal or nonterminal) for which semantic values are used. This is done for tokens with the %token Bison declaration (see Token Type Names) and for groupings with the %type Bison declaration (see Nonterminal Symbols).

Node:Actions, Next:Action Types, Previous:Multiple Types, Up:Semantics

Actions

An action accompanies a syntactic rule and contains C code to be executed each time an instance of that rule is recognized. The task of most actions is to compute a semantic value for the grouping built by the rule from the semantic values associated with tokens or smaller groupings.

An action consists of C statements surrounded by braces, much like a compound statement in C. It can be placed at any position in the rule; it is executed at that position. Most rules have just one action at the end of the rule, following all the components. Actions in the middle of a rule are tricky and used only for special purposes (see Actions in Mid-Rule).

The C code in an action can refer to the semantic values of the components matched by the rule with the construct $n, which stands for the value of the nth component. The semantic value for the grouping being constructed is $$. (Bison translates both of these constructs into array element references when it copies the actions into the parser file.)

Here is a typical example:

exp:    ...
        | exp '+' exp
            { $$ = $1 + $3; }

This rule constructs an exp from two smaller exp groupings connected by a plus-sign token. In the action, $1 and $3 refer to the semantic values of the two component exp groupings, which are the first and third symbols on the right hand side of the rule. The sum is stored into $$ so that it becomes the semantic value of the addition-expression just recognized by the rule. If there were a useful semantic value associated with the + token, it could be referred to as $2.

If you don't specify an action for a rule, Bison supplies a default: $$ = $1. Thus, the value of the first symbol in the rule becomes the value of the whole rule. Of course, the default rule is valid only if the two data types match. There is no meaningful default action for an empty rule; every empty rule must have an explicit action unless the rule's value does not matter.

$n with n zero or negative is allowed for reference to tokens and groupings on the stack before those that match the current rule. This is a very risky practice, and to use it reliably you must be certain of the context in which the rule is applied. Here is a case in which you can use this reliably:

foo:      expr bar '+' expr  { ... }
        | expr bar '-' expr  { ... }
        ;

bar:      /* empty */
        { previous_expr = $0; }
        ;

As long as bar is used only in the fashion shown here, $0 always refers to the expr which precedes bar in the definition of foo.

Node:Action Types, Next:Mid-Rule Actions, Previous:Actions, Up:Semantics

Data Types of Values in Actions

If you have chosen a single data type for semantic values, the $$ and $n constructs always have that data type.

If you have used %union to specify a variety of data types, then you must declare a choice among these types for each terminal or nonterminal symbol that can have a semantic value. Then each time you use $$ or $n, its data type is determined by which symbol it refers to in the rule. In this example,

exp:    ...
        | exp '+' exp
            { $$ = $1 + $3; }

$1 and $3 refer to instances of exp, so they all have the data type declared for the nonterminal symbol exp. If $2 were used, it would have the data type declared for the terminal symbol '+', whatever that might be.

Alternatively, you can specify the data type when you refer to the value, by inserting <type> after the $ at the beginning of the reference. For example, if you have defined types as shown here:

%union {
  int itype;
  double dtype;
}

then you can write $<itype>1 to refer to the first subunit of the rule as an integer, or $<dtype>1 to refer to it as a double.

Node:Mid-Rule Actions, Previous:Action Types, Up:Semantics

Actions in Mid-Rule

Occasionally it is useful to put an action in the middle of a rule. These actions are written just like usual end-of-rule actions, but they are executed before the parser even recognizes the following components.

A mid-rule action may refer to the components preceding it using $n, but it may not refer to subsequent components because it is run before they are parsed.

The mid-rule action itself counts as one of the components of the rule. This makes a difference when there is another action later in the same rule (and usually there is another at the end): you have to count the actions along with the symbols when working out which number n to use in $n.

The mid-rule action can also have a semantic value. The action can set its value with an assignment to $$, and actions later in the rule can refer to the value using $n. Since there is no symbol to name the action, there is no way to declare a data type for the value in advance, so you must use the $<...>n construct to specify a data type each time you refer to this value.

There is no way to set the value of the entire rule with a mid-rule action, because assignments to $$ do not have that effect. The only way to set the value for the entire rule is with an ordinary action at the end of the rule.

Here is an example from a hypothetical compiler, handling a let statement that looks like let (variable) statement and serves to create a variable named variable temporarily for the duration of statement. To parse this construct, we must put variable into the symbol table while statement is parsed, then remove it afterward. Here is how it is done:

stmt:   LET '(' var ')'
                { $<context>$ = push_context ();
                  declare_variable ($3); }
        stmt    { $$ = $6;
                  pop_context ($<context>5); }

As soon as let (variable) has been recognized, the first action is run. It saves a copy of the current semantic context (the list of accessible variables) as its semantic value, using alternative context in the data-type union. Then it calls declare_variable to add the new variable to that list. Once the first action is finished, the embedded statement stmt can be parsed. Note that the mid-rule action is component number 5, so the stmt is component number 6.

After the embedded statement is parsed, its semantic value becomes the value of the entire let-statement. Then the semantic value from the earlier action is used to restore the prior list of variables. This removes the temporary let-variable from the list so that it won't appear to exist while the rest of the program is parsed.

Taking action before a rule is completely recognized often leads to conflicts since the parser must commit to a parse in order to execute the action. For example, the following two rules, without mid-rule actions, can coexist in a working parser because the parser can shift the open-brace token and look at what follows before deciding whether there is a declaration or not:

compound: '{' declarations statements '}'
        | '{' statements '}'
        ;

But when we add a mid-rule action as follows, the rules become nonfunctional:

compound: { prepare_for_local_variables (); }
          '{' declarations statements '}'
        | '{' statements '}'
        ;

Now the parser is forced to decide whether to run the mid-rule action when it has read no farther than the open-brace. In other words, it must commit to using one rule or the other, without sufficient information to do it correctly. (The open-brace token is what is called the look-ahead token at this time, since the parser is still deciding what to do about it. See Look-Ahead Tokens.)

You might think that you could correct the problem by putting identical actions into the two rules, like this:

compound: { prepare_for_local_variables (); }
          '{' declarations statements '}'
        | { prepare_for_local_variables (); }
          '{' statements '}'
        ;

But this does not help, because Bison does not realize that the two actions are identical. (Bison never tries to understand the C code in an action.)

If the grammar is such that a declaration can be distinguished from a statement by the first token (which is true in C), then one solution which does work is to put the action after the open-brace, like this:

compound: '{' { prepare_for_local_variables (); }
          declarations statements '}'
        | '{' statements '}'
        ;

Now the first token of the following declaration or statement, which would in any case tell Bison which rule to use, can still do so.

Another solution is to bury the action inside a nonterminal symbol which serves as a subroutine:

subroutine: /* empty */
          { prepare_for_local_variables (); }
        ;

compound: subroutine
          '{' declarations statements '}'
        | subroutine
          '{' statements '}'
        ;

Now Bison can execute the action in the rule for subroutine without deciding which rule for compound it will eventually use. Note that the action is now at the end of its rule. Any mid-rule action can be converted to an end-of-rule action in this way, and this is what Bison actually does to implement mid-rule actions.

Node:Locations, Next:Declarations, Previous:Semantics, Up:Grammar File

Tracking Locations

Though grammar rules and semantic actions are enough to write a fully functional parser, it can be useful to process some additionnal informations, especially symbol locations.

The way locations are handled is defined by providing a data type, and actions to take when rules are matched.

  • Location Type: Specifying a data type for locations.
  • Actions and Locations: Using locations in actions.
  • Location Default Action: Defining a general way to compute locations.

Node:Location Type, Next:Actions and Locations, Up:Locations

Data Type of Locations

Defining a data type for locations is much simpler than for semantic values, since all tokens and groupings always use the same type.

The type of locations is specified by defining a macro called YYLTYPE. When YYLTYPE is not defined, Bison uses a default structure type with four members:

struct
{
  int first_line;
  int first_column;
  int last_line;
  int last_column;
}

Node:Actions and Locations, Next:Location Default Action, Previous:Location Type, Up:Locations

Actions and Locations

Actions are not only useful for defining language semantics, but also for describing the behavior of the output parser with locations.

The most obvious way for building locations of syntactic groupings is very similar to the way semantic values are computed. In a given rule, several constructs can be used to access the locations of the elements being matched. The location of the nth component of the right hand side is @n, while the location of the left hand side grouping is @$.

Here is a basic example using the default data type for locations:

exp:    ...
        | exp '/' exp
            {
              @$.first_column = @1.first_column;
              @$.first_line = @1.first_line;
              @$.last_column = @3.last_column;
              @$.last_line = @3.last_line;
              if ($3)
                $$ = $1 / $3;
              else
                {
                  $$ = 1;
                  printf("Division by zero, l%d,c%d-l%d,c%d",
                         @3.first_line, @3.first_column,
                         @3.last_line, @3.last_column);
                }
            }

As for semantic values, there is a default action for locations that is run each time a rule is matched. It sets the beginning of @$ to the beginning of the first symbol, and the end of @$ to the end of the last symbol.

With this default action, the location tracking can be fully automatic. The example above simply rewrites this way:

exp:    ...
        | exp '/' exp
            {
              if ($3)
                $$ = $1 / $3;
              else
                {
                  $$ = 1;
                  printf("Division by zero, l%d,c%d-l%d,c%d",
                         @3.first_line, @3.first_column,
                         @3.last_line, @3.last_column);
                }
            }

Node:Location Default Action, Previous:Actions and Locations, Up:Locations

Default Action for Locations

Actually, actions are not the best place to compute locations. Since locations are much more general than semantic values, there is room in the output parser to redefine the default action to take for each rule. The YYLLOC_DEFAULT macro is called each time a rule is matched, before the associated action is run.

Most of the time, this macro is general enough to suppress location dedicated code from semantic actions.

The YYLLOC_DEFAULT macro takes three parameters. The first one is the location of the grouping (the result of the computation). The second one is an array holding locations of all right hand side elements of the rule being matched. The last one is the size of the right hand side rule.

By default, it is defined this way:

#define YYLLOC_DEFAULT(Current, Rhs, N)         \
  Current.last_line   = Rhs[N].last_line;       \
  Current.last_column = Rhs[N].last_column;

When defining YYLLOC_DEFAULT, you should consider that:

  • All arguments are free of side-effects. However, only the first one (the result) should be modified by YYLLOC_DEFAULT.
  • Before YYLLOC_DEFAULT is executed, the output parser sets @$ to @1.
  • For consistency with semantic actions, valid indexes for the location array range from 1 to n.

Node:Declarations, Next:Multiple Parsers, Previous:Locations, Up:Grammar File

Bison Declarations

The Bison declarations section of a Bison grammar defines the symbols used in formulating the grammar and the data types of semantic values. See Symbols.

All token type names (but not single-character literal tokens such as '+' and '*') must be declared. Nonterminal symbols must be declared if you need to specify which data type to use for the semantic value (see More Than One Value Type).

The first rule in the file also specifies the start symbol, by default. If you want some other symbol to be the start symbol, you must declare it explicitly (see Languages and Context-Free Grammars).

  • Token Decl: Declaring terminal symbols.
  • Precedence Decl: Declaring terminals with precedence and associativity.
  • Union Decl: Declaring the set of all semantic value types.
  • Type Decl: Declaring the choice of type for a nonterminal symbol.
  • Expect Decl: Suppressing warnings about shift/reduce conflicts.
  • Start Decl: Specifying the start symbol.
  • Pure Decl: Requesting a reentrant parser.
  • Decl Summary: Table of all Bison declarations.

Node:Token Decl, Next:Precedence Decl, Up:Declarations

Token Type Names

The basic way to declare a token type name (terminal symbol) is as follows:

%token name

Bison will convert this into a #define directive in the parser, so that the function yylex (if it is in this file) can use the name name to stand for this token type's code.

Alternatively, you can use %left, %right, or %nonassoc instead of %token, if you wish to specify associativity and precedence. See Operator Precedence.

You can explicitly specify the numeric code for a token type by appending an integer value in the field immediately following the token name:

%token NUM 300

It is generally best, however, to let Bison choose the numeric codes for all token types. Bison will automatically select codes that don't conflict with each other or with ASCII characters.

In the event that the stack type is a union, you must augment the %token or other token declaration to include the data type alternative delimited by angle-brackets (see More Than One Value Type).

For example:

%union {              /* define stack type */
  double val;
  symrec *tptr;
}
%token <val> NUM      /* define token NUM and its type */

You can associate a literal string token with a token type name by writing the literal string at the end of a %token declaration which declares the name. For example:

%token arrow "=>"

For example, a grammar for the C language might specify these names with equivalent literal string tokens:

%token  <operator>  OR      "||"
%token  <operator>  LE 134  "<="
%left  OR  "<="

Once you equate the literal string and the token name, you can use them interchangeably in further declarations or the grammar rules. The yylex function can use the token name or the literal string to obtain the token type code number (see Calling Convention).

Node:Precedence Decl, Next:Union Decl, Previous:Token Decl, Up:Declarations

Operator Precedence

Use the %left, %right or %nonassoc declaration to declare a token and specify its precedence and associativity, all at once. These are called precedence declarations. See Operator Precedence, for general information on operator precedence.

The syntax of a precedence declaration is the same as that of %token: either

%left symbols...

or

%left <type> symbols...

And indeed any of these declarations serves the purposes of %token. But in addition, they specify the associativity and relative precedence for all the symbols:

  • The associativity of an operator op determines how repeated uses of the operator nest: whether x op y op z is parsed by grouping x with y first or by grouping y with z first. %left specifies left-associativity (grouping x with y first) and %right specifies right-associativity (grouping y with z first). %nonassoc specifies no associativity, which means that x op y op z is considered a syntax error.
  • The precedence of an operator determines how it nests with other operators. All the tokens declared in a single precedence declaration have equal precedence and nest together according to their associativity. When two tokens declared in different precedence declarations associate, the one declared later has the higher precedence and is grouped first.

Node:Union Decl, Next:Type Decl, Previous:Precedence Decl, Up:Declarations

The Collection of Value Types

The %union declaration specifies the entire collection of possible data types for semantic values. The keyword %union is followed by a pair of braces containing the same thing that goes inside a union in C.

For example:

%union {
  double val;
  symrec *tptr;
}

This says that the two alternative types are double and symrec *. They are given names val and tptr; these names are used in the %token and %type declarations to pick one of the types for a terminal or nonterminal symbol (see Nonterminal Symbols).

Note that, unlike making a union declaration in C, you do not write a semicolon after the closing brace.

Node:Type Decl, Next:Expect Decl, Previous:Union Decl, Up:Declarations

Nonterminal Symbols

When you use %union to specify multiple value types, you must declare the value type of each nonterminal symbol for which values are used. This is done with a %type declaration, like this:

%type <type> nonterminal...

Here nonterminal is the name of a nonterminal symbol, and type is the name given in the %union to the alternative that you want (see The Collection of Value Types). You can give any number of nonterminal symbols in the same %type declaration, if they have the same value type. Use spaces to separate the symbol names.

You can also declare the value type of a terminal symbol. To do this, use the same <type> construction in a declaration for the terminal symbol. All kinds of token declarations allow <type>.

Node:Expect Decl, Next:Start Decl, Previous:Type Decl, Up:Declarations

Suppressing Conflict Warnings

Bison normally warns if there are any conflicts in the grammar (see Shift/Reduce Conflicts), but most real grammars have harmless shift/reduce conflicts which are resolved in a predictable way and would be difficult to eliminate. It is desirable to suppress the warning about these conflicts unless the number of conflicts changes. You can do this with the %expect declaration.

The declaration looks like this:

%expect n

Here n is a decimal integer. The declaration says there should be no warning if there are n shift/reduce conflicts and no reduce/reduce conflicts. An error, instead of the usual warning, is given if there are either more or fewer conflicts, or if there are any reduce/reduce conflicts.

In general, using %expect involves these steps:

  • Compile your grammar without %expect. Use the -v option to get a verbose list of where the conflicts occur. Bison will also print the number of conflicts.
  • Check each of the conflicts to make sure that Bison's default resolution is what you really want. If not, rewrite the grammar and go back to the beginning.
  • Add an %expect declaration, copying the number n from the number which Bison printed.

Now Bison will stop annoying you about the conflicts you have checked, but it will warn you again if changes in the grammar result in additional conflicts.

Node:Start Decl, Next:Pure Decl, Previous:Expect Decl, Up:Declarations

The Start-Symbol

Bison assumes by default that the start symbol for the grammar is the first nonterminal specified in the grammar specification section. The programmer may override this restriction with the %start declaration as follows:

%start symbol

Node:Pure Decl, Next:Decl Summary, Previous:Start Decl, Up:Declarations

A Pure (Reentrant) Parser

A reentrant program is one which does not alter in the course of execution; in other words, it consists entirely of pure (read-only) code. Reentrancy is important whenever asynchronous execution is possible; for example, a non-reentrant program may not be safe to call from a signal handler. In systems with multiple threads of control, a non-reentrant program must be called only within interlocks.

Normally, Bison generates a parser which is not reentrant. This is suitable for most uses, and it permits compatibility with YACC. (The standard YACC interfaces are inherently nonreentrant, because they use statically allocated variables for communication with yylex, including yylval and yylloc.)

Alternatively, you can generate a pure, reentrant parser. The Bison declaration %pure_parser says that you want the parser to be reentrant. It looks like this:

%pure_parser

The result is that the communication variables yylval and yylloc become local variables in yyparse, and a different calling convention is used for the lexical analyzer function yylex. See Calling Conventions for Pure Parsers, for the details of this. The variable yynerrs also becomes local in yyparse (see The Error Reporting Function yyerror). The convention for calling yyparse itself is unchanged.

Whether the parser is pure has nothing to do with the grammar rules. You can generate either a pure parser or a nonreentrant parser from any valid grammar.

Node:Decl Summary, Previous:Pure Decl, Up:Declarations

Bison Declaration Summary

Here is a summary of the declarations used to define a grammar:

%union
Declare the collection of data types that semantic values may have (see The Collection of Value Types).
%token
Declare a terminal symbol (token type name) with no precedence or associativity specified (see Token Type Names).
%right
Declare a terminal symbol (token type name) that is right-associative (see Operator Precedence).
%left
Declare a terminal symbol (token type name) that is left-associative (see Operator Precedence).
%nonassoc
Declare a terminal symbol (token type name) that is nonassociative (using it in a way that would be associative is a syntax error) (see Operator Precedence).
%type
Declare the type of semantic values for a nonterminal symbol (see Nonterminal Symbols).
%start
Specify the grammar's start symbol (see The Start-Symbol).
%expect
Declare the expected number of shift-reduce conflicts (see Suppressing Conflict Warnings).

In order to change the behavior of bison, use the following directives:

%debug
In the parser file, define the macro YYDEBUG to 1 if it is not already defined, so that the debugging facilities are compiled. See Debugging Your Parser.
%defines
Write an extra output file containing macro definitions for the token type names defined in the grammar and the semantic value type YYSTYPE, as well as a few extern variable declarations.

If the parser output file is named name.c then this file is named name.h.

This output file is essential if you wish to put the definition of yylex in a separate source file, because yylex needs to be able to refer to token type codes and the variable yylval. See Semantic Values of Tokens.

%file-prefix="prefix"
Specify a prefix to use for all Bison output file names. The names are chosen as if the input file were named prefix.y.
%locations
Generate the code processing the locations (see Special Features for Use in Actions). This mode is enabled as soon as the grammar uses the special @n tokens, but if your grammar does not use it, using %locations allows for more accurate parse error messages.
%name-prefix="prefix"
Rename the external symbols used in the parser so that they start with prefix instead of yy. The precise list of symbols renamed is yyparse, yylex, yyerror, yynerrs, yylval, yychar and yydebug. For example, if you use %name-prefix="c_", the names become c_parse, c_lex, and so on. See Multiple Parsers in the Same Program.
%no-parser
Do not include any C code in the parser file; generate tables only. The parser file contains just #define directives and static variable declarations.

This option also tells Bison to write the C code for the grammar actions into a file named filename.act, in the form of a brace-surrounded body fit for a switch statement.

%no-lines
Don't generate any #line preprocessor commands in the parser file. Ordinarily Bison writes these commands in the parser file so that the C compiler and debuggers will associate errors and object code with your source file (the grammar file). This directive causes them to associate errors with the parser file, treating it an independent source file in its own right.
%output="filename"
Specify the filename for the parser file.
%pure-parser
Request a pure (reentrant) parser program (see A Pure (Reentrant) Parser).
%token_table
Generate an array of token names in the parser file. The name of the array is yytname; yytname[i] is the name of the token whose internal Bison token code number is i. The first three elements of yytname are always "$", "error", and "$illegal"; after these come the symbols defined in the grammar file.

For single-character literal tokens and literal string tokens, the name in the table includes the single-quote or double-quote characters: for example, "'+'" is a single-character literal and "\"<=\"" is a literal string token. All the characters of the literal string token appear verbatim in the string found in the table; even double-quote characters are not escaped. For example, if the token consists of three characters *"*, its string in yytname contains "*"*". (In C, that would be written as "\"*\"*\"").

When you specify %token_table, Bison also generates macro definitions for macros YYNTOKENS, YYNNTS, and YYNRULES, and YYNSTATES:

YYNTOKENS
The highest token number, plus one.
YYNNTS
The number of nonterminal symbols.
YYNRULES
The number of grammar rules,
YYNSTATES
The number of parser states (see Parser States).

%verbose
Write an extra output file containing verbose descriptions of the parser states and what is done for each type of look-ahead token in that state.

This file also describes all the conflicts, both those resolved by operator precedence and the unresolved ones.

The file's name is made by removing .tab.c or .c from the parser output file name, and adding .output instead.

Therefore, if the input file is foo.y, then the parser file is called foo.tab.c by default. As a consequence, the verbose output file is called foo.output.

%yacc
%fixed-output-files
Pretend the option --yacc was given, i.e., imitate Yacc, including its naming conventions. See Bison Options, for more.

Node:Multiple Parsers, Previous:Declarations, Up:Grammar File

Multiple Parsers in the Same Program

Most programs that use Bison parse only one language and therefore contain only one Bison parser. But what if you want to parse more than one language with the same program? Then you need to avoid a name conflict between different definitions of yyparse, yylval, and so on.

The easy way to do this is to use the option -p prefix (see Invoking Bison). This renames the interface functions and variables of the Bison parser to start with prefix instead of yy. You can use this to give each parser distinct names that do not conflict.

The precise list of symbols renamed is yyparse, yylex, yyerror, yynerrs, yylval, yychar and yydebug. For example, if you use -p c, the names become cparse, clex, and so on.

All the other variables and macros associated with Bison are not renamed. These others are not global; there is no conflict if the same name is used in different parsers. For example, YYSTYPE is not renamed, but defining this in different ways in different parsers causes no trouble (see Data Types of Semantic Values).

The -p option works by adding macro definitions to the beginning of the parser source file, defining yyparse as prefixparse, and so on. This effectively substitutes one name for the other in the entire parser file.

Node:Interface, Next:Algorithm, Previous:Grammar File, Up:Top

Parser C-Language Interface

The Bison parser is actually a C function named yyparse. Here we describe the interface conventions of yyparse and the other functions that it needs to use.

Keep in mind that the parser uses many C identifiers starting with yy and YY for internal purposes. If you use such an identifier (aside from those in this manual) in an action or in additional C code in the grammar file, you are likely to run into trouble.

  • Parser Function: How to call yyparse and what it returns.
  • Lexical: You must supply a function yylex which reads tokens.
  • Error Reporting: You must supply a function yyerror.
  • Action Features: Special features for use in actions.

Node:Parser Function, Next:Lexical, Up:Interface

The Parser Function yyparse

You call the function yyparse to cause parsing to occur. This function reads tokens, executes actions, and ultimately returns when it encounters end-of-input or an unrecoverable syntax error. You can also write an action which directs yyparse to return immediately without reading further.

The value returned by yyparse is 0 if parsing was successful (return is due to end-of-input).

The value is 1 if parsing failed (return is due to a syntax error).

In an action, you can cause immediate return from yyparse by using these macros:

YYACCEPT
Return immediately with value 0 (to report success).
YYABORT
Return immediately with value 1 (to report failure).

Node:Lexical, Next:Error Reporting, Previous:Parser Function, Up:Interface

The Lexical Analyzer Function yylex

The lexical analyzer function, yylex, recognizes tokens from the input stream and returns them to the parser. Bison does not create this function automatically; you must write it so that yyparse can call it. The function is sometimes referred to as a lexical scanner.

In simple programs, yylex is often defined at the end of the Bison grammar file. If yylex is defined in a separate source file, you need to arrange for the token-type macro definitions to be available there. To do this, use the -d option when you run Bison, so that it will write these macro definitions into a separate header file name.tab.h which you can include in the other source files that need it. See Invoking Bison.

  • Calling Convention: How yyparse calls yylex.
  • Token Values: How yylex must return the semantic value of the token it has read.
  • Token Positions: How yylex must return the text position (line number, etc.) of the token, if the actions want that.
  • Pure Calling: How the calling convention differs in a pure parser (see A Pure (Reentrant) Parser).

Node:Calling Convention, Next:Token Values, Up:Lexical

Calling Convention for yylex

The value that yylex returns must be the numeric code for the type of token it has just found, or 0 for end-of-input.

When a token is referred to in the grammar rules by a name, that name in the parser file becomes a C macro whose definition is the proper numeric code for that token type. So yylex can use the name to indicate that type. See Symbols.

When a token is referred to in the grammar rules by a character literal, the numeric code for that character is also the code for the token type. So yylex can simply return that character code. The null character must not be used this way, because its code is zero and that is what signifies end-of-input.

Here is an example showing these things:

int
yylex (void)
{
  ...
  if (c == EOF)     /* Detect end of file. */
    return 0;
  ...
  if (c == '+' || c == '-')
    return c;      /* Assume token type for `+' is '+'. */
  ...
  return INT;      /* Return the type of the token. */
  ...
}

This interface has been designed so that the output from the lex utility can be used without change as the definition of yylex.

If the grammar uses literal string tokens, there are two ways that yylex can determine the token type codes for them:

  • If the grammar defines symbolic token names as aliases for the literal string tokens, yylex can use these symbolic names like all others. In this case, the use of the literal string tokens in the grammar file has no effect on yylex.
  • yylex can find the multicharacter token in the yytname table. The index of the token in the table is the token type's code. The name of a multicharacter token is recorded in yytname with a double-quote, the token's characters, and another double-quote. The token's characters are not escaped in any way; they appear verbatim in the contents of the string in the table.

    Here's code for looking up a token in yytname, assuming that the characters of the token are stored in token_buffer.

    for (i = 0; i < YYNTOKENS; i++)
  {
    if (yytname[i] != 0
        && yytname[i][0] == '"'
        && strncmp (yytname[i] + 1, token_buffer,
                    strlen (token_buffer))
        && yytname[i][strlen (token_buffer) + 1] == '"'
        && yytname[i][strlen (token_buffer) + 2] == 0)
      break;
  }

    The yytname table is generated only if you use the %token_table declaration. See Decl Summary.

Node:Token Values, Next:Token Positions, Previous:Calling Convention, Up:Lexical

Semantic Values of Tokens

In an ordinary (non-reentrant) parser, the semantic value of the token must be stored into the global variable yylval. When you are using just one data type for semantic values, yylval has that type. Thus, if the type is int (the default), you might write this in yylex:

  ...
  yylval = value;  /* Put value onto Bison stack. */
  return INT;      /* Return the type of the token. */
  ...

When you are using multiple data types, yylval's type is a union made from the %union declaration (see The Collection of Value Types). So when you store a token's value, you must use the proper member of the union. If the %union declaration looks like this:

%union {
  int intval;
  double val;
  symrec *tptr;
}

then the code in yylex might look like this:

  ...
  yylval.intval = value; /* Put value onto Bison stack. */
  return INT;          /* Return the type of the token. */
  ...

Node:Token Positions, Next:Pure Calling, Previous:Token Values, Up:Lexical

Textual Positions of Tokens

If you are using the @n-feature (see Tracking Locations) in actions to keep track of the textual locations of tokens and groupings, then you must provide this information in yylex. The function yyparse expects to find the textual location of a token just parsed in the global variable yylloc. So yylex must store the proper data in that variable.

By default, the value of yylloc is a structure and you need only initialize the members that are going to be used by the actions. The four members are called first_line, first_column, last_line and last_column. Note that the use of this feature makes the parser noticeably slower.

The data type of yylloc has the name YYLTYPE.

Node:Pure Calling, Previous:Token Positions, Up:Lexical

Calling Conventions for Pure Parsers

When you use the Bison declaration %pure_parser to request a pure, reentrant parser, the global communication variables yylval and yylloc cannot be used. (See A Pure (Reentrant) Parser.) In such parsers the two global variables are replaced by pointers passed as arguments to yylex. You must declare them as shown here, and pass the information back by storing it through those pointers.

int
yylex (YYSTYPE *lvalp, YYLTYPE *llocp)
{
  ...
  *lvalp = value;  /* Put value onto Bison stack.  */
  return INT;      /* Return the type of the token.  */
  ...
}

If the grammar file does not use the @ constructs to refer to textual positions, then the type YYLTYPE will not be defined. In this case, omit the second argument; yylex will be called with only one argument.

If you use a reentrant parser, you can optionally pass additional parameter information to it in a reentrant way. To do so, define the macro YYPARSE_PARAM as a variable name. This modifies the yyparse function to accept one argument, of type void *, with that name.

When you call yyparse, pass the address of an object, casting the address to void *. The grammar actions can refer to the contents of the object by casting the pointer value back to its proper type and then dereferencing it. Here's an example. Write this in the parser:

%{
struct parser_control
{
  int nastiness;
  int randomness;
};

#define YYPARSE_PARAM parm
%}

Then call the parser like this:

struct parser_control
{
  int nastiness;
  int randomness;
};

...

{
  struct parser_control foo;
  ...  /* Store proper data in foo.  */
  value = yyparse ((void *) &foo);
  ...
}

In the grammar actions, use expressions like this to refer to the data:

((struct parser_control *) parm)->randomness

If you wish to pass the additional parameter data to yylex, define the macro YYLEX_PARAM just like YYPARSE_PARAM, as shown here:

%{
struct parser_control
{
  int nastiness;
  int randomness;
};

#define YYPARSE_PARAM parm
#define YYLEX_PARAM parm
%}

You should then define yylex to accept one additional argument--the value of parm. (This makes either two or three arguments in total, depending on whether an argument of type YYLTYPE is passed.) You can declare the argument as a pointer to the proper object type, or you can declare it as void * and access the contents as shown above.

You can use %pure_parser to request a reentrant parser without also using YYPARSE_PARAM. Then you should call yyparse with no arguments, as usual.

Node:Error Reporting, Next:Action Features, Previous:Lexical, Up:Interface

The Error Reporting Function yyerror

The Bison parser detects a parse error or syntax error whenever it reads a token which cannot satisfy any syntax rule. An action in the grammar can also explicitly proclaim an error, using the macro YYERROR (see Special Features for Use in Actions).

The Bison parser expects to report the error by calling an error reporting function named yyerror, which you must supply. It is called by yyparse whenever a syntax error is found, and it receives one argument. For a parse error, the string is normally "parse error".

If you define the macro YYERROR_VERBOSE in the Bison declarations section (see The Bison Declarations Section), then Bison provides a more verbose and specific error message string instead of just plain "parse error". It doesn't matter what definition you use for YYERROR_VERBOSE, just whether you define it.

The parser can detect one other kind of error: stack overflow. This happens when the input contains constructions that are very deeply nested. It isn't likely you will encounter this, since the Bison parser extends its stack automatically up to a very large limit. But if overflow happens, yyparse calls yyerror in the usual fashion, except that the argument string is "parser stack overflow".

The following definition suffices in simple programs:

void
yyerror (char *s)
{
  fprintf (stderr, "%s\n", s);
}

After yyerror returns to yyparse, the latter will attempt error recovery if you have written suitable error recovery grammar rules (see Error Recovery). If recovery is impossible, yyparse will immediately return 1.

The variable yynerrs contains the number of syntax errors encountered so far. Normally this variable is global; but if you request a pure parser (see A Pure (Reentrant) Parser) then it is a local variable which only the actions can access.

Node:Action Features, Previous:Error Reporting, Up:Interface

Special Features for Use in Actions

Here is a table of Bison constructs, variables and macros that are useful in actions.

$$
Acts like a variable that contains the semantic value for the grouping made by the current rule. See Actions.
$n
Acts like a variable that contains the semantic value for the nth component of the current rule. See Actions.
$<typealt>$
Like $$ but specifies alternative typealt in the union specified by the %union declaration. See Data Types of Values in Actions.
$<typealt>n
Like $n but specifies alternative typealt in the union specified by the %union declaration. See Data Types of Values in Actions.
YYABORT;
Return immediately from yyparse, indicating failure. See The Parser Function yyparse.
YYACCEPT;
Return immediately from yyparse, indicating success. See The Parser Function yyparse.
YYBACKUP (token, value);
Unshift a token. This macro is allowed only for rules that reduce a single value, and only when there is no look-ahead token. It installs a look-ahead token with token type token and semantic value value; then it discards the value that was going to be reduced by this rule.

If the macro is used when it is not valid, such as when there is a look-ahead token already, then it reports a syntax error with a message cannot back up and performs ordinary error recovery.

In either case, the rest of the action is not executed.

YYEMPTY
Value stored in yychar when there is no look-ahead token.
YYERROR;
Cause an immediate syntax error. This statement initiates error recovery just as if the parser itself had detected an error; however, it does not call yyerror, and does not print any message. If you want to print an error message, call yyerror explicitly before the YYERROR; statement. See Error Recovery.
YYRECOVERING
This macro stands for an expression that has the value 1 when the parser is recovering from a syntax error, and 0 the rest of the time. See Error Recovery.
yychar
Variable containing the current look-ahead token. (In a pure parser, this is actually a local variable within yyparse.) When there is no look-ahead token, the value YYEMPTY is stored in the variable. See Look-Ahead Tokens.
yyclearin;
Discard the current look-ahead token. This is useful primarily in error rules. See Error Recovery.
yyerrok;
Resume generating error messages immediately for subsequent syntax errors. This is useful primarily in error rules. See Error Recovery.
@$
Acts like a structure variable containing information on the textual position of the grouping made by the current rule. See Tracking Locations.
@n
Acts like a structure variable containing information on the textual position of the nth component of the current rule. See Tracking Locations.

Node:Algorithm, Next:Error Recovery, Previous:Interface, Up:Top

The Bison Parser Algorithm

As Bison reads tokens, it pushes them onto a stack along with their semantic values. The stack is called the parser stack. Pushing a token is traditionally called shifting.

For example, suppose the infix calculator has read 1 + 5 *, with a 3 to come. The stack will have four elements, one for each token that was shifted.

But the stack does not always have an element for each token read. When the last n tokens and groupings shifted match the components of a grammar rule, they can be combined according to that rule. This is called reduction. Those tokens and groupings are replaced on the stack by a single grouping whose symbol is the result (left hand side) of that rule. Running the rule's action is part of the process of reduction, because this is what computes the semantic value of the resulting grouping.

For example, if the infix calculator's parser stack contains this:

1 + 5 * 3

and the next input token is a newline character, then the last three elements can be reduced to 15 via the rule:

expr: expr '*' expr;

Then the stack contains just these three elements:

1 + 15

At this point, another reduction can be made, resulting in the single value 16. Then the newline token can be shifted.

The parser tries, by shifts and reductions, to reduce the entire input down to a single grouping whose symbol is the grammar's start-symbol (see Languages and Context-Free Grammars).

This kind of parser is known in the literature as a bottom-up parser.

  • Look-Ahead: Parser looks one token ahead when deciding what to do.
  • Shift/Reduce: Conflicts: when either shifting or reduction is valid.
  • Precedence: Operator precedence works by resolving conflicts.
  • Contextual Precedence: When an operator's precedence depends on context.
  • Parser States: The parser is a finite-state-machine with stack.
  • Reduce/Reduce: When two rules are applicable in the same situation.
  • Mystery Conflicts: Reduce/reduce conflicts that look unjustified.
  • Stack Overflow: What happens when stack gets full. How to avoid it.

Node:Look-Ahead, Next:Shift/Reduce, Up:Algorithm

Look-Ahead Tokens

The Bison parser does not always reduce immediately as soon as the last n tokens and groupings match a rule. This is because such a simple strategy is inadequate to handle most languages. Instead, when a reduction is possible, the parser sometimes "looks ahead" at the next token in order to decide what to do.

When a token is read, it is not immediately shifted; first it becomes the look-ahead token, which is not on the stack. Now the parser can perform one or more reductions of tokens and groupings on the stack, while the look-ahead token remains off to the side. When no more reductions should take place, the look-ahead token is shifted onto the stack. This does not mean that all possible reductions have been done; depending on the token type of the look-ahead token, some rules may choose to delay their application.

Here is a simple case where look-ahead is needed. These three rules define expressions which contain binary addition operators and postfix unary factorial operators (!), and allow parentheses for grouping.

expr:     term '+' expr
        | term
        ;

term:     '(' expr ')'
        | term '!'
        | NUMBER
        ;

Suppose that the tokens 1 + 2 have been read and shifted; what should be done? If the following token is ), then the first three tokens must be reduced to form an expr. This is the only valid course, because shifting the ) would produce a sequence of symbols term ')', and no rule allows this.

If the following token is !, then it must be shifted immediately so that 2 ! can be reduced to make a term. If instead the parser were to reduce before shifting, 1 + 2 would become an expr. It would then be impossible to shift the ! because doing so would produce on the stack the sequence of symbols expr '!'. No rule allows that sequence.

The current look-ahead token is stored in the variable yychar. See Special Features for Use in Actions.

Node:Shift/Reduce, Next:Precedence, Previous:Look-Ahead, Up:Algorithm

Shift/Reduce Conflicts

Suppose we are parsing a language which has if-then and if-then-else statements, with a pair of rules like this:

if_stmt:
          IF expr THEN stmt
        | IF expr THEN stmt ELSE stmt
        ;

Here we assume that IF, THEN and ELSE are terminal symbols for specific keyword tokens.

When the ELSE token is read and becomes the look-ahead token, the contents of the stack (assuming the input is valid) are just right for reduction by the first rule. But it is also legitimate to shift the ELSE, because that would lead to eventual reduction by the second rule.

This situation, where either a shift or a reduction would be valid, is called a shift/reduce conflict. Bison is designed to resolve these conflicts by choosing to shift, unless otherwise directed by operator precedence declarations. To see the reason for this, let's contrast it with the other alternative.

Since the parser prefers to shift the ELSE, the result is to attach the else-clause to the innermost if-statement, making these two inputs equivalent:

if x then if y then win (); else lose;

if x then do; if y then win (); else lose; end;

But if the parser chose to reduce when possible rather than shift, the result would be to attach the else-clause to the outermost if-statement, making these two inputs equivalent:

if x then if y then win (); else lose;

if x then do; if y then win (); end; else lose;

The conflict exists because the grammar as written is ambiguous: either parsing of the simple nested if-statement is legitimate. The established convention is that these ambiguities are resolved by attaching the else-clause to the innermost if-statement; this is what Bison accomplishes by choosing to shift rather than reduce. (It would ideally be cleaner to write an unambiguous grammar, but that is very hard to do in this case.) This particular ambiguity was first encountered in the specifications of Algol 60 and is called the "dangling else" ambiguity.

To avoid warnings from Bison about predictable, legitimate shift/reduce conflicts, use the %expect n declaration. There will be no warning as long as the number of shift/reduce conflicts is exactly n. See Suppressing Conflict Warnings.

The definition of if_stmt above is solely to blame for the conflict, but the conflict does not actually appear without additional rules. Here is a complete Bison input file that actually manifests the conflict:

%token IF THEN ELSE variable
%%
stmt:     expr
        | if_stmt
        ;

if_stmt:
          IF expr THEN stmt
        | IF expr THEN stmt ELSE stmt
        ;

expr:     variable
        ;

Node:Precedence, Next:Contextual Precedence, Previous:Shift/Reduce, Up:Algorithm

Operator Precedence

Another situation where shift/reduce conflicts appear is in arithmetic expressions. Here shifting is not always the preferred resolution; the Bison declarations for operator precedence allow you to specify when to shift and when to reduce.

  • Why Precedence: An example showing why precedence is needed.
  • Using Precedence: How to specify precedence in Bison grammars.
  • Precedence Examples: How these features are used in the previous example.
  • How Precedence: How they work.

Node:Why Precedence, Next:Using Precedence, Up:Precedence

When Precedence is Needed

Consider the following ambiguous grammar fragment (ambiguous because the input 1 - 2 * 3 can be parsed in two different ways):

expr:     expr '-' expr
        | expr '*' expr
        | expr '<' expr
        | '(' expr ')'
        ...
        ;

Suppose the parser has seen the tokens 1, - and 2; should it reduce them via the rule for the subtraction operator? It depends on the next token. Of course, if the next token is ), we must reduce; shifting is invalid because no single rule can reduce the token sequence - 2 ) or anything starting with that. But if the next token is * or <, we have a choice: either shifting or reduction would allow the parse to complete, but with different results.

To decide which one Bison should do, we must consider the results. If the next operator token op is shifted, then it must be reduced first in order to permit another opportunity to reduce the difference. The result is (in effect) 1 - (2 op 3). On the other hand, if the subtraction is reduced before shifting op, the result is (1 - 2) op 3. Clearly, then, the choice of shift or reduce should depend on the relative precedence of the operators - and op: * should be shifted first, but not <.

What about input such as 1 - 2 - 5; should this be (1 - 2) - 5 or should it be 1 - (2 - 5)? For most operators we prefer the former, which is called left association. The latter alternative, right association, is desirable for assignment operators. The choice of left or right association is a matter of whether the parser chooses to shift or reduce when the stack contains 1 - 2 and the look-ahead token is -: shifting makes right-associativity.

Node:Using Precedence, Next:Precedence Examples, Previous:Why Precedence, Up:Precedence

Specifying Operator Precedence

Bison allows you to specify these choices with the operator precedence declarations %left and %right. Each such declaration contains a list of tokens, which are operators whose precedence and associativity is being declared. The %left declaration makes all those operators left-associative and the %right declaration makes them right-associative. A third alternative is %nonassoc, which declares that it is a syntax error to find the same operator twice "in a row".

The relative precedence of different operators is controlled by the order in which they are declared. The first %left or %right declaration in the file declares the operators whose precedence is lowest, the next such declaration declares the operators whose precedence is a little higher, and so on.

Node:Precedence Examples, Next:How Precedence, Previous:Using Precedence, Up:Precedence

Precedence Examples

In our example, we would want the following declarations:

%left '<'
%left '-'
%left '*'

In a more complete example, which supports other operators as well, we would declare them in groups of equal precedence. For example, '+' is declared with '-':

%left '<' '>' '=' NE LE GE
%left '+' '-'
%left '*' '/'

(Here NE and so on stand for the operators for "not equal" and so on. We assume that these tokens are more than one character long and therefore are represented by names, not character literals.)

Node:How Precedence, Previous:Precedence Examples, Up:Precedence

How Precedence Works

The first effect of the precedence declarations is to assign precedence levels to the terminal symbols declared. The second effect is to assign precedence levels to certain rules: each rule gets its precedence from the last terminal symbol mentioned in the components. (You can also specify explicitly the precedence of a rule. See Context-Dependent Precedence.)

Finally, the resolution of conflicts works by comparing the precedence of the rule being considered with that of the look-ahead token. If the token's precedence is higher, the choice is to shift. If the rule's precedence is higher, the choice is to reduce. If they have equal precedence, the choice is made based on the associativity of that precedence level. The verbose output file made by -v (see Invoking Bison) says how each conflict was resolved.

Not all rules and not all tokens have precedence. If either the rule or the look-ahead token has no precedence, then the default is to shift.

Node:Contextual Precedence, Next:Parser States, Previous:Precedence, Up:Algorithm

Context-Dependent Precedence

Often the precedence of an operator depends on the context. This sounds outlandish at first, but it is really very common. For example, a minus sign typically has a very high precedence as a unary operator, and a somewhat lower precedence (lower than multiplication) as a binary operator.

The Bison precedence declarations, %left, %right and %nonassoc, can only be used once for a given token; so a token has only one precedence declared in this way. For context-dependent precedence, you need to use an additional mechanism: the %prec modifier for rules.

The %prec modifier declares the precedence of a particular rule by specifying a terminal symbol whose precedence should be used for that rule. It's not necessary for that symbol to appear otherwise in the rule. The modifier's syntax is:

%prec terminal-symbol

and it is written after the components of the rule. Its effect is to assign the rule the precedence of terminal-symbol, overriding the precedence that would be deduced for it in the ordinary way. The altered rule precedence then affects how conflicts involving that rule are resolved (see Operator Precedence).

Here is how %prec solves the problem of unary minus. First, declare a precedence for a fictitious terminal symbol named UMINUS. There are no tokens of this type, but the symbol serves to stand for its precedence:

...
%left '+' '-'
%left '*'
%left UMINUS

Now the precedence of UMINUS can be used in specific rules:

exp:    ...
        | exp '-' exp
        ...
        | '-' exp %prec UMINUS

Node:Parser States, Next:Reduce/Reduce, Previous:Contextual Precedence, Up:Algorithm

Parser States

The function yyparse is implemented using a finite-state machine. The values pushed on the parser stack are not simply token type codes; they represent the entire sequence of terminal and nonterminal symbols at or near the top of the stack. The current state collects all the information about previous input which is relevant to deciding what to do next.

Each time a look-ahead token is read, the current parser state together with the type of look-ahead token are looked up in a table. This table entry can say, "Shift the look-ahead token." In this case, it also specifies the new parser state, which is pushed onto the top of the parser stack. Or it can say, "Reduce using rule number n." This means that a certain number of tokens or groupings are taken off the top of the stack, and replaced by one grouping. In other words, that number of states are popped from the stack, and one new state is pushed.

There is one other alternative: the table can say that the look-ahead token is erroneous in the current state. This causes error processing to begin (see Error Recovery).

Node:Reduce/Reduce, Next:Mystery Conflicts, Previous:Parser States, Up:Algorithm

Reduce/Reduce Conflicts

A reduce/reduce conflict occurs if there are two or more rules that apply to the same sequence of input. This usually indicates a serious error in the grammar.

For example, here is an erroneous attempt to define a sequence of zero or more word groupings.

sequence: /* empty */
                { printf ("empty sequence\n"); }
        | maybeword
        | sequence word
                { printf ("added word %s\n", $2); }
        ;

maybeword: /* empty */
                { printf ("empty maybeword\n"); }
        | word
                { printf ("single word %s\n", $1); }
        ;

The error is an ambiguity: there is more than one way to parse a single word into a sequence. It could be reduced to a maybeword and then into a sequence via the second rule. Alternatively, nothing-at-all could be reduced into a sequence via the first rule, and this could be combined with the word using the third rule for sequence.

There is also more than one way to reduce nothing-at-all into a sequence. This can be done directly via the first rule, or indirectly via maybeword and then the second rule.

You might think that this is a distinction without a difference, because it does not change whether any particular input is valid or not. But it does affect which actions are run. One parsing order runs the second rule's action; the other runs the first rule's action and the third rule's action. In this example, the output of the program changes.

Bison resolves a reduce/reduce conflict by choosing to use the rule that appears first in the grammar, but it is very risky to rely on this. Every reduce/reduce conflict must be studied and usually eliminated. Here is the proper way to define sequence:

sequence: /* empty */
                { printf ("empty sequence\n"); }
        | sequence word
                { printf ("added word %s\n", $2); }
        ;

Here is another common error that yields a reduce/reduce conflict:

sequence: /* empty */
        | sequence words
        | sequence redirects
        ;

words:    /* empty */
        | words word
        ;

redirects:/* empty */
        | redirects redirect
        ;

The intention here is to define a sequence which can contain either word or redirect groupings. The individual definitions of sequence, words and redirects are error-free, but the three together make a subtle ambiguity: even an empty input can be parsed in infinitely many ways!

Consider: nothing-at-all could be a words. Or it could be two words in a row, or three, or any number. It could equally well be a redirects, or two, or any number. Or it could be a words followed by three redirects and another words. And so on.

Here are two ways to correct these rules. First, to make it a single level of sequence:

sequence: /* empty */
        | sequence word
        | sequence redirect
        ;

Second, to prevent either a words or a redirects from being empty:

sequence: /* empty */
        | sequence words
        | sequence redirects
        ;

words:    word
        | words word
        ;

redirects:redirect
        | redirects redirect
        ;

Node:Mystery Conflicts, Next:Stack Overflow, Previous:Reduce/Reduce, Up:Algorithm

Mysterious Reduce/Reduce Conflicts

Sometimes reduce/reduce conflicts can occur that don't look warranted. Here is an example:

%token ID

%%
def:    param_spec return_spec ','
        ;
param_spec:
             type
        |    name_list ':' type
        ;
return_spec:
             type
        |    name ':' type
        ;
type:        ID
        ;
name:        ID
        ;
name_list:
             name
        |    name ',' name_list
        ;

It would seem that this grammar can be parsed with only a single token of look-ahead: when a param_spec is being read, an ID is a name if a comma or colon follows, or a type if another ID follows. In other words, this grammar is LR(1).

However, Bison, like most parser generators, cannot actually handle all LR(1) grammars. In this grammar, two contexts, that after an ID at the beginning of a param_spec and likewise at the beginning of a return_spec, are similar enough that Bison assumes they are the same. They appear similar because the same set of rules would be active--the rule for reducing to a name and that for reducing to a type. Bison is unable to determine at that stage of processing that the rules would require different look-ahead tokens in the two contexts, so it makes a single parser state for them both. Combining the two contexts causes a conflict later. In parser terminology, this occurrence means that the grammar is not LALR(1).

In general, it is better to fix deficiencies than to document them. But this particular deficiency is intrinsically hard to fix; parser generators that can handle LR(1) grammars are hard to write and tend to produce parsers that are very large. In practice, Bison is more useful as it is now.

When the problem arises, you can often fix it by identifying the two parser states that are being confused, and adding something to make them look distinct. In the above example, adding one rule to return_spec as follows makes the problem go away:

%token BOGUS
...
%%
...
return_spec:
             type
        |    name ':' type
        /* This rule is never used.  */
        |    ID BOGUS
        ;

This corrects the problem because it introduces the possibility of an additional active rule in the context after the ID at the beginning of return_spec. This rule is not active in the corresponding context in a param_spec, so the two contexts receive distinct parser states. As long as the token BOGUS is never generated by yylex, the added rule cannot alter the way actual input is parsed.

In this particular example, there is another way to solve the problem: rewrite the rule for return_spec to use ID directly instead of via name. This also causes the two confusing contexts to have different sets of active rules, because the one for return_spec activates the altered rule for return_spec rather than the one for name.

param_spec:
             type
        |    name_list ':' type
        ;
return_spec:
             type
        |    ID ':' type
        ;

Node:Stack Overflow, Previous:Mystery Conflicts, Up:Algorithm

Stack Overflow, and How to Avoid It

The Bison parser stack can overflow if too many tokens are shifted and not reduced. When this happens, the parser function yyparse returns a nonzero value, pausing only to call yyerror to report the overflow.

By defining the macro YYMAXDEPTH, you can control how deep the parser stack can become before a stack overflow occurs. Define the macro with a value that is an integer. This value is the maximum number of tokens that can be shifted (and not reduced) before overflow. It must be a constant expression whose value is known at compile time.

The stack space allowed is not necessarily allocated. If you specify a large value for YYMAXDEPTH, the parser actually allocates a small stack at first, and then makes it bigger by stages as needed. This increasing allocation happens automatically and silently. Therefore, you do not need to make YYMAXDEPTH painfully small merely to save space for ordinary inputs that do not need much stack.

The default value of YYMAXDEPTH, if you do not define it, is 10000.

You can control how much stack is allocated initially by defining the macro YYINITDEPTH. This value too must be a compile-time constant integer. The default is 200.

Node:Error Recovery, Next:Context Dependency, Previous:Algorithm, Up:Top

Error Recovery

It is not usually acceptable to have a program terminate on a parse error. For example, a compiler should recover sufficiently to parse the rest of the input file and check it for errors; a calculator should accept another expression.

In a simple interactive command parser where each input is one line, it may be sufficient to allow yyparse to return 1 on error and have the caller ignore the rest of the input line when that happens (and then call yyparse again). But this is inadequate for a compiler, because it forgets all the syntactic context leading up to the error. A syntax error deep within a function in the compiler input should not cause the compiler to treat the following line like the beginning of a source file.

You can define how to recover from a syntax error by writing rules to recognize the special token error. This is a terminal symbol that is always defined (you need not declare it) and reserved for error handling. The Bison parser generates an error token whenever a syntax error happens; if you have provided a rule to recognize this token in the current context, the parse can continue.

For example:

stmnts:  /* empty string */
        | stmnts '\n'
        | stmnts exp '\n'
        | stmnts error '\n'

The fourth rule in this example says that an error followed by a newline makes a valid addition to any stmnts.

What happens if a syntax error occurs in the middle of an exp? The error recovery rule, interpreted strictly, applies to the precise sequence of a stmnts, an error and a newline. If an error occurs in the middle of an exp, there will probably be some additional tokens and subexpressions on the stack after the last stmnts, and there will be tokens to read before the next newline. So the rule is not applicable in the ordinary way.

But Bison can force the situation to fit the rule, by discarding part of the semantic context and part of the input. First it discards states and objects from the stack until it gets back to a state in which the error token is acceptable. (This means that the subexpressions already parsed are discarded, back to the last complete stmnts.) At this point the error token can be shifted. Then, if the old look-ahead token is not acceptable to be shifted next, the parser reads tokens and discards them until it finds a token which is acceptable. In this example, Bison reads and discards input until the next newline so that the fourth rule can apply.

The choice of error rules in the grammar is a choice of strategies for error recovery. A simple and useful strategy is simply to skip the rest of the current input line or current statement if an error is detected:

stmnt: error ';'  /* on error, skip until ';' is read */

It is also useful to recover to the matching close-delimiter of an opening-delimiter that has already been parsed. Otherwise the close-delimiter will probably appear to be unmatched, and generate another, spurious error message:

primary:  '(' expr ')'
        | '(' error ')'
        ...
        ;

Error recovery strategies are necessarily guesses. When they guess wrong, one syntax error often leads to another. In the above example, the error recovery rule guesses that an error is due to bad input within one stmnt. Suppose that instead a spurious semicolon is inserted in the middle of a valid stmnt. After the error recovery rule recovers from the first error, another syntax error will be found straightaway, since the text following the spurious semicolon is also an invalid stmnt.

To prevent an outpouring of error messages, the parser will output no error message for another syntax error that happens shortly after the first; only after three consecutive input tokens have been successfully shifted will error messages resume.

Note that rules which accept the error token may have actions, just as any other rules can.

You can make error messages resume immediately by using the macro yyerrok in an action. If you do this in the error rule's action, no error messages will be suppressed. This macro requires no arguments; yyerrok; is a valid C statement.

The previous look-ahead token is reanalyzed immediately after an error. If this is unacceptable, then the macro yyclearin may be used to clear this token. Write the statement yyclearin; in the error rule's action.

For example, suppose that on a parse error, an error handling routine is called that advances the input stream to some point where parsing should once again commence. The next symbol returned by the lexical scanner is probably correct. The previous look-ahead token ought to be discarded with yyclearin;.

The macro YYRECOVERING stands for an expression that has the value 1 when the parser is recovering from a syntax error, and 0 the rest of the time. A value of 1 indicates that error messages are currently suppressed for new syntax errors.

Node:Context Dependency, Next:Debugging, Previous:Error Recovery, Up:Top

Handling Context Dependencies

The Bison paradigm is to parse tokens first, then group them into larger syntactic units. In many languages, the meaning of a token is affected by its context. Although this violates the Bison paradigm, certain techniques (known as kludges) may enable you to write Bison parsers for such languages.

  • Semantic Tokens: Token parsing can depend on the semantic context.
  • Lexical Tie-ins: Token parsing can depend on the syntactic context.
  • Tie-in Recovery: Lexical tie-ins have implications for how error recovery rules must be written.

(Actually, "kludge" means any technique that gets its job done but is neither clean nor robust.)

Node:Semantic Tokens, Next:Lexical Tie-ins, Up:Context Dependency

Semantic Info in Token Types

The C language has a context dependency: the way an identifier is used depends on what its current meaning is. For example, consider this:

foo (x);

This looks like a function call statement, but if foo is a typedef name, then this is actually a declaration of x. How can a Bison parser for C decide how to parse this input?

The method used in GNU C is to have two different token types, IDENTIFIER and TYPENAME. When yylex finds an identifier, it looks up the current declaration of the identifier in order to decide which token type to return: TYPENAME if the identifier is declared as a typedef, IDENTIFIER otherwise.

The grammar rules can then express the context dependency by the choice of token type to recognize. IDENTIFIER is accepted as an expression, but TYPENAME is not. TYPENAME can start a declaration, but IDENTIFIER cannot. In contexts where the meaning of the identifier is not significant, such as in declarations that can shadow a typedef name, either TYPENAME or IDENTIFIER is accepted--there is one rule for each of the two token types.

This technique is simple to use if the decision of which kinds of identifiers to allow is made at a place close to where the identifier is parsed. But in C this is not always so: C allows a declaration to redeclare a typedef name provided an explicit type has been specified earlier:

typedef int foo, bar, lose;
static foo (bar);        /* redeclare bar as static variable */
static int foo (lose);   /* redeclare foo as function */

Unfortunately, the name being declared is separated from the declaration construct itself by a complicated syntactic structure--the "declarator".

As a result, part of the Bison parser for C needs to be duplicated, with all the nonterminal names changed: once for parsing a declaration in which a typedef name can be redefined, and once for parsing a declaration in which that can't be done. Here is a part of the duplication, with actions omitted for brevity:

initdcl:
          declarator maybeasm '='
          init
        | declarator maybeasm
        ;

notype_initdcl:
          notype_declarator maybeasm '='
          init
        | notype_declarator maybeasm
        ;

Here initdcl can redeclare a typedef name, but notype_initdcl cannot. The distinction between declarator and notype_declarator is the same sort of thing.

There is some similarity between this technique and a lexical tie-in (described next), in that information which alters the lexical analysis is changed during parsing by other parts of the program. The difference is here the information is global, and is used for other purposes in the program. A true lexical tie-in has a special-purpose flag controlled by the syntactic context.

Node:Lexical Tie-ins, Next:Tie-in Recovery, Previous:Semantic Tokens, Up:Context Dependency

Lexical Tie-ins

One way to handle context-dependency is the lexical tie-in: a flag which is set by Bison actions, whose purpose is to alter the way tokens are parsed.

For example, suppose we have a language vaguely like C, but with a special construct hex (hex-expr). After the keyword hex comes an expression in parentheses in which all integers are hexadecimal. In particular, the token a1b must be treated as an integer rather than as an identifier if it appears in that context. Here is how you can do it:

%{
int hexflag;
%}
%%
...
expr:   IDENTIFIER
        | constant
        | HEX '('
                { hexflag = 1; }
          expr ')'
                { hexflag = 0;
                   $$ = $4; }
        | expr '+' expr
                { $$ = make_sum ($1, $3); }
        ...
        ;

constant:
          INTEGER
        | STRING
        ;

Here we assume that yylex looks at the value of hexflag; when it is nonzero, all integers are parsed in hexadecimal, and tokens starting with letters are parsed as integers if possible.

The declaration of hexflag shown in the C declarations section of the parser file is needed to make it accessible to the actions (see The C Declarations Section). You must also write the code in yylex to obey the flag.

Node:Tie-in Recovery, Previous:Lexical Tie-ins, Up:Context Dependency

Lexical Tie-ins and Error Recovery

Lexical tie-ins make strict demands on any error recovery rules you have. See Error Recovery.

The reason for this is that the purpose of an error recovery rule is to abort the parsing of one construct and resume in some larger construct. For example, in C-like languages, a typical error recovery rule is to skip tokens until the next semicolon, and then start a new statement, like this:

stmt:   expr ';'
        | IF '(' expr ')' stmt { ... }
        ...
        error ';'
                { hexflag = 0; }
        ;

If there is a syntax error in the middle of a hex (expr) construct, this error rule will apply, and then the action for the completed hex (expr) will never run. So hexflag would remain set for the entire rest of the input, or until the next hex keyword, causing identifiers to be misinterpreted as integers.

To avoid this problem the error recovery rule itself clears hexflag.

There may also be an error recovery rule that works within expressions. For example, there could be a rule which applies within parentheses and skips to the close-parenthesis:

expr:   ...
        | '(' expr ')'
                { $$ = $2; }
        | '(' error ')'
        ...

If this rule acts within the hex construct, it is not going to abort that construct (since it applies to an inner level of parentheses within the construct). Therefore, it should not clear the flag: the rest of the hex construct should be parsed with the flag still in effect.

What if there is an error recovery rule which might abort out of the hex construct or might not, depending on circumstances? There is no way you can write the action to determine whether a hex construct is being aborted or not. So if you are using a lexical tie-in, you had better make sure your error recovery rules are not of this kind. Each rule must be such that you can be sure that it always will, or always won't, have to clear the flag.

Node:Debugging, Next:Invocation, Previous:Context Dependency, Up:Top

Debugging Your Parser

If a Bison grammar compiles properly but doesn't do what you want when it runs, the yydebug parser-trace feature can help you figure out why.

To enable compilation of trace facilities, you must define the macro YYDEBUG to a nonzero value when you compile the parser. You could use -DYYDEBUG=1 as a compiler option or you could put #define YYDEBUG 1 in the C declarations section of the grammar file (see The C Declarations Section). Alternatively, use the -t option when you run Bison (see Invoking Bison) or the %debug declaration (see Bison Declaration Summary). We suggest that you always define YYDEBUG so that debugging is always possible.

The trace facility outputs messages with macro calls of the form YYFPRINTF (stderr, format, args) where format and args are the usual printf format and arguments. If you define YYDEBUG to a nonzero value but do not define YYFPRINTF, <stdio.h> is automatically included and YYPRINTF is defined to fprintf.

Once you have compiled the program with trace facilities, the way to request a trace is to store a nonzero value in the variable yydebug. You can do this by making the C code do it (in main, perhaps), or you can alter the value with a C debugger.

Each step taken by the parser when yydebug is nonzero produces a line or two of trace information, written on stderr. The trace messages tell you these things:

  • Each time the parser calls yylex, what kind of token was read.
  • Each time a token is shifted, the depth and complete contents of the state stack (see Parser States).
  • Each time a rule is reduced, which rule it is, and the complete contents of the state stack afterward.

To make sense of this information, it helps to refer to the listing file produced by the Bison -v option (see Invoking Bison). This file shows the meaning of each state in terms of positions in various rules, and also what each state will do with each possible input token. As you read the successive trace messages, you can see that the parser is functioning according to its specification in the listing file. Eventually you will arrive at the place where something undesirable happens, and you will see which parts of the grammar are to blame.

The parser file is a C program and you can use C debuggers on it, but it's not easy to interpret what it is doing. The parser function is a finite-state machine interpreter, and aside from the actions it executes the same code over and over. Only the values of variables show where in the grammar it is working.

The debugging information normally gives the token type of each token read, but not its semantic value. You can optionally define a macro named YYPRINT to provide a way to print the value. If you define YYPRINT, it should take three arguments. The parser will pass a standard I/O stream, the numeric code for the token type, and the token value (from yylval).

Here is an example of YYPRINT suitable for the multi-function calculator (see Declarations for mfcalc):

#define YYPRINT(file, type, value)   yyprint (file, type, value)

static void
yyprint (FILE *file, int type, YYSTYPE value)
{
  if (type == VAR)
    fprintf (file, " %s", value.tptr->name);
  else if (type == NUM)
    fprintf (file, " %d", value.val);
}

Node:Invocation, Next:Table of Symbols, Previous:Debugging, Up:Top

Invoking Bison

The usual way to invoke Bison is as follows:

bison infile

Here infile is the grammar file name, which usually ends in .y. The parser file's name is made by replacing the .y with .tab.c. Thus, the bison foo.y filename yields foo.tab.c, and the bison hack/foo.y filename yields hack/foo.tab.c. It's is also possible, in case you are writing C++ code instead of C in your grammar file, to name it foo.ypp or foo.y++. Then, the output files will take an extention like the given one as input (repectively foo.tab.cpp and foo.tab.c++). This feature takes effect with all options that manipulate filenames like -o or -d.

For example :

bison -d infile.yxx

will produce infile.tab.cxx and infile.tab.hxx. and

bison -d infile.y -o output.c++

will produce output.c++ and outfile.h++.

  • Bison Options: All the options described in detail, in alphabetical order by short options.
  • Environment Variables: Variables which affect Bison execution.
  • Option Cross Key: Alphabetical list of long options.
  • Extension Limitations Under DOS: Bison output files extension differences depending on the DOS/Windows file system flavour used.
  • VMS Invocation: Bison command syntax on VMS.

Node:Bison Options, Next:Environment Variables, Up:Invocation

Bison Options

Bison supports both traditional single-letter options and mnemonic long option names. Long option names are indicated with -- instead of -. Abbreviations for option names are allowed as long as they are unique. When a long option takes an argument, like --file-prefix, connect the option name and the argument with =.

Here is a list of options that can be used with Bison, alphabetized by short option. It is followed by a cross key alphabetized by long option.

Operations modes:

-h
--help
Print a summary of the command-line options to Bison and exit.
-V
--version
Print the version number of Bison and exit.
-y
--yacc
--fixed-output-files
Equivalent to -o y.tab.c; the parser output file is called y.tab.c, and the other outputs are called y.output and y.tab.h. The purpose of this option is to imitate Yacc's output file name conventions. Thus, the following shell script can substitute for Yacc:
bison -y $*

Tuning the parser:

-S file
--skeleton=file
Specify the skeleton to use. You probably don't need this option unless you are developing Bison.
-t
--debug
In the parser file, define the macro YYDEBUG to 1 if it is not already defined, so that the debugging facilities are compiled. See Debugging Your Parser.
--locations
Pretend that %locations was specified. See Decl Summary.
-p prefix
--name-prefix=prefix
Pretend that %name-prefix="prefix" was specified. See Decl Summary.
-l
--no-lines
Don't put any #line preprocessor commands in the parser file. Ordinarily Bison puts them in the parser file so that the C compiler and debuggers will associate errors with your source file, the grammar file. This option causes them to associate errors with the parser file, treating it as an independent source file in its own right.
-n
--no-parser
Pretend that %no-parser was specified. See Decl Summary.
-k
--token-table
Pretend that %token-table was specified. See Decl Summary.

Adjust the output:

-d
--defines
Pretend that %defines was specified, i.e., write an extra output file containing macro definitions for the token type names defined in the grammar and the semantic value type YYSTYPE, as well as a few extern variable declarations. See Decl Summary.
--defines=defines-file
Same as above, but save in the file defines-file.
-b file-prefix
--file-prefix=prefix
Pretend that %verbose was specified, i.e, specify prefix to use for all Bison output file names. See Decl Summary.
-v
--verbose
Pretend that %verbose was specified, i.e, write an extra output file containing verbose descriptions of the grammar and parser. See Decl Summary.
-o filename
--output=filename
Specify the filename for the parser file.

The other output files' names are constructed from filename as described under the -v and -d options.

-g
Output a VCG definition of the LALR(1) grammar automaton computed by Bison. If the grammar file is foo.y, the VCG output file will be foo.vcg.
--graph=graph-file
The behaviour of -graph is the same than -g. The only difference is that it has an optionnal argument which is the name of the output graph filename.

Node:Environment Variables, Next:Option Cross Key, Previous:Bison Options, Up:Invocation

Environment Variables

Here is a list of environment variables which affect the way Bison runs.

BISON_SIMPLE
BISON_HAIRY
Much of the parser generated by Bison is copied verbatim from a file called bison.simple. If Bison cannot find that file, or if you would like to direct Bison to use a different copy, setting the environment variable BISON_SIMPLE to the path of the file will cause Bison to use that copy instead.

When the %semantic_parser declaration is used, Bison copies from a file called bison.hairy instead. The location of this file can also be specified or overridden in a similar fashion, with the BISON_HAIRY environment variable.

Node:Option Cross Key, Next:Extension Limitations Under DOS, Previous:Environment Variables, Up:Invocation

Option Cross Key

Here is a list of options, alphabetized by long option, to help you find the corresponding short option.

Node:Extension Limitations Under DOS, Next:VMS Invocation, Previous:Option Cross Key, Up:Invocation

Extension Limitations under DOS

On DOS/Windows 9X systems the file name extensions of the output files, like .tab.c, that may be used depend on the file system in use. The plain DOS file system has limited file name length, does not allow the use of a set of certain illicit characters and does not allow more than a single dot in the file name.

The DJGPP port of bison will detect at runtime if (LFN) long file name support is available or not. LFN support will be available in a DOS session under Windows 9X and successors. Windows NT 4.0 needs a special LFN driver (ntlfn08b.zip) or later available at any simtelnet mirror in the /v2misc dir) for proper LFN support in a DOS session. If LFN support is available the DJGPP port of bison will use the standard POSIX file name extensions of the output files. If LFN support is not available, then the DJGPP port of bison will use DOS specific file name extensions.

This table summarizes the used extensions:

LFN extension (Win9X) | SFN extension (plain DOS)
.tab.c | _tab.c
.tab.h | _tab.h
.tab.cpp | _tab.cpp
.tab.hpp | _tab.hpp
.output | .out
.stype.h | .sth
.guard.c | .guc

Node:VMS Invocation, Previous:Extension Limitations Under DOS, Up:Invocation

Invoking Bison under VMS

The command line syntax for Bison on VMS is a variant of the usual Bison command syntax--adapted to fit VMS conventions.

To find the VMS equivalent for any Bison option, start with the long option, and substitute a / for the leading --, and substitute a _ for each - in the name of the long option. For example, the following invocation under VMS:

bison /debug/name_prefix=bar foo.y

is equivalent to the following command under POSIX.

bison --debug --name-prefix=bar foo.y

The VMS file system does not permit filenames such as foo.tab.c. In the above example, the output file would instead be named foo_tab.c.

Node:Table of Symbols, Next:Glossary, Previous:Invocation, Up:Top

Bison Symbols

error
A token name reserved for error recovery. This token may be used in grammar rules so as to allow the Bison parser to recognize an error in the grammar without halting the process. In effect, a sentence containing an error may be recognized as valid. On a parse error, the token error becomes the current look-ahead token. Actions corresponding to error are then executed, and the look-ahead token is reset to the token that originally caused the violation. See Error Recovery.
YYABORT
Macro to pretend that an unrecoverable syntax error has occurred, by making yyparse return 1 immediately. The error reporting function yyerror is not called. See The Parser Function yyparse.
YYACCEPT
Macro to pretend that a complete utterance of the language has been read, by making yyparse return 0 immediately. See The Parser Function yyparse.
YYBACKUP
Macro to discard a value from the parser stack and fake a look-ahead token. See Special Features for Use in Actions.
YYERROR
Macro to pretend that a syntax error has just been detected: call yyerror and then perform normal error recovery if possible (see Error Recovery), or (if recovery is impossible) make yyparse return 1. See Error Recovery.
YYERROR_VERBOSE
Macro that you define with #define in the Bison declarations section to request verbose, specific error message strings when yyerror is called.
YYINITDEPTH
Macro for specifying the initial size of the parser stack. See Stack Overflow.
YYLEX_PARAM
Macro for specifying an extra argument (or list of extra arguments) for yyparse to pass to yylex. See Calling Conventions for Pure Parsers.
YYLTYPE
Macro for the data type of yylloc; a structure with four members. See Data Types of Locations.
yyltype
Default value for YYLTYPE.
YYMAXDEPTH
Macro for specifying the maximum size of the parser stack. See Stack Overflow.
YYPARSE_PARAM
Macro for specifying the name of a parameter that yyparse should accept. See Calling Conventions for Pure Parsers.
YYRECOVERING
Macro whose value indicates whether the parser is recovering from a syntax error. See Special Features for Use in Actions.
YYSTACK_USE_ALLOCA
Macro used to control the use of alloca. If defined to 0, the parser will not use alloca but malloc when trying to grow its internal stacks. Do not define YYSTACK_USE_ALLOCA to anything else.
YYSTYPE
Macro for the data type of semantic values; int by default. See Data Types of Semantic Values.
yychar
External integer variable that contains the integer value of the current look-ahead token. (In a pure parser, it is a local variable within yyparse.) Error-recovery rule actions may examine this variable. See Special Features for Use in Actions.
yyclearin
Macro used in error-recovery rule actions. It clears the previous look-ahead token. See Error Recovery.
yydebug
External integer variable set to zero by default. If yydebug is given a nonzero value, the parser will output information on input symbols and parser action. See Debugging Your Parser.
yyerrok
Macro to cause parser to recover immediately to its normal mode after a parse error. See Error Recovery.
yyerror
User-supplied function to be called by yyparse on error. The function receives one argument, a pointer to a character string containing an error message. See The Error Reporting Function yyerror.
yylex
User-supplied lexical analyzer function, called with no arguments to get the next token. See The Lexical Analyzer Function yylex.
yylval
External variable in which yylex should place the semantic value associated with a token. (In a pure parser, it is a local variable within yyparse, and its address is passed to yylex.) See Semantic Values of Tokens.
yylloc
External variable in which yylex should place the line and column numbers associated with a token. (In a pure parser, it is a local variable within yyparse, and its address is passed to yylex.) You can ignore this variable if you don't use the @ feature in the grammar actions. See Textual Positions of Tokens.
yynerrs
Global variable which Bison increments each time there is a parse error. (In a pure parser, it is a local variable within yyparse.) See The Error Reporting Function yyerror.
yyparse
The parser function produced by Bison; call this function to start parsing. See The Parser Function yyparse.
%debug
Equip the parser for debugging. See Decl Summary.
%defines
Bison declaration to create a header file meant for the scanner. See Decl Summary.
%file-prefix="prefix"
Bison declaration to set tge prefix of the output files. See Decl Summary.
%left
Bison declaration to assign left associativity to token(s). See Operator Precedence.
%name-prefix="prefix"
Bison declaration to rename the external symbols. See Decl Summary.
%no-lines
Bison declaration to avoid generating #line directives in the parser file. See Decl Summary.
%nonassoc
Bison declaration to assign non-associativity to token(s). See Operator Precedence.
%output="filename"
Bison declaration to set the name of the parser file. See Decl Summary.
%prec
Bison declaration to assign a precedence to a specific rule. See Context-Dependent Precedence.
%pure-parser
Bison declaration to request a pure (reentrant) parser. See A Pure (Reentrant) Parser.
%right
Bison declaration to assign right associativity to token(s). See Operator Precedence.
%start
Bison declaration to specify the start symbol. See The Start-Symbol.
%token
Bison declaration to declare token(s) without specifying precedence. See Token Type Names.
%token-table
Bison declaration to include a token name table in the parser file. See Decl Summary.
%type
Bison declaration to declare nonterminals. See Nonterminal Symbols.
%union
Bison declaration to specify several possible data types for semantic values. See The Collection of Value Types.

These are the punctuation and delimiters used in Bison input:

%%
Delimiter used to separate the grammar rule section from the Bison declarations section or the additional C code section. See The Overall Layout of a Bison Grammar.
%{ %}
All code listed between %{ and %} is copied directly to the output file uninterpreted. Such code forms the "C declarations" section of the input file. See Outline of a Bison Grammar.
/*...*/
Comment delimiters, as in C.
:
Separates a rule's result from its components. See Syntax of Grammar Rules.
;
Terminates a rule. See Syntax of Grammar Rules.
|
Separates alternate rules for the same result nonterminal. See Syntax of Grammar Rules.

Node:Glossary, Next:Copying This Manual, Previous:Table of Symbols, Up:Top

Glossary

Backus-Naur Form (BNF)
Formal method of specifying context-free grammars. BNF was first used in the ALGOL-60 report, 1963. See Languages and Context-Free Grammars.
Context-free grammars
Grammars specified as rules that can be applied regardless of context. Thus, if there is a rule which says that an integer can be used as an expression, integers are allowed anywhere an expression is permitted. See Languages and Context-Free Grammars.
Dynamic allocation
Allocation of memory that occurs during execution, rather than at compile time or on entry to a function.
Empty string
Analogous to the empty set in set theory, the empty string is a character string of length zero.
Finite-state stack machine
A "machine" that has discrete states in which it is said to exist at each instant in time. As input to the machine is processed, the machine moves from state to state as specified by the logic of the machine. In the case of the parser, the input is the language being parsed, and the states correspond to various stages in the grammar rules. See The Bison Parser Algorithm.
Grouping
A language construct that is (in general) grammatically divisible; for example, `expression' or `declaration' in C. See Languages and Context-Free Grammars.
Infix operator
An arithmetic operator that is placed between the operands on which it performs some operation.
Input stream
A continuous flow of data between devices or programs.
Language construct
One of the typical usage schemas of the language. For example, one of the constructs of the C language is the if statement. See Languages and Context-Free Grammars.
Left associativity
Operators having left associativity are analyzed from left to right: a+b+c first computes a+b and then combines with c. See Operator Precedence.
Left recursion
A rule whose result symbol is also its first component symbol; for example, expseq1 : expseq1 ',' exp;. See Recursive Rules.
Left-to-right parsing
Parsing a sentence of a language by analyzing it token by token from left to right. See The Bison Parser Algorithm.
Lexical analyzer (scanner)
A function that reads an input stream and returns tokens one by one. See The Lexical Analyzer Function yylex.
Lexical tie-in
A flag, set by actions in the grammar rules, which alters the way tokens are parsed. See Lexical Tie-ins.
Literal string token
A token which consists of two or more fixed characters. See Symbols.
Look-ahead token
A token already read but not yet shifted. See Look-Ahead Tokens.
LALR(1)
The class of context-free grammars that Bison (like most other parser generators) can handle; a subset of LR(1). See Mysterious Reduce/Reduce Conflicts.
LR(1)
The class of context-free grammars in which at most one token of look-ahead is needed to disambiguate the parsing of any piece of input.
Nonterminal symbol
A grammar symbol standing for a grammatical construct that can be expressed through rules in terms of smaller constructs; in other words, a construct that is not a token. See Symbols.
Parse error
An error encountered during parsing of an input stream due to invalid syntax. See Error Recovery.
Parser
A function that recognizes valid sentences of a language by analyzing the syntax structure of a set of tokens passed to it from a lexical analyzer.
Postfix operator
An arithmetic operator that is placed after the operands upon which it performs some operation.
Reduction
Replacing a string of nonterminals and/or terminals with a single nonterminal, according to a grammar rule. See The Bison Parser Algorithm.
Reentrant
A reentrant subprogram is a subprogram which can be in invoked any number of times in parallel, without interference between the various invocations. See A Pure (Reentrant) Parser.
Reverse polish notation
A language in which all operators are postfix operators.
Right recursion
A rule whose result symbol is also its last component symbol; for example, expseq1: exp ',' expseq1;. See Recursive Rules.
Semantics
In computer languages, the semantics are specified by the actions taken for each instance of the language, i.e., the meaning of each statement. See Defining Language Semantics.
Shift
A parser is said to shift when it makes the choice of analyzing further input from the stream rather than reducing immediately some already-recognized rule. See The Bison Parser Algorithm.
Single-character literal
A single character that is recognized and interpreted as is. See From Formal Rules to Bison Input.
Start symbol
The nonterminal symbol that stands for a complete valid utterance in the language being parsed. The start symbol is usually listed as the first nonterminal symbol in a language specification. See The Start-Symbol.
Symbol table
A data structure where symbol names and associated data are stored during parsing to allow for recognition and use of existing information in repeated uses of a symbol. See Multi-function Calc.
Token
A basic, grammatically indivisible unit of a language. The symbol that describes a token in the grammar is a terminal symbol. The input of the Bison parser is a stream of tokens which comes from the lexical analyzer. See Symbols.
Terminal symbol
A grammar symbol that has no rules in the grammar and therefore is grammatically indivisible. The piece of text it represents is a token. See Languages and Context-Free Grammars.

Node:Copying This Manual, Next:Index, Previous:Glossary, Up:Top

Copying This Manual

  • GNU Free Documentation License: License for copying this manual.

Node:GNU Free Documentation License, Up:Copying This Manual

GNU Free Documentation License

Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Node:Index, Previous:Copying This Manual, Up:Top

Index

  • action: Actions
  • action data types: Action Types
  • action features summary: Action Features
  • actions in mid-rule: Mid-Rule Actions
  • actions, location: Actions and Locations
  • actions, semantic: Semantic Actions
  • additional C code section: C Code
  • algorithm of parser: Algorithm
  • associativity: Why Precedence
  • Backus-Naur form: Language and Grammar
  • Bison declaration summary: Decl Summary
  • Bison declarations: Declarations
  • Bison declarations (introduction): Bison Declarations
  • Bison grammar: Grammar in Bison
  • Bison invocation: Invocation
  • Bison parser: Bison Parser
  • Bison parser algorithm: Algorithm
  • Bison symbols, table of: Table of Symbols
  • Bison utility: Bison Parser
  • BISON_HAIRY: Environment Variables
  • BISON_SIMPLE: Environment Variables
  • BNF: Language and Grammar
  • C code, section for additional: C Code
  • C declarations section: C Declarations
  • C-language interface: Interface
  • calc: Infix Calc
  • calculator, infix notation: Infix Calc
  • calculator, location tracking: Location Tracking Calc
  • calculator, multi-function: Multi-function Calc
  • calculator, simple: RPN Calc
  • character token: Symbols
  • compiling the parser: Rpcalc Compile
  • conflicts: Shift/Reduce
  • conflicts, reduce/reduce: Reduce/Reduce
  • conflicts, suppressing warnings of: Expect Decl
  • context-dependent precedence: Contextual Precedence
  • context-free grammar: Language and Grammar
  • controlling function: Rpcalc Main
  • dangling else: Shift/Reduce
  • data type of locations: Location Type
  • data types in actions: Action Types
  • data types of semantic values: Value Type
  • debugging: Debugging
  • declaration summary: Decl Summary
  • declarations, Bison: Declarations
  • declarations, Bison (introduction): Bison Declarations
  • declarations, C: C Declarations
  • declaring literal string tokens: Token Decl
  • declaring operator precedence: Precedence Decl
  • declaring the start symbol: Start Decl
  • declaring token type names: Token Decl
  • declaring value types: Union Decl
  • declaring value types, nonterminals: Type Decl
  • default action: Actions
  • default data type: Value Type
  • default location type: Location Type
  • default stack limit: Stack Overflow
  • default start symbol: Start Decl
  • defining language semantics: Semantics
  • DOS: Extension Limitations Under DOS
  • else, dangling: Shift/Reduce
  • environment variables: Environment Variables
  • error recovery: Error Recovery
  • error recovery, simple: Simple Error Recovery
  • error reporting function: Error Reporting
  • error reporting routine: Rpcalc Error
  • examples, simple: Examples
  • exercises: Exercises
  • extension limitations under DOS: Extension Limitations Under DOS
  • FDL, GNU Free Documentation License: GNU Free Documentation License
  • file format: Grammar Layout
  • finite-state machine: Parser States
  • formal grammar: Grammar in Bison
  • format of grammar file: Grammar Layout
  • glossary: Glossary
  • grammar file: Grammar Layout
  • grammar rule syntax: Rules
  • grammar rules section: Grammar Rules
  • grammar, Bison: Grammar in Bison
  • grammar, context-free: Language and Grammar
  • grouping, syntactic: Language and Grammar
  • infix notation calculator: Infix Calc
  • interface: Interface
  • introduction: Introduction
  • invoking Bison: Invocation
  • invoking Bison under VMS: VMS Invocation
  • LALR(1): Mystery Conflicts
  • language semantics, defining: Semantics
  • layout of Bison grammar: Grammar Layout
  • left recursion: Recursion
  • lexical analyzer: Lexical
  • lexical analyzer, purpose: Bison Parser
  • lexical analyzer, writing: Rpcalc Lexer
  • lexical tie-in: Lexical Tie-ins
  • literal string token: Symbols
  • literal token: Symbols
  • location: Locations, Locations Overview
  • location actions: Actions and Locations
  • location tracking calculator: Location Tracking Calc
  • look-ahead token: Look-Ahead
  • LR(1): Mystery Conflicts
  • ltcalc: Location Tracking Calc
  • main function in simple example: Rpcalc Main
  • mfcalc: Multi-function Calc
  • mid-rule actions: Mid-Rule Actions
  • multi-function calculator: Multi-function Calc
  • multicharacter literal: Symbols
  • mutual recursion: Recursion
  • nonterminal symbol: Symbols
  • operator precedence: Precedence
  • operator precedence, declaring: Precedence Decl
  • options for invoking Bison: Invocation
  • overflow of parser stack: Stack Overflow
  • parse error: Error Reporting
  • parser: Bison Parser
  • parser stack: Algorithm
  • parser stack overflow: Stack Overflow
  • parser state: Parser States
  • polish notation calculator: RPN Calc
  • position, textual: Locations, Locations Overview
  • precedence declarations: Precedence Decl
  • precedence of operators: Precedence
  • precedence, context-dependent: Contextual Precedence
  • precedence, unary operator: Contextual Precedence
  • preventing warnings about conflicts: Expect Decl
  • pure parser: Pure Decl
  • recovery from errors: Error Recovery
  • recursive rule: Recursion
  • reduce/reduce conflict: Reduce/Reduce
  • reduction: Algorithm
  • reentrant parser: Pure Decl
  • reverse polish notation: RPN Calc
  • right recursion: Recursion
  • rpcalc: RPN Calc
  • rule syntax: Rules
  • rules section for grammar: Grammar Rules
  • running Bison (introduction): Rpcalc Gen
  • semantic actions: Semantic Actions
  • semantic value: Semantic Values
  • semantic value type: Value Type
  • shift/reduce conflicts: Shift/Reduce
  • shifting: Algorithm
  • simple examples: Examples
  • single-character literal: Symbols
  • stack overflow: Stack Overflow
  • stack, parser: Algorithm
  • stages in using Bison: Stages
  • start symbol: Language and Grammar
  • start symbol, declaring: Start Decl
  • state (of parser): Parser States
  • string token: Symbols
  • summary, action features: Action Features
  • summary, Bison declaration: Decl Summary
  • suppressing conflict warnings: Expect Decl
  • symbol: Symbols
  • symbol table example: Mfcalc Symtab
  • symbols (abstract): Language and Grammar
  • symbols in Bison, table of: Table of Symbols
  • syntactic grouping: Language and Grammar
  • syntax error: Error Reporting
  • syntax of grammar rules: Rules
  • terminal symbol: Symbols
  • textual position: Locations, Locations Overview
  • token: Language and Grammar
  • token type: Symbols
  • token type names, declaring: Token Decl
  • tracing the parser: Debugging
  • unary operator precedence: Contextual Precedence
  • using Bison: Stages
  • value type, semantic: Value Type
  • value types, declaring: Union Decl
  • value types, nonterminals, declaring: Type Decl
  • value, semantic: Semantic Values
  • VMS: VMS Invocation
  • warnings, preventing: Expect Decl
  • writing a lexical analyzer: Rpcalc Lexer


GNU cfengine

cfengine reference

Edition 1.6.3 for version 1.6.3

Mark Burgess
Faculty of Engineering, Oslo College, Norway

Table of Contents

  • Command reference
    • acl
      • Access control entries
      • Solaris ACLs
      • DFS ACLs
      • NT ACLs
    • ACL Example
      • ACL Example
    • binservers
    • broadcast
    • control
      • access
      • actionsequence
      • AddClasses
      • AddInstallable
      • BinaryPaddingChar
      • CopyLinks
      • DefaultCopyType
      • DeleteNonUserMail
      • DeleteNonOwnerMail
      • domain
      • DryRun
      • editfilesize
      • ExcludeCopy
      • ExcludeLinks
      • ExpireAfter
      • HomePattern
      • IfElapsed
      • Inform
      • InterfaceName
      • FileExtensions
      • LockDirectory
      • LogDirectory
      • LinkCopies
      • moduledirectory
      • mountpattern
      • netmask
      • NonAlphaNumFiles
      • nfstype
      • RepChar
      • Repository
      • SecureInput
      • SensibleCount
      • SensibleSize
      • ShowActions
      • site/faculty
      • SplayTime
      • Split
      • suspiciousnames
      • sysadm
      • Syslog
      • timezone
      • TimeOut
      • Verbose
      • Warnings
      • WarnNonUserMail
      • WarnNonOwnerMail
    • classes
    • copy
      • Hard links in copying
      • Too many open files
    • defaultroute
    • disks
    • directories
    • disable
    • editfiles
    • files
      • Syntax
      • Recursion
      • Directory permissions
      • home directive
      • Owner and group wildcards
      • Files linkchildren
      • touch
      • create
    • filters
      • Complete filter examples
    • groups/classes
    • homeservers
    • ignore
    • import
    • interfaces
    • links
      • Single links
      • Multiple Links
      • Link Children
      • Relative and absolute links
      • Hard Links
    • mailserver
    • miscmounts
    • mountables
    • processes
    • required
    • resolve
    • shellcommands
    • tidy
    • unmount
  • Cfengine script gallery
    • User scripts for tidying old files
    • Controlled opening of files for friends and colleagues
    • Root script for emergency disk clearing
    • Script for making links
    • Ftp server
  • Problem solving, bugs, FAQs and tips
    • `cf.preconf' bootstrap file
    • `cfrc' resource file
    • Problems with compilation and installation
    • Bug reports and suggestions
    • FAQs and Tips
      • General
      • AIX
      • BSDI
      • HPUX
      • IRIX
      • LINUX
      • OSF
      • SUNOS (4.1.*)
      • SOLARIS 2
      • FreeBSD
  • Using the help scripts
    • cfwrap
    • cfmail
  • Example configuration files
    • cfengine.conf
    • cf.groups
    • cf.main
    • cf.site
    • cf.motd
    • cf.users
    • cf.solaris
    • cf.linux
    • cf.freebsd / cf.netbsd
    • cfd.conf
  • Runtime Options
  • Cfengine network protocol specs
  • Variable Index
  • Concept Index
  • FAQ Index

Command reference

In this section you will find each facet of a cfengine program listed together with an appropriate explanation. The commands are presented in alphabetical order for ease of lookup. Use this section in conjunction with the example program See section Example configuration files.

acl

   acl:

      class::

         { acl-alias

         action
         }

Cfengine's ACL feature is a common interface for managing filesystem access control lists (ACLs). An access control list is an extended file permission. It allows you to open or close a file to a named list of users (without having to create a group for those users); similarly, it allows you to open or close a file for a list of groups. Several operating systems have access control lists, but each typically has a different syntax and different user interface to this facility, making it very awkward to use. This part of a cfengine configuration simplifies the management of ACLs by providing a more convenient user interface for controlling them and--as far as possible--a common syntax.

An ACL may, by its very nature, contain a lot of information. Normally you would set ACLs in a files command, See section files, or a copy command, See section copy. It would be too cumbersome to repeat all of the information in every command in your configuration, so cfengine simplifies this by first associating an alias together with a complex list of ACL information. This alias is then used to represent the whole bundle of ACL entries in a files or copy command. The form of an ACL is similar to the form of an editfiles command. It is a bundle of information concerning a file's permissions.

 { acl-alias

  method:overwrite/append
  fstype:posix/solaris/dfs/afs/hpux/nt

  acl_type:user/group:permissions
  acl_type:user/group:permissions
  ...
 }

The name acl-alias can be any identifier containing alphanumeric characters and underscores. This is what you will use to refer to the ACL entries in practice. The method entry tells cfengine how to interpret the entries: should a file's ACLs be overwritten or only adjusted? Since the filesystems from different developers all use different models for ACLs, you must also tell cfengine what kind of filesystem the file resides on. Currently only solaris and DCE/DFS ACLs are implemented.

NOTE: if you set both file permissions and ACLs the file permissions override the ACLs.

Access control entries

An access control list is build of any number of individual access control entries (ACEs). The ACEs has the following general syntax:

    acl_type:user/group:permissions

The user or group is sometimes referred to as a key.

For an explanation of ACL types and their use, refer to your local manual page. However, note that for each type of filesystem, there are certain entries which must exist in an ACL. If you are creating a new ACL from scratch, you must specify these. For example, in solaris ACLs you must have entries for user, group and other. Under DFS you need what DFS calls a user_obj, group_obj and an other_obj, and in some cases mask_obj. In cfengine syntax these are called user:*:, other:*: and mask:*:, as described below. If you are appending to an existing entry, you do not have to re-specify these unless you want to change them.

Cfengine can overwrite (replace) or append to one or more ACL entries.

overwrite
method:overwrite is the default. This sets the ACL according to the specified entries which follow. The existing ACL will be overwritten completely.
append
method:append adds or modifies one or more specified ACL entries. If an entry already exists for the specified type and user/group, the specified permission bits will be added to the old permissions. If there is no ACL entry for the given type and user/group, a new entry will be appended.

If the new ACL exactly matches the existing ACL, the ACL is not replaced.

The individual bits in an ACE may be either added subtracted or set equal to a specified mask. The `+' symbol means add, the `-' symbol subtract and `=' means set equal to. Here are some examples:

  acltype:id/*:mask

  user:mark:+rx,-w
  user:ds:=r
  user:jacobs:noaccess
  user:forgiven:default

  user:*:rw
  group:*:r
  other:*:r

The keyword noaccess means set all access bits to zero for that user, i.e. remove all permissions. The keyword default means remove the named user from the access crontrol list altogether, so that the default permissions apply. A star/asterisk in the centre field indicates that the user or group ID is implicitly specified as of the owner of the file, or that no ID is applicable at all (as is the case for `other').

Solaris ACLs

Under Solaris, the ACL type can be one of the following:

        user
        group
        mask
        other
        default_user
        default_group
        default_mask
        default_other

A user or group can be specified to the user, group, default_user and default_group types. Solaris ACL permissions are the normal UNIX permissions bits `rwx', where:

        r - Grants read privileges.
        w - Grants write privileges.
        x - Grants execute privileges.

DFS ACLs

In DCE, the ACL type can be one of the following:

        other
        mask
        any
        unauthenticated
        user
        group
        foreign_other
        foreign_user
        foreign_group

The user, group, foreign_user and foreign_group types require that you specify a user or group. The DCE documentation refers to types user_obj, group_obj and so on. In the cfengine implementation, the ugly `_obj' suffix has been dropped to make these more in keeping with the POSIX names. user_obj::, is equivalent to user:*: is cfengine. The star/asterisk implies that the ACL applies to the owner of the file object.

DFS permissions are comprised of the bits `crwxid', where:

        c - Grants control privileges, to modify an acl.
        r - Grants read  privileges.
        w - Grants write privileges.
        x - Grants execute privileges.
        i - Grants insert privileges.
        d - Grants delete privileges.

See the DCE/DFS documentation for more information about this.

It is not possible to set ACLs in foreign cells currently using cfengine, but you can still have all of your ACL definitions in the same file. You must however arrange for the file to be executed on the server for the cell concerned. Note also that you must perform a DCE login (normally as user `cell_admin') in order to set ACLs on files which are not owned by the owner of the cfengine-process. This is because you must have a valid security ticket.

NT ACLs

NT ACEs are written as follows:

       acl_type:user/group:permissions:accesstype

The actual change consists of the extra field containing the access type. A star/asterisk in the field for user/group would normally imply that the ACL applies to the owner of the file object. However this functionality is as of today not yet implemented.

In NT, the ACL type can be one of the following:

           user
           group

Both types require that you specify the name of a user or a group.

NT permissions are comprised of the bits `rwxdpo', where:

    r - Read privileges
    w - Write privileges
    x - Execute privileges
    d - Delete privileges
    p - Privileges to change the permissions on the file
    o - Privileges to take ownership of the file

In addition to any combination of these bits, the word noaccess or default can be used as explained in the previous section. NT comes with some standard, predefined permissions. The standards are only a predefined combination of the different bits specified above and are provided with cfengine as well. You can use the standards by setting the permission to read, change or all. The bit implementation of each standard is as on NT:

           read   - rx
           change - rwxd
           all    - rwxdpo

where the bits follow the earlier definition. The keywords mentioned above can only be used alone, and not in combination with `+', `-', `=' and/or other permission bits.

NT defines several different access types, of which only two are used in connection with the ACL type that is implemented in cfengine for NT. The access type can be one of the following:

           allowed
           denied

Intuitively, allowed access grants the specified permissions to the user, whilst denied denies the user the specified permissions. If no access type is specified, the default is allowed. This enables cfengine's behaviour as on UNIX systems without any changes to the configuration file. If the permissions noaccess or default is used, the access type will be irrelevant.

ACL Example

Here is an example of a configuration file for an NT ACL:

control:
        actionsequence = ( files )
        domain = ( iu.hioslo.no )

files:
        $(HOME)/tt    acl=acl_alias1    action=fixall

acl:
        { acl_alias1

        method:overwrite
        fstype:nt

        user:gustafb:rwx:allowed
        user:mark:all:allowed
        user:toreo:read:allowed
        user:torej:default:allowed
        user:ds2:+rwx:allowed

        group:dummy:all:denied
        group:iu:read:allowed
        group:root:all:allowed
        group:guest:dpo:denied
        }

ACL Example

Here is an example of a configuration file for one Solaris ACL and one DCE/DFS ACL:

control:
        actionsequence = ( files )
        domain = ( iu.hioslo.no )

files:
        $(HOME)/tt    acl=acl_alias1    action=fixall
        /:/bigfile    acl=acl_alias2    action=fixall

acl:
        { acl_alias1

        method:overwrite
        fstype:posix

        user:*:rwx
        user:mark:=rwx
        user:sowille:=rx
        user:toreo:=rx
        user:torej:default
        user:ds2:+rwx
        group:*:rx
        group:iu:r
        group:root:x
        mask:*:rx
        other:*:rx

        default_user:*:=rw
        default_user:mark:+rwx
        default_user:ds:=rwx
        default_group::=r
        default_group:iu:+r
        default_mask::w
        default_other::rwx
        }

        { acl_alias2

        method:overwrite
        fstype:dfs

        user:*:rwxcid
        group:*:rxd
        other:*:wxir
        mask:*:rxw
        user:/.../iu.hioslo.no/cell_admin:rc
        group:/.../iu.hioslo.no/acct-admin:rwxcid
        user:/.../iu.hioslo.no/root:rx
        }

binservers

The binservers declaration need only be used if you are using cfengine's model for mounting NFS filesystems. This declaration informs hosts of which other hosts on the network possess filesystems containing software (binary files) which client hosts should mount. This includes resources like programs in /usr/local and so on. A host may have several binary servers, since there may be several machines to which disks are physically attached. In most cases, on a well organized network, there will be only one architecture server per UNIX platform type, for instance a SunOS server, an ULTRIX server and so on.

Binary servers are defined as follows:

binservers:

   physics.sun4::   sunserver sunserver2
   physics.linux::  linuxserver

The meaning of this declaration is the following. All hosts of type sun4 which are members of the group physics should mount any binaries declared in the mountables resource list which belong to hosts sunserver or sunserver2. Similarly all linux machines should mount binary filesystems in the mountables list from linuxserver.

Cfengine knows the difference between binaries and home directories in the mountables list, because home directories match the pattern given by homepattern. See section HomePattern. See section homeservers.

Note that every host is a binary server for itself, so that the first binary server (and that with highest priority) is always the current host. This ensures that local filesystems are always used in preference to NFS mounted filesystems. This is only relevant in connection with the variable $(binserver).

broadcast

This information is used to configure the network interface for each host.

Every local area network has a convention for determining which internet address is used for broadcast requests. Normally this is an address of the form aaa.bbb.ccc.255 or aaa.bbb.ccc.0. The difference between these two forms is whether all of the bits in the last number are ones or zeroes respectively. You must find out which convention is used at your establishment and tell cfengine using a declaration of the form:

broadcast:

  any::

     ones     # or zeros, or zeroes

In most cases you can use the generic class any, since all of the hosts on the same subnet have to use the same convention. If your configuration file encompasses several different subnets with different conventions then you will need to use a more specific.

Cfengine computes the actual value of the broadcast address using the value specified above and the netmask See section netmask.

control

The fundamental piece of any cfengine script or configuration file is the control section. If you omit this part of a cfengine script, it will not do anything! The control section is used to define certain variables, set default values and define the order in which the various actions you have defined will be carried out. Because cfengine is a declarative or descriptive language, the order in which actions appear in the file does not necessarily reflect the order in which they are executed. The syntax of declarations here is:

  control:

     classes::

        variable = ( list or value )

The control section is a sequence of declarations which looks something like the following example:

control:

  site     = ( univ )
  domain   = ( univ.edu )
  sysadm   = ( admin@computing.univ.edu )
  netmask  = ( 255.255.252.0 )
  timezone = ( EDT )
  nfstype  = ( nfs )

  sensiblesize  = ( 1000 )
  sensiblecount = ( 2 )
  editfilesize  = ( 4000 )

  actionsequence =
     (
     links.some
     mountall
     links.others
     files
     )

  myvariable = ( something )
  mymacro    = ( somethingelse )

Parentheses are required when making a declaring information in cfengine.

The meaning of each of these lines is described below.

access

The access list is a list of users who are to be allowed to execute a cfengine program. If the list does not exist then all users are allowed to run a program.

   access = ( user1 user2 ...  )

The list may consist of either numerical user identifiers or valid usernames from the password database. For example:

   access = ( mark aurora 22 456 )

would restrict a script to users mark, aurora and user id 22 and 456.

actionsequence

The action sequence determines the order in which collective actions are carried out. Here is an example containing the full list of possibilities:

   actionsequence =
      (
      mountall               # mount filesystems in fstab
      mountinfo              # scan mounted filesystems
      checktimezone          # check timezone
      netconfig              # check net interface config
      resolve                # check resolver setup
      unmount                # unmount any filesystems
      shellcommands          # execute shell commands
      editfiles              # edit files
      addmounts              # add new filesystems to system
      directories            # make any directories
      links                  # check and maintain links (single and child)
      simplelinks            # check only single links (separate from childlinks)
      childlinks             # check only childlinks (separate from singlelinks)
      mailcheck              # check mailserver
      mountall               # (again)
      required               # check required filesystems
      tidy                   # tidy files
      disable                # disable files
      files                  # check file permissions
      copy                   # make a copy/image of a master file
      processes              # signal / check processes
      module:name            # execute a user-defined module
      )

Here is a more complete description of the meaning of these keywords.

addmounts
causes cfengine to compute which NFS filesystems are missing from the current host and add them. This includes editing the filesystem table, creating the mount-directory, if required. This command relies on information provided by mountinfo, so it should normally only be called after mountinfo. If the filesystem already appears to be in the filesystem table, a warning is issued.
checktimezone
runs a check on the timezone defined for the shell running cfengine.
directories
executes all the commands defined under the directories section of the program. It builds new directories.
disable
executes all the commands defined under the disable section of the program.
editfiles
executes all the commands defined under the editfiles section of the program.
files
executes all the commands defined under the files section of the program.
links
executes all the commands defined under the links section of the program. Here one can also write singlelinks which checks only single (not multiply linked) objects, or childlinks which checks the remainder (multiply linked) objects. In this way one can separate these two actions if required, though normally this is not necessary.
mailcheck
tests for the presence of the NFS-mounted mail spooling directory on the current host. The name of the mail spool directory is defined in the mailserver section of the cfengine program. If the current host is the same as the mailserver (the host which has the physical spool directory disk) nothing is done. Otherwise the filesystem table is edited so as to include the mail directory.
module
Normally cfengine's ability to detect the systems condition is limited to what it is able to determine while excuting predefined actions. Classes may be switched on as a result of actions cfengine takes to correct a problem. To increase the flexibility of cfengine, a mechanism has been introduced in version 1.5 which allows you to include a module of your own making in order to define or undefine a number of classes. The syntax
  module:mytests.class1.class2.class3

  "module:mytests.class1.class2.class3 arg1 arg2 .."
declares a user defined module which can potentially set the classes class1 etc. Classes returned by the module must be declared so that cfengine knows to pay attention to rules which use these classes when parsing. Note might actually be preferable to define classes returned by modules under AddInstallables which is equivalent. If arguments are passed to the module, the whole string must be quoted like a shellcommand. @xref{Writing plugin modules,Writing plugin modules,Writing plugin modules,cfengine-Tutorial}. Whether or not these classes become set or not depends on the behaviour of your module. The classes continue to apply for all actions which occur after the module's execution. The module must be owned by the user executing cfengine or root (for security reasons), it must be named `module:module-name' and must lie in a special directory, See section moduledirectory.
mountall
mounts all filesystems defined in the hosts filesystem table. This causes new NFS filesystems added by addmounts and mailcheck to be actually mounted. This should probably be called both before mountinfo and after addmounts etc. A short timeout is placed on this operation to avoid hanging RPC connections when parsing NFS mounted file systems.
mountinfo
builds internal information about which filesystems are presently mounted on the current host. Cfengine assumes that required-filesystems which are not found need to be mounted. A short timeout is placed on this operation to avoid hanging RPC connections when parsing NFS mounted file systems. If this times out, no further mount operations are considered reliable and are summarily cancelled.
netconfig
checks the netmask, hostname, IP address and broadcast address for the current host. The correct values for the netmask and broadcast address are set if there is an error. The defaultroute is also added to the static routing table. This does not apply to DHCP clients.
required
executes all the commands defined under the required section of the program. It checks for the absence of important NFS resources.
resolve
checks and corrects the DNS domain name and the order of nameservers in the file `/etc/resolv.conf'.
shellcommands
executes all the commands defined under the shellcommands section of the program.
tidy
executes all the commands defined under the tidy section of the program.
unmount
executes all the commands defined under the unmount section of the program. The filesystem table is edited so as to remove the unwanted filesystems and the unmount operation is executed.
processes
executes commands defined under the processes section of the program.

Under normal circumstances this coarse ordering is enough to suit most purposes. In some cases you might want to, say, only perform half the link operations before mounting filesystems and then, say, perform the remainder. You can do this (and similar things) by using the idea of defining and undefining classes. @xref{Defining classes,Defining classes,Defining classes,cfengine-Tutorial}.

The syntax

actionsequence =
   (
   links.firstpass.include
   ...
   links.secondpass
   )

means that cfengine first executes links with the classes firstpass and include defined. Later it executes links with secondpass defined. You can use this method of adding classes to distinguish more finely the flow of control in programs.

A note about style: if you define and undefine lots of classes to do what you want to do, you might stop and ask yourself if your groups are defined as well as they should be. See section groups/classes. Programming in cfengine is about doing a lot for only a little writing. If you find yourself writing a lot, you are probably not going about things in the right way.

AddClasses

   AddClasses  = ( list of identifiers )

The AddClasses directive is used to define a list of class attributes for the current host. Normally only the hard classes defined by the system are `true' for a given host. It is convenient though to be able to define classes of your own to label certain actions, mainly so that they can later be excluded so as to cut short or filter out certain actions. This can be done in two ways. See section actionsequence.

To define a list of classes for the current session, you write:

AddClasses = ( exclude shortversion )

This is equivalent to (though more permanent than) defining classes on the command line with the -D option. You can now use these to qualify actions. For example

  any.exclude::
      ...

Under normal circumstances exclude is always true -- because you have defined it to be so, but you can undefine it in two ways so as to prevent the action from being carried out. One way is to undefine a class on the command line when you invoke cfengine:

host#  cfengine -N exclude

or

host#  cfengine -N exclude.shortversion

host#  cfengine -N a.b.c.d

These commands run cfengine with the named classes undefined. That means that actions labelled with these classes are excluded during that run.

Another way to restrict classes is to add a list of classes to be undefined in the actionsequence. See next section.

AddInstallable

   AddInstallable  = ( list of identifiers )

Some actions in your cfengine program will be labelled by classes which only become defined at run time using a define= option. Cfengine is not always able to see these classes until it meets them and tries to save space by only loading actions for classes which is believes will become defined at some point in the program. This can lead to some actions being missed if the action is parsed before the place where the class gets switched on, since cfengine is a one-pass interpreter,. To help cfengine determine classes which might become defined during a run, you can declare them in this list. It does no harm to declare classes here anyway. Here is an example where you need to declare a class because of the ordering of the actions.

control:

    AddInstallable  = ( myclass )

files:

   myclass::

     /tmp/test mode=644 action=fixall

copy:

     /tmp/foo dest=/tmp/test define=myclass

If we remove the declaration, then when cfengine meets the files command, it skips it because it knows nothing about the class `myclass'---when the copy command follows, it is too late. Remember that imported files are always parsed after the main program so definitions made in imported files always come later than things in the main program.

BinaryPaddingChar

BinaryPaddingChar = ( \0 )

This specifies the type of character used to pad strings of unequal length in editfiles during binary editing. The default value is the space character, since this is normally used to edit filenames or text messages within program code.

CopyLinks

This list is used to define a global list of names or patterns which are to be copied rather than linked symbolically. For example

CopyLinks = ( *.config )

The same facility can be specified for each individual link operation using the copy option See section links. Copying is performed using a file age comparison.

Note that all entries defined under a specified class are valid only as long as that class is defined. For instance

  class::

      CopyLinks = ( pattern )

would define a pattern which was only valid when class is defined.

DefaultCopyType

This parameter determines the default form of copying for all copy operations parsed after this variable. The legal values are ctime (intial default), mtime, checksum and binary. e.g.

 DefaultCopyType = ( mtime )

DeleteNonUserMail

If this parameter is set to true, cfengine will delete mail files on mailservers which do not have a name belonging to a known user id. This does not include lock files.

DeleteNonOwnerMail

If this parameter is set to true, cfengine will delete files on mailservers whose names do not correspond to a known user name, but might be owned by a known user.

domain

  domain = ( domain name )

This variable defines the domainname for your site. You must define it here, because your system might not know its domainname when you run cfengine for the first time. The domainname can be used as a cfengine variable subsequently by referring to $(domain). The domainname variable is used by the action resolve. The domain is also used implicitly by other matching routines. You should define the domain as early as possible in your configuration file so as to avoid problems, especially if you have the strange practice of naming hosts with their fully qualified host names since groups which use fully qualified names can fail to be defined if cfengine is not able to figure out the domain name.

DryRun

  DryRun = ( on/off )

This variable has the same effect as the command line options --dry-run or -n. It tells cfengine to only report what it should do without actually doing it.

 classes::

   DryRun = ( on )

editfilesize

   EditfileSize  = ( size )

This variable is used by cfengine every time it becomes necessary to edit a file. Since file editing applies only to text files, the files are probably going to be relatively small in most cases. Asking to edit a very large (perhaps binary) file could therefore be the result of an error.

A check is therefore made as a security feature. Cfengine will refuse to edit a file which is larger than the value of editfilesize in bytes. This is to prevent possible accidents from occurring. The default value for this variable is 10000 bytes. If you don't like this feature, simply set the value to be a very large number or to zero. If the value is zero, cfengine will ignore it.

ExcludeCopy

This list is used to define a global list of names or patterns which are to be excluded from copy operations. For example

 ExcludeCopy = ( *~ *% core )

The same facility can be specified for each individual link operation using the exclude option See section copy.

Note that all entries defined under a specified class are valid only as long as that class is defined. For instance

  class::

      ExcludeCopy = ( pattern )

would define a pattern which was only valid when class is defined.

ExcludeLinks

This list is used to define a global list of names or patterns which are to be excluded from linking operations. For example

 ExcludeLinks = ( *~ *% core )

The same facility can be specified for each individual link operation using the exclude option See section links.

Note that all entries defined under a specified class are valid only as long as that class is defined. For instance

  class::

      ExcludeLinks = ( pattern )

would define a pattern which was only valid when class is defined.

ExpireAfter

This parameter controls the global value of the ExpireAfter parameter. @xref{Spamming and security,Spamming and security,Spamming and security,cfengine-Tutorial}. This parameter controls the maximum time in minutes which a cfengine action is allowed to live. After this time cfengine will try to kill the cfengine which seems to have hung and attempt to restart the action.

 ExpireAfter = ( time-in-minutes )

This parameter may also be set per action in the action sequence by appending a pseudo-class called ExpireAftertime. For instance,

 actionsequence = ( copy.ExpireAfter15 )

sets the expiry time parameter to 15 minutes for this copy command.

HomePattern

   HomePattern  = ( list of wildcards )

The homepattern variable is used by the cfengine model for mounting nfs filesystems. @xref{NFS resources,NFS resources,NFS resources,cfengine-Tutorial}. It is also used in the evaluation of the pseudo variable home, See section files, section tidy.

homepattern is in fact a list and is used like a wildcard or pattern to determine which filesystems in the list of mountables are home directories. See section mountables. This relies on your sticking to a rigid naming convention as described in the first reference above.

For example, you might wish to mount (or locate directly if you are not using a separate partition for home directories) your home directories under mountpattern in directories u1, u2 and so on. In this case you would define homepattern to match these numbers:

homepattern = ( u? )

Cfengine now regards any directory matching $(mountpattern)/u? as being a user login directory.

Suppose you want to create mount home directories under $(mountpattern)/home and make subdirectories for staff and students. Then you would be tempted to write:

 HomePattern = ( home/staff home/students )

Unfortunately this is not presently possible. (This is, in principle, a bug which should be fixed in the future.) What you can do instead is to achieve the same this as follows:

 MountPattern = ( /$(site)/$(host) /$(site)/$(host)/home )
 HomePattern = ( staff students )

IfElapsed

This parameter controls the global value of the IfElapsed parameter, @xref{Spamming and security,Spamming and security,Spamming and security,cfengine-Tutorial}. This parameter controls the minimum time which must have elapsed for an action in the action sequence before which it will be executed again.

 IfElapsed = ( time-in-minutes )

This parameter may also be set per action in the action sequence by appending a pseudo-class called IfElapsedtime. For instance,

 ActionSequence = ( copy.IfElapsed15 )

sets the elapsed time parameter to 15 minutes for this copy command.

Inform

  Inform = ( on/off )

This variable switches on the output level whereby cfengine reports changes it makes during a run. Normally only urgent messages or clear errors are printed. Setting Inform to on makes cfengine report on all actions not explicitly cancelled with a `silent' option. To set this output level one writes:

 classes::

   Inform = ( on )

InterfaceName

If you have an operating system which is installed on some non-standard hardware, you might have to specifically set the name of the network interface. For example:

  control:

    nextstep.some::

       InterfaceName = ( en0 )

    nextstep.others::

       InterfaceName = ( ec0 )

It is only necessary to set the interface name in this fashion if you have an operating system which is running on special hardware. Most users will not need this. The choice set here overrides the system defaults and the choices made in the `cfrc' file, See section `cfrc' resource file.

FileExtensions

This list may be used to define a number of extensions which are regarded as being plain files by the system. As part of the general security checking cfengine will warn about any directories which have names using these extensions. They may be used to conceal directories.

  FileExtensions = ( c o gif jpg html )

LockDirectory

Specify an alternative directory for keeping cfengine's lock data. This defaults to `/var/run/cfengine' or `/etc/cfengine'.

  LockDirectory = ( /etc/cfengine )

LogDirectory

Specify an alternative directory for keeping cfengine's log data. This defaults to `/var/run/cfengine' or `/etc/cfengine'.

  LogDirectory = ( /etc/cfengine )

LinkCopies

This list is used to define a global list of names or patterns which are to be linked symbolically rather than copied. For example

excludelinks = ( *.gif *.jpg )

The same facility can be specified for each individual link operation using the symlink option See section copy.

Note that all entries defined under a specified class are valid only as long as that class is defined. For instance

  class::

      LinkCopies = ( pattern )

would define a pattern which was only valid when class is defined.

moduledirectory

   moduledirectory  = ( directory for plugin modules )

This is the directory where cfengine will look for plug-in modules for the actionsequence, See section actionsequence. Plugin modules may be used to activate classes using special algorithms. @xref{Writing plugin modules,Writing plugin modules,Writing plugin modules,cfengine-Tutorial}.

mountpattern

   mountpattern  = ( mount-point )

The mountpattern list is used by the cfengine model for mounting nfs filesystems. @xref{NFS resources,NFS resources,NFS resources,cfengine-Tutorial}. It is also used in the evaluation of the pseudo variable home, See section files, section tidy.

It is used together with the value of homepattern to locate and identify what filesystems are local to a given host and which are mounted over the network. For this list to make sense you need to stick to a rigid convention for mounting your filesystems under a single naming scheme as described in the section mentioned above. If you follow the recommended naming scheme then you will want to set the value of mountpattern to

mountpattern = ( /$(site)/$(host) )

which implies that cfengine will look for local disk partitions under a unique directory given by the name of the host and site. Any filesystems which are physically located on the current host lie in this directory. All mounted filesystems should lie elsewhere. If you insist on keeping mounted file systems in more than one location, you can make a list like this:

mountpattern = ( /$(site)/users /$(site)/projects )

netmask

   netmask = ( aaa.bbb.ccc.ddd )

The netmask variable defines the partitioning of the subnet addresses on your network. Its value is defined by your network administrator. On most systems it is likely to be 255.255.255.0. This is used to configure the network interface in netconfig. See section actionsequence.

Every host on the internet has its own unique address. The addresses are assigned hierarchically. Each network gets a domain name and can attach something like 65,000 hosts to that network. Since this is usually too many to handle in one go, every such network may be divided up into subnets. The administrator of the network can decide how the division into subnets is made. The decision is a trade-off between having many subnets with few hosts, or many hosts on few subnets. This choice is made by setting the value of a variable called netmask. The netmask looks like an internet address. It takes the form:

   aaa.bbb.ccc.mmm

The first two numbers `aaa.bbb' are the address of the domain. The remainder `ccc.mmm' specifies both the subnet and the hostname. The value of netmask tells all hosts on the network: how many of the bits in the second half label different subnets and how many label different hosts on each of the subnets?

The most common value for the netmask is `255.255.255.0'. It is most helpful to think of the netmask in terms of bits. Each base-10 number between 0-255 represents 8 bits which are either set or not set. Every bit which is set is a network address and every bit which is zero is part of a host address. The first two parts of the address `255.255' always takes these values. If the third number is `255', it means that the domain is divided up into 256 sub networks and then the remaining bits which are zero can be used to give 255 different host addresses on each of the subnets.

If the value had been `255.255.255.254', the network would be divided up into 2^15 subnets, since fifteen of the sixteen bits are one. The remaining bit leaves enough room for two addresses 0 and 1. One of those is reserved for broadcasts to all hosts, the other can be an actual host -- there would only be room for one host per subnet. This is a stupid example of course, the main point with the subnet mask is that it can be used to trade subnets for hosts per subnet. A value of `255.255.254.0' would allow 128 different subnets with 2*256-1 = 511 hosts on each.

We needn't be concerned with the details of the netmask here. Suffice it to say that its value is determined for your entire domain by the network administrator and each host has to be told what the value is.

Each host must also know what convention is used for the broadcast address. This is an address which hosts can send to if they wish to send a message to every other host on their subnet simultaneously. It is used a lot by services like NIS to ask if any hosts are willing to perform a particular service. There are two main conventions for the broadcast address: address zero (all host bits are zero) and the highest address on the subnet (all host bits are ones). The convention can be different on every subnet and it is decided by the network administrator. When you write a cfengine program you just specify the convention used on your subnet and cfengine works out the value of the broadcast address from the netmask and the host address See section broadcast. Cfengine works out the value of the broadcast address using the value of the netmask.

NonAlphaNumFiles

If enabled, this option causes cfengine to detect and disable files which have purely non-alphanumeric filenames, i.e. files which might be accidental or deliberately concealed. The files are then marked with a suffix .cf-nonalpha and are rendered visible.

  NonAlphaNumFiles = ( on )

These files can then be tidied by searching for the suffix. Note that alphanumeric means ascii codes less than 32 and greater than 126.

nfstype

   nfstype = ( nfs-type )

This variable is included only for future expansion. If you do not define this variable, its value defaults to "nfs".

At present cfengine operates only with NFS (the network file system). When cfengine looks for network file systems to mount, it adds lines in the filesystem table (`/etc/fstab',`/etc/checklist' etc.) to try to mount filesystems of type "nfs". In principle you might want to use a completely different system for mounting filesystems over the network, in which case the `mount type' would not be "nfs" but something else.

At the time of writing certain institutions are replacing NFS with AFS (the Andrew filesystem) and DFS (from the distributed computing environment). The use of these filesystems really excludes the need to use the mount protocol at all. In other words if you are using AFS or DFS, you don't need to use cfengine's mounting commands at all.

RepChar

   RepChar  = ( character )

The value of this variable determines the characters which is used by cfengine in creating the unique filenames in the file repository. Normally, its value is set to `_' and each `/' in the path name of the file is changed to `_' and stored in the repository. If you prefer a different character, define it here. Note that the character can be quoted with either single or double quotes in order to encompass spaces etc.

Repository

   Repository  = ( directory )

Defines a special directory where all backup and junk files are collected. Files are assigned a unique filename which identifies the path from which they originate. This affects files saved using disable, copy, links and editfiles @xref{Disabling and the file repository,Disabling and the file repository,Disabling and the file repository,cfengine-Tutorial}.

SecureInput

   SecureInput  = ( on )

If this is set cfengine will not import files which are not owned by the uid running the program, or which are writable by groups or others.

SensibleCount

   SensibleCount  = ( count )

This variable is used by the action required. It defines for cfengine what you consider to be the minimum number of files in a `required' directory. If you declare a directory as being required, cfengine will check to see if it exists. Then, if the directory contains fewer than the value of sensiblecount files, a warning is issued. The default value for this variable is 2.

SensibleSize

   SensibleSize  = ( size )

This variable is used by the action required. It defines for cfengine what you consider to be the minimum size for a `required' file. If you declare a file as being required, cfengine will check to see if the file exists. Of course, the file may exist but be empty, so the size of the file is also checked against this constant. If the file is smaller than the value of sensiblesize a warning is issued. The default value for this variable is 1000 bytes.

ShowActions

   ShowActions  = ( on )

This causes cfengine to produce detailed output of what action is being carried out as part of the prefix information during output. This is intended only for third party tools which collect and parse the cfengine output. It will be of little interest to humans.

site/faculty

  site    = ( sitename )
  faculty = ( facultyname )

This variable defines a convenient name for your site configuration. It is useful for making generic rules later on, because it means for instance that you can define the name of a directory to be

/$(site)/$(host)/local

without having to redefine the rule for a specific site. This is a handy trick for making generic rules in your files which can be imported into a configuration for any site.

faculty is a synonym for site. The two names may be used interchangeably.

SplayTime

  SplayTime = ( time-in-minutes )

This variable is used to set the maximum time over which cfengine will share its load on a server, @xref{Splaying host times,Splaying host times,Splaying host times,cfengine-Tutorial}.

Split

   Split  = ( character )

The value of this variable is used to define the list separator in variables which are expected to be treated as lists. The default value of this variable is the colon `:'. Cfengine treats variables containing this character as lists to be broken up and iterated over in the following cases:

  • in the `to' field of a multiple link action,
  • in the `from' field of a copy action,
  • in the directory field of a tidy action,
  • in the directory field of the files action,
  • in the ignore action.

This typically allows communication with PATH-like environment variables in the shell.

suspiciousnames

  SuspiciousNames = ( .mo lrk3 )

Filenames in this list are treated as suspicious and generate a warning as cfengine scans directories. This might be used to detect hacked systems or concealed programs. Checks are only made in directories which cfengine scans in connection with a command such as files, tidy or copy.

sysadm

   sysadm = ( mail address )

The mail address of your system administrator should be placed here. This is used in two instances. If cfengine is invoked with the option -a, then it simply prints out this value. This is a handy feature for making scripts. See section Using the help scripts.

The administrators mail address is also written into the personal log files which cfengine creates for each user after tidying files, so you should make this an address which users can mail if they have troubles.

Syslog

  Syslog = ( on/off )

This variable activates syslog logging of cfengine output at the `inform' level.

To set this output level one writes:

 classes::

   Syslog = ( on )

timezone

   timezone = ( 3-character timezone )

The timezone variable is a list of character strings which define your local timezone. Normally you will only need a single timezone, but sometimes there are several aliases for a given timezone e.g. MET and CET are synonymous. Currently only the first three characters of this string are checked against the timezone which cfengine manages to glean from the system. If a mismatch is detected a warning message is printed. cfengine does not attempt to configure the timezone. This feature works only as a reminder, since the timezone should really be set once and for all at the time the system is installed. On some systems you can set the timezone by editing a file, a procedure which you can automate with cfengine See section editfiles.

The value of the timezone can be accessed by variable substitution in the usual way. It expands to the first item in your list.

shellcommands:

       "echo ${timezone} | mail ${sysadm}"

TimeOut

  TimeOut = ( 10 )

The default timeout for network connections is 10 seconds. This is too short on some routed networks. It is not permitted to set this variable smaller than 3 seconds or larger than 60 seconds.

Verbose

  Verbose = ( on/off )

This variable switches on the output level whereby cfengine reports everything it does during a run in great detail. Normally only urgent messages or clear errors are printed, See section Inform. This option is almost equivalent to using the --verbose of -v command-line options. The only difference is that system environment reporting information, which is printed prior to parsing, is not shown. To set this output level on selected hosts one writes:

 classes::

   Verbose = ( on )

For related more limited output, See section Inform.

Warnings

  Warnings = ( on/off )

This variable switches on the parser-output level whereby cfengine reports non-fatal warnings. This is equivalent to setting the command line switch --no-warn, or -w. To set this output level on selected hosts one writes:

 classes::

   Warnings = ( on )

WarnNonUserMail

If this parameter is set to true, cfengine will warn about mail files on mailservers which do not have a name belonging to a known user id. This does not include lock files.

WarnNonOwnerMail

If this parameter is set to true, cfengine will warn about files on mailservers whose names do not correspond to a known user name, but might be owned by a known user.

classes

The classes keyword is an alias for groups as of version 1.4.0 of cfengine.

copy

Cfengine copies files between locally mounted filesystems and via the network from registered servers. The copy algorithm avoids race-conditions which can occur due to network and system latencies by copying first to a file called `file.cfnew' on the local filesystem, and then renaming this quickly into place. The aim of this roundabout procedure is to avoid situations where the direct rewriting of a file is interrupted midway, leaving a partially written file to be read by other processes. Cfengine attempts to preserve hard links to non-directory file-objects, but see the caution below.

Caution should be exercised in copying files which change rapidly in size. This can lead to file corruption, if the size changes during copying. Cfengine attempts to prevent this during remote copies.

The syntax summary is:

copy:

   class::

      master-file
                        dest=destination-file
                        mode=mode
                        owner=owner
                        group=group
                        action=silent/fix
                        backup=true/false
                        repository=backup directory
                        stealth=true/on/false/off
                        timestamps=preserve/keep
                        symlink=pattern
                        include=pattern
                        exclude=pattern
                        ignore=pattern
                        filter=filteralias
                        recurse=number/inf/0
                        type=ctime/mtime/checksum/sum/byte/binary
                        linktype=absolute/symbolic/relative/hard/none/copy
                        typecheck=true/on/false/off
                        define=class-list(,:.)
                        elsedefine=class-list(,:.)

                        force=true/on/false/off
                        size=size limits
                        server=server-host
                        secure=true/false
                        purge=true/false
                        syslog=true/on/false/off
                        inform=true/on/false/off

dest
The destination file is the only obligatory item. This must be the name of an object which matches the type of the master object i.e. if the master is a plain file, the destination must also be the explicit name of a plain file. An implicit `copy file to directory' syntax is not allowed. Symbolic links are copied as symbolic links, plain files are copied as plain files and special files are copied as special files. If the master and image are directories then all of the child files which are not directories are copied from source to destination.
mode, owner, group
The file mode, owner and group of the images are specified as in the files function See section files.
action
The action may take the values warn or silent. The default action is fix, i.e. copy files. If warn is specified, only a warning is issued about files which require updating. If silent is given, then cfengine will copy the files but not report the fact.
force
If set to `true', this option causes cfengine to copy files regardless of whether it is up to date.
backup
If the backup option is set to "false", cfengine will not make a backup copy of the file before copying.
repository
This allows a local override of the Repository variable, on an item by item basis. If set to "off" or "none" it cancels the value of a global repository. Copy makes a literal image of the master file at the destination, checking whether the master is newer than the image. If the image needs updating it is copied. Existing files are saved by appending .cfsaved to the filename.
stealth
If set to `on' causes cfengine to preserve atime and mtime on source files during local file copies. File times cannot be preserved on remote copies. This option should normally only be used together with a checksum copy, since preserving atime and mtime implies changing ctime which will force continual copying. This is a weakness in the Unix file system. Ctime cannot be preserved. Before version 1.5.0, there was a typo which made this option active on many file copies.
timestamps
If this is set to `preserve' or `keep', the times of the source files are kept by the destination files during copying. This is like the `p' option of the tar command.
recurse
Specifies the depth of recursion when copying whole file-trees recursively. The value may be a number or the keyword inf. Cfengine crosses device boundaries or mounted filesystems when descending recursively through file trees. To prevent this it is simplest to specify a maximum level of recursion.
symlink
This option may be repeated a number of times to specify the names of files, or wildcards which match files which are to be symbolically linked instead of copied. A global list of patterns can also be defined in the control section of the program See section LinkCopies.
ignore
This works like the global ignore directive but here you may provide a private list of ignorable directories and files. Unlike include, exclude this affects the way cfengine parses directory trees.
include
This option may be repeated a number of times to specify the names of files, or wildcards which match files which are to be included in a copy operation. Specifying one of these automatically excludes everything else except further include patterns. A global list of patterns can also be defined in the control section of the program.
exclude
This option may be repeated a number of times to specify the names of files, or wildcards which match files which are to be excluded from a copy operation. A global list of patterns can also be defined in the control section of the program `excludes' override `includes'. See section ExcludeLinks.
type
Normally cfengine uses the ctime date-stamps on files to determine whether a file needs to be copied: a file is only copied if the master is newer than the copy or if the copy doesn't exist. If the type is set to `checksum' or `sum', then a secure MD5 checksum is used to determine whether the source and destination files are identical. If `byte' or `binary' is specified, a byte by byte comparison is initiated. An `mtime' comparison does not take into account changes of file permissions, only modifications to the contents of the files.
server
If you want to copy a file remotely from a server, you specify the name of the server here. This must be the name of a host which is running the cfd daemon, and you must make sure that you have defined the variable domain in the control section of the `cfengine.conf' file. If you don't define a domain you will probably receive an error of the form `cfengine: Hey! cannot stat file'.
secure
Has an effect only when used in conjuction with copy from a remote file server. This causes cfengine to use 3DES key encryption and one-time keys on transferred data. This provides good enough privacy for the purposes of system adminstration, but it is not meant to be a super-secure means of encryption. Generally speaking the only case in which this function makes sense is in transferring shadow password files. If you are encrypting the transfer of system binaries, you need your head examining. When encrypt is specified, an md5 checksum is always used to verify the file. Note: the encryption keys required to get files from cfd are those for the user under which cfd is running (normally root). Cfd will not switch keys for other users, so encrypted transfer will not work for all users. If a file requires encrypted transfer (secure flag in cfd) then normal users will not be able to collect it.
size
With this option you can specify that a file is only to be copied if the source file meets a size critereon. This could be used to avoid installing a corrupted file (the copying of an empty password file, for instance). Sizes are in bytes by default, but may also be quoted in kilobytes or megabytes using the notation:

numberbytes
numberkbytes
numbermbytes
Only the first characters of these strings are significant, so they may be written however is convenient: e.g. 14kB, 14k, 14kilobytes etc. Examples are:

   size=<400  # copy if file size is < 400 bytes
   size=400   # copy if file size is equal to 400 bytes
   size=>400  # copy if file size > 400 bytes
linktype
This option determines the type of link used to make links. This only applies if the file is linked rather than copied because it matches a pattern set by symlink. The default type is a direct symbolic link. The values `relative' or `absolute' may be used, but hard links may not be created in place of copied files, since hard links must normally reside on the same filesystem as their files, and it is assumed that most links will be between filesystems. If this value is set to copy or none, symbolic links will be replaced by actual copies of the files they point to. Note that for directories, this option is ignored.
typecheck
Switches on/off error messages if source and existing destination files do not match in type, e.g. if a file would overwrite a directory or link.
define
This option is followed by a list of classes which are to be `switched on' if and only if the named file was copied. In multiple (recursive) copy operations the classes become defined if any of the files in the file tree were copied. This feature is useful for switching on other actions which are to be performed after the installation of key files (e.g. package installation scripts etc).
purge
If this option is set to true, cfengine will remove files in the destination directory which are not also in the source directory. This allows exact images of filesystems to be mantained. Note that if the copy command has includes or excludes or ignored files, cfengine will purge only those files on the client machine which are also on the server. This means that some files (such as system specific work files) can be excluded from copies without them being destroyed. Note that purging is disallowed if contant with a remote server fails. This means that local files will not be destroyed by a denial of service attack. You should not use this option to synchronize NFS mounted file systems. If the NFS server goes down, cfengine cannot then tell the difference between a valid empty directory and a missing NFS file system. If you use purge, use a remote copy also.

Example:

copy:

      /local/etc/aliases dest=/etc/aliases m=644 o=root g=other
      /local/backup-etc  dest=/etc

   solaris::

      /local/etc/nsswitch.conf dest=/etc/nsswitch.conf

In the first example, a global aliases file is copied from the master site file `/local/etc/aliases' to `/etc/aliases', setting the owner and protection as specified. The file gets installed if `/etc/aliases' doesn't exist and updated if `/local/etc/aliases' is newer than `/etc/aliases'. In the second example, `backup-etc' is a directory containing master configuration files (for instance, `services', `aliases', `passwd'...). Each of the files in `backup-etc' is installed or updated under `/etc'. Finally, a global `nsswitch.conf' file is kept up to date for solaris systems.

The home directive can be used as a destination, in which case cfengine will copy files to every user on the system. This is handy for distributing setup files and keeping them updated:

copy:

   /local/masterfiles/.cshrc  dest=home/.cshrc mode=0600

You can force the copying of files, regardless of the date stamps by setting the option force=true or force=on. The default is force=false or force=off.

Hard links in copying

Hard links are not like symbolic links, they are not merely pointers to other files, but alternative names for the same file. The name of every file is a hard link, the first so to speak. You can add additional names which really are the file, they are not just pointers. For the technically minded, they are not separate inodes, they are additional directory references to the same inode. When you perform a copy operation on multiple files, cfengine attempts to preserve hard links but this is a difficult task.

Because a hard link just looks like an ordinary file (it cannot be distingiushed from the original, the way a symbolic link can) there is a danger that any copy operation will copy two hard links to the same file as two separate copies of the same file. The difference is that changes a hard-linked file propagate to the links, whereas two copies of a file are completely independent thereafter. In order to faithfully reproduce all hardlinks to all files, cfengine needs to examine every file on the same filesystem and check whether they have the same inode-number. This would be an enourmous overhead, so it is not done. Instead what happens is that cfengine keeps track of only the files which it is asked to examine, for each atomic copy-command, and makes a note of any repeated inodes within this restricted set. It does not try to go off, wandering around file systems looking to other files which might be hardlinks.

To summarize, cfengine preserves hardlinks during copying, only within the scope of the present search. No backups are made of hard links, only of the first link or name of the file is backed up. This is a necessary precaution to avoid dangling references in the inode table. As a general rule, hard links are to be avoided because they are difficult to keep track of.

Too many open files

In long recursive copies, where you descend into many levels of diretories, you can quickly run out of file descriptors. The number of file descriptors is a resource which you can often set in the shell. It is a good idea to set this limit to a large number on a host which will be copying a lot of files. For instance, in the C shell you would write,

limit descriptors 1024

Most systems should have adequate defaults for this parameter, but on some systems it appears to be set to a low value such as 64, which is not sufficient for large recursive tree searches.

defaultroute

Dynamical routing is not configurable in cfengine, but for machines with static routing tables it is useful to check that a default route is configured to point to the nearest gateway or router. The syntax for this statement is simply:

defaultroute:

   class::

      my_gateway

For example:

defaultroute:

  most::

     129.240.22.1

  rest::

     small_gw

Gateways and routers usually have internet address aaa.bbb.ccc.1 --- i.e. the first address on the subnet. You may use the numerical form or a hostname for the gateway.

disks

This is a synonyn for required, See section required. This action tests for the existence of a file or filesystem. It should be called after all NFS filesystems have been mounted. You may use the special variable $(binserver) here.

  disks:

    /filesystem freespace=size-limit define=class-list(,:.)

Files or filesystems which you consider to be essential to the operation of the system can be declared as `required'. Cfengine will warn if such files are not found, or if they look funny.

Suppose you mount your filesystem /usr/local via NFS from some binary server. You might want to check that this filesystem is not empty! This might occur if the filesystem was actually not mounted as expected, but failed for some reason. It is therefore not enough to check whether the directory /usr/local exists, one must also check whether it contains anything sensible.

Cfengine uses two variables: sensiblesize and sensiblecount to figure out whether a file or filesystem is sensible or not. You can change the default values of these variables (which are 1000 and 2 respectively) in the control section. See section control.

If a file is smaller than sensiblesize or does not exist, it fails the `required' test. If a directory does not exist, or contains fewer than sensiblecount files, then it also fails the test and a warning is issued.

disks:

   any::

      /$(site)/$(binserver)/local

If you set the freespace variable to a value (the default units are kilobytes, but you may specify bytes or megabytes), e.g.

directories

Directories declarations consist of a number of directories to be created. Directories and files may also be checked and created using the touch option in the files actions. See section files.

The form of a declaration is:

  directories:

     classes::

         /directory
                         mode=mode
                         owner=uid
                         group=gid
                         define=classlist
                         syslog=true/on/false/off
                         inform=true/on/false/off

For example

directories:

  class::

     /usr/local/bin  mode=755 owner=root group=wheel

The form of the command is similar to that of files but this command is only used to create new directories. Valid options are mode, owner, group and are described under files See section files. This interface is only for convenience. It is strictly a part of the `files' functionality and is performed together with other `files' actions at run time.

The creation of a path will fail if one of the links in the path is a plain file or device node. A list of classes may optionally be defined here if a directory is created.

disable

Disabling a file means renaming it so that it becomes harmless. This feature is useful if you want to prevent certain dangerous files from being around, but you don't want to delete them-- a deleted file cannot be examined later. The syntax is

 disable:

   class::

      /filename
                      type=plain/file/link/links
                      rotate=empty/truncate/numerical-value
                      size=numerical-value
                      define=classlist
                      syslog=true/on/false/off
                      inform=true/on/false/off
                      repository=destination directory

Cfengine renames a given file by appending the name of the file with the suffix `.cfdisabled'. A typical example of a file you would probably want to disable would be the /etc/hosts.equiv file which is often found with the `+' symbol written in it, opening the system concerned to the entire NIS universe without password protection! Here is an example:

disable:

      /etc/hosts.equiv
      /etc/nologin
      /usr/lib/sendmail.fc

   sun4::

      /var/spool/cron/at.allow

Hint: The last example disables a file which restricts access to the at utility. Such a command could be followed by a file action, See section files,

files:

   some::

      /var/spool/cron/at.allow =0644 N [root] [wheel] touch

which would create an empty security file `at.allow'. See also your system manual pages for the at command if you don't understand why this could be useful.

Disabling a link deletes the link. If you wish you may use the optional syntax

disable:

    /directory/name type=file

to specify that a file object should only be disabled if it is a plain file. The optional element type= can take the values plain, file, link or links. If one of these is specified, cfengine checks the type and only disables the object if there is a match. This allows you to disable a file and replace it by a link to another file for instance.

NOTE that if you regularly disable a file which then gets recreated by some process, the disabled file `filename.cfdisabled' will be overwritten each time cfengine disables the file and therefore the contents of the original are lost each time. The rotate facility was created for just this contingency.

The disable feature can be used to control the size of system log files, such as `/var/adm/messages' using a further option rotate. If the value rotate is set to 4, say,

 disable:

    filename  rotate=4

then cfengine renames the file concerned by appending `.1' to it and a new, empty file is created in its place with the same owner and permissions. The next time disable is executed `.1' is renamed to `.2' and the file is renamed `.1' and a new empty file is created with the same permissions. Cfengine continues to rotate the files like this keeping a maximum of four files. This is similar to the behaviour of syslog.

If you simply want to empty the contents of a log file, without retaining a copy then you can use rotate=empty or rotate=truncate. For instance, to keep control of your World Wide Web server logs:

disable:

   Sunday|Wednesday::

       /usr/local/httpd/logs/access_log  rotate=empty

This keeps a running log which is emptied each Sunday and Wednesday.

The size= option in disable allows you to carry out a disable operation only if the size of the file is less than, equal to or greater than some specified size. Sizes are in bytes by default, but may also be quoted in kilobytes or megabytes using the notation:

numberbytes
numberkbytes
numbermbytes

Only the first characters of these strings are significant, so they may be written however is convenient: e.g. 14kB, 14k, 14kilobytes etc. Examples are:

   size=<400  # disable if file size is < 400 bytes
   size=400   # disable if file size is equal to 400 bytes
   size=>400  # disable if file size > 400 bytes

This options works with rotate or normal disabling; it is just an extra condition which must be satisfied.

If a disable command results in action being taken by cfengine, an optional list of classes becomes can be switched on with the aid of a statement define=classlist in order to trigger knock-on actions.

The repository declaration allows a local override of the Repository variable, on an item by item basis. If set to "off" or "none" it cancels the value of a global repository and leaves the disabled file in the same directory.

editfiles

Performs ascii (line-based) editing on text-files or limited binary editing of files. If editing a file which has hard links to it, be aware that editing the file will destroy the hard link references. This is also the case with shell commands. You should avoid hard links whenever possible. The form of an editing command is editfiles can also search directories recursively through directories and edit all files matching a pattern, using Include, Exclude, and Ignore (see Recursive File Sweeps in the tutorial).

editfiles:

   class::

      { file-to-be-edited

      action "quoted-string..."
      }

      { directory-to-be-edited

      Recurse "inf"
      Filter  "filteralias"
      Include ".cshrc"
      Ignore  "bin"
      Ignore  ".netscape"
      action "quoted-string..."
      }

Here are some examples:

editfiles:

   sun4::

      { /etc/netmasks

      DeleteLinesContaining "255.255.254.0"
      AppendIfNoSuchLine "128.39  255.255.255.0"
      }

   PrintServers::
      { /etc/hosts.lpd

      AppendIfNoSuchLine "tor"
      AppendIfNoSuchLine "odin"
      AppendIfNoSuchLine "borg"
      }

The first of these affects the file `/etc/netmasks' on all SunOS 4 systems, deleting any lines containing the string "255.255.254.0" and Appending a single line to the file containing "128.39 255.255.255.0" if none exists already. The second affects only hosts in the class `PrintServers' and adds the names of three hosts: tor, odin and borg to the file `/etc/hosts.lpd' which specifies that they are allowed to connect to the printer services on any host in the class `PrintServers'.

Note that single or double quotes may be used to enclose strings in cfengine. If you use single quotes, your strings may contain double quotes and vice-versa. Otherwise a double quoted string may not currently contain double quotes and likewise for single quoted strings.

As of version 1.3.0, you can use the `home' directive in edit filenames, enabling you to edit files for every user on the system, provided they exist. For example, to edit every user's login files, you would write

  { home/.cshrc

   AppendIfNoSuchLine "setenv PRINTER default-printer"
   AppendIfNoSuchLine "set path = ( $path /new/directory )"
  }

If a user does not possess the named file, cfengine just skips that user. A new file is not created.

The meanings of the file-editing actions should be self-explanatory. Commands containing the word 'comment' are used to `comment out' certain lines in a file rather than deleting them. Hash implies a shell comment of the type

# comment

Slash implies a comment of the C++ type:

// comment

Percent implies a comment of the type:

% comment

More general comment types may be defined using the SetCommentStart, SetCommentEnd and CommentLinesMatching, CommentLinesStarting functions.

A special group of editing commands is based on the GNU Regular Expression package. These use GNU regular expressions to search line by line through text and perform various editing functions. Some of these commands are based on the concept of a file pointer. The pointer starts at line one of the file and can be reset by 'locating' a certain line, or by using the reset-pointer commands. The current position of the pointer is used by commands such as InsertLine to allow a flexible way of editing the middle of files.

A simple decision mechanism is incorporated to allow certain editing actions to be excluded. For instance, to insert a number of lines in a file once only, you could write:

   { file

    LocateLineMatching "insert point..."
    IncrementPointer   "1"

    BeginGroupIfNoMatch "# cfengine - 2/Jan/95"

      InsertLine "# cfengine - 2/Jan/95"
      InsertLine "/local/bin/start-xdm"

    EndGroup
   }

Since the first inserted line matches the predicate on subsequent calls, the grouped lines will only be carried out once.

The full list of editing actions is given below in alphabetical order. Note that some commands refer to regular expressions and some refer to 'literal strings' (i.e. any string which is not a regular expression). Variable substitution is performed on all strings. Be aware that symbols such as `.', `*' and so on are meta-characters in regular expressions and a backslash must be used to make them literal. The regular expression matching functions are POSIX extended regular expressions. @xref{Regular expressions,Regular expressions,Regular expressions,cfengine-Tutorial}.

AbortAtLineMatching quoted-regex
This command sets the value of a regular expression. In all editing operations (except FixEndOfLine and GotoLastLine) which involve multiple replacements and searches, this expression marks a boundary beyond which cfengine will cease to look any further. In other words, if cfengine encounters a line matching this regular expression, it aborts the current action. BE CAREFUL with this feature: once set, the string remains set for the remainder of the current file. It might therefore interact in unsuspected ways with other search parameters. Editing actions are always aborted as soon as the abort expression is matched. Use UnsetAbort to unset the feature.
Append quoted-string
Add a line containing the quoted string to the end of the file. This should be used in conjunction with the decision structures BeginGroupIfNoLineMatching and BreakIfLineMatches.
AppendIfNoSuchLine quoted-string
Add a line containing the quoted string to the end of the file if the file doesn't contain the exact line already.
AppendIfNoLineMatching quoted-regex
A new version of the older AppendIfNoSuchLine which uses a regular expression instead of a literal string. The line which gets appended must be set previously using SetLine.
AppendToLineIfNotContains quoted-string
This commands looks for an exact match of the quoted string in the current line. If the quoted string is not contained in the line, it is appended. This may be used for adding entries to a list, See section FAQs and Tips.
AutoCreate
If this command is listed anywhere in the file action list, cfengine will create the named file if it doesn't exist. Normally cfengine issues an error if the named file does not exist. New files are created with mode 644, read access for everyone and write access for the cfengine user (normally root). Note that if you set this, BeginGroupIfFileIsNewer will always be true.
AutomountDirectResources quoted-string
This command is designed to assist with automounter configuration for users wishing to use the automounter for NFS filesystems, but still use the cfengine mount model. Applied to the current file, it is equivalent to saying: for each of the mountable resources in the list See section mountables, append if not found a line for a direct automount map command, to the current file. The string which follows can be used to specify any special mount options e.g. "-nosuid" for non setuid mounting (of all the mountables). Note that this is added to the current file and not to a file named `/etc/auto_direct'.
Backup quoted-string
Set to true or false, on or off to set inform level for this file. Default is on.
Repository quoted string
This allows a local override of the Repository variable, on an item by item basis. If set to "off" or "none" it cancels the value of a global repository.
BeginGroupIfFileExists quoted-string
The lines following, up to the first EndGroup are executed if the quoted filename exists (can be statted). Files which are not readable by the running process are for all intents and purposes non-existent.
BeginGroupIfFileIsNewer quoted-string
The lines following, up to the first EndGroup are executed if the quoted filename is newer than the file being edited.
BeginGroupIfNoLineContaining quoted-string
The lines following, up to the first EndGroup are executed if the quoted string does not appear in any line in the file.
BeginGroupIfNoLineMatching quoted-regex
The lines following, up to the first EndGroup are executed if the quoted regular expression does not match any line in the file.
BeginGroupIfNoMatch quoted-regex
The lines following, up to the first EndGroup are executed if the quoted regular expression does not match the current line.
BeginGroupIfNoSuchLine quoted-string
The lines following, up to the first EndGroup are executed if the quoted literal string does not match any line in the file.
BreakIfLineMatches quoted-regex
Terminates further editing of the current file if the current line matches the quoted regular expression.
CatchAbort
Edit actions which abort on failure (such as LocateLineMatching) will jump to the first instance of this marker instead of completely aborting an edit if this keyword occurs in an editing script. You can catch the exceptions thrown by the following commands: CommentNLines,CommentToLineMatching,DeleteNLines,DeleteToLineMatching, HashCommentToLineMatching,IncrementPointer, LocateLineMatching,PercentCommentToLineMatching, RunScriptIf(No)LineMatching,UnCommentNLines.
CommentLinesMatching quoted-regex
Use the current value of the comment delimiters set using SetCommentStart and SetCommentEnd to comment out lines matching the given regular expression in quotes.
CommentLinesStarting quoted-string
Use the current value of the comment delimiters set using SetCommentStart and SetCommentEnd to comment out lines starting with the quoted literal string.
CommentNLines quoted-string
Comments up to N lines from the current file, starting from the location of the current line pointer. If the end of the file is reached and less than N lines are deleted, a warning is issued, but editing continues. The current value of the comment delimiters is used to determine the method of commenting, (see SetCommentStart). After the operation the pointer points to the line after the commented lines.
CommentToLineMatching quoted-regex
Use the current value of the comment delimiters set using SetCommentStart and SetCommentEnd to comment out lines from the current position in a file to a line matching the given regular expression in quotes.
DefineClasses "class1:class2:..."
Activate the following colon, comma or dot-separated list of classes if and only if the file is edited.
DeleteLinesAfterThisMatching quoted-regex
DeleteLinesContaining quoted-string
Delete all lines containing the exact string quoted.
DeleteLinesMatching quoted-regex
Delete all lines matching the quoted regular expression.
DeleteLinesStarting quoted-string
Delete all lines beginning with the exact string quoted.
DeleteNLines quoted-string
Deletes up to N lines from the current file, starting from the location of the current line pointer. If the end of the file is reached and less than N lines are deleted, a warning is issued, but editing continues.
DeleteToLineMatching quoted-regex
Delete lines from the current position, up to but not including a line matching the regular expression in the quoted string. If no line matches the given expression, a warning is only printed in verbose mode, but all edits are immediately abandoned.
EmptyEntireFilePlease
Deletes all lines from the current file.
ElseDefineClasses
See DefineClasses
EndGroup
Terminates a begin-end conditional structure.
EndLoop
Terminates a loop. See ForEachLineIn
Filter filteralias
Name a fiter for pruning file searches.
FixEndOfLine
The quoted string which follows may be either `dos' or `unix' to fix the end of line character conventions to match these systems. This command should be executed last of all, since cfengine appends new lines with the conventions of the system on which is was complied during edit operations.
ForEachLineIn quoted-filename
This marks the beginning of a for-loop which reads successive lines from a named file. The result is like using SetLine for each line in the file. Nested loops are not permitted.
GotoLastLine
Moves the file pointer to the last line in the current file.
HashCommentLinesContaining quoted-string
Add a `#' to the start of any line containing the quoted string.
HashCommentLinesMatching quoted-regex
Add a `#' to the start of any line exactly matching the quoted regular expression.
HashCommentLinesStarting quoted-string
Add a `#' to the start of any line starting with the quoted string.
IncrementPointer quoted-number
Increments the value (in lines) of the file pointer by the number of lines specified in the quoted string (as a denary number). e.g. `"4"'. Negative values are equivalent to decrementing the pointer. If a request is made to increment/decrement outside of the file boundaries the pointer `bumps' into the boundary and remains there, i.e. either at start of file or end of file.
Inform quoted-string
Set to true or false, on or off to set inform level for this file. Default is off.
InsertFile quoted-string
Inserts the named file after the current line position in the file. This should be used in conjunction with a begin-end construction in order to avoid including the file every time cfengine is run. If the file does not exist, or cannot be opened, there is only a warning issued in verbose mode. Note if the file is empty, or if the current line pointer is not set, the file is inserted at the start of the file.
InsertLine quoted-string
Inserts the quoted string as a line at the current position in the file. After the insert, the file pointer is incremented by one so that subsequent inserted lines are placed after the first. This should probably be used in conjunction with the conditional begin-end tests to avoid lines being inserted on every run.
LocateLineMatching quoted-string
Moves the current-position pointer to the start of the line matching the quoted regular expression. If there is no match, a warning is only issued in verbose mode, but all editing is immediately aborted. See also WarnIfNoLineMatching so that you can get an explicit warning, even out of verbose mode.
PercentCommentLinesContaining quoted-string
Add a `%' to the start of any line containing the quoted string.
PercentCommentLinesMatching quoted-regex
Add a `%' to the start of any line exactly matching the quoted regular.
PercentCommentLinesStarting quoted-string
Add a `%' to the start of any line starting with the quoted string.
Prepend quoted-string
Add a line containing the quoted string to the start of the file. This should be used in conjunction with the decision structures BeginGroupIfNoLineMatching and BreakIfLineMatches.
PrependIfNoLineMatching quoted-regex
A new version of the older PrependIfNoSuchLine with uses a regular expression instead of a literal string. The string prepended is the one set using SetLine.
PrependIfNoSuchLine quoted-string
Add a line containing the quoted string to the start of the file if the file doesn't contain the exact line already.
Recurse digit/inf
For recursive descents when editing whole file trees.
ReplaceLineWith quoted-string
Replace the line at the current position with the text in the quoted string. The file pointer remains pointing to this line after the change.
ReplaceAll quoted-regex With quoted-string
Replace all instances of strings matching the regular expression in the first quotes with the exact string in the second set of quotes, throughout the current file. Note that cfengine matches on a left to right basis, with the first match taking precedence, so if your regular expression matches text ambiguously it is the first occurrence which is replaced. For example, if you replace `cf.*' with `CFENGINE' and cfengine encounters a line `hello cfengine cfengine', then this will be replaced with `hello CFENGINE' even though two possible strings match the regular expression. On the other hand if the expression is not ambiguous, say replacing `cfengine' with `CFENGINE', then the result would be `hello CFENGINE CFENGINE'.
ReplaceLinesMatchingField quoted-number
This command replaces any lines in the current file with the current line set by SetLine or ForEachLineIn, if the lines are split into fields (e.g. the password file) separated by the SplitOn character (':' by default), and the corresponding fields match. The idea behind this command was to be able to override global passwords (from a file which gets distributed) by new passwords in a local file. Rather than maintaining the files separately, this simply overrides the entries with the new ones See section FAQs and Tips.
ResetSearch quoted-string
Sets the current-position pointer to the line number in the quoted string. `EOF' indicates the end of the file.
RunScript quoted-string
Executes the named script command. Before executing the script any edits are saved to disk. After the script has executed, cfengine reloads the file for any further editing operations. The script (which may be any executable program) is appended with two arguments: the name of the file which is being edited and the system hard class (e.g. sun4, ultrix etc.) of the system executing the script. CAUTION: cfengine knows nothing about the success or failure of anything that is done during the execution of user scripts. This feature is to be used at the users own peril!
RunScriptIfLineMatching quoted-string
Executes the script named with the SetScript command only if the current file contains a line matching the quoted regular expression. CAUTION: cfengine knows nothing about the success or failure of anything that is done during the execution of user scripts. This feature is to be used at the users own peril!
RunScriptIfNoLineMatching quoted-regex
Executes the script named with the SetScript command if the current file contains no line matching the quoted regular expression. CAUTION: cfengine knows nothing about the success or failure of anything that is done during the execution of user scripts. This feature is to be used at the users own peril!
SetCommentStart quoted-string
Specify which string should be used for starting a comment using the commands CommentLineMatching and CommentLineStarting. The default is the hash symbol `#' followed by a single space.
SetCommentEnd quoted-string
Specify which string should be used for ending a comment using the commands CommentLineMatching and CommentLineStarting. The default is the empty string. For example, you could make C style comments by setting CommentStart to `/*' and comment end to `*/'.
SetLine quoted-string
Sets a current line value which can be appended using AppendIfNoLineMatching using a regular expression.
SetScript quoted-string
Sets the name of a user-supplied script for editing the current file.
SlashCommentLinesContaining quoted-string
Add a `//' to the start of any line containing the quoted string.
SlashCommentLinesMatching quoted-regex
Add a `//' to the start of any line exactly matching the quoted regular expression.
SlashCommentLinesStarting quoted-string
Add a `//' to the start of any line starting with the quoted string.
SplitOn quoted-string
This defines a single character which is to be interpreted as a field separator for editing files with columns. The default value for this is `:', as is used in the password and group files. It is used in conjunction with ReplaceLinesMatchingField.
Syslog quoted-string
Set to true or false, on or off to set inform level for this file. Default is off.
Umask quote mode
Set local umask for file creation and script execution.
UnCommentLinesContaining quoted-string
Uncomment all lines in file containing the quoted string as a substring. The comment delimiters are assumed to be those set using SetCommentStart and SetCommentEnd.
UnCommentLinesMatching quoted-regex
Uncomment all lines in file matching the quoted regular expression. The comment delimiters are assumed to be those set using SetCommentStart and SetCommentEnd.
UnCommentNLines quoted-string
Uncomments N lines starting from the current position, using the currently defined method for commenting. Note that the comment start and end symbols are removed independently, i.e. they are not matched, so that a comment may be spread over several lines. e.g. If using C style `/*' and `*/' comments, the command UnCommentNLines "3" would uncomment
 /* 1 */
 /* 2 */
 /* 3 */
and also
 /* 1
    2
    3 */
UnsetAbort quoted-string
Switches off the feature AbortAtLineMatching.
WarnIfLineContaining quoted-string
Issue a warning if the quoted string is found as a substring of one or more lines in the file.
WarnIfLineMatching quoted-regex
Issue a warning if the quoted regular expression matches one or more lines in the file.
WarnIfLineStarting quoted-string
Issue a warning if the quoted string matches the start of one or more lines in the file.
WarnIfNoLineContaining quoted-string
Issue a warning if the quoted string is not contained in one or more lines in the file.
WarnIfNoLineMatching reg-ex
Issue a warning if the quoted regular expression does not match one or more lines in the file.
WarnIfNoLineStarting quoted-string
Issue a warning if the quoted string is not found at the start of one or more lines in the file.
WarnIfNoSuchLine quoted-regex
Issue a warning if the quoted regular expression does not match one or more lines in the file.

A limited number of operations can also be performed on purely binary files, e.g. compiled programs, in order to search for strings or viral code, or to modify strings within a program. Binary mode is a mutually exclusive, separate mode to normal editing. The limit on the size of binary files is set by editbinaryfilesize in control.

ReplaceAll regex With literal
Replaces occurrences of the matched regular expression with\ the provided literal text, only if the length of the literal substitute is less than or equal to the length of the located string. If the replacement string is shorter, it is padded with ascii spaces (character 32) by default. The padding character can be changed by setting BinaryPaddingChar in control. Padding with a null byte would lead to corruption of text within a program.
WarnIfContainsString regex/literal
Yields a warning if the literal string or regular expression matches. Cfengine first attempts a literal match and then a regular expression match.
WarnIfContainsFile filename
Yields a warning if the contents of the named file exactly match part of the file which is being edited. This can be used to search for binary data which cannot be typed directly into the cfengine program, e.g. virus signatures.

It is suggested that you use these editing functions with caution. Although all possible safeguards have been incorporated into them, it is still possible through carelessness to do damage to important files on your system. Always test editing programs carefully before committing them to your global site configuration.

files

The files facility allows you to touch (create), check for the existence, owner and permissions of files, change the permissions and test for setuid root programs.

Syntax

A files-statement can have several options. We can begin by examining the form of the statement in pseudo-code:

  files:

     classes::

        /file-object
                          mode=mode
                          owner=uid-list
                          group=gid-list
                          action=fixall/other-options/warnall
                          links=false/stop/traverse/follow/tidy

                          ignore=pattern
                          include=pattern
                          exclude=pattern
                          filter=filter alias

                          define=classlist
                          elsedefine=classlist

                          checksum=md5
                          flags=BSD flags
                          syslog=true/on/false/off
                          inform=true/on/false/off

An example would be the following:

   any::

      /var/spool/printQ  mode=0775  r=0 o=daemon g=daemon  act=fixdirs

The meaning of these item is sketched out below and becomes clearer on looking at a number of examples. Note that, each of the options below can be written in either upper or lower case and abbreviated by any unique abbreviation. A file object is interpreted as a directory if you write it in the following form: `/directory-path/.'. i.e. a trailing dot signifies a directory. This then becomes the same as the directory command.

/directory
This is the only obligatory part of a file action. This is a directory at which a file search should begin. This may be a single file or a directory. The recursion specifier may be used to force cfengine to descend into subdirectories in a controlled fashion, starting from this point, checking files there also. The wildcard home may also be used. See section home directive.
mode=modestring
Specifies what the allowed permissions for files are. If cfengine finds that a file's mode is incorrect, the value of the action option determines what will be done about it. The modestring should consist of either a three digit octal numbers with `+', `-' or `=' symbols, or a text string like that used by the command chmod. For instance: mode=u=rwx,og+rx would mean set the read/write and execute flags for the user (file owner) and add the read/execute flags for others and group bits. An example of the numerical form might be -002 which would mean that the read-for-others flag should either not be set or should be unset, depending on the action you choose. +2000 would mean that the setuid flag should be present or set, depending on the action. +2000,-002 would be a combination of these. The `=' sign sets to an absolute value, so =755 would set the file mode to mode 755.
flags=BSD flags
The free BSD Unices have additional filesystem flags which can be seton files. Refer to the BSD chflags documentation for this. For example,

   /tmp/flags.01  mode=0600 owner=0 group=0
                  flags=uappnd,uchg,uunlnk,nodump,opaque,sappnd,schg,sunlnk
                  action=touch
recurse=number/inf
This specifier tells cfengine whether or not to recurse into subdirectories. If the value is zero, only the named file or directory is affected. If the value is 1, it will open at most one level of subdirectory and affect the files within this scope. If the value is inf then cfengine opens all subdirectories and files beginning from the specified filename.See section Recursion.
owner=owner list
This is a list of allowed owners, or uids by number, separated by commas. For example root,2,3,sysadm. In cases where you ask cfengine to fix the ownership automatically, the owner will be set to the first owner in the list if and only if it is not one of the named uids in the list.
group=group list
This is a list of allowed groups, or gids by number, separated by commas. For example wheel,2,3,sysadm. In cases where you ask cfengine to fix the ownership automatically, the group will be set to the first group in the list if and only if it is not one of the named gids in the list.
action=action
The action is one of the following keywords.
warnall warndirs warnplain
 fixall fixdirs fixplain
touch linkchildren create compress alert
The upper line results only in warnings being issued. The actions beginning `fix' prompt cfengine to fix encountered problems without bothering the user. No message is issued unless in verbose mode. The special features on the third line will be explained separately. Alert is like -print in the find command, it triggers on the existence of files which have not been ignored, excluded or filtered. This should normally be used together filter, in order to locate files of particular types.
include=wildcard/pattern
You can include this option several times to specify specific patterns which are to be included in the search. Once you specify one pattern you exclude all files not matching at least one of the patterns. The case be useful for restricting a search, or for modifying the permissions of only certain files.
exclude=wildcard/pattern
You can include this option several times to specify specific patterns which are to be excluded from the search. This overrides any patterns given in the include= list.
ignore
This works like the global ignore directive but here you may provide a private list of ignorable directories and files. Unlike include, exclude this affects the way cfengine parses directory trees.
links=stop/traverse/tidy
Normally cfengine does not descend into subdirectories which are pointed to by symbolic links. If you wish to force it to do so (without using the -l command line option) you may give this option the value true, or traverse, or follow. To specify no recursion you set the value false or stop. Note that the value set here in the cfengine program always overrides the value set by the -l command line option, so you can protect certain actions from this command line option by specifying a negative value here. If you specify no value here, the behaviour is determined by what you specify on the command line. The value links=tidy has the same effect as the `-L' command line option except that here it may be specified per item rather than globally. Setting this value causes links which point to non-existent files to be deleted. If the warn directive is used (for directories, plain files or both) then only a warning message is issued if the file being tested does not match the specification given. If the fix directives are used then cfengine does not issue a warning, it simply fixes the value silently. Non-existent files are created by the touch command. A directory may be touched (created) by writing the filename /a/b/c/. with a dot as the last character. (This may also be achieved with the directories directive, See section directories.)
define=classlist
If a file operation results in action being taken to fix a file, the colon, comma or dot separated list of classes becomes defined. Warnings do not activate the classes.
checksum=md5
If set this option causes cfengine to add a checksum for the named file to a database. Changes in the value of this checksum are then warned as a security issue. This should normally only be used to monitor binary files which one would not expect to change often. Note also that the use of this option can mean a significant performance penalty. The variable ChecksumDatabase should be set in control: to the filename of a database file which is used to cache checksum values. Note that it is also possible to use a database file for cfd's remote copying by checksum. If you use the same file for both purposes you risk losing warnings. Security warning messages are issued only once and the value in the database is then changed to the new value of the file automatically i.e. the behaviour is similar to that of setuid root program detection, @xref{Checksum Databases,Checksum Databases,Checksum Databases,cfengine-Tutorial}.

The default values are mode=+000, recurse=0, action=warnall and any owner or group is acceptable. The default for links is to not traverse links unless the -l option is set on the command line.

Recursion

The recursion specifier tells cfengine what to do, starting from /directory name. A value of r=0 means `no recursion' and any checking is limited only to the named file or directory. A value of r=inf implies unlimited recursion. Cfengine then descends into all subdirectories checking or setting the permissions of files until it `bottoms out' at a plain file. A value such as R=4 means descend recursively into subdirectories, but no more than four levels. This is a useful safety net in preventing unforeseen accidents. A recursive search also bottoms out on device boundaries and symbolic links (provided the -l option is not used).

Directory permissions

When you specify the permissions for a whole file tree, using the recursion specifier it is awkward to have to remember that directories must be executable. cfengine will do this for you automatically. If you specify that a file tree is to have a read flag set, cfengine will ensure that the corresponding execute flag is also set for directories which live in the tree. So the command

files:

  myclass::

      /dir  mode=a+rw r=inf fixall

would set all plain files to mode 644 and all directories to 755, that is read/write for everyone on plain files and read/write/execute for everyone on directories.

home directive

If you want to check the files of all the users who have their login areas on the current host, you can use a wildcard directive home instead of a directory name. In this case the file action iterates over all home directories physically on the current host. The home directories are, of course, located by searching for files which match

$(mountpattern)/$(homepattern)

i.e. the values which are specified in the control part of the program. For example the following line is a very useful service to ignorant users.

files:

  any::

    home mode=o-w r=inf act=fixall

It ensures automatically that no user has files which can be written to by other arbitrary users.

As a corollary to this, you may write something like

  any::

     home/www mode=a+r fixall

to specify a special subdirectory of every users' home directory. This statement would check that all of the files in users' world wide web directories were readable for everyone.

Owner and group wildcards

If you do not want to explicitly state the owner or group of a file you may simply omit the group or owner options.

  /file-object m=0664 r=inf

This example generate a warning if any files under the named directory do not have permission read/write for all users.

Files linkchildren

The linkchildren facility is almost identical to that already described under links. See section Link Children. The only difference here is that the ownership and permissions on the links are set all in one operation. For example:

myclass::

   /local/lib/emacs m=0770 o=me g=mygroup act=linkchildren

touch

The touch facility creates a new file with the specified permissions and ownership, or corrects the permissions and ownership of an existing file, in addition to updating the time stamps.

myclass::

   /newfile mode=0644 action=touch

create

This is like touch except that an existing file's time stamps, permissions and ownership will not be modified if the file already exists. If the file does not exist, the attributes are set to the values specified, or to the default values of 0644.

filters

A filter is a way of selecting or pruning during a search over files or processes. Since filter rules could apply to several objects, cfengine allows you to define filter conditions as separate objects to be applied in different contexts.

Filter objects can be used in copy, editfiles, files, tidy and processes. In most cases one writes

.. filter=<i>filteralias</i>

in the appropriate command. The exception is editfiles, where the syntax is

{
..
Filter "filteralias"
..
}

Example:

files:

 /tmp filter=testfilteralias action=alert r=inf

Filters are defined in a separate section. Filters for files and processes are defined together. They differ only in the criteria they contain. Here is are examples of file filters:

Filters:

  { filteralias1

  Owner:     "mark|cell|motd"
  Group:     "ecg|mark"
  Mode:      "700"

  FromCtime: "date(2000,1,1,0,0,0)"    # absolute date
  ToCtime:   "now"

  FromMtime: "tminus(1,0,0,2,30,0)"    # relative "ago" from now
  ToMtime:   "inf"                     # end of time

  FromAtime: "date(1997,2,22,0,0,0)"
  ToAtime:   "inf"

  FromSize:  "10000"                   # File size interval
  ToSize:    "10mb"

  ExecRegex: "/usr/bin/file(.*ascii.*)"# Result from "files" command

  Type:      "dir|link"                # reg|link|dir|socket|fifo|door|char|block

  NameRegex: ".*.asc"                  # regex matching file name

  IsSymLinkTo: "/dev/null"             # True if file is a link to object name regex

  Result:    "Type"                    # Result which shouldbe returned

  }

 #########################################

  { testfilteralias2

  ExecProgram: "/bin/ls $(this)"       # True if the program returns true. $(this) is the current object
  }

 #########################################

  { testfilteralias3

  Owner: "mark"
  }

Filters are evaluated like classes. In fact, the filtering works by evaluating the class attributes for each file.

File filters:

Owner:
and Group can use numerical id's or names, or "none" for users or groups which are undefined in the system passwd/group file.
Mode: applies only to file objects. It shares syntax with the mode= strings in the files command. This test returns true if the bits which are specified as `should be set' are indeed set, and those which are specified as `should not be set' are not set.
Atime:,Ctime:,Mtime:
apply only to file objects. These specify ranges From and To. If the file's time stamps lie in the specified range, this returns true. Times are specfied by a six component vector
(year,month,day,hour,minutes,seconds)
This may be evaluated as two functions: date() or tminus() which give absolute times and times relative to the current time respectively. In addition, the words now and inf may be used. e.g.
  FromCtime: "date(2000,1,1,0,0,0)"   # absolute date
  ToCtime:   "now"

  FromMtime: "tminus(1,0,0,2,30,0)"     # relative "ago" from now
  ToMtime:   "inf"                     # end of time
Type:
applies only to file objects may be a list of file types which are to be matched. The list should be separated by the OR symbol `|', since these types are mutually exclusive. The possible values are currently
reg|link|dir|socket|fifo|door|char|block
ExecRegex:
matches the test string against the output of the specified command.
NameRegex:
matches the name of the file with a regular expression.
IsSymLinkTo:
applies only when the file object $(this) is a symbolic link. It is true if the regular expression matches the contents of the link.
ExecProgram:
matches if the command returns successfully (with return code 0). Note that this feature introduces an implicit dependency on the command being called. This might be exploitable as a security weakness by advanced intruders.
Result:
specifies the way in which the above elements are combined into a single filter.

Process filters:

PID:
process ID (quoted regex)
PPID:
parent process ID (quoted regex)
PGID:
process group ID (quoted regex)
RSize:
resident size (quoted regex)
VSize:
virtual memory size (quoted regex)
Status:
status (quoted regex)
Command:
CMD or COMMAND fields (quoted regex)
(From/To)TTime:
Total elasped time in TIME field (accumulated time)
(From/To)STime:
Starting time for process in STIME or START field (accumulated time)
TTY:
terminal type, or none (quoted regex)
Priority:
PRI or NI field (quoted regex)
Threads:
NLWP field for SVR4 (quoted regex)
Result:
logical combination of above returned by filter (quoted regex)

Examples: processes started between 18th Nov 2000 and now.

  { filteralias

  FromSTime: "date(2000,11,18,0,0,0)"
  ToSTime:   "now"
  }

All processes which have accumulated between 1 and 20 hours of CPU time.

  { filteralias

  FromTTime:  "accumulated(0,0,0,1,0,0)"
  ToTTime:    "accumulated(0,0,0,20,0,0)"
  }

Complete filter examples

Here is an example filter to search for all files which are either directories or links, or any kind of file owned by mark, in group cfengine.

control:

 actionsequence = ( files )

files:

 /tmp       filter=testfilteralias action=alert r=inf
 /cfengine  filter=testfilteralias action=fixall r=inf mode=644

filters:

  { testfilteralias

  Owner:     "mark"
  Group:     "cfengine"
  Type:      "dir|link"

  Result:    "Type|(Owner.Group)"  # Both owner AND group required correct
  }

Find all ELF executables using data from the Unix file command. Caution, this takes a long time if used indescriminately.

control:

 actionsequence = ( files )

files:

 /tmp       filter=testfilteralias action=alert r=inf
 /cfengine  filter=testfilteralias action=fixall r=inf mode=644

filters:

  { testfilteralias

  ExecRegex: "/bin/file (.*ELF.*)"

  Result: "ExecRegex"
  }

Here is an example which warns of any process coupled to a terminal started in November:

control:

 actionsequence = ( processes )

filters:

  { filteralias
  FromSTime: "date(2000,11,0,0,0,0)"
  ToSTime:   "date(2000,11,30,0,0,0)"
  TTY: ".*pt.*"
  Result: "TTY.STime"
  }

processes:

 "." filter=filteralias action=warn

groups/classes

The groups action (equivalently referred to as classes as of version 1.4.0) is used to define classes which stand for groups of hosts. If you use the NIS (network information service) facility for defining netgroups then this idea will already be familiar to you and you can probably use your already-defined netgroups in cfengine.

To define a group, you simply make a list and assign it a name. Here is an example of the syntax:

groups:

   science = ( saga tor odin )

   packages = ( saga )

   AllHomeServers   = ( saga )
   AllBinaryServers = ( saga )

   OIH_servers = ( saga )
   OIH_clients = ( tor odin )

   notthis = ( !this )

To include a list of hosts from a NIS netgroup, you use the `+' symbol, or the `+@' construction. For example:

groups:

   science = ( +science-allhosts )

   physics = ( +physics-allhosts )

   physics_theory = ( +@physics-theory-sun4 dirac feynman schwinger )

Using an enormous netgroup does not use up any space. A group declaration results in the storage of only the class name regardless of how many hosts are in the list. The rule is that the left hand side of the assignment becomes defined (true) if the list on the right hand side includes the host which is parsing the file -- i.e. $(host).

In some cases your netgroups will not correspond exactly to the list you want, but it might be more convenient to use a netgroup except for certain hosts. You can `undefine' or remove hosts from the netgroup list by using the minus `-' symbol. For example:

group = ( +mynetgroup -specialhost -otherhost )

which means, of course, all hosts in netgroup mynetgroup except for specialhost and otherhost. Finally, you may also subtract two netgroups in the following manner.

group = ( +bignetgroup -smallnetgroup )

The `minus' command effectively eliminates its members from bignetgroup if they exist within that group. If none of the hosts in smallnetgroup exist in bignetgroup then the command has no effect.

Groups may now contain previously defined cfengine groups too. This allows one class to inherit the attributes of another class, for instance:

  AllSun4Hosts   = ( sonny sunny solar stella )
  AllUltrixHosts = ( ully olly wally golly )

  AllBSD = ( AllSun4Hosts AllUltrixHosts )

The classes on the right hand side are effectively ORed together into the left hand side. This enables complex classes to be constructed from several other basic classes, e.g.

  SpecialTimes = ( Hr00 Monday Day1 )

which evaluates to true every day when it between 00:00 hours and 00:59, all day Monday and all day on the first day of every month.

Finally, you can define groups (strictly classes) by the result of a shell command. A shell command or program is deemed to be `true' if it exits with a status of zero, i.e. it calls exit(0). Any other value is taken to be false. You can include shell commands as the members of groups in order to define classes based on the outcomes of your own scripts by enclosing the script in single or double quotes:

   have_cc = ( '/bin/test -f /usr/ucb/cc' )

The class have_cc will then be defined if the shell command returns true. Of course, you can put any script or program in the single quotes as long as they adhere to the convention that zero exit status means true. If you have several members which are shell commands, then the effect is to make the class the logical OR of the scripts' results.

As of version 1.4.0, you may use the synonym classes for groups.

homeservers

The homeservers declaration need only be used if you are using cfengine's model for mounting NFS filesystems. This declaration informs hosts of which other hosts on the network possess filesystems containing home directories (login areas) which client hosts should mount.

A sample homeserver declaration looks like this:

homeservers:

   Physics::  einstein
   Math::     riemann euler

The meaning of this declaration is the following. Any host which finds itself to be a member of the classes on the left hand side of the assignment need to mount all home directory resources from the hosts on the right hand side of the assignment. The pattern variable homepattern is used to determine which resources are home directories in the list of mountables. See section mountables.

Let us consider an example in which homepattern is set to the wildcard value `home?' and the mountables list is given by

mountables:

   einstein:/mysite/einstein/home1
   einstein:/mysite/einstein/home2
   riemann:/mysite/riemann/local
   euler:/mysite/euler/home1

Any host in the group Physics would now want to mount all home directories from the host einstein. There are two of these. Both the filesystems listed for einstein match the homepattern variable since they end in `home?'. cfengine would therefore take this to mean that all hosts in Physics should mount both of these filesystems.

Hosts in Math, on the other hand, should mount only homedirectories from the hosts riemann and euler. There is only a single filesystem on riemann and it does not match homepattern, so it is not mounted. On euler there is a match, so this filesystem will be added to the appropriate hosts.

Cfengine picks out home directory resources from the mountables list by trying to match the homepattern variable, starting from the end of the directory name. You do not therefore have to use the designation /site/host/home? but this is a simple choice and is highly recommended.

ignore

When you specify a recursive search as part of a files, tidy or copy action, you would sometimes like to exclude certain directories from the list of sub directories. In most cases you will want to do this on a per-command basis (see the pages for these actions separately), but you can also make a global ignore list. This can be accomplished by adding the directory to the ignore-list. The syntax is

  ignore:

     wildcards/directories/filenames

For example:

ignore:

   any::

      #
      # Prevent tidying .X11 directories in /tmp where
      # window managers write semaphores
      #

      .X11

      #
      # Don't tidy emacs locks
      #

      !*
      /local/lib/gnu/emacs/lock/
      /local/tmp
      /local/bin/top
      /local/lib/tex/fonts
      /local/etc
      /local/www
      /local/mutils/etc/finger.log

None of the above directories will be checked or entered during recursive descents unless a specific command is initiated to search those directories with their names as the top of the search tree.

A handy tip if you are tidying `/tmp' recursively is to include the directory `.X11' here. This directory is used by the X-windows system and deleting it while a window manager has an open session can cause the user some trouble.

Ignore refers to all recursive searches in tidy, files, copy and links.

import

To break up a large configuration file into smaller files you can use the include directive. This conditionally reads in files if the class on the left hand side of the assignment matches the host parsing the file. This enables also a variety of cfengine configuration scripts to read in a standard set of default settings. The syntax of the statement is:

import:

   any::

      cf.global_classes

   linux::

      cf.linux_classes

Note that, if you define variables in an imported file they will not be defined for operations in their parent files. This because cfengine reads in all the import files after the main file has been parsed--not at the place where you call import in your script. This means that variables or macros defined in imported files are only defined after the main program. Variables from earlier files are inherited by later includes, but not vice-versa.

interfaces

 interfaces:

   classes::

     interfacename netmask=netmask broadcast=broadcast

If you have more than one network interface, or you do not wish to use the default interface name, this section may be used to define further interfaces to be checked. This feature can replace the older method of setting netmask and broadcast address in control:. If the netmask variable is not set, cfengine ignores the default interface configuration. Example:

  interfaces:

    "le1" netmask=255.255.255.0 broadcast=ones
    "le2" netmask=255.255.255.0 broadcast=ones

links

The symbolic links function is one of the greatest plusses in cfengine as a system administration tool. It allows you to do two things: check single links for correctness and consistency (or make them if they do not exist), and check or make links to every file in a designated directory. This latter feature is called multiple linking or linking children. The linkchildren feature is also available from the files action See section files. The syntax of a link item is:

  from-link ->[!] to-object
 or
  from-link +>[!] to-object

            type=symbolic/absolute/abs/hard/relative/rel
            copy=pattern
            recurse=number/inf/0
            copytype=checksum/ctime
            include=pattern
            exclude=pattern
            ignore=pattern
            action=silent
            deadlinks=kill/force
            define=classlist
            nofile=kill/force
            syslog=true/on/false/off
            inform=true/on/false/off

The special variable $(binserver) can be used in links.

Single links

To define a single link, you create an entry of the following form:

links:

  class::

     linkname -> object_to_link_to
     linkname -> ./relative_link
     linkname -> ../relative_link

If links exists and point to their intended destinations then no action is taken. If a link exists but points incorrectly then a warning is issued, unless the pling operator `!' is given, in which case the correct value is forced. If the link exists and points to a file which does not exist a warning is issued unless the command line option -L is used, in which case the link is deleted. See section Runtime Options.

Here is an example of some valid link statements.

links:

  Physics.sun4::

   /usr/local       -> /$(site)/$(host)/local
   /home            -> /$(site)/$(host)/u1
   /etc/sendmail.cf -> /usr/local/mail/etc/global-sendmail.cf

   /usr/lib/sendmail ->! /local/lib/sendmail

cfengine makes any directories which are required leading up to the link name on the left hand side of the arrow automatically. In the last example the `pling' forces cfengine to make the link even if a file for link exists previously. Plain files are saved by appending `.cfsaved' to the filename, or by moving to a repository, whereas old links are removed. The same effect can be enforced globally using the -E option, but only if the program is run interactively. (In this case a prompt is issued to make sure that you wish to use such a big hammer on your system!)

The link operation accepts a number of parameters

type=hard/relative/absolute
If the link type is hard, a hard link is created See section Hard Links. Symbolic links may specify two special types. If relative is selected, and the `to' object is an absolute path name, the link name will be rewritten as a pathname relative to the source file, using `.' and `..' to move relative to the current directory. For instance, a link from `/usr/local/file' to `/usr/file' would be linked as `./../file'. If the `to' object is already relative, this has no effect. If absolute is specified, cfengine will try to resolve the true path location of the `to' object, expanding any symbolic links or dots in the path name, up to a maximum of four levels of symbolic links.
copy=pattern
This option can be repeated any number of times to build up a list of filenames or wildcards which are to be copied rather than linked symbolically. The copy is made on an age-comparison basis. A global variable may also be set to invoke this feature See section CopyLinks. Directories cannot be copied in this way.
copytype=checksum/ctime
This specifies the basis for deciding whether to update a file which is to be copied instead of linked See section copy.
nofile=kill/force
This decides what happens to links which point to non-existent files. The default action is to remove such links, or refuse to create them. By setting the force option you can force cfengine to make symbolic links to files which do not exist. This is useful for setting up links to filesystems which are not permanently mounted.
exclude=pattern
This option can be repeated any number of times to build up a list of filenames or wildcards which are to be excluded from the linking process. A global variable may also be set to invoke this feature See section ExcludeLinks.
ignore
This works like the global ignore directive but here you may provide a private list of ignorable directories and files. Unlike include, exclude this affects the way cfengine parses directory trees.
recurse=number/inf
This option can only be used with multiple link operations See section Multiple Links. If this option is specified, cfengine links only non-directory objects. Directories are instead created and links within those directories are also created. The value of this option specifies the maximum number of levels to which cfengine should recursively descend a link tree. inf means infinite recursion. Cfengine also ignores files and directories in the ignore list See section ignore.
define=classlist
If a link is created or replaced, the colon, comma or dot separated list of classes becomes defined.

The final feature of the links facility is connected to the use of the cfengine model for mounting NFS filesystems. In particular it concerns the variable $(binserver). The easiest way to understand this feature is to illustrate a couple of examples. Consider the following:

links:

   any::

      /local -> /${site}/${binserver}/local

The result of this command is quite different depending on which host is executing it. The variable $(site) clearly has a fixed value, but the variable $(binserver) might expand to any valid binary server for the host executing the program. See section binservers. The procedure cfengine adopts is to go through its list of mountables, keeping only those mountable resources which belong to defined binary servers for the current host. It then attempts to match a filesystem by substituting $(binserver) with each of its valid binservers in turn and it matches the first one binary server which yields an existing file.

Note that every host is a binary server for itself, so that the value of $(binserver) which has absolute priority is alway the same as the value of $(host). This ensures that the link will always be made to a local filesystem if the rules of the model are upheld.

Multiple Links

With the link symbol +>, you opt to link all of the files in a directory to corresponding files in another directory. This procedure is sometimes useful for installing software. In the example

links:

  myclass::

     /usr/local/bin +>  /usr/local/lib/perl/bin
     /opt           +>! /local

every file in the directory /usr/local/lib/perl/bin is linked symbolically to a corresponding file in /usr/local/bin. The `pling' character forces cfengine to replace old links or plain files already existing. Old links are removed, whereas old files are saved by appending `.cfsaved' to the filename See section Repository.

Each time cfengine runs it goes through all of the files in the directory concerned and checks the appropriate link accordingly. If new files appear, new links will be added. If a file disappears but the link to it remains, a warning will be issued, unless the -L command line option is used, in which case the link is deleted. See section Runtime Options.

Link Children

The linkchildren directive is a closely related to the cfengine model for NFS filesystems. It is a way of making links which embodies a rudimentary kind of `intelligence'.

Consider the following:

links:

   any::

      /usr/local/lib/emacs +> linkchildren

The word linkchildren automatically tells cfengine that it should look for an appropriate file to link to on a binary server for the current host. The exact meaning of the above statement is as follows. cfengine begins searching though the list of mountable resources, discarding any filesystems which do not belong to valid binary servers. It looks for a filesystem ending in `emacs' (the last link of the left hand side). If all is well, these file systems are already mounted and they can be searched. If no resource is found ending in `emacs', we go to the next link lib and look for a filesystem ending in `lib'. If this is not found we go to local and so on. When a match is made, cfengine then tries to locate the file by checking whether it exists relative to the matched filesystem. For example, suppose `local' matched with host:/site/host/local. It would then try to locate host:/site/host/local/lib/emacs and link all of the children therein to the local file directory /usr/local/lib/emacs.

Here is another example which makes reference to the cfengine model for mounting NFS filesystems. Suppose you have a host with some spare disk space. You want to mount /usr/local from the binary architecture server, but you also want to use the disk you have locally. The following lines

links:

   electron::

      /$(site)/electron/local +> linkchildren

   any::

      /usr/local              -> /$(site)/$(binserver)/local

have the effect of creating a directory /$(site)/electron/local and filling it with links to all of the files and directories on the binary server's mounted filesystem. It results in an exact copy (by linkage) on the local disk, but does not use up your local disk space. The space you have remaining could, for example, be used for software with a special license for that host. The second link links /usr/local to the `nearest' binary server. But the nearest binary server is always $(host) which means this evaluates to a file which now exists because of the first command, so on the host `electron' the directory /usr/local ends up being a link to /$(site)/electron/local which is full of links to the binary server.

If you've caught your breath after that mouthful you probably have mixed feelings about creating a bunch of links in this way. What happens if the files they point to are removed? Then you are left with a lot of useless links. Actually this is no problem for cfengine, since you can ask cfengine to simply remove links which point to non-existent files See section files. Nevertheless, this feature clearly requires some caution and is mainly a spice for advanced users of the cfengine model.

Relative and absolute links

When specifying symbolic linking, you can ask cfengine to change the link type to be either relative to the source or to be an absolute path. What this means is the following. Consider the following link:

   /var/tmp/cfengine -> /local/cfengine

If we add the option type=relative, then instead of creating a link which points to `/local/cfengine', the link is created pointing to the location

  ./../../local/cfengine

In other words, the link is relative to the calling directory `/var/tmp'.

If a link is specified as being absolute with the option type=absolute, then cfengine attempts to resolve to value of the link so as to be the true path of the target. If the target name contains a symbolic link, then this is expanded as far as possible to give the true path to the file. For example, if `/local' is really a link to `/site/myhost/local' then the link would point to `/site/myhost/local/cfengine'.

Hard Links

Cfengine will also allow you to create hard links to regular files. A hard link is in every way identical to the original file, it merely has a different name (technically, it is a duplicate inode). To create a hard link you use the link-option type=hard. For example:

links:

   /directory/newname -> /directory/othername type=hard

Cfengine will not create hard links to directories or other special files. This is always a slightly dubious practice and is best avoided anyway. POSIX says that the hard link can be on a different device to the file it points to, but both BSD and System 5 restrict hard links to be on the same device as their predecessors. Cfengine has no policy on this, but--in the theoretical case in which the hard link and the predecessor were on different file systems--it becomes near impossible to determine with certainly between a hard link and a very similar regular file, and thus cfengine issues a warning in verbose mode about this eventuality. Provided both link and predecessor are on the same filesystem cfengine determines the status of hard links by comparing the device and inode numbers of the file pointed to.

mailserver

The mailserver declaration need only be used if you are using cfengine's model for mounting NFS filesystems. This declaration informs hosts of which NFS filesystem contains mail for its users. All hosts apart from the mail-host itself must then mount the mail spool directory across the network. The declaration looks like this:

mailserver:

   class::      mailhost:/var/spool/mail

The result of the mailcheck command in the action-sequence is now to mount the filesystem /var/spool/mail on the host mailhost. This action is carried out on any machine which does not already have that filesystem mounted.

The mail spool directory is mounted, by default, onto the official mail spool directory for the system which is parsing the program. In other words, on an HPUX system, the spool directory is mounted on /usr/mail by default, whereas on a Sun system it would be mounted on /var/spool/mail. The default location can be changed by using the resource file. See section `cfrc' resource file.

miscmounts

If you do not use the cfengine model for statically mounting NFS filesystems (or if there are filesystems which do not naturally fall into the bounds of that model) then you can still statically mount miscellaneous filesystems using a statement of the form:

miscmounts:

   class::

      infohost:source-directory destination mode

      infohost:source-directory destination mode=mode

For example

   physics::

    # old syntax

      libraryserver:/$(site)/libraryserver/data1
                          /$(site)/libraryserver/data1 ro

    # consistent syntax

      libraryserver:/$(site)/libraryserver/data2
                          /$(site)/libraryserver/data2 mode=ro

      host:/foo /foo mode=rw,bg,hard,intr

This statement would mount the directory `/$(site)/libraryserver/data' physically attached to host libraryserver onto a directory of the same name on all hosts in the group physics. The modes ro and rw signify read-only and read-write respectively. If no mode is given, read-write is assumed.

mountables

The mountables declaration need only be used if you are using cfengine's model for mounting NFS filesystems. This declaration informs hosts of what filesystem resources are available for mounting. This list is used in conjunction with binservers and homeservers to determine which filesystems a given host should mount, according to the cfengine model.

The syntax of the list is:

mountables:

   class::

   server:/site/server/u1
   server:/site/server/local
   linuxhost:/site/linuxhost/local
   linuxhost:/site/linuxhost/u1

Notice that binary and home-directory filesystems are mixed freely here. Cfengine determines which of the entries are homedirectories using the homepattern variable.

Every time you add a disk or a mountable partition to your network, you should add the partition to the list of mountables.

NOTE: This list is read in order, top down. Cfengine looks for the first filesystem matching a given binary server when expanding the variable $(binserver), so sometimes the ordering of filesystems matters.

This list can be accessed in editfiles, to allow straightforward configuration of the automounter, using the command AutomountDirectResources.

processes

Using the processes facility, you can test for the existence of processes, signal (kill) processes and optionally restart them again. Cfengine opens a pipe from the system ps command and searches through the output from this command using regular expressions to match the lines of output from `ps'. The regular expression does not have to be an exact match, only a substring of the process line. The form of a process command is

processes:

    "quoted regular expression"

                        restart "shell command"
                        useshell=true/false/dumb
                        owner=restart-uid
                        group=restart-gid
                        chroot=directory
                        chdir=directory
                        umask=mask

                        signal=signal name
                        matches=number
                        define=classlist
                        action=signal/do/warn/bymatch
                        include=literal
                        exclude=literal
                        syslog=true/on/false/off
                        inform=true/on/false/off

    SetOptionString "quoted option string"

By default, the options sent to ps are "-aux" for BSD systems and "-ef" for system 5. You can use the SetOptionString command to redefine the option string. Cfengine assumes only that the first identifiable number on each line is the process identifier for the processes, so you must not choose options for ps which change this basic requirement (this is not a problem in practice). Cfengine reads the output of the ps-command normally only once, and searches through it in memory. The process table is only re-consulted if SetOptionString is called. The options have the following meanings:

signal=signal name
This option defines the name of a signal which is to be sent to all processes matching the quoted regular expression. If this option is omitted, no signal is sent. The signal names have the usual meanings. The full list, with largely standardized meanings, is
   hup       1   hang-up
   int       2   interrupt
   quit      3   quit
   ill       4   illegal instruction
   trap      5   trace trap
   iot       6   iot instruction
   emt       7   emt instruction
   fpe       8   floating point exception
   kill      9   kill signal
   bus      10   bus error
   segv     11   segmentation fault
   sys      12   bad argument to system call
   pipe     13   write to non existent pipe
   alrm     14   alarm clock
   term     15   software termination signal
   urg      16   urgent condition on I/O channel
   stop     17   stop signal (not from tty)
   tstp     18   stop from tty
   cont     19   continue
   chld     20   to parent on child exit/stop
   gttin    21   to readers pgrp upon background tty read
   gttou    22   like TTIN for output if (tp->t_local&LTOSTOP)
   io       23   input/output possible signal
   xcpu     24   exceeded CPU time limit
   xfsz     25   exceeded file size limit
   vtalrm   26   virtual time alarm
   prof     27   profiling time alarm
   winch    28   window changed
   lost     29   resource lost (eg, record-lock lost)
   usr1     30   user defined signal 1
   usr2     31   user defined signal 2
Note that cfengine will not attempt to signal or restart processes 0 to 3 on any system since such an attempt could bring down the system. The only exception is that the hangup (hup) signal may be sent to process 1 (init) which normally forces init to reread its terminal configuration files.
restart "shell command"
Note the syntax: there is no equals sign here. If the keyword `restart' appears, then the next quoted string is interpreted as a shell command which is to be executed after any signals have been sent. This command is only issued if the number of processes matching the specified regular expression is zero, or if the signal sent was signal 9 (sigkill) or 15 (sigterm) , i.e. the normal termination signals. This could be used to restart a daemon for instance. Cfengine executes this command and waits for its completion so you should normally only use this feature to execute non-blocking commands, such as daemons which dissociate themselves from the I/O stream and place themselves in the background. Some unices leave a hanging pipe on restart (they never manage to detect the end of file condition). This occurs on POSIX.1 and SVR4 popen calls which use wait4. For some reason they fail to find and end-of-file for an exiting child process and go into a deadlock trying to read from an already dead process. This leaves a zombie behind (the parent daemon process which forked and was supposed to exit) though the child continues. A way around this is to use a wrapper script which prints the line "cfengine-die" to STDOUT after restarting the process. This causes cfengine to close the pipe forcibly and continue. Cfengine places a timeout on the restart process and attempts to clean up zombies, but you should be aware of this possibility.
owner=,group=
Sets the process uid and gid (setuid,gid) for processes which are restarted. This applies only to cfengine run by root.
chroot
Changes the process root directory of the restarted process, creating a `sandbox' which the process cannot escape from. Best used together with a change of owner, since a root process can break out of such a confinement in principle.
chdir
Change the current working directory of the restarted process.
useshell=true/false/dumb
When restarting processes, cfengine normally uses a shell to interpret and execute the restart command. This has inherent security problems associated with it. If you set this option to true, cfengine executes restart commands without using a shell. This is recommended, but it does mean that you cannot use any shell operators or features in the restart command-line. Some programs (like cron) do not handle I/O properly when they fork their daemon parts, this causes a zombie process and normally hangs cfengine. By choosing the value `dumb' for this, cfengine ignores all output from a program and does not use a startup shell. This prevents programs like cron from hanging cfengine.
matches=number
This option may be used to set a maximum, minimum or exact number of matches. If cfengine doesn't find a number of matches to the regular expression which is in accordance with this value it signals a warning. The `<', `>' symbols are used to specify upper and lower limits. For example,
  matches=<6  # warn number of matches is greater than or equal to 6
  matches=1   # warn if not exactly 1 matching process
  matches=>2  # warn if there are less than or equal to 2 matching processes
include=literal
Items listed as includes provide an extra level of selection after the regular expression matches have been expanded. If you include one include option, then only lines containing one or more of the literal strings or wildcards will be matched.
exclude=literal
Process lines containing literal strings or wildcards in exclude statements are not matched. Excludes are processed after regular expression matching and after includes.
define=classlist
The colon, command or dot separated list of classes becomes activated if the number of regular expression matches is non zero.
action=signal/do/warn
The default value of this option is to silently send a signal (if one was defined using the signal option) to matching processes. This is equivalent to setting the value of this parameter to `signal' or `do'. If you set this option to `warn', cfengine sends no signal, but prints a message detailing the processes which match the regular expression. If the option is set to bymatch, then signals are only sent to the processes if the matches criteria fail.

Here is an example script which sends the hang-up signal to cron, forcing it to reread its crontab files:

processes:

   "cron" signal=hup

Here is a second example which may be used to restart the nameservice on a solaris system:

processes:

   solaris::

       "named" signal=kill restart "/usr/sbin/in.named"

A more complex match could be used to look for processes belonging to a particular user. Here is a script which kills ftp related processes belonging to a particular user who is known to spend the whole day FTP-ing files:

control:

    actionsequence = ( processes )

  #
  # Set a kill signal here for convenience
  #

    sig = ( kill )

  #
  # Better not find that dumpster here!
  #

    matches = ( 1 )

processes:

   #
   #  Look for Johnny Mnemonic trying to dump his head, user = jmnemon
   #

   ".*jmnemon.*ftp.*" signal=$(sig) matches=<$(matches) action=$(do)

   # No mercy!

The regular expression `.*' matches any number of characters, so this command searches for a line containing both the username and something to do with ftp and sends these processes the kill signal. Further examples may be found in the FAQ section See section FAQs and Tips.

You can arrange for signals to be sent, only if the number of matches fails the test. The action=bymatch option is used for this. For instance, to kill process `XXX' only if the number of matches is greater than 20, one would write:

processes:

"XXX" matches=<20  action=bymatch signal=kill

See also filters See section filters, for more complex searches.

required

This is a synonym for disks, See section disks. This action tests for the existence of a file or filesystem. It should be called after all NFS filesystems have been mounted. You may use the special variable $(binserver) here.

  required:

    /filesystem freespace=size-limit define=class-list(,:.)

Files or filesystems which you consider to be essential to the operation of the system can be declared as `required'. Cfengine will warn if such files are not found, or if they look funny.

Suppose you mount your filesystem /usr/local via NFS from some binary server. You might want to check that this filesystem is not empty! This might occur if the filesystem was actually not mounted as expected, but failed for some reason. It is therefore not enough to check whether the directory /usr/local exists, one must also check whether it contains anything sensible.

Cfengine uses two variables: sensiblesize and sensiblecount to figure out whether a file or filesystem is sensible or not. You can change the default values of these variables (which are 1000 and 2 respectively) in the control section. See section control.

If a file is smaller than sensiblesize or does not exist, it fails the `required' test. If a directory does not exist, or contains fewer than sensiblecount files, then it also fails the test and a warning is issued.

required:

   any::

      /$(site)/$(binserver)/local

If you set the freespace variable to a value (the default units are kilobytes, but you may specify bytes or megabytes), e.g.

required:

  /site/host/home1 freespace=50mb define=dotidy

then cfengine will warn when the filesystem concerned has less than this amount of free space. By adding a define tag, you can switch on any number of classes if this happens. This allows you to activate special measures for dealing with a filesystem which is in danger of becoming full.

resolve

The file /etc/resolv.conf specifies the default nameserver for each host, as well as the local domain name. This file can also contain other information, but these are the only two things cfengine currently cares about. In specifying nameservers you should use the dotted numerical form of the IP addresses since your system may not understand the text form if it is not correctly configured. You may list as many nameservers as you wish, with the default server at the top of the list. The resolver normally ignores entries if you add more than three. The statement:

resolve:

  mygroup::

     129.240.22.35
     129.240.22.222
     129.240.2.3

declares a list of nameservers for hosts in the group or class mygroup. When you add the resolve command to the actionsequence, this declaration together with the domain variable (set here to uio.no) results in a /etc/resolv.conf file of the form:

domain uio.no
nameserver 129.240.22.35
nameserver 129.240.22.222
nameserver 129.240.2.3

Note that the resolve action does not delete anything from the file /etc/resolv.conf. It adds nameservers which do not previously exist and reorders the lines of servers which do exist.

As of version 1.3.11, you may use a quoted string to add non-nameserver lines to this file. For example:

resolve:

  mygroup::

     129.240.22.35
     129.240.22.222
     "# Comment line"
     "order bind, files"

If the line begins with a non-numeric character, the word `nameserver' is not added to the line.

shellcommands

Cfengine focuses on fairly simple minded tasks in order to be as general as possible. In many cases you will therefore want to write a script to do something special on your system. You can still take advantage of the classes you have defined by executing these scripts or shell commands from this section.

The syntax is simply to quote the command you wish to be executed.

shellcommands:

  "command-string"

          timeout=seconds
          useshell=true/false
          umask=octal number
          owner=uid
          group=gid
          define=class-list
          background=false/true
          chdir=directory
          chroot=directory
          preview=true/false

The user and group ID's of the process can be set to restrict the permissions of the shellcommand to another user only if cfengine is executed by root. If you set the optional timeout string, then cfengine will abort the shellcommand if it exceeds the specified time-limit in seconds. This can be useful for avoiding situations caused by hung network connections etc.

Variable substitution works within the strings. Here are some examples.

shellcommands:

   sun4::

       "/usr/lib/find/updatedb"

   AllHomeServers.Sunday::

       "/dir/noseyparker /$(site)/$(host)/u1 $(sysadm) nomail"

   AllBinaryServers.sun4.Saturday::

      "/usr/etc/catman -w -M /usr/local/man"
      "/usr/etc/catman -w -M /usr/local/X11R5/man"
      "/usr/etc/catman -w -M /usr/man"
      "/usr/etc/catman -w -M /usr/local/gnu/man"

If you need to write more advanced scripts, which make detailed use of the classes defined by cfengine, use the $(allclasses) variable to send a complete list of classes to your script in the format

CFALLCLASSES=class1:class2:class3...

This variable is kept up-to-date at any given time with only the classes which are defined. The command line option `-u' or `--use-env' can be used to define an environment variable which will be inherited by all scripts and contains the same information. This is not the standard approach, since some systems cannot cope with this rapid change of environment and generate a Bus Error.

Commands can be iterated over variable lists, provided there is at least one space between each variable. For example:

control:

      actionsequence =
         (
         shellcommands
         )

 var1 = ( a:b:c )
 var2 = ( x:y:z )

shellcommands:

   "/bin/echo $(var1) $(var2)"

This iterates over all values of the list variables. @xref{Iterating over lists,Iterating over lists,Iterating over lists,cfengine-Tutorial}. If you are iterating over a list, the timeout applies to each separate iteration, not to the sum of all the iterations.

The chroot option changes the process root directory of the command, creating a `sandbox' which the process cannot escape from. Best used together with a change of owner, since a root process can break out of such a confinement in principle. The chdir option changes the current working directory of the restarted process.

The preview option means that the shellcommand will also be executed during the --dry-run (-n) options. This allows cfengine to be more aware of the results of scripts which define classes. This option should be used with care. Scripts should conform to the protocol of not executing unnecessary commands when the classes opt_dry_run is defined.

tidy

The tidy function is used to delete (remove permanently) unwanted files from a system. It is useful for tidying up in /tmp or cleaning out core files from users' home directories. The form of an entry is:

tidy:

  class::

      /directory
                       pattern=wildcard
                       recurse=number/inf
                       age=days
                       size=number/empty
                       type=ctime/mtime/atime
                       dirlinks=keep/tidy/delete
                       rmdirs=true/false/all/sub
                       links=stop/keep/traverse/tidy

                       define=classlist
                       elsedefine=classlist

                       syslog=true/on/false/off
                       inform=true/on/false/off

                       filter=filter alias
                       include=pattern
                       exclude=pattern

Note that, each of the options below can be written in either upper or lower case and abbreviated by any unique abbreviation.

/directory
This is the directory name to directories which mark the start of a search for files matching certain wildcards. The wildcard home may be used instead of an explicit directory, in which case cfengine iterates over all home directories. It is compulsory to specify a directory.
pattern=wildcard
A wildcard or filename to match the files you wish to be deleted. The pattern may contain the special symbols `?' which matches a single character and `*' which matches any number of characters as in the shell.
recurse=number/inf
This specifier tells cfengine whether or not to recurse into subdirectories. If the value is zero, only the named file or directory is affected. If the value is 1, it will open at most one level of subdirectory and affect the files within this scope. If the value is inf then cfengine opens all subdirectories and files beginning from the specified filename. See section Recursion.
age=days
The age of a file in days represents a minimum access time elapsed before the file will be deleted. In other word a file will be deleted if it has not been accessed for days days.
links=stop/traverse/tidy
Normally cfengine does not descend into subdirectories which are pointed to by symbolic links. If you wish to force it to do so (without using the -l command line option) you may give this option the value true, or traverse, or follow. To specify no recursion you set the value false or stop. Note that the value set here in the cfengine program always overrides the value set by the -l command line option, so you can protect certain actions from this command line option by specifying a negative value here. If you specify no value here, the behaviour is determined by what you specify on the command line. The value links=tidy has the same effect as the `-L' command line option except that here it may be specified per item rather than globally. Setting this value causes links which point to non-existent files to be deleted. This feature will not work on commands with the `home' wildcard feature. If you want to clean up old links you should either user a files command or the command line option which sets the tidy feature globally.
size=number/empty
The value of this parameter decides the size of files to be deleted. Files larger than this value will be deleted if they also are older than the time specified in age. The default size is zero so that any file which gets matched by another critereon is deleted. However, if you want to single out only totally empty files, the empty may be used. With this option only empty files, nevery files with anything in them, will be deleted, if older than age. By default, the filesizes are in kilobytes, but kilobytes and megabytes may also be specified by appending b,k,m to the numbers. Only the first character after the number is significant so you may write the numbers however it might be convenient, e.g. 14k, 14kB, 14kilobytes, the same as for disable.
type=ctime/mtime/atime
This value is used to set the type of time comparison made using age. The default is to compare access times (atime) or the last time the file was read. A comparison by modification time (mtime) uses the last time the contents of the file was changed. The ctime parameter is the last time the contents, owner or permissions of the file were changed.
dirlinks=keep/tidy/delete
This value is used to decide whether cfengine will delete links which point to directories. The default value is to keep the links. Note that, if the travlinks option is switched on, cfengine will not tidy or delete links which point to directories, instead it follows them into the subdirectory. This is a supplement to the rmdirs option. You need both to make links to directories disappear.
rmdirs=true/false/all/sub
Normally cfengine will not delete directories. If this option is set to `true' then cfengine will delete any directories which are empty. Non-empty directories will not be touched and no message will be given unless in verbose mode. Note that this option overrides the above option dirlinks, so that even links which point to empty directories will be removed. If this is set to `sub' then the topmost directory will not be removed, only sub-directories.
define=classlist
The colon, comma or dot separated list of classes becomes defined if any file matching the specified pattern is deleted.

Take a look at the following example:

tidy:

   AllHomeServers::

       home     pattern=core   R=inf age=0
       home     pattern=*~     R=inf age=7
       home     pattern=#*     R=inf age=30

   any::

       /tmp/    pat=*            R=inf   age=1
       /        pat=core         R=2     age=0
       /etc     pat=hosts.equiv  r=0     age=0

In the first example, all hosts in the group AllHomeServers iterate a search over all user home directories looking for `core' files (older than zero days) and emacs backup files `*~', `#*' older than seven days.

The default values for these options are the empty string for the wildcard pattern, zero for the recursion and a specification of the age is compulsory.

When cfengine tidies users' home directories, it keeps a log of all the files it deletes each time it is run. This means that, in case of accidents, the user can see that the file has been deleted and restore it from backup. The log file is called .cfengine.rm and it is placed in the home directory of each user. The file is owned by root, but is readable to the user concerned.

unmount

The unmount function unmounts non-required filesystems and removes the appropriate entry from the filesystem table (/etc/fstab or equivalent). The syntax is simply

unmount:

   class::

      mounthost:filesystem

        deletedir=true/false
        deletefstab=true/false
        force=true/false

The options allow you to temporarily unmount a directory without actually removing it from the filesystem table. The option force is not currently implemented and will likely have to be system dependent. For example:

unmount:

   physics::

      libraryserver:/$(site)/libraryserver/data

If the device is busy then the actual unmount will not take place until it becomes free, or the machine is rebooted. This feature should work on AIX systems, in spite of these machines inherent peculiarities in the form of the filesystem table.

Some users do not mount filesystems on a directory of the same name as the source directory. This can lead to confusion. Note, if you have problems removing a mounted filesystem, try using the mountpoint of the filesystem, rather than the name of the filesystem itself, in the unmount command.

Cfengine script gallery

Here is a gallery of simple-minded scripts to give you ideas for making your own. The absence of explicit testing in cfengine programs also makes these scripts transparent while offering a higher level of checking for no cost to the programmer. Similar shell scripts with this property would be complex indeed.

User scripts for tidying old files

Here is an example script for tidying old files in your own login area. If you want a long diagnostic, add the option -v to the first line of the script, before -f.

#!/usr/local/bin/cfengine -f
#
# Tidy
#

control:

   actionsequence =
      (
      tidy
      )

tidy:

      $(HOME)        pat=core   r=inf  age=0
      $(HOME)        pat=*~     r=inf  age=1
      $(HOME)        pat=#*     r=inf  age=7
      $(HOME)/code   pat=*.o    r=inf  age=7
      $(HOME)/tex    pat=*.dvi  r=inf  age=7
      $(HOME)/tex    pat=*.log  r=inf  age=7
      $(HOME)/tex    pat=*.aux  r=inf  age=7

      $(HOME)/ftp    pat=*.zip  r=inf  age=7

Controlled opening of files for friends and colleagues

#!/local/gnu/bin/cfengine -f
#
# Open my shared directory for others in my group
#
#

control:

  actionsequence =
     (
     files
     )

  gr = ( myshare )

files:

      $(HOME)       mode=0755 action=fixdirs r=0
      $(HOME)/share mode=0664 action=fixall  r=inf group=$(gr)

In this example, first your home directory is opened for the world, then all files in the subdirectory share and subdirectories are opened to the group myshare. This script could be made to run from a login/logout script of some kind (either .login or .xsession) so that any new files would automatically be controlled.

Root script for emergency disk clearing

A straightforward script could be used to clear space in cases where the disk hits the overflow level. This script tidies the whole system, not just the affected disk.

#!/local/gnu/bin/cfengine -f
#
# Emergency tidyup!
#
# (Users read their cfengine.rm files to see what got deleted!)
#

control:

site = ( mysite )

mountpattern = ( $(site)/$(host) )
homepattern   = ( u? )

actionsequence =
   (
   tidy
   )

tidy:

      home            pattern=core   R=inf   age=0
      home            pattern=*~     R=inf   age=0
      home            pattern=*.dvi  R=inf   age=1
      home            pattern=*.o    R=inf   age=0
      /tmp            pattern=*      R=inf   age=0  # could be risky
      /usr/tmp        pattern=*      R=inf   age=0  #      "

ignore:

     .X11

Script for making links

The following script could be used as part of a software installation procedure. Note that the link types can be made relative to the from-link by using type=relative See section links.

#!/tmp/cfengine -v -f
#
# Simple example script to make links
#

control:

  actionsequence = ( links )

links:

 host::

   /usr/local/bin                  +> /usr/local/lib/soft/bin
   /usr/local/X11/lib/app-defaults +> /usr/local/lib/soft/app-defaults

It makes links from every binary file in the packages `bin' directory to the more standard binary directory /usr/local/bin. This avoids having to place another search directory into the users' path variable. The second statement links the package's application defaults files (for the X-windows system) to a directory in the XAPPLRESDIR search path.

This script provides only one way of making the necessary files available to users. It is not the only solution to the problem.

Ftp server

This script carries out the necessary for setting up a safe anonymous ftp server on a sun workstation running SunOS4.1.

#!/local/gnu/bin/cfengine -f
##############################################################
#
# Cfengine script to set up an outgoing ftp server under
# SunOS 4.1.*.  Suitable for anonymous access.
#
###############################################################

control:

 addclasses = ( local global )

 actionsequence =
    (
    editfiles.global
    directories
    shellcommands
    files
    editfiles.local
    )

 ftp_root = ( /oih/saga/local/ftp )   # macro for convenience
 ftp_id   = ( 99 )                    # uid/gid for ftp

################################################################

editfiles:

 # Note the file /etc/ftpusers can contain a list of users
 # who can NOT use ftp to access files.

 global::

 { /etc/passwd

 AppendIfNoSuchLine "ftp:*:$(ftp_id):$(ftp_id): (line continues)
Anonymous ftp:$(ftp_root):/usr/ucb/ftp"
 }

 { /etc/group

 AppendIfNoSuchLine "ftp:*:$(ftp_id):"
 }

################################################################

directories:

  $(ftp_root)           mode=0555 owner=ftp
  $(ftp_root)/pub       mode=0555 owner=ftp
  $(ftp_root)/bin       mode=0555 owner=root
  $(ftp_root)/usr       mode=0555 owner=root
  $(ftp_root)/dev       mode=0555 owner=root
  $(ftp_root)/etc       mode=0555 owner=root
  $(ftp_root)/dev       mode=0555 owner=root
  $(ftp_root)/usr/lib   mode=0555 owner=root

###############################################################

shellcommands:

  "/bin/cp /bin/ls $(ftp_root)/bin/ls"
  "/bin/cp /lib/libc.so.1.8* $(ftp_root)/usr/lib"
  "/bin/cp /usr/lib/ld.so  $(ftp_root)/usr/lib"
  "/bin/cp /usr/lib/libdl.so.1.0 $(ftp_root)/usr/lib/libdl.so.1.0"
  "/usr/etc/mknod $(ftp_root)/dev/zero c 3 12 > /dev/null 2>&1"

##########################################################################

files:

 $(ftp_root)/bin/ls     mode=111 owner=root action=fixall
 $(ftp_root)/usr/lib    mode=555 owner=root action=fixall r=1
 $(ftp_root)/etc/passwd mode=444 owner=root action=touch
 $(ftp_root)/etc/group  mode=444 owner=root action=touch
 $(ftp_root)/pub        mode=644 owner=root action=fixall

################################################################

editfiles:

 local::

 { $(ftp_root)/etc/passwd

 AppendIfNoSuchLine "ftp:*:$(ftp_id):$(ftp_id): (line continues)
Anonymous ftp:$(ftp_root):/usr/ucb/ftp"
 }

 { $(ftp_root)/etc/group

 AppendIfNoSuchLine "ftp:*:$(ftp_id):"
 }

Problem solving, bugs, FAQs and tips

`cf.preconf' bootstrap file

In some cases you will want to run cfengine on a system to configure it from scratch. If the system is in a very bad way, it might not even be able to parse the cfengine configuration file, perhaps because the network was not properly configured or the DNS (Domain Name Service) was out of action. To help prevent this situation, cfengine looks for a script called cf.preconf which gets executed prior to parsing and can be used to perform any emergency tests. This file needs only contain enough to get the system to parse the configuration files.

cf.preconf may be any script in any language. It need not exist at all! It is fed one argument by cfengine, namely the system hard-class for the current system (e.g. ultrix). Here is an example:

#!/bin/sh
#
# cf.preconf is an emergency/bootstrap file to get things going
# in case cfengine is unable to parse its config file
#

backupdir=/iu/nexus/local/iu/etc

 #
 # If these files don't exist, you might not be able to parse cfengine.conf
 #

if [ ! -s /etc/resolv.conf ]; then

 echo Patching basics resolv.conf file
 cat > /etc/resolv.conf << XX
domain iu.hioslo.no
nameserver 128.39.89.10
XX

fi

#
# SVR4
#

if [ "$1" = "solaris" ]; then

  if [ ! -s "/etc/passwd" ]; then

  echo Patching missing passwd file
    /bin/cp $backupdir/passwd /etc/passwd
  fi

  if [ ! -s "/etc/shadow" ]; then

   echo Patching missing passwd file
   /bin/cp $backupdir/shadow /etc/shadow
  fi
fi

#
# BSD 4.3
#

if [ "$1" = "linux" ]; then

   if [ ! -s "/etc/passwd"  ]
   then

    echo Patching missing passwd file
    /bin/cp $backupdir/passwd.linux /etc/passwd
   fi
fi

`cfrc' resource file

If, for some reason you are not satisfied with the defaults which cfengine uses, then you can change them by making an entry in the resource file. The default values are defined in the source code file classes.c in the distribution. The format of the resource file is:

hardclass.variable: value

For example, you might want to forget about where your HPUX system mounts its mail directory and mount it under /usr/spool/mail. In this case you would add the line:

hpux.maildir: /usr/spool/mail

To redefine the filesystem table for GNU/linux, you would write:

linux.fstab: /etc/linuxfstab

The full list of re-definable resources is:

   mountcomm       # command used to mount filesystems
   unmountcomm     # command used to unmount filesystems
   ethernet        # name of the ethernet device
   mountopts       # options to above mount command
   fstab           # the name of the filesystemtable
   maildir         # the location of the mail directory
   netstat         # the full path to netstat and options
   pscomm          # the path to the system's ps command
   psopts          # the options used by ps (default aux/ef)

You should never need to redefine resources unless you decide to do something non-standard. Interested readers are referred to the values in classes.c.

Cfengine is easily extensible so as to support a variety of architectures. You can even add your own. To do so you need, first of all, to define a new class for the operating system concerned. The file classes.c has been separated off from the remainder of the source code so that you can easily see which data structures need to be extended.

To make life as straightforward as possible, three unused classes have been defined. They are called (unremarkably) unused1, unused2 and unused3. If you add any further classes, it will be necessary to increase the constant clssattr defined in cf.defs.h by one for every new addition. You do not need to change clssattr if you simple replace one of the unused classes by a real class.

To see fully the impact of what you need to do, you should make a search for the strings unused? in all of the source files. Certain special cases need to be handled for each operating system. For example, the form of the filesystem table is quite radically different on some systems such as AIX. One thing you must do is to fill in the default values for the new operating system in the file classes.c.

If you fill in the details for a new operating system before it finds its way into a new release, you might consider sending the details to the bug list in the next paragraph.

Problems with compilation and installation

Although every effort has been made to make the compilation of cfengine trouble free, you might still encounter some problems where non-standard features are concerned. The differences between systems is still a major headache.

Earlier versions of the GNU/Linux operating system do not have support for some of the facilities which cfengine uses. In particular, the ability to use NIS netgroups is absent from earlier versions. During the installation procedure, the configure script tests for this possibility and advises you if the facility cannot be used. You can still use cfengine in this case but netgroups will not be expanded. Another problem with GNU/Linux concerns a special socket call to the TCP/IP network interface. This is a command which configures the static routing table and appears to be absent from all versions of Linux and newer IRIX versions. There are also problems with NetBSD. These features are undocumented and will be fixed as soon as they have been understood! If you are running in verbose mode a warning message is printed, otherwise cfengine will ignore attempts to set a default route on the system.

A number of users have experienced a problem using flex and bison in place of lex and yacc. There appears to be a bug in one of these programs which causes cfengine to compile correctly but misinterpret its configuration files, generating an error of the form

cfengine:10:action contains invalid statement

for every line! The cure is to collect the latest versions of flex and bison from your nearest GNU site.

On really old systems, the configure program is not able to guess what kind of system you are working on. This is true of SunOS versions 4.0.* and also of BSD 4.3 systems. In such cases, you might be able to compile cfengine by using the autoconf option `host' to specify the host-type.

configure --host=sparc-sun-sunos4.0

Some other systems which will compile if forced are:

m68k-hp-bsd4.3
?-?-bsd4.3
romp-ibm-aos
?-?-aos

On some systems, problems arise when using flex. Flex might generate a lexer file lex.yy.c which defines malloc or some other function to be of a type which conflicts with the system definition. If you obtain such a culture crash, edit the lexer file manually and simply delete the offending definitions, then run make again.

As of version 1.4.0 cfengine tries to link in features based on the Berkeley database library `libdb' and the TCP wrappers library `libwrap'. If you want to use these facilities, you will have to collect them and install them before compiling cfengine. Some problems have been experienced with the linux version of TCP wrappers. If you experience compilation problems, the best thing to do is to edit `src/conf.h' after configuration and remove the line beginning `#define HAVE_LIBWRAP'.

Newer solaris systems have ACLs. The ACL features only matured in version 2.5 of solaris however, and there have been some problems with the partial implementation in 2.4. If you obtain error messages about unknown ACL functions, edit the `config.cache' file in the cfengine root directory and set the value:

ac_cv_header_sys_acl_h=${ac_cv_header_sys_acl_h='no'}

If you use the DCE (Distributed computing environment) cfengine will try to compile the ACL extension for DFS. This requires the DCE library to be present on the system on which you are compiling. On some systems it also requires thread libraries to be present. Unfortunately, the autoconf program which generates the Makefiles cannot detect shared libraries, only archive libraries. This means that you need to edit the `config.cache' file to compile in this support. Set the following values:

ac_cv_lib_dce_main=${ac_cv_lib_dce_main='yes'}
ac_cv_lib_dce_main=${ac_cv_lib_thread_main='yes'}

Finally, although the autoconfiguration program appends the same libraries to each executable, the following libraries are required only by the following programs.

 cfengine   -ldce -lthread -lm

 cfd        -ldb -lpthread

Bug reports and suggestions

If you experience a problem with cfengine, find a bug or have another suggestion which you wish to air, you can send your thoughts to the special mail address bug-cfengine@gnu.org.

Always think a bit before sending a message to the list. This helps to keep down the traffic improves the signal to noise ratio of your thoughts! Try to solve the problem yourself first and look particularly to see whether your system is clean or whether you have installed software or patches which might conflict with cfengine (I can't really imagine how this would happen--but it might). Always be clear about what type of operating system you are running and whether or not it is a complete installation.

Some vendors have begun the practice of distributing systems without key programs like the C compiler, lex and yacc. If you have this problem, you can pick up GNU replacements gcc, flex and bison from any GNU site.

FAQs and Tips

Here is a problem solver: an encyclopaedia of suggestions and uses for cfengine as accumulated over the years. If you have a contribution to make, please send it to help-cfengine@gnu.org. Format your submission like this:

Q:
How do I do....
A:
Very well thank-you....

The table below is updated as the tips occur to me, or as others contribute their own. Please note that any focusing on particular operating systems is purely a matter of personal usage/experience and should not be interpreted as a reflection of how many `bugs' these systems may or may not contain.

General

Q:
How can I check to see what cfengine will do without going through the whole program using `-n'?
A:
Run cfengine with options:

  cfengine -p -d3
This just parses the file and dumps the contents of the parser to the output.
Q:
Why doesn't cfengine have classes for each hour, instead of just for days?
A:
It does from version 1.3.20 and upward. The hours are denoted in 24 hour clock notation by Hr00---Hr23. Other time classes are also possible @xref{Using cfengine as a front-end for cron,Using cfengine as a front-end for cron,Using cfengine as a front-end for cron,cfengine-Tutorial}.
Q:
How can I replace the stupid version of sendmail my vendor ships with my OS with, say, Berkeley sendmail?
A:
First of all, compile your new sendmail in a filesystem which is held separate from the OS, for example `/local/mail'. You can keep all the files under this new file tree. Now you need to replace `/usr/lib/sendmail' with the new version and `/etc/sendmail.cf' or `/etc/mail/sendmail' with the new files, so that the system can find them.

   links:
      /usr/lib/sendmail ->! /local/mail/bin/sendmail
      /etc/sendmail.cf  ->! /local/mail/etc/sendmail.cf
Q:
How can I prevent big log-files like `/var/adm/wtmpx' and `httpd/access_log' from filling up my partitions?
A:
Add a line to disable the files once a week. That way you still get a chance to look at them, but you keep the size down:

   disable::

      Sunday::

         #
         # Do this to throw away old entries
         #

         /var/adm/wtmpx rotate=truncate

         #
         # Or this to keep the last lot
         #

         /var/adm/wtmpx rotate=1
An alternative to using disable would be to use tidy, but then you lose the file once and for all. Note though, that `wtmpx' gets updated all the time, so an age age=0 is necessary to have any effect at all. Some daemons, like `httpd', lose their ability to write to a log file if you rename and create a new file. The rotate feature in cfengine preserves the open file handle, fixing this problem.
Q:
How can I fix exports in cfengine?
A:
This is a complicated matter. There are lots of ways to do it. The key is either to edit the file `/etc/exports' (`/etc/dfs/dfstab' in solaris), or to execute an export (share) command directly from shellcommands. Under Solaris 2 this is quite easy owing to the fact that the file `dfstab' is just a script itself, rather than a configuration file like the old `/etc/exports' file. Since editing is limited and you need to specify a list of hosts which might change in time, one of the following is probably the best bet:

shellcommands:

   solaris::

      "/usr/sbin/share -F nfs -o rw=netgroup /var/mail"
On non-solaris systems:

editfiles:

   { /etc/exports

   AppendIfNoSuchLine "/site/host/fs -access=netgroup"
   }
Q:
How can I distribute key setup files to users and keep them up to date?
A:
The copy facility will distribute to all users if you use the home directive. For instance, to copy a basic `.cshrc' file or `.xsession', you could write

copy:

   /local/masterfiles/.cshrc     dest=home/.cshrc
   /local/masterfiles/.xsession  dest=home/.xsession
Q:
Some users set up their own IRC listen services called "eggdrop" which fill up the disk with all kinds of garbage. How can I kill all these processes?
A:

processes:

  #
  # Most users
  #

  "eggdrop"  signal=kill

  #
  # One wise-guy has renamed the daemon!
  #

  ".*wiseguy.*myegg.*"  signal=kill
Q:
My license server keeps crashing! How can I check that it's ok?
A:

processes:

  #
  # BSD - often need long descriptive lines
  #       to find this daemon
  #

  SetOptionString "-ax"

  # Exactly one should be running

  "lmgrd" matches=1
Q:
I want to use cfengine to keep DNS tables up to date, using editfiles. How can I make cfengine automatically restart the name server after the edits?
A:
This can be done in two ways. Probably, you need to update a serial number as well as restarting the daemon. You might use a Makefile to simplify this.

control:

  actionsequence = ( editfiles control )

  solaris::
           named = ( /usr/sbin/in.named)
  linux:
  freebsd:
           named = ( /usr/sbin/named )
  sun4:
           named = ( /usr/etc/named )

editfiles:

 # edit files here

shellcommands:

   #
   # If you use make to sort out the details
   #

  "/local/gnu/bin/make -f /local/named/Makefile > /dev/null"
Or if you need to explicitly restart the name daemon, you could supplement the above with an explicit restart command (this means you lose the cache),

processes:

  "named" signal=kill restart "$(named)"
Q:
How can I edit all users' login files?
A:
You can use the 'home' pseudo-variable to iterate over all users' homedirectories:

editfiles:

    { home/.cshrc

    # Local fixes

    AppendIfNoSuchLine "alias lp  special-print-command"

    # Security

    DeleteLinesMatching "xhost +"
    }
Q:
How can I kill all processes except for root processes?
A:
The following regular expression matches lines which do not contain the string root:

processes:

 "\(root\)\{0\}"  signal=term # or kill
Q:
How can I make cfengine distribute my `/etc/motd' file?
A:
You will need a master file which contains the text you want to put on your servers. Let us define a variable `masterfile' which contains this. This master file needs to be available on all hosts on a common NFS filesystem, for instance. (This will change when remote copying is implemented in cfengine.) Now you can do something like the following script. Note that we define a version number for motd which just prevents cfengine from editing the file every single time. You have to change this version number yourself in the config file to force an update. If you don't care about this, just leave out the Begin..End parentheses.

control:

masterfile = ( /usr/local/admin/motd-master )

editfiles:

  any::

     { /etc/motd

     BeginGroupIfFileIsNewer "$(masterfile)"
       EmptyEntireFilePlease
       InsertFile "$(masterfile)"
       PrependIfNoSuchLine "This system is running $(class):$(arch)"
       AppendIfNoSuchLine "$(motd_version)"
     EndGroup
     }
Note that, if you want special messages added just for, say, linux, then you can single out linux using a special class, or add a special edit after this one. Note, if you want to keep the first kernel line in this file, you can change this to:
editfiles:

   any::

   { /etc/motd

   BeginGroupIfFileIsNewer "$(masterfile)"
     IncrementPointer "1"
     DeleteLinesAfterThisMatching ".*"
     InsertFile "$(masterfile)"
     AppendIfNoSuchLine "$(motd_version)"
   EndGroup
   }
bug-cfengine exchange: (Reply courtesy of David Masterson).
I like cfengine a lot and it helps me very much, but I am a little concerned about security. I'm using cfengine to keep some files like /etc/hosts /etc/printcap /etc/mount etc. up to date. So cfengine is started by root in a cron job and reads its cfengine.conf file and all the other information from a filesystem which is common to all the systems. If now somebody manage to alter the cfengine.conf file he can do everything he wants. Wouldn't it be a good idea to make the cfengine.conf file something like a pgp signed messages, so that cfengine can test if this file was created by the right person? Or are there other tips to make it more secure? I'm not sure, but I think you're over-reacting or you need to be more specific about where you think the holes are in Cfengine's security. If you follow the tips of any standard systems administrator using cfengine or not, there should be few issues concerning security (ie. if security broke, there would be little chance that cfengine could do anything about it anyway). Ask yourself some of the standard questions with respect to security on UNIX:
  • Who owns your script files?
  • Who can update those script files?
  • If those script files are updated by the wrong person, has your security been purposely broken or does it just have a hole in it?
If you're still worried about the security of your script (be it a cfengine script or not), you could always adjust your cron script to "decrypt" the script file before executing it (see crypt(1)). Personally, I think if you've set the permissions on your script files properly, then, if someone breaks into those scripts, they've already broken into your system to a point where they could do what they wanted anyway.
Q:
How can I distribute password files in cfengine, but keep certain passwords different on some machines, like I can with NIS?
A:
If you keep a file with special local passwords, you can override the password file using editfiles. First you use copy to get the distributed file, then you edit the file like this:

  editfiles:

    { /etc/passwd

    SplitOn ":"

    ForEachLineIn "/usr/local/etc/passwd.local"

       ReplaceLinesMatchingField "1"

    EndLoop
    }
This means, if the first field of each line in the files matches in both files (and both files have the same column format) then replace the line in `/etc/passwd' with the line from `/usr/local/etc/passwd.local'.
Q:
How can I add entries to a list, like in the fiel `/etc/group'?
A:
Okay, suppose you wanted to make sure that a special user was in the group `adm', you would use a construction like this:
  control:

      person = ( new-user )

  editfiles:

   { /etc/group

   BeginGroupIfNoLineMatching "adm.*$(person).*"
     LocateLineMatching "adm.*"
     AppendToLineIfNotContains ",$(person)"
   EndGroup
   }
Q:
How can I take backups with cfengine?
A:
If you have a spare disk partition, you could make a mirror of the most important files. You would use something like this:

 control:

      excludecopy = ( *.mp3 *.o *.dvi *.ps *.zip *tar* *.lnk
                       core a.out *.au *.wav .* *.exe *.tgz )

 copy:

   BackupHost.Hr21::

     /site/host/home dest=/site/host/backup2/u1 r=inf size=<4mb backup=false action=silent
for each partition you want to back up.
Q:
I am using SAMBA and have windows file system data on my unix machine. When I try to make a backup by remote copying files, cfengine goes into a recursive loop when it meets short cuts.
A:
Short cuts do not seem to respect the unix file protocols. They look like directories to cfengine and this causes it problems since they do not parse like directories. Add *.lnk to the list of files to be excluded during the copy.
Q:
Is it possible to force shellcommands to change its working directory? separating the commands with ";" seems to be not possible. shellscripts should not be used for this purpose.
A:
(By Rolf Ebert, ebert@pe-muc.de ) I, too, have the need to pass variables to shellcommands and the shellcommands must be executed in a given directory. Here is how most of my shellcommands look like:
      # generate MMC configs
       '$(shell) "PUBLIC=$(public); export PUBLIC; cd $(public)/mmc/config; ./blinksrv.x.cfm.in > blinksrv.x.cfm"'
$(shell) is defined as '/bin/sh -c'. The actual script to be executed is `blinksrv.x.cfm.in' which is located in `$(public)/mmc/config'. It generates a file in the same directory. As an input parameter the script needs the environment variable `PUBLIC'.
Q: Using cfengine with the AFS.
We use AFS, therefore our directory structures look like this: `/afs/btv.ibm.com/system/current/rs_aix43/...' and so on. I want to build a cf file that can pull what AFS calls the "sysname" into the equation so I can have one cf file that can get data from the proper rs_aix directory depending on what level of AIX, or SUN for that matter, it happens to run on. If I use cfengine's class structure I would have to have a cf file for each AIX/SUN level rather than one that can handle them all. That is why I want exec to work. Can anyone offer an answer to this type of scenario?
A: Courtesy of Jeff Blaine
We reference @sys all the time in our cfengine files. It expands to the current machine's AFS sysname on the fly. It's part of AFS, use it!
control:
  #
  # ... stuff deleted ...
  #
  rcf_repos = ( /afs/whatever/our_admin_area/config )
  #
  # ... stuff deleted ...
  #

copy:

  # ... stuff deleted ...
  #
  #  SunOS 4 and IRIX automountd startup file to define /net -hosts
  #
  (sun4|irix|irix64)::
      $(rcf_repos)/@sys/etc/auto.master dest=/etc/auto.master mode=444 \
owner=root group=1 type=checksum
  #
  # ... stuff deleted ...

AIX

Q:
Hints about AIX?
A:
Send then to bug-cfengine@gnu.org.
Q: I get the error
ld: 0711-317 ERROR: Undefined symbol: .pthread_sigmask
ld: 0711-317 ERROR: Undefined symbol: .pthread_mutex_init
ld: 0711-317 ERROR: Undefined symbol: .pthread_mutex_lock
ld: 0711-317 ERROR: Undefined symbol: .pthread_mutex_unlock
on AIX 4.2
A:
Only AIX 4.3 supports POSIX threads fully. You should compile without thread support.
Q:
One of our Sysadmins has noted a limitation with line length under AIX. I'm not sure how easy it is to fix but it might be worth noting it somewhere in the cfengine docs. It appears that on the AIX machines the maximum line length we can use for cfengine files is defined by the constant YYLMAX which is set to be 200. On the Suns this constant is set to be the same as BUFSIZ which is currently set to be 1024. This manifested itself by very unusual behavior as cfengine variables began to be overwritten when line lengths in the config file exceeded 200 bytes. Peter can attest to this. Be forewarned "keep line lengths in cfengine less than 200 if you want them to work on AIX machines" Moral of the story "AIX users beware" Do you think we could just recompile cfengine and use larger buffer sizes all over, I don't know if this constant is all that should be tweaked or if it is somehow tied into the lexx implementation also, since lexx is used to create the parser for the config files.
A:
This is a problem with lex and yacc, not with cfengine. The variable BUFSIZ is a system quantity, not related to cfengine's internal variable bufsize. I would recommend getting bison and flex and doing away with the old lex and yacc from the system. Michael Lachowski reports that this is also a problem with HPUX 10's lex/yacc.

BSDI

Q:
The following error occurs while compiling:

% ./configure
loading cache ./config.cache
checking host system type... i386-pc-bsdi3.1
checking target system type... i386-pc-bsdi3.1
checking build system type... i386-pc-bsdi3.1
expr: syntax error, last argument was `'
test: syntax error: Undefined error: 0
expr: syntax error, last argument was `'
test: syntax error: Undefined error: 0
expr: syntax error, last argument was `'
test: syntax error: Undefined error: 0
checking whether make sets ${MAKE}... (cached) yes
checking for gcc... (cached) gcc
checking whether the C compiler (gcc  ) works... yes
checking whether the C compiler (gcc  ) is a cross-compiler... no
...
A:

  To correct this for BSDI I replaced the following script fragment from
configure:

-------------------------------------------------------------------------
#
# Add to the default list of places in LDFLAGS to compensate for
# ... the configure default value of LIBS on some systems
#
for x in /usr/local/gnu/lib /usr/local/gnulib /usr/local/lib /usr/lib /lib
do
  if test -d "$x"; then
    y=`expr match "$LDFLAGS" ".*-L$x"`
    if test $y -eq 0; then
      LDFLAGS="$LDFLAGS -L$x"
    fi
  fi
done

#
# Add to the default list of places in CPPFLAGS to match LDFLAGS above
#
for x in /usr/include /usr/local/gnu/include /usr/local/include
do
  if test -d "$x"; then
    y=`expr match "$CPPFLAGS" ".*-I$x"`
    if test $y -eq 0; then
      CPPFLAGS="$CPPFLAGS -I$x"
    fi
  fi
done
------------------------------------------------------------------------

   With this script fragment, which successfully executed:

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

#
# Add to the default list of places in LDFLAGS to compensate for
# ... the configure default value of LIBS on some systems
#
for x in /usr/local/gnu/lib /usr/local/gnulib /usr/local/lib /usr/lib /lib
do
  if test -d "$x"; then
    case $LDFLAGS in
    .*-L$x)
      LDFLAGS="$LDFLAGS -L$x"
      ;;
    esac
  fi
done

#
# Add to the default list of places in CPPFLAGS to match LDFLAGS above
#
for x in /usr/include /usr/local/gnu/include /usr/local/include
do
  if test -d "$x"; then
    case $CPPFLAGS in
    .*-I$x)
      CPPFLAGS="$CPPFLAGS -I$x"
      ;;
    esac
  fi
done
-----------------------------------------------------------------------

   I have not completed compiling, installing, testing yet, but presume I
should be fine from here. Thanks for the help.

-Jeff
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Jeff Reed
    Berkeley Software Design, Inc.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HPUX

Q:
Problems with line length in lex/yacc.
A:
See the FAQ for AIX.
Q:
What is the difference between the classes `hpux' and `hpux10'?
A:
In version 10 of HPUX, the file structure is reorganized to look more like SVR4. If you have an HPUX-10 system, the appropriate hardclass is hpux10 rather than hpux.
Q:
I set up the new sendmail but the configuration file doesn't work.
A:
There could be a frozen configuration file around. Try:
disable:

   hpux::

      /usr/lib/sendmail.fc
Q:
Why don't groups work in HPUX?
A:
HPUX uses the file `/etc/logingroup' not `/etc/group'. Make a link if you need to:
links:

  hpux::

     /etc/logingroup -> /etc/group
To encourage some cross-fertilization, here's a sanitized sendmail configuration script that I created for HPUX and HPUX10. (From David Masterson, posted to gnu.cfengine.help). David's script is nice since sendmail was the inspiration for cfengine's name.
#!/usr/local/bin/cfengine -f
####################################################
#
# File:		sendmail.conf
#
# Description: 	CFEngine script to setup the sendmail.cf.
#
####################################################

control:

    access = ( root )

#	Postmaster
    sysadm = ( myPostmaster )

#	NIS domain and group server
    site = ( myserver )

#	DNS domain
    domain = ( myDNSdomain )

#	our gateway host
    gtwyhost = ( mygateway )

#	sendmail.cf can be big
    editfilesize = ( 1000000 )

    actionsequence =
        (
        copy
        files
        editfiles
        shellcommands
        )

#	disable unwanted classes with "--undefine" option
    addclasses = ( maildom mailhst )

################
#	bindir - location of sendmail
#	libdir - location of current mail files
#	cfgdir - location of initial mail files
#	etcdir - location of hosts.smtp
#	own    - who should own result files
#	grp    - what group should result files be in
################
    hpux::
    bindir = ( /usr/lib )
    libdir = ( /usr/lib )
    cfgdir = ( /etc/newconfig )
    etcdir = ( /etc )
    own = ( root )
    grp = ( sys )

    hpux10::
    bindir = ( /usr/sbin )
    libdir = ( /etc/mail )
    cfgdir = ( /usr/newconfig/etc/mail )
    etcdir = ( /etc )
    own = ( root )
    grp = ( sys )

#	disable with "--no-copy" option
copy:

    $(cfgdir)/sendmail.cf dest=$(libdir)/sendmail.cf type=checksum
        mode=0644 owner=$(own) group=$(grp) force=true

#	checks for other important files
files:

    $(libdir)/aliases mode=444 owner=$(own) group=$(grp) action=touch
    $(libdir)/rev-aliases mode=444 owner=$(own) group=$(grp) action=touch
    $(etcdir)/hosts.smtp mode=444 owner=$(own) group=$(grp) action=touch

#	disable with "--no-edit" option
editfiles:

    any::

#	setup general part of sendmail.cf
    { $(libdir)/sendmail.cf

    SetCommentStart '#'
    SetCommentEnd ''
    ResetSearch "1"
    UnCommentLinesMatching "#OP.*"	# activate Postmaster
    ResetSearch "1"
    UnCommentLinesMatching "#DY.*"
    ResetSearch "1"
    LocateLineMatching "DY.*"
    ReplaceLineWith "DY$(site).$(domain)"	# set site hiding
    ResetSearch "1"
    UnCommentLinesMatching "#DS.*"
    ResetSearch "1"
    LocateLineMatching "DS.*"
    ReplaceLineWith "DS$(gtwyhost)"	# all-knowing SMTP host
    # Ruleset 0 setups
    ResetSearch "1"
    UnCommentLinesMatching "#R.*user@domain to SMTP relay.*"
    ResetSearch "1"
    LocateLineMatching "# try to connect to any host for user@domain"
    IncrementPointer "1"
    CommentNLines "1"
    }

#	add Postmaster alias
    { $(libdir)/aliases

    SetLine "Postmaster: $(sysadm)"
    AppendIfNoLineMatching "Postmaster.*"
    }

#	setup processing of local domain hosts
    maildom::

    { $(libdir)/sendmail.cf

    SetCommentStart '#'
    SetCommentEnd ''
    ResetSearch "1"
    LocateLineMatching "DL.*"
    ReplaceLineWith "DL$(domain)"
    # Ruleset 0 setups
    ResetSearch "1"
    LocateLineMatching "# connect to hosts in local domain"
    IncrementPointer "1"
    UnCommentNLines "1"
    }

#	setup processing via class S
    mailhst::

    { $(libdir)/sendmail.cf

    SetCommentStart '#'
    SetCommentEnd ''
    ResetSearch "1"
    UnCommentLinesMatching "#FS.*"
    # Ruleset 0 setups
    ResetSearch "1"
    LocateLineMatching "# connect to hosts in class S"
    IncrementPointer "1"
    UnCommentNLines "1"
    }

#	setup of list of hosts for class S
    { $(etcdir)/hosts.smtp

    EmptyEntireFilePlease
    Append "localhost1"
    Append "localhost2"
    }

#	disable with "--no-commands" option
shellcommands:

    "$(bindir)/sendmail -bk"
    "$(bindir)/sendmail -bi"
    "$(bindir)/sendmail -bz"
    "$(bindir)/sendmail -bd"

################
# End of File
################

IRIX

Q:
Hints about IRIX?
A:
Send them to bug-cfengine@gnu.org.

LINUX

Q:
When I try to compile cfd I get this error
 /usr/lib/libwrap.a(options.o): In function `twist_option':
 options.o(.text+0x5f7): undefined reference to `deny_severity'
 /usr/lib/libwrap.a(options.o): In function `severity_option':
 options.o(.text+0x808): undefined reference to `deny_severity'
 options.o(.text+0x81c): undefined reference to `deny_severity'
 options.o(.text+0x821): undefined reference to `deny_severity'
 options.o(.text+0x826): undefined reference to `deny_severity'
 options.o(.text+0x82b): undefined reference to `allow_severity'
 make[1]: *** [cfd] Error 1
A:
There seems to be a problem with the distributed version of the TCP wrappers library. Edit the `src/conf.h' file and comment out the `#define HAVE_LIBWRAP 1' line. This means that you will not be able to use TCP wrappers security however. You might prefer to collect and compile a new version of TCP wrappers.
Q:
Linux insists on rebuilding the message of the day file each time it boots, but that means I keep losing the messages I leave there.
A:
Add the following to your configuration files to comment out the offending lines in the startup scripts:
editfiles:

   linux::

    { /etc/rc.d/rc.S

    HashCommentLinesContaining "motd"
    }

OSF

Q:
Hints about OSF/1?
A:
Send them to bug-cfengine@gnu.org.

SUNOS (4.1.*)

Q:
How can I delete the `+' sign from the `/etc/hosts.equiv' file to improve security?
A:
Use editfiles to delete it:
editfiles:

   sun4::

      { /etc/hosts.equiv

      DeleteLinesMatching "+"
      }

SOLARIS 2

Q:
I keep getting a `bad address' error when cfengine tries to reset the netmask and broadcast address.
A:
This is a bug in the sockets library on solaris. It is supposed to be fixed in solaris 2.5.
Q:
How can I add my own file `rc.local' to the startup bootfiles automatically?
A:
For example, create a file called `/local/etc/rc.local' which looks something like this:
#
# rc.local
#
PATH=/local/gnu/bin:/bin:/usr/bin:/usr/sbin; export PATH

#!/bin/sh

if [ "`hostname`" = "net-server" ]; then

   echo Starting WWW server
   /local/httpd_1.4/httpd -d /local/httpd_1.4

   echo Starting GNU finger server
   /local/etc/fingerd

fi

echo Starting ypbind
/usr/lib/netsvc/yp/ypbind

echo Adding a default route and flushing table

route -f add default my-gateway 1

echo Starting xdm

/local/bin/start-xdm
Now add an entry to your `cfengine.conf' file like this

   solaris::

      { /etc/rc3.d/S99rc-local

      AutoCreate
      AppendIfNoSuchLine "exec sh /local/etc/rc.local"
      }
Q:
The solaris installation program creates `/tmp' without the sticky bit set, so that any user can delete any files in `/tmp'. It also means that a race condition can occur in the kernel which can give away root access to any user!
A:
Add the following line to the configuration immediately!

files:

   /tmp mode=1777 action=fixdirs
Q:
The ftp program will not allow me to log in to my own account!
A:
The problem is that your shell is not in the system file `/etc/shells'. Add a line something like this:

editfiles:

   { /etc/shells

   AppendIfNoSuchLine "/local/bin/tcsh"
   }
Q:
tcsh prints an error message on startup and will not read my `.cshrc' file.
A:
The problem is the central login file distributed with solaris. `tcsh' can't understand it. Add a line

disable:

    /etc/.login type=file
You might want to replace this with a link to your own file.
Q:
Why does solaris fill up the routing table with hundreds of addresses under the loop-back interface? (see netstat -r)
A:
First of all, get the latest patches for solaris, there are bugs in the kernel of solaris 2.4 which makes this worse. Second, make sure you have a file `/etc/defaultrouter' with the IP address of your local gateway, if you don't intend to run your system as a router. For instance:
files:

  solaris::

     /etc/defaultrouter o=root g=other m=644 act=touch

editfiles:

   solaris::

      { /etc/defaultrouter

      AppendIfNoSuchLine "xxx.xxx.xxx.1"
      }
where xxx.xxx.xxx.1 is the IP address of your gateway.
Q:
When trying to boot the system, solaris fails with the error message: fork: rescource temporarily unavailable/vfork failed. The system then claims that there is something wrong with one of the file systems.
A:
The file `/etc/system' has probably been corrupted. If this file does not exist, solaris establish the kernel properly and will not fork any processes. Things usually die early on in the boot process. This causes the side effect that the first fork the system needs to perform (to check the disk file systems) fails and misinterprets the reason for failure of the command. This makes it look as though something is wrong with the disks. Add a line:

files:

   /etc/system o=root g=root m=0644 action=touch
Q:
I am currently involved with setting up machines with jumpstart. Jumpstart as you may know allows handsfree installation of solaris. One of the things it allows you to do is specify a "finish" script. I am running cfengine from this script to do the bulk of the configuration. During jumpstart, the root of the machine you are installing is actually under "/a". This leads to problems with cfengine with LOCKFILEDIR and LOGFILEDIR at the very least. It would cause problems with all assumptions cfengine makes about system files too. What would be execeedingly nice would be a command line option to redefine where root is assumed to be. I realize this would be pretty hairy with respect to mounting through cfengine, but it would be very useful. For file editing and such a root prefix macro woudlprobably work ok. Let me know what you think.
A:
Define the filenames
 $(root)/filename
and set $(root) to "" or "/a" depending on context? That way you could the above without screwing up other things which might be needed. You can switch off the locks with -K. And you could override the `vfstab' location for solaris in the resource file.

FreeBSD

Q:
How can I stop my FreeBSD system from running the `/etc/daily' script which mails me every single day, week and month?
A:
Add an editfiles command

 freebsd::

   { /etc/crontab

   HashCommentLinesContaining "daily"
   HashCommentLinesContaining "weekly"
   HashCommentLinesContaining "monthly"
   }
Q:
Why don't filesystems get mounted in the freebsd version of cfengine?
A:
Cfengine fixes the `/etc/fstab' file, but has to choose between one of two courses of action when mounting, owing to a bug in the mount command on FreeBSD machines. Cfengine mounts filesystems each time it runs. On all other supported systems this causes no problems,: once a filesystem is mounted it will not be mounted again. Under FreeBSD however, a filesystem gets mounted again each time mount is run, leading to multiple mount information in the mount table. This causes cfengine to warn the filesystem is mounted many times, and could eventually result in a problem for the FreeBSD machine. The policy is therefore to use mount options which do not cause this behaviour, but an unfortunate side-effect is that newly defined filesystems do not get mounted. You can override the mount options if you want to force multiple mounting.

Using the help scripts

The following Perl scripts are included as examples and helpful tools in your system administration package. If you do not have Perl, you should get it -- it is a very useful language for system administration.

cfwrap

It is useful to run cfengine on a daily basis from a cron script. Use a line like the following one to start cfengine each night. (Note the curiosities of older BSD cronfiles).

0 0 * * * /usr/local/lib/cfengine-3.0/bin/cfwrap cfdaily

where cfdaily is a script which looks something like

#!/bin/sh

CFINPUTS=/usr/lib/cfengine/inputs

/usr/local/bin/cfengine

You will need to include full path names to the scripts in the cron file. The syntax for using cfwrap is as follows.

host% cfwrap mycommand

host% cfwrap cfengine

host% cfwrap script_which_sets_CFINPUTS_and_calls_cfengine

When you run cfengine it normally only generates output if something is wrong which needs your attention. If you are running cfengine as a cron job then the results of each job are normally mailed back to you -- or to root. But this causes problems in a networked environment, since mail to root is usually redirected to some central place which local system administrators cannot access. Moreover, you have no way of knowing which host sent the information. The solution is to use a script as a wrapper. The script simply executes some command and collects the output from that command into a file which then gets mailed to some address.

The address to be mailed to is obtained directly from cfengine by calling it with the -a switch. The name of the host running cfengine is prepended to the file before it is sent making it easy to see where each message originated. This is also transferred to the subject header of the mail message. cfwrap calls cfmail in order to mail the result of the command back to the system administrator.

cfmail

Because there are no standard mail-agents except for sendmail, the wrapper script cfwrap calls its own simple mail agent cfmail to send the message. Note that the flags variable in the script cfmail arranges for the mail message to be sent with a return address other than "root". This means that if the recipient of the mail should decide to hit `r' for `reply' to reply to the message, you have a chance of getting to see the message before it vanishes along with the rest of the mail to root into the same black hole that swallows up all those credit cards, house-keys and odd socks that disappear on a daily basis.

You might have to tweak the scripts slightly to tailor them to your own needs. They are used as follows:

host% echo test ....  | cfmail -s "Test message" mark

Example configuration files

Here is a sample from a large configuration file, just to give you some ideas. The file is broken up into manageable pieces for convenience.

cfengine.conf

#####################################################################
#
#  CFENGINE CONFIGURATION FOR site = iu.hioslo.no
#
#  This file is for root only.
#
######################################################################

###
#
# BEGIN cfengine.conf
#
###

import:

   #
   # Split things up to keep things tidy
   #

   any::
                    cf.groups
                    cf.main
                    cf.site
                    cf.motd

   hpux::           cf.hpux
   linux::          cf.linux
   solaris::        cf.solaris
   sun4::           cf.sun4
   ultrix::         cf.ultrix
   freebsd::        cf.freebsd

   #
   # Do you want to do this ?
   #

   AllHomeServers:: cf.users

###
#
# END cfengine.conf
#
###

cf.groups

##############################################################
#
# cf.groups - for iu.hioslo.no
#
# This file contains  all group/class definitions
#
#################################################################

###
#
# BEGIN cf.groups
#
###

groups:

   #
   # Define some groups
   #

   iu = ( nexus ferengi regula borg dax lore axis worf daystrom voyager
          aud1 aud2 aud3 aud4 bajor ds9 takpah takpeh nostromo galron
          thistledown rama chaos pc-steinarj pc-hildeh way jart kosh )

   diskless   = ( regula ferengi lore )

   standalone = ( nexus axis dax borg worf daystrom voyager
                  aud1 aud2 aud3 aud4 bajor ds9 takpah takpeh
                  nostromo galron thistledown rama pc-torejo
                  pc-steinarj pc-hildeh )

   AllHomeServers   = ( nexus )
   AllBinaryServers = ( nexus borg )

   XBootServer  = ( nexus )
   WWWServers   = ( nexus )
   FTPserver    = ( nexus )
   NameServers  = ( nexus )
   PasswdServer = ( nexus )
   BackupHost   = ( nexus )

   MailHub      = ( nexus )
   MailClients  = ( iu -nexus )

###
#
# END cf.groups
#
###

cf.main

##############################################################
#
# cf.main - for iu.hioslo.no
#
# This file contains generic config stuff
#
#################################################################

###
#
# BEGIN cf.main
#
###

control:

   access    = ( root )        # Only root should run this

   site      = ( iu )
   domain    = ( iu.hioslo.no )
   sysadm    = ( drift@iu.hioslo.no )

   repository = ( /var/spool/cfengine )

   netmask   = ( 255.255.255.0 )
   timezone  = ( MET )
   nfstype   = ( nfs )

   sensiblesize  = ( 1000 )
   sensiblecount = ( 2 )
   editfilesize  = ( 20000 )

   mountpattern = ( /$(site)/$(host) )
   homepattern  = ( u? )

   #
   # If we undefine this with cfengine -N longjob
   # then we switch off all jobs labelled with this class
   #

   addclasses = ( longjob )

   #
   # Macros & constants are inherited downwards in imports
   # but are not passed up to parent files. Good idea to
   # define them all here
   #

   masterfiles = ( /iu/nexus/local/iu )
   main_server = ( nexus )
   cfbin       = ( /iu/nexus/local/gnu/lib/cfengine/bin )
   gnu         = ( /local/gnu )
   ftp         = ( /local/iu/ftp )
   nisslave    = ( dax )
   nisfiles    = ( /iu/nexus/local/iu/etc )

   #
   # The action sequence for daily (full) runs and
   # for hourly updates (called with -DHourly)
   #

   Hr00::

      actionsequence =
         (
         copy
         mountall
         mountinfo
         checktimezone
         netconfig
         resolve
         unmount
         shellcommands
         addmounts
         links.Prepare
         files.Prepare
         directories
         links.Rest
         mailcheck
         mountall
         required
         tidy
         disable
         editfiles
         files.Rest
         processes
         )

   !Hr00::

      actionsequence =
         (
         resolve
         shellcommands
         copy
         editfiles
         processes
     links
         )

   force::

      actionsequence =
         (
         files.Prepare.Rest
         tidy
         )

######################################################################

homeservers:

   iu:: nexus

binservers:

   iu.solaris::                 nexus
   iu.linux::                   borg

mailserver:

   any:: nexus:/var/mail

mountables:

   any::
         nexus:/iu/nexus/u1
         nexus:/iu/nexus/u2
         nexus:/iu/nexus/u3
         nexus:/iu/nexus/u4
         nexus:/iu/nexus/u5
         nexus:/iu/nexus/u6
         nexus:/iu/nexus/ua
         nexus:/iu/nexus/ud
         nexus:/iu/nexus/local
         nexus:/opt/NeWSprint
         nexus:/opt/AcroRead
         borg:/iu/borg/local
         dax:/iu/dax/local

miscmounts:

   linux||freebsd::   nexus:/iu/nexus/local /iu/nexus/local ro

######################################################################

broadcast:

  ones

defaultroute:

   cadeler30-gw

######################################################################

resolve:

      128.39.89.10  # nexus
      158.36.85.10  # samson.hioslo.no
      129.241.1.99

######################################################################

tidy:

   #
   # Some global tidy-ups
   #

      /tmp/                    pat=*             r=inf     A=1
      /var/tmp                 pat=*             r=inf     A=1
      /                        pat=core          r=1       A=0
      /etc                     pat=core          r=1       A=0

######################################################################

ignore:                       # Don't check or tidy these directories

      /local/lib/gnu/emacs/lock/
      /local/tmp
      ftp
      projects
      /local/bin/top
      /local/lib/tex/fonts
      /local/iu/etc
      /local/etc
      /local/iu/httpd/conf
      /usr/tmp/locktelelogic
      /usr/tmp/lockIDE
      RootMailLog

      #
      # Emacs lock files etc
      #

      !*
      /local/lib/xemacs

      #
      # X11 keeps X server data in /tmp/.X11
      # better not delete this!
      #

      .X11

      #
      # Some users like to give a file or two 777 protection here
      # so netsurfers can update a log or counter when running as
      # `nobody'
      #

      www

#####################################################################

disable:

   /etc/hosts.equiv
   /etc/nologin
   /usr/lib/sendmail.fc

###
#
# END cf.main
#
###

cf.site

##############################################################
#
# cf.site - for iu.hioslo.no
#
# This file contains site specific data
#
#################################################################

###
#
# BEGIN cf.site
#
###

links:

   Prepare::

      /local     -> /$(site)/$(binserver)/local
      /usr/local -> /local

   dax::

      /iu/dax/local             +> /iu/nexus/local
      /projects                 -> /iu/dax/local/projects
      /iu/nexus/u1/sowille/data -> /iu/dax/scratch/data

   XBootServer::

      #
      # Set up a /local/tftpboot area where all X terminal
      # stuff will be kept.
      #

      /tftpboot                  -> /local/tftpboot
      /local/tftpboot/td/configs -> /local/tftpboot/td/examples/configs
      /etc/bootptab              -> /tftpboot/bootptab
      /tftpboot/usr/lib/X11/td   -> /tftpboot/td

   NameServers::

      /etc/named.boot -> /local/iu/named/named.boot

   MailHub::

      /etc/mail/sendmail.cf ->! /iu/nexus/local/mail/sendmail.cf

   MailClients.solaris::

      /etc/mail/sendmail.cf ->! /iu/nexus/local/mail/client.cf

   nexus::

    /local/bin +> /local/latex/bin

#############################################################

disable:

  #
  # We run Berkeley sendmail and the config files are
  # all under /iu/nexus/local/lib/mail
  #

    /etc/aliases

 WWWServers.Sunday::

   #
   # Disabling these log files weekly prevents them from
   # growing so enormous that they fill the disk!
   #

   /local/iu/httpd/logs/access_log   rotate=empty
   /local/iu/httpd/logs/agent_log    rotate=empty
   /local/iu/httpd/logs/error_log    rotate=empty
   /local/iu/httpd/logs/referer_log  rotate=empty

   #
   # CERT warning, security fix
   #

  any::

    /usr/lib/expreserve

  FTPserver.Sunday.Hr00::

   /local/iu/xferlog rotate=3

#################################################################

files:

  Prepare::

      /etc/motd              m=0644 r=0 o=root act=touch
      /.cshrc                m=0644 r=0 o=root act=touch

   PasswdServer::

      /local/iu/etc/passwd m=0644 o=root g=other action=fixplain
      /local/iu/etc/shadow m=0644 o=root g=other action=fixplain

   WWWServers.Rest::

      /local/iu/www                           m=775        g=www act=fixall r=inf
      /local/iu/httpd/conf                    m=664 o=root g=www act=fixall r=inf
      /local/iu/www/cgi-bin-public/count_file m=777 o=root g=www act=fixplain

   FTPserver::

      #
      # Make sure anonymous ftp areas have the correct
      # protection, or logins won't be able to read
      # files - or perhaps a security risk. This is
      # solaris 2 specific...
      #

      $(ftp)/pub        mode=755 o=ftp  g=ftp  r=inf act=fixall
      $(ftp)/Obin       mode=111 o=root g=other      act=fixall
      $(ftp)/etc        mode=111 o=root g=other      act=fixdirs
      $(ftp)/usr/bin/ls mode=111 o=root g=other      act=fixall
      $(ftp)/dev        mode=555 o=root g=other      act=fixall
      $(ftp)/usr        mode=555 o=root g=other      act=fixdirs

   Prepare::

      /etc/shells mode=0644 action=touch

   AllBinaryServers.Rest.longjob::

     /local mode=-0002 r=inf owner=root,bin group=0,1,2,3,4,5,6,7,staff
            links=tidy action=fixall

     /local/iu/RootMailLog  m=0666 action=touch

   dax.Rest::

    /iu/dax/scratch        r=0 o=root mode=1777 action=fixall
    /iu/dax/local/projects r=0 o=root mode=755  action=fixdirs

   nexus::

    /local/mail/sendmail.cf o=root m=444 act=fixplain

    /iu/nexus/ua/robot/.rhosts o=robot m=600 act=touch

    /local/iu/named/pz         o=root  m=644 act=fixall r=1

    /local/latex/lib/tex/texmf/fonts  owner=root
                                      mode=1666
                                      recurse=inf
                                      action=fixall

#################################################################

tidy:

      #
      # Make sure the file repository doesn't fill up
      #

      /var/spool/cfengine pattern=*    age=3

      /var                pattern=core age=0  r=inf
      /var/spool/mqueue   pattern=*    age=14 type=mtime

   BackupHost::

      # Here we tidy old backup tar files from the backup area
      # A special tmp area gets cleared every 4 days. The files
      # are created by Audun's backup help script (see shellcommands)

      /iu/nexus/backup1      pat=*  age=7

#################################################################

shellcommands:

   PasswdServer::

      # Build and install the BSD compatible passwd file
      # from the master passwd/shadow file on solaris

      "/local/iu/bin/BuildPasswdFiles"
      "/local/iu/bin/BuildGroupFiles"

  BackupHost.Sunday.Hr00|BackupHost.Wednesday.Hr00::

      #
      # Make a system backup of /iu/nexus/u? with Audun's script
      #

      "$(cfbin)/cfbackup -p -f /iu/nexus/backup1 -s /iu/nexus/ud"
      "$(cfbin)/cfbackup -p -f /iu/nexus/backup1 -s /iu/nexus/ua"
      "$(cfbin)/cfbackup -p -f /iu/nexus/backup1 -s /iu/nexus/u1"
      "$(cfbin)/cfbackup -p -f /iu/nexus/backup1 -s /iu/nexus/u2"
      "$(cfbin)/cfbackup -p -f /iu/nexus/backup2 -s /iu/nexus/u3"
      "$(cfbin)/cfbackup -p -f /iu/nexus/backup2 -s /iu/nexus/u4"
      "$(cfbin)/cfbackup -p -f /iu/nexus/backup2 -s /iu/nexus/u5"
      "$(cfbin)/cfbackup -p -f /iu/nexus/backup2 -s /iu/nexus/u6"

  nexus.Sunday.longjob.Hr00::

      #
      # See how much rubbish users have accumulated each Sunday
      #

      "$(cfbin)/noseyparker /iu/nexus/u1 $(sysadm) "
      "$(cfbin)/noseyparker /iu/nexus/u2 $(sysadm) "
      "$(cfbin)/noseyparker /iu/nexus/u3 $(sysadm) "
      "$(cfbin)/noseyparker /iu/nexus/u4 $(sysadm) "
      "$(cfbin)/noseyparker /iu/nexus/u5 $(sysadm) "
      "$(cfbin)/noseyparker /iu/nexus/u6 $(sysadm) "
      "$(cfbin)/noseyparker /iu/nexus/ua $(sysadm) nomail"
      "$(cfbin)/noseyparker /iu/nexus/ud $(sysadm) nomail"

   nexus.longjob.Hr00::

      #
      # Update the GNU find/locate database each night
      #

      "$(gnu)/lib/locate/updatedb"
      "/local/iu/bin/newhomepage.sh"

###############################################################

editfiles:

    #
    # cfengine installs itself as a cron job - sneaky! :)
    #

    { /var/spool/cron/crontabs/root

    AppendIfNoSuchLine "0 * * * * $(cfbin)/cfwrap $(cfbin)/cfhourly"
    }

   FTPserver::

      { /etc/shells

      AppendIfNoSuchLine "/bin/tcsh"
      AppendIfNoSuchLine "/local/gnu/bin/bash"
      }

   XBootServer::

      { /etc/inetd.conf

      AppendIfNoSuchLine
          "bootp dgram udp wait root /local/bin/bootpd bootpd -i -d"
      }

   nexus::

      { /iu/nexus/ua/robot/.rhosts

      AppendIfNoSuchLine "borg"
      AppendIfNoSuchLine "borg.iu.hioslo.no"
      AppendIfNoSuchLine "aud4"
      AppendIfNoSuchLine "aud4.iu.hioslo.no"
      }

   dax::

      { /etc/system

      AppendIfNoSuchLine "set pt_cnt=128"
      }

######################################################################

required:

   #
   # Any host must have a /local, /usr/local fs. Check that
   # it exists and looks sensible. (i.e. not empty)
   #

   /$(site)/$(binserver)/local

######################################################################

copy:

   #
   # NIS seems broken at IU, so here we use NFS to fudge
   # a file distribution as a temporary solution. Actually
   # this makes the system work faster without NIS!
   #

      $(nisfiles)/services dest=/etc/services o=root g=other mode=0644
      $(nisfiles)/hosts.deny dest=/etc/hosts.deny o=root mode=0644

   !debian::

      $(nisfiles)/hosts    dest=/etc/hosts o=root g=other mode=0644

   PasswdServer::

      /etc/passwd dest=$(nisfiles)/passwd o=root g=other mode=0644
      /etc/shadow dest=$(nisfiles)/shadow o=root g=other mode=0644

   nexus::

      /local/iu/etc/dfstab dest=/etc/dfs/dfstab  o=root  mode=0744

   solaris.!PasswdServer::

      $(nisfiles)/passwd dest=/etc/passwd o=root g=other mode=0644
      $(nisfiles)/shadow dest=/etc/shadow o=root g=other mode=0600
      $(nisfiles)/group.solaris dest=/etc/group o=root g=other mode=0644

   linux::

      $(nisfiles)/passwd.linux dest=/etc/passwd o=root g=other mode=0644
      $(nisfiles)/group.linux dest=/etc/group o=root g=other mode=0644

###############################################################

processes:

      "eggdrop"                           signal=kill
      "irc"                               signal=kill
      "ping"                              signal=kill
      "NetXRay"                           signal=kill
      "netxray"                           signal=kill
      "ypserv"                            signal=kill
      "ypbind"                            signal=kill
      "rarpd"                             signal=kill
      "rpc.boot"                          signal=kill
      "README"                            signal=kill # You don't sh README !

   !XBootServer::

      "bootp"                             signal=kill

   #
   # These processes are not killed every hour, but once a day
   # when cfengine runs at night. Note that there are often
   # hanging pine and elm processes. These programs crash and
   # go berserk, using hundreds of hours of CPU time.
   #

   Hr00::

      "cron"                 signal=hup  # HUP these to update their config
      "inetd"                signal=hup

      "/local/sdt/sdt/bin"   signal=term # For those elektro dudes who forget
                                         # to log out
      "netscape"             signal=kill
      "pine"                 signal=kill
      "elm"                  signal=kill

###
#
# END cf.site
#
###

cf.motd

##################################################################
#
# cf.motd
#
# This file is used to set the message of the day file on
# each host
#
##################################################################

 #####
 #
 # BEGIN cf.motd
 #
 #####

control:

   #
   # This points to the file containing general text
   #

   masterfile      = ( /iu/nexus/local/iu/etc/motd-master )
   local_message   = ( /etc/motd.local )

editfiles:

      { /etc/motd

      BeginGroupIfFileIsNewer "$(masterfile)"
        EmptyEntireFilePlease
        InsertFile "$(masterfile)"
        InsertFile "$(local_message)"
        PrependIfNoSuchLine "This system is running $(class):$(arch)"
      EndGroup
      }

 #####
 #
 # BEGIN cf.motd
 #
 #####

cf.users

Whether or not you perform any special services for users, with or without their consent is entirely a matter of local policy. In a school or college situation, users are often uncooperative and some are even irresponsible. This file shows you what you could do in an environment with inexperienced users, but please don't feel as though you have to be this totalitarian.

#################################################################
#
# cf.users - for iu.hioslo.no
#
# This file contains user specific actions
#
#################################################################

###
#
# BEGIN cf.users
#
###

ignore:

    robot

tidy:

   longjob::

     #
     # Some users just don't understand what they are doing
     # and this is safest, allbeit totalitarian
     #

     home                 pat=.rhosts                      age=0

     #
     # Tidy up users' home dirs
     #

     home                 pat=core             r=inf       age=0
     home                 pat=a.out            r=inf       age=1
     home                 p=*%                 r=inf       age=2
     home                 p=*~                 r=inf       age=2
     home                 p=#*                 r=inf       age=1
     home                 p=*.dvi              r=inf       age=14   type=ctime
     home                 p=*.log              r=inf       age=2
     home                 p=Log.*              r=inf       age=3
     home                 p=CKP                r=inf       age=1
     home                 p=BAK                r=inf       age=1
     home                 p=log                r=inf       age=0
     home                 p=*.o                r=inf       age=0
     home                 p=*.aux              r=inf       age=3
     home                 p=*.zip              r=inf       age=7
     home/.deleted        p=*                  r=inf       age=0
     home/.wastebacket    p=*                  r=inf       age=14
     home/www             p=*~                 r=inf       age=1

     #
     # Clear the big cache files netscape creates
     #

     home/.netscape-cache  p=cache????*         r=inf       age=0
     home/.MCOM-cache      p=cache????*         r=inf       age=0
     home/.netscape/cache  p=*                  r=inf       age=0

#################################################################

files:

   AllHomeServers.longjob.rest::

     #
     # Check users files are not writable to the world
     # and there are no stale links (pointing nowhere)
     #

     home mode=o-w recurse=inf action=fixall # links=tidy

     home/.xsession mode=755 action=fixall
     home/.cshrc    mode=755 action=fixall

#################################################################

copy:

   Hr00.longjob::

   #
   # Make sure each user has an up to date standard
   # setup.  Cshrc just sources in a big standard file
   # which is kept in ~user/../.setupfiles/cshrc
   # to reduce disk wastage
   #

   $(masterfiles)/lib/Cshrc   dest=home/.cshrc
   $(masterfiles)/lib/tkgrc   dest=home/.tkgrc
   $(masterfiles)/lib/fvwm2rc dest=home/.fvwm2rc

###
#
# END cf.users
#
###

cf.solaris

#################################################################
#
# cf.solaris - for iu.hioslo.no
#
# This file contains solaris specific patches
#
#################################################################

###
#
# BEGIN cf.solaris
#
###

directories:

     #
     # httpd/netscape want this to exist for some bizarre reason
     #

      /usr/lib/X11/nls

################################################################

tidy:

     /var/log  pattern=syslog.* age=0

   MailHub::

     /var/mail pattern=lp       age=0

#################################################################

files:

  #
  # If this doesn't exist fork will not work and the
  # system will not even be able to run the /etc/rc
  # scripts at boottime
  #

  /etc/system     o=root g=root m=644 action=touch

  /var/log/syslog o=root        m=666 action=touch

#############################################################

copy:

   #
   # Some standard setup files, can't link because
   # machine won't boot if their not on / partition.
   #

   /local/bin/tcsh dest=/bin/tcsh mode=755

   /local/iu/etc/nsswitch.standalone dest=/etc/nsswitch.conf

  #
  # Our named server uses a newer BIND
  # Put this here so that it will be preserved under
  # solaris reinstallation
  #

  NameServers::

   /local/iu/sbin/in.named         dest=/usr/sbin/in.named         mode=555
   /local/iu/sbin/in.named.reload  dest=/usr/sbin/in.named.reload  mode=555
   /local/iu/sbin/in.named.restart dest=/usr/sbin/in.named.restart mode=555
   /local/iu/sbin/in.ndc           dest=/usr/sbin/in.ndc           mode=555
   /local/iu/sbin/named-xfer       dest=/usr/sbin/named-xfer       mode=555
   /local/iu/lib/nslookup.help     dest=/usr/lib/nslookup.help     mode=444

  any::
   /local/iu/lib/libresolv.a        dest=/usr/lib/libresolv.a      mode=444
   /local/iu/lib/libresolv.so.2     dest=/usr/lib/libresolv.so.2   mode=444
   /local/bin/nslookup              dest=/usr/sbin/nslookup        mode=444

##############################################################

editfiles:

      { /etc/netmasks

      AppendIfNoSuchLine "128.39  255.255.255.0"
      }

      { /etc/defaultrouter

      AppendIfNoSuchLine "128.39.89.1"
      }

      { /usr/openwin/lib/app-defaults/XConsole

      AppendIfNoSuchLine "XConsole.autoRaise: on"
      }

   #
   # CERT security patch for vold vulnerability
   #

   { /etc/rmmount.conf

   HashCommentLinesContaining "action cdrom"
   HashCommentLinesContaining "action floppy"
   }

##############################################################

disable:

    /etc/.login  type=file
    /etc/aliases

   #
   # These files are ENORMOUS, don't let them fill the disk
   #

   Wednesday::

      /var/lp/logs/lpsched rotate=empty

      /var/adm/wtmpx       rotate=empty
      /var/adm/wtmp        rotate=empty

##############################################################

files:

    /etc/passwd        m=0644 o=root g=other action=fixplain
    /etc/shadow        m=0600 o=root g=other action=fixplain
    /etc/defaultrouter m=0644 o=root g=other action=touch
    /var/adm/wtmpx     m=0664 o=adm  g=adm   action=touch
    /var/adm/wtmp      m=0644 o=root g=adm   action=touch
    /var/adm/utmp      m=0644 o=root g=adm   action=fixplain
    /var/adm/utmpx     m=0664 o=adm  g=adm   action=fixplain

    /tmp m=1777                              action=fixdirs

##############################################################

disable:

   #
   # CERT security patch
   #

   /usr/openwin/bin/kcms_calibrate
   /usr/openwin/bin/kcms_configure
   /usr/bin/admintool

################################################################

shellcommands:

   AllBinaryServers.Saturday.longjob.Hr00::

      #
      # Make sure the man -k / apropos data are up to date
      #

      "/usr/bin/catman  -M /local/man"
      "/usr/bin/catman  -M /local/X11R5/man"
      "/usr/bin/catman  -M /usr/man"
      "/usr/bin/catman  -M /local/gnu/man"
      "/usr/bin/catman  -M /usr/openwin/share/man"
      "/usr/bin/catman  -M /local/X11R5/man"
      "/usr/bin/catman  -M /usr/share/man"

################################################################

editfiles:

      #
      # A painless way to add an rc.local script to the rc files
      # under solaris without having to fight though inittab
      #

      { /etc/rc3.d/S15nfs.server

      AppendIfNoSuchLine "sh /local/iu/etc/rc.local"
      }

      #
      # umask defined when inetd starts is inherited by all subprocesses
      # including ftpd which saves with mode 666 (!) unless we do this
      #

      { /etc/rc2.d/S72inetsvc

      PrependIfNoSuchLine "umask 022"
      }

###
#
# END cf.solaris
#
###

cf.linux

#################################################################
#
# cf.linux - for iu.hioslo.no
#
# This file contains debian linux specific patches
#
#################################################################

###
#
# BEGIN cf.linux
#
###

files:

      /etc/printcap m=644 o=root action=fixplain

     #
     # Cert advisories
     #

      /bin/mount         m=755 o=root action=fixall
      /bin/umount        m=755 o=root action=fixall

#######################################################################

  disable:

     #
     # Cert advisories
     #

      /sbin/dip-3.3.7n

########################################################################

links:

    /local/bin/tcsh   ->  /bin/tcsh

    /local/lib/mail   ->  /$(site)/$(main_server)/local/lib/mail

########################################################################

editfiles:

  #
  # Samba default mode needs to be set...
  #

   { /etc/smb.conf

   ReplaceAll "700" With "644"
   }

  #
  # Linux date is very stupid and needs a very careful
  # TZ definition, otherwise it loses
  #

   { /etc/csh.cshrc

   AppendIfNoSuchLine "setenv TZ 'MET-1MET DST-2,M3.5.0/2,M10.5.0/3'"
   }

  #
  # resolv+ ordering
  #

   { /etc/host.conf

   PrependIfNoSuchLine "order bind"
   }

  #
  # Should have been configured already (!)
  #

   { /etc/ld.so.conf

   AppendIfNoSuchLine "/usr/X11R6/lib"
   }

  #
  # Kill annoying messages
  #

   { /etc/cron.daily/standard

   HashCommentLinesContaining "security"
   }

#########################################################################

shellcommands:

  Hr00::

     #
     # Find/locate database
     #

     "/usr/bin/updatedb"

###
#
# END cf.linux
#
###

cf.freebsd / cf.netbsd

FreeBSD, OpenBSD and NetBSD are sufficiently similar to have a single file for all.

#################################################################
#
# cf.bsd - for iu.hioslo.no
#
# This file contains bsd specific patches
#
#################################################################

###
#
# BEGIN cf.bsd
#
###

links:

    /usr/spool        ->  /var/spool
    /local/bin/tcsh   ->  /bin/tcsh
    /local/bin/perl   ->  /usr/bin/perl
    /usr/lib/sendmail ->  /usr/sbin/sendmail

#################################################################

files:

   /usr/tmp mode=1777 owner=root action=fixall

#################################################################

editfiles:

   #
   # Comment out all lines to shut up this annoying cfengine-like
   # script, which sends mail every day!!!
   #

   { /etc/crontab

   HashCommentLinesContaining "daily"
   HashCommentLinesContaining "weekly"
   HashCommentLinesContaining "monthly"
   }

#################################################################

copy:

      $(masterfiles)/etc/printcap.client      dest=/etc/printcap mode=0644

#########################################################################

shellcommands:

  Hr00::

    "/usr/libexec/locate.updatedb"
    "/usr/bin/makewhatis /usr/share/man:/usr/X11R6/man"

###
#
# END cf.bsd
#
###

cfd.conf

#########################################################
#
# This is a cfd config file
#
# The access control here follows after any tcpd
# control in /etc/hosts.allow and /etc/hosts.deny
#
#########################################################

 #
 # Could import cf.groups here and use a structure like
 # in cfengine.conf, cf.main, cf.groups
 #

control:

  public = ( /usr/local/publicfiles )

  almost_public = ( /usr/local/almostpublicfiles )

  cfrunCommand = ( /iu/nexus/ud/mark/comp/Tests/cfrun-command )

  MaxConnections = ( 10 )

#########################################################

admit:   # or grant:

     $(public) *

     $(almost_public) *.iu.hioslo.no *.gnu.ai.mit.edu

     /etc/passwd *.iu.hioslo.no

     #
     # Who can exec cfengine remotely?
     #

     $(cfrunCommand) *.iu.hioslo.no

#########################################################

deny:

     $(public)/special *.moneyworld.com

Runtime Options

Note that GNU long options are available with the syntax --longoption. The long names are given in brackets.

`-a'
(--sysadm) Print only the name of the system administrator then quit.
`-A'
(--auto) Can be used to signify an automatic run of cfengine, as opposed to a manual run. The distinction is not predetermined. Use of this option currently causes cfengine to ignore locks. This option is reserved for future development.
`-b'
(--force-net-copy) Normally cfengine detects attempts to copy from a server via the network, if they loop back to the localhost. It then avoids using the network to make the copy. This option forces cfengine to copy using the network. (Yes, someone thinks this is useful!)
`-c'
(--no-check-files) Do not check file systems for ownership / permissions etc.
`-C'
(--no-check-mounts) Check mount points for consistency. If this option is specified then directories which lie in the "mount point" area are checked to see whether there is anything mounted on them. Normally this is off since not all machines use mounted file systems in the same way. e.g. HPUX does not generally operate with partitions, but nevertheless one might wish to mimick a partition-like environment there, but it would be irritating to be informed that nothing was mounted on the mount point.
`-d'
(--debug) Enable debugging output. Normally you will want to send this to a file using the shell script command or a pipe. -d1 shows only parsing output. -d2 shows only runtime action output. -d0 shows both levels. Debugging ouput is intended mainly for the author's convenience and is not a supported feature. The details of this output may change at any time.
`-D'
(--define) Define a compound class symbol of the form alpha.beta.gamma.
`-e'
(--no-edits) Suppress file editing.
`-E'
(--enforce-links) Globally force links to be created where plain files or links already exist. Since this option is a big hammer, you have to use it in interactive mode and answer a yes/no query before cfengine will run like this.
`-f'
(--file) Parse filename after this switch. By default cfengine looks for a file called cfengine.conf in the current directory.
`-h'
(--help) Help information. Display version banner and options summary.
`-H'
(--no-hard-classes). Prevents cfengine from generating any internal class name information. Can be used for emulation purposes.
`-i'
(--no-ifconfig) Do not attempt to configure the local area network interface.
`-I'
(--inform) Switches on the inform output level, whereby cfengine reports everything it changes..
`-k'
(--no-copy) Do not copy/image any files.
`-K'
(--no-lock) Ignore locks when running.
`-l'
(--traverse-links) Normally cfengine does not follow symbolic links when recursively parsing directories. This option will force it to do so.
`-L'
(--delete-stale-links) Delete links which do not point to existing files (except in user home directories, which are not touched).
`-m'
(--no-mount) Do not attempt to mount file systems or edit the filesystem table.
`-M'
(--no-modules) Ignore modules in actionsequence.
`-n'
(--recon,--dry-run,--just-print) No action. Only print what has to be done without actually doing it.
`-N'
(--negate,--undefine) Cancel a set of classes, or undefine (set value to false) a compound class of the form alpha.beta.gamma.
`-p'
(--parse-only) Parse file and then stop. Used for checking the syntax of a program. You do not have to be superuser to use this option.
`-q'
(--no-splay) Switch off host splaying (sleeping).
`-s'
(--no-commands) Do not execute scripts or shell commands.
`-S'
(--silent) Silence run time warnings.
`-t'
(--no-tidy) Do not tidy file systems.
`-u'
(--use-env) Causes cfengine to generate an environment variable `CFALLCLASSES' which can be read by child processes (scripts). This variable contains a summary of all the currently defined classes at any given time. This option causes some system 5 systems to generate a Bus Error or segmentation fault. The same information is available from the cfengine internal variable $(allclasses) and can be passed as a parameter to scripts.
`-U'
(--underscore-classes). When this option is set, cfengine adds an underscore to the beginning of the hard system classes (like _sun4, _linux etc. The longer compound classes are not underscored, since these are already complex and would unlikely result in collisions.) This can be used to avoid naming conflicts if you are so unjudicious as to name a host by the name of a hard class. Other classes are not affected.
`-v'
(--verbose) Verbose mode. Prints detailed information about actions and state.
`-V'
(--version) Print only the version string and then quit.
`-x'
(--no-preconf) Do not execute the `cf.preconf' net configuration file.
`-X'
(--no-links) Do not execute the links section of a program.
`-w'
(--no-warn,--quiet) Do not print warning messages.

Cfengine network protocol specs

Cfengine uses a simple protocol for communicating via a streams-based tcp connection. This section documents the protocol for anyone who might want to create their own clients or server components to interface with cfengine. Several transfers use a standard buffer size of 4096 bytes. The get-file service uses a character based read interface in which the buffer size is not directly relevant; the size of the get-file buffer is dictated by client-side disk blocksizes.

Each new connection to the remote server daemon must begin with a verification or `login' string whereby the client identifies itself to the server. This information is used to verify the connection by using a reverse DNS lookup and then a double-reverse lookup. This is the basis of hostname authentication.

The various services are listed below:

Stat file
  AUTH client-name server-name
  SYNCH long-time-string STAT filename

  reply with OK: <stat-reply-string>
Get file
   AUTH client-name server-name
   GET filename

   reply with <stream>, break on zero chars received
   or BAD: <message>
Opendir
Recursive parsing of directory trees poses a technical problem. If cfengine keeps a connection open and send buffers on a need-to-know basis, then the number of daemon connections will mount up and overload the server. If cfengine caches the entire directory on the client side, allowing the server connection to be severed, then the caching could easily fill the memory of the client. The policy chosen is to attempt to cache all names client-side, in spite of the possible memory problem. The reason for this choice is that, even on large filesystems (max size of paritions with 32 bit pointers is 4GB), the sum memory used by every filename is only of the order of a few megabytes, and this is within reasonable modern memory limits. It is assumed that, even 64 bit users will not create filesystems which are much large than this.
    AUTH client-name server-name
    OPENDIR dir-name

    reply with <stream>, break on zero chars received
In the future it might be useful to stat the file automatically here and cache the value client-side.
Exec
       AUTH client-name server-name
       EXEC option-string
       CLASSES stream terminated with --- (CFD_TERMINATE)

       reply with <stream>, break on zero chars received
Checksum verification
       MD5 filename 16 byte sequence

       reply with CFD_TRUE for no match (copy) or CFD_FALSE for match (no copy)
Reply formatting
The format of reply messages, except for stream data, is

  OK: message

  BAD: message
A return prefix of `BAD' implies a failure server-side and the client-side wrapper functions return -1 in this case. The server daemon currently runs single threaded for all requests except GetFile. Since cfd uses heavyweight processes for general applicablity this avoids unnecessary forking and context switching which would download the server. An upper limit on the number of forks which may be performed is set in the config file. This is mananged using the SIGCHLD signal and a pair of arrays in the master processes (This approach is used to avoid shared memory and semaphore usage which is not portable to many older BSD derivative systems).

Variable Index

Jump to: + - - - . - / - a - b - c - d - e - f - g - h - i - l - m - n - o - p - r - s - t - u - w - z

+

  • +

    • -

  • -a option
  • -D option
  • -l, -l
  • -L
  • -N option
  • -x option

    • .

  • .cfengine.rm

    • /

  • /etc/host.conf

    • a

  • a=, a=
  • action
  • actionsequence, actionsequence
  • AddClasses
  • AddInstallable
  • addmounts
  • age

    • b

  • backup=
  • binserver, binserver
  • binservers
  • broadcast

    • c

  • cf.preconf
  • CFALLCLASSES
  • cfrc
  • checktimezone
  • childlinks
  • control
  • create

    • d

  • directories
  • disable, disable
  • domain, domain
  • DryRun

    • e

  • editfiles
  • editfilesize, editfilesize
  • empty
  • exclude=

    • f

  • FileExtensions
  • files, files
  • filter
  • force=
  • freespace=, freespace=

    • g

  • g=
  • group
  • groups

    • h

  • home
  • HomePattern
  • homepattern
  • homeservers

    • i

  • import
  • include=
  • interface configuration
  • InterfaceName

    • l

  • l=
  • link
  • linkchildren, linkchildren
  • links, links

    • m

  • m=
  • mailcheck, mailcheck
  • mailserver
  • miscmounts
  • mode
  • module:
  • moduledirectory
  • mountables, mountables
  • mountall
  • mountinfo
  • mountpattern

    • n

  • netconfig
  • netmask, netmask
  • nfstype, nfstype

    • o

  • o=
  • ones
  • owner

    • p

  • p=
  • pattern
  • processes
  • purge=

    • r

  • r=, r=
  • recurse, recurse
  • RepChar
  • required
  • resolve, resolve
  • Restricting access
  • rotate=

    • s

  • SecureInput
  • sensiblecount
  • SensibleCount
  • SensibleSize
  • sensiblesize
  • shellcommands
  • ShowActions
  • singlelinks
  • site, site
  • split
  • SuspiciousNames
  • sysadm, sysadm

    • t

  • tidy, tidy
  • timezone
  • touch
  • truncate
  • type=, type=

    • u

  • unmount, unmount

    • w

  • Wildcards

    • z

  • zeroes
  • zeros

    • Concept Index

    Jump to: - + - - - . - / - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - q - r - s - t - u - v - w - x - y - z

    • +

  • `+' symbol in `/etc/hosts.equiv'

    • -

  • --dry-run option
  • -a option
  • -D option
  • -L option
  • -l option, -l option
  • -x option

    • .

  • .cfdisabled
  • .cfengine.rm
  • `.cfnew' files
  • `.cfsaved' files
  • `.cshrc', distributing
  • .X11 directory
  • `.xsession', distributing

    • /

  • `/etc/defaultroute'
  • /etc/host.conf
  • `/etc/hosts.equiv'
  • `/etc/shells'
  • `/tmp' under solaris

    • a

  • Absolute links
  • Access control
  • Access control lists
  • ACL key
  • ACLs
  • action sequence
  • Adding defined classes
  • Adding new classes
  • AFS
  • AFS and cfengine
  • allclasses variable
  • Andrew filesystem
  • AppendToLineIfNotContains, example
  • atime tidies
  • AutoCreate
  • automounter
  • awk, editing

    • b

  • Backup of files in copy
  • Backups, with copy
  • Bad address error in solaris
  • BeginGroupIfFileExists
  • BeginGroupIfFileIsNewer
  • Berkeley database library
  • Berkeley sendmail
  • Binary servers and links, Binary servers and links
  • Binary servers, defining
  • Binary servers, priority, Binary servers, priority
  • Bootstrap file
  • Broadcast address
  • Broadcast with solaris 2.4
  • Bugs, reporting

    • c

  • CatchAbort
  • cd in shellcommands
  • `cf.groups'
  • `cf.main'
  • `cf.motd'
  • cf.preconf bootstrap file
  • `cf.site', `cf.site'
  • CFALLCLASSES
  • Cfengine security worries
  • `cfengine.conf'
  • cfrc resource file
  • cfwrap, wrapper script
  • Class decided by shell command
  • Class dependencies
  • Class information, passing to scripts
  • classes, classes, classes
  • Classes, adding and defining
  • control section
  • Controlling log-files
  • Controlling the size of log files
  • copy, copy
  • Copy, exact filetree images
  • Copying files
  • Creating files
  • cron script to start cfengine
  • ctime tidies

    • d

  • db library
  • DCE key
  • Deadlock
  • Deadlock zombie bug in restart
  • Declaring classes
  • Decrementing line pointer in editfiles
  • Default route, cannot set
  • `defaultroute'
  • Defining a binary server
  • Defining a home server
  • Defining a mail server
  • Defining a mountable
  • Defining before use
  • Defining classes, Defining classes, Defining classes
  • Defining groups
  • Deleting directories
  • Deleting files
  • Deleting stale links, Deleting stale links
  • Dependencies
  • Device boundaries
  • Device boundaries and files
  • DFS
  • DHCP
  • Directories, deleting
  • Directories, hidden
  • Directories, making
  • Directory for cfengine modules
  • Directory permissions
  • disable, problems with logging afterwards
  • disable, trimming log files
  • Disabling file types
  • Disabling files
  • disks actions
  • Distributing files
  • Distributing user files
  • DNS
  • domain
  • Domain name
  • Double quotes
  • DryRun
  • Dual homed hosts

    • e

  • Editing users login files
  • Empty files
  • Environment variable CFALLCLASSES
  • Example configuration files
  • Excluding classes
  • Excluding files from a file sweep
  • exports, fixing

    • f

  • FAQs
  • Field separator in editfiles
  • File images (copy)
  • File management
  • File sizes, specifying
  • File tree images
  • Files, breaking up into several
  • Files, checking permissions
  • Files, home wildcard
  • Files, importing
  • Files, ownership
  • Files, recursion
  • Files, setting owner
  • Files, syntax
  • Flex and bison problem
  • Force copying
  • Fork error in solaris
  • FreeBSD mount problem
  • freespace=, freespace=
  • Frequently asked questions
  • Frozen configuration files
  • ftp and alternative shells
  • ftp login problems
  • Full disk warnings, Full disk warnings

    • g

  • Group dependencies
  • Group field, editing
  • groups
  • groups
  • Groups, defining

    • h

  • Hardlinks
  • Help scripts
  • Hints and Tips
  • home directive
  • Home path
  • Home servers, defining
  • home wildcard
  • Homepattern variable.
  • `hosts.equiv'
  • Hour classes
  • How can I make cfengine distribute my `/etc/motd' file?
  • httpd problem with logging
  • Hung machine

    • i

  • ignore command
  • Import files, variables in
  • Importing files
  • Incrementing line pointer in editfiles
  • Interface name, redefining by class
  • InterfaceName
  • Internal classes, switching off
  • Internet address
  • IP address
  • Iterating over lists in shellcommands
  • Iteration over lists

    • k

  • Key, ACL
  • Kill processes not owned by root
  • Killing processes
  • Kilobyte, filesize unit

    • l

  • lex and yacc problems
  • Linkchildren, Linkchildren
  • Links and binary servers, Links and binary servers
  • Links, absolute, Links, absolute
  • Links, deleting stale, Links, deleting stale
  • Links, forcing for non-existent files
  • Links, making
  • Links, multiple
  • Links, removing dead
  • Links, single
  • Links, traversing in searches, Links, traversing in searches
  • Linux, installing
  • Local disk space, make use of
  • Local startup file for solaris
  • Log files, controlling the size of
  • Log-files, preventing overflow
  • Login files, editing for all users

    • m

  • Mail agent
  • Mail from scripts
  • Mail server, defining
  • Making backups
  • Making directories
  • Making links
  • Making paths
  • Making use of local disk space
  • Master files, updating from
  • Megabytes, filesize unit
  • Message of the day files
  • Miscellaneous mount operations
  • Module directory
  • Modules, user defined
  • Mount paths
  • Mountable resources, defining, Mountable resources, defining
  • Mounted filesystems
  • Mounting filesystems.
  • mtime tidies
  • Multiple links

    • n

  • Negating classes
  • Negating entries from netgroups
  • Netgroups
  • Netgroups and Linux
  • Netgroups, negating entries
  • netmask
  • Netmask
  • Netmask with solaris 2.4
  • Network interfaces, several
  • New systems, support for
  • nfs
  • NFS mount model and automounter
  • nfstype
  • NIS, netgroup support
  • NT, ACL

    • o

  • ones
  • Ownership of files

    • p

  • Password file, editing
  • Path to home directories
  • Path to mounted filesystems
  • Paths, making
  • Pattern matching in file sweeps
  • Permissions, directories
  • Preserving file times in copy
  • Previewing shellcommands
  • Processes, 0 to 3
  • Processes, check if running
  • Processes, checking existence of
  • Processes, counting
  • Processes, killing
  • Processes, signalling

    • q

  • Quoted strings

    • r

  • `rc.local' in solaris
  • Recursion in files
  • Relative links
  • Removing directories
  • Removing entries from netgroups
  • Renaming files
  • Replacing file by link
  • Reporting bugs
  • Repository filenames, changing
  • resolv.conf
  • Resolver configuration
  • Resource file
  • Restart zombie deadlock bug
  • Restricting the size of files to be edited
  • rmdirs
  • Rotating log files
  • routed
  • Running cfengine, cron script

    • s

  • Scripts and class information
  • Scripts, examples
  • Scripts, writing
  • Search patterns in files
  • Searching for home directories
  • Searching, advanced
  • Secure input
  • Security under solaris
  • Security with NIS
  • sed, editing
  • Selecting files in searches
  • sendmail, sendmail
  • Sendmail configuration
  • `sendmail.fc'
  • Sensible file sizes
  • Sensible limits on files in a directory
  • Setting uid on restarted processes
  • Setting working directory in shellcommands
  • Several files
  • sharing filesystems
  • Shell command to decide class
  • Single links
  • Single quotes
  • site
  • size field in disable
  • Solaris and tcsh
  • Solaris routing bug
  • Solaris, `/tmp'
  • Solaris, security
  • Specifying file sizes
  • split
  • SplitOn
  • Starting cfengine, cron script
  • Subnet mask
  • Support for new systems
  • suspiciousnames
  • Switching off backup in copy
  • Switching off internal classes
  • Symbolic links, absolute
  • Symbolic links, relative
  • sysadm

    • t

  • TCP wrappers
  • tcsh and solaris
  • Tidy by ctime, mtime, atime
  • Tidying empty files
  • Tidying files
  • Time classes, hours
  • timeout= in shellcommands
  • Timeouts during iterations
  • Tips using cfengine
  • Too many open files error
  • Touching files
  • Tree copying, exact
  • Truncating log files

    • u

  • umask, umask, umask
  • Unmounting filesystems
  • Updating files from master source

    • v

  • Variables in import files

    • w

  • Warning about full disks, Warning about full disks
  • Wildcard home
  • Wildcards in homepattern
  • Working directory in shellcommands
  • Wrapper script
  • wtmpx
  • WWW server logs

    • x

  • xdev (File system boundaries)

    • y

  • yacc problems

    • z

  • zeros

    • FAQ Index

    Jump to: / - a - b - c - d - e - f - g - h - i - k - l - m - p - r - s - t - w

    /

  • `/etc/system' missing in solaris.

    • a

  • Action contains invalid statement problem
  • AFS help

    • b

  • Bad address error in solaris
  • BSDI configuration problems

    • c

  • cfd fails to compile
  • Cfengine security worries
  • Changing repository name conventions
  • Configure problem, BSDI
  • copy doesn't always copy files
  • ctime copy doesn't always copy files

    • d

  • Daily mail in FreeBSD
  • Difference between hpux and hpux10
  • Distribute key set up files to users

    • e

  • Edit all users login files
  • Edit and restart DNS

    • f

  • Fix exports in cfengine
  • Fixing /tmp permissions in solaris
  • Fork: resource unavailable in solaris
  • FreeBSD daily mail
  • FreeBSD mount doesn't work
  • Frozen configuration files
  • ftp, can't log in

    • g

  • Groups in hpux

    • h

  • Hanging commands, timeouts
  • Hey! Cannot stat file error
  • How can I add users to the `/etc/group' file?
  • How can I avoid hanging shellcommands?
  • How can I make cfengine distribute my `/etc/motd' file?
  • How can I override passwords locally?
  • How can I set a timeout for a shell command?
  • How do I configure sendmail?
  • How do I set a working directory for a shell command?
  • How to create files while editing

    • i

  • Iterating over lists

    • k

  • Kill all processes except root
  • Kill user processes
  • Killing "eggdrop"

    • l

  • Lex and yacc in AIX/HPUX
  • libwrap problem under compilation
  • License server crashes
  • Line length bug in AIX/HPUX

    • m

  • Message of the day files
  • Message of the day in linux
  • motd in linux
  • Mount filesystems fails in solaris

    • p

  • Prevent big log-files

    • r

  • rc.local in solaris
  • Remote copy problems, can't stat
  • Replace the stupid version of sendmail..?
  • Routing problem in solaris

    • s

  • Solaris /tmp sticky bit
  • Sticky bit in solaris /tmp

    • t

  • tcsh and solaris error
  • Too many open files error

    • w

  • Why can't I set a default route?
  • Why doesn't cfengine have classes for each hour..?

    • This document was generated on 22 January 2002 using texi2html 1.56k.


CVS--Concurrent Versions System

Table of Contents

  • About this manual
    • Checklist for the impatient reader
    • Credits
    • BUGS
  • What is CVS?
    • CVS is not...
  • Basic concepts
    • Revision numbers
    • Versions, revisions and releases
  • A sample session
    • Getting the source
    • Committing your changes
    • Cleaning up
    • Viewing differences
  • The Repository
    • Telling CVS where your repository is
    • How data is stored in the repository
      • Where files are stored within the repository
      • File permissions
    • The administrative files
      • Editing administrative files
    • Multiple repositories
    • Creating a repository
    • Remote repositories
      • Connecting with rsh
      • Direct connection with password authentication
        • Setting up the server for password authentication
        • Using the client with password authentication
        • Security considerations with password authentication
      • Direct connection with kerberos
  • Starting a project with CVS
    • Setting up the files
      • Creating a directory tree from a number of files
      • Creating Files From Other Version Control Systems
      • Creating a directory tree from scratch
    • Defining the module
  • Multiple developers
    • File status
    • Bringing a file up to date
    • Conflicts example
    • Informing others about commits
    • Several developers simultaneously attempting to run CVS
    • Mechanisms to track who is editing files
      • Telling CVS to watch certain files
      • Telling CVS to notify you
      • How to edit a file which is being watched
      • Information about who is watching and editing
      • Using watches with old versions of CVS
    • Choosing between reserved or unreserved checkouts
  • Branches
    • Tags--Symbolic revisions
    • What branches are good for
    • Creating a branch
    • Sticky tags
  • Merging
    • Merging an entire branch
    • Merging from a branch several times
    • Merging differences between any two revisions
    • Merging can add or remove files
  • Recursive behavior
  • Adding files to a directory
  • Removing files from a module
  • Tracking third-party sources
    • Importing a module for the first time
    • Updating a module with the import command
    • How to handle binary files with cvs import
  • Moving and renaming files
    • The Normal way to Rename
    • Moving the history file
    • Copying the history file
  • Moving and renaming directories
  • History browsing
    • Log messages
    • The history database
    • User-defined logging
    • Annotate command
  • Keyword substitution
    • RCS Keywords
    • Using keywords
    • Avoiding substitution
    • Substitution modes
    • Problems with the $@asis{}Log$ keyword.
  • Handling binary files
  • Revision management
    • When to commit?
  • Reference manual for CVS commands
    • Overall structure of CVS commands
    • Default options and the ~/.cvsrc file
    • Global options
    • Common command options
    • admin--Administration front end for rcs
      • admin options
      • admin examples
        • Outdating is dangerous
        • Comment leaders
    • checkout--Check out sources for editing
      • checkout options
      • checkout examples
    • commit--Check files into the repository
      • commit options
      • commit examples
        • New major release number
        • Committing to a branch
        • Creating the branch after editing
    • diff--Run diffs between revisions
      • diff options
      • diff examples
    • export--Export sources from CVS, similar to checkout
      • export options
    • history--Show status of files and users
      • history options
    • import--Import sources into CVS, using vendor branches
      • import options
      • import output
      • import examples
    • log--Print out log information for files
      • log options
      • log examples
    • rdiff---'patch' format diffs between releases
      • rdiff options
      • rdiff examples
    • release--Indicate that a Module is no longer in use
      • release options
      • release output
      • release examples
    • rtag--Add a symbolic tag to a module
      • rtag options
    • status--Display status information on checked out files
      • status options
    • tag--Add a symbolic tag to checked out versions of files
      • tag options
    • update--Bring work tree in sync with repository
      • update options
      • update output
      • update examples
  • Reference manual for the Administrative files
    • The modules file
    • The cvswrappers file
    • The commit support files
      • The common syntax
    • Commitinfo
    • Editinfo
      • Editinfo example
    • Loginfo
      • Loginfo example
      • Keeping a checked out copy
    • Rcsinfo
    • Ignoring files via cvsignore
    • The history file
    • Expansions in administrative files
  • All environment variables which affect CVS
  • Troubleshooting
    • Magic branch numbers
  • GNU GENERAL PUBLIC LICENSE
  • Index

Version Management

with

CVS

for CVS 1.9

Per Cederqvist et al

Copyright (C) 1992, 1993 Signum Support AB

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" and this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.

About this manual

Up to this point, one of the weakest parts of CVS has been the documentation. CVS is a complex program. Previous versions of the manual were written in the manual page format, which is not really well suited for such a complex program.

When writing this manual, I had several goals in mind:

  • No knowledge of RCS should be necessary.
  • No previous knowledge of revision control software should be necessary. All terms, such as revision numbers, revision trees and merging are explained as they are introduced.
  • The manual should concentrate on the things CVS users want to do, instead of what the CVS commands can do. The first part of this manual leads you through things you might want to do while doing development, and introduces the relevant CVS commands as they are needed.
  • Information should be easy to find. In the reference manual in the appendices almost all information about every CVS command is gathered together. There is also an extensive index, and a lot of cross references.

This manual was contributed by Signum Support AB in Sweden. Signum is yet another in the growing list of companies that support free software. You are free to copy both this manual and the CVS program. See section GNU GENERAL PUBLIC LICENSE, for the details. Signum Support offers support contracts and binary distribution for many programs, such as CVS, GNU Emacs, the GNU C compiler and others. Write to us for more information.

Signum Support AB
Box 2044
S-580 02  Linkoping
Sweden

Email: info@signum.se
Phone: +46 (0)13 - 21 46 00
Fax:   +46 (0)13 - 21 47 00

Another company selling support for CVS is Cyclic Software, web: http://www.cyclic.com/, email: info@cyclic.com.

Checklist for the impatient reader

CVS is a complex system. You will need to read the manual to be able to use all of its capabilities. There are dangers that can easily be avoided if you know about them, and this manual tries to warn you about them. This checklist is intended to help you avoid the dangers without reading the entire manual. If you intend to read the entire manual you can skip this table.

Binary files
CVS can handle binary files, but you must have RCS release 5.5 or later and a release of GNU diff that supports the `-a' flag (release 1.15 and later are OK). You must also configure both RCS and CVS to handle binary files when you install them. Keword substitution can be a source of trouble with binary files. See section Keyword substitution, for solutions.
The admin command
Careless use of the admin command can cause CVS to cease working. See section admin--Administration front end for rcs, before trying to use it.

Credits

Roland Pesch, Cygnus Support <pesch@cygnus.com> wrote the manual pages which were distributed with CVS 1.3. Appendix A and B contain much text that was extracted from them. He also read an early draft of this manual and contributed many ideas and corrections.

The mailing-list info-cvs is sometimes informative. I have included information from postings made by the following persons: David G. Grubbs <dgg@think.com>.

Some text has been extracted from the man pages for RCS.

The CVS FAQ by David G. Grubbs has provided useful material. The FAQ is no longer maintained, however, and this manual about the closest thing there is to a successor (with respect to documenting how to use CVS, at least).

In addition, the following persons have helped by telling me about mistakes I've made: Roxanne Brunskill <rbrunski@datap.ca>, Kathy Dyer <dyer@phoenix.ocf.llnl.gov>, Karl Pingle <pingle@acuson.com>, Thomas A Peterson <tap@src.honeywell.com>, Inge Wallin <ingwa@signum.se>, Dirk Koschuetzki <koschuet@fmi.uni-passau.de> and Michael Brown <brown@wi.extrel.com>.

BUGS

This manual is known to have room for improvement. Here is a list of known deficiencies:

  • In the examples, the output from CVS is sometimes displayed, sometimes not.
  • The input that you are supposed to type in the examples should have a different font than the output from the computer.
  • This manual should be clearer about what file permissions you should set up in the repository, and about setuid/setgid.
  • Some of the chapters are not yet complete. They are noted by comments in the `cvs.texinfo' file.
  • This list is not complete. If you notice any error, omission, or something that is unclear, please send mail to bug-cvs@prep.ai.mit.edu.

I hope that you will find this manual useful, despite the above-mentioned shortcomings.

Linkoping, October 1993
Per Cederqvist

What is CVS?

CVS is a version control system. Using it, you can record the history of your source files.

For example, bugs sometimes creep in when software is modified, and you might not detect the bug until a long time after you make the modification. With CVS, you can easily retrieve old versions to see exactly which change caused the bug. This can sometimes be a big help.

You could of course save every version of every file you have ever created. This would however waste an enormous amount of disk space. CVS stores all the versions of a file in a single file in a clever way that only stores the differences between versions.

CVS also helps you if you are part of a group of people working on the same project. It is all too easy to overwrite each others' changes unless you are extremely careful. Some editors, like GNU Emacs, try to make sure that the same file is never modified by two people at the same time. Unfortunately, if someone is using another editor, that safeguard will not work. CVS solves this problem by insulating the different developers from each other. Every developer works in his own directory, and CVS merges the work when each developer is done.

CVS started out as a bunch of shell scripts written by Dick Grune, posted to comp.sources.unix in the volume 6 release of December, 1986. While no actual code from these shell scripts is present in the current version of CVS much of the CVS conflict resolution algorithms come from them.

In April, 1989, Brian Berliner designed and coded CVS. Jeff Polk later helped Brian with the design of the CVS module and vendor branch support.

You can get CVS via anonymous ftp from a number of sites, for instance prep.ai.mit.edu in `pub/gnu'.

There is a mailing list, known as info-cvs, devoted to CVS. To subscribe or unsubscribe send a message to info-cvs-request@prep.ai.mit.edu. Please be specific about your email address. As of May 1996, subscription requests are handled by a busy human being, so you cannot expect to be added or removed immediately. The usenet group comp.software.config-mgmt is also a suitable place for CVS discussions (along with other configuration management systems).

CVS is not...

CVS can do a lot of things for you, but it does not try to be everything for everyone.

CVS is not a build system.
Though the structure of your repository and modules file interact with your build system (e.g. `Makefile's), they are essentially independent. CVS does not dictate how you build anything. It merely stores files for retrieval in a tree structure you devise. CVS does not dictate how to use disk space in the checked out working directories. If you write your `Makefile's or scripts in every directory so they have to know the relative positions of everything else, you wind up requiring the entire repository to be checked out. If you modularize your work, and construct a build system that will share files (via links, mounts, VPATH in `Makefile's, etc.), you can arrange your disk usage however you like. But you have to remember that any such system is a lot of work to construct and maintain. CVS does not address the issues involved. Of course, you should place the tools created to support such a build system (scripts, `Makefile's, etc) under CVS. Figuring out what files need to be rebuilt when something changes is, again, something to be handled outside the scope of CVS. One traditional approach is to use make for building, and use some automated tool for generating the depencies which make uses.
CVS is not a substitute for management.
Your managers and project leaders are expected to talk to you frequently enough to make certain you are aware of schedules, merge points, branch names and release dates. If they don't, CVS can't help. CVS is an instrument for making sources dance to your tune. But you are the piper and the composer. No instrument plays itself or writes its own music.
CVS is not a substitute for developer communication.
When faced with conflicts within a single file, most developers manage to resolve them without too much effort. But a more general definition of "conflict" includes problems too difficult to solve without communication between developers. CVS cannot determine when simultaneous changes within a single file, or across a whole collection of files, will logically conflict with one another. Its concept of a conflict is purely textual, arising when two changes to the same base file are near enough to spook the merge (i.e. diff3) command. CVS does not claim to help at all in figuring out non-textual or distributed conflicts in program logic. For example: Say you change the arguments to function X defined in file `A'. At the same time, someone edits file `B', adding new calls to function X using the old arguments. You are outside the realm of CVS's competence. Acquire the habit of reading specs and talking to your peers.
CVS does not have change control
Change control refers to a number of things. First of all it can mean bug-tracking, that is being able to keep a database of reported bugs and the status of each one (is it fixed? in what release? has the bug submitter agreed that it is fixed?). For interfacing CVS to an external bug-tracking system, see the `rcsinfo' and `editinfo' files (see section Reference manual for the Administrative files). Another aspect of change control is keeping track of the fact that changes to several files were in fact changed together as one logical change. If you check in several files in a single cvs commit operation, CVS then forgets that those files were checked in together, and the fact that they have the same log message is the only thing tying them together. Keeping a GNU style `ChangeLog' can help somewhat. Another aspect of change control, in some systems, is the ability to keep track of the status of each change. Some changes have been written by a developer, others have been reviewed by a second developer, and so on. Generally, the way to do this with CVS is to generate a diff (using cvs diff or diff) and email it to someone who can then apply it using the patch utility. This is very flexible, but depends on mechanisms outside CVS to make sure nothing falls through the cracks.
CVS is not an automated testing program
It should be possible to enforce mandatory use of a testsuite using the commitinfo file. I haven't heard a lot about projects trying to do that or whether there are subtle gotchas, however.
CVS does not have a builtin process model
Some systems provide ways to ensure that changes or releases go through various steps, with various approvals as needed. Generally, one can accomplish this with CVS but it might be a little more work. In some cases you'll want to use the `commitinfo', `loginfo', `rcsinfo', or `editinfo' files, to require that certain steps be performed before cvs will allow a checkin. Also consider whether features such as branches and tags can be used to perform tasks such as doing work in a development tree and then merging certain changes over to a stable tree only once they have been proven.

Basic concepts

CVS stores all files in a centralized repository (see section The Repository).

The repository contains directories and files, in an arbitrary tree. The modules feature can be used to group together a set of directories or files into a single entity (see section The modules file). A typical usage is to define one module per project.

Revision numbers

Each version of a file has a unique revision number. Revision numbers look like `1.1', `1.2', `1.3.2.2' or even `1.3.2.2.4.5'. A revision number always has an even number of period-separated decimal integers. By default revision 1.1 is the first revision of a file. Each successive revision is given a new number by increasing the rightmost number by one. The following figure displays a few revisions, with newer revisions to the right.

       +-----+    +-----+    +-----+    +-----+    +-----+
       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
       +-----+    +-----+    +-----+    +-----+    +-----+

CVS is not limited to linear development. The revision tree can be split into branches, where each branch is a self-maintained line of development. Changes made on one branch can easily be moved back to the main trunk.

Each branch has a branch number, consisting of an odd number of period-separated decimal integers. The branch number is created by appending an integer to the revision number where the corresponding branch forked off. Having branch numbers allows more than one branch to be forked off from a certain revision.

All revisions on a branch have revision numbers formed by appending an ordinal number to the branch number. The following figure illustrates branching with an example.

                                                     +-------------+
                          Branch 1.2.2.3.2 ->        ! 1.2.2.3.2.1 !
                                                   / +-------------+
                                                  /
                                                 /
                 +---------+    +---------+    +---------+    +---------+
Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !----! 1.2.2.4 !
               / +---------+    +---------+    +---------+    +---------+
              /
             /
+-----+    +-----+    +-----+    +-----+    +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
+-----+    +-----+    +-----+    +-----+    +-----+
                !
                !
                !   +---------+    +---------+    +---------+
Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
                    +---------+    +---------+    +---------+

The exact details of how the branch number is constructed is not something you normally need to be concerned about, but here is how it works: When CVS creates a branch number it picks the first unused even integer, starting with 2. So when you want to create a branch from revision 6.4 it will be numbered 6.4.2. All branch numbers ending in a zero (such as 6.4.0) are used internally by CVS (see section Magic branch numbers). The branch 1.1.1 has a special meaning. See section Tracking third-party sources.

Versions, revisions and releases

A file can have several versions, as described above. Likewise, a software product can have several versions. A software product is often given a version number such as `4.1.1'.

Versions in the first sense are called revisions in this document, and versions in the second sense are called releases. To avoid confusion, the word version is almost never used in this document.

A sample session

This section describes a typical work-session using CVS. It assumes that a repository is set up (see section The Repository).

Suppose you are working on a simple compiler. The source consists of a handful of C files and a `Makefile'. The compiler is called `tc' (Trivial Compiler), and the repository is set up so that there is a module called `tc'.

Getting the source

The first thing you must do is to get your own working copy of the source for `tc'. For this, you use the checkout command:

$ cvs checkout tc

This will create a new directory called `tc' and populate it with the source files.

$ cd tc
$ ls
CVS         Makefile    backend.c   driver.c    frontend.c  parser.c

The `CVS' directory is used internally by CVS. Normally, you should not modify or remove any of the files in it.

You start your favorite editor, hack away at `backend.c', and a couple of hours later you have added an optimization pass to the compiler. A note to RCS and SCCS users: There is no need to lock the files that you want to edit. See section Multiple developers for an explanation.

Committing your changes

When you have checked that the compiler is still compilable you decide to make a new version of `backend.c'.

$ cvs commit backend.c

CVS starts an editor, to allow you to enter a log message. You type in "Added an optimization pass.", save the temporary file, and exit the editor.

The environment variable $CVSEDITOR determines which editor is started. If $CVSEDITOR is not set, then if the environment variable $EDITOR is set, it will be used. If both $CVSEDITOR and $EDITOR are not set then the editor defaults to vi. If you want to avoid the overhead of starting an editor you can specify the log message on the command line using the `-m' flag instead, like this:

$ cvs commit -m "Added an optimization pass" backend.c

Cleaning up

Before you turn to other tasks you decide to remove your working copy of tc. One acceptable way to do that is of course

$ cd ..
$ rm -r tc

but a better way is to use the release command (see section release--Indicate that a Module is no longer in use):

$ cd ..
$ cvs release -d tc
M driver.c
? tc
You have [1] altered files in this repository.
Are you sure you want to release (and delete) module `tc': n
** `release' aborted by user choice.

The release command checks that all your modifications have been committed. If history logging is enabled it also makes a note in the history file. See section The history file.

When you use the `-d' flag with release, it also removes your working copy.

In the example above, the release command wrote a couple of lines of output. `? tc' means that the file `tc' is unknown to CVS. That is nothing to worry about: `tc' is the executable compiler, and it should not be stored in the repository. See section Ignoring files via cvsignore, for information about how to make that warning go away. See section release output, for a complete explanation of all possible output from release.

`M driver.c' is more serious. It means that the file `driver.c' has been modified since it was checked out.

The release command always finishes by telling you how many modified files you have in your working copy of the sources, and then asks you for confirmation before deleting any files or making any note in the history file.

You decide to play it safe and answer n RET when release asks for confirmation.

Viewing differences

You do not remember modifying `driver.c', so you want to see what has happened to that file.

$ cd tc
$ cvs diff driver.c

This command runs diff to compare the version of `driver.c' that you checked out with your working copy. When you see the output you remember that you added a command line option that enabled the optimization pass. You check it in, and release the module.

$ cvs commit -m "Added an optimization pass" driver.c
Checking in driver.c;
/usr/local/cvsroot/tc/driver.c,v  <--  driver.c
new revision: 1.2; previous revision: 1.1
done
$ cd ..
$ cvs release -d tc
? tc
You have [0] altered files in this repository.
Are you sure you want to release (and delete) module `tc': y

The Repository

The CVS repository stores a complete copy of all the files and directories which are under version control.

Normally, you never access any of the files in the repository directly. Instead, you use CVS commands to get your own copy of the files, and then work on that copy. When you've finished a set of changes, you check (or commit) them back into the repository. The repository then contains the changes which you have made, as well as recording exactly what you changed, when you changed it, and other such information.

CVS can access a repository by a variety of means. It might be on the local computer, or it might be on a computer across the room or across the world. To distinguish various ways to access a repository, the repository name can start with an access method. For example, the access method :local: means to access a repository directory, so the repository :local:/usr/local/cvsroot means that the repository is in `/usr/local/cvsroot' on the computer running CVS. For information on other access methods, see section Remote repositories.

If the access method is omitted, then if the repository does not contain `:', then :local: is assumed. If it does contain `:' than either :ext: or :server: is assumed. For example, if you have a local repository in `/usr/local/cvsroot', you can use /usr/local/cvsroot instead of :local:/usr/local/cvsroot. But if (under Windows NT, for example) your local repository is `c:\src\cvsroot', then you must specify the access method, as in :local:c:\src\cvsroot.

The repository is split in two parts. `$CVSROOT/CVSROOT' contains administrative files for CVS. The other directories contain the actual user-defined modules.

Telling CVS where your repository is

There are a couple of different ways to tell CVS where to find the repository. You can name the repository on the command line explicitly, with the -d (for "directory") option:

cvs -d /usr/local/cvsroot checkout yoyodyne/tc

Or you can set the $CVSROOT environment variable to an absolute path to the root of the repository, `/usr/local/cvsroot' in this example. To set $CVSROOT, all csh and tcsh users should have this line in their `.cshrc' or `.tcshrc' files:

setenv CVSROOT /usr/local/cvsroot

sh and bash users should instead have these lines in their `.profile' or `.bashrc':

CVSROOT=/usr/local/cvsroot
export CVSROOT

A repository specified with -d will override the $CVSROOT environment variable. Once you've checked a working copy out from the repository, it will remember where its repository is (the information is recorded in the `CVS/Root' file in the working copy).

The -d option and the `CVS/Root' file both override the $CVSROOT environment variable. If -d option differs from `CVS/Root', the former is used (and specifying -d will cause `CVS/Root' to be updated). Of course, for proper operation they should be two ways of referring to the same repository.

How data is stored in the repository

For most purposes it isn't important how CVS stores information in the repository. In fact, the format has changed in the past, and is likely to change in the future. Since in almost all cases one accesses the repository via CVS commands; such changes need not be disruptive.

However, in some cases it may be necessary to understand how CVS stores data in the repository, for example you might need to track down CVS locks (see section Several developers simultaneously attempting to run CVS) or you might need to deal with the file permissions appropriate for the repository.

Where files are stored within the repository

The overall structure of the repository is a directory tree corresponding to the directories in the working directory. For example, supposing the repository is in `/usr/local/cvsroot', here is a possible directory tree (showing only the directories):

/usr
 |
 +--local
 |   |
 |   +--cvsroot
 |   |    |
 |   |    +--CVSROOT
          |      (administrative files)
          |
          +--gnu
          |   |
          |   +--diff
          |   |   (source code to GNU diff)
          |   |
          |   +--rcs
          |   |   (source code to RCS)
          |   |
          |   +--cvs
          |       (source code to CVS)
          |
          +--yoyodyne
              |
              +--tc
              |    |
              |    +--man
              |    |
              |    +--testing
              |
              +--(other Yoyodyne software)

With the directories are history files for each file under version control. The name of the history file is the name of the corresponding file with `,v' appended to the end. Here is what the repository for the `yoyodyne/tc' directory might look like:

  $CVSROOT
    |
    +--yoyodyne
    |   |
    |   +--tc
    |   |   |
            +--Makefile,v
            +--backend.c,v
            +--driver.c,v
            +--frontend.c,v
            +--parser.c,v
            +--man
            |    |
            |    +--tc.1,v
            |
            +--testing
                 |
                 +--testpgm.t,v
                 +--test2.t,v

The history files contain, among other things, enough information to recreate any revision of the file, a log of all commit messages and the user-name of the person who committed the revision. The history files are known as RCS files, because the first program to store files in that format was a version control system known as RCS. For a full description of the file format, see the man page rcsfile(5), distributed with RCS. This file format has become very common--many systems other than CVS or RCS can at least import history files in this format.

File permissions

All `,v' files are created read-only, and you should not change the permission of those files. The directories inside the repository should be writable by the persons that have permission to modify the files in each directory. This normally means that you must create a UNIX group (see group(5)) consisting of the persons that are to edit the files in a project, and set up the repository so that it is that group that owns the directory.

This means that you can only control access to files on a per-directory basis.

Note that users must also have write access to check out files, because CVS needs to create lock files (see section Several developers simultaneously attempting to run CVS).

Also note that users must have write access to the `CVSROOT/val-tags' file. CVS uses it to keep track of what tags are valid tag names (it is sometimes updated when tags are used, as well as when they are created, though).

CVS tries to set up reasonable file permissions for new directories that are added inside the tree, but you must fix the permissions manually when a new directory should have different permissions than its parent directory. If you set the CVSUMASK environment variable that will control the file permissions which CVS uses in creating directories and/or files in the repository. CVSUMASK does not affect the file permissions in the working directory; such files have the permissions which are typical for newly created files, except that sometimes CVS creates them read-only (see the sections on watches, section Telling CVS to watch certain files; -r, section Global options; or CVSREAD, section All environment variables which affect CVS).

Since CVS was not written to be run setuid, it is unsafe to try to run it setuid. You cannot use the setuid features of RCS together with CVS.

The administrative files

The directory `$CVSROOT/CVSROOT' contains some administrative files. See section Reference manual for the Administrative files, for a complete description. You can use CVS without any of these files, but some commands work better when at least the `modules' file is properly set up.

The most important of these files is the `modules' file. It defines all modules in the repository. This is a sample `modules' file.

CVSROOT         CVSROOT
modules         CVSROOT modules
cvs             gnu/cvs
rcs             gnu/rcs
diff            gnu/diff
tc              yoyodyne/tc

The `modules' file is line oriented. In its simplest form each line contains the name of the module, whitespace, and the directory where the module resides. The directory is a path relative to $CVSROOT. The last four lines in the example above are examples of such lines.

The line that defines the module called `modules' uses features that are not explained here. See section The modules file, for a full explanation of all the available features.

Editing administrative files

You edit the administrative files in the same way that you would edit any other module. Use `cvs checkout CVSROOT' to get a working copy, edit it, and commit your changes in the normal way.

It is possible to commit an erroneous administrative file. You can often fix the error and check in a new revision, but sometimes a particularly bad error in the administrative file makes it impossible to commit new revisions.

Multiple repositories

In some situations it is a good idea to have more than one repository, for instance if you have two development groups that work on separate projects without sharing any code. All you have to do to have several repositories is to specify the appropriate repository, using the CVSROOT environment variable, the `-d' option to CVS, or (once you have checked out a working directory) by simply allowing CVS to use the repository that was used to check out the working directory (see section Telling CVS where your repository is).

The big advantage of having multiple repositories is that they can reside on different servers. The big disadvantage is that you cannot have a single CVS command recurse into directories which comes from different repositories. Generally speaking, if you are thinking of setting up several repositories on the same machine, you might want to consider using several directories within the same repository.

None of the examples in this manual show multiple repositories.

Creating a repository

To set up a CVS repository, choose a directory with ample disk space available for the revision history of the source files. It should be accessable (directly or via a networked file system) from all machines which want to use CVS in server or local mode; the client machines need not have any access to it other than via the CVS protocol. It is not possible to use CVS to read from a repository which one only has read access to; CVS needs to be able to create lock files (see section Several developers simultaneously attempting to run CVS).

To create a repository, run the cvs init command. It will set up an empty repository in the CVS root specified in the usual way (see section The Repository). For example,

cvs -d /usr/local/cvsroot init

cvs init is careful to never overwrite any existing files in the repository, so no harm is done if you run cvs init on an already set-up repository.

cvs init will enable history logging; if you don't want that, remove the history file after running cvs init. See section The history file.

Remote repositories

Your working copy of the sources can be on a different machine than the repository. Generally, using a remote repository is just like using a local one, except that the format of the repository name is:

:method:user@hostname:/path/to/repository

The details of exactly what needs to be set up depend on how you are connecting to the server.

If method is not specified, and the repository name contains `:', then the default is ext or server, depending on your platform; both are described in section Connecting with rsh.

Connecting with rsh

CVS uses the `rsh' protocol to perform these operations, so the remote user host needs to have a `.rhosts' file which grants access to the local user.

For example, suppose you are the user `mozart' on the local machine `anklet.grunge.com', and the server machine is `chainsaw.brickyard.com'. On chainsaw, put the following line into the file `.rhosts' in `bach''s home directory:

anklet.grunge.com  mozart

Then test that rsh is working with

rsh -l bach chainsaw.brickyard.com 'echo $PATH'

Next you have to make sure that rsh will be able to find the server. Make sure that the path which rsh printed in the above example includes the directory containing a program named cvs which is the server. You need to set the path in `.bashrc', `.cshrc', etc., not `.login' or `.profile'. Alternately, you can set the environment variable CVS_SERVER on the client machine to the filename of the server you want to use, for example `/usr/local/bin/cvs-1.6'.

There is no need to edit inetd.conf or start a CVS server daemon.

There are two access methods that you use in CVSROOT for rsh. :server: specifies an internal rsh client, which is supported only by some CVS ports. :ext: specifies an external rsh program. By default this is rsh but you may set the CVS_RSH environment variable to invoke another program which can access the remote server (for example, remsh on HP-UX 9 because rsh is something different). It must be a program which can transmit data to and from the server without modifying it; for example the Windows NT rsh is not suitable since it by default translates between CRLF and LF. The OS/2 CVS port has a hack to pass `-b' to rsh to get around this, but since this could potentially cause programs for programs other than the standard rsh, it may change in the future. If you set CVS_RSH to SSH or some other rsh replacement, the instructions in the rest of this section concerning `.rhosts' and so on are likely to be incorrect; consult the documentation for your rsh replacement.

Continuing our example, supposing you want to access the module `foo' in the repository `/usr/local/cvsroot/', on machine `chainsaw.brickyard.com', you are ready to go:

cvs -d :ext:bach@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo

(The `bach@' can be omitted if the username is the same on both the local and remote hosts.)

Direct connection with password authentication

The CVS client can also connect to the server using a password protocol. This is particularly useful if using rsh is not feasible (for example, the server is behind a firewall), and Kerberos also is not available.

To use this method, it is necessary to make some adjustments on both the server and client sides.

Setting up the server for password authentication

On the server side, the file `/etc/inetd.conf' needs to be edited so inetd knows to run the command cvs pserver when it receives a connection on the right port. By default, the port number is 2401; it would be different if your client were compiled with CVS_AUTH_PORT defined to something else, though.

If your inetd allows raw port numbers in `/etc/inetd.conf', then the following (all on a single line in `inetd.conf') should be sufficient:

2401  stream  tcp  nowait  root  /usr/local/bin/cvs
cvs -b /usr/local/bin pserver

The `-b' option specifies the directory which contains the RCS binaries on the server. You could also use the `-T' option to specify a temporary directory.

If your inetd wants a symbolic service name instead of a raw port number, then put this in `/etc/services':

cvspserver      2401/tcp

and put cvspserver instead of 2401 in `inetd.conf'.

Once the above is taken care of, restart your inetd, or do whatever is necessary to force it to reread its initialization files.

Because the client stores and transmits passwords in cleartext (almost--see section Security considerations with password authentication for details), a separate CVS password file may be used, so people don't compromise their regular passwords when they access the repository. This file is `$CVSROOT/CVSROOT/passwd' (see section The administrative files). Its format is similar to `/etc/passwd', except that it only has two fields, username and password. For example:

bach:ULtgRLXo7NRxs
cwang:1sOp854gDF3DY

The password is encrypted according to the standard Unix crypt() function, so it is possible to paste in passwords directly from regular Unix `passwd' files.

When authenticating a password, the server first checks for the user in the CVS `passwd' file. If it finds the user, it compares against that password. If it does not find the user, or if the CVS `passwd' file does not exist, then the server tries to match the password using the system's user-lookup routine. When using the CVS `passwd' file, the server runs under as the username specified in the the third argument in the entry, or as the first argument if there is no third argument (in this way CVS allows imaginary usernames provided the CVS `passwd' file indicates corresponding valid system usernames). In any case, CVS will have no privileges which the (valid) user would not have.

Right now, the only way to put a password in the CVS `passwd' file is to paste it there from somewhere else. Someday, there may be a cvs passwd command.

Using the client with password authentication

Before connecting to the server, the client must log in with the command cvs login. Logging in verifies a password with the server, and also records the password for later transactions with the server. The cvs login command needs to know the username, server hostname, and full repository path, and it gets this information from the repository argument or the CVSROOT environment variable.

cvs login is interactive -- it prompts for a password:

cvs -d :pserver:bach@chainsaw.brickyard.com:/usr/local/cvsroot login
CVS password:

The password is checked with the server; if it is correct, the login succeeds, else it fails, complaining that the password was incorrect.

Once you have logged in, you can force CVS to connect directly to the server and authenticate with the stored password:

cvs -d :pserver:bach@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo

The `:pserver:' is necessary because without it, CVS will assume it should use rsh to connect with the server (see section Connecting with rsh). (Once you have a working copy checked out and are running CVS commands from within it, there is no longer any need to specify the repository explicitly, because CVS records it in the working copy's `CVS' subdirectory.)

Passwords are stored by default in the file `$HOME/.cvspass'. Its format is human-readable, but don't edit it unless you know what you are doing. The passwords are not stored in cleartext, but are trivially encoded to protect them from "innocent" compromise (i.e., inadvertently being seen by a system administrator who happens to look at that file).

The CVS_PASSFILE environment variable overrides this default. If you use this variable, make sure you set it before cvs login is run. If you were to set it after running cvs login, then later CVS commands would be unable to look up the password for transmission to the server.

The CVS_PASSWORD environment variable overrides all stored passwords. If it is set, CVS will use it for all password-authenticated connections.

Security considerations with password authentication

The passwords are stored on the client side in a trivial encoding of the cleartext, and transmitted in the same encoding. The encoding is done only to prevent inadvertent password compromises (i.e., a system administrator accidentally looking at the file), and will not prevent even a naive attacker from gaining the password.

The separate CVS password file (see section Setting up the server for password authentication) allows people to use a different password for repository access than for login access. On the other hand, once a user has access to the repository, she can execute programs on the server system through a variety of means. Thus, repository access implies fairly broad system access as well. It might be possible to modify CVS to prevent that, but no one has done so as of this writing. Furthermore, there may be other ways in which having access to CVS allows people to gain more general access to the system; noone has done a careful audit.

In summary, anyone who gets the password gets repository access, and some measure of general system access as well. The password is available to anyone who can sniff network packets or read a protected (i.e., user read-only) file. If you want real security, get Kerberos.

Direct connection with kerberos

The main disadvantage of using rsh is that all the data needs to pass through additional programs, so it may be slower. So if you have kerberos installed you can connect via a direct TCP connection, authenticating with kerberos.

To do this, CVS needs to be compiled with kerberos support; when configuring CVS it tries to detect whether kerberos is present or you can use the `--with-krb4' flag to configure.

The data transmitted is not encrypted by default. Encryption support must be compiled into both the client and server; use the `--enable-encryption' configure option to turn it on. You must then use the -x global option to request encryption.

You need to edit inetd.conf on the server machine to run cvs kserver. The client uses port 1999 by default; if you want to use another port specify it in the CVS_CLIENT_PORT environment variable on the client.

When you want to use CVS, get a ticket in the usual way (generally kinit); it must be a ticket which allows you to log into the server machine. Then you are ready to go:

cvs -d :kserver:chainsaw.brickyard.com:/user/local/cvsroot checkout foo

Previous versions of CVS would fall back to a connection via rsh; this version will not do so.

Starting a project with CVS

Because renaming files and moving them between directories is somewhat inconvenient, the first thing you do when you start a new project should be to think through your file organization. It is not impossible to rename or move files, but it does increase the potential for confusion and CVS does have some quirks particularly in the area of renaming directories. See section Moving and renaming files.

What to do next depends on the situation at hand.

Setting up the files

The first step is to create the files inside the repository. This can be done in a couple of different ways.

Creating a directory tree from a number of files

When you begin using CVS, you will probably already have several projects that can be put under CVS control. In these cases the easiest way is to use the import command. An example is probably the easiest way to explain how to use it. If the files you want to install in CVS reside in `wdir', and you want them to appear in the repository as `$CVSROOT/yoyodyne/rdir', you can do this:

$ cd wdir
$ cvs import -m "Imported sources" yoyodyne/rdir yoyo start

Unless you supply a log message with the `-m' flag, CVS starts an editor and prompts for a message. The string `yoyo' is a vendor tag, and `start' is a release tag. They may fill no purpose in this context, but since CVS requires them they must be present. See section Tracking third-party sources, for more information about them.

You can now verify that it worked, and remove your original source directory.

$ cd ..
$ mv dir dir.orig
$ cvs checkout yoyodyne/dir       # Explanation below
$ ls -R yoyodyne
$ rm -r dir.orig

Erasing the original sources is a good idea, to make sure that you do not accidentally edit them in dir, bypassing CVS. Of course, it would be wise to make sure that you have a backup of the sources before you remove them.

The checkout command can either take a module name as argument (as it has done in all previous examples) or a path name relative to $CVSROOT, as it did in the example above.

It is a good idea to check that the permissions CVS sets on the directories inside `$CVSROOT' are reasonable, and that they belong to the proper groups. See section File permissions.

If some of the files you want to import are binary, you may want to use the wrappers features to specify which files are binary and which are not. See section The cvswrappers file.

Creating Files From Other Version Control Systems

If you have a project which you are maintaining with another version control system, such as RCS, you may wish to put the files from that project into CVS, and preserve the revision history of the files.

From RCS
If you have been using RCS, find the RCS files--usually a file named `foo.c' will have its RCS file in `RCS/foo.c,v' (but it could be other places; consult the RCS documentation for details). Then create the appropriate directories in CVS if they do not already exist. Then copy the files into the appropriate directories in the CVS repository (the name in the repository must be the name of the source file with `,v' added; the files go directly in the appopriate directory of the repository, not in an `RCS' subdirectory). This is one of the few times when it is a good idea to access the CVS repository directly, rather than using CVS commands. Then you are ready to check out a new working directory. The RCS file should not be locked when you move it into CVS; if it is, CVS will have trouble letting you operate on it.
From another version control system
Many version control systems have the ability to export RCS files in the standard format. If yours does, export the RCS files and then follow the above instructions.
From SCCS
There is a script in the `contrib' directory of the CVS source distribution called `sccs2rcs' which converts SCCS files to RCS files. Note: you must run it on a machine which has both SCCS and RCS installed, and like everything else in contrib it is unsupported (your mileage may vary).

Creating a directory tree from scratch

For a new project, the easiest thing to do is probably to create an empty directory structure, like this:

$ mkdir tc
$ mkdir tc/man
$ mkdir tc/testing

After that, you use the import command to create the corresponding (empty) directory structure inside the repository:

$ cd tc
$ cvs import -m "Created directory structure" yoyodyne/dir yoyo start

Then, use add to add files (and new directories) as they appear.

Check that the permissions CVS sets on the directories inside `$CVSROOT' are reasonable.

Defining the module

The next step is to define the module in the `modules' file. This is not strictly necessary, but modules can be convenient in grouping together related files and directories.

In simple cases these steps are sufficient to define a module.

  1. Get a working copy of the modules file.
    $ cvs checkout CVSROOT/modules
$ cd CVSROOT
  2. Edit the file and insert a line that defines the module. See section The administrative files, for an introduction. See section The modules file, for a full description of the modules file. You can use the following line to define the module `tc':
    tc   yoyodyne/tc
  3. Commit your changes to the modules file.
    $ cvs commit -m "Added the tc module." modules
  4. Release the modules module.
    $ cd ..
$ cvs release -d CVSROOT

Multiple developers

When more than one person works on a software project things often get complicated. Often, two people try to edit the same file simultaneously. One solution, known as file locking or reserved checkouts, is to allow only one person to edit each file at a time. This is the only solution with some version control systems, including RCS and SCCS. CVS doesn't have a very nice implementation of reserved checkouts (yet) but there are ways to get it working (for example, see the cvs admin -l command in section admin options). It also may be possible to use the watches features described below, together with suitable procedures (not enforced by software), to avoid having two people edit at the same time.

The default model with CVS is known as unreserved checkouts. In this model, developers can edit their own working copy of a file simultaneously. The first person that commits his changes has no automatic way of knowing that another has started to edit it. Others will get an error message when they try to commit the file. They must then use CVS commands to bring their working copy up to date with the repository revision. This process is almost automatic.

CVS also supports mechanisms which facilitate various kinds of communcation, without actually enforcing rules like reserved checkouts do.

The rest of this chapter describes how these various models work, and some of the issues involved in choosing between them.

File status

Based on what operations you have performed on a checked out file, and what operations others have performed to that file in the repository, one can classify a file in a number of states. The states, as reported by the status command, are:

Up-to-date
The file is identical with the latest revision in the repository for the branch in use.
Locally Modified
You have edited the file, and not yet committed your changes.
Locally Added
You have added the file with add, and not yet committed your changes.
Locally Removed
You have removed the file with remove, and not yet committed your changes.
Needs Checkout
Someone else has committed a newer revision to the repository. The name is slightly misleading; you will ordinarily use update rather than checkout to get that newer revision.
Needs Patch
Like Needs Checkout, but the CVS server will send a patch rather than the entire file. Sending a patch or sending an entire file accomplishes the same thing.
Needs Merge
Someone else has committed a newer revision to the repository, and you have also made modifications to the file.
Unresolved Conflict
This is like Locally Modified, except that a previous update command gave a conflict. You need to resolve the conflict as described in section Conflicts example.
Unknown
CVS doesn't know anything about this file. For example, you have created a new file and have not run add.

To help clarify the file status, status also reports the Working revision which is the revision that the file in the working directory derives from, and the Repository revision which is the latest revision in the repository for the branch in use.

For information on the options to status, see section status--Display status information on checked out files. For information on its Sticky tag and Sticky date output, see section Sticky tags. For information on its Sticky options output, see the `-k' option in section update options.

Bringing a file up to date

When you want to update or merge a file, use the update command. For files that are not up to date this is roughly equivalent to a checkout command: the newest revision of the file is extracted from the repository and put in your working copy of the module.

Your modifications to a file are never lost when you use update. If no newer revision exists, running update has no effect. If you have edited the file, and a newer revision is available, CVS will merge all changes into your working copy.

For instance, imagine that you checked out revision 1.4 and started editing it. In the meantime someone else committed revision 1.5, and shortly after that revision 1.6. If you run update on the file now, CVS will incorporate all changes between revision 1.4 and 1.6 into your file.

If any of the changes between 1.4 and 1.6 were made too close to any of the changes you have made, an overlap occurs. In such cases a warning is printed, and the resulting file includes both versions of the lines that overlap, delimited by special markers. See section update--Bring work tree in sync with repository, for a complete description of the update command.

Conflicts example

Suppose revision 1.4 of `driver.c' contains this:

#include <stdio.h>

void main()
{
    parse();
    if (nerr == 0)
        gencode();
    else
        fprintf(stderr, "No code generated.\n");
    exit(nerr == 0 ? 0 : 1);
}

Revision 1.6 of `driver.c' contains this:

#include <stdio.h>

int main(int argc,
         char **argv)
{
    parse();
    if (argc != 1)
    {
        fprintf(stderr, "tc: No args expected.\n");
        exit(1);
    }
    if (nerr == 0)
        gencode();
    else
        fprintf(stderr, "No code generated.\n");
    exit(!!nerr);
}

Your working copy of `driver.c', based on revision 1.4, contains this before you run `cvs update':

#include <stdlib.h>
#include <stdio.h>

void main()
{
    init_scanner();
    parse();
    if (nerr == 0)
        gencode();
    else
        fprintf(stderr, "No code generated.\n");
    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
}

You run `cvs update':

$ cvs update driver.c
RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
retrieving revision 1.4
retrieving revision 1.6
Merging differences between 1.4 and 1.6 into driver.c
rcsmerge warning: overlaps during merge
cvs update: conflicts found in driver.c
C driver.c

CVS tells you that there were some conflicts. Your original working file is saved unmodified in `.#driver.c.1.4'. The new version of `driver.c' contains this:

#include <stdlib.h>
#include <stdio.h>

int main(int argc,
         char **argv)
{
    init_scanner();
    parse();
    if (argc != 1)
    {
        fprintf(stderr, "tc: No args expected.\n");
        exit(1);
    }
    if (nerr == 0)
        gencode();
    else
        fprintf(stderr, "No code generated.\n");
<<<<<<< driver.c
    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
=======
    exit(!!nerr);
>>>>>>> 1.6
}

Note how all non-overlapping modifications are incorporated in your working copy, and that the overlapping section is clearly marked with `<<<<<<<', `=======' and `>>>>>>>'.

You resolve the conflict by editing the file, removing the markers and the erroneous line. Suppose you end up with this file:

#include <stdlib.h>
#include <stdio.h>

int main(int argc,
         char **argv)
{
    init_scanner();
    parse();
    if (argc != 1)
    {
        fprintf(stderr, "tc: No args expected.\n");
        exit(1);
    }
    if (nerr == 0)
        gencode();
    else
        fprintf(stderr, "No code generated.\n");
    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
}

You can now go ahead and commit this as revision 1.7.

$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
Checking in driver.c;
/usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
new revision: 1.7; previous revision: 1.6
done

For your protection, CVS will refuse to check in a file if a conflict occurred and you have not resolved the conflict. Currently to resolve a conflict, you must change the timestamp on the file, and must also insure that the file contains no conflict markers. If your file legitimately contains conflict markers (that is, occurrences of `>>>>>>> ' at the start of a line that don't mark a conflict), then CVS has trouble handling this and you need to start hacking on the CVS/Entries file or other such workarounds.

If you use release 1.04 or later of pcl-cvs (a GNU Emacs front-end for CVS) you can use an Emacs package called emerge to help you resolve conflicts. See the documentation for pcl-cvs.

Informing others about commits

It is often useful to inform others when you commit a new revision of a file. The `-i' option of the `modules' file, or the `loginfo' file, can be used to automate this process. See section The modules file. See section Loginfo. You can use these features of CVS to, for instance, instruct CVS to mail a message to all developers, or post a message to a local newsgroup.

Several developers simultaneously attempting to run CVS

If several developers try to run CVS at the same time, one may get the following message:

[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo

CVS will try again every 30 seconds, and either continue with the operation or print the message again, if it still needs to wait. If a lock seems to stick around for an undue amount of time, find the person holding the lock and ask them about the cvs command they are running. If they aren't running a cvs command, look for and remove files starting with `#cvs.tfl', `#cvs.rfl', or `#cvs.wfl' from the repository.

Note that these locks are to protect CVS's internal data structures and have no relationship to the word lock in the sense used by RCS---which refers to reserved checkouts (see section Multiple developers).

Any number of people can be reading from a given repository at a time; only when someone is writing do the locks prevent other people from reading or writing.

One might hope for the following property

If someone commits some changes in one cvs command,
then an update by someone else will either get all the
changes, or none of them.

but CVS does not have this property. For example, given the files

a/one.c
a/two.c
b/three.c
b/four.c

if someone runs

cvs ci a/two.c b/three.c

and someone else runs cvs update at the same time, the person running update might get only the change to `b/three.c' and not the change to `a/two.c'.

Mechanisms to track who is editing files

For many groups, use of CVS in its default mode is perfectly satisfactory. Users may sometimes go to check in a modification only to find that another modification has intervened, but they deal with it and proceed with their check in. Other groups prefer to be able to know who is editing what files, so that if two people try to edit the same file they can choose to talk about who is doing what when rather than be surprised at check in time. The features in this section allow such coordination, while retaining the ability of two developers to edit the same file at the same time.

For maximum benefit developers should use cvs edit (not chmod) to make files read-write to edit them, and cvs release (not rm) to discard a working directory which is no longer in use, but CVS is not able to enforce this behavior.

Telling CVS to watch certain files

To enable the watch features, you first specify that certain files are to be watched.

Command: cvs watch on [-l] files ...

Specify that developers should run cvs edit before editing files. CVS will create working copies of files read-only, to remind developers to run the cvs edit command before working on them.

If files includes the name of a directory, CVS arranges to watch all files added to the corresponding repository directory, and sets a default for files added in the future; this allows the user to set notification policies on a per-directory basis. The contents of the directory are processed recursively, unless the -l option is given.

If files is omitted, it defaults to the current directory.

Command: cvs watch off [-l] files ...

Do not provide notification about work on files. CVS will create working copies of files read-write.

The files and -l arguments are processed as for cvs watch on.

Telling CVS to notify you

You can tell CVS that you want to receive notifications about various actions taken on a file. You can do this without using cvs watch on for the file, but generally you will want to use cvs watch on, so that developers use the cvs edit command.

Command: cvs watch add [-a action] [-l] files ...

Add the current user to the list of people to receive notification of work done on files.

The -a option specifies what kinds of events CVS should notify the user about. action is one of the following:

edit
Another user has applied the cvs edit command (described below) to a file.
unedit
Another user has applied the cvs unedit command (described below) or the cvs release command to a file, or has deleted the file and allowed cvs update to recreate it.
commit
Another user has committed changes to a file.
all
All of the above.
none
None of the above. (This is useful with cvs edit, described below.)

The -a option may appear more than once, or not at all. If omitted, the action defaults to all.

The files and -l option are processed as for the cvs watch commands.

Command: cvs watch remove [-a action] [-l] files ...

Remove a notification request established using cvs watch add; the arguments are the same. If the -a option is present, only watches for the specified actions are removed.

When the conditions exist for notification, CVS calls the `notify' administrative file. Edit `notify' as one edits the other administrative files (see section The administrative files). This file follows the usual conventions for administrative files (see section The common syntax), where each line is a regular expression followed by a command to execute. The command should contain a single ocurrence of `%s' which will be replaced by the user to notify; the rest of the information regarding the notification will be supplied to the command on standard input. The standard thing to put in the notify file is the single line:

ALL mail %s -s \"CVS notification\"

This causes users to be notified by electronic mail.

Note that if you set this up in the straightforward way, users receive notifications on the server machine. One could of course write a `notify' script which directed notifications elsewhere, but to make this easy, CVS allows you to associate a notification address for each user. To do so create a file `users' in `CVSROOT' with a line for each user in the format user:value. Then instead of passing the name of the user to be notified to `notify', CVS will pass the value (normally an email address on some other machine).

How to edit a file which is being watched

Since a file which is being watched is checked out read-only, you cannot simply edit it. To make it read-write, and inform others that you are planning to edit it, use the cvs edit command. Some systems call this a checkout, but CVS uses that term for obtaining a copy of the sources (see section Getting the source), an operation which those systems call a get or a fetch.

Command: cvs edit [options] files ...

Prepare to edit the working files files. CVS makes the files read-write, and notifies users who have requested edit notification for any of files.

The cvs edit command accepts the same options as the cvs watch add command, and establishes a temporary watch for the user on files; CVS will remove the watch when files are unedited or committed. If the user does not wish to receive notifications, she should specify -a none.

The files and -l option are processed as for the cvs watch commands.

Normally when you are done with a set of changes, you use the cvs commit command, which checks in your changes and returns the watched files to their usual read-only state. But if you instead decide to abandon your changes, or not to make any changes, you can use the cvs unedit command.

Command: cvs unedit [-l] files ...

Abandon work on the working files files, and revert them to the repository versions on which they are based. CVS makes those files read-only for which users have requested notification using cvs watch on. CVS notifies users who have requested unedit notification for any of files.

The files and -l option are processed as for the cvs watch commands.

If watches are not in use, the unedit command probably does not work, and the way to revert to the repository version is to remove the file and then use cvs update to get a new copy. The meaning is not precisely the same; removing and updating may also bring in some changes which have been made in the repository since the last time you updated.

When using client/server CVS, you can use the cvs edit and cvs unedit commands even if CVS is unable to succesfully communicate with the server; the notifications will be sent upon the next successful CVS command.

Information about who is watching and editing

Command: cvs watchers [-l] files ...

List the users currently watching changes to files. The report includes the files being watched, and the mail address of each watcher.

The files and -l arguments are processed as for the cvs watch commands.

Command: cvs editors [-l] files ...

List the users currently working on files. The report includes the mail address of each user, the time when the user began working with the file, and the host and path of the working directory containing the file.

The files and -l arguments are processed as for the cvs watch commands.

Using watches with old versions of CVS

If you use the watch features on a repository, it creates `CVS' directories in the repository and stores the information about watches in that directory. If you attempt to use CVS 1.6 or earlier with the repository, you get an error message such as

cvs update: cannot open CVS/Entries for reading: No such file or directory

and your operation will likely be aborted. To use the watch features, you must upgrade all copies of CVS which use that repository in local or server mode. If you cannot upgrade, use the watch off and watch remove commands to remove all watches, and that will restore the repository to a state which CVS 1.6 can cope with.

Choosing between reserved or unreserved checkouts

Reserved and unreserved checkouts each have pros and cons. Let it be said that a lot of this is a matter of opinion or what works given different groups' working styles, but here is an attempt to briefly describe the issues. There are many ways to organize a team of developers. CVS does not try to enforce a certain organization. It is a tool that can be used in several ways.

Reserved checkouts can be very counter-productive. If two persons want to edit different parts of a file, there may be no reason to prevent either of them from doing so. Also, it is common for someone to take out a lock on a file, because they are planning to edit it, but then forget to release the lock.

People, especially people who are familiar with reserved checkouts, often wonder how often conflicts occur if unreserved checkouts are used, and how difficult they are to resolve. The experience with many groups is that they occur rarely and usually are relatively straightforward to resolve.

The rarity of serious conflicts may be surprising, until one realizes that they occur only when two developers disagree on the proper design for a given section of code; such a disagreement suggests that the team has not been communicating properly in the first place. In order to collaborate under any source management regimen, developers must agree on the general design of the system; given this agreement, overlapping changes are usually straightforward to merge.

In some cases unreserved checkouts are clearly inappropriate. If no merge tool exists for the kind of file you are managing (for example word processor files or files edited by Computer Aided Design programs), and it is not desirable to change to a program which uses a mergeable data format, then resolving conflicts is going to be unpleasant enough that you generally will be better off to simply avoid the conflicts instead, by using reserved checkouts.

The watches features described above in section Mechanisms to track who is editing files can be considered to be an intermediate model between reserved checkouts and unreserved checkouts. When you go to edit a file, it is possible to find out who else is editing it. And rather than having the system simply forbid both people editing the file, it can tell you what the situation is and let you figure out whether it is a problem in that particular case or not. Therefore, for some groups it can be considered the best of both the reserved checkout and unreserved checkout worlds.

Branches

So far, all revisions shown in this manual have been on the main trunk of the revision tree, i.e., all revision numbers have been of the form x.y. One useful feature, especially when maintaining several releases of a software product at once, is the ability to make branches on the revision tree. Tags, symbolic names for revisions, will also be introduced in this chapter.

Tags--Symbolic revisions

The revision numbers live a life of their own. They need not have anything at all to do with the release numbers of your software product. Depending on how you use CVS the revision numbers might change several times between two releases. As an example, some of the source files that make up RCS 5.6 have the following revision numbers:

ci.c            5.21
co.c            5.9
ident.c         5.3
rcs.c           5.12
rcsbase.h       5.11
rcsdiff.c       5.10
rcsedit.c       5.11
rcsfcmp.c       5.9
rcsgen.c        5.10
rcslex.c        5.11
rcsmap.c        5.2
rcsutil.c       5.10

You can use the tag command to give a symbolic name to a certain revision of a file. You can use the `-v' flag to the status command to see all tags that a file has, and which revision numbers they represent. Tag names can contain uppercase and lowercase letters, digits, `-', and `_'. The two tag names BASE and HEAD are reserved for use by CVS. It is expected that future names which are special to CVS will contain characters such as `%' or `=', rather than being named analogously to BASE and HEAD, to avoid conflicts with actual tag names.

The following example shows how you can add a tag to a file. The commands must be issued inside your working copy of the module. That is, you should issue the command in the directory where `backend.c' resides.

$ cvs tag release-0-4 backend.c
T backend.c
$ cvs status -v backend.c
===================================================================
File: backend.c         Status: Up-to-date

    Version:            1.4     Tue Dec  1 14:39:01 1992
    RCS Version:        1.4     /usr/local/cvsroot/yoyodyne/tc/backend.c,v
    Sticky Tag:         (none)
    Sticky Date:        (none)
    Sticky Options:     (none)

    Existing Tags:
        release-0-4                     (revision: 1.4)

There is seldom reason to tag a file in isolation. A more common use is to tag all the files that constitute a module with the same tag at strategic points in the development life-cycle, such as when a release is made.

$ cvs tag release-1-0 .
cvs tag: Tagging .
T Makefile
T backend.c
T driver.c
T frontend.c
T parser.c

(When you give CVS a directory as argument, it generally applies the operation to all the files in that directory, and (recursively), to any subdirectories that it may contain. See section Recursive behavior.)

The checkout command has a flag, `-r', that lets you check out a certain revision of a module. This flag makes it easy to retrieve the sources that make up release 1.0 of the module `tc' at any time in the future:

$ cvs checkout -r release-1-0 tc

This is useful, for instance, if someone claims that there is a bug in that release, but you cannot find the bug in the current working copy.

You can also check out a module as it was at any given date. See section checkout options.

When you tag more than one file with the same tag you can think about the tag as "a curve drawn through a matrix of filename vs. revision number." Say we have 5 files with the following revisions:

        file1   file2   file3   file4   file5

        1.1     1.1     1.1     1.1  /--1.1*      <-*-  TAG
        1.2*-   1.2     1.2    -1.2*-
        1.3  \- 1.3*-   1.3   / 1.3
        1.4          \  1.4  /  1.4
                      \-1.5*-   1.5
                        1.6

At some time in the past, the * versions were tagged. You can think of the tag as a handle attached to the curve drawn through the tagged revisions. When you pull on the handle, you get all the tagged revisions. Another way to look at it is that you "sight" through a set of revisions that is "flat" along the tagged revisions, like this:

        file1   file2   file3   file4   file5

                        1.1
                        1.2
                1.1     1.3                       _
        1.1     1.2     1.4     1.1              /
        1.2*----1.3*----1.5*----1.2*----1.1     (--- <--- Look here
        1.3             1.6     1.3              \_
        1.4                     1.4
                                1.5

What branches are good for

Suppose that release 1.0 of tc has been made. You are continuing to develop tc, planning to create release 1.1 in a couple of months. After a while your customers start to complain about a fatal bug. You check out release 1.0 (see section Tags--Symbolic revisions) and find the bug (which turns out to have a trivial fix). However, the current revision of the sources are in a state of flux and are not expected to be stable for at least another month. There is no way to make a bugfix release based on the newest sources.

The thing to do in a situation like this is to create a branch on the revision trees for all the files that make up release 1.0 of tc. You can then make modifications to the branch without disturbing the main trunk. When the modifications are finished you can select to either incorporate them on the main trunk, or leave them on the branch.

Creating a branch

The rtag command can be used to create a branch. The rtag command is much like tag, but it does not require that you have a working copy of the module. See section rtag--Add a symbolic tag to a module. (You can also use the tag command; see section tag--Add a symbolic tag to checked out versions of files).

$ cvs rtag -b -r release-1-0 release-1-0-patches tc

The `-b' flag makes rtag create a branch (rather than just a symbolic revision name). `-r release-1-0' says that this branch should be rooted at the node (in the revision tree) that corresponds to the tag `release-1-0'. Note that the numeric revision number that matches `release-1-0' will probably be different from file to file. The name of the new branch is `release-1-0-patches', and the module affected is `tc'.

To fix the problem in release 1.0, you need a working copy of the branch you just created.

$ cvs checkout -r release-1-0-patches tc
$ cvs status -v driver.c backend.c
===================================================================
File: driver.c          Status: Up-to-date

    Version:            1.7     Sat Dec  5 18:25:54 1992
    RCS Version:        1.7     /usr/local/cvsroot/yoyodyne/tc/driver.c,v
    Sticky Tag:         release-1-0-patches (branch: 1.7.2)
    Sticky Date:        (none)
    Sticky Options:     (none)

    Existing Tags:
        release-1-0-patches             (branch: 1.7.2)
        release-1-0                     (revision: 1.7)

===================================================================
File: backend.c         Status: Up-to-date

    Version:            1.4     Tue Dec  1 14:39:01 1992
    RCS Version:        1.4     /usr/local/cvsroot/yoyodyne/tc/backend.c,v
    Sticky Tag:         release-1-0-patches (branch: 1.4.2)
    Sticky Date:        (none)
    Sticky Options:     (none)

    Existing Tags:
        release-1-0-patches             (branch: 1.4.2)
        release-1-0                     (revision: 1.4)
        release-0-4                     (revision: 1.4)

As the output from the status command shows the branch number is created by adding a digit at the tail of the revision number it is based on. (If `release-1-0' corresponds to revision 1.4, the branch's revision number will be 1.4.2. For obscure reasons CVS always gives branches even numbers, starting at 2. See section Revision numbers).

Sticky tags

The `-r release-1-0-patches' flag that was given to checkout in the previous example is sticky, that is, it will apply to subsequent commands in this directory. If you commit any modifications, they are committed on the branch. You can later merge the modifications into the main trunk. See section Merging.

You can use the status command to see what sticky tags or dates are set:

$ vi driver.c   # Fix the bugs
$ cvs commit -m "Fixed initialization bug" driver.c
Checking in driver.c;
/usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
new revision: 1.7.2.1; previous revision: 1.7
done
$ cvs status -v driver.c
===================================================================
File: driver.c          Status: Up-to-date

    Version:            1.7.2.1 Sat Dec  5 19:35:03 1992
    RCS Version:        1.7.2.1 /usr/local/cvsroot/yoyodyne/tc/driver.c,v
    Sticky Tag:         release-1-0-patches (branch: 1.7.2)
    Sticky Date:        (none)
    Sticky Options:     (none)

    Existing Tags:
        release-1-0-patches             (branch: 1.7.2)
        release-1-0                     (revision: 1.7)

The sticky tags will remain on your working files until you delete them with `cvs update -A'. The `-A' option retrieves the version of the file from the head of the trunk, and forgets any sticky tags, dates, or options.

Sticky tags are not just for branches. For example, suppose that you want to avoid updating your working directory, to isolate yourself from possibly destabilizing changes other people are making. You can, of course, just refrain from running cvs update. But if you want to avoid updating only a portion of a larger tree, then sticky tags can help. If you check out a certain revision (such as 1.4) it will become sticky. Subsequent cvs update will not retrieve the latest revision until you reset the tag with cvs update -A. Likewise, use of the `-D' option to update or checkout sets a sticky date, which, similarly, causes that date to be used for future retrievals.

Many times you will want to retrieve an old version of a file without setting a sticky tag. The way to do that is with the `-p' option to checkout or update, which sends the contents of the file to standard output. For example, suppose you have a file named `file1' which existed as revision 1.1, and you then removed it (thus adding a dead revision 1.2). Now suppose you want to add it again, with the same contents it had previously. Here is how to do it:

$ cvs update -p -r 1.1 file1 >file1
===================================================================
Checking out file1
RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
VERS: 1.1
***************
$ cvs add file1
cvs add: re-adding file file1 (in place of dead revision 1.2)
cvs add: use 'cvs commit' to add this file permanently
$ cvs commit -m test
Checking in file1;
/tmp/cvs-sanity/cvsroot/first-dir/file1,v  <--  file1
new revision: 1.3; previous revision: 1.2
done
$

Merging

You can include the changes made between any two revisions into your working copy, by merging. You can then commit that revision, and thus effectively copy the changes onto another branch.

Merging an entire branch

You can merge changes made on a branch into your working copy by giving the `-j branch' flag to the update command. With one `-j branch' option it merges the changes made between the point where the branch forked and newest revision on that branch (into your working copy).

The `-j' stands for "join".

Consider this revision tree:

+-----+    +-----+    +-----+    +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      <- The main trunk
+-----+    +-----+    +-----+    +-----+
                !
                !
                !   +---------+    +---------+
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
                    +---------+    +---------+

The branch 1.2.2 has been given the tag (symbolic name) `R1fix'. The following example assumes that the module `mod' contains only one file, `m.c'.

$ cvs checkout mod               # Retrieve the latest revision, 1.4

$ cvs update -j R1fix m.c        # Merge all changes made on the branch,
                                 # i.e. the changes between revision 1.2
                                 # and 1.2.2.2, into your working copy
                                 # of the file.

$ cvs commit -m "Included R1fix" # Create revision 1.5.

A conflict can result from a merge operation. If that happens, you should resolve it before committing the new revision. See section Conflicts example.

The checkout command also supports the `-j branch' flag. The same effect as above could be achieved with this:

$ cvs checkout -j R1fix mod
$ cvs commit -m "Included R1fix"

Merging from a branch several times

Continuing our example, the revision tree now looks like this:

+-----+    +-----+    +-----+    +-----+    +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
+-----+    +-----+    +-----+    +-----+    +-----+
                !                           *
                !                          *
                !   +---------+    +---------+
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
                    +---------+    +---------+

where the starred line represents the merge from the `R1fix' branch to the main trunk, as just discussed.

Now suppose that development continues on the `R1fix' branch:

+-----+    +-----+    +-----+    +-----+    +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
+-----+    +-----+    +-----+    +-----+    +-----+
                !                           *
                !                          *
                !   +---------+    +---------+    +---------+
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
                    +---------+    +---------+    +---------+

and then you want to merge those new changes onto the main trunk. If you just use the cvs update -j R1fix m.c command again, CVS will attempt to merge again the changes which you have already merged, which can have undesirable side effects.

So instead you need to specify that you only want to merge the changes on the branch which have not yet been merged into the trunk. To do that you specify two `-j' options, and CVS merges the changes from the first revision to the second revision. For example, in this case the simplest way would be

cvs update -j 1.2.2.2 -j R1fix m.c    # Merge changes from 1.2.2.2 to the
                                      # head of the R1fix branch

The problem with this is that you need to specify the 1.2.2.2 revision manually. A slightly better approach might be to use the date the last merge was done:

cvs update -j R1fix:yesterday -j R1fix m.c

Better yet, tag the R1fix branch after every merge into the trunk, and then use that tag for subsequent merges:

cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c

Merging differences between any two revisions

With two `-j revision' flags, the update (and checkout) command can merge the differences between any two revisions into your working file.

$ cvs update -j 1.5 -j 1.3 backend.c

will remove all changes made between revision 1.3 and 1.5. Note the order of the revisions!

If you try to use this option when operating on multiple files, remember that the numeric revisions will probably be very different between the various files that make up a module. You almost always use symbolic tags rather than revision numbers when operating on multiple files.

Merging can add or remove files

If the changes which you are merging involve removing or adding some files, update -j will reflect such additions or removals.

For example:

cvs update -A
touch a b c
cvs add a b c ; cvs ci -m "added" a b c
cvs tag -b branchtag
cvs update -r branchtag
touch d ; cvs add d
rm a ; cvs rm a
cvs ci -m "added d, removed a"
cvs update -A
cvs update -jbranchtag

Recursive behavior

Almost all of the subcommands of CVS work recursively when you specify a directory as an argument. For instance, consider this directory structure:

      $HOME
        |
        +--tc
        |   |
            +--CVS
            |      (internal CVS files)
            +--Makefile
            +--backend.c
            +--driver.c
            +--frontend.c
            +--parser.c
            +--man
            |    |
            |    +--CVS
            |    |  (internal CVS files)
            |    +--tc.1
            |
            +--testing
                 |
                 +--CVS
                 |  (internal CVS files)
                 +--testpgm.t
                 +--test2.t

If `tc' is the current working directory, the following is true:

  • `cvs update testing' is equivalent to `cvs update testing/testpgm.t testing/test2.t'
  • `cvs update testing man' updates all files in the subdirectories
  • `cvs update .' or just `cvs update' updates all files in the tc module

If no arguments are given to update it will update all files in the current working directory and all its subdirectories. In other words, `.' is a default argument to update. This is also true for most of the CVS subcommands, not only the update command.

The recursive behavior of the CVS subcommands can be turned off with the `-l' option.

$ cvs update -l         # Don't update files in subdirectories

Adding files to a directory

To add a new file to a directory, follow these steps.

  • You must have a working copy of the directory. See section Getting the source.
  • Create the new file inside your working copy of the directory.
  • Use `cvs add filename' to tell CVS that you want to version control the file. If the file contains binary data, specify `-kb' (see section Handling binary files).
  • Use `cvs commit filename' to actually check in the file into the repository. Other developers cannot see the file until you perform this step.

You can also use the add command to add a new directory.

Unlike most other commands, the add command is not recursive. You cannot even type `cvs add foo/bar'! Instead, you have to

$ cd foo
$ cvs add bar

Command: cvs add [-k kflag] [-m message] files ...

Schedule files to be added to the repository. The files or directories specified with add must already exist in the current directory. To add a whole new directory hierarchy to the source repository (for example, files received from a third-party vendor), use the import command instead. See section import--Import sources into CVS, using vendor branches.

The added files are not placed in the source repository until you use commit to make the change permanent. Doing an add on a file that was removed with the remove command will undo the effect of the remove, unless a commit command intervened. See section Removing files from a module, for an example.

The `-k' option specifies the default way that this file will be checked out; for more information see section Substitution modes.

The `-m' option specifies a description for the file. This description appears in the history log (if it is enabled, see section The history file). It will also be saved in the version history inside the repository when the file is committed. The log command displays this description. The description can be changed using `admin -t'. See section admin--Administration front end for rcs. If you omit the `-m description' flag, an empty string will be used. You will not be prompted for a description.

For example, the following commands add the file `backend.c' to the repository:

$ cvs add backend.c
$ cvs commit -m "Early version. Not yet compilable." backend.c

When you add a file it is added only on the branch which you are working on (see section Branches). You can later merge the additions to another branch if you want (see section Merging can add or remove files).

Removing files from a module

Modules change. New files are added, and old files disappear. Still, you want to be able to retrieve an exact copy of old releases of the module.

Here is what you can do to remove a file from a module, but remain able to retrieve old revisions:

  • Make sure that you have not made any uncommitted modifications to the file. See section Viewing differences, for one way to do that. You can also use the status or update command. If you remove the file without committing your changes, you will of course not be able to retrieve the file as it was immediately before you deleted it.
  • Remove the file from your working copy of the module. You can for instance use rm.
  • Use `cvs remove filename' to tell CVS that you really want to delete the file.
  • Use `cvs commit filename' to actually perform the removal of the file from the repository.

When you commit the removal of the file, CVS records the fact that the file no longer exists. It is possible for a file to exist on only some branches and not on others, or to re-add another file with the same name later. CVS will correctly create or not create the file, based on the `-r' and `-D' options specified to checkout or update.

Command: cvs remove [-lR] files ...

Schedule file(s) to be removed from the repository (files which have not already been removed from the working directory are not processed). This command does not actually remove the file from the repository until you commit the removal. The `-R' option (the default) specifies that it will recurse into subdirectories; `-l' specifies that it will not.

Here is an example of removing several files:

$ cd test
$ rm ?.c
$ cvs remove
cvs remove: Removing .
cvs remove: scheduling a.c for removal
cvs remove: scheduling b.c for removal
cvs remove: use 'cvs commit' to remove these files permanently
$ cvs ci -m "Removed unneeded files"
cvs commit: Examining .
cvs commit: Committing .

If you change your mind you can easily resurrect the file before you commit it, using the add command.

$ ls
CVS   ja.h  oj.c
$ rm oj.c
$ cvs remove oj.c
cvs remove: scheduling oj.c for removal
cvs remove: use 'cvs commit' to remove this file permanently
$ cvs add oj.c
U oj.c
cvs add: oj.c, version 1.1.1.1, resurrected

If you realize your mistake before you run the remove command you can use update to resurrect the file:

$ rm oj.c
$ cvs update oj.c
cvs update: warning: oj.c was lost
U oj.c

When you remove a file it is added only on the branch which you are working on (see section Branches). You can later merge the additions to another branch if you want (see section Merging can add or remove files).

Tracking third-party sources

If you modify a program to better fit your site, you probably want to include your modifications when the next release of the program arrives. CVS can help you with this task.

In the terminology used in CVS, the supplier of the program is called a vendor. The unmodified distribution from the vendor is checked in on its own branch, the vendor branch. CVS reserves branch 1.1.1 for this use.

When you modify the source and commit it, your revision will end up on the main trunk. When a new release is made by the vendor, you commit it on the vendor branch and copy the modifications onto the main trunk.

Use the import command to create and update the vendor branch. After a successful import the vendor branch is made the `head' revision, so anyone that checks out a copy of the file gets that revision. When a local modification is committed it is placed on the main trunk, and made the `head' revision.

Importing a module for the first time

Use the import command to check in the sources for the first time. When you use the import command to track third-party sources, the vendor tag and release tags are useful. The vendor tag is a symbolic name for the branch (which is always 1.1.1, unless you use the `-b branch' flag---See section import options). The release tags are symbolic names for a particular release, such as `FSF_0_04'.

Suppose you use wdiff (a variant of diff that ignores changes that only involve whitespace), and are going to make private modifications that you want to be able to use even when new releases are made in the future. You start by importing the source to your repository:

$ tar xfz wdiff-0.04.tar.gz
$ cd wdiff-0.04
$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04

The vendor tag is named `FSF_DIST' in the above example, and the only release tag assigned is `WDIFF_0_04'.

Updating a module with the import command

When a new release of the source arrives, you import it into the repository with the same import command that you used to set up the repository in the first place. The only difference is that you specify a different release tag this time.

$ tar xfz wdiff-0.05.tar.gz
$ cd wdiff-0.05
$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05

For files that have not been modified locally, the newly created revision becomes the head revision. If you have made local changes, import will warn you that you must merge the changes into the main trunk, and tell you to use `checkout -j' to do so.

$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff

The above command will check out the latest revision of `wdiff', merging the changes made on the vendor branch `FSF_DIST' since yesterday into the working copy. If any conflicts arise during the merge they should be resolved in the normal way (see section Conflicts example). Then, the modified files may be committed.

Using a date, as suggested above, assumes that you do not import more than one release of a product per day. If you do, you can always use something like this instead:

$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff

In this case, the two above commands are equivalent.

How to handle binary files with cvs import

Use the `-k' wrapper option to tell import which files are binary. See section The cvswrappers file.

Moving and renaming files

Moving files to a different directory or renaming them is not difficult, but some of the ways in which this works may be non-obvious. (Moving or renaming a directory is even harder. See section Moving and renaming directories).

The examples below assume that the file old is renamed to new.

The Normal way to Rename

The normal way to move a file is to copy old to new, and then issue the normal CVS commands to remove old from the repository, and add new to it. (Both old and new could contain relative paths, for example `foo/bar.c').

$ mv old new
$ cvs remove old
$ cvs add new
$ cvs commit -m "Renamed old to new" old new

This is the simplest way to move a file, it is not error-prone, and it preserves the history of what was done. Note that to access the history of the file you must specify the old or the new name, depending on what portion of the history you are accessing. For example, cvs log old will give the log up until the time of the rename.

When new is committed its revision numbers will start at 1.0 again, so if that bothers you, use the `-r rev' option to commit (see section commit options)

Moving the history file

This method is more dangerous, since it involves moving files inside the repository. Read this entire section before trying it out!

$ cd $CVSROOT/module
$ mv old,v new,v

Advantages:

  • The log of changes is maintained intact.
  • The revision numbers are not affected.

Disadvantages:

  • Old releases of the module cannot easily be fetched from the repository. (The file will show up as new even in revisions from the time before it was renamed).
  • There is no log information of when the file was renamed.
  • Nasty things might happen if someone accesses the history file while you are moving it. Make sure no one else runs any of the CVS commands while you move it.

Copying the history file

This way also involves direct modifications to the repository. It is safe, but not without drawbacks.

# Copy the RCS file inside the repository
$ cd $CVSROOT/module
$ cp old,v new,v
# Remove the old file
$ cd ~/module
$ rm old
$ cvs remove old
$ cvs commit old
# Remove all tags from new
$ cvs update new
$ cvs log new             # Remember the non-branch tag names
$ cvs tag -d tag1 new
$ cvs tag -d tag2 new
...

By removing the tags you will be able to check out old revisions of the module.

Advantages:

  • Checking out old revisions works correctly, as long as you use `-rtag' and not `-Ddate' to retrieve the revisions.
  • The log of changes is maintained intact.
  • The revision numbers are not affected.

Disadvantages:

  • You cannot easily see the history of the file across the rename.
  • Unless you use the `-r rev' (see section commit options) flag when new is committed its revision numbers will start at 1.0 again.

Moving and renaming directories

If you want to be able to retrieve old versions of the module, you must move each file in the directory with the CVS commands. See section The Normal way to Rename. The old, empty directory will remain inside the repository, but it will not appear in your workspace when you check out the module in the future.

If you really want to rename or delete a directory, you can do it like this:

  1. Inform everyone who has a copy of the module that the directory will be renamed. They should commit all their changes, and remove their working copies of the module, before you take the steps below.
  2. Rename the directory inside the repository.
    $ cd $CVSROOT/module
$ mv old-dir new-dir
  3. Fix the CVS administrative files, if necessary (for instance if you renamed an entire module).
  4. Tell everyone that they can check out the module and continue working.

If someone had a working copy of the module the CVS commands will cease to work for him, until he removes the directory that disappeared inside the repository.

It is almost always better to move the files in the directory instead of moving the directory. If you move the directory you are unlikely to be able to retrieve old releases correctly, since they probably depend on the name of the directories.

History browsing

Once you have used CVS to store a version control history--what files have changed when, how, and by whom, there are a variety of mechanisms for looking through the history.

Log messages

Whenever you commit a file you specify a log message.

To look through the log messages which have been specified for every revision which has been committed, use the cvs log command (see section log--Print out log information for files).

The history database

You can use the history file (see section The history file) to log various CVS actions. To retrieve the information from the history file, use the cvs history command (see section history--Show status of files and users).

User-defined logging

You can customize CVS to log various kinds of actions, in whatever manner you choose. These mechanisms operate by executing a script at various times. The script might append a message to a file listing the information and the programmer who created it, or send mail to a group of developers, or, perhaps, post a message to a particular newsgroup. To log commits, use the `loginfo' file (see section Loginfo). To log commits, checkouts, exports, and tags, respectively, you can also use the `-i', `-o', `-e', and `-t' options in the modules file. For a more flexible way of giving notifications to various users, which requires less in the way of keeping centralized scripts up to date, use the cvs watch add command (see section Telling CVS to notify you); this command is useful even if you are not using cvs watch on.

The `taginfo' file defines programs to execute when someone executes a tag or rtag command. The `taginfo' file has the standard form for administrative files (see section Reference manual for the Administrative files), where each line is a regular expression followed by a command to execute. The arguments passed to the command are, in order, the tagname, operation (add for tag, mov for tag -F, and del for tag -d), repository, and any remaining are pairs of filename revision. A non-zero exit of the filter program will cause the tag to be aborted.

Annotate command

Command: cvs annotate [-lf] [-r rev|-D date] files ...

For each file in files, print the head revision of the trunk, together with information on the last modification for each line. For example:

$ cvs annotate ssfile
Annotations for ssfile
***************
1.1          (mary     27-Mar-96): ssfile line 1
1.2          (joe      28-Mar-96): ssfile line 2

The file `ssfile' currently contains two lines. The ssfile line 1 line was checked in by mary on March 27. Then, on March 28, joe added a line ssfile line 2, without modifying the ssfile line 1 line. This report doesn't tell you anything about lines which have been deleted or replaced; you need to use cvs diff for that (see section diff--Run diffs between revisions).

These standard options are available with annotate (see section Common command options, for a complete description of them):

-D date
Annotate the most recent revision no later than date.
-f
Only useful with the `-D date' or `-r tag' flags. If no matching revision is found, annotate the most recent revision (instead of ignoring the file).
-l
Local; run only in current working directory. See section Recursive behavior.
-r tag
Annotate revision tag.

Keyword substitution

As long as you edit source files inside your working copy of a module you can always find out the state of your files via `cvs status' and `cvs log'. But as soon as you export the files from your development environment it becomes harder to identify which revisions they are.

RCS uses a mechanism known as keyword substitution (or keyword expansion) to help identifying the files. Embedded strings of the form $keyword$ and $keyword:...$ in a file are replaced with strings of the form $keyword:value$ whenever you obtain a new revision of the file.

RCS Keywords

This is a list of the keywords that RCS currently (in release 5.6.0.1) supports:

$Author$
The login name of the user who checked in the revision.
$Date$
The date and time (UTC) the revision was checked in.
$Header$
A standard header containing the full pathname of the RCS file, the revision number, the date (UTC), the author, the state, and the locker (if locked). Files will normally never be locked when you use CVS.
$Id$
Same as $Header$, except that the RCS filename is without a path.
$Name$
Tag name used to check out this file.
$Locker$
The login name of the user who locked the revision (empty if not locked, and thus almost always useless when you are using CVS).
$Log$
The log message supplied during commit, preceded by a header containing the RCS filename, the revision number, the author, and the date (UTC). Existing log messages are not replaced. Instead, the new log message is inserted after $Log:...$. Each new line is prefixed with a comment leader which RCS guesses from the file name extension. It can be changed with cvs admin -c. See section admin options. This keyword is useful for accumulating a complete change log in a source file, but for several reasons it can be problematic. See section Problems with the $Log$ keyword..
$RCSfile$
The name of the RCS file without a path.
$Revision$
The revision number assigned to the revision.
$Source$
The full pathname of the RCS file.
$State$
The state assigned to the revision. States can be assigned with cvs admin -s---See section admin options.

Using keywords

To include a keyword string you simply include the relevant text string, such as $Id$, inside the file, and commit the file. CVS will automatically expand the string as part of the commit operation.

It is common to embed $Id$ string in the C source code. This example shows the first few lines of a typical file, after keyword substitution has been performed:

static char *rcsid="$Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
/* The following lines will prevent gcc version 2.x
   from issuing an "unused variable" warning. */
#if __GNUC__ == 2
#define USE(var) static void * use_##var = (&use_##var, (void *) &var)
USE (rcsid);
#endif

Even though a clever optimizing compiler could remove the unused variable rcsid, most compilers tend to include the string in the binary. Some compilers have a #pragma directive to include literal text in the binary.

The ident command (which is part of the RCS package) can be used to extract keywords and their values from a file. This can be handy for text files, but it is even more useful for extracting keywords from binary files.

$ ident samp.c
samp.c:
     $Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
$ gcc samp.c
$ ident a.out
a.out:
     $Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $

SCCS is another popular revision control system. It has a command, what, which is very similar to ident and used for the same purpose. Many sites without RCS have SCCS. Since what looks for the character sequence @(#) it is easy to include keywords that are detected by either command. Simply prefix the RCS keyword with the magic SCCS phrase, like this:

static char *id="@(#) $Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";

Avoiding substitution

Keyword substitution has its disadvantages. Sometimes you might want the literal text string `$'Author$ to appear inside a file without RCS interpreting it as a keyword and expanding it into something like `$'Author: ceder $.

There is unfortunately no way to selectively turn off keyword substitution. You can use `-ko' (see section Substitution modes) to turn off keyword substitution entirely.

In many cases you can avoid using RCS keywords in the source, even though they appear in the final product. For example, the source for this manual contains `$@asis{}Author$' whenever the text `$'Author$ should appear. In nroff and troff you can embed the null-character \& inside the keyword for a similar effect.

Substitution modes

Each file has a stored default substitution mode, and each working directory copy of a file also has a substitution mode. The former is set by the `-k' option to cvs add and cvs admin; the latter is set by the -k or -A options to cvs checkout or cvs update. cvs diff also has a `-k' option. For some examples, See section Handling binary files.

The modes available are:

`-kkv'
Generate keyword strings using the default form, e.g. $Revision: 5.7 $ for the Revision keyword.
`-kkvl'
Like `-kkv', except that a locker's name is always inserted if the given revision is currently locked. This option is normally not useful when CVS is used.
`-kk'
Generate only keyword names in keyword strings; omit their values. For example, for the Revision keyword, generate the string $Revision$ instead of $Revision: 5.7 $. This option is useful to ignore differences due to keyword substitution when comparing different revisions of a file.
`-ko'
Generate the old keyword string, present in the working file just before it was checked in. For example, for the Revision keyword, generate the string $Revision: 1.1 $ instead of $Revision: 5.7 $ if that is how the string appeared when the file was checked in.
`-kb'
Like `-ko', but also inhibit conversion of line endings between the canonical form in which they are stored in the repository (linefeed only), and the form appropriate to the operating system in use on the client. For systems, like unix, which use linefeed only to terminate lines, this is the same as `-ko'. For more information on binary files, see section Handling binary files.
`-kv'
Generate only keyword values for keyword strings. For example, for the Revision keyword, generate the string 5.7 instead of $Revision: 5.7 $. This can help generate files in programming languages where it is hard to strip keyword delimiters like $Revision: $ from a string. However, further keyword substitution cannot be performed once the keyword names are removed, so this option should be used with care. One often would like to use `-kv' with cvs export---see section export--Export sources from CVS, similar to checkout. But be aware that doesn't handle an export containing binary files correctly.

Problems with the $Log$ keyword.

The $Log$ keyword is somewhat controversial. As long as you are working on your development system the information is easily accessible even if you do not use the $Log$ keyword--just do a cvs log. Once you export the file the history information might be useless anyhow.

A more serious concern is that RCS is not good at handling $Log$ entries when a branch is merged onto the main trunk. Conflicts often result from the merging operation.

People also tend to "fix" the log entries in the file (correcting spelling mistakes and maybe even factual errors). If that is done the information from cvs log will not be consistent with the information inside the file. This may or may not be a problem in real life.

It has been suggested that the $Log$ keyword should be inserted last in the file, and not in the files header, if it is to be used at all. That way the long list of change messages will not interfere with everyday source file browsing.

Handling binary files

There are two issues with using CVS to store binary files. The first is that CVS by default convert line endings between the canonical form in which they are stored in the repository (linefeed only), and the form appropriate to the operating system in use on the client (for example, carriage return followed by line feed for Windows NT).

The second is that a binary file might happen to contain data which looks like a keyword (see section Keyword substitution), so keyword expansion must be turned off.

The `-kb' option available with some CVS commands insures that neither line ending conversion nor keyword expansion will be done. If you are using an old version of RCS without this option, and you are using an operating system, such as unix, which terminates lines with linefeeds only, you can use `-ko' instead; if you are on another operating system, upgrade to a version of RCS, such as 5.7 or later, which supports `-kb'.

Here is an example of how you can create a new file using the `-kb' flag:

$ echo '$Id$' > kotest
$ cvs add -kb -m"A test file" kotest
$ cvs ci -m"First checkin; contains a keyword" kotest

If a file accidentally gets added without `-kb', one can use the cvs admin command to recover. For example:

$ echo '$Id$' > kotest
$ cvs add -m"A test file" kotest
$ cvs ci -m"First checkin; contains a keyword" kotest
$ cvs admin -kb kotest
$ cvs update -A kotest
$ cvs commit -m "make it binary" kotest  # For non-unix systems

When you check in the file `kotest' the keywords are expanded. (Try the above example, and do a cat kotest after every command). The cvs admin -kb command sets the default keyword substitution method for this file, but it does not alter the working copy of the file that you have. The easiest way to get the unexpanded version of `kotest' is cvs update -A. If you need to cope with line endings (that is, you are using a CVS client on a non-unix system), then you need to check in a new copy of the file, as shown by the cvs commit command above.

However, in using cvs admin -k to change the keyword expansion, be aware that the keyword expansion mode is not version controlled. This means that, for example, that if you have a text file in old releases, and a binary file with the same name in new releases, CVS provides no way to check out the file in text or binary mode depending on what version you are checking out. There is no good workaround for this problem.

You can also set a default for whether cvs add and cvs import treat a file as binary based on its name; for example you could say that files who names end in `.exe' are binary. See section The cvswrappers file.

Revision management

If you have read this far, you probably have a pretty good grasp on what CVS can do for you. This chapter talks a little about things that you still have to decide.

If you are doing development on your own using CVS you could probably skip this chapter. The questions this chapter takes up become more important when more than one person is working in a repository.

When to commit?

Your group should decide which policy to use regarding commits. Several policies are possible, and as your experience with CVS grows you will probably find out what works for you.

If you commit files too quickly you might commit files that do not even compile. If your partner updates his working sources to include your buggy file, he will be unable to compile the code. On the other hand, other persons will not be able to benefit from the improvements you make to the code if you commit very seldom, and conflicts will probably be more common.

It is common to only commit files after making sure that they can be compiled. Some sites require that the files pass a test suite. Policies like this can be enforced using the commitinfo file (see section Commitinfo), but you should think twice before you enforce such a convention. By making the development environment too controlled it might become too regimented and thus counter-productive to the real goal, which is to get software written.

Reference manual for CVS commands

This appendix describes how to invoke CVS, and describes in detail those subcommands of CVS which are not fully described elsewhere. To look up a particular subcommand, see section Index.

Overall structure of CVS commands

The overall format of all CVS commands is:

cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
cvs
The name of the CVS program.
cvs_options
Some options that affect all sub-commands of CVS. These are described below.
cvs_command
One of several different sub-commands. Some of the commands have aliases that can be used instead; those aliases are noted in the reference manual for that command. There are only two situations where you may omit `cvs_command': `cvs -H' elicits a list of available commands, and `cvs -v' displays version information on CVS itself.
command_options
Options that are specific for the command.
command_args
Arguments to the commands.

There is unfortunately some confusion between cvs_options and command_options. `-l', when given as a cvs_option, only affects some of the commands. When it is given as a command_option is has a different meaning, and is accepted by more commands. In other words, do not take the above categorization too seriously. Look at the documentation instead.

Default options and the ~/.cvsrc file

There are some command_options that are used so often that you might have set up an alias or some other means to make sure you always specify that option. One example (the one that drove the implementation of the .cvsrc support, actually) is that many people find the default output of the `diff' command to be very hard to read, and that either context diffs or unidiffs are much easier to understand.

The `~/.cvsrc' file is a way that you can add default options to cvs_commands within cvs, instead of relying on aliases or other shell scripts.

The format of the `~/.cvsrc' file is simple. The file is searched for a line that begins with the same name as the cvs_command being executed. If a match is found, then the remainder of the line is split up (at whitespace characters) into separate options and added to the command arguments before any options from the command line.

If a command has two names (e.g., checkout and co), the official name, not necessarily the one used on the command line, will be used to match against the file. So if this is the contents of the user's `~/.cvsrc' file:

log -N
diff -u
update -P
co -P

the command `cvs checkout foo' would have the `-P' option added to the arguments, as well as `cvs co foo'.

With the example file above, the output from `cvs diff foobar' will be in unidiff format. `cvs diff -c foobar' will provide context diffs, as usual. Getting "old" format diffs would be slightly more complicated, because diff doesn't have an option to specify use of the "old" format, so you would need `cvs -f diff foobar'.

In place of the command name you can use cvs to specify global options (see section Global options). For example the following line in `.cvsrc'

cvs -z6

causes CVS to use compression level 6

Global options

The available `cvs_options' (that are given to the left of `cvs_command') are:

-b bindir
Use bindir as the directory where RCS programs are located. Overrides the setting of the $RCSBIN environment variable and any precompiled directory. This parameter should be specified as an absolute pathname.
-T tempdir
Use tempdir as the directory where temporary files are located. Overrides the setting of the $TMPDIR environment variable and any precompiled directory. This parameter should be specified as an absolute pathname.
-d cvs_root_directory
Use cvs_root_directory as the root directory pathname of the repository. Overrides the setting of the $CVSROOT environment variable. See section The Repository.
-e editor
Use editor to enter revision log information. Overrides the setting of the $CVSEDITOR and $EDITOR environment variables.
-f
Do not read the `~/.cvsrc' file. This option is most often used because of the non-orthogonality of the CVS option set. For example, the `cvs log' option `-N' (turn off display of tag names) does not have a corresponding option to turn the display on. So if you have `-N' in the `~/.cvsrc' entry for `log', you may need to use `-f' to show the tag names.
-H
Display usage information about the specified `cvs_command' (but do not actually execute the command). If you don't specify a command name, `cvs -H' displays a summary of all the commands available.
-l
Do not log the cvs_command in the command history (but execute it anyway). See section history--Show status of files and users, for information on command history.
-n
Do not change any files. Attempt to execute the `cvs_command', but only to issue reports; do not remove, update, or merge any existing files, or create any new files.
-Q
Cause the command to be really quiet; the command will only generate output for serious problems.
-q
Cause the command to be somewhat quiet; informational messages, such as reports of recursion through subdirectories, are suppressed.
-r
Make new working files files read-only. Same effect as if the $CVSREAD environment variable is set (see section All environment variables which affect CVS). The default is to make working files writable, unless watches are on (see section Mechanisms to track who is editing files).
-s variable=value
Set a user variable (see section Expansions in administrative files).
-t
Trace program execution; display messages showing the steps of CVS activity. Particularly useful with `-n' to explore the potential impact of an unfamiliar command.
-v
Display version and copyright information for CVS.
-w
Make new working files read-write. Overrides the setting of the $CVSREAD environment variable. Files are created read-write by default, unless $CVSREAD is set or `-r' is given.
-x
Encrypt all communication between the client and the server. Only has an effect on the CVS client. As of this writing, this is only implemented when using a Kerberos connection (see section Direct connection with kerberos). Encryption support is not available by default; it must be enabled using a special configure option, `--enable-encryption', when you build CVS.
-z gzip-level
Set the compression level. Only has an effect on the CVS client.

Common command options

This section describes the `command_options' that are available across several CVS commands. These options are always given to the right of `cvs_command'. Not all commands support all of these options; each option is only supported for commands where it makes sense. However, when a command has one of these options you can almost always count on the same behavior of the option as in other commands. (Other command options, which are listed with the individual commands, may have different behavior from one CVS command to the other).

Warning: the `history' command is an exception; it supports many options that conflict even with these standard options.

-D date_spec
Use the most recent revision no later than date_spec. date_spec is a single argument, a date description specifying a date in the past. The specification is sticky when you use it to make a private copy of a source file; that is, when you get a working file using `-D', CVS records the date you specified, so that further updates in the same directory will use the same date (for more information on sticky tags/dates, see section Sticky tags). A wide variety of date formats are supported by CVS. The date_spec is interpreted as being in the local timezone, unless a specific timezone is specified. Examples of valid date specifications include:
                    1 month ago
                    2 hours ago
                    400000 seconds ago
                    last year
                    last Monday
                    yesterday
                    a fortnight ago
                    3/31/92 10:00:07 PST
                    January 23, 1987 10:05pm
                    22:00 GMT
`-D' is available with the checkout, diff, export, history, rdiff, rtag, and update commands. (The history command uses this option in a slightly different way; see section history options). Note that when specifying a date like `3/31/92' it is month/day/year. So `1/4/96' is January 4, not March 1. Remember to quote the argument to the `-D' flag so that your shell doesn't interpret spaces as argument separators. A command using the `-D' flag can look like this:
$ cvs diff -D "1 hour ago" cvs.texinfo
-f
When you specify a particular date or tag to CVS commands, they normally ignore files that do not contain the tag (or did not exist prior to the date) that you specified. Use the `-f' option if you want files retrieved even when there is no match for the tag or date. (The most recent revision of the file will be used). `-f' is available with these commands: checkout, export, rdiff, rtag, and update. Warning: The commit command also has a `-f' option, but it has a different behavior for that command. See section commit options.
-H
Help; describe the options available for this command. This is the only option supported for all CVS commands.
-k kflag
Alter the default RCS processing of keywords. See section Keyword substitution, for the meaning of kflag. Your kflag specification is sticky when you use it to create a private copy of a source file; that is, when you use this option with the checkout or update commands, CVS associates your selected kflag with the file, and continues to use it with future update commands on the same file until you specify otherwise. The `-k' option is available with the add, checkout, diff and update commands.
-l
Local; run only in current working directory, rather than recursing through subdirectories. Warning: this is not the same as the overall `cvs -l' option, which you can specify to the left of a cvs command! Available with the following commands: checkout, commit, diff, export, log, remove, rdiff, rtag, status, tag, and update.
-m message
Use message as log information, instead of invoking an editor. Available with the following commands: add, commit and import.
-n
Do not run any checkout/commit/tag program. (A program can be specified to run on each of these activities, in the modules database (see section The modules file); this option bypasses it). Warning: this is not the same as the overall `cvs -n' option, which you can specify to the left of a cvs command! Available with the checkout, commit, export, and rtag commands.
-P
Prune (remove) directories that are empty after being updated, on checkout, or update. Normally, an empty directory (one that is void of revision-controlled files) is left alone. Specifying `-P' will cause these directories to be silently removed from your checked-out sources. This does not remove the directory from the repository, only from your checked out copy. Note that this option is implied by the `-r' or `-D' options of checkout and export.
-p
Pipe the files retrieved from the repository to standard output, rather than writing them in the current directory. Available with the checkout and update commands.
-W
Specify file names that should be filtered. You can use this option repeatedly. The spec can be a file name pattern of the same type that you can specify in the `.cvswrappers' file. Avaliable with the following commands: import, and update.
-r tag
Use the revision specified by the tag argument instead of the default head revision. As well as arbitrary tags defined with the tag or rtag command, two special tags are always available: `HEAD' refers to the most recent version available in the repository, and `BASE' refers to the revision you last checked out into the current working directory. The tag specification is sticky when you use this with checkout or update to make your own copy of a file: CVS remembers the tag and continues to use it on future update commands, until you specify otherwise (for more information on sticky tags/dates, see section Sticky tags). The tag can be either a symbolic or numeric tag. See section Tags--Symbolic revisions. Specifying the `-q' global option along with the `-r' command option is often useful, to suppress the warning messages when the RCS history file does not contain the specified tag. Warning: this is not the same as the overall `cvs -r' option, which you can specify to the left of a cvs command! `-r' is available with the checkout, commit, diff, history, export, rdiff, rtag, and update commands.

admin--Administration front end for rcs

  • Requires: repository, working directory.
  • Changes: repository.
  • Synonym: rcs

This is the CVS interface to assorted administrative RCS facilities, documented in rcs(1). admin simply passes all its options and arguments to the rcs command; it does no filtering or other processing. This command does work recursively, however, so extreme care should be used.

If there is a group whose name matches a compiled in value which defaults to cvsadmin, only members of that group can use cvs admin. To disallow cvs admin for all users, create a group with no users in it.

admin options

Not all valid rcs options are useful together with CVS. Some even makes it impossible to use CVS until you undo the effect!

This description of the available options is based on the `rcs(1)' man page, but modified to suit readers that are more interrested in CVS than RCS.

-Aoldfile
Might not work together with CVS. Append the access list of oldfile to the access list of the RCS file.
-alogins
Might not work together with CVS. Append the login names appearing in the comma-separated list logins to the access list of the RCS file.
-b[rev]
When used with bare RCS, this option sets the default branch to rev; in CVS sticky tags (see section Sticky tags) are a better way to decide which branch you want to work on. With CVS, this option can be used to control behavior with respect to the vendor branch.
-cstring
Useful with CVS. Sets the comment leader to string. The comment leader is printed before every log message line generated by the keyword $Log$ (see section Keyword substitution). This is useful for programming languages without multi-line comments. RCS initially guesses the value of the comment leader from the file name extension when the file is first committed.
-e[logins]
Might not work together with CVS. Erase the login names appearing in the comma-separated list logins from the access list of the RCS file. If logins is omitted, erase the entire access list.
-I
Run interactively, even if the standard input is not a terminal.
-i
Useless with CVS. When using bare RCS, this is used to create and initialize a new RCS file, without depositing a revision.
-ksubst
Useful with CVS. Set the default keyword substitution to subst. See section Keyword substitution. Giving an explicit `-k' option to cvs update, cvs export, or cvs checkout overrides this default.
-l[rev]
Lock the revision with number rev. If a branch is given, lock the latest revision on that branch. If rev is omitted, lock the latest revision on the default branch. This can be used in conjunction with the `rcslock.pl' script in the `contrib' directory of the CVS source distribution to provide reserved checkouts (where only one user can be editing a given file at a time). See the comments in that file for details (and see the `README' file in that directory for disclaimers about the unsupported nature of contrib). According to comments in that file, locking must set to strict (which is the default).
-L
Set locking to strict. Strict locking means that the owner of an RCS file is not exempt from locking for checkin. For use with CVS, strict locking must be set; see the discussion under the `-l' option above.
-mrev:msg
Replace the log message of revision rev with msg.
-Nname[:[rev]]
Act like `-n', except override any previous assignment of name.
-nname[:[rev]]
Associate the symbolic name name with the branch or revision rev. It is normally better to use `cvs tag' or `cvs rtag' instead. Delete the symbolic name if both `:' and rev are omitted; otherwise, print an error message if name is already associated with another number. If rev is symbolic, it is expanded before association. A rev consisting of a branch number followed by a `.' stands for the current latest revision in the branch. A `:' with an empty rev stands for the current latest revision on the default branch, normally the trunk. For example, `rcs -nname: RCS/*' associates name with the current latest revision of all the named RCS files; this contrasts with `rcs -nname:$ RCS/*' which associates name with the revision numbers extracted from keyword strings in the corresponding working files.
-orange
Potentially useful, but dangerous, with CVS (see below). Deletes (outdates) the revisions given by range. A range consisting of a single revision number means that revision. A range consisting of a branch number means the latest revision on that branch. A range of the form `rev1:rev2' means revisions rev1 to rev2 on the same branch, `:rev' means from the beginning of the branch containing rev up to and including rev, and `rev:' means from revision rev to the end of the branch containing rev. None of the outdated revisions may have branches or locks. Due to the way CVS handles branches rev cannot be specified symbolically if it is a branch. See section Magic branch numbers, for an explanation. Make sure that no-one has checked out a copy of the revision you outdate. Strange things will happen if he starts to edit it and tries to check it back in. For this reason, this option is not a good way to take back a bogus commit; commit a new revision undoing the bogus change instead (see section Merging differences between any two revisions).
-q
Run quietly; do not print diagnostics.
-sstate[:rev]
Useful with CVS. Set the state attribute of the revision rev to state. If rev is a branch number, assume the latest revision on that branch. If rev is omitted, assume the latest revision on the default branch. Any identifier is acceptable for state. A useful set of states is `Exp' (for experimental), `Stab' (for stable), and `Rel' (for released). By default, the state of a new revision is set to `Exp' when it is created. The state is visible in the output from cvs log (see section log--Print out log information for files), and in the `$'Log$ and `$'State$ keywords (see section Keyword substitution). Note that CVS uses the dead state for its own purposes; to take a file to or from the dead state use commands like cvs remove and cvs add, not cvs admin -s.
-t[file]
Useful with CVS. Write descriptive text from the contents of the named file into the RCS file, deleting the existing text. The file pathname may not begin with `-'. If file is omitted, obtain the text from standard input, terminated by end-of-file or by a line containing `.' by itself. Prompt for the text if interaction is possible; see `-I'. The descriptive text can be seen in the output from `cvs log' (see section log--Print out log information for files).
-t-string
Similar to `-tfile'. Write descriptive text from the string into the RCS file, deleting the existing text.
-U
Set locking to non-strict. Non-strict locking means that the owner of a file need not lock a revision for checkin. For use with CVS, strict locking must be set; see the discussion under the `-l' option above.
-u[rev]
See the option `-l' above, for a discussion of using this option with CVS. Unlock the revision with number rev. If a branch is given, unlock the latest revision on that branch. If rev is omitted, remove the latest lock held by the caller. Normally, only the locker of a revision may unlock it. Somebody else unlocking a revision breaks the lock. This causes a mail message to be sent to the original locker. The message contains a commentary solicited from the breaker. The commentary is terminated by end-of-file or by a line containing . by itself.
-Vn
Emulate RCS version n. Use -Vn to make an RCS file acceptable to RCS version n by discarding information that would confuse version n.
-xsuffixes
Useless with CVS. Use suffixes to characterize RCS files.

admin examples

Outdating is dangerous

First, an example of how not to use the admin command. It is included to stress the fact that this command can be quite dangerous unless you know exactly what you are doing.

The `-o' option can be used to outdate old revisions from the history file. If you are short on disc this option might help you. But think twice before using it--there is no way short of restoring the latest backup to undo this command!

The next line is an example of a command that you would not like to execute.

$ cvs admin -o:R_1_02 .

The above command will delete all revisions up to, and including, the revision that corresponds to the tag R_1_02. But beware! If there are files that have not changed between R_1_02 and R_1_03 the file will have the same numerical revision number assigned to the tags R_1_02 and R_1_03. So not only will it be impossible to retrieve R_1_02; R_1_03 will also have to be restored from the tapes!

Comment leaders

If you use the $Log$ keyword and you do not agree with the guess for comment leader that CVS has done, you can enforce your will with cvs admin -c. This might be suitable for nroff source:

$ cvs admin -c'.\" ' *.man
$ rm *.man
$ cvs update

The two last steps are to make sure that you get the versions with correct comment leaders in your working files.

checkout--Check out sources for editing

  • Synopsis: checkout [options] modules...
  • Requires: repository.
  • Changes: working directory.
  • Synonyms: co, get

Make a working directory containing copies of the source files specified by modules. You must execute checkout before using most of the other CVS commands, since most of them operate on your working directory.

The modules part of the command are either symbolic names for some collection of source directories and files, or paths to directories or files in the repository. The symbolic names are defined in the `modules' file. See section The modules file.

Depending on the modules you specify, checkout may recursively create directories and populate them with the appropriate source files. You can then edit these source files at any time (regardless of whether other software developers are editing their own copies of the sources); update them to include new changes applied by others to the source repository; or commit your work as a permanent change to the source repository.

Note that checkout is used to create directories. The top-level directory created is always added to the directory where checkout is invoked, and usually has the same name as the specified module. In the case of a module alias, the created sub-directory may have a different name, but you can be sure that it will be a sub-directory, and that checkout will show the relative path leading to each file as it is extracted into your private work area (unless you specify the `-Q' global option).

The files created by checkout are created read-write, unless the `-r' option to CVS (see section Global options) is specified, the CVSREAD environment variable is specified (see section All environment variables which affect CVS), or a watch is in effect for that file (see section Mechanisms to track who is editing files).

Running checkout on a directory that was already built by a prior checkout is also permitted, and has the same effect as specifying the `-d' option to the update command, that is, any new directories that have been created in the repository will appear in your work area. See section update--Bring work tree in sync with repository.

For the output produced by the checkout command see section update output.

checkout options

These standard options are supported by checkout (see section Common command options, for a complete description of them):

-D date
Use the most recent revision no later than date. This option is sticky, and implies `-P'. See section Sticky tags, for more information on sticky tags/dates.
-f
Only useful with the `-D date' or `-r tag' flags. If no matching revision is found, retrieve the most recent revision (instead of ignoring the file).
-k kflag
Process RCS keywords according to kflag. See co(1). This option is sticky; future updates of this file in this working directory will use the same kflag. The status command can be viewed to see the sticky options. See section status--Display status information on checked out files.
-l
Local; run only in current working directory.
-n
Do not run any checkout program (as specified with the `-o' option in the modules file; see section The modules file).
-P
Prune empty directories.
-p
Pipe files to the standard output.
-r tag
Use revision tag. This option is sticky, and implies `-P'. See section Sticky tags, for more information on sticky tags/dates.

In addition to those, you can use these special command options with checkout:

-A
Reset any sticky tags, dates, or `-k' options. See section Sticky tags, for more information on sticky tags/dates.
-c
Copy the module file, sorted, to the standard output, instead of creating or modifying any files or directories in your working directory.
-d dir
Create a directory called dir for the working files, instead of using the module name. Unless you also use `-N', the paths created under dir will be as short as possible.
-j tag
With two `-j' options, merge changes from the revision specified with the first `-j' option to the revision specified with the second `j' option, into the working directory. With one `-j' option, merge changes from the ancestor revision to the revision specified with the `-j' option, into the working directory. The ancestor revision is the common ancestor of the revision which the working directory is based on, and the revision specified in the `-j' option. In addition, each -j option can contain an optional date specification which, when used with branches, can limit the chosen revision to one within a specific date. An optional date is specified by adding a colon (:) to the tag: `-jSymbolic_Tag:Date_Specifier'. See section Merging.
-N
Only useful together with `-d dir'. With this option, CVS will not shorten module paths in your working directory. (Normally, CVS shortens paths as much as possible when you specify an explicit target directory).
-s
Like `-c', but include the status of all modules, and sort it by the status string. See section The modules file, for info about the `-s' option that is used inside the modules file to set the module status.

checkout examples

Get a copy of the module `tc':

$ cvs checkout tc

Get a copy of the module `tc' as it looked one day ago:

$ cvs checkout -D yesterday tc

commit--Check files into the repository

  • Version 1.3 Synopsis: commit [-lnR] [-m 'log_message' | -f file] [-r revision] [files...]
  • Version 1.3.1 Synopsis: commit [-lnRf] [-m 'log_message' | -F file] [-r revision] [files...]
  • Requires: working directory, repository.
  • Changes: repository.
  • Synonym: ci

Warning: The `-f file' option will probably be renamed to `-F file', and `-f' will be given a new behavior in future releases of CVS.

Use commit when you want to incorporate changes from your working source files into the source repository.

If you don't specify particular files to commit, all of the files in your working current directory are examined. commit is careful to change in the repository only those files that you have really changed. By default (or if you explicitly specify the `-R' option), files in subdirectories are also examined and committed if they have changed; you can use the `-l' option to limit commit to the current directory only.

commit verifies that the selected files are up to date with the current revisions in the source repository; it will notify you, and exit without committing, if any of the specified files must be made current first with update (see section update--Bring work tree in sync with repository). commit does not call the update command for you, but rather leaves that for you to do when the time is right.

When all is well, an editor is invoked to allow you to enter a log message that will be written to one or more logging programs (see section The modules file, and see section Loginfo) and placed in the RCS history file inside the repository. This log message can be retrieved with the log command; See section log--Print out log information for files. You can specify the log message on the command line with the `-m message' option, and thus avoid the editor invocation, or use the `-f file' option to specify that the argument file contains the log message.

commit options

These standard options are supported by commit (see section Common command options, for a complete description of them):

-l
Local; run only in current working directory.
-n
Do not run any module program.
-R
Commit directories recursively. This is on by default.
-r revision
Commit to revision. revision must be either a branch, or a revision on the main trunk that is higher than any existing revision number. You cannot commit to a specific revision on a branch.

commit also supports these options:

-F file
This option is present in CVS releases 1.3-s3 and later. Read the log message from file, instead of invoking an editor.
-f
This option is present in CVS 1.3-s3 and later releases of CVS. Note that this is not the standard behavior of the `-f' option as defined in See section Common command options. Force CVS to commit a new revision even if you haven't made any changes to the file. If the current revision of file is 1.7, then the following two commands are equivalent:
$ cvs commit -f file
$ cvs commit -r 1.8 file
-f file
This option is present in CVS releases 1.3, 1.3-s1 and 1.3-s2. Note that this is not the standard behavior of the `-f' option as defined in See section Common command options. Read the log message from file, instead of invoking an editor.
-m message
Use message as the log message, instead of invoking an editor.

commit examples

New major release number

When you make a major release of your product, you might want the revision numbers to track your major release number. You should normally not care about the revision numbers, but this is a thing that many people want to do, and it can be done without doing any harm.

To bring all your files up to the RCS revision 3.0 (including those that haven't changed), you might do:

$ cvs commit -r 3.0

Note that it is generally a bad idea to try to make the RCS revision number equal to the current release number of your product. You should think of the revision number as an internal number that the CVS package maintains, and that you generally never need to care much about. Using the tag and rtag commands you can give symbolic names to the releases instead. See section tag--Add a symbolic tag to checked out versions of files and See section rtag--Add a symbolic tag to a module.

Note that the number you specify with `-r' must be larger than any existing revision number. That is, if revision 3.0 exists, you cannot `cvs commit -r 1.3'.

Committing to a branch

You can commit to a branch revision (one that has an even number of dots) with the `-r' option. To create a branch revision, use the `-b' option of the rtag or tag commands (see section tag--Add a symbolic tag to checked out versions of files or see section rtag--Add a symbolic tag to a module). Then, either checkout or update can be used to base your sources on the newly created branch. From that point on, all commit changes made within these working sources will be automatically added to a branch revision, thereby not disturbing main-line development in any way. For example, if you had to create a patch to the 1.2 version of the product, even though the 2.0 version is already under development, you might do:

$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
$ cvs checkout -r FCS1_2_Patch product_module
$ cd product_module
[[ hack away ]]
$ cvs commit

This works automatically since the `-r' option is sticky.

Creating the branch after editing

Say you have been working on some extremely experimental software, based on whatever revision you happened to checkout last week. If others in your group would like to work on this software with you, but without disturbing main-line development, you could commit your change to a new branch. Others can then checkout your experimental stuff and utilize the full benefit of CVS conflict resolution. The scenario might look like:

[[ hacked sources are present ]]
$ cvs tag -b EXPR1
$ cvs update -r EXPR1
$ cvs commit

The update command will make the `-r EXPR1' option sticky on all files. Note that your changes to the files will never be removed by the update command. The commit will automatically commit to the correct branch, because the `-r' is sticky. You could also do like this:

[[ hacked sources are present ]]
$ cvs tag -b EXPR1
$ cvs commit -r EXPR1

but then, only those files that were changed by you will have the `-r EXPR1' sticky flag. If you hack away, and commit without specifying the `-r EXPR1' flag, some files may accidentally end up on the main trunk.

To work with you on the experimental change, others would simply do

$ cvs checkout -r EXPR1 whatever_module

diff--Run diffs between revisions

  • Synopsis: diff [-l] [rcsdiff_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files...]
  • Requires: working directory, repository.
  • Changes: nothing.

The diff command is used to compare different revisions of files. The default action is to compare your working files with the revisions they were based on, and report any differences that are found.

If any file names are given, only those files are compared. If any directories are given, all files under them will be compared.

The exit status will be 0 if no differences were found, 1 if some differences were found, and 2 if any error occurred.

diff options

These standard options are supported by diff (see section Common command options, for a complete description of them):

-D date
Use the most recent revision no later than date. See `-r' for how this affects the comparison. CVS can be configured to pass the `-D' option through to rcsdiff (which in turn passes it on to diff. GNU diff uses `-D' as a way to put cpp-style `#define' statements around the output differences. There is no way short of testing to figure out how CVS was configured. In the default configuration CVS will use the `-D date' option.
-k kflag
Process RCS keywords according to kflag. See co(1).
-l
Local; run only in current working directory.
-R
Examine directories recursively. This option is on by default.
-r tag
Compare with revision tag. Zero, one or two `-r' options can be present. With no `-r' option, the working file will be compared with the revision it was based on. With one `-r', that revision will be compared to your current working file. With two `-r' options those two revisions will be compared (and your working file will not affect the outcome in any way). One or both `-r' options can be replaced by a `-D date' option, described above.

Any other options that are found are passed through to rcsdiff, which in turn passes them to diff. The exact meaning of the options depends on which diff you are using. The long options introduced in GNU diff 2.0 are not yet supported in CVS. See the documentation for your diff to see which options are supported.

diff examples

The following line produces a Unidiff (`-u' flag) between revision 1.14 and 1.19 of `backend.c'. Due to the `-kk' flag no keywords are substituted, so differences that only depend on keyword substitution are ignored.

$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c

Suppose the experimental branch EXPR1 was based on a set of files tagged RELEASE_1_0. To see what has happened on that branch, the following can be used:

$ cvs diff -r RELEASE_1_0 -r EXPR1

A command like this can be used to produce a context diff between two releases:

$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs

If you are maintaining ChangeLogs, a command like the following just before you commit your changes may help you write the ChangeLog entry. All local modifications that have not yet been committed will be printed.

$ cvs diff -u | less

export--Export sources from CVS, similar to checkout

  • Synopsis: export [-flNn] [-r rev|-D date] [-k subst] [-d dir] module...
  • Requires: repository.
  • Changes: current directory.

This command is a variant of checkout; use it when you want a copy of the source for module without the CVS administrative directories. For example, you might use export to prepare source for shipment off-site. This command requires that you specify a date or tag (with `-D' or `-r'), so that you can count on reproducing the source you ship to others.

One often would like to use `-kv' with cvs export. This causes any RCS keywords to be expanded such that an import done at some other site will not lose the keyword revision information. But be aware that doesn't handle an export containing binary files correctly. Also be aware that after having used `-kv', one can no longer use the ident command (which is part of the RCS suite--see ident(1)) which looks for RCS keyword strings. If you want to be able to use ident you must not use `-kv'.

export options

These standard options are supported by export (see section Common command options, for a complete description of them):

-D date
Use the most recent revision no later than date.
-f
If no matching revision is found, retrieve the most recent revision (instead of ignoring the file).
-l
Local; run only in current working directory.
-n
Do not run any checkout program.
-R
Export directories recursively. This is on by default.
-r tag
Use revision tag.

In addition, these options (that are common to checkout and export) are also supported:

-d dir
Create a directory called dir for the working files, instead of using the module name. Unless you also use `-N', the paths created under dir will be as short as possible.
-k subst
Set keyword expansion mode (see section Substitution modes).
-N
Only useful together with `-d dir'. With this option, CVS will not shorten module paths in your working directory. (Normally, CVS shortens paths as much as possible when you specify an explicit target directory.)

history--Show status of files and users

  • Synopsis: history [-report] [-flags] [-options args] [files...]
  • Requires: the file `$CVSROOT/CVSROOT/history'
  • Changes: nothing.

CVS can keep a history file that tracks each use of the checkout, commit, rtag, update, and release commands. You can use history to display this information in various formats.

Logging must be enabled by creating the file `$CVSROOT/CVSROOT/history'.

Warning: history uses `-f', `-l', `-n', and `-p' in ways that conflict with the normal use inside CVS (see section Common command options).

history options

Several options (shown above as `-report') control what kind of report is generated:

-c
Report on each time commit was used (i.e., each time the repository was modified).
-e
Everything (all record types); equivalent to specifying `-xMACFROGWUT'.
-m module
Report on a particular module. (You can meaningfully use `-m' more than once on the command line.)
-o
Report on checked-out modules.
-T
Report on all tags.
-x type
Extract a particular set of record types type from the CVS history. The types are indicated by single letters, which you may specify in combination. Certain commands have a single record type:
F
release
O
checkout
T
rtag
One of four record types may result from an update:
C
A merge was necessary but collisions were detected (requiring manual merging).
G
A merge was necessary and it succeeded.
U
A working file was copied from the repository.
W
The working copy of a file was deleted during update (because it was gone from the repository).
One of three record types results from commit:
A
A file was added for the first time.
M
A file was modified.
R
A file was removed.

The options shown as `-flags' constrain or expand the report without requiring option arguments:

-a
Show data for all users (the default is to show data only for the user executing history).
-l
Show last modification only.
-w
Show only the records for modifications done from the same working directory where history is executing.

The options shown as `-options args' constrain the report based on an argument:

-b str
Show data back to a record containing the string str in either the module name, the file name, or the repository path.
-D date
Show data since date. This is slightly different from the normal use of `-D date', which selects the newest revision older than date.
-p repository
Show data for a particular source repository (you can specify several `-p' options on the same command line).
-r rev
Show records referring to revisions since the revision or tag named rev appears in individual RCS files. Each RCS file is searched for the revision or tag.
-t tag
Show records since tag tag was last added to the the history file. This differs from the `-r' flag above in that it reads only the history file, not the RCS files, and is much faster.
-u name
Show records for user name.

import--Import sources into CVS, using vendor branches

  • Synopsis: import [-options] repository vendortag releasetag...
  • Requires: Repository, source distribution directory.
  • Changes: repository.

Use import to incorporate an entire source distribution from an outside source (e.g., a source vendor) into your source repository directory. You can use this command both for initial creation of a repository, and for wholesale updates to the module from the outside source. See section Tracking third-party sources, for a discussion on this subject.

The repository argument gives a directory name (or a path to a directory) under the CVS root directory for repositories; if the directory did not exist, import creates it.

When you use import for updates to source that has been modified in your source repository (since a prior import), it will notify you of any files that conflict in the two branches of development; use `checkout -j' to reconcile the differences, as import instructs you to do.

If CVS decides a file should be ignored (see section Ignoring files via cvsignore), it does not import it and prints `I ' followed by the filename (see section import output, for a complete description of the output).

If the file `$CVSROOT/CVSROOT/cvswrappers' exists, any file whose names match the specifications in that file will be treated as packages and the appropriate filtering will be performed on the file/directory before being imported, See section The cvswrappers file.

The outside source is saved in a first-level RCS branch, by default 1.1.1. Updates are leaves of this branch; for example, files from the first imported collection of source will be revision 1.1.1.1, then files from the first imported update will be revision 1.1.1.2, and so on.

At least three arguments are required. repository is needed to identify the collection of source. vendortag is a tag for the entire branch (e.g., for 1.1.1). You must also specify at least one releasetag to identify the files at the leaves created each time you execute import.

import options

This standard option is supported by import (see section Common command options, for a complete description):

-m message
Use message as log information, instead of invoking an editor.

There are three additional special options.

-b branch
Specify a first-level branch other than 1.1.1. Unless the `-b branch' flag is given, revisions will always be made to the branch 1.1.1--even if a vendortag that matches another branch is given! What happens in that case, is that the tag will be reset to 1.1.1. Warning: This behavior might change in the future.
-k subst
Indicate the RCS keyword expansion mode desired. This setting will apply to all files created during the import, but not to any files that previously existed in the repository. See section Substitution modes for a list of valid `-k' settings.
-I name
Specify file names that should be ignored during import. You can use this option repeatedly. To avoid ignoring any files at all (even those ignored by default), specify `-I !'. name can be a file name pattern of the same type that you can specify in the `.cvsignore' file. See section Ignoring files via cvsignore.
-W spec
Specify file names that should be filtered during import. You can use this option repeatedly. spec can be a file name pattern of the same type that you can specify in the `.cvswrappers' file. See section The cvswrappers file.

import output

import keeps you informed of its progress by printing a line for each file, preceded by one character indicating the status of the file:

U file
The file already exists in the repository and has not been locally modified; a new revision has been created (if necessary).
N file
The file is a new file which has been added to the repository.
C file
The file already exists in the repository but has been locally modified; you will have to merge the changes.
I file
The file is being ignored (see section Ignoring files via cvsignore).
L file
The file is a symbolic link; at the moment (and for the forseeable future), symbolic links are ignored. (Various options in the `modules' file can be used to recreate symbolic links on checkout, update, etc.; see section The modules file.)

import examples

See section Tracking third-party sources, and See section Creating a directory tree from a number of files.

log--Print out log information for files

  • Synopsis: log [options] [files...]
  • Requires: repository, working directory.
  • Changes: nothing.

Display log information for files. log used to call the RCS utility rlog. Although this is no longer true in the current sources, this history determines the format of the output and the options, which are not quite in the style of the other CVS commands.

The output includes the location of the RCS file, the head revision (the latest revision on the trunk), all symbolic names (tags) and some other things. For each revision, the revision number, the author, the number of lines added/deleted and the log message are printed. All times are displayed in Coordinated Universal Time (UTC). (Other parts of CVS print times in the local timezone).

log options

By default, log prints all information that is available. All other options restrict the output.

-b
Print information about the revisions on the default branch, normally the highest branch on the trunk.
-d dates
Print information about revisions with a checkin date/time in the range given by the semicolon-separated list of dates. The date formats accepted are those accepted by the `-D' option to many other CVS commands (see section Common command options). Dates can be combined into ranges as follows:
d1<d2
d2>d1
Select the revisions that were deposited between d1 and d2.
<d
d>
Select all revisions dated d or earlier.
d<
>d
Select all revisions dated d or later.
d
Select the single, latest revision dated d or earlier.
The `>' or `<' characters may be followed by `=' to indicate an inclusive range rather than an exclusive one. Note that the separator is a semicolon (;).
-h
Print only the RCS pathname, working pathname, head, default branch, access list, locks, symbolic names, and suffix.
-l
Local; run only in current working directory. (Default is to run recursively).
-N
Do not print the list of tags for this file. This option can be very useful when your site uses a lot of tags, so rather than "more"'ing over 3 pages of tag information, the log information is presented without tags at all.
-R
Print only the name of the RCS history file.
-rrevisions
Print information about revisions given in the comma-separated list revisions of revisions and ranges. The following table explains the available range formats:
rev1:rev2
Revisions rev1 to rev2 (which must be on the same branch).
:rev
Revisions from the beginning of the branch up to and including rev.
rev:
Revisions starting with rev to the end of the branch containing rev.
branch
An argument that is a branch means all revisions on that branch.
branch1:branch2
A range of branches means all revisions on the branches in that range.
branch.
The latest revision in branch.
A bare `-r' with no revisions means the latest revision on the default branch, normally the trunk. There can be no space between the `-r' option and its argument.
-s states
Print information about revisions whose state attributes match one of the states given in the comma-separated list states.
-t
Print the same as `-h', plus the descriptive text.
-wlogins
Print information about revisions checked in by users with login names appearing in the comma-separated list logins. If logins is omitted, the user's login is assumed. There can be no space between the `-w' option and its argument.

log prints the intersection of the revisions selected with the options `-d', `-s', and `-w', intersected with the union of the revisions selected by `-b' and `-r'.

log examples

Contributed examples are gratefully accepted.

rdiff---'patch' format diffs between releases

  • rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules...
  • Requires: repository.
  • Changes: nothing.
  • Synonym: patch

Builds a Larry Wall format patch(1) file between two releases, that can be fed directly into the patch program to bring an old release up-to-date with the new release. (This is one of the few CVS commands that operates directly from the repository, and doesn't require a prior checkout.) The diff output is sent to the standard output device.

You can specify (using the standard `-r' and `-D' options) any combination of one or two revisions or dates. If only one revision or date is specified, the patch file reflects differences between that revision or date and the current head revisions in the RCS file.

Note that if the software release affected is contained in more than one directory, then it may be necessary to specify the `-p' option to the patch command when patching the old sources, so that patch is able to find the files that are located in other directories.

rdiff options

These standard options are supported by rdiff (see section Common command options, for a complete description of them):

-D date
Use the most recent revision no later than date.
-f
If no matching revision is found, retrieve the most recent revision (instead of ignoring the file).
-l
Local; don't descend subdirectories.
-r tag
Use revision tag.

In addition to the above, these options are available:

-c
Use the context diff format. This is the default format.
-s
Create a summary change report instead of a patch. The summary includes information about files that were changed or added between the releases. It is sent to the standard output device. This is useful for finding out, for example, which files have changed between two dates or revisions.
-t
A diff of the top two revisions is sent to the standard output device. This is most useful for seeing what the last change to a file was.
-u
Use the unidiff format for the context diffs. This option is not available if your diff does not support the unidiff format. Remember that old versions of the patch program can't handle the unidiff format, so if you plan to post this patch to the net you should probably not use `-u'.
-V vn
Expand RCS keywords according to the rules current in RCS version vn (the expansion format changed with RCS version 5).

rdiff examples

Suppose you receive mail from foo@bar.com asking for an update from release 1.2 to 1.4 of the tc compiler. You have no such patches on hand, but with CVS that can easily be fixed with a command such as this:

$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
$$ Mail -s 'The patches you asked for' foo@bar.com

Suppose you have made release 1.3, and forked a branch called `R_1_3fix' for bugfixes. `R_1_3_1' corresponds to release 1.3.1, which was made some time ago. Now, you want to see how much development has been done on the branch. This command can be used:

$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
cvs rdiff: Diffing module-name
File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
File bar.h,v changed from revision 1.29.2.1 to 1.2

release--Indicate that a Module is no longer in use

  • release [-d] directories...
  • Requires: Working directory.
  • Changes: Working directory, history log.

This command is meant to safely cancel the effect of `cvs checkout'. Since CVS doesn't lock files, it isn't strictly necessary to use this command. You can always simply delete your working directory, if you like; but you risk losing changes you may have forgotten, and you leave no trace in the CVS history file (see section The history file) that you've abandoned your checkout.

Use `cvs release' to avoid these problems. This command checks that no uncommitted changes are present; that you are executing it from immediately above a CVS working directory; and that the repository recorded for your files is the same as the repository defined in the module database.

If all these conditions are true, `cvs release' leaves a record of its execution (attesting to your intentionally abandoning your checkout) in the CVS history log.

release options

The release command supports one command option:

-d
Delete your working copy of the file if the release succeeds. If this flag is not given your files will remain in your working directory. Warning: The release command deletes all directories and files recursively. This has the very serious side-effect that any directory that you have created inside your checked-out sources, and not added to the repository (using the add command; see section Adding files to a directory) will be silently deleted--even if it is non-empty!

release output

Before release releases your sources it will print a one-line message for any file that is not up-to-date.

Warning: Any new directories that you have created, but not added to the CVS directory hierarchy with the add command (see section Adding files to a directory) will be silently ignored (and deleted, if `-d' is specified), even if they contain files.

U file
There exists a newer revision of this file in the repository, and you have not modified your local copy of the file.
A file
The file has been added to your private copy of the sources, but has not yet been committed to the repository. If you delete your copy of the sources this file will be lost.
R file
The file has been removed from your private copy of the sources, but has not yet been removed from the repository, since you have not yet committed the removal. See section commit--Check files into the repository.
M file
The file is modified in your working directory. There might also be a newer revision inside the repository.
? file
file is in your working directory, but does not correspond to anything in the source repository, and is not in the list of files for CVS to ignore (see the description of the `-I' option, and see section Ignoring files via cvsignore). If you remove your working sources, this file will be lost. Note that no warning message like this is printed for spurious directories that CVS encounters. The directory, and all its contents, are silently ignored.

release examples

Release the module, and delete your local working copy of the files.

$ cd ..         # You must stand immediately above the
                # sources when you issue `cvs release'.
$ cvs release -d tc
You have [0] altered files in this repository.
Are you sure you want to release (and delete) module `tc': y
$

rtag--Add a symbolic tag to a module

  • rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules...
  • Requires: repository.
  • Changes: repository.
  • Synonym: rfreeze

You can use this command to assign symbolic tags to particular, explicitly specified source revisions in the repository. rtag works directly on the repository contents (and requires no prior checkout). Use tag instead (see section tag--Add a symbolic tag to checked out versions of files), to base the selection of revisions on the contents of your working directory.

If you attempt to use a tag name that already exists, CVS will complain and not overwrite that tag. Use the `-F' option to force the new tag value.

rtag options

These standard options are supported by rtag (see section Common command options, for a complete description of them):

-D date
Tag the most recent revision no later than date.
-f
Only useful with the `-D date' or `-r tag' flags. If no matching revision is found, use the most recent revision (instead of ignoring the file).
-F
Overwrite an existing tag of the same name on a different revision. This option is new in CVS 1.4. The old behavior is matched by `cvs tag -F'.
-l
Local; run only in current working directory.
-n
Do not run any tag program that was specified with the `-t' flag inside the `modules' file. (see section The modules file).
-R
Commit directories recursively. This is on by default.
-r tag
Only tag those files that contain tag. This can be used to rename a tag: tag only the files identified by the old tag, then delete the old tag, leaving the new tag on exactly the same files as the old tag.

In addition to the above common options, these options are available:

-a
Use the `-a' option to have rtag look in the `Attic' (see section Removing files from a module) for removed files that contain the specified tag. The tag is removed from these files, which makes it convenient to re-use a symbolic tag as development continues (and files get removed from the up-coming distribution).
-b
Make the tag a branch tag. See section Branches.
-d
Delete the tag instead of creating it. In general, tags (often the symbolic names of software distributions) should not be removed, but the `-d' option is available as a means to remove completely obsolete symbolic names if necessary (as might be the case for an Alpha release, or if you mistagged a module).

status--Display status information on checked out files

  • status [-lR] [-v] [files...]
  • Requires: working directory, repository.
  • Changes: nothing.

Display a brief report on the current status of files with respect to the source repository. For information on the basic output see section File status. For information on the Sticky tag and Sticky date output, see section Sticky tags. For information on the Sticky options output, see the `-k' option in section update options.

You can also use this command to determine the potential impact of a `cvs update' on your working source directory--but remember that things might change in the repository before you run update.

status options

These standard options are supported by status (see section Common command options, for a complete description of them):

-l
Local; run only in current working directory.
-R
Commit directories recursively. This is on by default.

There is one additional option:

-v
Verbose. In addition to the information normally displayed, print all symbolic tags, together with the numerical value of the revision or branch they refer to. For more information, see section Tags--Symbolic revisions

tag--Add a symbolic tag to checked out versions of files

  • tag [-lR] [-b] [-c] [-d] symbolic_tag [files...]
  • Requires: working directory, repository.
  • Changes: repository.
  • Synonym: freeze

Use this command to assign symbolic tags to the nearest repository versions to your working sources. The tags are applied immediately to the repository, as with rtag, but the versions are supplied implicitly by the CVS records of your working files' history rather than applied explicitly.

One use for tags is to record a snapshot of the current sources when the software freeze date of a project arrives. As bugs are fixed after the freeze date, only those changed sources that are to be part of the release need be re-tagged.

The symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribution. The checkout and update commands allow you to extract an exact copy of a tagged release at any time in the future, regardless of whether files have been changed, added, or removed since the release was tagged.

This command can also be used to delete a symbolic tag, or to create a branch. See the options section below.

If you attempt to use a tag name that already exists, CVS will complain and not overwrite that tag. Use the `-F' option to force the new tag value.

tag options

These standard options are supported by tag (see section Common command options, for a complete description of them):

-F
Overwrite an existing tag of the same name on a different revision. This option is new in CVS 1.4. The old behavior is matched by `cvs tag -F'.
-l
Local; run only in current working directory.
-R
Commit directories recursively. This is on by default.

Two special options are available:

-b
The -b option makes the tag a branch tag (see section Branches), allowing concurrent, isolated development. This is most useful for creating a patch to a previously released software distribution.
-c
The -c option checks that all files which are to be tagged are unmodified. This can be used to make sure that you can reconstruct the current file contents.
-d
Delete a tag. If you use `cvs tag -d symbolic_tag', the symbolic tag you specify is deleted instead of being added. Warning: Be very certain of your ground before you delete a tag; doing this permanently discards some historical information, which may later turn out to be valuable.

update--Bring work tree in sync with repository

  • update [-AdflPpR] [-d] [-r tag|-D date] files...
  • Requires: repository, working directory.
  • Changes: working directory.

After you've run checkout to create your private copy of source from the common repository, other developers will continue changing the central source. From time to time, when it is convenient in your development process, you can use the update command from within your working directory to reconcile your work with any revisions applied to the source repository since your last checkout or update.

update options

These standard options are available with update (see section Common command options, for a complete description of them):

-D date
Use the most recent revision no later than date. This option is sticky, and implies `-P'. See section Sticky tags, for more information on sticky tags/dates.
-f
Only useful with the `-D date' or `-r tag' flags. If no matching revision is found, retrieve the most recent revision (instead of ignoring the file).
-k kflag
Process RCS keywords according to kflag. See co(1). This option is sticky; future updates of this file in this working directory will use the same kflag. The status command can be viewed to see the sticky options. See section status--Display status information on checked out files.
-l
Local; run only in current working directory. See section Recursive behavior.
-P
Prune empty directories.
-p
Pipe files to the standard output.
-R
Operate recursively. This is on by default. See section Recursive behavior.
-r tag
Retrieve revision tag. This option is sticky, and implies `-P'. See section Sticky tags, for more information on sticky tags/dates.

These special options are also available with update.

-A
Reset any sticky tags, dates, or `-k' options. See section Sticky tags, for more information on sticky tags/dates.
-d
Create any directories that exist in the repository if they're missing from the working directory. Normally, update acts only on directories and files that were already enrolled in your working directory. This is useful for updating directories that were created in the repository since the initial checkout; but it has an unfortunate side effect. If you deliberately avoided certain directories in the repository when you created your working directory (either through use of a module name or by listing explicitly the files and directories you wanted on the command line), then updating with `-d' will create those directories, which may not be what you want.
-I name
Ignore files whose names match name (in your working directory) during the update. You can specify `-I' more than once on the command line to specify several files to ignore. Use `-I !' to avoid ignoring any files at all. See section Ignoring files via cvsignore, for other ways to make CVS ignore some files.
-Wspec
Specify file names that should be filtered during update. You can use this option repeatedly. spec can be a file name pattern of the same type that you can specify in the `.cvswrappers' file. See section The cvswrappers file.
-jrevision
With two `-j' options, merge changes from the revision specified with the first `-j' option to the revision specified with the second `j' option, into the working directory. With one `-j' option, merge changes from the ancestor revision to the revision specified with the `-j' option, into the working directory. The ancestor revision is the common ancestor of the revision which the working directory is based on, and the revision specified in the `-j' option. In addition, each -j option can contain an optional date specification which, when used with branches, can limit the chosen revision to one within a specific date. An optional date is specified by adding a colon (:) to the tag: `-jSymbolic_Tag:Date_Specifier'. See section Merging.

update output

update and checkout keep you informed of its progress by printing a line for each file, preceded by one character indicating the status of the file:

U file
The file was brought up to date with respect to the repository. This is done for any file that exists in the repository but not in your source, and for files that you haven't changed but are not the most recent versions available in the repository.
A file
The file has been added to your private copy of the sources, and will be added to the source repository when you run commit on the file. This is a reminder to you that the file needs to be committed.
R file
The file has been removed from your private copy of the sources, and will be removed from the source repository when you run commit on the file. This is a reminder to you that the file needs to be committed.
M file
The file is modified in your working directory. `M' can indicate one of two states for a file you're working on: either there were no modifications to the same file in the repository, so that your file remains as you last saw it; or there were modifications in the repository as well as in your copy, but they were merged successfully, without conflict, in your working directory. CVS will print some messages if it merges your work, and a backup copy of your working file (as it looked before you ran update) will be made. The exact name of that file is printed while update runs.
C file
A conflict was detected while trying to merge your changes to file with changes from the source repository. file (the copy in your working directory) is now the output of the rcsmerge(1) command on the two revisions; an unmodified copy of your file is also in your working directory, with the name `.#file.revision' where revision is the RCS revision that your modified file started from. Resolve the conflict as described in section Conflicts example (Note that some systems automatically purge files that begin with `.#' if they have not been accessed for a few days. If you intend to keep a copy of your original file, it is a very good idea to rename it.) Under VMS, the file name starts with `__' rather than `.#'.
? file
file is in your working directory, but does not correspond to anything in the source repository, and is not in the list of files for CVS to ignore (see the description of the `-I' option, and see section Ignoring files via cvsignore). Note that no warning message like this is printed for spurious directories that CVS encounters. The directory, and all its contents, are silently ignored.

update examples

The following line will display all files which are not up-to-date without actually change anything in your working directory. It can be used to check what has been going on with the project.

$ cvs -n -q update

Reference manual for the Administrative files

Inside the repository, in the directory `$CVSROOT/CVSROOT', there are a number of supportive files for CVS. You can use CVS in a limited fashion without any of them, but if they are set up properly they can help make life easier. For a discussion of how to edit them, See section The administrative files.

The most important of these files is the `modules' file, which defines the modules inside the repository.

The modules file

The `modules' file records your definitions of names for collections of source code. CVS will use these definitions if you use CVS to update the modules file (use normal commands like add, commit, etc).

The `modules' file may contain blank lines and comments (lines beginning with `#') as well as module definitions. Long lines can be continued on the next line by specifying a backslash (`\') as the last character on the line.

A module definition is a single line of the `modules' file, in either of two formats. In both cases, mname represents the symbolic module name, and the remainder of the line is its definition.

mname -a aliases...
This represents the simplest way of defining a module mname. The `-a' flags the definition as a simple alias: CVS will treat any use of mname (as a command argument) as if the list of names aliases had been specified instead. aliases may contain either other module names or paths. When you use paths in aliases, checkout creates all intermediate directories in the working directory, just as if the path had been specified explicitly in the CVS arguments.
mname [ options ] dir [ files... ] [ &module... ]
In the simplest case, this form of module definition reduces to `mname dir'. This defines all the files in directory dir as module mname. dir is a relative path (from $CVSROOT) to a directory of source in the source repository. In this case, on checkout, a single directory called mname is created as a working directory; no intermediate directory levels are used by default, even if dir was a path involving several directory levels. By explicitly specifying files in the module definition after dir, you can select particular files from directory dir. The sample definition for `modules' is an example of a module defined with a single file from a particular directory. Here is another example:
m4test  unsupported/gnu/m4 foreach.m4 forloop.m4
With this definition, executing `cvs checkout m4test' will create a single working directory `m4test' containing the two files listed, which both come from a common directory several levels deep in the CVS source repository. A module definition can refer to other modules by including `&module' in its definition. checkout creates a subdirectory for each such module, in your working directory.
-d name
Name the working directory something other than the module name.
-e prog
Specify a program prog to run whenever files in a module are exported. prog runs with a single argument, the module name.
-i prog
Specify a program prog to run whenever files in a module are committed. prog runs with a single argument, the full pathname of the affected directory in a source repository. The `commitinfo', `loginfo', and `editinfo' files provide other ways to call a program on commit.
-o prog
Specify a program prog to run whenever files in a module are checked out. prog runs with a single argument, the module name.
-s status
Assign a status to the module. When the module file is printed with `cvs checkout -s' the modules are sorted according to primarily module status, and secondarily according to the module name. This option has no other meaning. You can use this option for several things besides status: for instance, list the person that is responsible for this module.
-t prog
Specify a program prog to run whenever files in a module are tagged with rtag. prog runs with two arguments: the module name and the symbolic tag specified to rtag. There is no way to specify a program to run when tag is executed.
-u prog
Specify a program prog to run whenever `cvs update' is executed from the top-level directory of the checked-out module. prog runs with a single argument, the full path to the source repository for this module.

The cvswrappers file

Wrappers allow you to set a hook which transforms files on their way in and out of CVS. Most or all of the wrappers features do not work with client/server CVS.

The file `cvswrappers' defines the script that will be run on a file when its name matches a regular expresion. There are two scripts that can be run on a file or directory. One script is executed on the file/directory before being checked into the repository (this is denoted with the -t flag) and the other when the file is checked out of the repository (this is denoted with the -f flag)

The `cvswrappers' also has a `-m' option to specify the merge methodology that should be used when the file is updated. MERGE means the usual CVS behavior: try to merge the files (this generally will not work for binary files). COPY means that cvs update will merely copy one version over the other, and require the user using mechanisms outside CVS, to insert any necessary changes. The `-m' wrapper option only affects behavior when merging is done on update; it does not affect how files are stored. See See section Handling binary files, for more on binary files.

The basic format of the file `cvswrappers' is:

wildcard     [option value][option value]...

where option is one of
-f           from cvs filter         value: path to filter
-t           to cvs filter           value: path to filter
-m           update methodology      value: MERGE or COPY
-k           keyword expansion       value: expansion mode

and value is a single-quote delimited value.

*.nib    -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
*.c      -t 'indent %s %s'

The above example of a `cvswrappers' file states that all files/directories that end with a .nib should be filtered with the `wrap' program before checking the file into the repository. The file should be filtered though the `unwrap' program when the file is checked out of the repository. The `cvswrappers' file also states that a COPY methodology should be used when updating the files in the repository (that is no merging should be performed).

The last example line says that all files that end with a *.c should be filtered with `indent' before being checked into the repository. Unlike the previous example no filtering of the *.c file is done when it is checked out of the repository. The -t filter is called with two arguments, the first is the name of the file/directory to filter and the second is the pathname to where the resulting filtered file should be placed.

The -f filter is called with one argument, which is the name of the file to filter from. The end result of this filter will be a file in the users directory that they can work on as they normally would.

For another example, the following command imports a directory, treating files whose name ends in `.exe' as binary:

cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag

The commit support files

The `-i' flag in the `modules' file can be used to run a certain program whenever files are committed (see section The modules file). The files described in this section provide other, more flexible, ways to run programs whenever something is committed.

There are three kind of programs that can be run on commit. They are specified in files in the repository, as described below. The following table summarizes the file names and the purpose of the corresponding programs.

`commitinfo'
The program is responsible for checking that the commit is allowed. If it exits with a non-zero exit status the commit will be aborted.
`editinfo'
The specified program is used to edit the log message, and possibly verify that it contains all required fields. This is most useful in combination with the `rcsinfo' file, which can hold a log message template (see section Rcsinfo).
`loginfo'
The specified program is called when the commit is complete. It receives the log message and some additional information and can store the log message in a file, or mail it to appropriate persons, or maybe post it to a local newsgroup, or... Your imagination is the limit!

The common syntax

The four files `commitinfo', `loginfo', `rcsinfo' and `editinfo' all have a common format. The purpose of the files are described later on. The common syntax is described here.

Each line contains the following:

  • A regular expression
  • A whitespace separator--one or more spaces and/or tabs.
  • A file name or command-line template.

Blank lines are ignored. Lines that start with the character `#' are treated as comments. Long lines unfortunately can not be broken in two parts in any way.

The first regular expression that matches the current directory name in the repository is used. The rest of the line is used as a file name or command-line as appropriate.

Commitinfo

The `commitinfo' file defines programs to execute whenever `cvs commit' is about to execute. These programs are used for pre-commit checking to verify that the modified, added and removed files are really ready to be committed. This could be used, for instance, to verify that the changed files conform to to your site's standards for coding practice.

As mentioned earlier, each line in the `commitinfo' file consists of a regular expression and a command-line template. The template can include a program name and any number of arguments you wish to supply to it. The full path to the current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).

The first line with a regular expression matching the relative path to the module will be used. If the command returns a non-zero exit status the commit will be aborted.

If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

All occurances of the name `ALL' appearing as a regular expression are used in addition to the first matching regular expression or the name `DEFAULT'.

Note: when CVS is accessing a remote repository, `commitinfo' will be run on the remote (i.e., server) side, not the client side (see section Remote repositories).

Editinfo

If you want to make sure that all log messages look the same way, you can use the `editinfo' file to specify a program that is used to edit the log message. This program could be a custom-made editor that always enforces a certain style of the log message, or maybe a simple shell script that calls an editor, and checks that the entered message contains the required fields.

If no matching line is found in the `editinfo' file, the editor specified in the environment variable $CVSEDITOR is used instead. If that variable is not set, then the environment variable $EDITOR is used instead. If that variable is not set a precompiled default, normally vi, will be used.

The `editinfo' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template.

Each line in the `editinfo' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

One thing that should be noted is that the `ALL' keyword is not supported. If more than one matching line is found, the first one is used. This can be useful for specifying a default edit script in a module, and then overriding it in a subdirectory.

If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

If the edit script exits with a non-zero exit status, the commit is aborted.

Note: when CVS is accessing a remote repository, or when the `-m' or `-F' options to cvs commit are used, `editinfo' will not be consulted. There is no good workaround for this.

Editinfo example

The following is a little silly example of a `editinfo' file, together with the corresponding `rcsinfo' file, the log message template and an editor script. We begin with the log message template. We want to always record a bug-id number on the first line of the log message. The rest of log message is free text. The following template is found in the file `/usr/cvssupport/tc.template'.

BugId:

The script `/usr/cvssupport/bugid.edit' is used to edit the log message.

#!/bin/sh
#
#       bugid.edit filename
#
#  Call $EDITOR on FILENAME, and verify that the
#  resulting file contains a valid bugid on the first
#  line.
if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
$CVSEDITOR $1
until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
do  echo -n  "No BugId found.  Edit again? ([y]/n)"
    read ans
    case ${ans} in
        n*) exit 1;;
    esac
    $CVSEDITOR $1
done

The `editinfo' file contains this line:

^tc     /usr/cvssupport/bugid.edit

The `rcsinfo' file contains this line:

^tc     /usr/cvssupport/tc.template

Loginfo

The `loginfo' file is used to control where `cvs commit' log information is sent. The first entry on a line is a regular expression which is tested against the directory that the change is being made to, relative to the $CVSROOT. If a match is found, then the remainder of the line is a filter program that should expect log information on its standard input.

The filter program may use one and only one % modifier (a la printf). If `%s' is specified in the filter program, a brief title is included (enclosed in single quotes) showing the modified file names.

If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

All occurances of the name `ALL' appearing as a regular expression are used in addition to the first matching regular expression or `DEFAULT'.

The first matching regular expression is used.

See section The commit support files, for a description of the syntax of the `loginfo' file.

Note: when CVS is accessing a remote repository, `loginfo' will be run on the remote (i.e., server) side, not the client side (see section Remote repositories).

Loginfo example

The following `loginfo' file, together with the tiny shell-script below, appends all log messages to the file `$CVSROOT/CVSROOT/commitlog', and any commits to the administrative files (inside the `CVSROOT' directory) are also logged in `/usr/adm/cvsroot-log'.

ALL             /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog
^CVSROOT        /usr/local/bin/cvs-log /usr/adm/cvsroot-log

The shell-script `/usr/local/bin/cvs-log' looks like this:

#!/bin/sh
(echo "-----------------------------------------------------------------";
 echo -n $USER"  ";
 date;
 echo;
 sed '1s+'${CVSROOT}'++') >> $1

Keeping a checked out copy

It is often useful to maintain a directory tree which contains files which correspond to the latest version in the repository. For example, other developers might want to refer to the latest sources without having to check them out, or you might be maintaining a web site with CVS and want every checkin to cause the files used by the web server to be updated.

The way to do this is by having loginfo invoke cvs update. Doing so in the naive way will cause a problem with locks, so the cvs update must be run in the background. Here is an example (this should all be on one line):

^cyclic-pages		(date; cat; (sleep 2; cd /u/www/local-docs;
 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1

This will cause checkins to repository directories starting with cyclic-pages to update the checked out tree in `/u/www/local-docs'.

Rcsinfo

The `rcsinfo' file can be used to specify a form to edit when filling out the commit log. The `rcsinfo' file has a syntax similar to the `editinfo', `commitinfo' and `loginfo' files. See section The common syntax. Unlike the other files the second part is not a command-line template. Instead, the part after the regular expression should be a full pathname to a file containing the log message template.

If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

All occurances of the name `ALL' appearing as a regular expression are used in addition to the first matching regular expression or `DEFAULT'.

The log message template will be used as a default log message. If you specify a log message with `cvs commit -m message' or `cvs commit -f file' that log message will override the template.

See section Editinfo example, for an example `rcsinfo' file.

When CVS is accessing a remote repository, the contents of `rcsinfo' at the time a directory is first checked out will specify a template which does not then change. If you edit `rcsinfo' or its templates, you may need to check out a new working directory.

Ignoring files via cvsignore

There are certain file names that frequently occur inside your working copy, but that you don't want to put under CVS control. Examples are all the object files that you get while you compile your sources. Normally, when you run `cvs update', it prints a line for each file it encounters that it doesn't know about (see section update output).

CVS has a list of files (or sh(1) file name patterns) that it should ignore while running update, import and release. This list is constructed in the following way.

  • The list is initialized to include certain file name patterns: names associated with CVS administration, or with other common source control systems; common names for patch files, object files, archive files, and editor backup files; and other names that are usually artifacts of assorted utilities. Currently, the default list of ignored file name patterns is:
        RCS     SCCS    CVS     CVS.adm
    RCSLOG  cvslog.*
    tags    TAGS
    .make.state     .nse_depinfo
    *~      #*      .#*     ,*      _$*     *$
    *.old   *.bak   *.BAK   *.orig  *.rej   .del-*
    *.a     *.olb   *.o     *.obj   *.so    *.exe
    *.Z     *.elc   *.ln
    core
  • The per-repository list in `$CVSROOT/CVSROOT/cvsignore' is appended to the list, if that file exists.
  • The per-user list in `.cvsignore' in your home directory is appended to the list, if it exists.
  • Any entries in the environment variable $CVSIGNORE is appended to the list.
  • Any `-I' options given to CVS is appended.
  • As CVS traverses through your directories, the contents of any `.cvsignore' will be appended to the list. The patterns found in `.cvsignore' are only valid for the directory that contains them, not for any sub-directories.

In any of the 5 places listed above, a single exclamation mark (`!') clears the ignore list. This can be used if you want to store any file which normally is ignored by CVS.

The history file

The file `$CVSROOT/CVSROOT/history' is used to log information for the history command (see section history--Show status of files and users). This file must be created to turn on logging. This is done automatically if the cvs init command is used to set up the repository (see section Creating a repository).

The file format of the `history' file is documented only in comments in the CVS source code, but generally programs should use the cvs history command to access it anyway, in case the format changes with future releases of CVS.

Expansions in administrative files

Sometimes in writing an administrative file, you might want the file to be able to know various things based on environment CVS is running in. There are several mechanisms to do that.

To find the home directory of the user running CVS (from the HOME environment variable), use `~' followed by `/' or the end of the line. Likewise for the home directory of user, use `~user'. These variables are expanded on the server machine, and don't get any resonable expansion if pserver (see section Direct connection with password authentication) is in used; therefore user variables (see below) may be a better choice to customize behavior based on the user running CVS.

One may want to know about various pieces of information internal to CVS. A CVS internal variable has the syntax ${variable}, where variable starts with a letter and consists of alphanumberic characters and `_'. If the character following variable is a non-alphanumeric character other than `_', the `{' and `}' can be omitted. The CVS internal variables are:

CVSROOT
This is the value of the CVS root in use. See section The Repository, for a description of the various ways to specify this.
RCSBIN
This is the value CVS is using for where to find RCS binaries. See section Global options, for a description of how to specify this.
CVSEDITOR
VISUAL
EDITOR
These all expand to the same value, which is the editor that CVS is using. See section Global options, for how to specify this.
USER
Username of the user running CVS (on the CVS server machine).

If you want to pass a value to the administrative files which the user that is running CVS can specify, use a user variable. To expand a user variable, the administrative file contains ${=variable}. To set a user variable, specify the global option `-s' to CVS, with argument variable=value. It may be particularly useful to specify this option via `.cvsrc' (see section Default options and the ~/.cvsrc file).

For example, if you want the administrative file to refer to a test directory you might create a user variable TESTDIR. Then if CVS is invoked as cvs -s TESTDIR=/work/local/tests, and the administrative file contains sh ${=TESTDIR}/runtests, then that string is expanded to sh /work/local/tests/runtests.

All other strings containing `$' are reserved; there is no way to quote a `$' character so that `$' represents itself.

All environment variables which affect CVS

This is a complete list of all environment variables that affect CVS.

$CVSIGNORE
A whitespace-separated list of file name patterns that CVS should ignore. See section Ignoring files via cvsignore.
$CVSWRAPPERS
A whitespace-separated list of file name patterns that CVS should treat as wrappers. See section The cvswrappers file.
$CVSREAD
If this is set, checkout and update will try hard to make the files in your working directory read-only. When this is not set, the default behavior is to permit modification of your working files.
$CVSROOT
Should contain the full pathname to the root of the CVS source repository (where the RCS history files are kept). This information must be available to CVS for most commands to execute; if $CVSROOT is not set, or if you wish to override it for one invocation, you can supply it on the command line: `cvs -d cvsroot cvs_command...' Once you have checked out a working directory, CVS stores the appropriate root (in the file `CVS/Root'), so normally you only need to worry about this when initially checking out a working directory.
$EDITOR
$CVSEDITOR
Specifies the program to use for recording log messages during commit. If not set, the default is `/usr/ucb/vi'. $CVSEDITOR overrides $EDITOR. $CVSEDITOR does not exist in CVS 1.3, but the next release will probably include it.
$PATH
If $RCSBIN is not set, and no path is compiled into CVS, it will use $PATH to try to find all programs it uses.
$RCSBIN
This is the value CVS is using for where to find RCS binaries. See section Global options, for a description of how to specify this. If not set, a compiled-in value is used, or your $PATH is searched.
$HOME
$HOMEPATH
Used to locate the directory where the `.cvsrc' file is searched ($HOMEPATH is used for Windows-NT). see section Default options and the ~/.cvsrc file
$CVS_RSH
Specifies the external program which CVS connects with, when :ext: access method is specified. see section Connecting with rsh.
$CVS_SERVER
Used in client-server mode when accessing a remote repository using RSH. It specifies the name of the program to start on the server side when accessing a remote repository using RSH. The default value is cvs. see section Connecting with rsh
$CVS_PASSFILE
Used in client-server mode when accessing the cvs login server. Default value is `$HOME/.cvspass'. see section Using the client with password authentication
$CVS_PASSWORD
Used in client-server mode when accessing the cvs login server. see section Using the client with password authentication
$CVS_CLIENT_PORT
Used in client-server mode when accessing the server via Kerberos. see section Direct connection with kerberos
$CVS_RCMD_PORT
Used in client-server mode. If set, specifies the port number to be used when accessing the RCMD demon on the server side. (Currently not used for Unix clients).
$CVS_CLIENT_LOG
Used for debugging only in client-server mode. If set, everything send to the server is logged into `$CVS_CLIENT_LOG.in' and everything send from the server is logged into `$CVS_CLIENT_LOG.out'.
$CVS_SERVER_SLEEP
Used only for debugging the server side in client-server mode. If set, delays the start of the server child process the the specified amount of seconds so that you can attach to it with a debugger.
$CVS_IGNORE_REMOTE_ROOT
(What is the purpose of this variable?)
$COMSPEC
Used under OS/2 only. It specifies the name of the command interpreter and defaults to CMD.EXE.
$TMPDIR
$TMP
$TEMP
Directory in which temporary files are located. Those parts of CVS which are implemented using RCS inspect the above variables in the order they appear above and the first value found is taken; if none of them are set, a host-dependent default is used, typically `/tmp'. The CVS server uses TMPDIR. See section Global options, for a description of how to specify this. Some parts of CVS will always use `/tmp' (via the tmpnam function provided by the system). On Windows NT, TMP is used (via the _tempnam function provided by the system). The patch program which is used by the CVS client uses TMPDIR, and if it is not set, uses `/tmp' (at least with GNU patch 2.1).

CVS invokes RCS to perform certain operations. The following environment variables affect RCS. Note that if you are using the client/server CVS, these variables need to be set on the server side (which may or not may be possible depending on how you are connecting). There is probably not any need to set any of them, however.

$LOGNAME
$USER
If set, they affect who RCS thinks you are. If you have trouble checking in files it might be because your login name differs from the setting of e.g. $LOGNAME.
$RCSINIT
Options prepended to the argument list, separated by spaces. A backslash escapes spaces within an option. The $RCSINIT options are prepended to the argument lists of most RCS commands.

Troubleshooting

Magic branch numbers

Externally, branch numbers consist of an odd number of dot-separated decimal integers. See section Revision numbers. That is not the whole truth, however. For efficiency reasons CVS sometimes inserts an extra 0 in the second rightmost position (1.2.3 becomes 1.2.0.3, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so on).

CVS does a pretty good job at hiding these so called magic branches, but in a few places the hiding is incomplete:

  • The magic branch number appears in the output from cvs log.
  • You cannot specify a symbolic branch name to cvs admin.

You can use the admin command to reassign a symbolic name to a branch the way RCS expects it to be. If R4patches is assigned to the branch 1.4.2 (magic branch number 1.4.0.2) in file `numbers.c' you can do this:

$ cvs admin -NR4patches:1.4.2 numbers.c

It only works if at least one revision is already committed on the branch. Be very careful so that you do not assign the tag to the wrong number. (There is no way to see how the tag was assigned yesterday).

GNU GENERAL PUBLIC LICENSE

Index

Jump to: - - . - / - : - < - = - > - _ - a - b - c - d - e - f - g - h - i - j - k - l - m - n - o - p - r - s - t - u - v - w - z

-

  • -j (merging branches)
  • -k (RCS kflags)

    • .

  • .# files
  • .bashrc, setting CVSROOT in
  • .cshrc, setting CVSROOT in
  • .cvsrc file
  • .profile, setting CVSROOT in
  • .tcshrc, setting CVSROOT in

    • /

  • /usr/local/cvsroot, as example repository

    • :

  • :ext:
  • :kserver:
  • :local:
  • :pserver:
  • :server:

    • <

  • <<<<<<<

    • =

  • =======

    • >

  • >>>>>>>

    • _

  • __ files (VMS)

    • a

  • A sample session
  • abandoning work
  • About this manual
  • add (subcommand)
  • Adding a tag
  • Adding files
  • Admin (subcommand)
  • Administrative files (intro)
  • Administrative files (reference)
  • Administrative files, editing them
  • ALL in commitinfo
  • annotate (subcommand)
  • Atomic transactions, lack of
  • authenticated client, using
  • authenticating server, setting up
  • Author keyword
  • Automatically ignored files
  • Avoiding editor invocation

    • b

  • Binary files
  • Branch merge example
  • Branch number
  • Branch numbers
  • Branch, creating a
  • Branch, vendor-
  • Branches
  • Branches motivation
  • Branches, copying changes between
  • Branches, sticky
  • Bringing a file up to date
  • Bugs, known in this manual
  • Bugs, reporting (manual)

    • c

  • Changes, copying between branches
  • Changing a log message
  • checked out copy, keeping
  • Checkin program
  • Checking commits
  • Checking out source
  • Checkout (subcommand)
  • Checkout program
  • checkout, as term for getting ready to edit
  • Checkout, example
  • choosing, reserved or unreserved checkouts
  • Cleaning up
  • Client/Server Operation
  • Co (subcommand)
  • Command reference
  • Command structure
  • Comment leader
  • Commit (subcommand)
  • Commit files
  • Commit, when to
  • Commitinfo
  • Committing changes
  • Common options
  • Common syntax of info files
  • COMSPEC
  • Conflict markers
  • Conflict resolution
  • Conflicts (merge example)
  • Contributors (CVS program)
  • Contributors (manual)
  • Copying changes
  • Correcting a log message
  • Creating a branch
  • Creating a project
  • Creating a repository
  • Credits (CVS program)
  • Credits (manual)
  • CVS 1.6, and watches
  • CVS command structure
  • CVS passwd file
  • CVS, history of
  • CVS, introduction to
  • CVS_CLIENT_LOG
  • CVS_CLIENT_PORT
  • CVS_IGNORE_REMOTE_ROOT
  • CVS_PASSFILE, environment variable
  • CVS_PASSWORD, environment variable
  • CVS_RCMD_PORT
  • CVS_RSH
  • CVS_SERVER
  • CVS_SERVER_SLEEP
  • CVSEDITOR
  • CVSEDITOR, environment variable
  • CVSIGNORE
  • cvsignore (admin file), global
  • CVSREAD
  • CVSREAD, overriding
  • CVSROOT
  • cvsroot
  • CVSROOT (file)
  • CVSROOT, environment variable
  • CVSROOT, module name
  • CVSROOT, multiple repositories
  • CVSROOT, overriding
  • CVSUMASK
  • CVSWRAPPERS
  • cvswrappers (admin file)
  • CVSWRAPPERS, environment variable

    • d

  • Date keyword
  • Dates
  • Decimal revision number
  • DEFAULT in commitinfo
  • DEFAULT in editinfo
  • Defining a module
  • Defining modules (intro)
  • Defining modules (reference manual)
  • Deleting files
  • Deleting revisions
  • Deleting sticky tags
  • Descending directories
  • Diff
  • Diff (subcommand)
  • Differences, merging
  • Directories, moving
  • Directory, descending
  • Disjoint repositories
  • Distributing log messages
  • driver.c (merge example)

    • e

  • edit (subcommand)
  • editinfo (admin file)
  • Editing administrative files
  • Editing the modules file
  • EDITOR
  • Editor, avoiding invocation of
  • EDITOR, environment variable
  • EDITOR, overriding
  • Editor, specifying per module
  • editors (subcommand)
  • emerge
  • Environment variables
  • Errors, reporting (manual)
  • Example of a work-session
  • Example of merge
  • Example, branch merge
  • Export (subcommand)
  • Export program

    • f

  • Fetching source
  • File locking
  • File permissions
  • File status
  • Files, moving
  • Files, reference manual
  • Fixing a log message
  • Forcing a tag match
  • Form for log message
  • Format of CVS commands

    • g

  • Getting started
  • Getting the source
  • Global cvsignore
  • Global options
  • Group

    • h

  • Header keyword
  • History (subcommand)
  • History browsing
  • History file
  • History files
  • History of CVS
  • HOME
  • HOMEPATH

    • i

  • Id keyword
  • Ident (shell command)
  • Identifying files
  • Ignored files
  • Ignoring files
  • Import (subcommand)
  • Importing files
  • Importing files, from other version control systesm
  • Importing modules
  • Index
  • Info files (syntax)
  • Informing others
  • init (subcommand)
  • Introduction to CVS
  • Invoking CVS
  • Isolation

    • j

  • Join

    • k

  • keeping a checked out copy
  • kerberos
  • Keyword expansion
  • Keyword substitution
  • Kflag
  • kinit
  • Known bugs in this manual

    • l

  • Layout of repository
  • Left-hand options
  • Linear development
  • List, mailing list
  • Locally Added
  • Locally Modified
  • Locally Removed
  • Locker keyword
  • Locking files
  • locks, cvs
  • Log (subcommand)
  • Log information, saving
  • Log keyword
  • Log keyword, selecting comment leader
  • Log message entry
  • Log message template
  • Log message, correcting
  • Log messages
  • Log messages, editing
  • Login (subcommand)
  • loginfo (admin file)
  • LOGNAME

    • m

  • Mail, automatic mail on commit
  • Mailing list
  • Mailing log messages
  • Main trunk (intro)
  • Main trunk and branches
  • Many repositories
  • Markers, conflict
  • Merge, an example
  • Merge, branch example
  • Merging
  • Merging a branch
  • Merging a file
  • Merging two revisions
  • Modifications, copying between branches
  • Module status
  • Module, defining
  • Modules (admin file)
  • Modules (intro)
  • Modules file
  • Modules file, changing
  • Motivation for branches
  • Moving directories
  • Moving files
  • Multiple developers
  • Multiple repositories

    • n

  • Name keyword
  • Name, symbolic (tag)
  • Needs Checkout
  • Needs Merge
  • Needs Patch
  • Newsgroups
  • notify (admin file)
  • Nroff (selecting comment leader)
  • Number, branch
  • Number, revision-

    • o

  • option defaults
  • Options, global
  • Outdating revisions
  • Overlap
  • Overriding CVSREAD
  • Overriding CVSROOT
  • Overriding EDITOR
  • Overriding RCSBIN
  • Overriding TMPDIR

    • p

  • Parallel repositories
  • passwd (admin file)
  • password client, using
  • password server, setting up
  • PATH
  • Per-module editor
  • Policy
  • Precommit checking
  • Preface
  • Pserver (subcommand)

    • r

  • RCS history files
  • RCS keywords
  • RCS revision numbers
  • RCS, importing files from
  • RCS-style locking
  • RCSBIN
  • RCSBIN, overriding
  • RCSfile keyword
  • rcsinfo (admin file)
  • RCSINIT
  • Rdiff (subcommand)
  • read-only files, and -r
  • read-only files, and CVSREAD
  • read-only files, and watches
  • read-only files, in repository
  • Read-only mode
  • Recursive (directory descending)
  • Reference manual (files)
  • Reference manual for variables
  • Reference, commands
  • Release (subcommand)
  • Releases, revisions and versions
  • Releasing your working copy
  • Remote repositories
  • Remove (subcommand)
  • Removing a change
  • Removing files
  • Removing your working copy
  • Renaming directories
  • Renaming files
  • Replacing a log message
  • Reporting bugs (manual)
  • Repositories, multiple
  • Repositories, remote
  • Repository (intro)
  • Repository, example
  • Repository, how data is stored
  • Repository, setting up
  • reserved checkouts
  • Resetting sticky tags
  • Resolving a conflict
  • Restoring old version of removed file
  • Resurrecting old version of dead file
  • Retrieving an old revision using tags
  • reverting to repository version
  • Revision keyword
  • Revision management
  • Revision numbers
  • Revision tree
  • Revision tree, making branches
  • Revisions, merging differences between
  • Revisions, versions and releases
  • Right-hand options
  • rsh
  • Rtag (subcommand)
  • rtag, creating a branch using

    • s

  • Saving space
  • SCCS, importing files from
  • Security
  • setgid
  • Setting up a repository
  • setuid
  • Signum Support
  • Source keyword
  • Source, getting CVS source
  • Source, getting from CVS
  • Specifying dates
  • Spreading information
  • Starting a project with CVS
  • State keyword
  • Status (subcommand)
  • Status of a file
  • Status of a module
  • sticky date
  • Sticky tags
  • Sticky tags, resetting
  • Storing log messages
  • Structure
  • Subdirectories
  • Support, getting CVS support
  • Symbolic name (tag)
  • Syntax of info files

    • t

  • Tag (subcommand)
  • Tag program
  • tag, command, introduction
  • tag, example
  • Tag, retrieving old revisions
  • Tag, symbolic name
  • taginfo
  • Tags
  • Tags, sticky
  • tc, Trivial Compiler (example)
  • Team of developers
  • TEMP
  • Template for log message
  • temporary files, location of
  • Third-party sources
  • Time
  • timezone, in input
  • timezone, in output
  • TMP
  • TMPDIR
  • TMPDIR, overriding
  • Trace
  • Traceability
  • Tracking sources
  • Transactions, atomic, lack of
  • Trivial Compiler (example)
  • Typical repository

    • u

  • umask, for repository files
  • Undoing a change
  • unedit (subcommand)
  • Unknown
  • unreserved checkouts
  • Unresolved Conflict
  • Up-to-date
  • Update (subcommand)
  • Update program
  • update, introduction
  • Updating a file
  • USER
  • users (admin file)

    • v

  • Vendor
  • Vendor branch
  • Versions, revisions and releases
  • Viewing differences

    • w

  • watch add (subcommand)
  • watch off (subcommand)
  • watch on (subcommand)
  • watch remove (subcommand)
  • watchers (subcommand)
  • Watches
  • Wdiff (import example)
  • What (shell command)
  • What branches are good for
  • What is CVS?
  • When to commit
  • Work-session, example of
  • Working copy
  • Working copy, removing
  • Wrappers

    • z

  • zone, time, in input
  • zone, time, in output

    • This document was generated on 7 November 1998 using the texi2html translator version 1.52.


dc, an arbitrary precision calculator

by Ken Pizzini
original manual by Richard Stallman

Table of Contents

  • Introduction
  • Invocation
  • Printing Commands
  • Arithmetic
  • Stack Control
  • Registers
  • Parameters
  • Strings
  • Status Inquiry
  • Miscellaneous
  • Reporting bugs

Introduction

DC is a reverse-polish desk calculator which supports unlimited precision arithmetic. It also allows you to define and call macros. Normally DC reads from the standard input; if any command arguments are given to it, they are filenames, and DC reads and executes the contents of the files instead of reading from standard input. All normal output is to standard output; all error messages are written to standard error.

To exit, use `q'. C-c does not exit; it is used to abort macros that are looping, etc. (Currently this is not true; C-c does exit.)

A reverse-polish calculator stores numbers on a stack. Entering a number pushes it on the stack. Arithmetic operations pop arguments off the stack and push the results.

To enter a number in DC, type the digits, with an optional decimal point. Exponential notation is not supported. To enter a negative number, begin the number with `_'. `-' cannot be used for this, as it is a binary operator for subtraction instead. To enter two numbers in succession, separate them with spaces or newlines. These have no meaning as commands.

Invocation

DC may be invoked with the following command-line options:

`-e expr'
`--expression=expr'
Evaluate expr as DC commands.
`-f file'
`--file=file'
Read and evaluate DC commands from file.
`-h'
`--help'
Print a usage message summarizing the command-line options, then exit.
`-V'
`--version'
Print the version information for this program, then exit.

If any command-line parameters remain after processing the options, these parameters are interpreted as additional files whose contents are read and evaluated. A file name of - refers to the standard input stream. If no -e option was specified, and no files were specified, then the standard input will be read for commands to evaluate.

Printing Commands

`p'
Prints the value on the top of the stack, without altering the stack. A newline is printed after the value.
`n'
Prints the value on the top of the stack, popping it off, and does not print a newline after. (This command is a GNU extension.)
`P'
Pops off the value on top of the stack. If it it a string, it is simply printed without a trailing newline. Otherwise it is a number, and the integer portion of its absolute value is printed out as a "base (UCHAR_MAX+1)" byte stream. Assuming that (UCHAR_MAX+1) is 256 (as it is on most machines with 8-bit bytes), the sequence KSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk could also accomplish this function, except for the side-effect of clobbering the x register. (Details of the behavior with a number are a GNU extension.)
`f'
Prints the entire contents of the stack without altering anything. This is a good command to use if you are lost or want to figure out what the effect of some command has been.

Arithmetic

`+'
Pops two values off the stack, adds them, and pushes the result. The precision of the result is determined only by the values of the arguments, and is enough to be exact.
`-'
Pops two values, subtracts the first one popped from the second one popped, and pushes the result.
`*'
Pops two values, multiplies them, and pushes the result. The number of fraction digits in the result is the largest of the precision value, the number of fraction digits in the multiplier, or the number of fraction digits in the multiplicand; but in no event exceeding the number of digits required for an exact result.
`/'
Pops two values, divides the second one popped from the first one popped, and pushes the result. The number of fraction digits is specified by the precision value.
`%'
Pops two values, computes the remainder of the division that the `/' command would do, and pushes that. The value computed is the same as that computed by the sequence Sd dld/ Ld*- .
`~'
Pops two values, divides the second one popped from the first one popped. The quotient is pushed first, and the remainder is pushed next. The number of fraction digits used in the division is specified by the precision value. (The sequence SdSn lnld/ LnLd% could also accomplish this function, with slightly different error checking.) (This command is a GNU extension.)
`^'
Pops two values and exponentiates, using the first value popped as the exponent and the second popped as the base. The fraction part of the exponent is ignored. The precision value specifies the number of fraction digits in the result.
`|'
Pops three values and computes a modular exponentiation. The first value popped is used as the reduction modulus; this value must be a non-zero number, and the result may not be accurate if the modulus is not an integer. The second popped is used as the exponent; this value must be a non-negative number, and any fractional part of this exponent will be ignored. The third value popped is the base which gets exponentiated, which should be an integer. For small integers this is like the sequence Sm^Lm%, but, unlike ^, this command will work with arbritrarily large exponents. (This command is a GNU extension.)
`v'
Pops one value, computes its square root, and pushes that. The precision value specifies the number of fraction digits in the result.

Most arithmetic operations are affected by the precision value, which you can set with the `k' command. The default precision value is zero, which means that all arithmetic except for addition and subtraction produces integer results.

Stack Control

`c'
Clears the stack, rendering it empty.
`d'
Duplicates the value on the top of the stack, pushing another copy of it. Thus, `4d*p' computes 4 squared and prints it.
`r'
Reverses the order of (swaps) the top two values on the stack. (This command is a GNU extension.)

Registers

DC provides at least 256 memory registers, each named by a single character. You can store a number in a register and retrieve it later.

`sr'
Pop the value off the top of the stack and store it into register r.
`lr'
Copy the value in register r, and push it onto the stack. This does not alter the contents of r. Each register also contains its own stack. The current register value is the top of the register's stack.
`Sr'
Pop the value off the top of the (main) stack and push it onto the stack of register r. The previous value of the register becomes inaccessible.
`Lr'
Pop the value off the top of register r's stack and push it onto the main stack. The previous value in register r's stack, if any, is now accessible via the `lr' command.

Parameters

DC has three parameters that control its operation: the precision, the input radix, and the output radix. The precision specifies the number of fraction digits to keep in the result of most arithmetic operations. The input radix controls the interpretation of numbers typed in; all numbers typed in use this radix. The output radix is used for printing numbers.

The input and output radices are separate parameters; you can make them unequal, which can be useful or confusing. The input radix must be between 2 and 16 inclusive. The output radix must be at least 2. The precision must be zero or greater. The precision is always measured in decimal digits, regardless of the current input or output radix.

`i'
Pops the value off the top of the stack and uses it to set the input radix.
`o'
Pops the value off the top of the stack and uses it to set the output radix.
`k'
Pops the value off the top of the stack and uses it to set the precision.
`I'
Pushes the current input radix on the stack.
`O'
Pushes the current output radix on the stack.
`K'
Pushes the current precision on the stack.

Strings

DC can operate on strings as well as on numbers. The only things you can do with strings are print them and execute them as macros (which means that the contents of the string are processed as DC commands). Both registers and the stack can hold strings, and DC always knows whether any given object is a string or a number. Some commands such as arithmetic operations demand numbers as arguments and print errors if given strings. Other commands can accept either a number or a string; for example, the `p' command can accept either and prints the object according to its type.

`[characters]'
Makes a string containing characters and pushes it on the stack. For example, `[foo]P' prints the characters `foo' (with no newline).
`a'
The mnemonic for this is somewhat erroneous: asciify. The top-of-stack is popped. If it was a number, then the low-order byte of this number is converted into a string and pushed onto the stack. Otherwise the top-of-stack was a string, and the first character of that string is pushed back. (This command is a GNU extension.)
`x'
Pops a value off the stack and executes it as a macro. Normally it should be a string; if it is a number, it is simply pushed back onto the stack. For example, `[1p]x' executes the macro `1p', which pushes 1 on the stack and prints `1' on a separate line. Macros are most often stored in registers; `[1p]sa' stores a macro to print `1' into register `a', and `lax' invokes the macro.
`>r'
Pops two values off the stack and compares them assuming they are numbers, executing the contents of register r as a macro if the original top-of-stack is greater. Thus, `1 2>a' will invoke register `a''s contents and `2 1>a' will not.
`!>r'
Similar but invokes the macro if the original top-of-stack is not greater (is less than or equal to) what was the second-to-top.
`<r'
Similar but invokes the macro if the original top-of-stack is less.
`!<r'
Similar but invokes the macro if the original top-of-stack is not less (is greater than or equal to) what was the second-to-top.
`=r'
Similar but invokes the macro if the two numbers popped are equal.
`!=r'
Similar but invokes the macro if the two numbers popped are not equal.
`?'
Reads a line from the terminal and executes it. This command allows a macro to request input from the user.
`q'
During the execution of a macro, this command exits from the macro and also from the macro which invoked it. If called from the top level, or from a macro which was called directly from the top level, the `q' command will cause DC to exit.
`Q'
Pops a value off the stack and uses it as a count of levels of macro execution to be exited. Thus, `3Q' exits three levels.

Status Inquiry

`Z'
Pops a value off the stack, calculates the number of digits it has (or number of characters, if it is a string) and pushes that number.
`X'
Pops a value off the stack, calculates the number of fraction digits it has, and pushes that number. For a string, the value pushed is 0.
`z'
Pushes the current stack depth: the number of objects on the stack before the execution of the `z' command.

Miscellaneous

`!'
Will run the rest of the line as a system command. Note that parsing of the !<, !=, and !> commands take precidence, so if you want to run a command starting with <, =, or > you will need to add a space after the !.
`#'
Will interpret the rest of the line as a comment. (This command is a GNU extension.)
`:r'
Will pop the top two values off of the stack. The old second-to-top value will be stored in the array r, indexed by the old top-of-stack value.
`;r'
Pops the top-of-stack and uses it as an index into the array r. The selected value is then pushed onto the stack.

Note that each stacked instance of a register has its own array associated with it. Thus `1 0:a 0Sa 2 0:a La 0;ap' will print 1, because the 2 was stored in an instance of 0:a that was later popped.

Reporting bugs

Email bug reports to bug-gnu-utils@prep.ai.mit.edu. Be sure to include the word "dc" somewhere in the "Subject:" field.

This document was generated on 7 November 1998 using the texi2html translator version 1.52.


Debugging with DDD

DDD is a graphical front-end for GDB and other command-line debuggers.

This is the First Edition of Debugging with DDD, 2000-01-03, for DDD Version 3.2.

  • Summary: Summary of DDD.

  • Sample Session: A sample DDD session.
  • Invocation: Getting in and out of DDD.
  • Windows: The DDD windows, menus, and buttons.
  • Navigating: Moving through the source code.
  • Stopping: Making your program stop at specific locations.
  • Running: Running programs under DDD.
  • Examining Data: Examining variable values and data structures.
  • Machine-Level Debugging: Examining machine code and registers.
  • Changing the Program: Changing source and object code.
  • Commands: Entering and editing DDD commands.

  • Application Defaults: Resources used in DDD.
  • Bugs: How, when, and why to report DDD bugs.
  • Configuration Notes: Configuration-specific notes.
  • Dirty Tricks: Room for your contributions.
  • Extending: Extending DDD.
  • FAQ: Frequently Answered Questions.
  • License: The DDD license.
  • Help and Assistance: Mailing Lists and other resources.

  • Label Index: All labels shown on the DDD GUI.
  • Key Index: Keys used to control DDD.
  • Command Index: Commands that can be typed within DDD.
  • Resource Index: All resources and environment variables.
  • File Index: All programs and files referenced by DDD.
  • Concept Index: All concepts as mentioned in this manual.

Table of Contents

  • Debugging with DDD
  • Summary of DDD
    • About this Manual
    • Free software
    • Getting DDD
    • Contributors to DDD
    • History of DDD
  • A Sample DDD Session
    • Sample Program
  • Getting In and Out of DDD
    • Invoking DDD
      • Choosing an Inferior Debugger
      • DDD Options
      • X Options
      • Inferior Debugger Options
        • GDB Options
        • DBX and Ladebug Options
        • XDB Options
        • JDB Options
        • PYDB Options
        • Perl Options
      • Multiple DDD Instances
      • X warnings
    • Quitting DDD
    • Persistent Sessions
      • Saving Sessions
      • Resuming Sessions
      • Deleting Sessions
      • Customizing Sessions
    • Remote Debugging
      • Running DDD on a Remote Host
      • Using DDD with a Remote Inferior Debugger
        • Customizing Remote Debugging
      • Debugging a Remote Program
    • Customizing Interaction with the Inferior Debugger
      • Invoking an Inferior Debugger
      • Initializing the Inferior Debugger
        • GDB Initialization
        • DBX Initialization
        • XDB Initialization
        • JDB Initialization
        • PYDB Initialization
        • Perl Initialization
        • Opening the Selection
      • Communication with the Inferior Debugger
  • The DDD Windows
    • The Menu Bar
      • The File Menu
      • The Edit Menu
      • The View Menu
      • The Program Menu
      • The Commands Menu
      • The Status Menu
      • The Source Menu
      • The Data Menu
      • The Maintenance Menu
      • The Help Menu
      • Customizing the Menu Bar
        • Auto-Raise Menus
        • Customizing the Edit Menu
    • The Tool Bar
      • Customizing the Tool Bar
    • The Command Tool
      • Customizing the Command Tool
        • Disabling the Command Tool
      • Command Tool Position
        • Customizing Tool Decoration
    • Getting Help
    • Undoing and Redoing Commands
    • Customizing DDD
      • How Customizing DDD Works
        • Resources
        • Changing Resources
        • Saving Options
      • Customizing DDD Help
        • Button Tips
        • Tip of the day
        • Help Helpers
      • Customizing Undo
      • Customizing the DDD Windows
        • Splash Screen
        • Window Layout
        • Customizing Fonts
        • Toggling Windows
        • Text Fields
        • Icons
        • Adding Buttons
        • More Customizations
      • Debugger Settings
  • Navigating through the Code
    • Compiling for Debugging
    • Opening Files
      • Opening Programs
      • Opening Core Dumps
      • Opening Source Files
      • Filtering Files
    • Looking up Items
      • Looking up Definitions
      • Textual Search
      • Looking up Previous Locations
      • Specifying Source Directories
    • Customizing the Source Window
      • Customizing Glyphs
      • Customizing Searching
      • Customizing Source Appearance
      • Customizing Source Scrolling
      • Customizing Source Lookup
      • Customizing File Filtering
  • Stopping the Program
    • Breakpoints
      • Setting Breakpoints
        • Setting Breakpoints by Location
        • Setting Breakpoints by Name
        • Setting Regexp Breakpoints
      • Deleting Breakpoints
      • Disabling Breakpoints
      • Temporary Breakpoints
      • Editing Breakpoint Properties
      • Breakpoint Conditions
      • Breakpoint Ignore Counts
      • Breakpoint Commands
      • Moving and Copying Breakpoints
      • Looking up Breakpoints
      • Editing all Breakpoints
      • Hardware-Assisted Breakpoints
    • Watchpoints
      • Setting Watchpoints
      • Editing Watchpoint Properties
      • Editing all Watchpoints
      • Deleting Watchpoints
    • Interrupting
    • Stopping X Programs
      • Customizing Grab Checking
  • Running the Program
    • Starting Program Execution
      • Your Program's Arguments
      • Your Program's Environment
      • Your Program's Working Directory
      • Your Program's Input and Output
    • Using the Execution Window
      • Customizing the Execution Window
    • Attaching to a Running Process
      • Customizing Attaching to Processes
    • Program Stops
    • Resuming Execution
      • Continuing
      • Stepping one Line
      • Continuing to the Next Line
      • Continuing Until Here
      • Continuing Until a Greater Line is Reached
      • Continuing Until Function Returns
    • Continuing at a Different Address
    • Examining the Stack
      • Stack Frames
      • Backtraces
      • Selecting a Frame
    • "Undoing" Program Execution
    • Examining Threads
    • Handling Signals
    • Killing the Program
  • Examining Data
    • Showing Simple Values using Value Tips
    • Printing Simple Values in the Debugger Console
    • Displaying Complex Values in the Data Window
      • Display Basics
        • Creating Single Displays
        • Selecting Displays
        • Showing and Hiding Details
        • Rotating Displays
        • Displaying Local Variables
        • Displaying Program Status
        • Refreshing the Data Window
        • Clustering Displays
        • Creating Multiple Displays
        • Editing all Displays
        • Deleting Displays
        • Customizing Displays
      • Displaying Arrays
        • Array Slices
        • Repeated Values
        • Arrays as Tables
      • Assignment to Variables
      • Examining Structures
        • Displaying Dependent Values
        • Dereferencing Pointers
        • Shared Structures
        • Display Shortcuts
      • Layouting the Graph
        • Moving Displays
        • Scrolling Data
        • Aligning Displays
        • Automatic Layout
        • Rotating the Graph
      • Printing the Graph
      • How Displays are Created
        • Handling Boxes
        • Building Boxes from Data
        • Customizing Display Appearance
    • Plotting Values
      • Plotting Arrays
      • Changing the Plot Appearance
      • Plotting Scalars and Composites
      • Plotting Display Histories
      • Printing Plots
      • Entering Plotting Commands
      • Exporting Plot Data
      • Animating Plots
      • Customizing Plots
        • Gnuplot Invocation
        • Gnuplot Settings
    • Examining Memory
  • Machine-Level Debugging
    • Examining Machine Code
    • Machine Code Execution
    • Examining Registers
    • Customizing Machine Code
  • Changing the Program
    • Editing Source Code
      • Customizing Editing
      • In-Place Editing
    • Recompiling
    • Patching
  • The Command-Line Interface
    • Entering Commands
      • Command Completion
      • Command History
    • Entering Commands at the TTY
    • Integrating DDD
      • Using DDD with Emacs
      • Using DDD with XEmacs
      • Using DDD with XXGDB
    • Defining Buttons
      • Customizing Buttons
    • Defining Commands
      • Defining Simple Commands using GDB
      • Defining Argument Commands using GDB
      • Defining Commands using Other Debuggers
  • Application Defaults
    • Actions
      • General Actions
      • Data Display Actions
      • Debugger Console Actions
      • Source Window Actions
    • Images
  • Bugs and How To Report Them
    • Where to Send Bug Reports
    • Is it a DDD Bug?
    • How to Report Bugs
    • What to Include in a Bug Report
    • Getting Diagnostics
      • Logging
        • Disabling Logging
      • Debugging DDD
      • Customizing Diagnostics
  • Configuration Notes
    • Using DDD with GDB
    • Using DDD with DBX
    • Using DDD with Ladebug
    • Using DDD with XDB
    • Using DDD with JDB
    • Using DDD with Perl
    • Using DDD with LessTif
  • Dirty Tricks
  • Extending DDD
  • Frequently Answered Questions
  • GNU General Public License
    • Preamble
    • How to Apply These Terms to Your New Programs
  • Help and Assistance
  • Label Index
  • Key Index
  • Command Index
  • Resource Index
  • File Index
  • Concept Index

Copyright © 2000 Universität Passau
Lehrstuhl für Software-Systeme
Innstraße 33
D-94032 Passau
GERMANY

Distributed by
Free Software Foundation, Inc.
59 Temple Place - Suite 330
Boston, MA 02111-1307
USA

DDD and this manual are available via the DDD WWW page.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "Copying" and "GNU General Public License" (see License) are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

Send questions, comments, suggestions, etc. to ddd@gnu.org.
Send bug reports to bug-ddd@gnu.org.

Node:Summary, Next:Sample Session, Previous:Top, Up:Top

Summary of DDD

The purpose of a debugger such as DDD is to allow you to see what is going on "inside" another program while it executes--or what another program was doing at the moment it crashed.

DDD can do four main kinds of things (plus other things in support of these) to help you catch bugs in the act:

  • Start your program, specifying anything that might affect its behavior.
  • Make your program stop on specified conditions.
  • Examine what has happened, when your program has stopped.
  • Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another.

Technically speaking, DDD is a front-end to a command-line debugger (called inferior debugger, because it lies at the layer beneath DDD). DDD supports the following inferior debuggers:

  • To debug executable binaries, you can use DDD with GDB, DBX, Ladebug, or XDB.
    • GDB, the GNU debugger, is the recommended inferior debugger for DDD. GDB supports native executables binaries originally written in C, C++, Java, Modula-2, Modula-3, Pascal, Chill, Ada, and FORTRAN. (see Languages, for information on language support in GDB.)
    • As an alternative to GDB, you can use DDD with the DBX debugger, as found on several UNIX systems. Most DBX incarnations offer fewer features than GDB, and some of the more advanced DBX features may not be supported by DDD. However, using DBX may be useful if GDB does not understand or fully support the debugging information as generated by your compiler.
    • As an alternative to GDB and DBX, you can use DDD with Ladebug, as found on DEC systems. Ladebug offers fewer features than GDB, and some of the more advanced Ladebug features may not be supported by DDD. However, using Ladebug may be useful if GDB or DBX do not understand or fully support the debugging information as generated by your compiler.1
    • As another alternative to GDB, you can use DDD with the XDB debugger, as found on HP-UX systems.2.
  • To debug Java byte-code programs, you can use DDD with JDB, the Java debugger, as of JDK 1.1 and later.
  • To debug Python programs, you can use DDD with PYDB, a Python debugger.
  • To debug Perl programs, you can use DDD with the Perl debugger, as of Perl 5.003 and later.

See Choosing an Inferior Debugger, for choosing the appropriate inferior debugger. See Sample Session, for getting a first impression of DDD.

  • About this Manual: Getting copies in various formats.
  • Free Software: How to copy and redistribute DDD.
  • Getting DDD: How to obtain copies of DDD.
  • Contributors: Who has done all this?
  • History: Old DDD versions.

Node:About this Manual, Next:Free Software, Up:Summary

About this Manual

This manual comes in several formats:

  • The Info format is used for browsing on character devices; it comes without pictures. You should have a local copy installed, which you can browse via Emacs, the stand-alone info program, or from DDD via Help => DDD Manual.

    The DDD source distribution ddd-3.2.tar.gz contains this manual as pre-formatted info files; you can also download them from
    the DDD WWW page.

  • The PostScript format is used for printing on paper; it comes with pictures as well.

    The DDD source distribution ddd-3.2.tar.gz contains this manual as pre-formatted PostScript file; you can also download it from
    the DDD WWW page.

  • The PDF format is used for printing on paper as well as for online browsing; it comes with pictures as well.

    The DDD source distribution ddd-3.2.tar.gz contains this manual as pre-formatted PDF file; you can also download it from
    the DDD WWW page.

  • The HTML format is used for browsing on bitmap devices; it includes several pictures. You can view it using a HTML browser, typically from a local copy.

    A pre-formatted HTML version of this manual comes in a separate DDD package
    ddd-3.2-html-manual.tar.gz; you can browse and download it via
    the DDD WWW page.

The manual itself is written in TeXinfo format; its source code ddd.texi is contained in the DDD source distribution ddd-3.2.tar.gz.

The picture sources come in a separate package ddd-3.2-pics.tar.gz; you need this package only if you want to re-create the PostScript, HTML, or PDF versions.

Node:Free Software, Next:Getting DDD, Previous:About this Manual, Up:Summary

Free software

DDD is free; this means that everyone is free to use it and free to redistribute it on a free basis. DDD is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of DDD that they might get from you. The precise conditions are found in the GNU General Public License that comes with DDD; See License, for details.

The easiest way to get a copy of DDD is from someone else who has it. You need not ask for permission to do so, or tell any one else; just copy it.

Node:Getting DDD, Next:Contributors, Previous:Free Software, Up:Summary

Getting DDD

If you have access to the Internet, you can get the latest version of DDD from the anonymous FTP server ftp.gnu.org in the directory /gnu/ddd. This should contain the following files:

ddd-version.tar.gz
The DDD source distribution. This should be all you need.
ddd-version-html-manual.tar.gz
The DDD manual in HTML format. You need this only if you want to install a local copy of the DDD manual in HTML format.
ddd-version-pics.tar.gz
Sources of images included in the DDD manual. You need this only if you want to recreate the DDD manual.

DDD can also be found at numerous other archive sites around the world; check the file ANNOUNCE in a DDD distribution for the latest known list.

Node:Contributors, Next:History, Previous:Getting DDD, Up:Summary

Contributors to DDD

Dorothea Lütkehaus and Andreas Zeller were the original authors of DDD. Many others have contributed to its development. The files ChangeLog and THANKS in the DDD distribution approximates a blow-by-blow account.

Node:History, Previous:Contributors, Up:Summary

History of DDD

The history of DDD is a story of code recycling. The oldest parts of DDD were written in 1990, when Andreas Zeller designed VSL, a box-based visual structure language for visualizing data and program structures. The VSL interpreter and the Box library became part of Andreas' Diploma Thesis, a graphical syntax editor based on the Programming System Generator PSG.

In 1992, the VSL and Box libraries were recycled for the NORA project. For NORA, an experimental inference-based software development tool set, Andreas wrote a graph editor (based on VSL and the Box libraries) and facilities for inter-process knowledge exchange. Based on these tools, Dorothea Lütkehaus (now Dorothea Krabiell) realized DDD as her Diploma Thesis, 1994

The original DDD had no source window; this was added by Dorothea during the winter of 1994-1995. In the first quarter of 1995, finally, Andreas completed DDD by adding command and execution windows, extensions for DBX and remote debugging as well as configuration support for several architectures. Since then, Andreas has further maintained and extended DDD, based on the comments and suggestions of several DDD users around the world. See the comments in the DDD source for details.

Major DDD events:

April, 1995
DDD 0.9: First DDD beta release.
May, 1995
DDD 1.0: First public DDD release.
December, 1995
DDD 1.4: Machine-level debugging, glyphs, Emacs integration.
October, 1996
DDD 2.0: Color displays, XDB support, generic DBX support, command tool.
May, 1997
DDD 2.1: Alias detection, button tips, status displays.
November, 1997
DDD 2.2: Sessions, display shortcuts.
June, 1998
DDD 3.0: Icon tool bar, Java support, JDB support.
December, 1998
DDD 3.1: Data plotting, Perl support, Python support, Undo/Redo.
January, 2000
DDD 3.2: New manual, Readline support, Ladebug support.

Node:Sample Session, Next:Invocation, Previous:Summary, Up:Top

A Sample DDD Session

You can use this manual at your leisure to read all about DDD. However, a handful of features are enough to get started using the debugger. This chapter illustrates those features.

The sample program sample.c (see Sample Program) exhibits the following bug. Normally, sample should sort and print its arguments numerically, as in the following example:

$ ./sample 8 7 5 4 1 3
1 3 4 5 7 8

However, with certain arguments, this goes wrong:

$ ./sample 8000 7000 5000 1000 4000
1000 1913 4000 5000 7000

Although the output is sorted and contains the right number of arguments, some arguments are missing and replaced by bogus numbers; here, 8000 is missing and replaced by 1913.3

Let us use DDD to see what is going on. First, you must compile sample.c for debugging (see Compiling for Debugging), giving the -g flag while compiling:

$ gcc -g -o sample sample.c
  • Sample Program: Source sample.c

Now, you can invoke DDD (see Invocation) on the sample executable:

$ ddd sample

After a few seconds, DDD comes up. The Source Window contains the source of your debugged program; use the Scroll Bar to scroll through the file.

The Debugger Console (at the bottom) contains DDD version information as well as a GDB prompt.4

GNU DDD Version 3.2, by Dorothea Lütkehaus and Andreas Zeller.
Copyright © 1999 Technische Universität Braunschweig, Germany.
Copyright © 1999 Universität Passau, Germany.
Reading symbols from sample...done.
(gdb)

The first thing to do now is to place a Breakpoint (see Breakpoints), making sample stop at a location you are interested in. Click on the blank space left to the initialization of a. The Argument field (): now contains the location (sample.c:31). Now, click on Break to create a breakpoint at the location in (). You see a little red stop sign appear in line 31.

The next thing to do is to actually execute the program, such that you can examine its behavior (see Running). Select Program => Run to execute the program; the Run Program dialog appears.

In Run with Arguments, you can now enter arguments for the sample program. Enter the arguments resulting in erroneous behavior here--that is, 8000 7000 5000 1000 4000. Click on Run to start execution with the arguments you just entered.

GDB now starts sample. Execution stops after a few moments as the breakpoint is reached. This is reported in the debugger console.

(gdb) break sample.c:31
Breakpoint 1 at 0x8048666: file sample.c, line 31.
(gdb) run 8000 7000 5000 1000 4000
Starting program: sample 8000 7000 5000 1000 4000

Breakpoint 1, main (argc=6, argv=0xbffff918) at sample.c:31
(gdb)

The current execution line is indicated by a green arrow.

=> a = (int *)malloc((argc - 1) * sizeof(int));

You can now examine the variable values. To examine a simple variable, you can simply move the mouse pointer on its name and leave it there. After a second, a small window with the variable value pops up (see Value Tips). Try this with argv to see its value (6). The local variable a is not yet initialized; you'll probably see 0x0 or some other invalid pointer value.

To execute the current line, click on the Next button on the command tool. The arrow advances to the following line. Now, point again on a to see that the value has changed and that a has actually been initialized.

To examine the individual values of the a array, enter a[0] in the argument field (you can clear it beforehand by clicking on ():) and then click on the Print button. This prints the current value of () in the debugger console (see Printing Values). In our case, you'll get

(gdb) print a[0]
$1 = 0
(gdb)

or some other value (note that a has only been allocated, but the contents have not yet been initialized).

To see all members of a at once, you must use a special GDB operator. Since a has been allocated dynamically, GDB does not know its size; you must specify it explicitly using the @ operator (see Array Slices). Enter a[0]@(argc - 1) in the argument field and click on the Print button. You get the first argc - 1 elements of a, or

(gdb) print a[0]@(argc - 1)
$2 = {0, 0, 0, 0, 0}
(gdb)

Rather than using Print at each stop to see the current value of a, you can also display a, such that its is automatically displayed. With a[0]@(argc - 1) still being shown in the argument field, click on Display. The contents of a are now shown in a new window, the Data Window. Click on Rotate to rotate the array horizontally.

Now comes the assignment of a's members:

=>  for (i = 0; i < argc - 1; i++)
        a[i] = atoi(argv[i + 1]);

You can now click on Next and Next again to see how the individual members of a are being assigned. Changed members are highlighted.

To resume execution of the loop, use the Until button. This makes GDB execute the program until a line greater than the current is reached. Click on Until until you end at the call of shell_sort in

=>  shell_sort(a, argc);

At this point, a's contents should be 8000 7000 5000 1000 4000. Click again on Next to step over the call to shell_sort. DDD ends in

=>  for (i = 0; i < argc - 1; i++)
        printf("%d ", a[i]);

and you see that after shell_sort has finished, the contents of a are 1000, 1913, 4000, 5000, 7000--that is, shell_sort has somehow garbled the contents of a.

To find out what has happened, execute the program once again. This time, you do not skip through the initialization, but jump directly into the shell_sort call. Delete the old breakpoint by selecting it and clicking on Clear. Then, create a new breakpoint in line 35 before the call to shell_sort. To execute the program once again, select Program => Run Again.

Once more, DDD ends up before the call to shell_sort:

=>  shell_sort(a, argc);

This time, you want to examine closer what shell_sort is doing. Click on Step to step into the call to shell_sort. This leaves your program in the first executable line, or

=> int h = 1;

while the debugger console tells us the function just entered:

(gdb) step
shell_sort (a=0x8049878, size=6) at sample.c:9
(gdb)

This output that shows the function where sample is now suspended (and its arguments) is called a stack frame display. It shows a summary of the stack. You can use Status => Backtrace to see where you are in the stack as a whole; selecting a line (or clicking on Up and Down) will let you move through the stack. Note how the a display disappears when its frame is left.

Let us now check whether shell_sort's arguments are correct. After returning to the lowest frame, enter a[0]@size in the argument field and click on Print:

(gdb) print a[0] @ size
$4 = {8000, 7000, 5000, 1000, 4000, 1913}
(gdb)

Surprise! Where does this additional value 1913 come from? The answer is simple: The array size as passed in size to shell_sort is too large by one--1913 is a bogus value which happens to reside in memory after a. And this last value is being sorted in as well.

To see whether this is actually the problem cause, you can now assign the correct value to size (see Assignment). Select size in the source code and click on Set. A dialog pops up where you can edit the variable value.

Change the value of size to 5 and click on OK. Then, click on Finish to resume execution of the shell_sort function:

(gdb) set variable size = 5
(gdb) finish
Run till exit from #0  shell_sort (a=0x8049878, size=5) at sample.c:9
0x80486ed in main (argc=6, argv=0xbffff918) at sample.c:35
(gdb)

Success! The a display now contains the correct values 1000, 4000, 5000, 7000, 8000.

You can verify that these values are actually printed to standard output by further executing the program. Click on Cont to continue execution.

(gdb) cont
1000 4000 5000 7000 8000

Program exited normally.
(gdb)

The message Program exited normally. is from GDB; it indicates that the sample program has finished executing.

Having found the problem cause, you can now fix the source code. Click on Edit to edit sample.c, and change the line

shell_sort(a, argc);

to the correct invocation

shell_sort(a, argc - 1);

You can now recompile sample

$ gcc -g -o sample sample.c

and verify (via Program => Run Again) that sample works fine now.

(gdb) run
`sample' has changed; re-reading symbols.
Reading in symbols...done.
Starting program: sample 8000 7000 5000 1000 4000
1000 4000 5000 7000 8000

Program exited normally.
(gdb)

All is done; the program works fine now. You can end this DDD session with Program => Exit or Ctrl+Q.

Node:Sample Program, Up:Sample Session

Sample Program

Here's the source sample.c of the sample program.

/* sample.c -- Sample C program to be debugged with DDD */

#include <stdio.h>
#include <stdlib.h>

static void shell_sort(int a[], int size)
{
    int i, j;
    int h = 1;
    do {
        h = h * 3 + 1;
    } while (h <= size);
    do {
        h /= 3;
        for (i = h; i < size; i++)
        {
            int v = a[i];
            for (j = i; j >= h && a[j - h] > v; j -= h)
                a[j] = a[j - h];
            if (i != j)
                a[j] = v;
        }
    } while (h != 1);
}

int main(int argc, char *argv[])
{
    int *a;
    int i;

    a = (int *)malloc((argc - 1) * sizeof(int));
    for (i = 0; i < argc - 1; i++)
        a[i] = atoi(argv[i + 1]);

    shell_sort(a, argc);

    for (i = 0; i < argc - 1; i++)
        printf("%d ", a[i]);
    printf("\n");

    free(a);
    return 0;
}

Node:Invocation, Next:Windows, Previous:Sample Session, Up:Top

Getting In and Out of DDD

This chapter discusses how to start DDD, and how to get out of it. The essentials are:

  • Type ddd to start DDD (see Invoking).
  • Use File => Exit or Ctrl+Q to exit (see Quitting).
  • Invoking: How to invoke DDD.
  • Quitting: How to quit DDD.
  • Sessions: Saving work across invocations.
  • Remote Debugging: Running DDD on a different host.
  • Customizing Debugger Interaction: How DDD and GDB communicate.

Node:Invoking, Next:Quitting, Up:Invocation

Invoking DDD

Normally, you can run DDD by invoking the program ddd.

You can also run DDD with a variety of arguments and options, to specify more of your debugging environment at the outset.

The most usual way to start DDD is with one argument, specifying an executable program:

ddd program

If you use GDB, DBX, Ladebug, or XDB as inferior debuggers, you can also start with both an executable program and a core file specified:

ddd program core

You can, instead, specify a process ID as a second argument, if you want to debug a running process:

ddd program 1234

would attach DDD to process 1234 (unless you also have a file named 1234; DDD does check for a core file first).

You can further control DDD by invoking it with specific options. To get a list of DDD options, invoke DDD as

ddd --help

Most important are the options to specify the inferior debugger (see Choosing an Inferior Debugger), but you can also customize several aspects of DDD upon invocation (see Options).

DDD also understands the usual X options such as -display or -geometry. See X Options, for details.

All arguments and options that are not understood by DDD are passed to the inferior debugger; See Inferior Debugger Options, for a survey. To pass an option to the inferior debugger that conflicts with an X option, or with a DDD option listed here, use the --debugger option (see Options).

  • Choosing an Inferior Debugger: Which debugger to use?
  • Options: How to invoke DDD
  • X Options: Setting X properties
  • Inferior Debugger Options: Customizing GDB, DBX, and so on
  • Multiple Instances: Running multiple DDD instances
  • X Warnings: Turning off obnoxious warnings

Node:Choosing an Inferior Debugger, Next:Options, Up:Invoking

Choosing an Inferior Debugger

The most frequently required options are those to choose a specific inferior debugger.

Normally, the inferior debugger is determined by the program to analyze:

  • If the program requires a specific interpreter, such as Java, Python, or Perl, then you should use a JDB, PYDB, or Perl inferior debugger.

    Use

    ddd --jdb program

    ddd --pydb program

    ddd --perl program

    to run DDD with JDB, PYDB, or Perl as inferior debugger.

  • If the program is an executable binary, you should use GDB, DBX, Ladebug, or XDB. In general, GDB provides the most functionality of these three debuggers.

    Use

    ddd --gdb program

    ddd --dbx program

    ddd --ladebug program

    ddd --xdb program

    to run DDD with GDB, DBX, Ladebug, or XDB as inferior debugger.

If you invoke DDD without any of these options, but give a program to analyze, then DDD will automatically determine the inferior debugger:

  • If program is a Python program, a Perl script, or a Java class, DDD will invoke the appropriate debugger.
  • If program is an executable binary, DDD will invoke its default debugger for executables (usually GDB).

See Customizing Debugger Interaction, for more details on determining the inferior debugger.

Node:Options, Next:X Options, Previous:Choosing an Inferior Debugger, Up:Invoking

DDD Options

You can further control how DDD starts up using the following options. All options may be abbreviated, as long as they are unambiguous; single dashes - instead of double dashes -- may also be used. Almost all options control a specific DDD resource or resource class (see Customizing).

--attach-windows
Attach the source and data windows to the debugger console, creating one single big DDD window. This is the default setting.

Giving this option is equivalent to setting the DDD Separate resource class to off. See Window Layout, for details.

--attach-source-window
Attach only the source window to the debugger console.

Giving this option is equivalent to setting the DDD separateSourceWindow resource to off. See Window Layout, for details.

--attach-data-window
Attach only the source window to the debugger console.

Giving this option is equivalent to setting the DDD separateDataWindow resource to off. See Window Layout, for details.

--automatic-debugger
Determine the inferior debugger automatically from the given arguments.

Giving this option is equivalent to setting the DDD autoDebugger resource to on. See Customizing Debugger Interaction, for details.

--button-tips
Enable button tips.

Giving this option is equivalent to setting the DDD buttonTips resource to on. See Customizing Help, for details.

--configuration
Print the DDD configuration settings on standard output and exit.

Giving this option is equivalent to setting the DDD showConfiguration resource to on. See Diagnostics, for details.

--check-configuration
Check the DDD environment (in particular, the X configuration), report any possible problem causes and exit.

Giving this option is equivalent to setting the DDD checkConfiguration resource to on. See Diagnostics, for details.

--data-window
Open the data window upon start-up.

Giving this option is equivalent to setting the DDD openDataWindow resource to on. See Toggling Windows, for details.

--dbx
Run DBX as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to dbx. See Customizing Debugger Interaction, for details.

--debugger name
Invoke the inferior debugger name. This is useful if you have several debugger versions around, or if the inferior debugger cannot be invoked under its usual name (i.e. gdb, dbx, xdb, jdb, pydb, or perl).

This option can also be used to pass options to the inferior debugger that would otherwise conflict with DDD options. For instance, to pass the option -d directory to XDB, use:

ddd --debugger "xdb -d directory"

If you use the --debugger option, be sure that the type of inferior debugger is specified as well. That is, use one of the options --gdb, --dbx, --xdb, --jdb, --pydb, or --perl (unless the default setting works fine).

Giving this option is equivalent to setting the DDD debuggerCommand resource to name. See Customizing Debugger Interaction, for details.

--debugger-console
Open the debugger console upon start-up.

Giving this option is equivalent to setting the DDD openDebuggerConsole resource to on. See Toggling Windows, for details.

--disassemble
Disassemble the source code. See also the --no-disassemble option, below.

Giving this option is equivalent to setting the DDD disassemble resource to on. See Customizing Source, for details.

--exec-window
Run the debugged program in a specially created execution window. This is useful for programs that have special terminal requirements not provided by the debugger window, as raw keyboard processing or terminal control sequences. See Using the Execution Window, for details.

Giving this option is equivalent to setting the DDD separateExecWindow resource to on. See Customizing the Execution Window, for details.

--font fontname
-fn fontname
Use fontname as default font.

Giving this option is equivalent to setting the DDD defaultFont resource to fontname. See Customizing Fonts, for details.

--fonts
Show the font definitions used by DDD on standard output.

Giving this option is equivalent to setting the DDD showFonts resource to on. See Diagnostics, for details.

--fontsize size
Set the default font size to size (in 1/10 points). To make DDD use 12-point fonts, say --fontsize 120.

Giving this option is equivalent to setting the DDD FontSize resource class to size. See Customizing Fonts, for details.

--fullname
-f
Enable the TTY interface, taking additional debugger commands from standard input and forwarding debugger output on standard output. Current positions are issued in GDB -fullname format suitable for debugger front-ends. By default, both the debugger console and source window are disabled. See TTY mode, for a discussion.

Giving this option is equivalent to setting the DDD TTYMode resource class to on. See TTY mode, for details.

--gdb
Run GDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to gdb. See Customizing Debugger Interaction, for details.

--glyphs
Display the current execution position and breakpoints as glyphs. See also the --no-glyphs option, below.

Giving this option is equivalent to setting the DDD displayGlyphs resource to on. See Customizing Source, for details.

--help
-h
-?
Give a list of frequently used options. Show options of the inferior debugger as well.

Giving this option is equivalent to setting the DDD showInvocation resource to on. See Diagnostics, for details.

--host hostname
--host username@hostname
Invoke the inferior debugger directly on the remote host hostname. If username is given and the --login option is not used, use username as remote user name. See Remote Debugger, for details.

Giving this option is equivalent to setting the DDD debuggerHost resource to hostname. See Remote Debugger, for details.

--jdb
Run JDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to gdb. See Customizing Debugger Interaction, for details.

--ladebug
Run Ladebug as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to ladebug. See Customizing Debugger Interaction, for details.

--lesstif-hacks
Equivalent to --lesstif-version 999. Deprecated.

Giving this option is equivalent to setting the DDD lessTifVersion resource to 999. See LessTif, for details.

--lesstif-version version
Enable some hacks to make DDD run properly with LessTif. See LessTif, for a discussion.

Giving this option is equivalent to setting the DDD lessTifVersion resource to version. See LessTif, for details.

--license
Print the DDD license on standard output and exit.

Giving this option is equivalent to setting the DDD showLicense resource to on. See Diagnostics, for details.

--login username
-l username
Use username as remote user name. See Remote Debugger, for details.

Giving this option is equivalent to setting the DDD debuggerHostLogin resource to username. See Remote Debugger, for details.

--maintenance
Enable the top-level Maintenance menu with options for debugging DDD. See Maintenance Menu, for details.

Giving this option is equivalent to setting the DDD maintenance resource to on. See Maintenance Menu, for details.

--manual
Print the DDD manual on standard output and exit.

Giving this option is equivalent to setting the DDD showManual resource to on. See Diagnostics, for details.

--news
Print the DDD news on standard output and exit.

Giving this option is equivalent to setting the DDD showNews resource to on. See Diagnostics, for details.

--no-button-tips
Disable button tips.

Giving this option is equivalent to setting the DDD buttonTips resource to off. See Customizing Help, for details.

--no-data-window
Do not open the data window upon start-up.

Giving this option is equivalent to setting the DDD openDataWindow resource to off. See Toggling Windows, for details.

--no-debugger-console
Do not open the debugger console upon start-up.

Giving this option is equivalent to setting the DDD openDebuggerConsole resource to off. See Toggling Windows, for details.

--no-disassemble
Do not disassemble the source code.

Giving this option is equivalent to setting the DDD disassemble resource to off. See Customizing Source, for details.

--no-exec-window
Do not run the debugged program in a specially created execution window; use the debugger console instead. Useful for programs that have little terminal input/output, or for remote debugging. See Using the Execution Window, for details.

Giving this option is equivalent to setting the DDD separateExecWindow resource to off. See Customizing the Execution Window, for details.

--no-glyphs
Do not use glyphs; display the current execution position and breakpoints as text characters.

Giving this option is equivalent to setting the DDD displayGlyphs resource to off. See Customizing Source, for details.

--no-lesstif-hacks
Equivalent to --lesstif-version 1000. Deprecated.

Giving this option is equivalent to setting the DDD lessTifVersion resource to 1000. See LessTif, for details.

--no-maintenance
Do not enable the top-level Maintenance menu with options for debugging DDD. This is the default. See Maintenance Menu, for details.

Giving this option is equivalent to setting the DDD maintenance resource to off. See Maintenance Menu, for details.

--no-source-window
Do not open the source window upon start-up.

Giving this option is equivalent to setting the DDD openSourceWindow resource to off. See Toggling Windows, for details.

--no-value-tips
Disable value tips.

Giving this option is equivalent to setting the DDD valueTips resource to off. See Value Tips, for details.

--nw
Do not use the X window interface. Start the inferior debugger on the local host.
--perl
Run Perl as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to perl. See Customizing Debugger Interaction, for details.

--pydb
Run PYDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to pydb. See Customizing Debugger Interaction, for details.

--panned-graph-editor
Use an Athena panner to scroll the data window. Most people prefer panners on scroll bars, since panners allow two-dimensional scrolling. However, the panner is off by default, since some Motif implementations do not work well with Athena widgets. See Customizing Displays, for details; see also --scrolled-graph-editor, below.

Giving this option is equivalent to setting the DDD pannedGraphEditor resource to on. See Customizing Displays, for details.

--play-log log-file
Recapitulate a previous DDD session.
ddd --play-log log-file

invokes DDD as inferior debugger, simulating the inferior debugger given in log-file (see below). This is useful for debugging DDD.

Giving this option is equivalent to setting the DDD playLog resource to on. See Customizing Debugger Interaction, for details.

--PLAY log-file
Simulate an inferior debugger. log-file is a $HOME/.ddd/log file as generated by some previous DDD session (see Logging). When a command is entered, scan log-file for this command and re-issue the logged reply; if the command is not found, do nothing. This is used by the --play option.
--rhost hostname
--rhost username@hostname
Run the inferior debugger interactively on the remote host hostname. If username is given and the --login option is not used, use username as remote user name. See Remote Debugger, for details.

Giving this option is equivalent to setting the DDD debuggerRHost resource to hostname. See Remote Debugger, for details.

--scrolled-graph-editor
Use Motif scroll bars to scroll the data window. This is the default in most DDD configurations. See Customizing Displays, for details; see also --panned-graph-editor, above.

Giving this option is equivalent to setting the DDD pannedGraphEditor resource to off. See Customizing Displays, for details.

--separate-windows
--separate
Separate the console, source and data windows. See also the --attach options, above.

Giving this option is equivalent to setting the DDD Separate resource class to off. See Window Layout, for details.

--session session
Load session upon start-up. See Resuming Sessions, for details.

Giving this option is equivalent to setting the DDD session resource to session. See Resuming Sessions, for details.

--source-window
Open the source window upon start-up.

Giving this option is equivalent to setting the DDD openSourceWindow resource to on. See Toggling Windows, for details.

--status-at-bottom
Place the status line at the bottom of the source window.

Giving this option is equivalent to setting the DDD statusAtBottom resource to on. See Window Layout, for details.

--status-at-top
Place the status line at the top of the source window.

Giving this option is equivalent to setting the DDD statusAtBottom resource to off. See Window Layout, for details.

--sync-debugger
Do not process X events while the debugger is busy. This may result in slightly better performance on single-processor systems.

Giving this option is equivalent to setting the DDD synchronousDebugger resource to on. See Customizing Debugger Interaction, for details.

--toolbars-at-bottom
Place the toolbars at the bottom of the respective window.

Giving this option is equivalent to setting the DDD toolbarsAtBottom resource to on. See Window Layout, for details.

--toolbars-at-top
Place the toolbars at the top of the respective window.

Giving this option is equivalent to setting the DDD toolbarsAtBottom resource to off. See Window Layout, for details.

--trace
Show the interaction between DDD and the inferior debugger on standard error. This is useful for debugging DDD. If --trace is not specified, this information is written into ~/.ddd/log (~ stands for your home directory), such that you can also do a post-mortem debugging. See Logging, for details about logging.

Giving this option is equivalent to setting the DDD trace resource to on. See Diagnostics, for details.

--tty
-t
Enable TTY interface, taking additional debugger commands from standard input and forwarding debugger output on standard output. Current positions are issued in a format readable for humans. By default, the debugger console is disabled.

Giving this option is equivalent to setting the DDD ttyMode resource to on. See TTY mode, for details.

--value-tips
Enable value tips.

Giving this option is equivalent to setting the DDD valueTips resource to on. See Value Tips, for details.

--version
-v
Print the DDD version on standard output and exit.

Giving this option is equivalent to setting the DDD showVersion resource to on. See Diagnostics, for details.

--vsl-library library
Load the VSL library library instead of using the DDD built-in library. This is useful for customizing display shapes and fonts.

Giving this option is equivalent to setting the DDD vslLibrary resource to library. See Customizing Display Appearance, for details.

--vsl-path path
Search VSL libraries in path (a colon-separated directory list).

Giving this option is equivalent to setting the DDD vslPath resource to path. See Customizing Display Appearance, for details.

--vsl-help
Show a list of further options controlling the VSL interpreter. These options are intended for debugging purposes and are subject to change without further notice.
--xdb
Run XDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to xdb. See Customizing Debugger Interaction, for details.

Node:X Options, Next:Inferior Debugger Options, Previous:Options, Up:Invoking

X Options

DDD also understands the following X options. Note that these options only take a single dash -.

-display display
Use the X server display. By default, display is taken from the DISPLAY environment variable.
-geometry geometry
Specify the initial size and location of the debugger console.
-iconic
Start DDD iconified.
-name name
Give DDD the name name.
-selectionTimeout timeout
Specify the timeout in milliseconds within which two communicating applications must respond to one another for a selection request.
-title name
Give the DDD window the title name.
-xrm resourcestring
Specify a resource name and value to override any defaults.

Node:Inferior Debugger Options, Next:Multiple Instances, Previous:X Options, Up:Invoking

Inferior Debugger Options

All options that DDD does not recognize are passed to the inferior debugger. This section lists the most useful options of the different inferior debuggers supported by DDD.

  • GDB Options:
  • DBX and Ladebug Options:
  • XDB Options:
  • JDB Options:
  • PYDB Options:
  • Perl Options:

Node:GDB Options, Next:DBX and Ladebug Options, Up:Inferior Debugger Options

GDB Options

These GDB options are useful when using DDD with GDB as inferior debugger. Single dashes - instead of double dashes -- may also be used.

-b baudrate
Set serial port baud rate used for remote debugging.
--cd dir
Change current directory to dir.
--command file
Execute GDB commands from file.
--core corefile
Analyze the core dump corefile.
--directory dir
-d dir
Add directory to the path to search for source files.
--exec execfile
Use execfile as the executable.
--mapped
Use mapped symbol files if supported on this system.
--nx
-n
Do not read .gdbinit file.
--readnow
Fully read symbol files on first access.
--se file
Use file as symbol file and executable file.
--symbols symfile
Read symbols from symfile.

See Invoking GDB, for further options that can be used with GDB.

Node:DBX and Ladebug Options, Next:XDB Options, Previous:GDB Options, Up:Inferior Debugger Options

DBX and Ladebug Options

DBX variants differ widely in their options, so we cannot give a list here. Check out the dbx(1) and ladebug(1) manual pages.

Node:XDB Options, Next:JDB Options, Previous:DBX and Ladebug Options, Up:Inferior Debugger Options

XDB Options

These XDB options are useful when using DDD with XDB as inferior debugger.

-d dir
Specify dir as an alternate directory where source files are located.
-P process-id
Specify the process ID of an existing process the user wants to debug.
-l library
Pre-load information about the shared library library. -l ALL means always pre-load shared library information.
-S num
Set the size of the string cache to num bytes (default is 1024, which is also the minimum).
-s
Enable debugging of shared libraries.

Further options can be found in the xdb(1) manual page.

Node:JDB Options, Next:PYDB Options, Previous:XDB Options, Up:Inferior Debugger Options

JDB Options

The following JDB options are useful when using DDD with JDB as inferior debugger.

-host hostname
host machine of interpreter to attach to
-password psswd
password of interpreter to attach to (from -debug)

These JDB options are forwarded to debuggee process:

-verbose
-v
Turn on verbose mode.
-debug
Enable remote Java debugging,
-noasyncgc
Don't allow asynchronous garbage collection.
-verbosegc
Print a message when garbage collection occurs.
-noclassgc
Disable class garbage collection.
-checksource
-cs
Check if source is newer when loading classes.
-ss number
Set the maximum native stack size for any thread.
-oss number
Set the maximum Java stack size for any thread.
-ms number
Set the initial Java heap size.
-mx number
Set the maximum Java heap size.
-Dname=value
Set the system property name to value.
-classpath path
List directories in which to look for classes. path is a list of directories separated by colons.
-prof
-prof:file
Output profiling data to ./java.prof. If file is given, write the data to ./file.
-verify
Verify all classes when read in.
-verifyremote
Verify classes read in over the network (default).
-noverify
Do not verify any class.
-dbgtrace
Print info for debugging JDB.

Further options can be found in the JDB documentation.

Node:PYDB Options, Next:Perl Options, Previous:JDB Options, Up:Inferior Debugger Options

PYDB Options

For a list of useful PYDB options, check out the PYDB documentation.

Node:Perl Options, Previous:PYDB Options, Up:Inferior Debugger Options

Perl Options

The most important Perl option to use with DDD is -w; it enables several important warnings. For further options, see the perlrun(1) manual page.

Node:Multiple Instances, Next:X Warnings, Previous:Inferior Debugger Options, Up:Invoking

Multiple DDD Instances

If you have multiple DDD instances running, they share common preferences and history files. This means that changes applied to one instance may get lost when being overwritten by the other instance. DDD has two means to protect you against unwanted losses. The first means is an automatic reloading of changed options, controlled by the following resource (see Customizing):

checkOptions (class CheckOptions) Resource
Every n seconds, where n is the value of this resource, DDD checks whether the options file has changed. Default is 30, which means that every 30 seconds, DDD checks for the options file. Setting this resource to 0 disables checking for changed option files.

Normally, automatic reloading of options should already suffice. If you need stronger protection, DDD also provides a warning against multiple instances. This warning is disabled by default, If you want to be warned about multiple DDD invocations sharing the same preferences and history files, enable Edit => Preferences => Warn if Multiple DDD Instances are Running.

This setting is tied to the following resource (see Customizing):

warnIfLocked (class WarnIfLocked) Resource
Whether to warn if multiple DDD instances are running (on) or not (off, default).

Node:X Warnings, Previous:Multiple Instances, Up:Invoking

X warnings

If you are bothered by X warnings, you can suppress them by setting Edit => Preferences => General => Suppress X warnings.

This setting is tied to the following resource (see Customizing):

suppressWarnings (class SuppressWarnings) Resource
If on, X warnings are suppressed. This is sometimes useful for executables that were built on a machine with a different X or Motif configuration. By default, this is off.

Node:Quitting, Next:Sessions, Previous:Invoking, Up:Invocation

Quitting DDD

To exit DDD, select File => Exit. You may also type the quit command at the debugger prompt or press <Ctrl+Q>. GDB and XDB also accept the q command or an end-of-file character (usually <Ctrl+D>). Closing the last DDD window will also exit DDD.

An interrupt (<ESC> or Interrupt) does not exit from DDD, but rather terminates the action of any debugger command that is in progress and returns to the debugger command level. It is safe to type the interrupt character at any time because the debugger does not allow it to take effect until a time when it is safe.

In case an ordinary interrupt does not succeed, you can also use an abort (<Ctrl+\> or Abort), which sends a SIGABRT signal to the inferior debugger. Use this in emergencies only; the inferior debugger may be left inconsistent or even exit after a SIGABRT signal.

As a last resort (if DDD hangs, for example), you may also interrupt DDD itself using an interrupt signal (SIGINT). This can be done by typing the interrupt character (usually <Ctrl+C>) in the shell DDD was started from, or by using the UNIX kill command. An interrupt signal interrupts any DDD action; the inferior debugger is interrupted as well. Since this interrupt signal can result in internal inconsistencies, use this as a last resort in emergencies only; save your work as soon as possible and restart DDD.

Node:Sessions, Next:Remote Debugging, Previous:Quitting, Up:Invocation

Persistent Sessions

If you want to interrupt your current DDD session, you can save the entire the entire DDD state as session on disk and resume later.

  • Saving Sessions:
  • Resuming Sessions:
  • Deleting Sessions:
  • Customizing Sessions:

Node:Saving Sessions, Next:Resuming Sessions, Up:Sessions

Saving Sessions

To save a session, select File => Save Session As. You will be asked for a symbolic session name session.

If your program is running (see Running), or if you have opened a core file (see Opening Core Dumps), DDD can also include a core file in the session such that the debuggee data will be restored when re-opening it. To get a core file, DDD typically must kill the debuggee. This means that you cannot resume program execution after saving a session. Depending on your architecture, other options for getting a core file may also be available.

Including a core dump is necessary for restoring memory contents and the current execution position. To include a core dump, enable Include Core Dump.

After clicking on Save, the session is saved in ~/.ddd/sessions/session.

Here's a list of the items whose state is saved in a session:

  • The state of the debugged program, as a core file.5
  • All breakpoints and watchpoints (see Stopping).
  • All signal settings (see Signals).
  • All displays (see Displaying Values).6
  • All DDD options (see Saving Options).
  • All debugger settings (see Debugger Settings).
  • All user-defined buttons (see Defining Buttons).
  • All user-defined commands (see Defining Commands).
  • The positions and sizes of DDD windows.
  • The command history (see Command History).

After saving the current state as a session, the session becomes active. This means that DDD state will be saved as session defaults:

  • User options will be saved in ~/.ddd/sessions/session/init instead of ~/.ddd/init. See Saving Options, for details.
  • The DDD command history will be saved in ~/.ddd/sessions/session/history instead of ~/.ddd/history. See Command History, for details.

To make the current session inactive, open the default session named [None]. See Resuming Sessions, for details on opening sessions.

Node:Resuming Sessions, Next:Deleting Sessions, Previous:Saving Sessions, Up:Sessions

Resuming Sessions

To resume a previously saved session, select File => Open Session and choose a session name from the list. After clicking on Open, the entire DDD state will be restored from the given session.

The session named [None] is the default session which is active when starting DDD. To save options for default sessions, open the default session and save options. See Saving Options, for details.

If a the restored session includes a core dump, the program being debugged will be in the same state at the time the session was saved; in particular, you can examine the program data. However, you will not be able to resume program execution since the process and its environment (open files, resources, etc.) no longer exist. However, you can restart the program, re-using the restored breakpoints and data displays.

Opening sessions also restores command definitions, buttons, display shortcuts and the source tab width. This way, you can maintain a different set of definitions for each session.

You can also specify a session to open when starting DDD. To invoke DDD with a session session, use

ddd --session session

There is also a shortcut that opens the session session and invokes the inferior debugger on an executable named session (in case session cannot be opened):

ddd =session

There is no need to give further command-line options when restarting a session, as they will be overridden by the options saved in the session.

You can also use an X session manager such as xsm to save and restore DDD sessions.7 When being shut down by a session manager, DDD saves its state under the name specified by the session manager; resuming the X session makes DDD reload its saved state.

Node:Deleting Sessions, Next:Customizing Sessions, Previous:Resuming Sessions, Up:Sessions

Deleting Sessions

To delete sessions that are no longer needed, select File => Open Session or File => Save Session. Select the sessions you want to delete and click on Delete.

The default session [None] cannot be deleted.

Node:Customizing Sessions, Previous:Deleting Sessions, Up:Sessions

Customizing Sessions

You can change the place where DDD saves its sessions by setting the environment variable DDD_SESSIONS to the name of a directory. Default is ~/.ddd/sessions/.

Where applicable, DDD supports a gcore command to obtain core files of the running program. You can enter its path via Edit => Preferences => Helpers => Get Core File. Leave the value empty if you have no gcore or similar command.

This setting is tied to the following resource (see Customizing):

getCoreCommand (class GetCoreCommand) Resource
A command to get a core dump of a running process (typically, gcore) @FILE@ is replaced by the base name of the file to create; @PID@ is replaced by the process id. The output must be written to @FILE@.@PID@.

Leave the value empty if you have no gcore or similar command.

Node:Remote Debugging, Next:Customizing Debugger Interaction, Previous:Sessions, Up:Invocation

Remote Debugging

You can have each of DDD, the inferior debugger, and the debugged program run on different machines.

  • Remote Host: Running DDD on a Remote Host
  • Remote Debugger: Using a Remote Inferior Debugger
  • Remote Program: Debugging a Remote Program

Node:Remote Host, Next:Remote Debugger, Up:Remote Debugging

Running DDD on a Remote Host

You can run DDD on a remote host, using your current host as X display. On the remote host, invoke DDD as

ddd -display display

where display is the name of the X server to connect to (for instance, hostname:0.0, where hostname is your host).

Instead of specifying -display display, you can also set the DISPLAY environment variable to display.

Node:Remote Debugger, Next:Remote Program, Previous:Remote Host, Up:Remote Debugging

Using DDD with a Remote Inferior Debugger

In order to run the inferior debugger on a remote host, you need remsh (called rsh on BSD systems) access on the remote host.

To run the debugger on a remote host hostname, invoke DDD as

ddd --host hostname remote-program

If your remote username differs from the local username, use

ddd --host hostname --login username remote-program

or

ddd --host username@hostname remote-program

instead.

There are a few caveats in remote mode:

  • The remote debugger is started in your remote home directory. Hence, you must specify an absolute path name for remote-program (or a path name relative to your remote home directory). Same applies to remote core files. Also, be sure to specify a remote process id when debugging a running program.
  • The remote debugger is started non-interactively. Some DBX versions have trouble with this. If you do not get a prompt from the remote debugger, use the --rhost option instead of --host. This will invoke the remote debugger via an interactive shell on the remote host, which may lead to better results.

    Note: using --rhost, DDD invokes the inferior debugger as soon as a shell prompt appears. The first output on the remote host ending in a space character or > and not followed by a newline is assumed to be a shell prompt. If necessary, adjust your shell prompt on the remote host.

  • To run the remote program, DDD invokes an xterm terminal emulator on the remote host, giving your current DISPLAY environment variable as address. If the remote host cannot invoke xterm, or does not have access to your X display, start DDD with the --no-exec-window option. The program input/output will then go through the DDD debugger console.
  • In remote mode, all sources are loaded from the remote host; file dialogs scan remote directories. This may result in somewhat slower operation than normal.
  • To help you find problems due to remote execution, run DDD with the --trace option. This prints the shell commands issued by DDD on standard error.

See Customizing Remote Debugging, for customizing remote mode.

  • Customizing Remote Debugging:

Node:Customizing Remote Debugging, Up:Remote Debugger

Customizing Remote Debugging

When having the inferior debugger run on a remote host (see Remote Debugging), all commands to access the inferior debugger as well as its files must be run remotely. This is controlled by the following resources (see Customizing):

rshCommand (class RshCommand) Resource
The remote shell command to invoke TTY-based commands on remote hosts. Usually, remsh, rsh, ssh, or on.

listCoreCommand (class listCoreCommand) Resource
The command to list all core files on the remote host. The string @MASK@ is replaced by a file filter. The default setting is:
Ddd*listCoreCommand: \
file @MASK@ | grep '.*:.*core.*' | cut -d: -f1

listDirCommand (class listDirCommand) Resource
The command to list all directories on the remote host. The string @MASK@ is replaced by a file filter. The default setting is:
Ddd*listDirCommand: \
file @MASK@ | grep '.*:.*directory.*' | cut -d: -f1

listExecCommand (class listExecCommand) Resource
The command to list all executable files on the remote host. The string @MASK@ is replaced by a file filter. The default setting is:
Ddd*listExecCommand: \
file @MASK@ | grep '.*:.*exec.*' \
  | grep -v  '.*:.*script.*' \
  | cut -d: -f1 | grep -v '.*\.o$'

listSourceCommand (class listSourceCommand) Resource
The command to list all source files on the remote host. The string @MASK@ is replaced by a file filter. The default setting is:
Ddd*listSourceCommand: \
file @MASK@ | grep '.*:.*text.*' | cut -d: -f1

Node:Remote Program, Previous:Remote Debugger, Up:Remote Debugging

Debugging a Remote Program

The GDB debugger allows you to run the debugged program on a remote machine (called remote target), while GDB runs on the local machine.

See Remote, for details. Basically, the following steps are required:

  • Transfer the executable to the remote target.
  • Start gdbserver on the remote target.
  • Start DDD using GDB on the local machine, and load the same executable using the GDB file command.
  • Attach to the remote gdbserver using the GDB target remote command.

The local .gdbinit file is useful for setting up directory search paths, etc.

Of course, you can also combine DDD remote mode and GDB remote mode, running DDD, GDB, and the debugged program each on a different machine.

Node:Customizing Debugger Interaction, Previous:Remote Debugging, Up:Invocation

Customizing Interaction with the Inferior Debugger

These settings control the interaction of DDD with its inferior debugger.

  • Debugger Invocation:
  • Debugger Initialization:
  • Debugger Communication:

Node:Debugger Invocation, Next:Debugger Initialization, Up:Customizing Debugger Interaction

Invoking an Inferior Debugger

To choose the default inferior debugger, select Edit => Preferences => Startup => Debugger Type. You can

  • have DDD determine the appropriate inferior debugger automatically from its command-line arguments. Set Determine Automatically from Arguments to enable.
  • have DDD start the debugger of your choice, as specified in Debugger Type.

The following DDD resources control the invocation of the inferior debugger (see Customizing).

autoDebugger (class AutoDebugger) Resource
If this is on (default), DDD will attempt to determine the debugger type from its arguments, possibly overriding the debugger resource (see below). If this is off, DDD will invoke the debugger specified by the debugger resource regardless of DDD arguments.

debugger (class Debugger) Resource
The type of the inferior debugger to invoke (gdb, dbx, ladebug, xdb, jdb, pydb, or perl).

This resource is usually set through the --gdb, --dbx, --ladebug, --xdb, --jdb, --pydb, and --perl, options; See Options, for details.

debuggerCommand (class DebuggerCommand) Resource
The name under which the inferior debugger is to be invoked. If this string is empty (default), the debugger type (debugger resource) is used.

This resource is usually set through the --debugger option; See Options, for details.

Node:Debugger Initialization, Next:Debugger Communication, Previous:Debugger Invocation, Up:Customizing Debugger Interaction

Initializing the Inferior Debugger

DDD uses a number of resources to initialize the inferior debugger (see Customizing).

  • GDB Initialization:
  • DBX Initialization:
  • XDB Initialization:
  • JDB Initialization:
  • PYDB Initialization:
  • Perl Initialization:
  • Opening the Selection:

Node:GDB Initialization, Next:DBX Initialization, Up:Debugger Initialization

GDB Initialization

gdbInitCommands (class InitCommands) Resource
This string contains a list of newline-separated commands that are initially sent to GDB. As a side-effect, all settings specified in this resource are considered fixed and cannot be changed through the GDB settings panel, unless preceded by white space. By default, the gdbInitCommands resource contains some settings vital to DDD:
  Ddd*gdbInitCommands: \
  set height 0\n\
  set width 0\n\
   set verbose off\n\
  set prompt (gdb) \n

While the set height, set width, and set prompt settings are fixed, the set verbose settings can be changed through the GDB settings panel (although being reset upon each new DDD invocation).

Do not use this resource to customize GDB; instead, use a personal ~/.gdbinit file. See your GDB documentation for details.

gdbSettings (class Settings) Resource
This string contains a list of newline-separated commands that are also initially sent to GDB. Its default value is
  Ddd*gdbSettings: \
  set print asm-demangle on\n

This resource is used to save and restore the debugger settings.

sourceInitCommands (class SourceInitCommands) Resource
If on (default), DDD writes all GDB initialization commands into a temporary file and makes GDB read this file, rather than sending each initialization command separately. This results in faster startup (especially if you have several user-defined commands). If off, DDD makes GDB process each command separately.

Node:DBX Initialization, Next:XDB Initialization, Previous:GDB Initialization, Up:Debugger Initialization

DBX Initialization

dbxInitCommands (class InitCommands) Resource
This string contains a list of newline-separated commands that are initially sent to DBX. By default, it is empty.

Do not use this resource to customize DBX; instead, use a personal ~/.dbxinit or ~/.dbxrc file. See your DBX documentation for details.

dbxSettings (class Settings) Resource
This string contains a list of newline-separated commands that are also initially sent to DBX. By default, it is empty.

Node:XDB Initialization, Next:JDB Initialization, Previous:DBX Initialization, Up:Debugger Initialization

XDB Initialization

xdbInitCommands (class InitCommands) Resource
This string contains a list of newline-separated commands that are initially sent to XDB. By default, it is empty.

Do not use this resource to customize DBX; instead, use a personal ~/.xdbrc file. See your XDB documentation for details.

xdbSettings (class Settings) Resource
This string contains a list of newline-separated commands that are also initially sent to XDB. By default, it is empty.

Node:JDB Initialization, Next:PYDB Initialization, Previous:XDB Initialization, Up:Debugger Initialization

JDB Initialization

jdbInitCommands (class InitCommands) Resource
This string contains a list of newline-separated commands that are initially sent to JDB. This resource may be used to customize JDB. By default, it is empty.

jdbSettings (class Settings) Resource
This string contains a list of newline-separated commands that are also initially sent to JDB. By default, it is empty.

This resource is used by DDD to save and restore JDB settings.

Node:PYDB Initialization, Next:Perl Initialization, Previous:JDB Initialization, Up:Debugger Initialization

PYDB Initialization

pydbInitCommands (class InitCommands) Resource
This string contains a list of newline-separated commands that are initially sent to PYDB. By default, it is empty.

This resource may be used to customize PYDB.

pydbSettings (class Settings) Resource
This string contains a list of newline-separated commands that are also initially sent to PYDB. By default, it is empty.

This resource is used by DDD to save and restore PYDB settings.

Node:Perl Initialization, Next:Opening the Selection, Previous:PYDB Initialization, Up:Debugger Initialization

Perl Initialization

perlInitCommands (class InitCommands) Resource
This string contains a list of newline-separated commands that are initially sent to the Perl debugger. By default, it is empty.

This resource may be used to customize the Perl debugger.

perlSettings (class Settings) Resource
This string contains a list of newline-separated commands that are also initially sent to the Perl debugger. By default, it is empty.

This resource is used by DDD to save and restore Perl debugger settings.

Node:Opening the Selection, Previous:Perl Initialization, Up:Debugger Initialization

Opening the Selection

openSelection (class OpenSelection) Resource
If this is on, DDD invoked without argument checks whether the current selection or clipboard contains the file name or URL of an executable program. If this is so, DDD will automatically open this program for debugging. If this resource is off (default), DDD invoked without arguments will always start without a debugged program.

Node:Debugger Communication, Previous:Debugger Initialization, Up:Customizing Debugger Interaction

Communication with the Inferior Debugger

The following resources control the communication with the inferior debugger.

blockTTYInput (class BlockTTYInput) Resource
Whether DDD should block when reading data from the inferior debugger via the pseudo-tty interface. Most UNIX systems except GNU/Linux require this; set it to on. On GNU/Linux, set it to off. The value auto (default) will always select the "best" choice (that is, the best choice known to the DDD developers).

displayTimeout (class DisplayTimeout) Resource
The time (in ms) to wait for the inferior debugger to finish a partial display information. Default is 2000.

positionTimeout (class PositionTimeout) Resource
The time (in ms) to wait for the inferior debugger to finish a partial position information. Default is 500.

questionTimeout (class QuestionTimeout) Resource
The time (in seconds) to wait for the inferior debugger to reply. Default is 10.

synchronousDebugger (class SynchronousDebugger) Resource
If on, X events are not processed while the debugger is busy. This may result in slightly better performance on single-processor systems. See Options, for the --sync-debugger option.

terminateOnEOF (class TerminateOnEOF) Resource
If on, DDD terminates the inferior debugger when DDD detects an EOF condition (that is, as soon as the inferior debugger closes its output channel). This was the default behavior in DDD 2.x and earlier. If off (default), DDD takes no special action.

useTTYCommand (class UseTTYCommand) Resource
If on, use the GDB tty command for redirecting input/output to the separate execution window. If off, use explicit redirection through shell redirection operators < and >. The default is off (explicit redirection), since on some systems, the tty command does not work properly on some GDB versions.

Node:Windows, Next:Navigating, Previous:Invocation, Up:Top

The DDD Windows

DDD is composed of three main windows. From top to bottom, we have:

  • The Data Window shows the current data of the debugged program. See Displaying Values, for details.
  • The Source Window shows the current source code of the debugged program. See Navigating, for details.
  • The Debugger Console accepts debugger commands and shows debugger messages. See Commands, for details.

Besides these three main windows, there are some other optional windows:

  • The Command Tool offers buttons for frequently used commands. It is usually placed on the source window. See Command Tool, for details.
  • The Machine Code Window shows the current machine code. It is usually placed beneath the current source. See Machine Code, for details.
  • The Execution Window shows the input and output of the debugged program. See Using the Execution Window, for details.
  • Menu Bar: All DDD pull-down menus.
  • Tool Bar: The DDD icon buttons.
  • Command Tool: The floating command tool.
  • Getting Help: What does this thing mean?
  • Undo and Redo: Oops!
  • Customizing: You can customize DDD

Node:Menu Bar, Next:Tool Bar, Up:Windows

The Menu Bar

The DDD Menu Bar gives you access to all DDD functions.

File
Perform file-related operations such as selecting programs, processes, and sessions, printing graphs, recompiling, as well as exiting DDD.
Edit
Perform standard editing operations, such as cutting, copying, pasting, and killing selected text. Also allows editing DDD options and preferences.
View
Allows accessing the individual DDD windows.
Program
Perform operations related to the program being debugged, such as starting and stopping the program.
Commands
Perform operations related to DDD commands, such as accessing the command history or defining new commands.
Status
Examine the program status, such as the stack traces, registers, or threads.
Source
Perform source-related operations such as looking up items or editing breakpoints.
Data
Perform data-related operations such as editing displays or layouting the display graph.
Maintenance
Perform operations that are useful for debugging DDD. By default, this menu is disabled.
Help
Give help on DDD usage.

There are two ways of selecting an item from a pull-down menu:

  • Select an item in the menu bar by moving the cursor over it and click mouse button 1. Then move the cursor over the menu item you want to choose and click left again.
  • Select an item in the menu bar by moving the cursor over it and click and hold mouse button 1. With the mouse button depressed, move the cursor over the menu item you want, then release it to make your selection.

The menus can also be torn off (i.e. turned into a persistent window) by selecting the dashed line at the top.

If a command in the pull-down menu is not applicable in a given situation, the command is disabled and its name appears faded. You cannot invoke items that are faded. For example, many commands on the Edit menu appear faded until you select text on which they are to operate; after you select a block of text, edit commands are enabled.

  • File Menu: Selecting programs and processes.
  • Edit Menu: Cut, copy, paste, and preferences.
  • View Menu: All DDD windows.
  • Program Menu: Starting and stopping.
  • Commands Menu: All DDD commands.
  • Status Menu: Examining the program status.
  • Source Menu: Navigating around.
  • Data Menu: Examining data.
  • Maintenance Menu: Maintaining DDD.
  • Help Menu: Getting help.
  • Customizing the Menu Bar: Alternate key bindings, etc.

Node:File Menu, Next:Edit Menu, Up:Menu Bar

The File Menu

The File menu contains file-related operations such as selecting programs, processes, and sessions, printing graphs, recompiling, as well as exiting DDD.

Open Program
Open Class
Open a program or class to be debugged. See Opening Programs, for details.
Open Recent
Re-open a recently opened program to be debugged. See Opening Programs, for details.
Open Core Dump
Open a core dump for the currently debugged program. See Opening Core Dumps, for details.
Open Source
Open a source file of the currently debugged program. See Opening Source Files, for details.
Open Session
Resume a previously saved DDD session. See Resuming Sessions, for details.
Save Session As
Save the current DDD session such that you can resume it later. See Saving Sessions, for details.
Attach to Process
Attach to a running process of the debugged program. See Attaching to a Process, for details.
Detach Process
Detach from the running process. See Attaching to a Process, for details.
Print Graph
Print the current graph on a printer. See Printing the Graph, for details.
Change Directory
Change the working directory of your program. See Working Directory, for details.
Make
Run the make program. See Recompiling, for details.
Close
Close this DDD window.
Restart
Restart DDD.
Exit
Exit DDD.

Node:Edit Menu, Next:View Menu, Previous:File Menu, Up:Menu Bar

The Edit Menu

The Edit menu contains standard editing operations, such as cutting, copying, pasting, and killing selected text. Also allows editing DDD options and preferences.

Undo
Undo the most recent action. Almost all commands can be undone this way. See Undo and Redo, for details.
Redo
Redo the action most recently undone. Every command undone can be redone this way. See Undo and Redo, for details.
Cut
Removes the selected text block from the current text area and makes it the X clipboard selection. Before executing this command, you have to select a region in a text area--either with the mouse or with the usual text selection keys.

This item can also be applied to displays (see Deleting Displays).

Copy
Makes a selected text block the X clipboard selection. You can select text by selecting a text region with the usual text selection keys or with the mouse. See Customizing the Edit Menu, for changing the default accelerator.

This item can also be applied to displays (see Deleting Displays).

Paste
Inserts the current value of the X clipboard selection in the most recently selected text area. You can paste in text you have placed in the clipboard using Copy or Cut. You can also use Paste to insert text that was pasted into the clipboard from other applications.
Clear
Clears the most recently selected text area.
Delete
Removes the selected text block from the most recently selected text area, but does not make it the X clipboard selection.

This item can also be applied to displays (see Deleting Displays).

Select All
Selects all characters from the most recently selected text area. See Customizing the Edit Menu, for changing the default accelerator.
Preferences
Allows you to customize DDD interactively. See Customizing, for details.
Debugger Settings
Allows you to customize the inferior debugger. See Debugger Settings, for details.
Save Options
Saves all preferences and settings for the next DDD invocation. See Saving Options, for details.

Node:View Menu, Next:Program Menu, Previous:Edit Menu, Up:Menu Bar

The View Menu

The View menu allows accessing the individual DDD windows.

Command Tool
Open and recenter the command tool. See Command Tool, for details.
Execution Window
Open the separate execution window. See Using the Execution Window, for details.
Debugger Console
Open the debugger console. See Commands, for details.
Source Window
Open the source window. See Navigating, for details.
Data Window
Open the data window. See Displaying Values, for details.
Machine Code Window
Show machine code. See Machine Code, for details.

Node:Program Menu, Next:Commands Menu, Previous:View Menu, Up:Menu Bar

The Program Menu

The Program menu performs operations related to the program being debugged, such as starting and stopping the program.

Most of these operations are also found on the command tool (see Command Tool).

Run
Start program execution, prompting for program arguments. See Starting Program Execution, for details.
Run Again
Start program execution with the most recently used arguments. See Starting Program Execution, for details.
Run in Execution Window
If enabled, start next program execution in separate execution window. See Using the Execution Window, for details.
Step
Continue running your program until control reaches a different source line, then stop it and return control to DDD. See Resuming Execution, for details.
Step Instruction
Execute one machine instruction, then stop and return to DDD. See Machine Code Execution, for details.
Next
Continue to the next source line in the current (innermost) stack frame. This is similar to Step, but function calls that appear within the line of code are executed without stopping. See Resuming Execution, for details.
Next Instruction
Execute one machine instruction, but if it is a function call, proceed until the function returns. See Machine Code Execution, for details.
Until
Continue running until a source line past the current line, in the current stack frame, is reached. See Resuming Execution, for details.
Finish
Continue running until just after function in the selected stack frame returns. Print the returned value (if any). See Resuming Execution, for details.
Continue
Resume program execution, at the address where your program last stopped; any breakpoints set at that address are bypassed. See Resuming Execution, for details.
Continue Without Signal
Continue execution without giving a signal. This is useful when your program stopped on account of a signal and would ordinary see the signal when resumed with Continue. See Signals, for details.
Kill
Kill the process of the debugged program. See Killing the Program, for details.
Interrupt
Interrupt program execution. This is equivalent to sending an interrupt signal to the process. See Interrupting, for details.
Abort
Abort program execution (and maybe debugger execution, too). This is equivalent to sending a SIGABRT signal to the process. See Quitting, for details.

Node:Commands Menu, Next:Status Menu, Previous:Program Menu, Up:Menu Bar

The Commands Menu

The Commands menu performs operations related to DDD commands, such as accessing the command history or defining new commands.

Most of these items are not meant to be actually executed via the menu; instead, they serve as reminder for the equivalent keyboard commands.

Command History
View the command history. See Command History, for details.
Previous
Show the previous command from the command history. See Command History, for details.
Next
Show the next command from the command history. See Command History, for details.
Find Backward
Do an incremental search backward through the command history. See Command History, for details.
Find Forward
Do an incremental search forward through the command history. See Command History, for details.
Quit Search
Quit incremental search through the command history. See Command History, for details.
Complete
Complete the current command in the debugger console. See Entering Commands, for details.
Apply
Apply the current command in the debugger console. See Entering Commands, for details.
Clear Line
Clear the current command line in the debugger console. See Entering Commands, for details.
Clear Window
Clear the debugger console. See Entering Commands, for details.
Define Command
Define a new debugger command. See Defining Commands, for details.
Edit Buttons
Customize DDD buttons. See Defining Buttons, for details.

Node:Status Menu, Next:Source Menu, Previous:Commands Menu, Up:Menu Bar

The Status Menu

The Status menu lets you examine the program status, such as the stack traces, registers, or threads.

Backtrace
View the current backtrace. See Backtraces, for a discussion.
Registers
View the current register contents. See Registers, for details.
Threads
View the current threads. See Threads, for details.
Signals
View and edit the current signal handling. See Signals, for details.
Up
Select the stack frame (i.e. the function) that called this one. This advances toward the outermost frame, to higher frame numbers, to frames that have existed longer. See Stack, for details.
Down
Select the stack frame (i.e. the function) that was called by this one. This advances toward the innermost frame, to lower frame numbers, to frames that were created more recently. See Stack, for details.

Node:Source Menu, Next:Data Menu, Previous:Status Menu, Up:Menu Bar

The Source Menu

The Source menu performs source-related operations such as looking up items or editing breakpoints.

Breakpoints
Edit all Breakpoints. See Editing all Breakpoints, for details.
Lookup ()
Look up the argument () in the source code. See Looking up Definitions, for details.
Find >> ()
Look up the next occurrence of the argument () in the current source code. See Textual Search, for details.
Find << ()
Look up the previous occurrence of the argument () in the current source code. See Textual Search, for details.
Find Words Only
If enabled, find only complete words. See Textual Search, for details.
Find Case Sensitive
If enabled, find is case-sensitive. See Textual Search, for details.
Display Line Numbers
If enabled, prefix source lines with their line number. See Customizing Source, for details.
Display Machine Code
If enabled, show machine code. See Machine Code, for details.
Edit Source
Invoke an editor for the current source file. See Editing Source Code, for details.
Reload Source
Reload the current source file. See Editing Source Code, for details.

Node:Data Menu, Next:Maintenance Menu, Previous:Source Menu, Up:Menu Bar

The Data Menu

The Data menu performs data-related operations such as editing displays or layouting the display graph.

Displays
Invoke the Display Editor. See Editing all Displays, for details.
Watchpoints
Edit all Watchpoints. See Editing all Watchpoints, for details.
Memory
View a memory dump. See Examining Memory, for details.
Print ()
Print the value of () in the debugger console. See Printing Values, for details.
Display ()
Display the value of () in the data window. See Displaying Values, for details.
Detect Aliases
If enabled, detect shared data structures. See Shared Structures, for a discussion.
Display Local Variables
Show all local variables in a display. See Displaying Local Variables, for details.
Display Arguments
Show all arguments of the current function in a display. See Displaying Local Variables, for details.
Status Displays
Show current debugging information in a display. See Displaying Program Status, for details.
Align on Grid
Align all displays on the grid. See Aligning Displays, for a discussion.
Rotate Graph
Rotate the graph by 90 degrees. See Rotating the Graph, for details.
Layout Graph
Layout the graph. See Layouting the Graph, for details.
Refresh
Update all values in the data window. See Refreshing the Data Window, for details.

Node:Maintenance Menu, Next:Help Menu, Previous:Data Menu, Up:Menu Bar

The Maintenance Menu

The Maintenance menu performs operations that are useful for debugging DDD.

By default, this menu is disabled; it is enabled by specifically requesting it at DDD invocation (via the --maintenance option; see Options). It is also enabled when DDD gets a fatal signal.

Debug DDD
Invoke a debugger (typically, GDB) and attach it to this DDD process. This is useful only if you are a DDD maintainer.
Dump Core Now
Make this DDD process dump core. This can also be achieved by sending DDD a SIGUSR1 signal.
Tic Tac Toe
Invoke a Tic Tac Toe game. You must try to get three stop signs in a row, while preventing DDD from doing so with its skulls. Click on New Game to restart.
When DDD Crashes
Select what to do when DDD gets a fatal signal.
Debug DDD
Invoke a debugger on the DDD core dump when DDD crashes. This is useful only if you are a DDD maintainer.
Dump Core
Just dump core when DDD crashes; don't invoke a debugger. This is the default setting, as the core dump may contain important information required for debugging DDD.
Do Nothing
Do not dump core or invoke a debugger when DDD crashes.

Remove Menu
Make this menu inaccessible again.

Node:Help Menu, Next:Customizing the Menu Bar, Previous:Maintenance Menu, Up:Menu Bar

The Help Menu

The Help menu gives help on DDD usage. See Getting Help, for a discussion on how to get help within DDD.

Overview
Explains the most important concepts of DDD help.
On Item
Lets you click on an item to get help on it.
On Window
Gives you help on this DDD window.
What Now?
Gives a hint on what to do next.
Tip of the Day
Shows the current tip of the day.
DDD Reference
Shows the DDD Manual.
DDD News
Shows what's new in this DDD release.
Debugger Reference
Shows the on-line documentation for the inferior debugger.
DDD License
Shows the DDD License (see License).
DDD WWW Page
Invokes a WWW browser for the DDD WWW page.
About DDD
Shows version and copyright information.

Node:Customizing the Menu Bar, Previous:Help Menu, Up:Menu Bar

Customizing the Menu Bar

The Menu Bar can be customized in various ways (see Customizing).

  • Auto-Raise Menus:
  • Customizing the Edit Menu:

Node:Auto-Raise Menus, Next:Customizing the Edit Menu, Up:Customizing the Menu Bar

Auto-Raise Menus

You can cause pull-down menus to be raised automatically.

autoRaiseMenu (class AutoRaiseMenu) Resource
If on (default), DDD will always keep the pull down menu on top of the DDD main window. If this setting interferes with your window manager, or if your window manager does not auto-raise windows, set this resource to off.

autoRaiseMenuDelay (class AutoRaiseMenuDelay) Resource
The time (in ms) during which an initial auto-raised window blocks further auto-raises. This is done to prevent two overlapping auto-raised windows from entering an auto-raise loop. Default is 100.

Node:Customizing the Edit Menu, Previous:Auto-Raise Menus, Up:Customizing the Menu Bar

Customizing the Edit Menu

In the Menu Bar, the Edit Menu can be customized in various ways. Use Edit => Preferences => Startup to customize these keys.

The <Ctrl+C> key can be bound to different actions, each in accordance with a specific style guide.

Copy
This setting binds <Ctrl+C> to the Copy operation, as specified by the KDE style guide. In this setting, use <ESC> to interrupt the debuggee.
Interrupt
This (default) setting binds <Ctrl+C> to the Interrupt operation, as used in several UNIX command-line programs. In this setting, use <Ctrl+Ins> to copy text to the clipboard.

The <Ctrl+A> key can be bound to different actions, too.

Select All
This (default) setting binds <Ctrl+A> to the Select All operation, as specified by the KDE style guide. In this setting, use <Home> to move the cursor to the beginning of a line.
Beginning of Line
This setting binds <Ctrl+A> to the Beginning of Line operation, as used in several UNIX text-editing programs. In this setting, use <Ctrl+Shift+A> to select all text.

Here are the related DDD resources:

cutCopyPasteBindings (class BindingStyle) Resource
Controls the key bindings for clipboard operations.
  • If this is Motif (default), Cut/Copy/Paste is on <Shift+Del>/<Ctrl+Ins>/<Shift+Ins>. This is conformant to the Motif style guide.
  • If this is KDE, Cut/Copy/Paste is on <Ctrl+X>/<Ctrl+C>/<Ctrl+V>. This is conformant to the KDE style guide. Note that this means that <Ctrl+C> no longer interrupts the debuggee; use <ESC> instead.

selectAllBindings (class BindingStyle) Resource
Controls the key bindings for the Select All operation.
  • If this is Motif, Select All is on <Shift+Ctrl+A>.
  • If this is KDE (default), Select All is on <Ctrl+A>. This is conformant to the KDE style guide. Note that this means that <Ctrl+A> no longer moves the cursor to the beginning of a line; use <Home> instead.

Node:Tool Bar, Next:Command Tool, Previous:Menu Bar, Up:Windows

The Tool Bar

Some DDD commands require an argument. This argument is specified in the argument field, labeled ():. Basically, there are four ways to set arguments:

  • You can key in the argument manually.
  • You can paste the current selection into the argument field (typically using mouse button 2). To clear old contents beforehand, click on the (): label.
  • You can select an item from the source and data windows. This will automatically copy the item to the argument field.
  • You can select a previously used argument from the drop-down menu at the right of the argument field.

Using GDB and Perl, the argument field provides a completion mechanism. You can enter the first few characters of an item an press the <TAB> key to complete it. Pressing <TAB> again shows alternative completions.

After having entered an argument, you can select one of the buttons on the right. Most of these buttons also have menus associated with them; this is indicated by a small arrow in the upper right corner. Pressing and holding mouse button 1 on such a button will pop up a menu with further operations.

These are the buttons of the tool bar. Note that not all buttons may be inactive, depending on the current state and the capabilities of the inferior debugger.

Lookup

Look up the argument () in the source code. See Looking up Definitions, for details.

Find >>

Look up the next occurrence of the argument () in the current source code. See Textual Search, for details.

Break/Clear

Toggle a breakpoint (see Breakpoints) at the location ().

Break
If there is no breakpoint at (), then this button is labeled Break. Clicking on Break sets a breakpoint at the location (). See Setting Breakpoints, for details.
Clear
If there already is a breakpoint at (), then this button is labeled Clear. Clicking on Clear clears (deletes) the breakpoint at the location (). See Deleting Breakpoints, for details.

Watch/Unwatch

Toggle a watchpoint (see Watchpoints) on the expression ().

Watch
If () is not being watched, then this button is labeled Watch. Clicking on Watch creates a watchpoint on the expression (). See Setting Watchpoints, for details.
Unwatch
If () is being watched, then this button is labeled Unwatch. Clicking on Unwatch clears (deletes) the watchpoint on (). See Deleting Watchpoints, for details.

Print

Print the value of () in the debugger console. See Printing Values, for details.

Display

Display the value of () in the data window. See Displaying Values, for details.

Plot

Plot () in a plot window. See Plotting Values, for details.

Show/Hide

Toggle details of the selected display(s). See Showing and Hiding Details, for a discussion.

Rotate

Rotate the selected display(s). See Rotating Displays, for details.

Set

Set (change) the value of (). See Assignment, for details.

Undisp

Undisplay (delete) the selected display(s). See Deleting Displays, for details.

  • Customizing the Tool Bar:

Node:Customizing the Tool Bar, Up:Tool Bar

Customizing the Tool Bar

The DDD tool bar buttons can appear in a variety of styles, customized via Edit => Preferences => Startup.

Images
This lets each tool bar button show an image illustrating the action.
Captions
This shows the action name below the image.

The default is to have images as well as captions, but you can choose to have only images (saving space) or only captions.

If you choose to have neither images nor captions, tool bar buttons are labeled like other buttons, as in DDD 2.x. Note that this implies that in the stacked window configuration, the common tool bar cannot be displayed; it is replaced by two separate tool bars, as in DDD 2.x.

If you enable Flat buttons (default), the border of tool bar buttons will appear only if the mouse pointer is over them. This latest-and-greatest GUI invention can be disabled, such that the button border is always shown.

If you enable Color buttons, tool bar images will be colored when entered. If DDD was built using Motif 2.0 and later, you can also choose a third setting, where buttons appear in color all the time.

Here are the related resources (see Customizing):

activeButtonColorKey (class ColorKey) Resource
The XPM color key to use for the images of active buttons (entered or armed). c means color, g (default) means grey, and m means monochrome.

buttonCaptions (class ButtonCaptions) Resource
Whether the tool bar buttons should be shown using captions (on, default) or not (off). If neither captions nor images are enabled, tool bar buttons are shown using ordinary labels. See also buttonImages, below.

buttonCaptionGeometry (class ButtonCaptionGeometry) Resource
The geometry of the caption subimage within the button icons. Default is 29x7+0-0.

buttonImages (class ButtonImages) Resource
Whether the tool bar buttons should be shown using images (on, default) or not (off). If neither captions nor images are enabled, tool bar buttons are shown using ordinary labels. See also buttonCaptions, above.

buttonImageGeometry (class ButtonImageGeometry) Resource
The geometry of the image within the button icon. Default is 25x21+2+0.

buttonColorKey (class ColorKey) Resource
The XPM color key to use for the images of inactive buttons (non-entered or insensitive). c means color, g (default) means grey, and m means monochrome.

flatToolbarButtons (class FlatButtons) Resource
If on (default), all tool bar buttons with images or captions are given a `flat' appearance--the 3-D border only shows up when the pointer is over the icon. If off, the 3-D border is shown all the time.

flatDialogButtons (class FlatButtons) Resource
If on (default), all dialog buttons with images or captions are given a `flat' appearance--the 3-D border only shows up when the pointer is over the icon. If off, the 3-D border is shown all the time.

Node:Command Tool, Next:Getting Help, Previous:Tool Bar, Up:Windows

The Command Tool

The command tool is a small window that gives you access to the most frequently used DDD commands. It can be moved around on top of the DDD windows, but it can also be placed besides them.

By default, the command tool sticks to the DDD source window: Whenever you move the DDD source window, the command tool follows such that the distance between source window and command tool remains the same. By default, the command tool is also auto-raised, such that it stays on top of other DDD windows.

The command tool can be configured to appear as a command tool bar above the source window; see Edit => Preferences => Source => Tool Buttons Location for details.

Whenever you save DDD state, DDD also saves the distance between command tool and source window, such that you can select your own individual command tool placement. To move the command tool to its saved position, use View => Command Tool.

These are the buttons of the command tool. Note that not all buttons may be inactive, depending on the current state and the capabilities of the inferior debugger.

Run
Start program execution. When you click this button, your program will begin to execute immediately. See Starting Program Execution, for details.
Interrupt
Interrupt program execution. This is equivalent to sending an interrupt signal to the process. See Interrupting, for details.
Step
Continue running your program until control reaches a different source line, then stop it and return control to DDD. See Resuming Execution, for details.
Stepi
Execute one machine instruction, then stop and return to DDD. See Machine Code Execution, for details.
Next
Continue to the next source line in the current (innermost) stack frame. This is similar to Step, but function calls that appear within the line of code are executed without stopping. See Resuming Execution, for details.
Nexti
Execute one machine instruction, but if it is a function call, proceed until the function returns. See Machine Code Execution, for details.
Until
Continue running until a source line past the current line, in the current stack frame, is reached. See Resuming Execution, for details.
Finish
Continue running until just after function in the selected stack frame returns. Print the returned value (if any). See Resuming Execution, for details.
Cont
Resume program execution, at the address where your program last stopped; any breakpoints set at that address are bypassed. See Resuming Execution, for details.
Kill
Kill the process of the debugged program. See Killing the Program, for details.
Up
Select the stack frame (i.e. the function) that called this one. This advances toward the outermost frame, to higher frame numbers, to frames that have existed longer. See Stack, for details.
Down
Select the stack frame (i.e. the function) that was called by this one. This advances toward the innermost frame, to lower frame numbers, to frames that were created more recently. See Stack, for details.
Undo
Undo the most recent action. Almost all commands can be undone this way. See Undo and Redo, for details.
Redo
Redo the action most recently undone. Every command undone can be redone this way. See Undo and Redo, for details.
Edit
Invoke an editor for the current source file. See Editing Source Code, for details.
Make
Run the make program with the most recently given arguments. See Recompiling, for details.
  • Customizing the Command Tool:
  • Customizing Tool Position:

Node:Customizing the Command Tool, Next:Customizing Tool Position, Up:Command Tool

Customizing the Command Tool

The Command Tool can be customized in various ways.

  • Disabling the Command Tool:

See Customizing Buttons, for details on customizing the tool buttons.

Node:Disabling the Command Tool, Up:Customizing the Command Tool

Disabling the Command Tool

You can disable the command tool and show its buttons in a separate row beneath the tool bar. To disable the command tool, set Edit => Preferences => Source => Tool Buttons Location => Source Window.

Here's the related resource:

commandToolBar (class ToolBar) Resource
Whether the tool buttons should be shown in a tool bar above the source window (on) or within the command tool (off, default). Enabling the command tool bar disables the command tool and vice versa.

Node:Customizing Tool Position, Previous:Customizing the Command Tool, Up:Command Tool

Command Tool Position

The following resources control the position of the command tool (see Customizing):

autoRaiseTool (class AutoRaiseTool) Resource
If on (default), DDD will always keep the command tool on top of other DDD windows. If this setting interferes with your window manager, or if your window manager keeps the command tool on top anyway, set this resource to off.

stickyTool (class StickyTool) Resource
If on (default), the command tool automatically follows every movement of the source window. Whenever the source window is moved, the command tool is moved by the same offset such that its position relative to the source window remains unchanged. If off, the command tool does not follow source window movements.

toolRightOffset (class Offset) Resource
The distance between the right border of the command tool and the right border of the source text (in pixels). Default is 8.

toolTopOffset (class Offset) Resource
The distance between the upper border of the command tool and the upper border of the source text (in pixels). Default is 8.

  • Customizing Tool Decoration:

Node:Customizing Tool Decoration, Up:Customizing Tool Position

Customizing Tool Decoration

The following resources control the decoration of the command tool (see Customizing):

decorateTool (class Decorate) Resource
This resource controls the decoration of the command tool.
  • If this is off, the command tool is created as a transient window. Several window managers keep transient windows automatically on top of their parents, which is appropriate for the command tool. However, your window manager may be configured not to decorate transient windows, which means that you cannot easily move the command tool around.
  • If this is on, DDD realizes the command tool as a top-level window. Such windows are always decorated by the window manager. However, top-level windows are not automatically kept on top of other windows, such that you may wish to set the autoRaiseTool resource, too.
  • If this is auto (default), DDD checks whether the window manager decorates transients. If yes, the command tool is realized as a transient window (as in the off setting); if no, the command tool is realized as a top-level window (as in the on setting). Hence, the command tool is always decorated using the "best" method, but the extra check takes some time.

Node:Getting Help, Next:Undo and Redo, Previous:Command Tool, Up:Windows

Getting Help

DDD has an extensive on-line help system. Here's how to get help while working with DDD.

  • You can get a short help text on most DDD buttons by simply moving the mouse pointer on it and leave it there. After a second, a small window (called button tip; also known as tool tip or balloon help) pops up, giving a hint on the button's meaning. The button tip disappears as soon as you move the mouse pointer to another item.
  • The status line also displays information about the currently selected item. By clicking on the status line, you can redisplay the most recent messages.
  • You can get detailed help on any visible DDD item. Just point on the item you want help and press the F1 key. This pops up a detailed help text.
  • The DDD dialogs all contain Help buttons that give detailed information about the dialog.
  • You can get help on debugger commands by entering help at the debugger prompt. See Entering Commands, for details on entering commands.
  • If you are totally stuck, try Help => What Now? (the What Now? item in the Help menu) or press <Ctrl+F1>. Depending on the current state, DDD will give you some hints on what you can do next.
  • Of course, you can always refer to the on-line documentation:
    • Help => DDD Reference gives you access to the DDD manual, the ultimate DDD reference.
    • Help => Debugger Reference shows you the on-line documentation of the inferior debugger.
    • Help => DDD WWW Page gives you access to the latest and greatest information on DDD.
  • Finally, the DDD Tip Of The Day gives you important hints with each new DDD invocation.

All these functions can be customized in various ways (see Customizing Help).

If, after all, you made a mistake, don't worry: almost every DDD command can be undone. See Undo and Redo, for details.

Node:Undo and Redo, Next:Customizing, Previous:Getting Help, Up:Windows

Undoing and Redoing Commands

Almost every DDD command can be undone, using Edit => Undo or the Undo button on the command tool.

Likewise, Edit => Redo repeats the command most recently undone.

The Edit menu shows which commands are to be undone and redone next; this is also indicated by the popup help on the Undo and Redo buttons.

Node:Customizing, Previous:Undo and Redo, Up:Windows

Customizing DDD

DDD is controlled by several resources--user-defined variables that take specific values in order to control and customize DDD behavior.

Most DDD resources can be set interactively while DDD is running or when invoking DDD. See Resource Index, for the full list of DDD resources.

We first discuss how customizing works in general; then we turn to customizing parts of DDD introduced so far.

  • How Customizing Works:
  • Customizing Help:
  • Customizing Undo:
  • Customizing Windows:
  • Debugger Settings:

Node:How Customizing Works, Next:Customizing Help, Up:Customizing

How Customizing DDD Works

  • Resources:
  • Changing Resources:
  • Saving Options:

Node:Resources, Next:Changing Resources, Up:How Customizing Works

Resources

Just like any X program, DDD has a number of places to get resource values from. For DDD, the most important places to specify resources are:

  • The ~/.ddd/init file (~ stands for your home directory). This file is read in by DDD upon start-up; the resources specified herein override all other sources (except for resources given implicitly by command-line options).

    If the environment variable DDD_STATE is set, its value is used instead of ~/.ddd/.

  • The Ddd application-defaults file. This file is typically compiled into the DDD executable. If it exists, its resource values override the values compiled into DDD. If the versions of the Ddd application-defaults file and the DDD executable do not match, DDD may not function properly; DDD will give you a warning in this case.8
  • The command-line options. These options override all other resource settings.
  • If the environment variable DDD_SESSION is set, it indicates the name of a session to start, overriding all options and resources. This is used by DDD when restarting itself.

Not every resource has a matching command-line option. Each resource (whether in ~/.ddd/init or Ddd) is specified using a line

Ddd*resource: value

For instance, to set the pollChildStatus resource to off, you would specify in ~/.ddd/init:

Ddd*pollChildStatus: off

For more details on the syntax of resource specifications, see the section RESOURCES in the X(1) manual page.

Node:Changing Resources, Next:Saving Options, Previous:Resources, Up:How Customizing Works

Changing Resources

You can change DDD resources by three methods:

  • Use DDD to change the options, notably Edit => Preferences. This works for the most important DDD resources. Be sure to save the options (see Saving Options) such that they apply to future DDD sessions, too.
  • You can also invoke DDD with an appropriate command-line option. This changes the related DDD resource for this particular DDD invocation. However, if you save the options (see Saving Options), the changed resource will also apply to future invocations.
  • Finally, you can set the appropriate resource in a file named .ddd/init in your home directory. See Resource Index, for a list of DDD resources to be set.

Node:Saving Options, Previous:Changing Resources, Up:How Customizing Works

Saving Options

You can save the current option settings by selecting Edit => Save Options. Options are saved in a file named .ddd/init in your home directory. If a session session is active, options will be saved in ~/.ddd/sessions/session/init instead.

Node:Customizing Help, Next:Customizing Undo, Previous:How Customizing Works, Up:Customizing

Customizing DDD Help

DDD Help can be customized in various ways.

  • Button tips: Turning off tips.
  • Tip of the day: Turning off the tip of the day.
  • Help Helpers: Helper programs invoked by Help.

Node:Button tips, Next:Tip of the day, Up:Customizing Help

Button Tips

Button tips are helpful for novices, but may be distracting for experienced users. You can turn off button tips via Edit => Preferences => General => Automatic display of Button Hints => as Popup Tips.

You can also turn off the hint that is displayed in the status line. Just toggle Edit => Preferences => General => Automatic Display of Button Hints => in the Status Line.

Here are related DDD resources (see Customizing):

buttonTips (class Tips) Resource
If on (default), enable button tips.

buttonDocs (class Docs) Resource
If on (default), show button hints in the status line.

Node:Tip of the day, Next:Help Helpers, Previous:Button tips, Up:Customizing Help

Tip of the day

You can turn off the tip of the day by toggling Edit => Preferences => Startup => Startup Windows => Tip of the Day.

Here is the related DDD resource (see Customizing):

startupTips (class StartupTips) Resource
If on (default), show a tip of the day upon DDD startup.

See Options, for options to set this resource upon DDD invocation.

The actual tips are controlled by these resources (see Customizing):

startupTipCount (class StartupTipCount) Resource
The number n of the tip of the day to be shown at startup. See also the tipn resources.

tip n (class Tip) Resource
The tip of the day numbered n (a string).

Node:Help Helpers, Previous:Tip of the day, Up:Customizing Help

Help Helpers

DDD relies on a number of external commands, specified via Edit => Preferences => Helpers.

To uncompress help texts, you can define a Uncompress command:

uncompressCommand (class UncompressCommand) Resource
The command to uncompress the built-in DDD manual, the DDD license, and the DDD news. Takes a compressed text from standard input and writes the uncompressed text to standard output. The default value is gzip -d -c; typical values include zcat and gunzip -c.

To view WWW pages, you can define a Web Browser command:

wwwCommand (class WWWCommand) Resource
The command to invoke a WWW browser. The string @URL@ is replaced by the URL to open. Default is to try a running Netscape first (trying mozilla, then netscape), then $WWWBROWSER, then to invoke a new Netscape process, then to let a running Emacs do the job, then to invoke Mosaic, then to invoke Lynx in an xterm.

To specify netscape-4.0 as browser, use the setting:

Ddd*wwwCommand: \
     netscape-4.0 -remote 'openURL(@URL@)' \
  || netscape-4.0 '@URL@'

This command first tries to connect to a running netscape-4.0 browser; if this fails, it starts a new netscape-4.0 process.

This is the default WWW Page shown by Help DDD WWW Page:

wwwPage (class WWWPage) Resource
The DDD WWW page. Value: http://www.gnu.org/software/ddd/

Node:Customizing Undo, Next:Customizing Windows, Previous:Customizing Help, Up:Customizing

Customizing Undo

DDD Undo can be customized in various ways.

To set a maximum size for the undo buffer, set Edit => Preferences => General => Undo Buffer Size.

This is related to the maxUndoSize resource:

maxUndoSize (class MaxUndoSize) Resource
The maximum memory usage (in bytes) of the undo buffer. Useful for limiting DDD memory usage. A negative value means to place no limit. Default is 2000000, or 2000 kBytes.

You can also limit the number of entries in the undo buffer, regardless of size (see Customizing):

maxUndoDepth (class MaxUndoDepth) Resource
The maximum number of entries in the undo buffer. This limits the number of actions that can be undone, and the number of states that can be shown in historic mode. Useful for limiting DDD memory usage. A negative value (default) means to place no limit.

To clear the undo buffer at any time, thus reducing memory usage, use Edit => Preferences => General => Clear Undo Buffer

Node:Customizing Windows, Next:Debugger Settings, Previous:Customizing Undo, Up:Customizing

Customizing the DDD Windows

You can customize the DDD Windows in various ways.

  • Splash Screen: Turning off the splash screen.
  • Window Layout: Re-arranging windows.
  • Customizing Fonts: Using alternate fonts.
  • Toggling Windows: Turning off windows.
  • Text Fields: Popdown histories.
  • Icons: Iconifying DDD windows.
  • Adding Buttons: Create your own button set.
  • More Customizations:

Node:Splash Screen, Next:Window Layout, Up:Customizing Windows

Splash Screen

You can turn off the DDD splash screen shown upon startup. Just select Edit => Preferences => Startup DDD Splash Screen.

The value applies only to the next DDD invocation.

This setting is related to the following resource:

splashScreen (class SplashScreen) Resource
If on (default), show a DDD splash screen upon start-up.

You can also customize the appearance of the splash screen (see Customizing):

splashScreenColorKey (class ColorKey) Resource
The color key to use for the DDD splash screen. Possible values include:
  • c (default) for a color visual,
  • g for a multi-level greyscale visual,
  • g4 for a 4-level greyscale visual, and
  • m for a dithered monochrome visual.
  • best chooses the best visual available for your display.

Please note: if DDD runs on a monochrome display, or if DDD was compiled without the XPM library, only the monochrome version (m) can be shown.

Node:Window Layout, Next:Customizing Fonts, Previous:Splash Screen, Up:Customizing Windows

Window Layout

By default, DDD stacks commands, source, and data in one single top-level window. To have separate top-level windows for source, data, and debugger console, set Edit => Preferences => Startup => Window Layout => Separate Windows.

Here are the related DDD resources:

separateDataWindow (class Separate) Resource
If on, the data window and the debugger console are realized in different top-level windows. If off (default), the data window is attached to the debugger console.

separateSourceWindow (class Separate) Resource
If on, the source window and the debugger console are realized in different top-level windows. If off (default), the source window is attached to the debugger console.

By default, the DDD tool bars are located on top of the window. If you prefer the tool bar being located at the bottom, as in DDD 2.x and earlier, set Edit => Preferences => Startup => Tool Bar Appearance => Bottom.

This is related to the toolbarsAtBottom resource:

toolbarsAtBottom (class ToolbarsAtBottom) Resource
Whether source and data tool bars should be placed above source and data, respectively (off, default), or below, as in DDD 2.x (on).

The bottom setting is only supported for separate tool bars--that is, you must either choose separate windows or configure the tool bar to have neither images nor captions (see Customizing the Tool Bar).

If you use stacked windows, you can choose whether there should be one tool bar or two tool bars. By default, DDD uses two tool bars if you use separate windows and disable captions and images, but you can also explicitly change the setting via this resource:

commonToolBar (class ToolBar) Resource
Whether the tool bar buttons should be shown in one common tool bar at the top of the common DDD window (on, default), or whether they should be placed in two separate tool bars, one for data, and one for source operations, as in DDD 2.x (off).

You can also change the location of the status line (see Customizing):

statusAtBottom (class StatusAtBottom) Resource
If on (default), the status line is placed at the bottom of the DDD source window. If off, the status line is placed at the top of the DDD source window (as in DDD 1.x).

See Options, for options to set these resources upon DDD invocation.

Node:Customizing Fonts, Next:Toggling Windows, Previous:Window Layout, Up:Customizing Windows

Customizing Fonts

You can configure the basic DDD fonts at run-time. Each font is specified using two members:

  • The font family is an X font specifications, where the initial foundry- specification may be omitted, as well as any specification after family. Thus, a pair family-weight usually suffices.
  • The font size is given as (resolution-independent) 1/10 points.

To specify fonts, select Edit => Preferences => Fonts.

The Browse button opens a font selection program, where you can select fonts and attributes interactively. Clicking quit or select in the font selector causes all non-default values to be transferred to the DDD font preferences panel.

The following fonts can be set using the preferences panel:

Default Font
The default DDD font to use for labels, menus, and buttons. Default is helvetica-bold.
Variable Width
The variable width DDD font to use for help texts and messages. Default is helvetica-medium.
Fixed Width
The fixed width DDD font to use for source code, the debugger console, text fields, data displays, and the execution window. Default is lucidatypewriter-medium.

Changes in this panel will not take effect immediately. Instead, you can

  • save options (using Edit => Save Options) to make the change effective for future DDD sessions,
  • or restart DDD (using File => Restart DDD) to make it effective for the restarted DDD session.

After having made changes in the panel, DDD will automatically offer you to restart itself, such that you can see the changes taking effect. Note that even after restarting, you still must save options to make the changes permanent.

The Reset button restores the most recently saved preferences.

Here are the resources related to font specifications:

defaultFont (class Font) Resource
The default DDD font to use for labels, menus, buttons, etc. The font is specified as an X font spec, where the initial Foundry specification may be omitted, as well as any specification after Family.

Default value is helvetica-bold.

To set the default DDD font to, say, helvetica medium, insert a line

Ddd*defaultFont: helvetica-medium

in your ~/.ddd/init file.

defaultFontSize (class FontSize) Resource
The size of the default DDD font, in 1/10 points. This resource overrides any font size specification in the defaultFont resource (see above). The default value is 120 for a 12.0 point font.

variableWidthFont (class Font) Resource
The variable width DDD font to use for help texts and messages. The font is specified as an X font spec, where the initial Foundry specification may be omitted, as well as any specification after Family.

Default value is helvetica-medium-r.

To set the variable width DDD font family to, say, times, insert a line

Ddd*fixedWidthFont: times-medium

in your ~/.ddd/init file.

variableWidthFontSize (class FontSize) Resource
The size of the variable width DDD font, in 1/10 points. This resource overrides any font size specification in the variableWidthFont resource (see above). The default value is 120 for a 12.0 point font.

fixedWidthFont (class Font) Resource
The fixed width DDD font to use for source code, the debugger console, text fields, data displays, and the execution window. The font is specified as an X font spec, where the initial Foundry specification may be omitted, as well as any specification after Family.

Default value is to lucidatypewriter-medium.

To set the fixed width DDD font family to, say, courier, insert a line

Ddd*fixedWidthFont: courier-medium

in your ~/.ddd/init file.

fixedWidthFontSize (class FontSize) Resource
The size of the fixed width DDD font, in 1/10 points. This resource overrides any font size specification in the fixedWidthFont resource (see above). The default value is 120 for a 12.0 point font.

As all font size resources have the same class (and by default the same value), you can easily change the default DDD font size to, say, 9.0 points by inserting a line

Ddd*FontSize: 90

in your ~/.ddd/init file.

Here's how to specify the command to select fonts:

fontSelectCommand (class FontSelectCommand) Resource
A command to select from a list of fonts. The string @FONT@ is replaced by the current DDD default font; the string @TYPE@ is replaced by a symbolic name of the DDD font to edit. The program must either place the name of the selected font in the PRIMARY selection or print the selected font on standard output. A typical value is:
Ddd*fontSelectCommand: xfontsel -print

See Options, for options to set these resources upon DDD invocation.

Node:Toggling Windows, Next:Text Fields, Previous:Customizing Fonts, Up:Customizing Windows

Toggling Windows

In the default stacked window setting, you can turn the individual DDD windows on and off by toggling the respective items in the View menu (see View Menu). When using separate windows (see Window Layout), you can close the individual windows via File => Close or by closing them via your window manager.

Whether windows are opened or closed when starting DDD is controlled by the following resources, immediately tied to the View menu items:

openDataWindow (class Window) Resource
If off (default), the data window is closed upon start-up.

openDebuggerConsole (class Window) Resource
If off, the debugger console is closed upon start-up.

openSourceWindow (class Window) Resource
If off, the source window is closed upon start-up.

See Options, for options to set these resources upon DDD invocation.

Node:Text Fields, Next:Icons, Previous:Toggling Windows, Up:Customizing Windows

Text Fields

The DDD text fields can be customized using the following resources:

popdownHistorySize (class HistorySize) Resource
The maximum number of items to display in pop-down value histories. A value of 0 (default) means an unlimited number of values.

sortPopdownHistory (class SortPopdownHistory) Resource
If on (default), items in the pop-down value histories are sorted alphabetically. If off, most recently used values will appear at the top.

Node:Icons, Next:Adding Buttons, Previous:Text Fields, Up:Customizing Windows

Icons

If you frequently switch between DDD and other multi-window applications, you may like to set Edit => Preferences => General => Iconify all windows at once. This way, all DDD windows are iconified and deiconified as a group.

This is tied to the following resource:

groupIconify (class GroupIconify) Resource
If this is on, (un)iconifying any DDD window causes all other DDD windows to (un)iconify as well. Default is off, meaning that each DDD window can be iconified on its own.

If you want to keep DDD off your desktop during a longer computation, you may like to set Edit => Preferences => General => Uniconify when ready. This way, you can iconify DDD while it is busy on a command (e.g. running a program); DDD will automatically pop up again after becoming ready (e.g. after the debugged program has stopped at a breakpoint). See Program Stop, for a discussion.

Here is the related resource:

uniconifyWhenReady (class UniconifyWhenReady) Resource
If this is on (default), the DDD windows are uniconified automatically whenever GDB becomes ready. This way, you can iconify DDD during some longer operation and have it uniconify itself as soon as the program stops. Setting this to off leaves the DDD windows iconified.

Node:Adding Buttons, Next:More Customizations, Previous:Icons, Up:Customizing Windows

Adding Buttons

You can extend DDD with new buttons. See Defining Buttons, for details.

Node:More Customizations, Previous:Adding Buttons, Up:Customizing Windows

More Customizations

You can change just about any label, color, keyboard mapping, etc. by changing resources from the Ddd application defaults file which comes with the DDD source distribution. Here's how it works:

  • Identify the appropriate resource in the Ddd file.
  • Copy the resource line to your ~/.ddd/init file and change it at will.

See Application Defaults, for details on the application-defaults file.

Node:Debugger Settings, Previous:Customizing Windows, Up:Customizing

Debugger Settings

For most inferior debuggers, you can change their internal settings using Edit => Settings. Using the settings editor, you can determine whether C++ names are to be demangled, how many array elements are to print, and so on.

The capabilities of the settings editor depend on the capabilities of your inferior debugger. Clicking on ? gives an an explanation on the specific item; the GDB documentation gives more details.

Use Edit => Undo to undo changes. Clicking on Reset restores the most recently saved settings.

Some debugger settings are insensitive and cannot be changed, because doing so would endanger DDD operation. See the gdbInitCommands and dbxInitCommands resources for details.

All debugger settings (except source and object paths) are saved with DDD options.

Node:Navigating, Next:Stopping, Previous:Windows, Up:Top

Navigating through the Code

This chapter discusses how to access code from within DDD.

  • Compiling for Debugging: Always use `-g' to compile.
  • Opening Files: How to open a program for debugging.
  • Looking up Items: Searching files and functions.
  • Customizing Source: Arranging the source window.

Node:Compiling for Debugging, Next:Opening Files, Up:Navigating

Compiling for Debugging

In order to debug a program effectively, you need to generate debugging information when you compile it. This debugging information is stored in the object file; it describes the data type of each variable or function and the correspondence between source line numbers and addresses in the executable code.9

To request debugging information, specify the -g option when you run the compiler.

Many C compilers are unable to handle the -g and -O options together. Using those compilers, you cannot generate optimized executables containing debugging information.

GCC, the GNU C compiler, supports -g with or without -O, making it possible to debug optimized code. We recommend that you always use -g whenever you compile a program. You may think your program is correct, but there is no sense in pushing your luck.

When you debug a program compiled with -g -O, remember that the optimizer is rearranging your code; the debugger shows you what is really there. Do not be too surprised when the execution path does not exactly match your source file! An extreme example: if you define a variable, but never use it, DDD never sees that variable--because the compiler optimizes it out of existence.

Node:Opening Files, Next:Looking up Items, Previous:Compiling for Debugging, Up:Navigating

Opening Files

If you did not invoke DDD specifying a program to be debugged, you can use the File menu to open programs, core dumps and sources.

  • Opening Programs: How to open a program for debugging.
  • Opening Core Dumps: Analyze a previous crash.
  • Opening Source Files: Open a source file of the program.
  • Filtering Files: DDD only lists matching files.

Node:Opening Programs, Next:Opening Core Dumps, Up:Opening Files

Opening Programs

To open a program to be debugged, select File => Open Program.10 Click on Open to open the program

In JDB, select File => Open Class instead. This gives you a list of available classes to choose from.

To re-open a recently debugged program or class, select File => Open Recent and choose a program or class from the list.

If no sources are found, See Source Path, for specifying source directories.

Node:Opening Core Dumps, Next:Opening Source Files, Previous:Opening Programs, Up:Opening Files

Opening Core Dumps

If a previous run of the program has crashed and you want to find out why, you can have DDD examine its core dump.11

To open a core dump for the program, select File => Open Core Dump. Click on Open to open the core dump.

Before Open Core Dump, you should first use File => Open Program to specify the program that generated the core dump and to load its symbol table.

Node:Opening Source Files, Next:Filtering Files, Previous:Opening Core Dumps, Up:Opening Files

Opening Source Files

To open a source file of the debugged program, select File => Open Source.

  • Using GDB, this gives you a list of the sources used for compiling your program.
  • Using other inferior debuggers, this gives you a list of accessible source files, which may or may not be related to your program.

Click on Open to open the source file. See Source Path, if no sources are found.

Node:Filtering Files, Previous:Opening Source Files, Up:Opening Files

Filtering Files

When presenting files to be opened, DDD by default filters files when opening execution files, core dumps, or source files, such that the selection shows only suitable files. This requires that DDD opens each file, which may take time. See Customizing File Filtering, if you want to turn off this feature.

Node:Looking up Items, Next:Customizing Source, Previous:Opening Files, Up:Navigating

Looking up Items

As soon as the source of the debugged program is available, the source window displays its current source text. (see Source Path, if a source text cannot be found.)

In the source window, you can lookup and examine function and variable definitions as well as search for arbitrary occurrences in the source text.

  • Looking up Definitions: Jump towards a specific item.
  • Textual Search: Search within the current source.
  • Looking up Previous Locations: Navigate back and forth.
  • Source Path: Make DDD know where to search.

Node:Looking up Definitions, Next:Textual Search, Up:Looking up Items

Looking up Definitions

If you wish to lookup a specific function or variable definition whose name is visible in the source text, click with mouse button 1 on the function or variable name. The name is copied to the argument field. Change the name if desired and click on the Lookup button to find its definition.

As a faster alternative, you can simply press mouse button 3 on the function name and select the Lookup item from the source popup menu.

As an even faster alternative, you can also double-click on a function call (an identifier followed by a ( character) to lookup the function definition.

If a source file is not found, See Source Path, for specifying source directories.

Node:Textual Search, Next:Looking up Previous Locations, Previous:Looking up Definitions, Up:Looking up Items

Textual Search

If the item you wish to search is visible in the source text, click with mouse button 1 on it. The identifier is copied to the argument field. Click on the Find >> button to find following occurrences and on Find >> => Find << () to find previous occurrences.

By default, DDD finds only complete words. To search for arbitrary substrings, change the value of the Source => Find Words Only option.

Node:Looking up Previous Locations, Next:Source Path, Previous:Textual Search, Up:Looking up Items

Looking up Previous Locations

After looking up a location, use Edit => Undo (or the Undo button on the command tool) to go back to the original locations. Edit => Redo brings you back again to the location you looked for.

Node:Source Path, Previous:Looking up Previous Locations, Up:Looking up Items

Specifying Source Directories

Executable programs sometimes do not record the directories of the source files from which they were compiled, just the names. Even when they do, the directories could be moved between the compilation and your debugging session.

Here's how GDB accesses source files; other inferior debuggers have similar methods.

GDB has a list of directories to search for source files; this is called the source path. Each time GDB wants a source file, it tries all the directories in the list, in the order they are present in the list, until it finds a file with the desired name. Note that the executable search path is not used for this purpose. Neither is the current working directory, unless it happens to be in the source path.

If GDB cannot find a source file in the source path, and the object program records a directory, GDB tries that directory too. If the source path is empty, and there is no record of the compilation directory, GDB looks in the current directory as a last resort.

To specify a source path for your inferior debugger, use Edit => Debugger Settings (see Debugger Settings and search for appropriate entries (in GDB, this is Search path for source files).

If Debugger Settings has no suitable entry, you can also specify a source path for the inferior debugger when invoking DDD. See Inferior Debugger Options, for details.

When using JDB, you can set the CLASSPATH environment variable to specify directories where JDB (and DDD) should search for classes.

If DDD does not find a source file for any reason, check the following issues:

  • In order to debug a program effectively, you need to generate debugging information when you compile it. Without debugging information, the inferior debugger will be unable to locate the source code. To request debugging information, specify the -g option when you run the compiler. See Compiling for Debugging, for details.
  • You may need to tell your inferior debugger where the source code files are. See Source Path, for details.

    Using GDB, you can also create a local .gdbinit file that contains a line directory path. Here, path is a colon-separated list of source paths.

Node:Customizing Source, Previous:Looking up Items, Up:Navigating

Customizing the Source Window

The source window can be customized in a number of ways, most of them accessed via Edit => Preferences => Source.

  • Customizing Glyphs:
  • Customizing Searching:
  • Customizing Source Appearance:
  • Customizing Source Scrolling:
  • Customizing Source Lookup:
  • Customizing File Filtering:

Node:Customizing Glyphs, Next:Customizing Searching, Up:Customizing Source

Customizing Glyphs

In the source text, the current execution position and breakpoints are indicated by symbols (glyphs). As an alternative, DDD can also indicate these positions using text characters. If you wish to disable glyphs, set Edit => Preferences => Source => Show Position and Breakpoints => as Text Characters option. This also makes DDD run slightly faster, especially when scrolling.

This setting is tied to this resource:

displayGlyphs (class DisplayGlyphs) Resource
If this is on, the current execution position and breakpoints are displayed as glyphs; otherwise, they are shown through characters in the text. The default is on. See Options, for the --glyphs and --no-glyphs options.

You can further control glyphs using the following resources:

cacheGlyphImages (class CacheMachineCode) Resource
Whether to cache (share) glyph images (on) or not (off). Caching glyph images requires less X resources, but has been reported to fail with Motif 2.1 on XFree86 servers. Default is off for Motif 2.1 or later on GNU/Linux machines, and on otherwise.

glyphUpdateDelay (class GlyphUpdateDelay) Resource
A delay (in ms) that says how much time to wait before updating glyphs while scrolling the source text. A small value results in glyphs being scrolled with the text, a large value disables glyphs while scrolling and makes scrolling faster. Default: 10.

maxGlyphs (class MaxGlyphs) Resource
The maximum number of glyphs to be displayed (default: 10). Raising this value causes more glyphs to be allocated, possibly wasting resources that are never needed.

Node:Customizing Searching, Next:Customizing Source Appearance, Previous:Customizing Glyphs, Up:Customizing Source

Customizing Searching

Searching in the source text (see Textual Search) is controlled by these resources, changed via the Source menu:

findCaseSensitive (class FindCaseSensitive) Resource
If this is on (default), the Find commands are case-sensitive. Otherwise, occurrences are found regardless of case.

findWordsOnly (class FindWordsOnly) Resource
If this is on (default), the Find commands find complete words only. Otherwise, arbitrary occurrences are found.

Node:Customizing Source Appearance, Next:Customizing Source Scrolling, Previous:Customizing Searching, Up:Customizing Source

Customizing Source Appearance

You can have DDD show line numbers within the source window. Use Edit => Preferences => Source => Display Source Line Numbers.

displayLineNumbers (class DisplayLineNumbers) Resource
If this is on, lines in the source text are prefixed with their respective line number. The default is off.

You can instruct DDD to indent the source code, leaving more room for breakpoints and execution glyphs. This is done using the Edit => Preferences => Source => Source indentation slider. The default value is 0 for no indentation at all.

indentSource (class Indent) Resource
The number of columns to indent the source code, such that there is enough place to display breakpoint locations. Default: 0.

By default, DDD uses a minimum indentation for script languages.

indentScript (class Indent) Resource
The minimum indentation for script languages, such as Perl and Python. Default: 4.

The maximum width of line numbers is controlled by this resource.

lineNumberWidth (class LineNumberWidth) Resource
The number of columns to use for line numbers (if displaying line numbers is enabled). Line numbers wider than this value extend into the breakpoint space. Default: 4.

If your source code uses a tab width different from 8 (the default), you can set an alternate width using the Edit => Preferences => Source => Tab width slider.

tabWidth (class TabWidth) Resource
The tab width used in the source window (default: 8)

Node:Customizing Source Scrolling, Next:Customizing Source Lookup, Previous:Customizing Source Appearance, Up:Customizing Source

Customizing Source Scrolling

These resources control when the source window is scrolled:

linesAboveCursor (class LinesAboveCursor) Resource
The minimum number of lines to show before the current location. Default is 2.

linesBelowCursor (class LinesBelowCursor) Resource
The minimum number of lines to show after the current location. Default is 3.

Node:Customizing Source Lookup, Next:Customizing File Filtering, Previous:Customizing Source Scrolling, Up:Customizing Source

Customizing Source Lookup

Some DBX and XDB variants do not properly handle paths in source file specifications. If you want the inferior debugger to refer to source locations by source base names only, unset the Edit => Preferences => Source => Refer to Program Sources by full path name option.

This is related to the following resource:

useSourcePath (class UseSourcePath) Resource
If this is off (default), the inferior debugger refers to source code locations only by their base names. If this is on (default), DDD uses the full source code paths.

By default, DDD caches source files in memory. This is convenient for remote debugging, since remote file access may be slow. If you want to reduce memory usage, unset the Edit => Preferences => Source => Cache source files option.

This is related to the following resource:

cacheSourceFiles (class CacheSourceFiles) Resource
Whether to cache source files (on, default) or not (off). Caching source files requires more memory, but makes DDD run faster.

Node:Customizing File Filtering, Previous:Customizing Source Lookup, Up:Customizing Source

Customizing File Filtering

You can control whether DDD should filter files to be opened.

filterFiles (class FilterFiles) Resource
If this is on (default), DDD filters files when opening execution files, core dumps, or source files, such that the selection shows only suitable files. This requires that DDD opens each file, which may take time. If this is off, DDD always presents all available files.

Node:Stopping, Next:Running, Previous:Navigating, Up:Top

Stopping the Program

The principal purposes of using a debugger are so that you can stop your program before it terminates; or so that, if your program runs into trouble, you can investigate and find out why.

Inside DDD, your program may stop for any of several reasons, such as a signal, a breakpoint, or reaching a new line after a DDD command such as Step. You may then examine and change variables, set new breakpoints or remove old ones, and then continue execution.

The inferior debuggers supported by DDD support two mechanisms for stopping a program upon specific events:

  • A breakpoint makes your program stop whenever a certain point in the program is reached. For each breakpoint, you can add conditions to control in finer detail whether your program stops. Typically, breakpoints are set before running the program.
  • A watchpoint is a special breakpoint that stops your program when the value of an expression changes.
  • Breakpoints: Stop at a certain point.
  • Watchpoints: Stop at a certain condition.
  • Interrupting: Stop manually.
  • Stopping X Programs: Take care of grabbed pointers!

Node:Breakpoints, Next:Watchpoints, Up:Stopping

Breakpoints

  • Setting Breakpoints:
  • Deleting Breakpoints:
  • Disabling Breakpoints:
  • Temporary Breakpoints:
  • Editing Breakpoint Properties:
  • Breakpoint Conditions:
  • Breakpoint Ignore Counts:
  • Breakpoint Commands:
  • Moving and Copying Breakpoints:
  • Looking up Breakpoints:
  • Editing all Breakpoints:
  • Hardware-Assisted Breakpoints:

Node:Setting Breakpoints, Next:Deleting Breakpoints, Up:Breakpoints

Setting Breakpoints

You can set breakpoints by location or by name.

Setting Breakpoints by Location

Breakpoints are set at a specific location in the program.

If the source line is visible, click with mouse button 1 on the left of the source line and then on the Break button.

As a faster alternative, you can simply press mouse button 3 on the left of the source line and select the Set Breakpoint item from the line popup menu.

As an even faster alternative, you can simply double-click on the left of the source line to set a breakpoint.

As yet another alternative, you can select Source => Breakpoints. Click on the Break button and enter the location.

(If you find this number of alternatives confusing, be aware that DDD users fall into three categories, which must all be supported. Novice users explore DDD and may prefer to use one single mouse button. Advanced users know how to use shortcuts and prefer popup menus. Experienced users prefer the command line interface.)

Breakpoints are indicated by a plain stop sign, or as #n, where n is the breakpoint number. A greyed out stop sign (or _n_) indicates a disabled breakpoint. A stop sign with a question mark (or ?n?) indicates a conditional breakpoint or a breakpoint with an ignore count set.

If you set a breakpoint by mistake, use Edit => Undo to delete it again.

Setting Breakpoints by Name

If the function name is visible, click with mouse button 1 on the function name. The function name is then copied to the argument field. Click on the Break button to set a breakpoint there.

As a shorter alternative, you can simply press mouse button 3 on the function name and select the Break at item from the popup menu.

As yet another alternative, you can click on Break... from the Breakpoint editor (invoked through Source => Breakpoints) and enter the function name.

Setting Regexp Breakpoints

Using GDB, you can also set a breakpoint on all functions that match a given string. Break => Set Breakpoints at Regexp () sets a breakpoint on all functions whose name matches the regular expression given in (). Here are some examples:

  • To set a breakpoint on every function that starts with Xm, set () to ^Xm.
  • To set a breakpoint on every member of class Date, set () to ^Date::.
  • To set a breakpoint on every function whose name contains _fun, set () to _fun.
  • To set a breakpoint on every function that ends in _test, set () to _test$.

Node:Deleting Breakpoints, Next:Disabling Breakpoints, Previous:Setting Breakpoints, Up:Breakpoints

Deleting Breakpoints

To delete a visible breakpoint, click with mouse button 1 on the breakpoint. The breakpoint location is copied to the argument field. Click on the Clear button to delete all breakpoints there.

If the function name is visible, click with mouse button 1 on the function name. The function name is copied to the argument field. Click on the Clear button to clear all breakpoints there.

As a faster alternative, you can simply press mouse button 3 on the breakpoint and select the Delete Breakpoint item from the popup menu.

As yet another alternative, you can select the breakpoint and click on Delete in the Breakpoint editor (invoked through Source => Breakpoints).

As an even faster alternative, you can simply double-click on the breakpoint while holding <Ctrl>.

Node:Disabling Breakpoints, Next:Temporary Breakpoints, Previous:Deleting Breakpoints, Up:Breakpoints

Disabling Breakpoints

Rather than deleting a breakpoint or watchpoint, you might prefer to disable it. This makes the breakpoint inoperative as if it had been deleted, but remembers the information on the breakpoint so that you can enable it again later.12

To disable a breakpoint, press mouse button 3 on the breakpoint symbol and select the Disable Breakpoint item from the breakpoint popup menu. To enable it again, select Enable Breakpoint.

As an alternative, you can select the breakpoint and click on Disable or Enable in the Breakpoint editor (invoked through Source => Breakpoints.

Disabled breakpoints are indicated by a grey stop sign, or _n_, where n is the breakpoint number.

The Disable Breakpoint item is also accessible via the Clear button. Just press and hold mouse button 1 on the button to get a popup menu.

Node:Temporary Breakpoints, Next:Editing Breakpoint Properties, Previous:Disabling Breakpoints, Up:Breakpoints

Temporary Breakpoints

A temporary breakpoint is immediately deleted as soon as it is reached.13

To set a temporary breakpoint, press mouse button 3 on the left of the source line and select the Set Temporary Breakpoint item from the popup menu.

As a faster alternative, you can simply double-click on the left of the source line while holding <Ctrl>.

Temporary breakpoints are convenient to make the program continue up to a specific location: just set the temporary breakpoint at this location and continue execution.

The Continue Until Here item from the popup menu sets a temporary breakpoint on the left of the source line and immediately continues execution. Execution stops when the temporary breakpoint is reached.

The Set Temporary Breakpoint and Continue Until Here items are also accessible via the Break button. Just press and hold mouse button 1 on the button to get a popup menu.

Node:Editing Breakpoint Properties, Next:Breakpoint Conditions, Previous:Temporary Breakpoints, Up:Breakpoints

Editing Breakpoint Properties

You can change all properties of a breakpoint by pressing mouse button 3 on the breakpoint symbol and select Properties from the breakpoint popup menu. This will pop up a dialog showing the current properties of the selected breakpoint.

As an even faster alternative, you can simply double-click on the breakpoint.

  • Click on Lookup to move the cursor to the breakpoint's location.
  • Click on Enable to enable the breakpoint.
  • Click on Disable to disable the breakpoint.
  • Click on Temp to make the breakpoint temporary.14
  • Click on Delete to delete the breakpoint.

Node:Breakpoint Conditions, Next:Breakpoint Ignore Counts, Previous:Editing Breakpoint Properties, Up:Breakpoints

Breakpoint Conditions

The simplest sort of breakpoint breaks every time your program reaches a specified place. You can also specify a condition for a breakpoint. A condition is just a Boolean expression in your programming language. A breakpoint with a condition evaluates the expression each time your program reaches it, and your program stops only if the condition is true.

This is the converse of using assertions for program validation; in that situation, you want to stop when the assertion is violated-that is, when the condition is false. In C, if you want to test an assertion expressed by the condition assertion, you should set the condition !assertion on the appropriate breakpoint.

Break conditions can have side effects, and may even call functions in your program. This can be useful, for example, to activate functions that log program progress, or to use your own print functions to format special data structures. The effects are completely predictable unless there is another enabled breakpoint at the same address. (In that case, DDD might see the other breakpoint first and stop your program without checking the condition of this one.)

Note that breakpoint commands are usually more convenient and flexible for the purpose of performing side effects when a breakpoint is reached. See Breakpoint Commands, for details.

Node:Breakpoint Ignore Counts, Next:Breakpoint Commands, Previous:Breakpoint Conditions, Up:Breakpoints

Breakpoint Ignore Counts

A special case of a breakpoint condition is to stop only when the breakpoint has been reached a certain number of times. This is so useful that there is a special way to do it, using the ignore count of the breakpoint. Every breakpoint has an ignore count, which is an integer. Most of the time, the ignore count is zero, and therefore has no effect. But if your program reaches a breakpoint whose ignore count is positive, then instead of stopping, it just decrements the ignore count by one and continues. As a result, if the ignore count value is n, the breakpoint does not stop the next n times your program reaches it.

In the field Ignore Count of the Breakpoint Properties panel, you can specify the breakpoint ignore count.15

If a breakpoint has a positive ignore count and a condition, the condition is not checked. Once the ignore count reaches zero, DDD resumes checking the condition.

Node:Breakpoint Commands, Next:Moving and Copying Breakpoints, Previous:Breakpoint Ignore Counts, Up:Breakpoints

Breakpoint Commands

You can give any breakpoint (or watchpoint) a series of DDD commands to execute when your program stops due to that breakpoint. For example, you might want to print the values of certain expressions, or enable other breakpoints.16

Using the Commands buttons of the Breakpoint Properties panel, you can edit commands to be executed when the breakpoint is hit.

To edit breakpoint commands, click on Edit >> and enter the commands in the commands editor. When done with editing, click on Edit << to close the commands editor.

Using GDB, you can also record a command sequence to be executed. To record a command sequence, follow these steps:

  1. Click on Record to begin the recording of the breakpoint commands.
  2. Now interact with DDD. While recording, DDD does not execute commands, but simply records them to be executed when the breakpoint is hit. The recorded debugger commands are shown in the debugger console.
  3. To stop the recording, click on End or enter end at the GDB prompt. To cancel the recording, click on Interrupt or press <ESC>.
  4. You can edit the breakpoint commands just recorded using Edit >>.

Node:Moving and Copying Breakpoints, Next:Looking up Breakpoints, Previous:Breakpoint Commands, Up:Breakpoints

Moving and Copying Breakpoints

To move a breakpoint to a different location, press mouse button 1 on the stop sign and drag it to the desired location.17 This is equivalent to deleting the breakpoint at the old location and setting a breakpoint at the new location. The new breakpoint inherits all properties of the old breakpoint, except the breakpoint number.

To copy a breakpoint to a new location, press <Shift> while dragging.

Node:Looking up Breakpoints, Next:Editing all Breakpoints, Previous:Moving and Copying Breakpoints, Up:Breakpoints

Looking up Breakpoints

If you wish to lookup a specific breakpoint, select Source => Breakpoints => Lookup. After selecting a breakpoint from the list and clicking the Lookup button, the breakpoint location is displayed.

As an alternative, you can enter #n in the argument field, where n is the breakpoint number, and click on the Lookup button to find its definition.

Node:Editing all Breakpoints, Next:Hardware-Assisted Breakpoints, Previous:Looking up Breakpoints, Up:Breakpoints

Editing all Breakpoints

To view and edit all breakpoints at once, select Source => Breakpoints. This will popup the Breakpoint Editor which displays the state of all breakpoints.

In the breakpoint editor, you can select individual breakpoints by clicking on them. Pressing <Ctrl> while clicking toggles the selection. To edit the properties of all selected breakpoints, click on Props.

Node:Hardware-Assisted Breakpoints, Previous:Editing all Breakpoints, Up:Breakpoints

Hardware-Assisted Breakpoints

Using GDB, a few more commands related to breakpoints can be invoked through the debugger console:

hbreak position
Sets a hardware-assisted breakpoint at position. This command requires hardware support and some target hardware may not have this support. The main purpose of this is EPROM/ROM code debugging, so you can set a breakpoint at an instruction without changing the instruction.
thbreak pos
Set a temporary hardware-assisted breakpoint at pos.

See Setting breakpoints, for details.

Node:Watchpoints, Next:Interrupting, Previous:Breakpoints, Up:Stopping

Watchpoints

You can make the program stop as soon as some variable value changes, or when some variable is read or written. This is called setting a watchpoint on a variable.18

Watchpoints have much in common with breakpoints: in particular, you can enable and disable them. You can also set conditions, ignore counts, and commands to be executed when a watched variable changes its value.

Please note: on architectures without special watchpoint support, watchpoints currently make the program execute two orders of magnitude more slowly. This is so because the inferior debugger must interrupt the program after each machine instruction in order to examine whether the watched value has changed. However, this delay can be well worth it to catch errors when you have no clue what part of your program is the culprit.

  • Setting Watchpoints:
  • Editing Watchpoint Properties:
  • Editing all Watchpoints:
  • Deleting Watchpoints:

Node:Setting Watchpoints, Next:Editing Watchpoint Properties, Up:Watchpoints

Setting Watchpoints

If the variable name is visible, click with mouse button 1 on the variable name. The variable name is copied to the argument field. Otherwise, enter the variable name in the argument field. Click on the Watch button to set a watchpoint there.

Using GDB, you can set different types of watchpoints. Click and hold mouse button 1 on the Watch button to get a menu.

Node:Editing Watchpoint Properties, Next:Editing all Watchpoints, Previous:Setting Watchpoints, Up:Watchpoints

Editing Watchpoint Properties

To change the properties of a watchpoint, enter the name of the watched variable in the argument field. Click and hold mouse button 1 on the Watch button and select Watchpoint Properties.

The Watchpoint Properties panel has the same functionality as the Breakpoint Properties panel (see Editing Breakpoint Properties). As an additional feature, you can click on Print to see the current value of a watched variable.

Node:Editing all Watchpoints, Next:Deleting Watchpoints, Previous:Editing Watchpoint Properties, Up:Watchpoints

Editing all Watchpoints

To view and edit all watchpoints at once, select Data => Watchpoints. This will popup the Watchpoint Editor which displays the state of all watchpoints.

The Watchpoint Editor has the same functionality as the Breakpoint Editor (see Editing all Breakpoints). As an additional feature, you can click on Print to see the current value of a watched variable.

Node:Deleting Watchpoints, Previous:Editing all Watchpoints, Up:Watchpoints

Deleting Watchpoints

To delete a watchpoint, enter the name of the watched variable in the argument field and click the Unwatch button.

Node:Interrupting, Next:Stopping X Programs, Previous:Watchpoints, Up:Stopping

Interrupting

If the program is already running (see Running), you can interrupt it any time by clicking the Interrupt button or typing <ESC> in a DDD window.19 Using GDB, this is equivalent to sending a SIGINT (Interrupt) signal.

Interrupt and <ESC> also interrupt a running debugger command, such as printing data.

Node:Stopping X Programs, Previous:Interrupting, Up:Stopping

Stopping X Programs

If your program is a modal X application, DDD may interrupt it while it has grabbed the mouse pointer, making further interaction impossible--your X display will be unresponsive to any user actions.

By default, DDD will check after each interaction whether the pointer is grabbed. If the pointer is grabbed, DDD will continue the debugged program such that you can continue to use your X display.

This is how this feature works: When the program stops, DDD checks for input events such as keyboard or mouse interaction. If DDD does not receive any event within the next 5 seconds, DDD checks whether the mouse pointer is grabbed by attempting to grab and ungrab it. If this attempt fails, then DDD considers the pointer grabbed.

Unfortunately, DDD cannot determine the program that grabbed the pointer--it may be the debugged program, or another program. Consequently, you have another 10 seconds to cancel continuation before DDD continues the program automatically.

There is one situation where this fails: if you lock your X display while DDD is running, then DDD will consider a resulting pointer grab as a result of running the program--and automatically continue execution of the debugged program. Consequently, you can turn off this feature via Edit => Preferences => General => Continue Automatically when Mouse Pointer is Frozen.

  • Customizing Grab Checking:

Node:Customizing Grab Checking, Up:Stopping X Programs

Customizing Grab Checking

The grab checks are controlled by the following resources:

checkGrabs (class CheckGrabs) Resource
If this is on (default), DDD will check after each interaction whether the pointer is grabbed. If this is so, DDD will automatically continue execution of debugged program.

checkGrabDelay (class CheckGrabDelay) Resource
The time to wait (in ms) after a debugger command before checking for a grabbed pointer. If DDD sees some pointer event within this delay, the pointer cannot be grabbed and an explicit check for a grabbed pointer is unnecessary. Default is 5000, or 5 seconds.

grabAction (class grabAction) Resource
The action to take after having detected a grabbed mouse pointer. This is a list of newline-separated commands. Default is cont, meaning to continue the debuggee. Other possible choices include kill (killing the debuggee) or quit (exiting DDD).

grabActionDelay (class grabActionDelay) Resource
The time to wait (in ms) before taking an action due to having detected a grabbed pointer. During this delay, a working dialog pops up telling the user about imminent execution of the grab action (see the grabAction resource, above). If the pointer grab is released within this delay, the working dialog pops down and no action is taken. This is done to exclude pointer grabs from sources other than the debugged program (including DDD). Default is 10000, or 10 seconds.

Node:Running, Next:Examining Data, Previous:Stopping, Up:Top

Running the Program

You may start the debugged program with its arguments, if any, in an environment of your choice. You may redirect your program's input and output, debug an already running process, or kill a child process.

  • Starting Program Execution:
  • Using the Execution Window:
  • Attaching to a Process:
  • Program Stop:
  • Resuming Execution:
  • Continuing Somewhere Else:
  • Stack:
  • Undoing Program Execution:
  • Threads:
  • Signals:
  • Killing the Program:

Node:Starting Program Execution, Next:Using the Execution Window, Up:Running

Starting Program Execution

To start execution of the debugged program, select Program => Run. You will then be prompted for the arguments to pass to your program. You can either select from a list of previously used arguments or enter own arguments in the text field. Afterwards, press the Run button to start execution with the selected arguments.

To run your program again, with the same arguments, select Program => Run Again or press the Run button on the command tool. You may also enter run, followed by arguments at the debugger prompt instead.

When you click on Run, your program begins to execute immediately. See Stopping, for a discussion of how to arrange for your program to stop. Once your program has stopped, you may call functions in your program to examine data. See Examining Data, for details.

If the modification time of your symbol file has changed since the last time GDB read its symbols, GDB discards its symbol table, and reads it again. When it does this, GDB and DDD try to retain your current debugger state, such as breakpoints.

  • Arguments: Your program's arguments.
  • Environment: Your program's environment.
  • Working Directory: Your program's directory.
  • Input/Output: Your program's I/O.

Node:Arguments, Next:Environment, Up:Starting Program Execution

Your Program's Arguments

The arguments to your program are specified by the arguments of the run command, as composed in Program => Run.

In GDB, the arguments are passed to a shell, which expands wildcard characters and performs redirection of I/O, and thence to your program. Your SHELL environment variable (if it exists) specifies what shell GDB uses. If you do not define SHELL, GDB uses /bin/sh.

If you use another inferior debugger, the exact semantics on how the arguments are interpreted depend on the inferior debugger you are using. Normally, the shell is used to pass the arguments, so that you may use normal conventions (such as wildcard expansion or variable substitution) in describing the arguments.

Node:Environment, Next:Working Directory, Previous:Arguments, Up:Starting Program Execution

Your Program's Environment

Your program normally inherits its environment from the inferior debugger, which again inherits it from DDD, which again inherits it from its parent process (typically the shell or desktop).

In GDB, you can use the commands set environment and unset environment to change parts of the environment that affect your program. See Your program's environment, for details.

The following environment variables are set by DDD:

DDD
Set to a string indicating the DDD version. By testing whether DDD is set, a debuggee (or inferior debugger) can determine whether it was invoked by DDD.
TERM
Set to dumb, the DDD terminal type. This is set for the inferior debugger only.20
TERMCAP
Set to `' (none), the DDD terminal capabilities.
PAGER
Set to cat, the preferred DDD pager.

The inferior debugger, in turn, might also set or unset some environment variables.

Node:Working Directory, Next:Input/Output, Previous:Environment, Up:Starting Program Execution

Your Program's Working Directory

Your program normally inherits its working directory from the inferior debugger, which again inherits it from DDD, which again inherits it from its parent process (typically the shell or desktop).

You can change the working directory of the inferior debugger via File => Change Directory or via the cd command of the inferior debugger.

Node:Input/Output, Previous:Working Directory, Up:Starting Program Execution

Your Program's Input and Output

By default, the program you run under DDD does input and output to the debugger console. Normally, you can redirect your program's input and/or output using shell redirections with the arguments--that is, additional arguments like < input or > output. You can enter these shell redirections just like other arguments (see Arguments).

Warning: While input and output redirection work, you cannot use pipes to pass the output of the program you are debugging to another program; if you attempt this, DDD may wind up debugging the wrong program. See Attaching to a Process, for an alternative.

If command output is sent to the debugger console, it is impossible for DDD to distinguish between the output of the debugged program and the output of the inferior debugger.

Program output that confuses DDD includes:

  • Primary debugger prompts (e.g. (gdb) , (dbx) or (ladebug) )
  • Secondary debugger prompts (e.g. >)
  • Confirmation prompts (e.g. (y or n) )
  • Prompts for more output (e.g. Press RETURN to continue)
  • Display output (e.g. $pc = 0x1234)

If your program outputs any of these strings, you may encounter problems with DDD mistaking them for debugger output. These problems can easily be avoided by redirecting program I/O, for instance to the separate execution window (see Using the Execution Window).

If the inferior debugger changes the default TTY settings, for instance through a stty command in its initialization file, DDD may also become confused. The same applies to debugged programs which change the default TTY settings.

The behavior of the debugger console can be controlled using the following resource:

lineBufferedConsole (class LineBuffered) Resource
If this is on (default), each line from the inferior debugger is output on each own, such that the final line is placed at the bottom of the debugger console. If this is off, all lines are output as a whole. This is faster, but results in a random position of the last line.

Node:Using the Execution Window, Next:Attaching to a Process, Previous:Starting Program Execution, Up:Running

Using the Execution Window

By default, input and output of your program go to the debugger console. As an alternative, DDD can also invoke an execution window, where the program terminal input and output is shown.21

To activate the execution window, select Program => Run in Execution Window.

The execution window is opened automatically as soon as you start the debugged program. While the execution window is active, DDD redirects the standard input, output, and error streams of your program to the execution window. Note that the device /dev/tty still refers to the debugger console, not the execution window.

You can override the DDD stream redirection by giving alternate redirection operations as arguments. For instance, to have your program read from file, but to write to the execution window, invoke your program with < file as argument. Likewise, to redirect the standard error output to the debugger console, use 2> /dev/tty (assuming the inferior debugger and/or your UNIX shell support standard error redirection).

  • Customizing the Execution Window:

Node:Customizing the Execution Window, Up:Using the Execution Window

Customizing the Execution Window

You can customize the DDD execution window and use a different TTY command. The command is set by Edit => Preferences => Helpers => Execution Window:

termCommand (class TermCommand) Resource
The command to invoke for the execution window--a TTY emulator that shows the input/output of the debugged program. A Bourne shell command to run in the separate TTY is appended to this string. The string @FONT@ is replaced by the name of the fixed width font used by DDD. A simple value is
Ddd*termCommand: xterm -fn @FONT@ -e /bin/sh -c

You can also set the terminal type:

termType (class TermType) Resource
The terminal type provided by the termCommand resource--that is, the value of the TERM environment variable to be passed to the debugged program. Default: xterm.

Whether the execution window is active or not, as set by Program => Run in Execution Window, is saved using this resource:

separateExecWindow (class Separate) Resource
If on, the debugged program is executed in a separate execution window. If off (default), the debugged program is executed in the console window.

Node:Attaching to a Process, Next:Program Stop, Previous:Using the Execution Window, Up:Running

Attaching to a Running Process

If the debugged program is already running in some process, you can attach to this process (instead of starting a new one with Run).22

To attach DDD to a process, select File => Attach to Process. You can now choose from a list of processes. Then, press the Attach button to attach to the specified process.

The first thing DDD does after arranging to debug the specified process is to stop it. You can examine and modify an attached process with all the DDD commands that are ordinarily available when you start processes with Run. You can insert breakpoints; you can step and continue; you can modify storage. If you would rather the process continue running, you may use Continue after attaching DDD to the process.

When using Attach to Process, you should first use Open Program to specify the program running in the process and load its symbol table.

When you have finished debugging the attached process, you can use the File => Detach Process to release it from DDD control. Detaching the process continues its execution. After Detach Process, that process and DDD become completely independent once more, and you are ready to attach another process or start one with Run.

You can customize the list of processes shown by defining an alternate command to list processes. See Edit => Preferences => Helpers => List Processes; See Customizing Attaching to Processes, for details.

  • Customizing Attaching to Processes:

Node:Customizing Attaching to Processes, Up:Attaching to a Process

Customizing Attaching to Processes

When attaching to a process (see Attaching to a Process), DDD uses a ps command to get the list of processes. This command is defined by the psCommand resource.

psCommand (class PsCommand) Resource
The command to get a list of processes. Usually ps. Depending on your system, useful alternate values include ps -ef and ps ux. The first line of the output must either contain a PID title, or each line must begin with a process ID.

Note that the output of this command is filtered by DDD; a process is only shown if it can be attached to. The DDD process itself as well as the process of the inferior debugger are suppressed, too.

Node:Program Stop, Next:Resuming Execution, Previous:Attaching to a Process, Up:Running

Program Stops

After the program has been started, it runs until one of the following happens:

  • A breakpoint is reached (see Breakpoints).
  • A watched value changes (see Watchpoints).
  • The program is interrupted (see Interrupting).
  • A signal is received (see Signals).
  • Execution completes.

DDD shows the current program status in the debugger console. The current execution position is highlighted by an arrow.

If Edit => Preferences => General => Uniconify When Ready is set, DDD automatically deiconifies itself when the program stops. This way, you can iconify DDD during a lengthy computation and have it uniconify as soon as the program stops.

Node:Resuming Execution, Next:Continuing Somewhere Else, Previous:Program Stop, Up:Running

Resuming Execution

Continuing

To resume execution, at the current execution position, click on the Continue button. Any breakpoints set at the current execution position are bypassed.

Stepping one Line

To execute just one source line, click on the Step button. The program is executed until control reaches a different source line, which may be in a different function. Then, the program is stopped and control returns to DDD.

Warning: If you use the Step button while control is within a function that was compiled without debugging information, execution proceeds until control reaches a function that does have debugging information. Likewise, it will not step into a function which is compiled without debugging information. To step through functions without debugging information, use the Stepi button (see Machine Code Execution).

In GDB, the Step button only stops at the first instruction of a source line. This prevents the multiple stops that used to occur in switch statements, for loops, etc. Step continues to stop if a function that has debugging information is called within the line.

Also, the Step in GDB only enters a subroutine if there is line number information for the subroutine. Otherwise it acts like the Next button.

Continuing to the Next Line

To continue to the next line in the current function, click on the Next button. This is similar to Step, but any function calls appearing within the line of code are executed without stopping.

Execution stops when control reaches a different line of code at the original stack level that was executing when you clicked on Next.

Continuing Until Here

To continue running until a specific location is reached, use the Continue Until Here facility from the line popup menu. See Temporary Breakpoints, for a discussion.

Continuing Until a Greater Line is Reached

To continue until a greater line in the current function is reached, click on the Until button. This is useful to avoid single stepping through a loop more than once.

Until is like Next, except that when Until encounters a jump, it automatically continues execution until the program counter is greater than the address of the jump.

This means that when you reach the end of a loop after single stepping though it, until makes your program continue execution until it exits the loop. In contrast, clicking on Next at the end of a loop simply steps back to the beginning of the loop, which forces you to step through the next iteration.

Until always stops your program if it attempts to exit the current stack frame.

Until works by means of single instruction stepping, and hence is slower than continuing until a breakpoint is reached.

Continuing Until Function Returns

To continue running until the current function returns, use the Finish button. The returned value (if any) is printed.

Node:Continuing Somewhere Else, Next:Stack, Previous:Resuming Execution, Up:Running

Continuing at a Different Address

Ordinarily, when you continue your program, you do so at the place where it stopped. You can instead continue at an address of your own choosing.

The most common occasion to use this feature is to back up--perhaps with more breakpoints set-over a portion of a program that has already executed, in order to examine its execution in more detail.

To set the execution position to the current location, use Set Execution Position from the breakpoint popup menu. This item is also accessible by pressing and holding the Break/Clear button.23

As a quicker alternative, you can also press mouse button 1 on the arrow and drag it to a different location.24

Moving the execution position does not change the current stack frame, or the stack pointer, or the contents of any memory location or any register other than the program counter.

Some inferior debuggers (notably GDB) allow you to set the new execution position into a different function from the one currently executing. This may lead to bizarre results if the two functions expect different patterns of arguments or of local variables. For this reason, moving the execution position requests confirmation if the specified line is not in the function currently executing.

After moving the execution position, click on Continue to resume execution.

Node:Stack, Next:Undoing Program Execution, Previous:Continuing Somewhere Else, Up:Running

Examining the Stack

When your program has stopped, the first thing you need to know is where it stopped and how it got there.

Each time your program performs a function call, information about the call is generated. That information includes the location of the call in your program, the arguments of the call, and the local variables of the function being called. The information is saved in a block of data called a stack frame. The stack frames are allocated in a region of memory called the call stack.

When your program stops, the DDD commands for examining the stack allow you to see all of this information.

One of the stack frames is selected by DDD and many DDD commands refer implicitly to the selected frame. In particular, whenever you ask DDD for the value of a variable in your program, the value is found in the selected frame. There are special DDD commands to select whichever frame you are interested in.

  • Frames: Callers and callees.
  • Backtraces: And you may ask yourself, `how did I get here?'
  • Selecting a frame: Moving up and down.

Node:Frames, Next:Backtraces, Up:Stack

Stack Frames

The call stack is divided up into contiguous pieces called stack frames, or frames for short; each frame is the data associated with one call to one function. The frame contains the arguments given to the function, the function's local variables, and the address at which the function is executing.

When your program is started, the stack has only one frame, that of the function main. This is called the initial frame or the outermost frame. Each time a function is called, a new frame is made. Each time a function returns, the frame for that function invocation is eliminated. If a function is recursive, there can be many frames for the same function. The frame for the function in which execution is actually occurring is called the innermost frame. This is the most recently created of all the stack frames that still exist.

Inside your program, stack frames are identified by their addresses. A stack frame consists of many bytes, each of which has its own address; each kind of computer has a convention for choosing one byte whose address serves as the address of the frame. Usually this address is kept in a register called the frame pointer register while execution is going on in that frame.

GDB assigns numbers to all existing stack frames, starting with zero for the innermost frame, one for the frame that called it, and so on upward. These numbers do not really exist in your program; they are assigned by GDB to give you a way of designating stack frames in GDB commands.

Node:Backtraces, Next:Selecting a frame, Previous:Frames, Up:Stack

Backtraces

DDD provides a backtrace window showing a summary of how your program got where it is. It shows one line per frame, for many frames, starting with the currently executing frame (frame zero), followed by its caller (frame one), and on up the stack.

To enable the backtrace window, select Status => Backtrace.

Using GDB, each line in the backtrace shows the frame number and the function name. The program counter value is also shown--unless you use the GDB command set print address off. The backtrace also shows the source file name and line number, as well as the arguments to the function. The program counter value is omitted if it is at the beginning of the code for that line number.

Node:Selecting a frame, Previous:Backtraces, Up:Stack

Selecting a Frame

Most commands for examining the stack and other data in your program work on whichever stack frame is selected at the moment. Here are the commands for selecting a stack frame.25

In the backtrace window, you can select an arbitrary frame to move from one stack frame to another. Just click on the desired frame.

The Up button selects the function that called the current one--that is, it moves one frame up.

The Down button selects the function that was called by the current one--that is, it moves one frame down.

You can also directly type the up and down commands at the debugger prompt. Typing <Ctrl+Up> and <Ctrl+Down>, respectively, will also move you through the stack.

Up and Down actions can be undone via Edit => Undo.

Node:Undoing Program Execution, Next:Threads, Previous:Stack, Up:Running

"Undoing" Program Execution

If you take a look at the Edit => Undo menu item after an execution command, you'll find that DDD offers you to undo execution commands just as other commands. Does this mean that DDD allows you to go backwards in time, undoing program execution as well as undoing any side-effects of your program?

Sorry--we must disappoint you. DDD cannot undo what your program did. (After a little bit of thought, you'll find that this would be impossible in general.) However, DDD can do something different: it can show previously recorded states of your program.

After "undoing" an execution command (via Edit => Undo, or the Undo button), the execution position moves back to the earlier position and displayed variables take their earlier values. Your program state is in fact unchanged, but DDD gives you a view on the earlier state as recorded by DDD.

In this so-called historic mode, most normal DDD commands that would query further information from the program are disabled, since the debugger cannot be queried for the earlier state. However, you can examine the current execution position, or the displayed variables. Using Undo and Redo, you can move back and forward in time to examine how your program got into the present state.

To let you know that you are operating in historic mode, the execution arrow gets a dashed-line appearance (indicating a past position); variable displays also come with dashed lines. Furthermore, the status line informs you that you are seeing an earlier program state.

Here's how historic mode works: each time your program stops, DDD collects the current execution position and the values of displayed variables. Backtrace, thread, and register information is also collected if the corresponding dialogs are open. When "undoing" an execution command, DDD updates its view from this collected state instead of querying the program.

If you want to collect this information without interrupting your program--within a loop, for instance--you can place a breakpoint with an associated cont command (see Breakpoint Commands). When the breakpoint is hit, DDD will stop, collect the data, and execute the cont command, resuming execution. Using a later Undo, you can step back and look at every single loop iteration.

To leave historic mode, you can use Redo until you are back in the current program state. However, any DDD command that refers to program state will also leave historic mode immediately by applying to the current program state instead. For instance, Up leaves historic mode immediately and selects an alternate frame in the restored current program state.

If you want to see the history of a specific variable, as recorded during program stops, you can enter the DDD command

graph history name

This returns a list of all previously recorded values of the variable name, using array syntax. Note that name must have been displayed at earlier program stops in order to record values.

Node:Threads, Next:Signals, Previous:Undoing Program Execution, Up:Running

Examining Threads

In some operating systems, a single program may have more than one thread of execution. The precise semantics of threads differ from one operating system to another, but in general the threads of a single program are akin to multiple processes--except that they share one address space (that is, they can all examine and modify the same variables). On the other hand, each thread has its own registers and execution stack, and perhaps private memory.

For debugging purposes, DDD lets you display the list of threads currently active in your program and lets you select the current thread--the thread which is the focus of debugging. DDD shows all program information from the perspective of the current thread.26

To view all currently active threads in your program, select Status => Threads. The current thread is highlighted. Select any thread to make it the current thread.

Using JDB, additional functionality is available:

  • Select a thread group to switch between viewing all threads and the threads of the selected thread group;
  • Click on Suspend to suspend execution of the selected threads;
  • Click on Resume to resume execution of the selected threads.

For more information on threads, see the JDB and GDB documentation (see Threads).

Node:Signals, Next:Killing the Program, Previous:Threads, Up:Running

Handling Signals

A signal is an asynchronous event that can happen in a program. The operating system defines the possible kinds of signals, and gives each kind a name and a number. For example, in UNIX, SIGINT is the signal a program gets when you type an interrupt; SIGSEGV is the signal a program gets from referencing a place in memory far away from all the areas in use; SIGALRM occurs when the alarm clock timer goes off (which happens only if your program has requested an alarm).

Some signals, including SIGALRM, are a normal part of the functioning of your program. Others, such as SIGSEGV, indicate errors; these signals are fatal (kill your program immediately) if the program has not specified in advance some other way to handle the signal. SIGINT does not indicate an error in your program, but it is normally fatal so it can carry out the purpose of the interrupt: to kill the program.

GDB has the ability to detect any occurrence of a signal in your program. You can tell GDB in advance what to do for each kind of signal.

Normally, DDD is set up to ignore non-erroneous signals like SIGALRM (so as not to interfere with their role in the functioning of your program) but to stop your program immediately whenever an error signal happens. In DDD, you can view and edit these settings via Status => Signals.

Status => Signals pops up a panel showing all the kinds of signals and how GDB has been told to handle each one. The settings available for each signal are:

Stop
If set, GDB should stop your program when this signal happens. This also implies Print being set.
Print
If set, GDB should print a message when this signal happens.

If unset, GDB should not mention the occurrence of the signal at all. This also implies Stop being unset.

Pass
If set, GDB should allow your program to see this signal; your program can handle the signal, or else it may terminate if the signal is fatal and not handled.

If unset, GDB should not allow your program to see this signal.

The entry All Signals is special. Changing a setting here affects all signals at once--except those used by the debugger, typically SIGTRAP and SIGINT.

To undo any changes, use Edit => Undo. The Reset button restores the saved settings.

When a signal stops your program, the signal is not visible until you continue. Your program sees the signal then, if Pass is in effect for the signal in question at that time. In other words, after GDB reports a signal, you can change the Pass setting in Status => Signals to control whether your program sees that signal when you continue.

You can also cause your program to see a signal it normally would not see, or to give it any signal at any time. The Send button will resume execution where your program stopped, but immediately give it the signal shown.

On the other hand, you can also prevent your program from seeing a signal. For example, if your program stopped due to some sort of memory reference error, you might store correct values into the erroneous variables and continue, hoping to see more execution; but your program would probably terminate immediately as a result of the fatal signal once it saw the signal. To prevent this, you can resume execution using Commands => Continue Without Signal.

Edit => Save Options does not save changed signal settings, since changed signal settings are normally useful within specific projects only. Instead, signal settings are saved with the current session, using File => Save Session As.

Node:Killing the Program, Previous:Signals, Up:Running

Killing the Program

You can kill the process of the debugged program at any time using the Kill button.

Killing the process is useful if you wish to debug a core dump instead of a running process. GDB ignores any core dump file while your program is running.

The Kill button is also useful if you wish to recompile and relink your program, since on many systems it is impossible to modify an executable file while it is running in a process. In this case, when you next click on Run, GDB notices that the file has changed, and reads the symbol table again (while trying to preserve your current debugger state).

Node:Examining Data, Next:Machine-Level Debugging, Previous:Running, Up:Top

Examining Data

DDD provides several means to examine data.

  • The quickest way to examine variables is to move the pointer on an occurrence in the source text. The value is displayed in the source line; after a second, a popup window (called value tip) shows the variable value. This is useful for quick examination of several simple values.
  • If you want to refer to variable values at a later time, you can print the value in the debugger console. This allows for displaying and examining larger data structures.
  • If you want to examine complex data structures, you can display them graphically in the data window. Displays remain effective until you delete them; they are updated each time the program stops. This is useful for large dynamic structures.
  • If you want to examine arrays of numeric values, you can plot them graphically in a separate plot window. The plot is updated each time the program stops. This is useful for large numeric arrays.
  • Using GDB or DBX, you can also examine memory contents in any of several formats, independently of your program's data types.
  • Value Tips: Just move the pointer on a variable.
  • Printing Values: Printing a value in the debugger console.
  • Displaying Values: Displaying structures as graphs.
  • Plotting Values: Displaying values as plots.
  • Examining Memory: Low-level memory examination.

Node:Value Tips, Next:Printing Values, Up:Examining Data

Showing Simple Values using Value Tips

To display the value of a simple variable, move the mouse pointer on its name. After a second, a small window (called value tip) pops up showing the value of the variable pointed at. The window disappears as soon as you move the mouse pointer away from the variable. The value is also shown in the status line.

You can disable value tips via Edit => Preferences => General => Automatic display of variable values as popup tips.

You can disable displaying variable values in the status line via Edit => Preferences => General => Automatic display of variable values in the status line.

These customizations are tied to the following resources:

valueTips (class Tips) Resource
Whether value tips are enabled (on, default) or not (off). Value tips affect DDD performance and may be distracting for some experienced users.

valueDocs (class Docs) Resource
Whether the display of variable values in the status line is enabled (on, default) or not (off).

You can turn off value tips via Edit => Preferences => General => Automatic Display of Variable Values.

Node:Printing Values, Next:Displaying Values, Previous:Value Tips, Up:Examining Data

Printing Simple Values in the Debugger Console

The variable value can also be printed in the debugger console, making it available for future operations. To print a variable value, select the desired variable by clicking mouse button 1 on its name. The variable name is copied to the argument field. By clicking the Print button, the value is printed in the debugger console. The printed value is also shown in the status line.

As a shorter alternative, you can simply press mouse button 3 on the variable name and select the Print item from the popup menu.

In GDB, the Print button generates a print command, which has several more options. See Data, for GDB-specific expressions, variables, and output formats.

Node:Displaying Values, Next:Plotting Values, Previous:Printing Values, Up:Examining Data

Displaying Complex Values in the Data Window

To explore complex data structures, you can display them permanently in the data window. The data window displays selected data of your program, showing complex data structures graphically. It is updated each time the program stops.

  • Display Basics: How to create, manipulate, and delete displays.
  • Displaying Arrays: Special functions for arrays.
  • Assignment: Setting variable values.
  • Examining Structures: Dereferencing pointers and other references.
  • Layouting the Graph: Automatic layout.
  • Printing the Graph: Printing on paper.
  • How Displays are Created: The technical details.

Node:Display Basics, Next:Displaying Arrays, Up:Displaying Values

Display Basics

This section discusses how to create, manipulate, and delete displays. The essentials are:

  • Click on Display to display the variable in ().
  • Click on a display to select it.
  • Click on Undisplay to delete the selected display.
  • Creating Single Displays:
  • Selecting Displays:
  • Showing and Hiding Details:
  • Rotating Displays:
  • Displaying Local Variables:
  • Displaying Program Status:
  • Refreshing the Data Window:
  • Clustering:
  • Creating Multiple Displays:
  • Editing all Displays:
  • Deleting Displays:
  • Customizing Displays:

Node:Creating Single Displays, Next:Selecting Displays, Up:Display Basics

Creating Single Displays

To create a new display showing a specific variable, select the variable by clicking mouse button 1 on its name. The variable name is copied to the argument field. By clicking the Display button, a new display is created in the data window. The data window opens automatically as soon as you create a display.

As a shorter alternative, you can simply press mouse button 3 on the variable name and select Display from the popup menu.

As an even faster alternative, you can also double-click on the variable name.

As another alternative, you may also enter the expression to be displayed in the argument field and press the Display button.

Finally, you may also type in a command at the debugger prompt:

graph display expr [clustered] [at (x, y)]
    [dependent on display] [[now or] when in scope]

This command creates a new display showing the value of the expression expr. The optional parts have the following meaning:

clustered
If given, the new display is created in a cluster. See Clustering, for a discussion.
at (x, y)
If given, the new display is created at the position (x, y). Otherwise, a default position is assigned.
dependent on display
If given, an edge from the display numbered or named display to the new display is created. Otherwise, no edge is created. See Dependent Values, for details.
when in scope
now or when in scope
If when in is given, the display creation is deferred until execution reaches the given scope (a function name, as in the backtrace output).

If now or when in is given, DDD first attempts to create the display immediately. The display is deferred only if display creation fails.

If neither when in suffix nor now or when in suffix is given, the display is created immediately.

Node:Selecting Displays, Next:Showing and Hiding Details, Previous:Creating Single Displays, Up:Display Basics

Selecting Displays

Each display in the data window has a title bar containing the display number and the displayed expression (the display name). Below the title, the display value is shown.

You can select single displays by clicking on them with mouse button 1.

You can extend an existing selection by pressing the <Shift> key while selecting. You can also toggle an existing selection by pressing the <Shift> key while selecting already selected displays.

Single displays may also be selected by using the arrow keys <Up>, <Down>, <Left>, and <Right>.

Multiple displays are selected by pressing and holding mouse button 1 somewhere on the window background. By moving the pointer while holding the button, a selection rectangle is shown; all displays fitting in the rectangle are selected when mouse button 1 is released.

If the <Shift> key is pressed while selecting, the existing selection is extended.

By double-clicking on a display title, the display itself and all connected displays are automatically selected.

Node:Showing and Hiding Details, Next:Rotating Displays, Previous:Selecting Displays, Up:Display Basics

Showing and Hiding Details

Aggregate values (i.e. records, structs, classes, and arrays) can be shown expanded, that is, displaying all details, or hidden, that is, displayed as {...}.

To show details about an aggregate, select the aggregate by clicking mouse button 1 on its name or value and click on the Show button. Details are shown for the aggregate itself as well as for all contained sub-aggregates.

To hide details about an aggregate, select the aggregate by clicking mouse button 1 on its name or value and click on the Hide button.

When pressing and holding mouse button 1 on the Show/Hide button, a menu pops up with even more alternatives:

Show More ()
Shows details of all aggregates currently hidden, but not of their sub-aggregates. You can invoke this item several times in a row to reveal more and more details of the selected aggregate.
Show Just ()
Shows details of the selected aggregate, but hides all sub-aggregates.
Show All ()
Shows all details of the selected aggregate and of its sub-aggregates. This item is equivalent to the Show button.
Hide ()
Hide all details of the selected aggregate. This item is equivalent to the Hide button.

As a faster alternative, you can also press mouse button 3 on the aggregate and select the appropriate menu item.

As an even faster alternative, you can also double-click mouse button 1 on a value. If some part of the value is hidden, more details will be shown; if the entire value is shown, double-clicking will hide the value instead. This way, you can double-click on a value until you get the right amount of details.

If all details of a display are hidden, the display is called disabled; this is indicated by the string (Disabled).

Displays can also be disabled or enabled via a DDD command, which you enter at the debugger prompt:

graph disable display displays...

disables the given displays.

graph enable display displays...

re-enables the given displays.

In both commands, displays... is either

  • a space-separated list of display numbers to disable or enable, or
  • a single display name. If you specify a display by name, all displays with this name will be affected.

Use Edit => Undo to undo disabling or enabling displays.

Node:Rotating Displays, Next:Displaying Local Variables, Previous:Showing and Hiding Details, Up:Display Basics

Rotating Displays

Arrays, structures and lists can be oriented horizontally or vertically. To change the orientation of a display, select it and then click on the Rotate button.

As a faster alternative, you can also press mouse button 3 on the array and select Rotate from the popup menu.

If a structure or list is oriented horizontally, DDD automatically suppresses the member names. This can be handy for saving space.

The last chosen display orientation is used for the creation of new displays. If you recently rotated an array to horizontal orientation, the next array you create will also be oriented horizontally. These settings are saved with Edit => Save Options; they are tied to the following resources:

arrayOrientation (class Orientation) Resource
How arrays are to be oriented. Possible values are XmVERTICAL (default) and XmHORIZONTAL.

showMemberNames (class ShowMemberNames) Resource
Whether to show struct member names or not. Default is on.

structOrientation (class Orientation) Resource
How structs are to be oriented. Possible values are XmVERTICAL (default) and XmHORIZONTAL.

Node:Displaying Local Variables, Next:Displaying Program Status, Previous:Rotating Displays, Up:Display Basics

Displaying Local Variables

You can display all local variables at once by choosing Data => Display Local Variables. When using DBX, XDB, JDB, or Perl, this displays all local variables, including the arguments of the current function. When using GDB or PYDB, function arguments are contained in a separate display, activated by Data => Display Arguments.

The display showing the local variables can be manipulated just like any other data display. Individual variables can be selected and dereferenced.

Node:Displaying Program Status, Next:Refreshing the Data Window, Previous:Displaying Local Variables, Up:Display Basics

Displaying Program Status

You can create a display from the output of an arbitrary debugger command. By entering

graph display `command`

the output of command is turned into a status display updated each time the program stops.

For instance, the command

graph display `where`

creates a status display named Where that shows the current backtrace.

If you are using GDB, DDD provides a panel from which you can choose useful status displays. Select Data => Status Displays and pick your choice from the list.

Refreshing status displays at each stop takes time; you should delete status displays as soon as you don't need them any more.

Node:Refreshing the Data Window, Next:Clustering, Previous:Displaying Program Status, Up:Display Basics

Refreshing the Data Window

The data window is automatically updated or refreshed each time the program stops. Values that have changed since the last refresh are highlighted.

However, there may be situations where you should refresh the data window explicitly. This is especially the case whenever you changed debugger settings that could affect the data format, and want the data window to reflect these settings.

You can refresh the data window by selecting Data => Refresh Displays.

As an alternative, you can press mouse button 3 on the background of the data window and select the Refresh Displays item.

Typing

graph refresh

at the debugger prompt has the same effect.

Node:Clustering, Next:Creating Multiple Displays, Previous:Refreshing the Data Window, Up:Display Basics

Clustering Displays

If you examine several variables at once, having a separate display for each of them uses a lot of screen space. This is why DDD supports clusters. A cluster merges several logical data displays into one physical display, saving screen space.

There are two ways to create clusters:

  • You can create clusters manually. This is done by selecting the displays to be clustered and choosing Undisp => Cluster (). This creates a new cluster from all selected displays. If an already existing cluster is selected, too, the selected displays will be clustered into the selected cluster.
  • You can create a cluster automatically for all independent data displays, such that all new data displays will automatically be clustered, too. This is achieved by enabling Edit => Preferences => Data => Cluster Data Displays.

Displays in a cluster can be selected and manipulated like parts of an ordinary display; in particular, you can show and hide details, or dereference pointers. However, edges leading to clustered displays can not be shown, and you must either select one or all clustered displays.

Disabling a cluster is called unclustering, and again, there are two ways of doing it:

  • You can uncluster displays manually, by selecting the cluster and choosing Undisp => Uncluster ().
  • You can uncluster all current and future displays by disabling Edit => Preferences => Data => Cluster Data Displays.

Node:Creating Multiple Displays, Next:Editing all Displays, Previous:Clustering, Up:Display Basics

Creating Multiple Displays

To display several successive objects of the same type (a section of an array, or an array of dynamically determined size), you can use the notation from..to in display expressions.

from and to are numbers that denote the first and last expression to display. Thus,

graph display argv[0..9]

creates 10 new displays for argv[0], argv[1], ..., argv[9]. The displays are clustered automatically (see Clustering), such that you can easily handle the set just like an array.

The from..to notation can also be used multiple times. For instance,

graph display 1..5 * 1..5

creates a handy small multiplication table.

The from..to notation creates several displays, which takes time to create and update. If you want to display only a part of an array, array slices are a more efficient way. See Array Slices, for a discussion.

Node:Editing all Displays, Next:Deleting Displays, Previous:Creating Multiple Displays, Up:Display Basics

Editing all Displays

You can view the state of all displays by selecting Data => Displays. This invokes the Display Editor.

The Display Editor shows the properties of each display, using the following fields:

Num
The display number.
Expression
The displayed expression.
State
One of
enabled
Normal state.
disabled
Disabled; all details are hidden. Use Show to enable.
not active
Out of scope.
deferred
Will be created as soon as its Scope is reached (see Creating Single Displays).
clustered
Part of a cluster (see Clustering). Use Undisp => Uncluster to uncluster.
alias of display
A suppressed alias of display display (see Shared Structures).

Scope
The scope in which the display was created. For deferred displays, this is the scope in which the display will be created.
Address
The address of the displayed expression. Used for resolving aliases (see Shared Structures).

Node:Deleting Displays, Next:Customizing Displays, Previous:Editing all Displays, Up:Display Basics

Deleting Displays

To delete a single display, select it and click on the Undisp button. As an alternative, you can also press mouse button 3 on the display and select the Undisplay item.

When a display is deleted, its immediate ancestors and descendants are automatically selected, so that you can easily delete entire graphs.

To delete several displays at once, use the Undisp button in the Display Editor (invoked via Data => Displays). Select any number of display items in the usual way and delete them by pressing Undisp.

As an alternative, you can also use a DDD command:

graph undisplay displays...

Here, displays... is either

  • a space-separated list of display numbers to disable or enable, or
  • a single display name. If you specify a display by name, all displays with this name will be affected.

If you are using stacked windows, deleting the last display from the data window also automatically closes the data window. (You can change this via Edit => Preferences => Data => Close data window when deleting last display.)

If you deleted a display by mistake, use Edit => Undo to re-create it.

Finally, you can also cut, copy, and paste displays using the Cut, Copy, and Paste items from the Edit menu. The clipboard holds the commands used to create the displays; Paste inserts the display commands in the debugger console. This allows you to save displays for later usage or to copy displays across multiple DDD instances.

Node:Customizing Displays, Previous:Deleting Displays, Up:Display Basics

Customizing Displays

You can use these resources to control display appearance:

autoCloseDataWindow (class AutoClose) Resource
If this is on (default) and DDD is in stacked window mode, deleting the last display automatically closes the data window. If this is off, the data window stays open even after deleting the last display.

bumpDisplays (class BumpDisplays) Resource
If some display d changes size and this resource is on (default), DDD assigns new positions to displays below and on the right of d such that the distance between displays remains constant. If this is off, other displays are not rearranged.

clusterDisplays (class ClusterDisplays) Resource
If on, new independent data displays will automatically be clustered. Default is off, meaning to leave new displays unclustered.

hideInactiveDisplays (class HideInactiveDisplays) Resource
If some display gets out of scope and this resource is on (default), DDD removes it from the data display. If this is off, it is simply disabled.

showBaseDisplayTitles (class ShowDisplayTitles) Resource
Whether to assign titles to base (independent) displays or not. Default is on.

showDependentDisplayTitles (class ShowDisplayTitles) Resource
Whether to assign titles to dependent displays or not. Default is off.

Node:Displaying Arrays, Next:Assignment, Previous:Display Basics, Up:Displaying Values

Displaying Arrays

DDD has some special features that facilitate handling of arrays.

  • Array Slices: Displaying from..to parts of an array
  • Repeated Values: How repeated values are handled.
  • Arrays as Tables: Displaying two-dimensional arrays.

Node:Array Slices, Next:Repeated Values, Up:Displaying Arrays

Array Slices

It is often useful to print out several successive objects of the same type in memory; a slice (section) of an array, or an array of dynamically determined size for which only a pointer exists in the program.

Using DDD, you can display slices using the from..to notation (see Creating Multiple Displays). But this requires that you already know from and to; it is also inefficient to create several single displays. If you use GDB, you have yet another alternative.

Using GDB, you can display successive objects by referring to a contiguous span of memory as an artificial array, using the binary operator @. The left operand of @ should be the first element of the desired array and be an individual object. The right operand should be the desired length of the array. The result is an array value whose elements are all of the type of the left argument. The first element is actually the left argument; the second element comes from bytes of memory immediately following those that hold the first element, and so on.

Here is an example. If a program says

int *array = (int *) malloc (len * sizeof (int));

you can print the contents of array with

print array[0]@len

and display the contents with

graph display array[0]@len

The general form of displaying an array slice is thus

graph display array[first]@nelems

where array is the name of the array to display, first is the index of the first element, and nelems is the number of elements to display.

The left operand of @ must reside in memory. Array values made with @ in this way behave just like other arrays in terms of subscripting, and are coerced to pointers when used in expressions.

Node:Repeated Values, Next:Arrays as Tables, Previous:Array Slices, Up:Displaying Arrays

Repeated Values

Using GDB, an array value that is repeated 10 or more times is displayed only once. The value is shown with a <nx> postfix added, where n is the number of times the value is repeated. Thus, the display 0x0 <30x> stands for 30 array elements, each with the value 0x0. This saves a lot of display space, especially with homogeneous arrays.

The default GDB threshold for repeated array values is 10. You can change it via Edit => GDB Settings => Threshold for repeated print elements. Setting the threshold to 0 will cause GDB (and DDD) to display each array element individually. Be sure to refresh the data window via Data => Refresh Displays after a change in GDB settings.

You can also configure DDD to display each array element individually:

expandRepeatedValues (class ExpandRepeatedValues) Resource
GDB can print repeated array elements as value <repeated n times>. If expandRepeatedValues is on, DDD will display n instances of value instead. If expandRepeatedValues is off (default), DDD will display value with <nx> appended to indicate the repetition.

Node:Arrays as Tables, Previous:Repeated Values, Up:Displaying Arrays

Arrays as Tables

By default, DDD lays out two-dimensional arrays as tables, such that all array elements are aligned with each other.27 To disable this feature, unset Edit => Preferences => Data => Display Two-Dimensional Arrays as Tables. This is tied to the following resource:

align2dArrays (class Align2dArrays) Resource
If on (default), DDD lays out two-dimensional arrays as tables, such that all array elements are aligned with each other. If off, DDD treats a two-dimensional array as an array of one-dimensional arrays, each aligned on its own.

Node:Assignment, Next:Examining Structures, Previous:Displaying Arrays, Up:Displaying Values

Assignment to Variables

During program execution, you can change the values of arbitrary variables.28

To change the value of a variable, enter its name in ()--for instance, by selecting an occurrence or a display. Then, click on the Set button. In a dialog, you can edit the variable value at will; clicking the OK or Apply button commits your change and assigns the new value to the variable.

To change a displayed value, you can also select Set Value menu from the data popup menu,

If you made a mistake, you can use Edit => Undo to re-set the variable to its previous value.

Node:Examining Structures, Next:Layouting the Graph, Previous:Assignment, Up:Displaying Values

Examining Structures

Besides displaying simple values, DDD can also visualize the Dependencies between values--especially pointers and other references that make up complex data structures.

  • Dependent Values: Edges from values to values.
  • Dereferencing Pointers: Examining pointer-based data structures.
  • Shared Structures: Multiple pointers to one display.
  • Display Shortcuts: Customize your own menus.

Node:Dependent Values, Next:Dereferencing Pointers, Up:Examining Structures

Displaying Dependent Values

Dependent displays are created from an existing display. The dependency is indicated by an edge leading from the originating display to the dependent display.

To create a dependent display, select the originating display or display part and enter the dependent expression in the (): argument field. Then click on the Display button.

Using dependent displays, you can investigate the data structure of a tree for example and lay it out according to your intuitive image of the tree data structure.

By default, DDD does not recognize shared data structures (i.e. a data object referenced by multiple other data objects). See Shared Structures, for details on how to examine such structures.

Node:Dereferencing Pointers, Next:Shared Structures, Previous:Dependent Values, Up:Examining Structures

Dereferencing Pointers

There are special shortcuts for creating dependent displays showing the value of a dereferenced pointer. This allows for rapid examination of pointer-based data structures.

To dereference a pointer, select the originating pointer value or name and click on the Disp * button. A new display showing the dereferenced pointer value is created.

As a faster alternative, you can also press mouse button 3 on the originating pointer value or name and select the Display * menu item.

As an even faster alternative, you can also double-click mouse button 1 on the originating pointer value or name. If you press <Ctrl> while double-clicking, the display will be dereferenced in place-that is, it will be replaced by the dereferenced display.

The Display *() function is also accessible by pressing and holding the Display button.

Node:Shared Structures, Next:Display Shortcuts, Previous:Dereferencing Pointers, Up:Examining Structures

Shared Structures

By default, DDD does not recognize shared data structures--that is, a data object referenced by multiple other data objects. For instance, if two pointers p1 and p2 point at the same data object d, the data displays d, *p1, and *p2 will be separate, although they denote the same object.

DDD provides a special mode which makes it detect these situations. DDD recognizes if two or more data displays are stored at the same physical address, and if this is so, merges all these aliases into one single data display, the original data display. This mode is called Alias Detection; it is enabled via Data => Detect Aliases.

When alias detection is enabled, DDD inquires the memory location (the address) of each data display after each program step. If two displays have the same address, they are merged into one. More specifically, only the one which has least recently changed remains (the original data display); all other aliases are suppressed, i.e. completely hidden. The edges leading to the aliases are replaced by edges leading to the original data display.

An edge created by alias detection is somewhat special: rather than connecting two displays directly, it goes through an edge hint, describing an arc connecting the two displays and the edge hint.

Each edge hint is a placeholder for a suppressed alias; selecting an edge hint is equivalent to selecting the alias. This way, you can easily delete display aliases by simply selecting the edge hint and clicking on Undisp.

To access suppressed display aliases, you can also use the Display Editor. Suppressed displays are listed in the Display Editor as aliases of the original data display. Via the Display Editor, you can select, change, and delete suppressed displays.

Suppressed displays become visible again as soon as

  • alias detection is disabled,
  • their address changes such that they are no more aliases, or
  • the original data display is deleted, such that the least recently changed alias becomes the new original data display.

Please note the following caveats with alias detection:

  • Alias detection requires that the current programming language provides a means to determine the address of an arbitrary data object. Currently, only C, C++, and Java are supported.
  • Some inferior debuggers (for instance, SunOS DBX) produce incorrect output for address expressions. Given a pointer p, you may verify the correct function of your inferior debugger by comparing the values of p and &p (unless p actually points to itself). You can also examine the data display addresses, as shown in the Display Editor.
  • Alias detection slows down DDD slightly, which is why it is disabled by default. You may consider to enable it only at need--for instance, while examining some complex data structure--and disable it while examining control flow (i.e., stepping through your program). DDD will automatically restore edges and data displays when switching modes.

Alias detection is controlled by the following resources:

deleteAliasDisplays (class DeleteAliasDisplays) Resource
If this is on (default), the Undisplay () button also deletes all aliases of the selected displays. If this is off, only the selected displays are deleted; the aliases remain, and one of the aliases will be unsuppressed.

detectAliases (class DetectAliases) Resource
If on, DDD attempts to recognize shared data structures. The default is off, meaning that shared data structures are not recognized.

typedAliases (class TypedAliases) Resource
If on (default), DDD requires structural equivalence in order to recognize shared data structures. If this is off, two displays at the same address are considered aliases, regardless of their structure.

Node:Display Shortcuts, Previous:Shared Structures, Up:Examining Structures

Display Shortcuts

DDD maintains a shortcut menu of frequently used display expressions. This menu is activated

  • by pressing and holding the Display button, or
  • by pressing mouse button 3 on some display and selecting New Display, or
  • by pressing <Shift> and mouse button 3 on some display.

By default, the shortcut menu contains frequently used base conversions.

The Other entry in the shortcut menu lets you create a new display that extends the shortcut menu.

As an example, assume you have selected a display named date_ptr. Selecting Display => Other pops up a dialog that allows you to enter a new expression to be displayed--for instance, you can cast the display date_ptr to a new display (char *)date_ptr. If the Include in New Display Menu toggle was activated, the shortcut menu will then contain a new entry Display (char *)() that will cast any selected display display to (char *)display. Such shortcuts can save you a lot of time when examining complex data structures.

You can edit the contents of the New Display menu by selecting its Edit Menu item. This pops up the Shortcut Editor containing all shortcut expressions, which you can edit at leisure. Each line contains the expression for exactly one menu item. Clicking on Apply re-creates the New Display menu from the text. If the text is empty, the New Display menu will be empty, too.

DDD also allows you to specify individual labels for user-defined buttons. You can write such a label after the expression, separated by //. This feature is used in the default contents of the GDB New Display menu, where each of the base conversions has a label:

/t ()	// Convert to Bin
/d ()	// Convert to Dec
/x ()	// Convert to Hex
/o ()	// Convert to Oct

Feel free to add other conversions here. DDD supports up to 20 New Display menu items.

The shortcut menu is controlled by the following resources:

dbxDisplayShortcuts (class DisplayShortcuts) Resource
A newline-separated list of display expressions to be included in the New Display menu for DBX.

If a line contains a label delimiter29, the string before the delimiter is used as expression, and the string after the delimiter is used as label. Otherwise, the label is Display expression. Upon activation, the string () in expression is replaced by the name of the currently selected display.

gdbDisplayShortcuts (class DisplayShortcuts) Resource
A newline-separated list of display expressions to be included in the New Display menu for GDB. See the description of dbxDisplayShortcuts, above.

jdbDisplayShortcuts (class DisplayShortcuts) Resource
A newline-separated list of display expressions to be included in the New Display menu for JDB. See the description of dbxDisplayShortcuts, above.

perlDisplayShortcuts (class DisplayShortcuts) Resource
A newline-separated list of display expressions to be included in the New Display menu for Perl. See the description of dbxDisplayShortcuts, above.

pydbDisplayShortcuts (class DisplayShortcuts) Resource
A newline-separated list of display expressions to be included in the New Display menu for PYDB. See the description of dbxDisplayShortcuts, above.

xdbDisplayShortcuts (class DisplayShortcuts) Resource
A newline-separated list of display expressions to be included in the New Display menu for XDB. See the description of dbxDisplayShortcuts, above.

Node:Layouting the Graph, Next:Printing the Graph, Previous:Examining Structures, Up:Displaying Values

Layouting the Graph

If you have several displays at once, you may wish to arrange them according to your personal preferences. This section tells you how you can do this.

  • Moving Displays:
  • Scrolling Data:
  • Aligning Displays:
  • Automatic Layout:
  • Rotating the Graph:

Node:Moving Displays, Next:Scrolling Data, Up:Layouting the Graph

Moving Displays

From time to time, you may wish to move displays at another place in the data window. You can move a single display by pressing and holding mouse button 1 on the display title. Moving the pointer while holding the button causes all selected displays to move along with the pointer.

Edge hints can be selected and moved around like other displays. If an arc goes through the edge hint, you can change the shape of the arc by moving the edge hint around.

For fine-grain movements, selected displays may also be moved using the arrow keys. Pressing <Shift> and an arrow key moves displays by single pixels. Pressing <Ctrl> and arrow keys moves displays by grid positions.

Node:Scrolling Data, Next:Aligning Displays, Previous:Moving Displays, Up:Layouting the Graph

Scrolling Data

If the data window becomes too small to hold all displays, scroll bars are created. If your DDD is set up to use panners instead, a panner is created in the lower right edge. When the panner is moved around, the window view follows the position of the panner.

To change from scroll bars to panners, use Edit => Startup => Data Scrolling and choose either Panner or Scrollbars.

This setting is tied to the following resource:

pannedGraphEditor (class PannedGraphEditor) Resource
The control to scroll the graph.
  • If this is on, an Athena panner is used (a kind of two-directional scrollbar).
  • If this is off (default), two Motif scrollbars are used.

See Options, for the --scrolled-graph-editor and --panned-graph-editor options.

Node:Aligning Displays, Next:Automatic Layout, Previous:Scrolling Data, Up:Layouting the Graph

Aligning Displays

You can align all displays on the nearest grid position by selecting Data => Align on Grid. This is useful for keeping edges strictly horizontal or vertical.

You can enforce alignment by selecting Edit => Preferences => Data => Auto-align Displays on Nearest Grid Point. If this feature is enabled, displays can be moved on grid positions only.

Node:Automatic Layout, Next:Rotating the Graph, Previous:Aligning Displays, Up:Layouting the Graph

Automatic Layout

You can layout the entire graph as a tree by selecting Data => Layout Graph.

Layouting the graph may introduce edge hints; that is, edges are no more straight lines, but lead to an edge hint and from there to their destination. Edge hints can be moved around like arbitrary displays.

To enable a more compact layout, you can set the Edit => Preferences => Data => Compact Layout option. This realizes an alternate layout algorithm, where successors are placed next to their parents. This algorithm is suitable for homogeneous data structures only.

You can enforce layout by setting Edit => Preferences => Data => Automatic Layout. If automatic layout is enabled, the graph is layouted after each change.

Node:Rotating the Graph, Previous:Automatic Layout, Up:Layouting the Graph

Rotating the Graph

You can rotate the entire graph clockwise by 90 degrees by selecting Data => Rotate Graph.

If the graph was previously layouted, you may need to layout it again. Subsequent layouts will respect the direction of the last rotation.

Node:Printing the Graph, Next:How Displays are Created, Previous:Layouting the Graph, Up:Displaying Values

Printing the Graph

DDD allows for printing the graph picture on PostScript printers or into files. This is useful for documenting program states.

To print the graph on a PostScript printer, select File => Print Graph. Enter the printing command in the Print Command field. Click on the OK or the Apply button to start printing.

As an alternative, you may also print the graph in a file. Click on the File button and enter the file name in the File Name field. Click on the Print button to create the file.

When the graph is printed in a file, two formats are available:

  • PostScript--suitable for enclosing the graph in another document;
  • FIG--suitable for post-processing, using the xfig graphic editor, or for conversion into other formats (among others, IBMGL, TeX, PIC), using the transfig or fig2dev programs.

Please note the following caveats related to printing graphs:

  • If any displays were selected when invoking the Print dialog, the option Selected Only is set. This makes DDD print only the selected displays.
  • The Color, Orientation, and Paper Size options are meaningful for PostScript only.

These settings are tied to the following resources:

printCommand (class PrintCommand) Resource
The command to print a PostScript file. Usually lp or lpr.

paperSize (class PaperSize) Resource
The paper size used for printing, in format width x height. The default is ISO A4 format, or 210mm x 297mm.

Node:How Displays are Created, Previous:Printing the Graph, Up:Displaying Values

How Displays are Created

This section discusses how DDD actually creates displays from data.

  • Handling Boxes:
  • Building Boxes from Data:
  • Customizing Display Appearance:

Node:Handling Boxes, Next:Building Boxes from Data, Up:How Displays are Created

Handling Boxes

All data displayed in the DDD data window is maintained by the inferior debugger. GDB, for instance, provides a display list, holding symbolic expressions to be evaluated and printed on standard output at each program stop. The GDB command display tree adds tree to the display list and makes GDB print the value of tree as, say, tree = (Tree *)0x20e98, at each program stop. This GDB output is processed by DDD and displayed in the data window.

Each element of the display list, as transmitted by the inferior debugger, is read by DDD and translated into a box. Boxes are rectangular entities with a specific content that can be displayed in the data window. We distinguish atomic boxes and composite boxes. An atomic box holds white or black space, a line, or a string. Composite boxes are horizontal or vertical alignments of other boxes. Each box has a size and an extent that determines how it fits into a larger surrounding space.

Through construction of larger and larger boxes, DDD constructs a graph node from the GDB data structure in a similar way a typesetting system like TeX builds words from letters and pages from paragraphs.

Such constructions are easily expressed by means of functions mapping boxes onto boxes. These display functions can be specified by the user and interpreted by DDD, using an applicative language called VSL for visual structure language. VSL functions can be specified by the DDD user, leaving much room for extensions and customization. A VSL display function putting a frame around its argument looks like this:

// Put a frame around TEXT
frame(text) = hrule()
  | vrule() & text & vrule()
  | hrule();

Here, hrule() and vrule() are primitive functions returning horizontal and vertical lines, respectively. The & and | operators construct horizontal and vertical alignments fro their arguments.

VSL provides basic facilities like pattern matching and variable numbers of function arguments. The halign() function, for instance, builds a horizontal alignment from an arbitrary number of arguments, matched by three dots (...):

// Horizontal alignment
halign(x) = x;
halign(x, ...) = x & halign(...);

Frequently needed functions like halign() are grouped into a standard VSL library.

Node:Building Boxes from Data, Next:Customizing Display Appearance, Previous:Handling Boxes, Up:How Displays are Created

Building Boxes from Data

To visualize data structures, each atomic type and each type constructor from the programming language is assigned a VSL display function. Atomic values like numbers, characters, enumerations, or character strings are displayed using string boxes holding their value; the VSL function to display them leaves them unchanged:

// Atomic Values
simple_value(value) = value;

Composite values require more attention. An array, for instance, may be displayed using a horizontal alignment:

// Array
array(...) = frame(halign(...));

When GDB sends DDD the value of an array, the VSL function array() is invoked with array elements as values. A GDB array expression {1, 2, 3} is thus evaluated in VSL as

array(simple_value("1"), simple_value("2"), simple_value("3"))

which equals

"1" & "2" & "3"

a composite box holding a horizontal alignment of three string boxes. The actual VSL function used in DDD also puts delimiters between the elements and comes in a vertical variant as well.

Nested structures like multi-dimensional arrays are displayed by applying the array() function in a bottom-up fashion. First, array() is applied to the innermost structures; the resulting boxes are then passed as arguments to another array() invocation. The GDB output

{{"A", "B", "C"}, {"D", "E", "F"}}

representing a 2 * 3 array of character strings, is evaluated in VSL as

array(array("A", "B", "C"), array("A", "B", "C"))

resulting in a horizontal alignment of two more alignments representing the inner arrays.

Record structures are built in a similar manner, using a display function struct\_member rendering the record members. Names and values are separated by an equality sign:

// Member of a record structure
struct_member (name, value) =
  name & " = " & value;

The display function struct renders the record itself, using the valign() function.30

// Record structure
struct(...) = frame(valign(...));

This is a simple example; the actual VSL function used in DDD takes additional effort to align the equality signs; also, it ensures that language-specific delimiters are used, that collapsed structs are rendered properly, and so on.

Node:Customizing Display Appearance, Previous:Building Boxes from Data, Up:How Displays are Created

Customizing Display Appearance

DDD comes with a built-in VSL library that should suffice for most, if not all, purposes. Using the following resources, one can change and enhance the VSL definitions:

vslBaseDefs (class VSLDefs) Resource
A string with additional VSL definitions that are appended to the builtin VSL library. This resource is prepended to the vslDefs resource below and set in the DDD application defaults file; don't change it.

vslDefs (class VSLDefs) Resource
A string with additional VSL definitions that are appended to the builtin VSL library. The default value is an empty string. This resource can be used to override specific VSL definitions that affect the data display.

The general pattern to replace a function definition function with a new definition new_def is:

#pragma replace function
function(args...) = new_def;

The following VSL functions are frequently used:

color(box, foreground [, background])
Set the foreground and background colors of box.
display_color(box)
The color used in data displays. Default: color(box, "black", "white")
title_color(box)
The color used in the title bar. Default: color(box, "black")
disabled_color(box)
The color used for disabled boxes. Default: color(box, "white", "grey50")
simple_color(box)
The color used for simple values. Default: color(box, "black")
pointer_color(box)
The color used for pointers. Default: color(box, "blue4")
struct_color(box)
The color used for structures. Default: color(box, "black")
array_color(box)
The color used for arrays. Default: color(box, "blue4")
reference_color(box)
The color used for references. Default: color(box, "blue4")
changed_color(box)
The color used for changed values. Default: color(box, "black", "#ffffcc")
stdfontfamily()
The font family used. One of family_times(), family_courier(), family_helvetica(), family_new_century(), or family_typewriter() (default).
stdfontsize()
The font size used (in pixels). 0 (default) means to use stdfontpoints() instead.
stdfontpoints()
The font size used (in 1/10 points). 0 means to use stdfontsize() instead. Default value: 90.
stdfontweight()
The font weight used. This is either weight_medium() (default) or weight_bold().

To set the pointer color to "red4", use

Ddd*vslDefs: \
#pragma replace pointer_color\n\
pointer_color(box) = color(box, "red4");\n

To set the default font size to resolution-independent 10.0 points, use

Ddd*vslDefs: \
#pragma replace stdfontsize\n\
#pragma replace stdfontpoints\n\
stdfontsize() = 0;\n
stdfontpoints() = 100;\n

To set the default font to 12-pixel courier, use

Ddd*vslDefs: \
#pragma replace stdfontsize\n\
#pragma replace stdfontfamily\n\
stdfontsize() = 12;\n\
stdfontfamily() = family_courier();\n

See the file ddd.vsl for further definitions to override using the vslDefs resource.

vslLibrary (class VSLLibrary) Resource
The VSL library to use. builtin (default) means to use the built-in library, any other value is used as file name.

vslPath (class VSLPath) Resource
A colon-separated list of directories to search for VSL include files. Default is ., the current directory.

If your DDD source distribution is installed in /opt/src, you can use the following settings to read the VSL library from /home/joe/ddd.vsl:

Ddd*vslLibrary: /home/joe/ddd.vsl
Ddd*vslPath:    .:/opt/src/ddd/ddd:/opt/src/ddd/vsllib

VSL include files referenced by /home/joe/ddd.vsl are searched first in the current directory ., then in /opt/src/ddd/ddd/, and then in /opt/src/ddd/vsllib/.

Instead of supplying another VSL library, it is often easier to specify some minor changes to the built-in library. See the vslDefs resource, above, for details.

Node:Plotting Values, Next:Examining Memory, Previous:Displaying Values, Up:Examining Data

Plotting Values

If you have huge amounts of numerical data to examine, a picture often says more than a thousand numbers. Therefore, DDD allows you to draw numerical values in nice 2-D and 3-D plots.

  • Plotting Arrays: Plotting 1-D and 2-D arrays.
  • Plot Appearance: Controlling the appearance.
  • Scalars and Composites: Plotting simple values.
  • Plotting Histories: Plotting the history of a variable.
  • Printing Plots: Printing on paper.
  • Entering Plotting Commands: Raw Gnuplot commands.
  • Exporting Plot Data: Processing data outside of DDD
  • Animating Plots: Visualizing dynamic behaviour.
  • Customizing Plots: All at your leisure.

Node:Plotting Arrays, Next:Plot Appearance, Up:Plotting Values

Plotting Arrays

Basically, DDD can plot two types of numerical values:

  • One-dimensional arrays. These are drawn in a 2-D x/y space, where x denotes the array index, and y the element value.
  • Two-dimensional arrays. These are drawn in a 3-D x/y/z space, where x and y denote the array indexes, and z the element value.

To plot a fixed-size array, select its name by clicking mouse button 1 on an occurrence. The array name is copied to the argument field. By clicking the Plot button, a new display is created in the data window, followed by a new top-level window containing the value plot.

To plot a dynamically sized array, you must use an array slice (see Array Slices). In the argument field, enter

array[first]@nelems

where array is the name of the array to display, first is the index of the first element, and nelems is the number of elements to display. Then, click on Plot to start the plot.

To plot a value, you can also enter a command at the debugger prompt:

graph plot expr

works like graph display expr (and takes the same arguments; see Creating Single Displays), but the value is additionally shown in the plot window.

Each time the value changes during program execution, the plot is updated to reflect the current values. The plot window remains active until you close it (via File => Close) or until the associated display is deleted.

Node:Plot Appearance, Next:Scalars and Composites, Previous:Plotting Arrays, Up:Plotting Values

Changing the Plot Appearance

The actual drawing is not done by DDD itself. Instead, DDD relies on an external gnuplot program to create the drawing.

DDD adds a menu bar to the Gnuplot plot window that lets you influence the appearance of the plot:

  • The View menu toggles optional parts of the plot, such as border lines or a background grid.
  • The Plot menu changes the plotting style. The 3-D Lines option is useful for plotting two-dimensional arrays.
  • The Scale menu allows you to enable logarithmic scaling and to enable or disable the scale tics.
  • The Contour menu adds contour lines to 3-D plots.

In a 3-D plot, you can use the scroll bars to change your view position. The horizontal scroll bar rotates the plot around the z axis, that is, to the left and right. The vertical scroll bar rotates the plot around the y axis, that is, up and down.

You can also resize the plot window as desired.

Node:Scalars and Composites, Next:Plotting Histories, Previous:Plot Appearance, Up:Plotting Values

Plotting Scalars and Composites

Besides plotting arrays, DDD also allows you to plot scalars (simple numerical values). This works just like plotting arrays--you select the numerical variable, click on Plot, and here comes the plot. However, plotting a scalar is not very exciting. A plot that contains nothing but a scalar simply draws the scalar's value as a y constant--that is, a horizontal line.

So why care about scalars at all? DDD allows you to combine multiple values into one plot. The basic idea is: if you want to plot something that is neither an array nor a scalar, DDD takes all numerical sub-values it can find and plots them all together in one window. For instance, you can plot all local variables by selecting Data => Display Local Variables, followed by Plot. This will create a plot containing all numerical values as found in the current local variables. Likewise, you can plot all numeric members contained in a structure by selecting it, followed by Plot.

If you want more control about what to include in a plot and what not, you can use display clusters (see Clustering). A common scenario is to plot a one-dimensional array together with the current index position. This is done in three steps:

  1. Display the array and the index, using Display.
  2. Cluster both displays: select them and choose Undisp => Cluster ().
  3. Plot the cluster by pressing Plot.

Scalars that are displayed together with arrays can be displayed either as vertical lines or horizontal lines. By default, scalars are plotted as horizontal lines. However, if a scalar is a valid index for an array that was previously plotted, it is shown as a vertical line. You can change this initial orientation by selecting the scalar display, followed by Rotate.

Node:Plotting Histories, Next:Printing Plots, Previous:Scalars and Composites, Up:Plotting Values

Plotting Display Histories

At each program stop, DDD records the values of all displayed variables, such that you can "undo" program execution (see Undoing Program Execution). These display histories can be plotted, too. The menu item Plot => Plot history of () creates a plot that shows all previously recorded values of the selected display.

Node:Printing Plots, Next:Entering Plotting Commands, Previous:Plotting Histories, Up:Plotting Values

Printing Plots

If you want to print the plot, select File => Print Plot. This pops up the DDD printing dialog, set up for printing plots. Just as when printing graphs, you have the choice between printing to a printer or a file and setting up appropriate options.

The actual printing is also performed by Gnuplot, using the appropriate driver. Please note the following caveats related to printing:

  • Creating FIG files requires an appropriate driver built into Gnuplot. Your Gnuplot program may not contain such a driver. In this case, you will have to recompile Gnuplot, including the line #define FIG in the Gnuplot term.h file.
  • The Portrait option generates an EPS file useful for inclusion in other documents. The Landscape option makes DDD print the plot in the size specified in the Paper Size option; this is useful for printing on a printer. In Portrait mode, the Paper Size option is ignored.
  • The Gnuplot device drivers for PostScript and X11 each have their own set of colors, such that the printed colors may differ from the displayed colors.
  • The Selected Only option is set by default, such that only the currently selected plot is printed. (If you select multiple plots to be printed, the respective outputs will all be concatenated, which may not be what you desire.)

Node:Entering Plotting Commands, Next:Exporting Plot Data, Previous:Printing Plots, Up:Plotting Values

Entering Plotting Commands

Via File => Command, you can enter Gnuplot commands directly. Each command entered at the gnuplot> prompt is passed to Gnuplot, followed by a Gnuplot replot command to update the view. This is useful for advanced Gnuplot tasks.

Here's a simple example. The Gnuplot command

set xrange [xmin:xmax]

sets the horizontal range that will be displayed to xmin...xmax. To plot only the elements 10 to 20, enter:

gnuplot> set xrange [10:20]

After each command entered, DDD adds a replot command, such that the plot is updated automatically.

Here's a more complex example. The following sequence of Gnuplot commands saves the plot in TeX format:

gnuplot> set output "plot.tex" # Set the output filename
gnuplot> set term latex        # Set the output format
gnuplot> set term x11          # Show original picture again

Due to the implicit replot command, the output is automatically written to plot.tex after the set term latex command.

The dialog keeps track of the commands entered; use the arrow keys to restore previous commands. Gnuplot error messages (if any) are also shown in the history area.

The interaction between DDD and Gnuplot is logged in the file ~/.ddd/log (see Logging). The DDD --trace option logs this interaction on standard output.

Node:Exporting Plot Data, Next:Animating Plots, Previous:Entering Plotting Commands, Up:Plotting Values

Exporting Plot Data

If you want some external program to process the plot data (a stand-alone Gnuplot program or the xmgr program, for instance), you can save the plot data in a file, using File => Save Data As. This pops up a dialog that lets you choose a data file to save the plotted data in.

The generated file starts with a few comment lines. The actual data follows in X/Y or X/Y/Z format. It is the same file as processed by Gnuplot.

Node:Animating Plots, Next:Customizing Plots, Previous:Exporting Plot Data, Up:Plotting Values

Animating Plots

If you want to see how your data evolves in time, you can set a breakpoint whose command sequence ends in a cont command (see Breakpoint Commands. Each time this "continue" breakpoint is reached, the program stops and DDD updates the displayed values, including the plots. Then, DDD executes the breakpoint command sequence, resuming execution.

This way, you can set a "continue" breakpoint at some decisive point within an array-processing algorithm and have DDD display the progress graphically. When your program has stopped for good, you can use Undo and Redo to redisplay and examine previous program states. See Undoing Program Execution, for details.

Node:Customizing Plots, Previous:Animating Plots, Up:Plotting Values

Customizing Plots

You can customize the Gnuplot program to invoke, as well as a number of basic settings.

  • Gnuplot Invocation:
  • Gnuplot Settings:

Node:Gnuplot Invocation, Next:Gnuplot Settings, Up:Customizing Plots

Gnuplot Invocation

Using Edit => Preferences => Helpers => Plot, you can choose the Gnuplot program to invoke. This is tied to the following resource:

plotCommand (class PlotCommand) Resource
The name of a Gnuplot executable. Default is gnuplot, followed by some options to set up colors and the initial geometry.

Using Edit => Preferences => Helpers => Plot Window, you can choose whether to use the Gnuplot plot window (External) or to use the plot window supplied by DDD (builtin). This is tied to the following resource:

plotTermType (class PlotTermType) Resource
The Gnuplot terminal type. Can have one of two values:
  • If this is x11, DDD "swallows" the external Gnuplot output window into its own user interface. Some window managers, notably mwm, have trouble with swallowing techniques.
  • Setting this resource to xlib (default) makes DDD provide a builtin plot window instead. In this mode, plots work well with any window manager, but are less customizable (Gnuplot resources are not understood).

You can further control interaction with the external plot window:

plotWindowClass (class PlotWindowClass) Resource
The class of the Gnuplot output window. When invoking Gnuplot, DDD waits for a window with this class and incorporates it into its own user interface (unless plotTermType is xlib; see above). Default is Gnuplot.

plotWindowDelay (class WindowDelay) Resource
The time (in ms) to wait for the creation of the Gnuplot window. Before this delay, DDD looks at each newly created window to see whether this is the plot window to swallow. This is cheap, but unfortunately, some window managers do not pass the creation event to DDD. If this delay has passed, and DDD has not found the plot window, DDD searches all existing windows, which is pretty expensive. Default time is 2000.

Node:Gnuplot Settings, Previous:Gnuplot Invocation, Up:Customizing Plots

Gnuplot Settings

To change Gnuplot settings, use these resources:

plotInitCommands (class PlotInitCommands) Resource
The initial Gnuplot commands issued by DDD. Default is:
set parametric
set urange [0:1]
set vrange [0:1]
set trange [0:1]

The parametric setting is required to make Gnuplot understand the data files as generated DDD. The range commands are used to plot scalars.

See the Gnuplot documentation for additional commands.

plot2dSettings (class PlotSettings) Resource
Additional initial settings for 2-D plots. Default is set noborder. Feel free to customize these settings as desired.

plot3dSettings (class PlotSettings) Resource
Additional initial settings for 3-D plots. Default is set border. Feel free to customize these settings as desired.

Node:Examining Memory, Previous:Plotting Values, Up:Examining Data

Examining Memory

Using GDB or DBX, you can examine memory in any of several formats, independently of your program's data types. The item Data => Memory pops up a panel where you can choose the format to be shown.

In the panel, you can enter

  • a repeat count, a decimal integer that specifies how much memory (counting by units) to display
  • a display format--one of
    octal
    Print as integer in octal
    hex
    Regard the bits of the value as an integer, and print the integer in hexadecimal.
    decimal
    Print as integer in signed decimal.
    unsigned
    Print as integer in unsigned decimal.
    binary
    Print as integer in binary.
    float
    Regard the bits of the value as a floating point number and print using typical floating point syntax.
    address
    Print as an address, both absolute in hexadecimal and as an offset from the nearest preceding symbol.
    instruction
    Print as machine instructions. The unit size is ignored for this display format.
    char
    Regard as an integer and print it as a character constant.
    string
    Print as null-terminated string. The unit size is ignored for this display format.
  • a unit size--one of
    bytes
    Bytes.
    halfwords
    Halfwords (two bytes).
    words
    Words (four bytes).
    giants
    Giant words (eight bytes).
  • an address--the starting display address. The expression need not have a pointer value (though it may); it is always interpreted as an integer address of a byte of memory.

There are two ways to examine the values:

  • You can dump the memory in the debugger console (using Print). If you repeat the resulting x command by pressing <Return> in the debugger console (see Command History), the following area of memory is shown.
  • You can also display the memory dump in the data window (using Display). If you choose to display the values, the values will be updated automatically each time the program stop.

Node:Machine-Level Debugging, Next:Changing the Program, Previous:Examining Data, Up:Top

Machine-Level Debugging

Sometimes, it is desirable to examine a program not only at the source level, but also at the machine level. DDD provides special machine code and register windows for this task.

  • Machine Code: Examining machine code.
  • Machine Code Execution: Stepping across instructions.
  • Registers: Examining registers.
  • Customizing Machine Code: Settings.

Node:Machine Code, Next:Machine Code Execution, Up:Machine-Level Debugging

Examining Machine Code

To enable machine-level support, select Source => Display Machine Code. With machine code enabled, an additional machine code window shows up, displaying the machine code of the current function.31 By moving the sash at the right of the separating line between source and machine code, you can resize the source and machine code windows.

The machine code window works very much like the source window. You can set, clear, and change breakpoints by selecting the address and pressing a Break or Clear button; the usual popup menus are also available. Breakpoints and the current execution position are displayed simultaneously in both source and machine code.

The Lookup button can be used to look up the machine code for a specific function--or the function for a specific address. Just click on the location in one window and press Lookup to see the corresponding code in the other window.

If source code is not available, only the machine code window is updated.

You can customize various aspects of the disassembling window. See Customizing Machine Code, for details.

Node:Machine Code Execution, Next:Registers, Previous:Machine Code, Up:Machine-Level Debugging

Machine Code Execution

All execution facilities available in the source code window are available in the machine code window as well. Two special facilities are convenient for machine-level debugging:

To execute just one machine instruction, click on the Stepi button or select Program => Step Instruction.

To continue to the next instruction in the current function, click on the Nexti button select Program => Next Instruction.. This is similar to Stepi, but any subroutine calls are executed without stopping.

Using GDB, it is often useful to do

graph display /i $pc

when stepping by machine instructions. This makes DDD automatically display the next instruction to be executed, each time your program stops.

Node:Registers, Next:Customizing Machine Code, Previous:Machine Code Execution, Up:Machine-Level Debugging

Examining Registers

DDD provides a register window showing the machine register values after each program stop. To enable the register window, select Status => Registers.32

By selecting one of the registers, its name is copied to the argument field. You can use it as value for Display, for instance, to have its value displayed in the data window.

Node:Customizing Machine Code, Previous:Registers, Up:Machine-Level Debugging

Customizing Machine Code

Enabling machine code via Source => Display Machine Code (see Machine Code) toggles the following resource:

disassemble (class Disassemble) Resource
If this is on, the source code is automatically disassembled. The default is off. See Options, for the --disassemble and --no-disassemble options.

You can keep disassembled code in memory, using Edit => Preferences => Source => Cache Machine Code:

cacheMachineCode (class CacheMachineCode) Resource
Whether to cache disassembled machine code (on, default) or not (off). Caching machine code requires more memory, but makes DDD run faster.

You can control the indentation of machine code, using Edit => Preferences => Source => Machine Code Indentation:

indentCode (class Indent) Resource
The number of columns to indent the machine code, such that there is enough place to display breakpoint locations. Default: 4.

The maxDisassemble resource controls how much is to be disassembled. If maxDisassemble is set to 256 (default) and the current function is larger than 256 bytes, DDD only disassembles the first 256 bytes below the current location. You can set the maxDisassemble resource to a larger value if you prefer to have a larger machine code view.

maxDisassemble (class MaxDisassemble) Resource
Maximum number of bytes to disassemble (default: 256). If this is zero, the entire current function is disassembled.

Node:Changing the Program, Next:Commands, Previous:Machine-Level Debugging, Up:Top

Changing the Program

DDD offers some basic facilities to edit and recompile the source code, as well as patching executables and core files.

  • Editing Source Code: You can invoke a source editor from DDD.
  • Recompiling: Invoking make from within DDD.
  • Patching: Changing source and object code.

Node:Editing Source Code, Next:Recompiling, Up:Changing the Program

Editing Source Code

In DDD itself, you cannot change the source file currently displayed. Instead, DDD allows you to invoke a text editor. To invoke a text editor for the current source file, select the Edit button or Source => Edit Source.

By default, DDD tries a number of common editors. You can customize DDD to use your favorite editor; See Customizing Editing, for details.

After the editor has exited, the source code shown is automatically updated.

If you have DDD and an editor running in parallel, you can also update the source code manually via Source => Reload Source. This reloads the source code shown from the source file. Since DDD automatically reloads the source code if the debugged program has been recompiled, this should seldom be necessary.

  • Customizing Editing:
  • In-Place Editing:

Node:Customizing Editing, Next:In-Place Editing, Up:Editing Source Code

Customizing Editing

You can customize the editor to be used via Edit => Preferences => Helpers => Edit Sources. This is tied to the following resource:

editCommand (class EditCommand) Resource
A command string to invoke an editor on the specific file. @LINE@ is replaced by the current line number, @FILE@ by the file name. The default is to invoke $XEDITOR first, then $EDITOR, then vi:
Ddd*editCommand: \
${XEDITOR-false} +@LINE@ @FILE@ || \
xterm -e ${EDITOR-vi} +@LINE@ @FILE@

This ~/.ddd/init setting invokes an editing session for an XEmacs editor running gnuserv:

Ddd*editCommand: gnuclient +@LINE@ @FILE@

This ~/.ddd/init setting invokes an editing session for an Emacs editor running emacsserver:

Ddd*editCommand: emacsclient +@LINE@ @FILE@

Node:In-Place Editing, Previous:Customizing Editing, Up:Editing Source Code

In-Place Editing

This resource is experimental:

sourceEditing (class SourceEditing) Resource
If this is on, the displayed source code becomes editable. This is an experimental feature and may become obsolete in future DDD releases. Default is off.

Node:Recompiling, Next:Patching, Previous:Editing Source Code, Up:Changing the Program

Recompiling

To recompile the source code using make, you can select File => Make. This pops up a dialog where you can enter a Make Target--typically the name of the executable. Clicking on the Make button invokes the make program with the given target.

The Make button on the command tool re-invokes make with the most recently given arguments.

Node:Patching, Previous:Recompiling, Up:Changing the Program

Patching

Using GDB, you can open your program's executable code (and the core file) for both reading and writing. This allows alterations to machine code, such that you can intentionally patch your program's binary. For example, you might want to turn on internal debugging flags, or even to make emergency repairs.

To patch the binary, enable Edit => GDB Settings => Writing into executable and core files. This makes GDB open executable and core files for both reading and writing. If you have already loaded a file, you must load it again (using Edit => Open File or Edit => Open Core), for your new setting to take effect.

Be sure to turn off Writing into executable and core files as soon as possible, to prevent accidental alterations to machine code.

Node:Commands, Next:Application Defaults, Previous:Changing the Program, Up:Top

The Command-Line Interface

All the buttons you click within DDD get eventually translated into some debugger command, shown in the debugger console. You can also type in and edit these commands directly.

  • Entering Commands: Direct interaction with the inferior debugger.
  • TTY mode: Controlling DDD from a terminal.
  • Integrating DDD: DDD and your programming environment.
  • Defining Buttons: Add your own DDD buttons.
  • Defining Commands: Add your own DDD commands.

Node:Entering Commands, Next:TTY mode, Up:Commands

Entering Commands

In the debugger console, you can interact with the command interface of the inferior debugger. Enter commands at the debugger prompt--that is, (gdb) for GDB, (dbx) for DBX, (ladebug) for Ladebug, > for XDB, > and thread[depth] for JDB, or (Pydb) for PYDB, or DB<> for Perl. You can use arbitrary debugger commands; use the <Return> key to enter them.

  • Command Completion: Using the <TAB> key.
  • Command History: Repeating previous commands.

Node:Command Completion, Next:Command History, Up:Entering Commands

Command Completion

When using GDB or Perl, you can use the <TAB> key for completing commands and arguments. This works in the debugger console as well as in all other text windows.

GDB can fill in the rest of a word in a command for you, if there is only one possibility; it can also show you what the valid possibilities are for the next word in a command, at any time. This works for GDB commands, GDB subcommands, and the names of symbols in your program.

Press the <TAB> key whenever you want GDB to fill out the rest of a word. If there is only one possibility, GDB fills in the word, and waits for you to finish the command (or press <RET> to enter it). For example, if you type

(gdb) info bre <TAB>

GDB fills in the rest of the word breakpoints, since that is the only info subcommand beginning with bre:

(gdb) info breakpoints

You can either press <RET> at this point, to run the info breakpoints command, or backspace and enter something else, if breakpoints does not look like the command you expected. (If you were sure you wanted info breakpoints in the first place, you might as well just type <RET> immediately after info bre, to exploit command abbreviations rather than command completion).

If there is more than one possibility for the next word when you press <TAB>, DDD sounds a bell. You can either supply more characters and try again, or just press <TAB> a second time; GDB displays all the possible completions for that word. For example, you might want to set a breakpoint on a subroutine whose name begins with make_, but when you type b make_<TAB>, DDD just sounds the bell. Typing <TAB> again displays all the function names in your program that begin with those characters. If you type <TAB> again, you cycle through the list of completions, for example:

(gdb) b make_ <TAB>

DDD sounds bell; press <TAB> again, to see:

make_a_section_from_file     make_environ
make_abs_section             make_function_type
make_blockvector             make_pointer_type
make_cleanup                 make_reference_type
make_command                 make_symbol_completion_list
(gdb) b make_ <TAB>

DDD presents one expansion after the other:

(gdb) b make_a_section_from_file <TAB>
(gdb) b make_abs_section <TAB>
(gdb) b make_blockvector <TAB>

After displaying the available possibilities, GDB copies your partial input (b make_ in the example) so you can finish the command--by pressing <TAB> again, or by entering the remainder manually.

Sometimes the string you need, while logically a "word", may contain parentheses or other characters that GDB normally excludes from its notion of a word. To permit word completion to work in this situation, you may enclose words in ' (single quote marks) in GDB commands.

The most likely situation where you might need this is in typing the name of a C++ function. This is because C++ allows function overloading (multiple definitions of the same function, distinguished by argument type). For example, when you want to set a breakpoint you may need to distinguish whether you mean the version of name that takes an int parameter, name(int), or the version that takes a float parameter, name(float). To use the word-completion facilities in this situation, type a single quote ' at the beginning of the function name. This alerts GDB that it may need to consider more information than usual when you press <TAB> to request word completion:

(gdb) b 'bubble( <TAB>
bubble(double,double)    bubble(int,int)
(gdb) b 'bubble(

In some cases, DDD can tell that completing a name requires using quotes. When this happens, DDD inserts the quote for you (while completing as much as it can) if you do not type the quote in the first place:

(gdb) b bub <TAB>

DDD alters your input line to the following, and rings a bell:

(gdb) b 'bubble(

In general, DDD can tell that a quote is needed (and inserts it) if you have not yet started typing the argument list when you ask for completion on an overloaded symbol.

If you prefer to use the <TAB> key for switching between items, unset Edit => Preferences => General => TAB Key completes in All Windows. This is useful if you have pointer-driven keyboard focus (see below) and no special usage for the <TAB> key. If the option is set, the <TAB> key completes in the debugger console only.

This option is tied to the following resource:

globalTabCompletion (class GlobalTabCompletion) Resource
If this is on (default), the <TAB> key completes arguments in all windows. If this is off, the <TAB> key completes arguments in the debugger console only.

Node:Command History, Previous:Command Completion, Up:Entering Commands

Command History

You can repeat previous and next commands by pressing the <Up> and <Down> arrow keys, respectively. This presents you previous and later commands on the command line; use <Return> to apply the current command.

If you enter an empty line (just use <Return> at the debugger prompt), the last command is repeated as well.

Commands => Command History shows the command history.

You can search for previous commands by pressing <Ctrl+B>. This invokes incremental search mode, where you can enter a string to be searched in previous commands. Press <Ctrl+B> again to repeat the search, or <Ctrl+F> to search in the reverse direction. To return to normal mode, press <ESC>, or use any cursor command.

The command history is automatically saved when exiting DDD. You can turn off this feature by setting the following resource to off:

saveHistoryOnExit (class SaveHistoryOnExit) Resource
If on (default), the command history is automatically saved when DDD exits.

Node:TTY mode, Next:Integrating DDD, Previous:Entering Commands, Up:Commands

Entering Commands at the TTY

Rather than entering commands at the debugger console, you may prefer to enter commands at the terminal window DDD was invoked from.

When DDD is invoked using the --tty option, it enables its TTY interface, taking additional debugger commands from standard input and forwarding debugger output to standard output, just as if the inferior debugger had been invoked directly. All remaining DDD functionality stays unchanged.

By default, the debugger console remains closed if DDD is invoked using the --tty option. Use View => Debugger Console to open it.

DDD can be configured to use the readline library for reading in commands from standard input. This GNU library provides consistent behavior for programs which provide a command line interface to the user. Advantages are GNU Emacs-style or vi-style inline editing of commands, csh-like history substitution, and a storage and recall of command history across debugging sessions. See Command Line Editing, for details on command-line editing via the TTY interface.

Node:Integrating DDD, Next:Defining Buttons, Previous:TTY mode, Up:Commands

Integrating DDD

You can run DDD as an inferior debugger in other debugger front-ends, combining their special abilities with those of DDD.

To have DDD run as an inferior debugger in other front-ends, the general idea is to set up your debugger front-end such that ddd --tty is invoked instead of the inferior debugger. When DDD is invoked using the --tty option, it enables its TTY interface, taking additional debugger commands from standard input and forwarding debugger output to standard output, just as if the inferior debugger had been invoked directly. All remaining DDD functionality stays unchanged.

In case your debugger front-end uses the GDB -fullname option to have GDB report source code positions, the --tty option is not required. DDD recognizes the -fullname option, finds that it has been invoked from a debugger front-end and automatically enables the TTY interface.

If DDD is invoked with the -fullname option, the debugger console and the source window are initially disabled, as their facilities are supposed to be provided by the integrating front-end. In case of need, you can use the View menu to re-enable these windows.

Using DDD with Emacs

To integrate DDD with Emacs, use M-x gdb or M-x dbx in Emacs to start a debugging session. At the prompt, enter ddd --tty (followed by --dbx or --gdb, if required), and the name of the program to be debugged. Proceed as usual.

Using DDD with XEmacs

To integrate DDD with XEmacs, set the variable gdb-command-name to "ddd", by inserting the following line in your ~/.emacs file:

(setq gdb-command-name "ddd")

You can also evaluate this expression by pressing <ESC> <:> and entering it directly (<ESC> <ESC> for XEmacs 19.13 and earlier).

To start a DDD debugging session in XEmacs, use M-x gdb or M-x gdbsrc. Proceed as usual.

Using DDD with XXGDB

To integrate DDD with XXGDB, invoke xxgdb as

xxgdb -db_name ddd -db_prompt '(gdb) '

Node:Defining Buttons, Next:Defining Commands, Previous:Integrating DDD, Up:Commands

Defining Buttons

To facilitate interaction, you can add own command buttons to DDD. These buttons can be added below the debugger console (Console Buttons), the source window (Source Buttons), or the data window (Data Buttons).

To define individual buttons, use the Button Editor, invoked via Commands => Edit Buttons. The button editor displays a text, where each line contains the command for exactly one button. Clicking on OK creates the appropriate buttons from the text. If the text is empty (the default), no button is created.

As a simple example, assume you want to create a print i button. Invoke Commands => Edit Buttons and enter a line saying print i in the button editor. Then click on OK. A button named Print i will now appear below the debugger console--try it! To remove the button, reopen the button editor, clear the print i line and press OK again.

If a button command contains (), the string () will automatically be replaced by the contents of the argument field. For instance, a button named return () will execute the GDB return command with the current content of the argument field as argument.

By default, DDD disables buttons whose commands are not supported by the inferior debugger. To enable such buttons, unset the Enable supported buttons only toggle in the button editor.

DDD also allows you to specify control sequences and special labels for user-defined buttons. See Customizing Buttons, for details.

  • Customizing Buttons: Adding your own command buttons.

Node:Customizing Buttons, Up:Defining Buttons

Customizing Buttons

DDD allows defining additional command buttons; See Defining Buttons, for doing this interactively. This section describes the resources that control user-defined buttons.

consoleButtons (class Buttons) Resource
A newline-separated list of buttons to be added under the debugger console. Each button issues the command given by its name.

The following characters have special meanings:

  • Commands ending with ... insert their name, followed by a space, in the debugger console.
  • Commands ending with a control character (that is, ^ followed by a letter or ?) insert the given control character.
  • The string () is replaced by the current contents of the argument field ().
  • The string specified in the labelDelimiter resource (usually //) separates the command name from the button label. If no button label is specified, the capitalized command will be used as button label.

The following button names are reserved:

Apply
Send the given command to the debugger.
Back
Lookup previously selected source position.
Clear
Clear current command
Complete
Complete current command.
Edit
Edit current source file.
Forward
Lookup next selected source position.
Make
Invoke the make program, using the most recently given arguments.
Next
Show next command
No
Answer current debugger prompt with no. This button is visible only if the debugger asks a yes/no question.
Prev
Show previous command
Reload
Reload source file.
Yes
Answer current debugger prompt with yes. This button is visible only if the debugger asks a yes/no question.

The default resource value is empty--no console buttons are created.

Here are some examples to insert into your ~/.ddd/init file. These are the settings of DDD 1.x:

Ddd*consoleButtons: Yes\nNo\nbreak^C

This setting creates some more buttons:

  Ddd*consoleButtons: \
  Yes\nNo\nrun\nClear\nPrev\nNext\nApply\nbreak^C

See also the dataButtons, sourceButtons and toolButtons resources.

dataButtons (class Buttons) Resource
A newline-separated list of buttons to be added under the data display. Each button issues the command given by its name. See the consoleButtons resource, above, for details on button syntax.

The default resource value is empty--no source buttons are created.

sourceButtons (class Buttons) Resource
A newline-separated list of buttons to be added under the debugger console. Each button issues the command given by its name. See the consoleButtons resource, above, for details on button syntax.

The default resource value is empty--no source buttons are created.

Here are some example to insert into your ~/.ddd/init file. These are the settings of DDD 1.x:

Ddd*sourceButtons: \
  run\nstep\nnext\nstepi\nnexti\ncont\n\
  finish\nkill\nup\ndown\n\
  Back\nForward\nEdit\ninterrupt^C

This setting creates some buttons which are not found on the command tool:

  Ddd*sourceButtons: \
  print *()\ngraph display *()\nprint /x ()\n\
  whatis ()\nptype ()\nwatch ()\nuntil\nshell

An even more professional setting uses customized button labels.

  Ddd*sourceButtons: \
  print *(()) // Print *()\n\
  graph display *(()) // Display *()\n\
  print /x ()\n\
  whatis () // What is ()\n\
  ptype ()\n\
  watch ()\n\
  until\n\
  shell

See also the consoleButtons and dataButtons resources, above, and the toolButtons resource, below.

toolButtons (class Buttons) Resource
A newline-separated list of buttons to be included in the command tool or the command tool bar (see Disabling the Command Tool). Each button issues the command given by its name. See Defining Buttons, for details on button syntax.

The default resource value is

Ddd*toolButtons: \
run\nbreak^C\nstep\nstepi\nnext\nnexti\n\
until\nfinish\ncont\n\kill\n\
up\ndown\nBack\nForward\nEdit\nMake

For each button, its location in the command tool must be specified using XmForm constraint resources. See the Ddd application defaults file for instructions.

If the toolButtons resource value is empty, the command tool is not created.

The following resources set up button details:

labelDelimiter (class LabelDelimiter) Resource
The string used to separate labels from commands and shortcuts. Default is //.

verifyButtons (class VerifyButtons) Resource
If on (default), verify for each button whether its command is actually supported by the inferior debugger. If the command is unknown, the button is disabled. If this resource is off, no checking is done: all commands are accepted "as is".

Node:Defining Commands, Previous:Defining Buttons, Up:Commands

Defining Commands

Aside from breakpoint commands (see Breakpoint Commands), DDD also allows you to define user-defined commands. A user-defined command is a sequence of commands to which you assign a new name as a command. This new command can be entered at the debugger prompt or invoked via a button.

  • GDB Simple Commands:
  • GDB Argument Commands:
  • Commands with Other Debuggers:

Node:GDB Simple Commands, Next:GDB Argument Commands, Up:Defining Commands

Defining Simple Commands using GDB

Aside from breakpoint commands (see Breakpoint commands, above), DDD also allows you to store sequences of commands as a user-defined GDB command. A user-defined command is a sequence of GDB commands to which you assign a new name as a command. Using DDD, this is done via the Command Editor, invoked via Commands => Define Command.

A GDB command is created in five steps:

  1. Enter the name of the command in the Command field. Use the drop-down list on the right to select from already defined commands.
  2. Click on Record to begin the recording of the command sequence.
  3. Now interact with DDD. While recording, DDD does not execute commands, but simply records them to be executed when the breakpoint is hit. The recorded debugger commands are shown in the debugger console.
  4. To stop the recording, click on End or enter end at the GDB prompt. To cancel the recording, click on Interrupt or press <ESC>.
  5. Click on Edit >> to edit the recorded commands. When done with editing, click on Edit << to close the commands editor.

After the command is defined, you can enter it at the GDB prompt. You may also click on Apply to apply the given user-defined command.

For convenience, you can assign a button to the defined command. Enabling one of the Button locations will add a button with the given command to the specified location. If you want to edit the button, select Commands => Edit Buttons. See Defining Buttons, for a discussion.

When user-defined GDB commands are executed, the commands of the definition are not printed. An error in any command stops execution of the user-defined command.33

If used interactively, commands that would ask for confirmation proceed without asking when used inside a user-defined command. Many GDB commands that normally print messages to say what they are doing omit the messages when used in a user-defined command.

To save all command definitions, use Edit => Save Options.

Node:GDB Argument Commands, Next:Commands with Other Debuggers, Previous:GDB Simple Commands, Up:Defining Commands

Defining Argument Commands using GDB

If you want to pass arguments to user-defined commands, you can enable the () toggle button in the Command Editor. Enabling () has two effects:

  • While recording commands, all references to the argument field are taken symbolically instead of literally. The argument field value is frozen to $arg0, which is how GDB denotes the argument of a user-defined command. When GDB executes the command, it will replace $arg0 by the current command argument.
  • When assigning a button to the command, the command will be suffixed by the current contents of the argument field.

While defining a command, you can toggle the () button as you wish to switch between using the argument field symbolically and literally.

As an example, let us define a command contuntil that will set a breakpoint in the given argument and continue execution.

  1. Enter contuntil in the Command field.
  2. Enable the () toggle button.
  3. Now click on Record to start recording. Note that the contents of the argument field change to $arg0.
  4. Click on Break at () to create a breakpoint. Note that the recorded breakpoint command refers to $arg0.
  5. Click on Cont to continue execution.
  6. Click on End to end recording. Note that the argument field is restored to its original value.
  7. Finally, click on one of the Button locations. This creates a Contuntil () button where () will be replaced by the current contents of the argument field--and thus passed to the contuntil command.
  8. You can now either use the Contuntil () button or enter a contuntil command at the GDB prompt. (If you plan to use the command frequently, you may wish to define a cu command, which again calls contuntil with its argument. This is a nice exercise.)

There is a little drawback with argument commands: a user-defined command in GDB has no means to access the argument list as a whole; only the first argument (up to whitespace) is processed. This may change in future GDB releases.

Node:Commands with Other Debuggers, Previous:GDB Argument Commands, Up:Defining Commands

Defining Commands using Other Debuggers

If your inferior debugger allows you to define own command sequences, you can also use these user-defined commands within DDD; just enter them at the debugger prompt.

However, you may encounter some problems:

  • In contrast to the well-documented commands of the inferior debugger, DDD does not know what a user-defined command does. This may lead to inconsistencies between DDD and the inferior debugger. For instance, if your the user-defined command bp sets a breakpoint, DDD may not display it immediately, because DDD does not know that bp changes the breakpoint state.
  • You cannot use DDD graph commands within user-defined commands. This is only natural, because user-defined commands are interpreted by the inferior debugger, which does not know about DDD commands.

As a solution, DDD provides a simple facility called auto-commands. If DDD receives any output from the inferior debugger in the form prefix command, it will interpret command as if it had been entered at the debugger prompt. prefix is a user-defined string, for example ddd: .

Suppose you want to define a command gd that serves as abbreviation for graph display. All the command gd has to do is to issue a string

ddd: graph display argument

where argument is the argument given to gd. Using GDB, this can be achieved using the echo command. In your ~/.gdbinit file, insert the lines

define gd
  echo ddd: graph display $arg0\n
end

To complete the setting, you must also set the autoCommandPrefix resource to the ddd: prefix you gave in your command. In ~/.ddd/init, write:

Ddd*autoCommandPrefix: ddd:\

(Be sure to leave a space after the trailing backslash.)

Entering gd foo will now have the same effect as entering graph display foo at the debugger prompt.

Please note: In your commands, you should choose some other prefix than ddd: . This is because auto-commands raise a security problem, since arbitrary commands can be executed. Just imagine some malicious program issuing a string like prefix shell rm -fr ~ when being debugged! As a consequence, be sure to choose your own prefix; it must be at least three characters long.

Node:Application Defaults, Next:Bugs, Previous:Commands, Up:Top

Application Defaults

Like any good X citizen, DDD comes with a large application-defaults file named Ddd. This appendix documents the actions and images referenced in Ddd, such that you can easily modify them.

  • Actions: All actions used in translation tables.
  • Images: All images used in resources,

Node:Actions, Next:Images, Up:Application Defaults

Actions

The following DDD actions may be used in translation tables.

  • General Actions:
  • Data Display Actions:
  • Debugger Console Actions:
  • Source Window Actions:

Node:General Actions, Next:Data Display Actions, Up:Actions

General Actions

ddd-get-focus () Action
Assign focus to the element that just received input.

ddd-next-tab-group () Action
Assign focus to the next tab group.

ddd-prev-tab-group () Action
Assign focus to the previous tab group.

ddd-previous-tab-group () Action
Assign focus to the previous tab group.

Node:Data Display Actions, Next:Debugger Console Actions, Previous:General Actions, Up:Actions

Data Display Actions

These actions are used in the DDD graph editor.

end () Action
End the action initiated by select. Bound to a button up event.

extend () Action
Extend the current selection. Bound to a button down event.

extend-or-move () Action
Extend the current selection. Bound to a button down event. If the pointer is dragged, move the selection.

follow () Action
Continue the action initiated by select. Bound to a pointer motion event.

graph-select () Action
Equivalent to select, but also updates the current argument.

graph-select-or-move () Action
Equivalent to select-or-move, but also updates the current argument.

graph-extend () Action
Equivalent to extend, but also updates the current argument.

graph-extend-or-move () Action
Equivalent to extend-or-move, but also updates the current argument.

graph-toggle () Action
Equivalent to toggle, but also updates the current argument.

graph-toggle-or-move () Action
Equivalent to toggle-or-move, but also updates the current argument.

graph-popup-menu ([graph|node|shortcut]) Action
Pops up a menu. graph pops up a menu with global graph operations, node pops up a menu with node operations, and shortcut pops up a menu with display shortcuts.

If no argument is given, pops up a menu depending on the context: when pointing on a node with the <Shift> key pressed, behaves like shortcut; when pointing on a without the <Shift> key pressed, behaves like node; otherwise, behaves as if graph was given.

graph-dereference () Action
Dereference the selected display.

graph-detail () Action
Show or hide detail of the selected display.

graph-rotate () Action
Rotate the selected display.

graph-dependent () Action
Pop up a dialog to create a dependent display.

hide-edges ([any|both|from|to]) Action
Hide some edges. any means to process all edges where either source or target node are selected. both means to process all edges where both nodes are selected. from means to process all edges where at least the source node is selected. to means to process all edges where at least the target node is selected. Default is any.

layout ([regular|compact], [[+|-] degrees]) Action
Layout the graph. regular means to use the regular layout algorithm; compact uses an alternate layout algorithm, where successors are placed next to their parents. Default is regular. degrees indicates in which direction the graph should be layouted. Default is the current graph direction.

move-selected (x-offset, y-offset) Action
Move all selected nodes in the direction given by x-offset and y-offset. x-offset and y-offset is either given as a numeric pixel value, or as +grid, or -grid, meaning the current grid size.

normalize () Action
Place all nodes on their positions and redraw the graph.

rotate ([[+|-]degrees]) Action
Rotate the graph around degrees degrees. degrees must be a multiple of 90. Default is +90.

select () Action
Select the node pointed at. Clear all other selections. Bound to a button down event.

select-all () Action
Select all nodes in the graph.

select-first () Action
Select the first node in the graph.

select-next () Action
Select the next node in the graph.

select-or-move () Action
Select the node pointed at. Clear all other selections. Bound to a button down event. If the pointer is dragged, move the selected node.

select-prev () Action
Select the previous node in the graph.

show-edges ([any|both|from|to]) Action
Show some edges. any means to process all edges where either source or target node are selected. both means to process all edges where both nodes are selected. from means to process all edges where at least the source node is selected. to means to process all edges where at least the target node is selected. Default is any.

snap-to-grid () Action
Place all nodes on the nearest grid position.

toggle () Action
Toggle the current selection--if the node pointed at is selected, it will be unselected, and vice versa. Bound to a button down event.

toggle-or-move () Action
Toggle the current selection--if the node pointed at is selected, it will be unselected, and vice versa. Bound to a button down event. If the pointer is dragged, move the selection.

unselect-all () Action
Clear the selection.

Node:Debugger Console Actions, Next:Source Window Actions, Previous:Data Display Actions, Up:Actions

Debugger Console Actions

These actions are used in the debugger console and other text fields.

gdb-backward-character () Action
Move one character to the left. Bound to Left.

gdb-beginning-of-line () Action
Move cursor to the beginning of the current line, after the prompt. Bound to HOME.

gdb-control (control-character) Action
Send the given control-character to the inferior debugger. control-character must be specified in the form ^X, where X is an upper-case letter, or ?.

gdb-command (command) Action
Execute command in the debugger console. The following replacements are performed on command:
  • If command has the form name..., insert name, followed by a space, in the debugger console.
  • All occurrences of () are replaced by the current contents of the argument field ().

gdb-complete-arg (command) Action
Complete current argument as if command was prepended. Bound to <Ctrl+T>.

gdb-complete-command () Action
Complete current command line in the debugger console. Bound to <TAB>.

gdb-complete-tab (command) Action
If global <TAB> completion is enabled, complete current argument as if command was prepended. Otherwise, proceed as if the <TAB> key was hit. Bound to <TAB>.

gdb-delete-or-control (control-character) Action
Like gdb-control, but effective only if the cursor is at the end of a line. Otherwise, control-character is ignored and the character following the cursor is deleted. Bound to <Ctrl+D>.

gdb-end-of-line () Action
Move cursor to the end of the current line. Bound to End.

gdb-forward-character () Action
Move one character to the right. Bound to Right.

gdb-insert-graph-arg () Action
Insert the contents of the data display argument field ().

gdb-insert-source-arg () Action
Insert the contents of the source argument field ().

gdb-interrupt () Action
If DDD is in incremental search mode, exit it; otherwise call gdb-control(^C).

gdb-isearch-prev () Action
Enter reverse incremental search mode. Bound to <Ctrl+B>.

gdb-isearch-next () Action
Enter incremental search mode. Bound to <Ctrl+F>.

gdb-isearch-exit () Action
Exit incremental search mode. Bound to <ESC>.

gdb-next-history () Action
Recall next command from history. Bound to Down.

gdb-prev-history () Action
Recall previous command from history. Bound to Up.

gdb-previous-history () Action
Recall previous command from history. Bound to Up.

gdb-process ([action [, args...]]) Action
Process the given event in the debugger console. Bound to key events in the source and data window. If this action is bound to the source window, and the source window is editable, perform action(args...) on the source window instead; if action is not given, perform self-insert().

gdb-select-all () Action
If the selectAllBindings resource is set to Motif, perform beginning-of-line. Otherwise, perform select-all. Bound to <Ctrl+A>.

gdb-set-line (value) Action
Set the current line to value. Bound to <Ctrl+U>.

Node:Source Window Actions, Previous:Debugger Console Actions, Up:Actions

Source Window Actions

These actions are used in the source and code windows.

source-delete-glyph () Action
Delete the breakpoint related to the glyph at cursor position.

source-double-click ([text-action [, line-action [, function-action]]]) Action
The double-click action in the source window.
  • If this action is taken on a breakpoint glyph, edit the breakpoint properties.
  • If this action is taken in the breakpoint area, invoke gdb-command(line-action). If line-action is not given, it defaults to break ().
  • If this action is taken in the source text, and the next character following the current selection is (, invoke gdb-command(function-action). If function-action is not given, it defaults to list ().
  • Otherwise, invoke gdb-command(text-action). If text-action is not given, it defaults to graph display ().

source-drag-glyph () Action
Initiate a drag on the glyph at cursor position.

source-drop-glyph ([action]) Action
Drop the dragged glyph at cursor position. action is either move, meaning to move the dragged glyph, or copy, meaning to copy the dragged glyph. If no action is given, move is assumed.

source-end-select-word () Action
End selecting a word.

source-follow-glyph () Action
Continue a drag on the glyph at cursor position. Usually bound to some motion event.

source-popup-menu () Action
Pop up a menu, depending on the location.

source-set-arg () Action
Set the argument field to the current selection. Typically bound to some selection operation.

source-start-select-word () Action
Start selecting a word.

source-update-glyphs () Action
Update all visible glyphs. Usually invoked after a scrolling operation.

Node:Images, Previous:Actions, Up:Application Defaults

Images

DDD installs a number of images that may be used as pixmap resources, simply by giving a symbolic name. For button images, three variants are installed as well:

  • The suffix -hi indicates a highlighted variant (Button is entered).
  • The suffix -arm indicates an armed variant (Button is pushed).
  • The suffix -xx indicates a disabled (insensitive) variant.

break_at Image
Break at () button.

clear_at Image
Clear at () button.

ddd Image
DDD icon.

delete Image
Delete () button.

disable Image
Disable button.

dispref Image
Display * () button.

display Image
Display () button.

drag_arrow Image
The execution pointer (being dragged).

drag_cond Image
A conditional breakpoint (being dragged).

drag_stop Image
A breakpoint (being dragged).

drag_temp Image
A temporary breakpoint (being dragged).

enable Image
Enable button.

find_forward Image
Find>> () button.

find_backward Image
Find<< () button.

grey_arrow Image
The execution pointer (not in lowest frame).

grey_cond Image
A conditional breakpoint (disabled).

grey_stop Image
A breakpoint (disabled).

grey_temp Image
A temporary breakpoint (disabled).

hide Image
Hide () button.

lookup Image
Lookup () button.

maketemp Image
Make Temporary button.

new_break Image
New Breakpoint button.

new_display Image
New Display button.

new_watch Image
New Watchpoint button.

plain_arrow Image
The execution pointer.

plain_cond Image
A conditional breakpoint (enabled).

plain_stop Image
A breakpoint (enabled).

plain_temp Image
A temporary breakpoint (enabled).

print Image
Print () button.

properties Image
Properties button.

rotate Image
Rotate () button.

set Image
Set () button.

show Image
Show () button.

signal_arrow Image
The execution pointer (stopped by signal).

undisplay Image
Undisplay () button.

unwatch Image
Unwatch () button.

watch Image
Watch () button.

Node:Bugs, Next:Configuration Notes, Previous:Application Defaults, Up:Top

Bugs and How To Report Them

Sometimes you will encounter a bug in DDD. Although we cannot promise we can or will fix the bug, and we might not even agree that it is a bug, we want to hear about bugs you encounter in case we do want to fix them.

To make it possible for us to fix a bug, you must report it. In order to do so effectively, you must know when and how to do it.

  • Where to Send Bug Reports: Our e-mail address.
  • Is it a DDD Bug?: DDD may not be at fault.
  • How to Report Bugs: Report all the facts.
  • Bug Reports: Include all configuration information.
  • Diagnostics: Maintaining DDD

Node:Where to Send Bug Reports, Next:Is it a DDD Bug?, Up:Bugs

Where to Send Bug Reports

Send bug reports for DDD via electronic mail to

bug-ddd@gnu.org

Node:Is it a DDD Bug?, Next:How to Report Bugs, Previous:Where to Send Bug Reports, Up:Bugs

Is it a DDD Bug?

Before sending in a bug report, try to find out whether the problem cause really lies within DDD. A common cause of problems are incomplete or missing X or Motif installations, for instance, or bugs in the X server or Motif itself. Running DDD as

$ ddd --check-configuration

checks for common problems and gives hints on how to repair them.

Another potential cause of problems is the inferior debugger; occasionally, they show bugs, too. To find out whether a bug was caused by the inferior debugger, run DDD as

$ ddd --trace

This shows the interaction between DDD and the inferior debugger on standard error while DDD is running. (If --trace is not given, this interaction is logged in the file ~/.ddd/log; see Logging) Compare the debugger output to the output of DDD and determine which one is wrong.

Node:How to Report Bugs, Next:Bug Reports, Previous:Is it a DDD Bug?, Up:Bugs

How to Report Bugs

Here are some guidelines for bug reports:

  • The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!
  • Keep in mind that the purpose of a bug report is to enable someone to fix the bug if it is not known. It is not very important what happens if the bug is already known. Therefore, always write your bug reports on the assumption that the bug is not known.
  • Your bug report should be self-contained. Do not refer to information sent in previous mails; your previous mail may have been forwarded to somebody else.
  • Please report each bug in a separate message. This makes it easier for us to track which bugs have been fixed and to forward your bugs reports to the appropriate maintainer.
  • Please report bugs in English; this increases the chances of finding someone who can fix the bug. Do not assume one particular person will receive your bug report.

Node:Bug Reports, Next:Diagnostics, Previous:How to Report Bugs, Up:Bugs

What to Include in a Bug Report

To enable us to fix a DDD bug, you must include the following information:

  • Your DDD configuration. Invoke DDD as
    $ ddd --configuration

    to get the configuration information. If this does not work, please include at least the DDD version, the type of machine you are using, and its operating system name and version number.

  • The debugger you are using and its version (e.g., gdb-4.17 or dbx as shipped with Solaris 2.6).
  • The compiler you used to compile DDD and its version (e.g., gcc-2.8.1).
  • A description of what behavior you observe that you believe is incorrect. For example, "DDD gets a fatal signal" or "DDD exits immediately after attempting to create the data window".
  • A log file showing the interaction between DDD and the inferior debugger. By default, this interaction is logged in the file ~/.ddd/log. Include all trace output from the DDD invocation up to the first bug occurrence; insert own comments where necessary.
  • If you wish to suggest changes to the DDD source, send us context diffs. If you even discuss something in the DDD source, refer to it by context, never by line number.

Be sure to include this information in every single bug report.

Node:Diagnostics, Previous:Bug Reports, Up:Bugs

Getting Diagnostics

  • Logging: DDD logs all interactions.
  • Debugging DDD: Facilities to debug DDD.
  • Customizing Diagnostics: All diagnostics resources.

Node:Logging, Next:Debugging DDD, Up:Diagnostics

Logging

If things go wrong, the first and most important information source is the DDD log file. This file, created in ~/.ddd/log (~ stands for your home directory), records the following information:

  • Your DDD configuration (at the top)
  • All programs invoked by DDD, shown as $ program args...
  • All DDD messages, shown as # message.
  • All information sent from DDD to the inferior debugger, shown as -> text.
  • All information sent from the inferior debugger standard output to DDD, shown as <- text.
  • All information sent from the inferior debugger standard error to DDD, shown as <= text.34
  • All information sent from DDD to Gnuplot, shown as >> text.
  • All information sent from Gnuplot standard output to DDD, shown as << text.
  • All information sent from Gnuplot standard error to DDD, shown as <= text.
  • If DDD crashes, a GDB backtrace of the DDD core dump is included at the end.

This information, all in one place, should give you (and anyone maintaining DDD) a first insight of what's going wrong.

  • Disabling Logging:

Node:Disabling Logging, Up:Logging

Disabling Logging

The log files created by DDD can become quite large, so you might want to turn off logging. There is no explicit DDD feature that allows you to do that. However, you can easily create a symbolic link from ~/.ddd/log to /dev/null, such that logging information is lost. Enter the following commands at the shell prompt:

$ cd
$ rm .ddd/log
$ ln -s /dev/null .ddd/log

Be aware, though, that having logging turned off makes diagnostics much more difficult; in case of trouble, it may be hard to reproduce the error.

Node:Debugging DDD, Next:Customizing Diagnostics, Previous:Logging, Up:Diagnostics

Debugging DDD

As long as DDD is compiled with -g (see Compiling for Debugging), you can invoke a debugger on DDD--even DDD itself, if you wish. From within DDD, a special Maintenance menu is provided that invokes GDB on the running DDD process. See Maintenance Menu, for details.

The DDD distribution comes with a .gdbinit file that is suitable for debugging DDD. Among others, this defines a ddd command that sets up an environment for debugging DDD and a string command that lets you print the contents of DDD string variables; just use print var followed by string.

You can cause DDD to dump core at any time by sending it a SIGUSR1 signal. DDD resumes execution while you can examine the core file with GDB.

When debugging DDD, it can be useful to make DDD not catch fatal errors. This can be achieved by setting the environment variable DDD_NO_SIGNAL_HANDLERS before invoking DDD.

Node:Customizing Diagnostics, Previous:Debugging DDD, Up:Diagnostics

Customizing Diagnostics

You can use these additional resources to obtain diagnostics about DDD. Most of them are tied to a particular invocation option.

appDefaultsVersion (class Version) Resource
The version of the DDD app-defaults file. If this string does not match the version of the current DDD executable, DDD issues a warning.

checkConfiguration (class CheckConfiguration) Resource
If on, check the DDD environment (in particular, the X configuration), report any possible problem causes and exit. See Options, for the --check-configuration option.

dddinitVersion (class Version) Resource
The version of the DDD executable that last wrote the ~/.ddd/init file. If this string does not match the version of the current DDD executable, DDD issues a warning.

debugCoreDumps (class DebugCoreDumps) Resource
If on, DDD invokes a debugger on itself when receiving a fatal signal. See Maintenance Menu, for setting this resource.

dumpCore (class DumpCore) Resource
If on (default), DDD dumps core when receiving a fatal signal. See Maintenance Menu, for setting this resource.

maintenance (class Maintenance) Resource
If on, enables the top-level Maintenance menu (see Maintenance Menu) with additional options. See Options, for the --maintenance option.

showConfiguration (class ShowConfiguration) Resource
If on, show the DDD configuration on standard output and exit. See Options, for the --configuration option.

showFonts (class ShowFonts) Resource
If on, show the DDD font definitions on standard output and exit. See Options, for the --fonts option.

showInvocation (class ShowInvocation) Resource
If on, show the DDD invocation options on standard output and exit. See Options, for the --help option.

showLicense (class ShowLicense) Resource
If on, show the DDD license on standard output and exit. See Options, for the --license option.

showManual (class ShowManual) Resource
If on, show this DDD manual page on standard output and exit. If the standard output is a terminal, the manual page is shown in a pager ($PAGER, less or more). See Options, for the --manual option.

showNews (class ShowNews) Resource
If on, show the DDD news on standard output and exit. See Options, for the --news option.

showVersion (class ShowVersion) Resource
If on, show the DDD version on standard output and exit. See Options, for the --version option.

suppressWarnings (class SuppressWarnings) Resource
If on, X warnings are suppressed. This is sometimes useful for executables that were built on a machine with a different X or Motif configuration. By default, this is off. See X Warnings, for details.

trace (class Trace) Resource
If on, show the dialog between DDD and the inferior debugger on standard output. Default is off. See Options, for the --trace option.

Node:Configuration Notes, Next:Dirty Tricks, Previous:Bugs, Up:Top

Configuration Notes

  • GDB: Using DDD with GDB
  • DBX: Using DDD with DBX
  • Ladebug: Using DDD with Ladebug
  • XDB: Using DDD with XDB
  • JDB: Using DDD with JDB
  • Perl: Using DDD with Perl
  • LessTif: Using DDD with LessTif

Node:GDB, Next:DBX, Up:Configuration Notes

Using DDD with GDB

Some GDB settings are essential for DDD to work correctly. These settings with their correct values are:

set height 0
set width 0
set verbose off
set prompt (gdb)

DDD sets these values automatically when invoking GDB; if these values are changed, there may be some malfunctions, especially in the data display.

When debugging at the machine level with GDB 4.12 and earlier as inferior debugger, use a display /x $pc command to ensure the program counter value is updated correctly at each stop. You may also enter the command in ~/.gdbinit or (better yet) upgrade to the most recent GDB version.

Node:DBX, Next:Ladebug, Previous:GDB, Up:Configuration Notes

Using DDD with DBX

When used for debugging Pascal-like programs, DDD does not infer correct array subscripts and always starts to count with 1.

With some DBX versions (notably Solaris DBX), DDD strips C-style and C++-style comments from the DBX output in order to interpret it properly. This also affects the output of the debugged program when sent to the debugger console. Using the separate execution window avoids these problems.

In some DBX versions (notably DEC DBX and AIX DBX), there is no automatic data display. As an alternative, DDD uses the DBX print command to access data values. This means that variable names are interpreted according to the current frame; variables outside the current frame cannot be displayed.

Node:Ladebug, Next:XDB, Previous:DBX, Up:Configuration Notes

Using DDD with Ladebug

All DBX limitations (see DBX) apply to Ladebug as well.

Node:XDB, Next:JDB, Previous:Ladebug, Up:Configuration Notes

Using DDD with XDB

There is no automatic data display in XDB. As a workaround, DDD uses the p command to access data values. This means that variable names are interpreted according to the current frame; variables outside the current frame cannot be displayed.

Node:JDB, Next:Perl, Previous:XDB, Up:Configuration Notes

Using DDD with JDB

There is no automatic data display in JDB. As a workaround, DDD uses the dump command to access data values. This means that variable names are interpreted according to the current frame; variables outside the current frame cannot be displayed.

The JDB dump and print commands do not support expression evaluation. Hence, you cannot display arbitrary expressions.

Parsing of JDB output is quite CPU-intensive, due to the recognition of asynchronous prompts (any thread may output anything at any time, including prompts). Hence, a program producing much console output is likely to slow down DDD considerably. In such a case, have the program run with -debug in a separate window and attach JDB to it using the -passwd option.

Node:Perl, Next:LessTif, Previous:JDB, Up:Configuration Notes

Using DDD with Perl

There is no automatic data display in Perl. As a workaround, DDD uses the x command to access data values. This means that variable names are interpreted according to the current frame; variables outside the current frame cannot be displayed.

Node:LessTif, Previous:Perl, Up:Configuration Notes

Using DDD with LessTif

DDD includes a number of hacks that make DDD run with LessTif, a free Motif clone, without loss of functionality. Since a DDD binary may be dynamically bound and used with either an OSF/Motif or LessTif library, these lesstif hacks can be enabled and disabled at run time.

Whether the lesstif hacks are included at run-time depends on the setting of the lessTifVersion resource:

lessTifVersion (class LessTifVersion) Resource
Indicates the LessTif version DDD is running against. For LessTif version x.y, the value is x multiplied by 1000 plus y--for instance, the value 79 stands for LessTif 0.79 and the value 1005 stands for LessTif 1.5.

If the value of this resource is less than 1000, indicating LessTif 0.99 or earlier, DDD enables version-specific hacks to make DDD work around LessTif bugs and deficiencies.

If DDD was compiled against LessTif, the default value is the value of the LessTifVersion macro in <Xm/Xm.h>. If DDD was compiled against OSF/Motif, the default value is 1000, disabling all LessTif-specific hacks.

To set the lessTifVersion resource at DDD invocation and to specify the version number of the LessTif library, you can also use the option --lesstif-version version.

The default value of the lessTifVersion resource is derived from the LessTif library DDD was compiled against (or 1000 when compiled against OSF/Motif). Hence, you normally don't need to worry about the value of this resource. However, if you use a dynamically linked DDD binary with a library other than the one DDD was compiled against, you must specify the version number of the library using this resource. (Unfortunately, DDD cannot detect this at run-time.)

Here are a few scenarios to illustrate this scheme:

  • Your DDD binary was compiled against OSF/Motif, but you use a LessTif 0.88 dynamic library instead. Invoke DDD with --lesstif-version 88.
  • Your DDD binary was compiled against LessTif, but you use a OSF/Motif dynamic library instead. Invoke DDD with --lesstif-version 1000.
  • Your DDD binary was compiled against LessTif 0.85, and you have upgraded to LessTif 0.90. Invoke DDD with --lesstif-version 90.

To find out the LessTif or OSF/Motif version DDD was compiled against, invoke DDD with the --configuration option.

In the DDD source, LessTif-specific hacks are controlled by the string lesstif_version.

Node:Dirty Tricks, Next:Extending, Previous:Configuration Notes, Up:Top

Dirty Tricks

Do you miss anything in this manual? Do you have any material that should be added? Please send any contributions to ddd@gnu.org.

Node:Extending, Next:FAQ, Previous:Dirty Tricks, Up:Top

Extending DDD

If you have any contributions to be incorporated into DDD, please send them to ddd@gnu.org. For suggestions on what might be done, see the file TODO in the DDD distribution.

Node:FAQ, Next:License, Previous:Extending, Up:Top

Frequently Answered Questions

See the DDD WWW page for frequently answered questions not covered in this manual.

Node:License, Next:Help and Assistance, Previous:FAQ, Up:Top

GNU General Public License

Version 2, June 1991

Copyright © 1989, 1991 Free Software Foundation, Inc.  675
Mass Ave, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and an idea of what it does.
Copyright (C) 19yy  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

Node:Help and Assistance, Next:Label Index, Previous:License, Up:Top

Help and Assistance

We have set up a mailing list for general DDD discussions. If you need help and assistance for solving a DDD problem, you find the right people here.

Send message to all receivers of the mailing list to:

ddd@gnu.org

This mailing list is also the place where new DDD releases are announced. If you want to subscribe the list, or get more information, send a mail to

ddd-request@gnu.org

See also the DDD WWW page for recent announcements and other news related to DDD.

Node:Label Index, Next:Key Index, Previous:Help and Assistance, Up:Top

Label Index

  • (): GDB Argument Commands
  • ():: Tool Bar
  • 3-D Lines: Plot Appearance
  • Abort: Program Menu, Quitting
  • About DDD: Help Menu
  • Align on Grid: Data Menu
  • All Signals: Signals
  • Apply: GDB Simple Commands, Commands Menu
  • Attach: Attaching to a Process
  • Attach to Process: Attaching to a Process, File Menu
  • Auto-align Displays on Nearest Grid Point: Aligning Displays
  • Automatic Display of Button Hints: Button tips
  • Automatic Display of Variable Values: Value Tips
  • Backtrace: Status Menu
  • Break: Setting Breakpoints, Tool Bar
  • Breakpoints: Source Menu
  • Button: GDB Simple Commands
  • Cache Machine Code: Customizing Machine Code
  • Cache source files: Customizing Source Lookup
  • Change Directory: Working Directory, File Menu
  • Clear: Disabling Breakpoints, Deleting Breakpoints, Tool Bar, Edit Menu
  • Clear Line: Commands Menu
  • Clear Undo Buffer: Customizing Undo
  • Clear Window: Commands Menu
  • Close: File Menu
  • Close data window when deleting last display: Deleting Displays
  • Cluster: Clustering
  • Cluster Data Displays: Clustering
  • Color: Printing the Graph
  • Command: GDB Simple Commands, Entering Plotting Commands
  • Command History: Commands Menu
  • Command Tool: View Menu
  • Commands: Commands Menu, Menu Bar
  • Complete: Commands Menu
  • Cont: Command Tool
  • Continue: Continuing Somewhere Else, Resuming Execution, Program Menu
  • Continue Automatically when Mouse Pointer is Frozen: Stopping X Programs
  • Continue Until Here: Temporary Breakpoints
  • Continue Without Signal: Signals, Program Menu
  • Contour: Plot Appearance
  • Copy: Deleting Displays, Edit Menu
  • Ctrl+A is: Customizing the Edit Menu
  • Ctrl+C is: Customizing the Edit Menu
  • Cut: Deleting Displays, Edit Menu
  • Data: Data Menu, Menu Bar
  • Data Scrolling: Scrolling Data
  • Data Window: View Menu
  • DBX Console: View Menu
  • DBX Reference: Getting Help, Help Menu
  • DBX Settings: Edit Menu
  • DDD License: Help Menu
  • DDD News: Help Menu
  • DDD Reference: Getting Help, Help Menu
  • DDD Splash Screen: Splash Screen
  • DDD WWW Page: Getting Help, Help Menu
  • Debug DDD: Maintenance Menu
  • Debugger Reference: Getting Help, Help Menu
  • Debugger Settings: Edit Menu
  • Debugger Type: Debugger Invocation
  • Define Command: Commands Menu
  • Delete: Editing Breakpoint Properties, Deleting Breakpoints, Edit Menu, Deleting Sessions
  • Delete Breakpoint: Deleting Breakpoints
  • Detach Process: Attaching to a Process, File Menu
  • Detect Aliases: Shared Structures, Data Menu
  • Determine Automatically from Arguments: Debugger Invocation
  • Disable: Editing Breakpoint Properties, Disabling Breakpoints
  • Disable Breakpoint: Disabling Breakpoints
  • Disp *: Dereferencing Pointers
  • Display: Creating Single Displays, Display Basics, Tool Bar
  • Display (): Data Menu
  • Display *: Dereferencing Pointers
  • Display *(): Dereferencing Pointers
  • Display Arguments: Displaying Local Variables, Data Menu
  • Display Line Numbers: Source Menu
  • Display Local Variables: Displaying Local Variables, Data Menu
  • Display Machine Code: Source Menu
  • Display Source Line Numbers: Customizing Source Appearance
  • Display Two-Dimensional Arrays as Tables: Arrays as Tables
  • Displays: Data Menu
  • Do Nothing: Maintenance Menu
  • Down: Selecting a frame, Command Tool, Status Menu
  • Dump Core: Maintenance Menu
  • Dump Core Now: Maintenance Menu
  • Edit: Editing Source Code, Command Tool, Edit Menu, Menu Bar
  • Edit <<: GDB Simple Commands
  • Edit >>: GDB Simple Commands, Breakpoint Commands
  • Edit Buttons: Defining Buttons, Commands Menu
  • Edit Menu: Display Shortcuts
  • Edit Source: Editing Source Code, Source Menu
  • Edit Sources: Editing Source Code
  • Enable: Editing Breakpoint Properties, Disabling Breakpoints
  • Enable Breakpoint: Disabling Breakpoints
  • Enable supported buttons only: Defining Buttons
  • End: GDB Simple Commands, Breakpoint Commands
  • Execution Window: Customizing the Execution Window, View Menu
  • Exit: File Menu, Quitting
  • File: File Menu, Menu Bar
  • File Name: Printing the Graph
  • Find <<: Textual Search
  • Find << (): Source Menu
  • Find >>: Textual Search, Tool Bar
  • Find >> (): Source Menu
  • Find Backward: Commands Menu
  • Find Case Sensitive: Source Menu
  • Find Forward: Commands Menu
  • Find Words Only: Textual Search, Source Menu
  • Finish: Resuming Execution, Command Tool, Program Menu
  • GDB Console: View Menu
  • GDB Reference: Getting Help, Help Menu
  • GDB Settings: Edit Menu
  • Get Core File: Customizing Sessions
  • Help: Getting Help, Help Menu, Menu Bar
  • Hide: Showing and Hiding Details, Tool Bar
  • Iconify all windows at once: Icons
  • Ignore Count: Breakpoint Ignore Counts
  • Include Core Dump: Saving Sessions
  • Interrupt: Interrupting, Command Tool, Program Menu
  • JDB Console: View Menu
  • JDB Reference: Getting Help, Help Menu
  • JDB Settings: Edit Menu
  • Kill: Killing the Program, Command Tool, Program Menu
  • Ladebug Console: View Menu
  • Ladebug Reference: Getting Help, Help Menu
  • Ladebug Settings: Edit Menu
  • Landscape: Printing Plots
  • Layout Graph: Automatic Layout, Data Menu
  • List Processes: Attaching to a Process
  • Lookup: Editing Breakpoint Properties, Looking up Definitions, Tool Bar
  • Lookup (): Source Menu
  • Machine Code Indentation: Customizing Machine Code
  • Machine Code Window: View Menu
  • Maintenance: Maintenance Menu, Menu Bar
  • Make: Recompiling, Command Tool, File Menu
  • Memory: Examining Memory, Data Menu
  • New Display: Display Shortcuts
  • New Game: Maintenance Menu
  • Next: Resuming Execution, Command Tool, Commands Menu, Program Menu
  • Next Instruction: Machine Code Execution, Program Menu
  • Nexti: Machine Code Execution, Command Tool
  • On item: Help Menu
  • Open: Opening Source Files, Opening Core Dumps, Opening Programs
  • Open Class: Opening Programs, File Menu
  • Open Core Dump: File Menu
  • Open Program: Attaching to a Process, Opening Programs, File Menu
  • Open Recent: Opening Programs, File Menu
  • Open Session: File Menu, Resuming Sessions
  • Open Source: Opening Source Files, File Menu
  • Orientation: Printing the Graph
  • Other: Display Shortcuts
  • Overview: Help Menu
  • Paper Size: Printing Plots, Printing the Graph
  • Pass: Signals
  • Paste: Deleting Displays, Edit Menu
  • Perl Console: View Menu
  • Perl Reference: Getting Help, Help Menu
  • Perl Settings: Edit Menu
  • Plot: Gnuplot Invocation, Plot Appearance, Tool Bar
  • Plot Window: Gnuplot Invocation
  • Portrait: Printing Plots
  • Preferences: Edit Menu
  • Previous: Commands Menu
  • Print: Printing Values, Signals, Editing all Watchpoints, Editing Watchpoint Properties, Tool Bar
  • Print (): Data Menu
  • Print Command: Printing the Graph
  • Print Graph: Printing the Graph, File Menu
  • Print Plot: Printing Plots
  • Program: Program Menu, Menu Bar
  • PYDB Console: View Menu
  • PYDB Reference: Getting Help, Help Menu
  • PYDB Settings: Edit Menu
  • Quit Search: Commands Menu
  • Record: GDB Simple Commands, Breakpoint Commands
  • Redo: Undoing Program Execution, Looking up Previous Locations, Undo and Redo, Command Tool, Edit Menu
  • Refer to Program Sources: Customizing Source Lookup
  • Refresh: Data Menu
  • Refresh Displays: Repeated Values, Refreshing the Data Window
  • Registers: Registers, Status Menu
  • Reload Source: Editing Source Code, Source Menu
  • Remove Menu: Maintenance Menu
  • Reset: Signals
  • Restart: File Menu
  • Rotate: Tool Bar
  • Rotate Graph: Rotating the Graph, Data Menu
  • Run: Starting Program Execution, Command Tool, Program Menu
  • Run Again: Starting Program Execution, Program Menu
  • Run in Execution Window: Using the Execution Window, Program Menu
  • Save Data As: Exporting Plot Data
  • Save Options: Signals, Edit Menu
  • Save Session As: Signals, File Menu, Saving Sessions
  • Scale: Plot Appearance
  • Search path for source files: Source Path
  • Select All: Edit Menu
  • Selected Only: Printing Plots, Printing the Graph
  • Send: Signals
  • Set: Assignment, Tool Bar
  • Set Execution Position: Continuing Somewhere Else
  • Set Temporary Breakpoint: Temporary Breakpoints
  • Set Value: Assignment
  • Show: Showing and Hiding Details, Tool Bar
  • Show All: Showing and Hiding Details
  • Show Just: Showing and Hiding Details
  • Show More: Showing and Hiding Details
  • Show Position and Breakpoints: Customizing Glyphs
  • Signals: Signals, Status Menu
  • Source: Source Menu, Menu Bar
  • Source indentation: Customizing Source Appearance
  • Source Window: View Menu
  • Status: Status Menu, Menu Bar
  • Status Displays: Displaying Program Status, Data Menu
  • Step: Resuming Execution, Command Tool, Program Menu
  • Step Instruction: Machine Code Execution, Program Menu
  • Stepi: Machine Code Execution, Command Tool
  • Stop: Signals
  • Suppress X warnings: X Warnings
  • Tab Width: Customizing Source Appearance
  • Temp: Editing Breakpoint Properties
  • Threads: Threads, Status Menu
  • Threshold for repeated print elements: Repeated Values
  • Tic Tac Toe: Maintenance Menu
  • Tip of the Day: Help Menu
  • Tool Bar Appearance: Window Layout
  • Tool Buttons Location: Disabling the Command Tool
  • Uncluster: Clustering
  • Uncompress: Help Helpers
  • Undisp: Deleting Displays, Tool Bar
  • Undisplay: Display Basics
  • Undo: Deleting Displays, Showing and Hiding Details, Undoing Program Execution, Selecting a frame, Looking up Previous Locations, Undo and Redo, Command Tool, Edit Menu
  • Undo Buffer Size: Customizing Undo
  • Uniconify When Ready: Program Stop
  • Until: Resuming Execution, Command Tool, Program Menu
  • Unwatch: Tool Bar
  • Up: Selecting a frame, Command Tool, Status Menu
  • View: Plot Appearance, View Menu, Menu Bar
  • Warn if Multiple DDD Instances are Running: Multiple Instances
  • Watch: Editing Watchpoint Properties, Setting Watchpoints, Tool Bar
  • Watchpoints: Data Menu
  • Web Browser: Help Helpers
  • What Now?: Getting Help, Help Menu
  • When DDD Crashes: Maintenance Menu
  • Window Layout: Window Layout
  • Writing into executable and core files: Patching
  • XDB Console: View Menu
  • XDB Reference: Getting Help, Help Menu
  • XDB Settings: Edit Menu

Node:Key Index, Next:Command Index, Previous:Label Index, Up:Top

Key Index

  • Ctrl+\: Quitting
  • Ctrl+B: Command History
  • Ctrl+C: Interrupting, Customizing the Edit Menu, Quitting
  • Ctrl+D: Quitting
  • Ctrl+Down: Selecting a frame
  • Ctrl+F: Command History
  • Ctrl+F1: Getting Help
  • Ctrl+Q: Quitting, Invocation
  • Ctrl+Shift+A: Customizing the Edit Menu
  • Ctrl+Up: Selecting a frame
  • Down: Command History, Moving Displays, Selecting Displays
  • ESC: Command History, Interrupting, Customizing the Edit Menu, Quitting
  • F1: Getting Help
  • Home: Customizing the Edit Menu
  • Left: Moving Displays, Selecting Displays
  • Return: Command History
  • Right: Moving Displays, Selecting Displays
  • Shift: Selecting Displays
  • TAB: Tool Bar
  • Up: Command History, Moving Displays, Selecting Displays

Node:Command Index, Next:Resource Index, Previous:Key Index, Up:Top

Command Index

  • cont: Undoing Program Execution, Customizing Grab Checking
  • contuntil: GDB Argument Commands
  • directory: Source Path
  • down: Selecting a frame
  • file: Remote Program
  • gcore: Customizing Sessions
  • gd: Commands with Other Debuggers
  • graph disable display: Showing and Hiding Details
  • graph display: Displaying Program Status, Creating Single Displays
  • graph enable display: Showing and Hiding Details
  • graph plot: Plotting Arrays
  • graph refresh: Refreshing the Data Window
  • gunzip: Help Helpers
  • gzip: Help Helpers
  • hbreak: Hardware-Assisted Breakpoints
  • help: Getting Help
  • kill: Customizing Grab Checking
  • mwm: Gnuplot Invocation
  • print: Printing Values
  • quit: Customizing Grab Checking, Quitting
  • remsh: Remote Debugger
  • replot: Entering Plotting Commands
  • rsh: Remote Debugger
  • run: Starting Program Execution
  • set environment: Environment
  • set output: Entering Plotting Commands
  • set term: Entering Plotting Commands
  • target remote: Remote Program
  • thbreak: Hardware-Assisted Breakpoints
  • tty: Debugger Communication
  • unset environment: Environment
  • up: Selecting a frame
  • zcat: Help Helpers

Node:Resource Index, Next:File Index, Previous:Command Index, Up:Top

Resource Index

  • activeButtonColorKey: Customizing the Tool Bar
  • align2dArrays: Arrays as Tables
  • appDefaultsVersion: Customizing Diagnostics
  • arrayOrientation: Rotating Displays
  • autoCloseDataWindow: Customizing Displays
  • autoDebugger: Debugger Invocation
  • autoRaiseMenu: Auto-Raise Menus
  • autoRaiseMenuDelay: Auto-Raise Menus
  • autoRaiseTool: Customizing Tool Position
  • blockTTYInput: Debugger Communication
  • break_at: Images
  • bumpDisplays: Customizing Displays
  • buttonCaptionGeometry: Customizing the Tool Bar
  • buttonCaptions: Customizing the Tool Bar
  • buttonColorKey: Customizing the Tool Bar
  • buttonDocs: Button tips
  • buttonImageGeometry: Customizing the Tool Bar
  • buttonImages: Customizing the Tool Bar
  • buttonTips: Button tips
  • cacheGlyphImages: Customizing Glyphs
  • cacheMachineCode: Customizing Machine Code
  • cacheSourceFiles: Customizing Source Lookup
  • checkConfiguration: Customizing Diagnostics
  • checkGrabDelay: Customizing Grab Checking
  • checkGrabs: Customizing Grab Checking
  • checkOptions: Multiple Instances
  • CLASSPATH: Source Path
  • clear_at: Images
  • clusterDisplays: Customizing Displays
  • commandToolBar: Disabling the Command Tool
  • commonToolBar: Window Layout
  • consoleButtons: Customizing Buttons
  • cutCopyPasteBindings: Customizing the Edit Menu
  • dataButtons: Customizing Buttons
  • dbxDisplayShortcuts: Display Shortcuts
  • dbxInitCommands: DBX Initialization
  • dbxSettings: DBX Initialization
  • ddd: Images
  • DDD: Environment
  • DDD_NO_SIGNAL_HANDLERS: Debugging DDD
  • DDD_SESSION: Resources
  • DDD_SESSIONS: Customizing Sessions
  • DDD_STATE: Resources
  • dddinitVersion: Customizing Diagnostics
  • debugCoreDumps: Customizing Diagnostics
  • debugger: Debugger Invocation
  • debuggerCommand: Debugger Invocation
  • decorateTool: Customizing Tool Decoration
  • defaultFont: Customizing Fonts
  • defaultFontSize: Customizing Fonts
  • delete: Images
  • deleteAliasDisplays: Shared Structures
  • detectAliases: Shared Structures
  • disable: Images
  • disassemble: Customizing Machine Code
  • display: Images
  • DISPLAY: Remote Host, X Options
  • displayGlyphs: Customizing Glyphs
  • displayLineNumbers: Customizing Source Appearance
  • displayTimeout: Debugger Communication
  • dispref: Images
  • drag_arrow: Images
  • drag_cond: Images
  • drag_stop: Images
  • drag_temp: Images
  • dumpCore: Customizing Diagnostics
  • editCommand: Customizing Editing
  • EDITOR: Customizing Editing
  • enable: Images
  • expandRepeatedValues: Repeated Values
  • filterFiles: Customizing File Filtering
  • find_backward: Images
  • find_forward: Images
  • findCaseSensitive: Customizing Searching
  • findWordsOnly: Customizing Searching
  • fixedWidthFont: Customizing Fonts
  • fixedWidthFontSize: Customizing Fonts
  • flatDialogButtons: Customizing the Tool Bar
  • flatToolbarButtons: Customizing the Tool Bar
  • fontSelectCommand: Customizing Fonts
  • gdbDisplayShortcuts: Display Shortcuts
  • gdbInitCommands: GDB Initialization
  • gdbSettings: GDB Initialization
  • getCoreCommand: Customizing Sessions
  • globalTabCompletion: Command Completion
  • glyphUpdateDelay: Customizing Glyphs
  • grabAction: Customizing Grab Checking
  • grabActionDelay: Customizing Grab Checking
  • grey_arrow: Images
  • grey_cond: Images
  • grey_stop: Images
  • grey_temp: Images
  • groupIconify: Icons
  • hide: Images
  • hideInactiveDisplays: Customizing Displays
  • indentCode: Customizing Machine Code
  • indentScript: Customizing Source Appearance
  • indentSource: Customizing Source Appearance
  • jdbDisplayShortcuts: Display Shortcuts
  • jdbInitCommands: JDB Initialization
  • jdbSettings: JDB Initialization
  • labelDelimiter: Customizing Buttons
  • lessTifVersion: LessTif
  • lineBufferedConsole: Input/Output
  • lineNumberWidth: Customizing Source Appearance
  • linesAboveCursor: Customizing Source Scrolling
  • linesBelowCursor: Customizing Source Scrolling
  • listCoreCommand: Customizing Remote Debugging
  • listDirCommand: Customizing Remote Debugging
  • listExecCommand: Customizing Remote Debugging
  • listSourceCommand: Customizing Remote Debugging
  • lookup: Images
  • maintenance: Customizing Diagnostics
  • maketemp: Images
  • maxDisassemble: Customizing Machine Code
  • maxGlyphs: Customizing Glyphs
  • maxUndoDepth: Customizing Undo
  • maxUndoSize: Customizing Undo
  • new_break: Images
  • new_display: Images
  • new_watch: Images
  • openDataWindow: Toggling Windows
  • openDebuggerConsole: Toggling Windows
  • openSelection: Opening the Selection
  • openSourceWindow: Toggling Windows
  • PAGER: Customizing Diagnostics, Environment
  • pannedGraphEditor: Scrolling Data
  • paperSize: Printing the Graph
  • perlDisplayShortcuts: Display Shortcuts
  • perlInitCommands: Perl Initialization
  • perlSettings: Perl Initialization
  • plain_arrow: Images
  • plain_cond: Images
  • plain_stop: Images
  • plain_temp: Images
  • plot2dSettings: Gnuplot Settings
  • plot3dSettings: Gnuplot Settings
  • plotCommand: Gnuplot Invocation
  • plotInitCommands: Gnuplot Settings
  • plotTermType: Gnuplot Invocation
  • plotWindowClass: Gnuplot Invocation
  • plotWindowDelay: Gnuplot Invocation
  • popdownHistorySize: Text Fields
  • positionTimeout: Debugger Communication
  • print: Images
  • printCommand: Printing the Graph
  • properties: Images
  • psCommand: Customizing Attaching to Processes
  • pydbDisplayShortcuts: Display Shortcuts
  • pydbInitCommands: PYDB Initialization
  • pydbSettings: PYDB Initialization
  • questionTimeout: Debugger Communication
  • rotate: Images
  • rshCommand: Customizing Remote Debugging
  • saveHistoryOnExit: Command History
  • selectAllBindings: Customizing the Edit Menu
  • separateDataWindow: Window Layout
  • separateExecWindow: Customizing the Execution Window
  • separateSourceWindow: Window Layout
  • set: Images
  • SHELL: Arguments
  • show: Images
  • showBaseDisplayTitles: Customizing Displays
  • showConfiguration: Customizing Diagnostics
  • showDependentDisplayTitles: Customizing Displays
  • showFonts: Customizing Diagnostics
  • showInvocation: Customizing Diagnostics
  • showLicense: Customizing Diagnostics
  • showManual: Customizing Diagnostics
  • showMemberNames: Rotating Displays
  • showNews: Customizing Diagnostics
  • showVersion: Customizing Diagnostics
  • signal_arrow: Images
  • sortPopdownHistory: Text Fields
  • sourceButtons: Customizing Buttons
  • sourceEditing: In-Place Editing
  • sourceInitCommands: GDB Initialization
  • splashScreen: Splash Screen
  • splashScreenColorKey: Splash Screen
  • startupTipCount: Tip of the day
  • startupTips: Tip of the day
  • statusAtBottom: Window Layout
  • stickyTool: Customizing Tool Position
  • structOrientation: Rotating Displays
  • suppressWarnings: Customizing Diagnostics, X Warnings
  • synchronousDebugger: Debugger Communication
  • tabWidth: Customizing Source Appearance
  • TERM: Customizing the Execution Window, Environment
  • TERMCAP: Environment
  • termCommand: Customizing the Execution Window
  • terminateOnEOF: Debugger Communication
  • termType: Customizing the Execution Window
  • tip: Tip of the day
  • toolbarsAtBottom: Window Layout
  • toolButtons: Customizing Buttons
  • toolRightOffset: Customizing Tool Position
  • toolTopOffset: Customizing Tool Position
  • trace: Customizing Diagnostics
  • typedAliases: Shared Structures
  • uncompressCommand: Help Helpers
  • undisplay: Images
  • uniconifyWhenReady: Icons
  • unwatch: Images
  • useSourcePath: Customizing Source Lookup
  • useTTYCommand: Debugger Communication
  • valueDocs: Value Tips
  • valueTips: Value Tips
  • variableWidthFont: Customizing Fonts
  • variableWidthFontSize: Customizing Fonts
  • verifyButtons: Customizing Buttons
  • vslBaseDefs: Customizing Display Appearance
  • vslDefs: Customizing Display Appearance
  • vslLibrary: Customizing Display Appearance
  • vslPath: Customizing Display Appearance
  • warnIfLocked: Multiple Instances
  • watch: Images
  • WWWBROWSER: Help Helpers
  • wwwCommand: Help Helpers
  • wwwPage: Help Helpers
  • xdbDisplayShortcuts: Display Shortcuts
  • xdbInitCommands: XDB Initialization
  • xdbSettings: XDB Initialization
  • XEDITOR: Customizing Editing

Node:File Index, Next:Concept Index, Previous:Resource Index, Up:Top

File Index

  • .emacs: Integrating DDD
  • .gdbinit: Debugging DDD, Remote Program, GDB Options
  • ChangeLog: Contributors
  • dbx: Options
  • Ddd: Application Defaults, More Customizations, Resources
  • ddd-3.2-html-manual.tar.gz: About this Manual
  • ddd-3.2-pics.tar.gz: About this Manual
  • ddd-3.2.tar.gz: About this Manual
  • ddd-version-html-manual.tar.gz: Getting DDD
  • ddd-version-pics.tar.gz: Getting DDD
  • ddd-version.tar.gz: Getting DDD
  • emacs: Integrating DDD, Customizing Editing, Help Helpers
  • emacsclient: Customizing Editing
  • emacsserver: Customizing Editing
  • fig2dev: Printing the Graph
  • file: Customizing Remote Debugging
  • gdb: Options
  • gdbserver: Remote Program
  • gnuclient: Customizing Editing
  • gnuplot: Plot Appearance
  • gnuserv: Customizing Editing
  • init: Resources
  • java.prof: JDB Options
  • jdb: Options
  • ladebug: Options
  • less: Customizing Diagnostics
  • log: Logging, Entering Plotting Commands, Options
  • lynx: Help Helpers
  • make: Recompiling
  • more: Customizing Diagnostics
  • mosaic: Help Helpers
  • mozilla: Help Helpers
  • netscape: Help Helpers
  • on: Customizing Remote Debugging
  • perl: Options
  • ps: Customizing Attaching to Processes
  • pydb: Options
  • remsh: Customizing Remote Debugging
  • rsh: Customizing Remote Debugging
  • sample: Sample Session
  • sample.c: Sample Program, Sample Session
  • sessions: Customizing Sessions
  • ssh: Customizing Remote Debugging
  • stty: Input/Output
  • TODO: Contributors
  • transfig: Printing the Graph
  • vi: Customizing Editing
  • xdb: Options
  • xemacs: Integrating DDD, Customizing Editing
  • xfig: Printing the Graph
  • xfontsel: Customizing Fonts
  • xmgr: Exporting Plot Data
  • xsm: Resuming Sessions
  • xterm: Customizing the Execution Window
  • xxgdb: Integrating DDD
  • ~: Resources, Options

Node:Concept Index, Previous:File Index, Up:Top

Concept Index

  • Aborting execution: Program Menu, Quitting
  • Ada: Summary
  • Aliases, detecting: Shared Structures
  • Animating plots: Animating Plots
  • Arguments, displaying: Displaying Local Variables
  • Arguments, of the debugged program: Arguments
  • Arguments, program: Starting Program Execution
  • Array slices: Array Slices
  • Array, artificial: Array Slices
  • Array, plotting: Plotting Arrays
  • Artificial arrays: Array Slices
  • Assertions and breakpoints: Breakpoint Conditions
  • Assertions and watchpoints: Watchpoints
  • Assignment: Assignment
  • Auto-command: Commands with Other Debuggers
  • Automatic Layout: Automatic Layout
  • Balloon help: Getting Help
  • Box library: History
  • Breakpoint: Stopping
  • Breakpoint commands: Breakpoint Commands
  • Breakpoint commands, vs. conditions: Breakpoint Conditions
  • Breakpoint conditions: Breakpoint Conditions
  • Breakpoint ignore counts: Breakpoint Ignore Counts
  • Breakpoint properties: Editing Breakpoint Properties
  • Breakpoint, copying: Moving and Copying Breakpoints
  • Breakpoint, deleting: Deleting Breakpoints
  • Breakpoint, disabling: Disabling Breakpoints
  • Breakpoint, dragging: Moving and Copying Breakpoints
  • Breakpoint, editing: Editing Breakpoint Properties
  • Breakpoint, enabling: Disabling Breakpoints
  • Breakpoint, hardware-assisted: Hardware-Assisted Breakpoints
  • Breakpoint, looking up: Looking up Breakpoints
  • Breakpoint, moving: Moving and Copying Breakpoints
  • Breakpoint, setting: Setting Breakpoints
  • Breakpoint, temporary: Temporary Breakpoints
  • Breakpoint, toggling: Tool Bar
  • Breakpoints, editing: Editing all Breakpoints
  • Button editor: Defining Buttons
  • Button tip: Getting Help
  • Button tip, turning off: Button tips
  • Buttons, defining: Defining Buttons
  • C: Summary
  • C++: Summary
  • Call stack: Stack
  • Chill: Summary
  • Class, opening: Opening Programs
  • Clipboard: Edit Menu
  • Clipboard, putting displays: Deleting Displays
  • Cluster: Clustering
  • Cluster, and plotting: Scalars and Composites
  • Clustered display, creating: Creating Single Displays
  • Command completion: Command Completion
  • Command history: Command History
  • Command tool: Windows
  • Command, argument: GDB Argument Commands
  • Command, auto: Commands with Other Debuggers
  • Command, breakpoint: Breakpoint Commands
  • Command, defining: Defining Commands
  • Command, defining in GDB: GDB Simple Commands
  • Command, defining with other debuggers: Commands with Other Debuggers
  • Command, recording: GDB Simple Commands
  • Command, repeating: Command History
  • Command, searching: Command History
  • Command, user-defined: Defining Commands
  • Command-line debugger: Summary
  • Compact Layout: Automatic Layout
  • Completion of commands: Command Completion
  • Completion of quoted strings: Command Completion
  • Conditions on breakpoints: Breakpoint Conditions
  • Context-sensitive help: Getting Help
  • Continue, at different address: Continuing Somewhere Else
  • Continue, one line: Resuming Execution
  • Continue, to location: Resuming Execution
  • Continue, to next line: Resuming Execution
  • Continue, until function returns: Resuming Execution
  • Continue, until greater line is reached: Resuming Execution
  • Continuing execution: Resuming Execution
  • Continuing process execution: Attaching to a Process
  • Contour lines, in plots: Plot Appearance
  • Contributors: Contributors
  • Copying displays: Deleting Displays
  • Core dump, opening: Opening Core Dumps
  • Core file, in sessions: Saving Sessions
  • Cutting displays: Deleting Displays
  • Data Window: Displaying Values
  • Data window: Windows
  • DBX: Summary
  • DBX, invoking DDD with: Choosing an Inferior Debugger
  • Debugger console: Windows
  • Debugger, on remote host: Remote Debugger
  • Debugging DDD: Debugging DDD
  • Debugging flags: Patching
  • Debugging optimized code: Compiling for Debugging
  • Default session: Resuming Sessions
  • Deferred display: Creating Single Displays
  • Deferred display, in sessions: Saving Sessions
  • Deleting displays: Deleting Displays, Tool Bar
  • Deleting displays, undoing: Deleting Displays
  • Dependent display: Creating Single Displays
  • Dereferencing: Dereferencing Pointers
  • Detail toggling with Show/Hide: Tool Bar
  • Detail, hiding: Showing and Hiding Details
  • Detail, showing: Showing and Hiding Details
  • Directory, of the debugged program: Working Directory
  • Disabled displays: Showing and Hiding Details
  • Disabling displays, undoing: Showing and Hiding Details
  • Display: Displaying Values
  • Display Editor: Editing all Displays
  • Display name: Selecting Displays
  • Display position: Creating Single Displays
  • Display selection: Selecting Displays
  • Display title: Selecting Displays
  • Display value: Selecting Displays
  • Display, aligning on grid: Aligning Displays
  • Display, clustered: Creating Single Displays
  • Display, clustering: Clustering
  • Display, copying: Deleting Displays
  • Display, creating: Creating Single Displays, Tool Bar
  • Display, customizing: Customizing Displays
  • Display, cutting: Deleting Displays
  • Display, deferred: Creating Single Displays
  • Display, deleting: Deleting Displays, Tool Bar
  • Display, dependent: Dependent Values, Creating Single Displays
  • Display, disabled: Showing and Hiding Details
  • Display, frozen: Stopping X Programs
  • Display, hiding details: Showing and Hiding Details
  • Display, locked: Stopping X Programs
  • Display, moving: Moving Displays
  • Display, pasting: Deleting Displays
  • Display, plotting the history: Plotting Histories
  • Display, refreshing: Refreshing the Data Window
  • Display, rotating: Rotating Displays, Tool Bar
  • Display, selecting: Selecting Displays
  • Display, setting: Tool Bar, Remote Host
  • Display, setting when invoking DDD: X Options
  • Display, showing details: Showing and Hiding Details
  • Display, toggling detail: Tool Bar
  • Display, updating: Refreshing the Data Window
  • Displaying values: Displaying Values, Examining Data
  • Displaying values with Display: Tool Bar
  • Dumping values: Examining Data
  • Edge: Dependent Values
  • Edge hint: Automatic Layout, Shared Structures
  • Editing source code: Editing Source Code
  • Emacs, integrating DDD: Integrating DDD
  • Emergency repairs: Patching
  • Environment, of the debugged program: Environment
  • EPROM code debugging: Hardware-Assisted Breakpoints
  • Examining memory contents: Examining Memory
  • Execution position, dragging: Continuing Somewhere Else
  • Execution window: Using the Execution Window, Windows
  • Execution, "undoing": Undoing Program Execution
  • Execution, aborting: Program Menu, Quitting
  • Execution, at different address: Continuing Somewhere Else
  • Execution, continuing: Resuming Execution
  • Execution, interrupting: Quitting
  • Execution, one line: Resuming Execution
  • Execution, to location: Resuming Execution
  • Execution, to next line: Resuming Execution
  • Execution, until function returns: Resuming Execution
  • Execution, until greater line is reached: Resuming Execution
  • Exiting: Quitting
  • Extending display selection: Selecting Displays
  • FIG file, printing as: Printing the Graph
  • Files, opening: Opening Files
  • Finding items: Tool Bar
  • Fonts: Customizing Fonts
  • FORTRAN: Summary
  • Frame: Frames, Stack
  • Frame changes, undoing: Selecting a frame
  • Frame number: Frames
  • Frame pointer: Frames
  • Frame, selecting: Selecting a frame
  • GCC: Compiling for Debugging
  • GDB: Summary
  • GDB, invoking DDD with: Choosing an Inferior Debugger
  • Glyph: Customizing Glyphs
  • GPL: Free Software
  • Grabbed pointer: Stopping X Programs
  • Graph, printing: Printing the Graph
  • Graph, rotating: Rotating the Graph
  • Grid, aligning displays: Aligning Displays
  • Grid, in plots: Plot Appearance
  • Help: Getting Help
  • Help, in the status line: Getting Help
  • Help, on buttons: Getting Help
  • Help, on commands: Getting Help
  • Help, on items: Getting Help
  • Help, when stuck: Getting Help
  • Hiding display details: Showing and Hiding Details
  • Historic mode: Undoing Program Execution
  • History: History
  • History, plotting: Plotting Histories
  • Host, remote: Remote Host
  • HTML manual: About this Manual
  • IBMGL file, printing as: Printing the Graph
  • Icon, invoking DDD as: X Options
  • Ignore count: Breakpoint Ignore Counts
  • Indent, source code: Customizing Source Appearance
  • Inferior debugger: Summary
  • Info manual: About this Manual
  • Initial frame: Frames
  • Innermost frame: Frames
  • Input of the debugged program: Input/Output
  • Instruction, stepping: Machine Code Execution
  • Integrating DDD: Integrating DDD
  • Interrupting DDD: Quitting
  • Interrupting execution: Quitting
  • Invoking: Invoking
  • Java: Summary
  • JDB: Summary
  • JDB, invoking DDD with: Choosing an Inferior Debugger
  • Jump to different address: Continuing Somewhere Else
  • Killing DDD: Quitting
  • Killing the debugged program: Killing the Program
  • Ladebug: Summary
  • Ladebug, invoking DDD with: Choosing an Inferior Debugger
  • License: License, Free Software
  • License, showing on standard output: Options
  • Line numbers: Customizing Source Appearance
  • Local variables, displaying: Displaying Local Variables
  • Logging: Logging
  • Logging, disabling: Disabling Logging
  • Looking up breakpoints: Looking up Breakpoints
  • Looking up items: Tool Bar
  • Lookups, redoing: Looking up Previous Locations
  • Lookups, undoing: Looking up Previous Locations
  • Lütkehaus, Dorothea: History, Contributors
  • Machine code window: Windows
  • Machine code, examining: Machine Code
  • Machine code, executing: Machine Code Execution
  • Make, invoking: Recompiling
  • Manual, showing on standard output: Options
  • Memory, dumping contents: Examining Data
  • Memory, examining: Examining Memory
  • Modula-2: Summary
  • Modula-3: Summary
  • Mouse pointer, frozen: Stopping X Programs
  • Name, display: Selecting Displays
  • News, showing on standard output: Options
  • NORA: History
  • Optimized code, debugging: Compiling for Debugging
  • Option: Invoking
  • Outermost frame: Frames
  • Output of the debugged program: Input/Output
  • Pascal: Summary
  • Pasting displays: Deleting Displays
  • Patching: Patching
  • PDF manual: About this Manual
  • Perl: Summary
  • Perl, invoking DDD with: Choosing an Inferior Debugger
  • PIC file, printing as: Printing the Graph
  • Pipe: Input/Output
  • Plot appearance: Plot Appearance
  • Plot, animating: Animating Plots
  • Plot, exporting: Exporting Plot Data
  • Plot, printing: Printing Plots
  • Plot, scrolling: Plot Appearance
  • Plotting style: Plot Appearance
  • Plotting values: Plotting Values, Examining Data, Tool Bar
  • Pointers, dereferencing: Dereferencing Pointers
  • Position, of display: Creating Single Displays
  • PostScript manual: About this Manual
  • PostScript, printing as: Printing the Graph
  • Print, output formats: Printing Values
  • Printing plots: Printing Plots
  • Printing the Graph: Printing the Graph
  • Printing values: Printing Values, Examining Data
  • Printing values with Print: Tool Bar
  • Process, attaching: Attaching to a Process
  • Program arguments: Starting Program Execution
  • Program counter, displaying: Machine Code Execution
  • Program output, confusing: Input/Output
  • Program, on remote host: Remote Program
  • Program, opening: Opening Programs
  • Program, patching: Patching
  • PSG: History
  • PYDB: Summary
  • PYDB, invoking DDD with: Choosing an Inferior Debugger
  • Python: Summary
  • Quitting: Quitting
  • Quotes in commands: Command Completion
  • Readline: TTY mode
  • Recompiling: Recompiling
  • Recording commands: GDB Simple Commands
  • Redirecting I/O of the debugged program: Input/Output
  • Redirecting I/O to the execution window: Using the Execution Window
  • Redirection: Input/Output
  • Redirection, to execution window: Using the Execution Window, Debugger Communication
  • Redoing commands: Undo and Redo
  • Redoing lookups: Looking up Previous Locations
  • Refreshing displayed values: Refreshing the Data Window
  • Registers, examining: Registers
  • Reloading source code: Editing Source Code
  • Remote debugger: Remote Debugger
  • Remote host: Remote Host
  • Remote program: Remote Program
  • Resource, setting when invoking DDD: X Options
  • Resources: Resources
  • ROM code debugging: Hardware-Assisted Breakpoints
  • Rotating displays with Rotate: Tool Bar
  • Rotating the graph: Rotating the Graph
  • Running the debugged program: Running
  • Scalars, plotting: Scalars and Composites
  • Scales, in plots: Plot Appearance
  • Scrolling: Scrolling Data
  • Search, using Find >>: Tool Bar
  • Searching commands: Command History
  • Selecting frames: Selecting a frame
  • Selecting multiple displays: Selecting Displays
  • Selecting single displays: Selecting Displays
  • Session: Sessions
  • Session, active: Saving Sessions
  • Session, default: Resuming Sessions
  • Session, deleting: Deleting Sessions
  • Session, opening: Resuming Sessions
  • Session, resuming: Resuming Sessions
  • Session, saving: Saving Sessions
  • Session, setting when invoking DDD: Options
  • Setting variables: Assignment
  • Setting variables with Set: Tool Bar
  • Shared structures, detecting: Shared Structures
  • Showing display details: Showing and Hiding Details
  • SIGABRT signal: Program Menu, Quitting
  • SIGALRM signal: Signals
  • SIGINT signal: Signals, Interrupting
  • Signal settings, editing: Signals
  • Signal settings, saving: Signals
  • Signal, fatal: Signals
  • Signal, sending to DDD: Quitting
  • Signals: Signals
  • SIGSEGV signal: Signals
  • SIGTRAP signal: Signals
  • SIGUSR1 signal: Debugging DDD, Maintenance Menu
  • Source code, editing: Editing Source Code
  • Source code, recompiling: Recompiling
  • Source code, reloading: Editing Source Code
  • Source directory: Source Path
  • Source file, opening: Opening Source Files
  • Source path: Source Path
  • Source path, specifying: Source Path
  • Source window: Windows
  • Source, accessing: Source Path
  • Stack Frame: Frames
  • Stack frame: Stack
  • Stack, moving within: Selecting a frame
  • Status display: Displaying Program Status
  • Status line: Getting Help
  • Status line, location: Window Layout
  • Tab width: Customizing Source Appearance
  • TeX file, printing as: Printing the Graph
  • TeXinfo manual: About this Manual
  • Threads: Threads
  • Tic Tac Toe game: Maintenance Menu
  • Tip of the day: Getting Help
  • Tip of the day, turning off: Tip of the day
  • Tip, on buttons: Getting Help
  • Tip, value: Value Tips, Examining Data
  • Title, display: Selecting Displays
  • Tool Bar, location: Window Layout
  • Tool tip: Getting Help
  • TTY interface: TTY mode
  • TTY mode, setting when invoking DDD: Options
  • TTY settings: Input/Output
  • Undo deleting displays: Deleting Displays
  • Undo disabling displays: Showing and Hiding Details
  • Undoing commands: Undo and Redo
  • Undoing frame changes: Selecting a frame
  • Undoing lookups: Looking up Previous Locations
  • Undoing program execution: Undoing Program Execution
  • Undoing signal handling: Signals
  • Updating displayed values: Refreshing the Data Window
  • User-defined command: Defining Commands
  • Value tip: Value Tips, Examining Data
  • Value, display: Selecting Displays
  • Value, displaying: Displaying Values, Examining Data
  • Value, dumping: Examining Data
  • Value, plotting: Examining Data
  • Value, plotting the history: Plotting Histories
  • Value, printing: Printing Values, Examining Data
  • Values, displaying with Display: Tool Bar
  • Values, plotting: Plotting Values
  • Values, plotting with Plot: Tool Bar
  • Values, printing with Print: Tool Bar
  • Variables, setting: Assignment
  • Variables, setting with Set: Tool Bar
  • VSL: History
  • Watchpoint: Watchpoints, Stopping
  • Watchpoint properties: Editing Watchpoint Properties
  • Watchpoint, deleting: Deleting Watchpoints
  • Watchpoint, editing: Editing Watchpoint Properties
  • Watchpoint, setting: Setting Watchpoints
  • Watchpoint, toggling: Tool Bar
  • Watchpoints, editing: Editing all Watchpoints
  • Working directory, of the debugged program: Working Directory
  • X programs, stopping: Stopping X Programs
  • X server, frozen: Stopping X Programs
  • X server, locked: Stopping X Programs
  • X session: Resuming Sessions
  • X Warnings, suppressing: X Warnings
  • XDB: Summary
  • XDB, invoking DDD with: Choosing an Inferior Debugger
  • XEmacs, integrating DDD: Integrating DDD
  • XXGDB, integrating DDD: Integrating DDD
  • Zeller, Andreas: History, Contributors

Footnotes

  1. Within DDD (and this manual), Ladebug is considered a DBX variant. Hence, everything said for DBX also applies to Ladebug, unless stated otherwise.

  2. XDB will no longer be maintained in future DDD releases. Use a recent GDB version instead.

  3. Actual numbers and behavior on your system may vary.

  4. Re-invoke DDD with --gdb, if you do not see a (gdb) prompt here (see Choosing an Inferior Debugger)

  5. Only if a core file is included.

  6. If a core file is not to be included in the session, DDD data displays are saved as deferred; that is, they will be restored as soon as program execution reaches the scope in which they were created. See Creating Single Displays, for details.

  7. Requires X11R6 or later.

  8. If you use a Ddd application-defaults file, you will not be able to maintain multiple DDD versions at the same time. This is why the suiting Ddd is normally compiled into the DDD executable.

  9. If you use DDD to debug Perl or Python scripts, then this section does not apply.

  10. With XDB and some DBX variants, the debugged program must be specified upon invocation and cannot be changed at run time.

  11. JDB, PYDB, and Perl do not support core dumps.

  12. JDB does not support breakpoint disabling.

  13. JDB does not support temporary breakpoints.

  14. GDB has no way to make a temporary breakpoint non-temporary again.

  15. JDB, Perl and some DBX variants do not support breakpoint ignore counts.

  16. JDB, PYDB, and some DBX variants do not support breakpoint commands.

  17. When glyphs are disabled (see Customizing Source), breakpoints cannot be dragged. Delete and set breakpoints instead.

  18. Watchpoints are available in GDB and some DBX variants only. In XDB, a similar feature is available via XDB assertions; see the XDB documentation for details.

  19. If <Ctrl+C> is not bound to Copy (see Customizing the Edit Menu), you can also use <Ctrl+C> to interrupt the running program.

  20. If the debuggee runs in a separate execution window, the debuggee's TERM value is set according to the termType resource; See Customizing the Execution Window, for details.

  21. The execution window is not available in JDB.

  22. JDB, PYDB, and Perl do not support attaching the debugger to running processes.

  23. JDB, PYDB, and Perl do not support altering the execution position.

  24. When glyphs are disabled (see Customizing Source), dragging the execution position is not possible. Set the execution position explicitly instead.

  25. Perl does not allow changing the current stack frame.

  26. Currently, threads are supported in GDB and JDB only.

  27. This requires that the full array size is known to the debugger.

  28. JDB does not support changing variable values.

  29. The string //; can be changed via the labelDelimiter resource. See Customizing Buttons, for details.

  30. valign() is similar to halign(), but builds a vertical alignment.

  31. The machine code window is available with GDB only.

  32. The machine code window is available with GDB and some DBX variants only.

  33. If you use DDD commands within command definitions, or if you include debugger commands that resume execution, these commands will be realized transparently as auto-commands--that is, they won't be executed directly by the inferior debugger, but result in a command string being sent to DDD. This command string is then interpreted by DDD and sent back to the inferior debugger, possibly prefixed by some other commands such that DDD can update its state. See Commands with Other Debuggers, for a discussion.

  34. Since the inferior debugger is invoked through a virtual TTY, standard error is normally redirected to standard output, so DDD never receives standard error from the inferior debugger.


DejaGnu Testing Framework

The DejaGnu Testing Framework

for DejaGnu Version 1.3

Jan 1996

Rob Savoye

Table of Contents

  • What is DejaGnu?
  • What is new in this release ?
    • Running existing tests
    • What does a DejaGnu test look like?
    • Design goals
    • A POSIX conforming test framework
    • Future directions
    • Tcl and Expect
  • Using runtest
  • Setting runtest defaults
      • Config Variables
      • Master Config File
      • Local Config File
      • Personal Config File
  • The DejaGnu Implementation
    • Conventions for using tool names
    • Initialization module
    • DejaGnu procedures
      • Core Internal Procedures
      • Remote Communication Procedures
      • Utility Procedures
      • Cross target procedure
      • Debugging Procedures
    • Target dependent procedures
    • Remote targets supported
    • The files DejaGnu reads
    • The files DejaGnu writes
      • Summary log
      • Detailed log
      • Logging expect internal actions
  • How To Write a Test Case
    • Writing a test case
    • Debugging a test case
    • Adding a test case to a test suite
    • Hints on writing a test case
    • Special variables used by test cases
  • New Tools, Targets, or Hosts
    • Writing tests for a new tool
    • Adding a target
    • Porting to a new host
  • Installing DejaGnu
    • Configuring the DejaGnu test driver
    • Installing DejaGnu
  • Index

o\input texinfo

Copyright (C) 92, 93, 94, 95, 1996 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

@raggedbottom

What is DejaGnu?

DejaGnu is a framework for testing other programs. Its purpose is to provide a single front end for all tests. Beyond this, DejaGnu offers several advantages for testing:

  1. The flexibility and consistency of the DejaGnu framework make it easy to write tests for any program.
  2. DejaGnu provides a layer of abstraction which allows you to write tests that are portable to any host or target where a program must be tested. For instance, a test for GDB can run (from any Unix based host) on any target architecture that DejaGnu supports. Currently DejaGnu runs tests on several single board computers, whose operating software ranges from just a boot monitor to a full-fledged, Unix-like realtime OS.
  3. All tests have the same output format. This makes it easy to integrate testing into other software development processes. DejaGnu's output is designed to be parsed by other filtering script, and it is also human readable.

DejaGnu is written in expect, which in turn uses Tcl---Tool command language.

Running tests requires two things: the testing framework, and the test suites themselves. Tests are usually written in expect using Tcl, but you can also use a Tcl script to run a test suite that is not based on expect. (expect script filenames conventionally use `.exp' as a suffix; for example, the main implementation of the DejaGnu test driver is in the file `runtest.exp'.)

What is new in this release ?

This release has a number of substantial changes over version 1.2. The most visible change is that the version of expect and Tcl included in the release are up-to-date with the current stable net releases. Other changes are:

  1. The config sub-system in DejaGnu has been completely redesigned. It now supports testing on remote hosts as well as remote targets.
  2. More builtin support for building target binaries with the correct linker flags. Currently this only works with GCC, preferably with a target support by libgloss.
  3. Lots of little bug fixes from a year of heavy use here at Cygnus Support.
  4. DejaGnu now uses autoconf for configuration.
  5. New test cases for DejaGnu have been added for the new features, plus the "--tool" option bug in the 1.2 testsuite has been fixed.
  6. The --tool option is now optional.
  7. runtest when searching for test drivers ignores all directories named SCCS, RCS, and CVS.
  8. There is now a generic keyword based test harness that uses comments in source code to control how each test case gets built and run.
  9. There is now some support for running a testsuite with multiple passes.

Running existing tests

To run tests from an existing collection, first use configure as usual to set up the source directory containing the tests. Then try running

make check

If the check target exists, it usually saves you some trouble--for instance, it can set up any auxiliary programs or other files needed by the tests.

Once you have run `make check' to build any auxiliary files, you might want to call the test driver runtest directly to repeat the tests. You may also have to call runtest directly for test collections with no check target in the `Makefile'.

Typically, you must use two command-line options: `--tool', to specify which set of tests to run(1), and `--srcdir', to specify where to find test directories.

For example, if the directory `gdb/testsuite' contains a collection of DejaGnu tests for GDB, you can run them like this:

eg$ cd gdb/testsuite
eg$ runtest --tool gdb
Test output follows, ending with:

        === gdb Summary ===

# of expected passes 508
# of expected failures 103
/usr/latest/bin/gdb version 4.14.4 -nx

You can use the option `--srcdir' to point to some other directory containing a collection of tests:

eg$ runtest --tool gdb --srcdir /devo/gdb/testsuite

These examples assume a native configuration, where the same computer runs both runtest and the tests themselves. When you have a cross configuration, the tests run on a different computer, controlled by the host running runtest. In this situation, you need the option `--name' to specify the network address for the other computer:

eg$ runtest --tool gdb --name vx9.munist.com

If you always use the same option values, you can record them in a file called `site.exp', rather than typing them each time. See section Config Variables.

By default, runtest prints only the names of the tests it runs, output from any tests that have unexpected results, and a summary showing how many tests passed and how many failed. To display output from all tests (whether or not they behave as expected), use the `--all' option. For more verbose output about processes being run, communication, and so on, use `--verbose'. To see even more output, use multiple `--verbose' options. See section Using runtest, for a more detailed explanation of each runtest option.

Test output goes into two files in your current directory: summary output in `tool.sum', and detailed output in `tool.log'. (tool refers to the collection of tests; for example, after a run with `--tool gdb', look for output files `gdb.sum' and `gdb.log'.) See section The files DejaGnu writes.

What does a DejaGnu test look like?

Each DejaGnu test is an expect script; the tests vary widely in complexity, depending on the nature of the tool and the feature tested.

Here is a very simple GDB test--one of the simplest tests shipped with DejaGnu (extracted from `gdb.t00/echo.exp'):(2)

# send a string to the GDB stdin:
send "echo Hello world!\n"

# inspect the GDB stdout for the correct reply,
# and determine whether the test passes or fails:
expect {
  -re "Hello world.*$prompt $"    { pass "Echo test" }
  -re "$prompt $"                 { fail "Echo test" }
  timeout                         { fail "(timeout) Echo test" }
  }

Though brief, this example is a complete test. It illustrates some of the main features of DejaGnu test scripts:

  • The test case does not start the tested program (GDB in this case); all test scripts for interactive tools can assume the corresponding tool is running.
  • Comments start with `#'.
  • The main commands you use to control a tested program are send (to give it commands) and expect (to analyze its responses).
  • The expect command uses a list of pairs; a pattern (regular expression if `-re' specified), followed by an action to run if the pattern matches output from the program. Only the action for the first matching pattern will execute.
  • Test cases use the commands pass and fail to record the test outcome.

Design goals

DejaGnu grew out of the internal needs of Cygnus Support. Cygnus maintains and enhances a variety of free programs in many different environments, and we needed a testing tool that:

  • is useful to developers while fixing bugs;
  • automates running many tests during a software release process;
  • is portable among a variety of host computers;
  • supports cross-development testing;
  • permits testing interactive programs, like GDB; and
  • permits testing batch oriented programs, like GCC.

Some of the requirements proved challenging. For example, interactive programs do not lend themselves very well to automated testing. But all the requirements are important: for instance, it is imperative to make sure that GDB works as well when cross-debugging as it does in a native configuration.

Probably the greatest challenge was testing in a cross-development environment (which can be a real nightmare). Most cross-development environments are customized by each developer. Even when buying packaged boards from vendors there are many differences. The communication interfaces vary from a serial line to ethernet. DejaGnu was designed with a modular communication setup, so that each kind of communication can be added as required, and supported thereafter. Once a communication procedure is coded, any test can use it. Currently DejaGnu can use rsh, rlogin, telnet, tip, kermit, and mondfe for remote communications.

Julia Menapace first coined the term "Deja Gnu" to describe an earlier testing framework at Cygnus Support. When we replaced it with the Expect-based framework, it was like DejaGnu all over again...

A POSIX conforming test framework

DejaGnu conforms to the POSIX standard for test frameworks.

POSIX standard 1003.3 defines what a testing framework needs to provide, in order to permit the creation of POSIX conformance test suites. This standard is primarily oriented to running POSIX conformance tests, but its requirements also support testing of features not related to POSIX conformance. POSIX 1003.3 does not specify a particular testing framework, but at this time there is only one other POSIX conforming test framework: TET.(3)

The POSIX documentation refers to assertions. An assertion is a description of behavior. For example, if a standard says "The sun shall shine", a corresponding assertion might be "The sun is shining." A test based on this assertion would pass or fail depending on whether it is daytime or nighttime. It is important to note that the standard being tested is never 1003.3; the standard being tested is some other standard, for which the assertions were written.

As there is no test suite to test testing frameworks for POSIX 1003.3 conformance, verifying conformance to this standard is done by repeatedly reading the standard and experimenting. One of the main things 1003.3 does specify is the set of allowed output messages, and their definitions. Four messages are supported for a required feature of POSIX conforming systems, and a fifth for a conditional feature. DejaGnu supports the use of all five output messages; in this sense a test suite that uses exactly these messages can be considered POSIX conforming. These definitions specify the output of a test case:

PASS
A test has succeeded. That is, it demonstrated that the assertion is true.
XFAIL
POSIX 1003.3 does not incorporate the notion of expected failures, so PASS, instead of XPASS, must also be returned for test cases which were expected to fail and did not. This means that PASS is in some sense more ambiguous than if XPASS is also used. For information on XPASS and XFAIL, see section Using runtest.
FAIL
A test has produced the bug it was intended to capture. That is, it has demonstrated that the assertion is false. The FAIL message is based on the test case only. Other messages are used to indicate a failure of the framework. As with PASS, POSIX tests must return FAIL rather than XFAIL even if a failure was expected.
UNRESOLVED
A test produced indeterminate results. Usually, this means the test executed in an unexpected fashion; this outcome requires that a human being go over results, to determine if the test should have passed or failed. This message is also used for any test that requires human intervention because it is beyond the abilities of the testing framework. Any unresolved test should resolved to PASS or FAIL before a test run can be considered finished. Note that for POSIX, each assertion must produce a test result code. If the test isn't actually run, it must produce UNRESOLVED rather than just leaving that test out of the output. This means that you have to be careful when writing tests, to not carelessly use tcl statements like return---if you alter the flow of control of the tcl code you must insure that every test still produces some result code. Here are some of the ways a test may wind up UNRESOLVED:
  • A test's execution is interrupted.
  • A test does not produce a clear result. This is usually because there was an ERROR from DejaGnu while processing the test, or because there were three or more WARNING messages. Any WARNING or ERROR messages can invalidate the output of the test. This usually requires a human being to examine the output to determine what really happened--and to improve the test case.
  • A test depends on a previous test, which fails.
  • The test was set up incorrectly.
UNTESTED
A test was not run. This is a placeholder, used when there is no real test case yet.

The only remaining output message left is intended to test features that are specified by the applicable POSIX standard as conditional:

UNSUPPORTED
There is no support for the tested case. This may mean that a conditional feature of an operating system, or of a compiler, is not implemented. DejaGnu also uses this message when a testing environment (often a "bare board" target) lacks basic support for compiling or running the test case. For example, a test for the system subroutine gethostname would never work on a target board running only a boot monitor.

DejaGnu uses the same output procedures to produce these messages for all test suites, and these procedures are already known to conform to POSIX 1003.3. For a DejaGnu test suite to conform to POSIX 1003.3, you must avoid the setup_xfail procedure as described in the PASS section above, and you must be careful to return UNRESOLVED where appropriate, as described in the UNRESOLVED section above.

Future directions

In the near future, there are two parallel directions for DejaGnu development. The first is to add support for more hosts and targets.

The second would permit testing programs with a more complex interface, whether text based or GUI based. Two components already exist: a Tcl based X window toolkit, and a terminal package for expect. Both of these could be merged into DejaGnu in a way that permits testing programs that run in each environment.

Meanwhile, we hope DejaGnu enables the creation of test suites for conformance to ANSI C and C++, to POSIX, and to other standards. We encourage you to make any test suites you create freely available, under the same terms as DejaGnu itself.

Tcl and Expect

Tcl was introduced in a paper by John K. Ousterhout at the 1990 Winter Usenix conference, Tcl: An Embeddable Command Language. That paper is included in PostScript form in the `doc' subdirectory of the Tcl distribution. The version of Tcl included in DejaGnu at this time is Tcl 7.4p3.

Don Libes introduced expect in his paper expect: Curing Those Uncontrollable Fits of Interaction at the 1990 Summer Usenix conference. The paper is included in PostScript form in the expect distribution (as are several other papers about expect). The version of expect included in DejaGnu at this time is expect 5.18.0.

Using runtest

runtest is the executable test driver for DejaGnu. You can specify two kinds of things on the runtest command line: command line options, and Tcl variables for the test scripts. The options are listed alphabetically below.

runtest returns an exit code of 1 if any test has an unexpected result; otherwise (if all tests pass or fail as expected) it returns 0 as the exit code.

runtest flags the outcome of each test as one of these cases. (See section A POSIX conforming test framework, for a discussion of how POSIX specifies the meanings of these cases.)

PASS
The most desirable outcome: the test succeeded, and was expected to succeed.
XPASS
A pleasant kind of failure: a test was expected to fail, but succeeded. This may indicate progress; inspect the test case to determine whether you should amend it to stop expecting failure.
FAIL
A test failed, although it was expected to succeed. This may indicate regress; inspect the test case and the failing software to locate the bug.
XFAIL
A test failed, but it was expected to fail. This result indicates no change in a known bug. If a test fails because the operating system where the test runs lacks some facility required by the test, the outcome is UNSUPPORTED instead.
UNRESOLVED
Output from a test requires manual inspection; the test suite could not automatically determine the outcome. For example, your tests can report this outcome is when a test does not complete as expected.
UNTESTED
A test case is not yet complete, and in particular cannot yet produce a PASS or FAIL. You can also use this outcome in dummy "tests" that note explicitly the absence of a real test case for a particular property.
UNSUPPORTED
A test depends on a conditionally available feature that does not exist (in the configured testing environment). For example, you can use this outcome to report on a test case that does not work on a particular target because its operating system support does not include a required subroutine.

runtest may also display the following messages:

ERROR
Indicates a major problem (detected by the test case itself) in running the test. This is usually an unrecoverable error, such as a missing file or loss of communication to the target. (POSIX test suites should not emit this message; use UNSUPPORTED, UNTESTED, or UNRESOLVED instead, as appropriate.)
WARNING
Indicates a possible problem in running the test. Usually warnings correspond to recoverable errors, or display an important message about the following tests.
NOTE
An informational message about the test case.

This is the full set of command line options that runtest recognizes. Arguments may be abbreviated to the shortest unique string.

runtest --tool tool  [ testsuite.exp ... ]
[ testsuite.exp="testfile1 ..." ]
[ tclvar=value... ]
[ --all ]  [ --baud baud-rate ]  [ --connect type ]
[ --debug ]  [ --help ]  [ --host string ]
[ --mail "name ..." ]  [ --name string ]
[ --name name ]  [ --outdir path ]
[ --objdir path ]  [ --reboot ]
[ --srcdir path ]  [ --strace n ]
[ --target string --build string ]
[ -v | --verbose ]  [ -V | --version ]  [ --Dn ]
--tool tool
tool specifies what set of tests to run, and what initialization module to use. tool is used only for these two purposes: it is not used to name the executable program to test. Executable tool names (and paths) are recorded in `site.exp' (see section Config Variables), and you can override them by specifying Tcl variables on the command line. For example, including `--tool gcc' on the runtest command line runs tests from all test subdirectories whose names match `gcc.*', and uses one of the initialization modules named `config/*-gcc.exp'. To specify the name of the compiler (perhaps as an alternative path to what runtest would use by default), use `GCC=binname' on the runtest command line.
testsuite.exp ...
Specify the names of testsuites to run. By default, runtest runs all tests for the tool, but you can restrict it to particular testsuites by giving the names of the `.exp' expect scripts that control them. testsuite.exp may not include path information; use plain filenames.
testfile.exp="testfile1 ..."
Specify a subset of tests in a suite to run. For compiler or assembler tests, which often use a single `.exp' script covering many different source files, this option allows you to further restrict the tests by listing particular source files to compile. Some tools even support wildcards here. The wildcards supported depend upon the tool, but typically they are ?, *, and [chars].
tclvar=value
You can define Tcl variables for use by your test scripts in the same style used with make for environment variables. For example, `runtest GDB=gdb.old' defines a variable called `GDB'; when your scripts refer to `$GDB' in this run, they use the value `gdb.old'. The default Tcl variables used for most tools are defined in the main DejaGnu Makefile; their values are captured in the `site.exp' file. See section Config Variables.
--all
Display all test output. By default, runtest shows only the output of tests that produce unexpected results; that is, tests with status `FAIL' (unexpected failure), `XPASS' (unexpected success), or `ERROR' (a severe error in the test case itself). Specify `--all' to see output for tests with status `PASS' (success, as expected) `XFAIL' (failure, as expected), or `WARNING' (minor error in the test case itself).
--baud baud-rate
-b baud-rate
Set the default baud rate to something other than 9600. (Some serial interface programs, like tip, use a separate initialization file instead of this value.)
--connect type
Connect to a target testing environment as specified by type, if the target is not the computer running runtest. For example, use `--connect' to change the program used to connect to a "bare board" boot monitor. The choices for type in the DejaGnu 1.0 distribution are `rlogin', `telnet', `rsh', `tip', `kermit', and `mondfe'. The default for this option depends on the configuration (see section Remote targets supported). The default is chosen to be the most convenient communication method available, but often other alternatives work as well; you may find it useful to try alternative connect methods if you suspect a communication problem with your testing target.
--debug
Turns on the expect internal debugging output. Debugging output is displayed as part of the runtest output, and logged to a file called `dbg.log'. The extra debugging output does not appear on standard output, unless the verbose level is greater than 2 (for instance, to see debug output immediately, specify `--debug -v -v'). The debugging output shows all attempts at matching the test output of the tool with the scripted patterns describing expected output. The output generated with `--strace' also goes into `dbg.log'.
--help
-he
Prints out a short summary of the runtest options, then exits (even if you also specify other options).
--host string
string is a full configuration "triple" name as used by configure. Use this option to override the default string recorded by your configuration's choice of host. This choice does not change how anything is actually configured unless --build is also specified; it affects only DejaGnu procedures that compare the host string with particular values. The procedures ishost, istarget, isnative, and setup_xfail are affected by `--host'. In this usage, host refers to the machine that the tests are to be run on, which may not be the same as the build machine. If --build is also specified, then --host refers to the machine that the tests wil, be run on, not the machine DejaGnu is run on.
--build string
string is a full configuration "triple" name as used by configure. This is the type of machine DejaGnu and the tools to be tested are built on. For a normal cross this is the same as the host, but for a canadian cross, they are seperate.
--name name
name is a name for the particular testing target machine (for cross testing). If the testing target has IP network support (for example, RPC or NFS), this is the network name for the target itself. (name is not the configuration string you specify as a target with configure; the `--name' option names a particular target, rather than describing a class of targets.) For targets that connect in other ways, the meaning of the name string depends on the connection method. See section Remote targets supported.
--name string
Specify a network name of testing target or its host. The particular names that are meaningful with `--name' will depend on your site configuration, and on the connection protocol: for example, tip connections require names from a serial line configuration file (usually called `/etc/remote'), while telnet connections use IP hostnames.
--objdir path
Use path as the top directory containing any auxiliary compiled test code. This defaults to `.'. Use this option to locate pre-compiled test code. You can normally prepare any auxiliary files needed with make.
--outdir path
Write output logs in directory path. The default is `.', the directory where you start runtest. This option affects only the summary and the detailed log files `tool.sum' and `tool.log'. The DejaGnu debug log `dbg.log' always appears (when requested) in the local directory.
--reboot
Reboot the target board when runtest initializes. Usually, when running tests on a separate target board, it is safer to reboot the target to be certain of its state. However, when developing test scripts, rebooting takes a lot of time.
--srcdir path
Use path as the top directory for test scripts to run. runtest looks in this directory for any subdirectory whose name begins with the toolname (specified with `--tool'). For instance, with `--tool gdb', runtest uses tests in subdirectories `gdb.*' (with the usual shell-like filename expansion). If you do not use `--srcdir', runtest looks for test directories under the current working directory.
--strace n
Turn on internal tracing for expect, to n levels deep. By adjusting the level, you can control the extent to which your output expands multi-level Tcl statements. This allows you to ignore some levels of case or if statements. Each procedure call or control structure counts as one "level". The output is recorded in the same file, `dbg.log', used for output from `--debug'.
--target string
Use this option to override the default setting (running native tests). string is a full configuration "triple" name(4) as used by configure. This option changes the configuration runtest uses for the default tool names, and other setup information. See section `Using configure' in Cygnus configure, for details about configure names.
--verbose
-v
Turns on more output. Repeating this option increases the amount of output displayed. Level one (`-v') is simply test output. Level two (`-v -v') shows messages on options, configuration, and process control. Verbose messages appear in the detailed (`*.log') log file, but not in the summary (`*.sum') log file.
--version
-V
Prints out the version numbers of DejaGnu, expect and Tcl, and exits without running any tests.
-D0
-D1
Start the internal Tcl debugger. The Tcl debugger supports breakpoints, single stepping, and other common debugging activities. (See A Debugger for Tcl Applications by Don Libes. (5)) If you specify `-D1', the expect shell stops at a breakpoint as soon as DejaGnu invokes it. If you specify `-D0', DejaGnu starts as usual, but you can enter the debugger by sending an interrupt (e.g. by typing C-c).

Setting runtest defaults

The site configuration file, `site.exp', captures configuration-dependent values and propagates them to the DejaGnu test environment using Tcl variables. This ties the DejaGnu test scripts into the configure and make programs.

DejaGnu supports more than one `site.exp' file. The multiple instances of `site.exp' are loaded in a fixed order built into DejaGnu (the more local last). The first file loaded is the optional ~/.dejagnurc, then the local files, and finally the global file.

  1. There is am optional "master" `site.exp', capturing configuration values that apply to DejaGnu across the board, in each configuration-specific subdirectory of the DejaGnu library directory. runtest loads these values first. See section Installing DejaGnu. The master `site.exp' contains the default values for all targets and hosts supported by DejaGnu. This master file is identified by setting the environment variable DEJAGNU to the name of the file. This is also refered to as the "global" config file.
  2. Any directory containing a configured test suite also has a `site.exp', capturing configuration values specific to the tool under test. Since runtest loads these values last, the individual test configuration can either rely on and use, or override, any of the global values from the "master" `site.exp'. You can usually generate or update the testsuite `site.exp' by typing `make site.exp' in the test suite directory, after the test suite is configured.
  3. You can also have a file in your home directory called .dejagnurc. This gets loaded first before the other config files. Usually this is used for personal stuff, like setting all_flag so all the output gets printed, or verbosity levels.

You can further override the default values in a user-editable section of any `site.exp', or by setting variables on the runtest command line.

Config Variables

DejaGnu uses a named array in Tcl to hold all the info for each machine. In the case of a canadian cross, this means host information as well as target information. The named array is called target_info, and it has two indices. The following fields are part of the array.

name
The name of the target. (mostly for error messages) This should also be the string used for this target's array. It should also be the same as the linker script so we can find them dynamically. This should be the same as the argument used for push_target{}.
ldflags
This is the linker flags required to produce a fully linked executable. For libgloss supported targets this is usually just the name of the linker script.
config
The target canonical for this target. This is used by some init files to make sure the target is supported.
cflags
The flags required to produce an object file from a source file.
connect
This is the connectmode for this target. This is for both IP and serial connections. Typically this is either telnet, rlogin, or rsh.
target
This is the hostname of the target. This is for TCP/IP based connections, and is also used for version of tip that use /etc/remote.
serial
This is the serial port. This is typically /dev/tty? or com?:.
netport
This is the IP port. This is commonly used for telneting to target boards that are connected to a terminal server. In that case the IP port specifies the which serial port to use.
baud
This is the baud rate for a serial port connection.
x10
This is the parameters for an x10 controller. These are simple devices that let us power cycle or reset a target board remotely.
fileid
This is the fileid or spawn id of of the connection.
prompt
a glob style pattern to recognize the prompt.
abbrev
abbreviation for tool init files.
ioport
This is the port for I/O on dual port systems. In this configuration, the main serial port 0 is usually used for stdin and stdout, which the second serial port can be used for debugging.

The first index into the array is the same value as used in the name field. This is usually a short version of the name of the target board. For an example, here's the settings I use for my Motorola's IDP board and my Motorola 6U VME MVME135-1 board. (both m68k targets)

# IDP board
set target_info(idp,name)       "idp"
set target_info(idp,ldflags)    "-Tidp.ld"
set target_info(idp,config)     m68k-unknown-aout
set target_info(idp,cflags)     ""
set target_info(idp,connect)    telnet
set target_info(idp,target)     "s7"
set target_info(idp,serial)     "tstty7"
set target_info(idp,netport)    "wharfrat:1007"
set target_info(idp,baud)       "9600"
# MVME 135 board
set target_info(idp,name)       "mvme"
set target_info(idp,ldflags)    "-Tmvme.ld"
set target_info(idp,config)     m68k-unknown-aout
set target_info(idp,cflags)     ""
set target_info(idp,connect)    telnet
set target_info(idp,target)     "s8"
set target_info(idp,serial)     "tstty8"
set target_info(idp,netport)    "wharfrat:1008"
set target_info(idp,baud)       "9600"

DejaGnu can use this information to switch between multiple targets in one test run. This is done through the use of the push_target procedure, which is discussed elsewhere.

This array can also hold information for a remote host, which is used when testing a candain cross. In this case, the only thing different is the index is just host. Here's the settings I use to run tests on my NT machine while running DejaGnu on a Unix machine. (in this case a Linux box)

set target_info(host,name)      "nt-host"
set target_info(host,config)    "386-unknown-winnt"
set target_info(host,connect)   "telnet"
set target_info(host,target)    "ripple"

There is more info on how to use these variables in the sections on the config files. See section Master Config File.

In the user editable second section of `site.exp', you can not only override the configuration variables captured in the first section, but also specify default values for all the runtest command line options. Save for `--debug', `--help', and `--version', each command line option has an associated Tcl variable. Use the Tcl set command to specify a new default value (as for the configuration variables). The following table describes the correspondence between command line options and variables you can set in `site.exp'. See section Using runtest, for explanations of the command-line options.

Master Config File

The master config file is where all the target specific config variables get set for a whole site get set. The idea is that for a centralized testing lab where people have to share a target between multiple developers. There are settings for both remote targets and remote hosts. Here's an example of a Master Config File (also called the Global config file) for a canadian cross. A canadian cross is when you build and test a cross compiler on a machine other than the one it's to be hosted on.

Here we have the config settings for our California office. Note that all config values are site dependant. Here we have two sets of values that we use for testing m68k-aout cross compilers. As both of these target boards has a different debugging protocol, we test on both of them in sequence.

global CFLAGS
global CXXFLAGS

case "$target_triplet" in {
    { "native" } {
        set target_abbrev unix
    }
    { "m68*-unknown-aout" } {
        set target_abbrev               "rom68k"
        # IDP target                    # IDP board with rom68k monitor
        set target_info(idp,name)       "idp"
        set target_info(idp,ldflags)    "-Tidp.ld"
        set target_info(idp,config)     m68k-unknown-aout
        set target_info(idp,cflags)     ""
        set target_info(idp,connect)    telnet
        set target_info(idp,target)     "s7"
        set target_info(idp,serial)     "tstty12"
        set target_info(idp,netport)    "truckin:1007"
        set target_info(idp,baud)       "9600"
        # MVME target                   # Motorola MVME 135 with BUG monitor
        set target_info(mvme,name)      "mvme"
        set target_info(mvme,ldflags)   "-Tmvme.ld"
        set target_info(mvme,config)    m68k-unknown-aout
        set target_info(mvme,cflags)    ""
        set target_info(mvme,connect)   telnet
        set target_info(mvme,target)    "s4"
        set target_info(mvme,serial)    "tstty8"
        set target_info(mvme,netport)   "truckin:1004"
        set target_info(mvme,baud)      "9600"
     }
}

In this case, we have support for several remote hosts for our m68k-aout cross compiler. Typically the remote Unix hosts run DejaGnu locally, but we also use them for debugging the testsuites when we find problems in running on remote hosts. Expect won't run on NT, so DejaGnu is run on the local build machine, and it'll connect to the NT host and run all the tests for this cross compiler on that host.

case "$host_triplet" in {
    "native" {
    }
    "i?86-*-linux*" {                   # Linux host
        set target_info(host,name)      "linux-host"
        set target_info(host,config)    $host_triplet
        set target_info(host,connect)   rlogin
        set target_info(host,target)    chinadoll
    }
    "i?86-*-winnt                       # NT host
        set target_info(host,name)      "nt-host"
        set target_info(host,config)    i386-unknown-winnt
        set target_info(host,connect)   telnet
        set target_info(host,target)    ripple
    }
    "hppa*-hp-hpux*" {                  # HP-UX host
        set target_info(host,name)      "hpux-host"
        set target_info(host,config)    $host_triplet
        set target_info(host,connect)   rlogin
        set target_info(host,target)    slipknot
        }
    "sparc-sun-sunos*" {                # SunOS (sun4)
        set target_info(host,name)      "sunos-host"
        set target_info(host,config)    $host_triplet
        set target_info(host,connect)   rlogin
        set target_info(host,target)    darkstar
    }
}

Local Config File

It is usually more convenient to keep these "manual overrides" in the `site.exp' local to each test directory, rather than in the "master" `site.exp' in the DejaGnu library.

All local `site.exp' usually files have two sections, separated by comment text. The first section is the part that is generated by make. It is essentially a collection of Tcl variable definitions based on `Makefile' environment variables. Since they are generated by make, they contain the values as specified by configure. (You can also customize these values by using the `--site' option to configure.) In particular, this section contains the `Makefile' variables for host and target configuration data. Do not edit this first section; if you do, your changes are replaced next time you run make.

The first section starts with:

## these variables are automatically generated by make ##
# Do not edit here. If you wish to override these values
# add them to the last section

In the second section, you can override any default values (locally to DejaGnu) for all the variables. The second section can also contain your preferred defaults for all the command line options to runtest. This allows you to easily customize runtest for your preferences in each configured test-suite tree, so that you need not type options repeatedly on the command line. (The second section may also be empty, if you do not wish to override any defaults.)

The first section ends with this line:

## All variables above are generated by configure. Do Not Edit ##

You can make any changes under this line. If you wish to redefine a variable in the top section, then just put a duplicate value in this second section. Usually the values defined in this config file are related to the configuration of the test run. This is the ideal place to set the variables host_triplet, build_triplet, target_triplet. All other variables are tool dependant. ie for testing a compiler, the value for CC might be set to a freshly built binary, as opposed to one in the user's path.

Personal Config File

The personal config file is used to customize runtest's behaviour for each person. It's typically used to set the user prefered setting for verbosity, and any experimental Tcl procedures. My personal `~/.dejagnurc' file looks like:

set all_flag 1
set RLOGIN /usr/ucb/rlogin
set RSH /usr/ucb/rsh

Here I set all_flag so I see all the test cases that PASS along with the ones that FAIL. I also set RLOGIN and RSH to the BSD version. I have kerberos installed, and when I rlogin to a target board, it usually isn't supported. So I use the non secure versions of these programs rather than the default that's in my path.

The DejaGnu Implementation

DejaGnu is entirely written in expect, which uses Tcl as a command language. expect serves as a very programmable shell; you can run any program, as with the usual Unix command shells--but once the program is started, your expect script has fully programmable control of its input and output. This does not just apply to the programs under test; expect can also run any auxiliary program, such as diff or sh, with full control over its input and output.

DejaGnu itself is merely a framework for the set of test suites distributed separately for each GNU tool. Future releases of GNU tools will include even more tests, developed throughout the free software community.

runtest is the glue to tie together and manage the test scripts. The runtest program is actually a simple Bourne shell script that locates a copy of the expect shell and then starts the main Tcl code, runtest.exp. runtest.exp itself has these essential functions:

  1. Parse the command line options, load the library files, and load the default configuration files.
  2. Locating the individual test scripts. runtest.exp locates the tests by exploiting a straightforward naming convention based on the string you specify with the `--tool' option.
  3. Providing an extended test environment, by defining additional Tcl procedures beyond those already in expect.
  4. Locating target-dependent functions, to standardize the test environment across a wide variety of test platforms.

Conventions for using tool names

DejaGnu uses `$tool', the name of the tool under test, to tie together the testing configuration in a straightforward but flexible way. If there is only one testsuite for a particular application, then `$tool' is optional.

`$tool' is not used to invoke the tool, since sites that run multiple configurations of a particular tool often call each configuration by a different name. runtest uses the configuration-dependent variables captured in `site.exp' to determine how to call each tool.

runtest uses tool names to find directories containing tests. runtest scans the source directory (specified with --srcdir) for all directories whose names start with the tool name. It is a common practice to put a period after the tool part of the name. For instance, directories that start with `g++.' contain G++ tests. To add a new test, just put it in any directory (create an entirely new directory, if you wish) whose name follows this convention.

A test is any file in an appropriately named subdirectory whose name ends in `.exp' (the conventional way of naming expect scripts). These simple naming conventions make it as simple as possible to install new tests: all you must do is put the test in the right directory.

runtest sorts the tests in each subdirectory by name (using the Tcl lsort command) and runs them in the resulting order.

Initialization module

The initialization module (or "init file") has two purposes: to provide tool and target dependent procedures, and to start up an interactive tool to the point where it is ready to operate. The latter includes establishing communications with the target. All the tests for interactive programs assume that the tool is already running and communicating. Initialization modules for non-interactive programs may only need to supply the support functions.

Each test suite directory must contain (in its `config' subdirectory) a separate initialization module for each target. The appropriate init file is can be named several ways. The prefered name is the os part of the canonical configuration name with .exp as the suffix. An example would be that for an m68k-coff system, the target_os part would be coff. The next way is for system where there are short filenames, or a shortcut is desired to refer to the OS name for that target. This is uses the value of $target_abbrev rather than the target_os.

The final file looked for is simply `default.exp'. If there is only one operating system to support, then this file can be used. It's main purpose is to offer some support for new operating systems, or for unsupported cross targets. The last file looked for is `unknown.exp'. This is usually limited to error handling for unsupported targets. It's whole contents is typically.

perror "Sorry, there is no support for this target"
exit 1

At the beginning of the init file, you must first determine the proper executable name of the tool to execute, since the actual name of the tool to be tested my vary from system to system. Here's an example for the GNU C compiler.

global AR
# look for the archiver ar
if ![info exists AR] {
    set AR [findfile $base_dir/../../binutils/ar $base_dir/../../binutils/ar [tr
ansform ar]]
    verbose "AR defaulting to $AR" 2
}
}

global CFLAGS
if ![info exists CFLAGS] then {
    set CFLAGS ""
}

It is always a good idea to first check the variable, and only set it if it has not yet been defined. Often the proper value of AR is set on the command line that invokes `runtest'.

The findfile procedure takes as it's first argument a file name to look for. The second argument is returned if the file is found, and the third argument is returned if the file is not found. base_dir is set internally by DejaGnu to the top level directory of the object tree.

The transform procedure takes as its argument the native name of a tool (such as `gcc' for the compiler), and returns the name as configured for that tool in the current installation. (For example, a cross-compiling version of GNU CC that generates MIPS code may be installed with a name like mips-idt-ecoff-gcc.)

In a test running native, writing the Tcl code for initialization is usually quite simple. For cross configurations, however, more elaborate instructions are usually needed to describe how to talk to a remote target.

Each initialization module defines up to four procedures with standard names and purposes. The names of these procedures begin with `$tool', the string that identifies tests for a particular tool: $tool_start, $tool_load, $tool_exit, and $tool_version. For example, the start procedure for GDB is called gdb_start. (Since start procedures are used differently for batch and interactive tools, however, runtest itself never calls the start procedure. Init files for interactive tools are expected to end by running the start procedure.)

The initialization module is also a good place to call load_lib to get any collections of utility procedures meant for a family of test cases, and to set up default values for any additional Tcl variables needed for a specific set of tests.

See section Target dependent procedures, for full descriptions of these procedures.

DejaGnu procedures

DejaGnu provides these Tcl procedures for use in test scripts. You can also use any standard expect or Tcl function. These procedures are stored in libraries, which DejaGnu loads at runtime. Here's explanation of the library procedures that get loaded at runtime. All other librarys are optional, and need to be loaded by the testsuite.

Core Internal Procedures

See section A POSIX conforming test framework, for more detailed explanations of the test outcomes (`FAIL', `PASS', `UNTESTED', `UNRESOLVED', `UNSUPPORTED').

perror "string number"
Declares a severe error in the testing framework itself. perror writes in the log files a message beginning with `ERROR', appending the argument string. If the optional number is supplied, then this is used to set the internal count of errors to that value. As a side effect, perror also changes the effect of the next pass or fail command: the test outcome becomes `UNRESOLVED', since an automatic `PASS' or `FAIL' cannot be trusted after a severe error in the test framework. If the optional numeric value is `0', then there are no further side effects to calling this function, and the following test outcome doesn't become `UNRESOLVED'. This can be used for errors with no known side effects.
warning "string number"
Declares detection of a minor error in the test case itself. warning writes in the log files a message beginning with `WARNING', appending the argument string. Use warning rather than error for cases (such as communication failure to be followed by a retry) where the test case can recover from the error. If the optional number is supplied, then this is used to set the internal count of warnings to that value. As a side effect, warning_threshold or more calls to warning in a single test case also changes the effect of the next pass or fail command: the test outcome becomes `UNRESOLVED' since an automatic `PASS' or `FAIL' may not be trustworthy after many warnings. If the optional numeric value is `0', then there are no further side effects to calling this function, and the following test outcome doesn't become `UNRESOLVED'. This can be used for errors with no known side effects.
note "string"
Appends an informational message to the log file. note writes in the log files a message beginning with `NOTE', appending the argument string. Use note sparingly. verbose should be used for most such messages, but in cases where a message is needed in the log file regardless of the verbosity level use note.
pass "string"
Declares a test to have passed. pass writes in the log files a message beginning with `PASS' (or XPASS, if failure was expected), appending the argument string.
fail "string"
Declares a test to have failed. fail writes in the log files a message beginning with `FAIL' (or XFAIL, if failure was expected), appending the argument string.
unresolved "string"
Declares a test to have an unresolved outcome. unresolved writes in the log file a message beginning with `UNRESOLVED', appending the argument string. This usually means the test did not execute as expected, and a human being must go over results to determine if it passed or failed (and to improve the test case).
untested "string"
Declares a test was not run. untested writes in the log file a message beginning with `UNTESTED', appending the argument string. For example, you might use this in a dummy test whose only role is to record that a test does not yet exist for some feature.
unsupported "string"
Declares that a test case depends on some facility that does not exist in the testing environment. unsupported writes in the log file a message beginning with `UNSUPPORTED', appending the argument string.
get_warning_threshold
Returns the current value of warning_threshold. The default value is 3.
set_warning_threshold threshold
Sets the value of warning_threshold. A value of 0 disables it: calls to warning will not turn a `PASS' or `FAIL' into an `UNRESOLVED'.
transform "toolname"
Generates a string for the name of a tool as it was configured and installed, given its native name (as the argument toolname). This makes the assumption that all tools are installed using the same naming conventions: it extrapolates from the invocation name for `runtest'. For example, if you call runtest as `m68k-vxworks-runtest', the result of ` transform "gcc" ' is `m68k-vxworks-gcc'.
ishost "host"
Tests for a particular host environment. If the currently configured host matches the argument string, the result is 1; otherwise the result is 0. host must be a full three-part configure host name; in particular, you may not use the shorter nicknames supported by configure (but you can use wildcard characters, using shell syntax, to specify sets of names).
istarget "target"
Tests for a particular target environment. If the currently configured target matches the argument string, the result is 1; otherwise the result is 0. target must be a full three-part configure target name; in particular, you may not use the shorter nicknames supported by configure (but you can use wildcard characters, using shell syntax, to specify sets of names). If it is passed a NULL string, then it returns the name of the build canonical configuration.
isbuild "host"
Tests for a particular build host environment. If the currently configured host matches the argument string, the result is 1; otherwise the result is 0. host must be a full three-part configure host name; in particular, you may not use the shorter nicknames supported by configure (but you can use wildcard characters, using shell syntax, to specify sets of names). If it is passed a NULL string, then it returns the name of the build canonical configuration. item is3way "host" Tests for a canadian cross. This is when the tests will be run on a remotly hosted cross compiler. If it is a canadian cross, then the result is 1; otherwise the result is 0.
isnative
Tests whether the current configuration has the same host and target. When it runs in a native configuration this procedure returns a 1; otherwise it returns a 0.
load_lib "library-file"
Loads the file library-file by searching a fixed path built into runtest. If DejaGnu has been installed, it looks in a path starting with the installed library directory. If you are running DejaGnu directly from a source directory, without first running `make install', this path defaults to the current directory. In either case, it then looks in the current directory for a directory called lib. If there are duplicate definitions, the last one loaded takes precedence over the earlier ones.
setup_xfail "config [bugid]"
Declares that the test is expected to fail on a particular set of configurations. The config argument must be a list of full three-part configure target name; in particular, you may not use the shorter nicknames supported by configure (but you can use the common shell wildcard characters to specify sets of names). The bugid argument is optional, and used only in the logging file output; use it as a link to a bug-tracking system such as GNATS (see section `Overview' in Tracking Bugs With GNATS). Once you use setup_xfail, the fail and pass procedures produce the messages `XFAIL' and `XPASS' respectively, allowing you to distinguish expected failures (and unexpected success!) from other test outcomes. Warning: you must clear the expected failure after using setup_xfail in a test case. Any call to pass or fail clears the expected failure implicitly; if the test has some other outcome, e.g. an error, you can call clear_xfail to clear the expected failure explicitly. Otherwise, the expected-failure declaration applies to whatever test runs next, leading to surprising results.
clear_xfail config
Cancel an expected failure (previously declared with setup_xfail) for a particular set of configurations. The config argument is a list of configuration target names. It is only necessary to call clear_xfail if a test case ends without calling either pass or fail, after calling setup_xfail.
verbose [-log] [-n] [--] "string" number
Test cases can use this function to issue helpful messages depending on the number of `--verbose' options on the runtest command line. It prints string if the value of the variable verbose is higher than or equal to the optional number. The default value for number is 1. Use the optional `-log' argument to cause string to always be added to the log file, even if it won't be printed. Use the optional `-n' argument to print string without a trailing newline. Use the optional `--' argument if string begins with "-".

Remote Communication Procedures

`lib/remote.exp' defines these functions, for establishing and managing communications:

Procedures to establish a connection: Each of these procedures tries to establish the connection up to three times before returning. Warnings (if retries will continue) or errors (if the attempt is abandoned) report on communication failures. The result for any of these procedures is either -1, when the connection cannot be established, or the spawn ID returned by the expect command spawn.

It use the value of the connect field in the target_info array (was connectmode as the type of connection to make. Current supported connection types are tip, kermit, telnet, rsh, rlogin, and netdata. If the --reboot option was used on the runtest command line, then the target is rebooted before the connection is made.

remote_open type
Remote Connection Procedure. This is passed host or target. Host or target refers to whether it is a connection to a remote target, or a remote host. This opens the connection to the desired target or host using the default values in the configuration system. It returns that spawn_id of the process that manages the connection. This value can be used in expect or exp_send statements, or passed to other procedures that need the connection process's id. This also sets the fileid field in the target_info array.
remote_close shellid
shellid is value returned by a call to remote_open. This closes the connection to the target so resources can be used by others. This parameter can be left off if the fileid field in the target_info array is set.
telnet hostname port
rlogin hostname
rsh hostname
IP network procedures. hostname refers to the IP address or name (for example, an entry in `/etc/hosts') for this target. The procedure names reflect the Unix utility used to establish a connection. The optional port is used to specify the IP port number. The value of the netport field in the target_info array is used. (was $netport) This value has two parts, the hostname and the port number, seperated by a :. If host or target is used in the hostname field, than the config array is used for all information.
tip port
Serial line procedure. Connect using the Unix utility tip. port must be a name from the tip configuration file `/etc/remote'. Often, this is called `hardwire', or something like `ttya'. This file holds all the configuration data for the serial port. The value of the serial field in the target_info array is used. (was $serialport) If host or target is used in the port field, than the config array is used for all information.
kermit port bps
Serial line procedure. Connect using the program kermit. port is the device name, e.g. `/dev/ttyb'. bps is the line speed to use (in bits per second) for the connection. The value of the serial field in the target_info array is used. (was $serialport) If host or target is used in the port field, than the config array is used for all information.

Procedures to manage a connection:

tip_download spawnid file
Download `file' to the process spawnid (the value returned when the connection was established), using the ~put command under tip. Most often used for single board computers that require downloading programs in ASCII S-records. Returns 1 if an error occurs, 0 otherwise.
exit_remote_shell spawnid
Exits a remote process started by any of the connection procedures. spawnid is the result of the connection procedure that started the remote process.
download file [ spawnid ]
After you establish a connection to a target, you can download programs using this command. download reads in file (object code in S-record format) and writes it to the device controlling this spawnid. (From the point of view of the target, the S-record file comes in via standard input.) If you have more than one target active, you can use the optional argument spawnid to specify an alternative target (the default is the most recently established spawnid.)

Utility Procedures

`lib/utils.exp' defines these utility procedures:

getdirs dir
getdirs dir pattern
Returns a list of all the directories in the single directory dir that match pattern. If you do not specify pattern, getdirs assumes `*'. You may use the common shell wildcard characters in pattern. If no directories match the pattern, then a NULL string is returned.
find dir pattern
Search for files whose names match pattern (using shell wildcard characters for filename expansion). Search subdirectories recursively, starting at dir. The result is the list of files whose names match; if no files match, the result is empty. Filenames in the result include all intervening subdirectory names. If no files match the pattern, then a NULL string is returned.
which binary
Searches the execution path for an executable file binary, like the the BSD which utility. This procedure uses the shell environment variable `PATH'. It returns 0 if the binary is not in the path, or if there is no `PATH' environment variable. If binary is in the path, it returns the full path to binary.
grep filename regexp
grep filename regexp line
Search the file called filename (a fully specified path) for lines that contain a match for regular expression regexp. The result is a list of all the lines that match. If no lines match, the result is an empty string. Specify regexp using the standard regular expression style used by the Unix utility program grep. Use the optional third argument `line' to start lines in the result with the line number in filename. (This argument is simply an option flag; type it just as shown---`line'.)
diff filename filename
Compares the two files and returns a 1 if they match, or a 0 if they don't. If verbose is set, then it'll print the differences to the screen.
slay name
This look in the process tabel for name and send it a unix SIGINT, killing the process.
absolute path
This procedure takes the relative path, and converts it to an absolute path.
psource filename
This sources the file filename, and traps all errors. It also ignores all extraneous output. If there was an error it returns a 1, otherwise it returns a 0.
prune list pattern
Remove elements of the Tcl list list. Elements are fields delimited by spaces. The result is a copy of list, without any elements that match pattern. You can use the common shell wildcard characters to specify pattern.
setenv var val
Sets the variable var to the value val.
unsetenv var
Unsets the environment variable var
getenv var
returns the value of var in the environment if it exists, otherwise it returns NULL.
runtest_file_p runtests testcase
Search runtests for testcase and return 1 if found, 0 if not. runtests is a list of two elements. The first is the pathname of the testsuite expect script running. The second is a copy of what was on the right side of the = if `foo.exp="..."' was specified, or an empty string if no such argument is present. This is used by tools like compilers where each testcase is a file.
prune_system_crud system text
For system system, delete text the host or target operating system might issue that will interfere with pattern matching of program output in text. An example is the message that is printed if a shared library is out of date.

Cross target procedure

`lib/target.exp' defines these utility procedures:

push_target name
This makes the target named name be the current target connection. The value of name is an index into the target_info array and is set in the global config file.
pop_target
This unsets the current target connection.
list_targets
This lists all the supported targets for this architecture.
push_host name
This makes the host named name be the current remote host connection. The value of name is an index into the target_info array and is set in the global config file.
pop_host
This unsets the current host connection. This invokes the compiler as set by CC to compile the file file. The default options for many cross compilation targets are guessed by DejaGnu, and these options can be added to by passing in more parameters as arguments to compile. Optionally, this will also use the value of the cflags field in the target config array. If the host is not the same as the build machines, then then compiler is run on the remote host using execute_anywhere. This produces an archive file. Any parameters passed to archive are used in addition to the default flags. Optionally, this will also use the value of the arflags field in the target config array. If the host is not the same as the build machines, then then archiver is run on the remote host using execute_anywhere. This generates an index for the archive file for systems that aren't POSIX yet. Any parameters passed to ranlib are used in for the flags.
execute_anywhere cmdline
This executes the cmdline on the proper host. This should be used as a replacement for the Tcl command exec as this version utilizes the target config info to execute this command on the build machine or a remote host. All config information for the remote host must be setup to have this command work. If this is a canadian cross, (where we test a cross compiler that runs on a different host then where DejaGnu is running) then a connection is made to the remote host and the command is executed there. It returns either REMOTERROR (for an error) or the output produced when the command was executed. This is used for running the tool to be tested, not a test case.

Debugging Procedures

`lib/debugger.exp' defines these utility procedures:

dumpvars expr
This takes a csh style regular expression (glob rules) and prints the values of the global variable names that match. It is abbreviated as dv
dumplocals expr
This takes a csh style regular expression (glob rules) and prints the values of the local variable names that match. It is abbreviated as dl.
dumprocs expr
This takes a csh style regular expression (glob rules) and prints the body of all procs that match. It is abbreviated as dp
dumpwatch expr
This takes a csh style regular expression (glob rules) and prints all the watchpoints. It is abbreviated as dw.
watchunset var
This breaks program execution when the variable var is unset. It is abbreviated as wu.
watchwrite var
This breaks program execution when the variable var is written. It is abbreviated as ww.
watchread var
This breaks program execution when the variable var is read. It is abbreviated as wr.
watchdel watch
This deletes a the watchpoint for watch. It is abbreviated as wd.
print var
This prints the value of the variable var. It is abbreviated as p.
quit
This makes runtest exit. It is abbreviated as q.
bt
This prints a backtrace of the executed Tcl commands.

Target dependent procedures

Each combination of target and tool requires some target-dependent procedures. The names of these procedures have a common form: the tool name, followed by an underbar `_', and finally a suffix describing the procedure's purpose. For example, a procedure to extract the version from GDB is called `gdb_version'. See section Initialization module, for a discussion of how DejaGnu arranges to find the right procedures for each target.

runtest itself calls only two of these procedures, tool_exit and tool_version; these procedures use no arguments.

The other two procedures, tool_start and tool_load, are only called by the test suites themselves (or by testsuite-specific initialization code); they may take arguments or not, depending on the conventions used within each test suite.

tool_start
Starts a particular tool. For an interactive tool, tool_start starts and initializes the tool, leaving the tool up and running for the test cases; an example is gdb_start, the start function for GDB. For a batch oriented tool, tool_start is optional; the recommended convention is to let tool_start run the tool, leaving the output in a variable called comp_output. Test scripts can then analyze `$comp_output' to determine the test results. An example of this second kind of start function is gcc_start, the start function for GCC. runtest itself does not call tool_start. The initialization module `tool_init.exp' must call tool_start for interactive tools; for batch-oriented tools, each individual test script calls tool_start (or makes other arrangements to run the tool).
tool_load
Loads something into a tool. For an interactive tool, this conditions the tool for a particular test case; for example, gdb_load loads a new executable file into the debugger. For batch oriented tools, tool_load may do nothing--though, for example, the GCC support uses gcc_load to load and run a binary on the target environment. Conventionally, tool_load leaves the output of any program it runs in a variable called `exec_output'. Writing tool_load can be the most complex part of extending DejaGnu to a new tool or a new target, if it requires much communication coding or file downloading. Test scripts call tool_load.
tool_exit
Cleans up (if necessary) before runtest exits. For interactive tools, this usually ends the interactive session. You can also use tool_exit to remove any temporary files left over from the tests. runtest calls tool_exit.
tool_version
Prints the version label and number for tool. This is called by the DejaGnu procedure that prints the final summary report. The output should consist of the full path name used for the tested tool, and its version number. runtest calls tool_version.

The usual convention for return codes from any of these procedures (although it is not required by runtest) is to return 0 if the procedure succeeded, 1 if it failed, and -1 if there was a communication error.

Remote targets supported

The DejaGnu distribution includes support for the following remote targets. You can set the target name and the connect mode in the `site.exp' file (using the Tcl variables `targetname' and `connectmode', respectively), or on the runtest command line (using `--name' and `--connect').

AMD 29000, with UDI protocol
Configure DejaGnu for target `a29k-amd-udi'. (Cygnus configure also recognizes the abbreviation `udi29k'.) Then, to run tests, use the runtest target name to specify whether you want to use a simulator, or a particular hardware board. The particular string to use with `--name' will depend on your UDI setup file, `udi_soc' (if `udi_soc' is not in your working directory, the environment variable `UDICONF' should contain a path to this file). For example, if your UDI setup file includes these lines:
iss   AF_UNIX  *   isstip -r /home/gnu/29k/src/osboot/sim/osboot
mon   AF_UNIX  *   montip -t serial -baud 9600 -com /dev/ttyb
You can use `--name iss' to run tests on the simulator, and `--name mon' to run tests on the 29K hardware. See the manufacturer's manuals for more information on UDI and `udi_soc'. The default connect protocol is `mondfe' with either back end. mondfe is the only shell DejaGnu supports for UDI targets. mondfe is an AMD specific monitor program freely available from AMD. Warning: This target requires GDB version 4.7.2 (or greater). Earlier versions of GDB do not fully support the load command on this target, so DejaGnu has no way to load executable files from the debugger.
Motorola 680x0 boards, a.out or COFF object format
Configure DejaGnu for any remote target matching `m68k-*'. Warning: Most `m68k-*' configurations run all tests only for native testing (when the target is the same as the host). When you specify most of these targets for a cross configuration, you will only be able to use tests that run completely within the host (for example, tests of the binary utilities such as the archiver; or compiler tests that only generate code rather than running it). To run a.out or COFF binaries on a remote M68K, you must configure DejaGnu for a particular target board. `m68k-abug' is an example. (In general for an embedded environment, because it does not have absolute addresses, a.out is not a good choice for output format in any case; most often S-records or Hex-32 are used instead.)
Motorola 68K MVME 135 board running ABug boot monitor
Configure for `m68k-abug-aout' or `m68k-abug-coff' (as a target). This boot monitor can only download S-records; therefore, the DejaGnu tests for this environment require a linker command script to convert either output format to S-records, setting the default addresses for .text, .bss, and .data. With this configuration, the default for `--connect' is `tip'. `tip' is the only communications protocol supported for connecting to `m68k-abug-*' targets. `tip' uses an ASCII downloader (the ~put command) to load S-records into the target board. The `--name' string must be a machine name that tip understands (for example, on some tip implementations it must be an entry from the initialization file for tip; this file is sometimes called `/etc/remote'). See your system documentation for information on how to create new entries in `/etc/remote'. (Some UNIX systems are distributed with at least one default entry with a name resembling `hardwire'; if your system has one, you can edit it, or make a modified copy with a new name.) When you have a working `/etc/remote' entry abugtarget, you should be able to type `tip abugtarget', and get the prompt `135ABUG>' from the board. Use the same abugtarget string with `runtest --name'.
Motorola IDP board running the rom68k boot monitor
This is the same in functionality as the MVME board running the BUG boot monitor. Only the monitor commands and the addresses are different.
VxWorks (Motorola 68K or Intel 960)
Configure DejaGnu for either `m68k-wrs-vxworks' (abbreviated `vxworks68') or `i960-wrs-vxworks' (abbreviated `vxworks960'). Since both targets support IP addressing, specify the network address (for example, a host name from `/etc/hosts') with `--name'. The default connect protocol is `rlogin', but you can use any of `--connect rlogin', `--connect telnet', or `--connect rsh'. Test scripts need no special code to load programs into these targets; since VxWorks supports NFS, all you must do is ensure test programs are on an exported filesystem. When you compile for VxWorks, use the linker `-r' option to make the linker output relocatable--at least if you want to use library routines. Many standard C routines are included in VxWorks; often no additional libraries are needed. See your VxWorks system documentation for additional details.

The files DejaGnu reads

The runtest program used to invoke DejaGnu is a short shell script generated by make during the configuration process. Its main task is to read the main test framework driver, `runtest.exp'.

`runtest.exp', in turn, reads expect code from certain other files, in this order:

  1. Each of the `site.exp' local definition files available. See section Setting runtest defaults, for details.
  2. `lib/utils.exp', a collection of utility procedures. See section DejaGnu procedures, for descriptions of these procedures.
  3. `lib/framework.exp', a file of subroutines meant for runtest itself rather than for general-purpose use in both runtest and test suites.
  4. `debugger.exp', Don Libes' Tcl Debugger. (See A Debugger for Tcl Applications by Don Libes. This paper is distributed with expect in PostScript form as the file `expect/tcl-debug.ps'.)
  5. `lib/remote.exp', a collection of subroutines meant for connecting to remote machines.
  6. `lib/target.exp', a collection of subroutines used for the configuration systems in DejaGnu. These procedures typically manipulate or utilize the configuration system.
  7. An initialization file tool_init.exp. See section Initialization module, for more discussion of init files.

The files DejaGnu writes

runtest always writes two kinds of output files: summary logs and detailed logs. The contents of both of these are determined by your tests.

For troubleshooting, a third kind of output file is useful: use `--debug' to request an output file showing details of what expect is doing internally.

Summary log

runtest always produces a summary output file `tool.sum'. This summary shows the names of all test files run; for each test file, one line of output from each pass command (showing status `PASS' or `XPASS') or fail command (status `FAIL' or `XFAIL'); trailing summary statistics that count passing and failing tests (expected and unexpected); and the full pathname and version number of the tool tested. (All possible outcomes, and all errors, are always reflected in the summary output file, regardless of whether or not you specify `--all'.)

If any of your tests use the procedures unresolved, unsupported, or untested, the summary output also tabulates the corresponding outcomes.

For example, after `runtest --tool binutils', look for a summary log in `binutils.sum'. Normally, runtest writes this file in your current working directory; use the `--outdir' option to select a different directory.

Here is a short sample summary log:

Test Run By rob on Mon May 25 21:40:57 PDT 1992
                === gdb tests ===
Running ./gdb.t00/echo.exp ...
PASS:   Echo test
Running ./gdb.all/help.exp ...
PASS:   help add-symbol-file
PASS:   help aliases
PASS:   help breakpoint "bre" abbreviation
FAIL:   help run "r" abbreviation
Running ./gdb.t10/crossload.exp ...
PASS:   m68k-elf (elf-big) explicit format; loaded
XFAIL:  mips-ecoff (ecoff-bigmips) "ptype v_signed_char" signed
C types
                === gdb Summary ===
# of expected passes 5
# of expected failures 1
# of unexpected failures 1
/usr/latest/bin/gdb version 4.6.5 -q

Detailed log

runtest also saves a detailed log file `tool.log', showing any output generated by tests as well as the summary output. For example, after `runtest --tool binutils', look for a detailed log in `binutils.log'. Normally, runtest writes this file in your current working directory; use the `--outdir' option to select a different directory.

Here is a brief example showing a detailed log for G++ tests:

Test Run By rob on Mon May 25 21:40:43 PDT 1992

                === g++ tests ===

--- Running ./g++.other/t01-1.exp ---
        PASS:   operate delete

--- Running ./g++.other/t01-2.exp ---
        FAIL:   i960 bug EOF
p0000646.C: In function `int  warn_return_1 ()':
p0000646.C:109: warning: control reaches end of non-void function
p0000646.C: In function `int  warn_return_arg (int)':
p0000646.C:117: warning: control reaches end of non-void function
p0000646.C: In function `int  warn_return_sum (int, int)':
p0000646.C:125: warning: control reaches end of non-void function
p0000646.C: In function `struct foo warn_return_foo ()':
p0000646.C:132: warning: control reaches end of non-void function

--- Running ./g++.other/t01-4.exp ---
        FAIL:   abort
900403_04.C:8: zero width for bit-field `foo'
--- Running ./g++.other/t01-3.exp ---
        FAIL:   segment violation
900519_12.C:9: parse error before `;'
900519_12.C:12: Segmentation violation
/usr/latest/bin/gcc: Internal compiler error: program cc1plus got
fatal signal

                === g++ Summary ===

# of expected passes 1
# of expected failures 3
/usr/ps/bin/g++ version cygnus-2.0.1

Logging expect internal actions

With the `--debug' option, you can request a log file showing the output from expect itself, running in debugging mode. This file (`dbg.log', in the directory where you start runtest) shows each pattern expect considers in analyzing test output.

This file reflects each send command, showing the string sent as input to the tool under test; and each expect command, showing each pattern it compares with the tool output.

The log messages for expect begin with a message of the form

expect: does {tool output} (spawn_id n) match pattern
{expected pattern}?

For every unsuccessful match, expect issues a `no' after this message; if other patterns are specified for the same expect command, they are reflected also, but without the first part of the message (`expect...match pattern').

When expect finds a match, the log for the successful match ends with `yes', followed by a record of the expect variables set to describe a successful match. Here is an excerpt from the debugging log for a GDB test:

send: sent {break gdbme.c:34\n} to spawn id 6
expect: does {} (spawn_id 6) match pattern {Breakpoint.*at.* file
 gdbme.c, line 34.*\(gdb\) $}? no
{.*\(gdb\) $}? no
expect: does {} (spawn_id 0) match pattern {<return>}? no
{\(y or n\) }? no
{buffer_full}? no
{virtual}? no
{memory}? no
{exhausted}? no
{Undefined}? no
{command}? no
break gdbme.c:34
Breakpoint 8 at 0x23d8: file gdbme.c, line 34.
(gdb) expect: does {break gdbme.c:34\r\nBreakpoint 8 at 0x23d8:
file gdbme.c, line 34.\r\n(gdb) } (spawn_id 6) match pattern
{Breakpoint.*at.* file gdbme.c, line 34.*\(gdb\) $}? yes
expect: set expect_out(0,start) {18}
expect: set expect_out(0,end) {71}
expect: set expect_out(0,string) {Breakpoint 8 at 0x23d8: file
gdbme.c, line 34.\r\n(gdb) }
expect: set expect_out(spawn_id) {6}
expect: set expect_out(buffer) {break gdbme.c:34\r\nBreakpoint 8
at 0x23d8: file gdbme.c, line 34.\r\n(gdb) }
        PASS:   70      0       breakpoint line number in file

This example exhibits three properties of expect and DejaGnu that might be surprising at first glance:

  • Empty output for the first attempted match. The first set of attempted matches shown ran against the output `{}'---that is, no output. expect begins attempting to match the patterns supplied immediately; often, the first pass is against incomplete output (or completely before all output, as in this case).
  • Interspersed tool output. The beginning of the log entry for the second attempted match may be hard to spot: this is because the prompt `(gdb) ' appears on the same line, just before the `expect:' that marks the beginning of the log entry.
  • Fail-safe patterns. Many of the patterns tested are fail-safe patterns provided by GDB testing utilities, to reduce possible indeterminacy. It is useful to anticipate potential variations caused by extreme system conditions (GDB might issue the message `virtual memory exhausted' in rare circumstances), or by changes in the tested program (`Undefined command' is the likeliest outcome if the name of a tested command changes). The pattern `{<return>}' is a particularly interesting fail-safe to notice; it checks for an unexpected RET prompt. This may happen, for example, if the tested tool can filter output through a pager. These fail-safe patterns (like the debugging log itself) are primarily useful while developing test scripts. Use the error procedure to make the actions for fail-safe patterns produce messages starting with `ERROR' on the runtest standard output, and in the detailed log file.

How To Write a Test Case

Writing a test case

The easiest way to prepare a new test case is to base it on an existing one for a similar situation. There are two major categories of tests: batch or interactive. Batch oriented tests are usually easier to write.

The GCC tests are a good example of batch oriented tests. All GCC tests consist primarily of a call to a single common procedure, since all the tests either have no output, or only have a few warning messages when successfully compiled. Any non-warning output is a test failure. All the C code needed is kept in the test directory. The test driver, written in expect, need only get a listing of all the C files in the directory, and compile them all using a generic procedure. This procedure and a few others supporting for these tests are kept in the library module `lib/c-torture.exp' in the GCC test suite. Most tests of this kind use very few expect features, and are coded almost purely in Tcl.

Writing the complete suite of C tests, then, consisted of these steps:

  1. Copying all the C code into the test directory. These tests were based on the C-torture test created by Torbjorn Granlund (on behalf of the Free Software Foundation) for GCC development.
  2. Writing (and debugging) the generic expect procedures for compilation.
  3. Writing the simple test driver: its main task is to search the directory (using the Tcl procedure glob for filename expansion with wildcards) and call a Tcl procedure with each filename. It also checks for a few errors from the testing procedure.

Testing interactive programs is intrinsically more complex. Tests for most interactive programs require some trial and error before they are complete.

However, some interactive programs can be tested in a simple fashion reminiscent of batch tests. For example, prior to the creation of DejaGnu, the GDB distribution already included a wide-ranging testing procedure. This procedure was very robust, and had already undergone much more debugging and error checking than many recent DejaGnu test cases. Accordingly, the best approach was simply to encapsulate the existing GDB tests, for reporting purposes. Thereafter, new GDB tests built up a family of expect procedures specialized for GDB testing.

`gdb.t10/crossload.exp' is a good example of an interactive test.

Debugging a test case

These are the kinds of debugging information available from DejaGnu:

  1. Output controlled by test scripts themselves, explicitly allowed for by the test author. This kind of debugging output appears in the detailed output recorded in the `tool.log' file. To do the same for new tests, use the verbose procedure (which in turn uses the variable also called verbose) to control how much output to generate. This will make it easier for other people running the test to debug it if necessary. Whenever possible, if `$verbose' is 0, there should be no output other than the output from pass, fail, error, and warning. Then, to whatever extent is appropriate for the particular test, allow successively higher values of `$verbose' to generate more information. Be kind to other programmers who use your tests: provide for a lot of debugging information.
  2. Output from the internal debugging functions of Tcl and expect. There is a command line options for each; both forms of debugging output are recorded in the file dbg.log in the current directory. Use `--debug' for information from the expect level; it generates displays of the expect attempts to match the tool output with the patterns specified (see section Logging expect internal actions). This output can be very helpful while developing test scripts, since it shows precisely the characters received. Iterating between the latest attempt at a new test script and the corresponding `dbg.log' can allow you to create the final patterns by "cut and paste". This is sometimes the best way to write a test case. Use `--strace' to see more detail at the Tcl level; this shows how Tcl procedure definitions expand, as they execute. The associated number controls the depth of definitions expanded; see the discussion of `--strace' in section Using runtest.
  3. Finally, if the value of `verbose' is 3 or greater, runtest turns on the expect command log_user. This command prints all expect actions to the expect standard output, to the detailed log file, and (if `--debug' is on) to `dbg.log'.

Adding a test case to a test suite

There are two slightly different ways to add a test case. One is to add the test case to an existing directory. The other is to create a new directory to hold your test. The existing test directories represent several styles of testing, all of which are slightly different; examine the directories for the tool of interest to see which (if any) is most suitable.

Adding a GCC test can be very simple: just add the C code to any directory beginning with `gcc.' and it runs on the next `runtest --tool gcc'.

To add a test to GDB, first add any source code you will need to the test directory. Then you can either create a new expect file, or add your test to an existing one (any file with a `.exp' suffix). Creating a new `.exp' file is probably a better idea if the test is significantly different from existing tests. Adding it as a separate file also makes upgrading easier. If the C code has to be already compiled before the test will run, then you'll have to add it to the `Makefile.in' file for that test directory, then run configure and make.

Adding a test by creating a new directory is very similar:

  1. Create the new directory. All subdirectory names begin with the name of the tool to test; e.g. G++ tests might be in a directory called `g++.other'. There can be multiple test directories that start with the same tool name (such as `g++').
  2. Add the new directory name to the `configdirs' definition in the `configure.in' file for the test suite directory. This way when make and configure next run, they include the new directory.
  3. Add the new test case to the directory, as above.
  4. To add support in the new directory for configure and make, you must also create a Makefile.in and a configure.in. See section `What Configure Does' in Cygnus Configure.

Hints on writing a test case

There may be useful existing procedures already written for your test in the `lib' directory of the DejaGnu distribution. See section DejaGnu procedures.

It is safest to write patterns that match all the output generated by the tested program; this is called closure. If a pattern does not match the entire output, any output that remains will be examined by the next expect command. In this situation, the precise boundary that determines which expect command sees what is very sensitive to timing between the expect task and the task running the tested tool. As a result, the test may sometimes appear to work, but is likely to have unpredictable results. (This problem is particularly likely for interactive tools, but can also affect batch tools--especially for tests that take a long time to finish.) The best way to ensure closure is to use the `-re' option for the expect command to write the pattern as a full regular expressions; then you can match the end of output using a `$'. It is also a good idea to write patterns that match all available output by using `.*\' after the text of interest; this will also match any intervening blank lines. Sometimes an alternative is to match end of line using `\r' or `\n', but this is usually too dependent on terminal settings.

Always escape punctuation, such as `(' or `"', in your patterns; for example, write `\('. If you forget to escape punctuation, you will usually see an error message like `extra characters after close-quote'.

If you have trouble understanding why a pattern does not match the program output, try using the `--debug' option to runtest, and examine the debug log carefully. See section Logging expect internal actions.

Be careful not to neglect output generated by setup rather than by the interesting parts of a test case. For example, while testing GDB, I issue a send `set height 0\n' command. The purpose is simply to make sure GDB never calls a paging program. The `set height' command in GDB does not generate any output; but running any command makes GDB issue a new `(gdb) ' prompt. If there were no expect command to match this prompt, the output `(gdb) ' begins the text seen by the next expect command--which might make that pattern fail to match.

To preserve basic sanity, I also recommended that no test ever pass if there was any kind of problem in the test case. To take an extreme case, tests that pass even when the tool will not spawn are misleading. Ideally, a test in this sort of situation should not fail either. Instead, print an error message by calling one of the DejaGnu procedures error or warning.

Special variables used by test cases

Your test cases can use these variables, with conventional meanings (as well as the variables saved in `site.exp' see section Setting runtest defaults):

These variables are available to all test cases.

prms_id
The tracking system (e.g. GNATS) number identifying a corresponding bugreport. (`0' if you do not specify it in the test script.)
bug_id
An optional bug id; may reflect a bug identification from another organization. (`0' if you do not specify it.)
subdir
The subdirectory for the current test case.

These variables should never be changed. They appear in most tests.

expect_out(buffer)
The output from the last command. This is an internal variable set by expect.
exec_output
This is the output from a tool_load command. This only applies to tools like GCC and GAS which produce an object file that must in turn be executed to complete a test.
comp_output
This is the output from a tool_start command. This is conventionally used for batch oriented programs, like GCC and GAS, that may produce interesting output (warnings, errors) without further interaction.

New Tools, Targets, or Hosts

The most common ways to extend the DejaGnu framework are: adding a suite of tests for a new tool to be tested; adding support for testing on a new target; and porting runtest to a new host.

Writing tests for a new tool

In general, the best way to learn how to write (code or even prose) is to read something similar. This principle applies to test cases and to test suites. Unfortunately, well-established test suites have a way of developing their own conventions: as test writers become more experienced with DejaGnu and with Tcl, they accumulate more utilities, and take advantage of more and more features of expect and Tcl in general.

Inspecting such established test suites may make the prospect of creating an entirely new test suite appear overwhelming. Nevertheless, it is quite straightforward to get a new test suite going.

There is one test suite that is guaranteed not to grow more elaborate over time: both it and the tool it tests were created expressly to illustrate what it takes to get started with DejaGnu. The `example/' directory of the DejaGnu distribution contains both an interactive tool called calc, and a test suite for it. Reading this test suite, and experimenting with it, is a good way to supplement the information in this section. (Thanks to Robert Lupton for creating calc and its test suite--and also the first version of this section of the manual!)

To help orient you further in this task, here is an outline of the steps to begin building a test suite for a program example.

  1. Create or select a directory to contain your new collection of tests. Change to that directory (shown here as testsuite):
    eg$ cd testsuite/
  2. Create a `configure.in' file in this directory, to control configuration-dependent choices for your tests. So far as DejaGnu is concerned, the important thing is to set a value for the variable target_abbrev; this value is the link to the init file you will write soon. (For simplicity, we assume the environment is Unix, and use `unix' as the value.) What else is needed in `configure.in' depends on the requirements of your tool, your intended test environments, and which configure system you use. This example is a minimal configure.in for use with Cygnus Configure. (For an alternative based on the FSF autoconf system, see the calc example distributed with DejaGnu.) Replace example with the name of your program:
    # This file is a shell script fragment
# for use with Cygnus configure.

srctrigger="example.0"
srcname="The DejaGnu example tests"

# per-host:

# per-target:

# everything defaults to unix for a target
target_abbrev=unix

# post-target:
  3. Create `Makefile.in', the source file used by configure to build your `Makefile'. Its leading section should as usual contain the values that configure may override:
    srcdir = .
prefix = /usr/local

exec_prefix = $(prefix)
bindir = $(exec_prefix)/bin
libdir = $(exec_prefix)/lib
tooldir = $(libdir)/$(target_alias)

datadir = $(exec_prefix)/lib/dejagnu

RUNTEST = runtest
RUNTESTFLAGS =
FLAGS_TO_PASS =

#### host, target, site specific Makefile frags come in here.
    This should be followed by the standard targets at your site. To begin with, they need not do anything--for example, these definitions will do:

all:

info:

install-info:

install:
uninstall:

clean:
        -rm -f *~ core *.info*
    It is also a good idea to make sure your `Makefile' can rebuild itself if `Makefile.in' changes, with a target like this (which works for either Cygnus or FSF Configure):
    Makefile : $(srcdir)/Makefile.in $(host_makefile_frag) \
             $(target_makefile_frag)
        $(SHELL) ./config.status
    You also need to include two targets important to DejaGnu: check, to run the tests, and site.exp, to set up the Tcl copies of configuration-dependent values. The check target must run `runtest --tool example':
    check: site.exp all
        $(RUNTEST) $(RUNTESTFLAGS) $(FLAGS_TO_PASS) \
            --tool example --srcdir $(srcdir)
    The site.exp target should usually set up (among other things!) a Tcl variable for the name of your program:
    site.exp: ./config.status Makefile
        @echo "Making a new config file..."
        -@rm -f ./tmp?
        @touch site.exp

        -@mv site.exp site.bak
        @echo "## these variables are automatically\
 generated by make ##" > ./tmp0
        @echo "# Do not edit here. If you wish to\
 override these values" >> ./tmp0
        @echo "# add them to the last section" >> ./tmp0
        @echo "set host_os ${host_os}" >> ./tmp0
        @echo "set host_alias ${host_alias}" >> ./tmp0
        @echo "set host_cpu ${host_cpu}" >> ./tmp0
        @echo "set host_vendor ${host_vendor}" >> ./tmp0
        @echo "set target_os ${target_os}" >> ./tmp0
        @echo "set target_alias ${target_alias}" >> ./tmp0
        @echo "set target_cpu ${target_cpu}" >> ./tmp0
        @echo "set target_vendor ${target_vendor}" >> ./tmp0
        @echo "set host_triplet ${host_canonical}" >> ./tmp0
        @echo "set target_triplet ${target_canonical}">>./tmp0
        @echo "set tool binutils" >> ./tmp0
        @echo "set srcdir ${srcdir}" >> ./tmp0
        @echo "set objdir `pwd`" >> ./tmp0
        @echo "set examplename example" >> ./tmp0
        @echo "## All variables above are generated by\
 configure. Do Not Edit ##" >> ./tmp0
                @cat ./tmp0 > site.exp
        @sed < site.bak \
               -e '1,/^## All variables above are.*##/ d' \
               >> site.exp
        -@rm -f ./tmp?
  4. Create a directory (in `testsuite/') called `config/':
    eg$ mkdir config
  5. Make an init file in this directory; its name must start with the target_abbrev value, so call it `config/unix.exp'. This is the file that contains the target-dependent procedures; fortunately, most of them do not have to do very much in order for runtest to run. If example is not interactive, you can get away with this minimal `unix.exp' to begin with:
    proc foo_exit {} {}
proc foo_version {} {}
    If example is interactive, however, you might as well define a start routine and invoke it by using an init file like this:
    proc foo_exit {} {}
proc foo_version {} {}

proc foo_start {} {
  global examplename
  spawn $examplename
  expect {
    -re "" {}
  }
}
foo_start
  6. Create a directory whose name begins with your tool's name, to contain tests:
    eg$ mkdir example.0
  7. Create a sample test file in `example.0'. Its name must end with `.exp'; you can use `first-try.exp' To begin with, just write there a line of Tcl code to issue a message:
    send_user "Testing: one, two...\n"
  8. Back in the `testsuite/' (top level) directory, run
    eg$ configure
    (You may have to specify more of a path, if a suitable configure is not available in your execution path.)
  9. You are now ready to triumphantly type `make check' or `runtest --tool example'. You should see something like this:
    Test Run By rhl on Fri Jan 29 16:25:44 EST 1993

                === example tests ===

Running ./example.0/first-try.exp ...
Testing: one, two...

                === example Summary ===
    There is no output in the summary, because so far the example does not call any of the procedures that establish a test outcome.
  10. Begin writing some real tests. For an interactive tool, you should probably write a real exit routine in fairly short order; in any case, you should also write a real version routine soon.

Adding a target

DejaGnu has some additional requirements for target support, beyond the general-purpose provisions of Cygnus configure. runtest must actively communicate with the target, rather than simply generating or managing code for the target architecture. Therefore, each tool requires an initialization module for each target. For new targets, you must supply a few Tcl procedures to adapt DejaGnu to the target. This permits DejaGnu itself to remain target independent. See section Initialization module, for a discussion of the naming conventions that enable DejaGnu to locate and use init files.

Usually the best way to write a new initialization module is to edit an existing initialization module; some trial and error will be required. If necessary, you can use the `--debug' option to see what is really going on.

When you code an initialization module, be generous in printing information controlled by the verbose procedure (see section DejaGnu procedures).

Most of the work is in getting the communications right. Communications code (for several situations involving IP networks or serial lines) is available in a DejaGnu library file, `lib/remote.exp'. See section DejaGnu procedures.

If you suspect a communication problem, try running the connection interactively from expect. (There are three ways of running expect as an interactive interpreter. You can run expect with no arguments, and control it completely interactively; or you can use `expect -i' together with other command-line options and arguments; or you can run the command interpreter from any expect procedure. Use return to get back to the calling procedure (if any), or return -tcl to make the calling procedure itself return to its caller; use exit or end-of-file to leave expect altogether.) Run the program whose name is recorded in `$connectmode', with the arguments in `$targetname', to establish a connection. You should at least be able to get a prompt from any target that is physically connected.

Porting to a new host

The task of porting DejaGnu is basically that of porting Tcl and expect. Tcl and expect, as distributed with DejaGnu, both use autoconf; they should port automatically to most Unix systems.

Once Tcl and expect are ported, DejaGnu should run. Most system dependencies are taken care of by using expect as the main command shell.

Installing DejaGnu

Once you have the DejaGnu source unpacked and available, you must first configure the software to specify where it is to run (and the associated defaults); then you can proceed to installing it.

Configuring the DejaGnu test driver

It is usually best to configure in a directory separate from the source tree, specifying where to find the source with the optional `--srcdir' option to configure. DejaGnu uses the GNU autoconf to configure itself. For more info on using autoconf, read the GNU autoconf manual. To configure, execute the `configure' program, no other options are required. For an example, to configure in a seperate tree for objects, execute the configure script from the source tree like this:

../dejagnu-1.3/configure

DejaGnu doesn't care at config time if it's for testing a native system or a cross system. That is determined at runtime by using the config files.

You may also want to use the configure option `--prefix' to specify where you want DejaGnu and its supporting code installed. By default, installation is in subdirectories of `/usr/local', but you can select any alternate directory altdir by including `--prefix=altdir' on the configure command line. (This value is captured in the Makefile variables prefix and exec_prefix.)

Save for a small number of example tests, the DejaGnu distribution itself does not include any test suites; these are available separately. Test suites for the GNU compiler (testing both GCC and G++) and for the GNU binary utilities are distributed in parallel with the DejaGnu distribution (but packaged as separate files). The test suite for the GNU debugger is distributed in parallel with each release of GDB itself, starting with GDB 4.9. After configuring the top-level DejaGnu directory, unpack and configure the test directories for the tools you want to test; then, in each test directory, run make to build auxiliary programs required by some of the tests.

Installing DejaGnu

To install DejaGnu in your filesystem (either in `/usr/local', or as specified by your `--prefix' option to configure), execute

eg$ make install

`make install' does these things for DejaGnu:

  1. Look in the path specified for executables (`$exec_prefix') for directories called `lib' and `bin'. If these directories do not exist, `make install' creates them.
  2. Create another directory in the `lib' directory, called `dejagnu'.
  3. Copy the runtest shell script into `$exec_prefix/bin'.
  4. Copy all the library files (used to support the framework) into `$exec_prefix/lib/dejagnu'.
  5. Copy `runtest.exp' into `$exec_prefix/lib/dejagnu'. This is the main Tcl code implementing DejaGnu.

Each test suite collection comes with simple installation instructions in a `README' file; in general, the test suites are designed to be unpacked in the source directory for the corresponding tool, and extract into a directory called `testsuite'.

Index

Jump to: - - . - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - q - r - s - t - u - v - w - x

-

  • --all (runtest option)
  • --baud (runtest option)
  • --build (runtest option)
  • --connect (runtest option)
  • --debug (runtest option)
  • --help (runtest option)
  • --host (runtest option)
  • --name (runtest option)
  • --objdir (runtest option)
  • --outdir (runtest option)
  • --reboot (runtest option)
  • --srcdir (runtest option)
  • --strace (runtest option)
  • --target (runtest option)
  • --tool and naming conventions
  • --tool (runtest option)
  • --verbose (runtest option)
  • --version (runtest option)
  • -b (runtest option)
  • -V (runtest option)
  • -v (runtest option)

    • .

  • .exp

    • a

  • absolute path
  • adding a target
  • adding a test case
  • all_flag
  • ambiguity, required for POSIX
  • archive object files
  • auxiliary files, building
  • auxiliary programs
  • auxiliary test programs

    • b

  • baud
  • baud rate, specifying
  • bps, specifying
  • bt
  • bug number
  • bug number, extra
  • bug_id
  • build config name, changing
  • build host configuration test
  • build_triplet
  • built in procedures, DejaGnu

    • c

  • C torture test
  • canadian cross configuration test
  • cancelling expected failure
  • check makefile target
  • clear_xfail config
  • Closing a remote connection
  • command line option variables
  • command line options
  • command line Tcl variable definition
  • communications procedures
  • comp_output
  • comparing files
  • compile a file
  • configuration dependent defaults
  • configuring DejaGnu
  • connecting to target
  • connectmode
  • converting relative paths to absolute
  • Core Internal Procedures
  • cross configuration
  • current test subdirectory

    • d

  • dbg.log file
  • debug log
  • debug log for test cases
  • debugger.exp
  • debugging a test case
  • default options, controlling
  • defaults, option
  • defaults, setting in init file
  • DejaGnu configuration
  • DejaGnu test driver
  • DejaGnu, the name
  • Delete a watchpoint.
  • design goals
  • detailed log
  • diff filename filename
  • directories matching a pattern
  • directory names and --tool
  • download a file
  • download file [ spawnid ]
  • download, tip
  • dumplocals expr
  • dumprocs expr
  • dumpvars expr
  • dumpwatch expr

    • e

  • echo.exp
  • ERROR, ERROR
  • example
  • exec_output
  • exec_prefix, configure options.
  • execute_anywhere cmdline
  • executing commands remotely
  • existing tests, running
  • exit code from runtest
  • exit procedure, tested tools
  • exit_remote_shell spawnid
  • exp filename suffix
  • expect internal tracing
  • expect script names
  • expect scripting language
  • expect_out(buffer)
  • expected failure, expected failure
  • expected failure, cancelling

    • f

  • FAIL, FAIL
  • fail "string"
  • failing test, expected
  • failing test, unexpected
  • failure, expected
  • failure, POSIX definition
  • filename for test files
  • files matching a pattern
  • find dir pattern
  • findfile
  • finding file differences
  • future directions

    • g

  • gdb.t00/echo.exp
  • get_warning_threshold
  • getdirs dir
  • getdirs dir pattern
  • getenv var
  • getting environment variables
  • GNATS bug number
  • Granlund, Torbjorn
  • grep filename regexp
  • grep filename regexp line

    • h

  • help with runtest
  • hints on test case writing
  • host config name, changing
  • host configuration test
  • host, explained
  • host_triplet

    • i

  • ignoretests
  • init file name
  • init file, purpose
  • initialization
  • input files
  • installed tool name
  • installing DejaGnu
  • internal details
  • invoking
  • IP network procedures
  • isbuild "host"
  • ishost "host"
  • isnative
  • istarget "target"

    • k

  • kermit port bps
  • kermit, remote testing via

    • l

  • last command output
  • lib/debugger.exp
  • lib/remote.exp
  • lib/target.exp
  • lib/utils.exp
  • Libes, Don
  • list, pruning
  • list_targets
  • lists supported targets
  • load library file
  • load procedure, tested tools
  • load_lib "library-file"
  • local `site.exp'
  • log files, where to write
  • Lupton, Robert

    • m

  • make builds part of tests
  • make check
  • master `site.exp'
  • Menapace, Julia
  • mondfe
  • mondfe, remote testing via

    • n

  • name "DejaGnu"
  • name for remote test machine
  • name transformations
  • name, initialization module
  • naming conventions
  • naming tests to run, naming tests to run
  • native configuration
  • native configuration test
  • network (IP) procedures
  • NOTE, NOTE
  • note "string"

    • o

  • objdir
  • object directory
  • Opening a remote connection
  • operating principles
  • option defaults
  • option list, runtest
  • options
  • options for runtest, common
  • options, Tcl variables for defaults
  • order of tests
  • Ousterhout, John K.
  • outdir
  • output directory
  • output files
  • output, additional
  • overriding `site.exp'
  • overview

    • p

  • PASS, PASS
  • pass "string"
  • path lookup
  • pattern match, directory
  • pattern match, filenames
  • perror "string number"
  • personal config `site.exp'
  • pop_host
  • pop_target
  • porting to a new host
  • POSIX conformance
  • prefix, configure options
  • Print a backtrace
  • Print global variable values
  • Print local variable value
  • Print procedure bodies
  • print var
  • Print watchpoints
  • Printing variable values
  • PRMS bug number
  • prms_id
  • problem, detected by test case
  • prune list pattern
  • prune_system_crud system text
  • pruning system output, examining program output
  • psource filename
  • push_host name
  • push_target name

    • q

  • quit
  • Quiting DejaGnu

    • r

  • ranlib a file
  • reboot
  • rebooting remote targets
  • regular expression, file contents
  • remote connection procedures
  • remote connection, ending
  • remote test machine name
  • remote testbed, connecting to
  • remote testing
  • remote testing via kermit
  • remote testing via mondfe
  • remote testing via rlogin
  • remote testing via rsh
  • remote testing via telnet
  • remote testing via tip
  • remote.exp
  • remote_close shellid
  • remote_open type
  • rlogin hostname
  • rlogin, remote testing via
  • rsh hostname
  • rsh, remote testing via
  • running
  • running tests
  • runtest description
  • runtest exit code
  • runtest option defaults
  • runtest option list
  • runtest, listing options
  • runtest, most common options
  • runtest, variable defns on cmdline
  • runtest.exp
  • runtest_file_p runtests testcase
  • runtests

    • s

  • searching file contents
  • selecting a range of tests, selecting a range of tests, selecting a range of tests
  • selecting tests for a tool
  • serial download, tip
  • serial line connection, kermit
  • serial line connection, tip
  • set current host
  • set current target
  • set_warning_threshold threshold
  • setenv var val
  • setting defaults for DejaGnu variables
  • setting environment variables
  • setting up targets
  • setup_xfail "config [bugid]"
  • site.exp
  • `site.exp' for all of DejaGnu
  • `site.exp' for each person
  • `site.exp' for each tool
  • `site.exp', multiple
  • slay name
  • slaying processes
  • source directory
  • sourcing Tcl files
  • special variables
  • specifying target name
  • specifying the build config name
  • specifying the host config name
  • specifying the target configuration
  • srcdir
  • standard conformance: POSIX 1003.3
  • start procedure, tested tools
  • starting interactive tools
  • starting the tcl debugger
  • subdir
  • success, POSIX definition
  • successful test
  • successful test, unexpected
  • suffix, expect scripts
  • summary log

    • t

  • target configuration test
  • target configuration, specifying
  • target dependent procedures
  • target machine name
  • target, explained
  • target.exp
  • target_triplet
  • targetname
  • targets
  • tcl
  • tcl debugger
  • Tcl variables for option defaults
  • Tcl variables, defining for runtest
  • tclvar=value
  • telnet hostname port
  • telnet, remote testing via
  • terminating remote connection
  • test case cannot run
  • test case messages
  • test case warnings
  • test case, debugging
  • test case, declaring ambiguity
  • test case, declaring failure
  • test case, declaring no support
  • test case, declaring no test
  • test case, declaring success
  • test case, ERROR in
  • test case, expecting failure
  • test case, informational messages
  • test case, WARNING in
  • test case, WARNING threshold, test case, WARNING threshold
  • test case, writing
  • test cases, debug log
  • test directories, naming
  • test filename
  • test output, displaying all
  • test programs, auxiliary
  • test suite distributions
  • test, failing
  • test, successful
  • test, unresolved outcome
  • test, unsupported
  • tests, running
  • tests, running order
  • tests, running specifically, tests, running specifically, tests, running specifically
  • TET
  • tip port
  • tip, remote testing via
  • tip_download spawnid file
  • tool
  • tool command language
  • tool initialization
  • tool name, as installed
  • tool names and naming conventions
  • tool_exit
  • tool_load
  • tool_start
  • tool_version
  • tracelevel
  • tracing Tcl commands
  • transform
  • transform "toolname"
  • transform tool name
  • turning on output

    • u

  • unexpected success
  • UNRESOLVED, UNRESOLVED
  • unresolved "string"
  • unset current host
  • unset current target
  • unsetenv var
  • unsetting environment variables
  • UNSUPPORTED, UNSUPPORTED
  • unsupported "string"
  • unsupported test
  • UNTESTED, UNTESTED
  • untested "string"
  • untested properties
  • utilities, loading from init file
  • utils.exp

    • v

  • variables for all tests
  • variables for option defaults
  • variables of DejaGnu, defaults
  • verbose
  • verbose [-log] [-n] [--] "string" number
  • verbose builtin function
  • version numbers
  • version procedure, tested tools
  • VxWorks, link with `-r'

    • w

  • WARNING, WARNING
  • warning "string number"
  • Watch when a variable is read
  • Watch when a variable is unset
  • Watch when a variable is written
  • watchdel watch
  • watchread var
  • watchunset var
  • watchwrite var
  • What is New
  • which binary
  • writing a test case

    • x

  • XFAIL, XFAIL
  • XFAIL, avoiding for POSIX
  • XFAIL, producing
  • XPASS
  • XPASS, producing

    • Footnotes

    (1)

    `--tool' selects a particular suite of tests, not the name of the executable program to run. See section Config Variables, for information on the variables that you can use to specify the names of programs to run.

    (2)

    More recent GDB tests use the `gdb_test' procedure. An equivalent test using that procedure is ` gdb_test "echo Hello world!" "Hello world!" '

    (3)

    TET was created by Unisoft for a consortium comprised of X/Open, Unix International, and the Open Software Foundation.

    (4)

    Configuration triples have the form `cpu-vendor-os'.

    (5)

    Distributed in PostScript form with expect as the file
    `expect/tcl-debug.ps'.

    This document was generated on 7 November 1998 using the texi2html translator version 1.52.


Comparing and Merging Files

Short Contents

  • Comparing and Merging Files
  • Overview
  • What Comparison Means
  • diff Output Formats
  • Incomplete Lines
  • Comparing Directories
  • Making diff Output Prettier
  • diff Performance Tradeoffs
  • Comparing Three Files
  • Merging From a Common Ancestor
  • Interactive Merging with sdiff
  • Merging with patch
  • Tips for Making and Using Patches
  • Invoking cmp
  • Invoking diff
  • Invoking diff3
  • Invoking patch
  • Invoking sdiff
  • Standards conformance
  • Future Projects
  • Copying This Manual
  • Index

Table of Contents

  • Comparing and Merging Files
  • Overview
  • What Comparison Means
    • Hunks
    • Suppressing Differences in Blank and Tab Spacing
    • Suppressing Differences in Blank Lines
    • Suppressing Case Differences
    • Suppressing Lines Matching a Regular Expression
    • Summarizing Which Files Differ
    • Binary Files and Forcing Text Comparisons
  • diff Output Formats
    • Two Sample Input Files
    • Showing Differences Without Context
      • Detailed Description of Normal Format
      • An Example of Normal Format
    • Showing Differences in Their Context
      • Context Format
        • Detailed Description of Context Format
        • An Example of Context Format
        • An Example of Context Format with Less Context
      • Unified Format
        • Detailed Description of Unified Format
        • An Example of Unified Format
      • Showing Which Sections Differences Are in
        • Showing Lines That Match Regular Expressions
        • Showing C Function Headings
      • Showing Alternate File Names
    • Showing Differences Side by Side
      • Controlling Side by Side Format
      • An Example of Side by Side Format
    • Making Edit Scripts
      • ed Scripts
        • Detailed Description of ed Format
        • Example ed Script
      • Forward ed Scripts
      • RCS Scripts
    • Merging Files with If-then-else
      • Line Group Formats
      • Line Formats
      • Detailed Description of If-then-else Format
      • An Example of If-then-else Format
  • Incomplete Lines
  • Comparing Directories
  • Making diff Output Prettier
    • Preserving Tab Stop Alignment
    • Paginating diff Output
  • diff Performance Tradeoffs
  • Comparing Three Files
    • A Third Sample Input File
    • Detailed Description of diff3 Normal Format
    • diff3 Hunks
    • An Example of diff3 Normal Format
  • Merging From a Common Ancestor
    • Selecting Which Changes to Incorporate
    • Marking Conflicts
    • Generating the Merged Output Directly
    • How diff3 Merges Incomplete Lines
    • Saving the Changed File
  • Interactive Merging with sdiff
    • Specifying diff Options to sdiff
    • Merge Commands
  • Merging with patch
    • Selecting the patch Input Format
    • Revision Control
    • Applying Imperfect Patches
      • Applying Patches with Changed White Space
      • Applying Reversed Patches
      • Helping patch Find Inexact Matches
      • Predicting what patch will do
    • Creating and Removing Files
    • Updating Time Stamps on Patched Files
    • Multiple Patches in a File
    • Applying Patches in Other Directories
    • Backup Files
    • Backup File Names
    • Reject File Names
    • Messages and Questions from patch
      • Controlling the Verbosity of patch
      • Inhibiting Keyboard Input
      • patch Quoting Style
    • patch and the POSIX Standard
    • GNU patch and Traditional patch
  • Tips for Making and Using Patches
    • Tips for Patch Producers
    • Tips for Patch Consumers
    • Avoiding Common Mistakes
    • Generating Smaller Patches
  • Invoking cmp
    • Options to cmp
  • Invoking diff
    • Options to diff
  • Invoking diff3
    • Options to diff3
  • Invoking patch
    • Options to patch
  • Invoking sdiff
    • Options to sdiff
  • Standards conformance
  • Future Projects
    • Suggested Projects for Improving GNU diff and patch
      • Handling Multibyte and Varying-Width Characters
      • Handling Changes to the Directory Structure
      • Files that are Neither Directories Nor Regular Files
      • File Names that Contain Unusual Characters
      • Outputting Diffs in Time Stamp Order
      • Ignoring Certain Changes
      • Improving Performance
    • Reporting Bugs
  • Copying This Manual
    • GNU Free Documentation License
      • ADDENDUM: How to use this License for your documents
  • Index

Node:Top, Next:Overview, Up:(dir)

Comparing and Merging Files

This manual is for GNU Diffutils (version 2.8.1, 5 April 2002), and documents the GNU diff, diff3, sdiff, and cmp commands for showing the differences between files and the GNU patch command for using their output to update files.

Copyright © 1992, 1993, 1994, 1998, 2001, 2002 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License."

(a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."

  • Overview: Preliminary information.
  • Comparison: What file comparison means.

  • Output Formats: Formats for two-way difference reports.
  • Incomplete Lines: Lines that lack trailing newlines.
  • Comparing Directories: Comparing files and directories.
  • Adjusting Output: Making diff output prettier.
  • diff Performance: Making diff smarter or faster.

  • Comparing Three Files: Formats for three-way difference reports.
  • diff3 Merging: Merging from a common ancestor.

  • Interactive Merging: Interactive merging with sdiff.

  • Merging with patch: Using patch to change old files into new ones.
  • Making Patches: Tips for making and using patch distributions.

  • Invoking cmp: Compare two files byte by byte.
  • Invoking diff: Compare two files line by line.
  • Invoking diff3: Compare three files line by line.
  • Invoking patch: Apply a diff file to an original.
  • Invoking sdiff: Side-by-side merge of file differences.

  • Standards conformance: Conformance to the POSIX standard.
  • Projects: If you've found a bug or other shortcoming.

  • Copying This Manual: How to make copies of this manual.
  • Index: Index.

Node:Overview, Next:Comparison, Previous:Top, Up:Top

Overview

Computer users often find occasion to ask how two files differ. Perhaps one file is a newer version of the other file. Or maybe the two files started out as identical copies but were changed by different people.

You can use the diff command to show differences between two files, or each corresponding file in two directories. diff outputs differences between files line by line in any of several formats, selectable by command line options. This set of differences is often called a diff or patch. For files that are identical, diff normally produces no output; for binary (non-text) files, diff normally reports only that they are different.

You can use the cmp command to show the byte and line numbers where two files differ. cmp can also show all the bytes that differ between the two files, side by side. A way to compare two files character by character is the Emacs command M-x compare-windows. See Other Window, for more information on that command.

You can use the diff3 command to show differences among three files. When two people have made independent changes to a common original, diff3 can report the differences between the original and the two changed versions, and can produce a merged file that contains both persons' changes together with warnings about conflicts.

You can use the sdiff command to merge two files interactively.

You can use the set of differences produced by diff to distribute updates to text files (such as program source code) to other people. This method is especially useful when the differences are small compared to the complete files. Given diff output, you can use the patch program to update, or patch, a copy of the file. If you think of diff as subtracting one file from another to produce their difference, you can think of patch as adding the difference to one file to reproduce the other.

This manual first concentrates on making diffs, and later shows how to use diffs to update files.

GNU diff was written by Paul Eggert, Mike Haertel, David Hayes, Richard Stallman, and Len Tower. Wayne Davison designed and implemented the unified output format. The basic algorithm is described in "An O(ND) Difference Algorithm and its Variations", Eugene W. Myers, Algorithmica Vol. 1 No. 2, 1986, pp. 251-266; and in "A File Comparison Program", Webb Miller and Eugene W. Myers, Software--Practice and Experience Vol. 15 No. 11, 1985, pp. 1025-1040. The algorithm was independently discovered as described in "Algorithms for Approximate String Matching", E. Ukkonen, Information and Control Vol. 64, 1985, pp. 100-118.

GNU diff3 was written by Randy Smith. GNU sdiff was written by Thomas Lord. GNU cmp was written by Torbjorn Granlund and David MacKenzie.

patch was written mainly by Larry Wall and Paul Eggert; several GNU enhancements were contributed by Wayne Davison and David MacKenzie. Parts of this manual are adapted from a manual page written by Larry Wall, with his permission.

Node:Comparison, Next:Output Formats, Previous:Overview, Up:Top

What Comparison Means

There are several ways to think about the differences between two files. One way to think of the differences is as a series of lines that were deleted from, inserted in, or changed in one file to produce the other file. diff compares two files line by line, finds groups of lines that differ, and reports each group of differing lines. It can report the differing lines in several formats, which have different purposes.

GNU diff can show whether files are different without detailing the differences. It also provides ways to suppress certain kinds of differences that are not important to you. Most commonly, such differences are changes in the amount of white space between words or lines. diff also provides ways to suppress differences in alphabetic case or in lines that match a regular expression that you provide. These options can accumulate; for example, you can ignore changes in both white space and alphabetic case.

Another way to think of the differences between two files is as a sequence of pairs of bytes that can be either identical or different. cmp reports the differences between two files byte by byte, instead of line by line. As a result, it is often more useful than diff for comparing binary files. For text files, cmp is useful mainly when you want to know only whether two files are identical, or whether one file is a prefix of the other.

To illustrate the effect that considering changes byte by byte can have compared with considering them line by line, think of what happens if a single newline character is added to the beginning of a file. If that file is then compared with an otherwise identical file that lacks the newline at the beginning, diff will report that a blank line has been added to the file, while cmp will report that almost every byte of the two files differs.

diff3 normally compares three input files line by line, finds groups of lines that differ, and reports each group of differing lines. Its output is designed to make it easy to inspect two different sets of changes to the same file.

  • Hunks: Groups of differing lines.
  • White Space: Suppressing differences in white space.
  • Blank Lines: Suppressing differences in blank lines.
  • Case Folding: Suppressing differences in alphabetic case.
  • Specified Folding: Suppressing differences that match regular expressions.
  • Brief: Summarizing which files are different.
  • Binary: Comparing binary files or forcing text comparisons.

Node:Hunks, Next:White Space, Up:Comparison

Hunks

When comparing two files, diff finds sequences of lines common to both files, interspersed with groups of differing lines called hunks. Comparing two identical files yields one sequence of common lines and no hunks, because no lines differ. Comparing two entirely different files yields no common lines and one large hunk that contains all lines of both files. In general, there are many ways to match up lines between two given files. diff tries to minimize the total hunk size by finding large sequences of common lines interspersed with small hunks of differing lines.

For example, suppose the file F contains the three lines a, b, c, and the file G contains the same three lines in reverse order c, b, a. If diff finds the line c as common, then the command diff F G produces this output:

1,2d0
< a
< b
3a2,3
> b
> a

But if diff notices the common line b instead, it produces this output:

1c1
< a
---
> c
3c3
< c
---
> a

It is also possible to find a as the common line. diff does not always find an optimal matching between the files; it takes shortcuts to run faster. But its output is usually close to the shortest possible. You can adjust this tradeoff with the --minimal option (see diff Performance).

Node:White Space, Next:Blank Lines, Previous:Hunks, Up:Comparison

Suppressing Differences in Blank and Tab Spacing

The -E and --ignore-tab-expansion options ignore the distinction between tabs and spaces on input. A tab is considered to be equivalent to the number of spaces to the next tab stop. diff assumes that tab stops are set every 8 print columns.

The -b and --ignore-space-change options are stronger. They ignore white space at line end, and consider all other sequences of one or more white space characters to be equivalent. With these options, diff considers the following two lines to be equivalent, where $ denotes the line end:

Here lyeth  muche rychnesse  in lytell space.   -- John Heywood$
Here lyeth muche rychnesse in lytell space. -- John Heywood   $

The -w and --ignore-all-space options are stronger still. They ignore difference even if one line has white space where the other line has none. White space characters include tab, newline, vertical tab, form feed, carriage return, and space; some locales may define additional characters to be white space. With these options, diff considers the following two lines to be equivalent, where $ denotes the line end and ^M denotes a carriage return:

Here lyeth  muche  rychnesse in lytell space.--  John Heywood$
  He relyeth much erychnes  seinly tells pace.  --John Heywood   ^M$

Node:Blank Lines, Next:Case Folding, Previous:White Space, Up:Comparison

Suppressing Differences in Blank Lines

The -B and --ignore-blank-lines options ignore insertions or deletions of blank lines. These options affect only lines that are completely empty; they do not affect lines that look empty but contain space or tab characters. With these options, for example, a file containing

1.  A point is that which has no part.

2.  A line is breadthless length.
-- Euclid, The Elements, I

is considered identical to a file containing

1.  A point is that which has no part.
2.  A line is breadthless length.

-- Euclid, The Elements, I

Node:Case Folding, Next:Specified Folding, Previous:Blank Lines, Up:Comparison

Suppressing Case Differences

GNU diff can treat lower case letters as equivalent to their upper case counterparts, so that, for example, it considers Funky Stuff, funky STUFF, and fUNKy stuFf to all be the same. To request this, use the -i or --ignore-case option.

Node:Specified Folding, Next:Brief, Previous:Case Folding, Up:Comparison

Suppressing Lines Matching a Regular Expression

To ignore insertions and deletions of lines that match a grep-style regular expression, use the -I regexp or --ignore-matching-lines=regexp option. You should escape regular expressions that contain shell metacharacters to prevent the shell from expanding them. For example, diff -I '^[[:digit:]]' ignores all changes to lines beginning with a digit.

However, -I only ignores the insertion or deletion of lines that contain the regular expression if every changed line in the hunk--every insertion and every deletion--matches the regular expression. In other words, for each nonignorable change, diff prints the complete set of changes in its vicinity, including the ignorable ones.

You can specify more than one regular expression for lines to ignore by using more than one -I option. diff tries to match each line against each regular expression.

Node:Brief, Next:Binary, Previous:Specified Folding, Up:Comparison

Summarizing Which Files Differ

When you only want to find out whether files are different, and you don't care what the differences are, you can use the summary output format. In this format, instead of showing the differences between the files, diff simply reports whether files differ. The -q and --brief options select this output format.

This format is especially useful when comparing the contents of two directories. It is also much faster than doing the normal line by line comparisons, because diff can stop analyzing the files as soon as it knows that there are any differences.

You can also get a brief indication of whether two files differ by using cmp. For files that are identical, cmp produces no output. When the files differ, by default, cmp outputs the byte and line number where the first difference occurs. You can use the -s option to suppress that information, so that cmp produces no output and reports whether the files differ using only its exit status (see Invoking cmp).

Unlike diff, cmp cannot compare directories; it can only compare two files.

Node:Binary, Previous:Brief, Up:Comparison

Binary Files and Forcing Text Comparisons

If diff thinks that either of the two files it is comparing is binary (a non-text file), it normally treats that pair of files much as if the summary output format had been selected (see Brief), and reports only that the binary files are different. This is because line by line comparisons are usually not meaningful for binary files.

diff determines whether a file is text or binary by checking the first few bytes in the file; the exact number of bytes is system dependent, but it is typically several thousand. If every byte in that part of the file is non-null, diff considers the file to be text; otherwise it considers the file to be binary.

Sometimes you might want to force diff to consider files to be text. For example, you might be comparing text files that contain null characters; diff would erroneously decide that those are non-text files. Or you might be comparing documents that are in a format used by a word processing system that uses null characters to indicate special formatting. You can force diff to consider all files to be text files, and compare them line by line, by using the -a or --text option. If the files you compare using this option do not in fact contain text, they will probably contain few newline characters, and the diff output will consist of hunks showing differences between long lines of whatever characters the files contain.

You can also force diff to consider all files to be binary files, and report only whether they differ (but not how). Use the -q or --brief option for this.

Differing binary files are considered to cause trouble because the resulting diff output does not capture all the differences. This trouble causes diff to exit with status 2. However, this trouble cannot occur with the --a or --text option, or with the -q or --brief option, as these options both cause diff to treat binary files like text files.

In operating systems that distinguish between text and binary files, diff normally reads and writes all data as text. Use the --binary option to force diff to read and write binary data instead. This option has no effect on a POSIX-compliant system like GNU or traditional Unix. However, many personal computer operating systems represent the end of a line with a carriage return followed by a newline. On such systems, diff normally ignores these carriage returns on input and generates them at the end of each output line, but with the --binary option diff treats each carriage return as just another input character, and does not generate a carriage return at the end of each output line. This can be useful when dealing with non-text files that are meant to be interchanged with POSIX-compliant systems.

The --strip-trailing-cr causes diff to treat input lines that end in carriage return followed by newline as if they end in plain newline. This can be useful when comparing text that is imperfectly imported from many personal computer operating systems. This option affects how lines are read, which in turn affects how they are compared and output.

If you want to compare two files byte by byte, you can use the cmp program with the -l option to show the values of each differing byte in the two files. With GNU cmp, you can also use the -b option to show the ASCII representation of those bytes. See Invoking cmp, for more information.

If diff3 thinks that any of the files it is comparing is binary (a non-text file), it normally reports an error, because such comparisons are usually not useful. diff3 uses the same test as diff to decide whether a file is binary. As with diff, if the input files contain a few non-text bytes but otherwise are like text files, you can force diff3 to consider all files to be text files and compare them line by line by using the -a or --text options.

Node:Output Formats, Next:Incomplete Lines, Previous:Comparison, Up:Top

diff Output Formats

diff has several mutually exclusive options for output format. The following sections describe each format, illustrating how diff reports the differences between two sample input files.

  • Sample diff Input: Sample diff input files for examples.
  • Normal: Showing differences without surrounding text.
  • Context: Showing differences with the surrounding text.
  • Side by Side: Showing differences in two columns.
  • Scripts: Generating scripts for other programs.
  • If-then-else: Merging files with if-then-else.

Node:Sample diff Input, Next:Normal, Up:Output Formats

Two Sample Input Files

Here are two sample files that we will use in numerous examples to illustrate the output of diff and how various options can change it.

This is the file lao:

The Way that can be told of is not the eternal Way;
The name that can be named is not the eternal name.
The Nameless is the origin of Heaven and Earth;
The Named is the mother of all things.
Therefore let there always be non-being,
  so we may see their subtlety,
And let there always be being,
  so we may see their outcome.
The two are the same,
But after they are produced,
  they have different names.

This is the file tzu:

The Nameless is the origin of Heaven and Earth;
The named is the mother of all things.

Therefore let there always be non-being,
  so we may see their subtlety,
And let there always be being,
  so we may see their outcome.
The two are the same,
But after they are produced,
  they have different names.
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!

In this example, the first hunk contains just the first two lines of lao, the second hunk contains the fourth line of lao opposing the second and third lines of tzu, and the last hunk contains just the last three lines of tzu.

Node:Normal, Next:Context, Previous:Sample diff Input, Up:Output Formats

Showing Differences Without Context

The "normal" diff output format shows each hunk of differences without any surrounding context. Sometimes such output is the clearest way to see how lines have changed, without the clutter of nearby unchanged lines (although you can get similar results with the context or unified formats by using 0 lines of context). However, this format is no longer widely used for sending out patches; for that purpose, the context format (see Context Format) and the unified format (see Unified Format) are superior. Normal format is the default for compatibility with older versions of diff and the POSIX standard. Use the --normal option to select this output format explicitly.

  • Detailed Normal: A detailed description of normal output format.
  • Example Normal: Sample output in the normal format.

Node:Detailed Normal, Next:Example Normal, Up:Normal

Detailed Description of Normal Format

The normal output format consists of one or more hunks of differences; each hunk shows one area where the files differ. Normal format hunks look like this:

change-command
< from-file-line
< from-file-line...
---
> to-file-line
> to-file-line...

There are three types of change commands. Each consists of a line number or comma-separated range of lines in the first file, a single character indicating the kind of change to make, and a line number or comma-separated range of lines in the second file. All line numbers are the original line numbers in each file. The types of change commands are:

lar
Add the lines in range r of the second file after line l of the first file. For example, 8a12,15 means append lines 12-15 of file 2 after line 8 of file 1; or, if changing file 2 into file 1, delete lines 12-15 of file 2.
fct
Replace the lines in range f of the first file with lines in range t of the second file. This is like a combined add and delete, but more compact. For example, 5,7c8,10 means change lines 5-7 of file 1 to read as lines 8-10 of file 2; or, if changing file 2 into file 1, change lines 8-10 of file 2 to read as lines 5-7 of file 1.
rdl
Delete the lines in range r from the first file; line l is where they would have appeared in the second file had they not been deleted. For example, 5,7d3 means delete lines 5-7 of file 1; or, if changing file 2 into file 1, append lines 5-7 of file 1 after line 3 of file 2.

Node:Example Normal, Previous:Detailed Normal, Up:Normal

An Example of Normal Format

Here is the output of the command diff lao tzu (see Sample diff Input, for the complete contents of the two files). Notice that it shows only the lines that are different between the two files.

1,2d0
< The Way that can be told of is not the eternal Way;
< The name that can be named is not the eternal name.
4c2,3
< The Named is the mother of all things.
---
> The named is the mother of all things.
>
11a11,13
> They both may be called deep and profound.
> Deeper and more profound,
> The door of all subtleties!

Node:Context, Next:Side by Side, Previous:Normal, Up:Output Formats

Showing Differences in Their Context

Usually, when you are looking at the differences between files, you will also want to see the parts of the files near the lines that differ, to help you understand exactly what has changed. These nearby parts of the files are called the context.

GNU diff provides two output formats that show context around the differing lines: context format and unified format. It can optionally show in which function or section of the file the differing lines are found.

If you are distributing new versions of files to other people in the form of diff output, you should use one of the output formats that show context so that they can apply the diffs even if they have made small changes of their own to the files. patch can apply the diffs in this case by searching in the files for the lines of context around the differing lines; if those lines are actually a few lines away from where the diff says they are, patch can adjust the line numbers accordingly and still apply the diff correctly. See Imperfect, for more information on using patch to apply imperfect diffs.

  • Context Format: An output format that shows surrounding lines.
  • Unified Format: A more compact output format that shows context.
  • Sections: Showing which sections of the files differences are in.
  • Alternate Names: Showing alternate file names in context headers.

Node:Context Format, Next:Unified Format, Up:Context

Context Format

The context output format shows several lines of context around the lines that differ. It is the standard format for distributing updates to source code.

To select this output format, use the -C lines, --context[=lines], or -c option. The argument lines that some of these options take is the number of lines of context to show. If you do not specify lines, it defaults to three. For proper operation, patch typically needs at least two lines of context.

  • Detailed Context: A detailed description of the context output format.
  • Example Context: Sample output in context format.
  • Less Context: Another sample with less context.

Node:Detailed Context, Next:Example Context, Up:Context Format
Detailed Description of Context Format

The context output format starts with a two-line header, which looks like this:

*** from-file from-file-modification-time
--- to-file to-file-modification time

The time stamp normally looks like 2002-02-21 23:30:39.942229878 -0800 to indicate the date, time with fractional seconds, and time zone in Internet RFC 2822 format. However, a traditional time stamp like Thu Feb 21 23:30:39 2002 is used if the LC_TIME locale category is either C or POSIX.

You can change the header's content with the --label=label option; see Alternate Names.

Next come one or more hunks of differences; each hunk shows one area where the files differ. Context format hunks look like this:

***************
*** from-file-line-range ****
  from-file-line
  from-file-line...
--- to-file-line-range ----
  to-file-line
  to-file-line...

The lines of context around the lines that differ start with two space characters. The lines that differ between the two files start with one of the following indicator characters, followed by a space character:

!
A line that is part of a group of one or more lines that changed between the two files. There is a corresponding group of lines marked with ! in the part of this hunk for the other file.
+
An "inserted" line in the second file that corresponds to nothing in the first file.
-
A "deleted" line in the first file that corresponds to nothing in the second file.

If all of the changes in a hunk are insertions, the lines of from-file are omitted. If all of the changes are deletions, the lines of to-file are omitted.

Node:Example Context, Next:Less Context, Previous:Detailed Context, Up:Context Format
An Example of Context Format

Here is the output of diff -c lao tzu (see Sample diff Input, for the complete contents of the two files). Notice that up to three lines that are not different are shown around each line that is different; they are the context lines. Also notice that the first two hunks have run together, because their contents overlap.

*** lao	2002-02-21 23:30:39.942229878 -0800
--- tzu	2002-02-21 23:30:50.442260588 -0800
***************
*** 1,7 ****
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
  The Nameless is the origin of Heaven and Earth;
! The Named is the mother of all things.
  Therefore let there always be non-being,
    so we may see their subtlety,
  And let there always be being,
--- 1,6 ----
  The Nameless is the origin of Heaven and Earth;
! The named is the mother of all things.
!
  Therefore let there always be non-being,
    so we may see their subtlety,
  And let there always be being,
***************
*** 9,11 ****
--- 8,13 ----
  The two are the same,
  But after they are produced,
    they have different names.
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!

Node:Less Context, Previous:Example Context, Up:Context Format
An Example of Context Format with Less Context

Here is the output of diff -C 1 lao tzu (see Sample diff Input, for the complete contents of the two files). Notice that at most one context line is reported here.

*** lao	2002-02-21 23:30:39.942229878 -0800
--- tzu	2002-02-21 23:30:50.442260588 -0800
***************
*** 1,5 ****
- The Way that can be told of is not the eternal Way;
- The name that can be named is not the eternal name.
  The Nameless is the origin of Heaven and Earth;
! The Named is the mother of all things.
  Therefore let there always be non-being,
--- 1,4 ----
  The Nameless is the origin of Heaven and Earth;
! The named is the mother of all things.
!
  Therefore let there always be non-being,
***************
*** 11 ****
--- 10,13 ----
    they have different names.
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!

Node:Unified Format, Next:Sections, Previous:Context Format, Up:Context

Unified Format

The unified output format is a variation on the context format that is more compact because it omits redundant context lines. To select this output format, use the -U lines, --unified[=lines], or -u option. The argument lines is the number of lines of context to show. When it is not given, it defaults to three.

At present, only GNU diff can produce this format and only GNU patch can automatically apply diffs in this format. For proper operation, patch typically needs at least three lines of context.

  • Detailed Unified: A detailed description of unified format.
  • Example Unified: Sample output in unified format.

Node:Detailed Unified, Next:Example Unified, Up:Unified Format
Detailed Description of Unified Format

The unified output format starts with a two-line header, which looks like this:

--- from-file from-file-modification-time
+++ to-file to-file-modification-time

The time stamp looks like 2002-02-21 23:30:39.942229878 -0800 to indicate the date, time with fractional seconds, and time zone.

You can change the header's content with the --label=label option; see See Alternate Names.

Next come one or more hunks of differences; each hunk shows one area where the files differ. Unified format hunks look like this:

@@ from-file-range to-file-range @@
 line-from-either-file
 line-from-either-file...

The lines common to both files begin with a space character. The lines that actually differ between the two files have one of the following indicator characters in the left print column:

+
A line was added here to the first file.
-
A line was removed here from the first file.

Node:Example Unified, Previous:Detailed Unified, Up:Unified Format
An Example of Unified Format

Here is the output of the command diff -u lao tzu (see Sample diff Input, for the complete contents of the two files):

--- lao	2002-02-21 23:30:39.942229878 -0800
+++ tzu	2002-02-21 23:30:50.442260588 -0800
@@ -1,7 +1,6 @@
-The Way that can be told of is not the eternal Way;
-The name that can be named is not the eternal name.
 The Nameless is the origin of Heaven and Earth;
-The Named is the mother of all things.
+The named is the mother of all things.
+
 Therefore let there always be non-being,
   so we may see their subtlety,
 And let there always be being,
@@ -9,3 +8,6 @@
 The two are the same,
 But after they are produced,
   they have different names.
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!

Node:Sections, Next:Alternate Names, Previous:Unified Format, Up:Context

Showing Which Sections Differences Are in

Sometimes you might want to know which part of the files each change falls in. If the files are source code, this could mean which function was changed. If the files are documents, it could mean which chapter or appendix was changed. GNU diff can show this by displaying the nearest section heading line that precedes the differing lines. Which lines are "section headings" is determined by a regular expression.

  • Specified Headings: Showing headings that match regular expressions.
  • C Function Headings: Showing headings of C functions.

Node:Specified Headings, Next:C Function Headings, Up:Sections
Showing Lines That Match Regular Expressions

To show in which sections differences occur for files that are not source code for C or similar languages, use the -F regexp or --show-function-line=regexp option. diff considers lines that match the grep-style regular expression regexp to be the beginning of a section of the file. Here are suggested regular expressions for some common languages:

^[[:alpha:]$_]
C, C++, Prolog
^(
Lisp
^@node
Texinfo

This option does not automatically select an output format; in order to use it, you must select the context format (see Context Format) or unified format (see Unified Format). In other output formats it has no effect.

The -F and --show-function-line options find the nearest unchanged line that precedes each hunk of differences and matches the given regular expression. Then they add that line to the end of the line of asterisks in the context format, or to the @@ line in unified format. If no matching line exists, they leave the output for that hunk unchanged. If that line is more than 40 characters long, they output only the first 40 characters. You can specify more than one regular expression for such lines; diff tries to match each line against each regular expression, starting with the last one given. This means that you can use -p and -F together, if you wish.

Node:C Function Headings, Previous:Specified Headings, Up:Sections
Showing C Function Headings

To show in which functions differences occur for C and similar languages, you can use the -p or --show-c-function option. This option automatically defaults to the context output format (see Context Format), with the default number of lines of context. You can override that number with -C lines elsewhere in the command line. You can override both the format and the number with -U lines elsewhere in the command line.

The -p and --show-c-function options are equivalent to -F '^[[:alpha:]$_]' if the unified format is specified, otherwise -c -F '^[[:alpha:]$_]' (see Specified Headings). GNU diff provides them for the sake of convenience.

Node:Alternate Names, Previous:Sections, Up:Context

Showing Alternate File Names

If you are comparing two files that have meaningless or uninformative names, you might want diff to show alternate names in the header of the context and unified output formats. To do this, use the --label=label option. The first time you give this option, its argument replaces the name and date of the first file in the header; the second time, its argument replaces the name and date of the second file. If you give this option more than twice, diff reports an error. The --label option does not affect the file names in the pr header when the -l or --paginate option is used (see Pagination).

Here are the first two lines of the output from diff -C 2 --label=original --label=modified lao tzu:

*** original
--- modified

Node:Side by Side, Next:Scripts, Previous:Context, Up:Output Formats

Showing Differences Side by Side

diff can produce a side by side difference listing of two files. The files are listed in two columns with a gutter between them. The gutter contains one of the following markers:

white space
The corresponding lines are in common. That is, either the lines are identical, or the difference is ignored because of one of the --ignore options (see White Space).
|
The corresponding lines differ, and they are either both complete or both incomplete.
<
The files differ and only the first file contains the line.
>
The files differ and only the second file contains the line.
(
Only the first file contains the line, but the difference is ignored.
)
Only the second file contains the line, but the difference is ignored.
\
The corresponding lines differ, and only the first line is incomplete.
/
The corresponding lines differ, and only the second line is incomplete.

Normally, an output line is incomplete if and only if the lines that it contains are incomplete; See Incomplete Lines. However, when an output line represents two differing lines, one might be incomplete while the other is not. In this case, the output line is complete, but its the gutter is marked \ if the first line is incomplete, / if the second line is.

Side by side format is sometimes easiest to read, but it has limitations. It generates much wider output than usual, and truncates lines that are too long to fit. Also, it relies on lining up output more heavily than usual, so its output looks particularly bad if you use varying width fonts, nonstandard tab stops, or nonprinting characters.

You can use the sdiff command to interactively merge side by side differences. See Interactive Merging, for more information on merging files.

  • Side by Side Format: Controlling side by side output format.
  • Example Side by Side: Sample side by side output.

Node:Side by Side Format, Next:Example Side by Side, Up:Side by Side

Controlling Side by Side Format

The -y or --side-by-side option selects side by side format. Because side by side output lines contain two input lines, the output is wider than usual: normally 130 print columns, which can fit onto a traditional printer line. You can set the width of the output with the -W columns or --width=columns option. The output is split into two halves of equal width, separated by a small gutter to mark differences; the right half is aligned to a tab stop so that tabs line up. Input lines that are too long to fit in half of an output line are truncated for output.

The --left-column option prints only the left column of two common lines. The --suppress-common-lines option suppresses common lines entirely.

Node:Example Side by Side, Previous:Side by Side Format, Up:Side by Side

An Example of Side by Side Format

Here is the output of the command diff -y -W 72 lao tzu (see Sample diff Input, for the complete contents of the two files).

The Way that can be told of is n   <
The name that can be named is no   <
The Nameless is the origin of He        The Nameless is the origin of He
The Named is the mother of all t   |    The named is the mother of all t
                                   >
Therefore let there always be no        Therefore let there always be no
  so we may see their subtlety,           so we may see their subtlety,
And let there always be being,          And let there always be being,
  so we may see their outcome.            so we may see their outcome.
The two are the same,                   The two are the same,
But after they are produced,            But after they are produced,
  they have different names.              they have different names.
                                   >    They both may be called deep and
                                   >    Deeper and more profound,
                                   >    The door of all subtleties!

Node:Scripts, Next:If-then-else, Previous:Side by Side, Up:Output Formats

Making Edit Scripts

Several output modes produce command scripts for editing from-file to produce to-file.

  • ed Scripts: Using diff to produce commands for ed.
  • Forward ed: Making forward ed scripts.
  • RCS: A special diff output format used by RCS.

Node:ed Scripts, Next:Forward ed, Up:Scripts

ed Scripts

diff can produce commands that direct the ed text editor to change the first file into the second file. Long ago, this was the only output mode that was suitable for editing one file into another automatically; today, with patch, it is almost obsolete. Use the -e or --ed option to select this output format.

Like the normal format (see Normal), this output format does not show any context; unlike the normal format, it does not include the information necessary to apply the diff in reverse (to produce the first file if all you have is the second file and the diff).

If the file d contains the output of diff -e old new, then the command (cat d && echo w) | ed - old edits old to make it a copy of new. More generally, if d1, d2, ..., dN contain the outputs of diff -e old new1, diff -e new1 new2, ..., diff -e newN-1 newN, respectively, then the command (cat d1 d2 ... dN && echo w) | ed - old edits old to make it a copy of newN.

  • Detailed ed: A detailed description of ed format.
  • Example ed: A sample ed script.

Node:Detailed ed, Next:Example ed, Up:ed Scripts
Detailed Description of ed Format

The ed output format consists of one or more hunks of differences. The changes closest to the ends of the files come first so that commands that change the number of lines do not affect how ed interprets line numbers in succeeding commands. ed format hunks look like this:

change-command
to-file-line
to-file-line...
.

Because ed uses a single period on a line to indicate the end of input, GNU diff protects lines of changes that contain a single period on a line by writing two periods instead, then writing a subsequent ed command to change the two periods into one. The ed format cannot represent an incomplete line, so if the second file ends in a changed incomplete line, diff reports an error and then pretends that a newline was appended.

There are three types of change commands. Each consists of a line number or comma-separated range of lines in the first file and a single character indicating the kind of change to make. All line numbers are the original line numbers in the file. The types of change commands are:

la
Add text from the second file after line l in the first file. For example, 8a means to add the following lines after line 8 of file 1.
rc
Replace the lines in range r in the first file with the following lines. Like a combined add and delete, but more compact. For example, 5,7c means change lines 5-7 of file 1 to read as the text file 2.
rd
Delete the lines in range r from the first file. For example, 5,7d means delete lines 5-7 of file 1.

Node:Example ed, Previous:Detailed ed, Up:ed Scripts
Example ed Script

Here is the output of diff -e lao tzu (see Sample diff Input, for the complete contents of the two files):

11a
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
.
4c
The named is the mother of all things.

.
1,2d

Node:Forward ed, Next:RCS, Previous:ed Scripts, Up:Scripts

Forward ed Scripts

diff can produce output that is like an ed script, but with hunks in forward (front to back) order. The format of the commands is also changed slightly: command characters precede the lines they modify, spaces separate line numbers in ranges, and no attempt is made to disambiguate hunk lines consisting of a single period. Like ed format, forward ed format cannot represent incomplete lines.

Forward ed format is not very useful, because neither ed nor patch can apply diffs in this format. It exists mainly for compatibility with older versions of diff. Use the -f or --forward-ed option to select it.

Node:RCS, Previous:Forward ed, Up:Scripts

RCS Scripts

The RCS output format is designed specifically for use by the Revision Control System, which is a set of free programs used for organizing different versions and systems of files. Use the -n or --rcs option to select this output format. It is like the forward ed format (see Forward ed), but it can represent arbitrary changes to the contents of a file because it avoids the forward ed format's problems with lines consisting of a single period and with incomplete lines. Instead of ending text sections with a line consisting of a single period, each command specifies the number of lines it affects; a combination of the a and d commands are used instead of c. Also, if the second file ends in a changed incomplete line, then the output also ends in an incomplete line.

Here is the output of diff -n lao tzu (see Sample diff Input, for the complete contents of the two files):

d1 2
d4 1
a4 2
The named is the mother of all things.

a11 3
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!

Node:If-then-else, Previous:Scripts, Up:Output Formats

Merging Files with If-then-else

You can use diff to merge two files of C source code. The output of diff in this format contains all the lines of both files. Lines common to both files are output just once; the differing parts are separated by the C preprocessor directives #ifdef name or #ifndef name, #else, and #endif. When compiling the output, you select which version to use by either defining or leaving undefined the macro name.

To merge two files, use diff with the -D name or --ifdef=name option. The argument name is the C preprocessor identifier to use in the #ifdef and #ifndef directives.

For example, if you change an instance of wait (&s) to waitpid (-1, &s, 0) and then merge the old and new files with the --ifdef=HAVE_WAITPID option, then the affected part of your code might look like this:

    do {
#ifndef HAVE_WAITPID
        if ((w = wait (&s)) < 0  &&  errno != EINTR)
#else /* HAVE_WAITPID */
        if ((w = waitpid (-1, &s, 0)) < 0  &&  errno != EINTR)
#endif /* HAVE_WAITPID */
            return w;
    } while (w != child);

You can specify formats for languages other than C by using line group formats and line formats, as described in the next sections.

  • Line Group Formats: Formats for general if-then-else line groups.
  • Line Formats: Formats for each line in a line group.
  • Detailed If-then-else: A detailed description of if-then-else format.
  • Example If-then-else: Sample if-then-else format output.

Node:Line Group Formats, Next:Line Formats, Up:If-then-else

Line Group Formats

Line group formats let you specify formats suitable for many applications that allow if-then-else input, including programming languages and text formatting languages. A line group format specifies the output format for a contiguous group of similar lines.

For example, the following command compares the TeX files old and new, and outputs a merged file in which old regions are surrounded by \begin{em}-\end{em} lines, and new regions are surrounded by \begin{bf}-\end{bf} lines.

diff \
   --old-group-format='\begin{em}
%<\end{em}
' \
   --new-group-format='\begin{bf}
%>\end{bf}
' \
   old new

The following command is equivalent to the above example, but it is a little more verbose, because it spells out the default line group formats.

diff \
   --old-group-format='\begin{em}
%<\end{em}
' \
   --new-group-format='\begin{bf}
%>\end{bf}
' \
   --unchanged-group-format='%=' \
   --changed-group-format='\begin{em}
%<\end{em}
\begin{bf}
%>\end{bf}
' \
   old new

Here is a more advanced example, which outputs a diff listing with headers containing line numbers in a "plain English" style.

diff \
   --unchanged-group-format='' \
   --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
%<' \
   --new-group-format='-------- %dN line%(N=1?:s) added after %de:
%>' \
   --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
%<-------- to:
%>' \
   old new

To specify a line group format, use diff with one of the options listed below. You can specify up to four line group formats, one for each kind of line group. You should quote format, because it typically contains shell metacharacters.

--old-group-format=format
These line groups are hunks containing only lines from the first file. The default old group format is the same as the changed group format if it is specified; otherwise it is a format that outputs the line group as-is.
--new-group-format=format
These line groups are hunks containing only lines from the second file. The default new group format is same as the changed group format if it is specified; otherwise it is a format that outputs the line group as-is.
--changed-group-format=format
These line groups are hunks containing lines from both files. The default changed group format is the concatenation of the old and new group formats.
--unchanged-group-format=format
These line groups contain lines common to both files. The default unchanged group format is a format that outputs the line group as-is.

In a line group format, ordinary characters represent themselves; conversion specifications start with % and have one of the following forms.

%<
stands for the lines from the first file, including the trailing newline. Each line is formatted according to the old line format (see Line Formats).
%>
stands for the lines from the second file, including the trailing newline. Each line is formatted according to the new line format.
%=
stands for the lines common to both files, including the trailing newline. Each line is formatted according to the unchanged line format.
%%
stands for %.
%c'C'
where C is a single character, stands for C. C may not be a backslash or an apostrophe. For example, %c':' stands for a colon, even inside the then-part of an if-then-else format, which a colon would normally terminate.
%c'\O'
where O is a string of 1, 2, or 3 octal digits, stands for the character with octal code O. For example, %c'\0' stands for a null character.
Fn
where F is a printf conversion specification and n is one of the following letters, stands for n's value formatted with F.
e
The line number of the line just before the group in the old file.
f
The line number of the first line in the group in the old file; equals e + 1.
l
The line number of the last line in the group in the old file.
m
The line number of the line just after the group in the old file; equals l + 1.
n
The number of lines in the group in the old file; equals l - f + 1.
E, F, L, M, N
Likewise, for lines in the new file.

The printf conversion specification can be %d, %o, %x, or %X, specifying decimal, octal, lower case hexadecimal, or upper case hexadecimal output respectively. After the % the following options can appear in sequence: a series of zero or more flags; an integer specifying the minimum field width; and a period followed by an optional integer specifying the minimum number of digits. The flags are - for left-justification, ' for separating the digit into groups as specified by the LC_NUMERIC locale category, and 0 for padding with zeros instead of spaces. For example, %5dN prints the number of new lines in the group in a field of width 5 characters, using the printf format "%5d".

(A=B?T:E)
If A equals B then T else E. A and B are each either a decimal constant or a single letter interpreted as above. This format spec is equivalent to T if A's value equals B's; otherwise it is equivalent to E.

For example, %(N=0?no:%dN) line%(N=1?:s) is equivalent to no lines if N (the number of lines in the group in the the new file) is 0, to 1 line if N is 1, and to %dN lines otherwise.

Node:Line Formats, Next:Detailed If-then-else, Previous:Line Group Formats, Up:If-then-else

Line Formats

Line formats control how each line taken from an input file is output as part of a line group in if-then-else format.

For example, the following command outputs text with a one-character change indicator to the left of the text. The first character of output is - for deleted lines, | for added lines, and a space for unchanged lines. The formats contain newline characters where newlines are desired on output.

diff \
   --old-line-format='-%l
' \
   --new-line-format='|%l
' \
   --unchanged-line-format=' %l
' \
   old new

To specify a line format, use one of the following options. You should quote format, since it often contains shell metacharacters.

--old-line-format=format
formats lines just from the first file.
--new-line-format=format
formats lines just from the second file.
--unchanged-line-format=format
formats lines common to both files.
--line-format=format
formats all lines; in effect, it sets all three above options simultaneously.

In a line format, ordinary characters represent themselves; conversion specifications start with % and have one of the following forms.

%l
stands for the contents of the line, not counting its trailing newline (if any). This format ignores whether the line is incomplete; See Incomplete Lines.
%L
stands for the contents of the line, including its trailing newline (if any). If a line is incomplete, this format preserves its incompleteness.
%%
stands for %.
%c'C'
where C is a single character, stands for C. C may not be a backslash or an apostrophe. For example, %c':' stands for a colon.
%c'\O'
where O is a string of 1, 2, or 3 octal digits, stands for the character with octal code O. For example, %c'\0' stands for a null character.
Fn
where F is a printf conversion specification, stands for the line number formatted with F. For example, %.5dn prints the line number using the printf format "%.5d". See Line Group Formats, for more about printf conversion specifications.

The default line format is %l followed by a newline character.

If the input contains tab characters and it is important that they line up on output, you should ensure that %l or %L in a line format is just after a tab stop (e.g. by preceding %l or %L with a tab character), or you should use the -t or --expand-tabs option.

Taken together, the line and line group formats let you specify many different formats. For example, the following command uses a format similar to normal diff format. You can tailor this command to get fine control over diff output.

diff \
   --old-line-format='< %l
' \
   --new-line-format='> %l
' \
   --old-group-format='%df%(f=l?:,%dl)d%dE
%<' \
   --new-group-format='%dea%dF%(F=L?:,%dL)
%>' \
   --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
%<---
%>' \
   --unchanged-group-format='' \
   old new

Node:Detailed If-then-else, Next:Example If-then-else, Previous:Line Formats, Up:If-then-else

Detailed Description of If-then-else Format

For lines common to both files, diff uses the unchanged line group format. For each hunk of differences in the merged output format, if the hunk contains only lines from the first file, diff uses the old line group format; if the hunk contains only lines from the second file, diff uses the new group format; otherwise, diff uses the changed group format.

The old, new, and unchanged line formats specify the output format of lines from the first file, lines from the second file, and lines common to both files, respectively.

The option --ifdef=name is equivalent to the following sequence of options using shell syntax:

--old-group-format='#ifndef name
%<#endif /* ! name */
' \
--new-group-format='#ifdef name
%>#endif /* name */
' \
--unchanged-group-format='%=' \
--changed-group-format='#ifndef name
%<#else /* name */
%>#endif /* name */
'

You should carefully check the diff output for proper nesting. For example, when using the -D name or --ifdef=name option, you should check that if the differing lines contain any of the C preprocessor directives #ifdef, #ifndef, #else, #elif, or #endif, they are nested properly and match. If they don't, you must make corrections manually. It is a good idea to carefully check the resulting code anyway to make sure that it really does what you want it to; depending on how the input files were produced, the output might contain duplicate or otherwise incorrect code.

The patch -D name option behaves like the diff -D name option, except it operates on a file and a diff to produce a merged file; See patch Options.

Node:Example If-then-else, Previous:Detailed If-then-else, Up:If-then-else

An Example of If-then-else Format

Here is the output of diff -DTWO lao tzu (see Sample diff Input, for the complete contents of the two files):

#ifndef TWO
The Way that can be told of is not the eternal Way;
The name that can be named is not the eternal name.
#endif /* ! TWO */
The Nameless is the origin of Heaven and Earth;
#ifndef TWO
The Named is the mother of all things.
#else /* TWO */
The named is the mother of all things.

#endif /* TWO */
Therefore let there always be non-being,
  so we may see their subtlety,
And let there always be being,
  so we may see their outcome.
The two are the same,
But after they are produced,
  they have different names.
#ifdef TWO
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
#endif /* TWO */

Node:Incomplete Lines, Next:Comparing Directories, Previous:Output Formats, Up:Top

Incomplete Lines

When an input file ends in a non-newline character, its last line is called an incomplete line because its last character is not a newline. All other lines are called full lines and end in a newline character. Incomplete lines do not match full lines unless differences in white space are ignored (see White Space).

An incomplete line is normally distinguished on output from a full line by a following line that starts with \. However, the RCS format (see RCS) outputs the incomplete line as-is, without any trailing newline or following line. The side by side format normally represents incomplete lines as-is, but in some cases uses a \ or / gutter marker; See Side by Side. The if-then-else line format preserves a line's incompleteness with %L, and discards the newline with %l; See Line Formats. Finally, with the ed and forward ed output formats (see Output Formats) diff cannot represent an incomplete line, so it pretends there was a newline and reports an error.

For example, suppose F and G are one-byte files that contain just f and g, respectively. Then diff F G outputs

1c1
< f
\ No newline at end of file
---
> g
\ No newline at end of file

(The exact message may differ in non-English locales.) diff -n F G outputs the following without a trailing newline:

d1 1
a1 1
g

diff -e F G reports two errors and outputs the following:

1c
g
.

Node:Comparing Directories, Next:Adjusting Output, Previous:Incomplete Lines, Up:Top

Comparing Directories

You can use diff to compare some or all of the files in two directory trees. When both file name arguments to diff are directories, it compares each file that is contained in both directories, examining file names in alphabetical order as specified by the LC_COLLATE locale category. Normally diff is silent about pairs of files that contain no differences, but if you use the -s or --report-identical-files option, it reports pairs of identical files. Normally diff reports subdirectories common to both directories without comparing subdirectories' files, but if you use the -r or --recursive option, it compares every corresponding pair of files in the directory trees, as many levels deep as they go.

For file names that are in only one of the directories, diff normally does not show the contents of the file that exists; it reports only that the file exists in that directory and not in the other. You can make diff act as though the file existed but was empty in the other directory, so that it outputs the entire contents of the file that actually exists. (It is output as either an insertion or a deletion, depending on whether it is in the first or the second directory given.) To do this, use the -N or --new-file option.

If the older directory contains one or more large files that are not in the newer directory, you can make the patch smaller by using the --unidirectional-new-file option instead of -N. This option is like -N except that it only inserts the contents of files that appear in the second directory but not the first (that is, files that were added). At the top of the patch, write instructions for the user applying the patch to remove the files that were deleted before applying the patch. See Making Patches, for more discussion of making patches for distribution.

To ignore some files while comparing directories, use the -x pattern or --exclude=pattern option. This option ignores any files or subdirectories whose base names match the shell pattern pattern. Unlike in the shell, a period at the start of the base of a file name matches a wildcard at the start of a pattern. You should enclose pattern in quotes so that the shell does not expand it. For example, the option -x '*.[ao]' ignores any file whose name ends with .a or .o.

This option accumulates if you specify it more than once. For example, using the options -x 'RCS' -x '*,v' ignores any file or subdirectory whose base name is RCS or ends with ,v.

If you need to give this option many times, you can instead put the patterns in a file, one pattern per line, and use the -X file or --exclude-from=file option.

If you have been comparing two directories and stopped partway through, later you might want to continue where you left off. You can do this by using the -S file or --starting-file=file option. This compares only the file file and all alphabetically later files in the topmost directory level.

If two directories differ only in that file names are lower case in one directory and upper case in the upper, diff normally reports many differences because it compares file names in a case sensitive way. With the --ignore-file-name-case option, diff ignores case differences in file names, so that for example the contents of the file Tao in one directory are compared to the contents of the file TAO in the other. The --no-ignore-file-name-case option cancels the effect of the --ignore-file-name-case option, reverting to the default behavior.

If an -x pattern, --exclude=pattern, -X file, or --exclude-from=file option is specified while the --ignore-file-name-case option is in effect, case is ignored when excluding file names matching the specified patterns.

Node:Adjusting Output, Next:diff Performance, Previous:Comparing Directories, Up:Top

Making diff Output Prettier

diff provides several ways to adjust the appearance of its output. These adjustments can be applied to any output format.

  • Tabs: Preserving the alignment of tab stops.
  • Pagination: Page numbering and time-stamping diff output.

Node:Tabs, Next:Pagination, Up:Adjusting Output

Preserving Tab Stop Alignment

The lines of text in some of the diff output formats are preceded by one or two characters that indicate whether the text is inserted, deleted, or changed. The addition of those characters can cause tabs to move to the next tab stop, throwing off the alignment of columns in the line. GNU diff provides two ways to make tab-aligned columns line up correctly.

The first way is to have diff convert all tabs into the correct number of spaces before outputting them; select this method with the -t or --expand-tabs option. diff assumes that tab stops are set every 8 print columns. To use this form of output with patch, you must give patch the -l or --ignore-white-space option (see Changed White Space, for more information).

The other method for making tabs line up correctly is to add a tab character instead of a space after the indicator character at the beginning of the line. This ensures that all following tab characters are in the same position relative to tab stops that they were in the original files, so that the output is aligned correctly. Its disadvantage is that it can make long lines too long to fit on one line of the screen or the paper. It also does not work with the unified output format, which does not have a space character after the change type indicator character. Select this method with the -T or --initial-tab option.

Node:Pagination, Previous:Tabs, Up:Adjusting Output

Paginating diff Output

It can be convenient to have long output page-numbered and time-stamped. The -l and --paginate options do this by sending the diff output through the pr program. Here is what the page header might look like for diff -lc lao tzu:

2002-02-22 14:20                 diff -lc lao tzu                 Page 1

Node:diff Performance, Next:Comparing Three Files, Previous:Adjusting Output, Up:Top

diff Performance Tradeoffs

GNU diff runs quite efficiently; however, in some circumstances you can cause it to run faster or produce a more compact set of changes.

One way to improve diff performance is to use hard or symbolic links to files instead of copies. This improves performance because diff normally does not need to read two hard or symbolic links to the same file, since their contents must be identical. For example, suppose you copy a large directory hierarchy, make a few changes to the copy, and then often use diff -r to compare the original to the copy. If the original files are read-only, you can greatly improve performance by creating the copy using hard or symbolic links (e.g., with GNU cp -lR or cp -sR). Before editing a file in the copy for the first time, you should break the link and replace it with a regular copy.

You can also affect the performance of GNU diff by giving it options that change the way it compares files. Performance has more than one dimension. These options improve one aspect of performance at the cost of another, or they improve performance in some cases while hurting it in others.

The way that GNU diff determines which lines have changed always comes up with a near-minimal set of differences. Usually it is good enough for practical purposes. If the diff output is large, you might want diff to use a modified algorithm that sometimes produces a smaller set of differences. The -d or --minimal option does this; however, it can also cause diff to run more slowly than usual, so it is not the default behavior.

When the files you are comparing are large and have small groups of changes scattered throughout them, you can use the --speed-large-files option to make a different modification to the algorithm that diff uses. If the input files have a constant small density of changes, this option speeds up the comparisons without changing the output. If not, diff might produce a larger set of differences; however, the output will still be correct.

Normally diff discards the prefix and suffix that is common to both files before it attempts to find a minimal set of differences. This makes diff run faster, but occasionally it may produce non-minimal output. The --horizon-lines=lines option prevents diff from discarding the last lines lines of the prefix and the first lines lines of the suffix. This gives diff further opportunities to find a minimal output.

Suppose a run of changed lines includes a sequence of lines at one end and there is an identical sequence of lines just outside the other end. The diff command is free to choose which identical sequence is included in the hunk. In this case, diff normally shifts the hunk's boundaries when this merges adjacent hunks, or shifts a hunk's lines towards the end of the file. Merging hunks can make the output look nicer in some cases.

Node:Comparing Three Files, Next:diff3 Merging, Previous:diff Performance, Up:Top

Comparing Three Files

Use the program diff3 to compare three files and show any differences among them. (diff3 can also merge files; see diff3 Merging).

The "normal" diff3 output format shows each hunk of differences without surrounding context. Hunks are labeled depending on whether they are two-way or three-way, and lines are annotated by their location in the input files.

See Invoking diff3, for more information on how to run diff3.

  • Sample diff3 Input: Sample diff3 input for examples.
  • Detailed diff3 Normal: A detailed description of normal output format.
  • diff3 Hunks: The format of normal output format.
  • Example diff3 Normal: Sample output in the normal format.

Node:Sample diff3 Input, Next:Detailed diff3 Normal, Up:Comparing Three Files

A Third Sample Input File

Here is a third sample file that will be used in examples to illustrate the output of diff3 and how various options can change it. The first two files are the same that we used for diff (see Sample diff Input). This is the third sample file, called tao:

The Way that can be told of is not the eternal Way;
The name that can be named is not the eternal name.
The Nameless is the origin of Heaven and Earth;
The named is the mother of all things.

Therefore let there always be non-being,
  so we may see their subtlety,
And let there always be being,
  so we may see their result.
The two are the same,
But after they are produced,
  they have different names.

  -- The Way of Lao-Tzu, tr. Wing-tsit Chan

Node:Detailed diff3 Normal, Next:diff3 Hunks, Previous:Sample diff3 Input, Up:Comparing Three Files

Detailed Description of diff3 Normal Format

Each hunk begins with a line marked ====. Three-way hunks have plain ==== lines, and two-way hunks have 1, 2, or 3 appended to specify which of the three input files differ in that hunk. The hunks contain copies of two or three sets of input lines each preceded by one or two commands identifying where the lines came from.

Normally, two spaces precede each copy of an input line to distinguish it from the commands. But with the -T or --initial-tab option, diff3 uses a tab instead of two spaces; this lines up tabs correctly. See Tabs, for more information.

Commands take the following forms:

file:la
This hunk appears after line l of file file, and contains no lines in that file. To edit this file to yield the other files, one must append hunk lines taken from the other files. For example, 1:11a means that the hunk follows line 11 in the first file and contains no lines from that file.
file:rc
This hunk contains the lines in the range r of file file. The range r is a comma-separated pair of line numbers, or just one number if the range is a singleton. To edit this file to yield the other files, one must change the specified lines to be the lines taken from the other files. For example, 2:11,13c means that the hunk contains lines 11 through 13 from the second file.

If the last line in a set of input lines is incomplete (see Incomplete Lines), it is distinguished on output from a full line by a following line that starts with \.

Node:diff3 Hunks, Next:Example diff3 Normal, Previous:Detailed diff3 Normal, Up:Comparing Three Files

diff3 Hunks

Groups of lines that differ in two or three of the input files are called diff3 hunks, by analogy with diff hunks (see Hunks). If all three input files differ in a diff3 hunk, the hunk is called a three-way hunk; if just two input files differ, it is a two-way hunk.

As with diff, several solutions are possible. When comparing the files A, B, and C, diff3 normally finds diff3 hunks by merging the two-way hunks output by the two commands diff A B and diff A C. This does not necessarily minimize the size of the output, but exceptions should be rare.

For example, suppose F contains the three lines a, b, f, G contains the lines g, b, g, and H contains the lines a, b, h. diff3 F G H might output the following:

====2
1:1c
3:1c
  a
2:1c
  g
====
1:3c
  f
2:3c
  g
3:3c
  h

because it found a two-way hunk containing a in the first and third files and g in the second file, then the single line b common to all three files, then a three-way hunk containing the last line of each file.

Node:Example diff3 Normal, Previous:diff3 Hunks, Up:Comparing Three Files

An Example of diff3 Normal Format

Here is the output of the command diff3 lao tzu tao (see Sample diff3 Input, for the complete contents of the files). Notice that it shows only the lines that are different among the three files.

====2
1:1,2c
3:1,2c
  The Way that can be told of is not the eternal Way;
  The name that can be named is not the eternal name.
2:0a
====1
1:4c
  The Named is the mother of all things.
2:2,3c
3:4,5c
  The named is the mother of all things.

====3
1:8c
2:7c
    so we may see their outcome.
3:9c
    so we may see their result.
====
1:11a
2:11,13c
  They both may be called deep and profound.
  Deeper and more profound,
  The door of all subtleties!
3:13,14c

    -- The Way of Lao-Tzu, tr. Wing-tsit Chan

Node:diff3 Merging, Next:Interactive Merging, Previous:Comparing Three Files, Up:Top

Merging From a Common Ancestor

When two people have made changes to copies of the same file, diff3 can produce a merged output that contains both sets of changes together with warnings about conflicts.

One might imagine programs with names like diff4 and diff5 to compare more than three files simultaneously, but in practice the need rarely arises. You can use diff3 to merge three or more sets of changes to a file by merging two change sets at a time.

diff3 can incorporate changes from two modified versions into a common preceding version. This lets you merge the sets of changes represented by the two newer files. Specify the common ancestor version as the second argument and the two newer versions as the first and third arguments, like this:

diff3 mine older yours

You can remember the order of the arguments by noting that they are in alphabetical order.

You can think of this as subtracting older from yours and adding the result to mine, or as merging into mine the changes that would turn older into yours. This merging is well-defined as long as mine and older match in the neighborhood of each such change. This fails to be true when all three input files differ or when only older differs; we call this a conflict. When all three input files differ, we call the conflict an overlap.

diff3 gives you several ways to handle overlaps and conflicts. You can omit overlaps or conflicts, or select only overlaps, or mark conflicts with special <<<<<<< and >>>>>>> lines.

diff3 can output the merge results as an ed script that that can be applied to the first file to yield the merged output. However, it is usually better to have diff3 generate the merged output directly; this bypasses some problems with ed.

  • Which Changes: Selecting changes to incorporate.
  • Marking Conflicts: Marking conflicts.
  • Bypassing ed: Generating merged output directly.
  • Merging Incomplete Lines: How diff3 merges incomplete lines.
  • Saving the Changed File: Emulating System V behavior.

Node:Which Changes, Next:Marking Conflicts, Up:diff3 Merging

Selecting Which Changes to Incorporate

You can select all unmerged changes from older to yours for merging into mine with the -e or --ed option. You can select only the nonoverlapping unmerged changes with -3 or --easy-only, and you can select only the overlapping changes with -x or --overlap-only.

The -e, -3 and -x options select only unmerged changes, i.e. changes where mine and yours differ; they ignore changes from older to yours where mine and yours are identical, because they assume that such changes have already been merged. If this assumption is not a safe one, you can use the -A or --show-all option (see Marking Conflicts).

Here is the output of the command diff3 with each of these three options (see Sample diff3 Input, for the complete contents of the files). Notice that -e outputs the union of the disjoint sets of changes output by -3 and -x.

Output of diff3 -e lao tzu tao:

11a

  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
.
8c
  so we may see their result.
.

Output of diff3 -3 lao tzu tao:

8c
  so we may see their result.
.

Output of diff3 -x lao tzu tao:

11a

  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
.

Node:Marking Conflicts, Next:Bypassing ed, Previous:Which Changes, Up:diff3 Merging

Marking Conflicts

diff3 can mark conflicts in the merged output by bracketing them with special marker lines. A conflict that comes from two files A and B is marked as follows:

<<<<<<< A
lines from A
=======
lines from B
>>>>>>> B

A conflict that comes from three files A, B and C is marked as follows:

<<<<<<< A
lines from A
||||||| B
lines from B
=======
lines from C
>>>>>>> C

The -A or --show-all option acts like the -e option, except that it brackets conflicts, and it outputs all changes from older to yours, not just the unmerged changes. Thus, given the sample input files (see Sample diff3 Input), diff3 -A lao tzu tao puts brackets around the conflict where only tzu differs:

<<<<<<< tzu
=======
The Way that can be told of is not the eternal Way;
The name that can be named is not the eternal name.
>>>>>>> tao

And it outputs the three-way conflict as follows:

<<<<<<< lao
||||||| tzu
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
=======

  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
>>>>>>> tao

The -E or --show-overlap option outputs less information than the -A or --show-all option, because it outputs only unmerged changes, and it never outputs the contents of the second file. Thus the -E option acts like the -e option, except that it brackets the first and third files from three-way overlapping changes. Similarly, -X acts like -x, except it brackets all its (necessarily overlapping) changes. For example, for the three-way overlapping change above, the -E and -X options output the following:

<<<<<<< lao
=======

  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
>>>>>>> tao

If you are comparing files that have meaningless or uninformative names, you can use the -L label or --label=label option to show alternate names in the <<<<<<<, ||||||| and >>>>>>> brackets. This option can be given up to three times, once for each input file. Thus diff3 -A -L X -L Y -L Z A B C acts like diff3 -A A B C, except that the output looks like it came from files named X, Y and Z rather than from files named A, B and C.

Node:Bypassing ed, Next:Merging Incomplete Lines, Previous:Marking Conflicts, Up:diff3 Merging

Generating the Merged Output Directly

With the -m or --merge option, diff3 outputs the merged file directly. This is more efficient than using ed to generate it, and works even with non-text files that ed would reject. If you specify -m without an ed script option, -A (--show-all) is assumed.

For example, the command diff3 -m lao tzu tao (see Sample diff3 Input for a copy of the input files) would output the following:

<<<<<<< tzu
=======
The Way that can be told of is not the eternal Way;
The name that can be named is not the eternal name.
>>>>>>> tao
The Nameless is the origin of Heaven and Earth;
The Named is the mother of all things.
Therefore let there always be non-being,
  so we may see their subtlety,
And let there always be being,
  so we may see their result.
The two are the same,
But after they are produced,
  they have different names.
<<<<<<< lao
||||||| tzu
They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!
=======

  -- The Way of Lao-Tzu, tr. Wing-tsit Chan
>>>>>>> tao

Node:Merging Incomplete Lines, Next:Saving the Changed File, Previous:Bypassing ed, Up:diff3 Merging

How diff3 Merges Incomplete Lines

With -m, incomplete lines (see Incomplete Lines) are simply copied to the output as they are found; if the merged output ends in an conflict and one of the input files ends in an incomplete line, succeeding |||||||, ======= or >>>>>>> brackets appear somewhere other than the start of a line because they are appended to the incomplete line.

Without -m, if an ed script option is specified and an incomplete line is found, diff3 generates a warning and acts as if a newline had been present.

Node:Saving the Changed File, Previous:Merging Incomplete Lines, Up:diff3 Merging

Saving the Changed File

Traditional Unix diff3 generates an ed script without the trailing w and q commands that save the changes. System V diff3 generates these extra commands. GNU diff3 normally behaves like traditional Unix diff3, but with the -i option it behaves like System V diff3 and appends the w and q commands.

The -i option requires one of the ed script options -AeExX3, and is incompatible with the merged output option -m.

Node:Interactive Merging, Next:Merging with patch, Previous:diff3 Merging, Up:Top

Interactive Merging with sdiff

With sdiff, you can merge two files interactively based on a side-by-side -y format comparison (see Side by Side). Use -o file or --output=file to specify where to put the merged text. See Invoking sdiff, for more details on the options to sdiff.

Another way to merge files interactively is to use the Emacs Lisp package emerge. See emerge, for more information.

  • sdiff Option Summary: Summary of sdiff options.
  • Merge Commands: Merging two files interactively.

Node:sdiff Option Summary, Next:Merge Commands, Up:Interactive Merging

Specifying diff Options to sdiff

The following sdiff options have the same meaning as for diff. See diff Options, for the use of these options.

-a -b -d -i -t -v
-B -E -I regexp

--ignore-blank-lines  --ignore-case
--ignore-matching-lines=regexp  --ignore-space-change
--ignore-tab-expansion
--left-column  --minimal  --speed-large-files
--strip-trailing-cr  --suppress-common-lines  --expand-tabs
--text  --version  --width=columns

For historical reasons, sdiff has alternate names for some options. The -l option is equivalent to the --left-column option, and similarly -s is equivalent to --suppress-common-lines. The meaning of the sdiff -w and -W options is interchanged from that of diff: with sdiff, -w columns is equivalent to --width=columns, and -W is equivalent to --ignore-all-space. sdiff without the -o option is equivalent to diff with the -y or --side-by-side option (see Side by Side).

Node:Merge Commands, Previous:sdiff Option Summary, Up:Interactive Merging

Merge Commands

Groups of common lines, with a blank gutter, are copied from the first file to the output. After each group of differing lines, sdiff prompts with % and pauses, waiting for one of the following commands. Follow each command with <RET>.

e
Discard both versions. Invoke a text editor on an empty temporary file, then copy the resulting file to the output.
eb
Concatenate the two versions, edit the result in a temporary file, then copy the edited result to the output.
ed
Like eb, except precede each version with a header that shows what file and lines the version came from.
el
Edit a copy of the left version, then copy the result to the output.
er
Edit a copy of the right version, then copy the result to the output.
l
Copy the left version to the output.
q
Quit.
r
Copy the right version to the output.
s
Silently copy common lines.
v
Verbosely copy common lines. This is the default.

The text editor invoked is specified by the EDITOR environment variable if it is set. The default is system-dependent.

Node:Merging with patch, Next:Making Patches, Previous:Interactive Merging, Up:Top

Merging with patch

patch takes comparison output produced by diff and applies the differences to a copy of the original file, producing a patched version. With patch, you can distribute just the changes to a set of files instead of distributing the entire file set; your correspondents can apply patch to update their copy of the files with your changes. patch automatically determines the diff format, skips any leading or trailing headers, and uses the headers to determine which file to patch. This lets your correspondents feed a mail message containing a difference listing directly to patch.

patch detects and warns about common problems like forward patches. It saves any patches that it could not apply. It can also maintain a patchlevel.h file to ensure that your correspondents apply diffs in the proper order.

patch accepts a series of diffs in its standard input, usually separated by headers that specify which file to patch. It applies diff hunks (see Hunks) one by one. If a hunk does not exactly match the original file, patch uses heuristics to try to patch the file as well as it can. If no approximate match can be found, patch rejects the hunk and skips to the next hunk. patch normally replaces each file f with its new version, putting reject hunks (if any) into f.rej.

See Invoking patch, for detailed information on the options to patch.

  • patch Input: Selecting the type of patch input.
  • Revision Control: Getting files from RCS, SCCS, etc.
  • Imperfect: Dealing with imperfect patches.
  • Creating and Removing: Creating and removing files with a patch.
  • Patching Time Stamps: Updating time stamps on patched files.
  • Multiple Patches: Handling multiple patches in a file.
  • patch Directories: Changing directory and stripping directories.
  • Backups: Whether backup files are made.
  • Backup Names: Backup file names.
  • Reject Names: Reject file names.
  • patch Messages: Messages and questions patch can produce.
  • patch and POSIX: Conformance to the POSIX standard.
  • patch and Tradition: GNU versus traditional patch.

Node:patch Input, Next:Revision Control, Up:Merging with patch

Selecting the patch Input Format

patch normally determines which diff format the patch file uses by examining its contents. For patch files that contain particularly confusing leading text, you might need to use one of the following options to force patch to interpret the patch file as a certain format of diff. The output formats listed here are the only ones that patch can understand.

-c
--context
context diff.
-e
--ed
ed script.
-n
--normal
normal diff.
-u
--unified
unified diff.

Node:Revision Control, Next:Imperfect, Previous:patch Input, Up:Merging with patch

Revision Control

If a nonexistent input file is under a revision control system supported by patch, patch normally asks the user whether to get (or check out) the file from the revision control system. Patch currently supports RCS, ClearCase and SCCS. Under RCS and SCCS, patch also asks when the input file is read-only and matches the default version in the revision control system.

The -g num or --get=num affects access to files under supported revision control systems. If num is positive, patch gets the file without asking the user; if zero, patch neither asks the user nor gets the file; and if negative, patch asks the user before getting the file. The default value of num is given by the value of the PATCH_GET environment variable if it is set; if not, the default value is zero if patch is conforming to POSIX, negative otherwise. See patch and POSIX.

The choice of revision control system is unaffected by the VERSION_CONTROL environment variable (see Backup Names).

Node:Imperfect, Next:Creating and Removing, Previous:Revision Control, Up:Merging with patch

Applying Imperfect Patches

patch tries to skip any leading text in the patch file, apply the diff, and then skip any trailing text. Thus you can feed a mail message directly to patch, and it should work. If the entire diff is indented by a constant amount of white space, patch automatically ignores the indentation. If a context diff contains trailing carriage return on each line, patch automatically ignores the carriage return. If a context diff has been encapsulated by prepending -  to lines beginning with - as per Internet RFC 934, patch automatically unencapsulates the input.

However, certain other types of imperfect input require user intervention or testing.

  • Changed White Space: When tabs and spaces don't match exactly.
  • Reversed Patches: Applying reversed patches correctly.
  • Inexact: Helping patch find close matches.
  • Dry Runs: Predicting what patch will do.

Node:Changed White Space, Next:Reversed Patches, Up:Imperfect

Applying Patches with Changed White Space

Sometimes mailers, editors, or other programs change spaces into tabs, or vice versa. If this happens to a patch file or an input file, the files might look the same, but patch will not be able to match them properly. If this problem occurs, use the -l or --ignore-white-space option, which makes patch compare blank characters (i.e. spaces and tabs) loosely so that any nonempty sequence of blanks in the patch file matches any nonempty sequence of blanks in the input files. Non-blank characters must still match exactly. Each line of the context must still match a line in the input file.

Node:Reversed Patches, Next:Inexact, Previous:Changed White Space, Up:Imperfect

Applying Reversed Patches

Sometimes people run diff with the new file first instead of second. This creates a diff that is "reversed". To apply such patches, give patch the -R or --reverse option. patch then attempts to swap each hunk around before applying it. Rejects come out in the swapped format.

Often patch can guess that the patch is reversed. If the first hunk of a patch fails, patch reverses the hunk to see if it can apply it that way. If it can, patch asks you if you want to have the -R option set; if it can't, patch continues to apply the patch normally. This method cannot detect a reversed patch if it is a normal diff and the first command is an append (which should have been a delete) since appends always succeed, because a null context matches anywhere. But most patches add or change lines rather than delete them, so most reversed normal diffs begin with a delete, which fails, and patch notices.

If you apply a patch that you have already applied, patch thinks it is a reversed patch and offers to un-apply the patch. This could be construed as a feature. If you did this inadvertently and you don't want to un-apply the patch, just answer n to this offer and to the subsequent "apply anyway" question--or type C-c to kill the patch process.

Node:Inexact, Next:Dry Runs, Previous:Reversed Patches, Up:Imperfect

Helping patch Find Inexact Matches

For context diffs, and to a lesser extent normal diffs, patch can detect when the line numbers mentioned in the patch are incorrect, and it attempts to find the correct place to apply each hunk of the patch. As a first guess, it takes the line number mentioned in the hunk, plus or minus any offset used in applying the previous hunk. If that is not the correct place, patch scans both forward and backward for a set of lines matching the context given in the hunk.

First patch looks for a place where all lines of the context match. If it cannot find such a place, and it is reading a context or unified diff, and the maximum fuzz factor is set to 1 or more, then patch makes another scan, ignoring the first and last line of context. If that fails, and the maximum fuzz factor is set to 2 or more, it makes another scan, ignoring the first two and last two lines of context are ignored. It continues similarly if the maximum fuzz factor is larger.

The -F lines or --fuzz=lines option sets the maximum fuzz factor to lines. This option only applies to context and unified diffs; it ignores up to lines lines while looking for the place to install a hunk. Note that a larger fuzz factor increases the odds of making a faulty patch. The default fuzz factor is 2; there is no point to setting it to more than the number of lines of context in the diff, ordinarily 3.

If patch cannot find a place to install a hunk of the patch, it writes the hunk out to a reject file (see Reject Names, for information on how reject files are named). It writes out rejected hunks in context format no matter what form the input patch is in. If the input is a normal or ed diff, many of the contexts are simply null. The line numbers on the hunks in the reject file may be different from those in the patch file: they show the approximate location where patch thinks the failed hunks belong in the new file rather than in the old one.

If the --verbose option is given, then as it completes each hunk patch tells you whether the hunk succeeded or failed, and if it failed, on which line (in the new file) patch thinks the hunk should go. If this is different from the line number specified in the diff, it tells you the offset. A single large offset may indicate that patch installed a hunk in the wrong place. patch also tells you if it used a fuzz factor to make the match, in which case you should also be slightly suspicious.

patch cannot tell if the line numbers are off in an ed script, and can only detect wrong line numbers in a normal diff when it finds a change or delete command. It may have the same problem with a context diff using a fuzz factor equal to or greater than the number of lines of context shown in the diff (typically 3). In these cases, you should probably look at a context diff between your original and patched input files to see if the changes make sense. Compiling without errors is a pretty good indication that the patch worked, but not a guarantee.

A patch against an empty file applies to a nonexistent file, and vice versa. See Creating and Removing.

patch usually produces the correct results, even when it must make many guesses. However, the results are guaranteed only when the patch is applied to an exact copy of the file that the patch was generated from.

Node:Dry Runs, Previous:Inexact, Up:Imperfect

Predicting what patch will do

It may not be obvious in advance what patch will do with a complicated or poorly formatted patch. If you are concerned that the input might cause patch to modify the wrong files, you can use the --dry-run option, which causes patch to print the results of applying patches without actually changing any files. You can then inspect the diagnostics generated by the dry run to see whether patch will modify the files that you expect. If the patch does not do what you want, you can modify the patch (or the other options to patch) and try another dry run. Once you are satisfied with the proposed patch you can apply it by invoking patch as before, but this time without the --dry-run option.

Node:Creating and Removing, Next:Patching Time Stamps, Previous:Imperfect, Up:Merging with patch

Creating and Removing Files

Sometimes when comparing two directories, a file may exist in one directory but not the other. If you give diff the -N or --new-file option, or if you supply an old or new file that is named /dev/null or is empty and is dated the Epoch (1970-01-01 00:00:00 UTC), diff outputs a patch that adds or deletes the contents of this file. When given such a patch, patch normally creates a new file or removes the old file. However, when conforming to POSIX (see patch and POSIX), patch does not remove the old file, but leaves it empty. The -E or --remove-empty-files option causes patch to remove output files that are empty after applying a patch, even if the patch does not appear to be one that removed the file.

If the patch appears to create a file that already exists, patch asks for confirmation before applying the patch.

Node:Patching Time Stamps, Next:Multiple Patches, Previous:Creating and Removing, Up:Merging with patch

Updating Time Stamps on Patched Files

When patch updates a file, it normally sets the file's last-modified time stamp to the current time of day. If you are using patch to track a software distribution, this can cause make to incorrectly conclude that a patched file is out of date. For example, if syntax.c depends on syntax.y, and patch updates syntax.c and then syntax.y, then syntax.c will normally appear to be out of date with respect to syntax.y even though its contents are actually up to date.

The -Z or --set-utc option causes patch to set a patched file's modification and access times to the time stamps given in context diff headers. If the context diff headers do not specify a time zone, they are assumed to use Coordinated Universal Time (UTC, often known as GMT).

The -T or --set-time option acts like -Z or --set-utc, except that it assumes that the context diff headers' time stamps use local time instead of UTC. This option is not recommended, because patches using local time cannot easily be used by people in other time zones, and because local time stamps are ambiguous when local clocks move backwards during daylight-saving time adjustments. If the context diff headers specify a time zone, this option is equivalent to -Z or --set-utc.

patch normally refrains from setting a file's time stamps if the file's original last-modified time stamp does not match the time given in the diff header, of if the file's contents do not exactly match the patch. However, if the -f or --force option is given, the file's time stamps are set regardless.

Due to the limitations of the current diff format, patch cannot update the times of files whose contents have not changed. Also, if you set file time stamps to values other than the current time of day, you should also remove (e.g., with make clean) all files that depend on the patched files, so that later invocations of make do not get confused by the patched files' times.

Node:Multiple Patches, Next:patch Directories, Previous:Patching Time Stamps, Up:Merging with patch

Multiple Patches in a File

If the patch file contains more than one patch, and if you do not specify an input file on the command line, patch tries to apply each patch as if they came from separate patch files. This means that it determines the name of the file to patch for each patch, and that it examines the leading text before each patch for file names and prerequisite revision level (see Making Patches, for more on that topic).

patch uses the following rules to intuit a file name from the leading text before a patch. First, patch takes an ordered list of candidate file names as follows:

  • If the header is that of a context diff, patch takes the old and new file names in the header. A name is ignored if it does not have enough slashes to satisfy the -pnum or --strip=num option. The name /dev/null is also ignored.
  • If there is an Index: line in the leading garbage and if either the old and new names are both absent or if patch is conforming to POSIX, patch takes the name in the Index: line.
  • For the purpose of the following rules, the candidate file names are considered to be in the order (old, new, index), regardless of the order that they appear in the header.

Then patch selects a file name from the candidate list as follows:

  • If some of the named files exist, patch selects the first name if conforming to POSIX, and the best name otherwise.
  • If patch is not ignoring RCS, ClearCase, and SCCS (see Revision Control), and no named files exist but an RCS, ClearCase, or SCCS master is found, patch selects the first named file with an RCS, ClearCase, or SCCS master.
  • If no named files exist, no RCS, ClearCase, or SCCS master was found, some names are given, patch is not conforming to POSIX, and the patch appears to create a file, patch selects the best name requiring the creation of the fewest directories.
  • If no file name results from the above heuristics, you are asked for the name of the file to patch, and patch selects that name.

To determine the best of a nonempty list of file names, patch first takes all the names with the fewest path name components; of those, it then takes all the names with the shortest basename; of those, it then takes all the shortest names; finally, it takes the first remaining name.

See patch and POSIX, to see whether patch is conforming to POSIX.

Node:patch Directories, Next:Backups, Previous:Multiple Patches, Up:Merging with patch

Applying Patches in Other Directories

The -d directory or --directory=directory option to patch makes directory directory the current directory for interpreting both file names in the patch file, and file names given as arguments to other options (such as -B and -o). For example, while in a mail reading program, you can patch a file in the /usr/src/emacs directory directly from a message containing the patch like this:

| patch -d /usr/src/emacs

Sometimes the file names given in a patch contain leading directories, but you keep your files in a directory different from the one given in the patch. In those cases, you can use the -pnumber or --strip=number option to set the file name strip count to number. The strip count tells patch how many slashes, along with the directory names between them, to strip from the front of file names. A sequence of one or more adjacent slashes is counted as a single slash. By default, patch strips off all leading directories, leaving just the base file names.

For example, suppose the file name in the patch file is /gnu/src/emacs/etc/NEWS. Using -p0 gives the entire file name unmodified, -p1 gives gnu/src/emacs/etc/NEWS (no leading slash), -p4 gives etc/NEWS, and not specifying -p at all gives NEWS.

patch looks for each file (after any slashes have been stripped) in the current directory, or if you used the -d directory option, in that directory.

Node:Backups, Next:Backup Names, Previous:patch Directories, Up:Merging with patch

Backup Files

Normally, patch creates a backup file if the patch does not exactly match the original input file, because in that case the original data might not be recovered if you undo the patch with patch -R (see Reversed Patches). However, when conforming to POSIX, patch does not create backup files by default. See patch and POSIX.

The -b or --backup option causes patch to make a backup file regardless of whether the patch matches the original input. The --backup-if-mismatch option causes patch to create backup files for mismatches files; this is the default when not conforming to POSIX. The --no-backup-if-mismatch option causes patch to not create backup files, even for mismatched patches; this is the default when conforming to POSIX.

When backing up a file that does not exist, an empty, unreadable backup file is created as a placeholder to represent the nonexistent file.

Node:Backup Names, Next:Reject Names, Previous:Backups, Up:Merging with patch

Backup File Names

Normally, patch renames an original input file into a backup file by appending to its name the extension .orig, or ~ if using .orig would make the backup file name too long.1 The -z backup-suffix or --suffix=backup-suffix option causes patch to use backup-suffix as the backup extension instead.

Alternately, you can specify the extension for backup files with the SIMPLE_BACKUP_SUFFIX environment variable, which the options override.

patch can also create numbered backup files the way GNU Emacs does. With this method, instead of having a single backup of each file, patch makes a new backup file name each time it patches a file. For example, the backups of a file named sink would be called, successively, sink.~1~, sink.~2~, sink.~3~, etc.

The -V backup-style or --version-control=backup-style option takes as an argument a method for creating backup file names. You can alternately control the type of backups that patch makes with the PATCH_VERSION_CONTROL environment variable, which the -V option overrides. If PATCH_VERSION_CONTROL is not set, the VERSION_CONTROL environment variable is used instead. Please note that these options and variables control backup file names; they do not affect the choice of revision control system (see Revision Control).

The values of these environment variables and the argument to the -V option are like the GNU Emacs version-control variable (see Backup Names, for more information on backup versions in Emacs). They also recognize synonyms that are more descriptive. The valid values are listed below; unique abbreviations are acceptable.

t
numbered
Always make numbered backups.
nil
existing
Make numbered backups of files that already have them, simple backups of the others. This is the default.
never
simple
Always make simple backups.

You can also tell patch to prepend a prefix, such as a directory name, to produce backup file names. The -B prefix or --prefix=prefix option makes backup files by prepending prefix to them. The -Y prefix or --basename-prefix=prefix prepends prefix to the last file name component of backup file names instead; for example, -Y ~ causes the backup name for dir/file.c to be dir/~file.c. If you use either of these prefix options, the suffix-based options are ignored.

If you specify the output file with the -o option, that file is the one that is backed up, not the input file.

Options that affect the names of backup files do not affect whether backups are made. For example, if you specify the --no-backup-if-mismatch option, none of the options described in this section have any affect, because no backups are made.

Node:Reject Names, Next:patch Messages, Previous:Backup Names, Up:Merging with patch

Reject File Names

The names for reject files (files containing patches that patch could not find a place to apply) are normally the name of the output file with .rej appended (or # if if using .rej would make the backup file name too long).

Alternatively, you can tell patch to place all of the rejected patches in a single file. The -r reject-file or --reject-file=reject-file option uses reject-file as the reject file name.

Node:patch Messages, Next:patch and POSIX, Previous:Reject Names, Up:Merging with patch

Messages and Questions from patch

patch can produce a variety of messages, especially if it has trouble decoding its input. In a few situations where it's not sure how to proceed, patch normally prompts you for more information from the keyboard. There are options to produce more or fewer messages, to have it not ask for keyboard input, and to affect the way that file names are quoted in messages.

  • More or Fewer Messages: Controlling the verbosity of patch.
  • patch and Keyboard Input: Inhibiting keyboard input.
  • patch Quoting Style: Quoting file names in diagnostics.

patch exits with status 0 if all hunks are applied successfully, 1 if some hunks cannot be applied, and 2 if there is more serious trouble. When applying a set of patches in a loop, you should check the exit status, so you don't apply a later patch to a partially patched file.

Node:More or Fewer Messages, Next:patch and Keyboard Input, Up:patch Messages

Controlling the Verbosity of patch

You can cause patch to produce more messages by using the --verbose option. For example, when you give this option, the message Hmm... indicates that patch is reading text in the patch file, attempting to determine whether there is a patch in that text, and if so, what kind of patch it is.

You can inhibit all terminal output from patch, unless an error occurs, by using the -s, --quiet, or --silent option.

Node:patch and Keyboard Input, Next:patch Quoting Style, Previous:More or Fewer Messages, Up:patch Messages

Inhibiting Keyboard Input

There are two ways you can prevent patch from asking you any questions. The -f or --force option assumes that you know what you are doing. It causes patch to do the following:

  • Skip patches that do not contain file names in their headers.
  • Patch files even though they have the wrong version for the Prereq: line in the patch;
  • Assume that patches are not reversed even if they look like they are.

The -t or --batch option is similar to -f, in that it suppresses questions, but it makes somewhat different assumptions:

  • Skip patches that do not contain file names in their headers (the same as -f).
  • Skip patches for which the file has the wrong version for the Prereq: line in the patch;
  • Assume that patches are reversed if they look like they are.

Node:patch Quoting Style, Previous:patch and Keyboard Input, Up:patch Messages

patch Quoting Style

When patch outputs a file name in a diagnostic message, it can format the name in any of several ways. This can be useful to output file names unambiguously, even if they contain punctuation or special characters like newlines. The --quoting-style=word option controls how names are output. The word should be one of the following:

literal
Output names as-is.
shell
Quote names for the shell if they contain shell metacharacters or would cause ambiguous output.
shell-always
Quote names for the shell, even if they would normally not require quoting.
c
Quote names as for a C language string.
escape
Quote as with c except omit the surrounding double-quote characters.

You can specify the default value of the --quoting-style option with the environment variable QUOTING_STYLE. If that environment variable is not set, the default value is shell, but this default may change in a future version of patch.

Node:patch and POSIX, Next:patch and Tradition, Previous:patch Messages, Up:Merging with patch

patch and the POSIX Standard

If you specify the --posix option, or set the POSIXLY_CORRECT environment variable, patch conforms more strictly to the POSIX standard, as follows:

  • Take the first existing file from the list (old, new, index) when intuiting file names from diff headers. See Multiple Patches.
  • Do not remove files that are removed by a diff. See Creating and Removing.
  • Do not ask whether to get files from RCS, ClearCase, or SCCS. See Revision Control.
  • Require that all options precede the files in the command line.
  • Do not backup files, even when there is a mismatch. See Backups.

Node:patch and Tradition, Previous:patch and POSIX, Up:Merging with patch

GNU patch and Traditional patch

The current version of GNU patch normally follows the POSIX standard. See patch and POSIX, for the few exceptions to this general rule.

Unfortunately, POSIX redefined the behavior of patch in several important ways. You should be aware of the following differences if you must interoperate with traditional patch, or with GNU patch version 2.1 and earlier.

  • In traditional patch, the -p option's operand was optional, and a bare -p was equivalent to -p0. The -p option now requires an operand, and -p 0 is now equivalent to -p0. For maximum compatibility, use options like -p0 and -p1.

    Also, traditional patch simply counted slashes when stripping path prefixes; patch now counts pathname components. That is, a sequence of one or more adjacent slashes now counts as a single slash. For maximum portability, avoid sending patches containing // in file names.

  • In traditional patch, backups were enabled by default. This behavior is now enabled with the -b or --backup option.

    Conversely, in POSIX patch, backups are never made, even when there is a mismatch. In GNU patch, this behavior is enabled with the --no-backup-if-mismatch option, or by conforming to POSIX.

    The -b suffix option of traditional patch is equivalent to the -b -z suffix options of GNU patch.

  • Traditional patch used a complicated (and incompletely documented) method to intuit the name of the file to be patched from the patch header. This method did not conform to POSIX, and had a few gotchas. Now patch uses a different, equally complicated (but better documented) method that is optionally POSIX-conforming; we hope it has fewer gotchas. The two methods are compatible if the file names in the context diff header and the Index: line are all identical after prefix-stripping. Your patch is normally compatible if each header's file names all contain the same number of slashes.
  • When traditional patch asked the user a question, it sent the question to standard error and looked for an answer from the first file in the following list that was a terminal: standard error, standard output, /dev/tty, and standard input. Now patch sends questions to standard output and gets answers from /dev/tty. Defaults for some answers have been changed so that patch never goes into an infinite loop when using default answers.
  • Traditional patch exited with a status value that counted the number of bad hunks, or with status 1 if there was real trouble. Now patch exits with status 1 if some hunks failed, or with 2 if there was real trouble.
  • Limit yourself to the following options when sending instructions meant to be executed by anyone running GNU patch, traditional patch, or a patch that conforms to POSIX. Spaces are significant in the following list, and operands are required.
    -c
-d dir
-D define
-e
-l
-n
-N
-o outfile
-pnum
-R
-r rejectfile

Node:Making Patches, Next:Invoking cmp, Previous:Merging with patch, Up:Top

Tips for Making and Using Patches

Use some common sense when making and using patches. For example, when sending bug fixes to a program's maintainer, send several small patches, one per independent subject, instead of one large, harder-to-digest patch that covers all the subjects.

Here are some other things you should keep in mind if you are going to distribute patches for updating a software package.

  • Tips for Patch Producers: Advice for making patches.
  • Tips for Patch Consumers: Advice for using patches.
  • Avoiding Common Mistakes: Avoiding common mistakes when using patch.
  • Generating Smaller Patches: How to generate smaller patches.

Node:Tips for Patch Producers, Next:Tips for Patch Consumers, Up:Making Patches

Tips for Patch Producers

To create a patch that changes an older version of a package into a newer version, first make a copy of the older and newer versions in adjacent subdirectories. It is common to do that by unpacking tar archives of the two versions.

To generate the patch, use the command diff -Naur old new where old and new identify the old and new directories. The names old and new should not contain any slashes. The -N option lets the patch create and remove files; -a lets the patch update non-text files; -u generates useful time stamps and enough context; and -r lets the patch update subdirectories. Here is an example command, using Bourne shell syntax:

diff -Naur gcc-3.0.3 gcc-3.0.4

Tell your recipients how to apply the patches. This should include which working directory to use, and which patch options to use; the option -p1 is recommended. Test your procedure by pretending to be a recipient and applying your patches to a copy of the original files.

See Avoiding Common Mistakes, for how to avoid common mistakes when generating a patch.

Node:Tips for Patch Consumers, Next:Avoiding Common Mistakes, Previous:Tips for Patch Producers, Up:Making Patches

Tips for Patch Consumers

A patch producer should tell recipients how to apply the patches, so the first rule of thumb for a patch consumer is to follow the instructions supplied with the patch.

GNU diff can analyze files with arbitrarily long lines and files that end in incomplete lines. However, older versions of patch cannot patch such files. If you are having trouble applying such patches, try upgrading to a recent version of GNU patch.

Node:Avoiding Common Mistakes, Next:Generating Smaller Patches, Previous:Tips for Patch Consumers, Up:Making Patches

Avoiding Common Mistakes

When producing a patch for multiple files, apply diff to directories whose names do not have slashes. This reduces confusion when the patch consumer specifies the -pnumber option, since this option can have surprising results when the old and new file names have different numbers of slashes. For example, do not send a patch with a header that looks like this:

diff -Naur v2.0.29/prog/README prog/README
--- v2.0.29/prog/README	2002-03-10 23:30:39.942229878 -0800
+++ prog/README	2002-03-17 20:49:32.442260588 -0800

because the two file names have different numbers of slashes, and different versions of patch interpret the file names differently. To avoid confusion, send output that looks like this instead:

diff -Naur v2.0.29/prog/README v2.0.30/prog/README
--- v2.0.29/prog/README	2002-03-10 23:30:39.942229878 -0800
+++ v2.0.30/prog/README	2002-03-17 20:49:32.442260588 -0800

Make sure you have specified the file names correctly, either in a context diff header or with an Index: line. Take care to not send out reversed patches, since these make people wonder whether they have already applied the patch.

Avoid sending patches that compare backup file names like README.orig or README~, since this might confuse patch into patching a backup file instead of the real file. Instead, send patches that compare the same base file names in different directories, e.g. old/README and new/README.

To save people from partially applying a patch before other patches that should have gone before it, you can make the first patch in the patch file update a file with a name like patchlevel.h or version.c, which contains a patch level or version number. If the input file contains the wrong version number, patch will complain immediately.

An even clearer way to prevent this problem is to put a Prereq: line before the patch. If the leading text in the patch file contains a line that starts with Prereq:, patch takes the next word from that line (normally a version number) and checks whether the next input file contains that word, preceded and followed by either white space or a newline. If not, patch prompts you for confirmation before proceeding. This makes it difficult to accidentally apply patches in the wrong order.

Node:Generating Smaller Patches, Previous:Avoiding Common Mistakes, Up:Making Patches

Generating Smaller Patches

The simplest way to generate a patch is to use diff -Naur (see Tips for Patch Producers), but you might be able to reduce the size of the patch by renaming or removing some files before making the patch. If the older version of the package contains any files that the newer version does not, or if any files have been renamed between the two versions, make a list of rm and mv commands for the user to execute in the old version directory before applying the patch. Then run those commands yourself in the scratch directory.

If there are any files that you don't need to include in the patch because they can easily be rebuilt from other files (for example, TAGS and output from yacc and makeinfo), exclude them from the patch by giving diff the -x pattern option (see Comparing Directories). If you want your patch to modify a derived file because your recipients lack tools to build it, make sure that the patch for the derived file follows any patches for files that it depends on, so that the recipients' time stamps will not confuse make.

Now you can create the patch using diff -Naur. Make sure to specify the scratch directory first and the newer directory second.

Add to the top of the patch a note telling the user any rm and mv commands to run before applying the patch. Then you can remove the scratch directory.

You can also shrink the patch size by using fewer lines of context, but bear in mind that patch typically needs at least two lines for proper operation when patches do not exactly match the input files.

Node:Invoking cmp, Next:Invoking diff, Previous:Making Patches, Up:Top

Invoking cmp

The cmp command compares two files, and if they differ, tells the first byte and line number where they differ. Bytes and lines are numbered starting with 1. The arguments of cmp are as follows:

cmp options... from-file [to-file [from-skip [to-skip]]]

The file name - is always the standard input. cmp also uses the standard input if one file name is omitted. The from-skip and to-skip operands specify how many bytes to ignore at the start of each file; they are equivalent to the --ignore-initial=from-skip:to-skip option.

An exit status of 0 means no differences were found, 1 means some differences were found, and 2 means trouble.

  • cmp Options: Summary of options to cmp.

Node:cmp Options, Up:Invoking cmp

Options to cmp

Below is a summary of all of the options that GNU cmp accepts. Most options have two equivalent names, one of which is a single letter preceded by -, and the other of which is a long name preceded by --. Multiple single letter options (unless they take an argument) can be combined into a single command line word: -bl is equivalent to -b -l.

-b
--print-bytes
Print the differing bytes. Display control bytes as a ^ followed by a letter of the alphabet and precede bytes that have the high bit set with M- (which stands for "meta").
--help
Output a summary of usage and then exit.
-i skip
--ignore-initial=skip
Ignore any differences in the first skip bytes of the input files. Treat files with fewer than skip bytes as if they are empty. If skip is of the form from-skip:to-skip, skip the first from-skip bytes of the first input file and the first to-skip bytes of the second.
-l
--verbose
Print the (decimal) byte numbers and (octal) values of all differing bytes.
-n count
--bytes=count
Compare at most count input bytes.
-s
--quiet
--silent
Do not print anything; only return an exit status indicating whether the files differ.
-v
--version
Output version information and then exit.

In the above table, operands that are byte counts are normally decimal, but may be preceded by 0 for octal and 0x for hexadecimal.

A byte count can be followed by a suffix to specify a multiple of that count; in this case an omitted integer is understood to be 1. A bare size letter, or one followed by iB, specifies a multiple using powers of 1024. A size letter followed by B specifies powers of 1000 instead. For example, -n 4M and -n 4MiB are equivalent to -n 4194304, whereas -n 4MB is equivalent to -n 4000000. This notation is upward compatible with the SI prefixes for decimal multiples and with the IEC 60027-2 prefixes for binary multiples.

The following suffixes are defined. Large sizes like 1Y may be rejected by your computer due to limitations of its arithmetic.

kB
kilobyte: 10^3 = 1000.
k
K
KiB
kibibyte: 2^10 = 1024. K is special: the SI prefix is k and the IEC 60027-2 prefix is Ki, but tradition and POSIX use k to mean KiB.
MB
megabyte: 10^6 = 1,000,000.
M
MiB
mebibyte: 2^20 = 1,048,576.
GB
gigabyte: 10^9 = 1,000,000,000.
G
GiB
gibibyte: 2^30 = 1,073,741,824.
TB
terabyte: 10^12 = 1,000,000,000,000.
T
TiB
tebibyte: 2^40 = 1,099,511,627,776.
PB
petabyte: 10^15 = 1,000,000,000,000,000.
P
PiB
pebibyte: 2^50 = 1,125,899,906,842,624.
EB
exabyte: 10^18 = 1,000,000,000,000,000,000.
E
EiB
exbibyte: 2^60 = 1,152,921,504,606,846,976.
ZB
zettabyte: 10^21 = 1,000,000,000,000,000,000,000
Z
ZiB
2^70 = 1,180,591,620,717,411,303,424. (Zi is a GNU extension to IEC 60027-2.)
YB
yottabyte: 10^24 = 1,000,000,000,000,000,000,000,000.
Y
YiB
2^80 = 1,208,925,819,614,629,174,706,176. (Yi is a GNU extension to IEC 60027-2.)

Node:Invoking diff, Next:Invoking diff3, Previous:Invoking cmp, Up:Top

Invoking diff

The format for running the diff command is:

diff options... files...

In the simplest case, two file names from-file and to-file are given, and diff compares the contents of from-file and to-file. A file name of - stands for text read from the standard input. As a special case, diff - - compares a copy of standard input to itself.

If one file is a directory and the other is not, diff compares the file in the directory whose name is that of the non-directory. The non-directory file must not be -.

If two file names are given and both are directories, diff compares corresponding files in both directories, in alphabetical order; this comparison is not recursive unless the -r or --recursive option is given. diff never compares the actual contents of a directory as if it were a file. The file that is fully specified may not be standard input, because standard input is nameless and the notion of "file with the same name" does not apply.

If the --from-file=file option is given, the number of file names is arbitrary, and file is compared to each named file. Similarly, if the --to-file=file option is given, each named file is compared to file.

diff options begin with -, so normally file names may not begin with -. However, -- as an argument by itself treats the remaining arguments as file names even if they begin with -.

An exit status of 0 means no differences were found, 1 means some differences were found, and 2 means trouble.

  • diff Options: Summary of options to diff.

Node:diff Options, Up:Invoking diff

Options to diff

Below is a summary of all of the options that GNU diff accepts. Most options have two equivalent names, one of which is a single letter preceded by -, and the other of which is a long name preceded by --. Multiple single letter options (unless they take an argument) can be combined into a single command line word: -ac is equivalent to -a -c. Long named options can be abbreviated to any unique prefix of their name. Brackets ([ and ]) indicate that an option takes an optional argument.

-a
--text
Treat all files as text and compare them line-by-line, even if they do not seem to be text. See Binary.
-b
--ignore-space-change
Ignore changes in amount of white space. See White Space.
-B
--ignore-blank-lines
Ignore changes that just insert or delete blank lines. See Blank Lines.
--binary
Read and write data in binary mode. See Binary.
-c
Use the context output format, showing three lines of context. See Context Format.
-C lines
--context[=lines]
Use the context output format, showing lines (an integer) lines of context, or three if lines is not given. See Context Format. For proper operation, patch typically needs at least two lines of context.

On older systems, diff supports an obsolete option -lines that has effect when combined with -c or -p. POSIX 1003.1-2001 (see Standards conformance) does not allow this; use -C lines instead.

--changed-group-format=format
Use format to output a line group containing differing lines from both files in if-then-else format. See Line Group Formats.
-d
--minimal
Change the algorithm perhaps find a smaller set of changes. This makes diff slower (sometimes much slower). See diff Performance.
-D name
--ifdef=name
Make merged #ifdef format output, conditional on the preprocessor macro name. See If-then-else.
-e
--ed
Make output that is a valid ed script. See ed Scripts.
-E
--ignore-tab-expansion
Ignore changes due to tab expansion. See White Space.
-f
--forward-ed
Make output that looks vaguely like an ed script but has changes in the order they appear in the file. See Forward ed.
-F regexp
--show-function-line=regexp
In context and unified format, for each hunk of differences, show some of the last preceding line that matches regexp. See Specified Headings.
--from-file=file
Compare file to each operand; file may be a directory.
--help
Output a summary of usage and then exit.
--horizon-lines=lines
Do not discard the last lines lines of the common prefix and the first lines lines of the common suffix. See diff Performance.
-i
--ignore-case
Ignore changes in case; consider upper- and lower-case letters equivalent. See Case Folding.
-I regexp
--ignore-matching-lines=regexp
Ignore changes that just insert or delete lines that match regexp. See Specified Folding.
--ignore-file-name-case
Ignore case when comparing file names during recursive comparison. See Comparing Directories.
-l
--paginate
Pass the output through pr to paginate it. See Pagination.
--label=label
Use label instead of the file name in the context format (see Context Format) and unified format (see Unified Format) headers. See RCS.
--left-column
Print only the left column of two common lines in side by side format. See Side by Side Format.
--line-format=format
Use format to output all input lines in if-then-else format. See Line Formats.
-n
--rcs
Output RCS-format diffs; like -f except that each command specifies the number of lines affected. See RCS.
-N
--new-file
In directory comparison, if a file is found in only one directory, treat it as present but empty in the other directory. See Comparing Directories.
--new-group-format=format
Use format to output a group of lines taken from just the second file in if-then-else format. See Line Group Formats.
--new-line-format=format
Use format to output a line taken from just the second file in if-then-else format. See Line Formats.
--old-group-format=format
Use format to output a group of lines taken from just the first file in if-then-else format. See Line Group Formats.
--old-line-format=format
Use format to output a line taken from just the first file in if-then-else format. See Line Formats.
-p
--show-c-function
Show which C function each change is in. See C Function Headings.
-q
--brief
Report only whether the files differ, not the details of the differences. See Brief.
-r
--recursive
When comparing directories, recursively compare any subdirectories found. See Comparing Directories.
-s
--report-identical-files
Report when two files are the same. See Comparing Directories.
-S file
--starting-file=file
When comparing directories, start with the file file. This is used for resuming an aborted comparison. See Comparing Directories.
--speed-large-files
Use heuristics to speed handling of large files that have numerous scattered small changes. See diff Performance.
--strip-trailing-cr
Strip any trailing carriage return at the end of an input line. See Binary.
--suppress-common-lines
Do not print common lines in side by side format. See Side by Side Format.
-t
--expand-tabs
Expand tabs to spaces in the output, to preserve the alignment of tabs in the input files. See Tabs.
-T
--initial-tab
Output a tab rather than a space before the text of a line in normal or context format. This causes the alignment of tabs in the line to look normal. See Tabs.
--to-file=file
Compare each operand to file; file may be a directory.
-u
Use the unified output format, showing three lines of context. See Unified Format.
--unchanged-group-format=format
Use format to output a group of common lines taken from both files in if-then-else format. See Line Group Formats.
--unchanged-line-format=format
Use format to output a line common to both files in if-then-else format. See Line Formats.
--unidirectional-new-file
When comparing directories, if a file appears only in the second directory of the two, treat it as present but empty in the other. See Comparing Directories.
-U lines
--unified[=lines]
Use the unified output format, showing lines (an integer) lines of context, or three if lines is not given. See Unified Format. For proper operation, patch typically needs at least two lines of context.

On older systems, diff supports an obsolete option -lines that has effect when combined with -u. POSIX 1003.1-2001 (see Standards conformance) does not allow this; use -U lines instead.

-v
--version
Output version information and then exit.
-w
--ignore-all-space
Ignore white space when comparing lines. See White Space.
-W columns
--width=columns
Output at most columns (default 130) print columns per line in side by side format. See Side by Side Format.
-x pattern
--exclude=pattern
When comparing directories, ignore files and subdirectories whose basenames match pattern. See Comparing Directories.
-X file
--exclude-from=file
When comparing directories, ignore files and subdirectories whose basenames match any pattern contained in file. See Comparing Directories.
-y
--side-by-side
Use the side by side output format. See Side by Side Format.

Node:Invoking diff3, Next:Invoking patch, Previous:Invoking diff, Up:Top

Invoking diff3

The diff3 command compares three files and outputs descriptions of their differences. Its arguments are as follows:

diff3 options... mine older yours

The files to compare are mine, older, and yours. At most one of these three file names may be -, which tells diff3 to read the standard input for that file.

An exit status of 0 means diff3 was successful, 1 means some conflicts were found, and 2 means trouble.

  • diff3 Options: Summary of options to diff3.

Node:diff3 Options, Up:Invoking diff3

Options to diff3

Below is a summary of all of the options that GNU diff3 accepts. Multiple single letter options (unless they take an argument) can be combined into a single command line argument.

-a
--text
Treat all files as text and compare them line-by-line, even if they do not appear to be text. See Binary.
-A
--show-all
Incorporate all unmerged changes from older to yours into mine, surrounding conflicts with bracket lines. See Marking Conflicts.
--diff-program=program
Use the compatible comparison program program to compare files instead of diff.
-e
--ed
Generate an ed script that incorporates all the changes from older to yours into mine. See Which Changes.
-E
--show-overlap
Like -e, except bracket lines from overlapping changes' first and third files. See Marking Conflicts. With -E, an overlapping change looks like this:
<<<<<<< mine
lines from mine
=======
lines from yours
>>>>>>> yours

--help
Output a summary of usage and then exit.
-i
Generate w and q commands at the end of the ed script for System V compatibility. This option must be combined with one of the -AeExX3 options, and may not be combined with -m. See Saving the Changed File.
-L label
--label=label
Use the label label for the brackets output by the -A, -E and -X options. This option may be given up to three times, one for each input file. The default labels are the names of the input files. Thus diff3 -L X -L Y -L Z -m A B C acts like diff3 -m A B C, except that the output looks like it came from files named X, Y and Z rather than from files named A, B and C. See Marking Conflicts.
-m
--merge
Apply the edit script to the first file and send the result to standard output. Unlike piping the output from diff3 to ed, this works even for binary files and incomplete lines. -A is assumed if no edit script option is specified. See Bypassing ed.
-T
--initial-tab
Output a tab rather than two spaces before the text of a line in normal format. This causes the alignment of tabs in the line to look normal. See Tabs.
-v
--version
Output version information and then exit.
-x
--overlap-only
Like -e, except output only the overlapping changes. See Which Changes.
-X
Like -E, except output only the overlapping changes. In other words, like -x, except bracket changes as in -E. See Marking Conflicts.
-3
--easy-only
Like -e, except output only the nonoverlapping changes. See Which Changes.

Node:Invoking patch, Next:Invoking sdiff, Previous:Invoking diff3, Up:Top

Invoking patch

Normally patch is invoked like this:

patch <patchfile

The full format for invoking patch is:

patch options... [origfile [patchfile]]

You can also specify where to read the patch from with the -i patchfile or --input=patchfile option. If you do not specify patchfile, or if patchfile is -, patch reads the patch (that is, the diff output) from the standard input.

If you do not specify an input file on the command line, patch tries to intuit from the leading text (any text in the patch that comes before the diff output) which file to edit. See Multiple Patches.

By default, patch replaces the original input file with the patched version, possibly after renaming the original file into a backup file (see Backup Names, for a description of how patch names backup files). You can also specify where to put the output with the -o file or --output=file option; however, do not use this option if file is one of the input files.

  • patch Options: Summary table of options to patch.

Node:patch Options, Up:Invoking patch

Options to patch

Here is a summary of all of the options that GNU patch accepts. See patch and Tradition, for which of these options are safe to use in older versions of patch.

Multiple single-letter options that do not take an argument can be combined into a single command line argument with only one dash.

-b
--backup
Back up the original contents of each file, even if backups would normally not be made. See Backups.
-B prefix
--prefix=prefix
Prepend prefix to backup file names. See Backup Names.
--backup-if-mismatch
Back up the original contents of each file if the patch does not exactly match the file. This is the default behavior when not conforming to POSIX. See Backups.
--binary
Read and write all files in binary mode, except for standard output and /dev/tty. This option has no effect on POSIX-conforming systems like GNU/Linux. On systems where this option makes a difference, the patch should be generated by diff -a --binary. See Binary.
-c
--context
Interpret the patch file as a context diff. See patch Input.
-d directory
--directory=directory
Make directory directory the current directory for interpreting both file names in the patch file, and file names given as arguments to other options. See patch Directories.
-D name
--ifdef=name
Make merged if-then-else output using name. See If-then-else.
--dry-run
Print the results of applying the patches without actually changing any files. See Dry Runs.
-e
--ed
Interpret the patch file as an ed script. See patch Input.
-E
--remove-empty-files
Remove output files that are empty after the patches have been applied. See Creating and Removing.
-f
--force
Assume that the user knows exactly what he or she is doing, and do not ask any questions. See patch Messages.
-F lines
--fuzz=lines
Set the maximum fuzz factor to lines. See Inexact.
-g num
--get=num
If num is positive, get input files from a revision control system as necessary; if zero, do not get the files; if negative, ask the user whether to get the files. See Revision Control.
--help
Output a summary of usage and then exit.
-i patchfile
--input=patchfile
Read the patch from patchfile rather than from standard input. See patch Options.
-l
--ignore-white-space
Let any sequence of blanks (spaces or tabs) in the patch file match any sequence of blanks in the input file. See Changed White Space.
-n
--normal
Interpret the patch file as a normal diff. See patch Input.
-N
--forward
Ignore patches that patch thinks are reversed or already applied. See also -R. See Reversed Patches.
--no-backup-if-mismatch
Do not back up the original contents of files. This is the default behavior when conforming to POSIX. See Backups.
-o file
--output=file
Use file as the output file name. See patch Options.
-pnumber
--strip=number
Set the file name strip count to number. See patch Directories.
--posix
Conform to POSIX, as if the POSIXLY_CORRECT environment variable had been set. See patch and POSIX.
--quoting-style=word
Use style word to quote names in diagnostics, as if the QUOTING_STYLE environment variable had been set to word. See patch Quoting Style.
-r reject-file
--reject-file=reject-file
Use reject-file as the reject file name. See Reject Names.
-R
--reverse
Assume that this patch was created with the old and new files swapped. See Reversed Patches.
-s
--quiet
--silent
Work silently unless an error occurs. See patch Messages.
-t
--batch
Do not ask any questions. See patch Messages.
-T
--set-time
Set the modification and access times of patched files from time stamps given in context diff headers, assuming that the context diff headers use local time. See Patching Time Stamps.
-u
--unified
Interpret the patch file as a unified diff. See patch Input.
-v
--version
Output version information and then exit.
-V backup-style
--version=control=backup-style
Select the naming convention for backup file names. See Backup Names.
--verbose
Print more diagnostics than usual. See patch Messages.
-x number
--debug=number
Set internal debugging flags. Of interest only to patch patchers.
-Y prefix
--basename-prefix=prefix
Prepend prefix to base names of backup files. See Backup Names.
-z suffix
--suffix=suffix
Use suffix as the backup extension instead of .orig or ~. See Backup Names.
-Z
--set-utc
Set the modification and access times of patched files from time stamps given in context diff headers, assuming that the context diff headers use UTC. See Patching Time Stamps.

Node:Invoking sdiff, Next:Standards conformance, Previous:Invoking patch, Up:Top

Invoking sdiff

The sdiff command merges two files and interactively outputs the results. Its arguments are as follows:

sdiff -o outfile options... from-file to-file

This merges from-file with to-file, with output to outfile. If from-file is a directory and to-file is not, sdiff compares the file in from-file whose file name is that of to-file, and vice versa. from-file and to-file may not both be directories.

sdiff options begin with -, so normally from-file and to-file may not begin with -. However, -- as an argument by itself treats the remaining arguments as file names even if they begin with -. You may not use - as an input file.

sdiff without -o (or --output) produces a side-by-side difference. This usage is obsolete; use the -y or --side-by-side option of diff instead.

An exit status of 0 means no differences were found, 1 means some differences were found, and 2 means trouble.

  • sdiff Options: Summary of options to diff.

Node:sdiff Options, Up:Invoking sdiff

Options to sdiff

Below is a summary of all of the options that GNU sdiff accepts. Each option has two equivalent names, one of which is a single letter preceded by -, and the other of which is a long name preceded by --. Multiple single letter options (unless they take an argument) can be combined into a single command line argument. Long named options can be abbreviated to any unique prefix of their name.

-a
--text
Treat all files as text and compare them line-by-line, even if they do not appear to be text. See Binary.
-b
--ignore-space-change
Ignore changes in amount of white space. See White Space.
-B
--ignore-blank-lines
Ignore changes that just insert or delete blank lines. See Blank Lines.
-d
--minimal
Change the algorithm to perhaps find a smaller set of changes. This makes sdiff slower (sometimes much slower). See diff Performance.
--diff-program=program
Use the compatible comparison program program to compare files instead of diff.
-E
--ignore-tab-expansion
Ignore changes due to tab expansion. See White Space.
--help
Output a summary of usage and then exit.
-i
--ignore-case
Ignore changes in case; consider upper- and lower-case to be the same. See Case Folding.
-I regexp
--ignore-matching-lines=regexp
Ignore changes that just insert or delete lines that match regexp. See Specified Folding.
-l
--left-column
Print only the left column of two common lines. See Side by Side Format.
-o file
--output=file
Put merged output into file. This option is required for merging.
-s
--suppress-common-lines
Do not print common lines. See Side by Side Format.
--speed-large-files
Use heuristics to speed handling of large files that have numerous scattered small changes. See diff Performance.
--strip-trailing-cr
Strip any trailing carriage return at the end of an input line. See Binary.
-t
--expand-tabs
Expand tabs to spaces in the output, to preserve the alignment of tabs in the input files. See Tabs.
-v
--version
Output version information and then exit.
-w columns
--width=columns
Output at most columns (default 130) print columns per line. See Side by Side Format. Note that for historical reasons, this option is -W in diff, -w in sdiff.
-W
--ignore-all-space
Ignore white space when comparing lines. See White Space. Note that for historical reasons, this option is -w in diff, -W in sdiff.

Node:Standards conformance, Next:Projects, Previous:Invoking sdiff, Up:Top

Standards conformance

In a few cases, the GNU utilities' default behavior is incompatible with the POSIX standard. To suppress these incompatibilities, define the POSIXLY_CORRECT environment variable. Unless you are checking for POSIX conformance, you probably do not need to define POSIXLY_CORRECT.

Normally options and operands can appear in any order, and programs act as if all the options appear before any operands. For example, diff lao tzu -C 2 acts like diff -C 2 lao tzu, since 2 is an option-argument of -C. However, if the POSIXLY_CORRECT environment variable is set, options must appear before operands, unless otherwise specified for a particular command.

Newer versions of POSIX are occasionally incompatible with older versions. For example, older versions of POSIX allowed the command diff -c -10 to have the same meaning as diff -C 10, but POSIX 1003.1-2001 diff no longer allows digit-string options like -10.

The GNU utilities normally conform to the version of POSIX that is standard for your system. To cause them to conform to a different version of POSIX, define the _POSIX2_VERSION environment variable to a value of the form yyyymm specifying the year and month the standard was adopted. Two values are currently supported for _POSIX2_VERSION: 199209 stands for POSIX 1003.2-1992, and 200112 stands for POSIX 1003.1-2001. For example, if you are running older software that assumes an older version of POSIX and uses diff -c -10, you can work around the compatibility problems by setting _POSIX2_VERSION=199209 in your environment.

Node:Projects, Next:Copying This Manual, Previous:Standards conformance, Up:Top

Future Projects

Here are some ideas for improving GNU diff and patch. The GNU project has identified some improvements as potential programming projects for volunteers. You can also help by reporting any bugs that you find.

If you are a programmer and would like to contribute something to the GNU project, please consider volunteering for one of these projects. If you are seriously contemplating work, please write to gnu@gnu.org to coordinate with other volunteers.

  • Shortcomings: Suggested projects for improvements.
  • Bugs: Reporting bugs.

Node:Shortcomings, Next:Bugs, Up:Projects

Suggested Projects for Improving GNU diff and patch

One should be able to use GNU diff to generate a patch from any pair of directory trees, and given the patch and a copy of one such tree, use patch to generate a faithful copy of the other. Unfortunately, some changes to directory trees cannot be expressed using current patch formats; also, patch does not handle some of the existing formats. These shortcomings motivate the following suggested projects.

  • Internationalization: Handling multibyte and varying-width characters.
  • Changing Structure: Handling changes to the directory structure.
  • Special Files: Handling symbolic links, device special files, etc.
  • Unusual File Names: Handling file names that contain unusual characters.
  • Time Stamp Order: Outputting diffs in time stamp order.
  • Ignoring Changes: Ignoring certain changes while showing others.
  • Speedups: Improving performance.

Node:Internationalization, Next:Changing Structure, Up:Shortcomings

Handling Multibyte and Varying-Width Characters

diff, diff3 and sdiff treat each line of input as a string of unibyte characters. This can mishandle multibyte characters in some cases. For example, when asked to ignore spaces, diff does not properly ignore a multibyte space character.

Also, diff currently assumes that each byte is one column wide, and this assumption is incorrect in some locales, e.g., locales that use UTF-8 encoding. This causes problems with the -y or --side-by-side option of diff.

These problems need to be fixed without unduly affecting the performance of the utilities in unibyte environments.

The IBM GNU/Linux Technology Center Internationalization Team has proposed some patches to support internationalized diff http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz. Unfortunately, these patches are incomplete and are to an older version of diff, so more work needs to be done in this area.

Node:Changing Structure, Next:Special Files, Previous:Internationalization, Up:Shortcomings

Handling Changes to the Directory Structure

diff and patch do not handle some changes to directory structure. For example, suppose one directory tree contains a directory named D with some subsidiary files, and another contains a file with the same name D. diff -r does not output enough information for patch to transform the directory subtree into the file.

There should be a way to specify that a file has been removed without having to include its entire contents in the patch file. There should also be a way to tell patch that a file was renamed, even if there is no way for diff to generate such information. There should be a way to tell patch that a file's time stamp has changed, even if its contents have not changed.

These problems can be fixed by extending the diff output format to represent changes in directory structure, and extending patch to understand these extensions.

Node:Special Files, Next:Unusual File Names, Previous:Changing Structure, Up:Shortcomings

Files that are Neither Directories Nor Regular Files

Some files are neither directories nor regular files: they are unusual files like symbolic links, device special files, named pipes, and sockets. Currently, diff treats symbolic links like regular files; it treats other special files like regular files if they are specified at the top level, but simply reports their presence when comparing directories. This means that patch cannot represent changes to such files. For example, if you change which file a symbolic link points to, diff outputs the difference between the two files, instead of the change to the symbolic link.

diff should optionally report changes to special files specially, and patch should be extended to understand these extensions.

Node:Unusual File Names, Next:Time Stamp Order, Previous:Special Files, Up:Shortcomings

File Names that Contain Unusual Characters

When a file name contains an unusual character like a newline or white space, diff -r generates a patch that patch cannot parse. The problem is with format of diff output, not just with patch, because with odd enough file names one can cause diff to generate a patch that is syntactically correct but patches the wrong files. The format of diff output should be extended to handle all possible file names.

Node:Time Stamp Order, Next:Ignoring Changes, Previous:Unusual File Names, Up:Shortcomings

Outputting Diffs in Time Stamp Order

Applying patch to a multiple-file diff can result in files whose time stamps are out of order. GNU patch has options to restore the time stamps of the updated files (see Patching Time Stamps), but sometimes it is useful to generate a patch that works even if the recipient does not have GNU patch, or does not use these options. One way to do this would be to implement a diff option to output diffs in time stamp order.

Node:Ignoring Changes, Next:Speedups, Previous:Time Stamp Order, Up:Shortcomings

Ignoring Certain Changes

It would be nice to have a feature for specifying two strings, one in from-file and one in to-file, which should be considered to match. Thus, if the two strings are foo and bar, then if two lines differ only in that foo in file 1 corresponds to bar in file 2, the lines are treated as identical.

It is not clear how general this feature can or should be, or what syntax should be used for it.

A partial substitute is to filter one or both files before comparing, e.g.:

sed 's/foo/bar/g' file1 | diff - file2

However, this outputs the filtered text, not the original.

Node:Speedups, Previous:Ignoring Changes, Up:Shortcomings

Improving Performance

When comparing two large directory structures, one of which was originally copied from the other with time stamps preserved (e.g., with cp -pR), it would greatly improve performance if an option told diff to assume that two files with the same size and time stamps have the same content. See diff Performance.

Node:Bugs, Previous:Shortcomings, Up:Projects

Reporting Bugs

If you think you have found a bug in GNU cmp, diff, diff3, or sdiff, please report it by electronic mail to the GNU utilities bug report mailing list bug-gnu-utils@gnu.org. Please send bug reports for GNU patch to bug-patch@gnu.org. Send as precise a description of the problem as you can, including the output of the --version option and sample input files that produce the bug, if applicable. If you have a nontrivial fix for the bug, please send it as well. If you have a patch, please send it too. It may simplify the maintainer's job if the patch is relative to a recent test release, which you can find in the directory ftp://alpha.gnu.org/gnu/diffutils/.

Node:Copying This Manual, Next:Index, Previous:Projects, Up:Top

Copying This Manual

  • GNU Free Documentation License: License for copying this manual.

Node:GNU Free Documentation License, Up:Copying This Manual

GNU Free Documentation License

Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Node:Index, Previous:Copying This Manual, Up:Top

Index

  • ! output format: Context
  • +- output format: Unified Format
  • < output format: Normal
  • <<<<<<< for marking conflicts: Marking Conflicts
  • _POSIX2_VERSION: Standards conformance
  • aligning tab stops: Tabs
  • alternate file names: Alternate Names
  • backup file names: Backup Names
  • backup file strategy: Backups
  • binary file diff: Binary
  • blank and tab difference suppression: White Space
  • blank line difference suppression: Blank Lines
  • brief difference reports: Brief
  • bug reports: Bugs
  • C function headings: C Function Headings
  • C if-then-else output format: If-then-else
  • case difference suppression: Case Folding
  • ClearCase: Revision Control
  • cmp invocation: Invoking cmp
  • cmp options: cmp Options
  • columnar output: Side by Side
  • common mistakes with patches: Avoiding Common Mistakes
  • comparing three files: Comparing Three Files
  • conflict: diff3 Merging
  • conflict marking: Marking Conflicts
  • context output format: Context
  • creating files: Creating and Removing
  • diagnostics from patch: patch Messages
  • diff invocation: Invoking diff
  • diff merging: Interactive Merging
  • diff options: diff Options
  • diff sample input: Sample diff Input
  • diff3 hunks: diff3 Hunks
  • diff3 invocation: Invoking diff3
  • diff3 options: diff3 Options
  • diff3 sample input: Sample diff3 Input
  • directories and patch: patch Directories
  • directory structure changes: Changing Structure
  • dry runs for patch: Dry Runs
  • ed script output format: ed Scripts
  • EDITOR: Merge Commands
  • empty files, removing: Creating and Removing
  • exabyte, definition of: cmp Options
  • exbibyte, definition of: cmp Options
  • FDL, GNU Free Documentation License: GNU Free Documentation License
  • file name alternates: Alternate Names
  • file names with unusual characters: Unusual File Names
  • format of diff output: Output Formats
  • format of diff3 output: Comparing Three Files
  • formats for if-then-else line groups: Line Group Formats
  • forward ed script output format: Forward ed
  • full lines: Incomplete Lines
  • function headings, C: C Function Headings
  • fuzz factor when patching: Inexact
  • gibibyte, definition of: cmp Options
  • gigabyte, definition of: cmp Options
  • headings: Sections
  • hunks: Hunks
  • hunks for diff3: diff3 Hunks
  • if-then-else output format: If-then-else
  • ifdef output format: If-then-else
  • imperfect patch application: Imperfect
  • incomplete line merging: Merging Incomplete Lines
  • incomplete lines: Incomplete Lines
  • inexact patches: Inexact
  • inhibit messages from patch: More or Fewer Messages
  • interactive merging: Interactive Merging
  • introduction: Comparison
  • intuiting file names from patches: Multiple Patches
  • invoking cmp: Invoking cmp
  • invoking diff: Invoking diff
  • invoking diff3: Invoking diff3
  • invoking patch: Invoking patch
  • invoking sdiff: Invoking sdiff
  • keyboard input to patch: patch and Keyboard Input
  • kibibyte, definition of: cmp Options
  • kilobyte, definition of: cmp Options
  • LC_COLLATE: Comparing Directories
  • LC_NUMERIC: Line Group Formats
  • LC_TIME: Detailed Context
  • line formats: Line Formats
  • line group formats: Line Group Formats
  • mebibyte, definition of: cmp Options
  • megabyte, definition of: cmp Options
  • merge commands: Merge Commands
  • merged diff3 format: Bypassing ed
  • merged output format: If-then-else
  • merging from a common ancestor: diff3 Merging
  • merging interactively: Merge Commands
  • messages from patch: patch Messages
  • multibyte characters: Internationalization
  • multiple patches: Multiple Patches
  • newline treatment by diff: Incomplete Lines
  • normal output format: Normal
  • options for cmp: cmp Options
  • options for diff: diff Options
  • options for diff3: diff3 Options
  • options for patch: patch Options
  • options for sdiff: sdiff Options
  • output formats: Output Formats
  • overlap: diff3 Merging
  • overlapping change, selection of: Which Changes
  • overview of diff and patch: Overview
  • paginating diff output: Pagination
  • patch consumer tips: Tips for Patch Consumers
  • patch input format: patch Input
  • patch invocation: Invoking patch
  • patch messages and questions: patch Messages
  • patch options: patch Options
  • patch producer tips: Tips for Patch Producers
  • patch, common mistakes: Avoiding Common Mistakes
  • PATCH_GET: Revision Control
  • PATCH_VERSION_CONTROL: Backup Names
  • patches, shrinking: Generating Smaller Patches
  • patching directories: patch Directories
  • pebibyte, definition of: cmp Options
  • performance of diff: diff Performance
  • petabyte, definition of: cmp Options
  • POSIX: Standards conformance, patch and POSIX
  • POSIXLY_CORRECT: Standards conformance, patch and POSIX
  • projects for directories: Shortcomings
  • quoting style: patch Quoting Style
  • QUOTING_STYLE: patch Quoting Style
  • RCS: Revision Control
  • RCS script output format: RCS
  • regular expression matching headings: Specified Headings
  • regular expression suppression: Specified Folding
  • reject file names: Reject Names
  • removing empty files: Creating and Removing
  • reporting bugs: Bugs
  • reversed patches: Reversed Patches
  • revision control: Revision Control
  • sample input for diff: Sample diff Input
  • sample input for diff3: Sample diff3 Input
  • SCCS: Revision Control
  • script output formats: Scripts
  • sdiff invocation: Invoking sdiff
  • sdiff options: sdiff Options
  • sdiff output format: sdiff Option Summary
  • section headings: Sections
  • side by side: Side by Side
  • side by side format: Side by Side Format
  • SIMPLE_BACKUP_SUFFIX: Backup Names
  • special files: Special Files
  • specified headings: Specified Headings
  • summarizing which files differ: Brief
  • System V diff3 compatibility: Saving the Changed File
  • tab and blank difference suppression: White Space
  • tab stop alignment: Tabs
  • tebibyte, definition of: cmp Options
  • terabyte, definition of: cmp Options
  • testing patch: Dry Runs
  • text versus binary diff: Binary
  • time stamp format, context diffs: Detailed Context
  • time stamp format, unified diffs: Detailed Unified
  • time stamps on patched files: Patching Time Stamps
  • traditional patch: patch and Tradition
  • two-column output: Side by Side
  • unified output format: Unified Format
  • unmerged change: Which Changes
  • varying-width characters: Internationalization
  • verbose messages from patch: More or Fewer Messages
  • version control: Revision Control
  • VERSION_CONTROL: Backup Names, Revision Control
  • white space in patches: Changed White Space
  • yottabyte, definition of: cmp Options
  • zettabyte, definition of: cmp Options

Footnotes

  1. A coding error in GNU patch version 2.5.4 causes it to always use ~, but this should be fixed in the next release.


GNU Emacs Lisp Reference Manual:

[Top]

[Contents]

[Index]

[ ? ]

GNU Emacs Lisp Reference Manual

This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to GNU Emacs version 21.2.

1. Introduction

Introduction and conventions used.

D.1 Emacs Lisp Coding Conventions

Coding conventions for Emacs Lisp.

2. Lisp Data Types

Data types of objects in Emacs Lisp.

3. Numbers

Numbers and arithmetic functions.

4. Strings and Characters

Strings, and functions that work on them.

5. Lists

Lists, cons cells, and related functions.

6. Sequences, Arrays, and Vectors

Lists, strings and vectors are called sequences. Certain functions act on any kind of sequence. The description of vectors is here as well.

7. Hash Tables

Very fast lookup-tables.

8. Symbols

Symbols represent names, uniquely.

9. Evaluation

How Lisp expressions are evaluated.

10. Control Structures

Conditionals, loops, nonlocal exits.

11. Variables

Using symbols in programs to stand for values.

12. Functions

A function is a Lisp program that can be invoked from other functions.

13. Macros

Macros are a way to extend the Lisp language.

14. Writing Customization Definitions

Writing customization declarations.

15. Loading

Reading files of Lisp code into Lisp.

16. Byte Compilation

Compilation makes programs run faster.

17. Advising Emacs Lisp Functions

Adding to the definition of a function.

18. Debugging Lisp Programs

Tools and tips for debugging Lisp programs.

19. Reading and Printing Lisp Objects

Converting Lisp objects to text and back.

20. Minibuffers

Using the minibuffer to read input.

21. Command Loop

How the editor command loop works, and how you can call its subroutines.

22. Keymaps

Defining the bindings from keys to commands.

23. Major and Minor Modes

Defining major and minor modes.

24. Documentation

Writing and using documentation strings.

25. Files

Accessing files.

26. Backups and Auto-Saving

Controlling how backups and auto-save files are made.

27. Buffers

Creating and using buffer objects.

28. Windows

Manipulating windows and displaying buffers.

29. Frames

Making multiple X windows.

30. Positions

Buffer positions and motion functions.

31. Markers

Markers represent positions and update automatically when the text is changed.

32. Text

Examining and changing text in buffers.

33. Non-ASCII Characters

Non-ASCII text in buffers and strings.

34. Searching and Matching

Searching buffers for strings or regexps.

35. Syntax Tables

The syntax table controls word and list parsing.

36. Abbrevs and Abbrev Expansion

How Abbrev mode works, and its data structures.

37. Processes

Running and communicating with subprocesses.

38. Emacs Display

Features for controlling the screen display.

39. Customizing the Calendar and Diary

Customizing the calendar and diary.

40. Operating System Interface

Getting the user id, system type, environment variables, and other such things.

Appendices

A. Emacs 20 Antinews

Info for users downgrading to Emacs 20.

B. GNU Free Documentation License

The license for this documentation

C. GNU General Public License

Conditions for copying and changing GNU Emacs.

D. Tips and Conventions

Advice and coding conventions for Emacs Lisp.

E. GNU Emacs Internals

Building and dumping Emacs; internal data structures.

F. Standard Errors

List of all error symbols.

G. Buffer-Local Variables

List of variables buffer-local in all buffers.

H. Standard Keymaps

List of standard keymaps.

I. Standard Hooks

List of standard hook variables.

Index

Index including concepts, functions, variables, and other terms.

New Symbols Since the Previous Edition

New functions and variables in Emacs 21.

-- The Detailed Node Listing ---

Here are other nodes that are inferiors of those already listed,
mentioned here so you can get to them in one step:

Introduction

1.1 Caveats

Flaws and a request for help.

1.2 Lisp History

Emacs Lisp is descended from Maclisp.

1.3 Conventions

How the manual is formatted.

1.5 Acknowledgements

The authors, editors, and sponsors of this manual.

Conventions

1.3.1 Some Terms

Explanation of terms we use in this manual.

1.3.2 nil and t

How the symbols nil and t are used.

1.3.3 Evaluation Notation

The format we use for examples of evaluation.

1.3.4 Printing Notation

The format we use for examples that print output.

1.3.5 Error Messages

The format we use for examples of errors.

1.3.6 Buffer Text Notation

The format we use for buffer contents in examples.

1.3.7 Format of Descriptions

Notation for describing functions, variables, etc.

Tips and Conventions

D.1 Emacs Lisp Coding Conventions

Conventions for clean and robust programs.

D.2 Tips for Making Compiled Code Fast

Making compiled code run fast.

D.3 Tips for Documentation Strings

Writing readable documentation strings.

D.4 Tips on Writing Comments

Conventions for writing comments.

D.5 Conventional Headers for Emacs Libraries

Standard headers for library packages.

Format of Descriptions

1.3.7.1 A Sample Function Description

1.3.7.2 A Sample Variable Description

Lisp Data Types

2.1 Printed Representation and Read Syntax

How Lisp objects are represented as text.

2.2 Comments

Comments and their formatting conventions.

2.3 Programming Types

Types found in all Lisp systems.

2.4 Editing Types

Types specific to Emacs.

2.6 Type Predicates

Tests related to types.

2.7 Equality Predicates

Tests of equality between any two objects.

Programming Types

2.3.1 Integer Type

Numbers without fractional parts.

2.3.2 Floating Point Type

Numbers with fractional parts and with a large range.

2.3.3 Character Type

The representation of letters, numbers and control characters.

2.3.5 Sequence Types

Both lists and arrays are classified as sequences.

2.3.6 Cons Cell and List Types

Cons cells, and lists (which are made from cons cells).

2.3.7 Array Type

Arrays include strings and vectors.

2.3.8 String Type

An (efficient) array of characters.

2.3.9 Vector Type

One-dimensional arrays.

2.3.4 Symbol Type

A multi-use object that refers to a function, variable, property list, or itself.

2.3.13 Function Type

A piece of executable code you can call from elsewhere.

2.3.14 Macro Type

A method of expanding an expression into another expression, more fundamental but less pretty.

2.3.15 Primitive Function Type

A function written in C, callable from Lisp.

2.3.16 Byte-Code Function Type

A function written in Lisp, then compiled.

2.3.17 Autoload Type

A type used for automatically loading seldom-used functions.

List Type

2.3.6.1 Dotted Pair Notation

An alternative syntax for lists.

2.3.6.2 Association List Type

A specially constructed list.

Editing Types

2.4.1 Buffer Type

The basic object of editing.

2.4.3 Window Type

What makes buffers visible.

2.4.5 Window Configuration Type

Save what the screen looks like.

2.4.2 Marker Type

A position in a buffer.

2.4.7 Process Type

A process running on the underlying OS.

2.4.8 Stream Type

Receive or send characters.

2.4.9 Keymap Type

What function a keystroke invokes.

2.4.10 Overlay Type

How an overlay is represented.

Numbers

3.1 Integer Basics

Representation and range of integers.

3.2 Floating Point Basics

Representation and range of floating point.

3.3 Type Predicates for Numbers

Testing for numbers.

3.4 Comparison of Numbers

Equality and inequality predicates.

3.6 Arithmetic Operations

How to add, subtract, multiply and divide.

3.8 Bitwise Operations on Integers

Logical and, or, not, shifting.

3.5 Numeric Conversions

Converting float to integer and vice versa.

3.9 Standard Mathematical Functions

Trig, exponential and logarithmic functions.

3.10 Random Numbers

Obtaining random integers, predictable or not.

Strings and Characters

4.1 String and Character Basics

Basic properties of strings and characters.

4.2 The Predicates for Strings

Testing whether an object is a string or char.

4.3 Creating Strings

Functions to allocate new strings.

4.5 Comparison of Characters and Strings

Comparing characters or strings.

4.6 Conversion of Characters and Strings

Converting characters or strings and vice versa.

4.7 Formatting Strings

format: Emacs's analogue of printf.

4.8 Case Conversion in Lisp

Case conversion functions.

Lists

5.1 Lists and Cons Cells

How lists are made out of cons cells.

5.2 Lists as Linked Pairs of Boxes

Graphical notation to explain lists.

5.3 Predicates on Lists

Is this object a list? Comparing two lists.

5.4 Accessing Elements of Lists

Extracting the pieces of a list.

5.5 Building Cons Cells and Lists

Creating list structure.

5.6 Modifying Existing List Structure

Storing new pieces into an existing list.

5.7 Using Lists as Sets

A list can represent a finite mathematical set.

5.8 Association Lists

A list can represent a finite relation or mapping.

Modifying Existing List Structure

5.6.1 Altering List Elements with setcar

Replacing an element in a list.

5.6.2 Altering the CDR of a List

Replacing part of the list backbone. This can be used to remove or add elements.

5.6.3 Functions that Rearrange Lists

Reordering the elements in a list; combining lists.

Sequences, Arrays, and Vectors

6.1 Sequences

Functions that accept any kind of sequence.

6.2 Arrays

Characteristics of arrays in Emacs Lisp.

6.3 Functions that Operate on Arrays

Functions specifically for arrays.

6.4 Vectors

Functions specifically for vectors.

Symbols

8.1 Symbol Components

Symbols have names, values, function definitions and property lists.

8.2 Defining Symbols

A definition says how a symbol will be used.

8.3 Creating and Interning Symbols

How symbols are kept unique.

8.4 Property Lists

Each symbol has a property list for recording miscellaneous information.

Evaluation

9.1 Introduction to Evaluation

Evaluation in the scheme of things.

9.4 Eval

How to invoke the Lisp interpreter explicitly.

9.2 Kinds of Forms

How various sorts of objects are evaluated.

9.3 Quoting

Avoiding evaluation (to put constants in the program).

Kinds of Forms

9.2.1 Self-Evaluating Forms

Forms that evaluate to themselves.

9.2.2 Symbol Forms

Symbols evaluate as variables.

9.2.3 Classification of List Forms

How to distinguish various sorts of list forms.

9.2.5 Evaluation of Function Forms

Forms that call functions.

9.2.6 Lisp Macro Evaluation

Forms that call macros.

9.2.7 Special Forms

"Special forms" are idiosyncratic primitives, most of them extremely important.

9.2.8 Autoloading

Functions set up to load files containing their real definitions.

Control Structures

10.1 Sequencing

Evaluation in textual order.

10.2 Conditionals

if, cond.

10.3 Constructs for Combining Conditions

and, or, not.

10.4 Iteration

while loops.

10.5 Nonlocal Exits

Jumping out of a sequence.

Nonlocal Exits

10.5.1 Explicit Nonlocal Exits: catch and throw

Nonlocal exits for the program's own purposes.

10.5.2 Examples of catch and throw

Showing how such nonlocal exits can be written.

10.5.3 Errors

How errors are signaled and handled.

10.5.4 Cleaning Up from Nonlocal Exits

Arranging to run a cleanup form if an error happens.

Errors

10.5.3.1 How to Signal an Error

How to report an error.

10.5.3.2 How Emacs Processes Errors

What Emacs does when you report an error.

10.5.3.3 Writing Code to Handle Errors

How you can trap errors and continue execution.

10.5.3.4 Error Symbols and Condition Names

How errors are classified for trapping them.

Variables

11.1 Global Variables

Variable values that exist permanently, everywhere.

11.2 Variables that Never Change

Certain "variables" have values that never change.

11.3 Local Variables

Variable values that exist only temporarily.

11.4 When a Variable is "Void"

Symbols that lack values.

11.5 Defining Global Variables

A definition says a symbol is used as a variable.

11.7 Accessing Variable Values

Examining values of variables whose names are known only at run time.

11.8 How to Alter a Variable Value

Storing new values in variables.

11.9 Scoping Rules for Variable Bindings

How Lisp chooses among local and global values.

11.10 Buffer-Local Variables

Variable values in effect only in one buffer.

Scoping Rules for Variable Bindings

11.9.1 Scope

Scope means where in the program a value is visible. Comparison with other languages.

11.9.2 Extent

Extent means how long in time a value exists.

11.9.3 Implementation of Dynamic Scoping

Two ways to implement dynamic scoping.

11.9.4 Proper Use of Dynamic Scoping

How to use dynamic scoping carefully and avoid problems.

Buffer-Local Variables

11.10.1 Introduction to Buffer-Local Variables

Introduction and concepts.

11.10.2 Creating and Deleting Buffer-Local Bindings

Creating and destroying buffer-local bindings.

11.10.3 The Default Value of a Buffer-Local Variable

The default value is seen in buffers that don't have their own buffer-local values.

Functions

12.1 What Is a Function?

Lisp functions vs primitives; terminology.

12.2 Lambda Expressions

How functions are expressed as Lisp objects.

12.3 Naming a Function

A symbol can serve as the name of a function.

12.4 Defining Functions

Lisp expressions for defining functions.

12.5 Calling Functions

How to use an existing function.

12.6 Mapping Functions

Applying a function to each element of a list, etc.

12.7 Anonymous Functions

Lambda-expressions are functions with no names.

12.8 Accessing Function Cell Contents

Accessing or setting the function definition of a symbol.

12.10 Other Topics Related to Functions

Cross-references to specific Lisp primitives that have a special bearing on how functions work.

Lambda Expressions

12.2.1 Components of a Lambda Expression

The parts of a lambda expression.

12.2.2 A Simple Lambda-Expression Example

A simple example.

12.2.3 Other Features of Argument Lists

Details and special features of argument lists.

12.2.4 Documentation Strings of Functions

How to put documentation in a function.

Macros

13.1 A Simple Example of a Macro

A basic example.

13.2 Expansion of a Macro Call

How, when and why macros are expanded.

13.3 Macros and Byte Compilation

How macros are expanded by the compiler.

13.4 Defining Macros

How to write a macro definition.

13.5 Backquote

Easier construction of list structure.

13.6 Common Problems Using Macros

Don't evaluate the macro arguments too many times. Don't hide the user's variables.

Loading

15.1 How Programs Do Loading

The load function and others.

15.4 Autoload

Setting up a function to autoload.

15.6 Features

Loading a library if it isn't already loaded.

15.5 Repeated Loading

Precautions about loading a file twice.

Byte Compilation

16.2 The Compilation Functions

Byte compilation functions.

16.7 Disassembled Byte-Code

Disassembling byte-code; how to read byte-code.

Advising Functions

17.1 A Simple Advice Example

A simple example to explain the basics of advice.

17.2 Defining Advice

Detailed description of defadvice.

17.4 Computed Advice

...is to defadvice as fset is to defun.

17.5 Activation of Advice

Advice doesn't do anything until you activate it.

17.6 Enabling and Disabling Advice

You can enable or disable each piece of advice.

17.7 Preactivation

Preactivation is a way of speeding up the loading of compiled advice.

17.8 Argument Access in Advice

How advice can access the function's arguments.

17.9 Definition of Subr Argument Lists

Accessing arguments when advising a primitive.

17.10 The Combined Definition

How advice is implemented.

Debugging Lisp Programs

18.1 The Lisp Debugger

How the Emacs Lisp debugger is implemented.

18.3 Debugging Invalid Lisp Syntax

How to find syntax errors.

18.4 Debugging Problems in Compilation

How to find errors that show up in byte compilation.

18.2 Edebug

A source-level Emacs Lisp debugger.

The Lisp Debugger

18.1.1 Entering the Debugger on an Error

Entering the debugger when an error happens.

18.1.3 Entering the Debugger on a Function Call

Entering it when a certain function is called.

18.1.4 Explicit Entry to the Debugger

Entering it at a certain point in the program.

18.1.5 Using the Debugger

What the debugger does; what you see while in it.

18.1.6 Debugger Commands

Commands used while in the debugger.

18.1.7 Invoking the Debugger

How to call the function debug.

18.1.8 Internals of the Debugger

Subroutines of the debugger, and global variables.

Debugging Invalid Lisp Syntax

18.3.1 Excess Open Parentheses

How to find a spurious open paren or missing close.

18.3.2 Excess Close Parentheses

How to find a spurious close paren or missing open.

Reading and Printing Lisp Objects

19.1 Introduction to Reading and Printing

Overview of streams, reading and printing.

19.2 Input Streams

Various data types that can be used as input streams.

19.3 Input Functions

Functions to read Lisp objects from text.

19.4 Output Streams

Various data types that can be used as output streams.

19.5 Output Functions

Functions to print Lisp objects as text.

Minibuffers

20.1 Introduction to Minibuffers

Basic information about minibuffers.

20.2 Reading Text Strings with the Minibuffer

How to read a straight text string.

20.3 Reading Lisp Objects with the Minibuffer

How to read a Lisp object or expression.

20.5 Completion

How to invoke and customize completion.

20.6 Yes-or-No Queries

Asking a question with a simple answer.

20.9 Minibuffer Miscellany

Various customization hooks and variables.

Completion

20.5.1 Basic Completion Functions

Low-level functions for completing strings.

(These are too low level to use the minibuffer.)

20.5.2 Completion and the Minibuffer

Invoking the minibuffer with completion.

20.5.3 Minibuffer Commands that Do Completion

Minibuffer commands that do completion.

20.5.4 High-Level Completion Functions

Convenient special cases of completion

(reading buffer name, file name, etc.)

20.5.5 Reading File Names

Using completion to read file names.

20.5.6 Programmed Completion

Finding the completions for a given file name.

Command Loop

21.1 Command Loop Overview

How the command loop reads commands.

21.2 Defining Commands

Specifying how a function should read arguments.

21.3 Interactive Call

Calling a command, so that it will read arguments.

21.4 Information from the Command Loop

Variables set by the command loop for you to examine.

21.6 Input Events

What input looks like when you read it.

21.7 Reading Input

How to read input events from the keyboard or mouse.

21.9 Waiting for Elapsed Time or Input

Waiting for user input or elapsed time.

21.10 Quitting

How C-g works. How to catch or defer quitting.

21.11 Prefix Command Arguments

How the commands to set prefix args work.

21.12 Recursive Editing

Entering a recursive edit, and why you usually shouldn't.

21.13 Disabling Commands

How the command loop handles disabled commands.

21.14 Command History

How the command history is set up, and how accessed.

21.15 Keyboard Macros

How keyboard macros are implemented.

Defining Commands

21.2.1 Using interactive

General rules for interactive.

21.2.2 Code Characters for interactive

The standard letter-codes for reading arguments in various ways.

21.2.3 Examples of Using interactive

Examples of how to read interactive arguments.

Keymaps

22.1 Keymap Terminology

Definitions of terms pertaining to keymaps.

22.2 Format of Keymaps

What a keymap looks like as a Lisp object.

22.3 Creating Keymaps

Functions to create and copy keymaps.

22.4 Inheritance and Keymaps

How one keymap can inherit the bindings of another keymap.

22.5 Prefix Keys

Defining a key with a keymap as its definition.

22.12 Menu Keymaps

A keymap can define a menu for X or for use from the terminal.

22.6 Active Keymaps

Each buffer has a local keymap to override the standard (global) bindings. Each minor mode can also override them.

22.7 Key Lookup

How extracting elements from keymaps works.

22.8 Functions for Key Lookup

How to request key lookup.

22.9 Changing Key Bindings

Redefining a key in a keymap.

22.10 Commands for Binding Keys

Interactive interfaces for redefining keys.

22.11 Scanning Keymaps

Looking through all keymaps, for printing help.

Major and Minor Modes

23.1 Major Modes

Defining major modes.

23.2 Minor Modes

Defining minor modes.

23.3 Mode Line Format

Customizing the text that appears in the mode line.

23.6 Hooks

How to use hooks; how to write code that provides hooks.

Major Modes

23.1.1 Major Mode Conventions

Coding conventions for keymaps, etc.

23.1.2 Major Mode Examples

Text mode and Lisp modes.

23.1.3 How Emacs Chooses a Major Mode

How Emacs chooses the major mode automatically.

23.1.4 Getting Help about a Major Mode

Finding out how to use a mode.

Minor Modes

23.2.1 Conventions for Writing Minor Modes

Tips for writing a minor mode.

23.2.2 Keymaps and Minor Modes

How a minor mode can have its own keymap.

Mode Line Format

23.3.1 The Data Structure of the Mode Line

The data structure that controls the mode line.

23.3.2 Variables Used in the Mode Line

Variables used in that data structure.

23.3.3 %-Constructs in the Mode Line

Putting information into a mode line.

Documentation

24.1 Documentation Basics

Good style for doc strings. Where to put them. How Emacs stores them.

24.2 Access to Documentation Strings

How Lisp programs can access doc strings.

24.3 Substituting Key Bindings in Documentation

Substituting current key bindings.

24.4 Describing Characters for Help Messages

Making printable descriptions of non-printing characters and key sequences.

24.5 Help Functions

Subroutines used by Emacs help facilities.

Files

25.1 Visiting Files

Reading files into Emacs buffers for editing.

25.2 Saving Buffers

Writing changed buffers back into files.

25.3 Reading from Files

Reading files into other buffers.

25.4 Writing to Files

Writing new files from parts of buffers.

25.5 File Locks

Locking and unlocking files, to prevent simultaneous editing by two people.

25.6 Information about Files

Testing existence, accessibility, size of files.

25.9 Contents of Directories

Getting a list of the files in a directory.

25.7 Changing File Names and Attributes

Renaming files, changing protection, etc.

25.8 File Names

Decomposing and expanding file names.

Visiting Files

25.1.1 Functions for Visiting Files

The usual interface functions for visiting.

25.1.2 Subroutines of Visiting

Lower-level subroutines that they use.

Information about Files

25.6.1 Testing Accessibility

Is a given file readable? Writable?

25.6.2 Distinguishing Kinds of Files

Is it a directory? A link?

25.6.4 Other Information about Files

How large is it? Any other names? Etc.

File Names

25.8.1 File Name Components

The directory part of a file name, and the rest.

25.8.2 Directory Names

A directory's name as a directory is different from its name as a file.

25.8.3 Absolute and Relative File Names

Some file names are relative to a current directory.

25.8.4 Functions that Expand Filenames

Converting relative file names to absolute ones.

25.8.5 Generating Unique File Names

Generating names for temporary files.

25.8.6 File Name Completion

Finding the completions for a given file name.

Backups and Auto-Saving

26.1 Backup Files

How backup files are made; how their names are chosen.

26.2 Auto-Saving

How auto-save files are made; how their names are chosen.

26.3 Reverting

revert-buffer, and how to customize what it does.

Backup Files

26.1.1 Making Backup Files

How Emacs makes backup files, and when.

26.1.2 Backup by Renaming or by Copying?

Two alternatives: renaming the old file or copying it.

26.1.3 Making and Deleting Numbered Backup Files

Keeping multiple backups for each source file.

26.1.4 Naming Backup Files

How backup file names are computed; customization.

Buffers

27.1 Buffer Basics

What is a buffer?

27.3 Buffer Names

Accessing and changing buffer names.

27.4 Buffer File Name

The buffer file name indicates which file is visited.

27.5 Buffer Modification

A buffer is modified if it needs to be saved.

27.6 Comparison of Modification Time

Determining whether the visited file was changed

"behind Emacs's back".

27.7 Read-Only Buffers

Modifying text is not allowed in a read-only buffer.

27.8 The Buffer List

How to look at all the existing buffers.

27.9 Creating Buffers

Functions that create buffers.

27.10 Killing Buffers

Buffers exist until explicitly killed.

27.2 The Current Buffer

Designating a buffer as current so primitives will access its contents.

Windows

28.1 Basic Concepts of Emacs Windows

Basic information on using windows.

28.2 Splitting Windows

Splitting one window into two windows.

28.3 Deleting Windows

Deleting a window gives its space to other windows.

28.4 Selecting Windows

The selected window is the one that you edit in.

28.5 Cyclic Ordering of Windows

Moving around the existing windows.

28.6 Buffers and Windows

Each window displays the contents of a buffer.

28.7 Displaying Buffers in Windows

Higher-lever functions for displaying a buffer and choosing a window for it.

28.9 Windows and Point

Each window has its own location of point.

28.10 The Window Start Position

The display-start position controls which text is on-screen in the window.

28.12 Vertical Fractional Scrolling

Moving text up and down in the window.

28.13 Horizontal Scrolling

Moving text sideways on the window.

28.14 The Size of a Window

Accessing the size of a window.

28.15 Changing the Size of a Window

Changing the size of a window.

28.17 Window Configurations

Saving and restoring the state of the screen.

Frames

29.1 Creating Frames

Creating additional frames.

29.2 Multiple Displays

Creating frames on other X displays.

29.3 Frame Parameters

Controlling frame size, position, font, etc.

29.4 Frame Titles

Automatic updating of frame titles.

29.5 Deleting Frames

Frames last until explicitly deleted.

29.6 Finding All Frames

How to examine all existing frames.

29.7 Frames and Windows

A frame contains windows; display of text always works through windows.

29.8 Minibuffers and Frames

How a frame finds the minibuffer to use.

29.9 Input Focus

Specifying the selected frame.

29.10 Visibility of Frames

Frames may be visible or invisible, or icons.

29.11 Raising and Lowering Frames

Raising a frame makes it hide other X windows; lowering it puts it underneath the others.

29.12 Frame Configurations

Saving the state of all frames.

29.13 Mouse Tracking

Getting events that say when the mouse moves.

29.14 Mouse Position

Asking where the mouse is, or moving it.

29.15 Pop-Up Menus

Displaying a menu for the user to select from.

29.16 Dialog Boxes

Displaying a box to ask yes or no.

29.17 Pointer Shapes

Specifying the shape of the mouse pointer.

29.18 Window System Selections

Transferring text to and from other windows.

29.19 Color Names

Getting the definitions of color names.

29.21 X Resources

Getting resource values from the server.

29.22 Display Feature Testing

Determining the features of a terminal.

Positions

30.1 Point

The special position where editing takes place.

30.2 Motion

Changing point.

30.3 Excursions

Temporary motion and buffer changes.

30.4 Narrowing

Restricting editing to a portion of the buffer.

Motion

30.2.1 Motion by Characters

Moving in terms of characters.

30.2.2 Motion by Words

Moving in terms of words.

30.2.3 Motion to an End of the Buffer

Moving to the beginning or end of the buffer.

30.2.4 Motion by Text Lines

Moving in terms of lines of text.

30.2.5 Motion by Screen Lines

Moving in terms of lines as displayed.

30.2.6 Moving over Balanced Expressions

Moving by parsing lists and sexps.

30.2.7 Skipping Characters

Skipping characters belonging to a certain set.

Markers

31.1 Overview of Markers

The components of a marker, and how it relocates.

31.2 Predicates on Markers

Testing whether an object is a marker.

31.3 Functions that Create Markers

Making empty markers or markers at certain places.

31.4 Information from Markers

Finding the marker's buffer or character position.

31.6 Moving Marker Positions

Moving the marker to a new buffer or position.

31.7 The Mark

How "the mark" is implemented with a marker.

31.8 The Region

How to access "the region".

Text

32.1 Examining Text Near Point

Examining text in the vicinity of point.

32.2 Examining Buffer Contents

Examining text in a general fashion.

32.4 Inserting Text

Adding new text to a buffer.

32.5 User-Level Insertion Commands

User-level commands to insert text.

32.6 Deleting Text

Removing text from a buffer.

32.7 User-Level Deletion Commands

User-level commands to delete text.

32.8 The Kill Ring

Where removed text sometimes is saved for later use.

32.9 Undo

Undoing changes to the text of a buffer.

32.14 Auto Filling

How auto-fill mode is implemented to break lines.

32.11 Filling

Functions for explicit filling.

32.12 Margins for Filling

How to specify margins for filling commands.

32.15 Sorting Text

Functions for sorting parts of the buffer.

32.17 Indentation

Functions to insert or adjust indentation.

32.16 Counting Columns

Computing horizontal positions, and using them.

32.18 Case Changes

Case conversion of parts of the buffer.

32.19 Text Properties

Assigning Lisp property lists to text characters.

32.20 Substituting for a Character Code

Replacing a given character wherever it appears.

32.22 Transposition of Text

Swapping two portions of a buffer.

32.21 Registers

How registers are implemented. Accessing the text or position stored in a register.

32.25 Change Hooks

Supplying functions to be run when text is changed.

The Kill Ring

32.8.1 Kill Ring Concepts

What text looks like in the kill ring.

32.8.2 Functions for Killing

Functions that kill text.

32.8.3 Functions for Yanking

Commands that access the kill ring.

32.8.4 Low-Level Kill Ring

Functions and variables for kill ring access.

32.8.5 Internals of the Kill Ring

Variables that hold kill-ring data.

Indentation

32.17.1 Indentation Primitives

Functions used to count and insert indentation.

32.17.2 Indentation Controlled by Major Mode

Customize indentation for different modes.

32.17.3 Indenting an Entire Region

Indent all the lines in a region.

32.17.4 Indentation Relative to Previous Lines

Indent the current line based on previous lines.

32.17.5 Adjustable "Tab Stops"

Adjustable, typewriter-like tab stops.

32.17.6 Indentation-Based Motion Commands

Move to first non-blank character.

Text Properties

32.19.1 Examining Text Properties

Looking at the properties of one character.

32.19.2 Changing Text Properties

Setting the properties of a range of text.

32.19.3 Text Property Search Functions

Searching for where a property changes value.

32.19.4 Properties with Special Meanings

Particular properties with special meanings.

32.19.5 Formatted Text Properties

Properties for representing formatting of text.

32.19.6 Stickiness of Text Properties

How inserted text gets properties from neighboring text.

32.19.7 Saving Text Properties in Files

Saving text properties in files, and reading them back.

32.19.8 Lazy Computation of Text Properties

Computing text properties in a lazy fashion only when text is examined.

32.19.9 Defining Clickable Text

Using text properties to make regions of text do something when you click on them.

32.19.10 Defining and Using Fields

The field property defines fields within the buffer.

32.19.11 Why Text Properties are not Intervals

Why text properties do not use Lisp-visible text intervals.

Non-ASCII Characters

33.1 Text Representations

Unibyte and multibyte representations

33.2 Converting Text Representations

Converting unibyte to multibyte and vice versa.

33.3 Selecting a Representation

Treating a byte sequence as unibyte or multi.

33.4 Character Codes

How unibyte and multibyte relate to codes of individual characters.

33.5 Character Sets

The space of possible characters codes is divided into various character sets.

33.6 Characters and Bytes

More information about multibyte encodings.

33.7 Splitting Characters

Converting a character to its byte sequence.

33.8 Scanning for Character Sets

Which character sets are used in a buffer?

33.9 Translation of Characters

Translation tables are used for conversion.

33.10 Coding Systems

Coding systems are conversions for saving files.

33.11 Input Methods

Input methods allow users to enter various non-ASCII characters without special keyboards.

33.12 Locales

Interacting with the POSIX locale.

Searching and Matching

34.1 Searching for Strings

Search for an exact match.

34.2 Regular Expressions

Describing classes of strings.

34.3 Regular Expression Searching

Searching for a match for a regexp.

34.6 The Match Data

Finding out which part of the text matched various parts of a regexp, after regexp search.

34.6.4 Saving and Restoring the Match Data

Saving and restoring this information.

34.8 Standard Regular Expressions Used in Editing

Useful regexps for finding sentences, pages,...

34.7 Searching and Case

Case-independent or case-significant searching.

Regular Expressions

34.2.1 Syntax of Regular Expressions

Rules for writing regular expressions.

34.2.2 Complex Regexp Example

Illustrates regular expression syntax.

Syntax Tables

35.2 Syntax Descriptors

How characters are classified.

35.3 Syntax Table Functions

How to create, examine and alter syntax tables.

35.6 Parsing Balanced Expressions

Parsing balanced expressions using the syntax table.

35.7 Some Standard Syntax Tables

Syntax tables used by various major modes.

35.8 Syntax Table Internals

How syntax table information is stored.

Syntax Descriptors

35.2.1 Table of Syntax Classes

Table of syntax classes.

35.2.2 Syntax Flags

Additional flags each character can have.

Abbrevs And Abbrev Expansion

36.1 Setting Up Abbrev Mode

Setting up Emacs for abbreviation.

36.2 Abbrev Tables

Creating and working with abbrev tables.

36.3 Defining Abbrevs

Specifying abbreviations and their expansions.

36.4 Saving Abbrevs in Files

Saving abbrevs in files.

36.5 Looking Up and Expanding Abbreviations

Controlling expansion; expansion subroutines.

36.6 Standard Abbrev Tables

Abbrev tables used by various major modes.

Processes

37.1 Functions that Create Subprocesses

Functions that start subprocesses.

37.3 Creating a Synchronous Process

Details of using synchronous subprocesses.

37.4 Creating an Asynchronous Process

Starting up an asynchronous subprocess.

37.5 Deleting Processes

Eliminating an asynchronous subprocess.

37.6 Process Information

Accessing run-status and other attributes.

37.7 Sending Input to Processes

Sending input to an asynchronous subprocess.

37.8 Sending Signals to Processes

Stopping, continuing or interrupting an asynchronous subprocess.

37.9 Receiving Output from Processes

Collecting output from an asynchronous subprocess.

37.10 Sentinels: Detecting Process Status Changes

Sentinels run when process run-status changes.

37.12 Network Connections

Opening network connections.

Receiving Output from Processes

37.9.1 Process Buffers

If no filter, output is put in a buffer.

37.9.2 Process Filter Functions

Filter functions accept output from the process.

37.9.3 Accepting Output from Processes

How to wait until process output arrives.

Operating System Interface

40.1 Starting Up Emacs

Customizing Emacs start-up processing.

40.2 Getting Out of Emacs

How exiting works (permanent or temporary).

40.3 Operating System Environment

Distinguish the name and kind of system.

40.8 Terminal Input

Recording terminal input for debugging.

40.9 Terminal Output

Recording terminal output for debugging.

40.12 Flow Control

How to turn output flow control on or off.

40.13 Batch Mode

Running Emacs without terminal interaction.

Starting Up Emacs

40.1.1 Summary: Sequence of Actions at Startup

Sequence of actions Emacs performs at start-up.

40.1.2 The Init File, `.emacs'

Details on reading the init file (`.emacs').

40.1.3 Terminal-Specific Initialization

How the terminal-specific Lisp file is read.

40.1.4 Command-Line Arguments

How command line arguments are processed, and how you can customize them.

Getting out of Emacs

40.2.1 Killing Emacs

Exiting Emacs irreversibly.

40.2.2 Suspending Emacs

Exiting Emacs reversibly.

Emacs Display

38.1 Refreshing the Screen

Clearing the screen and redrawing everything on it.

38.3 Truncation

Folding or wrapping long text lines.

38.4 The Echo Area

Where messages are displayed.

38.6 Selective Display

Hiding part of the buffer text.

38.7 The Overlay Arrow

Display of an arrow to indicate position.

38.8 Temporary Displays

Displays that go away automatically.

21.9 Waiting for Elapsed Time or Input

Forcing display update and waiting for user.

38.14 Blinking Parentheses

How Emacs shows the matching open parenthesis.

38.16 Usual Display Conventions

How control characters are displayed.

38.18 Beeping

Audible signal to the user.

38.19 Window Systems

Which window system is being used.

GNU Emacs Internals

E.1 Building Emacs

How to preload Lisp libraries into Emacs.

E.2 Pure Storage

A kludge to make preloaded Lisp functions sharable.

E.3 Garbage Collection

Reclaiming space for Lisp objects no longer used.

E.6 Object Internals

Data formats of buffers, windows, processes.

E.5 Writing Emacs Primitives

Writing C code for Emacs.

Object Internals

E.6.1 Buffer Internals

Components of a buffer structure.

E.6.2 Window Internals

Components of a window structure.

E.6.3 Process Internals

Components of a process structure.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1. Introduction

Most of the GNU Emacs text editor is written in the programming language called Emacs Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor. However, Emacs Lisp is more than a mere "extension language"; it is a full computer programming language in its own right. You can use it as you would any other programming language.

Because Emacs Lisp is designed for use in an editor, it has special features for scanning and parsing text as well as features for handling files, buffers, displays, subprocesses, and so on. Emacs Lisp is closely integrated with the editing facilities; thus, editing commands are functions that can also conveniently be called from Lisp programs, and parameters for customization are ordinary Lisp variables.

This manual attempts to be a full description of Emacs Lisp. For a beginner's introduction to Emacs Lisp, see An Introduction to Emacs Lisp Programming, by Bob Chassell, also published by the Free Software Foundation. This manual presumes considerable familiarity with the use of Emacs for editing; see The GNU Emacs Manual for this basic information.

Generally speaking, the earlier chapters describe features of Emacs Lisp that have counterparts in many programming languages, and later chapters describe features that are peculiar to Emacs Lisp or relate specifically to editing.

This is edition 2.8.

1.1 Caveats

Flaws and a request for help.

1.2 Lisp History

Emacs Lisp is descended from Maclisp.

1.3 Conventions

How the manual is formatted.

1.4 Version Information

Which Emacs version is running?

1.5 Acknowledgements

The authors, editors, and sponsors of this manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.1 Caveats

This manual has gone through numerous drafts. It is nearly complete but not flawless. There are a few topics that are not covered, either because we consider them secondary (such as most of the individual modes) or because they are yet to be written. Because we are not able to deal with them completely, we have left out several parts intentionally. This includes most information about usage on VMS.

The manual should be fully correct in what it does cover, and it is therefore open to criticism on anything it says--from specific examples and descriptive text, to the ordering of chapters and sections. If something is confusing, or you find that you have to look at the sources or experiment to learn something not covered in the manual, then perhaps the manual should be fixed. Please let us know.

As you use this manual, we ask that you send corrections as soon as you find them. If you think of a simple, real life example for a function or group of functions, please make an effort to write it up and send it in. Please reference any comments to the node name and function or variable name, as appropriate. Also state the number of the edition you are criticizing.

Please mail comments and corrections to
bug-lisp-manual@gnu.org
We let mail to this list accumulate unread until someone decides to apply the corrections. Months, and sometimes years, go by between updates. So please attach no significance to the lack of a reply--your mail will be acted on in due time. If you want to contact the Emacs maintainers more quickly, send mail to bug-gnu-emacs@gnu.org.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.2 Lisp History

Lisp (LISt Processing language) was first developed in the late 1950s at the Massachusetts Institute of Technology for research in artificial intelligence. The great power of the Lisp language makes it ideal for other purposes as well, such as writing editing commands.

Dozens of Lisp implementations have been built over the years, each with its own idiosyncrasies. Many of them were inspired by Maclisp, which was written in the 1960s at MIT's Project MAC. Eventually the implementors of the descendants of Maclisp came together and developed a standard for Lisp systems, called Common Lisp. In the meantime, Gerry Sussman and Guy Steele at MIT developed a simplified but very powerful dialect of Lisp, called Scheme.

GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common Lisp. If you know Common Lisp, you will notice many similarities. However, many features of Common Lisp have been omitted or simplified in order to reduce the memory requirements of GNU Emacs. Sometimes the simplifications are so drastic that a Common Lisp user might be very confused. We will occasionally point out how GNU Emacs Lisp differs from Common Lisp. If you don't know Common Lisp, don't worry about it; this manual is self-contained.

A certain amount of Common Lisp emulation is available via the `cl' library. See section `Common Lisp Extension' in Common Lisp Extensions.

Emacs Lisp is not at all influenced by Scheme; but the GNU project has an implementation of Scheme, called Guile. We use Guile in all new GNU software that calls for extensibility.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3 Conventions

This section explains the notational conventions that are used in this manual. You may want to skip this section and refer back to it later.

1.3.1 Some Terms

Explanation of terms we use in this manual.

1.3.2 nil and t

How the symbols nil and t are used.

1.3.3 Evaluation Notation

The format we use for examples of evaluation.

1.3.4 Printing Notation

The format we use when examples print text.

1.3.5 Error Messages

The format we use for examples of errors.

1.3.6 Buffer Text Notation

The format we use for buffer contents in examples.

1.3.7 Format of Descriptions

Notation for describing functions, variables, etc.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.1 Some Terms

Throughout this manual, the phrases "the Lisp reader" and "the Lisp printer" refer to those routines in Lisp that convert textual representations of Lisp objects into actual Lisp objects, and vice versa. See section 2.1 Printed Representation and Read Syntax, for more details. You, the person reading this manual, are thought of as "the programmer" and are addressed as "you". "The user" is the person who uses Lisp programs, including those you write.

Examples of Lisp code are formatted like this: (list 1 2 3). Names that represent metasyntactic variables, or arguments to a function being described, are formatted like this: first-number.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.2 nil and t

In Lisp, the symbol nil has three separate meanings: it is a symbol with the name `nil'; it is the logical truth value false; and it is the empty list--the list of zero elements. When used as a variable, nil always has the value nil.

As far as the Lisp reader is concerned, `()' and `nil' are identical: they stand for the same object, the symbol nil. The different ways of writing the symbol are intended entirely for human readers. After the Lisp reader has read either `()' or `nil', there is no way to determine which representation was actually written by the programmer.

In this manual, we use () when we wish to emphasize that it means the empty list, and we use nil when we wish to emphasize that it means the truth value false. That is a good convention to use in Lisp programs also.
(cons 'foo ())                ; Emphasize the empty list
(not nil)                     ; Emphasize the truth value false
In contexts where a truth value is expected, any non-nil value is considered to be true. However, t is the preferred way to represent the truth value true. When you need to choose a value which represents true, and there is no other basis for choosing, use t. The symbol t always has the value t.

In Emacs Lisp, nil and t are special symbols that always evaluate to themselves. This is so that you do not need to quote them to use them as constants in a program. An attempt to change their values results in a setting-constant error. The same is true of any symbol whose name starts with a colon (`:'). See section 11.2 Variables that Never Change.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.3 Evaluation Notation

A Lisp expression that you can evaluate is called a form. Evaluating a form always produces a result, which is a Lisp object. In the examples in this manual, this is indicated with `=>':
(car '(1 2))
     => 1
You can read this as "(car '(1 2)) evaluates to 1".

When a form is a macro call, it expands into a new form for Lisp to evaluate. We show the result of the expansion with `==>'. We may or may not show the result of the evaluation of the expanded form.
(third '(a b c))
     ==> (car (cdr (cdr '(a b c))))
     => c
Sometimes to help describe one form we show another form that produces identical results. The exact equivalence of two forms is indicated with `=='.
(make-sparse-keymap) == (list 'keymap)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.4 Printing Notation

Many of the examples in this manual print text when they are evaluated. If you execute example code in a Lisp Interaction buffer (such as the buffer `*scratch*'), the printed text is inserted into the buffer. If you execute the example by other means (such as by evaluating the function eval-region), the printed text is displayed in the echo area.

Examples in this manual indicate printed text with `-|', irrespective of where that text goes. The value returned by evaluating the form (here bar) follows on a separate line.
(progn (print 'foo) (print 'bar))
     -| foo
     -| bar
     => bar
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.5 Error Messages

Some examples signal errors. This normally displays an error message in the echo area. We show the error message on a line starting with `error-->'. Note that `error-->' itself does not appear in the echo area.
(+ 23 'x)
error--> Wrong type argument: number-or-marker-p, x
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.6 Buffer Text Notation

Some examples describe modifications to the contents of a buffer, by showing the "before" and "after" versions of the text. These examples show the contents of the buffer in question between two lines of dashes containing the buffer name. In addition, `-!-' indicates the location of point. (The symbol for point, of course, is not part of the text in the buffer; it indicates the place between two characters where point is currently located.)
---------- Buffer: foo ----------
This is the -!-contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     => nil
---------- Buffer: foo ----------
This is the changed -!-contents of foo.
---------- Buffer: foo ----------
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.7 Format of Descriptions

Functions, variables, macros, commands, user options, and special forms are described in this manual in a uniform format. The first line of a description contains the name of the item followed by its arguments, if any. The category--function, variable, or whatever--appears at the beginning of the line. The description follows on succeeding lines, sometimes with examples.

1.3.7.1 A Sample Function Description

A description of an imaginary function, foo.

1.3.7.2 A Sample Variable Description

A description of an imaginary variable,

electric-future-map.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.7.1 A Sample Function Description

In a function description, the name of the function being described appears first. It is followed on the same line by a list of argument names. These names are also used in the body of the description, to stand for the values of the arguments.

The appearance of the keyword &optional in the argument list indicates that the subsequent arguments may be omitted (omitted arguments default to nil). Do not write &optional when you call the function.

The keyword &rest (which must be followed by a single argument name) indicates that any number of arguments can follow. The single following argument name will have a value, as a variable, which is a list of all these remaining arguments. Do not write &rest when you call the function.

Here is a description of an imaginary function foo:

Function: foo integer1 &optional integer2 &rest integers
The function foo subtracts integer1 from integer2, then adds all the rest of the arguments to the result. If integer2 is not supplied, then the number 19 is used by default.
(foo 1 5 3 9)
     => 16
(foo 5)
     => 14
More generally,
(foo w x y...)
==
(+ (- x w) y...)
Any argument whose name contains the name of a type (e.g., integer, integer1 or buffer) is expected to be of that type. A plural of a type (such as buffers) often means a list of objects of that type. Arguments named object may be of any type. (See section 2. Lisp Data Types, for a list of Emacs object types.) Arguments with other sorts of names (e.g., new-file) are discussed specifically in the description of the function. In some sections, features common to the arguments of several functions are described at the beginning.

See section 12.2 Lambda Expressions, for a more complete description of optional and rest arguments.

Command, macro, and special form descriptions have the same format, but the word `Function' is replaced by `Command', `Macro', or `Special Form', respectively. Commands are simply functions that may be called interactively; macros process their arguments differently from functions (the arguments are not evaluated), but are presented the same way.

Special form descriptions use a more complex notation to specify optional and repeated arguments because they can break the argument list down into separate arguments in more complicated ways. `[optional-arg]' means that optional-arg is optional and `repeated-args...' stands for zero or more arguments. Parentheses are used when several arguments are grouped into additional levels of list structure. Here is an example:

Special Form: count-loop (var [from to [inc]]) body...
This imaginary special form implements a loop that executes the body forms and then increments the variable var on each iteration. On the first iteration, the variable has the value from; on subsequent iterations, it is incremented by one (or by inc if that is given). The loop exits before executing body if var equals to. Here is an example:
(count-loop (i 0 10)
  (prin1 i) (princ " ")
  (prin1 (aref vector i))
  (terpri))
If from and to are omitted, var is bound to nil before the loop begins, and the loop exits if var is non-nil at the beginning of an iteration. Here is an example:
(count-loop (done)
  (if (pending)
      (fixit)
    (setq done t)))
In this special form, the arguments from and to are optional, but must both be present or both absent. If they are present, inc may optionally be specified as well. These arguments are grouped with the argument var into a list, to distinguish them from body, which includes all remaining elements of the form.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.3.7.2 A Sample Variable Description

A variable is a name that can hold a value. Although any variable can be set by the user, certain variables that exist specifically so that users can change them are called user options. Ordinary variables and user options are described using a format like that for functions except that there are no arguments.

Here is a description of the imaginary electric-future-map variable.

Variable: electric-future-map
The value of this variable is a full keymap used by Electric Command Future mode. The functions in this map allow you to edit commands you have not yet thought about executing.

User option descriptions have the same format, but `Variable' is replaced by `User Option'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.4 Version Information

These facilities provide information about which version of Emacs is in use.

Command: emacs-version
This function returns a string describing the version of Emacs that is running. It is useful to include this string in bug reports.
(emacs-version)
  => "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
 of Sat Feb 14 1998 on psilocin.gnu.org"
Called interactively, the function prints the same information in the echo area.

Variable: emacs-build-time
The value of this variable indicates the time at which Emacs was built at the local site. It is a list of three integers, like the value of current-time (see section 40.5 Time of Day).
emacs-build-time
     => (13623 62065 344633)
Variable: emacs-version
The value of this variable is the version of Emacs being run. It is a string such as "20.3.1". The last number in this string is not really part of the Emacs release version number; it is incremented each time you build Emacs in any given directory. A value with four numeric components, such as "20.3.9.1", indicates an unreleased test version.

The following two variables have existed since Emacs version 19.23:

Variable: emacs-major-version
The major version number of Emacs, as an integer. For Emacs version 20.3, the value is 20.

Variable: emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version 20.3, the value is 3.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1.5 Acknowledgements

This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, Richard M. Stallman and Chris Welty, the volunteers of the GNU manual group, in an effort extending over several years. Robert J. Chassell helped to review and edit the manual, with the support of the Defense Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren A. Hunt, Jr. of Computational Logic, Inc.

Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Per Starbäck, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2. Lisp Data Types

A Lisp object is a piece of data used and manipulated by Lisp programs. For our purposes, a type or data type is a set of possible objects.

Every object belongs to at least one type. Objects of the same type have similar structures and may usually be used in the same contexts. Types can overlap, and objects can belong to two or more types. Consequently, we can ask whether an object belongs to a particular type, but not for "the" type of an object.

A few fundamental object types are built into Emacs. These, from which all other types are constructed, are called primitive types. Each object belongs to one and only one primitive type. These types include integer, float, cons, symbol, string, vector, hash-table, subr, and byte-code function, plus several special types, such as buffer, that are related to editing. (See section 2.4 Editing Types.)

Each primitive type has a corresponding Lisp function that checks whether an object is a member of that type.

Note that Lisp is unlike many other languages in that Lisp objects are self-typing: the primitive type of the object is implicit in the object itself. For example, if an object is a vector, nothing can treat it as a number; Lisp knows it is a vector, not a number.

In most languages, the programmer must declare the data type of each variable, and the type is known by the compiler but not represented in the data. Such type declarations do not exist in Emacs Lisp. A Lisp variable can have any type of value, and it remembers whatever value you store in it, type and all.

This chapter describes the purpose, printed representation, and read syntax of each of the standard types in GNU Emacs Lisp. Details on how to use these types can be found in later chapters.

2.1 Printed Representation and Read Syntax

How Lisp objects are represented as text.

2.2 Comments

Comments and their formatting conventions.

2.3 Programming Types

Types found in all Lisp systems.

2.4 Editing Types

Types specific to Emacs.

2.5 Read Syntax for Circular Objects

Read syntax for circular structure.

2.6 Type Predicates

Tests related to types.

2.7 Equality Predicates

Tests of equality between any two objects.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.1 Printed Representation and Read Syntax

The printed representation of an object is the format of the output generated by the Lisp printer (the function prin1) for that object. The read syntax of an object is the format of the input accepted by the Lisp reader (the function read) for that object. See section 19. Reading and Printing Lisp Objects.

Most objects have more than one possible read syntax. Some types of object have no read syntax, since it may not make sense to enter objects of these types directly in a Lisp program. Except for these cases, the printed representation of an object is also a read syntax for it.

In other languages, an expression is text; it has no other form. In Lisp, an expression is primarily a Lisp object and only secondarily the text that is the object's read syntax. Often there is no need to emphasize this distinction, but you must keep it in the back of your mind, or you will occasionally be very confused.

Every type has a printed representation. Some types have no read syntax--for example, the buffer type has none. Objects of these types are printed in hash notation: the characters `#<' followed by a descriptive string (typically the type name followed by the name of the object), and closed with a matching `>'. Hash notation cannot be read at all, so the Lisp reader signals the error invalid-read-syntax whenever it encounters `#<'.
(current-buffer)
     => #<buffer objects.texi>
When you evaluate an expression interactively, the Lisp interpreter first reads the textual representation of it, producing a Lisp object, and then evaluates that object (see section 9. Evaluation). However, evaluation and reading are separate activities. Reading returns the Lisp object represented by the text that is read; the object may or may not be evaluated later. See section 19.3 Input Functions, for a description of read, the basic function for reading objects.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.2 Comments

A comment is text that is written in a program only for the sake of humans that read the program, and that has no effect on the meaning of the program. In Lisp, a semicolon (`;') starts a comment if it is not within a string or character constant. The comment continues to the end of line. The Lisp reader discards comments; they do not become part of the Lisp objects which represent the program within the Lisp system.

The `#@count' construct, which skips the next count characters, is useful for program-generated comments containing binary data. The Emacs Lisp byte compiler uses this in its output files (see section 16. Byte Compilation). It isn't meant for source files, however.

See section D.4 Tips on Writing Comments, for conventions for formatting comments.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3 Programming Types

There are two general categories of types in Emacs Lisp: those having to do with Lisp programming, and those having to do with editing. The former exist in many Lisp implementations, in one form or another. The latter are unique to Emacs Lisp.

2.3.1 Integer Type

Numbers without fractional parts.

2.3.2 Floating Point Type

Numbers with fractional parts and with a large range.

2.3.3 Character Type

The representation of letters, numbers and control characters.

2.3.4 Symbol Type

A multi-use object that refers to a function, variable, or property list, and has a unique identity.

2.3.5 Sequence Types

Both lists and arrays are classified as sequences.

2.3.6 Cons Cell and List Types

Cons cells, and lists (which are made from cons cells).

2.3.7 Array Type

Arrays include strings and vectors.

2.3.8 String Type

An (efficient) array of characters.

2.3.9 Vector Type

One-dimensional arrays.

2.3.10 Char-Table Type

One-dimensional sparse arrays indexed by characters.

2.3.11 Bool-Vector Type

One-dimensional arrays of t or nil.

2.3.12 Hash Table Type

Super-fast lookup tables.

2.3.13 Function Type

A piece of executable code you can call from elsewhere.

2.3.14 Macro Type

A method of expanding an expression into another expression, more fundamental but less pretty.

2.3.15 Primitive Function Type

A function written in C, callable from Lisp.

2.3.16 Byte-Code Function Type

A function written in Lisp, then compiled.

2.3.17 Autoload Type

A type used for automatically loading seldom-used functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.1 Integer Type

The range of values for integers in Emacs Lisp is -134217728 to 134217727 (28 bits; i.e., -2**27 to 2**27 - 1) on most machines. (Some machines may provide a wider range.) It is important to note that the Emacs Lisp arithmetic functions do not check for overflow. Thus (1+ 134217727) is -134217728 on most machines.

The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The printed representation produced by the Lisp interpreter never has a leading `+' or a final `.'.
-1               ; The integer -1.
1                ; The integer 1.
1.               ; Also the integer 1.
+1               ; Also the integer 1.
268435457        ; Also the integer 1 on a 28-bit implementation.
See section 3. Numbers, for more information.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.2 Floating Point Type

Floating point numbers are the computer equivalent of scientific notation. The precise number of significant figures and the range of possible exponents is machine-specific; Emacs always uses the C data type double to store the value.

The printed representation for floating point numbers requires either a decimal point (with at least one digit following), an exponent, or both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4' are five ways of writing a floating point number whose value is 1500. They are all equivalent.

See section 3. Numbers, for more information.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.3 Character Type

A character in Emacs Lisp is nothing more than an integer. In other words, characters are represented by their character codes. For example, the character A is represented as the integer 65.

Individual characters are not often used in programs. It is far more common to work with strings, which are sequences composed of characters. See section 2.3.8 String Type.

Characters in strings, buffers, and files are currently limited to the range of 0 to 524287--nineteen bits. But not all values in that range are valid character codes. Codes 0 through 127 are ASCII codes; the rest are non-ASCII (see section 33. Non-ASCII Characters). Characters that represent keyboard input have a much wider range, to encode modifier keys such as Control, Meta and Shift.

Since characters are really integers, the printed representation of a character is a decimal number. This is also a possible read syntax for a character, but writing characters that way in Lisp programs is a very bad idea. You should always use the special read syntax formats that Emacs Lisp provides for characters. These syntax formats start with a question mark.

The usual read syntax for alphanumeric characters is a question mark followed by the character; thus, `?A' for the character A, `?B' for the character B, and `?a' for the character a.

For example:
?Q => 81     ?q => 113
You can use the same syntax for punctuation characters, but it is often a good idea to add a `\' so that the Emacs commands for editing Lisp code don't get confused. For example, `?\ ' is the way to write the space character. If the character is `\', you must use a second `\' to quote it: `?\\'.

You can express the characters Control-g, backspace, tab, newline, vertical tab, formfeed, return, del, and escape as `?\a', `?\b', `?\t', `?\n', `?\v', `?\f', `?\r', `?\d', and `?\e', respectively. Thus,
?\a => 7                 ; C-g
?\b => 8                 ; backspace, BS, C-h
?\t => 9                 ; tab, TAB, C-i
?\n => 10                ; newline, C-j
?\v => 11                ; vertical tab, C-k
?\f => 12                ; formfeed character, C-l
?\r => 13                ; carriage return, RET, C-m
?\e => 27                ; escape character, ESC, C-[
?\\ => 92                ; backslash character, \
?\d => 127               ; delete character, DEL
These sequences which start with backslash are also known as escape sequences, because backslash plays the role of an escape character; this usage has nothing to do with the character ESC.

Control characters may be represented using yet another read syntax. This consists of a question mark followed by a backslash, caret, and the corresponding non-control character, in either upper or lower case. For example, both `?\^I' and `?\^i' are valid read syntax for the character C-i, the character whose value is 9.

Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to `?\^I' and to `?\^i':
?\^I => 9     ?\C-I => 9
In strings and buffers, the only control characters allowed are those that exist in ASCII; but for keyboard input purposes, you can turn any character into a control character with `C-'. The character codes for these non-ASCII control characters include the 2**26 bit as well as the code for the corresponding non-control character. Ordinary terminals have no way of generating non-ASCII control characters, but you can generate them straightforwardly using X and other window systems.

For historical reasons, Emacs treats the DEL character as the control equivalent of ?:
?\^? => 127     ?\C-? => 127
As a result, it is currently not possible to represent the character Control-?, which is a meaningful input character under X, using `\C-'. It is not easy to change this, as various Lisp files refer to DEL in this way.

For representing control characters to be found in files or strings, we recommend the `^' syntax; for control characters in keyboard input, we prefer the `C-' syntax. Which one you use does not affect the meaning of the program, but may guide the understanding of people who read it.

A meta character is a character typed with the META modifier key. The integer that represents such a character has the 2**27 bit set (which on most machines makes it a negative number). We use high bits for this and other modifiers to make possible a wide range of basic character codes.

In a string, the 2**7 bit attached to an ASCII character indicates a meta character; thus, the meta characters that can fit in a string have codes in the range from 128 to 255, and are the meta versions of the ordinary ASCII characters. (In Emacs versions 18 and older, this convention was used for characters outside of strings as well.)

The read syntax for meta characters uses `\M-'. For example, `?\M-A' stands for M-A. You can use `\M-' together with octal character codes (see below), with `\C-', or with any other syntax for a character. Thus, you can write M-A as `?\M-A', or as `?\M-\101'. Likewise, you can write C-M-b as `?\M-\C-b', `?\C-\M-b', or `?\M-\002'.

The case of a graphic character is indicated by its character code; for example, ASCII distinguishes between the characters `a' and `A'. But ASCII has no way to represent whether a control character is upper case or lower case. Emacs uses the 2**25 bit to indicate that the shift key was used in typing a control character. This distinction is possible only when you use X terminals or other special terminals; ordinary terminals do not report the distinction to the computer in any way. The Lisp syntax for the shift bit is `\S-'; thus, `?\C-\S-o' or `?\C-\S-O' represents the shifted-control-o character.

The X Window System defines three other modifier bits that can be set in a character: hyper, super and alt. The syntaxes for these bits are `\H-', `\s-' and `\A-'. (Case is significant in these prefixes.) Thus, `?\H-\M-\A-x' represents Alt-Hyper-Meta-x. Numerically, the bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.

Finally, the most general read syntax for a character represents the character code in either octal or hex. To use octal, write a question mark followed by a backslash and the octal character code (up to three octal digits); thus, `?\101' for the character A, `?\001' for the character C-a, and ?\002 for the character C-b. Although this syntax can represent any ASCII character, it is preferred only when the precise octal value is more important than the ASCII representation.
?\012 => 10         ?\n => 10         ?\C-j => 10
?\101 => 65         ?A => 65
To use hex, write a question mark followed by a backslash, `x', and the hexadecimal character code. You can use any number of hex digits, so you can represent any character code in this way. Thus, `?\x41' for the character A, `?\x1' for the character C-a, and ?\x8e0 for the Latin-1 character `a' with grave accent.

A backslash is allowed, and harmless, preceding any character without a special escape meaning; thus, `?\+' is equivalent to `?+'. There is no reason to add a backslash before most characters. However, you should add a backslash before any of the characters `()\|;'`"#.,' to avoid confusing the Emacs commands for editing Lisp code. Also add a backslash before whitespace characters such as space, tab, newline and formfeed. However, it is cleaner to use one of the easily readable escape sequences, such as `\t', instead of an actual whitespace character such as a tab.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.4 Symbol Type

A symbol in GNU Emacs Lisp is an object with a name. The symbol name serves as the printed representation of the symbol. In ordinary use, the name is unique--no two symbols have the same name.

A symbol can serve as a variable, as a function name, or to hold a property list. Or it may serve only to be distinct from all other Lisp objects, so that its presence in a data structure may be recognized reliably. In a given context, usually only one of these uses is intended. But you can use one symbol in all of these ways, independently.

A symbol whose name starts with a colon (`:') is called a keyword symbol. These symbols automatically act as constants, and are normally used only by comparing an unknown symbol with a few specific alternatives.

A symbol name can contain any characters whatever. Most symbol names are written with letters, digits, and the punctuation characters `-+=*/'. Such names require no special punctuation; the characters of the name suffice as long as the name does not look like a number. (If it does, write a `\' at the beginning of the name to force interpretation as a symbol.) The characters `_~!@$%^&:<>{}?' are less often used but also require no special punctuation. Any other characters may be included in a symbol's name by escaping them with a backslash. In contrast to its use in strings, however, a backslash in the name of a symbol simply quotes the single character that follows the backslash. For example, in a string, `\t' represents a tab character; in the name of a symbol, however, `\t' merely quotes the letter `t'. To have a symbol with a tab character in its name, you must actually use a tab (preceded with a backslash). But it's rare to do such a thing.

Common Lisp note: In Common Lisp, lower case letters are always "folded" to upper case, unless they are explicitly escaped. In Emacs Lisp, upper case and lower case letters are distinct.

Here are several examples of symbol names. Note that the `+' in the fifth example is escaped to prevent it from being read as a number. This is not necessary in the sixth example because the rest of the name makes it invalid as a number.
foo                 ; A symbol named `foo'.
FOO                 ; A symbol named `FOO', different from `foo'.
char-to-string      ; A symbol named `char-to-string'.
1+                  ; A symbol named `1+'
                    ;   (not `+1', which is an integer).
\+1                 ; A symbol named `+1'
                    ;   (not a very readable name).
\(*\ 1\ 2\)         ; A symbol named `(* 1 2)' (a worse name).
+-*/_~!@$%^&=:<>{}  ; A symbol named `+-*/_~!@$%^&=:<>{}'.
                    ;   These characters need not be escaped.
Normally the Lisp reader interns all symbols (see section 8.3 Creating and Interning Symbols). To prevent interning, you can write `#:' before the name of the symbol.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.5 Sequence Types

A sequence is a Lisp object that represents an ordered set of elements. There are two kinds of sequence in Emacs Lisp, lists and arrays. Thus, an object of type list or of type array is also considered a sequence.

Arrays are further subdivided into strings, vectors, char-tables and bool-vectors. Vectors can hold elements of any type, but string elements must be characters, and bool-vector elements must be t or nil. Char-tables are like vectors except that they are indexed by any valid character code. The characters in a string can have text properties like characters in a buffer (see section 32.19 Text Properties), but vectors do not support text properties, even when their elements happen to be characters.

Lists, strings and the other array types are different, but they have important similarities. For example, all have a length l, and all have elements which can be indexed from zero to l minus one. Several functions, called sequence functions, accept any kind of sequence. For example, the function elt can be used to extract an element of a sequence, given its index. See section 6. Sequences, Arrays, and Vectors.

It is generally impossible to read the same sequence twice, since sequences are always created anew upon reading. If you read the read syntax for a sequence twice, you get two sequences with equal contents. There is one exception: the empty list () always stands for the same object, nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.6 Cons Cell and List Types

A cons cell is an object that consists of two slots, called the CAR slot and the CDR slot. Each slot can hold or refer to any Lisp object. We also say that "the CAR of this cons cell is" whatever object its CAR slot currently holds, and likewise for the CDR.

A note to C programmers: in Lisp, we do not distinguish between "holding" a value and "pointing to" the value, because pointers in Lisp are implicit.

A list is a series of cons cells, linked together so that the CDR slot of each cons cell holds either the next cons cell or the empty list. See section 5. Lists, for functions that work on lists. Because most cons cells are used as part of lists, the phrase list structure has come to refer to any structure made out of cons cells.

The names CAR and CDR derive from the history of Lisp. The original Lisp implementation ran on an IBM 704 computer which divided words into two parts, called the "address" part and the "decrement"; CAR was an instruction to extract the contents of the address part of a register, and CDR an instruction to extract the contents of the decrement. By contrast, "cons cells" are named for the function cons that creates them, which in turn was named for its purpose, the construction of cells.

Because cons cells are so central to Lisp, we also have a word for "an object which is not a cons cell". These objects are called atoms.

The read syntax and printed representation for lists are identical, and consist of a left parenthesis, an arbitrary number of elements, and a right parenthesis.

Upon reading, each object inside the parentheses becomes an element of the list. That is, a cons cell is made for each element. The CAR slot of the cons cell holds the element, and its CDR slot refers to the next cons cell of the list, which holds the next element in the list. The CDR slot of the last cons cell is set to hold nil.

A list can be illustrated by a diagram in which the cons cells are shown as pairs of boxes, like dominoes. (The Lisp reader cannot read such an illustration; unlike the textual notation, which can be understood by both humans and computers, the box illustrations can be understood only by humans.) This picture represents the three-element list (rose violet buttercup):
    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup
In this diagram, each box represents a slot that can hold or refer to any Lisp object. Each pair of boxes represents a cons cell. Each arrow represents a reference to a Lisp object, either an atom or another cons cell.

In this example, the first box, which holds the CAR of the first cons cell, refers to or "holds" rose (a symbol). The second box, holding the CDR of the first cons cell, refers to the next pair of boxes, the second cons cell. The CAR of the second cons cell is violet, and its CDR is the third cons cell. The CDR of the third (and last) cons cell is nil.

Here is another diagram of the same list, (rose violet buttercup), sketched in a different manner:
 ---------------       ----------------       -------------------
| car   | cdr   |     | car    | cdr   |     | car       | cdr   |
| rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
|       |       |     |        |       |     |           |       |
 ---------------       ----------------       -------------------
A list with no elements in it is the empty list; it is identical to the symbol nil. In other words, nil is both a symbol and a list.

Here are examples of lists written in Lisp syntax:
(A 2 "A")            ; A list of three elements.
()                   ; A list of no elements (the empty list).
nil                  ; A list of no elements (the empty list).
("A ()")             ; A list of one element: the string "A ()".
(A ())               ; A list of two elements: A and the empty list.
(A nil)              ; Equivalent to the previous.
((A B C))            ; A list of one element
                     ;   (which is a list of three elements).
Here is the list (A ()), or equivalently (A nil), depicted with boxes and arrows:
    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> A        --> nil
2.3.6.1 Dotted Pair Notation

An alternative syntax for lists.

2.3.6.2 Association List Type

A specially constructed list.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.6.1 Dotted Pair Notation

Dotted pair notation is an alternative syntax for cons cells that represents the CAR and CDR explicitly. In this syntax, (a . b) stands for a cons cell whose CAR is the object a, and whose CDR is the object b. Dotted pair notation is therefore more general than list syntax. In the dotted pair notation, the list `(1 2 3)' is written as `(1 . (2 . (3 . nil)))'. For nil-terminated lists, you can use either notation, but list notation is usually clearer and more convenient. When printing a list, the dotted pair notation is only used if the CDR of a cons cell is not a list.

Here's an example using boxes to illustrate dotted pair notation. This example shows the pair (rose . violet):
    --- ---
   |   |   |--> violet
    --- ---
     |
     |
      --> rose
You can combine dotted pair notation with list notation to represent conveniently a chain of cons cells with a non-nil final CDR. You write a dot after the last element of the list, followed by the CDR of the final cons cell. For example, (rose violet . buttercup) is equivalent to (rose . (violet . buttercup)). The object looks like this:
    --- ---      --- ---
   |   |   |--> |   |   |--> buttercup
    --- ---      --- ---
     |            |
     |            |
      --> rose     --> violet
The syntax (rose . violet . buttercup) is invalid because there is nothing that it could mean. If anything, it would say to put buttercup in the CDR of a cons cell whose CDR is already used for violet.

The list (rose violet) is equivalent to (rose . (violet)), and looks like this:
    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> rose     --> violet
Similarly, the three-element list (rose violet buttercup) is equivalent to (rose . (violet . (buttercup))). It looks like this:
    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.6.2 Association List Type

An association list or alist is a specially-constructed list whose elements are cons cells. In each element, the CAR is considered a key, and the CDR is considered an associated value. (In some cases, the associated value is stored in the CAR of the CDR.) Association lists are often used as stacks, since it is easy to add or remove associations at the front of the list.

For example,
(setq alist-of-colors
      '((rose . red) (lily . white) (buttercup . yellow)))
sets the variable alist-of-colors to an alist of three elements. In the first element, rose is the key and red is the value.

See section 5.8 Association Lists, for a further explanation of alists and for functions that work on alists. See section 7. Hash Tables, for another kind of lookup table, which is much faster for handling a large number of keys.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.7 Array Type

An array is composed of an arbitrary number of slots for holding or referring to other Lisp objects, arranged in a contiguous block of memory. Accessing any element of an array takes approximately the same amount of time. In contrast, accessing an element of a list requires time proportional to the position of the element in the list. (Elements at the end of a list take longer to access than elements at the beginning of a list.)

Emacs defines four types of array: strings, vectors, bool-vectors, and char-tables.

A string is an array of characters and a vector is an array of arbitrary objects. A bool-vector can hold only t or nil. These kinds of array may have any length up to the largest integer. Char-tables are sparse arrays indexed by any valid character code; they can hold arbitrary objects.

The first element of an array has index zero, the second element has index 1, and so on. This is called zero-origin indexing. For example, an array of four elements has indices 0, 1, 2, and 3. The largest possible index value is one less than the length of the array. Once an array is created, its length is fixed.

All Emacs Lisp arrays are one-dimensional. (Most other programming languages support multidimensional arrays, but they are not essential; you can get the same effect with an array of arrays.) Each type of array has its own read syntax; see the following sections for details.

The array type is contained in the sequence type and contains the string type, the vector type, the bool-vector type, and the char-table type.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.8 String Type

A string is an array of characters. Strings are used for many purposes in Emacs, as can be expected in a text editor; for example, as the names of Lisp symbols, as messages for the user, and to represent text extracted from buffers. Strings in Lisp are constants: evaluation of a string returns the same string.

See section 4. Strings and Characters, for functions that operate on strings.

2.3.8.1 Syntax for Strings

2.3.8.2 Non-ASCII Characters in Strings

2.3.8.3 Nonprinting Characters in Strings

2.3.8.4 Text Properties in Strings

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.8.1 Syntax for Strings

The read syntax for strings is a double-quote, an arbitrary number of characters, and another double-quote, "like this". To include a double-quote in a string, precede it with a backslash; thus, "\"" is a string containing just a single double-quote character. Likewise, you can include a backslash by preceding it with another backslash, like this: "this \\ is a single embedded backslash".

The newline character is not special in the read syntax for strings; if you write a new line between the double-quotes, it becomes a character in the string. But an escaped newline--one that is preceded by `\'---does not become part of the string; i.e., the Lisp reader ignores an escaped newline while reading a string. An escaped space `\ ' is likewise ignored.
"It is useful to include newlines
in documentation strings,
but the newline is \
ignored if escaped."
     => "It is useful to include newlines
in documentation strings,
but the newline is ignored if escaped."
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.8.2 Non-ASCII Characters in Strings

You can include a non-ASCII international character in a string constant by writing it literally. There are two text representations for non-ASCII characters in Emacs strings (and in buffers): unibyte and multibyte. If the string constant is read from a multibyte source, such as a multibyte buffer or string, or a file that would be visited as multibyte, then the character is read as a multibyte character, and that makes the string multibyte. If the string constant is read from a unibyte source, then the character is read as unibyte and that makes the string unibyte.

You can also represent a multibyte non-ASCII character with its character code: use a hex escape, `\xnnnnnnn', with as many digits as necessary. (Multibyte non-ASCII character codes are all greater than 256.) Any character which is not a valid hex digit terminates this construct. If the next character in the string could be interpreted as a hex digit, write `\ ' (backslash and space) to terminate the hex escape--for example, `\x8e0\ ' represents one character, `a' with grave accent. `\ ' in a string constant is just like backslash-newline; it does not contribute any character to the string, but it does terminate the preceding hex escape.

Using a multibyte hex escape forces the string to multibyte. You can represent a unibyte non-ASCII character with its character code, which must be in the range from 128 (0200 octal) to 255 (0377 octal). This forces a unibyte string. See section 33.1 Text Representations, for more information about the two text representations.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.8.3 Nonprinting Characters in Strings

You can use the same backslash escape-sequences in a string constant as in character literals (but do not use the question mark that begins a character constant). For example, you can write a string containing the nonprinting characters tab and C-a, with commas and spaces between them, like this: "\t, \C-a". See section 2.3.3 Character Type, for a description of the read syntax for characters.

However, not all of the characters you can write with backslash escape-sequences are valid in strings. The only control characters that a string can hold are the ASCII control characters. Strings do not distinguish case in ASCII control characters.

Properly speaking, strings cannot hold meta characters; but when a string is to be used as a key sequence, there is a special convention that provides a way to represent meta versions of ASCII characters in a string. If you use the `\M-' syntax to indicate a meta character in a string constant, this sets the 2**7 bit of the character in the string. If the string is used in define-key or lookup-key, this numeric code is translated into the equivalent meta character. See section 2.3.3 Character Type.

Strings cannot hold characters that have the hyper, super, or alt modifiers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.8.4 Text Properties in Strings

A string can hold properties for the characters it contains, in addition to the characters themselves. This enables programs that copy text between strings and buffers to copy the text's properties with no special effort. See section 32.19 Text Properties, for an explanation of what text properties mean. Strings with text properties use a special read and print syntax:
#("characters" property-data...)
where property-data consists of zero or more elements, in groups of three as follows:
beg end plist
The elements beg and end are integers, and together specify a range of indices in the string; plist is the property list for that range. For example,
#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
represents a string whose textual contents are `foo bar', in which the first three characters have a face property with value bold, and the last three have a face property with value italic. (The fourth character has no text properties, so its property list is nil. It is not actually necessary to mention ranges with nil as the property list, since any characters not mentioned in any range will default to having no properties.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.9 Vector Type

A vector is a one-dimensional array of elements of any type. It takes a constant amount of time to access any element of a vector. (In a list, the access time of an element is proportional to the distance of the element from the beginning of the list.)

The printed representation of a vector consists of a left square bracket, the elements, and a right square bracket. This is also the read syntax. Like numbers and strings, vectors are considered constants for evaluation.
[1 "two" (three)]      ; A vector of three elements.
     => [1 "two" (three)]
See section 6.4 Vectors, for functions that work with vectors.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.10 Char-Table Type

A char-table is a one-dimensional array of elements of any type, indexed by character codes. Char-tables have certain extra features to make them more useful for many jobs that involve assigning information to character codes--for example, a char-table can have a parent to inherit from, a default value, and a small number of extra slots to use for special purposes. A char-table can also specify a single value for a whole character set.

The printed representation of a char-table is like a vector except that there is an extra `#^' at the beginning.

See section 6.6 Char-Tables, for special functions to operate on char-tables. Uses of char-tables include:

Case tables (see section 4.9 The Case Table).

Character category tables (see section 35.9 Categories).

Display tables (see section 38.17 Display Tables).

Syntax tables (see section 35. Syntax Tables).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.11 Bool-Vector Type

A bool-vector is a one-dimensional array of elements that must be t or nil.

The printed representation of a bool-vector is like a string, except that it begins with `#&' followed by the length. The string constant that follows actually specifies the contents of the bool-vector as a bitmap--each "character" in the string contains 8 bits, which specify the next 8 elements of the bool-vector (1 stands for t, and 0 for nil). The least significant bits of the character correspond to the lowest indices in the bool-vector. If the length is not a multiple of 8, the printed representation shows extra elements, but these extras really make no difference.
(make-bool-vector 3 t)
     => #&3"\007"
(make-bool-vector 3 nil)
     => #&3"\0"
;; These are equal since only the first 3 bits are used.
(equal #&3"\377" #&3"\007")
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.12 Hash Table Type

A hash table is a very fast kind of lookup table, somewhat like an alist in that it maps keys to corresponding values, but much faster. Hash tables are a new feature in Emacs 21; they have no read syntax, and print using hash notation. See section 7. Hash Tables.
(make-hash-table)
     => #<hash-table 'eql nil 0/65 0x83af980>
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.13 Function Type

Just as functions in other programming languages are executable, Lisp function objects are pieces of executable code. However, functions in Lisp are primarily Lisp objects, and only secondarily the text which represents them. These Lisp objects are lambda expressions: lists whose first element is the symbol lambda (see section 12.2 Lambda Expressions).

In most programming languages, it is impossible to have a function without a name. In Lisp, a function has no intrinsic name. A lambda expression is also called an anonymous function (see section 12.7 Anonymous Functions). A named function in Lisp is actually a symbol with a valid function in its function cell (see section 12.4 Defining Functions).

Most of the time, functions are called when their names are written in Lisp expressions in Lisp programs. However, you can construct or obtain a function object at run time and then call it with the primitive functions funcall and apply. See section 12.5 Calling Functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.14 Macro Type

A Lisp macro is a user-defined construct that extends the Lisp language. It is represented as an object much like a function, but with different argument-passing semantics. A Lisp macro has the form of a list whose first element is the symbol macro and whose CDR is a Lisp function object, including the lambda symbol.

Lisp macro objects are usually defined with the built-in defmacro function, but any list that begins with macro is a macro as far as Emacs is concerned. See section 13. Macros, for an explanation of how to write a macro.

Warning: Lisp macros and keyboard macros (see section 21.15 Keyboard Macros) are entirely different things. When we use the word "macro" without qualification, we mean a Lisp macro, not a keyboard macro.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.15 Primitive Function Type

A primitive function is a function callable from Lisp but written in the C programming language. Primitive functions are also called subrs or built-in functions. (The word "subr" is derived from "subroutine".) Most primitive functions evaluate all their arguments when they are called. A primitive function that does not evaluate all its arguments is called a special form (see section 9.2.7 Special Forms).

It does not matter to the caller of a function whether the function is primitive. However, this does matter if you try to redefine a primitive with a function written in Lisp. The reason is that the primitive function may be called directly from C code. Calls to the redefined function from Lisp will use the new definition, but calls from C code may still use the built-in definition. Therefore, we discourage redefinition of primitive functions.

The term function refers to all Emacs functions, whether written in Lisp or C. See section 2.3.13 Function Type, for information about the functions written in Lisp.

Primitive functions have no read syntax and print in hash notation with the name of the subroutine.
(symbol-function 'car)          ; Access the function cell
                                ;   of the symbol.
     => #<subr car>
(subrp (symbol-function 'car))  ; Is this a primitive function?
     => t                       ; Yes.
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.16 Byte-Code Function Type

The byte compiler produces byte-code function objects. Internally, a byte-code function object is much like a vector; however, the evaluator handles this data type specially when it appears as a function to be called. See section 16. Byte Compilation, for information about the byte compiler.

The printed representation and read syntax for a byte-code function object is like that for a vector, with an additional `#' before the opening `['.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.3.17 Autoload Type

An autoload object is a list whose first element is the symbol autoload. It is stored as the function definition of a symbol, where it serves as a placeholder for the real definition. The autoload object says that the real definition is found in a file of Lisp code that should be loaded when necessary. It contains the name of the file, plus some other information about the real definition.

After the file has been loaded, the symbol should have a new function definition that is not an autoload object. The new definition is then called as if it had been there to begin with. From the user's point of view, the function call works as expected, using the function definition in the loaded file.

An autoload object is usually created with the function autoload, which stores the object in the function cell of a symbol. See section 15.4 Autoload, for more details.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4 Editing Types

The types in the previous section are used for general programming purposes, and most of them are common to most Lisp dialects. Emacs Lisp provides several additional data types for purposes connected with editing.

2.4.1 Buffer Type

The basic object of editing.

2.4.2 Marker Type

A position in a buffer.

2.4.3 Window Type

Buffers are displayed in windows.

2.4.4 Frame Type

Windows subdivide frames.

2.4.5 Window Configuration Type

Recording the way a frame is subdivided.

2.4.6 Frame Configuration Type

Recording the status of all frames.

2.4.7 Process Type

A process running on the underlying OS.

2.4.8 Stream Type

Receive or send characters.

2.4.9 Keymap Type

What function a keystroke invokes.

2.4.10 Overlay Type

How an overlay is represented.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.1 Buffer Type

A buffer is an object that holds text that can be edited (see section 27. Buffers). Most buffers hold the contents of a disk file (see section 25. Files) so they can be edited, but some are used for other purposes. Most buffers are also meant to be seen by the user, and therefore displayed, at some time, in a window (see section 28. Windows). But a buffer need not be displayed in any window.

The contents of a buffer are much like a string, but buffers are not used like strings in Emacs Lisp, and the available operations are different. For example, you can insert text efficiently into an existing buffer, altering the buffer's contents, whereas "inserting" text into a string requires concatenating substrings, and the result is an entirely new string object.

Each buffer has a designated position called point (see section 30. Positions). At any time, one buffer is the current buffer. Most editing commands act on the contents of the current buffer in the neighborhood of point. Many of the standard Emacs functions manipulate or test the characters in the current buffer; a whole chapter in this manual is devoted to describing these functions (see section 32. Text).

Several other data structures are associated with each buffer:

a local syntax table (see section 35. Syntax Tables);

a local keymap (see section 22. Keymaps); and,

a list of buffer-local variable bindings (see section 11.10 Buffer-Local Variables).

overlays (see section 38.9 Overlays).

text properties for the text in the buffer (see section 32.19 Text Properties).

The local keymap and variable list contain entries that individually override global bindings or values. These are used to customize the behavior of programs in different buffers, without actually changing the programs.

A buffer may be indirect, which means it shares the text of another buffer, but presents it differently. See section 27.11 Indirect Buffers.

Buffers have no read syntax. They print in hash notation, showing the buffer name.
(current-buffer)
     => #<buffer objects.texi>
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.2 Marker Type

A marker denotes a position in a specific buffer. Markers therefore have two components: one for the buffer, and one for the position. Changes in the buffer's text automatically relocate the position value as necessary to ensure that the marker always points between the same two characters in the buffer.

Markers have no read syntax. They print in hash notation, giving the current character position and the name of the buffer.
(point-marker)
     => #<marker at 10779 in objects.texi>
See section 31. Markers, for information on how to test, create, copy, and move markers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.3 Window Type

A window describes the portion of the terminal screen that Emacs uses to display a buffer. Every window has one associated buffer, whose contents appear in the window. By contrast, a given buffer may appear in one window, no window, or several windows.

Though many windows may exist simultaneously, at any time one window is designated the selected window. This is the window where the cursor is (usually) displayed when Emacs is ready for a command. The selected window usually displays the current buffer, but this is not necessarily the case.

Windows are grouped on the screen into frames; each window belongs to one and only one frame. See section 2.4.4 Frame Type.

Windows have no read syntax. They print in hash notation, giving the window number and the name of the buffer being displayed. The window numbers exist to identify windows uniquely, since the buffer displayed in any given window can change frequently.
(selected-window)
     => #<window 1 on objects.texi>
See section 28. Windows, for a description of the functions that work on windows.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.4 Frame Type

A frame is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window) which you can subdivide vertically or horizontally into smaller windows.

Frames have no read syntax. They print in hash notation, giving the frame's title, plus its address in core (useful to identify the frame uniquely).
(selected-frame)
     => #<frame emacs@psilocin.gnu.org 0xdac80>
See section 29. Frames, for a description of the functions that work on frames.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.5 Window Configuration Type

A window configuration stores information about the positions, sizes, and contents of the windows in a frame, so you can recreate the same arrangement of windows later.

Window configurations do not have a read syntax; their print syntax looks like `#<window-configuration>'. See section 28.17 Window Configurations, for a description of several functions related to window configurations.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.6 Frame Configuration Type

A frame configuration stores information about the positions, sizes, and contents of the windows in all frames. It is actually a list whose CAR is frame-configuration and whose CDR is an alist. Each alist element describes one frame, which appears as the CAR of that element.

See section 29.12 Frame Configurations, for a description of several functions related to frame configurations.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.7 Process Type

The word process usually means a running program. Emacs itself runs in a process of this sort. However, in Emacs Lisp, a process is a Lisp object that designates a subprocess created by the Emacs process. Programs such as shells, GDB, ftp, and compilers, running in subprocesses of Emacs, extend the capabilities of Emacs.

An Emacs subprocess takes textual input from Emacs and returns textual output to Emacs for further manipulation. Emacs can also send signals to the subprocess.

Process objects have no read syntax. They print in hash notation, giving the name of the process:
(process-list)
     => (#<process shell>)
See section 37. Processes, for information about functions that create, delete, return information about, send input or signals to, and receive output from processes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.8 Stream Type

A stream is an object that can be used as a source or sink for characters--either to supply characters for input or to accept them as output. Many different types can be used this way: markers, buffers, strings, and functions. Most often, input streams (character sources) obtain characters from the keyboard, a buffer, or a file, and output streams (character sinks) send characters to a buffer, such as a `*Help*' buffer, or to the echo area.

The object nil, in addition to its other meanings, may be used as a stream. It stands for the value of the variable standard-input or standard-output. Also, the object t as a stream specifies input using the minibuffer (see section 20. Minibuffers) or output in the echo area (see section 38.4 The Echo Area).

Streams have no special printed representation or read syntax, and print as whatever primitive type they are.

See section 19. Reading and Printing Lisp Objects, for a description of functions related to streams, including parsing and printing functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.9 Keymap Type

A keymap maps keys typed by the user to commands. This mapping controls how the user's command input is executed. A keymap is actually a list whose CAR is the symbol keymap.

See section 22. Keymaps, for information about creating keymaps, handling prefix keys, local as well as global keymaps, and changing key bindings.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.4.10 Overlay Type

An overlay specifies properties that apply to a part of a buffer. Each overlay applies to a specified range of the buffer, and contains a property list (a list whose elements are alternating property names and values). Overlay properties are used to present parts of the buffer temporarily in a different display style. Overlays have no read syntax, and print in hash notation, giving the buffer name and range of positions.

See section 38.9 Overlays, for how to create and use overlays.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.5 Read Syntax for Circular Objects

In Emacs 21, to represent shared or circular structure within a complex of Lisp objects, you can use the reader constructs `#n=' and `#n#'.

Use #n= before an object to label it for later reference; subsequently, you can use #n# to refer the same object in another place. Here, n is some integer. For example, here is how to make a list in which the first element recurs as the third element:
(#1=(a) b #1#)
This differs from ordinary syntax such as this
((a) b (a))
which would result in a list whose first and third elements look alike but are not the same Lisp object. This shows the difference:
(prog1 nil
  (setq x '(#1=(a) b #1#)))
(eq (nth 0 x) (nth 2 x))
     => t
(setq x '((a) b (a)))
(eq (nth 0 x) (nth 2 x))
     => nil
You can also use the same syntax to make a circular structure, which appears as an "element" within itself. Here is an example:
#1=(a #1#)
This makes a list whose second element is the list itself. Here's how you can see that it really works:
(prog1 nil
  (setq x '#1=(a #1#)))
(eq x (cadr x))
     => t
The Lisp printer can produce this syntax to record circular and shared structure in a Lisp object, if you bind the variable print-circle to a non-nil value. See section 19.6 Variables Affecting Output.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.6 Type Predicates

The Emacs Lisp interpreter itself does not perform type checking on the actual arguments passed to functions when they are called. It could not do so, since function arguments in Lisp do not have declared data types, as they do in other programming languages. It is therefore up to the individual function to test whether each actual argument belongs to a type that the function can use.

All built-in functions do check the types of their actual arguments when appropriate, and signal a wrong-type-argument error if an argument is of the wrong type. For example, here is what happens if you pass an argument to + that it cannot handle:
(+ 2 'a)
     error--> Wrong type argument: number-or-marker-p, a
If you want your program to handle different types differently, you must do explicit type checking. The most common way to check the type of an object is to call a type predicate function. Emacs has a type predicate for each type, as well as some predicates for combinations of types.

A type predicate function takes one argument; it returns t if the argument belongs to the appropriate type, and nil otherwise. Following a general Lisp convention for predicate functions, most type predicates' names end with `p'.

Here is an example which uses the predicates listp to check for a list and symbolp to check for a symbol.
(defun add-on (x)
  (cond ((symbolp x)
         ;; If X is a symbol, put it on LIST.
         (setq list (cons x list)))
        ((listp x)
         ;; If X is a list, add its elements to LIST.
         (setq list (append x list)))
        (t
         ;; We handle only symbols and lists.
         (error "Invalid argument %s in add-on" x))))
Here is a table of predefined type predicates, in alphabetical order, with references to further information.

atom
See section atom.

arrayp
See section arrayp.

bool-vector-p
See section bool-vector-p.

bufferp
See section bufferp.

byte-code-function-p
See section byte-code-function-p.

case-table-p
See section case-table-p.

char-or-string-p
See section char-or-string-p.

char-table-p
See section char-table-p.

commandp
See section commandp.

consp
See section consp.

display-table-p
See section display-table-p.

floatp
See section floatp.

frame-configuration-p
See section frame-configuration-p.

frame-live-p
See section frame-live-p.

framep
See section framep.

functionp
See section functionp.

integer-or-marker-p
See section integer-or-marker-p.

integerp
See section integerp.

keymapp
See section keymapp.

keywordp
See section 11.2 Variables that Never Change.

listp
See section listp.

markerp
See section markerp.

wholenump
See section wholenump.

nlistp
See section nlistp.

numberp
See section numberp.

number-or-marker-p
See section number-or-marker-p.

overlayp
See section overlayp.

processp
See section processp.

sequencep
See section sequencep.

stringp
See section stringp.

subrp
See section subrp.

symbolp
See section symbolp.

syntax-table-p
See section syntax-table-p.

user-variable-p
See section user-variable-p.

vectorp
See section vectorp.

window-configuration-p
See section window-configuration-p.

window-live-p
See section window-live-p.

windowp
See section windowp.
The most general way to check the type of an object is to call the function type-of. Recall that each object belongs to one and only one primitive type; type-of tells you which one (see section 2. Lisp Data Types). But type-of knows nothing about non-primitive types. In most cases, it is more convenient to use type predicates than type-of.

Function: type-of object
This function returns a symbol naming the primitive type of object. The value is one of the symbols symbol, integer, float, string, cons, vector, char-table, bool-vector, hash-table, subr, compiled-function, marker, overlay, window, buffer, frame, process, or window-configuration.
(type-of 1)
     => integer
(type-of 'nil)
     => symbol
(type-of '())    ; () is nil.
     => symbol
(type-of '(x))
     => cons
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2.7 Equality Predicates

Here we describe two functions that test for equality between any two objects. Other functions test equality between objects of specific types, e.g., strings. For these predicates, see the appropriate chapter describing the data type.

Function: eq object1 object2
This function returns t if object1 and object2 are the same object, nil otherwise. The "same object" means that a change in one will be reflected by the same change in the other.

eq returns t if object1 and object2 are integers with the same value. Also, since symbol names are normally unique, if the arguments are symbols with the same name, they are eq. For other types (e.g., lists, vectors, strings), two arguments with the same contents or elements are not necessarily eq to each other: they are eq only if they are the same object.
(eq 'foo 'foo)
     => t

(eq 456 456)
     => t

(eq "asdf" "asdf")
     => nil

(eq '(1 (2 (3))) '(1 (2 (3))))
     => nil

(setq foo '(1 (2 (3))))
     => (1 (2 (3)))
(eq foo foo)
     => t
(eq foo '(1 (2 (3))))
     => nil

(eq [(1 2) 3] [(1 2) 3])
     => nil

(eq (point-marker) (point-marker))
     => nil
The make-symbol function returns an uninterned symbol, distinct from the symbol that is used if you write the name in a Lisp expression. Distinct symbols with the same name are not eq. See section 8.3 Creating and Interning Symbols.
(eq (make-symbol "foo") 'foo)
     => nil
Function: equal object1 object2
This function returns t if object1 and object2 have equal components, nil otherwise. Whereas eq tests if its arguments are the same object, equal looks inside nonidentical arguments to see if their elements or contents are the same. So, if two objects are eq, they are equal, but the converse is not always true.
(equal 'foo 'foo)
     => t

(equal 456 456)
     => t

(equal "asdf" "asdf")
     => t
(eq "asdf" "asdf")
     => nil

(equal '(1 (2 (3))) '(1 (2 (3))))
     => t
(eq '(1 (2 (3))) '(1 (2 (3))))
     => nil

(equal [(1 2) 3] [(1 2) 3])
     => t
(eq [(1 2) 3] [(1 2) 3])
     => nil

(equal (point-marker) (point-marker))
     => t

(eq (point-marker) (point-marker))
     => nil
Comparison of strings is case-sensitive, but does not take account of text properties--it compares only the characters in the strings. A unibyte string never equals a multibyte string unless the contents are entirely ASCII (see section 33.1 Text Representations).
(equal "asdf" "ASDF")
     => nil
However, two distinct buffers are never considered equal, even if their textual contents are the same.

The test for equality is implemented recursively; for example, given two cons cells x and y, (equal x y) returns t if and only if both the expressions below return t:
(equal (car x) (car y))
(equal (cdr x) (cdr y))
Because of this recursive method, circular lists may therefore cause infinite recursion (leading to an error).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3. Numbers

GNU Emacs supports two numeric data types: integers and floating point numbers. Integers are whole numbers such as -3, 0, 7, 13, and 511. Their values are exact. Floating point numbers are numbers with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be expressed in exponential notation: 1.5e2 equals 150; in this example, `e2' stands for ten to the second power, and that is multiplied by 1.5. Floating point values are not exact; they have a fixed, limited amount of precision.

3.1 Integer Basics

Representation and range of integers.

3.2 Floating Point Basics

Representation and range of floating point.

3.3 Type Predicates for Numbers

Testing for numbers.

3.4 Comparison of Numbers

Equality and inequality predicates.

3.5 Numeric Conversions

Converting float to integer and vice versa.

3.6 Arithmetic Operations

How to add, subtract, multiply and divide.

3.7 Rounding Operations

Explicitly rounding floating point numbers.

3.8 Bitwise Operations on Integers

Logical and, or, not, shifting.

3.9 Standard Mathematical Functions

Trig, exponential and logarithmic functions.

3.10 Random Numbers

Obtaining random integers, predictable or not.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.1 Integer Basics

The range of values for an integer depends on the machine. The minimum range is -134217728 to 134217727 (28 bits; i.e., -2**27 to 2**27 - 1), but some machines may provide a wider range. Many examples in this chapter assume an integer has 28 bits.

The Lisp reader reads an integer as a sequence of digits with optional initial sign and optional final period.
 1               ; The integer 1.
 1.              ; The integer 1.
+1               ; Also the integer 1.
-1               ; The integer -1.
 268435457       ; Also the integer 1, due to overflow.
 0               ; The integer 0.
-0               ; The integer 0.
In addition, the Lisp reader recognizes a syntax for integers in bases other than 10: `#Binteger' reads integer in binary (radix 2), `#Ointeger' reads integer in octal (radix 8), `#Xinteger' reads integer in hexadecimal (radix 16), and `#radixrinteger' reads integer in radix radix (where radix is between 2 and 36, inclusivley). Case is not significant for the letter after `#' (`B', `O', etc.) that denotes the radix.

To understand how various functions work on integers, especially the bitwise operators (see section 3.8 Bitwise Operations on Integers), it is often helpful to view the numbers in their binary form.

In 28-bit binary, the decimal integer 5 looks like this:
0000  0000 0000  0000 0000  0000 0101
(We have inserted spaces between groups of 4 bits, and two spaces between groups of 8 bits, to make the binary integer easier to read.)

The integer -1 looks like this:
1111  1111 1111  1111 1111  1111 1111
-1 is represented as 28 ones. (This is called two's complement notation.)

The negative integer, -5, is creating by subtracting 4 from -1. In binary, the decimal integer 4 is 100. Consequently, -5 looks like this:
1111  1111 1111  1111 1111  1111 1011
In this implementation, the largest 28-bit binary integer value is 134,217,727 in decimal. In binary, it looks like this:
0111  1111 1111  1111 1111  1111 1111
Since the arithmetic functions do not check whether integers go outside their range, when you add 1 to 134,217,727, the value is the negative integer -134,217,728:
(+ 1 134217727)
     => -134217728
     => 1000  0000 0000  0000 0000  0000 0000
Many of the functions described in this chapter accept markers for arguments in place of numbers. (See section 31. Markers.) Since the actual arguments to such functions may be either numbers or markers, we often give these arguments the name number-or-marker. When the argument value is a marker, its position value is used and its buffer is ignored.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.2 Floating Point Basics

Floating point numbers are useful for representing numbers that are not integral. The precise range of floating point numbers is machine-specific; it is the same as the range of the C data type double on the machine you are using.

The read-syntax for floating point numbers requires either a decimal point (with at least one digit following), an exponent, or both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4' are five ways of writing a floating point number whose value is 1500. They are all equivalent. You can also use a minus sign to write negative floating point numbers, as in `-1.0'.

Most modern computers support the IEEE floating point standard, which provides for positive infinity and negative infinity as floating point values. It also provides for a class of values called NaN or "not-a-number"; numerical functions return such values in cases where there is no correct answer. For example, (sqrt -1.0) returns a NaN. For practical purposes, there's no significant difference between different NaN values in Emacs Lisp, and there's no rule for precisely which NaN value should be used in a particular case, so Emacs Lisp doesn't try to distinguish them. Here are the read syntaxes for these special floating point values:

positive infinity
`1.0e+INF'
negative infinity
`-1.0e+INF'
Not-a-number
`0.0e+NaN'.
In addition, the value -0.0 is distinguishable from ordinary zero in IEEE floating point (although equal and = consider them equal values).

You can use logb to extract the binary exponent of a floating point number (or estimate the logarithm of an integer):

Function: logb number
This function returns the binary exponent of number. More precisely, the value is the logarithm of number base 2, rounded down to an integer.
(logb 10)
     => 3
(logb 10.0e20)
     => 69
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.3 Type Predicates for Numbers

The functions in this section test whether the argument is a number or whether it is a certain sort of number. The functions integerp and floatp can take any type of Lisp object as argument (the predicates would not be of much use otherwise); but the zerop predicate requires a number as its argument. See also integer-or-marker-p and number-or-marker-p, in 31.2 Predicates on Markers.

Function: floatp object
This predicate tests whether its argument is a floating point number and returns t if so, nil otherwise.

floatp does not exist in Emacs versions 18 and earlier.

Function: integerp object
This predicate tests whether its argument is an integer, and returns t if so, nil otherwise.

Function: numberp object
This predicate tests whether its argument is a number (either integer or floating point), and returns t if so, nil otherwise.

Function: wholenump object
The wholenump predicate (whose name comes from the phrase "whole-number-p") tests to see whether its argument is a nonnegative integer, and returns t if so, nil otherwise. 0 is considered non-negative.

natnump is an obsolete synonym for wholenump.

Function: zerop number
This predicate tests whether its argument is zero, and returns t if so, nil otherwise. The argument must be a number.

These two forms are equivalent: (zerop x) == (= x 0).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.4 Comparison of Numbers

To test numbers for numerical equality, you should normally use =, not eq. There can be many distinct floating point number objects with the same numeric value. If you use eq to compare them, then you test whether two values are the same object. By contrast, = compares only the numeric values of the objects.

At present, each integer value has a unique Lisp object in Emacs Lisp. Therefore, eq is equivalent to = where integers are concerned. It is sometimes convenient to use eq for comparing an unknown value with an integer, because eq does not report an error if the unknown value is not a number--it accepts arguments of any type. By contrast, = signals an error if the arguments are not numbers or markers. However, it is a good idea to use = if you can, even for comparing integers, just in case we change the representation of integers in a future Emacs version.

Sometimes it is useful to compare numbers with equal; it treats two numbers as equal if they have the same data type (both integers, or both floating point) and the same value. By contrast, = can treat an integer and a floating point number as equal.

There is another wrinkle: because floating point arithmetic is not exact, it is often a bad idea to check for equality of two floating point values. Usually it is better to test for approximate equality. Here's a function to do this:
(defvar fuzz-factor 1.0e-6)
(defun approx-equal (x y)
  (or (and (= x 0) (= y 0))
      (< (/ (abs (- x y))
            (max (abs x) (abs y)))
         fuzz-factor)))
Common Lisp note: Comparing numbers in Common Lisp always requires = because Common Lisp implements multi-word integers, and two distinct integer objects can have the same numeric value. Emacs Lisp can have just one integer object for any given value because it has a limited range of integer values.

Function: = number-or-marker1 number-or-marker2
This function tests whether its arguments are numerically equal, and returns t if so, nil otherwise.

Function: /= number-or-marker1 number-or-marker2
This function tests whether its arguments are numerically equal, and returns t if they are not, and nil if they are.

Function: < number-or-marker1 number-or-marker2
This function tests whether its first argument is strictly less than its second argument. It returns t if so, nil otherwise.

Function: <= number-or-marker1 number-or-marker2
This function tests whether its first argument is less than or equal to its second argument. It returns t if so, nil otherwise.

Function: > number-or-marker1 number-or-marker2
This function tests whether its first argument is strictly greater than its second argument. It returns t if so, nil otherwise.

Function: >= number-or-marker1 number-or-marker2
This function tests whether its first argument is greater than or equal to its second argument. It returns t if so, nil otherwise.

Function: max number-or-marker &rest numbers-or-markers
This function returns the largest of its arguments. If any of the argument is floating-point, the value is returned as floating point, even if it was given as an integer.
(max 20)
     => 20
(max 1 2.5)
     => 2.5
(max 1 3 2.5)
     => 3.0
Function: min number-or-marker &rest numbers-or-markers
This function returns the smallest of its arguments. If any of the argument is floating-point, the value is returned as floating point, even if it was given as an integer.
(min -4 1)
     => -4
Function: abs number
This function returns the absolute value of number.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.5 Numeric Conversions

To convert an integer to floating point, use the function float.

Function: float number
This returns number converted to floating point. If number is already a floating point number, float returns it unchanged.

There are four functions to convert floating point numbers to integers; they differ in how they round. These functions accept integer arguments also, and return such arguments unchanged.

Function: truncate number
This returns number, converted to an integer by rounding towards zero.
(truncate 1.2)
     => 1
(truncate 1.7)
     => 1
(truncate -1.2)
     => -1
(truncate -1.7)
     => -1
Function: floor number &optional divisor
This returns number, converted to an integer by rounding downward (towards negative infinity).

If divisor is specified, floor divides number by divisor and then converts to an integer; this uses the kind of division operation that corresponds to mod, rounding downward. An arith-error results if divisor is 0.
(floor 1.2)
     => 1
(floor 1.7)
     => 1
(floor -1.2)
     => -2
(floor -1.7)
     => -2
(floor 5.99 3)
     => 1
Function: ceiling number
This returns number, converted to an integer by rounding upward (towards positive infinity).
(ceiling 1.2)
     => 2
(ceiling 1.7)
     => 2
(ceiling -1.2)
     => -1
(ceiling -1.7)
     => -1
Function: round number
This returns number, converted to an integer by rounding towards the nearest integer. Rounding a value equidistant between two integers may choose the integer closer to zero, or it may prefer an even integer, depending on your machine.
(round 1.2)
     => 1
(round 1.7)
     => 2
(round -1.2)
     => -1
(round -1.7)
     => -2
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.6 Arithmetic Operations

Emacs Lisp provides the traditional four arithmetic operations: addition, subtraction, multiplication, and division. Remainder and modulus functions supplement the division functions. The functions to add or subtract 1 are provided because they are traditional in Lisp and commonly used.

All of these functions except % return a floating point value if any argument is floating.

It is important to note that in Emacs Lisp, arithmetic functions do not check for overflow. Thus (1+ 134217727) may evaluate to -134217728, depending on your hardware.

Function: 1+ number-or-marker
This function returns number-or-marker plus 1. For example,
(setq foo 4)
     => 4
(1+ foo)
     => 5
This function is not analogous to the C operator ++---it does not increment a variable. It just computes a sum. Thus, if we continue,
foo
     => 4
If you want to increment the variable, you must use setq, like this:
(setq foo (1+ foo))
     => 5
Function: 1- number-or-marker
This function returns number-or-marker minus 1.

Function: + &rest numbers-or-markers
This function adds its arguments together. When given no arguments, + returns 0.
(+)
     => 0
(+ 1)
     => 1
(+ 1 2 3 4)
     => 10
Function: - &optional number-or-marker &rest more-numbers-or-markers
The - function serves two purposes: negation and subtraction. When - has a single argument, the value is the negative of the argument. When there are multiple arguments, - subtracts each of the more-numbers-or-markers from number-or-marker, cumulatively. If there are no arguments, the result is 0.
(- 10 1 2 3 4)
     => 0
(- 10)
     => -10
(-)
     => 0
Function: * &rest numbers-or-markers
This function multiplies its arguments together, and returns the product. When given no arguments, * returns 1.
(*)
     => 1
(* 1)
     => 1
(* 1 2 3 4)
     => 24
Function: / dividend divisor &rest divisors
This function divides dividend by divisor and returns the quotient. If there are additional arguments divisors, then it divides dividend by each divisor in turn. Each argument may be a number or a marker.

If all the arguments are integers, then the result is an integer too. This means the result has to be rounded. On most machines, the result is rounded towards zero after each division, but some machines may round differently with negative arguments. This is because the Lisp function / is implemented using the C division operator, which also permits machine-dependent rounding. As a practical matter, all known machines round in the standard fashion.

If you divide an integer by 0, an arith-error error is signaled. (See section 10.5.3 Errors.) Floating point division by zero returns either infinity or a NaN if your machine supports IEEE floating point; otherwise, it signals an arith-error error.
(/ 6 2)
     => 3
(/ 5 2)
     => 2
(/ 5.0 2)
     => 2.5
(/ 5 2.0)
     => 2.5
(/ 5.0 2.0)
     => 2.5
(/ 25 3 2)
     => 4
(/ -17 6)
     => -2
The result of (/ -17 6) could in principle be -3 on some machines.

Function: % dividend divisor
This function returns the integer remainder after division of dividend by divisor. The arguments must be integers or markers.

For negative arguments, the remainder is in principle machine-dependent since the quotient is; but in practice, all known machines behave alike.

An arith-error results if divisor is 0.
(% 9 4)
     => 1
(% -9 4)
     => -1
(% 9 -4)
     => 1
(% -9 -4)
     => -1
For any two integers dividend and divisor,
(+ (% dividend divisor)
   (* (/ dividend divisor) divisor))
always equals dividend.

Function: mod dividend divisor
This function returns the value of dividend modulo divisor; in other words, the remainder after division of dividend by divisor, but with the same sign as divisor. The arguments must be numbers or markers.

Unlike %, mod returns a well-defined result for negative arguments. It also permits floating point arguments; it rounds the quotient downward (towards minus infinity) to an integer, and uses that quotient to compute the remainder.

An arith-error results if divisor is 0.
(mod 9 4)
     => 1
(mod -9 4)
     => 3
(mod 9 -4)
     => -3
(mod -9 -4)
     => -1
(mod 5.5 2.5)
     => .5
For any two numbers dividend and divisor,
(+ (mod dividend divisor)
   (* (floor dividend divisor) divisor))
always equals dividend, subject to rounding error if either argument is floating point. For floor, see 3.5 Numeric Conversions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.7 Rounding Operations

The functions ffloor, fceiling, fround, and ftruncate take a floating point argument and return a floating point result whose value is a nearby integer. ffloor returns the nearest integer below; fceiling, the nearest integer above; ftruncate, the nearest integer in the direction towards zero; fround, the nearest integer.

Function: ffloor float
This function rounds float to the next lower integral value, and returns that value as a floating point number.

Function: fceiling float
This function rounds float to the next higher integral value, and returns that value as a floating point number.

Function: ftruncate float
This function rounds float towards zero to an integral value, and returns that value as a floating point number.

Function: fround float
This function rounds float to the nearest integral value, and returns that value as a floating point number.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.8 Bitwise Operations on Integers

In a computer, an integer is represented as a binary number, a sequence of bits (digits which are either zero or one). A bitwise operation acts on the individual bits of such a sequence. For example, shifting moves the whole sequence left or right one or more places, reproducing the same pattern "moved over".

The bitwise operations in Emacs Lisp apply only to integers.

Function: lsh integer1 count
lsh, which is an abbreviation for logical shift, shifts the bits in integer1 to the left count places, or to the right if count is negative, bringing zeros into the vacated bits. If count is negative, lsh shifts zeros into the leftmost (most-significant) bit, producing a positive result even if integer1 is negative. Contrast this with ash, below.

Here are two examples of lsh, shifting a pattern of bits one place to the left. We show only the low-order eight bits of the binary pattern; the rest are all zero.
(lsh 5 1)
     => 10
;; Decimal 5 becomes decimal 10.
00000101 => 00001010

(lsh 7 1)
     => 14
;; Decimal 7 becomes decimal 14.
00000111 => 00001110
As the examples illustrate, shifting the pattern of bits one place to the left produces a number that is twice the value of the previous number.

Shifting a pattern of bits two places to the left produces results like this (with 8-bit binary numbers):
(lsh 3 2)
     => 12
;; Decimal 3 becomes decimal 12.
00000011 => 00001100
On the other hand, shifting one place to the right looks like this:
(lsh 6 -1)
     => 3
;; Decimal 6 becomes decimal 3.
00000110 => 00000011

(lsh 5 -1)
     => 2
;; Decimal 5 becomes decimal 2.
00000101 => 00000010
As the example illustrates, shifting one place to the right divides the value of a positive integer by two, rounding downward.

The function lsh, like all Emacs Lisp arithmetic functions, does not check for overflow, so shifting left can discard significant bits and change the sign of the number. For example, left shifting 134,217,727 produces -2 on a 28-bit machine:
(lsh 134217727 1)          ; left shift
     => -2
In binary, in the 28-bit implementation, the argument looks like this:
;; Decimal 134,217,727
0111  1111 1111  1111 1111  1111 1111
which becomes the following when left shifted:
;; Decimal -2
1111  1111 1111  1111 1111  1111 1110
Function: ash integer1 count
ash (arithmetic shift) shifts the bits in integer1 to the left count places, or to the right if count is negative.

ash gives the same results as lsh except when integer1 and count are both negative. In that case, ash puts ones in the empty bit positions on the left, while lsh puts zeros in those bit positions.

Thus, with ash, shifting the pattern of bits one place to the right looks like this:
(ash -6 -1) => -3
;; Decimal -6 becomes decimal -3.
1111  1111 1111  1111 1111  1111 1010
     =>
1111  1111 1111  1111 1111  1111 1101
In contrast, shifting the pattern of bits one place to the right with lsh looks like this:
(lsh -6 -1) => 134217725
;; Decimal -6 becomes decimal 134,217,725.
1111  1111 1111  1111 1111  1111 1010
     =>
0111  1111 1111  1111 1111  1111 1101
Here are other examples:
                   ;               28-bit binary values

(lsh 5 2)          ;   5  =  0000  0000 0000  0000 0000  0000 0101
     => 20         ;      =  0000  0000 0000  0000 0000  0001 0100
(ash 5 2)
     => 20
(lsh -5 2)         ;  -5  =  1111  1111 1111  1111 1111  1111 1011
     => -20        ;      =  1111  1111 1111  1111 1111  1110 1100
(ash -5 2)
     => -20
(lsh 5 -2)         ;   5  =  0000  0000 0000  0000 0000  0000 0101
     => 1          ;      =  0000  0000 0000  0000 0000  0000 0001
(ash 5 -2)
     => 1
(lsh -5 -2)        ;  -5  =  1111  1111 1111  1111 1111  1111 1011
     => 4194302    ;      =  0011  1111 1111  1111 1111  1111 1110
(ash -5 -2)        ;  -5  =  1111  1111 1111  1111 1111  1111 1011
     => -2         ;      =  1111  1111 1111  1111 1111  1111 1110
Function: logand &rest ints-or-markers
This function returns the "logical and" of the arguments: the nth bit is set in the result if, and only if, the nth bit is set in all the arguments. ("Set" means that the value of the bit is 1 rather than 0.)

For example, using 4-bit binary numbers, the "logical and" of 13 and 12 is 12: 1101 combined with 1100 produces 1100. In both the binary numbers, the leftmost two bits are set (i.e., they are 1's), so the leftmost two bits of the returned value are set. However, for the rightmost two bits, each is zero in at least one of the arguments, so the rightmost two bits of the returned value are 0's.

Therefore,
(logand 13 12)
     => 12
If logand is not passed any argument, it returns a value of -1. This number is an identity element for logand because its binary representation consists entirely of ones. If logand is passed just one argument, it returns that argument.
                   ;                28-bit binary values

(logand 14 13)     ; 14  =  0000  0000 0000  0000 0000  0000 1110
                   ; 13  =  0000  0000 0000  0000 0000  0000 1101
     => 12         ; 12  =  0000  0000 0000  0000 0000  0000 1100

(logand 14 13 4)   ; 14  =  0000  0000 0000  0000 0000  0000 1110
                   ; 13  =  0000  0000 0000  0000 0000  0000 1101
                   ;  4  =  0000  0000 0000  0000 0000  0000 0100
     => 4          ;  4  =  0000  0000 0000  0000 0000  0000 0100

(logand)
     => -1         ; -1  =  1111  1111 1111  1111 1111  1111 1111
Function: logior &rest ints-or-markers
This function returns the "inclusive or" of its arguments: the nth bit is set in the result if, and only if, the nth bit is set in at least one of the arguments. If there are no arguments, the result is zero, which is an identity element for this operation. If logior is passed just one argument, it returns that argument.
                   ;               28-bit binary values

(logior 12 5)      ; 12  =  0000  0000 0000  0000 0000  0000 1100
                   ;  5  =  0000  0000 0000  0000 0000  0000 0101
     => 13         ; 13  =  0000  0000 0000  0000 0000  0000 1101

(logior 12 5 7)    ; 12  =  0000  0000 0000  0000 0000  0000 1100
                   ;  5  =  0000  0000 0000  0000 0000  0000 0101
                   ;  7  =  0000  0000 0000  0000 0000  0000 0111
     => 15         ; 15  =  0000  0000 0000  0000 0000  0000 1111
Function: logxor &rest ints-or-markers
This function returns the "exclusive or" of its arguments: the nth bit is set in the result if, and only if, the nth bit is set in an odd number of the arguments. If there are no arguments, the result is 0, which is an identity element for this operation. If logxor is passed just one argument, it returns that argument.
                   ;               28-bit binary values

(logxor 12 5)      ; 12  =  0000  0000 0000  0000 0000  0000 1100
                   ;  5  =  0000  0000 0000  0000 0000  0000 0101
     => 9          ;  9  =  0000  0000 0000  0000 0000  0000 1001

(logxor 12 5 7)    ; 12  =  0000  0000 0000  0000 0000  0000 1100
                   ;  5  =  0000  0000 0000  0000 0000  0000 0101
                   ;  7  =  0000  0000 0000  0000 0000  0000 0111
     => 14         ; 14  =  0000  0000 0000  0000 0000  0000 1110
Function: lognot integer
This function returns the logical complement of its argument: the nth bit is one in the result if, and only if, the nth bit is zero in integer, and vice-versa.
(lognot 5)
     => -6
;;  5  =  0000  0000 0000  0000 0000  0000 0101
;; becomes
;; -6  =  1111  1111 1111  1111 1111  1111 1010
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.9 Standard Mathematical Functions

These mathematical functions allow integers as well as floating point numbers as arguments.

Function: sin arg

Function: cos arg

Function: tan arg
These are the ordinary trigonometric functions, with argument measured in radians.

Function: asin arg
The value of (asin arg) is a number between -pi/2 and pi/2 (inclusive) whose sine is arg; if, however, arg is out of range (outside [-1, 1]), then the result is a NaN.

Function: acos arg
The value of (acos arg) is a number between 0 and pi (inclusive) whose cosine is arg; if, however, arg is out of range (outside [-1, 1]), then the result is a NaN.

Function: atan arg
The value of (atan arg) is a number between -pi/2 and pi/2 (exclusive) whose tangent is arg.

Function: exp arg
This is the exponential function; it returns e to the power arg. e is a fundamental mathematical constant also called the base of natural logarithms.

Function: log arg &optional base
This function returns the logarithm of arg, with base base. If you don't specify base, the base e is used. If arg is negative, the result is a NaN.

Function: log10 arg
This function returns the logarithm of arg, with base 10. If arg is negative, the result is a NaN. (log10 x) == (log x 10), at least approximately.

Function: expt x y
This function returns x raised to power y. If both arguments are integers and y is positive, the result is an integer; in this case, it is truncated to fit the range of possible integer values.

Function: sqrt arg
This returns the square root of arg. If arg is negative, the value is a NaN.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3.10 Random Numbers

A deterministic computer program cannot generate true random numbers. For most purposes, pseudo-random numbers suffice. A series of pseudo-random numbers is generated in a deterministic fashion. The numbers are not truly random, but they have certain properties that mimic a random series. For example, all possible values occur equally often in a pseudo-random series.

In Emacs, pseudo-random numbers are generated from a "seed" number. Starting from any given seed, the random function always generates the same sequence of numbers. Emacs always starts with the same seed value, so the sequence of values of random is actually the same in each Emacs run! For example, in one operating system, the first call to (random) after you start Emacs always returns -1457731, and the second one always returns -7692030. This repeatability is helpful for debugging.

If you want random numbers that don't always come out the same, execute (random t). This chooses a new seed based on the current time of day and on Emacs's process ID number.

Function: random &optional limit
This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers.

If limit is a positive integer, the value is chosen to be nonnegative and less than limit.

If limit is t, it means to choose a new seed based on the current time of day and on Emacs's process ID number.

On some machines, any integer representable in Lisp may be the result of random. On other machines, the result can never be larger than a certain maximum or less than a certain (negative) minimum.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4. Strings and Characters

A string in Emacs Lisp is an array that contains an ordered sequence of characters. Strings are used as names of symbols, buffers, and files; to send messages to users; to hold text being copied between buffers; and for many other purposes. Because strings are so important, Emacs Lisp has many functions expressly for manipulating them. Emacs Lisp programs use strings more often than individual characters.

See section 21.6.14 Putting Keyboard Events in Strings, for special considerations for strings of keyboard character events.

4.1 String and Character Basics

Basic properties of strings and characters.

4.2 The Predicates for Strings

Testing whether an object is a string or char.

4.3 Creating Strings

Functions to allocate new strings.

4.4 Modifying Strings

Altering the contents of an existing string.

4.5 Comparison of Characters and Strings

Comparing characters or strings.

4.6 Conversion of Characters and Strings

Converting to and from characters and strings.

4.7 Formatting Strings

format: Emacs's analogue of printf.

4.8 Case Conversion in Lisp

Case conversion functions.

4.9 The Case Table

Customizing case conversion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.1 String and Character Basics

Characters are represented in Emacs Lisp as integers; whether an integer is a character or not is determined only by how it is used. Thus, strings really contain integers.

The length of a string (like any array) is fixed, and cannot be altered once the string exists. Strings in Lisp are not terminated by a distinguished character code. (By contrast, strings in C are terminated by a character with ASCII code 0.)

Since strings are arrays, and therefore sequences as well, you can operate on them with the general array and sequence functions. (See section 6. Sequences, Arrays, and Vectors.) For example, you can access or change individual characters in a string using the functions aref and aset (see section 6.3 Functions that Operate on Arrays).

There are two text representations for non-ASCII characters in Emacs strings (and in buffers): unibyte and multibyte (see section 33.1 Text Representations). An ASCII character always occupies one byte in a string; in fact, when a string is all ASCII, there is no real difference between the unibyte and multibyte representations. For most Lisp programming, you don't need to be concerned with these two representations.

Sometimes key sequences are represented as strings. When a string is a key sequence, string elements in the range 128 to 255 represent meta characters (which are large integers) rather than character codes in the range 128 to 255.

Strings cannot hold characters that have the hyper, super or alt modifiers; they can hold ASCII control characters, but no other control characters. They do not distinguish case in ASCII control characters. If you want to store such characters in a sequence, such as a key sequence, you must use a vector instead of a string. See section 2.3.3 Character Type, for more information about the representation of meta and other modifiers for keyboard input characters.

Strings are useful for holding regular expressions. You can also match regular expressions against strings (see section 34.3 Regular Expression Searching). The functions match-string (see section 34.6.2 Simple Match Data Access) and replace-match (see section 34.6.1 Replacing the Text that Matched) are useful for decomposing and modifying strings based on regular expression matching.

Like a buffer, a string can contain text properties for the characters in it, as well as the characters themselves. See section 32.19 Text Properties. All the Lisp primitives that copy text from strings to buffers or other strings also copy the properties of the characters being copied.

See section 32. Text, for information about functions that display strings or copy them into buffers. See section 2.3.3 Character Type, and 2.3.8 String Type, for information about the syntax of characters and strings. See section 33. Non-ASCII Characters, for functions to convert between text representations and to encode and decode character codes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.2 The Predicates for Strings

For more information about general sequence and array predicates, see 6. Sequences, Arrays, and Vectors, and 6.2 Arrays.

Function: stringp object
This function returns t if object is a string, nil otherwise.

Function: char-or-string-p object
This function returns t if object is a string or a character (i.e., an integer), nil otherwise.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.3 Creating Strings

The following functions create strings, either from scratch, or by putting strings together, or by taking them apart.

Function: make-string count character
This function returns a string made up of count repetitions of character. If count is negative, an error is signaled.
(make-string 5 ?x)
     => "xxxxx"
(make-string 0 ?x)
     => ""
Other functions to compare with this one include char-to-string (see section 4.6 Conversion of Characters and Strings), make-vector (see section 6.4 Vectors), and make-list (see section 5.5 Building Cons Cells and Lists).

Function: string &rest characters
This returns a string containing the characters characters.
(string ?a ?b ?c)
     => "abc"
Function: substring string start &optional end
This function returns a new string which consists of those characters from string in the range from (and including) the character at the index start up to (but excluding) the character at the index end. The first character is at index zero.
(substring "abcdefg" 0 3)
     => "abc"
Here the index for `a' is 0, the index for `b' is 1, and the index for `c' is 2. Thus, three letters, `abc', are copied from the string "abcdefg". The index 3 marks the character position up to which the substring is copied. The character whose index is 3 is actually the fourth character in the string.

A negative number counts from the end of the string, so that -1 signifies the index of the last character of the string. For example:
(substring "abcdefg" -3 -1)
     => "ef"
In this example, the index for `e' is -3, the index for `f' is -2, and the index for `g' is -1. Therefore, `e' and `f' are included, and `g' is excluded.

When nil is used as an index, it stands for the length of the string. Thus,
(substring "abcdefg" -3 nil)
     => "efg"
Omitting the argument end is equivalent to specifying nil. It follows that (substring string 0) returns a copy of all of string.
(substring "abcdefg" 0)
     => "abcdefg"
But we recommend copy-sequence for this purpose (see section 6.1 Sequences).

If the characters copied from string have text properties, the properties are copied into the new string also. See section 32.19 Text Properties.

substring also accepts a vector for the first argument. For example:
(substring [a b (c) "d"] 1 3)
     => [b (c)]
A wrong-type-argument error is signaled if either start or end is not an integer or nil. An args-out-of-range error is signaled if start indicates a character following end, or if either integer is out of range for string.

Contrast this function with buffer-substring (see section 32.2 Examining Buffer Contents), which returns a string containing a portion of the text in the current buffer. The beginning of a string is at index 0, but the beginning of a buffer is at index 1.

Function: concat &rest sequences
This function returns a new string consisting of the characters in the arguments passed to it (along with their text properties, if any). The arguments may be strings, lists of numbers, or vectors of numbers; they are not themselves changed. If concat receives no arguments, it returns an empty string.
(concat "abc" "-def")
     => "abc-def"
(concat "abc" (list 120 121) [122])
     => "abcxyz"
;; nil is an empty sequence.
(concat "abc" nil "-def")
     => "abc-def"
(concat "The " "quick brown " "fox.")
     => "The quick brown fox."
(concat)
     => ""
The concat function always constructs a new string that is not eq to any existing string.

In Emacs versions before 21, when an argument was an integer (not a sequence of integers), it was converted to a string of digits making up the decimal printed representation of the integer. This obsolete usage no longer works. The proper way to convert an integer to its decimal printed form is with format (see section 4.7 Formatting Strings) or number-to-string (see section 4.6 Conversion of Characters and Strings).

For information about other concatenation functions, see the description of mapconcat in 12.6 Mapping Functions, vconcat in 6.4 Vectors, and append in 5.5 Building Cons Cells and Lists.

Function: split-string string separators
This function splits string into substrings at matches for the regular expression separators. Each match for separators defines a splitting point; the substrings between the splitting points are made into a list, which is the value returned by split-string. If separators is nil (or omitted), the default is "[ \f\t\n\r\v]+".

For example,
(split-string "Soup is good food" "o")
=> ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o+")
=> ("S" "up is g" "d f" "d")
When there is a match adjacent to the beginning or end of the string, this does not cause a null string to appear at the beginning or end of the list:
(split-string "out to moo" "o+")
=> ("ut t" " m")
Empty matches do count, when not adjacent to another match:
(split-string "Soup is good food" "o*")
=>("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
(split-string "Nice doggy!" "")
=>("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.4 Modifying Strings

The most basic way to alter the contents of an existing string is with aset (see section 6.3 Functions that Operate on Arrays). (aset string idx char) stores char into string at index idx. Each character occupies one or more bytes, and if char needs a different number of bytes from the character already present at that index, aset signals an error.

A more powerful function is store-substring:

Function: store-substring string idx obj
This function alters part of the contents of the string string, by storing obj starting at index idx. The argument obj may be either a character or a (smaller) string.

Since it is impossible to change the length of an existing string, it is an error if obj doesn't fit within string's actual length, or if any new character requires a different number of bytes from the character currently present at that point in string.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.5 Comparison of Characters and Strings

Function: char-equal character1 character2
This function returns t if the arguments represent the same character, nil otherwise. This function ignores differences in case if case-fold-search is non-nil.
(char-equal ?x ?x)
     => t
(let ((case-fold-search nil))
  (char-equal ?x ?X))
     => nil
Function: string= string1 string2
This function returns t if the characters of the two strings match exactly. Case is always significant, regardless of case-fold-search.
(string= "abc" "abc")
     => t
(string= "abc" "ABC")
     => nil
(string= "ab" "ABC")
     => nil
The function string= ignores the text properties of the two strings. When equal (see section 2.7 Equality Predicates) compares two strings, it uses string=.

If the strings contain non-ASCII characters, and one is unibyte while the other is multibyte, then they cannot be equal. See section 33.1 Text Representations.

Function: string-equal string1 string2
string-equal is another name for string=.

Function: string< string1 string2
This function compares two strings a character at a time. It scans both the strings at the same time to find the first pair of corresponding characters that do not match. If the lesser character of these two is the character from string1, then string1 is less, and this function returns t. If the lesser character is the one from string2, then string1 is greater, and this function returns nil. If the two strings match entirely, the value is nil.

Pairs of characters are compared according to their character codes. Keep in mind that lower case letters have higher numeric values in the ASCII character set than their upper case counterparts; digits and many punctuation characters have a lower numeric value than upper case letters. An ASCII character is less than any non-ASCII character; a unibyte non-ASCII character is always less than any multibyte non-ASCII character (see section 33.1 Text Representations).
(string< "abc" "abd")
     => t
(string< "abd" "abc")
     => nil
(string< "123" "abc")
     => t
When the strings have different lengths, and they match up to the length of string1, then the result is t. If they match up to the length of string2, the result is nil. A string of no characters is less than any other string.
(string< "" "abc")
     => t
(string< "ab" "abc")
     => t
(string< "abc" "")
     => nil
(string< "abc" "ab")
     => nil
(string< "" "")
     => nil
Function: string-lessp string1 string2
string-lessp is another name for string<.

Function: compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
This function compares the specified part of string1 with the specified part of string2. The specified part of string1 runs from index start1 up to index end1 (nil means the end of the string). The specified part of string2 runs from index start2 up to index end2 (nil means the end of the string).

The strings are both converted to multibyte for the comparison (see section 33.1 Text Representations) so that a unibyte string can be equal to a multibyte string. If ignore-case is non-nil, then case is ignored, so that upper case letters can be equal to lower case letters.

If the specified portions of the two strings match, the value is t. Otherwise, the value is an integer which indicates how many leading characters agree, and which string is less. Its absolute value is one plus the number of characters that agree at the beginning of the two strings. The sign is negative if string1 (or its specified portion) is less.

Function: assoc-ignore-case key alist
This function works like assoc, except that key must be a string, and comparison is done using compare-strings, ignoring case differences. See section 5.8 Association Lists.

Function: assoc-ignore-representation key alist
This function works like assoc, except that key must be a string, and comparison is done using compare-strings. Case differences are significant.

See also compare-buffer-substrings in 32.3 Comparing Text, for a way to compare text in buffers. The function string-match, which matches a regular expression against a string, can be used for a kind of string comparison; see 34.3 Regular Expression Searching.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.6 Conversion of Characters and Strings

This section describes functions for conversions between characters, strings and integers. format and prin1-to-string (see section 19.5 Output Functions) can also convert Lisp objects into strings. read-from-string (see section 19.3 Input Functions) can "convert" a string representation of a Lisp object into an object. The functions string-make-multibyte and string-make-unibyte convert the text representation of a string (see section 33.2 Converting Text Representations).

See section 24. Documentation, for functions that produce textual descriptions of text characters and general input events (single-key-description and text-char-description). These functions are used primarily for making help messages.

Function: char-to-string character
This function returns a new string containing one character, character. This function is semi-obsolete because the function string is more general. See section 4.3 Creating Strings.

Function: string-to-char string
This function returns the first character in string. If the string is empty, the function returns 0. The value is also 0 when the first character of string is the null character, ASCII code 0.
(string-to-char "ABC")
     => 65
(string-to-char "xyz")
     => 120
(string-to-char "")
     => 0
(string-to-char "\000")
     => 0
This function may be eliminated in the future if it does not seem useful enough to retain.

Function: number-to-string number
This function returns a string consisting of the printed base-ten representation of number, which may be an integer or a floating point number. The returned value starts with a minus sign if the argument is negative.
(number-to-string 256)
     => "256"
(number-to-string -23)
     => "-23"
(number-to-string -23.5)
     => "-23.5"
int-to-string is a semi-obsolete alias for this function.

See also the function format in 4.7 Formatting Strings.

Function: string-to-number string &optional base
This function returns the numeric value of the characters in string. If base is non-nil, integers are converted in that base. If base is nil, then base ten is used. Floating point conversion always uses base ten; we have not implemented other radices for floating point numbers, because that would be much more work and does not seem useful. If string looks like an integer but its value is too large to fit into a Lisp integer, string-to-number returns a floating point result.

The parsing skips spaces and tabs at the beginning of string, then reads as much of string as it can interpret as a number. (On some systems it ignores other whitespace at the beginning, not just spaces and tabs.) If the first character after the ignored whitespace is neither a digit, nor a plus or minus sign, nor the leading dot of a floating point number, this function returns 0.
(string-to-number "256")
     => 256
(string-to-number "25 is a perfect square.")
     => 25
(string-to-number "X256")
     => 0
(string-to-number "-4.5")
     => -4.5
(string-to-number "1e5")
     => 100000.0
string-to-int is an obsolete alias for this function.

Here are some other functions that can convert to or from a string:

concat
concat can convert a vector or a list into a string. See section 4.3 Creating Strings.

vconcat
vconcat can convert a string into a vector. See section 6.5 Functions for Vectors.

append
append can convert a string into a list. See section 5.5 Building Cons Cells and Lists.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.7 Formatting Strings

Formatting means constructing a string by substitution of computed values at various places in a constant string. This constant string controls how the other values are printed, as well as where they appear; it is called a format string.

Formatting is often useful for computing messages to be displayed. In fact, the functions message and error provide the same formatting feature described here; they differ from format only in how they use the result of formatting.

Function: format string &rest objects
This function returns a new string that is made by copying string and then replacing any format specification in the copy with encodings of the corresponding objects. The arguments objects are the computed values to be formatted.

The characters in string, other than the format specifications, are copied directly into the output; starting in Emacs 21, if they have text properties, these are copied into the output also.

A format specification is a sequence of characters beginning with a `%'. Thus, if there is a `%d' in string, the format function replaces it with the printed representation of one of the values to be formatted (one of the arguments objects). For example:
(format "The value of fill-column is %d." fill-column)
     => "The value of fill-column is 72."
If string contains more than one format specification, the format specifications correspond to successive values from objects. Thus, the first format specification in string uses the first such value, the second format specification uses the second such value, and so on. Any extra format specifications (those for which there are no corresponding values) cause unpredictable behavior. Any extra values to be formatted are ignored.

Certain format specifications require values of particular types. If you supply a value that doesn't fit the requirements, an error is signaled.

Here is a table of valid format specifications:

`%s'
Replace the specification with the printed representation of the object, made without quoting (that is, using princ, not prin1---see section 19.5 Output Functions). Thus, strings are represented by their contents alone, with no `"' characters, and symbols appear without `\' characters.
Starting in Emacs 21, if the object is a string, its text properties are copied into the output. The text properties of the `%s' itself are also copied, but those of the object take priority.

If there is no corresponding object, the empty string is used.

`%S'
Replace the specification with the printed representation of the object, made with quoting (that is, using prin1---see section 19.5 Output Functions). Thus, strings are enclosed in `"' characters, and `\' characters appear where necessary before special characters.
If there is no corresponding object, the empty string is used.

`%o'
Replace the specification with the base-eight representation of an integer.

`%d'
Replace the specification with the base-ten representation of an integer.

`%x'

`%X'
Replace the specification with the base-sixteen representation of an integer. `%x' uses lower case and `%X' uses upper case.

`%c'
Replace the specification with the character which is the value given.

`%e'
Replace the specification with the exponential notation for a floating point number.

`%f'
Replace the specification with the decimal-point notation for a floating point number.

`%g'
Replace the specification with notation for a floating point number, using either exponential notation or decimal-point notation, whichever is shorter.

`%%'
Replace the specification with a single `%'. This format specification is unusual in that it does not use a value. For example, (format "%% %d" 30) returns "% 30".
Any other format character results in an `Invalid format operation' error.

Here are several examples:
(format "The name of this buffer is %s." (buffer-name))
     => "The name of this buffer is strings.texi."

(format "The buffer object prints as %s." (current-buffer))
     => "The buffer object prints as strings.texi."

(format "The octal value of %d is %o,
         and the hex value is %x." 18 18 18)
     => "The octal value of 18 is 22,
         and the hex value is 12."
All the specification characters allow an optional numeric prefix between the `%' and the character. The optional numeric prefix defines the minimum width for the object. If the printed representation of the object contains fewer characters than this, then it is padded. The padding is on the left if the prefix is positive (or starts with zero) and on the right if the prefix is negative. The padding character is normally a space, but if the numeric prefix starts with a zero, zeros are used for padding. Here are some examples of padding:
(format "%06d is padded on the left with zeros" 123)
     => "000123 is padded on the left with zeros"

(format "%-6d is padded on the right" 123)
     => "123    is padded on the right"
format never truncates an object's printed representation, no matter what width you specify. Thus, you can use a numeric prefix to specify a minimum spacing between columns with no risk of losing information.

In the following three examples, `%7s' specifies a minimum width of 7. In the first case, the string inserted in place of `%7s' has only 3 letters, so 4 blank spaces are inserted for padding. In the second case, the string "specification" is 13 letters wide but is not truncated. In the third case, the padding is on the right.
(format "The word `%7s' actually has %d letters in it."
        "foo" (length "foo"))
     => "The word `    foo' actually has 3 letters in it."

(format "The word `%7s' actually has %d letters in it."
        "specification" (length "specification"))
     => "The word `specification' actually has 13 letters in it."

(format "The word `%-7s' actually has %d letters in it."
        "foo" (length "foo"))
     => "The word `foo    ' actually has 3 letters in it."
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.8 Case Conversion in Lisp

The character case functions change the case of single characters or of the contents of strings. The functions normally convert only alphabetic characters (the letters `A' through `Z' and `a' through `z', as well as non-ASCII letters); other characters are not altered. You can specify a different case conversion mapping by specifying a case table (see section 4.9 The Case Table).

These functions do not modify the strings that are passed to them as arguments.

The examples below use the characters `X' and `x' which have ASCII codes 88 and 120 respectively.

Function: downcase string-or-char
This function converts a character or a string to lower case.

When the argument to downcase is a string, the function creates and returns a new string in which each letter in the argument that is upper case is converted to lower case. When the argument to downcase is a character, downcase returns the corresponding lower case character. This value is an integer. If the original character is lower case, or is not a letter, then the value equals the original character.
(downcase "The cat in the hat")
     => "the cat in the hat"

(downcase ?X)
     => 120
Function: upcase string-or-char
This function converts a character or a string to upper case.

When the argument to upcase is a string, the function creates and returns a new string in which each letter in the argument that is lower case is converted to upper case.

When the argument to upcase is a character, upcase returns the corresponding upper case character. This value is an integer. If the original character is upper case, or is not a letter, then the value returned equals the original character.
(upcase "The cat in the hat")
     => "THE CAT IN THE HAT"

(upcase ?x)
     => 88
Function: capitalize string-or-char
This function capitalizes strings or characters. If string-or-char is a string, the function creates and returns a new string, whose contents are a copy of string-or-char in which each word has been capitalized. This means that the first character of each word is converted to upper case, and the rest are converted to lower case.

The definition of a word is any sequence of consecutive characters that are assigned to the word constituent syntax class in the current syntax table (see section 35.2.1 Table of Syntax Classes).

When the argument to capitalize is a character, capitalize has the same result as upcase.
(capitalize "The cat in the hat")
     => "The Cat In The Hat"

(capitalize "THE 77TH-HATTED CAT")
     => "The 77th-Hatted Cat"

(capitalize ?x)
     => 88
Function: upcase-initials string
This function capitalizes the initials of the words in string, without altering any letters other than the initials. It returns a new string whose contents are a copy of string, in which each word has had its initial letter converted to upper case.

The definition of a word is any sequence of consecutive characters that are assigned to the word constituent syntax class in the current syntax table (see section 35.2.1 Table of Syntax Classes).
(upcase-initials "The CAT in the hAt")
     => "The CAT In The HAt"
See section 4.5 Comparison of Characters and Strings, for functions that compare strings; some of them ignore case differences, or can optionally ignore case differences.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.9 The Case Table

You can customize case conversion by installing a special case table. A case table specifies the mapping between upper case and lower case letters. It affects both the case conversion functions for Lisp objects (see the previous section) and those that apply to text in the buffer (see section 32.18 Case Changes). Each buffer has a case table; there is also a standard case table which is used to initialize the case table of new buffers.

A case table is a char-table (see section 6.6 Char-Tables) whose subtype is case-table. This char-table maps each character into the corresponding lower case character. It has three extra slots, which hold related tables:

upcase
The upcase table maps each character into the corresponding upper case character.
canonicalize
The canonicalize table maps all of a set of case-related characters into a particular member of that set.
equivalences
The equivalences table maps each one of a set of case-related characters into the next character in that set.
In simple cases, all you need to specify is the mapping to lower-case; the three related tables will be calculated automatically from that one.

For some languages, upper and lower case letters are not in one-to-one correspondence. There may be two different lower case letters with the same upper case equivalent. In these cases, you need to specify the maps for both lower case and upper case.

The extra table canonicalize maps each character to a canonical equivalent; any two characters that are related by case-conversion have the same canonical equivalent character. For example, since `a' and `A' are related by case-conversion, they should have the same canonical equivalent character (which should be either `a' for both of them, or `A' for both of them).

The extra table equivalences is a map that cyclicly permutes each equivalence class (of characters with the same canonical equivalent). (For ordinary ASCII, this would map `a' into `A' and `A' into `a', and likewise for each set of equivalent characters.)

When you construct a case table, you can provide nil for canonicalize; then Emacs fills in this slot from the lower case and upper case mappings. You can also provide nil for equivalences; then Emacs fills in this slot from canonicalize. In a case table that is actually in use, those components are non-nil. Do not try to specify equivalences without also specifying canonicalize.

Here are the functions for working with case tables:

Function: case-table-p object
This predicate returns non-nil if object is a valid case table.

Function: set-standard-case-table table
This function makes table the standard case table, so that it will be used in any buffers created subsequently.

Function: standard-case-table
This returns the standard case table.

Function: current-case-table
This function returns the current buffer's case table.

Function: set-case-table table
This sets the current buffer's case table to table.

The following three functions are convenient subroutines for packages that define non-ASCII character sets. They modify the specified case table case-table; they also modify the standard syntax table. See section 35. Syntax Tables. Normally you would use these functions to change the standard case table.

Function: set-case-syntax-pair uc lc case-table
This function specifies a pair of corresponding letters, one upper case and one lower case.

Function: set-case-syntax-delims l r case-table
This function makes characters l and r a matching pair of case-invariant delimiters.

Function: set-case-syntax char syntax case-table
This function makes char case-invariant, with syntax syntax.

Command: describe-buffer-case-table
This command displays a description of the contents of the current buffer's case table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5. Lists

A list represents a sequence of zero or more elements (which may be any Lisp objects). The important difference between lists and vectors is that two or more lists can share part of their structure; in addition, you can insert or delete elements in a list without copying the whole list.

5.1 Lists and Cons Cells

How lists are made out of cons cells.

5.2 Lists as Linked Pairs of Boxes

Graphical notation to explain lists.

5.3 Predicates on Lists

Is this object a list? Comparing two lists.

5.4 Accessing Elements of Lists

Extracting the pieces of a list.

5.5 Building Cons Cells and Lists

Creating list structure.

5.6 Modifying Existing List Structure

Storing new pieces into an existing list.

5.7 Using Lists as Sets

A list can represent a finite mathematical set.

5.8 Association Lists

A list can represent a finite relation or mapping.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.1 Lists and Cons Cells

Lists in Lisp are not a primitive data type; they are built up from cons cells. A cons cell is a data object that represents an ordered pair. That is, it has two slots, and each slot holds, or refers to, some Lisp object. One slot is known as the CAR, and the other is known as the CDR. (These names are traditional; see 2.3.6 Cons Cell and List Types.) CDR is pronounced "could-er."

We say that "the CAR of this cons cell is" whatever object its CAR slot currently holds, and likewise for the CDR.

A list is a series of cons cells "chained together," so that each cell refers to the next one. There is one cons cell for each element of the list. By convention, the CARs of the cons cells hold the elements of the list, and the CDRs are used to chain the list: the CDR slot of each cons cell refers to the following cons cell. The CDR of the last cons cell is nil. This asymmetry between the CAR and the CDR is entirely a matter of convention; at the level of cons cells, the CAR and CDR slots have the same characteristics.

Because most cons cells are used as part of lists, the phrase list structure has come to mean any structure made out of cons cells.

The symbol nil is considered a list as well as a symbol; it is the list with no elements. For convenience, the symbol nil is considered to have nil as its CDR (and also as its CAR).

The CDR of any nonempty list l is a list containing all the elements of l except the first.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.2 Lists as Linked Pairs of Boxes

A cons cell can be illustrated as a pair of boxes. The first box represents the CAR and the second box represents the CDR. Here is an illustration of the two-element list, (tulip lily), made from two cons cells:
 ---------------         ---------------
| car   | cdr   |       | car   | cdr   |
| tulip |   o---------->| lily  |  nil  |
|       |       |       |       |       |
 ---------------         ---------------
Each pair of boxes represents a cons cell. Each box "refers to", "points to" or "holds" a Lisp object. (These terms are synonymous.) The first box, which describes the CAR of the first cons cell, contains the symbol tulip. The arrow from the CDR box of the first cons cell to the second cons cell indicates that the CDR of the first cons cell is the second cons cell.

The same list can be illustrated in a different sort of box notation like this:
    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> tulip    --> lily
Here is a more complex illustration, showing the three-element list, ((pine needles) oak maple), the first element of which is a two-element list:
    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
     |             --> oak      --> maple
     |
     |     --- ---      --- ---
      --> |   |   |--> |   |   |--> nil
           --- ---      --- ---
            |            |
            |            |
             --> pine     --> needles
The same list represented in the first box notation looks like this:
 --------------       --------------       --------------
| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
|   o   |   o------->| oak   |   o------->| maple |  nil |
|   |   |      |     |       |      |     |       |      |
 -- | ---------       --------------       --------------
    |
    |
    |        --------------       ----------------
    |       | car   | cdr  |     | car     | cdr  |
     ------>| pine  |   o------->| needles |  nil |
            |       |      |     |         |      |
             --------------       ----------------
See section 2.3.6 Cons Cell and List Types, for the read and print syntax of cons cells and lists, and for more "box and arrow" illustrations of lists.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.3 Predicates on Lists

The following predicates test whether a Lisp object is an atom, is a cons cell or is a list, or whether it is the distinguished object nil. (Many of these predicates can be defined in terms of the others, but they are used so often that it is worth having all of them.)

Function: consp object
This function returns t if object is a cons cell, nil otherwise. nil is not a cons cell, although it is a list.

Function: atom object
This function returns t if object is an atom, nil otherwise. All objects except cons cells are atoms. The symbol nil is an atom and is also a list; it is the only Lisp object that is both.
(atom object) == (not (consp object))
Function: listp object
This function returns t if object is a cons cell or nil. Otherwise, it returns nil.
(listp '(1))
     => t
(listp '())
     => t
Function: nlistp object
This function is the opposite of listp: it returns t if object is not a list. Otherwise, it returns nil.
(listp object) == (not (nlistp object))
Function: null object
This function returns t if object is nil, and returns nil otherwise. This function is identical to not, but as a matter of clarity we use null when object is considered a list and not when it is considered a truth value (see not in 10.3 Constructs for Combining Conditions).
(null '(1))
     => nil
(null '())
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.4 Accessing Elements of Lists

Function: car cons-cell
This function returns the value referred to by the first slot of the cons cell cons-cell. Expressed another way, this function returns the CAR of cons-cell.

As a special case, if cons-cell is nil, then car is defined to return nil; therefore, any list is a valid argument for car. An error is signaled if the argument is not a cons cell or nil.
(car '(a b c))
     => a
(car '())
     => nil
Function: cdr cons-cell
This function returns the value referred to by the second slot of the cons cell cons-cell. Expressed another way, this function returns the CDR of cons-cell.

As a special case, if cons-cell is nil, then cdr is defined to return nil; therefore, any list is a valid argument for cdr. An error is signaled if the argument is not a cons cell or nil.
(cdr '(a b c))
     => (b c)
(cdr '())
     => nil
Function: car-safe object
This function lets you take the CAR of a cons cell while avoiding errors for other data types. It returns the CAR of object if object is a cons cell, nil otherwise. This is in contrast to car, which signals an error if object is not a list.
(car-safe object)
==
(let ((x object))
  (if (consp x)
      (car x)
    nil))
Function: cdr-safe object
This function lets you take the CDR of a cons cell while avoiding errors for other data types. It returns the CDR of object if object is a cons cell, nil otherwise. This is in contrast to cdr, which signals an error if object is not a list.
(cdr-safe object)
==
(let ((x object))
  (if (consp x)
      (cdr x)
    nil))
Macro: pop listname
This macro is a way of examining the CAR of a list, and taking it off the list, all at once. It is new in Emacs 21.

It operates on the list which is stored in the symbol listname. It removes this element from the list by setting listname to the CDR of its old value--but it also returns the CAR of that list, which is the element being removed.
x
     => (a b c)
(pop x)
     => a
x
     => (b c)
Function: nth n list
This function returns the nth element of list. Elements are numbered starting with zero, so the CAR of list is element number zero. If the length of list is n or less, the value is nil.

If n is negative, nth returns the first element of list.
(nth 2 '(1 2 3 4))
     => 3
(nth 10 '(1 2 3 4))
     => nil
(nth -3 '(1 2 3 4))
     => 1

(nth n x) == (car (nthcdr n x))
The function elt is similar, but applies to any kind of sequence. For historical reasons, it takes its arguments in the opposite order. See section 6.1 Sequences.

Function: nthcdr n list
This function returns the nth CDR of list. In other words, it skips past the first n links of list and returns what follows.

If n is zero or negative, nthcdr returns all of list. If the length of list is n or less, nthcdr returns nil.
(nthcdr 1 '(1 2 3 4))
     => (2 3 4)
(nthcdr 10 '(1 2 3 4))
     => nil
(nthcdr -3 '(1 2 3 4))
     => (1 2 3 4)
Function: last list &optional n
This function returns the last link of list. The car of this link is the list's last element. If list is null, nil is returned. If n is non-nil the n-th-to-last link is returned instead, or the whole list if n is bigger than list's length.

Function: safe-length list
This function returns the length of list, with no risk of either an error or an infinite loop.

If list is not really a list, safe-length returns 0. If list is circular, it returns a finite value which is at least the number of distinct elements.

The most common way to compute the length of a list, when you are not worried that it may be circular, is with length. See section 6.1 Sequences.

Function: caar cons-cell
This is the same as (car (car cons-cell)).

Function: cadr cons-cell
This is the same as (car (cdr cons-cell)) or (nth 1 cons-cell).

Function: cdar cons-cell
This is the same as (cdr (car cons-cell)).

Function: cddr cons-cell
This is the same as (cdr (cdr cons-cell)) or (nthcdr 2 cons-cell).

Function: butlast x &optional n
This function returns the list x with the last element, or the last n elements, removed. If n is greater than zero it makes a copy of the list so as not to damage the original list. In general, (append (butlast x n) (last x n)) will return a list equal to x.

Function: nbutlast x &optional n
This is a version of butlast that works by destructively modifying the cdr of the appropriate element, rather than making a copy of the list.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.5 Building Cons Cells and Lists

Many functions build lists, as lists reside at the very heart of Lisp. cons is the fundamental list-building function; however, it is interesting to note that list is used more times in the source code for Emacs than cons.

Function: cons object1 object2
This function is the fundamental function used to build new list structure. It creates a new cons cell, making object1 the CAR, and object2 the CDR. It then returns the new cons cell. The arguments object1 and object2 may be any Lisp objects, but most often object2 is a list.
(cons 1 '(2))
     => (1 2)
(cons 1 '())
     => (1)
(cons 1 2)
     => (1 . 2)
cons is often used to add a single element to the front of a list. This is called consing the element onto the list. (1) For example:
(setq list (cons newelt list))
Note that there is no conflict between the variable named list used in this example and the function named list described below; any symbol can serve both purposes.

Macro: push newelt listname
This macro provides an alternative way to write (setq listname (cons newelt listname)). It is new in Emacs 21.
(setq l '(a b))
     => (a b)
(push 'c l)
     => (c a b)
l
     => (c a b)
Function: list &rest objects
This function creates a list with objects as its elements. The resulting list is always nil-terminated. If no objects are given, the empty list is returned.
(list 1 2 3 4 5)
     => (1 2 3 4 5)
(list 1 2 '(3 4 5) 'foo)
     => (1 2 (3 4 5) foo)
(list)
     => nil
Function: make-list length object
This function creates a list of length elements, in which each element is object. Compare make-list with make-string (see section 4.3 Creating Strings).
(make-list 3 'pigs)
     => (pigs pigs pigs)
(make-list 0 'pigs)
     => nil
(setq l (make-list 3 '(a b))
     => ((a b) (a b) (a b))
(eq (car l) (cadr l))
     => t
Function: append &rest sequences
This function returns a list containing all the elements of sequences. The sequences may be lists, vectors, bool-vectors, or strings, but the last one should usually be a list. All arguments except the last one are copied, so none of the arguments is altered. (See nconc in 5.6.3 Functions that Rearrange Lists, for a way to join lists with no copying.)

More generally, the final argument to append may be any Lisp object. The final argument is not copied or converted; it becomes the CDR of the last cons cell in the new list. If the final argument is itself a list, then its elements become in effect elements of the result list. If the final element is not a list, the result is a "dotted list" since its final CDR is not nil as required in a true list.

The append function also allows integers as arguments. It converts them to strings of digits, making up the decimal print representation of the integer, and then uses the strings instead of the original integers. Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now! The proper way to convert an integer to a decimal number in this way is with format (see section 4.7 Formatting Strings) or number-to-string (see section 4.6 Conversion of Characters and Strings).

Here is an example of using append:
(setq trees '(pine oak))
     => (pine oak)
(setq more-trees (append '(maple birch) trees))
     => (maple birch pine oak)

trees
     => (pine oak)
more-trees
     => (maple birch pine oak)
(eq trees (cdr (cdr more-trees)))
     => t
You can see how append works by looking at a box diagram. The variable trees is set to the list (pine oak) and then the variable more-trees is set to the list (maple birch pine oak). However, the variable trees continues to refer to the original list:
more-trees                trees
|                           |
|     --- ---      --- ---   -> --- ---      --- ---
 --> |   |   |--> |   |   |--> |   |   |--> |   |   |--> nil
      --- ---      --- ---      --- ---      --- ---
       |            |            |            |
       |            |            |            |
        --> maple    -->birch     --> pine     --> oak
An empty sequence contributes nothing to the value returned by append. As a consequence of this, a final nil argument forces a copy of the previous argument:
trees
     => (pine oak)
(setq wood (append trees nil))
     => (pine oak)
wood
     => (pine oak)
(eq wood trees)
     => nil
This once was the usual way to copy a list, before the function copy-sequence was invented. See section 6. Sequences, Arrays, and Vectors.

Here we show the use of vectors and strings as arguments to append:
(append [a b] "cd" nil)
     => (a b 99 100)
With the help of apply (see section 12.5 Calling Functions), we can append all the lists in a list of lists:
(apply 'append '((a b c) nil (x y z) nil))
     => (a b c x y z)
If no sequences are given, nil is returned:
(append)
     => nil
Here are some examples where the final argument is not a list:
(append '(x y) 'z)
     => (x y . z)
(append '(x y) [z])
     => (x y . [z])
The second example shows that when the final argument is a sequence but not a list, the sequence's elements do not become elements of the resulting list. Instead, the sequence becomes the final CDR, like any other non-list final argument.

Function: reverse list
This function creates a new list whose elements are the elements of list, but in reverse order. The original argument list is not altered.
(setq x '(1 2 3 4))
     => (1 2 3 4)
(reverse x)
     => (4 3 2 1)
x
     => (1 2 3 4)
Function: remq object list
This function returns a copy of list, with all elements removed which are eq to object. The letter `q' in remq says that it uses eq to compare object against the elements of list.
(setq sample-list '(a b c a b c))
     => (a b c a b c)
(remq 'a sample-list)
     => (b c b c)
sample-list
     => (a b c a b c)
The function delq offers a way to perform this operation destructively. See 5.7 Using Lists as Sets.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.6 Modifying Existing List Structure

You can modify the CAR and CDR contents of a cons cell with the primitives setcar and setcdr. We call these "destructive" operations because they change existing list structure.

Common Lisp note: Common Lisp uses functions rplaca and rplacd to alter list structure; they change structure the same way as setcar and setcdr, but the Common Lisp functions return the cons cell while setcar and setcdr return the new CAR or CDR.

5.6.1 Altering List Elements with setcar

Replacing an element in a list.

5.6.2 Altering the CDR of a List

Replacing part of the list backbone. This can be used to remove or add elements.

5.6.3 Functions that Rearrange Lists

Reordering the elements in a list; combining lists.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.6.1 Altering List Elements with setcar

Changing the CAR of a cons cell is done with setcar. When used on a list, setcar replaces one element of a list with a different element.

Function: setcar cons object
This function stores object as the new CAR of cons, replacing its previous CAR. In other words, it changes the CAR slot of cons to refer to object. It returns the value object. For example:
(setq x '(1 2))
     => (1 2)
(setcar x 4)
     => 4
x
     => (4 2)
When a cons cell is part of the shared structure of several lists, storing a new CAR into the cons changes one element of each of these lists. Here is an example:
;; Create two lists that are partly shared.
(setq x1 '(a b c))
     => (a b c)
(setq x2 (cons 'z (cdr x1)))
     => (z b c)

;; Replace the CAR of a shared link.
(setcar (cdr x1) 'foo)
     => foo
x1                           ; Both lists are changed.
     => (a foo c)
x2
     => (z foo c)

;; Replace the CAR of a link that is not shared.
(setcar x1 'baz)
     => baz
x1                           ; Only one list is changed.
     => (baz foo c)
x2
     => (z foo c)
Here is a graphical depiction of the shared structure of the two lists in the variables x1 and x2, showing why replacing b changes them both:
        --- ---        --- ---      --- ---
x1---> |   |   |----> |   |   |--> |   |   |--> nil
        --- ---        --- ---      --- ---
         |        -->   |            |
         |       |      |            |
          --> a  |       --> b        --> c
                 |
       --- ---   |
x2--> |   |   |--
       --- ---
        |
        |
         --> z
Here is an alternative form of box diagram, showing the same relationship:
x1:
 --------------       --------------       --------------
| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
|   a   |   o------->|   b   |   o------->|   c   |  nil |
|       |      |  -->|       |      |     |       |      |
 --------------  |    --------------       --------------
                 |
x2:              |
 --------------  |
| car   | cdr  | |
|   z   |   o----
|       |      |
 --------------
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.6.2 Altering the CDR of a List

The lowest-level primitive for modifying a CDR is setcdr:

Function: setcdr cons object
This function stores object as the new CDR of cons, replacing its previous CDR. In other words, it changes the CDR slot of cons to refer to object. It returns the value object.

Here is an example of replacing the CDR of a list with a different list. All but the first element of the list are removed in favor of a different sequence of elements. The first element is unchanged, because it resides in the CAR of the list, and is not reached via the CDR.
(setq x '(1 2 3))
     => (1 2 3)
(setcdr x '(4))
     => (4)
x
     => (1 4)
You can delete elements from the middle of a list by altering the CDRs of the cons cells in the list. For example, here we delete the second element, b, from the list (a b c), by changing the CDR of the first cons cell:
(setq x1 '(a b c))
     => (a b c)
(setcdr x1 (cdr (cdr x1)))
     => (c)
x1
     => (a c)
Here is the result in box notation:
                   --------------------
                  |                    |
 --------------   |   --------------   |    --------------
| car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
|   a   |   o-----   |   b   |   o-------->|   c   |  nil |
|       |      |     |       |      |      |       |      |
 --------------       --------------        --------------
The second cons cell, which previously held the element b, still exists and its CAR is still b, but it no longer forms part of this list.

It is equally easy to insert a new element by changing CDRs:
(setq x1 '(a b c))
     => (a b c)
(setcdr x1 (cons 'd (cdr x1)))
     => (d b c)
x1
     => (a d b c)
Here is this result in box notation:
 --------------        -------------       -------------
| car  | cdr   |      | car  | cdr  |     | car  | cdr  |
|   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
|      |   |   |  |   |      |      |     |      |      |
 --------- | --   |    -------------       -------------
           |      |
     -----         --------
    |                      |
    |    ---------------   |
    |   | car   | cdr   |  |
     -->|   d   |   o------
        |       |       |
         ---------------
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.6.3 Functions that Rearrange Lists

Here are some functions that rearrange lists "destructively" by modifying the CDRs of their component cons cells. We call these functions "destructive" because they chew up the original lists passed to them as arguments, relinking their cons cells to form a new list that is the returned value.

See delq, in 5.7 Using Lists as Sets, for another function that modifies cons cells.

Function: nconc &rest lists
This function returns a list containing all the elements of lists. Unlike append (see section 5.5 Building Cons Cells and Lists), the lists are not copied. Instead, the last CDR of each of the lists is changed to refer to the following list. The last of the lists is not altered. For example:
(setq x '(1 2 3))
     => (1 2 3)
(nconc x '(4 5))
     => (1 2 3 4 5)
x
     => (1 2 3 4 5)
Since the last argument of nconc is not itself modified, it is reasonable to use a constant list, such as '(4 5), as in the above example. For the same reason, the last argument need not be a list:
(setq x '(1 2 3))
     => (1 2 3)
(nconc x 'z)
     => (1 2 3 . z)
x
     => (1 2 3 . z)
However, the other arguments (all but the last) must be lists.

A common pitfall is to use a quoted constant list as a non-last argument to nconc. If you do this, your program will change each time you run it! Here is what happens:
(defun add-foo (x)            ; We want this function to add
  (nconc '(foo) x))           ;   foo to the front of its arg.

(symbol-function 'add-foo)
     => (lambda (x) (nconc (quote (foo)) x))

(setq xx (add-foo '(1 2)))    ; It seems to work.
     => (foo 1 2)
(setq xy (add-foo '(3 4)))    ; What happened?
     => (foo 1 2 3 4)
(eq xx xy)
     => t

(symbol-function 'add-foo)
     => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
Function: nreverse list
This function reverses the order of the elements of list. Unlike reverse, nreverse alters its argument by reversing the CDRs in the cons cells forming the list. The cons cell that used to be the last one in list becomes the first cons cell of the value.

For example:
(setq x '(a b c))
     => (a b c)
x
     => (a b c)
(nreverse x)
     => (c b a)
;; The cons cell that was first is now last.
x
     => (a)
To avoid confusion, we usually store the result of nreverse back in the same variable which held the original list:
(setq x (nreverse x))
Here is the nreverse of our favorite example, (a b c), presented graphically:
Original list head:                       Reversed list:
 -------------        -------------        ------------
| car  | cdr  |      | car  | cdr  |      | car | cdr  |
|   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
|      |      |   |  |      |   |  |   |  |     |   |  |
 -------------    |   --------- | -    |   -------- | -
                  |             |      |            |
                   -------------        ------------
Function: sort list predicate
This function sorts list stably, though destructively, and returns the sorted list. It compares elements using predicate. A stable sort is one in which elements with equal sort keys maintain their relative order before and after the sort. Stability is important when successive sorts are used to order elements according to different criteria.

The argument predicate must be a function that accepts two arguments. It is called with two elements of list. To get an increasing order sort, the predicate should return t if the first element is "less than" the second, or nil if not.

The comparison function predicate must give reliable results for any given pair of arguments, at least within a single call to sort. It must be antisymmetric; that is, if a is less than b, b must not be less than a. It must be transitive---that is, if a is less than b, and b is less than c, then a must be less than c. If you use a comparison function which does not meet these requirements, the result of sort is unpredictable.

The destructive aspect of sort is that it rearranges the cons cells forming list by changing CDRs. A nondestructive sort function would create new cons cells to store the elements in their sorted order. If you wish to make a sorted copy without destroying the original, copy it first with copy-sequence and then sort.

Sorting does not change the CARs of the cons cells in list; the cons cell that originally contained the element a in list still has a in its CAR after sorting, but it now appears in a different position in the list due to the change of CDRs. For example:
(setq nums '(1 3 2 6 5 4 0))
     => (1 3 2 6 5 4 0)
(sort nums '<)
     => (0 1 2 3 4 5 6)
nums
     => (1 2 3 4 5 6)
Warning: Note that the list in nums no longer contains 0; this is the same cons cell that it was before, but it is no longer the first one in the list. Don't assume a variable that formerly held the argument now holds the entire sorted list! Instead, save the result of sort and use that. Most often we store the result back into the variable that held the original list:
(setq nums (sort nums '<))
See section 32.15 Sorting Text, for more functions that perform sorting. See documentation in 24.2 Access to Documentation Strings, for a useful example of sort.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.7 Using Lists as Sets

A list can represent an unordered mathematical set--simply consider a value an element of a set if it appears in the list, and ignore the order of the list. To form the union of two sets, use append (as long as you don't mind having duplicate elements). Other useful functions for sets include memq and delq, and their equal versions, member and delete.

Common Lisp note: Common Lisp has functions union (which avoids duplicate elements) and intersection for set operations, but GNU Emacs Lisp does not have them. You can write them in Lisp if you wish.

Function: memq object list
This function tests to see whether object is a member of list. If it is, memq returns a list starting with the first occurrence of object. Otherwise, it returns nil. The letter `q' in memq says that it uses eq to compare object against the elements of the list. For example:
(memq 'b '(a b c b a))
     => (b c b a)
(memq '(2) '((1) (2)))    ; (2) and (2) are not eq.
     => nil
Function: member-ignore-case object list
This function is like member, except that it ignores differences in letter-case and text representation: upper-case and lower-case letters are treated as equal, and unibyte strings are converted to multibyte prior to comparison.

Function: delq object list
This function destructively removes all elements eq to object from list. The letter `q' in delq says that it uses eq to compare object against the elements of the list, like memq and remq.

When delq deletes elements from the front of the list, it does so simply by advancing down the list and returning a sublist that starts after those elements:
(delq 'a '(a b c)) == (cdr '(a b c))
When an element to be deleted appears in the middle of the list, removing it involves changing the CDRs (see section 5.6.2 Altering the CDR of a List).
(setq sample-list '(a b c (4)))
     => (a b c (4))
(delq 'a sample-list)
     => (b c (4))
sample-list
     => (a b c (4))
(delq 'c sample-list)
     => (a b (4))
sample-list
     => (a b (4))
Note that (delq 'c sample-list) modifies sample-list to splice out the third element, but (delq 'a sample-list) does not splice anything--it just returns a shorter list. Don't assume that a variable which formerly held the argument list now has fewer elements, or that it still holds the original list! Instead, save the result of delq and use that. Most often we store the result back into the variable that held the original list:
(setq flowers (delq 'rose flowers))
In the following example, the (4) that delq attempts to match and the (4) in the sample-list are not eq:
(delq '(4) sample-list)
     => (a c (4))
The following two functions are like memq and delq but use equal rather than eq to compare elements. See section 2.7 Equality Predicates.

Function: member object list
The function member tests to see whether object is a member of list, comparing members with object using equal. If object is a member, member returns a list starting with its first occurrence in list. Otherwise, it returns nil.

Compare this with memq:
(member '(2) '((1) (2)))  ; (2) and (2) are equal.
     => ((2))
(memq '(2) '((1) (2)))    ; (2) and (2) are not eq.
     => nil
;; Two strings with the same contents are equal.
(member "foo" '("foo" "bar"))
     => ("foo" "bar")
Function: delete object sequence
If sequence is a list, this function destructively removes all elements equal to object from sequence. For lists, delete is to delq as member is to memq: it uses equal to compare elements with object, like member; when it finds an element that matches, it removes the element just as delq would.

If sequence is a vector or string, delete returns a copy of sequence with all elements equal to object removed.

For example:
(delete '(2) '((2) (1) (2)))
     => ((1))
(delete '(2) [(2) (1) (2)])
     => [(1)]
Function: remove object sequence
This function is the non-destructive counterpart of delete. If returns a copy of sequence, a list, vector, or string, with elements equal to object removed. For example:
(remove '(2) '((2) (1) (2)))
     => ((1))
(remove '(2) [(2) (1) (2)])
     => [(1)]
Common Lisp note: The functions member, delete and remove in GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common Lisp versions do not use equal to compare elements.

See also the function add-to-list, in 11.8 How to Alter a Variable Value, for another way to add an element to a list stored in a variable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5.8 Association Lists

An association list, or alist for short, records a mapping from keys to values. It is a list of cons cells called associations: the CAR of each cons cell is the key, and the CDR is the associated value.(2)

Here is an example of an alist. The key pine is associated with the value cones; the key oak is associated with acorns; and the key maple is associated with seeds.
((pine . cones)
 (oak . acorns)
 (maple . seeds))
The associated values in an alist may be any Lisp objects; so may the keys. For example, in the following alist, the symbol a is associated with the number 1, and the string "b" is associated with the list (2 3), which is the CDR of the alist element:
((a . 1) ("b" 2 3))
Sometimes it is better to design an alist to store the associated value in the CAR of the CDR of the element. Here is an example of such an alist:
((rose red) (lily white) (buttercup yellow))
Here we regard red as the value associated with rose. One advantage of this kind of alist is that you can store other related information--even a list of other items--in the CDR of the CDR. One disadvantage is that you cannot use rassq (see below) to find the element containing a given value. When neither of these considerations is important, the choice is a matter of taste, as long as you are consistent about it for any given alist.

Note that the same alist shown above could be regarded as having the associated value in the CDR of the element; the value associated with rose would be the list (red).

Association lists are often used to record information that you might otherwise keep on a stack, since new associations may be added easily to the front of the list. When searching an association list for an association with a given key, the first one found is returned, if there is more than one.

In Emacs Lisp, it is not an error if an element of an association list is not a cons cell. The alist search functions simply ignore such elements. Many other versions of Lisp signal errors in such cases.

Note that property lists are similar to association lists in several respects. A property list behaves like an association list in which each key can occur only once. See section 8.4 Property Lists, for a comparison of property lists and association lists.

Function: assoc key alist
This function returns the first association for key in alist. It compares key against the alist elements using equal (see section 2.7 Equality Predicates). It returns nil if no association in alist has a CAR equal to key. For example:
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
     => ((pine . cones) (oak . acorns) (maple . seeds))
(assoc 'oak trees)
     => (oak . acorns)
(cdr (assoc 'oak trees))
     => acorns
(assoc 'birch trees)
     => nil
Here is another example, in which the keys and values are not symbols:
(setq needles-per-cluster
      '((2 "Austrian Pine" "Red Pine")
        (3 "Pitch Pine")
        (5 "White Pine")))

(cdr (assoc 3 needles-per-cluster))
     => ("Pitch Pine")
(cdr (assoc 2 needles-per-cluster))
     => ("Austrian Pine" "Red Pine")
The functions assoc-ignore-representation and assoc-ignore-case are much like assoc except using compare-strings to do the comparison. See section 4.5 Comparison of Characters and Strings.

Function: rassoc value alist
This function returns the first association with value value in alist. It returns nil if no association in alist has a CDR equal to value.

rassoc is like assoc except that it compares the CDR of each alist association instead of the CAR. You can think of this as "reverse assoc", finding the key for a given value.

Function: assq key alist
This function is like assoc in that it returns the first association for key in alist, but it makes the comparison using eq instead of equal. assq returns nil if no association in alist has a CAR eq to key. This function is used more often than assoc, since eq is faster than equal and most alists use symbols as keys. See section 2.7 Equality Predicates.
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
     => ((pine . cones) (oak . acorns) (maple . seeds))
(assq 'pine trees)
     => (pine . cones)
On the other hand, assq is not usually useful in alists where the keys may not be symbols:
(setq leaves
      '(("simple leaves" . oak)
        ("compound leaves" . horsechestnut)))

(assq "simple leaves" leaves)
     => nil
(assoc "simple leaves" leaves)
     => ("simple leaves" . oak)
Function: rassq value alist
This function returns the first association with value value in alist. It returns nil if no association in alist has a CDR eq to value.

rassq is like assq except that it compares the CDR of each alist association instead of the CAR. You can think of this as "reverse assq", finding the key for a given value.

For example:
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))

(rassq 'acorns trees)
     => (oak . acorns)
(rassq 'spores trees)
     => nil
Note that rassq cannot search for a value stored in the CAR of the CDR of an element:
(setq colors '((rose red) (lily white) (buttercup yellow)))

(rassq 'white colors)
     => nil
In this case, the CDR of the association (lily white) is not the symbol white, but rather the list (white). This becomes clearer if the association is written in dotted pair notation:
(lily white) == (lily . (white))
Function: assoc-default key alist &optional test default
This function searches alist for a match for key. For each element of alist, it compares the element (if it is an atom) or the element's CAR (if it is a cons) against key, by calling test with two arguments: the element or its CAR, and key. The arguments are passed in that order so that you can get useful results using string-match with an alist that contains regular expressions (see section 34.3 Regular Expression Searching). If test is omitted or nil, equal is used for comparison.

If an alist element matches key by this criterion, then assoc-default returns a value based on this element. If the element is a cons, then the value is the element's CDR. Otherwise, the return value is default.

If no alist element matches key, assoc-default returns nil.

Function: copy-alist alist
This function returns a two-level deep copy of alist: it creates a new copy of each association, so that you can alter the associations of the new alist without changing the old one.
(setq needles-per-cluster
      '((2 . ("Austrian Pine" "Red Pine"))
        (3 . ("Pitch Pine"))
        (5 . ("White Pine"))))
=>
((2 "Austrian Pine" "Red Pine")
 (3 "Pitch Pine")
 (5 "White Pine"))

(setq copy (copy-alist needles-per-cluster))
=>
((2 "Austrian Pine" "Red Pine")
 (3 "Pitch Pine")
 (5 "White Pine"))

(eq needles-per-cluster copy)
     => nil
(equal needles-per-cluster copy)
     => t
(eq (car needles-per-cluster) (car copy))
     => nil
(cdr (car (cdr needles-per-cluster)))
     => ("Pitch Pine")
(eq (cdr (car (cdr needles-per-cluster)))
    (cdr (car (cdr copy))))
     => t
This example shows how copy-alist makes it possible to change the associations of one copy without affecting the other:
(setcdr (assq 3 copy) '("Martian Vacuum Pine"))
(cdr (assq 3 needles-per-cluster))
     => ("Pitch Pine")
Function: assq-delete-all key alist
This function deletes from alist all the elements whose CAR is eq to key. It returns alist, modified in this way. Note that it modifies the original list structure of alist.
(assq-delete-all 'foo
                 '((foo 1) (bar 2) (foo 3) (lose 4)))
     => ((bar 2) (lose 4))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6. Sequences, Arrays, and Vectors

Recall that the sequence type is the union of two other Lisp types: lists and arrays. In other words, any list is a sequence, and any array is a sequence. The common property that all sequences have is that each is an ordered collection of elements.

An array is a single primitive object that has a slot for each of its elements. All the elements are accessible in constant time, but the length of an existing array cannot be changed. Strings, vectors, char-tables and bool-vectors are the four types of arrays.

A list is a sequence of elements, but it is not a single primitive object; it is made of cons cells, one cell per element. Finding the nth element requires looking through n cons cells, so elements farther from the beginning of the list take longer to access. But it is possible to add elements to the list, or remove elements.

The following diagram shows the relationship between these types:
          _____________________________________________
         |                                             |
         |          Sequence                           |
         |  ______   ________________________________  |
         | |      | |                                | |
         | | List | |             Array              | |
         | |      | |    ________       ________     | |
         | |______| |   |        |     |        |    | |
         |          |   | Vector |     | String |    | |
         |          |   |________|     |________|    | |
         |          |  ____________   _____________  | |
         |          | |            | |             | | |
         |          | | Char-table | | Bool-vector | | |
         |          | |____________| |_____________| | |
         |          |________________________________| |
         |_____________________________________________|
The elements of vectors and lists may be any Lisp objects. The elements of strings are all characters.

6.1 Sequences

Functions that accept any kind of sequence.

6.2 Arrays

Characteristics of arrays in Emacs Lisp.

6.3 Functions that Operate on Arrays

Functions specifically for arrays.

6.4 Vectors

Special characteristics of Emacs Lisp vectors.

6.5 Functions for Vectors

Functions specifically for vectors.

6.6 Char-Tables

How to work with char-tables.

6.7 Bool-vectors

How to work with bool-vectors.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.1 Sequences

In Emacs Lisp, a sequence is either a list or an array. The common property of all sequences is that they are ordered collections of elements. This section describes functions that accept any kind of sequence.

Function: sequencep object
Returns t if object is a list, vector, or string, nil otherwise.

Function: length sequence
This function returns the number of elements in sequence. If sequence is a cons cell that is not a list (because the final CDR is not nil), a wrong-type-argument error is signaled.

See section 5.4 Accessing Elements of Lists, for the related function safe-length.
(length '(1 2 3))
    => 3
(length ())
    => 0
(length "foobar")
    => 6
(length [1 2 3])
    => 3
(length (make-bool-vector 5 nil))
    => 5
Function: elt sequence index
This function returns the element of sequence indexed by index. Legitimate values of index are integers ranging from 0 up to one less than the length of sequence. If sequence is a list, then out-of-range values of index return nil; otherwise, they trigger an args-out-of-range error.
(elt [1 2 3 4] 2)
     => 3
(elt '(1 2 3 4) 2)
     => 3
;; We use string to show clearly which character elt returns.
(string (elt "1234" 2))
     => "3"
(elt [1 2 3 4] 4)
     error--> Args out of range: [1 2 3 4], 4
(elt [1 2 3 4] -1)
     error--> Args out of range: [1 2 3 4], -1
This function generalizes aref (see section 6.3 Functions that Operate on Arrays) and nth (see section 5.4 Accessing Elements of Lists).

Function: copy-sequence sequence
Returns a copy of sequence. The copy is the same type of object as the original sequence, and it has the same elements in the same order.

Storing a new element into the copy does not affect the original sequence, and vice versa. However, the elements of the new sequence are not copies; they are identical (eq) to the elements of the original. Therefore, changes made within these elements, as found via the copied sequence, are also visible in the original sequence.

If the sequence is a string with text properties, the property list in the copy is itself a copy, not shared with the original's property list. However, the actual values of the properties are shared. See section 32.19 Text Properties.

See also append in 5.5 Building Cons Cells and Lists, concat in 4.3 Creating Strings, and vconcat in 6.4 Vectors, for other ways to copy sequences.
(setq bar '(1 2))
     => (1 2)
(setq x (vector 'foo bar))
     => [foo (1 2)]
(setq y (copy-sequence x))
     => [foo (1 2)]

(eq x y)
     => nil
(equal x y)
     => t
(eq (elt x 1) (elt y 1))
     => t

;; Replacing an element of one sequence.
(aset x 0 'quux)
x => [quux (1 2)]
y => [foo (1 2)]

;; Modifying the inside of a shared element.
(setcar (aref x 1) 69)
x => [quux (69 2)]
y => [foo (69 2)]
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.2 Arrays

An array object has slots that hold a number of other Lisp objects, called the elements of the array. Any element of an array may be accessed in constant time. In contrast, an element of a list requires access time that is proportional to the position of the element in the list.

Emacs defines four types of array, all one-dimensional: strings, vectors, bool-vectors and char-tables. A vector is a general array; its elements can be any Lisp objects. A string is a specialized array; its elements must be characters. Each type of array has its own read syntax. See section 2.3.8 String Type, and 2.3.9 Vector Type.

All four kinds of array share these characteristics:

The first element of an array has index zero, the second element has index 1, and so on. This is called zero-origin indexing. For example, an array of four elements has indices 0, 1, 2, and 3.

The length of the array is fixed once you create it; you cannot change the length of an existing array.

The array is a constant, for evaluation--in other words, it evaluates to itself.

The elements of an array may be referenced or changed with the functions aref and aset, respectively (see section 6.3 Functions that Operate on Arrays).

When you create an array, other than a char-table, you must specify its length. You cannot specify the length of a char-table, because that is determined by the range of character codes.

In principle, if you want an array of text characters, you could use either a string or a vector. In practice, we always choose strings for such applications, for four reasons:

They occupy one-fourth the space of a vector of the same elements.

Strings are printed in a way that shows the contents more clearly as text.

Strings can hold text properties. See section 32.19 Text Properties.

Many of the specialized editing and I/O facilities of Emacs accept only strings. For example, you cannot insert a vector of characters into a buffer the way you can insert a string. See section 4. Strings and Characters.

By contrast, for an array of keyboard input characters (such as a key sequence), a vector may be necessary, because many keyboard input characters are outside the range that will fit in a string. See section 21.7.1 Key Sequence Input.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.3 Functions that Operate on Arrays

In this section, we describe the functions that accept all types of arrays.

Function: arrayp object
This function returns t if object is an array (i.e., a vector, a string, a bool-vector or a char-table).
(arrayp [a])
     => t
(arrayp "asdf")
     => t
(arrayp (syntax-table))    ;; A char-table.
     => t
Function: aref array index
This function returns the indexth element of array. The first element is at index zero.
(setq primes [2 3 5 7 11 13])
     => [2 3 5 7 11 13]
(aref primes 4)
     => 11
(aref "abcdefg" 1)
     => 98           ; `b' is ASCII code 98.
See also the function elt, in 6.1 Sequences.

Function: aset array index object
This function sets the indexth element of array to be object. It returns object.
(setq w [foo bar baz])
     => [foo bar baz]
(aset w 0 'fu)
     => fu
w
     => [fu bar baz]

(setq x "asdfasfd")
     => "asdfasfd"
(aset x 3 ?Z)
     => 90
x
     => "asdZasfd"
If array is a string and object is not a character, a wrong-type-argument error results. The function converts a unibyte string to multibyte if necessary to insert a character.

Function: fillarray array object
This function fills the array array with object, so that each element of array is object. It returns array.
(setq a [a b c d e f g])
     => [a b c d e f g]
(fillarray a 0)
     => [0 0 0 0 0 0 0]
a
     => [0 0 0 0 0 0 0]
(setq s "When in the course")
     => "When in the course"
(fillarray s ?-)
     => "------------------"
If array is a string and object is not a character, a wrong-type-argument error results.

The general sequence functions copy-sequence and length are often useful for objects known to be arrays. See section 6.1 Sequences.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.4 Vectors

Arrays in Lisp, like arrays in most languages, are blocks of memory whose elements can be accessed in constant time. A vector is a general-purpose array of specified length; its elements can be any Lisp objects. (By contrast, a string can hold only characters as elements.) Vectors in Emacs are used for obarrays (vectors of symbols), and as part of keymaps (vectors of commands). They are also used internally as part of the representation of a byte-compiled function; if you print such a function, you will see a vector in it.

In Emacs Lisp, the indices of the elements of a vector start from zero and count up from there.

Vectors are printed with square brackets surrounding the elements. Thus, a vector whose elements are the symbols a, b and a is printed as [a b a]. You can write vectors in the same way in Lisp input.

A vector, like a string or a number, is considered a constant for evaluation: the result of evaluating it is the same vector. This does not evaluate or even examine the elements of the vector. See section 9.2.1 Self-Evaluating Forms.

Here are examples illustrating these principles:
(setq avector [1 two '(three) "four" [five]])
     => [1 two (quote (three)) "four" [five]]
(eval avector)
     => [1 two (quote (three)) "four" [five]]
(eq avector (eval avector))
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.5 Functions for Vectors

Here are some functions that relate to vectors:

Function: vectorp object
This function returns t if object is a vector.
(vectorp [a])
     => t
(vectorp "asdf")
     => nil
Function: vector &rest objects
This function creates and returns a vector whose elements are the arguments, objects.
(vector 'foo 23 [bar baz] "rats")
     => [foo 23 [bar baz] "rats"]
(vector)
     => []
Function: make-vector length object
This function returns a new vector consisting of length elements, each initialized to object.
(setq sleepy (make-vector 9 'Z))
     => [Z Z Z Z Z Z Z Z Z]
Function: vconcat &rest sequences
This function returns a new vector containing all the elements of the sequences. The arguments sequences may be any kind of arrays, including lists, vectors, or strings. If no sequences are given, an empty vector is returned.

The value is a newly constructed vector that is not eq to any existing vector.
(setq a (vconcat '(A B C) '(D E F)))
     => [A B C D E F]
(eq a (vconcat a))
     => nil
(vconcat)
     => []
(vconcat [A B C] "aa" '(foo (6 7)))
     => [A B C 97 97 foo (6 7)]
The vconcat function also allows byte-code function objects as arguments. This is a special feature to make it easy to access the entire contents of a byte-code function object. See section 16.6 Byte-Code Function Objects.

The vconcat function also allows integers as arguments. It converts them to strings of digits, making up the decimal print representation of the integer, and then uses the strings instead of the original integers. Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now! The proper way to convert an integer to a decimal number in this way is with format (see section 4.7 Formatting Strings) or number-to-string (see section 4.6 Conversion of Characters and Strings).

For other concatenation functions, see mapconcat in 12.6 Mapping Functions, concat in 4.3 Creating Strings, and append in 5.5 Building Cons Cells and Lists.

The append function provides a way to convert a vector into a list with the same elements (see section 5.5 Building Cons Cells and Lists):
(setq avector [1 two (quote (three)) "four" [five]])
     => [1 two (quote (three)) "four" [five]]
(append avector nil)
     => (1 two (quote (three)) "four" [five])
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.6 Char-Tables

A char-table is much like a vector, except that it is indexed by character codes. Any valid character code, without modifiers, can be used as an index in a char-table. You can access a char-table's elements with aref and aset, as with any array. In addition, a char-table can have extra slots to hold additional data not associated with particular character codes. Char-tables are constants when evaluated.

Each char-table has a subtype which is a symbol. The subtype has two purposes: to distinguish char-tables meant for different uses, and to control the number of extra slots. For example, display tables are char-tables with display-table as the subtype, and syntax tables are char-tables with syntax-table as the subtype. A valid subtype must have a char-table-extra-slots property which is an integer between 0 and 10. This integer specifies the number of extra slots in the char-table.

A char-table can have a parent, which is another char-table. If it does, then whenever the char-table specifies nil for a particular character c, it inherits the value specified in the parent. In other words, (aref char-table c) returns the value from the parent of char-table if char-table itself specifies nil.

A char-table can also have a default value. If so, then (aref char-table c) returns the default value whenever the char-table does not specify any other non-nil value.

Function: make-char-table subtype &optional init
Return a newly created char-table, with subtype subtype. Each element is initialized to init, which defaults to nil. You cannot alter the subtype of a char-table after the char-table is created.

There is no argument to specify the length of the char-table, because all char-tables have room for any valid character code as an index.

Function: char-table-p object
This function returns t if object is a char-table, otherwise nil.

Function: char-table-subtype char-table
This function returns the subtype symbol of char-table.

Function: set-char-table-default char-table new-default
This function sets the default value of char-table to new-default.

There is no special function to access the default value of a char-table. To do that, use (char-table-range char-table nil).

Function: char-table-parent char-table
This function returns the parent of char-table. The parent is always either nil or another char-table.

Function: set-char-table-parent char-table new-parent
This function sets the parent of char-table to new-parent.

Function: char-table-extra-slot char-table n
This function returns the contents of extra slot n of char-table. The number of extra slots in a char-table is determined by its subtype.

Function: set-char-table-extra-slot char-table n value
This function stores value in extra slot n of char-table.

A char-table can specify an element value for a single character code; it can also specify a value for an entire character set.

Function: char-table-range char-table range
This returns the value specified in char-table for a range of characters range. Here are the possibilities for range:

nil
Refers to the default value.

char
Refers to the element for character char (supposing char is a valid character code).

charset
Refers to the value specified for the whole character set charset (see section 33.5 Character Sets).

generic-char
A generic character stands for a character set; specifying the generic character as argument is equivalent to specifying the character set name. See section 33.7 Splitting Characters, for a description of generic characters.

Function: set-char-table-range char-table range value
This function sets the value in char-table for a range of characters range. Here are the possibilities for range:

nil
Refers to the default value.

t
Refers to the whole range of character codes.

char
Refers to the element for character char (supposing char is a valid character code).

charset
Refers to the value specified for the whole character set charset (see section 33.5 Character Sets).

generic-char
A generic character stands for a character set; specifying the generic character as argument is equivalent to specifying the character set name. See section 33.7 Splitting Characters, for a description of generic characters.

Function: map-char-table function char-table
This function calls function for each element of char-table. function is called with two arguments, a key and a value. The key is a possible range argument for char-table-range---either a valid character or a generic character--and the value is (char-table-range char-table key).

Overall, the key-value pairs passed to function describe all the values stored in char-table.

The return value is always nil; to make this function useful, function should have side effects. For example, here is how to examine each element of the syntax table:
(let (accumulator)
  (map-char-table
   #'(lambda (key value)
       (setq accumulator
             (cons (list key value) accumulator)))
   (syntax-table))
  accumulator)
=>
((475008 nil) (474880 nil) (474752 nil) (474624 nil)
 ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6.7 Bool-vectors

A bool-vector is much like a vector, except that it stores only the values t and nil. If you try to store any non-nil value into an element of the bool-vector, the effect is to store t there. As with all arrays, bool-vector indices start from 0, and the length cannot be changed once the bool-vector is created. Bool-vectors are constants when evaluated.

There are two special functions for working with bool-vectors; aside from that, you manipulate them with same functions used for other kinds of arrays.

Function: make-bool-vector length initial
Return a new bool-vector of length elements, each one initialized to initial.

Function: bool-vector-p object
This returns t if object is a bool-vector, and nil otherwise.

Here is an example of creating, examining, and updating a bool-vector. Note that the printed form represents up to 8 boolean values as a single character.
(setq bv (make-bool-vector 5 t))
     => #&5"^_"
(aref bv 1)
     => t
(aset bv 3 nil)
     => nil
bv
     => #&5"^W"
These results make sense because the binary codes for control-_ and control-W are 11111 and 10111, respectively.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7. Hash Tables

A hash table is a very fast kind of lookup table, somewhat like an alist in that it maps keys to corresponding values. It differs from an alist in these ways:

Lookup in a hash table is extremely fast for large tables--in fact, the time required is essentially independent of how many elements are stored in the table. For smaller tables (a few tens of elements) alists may still be faster because hash tables have a more-or-less constant overhead.

The correspondences in a hash table are in no particular order.

There is no way to share structure between two hash tables, the way two alists can share a common tail.

Emacs Lisp (starting with Emacs 21) provides a general-purpose hash table data type, along with a series of functions for operating on them. Hash tables have no read syntax, and print in hash notation, like this:
(make-hash-table)
     => #<hash-table 'eql nil 0/65 0x83af980>
(The term "hash notation" refers to the initial `#' character---see section 2.1 Printed Representation and Read Syntax---and has nothing to do with the term "hash table.")

Obarrays are also a kind of hash table, but they are a different type of object and are used only for recording interned symbols (see section 8.3 Creating and Interning Symbols).

7.1 Creating Hash Tables

7.2 Hash Table Access

7.3 Defining Hash Comparisons

7.4 Other Hash Table Functions

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.1 Creating Hash Tables

The principal function for creating a hash table is make-hash-table.

Function: make-hash-table &rest keyword-args
This function creates a new hash table according to the specified arguments. The arguments should consist of alternating keywords (particular symbols recognized specially) and values corresponding to them.

Several keywords make sense in make-hash-table, but the only two that you really need to know about are :test and :weakness.

:test test
This specifies the method of key lookup for this hash table. The default is eql; eq and equal are other alternatives:

eql
Keys which are numbers are "the same" if they are equal in value; otherwise, two distinct objects are never "the same".

eq
Any two distinct Lisp objects are "different" as keys.

equal
Two Lisp objects are "the same", as keys, if they are equal according to equal.
You can use define-hash-table-test (see section 7.3 Defining Hash Comparisons) to define additional possibilities for test.

:weakness weak
The weakness of a hash table specifies whether the presence of a key or value in the hash table preserves it from garbage collection.
The value, weak, must be one of nil, key, value, key-or-value, key-and-value, or t which is an alias for key-and-value. If weak is key then the hash table does not prevent its keys from being collected as garbage (if they are not referenced anywhere else); if a particular key does get collected, the corresponding association is removed from the hash table.

If weak is value, then the hash table does not prevent values from being collected as garbage (if they are not referenced anywhere else); if a particular value does get collected, the corresponding association is removed from the hash table.

If weak is key-or-value or t, the hash table does not protect either keys or values from garbage collection; if either one is collected as garbage, the association is removed.

If weak is key-and-value, associations are removed from the hash table when both their key and value would be collected as garbage, again not considering references to the key and value from weak hash tables.

The default for weak is nil, so that all keys and values referenced in the hash table are preserved from garbage collection. If weak is t, neither keys nor values are protected (that is, both are weak).

:size size
This specifies a hint for how many associations you plan to store in the hash table. If you know the approximate number, you can make things a little more efficient by specifying it this way. If you specify too small a size, the hash table will grow automatically when necessary, but doing that takes some extra time.
The default size is 65.

:rehash-size rehash-size
When you add an association to a hash table and the table is "full," it grows automatically. This value specifies how to make the hash table larger, at that time.
If rehash-size is an integer, it should be positive, and the hash table grows by adding that much to the nominal size. If rehash-size is a floating point number, it had better be greater than 1, and the hash table grows by multiplying the old size by that number.

The default value is 1.5.

:rehash-threshold threshold
This specifies the criterion for when the hash table is "full." The value, threshold, should be a positive floating point number, no greater than 1. The hash table is "full" whenever the actual number of entries exceeds this fraction of the nominal size. The default for threshold is 0.8.

Function: makehash &optional test
This is equivalent to make-hash-table, but with a different style argument list. The argument test specifies the method of key lookup.

If you want to specify other parameters, you should use make-hash-table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.2 Hash Table Access

This section describes the functions for accessing and storing associations in a hash table.

Function: gethash key table &optional default
This function looks up key in table, and returns its associated value---or default, if key has no association in table.

Function: puthash key value table
This function enters an association for key in table, with value value. If key already has an association in table, value replaces the old associated value.

Function: remhash key table
This function removes the association for key from table, if there is one. If key has no association, remhash does nothing.

Function: clrhash table
This function removes all the associations from hash table table, so that it becomes empty. This is also called clearing the hash table.

Function: maphash function table
This function calls function once for each of the associations in table. The function function should accept two arguments--a key listed in table, and its associated value.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.3 Defining Hash Comparisons

You can define new methods of key lookup by means of define-hash-table-test. In order to use this feature, you need to understand how hash tables work, and what a hash code means.

You can think of a hash table conceptually as a large array of many slots, each capable of holding one association. To look up a key, gethash first computes an integer, the hash code, from the key. It reduces this integer modulo the length of the array, to produce an index in the array. Then it looks in that slot, and if necessary in other nearby slots, to see if it has found the key being sought.

Thus, to define a new method of key lookup, you need to specify both a function to compute the hash code from a key, and a function to compare two keys directly.

Function: define-hash-table-test name test-fn hash-fn
This function defines a new hash table test, named name.

After defining name in this way, you can use it as the test argument in make-hash-table. When you do that, the hash table will use test-fn to compare key values, and hash-fn to compute a "hash code" from a key value.

The function test-fn should accept two arguments, two keys, and return non-nil if they are considered "the same."

The function hash-fn should accept one argument, a key, and return an integer that is the "hash code" of that key. For good results, the function should use the whole range of integer values for hash codes, including negative integers.

The specified functions are stored in the property list of name under the property hash-table-test; the property value's form is (test-fn hash-fn).

Function: sxhash obj
This function returns a hash code for Lisp object obj. This is an integer which reflects the contents of obj and the other Lisp objects it points to.

If two objects obj1 and obj2 are equal, then (sxhash obj1) and (sxhash obj2) are the same integer.

If the two objects are not equal, the values returned by sxhash are usually different, but not always; but once in a rare while, by luck, you will encounter two distinct-looking objects that give the same result from sxhash.

This example creates a hash table whose keys are strings that are compared case-insensitively.
(defun case-fold-string= (a b)
  (compare-strings a nil nil b nil nil t))

(defun case-fold-string-hash (a)
  (sxhash (upcase a)))

(define-hash-table-test 'case-fold 'case-fold-string=
                        'case-fold-string-hash))

(make-hash-table :test 'case-fold)
Here is how you could define a hash table test equivalent to the predefined test value equal. The keys can be any Lisp object, and equal-looking objects are considered the same key.
(define-hash-table-test 'contents-hash 'equal 'sxhash)

(make-hash-table :test 'contents-hash)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7.4 Other Hash Table Functions

Here are some other functions for working with hash tables.

Function: hash-table-p table
This returns non-nil if table is a hash table object.

Function: copy-hash-table table
This function creates and returns a copy of table. Only the table itself is copied--the keys and values are shared.

Function: hash-table-count table
This function returns the actual number of entries in table.

Function: hash-table-test table
This returns the test value that was given when table was created, to specify how to hash and compare keys. See make-hash-table (see section 7.1 Creating Hash Tables).

Function: hash-table-weakness table
This function returns the weak value that was specified for hash table table.

Function: hash-table-rehash-size table
This returns the rehash size of table.

Function: hash-table-rehash-threshold table
This returns the rehash threshold of table.

Function: hash-table-size table
This returns the current nominal size of table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8. Symbols

A symbol is an object with a unique name. This chapter describes symbols, their components, their property lists, and how they are created and interned. Separate chapters describe the use of symbols as variables and as function names; see 11. Variables, and 12. Functions. For the precise read syntax for symbols, see 2.3.4 Symbol Type.

You can test whether an arbitrary Lisp object is a symbol with symbolp:

Function: symbolp object
This function returns t if object is a symbol, nil otherwise.

8.1 Symbol Components

Symbols have names, values, function definitions and property lists.

8.2 Defining Symbols

A definition says how a symbol will be used.

8.3 Creating and Interning Symbols

How symbols are kept unique.

8.4 Property Lists

Each symbol has a property list for recording miscellaneous information.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.1 Symbol Components

Each symbol has four components (or "cells"), each of which references another object:

Print name
The print name cell holds a string that names the symbol for reading and printing. See symbol-name in 8.3 Creating and Interning Symbols.

Value
The value cell holds the current value of the symbol as a variable. When a symbol is used as a form, the value of the form is the contents of the symbol's value cell. See symbol-value in 11.7 Accessing Variable Values.

Function
The function cell holds the function definition of the symbol. When a symbol is used as a function, its function definition is used in its place. This cell is also used to make a symbol stand for a keymap or a keyboard macro, for editor command execution. Because each symbol has separate value and function cells, variables names and function names do not conflict. See symbol-function in 12.8 Accessing Function Cell Contents.

Property list
The property list cell holds the property list of the symbol. See symbol-plist in 8.4 Property Lists.
The print name cell always holds a string, and cannot be changed. The other three cells can be set individually to any specified Lisp object.

The print name cell holds the string that is the name of the symbol. Since symbols are represented textually by their names, it is important not to have two symbols with the same name. The Lisp reader ensures this: every time it reads a symbol, it looks for an existing symbol with the specified name before it creates a new one. (In GNU Emacs Lisp, this lookup uses a hashing algorithm and an obarray; see 8.3 Creating and Interning Symbols.)

The value cell holds the symbol's value as a variable (see section 11. Variables). That is what you get if you evaluate the symbol as a Lisp expression (see section 9. Evaluation). Any Lisp object is a legitimate value. Certain symbols have values that cannot be changed; these include nil and t, and any symbol whose name starts with `:' (those are called keywords). See section 11.2 Variables that Never Change.

We often refer to "the function foo" when we really mean the function stored in the function cell of the symbol foo. We make the distinction explicit only when necessary. In normal usage, the function cell usually contains a function (see section 12. Functions) or a macro (see section 13. Macros), as that is what the Lisp interpreter expects to see there (see section 9. Evaluation). Keyboard macros (see section 21.15 Keyboard Macros), keymaps (see section 22. Keymaps) and autoload objects (see section 9.2.8 Autoloading) are also sometimes stored in the function cells of symbols.

The property list cell normally should hold a correctly formatted property list (see section 8.4 Property Lists), as a number of functions expect to see a property list there.

The function cell or the value cell may be void, which means that the cell does not reference any object. (This is not the same thing as holding the symbol void, nor the same as holding the symbol nil.) Examining a function or value cell that is void results in an error, such as `Symbol's value as variable is void'.

The four functions symbol-name, symbol-value, symbol-plist, and symbol-function return the contents of the four cells of a symbol. Here as an example we show the contents of the four cells of the symbol buffer-file-name:
(symbol-name 'buffer-file-name)
     => "buffer-file-name"
(symbol-value 'buffer-file-name)
     => "/gnu/elisp/symbols.texi"
(symbol-plist 'buffer-file-name)
     => (variable-documentation 29529)
(symbol-function 'buffer-file-name)
     => #<subr buffer-file-name>
Because this symbol is the variable which holds the name of the file being visited in the current buffer, the value cell contents we see are the name of the source file of this chapter of the Emacs Lisp Manual. The property list cell contains the list (variable-documentation 29529) which tells the documentation functions where to find the documentation string for the variable buffer-file-name in the `DOC-version' file. (29529 is the offset from the beginning of the `DOC-version' file to where that documentation string begins--see 24.1 Documentation Basics.) The function cell contains the function for returning the name of the file. buffer-file-name names a primitive function, which has no read syntax and prints in hash notation (see section 2.3.15 Primitive Function Type). A symbol naming a function written in Lisp would have a lambda expression (or a byte-code object) in this cell.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.2 Defining Symbols

A definition in Lisp is a special form that announces your intention to use a certain symbol in a particular way. In Emacs Lisp, you can define a symbol as a variable, or define it as a function (or macro), or both independently.

A definition construct typically specifies a value or meaning for the symbol for one kind of use, plus documentation for its meaning when used in this way. Thus, when you define a symbol as a variable, you can supply an initial value for the variable, plus documentation for the variable.

defvar and defconst are special forms that define a symbol as a global variable. They are documented in detail in 11.5 Defining Global Variables. For defining user option variables that can be customized, use defcustom (see section 14. Writing Customization Definitions).

defun defines a symbol as a function, creating a lambda expression and storing it in the function cell of the symbol. This lambda expression thus becomes the function definition of the symbol. (The term "function definition", meaning the contents of the function cell, is derived from the idea that defun gives the symbol its definition as a function.) defsubst and defalias are two other ways of defining a function. See section 12. Functions.

defmacro defines a symbol as a macro. It creates a macro object and stores it in the function cell of the symbol. Note that a given symbol can be a macro or a function, but not both at once, because both macro and function definitions are kept in the function cell, and that cell can hold only one Lisp object at any given time. See section 13. Macros.

In Emacs Lisp, a definition is not required in order to use a symbol as a variable or function. Thus, you can make a symbol a global variable with setq, whether you define it first or not. The real purpose of definitions is to guide programmers and programming tools. They inform programmers who read the code that certain symbols are intended to be used as variables, or as functions. In addition, utilities such as `etags' and `make-docfile' recognize definitions, and add appropriate information to tag tables and the `DOC-version' file. See section 24.2 Access to Documentation Strings.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.3 Creating and Interning Symbols

To understand how symbols are created in GNU Emacs Lisp, you must know how Lisp reads them. Lisp must ensure that it finds the same symbol every time it reads the same set of characters. Failure to do so would cause complete confusion.

When the Lisp reader encounters a symbol, it reads all the characters of the name. Then it "hashes" those characters to find an index in a table called an obarray. Hashing is an efficient method of looking something up. For example, instead of searching a telephone book cover to cover when looking up Jan Jones, you start with the J's and go from there. That is a simple version of hashing. Each element of the obarray is a bucket which holds all the symbols with a given hash code; to look for a given name, it is sufficient to look through all the symbols in the bucket for that name's hash code. (The same idea is used for general Emacs hash tables, but they are a different data type; see 7. Hash Tables.)

If a symbol with the desired name is found, the reader uses that symbol. If the obarray does not contain a symbol with that name, the reader makes a new symbol and adds it to the obarray. Finding or adding a symbol with a certain name is called interning it, and the symbol is then called an interned symbol.

Interning ensures that each obarray has just one symbol with any particular name. Other like-named symbols may exist, but not in the same obarray. Thus, the reader gets the same symbols for the same names, as long as you keep reading with the same obarray.

Interning usually happens automatically in the reader, but sometimes other programs need to do it. For example, after the M-x command obtains the command name as a string using the minibuffer, it then interns the string, to get the interned symbol with that name.

No obarray contains all symbols; in fact, some symbols are not in any obarray. They are called uninterned symbols. An uninterned symbol has the same four cells as other symbols; however, the only way to gain access to it is by finding it in some other object or as the value of a variable.

Creating an uninterned symbol is useful in generating Lisp code, because an uninterned symbol used as a variable in the code you generate cannot clash with any variables used in other Lisp programs.

In Emacs Lisp, an obarray is actually a vector. Each element of the vector is a bucket; its value is either an interned symbol whose name hashes to that bucket, or 0 if the bucket is empty. Each interned symbol has an internal link (invisible to the user) to the next symbol in the bucket. Because these links are invisible, there is no way to find all the symbols in an obarray except using mapatoms (below). The order of symbols in a bucket is not significant.

In an empty obarray, every element is 0, so you can create an obarray with (make-vector length 0). This is the only valid way to create an obarray. Prime numbers as lengths tend to result in good hashing; lengths one less than a power of two are also good.

Do not try to put symbols in an obarray yourself. This does not work--only intern can enter a symbol in an obarray properly.

Common Lisp note: In Common Lisp, a single symbol may be interned in several obarrays.

Most of the functions below take a name and sometimes an obarray as arguments. A wrong-type-argument error is signaled if the name is not a string, or if the obarray is not a vector.

Function: symbol-name symbol
This function returns the string that is symbol's name. For example:
(symbol-name 'foo)
     => "foo"
Warning: Changing the string by substituting characters does change the name of the symbol, but fails to update the obarray, so don't do it!

Function: make-symbol name
This function returns a newly-allocated, uninterned symbol whose name is name (which must be a string). Its value and function definition are void, and its property list is nil. In the example below, the value of sym is not eq to foo because it is a distinct uninterned symbol whose name is also `foo'.
(setq sym (make-symbol "foo"))
     => foo
(eq sym 'foo)
     => nil
Function: intern name &optional obarray
This function returns the interned symbol whose name is name. If there is no such symbol in the obarray obarray, intern creates a new one, adds it to the obarray, and returns it. If obarray is omitted, the value of the global variable obarray is used.
(setq sym (intern "foo"))
     => foo
(eq sym 'foo)
     => t

(setq sym1 (intern "foo" other-obarray))
     => foo
(eq sym1 'foo)
     => nil
Common Lisp note: In Common Lisp, you can intern an existing symbol in an obarray. In Emacs Lisp, you cannot do this, because the argument to intern must be a string, not a symbol.

Function: intern-soft name &optional obarray
This function returns the symbol in obarray whose name is name, or nil if obarray has no symbol with that name. Therefore, you can use intern-soft to test whether a symbol with a given name is already interned. If obarray is omitted, the value of the global variable obarray is used.

The argument name may also be a symbol; in that case, the function returns name if name is interned in the specified obarray, and otherwise nil.
(intern-soft "frazzle")        ; No such symbol exists.
     => nil
(make-symbol "frazzle")        ; Create an uninterned one.
     => frazzle
(intern-soft "frazzle")        ; That one cannot be found.
     => nil
(setq sym (intern "frazzle"))  ; Create an interned one.
     => frazzle
(intern-soft "frazzle")        ; That one can be found!
     => frazzle
(eq sym 'frazzle)              ; And it is the same one.
     => t
Variable: obarray
This variable is the standard obarray for use by intern and read.

Function: mapatoms function &optional obarray
This function calls function once with each symbol in the obarray obarray. Then it returns nil. If obarray is omitted, it defaults to the value of obarray, the standard obarray for ordinary symbols.
(setq count 0)
     => 0
(defun count-syms (s)
  (setq count (1+ count)))
     => count-syms
(mapatoms 'count-syms)
     => nil
count
     => 1871
See documentation in 24.2 Access to Documentation Strings, for another example using mapatoms.

Function: unintern symbol &optional obarray
This function deletes symbol from the obarray obarray. If symbol is not actually in the obarray, unintern does nothing. If obarray is nil, the current obarray is used.

If you provide a string instead of a symbol as symbol, it stands for a symbol name. Then unintern deletes the symbol (if any) in the obarray which has that name. If there is no such symbol, unintern does nothing.

If unintern does delete a symbol, it returns t. Otherwise it returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.4 Property Lists

A property list (plist for short) is a list of paired elements stored in the property list cell of a symbol. Each of the pairs associates a property name (usually a symbol) with a property or value. Property lists are generally used to record information about a symbol, such as its documentation as a variable, the name of the file where it was defined, or perhaps even the grammatical class of the symbol (representing a word) in a language-understanding system.

Character positions in a string or buffer can also have property lists. See section 32.19 Text Properties.

The property names and values in a property list can be any Lisp objects, but the names are usually symbols. Property list functions compare the property names using eq. Here is an example of a property list, found on the symbol progn when the compiler is loaded:
(lisp-indent-function 0 byte-compile byte-compile-progn)
Here lisp-indent-function and byte-compile are property names, and the other two elements are the corresponding values.

8.4.1 Property Lists and Association Lists

Comparison of the advantages of property lists and association lists.

8.4.2 Property List Functions for Symbols

Functions to access symbols' property lists.

8.4.3 Property Lists Outside Symbols

Accessing property lists stored elsewhere.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.4.1 Property Lists and Association Lists

Association lists (see section 5.8 Association Lists) are very similar to property lists. In contrast to association lists, the order of the pairs in the property list is not significant since the property names must be distinct.

Property lists are better than association lists for attaching information to various Lisp function names or variables. If your program keeps all of its associations in one association list, it will typically need to search that entire list each time it checks for an association. This could be slow. By contrast, if you keep the same information in the property lists of the function names or variables themselves, each search will scan only the length of one property list, which is usually short. This is why the documentation for a variable is recorded in a property named variable-documentation. The byte compiler likewise uses properties to record those functions needing special treatment.

However, association lists have their own advantages. Depending on your application, it may be faster to add an association to the front of an association list than to update a property. All properties for a symbol are stored in the same property list, so there is a possibility of a conflict between different uses of a property name. (For this reason, it is a good idea to choose property names that are probably unique, such as by beginning the property name with the program's usual name-prefix for variables and functions.) An association list may be used like a stack where associations are pushed on the front of the list and later discarded; this is not possible with a property list.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.4.2 Property List Functions for Symbols

Function: symbol-plist symbol
This function returns the property list of symbol.

Function: setplist symbol plist
This function sets symbol's property list to plist. Normally, plist should be a well-formed property list, but this is not enforced.
(setplist 'foo '(a 1 b (2 3) c nil))
     => (a 1 b (2 3) c nil)
(symbol-plist 'foo)
     => (a 1 b (2 3) c nil)
For symbols in special obarrays, which are not used for ordinary purposes, it may make sense to use the property list cell in a nonstandard fashion; in fact, the abbrev mechanism does so (see section 36. Abbrevs and Abbrev Expansion).

Function: get symbol property
This function finds the value of the property named property in symbol's property list. If there is no such property, nil is returned. Thus, there is no distinction between a value of nil and the absence of the property.

The name property is compared with the existing property names using eq, so any object is a legitimate property.

See put for an example.

Function: put symbol property value
This function puts value onto symbol's property list under the property name property, replacing any previous property value. The put function returns value.
(put 'fly 'verb 'transitive)
     =>'transitive
(put 'fly 'noun '(a buzzing little bug))
     => (a buzzing little bug)
(get 'fly 'verb)
     => transitive
(symbol-plist 'fly)
     => (verb transitive noun (a buzzing little bug))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.4.3 Property Lists Outside Symbols

These functions are useful for manipulating property lists that are stored in places other than symbols:

Function: plist-get plist property
This returns the value of the property property stored in the property list plist. For example,
(plist-get '(foo 4) 'foo)
     => 4
Function: plist-put plist property value
This stores value as the value of the property property in the property list plist. It may modify plist destructively, or it may construct a new list structure without altering the old. The function returns the modified property list, so you can store that back in the place where you got plist. For example,
(setq my-plist '(bar t foo 4))
     => (bar t foo 4)
(setq my-plist (plist-put my-plist 'foo 69))
     => (bar t foo 69)
(setq my-plist (plist-put my-plist 'quux '(a)))
     => (bar t foo 69 quux (a))
You could define put in terms of plist-put as follows:
(defun put (symbol prop value)
  (setplist symbol
            (plist-put (symbol-plist symbol) prop value)))
Function: plist-member plist property
This returns non-nil if plist contains the given property. Unlike plist-get, this allows you to distinguish between a missing property and a property with the value nil. The value is actually the tail of plist whose car is property.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9. Evaluation

The evaluation of expressions in Emacs Lisp is performed by the Lisp interpreter---a program that receives a Lisp object as input and computes its value as an expression. How it does this depends on the data type of the object, according to rules described in this chapter. The interpreter runs automatically to evaluate portions of your program, but can also be called explicitly via the Lisp primitive function eval.

9.1 Introduction to Evaluation

Evaluation in the scheme of things.

9.2 Kinds of Forms

How various sorts of objects are evaluated.

9.3 Quoting

Avoiding evaluation (to put constants in the program).

9.4 Eval

How to invoke the Lisp interpreter explicitly.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.1 Introduction to Evaluation

The Lisp interpreter, or evaluator, is the program that computes the value of an expression that is given to it. When a function written in Lisp is called, the evaluator computes the value of the function by evaluating the expressions in the function body. Thus, running any Lisp program really means running the Lisp interpreter.

How the evaluator handles an object depends primarily on the data type of the object.

A Lisp object that is intended for evaluation is called an expression or a form. The fact that expressions are data objects and not merely text is one of the fundamental differences between Lisp-like languages and typical programming languages. Any object can be evaluated, but in practice only numbers, symbols, lists and strings are evaluated very often.

It is very common to read a Lisp expression and then evaluate the expression, but reading and evaluation are separate activities, and either can be performed alone. Reading per se does not evaluate anything; it converts the printed representation of a Lisp object to the object itself. It is up to the caller of read whether this object is a form to be evaluated, or serves some entirely different purpose. See section 19.3 Input Functions.

Do not confuse evaluation with command key interpretation. The editor command loop translates keyboard input into a command (an interactively callable function) using the active keymaps, and then uses call-interactively to invoke the command. The execution of the command itself involves evaluation if the command is written in Lisp, but that is not a part of command key interpretation itself. See section 21. Command Loop.

Evaluation is a recursive process. That is, evaluation of a form may call eval to evaluate parts of the form. For example, evaluation of a function call first evaluates each argument of the function call, and then evaluates each form in the function body. Consider evaluation of the form (car x): the subform x must first be evaluated recursively, so that its value can be passed as an argument to the function car.

Evaluation of a function call ultimately calls the function specified in it. See section 12. Functions. The execution of the function may itself work by evaluating the function definition; or the function may be a Lisp primitive implemented in C, or it may be a byte-compiled function (see section 16. Byte Compilation).

The evaluation of forms takes place in a context called the environment, which consists of the current values and bindings of all Lisp variables.(3) Whenever a form refers to a variable without creating a new binding for it, the value of the variable's binding in the current environment is used. See section 11. Variables.

Evaluation of a form may create new environments for recursive evaluation by binding variables (see section 11.3 Local Variables). These environments are temporary and vanish by the time evaluation of the form is complete. The form may also make changes that persist; these changes are called side effects. An example of a form that produces side effects is (setq foo 1).

The details of what evaluation means for each kind of form are described below (see section 9.2 Kinds of Forms).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2 Kinds of Forms

A Lisp object that is intended to be evaluated is called a form. How Emacs evaluates a form depends on its data type. Emacs has three different kinds of form that are evaluated differently: symbols, lists, and "all other types". This section describes all three kinds, one by one, starting with the "all other types" which are self-evaluating forms.

9.2.1 Self-Evaluating Forms

Forms that evaluate to themselves.

9.2.2 Symbol Forms

Symbols evaluate as variables.

9.2.3 Classification of List Forms

How to distinguish various sorts of list forms.

9.2.4 Symbol Function Indirection

When a symbol appears as the car of a list, we find the real function via the symbol.

9.2.5 Evaluation of Function Forms

Forms that call functions.

9.2.6 Lisp Macro Evaluation

Forms that call macros.

9.2.7 Special Forms

"Special forms" are idiosyncratic primitives, most of them extremely important.

9.2.8 Autoloading

Functions set up to load files containing their real definitions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2.1 Self-Evaluating Forms

A self-evaluating form is any form that is not a list or symbol. Self-evaluating forms evaluate to themselves: the result of evaluation is the same object that was evaluated. Thus, the number 25 evaluates to 25, and the string "foo" evaluates to the string "foo". Likewise, evaluation of a vector does not cause evaluation of the elements of the vector--it returns the same vector with its contents unchanged.
'123               ; A number, shown without evaluation.
     => 123
123                ; Evaluated as usual---result is the same.
     => 123
(eval '123)        ; Evaluated ``by hand''---result is the same.
     => 123
(eval (eval '123)) ; Evaluating twice changes nothing.
     => 123
It is common to write numbers, characters, strings, and even vectors in Lisp code, taking advantage of the fact that they self-evaluate. However, it is quite unusual to do this for types that lack a read syntax, because there's no way to write them textually. It is possible to construct Lisp expressions containing these types by means of a Lisp program. Here is an example:
;; Build an expression containing a buffer object.
(setq print-exp (list 'print (current-buffer)))
     => (print #<buffer eval.texi>)
;; Evaluate it.
(eval print-exp)
     -| #<buffer eval.texi>
     => #<buffer eval.texi>
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2.2 Symbol Forms

When a symbol is evaluated, it is treated as a variable. The result is the variable's value, if it has one. If it has none (if its value cell is void), an error is signaled. For more information on the use of variables, see 11. Variables.

In the following example, we set the value of a symbol with setq. Then we evaluate the symbol, and get back the value that setq stored.
(setq a 123)
     => 123
(eval 'a)
     => 123
a
     => 123
The symbols nil and t are treated specially, so that the value of nil is always nil, and the value of t is always t; you cannot set or bind them to any other values. Thus, these two symbols act like self-evaluating forms, even though eval treats them like any other symbol. A symbol whose name starts with `:' also self-evaluates in the same way; likewise, its value ordinarily cannot be changed. See section 11.2 Variables that Never Change.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2.3 Classification of List Forms

A form that is a nonempty list is either a function call, a macro call, or a special form, according to its first element. These three kinds of forms are evaluated in different ways, described below. The remaining list elements constitute the arguments for the function, macro, or special form.

The first step in evaluating a nonempty list is to examine its first element. This element alone determines what kind of form the list is and how the rest of the list is to be processed. The first element is not evaluated, as it would be in some Lisp dialects such as Scheme.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2.4 Symbol Function Indirection

If the first element of the list is a symbol then evaluation examines the symbol's function cell, and uses its contents instead of the original symbol. If the contents are another symbol, this process, called symbol function indirection, is repeated until it obtains a non-symbol. See section 12.3 Naming a Function, for more information about using a symbol as a name for a function stored in the function cell of the symbol.

One possible consequence of this process is an infinite loop, in the event that a symbol's function cell refers to the same symbol. Or a symbol may have a void function cell, in which case the subroutine symbol-function signals a void-function error. But if neither of these things happens, we eventually obtain a non-symbol, which ought to be a function or other suitable object.

More precisely, we should now have a Lisp function (a lambda expression), a byte-code function, a primitive function, a Lisp macro, a special form, or an autoload object. Each of these types is a case described in one of the following sections. If the object is not one of these types, the error invalid-function is signaled.

The following example illustrates the symbol indirection process. We use fset to set the function cell of a symbol and symbol-function to get the function cell contents (see section 12.8 Accessing Function Cell Contents). Specifically, we store the symbol car into the function cell of first, and the symbol first into the function cell of erste.
;; Build this function cell linkage:
;;   -------------       -----        -------        -------
;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
;;   -------------       -----        -------        -------
(symbol-function 'car)
     => #<subr car>
(fset 'first 'car)
     => car
(fset 'erste 'first)
     => first
(erste '(1 2 3))   ; Call the function referenced by erste.
     => 1
By contrast, the following example calls a function without any symbol function indirection, because the first element is an anonymous Lisp function, not a symbol.
((lambda (arg) (erste arg))
 '(1 2 3))
     => 1
Executing the function itself evaluates its body; this does involve symbol function indirection when calling erste.

The built-in function indirect-function provides an easy way to perform symbol function indirection explicitly.

Function: indirect-function function
This function returns the meaning of function as a function. If function is a symbol, then it finds function's function definition and starts over with that value. If function is not a symbol, then it returns function itself.

Here is how you could define indirect-function in Lisp:
(defun indirect-function (function)
  (if (symbolp function)
      (indirect-function (symbol-function function))
    function))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2.5 Evaluation of Function Forms

If the first element of a list being evaluated is a Lisp function object, byte-code object or primitive function object, then that list is a function call. For example, here is a call to the function +:
(+ 1 x)
The first step in evaluating a function call is to evaluate the remaining elements of the list from left to right. The results are the actual argument values, one value for each list element. The next step is to call the function with this list of arguments, effectively using the function apply (see section 12.5 Calling Functions). If the function is written in Lisp, the arguments are used to bind the argument variables of the function (see section 12.2 Lambda Expressions); then the forms in the function body are evaluated in order, and the value of the last body form becomes the value of the function call.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2.6 Lisp Macro Evaluation

If the first element of a list being evaluated is a macro object, then the list is a macro call. When a macro call is evaluated, the elements of the rest of the list are not initially evaluated. Instead, these elements themselves are used as the arguments of the macro. The macro definition computes a replacement form, called the expansion of the macro, to be evaluated in place of the original form. The expansion may be any sort of form: a self-evaluating constant, a symbol, or a list. If the expansion is itself a macro call, this process of expansion repeats until some other sort of form results.

Ordinary evaluation of a macro call finishes by evaluating the expansion. However, the macro expansion is not necessarily evaluated right away, or at all, because other programs also expand macro calls, and they may or may not evaluate the expansions.

Normally, the argument expressions are not evaluated as part of computing the macro expansion, but instead appear as part of the expansion, so they are computed when the expansion is evaluated.

For example, given a macro defined as follows:
(defmacro cadr (x)
  (list 'car (list 'cdr x)))
an expression such as (cadr (assq 'handler list)) is a macro call, and its expansion is:
(car (cdr (assq 'handler list)))
Note that the argument (assq 'handler list) appears in the expansion.

See section 13. Macros, for a complete description of Emacs Lisp macros.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2.7 Special Forms

A special form is a primitive function specially marked so that its arguments are not all evaluated. Most special forms define control structures or perform variable bindings--things which functions cannot do.

Each special form has its own rules for which arguments are evaluated and which are used without evaluation. Whether a particular argument is evaluated may depend on the results of evaluating other arguments.

Here is a list, in alphabetical order, of all of the special forms in Emacs Lisp with a reference to where each is described.

and
see section 10.3 Constructs for Combining Conditions

catch
see section 10.5.1 Explicit Nonlocal Exits: catch and throw

cond
see section 10.2 Conditionals

condition-case
see section 10.5.3.3 Writing Code to Handle Errors

defconst
see section 11.5 Defining Global Variables

defmacro
see section 13.4 Defining Macros

defun
see section 12.4 Defining Functions

defvar
see section 11.5 Defining Global Variables

function
see section 12.7 Anonymous Functions

if
see section 10.2 Conditionals

interactive
see section 21.3 Interactive Call

let

let*
see section 11.3 Local Variables

or
see section 10.3 Constructs for Combining Conditions

prog1

prog2

progn
see section 10.1 Sequencing

quote
see section 9.3 Quoting

save-current-buffer
see section 27.2 The Current Buffer

save-excursion
see section 30.3 Excursions

save-restriction
see section 30.4 Narrowing

save-window-excursion
see section 28.17 Window Configurations

setq
see section 11.8 How to Alter a Variable Value

setq-default
see section 11.10.2 Creating and Deleting Buffer-Local Bindings

track-mouse
see section 29.13 Mouse Tracking

unwind-protect
see section 10.5 Nonlocal Exits

while
see section 10.4 Iteration

with-output-to-temp-buffer
see section 38.8 Temporary Displays

Common Lisp note: Here are some comparisons of special forms in GNU Emacs Lisp and Common Lisp. setq, if, and catch are special forms in both Emacs Lisp and Common Lisp. defun is a special form in Emacs Lisp, but a macro in Common Lisp. save-excursion is a special form in Emacs Lisp, but doesn't exist in Common Lisp. throw is a special form in Common Lisp (because it must be able to throw multiple values), but it is a function in Emacs Lisp (which doesn't have multiple values).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.2.8 Autoloading

The autoload feature allows you to call a function or macro whose function definition has not yet been loaded into Emacs. It specifies which file contains the definition. When an autoload object appears as a symbol's function definition, calling that symbol as a function automatically loads the specified file; then it calls the real definition loaded from that file. See section 15.4 Autoload.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.3 Quoting

The special form quote returns its single argument, as written, without evaluating it. This provides a way to include constant symbols and lists, which are not self-evaluating objects, in a program. (It is not necessary to quote self-evaluating objects such as numbers, strings, and vectors.)

Special Form: quote object
This special form returns object, without evaluating it.

Because quote is used so often in programs, Lisp provides a convenient read syntax for it. An apostrophe character (`'') followed by a Lisp object (in read syntax) expands to a list whose first element is quote, and whose second element is the object. Thus, the read syntax 'x is an abbreviation for (quote x).

Here are some examples of expressions that use quote:
(quote (+ 1 2))
     => (+ 1 2)
(quote foo)
     => foo
'foo
     => foo
''foo
     => (quote foo)
'(quote foo)
     => (quote foo)
['foo]
     => [(quote foo)]
Other quoting constructs include function (see section 12.7 Anonymous Functions), which causes an anonymous lambda expression written in Lisp to be compiled, and ``' (see section 13.5 Backquote), which is used to quote only part of a list, while computing and substituting other parts.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

9.4 Eval

Most often, forms are evaluated automatically, by virtue of their occurrence in a program being run. On rare occasions, you may need to write code that evaluates a form that is computed at run time, such as after reading a form from text being edited or getting one from a property list. On these occasions, use the eval function.

The functions and variables described in this section evaluate forms, specify limits to the evaluation process, or record recently returned values. Loading a file also does evaluation (see section 15. Loading).

Note: it is generally cleaner and more flexible to store a function in a data structure, and call it with funcall or apply, than to store an expression in the data structure and evaluate it. Using functions provides the ability to pass information to them as arguments.

Function: eval form
This is the basic function evaluating an expression. It evaluates form in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (see section 9.2 Kinds of Forms).

Since eval is a function, the argument expression that appears in a call to eval is evaluated twice: once as preparation before eval is called, and again by the eval function itself. Here is an example:
(setq foo 'bar)
     => bar
(setq bar 'baz)
     => baz
;; Here eval receives argument foo
(eval 'foo)
     => bar
;; Here eval receives argument bar, which is the value of foo
(eval foo)
     => baz
The number of currently active calls to eval is limited to max-lisp-eval-depth (see below).

Command: eval-region start end &optional stream read-function
This function evaluates the forms in the current buffer in the region defined by the positions start and end. It reads forms from the region and calls eval on them until the end of the region is reached, or until an error is signaled and not handled.

If stream is non-nil, the values that result from evaluating the expressions in the region are printed using stream. See section 19.4 Output Streams.

If read-function is non-nil, it should be a function, which is used instead of read to read expressions one by one. This function is called with one argument, the stream for reading input. You can also use the variable load-read-function (see section 15.1 How Programs Do Loading) to specify this function, but it is more robust to use the read-function argument.

eval-region always returns nil.

Command: eval-current-buffer &optional stream
This is like eval-region except that it operates on the whole buffer.

Variable: max-lisp-eval-depth
This variable defines the maximum depth allowed in calls to eval, apply, and funcall before an error is signaled (with error message "Lisp nesting exceeds max-lisp-eval-depth"). This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function.

The depth limit counts internal uses of eval, apply, and funcall, such as for calling the functions mentioned in Lisp expressions, and recursive evaluation of function call arguments and function body forms, as well as explicit calls in Lisp code.

The default value of this variable is 300. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute.

max-specpdl-size provides another limit on nesting. See section 11.3 Local Variables.

Variable: values
The value of this variable is a list of the values returned by all the expressions that were read, evaluated, and printed from buffers (including the minibuffer) by the standard Emacs commands which do this. The elements are ordered most recent first.
(setq x 1)
     => 1
(list 'A (1+ 2) auto-save-default)
     => (A 3 t)
values
     => ((A 3 t) 1 ...)
This variable is useful for referring back to values of forms recently evaluated. It is generally a bad idea to print the value of values itself, since this may be very long. Instead, examine particular elements, like this:
;; Refer to the most recent evaluation result.
(nth 0 values)
     => (A 3 t)
;; That put a new element on,
;;   so all elements move back one.
(nth 1 values)
     => (A 3 t)
;; This gets the element that was next-to-most-recent
;;   before this example.
(nth 3 values)
     => 1
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10. Control Structures

A Lisp program consists of expressions or forms (see section 9.2 Kinds of Forms). We control the order of execution of these forms by enclosing them in control structures. Control structures are special forms which control when, whether, or how many times to execute the forms they contain.

The simplest order of execution is sequential execution: first form a, then form b, and so on. This is what happens when you write several forms in succession in the body of a function, or at top level in a file of Lisp code--the forms are executed in the order written. We call this textual order. For example, if a function body consists of two forms a and b, evaluation of the function evaluates first a and then b. The result of evaluating b becomes the value of the function.

Explicit control structures make possible an order of execution other than sequential.

Emacs Lisp provides several kinds of control structure, including other varieties of sequencing, conditionals, iteration, and (controlled) jumps--all discussed below. The built-in control structures are special forms since their subforms are not necessarily evaluated or not evaluated sequentially. You can use macros to define your own control structure constructs (see section 13. Macros).

10.1 Sequencing

Evaluation in textual order.

10.2 Conditionals

if, cond, when, unless.

10.3 Constructs for Combining Conditions

and, or, not.

10.4 Iteration

while loops.

10.5 Nonlocal Exits

Jumping out of a sequence.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.1 Sequencing

Evaluating forms in the order they appear is the most common way control passes from one form to another. In some contexts, such as in a function body, this happens automatically. Elsewhere you must use a control structure construct to do this: progn, the simplest control construct of Lisp.

A progn special form looks like this:
(progn a b c ...)
and it says to execute the forms a, b, c, and so on, in that order. These forms are called the body of the progn form. The value of the last form in the body becomes the value of the entire progn. (progn) returns nil.

In the early days of Lisp, progn was the only way to execute two or more forms in succession and use the value of the last of them. But programmers found they often needed to use a progn in the body of a function, where (at that time) only one form was allowed. So the body of a function was made into an "implicit progn": several forms are allowed just as in the body of an actual progn. Many other control structures likewise contain an implicit progn. As a result, progn is not used as much as it was many years ago. It is needed now most often inside an unwind-protect, and, or, or in the then-part of an if.

Special Form: progn forms...
This special form evaluates all of the forms, in textual order, returning the result of the final form.
(progn (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
=> "The third form"
Two other control constructs likewise evaluate a series of forms but return a different value:

Special Form: prog1 form1 forms...
This special form evaluates form1 and all of the forms, in textual order, returning the result of form1.
(prog1 (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
=> "The first form"
Here is a way to remove the first element from a list in the variable x, then return the value of that former element:
(prog1 (car x) (setq x (cdr x)))
Special Form: prog2 form1 form2 forms...
This special form evaluates form1, form2, and all of the following forms, in textual order, returning the result of form2.
(prog2 (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
=> "The second form"
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.2 Conditionals

Conditional control structures choose among alternatives. Emacs Lisp has four conditional forms: if, which is much the same as in other languages; when and unless, which are variants of if; and cond, which is a generalized case statement.

Special Form: if condition then-form else-forms...
if chooses between the then-form and the else-forms based on the value of condition. If the evaluated condition is non-nil, then-form is evaluated and the result returned. Otherwise, the else-forms are evaluated in textual order, and the value of the last one is returned. (The else part of if is an example of an implicit progn. See section 10.1 Sequencing.)

If condition has the value nil, and no else-forms are given, if returns nil.

if is a special form because the branch that is not selected is never evaluated--it is ignored. Thus, in the example below, true is not printed because print is never called.
(if nil
    (print 'true)
  'very-false)
=> very-false
Macro: when condition then-forms...
This is a variant of if where there are no else-forms, and possibly several then-forms. In particular,
(when condition a b c)
is entirely equivalent to
(if condition (progn a b c) nil)
Macro: unless condition forms...
This is a variant of if where there is no then-form:
(unless condition a b c)
is entirely equivalent to
(if condition nil
   a b c)
Special Form: cond clause...
cond chooses among an arbitrary number of alternatives. Each clause in the cond must be a list. The CAR of this list is the condition; the remaining elements, if any, the body-forms. Thus, a clause looks like this:
(condition body-forms...)
cond tries the clauses in textual order, by evaluating the condition of each clause. If the value of condition is non-nil, the clause "succeeds"; then cond evaluates its body-forms, and the value of the last of body-forms becomes the value of the cond. The remaining clauses are ignored.

If the value of condition is nil, the clause "fails", so the cond moves on to the following clause, trying its condition.

If every condition evaluates to nil, so that every clause fails, cond returns nil.

A clause may also look like this:
(condition)
Then, if condition is non-nil when tested, the value of condition becomes the value of the cond form.

The following example has four clauses, which test for the cases where the value of x is a number, string, buffer and symbol, respectively:
(cond ((numberp x) x)
      ((stringp x) x)
      ((bufferp x)
       (setq temporary-hack x) ; multiple body-forms
       (buffer-name x))        ; in one clause
      ((symbolp x) (symbol-value x)))
Often we want to execute the last clause whenever none of the previous clauses was successful. To do this, we use t as the condition of the last clause, like this: (t body-forms). The form t evaluates to t, which is never nil, so this clause never fails, provided the cond gets to it at all.

For example,
(setq a 5)
(cond ((eq a 'hack) 'foo)
      (t "default"))
=> "default"
This cond expression returns foo if the value of a is hack, and returns the string "default" otherwise.

Any conditional construct can be expressed with cond or with if. Therefore, the choice between them is a matter of style. For example:
(if a b c)
==
(cond (a b) (t c))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.3 Constructs for Combining Conditions

This section describes three constructs that are often used together with if and cond to express complicated conditions. The constructs and and or can also be used individually as kinds of multiple conditional constructs.

Function: not condition
This function tests for the falsehood of condition. It returns t if condition is nil, and nil otherwise. The function not is identical to null, and we recommend using the name null if you are testing for an empty list.

Special Form: and conditions...
The and special form tests whether all the conditions are true. It works by evaluating the conditions one by one in the order written.

If any of the conditions evaluates to nil, then the result of the and must be nil regardless of the remaining conditions; so and returns nil right away, ignoring the remaining conditions.

If all the conditions turn out non-nil, then the value of the last of them becomes the value of the and form. Just (and), with no conditions, returns t, appropriate because all the conditions turned out non-nil. (Think about it; which one did not?)

Here is an example. The first condition returns the integer 1, which is not nil. Similarly, the second condition returns the integer 2, which is not nil. The third condition is nil, so the remaining condition is never evaluated.
(and (print 1) (print 2) nil (print 3))
     -| 1
     -| 2
=> nil
Here is a more realistic example of using and:
(if (and (consp foo) (eq (car foo) 'x))
    (message "foo is a list starting with x"))
Note that (car foo) is not executed if (consp foo) returns nil, thus avoiding an error.

and can be expressed in terms of either if or cond. For example:
(and arg1 arg2 arg3)
==
(if arg1 (if arg2 arg3))
==
(cond (arg1 (cond (arg2 arg3))))
Special Form: or conditions...
The or special form tests whether at least one of the conditions is true. It works by evaluating all the conditions one by one in the order written.

If any of the conditions evaluates to a non-nil value, then the result of the or must be non-nil; so or returns right away, ignoring the remaining conditions. The value it returns is the non-nil value of the condition just evaluated.

If all the conditions turn out nil, then the or expression returns nil. Just (or), with no conditions, returns nil, appropriate because all the conditions turned out nil. (Think about it; which one did not?)

For example, this expression tests whether x is either nil or the integer zero:
(or (eq x nil) (eq x 0))
Like the and construct, or can be written in terms of cond. For example:
(or arg1 arg2 arg3)
==
(cond (arg1)
      (arg2)
      (arg3))
You could almost write or in terms of if, but not quite:
(if arg1 arg1
  (if arg2 arg2
    arg3))
This is not completely equivalent because it can evaluate arg1 or arg2 twice. By contrast, (or arg1 arg2 arg3) never evaluates any argument more than once.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.4 Iteration

Iteration means executing part of a program repetitively. For example, you might want to repeat some computation once for each element of a list, or once for each integer from 0 to n. You can do this in Emacs Lisp with the special form while:

Special Form: while condition forms...
while first evaluates condition. If the result is non-nil, it evaluates forms in textual order. Then it reevaluates condition, and if the result is non-nil, it evaluates forms again. This process repeats until condition evaluates to nil.

There is no limit on the number of iterations that may occur. The loop will continue until either condition evaluates to nil or until an error or throw jumps out of it (see section 10.5 Nonlocal Exits).

The value of a while form is always nil.
(setq num 0)
     => 0
(while (< num 4)
  (princ (format "Iteration %d." num))
  (setq num (1+ num)))
     -| Iteration 0.
     -| Iteration 1.
     -| Iteration 2.
     -| Iteration 3.
     => nil
To write a "repeat...until" loop, which will execute something on each iteration and then do the end-test, put the body followed by the end-test in a progn as the first argument of while, as shown here:
(while (progn
         (forward-line 1)
         (not (looking-at "^$"))))
This moves forward one line and continues moving by lines until it reaches an empty line. It is peculiar in that the while has no body, just the end test (which also does the real work of moving point).

The dolist and dotimes macros provide convenient ways to write two common kinds of loops.

Macro: dolist (var list [result]) body...
This construct executes body once for each element of list, using the variable var to hold the current element. Then it returns the value of evaluating result, or nil if result is omitted. For example, here is how you could use dolist to define the reverse function:
(defun reverse (list)
  (let (value)
    (dolist (elt list value)
      (setq value (cons elt value)))))
Macro: dotimes (var count [result]) body...
This construct executes body once for each integer from 0 (inclusive) to count (exclusive), using the variable var to hold the integer for the current iteration. Then it returns the value of evaluating result, or nil if result is omitted. Here is an example of using dotimes do something 100 times:
(dotimes (i 100)
  (insert "I will not obey absurd orders\n"))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5 Nonlocal Exits

A nonlocal exit is a transfer of control from one point in a program to another remote point. Nonlocal exits can occur in Emacs Lisp as a result of errors; you can also use them under explicit control. Nonlocal exits unbind all variable bindings made by the constructs being exited.

10.5.1 Explicit Nonlocal Exits: catch and throw

Nonlocal exits for the program's own purposes.

10.5.2 Examples of catch and throw

Showing how such nonlocal exits can be written.

10.5.3 Errors

How errors are signaled and handled.

10.5.4 Cleaning Up from Nonlocal Exits

Arranging to run a cleanup form if an error happens.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5.1 Explicit Nonlocal Exits: catch and throw

Most control constructs affect only the flow of control within the construct itself. The function throw is the exception to this rule of normal program execution: it performs a nonlocal exit on request. (There are other exceptions, but they are for error handling only.) throw is used inside a catch, and jumps back to that catch. For example:
(defun foo-outer ()
  (catch 'foo
    (foo-inner)))

(defun foo-inner ()
  ...
  (if x
      (throw 'foo t))
  ...)
The throw form, if executed, transfers control straight back to the corresponding catch, which returns immediately. The code following the throw is not executed. The second argument of throw is used as the return value of the catch.

The function throw finds the matching catch based on the first argument: it searches for a catch whose first argument is eq to the one specified in the throw. If there is more than one applicable catch, the innermost one takes precedence. Thus, in the above example, the throw specifies foo, and the catch in foo-outer specifies the same symbol, so that catch is the applicable one (assuming there is no other matching catch in between).

Executing throw exits all Lisp constructs up to the matching catch, including function calls. When binding constructs such as let or function calls are exited in this way, the bindings are unbound, just as they are when these constructs exit normally (see section 11.3 Local Variables). Likewise, throw restores the buffer and position saved by save-excursion (see section 30.3 Excursions), and the narrowing status saved by save-restriction and the window selection saved by save-window-excursion (see section 28.17 Window Configurations). It also runs any cleanups established with the unwind-protect special form when it exits that form (see section 10.5.4 Cleaning Up from Nonlocal Exits).

The throw need not appear lexically within the catch that it jumps to. It can equally well be called from another function called within the catch. As long as the throw takes place chronologically after entry to the catch, and chronologically before exit from it, it has access to that catch. This is why throw can be used in commands such as exit-recursive-edit that throw back to the editor command loop (see section 21.12 Recursive Editing).

Common Lisp note: Most other versions of Lisp, including Common Lisp, have several ways of transferring control nonsequentially: return, return-from, and go, for example. Emacs Lisp has only throw.

Special Form: catch tag body...
catch establishes a return point for the throw function. The return point is distinguished from other such return points by tag, which may be any Lisp object except nil. The argument tag is evaluated normally before the return point is established.

With the return point in effect, catch evaluates the forms of the body in textual order. If the forms execute normally (without error or nonlocal exit) the value of the last body form is returned from the catch.

If a throw is executed during the execution of body, specifying the same value tag, the catch form exits immediately; the value it returns is whatever was specified as the second argument of throw.

Function: throw tag value
The purpose of throw is to return from a return point previously established with catch. The argument tag is used to choose among the various existing return points; it must be eq to the value specified in the catch. If multiple return points match tag, the innermost one is used.

The argument value is used as the value to return from that catch.

If no return point is in effect with tag tag, then a no-catch error is signaled with data (tag value).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5.2 Examples of catch and throw

One way to use catch and throw is to exit from a doubly nested loop. (In most languages, this would be done with a "go to".) Here we compute (foo i j) for i and j varying from 0 to 9:
(defun search-foo ()
  (catch 'loop
    (let ((i 0))
      (while (< i 10)
        (let ((j 0))
          (while (< j 10)
            (if (foo i j)
                (throw 'loop (list i j)))
            (setq j (1+ j))))
        (setq i (1+ i))))))
If foo ever returns non-nil, we stop immediately and return a list of i and j. If foo always returns nil, the catch returns normally, and the value is nil, since that is the result of the while.

Here are two tricky examples, slightly different, showing two return points at once. First, two return points with the same tag, hack:
(defun catch2 (tag)
  (catch tag
    (throw 'hack 'yes)))
=> catch2

(catch 'hack
  (print (catch2 'hack))
  'no)
-| yes
=> no
Since both return points have tags that match the throw, it goes to the inner one, the one established in catch2. Therefore, catch2 returns normally with value yes, and this value is printed. Finally the second body form in the outer catch, which is 'no, is evaluated and returned from the outer catch.

Now let's change the argument given to catch2:
(catch 'hack
  (print (catch2 'quux))
  'no)
=> yes
We still have two return points, but this time only the outer one has the tag hack; the inner one has the tag quux instead. Therefore, throw makes the outer catch return the value yes. The function print is never called, and the body-form 'no is never evaluated.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5.3 Errors

When Emacs Lisp attempts to evaluate a form that, for some reason, cannot be evaluated, it signals an error.

When an error is signaled, Emacs's default reaction is to print an error message and terminate execution of the current command. This is the right thing to do in most cases, such as if you type C-f at the end of the buffer.

In complicated programs, simple termination may not be what you want. For example, the program may have made temporary changes in data structures, or created temporary buffers that should be deleted before the program is finished. In such cases, you would use unwind-protect to establish cleanup expressions to be evaluated in case of error. (See section 10.5.4 Cleaning Up from Nonlocal Exits.) Occasionally, you may wish the program to continue execution despite an error in a subroutine. In these cases, you would use condition-case to establish error handlers to recover control in case of error.

Resist the temptation to use error handling to transfer control from one part of the program to another; use catch and throw instead. See section 10.5.1 Explicit Nonlocal Exits: catch and throw.

10.5.3.1 How to Signal an Error

How to report an error.

10.5.3.2 How Emacs Processes Errors

What Emacs does when you report an error.

10.5.3.3 Writing Code to Handle Errors

How you can trap errors and continue execution.

10.5.3.4 Error Symbols and Condition Names

How errors are classified for trapping them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5.3.1 How to Signal an Error

Most errors are signaled "automatically" within Lisp primitives which you call for other purposes, such as if you try to take the CAR of an integer or move forward a character at the end of the buffer. You can also signal errors explicitly with the functions error and signal.

Quitting, which happens when the user types C-g, is not considered an error, but it is handled almost like an error. See section 21.10 Quitting.

The error message should state what is wrong ("File does not exist"), not how things ought to be ("File must exist"). The convention in Emacs Lisp is that error messages should start with a capital letter, but should not end with any sort of punctuation.

Function: error format-string &rest args
This function signals an error with an error message constructed by applying format (see section 4.6 Conversion of Characters and Strings) to format-string and args.

These examples show typical uses of error:
(error "That is an error -- try something else")
     error--> That is an error -- try something else

(error "You have committed %d errors" 10)
     error--> You have committed 10 errors
error works by calling signal with two arguments: the error symbol error, and a list containing the string returned by format.

Warning: If you want to use your own string as an error message verbatim, don't just write (error string). If string contains `%', it will be interpreted as a format specifier, with undesirable results. Instead, use (error "%s" string).

Function: signal error-symbol data
This function signals an error named by error-symbol. The argument data is a list of additional Lisp objects relevant to the circumstances of the error.

The argument error-symbol must be an error symbol---a symbol bearing a property error-conditions whose value is a list of condition names. This is how Emacs Lisp classifies different sorts of errors.

The number and significance of the objects in data depends on error-symbol. For example, with a wrong-type-arg error, there should be two objects in the list: a predicate that describes the type that was expected, and the object that failed to fit that type. See section 10.5.3.4 Error Symbols and Condition Names, for a description of error symbols.

Both error-symbol and data are available to any error handlers that handle the error: condition-case binds a local variable to a list of the form (error-symbol . data) (see section 10.5.3.3 Writing Code to Handle Errors). If the error is not handled, these two values are used in printing the error message.

The function signal never returns (though in older Emacs versions it could sometimes return).
(signal 'wrong-number-of-arguments '(x y))
     error--> Wrong number of arguments: x, y

(signal 'no-such-error '("My unknown error condition"))
     error--> peculiar error: "My unknown error condition"
Common Lisp note: Emacs Lisp has nothing like the Common Lisp concept of continuable errors.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5.3.2 How Emacs Processes Errors

When an error is signaled, signal searches for an active handler for the error. A handler is a sequence of Lisp expressions designated to be executed if an error happens in part of the Lisp program. If the error has an applicable handler, the handler is executed, and control resumes following the handler. The handler executes in the environment of the condition-case that established it; all functions called within that condition-case have already been exited, and the handler cannot return to them.

If there is no applicable handler for the error, the current command is terminated and control returns to the editor command loop, because the command loop has an implicit handler for all kinds of errors. The command loop's handler uses the error symbol and associated data to print an error message.

An error that has no explicit handler may call the Lisp debugger. The debugger is enabled if the variable debug-on-error (see section 18.1.1 Entering the Debugger on an Error) is non-nil. Unlike error handlers, the debugger runs in the environment of the error, so that you can examine values of variables precisely as they were at the time of the error.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5.3.3 Writing Code to Handle Errors

The usual effect of signaling an error is to terminate the command that is running and return immediately to the Emacs editor command loop. You can arrange to trap errors occurring in a part of your program by establishing an error handler, with the special form condition-case. A simple example looks like this:
(condition-case nil
    (delete-file filename)
  (error nil))
This deletes the file named filename, catching any error and returning nil if an error occurs.

The second argument of condition-case is called the protected form. (In the example above, the protected form is a call to delete-file.) The error handlers go into effect when this form begins execution and are deactivated when this form returns. They remain in effect for all the intervening time. In particular, they are in effect during the execution of functions called by this form, in their subroutines, and so on. This is a good thing, since, strictly speaking, errors can be signaled only by Lisp primitives (including signal and error) called by the protected form, not by the protected form itself.

The arguments after the protected form are handlers. Each handler lists one or more condition names (which are symbols) to specify which errors it will handle. The error symbol specified when an error is signaled also defines a list of condition names. A handler applies to an error if they have any condition names in common. In the example above, there is one handler, and it specifies one condition name, error, which covers all errors.

The search for an applicable handler checks all the established handlers starting with the most recently established one. Thus, if two nested condition-case forms offer to handle the same error, the inner of the two gets to handle it.

If an error is handled by some condition-case form, this ordinarily prevents the debugger from being run, even if debug-on-error says this error should invoke the debugger. See section 18.1.1 Entering the Debugger on an Error. If you want to be able to debug errors that are caught by a condition-case, set the variable debug-on-signal to a non-nil value.

When an error is handled, control returns to the handler. Before this happens, Emacs unbinds all variable bindings made by binding constructs that are being exited and executes the cleanups of all unwind-protect forms that are exited. Once control arrives at the handler, the body of the handler is executed.

After execution of the handler body, execution returns from the condition-case form. Because the protected form is exited completely before execution of the handler, the handler cannot resume execution at the point of the error, nor can it examine variable bindings that were made within the protected form. All it can do is clean up and proceed.

The condition-case construct is often used to trap errors that are predictable, such as failure to open a file in a call to insert-file-contents. It is also used to trap errors that are totally unpredictable, such as when the program evaluates an expression read from the user.

Error signaling and handling have some resemblance to throw and catch (see section 10.5.1 Explicit Nonlocal Exits: catch and throw), but they are entirely separate facilities. An error cannot be caught by a catch, and a throw cannot be handled by an error handler (though using throw when there is no suitable catch signals an error that can be handled).

Special Form: condition-case var protected-form handlers...
This special form establishes the error handlers handlers around the execution of protected-form. If protected-form executes without error, the value it returns becomes the value of the condition-case form; in this case, the condition-case has no effect. The condition-case form makes a difference when an error occurs during protected-form.

Each of the handlers is a list of the form (conditions body...). Here conditions is an error condition name to be handled, or a list of condition names; body is one or more Lisp expressions to be executed when this handler handles an error. Here are examples of handlers:
(error nil)

(arith-error (message "Division by zero"))

((arith-error file-error)
 (message
  "Either division by zero or failure to open a file"))
Each error that occurs has an error symbol that describes what kind of error it is. The error-conditions property of this symbol is a list of condition names (see section 10.5.3.4 Error Symbols and Condition Names). Emacs searches all the active condition-case forms for a handler that specifies one or more of these condition names; the innermost matching condition-case handles the error. Within this condition-case, the first applicable handler handles the error.

After executing the body of the handler, the condition-case returns normally, using the value of the last form in the handler body as the overall value.

The argument var is a variable. condition-case does not bind this variable when executing the protected-form, only when it handles an error. At that time, it binds var locally to an error description, which is a list giving the particulars of the error. The error description has the form (error-symbol . data). The handler can refer to this list to decide what to do. For example, if the error is for failure opening a file, the file name is the second element of data---the third element of the error description.

If var is nil, that means no variable is bound. Then the error symbol and associated data are not available to the handler.

Function: error-message-string error-description
This function returns the error message string for a given error descriptor. It is useful if you want to handle an error by printing the usual error message for that error.

Here is an example of using condition-case to handle the error that results from dividing by zero. The handler displays the error message (but without a beep), then returns a very large number.
(defun safe-divide (dividend divisor)
  (condition-case err
      ;; Protected form.
      (/ dividend divisor)
    ;; The handler.
    (arith-error                        ; Condition.
     ;; Display the usual message for this error.
     (message "%s" (error-message-string err))
     1000000)))
=> safe-divide

(safe-divide 5 0)
     -| Arithmetic error: (arith-error)
=> 1000000
The handler specifies condition name arith-error so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this condition-case. Thus,
(safe-divide nil 3)
     error--> Wrong type argument: number-or-marker-p, nil
Here is a condition-case that catches all kinds of errors, including those signaled with error:
(setq baz 34)
     => 34

(condition-case err
    (if (eq baz 35)
        t
      ;; This is a call to the function error.
      (error "Rats!  The variable %s was %s, not 35" 'baz baz))
  ;; This is the handler; it is not a form.
  (error (princ (format "The error was: %s" err))
         2))
-| The error was: (error "Rats!  The variable baz was 34, not 35")
=> 2
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5.3.4 Error Symbols and Condition Names

When you signal an error, you specify an error symbol to specify the kind of error you have in mind. Each error has one and only one error symbol to categorize it. This is the finest classification of errors defined by the Emacs Lisp language.

These narrow classifications are grouped into a hierarchy of wider classes called error conditions, identified by condition names. The narrowest such classes belong to the error symbols themselves: each error symbol is also a condition name. There are also condition names for more extensive classes, up to the condition name error which takes in all kinds of errors. Thus, each error has one or more condition names: error, the error symbol if that is distinct from error, and perhaps some intermediate classifications.

In order for a symbol to be an error symbol, it must have an error-conditions property which gives a list of condition names. This list defines the conditions that this kind of error belongs to. (The error symbol itself, and the symbol error, should always be members of this list.) Thus, the hierarchy of condition names is defined by the error-conditions properties of the error symbols.

In addition to the error-conditions list, the error symbol should have an error-message property whose value is a string to be printed when that error is signaled but not handled. If the error-message property exists, but is not a string, the error message `peculiar error' is used.

Here is how we define a new error symbol, new-error:
(put 'new-error
     'error-conditions
     '(error my-own-errors new-error))
=> (error my-own-errors new-error)
(put 'new-error 'error-message "A new error")
=> "A new error"
This error has three condition names: new-error, the narrowest classification; my-own-errors, which we imagine is a wider classification; and error, which is the widest of all.

The error string should start with a capital letter but it should not end with a period. This is for consistency with the rest of Emacs. Naturally, Emacs will never signal new-error on its own; only an explicit call to signal (see section 10.5.3.1 How to Signal an Error) in your code can do this:
(signal 'new-error '(x y))
     error--> A new error: x, y
This error can be handled through any of the three condition names. This example handles new-error and any other errors in the class my-own-errors:
(condition-case foo
    (bar nil t)
  (my-own-errors nil))
The significant way that errors are classified is by their condition names--the names used to match errors with handlers. An error symbol serves only as a convenient way to specify the intended error message and list of condition names. It would be cumbersome to give signal a list of condition names rather than one error symbol.

By contrast, using only error symbols without condition names would seriously decrease the power of condition-case. Condition names make it possible to categorize errors at various levels of generality when you write an error handler. Using error symbols alone would eliminate all but the narrowest level of classification.

See section F. Standard Errors, for a list of all the standard error symbols and their conditions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

10.5.4 Cleaning Up from Nonlocal Exits

The unwind-protect construct is essential whenever you temporarily put a data structure in an inconsistent state; it permits you to make the data consistent again in the event of an error or throw.

Special Form: unwind-protect body cleanup-forms...
unwind-protect executes the body with a guarantee that the cleanup-forms will be evaluated if control leaves body, no matter how that happens. The body may complete normally, or execute a throw out of the unwind-protect, or cause an error; in all cases, the cleanup-forms will be evaluated.

If the body forms finish normally, unwind-protect returns the value of the last body form, after it evaluates the cleanup-forms. If the body forms do not finish, unwind-protect does not return any value in the normal sense.

Only the body is protected by the unwind-protect. If any of the cleanup-forms themselves exits nonlocally (via a throw or an error), unwind-protect is not guaranteed to evaluate the rest of them. If the failure of one of the cleanup-forms has the potential to cause trouble, then protect it with another unwind-protect around that form.

The number of currently active unwind-protect forms counts, together with the number of local variable bindings, against the limit max-specpdl-size (see section 11.3 Local Variables).

For example, here we make an invisible buffer for temporary use, and make sure to kill it before finishing:
(save-excursion
  (let ((buffer (get-buffer-create " *temp*")))
    (set-buffer buffer)
    (unwind-protect
        body
      (kill-buffer buffer))))
You might think that we could just as well write (kill-buffer (current-buffer)) and dispense with the variable buffer. However, the way shown above is safer, if body happens to get an error after switching to a different buffer! (Alternatively, you could write another save-excursion around the body, to ensure that the temporary buffer becomes current again in time to kill it.)

Emacs includes a standard macro called with-temp-buffer which expands into more or less the code shown above (see section 27.2 The Current Buffer). Several of the macros defined in this manual use unwind-protect in this way.

Here is an actual example derived from an FTP package. It creates a process (see section 37. Processes) to try to establish a connection to a remote machine. As the function ftp-login is highly susceptible to numerous problems that the writer of the function cannot anticipate, it is protected with a form that guarantees deletion of the process in the event of failure. Otherwise, Emacs might fill up with useless subprocesses.
(let ((win nil))
  (unwind-protect
      (progn
        (setq process (ftp-setup-buffer host file))
        (if (setq win (ftp-login process host user password))
            (message "Logged in")
          (error "Ftp login failed")))
    (or win (and process (delete-process process)))))
This example has a small bug: if the user types C-g to quit, and the quit happens immediately after the function ftp-setup-buffer returns but before the variable process is set, the process will not be killed. There is no easy way to fix this bug, but at least it is very unlikely.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11. Variables

A variable is a name used in a program to stand for a value. Nearly all programming languages have variables of some sort. In the text of a Lisp program, variables are written using the syntax for symbols.

In Lisp, unlike most programming languages, programs are represented primarily as Lisp objects and only secondarily as text. The Lisp objects used for variables are symbols: the symbol name is the variable name, and the variable's value is stored in the value cell of the symbol. The use of a symbol as a variable is independent of its use as a function name. See section 8.1 Symbol Components.

The Lisp objects that constitute a Lisp program determine the textual form of the program--it is simply the read syntax for those Lisp objects. This is why, for example, a variable in a textual Lisp program is written using the read syntax for the symbol that represents the variable.

11.1 Global Variables

Variable values that exist permanently, everywhere.

11.2 Variables that Never Change

Certain "variables" have values that never change.

11.3 Local Variables

Variable values that exist only temporarily.

11.4 When a Variable is "Void"

Symbols that lack values.

11.5 Defining Global Variables

A definition says a symbol is used as a variable.

11.6 Tips for Defining Variables Robustly

Things you should think about when you define a variable.

11.7 Accessing Variable Values

Examining values of variables whose names are known only at run time.

11.8 How to Alter a Variable Value

Storing new values in variables.

11.9 Scoping Rules for Variable Bindings

How Lisp chooses among local and global values.

11.10 Buffer-Local Variables

Variable values in effect only in one buffer.

11.11 Frame-Local Variables

Variable values in effect only in one frame.

11.12 Possible Future Local Variables

New kinds of local values we might add some day.

11.13 File Local Variables

Handling local variable lists in files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.1 Global Variables

The simplest way to use a variable is globally. This means that the variable has just one value at a time, and this value is in effect (at least for the moment) throughout the Lisp system. The value remains in effect until you specify a new one. When a new value replaces the old one, no trace of the old value remains in the variable.

You specify a value for a symbol with setq. For example,
(setq x '(a b))
gives the variable x the value (a b). Note that setq does not evaluate its first argument, the name of the variable, but it does evaluate the second argument, the new value.

Once the variable has a value, you can refer to it by using the symbol by itself as an expression. Thus,
x => (a b)
assuming the setq form shown above has already been executed.

If you do set the same variable again, the new value replaces the old one:
x
     => (a b)
(setq x 4)
     => 4
x
     => 4
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.2 Variables that Never Change

In Emacs Lisp, certain symbols normally evaluate to themselves. These include nil and t, as well as any symbol whose name starts with `:' (these are called keywords). These symbols cannot be rebound, nor can their values be changed. Any attempt to set or bind nil or t signals a setting-constant error. The same is true for a keyword (a symbol whose name starts with `:'), if it is interned in the standard obarray, except that setting such a symbol to itself is not an error.
nil == 'nil
     => nil
(setq nil 500)
error--> Attempt to set constant symbol: nil
Function: keywordp object
function returns t if object is a symbol whose name starts with `:', interned in the standard obarray, and returns nil otherwise.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.3 Local Variables

Global variables have values that last until explicitly superseded with new values. Sometimes it is useful to create variable values that exist temporarily--only until a certain part of the program finishes. These values are called local, and the variables so used are called local variables.

For example, when a function is called, its argument variables receive new local values that last until the function exits. The let special form explicitly establishes new local values for specified variables; these last until exit from the let form.

Establishing a local value saves away the previous value (or lack of one) of the variable. When the life span of the local value is over, the previous value is restored. In the mean time, we say that the previous value is shadowed and not visible. Both global and local values may be shadowed (see section 11.9.1 Scope).

If you set a variable (such as with setq) while it is local, this replaces the local value; it does not alter the global value, or previous local values, that are shadowed. To model this behavior, we speak of a local binding of the variable as well as a local value.

The local binding is a conceptual place that holds a local value. Entry to a function, or a special form such as let, creates the local binding; exit from the function or from the let removes the local binding. As long as the local binding lasts, the variable's value is stored within it. Use of setq or set while there is a local binding stores a different value into the local binding; it does not create a new binding.

We also speak of the global binding, which is where (conceptually) the global value is kept.

A variable can have more than one local binding at a time (for example, if there are nested let forms that bind it). In such a case, the most recently created local binding that still exists is the current binding of the variable. (This rule is called dynamic scoping; see 11.9 Scoping Rules for Variable Bindings.) If there are no local bindings, the variable's global binding is its current binding. We sometimes call the current binding the most-local existing binding, for emphasis. Ordinary evaluation of a symbol always returns the value of its current binding.

The special forms let and let* exist to create local bindings.

Special Form: let (bindings...) forms...
This special form binds variables according to bindings and then evaluates all of the forms in textual order. The let-form returns the value of the last form in forms.

Each of the bindings is either (i) a symbol, in which case that symbol is bound to nil; or (ii) a list of the form (symbol value-form), in which case symbol is bound to the result of evaluating value-form. If value-form is omitted, nil is used.

All of the value-forms in bindings are evaluated in the order they appear and before binding any of the symbols to them. Here is an example of this: Z is bound to the old value of Y, which is 2, not the new value of Y, which is 1.
(setq Y 2)
     => 2
(let ((Y 1)
      (Z Y))
  (list Y Z))
     => (1 2)
Special Form: let* (bindings...) forms...
This special form is like let, but it binds each variable right after computing its local value, before computing the local value for the next variable. Therefore, an expression in bindings can reasonably refer to the preceding symbols bound in this let* form. Compare the following example with the example above for let.
(setq Y 2)
     => 2
(let* ((Y 1)
       (Z Y))    ; Use the just-established value of Y.
  (list Y Z))
     => (1 1)
Here is a complete list of the other facilities that create local bindings:

Function calls (see section 12. Functions).

Macro calls (see section 13. Macros).

condition-case (see section 10.5.3 Errors).

Variables can also have buffer-local bindings (see section 11.10 Buffer-Local Variables) and frame-local bindings (see section 11.11 Frame-Local Variables); a few variables have terminal-local bindings (see section 29.2 Multiple Displays). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on "where" you are in Emacs, rather than localized in time.

Variable: max-specpdl-size
This variable defines the limit on the total number of local variable bindings and unwind-protect cleanups (see section 10.5 Nonlocal Exits) that are allowed before signaling an error (with data "Variable binding depth exceeds max-specpdl-size").

This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function. max-lisp-eval-depth provides another limit on depth of nesting. See section 9.4 Eval.

The default value is 600. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.4 When a Variable is "Void"

If you have never given a symbol any value as a global variable, we say that that symbol's global value is void. In other words, the symbol's value cell does not have any Lisp object in it. If you try to evaluate the symbol, you get a void-variable error rather than a value.

Note that a value of nil is not the same as void. The symbol nil is a Lisp object and can be the value of a variable just as any other object can be; but it is a value. A void variable does not have any value.

After you have given a variable a value, you can make it void once more using makunbound.

Function: makunbound symbol
This function makes the current variable binding of symbol void. Subsequent attempts to use this symbol's value as a variable will signal the error void-variable, unless and until you set it again.

makunbound returns symbol.
(makunbound 'x)      ; Make the global value of x void.
     => x
x
error--> Symbol's value as variable is void: x
If symbol is locally bound, makunbound affects the most local existing binding. This is the only way a symbol can have a void local binding, since all the constructs that create local bindings create them with values. In this case, the voidness lasts at most as long as the binding does; when the binding is removed due to exit from the construct that made it, the previous local or global binding is reexposed as usual, and the variable is no longer void unless the newly reexposed binding was void all along.
(setq x 1)               ; Put a value in the global binding.
     => 1
(let ((x 2))             ; Locally bind it.
  (makunbound 'x)        ; Void the local binding.
  x)
error--> Symbol's value as variable is void: x
x                        ; The global binding is unchanged.
     => 1

(let ((x 2))             ; Locally bind it.
  (let ((x 3))           ; And again.
    (makunbound 'x)      ; Void the innermost-local binding.
    x))                  ; And refer: it's void.
error--> Symbol's value as variable is void: x

(let ((x 2))
  (let ((x 3))
    (makunbound 'x))     ; Void inner binding, then remove it.
  x)                     ; Now outer let binding is visible.
     => 2
A variable that has been made void with makunbound is indistinguishable from one that has never received a value and has always been void.

You can use the function boundp to test whether a variable is currently void.

Function: boundp variable
boundp returns t if variable (a symbol) is not void; more precisely, if its current binding is not void. It returns nil otherwise.
(boundp 'abracadabra)          ; Starts out void.
     => nil
(let ((abracadabra 5))         ; Locally bind it.
  (boundp 'abracadabra))
     => t
(boundp 'abracadabra)          ; Still globally void.
     => nil
(setq abracadabra 5)           ; Make it globally nonvoid.
     => 5
(boundp 'abracadabra)
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.5 Defining Global Variables

You may announce your intention to use a symbol as a global variable with a variable definition: a special form, either defconst or defvar.

In Emacs Lisp, definitions serve three purposes. First, they inform people who read the code that certain symbols are intended to be used a certain way (as variables). Second, they inform the Lisp system of these things, supplying a value and documentation. Third, they provide information to utilities such as etags and make-docfile, which create data bases of the functions and variables in a program.

The difference between defconst and defvar is primarily a matter of intent, serving to inform human readers of whether the value should ever change. Emacs Lisp does not restrict the ways in which a variable can be used based on defconst or defvar declarations. However, it does make a difference for initialization: defconst unconditionally initializes the variable, while defvar initializes it only if it is void.

Special Form: defvar symbol [value [doc-string]]
This special form defines symbol as a variable and can also initialize and document it. The definition informs a person reading your code that symbol is used as a variable that might be set or changed. Note that symbol is not evaluated; the symbol to be defined must appear explicitly in the defvar.

If symbol is void and value is specified, defvar evaluates it and sets symbol to the result. But if symbol already has a value (i.e., it is not void), value is not even evaluated, and symbol's value remains unchanged. If value is omitted, the value of symbol is not changed in any case.

If symbol has a buffer-local binding in the current buffer, defvar operates on the default value, which is buffer-independent, not the current (buffer-local) binding. It sets the default value if the default value is void. See section 11.10 Buffer-Local Variables.

When you evaluate a top-level defvar form with C-M-x in Emacs Lisp mode (eval-defun), a special feature of eval-defun arranges to set the variable unconditionally, without testing whether its value is void.

If the doc-string argument appears, it specifies the documentation for the variable. (This opportunity to specify documentation is one of the main benefits of defining the variable.) The documentation is stored in the symbol's variable-documentation property. The Emacs help functions (see section 24. Documentation) look for this property.

If the variable is a user option that users would want to set interactively, you should use `*' as the first character of doc-string. This lets users set the variable conveniently using the set-variable command. Note that you should nearly always use defcustom instead of defvar to define these variables, so that users can use M-x customize and related commands to set them. See section 14. Writing Customization Definitions.

Here are some examples. This form defines foo but does not initialize it:
(defvar foo)
     => foo
This example initializes the value of bar to 23, and gives it a documentation string:
(defvar bar 23
  "The normal weight of a bar.")
     => bar
The following form changes the documentation string for bar, making it a user option, but does not change the value, since bar already has a value. (The addition (1+ nil) would get an error if it were evaluated, but since it is not evaluated, there is no error.)
(defvar bar (1+ nil)
  "*The normal weight of a bar.")
     => bar
bar
     => 23
Here is an equivalent expression for the defvar special form:
(defvar symbol value doc-string)
==
(progn
  (if (not (boundp 'symbol))
      (setq symbol value))
  (if 'doc-string
    (put 'symbol 'variable-documentation 'doc-string))
  'symbol)
The defvar form returns symbol, but it is normally used at top level in a file where its value does not matter.

Special Form: defconst symbol [value [doc-string]]
This special form defines symbol as a value and initializes it. It informs a person reading your code that symbol has a standard global value, established here, that should not be changed by the user or by other programs. Note that symbol is not evaluated; the symbol to be defined must appear explicitly in the defconst.

defconst always evaluates value, and sets the value of symbol to the result if value is given. If symbol does have a buffer-local binding in the current buffer, defconst sets the default value, not the buffer-local value. (But you should not be making buffer-local bindings for a symbol that is defined with defconst.)

Here, pi is a constant that presumably ought not to be changed by anyone (attempts by the Indiana State Legislature notwithstanding). As the second form illustrates, however, this is only advisory.
(defconst pi 3.1415 "Pi to five places.")
     => pi
(setq pi 3)
     => pi
pi
     => 3
Function: user-variable-p variable
This function returns t if variable is a user option--a variable intended to be set by the user for customization--and nil otherwise. (Variables other than user options exist for the internal purposes of Lisp programs, and users need not know about them.)

User option variables are distinguished from other variables either though being declared using defcustom (4) or by the first character of their variable-documentation property. If the property exists and is a string, and its first character is `*', then the variable is a user option.

If a user option variable has a variable-interactive property, the set-variable command uses that value to control reading the new value for the variable. The property's value is used as if it were specified in interactive (see section 21.2.1 Using interactive). However, this feature is largely obsoleted by defcustom (see section 14. Writing Customization Definitions).

Warning: If the defconst and defvar special forms are used while the variable has a local binding, they set the local binding's value; the global binding is not changed. This is not what you usually want. To prevent it, use these special forms at top level in a file, where normally no local binding is in effect, and make sure to load the file before making a local binding for the variable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.6 Tips for Defining Variables Robustly

When you define a variable whose value is a function, or a list of functions, use a name that ends in `-function' or `-functions', respectively.

There are several other variable name conventions; here is a complete list:

`...-hook'
The variable is a normal hook (see section 23.6 Hooks).

`...-function'
The value is a function.

`...-functions'
The value is a list of functions.

`...-form'
The value is a form (an expression).

`...-forms'
The value is a list of forms (expressions).

`...-predicate'
The value is a predicate--a function of one argument that returns non-nil for "good" arguments and nil for "bad" arguments.

`...-flag'
The value is significant only as to whether it is nil or not.

`...-program'
The value is a program name.

`...-command'
The value is a whole shell command.

``'-switches'
The value specifies options for a command.
When you define a variable, always consider whether you should mark it as "risky"; see 11.13 File Local Variables.

When defining and initializing a variable that holds a complicated value (such as a keymap with bindings in it), it's best to put the entire computation of the value into the defvar, like this:
(defvar my-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\C-c\C-a" 'my-command)
    ...
    map)
  docstring)
This method has several benefits. First, if the user quits while loading the file, the variable is either still uninitialized or initialized properly, never in-between. If it is still uninitialized, reloading the file will initialize it properly. Second, reloading the file once the variable is initialized will not alter it; that is important if the user has run hooks to alter part of the contents (such as, to rebind keys). Third, evaluating the defvar form with C-M-x will reinitialize the map completely.

Putting so much code in the defvar form has one disadvantage: it puts the documentation string far away from the line which names the variable. Here's a safe way to avoid that:
(defvar my-mode-map nil
  docstring)
(unless my-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\C-c\C-a" 'my-command)
    ...
    (setq my-mode-map map)))
This has all the same advantages as putting the initialization inside the defvar, except that you must type C-M-x twice, once on each form, if you do want to reinitialize the variable.

But be careful not to write the code like this:
(defvar my-mode-map nil
  docstring)
(unless my-mode-map
  (setq my-mode-map (make-sparse-keymap))
  (define-key my-mode-map "\C-c\C-a" 'my-command)
  ...)
This code sets the variable, then alters it, but it does so in more than one step. If the user quits just after the setq, that leaves the variable neither correctly initialized nor void nor nil. Once that happens, reloading the file will not initialize the variable; it will remain incomplete.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.7 Accessing Variable Values

The usual way to reference a variable is to write the symbol which names it (see section 9.2.2 Symbol Forms). This requires you to specify the variable name when you write the program. Usually that is exactly what you want to do. Occasionally you need to choose at run time which variable to reference; then you can use symbol-value.

Function: symbol-value symbol
This function returns the value of symbol. This is the value in the innermost local binding of the symbol, or its global value if it has no local bindings.
(setq abracadabra 5)
     => 5
(setq foo 9)
     => 9

;; Here the symbol abracadabra
;;   is the symbol whose value is examined.
(let ((abracadabra 'foo))
  (symbol-value 'abracadabra))
     => foo

;; Here the value of abracadabra,
;;   which is foo,
;;   is the symbol whose value is examined.
(let ((abracadabra 'foo))
  (symbol-value abracadabra))
     => 9

(symbol-value 'abracadabra)
     => 5
A void-variable error is signaled if the current binding of symbol is void.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.8 How to Alter a Variable Value

The usual way to change the value of a variable is with the special form setq. When you need to compute the choice of variable at run time, use the function set.

Special Form: setq [symbol form]...
This special form is the most common method of changing a variable's value. Each symbol is given a new value, which is the result of evaluating the corresponding form. The most-local existing binding of the symbol is changed.

setq does not evaluate symbol; it sets the symbol that you write. We say that this argument is automatically quoted. The `q' in setq stands for "quoted."

The value of the setq form is the value of the last form.
(setq x (1+ 2))
     => 3
x                   ; x now has a global value.
     => 3
(let ((x 5))
  (setq x 6)        ; The local binding of x is set.
  x)
     => 6
x                   ; The global value is unchanged.
     => 3
Note that the first form is evaluated, then the first symbol is set, then the second form is evaluated, then the second symbol is set, and so on:
(setq x 10          ; Notice that x is set before
      y (1+ x))     ;   the value of y is computed.
     => 11
Function: set symbol value
This function sets symbol's value to value, then returns value. Since set is a function, the expression written for symbol is evaluated to obtain the symbol to set.

The most-local existing binding of the variable is the binding that is set; shadowed bindings are not affected.
(set one 1)
error--> Symbol's value as variable is void: one
(set 'one 1)
     => 1
(set 'two 'one)
     => one
(set two 2)         ; two evaluates to symbol one.
     => 2
one                 ; So it is one that was set.
     => 2
(let ((one 1))      ; This binding of one is set,
  (set 'one 3)      ;   not the global value.
  one)
     => 3
one
     => 2
If symbol is not actually a symbol, a wrong-type-argument error is signaled.
(set '(x y) 'z)
error--> Wrong type argument: symbolp, (x y)
Logically speaking, set is a more fundamental primitive than setq. Any use of setq can be trivially rewritten to use set; setq could even be defined as a macro, given the availability of set. However, set itself is rarely used; beginners hardly need to know about it. It is useful only for choosing at run time which variable to set. For example, the command set-variable, which reads a variable name from the user and then sets the variable, needs to use set.

Common Lisp note: In Common Lisp, set always changes the symbol's "special" or dynamic value, ignoring any lexical bindings. In Emacs Lisp, all variables and all bindings are dynamic, so set always affects the most local existing binding.

One other function for setting a variable is designed to add an element to a list if it is not already present in the list.

Function: add-to-list symbol element
This function sets the variable symbol by consing element onto the old value, if element is not already a member of that value. It returns the resulting list, whether updated or not. The value of symbol had better be a list already before the call.

The argument symbol is not implicitly quoted; add-to-list is an ordinary function, like set and unlike setq. Quote the argument yourself if that is what you want.

Here's a scenario showing how to use add-to-list:
(setq foo '(a b))
     => (a b)

(add-to-list 'foo 'c)     ;; Add c.
     => (c a b)

(add-to-list 'foo 'b)     ;; No effect.
     => (c a b)

foo                       ;; foo was changed.
     => (c a b)
An equivalent expression for (add-to-list 'var value) is this:
(or (member value var)
    (setq var (cons value var)))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.9 Scoping Rules for Variable Bindings

A given symbol foo can have several local variable bindings, established at different places in the Lisp program, as well as a global binding. The most recently established binding takes precedence over the others.

Local bindings in Emacs Lisp have indefinite scope and dynamic extent. Scope refers to where textually in the source code the binding can be accessed. "Indefinite scope" means that any part of the program can potentially access the variable binding. Extent refers to when, as the program is executing, the binding exists. "Dynamic extent" means that the binding lasts as long as the activation of the construct that established it.

The combination of dynamic extent and indefinite scope is called dynamic scoping. By contrast, most programming languages use lexical scoping, in which references to a local variable must be located textually within the function or block that binds the variable.

Common Lisp note: Variables declared "special" in Common Lisp are dynamically scoped, like all variables in Emacs Lisp.

11.9.1 Scope

Scope means where in the program a value is visible. Comparison with other languages.

11.9.2 Extent

Extent means how long in time a value exists.

11.9.3 Implementation of Dynamic Scoping

Two ways to implement dynamic scoping.

11.9.4 Proper Use of Dynamic Scoping

How to use dynamic scoping carefully and avoid problems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.9.1 Scope

Emacs Lisp uses indefinite scope for local variable bindings. This means that any function anywhere in the program text might access a given binding of a variable. Consider the following function definitions:
(defun binder (x)   ; x is bound in binder.
   (foo 5))         ; foo is some other function.

(defun user ()      ; x is used ``free'' in user.
  (list x))
In a lexically scoped language, the binding of x in binder would never be accessible in user, because user is not textually contained within the function binder. However, in dynamically-scoped Emacs Lisp, user may or may not refer to the binding of x established in binder, depending on the circumstances:

If we call user directly without calling binder at all, then whatever binding of x is found, it cannot come from binder.

If we define foo as follows and then call binder, then the binding made in binder will be seen in user:
(defun foo (lose)
  (user))
However, if we define foo as follows and then call binder, then the binding made in binder will not be seen in user:
(defun foo (x)
  (user))
Here, when foo is called by binder, it binds x. (The binding in foo is said to shadow the one made in binder.) Therefore, user will access the x bound by foo instead of the one bound by binder.

Emacs Lisp uses dynamic scoping because simple implementations of lexical scoping are slow. In addition, every Lisp system needs to offer dynamic scoping at least as an option; if lexical scoping is the norm, there must be a way to specify dynamic scoping instead for a particular variable. It might not be a bad thing for Emacs to offer both, but implementing it with dynamic scoping only was much easier.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.9.2 Extent

Extent refers to the time during program execution that a variable name is valid. In Emacs Lisp, a variable is valid only while the form that bound it is executing. This is called dynamic extent. "Local" or "automatic" variables in most languages, including C and Pascal, have dynamic extent.

One alternative to dynamic extent is indefinite extent. This means that a variable binding can live on past the exit from the form that made the binding. Common Lisp and Scheme, for example, support this, but Emacs Lisp does not.

To illustrate this, the function below, make-add, returns a function that purports to add n to its own argument m. This would work in Common Lisp, but it does not do the job in Emacs Lisp, because after the call to make-add exits, the variable n is no longer bound to the actual argument 2.
(defun make-add (n)
    (function (lambda (m) (+ n m))))  ; Return a function.
     => make-add
(fset 'add2 (make-add 2))  ; Define function add2
                           ;   with (make-add 2).
     => (lambda (m) (+ n m))
(add2 4)                   ; Try to add 2 to 4.
error--> Symbol's value as variable is void: n
Some Lisp dialects have "closures", objects that are like functions but record additional variable bindings. Emacs Lisp does not have closures.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.9.3 Implementation of Dynamic Scoping

A simple sample implementation (which is not how Emacs Lisp actually works) may help you understand dynamic binding. This technique is called deep binding and was used in early Lisp systems.

Suppose there is a stack of bindings, which are variable-value pairs. At entry to a function or to a let form, we can push bindings onto the stack for the arguments or local variables created there. We can pop those bindings from the stack at exit from the binding construct.

We can find the value of a variable by searching the stack from top to bottom for a binding for that variable; the value from that binding is the value of the variable. To set the variable, we search for the current binding, then store the new value into that binding.

As you can see, a function's bindings remain in effect as long as it continues execution, even during its calls to other functions. That is why we say the extent of the binding is dynamic. And any other function can refer to the bindings, if it uses the same variables while the bindings are in effect. That is why we say the scope is indefinite.

The actual implementation of variable scoping in GNU Emacs Lisp uses a technique called shallow binding. Each variable has a standard place in which its current value is always found--the value cell of the symbol.

In shallow binding, setting the variable works by storing a value in the value cell. Creating a new binding works by pushing the old value (belonging to a previous binding) onto a stack, and storing the new local value in the value cell. Eliminating a binding works by popping the old value off the stack, into the value cell.

We use shallow binding because it has the same results as deep binding, but runs faster, since there is never a need to search for a binding.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.9.4 Proper Use of Dynamic Scoping

Binding a variable in one function and using it in another is a powerful technique, but if used without restraint, it can make programs hard to understand. There are two clean ways to use this technique:

Use or bind the variable only in a few related functions, written close together in one file. Such a variable is used for communication within one program.
You should write comments to inform other programmers that they can see all uses of the variable before them, and to advise them not to add uses elsewhere.

Give the variable a well-defined, documented meaning, and make all appropriate functions refer to it (but not bind it or set it) wherever that meaning is relevant. For example, the variable case-fold-search is defined as "non-nil means ignore case when searching"; various search and replace functions refer to it directly or through their subroutines, but do not bind or set it.
Then you can bind the variable in other programs, knowing reliably what the effect will be.

In either case, you should define the variable with defvar. This helps other people understand your program by telling them to look for inter-function usage. It also avoids a warning from the byte compiler. Choose the variable's name to avoid name conflicts--don't use short names like x.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.10 Buffer-Local Variables

Global and local variable bindings are found in most programming languages in one form or another. Emacs, however, also supports additional, unusual kinds of variable binding: buffer-local bindings, which apply only in one buffer, and frame-local bindings, which apply only in one frame. Having different values for a variable in different buffers and/or frames is an important customization method.

This section describes buffer-local bindings; for frame-local bindings, see the following section, 11.11 Frame-Local Variables. (A few variables have bindings that are local to each terminal; see 29.2 Multiple Displays.)

11.10.1 Introduction to Buffer-Local Variables

Introduction and concepts.

11.10.2 Creating and Deleting Buffer-Local Bindings

Creating and destroying buffer-local bindings.

11.10.3 The Default Value of a Buffer-Local Variable

The default value is seen in buffers that don't have their own buffer-local values.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.10.1 Introduction to Buffer-Local Variables

A buffer-local variable has a buffer-local binding associated with a particular buffer. The binding is in effect when that buffer is current; otherwise, it is not in effect. If you set the variable while a buffer-local binding is in effect, the new value goes in that binding, so its other bindings are unchanged. This means that the change is visible only in the buffer where you made it.

The variable's ordinary binding, which is not associated with any specific buffer, is called the default binding. In most cases, this is the global binding.

A variable can have buffer-local bindings in some buffers but not in other buffers. The default binding is shared by all the buffers that don't have their own bindings for the variable. (This includes all newly-created buffers.) If you set the variable in a buffer that does not have a buffer-local binding for it, this sets the default binding (assuming there are no frame-local bindings to complicate the matter), so the new value is visible in all the buffers that see the default binding.

The most common use of buffer-local bindings is for major modes to change variables that control the behavior of commands. For example, C mode and Lisp mode both set the variable paragraph-start to specify that only blank lines separate paragraphs. They do this by making the variable buffer-local in the buffer that is being put into C mode or Lisp mode, and then setting it to the new value for that mode. See section 23.1 Major Modes.

The usual way to make a buffer-local binding is with make-local-variable, which is what major mode commands typically use. This affects just the current buffer; all other buffers (including those yet to be created) will continue to share the default value unless they are explicitly given their own buffer-local bindings.

A more powerful operation is to mark the variable as automatically buffer-local by calling make-variable-buffer-local. You can think of this as making the variable local in all buffers, even those yet to be created. More precisely, the effect is that setting the variable automatically makes the variable local to the current buffer if it is not already so. All buffers start out by sharing the default value of the variable as usual, but setting the variable creates a buffer-local binding for the current buffer. The new value is stored in the buffer-local binding, leaving the default binding untouched. This means that the default value cannot be changed with setq in any buffer; the only way to change it is with setq-default.

Warning: When a variable has buffer-local values in one or more buffers, you can get Emacs very confused by binding the variable with let, changing to a different current buffer in which a different binding is in effect, and then exiting the let. This can scramble the values of the buffer-local and default bindings.

To preserve your sanity, avoid using a variable in that way. If you use save-excursion around each piece of code that changes to a different current buffer, you will not have this problem (see section 30.3 Excursions). Here is an example of what to avoid:
(setq foo 'b)
(set-buffer "a")
(make-local-variable 'foo)
(setq foo 'a)
(let ((foo 'temp))
  (set-buffer "b")
  body...)
foo => 'a      ; The old buffer-local value from buffer `a'
               ;   is now the default value.
(set-buffer "a")
foo => 'temp   ; The local let value that should be gone
               ;   is now the buffer-local value in buffer `a'.
But save-excursion as shown here avoids the problem:
(let ((foo 'temp))
  (save-excursion
    (set-buffer "b")
    body...))
Note that references to foo in body access the buffer-local binding of buffer `b'.

When a file specifies local variable values, these become buffer-local values when you visit the file. See section `File Variables' in The GNU Emacs Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.10.2 Creating and Deleting Buffer-Local Bindings

Command: make-local-variable variable
This function creates a buffer-local binding in the current buffer for variable (a symbol). Other buffers are not affected. The value returned is variable.

The buffer-local value of variable starts out as the same value variable previously had. If variable was void, it remains void.
;; In buffer `b1':
(setq foo 5)                ; Affects all buffers.
     => 5
(make-local-variable 'foo)  ; Now it is local in `b1'.
     => foo
foo                         ; That did not change
     => 5                   ;   the value.
(setq foo 6)                ; Change the value
     => 6                   ;   in `b1'.
foo
     => 6

;; In buffer `b2', the value hasn't changed.
(save-excursion
  (set-buffer "b2")
  foo)
     => 5
Making a variable buffer-local within a let-binding for that variable does not work reliably, unless the buffer in which you do this is not current either on entry to or exit from the let. This is because let does not distinguish between different kinds of bindings; it knows only which variable the binding was made for.

If the variable is terminal-local, this function signals an error. Such variables cannot have buffer-local bindings as well. See section 29.2 Multiple Displays.

Note: Do not use make-local-variable for a hook variable. Instead, use make-local-hook. See section 23.6 Hooks.

Command: make-variable-buffer-local variable
This function marks variable (a symbol) automatically buffer-local, so that any subsequent attempt to set it will make it local to the current buffer at the time.

A peculiar wrinkle of this feature is that binding the variable (with let or other binding constructs) does not create a buffer-local binding for it. Only setting the variable (with set or setq) does so.

The value returned is variable.

Warning: Don't assume that you should use make-variable-buffer-local for user-option variables, simply because users might want to customize them differently in different buffers. Users can make any variable local, when they wish to. It is better to leave the choice to them.

The time to use make-variable-buffer-local is when it is crucial that no two buffers ever share the same binding. For example, when a variable is used for internal purposes in a Lisp program which depends on having separate values in separate buffers, then using make-variable-buffer-local can be the best solution.

Function: local-variable-p variable &optional buffer
This returns t if variable is buffer-local in buffer buffer (which defaults to the current buffer); otherwise, nil.

Function: buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in buffer buffer. (If buffer is omitted, the current buffer is used.) It returns an association list (see section 5.8 Association Lists) in which each element contains one buffer-local variable and its value. However, when a variable's buffer-local binding in buffer is void, then the variable appears directly in the resulting list.
(make-local-variable 'foobar)
(makunbound 'foobar)
(make-local-variable 'bind-me)
(setq bind-me 69)
(setq lcl (buffer-local-variables))
    ;; First, built-in variables local in all buffers:
=> ((mark-active . nil)
    (buffer-undo-list . nil)
    (mode-name . "Fundamental")
    ...
    ;; Next, non-built-in buffer-local variables.
    ;; This one is buffer-local and void:
    foobar
    ;; This one is buffer-local and nonvoid:
    (bind-me . 69))
Note that storing new values into the CDRs of cons cells in this list does not change the buffer-local values of the variables.

Command: kill-local-variable variable
This function deletes the buffer-local binding (if any) for variable (a symbol) in the current buffer. As a result, the default binding of variable becomes visible in this buffer. This typically results in a change in the value of variable, since the default value is usually different from the buffer-local value just eliminated.

If you kill the buffer-local binding of a variable that automatically becomes buffer-local when set, this makes the default value visible in the current buffer. However, if you set the variable again, that will once again create a buffer-local binding for it.

kill-local-variable returns variable.

This function is a command because it is sometimes useful to kill one buffer-local variable interactively, just as it is useful to create buffer-local variables interactively.

Function: kill-all-local-variables
This function eliminates all the buffer-local variable bindings of the current buffer except for variables marked as "permanent". As a result, the buffer will see the default values of most variables.

This function also resets certain other information pertaining to the buffer: it sets the local keymap to nil, the syntax table to the value of (standard-syntax-table), the case table to (standard-case-table), and the abbrev table to the value of fundamental-mode-abbrev-table.

The very first thing this function does is run the normal hook change-major-mode-hook (see below).

Every major mode command begins by calling this function, which has the effect of switching to Fundamental mode and erasing most of the effects of the previous major mode. To ensure that this does its job, the variables that major modes set should not be marked permanent.

kill-all-local-variables returns nil.

Variable: change-major-mode-hook
The function kill-all-local-variables runs this normal hook before it does anything else. This gives major modes a way to arrange for something special to be done if the user switches to a different major mode. For best results, make this variable buffer-local, so that it will disappear after doing its job and will not interfere with the subsequent major mode. See section 23.6 Hooks.

A buffer-local variable is permanent if the variable name (a symbol) has a permanent-local property that is non-nil. Permanent locals are appropriate for data pertaining to where the file came from or how to save it, rather than with how to edit the contents.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.10.3 The Default Value of a Buffer-Local Variable

The global value of a variable with buffer-local bindings is also called the default value, because it is the value that is in effect whenever neither the current buffer nor the selected frame has its own binding for the variable.

The functions default-value and setq-default access and change a variable's default value regardless of whether the current buffer has a buffer-local binding. For example, you could use setq-default to change the default setting of paragraph-start for most buffers; and this would work even when you are in a C or Lisp mode buffer that has a buffer-local value for this variable.

The special forms defvar and defconst also set the default value (if they set the variable at all), rather than any buffer-local or frame-local value.

Function: default-value symbol
This function returns symbol's default value. This is the value that is seen in buffers and frames that do not have their own values for this variable. If symbol is not buffer-local, this is equivalent to symbol-value (see section 11.7 Accessing Variable Values).

Function: default-boundp symbol
The function default-boundp tells you whether symbol's default value is nonvoid. If (default-boundp 'foo) returns nil, then (default-value 'foo) would get an error.

default-boundp is to default-value as boundp is to symbol-value.

Special Form: setq-default [symbol form]...
This special form gives each symbol a new default value, which is the result of evaluating the corresponding form. It does not evaluate symbol, but does evaluate form. The value of the setq-default form is the value of the last form.

If a symbol is not buffer-local for the current buffer, and is not marked automatically buffer-local, setq-default has the same effect as setq. If symbol is buffer-local for the current buffer, then this changes the value that other buffers will see (as long as they don't have a buffer-local value), but not the value that the current buffer sees.
;; In buffer `foo':
(make-local-variable 'buffer-local)
     => buffer-local
(setq buffer-local 'value-in-foo)
     => value-in-foo
(setq-default buffer-local 'new-default)
     => new-default
buffer-local
     => value-in-foo
(default-value 'buffer-local)
     => new-default

;; In (the new) buffer `bar':
buffer-local
     => new-default
(default-value 'buffer-local)
     => new-default
(setq buffer-local 'another-default)
     => another-default
(default-value 'buffer-local)
     => another-default

;; Back in buffer `foo':
buffer-local
     => value-in-foo
(default-value 'buffer-local)
     => another-default
Function: set-default symbol value
This function is like setq-default, except that symbol is an ordinary evaluated argument.
(set-default (car '(a b c)) 23)
     => 23
(default-value 'a)
     => 23
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.11 Frame-Local Variables

Just as variables can have buffer-local bindings, they can also have frame-local bindings. These bindings belong to one frame, and are in effect when that frame is selected. Frame-local bindings are actually frame parameters: you create a frame-local binding in a specific frame by calling modify-frame-parameters and specifying the variable name as the parameter name.

To enable frame-local bindings for a certain variable, call the function make-variable-frame-local.

Command: make-variable-frame-local variable
Enable the use of frame-local bindings for variable. This does not in itself create any frame-local bindings for the variable; however, if some frame already has a value for variable as a frame parameter, that value automatically becomes a frame-local binding.

If the variable is terminal-local, this function signals an error, because such variables cannot have frame-local bindings as well. See section 29.2 Multiple Displays. A few variables that are implemented specially in Emacs can be (and usually are) buffer-local, but can never be frame-local.

Buffer-local bindings take precedence over frame-local bindings. Thus, consider a variable foo: if the current buffer has a buffer-local binding for foo, that binding is active; otherwise, if the selected frame has a frame-local binding for foo, that binding is active; otherwise, the default binding of foo is active.

Here is an example. First we prepare a few bindings for foo:
(setq f1 (selected-frame))
(make-variable-frame-local 'foo)

;; Make a buffer-local binding for foo in `b1'.
(set-buffer (get-buffer-create "b1"))
(make-local-variable 'foo)
(setq foo '(b 1))

;; Make a frame-local binding for foo in a new frame.
;; Store that frame in f2.
(setq f2 (make-frame))
(modify-frame-parameters f2 '((foo . (f 2))))
Now we examine foo in various contexts. Whenever the buffer `b1' is current, its buffer-local binding is in effect, regardless of the selected frame:
(select-frame f1)
(set-buffer (get-buffer-create "b1"))
foo
     => (b 1)

(select-frame f2)
(set-buffer (get-buffer-create "b1"))
foo
     => (b 1)
Otherwise, the frame gets a chance to provide the binding; when frame f2 is selected, its frame-local binding is in effect:
(select-frame f2)
(set-buffer (get-buffer "*scratch*"))
foo
     => (f 2)
When neither the current buffer nor the selected frame provides a binding, the default binding is used:
(select-frame f1)
(set-buffer (get-buffer "*scratch*"))
foo
     => nil
When the active binding of a variable is a frame-local binding, setting the variable changes that binding. You can observe the result with frame-parameters:
(select-frame f2)
(set-buffer (get-buffer "*scratch*"))
(setq foo 'nobody)
(assq 'foo (frame-parameters f2))
     => (foo . nobody)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.12 Possible Future Local Variables

We have considered the idea of bindings that are local to a category of frames--for example, all color frames, or all frames with dark backgrounds. We have not implemented them because it is not clear that this feature is really useful. You can get more or less the same results by adding a function to after-make-frame-functions, set up to define a particular frame parameter according to the appropriate conditions for each frame.

It would also be possible to implement window-local bindings. We don't know of many situations where they would be useful, and it seems that indirect buffers (see section 27.11 Indirect Buffers) with buffer-local bindings offer a way to handle these situations more robustly.

If sufficient application is found for either of these two kinds of local bindings, we will provide it in a subsequent Emacs version.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

11.13 File Local Variables

This section describes the functions and variables that affect processing of local variables lists in files.

User Option: enable-local-variables
This variable controls whether to process file local variables lists. A value of t means process the local variables lists unconditionally; nil means ignore them; anything else means ask the user what to do for each file. The default value is t.

Function: hack-local-variables &optional force
This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer. The variable enable-local-variables has its effect here.

The argument force usually comes from the argument find-file given to normal-mode.

If a file local variable list could specify the a function that will be called later, or an expression that will be executed later, simply visiting a file could take over your Emacs. To prevent this, Emacs takes care not to allow local variable lists to set such variables.

For one thing, any variable whose name ends in `-function', `-functions', `-hook', `-hooks', `-form', `-forms', `-program', `-command' or `-predicate' cannot be set in a local variable list. In general, you should use such a name whenever it is appropriate for the variable's meaning.

In addition, any variable whose name has a non-nil risky-local-variable property is also ignored. So are all variables listed in ignored-local-variables:

Variable: ignored-local-variables
This variable holds a list of variables that should not be set by a file's local variables list. Any value specified for one of these variables is ignored.

The `Eval:' "variable" is also a potential loophole, so Emacs normally asks for confirmation before handling it.

User Option: enable-local-eval
This variable controls processing of `Eval:' in local variables lists in files being visited. A value of t means process them unconditionally; nil means ignore them; anything else means ask the user what to do for each file. The default value is maybe.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12. Functions

A Lisp program is composed mainly of Lisp functions. This chapter explains what functions are, how they accept arguments, and how to define them.

12.1 What Is a Function?

Lisp functions vs. primitives; terminology.

12.2 Lambda Expressions

How functions are expressed as Lisp objects.

12.3 Naming a Function

A symbol can serve as the name of a function.

12.4 Defining Functions

Lisp expressions for defining functions.

12.5 Calling Functions

How to use an existing function.

12.6 Mapping Functions

Applying a function to each element of a list, etc.

12.7 Anonymous Functions

Lambda expressions are functions with no names.

12.8 Accessing Function Cell Contents

Accessing or setting the function definition of a symbol.

12.9 Inline Functions

Defining functions that the compiler will open code.

12.10 Other Topics Related to Functions

Cross-references to specific Lisp primitives that have a special bearing on how functions work.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.1 What Is a Function?

In a general sense, a function is a rule for carrying on a computation given several values called arguments. The result of the computation is called the value of the function. The computation can also have side effects: lasting changes in the values of variables or the contents of data structures.

Here are important terms for functions in Emacs Lisp and for other function-like objects.

function
In Emacs Lisp, a function is anything that can be applied to arguments in a Lisp program. In some cases, we use it more specifically to mean a function written in Lisp. Special forms and macros are not functions.

primitive
A primitive is a function callable from Lisp that is written in C, such as car or append. These functions are also called built-in functions or subrs. (Special forms are also considered primitives.)
Usually the reason we implement a function as a primitive is either because it is fundamental, because it provides a low-level interface to operating system services, or because it needs to run fast. Primitives can be modified or added only by changing the C sources and recompiling the editor. See E.5 Writing Emacs Primitives.

lambda expression
A lambda expression is a function written in Lisp. These are described in the following section. See section 12.2 Lambda Expressions.

special form
A special form is a primitive that is like a function but does not evaluate all of its arguments in the usual way. It may evaluate only some of the arguments, or may evaluate them in an unusual order, or several times. Many special forms are described in 10. Control Structures.

macro
A macro is a construct defined in Lisp by the programmer. It differs from a function in that it translates a Lisp expression that you write into an equivalent expression to be evaluated instead of the original expression. Macros enable Lisp programmers to do the sorts of things that special forms can do. See section 13. Macros, for how to define and use macros.

command
A command is an object that command-execute can invoke; it is a possible definition for a key sequence. Some functions are commands; a function written in Lisp is a command if it contains an interactive declaration (see section 21.2 Defining Commands). Such a function can be called from Lisp expressions like other functions; in this case, the fact that the function is a command makes no difference.
Keyboard macros (strings and vectors) are commands also, even though they are not functions. A symbol is a command if its function definition is a command; such symbols can be invoked with M-x. The symbol is a function as well if the definition is a function. See section 21.1 Command Loop Overview.

keystroke command
A keystroke command is a command that is bound to a key sequence (typically one to three keystrokes). The distinction is made here merely to avoid confusion with the meaning of "command" in non-Emacs editors; for Lisp programs, the distinction is normally unimportant.

byte-code function
A byte-code function is a function that has been compiled by the byte compiler. See section 2.3.16 Byte-Code Function Type.

Function: functionp object
This function returns t if object is any kind of function, or a special form or macro.

Function: subrp object
This function returns t if object is a built-in function (i.e., a Lisp primitive).
(subrp 'message)            ; message is a symbol,
     => nil                 ;   not a subr object.
(subrp (symbol-function 'message))
     => t
Function: byte-code-function-p object
This function returns t if object is a byte-code function. For example:
(byte-code-function-p (symbol-function 'next-line))
     => t
Function: subr-arity subr
This function provides information about the argument list of a primitive, subr. The returned value is a pair (min . max). min is the minimum number of args. max is the maximum number or the symbol many, for a function with &rest arguments, or the symbol unevalled if subr is a special form.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.2 Lambda Expressions

A function written in Lisp is a list that looks like this:
(lambda (arg-variables...)
  [documentation-string]
  [interactive-declaration]
  body-forms...)
Such a list is called a lambda expression. In Emacs Lisp, it actually is valid as an expression--it evaluates to itself. In some other Lisp dialects, a lambda expression is not a valid expression at all. In either case, its main use is not to be evaluated as an expression, but to be called as a function.

12.2.1 Components of a Lambda Expression

The parts of a lambda expression.

12.2.2 A Simple Lambda-Expression Example

A simple example.

12.2.3 Other Features of Argument Lists

Details and special features of argument lists.

12.2.4 Documentation Strings of Functions

How to put documentation in a function.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.2.1 Components of a Lambda Expression

A function written in Lisp (a "lambda expression") is a list that looks like this:
(lambda (arg-variables...)
  [documentation-string]
  [interactive-declaration]
  body-forms...)
The first element of a lambda expression is always the symbol lambda. This indicates that the list represents a function. The reason functions are defined to start with lambda is so that other lists, intended for other uses, will not accidentally be valid as functions.

The second element is a list of symbols--the argument variable names. This is called the lambda list. When a Lisp function is called, the argument values are matched up against the variables in the lambda list, which are given local bindings with the values provided. See section 11.3 Local Variables.

The documentation string is a Lisp string object placed within the function definition to describe the function for the Emacs help facilities. See section 12.2.4 Documentation Strings of Functions.

The interactive declaration is a list of the form (interactive code-string). This declares how to provide arguments if the function is used interactively. Functions with this declaration are called commands; they can be called using M-x or bound to a key. Functions not intended to be called in this way should not have interactive declarations. See section 21.2 Defining Commands, for how to write an interactive declaration.

The rest of the elements are the body of the function: the Lisp code to do the work of the function (or, as a Lisp programmer would say, "a list of Lisp forms to evaluate"). The value returned by the function is the value returned by the last element of the body.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.2.2 A Simple Lambda-Expression Example

Consider for example the following function:
(lambda (a b c) (+ a b c))
We can call this function by writing it as the CAR of an expression, like this:
((lambda (a b c) (+ a b c))
 1 2 3)
This call evaluates the body of the lambda expression with the variable a bound to 1, b bound to 2, and c bound to 3. Evaluation of the body adds these three numbers, producing the result 6; therefore, this call to the function returns the value 6.

Note that the arguments can be the results of other function calls, as in this example:
((lambda (a b c) (+ a b c))
 1 (* 2 3) (- 5 4))
This evaluates the arguments 1, (* 2 3), and (- 5 4) from left to right. Then it applies the lambda expression to the argument values 1, 6 and 1 to produce the value 8.

It is not often useful to write a lambda expression as the CAR of a form in this way. You can get the same result, of making local variables and giving them values, using the special form let (see section 11.3 Local Variables). And let is clearer and easier to use. In practice, lambda expressions are either stored as the function definitions of symbols, to produce named functions, or passed as arguments to other functions (see section 12.7 Anonymous Functions).

However, calls to explicit lambda expressions were very useful in the old days of Lisp, before the special form let was invented. At that time, they were the only way to bind and initialize local variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.2.3 Other Features of Argument Lists

Our simple sample function, (lambda (a b c) (+ a b c)), specifies three argument variables, so it must be called with three arguments: if you try to call it with only two arguments or four arguments, you get a wrong-number-of-arguments error.

It is often convenient to write a function that allows certain arguments to be omitted. For example, the function substring accepts three arguments--a string, the start index and the end index--but the third argument defaults to the length of the string if you omit it. It is also convenient for certain functions to accept an indefinite number of arguments, as the functions list and + do.

To specify optional arguments that may be omitted when a function is called, simply include the keyword &optional before the optional arguments. To specify a list of zero or more extra arguments, include the keyword &rest before one final argument.

Thus, the complete syntax for an argument list is as follows:
(required-vars...
 [&optional optional-vars...]
 [&rest rest-var])
The square brackets indicate that the &optional and &rest clauses, and the variables that follow them, are optional.

A call to the function requires one actual argument for each of the required-vars. There may be actual arguments for zero or more of the optional-vars, and there cannot be any actual arguments beyond that unless the lambda list uses &rest. In that case, there may be any number of extra actual arguments.

If actual arguments for the optional and rest variables are omitted, then they always default to nil. There is no way for the function to distinguish between an explicit argument of nil and an omitted argument. However, the body of the function is free to consider nil an abbreviation for some other meaningful value. This is what substring does; nil as the third argument to substring means to use the length of the string supplied.

Common Lisp note: Common Lisp allows the function to specify what default value to use when an optional argument is omitted; Emacs Lisp always uses nil. Emacs Lisp does not support "supplied-p" variables that tell you whether an argument was explicitly passed.

For example, an argument list that looks like this:
(a b &optional c d &rest e)
binds a and b to the first two actual arguments, which are required. If one or two more arguments are provided, c and d are bound to them respectively; any arguments after the first four are collected into a list and e is bound to that list. If there are only two arguments, c is nil; if two or three arguments, d is nil; if four arguments or fewer, e is nil.

There is no way to have required arguments following optional ones--it would not make sense. To see why this must be so, suppose that c in the example were optional and d were required. Suppose three actual arguments are given; which variable would the third argument be for? Would it be used for the c, or for d? One can argue for both possibilities. Similarly, it makes no sense to have any more arguments (either required or optional) after a &rest argument.

Here are some examples of argument lists and proper calls:
((lambda (n) (1+ n))                ; One required:
 1)                                 ; requires exactly one argument.
     => 2
((lambda (n &optional n1)           ; One required and one optional:
         (if n1 (+ n n1) (1+ n)))   ; 1 or 2 arguments.
 1 2)
     => 3
((lambda (n &rest ns)               ; One required and one rest:
         (+ n (apply '+ ns)))       ; 1 or more arguments.
 1 2 3 4 5)
     => 15
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.2.4 Documentation Strings of Functions

A lambda expression may optionally have a documentation string just after the lambda list. This string does not affect execution of the function; it is a kind of comment, but a systematized comment which actually appears inside the Lisp world and can be used by the Emacs help facilities. See section 24. Documentation, for how the documentation-string is accessed.

It is a good idea to provide documentation strings for all the functions in your program, even those that are called only from within your program. Documentation strings are like comments, except that they are easier to access.

The first line of the documentation string should stand on its own, because apropos displays just this first line. It should consist of one or two complete sentences that summarize the function's purpose.

The start of the documentation string is usually indented in the source file, but since these spaces come before the starting double-quote, they are not part of the string. Some people make a practice of indenting any additional lines of the string so that the text lines up in the program source. This is a mistake. The indentation of the following lines is inside the string; what looks nice in the source code will look ugly when displayed by the help commands.

You may wonder how the documentation string could be optional, since there are required components of the function that follow it (the body). Since evaluation of a string returns that string, without any side effects, it has no effect if it is not the last form in the body. Thus, in practice, there is no confusion between the first form of the body and the documentation string; if the only body form is a string then it serves both as the return value and as the documentation.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.3 Naming a Function

In most computer languages, every function has a name; the idea of a function without a name is nonsensical. In Lisp, a function in the strictest sense has no name. It is simply a list whose first element is lambda, a byte-code function object, or a primitive subr-object.

However, a symbol can serve as the name of a function. This happens when you put the function in the symbol's function cell (see section 8.1 Symbol Components). Then the symbol itself becomes a valid, callable function, equivalent to the list or subr-object that its function cell refers to. The contents of the function cell are also called the symbol's function definition. The procedure of using a symbol's function definition in place of the symbol is called symbol function indirection; see 9.2.4 Symbol Function Indirection.

In practice, nearly all functions are given names in this way and referred to through their names. For example, the symbol car works as a function and does what it does because the primitive subr-object #<subr car> is stored in its function cell.

We give functions names because it is convenient to refer to them by their names in Lisp expressions. For primitive subr-objects such as #<subr car>, names are the only way you can refer to them: there is no read syntax for such objects. For functions written in Lisp, the name is more convenient to use in a call than an explicit lambda expression. Also, a function with a name can refer to itself--it can be recursive. Writing the function's name in its own definition is much more convenient than making the function definition point to itself (something that is not impossible but that has various disadvantages in practice).

We often identify functions with the symbols used to name them. For example, we often speak of "the function car", not distinguishing between the symbol car and the primitive subr-object that is its function definition. For most purposes, there is no need to distinguish.

Even so, keep in mind that a function need not have a unique name. While a given function object usually appears in the function cell of only one symbol, this is just a matter of convenience. It is easy to store it in several symbols using fset; then each of the symbols is equally well a name for the same function.

A symbol used as a function name may also be used as a variable; these two uses of a symbol are independent and do not conflict. (Some Lisp dialects, such as Scheme, do not distinguish between a symbol's value and its function definition; a symbol's value as a variable is also its function definition.) If you have not given a symbol a function definition, you cannot use it as a function; whether the symbol has a value as a variable makes no difference to this.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.4 Defining Functions

We usually give a name to a function when it is first created. This is called defining a function, and it is done with the defun special form.

Special Form: defun name argument-list body-forms
defun is the usual way to define new Lisp functions. It defines the symbol name as a function that looks like this:
(lambda argument-list . body-forms)
defun stores this lambda expression in the function cell of name. It returns the value name, but usually we ignore this value.

As described previously (see section 12.2 Lambda Expressions), argument-list is a list of argument names and may include the keywords &optional and &rest. Also, the first two of the body-forms may be a documentation string and an interactive declaration.

There is no conflict if the same symbol name is also used as a variable, since the symbol's value cell is independent of the function cell. See section 8.1 Symbol Components.

Here are some examples:
(defun foo () 5)
     => foo
(foo)
     => 5

(defun bar (a &optional b &rest c)
    (list a b c))
     => bar
(bar 1 2 3 4 5)
     => (1 2 (3 4 5))
(bar 1)
     => (1 nil nil)
(bar)
error--> Wrong number of arguments.

(defun capitalize-backwards ()
  "Upcase the last letter of a word."
  (interactive)
  (backward-word 1)
  (forward-word 1)
  (backward-char 1)
  (capitalize-word 1))
     => capitalize-backwards
Be careful not to redefine existing functions unintentionally. defun redefines even primitive functions such as car without any hesitation or notification. Redefining a function already defined is often done deliberately, and there is no way to distinguish deliberate redefinition from unintentional redefinition.

Function: defalias name definition
This special form defines the symbol name as a function, with definition definition (which can be any valid Lisp function).

The proper place to use defalias is where a specific function name is being defined--especially where that name appears explicitly in the source file being loaded. This is because defalias records which file defined the function, just like defun (see section 15.7 Unloading).

By contrast, in programs that manipulate function definitions for other purposes, it is better to use fset, which does not keep such records.

See also defsubst, which defines a function like defun and tells the Lisp compiler to open-code it. See section 12.9 Inline Functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.5 Calling Functions

Defining functions is only half the battle. Functions don't do anything until you call them, i.e., tell them to run. Calling a function is also known as invocation.

The most common way of invoking a function is by evaluating a list. For example, evaluating the list (concat "a" "b") calls the function concat with arguments "a" and "b". See section 9. Evaluation, for a description of evaluation.

When you write a list as an expression in your program, the function name it calls is written in your program. This means that you choose which function to call, and how many arguments to give it, when you write the program. Usually that's just what you want. Occasionally you need to compute at run time which function to call. To do that, use the function funcall. When you also need to determine at run time how many arguments to pass, use apply.

Function: funcall function &rest arguments
funcall calls function with arguments, and returns whatever function returns.

Since funcall is a function, all of its arguments, including function, are evaluated before funcall is called. This means that you can use any expression to obtain the function to be called. It also means that funcall does not see the expressions you write for the arguments, only their values. These values are not evaluated a second time in the act of calling function; funcall enters the normal procedure for calling a function at the place where the arguments have already been evaluated.

The argument function must be either a Lisp function or a primitive function. Special forms and macros are not allowed, because they make sense only when given the "unevaluated" argument expressions. funcall cannot provide these because, as we saw above, it never knows them in the first place.
(setq f 'list)
     => list
(funcall f 'x 'y 'z)
     => (x y z)
(funcall f 'x 'y '(z))
     => (x y (z))
(funcall 'and t nil)
error--> Invalid function: #<subr and>
Compare these examples with the examples of apply.

Function: apply function &rest arguments
apply calls function with arguments, just like funcall but with one difference: the last of arguments is a list of objects, which are passed to function as separate arguments, rather than a single list. We say that apply spreads this list so that each individual element becomes an argument.

apply returns the result of calling function. As with funcall, function must either be a Lisp function or a primitive function; special forms and macros do not make sense in apply.
(setq f 'list)
     => list
(apply f 'x 'y 'z)
error--> Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     => 10
(apply '+ '(1 2 3 4))
     => 10

(apply 'append '((a b c) nil (x y z) nil))
     => (a b c x y z)
For an interesting example of using apply, see the description of mapcar, in 12.6 Mapping Functions.

It is common for Lisp functions to accept functions as arguments or find them in data structures (especially in hook variables and property lists) and call them using funcall or apply. Functions that accept function arguments are often called functionals.

Sometimes, when you call a functional, it is useful to supply a no-op function as the argument. Here are two different kinds of no-op function:

Function: identity arg
This function returns arg and has no side effects.

Function: ignore &rest args
This function ignores any arguments and returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.6 Mapping Functions

A mapping function applies a given function to each element of a list or other collection. Emacs Lisp has several such functions; mapcar and mapconcat, which scan a list, are described here. See section 8.3 Creating and Interning Symbols, for the function mapatoms which maps over the symbols in an obarray. See section 7.2 Hash Table Access, for the function maphash which maps over key/value associations in a hash table.

These mapping functions do not allow char-tables because a char-table is a sparse array whose nominal range of indices is very large. To map over a char-table in a way that deals properly with its sparse nature, use the function map-char-table (see section 6.6 Char-Tables).

Function: mapcar function sequence
mapcar applies function to each element of sequence in turn, and returns a list of the results.

The argument sequence can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string. The result is always a list. The length of the result is the same as the length of sequence.
For example:

(mapcar 'car '((a b) (c d) (e f)))
     => (a c e)
(mapcar '1+ [1 2 3])
     => (2 3 4)
(mapcar 'char-to-string "abc")
     => ("a" "b" "c")

;; Call each function in my-hooks.
(mapcar 'funcall my-hooks)

(defun mapcar* (function &rest args)
  "Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
  ;; If no list is exhausted,
  (if (not (memq 'nil args))
      ;; apply function to CARs.
      (cons (apply function (mapcar 'car args))
            (apply 'mapcar* function
                   ;; Recurse for rest of elements.
                   (mapcar 'cdr args)))))

(mapcar* 'cons '(a b c) '(1 2 3 4))
     => ((a . 1) (b . 2) (c . 3))
Function: mapc function sequence
mapc is like mapcar except that function is used for side-effects only--the values it returns are ignored, not collected into a list. mapc always returns sequence.

Function: mapconcat function sequence separator
mapconcat applies function to each element of sequence: the results, which must be strings, are concatenated. Between each pair of result strings, mapconcat inserts the string separator. Usually separator contains a space or comma or other suitable punctuation.

The argument function must be a function that can take one argument and return a string. The argument sequence can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string.
(mapconcat 'symbol-name
           '(The cat in the hat)
           " ")
     => "The cat in the hat"

(mapconcat (function (lambda (x) (format "%c" (1+ x))))
           "HAL-8000"
           "")
     => "IBM.9111"
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.7 Anonymous Functions

In Lisp, a function is a list that starts with lambda, a byte-code function compiled from such a list, or alternatively a primitive subr-object; names are "extra". Although usually functions are defined with defun and given names at the same time, it is occasionally more concise to use an explicit lambda expression--an anonymous function. Such a list is valid wherever a function name is.

Any method of creating such a list makes a valid function. Even this:
(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
=> (lambda (x) (+ 12 x))
This computes a list that looks like (lambda (x) (+ 12 x)) and makes it the value (not the function definition!) of silly.

Here is how we might call this function:
(funcall silly 1)
=> 13
(It does not work to write (silly 1), because this function is not the function definition of silly. We have not given silly any function definition, just a value as a variable.)

Most of the time, anonymous functions are constants that appear in your program. For example, you might want to pass one as an argument to the function mapcar, which applies any given function to each element of a list.

Here we define a function change-property which uses a function as its third argument:
(defun change-property (symbol prop function)
  (let ((value (get symbol prop)))
    (put symbol prop (funcall function value))))
Here we define a function that uses change-property, passing it a function to double a number:
(defun double-property (symbol prop)
  (change-property symbol prop '(lambda (x) (* 2 x))))
In such cases, we usually use the special form function instead of simple quotation to quote the anonymous function, like this:
(defun double-property (symbol prop)
  (change-property symbol prop
                   (function (lambda (x) (* 2 x)))))
Using function instead of quote makes a difference if you compile the function double-property. For example, if you compile the second definition of double-property, the anonymous function is compiled as well. By contrast, if you compile the first definition which uses ordinary quote, the argument passed to change-property is the precise list shown:
(lambda (x) (* x 2))
The Lisp compiler cannot assume this list is a function, even though it looks like one, since it does not know what change-property will do with the list. Perhaps it will check whether the CAR of the third element is the symbol *! Using function tells the compiler it is safe to go ahead and compile the constant function.

Nowadays it is possible to omit function entirely, like this:
(defun double-property (symbol prop)
  (change-property symbol prop (lambda (x) (* 2 x))))
This is because lambda itself implies function.

We sometimes write function instead of quote when quoting the name of a function, but this usage is just a sort of comment:
(function symbol) == (quote symbol) == 'symbol
The read syntax #' is a short-hand for using function. For example,
#'(lambda (x) (* x x))
is equivalent to
(function (lambda (x) (* x x)))
Special Form: function function-object
This special form returns function-object without evaluating it. In this, it is equivalent to quote. However, it serves as a note to the Emacs Lisp compiler that function-object is intended to be used only as a function, and therefore can safely be compiled. Contrast this with quote, in 9.3 Quoting.

See documentation in 24.2 Access to Documentation Strings, for a realistic example using function and an anonymous function.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.8 Accessing Function Cell Contents

The function definition of a symbol is the object stored in the function cell of the symbol. The functions described here access, test, and set the function cell of symbols.

See also the function indirect-function in 9.2.4 Symbol Function Indirection.

Function: symbol-function symbol
This returns the object in the function cell of symbol. If the symbol's function cell is void, a void-function error is signaled.

This function does not check that the returned object is a legitimate function.
(defun bar (n) (+ n 2))
     => bar
(symbol-function 'bar)
     => (lambda (n) (+ n 2))
(fset 'baz 'bar)
     => bar
(symbol-function 'baz)
     => bar
If you have never given a symbol any function definition, we say that that symbol's function cell is void. In other words, the function cell does not have any Lisp object in it. If you try to call such a symbol as a function, it signals a void-function error.

Note that void is not the same as nil or the symbol void. The symbols nil and void are Lisp objects, and can be stored into a function cell just as any other object can be (and they can be valid functions if you define them in turn with defun). A void function cell contains no object whatsoever.

You can test the voidness of a symbol's function definition with fboundp. After you have given a symbol a function definition, you can make it void once more using fmakunbound.

Function: fboundp symbol
This function returns t if the symbol has an object in its function cell, nil otherwise. It does not check that the object is a legitimate function.

Function: fmakunbound symbol
This function makes symbol's function cell void, so that a subsequent attempt to access this cell will cause a void-function error. (See also makunbound, in 11.4 When a Variable is "Void".)
(defun foo (x) x)
     => foo
(foo 1)
     =>1
(fmakunbound 'foo)
     => foo
(foo 1)
error--> Symbol's function definition is void: foo
Function: fset symbol definition
This function stores definition in the function cell of symbol. The result is definition. Normally definition should be a function or the name of a function, but this is not checked. The argument symbol is an ordinary evaluated argument.

There are three normal uses of this function:

Copying one symbol's function definition to another--in other words, making an alternate name for a function. (If you think of this as the definition of the new name, you should use defalias instead of fset; see 12.4 Defining Functions.)

Giving a symbol a function definition that is not a list and therefore cannot be made with defun. For example, you can use fset to give a symbol s1 a function definition which is another symbol s2; then s1 serves as an alias for whatever definition s2 presently has. (Once again use defalias instead of fset if you think of this as the definition of s1.)

In constructs for defining or altering functions. If defun were not a primitive, it could be written in Lisp (as a macro) using fset.

Here are examples of these uses:
;; Save foo's definition in old-foo.
(fset 'old-foo (symbol-function 'foo))

;; Make the symbol car the function definition of xfirst.
;; (Most likely, defalias would be better than fset here.)
(fset 'xfirst 'car)
     => car
(xfirst '(1 2 3))
     => 1
(symbol-function 'xfirst)
     => car
(symbol-function (symbol-function 'xfirst))
     => #<subr car>

;; Define a named keyboard macro.
(fset 'kill-two-lines "\^u2\^k")
     => "\^u2\^k"

;; Here is a function that alters other functions.
(defun copy-function-definition (new old)
  "Define NEW with the same function definition as OLD."
  (fset new (symbol-function old)))
When writing a function that extends a previously defined function, the following idiom is sometimes used:
(fset 'old-foo (symbol-function 'foo))
(defun foo ()
  "Just like old-foo, except more so."
  (old-foo)
  (more-so))
This does not work properly if foo has been defined to autoload. In such a case, when foo calls old-foo, Lisp attempts to define old-foo by loading a file. Since this presumably defines foo rather than old-foo, it does not produce the proper results. The only way to avoid this problem is to make sure the file is loaded before moving aside the old definition of foo.

But it is unmodular and unclean, in any case, for a Lisp file to redefine a function defined elsewhere. It is cleaner to use the advice facility (see section 17. Advising Emacs Lisp Functions).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.9 Inline Functions

You can define an inline function by using defsubst instead of defun. An inline function works just like an ordinary function except for one thing: when you compile a call to the function, the function's definition is open-coded into the caller.

Making a function inline makes explicit calls run faster. But it also has disadvantages. For one thing, it reduces flexibility; if you change the definition of the function, calls already inlined still use the old definition until you recompile them. Since the flexibility of redefining functions is an important feature of Emacs, you should not make a function inline unless its speed is really crucial.

Another disadvantage is that making a large function inline can increase the size of compiled code both in files and in memory. Since the speed advantage of inline functions is greatest for small functions, you generally should not make large functions inline.

It's possible to define a macro to expand into the same code that an inline function would execute. (See section 13. Macros.) But the macro would be limited to direct use in expressions--a macro cannot be called with apply, mapcar and so on. Also, it takes some work to convert an ordinary function into a macro. To convert it into an inline function is very easy; simply replace defun with defsubst. Since each argument of an inline function is evaluated exactly once, you needn't worry about how many times the body uses the arguments, as you do for macros. (See section 13.6.2 Evaluating Macro Arguments Repeatedly.)

Inline functions can be used and open-coded later on in the same file, following the definition, just like macros.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

12.10 Other Topics Related to Functions

Here is a table of several functions that do things related to function calling and function definitions. They are documented elsewhere, but we provide cross references here.

apply
See 12.5 Calling Functions.

autoload
See 15.4 Autoload.

call-interactively
See 21.3 Interactive Call.

commandp
See 21.3 Interactive Call.

documentation
See 24.2 Access to Documentation Strings.

eval
See 9.4 Eval.

funcall
See 12.5 Calling Functions.

function
See 12.7 Anonymous Functions.

ignore
See 12.5 Calling Functions.

indirect-function
See 9.2.4 Symbol Function Indirection.

interactive
See 21.2.1 Using interactive.

interactive-p
See 21.3 Interactive Call.

mapatoms
See 8.3 Creating and Interning Symbols.

mapcar
See 12.6 Mapping Functions.

map-char-table
See 6.6 Char-Tables.

mapconcat
See 12.6 Mapping Functions.

undefined
See 22.7 Key Lookup.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13. Macros

Macros enable you to define new control constructs and other language features. A macro is defined much like a function, but instead of telling how to compute a value, it tells how to compute another Lisp expression which will in turn compute the value. We call this expression the expansion of the macro.

Macros can do this because they operate on the unevaluated expressions for the arguments, not on the argument values as functions do. They can therefore construct an expansion containing these argument expressions or parts of them.

If you are using a macro to do something an ordinary function could do, just for the sake of speed, consider using an inline function instead. See section 12.9 Inline Functions.

13.1 A Simple Example of a Macro

A basic example.

13.2 Expansion of a Macro Call

How, when and why macros are expanded.

13.3 Macros and Byte Compilation

How macros are expanded by the compiler.

13.4 Defining Macros

How to write a macro definition.

13.5 Backquote

Easier construction of list structure.

13.6 Common Problems Using Macros

Don't evaluate the macro arguments too many times. Don't hide the user's variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.1 A Simple Example of a Macro

Suppose we would like to define a Lisp construct to increment a variable value, much like the ++ operator in C. We would like to write (inc x) and have the effect of (setq x (1+ x)). Here's a macro definition that does the job:
(defmacro inc (var)
   (list 'setq var (list '1+ var)))
When this is called with (inc x), the argument var is the symbol x---not the value of x, as it would be in a function. The body of the macro uses this to construct the expansion, which is (setq x (1+ x)). Once the macro definition returns this expansion, Lisp proceeds to evaluate it, thus incrementing x.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.2 Expansion of a Macro Call

A macro call looks just like a function call in that it is a list which starts with the name of the macro. The rest of the elements of the list are the arguments of the macro.

Evaluation of the macro call begins like evaluation of a function call except for one crucial difference: the macro arguments are the actual expressions appearing in the macro call. They are not evaluated before they are given to the macro definition. By contrast, the arguments of a function are results of evaluating the elements of the function call list.

Having obtained the arguments, Lisp invokes the macro definition just as a function is invoked. The argument variables of the macro are bound to the argument values from the macro call, or to a list of them in the case of a &rest argument. And the macro body executes and returns its value just as a function body does.

The second crucial difference between macros and functions is that the value returned by the macro body is not the value of the macro call. Instead, it is an alternate expression for computing that value, also known as the expansion of the macro. The Lisp interpreter proceeds to evaluate the expansion as soon as it comes back from the macro.

Since the expansion is evaluated in the normal manner, it may contain calls to other macros. It may even be a call to the same macro, though this is unusual.

You can see the expansion of a given macro call by calling macroexpand.

Function: macroexpand form &optional environment
This function expands form, if it is a macro call. If the result is another macro call, it is expanded in turn, until something which is not a macro call results. That is the value returned by macroexpand. If form is not a macro call to begin with, it is returned as given.

Note that macroexpand does not look at the subexpressions of form (although some macro definitions may do so). Even if they are macro calls themselves, macroexpand does not expand them.

The function macroexpand does not expand calls to inline functions. Normally there is no need for that, since a call to an inline function is no harder to understand than a call to an ordinary function.

If environment is provided, it specifies an alist of macro definitions that shadow the currently defined macros. Byte compilation uses this feature.
(defmacro inc (var)
    (list 'setq var (list '1+ var)))
     => inc

(macroexpand '(inc r))
     => (setq r (1+ r))

(defmacro inc2 (var1 var2)
    (list 'progn (list 'inc var1) (list 'inc var2)))
     => inc2

(macroexpand '(inc2 r s))
     => (progn (inc r) (inc s))  ; inc not expanded here.
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.3 Macros and Byte Compilation

You might ask why we take the trouble to compute an expansion for a macro and then evaluate the expansion. Why not have the macro body produce the desired results directly? The reason has to do with compilation.

When a macro call appears in a Lisp program being compiled, the Lisp compiler calls the macro definition just as the interpreter would, and receives an expansion. But instead of evaluating this expansion, it compiles the expansion as if it had appeared directly in the program. As a result, the compiled code produces the value and side effects intended for the macro, but executes at full compiled speed. This would not work if the macro body computed the value and side effects itself--they would be computed at compile time, which is not useful.

In order for compilation of macro calls to work, the macros must already be defined in Lisp when the calls to them are compiled. The compiler has a special feature to help you do this: if a file being compiled contains a defmacro form, the macro is defined temporarily for the rest of the compilation of that file. To make this feature work, you must put the defmacro in the same file where it is used, and before its first use.

Byte-compiling a file executes any require calls at top-level in the file. This is in case the file needs the required packages for proper compilation. One way to ensure that necessary macro definitions are available during compilation is to require the files that define them (see section 15.6 Features). To avoid loading the macro definition files when someone runs the compiled program, write eval-when-compile around the require calls (see section 16.5 Evaluation During Compilation).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.4 Defining Macros

A Lisp macro is a list whose CAR is macro. Its CDR should be a function; expansion of the macro works by applying the function (with apply) to the list of unevaluated argument-expressions from the macro call.

It is possible to use an anonymous Lisp macro just like an anonymous function, but this is never done, because it does not make sense to pass an anonymous macro to functionals such as mapcar. In practice, all Lisp macros have names, and they are usually defined with the special form defmacro.

Special Form: defmacro name argument-list body-forms...
defmacro defines the symbol name as a macro that looks like this:
(macro lambda argument-list . body-forms)
(Note that the CDR of this list is a function--a lambda expression.) This macro object is stored in the function cell of name. The value returned by evaluating the defmacro form is name, but usually we ignore this value.

The shape and meaning of argument-list is the same as in a function, and the keywords &rest and &optional may be used (see section 12.2.3 Other Features of Argument Lists). Macros may have a documentation string, but any interactive declaration is ignored since macros cannot be called interactively.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.5 Backquote

Macros often need to construct large list structures from a mixture of constants and nonconstant parts. To make this easier, use the ``' syntax (usually called backquote).

Backquote allows you to quote a list, but selectively evaluate elements of that list. In the simplest case, it is identical to the special form quote (see section 9.3 Quoting). For example, these two forms yield identical results:
`(a list of (+ 2 3) elements)
     => (a list of (+ 2 3) elements)
'(a list of (+ 2 3) elements)
     => (a list of (+ 2 3) elements)
The special marker `,' inside of the argument to backquote indicates a value that isn't constant. Backquote evaluates the argument of `,' and puts the value in the list structure:
(list 'a 'list 'of (+ 2 3) 'elements)
     => (a list of 5 elements)
`(a list of ,(+ 2 3) elements)
     => (a list of 5 elements)
Substitution with `,' is allowed at deeper levels of the list structure also. For example:
(defmacro t-becomes-nil (variable)
  `(if (eq ,variable t)
       (setq ,variable nil)))

(t-becomes-nil foo)
     == (if (eq foo t) (setq foo nil))
You can also splice an evaluated value into the resulting list, using the special marker `,@'. The elements of the spliced list become elements at the same level as the other elements of the resulting list. The equivalent code without using ``' is often unreadable. Here are some examples:
(setq some-list '(2 3))
     => (2 3)
(cons 1 (append some-list '(4) some-list))
     => (1 2 3 4 2 3)
`(1 ,@some-list 4 ,@some-list)
     => (1 2 3 4 2 3)

(setq list '(hack foo bar))
     => (hack foo bar)
(cons 'use
  (cons 'the
    (cons 'words (append (cdr list) '(as elements)))))
     => (use the words foo bar as elements)
`(use the words ,@(cdr list) as elements)
     => (use the words foo bar as elements)
In old Emacs versions, before version 19.29, ``' used a different syntax which required an extra level of parentheses around the entire backquote construct. Likewise, each `,' or `,@' substitution required an extra level of parentheses surrounding both the `,' or `,@' and the following expression. The old syntax required whitespace between the ``', `,' or `,@' and the following expression.

This syntax is still accepted, for compatibility with old Emacs versions, but we recommend not using it in new programs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.6 Common Problems Using Macros

The basic facts of macro expansion have counterintuitive consequences. This section describes some important consequences that can lead to trouble, and rules to follow to avoid trouble.

13.6.1 Wrong Time

Do the work in the expansion, not in the macro.

13.6.2 Evaluating Macro Arguments Repeatedly

The expansion should evaluate each macro arg once.

13.6.3 Local Variables in Macro Expansions

Local variable bindings in the expansion require special care.

13.6.4 Evaluating Macro Arguments in Expansion

Don't evaluate them; put them in the expansion.

13.6.5 How Many Times is the Macro Expanded?

Avoid depending on how many times expansion is done.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.6.1 Wrong Time

The most common problem in writing macros is doing too some of the real work prematurely--while expanding the macro, rather than in the expansion itself. For instance, one real package had this nmacro definition:
(defmacro my-set-buffer-multibyte (arg)
  (if (fboundp 'set-buffer-multibyte)
      (set-buffer-multibyte arg)))
With this erroneous macro definition, the program worked fine when interpreted but failed when compiled. This macro definition called set-buffer-multibyte during compilation, which was wrong, and then did nothing when the compiled package was run. The definition that the programmer really wanted was this:
(defmacro my-set-buffer-multibyte (arg)
  (if (fboundp 'set-buffer-multibyte)
      `(set-buffer-multibyte ,arg)))
This macro expands, if appropriate, into a call to set-buffer-multibyte that will be executed when the compiled program is actually run.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.6.2 Evaluating Macro Arguments Repeatedly

When defining a macro you must pay attention to the number of times the arguments will be evaluated when the expansion is executed. The following macro (used to facilitate iteration) illustrates the problem. This macro allows us to write a simple "for" loop such as one might find in Pascal.
(defmacro for (var from init to final do &rest body)
  "Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
  (list 'let (list (list var init))
        (cons 'while (cons (list '<= var final)
                           (append body (list (list 'inc var)))))))
=> for

(for i from 1 to 3 do
   (setq square (* i i))
   (princ (format "\n%d %d" i square)))
==>
(let ((i 1))
  (while (<= i 3)
    (setq square (* i i))
    (princ (format "%d      %d" i square))
    (inc i)))

     -|1       1
     -|2       4
     -|3       9
=> nil
The arguments from, to, and do in this macro are "syntactic sugar"; they are entirely ignored. The idea is that you will write noise words (such as from, to, and do) in those positions in the macro call.

Here's an equivalent definition simplified through use of backquote:
(defmacro for (var from init to final do &rest body)
  "Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
  `(let ((,var ,init))
     (while (<= ,var ,final)
       ,@body
       (inc ,var))))
Both forms of this definition (with backquote and without) suffer from the defect that final is evaluated on every iteration. If final is a constant, this is not a problem. If it is a more complex form, say (long-complex-calculation x), this can slow down the execution significantly. If final has side effects, executing it more than once is probably incorrect.

A well-designed macro definition takes steps to avoid this problem by producing an expansion that evaluates the argument expressions exactly once unless repeated evaluation is part of the intended purpose of the macro. Here is a correct expansion for the for macro:
(let ((i 1)
      (max 3))
  (while (<= i max)
    (setq square (* i i))
    (princ (format "%d      %d" i square))
    (inc i)))
Here is a macro definition that creates this expansion:
(defmacro for (var from init to final do &rest body)
  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  `(let ((,var ,init)
         (max ,final))
     (while (<= ,var max)
       ,@body
       (inc ,var))))
Unfortunately, this fix introduces another problem, described in the following section.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.6.3 Local Variables in Macro Expansions

In the previous section, the definition of for was fixed as follows to make the expansion evaluate the macro arguments the proper number of times:
(defmacro for (var from init to final do &rest body)
  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  `(let ((,var ,init)
         (max ,final))
     (while (<= ,var max)
       ,@body
       (inc ,var))))
The new definition of for has a new problem: it introduces a local variable named max which the user does not expect. This causes trouble in examples such as the following:
(let ((max 0))
  (for x from 0 to 10 do
    (let ((this (frob x)))
      (if (< max this)
          (setq max this)))))
The references to max inside the body of the for, which are supposed to refer to the user's binding of max, really access the binding made by for.

The way to correct this is to use an uninterned symbol instead of max (see section 8.3 Creating and Interning Symbols). The uninterned symbol can be bound and referred to just like any other symbol, but since it is created by for, we know that it cannot already appear in the user's program. Since it is not interned, there is no way the user can put it into the program later. It will never appear anywhere except where put by for. Here is a definition of for that works this way:
(defmacro for (var from init to final do &rest body)
  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  (let ((tempvar (make-symbol "max")))
    `(let ((,var ,init)
           (,tempvar ,final))
       (while (<= ,var ,tempvar)
         ,@body
         (inc ,var)))))
This creates an uninterned symbol named max and puts it in the expansion instead of the usual interned symbol max that appears in expressions ordinarily.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.6.4 Evaluating Macro Arguments in Expansion

Another problem can happen if the macro definition itself evaluates any of the macro argument expressions, such as by calling eval (see section 9.4 Eval). If the argument is supposed to refer to the user's variables, you may have trouble if the user happens to use a variable with the same name as one of the macro arguments. Inside the macro body, the macro argument binding is the most local binding of this variable, so any references inside the form being evaluated do refer to it. Here is an example:
(defmacro foo (a)
  (list 'setq (eval a) t))
     => foo
(setq x 'b)
(foo x) ==> (setq b t)
     => t                  ; and b has been set.
;; but
(setq a 'c)
(foo a) ==> (setq a t)
     => t                  ; but this set a, not c.
It makes a difference whether the user's variable is named a or x, because a conflicts with the macro argument variable a.

Another problem with calling eval in a macro definition is that it probably won't do what you intend in a compiled program. The byte-compiler runs macro definitions while compiling the program, when the program's own computations (which you might have wished to access with eval) don't occur and its local variable bindings don't exist.

To avoid these problems, don't evaluate an argument expression while computing the macro expansion. Instead, substitute the expression into the macro expansion, so that its value will be computed as part of executing the expansion. This is how the other examples in this chapter work.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

13.6.5 How Many Times is the Macro Expanded?

Occasionally problems result from the fact that a macro call is expanded each time it is evaluated in an interpreted function, but is expanded only once (during compilation) for a compiled function. If the macro definition has side effects, they will work differently depending on how many times the macro is expanded.

Therefore, you should avoid side effects in computation of the macro expansion, unless you really know what you are doing.

One special kind of side effect can't be avoided: constructing Lisp objects. Almost all macro expansions include constructed lists; that is the whole point of most macros. This is usually safe; there is just one case where you must be careful: when the object you construct is part of a quoted constant in the macro expansion.

If the macro is expanded just once, in compilation, then the object is constructed just once, during compilation. But in interpreted execution, the macro is expanded each time the macro call runs, and this means a new object is constructed each time.

In most clean Lisp code, this difference won't matter. It can matter only if you perform side-effects on the objects constructed by the macro definition. Thus, to avoid trouble, avoid side effects on objects constructed by macro definitions. Here is an example of how such side effects can get you into trouble:
(defmacro empty-object ()
  (list 'quote (cons nil nil)))

(defun initialize (condition)
  (let ((object (empty-object)))
    (if condition
        (setcar object condition))
    object))
If initialize is interpreted, a new list (nil) is constructed each time initialize is called. Thus, no side effect survives between calls. If initialize is compiled, then the macro empty-object is expanded during compilation, producing a single "constant" (nil) that is reused and altered each time initialize is called.

One way to avoid pathological cases like this is to think of empty-object as a funny kind of constant, not as a memory allocation construct. You wouldn't use setcar on a constant such as '(nil), so naturally you won't use it on (empty-object) either.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14. Writing Customization Definitions

This chapter describes how to declare user options for customization, and also customization groups for classifying them. We use the term customization item to include both kinds of customization definitions--as well as face definitions (see section 38.11.2 Defining Faces).

14.1 Common Item Keywords

14.2 Defining Custom Groups

14.3 Defining Customization Variables

14.4 Customization Types

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14.1 Common Item Keywords

All kinds of customization declarations (for variables and groups, and for faces) accept keyword arguments for specifying various information. This section describes some keywords that apply to all kinds.

All of these keywords, except :tag, can be used more than once in a given item. Each use of the keyword has an independent effect. The keyword :tag is an exception because any given item can only display one name.

:tag label
Use label, a string, instead of the item's name, to label the item in customization menus and buffers.

:group group
Put this customization item in group group. When you use :group in a defgroup, it makes the new group a subgroup of group.
If you use this keyword more than once, you can put a single item into more than one group. Displaying any of those groups will show this item. Please don't overdo this, since the result would be annoying.

:link link-data
Include an external link after the documentation string for this item. This is a sentence containing an active field which references some other documentation.
There are three alternatives you can use for link-data:

(custom-manual info-node)
Link to an Info node; info-node is a string which specifies the node name, as in "(emacs)Top". The link appears as `[manual]' in the customization buffer.

(info-link info-node)
Like custom-manual except that the link appears in the customization buffer with the Info node name.

(url-link url)
Link to a web page; url is a string which specifies the URL. The link appears in the customization buffer as url.

(emacs-commentary-link library)
Link to the commentary section of a library; library is a string which specifies the library name.
You can specify the text to use in the customization buffer by adding :tag name after the first element of the link-data; for example, (info-link :tag "foo" "(emacs)Top") makes a link to the Emacs manual which appears in the buffer as `foo'.

An item can have more than one external link; however, most items have none at all.

:load file
Load file file (a string) before displaying this customization item. Loading is done with load-library, and only if the file is not already loaded.

:require feature
Require feature feature (a symbol) when installing a value for this item (an option or a face) that was saved using the customization feature. This is done by calling require.
The most common reason to use :require is when a variable enables a feature such as a minor mode, and just setting the variable won't have any effect unless the code which implements the mode is loaded.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14.2 Defining Custom Groups

Each Emacs Lisp package should have one main customization group which contains all the options, faces and other groups in the package. If the package has a small number of options and faces, use just one group and put everything in it. When there are more than twelve or so options and faces, then you should structure them into subgroups, and put the subgroups under the package's main customization group. It is OK to put some of the options and faces in the package's main group alongside the subgroups.

The package's main or only group should be a member of one or more of the standard customization groups. (To display the full list of them, use M-x customize.) Choose one or more of them (but not too many), and add your group to each of them using the :group keyword.

The way to declare new customization groups is with defgroup.

Macro: defgroup group members doc [keyword value]...
Declare group as a customization group containing members. Do not quote the symbol group. The argument doc specifies the documentation string for the group. It should not start with a `*' as in defcustom; that convention is for variables only.

The argument members is a list specifying an initial set of customization items to be members of the group. However, most often members is nil, and you specify the group's members by using the :group keyword when defining those members.

If you want to specify group members through members, each element should have the form (name widget). Here name is a symbol, and widget is a widget type for editing that symbol. Useful widgets are custom-variable for a variable, custom-face for a face, and custom-group for a group.

When a new group is introduced into Emacs, use this keyword in defgroup:

:version version
This option specifies that the group was first introduced in Emacs version version. The value version must be a string.
Tag the group with a version like this when it is introduced, rather than the individual members (see section 14.3 Defining Customization Variables).

In addition to the common keywords (see section 14.1 Common Item Keywords), you can also use this keyword in defgroup:

:prefix prefix
If the name of an item in the group starts with prefix, then the tag for that item is constructed (by default) by omitting prefix.
One group can have any number of prefixes.
The prefix-discarding feature is currently turned off, which means that :prefix currently has no effect. We did this because we found that discarding the specified prefixes often led to confusing names for options. This happened because the people who wrote the defgroup definitions for various groups added :prefix keywords whenever they make logical sense--that is, whenever the variables in the library have a common prefix.

In order to obtain good results with :prefix, it would be necessary to check the specific effects of discarding a particular prefix, given the specific items in a group and their names and documentation. If the resulting text is not clear, then :prefix should not be used in that case.

It should be possible to recheck all the customization groups, delete the :prefix specifications which give unclear results, and then turn this feature back on, if someone would like to do the work.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14.3 Defining Customization Variables

Use defcustom to declare user-editable variables.

Macro: defcustom option default doc [keyword value]...
Declare option as a customizable user option variable. Do not quote option. The argument doc specifies the documentation string for the variable. It should often start with a `*' to mark it as a user option (see section 11.5 Defining Global Variables). Do not start the documentation string with `*' for options which cannot or normally should not be set with set-variable; examples of the former are global minor mode options such as global-font-lock-mode and examples of the latter are hooks.

If option is void, defcustom initializes it to default. default should be an expression to compute the value; be careful in writing it, because it can be evaluated on more than one occasion. You should normally avoid using backquotes in default because they are not expanded when editing the value, causing list values to appear to have the wrong structure.

When you evaluate a defcustom form with C-M-x in Emacs Lisp mode (eval-defun), a special feature of eval-defun arranges to set the variable unconditionally, without testing whether its value is void. (The same feature applies to defvar.) See section 11.5 Defining Global Variables.

defcustom accepts the following additional keywords:

:type type
Use type as the data type for this option. It specifies which values are legitimate, and how to display the value. See section 14.4 Customization Types, for more information.

:options list
Specify list as the list of reasonable values for use in this option. The user is not restricted to using only these values, but they are offered as convenient alternatives.
This is meaningful only for certain types, currently including hook, plist and alist. See the definition of the individual types for a description of how to use :options.

:version version
This option specifies that the variable was first introduced, or its default value was changed, in Emacs version version. The value version must be a string. For example,
(defcustom foo-max 34
  "*Maximum number of foo's allowed."
  :type 'integer
  :group 'foo
  :version "20.3")
:set setfunction
Specify setfunction as the way to change the value of this option. The function setfunction should take two arguments, a symbol and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting the option as a Lisp variable). The default for setfunction is set-default.

:get getfunction
Specify getfunction as the way to extract the value of this option. The function getfunction should take one argument, a symbol, and should return the "current value" for that symbol (which need not be the symbol's Lisp value). The default is default-value.

:initialize function
function should be a function used to initialize the variable when the defcustom is evaluated. It should take two arguments, the symbol and value. Here are some predefined functions meant for use in this way:

custom-initialize-set
Use the variable's :set function to initialize the variable, but do not reinitialize it if it is already non-void. This is the default :initialize function.

custom-initialize-default
Like custom-initialize-set, but use the function set-default to set the variable, instead of the variable's :set function. This is the usual choice for a variable whose :set function enables or disables a minor mode; with this choice, defining the variable will not call the minor mode function, but customizing the variable will do so.

custom-initialize-reset
Always use the :set function to initialize the variable. If the variable is already non-void, reset it by calling the :set function using the current value (returned by the :get method).

custom-initialize-changed
Use the :set function to initialize the variable, if it is already set or has been customized; otherwise, just use set-default.

:set-after variables
When setting variables according to saved customizations, make sure to set the variables variables before this one; in other words, delay setting this variable until after those others have been handled. Use :set-after if setting this variable won't work properly unless those other variables already have their intended values.
The :require option is useful for an option that turns on the operation of a certain feature. Assuming that the package is coded to check the value of the option, you still need to arrange for the package to be loaded. You can do that with :require. See section 14.1 Common Item Keywords. Here is an example, from the library `paren.el':
(defcustom show-paren-mode nil
  "Toggle Show Paren mode..."
  :set (lambda (symbol value)
         (show-paren-mode (or value 0)))
  :initialize 'custom-initialize-default
  :type 'boolean
  :group 'paren-showing
  :require 'paren)
If a customization item has a type such as hook or alist, which supports :options, you can add additional options to the item, outside the defcustom declaration, by calling custom-add-option. For example, if you define a function my-lisp-mode-initialization intended to be called from emacs-lisp-mode-hook, you might want to add that to the list of options for emacs-lisp-mode-hook, but not by editing its definition. You can do it thus:
(custom-add-option 'emacs-lisp-mode-hook
                   'my-lisp-mode-initialization)
Function: custom-add-option symbol option
To the customization symbol, add option.

The precise effect of adding option depends on the customization type of symbol.

Internally, defcustom uses the symbol property standard-value to record the expression for the default value, and saved-value to record the value saved by the user with the customization buffer. The saved-value property is actually a list whose car is an expression which evaluates to the value.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14.4 Customization Types

When you define a user option with defcustom, you must specify its customization type. That is a Lisp object which describes (1) which values are legitimate and (2) how to display the value in the customization buffer for editing.

You specify the customization type in defcustom with the :type keyword. The argument of :type is evaluated; since types that vary at run time are rarely useful, normally you use a quoted constant. For example:
(defcustom diff-command "diff"
  "*The command to use to run diff."
  :type '(string)
  :group 'diff)
In general, a customization type is a list whose first element is a symbol, one of the customization type names defined in the following sections. After this symbol come a number of arguments, depending on the symbol. Between the type symbol and its arguments, you can optionally write keyword-value pairs (see section 14.4.4 Type Keywords).

Some of the type symbols do not use any arguments; those are called simple types. For a simple type, if you do not use any keyword-value pairs, you can omit the parentheses around the type symbol. For example just string as a customization type is equivalent to (string).

14.4.1 Simple Types

14.4.2 Composite Types

14.4.3 Splicing into Lists

14.4.4 Type Keywords

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14.4.1 Simple Types

This section describes all the simple customization types.

sexp
The value may be any Lisp object that can be printed and read back. You can use sexp as a fall-back for any option, if you don't want to take the time to work out a more specific type to use.

integer
The value must be an integer, and is represented textually in the customization buffer.

number
The value must be a number, and is represented textually in the customization buffer.

string
The value must be a string, and the customization buffer shows just the contents, with no delimiting `"' characters and no quoting with `\'.

regexp
Like string except that the string must be a valid regular expression.

character
The value must be a character code. A character code is actually an integer, but this type shows the value by inserting the character in the buffer, rather than by showing the number.

file
The value must be a file name, and you can do completion with M-TAB.

(file :must-match t)
The value must be a file name for an existing file, and you can do completion with M-TAB.

directory
The value must be a directory name, and you can do completion with M-TAB.

hook
The value must be a list of functions (or a single function, but that is obsolete usage). This customization type is used for hook variables. You can use the :options keyword in a hook variable's defcustom to specify a list of functions recommended for use in the hook; see 14.3 Defining Customization Variables.

alist
The value must be a list of cons-cells, the CAR of each cell representing a key, and the CDR of the same cell representing an associated value. The user can add and delete key/value pairs, and edit both the key and the value of each pair.
You can specify the key and value types like this:
(alist :key-type key-type :value-type value-type)
where key-type and value-type are customization type specifications. The default key type is sexp, and the default value type is sexp.

The user can add any key matching the specified key type, but you can give some keys a preferential treatment by specifying them with the :options (see 14.3 Defining Customization Variables). The specified keys will always be shown in the customize buffer (together with a suitable value), with a checkbox to include or exclude or disable the key/value pair from the alist. The user will not be able to edit the keys specified by the :options keyword argument.

The argument to the :options keywords should be a list of option specifications. Ordinarily, the options are simply atoms, which are the specified keys. For example:
:options '("foo" "bar" "baz")
specifies that there are three "known" keys, namely "foo", "bar" and "baz", which will always be shown first.

You may want to restrict the value type for specific keys, for example, the value associated with the "bar" key can only be an integer. You can specify this by using a list instead of an atom in the option specification. The first element will specify the key, like before, while the second element will specify the value type.
:options '("foo" ("bar" integer) "baz")
Finally, you may want to change how the key is presented. By default, the key is simply shown as a const, since the user cannot change the special keys specified with the :options keyword. However, you may want to use a more specialized type for presenting the key, like function-item if you know it is a symbol with a function binding. This is done by using a customization type specification instead of a symbol for the key.
:options '("foo" ((function-item some-function) integer) "baz")
Many alists use lists with two elements, instead of cons cells. For example,
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
  "Each element is a list of the form (KEY VALUE).")
instead of
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
  "Each element is a cons-cell (KEY . VALUE).")
Because of the way lists are implemented on top of cons cells, you can treat list-alist in the example above as a cons cell alist, where the value type is a list with a single element containing the real value.
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
  "Each element is a list of the form (KEY VALUE)."
  :type '(alist :value-type (group integer)))
The group widget is used here instead of list only because the formatting is better suited for the purpose.

Similarily, you can have alists with more values associated with each key, using variations of this trick:
(defcustom person-data '(("brian"  50 t)
                         ("dorith" 55 nil)
                         ("ken"    52 t))
  "Alist of basic info about people.
Each element has the form (NAME AGE MALE-FLAG)."
  :type '(alist :value-type (group age boolean)))

(defcustom pets '(("brian")
                  ("dorith" "dog" "guppy")
                  ("ken" "cat"))
  "Alist of people's pets.
In an element (KEY . VALUE), KEY is the person's name,
and the VALUE is a list of that person's pets."
  :type '(alist :value-type (repeat string)))
plist
The plist custom type is similar to the alist (see above), except that the information is stored as a property list, i.e. a list of this form:
(key value key value key value ...)
The default :key-type for plist is symbol, rather than sexp.

symbol
The value must be a symbol. It appears in the customization buffer as the name of the symbol.

function
The value must be either a lambda expression or a function name. When it is a function name, you can do completion with M-TAB.

variable
The value must be a variable name, and you can do completion with M-TAB.

face
The value must be a symbol which is a face name, and you can do completion with M-TAB.

boolean
The value is boolean--either nil or t. Note that by using choice and const together (see the next section), you can specify that the value must be nil or t, but also specify the text to describe each value in a way that fits the specific meaning of the alternative.

coding-system
The value must be a coding-system name, and you can do completion with M-TAB.

color
The value must be a valid color name, and you can do completion with M-TAB. A sample is provided,

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14.4.2 Composite Types

When none of the simple types is appropriate, you can use composite types, which build new types from other types. Here are several ways of doing that:

(restricted-sexp :match-alternatives criteria)
The value may be any Lisp object that satisfies one of criteria. criteria should be a list, and each element should be one of these possibilities:

A predicate--that is, a function of one argument that has no side effects, and returns either nil or non-nil according to the argument. Using a predicate in the list says that objects for which the predicate returns non-nil are acceptable.

A quoted constant--that is, 'object. This sort of element in the list says that object itself is an acceptable value.

For example,
(restricted-sexp :match-alternatives
                 (integerp 't 'nil))
allows integers, t and nil as legitimate values.

The customization buffer shows all legitimate values using their read syntax, and the user edits them textually.

(cons car-type cdr-type)
The value must be a cons cell, its CAR must fit car-type, and its CDR must fit cdr-type. For example, (cons string symbol) is a customization type which matches values such as ("foo" . foo).
In the customization buffer, the CAR and the CDR are displayed and edited separately, each according to the type that you specify for it.

(list element-types...)
The value must be a list with exactly as many elements as the element-types you have specified; and each element must fit the corresponding element-type.
For example, (list integer string function) describes a list of three elements; the first element must be an integer, the second a string, and the third a function.

In the customization buffer, each element is displayed and edited separately, according to the type specified for it.

(vector element-types...)
Like list except that the value must be a vector instead of a list. The elements work the same as in list.

(choice alternative-types...)
The value must fit at least one of alternative-types. For example, (choice integer string) allows either an integer or a string.
In the customization buffer, the user selects one of the alternatives using a menu, and can then edit the value in the usual way for that alternative.

Normally the strings in this menu are determined automatically from the choices; however, you can specify different strings for the menu by including the :tag keyword in the alternatives. For example, if an integer stands for a number of spaces, while a string is text to use verbatim, you might write the customization type this way,
(choice (integer :tag "Number of spaces")
        (string :tag "Literal text"))
so that the menu offers `Number of spaces' and `Literal Text'.

In any alternative for which nil is not a valid value, other than a const, you should specify a valid default for that alternative using the :value keyword. See section 14.4.4 Type Keywords.

(radio element-types...)
This is similar to choice, except that the choices are displayed using `radio buttons' rather than a menu. This has the advantage of displaying documentation for the choices when applicable and so is often a good choice for a choice between constant functions (function-item customization types).

(const value)
The value must be value---nothing else is allowed.
The main use of const is inside of choice. For example, (choice integer (const nil)) allows either an integer or nil.

:tag is often used with const, inside of choice. For example,
(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (const :tag "Ask" foo))
describes a variable for which t means yes, nil means no, and foo means "ask."

(other value)
This alternative can match any Lisp value, but if the user chooses this alternative, that selects the value value.
The main use of other is as the last element of choice. For example,
(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (other :tag "Ask" foo))
describes a variable for which t means yes, nil means no, and anything else means "ask." If the user chooses `Ask' from the menu of alternatives, that specifies the value foo; but any other value (not t, nil or foo) displays as `Ask', just like foo.

(function-item function)
Like const, but used for values which are functions. This displays the documentation string as well as the function name. The documentation string is either the one you specify with :doc, or function's own documentation string.

(variable-item variable)
Like const, but used for values which are variable names. This displays the documentation string as well as the variable name. The documentation string is either the one you specify with :doc, or variable's own documentation string.

(set types...)
The value must be a list, and each element of the list must match one of the types specified.
This appears in the customization buffer as a checklist, so that each of types may have either one corresponding element or none. It is not possible to specify two different elements that match the same one of types. For example, (set integer symbol) allows one integer and/or one symbol in the list; it does not allow multiple integers or multiple symbols. As a result, it is rare to use nonspecific types such as integer in a set.

Most often, the types in a set are const types, as shown here:
(set (const :bold) (const :italic))
Sometimes they describe possible elements in an alist:
(set (cons :tag "Height" (const height) integer)
     (cons :tag "Width" (const width) integer))
That lets the user specify a height value optionally and a width value optionally.

(repeat element-type)
The value must be a list and each element of the list must fit the type element-type. This appears in the customization buffer as a list of elements, with `[INS]' and `[DEL]' buttons for adding more elements or removing elements.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14.4.3 Splicing into Lists

The :inline feature lets you splice a variable number of elements into the middle of a list or vector. You use it in a set, choice or repeat type which appears among the element-types of a list or vector.

Normally, each of the element-types in a list or vector describes one and only one element of the list or vector. Thus, if an element-type is a repeat, that specifies a list of unspecified length which appears as one element.

But when the element-type uses :inline, the value it matches is merged directly into the containing sequence. For example, if it matches a list with three elements, those become three elements of the overall sequence. This is analogous to using `,@' in the backquote construct.

For example, to specify a list whose first element must be t and whose remaining arguments should be zero or more of foo and bar, use this customization type:
(list (const t) (set :inline t foo bar))
This matches values such as (t), (t foo), (t bar) and (t foo bar).

When the element-type is a choice, you use :inline not in the choice itself, but in (some of) the alternatives of the choice. For example, to match a list which must start with a file name, followed either by the symbol t or two strings, use this customization type:
(list file
      (choice (const t)
              (list :inline t string string)))
If the user chooses the first alternative in the choice, then the overall list has two elements and the second element is t. If the user chooses the second alternative, then the overall list has three elements and the second and third must be strings.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

14.4.4 Type Keywords

You can specify keyword-argument pairs in a customization type after the type name symbol. Here are the keywords you can use, and their meanings:

:value default
This is used for a type that appears as an alternative inside of choice; it specifies the default value to use, at first, if and when the user selects this alternative with the menu in the customization buffer.
Of course, if the actual value of the option fits this alternative, it will appear showing the actual value, not default.

If nil is not a valid value for the alternative, then it is essential to specify a valid default with :value.

:format format-string
This string will be inserted in the buffer to represent the value corresponding to the type. The following `%' escapes are available for use in format-string:

`%[button%]'
Display the text button marked as a button. The :action attribute specifies what the button will do if the user invokes it; its value is a function which takes two arguments--the widget which the button appears in, and the event.
There is no way to specify two different buttons with different actions.

`%{sample%}'
Show sample in a special face specified by :sample-face.

`%v'
Substitute the item's value. How the value is represented depends on the kind of item, and (for variables) on the customization type.

`%d'
Substitute the item's documentation string.

`%h'
Like `%d', but if the documentation string is more than one line, add an active field to control whether to show all of it or just the first line.

`%t'
Substitute the tag here. You specify the tag with the :tag keyword.

`%%'
Display a literal `%'.

:action action
Perform action if the user clicks on a button.

:button-face face
Use the face face (a face name or a list of face names) for button text displayed with `%[...%]'.

:button-prefix prefix

:button-suffix suffix
These specify the text to display before and after a button. Each can be:

nil
No text is inserted.

a string
The string is inserted literally.

a symbol
The symbol's value is used.

:tag tag
Use tag (a string) as the tag for the value (or part of the value) that corresponds to this type.

:doc doc
Use doc as the documentation string for this value (or part of the value) that corresponds to this type. In order for this to work, you must specify a value for :format, and use `%d' or `%h' in that value.
The usual reason to specify a documentation string for a type is to provide more information about the meanings of alternatives inside a :choice type or the parts of some other composite type.

:help-echo motion-doc
When you move to this item with widget-forward or widget-backward, it will display the string motion-doc in the echo area. In addition, motion-doc is used as the mouse help-echo string and may actually be a function or form evaluated to yield a help string as for help-echo text properties.

:match function
Specify how to decide whether a value matches the type. The corresponding value, function, should be a function that accepts two arguments, a widget and a value; it should return non-nil if the value is acceptable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15. Loading

Loading a file of Lisp code means bringing its contents into the Lisp environment in the form of Lisp objects. Emacs finds and opens the file, reads the text, evaluates each form, and then closes the file.

The load functions evaluate all the expressions in a file just as the eval-current-buffer function evaluates all the expressions in a buffer. The difference is that the load functions read and evaluate the text in the file as found on disk, not the text in an Emacs buffer.

The loaded file must contain Lisp expressions, either as source code or as byte-compiled code. Each form in the file is called a top-level form. There is no special format for the forms in a loadable file; any form in a file may equally well be typed directly into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions.

A file containing Lisp code is often called a library. Thus, the "Rmail library" is a file containing code for Rmail mode. Similarly, a "Lisp library directory" is a directory of files containing Lisp code.

15.1 How Programs Do Loading

The load function and others.

15.2 Library Search

Finding a library to load.

15.3 Loading Non-ASCII Characters

Non-ASCII characters in Emacs Lisp files.

15.4 Autoload

Setting up a function to autoload.

15.5 Repeated Loading

Precautions about loading a file twice.

15.6 Features

Loading a library if it isn't already loaded.

15.7 Unloading

How to "unload" a library that was loaded.

15.8 Hooks for Loading

Providing code to be run when particular libraries are loaded.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15.1 How Programs Do Loading

Emacs Lisp has several interfaces for loading. For example, autoload creates a placeholder object for a function defined in a file; trying to call the autoloading function loads the file to get the function's real definition (see section 15.4 Autoload). require loads a file if it isn't already loaded (see section 15.6 Features). Ultimately, all these facilities call the load function to do the work.

Function: load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file.

To find the file, load first looks for a file named `filename.elc', that is, for a file whose name is filename with `.elc' appended. If such a file exists, it is loaded. If there is no file by that name, then load looks for a file named `filename.el'. If that file exists, it is loaded. Finally, if neither of those names is found, load looks for a file named filename with nothing appended, and loads it if it exists. (The load function is not clever about looking at filename. In the perverse case of a file named `foo.el.el', evaluation of (load "foo.el") will indeed find it.)

If the optional argument nosuffix is non-nil, then the suffixes `.elc' and `.el' are not tried. In this case, you must specify the precise file name you want. By specifying the precise file name and using t for nosuffix, you can prevent perverse file names such as `foo.el.el' from being tried.

If the optional argument must-suffix is non-nil, then load insists that the file name used must end in either `.el' or `.elc', unless it contains an explicit directory name. If filename does not contain an explicit directory name, and does not end in a suffix, then load insists on adding one.

If filename is a relative file name, such as `foo' or `baz/foo.bar', load searches for the file using the variable load-path. It appends filename to each of the directories listed in load-path, and loads the first file it finds whose name matches. The current default directory is tried only if it is specified in load-path, where nil stands for the default directory. load tries all three possible suffixes in the first directory in load-path, then all three suffixes in the second directory, and so on. See section 15.2 Library Search.

If you get a warning that `foo.elc' is older than `foo.el', it means you should consider recompiling `foo.el'. See section 16. Byte Compilation.

When loading a source file (not compiled), load performs character set translation just as Emacs would do when visiting the file. See section 33.10 Coding Systems.

Messages like `Loading foo...' and `Loading foo...done' appear in the echo area during loading unless nomessage is non-nil.

Any unhandled errors while loading a file terminate loading. If the load was done for the sake of autoload, any function definitions made during the loading are undone.

If load can't find the file to load, then normally it signals the error file-error (with `Cannot open load file filename'). But if missing-ok is non-nil, then load just returns nil.

You can use the variable load-read-function to specify a function for load to use instead of read for reading expressions. See below.

load returns t if the file loads successfully.

Command: load-file filename
This command loads the file filename. If filename is a relative file name, then the current default directory is assumed. load-path is not used, and suffixes are not appended. Use this command if you wish to specify precisely the file name to load.

Command: load-library library
This command loads the library named library. It is equivalent to load, except in how it reads its argument interactively.

Variable: load-in-progress
This variable is non-nil if Emacs is in the process of loading a file, and it is nil otherwise.

Variable: load-read-function
This variable specifies an alternate expression-reading function for load and eval-region to use instead of read. The function should accept one argument, just as read does.

Normally, the variable's value is nil, which means those functions should use read.

Note: Instead of using this variable, it is cleaner to use another, newer feature: to pass the function as the read-function argument to eval-region. See section 9.4 Eval.

For information about how load is used in building Emacs, see E.1 Building Emacs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15.2 Library Search

When Emacs loads a Lisp library, it searches for the library in a list of directories specified by the variable load-path.

User Option: load-path
The value of this variable is a list of directories to search when loading files with load. Each element is a string (which must be a directory name) or nil (which stands for the current working directory).

The value of load-path is initialized from the environment variable EMACSLOADPATH, if that exists; otherwise its default value is specified in `emacs/src/paths.h' when Emacs is built. Then the list is expanded by adding subdirectories of the directories in the list.

The syntax of EMACSLOADPATH is the same as used for PATH; `:' (or `;', according to the operating system) separates directory names, and `.' is used for the current default directory. Here is an example of how to set your EMACSLOADPATH variable from a csh `.login' file:
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
Here is how to set it using sh:
export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
Here is an example of code you can place in your init file (see section 40.1.2 The Init File, `.emacs') to add several directories to the front of your default load-path:
(setq load-path
      (append (list nil "/user/bil/emacs"
                    "/usr/local/lisplib"
                    "~/emacs")
              load-path))
In this example, the path searches the current working directory first, followed then by the `/user/bil/emacs' directory, the `/usr/local/lisplib' directory, and the `~/emacs' directory, which are then followed by the standard directories for Lisp code.

Dumping Emacs uses a special value of load-path. If the value of load-path at the end of dumping is unchanged (that is, still the same special value), the dumped Emacs switches to the ordinary load-path value when it starts up, as described above. But if load-path has any other value at the end of dumping, that value is used for execution of the dumped Emacs also.

Therefore, if you want to change load-path temporarily for loading a few libraries in `site-init.el' or `site-load.el', you should bind load-path locally with let around the calls to load.

The default value of load-path, when running an Emacs which has been installed on the system, includes two special directories (and their subdirectories as well):
"/usr/local/share/emacs/version/site-lisp"
and
"/usr/local/share/emacs/site-lisp"
The first one is for locally installed packages for a particular Emacs version; the second is for locally installed packages meant for use with all installed Emacs versions.

There are several reasons why a Lisp package that works well in one Emacs version can cause trouble in another. Sometimes packages need updating for incompatible changes in Emacs; sometimes they depend on undocumented internal Emacs data that can change without notice; sometimes a newer Emacs version incorporates a version of the package, and should be used only with that version.

Emacs finds these directories' subdirectories and adds them to load-path when it starts up. Both immediate subdirectories and subdirectories multiple levels down are added to load-path.

Not all subdirectories are included, though. Subdirectories whose names do not start with a letter or digit are excluded. Subdirectories named `RCS' or `CVS' are excluded. Also, a subdirectory which contains a file named `.nosearch' is excluded. You can use these methods to prevent certain subdirectories of the `site-lisp' directories from being searched.

If you run Emacs from the directory where it was built--that is, an executable that has not been formally installed--then load-path normally contains two additional directories. These are the lisp and site-lisp subdirectories of the main build directory. (Both are represented as absolute file names.)

Command: locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library library. It searches for the library in the same way load does, and the argument nosuffix has the same meaning as in load: don't add suffixes `.elc' or `.el' to the specified name library.

If the path is non-nil, that list of directories is used instead of load-path.

When locate-library is called from a program, it returns the file name as a string. When the user runs locate-library interactively, the argument interactive-call is t, and this tells locate-library to display the file name in the echo area.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15.3 Loading Non-ASCII Characters

When Emacs Lisp programs contain string constants with non-ASCII characters, these can be represented within Emacs either as unibyte strings or as multibyte strings (see section 33.1 Text Representations). Which representation is used depends on how the file is read into Emacs. If it is read with decoding into multibyte representation, the text of the Lisp program will be multibyte text, and its string constants will be multibyte strings. If a file containing Latin-1 characters (for example) is read without decoding, the text of the program will be unibyte text, and its string constants will be unibyte strings. See section 33.10 Coding Systems.

To make the results more predictable, Emacs always performs decoding into the multibyte representation when loading Lisp files, even if it was started with the `--unibyte' option. This means that string constants with non-ASCII characters translate into multibyte strings. The only exception is when a particular file specifies no decoding.

The reason Emacs is designed this way is so that Lisp programs give predictable results, regardless of how Emacs was started. In addition, this enables programs that depend on using multibyte text to work even in a unibyte Emacs. Of course, such programs should be designed to notice whether the user prefers unibyte or multibyte text, by checking default-enable-multibyte-characters, and convert representations appropriately.

In most Emacs Lisp programs, the fact that non-ASCII strings are multibyte strings should not be noticeable, since inserting them in unibyte buffers converts them to unibyte automatically. However, if this does make a difference, you can force a particular Lisp file to be interpreted as unibyte by writing `-*-unibyte: t;-*-' in a comment on the file's first line. With that designator, the file will unconditionally be interpreted as unibyte, even in an ordinary multibyte Emacs session. This can matter when making keybindings to non-ASCII characters written as ?vliteral.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15.4 Autoload

The autoload facility allows you to make a function or macro known in Lisp, but put off loading the file that defines it. The first call to the function automatically reads the proper file to install the real definition and other associated code, then runs the real definition as if it had been loaded all along.

There are two ways to set up an autoloaded function: by calling autoload, and by writing a special "magic" comment in the source before the real definition. autoload is the low-level primitive for autoloading; any Lisp program can call autoload at any time. Magic comments are the most convenient way to make a function autoload, for packages installed along with Emacs. These comments do nothing on their own, but they serve as a guide for the command update-file-autoloads, which constructs calls to autoload and arranges to execute them when Emacs is built.

Function: autoload function filename &optional docstring interactive type
This function defines the function (or macro) named function so as to load automatically from filename. The string filename specifies the file to load to get the real definition of function.

If filename does not contain either a directory name, or the suffix .el or .elc, then autoload insists on adding one of these suffixes, and it will not load from a file whose name is just filename with no added suffix.

The argument docstring is the documentation string for the function. Normally, this should be identical to the documentation string in the function definition itself. Specifying the documentation string in the call to autoload makes it possible to look at the documentation without loading the function's real definition.

If interactive is non-nil, that says function can be called interactively. This lets completion in M-x work without loading function's real definition. The complete interactive specification is not given here; it's not needed unless the user actually calls function, and when that happens, it's time to load the real definition.

You can autoload macros and keymaps as well as ordinary functions. Specify type as macro if function is really a macro. Specify type as keymap if function is really a keymap. Various parts of Emacs need to know this information without loading the real definition.

An autoloaded keymap loads automatically during key lookup when a prefix key's binding is the symbol function. Autoloading does not occur for other kinds of access to the keymap. In particular, it does not happen when a Lisp program gets the keymap from the value of a variable and calls define-key; not even if the variable name is the same symbol function.

If function already has a non-void function definition that is not an autoload object, autoload does nothing and returns nil. If the function cell of function is void, or is already an autoload object, then it is defined as an autoload object like this:
(autoload filename docstring interactive type)
For example,
(symbol-function 'run-prolog)
     => (autoload "prolog" 169681 t nil)
In this case, "prolog" is the name of the file to load, 169681 refers to the documentation string in the `emacs/etc/DOC-version' file (see section 24.1 Documentation Basics), t means the function is interactive, and nil that it is not a macro or a keymap.

The autoloaded file usually contains other definitions and may require or provide one or more features. If the file is not completely loaded (due to an error in the evaluation of its contents), any function definitions or provide calls that occurred during the load are undone. This is to ensure that the next attempt to call any function autoloading from this file will try again to load the file. If not for this, then some of the functions in the file might be defined by the aborted load, but fail to work properly for the lack of certain subroutines not loaded successfully because they come later in the file.

If the autoloaded file fails to define the desired Lisp function or macro, then an error is signaled with data "Autoloading failed to define function function-name".

A magic autoload comment consists of `;;;###autoload', on a line by itself, just before the real definition of the function in its autoloadable source file. The command M-x update-file-autoloads writes a corresponding autoload call into `loaddefs.el'. Building Emacs loads `loaddefs.el' and thus calls autoload. M-x update-directory-autoloads is even more powerful; it updates autoloads for all files in the current directory.

The same magic comment can copy any kind of form into `loaddefs.el'. If the form following the magic comment is not a function-defining form or a defcustom form, it is copied verbatim. "Function-defining forms" include define-skeleton, define-derived-mode, define-generic-mode and define-minor-mode as well as defun and defmacro. To save space, a defcustom form is converted to a defvar in `loaddefs.el', with some additional information if it uses :require.

You can also use a magic comment to execute a form at build time without executing it when the file itself is loaded. To do this, write the form on the same line as the magic comment. Since it is in a comment, it does nothing when you load the source file; but M-x update-file-autoloads copies it to `loaddefs.el', where it is executed while building Emacs.

The following example shows how doctor is prepared for autoloading with a magic comment:
;;;###autoload
(defun doctor ()
  "Switch to *doctor* buffer and start giving psychotherapy."
  (interactive)
  (switch-to-buffer "*doctor*")
  (doctor-mode))
Here's what that produces in `loaddefs.el':
(autoload 'doctor "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy."
  t)
The backslash and newline immediately following the double-quote are a convention used only in the preloaded uncompiled Lisp files such as `loaddefs.el'; they tell make-docfile to put the documentation string in the `etc/DOC' file. See section E.1 Building Emacs. See also the commentary in `lib-src/make-docfile.c'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15.5 Repeated Loading

You can load a given file more than once in an Emacs session. For example, after you have rewritten and reinstalled a function definition by editing it in a buffer, you may wish to return to the original version; you can do this by reloading the file it came from.

When you load or reload files, bear in mind that the load and load-library functions automatically load a byte-compiled file rather than a non-compiled file of similar name. If you rewrite a file that you intend to save and reinstall, you need to byte-compile the new version; otherwise Emacs will load the older, byte-compiled file instead of your newer, non-compiled file! If that happens, the message displayed when loading the file includes, `(compiled; note, source is newer)', to remind you to recompile it.

When writing the forms in a Lisp library file, keep in mind that the file might be loaded more than once. For example, think about whether each variable should be reinitialized when you reload the library; defvar does not change the value if the variable is already initialized. (See section 11.5 Defining Global Variables.)

The simplest way to add an element to an alist is like this:
(setq minor-mode-alist
      (cons '(leif-mode " Leif") minor-mode-alist))
But this would add multiple elements if the library is reloaded. To avoid the problem, write this:
(or (assq 'leif-mode minor-mode-alist)
    (setq minor-mode-alist
          (cons '(leif-mode " Leif") minor-mode-alist)))
To add an element to a list just once, you can also use add-to-list (see section 11.8 How to Alter a Variable Value).

Occasionally you will want to test explicitly whether a library has already been loaded. Here's one way to test, in a library, whether it has been loaded before:
(defvar foo-was-loaded nil)

(unless foo-was-loaded
  execute-first-time-only
  (setq foo-was-loaded t))
If the library uses provide to provide a named feature, you can use featurep earlier in the file to test whether the provide call has been executed before. See section 15.6 Features.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15.6 Features

provide and require are an alternative to autoload for loading files automatically. They work in terms of named features. Autoloading is triggered by calling a specific function, but a feature is loaded the first time another program asks for it by name.

A feature name is a symbol that stands for a collection of functions, variables, etc. The file that defines them should provide the feature. Another program that uses them may ensure they are defined by requiring the feature. This loads the file of definitions if it hasn't been loaded already.

To require the presence of a feature, call require with the feature name as argument. require looks in the global variable features to see whether the desired feature has been provided already. If not, it loads the feature from the appropriate file. This file should call provide at the top level to add the feature to features; if it fails to do so, require signals an error.

For example, in `emacs/lisp/prolog.el', the definition for run-prolog includes the following code:
(defun run-prolog ()
  "Run an inferior Prolog process, with I/O via buffer *prolog*."
  (interactive)
  (require 'comint)
  (switch-to-buffer (make-comint "prolog" prolog-program-name))
  (inferior-prolog-mode))
The expression (require 'comint) loads the file `comint.el' if it has not yet been loaded. This ensures that make-comint is defined. Features are normally named after the files that provide them, so that require need not be given the file name.

The `comint.el' file contains the following top-level expression:
(provide 'comint)
This adds comint to the global features list, so that (require 'comint) will henceforth know that nothing needs to be done.

When require is used at top level in a file, it takes effect when you byte-compile that file (see section 16. Byte Compilation) as well as when you load it. This is in case the required package contains macros that the byte compiler must know about. It also avoids byte-compiler warnings for functions and variables defined in the file loaded with require.

Although top-level calls to require are evaluated during byte compilation, provide calls are not. Therefore, you can ensure that a file of definitions is loaded before it is byte-compiled by including a provide followed by a require for the same feature, as in the following example.
(provide 'my-feature)  ; Ignored by byte compiler,
                       ;   evaluated by load.
(require 'my-feature)  ; Evaluated by byte compiler.
The compiler ignores the provide, then processes the require by loading the file in question. Loading the file does execute the provide call, so the subsequent require call does nothing when the file is loaded.

Function: provide feature
This function announces that feature is now loaded, or being loaded, into the current Emacs session. This means that the facilities associated with feature are or will be available for other Lisp programs.

The direct effect of calling provide is to add feature to the front of the list features if it is not already in the list. The argument feature must be a symbol. provide returns feature.
features
     => (bar bish)

(provide 'foo)
     => foo
features
     => (foo bar bish)
When a file is loaded to satisfy an autoload, and it stops due to an error in the evaluating its contents, any function definitions or provide calls that occurred during the load are undone. See section 15.4 Autoload.

Function: require feature &optional filename noerror
This function checks whether feature is present in the current Emacs session (using (featurep feature); see below). The argument feature must be a symbol.

If the feature is not present, then require loads filename with load. If filename is not supplied, then the name of the symbol feature is used as the base file name to load. However, in this case, require insists on finding feature with an added suffix; a file whose name is just feature won't be used.

If loading the file fails to provide feature, require signals an error, `Required feature feature was not provided', unless noerror is non-nil.

Function: featurep feature
This function returns t if feature has been provided in the current Emacs session (i.e., if feature is a member of features.)

Variable: features
The value of this variable is a list of symbols that are the features loaded in the current Emacs session. Each symbol was put in this list with a call to provide. The order of the elements in the features list is not significant.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15.7 Unloading

You can discard the functions and variables loaded by a library to reclaim memory for other Lisp objects. To do this, use the function unload-feature:

Command: unload-feature feature &optional force
This command unloads the library that provided feature feature. It undefines all functions, macros, and variables defined in that library with defun, defalias, defsubst, defmacro, defconst, defvar, and defcustom. It then restores any autoloads formerly associated with those symbols. (Loading saves these in the autoload property of the symbol.)

Before restoring the previous definitions, unload-feature runs remove-hook to remove functions in the library from certain hooks. These hooks include variables whose names end in `hook' or `-hooks', plus those listed in loadhist-special-hooks. This is to prevent Emacs from ceasing to function because important hooks refer to functions that are no longer defined.

If these measures are not sufficient to prevent malfunction, a library can define an explicit unload hook. If feature-unload-hook is defined, it is run as a normal hook before restoring the previous definitions, instead of the usual hook-removing actions. The unload hook ought to undo all the global state changes made by the library that might cease to work once the library is unloaded. unload-feature can cause problems with libraries that fail to do this, so it should be used with caution.

Ordinarily, unload-feature refuses to unload a library on which other loaded libraries depend. (A library a depends on library b if a contains a require for b.) If the optional argument force is non-nil, dependencies are ignored and you can unload any library.

The unload-feature function is written in Lisp; its actions are based on the variable load-history.

Variable: load-history
This variable's value is an alist connecting library names with the names of functions and variables they define, the features they provide, and the features they require.

Each element is a list and describes one library. The CAR of the list is the name of the library, as a string. The rest of the list is composed of these kinds of objects:

Symbols that were defined by this library.
Cons cells of the form (require . feature) indicating features that were required.
Cons cells of the form (provide . feature) indicating features that were provided.

The value of load-history may have one element whose CAR is nil. This element describes definitions made with eval-buffer on a buffer that is not visiting a file.

The command eval-region updates load-history, but does so by adding the symbols defined to the element for the file being visited, rather than replacing that element. See section 9.4 Eval.

Preloaded libraries don't contribute initially to load-history. Instead, preloading writes information about preloaded libraries into a file, which can be loaded later on to add information to load-history describing the preloaded files. This file is installed in exec-directory and has a name of the form `fns-emacsversion.el'.

See the source for the function symbol-file, for an example of code that loads this file to find functions in preloaded libraries.

Variable: loadhist-special-hooks
This variable holds a list of hooks to be scanned before unloading a library, to remove functions defined in the library.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

15.8 Hooks for Loading

You can ask for code to be executed if and when a particular library is loaded, by calling eval-after-load.

Function: eval-after-load library form
This function arranges to evaluate form at the end of loading the library library, if and when library is loaded. If library is already loaded, it evaluates form right away.

The library name library must exactly match the argument of load. To get the proper results when an installed library is found by searching load-path, you should not include any directory names in library.

An error in form does not undo the load, but does prevent execution of the rest of form.

In general, well-designed Lisp programs should not use this feature. The clean and modular ways to interact with a Lisp library are (1) examine and set the library's variables (those which are meant for outside use), and (2) call the library's functions. If you wish to do (1), you can do it immediately--there is no need to wait for when the library is loaded. To do (2), you must load the library (preferably with require).

But it is OK to use eval-after-load in your personal customizations if you don't feel they must meet the design standards for programs meant for wider use.

Variable: after-load-alist
This variable holds an alist of expressions to evaluate if and when particular libraries are loaded. Each element looks like this:
(filename forms...)
The function load checks after-load-alist in order to implement eval-after-load.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16. Byte Compilation

Emacs Lisp has a compiler that translates functions written in Lisp into a special representation called byte-code that can be executed more efficiently. The compiler replaces Lisp function definitions with byte-code. When a byte-code function is called, its definition is evaluated by the byte-code interpreter.

Because the byte-compiled code is evaluated by the byte-code interpreter, instead of being executed directly by the machine's hardware (as true compiled code is), byte-code is completely transportable from machine to machine without recompilation. It is not, however, as fast as true compiled code.

Compiling a Lisp file with the Emacs byte compiler always reads the file as multibyte text, even if Emacs was started with `--unibyte', unless the file specifies otherwise. This is so that compilation gives results compatible with running the same file without compilation. See section 15.3 Loading Non-ASCII Characters.

In general, any version of Emacs can run byte-compiled code produced by recent earlier versions of Emacs, but the reverse is not true. A major incompatible change was introduced in Emacs version 19.29, and files compiled with versions since that one will definitely not run in earlier versions unless you specify a special option. In addition, the modifier bits in keyboard characters were renumbered in Emacs 19.29; as a result, files compiled in versions before 19.29 will not work in subsequent versions if they contain character constants with modifier bits.

See section 18.4 Debugging Problems in Compilation, for how to investigate errors occurring in byte compilation.

16.1 Performance of Byte-Compiled Code

An example of speedup from byte compilation.

16.2 The Compilation Functions

Byte compilation functions.

16.3 Documentation Strings and Compilation

Dynamic loading of documentation strings.

16.4 Dynamic Loading of Individual Functions

Dynamic loading of individual functions.

16.5 Evaluation During Compilation

Code to be evaluated when you compile.

16.6 Byte-Code Function Objects

The data type used for byte-compiled functions.

16.7 Disassembled Byte-Code

Disassembling byte-code; how to read byte-code.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.1 Performance of Byte-Compiled Code

A byte-compiled function is not as efficient as a primitive function written in C, but runs much faster than the version written in Lisp. Here is an example:
(defun silly-loop (n)
  "Return time before and after N iterations of a loop."
  (let ((t1 (current-time-string)))
    (while (> (setq n (1- n))
              0))
    (list t1 (current-time-string))))
=> silly-loop

(silly-loop 100000)
=> ("Fri Mar 18 17:25:57 1994"
    "Fri Mar 18 17:26:28 1994")  ; 31 seconds

(byte-compile 'silly-loop)
=> [Compiled code not shown]

(silly-loop 100000)
=> ("Fri Mar 18 17:26:52 1994"
    "Fri Mar 18 17:26:58 1994")  ; 6 seconds
In this example, the interpreted code required 31 seconds to run, whereas the byte-compiled code required 6 seconds. These results are representative, but actual results will vary greatly.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.2 The Compilation Functions

You can byte-compile an individual function or macro definition with the byte-compile function. You can compile a whole file with byte-compile-file, or several files with byte-recompile-directory or batch-byte-compile.

The byte compiler produces error messages and warnings about each file in a buffer called `*Compile-Log*'. These report things in your program that suggest a problem but are not necessarily erroneous.

Be careful when writing macro calls in files that you may someday byte-compile. Macro calls are expanded when they are compiled, so the macros must already be defined for proper compilation. For more details, see 13.3 Macros and Byte Compilation. If a program does not work the same way when compiled as it does when interpreted, erroneous macro definitions are one likely cause (see section 13.6 Common Problems Using Macros).

Normally, compiling a file does not evaluate the file's contents or load the file. But it does execute any require calls at top level in the file. One way to ensure that necessary macro definitions are available during compilation is to require the file that defines them (see section 15.6 Features). To avoid loading the macro definition files when someone runs the compiled program, write eval-when-compile around the require calls (see section 16.5 Evaluation During Compilation).

Function: byte-compile symbol
This function byte-compiles the function definition of symbol, replacing the previous definition with the compiled one. The function definition of symbol must be the actual code for the function; i.e., the compiler does not follow indirection to another symbol. byte-compile returns the new, compiled definition of symbol.

If symbol's definition is a byte-code function object, byte-compile does nothing and returns nil. Lisp records only one function definition for any symbol, and if that is already compiled, non-compiled code is not available anywhere. So there is no way to "compile the same definition again."
(defun factorial (integer)
  "Compute factorial of INTEGER."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
=> factorial

(byte-compile 'factorial)
=>
#[(integer)
  "^H\301U\203^H^@\301\207\302^H\303^HS!\"\207"
  [integer 1 * factorial]
  4 "Compute factorial of INTEGER."]
The result is a byte-code function object. The string it contains is the actual byte-code; each character in it is an instruction or an operand of an instruction. The vector contains all the constants, variable names and function names used by the function, except for certain primitives that are coded as special instructions.

Command: compile-defun
This command reads the defun containing point, compiles it, and evaluates the result. If you use this on a defun that is actually a function definition, the effect is to install a compiled version of that function.

Command: byte-compile-file filename
This function compiles a file of Lisp code named filename into a file of byte-code. The output file's name is made by changing the `.el' suffix into `.elc'; if filename does not end in `.el', it adds `.elc' to the end of filename.

Compilation works by reading the input file one form at a time. If it is a definition of a function or macro, the compiled function or macro definition is written out. Other forms are batched together, then each batch is compiled, and written so that its compiled code will be executed when the file is read. All comments are discarded when the input file is read.

This command returns t. When called interactively, it prompts for the file name.
% ls -l push*
-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el

(byte-compile-file "~/emacs/push.el")
     => t

% ls -l push*
-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
-rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc
Command: byte-recompile-directory directory flag
This function recompiles every `.el' file in directory that needs recompilation. A file needs recompilation if a `.elc' file exists but is older than the `.el' file.

When a `.el' file has no corresponding `.elc' file, flag says what to do. If it is nil, these files are ignored. If it is non-nil, the user is asked whether to compile each such file.

The returned value of this command is unpredictable.

Function: batch-byte-compile
This function runs byte-compile-file on files specified on the command line. This function must be used only in a batch execution of Emacs, as it kills Emacs on completion. An error in one file does not prevent processing of subsequent files, but no output file will be generated for it, and the Emacs process will terminate with a nonzero status code.
% emacs -batch -f batch-byte-compile *.el
Function: byte-code code-string data-vector max-stack
This function actually interprets byte-code. A byte-compiled function is actually defined with a body that calls byte-code. Don't call this function yourself--only the byte compiler knows how to generate valid calls to this function.

In Emacs version 18, byte-code was always executed by way of a call to the function byte-code. Nowadays, byte-code is usually executed as part of a byte-code function object, and only rarely through an explicit call to byte-code.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.3 Documentation Strings and Compilation

Functions and variables loaded from a byte-compiled file access their documentation strings dynamically from the file whenever needed. This saves space within Emacs, and makes loading faster because the documentation strings themselves need not be processed while loading the file. Actual access to the documentation strings becomes slower as a result, but this normally is not enough to bother users.

Dynamic access to documentation strings does have drawbacks:

If you delete or move the compiled file after loading it, Emacs can no longer access the documentation strings for the functions and variables in the file.

If you alter the compiled file (such as by compiling a new version), then further access to documentation strings in this file will give nonsense results.

If your site installs Emacs following the usual procedures, these problems will never normally occur. Installing a new version uses a new directory with a different name; as long as the old version remains installed, its files will remain unmodified in the places where they are expected to be.

However, if you have built Emacs yourself and use it from the directory where you built it, you will experience this problem occasionally if you edit and recompile Lisp files. When it happens, you can cure the problem by reloading the file after recompiling it.

Byte-compiled files made with recent versions of Emacs (since 19.29) will not load into older versions because the older versions don't support this feature. You can turn off this feature at compile time by setting byte-compile-dynamic-docstrings to nil; then you can compile files that will load into older Emacs versions. You can do this globally, or for one source file by specifying a file-local binding for the variable. One way to do that is by adding this string to the file's first line:
-*-byte-compile-dynamic-docstrings: nil;-*-
Variable: byte-compile-dynamic-docstrings
If this is non-nil, the byte compiler generates compiled files that are set up for dynamic loading of documentation strings.

The dynamic documentation string feature writes compiled files that use a special Lisp reader construct, `#@count'. This construct skips the next count characters. It also uses the `#$' construct, which stands for "the name of this file, as a string." It is usually best not to use these constructs in Lisp source files, since they are not designed to be clear to humans reading the file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.4 Dynamic Loading of Individual Functions

When you compile a file, you can optionally enable the dynamic function loading feature (also known as lazy loading). With dynamic function loading, loading the file doesn't fully read the function definitions in the file. Instead, each function definition contains a place-holder which refers to the file. The first time each function is called, it reads the full definition from the file, to replace the place-holder.

The advantage of dynamic function loading is that loading the file becomes much faster. This is a good thing for a file which contains many separate user-callable functions, if using one of them does not imply you will probably also use the rest. A specialized mode which provides many keyboard commands often has that usage pattern: a user may invoke the mode, but use only a few of the commands it provides.

The dynamic loading feature has certain disadvantages:

If you delete or move the compiled file after loading it, Emacs can no longer load the remaining function definitions not already loaded.

If you alter the compiled file (such as by compiling a new version), then trying to load any function not already loaded will yield nonsense results.

These problems will never happen in normal circumstances with installed Emacs files. But they are quite likely to happen with Lisp files that you are changing. The easiest way to prevent these problems is to reload the new compiled file immediately after each recompilation.

The byte compiler uses the dynamic function loading feature if the variable byte-compile-dynamic is non-nil at compilation time. Do not set this variable globally, since dynamic loading is desirable only for certain files. Instead, enable the feature for specific source files with file-local variable bindings. For example, you could do it by writing this text in the source file's first line:
-*-byte-compile-dynamic: t;-*-
Variable: byte-compile-dynamic
If this is non-nil, the byte compiler generates compiled files that are set up for dynamic function loading.

Function: fetch-bytecode function
This immediately finishes loading the definition of function from its byte-compiled file, if it is not fully loaded already. The argument function may be a byte-code function object or a function name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.5 Evaluation During Compilation

These features permit you to write code to be evaluated during compilation of a program.

Special Form: eval-and-compile body
This form marks body to be evaluated both when you compile the containing code and when you run it (whether compiled or not).

You can get a similar result by putting body in a separate file and referring to that file with require. That method is preferable when body is large.

Special Form: eval-when-compile body
This form marks body to be evaluated at compile time but not when the compiled program is loaded. The result of evaluation by the compiler becomes a constant which appears in the compiled program. If you load the source file, rather than compiling it, body is evaluated normally.

Common Lisp Note: At top level, this is analogous to the Common Lisp idiom (eval-when (compile eval) ...). Elsewhere, the Common Lisp `#.' reader macro (but not when interpreting) is closer to what eval-when-compile does.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.6 Byte-Code Function Objects

Byte-compiled functions have a special data type: they are byte-code function objects.

Internally, a byte-code function object is much like a vector; however, the evaluator handles this data type specially when it appears as a function to be called. The printed representation for a byte-code function object is like that for a vector, with an additional `#' before the opening `['.

A byte-code function object must have at least four elements; there is no maximum number, but only the first six elements have any normal use. They are:

arglist
The list of argument symbols.

byte-code
The string containing the byte-code instructions.

constants
The vector of Lisp objects referenced by the byte code. These include symbols used as function names and variable names.

stacksize
The maximum stack size this function needs.

docstring
The documentation string (if any); otherwise, nil. The value may be a number or a list, in case the documentation string is stored in a file. Use the function documentation to get the real documentation string (see section 24.2 Access to Documentation Strings).

interactive
The interactive spec (if any). This can be a string or a Lisp expression. It is nil for a function that isn't interactive.
Here's an example of a byte-code function object, in printed representation. It is the definition of the command backward-sexp.
#[(&optional arg)
  "^H\204^F^@\301^P\302^H[!\207"
  [arg 1 forward-sexp]
  2
  254435
  "p"]
The primitive way to create a byte-code object is with make-byte-code:

Function: make-byte-code &rest elements
This function constructs and returns a byte-code function object with elements as its elements.

You should not try to come up with the elements for a byte-code function yourself, because if they are inconsistent, Emacs may crash when you call the function. Always leave it to the byte compiler to create these objects; it makes the elements consistent (we hope).

You can access the elements of a byte-code object using aref; you can also use vconcat to create a vector with the same elements.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.7 Disassembled Byte-Code

People do not write byte-code; that job is left to the byte compiler. But we provide a disassembler to satisfy a cat-like curiosity. The disassembler converts the byte-compiled code into humanly readable form.

The byte-code interpreter is implemented as a simple stack machine. It pushes values onto a stack of its own, then pops them off to use them in calculations whose results are themselves pushed back on the stack. When a byte-code function returns, it pops a value off the stack and returns it as the value of the function.

In addition to the stack, byte-code functions can use, bind, and set ordinary Lisp variables, by transferring values between variables and the stack.

Command: disassemble object &optional stream
This function prints the disassembled code for object. If stream is supplied, then output goes there. Otherwise, the disassembled code is printed to the stream standard-output. The argument object can be a function name or a lambda expression.

As a special exception, if this function is used interactively, it outputs to a buffer named `*Disassemble*'.

Here are two examples of using the disassemble function. We have added explanatory comments to help you relate the byte-code to the Lisp source; these do not appear in the output of disassemble. These examples show unoptimized byte-code. Nowadays byte-code is usually optimized, but we did not want to rewrite these examples, since they still serve their purpose.
(defun factorial (integer)
  "Compute factorial of an integer."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
     => factorial

(factorial 4)
     => 24

(disassemble 'factorial)
     -| byte-code for factorial:
 doc: Compute factorial of an integer.
 args: (integer)

0   constant 1              ; Push 1 onto stack.

1   varref   integer        ; Get value of integer
                            ;   from the environment
                            ;   and push the value
                            ;   onto the stack.

2   eqlsign                 ; Pop top two values off stack,
                            ;   compare them,
                            ;   and push result onto stack.

3   goto-if-nil 10          ; Pop and test top of stack;
                            ;   if nil, go to 10,
                            ;   else continue.

6   constant 1              ; Push 1 onto top of stack.

7   goto     17             ; Go to 17 (in this case, 1 will be
                            ;   returned by the function).

10  constant *              ; Push symbol * onto stack.

11  varref   integer        ; Push value of integer onto stack.

12  constant factorial      ; Push factorial onto stack.

13  varref   integer        ; Push value of integer onto stack.

14  sub1                    ; Pop integer, decrement value,
                            ;   push new value onto stack.

                            ; Stack now contains:
                            ;   - decremented value of integer
                            ;   - factorial
                            ;   - value of integer
                            ;   - *

15  call     1              ; Call function factorial using
                            ;   the first (i.e., the top) element
                            ;   of the stack as the argument;
                            ;   push returned value onto stack.

                            ; Stack now contains:
                            ;   - result of recursive
                            ;        call to factorial
                            ;   - value of integer
                            ;   - *

16  call     2              ; Using the first two
                            ;   (i.e., the top two)
                            ;   elements of the stack
                            ;   as arguments,
                            ;   call the function *,
                            ;   pushing the result onto the stack.

17  return                  ; Return the top element
                            ;   of the stack.
     => nil
The silly-loop function is somewhat more complex:
(defun silly-loop (n)
  "Return time before and after N iterations of a loop."
  (let ((t1 (current-time-string)))
    (while (> (setq n (1- n))
              0))
    (list t1 (current-time-string))))
     => silly-loop

(disassemble 'silly-loop)
     -| byte-code for silly-loop:
 doc: Return time before and after N iterations of a loop.
 args: (n)

0   constant current-time-string  ; Push
                                  ;   current-time-string
                                  ;   onto top of stack.

1   call     0              ; Call current-time-string
                            ;    with no argument,
                            ;    pushing result onto stack.

2   varbind  t1             ; Pop stack and bind t1
                            ;   to popped value.

3   varref   n              ; Get value of n from
                            ;   the environment and push
                            ;   the value onto the stack.

4   sub1                    ; Subtract 1 from top of stack.

5   dup                     ; Duplicate the top of the stack;
                            ;   i.e., copy the top of
                            ;   the stack and push the
                            ;   copy onto the stack.

6   varset   n              ; Pop the top of the stack,
                            ;   and bind n to the value.

                            ; In effect, the sequence dup varset
                            ;   copies the top of the stack
                            ;   into the value of n
                            ;   without popping it.

7   constant 0              ; Push 0 onto stack.

8   gtr                     ; Pop top two values off stack,
                            ;   test if n is greater than 0
                            ;   and push result onto stack.

9   goto-if-nil-else-pop 17 ; Goto 17 if n <= 0
                            ;   (this exits the while loop).
                            ;   else pop top of stack
                            ;   and continue

12  constant nil            ; Push nil onto stack
                            ;   (this is the body of the loop).

13  discard                 ; Discard result of the body
                            ;   of the loop (a while loop
                            ;   is always evaluated for
                            ;   its side effects).

14  goto     3              ; Jump back to beginning
                            ;   of while loop.

17  discard                 ; Discard result of while loop
                            ;   by popping top of stack.
                            ;   This result is the value nil that
                            ;   was not popped by the goto at 9.

18  varref   t1             ; Push value of t1 onto stack.

19  constant current-time-string  ; Push
                                  ;   current-time-string
                                  ;   onto top of stack.

20  call     0              ; Call current-time-string again.

21  list2                   ; Pop top two elements off stack,
                            ;   create a list of them,
                            ;   and push list onto stack.

22  unbind   1              ; Unbind t1 in local environment.

23  return                  ; Return value of the top of stack.

     => nil
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17. Advising Emacs Lisp Functions

The advice feature lets you add to the existing definition of a function, by advising the function. This is a clean method for a library to customize functions defined by other parts of Emacs--cleaner than redefining the whole function.

Each function can have multiple pieces of advice, separately defined. Each defined piece of advice can be enabled or disabled explicitly. All the enabled pieces of advice for any given function actually take effect when you activate advice for that function, or when you define or redefine the function. Note that enabling a piece of advice and activating advice for a function are not the same thing.

Usage Note: Advice is useful for altering the behavior of existing calls to an existing function. If you want the new behavior for new calls, or for key bindings, it is cleaner to define a new function (or a new command) which uses the existing function.

17.1 A Simple Advice Example

A simple example to explain the basics of advice.

17.2 Defining Advice

Detailed description of defadvice.

17.3 Around-Advice

Wrapping advice around a function's definition.

17.4 Computed Advice

...is to defadvice as fset is to defun.

17.5 Activation of Advice

Advice doesn't do anything until you activate it.

17.6 Enabling and Disabling Advice

You can enable or disable each piece of advice.

17.7 Preactivation

Preactivation is a way of speeding up the loading of compiled advice.

17.8 Argument Access in Advice

How advice can access the function's arguments.

17.9 Definition of Subr Argument Lists

Accessing arguments when advising a primitive.

17.10 The Combined Definition

How advice is implemented.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.1 A Simple Advice Example

The command next-line moves point down vertically one or more lines; it is the standard binding of C-n. When used on the last line of the buffer, this command inserts a newline to create a line to move to if next-line-add-newlines is non-nil (its default is nil.)

Suppose you wanted to add a similar feature to previous-line, which would insert a new line at the beginning of the buffer for the command to move to. How could you do this?

You could do it by redefining the whole function, but that is not modular. The advice feature provides a cleaner alternative: you can effectively add your code to the existing function definition, without actually changing or even seeing that definition. Here is how to do this:
(defadvice previous-line (before next-line-at-end (arg))
  "Insert an empty line when moving up from the top line."
  (if (and next-line-add-newlines (= arg 1)
           (save-excursion (beginning-of-line) (bobp)))
      (progn
        (beginning-of-line)
        (newline))))
This expression defines a piece of advice for the function previous-line. This piece of advice is named next-line-at-end, and the symbol before says that it is before-advice which should run before the regular definition of previous-line. (arg) specifies how the advice code can refer to the function's arguments.

When this piece of advice runs, it creates an additional line, in the situation where that is appropriate, but does not move point to that line. This is the correct way to write the advice, because the normal definition will run afterward and will move back to the newly inserted line.

Defining the advice doesn't immediately change the function previous-line. That happens when you activate the advice, like this:
(ad-activate 'previous-line)
This is what actually begins to use the advice that has been defined so far for the function previous-line. Henceforth, whenever that function is run, whether invoked by the user with C-p or M-x, or called from Lisp, it runs the advice first, and its regular definition second.

This example illustrates before-advice, which is one class of advice: it runs before the function's base definition. There are two other advice classes: after-advice, which runs after the base definition, and around-advice, which lets you specify an expression to wrap around the invocation of the base definition.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.2 Defining Advice

To define a piece of advice, use the macro defadvice. A call to defadvice has the following syntax, which is based on the syntax of defun and defmacro, but adds more:
(defadvice function (class name
                         [position] [arglist]
                         flags...)
  [documentation-string]
  [interactive-form]
  body-forms...)
Here, function is the name of the function (or macro or special form) to be advised. From now on, we will write just "function" when describing the entity being advised, but this always includes macros and special forms.

class specifies the class of the advice--one of before, after, or around. Before-advice runs before the function itself; after-advice runs after the function itself; around-advice is wrapped around the execution of the function itself. After-advice and around-advice can override the return value by setting ad-return-value.

Variable: ad-return-value
While advice is executing, after the function's original definition has been executed, this variable holds its return value, which will ultimately be returned to the caller after finishing all the advice. After-advice and around-advice can arrange to return some other value by storing it in this variable.

The argument name is the name of the advice, a non-nil symbol. The advice name uniquely identifies one piece of advice, within all the pieces of advice in a particular class for a particular function. The name allows you to refer to the piece of advice--to redefine it, or to enable or disable it.

In place of the argument list in an ordinary definition, an advice definition calls for several different pieces of information.

The optional position specifies where, in the current list of advice of the specified class, this new advice should be placed. It should be either first, last or a number that specifies a zero-based position (first is equivalent to 0). If no position is specified, the default is first. Position values outside the range of existing positions in this class are mapped to the beginning or the end of the range, whichever is closer. The position value is ignored when redefining an existing piece of advice.

The optional arglist can be used to define the argument list for the sake of advice. This becomes the argument list of the combined definition that is generated in order to run the advice (see section 17.10 The Combined Definition). Therefore, the advice expressions can use the argument variables in this list to access argument values.

The argument list used in advice need not be the same as the argument list used in the original function, but must be compatible with it, so that it can handle the ways the function is actually called. If two pieces of advice for a function both specify an argument list, they must specify the same argument list.

See section 17.8 Argument Access in Advice, for more information about argument lists and advice, and a more flexible way for advice to access the arguments.

The remaining elements, flags, are symbols that specify further information about how to use this piece of advice. Here are the valid symbols and their meanings:

activate
Activate the advice for function now. Changes in a function's advice always take effect the next time you activate advice for the function; this flag says to do so, for function, immediately after defining this piece of advice.
This flag has no immediate effect if function itself is not defined yet (a situation known as forward advice), because it is impossible to activate an undefined function's advice. However, defining function will automatically activate its advice.

protect
Protect this piece of advice against non-local exits and errors in preceding code and advice. Protecting advice places it as a cleanup in an unwind-protect form, so that it will execute even if the previous code gets an error or uses throw. See section 10.5.4 Cleaning Up from Nonlocal Exits.

compile
Compile the combined definition that is used to run the advice. This flag is ignored unless activate is also specified. See section 17.10 The Combined Definition.

disable
Initially disable this piece of advice, so that it will not be used unless subsequently explicitly enabled. See section 17.6 Enabling and Disabling Advice.

preactivate
Activate advice for function when this defadvice is compiled or macroexpanded. This generates a compiled advised definition according to the current advice state, which will be used during activation if appropriate. See section 17.7 Preactivation.
This is useful only if this defadvice is byte-compiled.
The optional documentation-string serves to document this piece of advice. When advice is active for function, the documentation for function (as returned by documentation) combines the documentation strings of all the advice for function with the documentation string of its original function definition.

The optional interactive-form form can be supplied to change the interactive behavior of the original function. If more than one piece of advice has an interactive-form, then the first one (the one with the smallest position) found among all the advice takes precedence.

The possibly empty list of body-forms specifies the body of the advice. The body of an advice can access or change the arguments, the return value, the binding environment, and perform any other kind of side effect.

Warning: When you advise a macro, keep in mind that macros are expanded when a program is compiled, not when a compiled program is run. All subroutines used by the advice need to be available when the byte compiler expands the macro.

Command: ad-unadvise function
This command deletes the advice from function.

Command: ad-unadvise-all
This command deletes all pieces of advice from all functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.3 Around-Advice

Around-advice lets you "wrap" a Lisp expression "around" the original function definition. You specify where the original function definition should go by means of the special symbol ad-do-it. Where this symbol occurs inside the around-advice body, it is replaced with a progn containing the forms of the surrounded code. Here is an example:
(defadvice foo (around foo-around)
  "Ignore case in `foo'."
  (let ((case-fold-search t))
    ad-do-it))
Its effect is to make sure that case is ignored in searches when the original definition of foo is run.

Variable: ad-do-it
This is not really a variable, but it is somewhat used like one in around-advice. It specifies the place to run the function's original definition and other "earlier" around-advice.

If the around-advice does not use ad-do-it, then it does not run the original function definition. This provides a way to override the original definition completely. (It also overrides lower-positioned pieces of around-advice).

If the around-advice uses ad-do-it more than once, the original definition is run at each place. In this way, around-advice can execute the original definition (and lower-positioned pieces of around-advice) several times. Another way to do that is by using ad-do-it inside of a loop.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.4 Computed Advice

The macro defadvice resembles defun in that the code for the advice, and all other information about it, are explicitly stated in the source code. You can also create advice whose details are computed, using the function ad-add-advice.

Function: ad-add-advice function advice class position
Calling ad-add-advice adds advice as a piece of advice to function in class class. The argument advice has this form:
(name protected enabled definition)
Here protected and enabled are flags, and definition is the expression that says what the advice should do. If enabled is nil, this piece of advice is initially disabled (see section 17.6 Enabling and Disabling Advice).

If function already has one or more pieces of advice in the specified class, then position specifies where in the list to put the new piece of advice. The value of position can either be first, last, or a number (counting from 0 at the beginning of the list). Numbers outside the range are mapped to the beginning or the end of the range, whichever is closer. The position value is ignored when redefining an existing piece of advice.

If function already has a piece of advice with the same name, then the position argument is ignored and the old advice is replaced with the new one.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.5 Activation of Advice

By default, advice does not take effect when you define it--only when you activate advice for the function that was advised. You can request the activation of advice for a function when you define the advice, by specifying the activate flag in the defadvice. But normally you activate the advice for a function by calling the function ad-activate or one of the other activation commands listed below.

Separating the activation of advice from the act of defining it permits you to add several pieces of advice to one function efficiently, without redefining the function over and over as each advice is added. More importantly, it permits defining advice for a function before that function is actually defined.

When a function's advice is first activated, the function's original definition is saved, and all enabled pieces of advice for that function are combined with the original definition to make a new definition. (Pieces of advice that are currently disabled are not used; see 17.6 Enabling and Disabling Advice.) This definition is installed, and optionally byte-compiled as well, depending on conditions described below.

In all of the commands to activate advice, if compile is t, the command also compiles the combined definition which implements the advice.

Command: ad-activate function &optional compile
This command activates all the advice defined for function.

To activate advice for a function whose advice is already active is not a no-op. It is a useful operation which puts into effect any changes in that function's advice since the previous activation of advice for that function.

Command: ad-deactivate function
This command deactivates the advice for function.

Command: ad-update function &optional compile
This command activates the advice for function if its advice is already activated. This is useful if you change the advice.

Command: ad-activate-all &optional compile
This command activates the advice for all functions.

Command: ad-deactivate-all
This command deactivates the advice for all functions.

Command: ad-update-all &optional compile
This command activates the advice for all functions whose advice is already activated. This is useful if you change the advice of some functions.

Command: ad-activate-regexp regexp &optional compile
This command activates all pieces of advice whose names match regexp. More precisely, it activates all advice for any function which has at least one piece of advice that matches regexp.

Command: ad-deactivate-regexp regexp
This command deactivates all pieces of advice whose names match regexp. More precisely, it deactivates all advice for any function which has at least one piece of advice that matches regexp.

Command: ad-update-regexp regexp &optional compile
This command activates pieces of advice whose names match regexp, but only those for functions whose advice is already activated.

Reactivating a function's advice is useful for putting into effect all the changes that have been made in its advice (including enabling and disabling specific pieces of advice; see section 17.6 Enabling and Disabling Advice) since the last time it was activated.

Command: ad-start-advice
Turn on automatic advice activation when a function is defined or redefined. If you turn on this mode, then advice takes effect immediately when defined.

Command: ad-stop-advice
Turn off automatic advice activation when a function is defined or redefined.

User Option: ad-default-compilation-action
This variable controls whether to compile the combined definition that results from activating advice for a function.

A value of always specifies to compile unconditionally. A value of nil specifies never compile the advice.

A value of maybe specifies to compile if the byte-compiler is already loaded. A value of like-original specifies to compile the advice if the original definition of the advised function is compiled or a built-in function.

This variable takes effect only if the compile argument of ad-activate (or any of the above functions) was supplied as nil. If that argument is non-nil, that means to compile the advice regardless.

If the advised definition was constructed during "preactivation" (see section 17.7 Preactivation), then that definition must already be compiled, because it was constructed during byte-compilation of the file that contained the defadvice with the preactivate flag.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.6 Enabling and Disabling Advice

Each piece of advice has a flag that says whether it is enabled or not. By enabling or disabling a piece of advice, you can turn it on and off without having to undefine and redefine it. For example, here is how to disable a particular piece of advice named my-advice for the function foo:
(ad-disable-advice 'foo 'before 'my-advice)
This function by itself only changes the enable flag for a piece of advice. To make the change take effect in the advised definition, you must activate the advice for foo again:
(ad-activate 'foo)
Command: ad-disable-advice function class name
This command disables the piece of advice named name in class class on function.

Command: ad-enable-advice function class name
This command enables the piece of advice named name in class class on function.

You can also disable many pieces of advice at once, for various functions, using a regular expression. As always, the changes take real effect only when you next reactivate advice for the functions in question.

Command: ad-disable-regexp regexp
This command disables all pieces of advice whose names match regexp, in all classes, on all functions.

Command: ad-enable-regexp regexp
This command enables all pieces of advice whose names match regexp, in all classes, on all functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.7 Preactivation

Constructing a combined definition to execute advice is moderately expensive. When a library advises many functions, this can make loading the library slow. In that case, you can use preactivation to construct suitable combined definitions in advance.

To use preactivation, specify the preactivate flag when you define the advice with defadvice. This defadvice call creates a combined definition which embodies this piece of advice (whether enabled or not) plus any other currently enabled advice for the same function, and the function's own definition. If the defadvice is compiled, that compiles the combined definition also.

When the function's advice is subsequently activated, if the enabled advice for the function matches what was used to make this combined definition, then the existing combined definition is used, thus avoiding the need to construct one. Thus, preactivation never causes wrong results--but it may fail to do any good, if the enabled advice at the time of activation doesn't match what was used for preactivation.

Here are some symptoms that can indicate that a preactivation did not work properly, because of a mismatch.

Activation of the advised function takes longer than usual.
The byte-compiler gets loaded while an advised function gets activated.
byte-compile is included in the value of features even though you did not ever explicitly use the byte-compiler.

Compiled preactivated advice works properly even if the function itself is not defined until later; however, the function needs to be defined when you compile the preactivated advice.

There is no elegant way to find out why preactivated advice is not being used. What you can do is to trace the function ad-cache-id-verification-code (with the function trace-function-background) before the advised function's advice is activated. After activation, check the value returned by ad-cache-id-verification-code for that function: verified means that the preactivated advice was used, while other values give some information about why they were considered inappropriate.

Warning: There is one known case that can make preactivation fail, in that a preconstructed combined definition is used even though it fails to match the current state of advice. This can happen when two packages define different pieces of advice with the same name, in the same class, for the same function. But you should avoid that anyway.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.8 Argument Access in Advice

The simplest way to access the arguments of an advised function in the body of a piece of advice is to use the same names that the function definition uses. To do this, you need to know the names of the argument variables of the original function.

While this simple method is sufficient in many cases, it has a disadvantage: it is not robust, because it hard-codes the argument names into the advice. If the definition of the original function changes, the advice might break.

Another method is to specify an argument list in the advice itself. This avoids the need to know the original function definition's argument names, but it has a limitation: all the advice on any particular function must use the same argument list, because the argument list actually used for all the advice comes from the first piece of advice for that function.

A more robust method is to use macros that are translated into the proper access forms at activation time, i.e., when constructing the advised definition. Access macros access actual arguments by position regardless of how these actual arguments get distributed onto the argument variables of a function. This is robust because in Emacs Lisp the meaning of an argument is strictly determined by its position in the argument list.

Macro: ad-get-arg position
This returns the actual argument that was supplied at position.

Macro: ad-get-args position
This returns the list of actual arguments supplied starting at position.

Macro: ad-set-arg position value
This sets the value of the actual argument at position to value

Macro: ad-set-args position value-list
This sets the list of actual arguments starting at position to value-list.

Now an example. Suppose the function foo is defined as
(defun foo (x y &optional z &rest r) ...)
and is then called with
(foo 0 1 2 3 4 5 6)
which means that x is 0, y is 1, z is 2 and r is (3 4 5 6) within the body of foo. Here is what ad-get-arg and ad-get-args return in this case:
(ad-get-arg 0) => 0
(ad-get-arg 1) => 1
(ad-get-arg 2) => 2
(ad-get-arg 3) => 3
(ad-get-args 2) => (2 3 4 5 6)
(ad-get-args 4) => (4 5 6)
Setting arguments also makes sense in this example:
(ad-set-arg 5 "five")
has the effect of changing the sixth argument to "five". If this happens in advice executed before the body of foo is run, then r will be (3 4 "five" 6) within that body.

Here is an example of setting a tail of the argument list:
(ad-set-args 0 '(5 4 3 2 1 0))
If this happens in advice executed before the body of foo is run, then within that body, x will be 5, y will be 4, z will be 3, and r will be (2 1 0) inside the body of foo.

These argument constructs are not really implemented as Lisp macros. Instead they are implemented specially by the advice mechanism.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.9 Definition of Subr Argument Lists

When the advice facility constructs the combined definition, it needs to know the argument list of the original function. This is not always possible for primitive functions. When advice cannot determine the argument list, it uses (&rest ad-subr-args), which always works but is inefficient because it constructs a list of the argument values. You can use ad-define-subr-args to declare the proper argument names for a primitive function:

Function: ad-define-subr-args function arglist
This function specifies that arglist should be used as the argument list for function function.

For example,
(ad-define-subr-args 'fset '(sym newdef))
specifies the argument list for the function fset.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

17.10 The Combined Definition

Suppose that a function has n pieces of before-advice (numbered from 0 through n-1), m pieces of around-advice and k pieces of after-advice. Assuming no piece of advice is protected, the combined definition produced to implement the advice for a function looks like this:
(lambda arglist
  [ [advised-docstring] [(interactive ...)] ]
  (let (ad-return-value)
    before-0-body-form...
         ....
    before-n-1-body-form...
    around-0-body-form...
       around-1-body-form...
             ....
          around-m-1-body-form...
             (setq ad-return-value
                   apply original definition to arglist)
          end-of-around-m-1-body-form...
             ....
       end-of-around-1-body-form...
    end-of-around-0-body-form...
    after-0-body-form...
          ....
    after-k-1-body-form...
    ad-return-value))
Macros are redefined as macros, which means adding macro to the beginning of the combined definition.

The interactive form is present if the original function or some piece of advice specifies one. When an interactive primitive function is advised, advice uses a special method: it calls the primitive with call-interactively so that it will read its own arguments. In this case, the advice cannot access the arguments.

The body forms of the various advice in each class are assembled according to their specified order. The forms of around-advice l are included in one of the forms of around-advice l - 1.

The innermost part of the around advice onion is
apply original definition to arglist
whose form depends on the type of the original function. The variable ad-return-value is set to whatever this returns. The variable is visible to all pieces of advice, which can access and modify it before it is actually returned from the advised function.

The semantic structure of advised functions that contain protected pieces of advice is the same. The only difference is that unwind-protect forms ensure that the protected advice gets executed even if some previous piece of advice had an error or a non-local exit. If any around-advice is protected, then the whole around-advice onion is protected as a result.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18. Debugging Lisp Programs

There are three ways to investigate a problem in an Emacs Lisp program, depending on what you are doing with the program when the problem appears.

If the problem occurs when you run the program, you can use a Lisp debugger to investigate what is happening during execution. In addition to the ordinary debugger, Emacs comes with a source level debugger, Edebug. This chapter describes both of them.

If the problem is syntactic, so that Lisp cannot even read the program, you can use the Emacs facilities for editing Lisp to localize it.

If the problem occurs when trying to compile the program with the byte compiler, you need to know how to examine the compiler's input buffer.

18.1 The Lisp Debugger

How the Emacs Lisp debugger is implemented.

18.2 Edebug

A source-level Emacs Lisp debugger.

18.3 Debugging Invalid Lisp Syntax

How to find syntax errors.

18.4 Debugging Problems in Compilation

How to find errors that show up in byte compilation.

Another useful debugging tool is the dribble file. When a dribble file is open, Emacs copies all keyboard input characters to that file. Afterward, you can examine the file to find out what input was used. See section 40.8 Terminal Input.

For debugging problems in terminal descriptions, the open-termscript function can be useful. See section 40.9 Terminal Output.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1 The Lisp Debugger

The ordinary Lisp debugger provides the ability to suspend evaluation of a form. While evaluation is suspended (a state that is commonly known as a break), you may examine the run time stack, examine the values of local or global variables, or change those values. Since a break is a recursive edit, all the usual editing facilities of Emacs are available; you can even run programs that will enter the debugger recursively. See section 21.12 Recursive Editing.

18.1.1 Entering the Debugger on an Error

Entering the debugger when an error happens.

18.1.2 Debugging Infinite Loops

Stopping and debugging a program that doesn't exit.

18.1.3 Entering the Debugger on a Function Call

Entering it when a certain function is called.

18.1.4 Explicit Entry to the Debugger

Entering it at a certain point in the program.

18.1.5 Using the Debugger

What the debugger does; what you see while in it.

18.1.6 Debugger Commands

Commands used while in the debugger.

18.1.7 Invoking the Debugger

How to call the function debug.

18.1.8 Internals of the Debugger

Subroutines of the debugger, and global variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1.1 Entering the Debugger on an Error

The most important time to enter the debugger is when a Lisp error happens. This allows you to investigate the immediate causes of the error.

However, entry to the debugger is not a normal consequence of an error. Many commands frequently cause Lisp errors when invoked inappropriately (such as C-f at the end of the buffer), and during ordinary editing it would be very inconvenient to enter the debugger each time this happens. So if you want errors to enter the debugger, set the variable debug-on-error to non-nil. (The command toggle-debug-on-error provides an easy way to do this.)

User Option: debug-on-error
This variable determines whether the debugger is called when an error is signaled and not handled. If debug-on-error is t, all kinds of errors call the debugger (except those listed in debug-ignored-errors). If it is nil, none call the debugger.

The value can also be a list of error conditions that should call the debugger. For example, if you set it to the list (void-variable), then only errors about a variable that has no value invoke the debugger.

When this variable is non-nil, Emacs does not create an error handler around process filter functions and sentinels. Therefore, errors in these functions also invoke the debugger. See section 37. Processes.

User Option: debug-ignored-errors
This variable specifies certain kinds of errors that should not enter the debugger. Its value is a list of error condition symbols and/or regular expressions. If the error has any of those condition symbols, or if the error message matches any of the regular expressions, then that error does not enter the debugger, regardless of the value of debug-on-error.

The normal value of this variable lists several errors that happen often during editing but rarely result from bugs in Lisp programs. However, "rarely" is not "never"; if your program fails with an error that matches this list, you will need to change this list in order to debug the error. The easiest way is usually to set debug-ignored-errors to nil.

User Option: debug-on-signal
Normally, errors that are caught by condition-case never run the debugger, even if debug-on-error is non-nil. In other words, condition-case gets a chance to handle the error before the debugger gets a chance.

If you set debug-on-signal to a non-nil value, then the debugger gets the first chance at every error; an error will invoke the debugger regardless of any condition-case, if it fits the criteria specified by the values of debug-on-error and debug-ignored-errors.

Warning: This variable is strong medicine! Various parts of Emacs handle errors in the normal course of affairs, and you may not even realize that errors happen there. If you set debug-on-signal to a non-nil value, those errors will enter the debugger.

Warning: debug-on-signal has no effect when debug-on-error is nil.

To debug an error that happens during loading of the init file, use the option `--debug-init'. This binds debug-on-error to t while loading the init file, and bypasses the condition-case which normally catches errors in the init file.

If your init file sets debug-on-error, the effect may not last past the end of loading the init file. (This is an undesirable byproduct of the code that implements the `--debug-init' command line option.) The best way to make the init file set debug-on-error permanently is with after-init-hook, like this:
(add-hook 'after-init-hook
          (lambda () (setq debug-on-error t)))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1.2 Debugging Infinite Loops

When a program loops infinitely and fails to return, your first problem is to stop the loop. On most operating systems, you can do this with C-g, which causes a quit.

Ordinary quitting gives no information about why the program was looping. To get more information, you can set the variable debug-on-quit to non-nil. Quitting with C-g is not considered an error, and debug-on-error has no effect on the handling of C-g. Likewise, debug-on-quit has no effect on errors.

Once you have the debugger running in the middle of the infinite loop, you can proceed from the debugger using the stepping commands. If you step through the entire loop, you will probably get enough information to solve the problem.

User Option: debug-on-quit
This variable determines whether the debugger is called when quit is signaled and not handled. If debug-on-quit is non-nil, then the debugger is called whenever you quit (that is, type C-g). If debug-on-quit is nil, then the debugger is not called when you quit. See section 21.10 Quitting.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1.3 Entering the Debugger on a Function Call

To investigate a problem that happens in the middle of a program, one useful technique is to enter the debugger whenever a certain function is called. You can do this to the function in which the problem occurs, and then step through the function, or you can do this to a function called shortly before the problem, step quickly over the call to that function, and then step through its caller.

Command: debug-on-entry function-name
This function requests function-name to invoke the debugger each time it is called. It works by inserting the form (debug 'debug) into the function definition as the first form.

Any function defined as Lisp code may be set to break on entry, regardless of whether it is interpreted code or compiled code. If the function is a command, it will enter the debugger when called from Lisp and when called interactively (after the reading of the arguments). You can't debug primitive functions (i.e., those written in C) this way.

When debug-on-entry is called interactively, it prompts for function-name in the minibuffer. If the function is already set up to invoke the debugger on entry, debug-on-entry does nothing. debug-on-entry always returns function-name.

Note: if you redefine a function after using debug-on-entry on it, the code to enter the debugger is discarded by the redefinition. In effect, redefining the function cancels the break-on-entry feature for that function.
(defun fact (n)
  (if (zerop n) 1
      (* n (fact (1- n)))))
     => fact
(debug-on-entry 'fact)
     => fact
(fact 3)

------ Buffer: *Backtrace* ------
Entering:
* fact(3)
  eval-region(4870 4878 t)
  byte-code("...")
  eval-last-sexp(nil)
  (let ...)
  eval-insert-last-sexp(nil)
* call-interactively(eval-insert-last-sexp)
------ Buffer: *Backtrace* ------

(symbol-function 'fact)
     => (lambda (n)
          (debug (quote debug))
          (if (zerop n) 1 (* n (fact (1- n)))))
Command: cancel-debug-on-entry function-name
This function undoes the effect of debug-on-entry on function-name. When called interactively, it prompts for function-name in the minibuffer. If function-name is nil or the empty string, it cancels break-on-entry for all functions.

Calling cancel-debug-on-entry does nothing to a function which is not currently set up to break on entry. It always returns function-name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1.4 Explicit Entry to the Debugger

You can cause the debugger to be called at a certain point in your program by writing the expression (debug) at that point. To do this, visit the source file, insert the text `(debug)' at the proper place, and type C-M-x. Warning: if you do this for temporary debugging purposes, be sure to undo this insertion before you save the file!

The place where you insert `(debug)' must be a place where an additional form can be evaluated and its value ignored. (If the value of (debug) isn't ignored, it will alter the execution of the program!) The most common suitable places are inside a progn or an implicit progn (see section 10.1 Sequencing).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1.5 Using the Debugger

When the debugger is entered, it displays the previously selected buffer in one window and a buffer named `*Backtrace*' in another window. The backtrace buffer contains one line for each level of Lisp function execution currently going on. At the beginning of this buffer is a message describing the reason that the debugger was invoked (such as the error message and associated data, if it was invoked due to an error).

The backtrace buffer is read-only and uses a special major mode, Debugger mode, in which letters are defined as debugger commands. The usual Emacs editing commands are available; thus, you can switch windows to examine the buffer that was being edited at the time of the error, switch buffers, visit files, or do any other sort of editing. However, the debugger is a recursive editing level (see section 21.12 Recursive Editing) and it is wise to go back to the backtrace buffer and exit the debugger (with the q command) when you are finished with it. Exiting the debugger gets out of the recursive edit and kills the backtrace buffer.

The backtrace buffer shows you the functions that are executing and their argument values. It also allows you to specify a stack frame by moving point to the line describing that frame. (A stack frame is the place where the Lisp interpreter records information about a particular invocation of a function.) The frame whose line point is on is considered the current frame. Some of the debugger commands operate on the current frame.

The debugger itself must be run byte-compiled, since it makes assumptions about how many stack frames are used for the debugger itself. These assumptions are false if the debugger is running interpreted.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1.6 Debugger Commands

Inside the debugger (in Debugger mode), these special commands are available in addition to the usual cursor motion commands. (Keep in mind that all the usual facilities of Emacs, such as switching windows or buffers, are still available.)

The most important use of debugger commands is for stepping through code, so that you can see how control flows. The debugger can step through the control structures of an interpreted function, but cannot do so in a byte-compiled function. If you would like to step through a byte-compiled function, replace it with an interpreted definition of the same function. (To do this, visit the source for the function and type C-M-x on its definition.)

Here is a list of Debugger mode commands:

c
Exit the debugger and continue execution. When continuing is possible, it resumes execution of the program as if the debugger had never been entered (aside from any side-effects that you caused by changing variable values or data structures while inside the debugger).
Continuing is possible after entry to the debugger due to function entry or exit, explicit invocation, or quitting. You cannot continue if the debugger was entered because of an error.

d
Continue execution, but enter the debugger the next time any Lisp function is called. This allows you to step through the subexpressions of an expression, seeing what values the subexpressions compute, and what else they do.
The stack frame made for the function call which enters the debugger in this way will be flagged automatically so that the debugger will be called again when the frame is exited. You can use the u command to cancel this flag.

b
Flag the current frame so that the debugger will be entered when the frame is exited. Frames flagged in this way are marked with stars in the backtrace buffer.

u
Don't enter the debugger when the current frame is exited. This cancels a b command on that frame. The visible effect is to remove the star from the line in the backtrace buffer.

e
Read a Lisp expression in the minibuffer, evaluate it, and print the value in the echo area. The debugger alters certain important variables, and the current buffer, as part of its operation; e temporarily restores their values from outside the debugger, so you can examine and change them. This makes the debugger more transparent. By contrast, M-: does nothing special in the debugger; it shows you the variable values within the debugger.

R
Like e, but also save the result of evaluation in the buffer `*Debugger-record*'.

q
Terminate the program being debugged; return to top-level Emacs command execution.
If the debugger was entered due to a C-g but you really want to quit, and not debug, use the q command.

r
Return a value from the debugger. The value is computed by reading an expression with the minibuffer and evaluating it.
The r command is useful when the debugger was invoked due to exit from a Lisp call frame (as requested with b or by entering the frame with d); then the value specified in the r command is used as the value of that frame. It is also useful if you call debug and use its return value. Otherwise, r has the same effect as c, and the specified return value does not matter.

You can't use r when the debugger was entered due to an error.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1.7 Invoking the Debugger

Here we describe in full detail the function debug that is used to invoke the debugger.

Function: debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer named `*Backtrace*' (or `*Backtrace*<2>' if it is the second recursive entry to the debugger, etc.), and fills it with information about the stack of Lisp function calls. It then enters a recursive edit, showing the backtrace buffer in Debugger mode.

The Debugger mode c and r commands exit the recursive edit; then debug switches back to the previous buffer and returns to whatever called debug. This is the only way the function debug can return to its caller.

The use of the debugger-args is that debug displays the rest of its arguments at the top of the `*Backtrace*' buffer, so that the user can see them. Except as described below, this is the only way these arguments are used.

However, certain values for first argument to debug have a special significance. (Normally, these values are used only by the internals of Emacs, and not by programmers calling debug.) Here is a table of these special values:

lambda
A first argument of lambda means debug was called because of entry to a function when debug-on-next-call was non-nil. The debugger displays `Entering:' as a line of text at the top of the buffer.

debug
debug as first argument indicates a call to debug because of entry to a function that was set to debug on entry. The debugger displays `Entering:', just as in the lambda case. It also marks the stack frame for that function so that it will invoke the debugger when exited.

t
When the first argument is t, this indicates a call to debug due to evaluation of a list form when debug-on-next-call is non-nil. The debugger displays the following as the top line in the buffer:
Beginning evaluation of function call form:
exit
When the first argument is exit, it indicates the exit of a stack frame previously marked to invoke the debugger on exit. The second argument given to debug in this case is the value being returned from the frame. The debugger displays `Return value:' in the top line of the buffer, followed by the value being returned.

error
When the first argument is error, the debugger indicates that it is being entered because an error or quit was signaled and not handled, by displaying `Signaling:' followed by the error signaled and any arguments to signal. For example,
(let ((debug-on-error t))
  (/ 1 0))

------ Buffer: *Backtrace* ------
Signaling: (arith-error)
  /(1 0)
...
------ Buffer: *Backtrace* ------
If an error was signaled, presumably the variable debug-on-error is non-nil. If quit was signaled, then presumably the variable debug-on-quit is non-nil.

nil
Use nil as the first of the debugger-args when you want to enter the debugger explicitly. The rest of the debugger-args are printed on the top line of the buffer. You can use this feature to display messages--for example, to remind yourself of the conditions under which debug is called.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.1.8 Internals of the Debugger

This section describes functions and variables used internally by the debugger.

Variable: debugger
The value of this variable is the function to call to invoke the debugger. Its value must be a function of any number of arguments, or, more typically, the name of a function. This function should invoke some kind of debugger. The default value of the variable is debug.

The first argument that Lisp hands to the function indicates why it was called. The convention for arguments is detailed in the description of debug.

Command: backtrace
This function prints a trace of Lisp function calls currently active. This is the function used by debug to fill up the `*Backtrace*' buffer. It is written in C, since it must have access to the stack to determine which function calls are active. The return value is always nil.

In the following example, a Lisp expression calls backtrace explicitly. This prints the backtrace to the stream standard-output, which, in this case, is the buffer `backtrace-output'.

Each line of the backtrace represents one function call. The line shows the values of the function's arguments if they are all known; if they are still being computed, the line says so. The arguments of special forms are elided.
(with-output-to-temp-buffer "backtrace-output"
  (let ((var 1))
    (save-excursion
      (setq var (eval '(progn
                         (1+ var)
                         (list 'testing (backtrace))))))))

     => nil

----------- Buffer: backtrace-output ------------
  backtrace()
  (list ...computing arguments...)
  (progn ...)
  eval((progn (1+ var) (list (quote testing) (backtrace))))
  (setq ...)
  (save-excursion ...)
  (let ...)
  (with-output-to-temp-buffer ...)
  eval-region(1973 2142 #<buffer *scratch*>)
  byte-code("...  for eval-print-last-sexp ...")
  eval-print-last-sexp(nil)
* call-interactively(eval-print-last-sexp)
----------- Buffer: backtrace-output ------------
The character `*' indicates a frame whose debug-on-exit flag is set.

Variable: debug-on-next-call
If this variable is non-nil, it says to call the debugger before the next eval, apply or funcall. Entering the debugger sets debug-on-next-call to nil.

The d command in the debugger works by setting this variable.

Function: backtrace-debug level flag
This function sets the debug-on-exit flag of the stack frame level levels down the stack, giving it the value flag. If flag is non-nil, this will cause the debugger to be entered when that frame later exits. Even a nonlocal exit through that frame will enter the debugger.

This function is used only by the debugger.

Variable: command-debug-status
This variable records the debugging status of the current interactive command. Each time a command is called interactively, this variable is bound to nil. The debugger can set this variable to leave information for future debugger invocations during the same command invocation.

The advantage of using this variable rather than an ordinary global variable is that the data will never carry over to a subsequent command invocation.

Function: backtrace-frame frame-number
The function backtrace-frame is intended for use in Lisp debuggers. It returns information about what computation is happening in the stack frame frame-number levels down.

If that frame has not evaluated the arguments yet, or is a special form, the value is (nil function arg-forms...).

If that frame has evaluated its arguments and called its function already, the return value is (t function arg-values...).

In the return value, function is whatever was supplied as the CAR of the evaluated list, or a lambda expression in the case of a macro call. If the function has a &rest argument, that is represented as the tail of the list arg-values.

If frame-number is out of range, backtrace-frame returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2 Edebug

Edebug is a source-level debugger for Emacs Lisp programs with which you can:

Step through evaluation, stopping before and after each expression.

Set conditional or unconditional breakpoints.

Stop when a specified condition is true (the global break event).

Trace slow or fast, stopping briefly at each stop point, or at each breakpoint.

Display expression results and evaluate expressions as if outside of Edebug.

Automatically re-evaluate a list of expressions and display their results each time Edebug updates the display.

Output trace info on function enter and exit.

Stop when an error occurs.

Display a backtrace, omitting Edebug's own frames.

Specify argument evaluation for macros and defining forms.

Obtain rudimentary coverage testing and frequency counts.

The first three sections below should tell you enough about Edebug to enable you to use it.

18.2.1 Using Edebug

Introduction to use of Edebug.

18.2.2 Instrumenting for Edebug

You must instrument your code in order to debug it with Edebug.

18.2.3 Edebug Execution Modes

Execution modes, stopping more or less often.

18.2.4 Jumping

Commands to jump to a specified place.

18.2.5 Miscellaneous Edebug Commands

Miscellaneous commands.

18.2.6 Breakpoints

Setting breakpoints to make the program stop.

18.2.7 Trapping Errors

Trapping errors with Edebug.

18.2.8 Edebug Views

Views inside and outside of Edebug.

18.2.9 Evaluation

Evaluating expressions within Edebug.

18.2.10 Evaluation List Buffer

Expressions whose values are displayed each time you enter Edebug.

18.2.11 Printing in Edebug

Customization of printing.

18.2.12 Trace Buffer

How to produce trace output in a buffer.

18.2.13 Coverage Testing

How to test evaluation coverage.

18.2.14 The Outside Context

Data that Edebug saves and restores.

18.2.15 Instrumenting Macro Calls

Specifying how to handle macro calls.

18.2.16 Edebug Options

Option variables for customizing Edebug.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.1 Using Edebug

To debug a Lisp program with Edebug, you must first instrument the Lisp code that you want to debug. A simple way to do this is to first move point into the definition of a function or macro and then do C-u C-M-x (eval-defun with a prefix argument). See 18.2.2 Instrumenting for Edebug, for alternative ways to instrument code.

Once a function is instrumented, any call to the function activates Edebug. Depending on which Edebug execution mode you have selected, activating Edebug may stop execution and let you step through the function, or it may update the display and continue execution while checking for debugging commands. The default execution mode is step, which stops execution. See section 18.2.3 Edebug Execution Modes.

Within Edebug, you normally view an Emacs buffer showing the source of the Lisp code you are debugging. This is referred to as the source code buffer, and it is temporarily read-only.

An arrow at the left margin indicates the line where the function is executing. Point initially shows where within the line the function is executing, but this ceases to be true if you move point yourself.

If you instrument the definition of fac (shown below) and then execute (fac 3), here is what you would normally see. Point is at the open-parenthesis before if.
(defun fac (n)
=>-!-(if (< 0 n)
      (* n (fac (1- n)))
    1))
The places within a function where Edebug can stop execution are called stop points. These occur both before and after each subexpression that is a list, and also after each variable reference. Here we use periods to show the stop points in the function fac:
(defun fac (n)
  .(if .(< 0 n.).
      .(* n. .(fac (1- n.).).).
    1).)
The special commands of Edebug are available in the source code buffer in addition to the commands of Emacs Lisp mode. For example, you can type the Edebug command SPC to execute until the next stop point. If you type SPC once after entry to fac, here is the display you will see:
(defun fac (n)
=>(if -!-(< 0 n)
      (* n (fac (1- n)))
    1))
When Edebug stops execution after an expression, it displays the expression's value in the echo area.

Other frequently used commands are b to set a breakpoint at a stop point, g to execute until a breakpoint is reached, and q to exit Edebug and return to the top-level command loop. Type ? to display a list of all Edebug commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.2 Instrumenting for Edebug

In order to use Edebug to debug Lisp code, you must first instrument the code. Instrumenting code inserts additional code into it, to invoke Edebug at the proper places.

Once you have loaded Edebug, the command C-M-x (eval-defun) is redefined so that when invoked with a prefix argument on a definition, it instruments the definition before evaluating it. (The source code itself is not modified.) If the variable edebug-all-defs is non-nil, that inverts the meaning of the prefix argument: in this case, C-M-x instruments the definition unless it has a prefix argument. The default value of edebug-all-defs is nil. The command M-x edebug-all-defs toggles the value of the variable edebug-all-defs.

If edebug-all-defs is non-nil, then the commands eval-region, eval-current-buffer, and eval-buffer also instrument any definitions they evaluate. Similarly, edebug-all-forms controls whether eval-region should instrument any form, even non-defining forms. This doesn't apply to loading or evaluations in the minibuffer. The command M-x edebug-all-forms toggles this option.

Another command, M-x edebug-eval-top-level-form, is available to instrument any top-level form regardless of the values of edebug-all-defs and edebug-all-forms.

While Edebug is active, the command I (edebug-instrument-callee) instruments the definition of the function or macro called by the list form after point, if is not already instrumented. This is possible only if Edebug knows where to find the source for that function; for this reading, after loading Edebug, eval-region records the position of every definition it evaluates, even if not instrumenting it. See also the i command (see section 18.2.4 Jumping), which steps into the call after instrumenting the function.

Edebug knows how to instrument all the standard special forms, interactive forms with an expression argument, anonymous lambda expressions, and other defining forms. However, Edebug cannot determine on its own what a user-defined macro will do with the arguments of a macro call, so you must provide that information; see 18.2.15 Instrumenting Macro Calls, for details.

When Edebug is about to instrument code for the first time in a session, it runs the hook edebug-setup-hook, then sets it to nil. You can use this to load Edebug specifications (see section 18.2.15 Instrumenting Macro Calls) associated with a package you are using, but only when you use Edebug.

To remove instrumentation from a definition, simply re-evaluate its definition in a way that does not instrument. There are two ways of evaluating forms that never instrument them: from a file with load, and from the minibuffer with eval-expression (M-:).

If Edebug detects a syntax error while instrumenting, it leaves point at the erroneous code and signals an invalid-read-syntax error.

See section 18.2.9 Evaluation, for other evaluation functions available inside of Edebug.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.3 Edebug Execution Modes

Edebug supports several execution modes for running the program you are debugging. We call these alternatives Edebug execution modes; do not confuse them with major or minor modes. The current Edebug execution mode determines how far Edebug continues execution before stopping--whether it stops at each stop point, or continues to the next breakpoint, for example--and how much Edebug displays the progress of the evaluation before it stops.

Normally, you specify the Edebug execution mode by typing a command to continue the program in a certain mode. Here is a table of these commands; all except for S resume execution of the program, at least for a certain distance.

S
Stop: don't execute any more of the program, but wait for more Edebug commands (edebug-stop).

SPC
Step: stop at the next stop point encountered (edebug-step-mode).

n
Next: stop at the next stop point encountered after an expression (edebug-next-mode). Also see edebug-forward-sexp in 18.2.5 Miscellaneous Edebug Commands.

t
Trace: pause one second at each Edebug stop point (edebug-trace-mode).

T
Rapid trace: update the display at each stop point, but don't actually pause (edebug-Trace-fast-mode).

g
Go: run until the next breakpoint (edebug-go-mode). See section 18.2.6 Breakpoints.

c
Continue: pause one second at each breakpoint, and then continue (edebug-continue-mode).

C
Rapid continue: move point to each breakpoint, but don't pause (edebug-Continue-fast-mode).

G
Go non-stop: ignore breakpoints (edebug-Go-nonstop-mode). You can still stop the program by typing S, or any editing command.
In general, the execution modes earlier in the above list run the program more slowly or stop sooner than the modes later in the list.

While executing or tracing, you can interrupt the execution by typing any Edebug command. Edebug stops the program at the next stop point and then executes the command you typed. For example, typing t during execution switches to trace mode at the next stop point. You can use S to stop execution without doing anything else.

If your function happens to read input, a character you type intending to interrupt execution may be read by the function instead. You can avoid such unintended results by paying attention to when your program wants input.

Keyboard macros containing the commands in this section do not completely work: exiting from Edebug, to resume the program, loses track of the keyboard macro. This is not easy to fix. Also, defining or executing a keyboard macro outside of Edebug does not affect commands inside Edebug. This is usually an advantage. See also the edebug-continue-kbd-macro option (see section 18.2.16 Edebug Options).

When you enter a new Edebug level, the initial execution mode comes from the value of the variable edebug-initial-mode. By default, this specifies step mode. Note that you may reenter the same Edebug level several times if, for example, an instrumented function is called several times from one command.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.4 Jumping

The commands described in this section execute until they reach a specified location. All except i make a temporary breakpoint to establish the place to stop, then switch to go mode. Any other breakpoint reached before the intended stop point will also stop execution. See section 18.2.6 Breakpoints, for the details on breakpoints.

These commands may fail to work as expected in case of nonlocal exit, as that can bypass the temporary breakpoint where you expected the program to stop.

h
Proceed to the stop point near where point is (edebug-goto-here).

f
Run the program forward over one expression (edebug-forward-sexp).

o
Run the program until the end of the containing sexp.

i
Step into the function or macro called by the form after point.
The h command proceeds to the stop point near the current location of point, using a temporary breakpoint. See 18.2.6 Breakpoints, for more information about breakpoints.

The f command runs the program forward over one expression. More precisely, it sets a temporary breakpoint at the position that C-M-f would reach, then executes in go mode so that the program will stop at breakpoints.

With a prefix argument n, the temporary breakpoint is placed n sexps beyond point. If the containing list ends before n more elements, then the place to stop is after the containing expression.

You must check that the position C-M-f finds is a place that the program will really get to. In cond, for example, this may not be true.

For flexibility, the f command does forward-sexp starting at point, rather than at the stop point. If you want to execute one expression from the current stop point, first type w, to move point there, and then type f.

The o command continues "out of" an expression. It places a temporary breakpoint at the end of the sexp containing point. If the containing sexp is a function definition itself, o continues until just before the last sexp in the definition. If that is where you are now, it returns from the function and then stops. In other words, this command does not exit the currently executing function unless you are positioned after the last sexp.

The i command steps into the function or macro called by the list form after point, and stops at its first stop point. Note that the form need not be the one about to be evaluated. But if the form is a function call about to be evaluated, remember to use this command before any of the arguments are evaluated, since otherwise it will be too late.

The i command instruments the function or macro it's supposed to step into, if it isn't instrumented already. This is convenient, but keep in mind that the function or macro remains instrumented unless you explicitly arrange to deinstrument it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.5 Miscellaneous Edebug Commands

Some miscellaneous Edebug commands are described here.

?
Display the help message for Edebug (edebug-help).

C-]
Abort one level back to the previous command level (abort-recursive-edit).

q
Return to the top level editor command loop (top-level). This exits all recursive editing levels, including all levels of Edebug activity. However, instrumented code protected with unwind-protect or condition-case forms may resume debugging.

Q
Like q, but don't stop even for protected code (top-level-nonstop).

r
Redisplay the most recently known expression result in the echo area (edebug-previous-result).

d
Display a backtrace, excluding Edebug's own functions for clarity (edebug-backtrace).
You cannot use debugger commands in the backtrace buffer in Edebug as you would in the standard debugger.

The backtrace buffer is killed automatically when you continue execution.
You can invoke commands from Edebug that activate Edebug again recursively. Whenever Edebug is active, you can quit to the top level with q or abort one recursive edit level with C-]. You can display a backtrace of all the pending evaluations with d.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.6 Breakpoints

Edebug's step mode stops execution when the next stop point is reached. There are three other ways to stop Edebug execution once it has started: breakpoints, the global break condition, and source breakpoints.

While using Edebug, you can specify breakpoints in the program you are testing: these are places where execution should stop. You can set a breakpoint at any stop point, as defined in 18.2.1 Using Edebug. For setting and unsetting breakpoints, the stop point that is affected is the first one at or after point in the source code buffer. Here are the Edebug commands for breakpoints:

b
Set a breakpoint at the stop point at or after point (edebug-set-breakpoint). If you use a prefix argument, the breakpoint is temporary--it turns off the first time it stops the program.

u
Unset the breakpoint (if any) at the stop point at or after point (edebug-unset-breakpoint).

x condition RET
Set a conditional breakpoint which stops the program only if condition evaluates to a non-nil value (edebug-set-conditional-breakpoint). With a prefix argument, the breakpoint is temporary.

B
Move point to the next breakpoint in the current definition (edebug-next-breakpoint).
While in Edebug, you can set a breakpoint with b and unset one with u. First move point to the Edebug stop point of your choice, then type b or u to set or unset a breakpoint there. Unsetting a breakpoint where none has been set has no effect.

Re-evaluating or reinstrumenting a definition removes all of its previous breakpoints.

A conditional breakpoint tests a condition each time the program gets there. Any errors that occur as a result of evaluating the condition are ignored, as if the result were nil. To set a conditional breakpoint, use x, and specify the condition expression in the minibuffer. Setting a conditional breakpoint at a stop point that has a previously established conditional breakpoint puts the previous condition expression in the minibuffer so you can edit it.

You can make a conditional or unconditional breakpoint temporary by using a prefix argument with the command to set the breakpoint. When a temporary breakpoint stops the program, it is automatically unset.

Edebug always stops or pauses at a breakpoint, except when the Edebug mode is Go-nonstop. In that mode, it ignores breakpoints entirely.

To find out where your breakpoints are, use the B command, which moves point to the next breakpoint following point, within the same function, or to the first breakpoint if there are no following breakpoints. This command does not continue execution--it just moves point in the buffer.

18.2.6.1 Global Break Condition

Breaking on an event.

18.2.6.2 Source Breakpoints

Embedding breakpoints in source code.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.6.1 Global Break Condition

A global break condition stops execution when a specified condition is satisfied, no matter where that may occur. Edebug evaluates the global break condition at every stop point; if it evaluates to a non-nil value, then execution stops or pauses depending on the execution mode, as if a breakpoint had been hit. If evaluating the condition gets an error, execution does not stop.

The condition expression is stored in edebug-global-break-condition. You can specify a new expression using the X command (edebug-set-global-break-condition).

The global break condition is the simplest way to find where in your code some event occurs, but it makes code run much more slowly. So you should reset the condition to nil when not using it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.6.2 Source Breakpoints

All breakpoints in a definition are forgotten each time you reinstrument it. If you wish to make a breakpoint that won't be forgotten, you can write a source breakpoint, which is simply a call to the function edebug in your source code. You can, of course, make such a call conditional. For example, in the fac function, you can insert the first line as shown below, to stop when the argument reaches zero:
(defun fac (n)
  (if (= n 0) (edebug))
  (if (< 0 n)
      (* n (fac (1- n)))
    1))
When the fac definition is instrumented and the function is called, the call to edebug acts as a breakpoint. Depending on the execution mode, Edebug stops or pauses there.

If no instrumented code is being executed when edebug is called, that function calls debug.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.7 Trapping Errors

Emacs normally displays an error message when an error is signaled and not handled with condition-case. While Edebug is active and executing instrumented code, it normally responds to all unhandled errors. You can customize this with the options edebug-on-error and edebug-on-quit; see 18.2.16 Edebug Options.

When Edebug responds to an error, it shows the last stop point encountered before the error. This may be the location of a call to a function which was not instrumented, and within which the error actually occurred. For an unbound variable error, the last known stop point might be quite distant from the offending variable reference. In that case, you might want to display a full backtrace (see section 18.2.5 Miscellaneous Edebug Commands).

If you change debug-on-error or debug-on-quit while Edebug is active, these changes will be forgotten when Edebug becomes inactive. Furthermore, during Edebug's recursive edit, these variables are bound to the values they had outside of Edebug.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.8 Edebug Views

These Edebug commands let you view aspects of the buffer and window status as they were before entry to Edebug. The outside window configuration is the collection of windows and contents that were in effect outside of Edebug.

v
Temporarily view the outside window configuration (edebug-view-outside).

p
Temporarily display the outside current buffer with point at its outside position (edebug-bounce-point). With a prefix argument n, pause for n seconds instead.

w
Move point back to the current stop point in the source code buffer (edebug-where).
If you use this command in a different window displaying the same buffer, that window will be used instead to display the current definition in the future.

W
Toggle whether Edebug saves and restores the outside window configuration (edebug-toggle-save-windows).
With a prefix argument, W only toggles saving and restoring of the selected window. To specify a window that is not displaying the source code buffer, you must use C-x X W from the global keymap.
You can view the outside window configuration with v or just bounce to the point in the current buffer with p, even if it is not normally displayed. After moving point, you may wish to jump back to the stop point with w from a source code buffer.

Each time you use W to turn saving off, Edebug forgets the saved outside window configuration--so that even if you turn saving back on, the current window configuration remains unchanged when you next exit Edebug (by continuing the program). However, the automatic redisplay of `*edebug*' and `*edebug-trace*' may conflict with the buffers you wish to see unless you have enough windows open.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.9 Evaluation

While within Edebug, you can evaluate expressions "as if" Edebug were not running. Edebug tries to be invisible to the expression's evaluation and printing. Evaluation of expressions that cause side effects will work as expected, except for changes to data that Edebug explicitly saves and restores. See section 18.2.14 The Outside Context, for details on this process.

e exp RET
Evaluate expression exp in the context outside of Edebug (edebug-eval-expression). That is, Edebug tries to minimize its interference with the evaluation.

M-: exp RET
Evaluate expression exp in the context of Edebug itself.

C-x C-e
Evaluate the expression before point, in the context outside of Edebug (edebug-eval-last-sexp).
Edebug supports evaluation of expressions containing references to lexically bound symbols created by the following constructs in `cl.el' (version 2.03 or later): lexical-let, macrolet, and symbol-macrolet.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.10 Evaluation List Buffer

You can use the evaluation list buffer, called `*edebug*', to evaluate expressions interactively. You can also set up the evaluation list of expressions to be evaluated automatically each time Edebug updates the display.

E
Switch to the evaluation list buffer `*edebug*' (edebug-visit-eval-list).
In the `*edebug*' buffer you can use the commands of Lisp Interaction mode (see section `Lisp Interaction' in The GNU Emacs Manual) as well as these special commands:

C-j
Evaluate the expression before point, in the outside context, and insert the value in the buffer (edebug-eval-print-last-sexp).

C-x C-e
Evaluate the expression before point, in the context outside of Edebug (edebug-eval-last-sexp).

C-c C-u
Build a new evaluation list from the contents of the buffer (edebug-update-eval-list).

C-c C-d
Delete the evaluation list group that point is in (edebug-delete-eval-item).

C-c C-w
Switch back to the source code buffer at the current stop point (edebug-where).
You can evaluate expressions in the evaluation list window with C-j or C-x C-e, just as you would in `*scratch*'; but they are evaluated in the context outside of Edebug.

The expressions you enter interactively (and their results) are lost when you continue execution; but you can set up an evaluation list consisting of expressions to be evaluated each time execution stops.

To do this, write one or more evaluation list groups in the evaluation list buffer. An evaluation list group consists of one or more Lisp expressions. Groups are separated by comment lines.

The command C-c C-u (edebug-update-eval-list) rebuilds the evaluation list, scanning the buffer and using the first expression of each group. (The idea is that the second expression of the group is the value previously computed and displayed.)

Each entry to Edebug redisplays the evaluation list by inserting each expression in the buffer, followed by its current value. It also inserts comment lines so that each expression becomes its own group. Thus, if you type C-c C-u again without changing the buffer text, the evaluation list is effectively unchanged.

If an error occurs during an evaluation from the evaluation list, the error message is displayed in a string as if it were the result. Therefore, expressions that use variables not currently valid do not interrupt your debugging.

Here is an example of what the evaluation list window looks like after several expressions have been added to it:
(current-buffer)
#<buffer *scratch*>
;---------------------------------------------------------------
(selected-window)
#<window 16 on *scratch*>
;---------------------------------------------------------------
(point)
196
;---------------------------------------------------------------
bad-var
"Symbol's value as variable is void: bad-var"
;---------------------------------------------------------------
(recursion-depth)
0
;---------------------------------------------------------------
this-command
eval-last-sexp
;---------------------------------------------------------------
To delete a group, move point into it and type C-c C-d, or simply delete the text for the group and update the evaluation list with C-c C-u. To add a new expression to the evaluation list, insert the expression at a suitable place, insert a new comment line, then type C-c C-u. You need not insert dashes in the comment line--its contents don't matter.

After selecting `*edebug*', you can return to the source code buffer with C-c C-w. The `*edebug*' buffer is killed when you continue execution, and recreated next time it is needed.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.11 Printing in Edebug

If an expression in your program produces a value containing circular list structure, you may get an error when Edebug attempts to print it.

One way to cope with circular structure is to set print-length or print-level to truncate the printing. Edebug does this for you; it binds print-length and print-level to 50 if they were nil. (Actually, the variables edebug-print-length and edebug-print-level specify the values to use within Edebug.) See section 19.6 Variables Affecting Output.

User Option: edebug-print-length
If non-nil, Edebug binds print-length to this value while printing results. The default value is 50.

User Option: edebug-print-level
If non-nil, Edebug binds print-level to this value while printing results. The default value is 50.

You can also print circular structures and structures that share elements more informatively by binding print-circle to a non-nil value.

Here is an example of code that creates a circular structure:
(setq a '(x y))
(setcar a a)
Custom printing prints this as `Result: #1=(#1# y)'. The `#1=' notation labels the structure that follows it with the label `1', and the `#1#' notation references the previously labeled structure. This notation is used for any shared elements of lists or vectors.

User Option: edebug-print-circle
If non-nil, Edebug binds print-circle to this value while printing results. The default value is nil.

Other programs can also use custom printing; see `cust-print.el' for details.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.12 Trace Buffer

Edebug can record an execution trace, storing it in a buffer named `*edebug-trace*'. This is a log of function calls and returns, showing the function names and their arguments and values. To enable trace recording, set edebug-trace to a non-nil value.

Making a trace buffer is not the same thing as using trace execution mode (see section 18.2.3 Edebug Execution Modes).

When trace recording is enabled, each function entry and exit adds lines to the trace buffer. A function entry record consists of `::::{', followed by the function name and argument values. A function exit record consists of `::::}', followed by the function name and result of the function.

The number of `:'s in an entry shows its recursion depth. You can use the braces in the trace buffer to find the matching beginning or end of function calls.

You can customize trace recording for function entry and exit by redefining the functions edebug-print-trace-before and edebug-print-trace-after.

Macro: edebug-tracing string body...
This macro requests additional trace information around the execution of the body forms. The argument string specifies text to put in the trace buffer. All the arguments are evaluated, and edebug-tracing returns the value of the last form in body.

Function: edebug-trace format-string &rest format-args
This function inserts text in the trace buffer. It computes the text with (apply 'format format-string format-args). It also appends a newline to separate entries.

edebug-tracing and edebug-trace insert lines in the trace buffer whenever they are called, even if Edebug is not active. Adding text to the trace buffer also scrolls its window to show the last lines inserted.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.13 Coverage Testing

Edebug provides rudimentary coverage testing and display of execution frequency.

Coverage testing works by comparing the result of each expression with the previous result; each form in the program is considered "covered" if it has returned two different values since you began testing coverage in the current Emacs session. Thus, to do coverage testing on your program, execute it under various conditions and note whether it behaves correctly; Edebug will tell you when you have tried enough different conditions that each form has returned two different values.

Coverage testing makes execution slower, so it is only done if edebug-test-coverage is non-nil. Frequency counting is performed for all execution of an instrumented function, even if the execution mode is Go-nonstop, and regardless of whether coverage testing is enabled.

Use M-x edebug-display-freq-count to display both the coverage information and the frequency counts for a definition.

Command: edebug-display-freq-count
This command displays the frequency count data for each line of the current definition.

The frequency counts appear as comment lines after each line of code, and you can undo all insertions with one undo command. The counts appear under the `(' before an expression or the `)' after an expression, or on the last character of a variable. To simplify the display, a count is not shown if it is equal to the count of an earlier expression on the same line.

The character `=' following the count for an expression says that the expression has returned the same value each time it was evaluated. In other words, it is not yet "covered" for coverage testing purposes.

To clear the frequency count and coverage data for a definition, simply reinstrument it with eval-defun.

For example, after evaluating (fac 5) with a source breakpoint, and setting edebug-test-coverage to t, when the breakpoint is reached, the frequency data looks like this:
(defun fac (n)
  (if (= n 0) (edebug))
;#6           1      0 =5
  (if (< 0 n)
;#5         =
      (* n (fac (1- n)))
;#    5               0
    1))
;#   0
The comment lines show that fac was called 6 times. The first if statement returned 5 times with the same result each time; the same is true of the condition on the second if. The recursive call of fac did not return at all.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.14 The Outside Context

Edebug tries to be transparent to the program you are debugging, but it does not succeed completely. Edebug also tries to be transparent when you evaluate expressions with e or with the evaluation list buffer, by temporarily restoring the outside context. This section explains precisely what context Edebug restores, and how Edebug fails to be completely transparent.

18.2.14.1 Checking Whether to Stop

When Edebug decides what to do.

18.2.14.2 Edebug Display Update

When Edebug updates the display.

18.2.14.3 Edebug Recursive Edit

When Edebug stops execution.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.14.1 Checking Whether to Stop

Whenever Edebug is entered, it needs to save and restore certain data before even deciding whether to make trace information or stop the program.

max-lisp-eval-depth and max-specpdl-size are both incremented once to reduce Edebug's impact on the stack. You could, however, still run out of stack space when using Edebug.

The state of keyboard macro execution is saved and restored. While Edebug is active, executing-macro is bound to edebug-continue-kbd-macro.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.14.2 Edebug Display Update

When Edebug needs to display something (e.g., in trace mode), it saves the current window configuration from "outside" Edebug (see section 28.17 Window Configurations). When you exit Edebug (by continuing the program), it restores the previous window configuration.

Emacs redisplays only when it pauses. Usually, when you continue execution, the program re-enters Edebug at a breakpoint or after stepping, without pausing or reading input in between. In such cases, Emacs never gets a chance to redisplay the "outside" configuration. Consequently, what you see is the same window configuration as the last time Edebug was active, with no interruption.

Entry to Edebug for displaying something also saves and restores the following data (though some of them are deliberately not restored if an error or quit signal occurs).

Which buffer is current, and the positions of point and the mark in the current buffer, are saved and restored.

The outside window configuration is saved and restored if edebug-save-windows is non-nil (see section 18.2.14.2 Edebug Display Update).
The window configuration is not restored on error or quit, but the outside selected window is reselected even on error or quit in case a save-excursion is active. If the value of edebug-save-windows is a list, only the listed windows are saved and restored.

The window start and horizontal scrolling of the source code buffer are not restored, however, so that the display remains coherent within Edebug.

The value of point in each displayed buffer is saved and restored if edebug-save-displayed-buffer-points is non-nil.

The variables overlay-arrow-position and overlay-arrow-string are saved and restored. So you can safely invoke Edebug from the recursive edit elsewhere in the same buffer.

cursor-in-echo-area is locally bound to nil so that the cursor shows up in the window.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.14.3 Edebug Recursive Edit

When Edebug is entered and actually reads commands from the user, it saves (and later restores) these additional data:

The current match data. See section 34.6 The Match Data.

last-command, this-command, last-command-char, last-input-char, last-input-event, last-command-event, last-event-frame, last-nonmenu-event, and track-mouse. Commands used within Edebug do not affect these variables outside of Edebug.
The key sequence returned by this-command-keys is changed by executing commands within Edebug and there is no way to reset the key sequence from Lisp.

Edebug cannot save and restore the value of unread-command-events. Entering Edebug while this variable has a nontrivial value can interfere with execution of the program you are debugging.

Complex commands executed while in Edebug are added to the variable command-history. In rare cases this can alter execution.

Within Edebug, the recursion depth appears one deeper than the recursion depth outside Edebug. This is not true of the automatically updated evaluation list window.

standard-output and standard-input are bound to nil by the recursive-edit, but Edebug temporarily restores them during evaluations.

The state of keyboard macro definition is saved and restored. While Edebug is active, defining-kbd-macro is bound to edebug-continue-kbd-macro.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.15 Instrumenting Macro Calls

When Edebug instruments an expression that calls a Lisp macro, it needs additional information about the macro to do the job properly. This is because there is no a-priori way to tell which subexpressions of the macro call are forms to be evaluated. (Evaluation may occur explicitly in the macro body, or when the resulting expansion is evaluated, or any time later.)

Therefore, you must define an Edebug specification for each macro that Edebug will encounter, to explain the format of calls to that macro. To do this, use def-edebug-spec.

Macro: def-edebug-spec macro specification
Specify which expressions of a call to macro macro are forms to be evaluated. For simple macros, the specification often looks very similar to the formal argument list of the macro definition, but specifications are much more general than macro arguments.

The macro argument can actually be any symbol, not just a macro name.

Here is a simple example that defines the specification for the for example macro (see section 13.6.2 Evaluating Macro Arguments Repeatedly), followed by an alternative, equivalent specification.
(def-edebug-spec for
  (symbolp "from" form "to" form "do" &rest form))

(def-edebug-spec for
  (symbolp ['from form] ['to form] ['do body]))
Here is a table of the possibilities for specification and how each directs processing of arguments.

t
All arguments are instrumented for evaluation.

0
None of the arguments is instrumented.

a symbol
The symbol must have an Edebug specification which is used instead. This indirection is repeated until another kind of specification is found. This allows you to inherit the specification from another macro.

a list
The elements of the list describe the types of the arguments of a calling form. The possible elements of a specification list are described in the following sections.

18.2.15.1 Specification List

How to specify complex patterns of evaluation.

18.2.15.2 Backtracking in Specifications

What Edebug does when matching fails.

18.2.15.3 Specification Examples

To help understand specifications.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.15.1 Specification List

A specification list is required for an Edebug specification if some arguments of a macro call are evaluated while others are not. Some elements in a specification list match one or more arguments, but others modify the processing of all following elements. The latter, called specification keywords, are symbols beginning with `&' (such as &optional).

A specification list may contain sublists which match arguments that are themselves lists, or it may contain vectors used for grouping. Sublists and groups thus subdivide the specification list into a hierarchy of levels. Specification keywords apply only to the remainder of the sublist or group they are contained in.

When a specification list involves alternatives or repetition, matching it against an actual macro call may require backtracking. See section 18.2.15.2 Backtracking in Specifications, for more details.

Edebug specifications provide the power of regular expression matching, plus some context-free grammar constructs: the matching of sublists with balanced parentheses, recursive processing of forms, and recursion via indirect specifications.

Here's a table of the possible elements of a specification list, with their meanings:

sexp
A single unevaluated Lisp object, which is not instrumented.

form
A single evaluated expression, which is instrumented.

place
A place to store a value, as in the Common Lisp setf construct.

body
Short for &rest form. See &rest below.

function-form
A function form: either a quoted function symbol, a quoted lambda expression, or a form (that should evaluate to a function symbol or lambda expression). This is useful when an argument that's a lambda expression might be quoted with quote rather than function, since it instruments the body of the lambda expression either way.

lambda-expr
A lambda expression with no quoting.

&optional
All following elements in the specification list are optional; as soon as one does not match, Edebug stops matching at this level.
To make just a few elements optional followed by non-optional elements, use [&optional specs...]. To specify that several elements must all match or none, use &optional [specs...]. See the defun example below.

&rest
All following elements in the specification list are repeated zero or more times. In the last repetition, however, it is not a problem if the expression runs out before matching all of the elements of the specification list.
To repeat only a few elements, use [&rest specs...]. To specify several elements that must all match on every repetition, use &rest [specs...].

&or
Each of the following elements in the specification list is an alternative. One of the alternatives must match, or the &or specification fails.
Each list element following &or is a single alternative. To group two or more list elements as a single alternative, enclose them in [...].

&not
Each of the following elements is matched as alternatives as if by using &or, but if any of them match, the specification fails. If none of them match, nothing is matched, but the &not specification succeeds.

&define
Indicates that the specification is for a defining form. The defining form itself is not instrumented (that is, Edebug does not stop before and after the defining form), but forms inside it typically will be instrumented. The &define keyword should be the first element in a list specification.

nil
This is successful when there are no more arguments to match at the current argument list level; otherwise it fails. See sublist specifications and the backquote example below.

gate
No argument is matched but backtracking through the gate is disabled while matching the remainder of the specifications at this level. This is primarily used to generate more specific syntax error messages. See 18.2.15.2 Backtracking in Specifications, for more details. Also see the let example below.

other-symbol
Any other symbol in a specification list may be a predicate or an indirect specification.
If the symbol has an Edebug specification, this indirect specification should be either a list specification that is used in place of the symbol, or a function that is called to process the arguments. The specification may be defined with def-edebug-spec just as for macros. See the defun example below.

Otherwise, the symbol should be a predicate. The predicate is called with the argument and the specification fails if the predicate returns nil. In either case, that argument is not instrumented.

Some suitable predicates include symbolp, integerp, stringp, vectorp, and atom.

[elements...]
A vector of elements groups the elements into a single group specification. Its meaning has nothing to do with vectors.

"string"
The argument should be a symbol named string. This specification is equivalent to the quoted symbol, 'symbol, where the name of symbol is the string, but the string form is preferred.

(vector elements...)
The argument should be a vector whose elements must match the elements in the specification. See the backquote example below.

(elements...)
Any other list is a sublist specification and the argument must be a list whose elements match the specification elements.
A sublist specification may be a dotted list and the corresponding list argument may then be a dotted list. Alternatively, the last CDR of a dotted list specification may be another sublist specification (via a grouping or an indirect specification, e.g., (spec . [(more specs...)])) whose elements match the non-dotted list arguments. This is useful in recursive specifications such as in the backquote example below. Also see the description of a nil specification above for terminating such recursion.

Note that a sublist specification written as (specs . nil) is equivalent to (specs), and (specs . (sublist-elements...)) is equivalent to (specs sublist-elements...).
Here is a list of additional specifications that may appear only after &define. See the defun example below.

name
The argument, a symbol, is the name of the defining form.
A defining form is not required to have a name field; and it may have multiple name fields.

:name
This construct does not actually match an argument. The element following :name should be a symbol; it is used as an additional name component for the definition. You can use this to add a unique, static component to the name of the definition. It may be used more than once.

arg
The argument, a symbol, is the name of an argument of the defining form. However, lambda-list keywords (symbols starting with `&') are not allowed.

lambda-list
This matches a lambda list--the argument list of a lambda expression.

def-body
The argument is the body of code in a definition. This is like body, described above, but a definition body must be instrumented with a different Edebug call that looks up information associated with the definition. Use def-body for the highest level list of forms within the definition.

def-form
The argument is a single, highest-level form in a definition. This is like def-body, except use this to match a single form rather than a list of forms. As a special case, def-form also means that tracing information is not output when the form is executed. See the interactive example below.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.15.2 Backtracking in Specifications

If a specification fails to match at some point, this does not necessarily mean a syntax error will be signaled; instead, backtracking will take place until all alternatives have been exhausted. Eventually every element of the argument list must be matched by some element in the specification, and every required element in the specification must match some argument. When a syntax error is detected, it might not be reported until much later after higher-level alternatives have been exhausted, and with the point positioned further from the real error. But if backtracking is disabled when an error occurs, it can be reported immediately. Note that backtracking is also reenabled automatically in several situations; it is reenabled when a new alternative is established by &optional, &rest, or &or, or at the start of processing a sublist, group, or indirect specification. The effect of enabling or disabling backtracking is limited to the remainder of the level currently being processed and lower levels.

Backtracking is disabled while matching any of the form specifications (that is, form, body, def-form, and def-body). These specifications will match any form so any error must be in the form itself rather than at a higher level.

Backtracking is also disabled after successfully matching a quoted symbol or string specification, since this usually indicates a recognized construct. But if you have a set of alternative constructs that all begin with the same symbol, you can usually work around this constraint by factoring the symbol out of the alternatives, e.g., ["foo" &or [first case] [second case] ...].

Most needs are satisfied by these two ways that bactracking is automatically disabled, but occasionally it is useful to explicitly disable backtracking by using the gate specification. This is useful when you know that no higher alternatives could apply. See the example of the let specification.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.15.3 Specification Examples

It may be easier to understand Edebug specifications by studying the examples provided here.

A let special form has a sequence of bindings and a body. Each of the bindings is either a symbol or a sublist with a symbol and optional expression. In the specification below, notice the gate inside of the sublist to prevent backtracking once a sublist is found.
(def-edebug-spec let
  ((&rest
    &or symbolp (gate symbolp &optional form))
   body))
Edebug uses the following specifications for defun and defmacro and the associated argument list and interactive specifications. It is necessary to handle interactive forms specially since an expression argument it is actually evaluated outside of the function body.
(def-edebug-spec defmacro defun) ; Indirect ref to defun spec.
(def-edebug-spec defun
  (&define name lambda-list
           [&optional stringp]   ; Match the doc string, if present.
           [&optional ("interactive" interactive)]
           def-body))

(def-edebug-spec lambda-list
  (([&rest arg]
    [&optional ["&optional" arg &rest arg]]
    &optional ["&rest" arg]
    )))

(def-edebug-spec interactive
  (&optional &or stringp def-form))    ; Notice: def-form
The specification for backquote below illustrates how to match dotted lists and use nil to terminate recursion. It also illustrates how components of a vector may be matched. (The actual specification defined by Edebug does not support dotted lists because doing so causes very deep recursion that could fail.)
(def-edebug-spec ` (backquote-form))   ; Alias just for clarity.

(def-edebug-spec backquote-form
  (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
       (backquote-form . [&or nil backquote-form])
       (vector &rest backquote-form)
       sexp))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.2.16 Edebug Options

These options affect the behavior of Edebug:

User Option: edebug-setup-hook
Functions to call before Edebug is used. Each time it is set to a new value, Edebug will call those functions once and then edebug-setup-hook is reset to nil. You could use this to load up Edebug specifications associated with a package you are using but only when you also use Edebug. See section 18.2.2 Instrumenting for Edebug.

User Option: edebug-all-defs
If this is non-nil, normal evaluation of defining forms such as defun and defmacro instruments them for Edebug. This applies to eval-defun, eval-region, eval-buffer, and eval-current-buffer.

Use the command M-x edebug-all-defs to toggle the value of this option. See section 18.2.2 Instrumenting for Edebug.

User Option: edebug-all-forms
If this is non-nil, the commands eval-defun, eval-region, eval-buffer, and eval-current-buffer instrument all forms, even those that don't define anything. This doesn't apply to loading or evaluations in the minibuffer.

Use the command M-x edebug-all-forms to toggle the value of this option. See section 18.2.2 Instrumenting for Edebug.

User Option: edebug-save-windows
If this is non-nil, Edebug saves and restores the window configuration. That takes some time, so if your program does not care what happens to the window configurations, it is better to set this variable to nil.

If the value is a list, only the listed windows are saved and restored.

You can use the W command in Edebug to change this variable interactively. See section 18.2.14.2 Edebug Display Update.

User Option: edebug-save-displayed-buffer-points
If this is non-nil, Edebug saves and restores point in all displayed buffers.

Saving and restoring point in other buffers is necessary if you are debugging code that changes the point of a buffer which is displayed in a non-selected window. If Edebug or the user then selects the window, point in that buffer will move to the window's value of point.

Saving and restoring point in all buffers is expensive, since it requires selecting each window twice, so enable this only if you need it. See section 18.2.14.2 Edebug Display Update.

User Option: edebug-initial-mode
If this variable is non-nil, it specifies the initial execution mode for Edebug when it is first activated. Possible values are step, next, go, Go-nonstop, trace, Trace-fast, continue, and Continue-fast.

The default value is step. See section 18.2.3 Edebug Execution Modes.

User Option: edebug-trace
Non-nil means display a trace of function entry and exit. Tracing output is displayed in a buffer named `*edebug-trace*', one function entry or exit per line, indented by the recursion level.

The default value is nil.

Also see edebug-tracing, in 18.2.12 Trace Buffer.

User Option: edebug-test-coverage
If non-nil, Edebug tests coverage of all expressions debugged. See section 18.2.13 Coverage Testing.

User Option: edebug-continue-kbd-macro
If non-nil, continue defining or executing any keyboard macro that is executing outside of Edebug. Use this with caution since it is not debugged. See section 18.2.3 Edebug Execution Modes.

User Option: edebug-on-error
Edebug binds debug-on-error to this value, if debug-on-error was previously nil. See section 18.2.7 Trapping Errors.

User Option: edebug-on-quit
Edebug binds debug-on-quit to this value, if debug-on-quit was previously nil. See section 18.2.7 Trapping Errors.

If you change the values of edebug-on-error or edebug-on-quit while Edebug is active, their values won't be used until the next time Edebug is invoked via a new command.

User Option: edebug-global-break-condition
If non-nil, an expression to test for at every stop point. If the result is non-nil, then break. Errors are ignored. See section 18.2.6.1 Global Break Condition.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.3 Debugging Invalid Lisp Syntax

The Lisp reader reports invalid syntax, but cannot say where the real problem is. For example, the error "End of file during parsing" in evaluating an expression indicates an excess of open parentheses (or square brackets). The reader detects this imbalance at the end of the file, but it cannot figure out where the close parenthesis should have been. Likewise, "Invalid read syntax: ")"" indicates an excess close parenthesis or missing open parenthesis, but does not say where the missing parenthesis belongs. How, then, to find what to change?

If the problem is not simply an imbalance of parentheses, a useful technique is to try C-M-e at the beginning of each defun, and see if it goes to the place where that defun appears to end. If it does not, there is a problem in that defun.

However, unmatched parentheses are the most common syntax errors in Lisp, and we can give further advice for those cases. (In addition, just moving point through the code with Show Paren mode enabled might find the mismatch.)

18.3.1 Excess Open Parentheses

How to find a spurious open paren or missing close.

18.3.2 Excess Close Parentheses

How to find a spurious close paren or missing open.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.3.1 Excess Open Parentheses

The first step is to find the defun that is unbalanced. If there is an excess open parenthesis, the way to do this is to go to the end of the file and type C-u C-M-u. This will move you to the beginning of the defun that is unbalanced.

The next step is to determine precisely what is wrong. There is no way to be sure of this except by studying the program, but often the existing indentation is a clue to where the parentheses should have been. The easiest way to use this clue is to reindent with C-M-q and see what moves. But don't do this yet! Keep reading, first.

Before you do this, make sure the defun has enough close parentheses. Otherwise, C-M-q will get an error, or will reindent all the rest of the file until the end. So move to the end of the defun and insert a close parenthesis there. Don't use C-M-e to move there, since that too will fail to work until the defun is balanced.

Now you can go to the beginning of the defun and type C-M-q. Usually all the lines from a certain point to the end of the function will shift to the right. There is probably a missing close parenthesis, or a superfluous open parenthesis, near that point. (However, don't assume this is true; study the code to make sure.) Once you have found the discrepancy, undo the C-M-q with C-_, since the old indentation is probably appropriate to the intended parentheses.

After you think you have fixed the problem, use C-M-q again. If the old indentation actually fit the intended nesting of parentheses, and you have put back those parentheses, C-M-q should not change anything.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.3.2 Excess Close Parentheses

To deal with an excess close parenthesis, first go to the beginning of the file, then type C-u -1 C-M-u to find the end of the unbalanced defun.

Then find the actual matching close parenthesis by typing C-M-f at the beginning of that defun. This will leave you somewhere short of the place where the defun ought to end. It is possible that you will find a spurious close parenthesis in that vicinity.

If you don't see a problem at that point, the next thing to do is to type C-M-q at the beginning of the defun. A range of lines will probably shift left; if so, the missing open parenthesis or spurious close parenthesis is probably near the first of those lines. (However, don't assume this is true; study the code to make sure.) Once you have found the discrepancy, undo the C-M-q with C-_, since the old indentation is probably appropriate to the intended parentheses.

After you think you have fixed the problem, use C-M-q again. If the old indentation actually fits the intended nesting of parentheses, and you have put back those parentheses, C-M-q should not change anything.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

18.4 Debugging Problems in Compilation

When an error happens during byte compilation, it is normally due to invalid syntax in the program you are compiling. The compiler prints a suitable error message in the `*Compile-Log*' buffer, and then stops. The message may state a function name in which the error was found, or it may not. Either way, here is how to find out where in the file the error occurred.

What you should do is switch to the buffer ` *Compiler Input*'. (Note that the buffer name starts with a space, so it does not show up in M-x list-buffers.) This buffer contains the program being compiled, and point shows how far the byte compiler was able to read.

If the error was due to invalid Lisp syntax, point shows exactly where the invalid syntax was detected. The cause of the error is not necessarily near by! Use the techniques in the previous section to find the error.

If the error was detected while compiling a form that had been read successfully, then point is located at the end of the form. In this case, this technique can't localize the error precisely, but can still show you which function to check.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

19. Reading and Printing Lisp Objects

Printing and reading are the operations of converting Lisp objects to textual form and vice versa. They use the printed representations and read syntax described in 2. Lisp Data Types.

This chapter describes the Lisp functions for reading and printing. It also describes streams, which specify where to get the text (if reading) or where to put it (if printing).

19.1 Introduction to Reading and Printing

Overview of streams, reading and printing.

19.2 Input Streams

Various data types that can be used as input streams.

19.3 Input Functions

Functions to read Lisp objects from text.

19.4 Output Streams

Various data types that can be used as output streams.

19.5 Output Functions

Functions to print Lisp objects as text.

19.6 Variables Affecting Output

Variables that control what the printing functions do.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

19.1 Introduction to Reading and Printing

Reading a Lisp object means parsing a Lisp expression in textual form and producing a corresponding Lisp object. This is how Lisp programs get into Lisp from files of Lisp code. We call the text the read syntax of the object. For example, the text `(a . 5)' is the read syntax for a cons cell whose CAR is a and whose CDR is the number 5.

Printing a Lisp object means producing text that represents that object--converting the object to its printed representation (see section 2.1 Printed Representation and Read Syntax). Printing the cons cell described above produces the text `(a . 5)'.

Reading and printing are more or less inverse operations: printing the object that results from reading a given piece of text often produces the same text, and reading the text that results from printing an object usually produces a similar-looking object. For example, printing the symbol foo produces the text `foo', and reading that text returns the symbol foo. Printing a list whose elements are a and b produces the text `(a b)', and reading that text produces a list (but not the same list) with elements a and b.

However, these two operations are not precisely inverse to each other. There are three kinds of exceptions:

Printing can produce text that cannot be read. For example, buffers, windows, frames, subprocesses and markers print as text that starts with `#'; if you try to read this text, you get an error. There is no way to read those data types.

One object can have multiple textual representations. For example, `1' and `01' represent the same integer, and `(a b)' and `(a . (b))' represent the same list. Reading will accept any of the alternatives, but printing must choose one of them.

Comments can appear at certain points in the middle of an object's read sequence without affecting the result of reading it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

19.2 Input Streams

Most of the Lisp functions for reading text take an input stream as an argument. The input stream specifies where or how to get the characters of the text to be read. Here are the possible types of input stream:

buffer
The input characters are read from buffer, starting with the character directly after point. Point advances as characters are read.

marker
The input characters are read from the buffer that marker is in, starting with the character directly after the marker. The marker position advances as characters are read. The value of point in the buffer has no effect when the stream is a marker.

string
The input characters are taken from string, starting at the first character in the string and using as many characters as required.

function
The input characters are generated by function, which must support two kinds of calls:

When it is called with no arguments, it should return the next character.

When it is called with one argument (always a character), function should save the argument and arrange to return it on the next call. This is called unreading the character; it happens when the Lisp reader reads one character too many and wants to "put it back where it came from". In this case, it makes no difference what value function returns.

t
t used as a stream means that the input is read from the minibuffer. In fact, the minibuffer is invoked once and the text given by the user is made into a string that is then used as the input stream. If Emacs is running in batch mode, standard input is used instead of the minibuffer. For example,
(message "%s" (read t))
will read a Lisp expression from standard input and print the result to standard output.

nil
nil supplied as an input stream means to use the value of standard-input instead; that value is the default input stream, and must be a non-nil input stream.

symbol
A symbol as input stream is equivalent to the symbol's function definition (if any).
Here is an example of reading from a stream that is a buffer, showing where point is located before and after:
---------- Buffer: foo ----------
This-!- is the contents of foo.
---------- Buffer: foo ----------

(read (get-buffer "foo"))
     => is
(read (get-buffer "foo"))
     => the

---------- Buffer: foo ----------
This is the-!- contents of foo.
---------- Buffer: foo ----------
Note that the first read skips a space. Reading skips any amount of whitespace preceding the significant text.

Here is an example of reading from a stream that is a marker, initially positioned at the beginning of the buffer shown. The value read is the symbol This.
---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------

(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
     => #<marker at 1 in foo>
(read m)
     => This
m
     => #<marker at 5 in foo>   ;; Before the first space.
Here we read from the contents of a string:
(read "(When in) the course")
     => (When in)
The following example reads from the minibuffer. The prompt is: `Lisp expression: '. (That is always the prompt used when you read from the stream t.) The user's input is shown following the prompt.
(read t)
     => 23
---------- Buffer: Minibuffer ----------
Lisp expression: 23 RET
---------- Buffer: Minibuffer ----------
Finally, here is an example of a stream that is a function, named useless-stream. Before we use the stream, we initialize the variable useless-list to a list of characters. Then each call to the function useless-stream obtains the next character in the list or unreads a character by adding it to the front of the list.
(setq useless-list (append "XY()" nil))
     => (88 89 40 41)

(defun useless-stream (&optional unread)
  (if unread
      (setq useless-list (cons unread useless-list))
    (prog1 (car useless-list)
           (setq useless-list (cdr useless-list)))))
     => useless-stream
Now we read using the stream thus constructed:
(read 'useless-stream)
     => XY

useless-list
     => (40 41)
Note that the open and close parentheses remain in the list. The Lisp reader encountered the open parenthesis, decided that it ended the input, and unread it. Another attempt to read from the stream at this point would read `()' and return nil.

Function: get-file-char
This function is used internally as an input stream to read from the input file opened by the function load. Don't use this function yourself.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

19.3 Input Functions

This section describes the Lisp functions and variables that pertain to reading.

In the functions below, stream stands for an input stream (see the previous section). If stream is nil or omitted, it defaults to the value of standard-input.

An end-of-file error is signaled if reading encounters an unterminated list, vector, or string.

Function: read &optional stream
This function reads one textual Lisp expression from stream, returning it as a Lisp object. This is the basic Lisp input function.

Function: read-from-string string &optional start end
This function reads the first textual Lisp expression from the text in string. It returns a cons cell whose CAR is that expression, and whose CDR is an integer giving the position of the next remaining character in the string (i.e., the first one not read).

If start is supplied, then reading begins at index start in the string (where the first character is at index 0). If you specify end, then reading is forced to stop just before that index, as if the rest of the string were not there.

For example:
(read-from-string "(setq x 55) (setq y 5)")
     => ((setq x 55) . 11)
(read-from-string "\"A short string\"")
     => ("A short string" . 16)

;; Read starting at the first character.
(read-from-string "(list 112)" 0)
     => ((list 112) . 10)
;; Read starting at the second character.
(read-from-string "(list 112)" 1)
     => (list . 5)
;; Read starting at the seventh character,
;;   and stopping at the ninth.
(read-from-string "(list 112)" 6 8)
     => (11 . 8)
Variable: standard-input
This variable holds the default input stream--the stream that read uses when the stream argument is nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

19.4 Output Streams

An output stream specifies what to do with the characters produced by printing. Most print functions accept an output stream as an optional argument. Here are the possible types of output stream:

buffer
The output characters are inserted into buffer at point. Point advances as characters are inserted.

marker
The output characters are inserted into the buffer that marker points into, at the marker position. The marker position advances as characters are inserted. The value of point in the buffer has no effect on printing when the stream is a marker, and this kind of printing does not move point.

function
The output characters are passed to function, which is responsible for storing them away. It is called with a single character as argument, as many times as there are characters to be output, and is responsible for storing the characters wherever you want to put them.

t
The output characters are displayed in the echo area.

nil
nil specified as an output stream means to use the value of standard-output instead; that value is the default output stream, and must not be nil.

symbol
A symbol as output stream is equivalent to the symbol's function definition (if any).
Many of the valid output streams are also valid as input streams. The difference between input and output streams is therefore more a matter of how you use a Lisp object, than of different types of object.

Here is an example of a buffer used as an output stream. Point is initially located as shown immediately before the `h' in `the'. At the end, point is located directly before that same `h'.
---------- Buffer: foo ----------
This is t-!-he contents of foo.
---------- Buffer: foo ----------

(print "This is the output" (get-buffer "foo"))
     => "This is the output"

---------- Buffer: foo ----------
This is t
"This is the output"
-!-he contents of foo.
---------- Buffer: foo ----------
Now we show a use of a marker as an output stream. Initially, the marker is in buffer foo, between the `t' and the `h' in the word `the'. At the end, the marker has advanced over the inserted text so that it remains positioned before the same `h'. Note that the location of point, shown in the usual fashion, has no effect.
---------- Buffer: foo ----------
This is the -!-output
---------- Buffer: foo ----------

(setq m (copy-marker 10))
     => #<marker at 10 in foo>

(print "More output for foo." m)
     => "More output for foo."

---------- Buffer: foo ----------
This is t
"More output for foo."
he -!-output
---------- Buffer: foo ----------

m
     => #<marker at 34 in foo>
The following example shows output to the echo area:
(print "Echo Area output" t)
     => "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------
Finally, we show the use of a function as an output stream. The function eat-output takes each character that it is given and conses it onto the front of the list last-output (see section 5.5 Building Cons Cells and Lists). At the end, the list contains all the characters output, but in reverse order.
(setq last-output nil)
     => nil

(defun eat-output (c)
  (setq last-output (cons c last-output)))
     => eat-output

(print "This is the output" 'eat-output)
     => "This is the output"

last-output
     => (10 34 116 117 112 116 117 111 32 101 104
    116 32 115 105 32 115 105 104 84 34 10)
Now we can put the output in the proper order by reversing the list:
(concat (nreverse last-output))
     => "
\"This is the output\"
"
Calling concat converts the list to a string so you can see its contents more clearly.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

19.5 Output Functions

This section describes the Lisp functions for printing Lisp objects--converting objects into their printed representation.

Some of the Emacs printing functions add quoting characters to the output when necessary so that it can be read properly. The quoting characters used are `"' and `\'; they distinguish strings from symbols, and prevent punctuation characters in strings and symbols from being taken as delimiters when reading. See section 2.1 Printed Representation and Read Syntax, for full details. You specify quoting or no quoting by the choice of printing function.

If the text is to be read back into Lisp, then you should print with quoting characters to avoid ambiguity. Likewise, if the purpose is to describe a Lisp object clearly for a Lisp programmer. However, if the purpose of the output is to look nice for humans, then it is usually better to print without quoting.

Lisp objects can refer to themselves. Printing a self-referential object in the normal way would require an infinite amount of text, and the attempt could cause infinite recursion. Emacs detects such recursion and prints `#level' instead of recursively printing an object already being printed. For example, here `#0' indicates a recursive reference to the object at level 0 of the current print operation:
(setq foo (list nil))
     => (nil)
(setcar foo foo)
     => (#0)
In the functions below, stream stands for an output stream. (See the previous section for a description of output streams.) If stream is nil or omitted, it defaults to the value of standard-output.

Function: print object &optional stream
The print function is a convenient way of printing. It outputs the printed representation of object to stream, printing in addition one newline before object and another after it. Quoting characters are used. print returns object. For example:
(progn (print 'The\ cat\ in)
       (print "the hat")
       (print " came back"))
     -|
     -| The\ cat\ in
     -|
     -| "the hat"
     -|
     -| " came back"
     -|
     => " came back"
Function: prin1 object &optional stream
This function outputs the printed representation of object to stream. It does not print newlines to separate output as print does, but it does use quoting characters just like print. It returns object.
(progn (prin1 'The\ cat\ in)
       (prin1 "the hat")
       (prin1 " came back"))
     -| The\ cat\ in"the hat"" came back"
     => " came back"
Function: princ object &optional stream
This function outputs the printed representation of object to stream. It returns object.

This function is intended to produce output that is readable by people, not by read, so it doesn't insert quoting characters and doesn't put double-quotes around the contents of strings. It does not add any spacing between calls.
(progn
  (princ 'The\ cat)
  (princ " in the \"hat\""))
     -| The cat in the "hat"
     => " in the \"hat\""
Function: terpri &optional stream
This function outputs a newline to stream. The name stands for "terminate print".

Function: write-char character &optional stream
This function outputs character to stream. It returns character.

Function: prin1-to-string object &optional noescape
This function returns a string containing the text that prin1 would have printed for the same argument.
(prin1-to-string 'foo)
     => "foo"
(prin1-to-string (mark-marker))
     => "#"
If noescape is non-nil, that inhibits use of quoting characters in the output. (This argument is supported in Emacs versions 19 and later.)
(prin1-to-string "foo")
     => "\"foo\""
(prin1-to-string "foo" t)
     => "foo"
See format, in 4.6 Conversion of Characters and Strings, for other ways to obtain the printed representation of a Lisp object as a string.

Macro: with-output-to-string body...
This macro executes the body forms with standard-output set up to feed output into a string. Then it returns that string.

For example, if the current buffer name is `foo',
(with-output-to-string
  (princ "The buffer is ")
  (princ (buffer-name)))
returns "The buffer is foo".

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

19.6 Variables Affecting Output

Variable: standard-output
The value of this variable is the default output stream--the stream that print functions use when the stream argument is nil.

Variable: print-escape-newlines
If this variable is non-nil, then newline characters in strings are printed as `\n' and formfeeds are printed as `\f'. Normally these characters are printed as actual newlines and formfeeds.

This variable affects the print functions prin1 and print that print with quoting. It does not affect princ. Here is an example using prin1:
(prin1 "a\nb")
     -| "a
     -| b"
     => "a
b"

(let ((print-escape-newlines t))
  (prin1 "a\nb"))
     -| "a\nb"
     => "a
b"
In the second expression, the local binding of print-escape-newlines is in effect during the call to prin1, but not during the printing of the result.

Variable: print-escape-nonascii
If this variable is non-nil, then unibyte non-ASCII characters in strings are unconditionally printed as backslash sequences by the print functions prin1 and print that print with quoting.

Those functions also use backslash sequences for unibyte non-ASCII characters, regardless of the value of this variable, when the output stream is a multibyte buffer or a marker pointing into one.

Variable: print-escape-multibyte
If this variable is non-nil, then multibyte non-ASCII characters in strings are unconditionally printed as backslash sequences by the print functions prin1 and print that print with quoting.

Those functions also use backslash sequences for multibyte non-ASCII characters, regardless of the value of this variable, when the output stream is a unibyte buffer or a marker pointing into one.

Variable: print-length
The value of this variable is the maximum number of elements to print in any list, vector or bool-vector. If an object being printed has more than this many elements, it is abbreviated with an ellipsis.

If the value is nil (the default), then there is no limit.
(setq print-length 2)
     => 2
(print '(1 2 3 4 5))
     -| (1 2 ...)
     => (1 2 ...)
Variable: print-level
The value of this variable is the maximum depth of nesting of parentheses and brackets when printed. Any list or vector at a depth exceeding this limit is abbreviated with an ellipsis. A value of nil (which is the default) means no limit.

These variables are used for detecting and reporting circular and shared structure--but they are only defined in Emacs 21.

Variable: print-circle
If non-nil, this variable enables detection of circular and shared structure in printing.

Variable: print-gensym
If non-nil, this variable enables detection of uninterned symbols (see section 8.3 Creating and Interning Symbols) in printing. When this is enabled, uninterned symbols print with the prefix `#:', which tells the Lisp reader to produce an uninterned symbol.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20. Minibuffers

A minibuffer is a special buffer that Emacs commands use to read arguments more complicated than the single numeric prefix argument. These arguments include file names, buffer names, and command names (as in M-x). The minibuffer is displayed on the bottom line of the frame, in the same place as the echo area, but only while it is in use for reading an argument.

20.1 Introduction to Minibuffers

Basic information about minibuffers.

20.2 Reading Text Strings with the Minibuffer

How to read a straight text string.

20.3 Reading Lisp Objects with the Minibuffer

How to read a Lisp object or expression.

20.4 Minibuffer History

Recording previous minibuffer inputs so the user can reuse them.

20.5 Completion

How to invoke and customize completion.

20.6 Yes-or-No Queries

Asking a question with a simple answer.

20.7 Asking Multiple Y-or-N Questions

Asking a series of similar questions.

20.8 Reading a Password

Reading a password from the terminal.

20.9 Minibuffer Miscellany

Various customization hooks and variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.1 Introduction to Minibuffers

In most ways, a minibuffer is a normal Emacs buffer. Most operations within a buffer, such as editing commands, work normally in a minibuffer. However, many operations for managing buffers do not apply to minibuffers. The name of a minibuffer always has the form ` *Minibuf-number', and it cannot be changed. Minibuffers are displayed only in special windows used only for minibuffers; these windows always appear at the bottom of a frame. (Sometimes frames have no minibuffer window, and sometimes a special kind of frame contains nothing but a minibuffer window; see 29.8 Minibuffers and Frames.)

The text in the minibuffer always starts with the prompt string, the text that was specified by the program that is using the minibuffer to tell the user what sort of input to type. This text is marked read-only so you won't accidentally delete or change it. It is also marked as a field (see section 32.19.10 Defining and Using Fields), so that certain motion functions, including beginning-of-line, forward-word, forward-sentence, and forward-paragraph, stop at the boundary between the prompt and the actual text. (In older Emacs versions, the prompt was displayed using a special mechanism and was not part of the buffer contents.)

The minibuffer's window is normally a single line; it grows automatically if necessary if the contents require more space. You can explicitly resize it temporarily with the window sizing commands; it reverts to its normal size when the minibuffer is exited. You can resize it permanently by using the window sizing commands in the frame's other window, when the minibuffer is not active. If the frame contains just a minibuffer, you can change the minibuffer's size by changing the frame's size.

If a command uses a minibuffer while there is an active minibuffer, this is called a recursive minibuffer. The first minibuffer is named ` *Minibuf-0*'. Recursive minibuffers are named by incrementing the number at the end of the name. (The names begin with a space so that they won't show up in normal buffer lists.) Of several recursive minibuffers, the innermost (or most recently entered) is the active minibuffer. We usually call this "the" minibuffer. You can permit or forbid recursive minibuffers by setting the variable enable-recursive-minibuffers or by putting properties of that name on command symbols (see section 20.9 Minibuffer Miscellany).

Like other buffers, a minibuffer may use any of several local keymaps (see section 22. Keymaps); these contain various exit commands and in some cases completion commands (see section 20.5 Completion).

minibuffer-local-map is for ordinary input (no completion).

minibuffer-local-ns-map is similar, except that SPC exits just like RET. This is used mainly for Mocklisp compatibility.

minibuffer-local-completion-map is for permissive completion.

minibuffer-local-must-match-map is for strict completion and for cautious completion.

When Emacs is running in batch mode, any request to read from the minibuffer actually reads a line from the standard input descriptor that was supplied when Emacs was started.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.2 Reading Text Strings with the Minibuffer

Most often, the minibuffer is used to read text as a string. It can also be used to read a Lisp object in textual form. The most basic primitive for minibuffer input is read-from-minibuffer; it can do either one.

In most cases, you should not call minibuffer input functions in the middle of a Lisp function. Instead, do all minibuffer input as part of reading the arguments for a command, in the interactive specification. See section 21.2 Defining Commands.

Function: read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
This function is the most general way to get input through the minibuffer. By default, it accepts arbitrary text and returns it as a string; however, if read is non-nil, then it uses read to convert the text into a Lisp object (see section 19.3 Input Functions).

The first thing this function does is to activate a minibuffer and display it with prompt-string as the prompt. This value must be a string. Then the user can edit text in the minibuffer.

When the user types a command to exit the minibuffer, read-from-minibuffer constructs the return value from the text in the minibuffer. Normally it returns a string containing that text. However, if read is non-nil, read-from-minibuffer reads the text and returns the resulting Lisp object, unevaluated. (See section 19.3 Input Functions, for information about reading.)

The argument default specifies a default value to make available through the history commands. It should be a string, or nil. If read is non-nil, then default is also used as the input to read, if the user enters empty input. However, in the usual case (where read is nil), read-from-minibuffer does not return default when the user enters empty input; it returns an empty string, "". In this respect, it is different from all the other minibuffer input functions in this chapter.

If keymap is non-nil, that keymap is the local keymap to use in the minibuffer. If keymap is omitted or nil, the value of minibuffer-local-map is used as the keymap. Specifying a keymap is the most important way to customize the minibuffer for various applications such as completion.

The argument hist specifies which history list variable to use for saving the input and for history commands used in the minibuffer. It defaults to minibuffer-history. See section 20.4 Minibuffer History.

If the variable minibuffer-allow-text-properties is non-nil, then the string which is returned includes whatever text properties were present in the minibuffer. Otherwise all the text properties are stripped when the value is returned.

If the argument inherit-input-method is non-nil, then the minibuffer inherits the current input method (see section 33.11 Input Methods) and the setting of enable-multibyte-characters (see section 33.1 Text Representations) from whichever buffer was current before entering the minibuffer.

If initial-contents is a string, read-from-minibuffer inserts it into the minibuffer, leaving point at the end, before the user starts to edit the text. The minibuffer appears with this text as its initial contents.

Alternatively, initial-contents can be a cons cell of the form (string . position). This means to insert string in the minibuffer but put point position characters from the beginning, rather than at the end.

Usage note: The initial-contents argument and the default argument are two alternative features for more or less the same job. It does not make sense to use both features in a single call to read-from-minibuffer. In general, we recommend using default, since this permits the user to insert the default value when it is wanted, but does not burden the user with deleting it from the minibuffer on other occasions.

Function: read-string prompt &optional initial history default inherit-input-method
This function reads a string from the minibuffer and returns it. The arguments prompt and initial are used as in read-from-minibuffer. The keymap used is minibuffer-local-map.

The optional argument history, if non-nil, specifies a history list and optionally the initial position in the list. The optional argument default specifies a default value to return if the user enters null input; it should be a string. The optional argument inherit-input-method specifies whether to inherit the current buffer's input method.

This function is a simplified interface to the read-from-minibuffer function:
(read-string prompt initial history default inherit)
==
(let ((value
       (read-from-minibuffer prompt initial nil nil
                             history default inherit)))
  (if (equal value "")
      default
    value))
Variable: minibuffer-allow-text-properties
If this variable is nil, then read-from-minibuffer strips all text properties from the minibuffer input before returning it. Since all minibuffer input uses read-from-minibuffer, this variable applies to all minibuffer input.

Note that the completion functions discard text properties unconditionally, regardless of the value of this variable.

Variable: minibuffer-local-map
This is the default local keymap for reading from the minibuffer. By default, it makes the following bindings:

C-j
exit-minibuffer

RET
exit-minibuffer

C-g
abort-recursive-edit

M-n
next-history-element

M-p
previous-history-element

M-r
next-matching-history-element

M-s
previous-matching-history-element

Function: read-no-blanks-input prompt &optional initial inherit-input-method
This function reads a string from the minibuffer, but does not allow whitespace characters as part of the input: instead, those characters terminate the input. The arguments prompt, initial, and inherit-input-method are used as in read-from-minibuffer.

This is a simplified interface to the read-from-minibuffer function, and passes the value of the minibuffer-local-ns-map keymap as the keymap argument for that function. Since the keymap minibuffer-local-ns-map does not rebind C-q, it is possible to put a space into the string, by quoting it.
(read-no-blanks-input prompt initial)
==
(read-from-minibuffer prompt initial minibuffer-local-ns-map)
Variable: minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local keymap in the function read-no-blanks-input. By default, it makes the following bindings, in addition to those of minibuffer-local-map:

SPC
exit-minibuffer

TAB
exit-minibuffer

?
self-insert-and-exit

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.3 Reading Lisp Objects with the Minibuffer

This section describes functions for reading Lisp objects with the minibuffer.

Function: read-minibuffer prompt &optional initial
This function reads a Lisp object using the minibuffer, and returns it without evaluating it. The arguments prompt and initial are used as in read-from-minibuffer.

This is a simplified interface to the read-from-minibuffer function:
(read-minibuffer prompt initial)
==
(read-from-minibuffer prompt initial nil t)
Here is an example in which we supply the string "(testing)" as initial input:
(read-minibuffer
 "Enter an expression: " (format "%s" '(testing)))

;; Here is how the minibuffer is displayed:

---------- Buffer: Minibuffer ----------
Enter an expression: (testing)-!-
---------- Buffer: Minibuffer ----------
The user can type RET immediately to use the initial input as a default, or can edit the input.

Function: eval-minibuffer prompt &optional initial
This function reads a Lisp expression using the minibuffer, evaluates it, then returns the result. The arguments prompt and initial are used as in read-from-minibuffer.

This function simply evaluates the result of a call to read-minibuffer:
(eval-minibuffer prompt initial)
==
(eval (read-minibuffer prompt initial))
Function: edit-and-eval-command prompt form
This function reads a Lisp expression in the minibuffer, and then evaluates it. The difference between this command and eval-minibuffer is that here the initial form is not optional and it is treated as a Lisp object to be converted to printed representation rather than as a string of text. It is printed with prin1, so if it is a string, double-quote characters (`"') appear in the initial text. See section 19.5 Output Functions.

The first thing edit-and-eval-command does is to activate the minibuffer with prompt as the prompt. Then it inserts the printed representation of form in the minibuffer, and lets the user edit it. When the user exits the minibuffer, the edited text is read with read and then evaluated. The resulting value becomes the value of edit-and-eval-command.

In the following example, we offer the user an expression with initial text which is a valid form already:
(edit-and-eval-command "Please edit: " '(forward-word 1))

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)-!-
---------- Buffer: Minibuffer ----------
Typing RET right away would exit the minibuffer and evaluate the expression, thus moving point forward one word. edit-and-eval-command returns nil in this example.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.4 Minibuffer History

A minibuffer history list records previous minibuffer inputs so the user can reuse them conveniently. A history list is actually a symbol, not a list; it is a variable whose value is a list of strings (previous inputs), most recent first.

There are many separate history lists, used for different kinds of inputs. It's the Lisp programmer's job to specify the right history list for each use of the minibuffer.

The basic minibuffer input functions read-from-minibuffer and completing-read both accept an optional argument named hist which is how you specify the history list. Here are the possible values:

variable
Use variable (a symbol) as the history list.

(variable . startpos)
Use variable (a symbol) as the history list, and assume that the initial history position is startpos (an integer, counting from zero which specifies the most recent element of the history).
If you specify startpos, then you should also specify that element of the history as the initial minibuffer contents, for consistency.
If you don't specify hist, then the default history list minibuffer-history is used. For other standard history lists, see below. You can also create your own history list variable; just initialize it to nil before the first use.

Both read-from-minibuffer and completing-read add new elements to the history list automatically, and provide commands to allow the user to reuse items on the list. The only thing your program needs to do to use a history list is to initialize it and to pass its name to the input functions when you wish. But it is safe to modify the list by hand when the minibuffer input functions are not using it.

Here are some of the standard minibuffer history list variables:

Variable: minibuffer-history
The default history list for minibuffer history input.

Variable: query-replace-history
A history list for arguments to query-replace (and similar arguments to other commands).

Variable: file-name-history
A history list for file-name arguments.

Variable: buffer-name-history
A history list for buffer-name arguments.

Variable: regexp-history
A history list for regular expression arguments.

Variable: extended-command-history
A history list for arguments that are names of extended commands.

Variable: shell-command-history
A history list for arguments that are shell commands.

Variable: read-expression-history
A history list for arguments that are Lisp expressions to evaluate.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.5 Completion

Completion is a feature that fills in the rest of a name starting from an abbreviation for it. Completion works by comparing the user's input against a list of valid names and determining how much of the name is determined uniquely by what the user has typed. For example, when you type C-x b (switch-to-buffer) and then type the first few letters of the name of the buffer to which you wish to switch, and then type TAB (minibuffer-complete), Emacs extends the name as far as it can.

Standard Emacs commands offer completion for names of symbols, files, buffers, and processes; with the functions in this section, you can implement completion for other kinds of names.

The try-completion function is the basic primitive for completion: it returns the longest determined completion of a given initial string, with a given set of strings to match against.

The function completing-read provides a higher-level interface for completion. A call to completing-read specifies how to determine the list of valid names. The function then activates the minibuffer with a local keymap that binds a few keys to commands useful for completion. Other functions provide convenient simple interfaces for reading certain kinds of names with completion.

20.5.1 Basic Completion Functions

Low-level functions for completing strings.

(These are too low level to use the minibuffer.)

20.5.2 Completion and the Minibuffer

Invoking the minibuffer with completion.

20.5.3 Minibuffer Commands that Do Completion

Minibuffer commands that do completion.

20.5.4 High-Level Completion Functions

Convenient special cases of completion

(reading buffer name, file name, etc.)

20.5.5 Reading File Names

Using completion to read file names.

20.5.6 Programmed Completion

Finding the completions for a given file name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.5.1 Basic Completion Functions

The two functions try-completion and all-completions have nothing in themselves to do with minibuffers. We describe them in this chapter so as to keep them near the higher-level completion features that do use the minibuffer.

Function: try-completion string collection &optional predicate
This function returns the longest common substring of all possible completions of string in collection. The value of collection must be an alist, an obarray, or a function that implements a virtual set of strings (see below).

Completion compares string against each of the permissible completions specified by collection; if the beginning of the permissible completion equals string, it matches. If no permissible completions match, try-completion returns nil. If only one permissible completion matches, and the match is exact, then try-completion returns t. Otherwise, the value is the longest initial sequence common to all the permissible completions that match.

If collection is an alist (see section 5.8 Association Lists), the CARs of the alist elements form the set of permissible completions.

If collection is an obarray (see section 8.3 Creating and Interning Symbols), the names of all symbols in the obarray form the set of permissible completions. The global variable obarray holds an obarray containing the names of all interned Lisp symbols.

Note that the only valid way to make a new obarray is to create it empty and then add symbols to it one by one using intern. Also, you cannot intern a given symbol in more than one obarray.

If the argument predicate is non-nil, then it must be a function of one argument. It is used to test each possible match, and the match is accepted only if predicate returns non-nil. The argument given to predicate is either a cons cell from the alist (the CAR of which is a string) or else it is a symbol (not a symbol name) from the obarray.

You can also use a symbol that is a function as collection. Then the function is solely responsible for performing completion; try-completion returns whatever this function returns. The function is called with three arguments: string, predicate and nil. (The reason for the third argument is so that the same function can be used in all-completions and do the appropriate thing in either case.) See section 20.5.6 Programmed Completion.

In the first of the following examples, the string `foo' is matched by three of the alist CARs. All of the matches begin with the characters `fooba', so that is the result. In the second example, there is only one possible match, and it is exact, so the value is t.
(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
     => "fooba"

(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
     => t
In the following example, numerous symbols begin with the characters `forw', and all of them begin with the word `forward'. In most of the symbols, this is followed with a `-', but not in all, so no more than `forward' can be completed.
(try-completion "forw" obarray)
     => "forward"
Finally, in the following example, only two of the three possible matches pass the predicate test (the string `foobaz' is too short). Both of those begin with the string `foobar'.
(defun test (s)
  (> (length (car s)) 6))
     => test
(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     => "foobar"
Function: all-completions string collection &optional predicate nospace
This function returns a list of all possible completions of string. The arguments to this function (aside from nospace) are the same as those of try-completion. If nospace is non-nil, completions that start with a space are ignored unless string also starts with a space.

If collection is a function, it is called with three arguments: string, predicate and t; then all-completions returns whatever the function returns. See section 20.5.6 Programmed Completion.

Here is an example, using the function test shown in the example for try-completion:
(defun test (s)
  (> (length (car s)) 6))
     => test

(all-completions
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     => ("foobar1" "foobar2")
Variable: completion-ignore-case
If the value of this variable is non-nil, Emacs does not consider case significant in completion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.5.2 Completion and the Minibuffer

This section describes the basic interface for reading from the minibuffer with completion.

Function: completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
This function reads a string in the minibuffer, assisting the user by providing completion. It activates the minibuffer with prompt prompt, which must be a string.

The actual completion is done by passing collection and predicate to the function try-completion. This happens in certain commands bound in the local keymaps used for completion.

If require-match is nil, the exit commands work regardless of the input in the minibuffer. If require-match is t, the usual minibuffer exit commands won't exit unless the input completes to an element of collection. If require-match is neither nil nor t, then the exit commands won't exit unless the input already in the buffer matches an element of collection.

However, empty input is always permitted, regardless of the value of require-match; in that case, completing-read returns default. The value of default (if non-nil) is also available to the user through the history commands.

The user can exit with null input by typing RET with an empty minibuffer. Then completing-read returns "". This is how the user requests whatever default the command uses for the value being read. The user can return using RET in this way regardless of the value of require-match, and regardless of whether the empty string is included in collection.

The function completing-read works by calling read-minibuffer. It uses minibuffer-local-completion-map as the keymap if require-match is nil, and uses minibuffer-local-must-match-map if require-match is non-nil. See section 20.5.3 Minibuffer Commands that Do Completion.

The argument hist specifies which history list variable to use for saving the input and for minibuffer history commands. It defaults to minibuffer-history. See section 20.4 Minibuffer History.

If initial is non-nil, completing-read inserts it into the minibuffer as part of the input. Then it allows the user to edit the input, providing several commands to attempt completion. In most cases, we recommend using default, and not initial.

We discourage use of a non-nil value for initial, because it is an intrusive interface. The history list feature (which did not exist when we introduced initial) offers a far more convenient and general way for the user to get the default and edit it, and it is always available.

If the argument inherit-input-method is non-nil, then the minibuffer inherits the current input method (see section 33.11 Input Methods) and the setting of enable-multibyte-characters (see section 33.1 Text Representations) from whichever buffer was current before entering the minibuffer.

Completion ignores case when comparing the input against the possible matches, if the built-in variable completion-ignore-case is non-nil. See section 20.5.1 Basic Completion Functions.

Here's an example of using completing-read:
(completing-read
 "Complete a foo: "
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 nil t "fo")

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
Complete a foo: fo-!-
---------- Buffer: Minibuffer ----------
If the user then types DEL DEL b RET, completing-read returns barfoo.

The completing-read function binds three variables to pass information to the commands that actually do completion. These variables are minibuffer-completion-table, minibuffer-completion-predicate and minibuffer-completion-confirm. For more information about them, see 20.5.3 Minibuffer Commands that Do Completion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.5.3 Minibuffer Commands that Do Completion

This section describes the keymaps, commands and user options used in the minibuffer to do completion.

Variable: minibuffer-local-completion-map
completing-read uses this value as the local keymap when an exact match of one of the completions is not required. By default, this keymap makes the following bindings:

?
minibuffer-completion-help

SPC
minibuffer-complete-word

TAB
minibuffer-complete
with other characters bound as in minibuffer-local-map (see section 20.2 Reading Text Strings with the Minibuffer).

Variable: minibuffer-local-must-match-map
completing-read uses this value as the local keymap when an exact match of one of the completions is required. Therefore, no keys are bound to exit-minibuffer, the command that exits the minibuffer unconditionally. By default, this keymap makes the following bindings:

?
minibuffer-completion-help

SPC
minibuffer-complete-word

TAB
minibuffer-complete

C-j
minibuffer-complete-and-exit

RET
minibuffer-complete-and-exit
with other characters bound as in minibuffer-local-map.

Variable: minibuffer-completion-table
The value of this variable is the alist or obarray used for completion in the minibuffer. This is the global variable that contains what completing-read passes to try-completion. It is used by minibuffer completion commands such as minibuffer-complete-word.

Variable: minibuffer-completion-predicate
This variable's value is the predicate that completing-read passes to try-completion. The variable is also used by the other minibuffer completion functions.

Command: minibuffer-complete-word
This function completes the minibuffer contents by at most a single word. Even if the minibuffer contents have only one completion, minibuffer-complete-word does not add any characters beyond the first character that is not a word constituent. See section 35. Syntax Tables.

Command: minibuffer-complete
This function completes the minibuffer contents as far as possible.

Command: minibuffer-complete-and-exit
This function completes the minibuffer contents, and exits if confirmation is not required, i.e., if minibuffer-completion-confirm is nil. If confirmation is required, it is given by repeating this command immediately--the command is programmed to work without confirmation when run twice in succession.

Variable: minibuffer-completion-confirm
When the value of this variable is non-nil, Emacs asks for confirmation of a completion before exiting the minibuffer. The function minibuffer-complete-and-exit checks the value of this variable before it exits.

Command: minibuffer-completion-help
This function creates a list of the possible completions of the current minibuffer contents. It works by calling all-completions using the value of the variable minibuffer-completion-table as the collection argument, and the value of minibuffer-completion-predicate as the predicate argument. The list of completions is displayed as text in a buffer named `*Completions*'.

Function: display-completion-list completions
This function displays completions to the stream in standard-output, usually a buffer. (See section 19. Reading and Printing Lisp Objects, for more information about streams.) The argument completions is normally a list of completions just returned by all-completions, but it does not have to be. Each element may be a symbol or a string, either of which is simply printed, or a list of two strings, which is printed as if the strings were concatenated.

This function is called by minibuffer-completion-help. The most common way to use it is together with with-output-to-temp-buffer, like this:
(with-output-to-temp-buffer "*Completions*"
  (display-completion-list
    (all-completions (buffer-string) my-alist)))
User Option: completion-auto-help
If this variable is non-nil, the completion commands automatically display a list of possible completions whenever nothing can be completed because the next character is not uniquely determined.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.5.4 High-Level Completion Functions

This section describes the higher-level convenient functions for reading certain sorts of names with completion.

In most cases, you should not call these functions in the middle of a Lisp function. When possible, do all minibuffer input as part of reading the arguments for a command, in the interactive specification. See section 21.2 Defining Commands.

Function: read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a string. The argument default is the default name to use, the value to return if the user exits with an empty minibuffer. If non-nil, it should be a string or a buffer. It is mentioned in the prompt, but is not inserted in the minibuffer as initial input.

If existing is non-nil, then the name specified must be that of an existing buffer. The usual commands to exit the minibuffer do not exit if the text is not valid, and RET does completion to attempt to find a valid name. (However, default is not checked for validity; it is returned, whatever it is, if the user exits with the minibuffer empty.)

In the following example, the user enters `minibuffer.t', and then types RET. The argument existing is t, and the only buffer name starting with the given input is `minibuffer.texi', so that name is the value.
(read-buffer "Buffer name? " "foo" t)
;; After evaluation of the preceding expression,
;;   the following prompt appears,
;;   with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Buffer name? (default foo) -!-
---------- Buffer: Minibuffer ----------

;; The user types minibuffer.t RET.
     => "minibuffer.texi"
Variable: read-buffer-function
This variable specifies how to read buffer names. For example, if you set this variable to iswitchb-read-buffer, all Emacs commands that call read-buffer to read a buffer name will actually use the iswitchb package to read it.

Function: read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp symbol. The argument prompt is used as in read-from-minibuffer. Recall that a command is anything for which commandp returns t, and a command name is a symbol for which commandp returns t. See section 21.3 Interactive Call.

The argument default specifies what to return if the user enters null input. It can be a symbol or a string; if it is a string, read-command interns it before returning it. If default is nil, that means no default has been specified; then if the user enters null input, the return value is nil.
(read-command "Command name? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------
If the user types forward-c RET, then this function returns forward-char.

The read-command function is a simplified interface to completing-read. It uses the variable obarray so as to complete in the set of extant Lisp symbols, and it uses the commandp predicate so as to accept only command names:
(read-command prompt)
==
(intern (completing-read prompt obarray
                         'commandp t nil))
Function: read-variable prompt &optional default
This function reads the name of a user variable and returns it as a symbol.

The argument default specifies what to return if the user enters null input. It can be a symbol or a string; if it is a string, read-variable interns it before returning it. If default is nil, that means no default has been specified; then if the user enters null input, the return value is nil.
(read-variable "Variable name? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears,
;;   with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Variable name? -!-
---------- Buffer: Minibuffer ----------
If the user then types fill-p RET, read-variable returns fill-prefix.

This function is similar to read-command, but uses the predicate user-variable-p instead of commandp:
(read-variable prompt)
==
(intern
 (completing-read prompt obarray
                  'user-variable-p t nil))
See also the functions read-coding-system and read-non-nil-coding-system, in 33.10.4 User-Chosen Coding Systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.5.5 Reading File Names

Here is another high-level completion function, designed for reading a file name. It provides special features including automatic insertion of the default directory.

Function: read-file-name prompt &optional directory default existing initial
This function reads a file name in the minibuffer, prompting with prompt and providing completion. If default is non-nil, then the function returns default if the user just types RET. default is not checked for validity; it is returned, whatever it is, if the user exits with the minibuffer empty.

If existing is non-nil, then the user must specify the name of an existing file; RET performs completion to make the name valid if possible, and then refuses to exit if it is not valid. If the value of existing is neither nil nor t, then RET also requires confirmation after completion. If existing is nil, then the name of a nonexistent file is acceptable.

The argument directory specifies the directory to use for completion of relative file names. If insert-default-directory is non-nil, directory is also inserted in the minibuffer as initial input. It defaults to the current buffer's value of default-directory.

If you specify initial, that is an initial file name to insert in the buffer (after directory, if that is inserted). In this case, point goes at the beginning of initial. The default for initial is nil---don't insert any file name. To see what initial does, try the command C-x C-v. Note: we recommend using default rather than initial in most cases.

Here is an example:
(read-file-name "The file is ")

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/-!-
---------- Buffer: Minibuffer ----------
Typing manual TAB results in the following:
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texi-!-
---------- Buffer: Minibuffer ----------
If the user types RET, read-file-name returns the file name as the string "/gp/gnu/elisp/manual.texi".

User Option: insert-default-directory
This variable is used by read-file-name. Its value controls whether read-file-name starts by placing the name of the default directory in the minibuffer, plus the initial file name if any. If the value of this variable is nil, then read-file-name does not place any initial input in the minibuffer (unless you specify initial input with the initial argument). In that case, the default directory is still used for completion of relative file names, but is not displayed.

For example:
;; Here the minibuffer starts out with the default directory.
(let ((insert-default-directory t))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/-!-
---------- Buffer: Minibuffer ----------

;; Here the minibuffer is empty and only the prompt
;;   appears on its line.
(let ((insert-default-directory nil))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is -!-
---------- Buffer: Minibuffer ----------
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.5.6 Programmed Completion

Sometimes it is not possible to create an alist or an obarray containing all the intended possible completions. In such a case, you can supply your own function to compute the completion of a given string. This is called programmed completion.

To use this feature, pass a symbol with a function definition as the collection argument to completing-read. The function completing-read arranges to pass your completion function along to try-completion and all-completions, which will then let your function do all the work.

The completion function should accept three arguments:

The string to be completed.

The predicate function to filter possible matches, or nil if none. Your function should call the predicate for each possible match, and ignore the possible match if the predicate returns nil.

A flag specifying the type of operation.

There are three flag values for three operations:

nil specifies try-completion. The completion function should return the completion of the specified string, or t if the string is a unique and exact match already, or nil if the string matches no possibility.
If the string is an exact match for one possibility, but also matches other longer possibilities, the function should return the string, not t.

t specifies all-completions. The completion function should return a list of all possible completions of the specified string.

lambda specifies a test for an exact match. The completion function should return t if the specified string is an exact match for some possibility; nil otherwise.

It would be consistent and clean for completion functions to allow lambda expressions (lists that are functions) as well as function symbols as collection, but this is impossible. Lists as completion tables are already assigned another meaning--as alists. It would be unreliable to fail to handle an alist normally because it is also a possible function. So you must arrange for any function you wish to use for completion to be encapsulated in a symbol.

Emacs uses programmed completion when completing file names. See section 25.8.6 File Name Completion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.6 Yes-or-No Queries

This section describes functions used to ask the user a yes-or-no question. The function y-or-n-p can be answered with a single character; it is useful for questions where an inadvertent wrong answer will not have serious consequences. yes-or-no-p is suitable for more momentous questions, since it requires three or four characters to answer.

If either of these functions is called in a command that was invoked using the mouse--more precisely, if last-nonmenu-event (see section 21.4 Information from the Command Loop) is either nil or a list--then it uses a dialog box or pop-up menu to ask the question. Otherwise, it uses keyboard input. You can force use of the mouse or use of keyboard input by binding last-nonmenu-event to a suitable value around the call.

Strictly speaking, yes-or-no-p uses the minibuffer and y-or-n-p does not; but it seems best to describe them together.

Function: y-or-n-p prompt
This function asks the user a question, expecting input in the echo area. It returns t if the user types y, nil if the user types n. This function also accepts SPC to mean yes and DEL to mean no. It accepts C-] to mean "quit", like C-g, because the question might look like a minibuffer and for that reason the user might try to use C-] to get out. The answer is a single character, with no RET needed to terminate it. Upper and lower case are equivalent.

"Asking the question" means printing prompt in the echo area, followed by the string `(y or n) '. If the input is not one of the expected answers (y, n, SPC, DEL, or something that quits), the function responds `Please answer y or n.', and repeats the request.

This function does not actually use the minibuffer, since it does not allow editing of the answer. It actually uses the echo area (see section 38.4 The Echo Area), which uses the same screen space as the minibuffer. The cursor moves to the echo area while the question is being asked.

The answers and their meanings, even `y' and `n', are not hardwired. The keymap query-replace-map specifies them. See section 34.5 Search and Replace.

In the following example, the user first types q, which is invalid. At the next prompt the user types y.
(y-or-n-p "Do you need a lift? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears in the echo area:

---------- Echo area ----------
Do you need a lift? (y or n)
---------- Echo area ----------

;; If the user then types q, the following appears:

---------- Echo area ----------
Please answer y or n.  Do you need a lift? (y or n)
---------- Echo area ----------

;; When the user types a valid answer,
;;   it is displayed after the question:

---------- Echo area ----------
Do you need a lift? (y or n) y
---------- Echo area ----------
We show successive lines of echo area messages, but only one actually appears on the screen at a time.

Function: y-or-n-p-with-timeout prompt seconds default-value
Like y-or-n-p, except that if the user fails to answer within seconds seconds, this function stops waiting and returns default-value. It works by setting up a timer; see 40.7 Timers for Delayed Execution. The argument seconds may be an integer or a floating point number.

Function: yes-or-no-p prompt
This function asks the user a question, expecting input in the minibuffer. It returns t if the user enters `yes', nil if the user types `no'. The user must type RET to finalize the response. Upper and lower case are equivalent.

yes-or-no-p starts by displaying prompt in the echo area, followed by `(yes or no) '. The user must type one of the expected responses; otherwise, the function responds `Please answer yes or no.', waits about two seconds and repeats the request.

yes-or-no-p requires more work from the user than y-or-n-p and is appropriate for more crucial decisions.

Here is an example:
(yes-or-no-p "Do you really want to remove everything? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears,
;;   with an empty minibuffer:

---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
If the user first types y RET, which is invalid because this function demands the entire word `yes', it responds by displaying these prompts, with a brief pause between them:
---------- Buffer: minibuffer ----------
Please answer yes or no.
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.7 Asking Multiple Y-or-N Questions

When you have a series of similar questions to ask, such as "Do you want to save this buffer" for each buffer in turn, you should use map-y-or-n-p to ask the collection of questions, rather than asking each question individually. This gives the user certain convenient facilities such as the ability to answer the whole series at once.

Function: map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
This function asks the user a series of questions, reading a single-character answer in the echo area for each one.

The value of list specifies the objects to ask questions about. It should be either a list of objects or a generator function. If it is a function, it should expect no arguments, and should return either the next object to ask about, or nil meaning stop asking questions.

The argument prompter specifies how to ask each question. If prompter is a string, the question text is computed like this:
(format prompter object)
where object is the next object to ask about (as obtained from list).

If not a string, prompter should be a function of one argument (the next object to ask about) and should return the question text. If the value is a string, that is the question to ask the user. The function can also return t meaning do act on this object (and don't ask the user), or nil meaning ignore this object (and don't ask the user).

The argument actor says how to act on the answers that the user gives. It should be a function of one argument, and it is called with each object that the user says yes for. Its argument is always an object obtained from list.

If the argument help is given, it should be a list of this form:
(singular plural action)
where singular is a string containing a singular noun that describes the objects conceptually being acted on, plural is the corresponding plural noun, and action is a transitive verb describing what actor does.

If you don't specify help, the default is ("object" "objects" "act on").

Each time a question is asked, the user may enter y, Y, or SPC to act on that object; n, N, or DEL to skip that object; ! to act on all following objects; ESC or q to exit (skip all following objects); . (period) to act on the current object and then exit; or C-h to get help. These are the same answers that query-replace accepts. The keymap query-replace-map defines their meaning for map-y-or-n-p as well as for query-replace; see 34.5 Search and Replace.

You can use action-alist to specify additional possible answers and what they mean. It is an alist of elements of the form (char function help), each of which defines one additional answer. In this element, char is a character (the answer); function is a function of one argument (an object from list); help is a string.

When the user responds with char, map-y-or-n-p calls function. If it returns non-nil, the object is considered "acted upon", and map-y-or-n-p advances to the next object in list. If it returns nil, the prompt is repeated for the same object.

Normally, map-y-or-n-p binds cursor-in-echo-area while prompting. But if no-cursor-in-echo-area is non-nil, it does not do that.

If map-y-or-n-p is called in a command that was invoked using the mouse--more precisely, if last-nonmenu-event (see section 21.4 Information from the Command Loop) is either nil or a list--then it uses a dialog box or pop-up menu to ask the question. In this case, it does not use keyboard input or the echo area. You can force use of the mouse or use of keyboard input by binding last-nonmenu-event to a suitable value around the call.

The return value of map-y-or-n-p is the number of objects acted on.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.8 Reading a Password

To read a password to pass to another program, you can use the function read-passwd.

Function: read-passwd prompt &optional confirm default
This function reads a password, prompting with prompt. It does not echo the password as the user types it; instead, it echoes `.' for each character in the password.

The optional argument confirm, if non-nil, says to read the password twice and insist it must be the same both times. If it isn't the same, the user has to type it over and over until the last two times match.

The optional argument default specifies the default password to return if the user enters empty input. If default is nil, then read-passwd returns the null string in that case.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

20.9 Minibuffer Miscellany

This section describes some basic functions and variables related to minibuffers.

Command: exit-minibuffer
This command exits the active minibuffer. It is normally bound to keys in minibuffer local keymaps.

Command: self-insert-and-exit
This command exits the active minibuffer after inserting the last character typed on the keyboard (found in last-command-char; see section 21.4 Information from the Command Loop).

Command: previous-history-element n
This command replaces the minibuffer contents with the value of the nth previous (older) history element.

Command: next-history-element n
This command replaces the minibuffer contents with the value of the nth more recent history element.

Command: previous-matching-history-element pattern n
This command replaces the minibuffer contents with the value of the nth previous (older) history element that matches pattern (a regular expression).

Command: next-matching-history-element pattern n
This command replaces the minibuffer contents with the value of the nth next (newer) history element that matches pattern (a regular expression).

Function: minibuffer-prompt
This function returns the prompt string of the currently active minibuffer. If no minibuffer is active, it returns nil.

Function: minibuffer-prompt-end
This function, available starting in Emacs 21, returns the current position of the end of the minibuffer prompt, if a minibuffer is current. Otherwise, it returns the minimum valid buffer position.

Function: minibuffer-contents
This function, available starting in Emacs 21, returns the editable contents of the minibuffer (that is, everything except the prompt) as a string, if a minibuffer is current. Otherwise, it returns the entire contents of the current buffer.

Function: minibuffer-contents-no-properties
This is like minibuffer-contents, except that it does not copy text properties, just the characters themselves. See section 32.19 Text Properties.

Function: delete-minibuffer-contents
This function, available starting in Emacs 21, erases the editable contents of the minibuffer (that is, everything except the prompt), if a minibuffer is current. Otherwise, it erases the entire buffer.

Function: minubuffer-prompt-width
This function returns the current display-width of the minibuffer prompt, if a minibuffer is current. Otherwise, it returns zero.

Variable: minibuffer-setup-hook
This is a normal hook that is run whenever the minibuffer is entered. See section 23.6 Hooks.

Variable: minibuffer-exit-hook
This is a normal hook that is run whenever the minibuffer is exited. See section 23.6 Hooks.

Variable: minibuffer-help-form
The current value of this variable is used to rebind help-form locally inside the minibuffer (see section 24.5 Help Functions).

Function: active-minibuffer-window
This function returns the currently active minibuffer window, or nil if none is currently active.

Function: minibuffer-window &optional frame
This function returns the minibuffer window used for frame frame. If frame is nil, that stands for the current frame. Note that the minibuffer window used by a frame need not be part of that frame--a frame that has no minibuffer of its own necessarily uses some other frame's minibuffer window.

Function: window-minibuffer-p window
This function returns non-nil if window is a minibuffer window.

It is not correct to determine whether a given window is a minibuffer by comparing it with the result of (minibuffer-window), because there can be more than one minibuffer window if there is more than one frame.

Function: minibuffer-window-active-p window
This function returns non-nil if window, assumed to be a minibuffer window, is currently active.

Variable: minibuffer-scroll-window
If the value of this variable is non-nil, it should be a window object. When the function scroll-other-window is called in the minibuffer, it scrolls this window.

Finally, some functions and variables deal with recursive minibuffers (see section 21.12 Recursive Editing):

Function: minibuffer-depth
This function returns the current depth of activations of the minibuffer, a nonnegative integer. If no minibuffers are active, it returns zero.

User Option: enable-recursive-minibuffers
If this variable is non-nil, you can invoke commands (such as find-file) that use minibuffers even while the minibuffer window is active. Such invocation produces a recursive editing level for a new minibuffer. The outer-level minibuffer is invisible while you are editing the inner one.

If this variable is nil, you cannot invoke minibuffer commands when the minibuffer window is active, not even if you switch to another window to do it.

If a command name has a property enable-recursive-minibuffers that is non-nil, then the command can use the minibuffer to read arguments even if it is invoked from the minibuffer. The minibuffer command next-matching-history-element (normally M-s in the minibuffer) uses this feature.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21. Command Loop

When you run Emacs, it enters the editor command loop almost immediately. This loop reads key sequences, executes their definitions, and displays the results. In this chapter, we describe how these things are done, and the subroutines that allow Lisp programs to do them.

21.1 Command Loop Overview

How the command loop reads commands.

21.2 Defining Commands

Specifying how a function should read arguments.

21.3 Interactive Call

Calling a command, so that it will read arguments.

21.4 Information from the Command Loop

Variables set by the command loop for you to examine.

21.5 Adjusting Point After Commands

Adjustment of point after a command.

21.6 Input Events

What input looks like when you read it.

21.7 Reading Input

How to read input events from the keyboard or mouse.

21.8 Special Events

Events processed immediately and individually.

21.9 Waiting for Elapsed Time or Input

Waiting for user input or elapsed time.

21.10 Quitting

How C-g works. How to catch or defer quitting.

21.11 Prefix Command Arguments

How the commands to set prefix args work.

21.12 Recursive Editing

Entering a recursive edit, and why you usually shouldn't.

21.13 Disabling Commands

How the command loop handles disabled commands.

21.14 Command History

How the command history is set up, and how accessed.

21.15 Keyboard Macros

How keyboard macros are implemented.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.1 Command Loop Overview

The first thing the command loop must do is read a key sequence, which is a sequence of events that translates into a command. It does this by calling the function read-key-sequence. Your Lisp code can also call this function (see section 21.7.1 Key Sequence Input). Lisp programs can also do input at a lower level with read-event (see section 21.7.2 Reading One Event) or discard pending input with discard-input (see section 21.7.5 Miscellaneous Event Input Features).

The key sequence is translated into a command through the currently active keymaps. See section 22.7 Key Lookup, for information on how this is done. The result should be a keyboard macro or an interactively callable function. If the key is M-x, then it reads the name of another command, which it then calls. This is done by the command execute-extended-command (see section 21.3 Interactive Call).

To execute a command requires first reading the arguments for it. This is done by calling command-execute (see section 21.3 Interactive Call). For commands written in Lisp, the interactive specification says how to read the arguments. This may use the prefix argument (see section 21.11 Prefix Command Arguments) or may read with prompting in the minibuffer (see section 20. Minibuffers). For example, the command find-file has an interactive specification which says to read a file name using the minibuffer. The command's function body does not use the minibuffer; if you call this command from Lisp code as a function, you must supply the file name string as an ordinary Lisp function argument.

If the command is a string or vector (i.e., a keyboard macro) then execute-kbd-macro is used to execute it. You can call this function yourself (see section 21.15 Keyboard Macros).

To terminate the execution of a running command, type C-g. This character causes quitting (see section 21.10 Quitting).

Variable: pre-command-hook
The editor command loop runs this normal hook before each command. At that time, this-command contains the command that is about to run, and last-command describes the previous command. See section 23.6 Hooks.

Variable: post-command-hook
The editor command loop runs this normal hook after each command (including commands terminated prematurely by quitting or by errors), and also when the command loop is first entered. At that time, this-command describes the command that just ran, and last-command describes the command before that. See section 23.6 Hooks.

Quitting is suppressed while running pre-command-hook and post-command-hook. If an error happens while executing one of these hooks, it terminates execution of the hook, and clears the hook variable to nil so as to prevent an infinite loop of errors.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.2 Defining Commands

A Lisp function becomes a command when its body contains, at top level, a form that calls the special form interactive. This form does nothing when actually executed, but its presence serves as a flag to indicate that interactive calling is permitted. Its argument controls the reading of arguments for an interactive call.

21.2.1 Using interactive

General rules for interactive.

21.2.2 Code Characters for interactive

The standard letter-codes for reading arguments in various ways.

21.2.3 Examples of Using interactive

Examples of how to read interactive arguments.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.2.1 Using interactive

This section describes how to write the interactive form that makes a Lisp function an interactively-callable command, and how to examine a commands's interactive form.

Special Form: interactive arg-descriptor
This special form declares that the function in which it appears is a command, and that it may therefore be called interactively (via M-x or by entering a key sequence bound to it). The argument arg-descriptor declares how to compute the arguments to the command when the command is called interactively.

A command may be called from Lisp programs like any other function, but then the caller supplies the arguments and arg-descriptor has no effect.

The interactive form has its effect because the command loop (actually, its subroutine call-interactively) scans through the function definition looking for it, before calling the function. Once the function is called, all its body forms including the interactive form are executed, but at this time interactive simply returns nil without even evaluating its argument.

There are three possibilities for the argument arg-descriptor:

It may be omitted or nil; then the command is called with no arguments. This leads quickly to an error if the command requires one or more arguments.

It may be a Lisp expression that is not a string; then it should be a form that is evaluated to get a list of arguments to pass to the command.
If this expression reads keyboard input (this includes using the minibuffer), keep in mind that the integer value of point or the mark before reading input may be incorrect after reading input. This is because the current buffer may be receiving subprocess output; if subprocess output arrives while the command is waiting for input, it could relocate point and the mark.

Here's an example of what not to do:
(interactive
 (list (region-beginning) (region-end)
       (read-string "Foo: " nil 'my-history)))
Here's how to avoid the problem, by examining point and the mark only after reading the keyboard input:
(interactive
 (let ((string (read-string "Foo: " nil 'my-history)))
   (list (region-beginning) (region-end) string)))
It may be a string; then its contents should consist of a code character followed by a prompt (which some code characters use and some ignore). The prompt ends either with the end of the string or with a newline. Here is a simple example:
(interactive "bFrobnicate buffer: ")
The code letter `b' says to read the name of an existing buffer, with completion. The buffer name is the sole argument passed to the command. The rest of the string is a prompt.

If there is a newline character in the string, it terminates the prompt. If the string does not end there, then the rest of the string should contain another code character and prompt, specifying another argument. You can specify any number of arguments in this way.

The prompt string can use `%' to include previous argument values (starting with the first argument) in the prompt. This is done using format (see section 4.7 Formatting Strings). For example, here is how you could read the name of an existing buffer followed by a new name to give to that buffer:
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
If the first character in the string is `*', then an error is signaled if the buffer is read-only.

If the first character in the string is `@', and if the key sequence used to invoke the command includes any mouse events, then the window associated with the first of those events is selected before the command is run.

You can use `*' and `@' together; the order does not matter. Actual reading of arguments is controlled by the rest of the prompt string (starting with the first character that is not `*' or `@').

Function: interactive-form function
This function returns the interactive form of function. If function is a command (see section 21.3 Interactive Call), the value is a list of the form (interactive spec), where spec is the descriptor specification used by the command's interactive form to compute the function's arguments (see section 21.2.1 Using interactive). If function is not a command, interactive-form returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.2.2 Code Characters for interactive

The code character descriptions below contain a number of key words, defined here as follows:

Completion
Provide completion. TAB, SPC, and RET perform name completion because the argument is read using completing-read (see section 20.5 Completion). ? displays a list of possible completions.

Existing
Require the name of an existing object. An invalid name is not accepted; the commands to exit the minibuffer do not exit if the current input is not valid.

Default
A default value of some sort is used if the user enters no text in the minibuffer. The default depends on the code character.

No I/O
This code letter computes an argument without reading any input. Therefore, it does not use a prompt string, and any prompt string you supply is ignored.
Even though the code letter doesn't use a prompt string, you must follow it with a newline if it is not the last code character in the string.

Prompt
A prompt immediately follows the code character. The prompt ends either with the end of the string or with a newline.

Special
This code character is meaningful only at the beginning of the interactive string, and it does not look for a prompt or a newline. It is a single, isolated character.
Here are the code character descriptions for use with interactive:

`*'
Signal an error if the current buffer is read-only. Special.

`@'
Select the window mentioned in the first mouse event in the key sequence that invoked this command. Special.

`a'
A function name (i.e., a symbol satisfying fboundp). Existing, Completion, Prompt.

`b'
The name of an existing buffer. By default, uses the name of the current buffer (see section 27. Buffers). Existing, Completion, Default, Prompt.

`B'
A buffer name. The buffer need not exist. By default, uses the name of a recently used buffer other than the current buffer. Completion, Default, Prompt.

`c'
A character. The cursor does not move into the echo area. Prompt.

`C'
A command name (i.e., a symbol satisfying commandp). Existing, Completion, Prompt.

`d'
The position of point, as an integer (see section 30.1 Point). No I/O.

`D'
A directory name. The default is the current default directory of the current buffer, default-directory (see section 40.3 Operating System Environment). Existing, Completion, Default, Prompt.

`e'
The first or next mouse event in the key sequence that invoked the command. More precisely, `e' gets events that are lists, so you can look at the data in the lists. See section 21.6 Input Events. No I/O.
You can use `e' more than once in a single command's interactive specification. If the key sequence that invoked the command has n events that are lists, the nth `e' provides the nth such event. Events that are not lists, such as function keys and ASCII characters, do not count where `e' is concerned.

`f'
A file name of an existing file (see section 25.8 File Names). The default directory is default-directory. Existing, Completion, Default, Prompt.

`F'
A file name. The file need not exist. Completion, Default, Prompt.

`i'
An irrelevant argument. This code always supplies nil as the argument's value. No I/O.

`k'
A key sequence (see section 22.1 Keymap Terminology). This keeps reading events until a command (or undefined command) is found in the current key maps. The key sequence argument is represented as a string or vector. The cursor does not move into the echo area. Prompt.
This kind of input is used by commands such as describe-key and global-set-key.

`K'
A key sequence, whose definition you intend to change. This works like `k', except that it suppresses, for the last input event in the key sequence, the conversions that are normally used (when necessary) to convert an undefined key into a defined one.

`m'
The position of the mark, as an integer. No I/O.

`M'
Arbitrary text, read in the minibuffer using the current buffer's input method, and returned as a string (see section `Input Methods' in The GNU Emacs Manual). Prompt.

`n'
A number read with the minibuffer. If the input is not a number, the user is asked to try again. The prefix argument, if any, is not used. Prompt.

`N'
The numeric prefix argument; but if there is no prefix argument, read a number as with n. Requires a number. See section 21.11 Prefix Command Arguments. Prompt.

`p'
The numeric prefix argument. (Note that this `p' is lower case.) No I/O.

`P'
The raw prefix argument. (Note that this `P' is upper case.) No I/O.

`r'
Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one. No I/O.

`s'
Arbitrary text, read in the minibuffer and returned as a string (see section 20.2 Reading Text Strings with the Minibuffer). Terminate the input with either C-j or RET. (C-q may be used to include either of these characters in the input.) Prompt.

`S'
An interned symbol whose name is read in the minibuffer. Any whitespace character terminates the input. (Use C-q to include whitespace in the string.) Other characters that normally terminate a symbol (e.g., parentheses and brackets) do not do so here. Prompt.

`v'
A variable declared to be a user option (i.e., satisfying the predicate user-variable-p). See section 20.5.4 High-Level Completion Functions. Existing, Completion, Prompt.

`x'
A Lisp object, specified with its read syntax, terminated with a C-j or RET. The object is not evaluated. See section 20.3 Reading Lisp Objects with the Minibuffer. Prompt.

`X'
A Lisp form is read as with x, but then evaluated so that its value becomes the argument for the command. Prompt.

`z'
A coding system name (a symbol). If the user enters null input, the argument value is nil. See section 33.10 Coding Systems. Completion, Existing, Prompt.

`Z'
A coding system name (a symbol)---but only if this command has a prefix argument. With no prefix argument, `Z' provides nil as the argument value. Completion, Existing, Prompt.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.2.3 Examples of Using interactive

Here are some examples of interactive:
(defun foo1 ()              ; foo1 takes no arguments,
    (interactive)           ;   just moves forward two words.
    (forward-word 2))
     => foo1

(defun foo2 (n)             ; foo2 takes one argument,
    (interactive "p")       ;   which is the numeric prefix.
    (forward-word (* 2 n)))
     => foo2

(defun foo3 (n)             ; foo3 takes one argument,
    (interactive "nCount:") ;   which is read with the Minibuffer.
    (forward-word (* 2 n)))
     => foo3

(defun three-b (b1 b2 b3)
  "Select three existing buffers.
Put them into three windows, selecting the last one."
    (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
    (delete-other-windows)
    (split-window (selected-window) 8)
    (switch-to-buffer b1)
    (other-window 1)
    (split-window (selected-window) 8)
    (switch-to-buffer b2)
    (other-window 1)
    (switch-to-buffer b3))
     => three-b
(three-b "*scratch*" "declarations.texi" "*mail*")
     => nil
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.3 Interactive Call

After the command loop has translated a key sequence into a command it invokes that command using the function command-execute. If the command is a function, command-execute calls call-interactively, which reads the arguments and calls the command. You can also call these functions yourself.

Function: commandp object
Returns t if object is suitable for calling interactively; that is, if object is a command. Otherwise, returns nil.

The interactively callable objects include strings and vectors (treated as keyboard macros), lambda expressions that contain a top-level call to interactive, byte-code function objects made from such lambda expressions, autoload objects that are declared as interactive (non-nil fourth argument to autoload), and some of the primitive functions.

A symbol satisfies commandp if its function definition satisfies commandp.

Keys and keymaps are not commands. Rather, they are used to look up commands (see section 22. Keymaps).

See documentation in 24.2 Access to Documentation Strings, for a realistic example of using commandp.

Function: call-interactively command &optional record-flag keys
This function calls the interactively callable function command, reading arguments according to its interactive calling specifications. An error is signaled if command is not a function or if it cannot be called interactively (i.e., is not a command). Note that keyboard macros (strings and vectors) are not accepted, even though they are considered commands, because they are not functions.

If record-flag is non-nil, then this command and its arguments are unconditionally added to the list command-history. Otherwise, the command is added only if it uses the minibuffer to read an argument. See section 21.14 Command History.

The argument keys, if given, specifies the sequence of events to supply if the command inquires which events were used to invoke it.

Function: command-execute command &optional record-flag keys special
This function executes command. The argument command must satisfy the commandp predicate; i.e., it must be an interactively callable function or a keyboard macro.

A string or vector as command is executed with execute-kbd-macro. A function is passed to call-interactively, along with the optional record-flag.

A symbol is handled by using its function definition in its place. A symbol with an autoload definition counts as a command if it was declared to stand for an interactively callable function. Such a definition is handled by loading the specified library and then rechecking the definition of the symbol.

The argument keys, if given, specifies the sequence of events to supply if the command inquires which events were used to invoke it.

The argument special, if given, means to ignore the prefix argument and not clear it. This is used for executing special events (see section 21.8 Special Events).

Command: execute-extended-command prefix-argument
This function reads a command name from the minibuffer using completing-read (see section 20.5 Completion). Then it uses command-execute to call the specified command. Whatever that command returns becomes the value of execute-extended-command.

If the command asks for a prefix argument, it receives the value prefix-argument. If execute-extended-command is called interactively, the current raw prefix argument is used for prefix-argument, and thus passed on to whatever command is run.

execute-extended-command is the normal definition of M-x, so it uses the string `M-x ' as a prompt. (It would be better to take the prompt from the events used to invoke execute-extended-command, but that is painful to implement.) A description of the value of the prefix argument, if any, also becomes part of the prompt.
(execute-extended-command 1)
---------- Buffer: Minibuffer ----------
1 M-x forward-word RET
---------- Buffer: Minibuffer ----------
     => t
Function: interactive-p
This function returns t if the containing function (the one whose code includes the call to interactive-p) was called interactively, with the function call-interactively. (It makes no difference whether call-interactively was called from Lisp or directly from the editor command loop.) If the containing function was called by Lisp evaluation (or with apply or funcall), then it was not called interactively.

The most common use of interactive-p is for deciding whether to print an informative message. As a special exception, interactive-p returns nil whenever a keyboard macro is being run. This is to suppress the informative messages and speed execution of the macro.

For example:
(defun foo ()
  (interactive)
  (when (interactive-p)
    (message "foo")))
     => foo

(defun bar ()
  (interactive)
  (setq foobar (list (foo) (interactive-p))))
     => bar

;; Type M-x foo.
     -| foo

;; Type M-x bar.
;; This does not print anything.

foobar
     => (nil t)
The other way to do this sort of job is to make the command take an argument print-message which should be non-nil in an interactive call, and use the interactive spec to make sure it is non-nil. Here's how:
(defun foo (&optional print-message)
  (interactive "p")
  (when print-message
    (message "foo")))
The numeric prefix argument, provided by `p', is never nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.4 Information from the Command Loop

The editor command loop sets several Lisp variables to keep status records for itself and for commands that are run.

Variable: last-command
This variable records the name of the previous command executed by the command loop (the one before the current command). Normally the value is a symbol with a function definition, but this is not guaranteed.

The value is copied from this-command when a command returns to the command loop, except when the command has specified a prefix argument for the following command.

This variable is always local to the current terminal and cannot be buffer-local. See section 29.2 Multiple Displays.

Variable: real-last-command
This variable is set up by Emacs just like last-command, but never altered by Lisp programs.

Variable: this-command
This variable records the name of the command now being executed by the editor command loop. Like last-command, it is normally a symbol with a function definition.

The command loop sets this variable just before running a command, and copies its value into last-command when the command finishes (unless the command specified a prefix argument for the following command).

Some commands set this variable during their execution, as a flag for whatever command runs next. In particular, the functions for killing text set this-command to kill-region so that any kill commands immediately following will know to append the killed text to the previous kill.

If you do not want a particular command to be recognized as the previous command in the case where it got an error, you must code that command to prevent this. One way is to set this-command to t at the beginning of the command, and set this-command back to its proper value at the end, like this:
(defun foo (args...)
  (interactive ...)
  (let ((old-this-command this-command))
    (setq this-command t)
    ...do the work...
    (setq this-command old-this-command)))
We do not bind this-command with let because that would restore the old value in case of error--a feature of let which in this case does precisely what we want to avoid.

Function: this-command-keys
This function returns a string or vector containing the key sequence that invoked the present command, plus any previous commands that generated the prefix argument for this command. The value is a string if all those events were characters. See section 21.6 Input Events.
(this-command-keys)
;; Now use C-u C-x C-e to evaluate that.
     => "^U^X^E"
Function: this-command-keys-vector
Like this-command-keys, except that it always returns the events in a vector, so you don't need to deal with the complexities of storing input events in a string (see section 21.6.14 Putting Keyboard Events in Strings).

Function: clear-this-command-keys
This function empties out the table of events for this-command-keys to return, and also empties the records that the function recent-keys (see section 40.8.3 Recording Input) will subsequently return. This is useful after reading a password, to prevent the password from echoing inadvertently as part of the next command in certain cases.

Variable: last-nonmenu-event
This variable holds the last input event read as part of a key sequence, not counting events resulting from mouse menus.

One use of this variable is for telling x-popup-menu where to pop up a menu. It is also used internally by y-or-n-p (see section 20.6 Yes-or-No Queries).

Variable: last-command-event

Variable: last-command-char
This variable is set to the last input event that was read by the command loop as part of a command. The principal use of this variable is in self-insert-command, which uses it to decide which character to insert.
last-command-event
;; Now use C-u C-x C-e to evaluate that.
     => 5
The value is 5 because that is the ASCII code for C-e.

The alias last-command-char exists for compatibility with Emacs version 18.

Variable: last-event-frame
This variable records which frame the last input event was directed to. Usually this is the frame that was selected when the event was generated, but if that frame has redirected input focus to another frame, the value is the frame to which the event was redirected. See section 29.9 Input Focus.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.5 Adjusting Point After Commands

It is not easy to display a value of point in the middle of a sequence of text that has the display or composition property. So after a command finishes and returns to the command loop, if point is within such a sequence, the command loop normally moves point to the edge of the sequence.

A command can inhibit this feature by setting the variable disable-point-adjustment:

Variable: disable-point-adjustment
If this variable is non-nil when a command returns to the command loop, then the command loop does not check for text properties such as display and composition, and does not move point out of sequences that have these properties.

The command loop sets this variable to nil before each command, so if a command sets it, the effect applies only to that command.

Variable: global-disable-point-adjustment
If you set this variable to a non-nil value, the feature of moving point out of these sequences is completely turned off.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6 Input Events

The Emacs command loop reads a sequence of input events that represent keyboard or mouse activity. The events for keyboard activity are characters or symbols; mouse events are always lists. This section describes the representation and meaning of input events in detail.

Function: eventp object
This function returns non-nil if object is an input event or event type.

Note that any symbol might be used as an event or an event type. eventp cannot distinguish whether a symbol is intended by Lisp code to be used as an event. Instead, it distinguishes whether the symbol has actually been used in an event that has been read as input in the current Emacs session. If a symbol has not yet been so used, eventp returns nil.

21.6.1 Keyboard Events

Ordinary characters--keys with symbols on them.

21.6.2 Function Keys

Function keys--keys with names, not symbols.

21.6.3 Mouse Events

Overview of mouse events.

21.6.4 Click Events

Pushing and releasing a mouse button.

21.6.5 Drag Events

Moving the mouse before releasing the button.

21.6.6 Button-Down Events

A button was pushed and not yet released.

21.6.7 Repeat Events

Double and triple click (or drag, or down).

21.6.8 Motion Events

Just moving the mouse, not pushing a button.

21.6.9 Focus Events

Moving the mouse between frames.

21.6.10 Miscellaneous Window System Events

Other events window systems can generate.

21.6.11 Event Examples

Examples of the lists for mouse events.

21.6.12 Classifying Events

Finding the modifier keys in an event symbol. Event types.

21.6.13 Accessing Events

Functions to extract info from events.

21.6.14 Putting Keyboard Events in Strings

Special considerations for putting keyboard character events in a string.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.1 Keyboard Events

There are two kinds of input you can get from the keyboard: ordinary keys, and function keys. Ordinary keys correspond to characters; the events they generate are represented in Lisp as characters. The event type of a character event is the character itself (an integer); see 21.6.12 Classifying Events.

An input character event consists of a basic code between 0 and 524287, plus any or all of these modifier bits:

meta
The 2**27 bit in the character code indicates a character typed with the meta key held down.

control
The 2**26 bit in the character code indicates a non-ASCII control character.
ASCII control characters such as C-a have special basic codes of their own, so Emacs needs no special bit to indicate them. Thus, the code for C-a is just 1.

But if you type a control combination not in ASCII, such as % with the control key, the numeric value you get is the code for % plus 2**26 (assuming the terminal supports non-ASCII control characters).

shift
The 2**25 bit in the character code indicates an ASCII control character typed with the shift key held down.
For letters, the basic code itself indicates upper versus lower case; for digits and punctuation, the shift key selects an entirely different character with a different basic code. In order to keep within the ASCII character set whenever possible, Emacs avoids using the 2**25 bit for those characters.

However, ASCII provides no way to distinguish C-A from C-a, so Emacs uses the 2**25 bit in C-A and not in C-a.

hyper
The 2**24 bit in the character code indicates a character typed with the hyper key held down.

super
The 2**23 bit in the character code indicates a character typed with the super key held down.

alt
The 2**22 bit in the character code indicates a character typed with the alt key held down. (On some terminals, the key labeled ALT is actually the meta key.)
It is best to avoid mentioning specific bit numbers in your program. To test the modifier bits of a character, use the function event-modifiers (see section 21.6.12 Classifying Events). When making key bindings, you can use the read syntax for characters with modifier bits (`\C-', `\M-', and so on). For making key bindings with define-key, you can use lists such as (control hyper ?x) to specify the characters (see section 22.9 Changing Key Bindings). The function event-convert-list converts such a list into an event type (see section 21.6.12 Classifying Events).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.2 Function Keys

Most keyboards also have function keys---keys that have names or symbols that are not characters. Function keys are represented in Emacs Lisp as symbols; the symbol's name is the function key's label, in lower case. For example, pressing a key labeled F1 places the symbol f1 in the input stream.

The event type of a function key event is the event symbol itself. See section 21.6.12 Classifying Events.

Here are a few special cases in the symbol-naming convention for function keys:

backspace, tab, newline, return, delete
These keys correspond to common ASCII control characters that have special keys on most keyboards.
In ASCII, C-i and TAB are the same character. If the terminal can distinguish between them, Emacs conveys the distinction to Lisp programs by representing the former as the integer 9, and the latter as the symbol tab.

Most of the time, it's not useful to distinguish the two. So normally function-key-map (see section 40.8.2 Translating Input Events) is set up to map tab into 9. Thus, a key binding for character code 9 (the character C-i) also applies to tab. Likewise for the other symbols in this group. The function read-char likewise converts these events into characters.

In ASCII, BS is really C-h. But backspace converts into the character code 127 (DEL), not into code 8 (BS). This is what most users prefer.

left, up, right, down
Cursor arrow keys
kp-add, kp-decimal, kp-divide, ...
Keypad keys (to the right of the regular keyboard).
kp-0, kp-1, ...
Keypad keys with digits.
kp-f1, kp-f2, kp-f3, kp-f4
Keypad PF keys.
kp-home, kp-left, kp-up, kp-right, kp-down
Keypad arrow keys. Emacs normally translates these into the corresponding non-keypad keys home, left, ...
kp-prior, kp-next, kp-end, kp-begin, kp-insert, kp-delete
Additional keypad duplicates of keys ordinarily found elsewhere. Emacs normally translates these into the like-named non-keypad keys.
You can use the modifier keys ALT, CTRL, HYPER, META, SHIFT, and SUPER with function keys. The way to represent them is with prefixes in the symbol name:

`A-'
The alt modifier.
`C-'
The control modifier.
`H-'
The hyper modifier.
`M-'
The meta modifier.
`S-'
The shift modifier.
`s-'
The super modifier.
Thus, the symbol for the key F3 with META held down is M-f3. When you use more than one prefix, we recommend you write them in alphabetical order; but the order does not matter in arguments to the key-binding lookup and modification functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.3 Mouse Events

Emacs supports four kinds of mouse events: click events, drag events, button-down events, and motion events. All mouse events are represented as lists. The CAR of the list is the event type; this says which mouse button was involved, and which modifier keys were used with it. The event type can also distinguish double or triple button presses (see section 21.6.7 Repeat Events). The rest of the list elements give position and time information.

For key lookup, only the event type matters: two events of the same type necessarily run the same command. The command can access the full values of these events using the `e' interactive code. See section 21.2.2 Code Characters for interactive.

A key sequence that starts with a mouse event is read using the keymaps of the buffer in the window that the mouse was in, not the current buffer. This does not imply that clicking in a window selects that window or its buffer--that is entirely under the control of the command binding of the key sequence.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.4 Click Events

When the user presses a mouse button and releases it at the same location, that generates a click event. Mouse click events have this form:
(event-type
 (window buffer-pos (x . y) timestamp)
 click-count)
Here is what the elements normally mean:

event-type
This is a symbol that indicates which mouse button was used. It is one of the symbols mouse-1, mouse-2, ..., where the buttons are numbered left to right.
You can also use prefixes `A-', `C-', `H-', `M-', `S-' and `s-' for modifiers alt, control, hyper, meta, shift and super, just as you would with function keys.

This symbol also serves as the event type of the event. Key bindings describe events by their types; thus, if there is a key binding for mouse-1, that binding would apply to all events whose event-type is mouse-1.

window
This is the window in which the click occurred.

x, y
These are the pixel-denominated coordinates of the click, relative to the top left corner of window, which is (0 . 0).

buffer-pos
This is the buffer position of the character clicked on.

timestamp
This is the time at which the event occurred, in milliseconds. (Since this value wraps around the entire range of Emacs Lisp integers in about five hours, it is useful only for relating the times of nearby events.)

click-count
This is the number of rapid repeated presses so far of the same mouse button. See section 21.6.7 Repeat Events.
The meanings of buffer-pos, x and y are somewhat different when the event location is in a special part of the screen, such as the mode line or a scroll bar.

If the location is in a scroll bar, then buffer-pos is the symbol vertical-scroll-bar or horizontal-scroll-bar, and the pair (x . y) is replaced with a pair (portion . whole), where portion is the distance of the click from the top or left end of the scroll bar, and whole is the length of the entire scroll bar.

If the position is on a mode line or the vertical line separating window from its neighbor to the right, then buffer-pos is the symbol mode-line, header-line, or vertical-line. For the mode line, y does not have meaningful data. For the vertical line, x does not have meaningful data.

In one special case, buffer-pos is a list containing a symbol (one of the symbols listed above) instead of just the symbol. This happens after the imaginary prefix keys for the event are inserted into the input stream. See section 21.7.1 Key Sequence Input.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.5 Drag Events

With Emacs, you can have a drag event without even changing your clothes. A drag event happens every time the user presses a mouse button and then moves the mouse to a different character position before releasing the button. Like all mouse events, drag events are represented in Lisp as lists. The lists record both the starting mouse position and the final position, like this:
(event-type
 (window1 buffer-pos1 (x1 . y1) timestamp1)
 (window2 buffer-pos2 (x2 . y2) timestamp2)
 click-count)
For a drag event, the name of the symbol event-type contains the prefix `drag-'. For example, dragging the mouse with button 2 held down generates a drag-mouse-2 event. The second and third elements of the event give the starting and ending position of the drag. Aside from that, the data have the same meanings as in a click event (see section 21.6.4 Click Events). You can access the second element of any mouse event in the same way, with no need to distinguish drag events from others.

The `drag-' prefix follows the modifier key prefixes such as `C-' and `M-'.

If read-key-sequence receives a drag event that has no key binding, and the corresponding click event does have a binding, it changes the drag event into a click event at the drag's starting position. This means that you don't have to distinguish between click and drag events unless you want to.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.6 Button-Down Events

Click and drag events happen when the user releases a mouse button. They cannot happen earlier, because there is no way to distinguish a click from a drag until the button is released.

If you want to take action as soon as a button is pressed, you need to handle button-down events.(5) These occur as soon as a button is pressed. They are represented by lists that look exactly like click events (see section 21.6.4 Click Events), except that the event-type symbol name contains the prefix `down-'. The `down-' prefix follows modifier key prefixes such as `C-' and `M-'.

The function read-key-sequence ignores any button-down events that don't have command bindings; therefore, the Emacs command loop ignores them too. This means that you need not worry about defining button-down events unless you want them to do something. The usual reason to define a button-down event is so that you can track mouse motion (by reading motion events) until the button is released. See section 21.6.8 Motion Events.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.7 Repeat Events

If you press the same mouse button more than once in quick succession without moving the mouse, Emacs generates special repeat mouse events for the second and subsequent presses.

The most common repeat events are double-click events. Emacs generates a double-click event when you click a button twice; the event happens when you release the button (as is normal for all click events).

The event type of a double-click event contains the prefix `double-'. Thus, a double click on the second mouse button with meta held down comes to the Lisp program as M-double-mouse-2. If a double-click event has no binding, the binding of the corresponding ordinary click event is used to execute it. Thus, you need not pay attention to the double click feature unless you really want to.

When the user performs a double click, Emacs generates first an ordinary click event, and then a double-click event. Therefore, you must design the command binding of the double click event to assume that the single-click command has already run. It must produce the desired results of a double click, starting from the results of a single click.

This is convenient, if the meaning of a double click somehow "builds on" the meaning of a single click--which is recommended user interface design practice for double clicks.

If you click a button, then press it down again and start moving the mouse with the button held down, then you get a double-drag event when you ultimately release the button. Its event type contains `double-drag' instead of just `drag'. If a double-drag event has no binding, Emacs looks for an alternate binding as if the event were an ordinary drag.

Before the double-click or double-drag event, Emacs generates a double-down event when the user presses the button down for the second time. Its event type contains `double-down' instead of just `down'. If a double-down event has no binding, Emacs looks for an alternate binding as if the event were an ordinary button-down event. If it finds no binding that way either, the double-down event is ignored.

To summarize, when you click a button and then press it again right away, Emacs generates a down event and a click event for the first click, a double-down event when you press the button again, and finally either a double-click or a double-drag event.

If you click a button twice and then press it again, all in quick succession, Emacs generates a triple-down event, followed by either a triple-click or a triple-drag. The event types of these events contain `triple' instead of `double'. If any triple event has no binding, Emacs uses the binding that it would use for the corresponding double event.

If you click a button three or more times and then press it again, the events for the presses beyond the third are all triple events. Emacs does not have separate event types for quadruple, quintuple, etc. events. However, you can look at the event list to find out precisely how many times the button was pressed.

Function: event-click-count event
This function returns the number of consecutive button presses that led up to event. If event is a double-down, double-click or double-drag event, the value is 2. If event is a triple event, the value is 3 or greater. If event is an ordinary mouse event (not a repeat event), the value is 1.

Variable: double-click-fuzz
To generate repeat events, successive mouse button presses must be at approximately the same screen position. The value of double-click-fuzz specifies the maximum number of pixels the mouse may be moved between two successive clicks to make a double-click.

Variable: double-click-time
To generate repeat events, the number of milliseconds between successive button presses must be less than the value of double-click-time. Setting double-click-time to nil disables multi-click detection entirely. Setting it to t removes the time limit; Emacs then detects multi-clicks by position only.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.8 Motion Events

Emacs sometimes generates mouse motion events to describe motion of the mouse without any button activity. Mouse motion events are represented by lists that look like this:
(mouse-movement (window buffer-pos (x . y) timestamp))
The second element of the list describes the current position of the mouse, just as in a click event (see section 21.6.4 Click Events).

The special form track-mouse enables generation of motion events within its body. Outside of track-mouse forms, Emacs does not generate events for mere motion of the mouse, and these events do not appear. See section 29.13 Mouse Tracking.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.9 Focus Events

Window systems provide general ways for the user to control which window gets keyboard input. This choice of window is called the focus. When the user does something to switch between Emacs frames, that generates a focus event. The normal definition of a focus event, in the global keymap, is to select a new frame within Emacs, as the user would expect. See section 29.9 Input Focus.

Focus events are represented in Lisp as lists that look like this:
(switch-frame new-frame)
where new-frame is the frame switched to.

Most X window managers are set up so that just moving the mouse into a window is enough to set the focus there. Emacs appears to do this, because it changes the cursor to solid in the new frame. However, there is no need for the Lisp program to know about the focus change until some other kind of input arrives. So Emacs generates a focus event only when the user actually types a keyboard key or presses a mouse button in the new frame; just moving the mouse between frames does not generate a focus event.

A focus event in the middle of a key sequence would garble the sequence. So Emacs never generates a focus event in the middle of a key sequence. If the user changes focus in the middle of a key sequence--that is, after a prefix key--then Emacs reorders the events so that the focus event comes either before or after the multi-event key sequence, and not within it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.10 Miscellaneous Window System Events

A few other event types represent occurrences within the window system.

(delete-frame (frame))
This kind of event indicates that the user gave the window manager a command to delete a particular window, which happens to be an Emacs frame.
The standard definition of the delete-frame event is to delete frame.

(iconify-frame (frame))
This kind of event indicates that the user iconified frame using the window manager. Its standard definition is ignore; since the frame has already been iconified, Emacs has no work to do. The purpose of this event type is so that you can keep track of such events if you want to.

(make-frame-visible (frame))
This kind of event indicates that the user deiconified frame using the window manager. Its standard definition is ignore; since the frame has already been made visible, Emacs has no work to do.

(mouse-wheel position delta)
This kind of event is generated by moving a wheel on a mouse (such as the MS Intellimouse). Its effect is typically a kind of scroll or zoom.
The element delta describes the amount and direction of the wheel rotation. Its absolute value is the number of increments by which the wheel was rotated. A negative delta indicates that the wheel was rotated backwards, towards the user, and a positive delta indicates that the wheel was rotated forward, away from the user.

The element position is a list describing the position of the event, in the same format as used in a mouse-click event.

This kind of event is generated only on some kinds of systems.

(drag-n-drop position files)
This kind of event is generated when a group of files is selected in an application outside of Emacs, and then dragged and dropped onto an Emacs frame.
The element position is a list describing the position of the event, in the same format as used in a mouse-click event, and files is the list of file names that were dragged and dropped. The usual way to handle this event is by visiting these files.

This kind of event is generated, at present, only on some kinds of systems.
If one of these events arrives in the middle of a key sequence--that is, after a prefix key--then Emacs reorders the events so that this event comes either before or after the multi-event key sequence, not within it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.11 Event Examples

If the user presses and releases the left mouse button over the same location, that generates a sequence of events like this:
(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
(mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))
While holding the control key down, the user might hold down the second mouse button, and drag the mouse from one line to the next. That produces two events, as shown here:
(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
                (#<window 18 on NEWS> 3510 (0 . 28) -729648))
While holding down the meta and shift keys, the user might press the second mouse button on the window's mode line, and then drag the mouse into another window. That produces a pair of events like these:
(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
                  (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
                   -453816))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.12 Classifying Events

Every event has an event type, which classifies the event for key binding purposes. For a keyboard event, the event type equals the event value; thus, the event type for a character is the character, and the event type for a function key symbol is the symbol itself. For events that are lists, the event type is the symbol in the CAR of the list. Thus, the event type is always a symbol or a character.

Two events of the same type are equivalent where key bindings are concerned; thus, they always run the same command. That does not necessarily mean they do the same things, however, as some commands look at the whole event to decide what to do. For example, some commands use the location of a mouse event to decide where in the buffer to act.

Sometimes broader classifications of events are useful. For example, you might want to ask whether an event involved the META key, regardless of which other key or mouse button was used.

The functions event-modifiers and event-basic-type are provided to get such information conveniently.

Function: event-modifiers event
This function returns a list of the modifiers that event has. The modifiers are symbols; they include shift, control, meta, alt, hyper and super. In addition, the modifiers list of a mouse event symbol always contains one of click, drag, and down.

The argument event may be an entire event object, or just an event type.

Here are some examples:
(event-modifiers ?a)
     => nil
(event-modifiers ?\C-a)
     => (control)
(event-modifiers ?\C-%)
     => (control)
(event-modifiers ?\C-\S-a)
     => (control shift)
(event-modifiers 'f5)
     => nil
(event-modifiers 's-f5)
     => (super)
(event-modifiers 'M-S-f5)
     => (meta shift)
(event-modifiers 'mouse-1)
     => (click)
(event-modifiers 'down-mouse-1)
     => (down)
The modifiers list for a click event explicitly contains click, but the event symbol name itself does not contain `click'.

Function: event-basic-type event
This function returns the key or mouse button that event describes, with all modifiers removed. For example:
(event-basic-type ?a)
     => 97
(event-basic-type ?A)
     => 97
(event-basic-type ?\C-a)
     => 97
(event-basic-type ?\C-\S-a)
     => 97
(event-basic-type 'f5)
     => f5
(event-basic-type 's-f5)
     => f5
(event-basic-type 'M-S-f5)
     => f5
(event-basic-type 'down-mouse-1)
     => mouse-1
Function: mouse-movement-p object
This function returns non-nil if object is a mouse movement event.

Function: event-convert-list list
This function converts a list of modifier names and a basic event type to an event type which specifies all of them. For example,
(event-convert-list '(control ?a))
     => 1
(event-convert-list '(control meta ?a))
     => -134217727
(event-convert-list '(control super f1))
     => C-s-f1
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.13 Accessing Events

This section describes convenient functions for accessing the data in a mouse button or motion event.

These two functions return the starting or ending position of a mouse-button event, as a list of this form:
(window buffer-position (x . y) timestamp)
Function: event-start event
This returns the starting position of event.

If event is a click or button-down event, this returns the location of the event. If event is a drag event, this returns the drag's starting position.

Function: event-end event
This returns the ending position of event.

If event is a drag event, this returns the position where the user released the mouse button. If event is a click or button-down event, the value is actually the starting position, which is the only position such events have.

These five functions take a position list as described above, and return various parts of it.

Function: posn-window position
Return the window that position is in.

Function: posn-point position
Return the buffer position in position. This is an integer.

Function: posn-x-y position
Return the pixel-based x and y coordinates in position, as a cons cell (x . y).

Function: posn-col-row position
Return the row and column (in units of characters) of position, as a cons cell (col . row). These are computed from the x and y values actually found in position.

Function: posn-timestamp position
Return the timestamp in position.

These functions are useful for decoding scroll bar events.

Function: scroll-bar-event-ratio event
This function returns the fractional vertical position of a scroll bar event within the scroll bar. The value is a cons cell (portion . whole) containing two integers whose ratio is the fractional position.

Function: scroll-bar-scale ratio total
This function multiplies (in effect) ratio by total, rounding the result to an integer. The argument ratio is not a number, but rather a pair (num . denom)---typically a value returned by scroll-bar-event-ratio.

This function is handy for scaling a position on a scroll bar into a buffer position. Here's how to do that:
(+ (point-min)
   (scroll-bar-scale
      (posn-x-y (event-start event))
      (- (point-max) (point-min))))
Recall that scroll bar events have two integers forming a ratio, in place of a pair of x and y coordinates.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.6.14 Putting Keyboard Events in Strings

In most of the places where strings are used, we conceptualize the string as containing text characters--the same kind of characters found in buffers or files. Occasionally Lisp programs use strings that conceptually contain keyboard characters; for example, they may be key sequences or keyboard macro definitions. However, storing keyboard characters in a string is a complex matter, for reasons of historical compatibility, and it is not always possible.

We recommend that new programs avoid dealing with these complexities by not storing keyboard events in strings. Here is how to do that:

Use vectors instead of strings for key sequences, when you plan to use them for anything other than as arguments to lookup-key and define-key. For example, you can use read-key-sequence-vector instead of read-key-sequence, and this-command-keys-vector instead of this-command-keys.

Use vectors to write key sequence constants containing meta characters, even when passing them directly to define-key.

When you have to look at the contents of a key sequence that might be a string, use listify-key-sequence (see section 21.7.5 Miscellaneous Event Input Features) first, to convert it to a list.

The complexities stem from the modifier bits that keyboard input characters can include. Aside from the Meta modifier, none of these modifier bits can be included in a string, and the Meta modifier is allowed only in special cases.

The earliest GNU Emacs versions represented meta characters as codes in the range of 128 to 255. At that time, the basic character codes ranged from 0 to 127, so all keyboard character codes did fit in a string. Many Lisp programs used `\M-' in string constants to stand for meta characters, especially in arguments to define-key and similar functions, and key sequences and sequences of events were always represented as strings.

When we added support for larger basic character codes beyond 127, and additional modifier bits, we had to change the representation of meta characters. Now the flag that represents the Meta modifier in a character is 2**27 and such numbers cannot be included in a string.

To support programs with `\M-' in string constants, there are special rules for including certain meta characters in a string. Here are the rules for interpreting a string as a sequence of input characters:

If the keyboard character value is in the range of 0 to 127, it can go in the string unchanged.

The meta variants of those characters, with codes in the range of 2**27 to 2**27+127, can also go in the string, but you must change their numeric values. You must set the 2**7 bit instead of the 2**27 bit, resulting in a value between 128 and 255. Only a unibyte string can include these codes.

Non-ASCII characters above 256 can be included in a multibyte string.

Other keyboard character events cannot fit in a string. This includes keyboard events in the range of 128 to 255.

Functions such as read-key-sequence that construct strings of keyboard input characters follow these rules: they construct vectors instead of strings, when the events won't fit in a string.

When you use the read syntax `\M-' in a string, it produces a code in the range of 128 to 255--the same code that you get if you modify the corresponding keyboard event to put it in the string. Thus, meta events in strings work consistently regardless of how they get into the strings.

However, most programs would do well to avoid these issues by following the recommendations at the beginning of this section.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.7 Reading Input

The editor command loop reads key sequences using the function read-key-sequence, which uses read-event. These and other functions for event input are also available for use in Lisp programs. See also momentary-string-display in 38.8 Temporary Displays, and sit-for in 21.9 Waiting for Elapsed Time or Input. See section 40.8 Terminal Input, for functions and variables for controlling terminal input modes and debugging terminal input. See section 40.8.2 Translating Input Events, for features you can use for translating or modifying input events while reading them.

For higher-level input facilities, see 20. Minibuffers.

21.7.1 Key Sequence Input

How to read one key sequence.

21.7.2 Reading One Event

How to read just one event.

21.7.3 Invoking the Input Method

How reading an event uses the input method.

21.7.4 Quoted Character Input

Asking the user to specify a character.

21.7.5 Miscellaneous Event Input Features

How to reread or throw away input events.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.7.1 Key Sequence Input

The command loop reads input a key sequence at a time, by calling read-key-sequence. Lisp programs can also call this function; for example, describe-key uses it to read the key to describe.

Function: read-key-sequence prompt
This function reads a key sequence and returns it as a string or vector. It keeps reading events until it has accumulated a complete key sequence; that is, enough to specify a non-prefix command using the currently active keymaps.

If the events are all characters and all can fit in a string, then read-key-sequence returns a string (see section 21.6.14 Putting Keyboard Events in Strings). Otherwise, it returns a vector, since a vector can hold all kinds of events--characters, symbols, and lists. The elements of the string or vector are the events in the key sequence.

The argument prompt is either a string to be displayed in the echo area as a prompt, or nil, meaning not to display a prompt.

In the example below, the prompt `?' is displayed in the echo area, and the user types C-x C-f.
(read-key-sequence "?")

---------- Echo Area ----------
?C-x C-f
---------- Echo Area ----------

     => "^X^F"
The function read-key-sequence suppresses quitting: C-g typed while reading with this function works like any other character, and does not set quit-flag. See section 21.10 Quitting.

Function: read-key-sequence-vector prompt
This is like read-key-sequence except that it always returns the key sequence as a vector, never as a string. See section 21.6.14 Putting Keyboard Events in Strings.

If an input character is an upper-case letter and has no key binding, but its lower-case equivalent has one, then read-key-sequence converts the character to lower case. Note that lookup-key does not perform case conversion in this way.

The function read-key-sequence also transforms some mouse events. It converts unbound drag events into click events, and discards unbound button-down events entirely. It also reshuffles focus events and miscellaneous window events so that they never appear in a key sequence with any other events.

When mouse events occur in special parts of a window, such as a mode line or a scroll bar, the event type shows nothing special--it is the same symbol that would normally represent that combination of mouse button and modifier keys. The information about the window part is kept elsewhere in the event--in the coordinates. But read-key-sequence translates this information into imaginary "prefix keys", all of which are symbols: header-line, horizontal-scroll-bar, menu-bar, mode-line, vertical-line, and vertical-scroll-bar. You can define meanings for mouse clicks in special window parts by defining key sequences using these imaginary prefix keys.

For example, if you call read-key-sequence and then click the mouse on the window's mode line, you get two events, like this:
(read-key-sequence "Click on the mode line: ")
     => [mode-line
         (mouse-1
          (#<window 6 on NEWS> mode-line
           (40 . 63) 5959987))]
Variable: num-input-keys
This variable's value is the number of key sequences processed so far in this Emacs session. This includes key sequences read from the terminal and key sequences read from keyboard macros being executed.

Variable: num-nonmacro-input-events
This variable holds the total number of input events received so far from the terminal--not counting those generated by keyboard macros.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.7.2 Reading One Event

The lowest level functions for command input are those that read a single event.

Function: read-event &optional prompt inherit-input-method
This function reads and returns the next event of command input, waiting if necessary until an event is available. Events can come directly from the user or from a keyboard macro.

If the optional argument prompt is non-nil, it should be a string to display in the echo area as a prompt. Otherwise, read-event does not display any message to indicate it is waiting for input; instead, it prompts by echoing: it displays descriptions of the events that led to or were read by the current command. See section 38.4 The Echo Area.

If inherit-input-method is non-nil, then the current input method (if any) is employed to make it possible to enter a non-ASCII character. Otherwise, input method handling is disabled for reading this event.

If cursor-in-echo-area is non-nil, then read-event moves the cursor temporarily to the echo area, to the end of any message displayed there. Otherwise read-event does not move the cursor.

If read-event gets an event that is defined as a help character, in some cases read-event processes the event directly without returning. See section 24.5 Help Functions. Certain other events, called special events, are also processed directly within read-event (see section 21.8 Special Events).

Here is what happens if you call read-event and then press the right-arrow function key:
(read-event)
     => right
Function: read-char &optional prompt inherit-input-method
This function reads and returns a character of command input. If the user generates an event which is not a character (i.e. a mouse click or function key event), read-char signals an error. The arguments work as in read-event.

In the first example, the user types the character 1 (ASCII code 49). The second example shows a keyboard macro definition that calls read-char from the minibuffer using eval-expression. read-char reads the keyboard macro's very next character, which is 1. Then eval-expression displays its return value in the echo area.
(read-char)
     => 49

;; We assume here you use M-: to evaluate this.
(symbol-function 'foo)
     => "^[:(read-char)^M1"
(execute-kbd-macro 'foo)
     -| 49
     => nil
Function: read-char-exclusive &optional prompt inherit-input-method
This function reads and returns a character of command input. If the user generates an event which is not a character, read-char-exclusive ignores it and reads another event, until it gets a character. The arguments work as in read-event.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.7.3 Invoking the Input Method

The event-reading functions invoke the current input method, if any (see section 33.11 Input Methods). If the value of input-method-function is non-nil, it should be a function; when read-event reads a printing character (including SPC) with no modifier bits, it calls that function, passing the character as an argument.

Variable: input-method-function
If this is non-nil, its value specifies the current input method function.

Note: Don't bind this variable with let. It is often buffer-local, and if you bind it around reading input (which is exactly when you would bind it), switching buffers asynchronously while Emacs is waiting will cause the value to be restored in the wrong buffer.

The input method function should return a list of events which should be used as input. (If the list is nil, that means there is no input, so read-event waits for another event.) These events are processed before the events in unread-command-events (see section 21.7.5 Miscellaneous Event Input Features). Events returned by the input method function are not passed to the input method function again, even if they are printing characters with no modifier bits.

If the input method function calls read-event or read-key-sequence, it should bind input-method-function to nil first, to prevent recursion.

The input method function is not called when reading the second and subsequent events of a key sequence. Thus, these characters are not subject to input method processing. The input method function should test the values of overriding-local-map and overriding-terminal-local-map; if either of these variables is non-nil, the input method should put its argument into a list and return that list with no further processing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.7.4 Quoted Character Input

You can use the function read-quoted-char to ask the user to specify a character, and allow the user to specify a control or meta character conveniently, either literally or as an octal character code. The command quoted-insert uses this function.

Function: read-quoted-char &optional prompt
This function is like read-char, except that if the first character read is an octal digit (0-7), it reads any number of octal digits (but stopping if a non-octal digit is found), and returns the character represented by that numeric character code.

Quitting is suppressed when the first character is read, so that the user can enter a C-g. See section 21.10 Quitting.

If prompt is supplied, it specifies a string for prompting the user. The prompt string is always displayed in the echo area, followed by a single `-'.

In the following example, the user types in the octal number 177 (which is 127 in decimal).
(read-quoted-char "What character")

---------- Echo Area ----------
What character-177
---------- Echo Area ----------

     => 127
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.7.5 Miscellaneous Event Input Features

This section describes how to "peek ahead" at events without using them up, how to check for pending input, and how to discard pending input. See also the function read-passwd (see section 20.8 Reading a Password).

Variable: unread-command-events
This variable holds a list of events waiting to be read as command input. The events are used in the order they appear in the list, and removed one by one as they are used.

The variable is needed because in some cases a function reads an event and then decides not to use it. Storing the event in this variable causes it to be processed normally, by the command loop or by the functions to read command input.

For example, the function that implements numeric prefix arguments reads any number of digits. When it finds a non-digit event, it must unread the event so that it can be read normally by the command loop. Likewise, incremental search uses this feature to unread events with no special meaning in a search, because these events should exit the search and then execute normally.

The reliable and easy way to extract events from a key sequence so as to put them in unread-command-events is to use listify-key-sequence (see section 21.6.14 Putting Keyboard Events in Strings).

Normally you add events to the front of this list, so that the events most recently unread will be reread first.

Function: listify-key-sequence key
This function converts the string or vector key to a list of individual events, which you can put in unread-command-events.

Variable: unread-command-char
This variable holds a character to be read as command input. A value of -1 means "empty".

This variable is mostly obsolete now that you can use unread-command-events instead; it exists only to support programs written for Emacs versions 18 and earlier.

Function: input-pending-p
This function determines whether any command input is currently available to be read. It returns immediately, with value t if there is available input, nil otherwise. On rare occasions it may return t when no input is available.

Variable: last-input-event

Variable: last-input-char
This variable records the last terminal input event read, whether as part of a command or explicitly by a Lisp program.

In the example below, the Lisp program reads the character 1, ASCII code 49. It becomes the value of last-input-event, while C-e (we assume C-x C-e command is used to evaluate this expression) remains the value of last-command-event.
(progn (print (read-char))
       (print last-command-event)
       last-input-event)
     -| 49
     -| 5
     => 49
The alias last-input-char exists for compatibility with Emacs version 18.

Function: discard-input
This function discards the contents of the terminal input buffer and cancels any keyboard macro that might be in the process of definition. It returns nil.

In the following example, the user may type a number of characters right after starting the evaluation of the form. After the sleep-for finishes sleeping, discard-input discards any characters typed during the sleep.
(progn (sleep-for 2)
       (discard-input))
     => nil
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.8 Special Events

Special events are handled at a very low level--as soon as they are read. The read-event function processes these events itself, and never returns them.

Events that are handled in this way do not echo, they are never grouped into key sequences, and they never appear in the value of last-command-event or (this-command-keys). They do not discard a numeric argument, they cannot be unread with unread-command-events, they may not appear in a keyboard macro, and they are not recorded in a keyboard macro while you are defining one.

These events do, however, appear in last-input-event immediately after they are read, and this is the way for the event's definition to find the actual event.

The events types iconify-frame, make-frame-visible and delete-frame are normally handled in this way. The keymap which defines how to handle special events--and which events are special--is in the variable special-event-map (see section 22.6 Active Keymaps).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.9 Waiting for Elapsed Time or Input

The wait functions are designed to wait for a certain amount of time to pass or until there is input. For example, you may wish to pause in the middle of a computation to allow the user time to view the display. sit-for pauses and updates the screen, and returns immediately if input comes in, while sleep-for pauses without updating the screen.

Function: sit-for seconds &optional millisec nodisp
This function performs redisplay (provided there is no pending input from the user), then waits seconds seconds, or until input is available. The value is t if sit-for waited the full time with no input arriving (see input-pending-p in 21.7.5 Miscellaneous Event Input Features). Otherwise, the value is nil.

The argument seconds need not be an integer. If it is a floating point number, sit-for waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, seconds is rounded down.

The optional argument millisec specifies an additional waiting period measured in milliseconds. This adds to the period specified by seconds. If the system doesn't support waiting fractions of a second, you get an error if you specify nonzero millisec.

The expression (sit-for 0) is a convenient way to request a redisplay, without any delay. See section 38.2 Forcing Redisplay.

If nodisp is non-nil, then sit-for does not redisplay, but it still returns as soon as input is available (or when the timeout elapses).

Iconifying or deiconifying a frame makes sit-for return, because that generates an event. See section 21.6.10 Miscellaneous Window System Events.

The usual purpose of sit-for is to give the user time to read text that you display.

Function: sleep-for seconds &optional millisec
This function simply pauses for seconds seconds without updating the display. It pays no attention to available input. It returns nil.

The argument seconds need not be an integer. If it is a floating point number, sleep-for waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, seconds is rounded down.

The optional argument millisec specifies an additional waiting period measured in milliseconds. This adds to the period specified by seconds. If the system doesn't support waiting fractions of a second, you get an error if you specify nonzero millisec.

Use sleep-for when you wish to guarantee a delay.

See section 40.5 Time of Day, for functions to get the current time.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.10 Quitting

Typing C-g while a Lisp function is running causes Emacs to quit whatever it is doing. This means that control returns to the innermost active command loop.

Typing C-g while the command loop is waiting for keyboard input does not cause a quit; it acts as an ordinary input character. In the simplest case, you cannot tell the difference, because C-g normally runs the command keyboard-quit, whose effect is to quit. However, when C-g follows a prefix key, they combine to form an undefined key. The effect is to cancel the prefix key as well as any prefix argument.

In the minibuffer, C-g has a different definition: it aborts out of the minibuffer. This means, in effect, that it exits the minibuffer and then quits. (Simply quitting would return to the command loop within the minibuffer.) The reason why C-g does not quit directly when the command reader is reading input is so that its meaning can be redefined in the minibuffer in this way. C-g following a prefix key is not redefined in the minibuffer, and it has its normal effect of canceling the prefix key and prefix argument. This too would not be possible if C-g always quit directly.

When C-g does directly quit, it does so by setting the variable quit-flag to t. Emacs checks this variable at appropriate times and quits if it is not nil. Setting quit-flag non-nil in any way thus causes a quit.

At the level of C code, quitting cannot happen just anywhere; only at the special places that check quit-flag. The reason for this is that quitting at other places might leave an inconsistency in Emacs's internal state. Because quitting is delayed until a safe place, quitting cannot make Emacs crash.

Certain functions such as read-key-sequence or read-quoted-char prevent quitting entirely even though they wait for input. Instead of quitting, C-g serves as the requested input. In the case of read-key-sequence, this serves to bring about the special behavior of C-g in the command loop. In the case of read-quoted-char, this is so that C-q can be used to quote a C-g.

You can prevent quitting for a portion of a Lisp function by binding the variable inhibit-quit to a non-nil value. Then, although C-g still sets quit-flag to t as usual, the usual result of this--a quit--is prevented. Eventually, inhibit-quit will become nil again, such as when its binding is unwound at the end of a let form. At that time, if quit-flag is still non-nil, the requested quit happens immediately. This behavior is ideal when you wish to make sure that quitting does not happen within a "critical section" of the program.

In some functions (such as read-quoted-char), C-g is handled in a special way that does not involve quitting. This is done by reading the input with inhibit-quit bound to t, and setting quit-flag to nil before inhibit-quit becomes nil again. This excerpt from the definition of read-quoted-char shows how this is done; it also shows that normal quitting is permitted after the first character of input.
(defun read-quoted-char (&optional prompt)
  "...documentation..."
  (let ((message-log-max nil) done (first t) (code 0) char)
    (while (not done)
      (let ((inhibit-quit first)
            ...)
    (and prompt (message "%s-" prompt))
    (setq char (read-event))
    (if inhibit-quit (setq quit-flag nil)))
      ...set the variable code...)
    code))
Variable: quit-flag
If this variable is non-nil, then Emacs quits immediately, unless inhibit-quit is non-nil. Typing C-g ordinarily sets quit-flag non-nil, regardless of inhibit-quit.

Variable: inhibit-quit
This variable determines whether Emacs should quit when quit-flag is set to a value other than nil. If inhibit-quit is non-nil, then quit-flag has no special effect.

Command: keyboard-quit
This function signals the quit condition with (signal 'quit nil). This is the same thing that quitting does. (See signal in 10.5.3 Errors.)

You can specify a character other than C-g to use for quitting. See the function set-input-mode in 40.8 Terminal Input.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.11 Prefix Command Arguments

Most Emacs commands can use a prefix argument, a number specified before the command itself. (Don't confuse prefix arguments with prefix keys.) The prefix argument is at all times represented by a value, which may be nil, meaning there is currently no prefix argument. Each command may use the prefix argument or ignore it.

There are two representations of the prefix argument: raw and numeric. The editor command loop uses the raw representation internally, and so do the Lisp variables that store the information, but commands can request either representation.

Here are the possible values of a raw prefix argument:

nil, meaning there is no prefix argument. Its numeric value is 1, but numerous commands make a distinction between nil and the integer 1.

An integer, which stands for itself.

A list of one element, which is an integer. This form of prefix argument results from one or a succession of C-u's with no digits. The numeric value is the integer in the list, but some commands make a distinction between such a list and an integer alone.

The symbol -. This indicates that M-- or C-u - was typed, without following digits. The equivalent numeric value is -1, but some commands make a distinction between the integer -1 and the symbol -.

We illustrate these possibilities by calling the following function with various prefixes:
(defun display-prefix (arg)
  "Display the value of the raw prefix arg."
  (interactive "P")
  (message "%s" arg))
Here are the results of calling display-prefix with various raw prefix arguments:
        M-x display-prefix  -| nil

C-u     M-x display-prefix  -| (4)

C-u C-u M-x display-prefix  -| (16)

C-u 3   M-x display-prefix  -| 3

M-3     M-x display-prefix  -| 3      ; (Same as C-u 3.)

C-u -   M-x display-prefix  -| -

M--     M-x display-prefix  -| -      ; (Same as C-u -.)

C-u - 7 M-x display-prefix  -| -7

M-- 7   M-x display-prefix  -| -7     ; (Same as C-u -7.)
Emacs uses two variables to store the prefix argument: prefix-arg and current-prefix-arg. Commands such as universal-argument that set up prefix arguments for other commands store them in prefix-arg. In contrast, current-prefix-arg conveys the prefix argument to the current command, so setting it has no effect on the prefix arguments for future commands.

Normally, commands specify which representation to use for the prefix argument, either numeric or raw, in the interactive declaration. (See section 21.2.1 Using interactive.) Alternatively, functions may look at the value of the prefix argument directly in the variable current-prefix-arg, but this is less clean.

Function: prefix-numeric-value arg
This function returns the numeric meaning of a valid raw prefix argument value, arg. The argument may be a symbol, a number, or a list. If it is nil, the value 1 is returned; if it is -, the value -1 is returned; if it is a number, that number is returned; if it is a list, the CAR of that list (which should be a number) is returned.

Variable: current-prefix-arg
This variable holds the raw prefix argument for the current command. Commands may examine it directly, but the usual method for accessing it is with (interactive "P").

Variable: prefix-arg
The value of this variable is the raw prefix argument for the next editing command. Commands such as universal-argument that specify prefix arguments for the following command work by setting this variable.

Variable: last-prefix-arg
The raw prefix argument value used by the previous command.

The following commands exist to set up prefix arguments for the following command. Do not call them for any other reason.

Command: universal-argument
This command reads input and specifies a prefix argument for the following command. Don't call this command yourself unless you know what you are doing.

Command: digit-argument arg
This command adds to the prefix argument for the following command. The argument arg is the raw prefix argument as it was before this command; it is used to compute the updated prefix argument. Don't call this command yourself unless you know what you are doing.

Command: negative-argument arg
This command adds to the numeric argument for the next command. The argument arg is the raw prefix argument as it was before this command; its value is negated to form the new prefix argument. Don't call this command yourself unless you know what you are doing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.12 Recursive Editing

The Emacs command loop is entered automatically when Emacs starts up. This top-level invocation of the command loop never exits; it keeps running as long as Emacs does. Lisp programs can also invoke the command loop. Since this makes more than one activation of the command loop, we call it recursive editing. A recursive editing level has the effect of suspending whatever command invoked it and permitting the user to do arbitrary editing before resuming that command.

The commands available during recursive editing are the same ones available in the top-level editing loop and defined in the keymaps. Only a few special commands exit the recursive editing level; the others return to the recursive editing level when they finish. (The special commands for exiting are always available, but they do nothing when recursive editing is not in progress.)

All command loops, including recursive ones, set up all-purpose error handlers so that an error in a command run from the command loop will not exit the loop.

Minibuffer input is a special kind of recursive editing. It has a few special wrinkles, such as enabling display of the minibuffer and the minibuffer window, but fewer than you might suppose. Certain keys behave differently in the minibuffer, but that is only because of the minibuffer's local map; if you switch windows, you get the usual Emacs commands.

To invoke a recursive editing level, call the function recursive-edit. This function contains the command loop; it also contains a call to catch with tag exit, which makes it possible to exit the recursive editing level by throwing to exit (see section 10.5.1 Explicit Nonlocal Exits: catch and throw). If you throw a value other than t, then recursive-edit returns normally to the function that called it. The command C-M-c (exit-recursive-edit) does this. Throwing a t value causes recursive-edit to quit, so that control returns to the command loop one level up. This is called aborting, and is done by C-] (abort-recursive-edit).

Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you change the major mode of the current buffer temporarily to a special major mode, which should have a command to go back to the previous mode. (The e command in Rmail uses this technique.) Or, if you wish to give the user different text to edit "recursively", create and select a new buffer in a special mode. In this mode, define a command to complete the processing and go back to the previous buffer. (The m command in Rmail does this.)

Recursive edits are useful in debugging. You can insert a call to debug into a function definition as a sort of breakpoint, so that you can look around when the function gets there. debug invokes a recursive edit but also provides the other features of the debugger.

Recursive editing levels are also used when you type C-r in query-replace or use C-x q (kbd-macro-query).

Function: recursive-edit
This function invokes the editor command loop. It is called automatically by the initialization of Emacs, to let the user begin editing. When called from a Lisp program, it enters a recursive editing level.

In the following example, the function simple-rec first advances point one word, then enters a recursive edit, printing out a message in the echo area. The user can then do any editing desired, and then type C-M-c to exit and continue executing simple-rec.
(defun simple-rec ()
  (forward-word 1)
  (message "Recursive edit in progress")
  (recursive-edit)
  (forward-word 1))
     => simple-rec
(simple-rec)
     => nil
Command: exit-recursive-edit
This function exits from the innermost recursive edit (including minibuffer input). Its definition is effectively (throw 'exit nil).

Command: abort-recursive-edit
This function aborts the command that requested the innermost recursive edit (including minibuffer input), by signaling quit after exiting the recursive edit. Its definition is effectively (throw 'exit t). See section 21.10 Quitting.

Command: top-level
This function exits all recursive editing levels; it does not return a value, as it jumps completely out of any computation directly back to the main command loop.

Function: recursion-depth
This function returns the current depth of recursive edits. When no recursive edit is active, it returns 0.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.13 Disabling Commands

Disabling a command marks the command as requiring user confirmation before it can be executed. Disabling is used for commands which might be confusing to beginning users, to prevent them from using the commands by accident.

The low-level mechanism for disabling a command is to put a non-nil disabled property on the Lisp symbol for the command. These properties are normally set up by the user's init file (see section 40.1.2 The Init File, `.emacs') with Lisp expressions such as this:
(put 'upcase-region 'disabled t)
For a few commands, these properties are present by default (you can remove them in your init file if you wish).

If the value of the disabled property is a string, the message saying the command is disabled includes that string. For example:
(put 'delete-region 'disabled
     "Text deleted this way cannot be yanked back!\n")
See section `Disabling' in The GNU Emacs Manual, for the details on what happens when a disabled command is invoked interactively. Disabling a command has no effect on calling it as a function from Lisp programs.

Command: enable-command command
Allow command to be executed without special confirmation from now on, and (if the user confirms) alter the user's init file (see section 40.1.2 The Init File, `.emacs') so that this will apply to future sessions.

Command: disable-command command
Require special confirmation to execute command from now on, and (if the user confirms) alter the user's init file so that this will apply to future sessions.

Variable: disabled-command-hook
When the user invokes a disabled command interactively, this normal hook is run instead of the disabled command. The hook functions can use this-command-keys to determine what the user typed to run the command, and thus find the command itself. See section 23.6 Hooks.

By default, disabled-command-hook contains a function that asks the user whether to proceed.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.14 Command History

The command loop keeps a history of the complex commands that have been executed, to make it convenient to repeat these commands. A complex command is one for which the interactive argument reading uses the minibuffer. This includes any M-x command, any M-: command, and any command whose interactive specification reads an argument from the minibuffer. Explicit use of the minibuffer during the execution of the command itself does not cause the command to be considered complex.

Variable: command-history
This variable's value is a list of recent complex commands, each represented as a form to evaluate. It continues to accumulate all complex commands for the duration of the editing session, but when it reaches the maximum size (specified by the variable history-length), the oldest elements are deleted as new ones are added.
command-history
=> ((switch-to-buffer "chistory.texi")
    (describe-key "^X^[")
    (visit-tags-table "~/emacs/src/")
    (find-tag "repeat-complex-command"))
This history list is actually a special case of minibuffer history (see section 20.4 Minibuffer History), with one special twist: the elements are expressions rather than strings.

There are a number of commands devoted to the editing and recall of previous commands. The commands repeat-complex-command, and list-command-history are described in the user manual (see section `Repetition' in The GNU Emacs Manual). Within the minibuffer, the usual minibuffer history commands are available.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

21.15 Keyboard Macros

A keyboard macro is a canned sequence of input events that can be considered a command and made the definition of a key. The Lisp representation of a keyboard macro is a string or vector containing the events. Don't confuse keyboard macros with Lisp macros (see section 13. Macros).

Function: execute-kbd-macro kbdmacro &optional count
This function executes kbdmacro as a sequence of events. If kbdmacro is a string or vector, then the events in it are executed exactly as if they had been input by the user. The sequence is not expected to be a single key sequence; normally a keyboard macro definition consists of several key sequences concatenated.

If kbdmacro is a symbol, then its function definition is used in place of kbdmacro. If that is another symbol, this process repeats. Eventually the result should be a string or vector. If the result is not a symbol, string, or vector, an error is signaled.

The argument count is a repeat count; kbdmacro is executed that many times. If count is omitted or nil, kbdmacro is executed once. If it is 0, kbdmacro is executed over and over until it encounters an error or a failing search.

See section 21.7.2 Reading One Event, for an example of using execute-kbd-macro.

Variable: executing-macro
This variable contains the string or vector that defines the keyboard macro that is currently executing. It is nil if no macro is currently executing. A command can test this variable so as to behave differently when run from an executing macro. Do not set this variable yourself.

Variable: defining-kbd-macro
This variable indicates whether a keyboard macro is being defined. A command can test this variable so as to behave differently while a macro is being defined. The commands start-kbd-macro and end-kbd-macro set this variable--do not set it yourself.

The variable is always local to the current terminal and cannot be buffer-local. See section 29.2 Multiple Displays.

Variable: last-kbd-macro
This variable is the definition of the most recently defined keyboard macro. Its value is a string or vector, or nil.

The variable is always local to the current terminal and cannot be buffer-local. See section 29.2 Multiple Displays.

Variable: kbd-macro-termination-hook
This normal hook (see section I. Standard Hooks) is run when a keyboard macro terminates, regardless of what caused it to terminate (reaching the macro end or an error which ended the macro prematurely).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22. Keymaps

The bindings between input events and commands are recorded in data structures called keymaps. Each binding in a keymap associates (or binds) an individual event type either to another keymap or to a command. When an event type is bound to a keymap, that keymap is used to look up the next input event; this continues until a command is found. The whole process is called key lookup.

22.1 Keymap Terminology

Definitions of terms pertaining to keymaps.

22.2 Format of Keymaps

What a keymap looks like as a Lisp object.

22.3 Creating Keymaps

Functions to create and copy keymaps.

22.4 Inheritance and Keymaps

How one keymap can inherit the bindings of another keymap.

22.5 Prefix Keys

Defining a key with a keymap as its definition.

22.6 Active Keymaps

Each buffer has a local keymap to override the standard (global) bindings. A minor mode can also override them.

22.7 Key Lookup

How extracting elements from keymaps works.

22.8 Functions for Key Lookup

How to request key lookup.

22.9 Changing Key Bindings

Redefining a key in a keymap.

22.10 Commands for Binding Keys

Interactive interfaces for redefining keys.

22.11 Scanning Keymaps

Looking through all keymaps, for printing help.

22.12 Menu Keymaps

Defining a menu as a keymap.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.1 Keymap Terminology

A keymap is a table mapping event types to definitions (which can be any Lisp objects, though only certain types are meaningful for execution by the command loop). Given an event (or an event type) and a keymap, Emacs can get the event's definition. Events include characters, function keys, and mouse actions (see section 21.6 Input Events).

A sequence of input events that form a unit is called a key sequence, or key for short. A sequence of one event is always a key sequence, and so are some multi-event sequences.

A keymap determines a binding or definition for any key sequence. If the key sequence is a single event, its binding is the definition of the event in the keymap. The binding of a key sequence of more than one event is found by an iterative process: the binding of the first event is found, and must be a keymap; then the second event's binding is found in that keymap, and so on until all the events in the key sequence are used up.

If the binding of a key sequence is a keymap, we call the key sequence a prefix key. Otherwise, we call it a complete key (because no more events can be added to it). If the binding is nil, we call the key undefined. Examples of prefix keys are C-c, C-x, and C-x 4. Examples of defined complete keys are X, RET, and C-x 4 C-f. Examples of undefined complete keys are C-x C-g, and C-c 3. See section 22.5 Prefix Keys, for more details.

The rule for finding the binding of a key sequence assumes that the intermediate bindings (found for the events before the last) are all keymaps; if this is not so, the sequence of events does not form a unit--it is not really one key sequence. In other words, removing one or more events from the end of any valid key sequence must always yield a prefix key. For example, C-f C-n is not a key sequence; C-f is not a prefix key, so a longer sequence starting with C-f cannot be a key sequence.

The set of possible multi-event key sequences depends on the bindings for prefix keys; therefore, it can be different for different keymaps, and can change when bindings are changed. However, a one-event sequence is always a key sequence, because it does not depend on any prefix keys for its well-formedness.

At any time, several primary keymaps are active---that is, in use for finding key bindings. These are the global map, which is shared by all buffers; the local keymap, which is usually associated with a specific major mode; and zero or more minor mode keymaps, which belong to currently enabled minor modes. (Not all minor modes have keymaps.) The local keymap bindings shadow (i.e., take precedence over) the corresponding global bindings. The minor mode keymaps shadow both local and global keymaps. See section 22.6 Active Keymaps, for details.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.2 Format of Keymaps

A keymap is a list whose CAR is the symbol keymap. The remaining elements of the list define the key bindings of the keymap. Use the function keymapp (see below) to test whether an object is a keymap.

Several kinds of elements may appear in a keymap, after the symbol keymap that begins it:

(type . binding)
This specifies one binding, for events of type type. Each ordinary binding applies to events of a particular event type, which is always a character or a symbol. See section 21.6.12 Classifying Events.

(t . binding)
This specifies a default key binding; any event not bound by other elements of the keymap is given binding as its binding. Default bindings allow a keymap to bind all possible event types without having to enumerate all of them. A keymap that has a default binding completely masks any lower-precedence keymap.

vector
If an element of a keymap is a vector, the vector counts as bindings for all the ASCII characters, codes 0 through 127; vector element n is the binding for the character with code n. This is a compact way to record lots of bindings. A keymap with such a vector is called a full keymap. Other keymaps are called sparse keymaps.
When a keymap contains a vector, it always defines a binding for each ASCII character, even if the vector contains nil for that character. Such a binding of nil overrides any default key binding in the keymap, for ASCII characters. However, default bindings are still meaningful for events other than ASCII characters. A binding of nil does not override lower-precedence keymaps; thus, if the local map gives a binding of nil, Emacs uses the binding from the global map.

string
Aside from bindings, a keymap can also have a string as an element. This is called the overall prompt string and makes it possible to use the keymap as a menu. See section 22.12.1 Defining Menus.
Keymaps do not directly record bindings for the meta characters. Instead, meta characters are regarded for purposes of key lookup as sequences of two characters, the first of which is ESC (or whatever is currently the value of meta-prefix-char). Thus, the key M-a is internally represented as ESC a, and its global binding is found at the slot for a in esc-map (see section 22.5 Prefix Keys).

This conversion applies only to characters, not to function keys or other input events; thus, M-end has nothing to do with ESC end.

Here as an example is the local keymap for Lisp mode, a sparse keymap. It defines bindings for DEL and TAB, plus C-c C-l, M-C-q, and M-C-x.
lisp-mode-map
=>
(keymap
 ;; TAB
 (9 . lisp-indent-line)
 ;; DEL
 (127 . backward-delete-char-untabify)
 (3 keymap
    ;; C-c C-l
    (12 . run-lisp))
 (27 keymap
     ;; M-C-q, treated as ESC C-q
     (17 . indent-sexp)
     ;; M-C-x, treated as ESC C-x
     (24 . lisp-send-defun)))
Function: keymapp object
This function returns t if object is a keymap, nil otherwise. More precisely, this function tests for a list whose CAR is keymap.
(keymapp '(keymap))
    => t
(keymapp (current-global-map))
    => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.3 Creating Keymaps

Here we describe the functions for creating keymaps.

Function: make-keymap &optional prompt
This function creates and returns a new full keymap. That keymap contains a char-table (see section 6.6 Char-Tables) with 384 slots: the first 128 slots are for defining all the ASCII characters, the next 128 slots are for 8-bit European characters, and each one of the final 128 slots is for one character set of non-ASCII characters supported by Emacs. The new keymap initially binds all these characters to nil, and does not bind any other kind of event.
(make-keymap)
    => (keymap [nil nil nil ... nil nil])
If you specify prompt, that becomes the overall prompt string for the keymap. The prompt string should be provided for menu keymaps (see section 22.12.1 Defining Menus).

Function: make-sparse-keymap &optional prompt
This function creates and returns a new sparse keymap with no entries. The new keymap does not contain a char-table, unlike make-keymap, and does not bind any events. The argument prompt specifies a prompt string, as in make-keymap.
(make-sparse-keymap)
    => (keymap)
Function: copy-keymap keymap
This function returns a copy of keymap. Any keymaps that appear directly as bindings in keymap are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function definition is a keymap; the same symbol appears in the new copy.
(setq map (copy-keymap (current-local-map)))
=> (keymap
     ;; (This implements meta characters.)
     (27 keymap
         (83 . center-paragraph)
         (115 . center-line))
     (9 . tab-to-tab-stop))

(eq map (current-local-map))
    => nil
(equal map (current-local-map))
    => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.4 Inheritance and Keymaps

A keymap can inherit the bindings of another keymap, which we call the parent keymap. Such a keymap looks like this:
(keymap bindings... . parent-keymap)
The effect is that this keymap inherits all the bindings of parent-keymap, whatever they may be at the time a key is looked up, but can add to them or override them with bindings.

If you change the bindings in parent-keymap using define-key or other key-binding functions, these changes are visible in the inheriting keymap unless shadowed by bindings. The converse is not true: if you use define-key to change the inheriting keymap, that affects bindings, but has no effect on parent-keymap.

The proper way to construct a keymap with a parent is to use set-keymap-parent; if you have code that directly constructs a keymap with a parent, please convert the program to use set-keymap-parent instead.

Function: keymap-parent keymap
This returns the parent keymap of keymap. If keymap has no parent, keymap-parent returns nil.

Function: set-keymap-parent keymap parent
This sets the parent keymap of keymap to parent, and returns parent. If parent is nil, this function gives keymap no parent at all.

If keymap has submaps (bindings for prefix keys), they too receive new parent keymaps that reflect what parent specifies for those prefix keys.

Here is an example showing how to make a keymap that inherits from text-mode-map:
(let ((map (make-sparse-keymap)))
  (set-keymap-parent map text-mode-map)
  map)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.5 Prefix Keys

A prefix key is a key sequence whose binding is a keymap. The keymap defines what to do with key sequences that extend the prefix key. For example, C-x is a prefix key, and it uses a keymap that is also stored in the variable ctl-x-map. This keymap defines bindings for key sequences starting with C-x.

Some of the standard Emacs prefix keys use keymaps that are also found in Lisp variables:

esc-map is the global keymap for the ESC prefix key. Thus, the global definitions of all meta characters are actually found here. This map is also the function definition of ESC-prefix.

help-map is the global keymap for the C-h prefix key.

mode-specific-map is the global keymap for the prefix key C-c. This map is actually global, not mode-specific, but its name provides useful information about C-c in the output of C-h b (display-bindings), since the main use of this prefix key is for mode-specific bindings.

ctl-x-map is the global keymap used for the C-x prefix key. This map is found via the function cell of the symbol Control-X-prefix.

mule-keymap is the global keymap used for the C-x RET prefix key.

ctl-x-4-map is the global keymap used for the C-x 4 prefix key.

ctl-x-5-map is the global keymap used for the C-x 5 prefix key.

2C-mode-map is the global keymap used for the C-x 6 prefix key.

vc-prefix-map is the global keymap used for the C-x v prefix key.

facemenu-keymap is the global keymap used for the M-g prefix key.

The other Emacs prefix keys are C-x @, C-x a i, C-x ESC and ESC ESC. They use keymaps that have no special names.

The keymap binding of a prefix key is used for looking up the event that follows the prefix key. (It may instead be a symbol whose function definition is a keymap. The effect is the same, but the symbol serves as a name for the prefix key.) Thus, the binding of C-x is the symbol Control-X-prefix, whose function cell holds the keymap for C-x commands. (The same keymap is also the value of ctl-x-map.)

Prefix key definitions can appear in any active keymap. The definitions of C-c, C-x, C-h and ESC as prefix keys appear in the global map, so these prefix keys are always available. Major and minor modes can redefine a key as a prefix by putting a prefix key definition for it in the local map or the minor mode's map. See section 22.6 Active Keymaps.

If a key is defined as a prefix in more than one active map, then its various definitions are in effect merged: the commands defined in the minor mode keymaps come first, followed by those in the local map's prefix definition, and then by those from the global map.

In the following example, we make C-p a prefix key in the local keymap, in such a way that C-p is identical to C-x. Then the binding for C-p C-f is the function find-file, just like C-x C-f. The key sequence C-p 6 is not found in any active keymap.
(use-local-map (make-sparse-keymap))
    => nil
(local-set-key "\C-p" ctl-x-map)
    => nil
(key-binding "\C-p\C-f")
    => find-file

(key-binding "\C-p6")
    => nil
Function: define-prefix-command symbol &optional mapvar prompt
This function prepares symbol for use as a prefix key's binding: it creates a sparse keymap and stores it as symbol's function definition. Subsequently binding a key sequence to symbol will make that key sequence into a prefix key. The return value is symbol.

This function also sets symbol as a variable, with the keymap as its value. But if mapvar is non-nil, it sets mapvar as a variable instead.

If prompt is non-nil, that becomes the overall prompt string for the keymap. The prompt string should be given for menu keymaps (see section 22.12.1 Defining Menus).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.6 Active Keymaps

Emacs normally contains many keymaps; at any given time, just a few of them are active in that they participate in the interpretation of user input. These are the global keymap, the current buffer's local keymap, and the keymaps of any enabled minor modes.

The global keymap holds the bindings of keys that are defined regardless of the current buffer, such as C-f. The variable global-map holds this keymap, which is always active.

Each buffer may have another keymap, its local keymap, which may contain new or overriding definitions for keys. The current buffer's local keymap is always active except when overriding-local-map overrides it. Text properties can specify an alternative local map for certain parts of the buffer; see 32.19.4 Properties with Special Meanings.

Each minor mode can have a keymap; if it does, the keymap is active when the minor mode is enabled.

The variable overriding-local-map, if non-nil, specifies another local keymap that overrides the buffer's local map and all the minor mode keymaps.

All the active keymaps are used together to determine what command to execute when a key is entered. Emacs searches these maps one by one, in order of decreasing precedence, until it finds a binding in one of the maps. The procedure for searching a single keymap is called key lookup; see 22.7 Key Lookup.

Normally, Emacs first searches for the key in the minor mode maps, in the order specified by minor-mode-map-alist; if they do not supply a binding for the key, Emacs searches the local map; if that too has no binding, Emacs then searches the global map. However, if overriding-local-map is non-nil, Emacs searches that map first, before the global map.

Since every buffer that uses the same major mode normally uses the same local keymap, you can think of the keymap as local to the mode. A change to the local keymap of a buffer (using local-set-key, for example) is seen also in the other buffers that share that keymap.

The local keymaps that are used for Lisp mode and some other major modes exist even if they have not yet been used. These local maps are the values of variables such as lisp-mode-map. For most major modes, which are less frequently used, the local keymap is constructed only when the mode is used for the first time in a session.

The minibuffer has local keymaps, too; they contain various completion and exit commands. See section 20.1 Introduction to Minibuffers.

Emacs has other keymaps that are used in a different way--translating events within read-key-sequence. See section 40.8.2 Translating Input Events.

See section H. Standard Keymaps, for a list of standard keymaps.

Variable: global-map
This variable contains the default global keymap that maps Emacs keyboard input to commands. The global keymap is normally this keymap. The default global keymap is a full keymap that binds self-insert-command to all of the printing characters.

It is normal practice to change the bindings in the global map, but you should not assign this variable any value other than the keymap it starts out with.

Function: current-global-map
This function returns the current global keymap. This is the same as the value of global-map unless you change one or the other.
(current-global-map)
=> (keymap [set-mark-command beginning-of-line ...
            delete-backward-char])
Function: current-local-map
This function returns the current buffer's local keymap, or nil if it has none. In the following example, the keymap for the `*scratch*' buffer (using Lisp Interaction mode) is a sparse keymap in which the entry for ESC, ASCII code 27, is another sparse keymap.
(current-local-map)
=> (keymap
    (10 . eval-print-last-sexp)
    (9 . lisp-indent-line)
    (127 . backward-delete-char-untabify)
    (27 keymap
        (24 . eval-defun)
        (17 . indent-sexp)))
Function: current-minor-mode-maps
This function returns a list of the keymaps of currently enabled minor modes.

Function: use-global-map keymap
This function makes keymap the new current global keymap. It returns nil.

It is very unusual to change the global keymap.

Function: use-local-map keymap
This function makes keymap the new local keymap of the current buffer. If keymap is nil, then the buffer has no local keymap. use-local-map returns nil. Most major mode commands use this function.

Variable: minor-mode-map-alist
This variable is an alist describing keymaps that may or may not be active according to the values of certain variables. Its elements look like this:
(variable . keymap)
The keymap keymap is active whenever variable has a non-nil value. Typically variable is the variable that enables or disables a minor mode. See section 23.2.2 Keymaps and Minor Modes.

Note that elements of minor-mode-map-alist do not have the same structure as elements of minor-mode-alist. The map must be the CDR of the element; a list with the map as the second element will not do. The CDR can be either a keymap (a list) or a symbol whose function definition is a keymap.

When more than one minor mode keymap is active, their order of priority is the order of minor-mode-map-alist. But you should design minor modes so that they don't interfere with each other. If you do this properly, the order will not matter.

See 23.2.2 Keymaps and Minor Modes, for more information about minor modes. See also minor-mode-key-binding (see section 22.8 Functions for Key Lookup).

Variable: minor-mode-overriding-map-alist
This variable allows major modes to override the key bindings for particular minor modes. The elements of this alist look like the elements of minor-mode-map-alist: (variable . keymap).

If a variable appears as an element of minor-mode-overriding-map-alist, the map specified by that element totally replaces any map specified for the same variable in minor-mode-map-alist.

minor-mode-overriding-map-alist is automatically buffer-local in all buffers.

Variable: overriding-local-map
If non-nil, this variable holds a keymap to use instead of the buffer's local keymap and instead of all the minor mode keymaps. This keymap, if any, overrides all other maps that would have been active, except for the current global map.

Variable: overriding-terminal-local-map
If non-nil, this variable holds a keymap to use instead of overriding-local-map, the buffer's local keymap and all the minor mode keymaps.

This variable is always local to the current terminal and cannot be buffer-local. See section 29.2 Multiple Displays. It is used to implement incremental search mode.

Variable: overriding-local-map-menu-flag
If this variable is non-nil, the value of overriding-local-map or overriding-terminal-local-map can affect the display of the menu bar. The default value is nil, so those map variables have no effect on the menu bar.

Note that these two map variables do affect the execution of key sequences entered using the menu bar, even if they do not affect the menu bar display. So if a menu bar key sequence comes in, you should clear the variables before looking up and executing that key sequence. Modes that use the variables would typically do this anyway; normally they respond to events that they do not handle by "unreading" them and exiting.

Variable: special-event-map
This variable holds a keymap for special events. If an event type has a binding in this keymap, then it is special, and the binding for the event is run directly by read-event. See section 21.8 Special Events.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.7 Key Lookup

Key lookup is the process of finding the binding of a key sequence from a given keymap. Actual execution of the binding is not part of key lookup.

Key lookup uses just the event type of each event in the key sequence; the rest of the event is ignored. In fact, a key sequence used for key lookup may designate mouse events with just their types (symbols) instead of with entire mouse events (lists). See section 21.6 Input Events. Such a "key-sequence" is insufficient for command-execute to run, but it is sufficient for looking up or rebinding a key.

When the key sequence consists of multiple events, key lookup processes the events sequentially: the binding of the first event is found, and must be a keymap; then the second event's binding is found in that keymap, and so on until all the events in the key sequence are used up. (The binding thus found for the last event may or may not be a keymap.) Thus, the process of key lookup is defined in terms of a simpler process for looking up a single event in a keymap. How that is done depends on the type of object associated with the event in that keymap.

Let's use the term keymap entry to describe the value found by looking up an event type in a keymap. (This doesn't include the item string and other extra elements in menu key bindings, because lookup-key and other key lookup functions don't include them in the returned value.) While any Lisp object may be stored in a keymap as a keymap entry, not all make sense for key lookup. Here is a table of the meaningful kinds of keymap entries:

nil
nil means that the events used so far in the lookup form an undefined key. When a keymap fails to mention an event type at all, and has no default binding, that is equivalent to a binding of nil for that event type.

command
The events used so far in the lookup form a complete key, and command is its binding. See section 12.1 What Is a Function?.

array
The array (either a string or a vector) is a keyboard macro. The events used so far in the lookup form a complete key, and the array is its binding. See 21.15 Keyboard Macros, for more information.

keymap
The events used so far in the lookup form a prefix key. The next event of the key sequence is looked up in keymap.

list
The meaning of a list depends on the types of the elements of the list.

If the CAR of list is the symbol keymap, then the list is a keymap, and is treated as a keymap (see above).

If the CAR of list is lambda, then the list is a lambda expression. This is presumed to be a command, and is treated as such (see above).

If the CAR of list is a keymap and the CDR is an event type, then this is an indirect entry:
(othermap . othertype)
When key lookup encounters an indirect entry, it looks up instead the binding of othertype in othermap and uses that.

This feature permits you to define one key as an alias for another key. For example, an entry whose CAR is the keymap called esc-map and whose CDR is 32 (the code for SPC) means, "Use the global binding of Meta-SPC, whatever that may be."

symbol
The function definition of symbol is used in place of symbol. If that too is a symbol, then this process is repeated, any number of times. Ultimately this should lead to an object that is a keymap, a command, or a keyboard macro. A list is allowed if it is a keymap or a command, but indirect entries are not understood when found via symbols.
Note that keymaps and keyboard macros (strings and vectors) are not valid functions, so a symbol with a keymap, string, or vector as its function definition is invalid as a function. It is, however, valid as a key binding. If the definition is a keyboard macro, then the symbol is also valid as an argument to command-execute (see section 21.3 Interactive Call).

The symbol undefined is worth special mention: it means to treat the key as undefined. Strictly speaking, the key is defined, and its binding is the command undefined; but that command does the same thing that is done automatically for an undefined key: it rings the bell (by calling ding) but does not signal an error.

undefined is used in local keymaps to override a global key binding and make the key "undefined" locally. A local binding of nil would fail to do this because it would not override the global binding.

anything else
If any other type of object is found, the events used so far in the lookup form a complete key, and the object is its binding, but the binding is not executable as a command.
In short, a keymap entry may be a keymap, a command, a keyboard macro, a symbol that leads to one of them, or an indirection or nil. Here is an example of a sparse keymap with two characters bound to commands and one bound to another keymap. This map is the normal value of emacs-lisp-mode-map. Note that 9 is the code for TAB, 127 for DEL, 27 for ESC, 17 for C-q and 24 for C-x.
(keymap (9 . lisp-indent-line)
        (127 . backward-delete-char-untabify)
        (27 keymap (17 . indent-sexp) (24 . eval-defun)))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.8 Functions for Key Lookup

Here are the functions and variables pertaining to key lookup.

Function: lookup-key keymap key &optional accept-defaults
This function returns the definition of key in keymap. All the other functions described in this chapter that look up keys use lookup-key. Here are examples:
(lookup-key (current-global-map) "\C-x\C-f")
    => find-file
(lookup-key (current-global-map) "\C-x\C-f12345")
    => 2
If the string or vector key is not a valid key sequence according to the prefix keys specified in keymap, it must be "too long" and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of key that compose a complete key.

If accept-defaults is non-nil, then lookup-key considers default bindings as well as bindings for the specific events in key. Otherwise, lookup-key reports only bindings for the specific sequence key, ignoring default bindings except when you explicitly ask about them. (To do this, supply t as an element of key; see 22.2 Format of Keymaps.)

If key contains a meta character (not a function key), that character is implicitly replaced by a two-character sequence: the value of meta-prefix-char, followed by the corresponding non-meta character. Thus, the first example below is handled by conversion into the second example.
(lookup-key (current-global-map) "\M-f")
    => forward-word
(lookup-key (current-global-map) "\ef")
    => forward-word
Unlike read-key-sequence, this function does not modify the specified events in ways that discard information (see section 21.7.1 Key Sequence Input). In particular, it does not convert letters to lower case and it does not change drag events to clicks.

Command: undefined
Used in keymaps to undefine keys. It calls ding, but does not cause an error.

Function: key-binding key &optional accept-defaults
This function returns the binding for key in the current keymaps, trying all the active keymaps. The result is nil if key is undefined in the keymaps.

The argument accept-defaults controls checking for default bindings, as in lookup-key (above).

An error is signaled if key is not a string or a vector.
(key-binding "\C-x\C-f")
    => find-file
Function: local-key-binding key &optional accept-defaults
This function returns the binding for key in the current local keymap, or nil if it is undefined there.

The argument accept-defaults controls checking for default bindings, as in lookup-key (above).

Function: global-key-binding key &optional accept-defaults
This function returns the binding for command key in the current global keymap, or nil if it is undefined there.

The argument accept-defaults controls checking for default bindings, as in lookup-key (above).

Function: minor-mode-key-binding key &optional accept-defaults
This function returns a list of all the active minor mode bindings of key. More precisely, it returns an alist of pairs (modename . binding), where modename is the variable that enables the minor mode, and binding is key's binding in that mode. If key has no minor-mode bindings, the value is nil.

If the first binding found is not a prefix definition (a keymap or a symbol defined as a keymap), all subsequent bindings from other minor modes are omitted, since they would be completely shadowed. Similarly, the list omits non-prefix bindings that follow prefix bindings.

The argument accept-defaults controls checking for default bindings, as in lookup-key (above).

Variable: meta-prefix-char
This variable is the meta-prefix character code. It is used when translating a meta character to a two-character sequence so it can be looked up in a keymap. For useful results, the value should be a prefix event (see section 22.5 Prefix Keys). The default value is 27, which is the ASCII code for ESC.

As long as the value of meta-prefix-char remains 27, key lookup translates M-b into ESC b, which is normally defined as the backward-word command. However, if you were to set meta-prefix-char to 24, the code for C-x, then Emacs will translate M-b into C-x b, whose standard binding is the switch-to-buffer command. (Don't actually do this!) Here is an illustration of what would happen:
meta-prefix-char                    ; The default value.
     => 27
(key-binding "\M-b")
     => backward-word
?\C-x                               ; The print representation
     => 24                          ;   of a character.
(setq meta-prefix-char 24)
     => 24
(key-binding "\M-b")
     => switch-to-buffer            ; Now, typing M-b is
                                    ;   like typing C-x b.

(setq meta-prefix-char 27)          ; Avoid confusion!
     => 27                          ; Restore the default value!
This translation of one event into two happens only for characters, not for other kinds of input events. Thus, M-F1, a function key, is not converted into ESC F1.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.9 Changing Key Bindings

The way to rebind a key is to change its entry in a keymap. If you change a binding in the global keymap, the change is effective in all buffers (though it has no direct effect in buffers that shadow the global binding with a local one). If you change the current buffer's local map, that usually affects all buffers using the same major mode. The global-set-key and local-set-key functions are convenient interfaces for these operations (see section 22.10 Commands for Binding Keys). You can also use define-key, a more general function; then you must specify explicitly the map to change.

In writing the key sequence to rebind, it is good to use the special escape sequences for control and meta characters (see section 2.3.8 String Type). The syntax `\C-' means that the following character is a control character and `\M-' means that the following character is a meta character. Thus, the string "\M-x" is read as containing a single M-x, "\C-f" is read as containing a single C-f, and "\M-\C-x" and "\C-\M-x" are both read as containing a single C-M-x. You can also use this escape syntax in vectors, as well as others that aren't allowed in strings; one example is `[?\C-\H-x home]'. See section 2.3.3 Character Type.

The key definition and lookup functions accept an alternate syntax for event types in a key sequence that is a vector: you can use a list containing modifier names plus one base event (a character or function key name). For example, (control ?a) is equivalent to ?\C-a and (hyper control left) is equivalent to C-H-left. One advantage of such lists is that the precise numeric codes for the modifier bits don't appear in compiled files.

For the functions below, an error is signaled if keymap is not a keymap or if key is not a string or vector representing a key sequence. You can use event types (symbols) as shorthand for events that are lists.

Function: define-key keymap key binding
This function sets the binding for key in keymap. (If key is more than one event long, the change is actually made in another keymap reached from keymap.) The argument binding can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see 22.7 Key Lookup.) The value returned by define-key is binding.

Every prefix of key must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of key is undefined, then define-key defines it as a prefix key so that the rest of key can be defined as specified.

If there was previously no binding for key in keymap, the new binding is added at the beginning of keymap. The order of bindings in a keymap makes no difference in most cases, but it does matter for menu keymaps (see section 22.12 Menu Keymaps).

Here is an example that creates a sparse keymap and makes a number of bindings in it:
(setq map (make-sparse-keymap))
    => (keymap)
(define-key map "\C-f" 'forward-char)
    => forward-char
map
    => (keymap (6 . forward-char))

;; Build sparse submap for C-x and bind f in that.
(define-key map "\C-xf" 'forward-word)
    => forward-word
map
=> (keymap
    (24 keymap                ; C-x
        (102 . forward-word)) ;      f
    (6 . forward-char))       ; C-f

;; Bind C-p to the ctl-x-map.
(define-key map "\C-p" ctl-x-map)
;; ctl-x-map
=> [nil ... find-file ... backward-kill-sentence]

;; Bind C-f to foo in the ctl-x-map.
(define-key map "\C-p\C-f" 'foo)
=> 'foo
map
=> (keymap     ; Note foo in ctl-x-map.
    (16 keymap [nil ... foo ... backward-kill-sentence])
    (24 keymap
        (102 . forward-word))
    (6 . forward-char))
Note that storing a new binding for C-p C-f actually works by changing an entry in ctl-x-map, and this has the effect of changing the bindings of both C-p C-f and C-x C-f in the default global map.

Function: substitute-key-definition olddef newdef keymap &optional oldmap
This function replaces olddef with newdef for any keys in keymap that were bound to olddef. In other words, olddef is replaced with newdef wherever it appears. The function returns nil.

For example, this redefines C-x C-f, if you do it in an Emacs with standard bindings:
(substitute-key-definition
 'find-file 'find-file-read-only (current-global-map))
If oldmap is non-nil, that changes the behavior of substitute-key-definition: the bindings in oldmap determine which keys to rebind. The rebindings still happen in keymap, not in oldmap. Thus, you can change one map under the control of the bindings in another. For example,
(substitute-key-definition
  'delete-backward-char 'my-funny-delete
  my-map global-map)
puts the special deletion command in my-map for whichever keys are globally bound to the standard deletion command.

Here is an example showing a keymap before and after substitution:
(setq map '(keymap
            (?1 . olddef-1)
            (?2 . olddef-2)
            (?3 . olddef-1)))
=> (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))

(substitute-key-definition 'olddef-1 'newdef map)
=> nil
map
=> (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
Function: suppress-keymap keymap &optional nodigits
This function changes the contents of the full keymap keymap by making all the printing characters undefined. More precisely, it binds them to the command undefined. This makes ordinary insertion of text impossible. suppress-keymap returns nil.

If nodigits is nil, then suppress-keymap defines digits to run digit-argument, and - to run negative-argument. Otherwise it makes them undefined like the rest of the printing characters.

The suppress-keymap function does not make it impossible to modify a buffer, as it does not suppress commands such as yank and quoted-insert. To prevent any modification of a buffer, make it read-only (see section 27.7 Read-Only Buffers).

Since this function modifies keymap, you would normally use it on a newly created keymap. Operating on an existing keymap that is used for some other purpose is likely to cause trouble; for example, suppressing global-map would make it impossible to use most of Emacs.

Most often, suppress-keymap is used to initialize local keymaps of modes such as Rmail and Dired where insertion of text is not desirable and the buffer is read-only. Here is an example taken from the file `emacs/lisp/dired.el', showing how the local keymap for Dired mode is set up:
(setq dired-mode-map (make-keymap))
(suppress-keymap dired-mode-map)
(define-key dired-mode-map "r" 'dired-rename-file)
(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
(define-key dired-mode-map "d" 'dired-flag-file-deleted)
(define-key dired-mode-map "v" 'dired-view-file)
(define-key dired-mode-map "e" 'dired-find-file)
(define-key dired-mode-map "f" 'dired-find-file)
...
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.10 Commands for Binding Keys

This section describes some convenient interactive interfaces for changing key bindings. They work by calling define-key.

People often use global-set-key in their init files (see section 40.1.2 The Init File, `.emacs') for simple customization. For example,
(global-set-key "\C-x\C-\\" 'next-line)
or
(global-set-key [?\C-x ?\C-\\] 'next-line)
or
(global-set-key [(control ?x) (control ?\\)] 'next-line)
redefines C-x C-\ to move down a line.
(global-set-key [M-mouse-1] 'mouse-set-point)
redefines the first (leftmost) mouse button, typed with the Meta key, to set point where you click.

Be careful when using non-ASCII text characters in Lisp specifications of keys to bind. If these are read as multibyte text, as they usually will be in a Lisp file (see section 15.3 Loading Non-ASCII Characters), you must type the keys as multibyte too. For instance, if you use this:
(global-set-key "ö" 'my-function) ; bind o-umlaut
or
(global-set-key ?ö 'my-function) ; bind o-umlaut
and your language environment is multibyte Latin-1, these commands actually bind the multibyte character with code 2294, not the unibyte Latin-1 character with code 246 (M-v). In order to use this binding, you need to enter the multibyte Latin-1 character as keyboard input. One way to do this is by using an appropriate input method (see section `Input Methods' in The GNU Emacs Manual).

If you want to use a unibyte character in the key binding, you can construct the key sequence string using multibyte-char-to-unibyte or string-make-unibyte (see section 33.2 Converting Text Representations).

Command: global-set-key key definition
This function sets the binding of key in the current global map to definition.
(global-set-key key definition)
==
(define-key (current-global-map) key definition)
Command: global-unset-key key
This function removes the binding of key from the current global map.

One use of this function is in preparation for defining a longer key that uses key as a prefix--which would not be allowed if key has a non-prefix binding. For example:
(global-unset-key "\C-l")
    => nil
(global-set-key "\C-l\C-l" 'redraw-display)
    => nil
This function is implemented simply using define-key:
(global-unset-key key)
==
(define-key (current-global-map) key nil)
Command: local-set-key key definition
This function sets the binding of key in the current local keymap to definition.
(local-set-key key definition)
==
(define-key (current-local-map) key definition)
Command: local-unset-key key
This function removes the binding of key from the current local map.
(local-unset-key key)
==
(define-key (current-local-map) key nil)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.11 Scanning Keymaps

This section describes functions used to scan all the current keymaps for the sake of printing help information.

Function: accessible-keymaps keymap &optional prefix
This function returns a list of all the keymaps that can be reached (via zero or more prefix keys) from keymap. The value is an association list with elements of the form (key . map), where key is a prefix key whose definition in keymap is map.

The elements of the alist are ordered so that the key increases in length. The first element is always ("" . keymap), because the specified keymap is accessible from itself with a prefix of no events.

If prefix is given, it should be a prefix key sequence; then accessible-keymaps includes only the submaps whose prefixes start with prefix. These elements look just as they do in the value of (accessible-keymaps); the only difference is that some elements are omitted.

In the example below, the returned alist indicates that the key ESC, which is displayed as `^[', is a prefix key whose definition is the sparse keymap (keymap (83 . center-paragraph) (115 . foo)).
(accessible-keymaps (current-local-map))
=>(("" keymap
      (27 keymap   ; Note this keymap for ESC is repeated below.
          (83 . center-paragraph)
          (115 . center-line))
      (9 . tab-to-tab-stop))

   ("^[" keymap
    (83 . center-paragraph)
    (115 . foo)))
In the following example, C-h is a prefix key that uses a sparse keymap starting with (keymap (118 . describe-variable)...). Another prefix, C-x 4, uses a keymap which is also the value of the variable ctl-x-4-map. The event mode-line is one of several dummy events used as prefixes for mouse actions in special parts of a window.
(accessible-keymaps (current-global-map))
=> (("" keymap [set-mark-command beginning-of-line ...
                   delete-backward-char])
    ("^H" keymap (118 . describe-variable) ...
     (8 . help-for-help))
    ("^X" keymap [x-flush-mouse-queue ...
     backward-kill-sentence])
    ("^[" keymap [mark-sexp backward-sexp ...
     backward-kill-word])
    ("^X4" keymap (15 . display-buffer) ...)
    ([mode-line] keymap
     (S-mouse-2 . mouse-split-window-horizontally) ...))
These are not all the keymaps you would see in actuality.

Function: where-is-internal command &optional keymap firstonly noindirect
This function is a subroutine used by the where-is command (see section `Help' in The GNU Emacs Manual). It returns a list of key sequences (of any length) that are bound to command in a set of keymaps.

The argument command can be any object; it is compared with all keymap entries using eq.

If keymap is nil, then the maps used are the current active keymaps, disregarding overriding-local-map (that is, pretending its value is nil). If keymap is non-nil, then the maps searched are keymap and the global keymap. If keymap is a list of keymaps, only those keymaps are searched.

Usually it's best to use overriding-local-map as the expression for keymap. Then where-is-internal searches precisely the keymaps that are active. To search only the global map, pass (keymap) (an empty keymap) as keymap.

If firstonly is non-ascii, then the value is a single string representing the first key sequence found, rather than a list of all possible key sequences. If firstonly is t, then the value is the first key sequence, except that key sequences consisting entirely of ASCII characters (or meta variants of ASCII characters) are preferred to all other key sequences.

If noindirect is non-nil, where-is-internal doesn't follow indirect keymap bindings. This makes it possible to search for an indirect definition itself.
(where-is-internal 'describe-function)
    => ("\^hf" "\^hd")
Command: describe-bindings &optional prefix
This function creates a listing of all current key bindings, and displays it in a buffer named `*Help*'. The text is grouped by modes--minor modes first, then the major mode, then global bindings.

If prefix is non-nil, it should be a prefix key; then the listing includes only keys that start with prefix.

The listing describes meta characters as ESC followed by the corresponding non-meta character.

When several characters with consecutive ASCII codes have the same definition, they are shown together, as `firstchar..lastchar'. In this instance, you need to know the ASCII codes to understand which characters this means. For example, in the default global map, the characters `SPC .. ~' are described by a single line. SPC is ASCII 32, ~ is ASCII 126, and the characters between them include all the normal printing characters, (e.g., letters, digits, punctuation, etc.); all these characters are bound to self-insert-command.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12 Menu Keymaps

A keymap can define a menu as well as bindings for keyboard keys and mouse button. Menus are usually actuated with the mouse, but they can work with the keyboard also.

22.12.1 Defining Menus

How to make a keymap that defines a menu.

22.12.2 Menus and the Mouse

How users actuate the menu with the mouse.

22.12.3 Menus and the Keyboard

How they actuate it with the keyboard.

22.12.4 Menu Example

Making a simple menu.

22.12.5 The Menu Bar

How to customize the menu bar.

22.12.6 Tool bars

A tool bar is a row of images.

22.12.7 Modifying Menus

How to add new items to a menu.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.1 Defining Menus

A keymap is suitable for menu use if it has an overall prompt string, which is a string that appears as an element of the keymap. (See section 22.2 Format of Keymaps.) The string should describe the purpose of the menu's commands. Emacs displays the overall prompt string as the menu title in some cases, depending on the toolkit (if any) used for displaying menus.(6) Keyboard menus also display the overall prompt string.

The easiest way to construct a keymap with a prompt string is to specify the string as an argument when you call make-keymap, make-sparse-keymap or define-prefix-command (see section 22.3 Creating Keymaps).

The order of items in the menu is the same as the order of bindings in the keymap. Since define-key puts new bindings at the front, you should define the menu items starting at the bottom of the menu and moving to the top, if you care about the order. When you add an item to an existing menu, you can specify its position in the menu using define-key-after (see section 22.12.7 Modifying Menus).

22.12.1.1 Simple Menu Items

A simple kind of menu key binding, limited in capabilities.

22.12.1.2 Extended Menu Items

More powerful menu item definitions let you specify keywords to enable various features.

22.12.1.3 Menu Separators

Drawing a horizontal line through a menu.

22.12.1.4 Alias Menu Items

Using command aliases in menu items.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.1.1 Simple Menu Items

The simpler and older way to define a menu keymap binding looks like this:
(item-string . real-binding)
The CAR, item-string, is the string to be displayed in the menu. It should be short--preferably one to three words. It should describe the action of the command it corresponds to.

You can also supply a second string, called the help string, as follows:
(item-string help . real-binding)
help specifies a "help-echo" string to display while the mouse is on that item in the same way as help-echo text properties (see Help display).

As far as define-key is concerned, item-string and help-string are part of the event's binding. However, lookup-key returns just real-binding, and only real-binding is used for executing the key.

If real-binding is nil, then item-string appears in the menu but cannot be selected.

If real-binding is a symbol and has a non-nil menu-enable property, that property is an expression that controls whether the menu item is enabled. Every time the keymap is used to display a menu, Emacs evaluates the expression, and it enables the menu item only if the expression's value is non-nil. When a menu item is disabled, it is displayed in a "fuzzy" fashion, and cannot be selected.

The menu bar does not recalculate which items are enabled every time you look at a menu. This is because the X toolkit requires the whole tree of menus in advance. To force recalculation of the menu bar, call force-mode-line-update (see section 23.3 Mode Line Format).

You've probably noticed that menu items show the equivalent keyboard key sequence (if any) to invoke the same command. To save time on recalculation, menu display caches this information in a sublist in the binding, like this:
(item-string [help-string] (key-binding-data) . real-binding)
Don't put these sublists in the menu item yourself; menu display calculates them automatically. Don't mention keyboard equivalents in the item strings themselves, since that is redundant.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.1.2 Extended Menu Items

An extended-format menu item is a more flexible and also cleaner alternative to the simple format. It consists of a list that starts with the symbol menu-item. To define a non-selectable string, the item looks like this:
(menu-item item-name)
A string starting with two or more dashes specifies a separator line; see 22.12.1.3 Menu Separators.

To define a real menu item which can be selected, the extended format item looks like this:
(menu-item item-name real-binding
    . item-property-list)
Here, item-name is an expression which evaluates to the menu item string. Thus, the string need not be a constant. The third element, real-binding, is the command to execute. The tail of the list, item-property-list, has the form of a property list which contains other information. Here is a table of the properties that are supported:

:enable form
The result of evaluating form determines whether the item is enabled (non-nil means yes). If the item is not enabled, you can't really click on it.

:visible form
The result of evaluating form determines whether the item should actually appear in the menu (non-nil means yes). If the item does not appear, then the menu is displayed as if this item were not defined at all.

:help help
The value of this property, help, specifies a "help-echo" string to display while the mouse is on that item. This is displayed in the same way as help-echo text properties (see Help display). Note that this must be a constant string, unlike the help-echo property for text and overlays.

:button (type . selected)
This property provides a way to define radio buttons and toggle buttons. The CAR, type, says which: it should be :toggle or :radio. The CDR, selected, should be a form; the result of evaluating it says whether this button is currently selected.
A toggle is a menu item which is labeled as either "on" or "off" according to the value of selected. The command itself should toggle selected, setting it to t if it is nil, and to nil if it is t. Here is how the menu item to toggle the debug-on-error flag is defined:
(menu-item "Debug on Error" toggle-debug-on-error
           :button (:toggle
                    . (and (boundp 'debug-on-error)
                           debug-on-error)))
This works because toggle-debug-on-error is defined as a command which toggles the variable debug-on-error.

Radio buttons are a group of menu items, in which at any time one and only one is "selected." There should be a variable whose value says which one is selected at any time. The selected form for each radio button in the group should check whether the variable has the right value for selecting that button. Clicking on the button should set the variable so that the button you clicked on becomes selected.

:key-sequence key-sequence
This property specifies which key sequence is likely to be bound to the same command invoked by this menu item. If you specify the right key sequence, that makes preparing the menu for display run much faster.
If you specify the wrong key sequence, it has no effect; before Emacs displays key-sequence in the menu, it verifies that key-sequence is really equivalent to this menu item.

:key-sequence nil
This property indicates that there is normally no key binding which is equivalent to this menu item. Using this property saves time in preparing the menu for display, because Emacs does not need to search the keymaps for a keyboard equivalent for this menu item.
However, if the user has rebound this item's definition to a key sequence, Emacs ignores the :keys property and finds the keyboard equivalent anyway.

:keys string
This property specifies that string is the string to display as the keyboard equivalent for this menu item. You can use the `\\[...]' documentation construct in string.

:filter filter-fn
This property provides a way to compute the menu item dynamically. The property value filter-fn should be a function of one argument; when it is called, its argument will be real-binding. The function should return the binding to use instead.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.1.3 Menu Separators

A menu separator is a kind of menu item that doesn't display any text--instead, it divides the menu into subparts with a horizontal line. A separator looks like this in the menu keymap:
(menu-item separator-type)
where separator-type is a string starting with two or more dashes.

In the simplest case, separator-type consists of only dashes. That specifies the default kind of separator. (For compatibility, "" and - also count as separators.)

Starting in Emacs 21, certain other values of separator-type specify a different style of separator. Here is a table of them:

"--no-line"

"--space"
An extra vertical space, with no actual line.

"--single-line"
A single line in the menu's foreground color.

"--double-line"
A double line in the menu's foreground color.

"--single-dashed-line"
A single dashed line in the menu's foreground color.

"--double-dashed-line"
A double dashed line in the menu's foreground color.

"--shadow-etched-in"
A single line with a 3D sunken appearance. This is the default, used separators consisting of dashes only.

"--shadow-etched-out"
A single line with a 3D raised appearance.

"--shadow-etched-in-dash"
A single dashed line with a 3D sunken appearance.

"--shadow-etched-out-dash"
A single dashed line with a 3D raised appearance.

"--shadow-double-etched-in"
Two lines with a 3D sunken appearance.

"--shadow-double-etched-out"
Two lines with a 3D raised appearance.

"--shadow-double-etched-in-dash"
Two dashed lines with a 3D sunken appearance.

"--shadow-double-etched-out-dash"
Two dashed lines with a 3D raised appearance.
You can also give these names in another style, adding a colon after the double-dash and replacing each single dash with capitalization of the following word. Thus, "--:singleLine", is equivalent to "--single-line".

Some systems and display toolkits don't really handle all of these separator types. If you use a type that isn't supported, the menu displays a similar kind of separator that is supported.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.1.4 Alias Menu Items

Sometimes it is useful to make menu items that use the "same" command but with different enable conditions. The best way to do this in Emacs now is with extended menu items; before that feature existed, it could be done by defining alias commands and using them in menu items. Here's an example that makes two aliases for toggle-read-only and gives them different enable conditions:
(defalias 'make-read-only 'toggle-read-only)
(put 'make-read-only 'menu-enable '(not buffer-read-only))
(defalias 'make-writable 'toggle-read-only)
(put 'make-writable 'menu-enable 'buffer-read-only)
When using aliases in menus, often it is useful to display the equivalent key bindings for the "real" command name, not the aliases (which typically don't have any key bindings except for the menu itself). To request this, give the alias symbol a non-nil menu-alias property. Thus,
(put 'make-read-only 'menu-alias t)
(put 'make-writable 'menu-alias t)
causes menu items for make-read-only and make-writable to show the keyboard bindings for toggle-read-only.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.2 Menus and the Mouse

The usual way to make a menu keymap produce a menu is to make it the definition of a prefix key. (A Lisp program can explicitly pop up a menu and receive the user's choice--see 29.15 Pop-Up Menus.)

If the prefix key ends with a mouse event, Emacs handles the menu keymap by popping up a visible menu, so that the user can select a choice with the mouse. When the user clicks on a menu item, the event generated is whatever character or symbol has the binding that brought about that menu item. (A menu item may generate a series of events if the menu has multiple levels or comes from the menu bar.)

It's often best to use a button-down event to trigger the menu. Then the user can select a menu item by releasing the button.

A single keymap can appear as multiple menu panes, if you explicitly arrange for this. The way to do this is to make a keymap for each pane, then create a binding for each of those maps in the main keymap of the menu. Give each of these bindings an item string that starts with `@'. The rest of the item string becomes the name of the pane. See the file `lisp/mouse.el' for an example of this. Any ordinary bindings with `@'-less item strings are grouped into one pane, which appears along with the other panes explicitly created for the submaps.

X toolkit menus don't have panes; instead, they can have submenus. Every nested keymap becomes a submenu, whether the item string starts with `@' or not. In a toolkit version of Emacs, the only thing special about `@' at the beginning of an item string is that the `@' doesn't appear in the menu item.

You can also produce multiple panes or submenus from separate keymaps. The full definition of a prefix key always comes from merging the definitions supplied by the various active keymaps (minor mode, local, and global). When more than one of these keymaps is a menu, each of them makes a separate pane or panes (when Emacs does not use an X-toolkit) or a separate submenu (when using an X-toolkit). See section 22.6 Active Keymaps.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.3 Menus and the Keyboard

When a prefix key ending with a keyboard event (a character or function key) has a definition that is a menu keymap, the user can use the keyboard to choose a menu item.

Emacs displays the menu's overall prompt string followed by the alternatives (the item strings of the bindings) in the echo area. If the bindings don't all fit at once, the user can type SPC to see the next line of alternatives. Successive uses of SPC eventually get to the end of the menu and then cycle around to the beginning. (The variable menu-prompt-more-char specifies which character is used for this; SPC is the default.)

When the user has found the desired alternative from the menu, he or she should type the corresponding character--the one whose binding is that alternative.

This way of using menus in an Emacs-like editor was inspired by the Hierarkey system.

Variable: menu-prompt-more-char
This variable specifies the character to use to ask to see the next line of a menu. Its initial value is 32, the code for SPC.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.4 Menu Example

Here is a complete example of defining a menu keymap. It is the definition of the `Print' submenu in the `Tools' menu in the menu bar, and it uses the simple menu item format (see section 22.12.1.1 Simple Menu Items). First we create the keymap, and give it a name:
(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
Next we define the menu items:
(define-key menu-bar-print-menu [ps-print-region]
  '("Postscript Print Region" . ps-print-region-with-faces))
(define-key menu-bar-print-menu [ps-print-buffer]
  '("Postscript Print Buffer" . ps-print-buffer-with-faces))
(define-key menu-bar-print-menu [separator-ps-print]
  '("--"))
(define-key menu-bar-print-menu [print-region]
  '("Print Region" . print-region))
(define-key menu-bar-print-menu [print-buffer]
  '("Print Buffer" . print-buffer))
Note the symbols which the bindings are "made for"; these appear inside square brackets, in the key sequence being defined. In some cases, this symbol is the same as the command name; sometimes it is different. These symbols are treated as "function keys", but they are not real function keys on the keyboard. They do not affect the functioning of the menu itself, but they are "echoed" in the echo area when the user selects from the menu, and they appear in the output of where-is and apropos.

The binding whose definition is ("--") is a separator line. Like a real menu item, the separator has a key symbol, in this case separator-ps-print. If one menu has two separators, they must have two different key symbols.

Here is code to define enable conditions for two of the commands in the menu:
(put 'print-region 'menu-enable 'mark-active)
(put 'ps-print-region-with-faces 'menu-enable 'mark-active)
Here is how we make this menu appear as an item in the parent menu:
(define-key menu-bar-tools-menu [print]
  (cons "Print" menu-bar-print-menu))
Note that this incorporates the submenu keymap, which is the value of the variable menu-bar-print-menu, rather than the symbol menu-bar-print-menu itself. Using that symbol in the parent menu item would be meaningless because menu-bar-print-menu is not a command.

If you wanted to attach the same print menu to a mouse click, you can do it this way:
(define-key global-map [C-S-down-mouse-1]
   menu-bar-print-menu)
We could equally well use an extended menu item (see section 22.12.1.2 Extended Menu Items) for print-region, like this:
(define-key menu-bar-print-menu [print-region]
  '(menu-item "Print Region" print-region
              :enable mark-active))
With the extended menu item, the enable condition is specified inside the menu item itself. If we wanted to make this item disappear from the menu entirely when the mark is inactive, we could do it this way:
(define-key menu-bar-print-menu [print-region]
  '(menu-item "Print Region" print-region
              :visible mark-active))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.5 The Menu Bar

Most window systems allow each frame to have a menu bar---a permanently displayed menu stretching horizontally across the top of the frame. The items of the menu bar are the subcommands of the fake "function key" menu-bar, as defined by all the active keymaps.

To add an item to the menu bar, invent a fake "function key" of your own (let's call it key), and make a binding for the key sequence [menu-bar key]. Most often, the binding is a menu keymap, so that pressing a button on the menu bar item leads to another menu.

When more than one active keymap defines the same fake function key for the menu bar, the item appears just once. If the user clicks on that menu bar item, it brings up a single, combined menu containing all the subcommands of that item--the global subcommands, the local subcommands, and the minor mode subcommands.

The variable overriding-local-map is normally ignored when determining the menu bar contents. That is, the menu bar is computed from the keymaps that would be active if overriding-local-map were nil. See section 22.6 Active Keymaps.

In order for a frame to display a menu bar, its menu-bar-lines parameter must be greater than zero. Emacs uses just one line for the menu bar itself; if you specify more than one line, the other lines serve to separate the menu bar from the windows in the frame. We recommend 1 or 2 as the value of menu-bar-lines. See section 29.3.3 Window Frame Parameters.

Here's an example of setting up a menu bar item:
(modify-frame-parameters (selected-frame)
                         '((menu-bar-lines . 2)))

;; Make a menu keymap (with a prompt string)
;; and make it the menu bar item's definition.
(define-key global-map [menu-bar words]
  (cons "Words" (make-sparse-keymap "Words")))

;; Define specific subcommands in this menu.
(define-key global-map
  [menu-bar words forward]
  '("Forward word" . forward-word))
(define-key global-map
  [menu-bar words backward]
  '("Backward word" . backward-word))
A local keymap can cancel a menu bar item made by the global keymap by rebinding the same fake function key with undefined as the binding. For example, this is how Dired suppresses the `Edit' menu bar item:
(define-key dired-mode-map [menu-bar edit] 'undefined)
edit is the fake function key used by the global map for the `Edit' menu bar item. The main reason to suppress a global menu bar item is to regain space for mode-specific items.

Variable: menu-bar-final-items
Normally the menu bar shows global items followed by items defined by the local maps.

This variable holds a list of fake function keys for items to display at the end of the menu bar rather than in normal sequence. The default value is (help-menu); thus, the `Help' menu item normally appears at the end of the menu bar, following local menu items.

Variable: menu-bar-update-hook
This normal hook is run whenever the user clicks on the menu bar, before displaying a submenu. You can use it to update submenus whose contents should vary.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.6 Tool bars

A tool bar is a row of icons at the top of a frame, that execute commands when you click on them--in effect, a kind of graphical menu bar. Emacs supports tool bars starting with version 21.

The frame parameter tool-bar-lines (X resource `toolBar') controls how many lines' worth of height to reserve for the tool bar. A zero value suppresses the tool bar. If the value is nonzero, and auto-resize-tool-bars is non-nil, the tool bar expands and contracts automatically as needed to hold the specified contents.

The tool bar contents are controlled by a menu keymap attached to a fake "function key" called tool-bar (much like the way the menu bar is controlled). So you define a tool bar item using define-key, like this:
(define-key global-map [tool-bar key] item)
where key is a fake "function key" to distinguish this item from other items, and item is a menu item key binding (see section 22.12.1.2 Extended Menu Items), which says how to display this item and how it behaves.

The usual menu keymap item properties, :visible, :enable, :button, and :filter, are useful in tool bar bindings and have their normal meanings. The real-binding in the item must be a command, not a keymap; in other words, it does not work to define a tool bar icon as a prefix key.

The :help property specifies a "help-echo" string to display while the mouse is on that item. This is displayed in the same way as help-echo text properties (see Help display).

In addition, you should use the :image property; this is how you specify the image to display in the tool bar:

:image image
images is either a single image specification or a vector of four image specifications. If you use a vector of four, one of them is used, depending on circumstances:

item 0
Used when the item is enabled and selected.
item 1
Used when the item is enabled and deselected.
item 2
Used when the item is disabled and selected.
item 3
Used when the item is disabled and deselected.
If image is a single image specification, Emacs draws the tool bar button in disabled state by applying an edge-detection algorithm to the image.

The default tool bar is defined so that items specific to editing do not appear for major modes whose command symbol has a mode-class property of special (see section 23.1.1 Major Mode Conventions). Major modes may add items to the global bar by binding [tool-bar foo] in their local map. It makes sense for some major modes to replace the default tool bar items completely, since not many can be accommodated conveniently, and the default bindings make this easy by using an indirection through tool-bar-map.

Variable: tool-bar-map
By default, the global map binds [tool-bar] as follows:
(global-set-key [tool-bar]
        '(menu-item "tool bar" ignore
                :filter (lambda (ignore) tool-bar-map)))
Thus the tool bar map is derived dynamically from the value of variable tool-bar-map and you should normally adjust the default (global) tool bar by changing that map. Major modes may replace the global bar completely by making tool-bar-map buffer-local and set to a keymap containing only the desired items. Info mode provides an example.

There are two convenience functions for defining tool bar items, as follows.

Function: tool-bar-add-item icon def key &rest props
This function adds an item to the tool bar by modifying tool-bar-map. The image to use is defined by icon, which is the base name of an XPM, XBM or PBM image file to located by find-image. Given a value `"exit"', say, `exit.xpm', `exit.pbm' and `exit.xbm' would be searched for in that order on a color display. On a monochrome display, the search order is `.pbm', `.xbm' and `.xpm'. The binding to use is the command def, and key is the fake function key symbol in the prefix keymap. The remaining arguments props are additional property list elements to add to the menu item specification.

To define items in some local map, bind `tool-bar-map with let around calls of this function:
(defvar foo-tool-bar-map
  (let ((tool-bar-map (make-sparse-keymap)))
    (tool-bar-add-item ...)
    ...
    tool-bar-map))
Function: tool-bar-add-item-from-menu command icon &optional map &rest props
This command is a convenience for defining tool bar items which are consistent with existing menu bar bindings. The binding of command is looked up in the menu bar in map (default global-map) and modified to add an image specification for icon, which is looked for in the same way as by tool-bar-add-item. The resulting binding is then placed in tool-bar-map. map must contain an appropriate keymap bound to [menu-bar]. The remaining arguments props are additional property list elements to add to the menu item specification.

Variable: auto-resize-tool-bar
If this variable is non-nil, the tool bar automatically resizes to show all defined tool bar items--but not larger than a quarter of the frame's height.

Variable: auto-raise-tool-bar-items
If this variable is non-nil, tool bar items display in raised form when the mouse moves over them.

Variable: tool-bar-item-margin
This variable specifies an extra margin to add around tool bar items. The value is an integer, a number of pixels. The default is 1.

Variable: tool-bar-item-relief
This variable specifies the shadow width for tool bar items. The value is an integer, a number of pixels. The default is 3.

You can define a special meaning for clicking on a tool bar item with the shift, control, meta, etc., modifiers. You do this by setting up additional items that relate to the original item through the fake function keys. Specifically, the additional items should use the modified versions of the same fake function key used to name the original item.

Thus, if the original item was defined this way,
(define-key global-map [tool-bar shell]
  '(menu-item "Shell" shell
              :image (image :type xpm :file "shell.xpm")))
then here is how you can define clicking on the same tool bar image with the shift modifier:
(define-key global-map [tool-bar S-shell] 'some-command)
See section 21.6.2 Function Keys, for more information about how to add modifiers to function keys.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

22.12.7 Modifying Menus

When you insert a new item in an existing menu, you probably want to put it in a particular place among the menu's existing items. If you use define-key to add the item, it normally goes at the front of the menu. To put it elsewhere in the menu, use define-key-after:

Function: define-key-after map key binding &optional after
Define a binding in map for key, with value binding, just like define-key, but position the binding in map after the binding for the event after. The argument key should be of length one--a vector or string with just one element. But after should be a single event type--a symbol or a character, not a sequence. The new binding goes after the binding for after. If after is t or is omitted, then the new binding goes last, at the end of the keymap. However, new bindings are added before any inherited keymap.

Here is an example:
(define-key-after my-menu [drink]
  '("Drink" . drink-command) 'eat)
makes a binding for the fake function key DRINK and puts it right after the binding for EAT.

Here is how to insert an item called `Work' in the `Signals' menu of Shell mode, after the item break:
(define-key-after
  (lookup-key shell-mode-map [menu-bar signals])
  [work] '("Work" . work-command) 'break)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23. Major and Minor Modes

A mode is a set of definitions that customize Emacs and can be turned on and off while you edit. There are two varieties of modes: major modes, which are mutually exclusive and used for editing particular kinds of text, and minor modes, which provide features that users can enable individually.

This chapter describes how to write both major and minor modes, how to indicate them in the mode line, and how they run hooks supplied by the user. For related topics such as keymaps and syntax tables, see 22. Keymaps, and 35. Syntax Tables.

23.1 Major Modes

Defining major modes.

23.2 Minor Modes

Defining minor modes.

23.3 Mode Line Format

Customizing the text that appears in the mode line.

23.4 Imenu

How a mode can provide a menu of definitions in the buffer.

23.5 Font Lock Mode

How modes can highlight text according to syntax.

23.6 Hooks

How to use hooks; how to write code that provides hooks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.1 Major Modes

Major modes specialize Emacs for editing particular kinds of text. Each buffer has only one major mode at a time.

The least specialized major mode is called Fundamental mode. This mode has no mode-specific definitions or variable settings, so each Emacs command behaves in its default manner, and each option is in its default state. All other major modes redefine various keys and options. For example, Lisp Interaction mode provides special key bindings for C-j (eval-print-last-sexp), TAB (lisp-indent-line), and other keys.

When you need to write several editing commands to help you perform a specialized editing task, creating a new major mode is usually a good idea. In practice, writing a major mode is easy (in contrast to writing a minor mode, which is often difficult).

If the new mode is similar to an old one, it is often unwise to modify the old one to serve two purposes, since it may become harder to use and maintain. Instead, copy and rename an existing major mode definition and alter the copy--or define a derived mode (see section 23.1.5 Defining Derived Modes). For example, Rmail Edit mode, which is in `emacs/lisp/mail/rmailedit.el', is a major mode that is very similar to Text mode except that it provides two additional commands. Its definition is distinct from that of Text mode, but uses that of Text mode.

Even if the new mode is not an obvious derivative of any other mode, it can be convenient to define it as a derivative of fundamental-mode, so that define-derived-mode can automatically enforce the most important coding conventions for you.

Rmail Edit mode offers an example of changing the major mode temporarily for a buffer, so it can be edited in a different way (with ordinary Emacs commands rather than Rmail commands). In such cases, the temporary major mode usually provides a command to switch back to the buffer's usual mode (Rmail mode, in this case). You might be tempted to present the temporary redefinitions inside a recursive edit and restore the usual ones when the user exits; but this is a bad idea because it constrains the user's options when it is done in more than one buffer: recursive edits must be exited most-recently-entered first. Using an alternative major mode avoids this limitation. See section 21.12 Recursive Editing.

The standard GNU Emacs Lisp library directory tree contains the code for several major modes, in files such as `text-mode.el', `texinfo.el', `lisp-mode.el', `c-mode.el', and `rmail.el'. They are found in various subdirectories of the `lisp' directory. You can study these libraries to see how modes are written. Text mode is perhaps the simplest major mode aside from Fundamental mode. Rmail mode is a complicated and specialized mode.

23.1.1 Major Mode Conventions

Coding conventions for keymaps, etc.

23.1.2 Major Mode Examples

Text mode and Lisp modes.

23.1.3 How Emacs Chooses a Major Mode

How Emacs chooses the major mode automatically.

23.1.4 Getting Help about a Major Mode

Finding out how to use a mode.

23.1.5 Defining Derived Modes

Defining a new major mode based on another major mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.1.1 Major Mode Conventions

The code for existing major modes follows various coding conventions, including conventions for local keymap and syntax table initialization, global names, and hooks. Please follow these conventions when you define a new major mode.

This list of conventions is only partial, because each major mode should aim for consistency in general with other Emacs major modes. This makes Emacs as a whole more coherent. It is impossible to list here all the possible points where this issue might come up; if the Emacs developers point out an area where your major mode deviates from the usual conventions, please make it compatible.

Define a command whose name ends in `-mode', with no arguments, that switches to the new mode in the current buffer. This command should set up the keymap, syntax table, and buffer-local variables in an existing buffer, without changing the buffer's contents.

Write a documentation string for this command that describes the special commands available in this mode. C-h m (describe-mode) in your mode will display this string.
The documentation string may include the special documentation substrings, `\[command]', `\{keymap}', and `\<keymap>', which enable the documentation to adapt automatically to the user's own key bindings. See section 24.3 Substituting Key Bindings in Documentation.

The major mode command should start by calling kill-all-local-variables. This is what gets rid of the buffer-local variables of the major mode previously in effect.

The major mode command should set the variable major-mode to the major mode command symbol. This is how describe-mode discovers which documentation to print.

The major mode command should set the variable mode-name to the "pretty" name of the mode, as a string. This string appears in the mode line.

Since all global names are in the same name space, all the global variables, constants, and functions that are part of the mode should have names that start with the major mode name (or with an abbreviation of it if the name is long). See section D.1 Emacs Lisp Coding Conventions.

In a major mode for editing some kind of structured text, such as a programming language, indentation of text according to structure is probably useful. So the mode should set indent-line-function to a suitable function, and probably customize other variables for indentation.

The major mode should usually have its own keymap, which is used as the local keymap in all buffers in that mode. The major mode command should call use-local-map to install this local map. See section 22.6 Active Keymaps, for more information.
This keymap should be stored permanently in a global variable named modename-mode-map. Normally the library that defines the mode sets this variable.

See section 11.6 Tips for Defining Variables Robustly, for advice about how to write the code to set up the mode's keymap variable.

The key sequences bound in a major mode keymap should usually start with C-c, followed by a control character, a digit, or {, }, <, >, : or ;. The other punctuation characters are reserved for minor modes, and ordinary letters are reserved for users.
It is reasonable for a major mode to rebind a key sequence with a standard meaning, if it implements a command that does "the same job" in a way that fits the major mode better. For example, a major mode for editing a programming language might redefine C-M-a to "move to the beginning of a function" in a way that works better for that language.

Major modes such as Dired or Rmail that do not allow self-insertion of text can reasonably redefine letters and other printing characters as editing commands. Dired and Rmail both do this.

Major modes must not define RET to do anything other than insert a newline. The command to insert a newline and then indent is C-j. Please keep this distinction uniform for all major modes.

Major modes should not alter options that are primary a matter of user preference, such as whether Auto-Fill mode is enabled. Leave this to each user to decide. However, a major mode should customize other variables so that Auto-Fill mode will work usefully if the user decides to use it.

The mode may have its own syntax table or may share one with other related modes. If it has its own syntax table, it should store this in a variable named modename-mode-syntax-table. See section 35. Syntax Tables.

If the mode handles a language that has a syntax for comments, it should set the variables that define the comment syntax. See section `Options Controlling Comments' in The GNU Emacs Manual.

The mode may have its own abbrev table or may share one with other related modes. If it has its own abbrev table, it should store this in a variable named modename-mode-abbrev-table. See section 36.2 Abbrev Tables.

The mode should specify how to do highlighting for Font Lock mode, by setting up a buffer-local value for the variable font-lock-defaults (see section 23.5 Font Lock Mode).

The mode should specify how Imenu should find the definitions or sections of a buffer, by setting up a buffer-local value for the variable imenu-generic-expression or imenu-create-index-function (see section 23.4 Imenu).

Use defvar or defcustom to set mode-related variables, so that they are not reinitialized if they already have a value. (Such reinitialization could discard customizations made by the user.)

To make a buffer-local binding for an Emacs customization variable, use make-local-variable in the major mode command, not make-variable-buffer-local. The latter function would make the variable local to every buffer in which it is subsequently set, which would affect buffers that do not use this mode. It is undesirable for a mode to have such global effects. See section 11.10 Buffer-Local Variables.
With rare exceptions, the only reasonable way to use make-variable-buffer-local in a Lisp package is for a variable which is used only within that package. Using it on a variable used by other packages would interfere with them.

Each major mode should have a mode hook named modename-mode-hook. The major mode command should run that hook, with run-hooks, as the very last thing it does. See section 23.6 Hooks.

The major mode command may also run the hooks of some more basic modes. For example, indented-text-mode runs text-mode-hook as well as indented-text-mode-hook. It may run these other hooks immediately before the mode's own hook (that is, after everything else), or it may run them earlier.

If something special should be done if the user switches a buffer from this mode to any other major mode, this mode can set up a buffer-local value for change-major-mode-hook (see section 11.10.2 Creating and Deleting Buffer-Local Bindings).

If this mode is appropriate only for specially-prepared text, then the major mode command symbol should have a property named mode-class with value special, put on as follows:
(put 'funny-mode 'mode-class 'special)
This tells Emacs that new buffers created while the current buffer is in Funny mode should not inherit Funny mode. Modes such as Dired, Rmail, and Buffer List use this feature.

If you want to make the new mode the default for files with certain recognizable names, add an element to auto-mode-alist to select the mode for those file names. If you define the mode command to autoload, you should add this element in the same file that calls autoload. Otherwise, it is sufficient to add the element in the file that contains the mode definition. See section 23.1.3 How Emacs Chooses a Major Mode.

In the documentation, you should provide a sample autoload form and an example of how to add to auto-mode-alist, that users can include in their init files (see section 40.1.2 The Init File, `.emacs').

The top-level forms in the file defining the mode should be written so that they may be evaluated more than once without adverse consequences. Even if you never load the file more than once, someone else will.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.1.2 Major Mode Examples

Text mode is perhaps the simplest mode besides Fundamental mode. Here are excerpts from `text-mode.el' that illustrate many of the conventions listed above:
;; Create mode-specific tables.
(defvar text-mode-syntax-table nil
  "Syntax table used while in text mode.")

(if text-mode-syntax-table
    ()              ; Do not change the table if it is already set up.
  (setq text-mode-syntax-table (make-syntax-table))
  (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
  (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
  (modify-syntax-entry ?' "w   " text-mode-syntax-table))

(defvar text-mode-abbrev-table nil
  "Abbrev table used while in text mode.")
(define-abbrev-table 'text-mode-abbrev-table ())

(defvar text-mode-map nil    ; Create a mode-specific keymap.
  "Keymap for Text mode.
Many other modes, such as Mail mode, Outline mode and Indented Text mode,
inherit all the commands defined in this map.")

(if text-mode-map
    ()              ; Do not change the keymap if it is already set up.
  (setq text-mode-map (make-sparse-keymap))
  (define-key text-mode-map "\e\t" 'ispell-complete-word)
  (define-key text-mode-map "\t" 'indent-relative)
  (define-key text-mode-map "\es" 'center-line)
  (define-key text-mode-map "\eS" 'center-paragraph))
Here is the complete major mode function definition for Text mode:
(defun text-mode ()
  "Major mode for editing text intended for humans to read...
 Special commands: \\{text-mode-map}
Turning on text-mode runs the hook `text-mode-hook'."
  (interactive)
  (kill-all-local-variables)
  (use-local-map text-mode-map)
  (setq local-abbrev-table text-mode-abbrev-table)
  (set-syntax-table text-mode-syntax-table)
  (make-local-variable 'paragraph-start)
  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
  (make-local-variable 'paragraph-separate)
  (setq paragraph-separate paragraph-start)
  (make-local-variable 'indent-line-function)
  (setq indent-line-function 'indent-relative-maybe)
  (setq mode-name "Text")
  (setq major-mode 'text-mode)
  (run-hooks 'text-mode-hook))      ; Finally, this permits the user to
                                    ;   customize the mode with a hook.
The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction mode) have more features than Text mode and the code is correspondingly more complicated. Here are excerpts from `lisp-mode.el' that illustrate how these modes are written.
;; Create mode-specific table variables.
(defvar lisp-mode-syntax-table nil "")
(defvar emacs-lisp-mode-syntax-table nil "")
(defvar lisp-mode-abbrev-table nil "")

(if (not emacs-lisp-mode-syntax-table) ; Do not change the table
                                       ;   if it is already set.
    (let ((i 0))
      (setq emacs-lisp-mode-syntax-table (make-syntax-table))

      ;; Set syntax of chars up to 0 to class of chars that are
      ;;   part of symbol names but not words.
      ;;   (The number 0 is 48 in the ASCII character set.)
      (while (< i ?0)
        (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
        (setq i (1+ i)))
      ...
      ;; Set the syntax for other characters.
      (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
      (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
      ...
      (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
      (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
      ...))
;; Create an abbrev table for lisp-mode.
(define-abbrev-table 'lisp-mode-abbrev-table ())
Much code is shared among the three Lisp modes. The following function sets various variables; it is called by each of the major Lisp mode functions:
(defun lisp-mode-variables (lisp-syntax)
  (cond (lisp-syntax
      (set-syntax-table lisp-mode-syntax-table)))
  (setq local-abbrev-table lisp-mode-abbrev-table)
  ...
Functions such as forward-paragraph use the value of the paragraph-start variable. Since Lisp code is different from ordinary text, the paragraph-start variable needs to be set specially to handle Lisp. Also, comments are indented in a special fashion in Lisp and the Lisp modes need their own mode-specific comment-indent-function. The code to set these variables is the rest of lisp-mode-variables.
  (make-local-variable 'paragraph-start)
  (setq paragraph-start (concat page-delimiter "\\|$" ))
  (make-local-variable 'paragraph-separate)
  (setq paragraph-separate paragraph-start)
  ...
  (make-local-variable 'comment-indent-function)
  (setq comment-indent-function 'lisp-comment-indent))
  ...
Each of the different Lisp modes has a slightly different keymap. For example, Lisp mode binds C-c C-z to run-lisp, but the other Lisp modes do not. However, all Lisp modes have some commands in common. The following code sets up the common commands:
(defvar shared-lisp-mode-map ()
  "Keymap for commands shared by all sorts of Lisp modes.")

(if shared-lisp-mode-map
    ()
   (setq shared-lisp-mode-map (make-sparse-keymap))
   (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
   (define-key shared-lisp-mode-map "\177"
               'backward-delete-char-untabify))
And here is the code to set up the keymap for Lisp mode:
(defvar lisp-mode-map ()
  "Keymap for ordinary Lisp mode...")

(if lisp-mode-map
    ()
  (setq lisp-mode-map (make-sparse-keymap))
  (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
  (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
  (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
Finally, here is the complete major mode function definition for Lisp mode.
(defun lisp-mode ()
  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
Commands:
Delete converts tabs to spaces as it moves back.
Blank lines separate paragraphs.  Semicolons start comments.
\\{lisp-mode-map}
Note that `run-lisp' may be used either to start an inferior Lisp job
or to switch back to an existing one.

Entry to this mode calls the value of `lisp-mode-hook'
if that value is non-nil."
  (interactive)
  (kill-all-local-variables)
  (use-local-map lisp-mode-map)          ; Select the mode's keymap.
  (setq major-mode 'lisp-mode)           ; This is how describe-mode
                                         ;   finds out what to describe.
  (setq mode-name "Lisp")                ; This goes into the mode line.
  (lisp-mode-variables t)                ; This defines various variables.
  (setq imenu-case-fold-search t)
  (set-syntax-table lisp-mode-syntax-table)
  (run-hooks 'lisp-mode-hook))           ; This permits the user to use a
                                         ;   hook to customize the mode.
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.1.3 How Emacs Chooses a Major Mode

Based on information in the file name or in the file itself, Emacs automatically selects a major mode for the new buffer when a file is visited. It also processes local variables specified in the file text.

Command: fundamental-mode
Fundamental mode is a major mode that is not specialized for anything in particular. Other major modes are defined in effect by comparison with this one--their definitions say what to change, starting from Fundamental mode. The fundamental-mode function does not run any hooks; you're not supposed to customize it. (If you want Emacs to behave differently in Fundamental mode, change the global state of Emacs.)

Command: normal-mode &optional find-file
This function establishes the proper major mode and buffer-local variable bindings for the current buffer. First it calls set-auto-mode, then it runs hack-local-variables to parse, and bind or evaluate as appropriate, the file's local variables.

If the find-file argument to normal-mode is non-nil, normal-mode assumes that the find-file function is calling it. In this case, it may process a local variables list at the end of the file and in the `-*-' line. The variable enable-local-variables controls whether to do so. See section `Local Variables in Files' in The GNU Emacs Manual, for the syntax of the local variables section of a file.

If you run normal-mode interactively, the argument find-file is normally nil. In this case, normal-mode unconditionally processes any local variables list.

normal-mode uses condition-case around the call to the major mode function, so errors are caught and reported as a `File mode specification error', followed by the original error message.

Function: set-auto-mode
This function selects the major mode that is appropriate for the current buffer. It may base its decision on the value of the `-*-' line, on the visited file name (using auto-mode-alist), on the `#!' line (using interpreter-mode-alist), or on the file's local variables list. However, this function does not look for the `mode:' local variable near the end of a file; the hack-local-variables function does that. See section `How Major Modes are Chosen' in The GNU Emacs Manual.

User Option: default-major-mode
This variable holds the default major mode for new buffers. The standard value is fundamental-mode.

If the value of default-major-mode is nil, Emacs uses the (previously) current buffer's major mode for the major mode of a new buffer. However, if that major mode symbol has a mode-class property with value special, then it is not used for new buffers; Fundamental mode is used instead. The modes that have this property are those such as Dired and Rmail that are useful only with text that has been specially prepared.

Function: set-buffer-major-mode buffer
This function sets the major mode of buffer to the value of default-major-mode. If that variable is nil, it uses the current buffer's major mode (if that is suitable).

The low-level primitives for creating buffers do not use this function, but medium-level commands such as switch-to-buffer and find-file-noselect use it whenever they create buffers.

Variable: initial-major-mode
The value of this variable determines the major mode of the initial `*scratch*' buffer. The value should be a symbol that is a major mode command. The default value is lisp-interaction-mode.

Variable: auto-mode-alist
This variable contains an association list of file name patterns (regular expressions; see section 34.2 Regular Expressions) and corresponding major mode commands. Usually, the file name patterns test for suffixes, such as `.el' and `.c', but this need not be the case. An ordinary element of the alist looks like (regexp . mode-function).

For example,
(("\\`/tmp/fol/" . text-mode)
 ("\\.texinfo\\'" . texinfo-mode)
 ("\\.texi\\'" . texinfo-mode)
 ("\\.el\\'" . emacs-lisp-mode)
 ("\\.c\\'" . c-mode)
 ("\\.h\\'" . c-mode)
 ...)
When you visit a file whose expanded file name (see section 25.8.4 Functions that Expand Filenames) matches a regexp, set-auto-mode calls the corresponding mode-function. This feature enables Emacs to select the proper major mode for most files.

If an element of auto-mode-alist has the form (regexp function t), then after calling function, Emacs searches auto-mode-alist again for a match against the portion of the file name that did not match before. This feature is useful for uncompression packages: an entry of the form ("\\.gz\\'" function t) can uncompress the file and then put the uncompressed file in the proper mode according to the name sans `.gz'.

Here is an example of how to prepend several pattern pairs to auto-mode-alist. (You might use this sort of expression in your init file.)
(setq auto-mode-alist
  (append
   ;; File name (within directory) starts with a dot.
   '(("/\\.[^/]*\\'" . fundamental-mode)
     ;; File name has no dot.
     ("[^\\./]*\\'" . fundamental-mode)
     ;; File name ends in `.C'.
     ("\\.C\\'" . c++-mode))
   auto-mode-alist))
Variable: interpreter-mode-alist
This variable specifies major modes to use for scripts that specify a command interpreter in a `#!' line. Its value is a list of elements of the form (interpreter . mode); for example, ("perl" . perl-mode) is one element present by default. The element says to use mode mode if the file specifies an interpreter which matches interpreter. The value of interpreter is actually a regular expression.

This variable is applicable only when the auto-mode-alist does not indicate which major mode to use.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.1.4 Getting Help about a Major Mode

The describe-mode function is used to provide information about major modes. It is normally called with C-h m. The describe-mode function uses the value of major-mode, which is why every major mode function needs to set the major-mode variable.

Command: describe-mode
This function displays the documentation of the current major mode.

The describe-mode function calls the documentation function using the value of major-mode as an argument. Thus, it displays the documentation string of the major mode function. (See section 24.2 Access to Documentation Strings.)

Variable: major-mode
This variable holds the symbol for the current buffer's major mode. This symbol should have a function definition that is the command to switch to that major mode. The describe-mode function uses the documentation string of the function as the documentation of the major mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.1.5 Defining Derived Modes

It's often useful to define a new major mode in terms of an existing one. An easy way to do this is to use define-derived-mode.

Macro: define-derived-mode variant parent name docstring body...
This construct defines variant as a major mode command, using name as the string form of the mode name.

The new command variant is defined to call the function parent, then override certain aspects of that parent mode:

The new mode has its own keymap, named variant-map. define-derived-mode initializes this map to inherit from parent-map, if it is not already set.

The new mode has its own syntax table, kept in the variable variant-syntax-table. define-derived-mode initializes this variable by copying parent-syntax-table, if it is not already set.

The new mode has its own abbrev table, kept in the variable variant-abbrev-table. define-derived-mode initializes this variable by copying parent-abbrev-table, if it is not already set.

The new mode has its own mode hook, variant-hook, which it runs in standard fashion as the very last thing that it does. (The new mode also runs the mode hook of parent as part of calling parent.)

In addition, you can specify how to override other aspects of parent with body. The command variant evaluates the forms in body after setting up all its usual overrides, just before running variant-hook.

The argument docstring specifies the documentation string for the new mode. If you omit docstring, define-derived-mode generates a documentation string.

Here is a hypothetical example:
(define-derived-mode hypertext-mode
  text-mode "Hypertext"
  "Major mode for hypertext.
\\{hypertext-mode-map}"
  (setq case-fold-search nil))

(define-key hypertext-mode-map
  [down-mouse-3] 'do-hyper-link)
Do not write an interactive spec in the definition; define-derived-mode does that automatically.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.2 Minor Modes

A minor mode provides features that users may enable or disable independently of the choice of major mode. Minor modes can be enabled individually or in combination. Minor modes would be better named "generally available, optional feature modes," except that such a name would be unwieldy.

A minor mode is not usually meant as a variation of a single major mode. Usually they are general and can apply to many major modes. For example, Auto Fill mode works with any major mode that permits text insertion. To be general, a minor mode must be effectively independent of the things major modes do.

A minor mode is often much more difficult to implement than a major mode. One reason is that you should be able to activate and deactivate minor modes in any order. A minor mode should be able to have its desired effect regardless of the major mode and regardless of the other minor modes in effect.

Often the biggest problem in implementing a minor mode is finding a way to insert the necessary hook into the rest of Emacs. Minor mode keymaps make this easier than it used to be.

23.2.1 Conventions for Writing Minor Modes

Tips for writing a minor mode.

23.2.2 Keymaps and Minor Modes

How a minor mode can have its own keymap.

23.2.3 Defining Minor Modes

A convenient facility for defining minor modes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.2.1 Conventions for Writing Minor Modes

There are conventions for writing minor modes just as there are for major modes. Several of the major mode conventions apply to minor modes as well: those regarding the name of the mode initialization function, the names of global symbols, and the use of keymaps and other tables.

In addition, there are several conventions that are specific to minor modes.

Make a variable whose name ends in `-mode' to control the minor mode. We call this the mode variable. The minor mode command should set this variable (nil to disable; anything else to enable).
If possible, implement the mode so that setting the variable automatically enables or disables the mode. Then the minor mode command does not need to do anything except set the variable.

This variable is used in conjunction with the minor-mode-alist to display the minor mode name in the mode line. It can also enable or disable a minor mode keymap. Individual commands or hooks can also check the variable's value.

If you want the minor mode to be enabled separately in each buffer, make the variable buffer-local.

Define a command whose name is the same as the mode variable. Its job is to enable and disable the mode by setting the variable.
The command should accept one optional argument. If the argument is nil, it should toggle the mode (turn it on if it is off, and off if it is on). Otherwise, it should turn the mode on if the argument is a positive integer, a symbol other than nil or -, or a list whose CAR is such an integer or symbol; it should turn the mode off otherwise.

Here is an example taken from the definition of transient-mark-mode. It shows the use of transient-mark-mode as a variable that enables or disables the mode's behavior, and also shows the proper way to toggle, enable or disable the minor mode based on the raw prefix argument value.
(setq transient-mark-mode
      (if (null arg) (not transient-mark-mode)
        (> (prefix-numeric-value arg) 0)))
Add an element to minor-mode-alist for each minor mode (see section 23.3.2 Variables Used in the Mode Line), if you want to indicate the minor mode in the mode line. This element should be a list of the following form:
(mode-variable string)
Here mode-variable is the variable that controls enabling of the minor mode, and string is a short string, starting with a space, to represent the mode in the mode line. These strings must be short so that there is room for several of them at once.

When you add an element to minor-mode-alist, use assq to check for an existing element, to avoid duplication. For example:
(unless (assq 'leif-mode minor-mode-alist)
  (setq minor-mode-alist
        (cons '(leif-mode " Leif") minor-mode-alist)))
or like this, using add-to-list (see section 11.8 How to Alter a Variable Value):
(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
Global minor modes distributed with Emacs should if possible support enabling and disabling via Custom (see section 14. Writing Customization Definitions). To do this, the first step is to define the mode variable with defcustom, and specify :type boolean.

If just setting the variable is not sufficient to enable the mode, you should also specify a :set method which enables the mode by invoke the mode command. Note in the variable's documentation string that setting the variable other than via Custom may not take effect.

Also mark the definition with an autoload cookie (see section 15.4 Autoload), and specify a :require so that customizing the variable will load the library that defines the mode. This will copy suitable definitions into `loaddefs.el' so that users can use customize-option to enable the mode. For example:
;;;###autoload
(defcustom msb-mode nil
  "Toggle msb-mode.
Setting this variable directly does not take effect;
use either \\[customize] or the function `msb-mode'."
  :set (lambda (symbol value)
     (msb-mode (or value 0)))
  :initialize 'custom-initialize-default
  :version "20.4"
  :type    'boolean
  :group   'msb
  :require 'msb)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.2.2 Keymaps and Minor Modes

Each minor mode can have its own keymap, which is active when the mode is enabled. To set up a keymap for a minor mode, add an element to the alist minor-mode-map-alist. See section 22.6 Active Keymaps.

One use of minor mode keymaps is to modify the behavior of certain self-inserting characters so that they do something else as well as self-insert. In general, this is the only way to do that, since the facilities for customizing self-insert-command are limited to special cases (designed for abbrevs and Auto Fill mode). (Do not try substituting your own definition of self-insert-command for the standard one. The editor command loop handles this function specially.)

The key sequences bound in a minor mode should consist of C-c followed by a punctuation character other than {, }, <, >, :, and ;. (Those few punctuation characters are reserved for major modes.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.2.3 Defining Minor Modes

The macro define-minor-mode offers a convenient way of implementing a mode in one self-contained definition. It supports only buffer-local minor modes, not global ones.

Macro: define-minor-mode mode doc &optional init-value mode-indicator keymap body...
This macro defines a new minor mode whose name is mode (a symbol). It defines a command named mode to toggle the minor mode, with doc as its documentation string. It also defines a variable named mode, which is set to t or nil by enabling or disabling the mode. The variable is initialized to init-value.

The command named mode finishes by executing the body forms, if any, after it has performed the standard actions such as setting the variable named mode.

The string mode-indicator says what to display in the mode line when the mode is enabled; if it is nil, the mode is not displayed in the mode line.

The optional argument keymap specifies the keymap for the minor mode. It can be a variable name, whose value is the keymap, or it can be an alist specifying bindings in this form:
(key-sequence . definition)
Here is an example of using define-minor-mode:
(define-minor-mode hungry-mode
  "Toggle Hungry mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.

When Hungry mode is enabled, the control delete key
gobbles all preceding whitespace except the last.
See the command \\[hungry-electric-delete]."
 ;; The initial value.
 nil
 ;; The indicator for the mode line.
 " Hungry"
 ;; The minor mode bindings.
 '(("\C-\^?" . hungry-electric-delete)
   ("\C-\M-\^?"
    . (lambda ()
        (interactive)
        (hungry-electric-delete t)))))
This defines a minor mode named "Hungry mode", a command named hungry-mode to toggle it, a variable named hungry-mode which indicates whether the mode is enabled, and a variable named hungry-mode-map which holds the keymap that is active when the mode is enabled. It initializes the keymap with key bindings for C-DEL and C-M-DEL.

The name easy-mmode-define-minor-mode is an alias for this macro.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.3 Mode Line Format

Each Emacs window (aside from minibuffer windows) typically has a mode line at the bottom, which displays status information about the buffer displayed in the window. The mode line contains information about the buffer, such as its name, associated file, depth of recursive editing, and major and minor modes. A window can also have a header line, which is much like the mode line but appears at the top of the window (starting in Emacs 21).

This section describes how to control the contents of the mode line and header line. We include it in this chapter because much of the information displayed in the mode line relates to the enabled major and minor modes.

mode-line-format is a buffer-local variable that holds a template used to display the mode line of the current buffer. All windows for the same buffer use the same mode-line-format, so their mode lines appear the same--except for scrolling percentages, and line and column numbers, since those depend on point and on how the window is scrolled. header-line-format is used likewise for header lines.

The mode line and header line of a window are normally updated whenever a different buffer is shown in the window, or when the buffer's modified-status changes from nil to t or vice-versa. If you modify any of the variables referenced by mode-line-format (see section 23.3.2 Variables Used in the Mode Line), or any other variables and data structures that affect how text is displayed (see section 38. Emacs Display), you may want to force an update of the mode line so as to display the new information or display it in the new way.

Function: force-mode-line-update
Force redisplay of the current buffer's mode line and header line.

The mode line is usually displayed in inverse video; see mode-line-inverse-video in 38.15 Inverse Video.

23.3.1 The Data Structure of the Mode Line

The data structure that controls the mode line.

23.3.2 Variables Used in the Mode Line

Variables used in that data structure.

23.3.3 %-Constructs in the Mode Line

Putting information into a mode line.

23.3.4 Properties in the Mode Line

Using text properties in the mode line.

23.3.5 Window Header Lines

Like a mode line, but at the top.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.3.1 The Data Structure of the Mode Line

The mode line contents are controlled by a data structure of lists, strings, symbols, and numbers kept in buffer-local variables. The data structure is called a mode line construct, and it is built in recursive fashion out of simpler mode line constructs. The same data structure is used for constructing frame titles (see section 29.4 Frame Titles) and header lines (see section 23.3.5 Window Header Lines).

Variable: mode-line-format
The value of this variable is a mode line construct with overall responsibility for the mode line format. The value of this variable controls which other variables are used to form the mode line text, and where they appear.

If you set this variable to nil in a buffer, that buffer does not have a mode line. (This feature was added in Emacs 21.)

A mode line construct may be as simple as a fixed string of text, but it usually specifies how to use other variables to construct the text. Many of these variables are themselves defined to have mode line constructs as their values.

The default value of mode-line-format incorporates the values of variables such as mode-name and minor-mode-alist. Because of this, very few modes need to alter mode-line-format itself. For most purposes, it is sufficient to alter some of the variables that mode-line-format refers to.

A mode line construct may be a list, a symbol, or a string. If the value is a list, each element may be a list, a symbol, or a string.

The mode line can display various faces, if the strings that control it have the face property. See section 23.3.4 Properties in the Mode Line. In addition, the face mode-line is used as a default for the whole mode line (see section 38.11.1 Standard Faces).

string
A string as a mode line construct is displayed verbatim in the mode line except for %-constructs. Decimal digits after the `%' specify the field width for space filling on the right (i.e., the data is left justified). See section 23.3.3 %-Constructs in the Mode Line.

symbol
A symbol as a mode line construct stands for its value. The value of symbol is used as a mode line construct, in place of symbol. However, the symbols t and nil are ignored, as is any symbol whose value is void.
There is one exception: if the value of symbol is a string, it is displayed verbatim: the %-constructs are not recognized.

(string rest...) or (list rest...)
A list whose first element is a string or list means to process all the elements recursively and concatenate the results. This is the most common form of mode line construct.

(:eval form)
A list whose first element is the symbol :eval says to evaluate form, and use the result as a string to display. (This feature is new as of Emacs 21.)

(symbol then else)
A list whose first element is a symbol that is not a keyword specifies a conditional. Its meaning depends on the value of symbol. If the value is non-nil, the second element, then, is processed recursively as a mode line element. But if the value of symbol is nil, the third element, else, is processed recursively. You may omit else; then the mode line element displays nothing if the value of symbol is nil.

(width rest...)
A list whose first element is an integer specifies truncation or padding of the results of rest. The remaining elements rest are processed recursively as mode line constructs and concatenated together. Then the result is space filled (if width is positive) or truncated (to -width columns, if width is negative) on the right.
For example, the usual way to show what percentage of a buffer is above the top of the window is to use a list like this: (-3 "%p").
If you do alter mode-line-format itself, the new value should use the same variables that appear in the default value (see section 23.3.2 Variables Used in the Mode Line), rather than duplicating their contents or displaying the information in another fashion. This way, customizations made by the user or by Lisp programs (such as display-time and major modes) via changes to those variables remain effective.

Here is an example of a mode-line-format that might be useful for shell-mode, since it contains the host name and default directory.
(setq mode-line-format
  (list "-"
   'mode-line-mule-info
   'mode-line-modified
   'mode-line-frame-identification
   "%b--"
   ;; Note that this is evaluated while making the list.
   ;; It makes a mode line construct which is just a string.
   (getenv "HOST")
   ":"
   'default-directory
   "   "
   'global-mode-string
   "   %[("
   '(:eval (mode-line-mode-name))
   'mode-line-process
   'minor-mode-alist
   "%n"
   ")%]--"
   '(which-func-mode ("" which-func-format "--"))
   '(line-number-mode "L%l--")
   '(column-number-mode "C%c--")
   '(-3 . "%p")
   "-%-"))
(The variables line-number-mode, column-number-mode and which-func-mode enable particular minor modes; as usual, these variable names are also the minor mode command names.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.3.2 Variables Used in the Mode Line

This section describes variables incorporated by the standard value of mode-line-format into the text of the mode line. There is nothing inherently special about these variables; any other variables could have the same effects on the mode line if mode-line-format were changed to use them.

Variable: mode-line-mule-info
This variable holds the value of the mode-line construct that displays information about the language environment, buffer coding system, and current input method. See section 33. Non-ASCII Characters.

Variable: mode-line-modified
This variable holds the value of the mode-line construct that displays whether the current buffer is modified.

The default value of mode-line-modified is ("%1*%1+"). This means that the mode line displays `**' if the buffer is modified, `--' if the buffer is not modified, `%%' if the buffer is read only, and `%*' if the buffer is read only and modified.

Changing this variable does not force an update of the mode line.

Variable: mode-line-frame-identification
This variable identifies the current frame. The default value is " " if you are using a window system which can show multiple frames, or "-%F " on an ordinary terminal which shows only one frame at a time.

Variable: mode-line-buffer-identification
This variable identifies the buffer being displayed in the window. Its default value is ("%12b"), which displays the buffer name, padded with spaces to at least 12 columns.

Variable: global-mode-string
This variable holds a mode line spec that appears in the mode line by default, just after the buffer name. The command display-time sets global-mode-string to refer to the variable display-time-string, which holds a string containing the time and load information.

The `%M' construct substitutes the value of global-mode-string, but that is obsolete, since the variable is included in the mode line from mode-line-format.

Variable: mode-name
This buffer-local variable holds the "pretty" name of the current buffer's major mode. Each major mode should set this variable so that the mode name will appear in the mode line.

Variable: minor-mode-alist
This variable holds an association list whose elements specify how the mode line should indicate that a minor mode is active. Each element of the minor-mode-alist should be a two-element list:
(minor-mode-variable mode-line-string)
More generally, mode-line-string can be any mode line spec. It appears in the mode line when the value of minor-mode-variable is non-nil, and not otherwise. These strings should begin with spaces so that they don't run together. Conventionally, the minor-mode-variable for a specific mode is set to a non-nil value when that minor mode is activated.

The default value of minor-mode-alist is:
minor-mode-alist
=> ((vc-mode vc-mode)
    (abbrev-mode " Abbrev")
    (overwrite-mode overwrite-mode)
    (auto-fill-function " Fill")
    (defining-kbd-macro " Def")
    (isearch-mode isearch-mode))
minor-mode-alist itself is not buffer-local. Each variable mentioned in the alist should be buffer-local if its minor mode can be enabled separately in each buffer.

Variable: mode-line-process
This buffer-local variable contains the mode line information on process status in modes used for communicating with subprocesses. It is displayed immediately following the major mode name, with no intervening space. For example, its value in the `*shell*' buffer is (":%s"), which allows the shell to display its status along with the major mode as: `(Shell:run)'. Normally this variable is nil.

Some variables are used by minor-mode-alist to display a string for various minor modes when enabled. This is a typical example:

Variable: vc-mode
The variable vc-mode, buffer-local in each buffer, records whether the buffer's visited file is maintained with version control, and, if so, which kind. Its value is a string that appears in the mode line, or nil for no version control.

The variable default-mode-line-format is where mode-line-format usually gets its value:

Variable: default-mode-line-format
This variable holds the default mode-line-format for buffers that do not override it. This is the same as (default-value 'mode-line-format).

The default value of default-mode-line-format is this list:
("-"
 mode-line-mule-info
 mode-line-modified
 mode-line-frame-identification
 mode-line-buffer-identification
 "   "
 global-mode-string
 "   %[("
 ;; mode-line-mode-name is a function
 ;; that copies the mode name and adds text
 ;; properties to make it mouse-sensitive.
 (:eval (mode-line-mode-name))
 mode-line-process
 minor-mode-alist
 "%n"
 ")%]--"
 (which-func-mode ("" which-func-format "--"))
 (line-number-mode "L%l--")
 (column-number-mode "C%c--")
 (-3 . "%p")
 "-%-")
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.3.3 %-Constructs in the Mode Line

The following table lists the recognized %-constructs and what they mean. In any construct except `%%', you can add a decimal integer after the `%' to specify how many characters to display.

%b
The current buffer name, obtained with the buffer-name function. See section 27.3 Buffer Names.

%c
The current column number of point.

%f
The visited file name, obtained with the buffer-file-name function. See section 27.4 Buffer File Name.

%F
The title (only on a window system) or the name of the selected frame. See section 29.3.3 Window Frame Parameters.

%l
The current line number of point, counting within the accessible portion of the buffer.

%n
`Narrow' when narrowing is in effect; nothing otherwise (see narrow-to-region in 30.4 Narrowing).

%p
The percentage of the buffer text above the top of window, or `Top', `Bottom' or `All'. Note that the default mode-line specification truncates this to three characters.

%P
The percentage of the buffer text that is above the bottom of the window (which includes the text visible in the window, as well as the text above the top), plus `Top' if the top of the buffer is visible on screen; or `Bottom' or `All'.

%s
The status of the subprocess belonging to the current buffer, obtained with process-status. See section 37.6 Process Information.

%t
Whether the visited file is a text file or a binary file. This is a meaningful distinction only on certain operating systems (see section 33.10.9 MS-DOS File Types).

%*
`%' if the buffer is read only (see buffer-read-only);
`*' if the buffer is modified (see buffer-modified-p);
`-' otherwise. See section 27.5 Buffer Modification.

%+
`*' if the buffer is modified (see buffer-modified-p);
`%' if the buffer is read only (see buffer-read-only);
`-' otherwise. This differs from `%*' only for a modified read-only buffer. See section 27.5 Buffer Modification.

%&
`*' if the buffer is modified, and `-' otherwise.

%[
An indication of the depth of recursive editing levels (not counting minibuffer levels): one `[' for each editing level. See section 21.12 Recursive Editing.

%]
One `]' for each recursive editing level (not counting minibuffer levels).

%-
Dashes sufficient to fill the remainder of the mode line.

%%
The character `%'---this is how to include a literal `%' in a string in which %-constructs are allowed.
The following two %-constructs are still supported, but they are obsolete, since you can get the same results with the variables mode-name and global-mode-string.

%m
The value of mode-name.

%M
The value of global-mode-string. Currently, only display-time modifies the value of global-mode-string.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.3.4 Properties in the Mode Line

Starting in Emacs 21, certain text properties are meaningful in the mode line. The face property affects the appearance of text; the help-echo property associate help strings with the text, and local-map can make the text mouse-sensitive.

There are three ways to specify text properties for text in the mode line:

Put a string with the local-map property directly into the mode-line data structure.

Put a local-map property on a mode-line %-construct such as `%12b'; then the expansion of the %-construct will have that same text property.

Use a list containing :eval form in the mode-line data structure, and make form evaluate to a string that has a local-map property.

You use the local-map property to specify a keymap. Like any keymap, it can bind character keys and function keys; but that has no effect, since it is impossible to move point into the mode line. This keymap can only take real effect for mouse clicks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.3.5 Window Header Lines

Starting in Emacs 21, a window can have a header line at the top, just as it can have a mode line at the bottom. The header line feature works just like the mode line feature, except that it's controlled by different variables.

Variable: header-line-format
This variable, local in every buffer, specifies how to display the header line, for windows displaying the buffer. The format of the value is the same as for mode-line-format (see section 23.3.1 The Data Structure of the Mode Line).

Variable: default-header-line-format
This variable holds the default header-line-format for buffers that do not override it. This is the same as (default-value 'header-line-format).

It is normally nil, so that ordinary buffers have no header line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.4 Imenu

Imenu is a feature that lets users select a definition or section in the buffer, from a menu which lists all of them, to go directly to that location in the buffer. Imenu works by constructing a buffer index which lists the names and buffer positions of the definitions, or other named portions of the buffer; then the user can choose one of them and move point to it. This section explains how to customize how Imenu finds the definitions or buffer portions for a particular major mode.

The usual and simplest way is to set the variable imenu-generic-expression:

Variable: imenu-generic-expression
This variable, if non-nil, specifies regular expressions for finding definitions for Imenu. In the simplest case, elements should look like this:
(menu-title regexp subexp)
Here, if menu-title is non-nil, it says that the matches for this element should go in a submenu of the buffer index; menu-title itself specifies the name for the submenu. If menu-title is nil, the matches for this element go directly in the top level of the buffer index.

The second item in the list, regexp, is a regular expression (see section 34.2 Regular Expressions); anything in the buffer that it matches is considered a definition, something to mention in the buffer index. The third item, subexp, indicates which subexpression in regexp matches the definition's name.

An element can also look like this:
(menu-title regexp index function arguments...)
Each match for this element creates a special index item which, if selected by the user, calls function with arguments consisting of the item name, the buffer position, and arguments.

For Emacs Lisp mode, pattern could look like this:
((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
 ("*Types*"
  "^\\s-*\
(def\\(type\\|struct\\|class\\|ine-condition\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2))
Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-case-fold-search
This variable controls whether matching against imenu-generic-expression is case-sensitive: t, the default, means matching should ignore case.

Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-syntax-alist
This variable is an alist of syntax table modifiers to use while processing imenu-generic-expression, to override the syntax table of the current buffer. Each element should have this form:
(characters . syntax-description)
The CAR, characters, can be either a character or a string. The element says to give that character or characters the syntax specified by syntax-description, which is passed to modify-syntax-entry (see section 35.3 Syntax Table Functions).

This feature is typically used to give word syntax to characters which normally have symbol syntax, and thus to simplify imenu-generic-expression and speed up matching. For example, Fortran mode uses it this way:
  (setq imenu-syntax-alist '(("_$" . "w")))
The imenu-generic-expression patterns can then use `\\sw+' instead of `\\(\\sw\\|\\s_\\)+'. Note that this technique may be inconvenient when the mode needs to limit the initial character of a name to a smaller set of characters than are allowed in the rest of a name.

Setting this variable makes it buffer-local in the current buffer.

Another way to customize Imenu for a major mode is to set the variables imenu-prev-index-position-function and imenu-extract-index-name-function:

Variable: imenu-prev-index-position-function
If this variable is non-nil, its value should be a function that finds the next "definition" to put in the buffer index, scanning backward in the buffer from point. It should return nil if it doesn't find another "definition" before point. Otherwise it shuould leave point at the place it finds a "definition," and return any non-nil value.

Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-extract-index-name-function
If this variable is non-nil, its value should be a function to return the name for a definition, assuming point is in that definition as the imenu-prev-index-position-function function would leave it.

Setting this variable makes it buffer-local in the current buffer.

The last way to customize Imenu for a major mode is to set the variable imenu-create-index-function:

Variable: imenu-create-index-function
This variable specifies the function to use for creating a buffer index. The function should take no arguments, and return an index for the current buffer. It is called within save-excursion, so where it leaves point makes no difference.

The default value is a function that uses imenu-generic-expression to produce the index alist. If you specify a different function, then imenu-generic-expression is not used.

Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-index-alist
This variable holds the index alist for the current buffer. Setting it makes it buffer-local in the current buffer.

Simple elements in the alist look like (index-name . index-position). Selecting a simple element has the effect of moving to position index-position in the buffer.

Special elements look like (index-name position function arguments...). Selecting a special element performs
(funcall function index-name position arguments...)
A nested sub-alist element looks like (index-name sub-alist).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.5 Font Lock Mode

Font Lock mode is a feature that automatically attaches face properties to certain parts of the buffer based on their syntactic role. How it parses the buffer depends on the major mode; most major modes define syntactic criteria for which faces to use in which contexts. This section explains how to customize Font Lock for a particular major mode.

Font Lock mode finds text to highlight in two ways: through syntactic parsing based on the syntax table, and through searching (usually for regular expressions). Syntactic fontification happens first; it finds comments and string constants, and highlights them using font-lock-comment-face and font-lock-string-face (see section 23.5.5 Faces for Font Lock). Search-based fontification follows.

23.5.1 Font Lock Basics

23.5.2 Search-based Fontification

23.5.3 Other Font Lock Variables

23.5.4 Levels of Font Lock

23.5.5 Faces for Font Lock

23.5.6 Syntactic Font Lock

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.5.1 Font Lock Basics

There are several variables that control how Font Lock mode highlights text. But major modes should not set any of these variables directly. Instead, they should set font-lock-defaults as a buffer-local variable. The value assigned to this variable is used, if and when Font Lock mode is enabled, to set all the other variables.

Variable: font-lock-defaults
This variable is set by major modes, as a buffer-local variable, to specify how to fontify text in that mode. The value should look like this:
(keywords keywords-only case-fold
 syntax-alist syntax-begin other-vars...)
The first element, keywords, indirectly specifies the value of font-lock-keywords. It can be a symbol, a variable whose value is the list to use for font-lock-keywords. It can also be a list of several such symbols, one for each possible level of fontification. The first symbol specifies how to do level 1 fontification, the second symbol how to do level 2, and so on.

The second element, keywords-only, specifies the value of the variable font-lock-keywords-only. If this is non-nil, syntactic fontification (of strings and comments) is not performed.

The third element, case-fold, specifies the value of font-lock-case-fold-search. If it is non-nil, Font Lock mode ignores case when searching as directed by font-lock-keywords.

If the fourth element, syntax-alist, is non-nil, it should be a list of cons cells of the form (char-or-string . string). These are used to set up a syntax table for fontification (see section 35.3 Syntax Table Functions). The resulting syntax table is stored in font-lock-syntax-table.

The fifth element, syntax-begin, specifies the value of font-lock-beginning-of-syntax-function (see below).

All the remaining elements (if any) are collectively called other-vars. Each of these elements should have the form (variable . value)---which means, make variable buffer-local and then set it to value. You can use these other-vars to set other variables that affect fontification, aside from those you can control with the first five elements.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.5.2 Search-based Fontification

The most important variable for customizing Font Lock mode is font-lock-keywords. It specifies the search criteria for search-based fontification.

Variable: font-lock-keywords
This variable's value is a list of the keywords to highlight. Be careful when composing regular expressions for this list; a poorly written pattern can dramatically slow things down!

Each element of font-lock-keywords specifies how to find certain cases of text, and how to highlight those cases. Font Lock mode processes the elements of font-lock-keywords one by one, and for each element, it finds and handles all matches. Ordinarily, once part of the text has been fontified already, this cannot be overridden by a subsequent match in the same text; but you can specify different behavior using the override element of a highlighter.

Each element of font-lock-keywords should have one of these forms:

regexp
Highlight all matches for regexp using font-lock-keyword-face. For example,
;; Highlight discrete occurrences of `foo'
;; using font-lock-keyword-face.
"\\"
The function regexp-opt (see section 34.2.1 Syntax of Regular Expressions) is useful for calculating optimal regular expressions to match a number of different keywords.

function
Find text by calling function, and highlight the matches it finds using font-lock-keyword-face.
When function is called, it receives one argument, the limit of the search. It should return non-nil if it succeeds, and set the match data to describe the match that was found.

(matcher . match)
In this kind of element, matcher is either a regular expression or a function, as described above. The CDR, match, specifies which subexpression of matcher should be highlighted (instead of the entire text that matcher matched).
;; Highlight the `bar' in each occurrence of `fubar',
;; using font-lock-keyword-face.
("fu\\(bar\\)" . 1)
If you use regexp-opt to produce the regular expression matcher, then you can use regexp-opt-depth (see section 34.2.1 Syntax of Regular Expressions) to calculate the value for match.

(matcher . facename)
In this kind of element, facename is an expression whose value specifies the face name to use for highlighting.
;; Highlight occurrences of `fubar',
;; using the face which is the value of fubar-face.
("fubar" . fubar-face)
(matcher . highlighter)
In this kind of element, highlighter is a list which specifies how to highlight matches found by matcher. It has the form
(subexp facename override laxmatch)
The CAR, subexp, is an integer specifying which subexpression of the match to fontify (0 means the entire matching text). The second subelement, facename, specifies the face, as described above.

The last two values in highlighter, override and laxmatch, are flags. If override is t, this element can override existing fontification made by previous elements of font-lock-keywords. If it is keep, then each character is fontified if it has not been fontified already by some other element. If it is prepend, the face facename is added to the beginning of the face property. If it is append, the face facename is added to the end of the face property.

If laxmatch is non-nil, it means there should be no error if there is no subexpression numbered subexp in matcher. Obviously, fontification of the subexpression numbered subexp will not occur. However, fontification of other subexpressions (and other regexps) will continue. If laxmatch is nil, and the specified subexpression is missing, then an error is signalled which terminates search-based fontification.

Here are some examples of elements of this kind, and what they do:
;; Highlight occurrences of either `foo' or `bar',
;; using foo-bar-face, even if they have already been highlighted.
;; foo-bar-face should be a variable whose value is a face.
("foo\\|bar" 0 foo-bar-face t)

;; Highlight the first subexpression within each occurrence
;; that the function fubar-match finds,
;; using the face which is the value of fubar-face.
(fubar-match 1 fubar-face)
(matcher highlighters...)
This sort of element specifies several highlighter lists for a single matcher. In order for this to be useful, each highlighter should have a different value of subexp; that is, each one should apply to a different subexpression of matcher.

(eval . form)
Here form is an expression to be evaluated the first time this value of font-lock-keywords is used in a buffer. Its value should have one of the forms described in this table.
Warning: Do not design an element of font-lock-keywords to match text which spans lines; this does not work reliably. While font-lock-fontify-buffer handles multi-line patterns correctly, updating when you edit the buffer does not, since it considers text one line at a time.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.5.3 Other Font Lock Variables

This section describes additional variables that a major mode can set by means of font-lock-defaults.

Variable: font-lock-keywords-only
Non-nil means Font Lock should not fontify comments or strings syntactically; it should only fontify based on font-lock-keywords.

Variable: font-lock-keywords-case-fold-search
Non-nil means that regular expression matching for the sake of font-lock-keywords should be case-insensitive.

Variable: font-lock-syntax-table
This variable specifies the syntax table to use for fontification of comments and strings.

Variable: font-lock-beginning-of-syntax-function
If this variable is non-nil, it should be a function to move point back to a position that is syntactically at "top level" and outside of strings or comments. Font Lock uses this when necessary to get the right results for syntactic fontification.

This function is called with no arguments. It should leave point at the beginning of any enclosing syntactic block. Typical values are beginning-of-line (i.e., the start of the line is known to be outside a syntactic block), or beginning-of-defun for programming modes or backward-paragraph for textual modes (i.e., the mode-dependent function is known to move outside a syntactic block).

If the value is nil, the beginning of the buffer is used as a position outside of a syntactic block. This cannot be wrong, but it can be slow.

Variable: font-lock-mark-block-function
If this variable is non-nil, it should be a function that is called with no arguments, to choose an enclosing range of text for refontification for the command M-g M-g (font-lock-fontify-block).

The function should report its choice by placing the region around it. A good choice is a range of text large enough to give proper results, but not too large so that refontification becomes slow. Typical values are mark-defun for programming modes or mark-paragraph for textual modes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.5.4 Levels of Font Lock

Many major modes offer three different levels of fontification. You can define multiple levels by using a list of symbols for keywords in font-lock-defaults. Each symbol specifies one level of fontification; it is up to the user to choose one of these levels. The chosen level's symbol value is used to initialize font-lock-keywords.

Here are the conventions for how to define the levels of fontification:

Level 1: highlight function declarations, file directives (such as include or import directives), strings and comments. The idea is speed, so only the most important and top-level components are fontified.

Level 2: in addition to level 1, highlight all language keywords, including type names that act like keywords, as well as named constant values. The idea is that all keywords (either syntactic or semantic) should be fontified appropriately.

Level 3: in addition to level 2, highlight the symbols being defined in function and variable declarations, and all builtin function names, wherever they appear.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.5.5 Faces for Font Lock

You can make Font Lock mode use any face, but several faces are defined specifically for Font Lock mode. Each of these symbols is both a face name, and a variable whose default value is the symbol itself. Thus, the default value of font-lock-comment-face is font-lock-comment-face. This means you can write font-lock-comment-face in a context such as font-lock-keywords where a face-name-valued expression is used.

font-lock-comment-face
Used (typically) for comments.

font-lock-string-face
Used (typically) for string constants.

font-lock-keyword-face
Used (typically) for keywords--names that have special syntactic significance, like for and if in C.

font-lock-builtin-face
Used (typically) for built-in function names.

font-lock-function-name-face
Used (typically) for the name of a function being defined or declared, in a function definition or declaration.

font-lock-variable-name-face
Used (typically) for the name of a variable being defined or declared, in a variable definition or declaration.

font-lock-type-face
Used (typically) for names of user-defined data types, where they are defined and where they are used.

font-lock-constant-face
Used (typically) for constant names.

font-lock-warning-face
Used (typically) for constructs that are peculiar, or that greatly change the meaning of other text. For example, this is used for `;;;###autoload' cookies in Emacs Lisp, and for #error directives in C.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.5.6 Syntactic Font Lock

Font Lock mode can be used to update syntax-table properties automatically. This is useful in languages for which a single syntax table by itself is not sufficient.

Variable: font-lock-syntactic-keywords
This variable enables and controls syntactic Font Lock. Its value should be a list of elements of this form:
(matcher subexp syntax override laxmatch)
The parts of this element have the same meanings as in the corresponding sort of element of font-lock-keywords,
(matcher subexp facename override laxmatch)
However, instead of specifying the value facename to use for the face property, it specifies the value syntax to use for the syntax-table property. Here, syntax can be a variable whose value is a syntax table, a syntax entry of the form (syntax-code . matching-char), or an expression whose value is one of those two types.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

23.6 Hooks

A hook is a variable where you can store a function or functions to be called on a particular occasion by an existing program. Emacs provides hooks for the sake of customization. Most often, hooks are set up in the init file (see section 40.1.2 The Init File, `.emacs'), but Lisp programs can set them also. See section I. Standard Hooks, for a list of standard hook variables.

Most of the hooks in Emacs are normal hooks. These variables contain lists of functions to be called with no arguments. When the hook name ends in `-hook', that tells you it is normal. We try to make all hooks normal, as much as possible, so that you can use them in a uniform way.

Every major mode function is supposed to run a normal hook called the mode hook as the last step of initialization. This makes it easy for a user to customize the behavior of the mode, by overriding the buffer-local variable assignments already made by the mode. But hooks are used in other contexts too. For example, the hook suspend-hook runs just before Emacs suspends itself (see section 40.2.2 Suspending Emacs).

The recommended way to add a hook function to a normal hook is by calling add-hook (see below). The hook functions may be any of the valid kinds of functions that funcall accepts (see section 12.1 What Is a Function?). Most normal hook variables are initially void; add-hook knows how to deal with this.

If the hook variable's name does not end with `-hook', that indicates it is probably an abnormal hook. Then you should look at its documentation to see how to use the hook properly.

If the variable's name ends in `-functions' or `-hooks', then the value is a list of functions, but it is abnormal in that either these functions are called with arguments or their values are used in some way. You can use add-hook to add a function to the list, but you must take care in writing the function. (A few of these variables are actually normal hooks which were named before we established the convention of using `-hook' for them.)

If the variable's name ends in `-function', then its value is just a single function, not a list of functions.

Here's an example that uses a mode hook to turn on Auto Fill mode when in Lisp Interaction mode:
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
At the appropriate time, Emacs uses the run-hooks function to run particular hooks. This function calls the hook functions that have been added with add-hook.

Function: run-hooks &rest hookvars
This function takes one or more hook variable names as arguments, and runs each hook in turn. Each argument should be a symbol that is a hook variable. These arguments are processed in the order specified.

If a hook variable has a non-nil value, that value may be a function or a list of functions. If the value is a function (either a lambda expression or a symbol with a function definition), it is called. If it is a list, the elements are called, in order. The hook functions are called with no arguments. Nowadays, storing a single function in the hook variable is semi-obsolete; you should always use a list of functions.

For example, here's how emacs-lisp-mode runs its mode hook:
(run-hooks 'emacs-lisp-mode-hook)
Function: run-hook-with-args hook &rest args
This function is the way to run an abnormal hook which passes arguments to the hook functions. It calls each of the hook functions, passing each of them the arguments args.

Function: run-hook-with-args-until-failure hook &rest args
This function is the way to run an abnormal hook which passes arguments to the hook functions, and stops as soon as any hook function fails. It calls each of the hook functions, passing each of them the arguments args, until some hook function returns nil. Then it stops, and returns nil if some hook function returned nil. Otherwise it returns a non-nil value.

Function: run-hook-with-args-until-success hook &rest args
This function is the way to run an abnormal hook which passes arguments to the hook functions, and stops as soon as any hook function succeeds. It calls each of the hook functions, passing each of them the arguments args, until some hook function returns non-nil. Then it stops, and returns whatever was returned by the last hook function that was called.

Function: add-hook hook function &optional append local
This function is the handy way to add function function to hook variable hook. The argument function may be any valid Lisp function with the proper number of arguments. For example,
(add-hook 'text-mode-hook 'my-text-hook-function)
adds my-text-hook-function to the hook called text-mode-hook.

You can use add-hook for abnormal hooks as well as for normal hooks.

It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is "asking for trouble." However, the order is predictable: normally, function goes at the front of the hook list, so it will be executed first (barring another add-hook call). If the optional argument append is non-nil, the new hook function goes at the end of the hook list and will be executed last.

If local is non-nil, that says to make the new hook function buffer-local in the current buffer and automatically calls make-local-hook to make the hook itself buffer-local.

Function: remove-hook hook function &optional local
This function removes function from the hook variable hook.

If local is non-nil, that says to remove function from the buffer-local hook list instead of from the global hook list. If the hook variable itself is not buffer-local, then the value of local makes no difference.

Function: make-local-hook hook
This function makes the hook variable hook buffer-local in the current buffer. When a hook variable is buffer-local, it can have buffer-local and global hook functions, and run-hooks runs all of them.

This function works by adding t as an element of the buffer-local value. That serves as a flag to use the hook functions listed in the default value of the hook variable, as well as those listed in the buffer-local value. Since run-hooks understands this flag, make-local-hook works with all normal hooks. It works for only some non-normal hooks--those whose callers have been updated to understand this meaning of t.

Do not use make-local-variable directly for hook variables; it is not sufficient.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

24. Documentation

GNU Emacs Lisp has convenient on-line help facilities, most of which derive their information from the documentation strings associated with functions and variables. This chapter describes how to write good documentation strings for your Lisp programs, as well as how to write programs to access documentation.

Note that the documentation strings for Emacs are not the same thing as the Emacs manual. Manuals have their own source files, written in the Texinfo language; documentation strings are specified in the definitions of the functions and variables they apply to. A collection of documentation strings is not sufficient as a manual because a good manual is not organized in that fashion; it is organized in terms of topics of discussion.

24.1 Documentation Basics

Good style for doc strings. Where to put them. How Emacs stores them.

24.2 Access to Documentation Strings

How Lisp programs can access doc strings.

24.3 Substituting Key Bindings in Documentation

Substituting current key bindings.

24.4 Describing Characters for Help Messages

Making printable descriptions of non-printing characters and key sequences.

24.5 Help Functions

Subroutines used by Emacs help facilities.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

24.1 Documentation Basics

A documentation string is written using the Lisp syntax for strings, with double-quote characters surrounding the text of the string. This is because it really is a Lisp string object. The string serves as documentation when it is written in the proper place in the definition of a function or variable. In a function definition, the documentation string follows the argument list. In a variable definition, the documentation string follows the initial value of the variable.

When you write a documentation string, make the first line a complete sentence (or two complete sentences) since some commands, such as apropos, show only the first line of a multi-line documentation string. Also, you should not indent the second line of a documentation string, if it has one, because that looks odd when you use C-h f (describe-function) or C-h v (describe-variable) to view the documentation string. See section D.3 Tips for Documentation Strings.

Documentation strings can contain several special substrings, which stand for key bindings to be looked up in the current keymaps when the documentation is displayed. This allows documentation strings to refer to the keys for related commands and be accurate even when a user rearranges the key bindings. (See section 24.2 Access to Documentation Strings.)

In Emacs Lisp, a documentation string is accessible through the function or variable that it describes:

The documentation for a function is stored in the function definition itself (see section 12.2 Lambda Expressions). The function documentation knows how to extract it.

The documentation for a variable is stored in the variable's property list under the property name variable-documentation. The function documentation-property knows how to retrieve it.

To save space, the documentation for preloaded functions and variables (including primitive functions and autoloaded functions) is stored in the file `emacs/etc/DOC-version'---not inside Emacs. The documentation strings for functions and variables loaded during the Emacs session from byte-compiled files are stored in those files (see section 16.3 Documentation Strings and Compilation).

The data structure inside Emacs has an integer offset into the file, or a list containing a file name and an integer, in place of the documentation string. The functions documentation and documentation-property use that information to fetch the documentation string from the appropriate file; this is transparent to the user.

For information on the uses of documentation strings, see section `Help' in The GNU Emacs Manual.

The `emacs/lib-src' directory contains two utilities that you can use to print nice-looking hardcopy for the file `emacs/etc/DOC-version'. These are `sorted-doc' and `digest-doc'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

24.2 Access to Documentation Strings

Function: documentation-property symbol property &optional verbatim
This function returns the documentation string that is recorded in symbol's property list under property property. It retrieves the text from a file if the value calls for that. If the property value isn't nil, isn't a string, and doesn't refer to text in a file, then it is evaluated to obtain a string.

Finally, documentation-property passes the string through substitute-command-keys to substitute actual key bindings, unless verbatim is non-nil.
(documentation-property 'command-line-processed
   'variable-documentation)
     => "Non-nil once command line has been processed"
(symbol-plist 'command-line-processed)
     => (variable-documentation 188902)
Function: documentation function &optional verbatim
This function returns the documentation string of function.

If function is a symbol, this function first looks for the function-documentation property of that symbol; if that has a non-nil value, the documentation comes from that value (if the value is not a string, it is evaluated). If function is not a symbol, or if it has no function-documentation property, then documentation extracts the documentation string from the actual function definition, reading it from a file if called for.

Finally, unless verbatim is non-nil, it calls substitute-command-keys so as to return a value containing the actual (current) key bindings.

The function documentation signals a void-function error if function has no function definition. However, it is OK if the function definition has no documentation string. In that case, documentation returns nil.

Here is an example of using the two functions, documentation and documentation-property, to display the documentation strings for several symbols in a `*Help*' buffer.
(defun describe-symbols (pattern)
  "Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the `*Help*' buffer."
  (interactive "sDescribe symbols matching: ")
  (let ((describe-func
         (function
          (lambda (s)
            ;; Print description of symbol.
            (if (fboundp s)             ; It is a function.
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (commandp s)
                       (let ((keys (where-is-internal s)))
                         (if keys
                             (concat
                              "Keys: "
                              (mapconcat 'key-description
                                         keys " "))
                           "Keys: none"))
                     "Function")
                   (or (documentation s)
                       "not documented"))))

            (if (boundp s)              ; It is a variable.
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (user-variable-p s)
                       "Option " "Variable")
                   (or (documentation-property
                         s 'variable-documentation)
                       "not documented")))))))
        sym-list)

    ;; Build a list of symbols that match pattern.
    (mapatoms (function
               (lambda (sym)
                 (if (string-match pattern (symbol-name sym))
                     (setq sym-list (cons sym sym-list))))))

    ;; Display the data.
    (with-output-to-temp-buffer "*Help*"
      (mapcar describe-func (sort sym-list 'string<))
      (print-help-return-message))))
The describe-symbols function works like apropos, but provides more information.
(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option
*Semipermanent goal column for vertical motion, as set by ...

set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.

temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was
at the start of current run of vertical motion commands.
When the `track-eol' feature is doing its job, the value is 9999.
---------- Buffer: *Help* ----------
The asterisk `*' as the first character of a variable's doc string, as shown above for the goal-column variable, means that it is a user option; see the description of defvar in 11.5 Defining Global Variables.

Function: Snarf-documentation filename
This function is used only during Emacs initialization, just before the runnable Emacs is dumped. It finds the file offsets of the documentation strings stored in the file filename, and records them in the in-core function definitions and variable property lists in place of the actual strings. See section E.1 Building Emacs.

Emacs reads the file filename from the `emacs/etc' directory. When the dumped Emacs is later executed, the same file will be looked for in the directory doc-directory. Usually filename is "DOC-version".

Variable: doc-directory
This variable holds the name of the directory which should contain the file "DOC-version" that contains documentation strings for built-in and preloaded functions and variables.

In most cases, this is the same as data-directory. They may be different when you run Emacs from the directory where you built it, without actually installing it. See data-directory in 24.5 Help Functions.

In older Emacs versions, exec-directory was used for this.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

24.3 Substituting Key Bindings in Documentation

When documentation strings refer to key sequences, they should use the current, actual key bindings. They can do so using certain special text sequences described below. Accessing documentation strings in the usual way substitutes current key binding information for these special sequences. This works by calling substitute-command-keys. You can also call that function yourself.

Here is a list of the special sequences and what they mean:

\[command]
stands for a key sequence that will invoke command, or `M-x command' if command has no key bindings.

\{mapvar}
stands for a summary of the keymap which is the value of the variable mapvar. The summary is made using describe-bindings.

\<mapvar>
stands for no text itself. It is used only for a side effect: it specifies mapvar's value as the keymap for any following `\[command]' sequences in this documentation string.

\=
quotes the following character and is discarded; thus, `\=\[' puts `\[' into the output, and `\=\=' puts `\=' into the output.
Please note: Each `\' must be doubled when written in a string in Emacs Lisp.

Function: substitute-command-keys string
This function scans string for the above special sequences and replaces them by what they stand for, returning the result as a string. This permits display of documentation that refers accurately to the user's own customized key bindings.

Here are examples of the special sequences:
(substitute-command-keys
   "To abort recursive edit, type: \\[abort-recursive-edit]")
=> "To abort recursive edit, type: C-]"

(substitute-command-keys
   "The keys that are defined for the minibuffer here are:
  \\{minibuffer-local-must-match-map}")
=> "The keys that are defined for the minibuffer here are:

?               minibuffer-completion-help
SPC             minibuffer-complete-word
TAB             minibuffer-complete
C-j             minibuffer-complete-and-exit
RET             minibuffer-complete-and-exit
C-g             abort-recursive-edit
"

(substitute-command-keys
   "To abort a recursive edit from the minibuffer, type\
\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
=> "To abort a recursive edit from the minibuffer, type C-g."
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

24.4 Describing Characters for Help Messages

These functions convert events, key sequences, or characters to textual descriptions. These descriptions are useful for including arbitrary text characters or key sequences in messages, because they convert non-printing and whitespace characters to sequences of printing characters. The description of a non-whitespace printing character is the character itself.

Function: key-description sequence
This function returns a string containing the Emacs standard notation for the input events in sequence. The argument sequence may be a string, vector or list. See section 21.6 Input Events, for more information about valid events. See also the examples for single-key-description, below.

Function: single-key-description event &optional no-angles
This function returns a string describing event in the standard Emacs notation for keyboard input. A normal printing character appears as itself, but a control character turns into a string starting with `C-', a meta character turns into a string starting with `M-', and space, tab, etc. appear as `SPC', `TAB', etc. A function key symbol appears inside angle brackets `<...>'. An event that is a list appears as the name of the symbol in the CAR of the list, inside angle brackets.

If the optional argument no-angles is non-nil, the angle brackets around function keys and event symbols are omitted; this is for compatibility with old versions of Emacs which didn't use the brackets.
(single-key-description ?\C-x)
     => "C-x"
(key-description "\C-x \M-y \n \t \r \f123")
     => "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
(single-key-description 'delete)
     => "<delete>"
(single-key-description 'C-mouse-1)
     => "<C-mouse-1>"
(single-key-description 'C-mouse-1 t)
     => "C-mouse-1"
Function: text-char-description character
This function returns a string describing character in the standard Emacs notation for characters that appear in text--like single-key-description, except that control characters are represented with a leading caret (which is how control characters in Emacs buffers are usually displayed).
(text-char-description ?\C-c)
     => "^C"
(text-char-description ?\M-m)
     => "M-m"
(text-char-description ?\C-\M-m)
     => "M-^M"
Function: read-kbd-macro string
This function is used mainly for operating on keyboard macros, but it can also be used as a rough inverse for key-description. You call it with a string containing key descriptions, separated by spaces; it returns a string or vector containing the corresponding events. (This may or may not be a single valid key sequence, depending on what events you use; see section 22.1 Keymap Terminology.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

24.5 Help Functions

Emacs provides a variety of on-line help functions, all accessible to the user as subcommands of the prefix C-h. For more information about them, see section `Help' in The GNU Emacs Manual. Here we describe some program-level interfaces to the same information.

Command: apropos regexp &optional do-all
This function finds all symbols whose names contain a match for the regular expression regexp, and returns a list of them (see section 34.2 Regular Expressions). It also displays the symbols in a buffer named `*Help*', each with a one-line description taken from the beginning of its documentation string.

If do-all is non-nil, then apropos also shows key bindings for the functions that are found; it also shows all symbols, even those that are neither functions nor variables.

In the first of the following examples, apropos finds all the symbols with names containing `exec'. (We don't show here the output that results in the `*Help*' buffer.)
(apropos "exec")
     => (Buffer-menu-execute command-execute exec-directory
    exec-path execute-extended-command execute-kbd-macro
    executing-kbd-macro executing-macro)
Variable: help-map
The value of this variable is a local keymap for characters following the Help key, C-h.

Prefix Command: help-command
This symbol is not a function; its function definition cell holds the keymap known as help-map. It is defined in `help.el' as follows:
(define-key global-map "\C-h" 'help-command)
(fset 'help-command help-map)
Function: print-help-return-message &optional function
This function builds a string that explains how to restore the previous state of the windows after a help command. After building the message, it applies function to it if function is non-nil. Otherwise it calls message to display it in the echo area.

This function expects to be called inside a with-output-to-temp-buffer special form, and expects standard-output to have the value bound by that special form. For an example of its use, see the long example in 24.2 Access to Documentation Strings.

Variable: help-char
The value of this variable is the help character--the character that Emacs recognizes as meaning Help. By default, its value is 8, which stands for C-h. When Emacs reads this character, if help-form is a non-nil Lisp expression, it evaluates that expression, and displays the result in a window if it is a string.

Usually the value of help-form is nil. Then the help character has no special meaning at the level of command input, and it becomes part of a key sequence in the normal way. The standard key binding of C-h is a prefix key for several general-purpose help features.

The help character is special after prefix keys, too. If it has no binding as a subcommand of the prefix key, it runs describe-prefix-bindings, which displays a list of all the subcommands of the prefix key.

Variable: help-event-list
The value of this variable is a list of event types that serve as alternative "help characters." These events are handled just like the event specified by help-char.

Variable: help-form
If this variable is non-nil, its value is a form to evaluate whenever the character help-char is read. If evaluating the form produces a string, that string is displayed.

A command that calls read-event or read-char probably should bind help-form to a non-nil expression while it does input. (The time when you should not do this is when C-h has some other meaning.) Evaluating this expression should result in a string that explains what the input is for and how to enter it properly.

Entry to the minibuffer binds this variable to the value of minibuffer-help-form (see section 20.9 Minibuffer Miscellany).

Variable: prefix-help-command
This variable holds a function to print help for a prefix key. The function is called when the user types a prefix key followed by the help character, and the help character has no binding after that prefix. The variable's default value is describe-prefix-bindings.

Function: describe-prefix-bindings
This function calls describe-bindings to display a list of all the subcommands of the prefix key of the most recent key sequence. The prefix described consists of all but the last event of that key sequence. (The last event is, presumably, the help character.)

The following two functions are meant for modes that want to provide help without relinquishing control, such as the "electric" modes. Their names begin with `Helper' to distinguish them from the ordinary help functions.

Command: Helper-describe-bindings
This command pops up a window displaying a help buffer containing a listing of all of the key bindings from both the local and global keymaps. It works by calling describe-bindings.

Command: Helper-help
This command provides help for the current mode. It prompts the user in the minibuffer with the message `Help (Type ? for further options)', and then provides assistance in finding out what the key bindings are, and what the mode is intended for. It returns nil.

This can be customized by changing the map Helper-help-map.

Variable: data-directory
This variable holds the name of the directory in which Emacs finds certain documentation and text files that come with Emacs. In older Emacs versions, exec-directory was used for this.

Macro: make-help-screen fname help-line help-text help-map
This macro defines a help command named fname that acts like a prefix key that shows a list of the subcommands it offers.

When invoked, fname displays help-text in a window, then reads and executes a key sequence according to help-map. The string help-text should describe the bindings available in help-map.

The command fname is defined to handle a few events itself, by scrolling the display of help-text. When fname reads one of those special events, it does the scrolling and then reads another event. When it reads an event that is not one of those few, and which has a binding in help-map, it executes that key's binding and then returns.

The argument help-line should be a single-line summary of the alternatives in help-map. In the current version of Emacs, this argument is used only if you set the option three-step-help to t.

This macro is used in the command help-for-help which is the binding of C-h C-h.

User Option: three-step-help
If this variable is non-nil, commands defined with make-help-screen display their help-line strings in the echo area at first, and display the longer help-text strings only if the user types the help character again.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25. Files

In Emacs, you can find, create, view, save, and otherwise work with files and file directories. This chapter describes most of the file-related functions of Emacs Lisp, but a few others are described in 27. Buffers, and those related to backups and auto-saving are described in 26. Backups and Auto-Saving.

Many of the file functions take one or more arguments that are file names. A file name is actually a string. Most of these functions expand file name arguments by calling expand-file-name, so that `~' is handled correctly, as are relative file names (including `../'). These functions don't recognize environment variable substitutions such as `$HOME'. See section 25.8.4 Functions that Expand Filenames.

When file I/O functions signal Lisp errors, they usually use the condition file-error (see section 10.5.3.3 Writing Code to Handle Errors). The error message is in most cases obtained from the operating system, according to locale system-message-locale, and decoded using coding system locale-coding-system (see section 33.12 Locales).

25.1 Visiting Files

Reading files into Emacs buffers for editing.

25.2 Saving Buffers

Writing changed buffers back into files.

25.3 Reading from Files

Reading files into buffers without visiting.

25.4 Writing to Files

Writing new files from parts of buffers.

25.5 File Locks

Locking and unlocking files, to prevent simultaneous editing by two people.

25.6 Information about Files

Testing existence, accessibility, size of files.

25.7 Changing File Names and Attributes

Renaming files, changing protection, etc.

25.8 File Names

Decomposing and expanding file names.

25.9 Contents of Directories

Getting a list of the files in a directory.

25.10 Creating and Deleting Directories

25.11 Making Certain File Names "Magic"

Defining "magic" special handling for certain file names.

25.12 File Format Conversion

Conversion to and from various file formats.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.1 Visiting Files

Visiting a file means reading a file into a buffer. Once this is done, we say that the buffer is visiting that file, and call the file "the visited file" of the buffer.

A file and a buffer are two different things. A file is information recorded permanently in the computer (unless you delete it). A buffer, on the other hand, is information inside of Emacs that will vanish at the end of the editing session (or when you kill the buffer). Usually, a buffer contains information that you have copied from a file; then we say the buffer is visiting that file. The copy in the buffer is what you modify with editing commands. Such changes to the buffer do not change the file; therefore, to make the changes permanent, you must save the buffer, which means copying the altered buffer contents back into the file.

In spite of the distinction between files and buffers, people often refer to a file when they mean a buffer and vice-versa. Indeed, we say, "I am editing a file," rather than, "I am editing a buffer that I will soon save as a file of the same name." Humans do not usually need to make the distinction explicit. When dealing with a computer program, however, it is good to keep the distinction in mind.

25.1.1 Functions for Visiting Files

The usual interface functions for visiting.

25.1.2 Subroutines of Visiting

Lower-level subroutines that they use.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.1.1 Functions for Visiting Files

This section describes the functions normally used to visit files. For historical reasons, these functions have names starting with `find-' rather than `visit-'. See section 27.4 Buffer File Name, for functions and variables that access the visited file name of a buffer or that find an existing buffer by its visited file name.

In a Lisp program, if you want to look at the contents of a file but not alter it, the fastest way is to use insert-file-contents in a temporary buffer. Visiting the file is not necessary and takes longer. See section 25.3 Reading from Files.

Command: find-file filename &optional wildcards
This command selects a buffer visiting the file filename, using an existing buffer if there is one, and otherwise creating a new buffer and reading the file into it. It also returns that buffer.

The body of the find-file function is very simple and looks like this:
(switch-to-buffer (find-file-noselect filename))
(See switch-to-buffer in 28.7 Displaying Buffers in Windows.)

If wildcards is non-nil, which is always true in an interactive call, then find-file expands wildcard characters in filename and visits all the matching files.

When find-file is called interactively, it prompts for filename in the minibuffer.

Function: find-file-noselect filename &optional nowarn rawfile wildcards
This function is the guts of all the file-visiting functions. It finds or creates a buffer visiting the file filename, and returns it. It uses an existing buffer if there is one, and otherwise creates a new buffer and reads the file into it. You may make the buffer current or display it in a window if you wish, but this function does not do so.

If wildcards is non-nil, then find-file-noselect expands wildcard characters in filename and visits all the matching files.

When find-file-noselect uses an existing buffer, it first verifies that the file has not changed since it was last visited or saved in that buffer. If the file has changed, then this function asks the user whether to reread the changed file. If the user says `yes', any changes previously made in the buffer are lost.

This function displays warning or advisory messages in various peculiar cases, unless the optional argument nowarn is non-nil. For example, if it needs to create a buffer, and there is no file named filename, it displays the message `(New file)' in the echo area, and leaves the buffer empty.

The find-file-noselect function normally calls after-find-file after reading the file (see section 25.1.2 Subroutines of Visiting). That function sets the buffer major mode, parses local variables, warns the user if there exists an auto-save file more recent than the file just visited, and finishes by running the functions in find-file-hooks.

If the optional argument rawfile is non-nil, then after-find-file is not called, and the find-file-not-found-hooks are not run in case of failure. What's more, a non-nil rawfile value suppresses coding system conversion (see section 33.10 Coding Systems) and format conversion (see section 25.12 File Format Conversion).

The find-file-noselect function usually returns the buffer that is visiting the file filename. But, if wildcards are actually used and expanded, it returns a list of buffers that are visiting the various files.
(find-file-noselect "/etc/fstab")
     => #<buffer fstab>
Command: find-file-other-window filename &optional wildcards
This command selects a buffer visiting the file filename, but does so in a window other than the selected window. It may use another existing window or split a window; see 28.7 Displaying Buffers in Windows.

When this command is called interactively, it prompts for filename.

Command: find-file-read-only filename &optional wildcards
This command selects a buffer visiting the file filename, like find-file, but it marks the buffer as read-only. See section 27.7 Read-Only Buffers, for related functions and variables.

When this command is called interactively, it prompts for filename.

Command: view-file filename
This command visits filename using View mode, returning to the previous buffer when you exit View mode. View mode is a minor mode that provides commands to skim rapidly through the file, but does not let you modify the text. Entering View mode runs the normal hook view-mode-hook. See section 23.6 Hooks.

When view-file is called interactively, it prompts for filename.

Variable: find-file-wildcards
If this variable is non-nil, then the various find-file commands check for wildcard characters and visit all the files that match them. If this is nil, then wildcard characters are not treated specially.

Variable: find-file-hooks
The value of this variable is a list of functions to be called after a file is visited. The file's local-variables specification (if any) will have been processed before the hooks are run. The buffer visiting the file is current when the hook functions are run.

This variable works just like a normal hook, but we think that renaming it would not be advisable. See section 23.6 Hooks.

Variable: find-file-not-found-hooks
The value of this variable is a list of functions to be called when find-file or find-file-noselect is passed a nonexistent file name. find-file-noselect calls these functions as soon as it detects a nonexistent file. It calls them in the order of the list, until one of them returns non-nil. buffer-file-name is already set up.

This is not a normal hook because the values of the functions are used, and in many cases only some of the functions are called.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.1.2 Subroutines of Visiting

The find-file-noselect function uses two important subroutines which are sometimes useful in user Lisp code: create-file-buffer and after-find-file. This section explains how to use them.

Function: create-file-buffer filename
This function creates a suitably named buffer for visiting filename, and returns it. It uses filename (sans directory) as the name if that name is free; otherwise, it appends a string such as `<2>' to get an unused name. See also 27.9 Creating Buffers.

Please note: create-file-buffer does not associate the new buffer with a file and does not select the buffer. It also does not use the default major mode.
(create-file-buffer "foo")
     => #<buffer foo>
(create-file-buffer "foo")
     => #<buffer foo<2>>
(create-file-buffer "foo")
     => #<buffer foo<3>>
This function is used by find-file-noselect. It uses generate-new-buffer (see section 27.9 Creating Buffers).

Function: after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
This function sets the buffer major mode, and parses local variables (see section 23.1.3 How Emacs Chooses a Major Mode). It is called by find-file-noselect and by the default revert function (see section 26.3 Reverting).

If reading the file got an error because the file does not exist, but its directory does exist, the caller should pass a non-nil value for error. In that case, after-find-file issues a warning: `(New file)'. For more serious errors, the caller should usually not call after-find-file.

If warn is non-nil, then this function issues a warning if an auto-save file exists and is more recent than the visited file.

If noauto is non-nil, that says not to enable or disable Auto-Save mode. The mode remains enabled if it was enabled before.

If after-find-file-from-revert-buffer is non-nil, that means this call was from revert-buffer. This has no direct effect, but some mode functions and hook functions check the value of this variable.

If nomodes is non-nil, that means don't alter the buffer's major mode, don't process local variables specifications in the file, and don't run find-file-hooks. This feature is used by revert-buffer in some cases.

The last thing after-find-file does is call all the functions in the list find-file-hooks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.2 Saving Buffers

When you edit a file in Emacs, you are actually working on a buffer that is visiting that file--that is, the contents of the file are copied into the buffer and the copy is what you edit. Changes to the buffer do not change the file until you save the buffer, which means copying the contents of the buffer into the file.

Command: save-buffer &optional backup-option
This function saves the contents of the current buffer in its visited file if the buffer has been modified since it was last visited or saved. Otherwise it does nothing.

save-buffer is responsible for making backup files. Normally, backup-option is nil, and save-buffer makes a backup file only if this is the first save since visiting the file. Other values for backup-option request the making of backup files in other circumstances:

With an argument of 4 or 64, reflecting 1 or 3 C-u's, the save-buffer function marks this version of the file to be backed up when the buffer is next saved.

With an argument of 16 or 64, reflecting 2 or 3 C-u's, the save-buffer function unconditionally backs up the previous version of the file before saving it.

Command: save-some-buffers &optional save-silently-p pred
This command saves some modified file-visiting buffers. Normally it asks the user about each buffer. But if save-silently-p is non-nil, it saves all the file-visiting buffers without querying the user.

The optional pred argument controls which buffers to ask about. If it is nil, that means to ask only about file-visiting buffers. If it is t, that means also offer to save certain other non-file buffers--those that have a non-nil buffer-local value of buffer-offer-save. (A user who says `yes' to saving a non-file buffer is asked to specify the file name to use.) The save-buffers-kill-emacs function passes the value t for pred.

If pred is neither t nor nil, then it should be a function of no arguments. It will be called in each buffer to decide whether to offer to save that buffer. If it returns a non-nil value in a certain buffer, that means do offer to save that buffer.

Command: write-file filename &optional confirm
This function writes the current buffer into file filename, makes the buffer visit that file, and marks it not modified. Then it renames the buffer based on filename, appending a string like `<2>' if necessary to make a unique buffer name. It does most of this work by calling set-visited-file-name (see section 27.4 Buffer File Name) and save-buffer.

If confirm is non-nil, that means to ask for confirmation before overwriting an existing file.

Saving a buffer runs several hooks. It also performs format conversion (see section 25.12 File Format Conversion), and may save text properties in "annotations" (see section 32.19.7 Saving Text Properties in Files).

Variable: write-file-hooks
The value of this variable is a list of functions to be called before writing out a buffer to its visited file. If one of them returns non-nil, the file is considered already written and the rest of the functions are not called, nor is the usual code for writing the file executed.

If a function in write-file-hooks returns non-nil, it is responsible for making a backup file (if that is appropriate). To do so, execute the following code:
(or buffer-backed-up (backup-buffer))
You might wish to save the file modes value returned by backup-buffer and use that to set the mode bits of the file that you write. This is what save-buffer normally does.

The hook functions in write-file-hooks are also responsible for encoding the data (if desired): they must choose a suitable coding system (see section 33.10.3 Coding Systems in Lisp), perform the encoding (see section 33.10.7 Explicit Encoding and Decoding), and set last-coding-system-used to the coding system that was used (see section 33.10.2 Encoding and I/O).

Do not make this variable buffer-local. To set up buffer-specific hook functions, use write-contents-hooks instead.

Even though this is not a normal hook, you can use add-hook and remove-hook to manipulate the list. See section 23.6 Hooks.

Variable: local-write-file-hooks
This works just like write-file-hooks, but it is intended to be made buffer-local in particular buffers, and used for hooks that pertain to the file name or the way the buffer contents were obtained.

The variable is marked as a permanent local, so that changing the major mode does not alter a buffer-local value. This is convenient for packages that read "file" contents in special ways, and set up hooks to save the data in a corresponding way.

Variable: write-contents-hooks
This works just like write-file-hooks, but it is intended for hooks that pertain to the contents of the file, as opposed to hooks that pertain to where the file came from. Such hooks are usually set up by major modes, as buffer-local bindings for this variable.

This variable automatically becomes buffer-local whenever it is set; switching to a new major mode always resets this variable. When you use add-hooks to add an element to this hook, you should not specify a non-nil local argument, since this variable is used only buffer-locally.

Variable: after-save-hook
This normal hook runs after a buffer has been saved in its visited file. One use of this hook is in Fast Lock mode; it uses this hook to save the highlighting information in a cache file.

Variable: file-precious-flag
If this variable is non-nil, then save-buffer protects against I/O errors while saving by writing the new file to a temporary name instead of the name it is supposed to have, and then renaming it to the intended name after it is clear there are no errors. This procedure prevents problems such as a lack of disk space from resulting in an invalid file.

As a side effect, backups are necessarily made by copying. See section 26.1.2 Backup by Renaming or by Copying?. Yet, at the same time, saving a precious file always breaks all hard links between the file you save and other file names.

Some modes give this variable a non-nil buffer-local value in particular buffers.

User Option: require-final-newline
This variable determines whether files may be written out that do not end with a newline. If the value of the variable is t, then save-buffer silently adds a newline at the end of the file whenever the buffer being saved does not already end in one. If the value of the variable is non-nil, but not t, then save-buffer asks the user whether to add a newline each time the case arises.

If the value of the variable is nil, then save-buffer doesn't add newlines at all. nil is the default value, but a few major modes set it to t in particular buffers.

See also the function set-visited-file-name (see section 27.4 Buffer File Name).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.3 Reading from Files

You can copy a file from the disk and insert it into a buffer using the insert-file-contents function. Don't use the user-level command insert-file in a Lisp program, as that sets the mark.

Function: insert-file-contents filename &optional visit beg end replace
This function inserts the contents of file filename into the current buffer after point. It returns a list of the absolute file name and the length of the data inserted. An error is signaled if filename is not the name of a file that can be read.

The function insert-file-contents checks the file contents against the defined file formats, and converts the file contents if appropriate. See section 25.12 File Format Conversion. It also calls the functions in the list after-insert-file-functions; see 32.19.7 Saving Text Properties in Files. Normally, one of the functions in the after-insert-file-functions list determines the coding system (see section 33.10 Coding Systems) used for decoding the file's contents.

If visit is non-nil, this function additionally marks the buffer as unmodified and sets up various fields in the buffer so that it is visiting the file filename: these include the buffer's visited file name and its last save file modtime. This feature is used by find-file-noselect and you probably should not use it yourself.

If beg and end are non-nil, they should be integers specifying the portion of the file to insert. In this case, visit must be nil. For example,
(insert-file-contents filename nil 0 500)
inserts the first 500 characters of a file.

If the argument replace is non-nil, it means to replace the contents of the buffer (actually, just the accessible portion) with the contents of the file. This is better than simply deleting the buffer contents and inserting the whole file, because (1) it preserves some marker positions and (2) it puts less data in the undo list.

It is possible to read a special file (such as a FIFO or an I/O device) with insert-file-contents, as long as replace and visit are nil.

Function: insert-file-contents-literally filename &optional visit beg end replace
This function works like insert-file-contents except that it does not do format decoding (see section 25.12 File Format Conversion), does not do character code conversion (see section 33.10 Coding Systems), does not run find-file-hooks, does not perform automatic uncompression, and so on.

If you want to pass a file name to another process so that another program can read the file, use the function file-local-copy; see 25.11 Making Certain File Names "Magic".

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.4 Writing to Files

You can write the contents of a buffer, or part of a buffer, directly to a file on disk using the append-to-file and write-region functions. Don't use these functions to write to files that are being visited; that could cause confusion in the mechanisms for visiting.

Command: append-to-file start end filename
This function appends the contents of the region delimited by start and end in the current buffer to the end of file filename. If that file does not exist, it is created. This function returns nil.

An error is signaled if filename specifies a nonwritable file, or a nonexistent file in a directory where files cannot be created.

Command: write-region start end filename &optional append visit lockname mustbenew
This function writes the region delimited by start and end in the current buffer into the file specified by filename.

If start is a string, then write-region writes or appends that string, rather than text from the buffer. end is ignored in this case.

If append is non-nil, then the specified text is appended to the existing file contents (if any). Starting in Emacs 21, if append is an integer, then write-region seeks to that byte offset from the start of the file and writes the data from there.

If mustbenew is non-nil, then write-region asks for confirmation if filename names an existing file. Starting in Emacs 21, if mustbenew is the symbol excl, then write-region does not ask for confirmation, but instead it signals an error file-already-exists if the file already exists.

The test for an existing file, when mustbenew is excl, uses a special system feature. At least for files on a local disk, there is no chance that some other program could create a file of the same name before Emacs does, without Emacs's noticing.

If visit is t, then Emacs establishes an association between the buffer and the file: the buffer is then visiting that file. It also sets the last file modification time for the current buffer to filename's modtime, and marks the buffer as not modified. This feature is used by save-buffer, but you probably should not use it yourself.

If visit is a string, it specifies the file name to visit. This way, you can write the data to one file (filename) while recording the buffer as visiting another file (visit). The argument visit is used in the echo area message and also for file locking; visit is stored in buffer-file-name. This feature is used to implement file-precious-flag; don't use it yourself unless you really know what you're doing.

The optional argument lockname, if non-nil, specifies the file name to use for purposes of locking and unlocking, overriding filename and visit for that purpose.

The function write-region converts the data which it writes to the appropriate file formats specified by buffer-file-format. See section 25.12 File Format Conversion. It also calls the functions in the list write-region-annotate-functions; see 32.19.7 Saving Text Properties in Files.

Normally, write-region displays the message `Wrote filename' in the echo area. If visit is neither t nor nil nor a string, then this message is inhibited. This feature is useful for programs that use files for internal purposes, files that the user does not need to know about.

Macro: with-temp-file file body...
The with-temp-file macro evaluates the body forms with a temporary buffer as the current buffer; then, at the end, it writes the buffer contents into file file. It kills the temporary buffer when finished, restoring the buffer that was current before the with-temp-file form. Then it returns the value of the last form in body.

The current buffer is restored even in case of an abnormal exit via throw or error (see section 10.5 Nonlocal Exits).

See also with-temp-buffer in 27.2 The Current Buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.5 File Locks

When two users edit the same file at the same time, they are likely to interfere with each other. Emacs tries to prevent this situation from arising by recording a file lock when a file is being modified. Emacs can then detect the first attempt to modify a buffer visiting a file that is locked by another Emacs job, and ask the user what to do. The file lock is really a file, a symbolic link with a special name, stored in the same directory as the file you are editing.

When you access files using NFS, there may be a small probability that you and another user will both lock the same file "simultaneously". If this happens, it is possible for the two users to make changes simultaneously, but Emacs will still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed on disk catches some cases of simultaneous editing; see 27.6 Comparison of Modification Time.

Function: file-locked-p filename
This function returns nil if the file filename is not locked. It returns t if it is locked by this Emacs process, and it returns the name of the user who has locked it if it is locked by some other job.
(file-locked-p "foo")
     => nil
Function: lock-buffer &optional filename
This function locks the file filename, if the current buffer is modified. The argument filename defaults to the current buffer's visited file. Nothing is done if the current buffer is not visiting a file, or is not modified.

Function: unlock-buffer
This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also does nothing if the current buffer is not visiting a file.

File locking is not supported on some systems. On systems that do not support it, the functions lock-buffer, unlock-buffer and file-locked-p do nothing and return nil.

Function: ask-user-about-lock file other-user
This function is called when the user tries to modify file, but it is locked by another user named other-user. The default definition of this function asks the user to say what to do. The value this function returns determines what Emacs does next:

A value of t says to grab the lock on the file. Then this user may edit the file and other-user loses the lock.

A value of nil says to ignore the lock and let this user edit the file anyway.

This function may instead signal a file-locked error, in which case the change that the user was about to make does not take place.
The error message for this error looks like this:
error--> File is locked: file other-user
where file is the name of the file and other-user is the name of the user who has locked the file.

If you wish, you can replace the ask-user-about-lock function with your own version that makes the decision in another way. The code for its usual definition is in `userlock.el'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.6 Information about Files

The functions described in this section all operate on strings that designate file names. All the functions have names that begin with the word `file'. These functions all return information about actual files or directories, so their arguments must all exist as actual files or directories unless otherwise noted.

25.6.1 Testing Accessibility

Is a given file readable? Writable?

25.6.2 Distinguishing Kinds of Files

Is it a directory? A symbolic link?

25.6.3 Truenames

Eliminating symbolic links from a file name.

25.6.4 Other Information about Files

How large is it? Any other names? Etc.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.6.1 Testing Accessibility

These functions test for permission to access a file in specific ways.

Function: file-exists-p filename
This function returns t if a file named filename appears to exist. This does not mean you can necessarily read the file, only that you can find out its attributes. (On Unix and GNU/Linux, this is true if the file exists and you have execute permission on the containing directories, regardless of the protection of the file itself.)

If the file does not exist, or if fascist access control policies prevent you from finding the attributes of the file, this function returns nil.

Function: file-readable-p filename
This function returns t if a file named filename exists and you can read it. It returns nil otherwise.
(file-readable-p "files.texi")
     => t
(file-exists-p "/usr/spool/mqueue")
     => t
(file-readable-p "/usr/spool/mqueue")
     => nil
Function: file-executable-p filename
This function returns t if a file named filename exists and you can execute it. It returns nil otherwise. On Unix and GNU/Linux, if the file is a directory, execute permission means you can check the existence and attributes of files inside the directory, and open those files if their modes permit.

Function: file-writable-p filename
This function returns t if the file filename can be written or created by you, and nil otherwise. A file is writable if the file exists and you can write it. It is creatable if it does not exist, but the specified directory does exist and you can write in that directory.

In the third example below, `foo' is not writable because the parent directory does not exist, even though the user could create such a directory.
(file-writable-p "~/foo")
     => t
(file-writable-p "/foo")
     => nil
(file-writable-p "~/no-such-dir/foo")
     => nil
Function: file-accessible-directory-p dirname
This function returns t if you have permission to open existing files in the directory whose name as a file is dirname; otherwise (or if there is no such directory), it returns nil. The value of dirname may be either a directory name or the file name of a file which is a directory.

Example: after the following,
(file-accessible-directory-p "/foo")
     => nil
we can deduce that any attempt to read a file in `/foo/' will give an error.

Function: access-file filename string
This function opens file filename for reading, then closes it and returns nil. However, if the open fails, it signals an error using string as the error message text.

Function: file-ownership-preserved-p filename
This function returns t if deleting the file filename and then creating it anew would keep the file's owner unchanged.

Function: file-newer-than-file-p filename1 filename2
This function returns t if the file filename1 is newer than file filename2. If filename1 does not exist, it returns nil. If filename2 does not exist, it returns t.

In the following example, assume that the file `aug-19' was written on the 19th, `aug-20' was written on the 20th, and the file `no-file' doesn't exist at all.
(file-newer-than-file-p "aug-19" "aug-20")
     => nil
(file-newer-than-file-p "aug-20" "aug-19")
     => t
(file-newer-than-file-p "aug-19" "no-file")
     => t
(file-newer-than-file-p "no-file" "aug-19")
     => nil
You can use file-attributes to get a file's last modification time as a list of two numbers. See section 25.6.4 Other Information about Files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.6.2 Distinguishing Kinds of Files

This section describes how to distinguish various kinds of files, such as directories, symbolic links, and ordinary files.

Function: file-symlink-p filename
If the file filename is a symbolic link, the file-symlink-p function returns the file name to which it is linked. This may be the name of a text file, a directory, or even another symbolic link, or it may be a nonexistent file name.

If the file filename is not a symbolic link (or there is no such file), file-symlink-p returns nil.
(file-symlink-p "foo")
     => nil
(file-symlink-p "sym-link")
     => "foo"
(file-symlink-p "sym-link2")
     => "sym-link"
(file-symlink-p "/bin")
     => "/pub/bin"
Function: file-directory-p filename
This function returns t if filename is the name of an existing directory, nil otherwise.
(file-directory-p "~rms")
     => t
(file-directory-p "~rms/lewis/files.texi")
     => nil
(file-directory-p "~rms/lewis/no-such-file")
     => nil
(file-directory-p "$HOME")
     => nil
(file-directory-p
 (substitute-in-file-name "$HOME"))
     => t
Function: file-regular-p filename
This function returns t if the file filename exists and is a regular file (not a directory, named pipe, terminal, or other I/O device).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.6.3 Truenames

The truename of a file is the name that you get by following symbolic links at all levels until none remain, then simplifying away `.' and `..' appearing as name components. This results in a sort of canonical name for the file. A file does not always have a unique truename; the number of distinct truenames a file has is equal to the number of hard links to the file. However, truenames are useful because they eliminate symbolic links as a cause of name variation.

Function: file-truename filename
The function file-truename returns the truename of the file filename. The argument must be an absolute file name.

Function: file-chase-links filename
This function follows symbolic links, starting with filename, until it finds a file name which is not the name of a symbolic link. Then it returns that file name.

To illustrate the difference between file-chase-links and file-truename, suppose that `/usr/foo' is a symbolic link to the directory `/home/foo', and `/home/foo/hello' is an ordinary file (or at least, not a symbolic link) or nonexistent. Then we would have:
(file-chase-links "/usr/foo/hello")
     ;; This does not follow the links in the parent directories.
     => "/usr/foo/hello"
(file-truename "/usr/foo/hello")
     ;; Assuming that `/home' is not a symbolic link.
     => "/home/foo/hello"
See section 27.4 Buffer File Name, for related information.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.6.4 Other Information about Files

This section describes the functions for getting detailed information about a file, other than its contents. This information includes the mode bits that control access permission, the owner and group numbers, the number of names, the inode number, the size, and the times of access and modification.

Function: file-modes filename
This function returns the mode bits of filename, as an integer. The mode bits are also called the file permissions, and they specify access control in the usual Unix fashion. If the low-order bit is 1, then the file is executable by all users, if the second-lowest-order bit is 1, then the file is writable by all users, etc.

The highest value returnable is 4095 (7777 octal), meaning that everyone has read, write, and execute permission, that the SUID bit is set for both others and group, and that the sticky bit is set.
(file-modes "~/junk/diffs")
     => 492               ; Decimal integer.
(format "%o" 492)
     => "754"             ; Convert to octal.

(set-file-modes "~/junk/diffs" 438)
     => nil

(format "%o" 438)
     => "666"             ; Convert to octal.

% ls -l diffs
  -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
Function: file-nlinks filename
This functions returns the number of names (i.e., hard links) that file filename has. If the file does not exist, then this function returns nil. Note that symbolic links have no effect on this function, because they are not considered to be names of the files they link to.
% ls -l foo*
-rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
-rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1

(file-nlinks "foo")
     => 2
(file-nlinks "doesnt-exist")
     => nil
Function: file-attributes filename
This function returns a list of attributes of file filename. If the specified file cannot be opened, it returns nil.

The elements of the list, in order, are:

t for a directory, a string for a symbolic link (the name linked to), or nil for a text file.

The number of names the file has. Alternate names, also known as hard links, can be created by using the add-name-to-file function (see section 25.7 Changing File Names and Attributes).

The file's UID.

The file's GID.

The time of last access, as a list of two integers. The first integer has the high-order 16 bits of time, the second has the low 16 bits. (This is similar to the value of current-time; see 40.5 Time of Day.)

The time of last modification as a list of two integers (as above).

The time of last status change as a list of two integers (as above).

The size of the file in bytes. If the size is too large to fit in a Lisp integer, this is a floating point number.

The file's modes, as a string of ten letters or dashes, as in `ls -l'.

t if the file's GID would change if file were deleted and recreated; nil otherwise.

The file's inode number. If possible, this is an integer. If the inode number is too large to be represented as an integer in Emacs Lisp, then the value has the form (high . low), where low holds the low 16 bits.

The file system number of the file system that the file is in. Depending on the magnitude of the value, this can be either an integer or a cons cell, in the same manner as the inode number. This element and the file's inode number together give enough information to distinguish any two files on the system--no two files can have the same values for both of these numbers.

For example, here are the file attributes for `files.texi':
(file-attributes "files.texi")
     =>  (nil 1 2235 75
          (8489 20284)
          (8489 20284)
          (8489 20285)
          14906 "-rw-rw-rw-"
          nil 129500 -32252)
and here is how the result is interpreted:

nil
is neither a directory nor a symbolic link.

1
has only one name (the name `files.texi' in the current default directory).

2235
is owned by the user with UID 2235.

75
is in the group with GID 75.

(8489 20284)
was last accessed on Aug 19 00:09.

(8489 20284)
was last modified on Aug 19 00:09.

(8489 20285)
last had its inode changed on Aug 19 00:09.

14906
is 14906 bytes long. (It may not contain 14906 characters, though, if some of the bytes belong to multibyte sequences.)

"-rw-rw-rw-"
has a mode of read and write access for the owner, group, and world.

nil
would retain the same GID if it were recreated.

129500
has an inode number of 129500.
-32252
is on file system number -32252.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.7 Changing File Names and Attributes

The functions in this section rename, copy, delete, link, and set the modes of files.

In the functions that have an argument newname, if a file by the name of newname already exists, the actions taken depend on the value of the argument ok-if-already-exists:

Signal a file-already-exists error if ok-if-already-exists is nil.

Request confirmation if ok-if-already-exists is a number.

Replace the old file without confirmation if ok-if-already-exists is any other value.

Function: add-name-to-file oldname newname &optional ok-if-already-exists
This function gives the file named oldname the additional name newname. This means that newname becomes a new "hard link" to oldname.

In the first part of the following example, we list two files, `foo' and `foo3'.
% ls -li fo*
81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
Now we create a hard link, by calling add-name-to-file, then list the files again. This shows two names for one file, `foo' and `foo2'.
(add-name-to-file "foo" "foo2")
     => nil

% ls -li fo*
81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
Finally, we evaluate the following:
(add-name-to-file "foo" "foo3" t)
and list the files again. Now there are three names for one file: `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
(add-name-to-file "foo1" "foo3")
     => nil

% ls -li fo*
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
This function is meaningless on operating systems where multiple names for one file are not allowed. Some systems implement multiple names by copying the file instead.

See also file-nlinks in 25.6.4 Other Information about Files.

Command: rename-file filename newname &optional ok-if-already-exists
This command renames the file filename as newname.

If filename has additional names aside from filename, it continues to have those names. In fact, adding the name newname with add-name-to-file and then deleting filename has the same effect as renaming, aside from momentary intermediate states.

In an interactive call, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

Command: copy-file oldname newname &optional ok-if-exists time
This command copies the file oldname to newname. An error is signaled if oldname does not exist.

If time is non-nil, then this function gives the new file the same last-modified time that the old one has. (This works on only some operating systems.) If setting the time gets an error, copy-file signals a file-date-error error.

In an interactive call, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

Command: delete-file filename
This command deletes the file filename, like the shell command `rm filename'. If the file has multiple names, it continues to exist under the other names.

A suitable kind of file-error error is signaled if the file does not exist, or is not deletable. (On Unix and GNU/Linux, a file is deletable if its directory is writable.)

See also delete-directory in 25.10 Creating and Deleting Directories.

Command: make-symbolic-link filename newname &optional ok-if-exists
This command makes a symbolic link to filename, named newname. This is like the shell command `ln -s filename newname'.

In an interactive call, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

This function is not available on systems that don't support symbolic links.

Function: define-logical-name varname string
This function defines the logical name name to have the value string. It is available only on VMS.

Function: set-file-modes filename mode
This function sets mode bits of filename to mode (which must be an integer). Only the low 12 bits of mode are used.

Function: set-default-file-modes mode
This function sets the default file protection for new files created by Emacs and its subprocesses. Every file created with Emacs initially has this protection, or a subset of it (write-region will not give a file execute permission even if the default file protection allows execute permission). On Unix and GNU/Linux, the default protection is the bitwise complement of the "umask" value.

The argument mode must be an integer. On most systems, only the low 9 bits of mode are meaningful. You can use the Lisp construct for octal character codes to enter mode; for example,
(set-default-file-modes ?\644)
Saving a modified version of an existing file does not count as creating the file; it preserves the existing file's mode, whatever that is. So the default file protection has no effect.

Function: default-file-modes
This function returns the current default protection value.

On MS-DOS, there is no such thing as an "executable" file mode bit. So Emacs considers a file executable if its name ends in one of the standard executable extensions, such as `.com', `.bat', `.exe', and some others. Files that begin with the Unix-standard `#!' signature, such as shell and Perl scripts, are also considered as executable files. This is reflected in the values returned by file-modes and file-attributes. Directories are also reported with executable bit set, for compatibility with Unix.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.8 File Names

Files are generally referred to by their names, in Emacs as elsewhere. File names in Emacs are represented as strings. The functions that operate on a file all expect a file name argument.

In addition to operating on files themselves, Emacs Lisp programs often need to operate on file names; i.e., to take them apart and to use part of a name to construct related file names. This section describes how to manipulate file names.

The functions in this section do not actually access files, so they can operate on file names that do not refer to an existing file or directory.

On MS-DOS and MS-Windows, these functions (like the function that actually operate on files) accept MS-DOS or MS-Windows file-name syntax, where backslashes separate the components, as well as Unix syntax; but they always return Unix syntax. On VMS, these functions (and the ones that operate on files) understand both VMS file-name syntax and Unix syntax. This enables Lisp programs to specify file names in Unix syntax and work properly on all systems without change.

25.8.1 File Name Components

The directory part of a file name, and the rest.

25.8.2 Directory Names

A directory's name as a directory is different from its name as a file.

25.8.3 Absolute and Relative File Names

Some file names are relative to a current directory.

25.8.4 Functions that Expand Filenames

Converting relative file names to absolute ones.

25.8.5 Generating Unique File Names

Generating names for temporary files.

25.8.6 File Name Completion

Finding the completions for a given file name.

25.8.7 Standard File Names

If your package uses a fixed file name, how to handle various operating systems simply.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.8.1 File Name Components

The operating system groups files into directories. To specify a file, you must specify the directory and the file's name within that directory. Therefore, Emacs considers a file name as having two main parts: the directory name part, and the nondirectory part (or file name within the directory). Either part may be empty. Concatenating these two parts reproduces the original file name.

On most systems, the directory part is everything up to and including the last slash (backslash is also allowed in input on MS-DOS or MS-Windows); the nondirectory part is the rest. The rules in VMS syntax are complicated.

For some purposes, the nondirectory part is further subdivided into the name proper and the version number. On most systems, only backup files have version numbers in their names. On VMS, every file has a version number, but most of the time the file name actually used in Emacs omits the version number, so that version numbers in Emacs are found mostly in directory lists.

Function: file-name-directory filename
This function returns the directory part of filename (or nil if filename does not include a directory part). On most systems, the function returns a string ending in a slash. On VMS, it returns a string ending in one of the three characters `:', `]', or `>'.
(file-name-directory "lewis/foo")  ; Unix example
     => "lewis/"
(file-name-directory "foo")        ; Unix example
     => nil
(file-name-directory "[X]FOO.TMP") ; VMS example
     => "[X]"
Function: file-name-nondirectory filename
This function returns the nondirectory part of filename.
(file-name-nondirectory "lewis/foo")
     => "foo"
(file-name-nondirectory "foo")
     => "foo"
;; The following example is accurate only on VMS.
(file-name-nondirectory "[X]FOO.TMP")
     => "FOO.TMP"
Function: file-name-sans-versions filename &optional keep-backup-version
This function returns filename with any file version numbers, backup version numbers, or trailing tildes discarded.

If keep-backup-version is non-nil, then true file version numbers understood as such by the file system are discarded from the return value, but backup version numbers are kept.
(file-name-sans-versions "~rms/foo.~1~")
     => "~rms/foo"
(file-name-sans-versions "~rms/foo~")
     => "~rms/foo"
(file-name-sans-versions "~rms/foo")
     => "~rms/foo"
;; The following example applies to VMS only.
(file-name-sans-versions "foo;23")
     => "foo"
Function: file-name-sans-extension filename
This function returns filename minus its "extension," if any. The extension, in a file name, is the part that starts with the last `.' in the last name component. For example,
(file-name-sans-extension "foo.lose.c")
     => "foo.lose"
(file-name-sans-extension "big.hack/foo")
     => "big.hack/foo"
Function: file-name-extension filename &optional period
This function returns filename's final "extension," if any, after applying file-name-sans-versions to remove any version/backup part. If period is non-nil, then the returned value includes the period that delimits the extension, and if filename has no extension, the value is "".

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.8.2 Directory Names

A directory name is the name of a directory. A directory is a kind of file, and it has a file name, which is related to the directory name but not identical to it. (This is not quite the same as the usual Unix terminology.) These two different names for the same entity are related by a syntactic transformation. On most systems, this is simple: a directory name ends in a slash (or backslash), whereas the directory's name as a file lacks that slash. On VMS, the relationship is more complicated.

The difference between a directory name and its name as a file is subtle but crucial. When an Emacs variable or function argument is described as being a directory name, a file name of a directory is not acceptable.

The following two functions convert between directory names and file names. They do nothing special with environment variable substitutions such as `$HOME', and the constructs `~', and `..'.

Function: file-name-as-directory filename
This function returns a string representing filename in a form that the operating system will interpret as the name of a directory. On most systems, this means appending a slash to the string (if it does not already end in one). On VMS, the function converts a string of the form `[X]Y.DIR.1' to the form `[X.Y]'.
(file-name-as-directory "~rms/lewis")
     => "~rms/lewis/"
Function: directory-file-name dirname
This function returns a string representing dirname in a form that the operating system will interpret as the name of a file. On most systems, this means removing the final slash (or backslash) from the string. On VMS, the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
(directory-file-name "~lewis/")
     => "~lewis"
Directory name abbreviations are useful for directories that are normally accessed through symbolic links. Sometimes the users recognize primarily the link's name as "the name" of the directory, and find it annoying to see the directory's "real" name. If you define the link name as an abbreviation for the "real" name, Emacs shows users the abbreviation instead.

Variable: directory-abbrev-alist
The variable directory-abbrev-alist contains an alist of abbreviations to use for file directories. Each element has the form (from . to), and says to replace from with to when it appears in a directory name. The from string is actually a regular expression; it should always start with `^'. The function abbreviate-file-name performs these substitutions.

You can set this variable in `site-init.el' to describe the abbreviations appropriate for your site.

Here's an example, from a system on which file system `/home/fsf' and so on are normally accessed through symbolic links named `/fsf' and so on.
(("^/home/fsf" . "/fsf")
 ("^/home/gp" . "/gp")
 ("^/home/gd" . "/gd"))
To convert a directory name to its abbreviation, use this function:

Function: abbreviate-file-name dirname
This function applies abbreviations from directory-abbrev-alist to its argument, and substitutes `~' for the user's home directory.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.8.3 Absolute and Relative File Names

All the directories in the file system form a tree starting at the root directory. A file name can specify all the directory names starting from the root of the tree; then it is called an absolute file name. Or it can specify the position of the file in the tree relative to a default directory; then it is called a relative file name. On Unix and GNU/Linux, an absolute file name starts with a slash or a tilde (`~'), and a relative one does not. On MS-DOS and MS-Windows, an absolute file name starts with a slash or a backslash, or with a drive specification `x:/', where x is the drive letter. The rules on VMS are complicated.

Function: file-name-absolute-p filename
This function returns t if file filename is an absolute file name, nil otherwise. On VMS, this function understands both Unix syntax and VMS syntax.
(file-name-absolute-p "~rms/foo")
     => t
(file-name-absolute-p "rms/foo")
     => nil
(file-name-absolute-p "/user/rms/foo")
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.8.4 Functions that Expand Filenames

Expansion of a file name means converting a relative file name to an absolute one. Since this is done relative to a default directory, you must specify the default directory name as well as the file name to be expanded. Expansion also simplifies file names by eliminating redundancies such as `./' and `name/../'.

Function: expand-file-name filename &optional directory
This function converts filename to an absolute file name. If directory is supplied, it is the default directory to start with if filename is relative. (The value of directory should itself be an absolute directory name; it may start with `~'.) Otherwise, the current buffer's value of default-directory is used. For example:
(expand-file-name "foo")
     => "/xcssun/users/rms/lewis/foo"
(expand-file-name "../foo")
     => "/xcssun/users/rms/foo"
(expand-file-name "foo" "/usr/spool/")
     => "/usr/spool/foo"
(expand-file-name "$HOME/foo")
     => "/xcssun/users/rms/lewis/$HOME/foo"
Filenames containing `.' or `..' are simplified to their canonical form:
(expand-file-name "bar/../foo")
     => "/xcssun/users/rms/lewis/foo"
Note that expand-file-name does not expand environment variables; only substitute-in-file-name does that.

Function: file-relative-name filename &optional directory
This function does the inverse of expansion--it tries to return a relative name that is equivalent to filename when interpreted relative to directory. If directory is omitted or nil, it defaults to the current buffer's default directory.

On some operating systems, an absolute file name begins with a device name. On such systems, filename has no relative equivalent based on directory if they start with two different device names. In this case, file-relative-name returns filename in absolute form.
(file-relative-name "/foo/bar" "/foo/")
     => "bar"
(file-relative-name "/foo/bar" "/hack/")
     => "../foo/bar"
Variable: default-directory
The value of this buffer-local variable is the default directory for the current buffer. It should be an absolute directory name; it may start with `~'. This variable is buffer-local in every buffer.

expand-file-name uses the default directory when its second argument is nil.

Aside from VMS, the value is always a string ending with a slash.
default-directory
     => "/user/lewis/manual/"
Function: substitute-in-file-name filename
This function replaces environment variables references in filename with the environment variable values. Following standard Unix shell syntax, `$' is the prefix to substitute an environment variable value.

The environment variable name is the series of alphanumeric characters (including underscores) that follow the `$'. If the character following the `$' is a `{', then the variable name is everything up to the matching `}'.

Here we assume that the environment variable HOME, which holds the user's home directory name, has value `/xcssun/users/rms'.
(substitute-in-file-name "$HOME/foo")
     => "/xcssun/users/rms/foo"
After substitution, if a `~' or a `/' appears following a `/', everything before the following `/' is discarded:
(substitute-in-file-name "bar/~/foo")
     => "~/foo"
(substitute-in-file-name "/usr/local/$HOME/foo")
     => "/xcssun/users/rms/foo"
     ;; `/usr/local/' has been discarded.
On VMS, `$' substitution is not done, so this function does nothing on VMS except discard superfluous initial components as shown above.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.8.5 Generating Unique File Names

Some programs need to write temporary files. Here is the usual way to construct a name for such a file, starting in Emacs 21:
(make-temp-file name-of-application)
The job of make-temp-file is to prevent two different users or two different jobs from trying to use the exact same file name.

Function: make-temp-file prefix &optional dir-flag
This function creates a temporary file and returns its name. The name starts with prefix; it also contains a number that is different in each Emacs job. If prefix is a relative file name, it is expanded against temporary-file-directory.
(make-temp-file "foo")
     => "/tmp/foo232J6v"
When make-temp-file returns, the file has been created and is empty. At that point, you should write the intended contents into the file.

If dir-flag is non-nil, make-temp-file creates an empty directory instead of an empty file.

To prevent conflicts among different libraries running in the same Emacs, each Lisp program that uses make-temp-file should have its own prefix. The number added to the end of prefix distinguishes between the same application running in different Emacs jobs. Additional added characters permit a large number of distinct names even in one Emacs job.

The default directory for temporary files is controlled by the variable temporary-file-directory. This variable gives the user a uniform way to specify the directory for all temporary files. Some programs use small-temporary-file-directory instead, if that is non-nil. To use it, you should expand the prefix against the proper directory before calling make-temp-file.

In older Emacs versions where make-temp-file does not exist, you should use make-temp-name instead:
(make-temp-name
 (expand-file-name name-of-application
                   temporary-file-directory))
Function: make-temp-name string
This function generates a string that can be used as a unique file name. The name starts with string, and contains a number that is different in each Emacs job. It is like make-temp-file except that it just constructs a name, and does not create a file. On MS-DOS, the string prefix can be truncated to fit into the 8+3 file-name limits.

Variable: temporary-file-directory
This variable specifies the directory name for creating temporary files. Its value should be a directory name (see section 25.8.2 Directory Names), but it is good for Lisp programs to cope if the value is a directory's file name instead. Using the value as the second argument to expand-file-name is a good way to achieve that.

The default value is determined in a reasonable way for your operating system; it is based on the TMPDIR, TMP and TEMP environment variables, with a fall-back to a system-dependent name if none of these variables is defined.

Even if you do not use make-temp-name to choose the temporary file's name, you should still use this variable to decide which directory to put the file in. However, if you expect the file to be small, you should use small-temporary-file-directory first if that is non-nil.

Variable: small-temporary-file-directory
This variable (new in Emacs 21) specifies the directory name for creating certain temporary files, which are likely to be small.

If you want to write a temporary file which is likely to be small, you should compute the directory like this:
(make-temp-file
  (expand-file-name prefix
                    (or small-temporary-file-directory
                        temporary-file-directory)))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.8.6 File Name Completion

This section describes low-level subroutines for completing a file name. For other completion functions, see 20.5 Completion.

Function: file-name-all-completions partial-filename directory
This function returns a list of all possible completions for a file whose name starts with partial-filename in directory directory. The order of the completions is the order of the files in the directory, which is unpredictable and conveys no useful information.

The argument partial-filename must be a file name containing no directory part and no slash (or backslash on some systems). The current buffer's default directory is prepended to directory, if directory is not absolute.

In the following example, suppose that `~rms/lewis' is the current default directory, and has five files whose names begin with `f': `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
(file-name-all-completions "f" "")
     => ("foo" "file~" "file.c.~2~"
                "file.c.~1~" "file.c")

(file-name-all-completions "fo" "")
     => ("foo")
Function: file-name-completion filename directory
This function completes the file name filename in directory directory. It returns the longest prefix common to all file names in directory directory that start with filename.

If only one match exists and filename matches it exactly, the function returns t. The function returns nil if directory directory contains no name starting with filename.

In the following example, suppose that the current default directory has five files whose names begin with `f': `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
(file-name-completion "fi" "")
     => "file"

(file-name-completion "file.c.~1" "")
     => "file.c.~1~"

(file-name-completion "file.c.~1~" "")
     => t

(file-name-completion "file.c.~3" "")
     => nil
User Option: completion-ignored-extensions
file-name-completion usually ignores file names that end in any string in this list. It does not ignore them when all the possible completions end in one of these suffixes or when a buffer showing all possible completions is displayed.

A typical value might look like this:
completion-ignored-extensions
     => (".o" ".elc" "~" ".dvi")
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.8.7 Standard File Names

Most of the file names used in Lisp programs are entered by the user. But occasionally a Lisp program needs to specify a standard file name for a particular use--typically, to hold customization information about each user. For example, abbrev definitions are stored (by default) in the file `~/.abbrev_defs'; the completion package stores completions in the file `~/.completions'. These are two of the many standard file names used by parts of Emacs for certain purposes.

Various operating systems have their own conventions for valid file names and for which file names to use for user profile data. A Lisp program which reads a file using a standard file name ought to use, on each type of system, a file name suitable for that system. The function convert-standard-filename makes this easy to do.

Function: convert-standard-filename filename
This function alters the file name filename to fit the conventions of the operating system in use, and returns the result as a new string.

The recommended way to specify a standard file name in a Lisp program is to choose a name which fits the conventions of GNU and Unix systems, usually with a nondirectory part that starts with a period, and pass it to convert-standard-filename instead of using it directly. Here is an example from the completion package:
(defvar save-completions-file-name
        (convert-standard-filename "~/.completions")
  "*The file name to save completions to.")
On GNU and Unix systems, and on some other systems as well, convert-standard-filename returns its argument unchanged. On some other systems, it alters the name to fit the system's conventions.

For example, on MS-DOS the alterations made by this function include converting a leading `.' to `_', converting a `_' in the middle of the name to `.' if there is no other `.', inserting a `.' after eight characters if there is none, and truncating to three characters after the `.'. (It makes other changes as well.) Thus, `.abbrev_defs' becomes `_abbrev.def', and `.completions' becomes `_complet.ion'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.9 Contents of Directories

A directory is a kind of file that contains other files entered under various names. Directories are a feature of the file system.

Emacs can list the names of the files in a directory as a Lisp list, or display the names in a buffer using the ls shell command. In the latter case, it can optionally display information about each file, depending on the options passed to the ls command.

Function: directory-files directory &optional full-name match-regexp nosort
This function returns a list of the names of the files in the directory directory. By default, the list is in alphabetical order.

If full-name is non-nil, the function returns the files' absolute file names. Otherwise, it returns the names relative to the specified directory.

If match-regexp is non-nil, this function returns only those file names that contain a match for that regular expression--the other file names are excluded from the list.

If nosort is non-nil, directory-files does not sort the list, so you get the file names in no particular order. Use this if you want the utmost possible speed and don't care what order the files are processed in. If the order of processing is visible to the user, then the user will probably be happier if you do sort the names.
(directory-files "~lewis")
     => ("#foo#" "#foo.el#" "." ".."
         "dired-mods.el" "files.texi"
         "files.texi.~1~")
An error is signaled if directory is not the name of a directory that can be read.

Function: file-name-all-versions file dirname
This function returns a list of all versions of the file named file in directory dirname.

Function: file-expand-wildcards pattern &optional full
This function expands the wildcard pattern pattern, returning a list of file names that match it.

If pattern is written as an absolute file name, the values are absolute also.

If pattern is written as a relative file name, it is interpreted relative to the current default directory. The file names returned are normally also relative to the current default directory. However, if full is non-nil, they are absolute.

Function: insert-directory file switches &optional wildcard full-directory-p
This function inserts (in the current buffer) a directory listing for directory file, formatted with ls according to switches. It leaves point after the inserted text.

The argument file may be either a directory name or a file specification including wildcard characters. If wildcard is non-nil, that means treat file as a file specification with wildcards.

If full-directory-p is non-nil, that means the directory listing is expected to show the full contents of a directory. You should specify t when file is a directory and switches do not contain `-d'. (The `-d' option to ls says to describe a directory itself as a file, rather than showing its contents.)

On most systems, this function works by running a directory listing program whose name is in the variable insert-directory-program. If wildcard is non-nil, it also runs the shell specified by shell-file-name, to expand the wildcards.

MS-DOS and MS-Windows systems usually lack the standard Unix program ls, so this function emulates the standard Unix program ls with Lisp code.

Variable: insert-directory-program
This variable's value is the program to run to generate a directory listing for the function insert-directory. It is ignored on systems which generate the listing with Lisp code.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.10 Creating and Deleting Directories

Most Emacs Lisp file-manipulation functions get errors when used on files that are directories. For example, you cannot delete a directory with delete-file. These special functions exist to create and delete directories.

Function: make-directory dirname &optional parents
This function creates a directory named dirname. If parents is non-nil, that means to create the parent directories first, if they don't already exist.

Function: delete-directory dirname
This function deletes the directory named dirname. The function delete-file does not work for files that are directories; you must use delete-directory for them. If the directory contains any files, delete-directory signals an error.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.11 Making Certain File Names "Magic"

You can implement special handling for certain file names. This is called making those names magic. The principal use for this feature is in implementing remote file names (see section `Remote Files' in The GNU Emacs Manual).

To define a kind of magic file name, you must supply a regular expression to define the class of names (all those that match the regular expression), plus a handler that implements all the primitive Emacs file operations for file names that do match.

The variable file-name-handler-alist holds a list of handlers, together with regular expressions that determine when to apply each handler. Each element has this form:
(regexp . handler)
All the Emacs primitives for file access and file name transformation check the given file name against file-name-handler-alist. If the file name matches regexp, the primitives handle that file by calling handler.

The first argument given to handler is the name of the primitive; the remaining arguments are the arguments that were passed to that primitive. (The first of these arguments is most often the file name itself.) For example, if you do this:
(file-exists-p filename)
and filename has handler handler, then handler is called like this:
(funcall handler 'file-exists-p filename)
When a function takes two or more arguments that must be file names, it checks each of those names for a handler. For example, if you do this:
(expand-file-name filename dirname)
then it checks for a handler for filename and then for a handler for dirname. In either case, the handler is called like this:
(funcall handler 'expand-file-name filename dirname)
The handler then needs to figure out whether to handle filename or dirname.

Here are the operations that a magic file name handler gets to handle:

add-name-to-file, copy-file, delete-directory, delete-file, diff-latest-backup-file, directory-file-name, directory-files, dired-call-process, dired-compress-file, dired-uncache, expand-file-name, file-accessible-directory-p,
file-attributes, file-directory-p, file-executable-p, file-exists-p,
file-local-copy, file-modes, file-name-all-completions,
file-name-as-directory, file-name-completion, file-name-directory, file-name-nondirectory, file-name-sans-versions, file-newer-than-file-p, file-ownership-preserved-p, file-readable-p, file-regular-p, file-symlink-p, file-truename, file-writable-p, find-backup-file-name, get-file-buffer,
insert-directory, insert-file-contents, load, make-directory, make-symbolic-link, rename-file, set-file-modes, set-visited-file-modtime, shell-command,
unhandled-file-name-directory, vc-registered, verify-visited-file-modtime,
write-region.

Handlers for insert-file-contents typically need to clear the buffer's modified flag, with (set-buffer-modified-p nil), if the visit argument is non-nil. This also has the effect of unlocking the buffer if it is locked.

The handler function must handle all of the above operations, and possibly others to be added in the future. It need not implement all these operations itself--when it has nothing special to do for a certain operation, it can reinvoke the primitive, to handle the operation "in the usual way". It should always reinvoke the primitive for an operation it does not recognize. Here's one way to do this:
(defun my-file-handler (operation &rest args)
  ;; First check for the specific operations
  ;; that we have special handling for.
  (cond ((eq operation 'insert-file-contents) ...)
        ((eq operation 'write-region) ...)
        ...
        ;; Handle any operation we don't know about.
        (t (let ((inhibit-file-name-handlers
                  (cons 'my-file-handler
                        (and (eq inhibit-file-name-operation operation)
                             inhibit-file-name-handlers)))
                 (inhibit-file-name-operation operation))
             (apply operation args)))))
When a handler function decides to call the ordinary Emacs primitive for the operation at hand, it needs to prevent the primitive from calling the same handler once again, thus leading to an infinite recursion. The example above shows how to do this, with the variables inhibit-file-name-handlers and inhibit-file-name-operation. Be careful to use them exactly as shown above; the details are crucial for proper behavior in the case of multiple handlers, and for operations that have two file names that may each have handlers.

Variable: inhibit-file-name-handlers
This variable holds a list of handlers whose use is presently inhibited for a certain operation.

Variable: inhibit-file-name-operation
The operation for which certain handlers are presently inhibited.

Function: find-file-name-handler file operation
This function returns the handler function for file name file, or nil if there is none. The argument operation should be the operation to be performed on the file--the value you will pass to the handler as its first argument when you call it. The operation is needed for comparison with inhibit-file-name-operation.

Function: file-local-copy filename
This function copies file filename to an ordinary non-magic file, if it isn't one already.

If filename specifies a magic file name, which programs outside Emacs cannot directly read or write, this copies the contents to an ordinary file and returns that file's name.

If filename is an ordinary file name, not magic, then this function does nothing and returns nil.

Function: unhandled-file-name-directory filename
This function returns the name of a directory that is not magic. It uses the directory part of filename if that is not magic. For a magic file name, it invokes the file name handler, which therefore decides what value to return.

This is useful for running a subprocess; every subprocess must have a non-magic directory to serve as its current directory, and this function is a good way to come up with one.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

25.12 File Format Conversion

The variable format-alist defines a list of file formats, which describe textual representations used in files for the data (text, text-properties, and possibly other information) in an Emacs buffer. Emacs performs format conversion if appropriate when reading and writing files.

Variable: format-alist
This list contains one format definition for each defined file format.

Each format definition is a list of this form:
(name doc-string regexp from-fn to-fn modify mode-fn)
Here is what the elements in a format definition mean:

name
The name of this format.

doc-string
A documentation string for the format.

regexp
A regular expression which is used to recognize files represented in this format.

from-fn
A shell command or function to decode data in this format (to convert file data into the usual Emacs data representation).
A shell command is represented as a string; Emacs runs the command as a filter to perform the conversion.

If from-fn is a function, it is called with two arguments, begin and end, which specify the part of the buffer it should convert. It should convert the text by editing it in place. Since this can change the length of the text, from-fn should return the modified end position.

One responsibility of from-fn is to make sure that the beginning of the file no longer matches regexp. Otherwise it is likely to get called again.

to-fn
A shell command or function to encode data in this format--that is, to convert the usual Emacs data representation into this format.
If to-fn is a string, it is a shell command; Emacs runs the command as a filter to perform the conversion.

If to-fn is a function, it is called with two arguments, begin and end, which specify the part of the buffer it should convert. There are two ways it can do the conversion:

By editing the buffer in place. In this case, to-fn should return the end-position of the range of text, as modified.

By returning a list of annotations. This is a list of elements of the form (position . string), where position is an integer specifying the relative position in the text to be written, and string is the annotation to add there. The list must be sorted in order of position when to-fn returns it.
When write-region actually writes the text from the buffer to the file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer.

modify
A flag, t if the encoding function modifies the buffer, and nil if it works by returning a list of annotations.

mode-fn
A minor-mode function to call after visiting a file converted from this format. The function is called with one argument, the integer 1; that tells a minor-mode function to enable the mode.
The function insert-file-contents automatically recognizes file formats when it reads the specified file. It checks the text of the beginning of the file against the regular expressions of the format definitions, and if it finds a match, it calls the decoding function for that format. Then it checks all the known formats over again. It keeps checking them until none of them is applicable.

Visiting a file, with find-file-noselect or the commands that use it, performs conversion likewise (because it calls insert-file-contents); it also calls the mode function for each format that it decodes. It stores a list of the format names in the buffer-local variable buffer-file-format.

Variable: buffer-file-format
This variable states the format of the visited file. More precisely, this is a list of the file format names that were decoded in the course of visiting the current buffer's file. It is always buffer-local in all buffers.

When write-region writes data into a file, it first calls the encoding functions for the formats listed in buffer-file-format, in the order of appearance in the list.

Command: format-write-file file format
This command writes the current buffer contents into the file file in format format, and makes that format the default for future saves of the buffer. The argument format is a list of format names.

Command: format-find-file file format
This command finds the file file, converting it according to format format. It also makes format the default if the buffer is saved later.

The argument format is a list of format names. If format is nil, no conversion takes place. Interactively, typing just RET for format specifies nil.

Command: format-insert-file file format &optional beg end
This command inserts the contents of file file, converting it according to format format. If beg and end are non-nil, they specify which part of the file to read, as in insert-file-contents (see section 25.3 Reading from Files).

The return value is like what insert-file-contents returns: a list of the absolute file name and the length of the data inserted (after conversion).

The argument format is a list of format names. If format is nil, no conversion takes place. Interactively, typing just RET for format specifies nil.

Variable: auto-save-file-format
This variable specifies the format to use for auto-saving. Its value is a list of format names, just like the value of buffer-file-format; however, it is used instead of buffer-file-format for writing auto-save files. This variable is always buffer-local in all buffers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

26. Backups and Auto-Saving

Backup files and auto-save files are two methods by which Emacs tries to protect the user from the consequences of crashes or of the user's own errors. Auto-saving preserves the text from earlier in the current editing session; backup files preserve file contents prior to the current session.

26.1 Backup Files

How backup files are made; how their names are chosen.

26.2 Auto-Saving

How auto-save files are made; how their names are chosen.

26.3 Reverting

revert-buffer, and how to customize what it does.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

26.1 Backup Files

A backup file is a copy of the old contents of a file you are editing. Emacs makes a backup file the first time you save a buffer into its visited file. Normally, this means that the backup file contains the contents of the file as it was before the current editing session. The contents of the backup file normally remain unchanged once it exists.

Backups are usually made by renaming the visited file to a new name. Optionally, you can specify that backup files should be made by copying the visited file. This choice makes a difference for files with multiple names; it also can affect whether the edited file remains owned by the original owner or becomes owned by the user editing it.

By default, Emacs makes a single backup file for each file edited. You can alternatively request numbered backups; then each new backup file gets a new name. You can delete old numbered backups when you don't want them any more, or Emacs can delete them automatically.

26.1.1 Making Backup Files

How Emacs makes backup files, and when.

26.1.2 Backup by Renaming or by Copying?

Two alternatives: renaming the old file or copying it.

26.1.3 Making and Deleting Numbered Backup Files

Keeping multiple backups for each source file.

26.1.4 Naming Backup Files

How backup file names are computed; customization.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

26.1.1 Making Backup Files

Function: backup-buffer
This function makes a backup of the file visited by the current buffer, if appropriate. It is called by save-buffer before saving the buffer the first time.

Variable: buffer-backed-up
This buffer-local variable indicates whether this buffer's file has been backed up on account of this buffer. If it is non-nil, then the backup file has been written. Otherwise, the file should be backed up when it is next saved (if backups are enabled). This is a permanent local; kill-all-local-variables does not alter it.

User Option: make-backup-files
This variable determines whether or not to make backup files. If it is non-nil, then Emacs creates a backup of each file when it is saved for the first time--provided that backup-inhibited is nil (see below).

The following example shows how to change the make-backup-files variable only in the Rmail buffers and not elsewhere. Setting it nil stops Emacs from making backups of these files, which may save disk space. (You would put this code in your init file.)
(add-hook 'rmail-mode-hook
          (function (lambda ()
                      (make-local-variable
                       'make-backup-files)
                      (setq make-backup-files nil))))
Variable: backup-enable-predicate
This variable's value is a function to be called on certain occasions to decide whether a file should have backup files. The function receives one argument, a file name to consider. If the function returns nil, backups are disabled for that file. Otherwise, the other variables in this section say whether and how to make backups.

The default value is normal-backup-enable-predicate, which checks for files in temporary-file-directory and small-temporary-file-directory.

Variable: backup-inhibited
If this variable is non-nil, backups are inhibited. It records the result of testing backup-enable-predicate on the visited file name. It can also coherently be used by other mechanisms that inhibit backups based on which file is visited. For example, VC sets this variable non-nil to prevent making backups for files managed with a version control system.

This is a permanent local, so that changing the major mode does not lose its value. Major modes should not set this variable--they should set make-backup-files instead.

Variable: backup-directory-alist
This variable's value is an alist of filename patterns and backup directory names. Each element looks like
(regexp . directory)
Backups of files with names matching regexp will be made in directory. directory may be relative or absolute. If it is absolute, so that all matching files are backed up into the same directory, the file names in this directory will be the full name of the file backed up with all directory separators changed to `!' to prevent clashes. This will not work correctly if your filesystem truncates the resulting name.

For the common case of all backups going into one directory, the alist should contain a single element pairing `"."' with the appropriate directory name.

If this variable is nil, or it fails to match a filename, the backup is made in the original file's directory.

On MS-DOS filesystems without long names this variable is always ignored.

Variable: make-backup-file-name-function
This variable's value is a function to use for making backups instead of the default make-backup-file-name. A value of nil gives the default make-backup-file-name behaviour.

This could be buffer-local to do something special for specific files. If you define it, you may need to change backup-file-name-p and file-name-sans-versions too.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

26.1.2 Backup by Renaming or by Copying?

There are two ways that Emacs can make a backup file:

Emacs can rename the original file so that it becomes a backup file, and then write the buffer being saved into a new file. After this procedure, any other names (i.e., hard links) of the original file now refer to the backup file. The new file is owned by the user doing the editing, and its group is the default for new files written by the user in that directory.

Emacs can copy the original file into a backup file, and then overwrite the original file with new contents. After this procedure, any other names (i.e., hard links) of the original file continue to refer to the current (updated) version of the file. The file's owner and group will be unchanged.

The first method, renaming, is the default.

The variable backup-by-copying, if non-nil, says to use the second method, which is to copy the original file and overwrite it with the new buffer contents. The variable file-precious-flag, if non-nil, also has this effect (as a sideline of its main significance). See section 25.2 Saving Buffers.

Variable: backup-by-copying
If this variable is non-nil, Emacs always makes backup files by copying.

The following two variables, when non-nil, cause the second method to be used in certain special cases. They have no effect on the treatment of files that don't fall into the special cases.

Variable: backup-by-copying-when-linked
If this variable is non-nil, Emacs makes backups by copying for files with multiple names (hard links).

This variable is significant only if backup-by-copying is nil, since copying is always used when that variable is non-nil.

Variable: backup-by-copying-when-mismatch
If this variable is non-nil, Emacs makes backups by copying in cases where renaming would change either the owner or the group of the file.

The value has no effect when renaming would not alter the owner or group of the file; that is, for files which are owned by the user and whose group matches the default for a new file created there by the user.

This variable is significant only if backup-by-copying is nil, since copying is always used when that variable is non-nil.

Variable: backup-by-copying-when-privileged-mismatch
This variable, if non-nil, specifies the same behavior as backup-by-copying-when-mismatch, but only for certain user-id values: namely, those less than or equal to a certain number. You set this variable to that number.

Thus, if you set backup-by-copying-when-privileged-mismatch to 0, backup by copying is done for the superuser only, when necessary to prevent a change in the owner of the file.

The default is 200.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

26.1.3 Making and Deleting Numbered Backup Files

If a file's name is `foo', the names of its numbered backup versions are `foo.~v~', for various integers v, like this: `foo.~1~', `foo.~2~', `foo.~3~', ..., `foo.~259~', and so on.

User Option: version-control
This variable controls whether to make a single non-numbered backup file or multiple numbered backups.

nil
Make numbered backups if the visited file already has numbered backups; otherwise, do not.

never
Do not make numbered backups.

anything else
Make numbered backups.
The use of numbered backups ultimately leads to a large number of backup versions, which must then be deleted. Emacs can do this automatically or it can ask the user whether to delete them.

User Option: kept-new-versions
The value of this variable is the number of newest versions to keep when a new numbered backup is made. The newly made backup is included in the count. The default value is 2.

User Option: kept-old-versions
The value of this variable is the number of oldest versions to keep when a new numbered backup is made. The default value is 2.

If there are backups numbered 1, 2, 3, 5, and 7, and both of these variables have the value 2, then the backups numbered 1 and 2 are kept as old versions and those numbered 5 and 7 are kept as new versions; backup version 3 is excess. The function find-backup-file-name (see section 26.1.4 Naming Backup Files) is responsible for determining which backup versions to delete, but does not delete them itself.

User Option: delete-old-versions
If this variable is t, then saving a file deletes excess backup versions silently. If it is nil, that means to ask for confirmation before deleting excess backups. Otherwise, they are not deleted at all.

User Option: dired-kept-versions
This variable specifies how many of the newest backup versions to keep in the Dired command . (dired-clean-directory). That's the same thing kept-new-versions specifies when you make a new backup file. The default value is 2.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

26.1.4 Naming Backup Files

The functions in this section are documented mainly because you can customize the naming conventions for backup files by redefining them. If you change one, you probably need to change the rest.

Function: backup-file-name-p filename
This function returns a non-nil value if filename is a possible name for a backup file. A file with the name filename need not exist; the function just checks the name.
(backup-file-name-p "foo")
     => nil
(backup-file-name-p "foo~")
     => 3
The standard definition of this function is as follows:
(defun backup-file-name-p (file)
  "Return non-nil if FILE is a backup file \
name (numeric or not)..."
  (string-match "~\\'" file))
Thus, the function returns a non-nil value if the file name ends with a `~'. (We use a backslash to split the documentation string's first line into two lines in the text, but produce just one line in the string itself.)

This simple expression is placed in a separate function to make it easy to redefine for customization.

Function: make-backup-file-name filename
This function returns a string that is the name to use for a non-numbered backup file for file filename. On Unix, this is just filename with a tilde appended.

The standard definition of this function, on most operating systems, is as follows:
(defun make-backup-file-name (file)
  "Create the non-numeric backup file name for FILE..."
  (concat file "~"))
You can change the backup-file naming convention by redefining this function. The following example redefines make-backup-file-name to prepend a `.' in addition to appending a tilde:
(defun make-backup-file-name (filename)
  (expand-file-name
    (concat "." (file-name-nondirectory filename) "~")
    (file-name-directory filename)))

(make-backup-file-name "backups.texi")
     => ".backups.texi~"
Some parts of Emacs, including some Dired commands, assume that backup file names end with `~'. If you do not follow that convention, it will not cause serious problems, but these commands may give less-than-desirable results.

Function: find-backup-file-name filename
This function computes the file name for a new backup file for filename. It may also propose certain existing backup files for deletion. find-backup-file-name returns a list whose CAR is the name for the new backup file and whose CDR is a list of backup files whose deletion is proposed.

Two variables, kept-old-versions and kept-new-versions, determine which backup versions should be kept. This function keeps those versions by excluding them from the CDR of the value. See section 26.1.3 Making and Deleting Numbered Backup Files.

In this example, the value says that `~rms/foo.~5~' is the name to use for the new backup file, and `~rms/foo.~3~' is an "excess" version that the caller should consider deleting now.
(find-backup-file-name "~rms/foo")
     => ("~rms/foo.~5~" "~rms/foo.~3~")
Function: file-newest-backup filename
This function returns the name of the most recent backup file for filename, or nil if that file has no backup files.

Some file comparison commands use this function so that they can automatically compare a file with its most recent backup.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

26.2 Auto-Saving

Emacs periodically saves all files that you are visiting; this is called auto-saving. Auto-saving prevents you from losing more than a limited amount of work if the system crashes. By default, auto-saves happen every 300 keystrokes, or after around 30 seconds of idle time. See section `Auto-Saving: Protection Against Disasters' in The GNU Emacs Manual, for information on auto-save for users. Here we describe the functions used to implement auto-saving and the variables that control them.

Variable: buffer-auto-save-file-name
This buffer-local variable is the name of the file used for auto-saving the current buffer. It is nil if the buffer should not be auto-saved.
buffer-auto-save-file-name
     => "/xcssun/users/rms/lewis/#backups.texi#"
Command: auto-save-mode arg
When used interactively without an argument, this command is a toggle switch: it turns on auto-saving of the current buffer if it is off, and vice versa. With an argument arg, the command turns auto-saving on if the value of arg is t, a nonempty list, or a positive integer. Otherwise, it turns auto-saving off.

Function: auto-save-file-name-p filename
This function returns a non-nil value if filename is a string that could be the name of an auto-save file. It assumes the usual naming convention for auto-save files: a name that begins and ends with hash marks (`#') is a possible auto-save file name. The argument filename should not contain a directory part.
(make-auto-save-file-name)
     => "/xcssun/users/rms/lewis/#backups.texi#"
(auto-save-file-name-p "#backups.texi#")
     => 0
(auto-save-file-name-p "backups.texi")
     => nil
The standard definition of this function is as follows:
(defun auto-save-file-name-p (filename)
  "Return non-nil if FILENAME can be yielded by..."
  (string-match "^#.*#$" filename))
This function exists so that you can customize it if you wish to change the naming convention for auto-save files. If you redefine it, be sure to redefine the function make-auto-save-file-name correspondingly.

Function: make-auto-save-file-name
This function returns the file name to use for auto-saving the current buffer. This is just the file name with hash marks (`#') prepended and appended to it. This function does not look at the variable auto-save-visited-file-name (described below); callers of this function should check that variable first.
(make-auto-save-file-name)
     => "/xcssun/users/rms/lewis/#backups.texi#"
The standard definition of this function is as follows:
(defun make-auto-save-file-name ()
  "Return file name to use for auto-saves \
of current buffer.."
  (if buffer-file-name
      (concat
       (file-name-directory buffer-file-name)
       "#"
       (file-name-nondirectory buffer-file-name)
       "#")
    (expand-file-name
     (concat "#%" (buffer-name) "#"))))
This exists as a separate function so that you can redefine it to customize the naming convention for auto-save files. Be sure to change auto-save-file-name-p in a corresponding way.

Variable: auto-save-visited-file-name
If this variable is non-nil, Emacs auto-saves buffers in the files they are visiting. That is, the auto-save is done in the same file that you are editing. Normally, this variable is nil, so auto-save files have distinct names that are created by make-auto-save-file-name.

When you change the value of this variable, the new value does not take effect in an existing buffer until the next time auto-save mode is reenabled in it. If auto-save mode is already enabled, auto-saves continue to go in the same file name until auto-save-mode is called again.

Function: recent-auto-save-p
This function returns t if the current buffer has been auto-saved since the last time it was read in or saved.

Function: set-buffer-auto-saved
This function marks the current buffer as auto-saved. The buffer will not be auto-saved again until the buffer text is changed again. The function returns nil.

User Option: auto-save-interval
The value of this variable specifies how often to do auto-saving, in terms of number of input events. Each time this many additional input events are read, Emacs does auto-saving for all buffers in which that is enabled.

User Option: auto-save-timeout
The value of this variable is the number of seconds of idle time that should cause auto-saving. Each time the user pauses for this long, Emacs does auto-saving for all buffers in which that is enabled. (If the current buffer is large, the specified timeout is multiplied by a factor that increases as the size increases; for a million-byte buffer, the factor is almost 4.)

If the value is zero or nil, then auto-saving is not done as a result of idleness, only after a certain number of input events as specified by auto-save-interval.

Variable: auto-save-hook
This normal hook is run whenever an auto-save is about to happen.

User Option: auto-save-default
If this variable is non-nil, buffers that are visiting files have auto-saving enabled by default. Otherwise, they do not.

Command: do-auto-save &optional no-message current-only
This function auto-saves all buffers that need to be auto-saved. It saves all buffers for which auto-saving is enabled and that have been changed since the previous auto-save.

Normally, if any buffers are auto-saved, a message that says `Auto-saving...' is displayed in the echo area while auto-saving is going on. However, if no-message is non-nil, the message is inhibited.

If current-only is non-nil, only the current buffer is auto-saved.

Function: delete-auto-save-file-if-necessary
This function deletes the current buffer's auto-save file if delete-auto-save-files is non-nil. It is called every time a buffer is saved.

Variable: delete-auto-save-files
This variable is used by the function delete-auto-save-file-if-necessary. If it is non-nil, Emacs deletes auto-save files when a true save is done (in the visited file). This saves disk space and unclutters your directory.

Function: rename-auto-save-file
This function adjusts the current buffer's auto-save file name if the visited file name has changed. It also renames an existing auto-save file. If the visited file name has not changed, this function does nothing.

Variable: buffer-saved-size
The value of this buffer-local variable is the length of the current buffer, when it was last read in, saved, or auto-saved. This is used to detect a substantial decrease in size, and turn off auto-saving in response.

If it is -1, that means auto-saving is temporarily shut off in this buffer due to a substantial decrease in size. Explicitly saving the buffer stores a positive value in this variable, thus reenabling auto-saving. Turning auto-save mode off or on also updates this variable, so that the substantial decrease in size is forgotten.

Variable: auto-save-list-file-name
This variable (if non-nil) specifies a file for recording the names of all the auto-save files. Each time Emacs does auto-saving, it writes two lines into this file for each buffer that has auto-saving enabled. The first line gives the name of the visited file (it's empty if the buffer has none), and the second gives the name of the auto-save file.

When Emacs exits normally, it deletes this file; if Emacs crashes, you can look in the file to find all the auto-save files that might contain work that was otherwise lost. The recover-session command uses this file to find them.

The default name for this file specifies your home directory and starts with `.saves-'. It also contains the Emacs process ID and the host name.

Variable: auto-save-list-file-prefix
After Emacs reads your init file, it initializes auto-save-list-file-name (if you have not already set it non-nil) based on this prefix, adding the host name and process ID. If you set this to nil in your init file, then Emacs does not initialize auto-save-list-file-name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

26.3 Reverting

If you have made extensive changes to a file and then change your mind about them, you can get rid of them by reading in the previous version of the file with the revert-buffer command. See section `Reverting a Buffer' in The GNU Emacs Manual.

Command: revert-buffer &optional ignore-auto noconfirm
This command replaces the buffer text with the text of the visited file on disk. This action undoes all changes since the file was visited or saved.

By default, if the latest auto-save file is more recent than the visited file, and the argument ignore-auto is nil, revert-buffer asks the user whether to use that auto-save instead. When you invoke this command interactively, ignore-auto is t if there is no numeric prefix argument; thus, the interactive default is not to check the auto-save file.

Normally, revert-buffer asks for confirmation before it changes the buffer; but if the argument noconfirm is non-nil, revert-buffer does not ask for confirmation.

Reverting tries to preserve marker positions in the buffer by using the replacement feature of insert-file-contents. If the buffer contents and the file contents are identical before the revert operation, reverting preserves all the markers. If they are not identical, reverting does change the buffer; in that case, it preserves the markers in the unchanged text (if any) at the beginning and end of the buffer. Preserving any additional markers would be problematical.

You can customize how revert-buffer does its work by setting the variables described in the rest of this section.

Variable: revert-without-query
This variable holds a list of files that should be reverted without query. The value is a list of regular expressions. If the visited file name matches one of these regular expressions, and the file has changed on disk but the buffer is not modified, then revert-buffer reverts the file without asking the user for confirmation.

Some major modes customize revert-buffer by making buffer-local bindings for these variables:

Variable: revert-buffer-function
The value of this variable is the function to use to revert this buffer. If non-nil, it is called as a function with no arguments to do the work of reverting. If the value is nil, reverting works the usual way.

Modes such as Dired mode, in which the text being edited does not consist of a file's contents but can be regenerated in some other fashion, can give this variable a buffer-local value that is a function to regenerate the contents.

Variable: revert-buffer-insert-file-contents-function
The value of this variable, if non-nil, specifies the function to use to insert the updated contents when reverting this buffer. The function receives two arguments: first the file name to use; second, t if the user has asked to read the auto-save file.

The reason for a mode to set this variable instead of revert-buffer-function is to avoid duplicating or replacing the rest of what revert-buffer does: asking for confirmation, clearing the undo list, deciding the proper major mode, and running the hooks listed below.

Variable: before-revert-hook
This normal hook is run by revert-buffer before inserting the modified contents--but only if revert-buffer-function is nil.

Variable: after-revert-hook
This normal hook is run by revert-buffer after inserting the modified contents--but only if revert-buffer-function is nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27. Buffers

A buffer is a Lisp object containing text to be edited. Buffers are used to hold the contents of files that are being visited; there may also be buffers that are not visiting files. While several buffers may exist at one time, only one buffer is designated the current buffer at any time. Most editing commands act on the contents of the current buffer. Each buffer, including the current buffer, may or may not be displayed in any windows.

27.1 Buffer Basics

What is a buffer?

27.2 The Current Buffer

Designating a buffer as current so that primitives will access its contents.

27.3 Buffer Names

Accessing and changing buffer names.

27.4 Buffer File Name

The buffer file name indicates which file is visited.

27.5 Buffer Modification

A buffer is modified if it needs to be saved.

27.6 Comparison of Modification Time

Determining whether the visited file was changed

"behind Emacs's back".

27.7 Read-Only Buffers

Modifying text is not allowed in a read-only buffer.

27.8 The Buffer List

How to look at all the existing buffers.

27.9 Creating Buffers

Functions that create buffers.

27.10 Killing Buffers

Buffers exist until explicitly killed.

27.11 Indirect Buffers

An indirect buffer shares text with some other buffer.

27.12 The Buffer Gap

The gap in the buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.1 Buffer Basics

A buffer is a Lisp object containing text to be edited. Buffers are used to hold the contents of files that are being visited; there may also be buffers that are not visiting files. Although several buffers normally exist, only one buffer is designated the current buffer at any time. Most editing commands act on the contents of the current buffer. Each buffer, including the current buffer, may or may not be displayed in any windows.

Buffers in Emacs editing are objects that have distinct names and hold text that can be edited. Buffers appear to Lisp programs as a special data type. You can think of the contents of a buffer as a string that you can extend; insertions and deletions may occur in any part of the buffer. See section 32. Text.

A Lisp buffer object contains numerous pieces of information. Some of this information is directly accessible to the programmer through variables, while other information is accessible only through special-purpose functions. For example, the visited file name is directly accessible through a variable, while the value of point is accessible only through a primitive function.

Buffer-specific information that is directly accessible is stored in buffer-local variable bindings, which are variable values that are effective only in a particular buffer. This feature allows each buffer to override the values of certain variables. Most major modes override variables such as fill-column or comment-column in this way. For more information about buffer-local variables and functions related to them, see 11.10 Buffer-Local Variables.

For functions and variables related to visiting files in buffers, see 25.1 Visiting Files and 25.2 Saving Buffers. For functions and variables related to the display of buffers in windows, see 28.6 Buffers and Windows.

Function: bufferp object
This function returns t if object is a buffer, nil otherwise.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.2 The Current Buffer

There are, in general, many buffers in an Emacs session. At any time, one of them is designated as the current buffer. This is the buffer in which most editing takes place, because most of the primitives for examining or changing text in a buffer operate implicitly on the current buffer (see section 32. Text). Normally the buffer that is displayed on the screen in the selected window is the current buffer, but this is not always so: a Lisp program can temporarily designate any buffer as current in order to operate on its contents, without changing what is displayed on the screen.

The way to designate a current buffer in a Lisp program is by calling set-buffer. The specified buffer remains current until a new one is designated.

When an editing command returns to the editor command loop, the command loop designates the buffer displayed in the selected window as current, to prevent confusion: the buffer that the cursor is in when Emacs reads a command is the buffer that the command will apply to. (See section 21. Command Loop.) Therefore, set-buffer is not the way to switch visibly to a different buffer so that the user can edit it. For that, you must use the functions described in 28.7 Displaying Buffers in Windows.

Note: Lisp functions that change to a different current buffer should not depend on the command loop to set it back afterwards. Editing commands written in Emacs Lisp can be called from other programs as well as from the command loop; it is convenient for the caller if the subroutine does not change which buffer is current (unless, of course, that is the subroutine's purpose). Therefore, you should normally use set-buffer within a save-current-buffer or save-excursion (see section 30.3 Excursions) form that will restore the current buffer when your function is done. Here is an example, the code for the command append-to-buffer (with the documentation string abridged):
(defun append-to-buffer (buffer start end)
  "Append to specified buffer the text of the region.
..."
  (interactive "BAppend to buffer: \nr")
  (let ((oldbuf (current-buffer)))
    (save-current-buffer
      (set-buffer (get-buffer-create buffer))
      (insert-buffer-substring oldbuf start end))))
This function binds a local variable to record the current buffer, and then save-current-buffer arranges to make it current again. Next, set-buffer makes the specified buffer current. Finally, insert-buffer-substring copies the string from the original current buffer to the specified (and now current) buffer.

If the buffer appended to happens to be displayed in some window, the next redisplay will show how its text has changed. Otherwise, you will not see the change immediately on the screen. The buffer becomes current temporarily during the execution of the command, but this does not cause it to be displayed.

If you make local bindings (with let or function arguments) for a variable that may also have buffer-local bindings, make sure that the same buffer is current at the beginning and at the end of the local binding's scope. Otherwise you might bind it in one buffer and unbind it in another! There are two ways to do this. In simple cases, you may see that nothing ever changes the current buffer within the scope of the binding. Otherwise, use save-current-buffer or save-excursion to make sure that the buffer current at the beginning is current again whenever the variable is unbound.

Do not rely on using set-buffer to change the current buffer back, because that won't do the job if a quit happens while the wrong buffer is current. Here is what not to do:
(let (buffer-read-only
      (obuf (current-buffer)))
  (set-buffer ...)
  ...
  (set-buffer obuf))
Using save-current-buffer, as shown here, handles quitting, errors, and throw, as well as ordinary evaluation.
(let (buffer-read-only)
  (save-current-buffer
    (set-buffer ...)
    ...))
Function: current-buffer
This function returns the current buffer.
(current-buffer)
     => #<buffer buffers.texi>
Function: set-buffer buffer-or-name
This function makes buffer-or-name the current buffer. This does not display the buffer in any window, so the user cannot necessarily see the buffer. But Lisp programs will now operate on it.

This function returns the buffer identified by buffer-or-name. An error is signaled if buffer-or-name does not identify an existing buffer.

Special Form: save-current-buffer body...
The save-current-buffer macro saves the identity of the current buffer, evaluates the body forms, and finally restores that buffer as current. The return value is the value of the last form in body. The current buffer is restored even in case of an abnormal exit via throw or error (see section 10.5 Nonlocal Exits).

If the buffer that used to be current has been killed by the time of exit from save-current-buffer, then it is not made current again, of course. Instead, whichever buffer was current just before exit remains current.

Macro: with-current-buffer buffer body...
The with-current-buffer macro saves the identity of the current buffer, makes buffer current, evaluates the body forms, and finally restores the buffer. The return value is the value of the last form in body. The current buffer is restored even in case of an abnormal exit via throw or error (see section 10.5 Nonlocal Exits).

Macro: with-temp-buffer body...
The with-temp-buffer macro evaluates the body forms with a temporary buffer as the current buffer. It saves the identity of the current buffer, creates a temporary buffer and makes it current, evaluates the body forms, and finally restores the previous current buffer while killing the temporary buffer.

The return value is the value of the last form in body. You can return the contents of the temporary buffer by using (buffer-string) as the last form.

The current buffer is restored even in case of an abnormal exit via throw or error (see section 10.5 Nonlocal Exits).

See also with-temp-file in 25.4 Writing to Files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.3 Buffer Names

Each buffer has a unique name, which is a string. Many of the functions that work on buffers accept either a buffer or a buffer name as an argument. Any argument called buffer-or-name is of this sort, and an error is signaled if it is neither a string nor a buffer. Any argument called buffer must be an actual buffer object, not a name.

Buffers that are ephemeral and generally uninteresting to the user have names starting with a space, so that the list-buffers and buffer-menu commands don't mention them. A name starting with space also initially disables recording undo information; see 32.9 Undo.

Function: buffer-name &optional buffer
This function returns the name of buffer as a string. If buffer is not supplied, it defaults to the current buffer.

If buffer-name returns nil, it means that buffer has been killed. See section 27.10 Killing Buffers.
(buffer-name)
     => "buffers.texi"

(setq foo (get-buffer "temp"))
     => #<buffer temp>
(kill-buffer foo)
     => nil
(buffer-name foo)
     => nil
foo
     => #<killed buffer>
Command: rename-buffer newname &optional unique
This function renames the current buffer to newname. An error is signaled if newname is not a string, or if there is already a buffer with that name. The function returns newname.

Ordinarily, rename-buffer signals an error if newname is already in use. However, if unique is non-nil, it modifies newname to make a name that is not in use. Interactively, you can make unique non-nil with a numeric prefix argument. (This is how the command rename-uniquely is implemented.)

Function: get-buffer buffer-or-name
This function returns the buffer specified by buffer-or-name. If buffer-or-name is a string and there is no buffer with that name, the value is nil. If buffer-or-name is a buffer, it is returned as given; that is not very useful, so the argument is usually a name. For example:
(setq b (get-buffer "lewis"))
     => #<buffer lewis>
(get-buffer b)
     => #<buffer lewis>
(get-buffer "Frazzle-nots")
     => nil
See also the function get-buffer-create in 27.9 Creating Buffers.

Function: generate-new-buffer-name starting-name &rest ignore
This function returns a name that would be unique for a new buffer--but does not create the buffer. It starts with starting-name, and produces a name not currently in use for any buffer by appending a number inside of `<...>'.

If the optional second argument ignore is non-nil, it should be a string; it makes a difference if it is a name in the sequence of names to be tried. That name will be considered acceptable, if it is tried, even if a buffer with that name exists. Thus, if buffers named `foo', `foo<2>', `foo<3>' and `foo<4>' exist,
(generate-new-buffer-name "foo")
     => "foo<5>"
(generate-new-buffer-name "foo" "foo<3>")
     => "foo<3>"
(generate-new-buffer-name "foo" "foo<6>")
     => "foo<5>"
See the related function generate-new-buffer in 27.9 Creating Buffers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.4 Buffer File Name

The buffer file name is the name of the file that is visited in that buffer. When a buffer is not visiting a file, its buffer file name is nil. Most of the time, the buffer name is the same as the nondirectory part of the buffer file name, but the buffer file name and the buffer name are distinct and can be set independently. See section 25.1 Visiting Files.

Function: buffer-file-name &optional buffer
This function returns the absolute file name of the file that buffer is visiting. If buffer is not visiting any file, buffer-file-name returns nil. If buffer is not supplied, it defaults to the current buffer.
(buffer-file-name (other-buffer))
     => "/usr/user/lewis/manual/files.texi"
Variable: buffer-file-name
This buffer-local variable contains the name of the file being visited in the current buffer, or nil if it is not visiting a file. It is a permanent local variable, unaffected by kill-all-local-variables.
buffer-file-name
     => "/usr/user/lewis/manual/buffers.texi"
It is risky to change this variable's value without doing various other things. Normally it is better to use set-visited-file-name (see below); some of the things done there, such as changing the buffer name, are not strictly necessary, but others are essential to avoid confusing Emacs.

Variable: buffer-file-truename
This buffer-local variable holds the truename of the file visited in the current buffer, or nil if no file is visited. It is a permanent local, unaffected by kill-all-local-variables. See section 25.6.3 Truenames.

Variable: buffer-file-number
This buffer-local variable holds the file number and directory device number of the file visited in the current buffer, or nil if no file or a nonexistent file is visited. It is a permanent local, unaffected by kill-all-local-variables.

The value is normally a list of the form (filenum devnum). This pair of numbers uniquely identifies the file among all files accessible on the system. See the function file-attributes, in 25.6.4 Other Information about Files, for more information about them.

Function: get-file-buffer filename
This function returns the buffer visiting file filename. If there is no such buffer, it returns nil. The argument filename, which must be a string, is expanded (see section 25.8.4 Functions that Expand Filenames), then compared against the visited file names of all live buffers.
(get-file-buffer "buffers.texi")
    => #<buffer buffers.texi>
In unusual circumstances, there can be more than one buffer visiting the same file name. In such cases, this function returns the first such buffer in the buffer list.

Command: set-visited-file-name filename &optional no-query along-with-file
If filename is a non-empty string, this function changes the name of the file visited in the current buffer to filename. (If the buffer had no visited file, this gives it one.) The next time the buffer is saved it will go in the newly-specified file. This command marks the buffer as modified, since it does not (as far as Emacs knows) match the contents of filename, even if it matched the former visited file.

If filename is nil or the empty string, that stands for "no visited file". In this case, set-visited-file-name marks the buffer as having no visited file.

Normally, this function asks the user for confirmation if the specified file already exists. If no-query is non-nil, that prevents asking this question.

If along-with-file is non-nil, that means to assume that the former visited file has been renamed to filename.

When the function set-visited-file-name is called interactively, it prompts for filename in the minibuffer.

Variable: list-buffers-directory
This buffer-local variable specifies a string to display in a buffer listing where the visited file name would go, for buffers that don't have a visited file name. Dired buffers use this variable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.5 Buffer Modification

Emacs keeps a flag called the modified flag for each buffer, to record whether you have changed the text of the buffer. This flag is set to t whenever you alter the contents of the buffer, and cleared to nil when you save it. Thus, the flag shows whether there are unsaved changes. The flag value is normally shown in the mode line (see section 23.3.2 Variables Used in the Mode Line), and controls saving (see section 25.2 Saving Buffers) and auto-saving (see section 26.2 Auto-Saving).

Some Lisp programs set the flag explicitly. For example, the function set-visited-file-name sets the flag to t, because the text does not match the newly-visited file, even if it is unchanged from the file formerly visited.

The functions that modify the contents of buffers are described in 32. Text.

Function: buffer-modified-p &optional buffer
This function returns t if the buffer buffer has been modified since it was last read in from a file or saved, or nil otherwise. If buffer is not supplied, the current buffer is tested.

Function: set-buffer-modified-p flag
This function marks the current buffer as modified if flag is non-nil, or as unmodified if the flag is nil.

Another effect of calling this function is to cause unconditional redisplay of the mode line for the current buffer. In fact, the function force-mode-line-update works by doing this:
(set-buffer-modified-p (buffer-modified-p))
Command: not-modified
This command marks the current buffer as unmodified, and not needing to be saved. With prefix arg, it marks the buffer as modified, so that it will be saved at the next suitable occasion.

Don't use this function in programs, since it prints a message in the echo area; use set-buffer-modified-p (above) instead.

Function: buffer-modified-tick &optional buffer
This function returns buffer's modification-count. This is a counter that increments every time the buffer is modified. If buffer is nil (or omitted), the current buffer is used.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.6 Comparison of Modification Time

Suppose that you visit a file and make changes in its buffer, and meanwhile the file itself is changed on disk. At this point, saving the buffer would overwrite the changes in the file. Occasionally this may be what you want, but usually it would lose valuable information. Emacs therefore checks the file's modification time using the functions described below before saving the file.

Function: verify-visited-file-modtime buffer
This function compares what buffer has recorded for the modification time of its visited file against the actual modification time of the file as recorded by the operating system. The two should be the same unless some other process has written the file since Emacs visited or saved it.

The function returns t if the last actual modification time and Emacs's recorded modification time are the same, nil otherwise.

Function: clear-visited-file-modtime
This function clears out the record of the last modification time of the file being visited by the current buffer. As a result, the next attempt to save this buffer will not complain of a discrepancy in file modification times.

This function is called in set-visited-file-name and other exceptional places where the usual test to avoid overwriting a changed file should not be done.

Function: visited-file-modtime
This function returns the buffer's recorded last file modification time, as a list of the form (high . low). (This is the same format that file-attributes uses to return time values; see 25.6.4 Other Information about Files.)

Function: set-visited-file-modtime &optional time
This function updates the buffer's record of the last modification time of the visited file, to the value specified by time if time is not nil, and otherwise to the last modification time of the visited file.

If time is not nil, it should have the form (high . low) or (high low), in either case containing two integers, each of which holds 16 bits of the time.

This function is useful if the buffer was not read from the file normally, or if the file itself has been changed for some known benign reason.

Function: ask-user-about-supersession-threat filename
This function is used to ask a user how to proceed after an attempt to modify an obsolete buffer visiting file filename. An obsolete buffer is an unmodified buffer for which the associated file on disk is newer than the last save-time of the buffer. This means some other program has probably altered the file.

Depending on the user's answer, the function may return normally, in which case the modification of the buffer proceeds, or it may signal a file-supersession error with data (filename), in which case the proposed buffer modification is not allowed.

This function is called automatically by Emacs on the proper occasions. It exists so you can customize Emacs by redefining it. See the file `userlock.el' for the standard definition.

See also the file locking mechanism in 25.5 File Locks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.7 Read-Only Buffers

If a buffer is read-only, then you cannot change its contents, although you may change your view of the contents by scrolling and narrowing.

Read-only buffers are used in two kinds of situations:

A buffer visiting a write-protected file is normally read-only.
Here, the purpose is to inform the user that editing the buffer with the aim of saving it in the file may be futile or undesirable. The user who wants to change the buffer text despite this can do so after clearing the read-only flag with C-x C-q.

Modes such as Dired and Rmail make buffers read-only when altering the contents with the usual editing commands would probably be a mistake.
The special commands of these modes bind buffer-read-only to nil (with let) or bind inhibit-read-only to t around the places where they themselves change the text.

Variable: buffer-read-only
This buffer-local variable specifies whether the buffer is read-only. The buffer is read-only if this variable is non-nil.

Variable: inhibit-read-only
If this variable is non-nil, then read-only buffers and read-only characters may be modified. Read-only characters in a buffer are those that have non-nil read-only properties (either text properties or overlay properties). See section 32.19.4 Properties with Special Meanings, for more information about text properties. See section 38.9 Overlays, for more information about overlays and their properties.

If inhibit-read-only is t, all read-only character properties have no effect. If inhibit-read-only is a list, then read-only character properties have no effect if they are members of the list (comparison is done with eq).

Command: toggle-read-only
This command changes whether the current buffer is read-only. It is intended for interactive use; do not use it in programs. At any given point in a program, you should know whether you want the read-only flag on or off; so you can set buffer-read-only explicitly to the proper value, t or nil.

Function: barf-if-buffer-read-only
This function signals a buffer-read-only error if the current buffer is read-only. See section 21.3 Interactive Call, for another way to signal an error if the current buffer is read-only.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.8 The Buffer List

The buffer list is a list of all live buffers. Creating a buffer adds it to this list, and killing a buffer excises it. The order of the buffers in the list is based primarily on how recently each buffer has been displayed in the selected window. Buffers move to the front of the list when they are selected and to the end when they are buried (see bury-buffer, below). Several functions, notably other-buffer, use this ordering. A buffer list displayed for the user also follows this order.

In addition to the fundamental Emacs buffer list, each frame has its own version of the buffer list, in which the buffers that have been selected in that frame come first, starting with the buffers most recently selected in that frame. (This order is recorded in frame's buffer-list frame parameter; see 29.3.3 Window Frame Parameters.) The buffers that were never selected in frame come afterward, ordered according to the fundamental Emacs buffer list.

Function: buffer-list &optional frame
This function returns the buffer list, including all buffers, even those whose names begin with a space. The elements are actual buffers, not their names.

If frame is a frame, this returns frame's buffer list. If frame is nil, the fundamental Emacs buffer list is used: all the buffers appear in order of most recent selection, regardless of which frames they were selected in.
(buffer-list)
     => (#<buffer buffers.texi>
         #<buffer  *Minibuf-1*> #<buffer buffer.c>
         #<buffer *Help*> #<buffer TAGS>)

;; Note that the name of the minibuffer
;;   begins with a space!
(mapcar (function buffer-name) (buffer-list))
    => ("buffers.texi" " *Minibuf-1*"
        "buffer.c" "*Help*" "TAGS")
The list that buffer-list returns is constructed specifically by buffer-list; it is not an internal Emacs data structure, and modifying it has no effect on the order of buffers. If you want to change the order of buffers in the frame-independent buffer list, here is an easy way:
(defun reorder-buffer-list (new-list)
  (while new-list
    (bury-buffer (car new-list))
    (setq new-list (cdr new-list))))
With this method, you can specify any order for the list, but there is no danger of losing a buffer or adding something that is not a valid live buffer.

To change the order or value of a frame's buffer list, set the frame's buffer-list frame parameter with modify-frame-parameters (see section 29.3.1 Access to Frame Parameters).

Function: other-buffer &optional buffer visible-ok frame
This function returns the first buffer in the buffer list other than buffer. Usually this is the buffer selected most recently (in frame frame or else the currently selected frame, see section 29.9 Input Focus), aside from buffer. Buffers whose names start with a space are not considered at all.

If buffer is not supplied (or if it is not a buffer), then other-buffer returns the first buffer in the selected frame's buffer list that is not now visible in any window in a visible frame.

If frame has a non-nil buffer-predicate parameter, then other-buffer uses that predicate to decide which buffers to consider. It calls the predicate once for each buffer, and if the value is nil, that buffer is ignored. See section 29.3.3 Window Frame Parameters.

If visible-ok is nil, other-buffer avoids returning a buffer visible in any window on any visible frame, except as a last resort. If visible-ok is non-nil, then it does not matter whether a buffer is displayed somewhere or not.

If no suitable buffer exists, the buffer `*scratch*' is returned (and created, if necessary).

Command: bury-buffer &optional buffer-or-name
This function puts buffer-or-name at the end of the buffer list, without changing the order of any of the other buffers on the list. This buffer therefore becomes the least desirable candidate for other-buffer to return.

bury-buffer operates on each frame's buffer-list parameter as well as the frame-independent Emacs buffer list; therefore, the buffer that you bury will come last in the value of (buffer-list frame) and in the value of (buffer-list nil).

If buffer-or-name is nil or omitted, this means to bury the current buffer. In addition, if the buffer is displayed in the selected window, this switches to some other buffer (obtained using other-buffer) in the selected window. But if the buffer is displayed in some other window, it remains displayed there.

To replace a buffer in all the windows that display it, use replace-buffer-in-windows. See section 28.6 Buffers and Windows.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.9 Creating Buffers

This section describes the two primitives for creating buffers. get-buffer-create creates a buffer if it finds no existing buffer with the specified name; generate-new-buffer always creates a new buffer and gives it a unique name.

Other functions you can use to create buffers include with-output-to-temp-buffer (see section 38.8 Temporary Displays) and create-file-buffer (see section 25.1 Visiting Files). Starting a subprocess can also create a buffer (see section 37. Processes).

Function: get-buffer-create name
This function returns a buffer named name. It returns an existing buffer with that name, if one exists; otherwise, it creates a new buffer. The buffer does not become the current buffer--this function does not change which buffer is current.

An error is signaled if name is not a string.
(get-buffer-create "foo")
     => #<buffer foo>
The major mode for the new buffer is set to Fundamental mode. The variable default-major-mode is handled at a higher level. See section 23.1.3 How Emacs Chooses a Major Mode.

Function: generate-new-buffer name
This function returns a newly created, empty buffer, but does not make it current. If there is no buffer named name, then that is the name of the new buffer. If that name is in use, this function adds suffixes of the form `<n>' to name, where n is an integer. It tries successive integers starting with 2 until it finds an available name.

An error is signaled if name is not a string.
(generate-new-buffer "bar")
     => #<buffer bar>
(generate-new-buffer "bar")
     => #<buffer bar<2>>
(generate-new-buffer "bar")
     => #<buffer bar<3>>
The major mode for the new buffer is set to Fundamental mode. The variable default-major-mode is handled at a higher level. See section 23.1.3 How Emacs Chooses a Major Mode.

See the related function generate-new-buffer-name in 27.3 Buffer Names.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.10 Killing Buffers

Killing a buffer makes its name unknown to Emacs and makes its text space available for other use.

The buffer object for the buffer that has been killed remains in existence as long as anything refers to it, but it is specially marked so that you cannot make it current or display it. Killed buffers retain their identity, however; if you kill two distinct buffers, they remain distinct according to eq although both are dead.

If you kill a buffer that is current or displayed in a window, Emacs automatically selects or displays some other buffer instead. This means that killing a buffer can in general change the current buffer. Therefore, when you kill a buffer, you should also take the precautions associated with changing the current buffer (unless you happen to know that the buffer being killed isn't current). See section 27.2 The Current Buffer.

If you kill a buffer that is the base buffer of one or more indirect buffers, the indirect buffers are automatically killed as well.

The buffer-name of a killed buffer is nil. You can use this feature to test whether a buffer has been killed:
(defun buffer-killed-p (buffer)
  "Return t if BUFFER is killed."
  (not (buffer-name buffer)))
Command: kill-buffer buffer-or-name
This function kills the buffer buffer-or-name, freeing all its memory for other uses or to be returned to the operating system. It returns nil.

Any processes that have this buffer as the process-buffer are sent the SIGHUP signal, which normally causes them to terminate. (The basic meaning of SIGHUP is that a dialup line has been disconnected.) See section 37.5 Deleting Processes.

If the buffer is visiting a file and contains unsaved changes, kill-buffer asks the user to confirm before the buffer is killed. It does this even if not called interactively. To prevent the request for confirmation, clear the modified flag before calling kill-buffer. See section 27.5 Buffer Modification.

Killing a buffer that is already dead has no effect.
(kill-buffer "foo.unchanged")
     => nil
(kill-buffer "foo.changed")

---------- Buffer: Minibuffer ----------
Buffer foo.changed modified; kill anyway? (yes or no) yes
---------- Buffer: Minibuffer ----------

     => nil
Variable: kill-buffer-query-functions
After confirming unsaved changes, kill-buffer calls the functions in the list kill-buffer-query-functions, in order of appearance, with no arguments. The buffer being killed is the current buffer when they are called. The idea of this feature is that these functions will ask for confirmation from the user. If any of them returns nil, kill-buffer spares the buffer's life.

Variable: kill-buffer-hook
This is a normal hook run by kill-buffer after asking all the questions it is going to ask, just before actually killing the buffer. The buffer to be killed is current when the hook functions run. See section 23.6 Hooks.

Variable: buffer-offer-save
This variable, if non-nil in a particular buffer, tells save-buffers-kill-emacs and save-some-buffers to offer to save that buffer, just as they offer to save file-visiting buffers. The variable buffer-offer-save automatically becomes buffer-local when set for any reason. See section 11.10 Buffer-Local Variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.11 Indirect Buffers

An indirect buffer shares the text of some other buffer, which is called the base buffer of the indirect buffer. In some ways it is the analogue, for buffers, of a symbolic link among files. The base buffer may not itself be an indirect buffer.

The text of the indirect buffer is always identical to the text of its base buffer; changes made by editing either one are visible immediately in the other. This includes the text properties as well as the characters themselves.

In all other respects, the indirect buffer and its base buffer are completely separate. They have different names, different values of point, different narrowing, different markers and overlays (though inserting or deleting text in either buffer relocates the markers and overlays for both), different major modes, and different buffer-local variables.

An indirect buffer cannot visit a file, but its base buffer can. If you try to save the indirect buffer, that actually saves the base buffer.

Killing an indirect buffer has no effect on its base buffer. Killing the base buffer effectively kills the indirect buffer in that it cannot ever again be the current buffer.

Command: make-indirect-buffer base-buffer name
This creates an indirect buffer named name whose base buffer is base-buffer. The argument base-buffer may be a buffer or a string. If base-buffer is an indirect buffer, its base buffer is used as the base for the new buffer.

Function: buffer-base-buffer buffer
This function returns the base buffer of buffer. If buffer is not indirect, the value is nil. Otherwise, the value is another buffer, which is never an indirect buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

27.12 The Buffer Gap

Emacs buffers are implemented using an invisible gap to make insertion and deletion faster. Insertion works by filling in part of the gap, and deletion adds to the gap. Of course, this means that the gap must first be moved to the locus of the insertion or deletion. Emacs moves the gap only when you try to insert or delete. This is why your first editing command in one part of a large buffer, after previously editing in another far-away part, sometimes involves a noticeable delay.

This mechanism works invisibly, and Lisp code should never be affected by the gap's current location, but these functions are available for getting information about the gap status.

Function: gap-position
This function returns the current gap position in the current buffer.

Function: gap-size
This function returns the current gap size of the current buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28. Windows

This chapter describes most of the functions and variables related to Emacs windows. See 38. Emacs Display, for information on how text is displayed in windows.

28.1 Basic Concepts of Emacs Windows

Basic information on using windows.

28.2 Splitting Windows

Splitting one window into two windows.

28.3 Deleting Windows

Deleting a window gives its space to other windows.

28.4 Selecting Windows

The selected window is the one that you edit in.

28.5 Cyclic Ordering of Windows

Moving around the existing windows.

28.6 Buffers and Windows

Each window displays the contents of a buffer.

28.7 Displaying Buffers in Windows

Higher-lever functions for displaying a buffer and choosing a window for it.

28.8 Choosing a Window for Display

How to choose a window for displaying a buffer.

28.9 Windows and Point

Each window has its own location of point.

28.10 The Window Start Position

The display-start position controls which text is on-screen in the window.

28.11 Textual Scrolling

Moving text up and down through the window.

28.12 Vertical Fractional Scrolling

Moving the contents up and down on the window.

28.13 Horizontal Scrolling

Moving the contents sideways on the window.

28.14 The Size of a Window

Accessing the size of a window.

28.15 Changing the Size of a Window

Changing the size of a window.

28.16 Coordinates and Windows

Converting coordinates to windows.

28.17 Window Configurations

Saving and restoring the state of the screen.

28.18 Hooks for Window Scrolling and Changes

Hooks for scrolling, window size changes, redisplay going past a certain point, or window configuration changes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.1 Basic Concepts of Emacs Windows

A window in Emacs is the physical area of the screen in which a buffer is displayed. The term is also used to refer to a Lisp object that represents that screen area in Emacs Lisp. It should be clear from the context which is meant.

Emacs groups windows into frames. A frame represents an area of screen available for Emacs to use. Each frame always contains at least one window, but you can subdivide it vertically or horizontally into multiple nonoverlapping Emacs windows.

In each frame, at any time, one and only one window is designated as selected within the frame. The frame's cursor appears in that window. At any time, one frame is the selected frame; and the window selected within that frame is the selected window. The selected window's buffer is usually the current buffer (except when set-buffer has been used). See section 27.2 The Current Buffer.

For practical purposes, a window exists only while it is displayed in a frame. Once removed from the frame, the window is effectively deleted and should not be used, even though there may still be references to it from other Lisp objects. Restoring a saved window configuration is the only way for a window no longer on the screen to come back to life. (See section 28.3 Deleting Windows.)

Each window has the following attributes:

containing frame

window height

window width

window edges with respect to the screen or frame

the buffer it displays

position within the buffer at the upper left of the window

amount of horizontal scrolling, in columns

point

the mark

how recently the window was selected

Users create multiple windows so they can look at several buffers at once. Lisp libraries use multiple windows for a variety of reasons, but most often to display related information. In Rmail, for example, you can move through a summary buffer in one window while the other window shows messages one at a time as they are reached.

The meaning of "window" in Emacs is similar to what it means in the context of general-purpose window systems such as X, but not identical. The X Window System places X windows on the screen; Emacs uses one or more X windows as frames, and subdivides them into Emacs windows. When you use Emacs on a character-only terminal, Emacs treats the whole terminal screen as one frame.

Most window systems support arbitrarily located overlapping windows. In contrast, Emacs windows are tiled; they never overlap, and together they fill the whole screen or frame. Because of the way in which Emacs creates new windows and resizes them, not all conceivable tilings of windows on an Emacs frame are actually possible. See section 28.2 Splitting Windows, and 28.14 The Size of a Window.

See section 38. Emacs Display, for information on how the contents of the window's buffer are displayed in the window.

Function: windowp object
This function returns t if object is a window.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.2 Splitting Windows

The functions described here are the primitives used to split a window into two windows. Two higher level functions sometimes split a window, but not always: pop-to-buffer and display-buffer (see section 28.7 Displaying Buffers in Windows).

The functions described here do not accept a buffer as an argument. The two "halves" of the split window initially display the same buffer previously visible in the window that was split.

Command: split-window &optional window size horizontal
This function splits window into two windows. The original window window remains the selected window, but occupies only part of its former screen area. The rest is occupied by a newly created window which is returned as the value of this function.

If horizontal is non-nil, then window splits into two side by side windows. The original window window keeps the leftmost size columns, and gives the rest of the columns to the new window. Otherwise, it splits into windows one above the other, and window keeps the upper size lines and gives the rest of the lines to the new window. The original window is therefore the left-hand or upper of the two, and the new window is the right-hand or lower.

If window is omitted or nil, then the selected window is split. If size is omitted or nil, then window is divided evenly into two parts. (If there is an odd line, it is allocated to the new window.) When split-window is called interactively, all its arguments are nil.

The following example starts with one window on a screen that is 50 lines high by 80 columns wide; then the window is split.
(setq w (selected-window))
     => #<window 8 on windows.texi>
(window-edges)          ; Edges in order:
     => (0 0 80 50)     ;   left--top--right--bottom

;; Returns window created
(setq w2 (split-window w 15))
     => #<window 28 on windows.texi>
(window-edges w2)
     => (0 15 80 50)    ; Bottom window;
                        ;   top is line 15
(window-edges w)
     => (0 0 80 15)     ; Top window
The screen looks like this:
         __________
        |          |  line 0
        |    w     |
        |__________|
        |          |  line 15
        |    w2    |
        |__________|
                      line 50
 column 0   column 80
Next, the top window is split horizontally:
(setq w3 (split-window w 35 t))
     => #<window 32 on windows.texi>
(window-edges w3)
     => (35 0 80 15)  ; Left edge at column 35
(window-edges w)
     => (0 0 35 15)   ; Right edge at column 35
(window-edges w2)
     => (0 15 80 50)  ; Bottom window unchanged
Now, the screen looks like this:
     column 35
         __________
        |   |      |  line 0
        | w |  w3  |
        |___|______|
        |          |  line 15
        |    w2    |
        |__________|
                      line 50
 column 0   column 80
Normally, Emacs indicates the border between two side-by-side windows with a scroll bar (see section Scroll Bars) or `|' characters. The display table can specify alternative border characters; see 38.17 Display Tables.

Command: split-window-vertically &optional size
This function splits the selected window into two windows, one above the other, leaving the upper of the two windows selected, with size lines. (If size is negative, then the lower of the two windows gets - size lines and the upper window gets the rest, but the upper window is still the one selected.)

Command: split-window-horizontally &optional size
This function splits the selected window into two windows side-by-side, leaving the selected window with size columns.

This function is basically an interface to split-window. You could define a simplified version of the function like this:
(defun split-window-horizontally (&optional arg)
  "Split selected window into two windows, side by side..."
  (interactive "P")
  (let ((size (and arg (prefix-numeric-value arg))))
    (and size (< size 0)
     (setq size (+ (window-width) size)))
    (split-window nil size t)))
Function: one-window-p &optional no-mini all-frames
This function returns non-nil if there is only one window. The argument no-mini, if non-nil, means don't count the minibuffer even if it is active; otherwise, the minibuffer window is included, if active, in the total number of windows, which is compared against one.

The argument all-frames specifies which frames to consider. Here are the possible values and their meanings:

nil
Count the windows in the selected frame, plus the minibuffer used by that frame even if it lies in some other frame.

t
Count all windows in all existing frames.

visible
Count all windows in all visible frames.

0
Count all windows in all visible or iconified frames.

anything else
Count precisely the windows in the selected frame, and no others.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.3 Deleting Windows

A window remains visible on its frame unless you delete it by calling certain functions that delete windows. A deleted window cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a window aside from restoring a saved window configuration (see section 28.17 Window Configurations). Restoring a window configuration also deletes any windows that aren't part of that configuration.

When you delete a window, the space it took up is given to one adjacent sibling.

Function: window-live-p window
This function returns nil if window is deleted, and t otherwise.

Warning: Erroneous information or fatal errors may result from using a deleted window as if it were live.

Command: delete-window &optional window
This function removes window from display, and returns nil. If window is omitted, then the selected window is deleted. An error is signaled if there is only one window when delete-window is called.

Command: delete-other-windows &optional window
This function makes window the only window on its frame, by deleting the other windows in that frame. If window is omitted or nil, then the selected window is used by default.

The return value is nil.

Command: delete-windows-on buffer &optional frame
This function deletes all windows showing buffer. If there are no windows showing buffer, it does nothing.

delete-windows-on operates frame by frame. If a frame has several windows showing different buffers, then those showing buffer are removed, and the others expand to fill the space. If all windows in some frame are showing buffer (including the case where there is only one window), then the frame reverts to having a single window showing another buffer chosen with other-buffer. See section 27.8 The Buffer List.

The argument frame controls which frames to operate on. This function does not use it in quite the same way as the other functions which scan all windows; specifically, the values t and nil have the opposite of their meanings in other functions. Here are the full details:

If it is nil, operate on all frames.
If it is t, operate on the selected frame.
If it is visible, operate on all visible frames.
If it is 0, operate on all visible or iconified frames.
If it is a frame, operate on that frame.

This function always returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.4 Selecting Windows

When a window is selected, the buffer in the window becomes the current buffer, and the cursor will appear in it.

Function: selected-window
This function returns the selected window. This is the window in which the cursor appears and to which many commands apply.

Function: select-window window
This function makes window the selected window. The cursor then appears in window (on redisplay). The buffer being displayed in window is immediately designated the current buffer.

The return value is window.
(setq w (next-window))
(select-window w)
     => #<window 65 on windows.texi>
Macro: save-selected-window forms...
This macro records the selected window, executes forms in sequence, then restores the earlier selected window, unless it is no longer alive.

This macro does not save or restore anything about the sizes, arrangement or contents of windows; therefore, if the forms change them, the change persists.

Each frame, at any time, has a window selected within the frame. This macro saves only the selected window; it does not save anything about other frames. If the forms select some other frame and alter the window selected within it, the change persists.

The following functions choose one of the windows on the screen, offering various criteria for the choice.

Function: get-lru-window &optional frame
This function returns the window least recently "used" (that is, selected). The selected window is always the most recently used window.

The selected window can be the least recently used window if it is the only window. A newly created window becomes the least recently used window until it is selected. A minibuffer window is never a candidate.

The argument frame controls which windows are considered.

If it is nil, consider windows on the selected frame.
If it is t, consider windows on all frames.
If it is visible, consider windows on all visible frames.
If it is 0, consider windows on all visible or iconified frames.
If it is a frame, consider windows on that frame.

Function: get-largest-window &optional frame
This function returns the window with the largest area (height times width). If there are no side-by-side windows, then this is the window with the most lines. A minibuffer window is never a candidate.

If there are two windows of the same size, then the function returns the window that is first in the cyclic ordering of windows (see following section), starting from the selected window.

The argument frame controls which set of windows to consider. See get-lru-window, above.

Function: get-window-with-predicate predicate &optional minibuf all-frames default
This function returns a window satisfying predicate. It cycles through all visible windows using walk-windows (see section 28.5 Cyclic Ordering of Windows), calling predicate on each one one of them with that window as its argument. The function returns the first window for which predicate returns a non-nil value; if that never happens, it returns default.

The optional arguments minibuf and all-frames specify the set of windows to include in the scan. See the description of next-window in 28.5 Cyclic Ordering of Windows, for details.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.5 Cyclic Ordering of Windows

When you use the command C-x o (other-window) to select the next window, it moves through all the windows on the screen in a specific cyclic order. For any given configuration of windows, this order never varies. It is called the cyclic ordering of windows.

This ordering generally goes from top to bottom, and from left to right. But it may go down first or go right first, depending on the order in which the windows were split.

If the first split was vertical (into windows one above each other), and then the subwindows were split horizontally, then the ordering is left to right in the top of the frame, and then left to right in the next lower part of the frame, and so on. If the first split was horizontal, the ordering is top to bottom in the left part, and so on. In general, within each set of siblings at any level in the window tree, the order is left to right, or top to bottom.

Function: next-window &optional window minibuf all-frames
This function returns the window following window in the cyclic ordering of windows. This is the window that C-x o would select if typed when window is selected. If window is the only window visible, then this function returns window. If omitted, window defaults to the selected window.

The value of the argument minibuf determines whether the minibuffer is included in the window order. Normally, when minibuf is nil, the minibuffer is included if it is currently active; this is the behavior of C-x o. (The minibuffer window is active while the minibuffer is in use. See section 20. Minibuffers.)

If minibuf is t, then the cyclic ordering includes the minibuffer window even if it is not active.

If minibuf is neither t nor nil, then the minibuffer window is not included even if it is active.

The argument all-frames specifies which frames to consider. Here are the possible values and their meanings:

nil
Consider all the windows in window's frame, plus the minibuffer used by that frame even if it lies in some other frame.

t
Consider all windows in all existing frames.

visible
Consider all windows in all visible frames. (To get useful results, you must ensure window is in a visible frame.)

0
Consider all windows in all visible or iconified frames.

anything else
Consider precisely the windows in window's frame, and no others.
This example assumes there are two windows, both displaying the buffer `windows.texi':
(selected-window)
     => #<window 56 on windows.texi>
(next-window (selected-window))
     => #<window 52 on windows.texi>
(next-window (next-window (selected-window)))
     => #<window 56 on windows.texi>
Function: previous-window &optional window minibuf all-frames
This function returns the window preceding window in the cyclic ordering of windows. The other arguments specify which windows to include in the cycle, as in next-window.

Command: other-window count &optional all-frames
This function selects the countth following window in the cyclic order. If count is negative, then it moves back -count windows in the cycle, rather than forward. It returns nil.

The argument all-frames has the same meaning as in next-window, but the minibuf argument of next-window is always effectively nil.

In an interactive call, count is the numeric prefix argument.

Function: walk-windows proc &optional minibuf all-frames
This function cycles through all windows, calling proc once for each window with the window as its sole argument.

The optional arguments minibuf and all-frames specify the set of windows to include in the scan. See next-window, above, for details.

Function: window-list &optional frame minibuf window
This function returns a list of the windows on frame, starting with window. If frame is nil or omitted, the selected frame is used instead; if window is nil or omitted, the selected window is used instead.

The value of minibuf determines if the minibuffer window will be included in the result list. If minibuf is t, the minibuffer window will be included, even if it isn't active. If minibuf is nil or omitted, the minibuffer window will only be included in the list if it is active. If minibuf is neither nil nor t, the minibuffer window is not included, whether or not it is active.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.6 Buffers and Windows

This section describes low-level functions to examine windows or to display buffers in windows in a precisely controlled fashion. See section 28.7 Displaying Buffers in Windows, for related functions that find a window to use and specify a buffer for it. The functions described there are easier to use than these, but they employ heuristics in choosing or creating a window; use these functions when you need complete control.

Function: set-window-buffer window buffer-or-name
This function makes window display buffer-or-name as its contents. It returns nil. This is the fundamental primitive for changing which buffer is displayed in a window, and all ways of doing that call this function.
(set-window-buffer (selected-window) "foo")
     => nil
Function: window-buffer &optional window
This function returns the buffer that window is displaying. If window is omitted, this function returns the buffer for the selected window.
(window-buffer)
     => #<buffer windows.texi>
Function: get-buffer-window buffer-or-name &optional all-frames
This function returns a window currently displaying buffer-or-name, or nil if there is none. If there are several such windows, then the function returns the first one in the cyclic ordering of windows, starting from the selected window. See section 28.5 Cyclic Ordering of Windows.

The argument all-frames controls which windows to consider.

If it is nil, consider windows on the selected frame.
If it is t, consider windows on all frames.
If it is visible, consider windows on all visible frames.
If it is 0, consider windows on all visible or iconified frames.
If it is a frame, consider windows on that frame.

Function: get-buffer-window-list buffer-or-name &optional minibuf all-frames
This function returns a list of all the windows currently displaying buffer-or-name.

The two optional arguments work like the optional arguments of next-window (see section 28.5 Cyclic Ordering of Windows); they are not like the single optional argument of get-buffer-window. Perhaps we should change get-buffer-window in the future to make it compatible with the other functions.

The argument all-frames controls which windows to consider.

If it is nil, consider windows on the selected frame.
If it is t, consider windows on all frames.
If it is visible, consider windows on all visible frames.
If it is 0, consider windows on all visible or iconified frames.
If it is a frame, consider windows on that frame.

Variable: buffer-display-time
This variable records the time at which a buffer was last made visible in a window. It is always local in each buffer; each time set-window-buffer is called, it sets this variable to (current-time) in the specified buffer (see section 40.5 Time of Day). When a buffer is first created, buffer-display-time starts out with the value nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.7 Displaying Buffers in Windows

In this section we describe convenient functions that choose a window automatically and use it to display a specified buffer. These functions can also split an existing window in certain circumstances. We also describe variables that parameterize the heuristics used for choosing a window. See section 28.6 Buffers and Windows, for low-level functions that give you more precise control. All of these functions work by calling set-window-buffer.

Do not use the functions in this section in order to make a buffer current so that a Lisp program can access or modify it; they are too drastic for that purpose, since they change the display of buffers in windows, which would be gratuitous and surprise the user. Instead, use set-buffer and save-current-buffer (see section 27.2 The Current Buffer), which designate buffers as current for programmed access without affecting the display of buffers in windows.

Command: switch-to-buffer buffer-or-name &optional norecord
This function makes buffer-or-name the current buffer, and also displays the buffer in the selected window. This means that a human can see the buffer and subsequent keyboard commands will apply to it. Contrast this with set-buffer, which makes buffer-or-name the current buffer but does not display it in the selected window. See section 27.2 The Current Buffer.

If buffer-or-name does not identify an existing buffer, then a new buffer by that name is created. The major mode for the new buffer is set according to the variable default-major-mode. See section 23.1.3 How Emacs Chooses a Major Mode.

Normally the specified buffer is put at the front of the buffer list (both the selected frame's buffer list and the frame-independent buffer list). This affects the operation of other-buffer. However, if norecord is non-nil, this is not done. See section 27.8 The Buffer List.

The switch-to-buffer function is often used interactively, as the binding of C-x b. It is also used frequently in programs. It always returns nil.

Command: switch-to-buffer-other-window buffer-or-name &optional norecord
This function makes buffer-or-name the current buffer and displays it in a window not currently selected. It then selects that window. The handling of the buffer is the same as in switch-to-buffer.

The currently selected window is absolutely never used to do the job. If it is the only window, then it is split to make a distinct window for this purpose. If the selected window is already displaying the buffer, then it continues to do so, but another window is nonetheless found to display it in as well.

This function updates the buffer list just like switch-to-buffer unless norecord is non-nil.

Function: pop-to-buffer buffer-or-name &optional other-window norecord
This function makes buffer-or-name the current buffer and switches to it in some window, preferably not the window previously selected. The "popped-to" window becomes the selected window within its frame.

If the variable pop-up-frames is non-nil, pop-to-buffer looks for a window in any visible frame already displaying the buffer; if there is one, it returns that window and makes it be selected within its frame. If there is none, it creates a new frame and displays the buffer in it.

If pop-up-frames is nil, then pop-to-buffer operates entirely within the selected frame. (If the selected frame has just a minibuffer, pop-to-buffer operates within the most recently selected frame that was not just a minibuffer.)

If the variable pop-up-windows is non-nil, windows may be split to create a new window that is different from the original window. For details, see 28.8 Choosing a Window for Display.

If other-window is non-nil, pop-to-buffer finds or creates another window even if buffer-or-name is already visible in the selected window. Thus buffer-or-name could end up displayed in two windows. On the other hand, if buffer-or-name is already displayed in the selected window and other-window is nil, then the selected window is considered sufficient display for buffer-or-name, so that nothing needs to be done.

All the variables that affect display-buffer affect pop-to-buffer as well. See section 28.8 Choosing a Window for Display.

If buffer-or-name is a string that does not name an existing buffer, a buffer by that name is created. The major mode for the new buffer is set according to the variable default-major-mode. See section 23.1.3 How Emacs Chooses a Major Mode.

This function updates the buffer list just like switch-to-buffer unless norecord is non-nil.

Command: replace-buffer-in-windows buffer
This function replaces buffer with some other buffer in all windows displaying it. The other buffer used is chosen with other-buffer. In the usual applications of this function, you don't care which other buffer is used; you just want to make sure that buffer is no longer displayed.

This function returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.8 Choosing a Window for Display

This section describes the basic facility that chooses a window to display a buffer in---display-buffer. All the higher-level functions and commands use this subroutine. Here we describe how to use display-buffer and how to customize it.

Command: display-buffer buffer-or-name &optional not-this-window frame
This command makes buffer-or-name appear in some window, like pop-to-buffer, but it does not select that window and does not make the buffer current. The identity of the selected window is unaltered by this function.

If not-this-window is non-nil, it means to display the specified buffer in a window other than the selected one, even if it is already on display in the selected window. This can cause the buffer to appear in two windows at once. Otherwise, if buffer-or-name is already being displayed in any window, that is good enough, so this function does nothing.

display-buffer returns the window chosen to display buffer-or-name.

If the argument frame is non-nil, it specifies which frames to check when deciding whether the buffer is already displayed. If the buffer is already displayed in some window on one of these frames, display-buffer simply returns that window. Here are the possible values of frame:

If it is nil, consider windows on the selected frame.
If it is t, consider windows on all frames.
If it is visible, consider windows on all visible frames.
If it is 0, consider windows on all visible or iconified frames.
If it is a frame, consider windows on that frame.

Precisely how display-buffer finds or creates a window depends on the variables described below.

User Option: display-buffer-reuse-frames
If this variable is non-nil, display-buffer searches existing frames for a window displaying the buffer. If the buffer is already displayed in a window in some frame, display-buffer makes the frame visible and raises it, to use that window. If the buffer is not already displayed, or if display-buffer-reuse-frames is nil, display-buffer's behavior is determined by other variables, described below.

User Option: pop-up-windows
This variable controls whether display-buffer makes new windows. If it is non-nil and there is only one window, then that window is split. If it is nil, then display-buffer does not split the single window, but uses it whole.

User Option: split-height-threshold
This variable determines when display-buffer may split a window, if there are multiple windows. display-buffer always splits the largest window if it has at least this many lines. If the largest window is not this tall, it is split only if it is the sole window and pop-up-windows is non-nil.

User Option: even-window-heights
This variable determines if display-buffer should even out window heights if the buffer gets displayed in an existing window, above or beneath another existing window. If even-window-heights is t, the default, window heights will be evened out. If even-window-heights is nil, the orginal window heights will be left alone.

User Option: pop-up-frames
This variable controls whether display-buffer makes new frames. If it is non-nil, display-buffer looks for an existing window already displaying the desired buffer, on any visible frame. If it finds one, it returns that window. Otherwise it makes a new frame. The variables pop-up-windows and split-height-threshold do not matter if pop-up-frames is non-nil.

If pop-up-frames is nil, then display-buffer either splits a window or reuses one.

See section 29. Frames, for more information.

Variable: pop-up-frame-function
This variable specifies how to make a new frame if pop-up-frames is non-nil.

Its value should be a function of no arguments. When display-buffer makes a new frame, it does so by calling that function, which should return a frame. The default value of the variable is a function that creates a frame using parameters from pop-up-frame-alist.

User Option: pop-up-frame-alist
This variable holds an alist specifying frame parameters used when display-buffer makes a new frame. See section 29.3 Frame Parameters, for more information about frame parameters.

User Option: special-display-buffer-names
A list of buffer names for buffers that should be displayed specially. If the buffer's name is in this list, display-buffer handles the buffer specially.

By default, special display means to give the buffer a dedicated frame.

If an element is a list, instead of a string, then the CAR of the list is the buffer name, and the rest of the list says how to create the frame. There are two possibilities for the rest of the list. It can be an alist, specifying frame parameters, or it can contain a function and arguments to give to it. (The function's first argument is always the buffer to be displayed; the arguments from the list come after that.)

User Option: special-display-regexps
A list of regular expressions that specify buffers that should be displayed specially. If the buffer's name matches any of the regular expressions in this list, display-buffer handles the buffer specially.

By default, special display means to give the buffer a dedicated frame.

If an element is a list, instead of a string, then the CAR of the list is the regular expression, and the rest of the list says how to create the frame. See above, under special-display-buffer-names.

Variable: special-display-function
This variable holds the function to call to display a buffer specially. It receives the buffer as an argument, and should return the window in which it is displayed.

The default value of this variable is special-display-popup-frame.

Function: special-display-popup-frame buffer &rest args
This function makes buffer visible in a frame of its own. If buffer is already displayed in a window in some frame, it makes the frame visible and raises it, to use that window. Otherwise, it creates a frame that will be dedicated to buffer.

If args is an alist, it specifies frame parameters for the new frame.

If args is a list whose CAR is a symbol, then (car args) is called as a function to actually create and set up the frame; it is called with buffer as first argument, and (cdr args) as additional arguments.

This function always uses an existing window displaying buffer, whether or not it is in a frame of its own; but if you set up the above variables in your init file, before buffer was created, then presumably the window was previously made by this function.

User Option: special-display-frame-alist
This variable holds frame parameters for special-display-popup-frame to use when it creates a frame.

User Option: same-window-buffer-names
A list of buffer names for buffers that should be displayed in the selected window. If the buffer's name is in this list, display-buffer handles the buffer by switching to it in the selected window.

User Option: same-window-regexps
A list of regular expressions that specify buffers that should be displayed in the selected window. If the buffer's name matches any of the regular expressions in this list, display-buffer handles the buffer by switching to it in the selected window.

Variable: display-buffer-function
This variable is the most flexible way to customize the behavior of display-buffer. If it is non-nil, it should be a function that display-buffer calls to do the work. The function should accept two arguments, the same two arguments that display-buffer received. It should choose or create a window, display the specified buffer, and then return the window.

This hook takes precedence over all the other options and hooks described above.

A window can be marked as "dedicated" to its buffer. Then display-buffer will not try to use that window to display any other buffer.

Function: window-dedicated-p window
This function returns t if window is marked as dedicated; otherwise nil.

Function: set-window-dedicated-p window flag
This function marks window as dedicated if flag is non-nil, and nondedicated otherwise.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.9 Windows and Point

Each window has its own value of point, independent of the value of point in other windows displaying the same buffer. This makes it useful to have multiple windows showing one buffer.

The window point is established when a window is first created; it is initialized from the buffer's point, or from the window point of another window opened on the buffer if such a window exists.

Selecting a window sets the value of point in its buffer from the window's value of point. Conversely, deselecting a window sets the window's value of point from that of the buffer. Thus, when you switch between windows that display a given buffer, the point value for the selected window is in effect in the buffer, while the point values for the other windows are stored in those windows.

As long as the selected window displays the current buffer, the window's point and the buffer's point always move together; they remain equal.

See section 30. Positions, for more details on buffer positions.

As far as the user is concerned, point is where the cursor is, and when the user switches to another buffer, the cursor jumps to the position of point in that buffer.

Function: window-point &optional window
This function returns the current position of point in window. For a nonselected window, this is the value point would have (in that window's buffer) if that window were selected. If window is nil, the selected window is used.

When window is the selected window and its buffer is also the current buffer, the value returned is the same as point in that buffer.

Strictly speaking, it would be more correct to return the "top-level" value of point, outside of any save-excursion forms. But that value is hard to find.

Function: set-window-point window position
This function positions point in window at position position in window's buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.10 The Window Start Position

Each window contains a marker used to keep track of a buffer position that specifies where in the buffer display should start. This position is called the display-start position of the window (or just the start). The character after this position is the one that appears at the upper left corner of the window. It is usually, but not inevitably, at the beginning of a text line.

Function: window-start &optional window
This function returns the display-start position of window window. If window is nil, the selected window is used. For example,
(window-start)
     => 7058
When you create a window, or display a different buffer in it, the display-start position is set to a display-start position recently used for the same buffer, or 1 if the buffer doesn't have any.

Redisplay updates the window-start position (if you have not specified it explicitly since the previous redisplay)---for example, to make sure point appears on the screen. Nothing except redisplay automatically changes the window-start position; if you move point, do not expect the window-start position to change in response until after the next redisplay.

For a realistic example of using window-start, see the description of count-lines in 30.2.4 Motion by Text Lines.

Function: window-end &optional window update
This function returns the position of the end of the display in window window. If window is nil, the selected window is used.

Simply changing the buffer text or moving point does not update the value that window-end returns. The value is updated only when Emacs redisplays and redisplay completes without being preempted.

If the last redisplay of window was preempted, and did not finish, Emacs does not know the position of the end of display in that window. In that case, this function returns nil.

If update is non-nil, window-end always returns an up-to-date value for where the window ends, based on the current window-start value. If the saved value is valid, window-end returns that; otherwise it computes the correct value by scanning the buffer text.

Even if update is non-nil, window-end does not attempt to scroll the display if point has moved off the screen, the way real redisplay would do. It does not alter the window-start value. In effect, it reports where the displayed text will end if scrolling is not required.

Function: set-window-start window position &optional noforce
This function sets the display-start position of window to position in window's buffer. It returns position.

The display routines insist that the position of point be visible when a buffer is displayed. Normally, they change the display-start position (that is, scroll the window) whenever necessary to make point visible. However, if you specify the start position with this function using nil for noforce, it means you want display to start at position even if that would put the location of point off the screen. If this does place point off screen, the display routines move point to the left margin on the middle line in the window.

For example, if point is 1 and you set the start of the window to 2, then point would be "above" the top of the window. The display routines will automatically move point if it is still 1 when redisplay occurs. Here is an example:
;; Here is what `foo' looks like before executing
;;   the set-window-start expression.

---------- Buffer: foo ----------
-!-This is the contents of buffer foo.
2
3
4
5
6
---------- Buffer: foo ----------

(set-window-start
 (selected-window)
 (1+ (window-start)))
=> 2

;; Here is what `foo' looks like after executing
;;   the set-window-start expression.
---------- Buffer: foo ----------
his is the contents of buffer foo.
2
3
-!-4
5
6
---------- Buffer: foo ----------
If noforce is non-nil, and position would place point off screen at the next redisplay, then redisplay computes a new window-start position that works well with point, and thus position is not used.

Function: pos-visible-in-window-p &optional position window partially
This function returns t if position is within the range of text currently visible on the screen in window. It returns nil if position is scrolled vertically or horizontally out of view. Locations that are partially obscured are not considered visible unless partially is non-nil. The argument position defaults to the current position of point in window; window, to the selected window.

Here is an example:
(or (pos-visible-in-window-p
     (point) (selected-window))
    (recenter 0))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.11 Textual Scrolling

Textual scrolling means moving the text up or down though a window. It works by changing the value of the window's display-start location. It may also change the value of window-point to keep point on the screen.

Textual scrolling was formerly called "vertical scrolling," but we changed its name to distinguish it from the new vertical fractional scrolling feature (see section 28.12 Vertical Fractional Scrolling).

In the commands scroll-up and scroll-down, the directions "up" and "down" refer to the motion of the text in the buffer at which you are looking through the window. Imagine that the text is written on a long roll of paper and that the scrolling commands move the paper up and down. Thus, if you are looking at text in the middle of a buffer and repeatedly call scroll-down, you will eventually see the beginning of the buffer.

Some people have urged that the opposite convention be used: they imagine that the window moves over text that remains in place. Then "down" commands would take you to the end of the buffer. This view is more consistent with the actual relationship between windows and the text in the buffer, but it is less like what the user sees. The position of a window on the terminal does not move, and short scrolling commands clearly move the text up or down on the screen. We have chosen names that fit the user's point of view.

The textual scrolling functions (aside from scroll-other-window) have unpredictable results if the current buffer is different from the buffer that is displayed in the selected window. See section 27.2 The Current Buffer.

Command: scroll-up &optional count
This function scrolls the text in the selected window upward count lines. If count is negative, scrolling is actually downward.

If count is nil (or omitted), then the length of scroll is next-screen-context-lines lines less than the usable height of the window (not counting its mode line).

scroll-up returns nil.

Command: scroll-down &optional count
This function scrolls the text in the selected window downward count lines. If count is negative, scrolling is actually upward.

If count is omitted or nil, then the length of the scroll is next-screen-context-lines lines less than the usable height of the window (not counting its mode line).

scroll-down returns nil.

Command: scroll-other-window &optional count
This function scrolls the text in another window upward count lines. Negative values of count, or nil, are handled as in scroll-up.

You can specify which buffer to scroll by setting the variable other-window-scroll-buffer to a buffer. If that buffer isn't already displayed, scroll-other-window displays it in some window.

When the selected window is the minibuffer, the next window is normally the one at the top left corner. You can specify a different window to scroll, when the minibuffer is selected, by setting the variable minibuffer-scroll-window. This variable has no effect when any other window is selected. See section 20.9 Minibuffer Miscellany.

When the minibuffer is active, it is the next window if the selected window is the one at the bottom right corner. In this case, scroll-other-window attempts to scroll the minibuffer. If the minibuffer contains just one line, it has nowhere to scroll to, so the line reappears after the echo area momentarily displays the message "Beginning of buffer".

Variable: other-window-scroll-buffer
If this variable is non-nil, it tells scroll-other-window which buffer to scroll.

User Option: scroll-margin
This option specifies the size of the scroll margin--a minimum number of lines between point and the top or bottom of a window. Whenever point gets within this many lines of the top or bottom of the window, the window scrolls automatically (if possible) to move point out of the margin, closer to the center of the window.

User Option: scroll-conservatively
This variable controls how scrolling is done automatically when point moves off the screen (or into the scroll margin). If the value is zero, then redisplay scrolls the text to center point vertically in the window. If the value is a positive integer n, then redisplay scrolls the window up to n lines in either direction, if that will bring point back into view. Otherwise, it centers point. The default value is zero.

User Option: scroll-down-aggressively
The value of this variable should be either nil or a fraction f between 0 and 1. If it is a fraction, that specifies where on the screen to put point when scrolling down. More precisely, when a window scrolls down because point is above the window start, the new start position is chosen to put point f part of the window height from the top. The larger f, the more aggressive the scrolling.

A value of nil is equivalent to .5, since its effect is to center point. This variable automatically becomes buffer-local when set in any fashion.

User Option: scroll-up-aggressively
Likewise, for scrolling up. The value, f, specifies how far point should be placed from the bottom of the window; thus, as with scroll-up-aggressively, a larger value scrolls more aggressively.

User Option: scroll-step
This variable is an older variant of scroll-conservatively. The difference is that it if its value is n, that permits scrolling only by precisely n lines, not a smaller number. This feature does not work with scroll-margin. The default value is zero.

User Option: scroll-preserve-screen-position
If this option is non-nil, the scroll functions move point so that the vertical position of the cursor is unchanged, when that is possible.

User Option: next-screen-context-lines
The value of this variable is the number of lines of continuity to retain when scrolling by full screens. For example, scroll-up with an argument of nil scrolls so that this many lines at the bottom of the window appear instead at the top. The default value is 2.

Command: recenter &optional count
This function scrolls the selected window to put the text where point is located at a specified vertical position within the window.

If count is a nonnegative number, it puts the line containing point count lines down from the top of the window. If count is a negative number, then it counts upward from the bottom of the window, so that -1 stands for the last usable line in the window. If count is a non-nil list, then it stands for the line in the middle of the window.

If count is nil, recenter puts the line containing point in the middle of the window, then clears and redisplays the entire selected frame.

When recenter is called interactively, count is the raw prefix argument. Thus, typing C-u as the prefix sets the count to a non-nil list, while typing C-u 4 sets count to 4, which positions the current line four lines from the top.

With an argument of zero, recenter positions the current line at the top of the window. This action is so handy that some people make a separate key binding to do this. For example,
(defun line-to-top-of-window ()
  "Scroll current line to top of window.
Replaces three keystroke sequence C-u 0 C-l."
  (interactive)
  (recenter 0))

(global-set-key [kp-multiply] 'line-to-top-of-window)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.12 Vertical Fractional Scrolling

Vertical fractional scrolling means shifting the image in the window up or down by a specified multiple or fraction of a line. Starting in Emacs 21, each window has a vertical scroll position, which is a number, never less than zero. It specifies how far to raise the contents of the window. Raising the window contents generally makes all or part of some lines disappear off the top, and all or part of some other lines appear at the bottom. The usual value is zero.

The vertical scroll position is measured in units of the normal line height, which is the height of the default font. Thus, if the value is .5, that means the window contents are scrolled up half the normal line height. If it is 3.3, that means the window contents are scrolled up somewhat over three times the normal line height.

What fraction of a line the vertical scrolling covers, or how many lines, depends on what the lines contain. A value of .5 could scroll a line whose height is very short off the screen, while a value of 3.3 could scroll just part of the way through a tall line or an image.

Function: window-vscroll &optional window
This function returns the current vertical scroll position of window, If window is nil, the selected window is used.
(window-vscroll)
     => 0
Function: set-window-vscroll window lines
This function sets window's vertical scroll position to lines. The argument lines should be zero or positive; if not, it is taken as zero.

The actual vertical scroll position must always correspond to an integral number of pixels, so the value you specify is rounded accordingly.

The return value is the result of this rounding.
(set-window-vscroll (selected-window) 1.2)
     => 1.13
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.13 Horizontal Scrolling

Horizontal scrolling means shifting the image in the window left or right by a specified multiple of the normal character width. Each window has a vertical scroll position, which is a number, never less than zero. It specifies how far to shift the contents left. Shifting the window contents left generally makes all or part of some characters disappear off the left, and all or part of some other characters appear at the right. The usual value is zero.

The horizontal scroll position is measured in units of the normal character width, which is the width of space in the default font. Thus, if the value is 5, that means the window contents are scrolled left by 5 times the normal character width. How many characters actually disappear off to the left depends on their width, and could vary from line to line.

Because we read from side to side in the "inner loop", and from top to bottom in the "outer loop", the effect of horizontal scrolling is not like that of textual or vertical scrolling. Textual scrolling involves selection of a portion of text to display, and vertical scrolling moves the window contents contiguously; but horizontal scrolling causes part of each line to go off screen.

Usually, no horizontal scrolling is in effect; then the leftmost column is at the left edge of the window. In this state, scrolling to the right is meaningless, since there is no data to the left of the edge to be revealed by it; so this is not allowed. Scrolling to the left is allowed; it scrolls the first columns of text off the edge of the window and can reveal additional columns on the right that were truncated before. Once a window has a nonzero amount of leftward horizontal scrolling, you can scroll it back to the right, but only so far as to reduce the net horizontal scroll to zero. There is no limit to how far left you can scroll, but eventually all the text will disappear off the left edge.

In Emacs 21, redisplay automatically alters the horizontal scrolling of a window as necessary to ensure that point is always visible, if automatic-hscrolling is set. However, you can still set the horizontal scrolling value explicitly. The value you specify serves as a lower bound for automatic scrolling, i.e. automatic scrolling will not scroll a window to a column less than the specified one.

Command: scroll-left &optional count
This function scrolls the selected window count columns to the left (or to the right if count is negative). The default for count is the window width, minus 2.

The return value is the total amount of leftward horizontal scrolling in effect after the change--just like the value returned by window-hscroll (below).

Command: scroll-right &optional count
This function scrolls the selected window count columns to the right (or to the left if count is negative). The default for count is the window width, minus 2.

The return value is the total amount of leftward horizontal scrolling in effect after the change--just like the value returned by window-hscroll (below).

Once you scroll a window as far right as it can go, back to its normal position where the total leftward scrolling is zero, attempts to scroll any farther right have no effect.

Function: window-hscroll &optional window
This function returns the total leftward horizontal scrolling of window---the number of columns by which the text in window is scrolled left past the left margin.

The value is never negative. It is zero when no horizontal scrolling has been done in window (which is usually the case).

If window is nil, the selected window is used.
(window-hscroll)
     => 0
(scroll-left 5)
     => 5
(window-hscroll)
     => 5
Function: set-window-hscroll window columns
This function sets the number of columns from the left margin that window is scrolled from the value of columns. The argument columns should be zero or positive; if not, it is taken as zero. Fractional values of columns are not supported at present.

The value returned is columns.
(set-window-hscroll (selected-window) 10)
     => 10
Here is how you can determine whether a given position position is off the screen due to horizontal scrolling:
(defun hscroll-on-screen (window position)
  (save-excursion
    (goto-char position)
    (and
     (>= (- (current-column) (window-hscroll window)) 0)
     (< (- (current-column) (window-hscroll window))
        (window-width window)))))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.14 The Size of a Window

An Emacs window is rectangular, and its size information consists of the height (the number of lines) and the width (the number of character positions in each line). The mode line is included in the height. But the width does not count the scroll bar or the column of `|' characters that separates side-by-side windows.

The following three functions return size information about a window:

Function: window-height &optional window
This function returns the number of lines in window, including its mode line. If window fills its entire frame, this is typically one less than the value of frame-height on that frame (since the last line is always reserved for the minibuffer).

If window is nil, the function uses the selected window.
(window-height)
     => 23
(split-window-vertically)
     => #<window 4 on windows.texi>
(window-height)
     => 11
Function: window-width &optional window
This function returns the number of columns in window. If window fills its entire frame, this is the same as the value of frame-width on that frame. The width does not include the window's scroll bar or the column of `|' characters that separates side-by-side windows.

If window is nil, the function uses the selected window.
(window-width)
     => 80
Function: window-edges &optional window
This function returns a list of the edge coordinates of window. If window is nil, the selected window is used.

The order of the list is (left top right bottom), all elements relative to 0, 0 at the top left corner of the frame. The element right of the value is one more than the rightmost column used by window, and bottom is one more than the bottommost row used by window and its mode-line.

If a window has a scroll bar, the right edge value includes the width of the scroll bar. Otherwise, if the window has a neighbor on the right, its right edge value includes the width of the separator line between the window and that neighbor. Since the width of the window does not include this separator, the width does not usually equal the difference between the right and left edges.

Here is the result obtained on a typical 24-line terminal with just one window:
(window-edges (selected-window))
     => (0 0 80 23)
The bottom edge is at line 23 because the last line is the echo area.

If window is at the upper left corner of its frame, then bottom is the same as the value of (window-height), right is almost the same as the value of (window-width), and top and left are zero. For example, the edges of the following window are `0 0 8 5'. Assuming that the frame has more than 8 columns, the last column of the window (column 7) holds a border rather than text. The last row (row 4) holds the mode line, shown here with `xxxxxxxxx'.
           0
           _______
        0 |       |
          |       |
          |       |
          |       |
          xxxxxxxxx  4

                  7
In the following example, let's suppose that the frame is 7 columns wide. Then the edges of the left window are `0 0 4 3' and the edges of the right window are `4 0 8 3'.
           ___ ___
          |   |   |
          |   |   |
          xxxxxxxxx

           0  34  7
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.15 Changing the Size of a Window

The window size functions fall into two classes: high-level commands that change the size of windows and low-level functions that access window size. Emacs does not permit overlapping windows or gaps between windows, so resizing one window affects other windows.

Command: enlarge-window size &optional horizontal
This function makes the selected window size lines taller, stealing lines from neighboring windows. It takes the lines from one window at a time until that window is used up, then takes from another. If a window from which lines are stolen shrinks below window-min-height lines, that window disappears.

If horizontal is non-nil, this function makes window wider by size columns, stealing columns instead of lines. If a window from which columns are stolen shrinks below window-min-width columns, that window disappears.

If the requested size would exceed that of the window's frame, then the function makes the window occupy the entire height (or width) of the frame.

If there are various other windows from which lines or columns can be stolen, and some of them specify fixed size (using window-size-fixed, see below), they are left untouched while other windows are "robbed." If it would be necessary to alter the size of a fixed-size window, enlarge-window gets an error instead.

If size is negative, this function shrinks the window by -size lines or columns. If that makes the window smaller than the minimum size (window-min-height and window-min-width), enlarge-window deletes the window.

enlarge-window returns nil.

Command: enlarge-window-horizontally columns
This function makes the selected window columns wider. It could be defined as follows:
(defun enlarge-window-horizontally (columns)
  (enlarge-window columns t))
Command: shrink-window size &optional horizontal
This function is like enlarge-window but negates the argument size, making the selected window smaller by giving lines (or columns) to the other windows. If the window shrinks below window-min-height or window-min-width, then it disappears.

If size is negative, the window is enlarged by -size lines or columns.

Command: shrink-window-horizontally columns
This function makes the selected window columns narrower. It could be defined as follows:
(defun shrink-window-horizontally (columns)
  (shrink-window columns t))
Command: shrink-window-if-larger-than-buffer &optional window
This command shrinks window to be as small as possible while still showing the full contents of its buffer--but not less than window-min-height lines. If window is not given, it defaults to the selected window.

However, the command does nothing if the window is already too small to display the whole text of the buffer, or if part of the contents are currently scrolled off screen, or if the window is not the full width of its frame, or if the window is the only window in its frame.

Variable: window-size-fixed
If this variable is non-nil, in any given buffer, then the size of any window displaying the buffer remains fixed unless you explicitly change it or Emacs has no other choice. (This feature is new in Emacs 21.)

If the value is height, then only the window's height is fixed; if the value is width, then only the window's width is fixed. Any other non-nil value fixes both the width and the height.

The usual way to use this variable is to give it a buffer-local value in a particular buffer. That way, the windows (but usually there is only one) displaying that buffer have fixed size.

Explicit size-change functions such as enlarge-window get an error if they would have to change a window size which is fixed. Therefore, when you want to change the size of such a window, you should bind window-size-fixed to nil, like this:
(let ((window-size-fixed nil))
   (enlarge-window 10))
Note that changing the frame size will change the size of a fixed-size window, if there is no other alternative.

The following two variables constrain the window-size-changing functions to a minimum height and width.

User Option: window-min-height
The value of this variable determines how short a window may become before it is automatically deleted. Making a window smaller than window-min-height automatically deletes it, and no window may be created shorter than this. The absolute minimum height is two (allowing one line for the mode line, and one line for the buffer display). Actions that change window sizes reset this variable to two if it is less than two. The default value is 4.

User Option: window-min-width
The value of this variable determines how narrow a window may become before it is automatically deleted. Making a window smaller than window-min-width automatically deletes it, and no window may be created narrower than this. The absolute minimum width is one; any value below that is ignored. The default value is 10.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.16 Coordinates and Windows

This section describes how to relate screen coordinates to windows.

Function: window-at x y &optional frame
This function returns the window containing the specified cursor position in the frame frame. The coordinates x and y are measured in characters and count from the top left corner of the frame. If they are out of range, window-at returns nil.

If you omit frame, the selected frame is used.

Function: coordinates-in-window-p coordinates window
This function checks whether a particular frame position falls within the window window.

The argument coordinates is a cons cell of the form (x . y). The coordinates x and y are measured in characters, and count from the top left corner of the screen or frame.

The value returned by coordinates-in-window-p is non-nil if the coordinates are inside window. The value also indicates what part of the window the position is in, as follows:

(relx . rely)
The coordinates are inside window. The numbers relx and rely are the equivalent window-relative coordinates for the specified position, counting from 0 at the top left corner of the window.

mode-line
The coordinates are in the mode line of window.

header-line
The coordinates are in the header line of window.

vertical-line
The coordinates are in the vertical line between window and its neighbor to the right. This value occurs only if the window doesn't have a scroll bar; positions in a scroll bar are considered outside the window for these purposes.

nil
The coordinates are not in any part of window.
The function coordinates-in-window-p does not require a frame as argument because it always uses the frame that window is on.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.17 Window Configurations

A window configuration records the entire layout of one frame--all windows, their sizes, which buffers they contain, what part of each buffer is displayed, and the values of point and the mark. You can bring back an entire previous layout by restoring a window configuration previously saved.

If you want to record all frames instead of just one, use a frame configuration instead of a window configuration. See section 29.12 Frame Configurations.

Function: current-window-configuration &optional frame
This function returns a new object representing frame's current window configuration, including the number of windows, their sizes and current buffers, which window is the selected window, and for each window the displayed buffer, the display-start position, and the positions of point and the mark. It also includes the values of window-min-height, window-min-width and minibuffer-scroll-window. An exception is made for point in the current buffer, whose value is not saved.

If frame is omitted, the selected frame is used.

Function: set-window-configuration configuration
This function restores the configuration of windows and buffers as specified by configuration, for the frame that configuration was created for.

The argument configuration must be a value that was previously returned by current-window-configuration. This configuration is restored in the frame from which configuration was made, whether that frame is selected or not. This always counts as a window size change and triggers execution of the window-size-change-functions (see section 28.18 Hooks for Window Scrolling and Changes), because set-window-configuration doesn't know how to tell whether the new configuration actually differs from the old one.

If the frame which configuration was saved from is dead, all this function does is restore the three variables window-min-height, window-min-width and minibuffer-scroll-window.

Here is a way of using this function to get the same effect as save-window-excursion:
(let ((config (current-window-configuration)))
  (unwind-protect
      (progn (split-window-vertically nil)
             ...)
    (set-window-configuration config)))
Special Form: save-window-excursion forms...
This special form records the window configuration, executes forms in sequence, then restores the earlier window configuration. The window configuration includes the value of point and the portion of the buffer that is visible. It also includes the choice of selected window. However, it does not include the value of point in the current buffer; use save-excursion also, if you wish to preserve that.

Don't use this construct when save-selected-window is all you need.

Exit from save-window-excursion always triggers execution of the window-size-change-functions. (It doesn't know how to tell whether the restored configuration actually differs from the one in effect at the end of the forms.)

The return value is the value of the final form in forms. For example:
(split-window)
     => #<window 25 on control.texi>
(setq w (selected-window))
     => #<window 19 on control.texi>
(save-window-excursion
  (delete-other-windows w)
  (switch-to-buffer "foo")
  'do-something)
     => do-something
     ;; The screen is now split again.
Function: window-configuration-p object
This function returns t if object is a window configuration.

Function: compare-window-configurations config1 config2
This function compares two window configurations as regards the structure of windows, but ignores the values of point and mark and the saved scrolling positions--it can return t even if those aspects differ.

The function equal can also compare two window configurations; it regards configurations as unequal if they differ in any respect, even a saved point or mark.

Primitives to look inside of window configurations would make sense, but none are implemented. It is not clear they are useful enough to be worth implementing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

28.18 Hooks for Window Scrolling and Changes

This section describes how a Lisp program can take action whenever a window displays a different part of its buffer or a different buffer. There are three actions that can change this: scrolling the window, switching buffers in the window, and changing the size of the window. The first two actions run window-scroll-functions; the last runs window-size-change-functions. The paradigmatic use of these hooks is in the implementation of Lazy Lock mode; see section `Font Lock Support Modes' in The GNU Emacs Manual.

Variable: window-scroll-functions
This variable holds a list of functions that Emacs should call before redisplaying a window with scrolling. It is not a normal hook, because each function is called with two arguments: the window, and its new display-start position.

Displaying a different buffer in the window also runs these functions.

These functions must be careful in using window-end (see section 28.10 The Window Start Position); if you need an up-to-date value, you must use the update argument to ensure you get it.

Variable: window-size-change-functions
This variable holds a list of functions to be called if the size of any window changes for any reason. The functions are called just once per redisplay, and just once for each frame on which size changes have occurred.

Each function receives the frame as its sole argument. There is no direct way to find out which windows on that frame have changed size, or precisely how. However, if a size-change function records, at each call, the existing windows and their sizes, it can also compare the present sizes and the previous sizes.

Creating or deleting windows counts as a size change, and therefore causes these functions to be called. Changing the frame size also counts, because it changes the sizes of the existing windows.

It is not a good idea to use save-window-excursion (see section 28.17 Window Configurations) in these functions, because that always counts as a size change, and it would cause these functions to be called over and over. In most cases, save-selected-window (see section 28.4 Selecting Windows) is what you need here.

Variable: redisplay-end-trigger-functions
This abnormal hook is run whenever redisplay in a window uses text that extends past a specified end trigger position. You set the end trigger position with the function set-window-redisplay-end-trigger. The functions are called with two arguments: the window, and the end trigger position. Storing nil for the end trigger position turns off the feature, and the trigger value is automatically reset to nil just after the hook is run.

Function: set-window-redisplay-end-trigger window position
This function sets window's end trigger position at position.

Function: window-redisplay-end-trigger &optional window
This function returns window's current end trigger position.

Variable: window-configuration-change-hook
A normal hook that is run every time you change the window configuration of an existing frame. This includes splitting or deleting windows, changing the sizes of windows, or displaying a different buffer in a window. The frame whose window configuration has changed is the selected frame when this hook runs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29. Frames

A frame is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window), which you can subdivide vertically or horizontally into smaller windows.

When Emacs runs on a text-only terminal, it starts with one terminal frame. If you create additional ones, Emacs displays one and only one at any given time--on the terminal screen, of course.

When Emacs communicates directly with a supported window system, such as X, it does not have a terminal frame; instead, it starts with a single window frame, but you can create more, and Emacs can display several such frames at once as is usual for window systems.

Function: framep object
This predicate returns a non-nil value if object is a frame, and nil otherwise. For a frame, the value indicates which kind of display the frame uses:

x
The frame is displayed in an X window.
t
A terminal frame on a character display.
mac
The frame is displayed on a Macintosh.
w32
The frame is displayed on MS-Windows 9X/NT.
pc
The frame is displayed on an MS-DOS terminal.

29.1 Creating Frames

Creating additional frames.

29.2 Multiple Displays

Creating frames on other displays.

29.3 Frame Parameters

Controlling frame size, position, font, etc.

29.4 Frame Titles

Automatic updating of frame titles.

29.5 Deleting Frames

Frames last until explicitly deleted.

29.6 Finding All Frames

How to examine all existing frames.

29.7 Frames and Windows

A frame contains windows; display of text always works through windows.

29.8 Minibuffers and Frames

How a frame finds the minibuffer to use.

29.9 Input Focus

Specifying the selected frame.

29.10 Visibility of Frames

Frames may be visible or invisible, or icons.

29.11 Raising and Lowering Frames

Raising a frame makes it hide other windows; lowering it makes the others hide them.

29.12 Frame Configurations

Saving the state of all frames.

29.13 Mouse Tracking

Getting events that say when the mouse moves.

29.14 Mouse Position

Asking where the mouse is, or moving it.

29.15 Pop-Up Menus

Displaying a menu for the user to select from.

29.16 Dialog Boxes

Displaying a box to ask yes or no.

29.17 Pointer Shapes

Specifying the shape of the mouse pointer.

29.18 Window System Selections

Transferring text to and from other X clients.

29.19 Color Names

Getting the definitions of color names.

29.20 Text Terminal Colors

Defining colors for text-only terminals.

29.21 X Resources

Getting resource values from the server.

29.22 Display Feature Testing

Determining the features of a terminal.

See section 38. Emacs Display, for information about the related topic of controlling Emacs redisplay.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.1 Creating Frames

To create a new frame, call the function make-frame.

Function: make-frame &optional alist
This function creates a new frame. If you are using a supported window system, it makes a window frame; otherwise, it makes a terminal frame.

The argument is an alist specifying frame parameters. Any parameters not mentioned in alist default according to the value of the variable default-frame-alist; parameters not specified even there default from the standard X resources or whatever is used instead on your system.

The set of possible parameters depends in principle on what kind of window system Emacs uses to display its frames. See section 29.3.3 Window Frame Parameters, for documentation of individual parameters you can specify.

Variable: before-make-frame-hook
A normal hook run by make-frame before it actually creates the frame.

Variable: after-make-frame-functions
An abnormal hook run by make-frame after it creates the frame. Each function in after-make-frame-functions receives one argument, the frame just created.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.2 Multiple Displays

A single Emacs can talk to more than one X display. Initially, Emacs uses just one display--the one chosen with the DISPLAY environment variable or with the `--display' option (see section `Initial Options' in The GNU Emacs Manual). To connect to another display, use the command make-frame-on-display or specify the display frame parameter when you create the frame.

Emacs treats each X server as a separate terminal, giving each one its own selected frame and its own minibuffer windows. However, only one of those frames is "the selected frame" at any given moment, see 29.9 Input Focus.

A few Lisp variables are terminal-local; that is, they have a separate binding for each terminal. The binding in effect at any time is the one for the terminal that the currently selected frame belongs to. These variables include default-minibuffer-frame, defining-kbd-macro, last-kbd-macro, and system-key-alist. They are always terminal-local, and can never be buffer-local (see section 11.10 Buffer-Local Variables) or frame-local.

A single X server can handle more than one screen. A display name `host:server.screen' has three parts; the last part specifies the screen number for a given server. When you use two screens belonging to one server, Emacs knows by the similarity in their names that they share a single keyboard, and it treats them as a single terminal.

Command: make-frame-on-display display &optional parameters
This creates a new frame on display display, taking the other frame parameters from parameters. Aside from the display argument, it is like make-frame (see section 29.1 Creating Frames).

Function: x-display-list
This returns a list that indicates which X displays Emacs has a connection to. The elements of the list are strings, and each one is a display name.

Function: x-open-connection display &optional xrm-string must-succeed
This function opens a connection to the X display display. It does not create a frame on that display, but it permits you to check that communication can be established with that display.

The optional argument xrm-string, if not nil, is a string of resource names and values, in the same format used in the `.Xresources' file. The values you specify override the resource values recorded in the X server itself; they apply to all Emacs frames created on this display. Here's an example of what this string might look like:
"*BorderWidth: 3\n*InternalBorder: 2\n"
See section 29.21 X Resources.

If must-succeed is non-nil, failure to open the connection terminates Emacs. Otherwise, it is an ordinary Lisp error.

Function: x-close-connection display
This function closes the connection to display display. Before you can do this, you must first delete all the frames that were open on that display (see section 29.5 Deleting Frames).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.3 Frame Parameters

A frame has many parameters that control its appearance and behavior. Just what parameters a frame has depends on what display mechanism it uses.

Frame parameters exist mostly for the sake of window systems. A terminal frame has a few parameters, mostly for compatibility's sake; only the height, width, name, title, menu-bar-lines, buffer-list and buffer-predicate parameters do something special. If the terminal supports colors, the parameters foreground-color, background-color, background-mode and display-type are also meaningful.

29.3.1 Access to Frame Parameters

How to change a frame's parameters.

29.3.2 Initial Frame Parameters

Specifying frame parameters when you make a frame.

29.3.3 Window Frame Parameters

List of frame parameters for window systems.

29.3.4 Frame Size And Position

Changing the size and position of a frame.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.3.1 Access to Frame Parameters

These functions let you read and change the parameter values of a frame.

Function: frame-parameter frame parameter
This function returns the value of the parameter named parameter of frame. If frame is nil, it returns the selected frame's parameter.

Function: frame-parameters frame
The function frame-parameters returns an alist listing all the parameters of frame and their values.

Function: modify-frame-parameters frame alist
This function alters the parameters of frame frame based on the elements of alist. Each element of alist has the form (parm . value), where parm is a symbol naming a parameter. If you don't mention a parameter in alist, its value doesn't change.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.3.2 Initial Frame Parameters

You can specify the parameters for the initial startup frame by setting initial-frame-alist in your init file (see section 40.1.2 The Init File, `.emacs').

Variable: initial-frame-alist
This variable's value is an alist of parameter values used when creating the initial window frame. You can set this variable to specify the appearance of the initial frame without altering subsequent frames. Each element has the form:
(parameter . value)
Emacs creates the initial frame before it reads your init file. After reading that file, Emacs checks initial-frame-alist, and applies the parameter settings in the altered value to the already created initial frame.

If these settings affect the frame geometry and appearance, you'll see the frame appear with the wrong ones and then change to the specified ones. If that bothers you, you can specify the same geometry and appearance with X resources; those do take effect before the frame is created. See section `X Resources' in The GNU Emacs Manual.

X resource settings typically apply to all frames. If you want to specify some X resources solely for the sake of the initial frame, and you don't want them to apply to subsequent frames, here's how to achieve this. Specify parameters in default-frame-alist to override the X resources for subsequent frames; then, to prevent these from affecting the initial frame, specify the same parameters in initial-frame-alist with values that match the X resources.

If these parameters specify a separate minibuffer-only frame with (minibuffer . nil), and you have not created one, Emacs creates one for you.

Variable: minibuffer-frame-alist
This variable's value is an alist of parameter values used when creating an initial minibuffer-only frame--if such a frame is needed, according to the parameters for the main initial frame.

Variable: default-frame-alist
This is an alist specifying default values of frame parameters for all Emacs frames--the first frame, and subsequent frames. When using the X Window System, you can get the same results by means of X resources in many cases.

See also special-display-frame-alist, in 28.8 Choosing a Window for Display.

If you use options that specify window appearance when you invoke Emacs, they take effect by adding elements to default-frame-alist. One exception is `-geometry', which adds the specified position to initial-frame-alist instead. See section `Command Arguments' in The GNU Emacs Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.3.3 Window Frame Parameters

Just what parameters a frame has depends on what display mechanism it uses. Here is a table of the parameters that have special meanings in a window frame; of these, name, title, height, width, buffer-list and buffer-predicate provide meaningful information in terminal frames.

display
The display on which to open this frame. It should be a string of the form "host:dpy.screen", just like the DISPLAY environment variable.

title
If a frame has a non-nil title, it appears in the window system's border for the frame, and also in the mode line of windows in that frame if mode-line-frame-identification uses `%F' (see section 23.3.3 %-Constructs in the Mode Line). This is normally the case when Emacs is not using a window system, and can only display one frame at a time. See section 29.4 Frame Titles.

name
The name of the frame. The frame name serves as a default for the frame title, if the title parameter is unspecified or nil. If you don't specify a name, Emacs sets the frame name automatically (see section 29.4 Frame Titles).
If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame.

left
The screen position of the left edge, in pixels, with respect to the left edge of the screen. The value may be a positive number pos, or a list of the form (+ pos) which permits specifying a negative pos value.
A negative number -pos, or a list of the form (- pos), actually specifies the position of the right edge of the window with respect to the right edge of the screen. A positive value of pos counts toward the left. Reminder: if the parameter is a negative integer -pos, then pos is positive.

Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as well.

top
The screen position of the top edge, in pixels, with respect to the top edge of the screen. The value may be a positive number pos, or a list of the form (+ pos) which permits specifying a negative pos value.
A negative number -pos, or a list of the form (- pos), actually specifies the position of the bottom edge of the window with respect to the bottom edge of the screen. A positive value of pos counts toward the top. Reminder: if the parameter is a negative integer -pos, then pos is positive.

Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as well.

icon-left
The screen position of the left edge of the frame's icon, in pixels, counting from the left edge of the screen. This takes effect if and when the frame is iconified.

icon-top
The screen position of the top edge of the frame's icon, in pixels, counting from the top edge of the screen. This takes effect if and when the frame is iconified.

user-position
When you create a frame and specify its screen position with the left and top parameters, use this parameter to say whether the specified position was user-specified (explicitly requested in some way by a human user) or merely program-specified (chosen by a program). A non-nil value says the position was user-specified.
Window managers generally heed user-specified positions, and some heed program-specified positions too. But many ignore program-specified positions, placing the window in a default fashion or letting the user place it with the mouse. Some window managers, including twm, let the user specify whether to obey program-specified positions or ignore them.

When you call make-frame, you should specify a non-nil value for this parameter if the values of the left and top parameters represent the user's stated preference; otherwise, use nil.

height
The height of the frame contents, in characters. (To get the height in pixels, call frame-pixel-height; see 29.3.4 Frame Size And Position.)

width
The width of the frame contents, in characters. (To get the height in pixels, call frame-pixel-width; see 29.3.4 Frame Size And Position.)

window-id
The number of the window-system window used by the frame to contain the actual Emacs windows.

outer-window-id
The number of the outermost window-system window used for the whole frame.

minibuffer
Whether this frame has its own minibuffer. The value t means yes, nil means no, only means this frame is just a minibuffer. If the value is a minibuffer window (in some other frame), the new frame uses that minibuffer.

buffer-predicate
The buffer-predicate function for this frame. The function other-buffer uses this predicate (from the selected frame) to decide which buffers it should consider, if the predicate is not nil. It calls the predicate with one argument, a buffer, once for each buffer; if the predicate returns a non-nil value, it considers that buffer.

buffer-list
A list of buffers that have been selected in this frame, ordered most-recently-selected first.

font
The name of the font for displaying text in the frame. This is a string, either a valid font name for your system or the name of an Emacs fontset (see section 38.11.10 Fontsets). Changing this frame parameter on a frame also changes the font-related attributes of the default face on that frame.

auto-raise
Whether selecting the frame raises it (non-nil means yes).

auto-lower
Whether deselecting the frame lowers it (non-nil means yes).

vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are left, right, and nil for no scroll bars.

horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling (non-nil means yes). (Horizontal scroll bars are not currently implemented.)

scroll-bar-width
The width of the vertical scroll bar, in pixels.

icon-type
The type of icon to use for this frame when it is iconified. If the value is a string, that specifies a file containing a bitmap to use. Any other non-nil value specifies the default bitmap icon (a picture of a gnu); nil specifies a text icon.

icon-name
The name to use in the icon for this frame, when and if the icon appears. If this is nil, the frame's title is used.

foreground-color
The color to use for the image of a character. This is a string; the window system defines the meaningful color names. Changing this parameter is equivalent to changing the foreground color of the face default on the frame in question.

background-color
The color to use for the background of characters. Changing this parameter is equivalent to changing the foreground color of the face default on the frame in question.

background-mode
This parameter is either dark or light, according to whether the background color is a light one or a dark one.

mouse-color
The color for the mouse pointer. Changing this parameter is equivalent to changing the background color of face mouse.

cursor-color
The color for the cursor that shows point. Changing this parameter is equivalent to changing the background color of face cursor.

border-color
The color for the border of the frame. Changing this parameter is equivalent to changing the background color of face border.

scroll-bar-foreground
If non-nil, the color for the foreground of scroll bars. Changing this parameter is equivalent to setting the foreground color of face scroll-bar.

scroll-bar-background
If non-nil, the color for the background of scroll bars. Changing this parameter is equivalent to setting the foreground color of face scroll-bar.

display-type
This parameter describes the range of possible colors that can be used in this frame. Its value is color, grayscale or mono.

cursor-type
The way to display the cursor. The legitimate values are bar, box, and (bar . width). The symbol box specifies an ordinary black box overlaying the character after point; that is the default. The symbol bar specifies a vertical bar between characters as the cursor. (bar . width) specifies a bar width pixels wide.
The buffer-local variable cursor-type overrides the value of the cursor-type frame parameter, and can in addition have values t (use the cursor specified for the frame) and nil (don't display a cursor).

border-width
The width in pixels of the window border.

internal-border-width
The distance in pixels between text and border.

unsplittable
If non-nil, this frame's window is never split automatically.

visibility
The state of visibility of the frame. There are three possibilities: nil for invisible, t for visible, and icon for iconified. See section 29.10 Visibility of Frames.

menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar. The default is 1. See section 22.12.5 The Menu Bar. (In Emacs versions that use the X toolkit, there is only one menu bar line; all that matters about the number you specify is whether it is greater than zero.)

screen-gamma
If this is a number, Emacs performs "gamma correction" on colors. The value should be the screen gamma of your display, a floating point number. Usual PC monitors have a screen gamma of 2.2, so the default is to display for that gamma value. Specifying a smaller value results in darker colors, which is desirable for a monitor that tends to display colors too light. A screen gamma value of 1.5 may give good results for LCD color displays.

tool-bar-lines
The number of lines to use for the toolbar. A value of nil means don't display a tool bar.

line-spacing
Additional space put below text lines in pixels (a positive integer).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.3.4 Frame Size And Position

You can read or change the size and position of a frame using the frame parameters left, top, height, and width. Whatever geometry parameters you don't specify are chosen by the window manager in its usual fashion.

Here are some special features for working with sizes and positions. (For the precise meaning of "selected frame" used by these functions, see 29.9 Input Focus.)

Function: set-frame-position frame left top
This function sets the position of the top left corner of frame to left and top. These arguments are measured in pixels, and normally count from the top left corner of the screen.

Negative parameter values position the bottom edge of the window up from the bottom edge of the screen, or the right window edge to the left of the right edge of the screen. It would probably be better if the values were always counted from the left and top, so that negative arguments would position the frame partly off the top or left edge of the screen, but it seems inadvisable to change that now.

Function: frame-height &optional frame

Function: frame-width &optional frame
These functions return the height and width of frame, measured in lines and columns. If you don't supply frame, they use the selected frame.

Function: screen-height

Function: screen-width
These functions are old aliases for frame-height and frame-width. When you are using a non-window terminal, the size of the frame is normally the same as the size of the terminal screen.

Function: frame-pixel-height &optional frame

Function: frame-pixel-width &optional frame
These functions return the height and width of frame, measured in pixels. If you don't supply frame, they use the selected frame.

Function: frame-char-height &optional frame

Function: frame-char-width &optional frame
These functions return the height and width of a character in frame, measured in pixels. The values depend on the choice of font. If you don't supply frame, these functions use the selected frame.

Function: set-frame-size frame cols rows
This function sets the size of frame, measured in characters; cols and rows specify the new width and height.

To set the size based on values measured in pixels, use frame-char-height and frame-char-width to convert them to units of characters.

Function: set-frame-height frame lines &optional pretend
This function resizes frame to a height of lines lines. The sizes of existing windows in frame are altered proportionally to fit.

If pretend is non-nil, then Emacs displays lines lines of output in frame, but does not change its value for the actual height of the frame. This is only useful for a terminal frame. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame height "for real" does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on a terminal frame.

Function: set-frame-width frame width &optional pretend
This function sets the width of frame, measured in characters. The argument pretend has the same meaning as in set-frame-height.

The older functions set-screen-height and set-screen-width were used to specify the height and width of the screen, in Emacs versions that did not support multiple frames. They are semi-obsolete, but still work; they apply to the selected frame.

Function: x-parse-geometry geom
The function x-parse-geometry converts a standard X window geometry string to an alist that you can use as part of the argument to make-frame.

The alist describes which parameters were specified in geom, and gives the values specified for them. Each element looks like (parameter . value). The possible parameter values are left, top, width, and height.

For the size parameters, the value must be an integer. The position parameter names left and top are not totally accurate, because some values indicate the position of the right or bottom edges instead. These are the value possibilities for the position parameters:

an integer
A positive integer relates the left edge or top edge of the window to the left or top edge of the screen. A negative integer relates the right or bottom edge of the window to the right or bottom edge of the screen.

(+ position)
This specifies the position of the left or top edge of the window relative to the left or top edge of the screen. The integer position may be positive or negative; a negative value specifies a position outside the screen.

(- position)
This specifies the position of the right or bottom edge of the window relative to the right or bottom edge of the screen. The integer position may be positive or negative; a negative value specifies a position outside the screen.
Here is an example:
(x-parse-geometry "35x70+0-0")
     => ((height . 70) (width . 35)
         (top - 0) (left . 0))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.4 Frame Titles

Every frame has a name parameter; this serves as the default for the frame title which window systems typically display at the top of the frame. You can specify a name explicitly by setting the name frame property.

Normally you don't specify the name explicitly, and Emacs computes the frame name automatically based on a template stored in the variable frame-title-format. Emacs recomputes the name each time the frame is redisplayed.

Variable: frame-title-format
This variable specifies how to compute a name for a frame when you have not explicitly specified one. The variable's value is actually a mode line construct, just like mode-line-format. See section 23.3.1 The Data Structure of the Mode Line.

Variable: icon-title-format
This variable specifies how to compute the name for an iconified frame, when you have not explicitly specified the frame title. This title appears in the icon itself.

Variable: multiple-frames
This variable is set automatically by Emacs. Its value is t when there are two or more frames (not counting minibuffer-only frames or invisible frames). The default value of frame-title-format uses multiple-frames so as to put the buffer name in the frame title only when there is more than one frame.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.5 Deleting Frames

Frames remain potentially visible until you explicitly delete them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a frame aside from restoring a saved frame configuration (see section 29.12 Frame Configurations); this is similar to the way windows behave.

Command: delete-frame &optional frame force
This function deletes the frame frame after running the hook delete-frame-hook. By default, frame is the selected frame.

A frame cannot be deleted if its minibuffer is used by other frames. Normally, you cannot delete a frame if all other frames are invisible, but if the force is non-nil, then you are allowed to do so.

Function: frame-live-p frame
The function frame-live-p returns non-nil if the frame frame has not been deleted.

Some window managers provide a command to delete a window. These work by sending a special message to the program that operates the window. When Emacs gets one of these commands, it generates a delete-frame event, whose normal definition is a command that calls the function delete-frame. See section 21.6.10 Miscellaneous Window System Events.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.6 Finding All Frames

Function: frame-list
The function frame-list returns a list of all the frames that have not been deleted. It is analogous to buffer-list for buffers, and includes frames on all terminals. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of Emacs.

Function: visible-frame-list
This function returns a list of just the currently visible frames. See section 29.10 Visibility of Frames. (Terminal frames always count as "visible", even though only the selected one is actually displayed.)

Function: next-frame &optional frame minibuf
The function next-frame lets you cycle conveniently through all the frames on the current display from an arbitrary starting point. It returns the "next" frame after frame in the cycle. If frame is omitted or nil, it defaults to the selected frame (see section 29.9 Input Focus).

The second argument, minibuf, says which frames to consider:

nil
Exclude minibuffer-only frames.
visible
Consider all visible frames.
0
Consider all visible or iconified frames.
a window
Consider only the frames using that particular window as their minibuffer.
anything else
Consider all frames.

Function: previous-frame &optional frame minibuf
Like next-frame, but cycles through all frames in the opposite direction.

See also next-window and previous-window, in 28.5 Cyclic Ordering of Windows.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.7 Frames and Windows

Each window is part of one and only one frame; you can get the frame with window-frame.

Function: window-frame window
This function returns the frame that window is on.

All the non-minibuffer windows in a frame are arranged in a cyclic order. The order runs from the frame's top window, which is at the upper left corner, down and to the right, until it reaches the window at the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top. See section 28.5 Cyclic Ordering of Windows.

Function: frame-first-window frame
This returns the topmost, leftmost window of frame frame.

At any time, exactly one window on any frame is selected within the frame. The significance of this designation is that selecting the frame also selects this window. You can get the frame's current selected window with frame-selected-window.

Function: frame-selected-window frame
This function returns the window on frame that is selected within frame.

Conversely, selecting a window for Emacs with select-window also makes that window selected within its frame. See section 28.4 Selecting Windows.

Another function that (usually) returns one of the windows in a given frame is minibuffer-window. See section 20.9 Minibuffer Miscellany.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.8 Minibuffers and Frames

Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. If the frame has a minibuffer, you can get it with minibuffer-window (see section 20.9 Minibuffer Miscellany).

However, you can also create a frame with no minibuffer. Such a frame must use the minibuffer window of some other frame. When you create the frame, you can specify explicitly the minibuffer window to use (in some other frame). If you don't, then the minibuffer is found in the frame which is the value of the variable default-minibuffer-frame. Its value should be a frame that does have a minibuffer.

If you use a minibuffer-only frame, you might want that frame to raise when you enter the minibuffer. If so, set the variable minibuffer-auto-raise to t. See section 29.11 Raising and Lowering Frames.

Variable: default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by default. It is always local to the current terminal and cannot be buffer-local. See section 29.2 Multiple Displays.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.9 Input Focus

At any time, one frame in Emacs is the selected frame. The selected window always resides on the selected frame.

When Emacs displays its frames on several terminals (see section 29.2 Multiple Displays), each terminal has its own selected frame. But only one of these is "the selected frame": it's the frame that belongs to the terminal from which the most recent input came. That is, when Emacs runs a command that came from a certain terminal, the selected frame is the one of that terminal. Since Emacs runs only a single command at any given time, it needs to consider only one selected frame at a time; this frame is what we call the selected frame in this manual. The display on which the selected frame is displayed is the selected frame's display.

Function: selected-frame
This function returns the selected frame.

Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to shift the focus to various window objects. Either way, Emacs automatically keeps track of which frame has the focus.

Lisp programs can also switch frames "temporarily" by calling the function select-frame. This does not alter the window system's concept of focus; rather, it escapes from the window manager's control until that control is somehow reasserted.

When using a text-only terminal, only the selected terminal frame is actually displayed on the terminal. switch-frame is the only way to switch frames, and the change lasts until overridden by a subsequent call to switch-frame. Each terminal screen except for the initial one has a number, and the number of the selected frame appears in the mode line before the buffer name (see section 23.3.2 Variables Used in the Mode Line).

Function: select-frame frame
This function selects frame frame, temporarily disregarding the focus of the X server if any. The selection of frame lasts until the next time the user does something to select a different frame, or until the next time this function is called. The specified frame becomes the selected frame, as explained above, and the terminal that frame is on becomes the selected terminal.

In general, you should never use select-frame in a way that could switch to a different terminal without switching back when you're done.

Emacs cooperates with the window system by arranging to select frames as the server and window manager request. It does so by generating a special kind of input event, called a focus event, when appropriate. The command loop handles a focus event by calling handle-switch-frame. See section 21.6.9 Focus Events.

Command: handle-switch-frame frame
This function handles a focus event by selecting frame frame.

Focus events normally do their job by invoking this command. Don't call it for any other reason.

Function: redirect-frame-focus frame focus-frame
This function redirects focus from frame to focus-frame. This means that focus-frame will receive subsequent keystrokes and events intended for frame. After such an event, the value of last-event-frame will be focus-frame. Also, switch-frame events specifying frame will instead select focus-frame.

If focus-frame is nil, that cancels any existing redirection for frame, which therefore once again receives its own events.

One use of focus redirection is for frames that don't have minibuffers. These frames use minibuffers on other frames. Activating a minibuffer on another frame redirects focus to that frame. This puts the focus on the minibuffer's frame, where it belongs, even though the mouse remains in the frame that activated the minibuffer.

Selecting a frame can also change focus redirections. Selecting frame bar, when foo had been selected, changes any redirections pointing to foo so that they point to bar instead. This allows focus redirection to work properly when the user switches from one frame to another using select-window.

This means that a frame whose focus is redirected to itself is treated differently from a frame whose focus is not redirected. select-frame affects the former but not the latter.

The redirection lasts until redirect-frame-focus is called to change it.

User Option: focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers focus when the user moves the mouse. Non-nil says that it does. When this is so, the command other-frame moves the mouse to a position consistent with the new selected frame.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.10 Visibility of Frames

A window frame may be visible, invisible, or iconified. If it is visible, you can see its contents. If it is iconified, the frame's contents do not appear on the screen, but an icon does. If the frame is invisible, it doesn't show on the screen, not even as an icon.

Visibility is meaningless for terminal frames, since only the selected one is actually displayed in any case.

Command: make-frame-visible &optional frame
This function makes frame frame visible. If you omit frame, it makes the selected frame visible.

Command: make-frame-invisible &optional frame
This function makes frame frame invisible. If you omit frame, it makes the selected frame invisible.

Command: iconify-frame &optional frame
This function iconifies frame frame. If you omit frame, it iconifies the selected frame.

Function: frame-visible-p frame
This returns the visibility status of frame frame. The value is t if frame is visible, nil if it is invisible, and icon if it is iconified.

The visibility status of a frame is also available as a frame parameter. You can read or change it as such. See section 29.3.3 Window Frame Parameters.

The user can iconify and deiconify frames with the window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. See section 21.6.10 Miscellaneous Window System Events.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.11 Raising and Lowering Frames

Most window systems use a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from "highest" to "lowest". Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it.

A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. Raising a window means moving it "up", to the top of the stack. Lowering a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen.

You can raise and lower Emacs frame Windows with these functions:

Command: raise-frame &optional frame
This function raises frame frame (default, the selected frame).

Command: lower-frame &optional frame
This function lowers frame frame (default, the selected frame).

User Option: minibuffer-auto-raise
If this is non-nil, activation of the minibuffer raises the frame that the minibuffer window is in.

You can also enable auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected) for any frame using frame parameters. See section 29.3.3 Window Frame Parameters.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.12 Frame Configurations

A frame configuration records the current arrangement of frames, all their properties, and the window configuration of each one. (See section 28.17 Window Configurations.)

Function: current-frame-configuration
This function returns a frame configuration list that describes the current arrangement of frames and their contents.

Function: set-frame-configuration configuration &optional nodelete
This function restores the state of frames described in configuration.

Ordinarily, this function deletes all existing frames not listed in configuration. But if nodelete is non-nil, the unwanted frames are iconified instead.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.13 Mouse Tracking

Sometimes it is useful to track the mouse, which means to display something to indicate where the mouse is and move the indicator as the mouse moves. For efficient mouse tracking, you need a way to wait until the mouse actually moves.

The convenient way to track the mouse is to ask for events to represent mouse motion. Then you can wait for motion by waiting for an event. In addition, you can easily handle any other sorts of events that may occur. That is useful, because normally you don't want to track the mouse forever--only until some other event, such as the release of a button.

Special Form: track-mouse body...
This special form executes body, with generation of mouse motion events enabled. Typically body would use read-event to read the motion events and modify the display accordingly. See section 21.6.8 Motion Events, for the format of mouse motion events.

The value of track-mouse is that of the last form in body. You should design body to return when it sees the up-event that indicates the release of the button, or whatever kind of event means it is time to stop tracking.

The usual purpose of tracking mouse motion is to indicate on the screen the consequences of pushing or releasing a button at the current position.

In many cases, you can avoid the need to track the mouse by using the mouse-face text property (see section 32.19.4 Properties with Special Meanings). That works at a much lower level and runs more smoothly than Lisp-level mouse tracking.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.14 Mouse Position

The functions mouse-position and set-mouse-position give access to the current position of the mouse.

Function: mouse-position
This function returns a description of the position of the mouse. The value looks like (frame x . y), where x and y are integers giving the position in characters relative to the top left corner of the inside of frame.

Variable: mouse-position-function
If non-nil, the value of this variable is a function for mouse-position to call. mouse-position calls this function just before returning, with its normal return value as the sole argument, and it returns whatever this function returns to it.

This abnormal hook exists for the benefit of packages like `xt-mouse.el' that need to do mouse handling at the Lisp level.

Function: set-mouse-position frame x y
This function warps the mouse to position x, y in frame frame. The arguments x and y are integers, giving the position in characters relative to the top left corner of the inside of frame. If frame is not visible, this function does nothing. The return value is not significant.

Function: mouse-pixel-position
This function is like mouse-position except that it returns coordinates in units of pixels rather than units of characters.

Function: set-mouse-pixel-position frame x y
This function warps the mouse like set-mouse-position except that x and y are in units of pixels rather than units of characters. These coordinates are not required to be within the frame.

If frame is not visible, this function does nothing. The return value is not significant.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.15 Pop-Up Menus

When using a window system, a Lisp program can pop up a menu so that the user can choose an alternative with the mouse.

Function: x-popup-menu position menu
This function displays a pop-up menu and returns an indication of what selection the user makes.

The argument position specifies where on the screen to put the menu. It can be either a mouse button event (which says to put the menu where the user actuated the button) or a list of this form:
((xoffset yoffset) window)
where xoffset and yoffset are coordinates, measured in pixels, counting from the top left corner of window's frame.

If position is t, it means to use the current mouse position. If position is nil, it means to precompute the key binding equivalents for the keymaps specified in menu, without actually displaying or popping up the menu.

The argument menu says what to display in the menu. It can be a keymap or a list of keymaps (see section 22.12 Menu Keymaps). Alternatively, it can have the following form:
(title pane1 pane2...)
where each pane is a list of form
(title (line . item)...)
Each line should be a string, and each item should be the value to return if that line is chosen.

Usage note: Don't use x-popup-menu to display a menu if you could do the job with a prefix key defined with a menu keymap. If you use a menu keymap to implement a menu, C-h c and C-h a can see the individual items in that menu and provide help for them. If instead you implement the menu by defining a command that calls x-popup-menu, the help facilities cannot know what happens inside that command, so they cannot give any help for the menu's items.

The menu bar mechanism, which lets you switch between submenus by moving the mouse, cannot look within the definition of a command to see that it calls x-popup-menu. Therefore, if you try to implement a submenu using x-popup-menu, it cannot work with the menu bar in an integrated fashion. This is why all menu bar submenus are implemented with menu keymaps within the parent menu, and never with x-popup-menu. See section 22.12.5 The Menu Bar,

If you want a menu bar submenu to have contents that vary, you should still use a menu keymap to implement it. To make the contents vary, add a hook function to menu-bar-update-hook to update the contents of the menu keymap as necessary.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.16 Dialog Boxes

A dialog box is a variant of a pop-up menu--it looks a little different, it always appears in the center of a frame, and it has just one level and one pane. The main use of dialog boxes is for asking questions that the user can answer with "yes", "no", and a few other alternatives. The functions y-or-n-p and yes-or-no-p use dialog boxes instead of the keyboard, when called from commands invoked by mouse clicks.

Function: x-popup-dialog position contents
This function displays a pop-up dialog box and returns an indication of what selection the user makes. The argument contents specifies the alternatives to offer; it has this format:
(title (string . value)...)
which looks like the list that specifies a single pane for x-popup-menu.

The return value is value from the chosen alternative.

An element of the list may be just a string instead of a cons cell (string . value). That makes a box that cannot be selected.

If nil appears in the list, it separates the left-hand items from the right-hand items; items that precede the nil appear on the left, and items that follow the nil appear on the right. If you don't include a nil in the list, then approximately half the items appear on each side.

Dialog boxes always appear in the center of a frame; the argument position specifies which frame. The possible values are as in x-popup-menu, but the precise coordinates don't matter; only the frame matters.

In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the frame.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.17 Pointer Shapes

These variables specify which shape to use for the mouse pointer in various situations, when using the X Window System:

x-pointer-shape
This variable specifies the pointer shape to use ordinarily in the Emacs frame.

x-sensitive-text-pointer-shape
This variable specifies the pointer shape to use when the mouse is over mouse-sensitive text.
These variables affect newly created frames. They do not normally affect existing frames; however, if you set the mouse color of a frame, that also updates its pointer shapes based on the current values of these variables. See section 29.3.3 Window Frame Parameters.

The values you can use, to specify either of these pointer shapes, are defined in the file `lisp/term/x-win.el'. Use M-x apropos RET x-pointer RET to see a list of them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.18 Window System Selections

The X server records a set of selections which permit transfer of data between application programs. The various selections are distinguished by selection types, represented in Emacs by symbols. X clients including Emacs can read or set the selection for any given type.

Function: x-set-selection type data
This function sets a "selection" in the X server. It takes two arguments: a selection type type, and the value to assign to it, data. If data is nil, it means to clear out the selection. Otherwise, data may be a string, a symbol, an integer (or a cons of two integers or list of two integers), an overlay, or a cons of two markers pointing to the same buffer. An overlay or a pair of markers stands for text in the overlay or between the markers.

The argument data may also be a vector of valid non-vector selection values.

Each possible type has its own selection value, which changes independently. The usual values of type are PRIMARY and SECONDARY; these are symbols with upper-case names, in accord with X Window System conventions. The default is PRIMARY.

Function: x-get-selection &optional type data-type
This function accesses selections set up by Emacs or by other X clients. It takes two optional arguments, type and data-type. The default for type, the selection type, is PRIMARY.

The data-type argument specifies the form of data conversion to use, to convert the raw data obtained from another X client into Lisp data. Meaningful values include TEXT, STRING, TARGETS, LENGTH, DELETE, FILE_NAME, CHARACTER_POSITION, LINE_NUMBER, COLUMN_NUMBER, OWNER_OS, HOST_NAME, USER, CLASS, NAME, ATOM, and INTEGER. (These are symbols with upper-case names in accord with X conventions.) The default for data-type is STRING.

The X server also has a set of numbered cut buffers which can store text or other data being moved between applications. Cut buffers are considered obsolete, but Emacs supports them for the sake of X clients that still use them.

Function: x-get-cut-buffer n
This function returns the contents of cut buffer number n.

Function: x-set-cut-buffer string &optional push
This function stores string into the first cut buffer (cut buffer 0). If push is nil, only the first cut buffer is changed. If push is non-nil, that says to move the values down through the series of cut buffers, much like the way successive kills in Emacs move down the kill ring. In other words, the previous value of the first cut buffer moves into the second cut buffer, and the second to the third, and so on through all eight cut buffers.

Variable: selection-coding-system
This variable specifies the coding system to use when reading and writing selections, the clipboard, or a cut buffer. See section 33.10 Coding Systems. The default is compound-text, which converts to the text representation that X11 normally uses.

When Emacs runs on MS-Windows, it does not implement X selections in general, but it does support the clipboard. x-get-selection and x-set-selection on MS-Windows support the text data type only; if the clipboard holds other types of data, Emacs treats the clipboard as empty.

User Option: x-select-enable-clipboard
If this is non-nil, the Emacs yank functions consult the clipboard before the primary selection, and the kill functions store in the clipboard as well as the primary selection. Otherwise they do not access the clipboard at all. The default is nil on most systems, but t on MS-Windows.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.19 Color Names

These functions provide a way to determine which color names are valid, and what they look like. In some cases, the value depends on the selected frame, as described below; see 29.9 Input Focus, for the meaning of the term "selected frame".

Function: color-defined-p color &optional frame
This function reports whether a color name is meaningful. It returns t if so; otherwise, nil. The argument frame says which frame's display to ask about; if frame is omitted or nil, the selected frame is used.

Note that this does not tell you whether the display you are using really supports that color. When using X, you can ask for any defined color on any kind of display, and you will get some result--typically, the closest it can do. To determine whether a frame can really display a certain color, use color-supported-p (see below).

This function used to be called x-color-defined-p, and that name is still supported as an alias.

Function: defined-colors &optional frame
This function returns a list of the color names that are defined and supported on frame frame (default, the selected frame).

This function used to be called x-defined-colors, and that name is still supported as an alias.

Function: color-supported-p color &optional frame background-p
This returns t if frame can really display the color color (or at least something close to it). If frame is omitted or nil, the question applies to the selected frame.

Some terminals support a different set of colors for foreground and background. If background-p is non-nil, that means you are asking whether color can be used as a background; otherwise you are asking whether it can be used as a foreground.

The argument color must be a valid color name.

Function: color-gray-p color &optional frame
This returns t if color is a shade of gray, as defined on frame's display. If frame is omitted or nil, the question applies to the selected frame. The argument color must be a valid color name.

Function: color-values color &optional frame
This function returns a value that describes what color should ideally look like. If color is defined, the value is a list of three integers, which give the amount of red, the amount of green, and the amount of blue. Each integer ranges in principle from 0 to 65535, but in practice no value seems to be above 65280. This kind of three-element list is called an rgb value.

If color is not defined, the value is nil.
(color-values "black")
     => (0 0 0)
(color-values "white")
     => (65280 65280 65280)
(color-values "red")
     => (65280 0 0)
(color-values "pink")
     => (65280 49152 51968)
(color-values "hungry")
     => nil
The color values are returned for frame's display. If frame is omitted or nil, the information is returned for the selected frame's display.

This function used to be called x-color-values, and that name is still supported as an alias.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.20 Text Terminal Colors

Emacs can display color on text-only terminals, starting with version 21. These terminals support only a small number of colors, and the computer uses small integers to select colors on the terminal. This means that the computer cannot reliably tell what the selected color looks like; instead, you have to inform your application which small integers correspond to which colors. However, Emacs does know the standard set of colors and will try to use them automatically.

Several of these functions use or return rgb values. An rgb value is a list of three integers, which give the amount of red, the amount of green, and the amount of blue. Each integer ranges in principle from 0 to 65535, but in practice the largest value used is 65280.

These functions accept a display (either a frame or the name of a terminal) as an optional argument. We hope in the future to make Emacs support more than one text-only terminal at one time; then this argument will specify which terminal to operate on (the default being the selected frame's terminal; see section 29.9 Input Focus). At present, though, the display argument has no effect.

Function: tty-color-define name number &optional rgb display
This function associates the color name name with color number number on the terminal.

The optional argument rgb, if specified, is an rgb value; it says what the color actually looks like. If you do not specify rgb, then this color cannot be used by tty-color-approximate to approximate other colors, because Emacs does not know what it looks like.

Function: tty-color-clear &optional display
This function clears the table of defined colors for a text-only terminal.

Function: tty-color-alist &optional display
This function returns an alist recording the known colors supported by a text-only terminal.

Each element has the form (name number . rgb) or (name number). Here, name is the color name, number is the number used to specify it to the terminal. If present, rgb is an rgb value that says what the color actually looks like.

Function: tty-color-approximate rgb &optional display
This function finds the closest color, among the known colors supported for display, to that described by the rgb value rgb.

Function: tty-color-translate color &optional display
This function finds the closest color to color among the known colors supported for display. If the name color is not defined, the value is nil.

color can be an X-style "#xxxyyyzzz" specification instead of an actual name. The format "RGB:xx/yy/zz" is also supported.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.21 X Resources

Function: x-get-resource attribute class &optional component subclass
The function x-get-resource retrieves a resource value from the X Windows defaults database.

Resources are indexed by a combination of a key and a class. This function searches using a key of the form `instance.attribute' (where instance is the name under which Emacs was invoked), and using `Emacs.class' as the class.

The optional arguments component and subclass add to the key and the class, respectively. You must specify both of them or neither. If you specify them, the key is `instance.component.attribute', and the class is `Emacs.class.subclass'.

Variable: x-resource-class
This variable specifies the application name that x-get-resource should look up. The default value is "Emacs". You can examine X resources for application names other than "Emacs" by binding this variable to some other string, around a call to x-get-resource.

See section `X Resources' in The GNU Emacs Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

29.22 Display Feature Testing

The functions in this section describe the basic capabilities of a particular display. Lisp programs can use them to adapt their behavior to what the display can do. For example, a program that ordinarly uses a popup menu could use the minibuffer if popup menus are not supported.

The optional argument display in these functions specifies which display to ask the question about. It can be a display name, a frame (which designates the display that frame is on), or nil (which refers to the selected frame's display, see section 29.9 Input Focus).

See section 29.19 Color Names, 29.20 Text Terminal Colors, for other functions to obtain information about displays.

Function: display-popup-menus-p &optional display
This function returns t if popup menus are supported on display, nil if not. Support for popup menus requires that the mouse be available, since the user cannot choose menu items without a mouse.

Function: display-graphic-p &optional display
This function returns t if display is a graphic display capable of displaying several frames and several different fonts at once. This is true for displays that use a window system such as X, and false for text-only terminals.

Function: display-mouse-p &optional display
This function returns t if display has a mouse available, nil if not.

Function: display-color-p &optional display
This function returns t if the screen is a color screen. It used to be called x-display-color-p, and that name is still supported as an alias.

Function: display-grayscale-p &optional display
This function returns t if the screen can display shades of gray. (All color displays can do this.)

Function: display-selections-p &optional display
This function returns t if display supports selections. Windowed displays normally support selections, but they may also be supported in some other cases.

Function: display-images-p &optional display
This function returns t if display can display images. Windowed displays ought in principle to handle images, but some systems lack the support for that. On a display that does not support images, Emacs cannot display a tool bar.

Function: display-screens &optional display
This function returns the number of screens associated with the display.

Function: display-pixel-height &optional display
This function returns the height of the screen in pixels.

Function: display-mm-height &optional display
This function returns the height of the screen in millimeters, or nil if Emacs cannot get that information.

Function: display-pixel-width &optional display
This function returns the width of the screen in pixels.

Function: display-mm-width &optional display
This function returns the width of the screen in millimeters, or nil if Emacs cannot get that information.

Function: display-backing-store &optional display
This function returns the backing store capability of the display. Backing store means recording the pixels of windows (and parts of windows) that are not exposed, so that when exposed they can be displayed very quickly.

Values can be the symbols always, when-mapped, or not-useful. The function can also return nil when the question is inapplicable to a certain kind of display.

Function: display-save-under &optional display
This function returns non-nil if the display supports the SaveUnder feature. That feature is used by pop-up windows to save the pixels they obscure, so that they can pop down quickly.

Function: display-planes &optional display
This function returns the number of planes the display supports. This is typically the number of bits per pixel. For a tty display, it is log to base two of the number of colours supported.

Function: display-visual-class &optional display
This function returns the visual class for the screen. The value is one of the symbols static-gray, gray-scale, static-color, pseudo-color, true-color, and direct-color.

Function: display-color-cells &optional display
This function returns the number of color cells the screen supports.

These functions obtain additional information specifically about X displays.

Function: x-server-version &optional display
This function returns the list of version numbers of the X server running the display.

Function: x-server-vendor &optional display
This function returns the vendor that provided the X server software.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30. Positions

A position is the index of a character in the text of a buffer. More precisely, a position identifies the place between two characters (or before the first character, or after the last character), so we can speak of the character before or after a given position. However, we often speak of the character "at" a position, meaning the character after that position.

Positions are usually represented as integers starting from 1, but can also be represented as markers---special objects that relocate automatically when text is inserted or deleted so they stay with the surrounding characters. See section 31. Markers.

See also the "field" feature (see section 32.19.10 Defining and Using Fields), which provides functions that are used by many cursur-motion commands.

30.1 Point

The special position where editing takes place.

30.2 Motion

Changing point.

30.3 Excursions

Temporary motion and buffer changes.

30.4 Narrowing

Restricting editing to a portion of the buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.1 Point

Point is a special buffer position used by many editing commands, including the self-inserting typed characters and text insertion functions. Other commands move point through the text to allow editing and insertion at different places.

Like other positions, point designates a place between two characters (or before the first character, or after the last character), rather than a particular character. Usually terminals display the cursor over the character that immediately follows point; point is actually before the character on which the cursor sits.

The value of point is a number no less than 1, and no greater than the buffer size plus 1. If narrowing is in effect (see section 30.4 Narrowing), then point is constrained to fall within the accessible portion of the buffer (possibly at one end of it).

Each buffer has its own value of point, which is independent of the value of point in other buffers. Each window also has a value of point, which is independent of the value of point in other windows on the same buffer. This is why point can have different values in various windows that display the same buffer. When a buffer appears in only one window, the buffer's point and the window's point normally have the same value, so the distinction is rarely important. See section 28.9 Windows and Point, for more details.

Function: point
This function returns the value of point in the current buffer, as an integer.
(point)
     => 175
Function: point-min
This function returns the minimum accessible value of point in the current buffer. This is normally 1, but if narrowing is in effect, it is the position of the start of the region that you narrowed to. (See section 30.4 Narrowing.)

Function: point-max
This function returns the maximum accessible value of point in the current buffer. This is (1+ (buffer-size)), unless narrowing is in effect, in which case it is the position of the end of the region that you narrowed to. (See section 30.4 Narrowing.)

Function: buffer-end flag
This function returns (point-min) if flag is less than 1, (point-max) otherwise. The argument flag must be a number.

Function: buffer-size &optional buffer
This function returns the total number of characters in the current buffer. In the absence of any narrowing (see section 30.4 Narrowing), point-max returns a value one larger than this.

If you specify a buffer, buffer, then the value is the size of buffer.
(buffer-size)
     => 35
(point-max)
     => 36
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.2 Motion

Motion functions change the value of point, either relative to the current value of point, relative to the beginning or end of the buffer, or relative to the edges of the selected window. See section 30.1 Point.

30.2.1 Motion by Characters

Moving in terms of characters.

30.2.2 Motion by Words

Moving in terms of words.

30.2.3 Motion to an End of the Buffer

Moving to the beginning or end of the buffer.

30.2.4 Motion by Text Lines

Moving in terms of lines of text.

30.2.5 Motion by Screen Lines

Moving in terms of lines as displayed.

30.2.6 Moving over Balanced Expressions

Moving by parsing lists and sexps.

30.2.7 Skipping Characters

Skipping characters belonging to a certain set.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.2.1 Motion by Characters

These functions move point based on a count of characters. goto-char is the fundamental primitive; the other functions use that.

Command: goto-char position
This function sets point in the current buffer to the value position. If position is less than 1, it moves point to the beginning of the buffer. If position is greater than the length of the buffer, it moves point to the end.

If narrowing is in effect, position still counts from the beginning of the buffer, but point cannot go outside the accessible portion. If position is out of range, goto-char moves point to the beginning or the end of the accessible portion.

When this function is called interactively, position is the numeric prefix argument, if provided; otherwise it is read from the minibuffer.

goto-char returns position.

Command: forward-char &optional count
This function moves point count characters forward, towards the end of the buffer (or backward, towards the beginning of the buffer, if count is negative). If the function attempts to move point past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), an error is signaled with error code beginning-of-buffer or end-of-buffer.

In an interactive call, count is the numeric prefix argument.

Command: backward-char &optional count
This function moves point count characters backward, towards the beginning of the buffer (or forward, towards the end of the buffer, if count is negative). If the function attempts to move point past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), an error is signaled with error code beginning-of-buffer or end-of-buffer.

In an interactive call, count is the numeric prefix argument.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.2.2 Motion by Words

These functions for parsing words use the syntax table to decide whether a given character is part of a word. See section 35. Syntax Tables.

Command: forward-word count
This function moves point forward count words (or backward if count is negative). "Moving one word" means moving until point crosses a word-constituent character and then encounters a word-separator character. However, this function cannot move point past the boundary of the accessible portion of the buffer, or across a field boundary (see section 32.19.10 Defining and Using Fields). The most common case of a field boundary is the end of the prompt in the minibuffer.

If it is possible to move count words, without being stopped prematurely by the buffer boundary or a field boundary, the value is t. Otherwise, the return value is nil and point stops at the buffer boundary or field boundary.

If inhibit-field-text-motion is non-nil, this function ignores field boundaries.

In an interactive call, count is specified by the numeric prefix argument.

Command: backward-word count
This function is just like forward-word, except that it moves backward until encountering the front of a word, rather than forward.

In an interactive call, count is set to the numeric prefix argument.

Variable: words-include-escapes
This variable affects the behavior of forward-word and everything that uses it. If it is non-nil, then characters in the "escape" and "character quote" syntax classes count as part of words. Otherwise, they do not.

Variable: inhibit-field-text-motion
If this variable is non-nil, certain motion functions including forward-word, forward-sentence, and forward-paragraph ignore field boundaries.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.2.3 Motion to an End of the Buffer

To move point to the beginning of the buffer, write:
(goto-char (point-min))
Likewise, to move to the end of the buffer, use:
(goto-char (point-max))
Here are two commands that users use to do these things. They are documented here to warn you not to use them in Lisp programs, because they set the mark and display messages in the echo area.

Command: beginning-of-buffer &optional n
This function moves point to the beginning of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If n is non-nil, then it puts point n tenths of the way from the beginning of the accessible portion of the buffer.

In an interactive call, n is the numeric prefix argument, if provided; otherwise n defaults to nil.

Warning: Don't use this function in Lisp programs!

Command: end-of-buffer &optional n
This function moves point to the end of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If n is non-nil, then it puts point n tenths of the way from the end of the accessible portion of the buffer.

In an interactive call, n is the numeric prefix argument, if provided; otherwise n defaults to nil.

Warning: Don't use this function in Lisp programs!

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.2.4 Motion by Text Lines

Text lines are portions of the buffer delimited by newline characters, which are regarded as part of the previous line. The first text line begins at the beginning of the buffer, and the last text line ends at the end of the buffer whether or not the last character is a newline. The division of the buffer into text lines is not affected by the width of the window, by line continuation in display, or by how tabs and control characters are displayed.

Command: goto-line line
This function moves point to the front of the lineth line, counting from line 1 at beginning of the buffer. If line is less than 1, it moves point to the beginning of the buffer. If line is greater than the number of lines in the buffer, it moves point to the end of the buffer--that is, the end of the last line of the buffer. This is the only case in which goto-line does not necessarily move to the beginning of a line.

If narrowing is in effect, then line still counts from the beginning of the buffer, but point cannot go outside the accessible portion. So goto-line moves point to the beginning or end of the accessible portion, if the line number specifies an inaccessible position.

The return value of goto-line is the difference between line and the line number of the line to which point actually was able to move (in the full buffer, before taking account of narrowing). Thus, the value is positive if the scan encounters the real end of the buffer before finding the specified line. The value is zero if scan encounters the end of the accessible portion but not the real end of the buffer.

In an interactive call, line is the numeric prefix argument if one has been provided. Otherwise line is read in the minibuffer.

Command: beginning-of-line &optional count
This function moves point to the beginning of the current line. With an argument count not nil or 1, it moves forward count-1 lines and then to the beginning of the line.

This function does not move point across a field boundary (see section 32.19.10 Defining and Using Fields) unless doing so would move beyond there to a different line; therefore, if count is nil or 1, and point starts at a field boundary, point does not move. To ignore field boundaries, either bind inhibit-field-text-motion to t, or use the forward-line function instead. For instance, (forward-line 0) does the same thing as (beginning-of-line), except that it ignores field boundaries.

If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled.

Function: line-beginning-position &optional count
Return the position that (beginning-of-line count) would move to.

Command: end-of-line &optional count
This function moves point to the end of the current line. With an argument count not nil or 1, it moves forward count-1 lines and then to the end of the line.

This function does not move point across a field boundary (see section 32.19.10 Defining and Using Fields) unless doing so would move beyond there to a different line; therefore, if count is nil or 1, and point starts at a field boundary, point does not move. To ignore field boundaries, bind inhibit-field-text-motion to t.

If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled.

Function: line-end-position &optional count
Return the position that (end-of-line count) would move to.

Command: forward-line &optional count
This function moves point forward count lines, to the beginning of the line. If count is negative, it moves point -count lines backward, to the beginning of a line. If count is zero, it moves point to the beginning of the current line.

If forward-line encounters the beginning or end of the buffer (or of the accessible portion) before finding that many lines, it sets point there. No error is signaled.

forward-line returns the difference between count and the number of lines actually moved. If you attempt to move down five lines from the beginning of a buffer that has only three lines, point stops at the end of the last line, and the value will be 2.

In an interactive call, count is the numeric prefix argument.

Function: count-lines start end
This function returns the number of lines between the positions start and end in the current buffer. If start and end are equal, then it returns 0. Otherwise it returns at least 1, even if start and end are on the same line. This is because the text between them, considered in isolation, must contain at least one line unless it is empty.

Here is an example of using count-lines:
(defun current-line ()
  "Return the vertical position of point..."
  (+ (count-lines (window-start) (point))
     (if (= (current-column) 0) 1 0)
     -1))
Also see the functions bolp and eolp in 32.1 Examining Text Near Point. These functions do not move point, but test whether it is already at the beginning or end of a line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.2.5 Motion by Screen Lines

The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen lines, which are defined by the way the text appears on the screen. A text line is a single screen line if it is short enough to fit the width of the selected window, but otherwise it may occupy several screen lines.

In some cases, text lines are truncated on the screen rather than continued onto additional screen lines. In these cases, vertical-motion moves point much like forward-line. See section 38.3 Truncation.

Because the width of a given string depends on the flags that control the appearance of certain characters, vertical-motion behaves differently, for a given piece of text, depending on the buffer it is in, and even on the selected window (because the width, the truncation flag, and display table may vary between windows). See section 38.16 Usual Display Conventions.

These functions scan text to determine where screen lines break, and thus take time proportional to the distance scanned. If you intend to use them heavily, Emacs provides caches which may improve the performance of your code. See section cache-long-line-scans.

Function: vertical-motion count &optional window
This function moves point to the start of the screen line count screen lines down from the screen line containing point. If count is negative, it moves up instead.

vertical-motion returns the number of screen lines over which it moved point. The value may be less in absolute value than count if the beginning or end of the buffer was reached.

The window window is used for obtaining parameters such as the width, the horizontal scrolling, and the display table. But vertical-motion always operates on the current buffer, even if window currently displays some other buffer.

Function: count-screen-lines &optional beg end count-final-newline window
This function returns the number of screen lines in the text from beg to end. The number of screen lines may be different from the number of actual lines, due to line continuation, the display table, etc. If beg and end are nil or omitted, they default to the beginning and end of the accessible portion of the buffer.

If the region ends with a newline, that is ignored unless the optional third argument count-final-newline is non-nil.

The optional fourth argument window specifies the window for obtaining parameters such as width, horizontal scrolling, and so on. The default is to use the selected window's parameters.

Like vertical-motion, count-screen-lines always uses the current buffer, regardless of which buffer is displayed in window. This makes possible to use count-screen-lines in any buffer, whether or not it is currently displayed in some window.

Command: move-to-window-line count
This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen line count screen lines from the top of the window. If count is negative, that specifies a position -count lines from the bottom (or the last line of the buffer, if the buffer ends above the specified screen position).

If count is nil, then point moves to the beginning of the line in the middle of the window. If the absolute value of count is greater than the size of the window, then point moves to the place that would appear on that screen line if the window were tall enough. This will probably cause the next redisplay to scroll to bring that location onto the screen.

In an interactive call, count is the numeric prefix argument.

The value returned is the window line number point has moved to, with the top line in the window numbered 0.

Function: compute-motion from frompos to topos width offsets window
This function scans the current buffer, calculating screen positions. It scans the buffer forward from position from, assuming that is at screen coordinates frompos, to position to or coordinates topos, whichever comes first. It returns the ending buffer position and screen coordinates.

The coordinate arguments frompos and topos are cons cells of the form (hpos . vpos).

The argument width is the number of columns available to display text; this affects handling of continuation lines. Use the value returned by window-width for the window of your choice; normally, use (window-width window).

The argument offsets is either nil or a cons cell of the form (hscroll . tab-offset). Here hscroll is the number of columns not being displayed at the left margin; most callers get this by calling window-hscroll. Meanwhile, tab-offset is the offset between column numbers on the screen and column numbers in the buffer. This can be nonzero in a continuation line, when the previous screen lines' widths do not add up to a multiple of tab-width. It is always zero in a non-continuation line.

The window window serves only to specify which display table to use. compute-motion always operates on the current buffer, regardless of what buffer is displayed in window.

The return value is a list of five elements:
(pos vpos hpos prevhpos contin)
Here pos is the buffer position where the scan stopped, vpos is the vertical screen position, and hpos is the horizontal screen position.

The result prevhpos is the horizontal position one character back from pos. The result contin is t if the last line was continued after (or within) the previous character.

For example, to find the buffer position of column col of screen line line of a certain window, pass the window's display start location as from and the window's upper-left coordinates as frompos. Pass the buffer's (point-max) as to, to limit the scan to the end of the accessible portion of the buffer, and pass line and col as topos. Here's a function that does this:
(defun coordinates-of-position (col line)
  (car (compute-motion (window-start)
                       '(0 . 0)
                       (point-max)
                       (cons col line)
                       (window-width)
                       (cons (window-hscroll) 0)
                       (selected-window))))
When you use compute-motion for the minibuffer, you need to use minibuffer-prompt-width to get the horizontal position of the beginning of the first screen line. See section 20.9 Minibuffer Miscellany.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.2.6 Moving over Balanced Expressions

Here are several functions concerned with balanced-parenthesis expressions (also called sexps in connection with moving across them in Emacs). The syntax table controls how these functions interpret various characters; see 35. Syntax Tables. See section 35.6 Parsing Balanced Expressions, for lower-level primitives for scanning sexps or parts of sexps. For user-level commands, see section `Lists Commands' in The GNU Emacs Manual.

Command: forward-list &optional arg
This function moves forward across arg (default 1) balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.)

Command: backward-list &optional arg
This function moves backward across arg (default 1) balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.)

Command: up-list &optional arg
This function moves forward out of arg (default 1) levels of parentheses. A negative argument means move backward but still to a less deep spot.

Command: down-list &optional arg
This function moves forward into arg (default 1) levels of parentheses. A negative argument means move backward but still go deeper in parentheses (-arg levels).

Command: forward-sexp &optional arg
This function moves forward across arg (default 1) balanced expressions. Balanced expressions include both those delimited by parentheses and other kinds, such as words and string constants. For example,
---------- Buffer: foo ----------
(concat-!- "foo " (car x) y z)
---------- Buffer: foo ----------

(forward-sexp 3)
     => nil

---------- Buffer: foo ----------
(concat "foo " (car x) y-!- z)
---------- Buffer: foo ----------
Command: backward-sexp &optional arg
This function moves backward across arg (default 1) balanced expressions.

Command: beginning-of-defun arg
This function moves back to the argth beginning of a defun. If arg is negative, this actually moves forward, but it still moves to the beginning of a defun, not to the end of one.

Command: end-of-defun arg
This function moves forward to the argth end of a defun. If arg is negative, this actually moves backward, but it still moves to the end of a defun, not to the beginning of one.

User Option: defun-prompt-regexp
If non-nil, this variable holds a regular expression that specifies what text can appear before the open-parenthesis that starts a defun. That is to say, a defun begins on a line that starts with a match for this regular expression, followed by a character with open-parenthesis syntax.

User Option: open-paren-in-column-0-is-defun-start
If this variable's value is non-nil, an open parenthesis in column 0 is considered to be the start of a defun. If it is nil, an open parenthesis in column 0 has no special meaning. The default is t.

Variable: beginning-of-defun-function
If non-nil, this variable holds a function for finding the beginning of a defun. The function beginning-of-defun calls this function instead of using its normal method.

Variable: end-of-defun-function
If non-nil, this variable holds a function for finding the end of a defun. The function end-of-defun calls this function instead of using its normal method.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.2.7 Skipping Characters

The following two functions move point over a specified set of characters. For example, they are often used to skip whitespace. For related functions, see 35.5 Motion and Syntax.

Function: skip-chars-forward character-set &optional limit
This function moves point in the current buffer forward, skipping over a given set of characters. It examines the character following point, then advances point if the character matches character-set. This continues until it reaches a character that does not match. The function returns the number of characters moved over.

The argument character-set is like the inside of a `[...]' in a regular expression except that `]' is never special and `\' quotes `^', `-' or `\'. Thus, "a-zA-Z" skips over all letters, stopping before the first nonletter, and "^a-zA-Z" skips nonletters stopping before the first letter. See section 34.2 Regular Expressions.

If limit is supplied (it must be a number or a marker), it specifies the maximum position in the buffer that point can be skipped to. Point will stop at or before limit.

In the following example, point is initially located directly before the `T'. After the form is evaluated, point is located at the end of that line (between the `t' of `hat' and the newline). The function skips all letters and spaces, but not newlines.
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(skip-chars-forward "a-zA-Z ")
     => nil

---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
Function: skip-chars-backward character-set &optional limit
This function moves point backward, skipping characters that match character-set, until limit. It is just like skip-chars-forward except for the direction of motion.

The return value indicates the distance traveled. It is an integer that is zero or less.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.3 Excursions

It is often useful to move point "temporarily" within a localized portion of the program, or to switch buffers temporarily. This is called an excursion, and it is done with the save-excursion special form. This construct initially remembers the identity of the current buffer, and its values of point and the mark, and restores them after the completion of the excursion.

The forms for saving and restoring the configuration of windows are described elsewhere (see 28.17 Window Configurations, and see section 29.12 Frame Configurations).

Special Form: save-excursion forms...
The save-excursion special form saves the identity of the current buffer and the values of point and the mark in it, evaluates forms, and finally restores the buffer and its saved values of point and the mark. All three saved values are restored even in case of an abnormal exit via throw or error (see section 10.5 Nonlocal Exits).

The save-excursion special form is the standard way to switch buffers or move point within one part of a program and avoid affecting the rest of the program. It is used more than 4000 times in the Lisp sources of Emacs.

save-excursion does not save the values of point and the mark for other buffers, so changes in other buffers remain in effect after save-excursion exits.

Likewise, save-excursion does not restore window-buffer correspondences altered by functions such as switch-to-buffer. One way to restore these correspondences, and the selected window, is to use save-window-excursion inside save-excursion (see section 28.17 Window Configurations).

The value returned by save-excursion is the result of the last of forms, or nil if no forms are given.
(save-excursion forms)
==
(let ((old-buf (current-buffer))
      (old-pnt (point-marker))
      (old-mark (copy-marker (mark-marker))))
  (unwind-protect
      (progn forms)
    (set-buffer old-buf)
    (goto-char old-pnt)
    (set-marker (mark-marker) old-mark)))
Warning: Ordinary insertion of text adjacent to the saved point value relocates the saved value, just as it relocates all markers. Therefore, when the saved point value is restored, it normally comes before the inserted text.

Although save-excursion saves the location of the mark, it does not prevent functions which modify the buffer from setting deactivate-mark, and thus causing the deactivation of the mark after the command finishes. See section 31.7 The Mark.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

30.4 Narrowing

Narrowing means limiting the text addressable by Emacs editing commands to a limited range of characters in a buffer. The text that remains addressable is called the accessible portion of the buffer.

Narrowing is specified with two buffer positions which become the beginning and end of the accessible portion. For most editing commands and most Emacs primitives, these positions replace the values of the beginning and end of the buffer. While narrowing is in effect, no text outside the accessible portion is displayed, and point cannot move outside the accessible portion.

Values such as positions or line numbers, which usually count from the beginning of the buffer, do so despite narrowing, but the functions which use them refuse to operate on text that is inaccessible.

The commands for saving buffers are unaffected by narrowing; they save the entire buffer regardless of any narrowing.

Command: narrow-to-region start end
This function sets the accessible portion of the current buffer to start at start and end at end. Both arguments should be character positions.

In an interactive call, start and end are set to the bounds of the current region (point and the mark, with the smallest first).

Command: narrow-to-page move-count
This function sets the accessible portion of the current buffer to include just the current page. An optional first argument move-count non-nil means to move forward or backward by move-count pages and then narrow to one page. The variable page-delimiter specifies where pages start and end (see section 34.8 Standard Regular Expressions Used in Editing).

In an interactive call, move-count is set to the numeric prefix argument.

Command: widen
This function cancels any narrowing in the current buffer, so that the entire contents are accessible. This is called widening. It is equivalent to the following expression:
(narrow-to-region 1 (1+ (buffer-size)))
Special Form: save-restriction body...
This special form saves the current bounds of the accessible portion, evaluates the body forms, and finally restores the saved bounds, thus restoring the same state of narrowing (or absence thereof) formerly in effect. The state of narrowing is restored even in the event of an abnormal exit via throw or error (see section 10.5 Nonlocal Exits). Therefore, this construct is a clean way to narrow a buffer temporarily.

The value returned by save-restriction is that returned by the last form in body, or nil if no body forms were given.

Caution: it is easy to make a mistake when using the save-restriction construct. Read the entire description here before you try it.

If body changes the current buffer, save-restriction still restores the restrictions on the original buffer (the buffer whose restrictions it saved from), but it does not restore the identity of the current buffer.

save-restriction does not restore point and the mark; use save-excursion for that. If you use both save-restriction and save-excursion together, save-excursion should come first (on the outside). Otherwise, the old point value would be restored with temporary narrowing still in effect. If the old point value were outside the limits of the temporary narrowing, this would fail to restore it accurately.

Here is a simple example of correct use of save-restriction:
---------- Buffer: foo ----------
This is the contents of foo
This is the contents of foo
This is the contents of foo-!-
---------- Buffer: foo ----------

(save-excursion
  (save-restriction
    (goto-char 1)
    (forward-line 2)
    (narrow-to-region 1 (point))
    (goto-char (point-min))
    (replace-string "foo" "bar")))

---------- Buffer: foo ----------
This is the contents of bar
This is the contents of bar
This is the contents of foo-!-
---------- Buffer: foo ----------
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31. Markers

A marker is a Lisp object used to specify a position in a buffer relative to the surrounding text. A marker changes its offset from the beginning of the buffer automatically whenever text is inserted or deleted, so that it stays with the two characters on either side of it.

31.1 Overview of Markers

The components of a marker, and how it relocates.

31.2 Predicates on Markers

Testing whether an object is a marker.

31.3 Functions that Create Markers

Making empty markers or markers at certain places.

31.4 Information from Markers

Finding the marker's buffer or character position.

31.5 Marker Insertion Types

Two ways a marker can relocate when you insert where it points.

31.6 Moving Marker Positions

Moving the marker to a new buffer or position.

31.7 The Mark

How "the mark" is implemented with a marker.

31.8 The Region

How to access "the region".

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31.1 Overview of Markers

A marker specifies a buffer and a position in that buffer. The marker can be used to represent a position in the functions that require one, just as an integer could be used. See section 30. Positions, for a complete description of positions.

A marker has two attributes: the marker position, and the marker buffer. The marker position is an integer that is equivalent (at a given time) to the marker as a position in that buffer. But the marker's position value can change often during the life of the marker. Insertion and deletion of text in the buffer relocate the marker. The idea is that a marker positioned between two characters remains between those two characters despite insertion and deletion elsewhere in the buffer. Relocation changes the integer equivalent of the marker.

Deleting text around a marker's position leaves the marker between the characters immediately before and after the deleted text. Inserting text at the position of a marker normally leaves the marker either in front of or after the new text, depending on the marker's insertion type (see section 31.5 Marker Insertion Types)---unless the insertion is done with insert-before-markers (see section 32.4 Inserting Text).

Insertion and deletion in a buffer must check all the markers and relocate them if necessary. This slows processing in a buffer with a large number of markers. For this reason, it is a good idea to make a marker point nowhere if you are sure you don't need it any more. Unreferenced markers are garbage collected eventually, but until then will continue to use time if they do point somewhere.

Because it is common to perform arithmetic operations on a marker position, most of the arithmetic operations (including + and -) accept markers as arguments. In such cases, the marker stands for its current position.

Here are examples of creating markers, setting markers, and moving point to markers:
;; Make a new marker that initially does not point anywhere:
(setq m1 (make-marker))
     => #<marker in no buffer>

;; Set m1 to point between the 99th and 100th characters
;;   in the current buffer:
(set-marker m1 100)
     => #<marker at 100 in markers.texi>

;; Now insert one character at the beginning of the buffer:
(goto-char (point-min))
     => 1
(insert "Q")
     => nil

;; m1 is updated appropriately.
m1
     => #<marker at 101 in markers.texi>

;; Two markers that point to the same position
;;   are not eq, but they are equal.
(setq m2 (copy-marker m1))
     => #<marker at 101 in markers.texi>
(eq m1 m2)
     => nil
(equal m1 m2)
     => t

;; When you are finished using a marker, make it point nowhere.
(set-marker m1 nil)
     => #<marker in no buffer>
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31.2 Predicates on Markers

You can test an object to see whether it is a marker, or whether it is either an integer or a marker. The latter test is useful in connection with the arithmetic functions that work with both markers and integers.

Function: markerp object
This function returns t if object is a marker, nil otherwise. Note that integers are not markers, even though many functions will accept either a marker or an integer.

Function: integer-or-marker-p object
This function returns t if object is an integer or a marker, nil otherwise.

Function: number-or-marker-p object
This function returns t if object is a number (either integer or floating point) or a marker, nil otherwise.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31.3 Functions that Create Markers

When you create a new marker, you can make it point nowhere, or point to the present position of point, or to the beginning or end of the accessible portion of the buffer, or to the same place as another given marker.

Function: make-marker
This function returns a newly created marker that does not point anywhere.
(make-marker)
     => #<marker in no buffer>
Function: point-marker
This function returns a new marker that points to the present position of point in the current buffer. See section 30.1 Point. For an example, see copy-marker, below.

Function: point-min-marker
This function returns a new marker that points to the beginning of the accessible portion of the buffer. This will be the beginning of the buffer unless narrowing is in effect. See section 30.4 Narrowing.

Function: point-max-marker
This function returns a new marker that points to the end of the accessible portion of the buffer. This will be the end of the buffer unless narrowing is in effect. See section 30.4 Narrowing.

Here are examples of this function and point-min-marker, shown in a buffer containing a version of the source file for the text of this chapter.
(point-min-marker)
     => #<marker at 1 in markers.texi>
(point-max-marker)
     => #<marker at 15573 in markers.texi>

(narrow-to-region 100 200)
     => nil
(point-min-marker)
     => #<marker at 100 in markers.texi>
(point-max-marker)
     => #<marker at 200 in markers.texi>
Function: copy-marker marker-or-integer insertion-type
If passed a marker as its argument, copy-marker returns a new marker that points to the same place and the same buffer as does marker-or-integer. If passed an integer as its argument, copy-marker returns a new marker that points to position marker-or-integer in the current buffer.

The new marker's insertion type is specified by the argument insertion-type. See section 31.5 Marker Insertion Types.

If passed an integer argument less than 1, copy-marker returns a new marker that points to the beginning of the current buffer. If passed an integer argument greater than the length of the buffer, copy-marker returns a new marker that points to the end of the buffer.
(copy-marker 0)
     => #<marker at 1 in markers.texi>

(copy-marker 20000)
     => #<marker at 7572 in markers.texi>
An error is signaled if marker is neither a marker nor an integer.

Two distinct markers are considered equal (even though not eq) to each other if they have the same position and buffer, or if they both point nowhere.
(setq p (point-marker))
     => #<marker at 2139 in markers.texi>

(setq q (copy-marker p))
     => #<marker at 2139 in markers.texi>

(eq p q)
     => nil

(equal p q)
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31.4 Information from Markers

This section describes the functions for accessing the components of a marker object.

Function: marker-position marker
This function returns the position that marker points to, or nil if it points nowhere.

Function: marker-buffer marker
This function returns the buffer that marker points into, or nil if it points nowhere.
(setq m (make-marker))
     => #<marker in no buffer>
(marker-position m)
     => nil
(marker-buffer m)
     => nil

(set-marker m 3770 (current-buffer))
     => #<marker at 3770 in markers.texi>
(marker-buffer m)
     => #<buffer markers.texi>
(marker-position m)
     => 3770
Function: buffer-has-markers-at position
This function returns t if one or more markers point at position position in the current buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31.5 Marker Insertion Types

When you insert text directly at the place where a marker points, there are two possible ways to relocate that marker: it can point before the inserted text, or point after it. You can specify which one a given marker should do by setting its insertion type. Note that use of insert-before-markers ignores markers' insertion types, always relocating a marker to point after the inserted text.

Function: set-marker-insertion-type marker type
This function sets the insertion type of marker marker to type. If type is t, marker will advance when text is inserted at its position. If type is nil, marker does not advance when text is inserted there.

Function: marker-insertion-type marker
This function reports the current insertion type of marker.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31.6 Moving Marker Positions

This section describes how to change the position of an existing marker. When you do this, be sure you know whether the marker is used outside of your program, and, if so, what effects will result from moving it--otherwise, confusing things may happen in other parts of Emacs.

Function: set-marker marker position &optional buffer
This function moves marker to position in buffer. If buffer is not provided, it defaults to the current buffer.

If position is less than 1, set-marker moves marker to the beginning of the buffer. If position is greater than the size of the buffer, set-marker moves marker to the end of the buffer. If position is nil or a marker that points nowhere, then marker is set to point nowhere.

The value returned is marker.
(setq m (point-marker))
     => #<marker at 4714 in markers.texi>
(set-marker m 55)
     => #<marker at 55 in markers.texi>
(setq b (get-buffer "foo"))
     => #<buffer foo>
(set-marker m 0 b)
     => #<marker at 1 in foo>
Function: move-marker marker position &optional buffer
This is another name for set-marker.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31.7 The Mark

One special marker in each buffer is designated the mark. It records a position for the user for the sake of commands such as kill-region and indent-rigidly. Lisp programs should set the mark only to values that have a potential use to the user, and never for their own internal purposes. For example, the replace-regexp command sets the mark to the value of point before doing any replacements, because this enables the user to move back there conveniently after the replace is finished.

Many commands are designed so that when called interactively they operate on the text between point and the mark. If you are writing such a command, don't examine the mark directly; instead, use interactive with the `r' specification. This provides the values of point and the mark as arguments to the command in an interactive call, but permits other Lisp programs to specify arguments explicitly. See section 21.2.2 Code Characters for interactive.

Each buffer has its own value of the mark that is independent of the value of the mark in other buffers. When a buffer is created, the mark exists but does not point anywhere. We consider this state as "the absence of a mark in that buffer."

Once the mark "exists" in a buffer, it normally never ceases to exist. However, it may become inactive, if Transient Mark mode is enabled. The variable mark-active, which is always buffer-local in all buffers, indicates whether the mark is active: non-nil means yes. A command can request deactivation of the mark upon return to the editor command loop by setting deactivate-mark to a non-nil value (but this causes deactivation only if Transient Mark mode is enabled).

The main motivation for using Transient Mark mode is that this mode also enables highlighting of the region when the mark is active. See section 38. Emacs Display.

In addition to the mark, each buffer has a mark ring which is a list of markers containing previous values of the mark. When editing commands change the mark, they should normally save the old value of the mark on the mark ring. The variable mark-ring-max specifies the maximum number of entries in the mark ring; once the list becomes this long, adding a new element deletes the last element.

There is also a separate global mark ring, but that is used only in a few particular user-level commands, and is not relevant to Lisp programming. So we do not describe it here.

Function: mark &optional force
This function returns the current buffer's mark position as an integer.

If the mark is inactive, mark normally signals an error. However, if force is non-nil, then mark returns the mark position anyway--or nil, if the mark is not yet set for this buffer.

Function: mark-marker
This function returns the current buffer's mark. This is the very marker that records the mark location inside Emacs, not a copy. Therefore, changing this marker's position will directly affect the position of the mark. Don't do it unless that is the effect you want.
(setq m (mark-marker))
     => #<marker at 3420 in markers.texi>
(set-marker m 100)
     => #<marker at 100 in markers.texi>
(mark-marker)
     => #<marker at 100 in markers.texi>
Like any marker, this marker can be set to point at any buffer you like. We don't recommend that you make it point at any buffer other than the one of which it is the mark. If you do, it will yield perfectly consistent, but rather odd, results.

Function: set-mark position
This function sets the mark to position, and activates the mark. The old value of the mark is not pushed onto the mark ring.

Please note: Use this function only if you want the user to see that the mark has moved, and you want the previous mark position to be lost. Normally, when a new mark is set, the old one should go on the mark-ring. For this reason, most applications should use push-mark and pop-mark, not set-mark.

Novice Emacs Lisp programmers often try to use the mark for the wrong purposes. The mark saves a location for the user's convenience. An editing command should not alter the mark unless altering the mark is part of the user-level functionality of the command. (And, in that case, this effect should be documented.) To remember a location for internal use in the Lisp program, store it in a Lisp variable. For example:
(let ((beg (point)))
  (forward-line 1)
  (delete-region beg (point))).
Function: push-mark &optional position nomsg activate
This function sets the current buffer's mark to position, and pushes a copy of the previous mark onto mark-ring. If position is nil, then the value of point is used. push-mark returns nil.

The function push-mark normally does not activate the mark. To do that, specify t for the argument activate.

A `Mark set' message is displayed unless nomsg is non-nil.

Function: pop-mark
This function pops off the top element of mark-ring and makes that mark become the buffer's actual mark. This does not move point in the buffer, and it does nothing if mark-ring is empty. It deactivates the mark.

The return value is not meaningful.

User Option: transient-mark-mode
This variable if non-nil enables Transient Mark mode, in which every buffer-modifying primitive sets deactivate-mark. The consequence of this is that commands that modify the buffer normally make the mark inactive.

User Option: mark-even-if-inactive
If this is non-nil, Lisp programs and the Emacs user can use the mark even when it is inactive. This option affects the behavior of Transient Mark mode. When the option is non-nil, deactivation of the mark turns off region highlighting, but commands that use the mark behave as if the mark were still active.

Variable: deactivate-mark
If an editor command sets this variable non-nil, then the editor command loop deactivates the mark after the command returns (if Transient Mark mode is enabled). All the primitives that change the buffer set deactivate-mark, to deactivate the mark when the command is finished.

Function: deactivate-mark
This function deactivates the mark, if Transient Mark mode is enabled. Otherwise it does nothing.

Variable: mark-active
The mark is active when this variable is non-nil. This variable is always buffer-local in each buffer.

Variable: activate-mark-hook

Variable: deactivate-mark-hook
These normal hooks are run, respectively, when the mark becomes active and when it becomes inactive. The hook activate-mark-hook is also run at the end of a command if the mark is active and it is possible that the region may have changed.

Variable: mark-ring
The value of this buffer-local variable is the list of saved former marks of the current buffer, most recent first.
mark-ring
=> (#<marker at 11050 in markers.texi>
    #<marker at 10832 in markers.texi>
    ...)
User Option: mark-ring-max
The value of this variable is the maximum size of mark-ring. If more marks than this are pushed onto the mark-ring, push-mark discards an old mark when it adds a new one.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

31.8 The Region

The text between point and the mark is known as the region. Various functions operate on text delimited by point and the mark, but only those functions specifically related to the region itself are described here.

Function: region-beginning
This function returns the position of the beginning of the region (as an integer). This is the position of either point or the mark, whichever is smaller.

If the mark does not point anywhere, an error is signaled.

Function: region-end
This function returns the position of the end of the region (as an integer). This is the position of either point or the mark, whichever is larger.

If the mark does not point anywhere, an error is signaled.

Few programs need to use the region-beginning and region-end functions. A command designed to operate on a region should normally use interactive with the `r' specification to find the beginning and end of the region. This lets other Lisp programs specify the bounds explicitly as arguments. (See section 21.2.2 Code Characters for interactive.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32. Text

This chapter describes the functions that deal with the text in a buffer. Most examine, insert, or delete text in the current buffer, often operating at point or on text adjacent to point. Many are interactive. All the functions that change the text provide for undoing the changes (see section 32.9 Undo).

Many text-related functions operate on a region of text defined by two buffer positions passed in arguments named start and end. These arguments should be either markers (see section 31. Markers) or numeric character positions (see section 30. Positions). The order of these arguments does not matter; it is all right for start to be the end of the region and end the beginning. For example, (delete-region 1 10) and (delete-region 10 1) are equivalent. An args-out-of-range error is signaled if either start or end is outside the accessible portion of the buffer. In an interactive call, point and the mark are used for these arguments.

Throughout this chapter, "text" refers to the characters in the buffer, together with their properties (when relevant). Keep in mind that point is always between two characters, and the cursor appears on the character after point.

32.1 Examining Text Near Point

Examining text in the vicinity of point.

32.2 Examining Buffer Contents

Examining text in a general fashion.

32.3 Comparing Text

Comparing substrings of buffers.

32.4 Inserting Text

Adding new text to a buffer.

32.5 User-Level Insertion Commands

User-level commands to insert text.

32.6 Deleting Text

Removing text from a buffer.

32.7 User-Level Deletion Commands

User-level commands to delete text.

32.8 The Kill Ring

Where removed text sometimes is saved for later use.

32.9 Undo

Undoing changes to the text of a buffer.

32.10 Maintaining Undo Lists

How to enable and disable undo information. How to control how much information is kept.

32.11 Filling

Functions for explicit filling.

32.12 Margins for Filling

How to specify margins for filling commands.

32.13 Adaptive Fill Mode

Adaptive Fill mode chooses a fill prefix from context.

32.14 Auto Filling

How auto-fill mode is implemented to break lines.

32.15 Sorting Text

Functions for sorting parts of the buffer.

32.16 Counting Columns

Computing horizontal positions, and using them.

32.17 Indentation

Functions to insert or adjust indentation.

32.18 Case Changes

Case conversion of parts of the buffer.

32.19 Text Properties

Assigning Lisp property lists to text characters.

32.20 Substituting for a Character Code

Replacing a given character wherever it appears.

32.22 Transposition of Text

Swapping two portions of a buffer.

32.21 Registers

How registers are implemented. Accessing the text or position stored in a register.

32.23 Base 64 Encoding

Conversion to or from base 64 encoding.

32.24 MD5 Checksum

Compute the MD5 "message digest"/"checksum".

32.25 Change Hooks

Supplying functions to be run when text is changed.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.1 Examining Text Near Point

Many functions are provided to look at the characters around point. Several simple functions are described here. See also looking-at in 34.3 Regular Expression Searching.

Function: char-after &optional position
This function returns the character in the current buffer at (i.e., immediately after) position position. If position is out of range for this purpose, either before the beginning of the buffer, or at or beyond the end, then the value is nil. The default for position is point.

In the following example, assume that the first character in the buffer is `@':
(char-to-string (char-after 1))
     => "@"
Function: char-before &optional position
This function returns the character in the current buffer immediately before position position. If position is out of range for this purpose, either before the beginning of the buffer, or at or beyond the end, then the value is nil. The default for position is point.

Function: following-char
This function returns the character following point in the current buffer. This is similar to (char-after (point)). However, if point is at the end of the buffer, then following-char returns 0.

Remember that point is always between characters, and the terminal cursor normally appears over the character following point. Therefore, the character returned by following-char is the character the cursor is over.

In this example, point is between the `a' and the `c'.
---------- Buffer: foo ----------
Gentlemen may cry ``Pea-!-ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(char-to-string (preceding-char))
     => "a"
(char-to-string (following-char))
     => "c"
Function: preceding-char
This function returns the character preceding point in the current buffer. See above, under following-char, for an example. If point is at the beginning of the buffer, preceding-char returns 0.

Function: bobp
This function returns t if point is at the beginning of the buffer. If narrowing is in effect, this means the beginning of the accessible portion of the text. See also point-min in 30.1 Point.

Function: eobp
This function returns t if point is at the end of the buffer. If narrowing is in effect, this means the end of accessible portion of the text. See also point-max in See section 30.1 Point.

Function: bolp
This function returns t if point is at the beginning of a line. See section 30.2.4 Motion by Text Lines. The beginning of the buffer (or of its accessible portion) always counts as the beginning of a line.

Function: eolp
This function returns t if point is at the end of a line. The end of the buffer (or of its accessible portion) is always considered the end of a line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.2 Examining Buffer Contents

This section describes two functions that allow a Lisp program to convert any portion of the text in the buffer into a string.

Function: buffer-substring start end
This function returns a string containing a copy of the text of the region defined by positions start and end in the current buffer. If the arguments are not positions in the accessible portion of the buffer, buffer-substring signals an args-out-of-range error.

It is not necessary for start to be less than end; the arguments can be given in either order. But most often the smaller argument is written first.

If the text being copied has any text properties, these are copied into the string along with the characters they belong to. See section 32.19 Text Properties. However, overlays (see section 38.9 Overlays) in the buffer and their properties are ignored, not copied.
---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-substring 1 10)
=> "This is t"
(buffer-substring (point-max) 10)
=> "he contents of buffer foo
"
Function: buffer-substring-no-properties start end
This is like buffer-substring, except that it does not copy text properties, just the characters themselves. See section 32.19 Text Properties.

Function: buffer-string
This function returns the contents of the entire accessible portion of the current buffer as a string. It is equivalent to
(buffer-substring (point-min) (point-max))
---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-string)
     => "This is the contents of buffer foo
"
Function: thing-at-point thing
Return the thing around or next to point, as a string.

The argument thing is a symbol which specifies a kind of syntactic entity. Possibilities include symbol, list, sexp, defun, filename, url, word, sentence, whitespace, line, page, and others.
---------- Buffer: foo ----------
Gentlemen may cry ``Pea-!-ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(thing-at-point 'word)
     => "Peace"
(thing-at-point 'line)
     => "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
     => nil
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.3 Comparing Text

This function lets you compare portions of the text in a buffer, without copying them into strings first.

Function: compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
This function lets you compare two substrings of the same buffer or two different buffers. The first three arguments specify one substring, giving a buffer and two positions within the buffer. The last three arguments specify the other substring in the same way. You can use nil for buffer1, buffer2, or both to stand for the current buffer.

The value is negative if the first substring is less, positive if the first is greater, and zero if they are equal. The absolute value of the result is one plus the index of the first differing characters within the substrings.

This function ignores case when comparing characters if case-fold-search is non-nil. It always ignores text properties.

Suppose the current buffer contains the text `foobarbar haha!rara!'; then in this example the two substrings are `rbar ' and `rara!'. The value is 2 because the first substring is greater at the second character.
(compare-buffer-substrings nil 6 11 nil 16 21)
     => 2
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.4 Inserting Text

Insertion means adding new text to a buffer. The inserted text goes at point--between the character before point and the character after point. Some insertion functions leave point before the inserted text, while other functions leave it after. We call the former insertion after point and the latter insertion before point.

Insertion relocates markers that point at positions after the insertion point, so that they stay with the surrounding text (see section 31. Markers). When a marker points at the place of insertion, insertion may or may not relocate the marker, depending on the marker's insertion type (see section 31.5 Marker Insertion Types). Certain special functions such as insert-before-markers relocate all such markers to point after the inserted text, regardless of the markers' insertion type.

Insertion functions signal an error if the current buffer is read-only or if they insert within read-only text.

These functions copy text characters from strings and buffers along with their properties. The inserted characters have exactly the same properties as the characters they were copied from. By contrast, characters specified as separate arguments, not part of a string or buffer, inherit their text properties from the neighboring text.

The insertion functions convert text from unibyte to multibyte in order to insert in a multibyte buffer, and vice versa--if the text comes from a string or from a buffer. However, they do not convert unibyte character codes 128 through 255 to multibyte characters, not even if the current buffer is a multibyte buffer. See section 33.2 Converting Text Representations.

Function: insert &rest args
This function inserts the strings and/or characters args into the current buffer, at point, moving point forward. In other words, it inserts the text before point. An error is signaled unless all args are either strings or characters. The value is nil.

Function: insert-before-markers &rest args
This function inserts the strings and/or characters args into the current buffer, at point, moving point forward. An error is signaled unless all args are either strings or characters. The value is nil.

This function is unlike the other insertion functions in that it relocates markers initially pointing at the insertion point, to point after the inserted text. If an overlay begins the insertion point, the inserted text falls outside the overlay; if a nonempty overlay ends at the insertion point, the inserted text falls inside that overlay.

Function: insert-char character &optional count inherit
This function inserts count instances of character into the current buffer before point. The argument count should be a number (nil means 1), and character must be a character. The value is nil.

This function does not convert unibyte character codes 128 through 255 to multibyte characters, not even if the current buffer is a multibyte buffer. See section 33.2 Converting Text Representations.

If inherit is non-nil, then the inserted characters inherit sticky text properties from the two characters before and after the insertion point. See section 32.19.6 Stickiness of Text Properties.

Function: insert-buffer-substring from-buffer-or-name &optional start end
This function inserts a portion of buffer from-buffer-or-name (which must already exist) into the current buffer before point. The text inserted is the region from start and end. (These arguments default to the beginning and end of the accessible portion of that buffer.) This function returns nil.

In this example, the form is executed with buffer `bar' as the current buffer. We assume that buffer `bar' is initially empty.
---------- Buffer: foo ----------
We hold these truths to be self-evident, that all
---------- Buffer: foo ----------

(insert-buffer-substring "foo" 1 20)
     => nil

---------- Buffer: bar ----------
We hold these truth-!-
---------- Buffer: bar ----------
See section 32.19.6 Stickiness of Text Properties, for other insertion functions that inherit text properties from the nearby text in addition to inserting it. Whitespace inserted by indentation functions also inherits text properties.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.5 User-Level Insertion Commands

This section describes higher-level commands for inserting text, commands intended primarily for the user but useful also in Lisp programs.

Command: insert-buffer from-buffer-or-name
This command inserts the entire contents of from-buffer-or-name (which must exist) into the current buffer after point. It leaves the mark after the inserted text. The value is nil.

Command: self-insert-command count
This command inserts the last character typed; it does so count times, before point, and returns nil. Most printing characters are bound to this command. In routine use, self-insert-command is the most frequently called function in Emacs, but programs rarely use it except to install it on a keymap.

In an interactive call, count is the numeric prefix argument.

This command calls auto-fill-function whenever that is non-nil and the character inserted is in the table auto-fill-chars (see section 32.14 Auto Filling).

This command performs abbrev expansion if Abbrev mode is enabled and the inserted character does not have word-constituent syntax. (See section 36. Abbrevs and Abbrev Expansion, and 35.2.1 Table of Syntax Classes.)

This is also responsible for calling blink-paren-function when the inserted character has close parenthesis syntax (see section 38.14 Blinking Parentheses).

Do not try substituting your own definition of self-insert-command for the standard one. The editor command loop handles this function specially.

Command: newline &optional number-of-newlines
This command inserts newlines into the current buffer before point. If number-of-newlines is supplied, that many newline characters are inserted.

This function calls auto-fill-function if the current column number is greater than the value of fill-column and number-of-newlines is nil. Typically what auto-fill-function does is insert a newline; thus, the overall result in this case is to insert two newlines at different places: one at point, and another earlier in the line. newline does not auto-fill if number-of-newlines is non-nil.

This command indents to the left margin if that is not zero. See section 32.12 Margins for Filling.

The value returned is nil. In an interactive call, count is the numeric prefix argument.

Command: split-line
This command splits the current line, moving the portion of the line after point down vertically so that it is on the next line directly below where it was before. Whitespace is inserted as needed at the beginning of the lower line, using the indent-to function. split-line returns the position of point.

Programs hardly ever use this function.

Variable: overwrite-mode
This variable controls whether overwrite mode is in effect. The value should be overwrite-mode-textual, overwrite-mode-binary, or nil. overwrite-mode-textual specifies textual overwrite mode (treats newlines and tabs specially), and overwrite-mode-binary specifies binary overwrite mode (treats newlines and tabs like any other characters).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.6 Deleting Text

Deletion means removing part of the text in a buffer, without saving it in the kill ring (see section 32.8 The Kill Ring). Deleted text can't be yanked, but can be reinserted using the undo mechanism (see section 32.9 Undo). Some deletion functions do save text in the kill ring in some special cases.

All of the deletion functions operate on the current buffer, and all return a value of nil.

Command: erase-buffer
This function deletes the entire text of the current buffer, leaving it empty. If the buffer is read-only, it signals a buffer-read-only error; if some of the text in it is read-only, it signals a text-read-only error. Otherwise, it deletes the text without asking for any confirmation. It returns nil.

Normally, deleting a large amount of text from a buffer inhibits further auto-saving of that buffer "because it has shrunk". However, erase-buffer does not do this, the idea being that the future text is not really related to the former text, and its size should not be compared with that of the former text.

Command: delete-region start end
This command deletes the text between positions start and end in the current buffer, and returns nil. If point was inside the deleted region, its value afterward is start. Otherwise, point relocates with the surrounding text, as markers do.

Function: delete-and-extract-region start end
This function deletes the text between positions start and end in the current buffer, and returns a string containing the text just deleted.

If point was inside the deleted region, its value afterward is start. Otherwise, point relocates with the surrounding text, as markers do.

Command: delete-char count &optional killp
This command deletes count characters directly after point, or before point if count is negative. If killp is non-nil, then it saves the deleted characters in the kill ring.

In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.

The value returned is always nil.

Command: delete-backward-char count &optional killp
This command deletes count characters directly before point, or after point if count is negative. If killp is non-nil, then it saves the deleted characters in the kill ring.

In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.

The value returned is always nil.

Command: backward-delete-char-untabify count &optional killp
This command deletes count characters backward, changing tabs into spaces. When the next character to be deleted is a tab, it is first replaced with the proper number of spaces to preserve alignment and then one of those spaces is deleted instead of the tab. If killp is non-nil, then the command saves the deleted characters in the kill ring.

Conversion of tabs to spaces happens only if count is positive. If it is negative, exactly -count characters after point are deleted.

In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.

The value returned is always nil.

User Option: backward-delete-char-untabify-method
This option specifies how backward-delete-char-untabify should deal with whitespace. Possible values include untabify, the default, meaning convert a tab to many spaces and delete one; hungry, meaning delete all the whitespace characters before point with one command, and nil, meaning do nothing special for whitespace characters.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.7 User-Level Deletion Commands

This section describes higher-level commands for deleting text, commands intended primarily for the user but useful also in Lisp programs.

Command: delete-horizontal-space
This function deletes all spaces and tabs around point. It returns nil.

In the following examples, we call delete-horizontal-space four times, once on each line, with point between the second and third characters on the line each time.
---------- Buffer: foo ----------
I -!-thought
I -!-     thought
We-!- thought
Yo-!-u thought
---------- Buffer: foo ----------

(delete-horizontal-space)   ; Four times.
     => nil

---------- Buffer: foo ----------
Ithought
Ithought
Wethought
You thought
---------- Buffer: foo ----------
Command: delete-indentation &optional join-following-p
This function joins the line point is on to the previous line, deleting any whitespace at the join and in some cases replacing it with one space. If join-following-p is non-nil, delete-indentation joins this line to the following line instead. The function returns nil.

If there is a fill prefix, and the second of the lines being joined starts with the prefix, then delete-indentation deletes the fill prefix before joining the lines. See section 32.12 Margins for Filling.

In the example below, point is located on the line starting `events', and it makes no difference if there are trailing spaces in the preceding line.
---------- Buffer: foo ----------
When in the course of human
-!-    events, it becomes necessary
---------- Buffer: foo ----------

(delete-indentation)
     => nil

---------- Buffer: foo ----------
When in the course of human-!- events, it becomes necessary
---------- Buffer: foo ----------
After the lines are joined, the function fixup-whitespace is responsible for deciding whether to leave a space at the junction.

Function: fixup-whitespace
This function replaces all the whitespace surrounding point with either one space or no space, according to the context. It returns nil.

At the beginning or end of a line, the appropriate amount of space is none. Before a character with close parenthesis syntax, or after a character with open parenthesis or expression-prefix syntax, no space is also appropriate. Otherwise, one space is appropriate. See section 35.2.1 Table of Syntax Classes.

In the example below, fixup-whitespace is called the first time with point before the word `spaces' in the first line. For the second invocation, point is directly after the `('.
---------- Buffer: foo ----------
This has too many     -!-spaces
This has too many spaces at the start of (-!-   this list)
---------- Buffer: foo ----------

(fixup-whitespace)
     => nil
(fixup-whitespace)
     => nil

---------- Buffer: foo ----------
This has too many spaces
This has too many spaces at the start of (this list)
---------- Buffer: foo ----------
Command: just-one-space
This command replaces any spaces and tabs around point with a single space. It returns nil.

Command: delete-blank-lines
This function deletes blank lines surrounding point. If point is on a blank line with one or more blank lines before or after it, then all but one of them are deleted. If point is on an isolated blank line, then it is deleted. If point is on a nonblank line, the command deletes all blank lines following it.

A blank line is defined as a line containing only tabs and spaces.

delete-blank-lines returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.8 The Kill Ring

Kill functions delete text like the deletion functions, but save it so that the user can reinsert it by yanking. Most of these functions have `kill-' in their name. By contrast, the functions whose names start with `delete-' normally do not save text for yanking (though they can still be undone); these are "deletion" functions.

Most of the kill commands are primarily for interactive use, and are not described here. What we do describe are the functions provided for use in writing such commands. You can use these functions to write commands for killing text. When you need to delete text for internal purposes within a Lisp function, you should normally use deletion functions, so as not to disturb the kill ring contents. See section 32.6 Deleting Text.

Killed text is saved for later yanking in the kill ring. This is a list that holds a number of recent kills, not just the last text kill. We call this a "ring" because yanking treats it as having elements in a cyclic order. The list is kept in the variable kill-ring, and can be operated on with the usual functions for lists; there are also specialized functions, described in this section, that treat it as a ring.

Some people think this use of the word "kill" is unfortunate, since it refers to operations that specifically do not destroy the entities "killed". This is in sharp contrast to ordinary life, in which death is permanent and "killed" entities do not come back to life. Therefore, other metaphors have been proposed. For example, the term "cut ring" makes sense to people who, in pre-computer days, used scissors and paste to cut up and rearrange manuscripts. However, it would be difficult to change the terminology now.

32.8.1 Kill Ring Concepts

What text looks like in the kill ring.

32.8.2 Functions for Killing

Functions that kill text.

32.8.3 Functions for Yanking

Commands that access the kill ring.

32.8.4 Low-Level Kill Ring

Functions and variables for kill ring access.

32.8.5 Internals of the Kill Ring

Variables that hold kill-ring data.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.8.1 Kill Ring Concepts

The kill ring records killed text as strings in a list, most recent first. A short kill ring, for example, might look like this:
("some text" "a different piece of text" "even older text")
When the list reaches kill-ring-max entries in length, adding a new entry automatically deletes the last entry.

When kill commands are interwoven with other commands, each kill command makes a new entry in the kill ring. Multiple kill commands in succession build up a single kill-ring entry, which would be yanked as a unit; the second and subsequent consecutive kill commands add text to the entry made by the first one.

For yanking, one entry in the kill ring is designated the "front" of the ring. Some yank commands "rotate" the ring by designating a different element as the "front." But this virtual rotation doesn't change the list itself--the most recent entry always comes first in the list.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.8.2 Functions for Killing

kill-region is the usual subroutine for killing text. Any command that calls this function is a "kill command" (and should probably have `kill' in its name). kill-region puts the newly killed text in a new element at the beginning of the kill ring or adds it to the most recent element. It determines automatically (using last-command) whether the previous command was a kill command, and if so appends the killed text to the most recent entry.

Command: kill-region start end
This function kills the text in the region defined by start and end. The text is deleted but saved in the kill ring, along with its text properties. The value is always nil.

In an interactive call, start and end are point and the mark.

If the buffer or text is read-only, kill-region modifies the kill ring just the same, then signals an error without modifying the buffer. This is convenient because it lets the user use a series of kill commands to copy text from a read-only buffer into the kill ring.

User Option: kill-read-only-ok
If this option is non-nil, kill-region does not signal an error if the buffer or text is read-only. Instead, it simply returns, updating the kill ring but not changing the buffer.

Command: copy-region-as-kill start end
This command saves the region defined by start and end on the kill ring (including text properties), but does not delete the text from the buffer. It returns nil. It also indicates the extent of the text copied by moving the cursor momentarily, or by displaying a message in the echo area.

The command does not set this-command to kill-region, so a subsequent kill command does not append to the same kill ring entry.

Don't call copy-region-as-kill in Lisp programs unless you aim to support Emacs 18. For newer Emacs versions, it is better to use kill-new or kill-append instead. See section 32.8.4 Low-Level Kill Ring.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.8.3 Functions for Yanking

Yanking means reinserting an entry of previously killed text from the kill ring. The text properties are copied too.

Command: yank &optional arg
This command inserts before point the text in the first entry in the kill ring. It positions the mark at the beginning of that text, and point at the end.

If arg is a list (which occurs interactively when the user types C-u with no digits), then yank inserts the text as described above, but puts point before the yanked text and puts the mark after it.

If arg is a number, then yank inserts the argth most recently killed text--the argth element of the kill ring list.

yank does not alter the contents of the kill ring or rotate it. It returns nil.

Command: yank-pop arg
This command replaces the just-yanked entry from the kill ring with a different entry from the kill ring.

This is allowed only immediately after a yank or another yank-pop. At such a time, the region contains text that was just inserted by yanking. yank-pop deletes that text and inserts in its place a different piece of killed text. It does not add the deleted text to the kill ring, since it is already in the kill ring somewhere.

If arg is nil, then the replacement text is the previous element of the kill ring. If arg is numeric, the replacement is the argth previous kill. If arg is negative, a more recent kill is the replacement.

The sequence of kills in the kill ring wraps around, so that after the oldest one comes the newest one, and before the newest one goes the oldest.

The return value is always nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.8.4 Low-Level Kill Ring

These functions and variables provide access to the kill ring at a lower level, but still convenient for use in Lisp programs, because they take care of interaction with window system selections (see section 29.18 Window System Selections).

Function: current-kill n &optional do-not-move
The function current-kill rotates the yanking pointer, which designates the "front" of the kill ring, by n places (from newer kills to older ones), and returns the text at that place in the ring.

If the optional second argument do-not-move is non-nil, then current-kill doesn't alter the yanking pointer; it just returns the nth kill, counting from the current yanking pointer.

If n is zero, indicating a request for the latest kill, current-kill calls the value of interprogram-paste-function (documented below) before consulting the kill ring.

Function: kill-new string
This function puts the text string into the kill ring as a new entry at the front of the ring. It discards the oldest entry if appropriate. It also invokes the value of interprogram-cut-function (see below).

Function: kill-append string before-p
This function appends the text string to the first entry in the kill ring. Normally string goes at the end of the entry, but if before-p is non-nil, it goes at the beginning. This function also invokes the value of interprogram-cut-function (see below).

Variable: interprogram-paste-function
This variable provides a way of transferring killed text from other programs, when you are using a window system. Its value should be nil or a function of no arguments.

If the value is a function, current-kill calls it to get the "most recent kill". If the function returns a non-nil value, then that value is used as the "most recent kill". If it returns nil, then the first element of kill-ring is used.

The normal use of this hook is to get the window system's primary selection as the most recent kill, even if the selection belongs to another application. See section 29.18 Window System Selections.

Variable: interprogram-cut-function
This variable provides a way of communicating killed text to other programs, when you are using a window system. Its value should be nil or a function of one argument.

If the value is a function, kill-new and kill-append call it with the new first element of the kill ring as an argument.

The normal use of this hook is to set the window system's primary selection from the newly killed text. See section 29.18 Window System Selections.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.8.5 Internals of the Kill Ring

The variable kill-ring holds the kill ring contents, in the form of a list of strings. The most recent kill is always at the front of the list.

The kill-ring-yank-pointer variable points to a link in the kill ring list, whose CAR is the text to yank next. We say it identifies the "front" of the ring. Moving kill-ring-yank-pointer to a different link is called rotating the kill ring. We call the kill ring a "ring" because the functions that move the yank pointer wrap around from the end of the list to the beginning, or vice-versa. Rotation of the kill ring is virtual; it does not change the value of kill-ring.

Both kill-ring and kill-ring-yank-pointer are Lisp variables whose values are normally lists. The word "pointer" in the name of the kill-ring-yank-pointer indicates that the variable's purpose is to identify one element of the list for use by the next yank command.

The value of kill-ring-yank-pointer is always eq to one of the links in the kill ring list. The element it identifies is the CAR of that link. Kill commands, which change the kill ring, also set this variable to the value of kill-ring. The effect is to rotate the ring so that the newly killed text is at the front.

Here is a diagram that shows the variable kill-ring-yank-pointer pointing to the second entry in the kill ring ("some text" "a different piece of text" "yet older text").
kill-ring                  ---- kill-ring-yank-pointer
  |                       |
  |                       v
  |     --- ---          --- ---      --- ---
   --> |   |   |------> |   |   |--> |   |   |--> nil
        --- ---          --- ---      --- ---
         |                |            |
         |                |            |
         |                |             -->"yet older text"
         |                |
         |                 --> "a different piece of text"
         |
          --> "some text"
This state of affairs might occur after C-y (yank) immediately followed by M-y (yank-pop).

Variable: kill-ring
This variable holds the list of killed text sequences, most recently killed first.

Variable: kill-ring-yank-pointer
This variable's value indicates which element of the kill ring is at the "front" of the ring for yanking. More precisely, the value is a tail of the value of kill-ring, and its CAR is the kill string that C-y should yank.

User Option: kill-ring-max
The value of this variable is the maximum length to which the kill ring can grow, before elements are thrown away at the end. The default value for kill-ring-max is 30.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.9 Undo

Most buffers have an undo list, which records all changes made to the buffer's text so that they can be undone. (The buffers that don't have one are usually special-purpose buffers for which Emacs assumes that undoing is not useful.) All the primitives that modify the text in the buffer automatically add elements to the front of the undo list, which is in the variable buffer-undo-list.

Variable: buffer-undo-list
This variable's value is the undo list of the current buffer. A value of t disables the recording of undo information.

Here are the kinds of elements an undo list can have:

position
This kind of element records a previous value of point; undoing this element moves point to position. Ordinary cursor motion does not make any sort of undo record, but deletion operations use these entries to record where point was before the command.

(beg . end)
This kind of element indicates how to delete text that was inserted. Upon insertion, the text occupied the range beg--end in the buffer.

(text . position)
This kind of element indicates how to reinsert text that was deleted. The deleted text itself is the string text. The place to reinsert it is (abs position).

(t high . low)
This kind of element indicates that an unmodified buffer became modified. The elements high and low are two integers, each recording 16 bits of the visited file's modification time as of when it was previously visited or saved. primitive-undo uses those values to determine whether to mark the buffer as unmodified once again; it does so only if the file's modification time matches those numbers.

(nil property value beg . end)
This kind of element records a change in a text property. Here's how you might undo the change:
(put-text-property beg end property value)
(marker . adjustment)
This kind of element records the fact that the marker marker was relocated due to deletion of surrounding text, and that it moved adjustment character positions. Undoing this element moves marker - adjustment characters.

nil
This element is a boundary. The elements between two boundaries are called a change group; normally, each change group corresponds to one keyboard command, and undo commands normally undo an entire group as a unit.

Function: undo-boundary
This function places a boundary element in the undo list. The undo command stops at such a boundary, and successive undo commands undo to earlier and earlier boundaries. This function returns nil.

The editor command loop automatically creates an undo boundary before each key sequence is executed. Thus, each undo normally undoes the effects of one command. Self-inserting input characters are an exception. The command loop makes a boundary for the first such character; the next 19 consecutive self-inserting input characters do not make boundaries, and then the 20th does, and so on as long as self-inserting characters continue.

All buffer modifications add a boundary whenever the previous undoable change was made in some other buffer. This is to ensure that each command makes a boundary in each buffer where it makes changes.

Calling this function explicitly is useful for splitting the effects of a command into more than one unit. For example, query-replace calls undo-boundary after each replacement, so that the user can undo individual replacements one by one.

Function: primitive-undo count list
This is the basic function for undoing elements of an undo list. It undoes the first count elements of list, returning the rest of list. You could write this function in Lisp, but it is convenient to have it in C.

primitive-undo adds elements to the buffer's undo list when it changes the buffer. Undo commands avoid confusion by saving the undo list value at the beginning of a sequence of undo operations. Then the undo operations use and update the saved value. The new elements added by undoing are not part of this saved value, so they don't interfere with continuing to undo.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.10 Maintaining Undo Lists

This section describes how to enable and disable undo information for a given buffer. It also explains how the undo list is truncated automatically so it doesn't get too big.

Recording of undo information in a newly created buffer is normally enabled to start with; but if the buffer name starts with a space, the undo recording is initially disabled. You can explicitly enable or disable undo recording with the following two functions, or by setting buffer-undo-list yourself.

Command: buffer-enable-undo &optional buffer-or-name
This command enables recording undo information for buffer buffer-or-name, so that subsequent changes can be undone. If no argument is supplied, then the current buffer is used. This function does nothing if undo recording is already enabled in the buffer. It returns nil.

In an interactive call, buffer-or-name is the current buffer. You cannot specify any other buffer.

Command: buffer-disable-undo &optional buffer

Command: buffer-flush-undo &optional buffer
This function discards the undo list of buffer, and disables further recording of undo information. As a result, it is no longer possible to undo either previous changes or any subsequent changes. If the undo list of buffer is already disabled, this function has no effect.

This function returns nil.

The name buffer-flush-undo is not considered obsolete, but the preferred name is buffer-disable-undo.

As editing continues, undo lists get longer and longer. To prevent them from using up all available memory space, garbage collection trims them back to size limits you can set. (For this purpose, the "size" of an undo list measures the cons cells that make up the list, plus the strings of deleted text.) Two variables control the range of acceptable sizes: undo-limit and undo-strong-limit.

Variable: undo-limit
This is the soft limit for the acceptable size of an undo list. The change group at which this size is exceeded is the last one kept.

Variable: undo-strong-limit
This is the upper limit for the acceptable size of an undo list. The change group at which this size is exceeded is discarded itself (along with all older change groups). There is one exception: the very latest change group is never discarded no matter how big it is.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.11 Filling

Filling means adjusting the lengths of lines (by moving the line breaks) so that they are nearly (but no greater than) a specified maximum width. Additionally, lines can be justified, which means inserting spaces to make the left and/or right margins line up precisely. The width is controlled by the variable fill-column. For ease of reading, lines should be no longer than 70 or so columns.

You can use Auto Fill mode (see section 32.14 Auto Filling) to fill text automatically as you insert it, but changes to existing text may leave it improperly filled. Then you must fill the text explicitly.

Most of the commands in this section return values that are not meaningful. All the functions that do filling take note of the current left margin, current right margin, and current justification style (see section 32.12 Margins for Filling). If the current justification style is none, the filling functions don't actually do anything.

Several of the filling functions have an argument justify. If it is non-nil, that requests some kind of justification. It can be left, right, full, or center, to request a specific style of justification. If it is t, that means to use the current justification style for this part of the text (see current-justification, below). Any other value is treated as full.

When you call the filling functions interactively, using a prefix argument implies the value full for justify.

Command: fill-paragraph justify
This command fills the paragraph at or after point. If justify is non-nil, each line is justified as well. It uses the ordinary paragraph motion commands to find paragraph boundaries. See section `Paragraphs' in The GNU Emacs Manual.

Command: fill-region start end &optional justify nosqueeze to-eop
This command fills each of the paragraphs in the region from start to end. It justifies as well if justify is non-nil.

If nosqueeze is non-nil, that means to leave whitespace other than line breaks untouched. If to-eop is non-nil, that means to keep filling to the end of the paragraph--or the next hard newline, if use-hard-newlines is enabled (see below).

The variable paragraph-separate controls how to distinguish paragraphs. See section 34.8 Standard Regular Expressions Used in Editing.

Command: fill-individual-paragraphs start end &optional justify citation-regexp
This command fills each paragraph in the region according to its individual fill prefix. Thus, if the lines of a paragraph were indented with spaces, the filled paragraph will remain indented in the same fashion.

The first two arguments, start and end, are the beginning and end of the region to be filled. The third and fourth arguments, justify and citation-regexp, are optional. If justify is non-nil, the paragraphs are justified as well as filled. If citation-regexp is non-nil, it means the function is operating on a mail message and therefore should not fill the header lines. If citation-regexp is a string, it is used as a regular expression; if it matches the beginning of a line, that line is treated as a citation marker.

Ordinarily, fill-individual-paragraphs regards each change in indentation as starting a new paragraph. If fill-individual-varying-indent is non-nil, then only separator lines separate paragraphs. That mode can handle indented paragraphs with additional indentation on the first line.

User Option: fill-individual-varying-indent
This variable alters the action of fill-individual-paragraphs as described above.

Command: fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
This command considers a region of text as a single paragraph and fills it. If the region was made up of many paragraphs, the blank lines between paragraphs are removed. This function justifies as well as filling when justify is non-nil.

In an interactive call, any prefix argument requests justification.

If nosqueeze is non-nil, that means to leave whitespace other than line breaks untouched. If squeeze-after is non-nil, it specifies a position in the region, and means don't canonicalize spaces before that position.

In Adaptive Fill mode, this command calls fill-context-prefix to choose a fill prefix by default. See section 32.13 Adaptive Fill Mode.

Command: justify-current-line &optional how eop nosqueeze
This command inserts spaces between the words of the current line so that the line ends exactly at fill-column. It returns nil.

The argument how, if non-nil specifies explicitly the style of justification. It can be left, right, full, center, or none. If it is t, that means to do follow specified justification style (see current-justification, below). nil means to do full justification.

If eop is non-nil, that means do left-justification if current-justification specifies full justification. This is used for the last line of a paragraph; even if the paragraph as a whole is fully justified, the last line should not be.

If nosqueeze is non-nil, that means do not change interior whitespace.

User Option: default-justification
This variable's value specifies the style of justification to use for text that doesn't specify a style with a text property. The possible values are left, right, full, center, or none. The default value is left.

Function: current-justification
This function returns the proper justification style to use for filling the text around point.

User Option: sentence-end-double-space
If this variable is non-nil, a period followed by just one space does not count as the end of a sentence, and the filling functions avoid breaking the line at such a place.

Variable: fill-paragraph-function
This variable provides a way for major modes to override the filling of paragraphs. If the value is non-nil, fill-paragraph calls this function to do the work. If the function returns a non-nil value, fill-paragraph assumes the job is done, and immediately returns that value.

The usual use of this feature is to fill comments in programming language modes. If the function needs to fill a paragraph in the usual way, it can do so as follows:
(let ((fill-paragraph-function nil))
  (fill-paragraph arg))
Variable: use-hard-newlines
If this variable is non-nil, the filling functions do not delete newlines that have the hard text property. These "hard newlines" act as paragraph separators.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.12 Margins for Filling

User Option: fill-prefix
This buffer-local variable specifies a string of text that appears at the beginning of normal text lines and should be disregarded when filling them. Any line that fails to start with the fill prefix is considered the start of a paragraph; so is any line that starts with the fill prefix followed by additional whitespace. Lines that start with the fill prefix but no additional whitespace are ordinary text lines that can be filled together. The resulting filled lines also start with the fill prefix.

The fill prefix follows the left margin whitespace, if any.

User Option: fill-column
This buffer-local variable specifies the maximum width of filled lines. Its value should be an integer, which is a number of columns. All the filling, justification, and centering commands are affected by this variable, including Auto Fill mode (see section 32.14 Auto Filling).

As a practical matter, if you are writing text for other people to read, you should set fill-column to no more than 70. Otherwise the line will be too long for people to read comfortably, and this can make the text seem clumsy.

Variable: default-fill-column
The value of this variable is the default value for fill-column in buffers that do not override it. This is the same as (default-value 'fill-column).

The default value for default-fill-column is 70.

Command: set-left-margin from to margin
This sets the left-margin property on the text from from to to to the value margin. If Auto Fill mode is enabled, this command also refills the region to fit the new margin.

Command: set-right-margin from to margin
This sets the right-margin property on the text from from to to to the value margin. If Auto Fill mode is enabled, this command also refills the region to fit the new margin.

Function: current-left-margin
This function returns the proper left margin value to use for filling the text around point. The value is the sum of the left-margin property of the character at the start of the current line (or zero if none), and the value of the variable left-margin.

Function: current-fill-column
This function returns the proper fill column value to use for filling the text around point. The value is the value of the fill-column variable, minus the value of the right-margin property of the character after point.

Command: move-to-left-margin &optional n force
This function moves point to the left margin of the current line. The column moved to is determined by calling the function current-left-margin. If the argument n is non-nil, move-to-left-margin moves forward n-1 lines first.

If force is non-nil, that says to fix the line's indentation if that doesn't match the left margin value.

Function: delete-to-left-margin &optional from to
This function removes left margin indentation from the text between from and to. The amount of indentation to delete is determined by calling current-left-margin. In no case does this function delete non-whitespace. If from and to are omitted, they default to the whole buffer.

Function: indent-to-left-margin
This is the default indent-line-function, used in Fundamental mode, Text mode, etc. Its effect is to adjust the indentation at the beginning of the current line to the value specified by the variable left-margin. This may involve either inserting or deleting whitespace.

Variable: left-margin
This variable specifies the base left margin column. In Fundamental mode, C-j indents to this column. This variable automatically becomes buffer-local when set in any fashion.

Variable: fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line at certain places. Its value should be a function. This function is called during filling, with no arguments and with point located at the place where a break is being considered. If the function returns non-nil, then the line won't be broken there.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.13 Adaptive Fill Mode

Adaptive Fill mode chooses a fill prefix automatically from the text in each paragraph being filled.

User Option: adaptive-fill-mode
Adaptive Fill mode is enabled when this variable is non-nil. It is t by default.

Function: fill-context-prefix from to
This function implements the heart of Adaptive Fill mode; it chooses a fill prefix based on the text between from and to. It does this by looking at the first two lines of the paragraph, based on the variables described below.

User Option: adaptive-fill-regexp
This variable holds a regular expression to control Adaptive Fill mode. Adaptive Fill mode matches this regular expression against the text starting after the left margin whitespace (if any) on a line; the characters it matches are that line's candidate for the fill prefix.

User Option: adaptive-fill-first-line-regexp
In a one-line paragraph, if the candidate fill prefix matches this regular expression, or if it matches comment-start-skip, then it is used--otherwise, spaces amounting to the same width are used instead.

However, the fill prefix is never taken from a one-line paragraph if it would act as a paragraph starter on subsequent lines.

User Option: adaptive-fill-function
You can specify more complex ways of choosing a fill prefix automatically by setting this variable to a function. The function is called when adaptive-fill-regexp does not match, with point after the left margin of a line, and it should return the appropriate fill prefix based on that line. If it returns nil, that means it sees no fill prefix in that line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.14 Auto Filling

Auto Fill mode is a minor mode that fills lines automatically as text is inserted. This section describes the hook used by Auto Fill mode. For a description of functions that you can call explicitly to fill and justify existing text, see 32.11 Filling.

Auto Fill mode also enables the functions that change the margins and justification style to refill portions of the text. See section 32.12 Margins for Filling.

Variable: auto-fill-function
The value of this variable should be a function (of no arguments) to be called after self-inserting a character from the table auto-fill-chars. It may be nil, in which case nothing special is done in that case.

The value of auto-fill-function is do-auto-fill when Auto-Fill mode is enabled. That is a function whose sole purpose is to implement the usual strategy for breaking a line.

In older Emacs versions, this variable was named auto-fill-hook, but since it is not called with the standard convention for hooks, it was renamed to auto-fill-function in version 19.

Variable: normal-auto-fill-function
This variable specifies the function to use for auto-fill-function, if and when Auto Fill is turned on. Major modes can set buffer-local values for this variable to alter how Auto Fill works.

Variable: auto-fill-chars
A char table of characters which invoke auto-fill-function when self-inserted--space and newline in most language environments. They have an entry t in the table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.15 Sorting Text

The sorting functions described in this section all rearrange text in a buffer. This is in contrast to the function sort, which rearranges the order of the elements of a list (see section 5.6.3 Functions that Rearrange Lists). The values returned by these functions are not meaningful.

Function: sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
This function is the general text-sorting routine that subdivides a buffer into records and then sorts them. Most of the commands in this section use this function.

To understand how sort-subr works, consider the whole accessible portion of the buffer as being divided into disjoint pieces called sort records. The records may or may not be contiguous, but they must not overlap. A portion of each sort record (perhaps all of it) is designated as the sort key. Sorting rearranges the records in order by their sort keys.

Usually, the records are rearranged in order of ascending sort key. If the first argument to the sort-subr function, reverse, is non-nil, the sort records are rearranged in order of descending sort key.

The next four arguments to sort-subr are functions that are called to move point across a sort record. They are called many times from within sort-subr.

nextrecfun is called with point at the end of a record. This function moves point to the start of the next record. The first record is assumed to start at the position of point when sort-subr is called. Therefore, you should usually move point to the beginning of the buffer before calling sort-subr.
This function can indicate there are no more sort records by leaving point at the end of the buffer.

endrecfun is called with point within a record. It moves point to the end of the record.

startkeyfun is called to move point from the start of a record to the start of the sort key. This argument is optional; if it is omitted, the whole record is the sort key. If supplied, the function should either return a non-nil value to be used as the sort key, or return nil to indicate that the sort key is in the buffer starting at point. In the latter case, endkeyfun is called to find the end of the sort key.

endkeyfun is called to move point from the start of the sort key to the end of the sort key. This argument is optional. If startkeyfun returns nil and this argument is omitted (or nil), then the sort key extends to the end of the record. There is no need for endkeyfun if startkeyfun returns a non-nil value.

As an example of sort-subr, here is the complete function definition for sort-lines:
;; Note that the first two lines of doc string
;; are effectively one line when viewed by a user.
(defun sort-lines (reverse beg end)
  "Sort lines in region alphabetically;\
 argument means descending order.
Called from a program, there are three arguments:
REVERSE (non-nil means reverse order),\
 BEG and END (region to sort).
The variable `sort-fold-case' determines\
 whether alphabetic case affects
the sort order.
  (interactive "P\nr")
  (save-excursion
    (save-restriction
      (narrow-to-region beg end)
      (goto-char (point-min))
      (sort-subr reverse 'forward-line 'end-of-line))))
Here forward-line moves point to the start of the next record, and end-of-line moves point to the end of record. We do not pass the arguments startkeyfun and endkeyfun, because the entire record is used as the sort key.

The sort-paragraphs function is very much the same, except that its sort-subr call looks like this:
(sort-subr reverse
           (function
             (lambda ()
               (while (and (not (eobp))
                      (looking-at paragraph-separate))
                 (forward-line 1))))
           'forward-paragraph)
Markers pointing into any sort records are left with no useful position after sort-subr returns.

User Option: sort-fold-case
If this variable is non-nil, sort-subr and the other buffer sorting functions ignore case when comparing strings.

Command: sort-regexp-fields reverse record-regexp key-regexp start end
This command sorts the region between start and end alphabetically as specified by record-regexp and key-regexp. If reverse is a negative integer, then sorting is in reverse order.

Alphabetical sorting means that two sort keys are compared by comparing the first characters of each, the second characters of each, and so on. If a mismatch is found, it means that the sort keys are unequal; the sort key whose character is less at the point of first mismatch is the lesser sort key. The individual characters are compared according to their numerical character codes in the Emacs character set.

The value of the record-regexp argument specifies how to divide the buffer into sort records. At the end of each record, a search is done for this regular expression, and the text that matches it is taken as the next record. For example, the regular expression `^.+$', which matches lines with at least one character besides a newline, would make each such line into a sort record. See section 34.2 Regular Expressions, for a description of the syntax and meaning of regular expressions.

The value of the key-regexp argument specifies what part of each record is the sort key. The key-regexp could match the whole record, or only a part. In the latter case, the rest of the record has no effect on the sorted order of records, but it is carried along when the record moves to its new position.

The key-regexp argument can refer to the text matched by a subexpression of record-regexp, or it can be a regular expression on its own.

If key-regexp is:

`\digit'
then the text matched by the digitth `\(...\)' parenthesis grouping in record-regexp is the sort key.

`\&'
then the whole record is the sort key.

a regular expression
then sort-regexp-fields searches for a match for the regular expression within the record. If such a match is found, it is the sort key. If there is no match for key-regexp within a record then that record is ignored, which means its position in the buffer is not changed. (The other records may move around it.)
For example, if you plan to sort all the lines in the region by the first word on each line starting with the letter `f', you should set record-regexp to `^.*$' and set key-regexp to `\<f\w*\>'. The resulting expression looks like this:
(sort-regexp-fields nil "^.*$" "\\"
                    (region-beginning)
                    (region-end))
If you call sort-regexp-fields interactively, it prompts for record-regexp and key-regexp in the minibuffer.

Command: sort-lines reverse start end
This command alphabetically sorts lines in the region between start and end. If reverse is non-nil, the sort is in reverse order.

Command: sort-paragraphs reverse start end
This command alphabetically sorts paragraphs in the region between start and end. If reverse is non-nil, the sort is in reverse order.

Command: sort-pages reverse start end
This command alphabetically sorts pages in the region between start and end. If reverse is non-nil, the sort is in reverse order.

Command: sort-fields field start end
This command sorts lines in the region between start and end, comparing them alphabetically by the fieldth field of each line. Fields are separated by whitespace and numbered starting from 1. If field is negative, sorting is by the -fieldth field from the end of the line. This command is useful for sorting tables.

Command: sort-numeric-fields field start end
This command sorts lines in the region between start and end, comparing them numerically by the fieldth field of each line. The specified field must contain a number in each line of the region. Fields are separated by whitespace and numbered starting from 1. If field is negative, sorting is by the -fieldth field from the end of the line. This command is useful for sorting tables.

Command: sort-columns reverse &optional beg end
This command sorts the lines in the region between beg and end, comparing them alphabetically by a certain range of columns. The column positions of beg and end bound the range of columns to sort on.

If reverse is non-nil, the sort is in reverse order.

One unusual thing about this command is that the entire line containing position beg, and the entire line containing position end, are included in the region sorted.

Note that sort-columns uses the sort utility program, and so cannot work properly on text containing tab characters. Use M-x untabify to convert tabs to spaces before sorting.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.16 Counting Columns

The column functions convert between a character position (counting characters from the beginning of the buffer) and a column position (counting screen characters from the beginning of a line).

These functions count each character according to the number of columns it occupies on the screen. This means control characters count as occupying 2 or 4 columns, depending upon the value of ctl-arrow, and tabs count as occupying a number of columns that depends on the value of tab-width and on the column where the tab begins. See section 38.16 Usual Display Conventions.

Column number computations ignore the width of the window and the amount of horizontal scrolling. Consequently, a column value can be arbitrarily high. The first (or leftmost) column is numbered 0.

Function: current-column
This function returns the horizontal position of point, measured in columns, counting from 0 at the left margin. The column position is the sum of the widths of all the displayed representations of the characters between the start of the current line and point.

For an example of using current-column, see the description of count-lines in 30.2.4 Motion by Text Lines.

Function: move-to-column column &optional force
This function moves point to column in the current line. The calculation of column takes into account the widths of the displayed representations of the characters between the start of the line and point.

If column column is beyond the end of the line, point moves to the end of the line. If column is negative, point moves to the beginning of the line.

If it is impossible to move to column column because that is in the middle of a multicolumn character such as a tab, point moves to the end of that character. However, if force is non-nil, and column is in the middle of a tab, then move-to-column converts the tab into spaces so that it can move precisely to column column. Other multicolumn characters can cause anomalies despite force, since there is no way to split them.

The argument force also has an effect if the line isn't long enough to reach column column; if it is t, that means to add whitespace at the end of the line to reach that column.

If column is not an integer, an error is signaled.

The return value is the column number actually moved to.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.17 Indentation

The indentation functions are used to examine, move to, and change whitespace that is at the beginning of a line. Some of the functions can also change whitespace elsewhere on a line. Columns and indentation count from zero at the left margin.

32.17.1 Indentation Primitives

Functions used to count and insert indentation.

32.17.2 Indentation Controlled by Major Mode

Customize indentation for different modes.

32.17.3 Indenting an Entire Region

Indent all the lines in a region.

32.17.4 Indentation Relative to Previous Lines

Indent the current line based on previous lines.

32.17.5 Adjustable "Tab Stops"

Adjustable, typewriter-like tab stops.

32.17.6 Indentation-Based Motion Commands

Move to first non-blank character.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.17.1 Indentation Primitives

This section describes the primitive functions used to count and insert indentation. The functions in the following sections use these primitives. See section 38.10 Width, for related functions.

Function: current-indentation
This function returns the indentation of the current line, which is the horizontal position of the first nonblank character. If the contents are entirely blank, then this is the horizontal position of the end of the line.

Command: indent-to column &optional minimum
This function indents from point with tabs and spaces until column is reached. If minimum is specified and non-nil, then at least that many spaces are inserted even if this requires going beyond column. Otherwise the function does nothing if point is already beyond column. The value is the column at which the inserted indentation ends.

The inserted whitespace characters inherit text properties from the surrounding text (usually, from the preceding text only). See section 32.19.6 Stickiness of Text Properties.

User Option: indent-tabs-mode
If this variable is non-nil, indentation functions can insert tabs as well as spaces. Otherwise, they insert only spaces. Setting this variable automatically makes it buffer-local in the current buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.17.2 Indentation Controlled by Major Mode

An important function of each major mode is to customize the TAB key to indent properly for the language being edited. This section describes the mechanism of the TAB key and how to control it. The functions in this section return unpredictable values.

Variable: indent-line-function
This variable's value is the function to be used by TAB (and various commands) to indent the current line. The command indent-according-to-mode does no more than call this function.

In Lisp mode, the value is the symbol lisp-indent-line; in C mode, c-indent-line; in Fortran mode, fortran-indent-line. In Fundamental mode, Text mode, and many other modes with no standard for indentation, the value is indent-to-left-margin (which is the default value).

Command: indent-according-to-mode
This command calls the function in indent-line-function to indent the current line in a way appropriate for the current major mode.

Command: indent-for-tab-command
This command calls the function in indent-line-function to indent the current line; however, if that function is indent-to-left-margin, insert-tab is called instead. (That is a trivial command that inserts a tab character.)

Command: newline-and-indent
This function inserts a newline, then indents the new line (the one following the newline just inserted) according to the major mode.

It does indentation by calling the current indent-line-function. In programming language modes, this is the same thing TAB does, but in some text modes, where TAB inserts a tab, newline-and-indent indents to the column specified by left-margin.

Command: reindent-then-newline-and-indent
This command reindents the current line, inserts a newline at point, and then indents the new line (the one following the newline just inserted).

This command does indentation on both lines according to the current major mode, by calling the current value of indent-line-function. In programming language modes, this is the same thing TAB does, but in some text modes, where TAB inserts a tab, reindent-then-newline-and-indent indents to the column specified by left-margin.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.17.3 Indenting an Entire Region

This section describes commands that indent all the lines in the region. They return unpredictable values.

Command: indent-region start end to-column
This command indents each nonblank line starting between start (inclusive) and end (exclusive). If to-column is nil, indent-region indents each nonblank line by calling the current mode's indentation function, the value of indent-line-function.

If to-column is non-nil, it should be an integer specifying the number of columns of indentation; then this function gives each line exactly that much indentation, by either adding or deleting whitespace.

If there is a fill prefix, indent-region indents each line by making it start with the fill prefix.

Variable: indent-region-function
The value of this variable is a function that can be used by indent-region as a short cut. It should take two arguments, the start and end of the region. You should design the function so that it will produce the same results as indenting the lines of the region one by one, but presumably faster.

If the value is nil, there is no short cut, and indent-region actually works line by line.

A short-cut function is useful in modes such as C mode and Lisp mode, where the indent-line-function must scan from the beginning of the function definition: applying it to each line would be quadratic in time. The short cut can update the scan information as it moves through the lines indenting them; this takes linear time. In a mode where indenting a line individually is fast, there is no need for a short cut.

indent-region with a non-nil argument to-column has a different meaning and does not use this variable.

Command: indent-rigidly start end count
This command indents all lines starting between start (inclusive) and end (exclusive) sideways by count columns. This "preserves the shape" of the affected region, moving it as a rigid unit. Consequently, this command is useful not only for indenting regions of unindented text, but also for indenting regions of formatted code.

For example, if count is 3, this command adds 3 columns of indentation to each of the lines beginning in the region specified.

In Mail mode, C-c C-y (mail-yank-original) uses indent-rigidly to indent the text copied from the message being replied to.

Function: indent-code-rigidly start end columns &optional nochange-regexp
This is like indent-rigidly, except that it doesn't alter lines that start within strings or comments.

In addition, it doesn't alter a line if nochange-regexp matches at the beginning of the line (if nochange-regexp is non-nil).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.17.4 Indentation Relative to Previous Lines

This section describes two commands that indent the current line based on the contents of previous lines.

Command: indent-relative &optional unindented-ok
This command inserts whitespace at point, extending to the same column as the next indent point of the previous nonblank line. An indent point is a non-whitespace character following whitespace. The next indent point is the first one at a column greater than the current column of point. For example, if point is underneath and to the left of the first non-blank character of a line of text, it moves to that column by inserting whitespace.

If the previous nonblank line has no next indent point (i.e., none at a great enough column position), indent-relative either does nothing (if unindented-ok is non-nil) or calls tab-to-tab-stop. Thus, if point is underneath and to the right of the last column of a short line of text, this command ordinarily moves point to the next tab stop by inserting whitespace.

The return value of indent-relative is unpredictable.

In the following example, point is at the beginning of the second line:
            This line is indented twelve spaces.
-!-The quick brown fox jumped.
Evaluation of the expression (indent-relative nil) produces the following:
            This line is indented twelve spaces.
            -!-The quick brown fox jumped.
In this next example, point is between the `m' and `p' of `jumped':
            This line is indented twelve spaces.
The quick brown fox jum-!-ped.
Evaluation of the expression (indent-relative nil) produces the following:
            This line is indented twelve spaces.
The quick brown fox jum  -!-ped.
Command: indent-relative-maybe
This command indents the current line like the previous nonblank line, by calling indent-relative with t as the unindented-ok argument. The return value is unpredictable.

If the previous nonblank line has no indent points beyond the current column, this command does nothing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.17.5 Adjustable "Tab Stops"

This section explains the mechanism for user-specified "tab stops" and the mechanisms that use and set them. The name "tab stops" is used because the feature is similar to that of the tab stops on a typewriter. The feature works by inserting an appropriate number of spaces and tab characters to reach the next tab stop column; it does not affect the display of tab characters in the buffer (see section 38.16 Usual Display Conventions). Note that the TAB character as input uses this tab stop feature only in a few major modes, such as Text mode.

Command: tab-to-tab-stop
This command inserts spaces or tabs before point, up to the next tab stop column defined by tab-stop-list. It searches the list for an element greater than the current column number, and uses that element as the column to indent to. It does nothing if no such element is found.

User Option: tab-stop-list
This variable is the list of tab stop columns used by tab-to-tab-stops. The elements should be integers in increasing order. The tab stop columns need not be evenly spaced.

Use M-x edit-tab-stops to edit the location of tab stops interactively.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.17.6 Indentation-Based Motion Commands

These commands, primarily for interactive use, act based on the indentation in the text.

Command: back-to-indentation
This command moves point to the first non-whitespace character in the current line (which is the line in which point is located). It returns nil.

Command: backward-to-indentation arg
This command moves point backward arg lines and then to the first nonblank character on that line. It returns nil.

Command: forward-to-indentation arg
This command moves point forward arg lines and then to the first nonblank character on that line. It returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.18 Case Changes

The case change commands described here work on text in the current buffer. See section 4.8 Case Conversion in Lisp, for case conversion functions that work on strings and characters. See section 4.9 The Case Table, for how to customize which characters are upper or lower case and how to convert them.

Command: capitalize-region start end
This function capitalizes all words in the region defined by start and end. To capitalize means to convert each word's first character to upper case and convert the rest of each word to lower case. The function returns nil.

If one end of the region is in the middle of a word, the part of the word within the region is treated as an entire word.

When capitalize-region is called interactively, start and end are point and the mark, with the smallest first.
---------- Buffer: foo ----------
This is the contents of the 5th foo.
---------- Buffer: foo ----------

(capitalize-region 1 44)
=> nil

---------- Buffer: foo ----------
This Is The Contents Of The 5th Foo.
---------- Buffer: foo ----------
Command: downcase-region start end
This function converts all of the letters in the region defined by start and end to lower case. The function returns nil.

When downcase-region is called interactively, start and end are point and the mark, with the smallest first.

Command: upcase-region start end
This function converts all of the letters in the region defined by start and end to upper case. The function returns nil.

When upcase-region is called interactively, start and end are point and the mark, with the smallest first.

Command: capitalize-word count
This function capitalizes count words after point, moving point over as it does. To capitalize means to convert each word's first character to upper case and convert the rest of each word to lower case. If count is negative, the function capitalizes the -count previous words but does not move point. The value is nil.

If point is in the middle of a word, the part of the word before point is ignored when moving forward. The rest is treated as an entire word.

When capitalize-word is called interactively, count is set to the numeric prefix argument.

Command: downcase-word count
This function converts the count words after point to all lower case, moving point over as it does. If count is negative, it converts the -count previous words but does not move point. The value is nil.

When downcase-word is called interactively, count is set to the numeric prefix argument.

Command: upcase-word count
This function converts the count words after point to all upper case, moving point over as it does. If count is negative, it converts the -count previous words but does not move point. The value is nil.

When upcase-word is called interactively, count is set to the numeric prefix argument.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19 Text Properties

Each character position in a buffer or a string can have a text property list, much like the property list of a symbol (see section 8.4 Property Lists). The properties belong to a particular character at a particular place, such as, the letter `T' at the beginning of this sentence or the first `o' in `foo'---if the same character occurs in two different places, the two occurrences generally have different properties.

Each property has a name and a value. Both of these can be any Lisp object, but the name is normally a symbol. The usual way to access the property list is to specify a name and ask what value corresponds to it.

If a character has a category property, we call it the category of the character. It should be a symbol. The properties of the symbol serve as defaults for the properties of the character.

Copying text between strings and buffers preserves the properties along with the characters; this includes such diverse functions as substring, insert, and buffer-substring.

32.19.1 Examining Text Properties

Looking at the properties of one character.

32.19.2 Changing Text Properties

Setting the properties of a range of text.

32.19.3 Text Property Search Functions

Searching for where a property changes value.

32.19.4 Properties with Special Meanings

Particular properties with special meanings.

32.19.5 Formatted Text Properties

Properties for representing formatting of text.

32.19.6 Stickiness of Text Properties

How inserted text gets properties from neighboring text.

32.19.7 Saving Text Properties in Files

Saving text properties in files, and reading them back.

32.19.8 Lazy Computation of Text Properties

Computing text properties in a lazy fashion only when text is examined.

32.19.9 Defining Clickable Text

Using text properties to make regions of text do something when you click on them.

32.19.10 Defining and Using Fields

The field property defines fields within the buffer.

32.19.11 Why Text Properties are not Intervals

Why text properties do not use Lisp-visible text intervals.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.1 Examining Text Properties

The simplest way to examine text properties is to ask for the value of a particular property of a particular character. For that, use get-text-property. Use text-properties-at to get the entire property list of a character. See section 32.19.3 Text Property Search Functions, for functions to examine the properties of a number of characters at once.

These functions handle both strings and buffers. Keep in mind that positions in a string start from 0, whereas positions in a buffer start from 1.

Function: get-text-property pos prop &optional object
This function returns the value of the prop property of the character after position pos in object (a buffer or string). The argument object is optional and defaults to the current buffer.

If there is no prop property strictly speaking, but the character has a category that is a symbol, then get-text-property returns the prop property of that symbol.

Function: get-char-property pos prop &optional object
This function is like get-text-property, except that it checks overlays first and then text properties. See section 38.9 Overlays.

The argument object may be a string, a buffer, or a window. If it is a window, then the buffer displayed in that window is used for text properties and overlays, but only the overlays active for that window are considered. If object is a buffer, then all overlays in that buffer are considered, as well as text properties. If object is a string, only text properties are considered, since strings never have overlays.

Function: text-properties-at position &optional object
This function returns the entire property list of the character at position in the string or buffer object. If object is nil, it defaults to the current buffer.

Variable: default-text-properties
This variable holds a property list giving default values for text properties. Whenever a character does not specify a value for a property, neither directly nor through a category symbol, the value stored in this list is used instead. Here is an example:
(setq default-text-properties '(foo 69))
;; Make sure character 1 has no properties of its own.
(set-text-properties 1 2 nil)
;; What we get, when we ask, is the default value.
(get-text-property 1 'foo)
     => 69
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.2 Changing Text Properties

The primitives for changing properties apply to a specified range of text in a buffer or string. The function set-text-properties (see end of section) sets the entire property list of the text in that range; more often, it is useful to add, change, or delete just certain properties specified by name.

Since text properties are considered part of the contents of the buffer (or string), and can affect how a buffer looks on the screen, any change in buffer text properties marks the buffer as modified. Buffer text property changes are undoable also (see section 32.9 Undo).

Function: put-text-property start end prop value &optional object
This function sets the prop property to value for the text between start and end in the string or buffer object. If object is nil, it defaults to the current buffer.

Function: add-text-properties start end props &optional object
This function adds or overrides text properties for the text between start and end in the string or buffer object. If object is nil, it defaults to the current buffer.

The argument props specifies which properties to add. It should have the form of a property list (see section 8.4 Property Lists): a list whose elements include the property names followed alternately by the corresponding values.

The return value is t if the function actually changed some property's value; nil otherwise (if props is nil or its values agree with those in the text).

For example, here is how to set the comment and face properties of a range of text:
(add-text-properties start end
                     '(comment t face highlight))
Function: remove-text-properties start end props &optional object
This function deletes specified text properties from the text between start and end in the string or buffer object. If object is nil, it defaults to the current buffer.

The argument props specifies which properties to delete. It should have the form of a property list (see section 8.4 Property Lists): a list whose elements are property names alternating with corresponding values. But only the names matter--the values that accompany them are ignored. For example, here's how to remove the face property.
(remove-text-properties start end '(face nil))
The return value is t if the function actually changed some property's value; nil otherwise (if props is nil or if no character in the specified text had any of those properties).

To remove all text properties from certain text, use set-text-properties and specify nil for the new property list.

Function: set-text-properties start end props &optional object
This function completely replaces the text property list for the text between start and end in the string or buffer object. If object is nil, it defaults to the current buffer.

The argument props is the new property list. It should be a list whose elements are property names alternating with corresponding values.

After set-text-properties returns, all the characters in the specified range have identical properties.

If props is nil, the effect is to get rid of all properties from the specified range of text. Here's an example:
(set-text-properties start end nil)
The easiest way to make a string with text properties is with propertize:

Function: propertize string &rest properties
This function returns a copy of string which has the text properties properties. These properties apply to all the characters in the string that is returned. Here is an example that constructs a string with a face property and a mouse-face property:
(propertize "foo" 'face 'italic
            'mouse-face 'bold-italic)
     => #("foo" 0 3 (mouse-face bold-italic face italic))
To put different properties on various parts of a string, you can construct each part with propertize and then combine them with concat:
(concat
 (propertize "foo" 'face 'italic
             'mouse-face 'bold-italic)
 " and "
 (propertize "bar" 'face 'italic
             'mouse-face 'bold-italic))
     => #("foo and bar"
                 0 3 (face italic mouse-face bold-italic)
                 3 8 nil
                 8 11 (face italic mouse-face bold-italic))
See also the function buffer-substring-no-properties (see section 32.2 Examining Buffer Contents) which copies text from the buffer but does not copy its properties.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.3 Text Property Search Functions

In typical use of text properties, most of the time several or many consecutive characters have the same value for a property. Rather than writing your programs to examine characters one by one, it is much faster to process chunks of text that have the same property value.

Here are functions you can use to do this. They use eq for comparing property values. In all cases, object defaults to the current buffer.

For high performance, it's very important to use the limit argument to these functions, especially the ones that search for a single property--otherwise, they may spend a long time scanning to the end of the buffer, if the property you are interested in does not change.

These functions do not move point; instead, they return a position (or nil). Remember that a position is always between two characters; the position returned by these functions is between two characters with different properties.

Function: next-property-change pos &optional object limit
The function scans the text forward from position pos in the string or buffer object till it finds a change in some text property, then returns the position of the change. In other words, it returns the position of the first character beyond pos whose properties are not identical to those of the character just after pos.

If limit is non-nil, then the scan ends at position limit. If there is no property change before that point, next-property-change returns limit.

The value is nil if the properties remain unchanged all the way to the end of object and limit is nil. If the value is non-nil, it is a position greater than or equal to pos. The value equals pos only when limit equals pos.

Here is an example of how to scan the buffer by chunks of text within which all properties are constant:
(while (not (eobp))
  (let ((plist (text-properties-at (point)))
        (next-change
         (or (next-property-change (point) (current-buffer))
             (point-max))))
    Process text from point to next-change...
    (goto-char next-change)))
Function: next-single-property-change pos prop &optional object limit
The function scans the text forward from position pos in the string or buffer object till it finds a change in the prop property, then returns the position of the change. In other words, it returns the position of the first character beyond pos whose prop property differs from that of the character just after pos.

If limit is non-nil, then the scan ends at position limit. If there is no property change before that point, next-single-property-change returns limit.

The value is nil if the property remains unchanged all the way to the end of object and limit is nil. If the value is non-nil, it is a position greater than or equal to pos; it equals pos only if limit equals pos.

Function: previous-property-change pos &optional object limit
This is like next-property-change, but scans back from pos instead of forward. If the value is non-nil, it is a position less than or equal to pos; it equals pos only if limit equals pos.

Function: previous-single-property-change pos prop &optional object limit
This is like next-single-property-change, but scans back from pos instead of forward. If the value is non-nil, it is a position less than or equal to pos; it equals pos only if limit equals pos.

Function: next-char-property-change pos &optional limit
This is like next-property-change except that it considers overlay properties as well as text properties, and if no change is found before the end of the buffer, it returns the maximum buffer position rather than nil (in this sense, it resembles the corresponding overlay function next-overlay-change, rather than next-property-change). There is no object operand because this function operates only on the current buffer. It returns the next address at which either kind of property changes.

Function: previous-char-property-change pos &optional limit
This is like next-char-property-change, but scans back from pos instead of forward, and returns the minimum buffer position if no change is found.

Function: next-single-char-property-change pos prop &optional object limit
This is like next-single-property-change except that it considers overlay properties as well as text properties, and if no change is found before the end of the object, it returns the maximum valid position in object rather than nil. Unlike next-char-property-change, this function does have an object operand; if object is not a buffer, only text-properties are considered.

Function: previous-single-char-property-change pos prop &optional object limit
This is like next-single-char-property-change, but scans back from pos instead of forward, and returns the minimum valid position in object if no change is found.

Function: text-property-any start end prop value &optional object
This function returns non-nil if at least one character between start and end has a property prop whose value is value. More precisely, it returns the position of the first such character. Otherwise, it returns nil.

The optional fifth argument, object, specifies the string or buffer to scan. Positions are relative to object. The default for object is the current buffer.

Function: text-property-not-all start end prop value &optional object
This function returns non-nil if at least one character between start and end does not have a property prop with value value. More precisely, it returns the position of the first such character. Otherwise, it returns nil.

The optional fifth argument, object, specifies the string or buffer to scan. Positions are relative to object. The default for object is the current buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.4 Properties with Special Meanings

Here is a table of text property names that have special built-in meanings. The following sections list a few additional special property names that control filling and property inheritance. All other names have no standard meaning, and you can use them as you like.

category
If a character has a category property, we call it the category of the character. It should be a symbol. The properties of the symbol serve as defaults for the properties of the character.

face
You can use the property face to control the font and color of text. See section 38.11 Faces, for more information.
In the simplest case, the value is a face name. It can also be a list; then each element can be any of these possibilities;

A face name (a symbol or string).

Starting in Emacs 21, a property list of face attributes. This has the form (keyword value ...), where each keyword is a face attribute name and value is a meaningful value for that attribute. With this feature, you do not need to create a face each time you want to specify a particular attribute for certain text. See section 38.11.3 Face Attributes.

A cons cell of the form (foreground-color . color-name) or (background-color . color-name). These elements specify just the foreground color or just the background color.
(foreground-color . color-name) is equivalent to (:foreground color-name), and likewise for the background.

See section 23.5 Font Lock Mode, for information on how to update face properties automatically based on the contents of the text.

mouse-face
The property mouse-face is used instead of face when the mouse is on or near the character. For this purpose, "near" means that all text between the character and where the mouse is have the same mouse-face property value.

fontified
This property, if non-nil, says that text in the buffer has had faces assigned automatically by a feature such as Font-Lock mode. See section 38.11.8 Automatic Face Assignment.

display
This property activates various features that change the way text is displayed. For example, it can make text appear taller or shorter, higher or lower, wider or narrow, or replaced with an image. See section 38.12 The display Property.

help-echo
If text has a string as its help-echo property, then when you move the mouse onto that text, Emacs displays that string in the echo area, or in the tooltip window.
If the value of the help-echo property is a function, that function is called with three arguments, window, object and position and should return a help string or nil for none. The first argument, window is the window in which the help was found. The second, object, is the buffer, overlay or string which had the help-echo property. The position argument is as follows:

If object is a buffer, pos is the position in the buffer where the help-echo text property was found.
If object is an overlay, that overlay has a help-echo property, and pos is the position in the overlay's buffer under the mouse.
If object is a string (an overlay string or a string displayed with the display property), pos is the position in that string under the mouse.

If the value of the help-echo property is neither a function nor a string, it is evaluated to obtain a help string.

You can alter the way help text is displayed by setting the variable show-help-function (see Help display).

This feature is used in the mode line and for other active text. It is available starting in Emacs 21.

local-map
You can specify a different keymap for some of the text in a buffer by means of the local-map property. The property's value for the character after point, if non-nil, is used for key lookup instead of the buffer's local map. If the property value is a symbol, the symbol's function definition is used as the keymap. See section 22.6 Active Keymaps.

keymap
The keymap property is similar to local-map but overrides the buffer's local map (and the map specified by the local-map property) rather than replacing it.

syntax-table
The syntax-table property overrides what the syntax table says about this particular character. See section 35.4 Syntax Properties.

read-only
If a character has the property read-only, then modifying that character is not allowed. Any command that would do so gets an error, text-read-only.
Insertion next to a read-only character is an error if inserting ordinary text there would inherit the read-only property due to stickiness. Thus, you can control permission to insert next to read-only text by controlling the stickiness. See section 32.19.6 Stickiness of Text Properties.

Since changing properties counts as modifying the buffer, it is not possible to remove a read-only property unless you know the special trick: bind inhibit-read-only to a non-nil value and then remove the property. See section 27.7 Read-Only Buffers.

invisible
A non-nil invisible property can make a character invisible on the screen. See section 38.5 Invisible Text, for details.

intangible
If a group of consecutive characters have equal and non-nil intangible properties, then you cannot place point between them. If you try to move point forward into the group, point actually moves to the end of the group. If you try to move point backward into the group, point actually moves to the start of the group.
When the variable inhibit-point-motion-hooks is non-nil, the intangible property is ignored.

field
Consecutive characters with the same field property constitute a field. Some motion functions including forward-word and beginning-of-line stop moving at a field boundary. See section 32.19.10 Defining and Using Fields.

modification-hooks
If a character has the property modification-hooks, then its value should be a list of functions; modifying that character calls all of those functions. Each function receives two arguments: the beginning and end of the part of the buffer being modified. Note that if a particular modification hook function appears on several characters being modified by a single primitive, you can't predict how many times the function will be called.

insert-in-front-hooks

insert-behind-hooks
The operation of inserting text in a buffer also calls the functions listed in the insert-in-front-hooks property of the following character and in the insert-behind-hooks property of the preceding character. These functions receive two arguments, the beginning and end of the inserted text. The functions are called after the actual insertion takes place.
See also 32.25 Change Hooks, for other hooks that are called when you change text in a buffer.

point-entered

point-left
The special properties point-entered and point-left record hook functions that report motion of point. Each time point moves, Emacs compares these two property values:

the point-left property of the character after the old location, and
the point-entered property of the character after the new location.

If these two values differ, each of them is called (if not nil) with two arguments: the old value of point, and the new one.

The same comparison is made for the characters before the old and new locations. The result may be to execute two point-left functions (which may be the same function) and/or two point-entered functions (which may be the same function). In any case, all the point-left functions are called first, followed by all the point-entered functions.

It is possible using char-after to examine characters at various positions without moving point to those positions. Only an actual change in the value of point runs these hook functions.

Variable: inhibit-point-motion-hooks
When this variable is non-nil, point-left and point-entered hooks are not run, and the intangible property has no effect. Do not set this variable globally; bind it with let.

Variable: show-help-function
If this variable is non-nil, it specifies a function called to display help strings. These may be help-echo properties, menu help strings (see section 22.12.1.1 Simple Menu Items, see section 22.12.1.2 Extended Menu Items), or tool bar help strings (see section 22.12.6 Tool bars). The specified function is called with one argument, the help string to display. Tooltip mode (see section `Tooltips' in The GNU Emacs Manual) provides an example.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.5 Formatted Text Properties

These text properties affect the behavior of the fill commands. They are used for representing formatted text. See section 32.11 Filling, and 32.12 Margins for Filling.

hard
If a newline character has this property, it is a "hard" newline. The fill commands do not alter hard newlines and do not move words across them. However, this property takes effect only if the variable use-hard-newlines is non-nil.

right-margin
This property specifies an extra right margin for filling this part of the text.

left-margin
This property specifies an extra left margin for filling this part of the text.

justification
This property specifies the style of justification for filling this part of the text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.6 Stickiness of Text Properties

Self-inserting characters normally take on the same properties as the preceding character. This is called inheritance of properties.

In a Lisp program, you can do insertion with inheritance or without, depending on your choice of insertion primitive. The ordinary text insertion functions such as insert do not inherit any properties. They insert text with precisely the properties of the string being inserted, and no others. This is correct for programs that copy text from one context to another--for example, into or out of the kill ring. To insert with inheritance, use the special primitives described in this section. Self-inserting characters inherit properties because they work using these primitives.

When you do insertion with inheritance, which properties are inherited, and from where, depends on which properties are sticky. Insertion after a character inherits those of its properties that are rear-sticky. Insertion before a character inherits those of its properties that are front-sticky. When both sides offer different sticky values for the same property, the previous character's value takes precedence.

By default, a text property is rear-sticky but not front-sticky; thus, the default is to inherit all the properties of the preceding character, and nothing from the following character.

You can control the stickiness of various text properties with two specific text properties, front-sticky and rear-nonsticky, and with the variable text-property-default-nonsticky. You can use the variable to specify a different default for a given property. You can use those two text properties to make any specific properties sticky or nonsticky in any particular part of the text.

If a character's front-sticky property is t, then all its properties are front-sticky. If the front-sticky property is a list, then the sticky properties of the character are those whose names are in the list. For example, if a character has a front-sticky property whose value is (face read-only), then insertion before the character can inherit its face property and its read-only property, but no others.

The rear-nonsticky property works the opposite way. Most properties are rear-sticky by default, so the rear-nonsticky property says which properties are not rear-sticky. If a character's rear-nonsticky property is t, then none of its properties are rear-sticky. If the rear-nonsticky property is a list, properties are rear-sticky unless their names are in the list.

Variable: text-property-default-nonsticky
This variable holds an alist which defines the default rear-stickiness of various text properties. Each element has the form (property . nonstickiness), and it defines the stickiness of a particular text property, property.

If nonstickiness is non-nil, this means that the property property is rear-nonsticky by default. Since all properties are front-nonsticky by default, this makes property nonsticky in both directions by default.

The text properties front-sticky and rear-nonsticky, when used, take precedence over the default nonstickiness specifed in text-property-default-nonsticky.

Here are the functions that insert text with inheritance of properties:

Function: insert-and-inherit &rest strings
Insert the strings strings, just like the function insert, but inherit any sticky properties from the adjoining text.

Function: insert-before-markers-and-inherit &rest strings
Insert the strings strings, just like the function insert-before-markers, but inherit any sticky properties from the adjoining text.

See section 32.4 Inserting Text, for the ordinary insertion functions which do not inherit.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.7 Saving Text Properties in Files

You can save text properties in files (along with the text itself), and restore the same text properties when visiting or inserting the files, using these two hooks:

Variable: write-region-annotate-functions
This variable's value is a list of functions for write-region to run to encode text properties in some fashion as annotations to the text being written in the file. See section 25.4 Writing to Files.

Each function in the list is called with two arguments: the start and end of the region to be written. These functions should not alter the contents of the buffer. Instead, they should return lists indicating annotations to write in the file in addition to the text in the buffer.

Each function should return a list of elements of the form (position . string), where position is an integer specifying the relative position within the text to be written, and string is the annotation to add there.

Each list returned by one of these functions must be already sorted in increasing order by position. If there is more than one function, write-region merges the lists destructively into one sorted list.

When write-region actually writes the text from the buffer to the file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer.

Variable: after-insert-file-functions
This variable holds a list of functions for insert-file-contents to call after inserting a file's contents. These functions should scan the inserted text for annotations, and convert them to the text properties they stand for.

Each function receives one argument, the length of the inserted text; point indicates the start of that text. The function should scan that text for annotations, delete them, and create the text properties that the annotations specify. The function should return the updated length of the inserted text, as it stands after those changes. The value returned by one function becomes the argument to the next function.

These functions should always return with point at the beginning of the inserted text.

The intended use of after-insert-file-functions is for converting some sort of textual annotations into actual text properties. But other uses may be possible.

We invite users to write Lisp programs to store and retrieve text properties in files, using these hooks, and thus to experiment with various data formats and find good ones. Eventually we hope users will produce good, general extensions we can install in Emacs.

We suggest not trying to handle arbitrary Lisp objects as text property names or values--because a program that general is probably difficult to write, and slow. Instead, choose a set of possible data types that are reasonably flexible, and not too hard to encode.

See section 25.12 File Format Conversion, for a related feature.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.8 Lazy Computation of Text Properties

Instead of computing text properties for all the text in the buffer, you can arrange to compute the text properties for parts of the text when and if something depends on them.

The primitive that extracts text from the buffer along with its properties is buffer-substring. Before examining the properties, this function runs the abnormal hook buffer-access-fontify-functions.

Variable: buffer-access-fontify-functions
This variable holds a list of functions for computing text properties. Before buffer-substring copies the text and text properties for a portion of the buffer, it calls all the functions in this list. Each of the functions receives two arguments that specify the range of the buffer being accessed. (The buffer itself is always the current buffer.)

The function buffer-substring-no-properties does not call these functions, since it ignores text properties anyway.

In order to prevent the hook functions from being called more than once for the same part of the buffer, you can use the variable buffer-access-fontified-property.

Variable: buffer-access-fontified-property
If this value's variable is non-nil, it is a symbol which is used as a text property name. A non-nil value for that text property means, "the other text properties for this character have already been computed."

If all the characters in the range specified for buffer-substring have a non-nil value for this property, buffer-substring does not call the buffer-access-fontify-functions functions. It assumes these characters already have the right text properties, and just copies the properties they already have.

The normal way to use this feature is that the buffer-access-fontify-functions functions add this property, as well as others, to the characters they operate on. That way, they avoid being called over and over for the same text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.9 Defining Clickable Text

There are two ways to set up clickable text in a buffer. There are typically two parts of this: to make the text highlight when the mouse is over it, and to make a mouse button do something when you click it on that part of the text.

Highlighting is done with the mouse-face text property. Here is an example of how Dired does it:
(condition-case nil
    (if (dired-move-to-filename)
        (put-text-property (point)
                           (save-excursion
                             (dired-move-to-end-of-filename)
                             (point))
                           'mouse-face 'highlight))
  (error nil))
The first two arguments to put-text-property specify the beginning and end of the text.

The usual way to make the mouse do something when you click it on this text is to define mouse-2 in the major mode's keymap. The job of checking whether the click was on clickable text is done by the command definition. Here is how Dired does it:
(defun dired-mouse-find-file-other-window (event)
  "In dired, visit the file or directory name you click on."
  (interactive "e")
  (let (file)
    (save-excursion
      (set-buffer (window-buffer (posn-window (event-end event))))
      (save-excursion
        (goto-char (posn-point (event-end event)))
        (setq file (dired-get-filename))))
    (select-window (posn-window (event-end event)))
    (find-file-other-window (file-name-sans-versions file t))))
The reason for the outer save-excursion construct is to avoid changing the current buffer; the reason for the inner one is to avoid permanently altering point in the buffer you click on. In this case, Dired uses the function dired-get-filename to determine which file to visit, based on the position found in the event.

Instead of defining a mouse command for the major mode, you can define a key binding for the clickable text itself, using the keymap text property:
(let ((map (make-sparse-keymap)))
  (define-key map [mouse-2] 'operate-this-button)
  (put-text-property (point)
                     (save-excursion
                       (dired-move-to-end-of-filename)
                       (point))
                     'keymap map))
This method makes it possible to define different commands for various clickable pieces of text. Also, the major mode definition (or the global definition) remains available for the rest of the text in the buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.10 Defining and Using Fields

A field is a range of consecutive characters in the buffer that are identified by having the same value (comparing with eq) of the field property (either a text-property or an overlay property). This section describes special functions that are available for operating on fields.

You specify a field with a buffer position, pos. We think of each field as containing a range of buffer positions, so the position you specify stands for the field containing that position.

When the characters before and after pos are part of the same field, there is no doubt which field contains pos: the one those characters both belong to. When pos is at a boundary between fields, which field it belongs to depends on the stickiness of the field properties of the two surrounding characters (see section 32.19.6 Stickiness of Text Properties). The field whose property would be inherited by text inserted at pos is the field that contains pos.

There is an anomalous case where newly inserted text at pos would not inherit the field property from either side. This happens if the previous character's field property is not rear-sticky, and the following character's field property is not front-sticky. In this case, pos belongs to neither the preceding field nor the following field; the field functions treat it as belonging to an empty field whose beginning and end are both at pos.

In all of these functions, if pos is omitted or nil, the value of point is used by default.

Function: field-beginning &optional pos escape-from-edge
This function returns the beginning of the field specified by pos.

If pos is at the beginning of its field, and escape-from-edge is non-nil, then the return value is always the beginning of the preceding field that ends at pos, regardless of the stickiness of the field properties around pos.

Function: field-end &optional pos escape-from-edge
This function returns the end of the field specified by pos.

If pos is at the end of its field, and escape-from-edge is non-nil, then the return value is always the end of the following field that begins at pos, regardless of the stickiness of the field properties around pos.

Function: field-string &optional pos
This function returns the contents of the field specified by pos, as a string.

Function: field-string-no-properties &optional pos
This function returns the contents of the field specified by pos, as a string, discarding text properties.

Function: delete-field &optional pos
This function deletes the text of the field specified by pos.

Function: constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
This function "constrains" new-pos to the field that old-pos belongs to--in other words, it returns the position closest to new-pos that is in the same field as old-pos.

If new-pos is nil, then constrain-to-field uses the value of point instead, and moves point to the resulting position.

If old-pos is at the boundary of two fields, then the acceptable positions for new-pos depend on the value of the optional argument escape-from-edge. If escape-from-edge is nil, then new-pos is constrained to the field that has the same field property (either a text-property or an overlay property) that new characters inserted at old-pos would get. (This depends on the stickiness of the field property for the characters before and after old-pos.) If escape-from-edge is non-nil, new-pos is constrained to the union of the two adjacent fields. Additionally, if two fields are separated by another field with the special value boundary, then any point within this special field is also considered to be "on the boundary."

If the optional argument only-in-line is non-nil, and constraining new-pos in the usual way would move it to a different line, new-pos is returned unconstrained. This used in commands that move by line, such as next-line and beginning-of-line, so that they respect field boundaries only in the case where they can still move to the right line.

If the optional argument inhibit-capture-property is non-nil, and old-pos has a non-nil property of that name, then any field boundaries are ignored.

You can cause constrain-to-field to ignore all field boundaries (and so never constrain anything) by binding the variable inhibit-field-text-motion to a non-nil value.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.19.11 Why Text Properties are not Intervals

Some editors that support adding attributes to text in the buffer do so by letting the user specify "intervals" within the text, and adding the properties to the intervals. Those editors permit the user or the programmer to determine where individual intervals start and end. We deliberately provided a different sort of interface in Emacs Lisp to avoid certain paradoxical behavior associated with text modification.

If the actual subdivision into intervals is meaningful, that means you can distinguish between a buffer that is just one interval with a certain property, and a buffer containing the same text subdivided into two intervals, both of which have that property.

Suppose you take the buffer with just one interval and kill part of the text. The text remaining in the buffer is one interval, and the copy in the kill ring (and the undo list) becomes a separate interval. Then if you yank back the killed text, you get two intervals with the same properties. Thus, editing does not preserve the distinction between one interval and two.

Suppose we "fix" this problem by coalescing the two intervals when the text is inserted. That works fine if the buffer originally was a single interval. But suppose instead that we have two adjacent intervals with the same properties, and we kill the text of one interval and yank it back. The same interval-coalescence feature that rescues the other case causes trouble in this one: after yanking, we have just one interval. One again, editing does not preserve the distinction between one interval and two.

Insertion of text at the border between intervals also raises questions that have no satisfactory answer.

However, it is easy to arrange for editing to behave consistently for questions of the form, "What are the properties of this character?" So we have decided these are the only questions that make sense; we have not implemented asking questions about where intervals start or end.

In practice, you can usually use the text property search functions in place of explicit interval boundaries. You can think of them as finding the boundaries of intervals, assuming that intervals are always coalesced whenever possible. See section 32.19.3 Text Property Search Functions.

Emacs also provides explicit intervals as a presentation feature; see 38.9 Overlays.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.20 Substituting for a Character Code

The following functions replace characters within a specified region based on their character codes.

Function: subst-char-in-region start end old-char new-char &optional noundo
This function replaces all occurrences of the character old-char with the character new-char in the region of the current buffer defined by start and end.

If noundo is non-nil, then subst-char-in-region does not record the change for undo and does not mark the buffer as modified. This was useful for controlling the old selective display feature (see section 38.6 Selective Display).

subst-char-in-region does not move point and returns nil.
---------- Buffer: foo ----------
This is the contents of the buffer before.
---------- Buffer: foo ----------

(subst-char-in-region 1 20 ?i ?X)
     => nil

---------- Buffer: foo ----------
ThXs Xs the contents of the buffer before.
---------- Buffer: foo ----------
Function: translate-region start end table
This function applies a translation table to the characters in the buffer between positions start and end.

The translation table table is a string; (aref table ochar) gives the translated character corresponding to ochar. If the length of table is less than 256, any characters with codes larger than the length of table are not altered by the translation.

The return value of translate-region is the number of characters that were actually changed by the translation. This does not count characters that were mapped into themselves in the translation table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.21 Registers

A register is a sort of variable used in Emacs editing that can hold a variety of different kinds of values. Each register is named by a single character. All ASCII characters and their meta variants (but with the exception of C-g) can be used to name registers. Thus, there are 255 possible registers. A register is designated in Emacs Lisp by the character that is its name.

Variable: register-alist
This variable is an alist of elements of the form (name . contents). Normally, there is one element for each Emacs register that has been used.

The object name is a character (an integer) identifying the register.

The contents of a register can have several possible types:

a number
A number stands for itself. If insert-register finds a number in the register, it converts the number to decimal.

a marker
A marker represents a buffer position to jump to.

a string
A string is text saved in the register.

a rectangle
A rectangle is represented by a list of strings.

(window-configuration position)
This represents a window configuration to restore in one frame, and a position to jump to in the current buffer.

(frame-configuration position)
This represents a frame configuration to restore, and a position to jump to in the current buffer.

(file filename)
This represents a file to visit; jumping to this value visits file filename.

(file-query filename position)
This represents a file to visit and a position in it; jumping to this value visits file filename and goes to buffer position position. Restoring this type of position asks the user for confirmation first.
The functions in this section return unpredictable values unless otherwise stated.

Function: get-register reg
This function returns the contents of the register reg, or nil if it has no contents.

Function: set-register reg value
This function sets the contents of register reg to value. A register can be set to any value, but the other register functions expect only certain data types. The return value is value.

Command: view-register reg
This command displays what is contained in register reg.

Command: insert-register reg &optional beforep
This command inserts contents of register reg into the current buffer.

Normally, this command puts point before the inserted text, and the mark after it. However, if the optional second argument beforep is non-nil, it puts the mark before and point after. You can pass a non-nil second argument beforep to this function interactively by supplying any prefix argument.

If the register contains a rectangle, then the rectangle is inserted with its upper left corner at point. This means that text is inserted in the current line and underneath it on successive lines.

If the register contains something other than saved text (a string) or a rectangle (a list), currently useless things happen. This may be changed in the future.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.22 Transposition of Text

This subroutine is used by the transposition commands.

Function: transpose-regions start1 end1 start2 end2 &optional leave-markers
This function exchanges two nonoverlapping portions of the buffer. Arguments start1 and end1 specify the bounds of one portion and arguments start2 and end2 specify the bounds of the other portion.

Normally, transpose-regions relocates markers with the transposed text; a marker previously positioned within one of the two transposed portions moves along with that portion, thus remaining between the same two characters in their new position. However, if leave-markers is non-nil, transpose-regions does not do this--it leaves all markers unrelocated.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.23 Base 64 Encoding

Base 64 code is used in email to encode a sequence of 8-bit bytes as a longer sequence of ASCII graphic characters. It is defined in Internet RFC(7)2045. This section describes the functions for converting to and from this code.

Function: base64-encode-region beg end &optional no-line-break
This function converts the region from beg to end into base 64 code. It returns the length of the encoded text. An error is signaled if a character in the region is multibyte, i.e. in a multibyte buffer the region must contain only characters from the charsets ascii, eight-bit-control and eight-bit-graphic.

Normally, this function inserts newline characters into the encoded text, to avoid overlong lines. However, if the optional argument no-line-break is non-nil, these newlines are not added, so the output is just one long line.

Function: base64-encode-string string &optional no-line-break
This function converts the string string into base 64 code. It returns a string containing the encoded text. As for base64-encode-region, an error is signaled if a character in the string is multibyte.

Normally, this function inserts newline characters into the encoded text, to avoid overlong lines. However, if the optional argument no-line-break is non-nil, these newlines are not added, so the result string is just one long line.

Function: base64-decode-region beg end
This function converts the region from beg to end from base 64 code into the corresponding decoded text. It returns the length of the decoded text.

The decoding functions ignore newline characters in the encoded text.

Function: base64-decode-string string
This function converts the string string from base 64 code into the corresponding decoded text. It returns a string containing the decoded text.

The decoding functions ignore newline characters in the encoded text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.24 MD5 Checksum

MD5 cryptographic checksums, or message digests, are 128-bit "fingerprints" of a document or program. They are used to verify that you have an exact and unaltered copy of the data. The algorithm to calculate the MD5 message digest is defined in Internet RFC(8)1321. This section describes the Emacs facilities for computing message digests.

Function: md5 object &optional start end coding-system noerror
This function returns the MD5 message digest of object, which should be a buffer or a string.

The two optional arguments start and end are character positions specifying the portion of object to compute the message digest for. If they are nil or omitted, the digest is computed for the whole of object.

The function md5 does not compute the message digest directly from the internal Emacs representation of the text (see section 33.1 Text Representations). Instead, it encodes the text using a coding system, and computes the message digest from the encoded text. The optional fourth argument coding-system specifies which coding system to use for encoding the text. It should be the same coding system that you used to read the text, or that you used or will use when saving or sending the text. See section 33.10 Coding Systems, for more information about coding systems.

If coding-system is nil or omitted, the default depends on object. If object is a buffer, the default for coding-system is whatever coding system would be chosen by default for writing this text into a file. If object is a string, the user's most preferred coding system (see section `the description of prefer-coding-system' in GNU Emacs Manual) is used.

Normally, md5 signals an error if the text can't be encoded using the specified or chosen coding system. However, if noerror is non-nil, it silently uses raw-text coding instead.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

32.25 Change Hooks

These hook variables let you arrange to take notice of all changes in all buffers (or in a particular buffer, if you make them buffer-local). See also 32.19.4 Properties with Special Meanings, for how to detect changes to specific parts of the text.

The functions you use in these hooks should save and restore the match data if they do anything that uses regular expressions; otherwise, they will interfere in bizarre ways with the editing operations that call them.

Variable: before-change-functions
This variable holds a list of functions to call before any buffer modification. Each function gets two arguments, the beginning and end of the region that is about to change, represented as integers. The buffer that is about to change is always the current buffer.

Variable: after-change-functions
This variable holds a list of functions to call after any buffer modification. Each function receives three arguments: the beginning and end of the region just changed, and the length of the text that existed before the change. All three arguments are integers. The buffer that's about to change is always the current buffer.

The length of the old text is the difference between the buffer positions before and after that text as it was before the change. As for the changed text, its length is simply the difference between the first two arguments.

Macro: combine-after-change-calls body...
The macro executes body normally, but arranges to call the after-change functions just once for a series of several changes--if that seems safe.

If a program makes several text changes in the same area of the buffer, using the macro combine-after-change-calls around that part of the program can make it run considerably faster when after-change hooks are in use. When the after-change hooks are ultimately called, the arguments specify a portion of the buffer including all of the changes made within the combine-after-change-calls body.

Warning: You must not alter the values of after-change-functions within the body of a combine-after-change-calls form.

Note: If the changes you combine occur in widely scattered parts of the buffer, this will still work, but it is not advisable, because it may lead to inefficient behavior for some change hook functions.

The two variables above are temporarily bound to nil during the time that any of these functions is running. This means that if one of these functions changes the buffer, that change won't run these functions. If you do want a hook function to make changes that run these functions, make it bind these variables back to their usual values.

One inconvenient result of this protective feature is that you cannot have a function in after-change-functions or before-change-functions which changes the value of that variable. But that's not a real limitation. If you want those functions to change the list of functions to run, simply add one fixed function to the hook, and code that function to look in another variable for other functions to call. Here is an example:
(setq my-own-after-change-functions nil)
(defun indirect-after-change-function (beg end len)
  (let ((list my-own-after-change-functions))
    (while list
      (funcall (car list) beg end len)
      (setq list (cdr list)))))

(add-hooks 'after-change-functions
           'indirect-after-change-function)
Variable: first-change-hook
This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state.

Variable: inhibit-modification-hooks
If this variable is non-nil, all of the change hooks are disabled; none of them run. This affects all the hook variables described above in this section, as well as the hooks attached to certain special text properties (see section 32.19.4 Properties with Special Meanings) and overlay properties (see section 38.9.1 Overlay Properties).

This variable is available starting in Emacs 21.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33. Non-ASCII Characters

This chapter covers the special issues relating to non-ASCII characters and how they are stored in strings and buffers.

33.1 Text Representations

Unibyte and multibyte representations

33.2 Converting Text Representations

Converting unibyte to multibyte and vice versa.

33.3 Selecting a Representation

Treating a byte sequence as unibyte or multi.

33.4 Character Codes

How unibyte and multibyte relate to codes of individual characters.

33.5 Character Sets

The space of possible characters codes is divided into various character sets.

33.6 Characters and Bytes

More information about multibyte encodings.

33.7 Splitting Characters

Converting a character to its byte sequence.

33.8 Scanning for Character Sets

Which character sets are used in a buffer?

33.9 Translation of Characters

Translation tables are used for conversion.

33.10 Coding Systems

Coding systems are conversions for saving files.

33.11 Input Methods

Input methods allow users to enter various non-ASCII characters without special keyboards.

33.12 Locales

Interacting with the POSIX locale.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.1 Text Representations

Emacs has two text representations---two ways to represent text in a string or buffer. These are called unibyte and multibyte. Each string, and each buffer, uses one of these two representations. For most purposes, you can ignore the issue of representations, because Emacs converts text between them as appropriate. Occasionally in Lisp programming you will need to pay attention to the difference.

In unibyte representation, each character occupies one byte and therefore the possible character codes range from 0 to 255. Codes 0 through 127 are ASCII characters; the codes from 128 through 255 are used for one non-ASCII character set (you can choose which character set by setting the variable nonascii-insert-offset).

In multibyte representation, a character may occupy more than one byte, and as a result, the full range of Emacs character codes can be stored. The first byte of a multibyte character is always in the range 128 through 159 (octal 0200 through 0237). These values are called leading codes. The second and subsequent bytes of a multibyte character are always in the range 160 through 255 (octal 0240 through 0377); these values are trailing codes.

Some sequences of bytes are not valid in multibyte text: for example, a single isolated byte in the range 128 through 159 is not allowed. But character codes 128 through 159 can appear in multibyte text, represented as two-byte sequences. All the character codes 128 through 255 are possible (though slightly abnormal) in multibyte text; they appear in multibyte buffers and strings when you do explicit encoding and decoding (see section 33.10.7 Explicit Encoding and Decoding).

In a buffer, the buffer-local value of the variable enable-multibyte-characters specifies the representation used. The representation for a string is determined and recorded in the string when the string is constructed.

Variable: enable-multibyte-characters
This variable specifies the current buffer's text representation. If it is non-nil, the buffer contains multibyte text; otherwise, it contains unibyte text.

You cannot set this variable directly; instead, use the function set-buffer-multibyte to change a buffer's representation.

Variable: default-enable-multibyte-characters
This variable's value is entirely equivalent to (default-value 'enable-multibyte-characters), and setting this variable changes that default value. Setting the local binding of enable-multibyte-characters in a specific buffer is not allowed, but changing the default value is supported, and it is a reasonable thing to do, because it has no effect on existing buffers.

The `--unibyte' command line option does its job by setting the default value to nil early in startup.

Function: position-bytes position
Return the byte-position corresponding to buffer position position in the current buffer.

Function: byte-to-position byte-position
Return the buffer position corresponding to byte-position byte-position in the current buffer.

Function: multibyte-string-p string
Return t if string is a multibyte string.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.2 Converting Text Representations

Emacs can convert unibyte text to multibyte; it can also convert multibyte text to unibyte, though this conversion loses information. In general these conversions happen when inserting text into a buffer, or when putting text from several strings together in one string. You can also explicitly convert a string's contents to either representation.

Emacs chooses the representation for a string based on the text that it is constructed from. The general rule is to convert unibyte text to multibyte text when combining it with other multibyte text, because the multibyte representation is more general and can hold whatever characters the unibyte text has.

When inserting text into a buffer, Emacs converts the text to the buffer's representation, as specified by enable-multibyte-characters in that buffer. In particular, when you insert multibyte text into a unibyte buffer, Emacs converts the text to unibyte, even though this conversion cannot in general preserve all the characters that might be in the multibyte text. The other natural alternative, to convert the buffer contents to multibyte, is not acceptable because the buffer's representation is a choice made by the user that cannot be overridden automatically.

Converting unibyte text to multibyte text leaves ASCII characters unchanged, and likewise character codes 128 through 159. It converts the non-ASCII codes 160 through 255 by adding the value nonascii-insert-offset to each character code. By setting this variable, you specify which character set the unibyte characters correspond to (see section 33.5 Character Sets). For example, if nonascii-insert-offset is 2048, which is (- (make-char 'latin-iso8859-1) 128), then the unibyte non-ASCII characters correspond to Latin 1. If it is 2688, which is (- (make-char 'greek-iso8859-7) 128), then they correspond to Greek letters.

Converting multibyte text to unibyte is simpler: it discards all but the low 8 bits of each character code. If nonascii-insert-offset has a reasonable value, corresponding to the beginning of some character set, this conversion is the inverse of the other: converting unibyte text to multibyte and back to unibyte reproduces the original unibyte text.

Variable: nonascii-insert-offset
This variable specifies the amount to add to a non-ASCII character when converting unibyte text to multibyte. It also applies when self-insert-command inserts a character in the unibyte non-ASCII range, 128 through 255. However, the functions insert and insert-char do not perform this conversion.

The right value to use to select character set cs is (- (make-char cs) 128). If the value of nonascii-insert-offset is zero, then conversion actually uses the value for the Latin 1 character set, rather than zero.

Variable: nonascii-translation-table
This variable provides a more general alternative to nonascii-insert-offset. You can use it to specify independently how to translate each code in the range of 128 through 255 into a multibyte character. The value should be a char-table, or nil. If this is non-nil, it overrides nonascii-insert-offset.

Function: string-make-unibyte string
This function converts the text of string to unibyte representation, if it isn't already, and returns the result. If string is a unibyte string, it is returned unchanged. Multibyte character codes are converted to unibyte by using just the low 8 bits.

Function: string-make-multibyte string
This function converts the text of string to multibyte representation, if it isn't already, and returns the result. If string is a multibyte string, it is returned unchanged. The function unibyte-char-to-multibyte is used to convert each unibyte character to a multibyte character.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.3 Selecting a Representation

Sometimes it is useful to examine an existing buffer or string as multibyte when it was unibyte, or vice versa.

Function: set-buffer-multibyte multibyte
Set the representation type of the current buffer. If multibyte is non-nil, the buffer becomes multibyte. If multibyte is nil, the buffer becomes unibyte.

This function leaves the buffer contents unchanged when viewed as a sequence of bytes. As a consequence, it can change the contents viewed as characters; a sequence of two bytes which is treated as one character in multibyte representation will count as two characters in unibyte representation. Character codes 128 through 159 are an exception. They are represented by one byte in a unibyte buffer, but when the buffer is set to multibyte, they are converted to two-byte sequences, and vice versa.

This function sets enable-multibyte-characters to record which representation is in use. It also adjusts various data in the buffer (including overlays, text properties and markers) so that they cover the same text as they did before.

You cannot use set-buffer-multibyte on an indirect buffer, because indirect buffers always inherit the representation of the base buffer.

Function: string-as-unibyte string
This function returns a string with the same bytes as string but treating each byte as a character. This means that the value may have more characters than string has.

If string is already a unibyte string, then the value is string itself. Otherwise it is a newly created string, with no text properties. If string is multibyte, any characters it contains of charset eight-bit-control or eight-bit-graphic are converted to the corresponding single byte.

Function: string-as-multibyte string
This function returns a string with the same bytes as string but treating each multibyte sequence as one character. This means that the value may have fewer characters than string has.

If string is already a multibyte string, then the value is string itself. Otherwise it is a newly created string, with no text properties. If string is unibyte and contains any individual 8-bit bytes (i.e. not part of a multibyte form), they are converted to the corresponding multibyte character of charset eight-bit-control or eight-bit-graphic.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.4 Character Codes

The unibyte and multibyte text representations use different character codes. The valid character codes for unibyte representation range from 0 to 255--the values that can fit in one byte. The valid character codes for multibyte representation range from 0 to 524287, but not all values in that range are valid. The values 128 through 255 are not entirely proper in multibyte text, but they can occur if you do explicit encoding and decoding (see section 33.10.7 Explicit Encoding and Decoding). Some other character codes cannot occur at all in multibyte text. Only the ASCII codes 0 through 127 are completely legitimate in both representations.

Function: char-valid-p charcode &optional genericp
This returns t if charcode is valid for either one of the two text representations.
(char-valid-p 65)
     => t
(char-valid-p 256)
     => nil
(char-valid-p 2248)
     => t
If the optional argument genericp is non-nil, this function returns t if charcode is a generic character (see section 33.7 Splitting Characters).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.5 Character Sets

Emacs classifies characters into various character sets, each of which has a name which is a symbol. Each character belongs to one and only one character set.

In general, there is one character set for each distinct script. For example, latin-iso8859-1 is one character set, greek-iso8859-7 is another, and ascii is another. An Emacs character set can hold at most 9025 characters; therefore, in some cases, characters that would logically be grouped together are split into several character sets. For example, one set of Chinese characters, generally known as Big 5, is divided into two Emacs character sets, chinese-big5-1 and chinese-big5-2.

ASCII characters are in character set ascii. The non-ASCII characters 128 through 159 are in character set eight-bit-control, and codes 160 through 255 are in character set eight-bit-graphic.

Function: charsetp object
Returns t if object is a symbol that names a character set, nil otherwise.

Function: charset-list
This function returns a list of all defined character set names.

Function: char-charset character
This function returns the name of the character set that character belongs to.

Function: charset-plist charset
This function returns the charset property list of the character set charset. Although charset is a symbol, this is not the same as the property list of that symbol. Charset properties are used for special purposes within Emacs; for example, preferred-coding-system helps determine which coding system to use to encode characters in a charset.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.6 Characters and Bytes

In multibyte representation, each character occupies one or more bytes. Each character set has an introduction sequence, which is normally one or two bytes long. (Exception: the ASCII character set and the EIGHT-BIT-GRAPHIC character set have a zero-length introduction sequence.) The introduction sequence is the beginning of the byte sequence for any character in the character set. The rest of the character's bytes distinguish it from the other characters in the same character set. Depending on the character set, there are either one or two distinguishing bytes; the number of such bytes is called the dimension of the character set.

Function: charset-dimension charset
This function returns the dimension of charset; at present, the dimension is always 1 or 2.

Function: charset-bytes charset
This function returns the number of bytes used to represent a character in character set charset.

This is the simplest way to determine the byte length of a character set's introduction sequence:
(- (charset-bytes charset)
   (charset-dimension charset))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.7 Splitting Characters

The functions in this section convert between characters and the byte values used to represent them. For most purposes, there is no need to be concerned with the sequence of bytes used to represent a character, because Emacs translates automatically when necessary.

Function: split-char character
Return a list containing the name of the character set of character, followed by one or two byte values (integers) which identify character within that character set. The number of byte values is the character set's dimension.
(split-char 2248)
     => (latin-iso8859-1 72)
(split-char 65)
     => (ascii 65)
(split-char 128)
     => (eight-bit-control 128)
Function: make-char charset &optional code1 code2
This function returns the character in character set charset whose position codes are code1 and code2. This is roughly the inverse of split-char. Normally, you should specify either one or both of code1 and code2 according to the dimension of charset. For example,
(make-char 'latin-iso8859-1 72)
     => 2248
If you call make-char with no byte-values, the result is a generic character which stands for charset. A generic character is an integer, but it is not valid for insertion in the buffer as a character. It can be used in char-table-range to refer to the whole character set (see section 6.6 Char-Tables). char-valid-p returns nil for generic characters. For example:
(make-char 'latin-iso8859-1)
     => 2176
(char-valid-p 2176)
     => nil
(char-valid-p 2176 t)
     => t
(split-char 2176)
     => (latin-iso8859-1 0)
The character sets ASCII, EIGHT-BIT-CONTROL, and EIGHT-BIT-GRAPHIC don't have corresponding generic characters. If charset is one of them and you don't supply code1, make-char returns the character code corresponding to the smallest code in charset.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.8 Scanning for Character Sets

Sometimes it is useful to find out which character sets appear in a part of a buffer or a string. One use for this is in determining which coding systems (see section 33.10 Coding Systems) are capable of representing all of the text in question.

Function: find-charset-region beg end &optional translation
This function returns a list of the character sets that appear in the current buffer between positions beg and end.

The optional argument translation specifies a translation table to be used in scanning the text (see section 33.9 Translation of Characters). If it is non-nil, then each character in the region is translated through this table, and the value returned describes the translated characters instead of the characters actually in the buffer.

Function: find-charset-string string &optional translation
This function returns a list of the character sets that appear in the string string. It is just like find-charset-region, except that it applies to the contents of string instead of part of the current buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.9 Translation of Characters

A translation table specifies a mapping of characters into characters. These tables are used in encoding and decoding, and for other purposes. Some coding systems specify their own particular translation tables; there are also default translation tables which apply to all other coding systems.

Function: make-translation-table &rest translations
This function returns a translation table based on the argument translations. Each element of translations should be a list of elements of the form (from . to); this says to translate the character from into to.

The arguments and the forms in each argument are processed in order, and if a previous form already translates to to some other character, say to-alt, from is also translated to to-alt.

You can also map one whole character set into another character set with the same dimension. To do this, you specify a generic character (which designates a character set) for from (see section 33.7 Splitting Characters). In this case, to should also be a generic character, for another character set of the same dimension. Then the translation table translates each character of from's character set into the corresponding character of to's character set.

In decoding, the translation table's translations are applied to the characters that result from ordinary decoding. If a coding system has property character-translation-table-for-decode, that specifies the translation table to use. Otherwise, if standard-translation-table-for-decode is non-nil, decoding uses that table.

In encoding, the translation table's translations are applied to the characters in the buffer, and the result of translation is actually encoded. If a coding system has property character-translation-table-for-encode, that specifies the translation table to use. Otherwise the variable standard-translation-table-for-encode specifies the translation table.

Variable: standard-translation-table-for-decode
This is the default translation table for decoding, for coding systems that don't specify any other translation table.

Variable: standard-translation-table-for-encode
This is the default translation table for encoding, for coding systems that don't specify any other translation table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10 Coding Systems

When Emacs reads or writes a file, and when Emacs sends text to a subprocess or receives text from a subprocess, it normally performs character code conversion and end-of-line conversion as specified by a particular coding system.

How to define a coding system is an arcane matter, and is not documented here.

33.10.1 Basic Concepts of Coding Systems

Basic concepts.

33.10.2 Encoding and I/O

How file I/O functions handle coding systems.

33.10.3 Coding Systems in Lisp

Functions to operate on coding system names.

33.10.4 User-Chosen Coding Systems

Asking the user to choose a coding system.

33.10.5 Default Coding Systems

Controlling the default choices.

33.10.6 Specifying a Coding System for One Operation

Requesting a particular coding system for a single file operation.

33.10.7 Explicit Encoding and Decoding

Encoding or decoding text without doing I/O.

33.10.8 Terminal I/O Encoding

Use of encoding for terminal I/O.

33.10.9 MS-DOS File Types

How DOS "text" and "binary" files relate to coding systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.1 Basic Concepts of Coding Systems

Character code conversion involves conversion between the encoding used inside Emacs and some other encoding. Emacs supports many different encodings, in that it can convert to and from them. For example, it can convert text to or from encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and several variants of ISO 2022. In some cases, Emacs supports several alternative encodings for the same characters; for example, there are three coding systems for the Cyrillic (Russian) alphabet: ISO, Alternativnyj, and KOI8.

Most coding systems specify a particular character code for conversion, but some of them leave the choice unspecified--to be chosen heuristically for each file, based on the data.

End of line conversion handles three different conventions used on various systems for representing end of line in files. The Unix convention is to use the linefeed character (also called newline). The DOS convention is to use a carriage-return and a linefeed at the end of a line. The Mac convention is to use just carriage-return.

Base coding systems such as latin-1 leave the end-of-line conversion unspecified, to be chosen based on the data. Variant coding systems such as latin-1-unix, latin-1-dos and latin-1-mac specify the end-of-line conversion explicitly as well. Most base coding systems have three corresponding variants whose names are formed by adding `-unix', `-dos' and `-mac'.

The coding system raw-text is special in that it prevents character code conversion, and causes the buffer visited with that coding system to be a unibyte buffer. It does not specify the end-of-line conversion, allowing that to be determined as usual by the data, and has the usual three variants which specify the end-of-line conversion. no-conversion is equivalent to raw-text-unix: it specifies no conversion of either character codes or end-of-line.

The coding system emacs-mule specifies that the data is represented in the internal Emacs encoding. This is like raw-text in that no code conversion happens, but different in that the result is multibyte data.

Function: coding-system-get coding-system property
This function returns the specified property of the coding system coding-system. Most coding system properties exist for internal purposes, but one that you might find useful is mime-charset. That property's value is the name used in MIME for the character coding which this coding system can read and write. Examples:
(coding-system-get 'iso-latin-1 'mime-charset)
     => iso-8859-1
(coding-system-get 'iso-2022-cn 'mime-charset)
     => iso-2022-cn
(coding-system-get 'cyrillic-koi8 'mime-charset)
     => koi8-r
The value of the mime-charset property is also defined as an alias for the coding system.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.2 Encoding and I/O

The principal purpose of coding systems is for use in reading and writing files. The function insert-file-contents uses a coding system for decoding the file data, and write-region uses one to encode the buffer contents.

You can specify the coding system to use either explicitly (see section 33.10.6 Specifying a Coding System for One Operation), or implicitly using the defaulting mechanism (see section 33.10.5 Default Coding Systems). But these methods may not completely specify what to do. For example, they may choose a coding system such as undefined which leaves the character code conversion to be determined from the data. In these cases, the I/O operation finishes the job of choosing a coding system. Very often you will want to find out afterwards which coding system was chosen.

Variable: buffer-file-coding-system
This variable records the coding system that was used for visiting the current buffer. It is used for saving the buffer, and for writing part of the buffer with write-region. When those operations ask the user to specify a different coding system, buffer-file-coding-system is updated to the coding system specified.

However, buffer-file-coding-system does not affect sending text to a subprocess.

Variable: save-buffer-coding-system
This variable specifies the coding system for saving the buffer (by overriding buffer-file-coding-system). Note that it is not used for write-region.

When a command to save the buffer starts out to use buffer-file-coding-system (or save-buffer-coding-system), and that coding system cannot handle the actual text in the buffer, the command asks the user to choose another coding system. After that happens, the command also updates buffer-file-coding-system to represent the coding system that the user specified.

Variable: last-coding-system-used
I/O operations for files and subprocesses set this variable to the coding system name that was used. The explicit encoding and decoding functions (see section 33.10.7 Explicit Encoding and Decoding) set it too.

Warning: Since receiving subprocess output sets this variable, it can change whenever Emacs waits; therefore, you should copy the value shortly after the function call that stores the value you are interested in.

The variable selection-coding-system specifies how to encode selections for the window system. See section 29.18 Window System Selections.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.3 Coding Systems in Lisp

Here are the Lisp facilities for working with coding systems:

Function: coding-system-list &optional base-only
This function returns a list of all coding system names (symbols). If base-only is non-nil, the value includes only the base coding systems. Otherwise, it includes alias and variant coding systems as well.

Function: coding-system-p object
This function returns t if object is a coding system name.

Function: check-coding-system coding-system
This function checks the validity of coding-system. If that is valid, it returns coding-system. Otherwise it signals an error with condition coding-system-error.

Function: coding-system-change-eol-conversion coding-system eol-type
This function returns a coding system which is like coding-system except for its eol conversion, which is specified by eol-type. eol-type should be unix, dos, mac, or nil. If it is nil, the returned coding system determines the end-of-line conversion from the data.

Function: coding-system-change-text-conversion eol-coding text-coding
This function returns a coding system which uses the end-of-line conversion of eol-coding, and the text conversion of text-coding. If text-coding is nil, it returns undecided, or one of its variants according to eol-coding.

Function: find-coding-systems-region from to
This function returns a list of coding systems that could be used to encode a text between from and to. All coding systems in the list can safely encode any multibyte characters in that portion of the text.

If the text contains no multibyte characters, the function returns the list (undecided).

Function: find-coding-systems-string string
This function returns a list of coding systems that could be used to encode the text of string. All coding systems in the list can safely encode any multibyte characters in string. If the text contains no multibyte characters, this returns the list (undecided).

Function: find-coding-systems-for-charsets charsets
This function returns a list of coding systems that could be used to encode all the character sets in the list charsets.

Function: detect-coding-region start end &optional highest
This function chooses a plausible coding system for decoding the text from start to end. This text should be a byte sequence (see section 33.10.7 Explicit Encoding and Decoding).

Normally this function returns a list of coding systems that could handle decoding the text that was scanned. They are listed in order of decreasing priority. But if highest is non-nil, then the return value is just one coding system, the one that is highest in priority.

If the region contains only ASCII characters, the value is undecided or (undecided).

Function: detect-coding-string string highest
This function is like detect-coding-region except that it operates on the contents of string instead of bytes in the buffer.

See section 37.6 Process Information, for how to examine or set the coding systems used for I/O to a subprocess.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.4 User-Chosen Coding Systems

Function: select-safe-coding-system from to &optional default-coding-system accept-default-p
This function selects a coding system for encoding specified text, asking the user to choose if necessary. Normally the specified text is the text in the current buffer between from and to, defaulting to the whole buffer if they are nil. If from is a string, the string is the specified text, and to is ignored.

If default-coding-system is non-nil, that is the first coding system to try; if that can handle the text, select-safe-coding-system returns that coding system. It can also be a list of coding systems; then the function tries each of them one by one. After trying all of them, it next tries the user's most preferred coding system (see section `the description of prefer-coding-system' in GNU Emacs Manual), and after that the current buffer's value of buffer-file-coding-system (if it is not undecided).

If one of those coding systems can safely encode all the specified text, select-safe-coding-system chooses it and returns it. Otherwise, it asks the user to choose from a list of coding systems which can encode all the text, and returns the user's choice.

The optional argument accept-default-p, if non-nil, should be a function to determine whether the coding system selected without user interaction is acceptable. If this function returns nil, the silently selected coding system is rejected, and the user is asked to select a coding system from a list of possible candidates.

If the variable select-safe-coding-system-accept-default-p is non-nil, its value overrides the value of accept-default-p.

Here are two functions you can use to let the user specify a coding system, with completion. See section 20.5 Completion.

Function: read-coding-system prompt &optional default
This function reads a coding system using the minibuffer, prompting with string prompt, and returns the coding system name as a symbol. If the user enters null input, default specifies which coding system to return. It should be a symbol or a string.

Function: read-non-nil-coding-system prompt
This function reads a coding system using the minibuffer, prompting with string prompt, and returns the coding system name as a symbol. If the user tries to enter null input, it asks the user to try again. See section 33.10 Coding Systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.5 Default Coding Systems

This section describes variables that specify the default coding system for certain files or when running certain subprograms, and the function that I/O operations use to access them.

The idea of these variables is that you set them once and for all to the defaults you want, and then do not change them again. To specify a particular coding system for a particular operation in a Lisp program, don't change these variables; instead, override them using coding-system-for-read and coding-system-for-write (see section 33.10.6 Specifying a Coding System for One Operation).

Variable: auto-coding-regexp-alist
This variable is an alist of text patterns and corresponding coding systems. Each element has the form (regexp . coding-system); a file whose first few kilobytes match regexp is decoded with coding-system when its contents are read into a buffer. The settings in this alist take priority over coding: tags in the files and the contents of file-coding-system-alist (see below). The default value is set so that Emacs automatically recognizes mail files in Babyl format and reads them with no code conversions.

Variable: file-coding-system-alist
This variable is an alist that specifies the coding systems to use for reading and writing particular files. Each element has the form (pattern . coding), where pattern is a regular expression that matches certain file names. The element applies to file names that match pattern.

The CDR of the element, coding, should be either a coding system, a cons cell containing two coding systems, or a function name (a symbol with a function definition). If coding is a coding system, that coding system is used for both reading the file and writing it. If coding is a cons cell containing two coding systems, its CAR specifies the coding system for decoding, and its CDR specifies the coding system for encoding.

If coding is a function name, the function must return a coding system or a cons cell containing two coding systems. This value is used as described above.

Variable: process-coding-system-alist
This variable is an alist specifying which coding systems to use for a subprocess, depending on which program is running in the subprocess. It works like file-coding-system-alist, except that pattern is matched against the program name used to start the subprocess. The coding system or systems specified in this alist are used to initialize the coding systems used for I/O to the subprocess, but you can specify other coding systems later using set-process-coding-system.

Warning: Coding systems such as undecided, which determine the coding system from the data, do not work entirely reliably with asynchronous subprocess output. This is because Emacs handles asynchronous subprocess output in batches, as it arrives. If the coding system leaves the character code conversion unspecified, or leaves the end-of-line conversion unspecified, Emacs must try to detect the proper conversion from one batch at a time, and this does not always work.

Therefore, with an asynchronous subprocess, if at all possible, use a coding system which determines both the character code conversion and the end of line conversion--that is, one like latin-1-unix, rather than undecided or latin-1.

Variable: network-coding-system-alist
This variable is an alist that specifies the coding system to use for network streams. It works much like file-coding-system-alist, with the difference that the pattern in an element may be either a port number or a regular expression. If it is a regular expression, it is matched against the network service name used to open the network stream.

Variable: default-process-coding-system
This variable specifies the coding systems to use for subprocess (and network stream) input and output, when nothing else specifies what to do.

The value should be a cons cell of the form (input-coding . output-coding). Here input-coding applies to input from the subprocess, and output-coding applies to output to it.

Function: find-operation-coding-system operation &rest arguments
This function returns the coding system to use (by default) for performing operation with arguments. The value has this form:
(decoding-system encoding-system)
The first element, decoding-system, is the coding system to use for decoding (in case operation does decoding), and encoding-system is the coding system for encoding (in case operation does encoding).

The argument operation should be a symbol, one of insert-file-contents, write-region, call-process, call-process-region, start-process, or open-network-stream. These are the names of the Emacs I/O primitives that can do coding system conversion.

The remaining arguments should be the same arguments that might be given to that I/O primitive. Depending on the primitive, one of those arguments is selected as the target. For example, if operation does file I/O, whichever argument specifies the file name is the target. For subprocess primitives, the process name is the target. For open-network-stream, the target is the service name or port number.

This function looks up the target in file-coding-system-alist, process-coding-system-alist, or network-coding-system-alist, depending on operation. See section 33.10.5 Default Coding Systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.6 Specifying a Coding System for One Operation

You can specify the coding system for a specific operation by binding the variables coding-system-for-read and/or coding-system-for-write.

Variable: coding-system-for-read
If this variable is non-nil, it specifies the coding system to use for reading a file, or for input from a synchronous subprocess.

It also applies to any asynchronous subprocess or network stream, but in a different way: the value of coding-system-for-read when you start the subprocess or open the network stream specifies the input decoding method for that subprocess or network stream. It remains in use for that subprocess or network stream unless and until overridden.

The right way to use this variable is to bind it with let for a specific I/O operation. Its global value is normally nil, and you should not globally set it to any other value. Here is an example of the right way to use the variable:
;; Read the file with no character code conversion.
;; Assume CRLF represents end-of-line.
(let ((coding-system-for-write 'emacs-mule-dos))
  (insert-file-contents filename))
When its value is non-nil, coding-system-for-read takes precedence over all other methods of specifying a coding system to use for input, including file-coding-system-alist, process-coding-system-alist and network-coding-system-alist.

Variable: coding-system-for-write
This works much like coding-system-for-read, except that it applies to output rather than input. It affects writing to files, as well as sending output to subprocesses and net connections.

When a single operation does both input and output, as do call-process-region and start-process, both coding-system-for-read and coding-system-for-write affect it.

Variable: inhibit-eol-conversion
When this variable is non-nil, no end-of-line conversion is done, no matter which coding system is specified. This applies to all the Emacs I/O and subprocess primitives, and to the explicit encoding and decoding functions (see section 33.10.7 Explicit Encoding and Decoding).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.7 Explicit Encoding and Decoding

All the operations that transfer text in and out of Emacs have the ability to use a coding system to encode or decode the text. You can also explicitly encode and decode text using the functions in this section.

The result of encoding, and the input to decoding, are not ordinary text. They logically consist of a series of byte values; that is, a series of characters whose codes are in the range 0 through 255. In a multibyte buffer or string, character codes 128 through 159 are represented by multibyte sequences, but this is invisible to Lisp programs.

The usual way to read a file into a buffer as a sequence of bytes, so you can decode the contents explicitly, is with insert-file-contents-literally (see section 25.3 Reading from Files); alternatively, specify a non-nil rawfile argument when visiting a file with find-file-noselect. These methods result in a unibyte buffer.

The usual way to use the byte sequence that results from explicitly encoding text is to copy it to a file or process--for example, to write it with write-region (see section 25.4 Writing to Files), and suppress encoding by binding coding-system-for-write to no-conversion.

Here are the functions to perform explicit encoding or decoding. The decoding functions produce sequences of bytes; the encoding functions are meant to operate on sequences of bytes. All of these functions discard text properties.

Function: encode-coding-region start end coding-system
This function encodes the text from start to end according to coding system coding-system. The encoded text replaces the original text in the buffer. The result of encoding is logically a sequence of bytes, but the buffer remains multibyte if it was multibyte before.

Function: encode-coding-string string coding-system
This function encodes the text in string according to coding system coding-system. It returns a new string containing the encoded text. The result of encoding is a unibyte string.

Function: decode-coding-region start end coding-system
This function decodes the text from start to end according to coding system coding-system. The decoded text replaces the original text in the buffer. To make explicit decoding useful, the text before decoding ought to be a sequence of byte values, but both multibyte and unibyte buffers are acceptable.

Function: decode-coding-string string coding-system
This function decodes the text in string according to coding system coding-system. It returns a new string containing the decoded text. To make explicit decoding useful, the contents of string ought to be a sequence of byte values, but a multibyte string is acceptable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.8 Terminal I/O Encoding

Emacs can decode keyboard input using a coding system, and encode terminal output. This is useful for terminals that transmit or display text using a particular encoding such as Latin-1. Emacs does not set last-coding-system-used for encoding or decoding for the terminal.

Function: keyboard-coding-system
This function returns the coding system that is in use for decoding keyboard input--or nil if no coding system is to be used.

Function: set-keyboard-coding-system coding-system
This function specifies coding-system as the coding system to use for decoding keyboard input. If coding-system is nil, that means do not decode keyboard input.

Function: terminal-coding-system
This function returns the coding system that is in use for encoding terminal output--or nil for no encoding.

Function: set-terminal-coding-system coding-system
This function specifies coding-system as the coding system to use for encoding terminal output. If coding-system is nil, that means do not encode terminal output.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.10.9 MS-DOS File Types

On MS-DOS and Microsoft Windows, Emacs guesses the appropriate end-of-line conversion for a file by looking at the file's name. This feature classifies files as text files and binary files. By "binary file" we mean a file of literal byte values that are not necessarily meant to be characters; Emacs does no end-of-line conversion and no character code conversion for them. On the other hand, the bytes in a text file are intended to represent characters; when you create a new file whose name implies that it is a text file, Emacs uses DOS end-of-line conversion.

Variable: buffer-file-type
This variable, automatically buffer-local in each buffer, records the file type of the buffer's visited file. When a buffer does not specify a coding system with buffer-file-coding-system, this variable is used to determine which coding system to use when writing the contents of the buffer. It should be nil for text, t for binary. If it is t, the coding system is no-conversion. Otherwise, undecided-dos is used.

Normally this variable is set by visiting a file; it is set to nil if the file was visited without any actual conversion.

User Option: file-name-buffer-file-type-alist
This variable holds an alist for recognizing text and binary files. Each element has the form (regexp . type), where regexp is matched against the file name, and type may be nil for text, t for binary, or a function to call to compute which. If it is a function, then it is called with a single argument (the file name) and should return t or nil.

When running on MS-DOS or MS-Windows, Emacs checks this alist to decide which coding system to use when reading a file. For a text file, undecided-dos is used. For a binary file, no-conversion is used.

If no element in this alist matches a given file name, then default-buffer-file-type says how to treat the file.

User Option: default-buffer-file-type
This variable says how to handle files for which file-name-buffer-file-type-alist says nothing about the type.

If this variable is non-nil, then these files are treated as binary: the coding system no-conversion is used. Otherwise, nothing special is done for them--the coding system is deduced solely from the file contents, in the usual Emacs fashion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.11 Input Methods

Input methods provide convenient ways of entering non-ASCII characters from the keyboard. Unlike coding systems, which translate non-ASCII characters to and from encodings meant to be read by programs, input methods provide human-friendly commands. (See section `Input Methods' in The GNU Emacs Manual, for information on how users use input methods to enter text.) How to define input methods is not yet documented in this manual, but here we describe how to use them.

Each input method has a name, which is currently a string; in the future, symbols may also be usable as input method names.

Variable: current-input-method
This variable holds the name of the input method now active in the current buffer. (It automatically becomes local in each buffer when set in any fashion.) It is nil if no input method is active in the buffer now.

Variable: default-input-method
This variable holds the default input method for commands that choose an input method. Unlike current-input-method, this variable is normally global.

Function: set-input-method input-method
This function activates input method input-method for the current buffer. It also sets default-input-method to input-method. If input-method is nil, this function deactivates any input method for the current buffer.

Function: read-input-method-name prompt &optional default inhibit-null
This function reads an input method name with the minibuffer, prompting with prompt. If default is non-nil, that is returned by default, if the user enters empty input. However, if inhibit-null is non-nil, empty input signals an error.

The returned value is a string.

Variable: input-method-alist
This variable defines all the supported input methods. Each element defines one input method, and should have the form:
(input-method language-env activate-func
 title description args...)
Here input-method is the input method name, a string; language-env is another string, the name of the language environment this input method is recommended for. (That serves only for documentation purposes.)

activate-func is a function to call to activate this method. The args, if any, are passed as arguments to activate-func. All told, the arguments to activate-func are input-method and the args.

title is a string to display in the mode line while this method is active. description is a string describing this method and what it is good for.

The fundamental interface to input methods is through the variable input-method-function. See section 21.7.2 Reading One Event.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

33.12 Locales

POSIX defines a concept of "locales" which control which language to use in language-related features. These Emacs variables control how Emacs interacts with these features.

Variable: locale-coding-system
This variable specifies the coding system to use for decoding system error messages, for encoding the format argument to format-time-string, and for decoding the return value of format-time-string.

Variable: system-messages-locale
This variable specifies the locale to use for generating system error messages. Changing the locale can cause messages to come out in a different language or in a different orthography. If the variable is nil, the locale is specified by environment variables in the usual POSIX fashion.

Variable: system-time-locale
This variable specifies the locale to use for formatting time values. Changing the locale can cause messages to appear according to the conventions of a different language. If the variable is nil, the locale is specified by environment variables in the usual POSIX fashion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34. Searching and Matching

GNU Emacs provides two ways to search through a buffer for specified text: exact string searches and regular expression searches. After a regular expression search, you can examine the match data to determine which text matched the whole regular expression or various portions of it.

34.1 Searching for Strings

Search for an exact match.

34.2 Regular Expressions

Describing classes of strings.

34.3 Regular Expression Searching

Searching for a match for a regexp.

34.4 POSIX Regular Expression Searching

Searching POSIX-style for the longest match.

34.5 Search and Replace

Internals of query-replace.

34.6 The Match Data

Finding out which part of the text matched various parts of a regexp, after regexp search.

34.7 Searching and Case

Case-independent or case-significant searching.

34.8 Standard Regular Expressions Used in Editing

Useful regexps for finding sentences, pages,...

The `skip-chars...' functions also perform a kind of searching. See section 30.2.7 Skipping Characters.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.1 Searching for Strings

These are the primitive functions for searching through the text in a buffer. They are meant for use in programs, but you may call them interactively. If you do so, they prompt for the search string; the arguments limit and noerror are nil, and repeat is 1.

These search functions convert the search string to multibyte if the buffer is multibyte; they convert the search string to unibyte if the buffer is unibyte. See section 33.1 Text Representations.

Command: search-forward string &optional limit noerror repeat
This function searches forward from point for an exact match for string. If successful, it sets point to the end of the occurrence found, and returns the new value of point. If no match is found, the value and side effects depend on noerror (see below).

In the following example, point is initially at the beginning of the line. Then (search-forward "fox") moves point after the last letter of `fox':
---------- Buffer: foo ----------
-!-The quick brown fox jumped over the lazy dog.
---------- Buffer: foo ----------

(search-forward "fox")
     => 20

---------- Buffer: foo ----------
The quick brown fox-!- jumped over the lazy dog.
---------- Buffer: foo ----------
The argument limit specifies the upper bound to the search. (It must be a position in the current buffer.) No match extending after that position is accepted. If limit is omitted or nil, it defaults to the end of the accessible portion of the buffer.

What happens when the search fails depends on the value of noerror. If noerror is nil, a search-failed error is signaled. If noerror is t, search-forward returns nil and does nothing. If noerror is neither nil nor t, then search-forward moves point to the upper bound and returns nil. (It would be more consistent now to return the new position of point in that case, but some existing programs may depend on a value of nil.)

If repeat is supplied (it must be a positive number), then the search is repeated that many times (each time starting at the end of the previous time's match). If these successive searches succeed, the function succeeds, moving point and returning its new value. Otherwise the search fails.

Command: search-backward string &optional limit noerror repeat
This function searches backward from point for string. It is just like search-forward except that it searches backwards and leaves point at the beginning of the match.

Command: word-search-forward string &optional limit noerror repeat
This function searches forward from point for a "word" match for string. If it finds a match, it sets point to the end of the match found, and returns the new value of point.

Word matching regards string as a sequence of words, disregarding punctuation that separates them. It searches the buffer for the same sequence of words. Each word must be distinct in the buffer (searching for the word `ball' does not match the word `balls'), but the details of punctuation and spacing are ignored (searching for `ball boy' does match `ball. Boy!').

In this example, point is initially at the beginning of the buffer; the search leaves it between the `y' and the `!'.
---------- Buffer: foo ----------
-!-He said "Please!  Find
the ball boy!"
---------- Buffer: foo ----------

(word-search-forward "Please find the ball, boy.")
     => 35

---------- Buffer: foo ----------
He said "Please!  Find
the ball boy-!-!"
---------- Buffer: foo ----------
If limit is non-nil (it must be a position in the current buffer), then it is the upper bound to the search. The match found must not extend after that position.

If noerror is nil, then word-search-forward signals an error if the search fails. If noerror is t, then it returns nil instead of signaling an error. If noerror is neither nil nor t, it moves point to limit (or the end of the buffer) and returns nil.

If repeat is non-nil, then the search is repeated that many times. Point is positioned at the end of the last match.

Command: word-search-backward string &optional limit noerror repeat
This function searches backward from point for a word match to string. This function is just like word-search-forward except that it searches backward and normally leaves point at the beginning of the match.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.2 Regular Expressions

A regular expression (regexp, for short) is a pattern that denotes a (possibly infinite) set of strings. Searching for matches for a regexp is a very powerful operation. This section explains how to write regexps; the following section says how to search for them.

34.2.1 Syntax of Regular Expressions

Rules for writing regular expressions.

34.2.3 Regular Expression Functions

Functions for operating on regular expressions.

34.2.2 Complex Regexp Example

Illustrates regular expression syntax.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.2.1 Syntax of Regular Expressions

Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character is a simple regular expression that matches that character and nothing else. The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and `\'; no new special characters will be defined in the future. Any other character appearing in a regular expression is ordinary, unless a `\' precedes it.

For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does not match the string `fg', but it does match a part of that string.) Likewise, `o' is a regular expression that matches only `o'.

Any two regular expressions a and b can be concatenated. The result is a regular expression that matches a string if a matches some amount of the beginning of that string and b matches the rest of the string.

As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial. To do something more powerful, you need to use one of the special regular expression constructs.

34.2.1.1 Special Characters in Regular Expressions

Special characters in regular expressions.

34.2.1.2 Character Classes

Character classes used in regular expressions.

34.2.1.3 Backslash Constructs in Regular Expressions

Backslash-sequences in regular expressions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.2.1.1 Special Characters in Regular Expressions

Here is a list of the characters that are special in a regular expression.

`.' (Period)
is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like `a.b', which matches any three-character string that begins with `a' and ends with `b'.

`*'
is not a construct by itself; it is a postfix operator that means to match the preceding regular expression repetitively as many times as possible. Thus, `o*' matches any number of `o's (including no `o's).
`*' always applies to the smallest possible preceding expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. It matches `f', `fo', `foo', and so on.

The matcher processes a `*' construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the `*'-modified construct in the hope that that will make it possible to match the rest of the pattern. For example, in matching `ca*ar' against the string `caaar', the `a*' first tries to match all three `a's; but the rest of the pattern is `ar' and there is only `r' left to match, so this try fails. The next alternative is for `a*' to match only two `a's. With this choice, the rest of the regexp matches successfully.

Nested repetition operators can be extremely slow if they specify backtracking loops. For example, it could take hours for the regular expression `\(x+y*\)*a' to try to match the sequence `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz', before it ultimately fails. The slowness is because Emacs must try each imaginable way of grouping the 35 `x's before concluding that none of them can work. To make sure your regular expressions run fast, check nested repetitions carefully.

`+'
is a postfix operator, similar to `*' except that it must match the preceding expression at least once. So, for example, `ca+r' matches the strings `car' and `caaaar' but not the string `cr', whereas `ca*r' matches all three strings.

`?'
is a postfix operator, similar to `*' except that it must match the preceding expression either once or not at all. For example, `ca?r' matches `car' or `cr'; nothing else.

`*?', `+?', `??'
These are "non-greedy" variants of the operators `*', `+' and `?'. Where those operators match the largest possible substring (consistent with matching the entire containing expression), the non-greedy variants match the smallest possible substring (consistent with matching the entire containing expression).
For example, the regular expression `c[ad]*a' when applied to the string `cdaaada' matches the whole string; but the regular expression `c[ad]*?a', applied to that same string, matches just `cda'. (The smallest possible match here for `[ad]*?' that permits the whole expression to match is `d'.)

`[ ... ]'
is a character alternative, which begins with `[' and is terminated by `]'. In the simplest case, the characters between the two brackets are what this character alternative can match.
Thus, `[ad]' matches either one `a' or one `d', and `[ad]*' matches any string composed of just `a's and `d's (including the empty string), from which it follows that `c[ad]*r' matches `cr', `car', `cdr', `caddaar', etc.

You can also include character ranges in a character alternative, by writing the starting and ending characters with a `-' between them. Thus, `[a-z]' matches any lower-case ASCII letter. Ranges may be intermixed freely with individual characters, as in `[a-z$%.]', which matches any lower case ASCII letter or `$', `%' or period.

Note that the usual regexp special characters are not special inside a character alternative. A completely different set of characters is special inside character alternatives: `]', `-' and `^'.

To include a `]' in a character alternative, you must make it the first character. For example, `[]a]' matches `]' or `a'. To include a `-', write `-' as the first or last character of the character alternative, or put it after a range. Thus, `[]-]' matches both `]' and `-'.

To include `^' in a character alternative, put it anywhere but at the beginning.

The beginning and end of a range of multibyte characters must be in the same character set (see section 33.5 Character Sets). Thus, "[\x8e0-\x97c]" is invalid because character 0x8e0 (`a' with grave accent) is in the Emacs character set for Latin-1 but the character 0x97c (`u' with diaeresis) is in the Emacs character set for Latin-2. (We use Lisp string syntax to write that example, and a few others in the next few paragraphs, in order to include hex escape sequences in them.)

If a range starts with a unibyte character c and ends with a multibyte character c2, the range is divided into two parts: one is `c..?\377', the other is `c1..c2', where c1 is the first character of the charset to which c2 belongs. You cannot always match all non-ASCII characters with the regular expression "[\200-\377]". This works when searching a unibyte buffer or string (see section 33.1 Text Representations), but not in a multibyte buffer or string, because many non-ASCII characters have codes above octal 0377. However, the regular expression "[^\000-\177]" does match all non-ASCII characters (see below regarding `^'), in both multibyte and unibyte representations, because only the ASCII characters are excluded.

Starting in Emacs 21, a character alternative can also specify named character classes (see section 34.2.1.2 Character Classes). This is a POSIX feature whose syntax is `[:class:]'. Using a character class is equivalent to mentioning each of the characters in that class; but the latter is not feasible in practice, since some classes include thousands of different characters.

`[^ ... ]'
`[^' begins a complemented character alternative, which matches any character except the ones specified. Thus, `[^a-z0-9A-Z]' matches all characters except letters and digits.
`^' is not special in a character alternative unless it is the first character. The character following the `^' is treated as if it were first (in other words, `-' and `]' are not special there).

A complemented character alternative can match a newline, unless newline is mentioned as one of the characters not to match. This is in contrast to the handling of regexps in programs such as grep.

`^'
is a special character that matches the empty string, but only at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, `^foo' matches a `foo' that occurs at the beginning of a line.
When matching a string instead of a buffer, `^' matches at the beginning of the string or after a newline character.

For historical compatibility reasons, `^' can be used only at the beginning of the regular expression, or after `\(' or `\|'.

`$'
is similar to `^' but matches only at the end of a line. Thus, `x+$' matches a string of one `x' or more at the end of a line.
When matching a string instead of a buffer, `$' matches at the end of the string or before a newline character.

For historical compatibility reasons, `$' can be used only at the end of the regular expression, or before `\)' or `\|'.

`\'
has two functions: it quotes the special characters (including `\'), and it introduces additional special constructs.
Because `\' quotes special characters, `\$' is a regular expression that matches only `$', and `\[' is a regular expression that matches only `[', and so on.

Note that `\' also has special meaning in the read syntax of Lisp strings (see section 2.3.8 String Type), and must be quoted with `\'. For example, the regular expression that matches the `\' character is `\\'. To write a Lisp string that contains the characters `\\', Lisp syntax requires you to quote each `\' with another `\'. Therefore, the read syntax for a regular expression matching `\' is "\\\\".
Please note: For historical compatibility, special characters are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, `*foo' treats `*' as ordinary since there is no preceding expression on which the `*' can act. It is poor practice to depend on this behavior; quote the special character anyway, regardless of where it appears.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.2.1.2 Character Classes

Here is a table of the classes you can use in a character alternative, in Emacs 21, and what they mean:

`[:ascii:]'
This matches any ASCII (unibyte) character.
`[:alnum:]'
This matches any letter or digit. (At present, for multibyte characters, it matches anything that has word syntax.)
`[:alpha:]'
This matches any letter. (At present, for multibyte characters, it matches anything that has word syntax.)
`[:blank:]'
This matches space and tab only.
`[:cntrl:]'
This matches any ASCII control character.
`[:digit:]'
This matches `0' through `9'. Thus, `[-+[:digit:]]' matches any digit, as well as `+' and `-'.
`[:graph:]'
This matches graphic characters--everything except ASCII control characters, space, and the delete character.
`[:lower:]'
This matches any lower-case letter, as determined by the current case table (see section 4.9 The Case Table).
`[:nonascii:]'
This matches any non-ASCII (multibyte) character.
`[:print:]'
This matches printing characters--everything except ASCII control characters and the delete character.
`[:punct:]'
This matches any punctuation character. (At present, for multibyte characters, it matches anything that has non-word syntax.)
`[:space:]'
This matches any character that has whitespace syntax (see section 35.2.1 Table of Syntax Classes).
`[:upper:]'
This matches any upper-case letter, as determined by the current case table (see section 4.9 The Case Table).
`[:word:]'
This matches any character that has word syntax (see section 35.2.1 Table of Syntax Classes).
`[:xdigit:]'
This matches the hexadecimal digits: `0' through `9', `a' through `f' and `A' through `F'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.2.1.3 Backslash Constructs in Regular Expressions

For the most part, `\' followed by any character matches only that character. However, there are several exceptions: certain two-character sequences starting with `\' that have special meanings. (The character after the `\' in such a sequence is always ordinary when used on its own.) Here is a table of the special `\' constructs.

`\|'
specifies an alternative. Two regular expressions a and b with `\|' in between form an expression that matches anything that either a or b matches.
Thus, `foo\|bar' matches either `foo' or `bar' but no other string.

`\|' applies to the largest possible surrounding expressions. Only a surrounding `\( ... \)' grouping can limit the grouping power of `\|'.

Full backtracking capability exists to handle multiple uses of `\|', if you use the POSIX regular expression functions (see section 34.4 POSIX Regular Expression Searching).

`\{m\}'
is a postfix operator that repeats the previous pattern exactly m times. Thus, `x\{5\}' matches the string `xxxxx' and nothing else. `c[ad]\{3\}r' matches string such as `caaar', `cdddr', `cadar', and so on.

`\{m,n\}'
is more general postfix operator that specifies repetition with a minimum of m repeats and a maximum of n repeats. If m is omitted, the minimum is 0; if n is omitted, there is no maximum.
For example, `c[ad]\{1,2\}r' matches the strings `car', `cdr', `caar', `cadr', `cdar', and `cddr', and nothing else.
`\{0,1\}' or `\{,1\}' is equivalent to `?'.
`\{0,\}' or `\{,\}' is equivalent to `*'.
`\{1,\}' is equivalent to `+'.

`\( ... \)'
is a grouping construct that serves three purposes:

To enclose a set of `\|' alternatives for other operations. Thus, the regular expression `\(foo\|bar\)x' matches either `foox' or `barx'.

To enclose a complicated expression for the postfix operators `*', `+' and `?' to operate on. Thus, `ba\(na\)*' matches `ba', `bana', `banana', `bananana', etc., with any number (zero or more) of `na' strings.

To record a matched substring for future reference with `\digit' (see below).

This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that was assigned as a second meaning to the same `\( ... \)' construct because, in pratice, there was usually no conflict between the two meanings. But occasionally there is a conflict, and that led to the introduction of shy groups.

`\(?: ... \)'
is the shy group construct. A shy group serves the first two purposes of an ordinary group (controlling the nesting of other operators), but it does not get a number, so you cannot refer back to its value with `\digit'.
Shy groups are particulary useful for mechanically-constructed regular expressions because they can be added automatically without altering the numbering of any ordinary, non-shy groups.

`\digit'
matches the same text that matched the digitth occurrence of a grouping (`\( ... \)') construct.
In other words, after the end of a group, the matcher remembers the beginning and end of the text matched by that group. Later on in the regular expression you can use `\' followed by digit to match that same text, whatever it may have been.

The strings matching the first nine grouping constructs appearing in the entire regular expression passed to a search or matching function are assigned numbers 1 through 9 in the order that the open parentheses appear in the regular expression. So you can use `\1' through `\9' to refer to the text matched by the corresponding grouping constructs.

For example, `\(.*\)\1' matches any newline-free string that is composed of two identical halves. The `\(.*\)' matches the first half, which may be anything, but the `\1' that follows must match the same exact text.

If a particular grouping construct in the regular expression was never matched--for instance, if it appears inside of an alternative that wasn't used, or inside of a repetition that repeated zero times--then the corresponding `\digit' construct never matches anything. To use an artificial example,, `\(foo\(b*\)\|lose\)\2' cannot match `lose': the second alternative inside the larger group matches it, but then `\2' is undefined and can't match anything. But it can match `foobb', because the first alternative matches `foob' and `\2' matches `b'.

`\w'
matches any word-constituent character. The editor syntax table determines which characters these are. See section 35. Syntax Tables.

`\W'
matches any character that is not a word constituent.

`\scode'
matches any character whose syntax is code. Here code is a character that represents a syntax code: thus, `w' for word constituent, `-' for whitespace, `(' for open parenthesis, etc. To represent whitespace syntax, use either `-' or a space character. See section 35.2.1 Table of Syntax Classes, for a list of syntax codes and the characters that stand for them.

`\Scode'
matches any character whose syntax is not code.

`\cc'
matches any character whose category is c. Here c is a character that represents a category: thus, `c' for Chinese characters or `g' for Greek characters in the standard category table.

`\Cc'
matches any character whose category is not c.
The following regular expression constructs match the empty string--that is, they don't use up any characters--but whether they match depends on the context.

`\`'
matches the empty string, but only at the beginning of the buffer or string being matched against.

`\''
matches the empty string, but only at the end of the buffer or string being matched against.

`\='
matches the empty string, but only at point. (This construct is not defined when matching against a string.)

`\b'
matches the empty string, but only at the beginning or end of a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a separate word. `\bballs?\b' matches `ball' or `balls' as a separate word.
`\b' matches at the beginning or end of the buffer regardless of what text appears next to it.

`\B'
matches the empty string, but not at the beginning or end of a word.

`\<'
matches the empty string, but only at the beginning of a word. `\<' matches at the beginning of the buffer only if a word-constituent character follows.

`\>'
matches the empty string, but only at the end of a word. `\>' matches at the end of the buffer only if the contents end with a word-constituent character.
Not every string is a valid regular expression. For example, a string with unbalanced square brackets is invalid (with a few exceptions, such as `[]]'), and so is a string that ends with a single `\'. If an invalid regular expression is passed to any of the search functions, an invalid-regexp error is signaled.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.2.2 Complex Regexp Example

Here is a complicated regexp, used by Emacs to recognize the end of a sentence together with any whitespace that follows. It is the value of the variable sentence-end.

First, we show the regexp as a string in Lisp syntax to distinguish spaces from tab characters. The string constant begins and ends with a double-quote. `\"' stands for a double-quote as part of the string, `\\' for a backslash as part of the string, `\t' for a tab and `\n' for a newline.
"[.?!][]\"')}]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
In contrast, if you evaluate the variable sentence-end, you will see the following:
sentence-end
     => "[.?!][]\"')}]*\\($\\| $\\|  \\|  \\)[
]*"
In this output, tab and newline appear as themselves.

This regular expression contains four parts in succession and can be deciphered as follows:

[.?!]
The first part of the pattern is a character alternative that matches any one of three characters: period, question mark, and exclamation mark. The match must begin with one of these three characters.

[]\"')}]*
The second part of the pattern matches any closing braces and quotation marks, zero or more of them, that may follow the period, question mark or exclamation mark. The \" is Lisp syntax for a double-quote in a string. The `*' at the end indicates that the immediately preceding regular expression (a character alternative, in this case) may be repeated zero or more times.

\\($\\| $\\|\t\\| \\)
The third part of the pattern matches the whitespace that follows the end of a sentence: the end of a line (optionally with a space), or a tab, or two spaces. The double backslashes mark the parentheses and vertical bars as regular expression syntax; the parentheses delimit a group and the vertical bars separate alternatives. The dollar sign is used to match the end of a line.

[ \t\n]*
Finally, the last part of the pattern matches any additional whitespace beyond the minimum needed to end a sentence.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.2.3 Regular Expression Functions

These functions operate on regular expressions.

Function: regexp-quote string
This function returns a regular expression whose only exact match is string. Using this regular expression in looking-at will succeed only if the next characters in the buffer are string; using it in a search function will succeed if the text being searched contains string.

This allows you to request an exact string match or search when calling a function that wants a regular expression.
(regexp-quote "^The cat$")
     => "\\^The cat\\$"
One use of regexp-quote is to combine an exact string match with context described as a regular expression. For example, this searches for the string that is the value of string, surrounded by whitespace:
(re-search-forward
 (concat "\\s-" (regexp-quote string) "\\s-"))
Function: regexp-opt strings &optional paren
This function returns an efficient regular expression that will match any of the strings strings. This is useful when you need to make matching or searching as fast as possible--for example, for Font Lock mode.

If the optional argument paren is non-nil, then the returned regular expression is always enclosed by at least one parentheses-grouping construct.

This simplified definition of regexp-opt produces a regular expression which is equivalent to the actual value (but not as efficient):
(defun regexp-opt (strings paren)
  (let ((open-paren (if paren "\\(" ""))
        (close-paren (if paren "\\)" "")))
    (concat open-paren
            (mapconcat 'regexp-quote strings "\\|")
            close-paren)))
Function: regexp-opt-depth regexp
This function returns the total number of grouping constructs (parenthesized expressions) in regexp.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.3 Regular Expression Searching

In GNU Emacs, you can search for the next match for a regular expression either incrementally or not. For incremental search commands, see section `Regular Expression Search' in The GNU Emacs Manual. Here we describe only the search functions useful in programs. The principal one is re-search-forward.

These search functions convert the regular expression to multibyte if the buffer is multibyte; they convert the regular expression to unibyte if the buffer is unibyte. See section 33.1 Text Representations.

Command: re-search-forward regexp &optional limit noerror repeat
This function searches forward in the current buffer for a string of text that is matched by the regular expression regexp. The function skips over any amount of text that is not matched by regexp, and leaves point at the end of the first match found. It returns the new value of point.

If limit is non-nil (it must be a position in the current buffer), then it is the upper bound to the search. No match extending after that position is accepted.

If repeat is supplied (it must be a positive number), then the search is repeated that many times (each time starting at the end of the previous time's match). If all these successive searches succeed, the function succeeds, moving point and returning its new value. Otherwise the function fails.

What happens when the function fails depends on the value of noerror. If noerror is nil, a search-failed error is signaled. If noerror is t, re-search-forward does nothing and returns nil. If noerror is neither nil nor t, then re-search-forward moves point to limit (or the end of the buffer) and returns nil.

In the following example, point is initially before the `T'. Evaluating the search call moves point to the end of that line (between the `t' of `hat' and the newline).
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(re-search-forward "[a-z]+" nil t 5)
     => 27

---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
Command: re-search-backward regexp &optional limit noerror repeat
This function searches backward in the current buffer for a string of text that is matched by the regular expression regexp, leaving point at the beginning of the first text found.

This function is analogous to re-search-forward, but they are not simple mirror images. re-search-forward finds the match whose beginning is as close as possible to the starting point. If re-search-backward were a perfect mirror image, it would find the match whose end is as close as possible. However, in fact it finds the match whose beginning is as close as possible. The reason for this is that matching a regular expression at a given spot always works from beginning to end, and starts at a specified beginning position.

A true mirror-image of re-search-forward would require a special feature for matching regular expressions from end to beginning. It's not worth the trouble of implementing that.

Function: string-match regexp string &optional start
This function returns the index of the start of the first match for the regular expression regexp in string, or nil if there is no match. If start is non-nil, the search starts at that index in string.

For example,
(string-match
 "quick" "The quick brown fox jumped quickly.")
     => 4
(string-match
 "quick" "The quick brown fox jumped quickly." 8)
     => 27
The index of the first character of the string is 0, the index of the second character is 1, and so on.

After this function returns, the index of the first character beyond the match is available as (match-end 0). See section 34.6 The Match Data.
(string-match
 "quick" "The quick brown fox jumped quickly." 8)
     => 27

(match-end 0)
     => 32
Function: looking-at regexp
This function determines whether the text in the current buffer directly following point matches the regular expression regexp. "Directly following" means precisely that: the search is "anchored" and it can succeed only starting with the first character following point. The result is t if so, nil otherwise.

This function does not move point, but it updates the match data, which you can access using match-beginning and match-end. See section 34.6 The Match Data.

In this example, point is located directly before the `T'. If it were anywhere else, the result would be nil.
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(looking-at "The cat in the hat$")
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.4 POSIX Regular Expression Searching

The usual regular expression functions do backtracking when necessary to handle the `\|' and repetition constructs, but they continue this only until they find some match. Then they succeed and report the first match found.

This section describes alternative search functions which perform the full backtracking specified by the POSIX standard for regular expression matching. They continue backtracking until they have tried all possibilities and found all matches, so they can report the longest match, as required by POSIX. This is much slower, so use these functions only when you really need the longest match.

Function: posix-search-forward regexp &optional limit noerror repeat
This is like re-search-forward except that it performs the full backtracking specified by the POSIX standard for regular expression matching.

Function: posix-search-backward regexp &optional limit noerror repeat
This is like re-search-backward except that it performs the full backtracking specified by the POSIX standard for regular expression matching.

Function: posix-looking-at regexp
This is like looking-at except that it performs the full backtracking specified by the POSIX standard for regular expression matching.

Function: posix-string-match regexp string &optional start
This is like string-match except that it performs the full backtracking specified by the POSIX standard for regular expression matching.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.5 Search and Replace

Function: perform-replace from-string replacements start end query-flag regexp-flag delimited-flag &optional repeat-count map
This function is the guts of query-replace and related commands. It searches for occurrences of from-string in the text between positions start and end and replaces some or all of them. If start is nil, point is used instead, and the buffer's end is used for end.

If query-flag is nil, it replaces all occurrences; otherwise, it asks the user what to do about each one.

If regexp-flag is non-nil, then from-string is considered a regular expression; otherwise, it must match literally. If delimited-flag is non-nil, then only replacements surrounded by word boundaries are considered.

The argument replacements specifies what to replace occurrences with. If it is a string, that string is used. It can also be a list of strings, to be used in cyclic order.

If replacements is a cons cell, (function . data), this means to call function after each match to get the replacement text. This function is called with two arguments: data, and the number of replacements already made.

If repeat-count is non-nil, it should be an integer. Then it specifies how many times to use each of the strings in the replacements list before advancing cyclicly to the next one.

If from-string contains upper-case letters, then perform-replace binds case-fold-search to nil, and it uses the replacements without altering the case of them.

Normally, the keymap query-replace-map defines the possible user responses for queries. The argument map, if non-nil, is a keymap to use instead of query-replace-map.

Variable: query-replace-map
This variable holds a special keymap that defines the valid user responses for query-replace and related functions, as well as y-or-n-p and map-y-or-n-p. It is unusual in two ways:

The "key bindings" are not commands, just symbols that are meaningful to the functions that use this map.

Prefix keys are not supported; each key binding must be for a single-event key sequence. This is because the functions don't use read-key-sequence to get the input; instead, they read a single event and look it up "by hand."

Here are the meaningful "bindings" for query-replace-map. Several of them are meaningful only for query-replace and friends.

act
Do take the action being considered--in other words, "yes."

skip
Do not take action for this question--in other words, "no."

exit
Answer this question "no," and give up on the entire series of questions, assuming that the answers will be "no."

act-and-exit
Answer this question "yes," and give up on the entire series of questions, assuming that subsequent answers will be "no."

act-and-show
Answer this question "yes," but show the results--don't advance yet to the next question.

automatic
Answer this question and all subsequent questions in the series with "yes," without further user interaction.

backup
Move back to the previous place that a question was asked about.

edit
Enter a recursive edit to deal with this question--instead of any other action that would normally be taken.

delete-and-edit
Delete the text being considered, then enter a recursive edit to replace it.

recenter
Redisplay and center the window, then ask the same question again.

quit
Perform a quit right away. Only y-or-n-p and related functions use this answer.

help
Display some help, then ask again.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.6 The Match Data

Emacs keeps track of the start and end positions of the segments of text found during a regular expression search. This means, for example, that you can search for a complex pattern, such as a date in an Rmail message, and then extract parts of the match under control of the pattern.

Because the match data normally describe the most recent search only, you must be careful not to do another search inadvertently between the search you wish to refer back to and the use of the match data. If you can't avoid another intervening search, you must save and restore the match data around it, to prevent it from being overwritten.

34.6.1 Replacing the Text that Matched

Replacing a substring that was matched.

34.6.2 Simple Match Data Access

Accessing single items of match data, such as where a particular subexpression started.

34.6.3 Accessing the Entire Match Data

Accessing the entire match data at once, as a list.

34.6.4 Saving and Restoring the Match Data

Saving and restoring the match data.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.6.1 Replacing the Text that Matched

This function replaces the text matched by the last search with replacement.

Function: replace-match replacement &optional fixedcase literal string subexp
This function replaces the text in the buffer (or in string) that was matched by the last search. It replaces that text with replacement.

If you did the last search in a buffer, you should specify nil for string. Then replace-match does the replacement by editing the buffer; it leaves point at the end of the replacement text, and returns t.

If you did the search in a string, pass the same string as string. Then replace-match does the replacement by constructing and returning a new string.

If fixedcase is non-nil, then the case of the replacement text is not changed; otherwise, the replacement text is converted to a different case depending upon the capitalization of the text to be replaced. If the original text is all upper case, the replacement text is converted to upper case. If the first word of the original text is capitalized, then the first word of the replacement text is capitalized. If the original text contains just one word, and that word is a capital letter, replace-match considers this a capitalized first word rather than all upper case.

If literal is non-nil, then replacement is inserted exactly as it is, the only alterations being case changes as needed. If it is nil (the default), then the character `\' is treated specially. If a `\' appears in replacement, then it must be part of one of the following sequences:

`\&'
`\&' stands for the entire text being replaced.

`\n'
`\n', where n is a digit, stands for the text that matched the nth subexpression in the original regexp. Subexpressions are those expressions grouped inside `\(...\)'.

`\\'
`\\' stands for a single `\' in the replacement text.
If subexp is non-nil, that says to replace just subexpression number subexp of the regexp that was matched, not the entire match. For example, after matching `foo \(ba*r\)', calling replace-match with 1 as subexp means to replace just the text that matched `\(ba*r\)'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.6.2 Simple Match Data Access

This section explains how to use the match data to find out what was matched by the last search or match operation.

You can ask about the entire matching text, or about a particular parenthetical subexpression of a regular expression. The count argument in the functions below specifies which. If count is zero, you are asking about the entire match. If count is positive, it specifies which subexpression you want.

Recall that the subexpressions of a regular expression are those expressions grouped with escaped parentheses, `\(...\)'. The countth subexpression is found by counting occurrences of `\(' from the beginning of the whole regular expression. The first subexpression is numbered 1, the second 2, and so on. Only regular expressions can have subexpressions--after a simple string search, the only information available is about the entire match.

A search which fails may or may not alter the match data. In the past, a failing search did not do this, but we may change it in the future.

Function: match-string count &optional in-string
This function returns, as a string, the text matched in the last search or match operation. It returns the entire text if count is zero, or just the portion corresponding to the countth parenthetical subexpression, if count is positive.

If the last such operation was done against a string with string-match, then you should pass the same string as the argument in-string. After a buffer search or match, you should omit in-string or pass nil for it; but you should make sure that the current buffer when you call match-string is the one in which you did the searching or matching.

The value is nil if count is out of range, or for a subexpression inside a `\|' alternative that wasn't used or a repetition that repeated zero times.

Function: match-string-no-properties count &optional in-string
This function is like match-string except that the result has no text properties.

Function: match-beginning count
This function returns the position of the start of text matched by the last regular expression searched for, or a subexpression of it.

If count is zero, then the value is the position of the start of the entire match. Otherwise, count specifies a subexpression in the regular expression, and the value of the function is the starting position of the match for that subexpression.

The value is nil for a subexpression inside a `\|' alternative that wasn't used or a repetition that repeated zero times.

Function: match-end count
This function is like match-beginning except that it returns the position of the end of the match, rather than the position of the beginning.

Here is an example of using the match data, with a comment showing the positions within the text:
(string-match "\\(qu\\)\\(ick\\)"
              "The quick fox jumped quickly.")
              ;0123456789
     => 4

(match-string 0 "The quick fox jumped quickly.")
     => "quick"
(match-string 1 "The quick fox jumped quickly.")
     => "qu"
(match-string 2 "The quick fox jumped quickly.")
     => "ick"

(match-beginning 1)       ; The beginning of the match
     => 4                 ;   with `qu' is at index 4.

(match-beginning 2)       ; The beginning of the match
     => 6                 ;   with `ick' is at index 6.

(match-end 1)             ; The end of the match
     => 6                 ;   with `qu' is at index 6.

(match-end 2)             ; The end of the match
     => 9                 ;   with `ick' is at index 9.
Here is another example. Point is initially located at the beginning of the line. Searching moves point to between the space and the word `in'. The beginning of the entire match is at the 9th character of the buffer (`T'), and the beginning of the match for the first subexpression is at the 13th character (`c').
(list
  (re-search-forward "The \\(cat \\)")
  (match-beginning 0)
  (match-beginning 1))
    => (9 9 13)

---------- Buffer: foo ----------
I read "The cat -!-in the hat comes back" twice.
        ^   ^
        9  13
---------- Buffer: foo ----------
(In this case, the index returned is a buffer position; the first character of the buffer counts as 1.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.6.3 Accessing the Entire Match Data

The functions match-data and set-match-data read or write the entire match data, all at once.

Function: match-data
This function returns a newly constructed list containing all the information on what text the last search matched. Element zero is the position of the beginning of the match for the whole expression; element one is the position of the end of the match for the expression. The next two elements are the positions of the beginning and end of the match for the first subexpression, and so on. In general, element number 2n corresponds to (match-beginning n); and element number 2n + 1 corresponds to (match-end n).

All the elements are markers or nil if matching was done on a buffer, and all are integers or nil if matching was done on a string with string-match.

As always, there must be no possibility of intervening searches between the call to a search function and the call to match-data that is intended to access the match data for that search.
(match-data)
     =>  (#<marker at 9 in foo>
          #<marker at 17 in foo>
          #<marker at 13 in foo>
          #<marker at 17 in foo>)
Function: set-match-data match-list
This function sets the match data from the elements of match-list, which should be a list that was the value of a previous call to match-data.

If match-list refers to a buffer that doesn't exist, you don't get an error; that sets the match data in a meaningless but harmless way.

store-match-data is a semi-obsolete alias for set-match-data.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.6.4 Saving and Restoring the Match Data

When you call a function that may do a search, you may need to save and restore the match data around that call, if you want to preserve the match data from an earlier search for later use. Here is an example that shows the problem that arises if you fail to save the match data:
(re-search-forward "The \\(cat \\)")
     => 48
(foo)                   ; Perhaps foo does
                        ;   more searching.
(match-end 0)
     => 61              ; Unexpected result---not 48!
You can save and restore the match data with save-match-data:

Macro: save-match-data body...
This macro executes body, saving and restoring the match data around it.

You could use set-match-data together with match-data to imitate the effect of the special form save-match-data. Here is how:
(let ((data (match-data)))
  (unwind-protect
      ...   ; Ok to change the original match data.
    (set-match-data data)))
Emacs automatically saves and restores the match data when it runs process filter functions (see section 37.9.2 Process Filter Functions) and process sentinels (see section 37.10 Sentinels: Detecting Process Status Changes).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.7 Searching and Case

By default, searches in Emacs ignore the case of the text they are searching through; if you specify searching for `FOO', then `Foo' or `foo' is also considered a match. This applies to regular expressions, too; thus, `[aB]' would match `a' or `A' or `b' or `B'.

If you do not want this feature, set the variable case-fold-search to nil. Then all letters must match exactly, including case. This is a buffer-local variable; altering the variable affects only the current buffer. (See section 11.10.1 Introduction to Buffer-Local Variables.) Alternatively, you may change the value of default-case-fold-search, which is the default value of case-fold-search for buffers that do not override it.

Note that the user-level incremental search feature handles case distinctions differently. When given a lower case letter, it looks for a match of either case, but when given an upper case letter, it looks for an upper case letter only. But this has nothing to do with the searching functions used in Lisp code.

User Option: case-replace
This variable determines whether the replacement functions should preserve case. If the variable is nil, that means to use the replacement text verbatim. A non-nil value means to convert the case of the replacement text according to the text being replaced.

This variable is used by passing it as an argument to the function replace-match. See section 34.6.1 Replacing the Text that Matched.

User Option: case-fold-search
This buffer-local variable determines whether searches should ignore case. If the variable is nil they do not ignore case; otherwise they do ignore case.

Variable: default-case-fold-search
The value of this variable is the default value for case-fold-search in buffers that do not override it. This is the same as (default-value 'case-fold-search).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

34.8 Standard Regular Expressions Used in Editing

This section describes some variables that hold regular expressions used for certain purposes in editing:

Variable: page-delimiter
This is the regular expression describing line-beginnings that separate pages. The default value is "^\014" (i.e., "^^L" or "^\C-l"); this matches a line that starts with a formfeed character.

The following two regular expressions should not assume the match always starts at the beginning of a line; they should not use `^' to anchor the match. Most often, the paragraph commands do check for a match only at the beginning of a line, which means that `^' would be superfluous. When there is a nonzero left margin, they accept matches that start after the left margin. In that case, a `^' would be incorrect. However, a `^' is harmless in modes where a left margin is never used.

Variable: paragraph-separate
This is the regular expression for recognizing the beginning of a line that separates paragraphs. (If you change this, you may have to change paragraph-start also.) The default value is "[ \t\f]*$", which matches a line that consists entirely of spaces, tabs, and form feeds (after its left margin).

Variable: paragraph-start
This is the regular expression for recognizing the beginning of a line that starts or separates paragraphs. The default value is "[ \t\n\f]", which matches a line starting with a space, tab, newline, or form feed (after its left margin).

Variable: sentence-end
This is the regular expression describing the end of a sentence. (All paragraph boundaries also end sentences, regardless.) The default value is:
"[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
This means a period, question mark or exclamation mark, followed optionally by a closing parenthetical character, followed by tabs, spaces or new lines.

For a detailed explanation of this regular expression, see 34.2.2 Complex Regexp Example.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35. Syntax Tables

A syntax table specifies the syntactic textual function of each character. This information is used by the parsing functions, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (see section 30.2.2 Motion by Words) and the list motion functions (see section 30.2.6 Moving over Balanced Expressions), as well as the functions in this chapter.

35.1 Syntax Table Concepts

Basic concepts of syntax tables.

35.2 Syntax Descriptors

How characters are classified.

35.3 Syntax Table Functions

How to create, examine and alter syntax tables.

35.4 Syntax Properties

Overriding syntax with text properties.

35.5 Motion and Syntax

Moving over characters with certain syntaxes.

35.6 Parsing Balanced Expressions

Parsing balanced expressions using the syntax table.

35.7 Some Standard Syntax Tables

Syntax tables used by various major modes.

35.8 Syntax Table Internals

How syntax table information is stored.

35.9 Categories

Another way of classifying character syntax.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.1 Syntax Table Concepts

A syntax table provides Emacs with the information that determines the syntactic use of each character in a buffer. This information is used by the parsing commands, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (see section 30.2.2 Motion by Words) and the list motion functions (see section 30.2.6 Moving over Balanced Expressions) as well as the functions in this chapter.

A syntax table is a char-table (see section 6.6 Char-Tables). The element at index c describes the character with code c. The element's value should be a list that encodes the syntax of the character in question.

Syntax tables are used only for moving across text, not for the Emacs Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp expressions, and these rules cannot be changed. (Some Lisp systems provide ways to redefine the read syntax, but we decided to leave this feature out of Emacs Lisp for simplicity.)

Each buffer has its own major mode, and each major mode has its own idea of the syntactic class of various characters. For example, in Lisp mode, the character `;' begins a comment, but in C mode, it terminates a statement. To support these variations, Emacs makes the choice of syntax table local to each buffer. Typically, each major mode has its own syntax table and installs that table in each buffer that uses that mode. Changing this table alters the syntax in all those buffers as well as in any buffers subsequently put in that mode. Occasionally several similar modes share one syntax table. See section 23.1.2 Major Mode Examples, for an example of how to set up a syntax table.

A syntax table can inherit the data for some characters from the standard syntax table, while specifying other characters itself. The "inherit" syntax class means "inherit this character's syntax from the standard syntax table." Just changing the standard syntax for a character affects all syntax tables that inherit from it.

Function: syntax-table-p object
This function returns t if object is a syntax table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.2 Syntax Descriptors

This section describes the syntax classes and flags that denote the syntax of a character, and how they are represented as a syntax descriptor, which is a Lisp string that you pass to modify-syntax-entry to specify the syntax you want.

The syntax table specifies a syntax class for each character. There is no necessary relationship between the class of a character in one syntax table and its class in any other table.

Each class is designated by a mnemonic character, which serves as the name of the class when you need to specify a class. Usually the designator character is one that is often assigned that class; however, its meaning as a designator is unvarying and independent of what syntax that character currently has. Thus, `\' as a designator character always gives "escape character" syntax, regardless of what syntax `\' currently has.

A syntax descriptor is a Lisp string that specifies a syntax class, a matching character (used only for the parenthesis classes) and flags. The first character is the designator for a syntax class. The second character is the character to match; if it is unused, put a space there. Then come the characters for any desired flags. If no matching character or flags are needed, one character is sufficient.

For example, the syntax descriptor for the character `*' in C mode is `. 23' (i.e., punctuation, matching character slot unused, second character of a comment-starter, first character of a comment-ender), and the entry for `/' is `. 14' (i.e., punctuation, matching character slot unused, first character of a comment-starter, second character of a comment-ender).

35.2.1 Table of Syntax Classes

Table of syntax classes.

35.2.2 Syntax Flags

Additional flags each character can have.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.2.1 Table of Syntax Classes

Here is a table of syntax classes, the characters that stand for them, their meanings, and examples of their use.

Syntax class: whitespace character
Whitespace characters (designated by ` ' or `-') separate symbols and words from each other. Typically, whitespace characters have no other syntactic significance, and multiple whitespace characters are syntactically equivalent to a single one. Space, tab, newline and formfeed are classified as whitespace in almost all major modes.

Syntax class: word constituent
Word constituents (designated by `w') are parts of normal English words and are typically used in variable and command names in programs. All upper- and lower-case letters, and the digits, are typically word constituents.

Syntax class: symbol constituent
Symbol constituents (designated by `_') are the extra characters that are used in variable and command names along with word constituents. For example, the symbol constituents class is used in Lisp mode to indicate that certain characters may be part of symbol names even though they are not part of English words. These characters are `$&*+-_<>'. In standard C, the only non-word-constituent character that is valid in symbols is underscore (`_').

Syntax class: punctuation character
Punctuation characters (designated by `.') are those characters that are used as punctuation in English, or are used in some way in a programming language to separate symbols from one another. Most programming language modes, including Emacs Lisp mode, have no characters in this class since the few characters that are not symbol or word constituents all have other uses.

Syntax class: open parenthesis character

Syntax class: close parenthesis character
Open and close parenthesis characters are characters used in dissimilar pairs to surround sentences or expressions. Such a grouping is begun with an open parenthesis character and terminated with a close. Each open parenthesis character matches a particular close parenthesis character, and vice versa. Normally, Emacs indicates momentarily the matching open parenthesis when you insert a close parenthesis. See section 38.14 Blinking Parentheses.

The class of open parentheses is designated by `(', and that of close parentheses by `)'.

In English text, and in C code, the parenthesis pairs are `()', `[]', and `{}'. In Emacs Lisp, the delimiters for lists and vectors (`()' and `[]') are classified as parenthesis characters.

Syntax class: string quote
String quote characters (designated by `"') are used in many languages, including Lisp and C, to delimit string constants. The same string quote character appears at the beginning and the end of a string. Such quoted strings do not nest.

The parsing facilities of Emacs consider a string as a single token. The usual syntactic meanings of the characters in the string are suppressed.

The Lisp modes have two string quote characters: double-quote (`"') and vertical bar (`|'). `|' is not used in Emacs Lisp, but it is used in Common Lisp. C also has two string quote characters: double-quote for strings, and single-quote (`'') for character constants.

English text has no string quote characters because English is not a programming language. Although quotation marks are used in English, we do not want them to turn off the usual syntactic properties of other characters in the quotation.

Syntax class: escape
An escape character (designated by `\') starts an escape sequence such as is used in C string and character constants. The character `\' belongs to this class in both C and Lisp. (In C, it is used thus only inside strings, but it turns out to cause no trouble to treat it this way throughout C code.)

Characters in this class count as part of words if words-include-escapes is non-nil. See section 30.2.2 Motion by Words.

Syntax class: character quote
A character quote character (designated by `/') quotes the following character so that it loses its normal syntactic meaning. This differs from an escape character in that only the character immediately following is ever affected.

Characters in this class count as part of words if words-include-escapes is non-nil. See section 30.2.2 Motion by Words.

This class is used for backslash in TeX mode.

Syntax class: paired delimiter
Paired delimiter characters (designated by `$') are like string quote characters except that the syntactic properties of the characters between the delimiters are not suppressed. Only TeX mode uses a paired delimiter presently--the `$' that both enters and leaves math mode.

Syntax class: expression prefix
An expression prefix operator (designated by `'') is used for syntactic operators that are considered as part of an expression if they appear next to one. In Lisp modes, these characters include the apostrophe, `'' (used for quoting), the comma, `,' (used in macros), and `#' (used in the read syntax for certain data types).

Syntax class: comment starter

Syntax class: comment ender
The comment starter and comment ender characters are used in various languages to delimit comments. These classes are designated by `<' and `>', respectively.

English text has no comment characters. In Lisp, the semicolon (`;') starts a comment and a newline or formfeed ends one.

Syntax class: inherit
This syntax class does not specify a particular syntax. It says to look in the standard syntax table to find the syntax of this character. The designator for this syntax code is `@'.

Syntax class: generic comment delimiter
A generic comment delimiter (designated by `!') starts or ends a special kind of comment. Any generic comment delimiter matches any generic comment delimiter, but they cannot match a comment starter or comment ender; generic comment delimiters can only match each other.

This syntax class is primarily meant for use with the syntax-table text property (see section 35.4 Syntax Properties). You can mark any range of characters as forming a comment, by giving the first and last characters of the range syntax-table properties identifying them as generic comment delimiters.

Syntax class: generic string delimiter
A generic string delimiter (designated by `|') starts or ends a string. This class differs from the string quote class in that any generic string delimiter can match any other generic string delimiter; but they do not match ordinary string quote characters.

This syntax class is primarily meant for use with the syntax-table text property (see section 35.4 Syntax Properties). You can mark any range of characters as forming a string constant, by giving the first and last characters of the range syntax-table properties identifying them as generic string delimiters.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.2.2 Syntax Flags

In addition to the classes, entries for characters in a syntax table can specify flags. There are seven possible flags, represented by the characters `1', `2', `3', `4', `b', `n', and `p'.

All the flags except `n' and `p' are used to describe multi-character comment delimiters. The digit flags indicate that a character can also be part of a comment sequence, in addition to the syntactic properties associated with its character class. The flags are independent of the class and each other for the sake of characters such as `*' in C mode, which is a punctuation character, and the second character of a start-of-comment sequence (`/*'), and the first character of an end-of-comment sequence (`*/').

Here is a table of the possible flags for a character c, and what they mean:

`1' means c is the start of a two-character comment-start sequence.

`2' means c is the second character of such a sequence.

`3' means c is the start of a two-character comment-end sequence.

`4' means c is the second character of such a sequence.

`b' means that c as a comment delimiter belongs to the alternative "b" comment style.
Emacs supports two comment styles simultaneously in any one syntax table. This is for the sake of C++. Each style of comment syntax has its own comment-start sequence and its own comment-end sequence. Each comment must stick to one style or the other; thus, if it starts with the comment-start sequence of style "b", it must also end with the comment-end sequence of style "b".

The two comment-start sequences must begin with the same character; only the second character may differ. Mark the second character of the "b"-style comment-start sequence with the `b' flag.

A comment-end sequence (one or two characters) applies to the "b" style if its first character has the `b' flag set; otherwise, it applies to the "a" style.

The appropriate comment syntax settings for C++ are as follows:

`/'
`124b'
`*'
`23'
newline
`>b'
This defines four comment-delimiting sequences:

`/*'
This is a comment-start sequence for "a" style because the second character, `*', does not have the `b' flag.

`//'
This is a comment-start sequence for "b" style because the second character, `/', does have the `b' flag.

`*/'
This is a comment-end sequence for "a" style because the first character, `*', does not have the `b' flag.

newline
This is a comment-end sequence for "b" style, because the newline character has the `b' flag.

`n' on a comment delimiter character specifies that this kind of comment can be nested. For a two-character comment delimiter, `n' on either character makes it nestable.

`p' identifies an additional "prefix character" for Lisp syntax. These characters are treated as whitespace when they appear between expressions. When they appear within an expression, they are handled according to their usual syntax codes.
The function backward-prefix-chars moves back over these characters, as well as over characters whose primary syntax class is prefix (`''). See section 35.5 Motion and Syntax.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.3 Syntax Table Functions

In this section we describe functions for creating, accessing and altering syntax tables.

Function: make-syntax-table
This function creates a new syntax table. It inherits the syntax for letters and control characters from the standard syntax table. For other characters, the syntax is copied from the standard syntax table.

Most major mode syntax tables are created in this way.

Function: copy-syntax-table &optional table
This function constructs a copy of table and returns it. If table is not supplied (or is nil), it returns a copy of the current syntax table. Otherwise, an error is signaled if table is not a syntax table.

Command: modify-syntax-entry char syntax-descriptor &optional table
This function sets the syntax entry for char according to syntax-descriptor. The syntax is changed only for table, which defaults to the current buffer's syntax table, and not in any other syntax table. The argument syntax-descriptor specifies the desired syntax; this is a string beginning with a class designator character, and optionally containing a matching character and flags as well. See section 35.2 Syntax Descriptors.

This function always returns nil. The old syntax information in the table for this character is discarded.

An error is signaled if the first character of the syntax descriptor is not one of the twelve syntax class designator characters. An error is also signaled if char is not a character.
Examples:

;; Put the space character in class whitespace.
(modify-syntax-entry ?\  " ")
     => nil

;; Make `$' an open parenthesis character,
;;   with `^' as its matching close.
(modify-syntax-entry ?$ "(^")
     => nil

;; Make `^' a close parenthesis character,
;;   with `$' as its matching open.
(modify-syntax-entry ?^ ")$")
     => nil

;; Make `/' a punctuation character,
;;   the first character of a start-comment sequence,
;;   and the second character of an end-comment sequence.
;;   This is used in C mode.
(modify-syntax-entry ?/ ". 14")
     => nil
Function: char-syntax character
This function returns the syntax class of character, represented by its mnemonic designator character. This returns only the class, not any matching parenthesis or flags.

An error is signaled if char is not a character.

The following examples apply to C mode. The first example shows that the syntax class of space is whitespace (represented by a space). The second example shows that the syntax of `/' is punctuation. This does not show the fact that it is also part of comment-start and -end sequences. The third example shows that open parenthesis is in the class of open parentheses. This does not show the fact that it has a matching character, `)'.
(string (char-syntax ?\ ))
     => " "

(string (char-syntax ?/))
     => "."

(string (char-syntax ?\())
     => "("
We use string to make it easier to see the character returned by char-syntax.

Function: set-syntax-table table
This function makes table the syntax table for the current buffer. It returns table.

Function: syntax-table
This function returns the current syntax table, which is the table for the current buffer.

Macro: with-syntax-table table body...
This macro executes body using table as the current syntax table. It returns the value of the last form in body, after restoring the old current syntax table.

Since each buffer has its own current syntax table, we should make that more precise: with-syntax-table temporarily alters the current syntax table of whichever buffer is current at the time the macro execution starts. Other buffers are not affected.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.4 Syntax Properties

When the syntax table is not flexible enough to specify the syntax of a language, you can use syntax-table text properties to override the syntax table for specific character occurrences in the buffer. See section 32.19 Text Properties.

The valid values of syntax-table text property are:

syntax-table
If the property value is a syntax table, that table is used instead of the current buffer's syntax table to determine the syntax for this occurrence of the character.

(syntax-code . matching-char)
A cons cell of this format specifies the syntax for this occurrence of the character. (see section 35.8 Syntax Table Internals)

nil
If the property is nil, the character's syntax is determined from the current syntax table in the usual way.

Variable: parse-sexp-lookup-properties
If this is non-nil, the syntax scanning functions pay attention to syntax text properties. Otherwise they use only the current syntax table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.5 Motion and Syntax

This section describes functions for moving across characters that have certain syntax classes.

Function: skip-syntax-forward syntaxes &optional limit
This function moves point forward across characters having syntax classes mentioned in syntaxes. It stops when it encounters the end of the buffer, or position limit (if specified), or a character it is not supposed to skip.

If syntaxes starts with `^', then the function skips characters whose syntax is not in syntaxes.

The return value is the distance traveled, which is a nonnegative integer.

Function: skip-syntax-backward syntaxes &optional limit
This function moves point backward across characters whose syntax classes are mentioned in syntaxes. It stops when it encounters the beginning of the buffer, or position limit (if specified), or a character it is not supposed to skip.

If syntaxes starts with `^', then the function skips characters whose syntax is not in syntaxes.

The return value indicates the distance traveled. It is an integer that is zero or less.

Function: backward-prefix-chars
This function moves point backward over any number of characters with expression prefix syntax. This includes both characters in the expression prefix syntax class, and characters with the `p' flag.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.6 Parsing Balanced Expressions

Here are several functions for parsing and scanning balanced expressions, also known as sexps, in which parentheses match in pairs. The syntax table controls the interpretation of characters, so these functions can be used for Lisp expressions when in Lisp mode and for C expressions when in C mode. See section 30.2.6 Moving over Balanced Expressions, for convenient higher-level functions for moving over balanced expressions.

Function: parse-partial-sexp start limit &optional target-depth stop-before state stop-comment
This function parses a sexp in the current buffer starting at start, not scanning past limit. It stops at position limit or when certain criteria described below are met, and sets point to the location where parsing stops. It returns a value describing the status of the parse at the point where it stops.

If state is nil, start is assumed to be at the top level of parenthesis structure, such as the beginning of a function definition. Alternatively, you might wish to resume parsing in the middle of the structure. To do this, you must provide a state argument that describes the initial status of parsing.

If the third argument target-depth is non-nil, parsing stops if the depth in parentheses becomes equal to target-depth. The depth starts at 0, or at whatever is given in state.

If the fourth argument stop-before is non-nil, parsing stops when it comes to any character that starts a sexp. If stop-comment is non-nil, parsing stops when it comes to the start of a comment. If stop-comment is the symbol syntax-table, parsing stops after the start of a comment or a string, or the end of a comment or a string, whichever comes first.

The fifth argument state is a nine-element list of the same form as the value of this function, described below. (It is OK to omit the last element of the nine.) The return value of one call may be used to initialize the state of the parse on another call to parse-partial-sexp.

The result is a list of nine elements describing the final state of the parse:

The depth in parentheses, counting from 0.

The character position of the start of the innermost parenthetical grouping containing the stopping point; nil if none.

The character position of the start of the last complete subexpression terminated; nil if none.

Non-nil if inside a string. More precisely, this is the character that will terminate the string, or t if a generic string delimiter character should terminate it.

t if inside a comment (of either style), or the comment nesting level if inside a kind of comment that can be nested.

t if point is just after a quote character.

The minimum parenthesis depth encountered during this scan.

What kind of comment is active: nil for a comment of style "a", t for a comment of style "b", and syntax-table for a comment that should be ended by a generic comment delimiter character.

The string or comment start position. While inside a comment, this is the position where the comment began; while inside a string, this is the position where the string began. When outside of strings and comments, this element is nil.

Elements 0, 3, 4, 5 and 7 are significant in the argument state.

This function is most often used to compute indentation for languages that have nested parentheses.

Function: scan-lists from count depth
This function scans forward count balanced parenthetical groupings from position from. It returns the position where the scan stops. If count is negative, the scan moves backwards.

If depth is nonzero, parenthesis depth counting begins from that value. The only candidates for stopping are places where the depth in parentheses becomes zero; scan-lists counts count such places and then stops. Thus, a positive value for depth means go out depth levels of parenthesis.

Scanning ignores comments if parse-sexp-ignore-comments is non-nil.

If the scan reaches the beginning or end of the buffer (or its accessible portion), and the depth is not zero, an error is signaled. If the depth is zero but the count is not used up, nil is returned.

Function: scan-sexps from count
This function scans forward count sexps from position from. It returns the position where the scan stops. If count is negative, the scan moves backwards.

Scanning ignores comments if parse-sexp-ignore-comments is non-nil.

If the scan reaches the beginning or end of (the accessible part of) the buffer while in the middle of a parenthetical grouping, an error is signaled. If it reaches the beginning or end between groupings but before count is used up, nil is returned.

Variable: multibyte-syntax-as-symbol
If this variable is non-nil, scan-sexps treats all non-ASCII characters as symbol constituents regardless of what the syntax table says about them. (However, text properties can still override the syntax.)

Variable: parse-sexp-ignore-comments
If the value is non-nil, then comments are treated as whitespace by the functions in this section and by forward-sexp.

In older Emacs versions, this feature worked only when the comment terminator is something like `*/', and appears only to end a comment. In languages where newlines terminate comments, it was necessary make this variable nil, since not every newline is the end of a comment. This limitation no longer exists.

You can use forward-comment to move forward or backward over one comment or several comments.

Function: forward-comment count
This function moves point forward across count comments (backward, if count is negative). If it finds anything other than a comment or whitespace, it stops, leaving point at the place where it stopped. It also stops after satisfying count.

To move forward over all comments and whitespace following point, use (forward-comment (buffer-size)). (buffer-size) is a good argument to use, because the number of comments in the buffer cannot exceed that many.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.7 Some Standard Syntax Tables

Most of the major modes in Emacs have their own syntax tables. Here are several of them:

Function: standard-syntax-table
This function returns the standard syntax table, which is the syntax table used in Fundamental mode.

Variable: text-mode-syntax-table
The value of this variable is the syntax table used in Text mode.

Variable: c-mode-syntax-table
The value of this variable is the syntax table for C-mode buffers.

Variable: emacs-lisp-mode-syntax-table
The value of this variable is the syntax table used in Emacs Lisp mode by editing commands. (It has no effect on the Lisp read function.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.8 Syntax Table Internals

Lisp programs don't usually work with the elements directly; the Lisp-level syntax table functions usually work with syntax descriptors (see section 35.2 Syntax Descriptors). Nonetheless, here we document the internal format. This format is used mostly when manipulating syntax properties.

Each element of a syntax table is a cons cell of the form (syntax-code . matching-char). The CAR, syntax-code, is an integer that encodes the syntax class, and any flags. The CDR, matching-char, is non-nil if a character to match was specified.

This table gives the value of syntax-code which corresponds to each syntactic type.

Integer Class

Integer Class

Integer Class

0 whitespace

5 close parenthesis

10 character quote

1 punctuation

6 expression prefix

11 comment-start

2 word

7 string quote

12 comment-end

3 symbol

8 paired delimiter

13 inherit

4 open parenthesis

9 escape

14 comment-fence

15 string-fence

For example, the usual syntax value for `(' is (4 . 41). (41 is the character code for `)'.)

The flags are encoded in higher order bits, starting 16 bits from the least significant bit. This table gives the power of two which corresponds to each syntax flag.

Prefix Flag

Prefix Flag

Prefix Flag

`1' (lsh 1 16)

`4' (lsh 1 19)

`b' (lsh 1 21)

`2' (lsh 1 17)

`p' (lsh 1 20)

`n' (lsh 1 22)

`3' (lsh 1 18)

Function: string-to-syntax desc
This function returns the internal form (syntax-code . matching-char) corresponding to the syntax descriptor desc.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

35.9 Categories

Categories provide an alternate way of classifying characters syntactically. You can define several categories as needed, then independently assign each character to one or more categories. Unlike syntax classes, categories are not mutually exclusive; it is normal for one character to belong to several categories.

Each buffer has a category table which records which categories are defined and also which characters belong to each category. Each category table defines its own categories, but normally these are initialized by copying from the standard categories table, so that the standard categories are available in all modes.

Each category has a name, which is an ASCII printing character in the range ` ' to `~'. You specify the name of a category when you define it with define-category.

The category table is actually a char-table (see section 6.6 Char-Tables). The element of the category table at index c is a category set---a bool-vector--that indicates which categories character c belongs to. In this category set, if the element at index cat is t, that means category cat is a member of the set, and that character c belongs to category cat.

Function: define-category char docstring &optional table
This function defines a new category, with name char and documentation docstring.

The new category is defined for category table table, which defaults to the current buffer's category table.

Function: category-docstring category &optional table
This function returns the documentation string of category category in category table table.
(category-docstring ?a)
     => "ASCII"
(category-docstring ?l)
     => "Latin"
Function: get-unused-category table
This function returns a category name (a character) which is not currently defined in table. If all possible categories are in use in table, it returns nil.

Function: category-table
This function returns the current buffer's category table.

Function: category-table-p object
This function returns t if object is a category table, otherwise nil.

Function: standard-category-table
This function returns the standard category table.

Function: copy-category-table &optional table
This function constructs a copy of table and returns it. If table is not supplied (or is nil), it returns a copy of the current category table. Otherwise, an error is signaled if table is not a category table.

Function: set-category-table table
This function makes table the category table for the current buffer. It returns table.

Function: make-category-table
This creates and returns an empty category table. In an empty category table, no categories have been allocated, and no characters belong to any categories.

Function: make-category-set categories
This function returns a new category set--a bool-vector--whose initial contents are the categories listed in the string categories. The elements of categories should be category names; the new category set has t for each of those categories, and nil for all other categories.
(make-category-set "al")
     => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
Function: char-category-set char
This function returns the category set for character char. This is the bool-vector which records which categories the character char belongs to. The function char-category-set does not allocate storage, because it returns the same bool-vector that exists in the category table.
(char-category-set ?a)
     => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
Function: category-set-mnemonics category-set
This function converts the category set category-set into a string containing the characters that designate the categories that are members of the set.
(category-set-mnemonics (char-category-set ?a))
     => "al"
Function: modify-category-entry character category &optional table reset
This function modifies the category set of character in category table table (which defaults to the current buffer's category table).

Normally, it modifies the category set by adding category to it. But if reset is non-nil, then it deletes category instead.

Command: describe-categories
This function describes the category specifications in the current category table. The descriptions are inserted in a buffer, which is then displayed.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36. Abbrevs and Abbrev Expansion

An abbreviation or abbrev is a string of characters that may be expanded to a longer string. The user can insert the abbrev string and find it replaced automatically with the expansion of the abbrev. This saves typing.

The set of abbrevs currently in effect is recorded in an abbrev table. Each buffer has a local abbrev table, but normally all buffers in the same major mode share one abbrev table. There is also a global abbrev table. Normally both are used.

An abbrev table is represented as an obarray containing a symbol for each abbreviation. The symbol's name is the abbreviation; its value is the expansion; its function definition is the hook function to do the expansion (see section 36.3 Defining Abbrevs); its property list cell contains the use count, the number of times the abbreviation has been expanded. Because these symbols are not interned in the usual obarray, they will never appear as the result of reading a Lisp expression; in fact, normally they are never used except by the code that handles abbrevs. Therefore, it is safe to use them in an extremely nonstandard way. See section 8.3 Creating and Interning Symbols.

For the user-level commands for abbrevs, see section `Abbrev Mode' in The GNU Emacs Manual.

36.1 Setting Up Abbrev Mode

Setting up Emacs for abbreviation.

36.2 Abbrev Tables

Creating and working with abbrev tables.

36.3 Defining Abbrevs

Specifying abbreviations and their expansions.

36.4 Saving Abbrevs in Files

Saving abbrevs in files.

36.5 Looking Up and Expanding Abbreviations

Controlling expansion; expansion subroutines.

36.6 Standard Abbrev Tables

Abbrev tables used by various major modes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.1 Setting Up Abbrev Mode

Abbrev mode is a minor mode controlled by the value of the variable abbrev-mode.

Variable: abbrev-mode
A non-nil value of this variable turns on the automatic expansion of abbrevs when their abbreviations are inserted into a buffer. If the value is nil, abbrevs may be defined, but they are not expanded automatically.

This variable automatically becomes buffer-local when set in any fashion.

Variable: default-abbrev-mode
This is the value of abbrev-mode for buffers that do not override it. This is the same as (default-value 'abbrev-mode).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.2 Abbrev Tables

This section describes how to create and manipulate abbrev tables.

Function: make-abbrev-table
This function creates and returns a new, empty abbrev table--an obarray containing no symbols. It is a vector filled with zeros.

Function: clear-abbrev-table table
This function undefines all the abbrevs in abbrev table table, leaving it empty. It always returns nil.

Function: define-abbrev-table tabname definitions
This function defines tabname (a symbol) as an abbrev table name, i.e., as a variable whose value is an abbrev table. It defines abbrevs in the table according to definitions, a list of elements of the form (abbrevname expansion hook usecount). The return value is always nil.

Variable: abbrev-table-name-list
This is a list of symbols whose values are abbrev tables. define-abbrev-table adds the new abbrev table name to this list.

Function: insert-abbrev-table-description name &optional human
This function inserts before point a description of the abbrev table named name. The argument name is a symbol whose value is an abbrev table. The return value is always nil.

If human is non-nil, the description is human-oriented. Otherwise the description is a Lisp expression--a call to define-abbrev-table that would define name exactly as it is currently defined.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.3 Defining Abbrevs

These functions define an abbrev in a specified abbrev table. define-abbrev is the low-level basic function, while add-abbrev is used by commands that ask for information from the user.

Function: add-abbrev table type arg
This function adds an abbreviation to abbrev table table based on information from the user. The argument type is a string describing in English the kind of abbrev this will be (typically, "global" or "mode-specific"); this is used in prompting the user. The argument arg is the number of words in the expansion.

The return value is the symbol that internally represents the new abbrev, or nil if the user declines to confirm redefining an existing abbrev.

Function: define-abbrev table name expansion &optional hook count
This function defines an abbrev named name, in table, to expand to expansion and call hook. The value of count, if specified, initializes the abbrev's usage-count. If count is not specified or nil, the use count is initialized to zero. The return value is a symbol that represents the abbrev inside Emacs; its name is name.

The argument name should be a string. The argument expansion is normally the desired expansion (a string), or nil to undefine the abbrev. If it is anything but a string or nil, then the abbreviation "expands" solely by running hook.

The argument hook is a function or nil. If hook is non-nil, then it is called with no arguments after the abbrev is replaced with expansion; point is located at the end of expansion when hook is called.

If hook is a non-nil symbol whose no-self-insert property is non-nil, hook can explicitly control whether to insert the self-inserting input character that triggered the expansion. If hook returns non-nil in this case, that inhibits insertion of the character. By contrast, if hook returns nil, expand-abbrev also returns nil, as if expansion had not really occurred.

User Option: only-global-abbrevs
If this variable is non-nil, it means that the user plans to use global abbrevs only. This tells the commands that define mode-specific abbrevs to define global ones instead. This variable does not alter the behavior of the functions in this section; it is examined by their callers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.4 Saving Abbrevs in Files

A file of saved abbrev definitions is actually a file of Lisp code. The abbrevs are saved in the form of a Lisp program to define the same abbrev tables with the same contents. Therefore, you can load the file with load (see section 15.1 How Programs Do Loading). However, the function quietly-read-abbrev-file is provided as a more convenient interface.

User-level facilities such as save-some-buffers can save abbrevs in a file automatically, under the control of variables described here.

User Option: abbrev-file-name
This is the default file name for reading and saving abbrevs.

Function: quietly-read-abbrev-file &optional filename
This function reads abbrev definitions from a file named filename, previously written with write-abbrev-file. If filename is omitted or nil, the file specified in abbrev-file-name is used. save-abbrevs is set to t so that changes will be saved.

This function does not display any messages. It returns nil.

User Option: save-abbrevs
A non-nil value for save-abbrev means that Emacs should save abbrevs when files are saved. abbrev-file-name specifies the file to save the abbrevs in.

Variable: abbrevs-changed
This variable is set non-nil by defining or altering any abbrevs. This serves as a flag for various Emacs commands to offer to save your abbrevs.

Command: write-abbrev-file &optional filename
Save all abbrev definitions, in all abbrev tables, in the file filename, in the form of a Lisp program that when loaded will define the same abbrevs. If filename is nil or omitted, abbrev-file-name is used. This function returns nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.5 Looking Up and Expanding Abbreviations

Abbrevs are usually expanded by certain interactive commands, including self-insert-command. This section describes the subroutines used in writing such commands, as well as the variables they use for communication.

Function: abbrev-symbol abbrev &optional table
This function returns the symbol representing the abbrev named abbrev. The value returned is nil if that abbrev is not defined. The optional second argument table is the abbrev table to look it up in. If table is nil, this function tries first the current buffer's local abbrev table, and second the global abbrev table.

Function: abbrev-expansion abbrev &optional table
This function returns the string that abbrev would expand into (as defined by the abbrev tables used for the current buffer). The optional argument table specifies the abbrev table to use, as in abbrev-symbol.

Command: expand-abbrev
This command expands the abbrev before point, if any. If point does not follow an abbrev, this command does nothing. The command returns the abbrev symbol if it did expansion, nil otherwise.

If the abbrev symbol has a hook function which is a symbol whose no-self-insert property is non-nil, and if the hook function returns nil as its value, then expand-abbrev returns nil even though expansion did occur.

Command: abbrev-prefix-mark &optional arg
Mark current point as the beginning of an abbrev. The next call to expand-abbrev will use the text from here to point (where it is then) as the abbrev to expand, rather than using the previous word as usual.

User Option: abbrev-all-caps
When this is set non-nil, an abbrev entered entirely in upper case is expanded using all upper case. Otherwise, an abbrev entered entirely in upper case is expanded by capitalizing each word of the expansion.

Variable: abbrev-start-location
This is the buffer position for expand-abbrev to use as the start of the next abbrev to be expanded. (nil means use the word before point instead.) abbrev-start-location is set to nil each time expand-abbrev is called. This variable is also set by abbrev-prefix-mark.

Variable: abbrev-start-location-buffer
The value of this variable is the buffer for which abbrev-start-location has been set. Trying to expand an abbrev in any other buffer clears abbrev-start-location. This variable is set by abbrev-prefix-mark.

Variable: last-abbrev
This is the abbrev-symbol of the most recent abbrev expanded. This information is left by expand-abbrev for the sake of the unexpand-abbrev command (see section `Expanding Abbrevs' in The GNU Emacs Manual).

Variable: last-abbrev-location
This is the location of the most recent abbrev expanded. This contains information left by expand-abbrev for the sake of the unexpand-abbrev command.

Variable: last-abbrev-text
This is the exact expansion text of the most recent abbrev expanded, after case conversion (if any). Its value is nil if the abbrev has already been unexpanded. This contains information left by expand-abbrev for the sake of the unexpand-abbrev command.

Variable: pre-abbrev-expand-hook
This is a normal hook whose functions are executed, in sequence, just before any expansion of an abbrev. See section 23.6 Hooks. Since it is a normal hook, the hook functions receive no arguments. However, they can find the abbrev to be expanded by looking in the buffer before point. Running the hook is the first thing that expand-abbrev does, and so a hook function can be used to change the current abbrev table before abbrev lookup happens.

The following sample code shows a simple use of pre-abbrev-expand-hook. If the user terminates an abbrev with a punctuation character, the hook function asks for confirmation. Thus, this hook allows the user to decide whether to expand the abbrev, and aborts expansion if it is not confirmed.
(add-hook 'pre-abbrev-expand-hook 'query-if-not-space)

;; This is the function invoked by pre-abbrev-expand-hook.

;; If the user terminated the abbrev with a space, the function does
;; nothing (that is, it returns so that the abbrev can expand).  If the
;; user entered some other character, this function asks whether
;; expansion should continue.

;; If the user answers the prompt with y, the function returns
;; nil (because of the not function), but that is
;; acceptable; the return value has no effect on expansion.

(defun query-if-not-space ()
  (if (/= ?\  (preceding-char))
      (if (not (y-or-n-p "Do you want to expand this abbrev? "))
          (error "Not expanding this abbrev"))))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.6 Standard Abbrev Tables

Here we list the variables that hold the abbrev tables for the preloaded major modes of Emacs.

Variable: global-abbrev-table
This is the abbrev table for mode-independent abbrevs. The abbrevs defined in it apply to all buffers. Each buffer may also have a local abbrev table, whose abbrev definitions take precedence over those in the global table.

Variable: local-abbrev-table
The value of this buffer-local variable is the (mode-specific) abbreviation table of the current buffer.

Variable: fundamental-mode-abbrev-table
This is the local abbrev table used in Fundamental mode; in other words, it is the local abbrev table in all buffers in Fundamental mode.

Variable: text-mode-abbrev-table
This is the local abbrev table used in Text mode.

Variable: lisp-mode-abbrev-table
This is the local abbrev table used in Lisp mode and Emacs Lisp mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37. Processes

In the terminology of operating systems, a process is a space in which a program can execute. Emacs runs in a process. Emacs Lisp programs can invoke other programs in processes of their own. These are called subprocesses or child processes of the Emacs process, which is their parent process.

A subprocess of Emacs may be synchronous or asynchronous, depending on how it is created. When you create a synchronous subprocess, the Lisp program waits for the subprocess to terminate before continuing execution. When you create an asynchronous subprocess, it can run in parallel with the Lisp program. This kind of subprocess is represented within Emacs by a Lisp object which is also called a "process". Lisp programs can use this object to communicate with the subprocess or to control it. For example, you can send signals, obtain status information, receive output from the process, or send input to it.

Function: processp object
This function returns t if object is a process, nil otherwise.

37.1 Functions that Create Subprocesses

Functions that start subprocesses.

37.2 Shell Arguments

Quoting an argument to pass it to a shell.

37.3 Creating a Synchronous Process

Details of using synchronous subprocesses.

37.4 Creating an Asynchronous Process

Starting up an asynchronous subprocess.

37.5 Deleting Processes

Eliminating an asynchronous subprocess.

37.6 Process Information

Accessing run-status and other attributes.

37.7 Sending Input to Processes

Sending input to an asynchronous subprocess.

37.8 Sending Signals to Processes

Stopping, continuing or interrupting an asynchronous subprocess.

37.9 Receiving Output from Processes

Collecting output from an asynchronous subprocess.

37.10 Sentinels: Detecting Process Status Changes

Sentinels run when process run-status changes.

37.11 Transaction Queues

Transaction-based communication with subprocesses.

37.12 Network Connections

Opening network connections.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.1 Functions that Create Subprocesses

There are three functions that create a new subprocess in which to run a program. One of them, start-process, creates an asynchronous process and returns a process object (see section 37.4 Creating an Asynchronous Process). The other two, call-process and call-process-region, create a synchronous process and do not return a process object (see section 37.3 Creating a Synchronous Process).

Synchronous and asynchronous processes are explained in the following sections. Since the three functions are all called in a similar fashion, their common arguments are described here.

In all cases, the function's program argument specifies the program to be run. An error is signaled if the file is not found or cannot be executed. If the file name is relative, the variable exec-path contains a list of directories to search. Emacs initializes exec-path when it starts up, based on the value of the environment variable PATH. The standard file name constructs, `~', `.', and `..', are interpreted as usual in exec-path, but environment variable substitutions (`$HOME', etc.) are not recognized; use substitute-in-file-name to perform them (see section 25.8.4 Functions that Expand Filenames).

Each of the subprocess-creating functions has a buffer-or-name argument which specifies where the standard output from the program will go. It should be a buffer or a buffer name; if it is a buffer name, that will create the buffer if it does not already exist. It can also be nil, which says to discard the output unless a filter function handles it. (See section 37.9.2 Process Filter Functions, and 19. Reading and Printing Lisp Objects.) Normally, you should avoid having multiple processes send output to the same buffer because their output would be intermixed randomly.

All three of the subprocess-creating functions have a &rest argument, args. The args must all be strings, and they are supplied to program as separate command line arguments. Wildcard characters and other shell constructs have no special meanings in these strings, since the whole strings are passed directly to the specified program.

Please note: The argument program contains only the name of the program; it may not contain any command-line arguments. You must use args to provide those.

The subprocess gets its current directory from the value of default-directory (see section 25.8.4 Functions that Expand Filenames).

The subprocess inherits its environment from Emacs, but you can specify overrides for it with process-environment. See section 40.3 Operating System Environment.

Variable: exec-directory
The value of this variable is a string, the name of a directory that contains programs that come with GNU Emacs, programs intended for Emacs to invoke. The program movemail is an example of such a program; Rmail uses it to fetch new mail from an inbox.

User Option: exec-path
The value of this variable is a list of directories to search for programs to run in subprocesses. Each element is either the name of a directory (i.e., a string), or nil, which stands for the default directory (which is the value of default-directory).

The value of exec-path is used by call-process and start-process when the program argument is not an absolute file name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.2 Shell Arguments

Lisp programs sometimes need to run a shell and give it a command that contains file names that were specified by the user. These programs ought to be able to support any valid file name. But the shell gives special treatment to certain characters, and if these characters occur in the file name, they will confuse the shell. To handle these characters, use the function shell-quote-argument:

Function: shell-quote-argument argument
This function returns a string which represents, in shell syntax, an argument whose actual contents are argument. It should work reliably to concatenate the return value into a shell command and then pass it to a shell for execution.

Precisely what this function does depends on your operating system. The function is designed to work with the syntax of your system's standard shell; if you use an unusual shell, you will need to redefine this function.
;; This example shows the behavior on GNU and Unix systems.
(shell-quote-argument "foo > bar")
     => "foo\\ \\>\\ bar"

;; This example shows the behavior on MS-DOS and MS-Windows systems.
(shell-quote-argument "foo > bar")
     => "\"foo > bar\""
Here's an example of using shell-quote-argument to construct a shell command:
(concat "diff -c "
        (shell-quote-argument oldfile)
        " "
        (shell-quote-argument newfile))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.3 Creating a Synchronous Process

After a synchronous process is created, Emacs waits for the process to terminate before continuing. Starting Dired on GNU or Unix(9) is an example of this: it runs ls in a synchronous process, then modifies the output slightly. Because the process is synchronous, the entire directory listing arrives in the buffer before Emacs tries to do anything with it.

While Emacs waits for the synchronous subprocess to terminate, the user can quit by typing C-g. The first C-g tries to kill the subprocess with a SIGINT signal; but it waits until the subprocess actually terminates before quitting. If during that time the user types another C-g, that kills the subprocess instantly with SIGKILL and quits immediately (except on MS-DOS, where killing other processes doesn't work). See section 21.10 Quitting.

The synchronous subprocess functions return an indication of how the process terminated.

The output from a synchronous subprocess is generally decoded using a coding system, much like text read from a file. The input sent to a subprocess by call-process-region is encoded using a coding system, much like text written into a file. See section 33.10 Coding Systems.

Function: call-process program &optional infile destination display &rest args
This function calls program in a separate process and waits for it to finish.

The standard input for the process comes from file infile if infile is not nil, and from the null device otherwise. The argument destination says where to put the process output. Here are the possibilities:

a buffer
Insert the output in that buffer, before point. This includes both the standard output stream and the standard error stream of the process.

a string
Insert the output in a buffer with that name, before point.

t
Insert the output in the current buffer, before point.

nil
Discard the output.

0
Discard the output, and return nil immediately without waiting for the subprocess to finish.
In this case, the process is not truly synchronous, since it can run in parallel with Emacs; but you can think of it as synchronous in that Emacs is essentially finished with the subprocess as soon as this function returns.

MS-DOS doesn't support asynchronous subprocesses, so this option doesn't work there.

(real-destination error-destination)
Keep the standard output stream separate from the standard error stream; deal with the ordinary output as specified by real-destination, and dispose of the error output according to error-destination. If error-destination is nil, that means to discard the error output, t means mix it with the ordinary output, and a string specifies a file name to redirect error output into.
You can't directly specify a buffer to put the error output in; that is too difficult to implement. But you can achieve this result by sending the error output to a temporary file and then inserting the file into a buffer.
If display is non-nil, then call-process redisplays the buffer as output is inserted. (However, if the coding system chosen for decoding output is undecided, meaning deduce the encoding from the actual data, then redisplay sometimes cannot continue once non-ASCII characters are encountered. There are fundamental reasons why it is hard to fix this; see 37.9 Receiving Output from Processes.)

Otherwise the function call-process does no redisplay, and the results become visible on the screen only when Emacs redisplays that buffer in the normal course of events.

The remaining arguments, args, are strings that specify command line arguments for the program.

The value returned by call-process (unless you told it not to wait) indicates the reason for process termination. A number gives the exit status of the subprocess; 0 means success, and any other value means failure. If the process terminated with a signal, call-process returns a string describing the signal.

In the examples below, the buffer `foo' is current.
(call-process "pwd" nil t)
     => 0

---------- Buffer: foo ----------
/usr/user/lewis/manual
---------- Buffer: foo ----------

(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
     => 0

---------- Buffer: bar ----------
lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh

---------- Buffer: bar ----------
Here is a good example of the use of call-process, which used to be found in the definition of insert-directory:
(call-process insert-directory-program nil t nil switches
              (if full-directory-p
                  (concat (file-name-as-directory file) ".")
                file))
Function: call-process-region start end program &optional delete destination display &rest args
This function sends the text from start to end as standard input to a process running program. It deletes the text sent if delete is non-nil; this is useful when destination is t, to insert the output in the current buffer in place of the input.

The arguments destination and display control what to do with the output from the subprocess, and whether to update the display as it comes in. For details, see the description of call-process, above. If destination is the integer 0, call-process-region discards the output and returns nil immediately, without waiting for the subprocess to finish (this only works if asynchronous subprocesses are supported).

The remaining arguments, args, are strings that specify command line arguments for the program.

The return value of call-process-region is just like that of call-process: nil if you told it to return without waiting; otherwise, a number or string which indicates how the subprocess terminated.

In the following example, we use call-process-region to run the cat utility, with standard input being the first five characters in buffer `foo' (the word `input'). cat copies its standard input into its standard output. Since the argument destination is t, this output is inserted in the current buffer.
---------- Buffer: foo ----------
input-!-
---------- Buffer: foo ----------

(call-process-region 1 6 "cat" nil t)
     => 0

---------- Buffer: foo ----------
inputinput-!-
---------- Buffer: foo ----------
The shell-command-on-region command uses call-process-region like this:
(call-process-region
 start end
 shell-file-name      ; Name of program.
 nil                  ; Do not delete region.
 buffer               ; Send output to buffer.
 nil                  ; No redisplay during output.
 "-c" command)        ; Arguments for the shell.
Function: shell-command-to-string command
This function executes command (a string) as a shell command, then returns the command's output as a string.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.4 Creating an Asynchronous Process

After an asynchronous process is created, Emacs and the subprocess both continue running immediately. The process thereafter runs in parallel with Emacs, and the two can communicate with each other using the functions described in the following sections. However, communication is only partially asynchronous: Emacs sends data to the process only when certain functions are called, and Emacs accepts data from the process only when Emacs is waiting for input or for a time delay.

Here we describe how to create an asynchronous process.

Function: start-process name buffer-or-name program &rest args
This function creates a new asynchronous subprocess and starts the program program running in it. It returns a process object that stands for the new subprocess in Lisp. The argument name specifies the name for the process object; if a process with this name already exists, then name is modified (by appending `<1>', etc.) to be unique. The buffer buffer-or-name is the buffer to associate with the process.

The remaining arguments, args, are strings that specify command line arguments for the program.

In the example below, the first process is started and runs (rather, sleeps) for 100 seconds. Meanwhile, the second process is started, and given the name `my-process<1>' for the sake of uniqueness. It inserts the directory listing at the end of the buffer `foo', before the first process finishes. Then it finishes, and a message to that effect is inserted in the buffer. Much later, the first process finishes, and another message is inserted in the buffer for it.
(start-process "my-process" "foo" "sleep" "100")
     => #<process my-process>

(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
     => #<process my-process<1>>

---------- Buffer: foo ----------
total 2
lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
-rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon

Process my-process<1> finished

Process my-process finished
---------- Buffer: foo ----------
Function: start-process-shell-command name buffer-or-name command &rest command-args
This function is like start-process except that it uses a shell to execute the specified command. The argument command is a shell command name, and command-args are the arguments for the shell command. The variable shell-file-name specifies which shell to use.

The point of running a program through the shell, rather than directly with start-process, is so that you can employ shell features such as wildcards in the arguments. It follows that if you include an arbitrary user-specified arguments in the command, you should quote it with shell-quote-argument first, so that any special shell characters do not have their special shell meanings. See section 37.2 Shell Arguments.

Variable: process-connection-type
This variable controls the type of device used to communicate with asynchronous subprocesses. If it is non-nil, then PTYs are used, when available. Otherwise, pipes are used.

PTYs are usually preferable for processes visible to the user, as in Shell mode, because they allow job control (C-c, C-z, etc.) to work between the process and its children, whereas pipes do not. For subprocesses used for internal purposes by programs, it is often better to use a pipe, because they are more efficient. In addition, the total number of PTYs is limited on many systems and it is good not to waste them.

The value of process-connection-type is used when start-process is called. So you can specify how to communicate with one subprocess by binding the variable around the call to start-process.
(let ((process-connection-type nil))  ; Use a pipe.
  (start-process ...))
To determine whether a given subprocess actually got a pipe or a PTY, use the function process-tty-name (see section 37.6 Process Information).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.5 Deleting Processes

Deleting a process disconnects Emacs immediately from the subprocess, and removes it from the list of active processes. It sends a signal to the subprocess to make the subprocess terminate, but this is not guaranteed to happen immediately. The process object itself continues to exist as long as other Lisp objects point to it. The process mark continues to point to the same place as before (usually into a buffer where output from the process was being inserted).

You can delete a process explicitly at any time. Processes are deleted automatically after they terminate, but not necessarily right away. If you delete a terminated process explicitly before it is deleted automatically, no harm results.

User Option: delete-exited-processes
This variable controls automatic deletion of processes that have terminated (due to calling exit or to a signal). If it is nil, then they continue to exist until the user runs list-processes. Otherwise, they are deleted immediately after they exit.

Function: delete-process name
This function deletes the process associated with name, killing it with a SIGHUP signal. The argument name may be a process, the name of a process, a buffer, or the name of a buffer.
(delete-process "*shell*")
     => nil
Function: process-kill-without-query process &optional do-query
This function specifies whether Emacs should query the user if process is still running when Emacs is exited. If do-query is nil, the process will be deleted silently. Otherwise, Emacs will query about killing it.

The value is t if the process was formerly set up to require query, nil otherwise. A newly-created process always requires query.
(process-kill-without-query (get-process "shell"))
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.6 Process Information

Several functions return information about processes. list-processes is provided for interactive use.

Command: list-processes
This command displays a listing of all living processes. In addition, it finally deletes any process whose status was `Exited' or `Signaled'. It returns nil.

Function: process-list
This function returns a list of all processes that have not been deleted.
(process-list)
     => (#<process display-time> #<process shell>)
Function: get-process name
This function returns the process named name, or nil if there is none. An error is signaled if name is not a string.
(get-process "shell")
     => #<process shell>
Function: process-command process
This function returns the command that was executed to start process. This is a list of strings, the first string being the program executed and the rest of the strings being the arguments that were given to the program.
(process-command (get-process "shell"))
     => ("/bin/csh" "-i")
Function: process-id process
This function returns the PID of process. This is an integer that distinguishes the process process from all other processes running on the same computer at the current time. The PID of a process is chosen by the operating system kernel when the process is started and remains constant as long as the process exists.

Function: process-name process
This function returns the name of process.

Function: process-contact process
This function returns t for an ordinary child process, and (hostname service) for a net connection (see section 37.12 Network Connections).

Function: process-status process-name
This function returns the status of process-name as a symbol. The argument process-name must be a process, a buffer, a process name (string) or a buffer name (string).

The possible values for an actual subprocess are:

run
for a process that is running.
stop
for a process that is stopped but continuable.
exit
for a process that has exited.
signal
for a process that has received a fatal signal.
open
for a network connection that is open.
closed
for a network connection that is closed. Once a connection is closed, you cannot reopen it, though you might be able to open a new connection to the same place.
nil
if process-name is not the name of an existing process.
(process-status "shell")
     => run
(process-status (get-buffer "*shell*"))
     => run
x
     => #<process xx<1>>
(process-status x)
     => exit
For a network connection, process-status returns one of the symbols open or closed. The latter means that the other side closed the connection, or Emacs did delete-process.

Function: process-exit-status process
This function returns the exit status of process or the signal number that killed it. (Use the result of process-status to determine which of those it is.) If process has not yet terminated, the value is 0.

Function: process-tty-name process
This function returns the terminal name that process is using for its communication with Emacs--or nil if it is using pipes instead of a terminal (see process-connection-type in 37.4 Creating an Asynchronous Process).

Function: process-coding-system process
This function returns a cons cell describing the coding systems in use for decoding output from process and for encoding input to process (see section 33.10 Coding Systems). The value has this form:
(coding-system-for-decoding . coding-system-for-encoding)
Function: set-process-coding-system process decoding-system encoding-system
This function specifies the coding systems to use for subsequent output from and input to process. It will use decoding-system to decode subprocess output, and encoding-system to encode subprocess input.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.7 Sending Input to Processes

Asynchronous subprocesses receive input when it is sent to them by Emacs, which is done with the functions in this section. You must specify the process to send input to, and the input data to send. The data appears on the "standard input" of the subprocess.

Some operating systems have limited space for buffered input in a PTY. On these systems, Emacs sends an EOF periodically amidst the other characters, to force them through. For most programs, these EOFs do no harm.

Subprocess input is normally encoded using a coding system before the subprocess receives it, much like text written into a file. You can use set-process-coding-system to specify which coding system to use (see section 37.6 Process Information). Otherwise, the coding system comes from coding-system-for-write, if that is non-nil; or else from the defaulting mechanism (see section 33.10.5 Default Coding Systems).

Sometimes the system is unable to accept input for that process, because the input buffer is full. When this happens, the send functions wait a short while, accepting output from subprocesses, and then try again. This gives the subprocess a chance to read more of its pending input and make space in the buffer. It also allows filters, sentinels and timers to run--so take account of that in writing your code.

Function: process-send-string process-name string
This function sends process-name the contents of string as standard input. The argument process-name must be a process or the name of a process. If it is nil, the current buffer's process is used.

The function returns nil.
(process-send-string "shell<1>" "ls\n")
     => nil

---------- Buffer: *shell* ----------
...
introduction.texi               syntax-tables.texi~
introduction.texi~              text.texi
introduction.txt                text.texi~
...
---------- Buffer: *shell* ----------
Function: process-send-region process-name start end
This function sends the text in the region defined by start and end as standard input to process-name, which is a process or a process name. (If it is nil, the current buffer's process is used.)

An error is signaled unless both start and end are integers or markers that indicate positions in the current buffer. (It is unimportant which number is larger.)

Function: process-send-eof &optional process-name
This function makes process-name see an end-of-file in its input. The EOF comes after any text already sent to it.

If process-name is not supplied, or if it is nil, then this function sends the EOF to the current buffer's process. An error is signaled if the current buffer has no process.

The function returns process-name.
(process-send-eof "shell")
     => "shell"
Function: process-running-child-p process
This function will tell you whether a subprocess has given control of its terminal to its own child process. The value is t if this is true, or if Emacs cannot tell; it is nil if Emacs can be certain that this is not so.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.8 Sending Signals to Processes

Sending a signal to a subprocess is a way of interrupting its activities. There are several different signals, each with its own meaning. The set of signals and their names is defined by the operating system. For example, the signal SIGINT means that the user has typed C-c, or that some analogous thing has happened.

Each signal has a standard effect on the subprocess. Most signals kill the subprocess, but some stop or resume execution instead. Most signals can optionally be handled by programs; if the program handles the signal, then we can say nothing in general about its effects.

You can send signals explicitly by calling the functions in this section. Emacs also sends signals automatically at certain times: killing a buffer sends a SIGHUP signal to all its associated processes; killing Emacs sends a SIGHUP signal to all remaining processes. (SIGHUP is a signal that usually indicates that the user hung up the phone.)

Each of the signal-sending functions takes two optional arguments: process-name and current-group.

The argument process-name must be either a process, the name of one, or nil. If it is nil, the process defaults to the process associated with the current buffer. An error is signaled if process-name does not identify a process.

The argument current-group is a flag that makes a difference when you are running a job-control shell as an Emacs subprocess. If it is non-nil, then the signal is sent to the current process-group of the terminal that Emacs uses to communicate with the subprocess. If the process is a job-control shell, this means the shell's current subjob. If it is nil, the signal is sent to the process group of the immediate subprocess of Emacs. If the subprocess is a job-control shell, this is the shell itself.

The flag current-group has no effect when a pipe is used to communicate with the subprocess, because the operating system does not support the distinction in the case of pipes. For the same reason, job-control shells won't work when a pipe is used. See process-connection-type in 37.4 Creating an Asynchronous Process.

Function: interrupt-process &optional process-name current-group
This function interrupts the process process-name by sending the signal SIGINT. Outside of Emacs, typing the "interrupt character" (normally C-c on some systems, and DEL on others) sends this signal. When the argument current-group is non-nil, you can think of this function as "typing C-c" on the terminal by which Emacs talks to the subprocess.

Function: kill-process &optional process-name current-group
This function kills the process process-name by sending the signal SIGKILL. This signal kills the subprocess immediately, and cannot be handled by the subprocess.

Function: quit-process &optional process-name current-group
This function sends the signal SIGQUIT to the process process-name. This signal is the one sent by the "quit character" (usually C-b or C-\) when you are not inside Emacs.

Function: stop-process &optional process-name current-group
This function stops the process process-name by sending the signal SIGTSTP. Use continue-process to resume its execution.

Outside of Emacs, on systems with job control, the "stop character" (usually C-z) normally sends this signal. When current-group is non-nil, you can think of this function as "typing C-z" on the terminal Emacs uses to communicate with the subprocess.

Function: continue-process &optional process-name current-group
This function resumes execution of the process process by sending it the signal SIGCONT. This presumes that process-name was stopped previously.

Function: signal-process pid signal
This function sends a signal to process pid, which need not be a child of Emacs. The argument signal specifies which signal to send; it should be an integer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.9 Receiving Output from Processes

There are two ways to receive the output that a subprocess writes to its standard output stream. The output can be inserted in a buffer, which is called the associated buffer of the process, or a function called the filter function can be called to act on the output. If the process has no buffer and no filter function, its output is discarded. Output from a subprocess can arrive only while Emacs is waiting: when reading terminal input, in sit-for and sleep-for (see section 21.9 Waiting for Elapsed Time or Input), and in accept-process-output (see section 37.9.3 Accepting Output from Processes). This minimizes the problem of timing errors that usually plague parallel programming. For example, you can safely create a process and only then specify its buffer or filter function; no output can arrive before you finish, if the code in between does not call any primitive that waits.

It is impossible to separate the standard output and standard error streams of the subprocess, because Emacs normally spawns the subprocess inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If you want to keep the output to those streams separate, you should redirect one of them to a file--for example, by using an appropriate shell command.

Subprocess output is normally decoded using a coding system before the buffer or filter function receives it, much like text read from a file. You can use set-process-coding-system to specify which coding system to use (see section 37.6 Process Information). Otherwise, the coding system comes from coding-system-for-read, if that is non-nil; or else from the defaulting mechanism (see section 33.10.5 Default Coding Systems).

Warning: Coding systems such as undecided which determine the coding system from the data do not work entirely reliably with asynchronous subprocess output. This is because Emacs has to process asynchronous subprocess output in batches, as it arrives. Emacs must try to detect the proper coding system from one batch at a time, and this does not always work. Therefore, if at all possible, use a coding system which determines both the character code conversion and the end of line conversion--that is, one like latin-1-unix, rather than undecided or latin-1.

37.9.1 Process Buffers

If no filter, output is put in a buffer.

37.9.2 Process Filter Functions

Filter functions accept output from the process.

37.9.3 Accepting Output from Processes

Explicitly permitting subprocess output. Waiting for subprocess output.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.9.1 Process Buffers

A process can (and usually does) have an associated buffer, which is an ordinary Emacs buffer that is used for two purposes: storing the output from the process, and deciding when to kill the process. You can also use the buffer to identify a process to operate on, since in normal practice only one process is associated with any given buffer. Many applications of processes also use the buffer for editing input to be sent to the process, but this is not built into Emacs Lisp.

Unless the process has a filter function (see section 37.9.2 Process Filter Functions), its output is inserted in the associated buffer. The position to insert the output is determined by the process-mark, which is then updated to point to the end of the text just inserted. Usually, but not always, the process-mark is at the end of the buffer.

Function: process-buffer process
This function returns the associated buffer of the process process.
(process-buffer (get-process "shell"))
     => #<buffer *shell*>
Function: process-mark process
This function returns the process marker for process, which is the marker that says where to insert output from the process.

If process does not have a buffer, process-mark returns a marker that points nowhere.

Insertion of process output in a buffer uses this marker to decide where to insert, and updates it to point after the inserted text. That is why successive batches of output are inserted consecutively.

Filter functions normally should use this marker in the same fashion as is done by direct insertion of output in the buffer. A good example of a filter function that uses process-mark is found at the end of the following section.

When the user is expected to enter input in the process buffer for transmission to the process, the process marker separates the new input from previous output.

Function: set-process-buffer process buffer
This function sets the buffer associated with process to buffer. If buffer is nil, the process becomes associated with no buffer.

Function: get-buffer-process buffer-or-name
This function returns the process associated with buffer-or-name. If there are several processes associated with it, then one is chosen. (Currently, the one chosen is the one most recently created.) It is usually a bad idea to have more than one process associated with the same buffer.
(get-buffer-process "*shell*")
     => #<process shell>
Killing the process's buffer deletes the process, which kills the subprocess with a SIGHUP signal (see section 37.8 Sending Signals to Processes).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.9.2 Process Filter Functions

A process filter function is a function that receives the standard output from the associated process. If a process has a filter, then all output from that process is passed to the filter. The process buffer is used directly for output from the process only when there is no filter.

The filter function can only be called when Emacs is waiting for something, because process output arrives only at such times. Emacs waits when reading terminal input, in sit-for and sleep-for (see section 21.9 Waiting for Elapsed Time or Input), and in accept-process-output (see section 37.9.3 Accepting Output from Processes).

A filter function must accept two arguments: the associated process and a string, which is output just received from it. The function is then free to do whatever it chooses with the output.

Quitting is normally inhibited within a filter function--otherwise, the effect of typing C-g at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a filter function, bind inhibit-quit to nil. See section 21.10 Quitting.

If an error happens during execution of a filter function, it is caught automatically, so that it doesn't stop the execution of whatever program was running when the filter function was started. However, if debug-on-error is non-nil, the error-catching is turned off. This makes it possible to use the Lisp debugger to debug the filter function. See section 18.1 The Lisp Debugger.

Many filter functions sometimes or always insert the text in the process's buffer, mimicking the actions of Emacs when there is no filter. Such filter functions need to use set-buffer in order to be sure to insert in that buffer. To avoid setting the current buffer semipermanently, these filter functions must save and restore the current buffer. They should also update the process marker, and in some cases update the value of point. Here is how to do these things:
(defun ordinary-insertion-filter (proc string)
  (with-current-buffer (process-buffer proc)
    (let ((moving (= (point) (process-mark proc))))
      (save-excursion
        ;; Insert the text, advancing the process marker.
        (goto-char (process-mark proc))
        (insert string)
        (set-marker (process-mark proc) (point)))
      (if moving (goto-char (process-mark proc))))))
The reason to use with-current-buffer, rather than using save-excursion to save and restore the current buffer, is so as to preserve the change in point made by the second call to goto-char.

To make the filter force the process buffer to be visible whenever new text arrives, insert the following line just before the with-current-buffer construct:
(display-buffer (process-buffer proc))
To force point to the end of the new output, no matter where it was previously, eliminate the variable moving and call goto-char unconditionally.

In earlier Emacs versions, every filter function that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for filter functions; they never need to do it explicitly. See section 34.6 The Match Data.

A filter function that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. The expression (buffer-name (process-buffer process)) returns nil if the buffer is dead.

The output to the function may come in chunks of any size. A program that produces the same output twice in a row may send it as one batch of 200 characters one time, and five batches of 40 characters the next. If the filter looks for certain text strings in the subprocess output, make sure to handle the case where one of these strings is split across two or more batches of output.

Function: set-process-filter process filter
This function gives process the filter function filter. If filter is nil, it gives the process no filter.

Function: process-filter process
This function returns the filter function of process, or nil if it has none.

Here is an example of use of a filter function:
(defun keep-output (process output)
   (setq kept (cons output kept)))
     => keep-output
(setq kept nil)
     => nil
(set-process-filter (get-process "shell") 'keep-output)
     => keep-output
(process-send-string "shell" "ls ~/other\n")
     => nil
kept
     => ("lewis@slug[8] % "
"FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
address.txt             backup.psf              kolstad.psf
backup.bib~             david.mss               resume-Dec-86.mss~
backup.err              david.psf               resume-Dec.psf
backup.mss              dland                   syllabus.mss
"
"#backups.mss#          backup.mss~             kolstad.mss
")
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.9.3 Accepting Output from Processes

Output from asynchronous subprocesses normally arrives only while Emacs is waiting for some sort of external event, such as elapsed time or terminal input. Occasionally it is useful in a Lisp program to explicitly permit output to arrive at a specific point, or even to wait until output arrives from a process.

Function: accept-process-output &optional process seconds millisec
This function allows Emacs to read pending output from processes. The output is inserted in the associated buffers or given to their filter functions. If process is non-nil then this function does not return until some output has been received from process.

The arguments seconds and millisec let you specify timeout periods. The former specifies a period measured in seconds and the latter specifies one measured in milliseconds. The two time periods thus specified are added together, and accept-process-output returns after that much time whether or not there has been any subprocess output.

The argument seconds need not be an integer. If it is a floating point number, this function waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, seconds is rounded down.

Not all operating systems support waiting periods other than multiples of a second; on those that do not, you get an error if you specify nonzero millisec.

The function accept-process-output returns non-nil if it did get some output, or nil if the timeout expired before output arrived.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.10 Sentinels: Detecting Process Status Changes

A process sentinel is a function that is called whenever the associated process changes status for any reason, including signals (whether sent by Emacs or caused by the process's own actions) that terminate, stop, or continue the process. The process sentinel is also called if the process exits. The sentinel receives two arguments: the process for which the event occurred, and a string describing the type of event.

The string describing the event looks like one of the following:

"finished\n".

"exited abnormally with code exitcode\n".

"name-of-signal\n".

"name-of-signal (core dumped)\n".

A sentinel runs only while Emacs is waiting (e.g., for terminal input, or for time to elapse, or for process output). This avoids the timing errors that could result from running them at random places in the middle of other Lisp programs. A program can wait, so that sentinels will run, by calling sit-for or sleep-for (see section 21.9 Waiting for Elapsed Time or Input), or accept-process-output (see section 37.9.3 Accepting Output from Processes). Emacs also allows sentinels to run when the command loop is reading input.

Quitting is normally inhibited within a sentinel--otherwise, the effect of typing C-g at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a sentinel, bind inhibit-quit to nil. See section 21.10 Quitting.

A sentinel that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. If the buffer is dead, (buffer-name (process-buffer process)) returns nil.

If an error happens during execution of a sentinel, it is caught automatically, so that it doesn't stop the execution of whatever programs was running when the sentinel was started. However, if debug-on-error is non-nil, the error-catching is turned off. This makes it possible to use the Lisp debugger to debug the sentinel. See section 18.1 The Lisp Debugger.

In earlier Emacs versions, every sentinel that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for sentinels; they never need to do it explicitly. See section 34.6 The Match Data.

Function: set-process-sentinel process sentinel
This function associates sentinel with process. If sentinel is nil, then the process will have no sentinel. The default behavior when there is no sentinel is to insert a message in the process's buffer when the process status changes.
(defun msg-me (process event)
   (princ
     (format "Process: %s had the event `%s'" process event)))
(set-process-sentinel (get-process "shell") 'msg-me)
     => msg-me
(kill-process (get-process "shell"))
     -| Process: #<process shell> had the event `killed'
     => #<process shell>
Function: process-sentinel process
This function returns the sentinel of process, or nil if it has none.

Function: waiting-for-user-input-p
While a sentinel or filter function is running, this function returns non-nil if Emacs was waiting for keyboard input from the user at the time the sentinel or filter function was called, nil if it was not.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.11 Transaction Queues

You can use a transaction queue to communicate with a subprocess using transactions. First use tq-create to create a transaction queue communicating with a specified process. Then you can call tq-enqueue to send a transaction.

Function: tq-create process
This function creates and returns a transaction queue communicating with process. The argument process should be a subprocess capable of sending and receiving streams of bytes. It may be a child process, or it may be a TCP connection to a server, possibly on another machine.

Function: tq-enqueue queue question regexp closure fn
This function sends a transaction to queue queue. Specifying the queue has the effect of specifying the subprocess to talk to.

The argument question is the outgoing message that starts the transaction. The argument fn is the function to call when the corresponding answer comes back; it is called with two arguments: closure, and the answer received.

The argument regexp is a regular expression that should match text at the end of the entire answer, but nothing before; that's how tq-enqueue determines where the answer ends.

The return value of tq-enqueue itself is not meaningful.

Function: tq-close queue
Shut down transaction queue queue, waiting for all pending transactions to complete, and then terminate the connection or child process.

Transaction queues are implemented by means of a filter function. See section 37.9.2 Process Filter Functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

37.12 Network Connections

Emacs Lisp programs can open TCP network connections to other processes on the same machine or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object. However, the process you are communicating with is not a child of the Emacs process, so you can't kill it or send it signals. All you can do is send and receive data. delete-process closes the connection, but does not kill the process at the other end; that process must decide what to do about closure of the connection.

You can distinguish process objects representing network connections from those representing subprocesses with the process-status function. It always returns either open or closed for a network connection, and it never returns either of those values for a real subprocess. See section 37.6 Process Information.

Function: open-network-stream name buffer-or-name host service
This function opens a TCP connection for a service to a host. It returns a process object to represent the connection.

The name argument specifies the name for the process object. It is modified as necessary to make it unique.

The buffer-or-name argument is the buffer to associate with the connection. Output from the connection is inserted in the buffer, unless you specify a filter function to handle the output. If buffer-or-name is nil, it means that the connection is not associated with any buffer.

The arguments host and service specify where to connect to; host is the host name (a string), and service is the name of a defined network service (a string) or a port number (an integer).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38. Emacs Display

This chapter describes a number of features related to the display that Emacs presents to the user.

38.1 Refreshing the Screen

Clearing the screen and redrawing everything on it.

38.2 Forcing Redisplay

Forcing redisplay.

38.3 Truncation

Folding or wrapping long text lines.

38.4 The Echo Area

Where messages are displayed.

38.5 Invisible Text

Hiding part of the buffer text.

38.6 Selective Display

Hiding part of the buffer text (the old way).

38.7 The Overlay Arrow

Display of an arrow to indicate position.

38.8 Temporary Displays

Displays that go away automatically.

38.9 Overlays

Use overlays to highlight parts of the buffer.

38.10 Width

How wide a character or string is on the screen.

38.11 Faces

A face defines a graphics style for text characters: font, colors, etc.

38.12 The display Property

Enabling special display features.

38.13 Images

Displaying images in Emacs buffers.

38.14 Blinking Parentheses

How Emacs shows the matching open parenthesis.

38.15 Inverse Video

Specifying how the screen looks.

38.16 Usual Display Conventions

The usual conventions for displaying nonprinting chars.

38.17 Display Tables

How to specify other conventions.

38.18 Beeping

Audible signal to the user.

38.19 Window Systems

Which window system is being used.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.1 Refreshing the Screen

The function redraw-frame redisplays the entire contents of a given frame (see section 29. Frames).

Function: redraw-frame frame
This function clears and redisplays frame frame.

Even more powerful is redraw-display:

Command: redraw-display
This function clears and redisplays all visible frames.

Processing user input takes absolute priority over redisplay. If you call these functions when input is available, they do nothing immediately, but a full redisplay does happen eventually--after all the input has been processed.

Normally, suspending and resuming Emacs also refreshes the screen. Some terminal emulators record separate contents for display-oriented programs such as Emacs and for ordinary sequential display. If you are using such a terminal, you might want to inhibit the redisplay on resumption.

Variable: no-redraw-on-reenter
This variable controls whether Emacs redraws the entire screen after it has been suspended and resumed. Non-nil means there is no need to redraw, nil means redrawing is needed. The default is nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.2 Forcing Redisplay

Emacs redisplay normally stops if input arrives, and does not happen at all if input is available before it starts. Most of the time, this is exactly what you want. However, you can prevent preemption by binding redisplay-dont-pause to a non-nil value.

Variable: redisplay-dont-pause
If this variable is non-nil, pending input does not prevent or halt redisplay; redisplay occurs, and finishes, regardless of whether input is available. This feature is available as of Emacs 21.

You can request a display update, but only if no input is pending, with (sit-for 0). To force a display update even when input is pending, do this:
(let ((redisplay-dont-pause t))
  (sit-for 0))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.3 Truncation

When a line of text extends beyond the right edge of a window, the line can either be continued on the next screen line, or truncated to one screen line. The additional screen lines used to display a long text line are called continuation lines. Normally, a `$' in the rightmost column of the window indicates truncation; a `\' on the rightmost column indicates a line that "wraps" onto the next line, which is also called continuing the line. (The display table can specify alternative indicators; see 38.17 Display Tables.)

Note that continuation is different from filling; continuation happens on the screen only, not in the buffer contents, and it breaks a line precisely at the right margin, not at a word boundary. See section 32.11 Filling.

User Option: truncate-lines
This buffer-local variable controls how Emacs displays lines that extend beyond the right edge of the window. The default is nil, which specifies continuation. If the value is non-nil, then these lines are truncated.

If the variable truncate-partial-width-windows is non-nil, then truncation is always used for side-by-side windows (within one frame) regardless of the value of truncate-lines.

User Option: default-truncate-lines
This variable is the default value for truncate-lines, for buffers that do not have buffer-local values for it.

User Option: truncate-partial-width-windows
This variable controls display of lines that extend beyond the right edge of the window, in side-by-side windows (see section 28.2 Splitting Windows). If it is non-nil, these lines are truncated; otherwise, truncate-lines says what to do with them.

When horizontal scrolling (see section 28.13 Horizontal Scrolling) is in use in a window, that forces truncation.

You can override the glyphs that indicate continuation or truncation using the display table; see 38.17 Display Tables.

If your buffer contains very long lines, and you use continuation to display them, just thinking about them can make Emacs redisplay slow. The column computation and indentation functions also become slow. Then you might find it advisable to set cache-long-line-scans to t.

Variable: cache-long-line-scans
If this variable is non-nil, various indentation and motion functions, and Emacs redisplay, cache the results of scanning the buffer, and consult the cache to avoid rescanning regions of the buffer unless they are modified.

Turning on the cache slows down processing of short lines somewhat.

This variable is automatically buffer-local in every buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.4 The Echo Area

The echo area is used for displaying messages made with the message primitive, and for echoing keystrokes. It is not the same as the minibuffer, despite the fact that the minibuffer appears (when active) in the same place on the screen as the echo area. The GNU Emacs Manual specifies the rules for resolving conflicts between the echo area and the minibuffer for use of that screen space (see section `The Minibuffer' in The GNU Emacs Manual). Error messages appear in the echo area; see 10.5.3 Errors.

You can write output in the echo area by using the Lisp printing functions with t as the stream (see section 19.5 Output Functions), or as follows:

Function: message string &rest arguments
This function displays a message in the echo area. The argument string is similar to a C language printf control string. See format in 4.6 Conversion of Characters and Strings, for the details on the conversion specifications. message returns the constructed string.

In batch mode, message prints the message text on the standard error stream, followed by a newline.

If string, or strings among the arguments, have face text properties, these affect the way the message is displayed.

If string is nil, message clears the echo area; if the echo area has been expanded automatically, this brings it back to its normal size. If the minibuffer is active, this brings the minibuffer contents back onto the screen immediately.

Normally, displaying a long message resizes the echo area to display the entire message. But if the variable message-truncate-lines is non-nil, the echo area does not resize, and the message is truncated to fit it, as in Emacs 20 and before.
(message "Minibuffer depth is %d."
         (minibuffer-depth))
 -| Minibuffer depth is 0.
=> "Minibuffer depth is 0."

---------- Echo Area ----------
Minibuffer depth is 0.
---------- Echo Area ----------
To automatically display a message in the echo area or in a pop-buffer, depending on its size, use display-message-or-buffer.

Macro: with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during the execution of body. It displays message, executes body, then returns the value of the last body form while restoring the previous echo area contents.

Function: message-or-box string &rest arguments
This function displays a message like message, but may display it in a dialog box instead of the echo area. If this function is called in a command that was invoked using the mouse--more precisely, if last-nonmenu-event (see section 21.4 Information from the Command Loop) is either nil or a list--then it uses a dialog box or pop-up menu to display the message. Otherwise, it uses the echo area. (This is the same criterion that y-or-n-p uses to make a similar decision; see 20.6 Yes-or-No Queries.)

You can force use of the mouse or of the echo area by binding last-nonmenu-event to a suitable value around the call.

Function: message-box string &rest arguments
This function displays a message like message, but uses a dialog box (or a pop-up menu) whenever that is possible. If it is impossible to use a dialog box or pop-up menu, because the terminal does not support them, then message-box uses the echo area, like message.

Function: display-message-or-buffer message &optional buffer-name not-this-window frame
This function displays the message message, which may be either a string or a buffer. If it is shorter than the maximum height of the echo area, as defined by max-mini-window-height, it is displayed in the echo area, using message. Otherwise, display-buffer is used to show it in a pop-up buffer.

Returns either the string shown in the echo area, or when a pop-up buffer is used, the window used to display it.

If message is a string, then the optional argument buffer-name is the name of the buffer used to display it when a pop-up buffer is used, defaulting to `*Message*'. In the case where message is a string and displayed in the echo area, it is not specified whether the contents are inserted into the buffer anyway.

The optional arguments not-this-window and frame are as for display-buffer, and only used if a buffer is displayed.

Function: current-message
This function returns the message currently being displayed in the echo area, or nil if there is none.

Variable: cursor-in-echo-area
This variable controls where the cursor appears when a message is displayed in the echo area. If it is non-nil, then the cursor appears at the end of the message. Otherwise, the cursor appears at point--not in the echo area at all.

The value is normally nil; Lisp programs bind it to t for brief periods of time.

Variable: echo-area-clear-hook
This normal hook is run whenever the echo area is cleared--either by (message nil) or for any other reason.

Almost all the messages displayed in the echo area are also recorded in the `*Messages*' buffer.

User Option: message-log-max
This variable specifies how many lines to keep in the `*Messages*' buffer. The value t means there is no limit on how many lines to keep. The value nil disables message logging entirely. Here's how to display a message and prevent it from being logged:
(let (message-log-max)
  (message ...))
Variable: echo-keystrokes
This variable determines how much time should elapse before command characters echo. Its value must be an integer or floating point number, which specifies the number of seconds to wait before echoing. If the user types a prefix key (such as C-x) and then delays this many seconds before continuing, the prefix key is echoed in the echo area. (Once echoing begins in a key sequence, all subsequent characters in the same key sequence are echoed immediately.)

If the value is zero, then command input is not echoed.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.5 Invisible Text

You can make characters invisible, so that they do not appear on the screen, with the invisible property. This can be either a text property (see section 32.19 Text Properties) or a property of an overlay (see section 38.9 Overlays).

In the simplest case, any non-nil invisible property makes a character invisible. This is the default case--if you don't alter the default value of buffer-invisibility-spec, this is how the invisible property works.

More generally, you can use the variable buffer-invisibility-spec to control which values of the invisible property make text invisible. This permits you to classify the text into different subsets in advance, by giving them different invisible values, and subsequently make various subsets visible or invisible by changing the value of buffer-invisibility-spec.

Controlling visibility with buffer-invisibility-spec is especially useful in a program to display the list of entries in a database. It permits the implementation of convenient filtering commands to view just a part of the entries in the database. Setting this variable is very fast, much faster than scanning all the text in the buffer looking for properties to change.

Variable: buffer-invisibility-spec
This variable specifies which kinds of invisible properties actually make a character invisible.

t
A character is invisible if its invisible property is non-nil. This is the default.

a list
Each element of the list specifies a criterion for invisibility; if a character's invisible property fits any one of these criteria, the character is invisible. The list can have two kinds of elements:

atom
A character is invisible if its invisible property value is atom or if it is a list with atom as a member.

(atom . t)
A character is invisible if its invisible property value is atom or if it is a list with atom as a member. Moreover, if this character is at the end of a line and is followed by a visible newline, it displays an ellipsis.
Two functions are specifically provided for adding elements to buffer-invisibility-spec and removing elements from it.

Function: add-to-invisibility-spec element
Add the element element to buffer-invisibility-spec (if it is not already present in that list).

Function: remove-from-invisibility-spec element
Remove the element element from buffer-invisibility-spec. This does nothing if element is not in the list.

One convention about the use of buffer-invisibility-spec is that a major mode should use the mode's own name as an element of buffer-invisibility-spec and as the value of the invisible property:
;; If you want to display an ellipsis:
(add-to-invisibility-spec '(my-symbol . t))
;; If you don't want ellipsis:
(add-to-invisibility-spec 'my-symbol)

(overlay-put (make-overlay beginning end)
             'invisible 'my-symbol)

;; When done with the overlays:
(remove-from-invisibility-spec '(my-symbol . t))
;; Or respectively:
(remove-from-invisibility-spec 'my-symbol)
Ordinarily, commands that operate on text or move point do not care whether the text is invisible. The user-level line motion commands explicitly ignore invisible newlines if line-move-ignore-invisible is non-nil, but only because they are explicitly programmed to do so.

Incremental search can make invisible overlays visible temporarily and/or permanently when a match includes invisible text. To enable this, the overlay should have a non-nil isearch-open-invisible property. The property value should be a function to be called with the overlay as an argument. This function should make the overlay visible permanently; it is used when the match overlaps the overlay on exit from the search.

During the search, such overlays are made temporarily visible by temporarily modifying their invisible and intangible properties. If you want this to be done differently for a certain overlay, give it an isearch-open-invisible-temporary property which is a function. The function is called with two arguments: the first is the overlay, and the second is nil to make the overlay visible, or t to make it invisible again.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.6 Selective Display

Selective display refers to a pair of related features for hiding certain lines on the screen.

The first variant, explicit selective display, is designed for use in a Lisp program: it controls which lines are hidden by altering the text. The invisible text feature (see section 38.5 Invisible Text) has partially replaced this feature.

In the second variant, the choice of lines to hide is made automatically based on indentation. This variant is designed to be a user-level feature.

The way you control explicit selective display is by replacing a newline (control-j) with a carriage return (control-m). The text that was formerly a line following that newline is now invisible. Strictly speaking, it is temporarily no longer a line at all, since only newlines can separate lines; it is now part of the previous line.

Selective display does not directly affect editing commands. For example, C-f (forward-char) moves point unhesitatingly into invisible text. However, the replacement of newline characters with carriage return characters affects some editing commands. For example, next-line skips invisible lines, since it searches only for newlines. Modes that use selective display can also define commands that take account of the newlines, or that make parts of the text visible or invisible.

When you write a selectively displayed buffer into a file, all the control-m's are output as newlines. This means that when you next read in the file, it looks OK, with nothing invisible. The selective display effect is seen only within Emacs.

Variable: selective-display
This buffer-local variable enables selective display. This means that lines, or portions of lines, may be made invisible.

If the value of selective-display is t, then the character control-m marks the start of invisible text; the control-m, and the rest of the line following it, are not displayed. This is explicit selective display.

If the value of selective-display is a positive integer, then lines that start with more than that many columns of indentation are not displayed.

When some portion of a buffer is invisible, the vertical movement commands operate as if that portion did not exist, allowing a single next-line command to skip any number of invisible lines. However, character movement commands (such as forward-char) do not skip the invisible portion, and it is possible (if tricky) to insert or delete text in an invisible portion.

In the examples below, we show the display appearance of the buffer foo, which changes with the value of selective-display. The contents of the buffer do not change.
(setq selective-display nil)
     => nil

---------- Buffer: foo ----------
1 on this column
 2on this column
  3n this column
  3n this column
 2on this column
1 on this column
---------- Buffer: foo ----------

(setq selective-display 2)
     => 2

---------- Buffer: foo ----------
1 on this column
 2on this column
 2on this column
1 on this column
---------- Buffer: foo ----------
Variable: selective-display-ellipses
If this buffer-local variable is non-nil, then Emacs displays `...' at the end of a line that is followed by invisible text. This example is a continuation of the previous one.
(setq selective-display-ellipses t)
     => t

---------- Buffer: foo ----------
1 on this column
 2on this column ...
 2on this column
1 on this column
---------- Buffer: foo ----------
You can use a display table to substitute other text for the ellipsis (`...'). See section 38.17 Display Tables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.7 The Overlay Arrow

The overlay arrow is useful for directing the user's attention to a particular line in a buffer. For example, in the modes used for interface to debuggers, the overlay arrow indicates the line of code about to be executed.

Variable: overlay-arrow-string
This variable holds the string to display to call attention to a particular line, or nil if the arrow feature is not in use. On a graphical display the contents of the string are ignored; instead a glyph is displayed in the fringe area to the left of the display area.

Variable: overlay-arrow-position
This variable holds a marker that indicates where to display the overlay arrow. It should point at the beginning of a line. On a non-graphical display the arrow text appears at the beginning of that line, overlaying any text that would otherwise appear. Since the arrow is usually short, and the line usually begins with indentation, normally nothing significant is overwritten.

The overlay string is displayed only in the buffer that this marker points into. Thus, only one buffer can have an overlay arrow at any given time.

You can do a similar job by creating an overlay with a before-string property. See section 38.9.1 Overlay Properties.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.8 Temporary Displays

Temporary displays are used by Lisp programs to put output into a buffer and then present it to the user for perusal rather than for editing. Many help commands use this feature.

Special Form: with-output-to-temp-buffer buffer-name forms...
This function executes forms while arranging to insert any output they print into the buffer named buffer-name, which is first created if necessary, and put into Help mode. Finally, the buffer is displayed in some window, but not selected.

If the forms do not change the major mode in the output buffer, so that it is still Help mode at the end of their execution, then with-output-to-temp-buffer makes this buffer read-only at the end, and also scans it for function and variable names to make them into clickable cross-references.

The string buffer-name specifies the temporary buffer, which need not already exist. The argument must be a string, not a buffer. The buffer is erased initially (with no questions asked), and it is marked as unmodified after with-output-to-temp-buffer exits.

with-output-to-temp-buffer binds standard-output to the temporary buffer, then it evaluates the forms in forms. Output using the Lisp output functions within forms goes by default to that buffer (but screen display and messages in the echo area, although they are "output" in the general sense of the word, are not affected). See section 19.5 Output Functions.

Several hooks are available for customizing the behavior of this construct; they are listed below.

The value of the last form in forms is returned.
---------- Buffer: foo ----------
 This is the contents of foo.
---------- Buffer: foo ----------

(with-output-to-temp-buffer "foo"
    (print 20)
    (print standard-output))
=> #<buffer foo>

---------- Buffer: foo ----------
20

#<buffer foo>

---------- Buffer: foo ----------
Variable: temp-buffer-show-function
If this variable is non-nil, with-output-to-temp-buffer calls it as a function to do the job of displaying a help buffer. The function gets one argument, which is the buffer it should display.

It is a good idea for this function to run temp-buffer-show-hook just as with-output-to-temp-buffer normally would, inside of save-selected-window and with the chosen window and buffer selected.

Variable: temp-buffer-setup-hook
This normal hook is run by with-output-to-temp-buffer before evaluating body. When the hook runs, the help buffer is current. This hook is normally set up with a function to put the buffer in Help mode.

Variable: temp-buffer-show-hook
This normal hook is run by with-output-to-temp-buffer after displaying the help buffer. When the hook runs, the help buffer is current, and the window it was displayed in is selected. This hook is normally set up with a function to make the buffer read only, and find function names and variable names in it, provided the major mode is still Help mode.

Function: momentary-string-display string position &optional char message
This function momentarily displays string in the current buffer at position. It has no effect on the undo list or on the buffer's modification status.

The momentary display remains until the next input event. If the next input event is char, momentary-string-display ignores it and returns. Otherwise, that event remains buffered for subsequent use as input. Thus, typing char will simply remove the string from the display, while typing (say) C-f will remove the string from the display and later (presumably) move point forward. The argument char is a space by default.

The return value of momentary-string-display is not meaningful.

If the string string does not contain control characters, you can do the same job in a more general way by creating (and then subsequently deleting) an overlay with a before-string property. See section 38.9.1 Overlay Properties.

If message is non-nil, it is displayed in the echo area while string is displayed in the buffer. If it is nil, a default message says to type char to continue.

In this example, point is initially located at the beginning of the second line:
---------- Buffer: foo ----------
This is the contents of foo.
-!-Second line.
---------- Buffer: foo ----------

(momentary-string-display
  "**** Important Message! ****"
  (point) ?\r
  "Type RET when done reading")
=> t

---------- Buffer: foo ----------
This is the contents of foo.
**** Important Message! ****Second line.
---------- Buffer: foo ----------

---------- Echo Area ----------
Type RET when done reading
---------- Echo Area ----------
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.9 Overlays

You can use overlays to alter the appearance of a buffer's text on the screen, for the sake of presentation features. An overlay is an object that belongs to a particular buffer, and has a specified beginning and end. It also has properties that you can examine and set; these affect the display of the text within the overlay.

38.9.1 Overlay Properties

How to read and set properties. What properties do to the screen display.

38.9.2 Managing Overlays

Creating and moving overlays.

38.9.3 Searching for Overlays

Searching for overlays.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.9.1 Overlay Properties

Overlay properties are like text properties in that the properties that alter how a character is displayed can come from either source. But in most respects they are different. Text properties are considered a part of the text; overlays are specifically considered not to be part of the text. Thus, copying text between various buffers and strings preserves text properties, but does not try to preserve overlays. Changing a buffer's text properties marks the buffer as modified, while moving an overlay or changing its properties does not. Unlike text property changes, overlay changes are not recorded in the buffer's undo list. See section 32.19 Text Properties, for comparison.

These functions are used for reading and writing the properties of an overlay:

Function: overlay-get overlay prop
This function returns the value of property prop recorded in overlay, if any. If overlay does not record any value for that property, but it does have a category property which is a symbol, that symbol's prop property is used. Otherwise, the value is nil.

Function: overlay-put overlay prop value
This function sets the value of property prop recorded in overlay to value. It returns value.

See also the function get-char-property which checks both overlay properties and text properties for a given character. See section 32.19.1 Examining Text Properties.

Many overlay properties have special meanings; here is a table of them:

priority
This property's value (which should be a nonnegative number) determines the priority of the overlay. The priority matters when two or more overlays cover the same character and both specify a face for display; the one whose priority value is larger takes priority over the other, and its face attributes override the face attributes of the lower priority overlay.
Currently, all overlays take priority over text properties. Please avoid using negative priority values, as we have not yet decided just what they should mean.

window
If the window property is non-nil, then the overlay applies only on that window.

category
If an overlay has a category property, we call it the category of the overlay. It should be a symbol. The properties of the symbol serve as defaults for the properties of the overlay.

face
This property controls the way text is displayed--for example, which font and which colors. See section 38.11 Faces, for more information.
In the simplest case, the value is a face name. It can also be a list; then each element can be any of these possibilities:

A face name (a symbol or string).

Starting in Emacs 21, a property list of face attributes. This has the form (keyword value ...), where each keyword is a face attribute name and value is a meaningful value for that attribute. With this feature, you do not need to create a face each time you want to specify a particular attribute for certain text. See section 38.11.3 Face Attributes.

A cons cell of the form (foreground-color . color-name) or (background-color . color-name). These elements specify just the foreground color or just the background color.
(foreground-color . color-name) is equivalent to (:foreground color-name), and likewise for the background.

mouse-face
This property is used instead of face when the mouse is within the range of the overlay.

display
This property activates various features that change the way text is displayed. For example, it can make text appear taller or shorter, higher or lower, wider or narrower, or replaced with an image. See section 38.12 The display Property.

help-echo
If an overlay has a help-echo property, then when you move the mouse onto the text in the overlay, Emacs displays a help string in the echo area, or in the tooltip window. For details see Text help-echo. This feature is available starting in Emacs 21.

modification-hooks
This property's value is a list of functions to be called if any character within the overlay is changed or if text is inserted strictly within the overlay.
The hook functions are called both before and after each change. If the functions save the information they receive, and compare notes between calls, they can determine exactly what change has been made in the buffer text.

When called before a change, each function receives four arguments: the overlay, nil, and the beginning and end of the text range to be modified.

When called after a change, each function receives five arguments: the overlay, t, the beginning and end of the text range just modified, and the length of the pre-change text replaced by that range. (For an insertion, the pre-change length is zero; for a deletion, that length is the number of characters deleted, and the post-change beginning and end are equal.)

insert-in-front-hooks
This property's value is a list of functions to be called before and after inserting text right at the beginning of the overlay. The calling conventions are the same as for the modification-hooks functions.

insert-behind-hooks
This property's value is a list of functions to be called before and after inserting text right at the end of the overlay. The calling conventions are the same as for the modification-hooks functions.

invisible
The invisible property can make the text in the overlay invisible, which means that it does not appear on the screen. See section 38.5 Invisible Text, for details.

intangible
The intangible property on an overlay works just like the intangible text property. See section 32.19.4 Properties with Special Meanings, for details.

isearch-open-invisible
This property tells incremental search how to make an invisible overlay visible, permanently, if the final match overlaps it. See section 38.5 Invisible Text.

isearch-open-invisible-temporary
This property tells incremental search how to make an invisible overlay visible, temporarily, during the search. See section 38.5 Invisible Text.

before-string
This property's value is a string to add to the display at the beginning of the overlay. The string does not appear in the buffer in any sense--only on the screen.

after-string
This property's value is a string to add to the display at the end of the overlay. The string does not appear in the buffer in any sense--only on the screen.

evaporate
If this property is non-nil, the overlay is deleted automatically if it ever becomes empty (i.e., if it spans no characters).

local-map
If this property is non-nil, it specifies a keymap for a portion of the text. The property's value replaces the buffer's local map, when the character after point is within the overlay. See section 22.6 Active Keymaps.

keymap
The keymap property is similar to local-map but overrides the buffer's local map (and the map specified by the local-map property) rather than replacing it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.9.2 Managing Overlays

This section describes the functions to create, delete and move overlays, and to examine their contents.

Function: make-overlay start end &optional buffer front-advance rear-advance
This function creates and returns an overlay that belongs to buffer and ranges from start to end. Both start and end must specify buffer positions; they may be integers or markers. If buffer is omitted, the overlay is created in the current buffer.

The arguments front-advance and rear-advance specify the insertion type for the start of the overlay and for the end of the overlay, respectively. See section 31.5 Marker Insertion Types.

Function: overlay-start overlay
This function returns the position at which overlay starts, as an integer.

Function: overlay-end overlay
This function returns the position at which overlay ends, as an integer.

Function: overlay-buffer overlay
This function returns the buffer that overlay belongs to.

Function: delete-overlay overlay
This function deletes overlay. The overlay continues to exist as a Lisp object, and its property list is unchanged, but it ceases to be attached to the buffer it belonged to, and ceases to have any effect on display.

A deleted overlay is not permanently disconnected. You can give it a position in a buffer again by calling move-overlay.

Function: move-overlay overlay start end &optional buffer
This function moves overlay to buffer, and places its bounds at start and end. Both arguments start and end must specify buffer positions; they may be integers or markers.

If buffer is omitted, overlay stays in the same buffer it was already associated with; if overlay was deleted, it goes into the current buffer.

The return value is overlay.

This is the only valid way to change the endpoints of an overlay. Do not try modifying the markers in the overlay by hand, as that fails to update other vital data structures and can cause some overlays to be "lost".

Here are some examples:
;; Create an overlay.
(setq foo (make-overlay 1 10))
     => #<overlay from 1 to 10 in display.texi>
(overlay-start foo)
     => 1
(overlay-end foo)
     => 10
(overlay-buffer foo)
     => #<buffer display.texi>
;; Give it a property we can check later.
(overlay-put foo 'happy t)
     => t
;; Verify the property is present.
(overlay-get foo 'happy)
     => t
;; Move the overlay.
(move-overlay foo 5 20)
     => #<overlay from 5 to 20 in display.texi>
(overlay-start foo)
     => 5
(overlay-end foo)
     => 20
;; Delete the overlay.
(delete-overlay foo)
     => nil
;; Verify it is deleted.
foo
     => #<overlay in no buffer>
;; A deleted overlay has no position.
(overlay-start foo)
     => nil
(overlay-end foo)
     => nil
(overlay-buffer foo)
     => nil
;; Undelete the overlay.
(move-overlay foo 1 20)
     => #<overlay from 1 to 20 in display.texi>
;; Verify the results.
(overlay-start foo)
     => 1
(overlay-end foo)
     => 20
(overlay-buffer foo)
     => #<buffer display.texi>
;; Moving and deleting the overlay does not change its properties.
(overlay-get foo 'happy)
     => t
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.9.3 Searching for Overlays

Function: overlays-at pos
This function returns a list of all the overlays that cover the character at position pos in the current buffer. The list is in no particular order. An overlay contains position pos if it begins at or before pos, and ends after pos.

To illustrate usage, here is a Lisp function that returns a list of the overlays that specify property prop for the character at point:
(defun find-overlays-specifying (prop)
  (let ((overlays (overlays-at (point)))
        found)
    (while overlays
      (let ((overlay (car overlays)))
        (if (overlay-get overlay prop)
            (setq found (cons overlay found))))
      (setq overlays (cdr overlays)))
    found))
Function: overlays-in beg end
This function returns a list of the overlays that overlap the region beg through end. "Overlap" means that at least one character is contained within the overlay and also contained within the specified region; however, empty overlays are included in the result if they are located at beg, or strictly between beg and end.

Function: next-overlay-change pos
This function returns the buffer position of the next beginning or end of an overlay, after pos.

Function: previous-overlay-change pos
This function returns the buffer position of the previous beginning or end of an overlay, before pos.

Here's an easy way to use next-overlay-change to search for the next character which gets a non-nil happy property from either its overlays or its text properties (see section 32.19.3 Text Property Search Functions):
(defun find-overlay-prop (prop)
  (save-excursion
    (while (and (not (eobp))
                (not (get-char-property (point) 'happy)))
      (goto-char (min (next-overlay-change (point))
                      (next-single-property-change (point) 'happy))))
    (point)))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.10 Width

Since not all characters have the same width, these functions let you check the width of a character. See section 32.17.1 Indentation Primitives, and 30.2.5 Motion by Screen Lines, for related functions.

Function: char-width char
This function returns the width in columns of the character char, if it were displayed in the current buffer and the selected window.

Function: string-width string
This function returns the width in columns of the string string, if it were displayed in the current buffer and the selected window.

Function: truncate-string-to-width string width &optional start-column padding
This function returns the part of string that fits within width columns, as a new string.

If string does not reach width, then the result ends where string ends. If one multi-column character in string extends across the column width, that character is not included in the result. Thus, the result can fall short of width but cannot go beyond it.

The optional argument start-column specifies the starting column. If this is non-nil, then the first start-column columns of the string are omitted from the value. If one multi-column character in string extends across the column start-column, that character is not included.

The optional argument padding, if non-nil, is a padding character added at the beginning and end of the result string, to extend it to exactly width columns. The padding character is used at the end of the result if it falls short of width. It is also used at the beginning of the result if one multi-column character in string extends across the column start-column.
(truncate-string-to-width "\tab\t" 12 4)
     => "ab"
(truncate-string-to-width "\tab\t" 12 4 ?\ )
     => "    ab  "
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11 Faces

A face is a named collection of graphical attributes: font family, foreground color, background color, optional underlining, and many others. Faces are used in Emacs to control the style of display of particular parts of the text or the frame.

Each face has its own face number, which distinguishes faces at low levels within Emacs. However, for most purposes, you refer to faces in Lisp programs by their names.

Function: facep object
This function returns t if object is a face name symbol (or if it is a vector of the kind used internally to record face data). It returns nil otherwise.

Each face name is meaningful for all frames, and by default it has the same meaning in all frames. But you can arrange to give a particular face name a special meaning in one frame if you wish.

38.11.1 Standard Faces

The faces Emacs normally comes with.

38.11.2 Defining Faces

How to define a face with defface.

38.11.3 Face Attributes

What is in a face?

38.11.4 Face Attribute Functions

Functions to examine and set face attributes.

38.11.5 Merging Faces for Display

How Emacs combines the faces specified for a character.

38.11.6 Font Selection

Finding the best available font for a face.

38.11.7 Functions for Working with Faces

How to define and examine faces.

38.11.8 Automatic Face Assignment

Hook for automatic face assignment.

38.11.9 Looking Up Fonts

Looking up the names of available fonts and information about them.

38.11.10 Fontsets

A fontset is a collection of fonts that handle a range of character sets.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.1 Standard Faces

This table lists all the standard faces and their uses. Most of them are used for displaying certain parts of the frames or certain kinds of text; you can control how those places look by customizing these faces.

default
This face is used for ordinary text.

mode-line
This face is used for mode lines, and for menu bars when toolkit menus are not used--but only if mode-line-inverse-video is non-nil.

modeline
This is an alias for the mode-line face, for compatibility with old Emacs versions.

header-line
This face is used for the header lines of windows that have them.

menu
This face controls the display of menus, both their colors and their font. (This works only on certain systems.)

fringe
This face controls the colors of window fringes, the thin areas on either side that are used to display continuation and truncation glyphs.

scroll-bar
This face controls the colors for display of scroll bars.

tool-bar
This face is used for display of the tool bar, if any.

region
This face is used for highlighting the region in Transient Mark mode.

secondary-selection
This face is used to show any secondary selection you have made.

highlight
This face is meant to be used for highlighting for various purposes.

trailing-whitespace
This face is used to display excess whitespace at the end of a line, if show-trailing-whitespace is non-nil.
In contrast, these faces are provided to change the appearance of text in specific ways. You can use them on specific text, when you want the effects they produce.

bold
This face uses a bold font, if possible. It uses the bold variant of the frame's font, if it has one. It's up to you to choose a default font that has a bold variant, if you want to use one.

italic
This face uses the italic variant of the frame's font, if it has one.

bold-italic
This face uses the bold italic variant of the frame's font, if it has one.

underline
This face underlines text.

fixed-pitch
This face forces use of a particular fixed-width font.

variable-pitch
This face forces use of a particular variable-width font. It's reasonable to customize this to use a different variable-width font, if you like, but you should not make it a fixed-width font.

Variable: show-trailing-whitespace
If this variable is non-nil, Emacs uses the trailing-whitespace face to display any spaces and tabs at the end of a line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.2 Defining Faces

The way to define a new face is with defface. This creates a kind of customization item (see section 14. Writing Customization Definitions) which the user can customize using the Customization buffer (see section `Easy Customization' in The GNU Emacs Manual).

Macro: defface face spec doc [keyword value]...
This declares face as a customizable face that defaults according to spec. You should not quote the symbol face. The argument doc specifies the face documentation. The keywords you can use in defface are the same ones that are meaningful in both defgroup and defcustom (see section 14.1 Common Item Keywords).

When defface executes, it defines the face according to spec, then uses any customizations that were read from the init file (see section 40.1.2 The Init File, `.emacs') to override that specification.

The purpose of spec is to specify how the face should appear on different kinds of terminals. It should be an alist whose elements have the form (display atts). Each element's CAR, display, specifies a class of terminals. The element's second element, atts, is a list of face attributes and their values; it specifies what the face should look like on that kind of terminal. The possible attributes are defined in the value of custom-face-attributes.

The display part of an element of spec determines which frames the element applies to. If more than one element of spec matches a given frame, the first matching element is the only one used for that frame. There are two possibilities for display:

t
This element of spec matches all frames. Therefore, any subsequent elements of spec are never used. Normally t is used in the last (or only) element of spec.

a list
If display is a list, each element should have the form (characteristic value...). Here characteristic specifies a way of classifying frames, and the values are possible classifications which display should apply to. Here are the possible values of characteristic:

type
The kind of window system the frame uses--either graphic (any graphics-capable display), x, pc (for the MS-DOS console), w32 (for MS Windows 9X/NT), or tty (a non-graphics-capable display).

class
What kinds of colors the frame supports--either color, grayscale, or mono.

background
The kind of background--either light or dark.
If an element of display specifies more than one value for a given characteristic, any of those values is acceptable. If display has more than one element, each element should specify a different characteristic; then each characteristic of the frame must match one of the values specified for it in display.
Here's how the standard face region is defined:
(defface region
  `((((type tty) (class color))
     (:background "blue" :foreground "white"))
    (((type tty) (class mono))
     (:inverse-video t))
    (((class color) (background dark))
     (:background "blue"))
    (((class color) (background light))
     (:background "lightblue"))
    (t (:background "gray")))
  "Basic face for highlighting the region."
  :group 'basic-faces)
Internally, defface uses the symbol property face-defface-spec to record the face attributes specified in defface, saved-face for the attributes saved by the user with the customization buffer, and face-documentation for the documentation string.

User Option: frame-background-mode
This option, if non-nil, specifies the background type to use for interpreting face definitions. If it is dark, then Emacs treats all frames as if they had a dark background, regardless of their actual background colors. If it is light, then Emacs treats all frames as if they had a light background.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.3 Face Attributes

The effect of using a face is determined by a fixed set of face attributes. This table lists all the face attributes, and what they mean. Note that in general, more than one face can be specified for a given piece of text; when that happens, the attributes of all the faces are merged to specify how to display the text. See section 38.11.5 Merging Faces for Display.

In Emacs 21, any attribute in a face can have the value unspecified. This means the face doesn't specify that attribute. In face merging, when the first face fails to specify a particular attribute, that means the next face gets a chance. However, the default face must specify all attributes.

Some of these font attributes are meaningful only on certain kinds of displays--if your display cannot handle a certain attribute, the attribute is ignored. (The attributes :family, :width, :height, :weight, and :slant correspond to parts of an X Logical Font Descriptor.)

:family
Font family name, or fontset name (see section 38.11.10 Fontsets). If you specify a font family name, the wild-card characters `*' and `?' are allowed.

:width
Relative proportionate width, also known as the character set width or set width. This should be one of the symbols ultra-condensed, extra-condensed, condensed, semi-condensed, normal, semi-expanded, expanded, extra-expanded, or ultra-expanded.
:height
Either the font height, an integer in units of 1/10 point, a floating point number specifying the amount by which to scale the height of any underlying face, or a function, which is called with the old height (from the underlying face), and should return the new height.
:weight
Font weight--a symbol from this series (from most dense to most faint): ultra-bold, extra-bold, bold, semi-bold, normal, semi-light, light, extra-light, or ultra-light.
On a text-only terminal, any weight greater than normal is displayed as extra bright, and any weight less than normal is displayed as half-bright (provided the terminal supports the feature).

:slant
Font slant--one of the symbols italic, oblique, normal, reverse-italic, or reverse-oblique.
On a text-only terminal, slanted text is displayed as half-bright, if the terminal supports the feature.

:foreground
Foreground color, a string.
:background
Background color, a string.

:inverse-video
Whether or not characters should be displayed in inverse video. The value should be t (yes) or nil (no).

:stipple
The background stipple, a bitmap.
The value can be a string; that should be the name of a file containing external-format X bitmap data. The file is found in the directories listed in the variable x-bitmap-file-path.

Alternatively, the value can specify the bitmap directly, with a list of the form (width height data). Here, width and height specify the size in pixels, and data is a string containing the raw bits of the bitmap, row by row. Each row occupies (width + 7) / 8 consecutie bytes in the string (which should be a unibyte string for best results).

If the value is nil, that means use no stipple pattern.

Normally you do not need to set the stipple attribute, because it is used automatically to handle certain shades of gray.

:underline
Whether or not characters should be underlined, and in what color. If the value is t, underlining uses the foreground color of the face. If the value is a string, underlining uses that color. The value nil means do not underline.

:overline
Whether or not characters should be overlined, and in what color. The value is used like that of :underline.

:strike-through
Whether or not characters should be strike-through, and in what color. The value is used like that of :underline.

:inherit
The name of a face from which to inherit attributes, or a list of face names. Attributes from inherited faces are merged into the face like an underlying face would be, with higher priority than underlying faces.

:box
Whether or not a box should be drawn around characters, its color, the width of the box lines, and 3D appearance.
Here are the possible values of the :box attribute, and what they mean:

nil
Don't draw a box.

t
Draw a box with lines of width 1, in the foreground color.

color
Draw a box with lines of width 1, in color color.

(:line-width width :color color :style style)
This way you can explicitly specify all aspects of the box. The value width specifies the width of the lines to draw; it defaults to 1.
The value color specifies the color to draw with. The default is the foreground color of the face for simple boxes, and the background color of the face for 3D boxes.

The value style specifies whether to draw a 3D box. If it is released-button, the box looks like a 3D button that is not being pressed. If it is pressed-button, the box looks like a 3D button that is being pressed. If it is nil or omitted, a plain 2D box is used.
The attributes :overline, :strike-through and :box are new in Emacs 21. The attributes :family, :height, :width, :weight, :slant are also new; previous versions used the following attributes, now semi-obsolete, to specify some of the same information:

:font
This attribute specifies the font name.

:bold
A non-nil value specifies a bold font.

:italic
A non-nil value specifies an italic font.
For compatibility, you can still set these "attributes" in Emacs 21, even though they are not real face attributes. Here is what that does:

:font
You can specify an X font name as the "value" of this "attribute"; that sets the :family, :width, :height, :weight, and :slant attributes according to the font name.
If the value is a pattern with wildcards, the first font that matches the pattern is used to set these attributes.

:bold
A non-nil makes the face bold; nil makes it normal. This actually works by setting the :weight attribute.

:italic
A non-nil makes the face italic; nil makes it normal. This actually works by setting the :slant attribute.

Variable: x-bitmap-file-path
This variable specifies a list of directories for searching for bitmap files, for the :stipple attribute.

Function: bitmap-spec-p object
This returns t if object is a valid bitmap specification, suitable for use with :stipple. It returns nil otherwise.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.4 Face Attribute Functions

You can modify the attributes of an existing face with the following functions. If you specify frame, they affect just that frame; otherwise, they affect all frames as well as the defaults that apply to new frames.

Function: set-face-attribute face frame &rest arguments
This function sets one or more attributes of face face for frame frame. If frame is nil, it sets the attribute for all frames, and the defaults for new frames.

The extra arguments arguments specify the attributes to set, and the values for them. They should consist of alternating attribute names (such as :family or :underline) and corresponding values. Thus,
(set-face-attribute 'foo nil
                    :width :extended
                    :weight :bold
                    :underline "red")
sets the attributes :width, :weight and :underline to the corresponding values.

Function: face-attribute face attribute &optional frame
This returns the value of the attribute attribute of face face on frame. If frame is nil, that means the selected frame (see section 29.9 Input Focus).

If frame is t, the value is the default for face for new frames.

For example,
(face-attribute 'bold :weight)
     => bold
The functions above did not exist before Emacs 21. For compatibility with older Emacs versions, you can use the following functions to set and examine the face attributes which existed in those versions.

Function: set-face-foreground face color &optional frame

Function: set-face-background face color &optional frame
These functions set the foreground (or background, respectively) color of face face to color. The argument color should be a string, the name of a color.

Certain shades of gray are implemented by stipple patterns on black-and-white screens.

Function: set-face-stipple face pattern &optional frame
This function sets the background stipple pattern of face face to pattern. The argument pattern should be the name of a stipple pattern defined by the X server, or nil meaning don't use stipple.

Normally there is no need to pay attention to stipple patterns, because they are used automatically to handle certain shades of gray.

Function: set-face-font face font &optional frame
This function sets the font of face face.

In Emacs 21, this actually sets the attributes :family, :width, :height, :weight, and :slant according to the font name font.

In Emacs 20, this sets the font attribute. Once you set the font explicitly, the bold and italic attributes cease to have any effect, because the precise font that you specified is used.

Function: set-face-bold-p face bold-p &optional frame
This function specifies whether face should be bold. If bold-p is non-nil, that means yes; nil means no.

In Emacs 21, this sets the :weight attribute. In Emacs 20, it sets the :bold attribute.

Function: set-face-italic-p face italic-p &optional frame
This function specifies whether face should be italic. If italic-p is non-nil, that means yes; nil means no.

In Emacs 21, this sets the :slant attribute. In Emacs 20, it sets the :italic attribute.

Function: set-face-underline-p face underline-p &optional frame
This function sets the underline attribute of face face. Non-nil means do underline; nil means don't.

Function: invert-face face &optional frame
This function inverts the :inverse-video attribute of face face. If the attribute is nil, this function sets it to t, and vice versa.

These functions examine the attributes of a face. If you don't specify frame, they refer to the default data for new frames. They return the symbol unspecified if the face doesn't define any value for that attribute.

Function: face-foreground face &optional frame

Function: face-background face &optional frame
These functions return the foreground color (or background color, respectively) of face face, as a string.

Function: face-stipple face &optional frame
This function returns the name of the background stipple pattern of face face, or nil if it doesn't have one.

Function: face-font face &optional frame
This function returns the name of the font of face face.

Function: face-bold-p face &optional frame
This function returns t if face is bold--that is, if it is bolder than normal. It returns nil otherwise.

Function: face-italic-p face &optional frame
This function returns t if face is italic or oblique, nil otherwise.

Function: face-underline-p face &optional frame
This function returns the :underline attribute of face face.

Function: face-inverse-video-p face &optional frame
This function returns the :inverse-video attribute of face face.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.5 Merging Faces for Display

Here are the ways to specify which faces to use for display of text:

With defaults. The default face is used as the ultimate default for all text. (In Emacs 19 and 20, the default face is used only when no other face is specified.)
For a mode line or header line, the face modeline or header-line is used just before default.

With text properties. A character can have a face property; if so, the faces and face attributes specified there apply. See section 32.19.4 Properties with Special Meanings.
If the character has a mouse-face property, that is used instead of the face property when the mouse is "near enough" to the character.

With overlays. An overlay can have face and mouse-face properties too; they apply to all the text covered by the overlay.

With a region that is active. In Transient Mark mode, the region is highlighted with the face region (see section 38.11.1 Standard Faces).

With special glyphs. Each glyph can specify a particular face number. See section 38.17.3 Glyphs.

If these various sources together specify more than one face for a particular character, Emacs merges the attributes of the various faces specified. The attributes of the faces of special glyphs come first; then comes the face for region highlighting, if appropriate; then come attributes of faces from overlays, followed by those from text properties, and last the default face.

When multiple overlays cover one character, an overlay with higher priority overrides those with lower priority. See section 38.9 Overlays.

In Emacs 20, if an attribute such as the font or a color is not specified in any of the above ways, the frame's own font or color is used. In newer Emacs versions, this cannot happen, because the default face specifies all attributes--in fact, the frame's own font and colors are synonymous with those of the default face.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.6 Font Selection

Selecting a font means mapping the specified face attributes for a character to a font that is available on a particular display. The face attributes, as determined by face merging, specify most of the font choice, but not all. Part of the choice depends on what character it is.

For multibyte characters, typically each font covers only one character set. So each character set (see section 33.5 Character Sets) specifies a registry and encoding to use, with the character set's x-charset-registry property. Its value is a string containing the registry and the encoding, with a dash between them:
(plist-get (charset-plist 'latin-iso8859-1)
           'x-charset-registry)
     => "ISO8859-1"
Unibyte text does not have character sets, so displaying a unibyte character takes the registry and encoding from the variable face-default-registry.

Variable: face-default-registry
This variable specifies which registry and encoding to use in choosing fonts for unibyte characters. The value is initialized at Emacs startup time from the font the user specified for Emacs.

If the face specifies a fontset name, that fontset determines a pattern for fonts of the given charset. If the face specifies a font family, a font pattern is constructed.

Emacs tries to find an available font for the given face attributes and character's registry and encoding. If there is a font that matches exactly, it is used, of course. The hard case is when no available font exactly fits the specification. Then Emacs looks for one that is "close"---one attribute at a time. You can specify the order to consider the attributes. In the case where a specified font family is not available, you can specify a set of mappings for alternatives to try.

Variable: face-font-selection-order
This variable specifies the order of importance of the face attributes :width, :height, :weight, and :slant. The value should be a list containing those four symbols, in order of decreasing importance.

Font selection first finds the best available matches for the first attribute listed; then, among the fonts which are best in that way, it searches for the best matches in the second attribute, and so on.

The attributes :weight and :width have symbolic values in a range centered around normal. Matches that are more extreme (farther from normal) are somewhat preferred to matches that are less extreme (closer to normal); this is designed to ensure that non-normal faces contrast with normal ones, whenever possible.

The default is (:width :height :weight :slant), which means first find the fonts closest to the specified :width, then--among the fonts with that width--find a best match for the specified font height, and so on.

One example of a case where this variable makes a difference is when the default font has no italic equivalent. With the default ordering, the italic face will use a non-italic font that is similar to the default one. But if you put :slant before :height, the italic face will use an italic font, even if its height is not quite right.

Variable: face-font-family-alternatives
This variable lets you specify alternative font families to try, if a given family is specified and doesn't exist. Each element should have this form:
(family alternate-families...)
If family is specified but not available, Emacs will try the other families given in alternate-families, one by one, until it finds a family that does exist.

Variable: face-font-registry-alternatives
This variable lets you specify alternative font registries to try, if a given registry is specified and doesn't exist. Each element should have this form:
(registry alternate-registries...)
If registry is specified but not available, Emacs will try the other registries given in alternate-registries, one by one, until it finds a registry that does exist.

Emacs can make use of scalable fonts, but by default it does not use them, since the use of too many or too big scalable fonts can crash XFree86 servers.

Variable: scalable-fonts-allowed
This variable controls which scalable fonts to use. A value of nil, the default, means do not use scalable fonts. t means to use any scalable font that seems appropriate for the text.

Otherwise, the value must be a list of regular expressions. Then a scalable font is enabled for use if its name matches any regular expression in the list. For example,
(setq scalable-fonts-allowed '("muleindian-2$"))
allows the use of scalable fonts with registry muleindian-2.

Function: clear-face-cache &optional unload-p
This function clears the face cache for all frames. If unload-p is non-nil, that means to unload all unused fonts as well.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.7 Functions for Working with Faces

Here are additional functions for creating and working with faces.

Function: make-face name
This function defines a new face named name, initially with all attributes nil. It does nothing if there is already a face named name.

Function: face-list
This function returns a list of all defined face names.

Function: copy-face old-face new-name &optional frame new-frame
This function defines the face new-name as a copy of the existing face named old-face. It creates the face new-name if that doesn't already exist.

If the optional argument frame is given, this function applies only to that frame. Otherwise it applies to each frame individually, copying attributes from old-face in each frame to new-face in the same frame.

If the optional argument new-frame is given, then copy-face copies the attributes of old-face in frame to new-name in new-frame.

Function: face-id face
This function returns the face number of face face.

Function: face-documentation face
This function returns the documentation string of face face, or nil if none was specified for it.

Function: face-equal face1 face2 &optional frame
This returns t if the faces face1 and face2 have the same attributes for display.

Function: face-differs-from-default-p face &optional frame
This returns t if the face face displays differently from the default face. A face is considered to be "the same" as the default face if each attribute is either the same as that of the default face, or unspecified (meaning to inherit from the default).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.8 Automatic Face Assignment

Starting with Emacs 21, a hook is available for automatically assigning faces to text in the buffer. This hook is used for part of the implementation of Font-Lock mode.

Variable: fontification-functions
This variable holds a list of functions that are called by Emacs redisplay as needed to assign faces automatically to text in the buffer.

The functions are called in the order listed, with one argument, a buffer position pos. Each function should attempt to assign faces to the text in the current buffer starting at pos.

Each function should record the faces they assign by setting the face property. It should also add a non-nil fontified property for all the text it has assigned faces to. That property tells redisplay that faces have been assigned to that text already.

It is probably a good idea for each function to do nothing if the character after pos already has a non-nil fontified property, but this is not required. If one function overrides the assignments made by a previous one, the properties as they are after the last function finishes are the ones that really matter.

For efficiency, we recommend writing these functions so that they usually assign faces to around 400 to 600 characters at each call.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.9 Looking Up Fonts

Function: x-list-fonts pattern &optional face frame maximum
This function returns a list of available font names that match pattern. If the optional arguments face and frame are specified, then the list is limited to fonts that are the same size as face currently is on frame.

The argument pattern should be a string, perhaps with wildcard characters: the `*' character matches any substring, and the `?' character matches any single character. Pattern matching of font names ignores case.

If you specify face and frame, face should be a face name (a symbol) and frame should be a frame.

The optional argument maximum sets a limit on how many fonts to return. If this is non-nil, then the return value is truncated after the first maximum matching fonts. Specifying a small value for maximum can make this function much faster, in cases where many fonts match the pattern.

These additional functions are available starting in Emacs 21.

Function: x-family-fonts &optional family frame
This function returns a list describing the available fonts for family family on frame. If family is omitted or nil, this list applies to all families, and therefore, it contains all available fonts. Otherwise, family must be a string; it may contain the wildcards `?' and `*'.

The list describes the display that frame is on; if frame is omitted or nil, it applies to the selected frame's display (see section 29.9 Input Focus).

The list contains a vector of the following form for each font:
[family width point-size weight slant
 fixed-p full registry-and-encoding]
The first five elements correspond to face attributes; if you specify these attributes for a face, it will use this font.

The last three elements give additional information about the font. fixed-p is non-nil if the font is fixed-pitch. full is the full name of the font, and registry-and-encoding is a string giving the registry and encoding of the font.

The result list is sorted according to the current face font sort order.

Function: x-font-family-list &optional frame
This function returns a list of the font families available for frame's display. If frame is omitted or nil, it describes the selected frame's display (see section 29.9 Input Focus).

The value is a list of elements of this form:
(family . fixed-p)
Here family is a font family, and fixed-p is non-nil if fonts of that family are fixed-pitch.

Variable: font-list-limit
This variable specifies maximum number of fonts to consider in font matching. The function x-family-fonts will not return more than that many fonts, and font selection will consider only that many fonts when searching a matching font for face attributes. The default is currently 100.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.11.10 Fontsets

A fontset is a list of fonts, each assigned to a range of character codes. An individual font cannot display the whole range of characters that Emacs supports, but a fontset can. Fontsets have names, just as fonts do, and you can use a fontset name in place of a font name when you specify the "font" for a frame or a face. Here is information about defining a fontset under Lisp program control.

Function: create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
This function defines a new fontset according to the specification string fontset-spec. The string should have this format:
fontpattern, [charsetname:fontname]...
Whitespace characters before and after the commas are ignored.

The first part of the string, fontpattern, should have the form of a standard X font name, except that the last two fields should be `fontset-alias'.

The new fontset has two names, one long and one short. The long name is fontpattern in its entirety. The short name is `fontset-alias'. You can refer to the fontset by either name. If a fontset with the same name already exists, an error is signaled, unless noerror is non-nil, in which case this function does nothing.

If optional argument style-variant-p is non-nil, that says to create bold, italic and bold-italic variants of the fontset as well. These variant fontsets do not have a short name, only a long one, which is made by altering fontpattern to indicate the bold or italic status.

The specification string also says which fonts to use in the fontset. See below for the details.

The construct `charset:font' specifies which font to use (in this fontset) for one particular character set. Here, charset is the name of a character set, and font is the font to use for that character set. You can use this construct any number of times in the specification string.

For the remaining character sets, those that you don't specify explicitly, Emacs chooses a font based on fontpattern: it replaces `fontset-alias' with a value that names one character set. For the ASCII character set, `fontset-alias' is replaced with `ISO8859-1'.

In addition, when several consecutive fields are wildcards, Emacs collapses them into a single wildcard. This is to prevent use of auto-scaled fonts. Fonts made by scaling larger fonts are not usable for editing, and scaling a smaller font is not useful because it is better to use the smaller font in its own size, which Emacs does.

Thus if fontpattern is this,
-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
the font specification for ASCII characters would be this:
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
and the font specification for Chinese GB2312 characters would be this:
-*-fixed-medium-r-normal-*-24-*-gb2312*-*
You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that have `song ti' or `fangsong ti' in the family field. In such a case, `Fontset-n' can be specified as below:
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
Then, the font specifications for all but Chinese GB2312 characters have `fixed' in the family field, and the font specification for Chinese GB2312 characters has a wild card `*' in the family field.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.12 The display Property

The display text property (or overlay property) is used to insert images into text, and also control other aspects of how text displays. These features are available starting in Emacs 21. The value of the display property should be a display specification, or a list or vector containing several display specifications. The rest of this section describes several kinds of display specifications and what they mean.

38.12.1 Specified Spaces

Displaying one space with a specified width.

38.12.2 Other Display Specifications

Displaying an image; magnifying text; moving it up or down on the page; adjusting the width of spaces within text.

38.12.3 Displaying in the Margins

Displaying text or images to the side of the main text.

38.12.4 Conditional Display Specifications

Making any of the above features conditional depending on some Lisp expression.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.12.1 Specified Spaces

To display a space of specified width and/or height, use a display specification of the form (space . props), where props is a property list (a list of alternating properties and values). You can put this property on one or more consecutive characters; a space of the specified height and width is displayed in place of all of those characters. These are the properties you can use to specify the weight of the space:

:width width
Specifies that the space width should be width times the normal character width. width can be an integer or floating point number.

:relative-width factor
Specifies that the width of the stretch should be computed from the first character in the group of consecutive characters that have the same display property. The space width is the width of that character, multiplied by factor.

:align-to hpos
Specifies that the space should be wide enough to reach hpos. The value hpos is measured in units of the normal character width. It may be an interer or a floating point number.
Exactly one of the above properties should be used. You can also specify the height of the space, with other properties:

:height height
Specifies the height of the space, as height, measured in terms of the normal line height.

:relative-height factor
Specifies the height of the space, multiplying the ordinary height of the text having this display specification by factor.

:ascent ascent
Specifies that ascent percent of the height of the space should be considered as the ascent of the space--that is, the part above the baseline. The value of ascent must be a non-negative number no greater than 100.
You should not use both :height and :relative-height together.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.12.2 Other Display Specifications

(image . image-props)
This is in fact an image descriptor (see section 38.13 Images). When used as a display specification, it means to display the image instead of the text that has the display specification.

((margin nil) string)

string
A display specification of this form means to display string instead of the text that has the display specification, at the same position as that text. This is a special case of marginal display (see section 38.12.3 Displaying in the Margins).
Recursive display specifications are not supported, i.e. string display specifications that have a display specification property themselves.

(space-width factor)
This display specification affects all the space characters within the text that has the specification. It displays all of these spaces factor times as wide as normal. The element factor should be an integer or float. Characters other than spaces are not affected at all; in particular, this has no effect on tab characters.

(height height)
This display specification makes the text taller or shorter. Here are the possibilities for height:

(+ n)
This means to use a font that is n steps larger. A "step" is defined by the set of available fonts--specifically, those that match what was otherwise specified for this text, in all attributes except height. Each size for which a suitable font is available counts as another step. n should be an integer.

(- n)
This means to use a font that is n steps smaller.

a number, factor
A number, factor, means to use a font that is factor times as tall as the default font.

a symbol, function
A symbol is a function to compute the height. It is called with the current height as argument, and should return the new height to use.

anything else, form
If the height value doesn't fit the previous possibilities, it is a form. Emacs evaluates it to get the new height, with the symbol height bound to the current specified font height.

(raise factor)
This kind of display specification raises or lowers the text it applies to, relative to the baseline of the line.
factor must be a number, which is interpreted as a multiple of the height of the affected text. If it is positive, that means to display the characters raised. If it is negative, that means to display them lower down.

If the text also has a height display specification, that does not affect the amount of raising or lowering, which is based on the faces used for the text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.12.3 Displaying in the Margins

A buffer can have blank areas called display margins on the left and on the right. Ordinary text never appears in these areas, but you can put things into the display margins using the display property.

To put text in the left or right display margin of the window, use a display specification of the form (margin right-margin) or (margin left-margin) on it. To put an image in a display margin, use that display specification along with the display specification for the image.

Before the display margins can display anything, you must give them a nonzero width. The usual way to do that is to set these variables:

Variable: left-margin-width
This variable specifies the width of the left margin. It is buffer-local in all buffers.

Variable: right-margin-width
This variable specifies the width of the right margin. It is buffer-local in all buffers.

Setting these variables does not immediately affect the window. These variables are checked when a new buffer is displayed in the window. Thus, you can make changes take effect by calling set-window-buffer.

You can also set the margin widths immediately.

Function: set-window-margins window left &optional right
This function specifies the margin widths for window window. The argument left controls the left margin and right controls the right margin (default 0).

Function: window-margins &optional window
This function returns the left and right margins of window as a cons cell of the form (left . right). If window is nil, the selected window is used.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.12.4 Conditional Display Specifications

You can make any display specification conditional. To do that, package it in another list of the form (when condition . spec). Then the specification spec applies only when condition evaluates to a non-nil value. During the evaluation, object is bound to the string or buffer having the conditional display property. position and buffer-position are bound to the position within object and the buffer position where the display property was found, respectively. Both positions can be different when object is a string.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13 Images

To display an image in an Emacs buffer, you must first create an image descriptor, then use it as a display specifier in the display property of text that is displayed (see section 38.12 The display Property). Like the display property, this feature is available starting in Emacs 21.

Emacs can display a number of different image formats; some of them are supported only if particular support libraries are installed on your machine. The supported image formats include XBM, XPM (needing the libraries libXpm version 3.4k and libz), GIF (needing libungif 4.1.0), Postscript, PBM, JPEG (needing the libjpeg library version v6a), TIFF (needing libtiff v3.4), and PNG (needing libpng 1.0.2).

You specify one of these formats with an image type symbol. The image type symbols are xbm, xpm, gif, postscript, pbm, jpeg, tiff, and png.

Variable: image-types
This variable contains a list of those image type symbols that are supported in the current configuration.

38.13.1 Image Descriptors

How to specify an image for use in :display.

38.13.2 XBM Images

Special features for XBM format.

38.13.3 XPM Images

Special features for XPM format.

38.13.4 GIF Images

Special features for GIF format.

38.13.5 Postscript Images

Special features for Postscript format.

38.13.6 Other Image Types

Various other formats are supported.

38.13.7 Defining Images

Convenient ways to define an image for later use.

38.13.8 Showing Images

Convenient ways to display an image once it is defined.

38.13.9 Image Cache

Internal mechanisms of image display.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.1 Image Descriptors

An image description is a list of the form (image . props), where props is a property list containing alternating keyword symbols (symbols whose names start with a colon) and their values. You can use any Lisp object as a property, but the only properties that have any special meaning are certain symbols, all of them keywords.

Every image descriptor must contain the property :type type to specify the format of the image. The value of type should be an image type symbol; for example, xpm for an image in XPM format.

Here is a list of other properties that are meaningful for all image types:

:file file
The :file property specifies to load the image from file file. If file is not an absolute file name, it is expanded in data-directory.

:data data
The :data property specifies the actual contents of the image. Each image must use either :data or :file, but not both. For most image types, the value of the :data property should be a string containing the image data; we recommend using a unibyte string.
Before using :data, look for further information in the section below describing the specific image format. For some image types, :data may not be supported; for some, it allows other data types; for some, :data alone is not enough, so you need to use other image properties along with :data.

:margin margin
The :margin property specifies how many pixels to add as an extra margin around the image. The value, margin, must be a a non-negative number, or a pair (x . y) of such numbers. If it is a pair, x specifies how many pixels to add horizontally, and y specifies how many pixels to add vertically. If :margin is not specified, the default is zero.

:ascent ascent
The :ascent property specifies the amount of the image's height to use for its ascent--that is, the part above the baseline. The value, ascent, must be a number in the range 0 to 100, or the symbol center.
If ascent is a number, that percentage of the image's height is used for its ascent.

If ascent is center, the image is vertically centered around a centerline which would be the vertical centerline of text drawn at the position of the image, in the manner specified by the text properties and overlays that apply to the image.

If this property is omitted, it defaults to 50.

:relief relief
The :relief property, if non-nil, adds a shadow rectangle around the image. The value, relief, specifies the width of the shadow lines, in pixels. If relief is negative, shadows are drawn so that the image appears as a pressed button; otherwise, it appears as an unpressed button.

:conversion algorithm
The :conversion property, if non-nil, specifies a conversion algorithm that should be applied to the image before it is displayed; the value, algorithm, specifies which algorithm.

laplace

emboss
Specifies the Laplace edge detection algorithm, which blurs out small differences in color while highlighting larger differences. People sometimes consider this useful for displaying the image for a "disabled" button.

(edge-detection :matrix matrix :color-adjust adjust)
Specifies a general edge-detection algorithm. matrix must be either a nine-element list or a nine-element vector of numbers. A pixel at position x/y in the transformed image is computed from original pixels around that position. matrix specifies, for each pixel in the neighborhood of x/y, a factor with which that pixel will influence the transformed pixel; element 0 specifies the factor for the pixel at x-1/y-1, element 1 the factor for the pixel at x/y-1 etc., as shown below:
  (x-1/y-1  x/y-1  x+1/y-1
   x-1/y    x/y    x+1/y
   x-1/y+1  x/y+1  x+1/y+1)
The resulting pixel is computed from the color intensity of the color resulting from summing up the RGB values of surrounding pixels, multiplied by the specified factors, and dividing that sum by the sum of the factors' absolute values.

Laplace edge-detection currently uses a matrix of
  (1  0  0
   0  0  0
   9  9 -1)
Emboss edge-detection uses a matrix of
  ( 2 -1  0
   -1  0  1
    0  1 -2)
disabled
Specifies transforming the image so that it looks "disabled".

:mask mask
If mask is heuristic or (heuristic bg), build a clipping mask for the image, so that the background of a frame is visible behind the image. If bg is not specified, or if bg is t, determine the background color of the image by looking at the four corners of the image, assuming the most frequently occurring color from the corners is the background color of the image. Otherwise, bg must be a list (red green blue) specifying the color to assume for the background of the image.
If mask is nil, remove a mask from the image, if it has one. Images in some formats include a mask which can be removed by specifying :mask nil.

Function: image-mask-p spec &optional frame
This function returns t if image spec has a mask bitmap. frame is the frame on which the image will be displayed. frame nil or omitted means to use the selected frame (see section 29.9 Input Focus).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.2 XBM Images

To use XBM format, specify xbm as the image type. This image format doesn't require an external library, so images of this type are always supported.

Additional image properties supported for the xbm image type are:

:foreground foreground
The value, foreground, should be a string specifying the image foreground color, or nil for the default color. This color is used for each pixel in the XBM that is 1. The default is the frame's foreground color.

:background background
The value, background, should be a string specifying the image background color, or nil for the default color. This color is used for each pixel in the XBM that is 0. The default is the frame's background color.
If you specify an XBM image using data within Emacs instead of an external file, use the following three properties:

:data data
The value, data, specifies the contents of the image. There are three formats you can use for data:

A vector of strings or bool-vectors, each specifying one line of the image. Do specify :height and :width.

A string containing the same byte sequence as an XBM file would contain. You must not specify :height and :width in this case, because omitting them is what indicates the data has the format of an XBM file. The file contents specify the height and width of the image.

A string or a bool-vector containing the bits of the image (plus perhaps some extra bits at the end that will not be used). It should contain at least width * height bits. In this case, you must specify :height and :width, both to indicate that the string contains just the bits rather than a whole XBM file, and to specify the size of the image.

:width width
The value, width, specifies the width of the image, in pixels.

:height height
The value, height, specifies the height of the image, in pixels.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.3 XPM Images

To use XPM format, specify xpm as the image type. The additional image property :color-symbols is also meaningful with the xpm image type:

:color-symbols symbols
The value, symbols, should be an alist whose elements have the form (name . color). In each element, name is the name of a color as it appears in the image file, and color specifies the actual color to use for displaying that name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.4 GIF Images

For GIF images, specify image type gif. Because of the patents in the US covering the LZW algorithm, the continued use of GIF format is a problem for the whole Internet; to end this problem, it is a good idea for everyone, even outside the US, to stop using GIFS right away (http://www.burnallgifs.org/). But if you still want to use them, Emacs can display them.

:index index
You can use :index to specify one image from a GIF file that contains more than one image. This property specifies use of image number index from the file. An error is signaled if the GIF file doesn't contain an image with index index.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.5 Postscript Images

To use Postscript for an image, specify image type postscript. This works only if you have Ghostscript installed. You must always use these three properties:

:pt-width width
The value, width, specifies the width of the image measured in points (1/72 inch). width must be an integer.

:pt-height height
The value, height, specifies the height of the image in points (1/72 inch). height must be an integer.

:bounding-box box
The value, box, must be a list or vector of four integers, which specifying the bounding box of the Postscript image, analogous to the `BoundingBox' comment found in Postscript files.
%%BoundingBox: 22 171 567 738
Displaying Postscript images from Lisp data is not currently implemented, but it may be implemented by the time you read this. See the `etc/NEWS' file to make sure.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.6 Other Image Types

For PBM images, specify image type pbm. Color, gray-scale and monochromatic images are supported. For mono PBM images, two additional image properties are supported.

:foreground foreground
The value, foreground, should be a string specifying the image foreground color, or nil for the default color. This color is used for each pixel in the XBM that is 1. The default is the frame's foreground color.

:background background
The value, background, should be a string specifying the image background color, or nil for the default color. This color is used for each pixel in the XBM that is 0. The default is the frame's background color.
For JPEG images, specify image type jpeg.

For TIFF images, specify image type tiff.

For PNG images, specify image type png.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.7 Defining Images

The functions create-image, defimage and find-image provide convenient ways to create image descriptors.

Function: create-image file &optional type &rest props
This function creates and returns an image descriptor which uses the data in file.

The optional argument type is a symbol specifying the image type. If type is omitted or nil, create-image tries to determine the image type from the file's first few bytes, or else from the file's name.

The remaining arguments, props, specify additional image properties--for example,
(create-image "foo.xpm" 'xpm :heuristic-mask t)
The function returns nil if images of this type are not supported. Otherwise it returns an image descriptor.

Macro: defimage variable doc &rest specs
This macro defines variable as an image name. The second argument, doc, is an optional documentation string. The remaining arguments, specs, specify alternative ways to display the image.

Each argument in specs has the form of a property list, and each one should specify at least the :type property and the :file property. Here is an example:
(defimage test-image
  '((:type xpm :file "~/test1.xpm")
    (:type xbm :file "~/test1.xbm")))
defimage tests each argument, one by one, to see if it is usable--that is, if the type is supported and the file exists. The first usable argument is used to make an image descriptor which is stored in the variable variable.

If none of the alternatives will work, then variable is defined as nil.

Function: find-image specs
This function provides a convenient way to find an image satisfying one of a list of image specifications specs.

Each specification in specs is a property list with contents depending on image type. All specifications must at least contain the properties :type type and either :file file or :data DATA, where type is a symbol specifying the image type, e.g. xbm, file is the file to load the image from, and data is a string containing the actual image data. The first specification in the list whose type is supported, and file exists, is used to construct the image specification to be returned. If no specification is satisfied, nil is returned.

The image is looked for first on load-path and then in data-directory.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.8 Showing Images

You can use an image descriptor by setting up the display property yourself, but it is easier to use the functions in this section.

Function: insert-image image &optional string area
This function inserts image in the current buffer at point. The value image should be an image descriptor; it could be a value returned by create-image, or the value of a symbol defined with defimage. The argument string specifies the text to put in the buffer to hold the image.

The argument area specifies whether to put the image in a margin. If it is left-margin, the image appears in the left margin; right-margin specifies the right margin. If area is nil or omitted, the image is displayed at point within the buffer's text.

Internally, this function inserts string in the buffer, and gives it a display property which specifies image. See section 38.12 The display Property.

Function: put-image image pos &optional string area
This function puts image image in front of pos in the current buffer. The argument pos should be an integer or a marker. It specifies the buffer position where the image should appear. The argument string specifies the text that should hold the image as an alternative to the default.

The argument image must be an image descriptor, perhaps returned by create-image or stored by defimage.

The argument area specifies whether to put the image in a margin. If it is left-margin, the image appears in the left margin; right-margin specifies the right margin. If area is nil or omitted, the image is displayed at point within the buffer's text.

Internally, this function creates an overlay, and gives it a before-string property containing text that has a display property whose value is the image. (Whew!)

Function: remove-images start end &optional buffer
This function removes images in buffer between positions start and end. If buffer is omitted or nil, images are removed from the current buffer.

This removes only images that were put into buffer the way put-image does it, not images that were inserted with insert-image or in other ways.

Function: image-size spec &optional pixels frame
This function returns the size of an image as a pair (width . height). spec is an image specification. pixels non-nil means return sizes measured in pixels, otherwise return sizes measured in canonical character units (fractions of the width/height of the frame's default font). frame is the frame on which the image will be displayed. frame null or omitted means use the selected frame (see section 29.9 Input Focus).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.13.9 Image Cache

Emacs stores images in an image cache when it displays them, so it can display them again more efficiently. It removes an image from the cache when it hasn't been displayed for a specified period of time.

When an image is looked up in the cache, its specification is compared with cached image specifications using equal. This means that all images with equal specifications share the same image in the cache.

Variable: image-cache-eviction-delay
This variable specifies the number of seconds an image can remain in the cache without being displayed. When an image is not displayed for this length of time, Emacs removes it from the image cache.

If the value is nil, Emacs does not remove images from the cache except when you explicitly clear it. This mode can be useful for debugging.

Function: clear-image-cache &optional frame
This function clears the image cache. If frame is non-nil, only the cache for that frame is cleared. Otherwise all frames' caches are cleared.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.14 Blinking Parentheses

This section describes the mechanism by which Emacs shows a matching open parenthesis when the user inserts a close parenthesis.

Variable: blink-paren-function
The value of this variable should be a function (of no arguments) to be called whenever a character with close parenthesis syntax is inserted. The value of blink-paren-function may be nil, in which case nothing is done.

User Option: blink-matching-paren
If this variable is nil, then blink-matching-open does nothing.

User Option: blink-matching-paren-distance
This variable specifies the maximum distance to scan for a matching parenthesis before giving up.

User Option: blink-matching-delay
This variable specifies the number of seconds for the cursor to remain at the matching parenthesis. A fraction of a second often gives good results, but the default is 1, which works on all systems.

Command: blink-matching-open
This function is the default value of blink-paren-function. It assumes that point follows a character with close parenthesis syntax and moves the cursor momentarily to the matching opening character. If that character is not already on the screen, it displays the character's context in the echo area. To avoid long delays, this function does not search farther than blink-matching-paren-distance characters.

Here is an example of calling this function explicitly.
(defun interactive-blink-matching-open ()
  "Indicate momentarily the start of sexp before point."
  (interactive)
  (let ((blink-matching-paren-distance
         (buffer-size))
        (blink-matching-paren t))
    (blink-matching-open)))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.15 Inverse Video

User Option: inverse-video
This variable controls whether Emacs uses inverse video for all text on the screen. Non-nil means yes, nil means no. The default is nil.

User Option: mode-line-inverse-video
This variable controls the use of inverse video for mode lines and menu bars. If it is non-nil, then these lines are displayed in inverse video. Otherwise, these lines are displayed normally, just like other text. The default is t.

For window frames, this feature actually applies the face named mode-line; that face is normally set up as the inverse of the default face, unless you change it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.16 Usual Display Conventions

The usual display conventions define how to display each character code. You can override these conventions by setting up a display table (see section 38.17 Display Tables). Here are the usual display conventions:

Character codes 32 through 126 map to glyph codes 32 through 126. Normally this means they display as themselves.

Character code 9 is a horizontal tab. It displays as whitespace up to a position determined by tab-width.

Character code 10 is a newline.

All other codes in the range 0 through 31, and code 127, display in one of two ways according to the value of ctl-arrow. If it is non-nil, these codes map to sequences of two glyphs, where the first glyph is the ASCII code for `^'. (A display table can specify a glyph to use instead of `^'.) Otherwise, these codes map just like the codes in the range 128 to 255.
On MS-DOS terminals, Emacs arranges by default for the character code 127 to be mapped to the glyph code 127, which normally displays as an empty polygon. This glyph is used to display non-ASCII characters that the MS-DOS terminal doesn't support. See section `MS-DOS and MULE' in The GNU Emacs Manual.

Character codes 128 through 255 map to sequences of four glyphs, where the first glyph is the ASCII code for `\', and the others are digit characters representing the character code in octal. (A display table can specify a glyph to use instead of `\'.)

Multibyte character codes above 256 are displayed as themselves, or as a question mark or empty box if the terminal cannot display that character.

The usual display conventions apply even when there is a display table, for any character whose entry in the active display table is nil. Thus, when you set up a display table, you need only specify the characters for which you want special behavior.

These display rules apply to carriage return (character code 13), when it appears in the buffer. But that character may not appear in the buffer where you expect it, if it was eliminated as part of end-of-line conversion (see section 33.10.1 Basic Concepts of Coding Systems).

These variables affect the way certain characters are displayed on the screen. Since they change the number of columns the characters occupy, they also affect the indentation functions. These variables also affect how the mode line is displayed; if you want to force redisplay of the mode line using the new values, call the function force-mode-line-update (see section 23.3 Mode Line Format).

User Option: ctl-arrow
This buffer-local variable controls how control characters are displayed. If it is non-nil, they are displayed as a caret followed by the character: `^A'. If it is nil, they are displayed as a backslash followed by three octal digits: `\001'.

Variable: default-ctl-arrow
The value of this variable is the default value for ctl-arrow in buffers that do not override it. See section 11.10.3 The Default Value of a Buffer-Local Variable.

User Option: indicate-empty-lines
When this is non-nil, Emacs displays a special glyph in each empty line at the end of the buffer, on terminals that support it (window systems).

User Option: tab-width
The value of this variable is the spacing between tab stops used for displaying tab characters in Emacs buffers. The value is in units of columns, and the default is 8. Note that this feature is completely independent of the user-settable tab stops used by the command tab-to-tab-stop. See section 32.17.5 Adjustable "Tab Stops".

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.17 Display Tables

You can use the display table feature to control how all possible character codes display on the screen. This is useful for displaying European languages that have letters not in the ASCII character set.

The display table maps each character code into a sequence of glyphs, each glyph being a graphic that takes up one character position on the screen. You can also define how to display each glyph on your terminal, using the glyph table.

Display tables affect how the mode line is displayed; if you want to force redisplay of the mode line using a new display table, call force-mode-line-update (see section 23.3 Mode Line Format).

38.17.1 Display Table Format

What a display table consists of.

38.17.2 Active Display Table

How Emacs selects a display table to use.

38.17.3 Glyphs

How to define a glyph, and what glyphs mean.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.17.1 Display Table Format

A display table is actually a char-table (see section 6.6 Char-Tables) with display-table as its subtype.

Function: make-display-table
This creates and returns a display table. The table initially has nil in all elements.

The ordinary elements of the display table are indexed by character codes; the element at index c says how to display the character code c. The value should be nil or a vector of glyph values (see section 38.17.3 Glyphs). If an element is nil, it says to display that character according to the usual display conventions (see section 38.16 Usual Display Conventions).

If you use the display table to change the display of newline characters, the whole buffer will be displayed as one long "line."

The display table also has six "extra slots" which serve special purposes. Here is a table of their meanings; nil in any slot means to use the default for that slot, as stated below.

0
The glyph for the end of a truncated screen line (the default for this is `$'). See section 38.17.3 Glyphs. Newer Emacs versions, on some platforms, display arrows to indicate truncation--the display table has no effect in these situations.
1
The glyph for the end of a continued line (the default is `\'). Newer Emacs versions, on some platforms, display curved arrows to indicate truncation--the display table has no effect in these situations.
2
The glyph for indicating a character displayed as an octal character code (the default is `\').
3
The glyph for indicating a control character (the default is `^').
4
A vector of glyphs for indicating the presence of invisible lines (the default is `...'). See section 38.6 Selective Display.
5
The glyph used to draw the border between side-by-side windows (the default is `|'). See section 28.2 Splitting Windows. This takes effect only when there are no scroll bars; if scroll bars are supported and in use, a scroll bar separates the two windows.
For example, here is how to construct a display table that mimics the effect of setting ctl-arrow to a non-nil value:
(setq disptab (make-display-table))
(let ((i 0))
  (while (< i 32)
    (or (= i ?\t) (= i ?\n)
        (aset disptab i (vector ?^ (+ i 64))))
    (setq i (1+ i)))
  (aset disptab 127 (vector ?^ ??)))
Function: display-table-slot display-table slot
This function returns the value of the extra slot slot of display-table. The argument slot may be a number from 0 to 5 inclusive, or a slot name (symbol). Valid symbols are truncation, wrap, escape, control, selective-display, and vertical-border.

Function: set-display-table-slot display-table slot value
This function stores value in the extra slot slot of display-table. The argument slot may be a number from 0 to 5 inclusive, or a slot name (symbol). Valid symbols are truncation, wrap, escape, control, selective-display, and vertical-border.

Function: describe-display-table display-table
This function displays a description of the display table display-table in a help buffer.

Command: describe-current-display-table
This command displays a description of the current display table in a help buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.17.2 Active Display Table

Each window can specify a display table, and so can each buffer. When a buffer b is displayed in window w, display uses the display table for window w if it has one; otherwise, the display table for buffer b if it has one; otherwise, the standard display table if any. The display table chosen is called the active display table.

Function: window-display-table window
This function returns window's display table, or nil if window does not have an assigned display table.

Function: set-window-display-table window table
This function sets the display table of window to table. The argument table should be either a display table or nil.

Variable: buffer-display-table
This variable is automatically buffer-local in all buffers; its value in a particular buffer specifies the display table for that buffer. If it is nil, that means the buffer does not have an assigned display table.

Variable: standard-display-table
This variable's value is the default display table, used whenever a window has no display table and neither does the buffer displayed in that window. This variable is nil by default.

If there is no display table to use for a particular window--that is, if the window specifies none, its buffer specifies none, and standard-display-table is nil---then Emacs uses the usual display conventions for all character codes in that window. See section 38.16 Usual Display Conventions.

A number of functions for changing the standard display table are defined in the library `disp-table'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.17.3 Glyphs

A glyph is a generalization of a character; it stands for an image that takes up a single character position on the screen. Glyphs are represented in Lisp as integers, just as characters are.

The meaning of each integer, as a glyph, is defined by the glyph table, which is the value of the variable glyph-table.

Variable: glyph-table
The value of this variable is the current glyph table. It should be a vector; the gth element defines glyph code g. If the value is nil instead of a vector, then all glyphs are simple (see below). The glyph table is not used on windowed displays.

Here are the possible types of elements in the glyph table:

string
Send the characters in string to the terminal to output this glyph. This alternative is available on character terminals, but not under a window system.

integer
Define this glyph code as an alias for glyph code integer. You can use an alias to specify a face code for the glyph; see below.

nil
This glyph is simple. The glyph code mod 524288 is the character to output, and the glyph code divided by 524288 specifies the face number (see section 38.11.7 Functions for Working with Faces) to use while outputting it. (524288 is 2**19.) See section 38.11 Faces.
If a glyph code is greater than or equal to the length of the glyph table, that code is automatically simple.

Function: create-glyph string
This function returns a newly-allocated glyph code which is set up to display by sending string to the terminal.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.18 Beeping

This section describes how to make Emacs ring the bell (or blink the screen) to attract the user's attention. Be conservative about how often you do this; frequent bells can become irritating. Also be careful not to use just beeping when signaling an error is more appropriate. (See section 10.5.3 Errors.)

Function: ding &optional do-not-terminate
This function beeps, or flashes the screen (see visible-bell below). It also terminates any keyboard macro currently executing unless do-not-terminate is non-nil.

Function: beep &optional do-not-terminate
This is a synonym for ding.

User Option: visible-bell
This variable determines whether Emacs should flash the screen to represent a bell. Non-nil means yes, nil means no. This is effective on a window system, and on a character-only terminal provided the terminal's Termcap entry defines the visible bell capability (`vb').

Variable: ring-bell-function
If this is non-nil, it specifies how Emacs should "ring the bell." Its value should be a function of no arguments. If this is non-nil, it takes precedence over the visible-bell variable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

38.19 Window Systems

Emacs works with several window systems, most notably the X Window System. Both Emacs and X use the term "window", but use it differently. An Emacs frame is a single window as far as X is concerned; the individual Emacs windows are not known to X at all.

Variable: window-system
This variable tells Lisp programs what window system Emacs is running under. The possible values are

x
Emacs is displaying using X.
pc
Emacs is displaying using MS-DOS.
w32
Emacs is displaying using Windows.
mac
Emacs is displaying using a Macintosh.
nil
Emacs is using a character-based terminal.

Variable: window-setup-hook
This variable is a normal hook which Emacs runs after handling the initialization files. Emacs runs this hook after it has completed loading your init file, the default initialization file (if any), and the terminal-specific Lisp code, and running the hook term-setup-hook.

This hook is used for internal purposes: setting up communication with the window system, and creating the initial window. Users should not interfere with it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39. Customizing the Calendar and Diary

There are many customizations that you can use to make the calendar and diary suit your personal tastes.

39.1 Customizing the Calendar

Defaults you can set.

39.2 Customizing the Holidays

Defining your own holidays.

39.3 Date Display Format

Changing the format.

39.4 Time Display Format

Changing the format.

39.5 Daylight Savings Time

Changing the default.

39.6 Customizing the Diary

Defaults you can set.

39.7 Hebrew- and Islamic-Date Diary Entries

How to obtain them.

39.8 Fancy Diary Display

Enhancing the diary display, sorting entries, using included diary files.

39.9 Sexp Entries and the Fancy Diary Display

Fancy things you can do.

39.10 Customizing Appointment Reminders

Customizing appointment reminders.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.1 Customizing the Calendar

If you set the variable view-diary-entries-initially to t, calling up the calendar automatically displays the diary entries for the current date as well. The diary dates appear only if the current date is visible. If you add both of the following lines to your init file:
(setq view-diary-entries-initially t)
(calendar)
this displays both the calendar and diary windows whenever you start Emacs.

Similarly, if you set the variable view-calendar-holidays-initially to t, entering the calendar automatically displays a list of holidays for the current three-month period. The holiday list appears in a separate window.

You can set the variable mark-diary-entries-in-calendar to t in order to mark any dates with diary entries. This takes effect whenever the calendar window contents are recomputed. There are two ways of marking these dates: by changing the face (see section 38.11 Faces), or by placing a plus sign (`+') beside the date.

Similarly, setting the variable mark-holidays-in-calendar to t marks holiday dates, either with a change of face or with an asterisk (`*').

The variable calendar-holiday-marker specifies how to mark a date as being a holiday. Its value may be a character to insert next to the date, or a face name to use for displaying the date. Likewise, the variable diary-entry-marker specifies how to mark a date that has diary entries. The calendar creates faces named holiday-face and diary-face for these purposes; those symbols are the default values of these variables.

The variable calendar-load-hook is a normal hook run when the calendar package is first loaded (before actually starting to display the calendar).

Starting the calendar runs the normal hook initial-calendar-window-hook. Recomputation of the calendar display does not run this hook. But if you leave the calendar with the q command and reenter it, the hook runs again.

The variable today-visible-calendar-hook is a normal hook run after the calendar buffer has been prepared with the calendar when the current date is visible in the window. One use of this hook is to replace today's date with asterisks; to do that, use the hook function calendar-star-date.
(add-hook 'today-visible-calendar-hook 'calendar-star-date)
Another standard hook function marks the current date, either by changing its face or by adding an asterisk. Here's how to use it:
(add-hook 'today-visible-calendar-hook 'calendar-mark-today)
The variable calendar-today-marker specifies how to mark today's date. Its value should be a character to insert next to the date or a face name to use for displaying the date. A face named calendar-today-face is provided for this purpose; that symbol is the default for this variable.

A similar normal hook, today-invisible-calendar-hook is run if the current date is not visible in the window.

Starting in Emacs 21, each of the calendar cursor motion commands runs the hook calendar-move-hook after it moves the cursor.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.2 Customizing the Holidays

Emacs knows about holidays defined by entries on one of several lists. You can customize these lists of holidays to your own needs, adding or deleting holidays. The lists of holidays that Emacs uses are for general holidays (general-holidays), local holidays (local-holidays), Christian holidays (christian-holidays), Hebrew (Jewish) holidays (hebrew-holidays), Islamic (Moslem) holidays (islamic-holidays), and other holidays (other-holidays).

The general holidays are, by default, holidays common throughout the United States. To eliminate these holidays, set general-holidays to nil.

There are no default local holidays (but sites may supply some). You can set the variable local-holidays to any list of holidays, as described below.

By default, Emacs does not include all the holidays of the religions that it knows, only those commonly found in secular calendars. For a more extensive collection of religious holidays, you can set any (or all) of the variables all-christian-calendar-holidays, all-hebrew-calendar-holidays, or all-islamic-calendar-holidays to t. If you want to eliminate the religious holidays, set any or all of the corresponding variables christian-holidays, hebrew-holidays, and islamic-holidays to nil.

You can set the variable other-holidays to any list of holidays. This list, normally empty, is intended for individual use.

Each of the lists (general-holidays, local-holidays, christian-holidays, hebrew-holidays, islamic-holidays, and other-holidays) is a list of holiday forms, each holiday form describing a holiday (or sometimes a list of holidays).

Here is a table of the possible kinds of holiday form. Day numbers and month numbers count starting from 1, but "dayname" numbers count Sunday as 0. The element string is always the name of the holiday, as a string.

(holiday-fixed month day string)
A fixed date on the Gregorian calendar.

(holiday-float month dayname k string)
The kth dayname in month on the Gregorian calendar (dayname=0 for Sunday, and so on); negative k means count back from the end of the month.

(holiday-hebrew month day string)
A fixed date on the Hebrew calendar.

(holiday-islamic month day string)
A fixed date on the Islamic calendar.

(holiday-julian month day string)
A fixed date on the Julian calendar.

(holiday-sexp sexp string)
A date calculated by the Lisp expression sexp. The expression should use the variable year to compute and return the date of a holiday, or nil if the holiday doesn't happen this year. The value of sexp must represent the date as a list of the form (month day year).

(if condition holiday-form)
A holiday that happens only if condition is true.

(function [args])
A list of dates calculated by the function function, called with arguments args.
For example, suppose you want to add Bastille Day, celebrated in France on July 14. You can do this as follows:
(setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
The holiday form (holiday-fixed 7 14 "Bastille Day") specifies the fourteenth day of the seventh month (July).

Many holidays occur on a specific day of the week, at a specific time of month. Here is a holiday form describing Hurricane Supplication Day, celebrated in the Virgin Islands on the fourth Monday in August:
(holiday-float 8 1 4 "Hurricane Supplication Day")
Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in the month (1 specifies the first occurrence, 2 the second occurrence, -1 the last occurrence, -2 the second-to-last occurrence, and so on).

You can specify holidays that occur on fixed days of the Hebrew, Islamic, and Julian calendars too. For example,
(setq other-holidays
      '((holiday-hebrew 10 2 "Last day of Hanukkah")
        (holiday-islamic 3 12 "Mohammed's Birthday")
        (holiday-julian 4 2 "Jefferson's Birthday")))
adds the last day of Hanukkah (since the Hebrew months are numbered with 1 starting from Nisan), the Islamic feast celebrating Mohammed's birthday (since the Islamic months are numbered from 1 starting with Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the Julian calendar.

To include a holiday conditionally, use either Emacs Lisp's if or the holiday-sexp form. For example, American presidential elections occur on the first Tuesday after the first Monday in November of years divisible by 4:
(holiday-sexp (if (= 0 (% year 4))
                   (calendar-gregorian-from-absolute
                    (1+ (calendar-dayname-on-or-before
                          1 (+ 6 (calendar-absolute-from-gregorian
                                  (list 11 1 year))))))
              "US Presidential Election"))
or
(if (= 0 (% displayed-year 4))
    (fixed 11
           (extract-calendar-day
             (calendar-gregorian-from-absolute
               (1+ (calendar-dayname-on-or-before
                     1 (+ 6 (calendar-absolute-from-gregorian
                              (list 11 1 displayed-year)))))))
           "US Presidential Election"))
Some holidays just don't fit into any of these forms because special calculations are involved in their determination. In such cases you must write a Lisp function to do the calculation. To include eclipses, for example, add (eclipses) to other-holidays and write an Emacs Lisp function eclipses that returns a (possibly empty) list of the relevant Gregorian dates among the range visible in the calendar window, with descriptive strings, like this:
(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.3 Date Display Format

You can customize the manner of displaying dates in the diary, in mode lines, and in messages by setting calendar-date-display-form. This variable holds a list of expressions that can involve the variables month, day, and year, which are all numbers in string form, and monthname and dayname, which are both alphabetic strings. In the American style, the default value of this list is as follows:
((if dayname (concat dayname ", ")) monthname " " day ", " year)
while in the European style this value is the default:
((if dayname (concat dayname ", ")) day " " monthname " " year)
The ISO standard date representation is this:
(year "-" month "-" day)
This specifies a typical American format:
(month "/" day "/" (substring year -2))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.4 Time Display Format

The calendar and diary by default display times of day in the conventional American style with the hours from 1 through 12, minutes, and either `am' or `pm'. If you prefer the European style, also known in the US as military, in which the hours go from 00 to 23, you can alter the variable calendar-time-display-form. This variable is a list of expressions that can involve the variables 12-hours, 24-hours, and minutes, which are all numbers in string form, and am-pm and time-zone, which are both alphabetic strings. The default value of calendar-time-display-form is as follows:
(12-hours ":" minutes am-pm
          (if time-zone " (") time-zone (if time-zone ")"))
Here is a value that provides European style times:
(24-hours ":" minutes
          (if time-zone " (") time-zone (if time-zone ")"))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.5 Daylight Savings Time

Emacs understands the difference between standard time and daylight savings time--the times given for sunrise, sunset, solstices, equinoxes, and the phases of the moon take that into account. The rules for daylight savings time vary from place to place and have also varied historically from year to year. To do the job properly, Emacs needs to know which rules to use.

Some operating systems keep track of the rules that apply to the place where you are; on these systems, Emacs gets the information it needs from the system automatically. If some or all of this information is missing, Emacs fills in the gaps with the rules currently used in Cambridge, Massachusetts, which is the center of GNU's world.

If the default choice of rules is not appropriate for your location, you can tell Emacs the rules to use by setting the variables calendar-daylight-savings-starts and calendar-daylight-savings-ends. Their values should be Lisp expressions that refer to the variable year, and evaluate to the Gregorian date on which daylight savings time starts or (respectively) ends, in the form of a list (month day year). The values should be nil if your area does not use daylight savings time.

Emacs uses these expressions to determine the start and end dates of daylight savings time as holidays and for correcting times of day in the solar and lunar calculations.

The values for Cambridge, Massachusetts are as follows:
(calendar-nth-named-day 1 0 4 year)
(calendar-nth-named-day -1 0 10 year)
i.e., the first 0th day (Sunday) of the fourth month (April) in the year specified by year, and the last Sunday of the tenth month (October) of that year. If daylight savings time were changed to start on October 1, you would set calendar-daylight-savings-starts to this:
(list 10 1 year)
For a more complex example, suppose daylight savings time begins on the first of Nisan on the Hebrew calendar. You should set calendar-daylight-savings-starts to this value:
(calendar-gregorian-from-absolute
  (calendar-absolute-from-hebrew
    (list 1 1 (+ year 3760))))
because Nisan is the first month in the Hebrew calendar and the Hebrew year differs from the Gregorian year by 3760 at Nisan.

If there is no daylight savings time at your location, or if you want all times in standard time, set calendar-daylight-savings-starts and calendar-daylight-savings-ends to nil.

The variable calendar-daylight-time-offset specifies the difference between daylight savings time and standard time, measured in minutes. The value for Cambridge is 60.

The variable calendar-daylight-savings-starts-time and the variable calendar-daylight-savings-ends-time specify the number of minutes after midnight local time when the transition to and from daylight savings time should occur. For Cambridge, both variables' values are 120.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.6 Customizing the Diary

Ordinarily, the mode line of the diary buffer window indicates any holidays that fall on the date of the diary entries. The process of checking for holidays can take several seconds, so including holiday information delays the display of the diary buffer noticeably. If you'd prefer to have a faster display of the diary buffer but without the holiday information, set the variable holidays-in-diary-buffer to nil.

The variable number-of-diary-entries controls the number of days of diary entries to be displayed at one time. It affects the initial display when view-diary-entries-initially is t, as well as the command M-x diary. For example, the default value is 1, which says to display only the current day's diary entries. If the value is 2, both the current day's and the next day's entries are displayed. The value can also be a vector of seven elements: for example, if the value is [0 2 2 2 2 4 1] then no diary entries appear on Sunday, the current date's and the next day's diary entries appear Monday through Thursday, Friday through Monday's entries appear on Friday, while on Saturday only that day's entries appear.

The variable print-diary-entries-hook is a normal hook run after preparation of a temporary buffer containing just the diary entries currently visible in the diary buffer. (The other, irrelevant diary entries are really absent from the temporary buffer; in the diary buffer, they are merely hidden.) The default value of this hook does the printing with the command lpr-buffer. If you want to use a different command to do the printing, just change the value of this hook. Other uses might include, for example, rearranging the lines into order by day and time.

You can customize the form of dates in your diary file, if neither the standard American nor European styles suits your needs, by setting the variable diary-date-forms. This variable is a list of patterns for recognizing a date. Each date pattern is a list whose elements may be regular expressions (see section 34.2 Regular Expressions) or the symbols month, day, year, monthname, and dayname. All these elements serve as patterns that match certain kinds of text in the diary file. In order for the date pattern, as a whole, to match, all of its elements must match consecutively.

A regular expression in a date pattern matches in its usual fashion, using the standard syntax table altered so that `*' is a word constituent.

The symbols month, day, year, monthname, and dayname match the month number, day number, year number, month name, and day name of the date being considered. The symbols that match numbers allow leading zeros; those that match names allow three-letter abbreviations and capitalization. All the symbols can match `*'; since `*' in a diary entry means "any day", "any month", and so on, it should match regardless of the date being considered.

The default value of diary-date-forms in the American style is this:
((month "/" day "[^/0-9]")
 (month "/" day "/" year "[^0-9]")
 (monthname " *" day "[^,0-9]")
 (monthname " *" day ", *" year "[^0-9]")
 (dayname "\\W"))
The date patterns in the list must be mutually exclusive and must not match any portion of the diary entry itself, just the date and one character of whitespace. If, to be mutually exclusive, the pattern must match a portion of the diary entry text--beyond the whitespace that ends the date--then the first element of the date pattern must be backup. This causes the date recognizer to back up to the beginning of the current word of the diary entry, after finishing the match. Even if you use backup, the date pattern must absolutely not match more than a portion of the first word of the diary entry. The default value of diary-date-forms in the European style is this list:
((day "/" month "[^/0-9]")
 (day "/" month "/" year "[^0-9]")
 (backup day " *" monthname "\\W+\\<[^*0-9]")
 (day " *" monthname " *" year "[^0-9]")
 (dayname "\\W"))
Notice the use of backup in the third pattern, because it needs to match part of a word beyond the date itself to distinguish it from the fourth pattern.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.7 Hebrew- and Islamic-Date Diary Entries

Your diary file can have entries based on Hebrew or Islamic dates, as well as entries based on the world-standard Gregorian calendar. However, because recognition of such entries is time-consuming and most people don't use them, you must explicitly enable their use. If you want the diary to recognize Hebrew-date diary entries, for example, you must do this:
(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
If you want Islamic-date entries, do this:
(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
Hebrew- and Islamic-date diary entries have the same formats as Gregorian-date diary entries, except that `H' precedes a Hebrew date and `I' precedes an Islamic date. Moreover, because the Hebrew and Islamic month names are not uniquely specified by the first three letters, you may not abbreviate them. For example, a diary entry for the Hebrew date Heshvan 25 could look like this:
HHeshvan 25 Happy Hebrew birthday!
and would appear in the diary for any date that corresponds to Heshvan 25 on the Hebrew calendar. And here is an Islamic-date diary entry that matches Dhu al-Qada 25:
IDhu al-Qada 25 Happy Islamic birthday!
As with Gregorian-date diary entries, Hebrew- and Islamic-date entries are nonmarking if they are preceded with an ampersand (`&').

Here is a table of commands used in the calendar to create diary entries that match the selected date and other dates that are similar in the Hebrew or Islamic calendar:

i h d
Add a diary entry for the Hebrew date corresponding to the selected date (insert-hebrew-diary-entry).
i h m
Add a diary entry for the day of the Hebrew month corresponding to the selected date (insert-monthly-hebrew-diary-entry). This diary entry matches any date that has the same Hebrew day-within-month as the selected date.
i h y
Add a diary entry for the day of the Hebrew year corresponding to the selected date (insert-yearly-hebrew-diary-entry). This diary entry matches any date which has the same Hebrew month and day-within-month as the selected date.
i i d
Add a diary entry for the Islamic date corresponding to the selected date (insert-islamic-diary-entry).
i i m
Add a diary entry for the day of the Islamic month corresponding to the selected date (insert-monthly-islamic-diary-entry).
i i y
Add a diary entry for the day of the Islamic year corresponding to the selected date (insert-yearly-islamic-diary-entry).
These commands work much like the corresponding commands for ordinary diary entries: they apply to the date that point is on in the calendar window, and what they do is insert just the date portion of a diary entry at the end of your diary file. You must then insert the rest of the diary entry.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.8 Fancy Diary Display

Diary display works by preparing the diary buffer and then running the hook diary-display-hook. The default value of this hook (simple-diary-display) hides the irrelevant diary entries and then displays the buffer. However, if you specify the hook as follows,
(add-hook 'diary-display-hook 'fancy-diary-display)
this enables fancy diary display. It displays diary entries and holidays by copying them into a special buffer that exists only for the sake of display. Copying to a separate buffer provides an opportunity to change the displayed text to make it prettier--for example, to sort the entries by the dates they apply to.

As with simple diary display, you can print a hard copy of the buffer with print-diary-entries. To print a hard copy of a day-by-day diary for a week, position point on Sunday of that week, type 7 d, and then do M-x print-diary-entries. As usual, the inclusion of the holidays slows down the display slightly; you can speed things up by setting the variable holidays-in-diary-buffer to nil.

Ordinarily, the fancy diary buffer does not show days for which there are no diary entries, even if that day is a holiday. If you want such days to be shown in the fancy diary buffer, set the variable diary-list-include-blanks to t.

If you use the fancy diary display, you can use the normal hook list-diary-entries-hook to sort each day's diary entries by their time of day. Here's how:
(add-hook 'list-diary-entries-hook 'sort-diary-entries t)
For each day, this sorts diary entries that begin with a recognizable time of day according to their times. Diary entries without times come first within each day.

Fancy diary display also has the ability to process included diary files. This permits a group of people to share a diary file for events that apply to all of them. Lines in the diary file of this form:
#include "filename"
includes the diary entries from the file filename in the fancy diary buffer. The include mechanism is recursive, so that included files can include other files, and so on; you must be careful not to have a cycle of inclusions, of course. Here is how to enable the include facility:
(add-hook 'list-diary-entries-hook 'include-other-diary-files)
(add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
The include mechanism works only with the fancy diary display, because ordinary diary display shows the entries directly from your diary file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.9 Sexp Entries and the Fancy Diary Display

Sexp diary entries allow you to do more than just have complicated conditions under which a diary entry applies. If you use the fancy diary display, sexp entries can generate the text of the entry depending on the date itself. For example, an anniversary diary entry can insert the number of years since the anniversary date into the text of the diary entry. Thus the `%d' in this dairy entry:
%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
gets replaced by the age, so on October 31, 1990 the entry appears in the fancy diary buffer like this:
Arthur's birthday (42 years old)
If the diary file instead contains this entry:
%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
the entry in the fancy diary buffer for October 31, 1990 appears like this:
Arthur's 42nd birthday
Similarly, cyclic diary entries can interpolate the number of repetitions that have occurred:
%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
looks like this:
Renew medication (5th time)
in the fancy diary display on September 8, 1990.

There is an early reminder diary sexp that includes its entry in the diary not only on the date of occurrence, but also on earlier dates. For example, if you want a reminder a week before your anniversary, you can use
%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
and the fancy diary will show
Ed's anniversary
both on December 15 and on December 22.

The function diary-date applies to dates described by a month, day, year combination, each of which can be an integer, a list of integers, or t. The value t means all values. For example,
%%(diary-date '(10 11 12) 22 t) Rake leaves
causes the fancy diary to show
Rake leaves
on October 22, November 22, and December 22 of every year.

The function diary-float allows you to describe diary entries that apply to dates like the third Friday of November, or the last Tuesday in April. The parameters are the month, dayname, and an index n. The entry appears on the nth dayname of month, where dayname=0 means Sunday, 1 means Monday, and so on. If n is negative it counts backward from the end of month. The value of month can be a list of months, a single month, or t to specify all months. You can also use an optional parameter day to specify the nth dayname of month on or after/before day; the value of day defaults to 1 if n is positive and to the last day of month if n is negative. For example,
%%(diary-float t 1 -1) Pay rent
causes the fancy diary to show
Pay rent
on the last Monday of every month.

The generality of sexp diary entries lets you specify any diary entry that you can describe algorithmically. A sexp diary entry contains an expression that computes whether the entry applies to any given date. If its value is non-nil, the entry applies to that date; otherwise, it does not. The expression can use the variable date to find the date being considered; its value is a list (month day year) that refers to the Gregorian calendar.

Suppose you get paid on the 21st of the month if it is a weekday, and on the Friday before if the 21st is on a weekend. Here is how to write a sexp diary entry that matches those dates:
&%%(let ((dayname (calendar-day-of-week date))
         (day (car (cdr date))))
      (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
          (and (memq day '(19 20)) (= dayname 5)))
         ) Pay check deposited
The following sexp diary entries take advantage of the ability (in the fancy diary display) to concoct diary entries whose text varies based on the date:

%%(diary-sunrise-sunset)
Make a diary entry for the local times of today's sunrise and sunset.
%%(diary-phases-of-moon)
Make a diary entry for the phases (quarters) of the moon.
%%(diary-day-of-year)
Make a diary entry with today's day number in the current year and the number of days remaining in the current year.
%%(diary-iso-date)
Make a diary entry with today's equivalent ISO commercial date.
%%(diary-julian-date)
Make a diary entry with today's equivalent date on the Julian calendar.
%%(diary-astro-day-number)
Make a diary entry with today's equivalent astronomical (Julian) day number.
%%(diary-hebrew-date)
Make a diary entry with today's equivalent date on the Hebrew calendar.
%%(diary-islamic-date)
Make a diary entry with today's equivalent date on the Islamic calendar.
%%(diary-french-date)
Make a diary entry with today's equivalent date on the French Revolutionary calendar.
%%(diary-mayan-date)
Make a diary entry with today's equivalent date on the Mayan calendar.
Thus including the diary entry
&%%(diary-hebrew-date)
causes every day's diary display to contain the equivalent date on the Hebrew calendar, if you are using the fancy diary display. (With simple diary display, the line `&%%(diary-hebrew-date)' appears in the diary for any date, but does nothing particularly useful.)

These functions can be used to construct sexp diary entries based on the Hebrew calendar in certain standard ways:

%%(diary-rosh-hodesh)
Make a diary entry that tells the occurrence and ritual announcement of each new Hebrew month.
%%(diary-parasha)
Make a Saturday diary entry that tells the weekly synagogue scripture reading.
%%(diary-sabbath-candles)
Make a Friday diary entry that tells the local time of Sabbath candle lighting.
%%(diary-omer)
Make a diary entry that gives the omer count, when appropriate.
%%(diary-yahrzeit month day year) name
Make a diary entry marking the anniversary of a date of death. The date is the Gregorian (civil) date of death. The diary entry appears on the proper Hebrew calendar anniversary and on the day before. (In the European style, the order of the parameters is changed to day, month, year.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

39.10 Customizing Appointment Reminders

You can specify exactly how Emacs reminds you of an appointment, and how far in advance it begins doing so, by setting these variables:

appt-message-warning-time
The time in minutes before an appointment that the reminder begins. The default is 10 minutes.
appt-audible
If this is non-nil, Emacs rings the terminal bell for appointment reminders. The default is t.
appt-visible
If this is non-nil, Emacs displays the appointment message in the echo area. The default is t.
appt-display-mode-line
If this is non-nil, Emacs displays the number of minutes to the appointment on the mode line. The default is t.
appt-msg-window
If this is non-nil, Emacs displays the appointment message in another window. The default is t.
appt-disp-window-function
This variable holds a function to use to create the other window for the appointment message.
appt-delete-window-function
This variable holds a function to use to get rid of the appointment message window, when its time is up.
appt-display-duration
The number of seconds to display an appointment message. The default is 5 seconds.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40. Operating System Interface

This chapter is about starting and getting out of Emacs, access to values in the operating system environment, and terminal input, output, and flow control.

See section E.1 Building Emacs, for related information. See also 38. Emacs Display, for additional operating system status information pertaining to the terminal and the screen.

40.1 Starting Up Emacs

Customizing Emacs startup processing.

40.2 Getting Out of Emacs

How exiting works (permanent or temporary).

40.3 Operating System Environment

Distinguish the name and kind of system.

40.4 User Identification

Finding the name and user id of the user.

40.5 Time of Day

Getting the current time.

40.6 Time Conversion

Converting a time from numeric form to a string, or to calendrical data (or vice versa).

40.7 Timers for Delayed Execution

Setting a timer to call a function at a certain time.

40.8 Terminal Input

Recording terminal input for debugging.

40.9 Terminal Output

Recording terminal output for debugging.

40.10 Sound Output

Playing sounds on the computer's speaker.

40.11 System-Specific X11 Keysyms

Defining system-specific key symbols for X.

40.12 Flow Control

How to turn output flow control on or off.

40.13 Batch Mode

Running Emacs without terminal interaction.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.1 Starting Up Emacs

This section describes what Emacs does when it is started, and how you can customize these actions.

40.1.1 Summary: Sequence of Actions at Startup

Sequence of actions Emacs performs at startup.

40.1.2 The Init File, `.emacs'

Details on reading the init file (`.emacs').

40.1.3 Terminal-Specific Initialization

How the terminal-specific Lisp file is read.

40.1.4 Command-Line Arguments

How command-line arguments are processed, and how you can customize them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.1.1 Summary: Sequence of Actions at Startup

The order of operations performed (in `startup.el') by Emacs when it is started up is as follows:

It adds subdirectories to load-path, by running the file named `subdirs.el' in each directory in the list. Normally this file adds the directory's subdirectories to the list, and these will be scanned in their turn. The files `subdirs.el' are normally generated automatically by Emacs installation.

It sets the language environment and the terminal coding system, if requested by environment variables such as LANG.

It loads the initialization library for the window system, if you are using a window system. This library's name is `term/windowsystem-win.el'.

It processes the initial options. (Some of them are handled even earlier than this.)

It initializes the window frame and faces, if appropriate.

It runs the normal hook before-init-hook.

It loads the library `site-start', unless the option `-no-site-file' was specified. The library's file name is usually `site-start.el'.

It loads your init file (usually `~/.emacs'), unless `-q', `-no-init-file', or `-batch' was specified on the command line. The `-u' option can specify another user whose home directory should be used instead of `~'.

It loads the library `default', unless inhibit-default-init is non-nil. (This is not done in `-batch' mode or if `-q' was specified on the command line.) The library's file name is usually `default.el'.

It runs the normal hook after-init-hook.

It sets the major mode according to initial-major-mode, provided the buffer `*scratch*' is still current and still in Fundamental mode.

It loads the terminal-specific Lisp file, if any, except when in batch mode or using a window system.

It displays the initial echo area message, unless you have suppressed that with inhibit-startup-echo-area-message.

It processes the action arguments from the command line.

It runs emacs-startup-hook and then term-setup-hook.

It calls frame-notice-user-settings, which modifies the parameters of the selected frame according to whatever the init files specify.

It runs window-setup-hook. See section 38.19 Window Systems.

It displays copyleft, nonwarranty, and basic use information, provided there were no remaining command-line arguments (a few steps above), the value of inhibit-startup-message is nil, and the buffer is still empty.

User Option: inhibit-startup-message
This variable inhibits the initial startup messages (the nonwarranty, etc.). If it is non-nil, then the messages are not printed.

This variable exists so you can set it in your personal init file, once you are familiar with the contents of the startup message. Do not set this variable in the init file of a new user, or in a way that affects more than one user, because that would prevent new users from receiving the information they are supposed to see.

User Option: inhibit-startup-echo-area-message
This variable controls the display of the startup echo area message. You can suppress the startup echo area message by adding text with this form to your init file:
(setq inhibit-startup-echo-area-message
      "your-login-name")
Emacs explicitly checks for an expression as shown above in your init file; your login name must appear in the expression as a Lisp string constant. Other methods of setting inhibit-startup-echo-area-message to the same value do not inhibit the startup message.

This way, you can easily inhibit the message for yourself if you wish, but thoughtless copying of your init file will not inhibit the message for someone else.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.1.2 The Init File, `.emacs'

When you start Emacs, it normally attempts to load your init file, a file in your home directory. Its normal name is `.emacs', but you can alternatively call it `.emacs.el', which enables you to byte-compile it (see section 16. Byte Compilation); then the actual file loaded will be `.emacs.elc'.

The command-line switches `-q' and `-u' control whether and where to find the init file; `-q' says not to load an init file, and `-u user' says to load user's init file instead of yours. See section `Entering Emacs' in The GNU Emacs Manual. If neither option is specified, Emacs uses the LOGNAME environment variable, or the USER (most systems) or USERNAME (MS systems) variable, to find your home directory and thus your init file; this way, even if you have su'd, Emacs still loads your own init file. If those environment variables are absent, though, Emacs uses your user-id to find your home directory.

A site may have a default init file, which is the library named `default.el'. Emacs finds the `default.el' file through the standard search path for libraries (see section 15.1 How Programs Do Loading). The Emacs distribution does not come with this file; sites may provide one for local customizations. If the default init file exists, it is loaded whenever you start Emacs, except in batch mode or if `-q' is specified. But your own personal init file, if any, is loaded first; if it sets inhibit-default-init to a non-nil value, then Emacs does not subsequently load the `default.el' file.

Another file for site-customization is `site-start.el'. Emacs loads this before the user's init file. You can inhibit the loading of this file with the option `-no-site-file'.

Variable: site-run-file
This variable specifies the site-customization file to load before the user's init file. Its normal value is "site-start". The only way you can change it with real effect is to do so before dumping Emacs.

See section `Init File Examples' in The GNU Emacs Manual, for examples of how to make various commonly desired customizations in your `.emacs' file.

User Option: inhibit-default-init
This variable prevents Emacs from loading the default initialization library file for your session of Emacs. If its value is non-nil, then the default library is not loaded. The default value is nil.

Variable: before-init-hook
This normal hook is run, once, just before loading all the init files (the user's init file, `default.el', and/or `site-start.el'). (The only way to change it with real effect is before dumping Emacs.)

Variable: after-init-hook
This normal hook is run, once, just after loading all the init files (the user's init file, `default.el', and/or `site-start.el'), before loading the terminal-specific library and processing the command-line arguments.

Variable: emacs-startup-hook
This normal hook is run, once, just after handling the command line arguments, just before term-setup-hook.

Variable: user-init-file
This variable holds the file name of the user's init file. If the actual init file loaded is a compiled file, such as `.emacs.elc', the value refers to the corresponding source file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.1.3 Terminal-Specific Initialization

Each terminal type can have its own Lisp library that Emacs loads when run on that type of terminal. The library's name is constructed by concatenating the value of the variable term-file-prefix and the terminal type (specified by the environment variable TERM). Normally, term-file-prefix has the value "term/"; changing this is not recommended. Emacs finds the file in the normal manner, by searching the load-path directories, and trying the `.elc' and `.el' suffixes.

The usual function of a terminal-specific library is to enable special keys to send sequences that Emacs can recognize. It may also need to set or add to function-key-map if the Termcap entry does not specify all the terminal's function keys. See section 40.8 Terminal Input.

When the name of the terminal type contains a hyphen, only the part of the name before the first hyphen is significant in choosing the library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use the `term/aaa' library. If necessary, the library can evaluate (getenv "TERM") to find the full name of the terminal type.

Your init file can prevent the loading of the terminal-specific library by setting the variable term-file-prefix to nil. This feature is useful when experimenting with your own peculiar customizations.

You can also arrange to override some of the actions of the terminal-specific library by setting the variable term-setup-hook. This is a normal hook which Emacs runs using run-hooks at the end of Emacs initialization, after loading both your init file and any terminal-specific libraries. You can use this variable to define initializations for terminals that do not have their own libraries. See section 23.6 Hooks.

Variable: term-file-prefix
If the term-file-prefix variable is non-nil, Emacs loads a terminal-specific initialization file as follows:
(load (concat term-file-prefix (getenv "TERM")))
You may set the term-file-prefix variable to nil in your init file if you do not wish to load the terminal-initialization file. To do this, put the following in your init file: (setq term-file-prefix nil).

On MS-DOS, if the environment variable TERM is not set, Emacs uses `internal' as the terminal type.

Variable: term-setup-hook
This variable is a normal hook that Emacs runs after loading your init file, the default initialization file (if any) and the terminal-specific Lisp file.

You can use term-setup-hook to override the definitions made by a terminal-specific file.

See window-setup-hook in 38.19 Window Systems, for a related feature.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.1.4 Command-Line Arguments

You can use command-line arguments to request various actions when you start Emacs. Since you do not need to start Emacs more than once per day, and will often leave your Emacs session running longer than that, command-line arguments are hardly ever used. As a practical matter, it is best to avoid making the habit of using them, since this habit would encourage you to kill and restart Emacs unnecessarily often. These options exist for two reasons: to be compatible with other editors (for invocation by other programs) and to enable shell scripts to run specific Lisp programs.

This section describes how Emacs processes command-line arguments, and how you can customize them.

Function: command-line
This function parses the command line that Emacs was called with, processes it, loads the user's init file and displays the startup messages.

Variable: command-line-processed
The value of this variable is t once the command line has been processed.

If you redump Emacs by calling dump-emacs, you may wish to set this variable to nil first in order to cause the new dumped Emacs to process its new command-line arguments.

Variable: command-switch-alist
The value of this variable is an alist of user-defined command-line options and associated handler functions. This variable exists so you can add elements to it.

A command-line option is an argument on the command line, which has the form:
-option
The elements of the command-switch-alist look like this:
(option . handler-function)
The CAR, option, is a string, the name of a command-line option (not including the initial hyphen). The handler-function is called to handle option, and receives the option name as its sole argument.

In some cases, the option is followed in the command line by an argument. In these cases, the handler-function can find all the remaining command-line arguments in the variable command-line-args-left. (The entire list of command-line arguments is in command-line-args.)

The command-line arguments are parsed by the command-line-1 function in the `startup.el' file. See also section `Command Line Switches and Arguments' in The GNU Emacs Manual.

Variable: command-line-args
The value of this variable is the list of command-line arguments passed to Emacs.

Variable: command-line-functions
This variable's value is a list of functions for handling an unrecognized command-line argument. Each time the next argument to be processed has no special meaning, the functions in this list are called, in order of appearance, until one of them returns a non-nil value.

These functions are called with no arguments. They can access the command-line argument under consideration through the variable argi, which is bound temporarily at this point. The remaining arguments (not including the current one) are in the variable command-line-args-left.

When a function recognizes and processes the argument in argi, it should return a non-nil value to say it has dealt with that argument. If it has also dealt with some of the following arguments, it can indicate that by deleting them from command-line-args-left.

If all of these functions return nil, then the argument is used as a file name to visit.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.2 Getting Out of Emacs

There are two ways to get out of Emacs: you can kill the Emacs job, which exits permanently, or you can suspend it, which permits you to reenter the Emacs process later. As a practical matter, you seldom kill Emacs--only when you are about to log out. Suspending is much more common.

40.2.1 Killing Emacs

Exiting Emacs irreversibly.

40.2.2 Suspending Emacs

Exiting Emacs reversibly.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.2.1 Killing Emacs

Killing Emacs means ending the execution of the Emacs process. The parent process normally resumes control. The low-level primitive for killing Emacs is kill-emacs.

Function: kill-emacs &optional exit-data
This function exits the Emacs process and kills it.

If exit-data is an integer, then it is used as the exit status of the Emacs process. (This is useful primarily in batch operation; see 40.13 Batch Mode.)

If exit-data is a string, its contents are stuffed into the terminal input buffer so that the shell (or whatever program next reads input) can read them.

All the information in the Emacs process, aside from files that have been saved, is lost when the Emacs process is killed. Because killing Emacs inadvertently can lose a lot of work, Emacs queries for confirmation before actually terminating if you have buffers that need saving or subprocesses that are running. This is done in the function save-buffers-kill-emacs.

Variable: kill-emacs-query-functions
After asking the standard questions, save-buffers-kill-emacs calls the functions in the list kill-emacs-query-functions, in order of appearance, with no arguments. These functions can ask for additional confirmation from the user. If any of them returns nil, Emacs is not killed.

Variable: kill-emacs-hook
This variable is a normal hook; once save-buffers-kill-emacs is finished with all file saving and confirmation, it runs the functions in this hook.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.2.2 Suspending Emacs

Suspending Emacs means stopping Emacs temporarily and returning control to its superior process, which is usually the shell. This allows you to resume editing later in the same Emacs process, with the same buffers, the same kill ring, the same undo history, and so on. To resume Emacs, use the appropriate command in the parent shell--most likely fg.

Some operating systems do not support suspension of jobs; on these systems, "suspension" actually creates a new shell temporarily as a subprocess of Emacs. Then you would exit the shell to return to Emacs.

Suspension is not useful with window systems, because the Emacs job may not have a parent that can resume it again, and in any case you can give input to some other job such as a shell merely by moving to a different window. Therefore, suspending is not allowed when Emacs is using a window system (X or MS Windows).

Function: suspend-emacs string
This function stops Emacs and returns control to the superior process. If and when the superior process resumes Emacs, suspend-emacs returns nil to its caller in Lisp.

If string is non-nil, its characters are sent to be read as terminal input by Emacs's superior shell. The characters in string are not echoed by the superior shell; only the results appear.

Before suspending, suspend-emacs runs the normal hook suspend-hook.

After the user resumes Emacs, suspend-emacs runs the normal hook suspend-resume-hook. See section 23.6 Hooks.

The next redisplay after resumption will redraw the entire screen, unless the variable no-redraw-on-reenter is non-nil (see section 38.1 Refreshing the Screen).

In the following example, note that `pwd' is not echoed after Emacs is suspended. But it is read and executed by the shell.
(suspend-emacs)
     => nil

(add-hook 'suspend-hook
          (function (lambda ()
                      (or (y-or-n-p
                            "Really suspend? ")
                          (error "Suspend cancelled")))))
     => (lambda nil
          (or (y-or-n-p "Really suspend? ")
              (error "Suspend cancelled")))
(add-hook 'suspend-resume-hook
          (function (lambda () (message "Resumed!"))))
     => (lambda nil (message "Resumed!"))
(suspend-emacs "pwd")
     => nil
---------- Buffer: Minibuffer ----------
Really suspend? y
---------- Buffer: Minibuffer ----------

---------- Parent Shell ----------
lewis@slug[23] % /user/lewis/manual
lewis@slug[24] % fg

---------- Echo Area ----------
Resumed!
Variable: suspend-hook
This variable is a normal hook that Emacs runs before suspending.

Variable: suspend-resume-hook
This variable is a normal hook that Emacs runs on resuming after a suspension.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.3 Operating System Environment

Emacs provides access to variables in the operating system environment through various functions. These variables include the name of the system, the user's UID, and so on.

Variable: system-configuration
This variable holds the GNU configuration name for the hardware/software configuration of your system, as a string. The convenient way to test parts of this string is with string-match.

Variable: system-type
The value of this variable is a symbol indicating the type of operating system Emacs is operating on. Here is a table of the possible values:

alpha-vms
VMS on the Alpha.

aix-v3
AIX.

berkeley-unix
Berkeley BSD.

dgux
Data General DGUX operating system.

gnu
the GNU system (using the GNU kernel, which consists of the HURD and Mach).

gnu/linux
A GNU/Linux system--that is, a variant GNU system, using the Linux kernel. (These systems are the ones people often call "Linux," but actually Linux is just the kernel, not the whole system.)

hpux
Hewlett-Packard HPUX operating system.

irix
Silicon Graphics Irix system.

ms-dos
Microsoft MS-DOS "operating system." Emacs compiled with DJGPP for MS-DOS binds system-type to ms-dos even when you run it on MS-Windows.

next-mach
NeXT Mach-based system.

rtu
Masscomp RTU, UCB universe.

unisoft-unix
UniSoft UniPlus.

usg-unix-v
AT&T System V.

vax-vms
VAX VMS.

windows-nt
Microsoft windows NT. The same executable supports Windows 9X, but the value of system-type is windows-nt in either case.

xenix
SCO Xenix 386.
We do not wish to add new symbols to make finer distinctions unless it is absolutely necessary! In fact, we hope to eliminate some of these alternatives in the future. We recommend using system-configuration to distinguish between different operating systems.

Function: system-name
This function returns the name of the machine you are running on.
(system-name)
     => "www.gnu.org"
The symbol system-name is a variable as well as a function. In fact, the function returns whatever value the variable system-name currently holds. Thus, you can set the variable system-name in case Emacs is confused about the name of your system. The variable is also useful for constructing frame titles (see section 29.4 Frame Titles).

Variable: mail-host-address
If this variable is non-nil, it is used instead of system-name for purposes of generating email addresses. For example, it is used when constructing the default value of user-mail-address. See section 40.4 User Identification. (Since this is done when Emacs starts up, the value actually used is the one saved when Emacs was dumped. See section E.1 Building Emacs.)

Command: getenv var
This function returns the value of the environment variable var, as a string. Within Emacs, the environment variable values are kept in the Lisp variable process-environment.
(getenv "USER")
     => "lewis"

lewis@slug[10] % printenv
PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
USER=lewis
TERM=ibmapa16
SHELL=/bin/csh
HOME=/user/lewis
Command: setenv variable value
This command sets the value of the environment variable named variable to value. Both arguments should be strings. This function works by modifying process-environment; binding that variable with let is also reasonable practice.

Variable: process-environment
This variable is a list of strings, each describing one environment variable. The functions getenv and setenv work by means of this variable.
process-environment
=> ("l=/usr/stanford/lib/gnuemacs/lisp"
    "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
    "USER=lewis"
    "TERM=ibmapa16"
    "SHELL=/bin/csh"
    "HOME=/user/lewis")
Variable: path-separator
This variable holds a string which says which character separates directories in a search path (as found in an environment variable). Its value is ":" for Unix and GNU systems, and ";" for MS-DOS and MS-Windows.

Function: parse-colon-path path
This function takes a search path string such as would be the value of the PATH environment variable, and splits it at the separators, returning a list of directory names. nil in this list stands for "use the current directory." Although the function's name says "colon," it actually uses the value of path-separator.
(parse-colon-path ":/foo:/bar")
     => (nil "/foo/" "/bar/")
Variable: invocation-name
This variable holds the program name under which Emacs was invoked. The value is a string, and does not include a directory name.

Variable: invocation-directory
This variable holds the directory from which the Emacs executable was invoked, or perhaps nil if that directory cannot be determined.

Variable: installation-directory
If non-nil, this is a directory within which to look for the `lib-src' and `etc' subdirectories. This is non-nil when Emacs can't find those directories in their standard installed locations, but can find them in a directory related somehow to the one containing the Emacs executable.

Function: load-average &optional use-float
This function returns the current 1-minute, 5-minute, and 15-minute load averages, in a list.

By default, the values are integers that are 100 times the system load averages, which indicate the average number of processes trying to run. If use-float is non-nil, then they are returned as floating point numbers and without multiplying by 100.
(load-average)
     => (169 48 36)
(load-average t)
     => (1.69 0.48 0.36)

lewis@rocky[5] % uptime
 11:55am  up 1 day, 19:37,  3 users,
 load average: 1.69, 0.48, 0.36
Function: emacs-pid
This function returns the process ID of the Emacs process.

Variable: tty-erase-char
This variable holds the erase character that was selected in the system's terminal driver, before Emacs was started.

Function: setprv privilege-name &optional setp getprv
This function sets or resets a VMS privilege. (It does not exist on other systems.) The first argument is the privilege name, as a string. The second argument, setp, is t or nil, indicating whether the privilege is to be turned on or off. Its default is nil. The function returns t if successful, nil otherwise.

If the third argument, getprv, is non-nil, setprv does not change the privilege, but returns t or nil indicating whether the privilege is currently enabled.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.4 User Identification

Variable: init-file-user
This variable says which user's init files should be used by Emacs--or nil if none. The value reflects command-line options such as `-q' or `-u user'.

Lisp packages that load files of customizations, or any other sort of user profile, should obey this variable in deciding where to find it. They should load the profile of the user name found in this variable. If init-file-user is nil, meaning that the `-q' option was used, then Lisp packages should not load any customization files or user profile.

Variable: user-mail-address
This holds the nominal email address of the user who is using Emacs. Emacs normally sets this variable to a default value after reading your init files, but not if you have already set it. So you can set the variable to some other value in your init file if you do not want to use the default value.

Function: user-login-name &optional uid
If you don't specify uid, this function returns the name under which the user is logged in. If the environment variable LOGNAME is set, that value is used. Otherwise, if the environment variable USER is set, that value is used. Otherwise, the value is based on the effective UID, not the real UID.

If you specify uid, the value is the user name that corresponds to uid (which should be an integer).
(user-login-name)
     => "lewis"
Function: user-real-login-name
This function returns the user name corresponding to Emacs's real UID. This ignores the effective UID and ignores the environment variables LOGNAME and USER.

Function: user-full-name &optional uid
This function returns the full name of the logged-in user--or the value of the environment variable NAME, if that is set.
(user-full-name)
     => "Bil Lewis"
If the Emacs job's user-id does not correspond to any known user (and provided NAME is not set), the value is "unknown".

If uid is non-nil, then it should be an integer (a user-id) or a string (a login name). Then user-full-name returns the full name corresponding to that user-id or login name. If you specify a user-id or login name that isn't defined, it returns nil.

The symbols user-login-name, user-real-login-name and user-full-name are variables as well as functions. The functions return the same values that the variables hold. These variables allow you to "fake out" Emacs by telling the functions what to return. The variables are also useful for constructing frame titles (see section 29.4 Frame Titles).

Function: user-real-uid
This function returns the real UID of the user.
(user-real-uid)
     => 19
Function: user-uid
This function returns the effective UID of the user.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.5 Time of Day

This section explains how to determine the current time and the time zone.

Function: current-time-string &optional time-value
This function returns the current time and date as a human-readable string. The format of the string is unvarying; the number of characters used for each part is always the same, so you can reliably use substring to extract pieces of it. It is wise to count the characters from the beginning of the string rather than from the end, as additional information may some day be added at the end.

The argument time-value, if given, specifies a time to format instead of the current time. The argument should be a list whose first two elements are integers. Thus, you can use times obtained from current-time (see below) and from file-attributes (see section 25.6.4 Other Information about Files).
(current-time-string)
     => "Wed Oct 14 22:21:05 1987"
Function: current-time
This function returns the system's time value as a list of three integers: (high low microsec). The integers high and low combine to give the number of seconds since 0:00 January 1, 1970 (local time), which is high * 2**16 + low.

The third element, microsec, gives the microseconds since the start of the current second (or 0 for systems that return time with the resolution of only one second).

The first two elements can be compared with file time values such as you get with the function file-attributes. See section 25.6.4 Other Information about Files.

Function: current-time-zone &optional time-value
This function returns a list describing the time zone that the user is in.

The value has the form (offset name). Here offset is an integer giving the number of seconds ahead of UTC (east of Greenwich). A negative value means west of Greenwich. The second element, name, is a string giving the name of the time zone. Both elements change when daylight savings time begins or ends; if the user has specified a time zone that does not use a seasonal time adjustment, then the value is constant through time.

If the operating system doesn't supply all the information necessary to compute the value, both elements of the list are nil.

The argument time-value, if given, specifies a time to analyze instead of the current time. The argument should be a cons cell containing two integers, or a list whose first two elements are integers. Thus, you can use times obtained from current-time (see above) and from file-attributes (see section 25.6.4 Other Information about Files).

Function: float-time &optional time-value
This function returns the current time as a floating-point number of seconds since the epoch. The argument time-value, if given, specifies a time to convert instead of the current time. The argument should have the same form as for current-time-string (see above), and it also accepts the output of current-time and file-attributes.

Warning: Since the result is floating point, it may not be exact. Do not use this function if precise time stamps are required.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.6 Time Conversion

These functions convert time values (lists of two or three integers) to strings or to calendrical information. There is also a function to convert calendrical information to a time value. You can get time values from the functions current-time (see section 40.5 Time of Day) and file-attributes (see section 25.6.4 Other Information about Files).

Many operating systems are limited to time values that contain 32 bits of information; these systems typically handle only the times from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some operating systems have larger time values, and can represent times far in the past or future.

Time conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers count the number of years since the year 1 B.C., and do not skip zero as traditional Gregorian years do; for example, the year number -37 represents the Gregorian year 38 B.C.

Function: format-time-string format-string &optional time universal
This function converts time (or the current time, if time is omitted) to a string according to format-string. The argument format-string may contain `%'-sequences which say to substitute parts of the time. Here is a table of what the `%'-sequences mean:

`%a'
This stands for the abbreviated name of the day of week.
`%A'
This stands for the full name of the day of week.
`%b'
This stands for the abbreviated name of the month.
`%B'
This stands for the full name of the month.
`%c'
This is a synonym for `%x %X'.
`%C'
This has a locale-specific meaning. In the default locale (named C), it is equivalent to `%A, %B %e, %Y'.
`%d'
This stands for the day of month, zero-padded.
`%D'
This is a synonym for `%m/%d/%y'.
`%e'
This stands for the day of month, blank-padded.
`%h'
This is a synonym for `%b'.
`%H'
This stands for the hour (00-23).
`%I'
This stands for the hour (01-12).
`%j'
This stands for the day of the year (001-366).
`%k'
This stands for the hour (0-23), blank padded.
`%l'
This stands for the hour (1-12), blank padded.
`%m'
This stands for the month (01-12).
`%M'
This stands for the minute (00-59).
`%n'
This stands for a newline.
`%p'
This stands for `AM' or `PM', as appropriate.
`%r'
This is a synonym for `%I:%M:%S %p'.
`%R'
This is a synonym for `%H:%M'.
`%S'
This stands for the seconds (00-59).
`%t'
This stands for a tab character.
`%T'
This is a synonym for `%H:%M:%S'.
`%U'
This stands for the week of the year (01-52), assuming that weeks start on Sunday.
`%w'
This stands for the numeric day of week (0-6). Sunday is day 0.
`%W'
This stands for the week of the year (01-52), assuming that weeks start on Monday.
`%x'
This has a locale-specific meaning. In the default locale (named `C'), it is equivalent to `%D'.
`%X'
This has a locale-specific meaning. In the default locale (named `C'), it is equivalent to `%T'.
`%y'
This stands for the year without century (00-99).
`%Y'
This stands for the year with century.
`%Z'
This stands for the time zone abbreviation.
You can also specify the field width and type of padding for any of these `%'-sequences. This works as in printf: you write the field width as digits in the middle of a `%'-sequences. If you start the field width with `0', it means to pad with zeros. If you start the field width with `_', it means to pad with spaces.

For example, `%S' specifies the number of seconds since the minute; `%03S' means to pad this with zeros to 3 positions, `%_3S' to pad with spaces to 3 positions. Plain `%3S' pads with zeros, because that is how `%S' normally pads to two positions.

The characters `E' and `O' act as modifiers when used between `%' and one of the letters in the table above. `E' specifies using the current locale's "alternative" version of the date and time. In a Japanese locale, for example, %Ex might yield a date format based on the Japanese Emperors' reigns. `E' is allowed in `%Ec', `%EC', `%Ex', `%EX', `%Ey', and `%EY'.

`O' means to use the current locale's "alternative" representation of numbers, instead of the ordinary decimal digits. This is allowed with most letters, all the ones that output numbers.

If universal is non-nil, that means to describe the time as Universal Time; nil means describe it using what Emacs believes is the local time zone (see current-time-zone).

This function uses the C library function strftime to do most of the work. In order to communicate with that function, it first encodes its argument using the coding system specified by locale-coding-system (see section 33.12 Locales); after strftime returns the resulting string, format-time-string decodes the string using that same coding system.

Function: decode-time time
This function converts a time value into calendrical information. The return value is a list of nine elements, as follows:
(seconds minutes hour day month year dow dst zone)
Here is what the elements mean:

seconds
The number of seconds past the minute, as an integer between 0 and 59.
minutes
The number of minutes past the hour, as an integer between 0 and 59.
hour
The hour of the day, as an integer between 0 and 23.
day
The day of the month, as an integer between 1 and 31.
month
The month of the year, as an integer between 1 and 12.
year
The year, an integer typically greater than 1900.
dow
The day of week, as an integer between 0 and 6, where 0 stands for Sunday.
dst
t if daylight savings time is effect, otherwise nil.
zone
An integer indicating the time zone, as the number of seconds east of Greenwich.
Common Lisp Note: Common Lisp has different meanings for dow and zone.

Function: encode-time seconds minutes hour day month year &optional zone
This function is the inverse of decode-time. It converts seven items of calendrical data into a time value. For the meanings of the arguments, see the table above under decode-time.

Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call encode-time.

The optional argument zone defaults to the current time zone and its daylight savings time rules. If specified, it can be either a list (as you would get from current-time-zone), a string as in the TZ environment variable, or an integer (as you would get from decode-time). The specified zone is used without any further alteration for daylight savings time.

If you pass more than seven arguments to encode-time, the first six are used as seconds through year, the last argument is used as zone, and the arguments in between are ignored. This feature makes it possible to use the elements of a list returned by decode-time as the arguments to encode-time, like this:
(apply 'encode-time (decode-time ...))
You can perform simple date arithmetic by using out-of-range values for the seconds, minutes, hour, day, and month arguments; for example, day 0 means the day preceding the given month.

The operating system puts limits on the range of possible time values; if you try to encode a time that is out of range, an error results.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.7 Timers for Delayed Execution

You can set up a timer to call a function at a specified future time or after a certain length of idleness.

Emacs cannot run timers at any arbitrary point in a Lisp program; it can run them only when Emacs could accept output from a subprocess: namely, while waiting or inside certain primitive functions such as sit-for or read-event which can wait. Therefore, a timer's execution may be delayed if Emacs is busy. However, the time of execution is very precise if Emacs is idle.

Function: run-at-time time repeat function &rest args
This function arranges to call function with arguments args at time time. The argument function is a function to call later, and args are the arguments to give it when it is called. The time time is specified as a string.

Absolute times may be specified in a wide variety of formats; this function tries to accept all the commonly used date formats. Valid formats include these two,
year-month-day hour:min:sec timezone

hour:min:sec timezone month/day/year
where in both examples all fields are numbers; the format that current-time-string returns is also allowed, and many others as well.

To specify a relative time, use numbers followed by units. For example:

`1 min'
denotes 1 minute from now.
`1 min 5 sec'
denotes 65 seconds from now.
`1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year'
denotes exactly 103 months, 123 days, and 10862 seconds from now.
For relative time values, Emacs considers a month to be exactly thirty days, and a year to be exactly 365.25 days.

If time is a number (integer or floating point), that specifies a relative time measured in seconds.

The argument repeat specifies how often to repeat the call. If repeat is nil, there are no repetitions; function is called just once, at time. If repeat is a number, it specifies a repetition period measured in seconds.

In most cases, repeat has no effect on when first call takes place---time alone specifies that. There is one exception: if time is t, then the timer runs whenever the time is a multiple of repeat seconds after the epoch. This is useful for functions like display-time.

The function run-at-time returns a timer value that identifies the particular scheduled future action. You can use this value to call cancel-timer (see below).

Macro: with-timeout (seconds timeout-forms...) body...
Execute body, but give up after seconds seconds. If body finishes before the time is up, with-timeout returns the value of the last form in body. If, however, the execution of body is cut short by the timeout, then with-timeout executes all the timeout-forms and returns the value of the last of them.

This macro works by setting a timer to run after seconds seconds. If body finishes before that time, it cancels the timer. If the timer actually runs, it terminates execution of body, then executes timeout-forms.

Since timers can run within a Lisp program only when the program calls a primitive that can wait, with-timeout cannot stop executing body while it is in the midst of a computation--only when it calls one of those primitives. So use with-timeout only with a body that waits for input, not one that does a long computation.

The function y-or-n-p-with-timeout provides a simple way to use a timer to avoid waiting too long for an answer. See section 20.6 Yes-or-No Queries.

Function: run-with-idle-timer secs repeat function &rest args
Set up a timer which runs when Emacs has been idle for secs seconds. The value of secs may be an integer or a floating point number.

If repeat is nil, the timer runs just once, the first time Emacs remains idle for a long enough time. More often repeat is non-nil, which means to run the timer each time Emacs remains idle for secs seconds.

The function run-with-idle-timer returns a timer value which you can use in calling cancel-timer (see below).

Emacs becomes "idle" when it starts waiting for user input, and it remains idle until the user provides some input. If a timer is set for five seconds of idleness, it runs approximately five seconds after Emacs first becomes idle. Even if repeat is non-nil, this timer will not run again as long as Emacs remains idle, because the duration of idleness will continue to increase and will not go down to five seconds again.

Emacs can do various things while idle: garbage collect, autosave or handle data from a subprocess. But these interludes during idleness do not interfere with idle timers, because they do not reset the clock of idleness to zero. An idle timer set for 600 seconds will run when ten minutes have elapsed since the last user command was finished, even if subprocess output has been accepted thousands of times within those ten minutes, and even if there have been garbage collections and autosaves.

When the user supplies input, Emacs becomes non-idle while executing the input. Then it becomes idle again, and all the idle timers that are set up to repeat will subsequently run another time, one by one.

Function: cancel-timer timer
Cancel the requested action for timer, which should be a value previously returned by run-at-time or run-with-idle-timer. This cancels the effect of that call to run-at-time; the arrival of the specified time will not cause anything special to happen.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.8 Terminal Input

This section describes functions and variables for recording or manipulating terminal input. See 38. Emacs Display, for related functions.

40.8.1 Input Modes

Options for how input is processed.

40.8.2 Translating Input Events

Low level conversion of some characters or events into others.

40.8.3 Recording Input

Saving histories of recent or all input events.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.8.1 Input Modes

Function: set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input. If interrupt is non-null, then Emacs uses input interrupts. If it is nil, then it uses CBREAK mode. The default setting is system-dependent. Some systems always use CBREAK mode regardless of what is specified.

When Emacs communicates directly with X, it ignores this argument and uses interrupts if that is the way it knows how to communicate.

If flow is non-nil, then Emacs uses XON/XOFF (C-q, C-s) flow control for output to the terminal. This has no effect except in CBREAK mode. See section 40.12 Flow Control.

The argument meta controls support for input character codes above 127. If meta is t, Emacs converts characters with the 8th bit set into Meta characters. If meta is nil, Emacs disregards the 8th bit; this is necessary when the terminal uses it as a parity bit. If meta is neither t nor nil, Emacs uses all 8 bits of input unchanged. This is good for terminals that use 8-bit character sets.

If quit-char is non-nil, it specifies the character to use for quitting. Normally this character is C-g. See section 21.10 Quitting.

The current-input-mode function returns the input mode settings Emacs is currently using.

Function: current-input-mode
This function returns the current mode for reading keyboard input. It returns a list, corresponding to the arguments of set-input-mode, of the form (interrupt flow meta quit) in which:
interrupt
is non-nil when Emacs is using interrupt-driven input. If nil, Emacs is using CBREAK mode.
flow
is non-nil if Emacs uses XON/XOFF (C-q, C-s) flow control for output to the terminal. This value is meaningful only when interrupt is nil.
meta
is t if Emacs treats the eighth bit of input characters as the meta bit; nil means Emacs clears the eighth bit of every input character; any other value means Emacs uses all eight bits as the basic character code.
quit
is the character Emacs currently uses for quitting, usually C-g.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.8.2 Translating Input Events

This section describes features for translating input events into other input events before they become part of key sequences. These features apply to each event in the order they are described here: each event is first modified according to extra-keyboard-modifiers, then translated through keyboard-translate-table (if applicable), and finally decoded with the specified keyboard coding system. If it is being read as part of a key sequence, it is then added to the sequence being read; then subsequences containing it are checked first with function-key-map and then with key-translation-map.

Variable: extra-keyboard-modifiers
This variable lets Lisp programs "press" the modifier keys on the keyboard. The value is a bit mask:

1
The SHIFT key.
2
The LOCK key.
4
The CTL key.
8
The META key.
Each time the user types a keyboard key, it is altered as if the modifier keys specified in the bit mask were held down.

When using a window system, the program can "press" any of the modifier keys in this way. Otherwise, only the CTL and META keys can be virtually pressed.

Variable: keyboard-translate-table
This variable is the translate table for keyboard characters. It lets you reshuffle the keys on the keyboard without changing any command bindings. Its value is normally a char-table, or else nil.

If keyboard-translate-table is a char-table (see section 6.6 Char-Tables), then each character read from the keyboard is looked up in this char-table. If the value found there is non-nil, then it is used instead of the actual input character.

In the example below, we set keyboard-translate-table to a char-table. Then we fill it in to swap the characters C-s and C-\ and the characters C-q and C-^. Subsequently, typing C-\ has all the usual effects of typing C-s, and vice versa. (See section 40.12 Flow Control, for more information on this subject.)
(defun evade-flow-control ()
  "Replace C-s with C-\ and C-q with C-^."
  (interactive)
  (setq keyboard-translate-table
        (make-char-table 'keyboard-translate-table nil))
  ;; Swap C-s and C-\.
  (aset keyboard-translate-table ?\034 ?\^s)
  (aset keyboard-translate-table ?\^s ?\034)
  ;; Swap C-q and C-^.
  (aset keyboard-translate-table ?\036 ?\^q)
  (aset keyboard-translate-table ?\^q ?\036))
Note that this translation is the first thing that happens to a character after it is read from the terminal. Record-keeping features such as recent-keys and dribble files record the characters after translation.

Function: keyboard-translate from to
This function modifies keyboard-translate-table to translate character code from into character code to. It creates the keyboard translate table if necessary.

The remaining translation features translate subsequences of key sequences being read. They are implemented in read-key-sequence and have no effect on input read with read-event.

Variable: function-key-map
This variable holds a keymap that describes the character sequences sent by function keys on an ordinary character terminal. This keymap has the same structure as other keymaps, but is used differently: it specifies translations to make while reading key sequences, rather than bindings for key sequences.

If function-key-map "binds" a key sequence k to a vector v, then when k appears as a subsequence anywhere in a key sequence, it is replaced with the events in v.

For example, VT100 terminals send ESC O P when the keypad PF1 key is pressed. Therefore, we want Emacs to translate that sequence of events into the single event pf1. We accomplish this by "binding" ESC O P to [pf1] in function-key-map, when using a VT100.

Thus, typing C-c PF1 sends the character sequence C-c ESC O P; later the function read-key-sequence translates this back into C-c PF1, which it returns as the vector [?\C-c pf1].

Entries in function-key-map are ignored if they conflict with bindings made in the minor mode, local, or global keymaps. The intent is that the character sequences that function keys send should not have command bindings in their own right--but if they do, the ordinary bindings take priority.

The value of function-key-map is usually set up automatically according to the terminal's Terminfo or Termcap entry, but sometimes those need help from terminal-specific Lisp files. Emacs comes with terminal-specific files for many common terminals; their main purpose is to make entries in function-key-map beyond those that can be deduced from Termcap and Terminfo. See section 40.1.3 Terminal-Specific Initialization.

Variable: key-translation-map
This variable is another keymap used just like function-key-map to translate input events into other events. It differs from function-key-map in two ways:

key-translation-map goes to work after function-key-map is finished; it receives the results of translation by function-key-map.

key-translation-map overrides actual key bindings. For example, if C-x f has a binding in key-translation-map, that translation takes effect even though C-x f also has a key binding in the global map.

The intent of key-translation-map is for users to map one character set to another, including ordinary characters normally bound to self-insert-command.

You can use function-key-map or key-translation-map for more than simple aliases, by using a function, instead of a key sequence, as the "translation" of a key. Then this function is called to compute the translation of that key.

The key translation function receives one argument, which is the prompt that was specified in read-key-sequence---or nil if the key sequence is being read by the editor command loop. In most cases you can ignore the prompt value.

If the function reads input itself, it can have the effect of altering the event that follows. For example, here's how to define C-c h to turn the character that follows into a Hyper character:
(defun hyperify (prompt)
  (let ((e (read-event)))
    (vector (if (numberp e)
                (logior (lsh 1 24) e)
              (if (memq 'hyper (event-modifiers e))
                  e
                (add-event-modifier "H-" e))))))

(defun add-event-modifier (string e)
  (let ((symbol (if (symbolp e) e (car e))))
    (setq symbol (intern (concat string
                                 (symbol-name symbol))))
    (if (symbolp e)
        symbol
      (cons symbol (cdr e)))))

(define-key function-key-map "\C-ch" 'hyperify)
Finally, if you have enabled keyboard character set decoding using set-keyboard-coding-system, decoding is done after the translations listed above. See section 33.10.6 Specifying a Coding System for One Operation. In future Emacs versions, character set decoding may be done before the other translations.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.8.3 Recording Input

Function: recent-keys
This function returns a vector containing the last 100 input events from the keyboard or mouse. All input events are included, whether or not they were used as parts of key sequences. Thus, you always get the last 100 input events, not counting events generated by keyboard macros. (These are excluded because they are less interesting for debugging; it should be enough to see the events that invoked the macros.)

A call to clear-this-command-keys (see section 21.4 Information from the Command Loop) causes this function to return an empty vector immediately afterward.

Command: open-dribble-file filename
This function opens a dribble file named filename. When a dribble file is open, each input event from the keyboard or mouse (but not those from keyboard macros) is written in that file. A non-character event is expressed using its printed representation surrounded by `<...>'.

You close the dribble file by calling this function with an argument of nil.

This function is normally used to record the input necessary to trigger an Emacs bug, for the sake of a bug report.
(open-dribble-file "~/dribble")
     => nil
See also the open-termscript function (see section 40.9 Terminal Output).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.9 Terminal Output

The terminal output functions send output to the terminal, or keep track of output sent to the terminal. The variable baud-rate tells you what Emacs thinks is the output speed of the terminal.

Variable: baud-rate
This variable's value is the output speed of the terminal, as far as Emacs knows. Setting this variable does not change the speed of actual data transmission, but the value is used for calculations such as padding. It also affects decisions about whether to scroll part of the screen or repaint--even when using a window system. (We designed it this way despite the fact that a window system has no true "output speed", to give you a way to tune these decisions.)

The value is measured in baud.

If you are running across a network, and different parts of the network work at different baud rates, the value returned by Emacs may be different from the value used by your local terminal. Some network protocols communicate the local terminal speed to the remote machine, so that Emacs and other programs can get the proper value, but others do not. If Emacs has the wrong value, it makes decisions that are less than optimal. To fix the problem, set baud-rate.

Function: baud-rate
This obsolete function returns the value of the variable baud-rate.

Function: send-string-to-terminal string
This function sends string to the terminal without alteration. Control characters in string have terminal-dependent effects.

One use of this function is to define function keys on terminals that have downloadable function key definitions. For example, this is how (on certain terminals) to define function key 4 to move forward four characters (by transmitting the characters C-u C-f to the computer):
(send-string-to-terminal "\eF4\^U\^F")
     => nil
Command: open-termscript filename
This function is used to open a termscript file that will record all the characters sent by Emacs to the terminal. It returns nil. Termscript files are useful for investigating problems where Emacs garbles the screen, problems that are due to incorrect Termcap entries or to undesirable settings of terminal options more often than to actual Emacs bugs. Once you are certain which characters were actually output, you can determine reliably whether they correspond to the Termcap specifications in use.

See also open-dribble-file in 40.8 Terminal Input.
(open-termscript "../junk/termscript")
     => nil
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.10 Sound Output

To play sound using Emacs, use the function play-sound. Only certain systems are supported; if you call play-sound on a system which cannot really do the job, it gives an error. Emacs version 20 and earlier did not support sound at all.

The sound must be stored as a file in RIFF-WAVE format (`.wav') or Sun Audio format (`.au').

Function: play-sound sound
This function plays a specified sound. The argument, sound, has the form (sound properties...), where the properties consist of alternating keywords (particular symbols recognized specially) and values corresponding to them.

Here is a table of the keywords that are currently meaningful in sound, and their meanings:

:file file
This specifies the file containing the sound to play. If the file name is not absolute, it is expanded against the directory data-directory.

:data data
This specifies the sound to play without need to refer to a file. The value, data, should be a string containing the same bytes as a sound file. We recommend using a unibyte string.

:volume volume
This specifies how loud to play the sound. It should be a number in the range of 0 to 1. The default is to use whatever volume has been specified before.

:device device
This specifies the system device on which to play the sound, as a string. The default device is system-dependent.
Before actually playing the sound, play-sound calls the functions in the list play-sound-functions. Each function is called with one argument, sound.

Function: play-sound-file file &optional volume device
This function is an alternative interface to playing a sound file specifying an optional volume and device.

Variable: play-sound-functions
A list of functions to be called before playing a sound. Each function is called with one argument, a property list that describes the sound.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.11 System-Specific X11 Keysyms

To define system-specific X11 keysyms, set the variable system-key-alist.

Variable: system-key-alist
This variable's value should be an alist with one element for each system-specific keysym. Each element has the form (code . symbol), where code is the numeric keysym code (not including the "vendor specific" bit, -2**28), and symbol is the name for the function key.

For example (168 . mute-acute) defines a system-specific key (used by HP X servers) whose numeric code is -2**28 + 168.

It is not crucial to exclude from the alist the keysyms of other X servers; those do no harm, as long as they don't conflict with the ones used by the X server actually in use.

The variable is always local to the current terminal, and cannot be buffer-local. See section 29.2 Multiple Displays.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.12 Flow Control

This section attempts to answer the question "Why does Emacs use flow-control characters in its command character set?" For a second view on this issue, read the comments on flow control in the `emacs/INSTALL' file from the distribution; for help with Termcap entries and DEC terminal concentrators, see `emacs/etc/TERMS'.

At one time, most terminals did not need flow control, and none used C-s and C-q for flow control. Therefore, the choice of C-s and C-q as command characters for searching and quoting was natural and uncontroversial. With so many commands needing key assignments, of course we assigned meanings to nearly all ASCII control characters.

Later, some terminals were introduced which required these characters for flow control. They were not very good terminals for full-screen editing, so Emacs maintainers ignored them. In later years, flow control with C-s and C-q became widespread among terminals, but by this time it was usually an option. And the majority of Emacs users, who can turn flow control off, did not want to switch to less mnemonic key bindings for the sake of flow control.

So which usage is "right"---Emacs's or that of some terminal and concentrator manufacturers? This question has no simple answer.

One reason why we are reluctant to cater to the problems caused by C-s and C-q is that they are gratuitous. There are other techniques (albeit less common in practice) for flow control that preserve transparency of the character stream. Note also that their use for flow control is not an official standard. Interestingly, on the model 33 teletype with a paper tape punch (around 1970), C-s and C-q were sent by the computer to turn the punch on and off!

As window systems and PC terminal emulators replace character-only terminals, the flow control problem is gradually disappearing. For the mean time, Emacs provides a convenient way of enabling flow control if you want it: call the function enable-flow-control.

Command: enable-flow-control
This function enables use of C-s and C-q for output flow control, and provides the characters C-\ and C-^ as aliases for them using keyboard-translate-table (see section 40.8.2 Translating Input Events).

You can use the function enable-flow-control-on in your init file to enable flow control automatically on certain terminal types.

Function: enable-flow-control-on &rest termtypes
This function enables flow control, and the aliases C-\ and C-^, if the terminal type is one of termtypes. For example:
(enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
Here is how enable-flow-control does its job:

It sets CBREAK mode for terminal input, and tells the operating system to handle flow control, with (set-input-mode nil t).

It sets up keyboard-translate-table to translate C-\ and C-^ into C-s and C-q. Except at its very lowest level, Emacs never knows that the characters typed were anything but C-s and C-q, so you can in effect type them as C-\ and C-^ even when they are input for other commands. See section 40.8.2 Translating Input Events.

If the terminal is the source of the flow control characters, then once you enable kernel flow control handling, you probably can make do with less padding than normal for that terminal. You can reduce the amount of padding by customizing the Termcap entry. You can also reduce it by setting baud-rate to a smaller value so that Emacs uses a smaller speed when calculating the padding needed. See section 40.9 Terminal Output.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

40.13 Batch Mode

The command-line option `-batch' causes Emacs to run noninteractively. In this mode, Emacs does not read commands from the terminal, it does not alter the terminal modes, and it does not expect to be outputting to an erasable screen. The idea is that you specify Lisp programs to run; when they are finished, Emacs should exit. The way to specify the programs to run is with `-l file', which loads the library named file, and `-f function', which calls function with no arguments.

Any Lisp program output that would normally go to the echo area, either using message, or using prin1, etc., with t as the stream, goes instead to Emacs's standard error descriptor when in batch mode. Similarly, input that would normally come from the minibuffer is read from the standard input descriptor. Thus, Emacs behaves much like a noninteractive application program. (The echo area output that Emacs itself normally generates, such as command echoing, is suppressed entirely.)

Variable: noninteractive
This variable is non-nil when Emacs is running in batch mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

A. Emacs 20 Antinews

For those users who live backwards in time, here is information about downgrading to Emacs version 20.4. We hope you will enjoy the greater simplicity that results from the absence of many Emacs 21 features. In the following section, we carry this information back to Emacs 20.3, for which the previous printed edition of this manual was made.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

A.1 Old Lisp Features in Emacs 20

The push and pop macros are not defined. Neither are dolist and dotimes.

You can't display images in buffers. (Emacs is meant for editing text.) With no images, there are no display margins, and no tool bars.

The display text property has no special meaning; you can use it freely in Lisp programs, with no effects except what you implement for yourself. With no images, who needs the display text property?

The field text property has no special meaning; buffers are no longer subdivided into fields. (The division of information into fields is always rather arbitrary.)

Faces have fewer attributes. The attributes :family, :height, :width, :weight, and :slant, have been replaced with a font name, a "bold" flag, and an "italic" flag.
The attributes :overline, :strike-through and :box have been eliminated too. Underlining now always has the same color as the text--using any other color would be bad taste.

With fewer font attributes, there are no functions set-face-attribute and face-attribute. Instead, you access these attributes using functions such as face-font, and set them with functions such as set-face-font. (These functions were available in Emacs 21, but are not as useful there.)

The standard faces scroll-bar, menu, border, cursor, and mouse have been eliminated. They are rather strange, as faces, and therefore shouldn't really exist. You can use set-border-color, set-cursor-color and set-mouse-color to specify the colors for the frame border, the text cursor, and the mouse cursor. To specify menu colors, use X resources.

Colors and other face attributes are no longer supported on character terminals, so you no longer have to worry about terminals making faces at you.

Emacs will respect your peace and quiet, aside from occasional beeps, because there are no facilities for playing sounds.

Emacs 20 provides a complex and badly designed method for handling character composition for languages such as Thai that display several letters as a single combined image. We are too ashamed of it to tell you any more than that.

delete-and-extract-region has been deleted; instead, use buffer-substring to extract the text, then use delete-region to delete it.

Regular expressions do not support the POSIX character classes such as `[:alpha:]'. All characters are created equal.

Hash tables have been eliminated; use alists instead.

The Lisp printer does not detect and report circular structure. That is ok, because the Lisp reader cannot recreate circular structure anyway. However, there is a library `cust-print.el' which can report circular structure.

Emacs provides its own implementation of scroll bars, instead of using those of the X toolkit. They always use the frame foreground and background colors, so you cannot specify different colors for the scroll bars.

For simplicity, all ASCII characters now have the same height and width. (Certain characters, such as Chinese characters, always have twice the standard width.) All characters are created equal.

You can now resize any Emacs window, and size changes in one window can propagate to all others. Windows can no longer use window-size-fixed to get special privileges.

The function intern-soft no longer accepts a symbol as argument.

The function bitmap-spec-p has been renamed to pixmap-spec-p to encourage users to practice Emacs' help system while trying to find it.

Tooltips operate using ordinary Emacs frames.

Areas of the mode line are not mouse-sensitive; however, some mouse commands are available for the mode line as a whole.

Windows cannot have header lines. Conversely, there is no way to turn off the mode line of a window unless it is a minibuffer.

Plain dashes are the only separators you can use in a menu.

Vertical fractional scrolling does not exist.

The functions format and message ignore and discard text properties.

The function propertize does not exist; you can get the job done using set-text-properties.

Colors are supported only on window systems, not on text-only terminals. So the support functions for colors on text-only terminals are not needed, and have been eliminated.

The functions color-values, color-defined-p and defined-colors have been renamed to x-color-values, x-color-defined-p and x-defined-colors.

Windows cannot be made fixed-width or fixed-height; Emacs will adjust the size of all windows when it needs to.

The string used as the value of the before-string or after-string property must contain only characters that display as a single column--control characters, including tabs and newlines, will give strange results.

The minibuffer prompt does not actually appear in content of the minibuffer; it is displayed specially in the minibuffer window.

The "exclusive open" feature of write-region has been eliminated; any non-nil value for the seventh argument now means to ask the user for confirmation.

The function buffer-size always reports on the current buffer.

The function assq-delete-all has itself been deleted. So there!

The keyword :set-after no longer does anything in defcustom.

The variable small-temporary-file-directory has no special meaning. There's only one variable for specifying which directory to use for temporary files, temporary-file-directory, but not all Emacs features use it anyway. Some use the TMP environment variable, and some use the TMPDIR environment variable.

If the second argument of save-some-buffers, pred, is not nil, then the precise value no longer matters. Any non-nil value means the same as t: offer to save each non-file buffer that has a non-nil value for buffer-offer-save.

The variable inhibit-modification-hooks has no special meaning.

The hook fontification-functions has been eliminated, but there are other hooks, such as window-scroll-functions, that you can use to do a similar job.

The variable redisplay-dont-pause has no special meaning.

The hook calendar-move-hook has been deleted.

The function move-to-column treats any non-nil second argument just like t.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

A.2 Old Lisp Features in Emacs 20.3

Here are the most important of the features that you will learn to do without in Emacs 20.3:

Here are changes in the Lisp language itself:

The functions line-beginning-position and line-end-position have been eliminated.

The functions directory-files-and-attributes, file-attributes-lessp, and file-expand-wildcards, have been eliminated.

The functions decode-coding-region and encode-coding-region leave text properties untouched, in case that is useful. (It rarely makes any sense, though.)

The functions position-bytes and byte-to-position have been eliminated.

Temporary buffers made with with-output-to-temp-buffer are now modifiable by default, and use Fundamental mode rather than Help mode.

The functions sref interprets its index argument as a number of bytes, not a number of characters. And the function char-bytes actually tries to report on the number of bytes that a character occupies.

The function process-running-child-p has been eliminated.

The function interrupt-process and similar functions no longer do anything special when the second argument is lambda.

The function define-prefix-command accepts only two arguments.

The meaning of the second argument to read-char, read-event, and read-char-exclusive has been reversed: they use the current input method if the argument is if nil.

The function with-temp-message has been eliminated.

The function clear-this-command-keys has been eliminated.

The functions gap-position and gap-size have been eliminated.

In modify-face, an argument of (nil) has no special meaning.

The base64 conversion functions have been eliminated.

Wildcard support has been eliminated from find-file and allied functions.

file-attributes returns the file size and the file inode number only as a simple integer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B. GNU Free Documentation License
Version 1.1, March 2000
Copyright (C) 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
PREAMBLE
The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.
COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.
If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

C. GNU General Public License
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does.
Copyright (C) year  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D. Tips and Conventions

This chapter describes no additional features of Emacs Lisp. Instead it gives advice on making effective use of the features described in the previous chapters, and describes conventions Emacs Lisp programmers should follow.

You can automatically check some of the conventions described below by running the command M-x checkdoc RET when visiting a Lisp file. It cannot check all of the conventions, and not all the warnings it gives necessarily correspond to problems, but it is worth examining them all.

D.1 Emacs Lisp Coding Conventions

Conventions for clean and robust programs.

D.2 Tips for Making Compiled Code Fast

Making compiled code run fast.

D.3 Tips for Documentation Strings

Writing readable documentation strings.

D.4 Tips on Writing Comments

Conventions for writing comments.

D.5 Conventional Headers for Emacs Libraries

Standard headers for library packages.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.1 Emacs Lisp Coding Conventions

Here are conventions that you should follow when writing Emacs Lisp code intended for widespread use:

Since all global variables share the same name space, and all functions share another name space, you should choose a short word to distinguish your program from other Lisp programs.(10) Then take care to begin the names of all global variables, constants, and functions in your program with the chosen prefix. This helps avoid name conflicts.
This recommendation applies even to names for traditional Lisp primitives that are not primitives in Emacs Lisp--even to copy-list. Believe it or not, there is more than one plausible way to define copy-list. Play it safe; append your name prefix to produce a name like foo-copy-list or mylib-copy-list instead.

If you write a function that you think ought to be added to Emacs under a certain name, such as twiddle-files, don't call it by that name in your program. Call it mylib-twiddle-files in your program, and send mail to `bug-gnu-emacs@gnu.org' suggesting we add it to Emacs. If and when we do, we can change the name easily enough.

If one prefix is insufficient, your package may use two or three alternative common prefixes, so long as they make sense.

Separate the prefix from the rest of the symbol name with a hyphen, `-'. This will be consistent with Emacs itself and with most Emacs Lisp programs.

It is often useful to put a call to provide in each separate library program, at least if there is more than one entry point to the program.

If a file requires certain other library programs to be loaded beforehand, then the comments at the beginning of the file should say so. Also, use require to make sure they are loaded.

If one file foo uses a macro defined in another file bar, foo should contain this expression before the first use of the macro:
(eval-when-compile (require 'bar))
(And the library bar should contain (provide 'bar), to make the require work.) This will cause bar to be loaded when you byte-compile foo. Otherwise, you risk compiling foo without the necessary macro loaded, and that would produce compiled code that won't work right. See section 13.3 Macros and Byte Compilation.

Using eval-when-compile avoids loading bar when the compiled version of foo is used.

Please don't require the cl package of Common Lisp extensions at run time. Use of this package is optional, and it is not part of the standard Emacs namespace. If your package loads cl at run time, that could cause name clashes for users who don't use that package.
However, there is no problem with using the cl package at compile time, for the sake of macros. You do that like this:
(eval-when-compile (require 'cl))
When defining a major mode, please follow the major mode conventions. See section 23.1.1 Major Mode Conventions.

When defining a minor mode, please follow the minor mode conventions. See section 23.2.1 Conventions for Writing Minor Modes.

If the purpose of a function is to tell you whether a certain condition is true or false, give the function a name that ends in `p'. If the name is one word, add just `p'; if the name is multiple words, add `-p'. Examples are framep and frame-live-p.

If a user option variable records a true-or-false condition, give it a name that ends in `-flag'.

Please do not define C-c letter as a key in your major modes. These sequences are reserved for users; they are the only sequences reserved for users, so do not block them.
Instead, define sequences consisting of C-c followed by a control character, a digit, or certain punctuation characters. These sequences are reserved for major modes.

Changing all the Emacs major modes to follow this convention was a lot of work. Abandoning this convention would make that work go to waste, and inconvenience users.

Sequences consisting of C-c followed by {, }, <, >, : or ; are also reserved for major modes.

Sequences consisting of C-c followed by any other punctuation character are allocated for minor modes. Using them in a major mode is not absolutely prohibited, but if you do that, the major mode binding may be shadowed from time to time by minor modes.

Function keys F5 through F9 without modifier keys are reserved for users to define.

Do not bind C-h following any prefix character (including C-c). If you don't bind C-h, it is automatically available as a help character for listing the subcommands of the prefix character.

Do not bind a key sequence ending in ESC except following another ESC. (That is, it is OK to bind a sequence ending in ESC ESC.)
The reason for this rule is that a non-prefix binding for ESC in any context prevents recognition of escape sequences as function keys in that context.

Anything which acts like a temporary mode or state which the user can enter and leave should define ESC ESC or ESC ESC ESC as a way to escape.
For a state which accepts ordinary Emacs commands, or more generally any kind of state in which ESC followed by a function key or arrow key is potentially meaningful, then you must not define ESC ESC, since that would preclude recognizing an escape sequence after ESC. In these states, you should define ESC ESC ESC as the way to escape. Otherwise, define ESC ESC instead.

Applications should not bind mouse events based on button 1 with the shift key held down. These events include S-mouse-1, M-S-mouse-1, C-S-mouse-1, and so on. They are reserved for users.

Special major modes used for read-only text should usually redefine mouse-2 and RET to trace some sort of reference in the text. Modes such as Dired, Info, Compilation, and Occur redefine it in this way.

When a package provides a modification of ordinary Emacs behavior, it is good to include a command to enable and disable the feature, Provide a command named whatever-mode which turns the feature on or off, and make it autoload (see section 15.4 Autoload). Design the package so that simply loading it has no visible effect--that should not enable the feature.(11) Users will request the feature by invoking the command.

It is a bad idea to define aliases for the Emacs primitives. Use the standard names instead.

If a package needs to define an alias or a new function for compatibility with some other version of Emacs, name it with the package prefix, not with the raw name with which it occurs in the other version. Here is an example from Gnus, which provides many examples of such compatibility issues.
(defalias 'gnus-point-at-bol
  (if (fboundp 'point-at-bol)
      'point-at-bol
    'line-beginning-position))
Redefining (or advising) an Emacs primitive is discouraged. It may do the right thing for a particular program, but there is no telling what other programs might break as a result.

If a file does replace any of the functions or library programs of standard Emacs, prominent comments at the beginning of the file should say which functions are replaced, and how the behavior of the replacements differs from that of the originals.

Please keep the names of your Emacs Lisp source files to 13 characters or less. This way, if the files are compiled, the compiled files' names will be 14 characters or less, which is short enough to fit on all kinds of Unix systems.

Don't use next-line or previous-line in programs; nearly always, forward-line is more convenient as well as more predictable and robust. See section 30.2.4 Motion by Text Lines.

Don't call functions that set the mark, unless setting the mark is one of the intended features of your program. The mark is a user-level feature, so it is incorrect to change the mark except to supply a value for the user's benefit. See section 31.7 The Mark.
In particular, don't use any of these functions:

beginning-of-buffer, end-of-buffer
replace-string, replace-regexp

If you just want to move point, or replace a certain string, without any of the other features intended for interactive users, you can replace these functions with one or two lines of simple Lisp code.

Use lists rather than vectors, except when there is a particular reason to use a vector. Lisp has more facilities for manipulating lists than for vectors, and working with lists is usually more convenient.
Vectors are advantageous for tables that are substantial in size and are accessed in random order (not searched front to back), provided there is no need to insert or delete elements (only lists allow that).

The recommended way to print a message in the echo area is with the message function, not princ. See section 38.4 The Echo Area.

When you encounter an error condition, call the function error (or signal). The function error does not return. See section 10.5.3.1 How to Signal an Error.
Do not use message, throw, sleep-for, or beep to report errors.

An error message should start with a capital letter but should not end with a period.

In interactive, if you use a Lisp expression to produce a list of arguments, don't try to provide the "correct" default values for region or position arguments. Instead, provide nil for those arguments if they were not specified, and have the function body compute the default value when the argument is nil. For instance, write this:
(defun foo (pos)
  (interactive
   (list (if specified specified-pos)))
  (unless pos (setq pos default-pos))
  ...)
rather than this:
(defun foo (pos)
  (interactive
   (list (if specified specified-pos
             default-pos)))
  ...)
This is so that repetition of the command will recompute these defaults based on the current circumstances.

You do not need to take such precautions when you use interactive specs `d', `m' and `r', because they make special arrangements to recompute the argument values on repetition of the command.

Many commands that take a long time to execute display a message that says something like `Operating...' when they start, and change it to `Operating...done' when they finish. Please keep the style of these messages uniform: no space around the ellipsis, and no period after `done'.

Try to avoid using recursive edits. Instead, do what the Rmail e command does: use a new local keymap that contains one command defined to switch back to the old local keymap. Or do what the edit-options command does: switch to another buffer and let the user switch back at will. See section 21.12 Recursive Editing.

In some other systems there is a convention of choosing variable names that begin and end with `*'. We don't use that convention in Emacs Lisp, so please don't use it in your programs. (Emacs uses such names only for special-purpose buffers.) The users will find Emacs more coherent if all libraries use the same conventions.

Try to avoid compiler warnings about undefined free variables, by adding defvar definitions for these variables.
Sometimes adding a require for another package is useful to avoid compilation warnings for variables and functions defined in that package. If you do this, often it is better if the require acts only at compile time. Here's how to do that:
(eval-when-compile
  (require 'foo)
  (defvar bar-baz))
If you bind a variable in one function, and use it or set it in another function, the compiler warns about the latter function unless the variable has a definition. But often these variables have short names, and it is not clean for Lisp packages to define such variable names. Therefore, you should rename the variable to start with the name prefix used for the other functions and variables in your package.

Indent each function with C-M-q (indent-sexp) using the default indentation parameters.

Don't make a habit of putting close-parentheses on lines by themselves; Lisp programmers find this disconcerting. Once in a while, when there is a sequence of many consecutive close-parentheses, it may make sense to split the sequence in one or two significant places.

Please put a copyright notice on the file if you give copies to anyone. Use a message like this one:
;; Copyright (C) year name

;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2 of
;; the License, or (at your option) any later version.

;; This program is distributed in the hope that it will be
;; useful, but WITHOUT ANY WARRANTY; without even the implied
;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
;; PURPOSE.  See the GNU General Public License for more details.

;; You should have received a copy of the GNU General Public
;; License along with this program; if not, write to the Free
;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
;; MA 02111-1307 USA
If you have signed papers to assign the copyright to the Foundation, then use `Free Software Foundation, Inc.' as name. Otherwise, use your name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.2 Tips for Making Compiled Code Fast

Here are ways of improving the execution speed of byte-compiled Lisp programs.

Profile your program with the `profile' library or the `elp' library. See the files `profile.el' and `elp.el' for instructions.

Use iteration rather than recursion whenever possible. Function calls are slow in Emacs Lisp even when a compiled function is calling another compiled function.

Using the primitive list-searching functions memq, member, assq, or assoc is even faster than explicit iteration. It can be worth rearranging a data structure so that one of these primitive search functions can be used.

Certain built-in functions are handled specially in byte-compiled code, avoiding the need for an ordinary function call. It is a good idea to use these functions rather than alternatives. To see whether a function is handled specially by the compiler, examine its byte-compile property. If the property is non-nil, then the function is handled specially.
For example, the following input will show you that aref is compiled specially (see section 6.3 Functions that Operate on Arrays):
(get 'aref 'byte-compile)
     => byte-compile-two-args
If calling a small function accounts for a substantial part of your program's running time, make the function inline. This eliminates the function call overhead. Since making a function inline reduces the flexibility of changing the program, don't do it unless it gives a noticeable speedup in something slow enough that users care about the speed. See section 12.9 Inline Functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.3 Tips for Documentation Strings

Here are some tips and conventions for the writing of documentation strings. You can check many of these conventions by running the command M-x checkdoc-minor-mode.

Every command, function, or variable intended for users to know about should have a documentation string.

An internal variable or subroutine of a Lisp program might as well have a documentation string. In earlier Emacs versions, you could save space by using a comment instead of a documentation string, but that is no longer the case--documentation strings now take up very little space in a running Emacs.

The first line of the documentation string should consist of one or two complete sentences that stand on their own as a summary. M-x apropos displays just the first line, and if that line's contents don't stand on their own, the result looks bad. In particular, start the first line with a capital letter and end with a period.
The documentation string is not limited to one line; use as many lines as you need to explain the details of how to use the function or variable. Please use complete sentences in the additional lines.

For consistency, phrase the verb in the first sentence of a function's documentation string as an imperative--for instance, use "Return the cons of A and B." in preference to "Returns the cons of A and B." Usually it looks good to do likewise for the rest of the first paragraph. Subsequent paragraphs usually look better if each sentence has a proper subject.

Write documentation strings in the active voice, not the passive, and in the present tense, not the future. For instance, use "Return a list containing A and B." instead of "A list containing A and B will be returned."

Avoid using the word "cause" (or its equivalents) unnecessarily. Instead of, "Cause Emacs to display text in boldface," write just "Display text in boldface."

When a command is meaningful only in a certain mode or situation, do mention that in the documentation string. For example, the documentation of dired-find-file is:
In Dired, visit the file or directory named on this line.
Do not start or end a documentation string with whitespace.

Format the documentation string so that it fits in an Emacs window on an 80-column screen. It is a good idea for most lines to be no wider than 60 characters. The first line should not be wider than 67 characters or it will look bad in the output of apropos.
You can fill the text if that looks good. However, rather than blindly filling the entire documentation string, you can often make it much more readable by choosing certain line breaks with care. Use blank lines between topics if the documentation string is long.
Do not indent subsequent lines of a documentation string so that the text is lined up in the source code with the text of the first line. This looks nice in the source code, but looks bizarre when users view the documentation. Remember that the indentation before the starting double-quote is not part of the string!

When the user tries to use a disabled command, Emacs displays just the first paragraph of its documentation string--everything through the first blank line. If you wish, you can choose which information to include before the first blank line so as to make this display useful.

A variable's documentation string should start with `*' if the variable is one that users would often want to set interactively. If the value is a long list, or a function, or if the variable would be set only in init files, then don't start the documentation string with `*'. See section 11.5 Defining Global Variables.

The documentation string for a variable that is a yes-or-no flag should start with words such as "Non-nil means...", to make it clear that all non-nil values are equivalent and indicate explicitly what nil and non-nil mean.

When a function's documentation string mentions the value of an argument of the function, use the argument name in capital letters as if it were a name for that value. Thus, the documentation string of the function eval refers to its second argument as `FORM', because the actual argument name is form:
Evaluate FORM and return its value.
Also write metasyntactic variables in capital letters, such as when you show the decomposition of a list or vector into subunits, some of which may vary. `KEY' and `VALUE' in the following example illustrate this practice:
The argument TABLE should be an alist whose elements
have the form (KEY . VALUE).  Here, KEY is ...
If a line in a documentation string begins with an open-parenthesis, write a backslash before the open-parenthesis, like this:
The argument FOO can be either a number
\(a buffer position) or a string (a file name).
This prevents the open-parenthesis from being treated as the start of a defun (see section `Defuns' in The GNU Emacs Manual).

When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), with single-quotes around it. For example: `lambda'. There are two exceptions: write t and nil without single-quotes. (In this manual, we use a different convention, with single-quotes for all symbols.)
Help mode automatically creates a hyperlink when a documentation string uses a symbol name inside single quotes, if the symbol has either a function or a variable definition. You do not need to do anything special to make use of this feature. However, when a symbol has both a function definition and a variable definition, and you want to refer to just one of them, you can specify which one by writing one of the words `variable', `option', `function', or `command', immediately before the symbol name. (Case makes no difference in recognizing these indicator words.) For example, if you write
This function sets the variable `buffer-file-name'.
then the hyperlink will refer only to the variable documentation of buffer-file-name, and not to its function documentation.

If a symbol has a function definition and/or a variable definition, but those are irrelevant to the use of the symbol that you are documenting, you can write the word `symbol' before the symbol name to prevent making any hyperlink. For example,
If the argument KIND-OF-RESULT is the symbol `list',
this function returns a list of all the objects
that satisfy the criterion.
does not make a hyperlink to the documentation, irrelevant here, of the function list.

To make a hyperlink to Info documentation, write the name of the Info node in single quotes, preceded by `info node' or `Info node'. The Info file name defaults to `emacs'. For example,
See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
Don't write key sequences directly in documentation strings. Instead, use the `\\[...]' construct to stand for them. For example, instead of writing `C-f', write the construct `\\[forward-char]'. When Emacs displays the documentation string, it substitutes whatever key is currently bound to forward-char. (This is normally `C-f', but it may be some other character if the user has moved key bindings.) See section 24.3 Substituting Key Bindings in Documentation.

In documentation strings for a major mode, you will want to refer to the key bindings of that mode's local map, rather than global ones. Therefore, use the construct `\\<...>' once in the documentation string to specify which key map to use. Do this before the first use of `\\[...]'. The text inside the `\\<...>' should be the name of the variable containing the local keymap for the major mode.
It is not practical to use `\\[...]' very many times, because display of the documentation string will become slow. So use this to describe the most important commands in your major mode, and then use `\\{...}' to display the rest of the mode's keymap.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.4 Tips on Writing Comments

We recommend these conventions for where to put comments and how to indent them:

`;'
Comments that start with a single semicolon, `;', should all be aligned to the same column on the right of the source code. Such comments usually explain how the code on the same line does its job. In Lisp mode and related modes, the M-; (indent-for-comment) command automatically inserts such a `;' in the right place, or aligns such a comment if it is already present.
This and following examples are taken from the Emacs sources.
(setq base-version-list                 ; there was a base
      (assoc (substring fn 0 start-vn)  ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion
`;;'
Comments that start with two semicolons, `;;', should be aligned to the same level of indentation as the code. Such comments usually describe the purpose of the following lines or the state of the program at that point. For example:
(prog1 (setq auto-fill-function
             ...
             ...
  ;; update mode line
  (force-mode-line-update)))
We also normally use two semicolons for comments outside functions.
;; This Lisp code is run in Emacs
;; when it is to operate as a server
;; for other processes.
Every function that has no documentation string (presumably one that is used only internally within the package it belongs to), should instead have a two-semicolon comment right before the function, explaining what the function does and how to call it properly. Explain precisely what each argument means and how the function interprets its possible values.

`;;;'
Comments that start with three semicolons, `;;;', should start at the left margin. These are used, occasionally, for comments within functions that should start at the margin. We also use them sometimes for comments that are between functions--whether to use two or three semicolons there is a matter of style.
Another use for triple-semicolon comments is for commenting out lines within a function. We use three semicolons for this precisely so that they remain at the left margin.
(defun foo (a)
;;; This is no longer necessary.
;;;  (force-mode-line-update)
  (message "Finished with %s" a))
`;;;;'
Comments that start with four semicolons, `;;;;', should be aligned to the left margin and are used for headings of major sections of a program. For example:
;;;; The kill ring
The indentation commands of the Lisp modes in Emacs, such as M-; (indent-for-comment) and TAB (lisp-indent-line), automatically indent comments according to these conventions, depending on the number of semicolons. See section `Manipulating Comments' in The GNU Emacs Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.5 Conventional Headers for Emacs Libraries

Emacs has conventions for using special comments in Lisp libraries to divide them into sections and give information such as who wrote them. This section explains these conventions.

We'll start with an example, a package that is included in the Emacs distribution.

Parts of this example reflect its status as part of Emacs; for example, the copyright notice lists the Free Software Foundation as the copyright holder, and the copying permission says the file is part of Emacs. When you write a package and post it, the copyright holder would be you (unless your employer claims to own it instead), and you should get the suggested copying permission from the end of the GNU General Public License itself. Don't say your file is part of Emacs if we haven't installed it in Emacs yet!

With that warning out of the way, on to the example:
;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers

;; Copyright (C) 1992 Free Software Foundation, Inc.

;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
;; Created: 14 Jul 1992
;; Version: 1.2
;; Keywords: docs

;; This file is part of GNU Emacs.
...
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
The very first line should have this format:
;;; filename --- description
The description should be complete in one line.

After the copyright notice come several header comment lines, each beginning with `;; header-name:'. Here is a table of the conventional possibilities for header-name:

`Author'
This line states the name and net address of at least the principal author of the library.
If there are multiple authors, you can list them on continuation lines led by ;; and a tab character, like this:
;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
;;      Dave Sill <de5@ornl.gov>
;;      Dave Brennan <brennan@hal.com>
;;      Eric Raymond <esr@snark.thyrsus.com>
`Maintainer'
This line should contain a single name/address as in the Author line, or an address only, or the string `FSF'. If there is no maintainer line, the person(s) in the Author field are presumed to be the maintainers. The example above is mildly bogus because the maintainer line is redundant.
The idea behind the `Author' and `Maintainer' lines is to make possible a Lisp function to "send mail to the maintainer" without having to mine the name out by hand.

Be sure to surround the network address with `<...>' if you include the person's full name as well as the network address.

`Created'
This optional line gives the original creation date of the file. For historical interest only.

`Version'
If you wish to record version numbers for the individual Lisp program, put them in this line.

`Adapted-By'
In this header line, place the name of the person who adapted the library for installation (to make it fit the style conventions, for example).

`Keywords'
This line lists keywords for the finder-by-keyword help command. Please use that command to see a list of the meaningful keywords.
This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both.
Just about every Lisp library ought to have the `Author' and `Keywords' header comment lines. Use the others if they are appropriate. You can also put in header lines with other header names--they have no standard meanings, so they can't do any harm.

We use additional stylized comments to subdivide the contents of the library file. These should be separated by blank lines from anything else. Here is a table of them:

`;;; Commentary:'
This begins introductory comments that explain how the library works. It should come right after the copying permissions, terminated by a `Change Log', `History' or `Code' comment line. This text is used by the Finder package, so it should make sense in that context.

`;;; Documentation'
This has been used in some files in place of `;;; Commentary:', but `;;; Commentary:' is preferred.

`;;; Change Log:'
This begins change log information stored in the library file (if you store the change history there). For Lisp files distributed with Emacs, the change history is kept in the file `ChangeLog' and not in the source file at all; these files generally do not have a `;;; Change Log:' line. `History' is an alternative to `Change Log'.

`;;; Code:'
This begins the actual code of the program.

`;;; filename ends here'
This is the footer line; it appears at the very end of the file. Its purpose is to enable people to detect truncated versions of the file from the lack of a footer line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E. GNU Emacs Internals

This chapter describes how the runnable Emacs executable is dumped with the preloaded Lisp libraries in it, how storage is allocated, and some internal aspects of GNU Emacs that may be of interest to C programmers.

E.1 Building Emacs

How to the dumped Emacs is made.

E.2 Pure Storage

A kludge to make preloaded Lisp functions sharable.

E.3 Garbage Collection

Reclaiming space for Lisp objects no longer used.

E.4 Memory Usage

Info about total size of Lisp objects made so far.

E.5 Writing Emacs Primitives

Writing C code for Emacs.

E.6 Object Internals

Data formats of buffers, windows, processes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.1 Building Emacs

This section explains the steps involved in building the Emacs executable. You don't have to know this material to build and install Emacs, since the makefiles do all these things automatically. This information is pertinent to Emacs maintenance.

Compilation of the C source files in the `src' directory produces an executable file called `temacs', also called a bare impure Emacs. It contains the Emacs Lisp interpreter and I/O routines, but not the editing commands.

The command `temacs -l loadup' uses `temacs' to create the real runnable Emacs executable. These arguments direct `temacs' to evaluate the Lisp files specified in the file `loadup.el'. These files set up the normal Emacs editing environment, resulting in an Emacs that is still impure but no longer bare.

It takes a substantial time to load the standard Lisp files. Luckily, you don't have to do this each time you run Emacs; `temacs' can dump out an executable program called `emacs' that has these files preloaded. `emacs' starts more quickly because it does not need to load the files. This is the Emacs executable that is normally installed.

To create `emacs', use the command `temacs -batch -l loadup dump'. The purpose of `-batch' here is to prevent `temacs' from trying to initialize any of its data on the terminal; this ensures that the tables of terminal information are empty in the dumped Emacs. The argument `dump' tells `loadup.el' to dump a new executable named `emacs'.

Some operating systems don't support dumping. On those systems, you must start Emacs with the `temacs -l loadup' command each time you use it. This takes a substantial time, but since you need to start Emacs once a day at most--or once a week if you never log out--the extra time is not too severe a problem.

You can specify additional files to preload by writing a library named `site-load.el' that loads them. You may need to add a definition
#define SITELOAD_PURESIZE_EXTRA n
to make n added bytes of pure space to hold the additional files. (Try adding increments of 20000 until it is big enough.) However, the advantage of preloading additional files decreases as machines get faster. On modern machines, it is usually not advisable.

After `loadup.el' reads `site-load.el', it finds the documentation strings for primitive and preloaded functions (and variables) in the file `etc/DOC' where they are stored, by calling Snarf-documentation (see section 24.2 Access to Documentation Strings).

You can specify other Lisp expressions to execute just before dumping by putting them in a library named `site-init.el'. This file is executed after the documentation strings are found.

If you want to preload function or variable definitions, there are three ways you can do this and make their documentation strings accessible when you subsequently run Emacs:

Arrange to scan these files when producing the `etc/DOC' file, and load them with `site-load.el'.

Load the files with `site-init.el', then copy the files into the installation directory for Lisp files when you install Emacs.

Specify a non-nil value for byte-compile-dynamic-docstrings as a local variable in each of these files, and load them with either `site-load.el' or `site-init.el'. (This method has the drawback that the documentation strings take up space in Emacs all the time.)

It is not advisable to put anything in `site-load.el' or `site-init.el' that would alter any of the features that users expect in an ordinary unmodified Emacs. If you feel you must override normal features for your site, do it with `default.el', so that users can override your changes if they wish. See section 40.1.1 Summary: Sequence of Actions at Startup.

Function: dump-emacs to-file from-file
This function dumps the current state of Emacs into an executable file to-file. It takes symbols from from-file (this is normally the executable file `temacs').

If you want to use this function in an Emacs that was already dumped, you must run Emacs with `-batch'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.2 Pure Storage

Emacs Lisp uses two kinds of storage for user-created Lisp objects: normal storage and pure storage. Normal storage is where all the new data created during an Emacs session are kept; see the following section for information on normal storage. Pure storage is used for certain data in the preloaded standard Lisp files--data that should never change during actual use of Emacs.

Pure storage is allocated only while `temacs' is loading the standard preloaded Lisp libraries. In the file `emacs', it is marked as read-only (on operating systems that permit this), so that the memory space can be shared by all the Emacs jobs running on the machine at once. Pure storage is not expandable; a fixed amount is allocated when Emacs is compiled, and if that is not sufficient for the preloaded libraries, `temacs' crashes. If that happens, you must increase the compilation parameter PURESIZE in the file `src/puresize.h'. This normally won't happen unless you try to preload additional libraries or add features to the standard ones.

Function: purecopy object
This function makes a copy in pure storage of object, and returns it. It copies a string by simply making a new string with the same characters in pure storage. It recursively copies the contents of vectors and cons cells. It does not make copies of other objects such as symbols, but just returns them unchanged. It signals an error if asked to copy markers.

This function is a no-op except while Emacs is being built and dumped; it is usually called only in the file `emacs/lisp/loaddefs.el', but a few packages call it just in case you decide to preload them.

Variable: pure-bytes-used
The value of this variable is the number of bytes of pure storage allocated so far. Typically, in a dumped Emacs, this number is very close to the total amount of pure storage available--if it were not, we would preallocate less.

Variable: purify-flag
This variable determines whether defun should make a copy of the function definition in pure storage. If it is non-nil, then the function definition is copied into pure storage.

This flag is t while loading all of the basic functions for building Emacs initially (allowing those functions to be sharable and non-collectible). Dumping Emacs as an executable always writes nil in this variable, regardless of the value it actually has before and after dumping.

You should not change this flag in a running Emacs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.3 Garbage Collection

When a program creates a list or the user defines a new function (such as by loading a library), that data is placed in normal storage. If normal storage runs low, then Emacs asks the operating system to allocate more memory in blocks of 1k bytes. Each block is used for one type of Lisp object, so symbols, cons cells, markers, etc., are segregated in distinct blocks in memory. (Vectors, long strings, buffers and certain other editing types, which are fairly large, are allocated in individual blocks, one per object, while small strings are packed into blocks of 8k bytes.)

It is quite common to use some storage for a while, then release it by (for example) killing a buffer or deleting the last pointer to an object. Emacs provides a garbage collector to reclaim this abandoned storage. (This name is traditional, but "garbage recycler" might be a more intuitive metaphor for this facility.)

The garbage collector operates by finding and marking all Lisp objects that are still accessible to Lisp programs. To begin with, it assumes all the symbols, their values and associated function definitions, and any data presently on the stack, are accessible. Any objects that can be reached indirectly through other accessible objects are also accessible.

When marking is finished, all objects still unmarked are garbage. No matter what the Lisp program or the user does, it is impossible to refer to them, since there is no longer a way to reach them. Their space might as well be reused, since no one will miss them. The second ("sweep") phase of the garbage collector arranges to reuse them.

The sweep phase puts unused cons cells onto a free list for future allocation; likewise for symbols and markers. It compacts the accessible strings so they occupy fewer 8k blocks; then it frees the other 8k blocks. Vectors, buffers, windows, and other large objects are individually allocated and freed using malloc and free.

Common Lisp note: Unlike other Lisps, GNU Emacs Lisp does not call the garbage collector when the free list is empty. Instead, it simply requests the operating system to allocate more storage, and processing continues until gc-cons-threshold bytes have been used.
This means that you can make sure that the garbage collector will not run during a certain portion of a Lisp program by calling the garbage collector explicitly just before it (provided that portion of the program does not use so much space as to force a second garbage collection).

Command: garbage-collect
This command runs a garbage collection, and returns information on the amount of space in use. (Garbage collection can also occur spontaneously if you use more than gc-cons-threshold bytes of Lisp data since the previous garbage collection.)

garbage-collect returns a list containing the following information:
((used-conses . free-conses)
 (used-syms . free-syms)
 (used-miscs . free-miscs)
 used-string-chars
 used-vector-slots
 (used-floats . free-floats)
 (used-intervals . free-intervals)
 (used-strings . free-strings))
Here is an example:
(garbage-collect)
     => ((106886 . 13184) (9769 . 0)
                (7731 . 4651) 347543 121628
                (31 . 94) (1273 . 168)
                (25474 . 3569))
Here is a table explaining each element:

used-conses
The number of cons cells in use.

free-conses
The number of cons cells for which space has been obtained from the operating system, but that are not currently being used.

used-syms
The number of symbols in use.

free-syms
The number of symbols for which space has been obtained from the operating system, but that are not currently being used.

used-miscs
The number of miscellaneous objects in use. These include markers and overlays, plus certain objects not visible to users.

free-miscs
The number of miscellaneous objects for which space has been obtained from the operating system, but that are not currently being used.

used-string-chars
The total size of all strings, in characters.

used-vector-slots
The total number of elements of existing vectors.

used-floats
The number of floats in use.

free-floats
The number of floats for which space has been obtained from the operating system, but that are not currently being used.

used-intervals
The number of intervals in use. Intervals are an internal data structure used for representing text properties.

free-intervals
The number of intervals for which space has been obtained from the operating system, but that are not currently being used.

used-strings
The number of strings in use.

free-strings
The number of string headers for which the space was obtained from the operating system, but which are currently not in use. (A string object consists of a header and the storage for the string text itself; the latter is only allocated when the string is created.)

User Option: garbage-collection-messages
If this variable is non-nil, Emacs displays a message at the beginning and end of garbage collection. The default value is nil, meaning there are no such messages.

User Option: gc-cons-threshold
The value of this variable is the number of bytes of storage that must be allocated for Lisp objects after one garbage collection in order to trigger another garbage collection. A cons cell counts as eight bytes, a string as one byte per character plus a few bytes of overhead, and so on; space allocated to the contents of buffers does not count. Note that the subsequent garbage collection does not happen immediately when the threshold is exhausted, but only the next time the Lisp evaluator is called.

The initial threshold value is 400,000. If you specify a larger value, garbage collection will happen less often. This reduces the amount of time spent garbage collecting, but increases total memory use. You may want to do this when running a program that creates lots of Lisp data.

You can make collections more frequent by specifying a smaller value, down to 10,000. A value less than 10,000 will remain in effect only until the subsequent garbage collection, at which time garbage-collect will set the threshold back to 10,000.

The value return by garbage-collect describes the amount of memory used by Lisp data, broken down by data type. By contrast, the function memory-limit provides information on the total amount of memory Emacs is currently using.

Function: memory-limit
This function returns the address of the last byte Emacs has allocated, divided by 1024. We divide the value by 1024 to make sure it fits in a Lisp integer.

You can use this to get a general idea of how your actions affect the memory usage.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.4 Memory Usage

These functions and variables give information about the total amount of memory allocation that Emacs has done, broken down by data type. Note the difference between these and the values returned by (garbage-collect); those count objects that currently exist, but these count the number or size of all allocations, including those for objects that have since been freed.

Variable: cons-cells-consed
The total number of cons cells that have been allocated so far in this Emacs session.

Variable: floats-consed
The total number of floats that have been allocated so far in this Emacs session.

Variable: vector-cells-consed
The total number of vector cells that have been allocated so far in this Emacs session.

Variable: symbols-consed
The total number of symbols that have been allocated so far in this Emacs session.

Variable: string-chars-consed
The total number of string characters that have been allocated so far in this Emacs session.

Variable: misc-objects-consed
The total number of miscellaneous objects that have been allocated so far in this Emacs session. These include markers and overlays, plus certain objects not visible to users.

Variable: intervals-consed
The total number of intervals that have been allocated so far in this Emacs session.

Variable: strings-consed
The total number of strings that have been allocated so far in this Emacs session.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.5 Writing Emacs Primitives

Lisp primitives are Lisp functions implemented in C. The details of interfacing the C function so that Lisp can call it are handled by a few C macros. The only way to really understand how to write new C code is to read the source, but we can explain some things here.

An example of a special form is the definition of or, from `eval.c'. (An ordinary function would have the same general appearance.)
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
  "Eval args until one of them yields non-nil; return that value.\n\
The remaining args are not evalled at all.\n\
If all args return nil, return nil.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object val;
  Lisp_Object args_left;
  struct gcpro gcpro1;

  if (NILP (args))
    return Qnil;

  args_left = args;
  GCPRO1 (args_left);

  do
    {
      val = Feval (Fcar (args_left));
      if (!NILP (val))
        break;
      args_left = Fcdr (args_left);
    }
  while (!NILP (args_left));

  UNGCPRO;
  return val;
}
Let's start with a precise explanation of the arguments to the DEFUN macro. Here is a template for them:
DEFUN (lname, fname, sname, min, max, interactive, doc)
lname
This is the name of the Lisp symbol to define as the function name; in the example above, it is or.

fname
This is the C function name for this function. This is the name that is used in C code for calling the function. The name is, by convention, `F' prepended to the Lisp name, with all dashes (`-') in the Lisp name changed to underscores. Thus, to call this function from C code, call For. Remember that the arguments must be of type Lisp_Object; various macros and functions for creating values of type Lisp_Object are declared in the file `lisp.h'.

sname
This is a C variable name to use for a structure that holds the data for the subr object that represents the function in Lisp. This structure conveys the Lisp symbol name to the initialization routine that will create the symbol and store the subr object as its definition. By convention, this name is always fname with `F' replaced with `S'.

min
This is the minimum number of arguments that the function requires. The function or allows a minimum of zero arguments.

max
This is the maximum number of arguments that the function accepts, if there is a fixed maximum. Alternatively, it can be UNEVALLED, indicating a special form that receives unevaluated arguments, or MANY, indicating an unlimited number of evaluated arguments (the equivalent of &rest). Both UNEVALLED and MANY are macros. If max is a number, it may not be less than min and it may not be greater than seven.

interactive
This is an interactive specification, a string such as might be used as the argument of interactive in a Lisp function. In the case of or, it is 0 (a null pointer), indicating that or cannot be called interactively. A value of "" indicates a function that should receive no arguments when called interactively.

doc
This is the documentation string. It is written just like a documentation string for a function defined in Lisp, except you must write `\n\' at the end of each line. In particular, the first line should be a single sentence.
After the call to the DEFUN macro, you must write the argument name list that every C function must have, followed by ordinary C declarations for the arguments. For a function with a fixed maximum number of arguments, declare a C argument for each Lisp argument, and give them all type Lisp_Object. When a Lisp function has no upper limit on the number of arguments, its implementation in C actually receives exactly two arguments: the first is the number of Lisp arguments, and the second is the address of a block containing their values. They have types int and Lisp_Object *.

Within the function For itself, note the use of the macros GCPRO1 and UNGCPRO. GCPRO1 is used to "protect" a variable from garbage collection--to inform the garbage collector that it must look in that variable and regard its contents as an accessible object. This is necessary whenever you call Feval or anything that can directly or indirectly call Feval. At such a time, any Lisp object that you intend to refer to again must be protected somehow. UNGCPRO cancels the protection of the variables that are protected in the current function. It is necessary to do this explicitly.

For most data types, it suffices to protect at least one pointer to the object; as long as the object is not recycled, all pointers to it remain valid. This is not so for strings, because the garbage collector can move them. When the garbage collector moves a string, it relocates all the pointers it knows about; any other pointers become invalid. Therefore, you must protect all pointers to strings across any point where garbage collection may be possible.

The macro GCPRO1 protects just one local variable. If you want to protect two, use GCPRO2 instead; repeating GCPRO1 will not work. Macros GCPRO3 and GCPRO4 also exist.

These macros implicitly use local variables such as gcpro1; you must declare these explicitly, with type struct gcpro. Thus, if you use GCPRO2, you must declare gcpro1 and gcpro2. Alas, we can't explain all the tricky details here.

You must not use C initializers for static or global variables unless the variables are never written once Emacs is dumped. These variables with initializers are allocated in an area of memory that becomes read-only (on certain operating systems) as a result of dumping Emacs. See section E.2 Pure Storage.

Do not use static variables within functions--place all static variables at top level in the file. This is necessary because Emacs on some operating systems defines the keyword static as a null macro. (This definition is used because those systems put all variables declared static in a place that becomes read-only after dumping, whether they have initializers or not.)

Defining the C function is not enough to make a Lisp primitive available; you must also create the Lisp symbol for the primitive and store a suitable subr object in its function cell. The code looks like this:
defsubr (&subr-structure-name);
Here subr-structure-name is the name you used as the third argument to DEFUN.

If you add a new primitive to a file that already has Lisp primitives defined in it, find the function (near the end of the file) named syms_of_something, and add the call to defsubr there. If the file doesn't have this function, or if you create a new file, add to it a syms_of_filename (e.g., syms_of_myfile). Then find the spot in `emacs.c' where all of these functions are called, and add a call to syms_of_filename there.

The function syms_of_filename is also the place to define any C variables that are to be visible as Lisp variables. DEFVAR_LISP makes a C variable of type Lisp_Object visible in Lisp. DEFVAR_INT makes a C variable of type int visible in Lisp with a value that is always an integer. DEFVAR_BOOL makes a C variable of type int visible in Lisp with a value that is either t or nil. Note that variables defined with DEFVAR_BOOL are automatically added to the list byte-boolean-vars used by the byte compiler.

If you define a file-scope C variable of type Lisp_Object, you must protect it from garbage-collection by calling staticpro in syms_of_filename, like this:
staticpro (&variable);
Here is another example function, with more complicated arguments. This comes from the code in `window.c', and it demonstrates the use of macros and functions to manipulate Lisp objects.
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
  Scoordinates_in_window_p, 2, 2,
  "xSpecify coordinate pair: \nXExpression which evals to window: ",
  "Return non-nil if COORDINATES is in WINDOW.\n\
COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
...
If they are on the border between WINDOW and its right sibling,\n\
   `vertical-line' is returned.")
  (coordinates, window)
     register Lisp_Object coordinates, window;
{
  int x, y;

  CHECK_LIVE_WINDOW (window, 0);
  CHECK_CONS (coordinates, 1);
  x = XINT (Fcar (coordinates));
  y = XINT (Fcdr (coordinates));

  switch (coordinates_in_window (XWINDOW (window), &x, &y))
    {
    case 0:			/* NOT in window at all. */
      return Qnil;

    case 1:			/* In text part of window. */
      return Fcons (make_number (x), make_number (y));

    case 2:			/* In mode line of window. */
      return Qmode_line;

    case 3:			/* On right border of window.  */
      return Qvertical_line;

    default:
      abort ();
    }
}
Note that C code cannot call functions by name unless they are defined in C. The way to call a function written in Lisp is to use Ffuncall, which embodies the Lisp function funcall. Since the Lisp function funcall accepts an unlimited number of arguments, in C it takes two: the number of Lisp-level arguments, and a one-dimensional array containing their values. The first Lisp-level argument is the Lisp function to call, and the rest are the arguments to pass to it. Since Ffuncall can call the evaluator, you must protect pointers from garbage collection around the call to Ffuncall.

The C functions call0, call1, call2, and so on, provide handy ways to call a Lisp function conveniently with a fixed number of arguments. They work by calling Ffuncall.

`eval.c' is a very good file to look through for examples; `lisp.h' contains the definitions for some important macros and functions.

If you define a function which is side-effect free, update the code in `byte-opt.el' which binds side-effect-free-fns and side-effect-and-error-free-fns to include it. This will help the optimizer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.6 Object Internals

GNU Emacs Lisp manipulates many different types of data. The actual data are stored in a heap and the only access that programs have to it is through pointers. Pointers are thirty-two bits wide in most implementations. Depending on the operating system and type of machine for which you compile Emacs, twenty-eight bits are used to address the object, and the remaining four bits are used for a GC mark bit and the tag that identifies the object's type.

Because Lisp objects are represented as tagged pointers, it is always possible to determine the Lisp data type of any object. The C data type Lisp_Object can hold any Lisp object of any data type. Ordinary variables have type Lisp_Object, which means they can hold any type of Lisp value; you can determine the actual data type only at run time. The same is true for function arguments; if you want a function to accept only a certain type of argument, you must check the type explicitly using a suitable predicate (see section 2.6 Type Predicates).

E.6.1 Buffer Internals

Components of a buffer structure.

E.6.2 Window Internals

Components of a window structure.

E.6.3 Process Internals

Components of a process structure.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.6.1 Buffer Internals

Buffers contain fields not directly accessible by the Lisp programmer. We describe them here, naming them by the names used in the C code. Many are accessible indirectly in Lisp programs via Lisp primitives.

Two structures are used to represent buffers in C. The buffer_text structure contains fields describing the text of a buffer; the buffer structure holds other fields. In the case of indirect buffers, two or more buffer structures reference the same buffer_text structure.

Here is a list of the struct buffer_text fields:

beg
This field contains the actual address of the buffer contents.

gpt
This holds the character position of the gap in the buffer.

z
This field contains the character position of the end of the buffer text.

gpt_byte
Contains the byte position of the gap.

z_byte
Holds the byte position of the end of the buffer text.

gap_size
Contains the size of buffer's gap.

modiff
This field counts buffer-modification events for this buffer. It is incremented for each such event, and never otherwise changed.

save_modiff
Contains the previous value of modiff, as of the last time a buffer was visited or saved in a file.
overlay_modiff
Counts modifications to overlays analogous to modiff.
beg_unchanged
Holds the number of characters at the start of the text that are known to be unchanged since the last redisplay that finished.
end_unchanged
Holds the number of characters at the end of the text that are known to be unchanged since the last redisplay that finished.
unchanged_modified
Contains the value of modiff at the time of the last redisplay that finished. If this value matches modiff, beg_unchanged and end_unchanged contain no useful information.
overlay_unchanged_modified
Contains the value of overlay_modiff at the time of the last redisplay that finished. If this value matches overlay_modiff, beg_unchanged and end_unchanged contain no useful information.
markers
The markers that refer to this buffer. This is actually a single marker, and successive elements in its marker chain are the other markers referring to this buffer text.

intervals
Contains the interval tree which records the text properties of this buffer.
The fields of struct buffer are:

next
Points to the next buffer, in the chain of all buffers including killed buffers. This chain is used only for garbage collection, in order to collect killed buffers properly. Note that vectors, and most kinds of objects allocated as vectors, are all on one chain, but buffers are on a separate chain of their own.

own_text
This is a struct buffer_text structure. In an ordinary buffer, it holds the buffer contents. In indirect buffers, this field is not used.

text
This points to the buffer_text structure that is used for this buffer. In an ordinary buffer, this is the own_text field above. In an indirect buffer, this is the own_text field of the base buffer.

pt
Contains the character position of point in a buffer.

pt_byte
Contains the byte position of point in a buffer.

begv
This field contains the character position of the beginning of the accessible range of text in the buffer.

begv_byte
This field contains the byte position of the beginning of the accessible range of text in the buffer.

zv
This field contains the character position of the end of the accessible range of text in the buffer.

zv_byte
This field contains the byte position of the end of the accessible range of text in the buffer.

base_buffer
In an indirect buffer, this points to the base buffer. In an ordinary buffer, it is null.

local_var_flags
This field contains flags indicating that certain variables are local in this buffer. Such variables are declared in the C code using DEFVAR_PER_BUFFER, and their buffer-local bindings are stored in fields in the buffer structure itself. (Some of these fields are described in this table.)

modtime
This field contains the modification time of the visited file. It is set when the file is written or read. Before writing the buffer into a file, this field is compared to the modification time of the file to see if the file has changed on disk. See section 27.5 Buffer Modification.

auto_save_modified
This field contains the time when the buffer was last auto-saved.

auto_save_failure_time
The time at which we detected a failure to auto-save, or -1 if we didn't have a failure.

last_window_start
This field contains the window-start position in the buffer as of the last time the buffer was displayed in a window.

clip_changed
This flag is set when narrowing changes in a buffer.

prevent_redisplay_optimizations_p
this flag indicates that redisplay optimizations should not be used to display this buffer.

undo_list
This field points to the buffer's undo list. See section 32.9 Undo.

name
The buffer name is a string that names the buffer. It is guaranteed to be unique. See section 27.3 Buffer Names.

filename
The name of the file visited in this buffer, or nil.
directory
The directory for expanding relative file names.

save_length
Length of the file this buffer is visiting, when last read or saved. This and other fields concerned with saving are not kept in the buffer_text structure because indirect buffers are never saved.

auto_save_file_name
File name used for auto-saving this buffer. This is not in the buffer_text because it's not used in indirect buffers at all.

read_only
Non-nil means this buffer is read-only.

mark
This field contains the mark for the buffer. The mark is a marker, hence it is also included on the list markers. See section 31.7 The Mark.

local_var_alist
This field contains the association list describing the buffer-local variable bindings of this buffer, not including the built-in buffer-local bindings that have special slots in the buffer object. (Those slots are omitted from this table.) See section 11.10 Buffer-Local Variables.

major_mode
Symbol naming the major mode of this buffer, e.g., lisp-mode.

mode_name
Pretty name of major mode, e.g., "Lisp".

mode_line_format
Mode line element that controls the format of the mode line. If this is nil, no mode line will be displayed.

header_line_format
This field is analoguous to mode_line_format for the mode line displayed at the top of windows.

keymap
This field holds the buffer's local keymap. See section 22. Keymaps.

abbrev_table
This buffer's local abbrevs.

syntax_table
This field contains the syntax table for the buffer. See section 35. Syntax Tables.

category_table
This field contains the category table for the buffer.

case_fold_search
The value of case-fold-search in this buffer.

tab_width
The value of tab-width in this buffer.

fill_column
The value of fill-column in this buffer.

left_margin
The value of left-margin in this buffer.

auto_fill_function
The value of auto-fill-function in this buffer.

downcase_table
This field contains the conversion table for converting text to lower case. See section 4.9 The Case Table.

upcase_table
This field contains the conversion table for converting text to upper case. See section 4.9 The Case Table.

case_canon_table
This field contains the conversion table for canonicalizing text for case-folding search. See section 4.9 The Case Table.

case_eqv_table
This field contains the equivalence table for case-folding search. See section 4.9 The Case Table.

truncate_lines
The value of truncate-lines in this buffer.

ctl_arrow
The value of ctl-arrow in this buffer.

selective_display
The value of selective-display in this buffer.

selective_display_ellipsis
The value of selective-display-ellipsis in this buffer.

minor_modes
An alist of the minor modes of this buffer.

overwrite_mode
The value of overwrite_mode in this buffer.

abbrev_mode
The value of abbrev-mode in this buffer.

display_table
This field contains the buffer's display table, or nil if it doesn't have one. See section 38.17 Display Tables.

save_modified
This field contains the time when the buffer was last saved, as an integer. See section 27.5 Buffer Modification.

mark_active
This field is non-nil if the buffer's mark is active.

overlays_before
This field holds a list of the overlays in this buffer that end at or before the current overlay center position. They are sorted in order of decreasing end position.

overlays_after
This field holds a list of the overlays in this buffer that end after the current overlay center position. They are sorted in order of increasing beginning position.

overlay_center
This field holds the current overlay center position. See section 38.9 Overlays.

enable_multibyte_characters
This field holds the buffer's local value of enable-multibyte-characters---either t or nil.

buffer_file_coding_system
The value of buffer-file-coding-system in this buffer.

file_format
The value of buffer-file-format in this buffer.

pt_marker
In an indirect buffer, or a buffer that is the base of an indirect buffer, this holds a marker that records point for this buffer when the buffer is not current.

begv_marker
In an indirect buffer, or a buffer that is the base of an indirect buffer, this holds a marker that records begv for this buffer when the buffer is not current.
zv_marker
In an indirect buffer, or a buffer that is the base of an indirect buffer, this holds a marker that records zv for this buffer when the buffer is not current.

file_truename
The truename of the visited file, or nil.

invisibility_spec
The value of buffer-invisibility-spec in this buffer.

last_selected_window
This is the last window that was selected with this buffer in it, or nil if that window no longer displays this buffer.

display_count
This field is incremented each time the buffer is displayed in a window.

left_margin_width
The value of left-margin-width in this buffer.

right_margin_width
The value of right-margin-width in this buffer.

indicate_empty_lines
Non-nil means indicate empty lines (lines with no text) with a small bitmap in the fringe, when using a window system that can do it.

display_time
This holds a time stamp that is updated each time this buffer is displayed in a window.

scroll_up_aggressively
The value of scroll-up-aggressively in this buffer.
scroll_down_aggressively
The value of scroll-down-aggressively in this buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.6.2 Window Internals

Windows have the following accessible fields:

frame
The frame that this window is on.

mini_p
Non-nil if this window is a minibuffer window.

parent
Internally, Emacs arranges windows in a tree; each group of siblings has a parent window whose area includes all the siblings. This field points to a window's parent.
Parent windows do not display buffers, and play little role in display except to shape their child windows. Emacs Lisp programs usually have no access to the parent windows; they operate on the windows at the leaves of the tree, which actually display buffers.

The following four fields also describe the window tree structure.

hchild
In a window subdivided horizontally by child windows, the leftmost child. Otherwise, nil.

vchild
In a window subdivided vertically by child windows, the topmost child. Otherwise, nil.

next
The next sibling of this window. It is nil in a window that is the rightmost or bottommost of a group of siblings.

prev
The previous sibling of this window. It is nil in a window that is the leftmost or topmost of a group of siblings.

left
This is the left-hand edge of the window, measured in columns. (The leftmost column on the screen is column 0.)

top
This is the top edge of the window, measured in lines. (The top line on the screen is line 0.)

height
The height of the window, measured in lines.

width
The width of the window, measured in columns. This width includes the scroll bar and fringes, and/or the separator line on the right of the window (if any).

buffer
The buffer that the window is displaying. This may change often during the life of the window.

start
The position in the buffer that is the first character to be displayed in the window.

pointm
This is the value of point in the current buffer when this window is selected; when it is not selected, it retains its previous value.

force_start
If this flag is non-nil, it says that the window has been scrolled explicitly by the Lisp program. This affects what the next redisplay does if point is off the screen: instead of scrolling the window to show the text around point, it moves point to a location that is on the screen.

frozen_window_start_p
This field is set temporarily to 1 to indicate to redisplay that start of this window should not be changed, even if point gets invisible.

start_at_line_beg
Non-nil means current value of start was the beginning of a line when it was chosen.

too_small_ok
Non-nil means don't delete this window for becoming "too small".

height_fixed_p
This field is temporarily set to 1 to fix the height of the selected window when the echo area is resized.

use_time
This is the last time that the window was selected. The function get-lru-window uses this field.

sequence_number
A unique number assigned to this window when it was created.

last_modified
The modiff field of the window's buffer, as of the last time a redisplay completed in this window.

last_overlay_modified
The overlay_modiff field of the window's buffer, as of the last time a redisplay completed in this window.

last_point
The buffer's value of point, as of the last time a redisplay completed in this window.

last_had_star
A non-nil value means the window's buffer was "modified" when the window was last updated.

vertical_scroll_bar
This window's vertical scroll bar.

left_margin_width
The width of the left margin in this window, or nil not to specify it (in which case the buffer's value of left-margin-width is used.

right_margin_width
Likewise for the right margin.

window_end_pos
This is computed as z minus the buffer position of the last glyph in the current matrix of the window. The value is only valid if window_end_valid is not nil.

window_end_bytepos
The byte position corresponding to window_end_pos.

window_end_vpos
The window-relative vertical position of the line containing window_end_pos.

window_end_valid
This field is set to a non-nil value if window_end_pos is truly valid. This is nil if nontrivial redisplay is preempted since in that case the display that window_end_pos was computed for did not get onto the screen.

redisplay_end_trigger
If redisplay in this window goes beyond this buffer position, it runs run the redisplay-end-trigger-hook.

cursor
A structure describing where the cursor is in this window.

last_cursor
The value of cursor as of the last redisplay that finished.

phys_cursor
A structure describing where the cursor of this window physically is.

phys_cursor_type
The type of cursor that was last displayed on this window.

phys_cursor_on_p
This field is non-zero if the cursor is physically on.

cursor_off_p
Non-zero means the cursor in this window is logically on.

last_cursor_off_p
This field contains the value of cursor_off_p as of the time of the last redisplay.

must_be_updated_p
This is set to 1 during redisplay when this window must be updated.

hscroll
This is the number of columns that the display in the window is scrolled horizontally to the left. Normally, this is 0.

vscroll
Vertical scroll amount, in pixels. Normally, this is 0.

dedicated
Non-nil if this window is dedicated to its buffer.

display_table
The window's display table, or nil if none is specified for it.

update_mode_line
Non-nil means this window's mode line needs to be updated.

base_line_number
The line number of a certain position in the buffer, or nil. This is used for displaying the line number of point in the mode line.

base_line_pos
The position in the buffer for which the line number is known, or nil meaning none is known.

region_showing
If the region (or part of it) is highlighted in this window, this field holds the mark position that made one end of that region. Otherwise, this field is nil.

column_number_displayed
The column number currently displayed in this window's mode line, or nil if column numbers are not being displayed.

current_matrix
A glyph matrix describing the current display of this window.

desired_matrix
A glyph matrix describing the desired display of this window.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.6.3 Process Internals

The fields of a process are:

name
A string, the name of the process.

command
A list containing the command arguments that were used to start this process.

filter
A function used to accept output from the process instead of a buffer, or nil.

sentinel
A function called whenever the process receives a signal, or nil.

buffer
The associated buffer of the process.

pid
An integer, the Unix process ID.

childp
A flag, non-nil if this is really a child process. It is nil for a network connection.

mark
A marker indicating the position of the end of the last output from this process inserted into the buffer. This is often but not always the end of the buffer.

kill_without_query
If this is non-nil, killing Emacs while this process is still running does not ask for confirmation about killing the process.

raw_status_low

raw_status_high
These two fields record 16 bits each of the process status returned by the wait system call.

status
The process status, as process-status should return it.

tick

update_tick
If these two fields are not equal, a change in the status of the process needs to be reported, either by running the sentinel or by inserting a message in the process buffer.

pty_flag
Non-nil if communication with the subprocess uses a PTY; nil if it uses a pipe.

infd
The file descriptor for input from the process.

outfd
The file descriptor for output to the process.

subtty
The file descriptor for the terminal that the subprocess is using. (On some systems, there is no need to record this, so the value is nil.)

tty_name
The name of the terminal that the subprocess is using, or nil if it is using pipes.

decode_coding_system
Coding-system for decoding the input from this process.

decoding_buf
A working buffer for decoding.

decoding_carryover
Size of carryover in decoding.

encode_coding_system
Coding-system for encoding the output to this process.

encoding_buf
A working buffer for enecoding.

encoding_carryover
Size of carryover in encoding.

inherit_coding_system_flag
Flag to set coding-system of the process buffer from the coding system used to decode process output.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

F. Standard Errors

Here is the complete list of the error symbols in standard Emacs, grouped by concept. The list includes each symbol's message (on the error-message property of the symbol) and a cross reference to a description of how the error can occur.

Each error symbol has an error-conditions property that is a list of symbols. Normally this list includes the error symbol itself and the symbol error. Occasionally it includes additional symbols, which are intermediate classifications, narrower than error but broader than a single error symbol. For example, all the errors in accessing files have the condition file-error. If we do not say here that a certain error symbol has additional error conditions, that means it has none.

As a special exception, the error symbol quit does not have the condition error, because quitting is not considered an error.

See section 10.5.3 Errors, for an explanation of how errors are generated and handled.

symbol
string; reference.

error
"error"
See section 10.5.3 Errors.

quit
"Quit"
See section 21.10 Quitting.

args-out-of-range
"Args out of range"
See section 6. Sequences, Arrays, and Vectors.

arith-error
"Arithmetic error"
See / and % in 3. Numbers.

beginning-of-buffer
"Beginning of buffer"
See section 30.2 Motion.

buffer-read-only
"Buffer is read-only"
See section 27.7 Read-Only Buffers.

coding-system-error
"Invalid coding system"
See section 33.10 Coding Systems.

cyclic-function-indirection
"Symbol's chain of function indirections\
contains a loop"
See section 9.2.4 Symbol Function Indirection.

end-of-buffer
"End of buffer"
See section 30.2 Motion.

end-of-file
"End of file during parsing"
Note that this is not a subcategory of file-error, because it pertains to the Lisp reader, not to file I/O. See section 19.3 Input Functions.

file-already-exists
This is a subcategory of file-error.
See section 25.4 Writing to Files.

file-date-error
This is a subcategory of file-error. It occurs when copy-file tries and fails to set the last-modification time of the output file. See section 25.7 Changing File Names and Attributes.

file-error
This error and its subcategories do not have error-strings, because the error message is constructed from the data items alone when the error condition file-error is present.
See section 25. Files.

file-locked
This is a subcategory of file-error.
See section 25.5 File Locks.

file-supersession
This is a subcategory of file-error.
See section 27.6 Comparison of Modification Time.

ftp-error
This is a subcategory of file-error, which results from problems in accessing a remote file using ftp.
See section `Remote Files' in The GNU Emacs Manual.

invalid-function
"Invalid function"
See section 9.2.3 Classification of List Forms.

invalid-read-syntax
"Invalid read syntax"
See section 19.3 Input Functions.

invalid-regexp
"Invalid regexp"
See section 34.2 Regular Expressions.

mark-inactive
"Mark inactive"
See section 31.7 The Mark.

no-catch
"No catch for tag"
See section 10.5.1 Explicit Nonlocal Exits: catch and throw.

scan-error
"Scan error"
This happens when certain syntax-parsing functions find invalid syntax or mismatched parentheses.
See section 30.2.6 Moving over Balanced Expressions, and 35.6 Parsing Balanced Expressions.

search-failed
"Search failed"
See section 34. Searching and Matching.

setting-constant
"Attempt to set a constant symbol"
The values of the symbols nil and t, and any symbols that start with `:', may not be changed.
See section Variables that Never Change.

text-read-only
"Text is read-only"
See section 32.19.4 Properties with Special Meanings.

undefined-color
"Undefined color"
See section 29.19 Color Names.

void-function
"Symbol's function definition is void"
See section 12.8 Accessing Function Cell Contents.

void-variable
"Symbol's value as variable is void"
See section 11.7 Accessing Variable Values.

wrong-number-of-arguments
"Wrong number of arguments"
See section 9.2.3 Classification of List Forms.

wrong-type-argument
"Wrong type argument"
See section 2.6 Type Predicates.
These kinds of error, which are classified as special cases of arith-error, can occur on certain systems for invalid use of mathematical functions.

domain-error
"Arithmetic domain error"
See section 3.9 Standard Mathematical Functions.

overflow-error
"Arithmetic overflow error"
See section 3.9 Standard Mathematical Functions.

range-error
"Arithmetic range error"
See section 3.9 Standard Mathematical Functions.

singularity-error
"Arithmetic singularity error"
See section 3.9 Standard Mathematical Functions.

underflow-error
"Arithmetic underflow error"
See section 3.9 Standard Mathematical Functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G. Buffer-Local Variables

The table below lists the general-purpose Emacs variables that automatically become buffer-local in each buffer. Most become buffer-local only when set; a few of them are always local in every buffer. Many Lisp packages define such variables for their internal use, but we don't try to list them all here.

abbrev-mode
See section 36. Abbrevs and Abbrev Expansion.

auto-fill-function
See section 32.14 Auto Filling.

buffer-auto-save-file-name
See section 26.2 Auto-Saving.

buffer-backed-up
See section 26.1 Backup Files.

buffer-display-count
See section 28.7 Displaying Buffers in Windows.

buffer-display-table
See section 38.17 Display Tables.

buffer-file-coding-system
See section 33.10.2 Encoding and I/O.

buffer-file-format
See section 25.12 File Format Conversion.

buffer-file-name
See section 27.4 Buffer File Name.

buffer-file-number
See section 27.4 Buffer File Name.

buffer-file-truename
See section 27.4 Buffer File Name.

buffer-file-type
See section 33.10.9 MS-DOS File Types.

buffer-invisibility-spec
See section 38.5 Invisible Text.

buffer-offer-save
See section 25.2 Saving Buffers.

buffer-read-only
See section 27.7 Read-Only Buffers.

buffer-saved-size
See section 30.1 Point.

buffer-undo-list
See section 32.9 Undo.

cache-long-line-scans
See section 30.2.4 Motion by Text Lines.

case-fold-search
See section 34.7 Searching and Case.

ctl-arrow
See section 38.16 Usual Display Conventions.

comment-column
See section `Comments' in The GNU Emacs Manual.

default-directory
See section 40.3 Operating System Environment.

defun-prompt-regexp
See section 30.2.6 Moving over Balanced Expressions.

enable-multibyte-characters
33. Non-ASCII Characters.

fill-column
See section 32.14 Auto Filling.

goal-column
See section `Moving Point' in The GNU Emacs Manual.

header-line-format
See section 23.3.1 The Data Structure of the Mode Line.

indicate-empty-lines
See section 38.16 Usual Display Conventions.

left-margin
See section 32.17 Indentation.

left-margin-width
See section 38.12.3 Displaying in the Margins.

local-abbrev-table
See section 36. Abbrevs and Abbrev Expansion.

local-write-file-hooks
See section 25.2 Saving Buffers.

major-mode
See section 23.1.4 Getting Help about a Major Mode.

mark-active
See section 31.7 The Mark.

mark-ring
See section 31.7 The Mark.

minor-modes
See section 23.2 Minor Modes.

mode-line-buffer-identification
See section 23.3.2 Variables Used in the Mode Line.

mode-line-format
See section 23.3.1 The Data Structure of the Mode Line.

mode-line-modified
See section 23.3.2 Variables Used in the Mode Line.

mode-line-process
See section 23.3.2 Variables Used in the Mode Line.

mode-name
See section 23.3.2 Variables Used in the Mode Line.

overwrite-mode
See section 32.4 Inserting Text.

paragraph-separate
See section 34.8 Standard Regular Expressions Used in Editing.

paragraph-start
See section 34.8 Standard Regular Expressions Used in Editing.

point-before-scroll
Used for communication between mouse commands and scroll-bar commands.

require-final-newline
See section 32.4 Inserting Text.

right-margin-width
See section 38.12.3 Displaying in the Margins.

scroll-down-aggressively
See section 28.11 Textual Scrolling.

scroll-up-aggressively
See section 28.11 Textual Scrolling.

selective-display
See section 38.6 Selective Display.

selective-display-ellipses
See section 38.6 Selective Display.

tab-width
See section 38.16 Usual Display Conventions.

truncate-lines
See section 38.3 Truncation.

vc-mode
See section 23.3.2 Variables Used in the Mode Line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H. Standard Keymaps

The following symbols are used as the names for various keymaps. Some of these exist when Emacs is first started, others are loaded only when their respective mode is used. This is not an exhaustive list.

Almost all of these maps are used as local maps. Indeed, of the modes that presently exist, only Vip mode and Terminal mode ever change the global keymap.

Buffer-menu-mode-map
A full keymap used by Buffer Menu mode.

c-mode-map
A sparse keymap used by C mode.

command-history-map
A full keymap used by Command History mode.

ctl-x-4-map
A sparse keymap for subcommands of the prefix C-x 4.

ctl-x-5-map
A sparse keymap for subcommands of the prefix C-x 5.

ctl-x-map
A full keymap for C-x commands.

debugger-mode-map
A full keymap used by Debugger mode.

dired-mode-map
A full keymap for dired-mode buffers.

edit-abbrevs-map
A sparse keymap used in edit-abbrevs.

edit-tab-stops-map
A sparse keymap used in edit-tab-stops.

electric-buffer-menu-mode-map
A full keymap used by Electric Buffer Menu mode.

electric-history-map
A full keymap used by Electric Command History mode.

emacs-lisp-mode-map
A sparse keymap used by Emacs Lisp mode.

facemenu-menu
The sparse keymap that displays the Text Properties menu.

facemenu-background-menu
The sparse keymap that displays the Background Color submenu of the Text Properties menu.

facemenu-face-menu
The sparse keymap that displays the Face submenu of the Text Properties menu.

facemenu-foreground-menu
The sparse keymap that displays the Foreground Color submenu of the Text Properties menu.

facemenu-indentation-menu
The sparse keymap that displays the Indentation submenu of the Text Properties menu.

facemenu-justification-menu
The sparse keymap that displays the Justification submenu of the Text Properties menu.

facemenu-special-menu
The sparse keymap that displays the Special Props submenu of the Text Properties menu.

function-key-map
The keymap for translating keypad and function keys.
If there are none, then it contains an empty sparse keymap. See section 40.8.2 Translating Input Events.

fundamental-mode-map
The sparse keymap for Fundamental mode.
It is empty and should not be changed.

Helper-help-map
A full keymap used by the help utility package.
It has the same keymap in its value cell and in its function cell.

Info-edit-map
A sparse keymap used by the e command of Info.

Info-mode-map
A sparse keymap containing Info commands.

isearch-mode-map
A keymap that defines the characters you can type within incremental search.

key-translation-map
A keymap for translating keys. This one overrides ordinary key bindings, unlike function-key-map. See section 40.8.2 Translating Input Events.

lisp-interaction-mode-map
A sparse keymap used by Lisp Interaction mode.

lisp-mode-map
A sparse keymap used by Lisp mode.

menu-bar-edit-menu
The keymap which displays the Edit menu in the menu bar.

menu-bar-files-menu
The keymap which displays the Files menu in the menu bar.

menu-bar-help-menu
The keymap which displays the Help menu in the menu bar.

menu-bar-mule-menu
The keymap which displays the Mule menu in the menu bar.

menu-bar-search-menu
The keymap which displays the Search menu in the menu bar.

menu-bar-tools-menu
The keymap which displays the Tools menu in the menu bar.

mode-specific-map
The keymap for characters following C-c. Note, this is in the global map. This map is not actually mode specific: its name was chosen to be informative for the user in C-h b (display-bindings), where it describes the main use of the C-c prefix key.

occur-mode-map
A sparse keymap used by Occur mode.

query-replace-map
A sparse keymap used for responses in query-replace and related commands; also for y-or-n-p and map-y-or-n-p. The functions that use this map do not support prefix keys; they look up one event at a time.

text-mode-map
A sparse keymap used by Text mode.

view-mode-map
A full keymap used by View mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I. Standard Hooks

The following is a list of hook variables that let you provide functions to be called from within Emacs on suitable occasions.

Most of these variables have names ending with `-hook'. They are normal hooks, run by means of run-hooks. The value of such a hook is a list of functions; the functions are called with no arguments and their values are completely ignored. The recommended way to put a new function on such a hook is to call add-hook. See section 23.6 Hooks, for more information about using hooks.

The variables whose names end in `-hooks' or `-functions' are usually abnormal hooks; their values are lists of functions, but these functions are called in a special way (they are passed arguments, or their values are used). A few of these variables are actually normal hooks which were named before we established the convention that normal hooks' names should end in `-hook'.

The variables whose names end in `-function' have single functions as their values. (In older Emacs versions, some of these variables had names ending in `-hook' even though they were not normal hooks; however, we have renamed all of those.)

activate-mark-hook

after-change-functions

after-init-hook

after-insert-file-functions

after-make-frame-functions

after-revert-hook

after-save-hook

apropos-mode-hook

auto-fill-function

auto-save-hook

before-change-functions

before-init-hook

before-make-frame-hook

before-revert-hook

blink-paren-function

buffer-access-fontify-functions

c-mode-hook

calendar-load-hook

change-major-mode-hook

command-history-hook

command-line-functions

comment-indent-function

deactivate-mark-hook

diary-display-hook

diary-hook

dired-mode-hook

disabled-command-hook

echo-area-clear-hook

edit-picture-hook

electric-buffer-menu-mode-hook

electric-command-history-hook

electric-help-mode-hook

emacs-lisp-mode-hook

find-file-hooks

find-file-not-found-hooks

first-change-hook

fortran-comment-hook

fortran-mode-hook

indent-mim-hook

initial-calendar-window-hook

kbd-macro-termination-hook

kill-buffer-hook

kill-buffer-query-functions

kill-emacs-hook

kill-emacs-query-functions

LaTeX-mode-hook

ledit-mode-hook

lisp-indent-function

lisp-interaction-mode-hook

lisp-mode-hook

list-diary-entries-hook

local-write-file-hooks

mail-mode-hook

mail-setup-hook

mark-diary-entries-hook

medit-mode-hook

menu-bar-update-hook

minibuffer-setup-hook

minibuffer-exit-hook

mouse-position-function

news-mode-hook

news-reply-mode-hook

news-setup-hook

nongregorian-diary-listing-hook

nongregorian-diary-marking-hook

nroff-mode-hook

outline-mode-hook

plain-TeX-mode-hook

post-command-hook

pre-abbrev-expand-hook

pre-command-hook

print-diary-entries-hook

prolog-mode-hook

protect-innocence-hook

redisplay-end-trigger-functions

rmail-edit-mode-hook

rmail-mode-hook

rmail-summary-mode-hook

scheme-indent-hook

scheme-mode-hook

scribe-mode-hook

shell-mode-hook

shell-set-directory-error-hook

suspend-hook

suspend-resume-hook

temp-buffer-show-function

term-setup-hook

terminal-mode-hook

terminal-mode-break-hook

TeX-mode-hook

text-mode-hook

today-visible-calendar-hook

today-invisible-calendar-hook

vi-mode-hook

view-hook

window-configuration-change-hook

window-scroll-functions

window-setup-hook

window-size-change-functions

write-contents-hooks

write-file-hooks

write-region-annotate-functions

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Index

Jump to:

" # $ % & ' ( ) * + , - . / 1 2 ; < = > ? @ [ \ ] ^ ` |
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

Index Entry

Section

"

`"' in printing

19.5 Output Functions

`"' in strings

2.3.8.1 Syntax for Strings

#

`#$'

16.3 Documentation Strings and Compilation

`#'' syntax

12.7 Anonymous Functions

`#@count'

16.3 Documentation Strings and Compilation

`#colon' read syntax

2.3.4 Symbol Type

`#n#' read syntax

2.5 Read Syntax for Circular Objects

`#n=' read syntax

2.5 Read Syntax for Circular Objects

$

`$' in display

38.3 Truncation

`$' in regexp

34.2.1.1 Special Characters in Regular Expressions

%

%

3.6 Arithmetic Operations

`%' in format

4.7 Formatting Strings

&

`&' in replacement

34.6.1 Replacing the Text that Matched

&define (Edebug)

18.2.15.1 Specification List

&not (Edebug)

18.2.15.1 Specification List

&optional

12.2.3 Other Features of Argument Lists

&optional (Edebug)

18.2.15.1 Specification List

&or (Edebug)

18.2.15.1 Specification List

&rest

12.2.3 Other Features of Argument Lists

&rest (Edebug)

18.2.15.1 Specification List

'

`'' for quoting

9.3 Quoting

(

`(' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

)

`)' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

*

*

3.6 Arithmetic Operations

`*' in interactive

21.2.1 Using interactive

`*' in regexp

34.2.1.1 Special Characters in Regular Expressions

`*scratch*'

23.1.3 How Emacs Chooses a Major Mode

+

+

3.6 Arithmetic Operations

`+' in regexp

34.2.1.1 Special Characters in Regular Expressions

,

, (with Backquote)

13.5 Backquote

,@ (with Backquote)

13.5 Backquote

-

-

3.6 Arithmetic Operations

.

`.' in lists

2.3.6.1 Dotted Pair Notation

`.' in regexp

34.2.1.1 Special Characters in Regular Expressions

`.emacs'

40.1.2 The Init File, `.emacs'

/

/

3.6 Arithmetic Operations

/=

3.4 Comparison of Numbers

1

1+

3.6 Arithmetic Operations

1-

3.6 Arithmetic Operations

2

2C-mode-map

22.5 Prefix Keys

;

`;' in comment

2.2 Comments

<

<

3.4 Comparison of Numbers

<=

3.4 Comparison of Numbers

=

=

3.4 Comparison of Numbers

>

>

3.4 Comparison of Numbers

>=

3.4 Comparison of Numbers

?

`?' in character constant

2.3.3 Character Type

? in minibuffer

20.2 Reading Text Strings with the Minibuffer

`?' in regexp

34.2.1.1 Special Characters in Regular Expressions

@

`@' in interactive

21.2.1 Using interactive

`(...)' in lists

2.3.6 Cons Cell and List Types

[

`[' in regexp

34.2.1.1 Special Characters in Regular Expressions

[...] (Edebug)

18.2.15.1 Specification List

\

`\' in character constant

2.3.3 Character Type

`\' in display

38.3 Truncation

`\' in printing

19.5 Output Functions

`\' in regexp

34.2.1.1 Special Characters in Regular Expressions

`\' in replacement

34.6.1 Replacing the Text that Matched

`\' in strings

2.3.8.1 Syntax for Strings

`\' in symbols

2.3.4 Symbol Type

`\'' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\<' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\=' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\>' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\`' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\a'

2.3.3 Character Type

`\b'

2.3.3 Character Type

`\b' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\B' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\e'

2.3.3 Character Type

`\f'

2.3.3 Character Type

`\n'

2.3.3 Character Type

`\n' in print

19.6 Variables Affecting Output

`\n' in replacement

34.6.1 Replacing the Text that Matched

`\r'

2.3.3 Character Type

`\s' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\S' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\t'

2.3.3 Character Type

`\v'

2.3.3 Character Type

`\W' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

`\w' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

]

`]' in regexp

34.2.1.1 Special Characters in Regular Expressions

^

`^' in regexp

34.2.1.1 Special Characters in Regular Expressions

`

`

13.5 Backquote

` (list substitution)

13.5 Backquote

|

`|' in regexp

34.2.1.3 Backslash Constructs in Regular Expressions

A

abbrev

36. Abbrevs and Abbrev Expansion

abbrev table

36. Abbrevs and Abbrev Expansion

abbrev tables in modes

23.1.1 Major Mode Conventions

abbrev-all-caps

36.5 Looking Up and Expanding Abbreviations

abbrev-expansion

36.5 Looking Up and Expanding Abbreviations

abbrev-file-name

36.4 Saving Abbrevs in Files

abbrev-mode

36.1 Setting Up Abbrev Mode

abbrev-prefix-mark

36.5 Looking Up and Expanding Abbreviations

abbrev-start-location

36.5 Looking Up and Expanding Abbreviations

abbrev-start-location-buffer

36.5 Looking Up and Expanding Abbreviations

abbrev-symbol

36.5 Looking Up and Expanding Abbreviations

abbrev-table-name-list

36.2 Abbrev Tables

abbreviate-file-name

25.8.2 Directory Names

abbrevs-changed

36.4 Saving Abbrevs in Files

abnormal hook

23.6 Hooks

abort-recursive-edit

21.12 Recursive Editing

aborting

21.12 Recursive Editing

abs

3.4 Comparison of Numbers

absolute file name

25.8.3 Absolute and Relative File Names

accept-process-output

37.9.3 Accepting Output from Processes

access-file

25.6.1 Testing Accessibility

accessibility of a file

25.6.1 Testing Accessibility

accessible portion (of a buffer)

30.4 Narrowing

accessible-keymaps

22.11 Scanning Keymaps

accessing data of mouse events

21.6.13 Accessing Events

acos

3.9 Standard Mathematical Functions

activate-mark-hook

31.7 The Mark

activating advice

17.5 Activation of Advice

active display table

38.17.2 Active Display Table

active keymap

22.6 Active Keymaps

active-minibuffer-window

20.9 Minibuffer Miscellany

ad-activate

17.5 Activation of Advice

ad-activate-all

17.5 Activation of Advice

ad-activate-regexp

17.5 Activation of Advice

ad-add-advice

17.4 Computed Advice

ad-deactivate

17.5 Activation of Advice

ad-deactivate-all

17.5 Activation of Advice

ad-deactivate-regexp

17.5 Activation of Advice

ad-default-compilation-action

17.5 Activation of Advice

ad-define-subr-args

17.9 Definition of Subr Argument Lists

ad-disable-advice

17.6 Enabling and Disabling Advice

ad-disable-regexp

17.6 Enabling and Disabling Advice

ad-do-it

17.3 Around-Advice

ad-enable-advice

17.6 Enabling and Disabling Advice

ad-enable-regexp

17.6 Enabling and Disabling Advice

ad-get-arg

17.8 Argument Access in Advice

ad-get-args

17.8 Argument Access in Advice

ad-return-value

17.2 Defining Advice

ad-set-arg

17.8 Argument Access in Advice

ad-set-args

17.8 Argument Access in Advice

ad-start-advice

17.5 Activation of Advice

ad-stop-advice

17.5 Activation of Advice

ad-unadvise

17.2 Defining Advice

ad-unadvise-all

17.2 Defining Advice

ad-update

17.5 Activation of Advice

ad-update-all

17.5 Activation of Advice

ad-update-regexp

17.5 Activation of Advice

Adaptive Fill mode

32.13 Adaptive Fill Mode

adaptive-fill-first-line-regexp

32.13 Adaptive Fill Mode

adaptive-fill-function

32.13 Adaptive Fill Mode

adaptive-fill-mode

32.13 Adaptive Fill Mode

adaptive-fill-regexp

32.13 Adaptive Fill Mode

add-abbrev

36.3 Defining Abbrevs

add-hook

23.6 Hooks

add-name-to-file

25.7 Changing File Names and Attributes

add-text-properties

32.19.2 Changing Text Properties

add-to-invisibility-spec

38.5 Invisible Text

add-to-list

11.8 How to Alter a Variable Value

address field of register

2.3.6 Cons Cell and List Types

advice, activating

17.5 Activation of Advice

advice, deactivating

17.5 Activation of Advice

advice, defining

17.2 Defining Advice

advice, enabling and disabling

17.6 Enabling and Disabling Advice

advice, preactivating

17.7 Preactivation

advising functions

17. Advising Emacs Lisp Functions

after-advice

17.2 Defining Advice

after-change-functions

32.25 Change Hooks

after-find-file

25.1.2 Subroutines of Visiting

after-init-hook

40.1.2 The Init File, `.emacs'

after-insert-file-functions

32.19.7 Saving Text Properties in Files

after-load-alist

15.8 Hooks for Loading

after-make-frame-functions

29.1 Creating Frames

after-revert-hook

26.3 Reverting

after-save-hook

25.2 Saving Buffers

after-string (overlay property)

38.9.1 Overlay Properties

alist

5.8 Association Lists

all-christian-calendar-holidays

39.2 Customizing the Holidays

all-completions

20.5.1 Basic Completion Functions

all-hebrew-calendar-holidays

39.2 Customizing the Holidays

all-islamic-calendar-holidays

39.2 Customizing the Holidays

alt characters

2.3.3 Character Type

and

10.3 Constructs for Combining Conditions

anonymous function

12.7 Anonymous Functions

anonymous lambda expressions (Edebug)

18.2.2 Instrumenting for Edebug

apostrophe for quoting

9.3 Quoting

append

5.5 Building Cons Cells and Lists

append-to-file

25.4 Writing to Files

apply

12.5 Calling Functions

apply, and debugging

18.1.8 Internals of the Debugger

appt-audible

39.10 Customizing Appointment Reminders

appt-delete-window-function

39.10 Customizing Appointment Reminders

appt-disp-window-function

39.10 Customizing Appointment Reminders

appt-display-duration

39.10 Customizing Appointment Reminders

appt-display-mode-line

39.10 Customizing Appointment Reminders

appt-message-warning-time

39.10 Customizing Appointment Reminders

appt-msg-window

39.10 Customizing Appointment Reminders

appt-visible

39.10 Customizing Appointment Reminders

apropos

24.5 Help Functions

aref

6.3 Functions that Operate on Arrays

argument binding

12.2.3 Other Features of Argument Lists

argument descriptors

21.2.1 Using interactive

argument evaluation form

21.2.1 Using interactive

argument prompt

21.2.1 Using interactive

arguments, reading

20. Minibuffers

arith-error example

10.5.3.3 Writing Code to Handle Errors

arith-error in division

3.6 Arithmetic Operations

arithmetic shift

3.8 Bitwise Operations on Integers

around-advice

17.2 Defining Advice

array

6.2 Arrays

array elements

6.3 Functions that Operate on Arrays

arrayp

6.3 Functions that Operate on Arrays

ASCII character codes

2.3.3 Character Type

aset

6.3 Functions that Operate on Arrays

ash

3.8 Bitwise Operations on Integers

asin

3.9 Standard Mathematical Functions

ask-user-about-lock

25.5 File Locks

ask-user-about-supersession-threat

27.6 Comparison of Modification Time

asking the user questions

20.6 Yes-or-No Queries

assoc

5.8 Association Lists

assoc-default

5.8 Association Lists

assoc-ignore-case

4.5 Comparison of Characters and Strings

assoc-ignore-representation

4.5 Comparison of Characters and Strings

association list

5.8 Association Lists

assq

5.8 Association Lists

assq-delete-all

5.8 Association Lists

asynchronous subprocess

37.4 Creating an Asynchronous Process

atan

3.9 Standard Mathematical Functions

atom

5.3 Predicates on Lists

atoms

5.3 Predicates on Lists

attributes of text

32.19 Text Properties

Auto Fill mode

32.14 Auto Filling

auto-coding-regexp-alist

33.10.5 Default Coding Systems

auto-fill-chars

32.14 Auto Filling

auto-fill-function

32.14 Auto Filling

auto-mode-alist

23.1.3 How Emacs Chooses a Major Mode

auto-raise-tool-bar-items

22.12.6 Tool bars

auto-resize-tool-bar

22.12.6 Tool bars

auto-save-default

26.2 Auto-Saving

auto-save-file-format

25.12 File Format Conversion

auto-save-file-name-p

26.2 Auto-Saving

auto-save-hook

26.2 Auto-Saving

auto-save-interval

26.2 Auto-Saving

auto-save-list-file-name

26.2 Auto-Saving

auto-save-list-file-prefix

26.2 Auto-Saving

auto-save-mode

26.2 Auto-Saving

auto-save-timeout

26.2 Auto-Saving

auto-save-visited-file-name

26.2 Auto-Saving

auto-saving

26.2 Auto-Saving

autoload

15.4 Autoload

autoload errors

15.4 Autoload

automatic face assignment

38.11.8 Automatic Face Assignment

automatically buffer-local

11.10.1 Introduction to Buffer-Local Variables

B

back-to-indentation

32.17.6 Indentation-Based Motion Commands

backquote (list substitution)

13.5 Backquote

backslash in character constant

2.3.3 Character Type

backslash in strings

2.3.8.1 Syntax for Strings

backslash in symbols

2.3.4 Symbol Type

backspace

2.3.3 Character Type

backtrace

18.1.8 Internals of the Debugger

backtrace-debug

18.1.8 Internals of the Debugger

backtrace-frame

18.1.8 Internals of the Debugger

backtracking

18.2.15.2 Backtracking in Specifications

backup file

26.1 Backup Files

backup files, how to make them

26.1.2 Backup by Renaming or by Copying?

backup-buffer

26.1.1 Making Backup Files

backup-by-copying

26.1.2 Backup by Renaming or by Copying?

backup-by-copying-when-linked

26.1.2 Backup by Renaming or by Copying?

backup-by-copying-when-mismatch

26.1.2 Backup by Renaming or by Copying?

backup-by-copying-when-privileged-mismatch

26.1.2 Backup by Renaming or by Copying?

backup-directory-alist

26.1.1 Making Backup Files

backup-enable-predicate

26.1.1 Making Backup Files

backup-file-name-p

26.1.4 Naming Backup Files

backup-inhibited

26.1.1 Making Backup Files

backward-char

30.2.1 Motion by Characters

backward-delete-char-untabify

32.6 Deleting Text

backward-delete-char-untabify-method

32.6 Deleting Text

backward-list

30.2.6 Moving over Balanced Expressions

backward-prefix-chars

35.5 Motion and Syntax

backward-sexp

30.2.6 Moving over Balanced Expressions

backward-to-indentation

32.17.6 Indentation-Based Motion Commands

backward-word

30.2.2 Motion by Words

balancing parentheses

38.14 Blinking Parentheses

barf-if-buffer-read-only

27.7 Read-Only Buffers

base 64 encoding

32.23 Base 64 Encoding

base buffer

27.11 Indirect Buffers

base coding system

33.10.1 Basic Concepts of Coding Systems

base for reading an integer

3.1 Integer Basics

base64-decode-region

32.23 Base 64 Encoding

base64-decode-string

32.23 Base 64 Encoding

base64-encode-region

32.23 Base 64 Encoding

base64-encode-string

32.23 Base 64 Encoding

basic code (of input character)

21.6.1 Keyboard Events

batch mode

40.13 Batch Mode

batch-byte-compile

16.2 The Compilation Functions

baud-rate

40.9 Terminal Output

beep

38.18 Beeping

beeping

38.18 Beeping

before point, insertion

32.4 Inserting Text

before-advice

17.2 Defining Advice

before-change-functions

32.25 Change Hooks

before-init-hook

40.1.2 The Init File, `.emacs'

before-make-frame-hook

29.1 Creating Frames

before-revert-hook

26.3 Reverting

before-string (overlay property)

38.9.1 Overlay Properties

beginning of line

30.2.4 Motion by Text Lines

beginning of line in regexp

34.2.1.1 Special Characters in Regular Expressions

beginning-of-buffer

30.2.3 Motion to an End of the Buffer

beginning-of-defun

30.2.6 Moving over Balanced Expressions

beginning-of-defun-function

30.2.6 Moving over Balanced Expressions

beginning-of-line

30.2.4 Motion by Text Lines

bell

38.18 Beeping

bell character

2.3.3 Character Type

binary files and text files

33.10.9 MS-DOS File Types

binding arguments

12.2.3 Other Features of Argument Lists

binding local variables

11.3 Local Variables

binding of a key

22.1 Keymap Terminology

bitmap-spec-p

38.11.3 Face Attributes

bitwise and

3.8 Bitwise Operations on Integers

bitwise exclusive or

3.8 Bitwise Operations on Integers

bitwise not

3.8 Bitwise Operations on Integers

bitwise or

3.8 Bitwise Operations on Integers

blink-matching-delay

38.14 Blinking Parentheses

blink-matching-open

38.14 Blinking Parentheses

blink-matching-paren

38.14 Blinking Parentheses

blink-matching-paren-distance

38.14 Blinking Parentheses

blink-paren-function

38.14 Blinking Parentheses

blinking

38.14 Blinking Parentheses

bobp

32.1 Examining Text Near Point

body of function

12.2.1 Components of a Lambda Expression

bold (face name)

38.11.1 Standard Faces

bold-italic (face name)

38.11.1 Standard Faces

bolp

32.1 Examining Text Near Point

bool-vector-p

6.7 Bool-vectors

Bool-vectors

6.7 Bool-vectors

boolean

1.3.2 nil and t

boundp

11.4 When a Variable is "Void"

box diagrams, for lists

2.3.6 Cons Cell and List Types

box representation for lists

5.2 Lists as Linked Pairs of Boxes

break

18.1 The Lisp Debugger

breakpoints

18.2.6 Breakpoints

bucket (in obarray)

8.3 Creating and Interning Symbols

buffer

27. Buffers

buffer contents

32. Text

buffer file name

27.4 Buffer File Name

buffer input stream

19.2 Input Streams

buffer internals

E.6.1 Buffer Internals

buffer list

27.8 The Buffer List

buffer modification

27.5 Buffer Modification

buffer names

27.3 Buffer Names

buffer output stream

19.4 Output Streams

buffer text notation

1.3.6 Buffer Text Notation

buffer, read-only

27.7 Read-Only Buffers

buffer-access-fontified-property

32.19.8 Lazy Computation of Text Properties

buffer-access-fontify-functions

32.19.8 Lazy Computation of Text Properties

buffer-auto-save-file-name

26.2 Auto-Saving

buffer-backed-up

26.1.1 Making Backup Files

buffer-base-buffer

27.11 Indirect Buffers

buffer-disable-undo

32.10 Maintaining Undo Lists

buffer-display-table

38.17.2 Active Display Table

buffer-display-time

28.6 Buffers and Windows

buffer-enable-undo

32.10 Maintaining Undo Lists

buffer-end

30.1 Point

buffer-file-coding-system

33.10.2 Encoding and I/O

buffer-file-format

25.12 File Format Conversion

buffer-file-name

27.4 Buffer File Name

buffer-file-number

27.4 Buffer File Name

buffer-file-truename

27.4 Buffer File Name

buffer-file-type

33.10.9 MS-DOS File Types

buffer-flush-undo

32.10 Maintaining Undo Lists

buffer-has-markers-at

31.4 Information from Markers

buffer-invisibility-spec

38.5 Invisible Text

buffer-list

27.8 The Buffer List

buffer-local variables

11.10 Buffer-Local Variables

buffer-local variables in modes

23.1.1 Major Mode Conventions

buffer-local-variables

11.10.2 Creating and Deleting Buffer-Local Bindings

Buffer-menu-mode-map

H. Standard Keymaps

buffer-modified-p

27.5 Buffer Modification

buffer-modified-tick

27.5 Buffer Modification

buffer-name

27.3 Buffer Names

buffer-name-history

20.4 Minibuffer History

buffer-offer-save

27.10 Killing Buffers

buffer-read-only

27.7 Read-Only Buffers

buffer-saved-size

26.2 Auto-Saving

buffer-size

30.1 Point

buffer-string

32.2 Examining Buffer Contents

buffer-substring

32.2 Examining Buffer Contents

buffer-substring-no-properties

32.2 Examining Buffer Contents

buffer-undo-list

32.9 Undo

bufferp

27.1 Buffer Basics

buffers, controlled in windows

28.6 Buffers and Windows

buffers, creating

27.9 Creating Buffers

buffers, killing

27.10 Killing Buffers

building Emacs

E.1 Building Emacs

building lists

5.5 Building Cons Cells and Lists

built-in function

12.1 What Is a Function?

bury-buffer

27.8 The Buffer List

butlast

5.4 Accessing Elements of Lists

button-down event

21.6.6 Button-Down Events

byte-boolean-vars

E.5 Writing Emacs Primitives

byte-code

16.2 The Compilation Functions

byte-code function

16.6 Byte-Code Function Objects

byte-code interpreter

16.2 The Compilation Functions

byte-code-function-p

12.1 What Is a Function?

byte-compile

16.2 The Compilation Functions

byte-compile-dynamic

16.4 Dynamic Loading of Individual Functions

byte-compile-dynamic-docstrings

16.3 Documentation Strings and Compilation

byte-compile-file

16.2 The Compilation Functions

byte-compiling macros

13.3 Macros and Byte Compilation

byte-compiling require

15.6 Features

byte-recompile-directory

16.2 The Compilation Functions

byte-to-position

33.1 Text Representations

bytes

4. Strings and Characters

bytes and characters

33.6 Characters and Bytes

C

C-c

22.5 Prefix Keys

C-g

21.10 Quitting

C-h

22.5 Prefix Keys

C-M-x

18.2.2 Instrumenting for Edebug

c-mode-map

H. Standard Keymaps

c-mode-syntax-table

35.7 Some Standard Syntax Tables

C-q

40.12 Flow Control

C-s

40.12 Flow Control

C-x

22.5 Prefix Keys

C-x 4

22.5 Prefix Keys

C-x 5

22.5 Prefix Keys

C-x 6

22.5 Prefix Keys

C-x RET

22.5 Prefix Keys

C-x v

22.5 Prefix Keys

caar

5.4 Accessing Elements of Lists

cache-long-line-scans

38.3 Truncation

cadr

5.4 Accessing Elements of Lists

calendar-date-display-form

39.3 Date Display Format

calendar-daylight-savings-ends

39.5 Daylight Savings Time

calendar-daylight-savings-ends-time

39.5 Daylight Savings Time

calendar-daylight-savings-starts

39.5 Daylight Savings Time

calendar-daylight-savings-starts-time

39.5 Daylight Savings Time

calendar-daylight-time-offset

39.5 Daylight Savings Time

calendar-holiday-marker

39.1 Customizing the Calendar

calendar-holidays

39.2 Customizing the Holidays

calendar-load-hook

39.1 Customizing the Calendar

calendar-mark-today

39.1 Customizing the Calendar

calendar-move-hook

39.1 Customizing the Calendar

calendar-star-date

39.1 Customizing the Calendar

calendar-time-display-form

39.4 Time Display Format

calendar-today-marker

39.1 Customizing the Calendar

call stack

18.1.8 Internals of the Debugger

call-interactively

21.3 Interactive Call

call-process

37.3 Creating a Synchronous Process

call-process-region

37.3 Creating a Synchronous Process

calling a function

12.5 Calling Functions

cancel-debug-on-entry

18.1.3 Entering the Debugger on a Function Call

cancel-timer

40.7 Timers for Delayed Execution

candle lighting times

39.9 Sexp Entries and the Fancy Diary Display

capitalization

4.8 Case Conversion in Lisp

capitalize

4.8 Case Conversion in Lisp

capitalize-region

32.18 Case Changes

capitalize-word

32.18 Case Changes

car

5.4 Accessing Elements of Lists

car-safe

5.4 Accessing Elements of Lists

case conversion in buffers

32.18 Case Changes

case conversion in Lisp

4.8 Case Conversion in Lisp

case in replacements

34.6.1 Replacing the Text that Matched

case-fold-search

34.7 Searching and Case

case-replace

34.7 Searching and Case

case-table-p

4.9 The Case Table

catch

10.5.1 Explicit Nonlocal Exits: catch and throw

categories of characters

35.9 Categories

category (overlay property)

38.9.1 Overlay Properties

category (text property)

32.19.4 Properties with Special Meanings

category of text character

32.19.4 Properties with Special Meanings

category-docstring

35.9 Categories

category-set-mnemonics

35.9 Categories

category-table

35.9 Categories

category-table-p

35.9 Categories

CBREAK

40.12 Flow Control

cdar

5.4 Accessing Elements of Lists

cddr

5.4 Accessing Elements of Lists

cdr

5.4 Accessing Elements of Lists

cdr-safe

5.4 Accessing Elements of Lists

ceiling

3.5 Numeric Conversions

centering point

28.11 Textual Scrolling

change hooks

32.25 Change Hooks

change hooks for a character

32.19.4 Properties with Special Meanings

change-major-mode-hook

11.10.2 Creating and Deleting Buffer-Local Bindings

changing key bindings

22.9 Changing Key Bindings

changing to another buffer

27.2 The Current Buffer

changing window size

28.15 Changing the Size of a Window

char-after

32.1 Examining Text Near Point

char-before

32.1 Examining Text Near Point

char-category-set

35.9 Categories

char-charset

33.5 Character Sets

char-equal

4.5 Comparison of Characters and Strings

char-or-string-p

4.2 The Predicates for Strings

char-syntax

35.3 Syntax Table Functions

char-table-extra-slot

6.6 Char-Tables

char-table-p

6.6 Char-Tables

char-table-parent

6.6 Char-Tables

char-table-range

6.6 Char-Tables

char-table-subtype

6.6 Char-Tables

char-tables

6.6 Char-Tables

char-to-string

4.6 Conversion of Characters and Strings

char-valid-p

33.4 Character Codes

char-width

38.10 Width

character alternative (in regexp)

34.2.1.1 Special Characters in Regular Expressions

character arrays

4. Strings and Characters

character case

4.8 Case Conversion in Lisp

character classes in regexp

34.2.1.2 Character Classes

character code conversion

33.10.1 Basic Concepts of Coding Systems

character codes

33.4 Character Codes

character insertion

32.5 User-Level Insertion Commands

character printing

24.4 Describing Characters for Help Messages

character quote

35.2.1 Table of Syntax Classes

character sets

33.5 Character Sets

character to string

4.6 Conversion of Characters and Strings

character translation tables

33.9 Translation of Characters

characters

4. Strings and Characters

characters for interactive codes

21.2.2 Code Characters for interactive

charset-bytes

33.6 Characters and Bytes

charset-dimension

33.6 Characters and Bytes

charset-list

33.5 Character Sets

charset-plist

33.5 Character Sets

charsetp

33.5 Character Sets

check-coding-system

33.10.3 Coding Systems in Lisp

checkdoc-minor-mode

D.3 Tips for Documentation Strings

child process

37. Processes

christian-holidays

39.2 Customizing the Holidays

circular structure, read syntax

2.5 Read Syntax for Circular Objects

cl

1.2 Lisp History

CL note---rplaca vrs setcar

5.6 Modifying Existing List Structure

CL note---set local

11.8 How to Alter a Variable Value

CL note--allocate more storage

E.3 Garbage Collection

CL note--case of letters

2.3.4 Symbol Type

CL note--default optional arg

12.2.3 Other Features of Argument Lists

CL note--integers vrs eq

3.4 Comparison of Numbers

CL note--interning existing symbol

8.3 Creating and Interning Symbols

CL note--lack union, intersection

5.7 Using Lists as Sets

CL note--no continuable errors

10.5.3.1 How to Signal an Error

CL note--only throw in Emacs

10.5.1 Explicit Nonlocal Exits: catch and throw

CL note--special forms compared

9.2.7 Special Forms

CL note--special variables

11.9 Scoping Rules for Variable Bindings

CL note--symbol in obarrays

8.3 Creating and Interning Symbols

cl-specs.el

18.2.2 Instrumenting for Edebug

cl.el (Edebug)

18.2.2 Instrumenting for Edebug

class of advice

17.2 Defining Advice

cleanup forms

10.5.4 Cleaning Up from Nonlocal Exits

clear-abbrev-table

36.2 Abbrev Tables

clear-face-cache

38.11.6 Font Selection

clear-image-cache

38.13.9 Image Cache

clear-this-command-keys

21.4 Information from the Command Loop

clear-visited-file-modtime

27.6 Comparison of Modification Time

click event

21.6.4 Click Events

clickable text

32.19.9 Defining Clickable Text

clipboard support (for MS-Windows)

29.18 Window System Selections

close parenthesis

38.14 Blinking Parentheses

close parenthesis character

35.2.1 Table of Syntax Classes

closures not available

11.9.2 Extent

clrhash

7.2 Hash Table Access

codes, interactive, description of

21.2.2 Code Characters for interactive

coding standards

D. Tips and Conventions

coding system

33.10 Coding Systems

coding-system-change-eol-conversion

33.10.3 Coding Systems in Lisp

coding-system-change-text-conversion

33.10.3 Coding Systems in Lisp

coding-system-for-read

33.10.6 Specifying a Coding System for One Operation

coding-system-for-write

33.10.6 Specifying a Coding System for One Operation

coding-system-get

33.10.1 Basic Concepts of Coding Systems

coding-system-list

33.10.3 Coding Systems in Lisp

coding-system-p

33.10.3 Coding Systems in Lisp

color-defined-p

29.19 Color Names

color-gray-p

29.19 Color Names

color-supported-p

29.19 Color Names

color-values

29.19 Color Names

colors on text-only terminals

29.20 Text Terminal Colors

columns

32.16 Counting Columns

combine-after-change-calls

32.25 Change Hooks

command

12.1 What Is a Function?

command descriptions

1.3.7.1 A Sample Function Description

command history

21.14 Command History

command in keymap

22.7 Key Lookup

command loop

21. Command Loop

command loop, recursive

21.12 Recursive Editing

command-debug-status

18.1.8 Internals of the Debugger

command-execute

21.3 Interactive Call

command-history

21.14 Command History

command-history-map

H. Standard Keymaps

command-line

40.1.4 Command-Line Arguments

command-line arguments

40.1.4 Command-Line Arguments

command-line options

40.1.4 Command-Line Arguments

command-line-args

40.1.4 Command-Line Arguments

command-line-functions

40.1.4 Command-Line Arguments

command-line-processed

40.1.4 Command-Line Arguments

command-switch-alist

40.1.4 Command-Line Arguments

commandp

21.3 Interactive Call

commandp example

20.5.4 High-Level Completion Functions

commands, defining

21.2 Defining Commands

comment ender

35.2.1 Table of Syntax Classes

comment starter

35.2.1 Table of Syntax Classes

comment syntax

35.2.1 Table of Syntax Classes

comments

2.2 Comments

Common Lisp

1.2 Lisp History

Common Lisp (Edebug)

18.2.2 Instrumenting for Edebug

compare-buffer-substrings

32.3 Comparing Text

compare-strings

4.5 Comparison of Characters and Strings

compare-window-configurations

28.17 Window Configurations

comparing buffer text

32.3 Comparing Text

comparison of modification time

27.6 Comparison of Modification Time

compilation

16. Byte Compilation

compilation functions

16.2 The Compilation Functions

compile-defun

16.2 The Compilation Functions

compiled function

16.6 Byte-Code Function Objects

complete key

22.1 Keymap Terminology

completing-read

20.5.2 Completion and the Minibuffer

completion

20.5 Completion

completion, file name

25.8.6 File Name Completion

completion-auto-help

20.5.3 Minibuffer Commands that Do Completion

completion-ignore-case

20.5.1 Basic Completion Functions

completion-ignored-extensions

25.8.6 File Name Completion

complex arguments

20. Minibuffers

complex command

21.14 Command History

compute-motion

30.2.5 Motion by Screen Lines

concat

4.3 Creating Strings

concatenating lists

5.6.3 Functions that Rearrange Lists

concatenating strings

4.3 Creating Strings

cond

10.2 Conditionals

condition name

10.5.3.4 Error Symbols and Condition Names

condition-case

10.5.3.3 Writing Code to Handle Errors

conditional display specifications

38.12.4 Conditional Display Specifications

conditional evaluation

10.2 Conditionals

conditional selection of windows

28.4 Selecting Windows

cons

5.5 Building Cons Cells and Lists

cons cell as box

5.2 Lists as Linked Pairs of Boxes

cons cells

5.5 Building Cons Cells and Lists

cons-cells-consed

E.4 Memory Usage

consing

5.5 Building Cons Cells and Lists

consp

5.3 Predicates on Lists

constrain-to-field

32.19.10 Defining and Using Fields

continuation lines

38.3 Truncation

continue-process

37.8 Sending Signals to Processes

control character key constants

22.9 Changing Key Bindings

control character printing

24.4 Describing Characters for Help Messages

control characters

2.3.3 Character Type

control characters in display

38.16 Usual Display Conventions

control characters, reading

21.7.4 Quoted Character Input

control structures

10. Control Structures

Control-X-prefix

22.5 Prefix Keys

conventions for writing minor modes

23.2.1 Conventions for Writing Minor Modes

conversion of strings

4.6 Conversion of Characters and Strings

convert-standard-filename

25.8.7 Standard File Names

coordinates-in-window-p

28.16 Coordinates and Windows

copy-alist

5.8 Association Lists

copy-category-table

35.9 Categories

copy-face

38.11.7 Functions for Working with Faces

copy-file

25.7 Changing File Names and Attributes

copy-hash-table

7.4 Other Hash Table Functions

copy-keymap

22.3 Creating Keymaps

copy-marker

31.3 Functions that Create Markers

copy-region-as-kill

32.8.2 Functions for Killing

copy-sequence

6.1 Sequences

copy-syntax-table

35.3 Syntax Table Functions

copying alists

5.8 Association Lists

copying files

25.7 Changing File Names and Attributes

copying lists

5.5 Building Cons Cells and Lists

copying sequences

6.1 Sequences

copying strings

4.3 Creating Strings

copying vectors

6.5 Functions for Vectors

cos

3.9 Standard Mathematical Functions

count-lines

30.2.4 Motion by Text Lines

count-loop

1.3.7.1 A Sample Function Description

count-screen-lines

30.2.5 Motion by Screen Lines

counting columns

32.16 Counting Columns

coverage testing

18.2.13 Coverage Testing

create-file-buffer

25.1.2 Subroutines of Visiting

create-fontset-from-fontset-spec

38.11.10 Fontsets

create-glyph

38.17.3 Glyphs

create-image

38.13.7 Defining Images

creating buffers

27.9 Creating Buffers

creating keymaps

22.3 Creating Keymaps

ctl-arrow

38.16 Usual Display Conventions

ctl-x-4-map

22.5 Prefix Keys

ctl-x-5-map

22.5 Prefix Keys

ctl-x-map

22.5 Prefix Keys

current binding

11.3 Local Variables

current buffer

27.2 The Current Buffer

current buffer excursion

30.3 Excursions

current buffer mark

31.7 The Mark

current buffer point and mark (Edebug)

18.2.14.2 Edebug Display Update

current buffer position

30.1 Point

current command

21.4 Information from the Command Loop

current stack frame

18.1.5 Using the Debugger

current-buffer

27.2 The Current Buffer

current-case-table

4.9 The Case Table

current-column

32.16 Counting Columns

current-fill-column

32.12 Margins for Filling

current-frame-configuration

29.12 Frame Configurations

current-global-map

22.6 Active Keymaps

current-indentation

32.17.1 Indentation Primitives

current-input-method

33.11 Input Methods

current-input-mode

40.8.1 Input Modes

current-justification

32.11 Filling

current-kill

32.8.4 Low-Level Kill Ring

current-left-margin

32.12 Margins for Filling

current-local-map

22.6 Active Keymaps

current-message

38.4 The Echo Area

current-minor-mode-maps

22.6 Active Keymaps

current-prefix-arg

21.11 Prefix Command Arguments

current-time

40.5 Time of Day

current-time-string

40.5 Time of Day

current-time-zone

40.5 Time of Day

current-window-configuration

28.17 Window Configurations

cursor-in-echo-area

38.4 The Echo Area

cursor-type

29.3.3 Window Frame Parameters

cust-print

18.2.11 Printing in Edebug

custom-add-option

14.3 Defining Customization Variables

cut buffer

29.18 Window System Selections

cyclic ordering of windows

28.5 Cyclic Ordering of Windows

D

data type

2. Lisp Data Types

data-directory

24.5 Help Functions

daylight savings time

39.5 Daylight Savings Time

deactivate-mark

31.7 The Mark

deactivate-mark-hook

31.7 The Mark

deactivating advice

17.5 Activation of Advice

debug

18.1.7 Invoking the Debugger

debug-ignored-errors

18.1.1 Entering the Debugger on an Error

debug-on-entry

18.1.3 Entering the Debugger on a Function Call

debug-on-error

18.1.1 Entering the Debugger on an Error

debug-on-error use

10.5.3.2 How Emacs Processes Errors

debug-on-next-call

18.1.8 Internals of the Debugger

debug-on-quit

18.1.2 Debugging Infinite Loops

debug-on-signal

18.1.1 Entering the Debugger on an Error

debugger

18.1.8 Internals of the Debugger

debugger command list

18.1.6 Debugger Commands

debugger-mode-map

H. Standard Keymaps

debugging errors

18.1.1 Entering the Debugger on an Error

debugging specific functions

18.1.3 Entering the Debugger on a Function Call

decode-coding-region

33.10.7 Explicit Encoding and Decoding

decode-coding-string

33.10.7 Explicit Encoding and Decoding

decode-time

40.6 Time Conversion

decoding file formats

25.12 File Format Conversion

decoding text

33.10.7 Explicit Encoding and Decoding

decrement field of register

2.3.6 Cons Cell and List Types

dedicated window

28.8 Choosing a Window for Display

deep binding

11.9.3 Implementation of Dynamic Scoping

def-edebug-spec

18.2.15 Instrumenting Macro Calls

defadvice

17.2 Defining Advice

defalias

12.4 Defining Functions

default (face name)

38.11.1 Standard Faces

default argument string

21.2.2 Code Characters for interactive

default init file

40.1.2 The Init File, `.emacs'

default key binding

22.2 Format of Keymaps

default value

11.10.3 The Default Value of a Buffer-Local Variable

default value of char-table

6.6 Char-Tables

default-abbrev-mode

36.1 Setting Up Abbrev Mode

default-boundp

11.10.3 The Default Value of a Buffer-Local Variable

default-buffer-file-type

33.10.9 MS-DOS File Types

default-case-fold-search

34.7 Searching and Case

default-ctl-arrow

38.16 Usual Display Conventions

default-directory

25.8.4 Functions that Expand Filenames

default-enable-multibyte-characters

33.1 Text Representations

default-file-modes

25.7 Changing File Names and Attributes

default-fill-column

32.12 Margins for Filling

default-frame-alist

29.3.2 Initial Frame Parameters

default-header-line-format

23.3.5 Window Header Lines

default-input-method

33.11 Input Methods

default-justification

32.11 Filling

default-major-mode

23.1.3 How Emacs Chooses a Major Mode

default-minibuffer-frame

29.8 Minibuffers and Frames

default-mode-line-format

23.3.2 Variables Used in the Mode Line

default-process-coding-system

33.10.5 Default Coding Systems

default-text-properties

32.19.1 Examining Text Properties

default-truncate-lines

38.3 Truncation

default-value

11.10.3 The Default Value of a Buffer-Local Variable

`default.el'

40.1.1 Summary: Sequence of Actions at Startup

defconst

11.5 Defining Global Variables

defcustom

14.3 Defining Customization Variables

defface

38.11.2 Defining Faces

defgroup

14.2 Defining Custom Groups

defimage

38.13.7 Defining Images

define-abbrev

36.3 Defining Abbrevs

define-abbrev-table

36.2 Abbrev Tables

define-category

35.9 Categories

define-derived-mode

23.1.5 Defining Derived Modes

define-hash-table-test

7.3 Defining Hash Comparisons

define-key

22.9 Changing Key Bindings

define-key-after

22.12.7 Modifying Menus

define-logical-name

25.7 Changing File Names and Attributes

define-minor-mode

23.2.3 Defining Minor Modes

define-prefix-command

22.5 Prefix Keys

defined-colors

29.19 Color Names

defining a function

12.4 Defining Functions

defining advice

17.2 Defining Advice

defining commands

21.2 Defining Commands

defining menus

22.12.1 Defining Menus

defining-kbd-macro

21.15 Keyboard Macros

definition of a symbol

8.2 Defining Symbols

defmacro

13.4 Defining Macros

defsubst

12.9 Inline Functions

defun

12.4 Defining Functions

defun-prompt-regexp

30.2.6 Moving over Balanced Expressions

defvar

11.5 Defining Global Variables

delete

5.7 Using Lists as Sets

delete previous char

32.6 Deleting Text

delete-and-extract-region

32.6 Deleting Text

delete-auto-save-file-if-necessary

26.2 Auto-Saving

delete-auto-save-files

26.2 Auto-Saving

delete-backward-char

32.6 Deleting Text

delete-blank-lines

32.7 User-Level Deletion Commands

delete-char

32.6 Deleting Text

delete-directory

25.10 Creating and Deleting Directories

delete-exited-processes

37.5 Deleting Processes

delete-field

32.19.10 Defining and Using Fields

delete-file

25.7 Changing File Names and Attributes

delete-frame

29.5 Deleting Frames

delete-frame event

21.6.10 Miscellaneous Window System Events

delete-frame-hook

29.5 Deleting Frames

delete-horizontal-space

32.7 User-Level Deletion Commands

delete-indentation

32.7 User-Level Deletion Commands

delete-minibuffer-contents

20.9 Minibuffer Miscellany

delete-old-versions

26.1.3 Making and Deleting Numbered Backup Files

delete-other-windows

28.3 Deleting Windows

delete-overlay

38.9.2 Managing Overlays

delete-process

37.5 Deleting Processes

delete-region

32.6 Deleting Text

delete-to-left-margin

32.12 Margins for Filling

delete-window

28.3 Deleting Windows

delete-windows-on

28.3 Deleting Windows

deleting files

25.7 Changing File Names and Attributes

deleting processes

37.5 Deleting Processes

deleting whitespace

32.7 User-Level Deletion Commands

deleting windows

28.3 Deleting Windows

deletion of elements

5.7 Using Lists as Sets

deletion of frames

29.5 Deleting Frames

deletion vs killing

32.6 Deleting Text

delq

5.7 Using Lists as Sets

describe-bindings

22.11 Scanning Keymaps

describe-buffer-case-table

4.9 The Case Table

describe-categories

35.9 Categories

describe-current-display-table

38.17.1 Display Table Format

describe-display-table

38.17.1 Display Table Format

describe-mode

23.1.4 Getting Help about a Major Mode

describe-prefix-bindings

24.5 Help Functions

description for interactive codes

21.2.2 Code Characters for interactive

description format

1.3.7 Format of Descriptions

destructive list operations

5.6 Modifying Existing List Structure

detect-coding-region

33.10.3 Coding Systems in Lisp

detect-coding-string

33.10.3 Coding Systems in Lisp

diagrams, boxed, for lists

2.3.6 Cons Cell and List Types

dialog boxes

29.16 Dialog Boxes

diary buffer

39.8 Fancy Diary Display

diary-anniversary

39.9 Sexp Entries and the Fancy Diary Display

diary-astro-day-number

39.9 Sexp Entries and the Fancy Diary Display

diary-cyclic

39.9 Sexp Entries and the Fancy Diary Display

diary-date

39.9 Sexp Entries and the Fancy Diary Display

diary-date-forms

39.6 Customizing the Diary

diary-day-of-year

39.9 Sexp Entries and the Fancy Diary Display

diary-display-hook

39.8 Fancy Diary Display

diary-entry-marker

39.1 Customizing the Calendar

diary-float

39.9 Sexp Entries and the Fancy Diary Display

diary-french-date

39.9 Sexp Entries and the Fancy Diary Display

diary-hebrew-date

39.9 Sexp Entries and the Fancy Diary Display

diary-islamic-date

39.9 Sexp Entries and the Fancy Diary Display

diary-iso-date

39.9 Sexp Entries and the Fancy Diary Display

diary-julian-date

39.9 Sexp Entries and the Fancy Diary Display

diary-list-include-blanks

39.8 Fancy Diary Display

diary-mayan-date

39.9 Sexp Entries and the Fancy Diary Display

diary-omer

39.9 Sexp Entries and the Fancy Diary Display

diary-parasha

39.9 Sexp Entries and the Fancy Diary Display

diary-phases-of-moon

39.9 Sexp Entries and the Fancy Diary Display

diary-remind

39.9 Sexp Entries and the Fancy Diary Display

diary-rosh-hodesh

39.9 Sexp Entries and the Fancy Diary Display

diary-sabbath-candles

39.9 Sexp Entries and the Fancy Diary Display

diary-sunrise-sunset

39.9 Sexp Entries and the Fancy Diary Display

diary-yahrzeit

39.9 Sexp Entries and the Fancy Diary Display

digit-argument

21.11 Prefix Command Arguments

dimension (of character set)

33.6 Characters and Bytes

ding

38.18 Beeping

directory name

25.8.2 Directory Names

directory name abbreviation

25.8.2 Directory Names

directory part (of file name)

25.8.1 File Name Components

directory-abbrev-alist

25.8.2 Directory Names

directory-file-name

25.8.2 Directory Names

directory-files

25.9 Contents of Directories

directory-oriented functions

25.9 Contents of Directories

dired-kept-versions

26.1.3 Making and Deleting Numbered Backup Files

dired-mode-map

H. Standard Keymaps

disable undo

32.10 Maintaining Undo Lists

disable-command

21.13 Disabling Commands

disable-point-adjustment

21.5 Adjusting Point After Commands

disabled

21.13 Disabling Commands

disabled command

21.13 Disabling Commands

disabled-command-hook

21.13 Disabling Commands

disabling advice

17.6 Enabling and Disabling Advice

disassemble

16.7 Disassembled Byte-Code

disassembled byte-code

16.7 Disassembled Byte-Code

discard input

21.7.5 Miscellaneous Event Input Features

discard-input

21.7.5 Miscellaneous Event Input Features

display (overlay property)

38.9.1 Overlay Properties

display (text property)

32.19.4 Properties with Special Meanings

display (text property)

38.12 The display Property

display feature testing

29.22 Display Feature Testing

display margins

38.12.3 Displaying in the Margins

display specification

38.12 The display Property

display table

38.17 Display Tables

display-backing-store

29.22 Display Feature Testing

display-buffer

28.8 Choosing a Window for Display

display-buffer-function

28.8 Choosing a Window for Display

display-buffer-reuse-frames

28.8 Choosing a Window for Display

display-color-cells

29.22 Display Feature Testing

display-color-p

29.22 Display Feature Testing

display-completion-list

20.5.3 Minibuffer Commands that Do Completion

display-graphic-p

29.22 Display Feature Testing

display-grayscale-p

29.22 Display Feature Testing

display-images-p

29.22 Display Feature Testing

display-message-or-buffer

38.4 The Echo Area

display-mm-height

29.22 Display Feature Testing

display-mm-width

29.22 Display Feature Testing

display-mouse-p

29.22 Display Feature Testing

display-pixel-height

29.22 Display Feature Testing

display-pixel-width

29.22 Display Feature Testing

display-planes

29.22 Display Feature Testing

display-popup-menus-p

29.22 Display Feature Testing

display-save-under

29.22 Display Feature Testing

display-screens

29.22 Display Feature Testing

display-selections-p

29.22 Display Feature Testing

display-table-slot

38.17.1 Display Table Format

display-visual-class

29.22 Display Feature Testing

displaying a buffer

28.7 Displaying Buffers in Windows

displays, multiple

29.2 Multiple Displays

do-auto-save

26.2 Auto-Saving

`DOC' (documentation) file

24.1 Documentation Basics

doc-directory

24.2 Access to Documentation Strings

documentation

24.2 Access to Documentation Strings

documentation conventions

24.1 Documentation Basics

documentation for major mode

23.1.4 Getting Help about a Major Mode

documentation notation

1.3.3 Evaluation Notation

documentation of function

12.2.4 Documentation Strings of Functions

documentation strings

24. Documentation

documentation, keys in

24.3 Substituting Key Bindings in Documentation

documentation-property

24.2 Access to Documentation Strings

dolist

10.4 Iteration

DOS file types

33.10.9 MS-DOS File Types

dotimes

10.4 Iteration

dotted lists (Edebug)

18.2.15.1 Specification List

dotted pair notation

2.3.6.1 Dotted Pair Notation

double-click events

21.6.7 Repeat Events

double-click-fuzz

21.6.7 Repeat Events

double-click-time

21.6.7 Repeat Events

double-quote in strings

2.3.8.1 Syntax for Strings

down-list

30.2.6 Moving over Balanced Expressions

downcase

4.8 Case Conversion in Lisp

downcase-region

32.18 Case Changes

downcase-word

32.18 Case Changes

downcasing in lookup-key

21.7.1 Key Sequence Input

drag event

21.6.5 Drag Events

drag-n-drop event

21.6.10 Miscellaneous Window System Events

dribble file

40.8.3 Recording Input

dump-emacs

E.1 Building Emacs

dynamic loading of documentation

16.3 Documentation Strings and Compilation

dynamic loading of functions

16.4 Dynamic Loading of Individual Functions

dynamic scoping

11.9 Scoping Rules for Variable Bindings

E

easy-mmode-define-minor-mode

23.2.3 Defining Minor Modes

echo area

38.4 The Echo Area

echo-area-clear-hook

38.4 The Echo Area

echo-keystrokes

38.4 The Echo Area

edebug

18.2.6.2 Source Breakpoints

Edebug

18.2 Edebug

Edebug execution modes

18.2.3 Edebug Execution Modes

Edebug mode

18.2 Edebug

Edebug specification list

18.2.15.1 Specification List

edebug-all-defs

18.2.16 Edebug Options

edebug-all-forms

18.2.16 Edebug Options

edebug-continue-kbd-macro

18.2.16 Edebug Options

edebug-display-freq-count

18.2.13 Coverage Testing

edebug-eval-top-level-form

18.2.2 Instrumenting for Edebug

edebug-global-break-condition

18.2.16 Edebug Options

edebug-initial-mode

18.2.16 Edebug Options

edebug-on-error

18.2.16 Edebug Options

edebug-on-quit

18.2.16 Edebug Options

edebug-print-circle

18.2.11 Printing in Edebug

edebug-print-length

18.2.11 Printing in Edebug

edebug-print-level

18.2.11 Printing in Edebug

edebug-print-trace-after

18.2.12 Trace Buffer

edebug-print-trace-before

18.2.12 Trace Buffer

edebug-save-displayed-buffer-points

18.2.16 Edebug Options

edebug-save-windows

18.2.16 Edebug Options

edebug-set-global-break-condition

18.2.6.1 Global Break Condition

edebug-setup-hook

18.2.16 Edebug Options

edebug-test-coverage

18.2.16 Edebug Options

edebug-trace

18.2.16 Edebug Options

edebug-tracing

18.2.12 Trace Buffer

edebug-unwrap

18.2.15.1 Specification List

edit-abbrevs-map

H. Standard Keymaps

edit-and-eval-command

20.3 Reading Lisp Objects with the Minibuffer

edit-tab-stops-map

H. Standard Keymaps

editing types

2.4 Editing Types

editor command loop

21. Command Loop

electric-buffer-menu-mode-map

H. Standard Keymaps

electric-future-map

1.3.7.2 A Sample Variable Description

electric-history-map

H. Standard Keymaps

element (of list)

5. Lists

elements of sequences

6.1 Sequences

`elp.el'

D.2 Tips for Making Compiled Code Fast

elt

6.1 Sequences

Emacs event standard notation

24.4 Describing Characters for Help Messages

emacs-build-time

1.4 Version Information

emacs-lisp-mode-map

H. Standard Keymaps

emacs-lisp-mode-syntax-table

35.7 Some Standard Syntax Tables

emacs-major-version

1.4 Version Information

emacs-minor-version

1.4 Version Information

emacs-pid

40.3 Operating System Environment

emacs-startup-hook

40.1.2 The Init File, `.emacs'

emacs-version

1.4 Version Information

`emacs/etc/DOC-version'

24.1 Documentation Basics

EMACSLOADPATH environment variable

15.2 Library Search

empty list

2.3.6 Cons Cell and List Types

enable-command

21.13 Disabling Commands

enable-flow-control

40.12 Flow Control

enable-flow-control-on

40.12 Flow Control

enable-local-eval

11.13 File Local Variables

enable-local-variables

11.13 File Local Variables

enable-multibyte-characters

33.1 Text Representations

enable-recursive-minibuffers

20.9 Minibuffer Miscellany

enabling advice

17.6 Enabling and Disabling Advice

encode-coding-region

33.10.7 Explicit Encoding and Decoding

encode-coding-string

33.10.7 Explicit Encoding and Decoding

encode-time

40.6 Time Conversion

encoding file formats

25.12 File Format Conversion

encoding text

33.10.7 Explicit Encoding and Decoding

end of buffer marker

31.3 Functions that Create Markers

end of line conversion

33.10.1 Basic Concepts of Coding Systems

end of line in regexp

34.2.1.1 Special Characters in Regular Expressions

end-of-buffer

30.2.3 Motion to an End of the Buffer

end-of-defun

30.2.6 Moving over Balanced Expressions

end-of-defun-function

30.2.6 Moving over Balanced Expressions

end-of-file

19.3 Input Functions

end-of-line

30.2.4 Motion by Text Lines

enlarge-window

28.15 Changing the Size of a Window

enlarge-window-horizontally

28.15 Changing the Size of a Window

environment

9.1 Introduction to Evaluation

environment variable access

40.3 Operating System Environment

environment variables, subprocesses

37.1 Functions that Create Subprocesses

eobp

32.1 Examining Text Near Point

eolp

32.1 Examining Text Near Point

eq

2.7 Equality Predicates

equal

2.7 Equality Predicates

equality

2.7 Equality Predicates

erase-buffer

32.6 Deleting Text

error

10.5.3.1 How to Signal an Error

error cleanup

10.5.4 Cleaning Up from Nonlocal Exits

error debugging

18.1.1 Entering the Debugger on an Error

error description

10.5.3.3 Writing Code to Handle Errors

error display

38.4 The Echo Area

error handler

10.5.3.3 Writing Code to Handle Errors

error in debug

18.1.7 Invoking the Debugger

error message notation

1.3.5 Error Messages

error name

10.5.3.4 Error Symbols and Condition Names

error symbol

10.5.3.4 Error Symbols and Condition Names

error-conditions

10.5.3.4 Error Symbols and Condition Names

error-message-string

10.5.3.3 Writing Code to Handle Errors

errors

10.5.3 Errors

ESC

22.8 Functions for Key Lookup

esc-map

22.5 Prefix Keys

ESC-prefix

22.5 Prefix Keys

escape

35.2.1 Table of Syntax Classes

escape characters

19.6 Variables Affecting Output

escape characters in printing

19.5 Output Functions

escape sequence

2.3.3 Character Type

`etc/DOC-version'

24.1 Documentation Basics

eval

9.4 Eval

eval, and debugging

18.1.8 Internals of the Debugger

eval-after-load

15.8 Hooks for Loading

eval-and-compile

16.5 Evaluation During Compilation

eval-current-buffer

9.4 Eval

eval-current-buffer (Edebug)

18.2.2 Instrumenting for Edebug

eval-defun (Edebug)

18.2.2 Instrumenting for Edebug

eval-expression (Edebug)

18.2.2 Instrumenting for Edebug

eval-minibuffer

20.3 Reading Lisp Objects with the Minibuffer

eval-region

9.4 Eval

eval-region (Edebug)

18.2.2 Instrumenting for Edebug

eval-when-compile

16.5 Evaluation During Compilation

evaluated expression argument

21.2.2 Code Characters for interactive

evaluation

9. Evaluation

evaluation error

11.3 Local Variables

evaluation list group

18.2.10 Evaluation List Buffer

evaluation notation

1.3.3 Evaluation Notation

evaluation of buffer contents

9.4 Eval

evaporate (overlay property)

38.9.1 Overlay Properties

even-window-heights

28.8 Choosing a Window for Display

event printing

24.4 Describing Characters for Help Messages

event type

21.6.12 Classifying Events

event, reading only one

21.7.2 Reading One Event

event-basic-type

21.6.12 Classifying Events

event-click-count

21.6.7 Repeat Events

event-convert-list

21.6.12 Classifying Events

event-end

21.6.13 Accessing Events

event-modifiers

21.6.12 Classifying Events

event-start

21.6.13 Accessing Events

eventp

21.6 Input Events

events

21.6 Input Events

examining the interactive form

21.2.1 Using interactive

examining windows

28.6 Buffers and Windows

examples of using interactive

21.2.3 Examples of Using interactive

excursion

30.3 Excursions

exec-directory

37.1 Functions that Create Subprocesses

exec-path

37.1 Functions that Create Subprocesses

execute program

37.1 Functions that Create Subprocesses

execute with prefix argument

21.3 Interactive Call

execute-extended-command

21.3 Interactive Call

execute-kbd-macro

21.15 Keyboard Macros

executing-macro

21.15 Keyboard Macros

execution speed

D.2 Tips for Making Compiled Code Fast

exit

21.12 Recursive Editing

exit recursive editing

21.12 Recursive Editing

exit-minibuffer

20.9 Minibuffer Miscellany

exit-recursive-edit

21.12 Recursive Editing

exiting Emacs

40.2 Getting Out of Emacs

exp

3.9 Standard Mathematical Functions

expand-abbrev

36.5 Looking Up and Expanding Abbreviations

expand-file-name

25.8.4 Functions that Expand Filenames

expansion of file names

25.8.4 Functions that Expand Filenames

expansion of macros

13.2 Expansion of a Macro Call

expression

9.1 Introduction to Evaluation

expression prefix

35.2.1 Table of Syntax Classes

expt

3.9 Standard Mathematical Functions

extended-command-history

20.4 Minibuffer History

extent

11.9 Scoping Rules for Variable Bindings

extra slots of char-table

6.6 Char-Tables

extra-keyboard-modifiers

40.8.2 Translating Input Events

F

face

38.11 Faces

face (overlay property)

38.9.1 Overlay Properties

face (text property)

32.19.4 Properties with Special Meanings

face attributes

38.11.3 Face Attributes

face codes of text

32.19.4 Properties with Special Meanings

face id

38.11 Faces

face-attribute

38.11.4 Face Attribute Functions

face-background

38.11.4 Face Attribute Functions

face-bold-p

38.11.4 Face Attribute Functions

face-default-registry

38.11.6 Font Selection

face-differs-from-default-p

38.11.7 Functions for Working with Faces

face-documentation

38.11.7 Functions for Working with Faces

face-equal

38.11.7 Functions for Working with Faces

face-font

38.11.4 Face Attribute Functions

face-font-family-alternatives

38.11.6 Font Selection

face-font-registry-alternatives

38.11.6 Font Selection

face-font-selection-order

38.11.6 Font Selection

face-foreground

38.11.4 Face Attribute Functions

face-id

38.11.7 Functions for Working with Faces

face-inverse-video-p

38.11.4 Face Attribute Functions

face-italic-p

38.11.4 Face Attribute Functions

face-list

38.11.7 Functions for Working with Faces

face-stipple

38.11.4 Face Attribute Functions

face-underline-p

38.11.4 Face Attribute Functions

facemenu-background-menu

H. Standard Keymaps

facemenu-face-menu

H. Standard Keymaps

facemenu-foreground-menu

H. Standard Keymaps

facemenu-indentation-menu

H. Standard Keymaps

facemenu-justification-menu

H. Standard Keymaps

facemenu-keymap

22.5 Prefix Keys

facemenu-menu

H. Standard Keymaps

facemenu-special-menu

H. Standard Keymaps

facep

38.11 Faces

faces, automatic choice

38.11.8 Automatic Face Assignment

false

1.3.2 nil and t

fancy-diary-display

39.8 Fancy Diary Display

fboundp

12.8 Accessing Function Cell Contents

fceiling

3.7 Rounding Operations

feature-unload-hook

15.7 Unloading

featurep

15.6 Features

features

15.6 Features

fetch-bytecode

16.4 Dynamic Loading of Individual Functions

ffloor

3.7 Rounding Operations

field (text property)

32.19.4 Properties with Special Meanings

field width

4.7 Formatting Strings

field-beginning

32.19.10 Defining and Using Fields

field-end

32.19.10 Defining and Using Fields

field-string

32.19.10 Defining and Using Fields

field-string-no-properties

32.19.10 Defining and Using Fields

fields

32.19.10 Defining and Using Fields

file accessibility

25.6.1 Testing Accessibility

file age

25.6.1 Testing Accessibility

file attributes

25.6.4 Other Information about Files

file format conversion

25.12 File Format Conversion

file hard link

25.7 Changing File Names and Attributes

file locks

25.5 File Locks

file mode specification error

23.1.3 How Emacs Chooses a Major Mode

file modes and MS-DOS

25.7 Changing File Names and Attributes

file modification time

25.6.1 Testing Accessibility

file name completion subroutines

25.8.6 File Name Completion

file name of buffer

27.4 Buffer File Name

file name of directory

25.8.2 Directory Names

file names

25.8 File Names

file names in directory

25.9 Contents of Directories

file open error

25.1.2 Subroutines of Visiting

file symbolic links

25.6.2 Distinguishing Kinds of Files

file types on MS-DOS and Windows

33.10.9 MS-DOS File Types

file with multiple names

25.7 Changing File Names and Attributes

file-accessible-directory-p

25.6.1 Testing Accessibility

file-already-exists

25.7 Changing File Names and Attributes

file-attributes

25.6.4 Other Information about Files

file-chase-links

25.6.3 Truenames

file-coding-system-alist

33.10.5 Default Coding Systems

file-directory-p

25.6.2 Distinguishing Kinds of Files

file-error

15.1 How Programs Do Loading

file-executable-p

25.6.1 Testing Accessibility

file-exists-p

25.6.1 Testing Accessibility

file-expand-wildcards

25.9 Contents of Directories

file-local-copy

25.11 Making Certain File Names "Magic"

file-locked

25.5 File Locks

file-locked-p

25.5 File Locks

file-modes

25.6.4 Other Information about Files

file-name-absolute-p

25.8.3 Absolute and Relative File Names

file-name-all-completions

25.8.6 File Name Completion

file-name-all-versions

25.9 Contents of Directories

file-name-as-directory

25.8.2 Directory Names

file-name-buffer-file-type-alist

33.10.9 MS-DOS File Types

file-name-completion

25.8.6 File Name Completion

file-name-directory

25.8.1 File Name Components

file-name-extension

25.8.1 File Name Components

file-name-history

20.4 Minibuffer History

file-name-nondirectory

25.8.1 File Name Components

file-name-sans-extension

25.8.1 File Name Components

file-name-sans-versions

25.8.1 File Name Components

file-newer-than-file-p

25.6.1 Testing Accessibility

file-newest-backup

26.1.4 Naming Backup Files

file-nlinks

25.6.4 Other Information about Files

file-ownership-preserved-p

25.6.1 Testing Accessibility

file-precious-flag

25.2 Saving Buffers

file-readable-p

25.6.1 Testing Accessibility

file-regular-p

25.6.2 Distinguishing Kinds of Files

file-relative-name

25.8.4 Functions that Expand Filenames

file-supersession

27.6 Comparison of Modification Time

file-symlink-p

25.6.2 Distinguishing Kinds of Files

file-truename

25.6.3 Truenames

file-writable-p

25.6.1 Testing Accessibility

fill-column

32.12 Margins for Filling

fill-context-prefix

32.13 Adaptive Fill Mode

fill-individual-paragraphs

32.11 Filling

fill-individual-varying-indent

32.11 Filling

fill-nobreak-predicate

32.12 Margins for Filling

fill-paragraph

32.11 Filling

fill-paragraph-function

32.11 Filling

fill-prefix

32.12 Margins for Filling

fill-region

32.11 Filling

fill-region-as-paragraph

32.11 Filling

fillarray

6.3 Functions that Operate on Arrays

filling a paragraph

32.11 Filling

filling, automatic

32.14 Auto Filling

filling, explicit

32.11 Filling

filter function

37.9.2 Process Filter Functions

find-backup-file-name

26.1.4 Naming Backup Files

find-charset-region

33.8 Scanning for Character Sets

find-charset-string

33.8 Scanning for Character Sets

find-coding-systems-for-charsets

33.10.3 Coding Systems in Lisp

find-coding-systems-region

33.10.3 Coding Systems in Lisp

find-coding-systems-string

33.10.3 Coding Systems in Lisp

find-file

25.1.1 Functions for Visiting Files

find-file-hooks

25.1.1 Functions for Visiting Files

find-file-name-handler

25.11 Making Certain File Names "Magic"

find-file-noselect

25.1.1 Functions for Visiting Files

find-file-not-found-hooks

25.1.1 Functions for Visiting Files

find-file-other-window

25.1.1 Functions for Visiting Files

find-file-read-only

25.1.1 Functions for Visiting Files

find-file-wildcards

25.1.1 Functions for Visiting Files

find-image

38.13.7 Defining Images

find-operation-coding-system

33.10.5 Default Coding Systems

finding files

25.1 Visiting Files

finding windows

28.4 Selecting Windows

first-change-hook

32.25 Change Hooks

fixed-pitch (face name)

38.11.1 Standard Faces

fixup-whitespace

32.7 User-Level Deletion Commands

float

3.5 Numeric Conversions

float-time

40.5 Time of Day

floatp

3.3 Type Predicates for Numbers

floats-consed

E.4 Memory Usage

floor

3.5 Numeric Conversions

flow control characters

40.12 Flow Control

flow control example

40.8.2 Translating Input Events

flush input

21.7.5 Miscellaneous Event Input Features

fmakunbound

12.8 Accessing Function Cell Contents

focus event

21.6.9 Focus Events

focus-follows-mouse

29.9 Input Focus

following-char

32.1 Examining Text Near Point

Font Lock Mode

23.5 Font Lock Mode

font-list-limit

38.11.9 Looking Up Fonts

Font-Lock mode

38.11.8 Automatic Face Assignment

font-lock-beginning-of-syntax-function

23.5.3 Other Font Lock Variables

font-lock-builtin-face

23.5.5 Faces for Font Lock

font-lock-comment-face

23.5.5 Faces for Font Lock

font-lock-constant-face

23.5.5 Faces for Font Lock

font-lock-defaults

23.5.1 Font Lock Basics

font-lock-function-name-face

23.5.5 Faces for Font Lock

font-lock-keyword-face

23.5.5 Faces for Font Lock

font-lock-keywords

23.5.2 Search-based Fontification

font-lock-keywords-case-fold-search

23.5.3 Other Font Lock Variables

font-lock-keywords-only

23.5.3 Other Font Lock Variables

font-lock-mark-block-function

23.5.3 Other Font Lock Variables

font-lock-string-face

23.5.5 Faces for Font Lock

font-lock-syntactic-keywords

23.5.6 Syntactic Font Lock

font-lock-syntax-table

23.5.3 Other Font Lock Variables

font-lock-type-face

23.5.5 Faces for Font Lock

font-lock-variable-name-face

23.5.5 Faces for Font Lock

font-lock-warning-face

23.5.5 Faces for Font Lock

fontification-functions

38.11.8 Automatic Face Assignment

fontified (text property)

32.19.4 Properties with Special Meanings

fonts

1.3.1 Some Terms

fonts, more than one on display

29.22 Display Feature Testing

foo

1.3.7.1 A Sample Function Description

for

13.6.2 Evaluating Macro Arguments Repeatedly

force-mode-line-update

23.3 Mode Line Format

forcing redisplay

38.2 Forcing Redisplay

format

4.7 Formatting Strings

format definition

25.12 File Format Conversion

format of keymaps

22.2 Format of Keymaps

format specification

4.7 Formatting Strings

format-alist

25.12 File Format Conversion

format-find-file

25.12 File Format Conversion

format-insert-file

25.12 File Format Conversion

format-time-string

40.6 Time Conversion

format-write-file

25.12 File Format Conversion

formatting strings

4.7 Formatting Strings

formfeed

2.3.3 Character Type

forms

9.1 Introduction to Evaluation

forward advice

17.2 Defining Advice

forward-char

30.2.1 Motion by Characters

forward-comment

35.6 Parsing Balanced Expressions

forward-line

30.2.4 Motion by Text Lines

forward-list

30.2.6 Moving over Balanced Expressions

forward-sexp

30.2.6 Moving over Balanced Expressions

forward-to-indentation

32.17.6 Indentation-Based Motion Commands

forward-word

30.2.2 Motion by Words

frame

29. Frames

frame configuration

29.12 Frame Configurations

frame size

29.3.4 Frame Size And Position

frame visibility

29.10 Visibility of Frames

frame-background-mode

38.11.2 Defining Faces

frame-char-height

29.3.4 Frame Size And Position

frame-char-width

29.3.4 Frame Size And Position

frame-first-window

29.7 Frames and Windows

frame-height

29.3.4 Frame Size And Position

frame-list

29.6 Finding All Frames

frame-live-p

29.5 Deleting Frames

frame-parameter

29.3.1 Access to Frame Parameters

frame-parameters

29.3.1 Access to Frame Parameters

frame-pixel-height

29.3.4 Frame Size And Position

frame-pixel-width

29.3.4 Frame Size And Position

frame-selected-window

29.7 Frames and Windows

frame-title-format

29.4 Frame Titles

frame-visible-p

29.10 Visibility of Frames

frame-width

29.3.4 Frame Size And Position

framep

29. Frames

frames, more than one on display

29.22 Display Feature Testing

free list

E.3 Garbage Collection

frequency counts

18.2.13 Coverage Testing

fringe (face name)

38.11.1 Standard Faces

fround

3.7 Rounding Operations

fset

12.8 Accessing Function Cell Contents

ftp-login

10.5.4 Cleaning Up from Nonlocal Exits

ftruncate

3.7 Rounding Operations

full keymap

22.2 Format of Keymaps

funcall

12.5 Calling Functions

funcall, and debugging

18.1.8 Internals of the Debugger

function

12.7 Anonymous Functions

function call

9.2.5 Evaluation of Function Forms

function call debugging

18.1.3 Entering the Debugger on a Function Call

function cell

8.1 Symbol Components

function cell in autoload

15.4 Autoload

function definition

12.3 Naming a Function

function descriptions

1.3.7.1 A Sample Function Description

function form evaluation

9.2.5 Evaluation of Function Forms

function input stream

19.2 Input Streams

function invocation

12.5 Calling Functions

function keys

21.6.2 Function Keys

function name

12.3 Naming a Function

function output stream

19.4 Output Streams

function quoting

12.7 Anonymous Functions

function-key-map

40.8.2 Translating Input Events

functionals

12.5 Calling Functions

functionp

12.1 What Is a Function?

functions in modes

23.1.1 Major Mode Conventions

functions, making them interactive

21.2 Defining Commands

Fundamental mode

23.1 Major Modes

fundamental-mode

23.1.3 How Emacs Chooses a Major Mode

fundamental-mode-abbrev-table

36.6 Standard Abbrev Tables

fundamental-mode-map

H. Standard Keymaps

G

gamma correction

29.3.3 Window Frame Parameters

gap-position

27.12 The Buffer Gap

gap-size

27.12 The Buffer Gap

garbage collection protection

E.5 Writing Emacs Primitives

garbage collector

E.3 Garbage Collection

garbage-collect

E.3 Garbage Collection

garbage-collection-messages

E.3 Garbage Collection

gc-cons-threshold

E.3 Garbage Collection

general-holidays

39.2 Customizing the Holidays

generate-new-buffer

27.9 Creating Buffers

generate-new-buffer-name

27.3 Buffer Names

generic characters

33.7 Splitting Characters

generic comment delimiter

35.2.1 Table of Syntax Classes

generic string delimiter

35.2.1 Table of Syntax Classes

geometry specification

29.3.4 Frame Size And Position

get

8.4.2 Property List Functions for Symbols

get-buffer

27.3 Buffer Names

get-buffer-create

27.9 Creating Buffers

get-buffer-process

37.9.1 Process Buffers

get-buffer-window

28.6 Buffers and Windows

get-buffer-window-list

28.6 Buffers and Windows

get-char-property

32.19.1 Examining Text Properties

get-file-buffer

27.4 Buffer File Name

get-file-char

19.2 Input Streams

get-largest-window

28.4 Selecting Windows

get-lru-window

28.4 Selecting Windows

get-process

37.6 Process Information

get-register

32.21 Registers

get-text-property

32.19.1 Examining Text Properties

get-unused-category

35.9 Categories

get-window-with-predicate

28.4 Selecting Windows

getenv

40.3 Operating System Environment

gethash

7.2 Hash Table Access

GIF

38.13.4 GIF Images

global binding

11.3 Local Variables

global break condition

18.2.6.1 Global Break Condition

global keymap

22.6 Active Keymaps

global variable

11.1 Global Variables

global-abbrev-table

36.6 Standard Abbrev Tables

global-disable-point-adjustment

21.5 Adjusting Point After Commands

global-key-binding

22.8 Functions for Key Lookup

global-map

22.6 Active Keymaps

global-mode-string

23.3.2 Variables Used in the Mode Line

global-set-key

22.10 Commands for Binding Keys

global-unset-key

22.10 Commands for Binding Keys

glyph

38.17.3 Glyphs

glyph table

38.17.3 Glyphs

glyph-table

38.17.3 Glyphs

goto-char

30.2.1 Motion by Characters

goto-line

30.2.4 Motion by Text Lines

H

hack-local-variables

11.13 File Local Variables

handle-switch-frame

29.9 Input Focus

handling errors

10.5.3.3 Writing Code to Handle Errors

hash code

7.3 Defining Hash Comparisons

hash notation

2.1 Printed Representation and Read Syntax

hash tables

7. Hash Tables

hash-table-count

7.4 Other Hash Table Functions

hash-table-p

7.4 Other Hash Table Functions

hash-table-rehash-size

7.4 Other Hash Table Functions

hash-table-rehash-threshold

7.4 Other Hash Table Functions

hash-table-size

7.4 Other Hash Table Functions

hash-table-test

7.4 Other Hash Table Functions

hash-table-weakness

7.4 Other Hash Table Functions

hashing

8.3 Creating and Interning Symbols

header comments

D.5 Conventional Headers for Emacs Libraries

header line (of a window)

23.3.5 Window Header Lines

header-line (face name)

38.11.1 Standard Faces

header-line prefix key

21.7.1 Key Sequence Input

header-line-format

23.3.5 Window Header Lines

hebrew-holidays

39.2 Customizing the Holidays

help for major mode

23.1.4 Getting Help about a Major Mode

help-char

24.5 Help Functions

help-command

24.5 Help Functions

help-echo (text property)

32.19.4 Properties with Special Meanings

help-echo (text property)

38.9.1 Overlay Properties

help-event-list

24.5 Help Functions

help-form

24.5 Help Functions

help-map

24.5 Help Functions

Helper-describe-bindings

24.5 Help Functions

Helper-help

24.5 Help Functions

Helper-help-map

H. Standard Keymaps

highlight (face name)

38.11.1 Standard Faces

highlighting

38.15 Inverse Video

history list

20.4 Minibuffer History

history of commands

21.14 Command History

holiday forms

39.2 Customizing the Holidays

holidays-in-diary-buffer

39.6 Customizing the Diary

HOME environment variable

37.1 Functions that Create Subprocesses

hooks

23.6 Hooks

hooks for changing a character

32.19.4 Properties with Special Meanings

hooks for loading

15.8 Hooks for Loading

hooks for motion of point

32.19.4 Properties with Special Meanings

hooks for text changes

32.25 Change Hooks

horizontal position

32.16 Counting Columns

horizontal scrolling

28.13 Horizontal Scrolling

horizontal-scroll-bar prefix key

21.7.1 Key Sequence Input

hyper characters

2.3.3 Character Type

I

icon-title-format

29.4 Frame Titles

iconified frame

29.10 Visibility of Frames

iconify-frame

29.10 Visibility of Frames

iconify-frame event

21.6.10 Miscellaneous Window System Events

identity

12.5 Calling Functions

idleness

40.7 Timers for Delayed Execution

IEEE floating point

3.2 Floating Point Basics

if

10.2 Conditionals

ignore

12.5 Calling Functions

ignored-local-variables

11.13 File Local Variables

image descriptor

38.13.1 Image Descriptors

image-cache-eviction-delay

38.13.9 Image Cache

image-mask-p

38.13.1 Image Descriptors

image-size

38.13.8 Showing Images

image-types

38.13 Images

images in buffers

38.13 Images

Imenu

23.4 Imenu

imenu-case-fold-search

23.4 Imenu

imenu-create-index-function

23.4 Imenu

imenu-extract-index-name-function

23.4 Imenu

imenu-generic-expression

23.4 Imenu

imenu-index-alist

23.4 Imenu

imenu-prev-index-position-function

23.4 Imenu

imenu-syntax-alist

23.4 Imenu

implicit progn

10.1 Sequencing

inc

13.1 A Simple Example of a Macro

include-other-diary-files

39.8 Fancy Diary Display

indent-according-to-mode

32.17.2 Indentation Controlled by Major Mode

indent-code-rigidly

32.17.3 Indenting an Entire Region

indent-for-tab-command

32.17.2 Indentation Controlled by Major Mode

indent-line-function

32.17.2 Indentation Controlled by Major Mode

indent-region

32.17.3 Indenting an Entire Region

indent-region-function

32.17.3 Indenting an Entire Region

indent-relative

32.17.4 Indentation Relative to Previous Lines

indent-relative-maybe

32.17.4 Indentation Relative to Previous Lines

indent-rigidly

32.17.3 Indenting an Entire Region

indent-tabs-mode

32.17.1 Indentation Primitives

indent-to

32.17.1 Indentation Primitives

indent-to-left-margin

32.12 Margins for Filling

indentation

32.17 Indentation

indenting with parentheses

35.6 Parsing Balanced Expressions

indicate-empty-lines

38.16 Usual Display Conventions

indirect buffers

27.11 Indirect Buffers

indirect specifications

18.2.15.1 Specification List

indirect-function

9.2.4 Symbol Function Indirection

indirection

9.2.4 Symbol Function Indirection

infinite loops

18.1.2 Debugging Infinite Loops

infinite recursion

11.3 Local Variables

infinity

3.2 Floating Point Basics

Info-edit-map

H. Standard Keymaps

Info-mode-map

H. Standard Keymaps

inherit

35.2.1 Table of Syntax Classes

inheritance of text properties

32.19.6 Stickiness of Text Properties

inheriting a keymap's bindings

22.4 Inheritance and Keymaps

inhibit-default-init

40.1.2 The Init File, `.emacs'

inhibit-eol-conversion

33.10.6 Specifying a Coding System for One Operation

inhibit-field-text-motion

30.2.2 Motion by Words

inhibit-file-name-handlers

25.11 Making Certain File Names "Magic"

inhibit-file-name-operation

25.11 Making Certain File Names "Magic"

inhibit-modification-hooks

32.25 Change Hooks

inhibit-point-motion-hooks

32.19.4 Properties with Special Meanings

inhibit-quit

21.10 Quitting

inhibit-read-only

27.7 Read-Only Buffers

inhibit-startup-echo-area-message

40.1.1 Summary: Sequence of Actions at Startup

inhibit-startup-message

40.1.1 Summary: Sequence of Actions at Startup

init file

40.1.2 The Init File, `.emacs'

init-file-user

40.4 User Identification

initial-calendar-window-hook

39.1 Customizing the Calendar

initial-frame-alist

29.3.2 Initial Frame Parameters

initial-major-mode

23.1.3 How Emacs Chooses a Major Mode

initialization

40.1.1 Summary: Sequence of Actions at Startup

inline functions

12.9 Inline Functions

innermost containing parentheses

35.6 Parsing Balanced Expressions

input events

21.6 Input Events

input focus

29.9 Input Focus

input methods

33.11 Input Methods

input modes

40.8.1 Input Modes

input stream

19.2 Input Streams

input-method-alist

33.11 Input Methods

input-method-function

21.7.3 Invoking the Input Method

input-pending-p

21.7.5 Miscellaneous Event Input Features

insert

32.4 Inserting Text

insert-abbrev-table-description

36.2 Abbrev Tables

insert-and-inherit

32.19.6 Stickiness of Text Properties

insert-before-markers

32.4 Inserting Text

insert-before-markers-and-inherit

32.19.6 Stickiness of Text Properties

insert-behind-hooks (overlay property)

38.9.1 Overlay Properties

insert-behind-hooks (text property)

32.19.4 Properties with Special Meanings

insert-buffer

32.5 User-Level Insertion Commands

insert-buffer-substring

32.4 Inserting Text

insert-char

32.4 Inserting Text

insert-default-directory

20.5.5 Reading File Names

insert-directory

25.9 Contents of Directories

insert-directory-program

25.9 Contents of Directories

insert-file-contents

25.3 Reading from Files

insert-file-contents-literally

25.3 Reading from Files

insert-hebrew-diary-entry

39.7 Hebrew- and Islamic-Date Diary Entries

insert-image

38.13.8 Showing Images

insert-in-front-hooks (overlay property)

38.9.1 Overlay Properties

insert-in-front-hooks (text property)

32.19.4 Properties with Special Meanings

insert-islamic-diary-entry

39.7 Hebrew- and Islamic-Date Diary Entries

insert-monthly-hebrew-diary-entry

39.7 Hebrew- and Islamic-Date Diary Entries

insert-monthly-islamic-diary-entry

39.7 Hebrew- and Islamic-Date Diary Entries

insert-register

32.21 Registers

insert-yearly-hebrew-diary-entry

39.7 Hebrew- and Islamic-Date Diary Entries

insert-yearly-islamic-diary-entry

39.7 Hebrew- and Islamic-Date Diary Entries

inserting killed text

32.8.3 Functions for Yanking

insertion before point

32.4 Inserting Text

insertion of text

32.4 Inserting Text

insertion type of a marker

31.5 Marker Insertion Types

inside comment

35.6 Parsing Balanced Expressions

inside string

35.6 Parsing Balanced Expressions

installation-directory

40.3 Operating System Environment

int-to-string

4.6 Conversion of Characters and Strings

intangible (overlay property)

38.9.1 Overlay Properties

intangible (text property)

32.19.4 Properties with Special Meanings

integer to decimal

4.6 Conversion of Characters and Strings

integer to hexadecimal

4.7 Formatting Strings

integer to octal

4.7 Formatting Strings

integer to string

4.6 Conversion of Characters and Strings

integer-or-marker-p

31.2 Predicates on Markers

integerp

3.3 Type Predicates for Numbers

integers

3. Numbers

integers in specific radix

3.1 Integer Basics

interactive

21.2.1 Using interactive

interactive call

21.3 Interactive Call

interactive code description

21.2.2 Code Characters for interactive

interactive commands (Edebug)

18.2.2 Instrumenting for Edebug

interactive completion

21.2.2 Code Characters for interactive

interactive function

21.2 Defining Commands

interactive, examples of using

21.2.3 Examples of Using interactive

interactive-form

21.2.1 Using interactive

interactive-p

21.3 Interactive Call

intern

8.3 Creating and Interning Symbols

intern-soft

8.3 Creating and Interning Symbols

internals, of buffer

E.6.1 Buffer Internals

internals, of process

E.6.3 Process Internals

internals, of window

E.6.2 Window Internals

interning

8.3 Creating and Interning Symbols

interpreter

9. Evaluation

interpreter

9. Evaluation

interpreter-mode-alist

23.1.3 How Emacs Chooses a Major Mode

interprogram-cut-function

32.8.4 Low-Level Kill Ring

interprogram-paste-function

32.8.4 Low-Level Kill Ring

interrupt-process

37.8 Sending Signals to Processes

intervals

32.19.11 Why Text Properties are not Intervals

intervals-consed

E.4 Memory Usage

introduction sequence

33.6 Characters and Bytes

invalid function

9.2.4 Symbol Function Indirection

invalid prefix key error

22.9 Changing Key Bindings

invalid-function

9.2.4 Symbol Function Indirection

invalid-read-syntax

2.1 Printed Representation and Read Syntax

invalid-regexp

34.2.1.3 Backslash Constructs in Regular Expressions

Inverse Video

38.15 Inverse Video

inverse-video

38.15 Inverse Video

invert-face

38.11.4 Face Attribute Functions

invisible (overlay property)

38.9.1 Overlay Properties

invisible (text property)

32.19.4 Properties with Special Meanings

invisible frame

29.10 Visibility of Frames

invisible text

38.5 Invisible Text

invocation-directory

40.3 Operating System Environment

invocation-name

40.3 Operating System Environment

isearch-mode-map

H. Standard Keymaps

islamic-holidays

39.2 Customizing the Holidays

italic (face name)

38.11.1 Standard Faces

iteration

10.4 Iteration

J

joining lists

5.6.3 Functions that Rearrange Lists

just-one-space

32.7 User-Level Deletion Commands

justify-current-line

32.11 Filling

K

kbd-macro-termination-hook

21.15 Keyboard Macros

kept-new-versions

26.1.3 Making and Deleting Numbered Backup Files

kept-old-versions

26.1.3 Making and Deleting Numbered Backup Files

key

22.1 Keymap Terminology

key binding

22.1 Keymap Terminology

key lookup

22.7 Key Lookup

key sequence

21.7.1 Key Sequence Input

key sequence error

22.9 Changing Key Bindings

key sequence input

21.7.1 Key Sequence Input

key translation function

40.8.2 Translating Input Events

key-binding

22.8 Functions for Key Lookup

key-description

24.4 Describing Characters for Help Messages

key-translation-map

40.8.2 Translating Input Events

keyboard events in strings

21.6.14 Putting Keyboard Events in Strings

keyboard macro execution

21.3 Interactive Call

keyboard macro termination

38.18 Beeping

keyboard macros

21.15 Keyboard Macros

keyboard macros (Edebug)

18.2.3 Edebug Execution Modes

keyboard-coding-system

33.10.8 Terminal I/O Encoding

keyboard-quit

21.10 Quitting

keyboard-translate

40.8.2 Translating Input Events

keyboard-translate-table

40.8.2 Translating Input Events

keymap

22. Keymaps

keymap (overlay property)

38.9.1 Overlay Properties

keymap (text property)

32.19.4 Properties with Special Meanings

keymap entry

22.7 Key Lookup

keymap format

22.2 Format of Keymaps

keymap in keymap

22.7 Key Lookup

keymap inheritance

22.4 Inheritance and Keymaps

keymap of character

32.19.4 Properties with Special Meanings

keymap of character (and overlays)

38.9.1 Overlay Properties

keymap prompt string

22.2 Format of Keymaps

keymap-parent

22.4 Inheritance and Keymaps

keymapp

22.2 Format of Keymaps

keymaps in modes

23.1.1 Major Mode Conventions

keys in documentation strings

24.3 Substituting Key Bindings in Documentation

keys, reserved

D.1 Emacs Lisp Coding Conventions

keystroke

22.1 Keymap Terminology

keystroke command

12.1 What Is a Function?

keyword symbol

11.2 Variables that Never Change

keywordp

11.2 Variables that Never Change

kill command repetition

21.4 Information from the Command Loop

kill ring

32.8 The Kill Ring

kill-all-local-variables

11.10.2 Creating and Deleting Buffer-Local Bindings

kill-append

32.8.4 Low-Level Kill Ring

kill-buffer

27.10 Killing Buffers

kill-buffer-hook

27.10 Killing Buffers

kill-buffer-query-functions

27.10 Killing Buffers

kill-emacs

40.2.1 Killing Emacs

kill-emacs-hook

40.2.1 Killing Emacs

kill-emacs-query-functions

40.2.1 Killing Emacs

kill-local-variable

11.10.2 Creating and Deleting Buffer-Local Bindings

kill-new

32.8.4 Low-Level Kill Ring

kill-process

37.8 Sending Signals to Processes

kill-read-only-ok

32.8.2 Functions for Killing

kill-region

32.8.2 Functions for Killing

kill-ring

32.8.5 Internals of the Kill Ring

kill-ring-max

32.8.5 Internals of the Kill Ring

kill-ring-yank-pointer

32.8.5 Internals of the Kill Ring

killing buffers

27.10 Killing Buffers

killing Emacs

40.2.1 Killing Emacs

L

lambda expression

12.2 Lambda Expressions

lambda in debug

18.1.7 Invoking the Debugger

lambda in keymap

22.7 Key Lookup

lambda list

12.2.1 Components of a Lambda Expression

lambda-list (Edebug)

18.2.15.1 Specification List

last

5.4 Accessing Elements of Lists

last-abbrev

36.5 Looking Up and Expanding Abbreviations

last-abbrev-location

36.5 Looking Up and Expanding Abbreviations

last-abbrev-text

36.5 Looking Up and Expanding Abbreviations

last-coding-system-used

33.10.2 Encoding and I/O

last-command

21.4 Information from the Command Loop

last-command-char

21.4 Information from the Command Loop

last-command-event

21.4 Information from the Command Loop

last-event-frame

21.4 Information from the Command Loop

last-input-char

21.7.5 Miscellaneous Event Input Features

last-input-event

21.7.5 Miscellaneous Event Input Features

last-kbd-macro

21.15 Keyboard Macros

last-nonmenu-event

21.4 Information from the Command Loop

last-prefix-arg

21.11 Prefix Command Arguments

lazy loading

16.4 Dynamic Loading of Individual Functions

leading code

33.1 Text Representations

left-margin

32.12 Margins for Filling

left-margin-width

38.12.3 Displaying in the Margins

length

6.1 Sequences

let

11.3 Local Variables

let*

11.3 Local Variables

lexical binding (Edebug)

18.2.9 Evaluation

lexical comparison

4.5 Comparison of Characters and Strings

library

15. Loading

library compilation

16.2 The Compilation Functions

library header comments

D.5 Conventional Headers for Emacs Libraries

line wrapping

38.3 Truncation

line-beginning-position

30.2.4 Motion by Text Lines

line-end-position

30.2.4 Motion by Text Lines

line-move-ignore-invisible

38.5 Invisible Text

lines

30.2.4 Motion by Text Lines

lines in region

30.2.4 Motion by Text Lines

linking files

25.7 Changing File Names and Attributes

Lisp debugger

18.1 The Lisp Debugger

Lisp expression motion

30.2.6 Moving over Balanced Expressions

Lisp history

1.2 Lisp History

Lisp library

15. Loading

Lisp nesting error

9.4 Eval

Lisp object

2. Lisp Data Types

Lisp printer

19.5 Output Functions

Lisp reader

19.1 Introduction to Reading and Printing

lisp-interaction-mode-map

H. Standard Keymaps

lisp-mode-abbrev-table

36.6 Standard Abbrev Tables

lisp-mode-map

H. Standard Keymaps

`lisp-mode.el'

23.1.2 Major Mode Examples

list

5.5 Building Cons Cells and Lists

list elements

5.4 Accessing Elements of Lists

list form evaluation

9.2.3 Classification of List Forms

list in keymap

22.7 Key Lookup

list length

6.1 Sequences

list motion

30.2.6 Moving over Balanced Expressions

list structure

5.1 Lists and Cons Cells

list-buffers-directory

27.4 Buffer File Name

list-diary-entries-hook

39.8 Fancy Diary Display

list-hebrew-diary-entries

39.7 Hebrew- and Islamic-Date Diary Entries

list-islamic-diary-entries

39.7 Hebrew- and Islamic-Date Diary Entries

list-processes

37.6 Process Information

listify-key-sequence

21.7.5 Miscellaneous Event Input Features

listp

5.3 Predicates on Lists

lists and cons cells

5.1 Lists and Cons Cells

lists as sets

5.7 Using Lists as Sets

lists represented as boxes

5.2 Lists as Linked Pairs of Boxes

literal evaluation

9.2.1 Self-Evaluating Forms

ln

25.7 Changing File Names and Attributes

load

15.1 How Programs Do Loading

load error with require

15.6 Features

load errors

15.1 How Programs Do Loading

load-average

40.3 Operating System Environment

load-file

15.1 How Programs Do Loading

load-history

15.7 Unloading

load-in-progress

15.1 How Programs Do Loading

load-library

15.1 How Programs Do Loading

load-path

15.2 Library Search

load-read-function

15.1 How Programs Do Loading

loadhist-special-hooks

15.7 Unloading

loading

15. Loading

loading hooks

15.8 Hooks for Loading

`loadup.el'

E.1 Building Emacs

local binding

11.3 Local Variables

local keymap

22.6 Active Keymaps

local variables

11.3 Local Variables

local-abbrev-table

36.6 Standard Abbrev Tables

local-holidays

39.2 Customizing the Holidays

local-key-binding

22.8 Functions for Key Lookup

local-map (overlay property)

38.9.1 Overlay Properties

local-map (text property)

32.19.4 Properties with Special Meanings

local-set-key

22.10 Commands for Binding Keys

local-unset-key

22.10 Commands for Binding Keys

local-variable-p

11.10.2 Creating and Deleting Buffer-Local Bindings

local-write-file-hooks

25.2 Saving Buffers

locale

33.12 Locales

locale-coding-system

33.12 Locales

locate-library

15.2 Library Search

lock-buffer

25.5 File Locks

log

3.9 Standard Mathematical Functions

log10

3.9 Standard Mathematical Functions

logand

3.8 Bitwise Operations on Integers

logb

3.2 Floating Point Basics

logical and

3.8 Bitwise Operations on Integers

logical exclusive or

3.8 Bitwise Operations on Integers

logical inclusive or

3.8 Bitwise Operations on Integers

logical not

3.8 Bitwise Operations on Integers

logical shift

3.8 Bitwise Operations on Integers

logior

3.8 Bitwise Operations on Integers

lognot

3.8 Bitwise Operations on Integers

logxor

3.8 Bitwise Operations on Integers

looking-at

34.3 Regular Expression Searching

lookup-key

22.8 Functions for Key Lookup

loops, infinite

18.1.2 Debugging Infinite Loops

lower case

4.8 Case Conversion in Lisp

lower-frame

29.11 Raising and Lowering Frames

lowering a frame

29.11 Raising and Lowering Frames

lsh

3.8 Bitwise Operations on Integers

M

M-g

22.5 Prefix Keys

M-x

21.3 Interactive Call

Maclisp

1.2 Lisp History

macro

12.1 What Is a Function?

macro argument evaluation

13.6.2 Evaluating Macro Arguments Repeatedly

macro call

13.2 Expansion of a Macro Call

macro call evaluation

9.2.6 Lisp Macro Evaluation

macro compilation

16.2 The Compilation Functions

macro descriptions

1.3.7.1 A Sample Function Description

macro expansion

13.2 Expansion of a Macro Call

macroexpand

13.2 Expansion of a Macro Call

macros

13. Macros

magic file names

25.11 Making Certain File Names "Magic"

mail-host-address

40.3 Operating System Environment

major mode

23.1 Major Modes

major mode hook

23.1.1 Major Mode Conventions

major mode keymap

22.6 Active Keymaps

major-mode

23.1.4 Getting Help about a Major Mode

make-abbrev-table

36.2 Abbrev Tables

make-auto-save-file-name

26.2 Auto-Saving

make-backup-file-name

26.1.4 Naming Backup Files

make-backup-file-name-function

26.1.1 Making Backup Files

make-backup-files

26.1.1 Making Backup Files

make-bool-vector

6.7 Bool-vectors

make-byte-code

16.6 Byte-Code Function Objects

make-category-set

35.9 Categories

make-category-table

35.9 Categories

make-char

33.7 Splitting Characters

make-char-table

6.6 Char-Tables

make-directory

25.10 Creating and Deleting Directories

make-display-table

38.17.1 Display Table Format

make-face

38.11.7 Functions for Working with Faces

make-frame

29.1 Creating Frames

make-frame-invisible

29.10 Visibility of Frames

make-frame-on-display

29.2 Multiple Displays

make-frame-visible

29.10 Visibility of Frames

make-frame-visible event

21.6.10 Miscellaneous Window System Events

make-hash-table

7.1 Creating Hash Tables

make-help-screen

24.5 Help Functions

make-indirect-buffer

27.11 Indirect Buffers

make-keymap

22.3 Creating Keymaps

make-list

5.5 Building Cons Cells and Lists

make-local-hook

23.6 Hooks

make-local-variable

11.10.2 Creating and Deleting Buffer-Local Bindings

make-marker

31.3 Functions that Create Markers

make-overlay

38.9.2 Managing Overlays

make-sparse-keymap

22.3 Creating Keymaps

make-string

4.3 Creating Strings

make-symbol

8.3 Creating and Interning Symbols

make-symbolic-link

25.7 Changing File Names and Attributes

make-syntax-table

35.3 Syntax Table Functions

make-temp-file

25.8.5 Generating Unique File Names

make-temp-name

25.8.5 Generating Unique File Names

make-translation-table

33.9 Translation of Characters

make-variable-buffer-local

11.10.2 Creating and Deleting Buffer-Local Bindings

make-variable-frame-local

11.11 Frame-Local Variables

make-vector

6.5 Functions for Vectors

makehash

7.1 Creating Hash Tables

makunbound

11.4 When a Variable is "Void"

map-char-table

6.6 Char-Tables

map-y-or-n-p

20.7 Asking Multiple Y-or-N Questions

mapatoms

8.3 Creating and Interning Symbols

mapc

12.6 Mapping Functions

mapcar

12.6 Mapping Functions

mapconcat

12.6 Mapping Functions

maphash

7.2 Hash Table Access

mapping functions

12.6 Mapping Functions

margins, display

38.12.3 Displaying in the Margins

mark

31.7 The Mark

mark excursion

30.3 Excursions

mark ring

31.7 The Mark

mark, the

31.7 The Mark

mark-active

31.7 The Mark

mark-diary-entries-hook

39.8 Fancy Diary Display

mark-diary-entries-in-calendar

39.1 Customizing the Calendar

mark-even-if-inactive

31.7 The Mark

mark-hebrew-diary-entries

39.7 Hebrew- and Islamic-Date Diary Entries

mark-holidays-in-calendar

39.1 Customizing the Calendar

mark-included-diary-files

39.8 Fancy Diary Display

mark-islamic-diary-entries

39.7 Hebrew- and Islamic-Date Diary Entries

mark-marker

31.7 The Mark

mark-ring

31.7 The Mark

mark-ring-max

31.7 The Mark

marker argument

21.2.2 Code Characters for interactive

marker garbage collection

31.1 Overview of Markers

marker input stream

19.2 Input Streams

marker output stream

19.4 Output Streams

marker relocation

31.1 Overview of Markers

marker-buffer

31.4 Information from Markers

marker-insertion-type

31.5 Marker Insertion Types

marker-position

31.4 Information from Markers

markerp

31.2 Predicates on Markers

markers

31. Markers

markers as numbers

31.1 Overview of Markers

match data

34.6 The Match Data

match-beginning

34.6.2 Simple Match Data Access

match-data

34.6.3 Accessing the Entire Match Data

match-end

34.6.2 Simple Match Data Access

match-string

34.6.2 Simple Match Data Access

match-string-no-properties

34.6.2 Simple Match Data Access

mathematical functions

3.9 Standard Mathematical Functions

max

3.4 Comparison of Numbers

max-lisp-eval-depth

9.4 Eval

max-specpdl-size

11.3 Local Variables

md5

32.24 MD5 Checksum

MD5 checksum

32.24 MD5 Checksum

member

5.7 Using Lists as Sets

member-ignore-case

5.7 Using Lists as Sets

membership in a list

5.7 Using Lists as Sets

memory allocation

E.3 Garbage Collection

memory-limit

E.3 Garbage Collection

memq

5.7 Using Lists as Sets

menu bar

22.12.5 The Menu Bar

menu definition example

22.12.4 Menu Example

menu keymaps

22.12 Menu Keymaps

menu prompt string

22.12.1 Defining Menus

menu separators

22.12.1.3 Menu Separators

menu-bar prefix key

21.7.1 Key Sequence Input

menu-bar-edit-menu

H. Standard Keymaps

menu-bar-files-menu

H. Standard Keymaps

menu-bar-final-items

22.12.5 The Menu Bar

menu-bar-help-menu

H. Standard Keymaps

menu-bar-mule-menu

H. Standard Keymaps

menu-bar-search-menu

H. Standard Keymaps

menu-bar-tools-menu

H. Standard Keymaps

menu-bar-update-hook

22.12.5 The Menu Bar

menu-item

22.12.1.2 Extended Menu Items

menu-prompt-more-char

22.12.3 Menus and the Keyboard

message

38.4 The Echo Area

message digest computation

32.24 MD5 Checksum

message-box

38.4 The Echo Area

message-log-max

38.4 The Echo Area

message-or-box

38.4 The Echo Area

message-truncate-lines

38.4 The Echo Area

meta character key constants

22.9 Changing Key Bindings

meta character printing

24.4 Describing Characters for Help Messages

meta characters

2.3.3 Character Type

meta characters lookup

22.2 Format of Keymaps

meta-prefix-char

22.8 Functions for Key Lookup

min

3.4 Comparison of Numbers

minibuffer

20. Minibuffers

minibuffer history

20.4 Minibuffer History

minibuffer input

21.12 Recursive Editing

minibuffer window

28.5 Cyclic Ordering of Windows

minibuffer-allow-text-properties

20.2 Reading Text Strings with the Minibuffer

minibuffer-auto-raise

29.11 Raising and Lowering Frames

minibuffer-complete

20.5.3 Minibuffer Commands that Do Completion

minibuffer-complete-and-exit

20.5.3 Minibuffer Commands that Do Completion

minibuffer-complete-word

20.5.3 Minibuffer Commands that Do Completion

minibuffer-completion-confirm

20.5.3 Minibuffer Commands that Do Completion

minibuffer-completion-help

20.5.3 Minibuffer Commands that Do Completion

minibuffer-completion-predicate

20.5.3 Minibuffer Commands that Do Completion

minibuffer-completion-table

20.5.3 Minibuffer Commands that Do Completion

minibuffer-contents

20.9 Minibuffer Miscellany

minibuffer-contents-no-properties

20.9 Minibuffer Miscellany

minibuffer-depth

20.9 Minibuffer Miscellany

minibuffer-exit-hook

20.9 Minibuffer Miscellany

minibuffer-frame-alist

29.3.2 Initial Frame Parameters

minibuffer-help-form

20.9 Minibuffer Miscellany

minibuffer-history

20.4 Minibuffer History

minibuffer-local-completion-map

20.5.3 Minibuffer Commands that Do Completion

minibuffer-local-map

20.2 Reading Text Strings with the Minibuffer

minibuffer-local-must-match-map

20.5.3 Minibuffer Commands that Do Completion

minibuffer-local-ns-map

20.2 Reading Text Strings with the Minibuffer

minibuffer-prompt

20.9 Minibuffer Miscellany

minibuffer-prompt-end

20.9 Minibuffer Miscellany

minibuffer-scroll-window

20.9 Minibuffer Miscellany

minibuffer-setup-hook

20.9 Minibuffer Miscellany

minibuffer-window

20.9 Minibuffer Miscellany

minibuffer-window-active-p

20.9 Minibuffer Miscellany

minimum window size

28.15 Changing the Size of a Window

minor mode

23.2 Minor Modes

minor mode conventions

23.2.1 Conventions for Writing Minor Modes

minor-mode-alist

23.3.2 Variables Used in the Mode Line

minor-mode-key-binding

22.8 Functions for Key Lookup

minor-mode-map-alist

22.6 Active Keymaps

minor-mode-overriding-map-alist

22.6 Active Keymaps

minubuffer-prompt-width

20.9 Minibuffer Miscellany

misc-objects-consed

E.4 Memory Usage

mod

3.6 Arithmetic Operations

mode

23. Major and Minor Modes

mode help

23.1.4 Getting Help about a Major Mode

mode hook

23.1.1 Major Mode Conventions

mode line

23.3 Mode Line Format

mode line construct

23.3.1 The Data Structure of the Mode Line

mode loading

23.1.1 Major Mode Conventions

mode variable

23.2.1 Conventions for Writing Minor Modes

mode-class property

23.1.1 Major Mode Conventions

mode-line (face name)

38.11.1 Standard Faces

mode-line prefix key

21.7.1 Key Sequence Input

mode-line-buffer-identification

23.3.2 Variables Used in the Mode Line

mode-line-format

23.3.1 The Data Structure of the Mode Line

mode-line-frame-identification

23.3.2 Variables Used in the Mode Line

mode-line-inverse-video

38.15 Inverse Video

mode-line-modified

23.3.2 Variables Used in the Mode Line

mode-line-mule-info

23.3.2 Variables Used in the Mode Line

mode-line-process

23.3.2 Variables Used in the Mode Line

mode-name

23.3.2 Variables Used in the Mode Line

mode-specific-map

22.5 Prefix Keys

modeline (face name)

38.11.1 Standard Faces

modification flag (of buffer)

27.5 Buffer Modification

modification of lists

5.6.3 Functions that Rearrange Lists

modification time, comparison of

27.6 Comparison of Modification Time

modification-hooks (overlay property)

38.9.1 Overlay Properties

modification-hooks (text property)

32.19.4 Properties with Special Meanings

modifier bits (of input character)

21.6.1 Keyboard Events

modify-category-entry

35.9 Categories

modify-frame-parameters

29.3.1 Access to Frame Parameters

modify-syntax-entry

35.3 Syntax Table Functions

modulus

3.6 Arithmetic Operations

momentary-string-display

38.8 Temporary Displays

motion event

21.6.8 Motion Events

mouse click event

21.6.4 Click Events

mouse drag event

21.6.5 Drag Events

mouse event, timestamp

21.6.13 Accessing Events

mouse events, accessing the data

21.6.13 Accessing Events

mouse events, in special parts of frame

21.7.1 Key Sequence Input

mouse events, repeated

21.6.7 Repeat Events

mouse motion events

21.6.8 Motion Events

mouse pointer shape

29.17 Pointer Shapes

mouse position

29.14 Mouse Position

mouse position list, accessing

21.6.13 Accessing Events

mouse tracking

29.13 Mouse Tracking

mouse, availability

29.22 Display Feature Testing

mouse-2

D.1 Emacs Lisp Coding Conventions

mouse-face (overlay property)

38.9.1 Overlay Properties

mouse-face (text property)

32.19.4 Properties with Special Meanings

mouse-movement-p

21.6.12 Classifying Events

mouse-pixel-position

29.14 Mouse Position

mouse-position

29.14 Mouse Position

mouse-position-function

29.14 Mouse Position

mouse-wheel event

21.6.10 Miscellaneous Window System Events

move-marker

31.6 Moving Marker Positions

move-overlay

38.9.2 Managing Overlays

move-to-column

32.16 Counting Columns

move-to-left-margin

32.12 Margins for Filling

move-to-window-line

30.2.5 Motion by Screen Lines

movemail

37.1 Functions that Create Subprocesses

MS-DOS and file modes

25.7 Changing File Names and Attributes

MS-DOS file types

33.10.9 MS-DOS File Types

mule-keymap

22.5 Prefix Keys

multibyte characters

33. Non-ASCII Characters

multibyte text

33.1 Text Representations

multibyte-string-p

33.1 Text Representations

multibyte-syntax-as-symbol

35.6 Parsing Balanced Expressions

multiple windows

28.1 Basic Concepts of Emacs Windows

multiple X displays

29.2 Multiple Displays

multiple-frames

29.4 Frame Titles

N

named function

12.3 Naming a Function

NaN

3.2 Floating Point Basics

narrow-to-page

30.4 Narrowing

narrow-to-region

30.4 Narrowing

narrowing

30.4 Narrowing

natnump

3.3 Type Predicates for Numbers

natural numbers

3.3 Type Predicates for Numbers

nbutlast

5.4 Accessing Elements of Lists

nconc

5.6.3 Functions that Rearrange Lists

negative infinity

3.2 Floating Point Basics

negative-argument

21.11 Prefix Command Arguments

network connection

37.12 Network Connections

network-coding-system-alist

33.10.5 Default Coding Systems

new file message

25.1.2 Subroutines of Visiting

newline

32.5 User-Level Insertion Commands

newline and Auto Fill mode

32.5 User-Level Insertion Commands

newline in print

19.5 Output Functions

newline in strings

2.3.8.1 Syntax for Strings

newline-and-indent

32.17.2 Indentation Controlled by Major Mode

next input

21.7.5 Miscellaneous Event Input Features

next-char-property-change

32.19.3 Text Property Search Functions

next-frame

29.6 Finding All Frames

next-history-element

20.9 Minibuffer Miscellany

next-matching-history-element

20.9 Minibuffer Miscellany

next-overlay-change

38.9.3 Searching for Overlays

next-property-change

32.19.3 Text Property Search Functions

next-screen-context-lines

28.11 Textual Scrolling

next-single-char-property-change

32.19.3 Text Property Search Functions

next-single-property-change

32.19.3 Text Property Search Functions

next-window

28.5 Cyclic Ordering of Windows

nil

11.2 Variables that Never Change

nil and lists

5.1 Lists and Cons Cells

nil in keymap

22.7 Key Lookup

nil in lists

2.3.6 Cons Cell and List Types

nil input stream

19.2 Input Streams

nil output stream

19.4 Output Streams

nil, uses of

1.3.2 nil and t

nlistp

5.3 Predicates on Lists

no-catch

10.5.1 Explicit Nonlocal Exits: catch and throw

no-redraw-on-reenter

38.1 Refreshing the Screen

non-ASCII characters

33. Non-ASCII Characters

non-ASCII text in keybindings

22.10 Commands for Binding Keys

nonascii-insert-offset

33.2 Converting Text Representations

nonascii-translation-table

33.2 Converting Text Representations

nondirectory part (of file name)

25.8.1 File Name Components

nongregorian-diary-listing-hook

39.7 Hebrew- and Islamic-Date Diary Entries

nongregorian-diary-marking-hook

39.7 Hebrew- and Islamic-Date Diary Entries

noninteractive

40.13 Batch Mode

noninteractive use

40.13 Batch Mode

nonlocal exits

10.5 Nonlocal Exits

nonprinting characters, reading

21.7.4 Quoted Character Input

normal hook

23.6 Hooks

normal-auto-fill-function

32.14 Auto Filling

normal-backup-enable-predicate

26.1.1 Making Backup Files

normal-mode

23.1.3 How Emacs Chooses a Major Mode

not

10.3 Constructs for Combining Conditions

not-modified

27.5 Buffer Modification

nreverse

5.6.3 Functions that Rearrange Lists

nth

5.4 Accessing Elements of Lists

nthcdr

5.4 Accessing Elements of Lists

null

5.3 Predicates on Lists

num-input-keys

21.7.1 Key Sequence Input

num-nonmacro-input-events

21.7.1 Key Sequence Input

number equality

3.4 Comparison of Numbers

number-of-diary-entries

39.6 Customizing the Diary

number-or-marker-p

31.2 Predicates on Markers

number-to-string

4.6 Conversion of Characters and Strings

numberp

3.3 Type Predicates for Numbers

numbers

3. Numbers

numeric prefix

4.7 Formatting Strings

numeric prefix argument

21.11 Prefix Command Arguments

numeric prefix argument usage

21.2.2 Code Characters for interactive

O

obarray

8.3 Creating and Interning Symbols

obarray in completion

20.5.1 Basic Completion Functions

object

2. Lisp Data Types

object internals

E.6 Object Internals

object to string

19.5 Output Functions

obsolete buffer

27.6 Comparison of Modification Time

occur-mode-map

H. Standard Keymaps

octal character code

2.3.3 Character Type

octal character input

21.7.4 Quoted Character Input

omer count

39.9 Sexp Entries and the Fancy Diary Display

one-window-p

28.2 Splitting Windows

only-global-abbrevs

36.3 Defining Abbrevs

open parenthesis character

35.2.1 Table of Syntax Classes

open-dribble-file

40.8.3 Recording Input

open-network-stream

37.12 Network Connections

open-paren-in-column-0-is-defun-start

30.2.6 Moving over Balanced Expressions

open-termscript

40.9 Terminal Output

operating system environment

40.3 Operating System Environment

option descriptions

1.3.7.2 A Sample Variable Description

optional arguments

12.2.3 Other Features of Argument Lists

options on command line

40.1.4 Command-Line Arguments

or

10.3 Constructs for Combining Conditions

ordering of windows, cyclic

28.5 Cyclic Ordering of Windows

other-buffer

27.8 The Buffer List

other-holidays

39.2 Customizing the Holidays

other-window

28.5 Cyclic Ordering of Windows

other-window-scroll-buffer

28.11 Textual Scrolling

output from processes

37.9 Receiving Output from Processes

output stream

19.4 Output Streams

overall prompt string

22.2 Format of Keymaps

overflow

3.1 Integer Basics

overlay arrow

38.7 The Overlay Arrow

overlay-arrow-position

38.7 The Overlay Arrow

overlay-arrow-string

38.7 The Overlay Arrow

overlay-buffer

38.9.2 Managing Overlays

overlay-end

38.9.2 Managing Overlays

overlay-get

38.9.1 Overlay Properties

overlay-put

38.9.1 Overlay Properties

overlay-start

38.9.2 Managing Overlays

overlays

38.9 Overlays

overlays-at

38.9.3 Searching for Overlays

overlays-in

38.9.3 Searching for Overlays

overriding-local-map

22.6 Active Keymaps

overriding-local-map-menu-flag

22.6 Active Keymaps

overriding-terminal-local-map

22.6 Active Keymaps

overwrite-mode

32.5 User-Level Insertion Commands

P

padding

4.7 Formatting Strings

page-delimiter

34.8 Standard Regular Expressions Used in Editing

paired delimiter

35.2.1 Table of Syntax Classes

paragraph-separate

34.8 Standard Regular Expressions Used in Editing

paragraph-start

34.8 Standard Regular Expressions Used in Editing

parasha, weekly

39.9 Sexp Entries and the Fancy Diary Display

parent of char-table

6.6 Char-Tables

parent process

37. Processes

parenthesis

2.3.6 Cons Cell and List Types

parenthesis depth

35.6 Parsing Balanced Expressions

parenthesis matching

38.14 Blinking Parentheses

parenthesis syntax

35.2.1 Table of Syntax Classes

parse state

35.6 Parsing Balanced Expressions

parse-colon-path

40.3 Operating System Environment

parse-partial-sexp

35.6 Parsing Balanced Expressions

parse-sexp-ignore-comments

35.6 Parsing Balanced Expressions

parse-sexp-lookup-properties

35.4 Syntax Properties

parsing

35. Syntax Tables

passwords, reading

20.8 Reading a Password

PATH environment variable

37.1 Functions that Create Subprocesses

path-separator

40.3 Operating System Environment

pausing

21.9 Waiting for Elapsed Time or Input

PBM

38.13.6 Other Image Types

peculiar error

10.5.3.4 Error Symbols and Condition Names

peeking at input

21.7.5 Miscellaneous Event Input Features

percent symbol in mode line

23.3.1 The Data Structure of the Mode Line

perform-replace

34.5 Search and Replace

performance analysis

18.2.13 Coverage Testing

permanent local variable

11.10.2 Creating and Deleting Buffer-Local Bindings

permission

25.6.4 Other Information about Files

piece of advice

17. Advising Emacs Lisp Functions

pipes

37.4 Creating an Asynchronous Process

play-sound

40.10 Sound Output

play-sound-file

40.10 Sound Output

play-sound-functions

40.10 Sound Output

plist

8.4 Property Lists

plist-get

8.4.3 Property Lists Outside Symbols

plist-member

8.4.3 Property Lists Outside Symbols

plist-put

8.4.3 Property Lists Outside Symbols

point

30.1 Point

point excursion

30.3 Excursions

point in window

28.9 Windows and Point

point with narrowing

30.1 Point

point-entered (text property)

32.19.4 Properties with Special Meanings

point-left (text property)

32.19.4 Properties with Special Meanings

point-marker

31.3 Functions that Create Markers

point-max

30.1 Point

point-max-marker

31.3 Functions that Create Markers

point-min

30.1 Point

point-min-marker

31.3 Functions that Create Markers

pointer shape

29.17 Pointer Shapes

pointers

2.3.6 Cons Cell and List Types

pop

5.4 Accessing Elements of Lists

pop-mark

31.7 The Mark

pop-to-buffer

28.7 Displaying Buffers in Windows

pop-up-frame-alist

28.8 Choosing a Window for Display

pop-up-frame-function

28.8 Choosing a Window for Display

pop-up-frames

28.8 Choosing a Window for Display

pop-up-windows

28.8 Choosing a Window for Display

pos-visible-in-window-p

28.10 The Window Start Position

position (in buffer)

30. Positions

position argument

21.2.2 Code Characters for interactive

position in window

28.9 Windows and Point

position of mouse

29.14 Mouse Position

position-bytes

33.1 Text Representations

positive infinity

3.2 Floating Point Basics

posix-looking-at

34.4 POSIX Regular Expression Searching

posix-search-backward

34.4 POSIX Regular Expression Searching

posix-search-forward

34.4 POSIX Regular Expression Searching

posix-string-match

34.4 POSIX Regular Expression Searching

posn-col-row

21.6.13 Accessing Events

posn-point

21.6.13 Accessing Events

posn-timestamp

21.6.13 Accessing Events

posn-window

21.6.13 Accessing Events

posn-x-y

21.6.13 Accessing Events

post-command-hook

21.1 Command Loop Overview

Postscript images

38.13.5 Postscript Images

pre-abbrev-expand-hook

36.5 Looking Up and Expanding Abbreviations

pre-command-hook

21.1 Command Loop Overview

preactivating advice

17.7 Preactivation

preceding-char

32.1 Examining Text Near Point

predicates

2.6 Type Predicates

prefix argument

21.11 Prefix Command Arguments

prefix argument unreading

21.7.5 Miscellaneous Event Input Features

prefix command

22.5 Prefix Keys

prefix key

22.5 Prefix Keys

prefix-arg

21.11 Prefix Command Arguments

prefix-help-command

24.5 Help Functions

prefix-numeric-value

21.11 Prefix Command Arguments

preventing backtracking

18.2.15.1 Specification List

preventing prefix key

22.7 Key Lookup

previous complete subexpression

35.6 Parsing Balanced Expressions

previous-char-property-change

32.19.3 Text Property Search Functions

previous-frame

29.6 Finding All Frames

previous-history-element

20.9 Minibuffer Miscellany

previous-matching-history-element

20.9 Minibuffer Miscellany

previous-overlay-change

38.9.3 Searching for Overlays

previous-property-change

32.19.3 Text Property Search Functions

previous-single-char-property-change

32.19.3 Text Property Search Functions

previous-single-property-change

32.19.3 Text Property Search Functions

previous-window

28.5 Cyclic Ordering of Windows

primitive

12.1 What Is a Function?

primitive function internals

E.5 Writing Emacs Primitives

primitive type

2. Lisp Data Types

primitive-undo

32.9 Undo

prin1

19.5 Output Functions

prin1-to-string

19.5 Output Functions

princ

19.5 Output Functions

print

19.5 Output Functions

print example

19.4 Output Streams

print name cell

8.1 Symbol Components

print-circle

19.6 Variables Affecting Output

print-diary-entries

39.6 Customizing the Diary

print-diary-entries-hook

39.6 Customizing the Diary

print-escape-multibyte

19.6 Variables Affecting Output

print-escape-newlines

19.6 Variables Affecting Output

print-escape-nonascii

19.6 Variables Affecting Output

print-gensym

19.6 Variables Affecting Output

print-help-return-message

24.5 Help Functions

print-length

19.6 Variables Affecting Output

print-level

19.6 Variables Affecting Output

printed representation

2.1 Printed Representation and Read Syntax

printed representation for characters

2.3.3 Character Type

printing

19.1 Introduction to Reading and Printing

printing (Edebug)

18.2.11 Printing in Edebug

printing circular structures

18.2.11 Printing in Edebug

printing limits

19.6 Variables Affecting Output

printing notation

1.3.4 Printing Notation

priority (overlay property)

38.9.1 Overlay Properties

process

37. Processes

process filter

37.9.2 Process Filter Functions

process input

37.7 Sending Input to Processes

process internals

E.6.3 Process Internals

process output

37.9 Receiving Output from Processes

process sentinel

37.10 Sentinels: Detecting Process Status Changes

process signals

37.8 Sending Signals to Processes

process-buffer

37.9.1 Process Buffers

process-coding-system

37.6 Process Information

process-coding-system-alist

33.10.5 Default Coding Systems

process-command

37.6 Process Information

process-connection-type

37.4 Creating an Asynchronous Process

process-contact

37.6 Process Information

process-environment

40.3 Operating System Environment

process-exit-status

37.6 Process Information

process-filter

37.9.2 Process Filter Functions

process-id

37.6 Process Information

process-kill-without-query

37.5 Deleting Processes

process-list

37.6 Process Information

process-mark

37.9.1 Process Buffers

process-name

37.6 Process Information

process-running-child-p

37.7 Sending Input to Processes

process-send-eof

37.7 Sending Input to Processes

process-send-region

37.7 Sending Input to Processes

process-send-string

37.7 Sending Input to Processes

process-sentinel

37.10 Sentinels: Detecting Process Status Changes

process-status

37.6 Process Information

process-tty-name

37.6 Process Information

processp

37. Processes

`profile.el'

D.2 Tips for Making Compiled Code Fast

profiling

D.2 Tips for Making Compiled Code Fast

prog1

10.1 Sequencing

prog2

10.1 Sequencing

progn

10.1 Sequencing

program arguments

37.1 Functions that Create Subprocesses

program directories

37.1 Functions that Create Subprocesses

programmed completion

20.5.6 Programmed Completion

programming types

2.3 Programming Types

prompt string (of menu)

22.12.1 Defining Menus

prompt string of keymap

22.2 Format of Keymaps

properties of text

32.19 Text Properties

propertize

32.19.2 Changing Text Properties

property list

8.4 Property Lists

property list cell

8.1 Symbol Components

property lists vs association lists

8.4.1 Property Lists and Association Lists

protected forms

10.5.4 Cleaning Up from Nonlocal Exits

provide

15.6 Features

providing features

15.6 Features

PTYs

37.4 Creating an Asynchronous Process

punctuation character

35.2.1 Table of Syntax Classes

pure storage

E.2 Pure Storage

pure-bytes-used

E.2 Pure Storage

purecopy

E.2 Pure Storage

purify-flag

E.2 Pure Storage

push

5.5 Building Cons Cells and Lists

push-mark

31.7 The Mark

put

8.4.2 Property List Functions for Symbols

put-image

38.13.8 Showing Images

put-text-property

32.19.2 Changing Text Properties

puthash

7.2 Hash Table Access

Q

query-replace-history

20.4 Minibuffer History

query-replace-map

34.5 Search and Replace

querying the user

20.6 Yes-or-No Queries

question mark in character constant

2.3.3 Character Type

quietly-read-abbrev-file

36.4 Saving Abbrevs in Files

quit-flag

21.10 Quitting

quit-process

37.8 Sending Signals to Processes

quitting

21.10 Quitting

quitting from infinite loop

18.1.2 Debugging Infinite Loops

quote

9.3 Quoting

quote character

35.6 Parsing Balanced Expressions

quoted character input

21.7.4 Quoted Character Input

quoted-insert suppression

22.9 Changing Key Bindings

quoting

9.3 Quoting

quoting characters in printing

19.5 Output Functions

quoting using apostrophe

9.3 Quoting

R

radix for reading an integer

3.1 Integer Basics

raise-frame

29.11 Raising and Lowering Frames

raising a frame

29.11 Raising and Lowering Frames

random

3.10 Random Numbers

random numbers

3.10 Random Numbers

rassoc

5.8 Association Lists

rassq

5.8 Association Lists

raw prefix argument

21.11 Prefix Command Arguments

raw prefix argument usage

21.2.2 Code Characters for interactive

re-search-backward

34.3 Regular Expression Searching

re-search-forward

34.3 Regular Expression Searching

reactivating advice

17.5 Activation of Advice

read

19.3 Input Functions

read command name

21.3 Interactive Call

read syntax

2.1 Printed Representation and Read Syntax

read syntax for characters

2.3.3 Character Type

read-buffer

20.5.4 High-Level Completion Functions

read-buffer-function

20.5.4 High-Level Completion Functions

read-char

21.7.2 Reading One Event

read-char-exclusive

21.7.2 Reading One Event

read-coding-system

33.10.4 User-Chosen Coding Systems

read-command

20.5.4 High-Level Completion Functions

read-event

21.7.2 Reading One Event

read-expression-history

20.4 Minibuffer History

read-file-name

20.5.5 Reading File Names

read-from-minibuffer

20.2 Reading Text Strings with the Minibuffer

read-from-string

19.3 Input Functions

read-input-method-name

33.11 Input Methods

read-kbd-macro

24.4 Describing Characters for Help Messages

read-key-sequence

21.7.1 Key Sequence Input

read-key-sequence-vector

21.7.1 Key Sequence Input

read-minibuffer

20.3 Reading Lisp Objects with the Minibuffer

read-no-blanks-input

20.2 Reading Text Strings with the Minibuffer

read-non-nil-coding-system

33.10.4 User-Chosen Coding Systems

read-only (text property)

32.19.4 Properties with Special Meanings

read-only buffer

27.7 Read-Only Buffers

read-only buffers in interactive

21.2.1 Using interactive

read-only character

32.19.4 Properties with Special Meanings

read-passwd

20.8 Reading a Password

read-quoted-char

21.7.4 Quoted Character Input

read-quoted-char quitting

21.10 Quitting

read-string

20.2 Reading Text Strings with the Minibuffer

read-variable

20.5.4 High-Level Completion Functions

reading

19.1 Introduction to Reading and Printing

reading a single event

21.7.2 Reading One Event

reading interactive arguments

21.2.2 Code Characters for interactive

reading symbols

8.3 Creating and Interning Symbols

real-last-command

21.4 Information from the Command Loop

rearrangement of lists

5.6.3 Functions that Rearrange Lists

rebinding

22.9 Changing Key Bindings

recent-auto-save-p

26.2 Auto-Saving

recent-keys

40.8.3 Recording Input

recenter

28.11 Textual Scrolling

record command history

21.3 Interactive Call

recursion

10.4 Iteration

recursion-depth

21.12 Recursive Editing

recursive command loop

21.12 Recursive Editing

recursive editing level

21.12 Recursive Editing

recursive evaluation

9.1 Introduction to Evaluation

recursive-edit

21.12 Recursive Editing

redirect-frame-focus

29.9 Input Focus

redisplay-dont-pause

38.2 Forcing Redisplay

redisplay-end-trigger-functions

28.18 Hooks for Window Scrolling and Changes

redo

32.9 Undo

redraw-display

38.1 Refreshing the Screen

redraw-frame

38.1 Refreshing the Screen

references, following

D.1 Emacs Lisp Coding Conventions

regexp

34.2 Regular Expressions

regexp alternative

34.2.1.3 Backslash Constructs in Regular Expressions

regexp grouping

34.2.1.3 Backslash Constructs in Regular Expressions

regexp searching

34.3 Regular Expression Searching

regexp-history

20.4 Minibuffer History

regexp-opt

34.2.3 Regular Expression Functions

regexp-opt-depth

34.2.3 Regular Expression Functions

regexp-quote

34.2.3 Regular Expression Functions

regexps used standardly in editing

34.8 Standard Regular Expressions Used in Editing

region (face name)

38.11.1 Standard Faces

region argument

21.2.2 Code Characters for interactive

region, the

31.8 The Region

region-beginning

31.8 The Region

region-end

31.8 The Region

register-alist

32.21 Registers

registers

32.21 Registers

regular expression

34.2 Regular Expressions

regular expression searching

34.3 Regular Expression Searching

reindent-then-newline-and-indent

32.17.2 Indentation Controlled by Major Mode

relative file name

25.8.3 Absolute and Relative File Names

remainder

3.6 Arithmetic Operations

remhash

7.2 Hash Table Access

remove

5.7 Using Lists as Sets

remove-from-invisibility-spec

38.5 Invisible Text

remove-hook

23.6 Hooks

remove-images

38.13.8 Showing Images

remove-text-properties

32.19.2 Changing Text Properties

remq

5.5 Building Cons Cells and Lists

rename-auto-save-file

26.2 Auto-Saving

rename-buffer

27.3 Buffer Names

rename-file

25.7 Changing File Names and Attributes

renaming files

25.7 Changing File Names and Attributes

repeat events

21.6.7 Repeat Events

repeated loading

15.5 Repeated Loading

replace bindings

22.9 Changing Key Bindings

replace characters

32.20 Substituting for a Character Code

replace-buffer-in-windows

28.7 Displaying Buffers in Windows

replace-match

34.6.1 Replacing the Text that Matched

replacement

34.5 Search and Replace

require

15.6 Features

require-final-newline

25.2 Saving Buffers

requiring features

15.6 Features

reserved keys

D.1 Emacs Lisp Coding Conventions

resize frame

29.3.4 Frame Size And Position

rest arguments

12.2.3 Other Features of Argument Lists

restriction (in a buffer)

30.4 Narrowing

resume (cf. no-redraw-on-reenter)

38.1 Refreshing the Screen

return

2.3.3 Character Type

reverse

5.5 Building Cons Cells and Lists

reversing a list

5.6.3 Functions that Rearrange Lists

revert-buffer

26.3 Reverting

revert-buffer-function

26.3 Reverting

revert-buffer-insert-file-contents-function

26.3 Reverting

revert-without-query

26.3 Reverting

rgb value

29.20 Text Terminal Colors

right-margin-width

38.12.3 Displaying in the Margins

ring-bell-function

38.18 Beeping

rm

25.7 Changing File Names and Attributes

rosh hodesh

39.9 Sexp Entries and the Fancy Diary Display

round

3.5 Numeric Conversions

rounding in conversions

3.5 Numeric Conversions

rounding without conversion

3.7 Rounding Operations

rplaca

5.6 Modifying Existing List Structure

rplacd

5.6 Modifying Existing List Structure

run time stack

18.1.8 Internals of the Debugger

run-at-time

40.7 Timers for Delayed Execution

run-hook-with-args

23.6 Hooks

run-hook-with-args-until-failure

23.6 Hooks

run-hook-with-args-until-success

23.6 Hooks

run-hooks

23.6 Hooks

run-with-idle-timer

40.7 Timers for Delayed Execution

S

safe-length

5.4 Accessing Elements of Lists

same-window-buffer-names

28.8 Choosing a Window for Display

same-window-regexps

28.8 Choosing a Window for Display

save-abbrevs

36.4 Saving Abbrevs in Files

save-buffer

25.2 Saving Buffers

save-buffer-coding-system

33.10.2 Encoding and I/O

save-current-buffer

27.2 The Current Buffer

save-excursion

30.3 Excursions

save-match-data

34.6.4 Saving and Restoring the Match Data

save-restriction

30.4 Narrowing

save-selected-window

28.4 Selecting Windows

save-some-buffers

25.2 Saving Buffers

save-window-excursion

28.17 Window Configurations

saving text properties

32.19.7 Saving Text Properties in Files

saving window information

28.17 Window Configurations

scalable-fonts-allowed

38.11.6 Font Selection

scan-lists

35.6 Parsing Balanced Expressions

scan-sexps

35.6 Parsing Balanced Expressions

scope

11.9 Scoping Rules for Variable Bindings

screen layout

2.4.5 Window Configuration Type

screen layout

2.4.6 Frame Configuration Type

screen of terminal

28.1 Basic Concepts of Emacs Windows

screen size

29.3.4 Frame Size And Position

screen-height

29.3.4 Frame Size And Position

screen-width

29.3.4 Frame Size And Position

scroll-bar (face name)

38.11.1 Standard Faces

scroll-bar-event-ratio

21.6.13 Accessing Events

scroll-bar-scale

21.6.13 Accessing Events

scroll-conservatively

28.11 Textual Scrolling

scroll-down

28.11 Textual Scrolling

scroll-down-aggressively

28.11 Textual Scrolling

scroll-left

28.13 Horizontal Scrolling

scroll-margin

28.11 Textual Scrolling

scroll-other-window

28.11 Textual Scrolling

scroll-preserve-screen-position

28.11 Textual Scrolling

scroll-right

28.13 Horizontal Scrolling

scroll-step

28.11 Textual Scrolling

scroll-up

28.11 Textual Scrolling

scroll-up-aggressively

28.11 Textual Scrolling

scrolling textually

28.11 Textual Scrolling

search-backward

34.1 Searching for Strings

search-failed

34.1 Searching for Strings

search-forward

34.1 Searching for Strings

searching

34. Searching and Matching

searching and case

34.7 Searching and Case

searching for regexp

34.3 Regular Expression Searching

secondary-selection (face name)

38.11.1 Standard Faces

select-frame

29.9 Input Focus

select-safe-coding-system

33.10.4 User-Chosen Coding Systems

select-safe-coding-system-accept-default-p

33.10.4 User-Chosen Coding Systems

select-window

28.4 Selecting Windows

selected frame

29.9 Input Focus

selected window

28.1 Basic Concepts of Emacs Windows

selected-frame

29.9 Input Focus

selected-window

28.4 Selecting Windows

selecting a buffer

27.2 The Current Buffer

selecting windows

28.4 Selecting Windows

selection (for window systems)

29.18 Window System Selections

selection-coding-system

29.18 Window System Selections

selective display

38.6 Selective Display

selective-display

38.6 Selective Display

selective-display-ellipses

38.6 Selective Display

self-evaluating form

9.2.1 Self-Evaluating Forms

self-insert-and-exit

20.9 Minibuffer Miscellany

self-insert-command

32.5 User-Level Insertion Commands

self-insert-command override

22.9 Changing Key Bindings

self-insert-command, minor modes

23.2.2 Keymaps and Minor Modes

self-insertion

32.5 User-Level Insertion Commands

send-string-to-terminal

40.9 Terminal Output

sending signals

37.8 Sending Signals to Processes

sentence-end

34.8 Standard Regular Expressions Used in Editing

sentence-end-double-space

32.11 Filling

sentinel

37.10 Sentinels: Detecting Process Status Changes

sequence

6. Sequences, Arrays, and Vectors

sequence length

6.1 Sequences

sequencep

6.1 Sequences

set

11.8 How to Alter a Variable Value

set-auto-mode

23.1.3 How Emacs Chooses a Major Mode

set-buffer

27.2 The Current Buffer

set-buffer-auto-saved

26.2 Auto-Saving

set-buffer-major-mode

23.1.3 How Emacs Chooses a Major Mode

set-buffer-modified-p

27.5 Buffer Modification

set-buffer-multibyte

33.3 Selecting a Representation

set-case-syntax

4.9 The Case Table

set-case-syntax-delims

4.9 The Case Table

set-case-syntax-pair

4.9 The Case Table

set-case-table

4.9 The Case Table

set-category-table

35.9 Categories

set-char-table-default

6.6 Char-Tables

set-char-table-extra-slot

6.6 Char-Tables

set-char-table-parent

6.6 Char-Tables

set-char-table-range

6.6 Char-Tables

set-default

11.10.3 The Default Value of a Buffer-Local Variable

set-default-file-modes

25.7 Changing File Names and Attributes

set-display-table-slot

38.17.1 Display Table Format

set-face-attribute

38.11.4 Face Attribute Functions

set-face-background

38.11.4 Face Attribute Functions

set-face-bold-p

38.11.4 Face Attribute Functions

set-face-font

38.11.4 Face Attribute Functions

set-face-foreground

38.11.4 Face Attribute Functions

set-face-italic-p

38.11.4 Face Attribute Functions

set-face-stipple

38.11.4 Face Attribute Functions

set-face-underline-p

38.11.4 Face Attribute Functions

set-file-modes

25.7 Changing File Names and Attributes

set-frame-configuration

29.12 Frame Configurations

set-frame-height

29.3.4 Frame Size And Position

set-frame-position

29.3.4 Frame Size And Position

set-frame-size

29.3.4 Frame Size And Position

set-frame-width

29.3.4 Frame Size And Position

set-input-method

33.11 Input Methods

set-input-mode

40.8.1 Input Modes

set-keyboard-coding-system

33.10.8 Terminal I/O Encoding

set-keymap-parent

22.4 Inheritance and Keymaps

set-left-margin

32.12 Margins for Filling

set-mark

31.7 The Mark

set-marker

31.6 Moving Marker Positions

set-marker-insertion-type

31.5 Marker Insertion Types

set-match-data

34.6.3 Accessing the Entire Match Data

set-mouse-pixel-position

29.14 Mouse Position

set-mouse-position

29.14 Mouse Position

set-process-buffer

37.9.1 Process Buffers

set-process-coding-system

37.6 Process Information

set-process-filter

37.9.2 Process Filter Functions

set-process-sentinel

37.10 Sentinels: Detecting Process Status Changes

set-register

32.21 Registers

set-right-margin

32.12 Margins for Filling

set-screen-height

29.3.4 Frame Size And Position

set-screen-width

29.3.4 Frame Size And Position

set-standard-case-table

4.9 The Case Table

set-syntax-table

35.3 Syntax Table Functions

set-terminal-coding-system

33.10.8 Terminal I/O Encoding

set-text-properties

32.19.2 Changing Text Properties

set-visited-file-modtime

27.6 Comparison of Modification Time

set-visited-file-name

27.4 Buffer File Name

set-window-buffer

28.6 Buffers and Windows

set-window-configuration

28.17 Window Configurations

set-window-dedicated-p

28.8 Choosing a Window for Display

set-window-display-table

38.17.2 Active Display Table

set-window-hscroll

28.13 Horizontal Scrolling

set-window-margins

38.12.3 Displaying in the Margins

set-window-point

28.9 Windows and Point

set-window-redisplay-end-trigger

28.18 Hooks for Window Scrolling and Changes

set-window-start

28.10 The Window Start Position

set-window-vscroll

28.12 Vertical Fractional Scrolling

setcar

5.6.1 Altering List Elements with setcar

setcdr

5.6.2 Altering the CDR of a List

setenv

40.3 Operating System Environment

setplist

8.4.2 Property List Functions for Symbols

setprv

40.3 Operating System Environment

setq

11.8 How to Alter a Variable Value

setq-default

11.10.3 The Default Value of a Buffer-Local Variable

sets

5.7 Using Lists as Sets

setting modes of files

25.7 Changing File Names and Attributes

setting-constant

11.2 Variables that Never Change

sexp diary entries

39.9 Sexp Entries and the Fancy Diary Display

sexp motion

30.2.6 Moving over Balanced Expressions

shadowing of variables

11.3 Local Variables

shallow binding

11.9.3 Implementation of Dynamic Scoping

shared structure, read syntax

2.5 Read Syntax for Circular Objects

Shell mode mode-line-format

23.3.1 The Data Structure of the Mode Line

shell-command-history

20.4 Minibuffer History

shell-command-to-string

37.3 Creating a Synchronous Process

shell-quote-argument

37.2 Shell Arguments

show-help-function

32.19.4 Properties with Special Meanings

show-trailing-whitespace

38.11.1 Standard Faces

shrink-window

28.15 Changing the Size of a Window

shrink-window-horizontally

28.15 Changing the Size of a Window

shrink-window-if-larger-than-buffer

28.15 Changing the Size of a Window

side effect

9.1 Introduction to Evaluation

signal

10.5.3.1 How to Signal an Error

signal-process

37.8 Sending Signals to Processes

signaling errors

10.5.3.1 How to Signal an Error

signals

37.8 Sending Signals to Processes

simple-diary-display

39.8 Fancy Diary Display

sin

3.9 Standard Mathematical Functions

single-key-description

24.4 Describing Characters for Help Messages

sit-for

21.9 Waiting for Elapsed Time or Input

`site-init.el'

E.1 Building Emacs

`site-load.el'

E.1 Building Emacs

site-run-file

40.1.2 The Init File, `.emacs'

`site-start.el'

40.1.1 Summary: Sequence of Actions at Startup

size of frame

29.3.4 Frame Size And Position

size of window

28.14 The Size of a Window

skip-chars-backward

30.2.7 Skipping Characters

skip-chars-forward

30.2.7 Skipping Characters

skip-syntax-backward

35.5 Motion and Syntax

skip-syntax-forward

35.5 Motion and Syntax

skipping characters

30.2.7 Skipping Characters

skipping comments

35.6 Parsing Balanced Expressions

sleep-for

21.9 Waiting for Elapsed Time or Input

small-temporary-file-directory

25.8.5 Generating Unique File Names

Snarf-documentation

24.2 Access to Documentation Strings

sort

5.6.3 Functions that Rearrange Lists

sort-columns

32.15 Sorting Text

sort-diary-entries

39.8 Fancy Diary Display

sort-fields

32.15 Sorting Text

sort-fold-case

32.15 Sorting Text

sort-lines

32.15 Sorting Text

sort-numeric-fields

32.15 Sorting Text

sort-pages

32.15 Sorting Text

sort-paragraphs

32.15 Sorting Text

sort-regexp-fields

32.15 Sorting Text

sort-subr

32.15 Sorting Text

sorting diary entries

39.8 Fancy Diary Display

sorting lists

5.6.3 Functions that Rearrange Lists

sorting text

32.15 Sorting Text

sound

40.10 Sound Output

source breakpoints

18.2.6.2 Source Breakpoints

spaces, specified height or width

38.12.1 Specified Spaces

sparse keymap

22.2 Format of Keymaps

SPC in minibuffer

20.2 Reading Text Strings with the Minibuffer

special

23.1.1 Major Mode Conventions

special events

21.8 Special Events

special form descriptions

1.3.7.1 A Sample Function Description

special form evaluation

9.2.7 Special Forms

special forms

2.3.15 Primitive Function Type

special forms (Edebug)

18.2.2 Instrumenting for Edebug

special forms for control structures

10. Control Structures

special-display-buffer-names

28.8 Choosing a Window for Display

special-display-frame-alist

28.8 Choosing a Window for Display

special-display-function

28.8 Choosing a Window for Display

special-display-popup-frame

28.8 Choosing a Window for Display

special-display-regexps

28.8 Choosing a Window for Display

special-event-map

22.6 Active Keymaps

specified spaces

38.12.1 Specified Spaces

speedups

D.2 Tips for Making Compiled Code Fast

splicing (with backquote)

13.5 Backquote

split-char

33.7 Splitting Characters

split-height-threshold

28.8 Choosing a Window for Display

split-line

32.5 User-Level Insertion Commands

split-string

4.3 Creating Strings

split-window

28.2 Splitting Windows

split-window-horizontally

28.2 Splitting Windows

split-window-vertically

28.2 Splitting Windows

splitting windows

28.2 Splitting Windows

sqrt

3.9 Standard Mathematical Functions

stable sort

5.6.3 Functions that Rearrange Lists

standard regexps used in editing

34.8 Standard Regular Expressions Used in Editing

standard-case-table

4.9 The Case Table

standard-category-table

35.9 Categories

standard-display-table

38.17.2 Active Display Table

standard-input

19.3 Input Functions

standard-output

19.6 Variables Affecting Output

standard-syntax-table

35.7 Some Standard Syntax Tables

standard-translation-table-for-decode

33.9 Translation of Characters

standard-translation-table-for-encode

33.9 Translation of Characters

standards of coding style

D. Tips and Conventions

start-process

37.4 Creating an Asynchronous Process

start-process-shell-command

37.4 Creating an Asynchronous Process

startup of Emacs

40.1.1 Summary: Sequence of Actions at Startup

`startup.el'

40.1.1 Summary: Sequence of Actions at Startup

sticky text properties

32.19.6 Stickiness of Text Properties

stop points

18.2.1 Using Edebug

stop-process

37.8 Sending Signals to Processes

stopping an infinite loop

18.1.2 Debugging Infinite Loops

stopping on events

18.2.6.1 Global Break Condition

store-match-data

34.6.3 Accessing the Entire Match Data

store-substring

4.4 Modifying Strings

stream (for printing)

19.4 Output Streams

stream (for reading)

19.2 Input Streams

string

4.3 Creating Strings

string equality

4.5 Comparison of Characters and Strings

string in keymap

22.7 Key Lookup

string input stream

19.2 Input Streams

string length

6.1 Sequences

string quote

35.2.1 Table of Syntax Classes

string search

34.1 Searching for Strings

string to character

4.6 Conversion of Characters and Strings

string to number

4.6 Conversion of Characters and Strings

string to object

19.3 Input Functions

string, writing a doc string

24.1 Documentation Basics

string-as-multibyte

33.3 Selecting a Representation

string-as-unibyte

33.3 Selecting a Representation

string-chars-consed

E.4 Memory Usage

string-equal

4.5 Comparison of Characters and Strings

string-lessp

4.5 Comparison of Characters and Strings

string-make-multibyte

33.2 Converting Text Representations

string-make-unibyte

33.2 Converting Text Representations

string-match

34.3 Regular Expression Searching

string-to-char

4.6 Conversion of Characters and Strings

string-to-int

4.6 Conversion of Characters and Strings

string-to-number

4.6 Conversion of Characters and Strings

string-to-syntax

35.8 Syntax Table Internals

string-width

38.10 Width

string<

4.5 Comparison of Characters and Strings

string=

4.5 Comparison of Characters and Strings

stringp

4.2 The Predicates for Strings

strings

4. Strings and Characters

strings with keyboard events

21.6.14 Putting Keyboard Events in Strings

strings, formatting them

4.7 Formatting Strings

strings-consed

E.4 Memory Usage

subprocess

37. Processes

subr

12.1 What Is a Function?

subr-arity

12.1 What Is a Function?

subrp

12.1 What Is a Function?

subst-char-in-region

32.20 Substituting for a Character Code

substitute-command-keys

24.3 Substituting Key Bindings in Documentation

substitute-in-file-name

25.8.4 Functions that Expand Filenames

substitute-key-definition

22.9 Changing Key Bindings

substituting keys in documentation

24.3 Substituting Key Bindings in Documentation

substring

4.3 Creating Strings

subtype of char-table

6.6 Char-Tables

super characters

2.3.3 Character Type

suppress-keymap

22.9 Changing Key Bindings

suspend (cf. no-redraw-on-reenter)

38.1 Refreshing the Screen

suspend evaluation

21.12 Recursive Editing

suspend-emacs

40.2.2 Suspending Emacs

suspend-hook

40.2.2 Suspending Emacs

suspend-resume-hook

40.2.2 Suspending Emacs

suspending Emacs

40.2.2 Suspending Emacs

switch-to-buffer

28.7 Displaying Buffers in Windows

switch-to-buffer-other-window

28.7 Displaying Buffers in Windows

switches on command line

40.1.4 Command-Line Arguments

switching to a buffer

28.7 Displaying Buffers in Windows

sxhash

7.3 Defining Hash Comparisons

symbol

8. Symbols

symbol components

8.1 Symbol Components

symbol constituent

35.2.1 Table of Syntax Classes

symbol equality

8.3 Creating and Interning Symbols

symbol evaluation

9.2.2 Symbol Forms

symbol function indirection

9.2.4 Symbol Function Indirection

symbol in keymap

22.7 Key Lookup

symbol name hashing

8.3 Creating and Interning Symbols

symbol-file

15.7 Unloading

symbol-function

12.8 Accessing Function Cell Contents

symbol-name

8.3 Creating and Interning Symbols

symbol-plist

8.4.2 Property List Functions for Symbols

symbol-value

11.7 Accessing Variable Values

symbolp

8. Symbols

symbols-consed

E.4 Memory Usage

synchronous subprocess

37.3 Creating a Synchronous Process

syntax classes

35.2 Syntax Descriptors

syntax descriptor

35.2 Syntax Descriptors

syntax error (Edebug)

18.2.15.2 Backtracking in Specifications

syntax flags

35.2.2 Syntax Flags

syntax for characters

2.3.3 Character Type

syntax table

35. Syntax Tables

syntax table example

23.1.2 Major Mode Examples

syntax table internals

35.8 Syntax Table Internals

syntax tables in modes

23.1.1 Major Mode Conventions

syntax-table

35.3 Syntax Table Functions

syntax-table (text property)

35.4 Syntax Properties

syntax-table-p

35.1 Syntax Table Concepts

system-configuration

40.3 Operating System Environment

system-key-alist

40.11 System-Specific X11 Keysyms

system-messages-locale

33.12 Locales

system-name

40.3 Operating System Environment

system-time-locale

33.12 Locales

system-type

40.3 Operating System Environment

T

t

11.2 Variables that Never Change

t and truth

1.3.2 nil and t

t input stream

19.2 Input Streams

t output stream

19.4 Output Streams

tab

2.3.3 Character Type

tab deletion

32.6 Deleting Text

TAB in minibuffer

20.2 Reading Text Strings with the Minibuffer

tab-stop-list

32.17.5 Adjustable "Tab Stops"

tab-to-tab-stop

32.17.5 Adjustable "Tab Stops"

tab-width

38.16 Usual Display Conventions

tabs stops for indentation

32.17.5 Adjustable "Tab Stops"

tag on run time stack

10.5.1 Explicit Nonlocal Exits: catch and throw

tan

3.9 Standard Mathematical Functions

TCP

37.12 Network Connections

temacs

E.1 Building Emacs

TEMP environment variable

25.8.5 Generating Unique File Names

temp-buffer-setup-hook

38.8 Temporary Displays

temp-buffer-show-function

38.8 Temporary Displays

temp-buffer-show-hook

38.8 Temporary Displays

temporary-file-directory

25.8.5 Generating Unique File Names

TERM environment variable

40.1.3 Terminal-Specific Initialization

term-file-prefix

40.1.3 Terminal-Specific Initialization

term-setup-hook

40.1.3 Terminal-Specific Initialization

Termcap

40.1.3 Terminal-Specific Initialization

terminal frame

29. Frames

terminal input

40.8 Terminal Input

terminal input modes

40.8.1 Input Modes

terminal output

40.9 Terminal Output

terminal screen

28.1 Basic Concepts of Emacs Windows

terminal-coding-system

33.10.8 Terminal I/O Encoding

terminal-specific initialization

40.1.3 Terminal-Specific Initialization

terminate keyboard macro

21.7.5 Miscellaneous Event Input Features

termscript file

40.9 Terminal Output

terpri

19.5 Output Functions

testing types

2.6 Type Predicates

text

32. Text

text files and binary files

33.10.9 MS-DOS File Types

text insertion

32.4 Inserting Text

text parsing

35. Syntax Tables

text properties

32.19 Text Properties

text properties in files

32.19.7 Saving Text Properties in Files

text representations

33.1 Text Representations

text-char-description

24.4 Describing Characters for Help Messages

text-mode-abbrev-table

36.6 Standard Abbrev Tables

text-mode-map

H. Standard Keymaps

text-mode-syntax-table

35.7 Some Standard Syntax Tables

text-properties-at

32.19.1 Examining Text Properties

text-property-any

32.19.3 Text Property Search Functions

text-property-default-nonsticky

32.19.6 Stickiness of Text Properties

text-property-not-all

32.19.3 Text Property Search Functions

textual scrolling

28.11 Textual Scrolling

thing-at-point

32.2 Examining Buffer Contents

this-command

21.4 Information from the Command Loop

this-command-keys

21.4 Information from the Command Loop

this-command-keys-vector

21.4 Information from the Command Loop

three-step-help

24.5 Help Functions

throw

10.5.1 Explicit Nonlocal Exits: catch and throw

throw example

21.12 Recursive Editing

tiled windows

28.1 Basic Concepts of Emacs Windows

timer

40.7 Timers for Delayed Execution

timestamp of a mouse event

21.6.13 Accessing Events

timing programs

D.2 Tips for Making Compiled Code Fast

tips

D. Tips and Conventions

TMP environment variable

25.8.5 Generating Unique File Names

TMPDIR environment variable

25.8.5 Generating Unique File Names

today-invisible-calendar-hook

39.1 Customizing the Calendar

today-visible-calendar-hook

39.1 Customizing the Calendar

toggle-read-only

27.7 Read-Only Buffers

tool bar

22.12.6 Tool bars

tool-bar (face name)

38.11.1 Standard Faces

tool-bar-add-item

22.12.6 Tool bars

tool-bar-add-item-from-menu

22.12.6 Tool bars

tool-bar-item-margin

22.12.6 Tool bars

tool-bar-item-relief

22.12.6 Tool bars

tool-bar-map

22.12.6 Tool bars

top-level

21.12 Recursive Editing

top-level form

15. Loading

tq-close

37.11 Transaction Queues

tq-create

37.11 Transaction Queues

tq-enqueue

37.11 Transaction Queues

trace buffer

18.2.12 Trace Buffer

track-mouse

29.13 Mouse Tracking

tracking the mouse

29.13 Mouse Tracking

trailing codes

33.1 Text Representations

trailing-whitespace (face name)

38.11.1 Standard Faces

transaction queue

37.11 Transaction Queues

transcendental functions

3.9 Standard Mathematical Functions

Transient Mark mode

31.7 The Mark

transient-mark-mode

31.7 The Mark

translate-region

32.20 Substituting for a Character Code

translating input events

40.8.2 Translating Input Events

translation tables

33.9 Translation of Characters

transpose-regions

32.22 Transposition of Text

triple-click events

21.6.7 Repeat Events

true

1.3.2 nil and t

truename (of file)

25.6.3 Truenames

truncate

3.5 Numeric Conversions

truncate-lines

38.3 Truncation

truncate-partial-width-windows

38.3 Truncation

truncate-string-to-width

38.10 Width

truth value

1.3.2 nil and t

try-completion

20.5.1 Basic Completion Functions

tty-color-alist

29.20 Text Terminal Colors

tty-color-approximate

29.20 Text Terminal Colors

tty-color-clear

29.20 Text Terminal Colors

tty-color-define

29.20 Text Terminal Colors

tty-color-translate

29.20 Text Terminal Colors

tty-erase-char

40.3 Operating System Environment

two's complement

3.1 Integer Basics

type

2. Lisp Data Types

type checking

2.6 Type Predicates

type checking internals

E.6 Object Internals

type predicates

2.6 Type Predicates

type-of

2.6 Type Predicates

U

unbinding keys

22.10 Commands for Binding Keys

undefined

22.8 Functions for Key Lookup

undefined in keymap

22.7 Key Lookup

undefined key

22.1 Keymap Terminology

underline (face name)

38.11.1 Standard Faces

undo avoidance

32.20 Substituting for a Character Code

undo-boundary

32.9 Undo

undo-limit

32.10 Maintaining Undo Lists

undo-strong-limit

32.10 Maintaining Undo Lists

unexec

E.1 Building Emacs

unhandled-file-name-directory

25.11 Making Certain File Names "Magic"

unibyte text

33.1 Text Representations

unintern

8.3 Creating and Interning Symbols

uninterned symbol

8.3 Creating and Interning Symbols

universal-argument

21.11 Prefix Command Arguments

unless

10.2 Conditionals

unload-feature

15.7 Unloading

unloading

15.7 Unloading

unlock-buffer

25.5 File Locks

unread-command-char

21.7.5 Miscellaneous Event Input Features

unread-command-events

21.7.5 Miscellaneous Event Input Features

unwind-protect

10.5.4 Cleaning Up from Nonlocal Exits

unwinding

10.5.4 Cleaning Up from Nonlocal Exits

up-list

30.2.6 Moving over Balanced Expressions

upcase

4.8 Case Conversion in Lisp

upcase-initials

4.8 Case Conversion in Lisp

upcase-region

32.18 Case Changes

upcase-word

32.18 Case Changes

update-directory-autoloads

15.4 Autoload

update-file-autoloads

15.4 Autoload

upper case

4.8 Case Conversion in Lisp

upper case key sequence

21.7.1 Key Sequence Input

use-global-map

22.6 Active Keymaps

use-hard-newlines

32.11 Filling

use-local-map

22.6 Active Keymaps

user option

11.5 Defining Global Variables

user-defined error

10.5.3.4 Error Symbols and Condition Names

user-full-name

40.4 User Identification

user-init-file

40.1.2 The Init File, `.emacs'

user-login-name

40.4 User Identification

user-mail-address

40.4 User Identification

user-real-login-name

40.4 User Identification

user-real-uid

40.4 User Identification

user-uid

40.4 User Identification

user-variable-p

11.5 Defining Global Variables

user-variable-p example

20.5.4 High-Level Completion Functions

V

value cell

8.1 Symbol Components

value of expression

9. Evaluation

values

9.4 Eval

variable

11. Variables

variable definition

11.5 Defining Global Variables

variable descriptions

1.3.7.2 A Sample Variable Description

variable limit error

11.3 Local Variables

variable-documentation

24.1 Documentation Basics

variable-interactive

11.5 Defining Global Variables

variable-pitch (face name)

38.11.1 Standard Faces

variable-width spaces

38.12.1 Specified Spaces

variables, buffer-local

11.10 Buffer-Local Variables

variant coding system

33.10.1 Basic Concepts of Coding Systems

vc-mode

23.3.2 Variables Used in the Mode Line

vc-prefix-map

22.5 Prefix Keys

vconcat

6.5 Functions for Vectors

vector

6.5 Functions for Vectors

vector evaluation

9.2.1 Self-Evaluating Forms

vector length

6.1 Sequences

vector-cells-consed

E.4 Memory Usage

vectorp

6.5 Functions for Vectors

verify-visited-file-modtime

27.6 Comparison of Modification Time

version number (in file name)

25.8.1 File Name Components

version-control

26.1.3 Making and Deleting Numbered Backup Files

Vertical Fractional Scrolling

28.12 Vertical Fractional Scrolling

vertical tab

2.3.3 Character Type

vertical-line prefix key

21.7.1 Key Sequence Input

vertical-motion

30.2.5 Motion by Screen Lines

vertical-scroll-bar prefix key

21.7.1 Key Sequence Input

view-calendar-holidays-initially

39.1 Customizing the Calendar

view-diary-entries-initially

39.1 Customizing the Calendar

view-file

25.1.1 Functions for Visiting Files

view-mode-map

H. Standard Keymaps

view-register

32.21 Registers

visible frame

29.10 Visibility of Frames

visible-bell

38.18 Beeping

visible-frame-list

29.6 Finding All Frames

visited file

27.4 Buffer File Name

visited file mode

23.1.3 How Emacs Chooses a Major Mode

visited-file-modtime

27.6 Comparison of Modification Time

visiting files

25.1 Visiting Files

void function

9.2.4 Symbol Function Indirection

void function cell

12.8 Accessing Function Cell Contents

void variable

11.4 When a Variable is "Void"

void-function

12.8 Accessing Function Cell Contents

void-variable

11.4 When a Variable is "Void"

W

waiting

21.9 Waiting for Elapsed Time or Input

waiting for command key input

21.7.5 Miscellaneous Event Input Features

waiting-for-user-input-p

37.10 Sentinels: Detecting Process Status Changes

walk-windows

28.5 Cyclic Ordering of Windows

when

10.2 Conditionals

where-is-internal

22.11 Scanning Keymaps

while

10.4 Iteration

whitespace

2.3.3 Character Type

whitespace character

35.2.1 Table of Syntax Classes

wholenump

3.3 Type Predicates for Numbers

widen

30.4 Narrowing

widening

30.4 Narrowing

window

28.1 Basic Concepts of Emacs Windows

window (overlay property)

38.9.1 Overlay Properties

window configuration (Edebug)

18.2.14.2 Edebug Display Update

window configurations

28.17 Window Configurations

window excursions

30.3 Excursions

window frame

29. Frames

window header line

23.3.5 Window Header Lines

window internals

E.6.2 Window Internals

window ordering, cyclic

28.5 Cyclic Ordering of Windows

window point

28.9 Windows and Point

window point internals

E.6.2 Window Internals

window position

28.9 Windows and Point

window resizing

28.15 Changing the Size of a Window

window size

28.14 The Size of a Window

window size, changing

28.15 Changing the Size of a Window

window splitting

28.2 Splitting Windows

window that satisfies a predicate

28.4 Selecting Windows

window top line

28.10 The Window Start Position

window-at

28.16 Coordinates and Windows

window-buffer

28.6 Buffers and Windows

window-configuration-change-hook

28.18 Hooks for Window Scrolling and Changes

window-configuration-p

28.17 Window Configurations

window-dedicated-p

28.8 Choosing a Window for Display

window-display-table

38.17.2 Active Display Table

window-edges

28.14 The Size of a Window

window-end

28.10 The Window Start Position

window-frame

29.7 Frames and Windows

window-height

28.14 The Size of a Window

window-hscroll

28.13 Horizontal Scrolling

window-list

28.5 Cyclic Ordering of Windows

window-live-p

28.3 Deleting Windows

window-margins

38.12.3 Displaying in the Margins

window-min-height

28.15 Changing the Size of a Window

window-min-width

28.15 Changing the Size of a Window

window-minibuffer-p

20.9 Minibuffer Miscellany

window-point

28.9 Windows and Point

window-redisplay-end-trigger

28.18 Hooks for Window Scrolling and Changes

window-scroll-functions

28.18 Hooks for Window Scrolling and Changes

window-setup-hook

38.19 Window Systems

window-size-change-functions

28.18 Hooks for Window Scrolling and Changes

window-size-fixed

28.15 Changing the Size of a Window

window-start

28.10 The Window Start Position

window-system

38.19 Window Systems

window-vscroll

28.12 Vertical Fractional Scrolling

window-width

28.14 The Size of a Window

windowp

28.1 Basic Concepts of Emacs Windows

Windows file types

33.10.9 MS-DOS File Types

windows, controlling precisely

28.6 Buffers and Windows

with-current-buffer

27.2 The Current Buffer

with-output-to-string

19.5 Output Functions

with-output-to-temp-buffer

38.8 Temporary Displays

with-syntax-table

35.3 Syntax Table Functions

with-temp-buffer

27.2 The Current Buffer

with-temp-file

25.4 Writing to Files

with-temp-message

38.4 The Echo Area

with-timeout

40.7 Timers for Delayed Execution

word constituent

35.2.1 Table of Syntax Classes

word search

34.1 Searching for Strings

word-search-backward

34.1 Searching for Strings

word-search-forward

34.1 Searching for Strings

words-include-escapes

30.2.2 Motion by Words

write-abbrev-file

36.4 Saving Abbrevs in Files

write-char

19.5 Output Functions

write-contents-hooks

25.2 Saving Buffers

write-file

25.2 Saving Buffers

write-file-hooks

25.2 Saving Buffers

write-region

25.4 Writing to Files

write-region-annotate-functions

32.19.7 Saving Text Properties in Files

writing a documentation string

24.1 Documentation Basics

wrong-number-of-arguments

12.2.3 Other Features of Argument Lists

wrong-type-argument

2.6 Type Predicates

X

X Window System

38.19 Window Systems

x-bitmap-file-path

38.11.3 Face Attributes

x-close-connection

29.2 Multiple Displays

x-color-defined-p

29.19 Color Names

x-color-values

29.19 Color Names

x-defined-colors

29.19 Color Names

x-display-color-p

29.22 Display Feature Testing

x-display-list

29.2 Multiple Displays

x-family-fonts

38.11.9 Looking Up Fonts

x-font-family-list

38.11.9 Looking Up Fonts

x-get-cut-buffer

29.18 Window System Selections

x-get-resource

29.21 X Resources

x-get-selection

29.18 Window System Selections

x-list-fonts

38.11.9 Looking Up Fonts

x-open-connection

29.2 Multiple Displays

x-parse-geometry

29.3.4 Frame Size And Position

x-pointer-shape

29.17 Pointer Shapes

x-popup-dialog

29.16 Dialog Boxes

x-popup-menu

29.15 Pop-Up Menus

x-resource-class

29.21 X Resources

x-select-enable-clipboard

29.18 Window System Selections

x-sensitive-text-pointer-shape

29.17 Pointer Shapes

x-server-vendor

29.22 Display Feature Testing

x-server-version

29.22 Display Feature Testing

x-set-cut-buffer

29.18 Window System Selections

x-set-selection

29.18 Window System Selections

XBM

38.13.2 XBM Images

XPM

38.13.3 XPM Images

Y

y-or-n-p

20.6 Yes-or-No Queries

y-or-n-p-with-timeout

20.6 Yes-or-No Queries

yahrzeits

39.9 Sexp Entries and the Fancy Diary Display

yank

32.8.3 Functions for Yanking

yank suppression

22.9 Changing Key Bindings

yank-pop

32.8.3 Functions for Yanking

yes-or-no questions

20.6 Yes-or-No Queries

yes-or-no-p

20.6 Yes-or-No Queries

Z

zerop

3.3 Type Predicates for Numbers

Jump to:

" # $ % & ' ( ) * + , - . / 1 2 ; < = > ? @ [ \ ] ^ ` |
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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

New Symbols Since the Previous Edition

Jump to:

A B C D E F G H I K L M N P R S T U W X

Index Entry

Section

A

after-make-frame-functions

29.1 Creating Frames

assq-delete-all

5.8 Association Lists

auto-raise-tool-bar-items

22.12.6 Tool bars

auto-resize-tool-bar

22.12.6 Tool bars

auto-save-list-file-prefix

26.2 Auto-Saving

B

backup-directory-alist

26.1.1 Making Backup Files

base64-decode-region

32.23 Base 64 Encoding

base64-decode-string

32.23 Base 64 Encoding

base64-encode-region

32.23 Base 64 Encoding

base64-encode-string

32.23 Base 64 Encoding

beginning-of-defun-function

30.2.6 Moving over Balanced Expressions

buffer-has-markers-at

31.4 Information from Markers

byte-to-position

33.1 Text Representations

C

charset-bytes

33.6 Characters and Bytes

charset-plist

33.5 Character Sets

clear-face-cache

38.11.6 Font Selection

clear-image-cache

38.13.9 Image Cache

clear-this-command-keys

21.4 Information from the Command Loop

clrhash

7.2 Hash Table Access

color-defined-p

29.19 Color Names

color-gray-p

29.19 Color Names

color-supported-p

29.19 Color Names

color-values

29.19 Color Names

constrain-to-field

32.19.10 Defining and Using Fields

copy-hash-table

7.4 Other Hash Table Functions

create-glyph

38.17.3 Glyphs

create-image

38.13.7 Defining Images

D

default-header-line-format

23.3.5 Window Header Lines

defimage

38.13.7 Defining Images

define-hash-table-test

7.3 Defining Hash Comparisons

define-minor-mode

23.2.3 Defining Minor Modes

defined-colors

29.19 Color Names

delete-and-extract-region

32.6 Deleting Text

delete-field

32.19.10 Defining and Using Fields

delete-minibuffer-contents

20.9 Minibuffer Miscellany

describe-current-display-table

38.17.1 Display Table Format

describe-display-table

38.17.1 Display Table Format

disable-point-adjustment

21.5 Adjusting Point After Commands

display-backing-store

29.22 Display Feature Testing

display-color-cells

29.22 Display Feature Testing

display-color-p

29.22 Display Feature Testing

display-graphic-p

29.22 Display Feature Testing

display-grayscale-p

29.22 Display Feature Testing

display-message-or-buffer

38.4 The Echo Area

display-mm-height

29.22 Display Feature Testing

display-mm-width

29.22 Display Feature Testing

display-mouse-p

29.22 Display Feature Testing

display-pixel-height

29.22 Display Feature Testing

display-pixel-width

29.22 Display Feature Testing

display-planes

29.22 Display Feature Testing

display-popup-menus-p

29.22 Display Feature Testing

display-save-under

29.22 Display Feature Testing

display-screens

29.22 Display Feature Testing

display-selections-p

29.22 Display Feature Testing

display-visual-class

29.22 Display Feature Testing

dolist

10.4 Iteration

dotimes

10.4 Iteration

E

emacs-startup-hook

40.1.2 The Init File, `.emacs'

end-of-defun-function

30.2.6 Moving over Balanced Expressions

F

face-attribute

38.11.4 Face Attribute Functions

face-font-family-alternatives

38.11.6 Font Selection

face-font-registry-alternatives

38.11.6 Font Selection

face-font-selection-order

38.11.6 Font Selection

field-beginning

32.19.10 Defining and Using Fields

field-end

32.19.10 Defining and Using Fields

field-string

32.19.10 Defining and Using Fields

field-string-no-properties

32.19.10 Defining and Using Fields

file-expand-wildcards

25.9 Contents of Directories

find-file-wildcards

25.1.1 Functions for Visiting Files

find-image

38.13.7 Defining Images

font-list-limit

38.11.9 Looking Up Fonts

fontification-functions

38.11.8 Automatic Face Assignment

frame-parameter

29.3.1 Access to Frame Parameters

G

gethash

7.2 Hash Table Access

global-disable-point-adjustment

21.5 Adjusting Point After Commands

H

hash-table-count

7.4 Other Hash Table Functions

hash-table-p

7.4 Other Hash Table Functions

hash-table-rehash-size

7.4 Other Hash Table Functions

hash-table-rehash-threshold

7.4 Other Hash Table Functions

hash-table-size

7.4 Other Hash Table Functions

hash-table-test

7.4 Other Hash Table Functions

hash-table-weakness

7.4 Other Hash Table Functions

header-line-format

23.3.5 Window Header Lines

I

image-cache-eviction-delay

38.13.9 Image Cache

image-mask-p

38.13.1 Image Descriptors

image-size

38.13.8 Showing Images

indicate-empty-lines

38.16 Usual Display Conventions

inhibit-field-text-motion

30.2.2 Motion by Words

inhibit-modification-hooks

32.25 Change Hooks

K

keywordp

11.2 Variables that Never Change

L

left-margin-width

38.12.3 Displaying in the Margins

line-beginning-position

30.2.4 Motion by Text Lines

line-end-position

30.2.4 Motion by Text Lines

locale-coding-system

33.12 Locales

M

make-backup-file-name-function

26.1.1 Making Backup Files

make-category-table

35.9 Categories

make-hash-table

7.1 Creating Hash Tables

make-temp-file

25.8.5 Generating Unique File Names

makehash

7.1 Creating Hash Tables

mapc

12.6 Mapping Functions

maphash

7.2 Hash Table Access

minibuffer-contents

20.9 Minibuffer Miscellany

minibuffer-contents-no-properties

20.9 Minibuffer Miscellany

minibuffer-prompt-end

20.9 Minibuffer Miscellany

multibyte-syntax-as-symbol

35.6 Parsing Balanced Expressions

N

next-single-char-property-change

32.19.3 Text Property Search Functions

P

parse-colon-path

40.3 Operating System Environment

play-sound

40.10 Sound Output

play-sound-file

40.10 Sound Output

play-sound-functions

40.10 Sound Output

plist-member

8.4.3 Property Lists Outside Symbols

pop

5.4 Accessing Elements of Lists

position-bytes

33.1 Text Representations

previous-single-char-property-change

32.19.3 Text Property Search Functions

print-circle

19.6 Variables Affecting Output

print-gensym

19.6 Variables Affecting Output

process-running-child-p process

37.7 Sending Input to Processes

propertize

32.19.2 Changing Text Properties

push

5.5 Building Cons Cells and Lists

puthash

7.2 Hash Table Access

R

redisplay-dont-pause

38.2 Forcing Redisplay

remhash

7.2 Hash Table Access

right-margin-width

38.12.3 Displaying in the Margins

S

scalable-fonts-allowed

38.11.6 Font Selection

scroll-down-aggressively

28.11 Textual Scrolling

scroll-up-aggressively

28.11 Textual Scrolling

set-face-attribute

38.11.4 Face Attribute Functions

set-window-margins

38.12.3 Displaying in the Margins

show-help-function

32.19.4 Properties with Special Meanings

show-trailing-whitespace

38.11.1 Standard Faces

small-temporary-file-directory

25.8.5 Generating Unique File Names

subr-arity

12.1 What Is a Function?

sxhash

7.3 Defining Hash Comparisons

system-messages-locale

33.12 Locales

system-time-locale

33.12 Locales

T

temp-buffer-setup-hook

38.8 Temporary Displays

text-property-default-nonsticky

32.19.6 Stickiness of Text Properties

tool-bar-add-item

22.12.6 Tool bars

tool-bar-add-item-from-menu

22.12.6 Tool bars

tool-bar-item-margin

22.12.6 Tool bars

tool-bar-item-relief

22.12.6 Tool bars

tool-bar-map

22.12.6 Tool bars

tty-color-alist

29.20 Text Terminal Colors

tty-color-approximate

29.20 Text Terminal Colors

tty-color-clear

29.20 Text Terminal Colors

tty-color-define

29.20 Text Terminal Colors

tty-color-translate

29.20 Text Terminal Colors

U

user-init-file

40.1.2 The Init File, `.emacs'

W

window-margins

38.12.3 Displaying in the Margins

window-size-fixed

28.15 Changing the Size of a Window

with-syntax-table

35.3 Syntax Table Functions

with-temp-message

38.4 The Echo Area

X

x-family-fonts

38.11.9 Looking Up Fonts

x-font-family-list

38.11.9 Looking Up Fonts

Jump to:

A B C D E F G H I K L M N P R S T U W X

[Top]

[Contents]

[Index]

[ ? ]

Footnotes

(1)

There is no strictly equivalent way to add an element to the end of a list. You can use (append listname (list newelt)), which creates a whole new list by copying listname and adding newelt to its end. Or you can use (nconc listname (list newelt)), which modifies listname by following all the CDRs and then replacing the terminating nil. Compare this to adding an element to the beginning of a list with cons, which neither copies nor modifies the list.
(2)

This usage of "key" is not related to the term "key sequence"; it means a value used to look up an item in a table. In this case, the table is the alist, and the alist associations are the items.
(3)

This definition of "environment" is specifically not intended to include all the data that can affect the result of a program.
(4)

They may also be declared equivalently in `cus-start.el'.
(5)

Button-down is the conservative antithesis of drag.
(6)

It is required for menus which do not use a toolkit, e.g. under MS-DOS.
(7)

An RFC, an acronym for Request for Comments, is a numbered Internet informational document describing a standard. RFCs are usually written by technical experts acting on their own initiative, and are traditionally written in a pragmatic, experience-driven manner.
(8)

For an explanation of what is an RFC, see the footnote in 32.23 Base 64 Encoding.
(9)

On other systems, Emacs uses a Lisp emulation of ls; see 25.9 Contents of Directories.
(10)

The benefits of a Common Lisp-style package system are considered not to outweigh the costs.
(11)

Consider that the package may be loaded arbitrarily by Custom for instance.

[Top]

[Contents]

[Index]

[ ? ]

Table of Contents

1. Introduction

1.1 Caveats
1.2 Lisp History
1.3 Conventions

1.3.1 Some Terms
1.3.2 nil and t
1.3.3 Evaluation Notation
1.3.4 Printing Notation
1.3.5 Error Messages
1.3.6 Buffer Text Notation
1.3.7 Format of Descriptions

1.3.7.1 A Sample Function Description
1.3.7.2 A Sample Variable Description

1.4 Version Information
1.5 Acknowledgements

2. Lisp Data Types

2.1 Printed Representation and Read Syntax
2.2 Comments
2.3 Programming Types

2.3.1 Integer Type
2.3.2 Floating Point Type
2.3.3 Character Type
2.3.4 Symbol Type
2.3.5 Sequence Types
2.3.6 Cons Cell and List Types

2.3.6.1 Dotted Pair Notation
2.3.6.2 Association List Type

2.3.7 Array Type
2.3.8 String Type

2.3.8.1 Syntax for Strings
2.3.8.2 Non-ASCII Characters in Strings
2.3.8.3 Nonprinting Characters in Strings
2.3.8.4 Text Properties in Strings

2.3.9 Vector Type
2.3.10 Char-Table Type
2.3.11 Bool-Vector Type
2.3.12 Hash Table Type
2.3.13 Function Type
2.3.14 Macro Type
2.3.15 Primitive Function Type
2.3.16 Byte-Code Function Type
2.3.17 Autoload Type

2.4 Editing Types

2.4.1 Buffer Type
2.4.2 Marker Type
2.4.3 Window Type
2.4.4 Frame Type
2.4.5 Window Configuration Type
2.4.6 Frame Configuration Type
2.4.7 Process Type
2.4.8 Stream Type
2.4.9 Keymap Type
2.4.10 Overlay Type

2.5 Read Syntax for Circular Objects
2.6 Type Predicates
2.7 Equality Predicates

3. Numbers

3.1 Integer Basics
3.2 Floating Point Basics
3.3 Type Predicates for Numbers
3.4 Comparison of Numbers
3.5 Numeric Conversions
3.6 Arithmetic Operations
3.7 Rounding Operations
3.8 Bitwise Operations on Integers
3.9 Standard Mathematical Functions
3.10 Random Numbers

4. Strings and Characters

4.1 String and Character Basics
4.2 The Predicates for Strings
4.3 Creating Strings
4.4 Modifying Strings
4.5 Comparison of Characters and Strings
4.6 Conversion of Characters and Strings
4.7 Formatting Strings
4.8 Case Conversion in Lisp
4.9 The Case Table

5. Lists

5.1 Lists and Cons Cells
5.2 Lists as Linked Pairs of Boxes
5.3 Predicates on Lists
5.4 Accessing Elements of Lists
5.5 Building Cons Cells and Lists
5.6 Modifying Existing List Structure

5.6.1 Altering List Elements with setcar
5.6.2 Altering the CDR of a List
5.6.3 Functions that Rearrange Lists

5.7 Using Lists as Sets
5.8 Association Lists

6. Sequences, Arrays, and Vectors

6.1 Sequences
6.2 Arrays
6.3 Functions that Operate on Arrays
6.4 Vectors
6.5 Functions for Vectors
6.6 Char-Tables
6.7 Bool-vectors

7. Hash Tables

7.1 Creating Hash Tables
7.2 Hash Table Access
7.3 Defining Hash Comparisons
7.4 Other Hash Table Functions

8. Symbols

8.1 Symbol Components
8.2 Defining Symbols
8.3 Creating and Interning Symbols
8.4 Property Lists

8.4.1 Property Lists and Association Lists
8.4.2 Property List Functions for Symbols
8.4.3 Property Lists Outside Symbols

9. Evaluation

9.1 Introduction to Evaluation
9.2 Kinds of Forms

9.2.1 Self-Evaluating Forms
9.2.2 Symbol Forms
9.2.3 Classification of List Forms
9.2.4 Symbol Function Indirection
9.2.5 Evaluation of Function Forms
9.2.6 Lisp Macro Evaluation
9.2.7 Special Forms
9.2.8 Autoloading

9.3 Quoting
9.4 Eval

10. Control Structures

10.1 Sequencing
10.2 Conditionals
10.3 Constructs for Combining Conditions
10.4 Iteration
10.5 Nonlocal Exits

10.5.1 Explicit Nonlocal Exits: catch and throw
10.5.2 Examples of catch and throw
10.5.3 Errors

10.5.3.1 How to Signal an Error
10.5.3.2 How Emacs Processes Errors
10.5.3.3 Writing Code to Handle Errors
10.5.3.4 Error Symbols and Condition Names

10.5.4 Cleaning Up from Nonlocal Exits

11. Variables

11.1 Global Variables
11.2 Variables that Never Change
11.3 Local Variables
11.4 When a Variable is "Void"
11.5 Defining Global Variables
11.6 Tips for Defining Variables Robustly
11.7 Accessing Variable Values
11.8 How to Alter a Variable Value
11.9 Scoping Rules for Variable Bindings

11.9.1 Scope
11.9.2 Extent
11.9.3 Implementation of Dynamic Scoping
11.9.4 Proper Use of Dynamic Scoping

11.10 Buffer-Local Variables

11.10.1 Introduction to Buffer-Local Variables
11.10.2 Creating and Deleting Buffer-Local Bindings
11.10.3 The Default Value of a Buffer-Local Variable

11.11 Frame-Local Variables
11.12 Possible Future Local Variables
11.13 File Local Variables

12. Functions

12.1 What Is a Function?
12.2 Lambda Expressions

12.2.1 Components of a Lambda Expression
12.2.2 A Simple Lambda-Expression Example
12.2.3 Other Features of Argument Lists
12.2.4 Documentation Strings of Functions

12.3 Naming a Function
12.4 Defining Functions
12.5 Calling Functions
12.6 Mapping Functions
12.7 Anonymous Functions
12.8 Accessing Function Cell Contents
12.9 Inline Functions
12.10 Other Topics Related to Functions

13. Macros

13.1 A Simple Example of a Macro
13.2 Expansion of a Macro Call
13.3 Macros and Byte Compilation
13.4 Defining Macros
13.5 Backquote
13.6 Common Problems Using Macros

13.6.1 Wrong Time
13.6.2 Evaluating Macro Arguments Repeatedly
13.6.3 Local Variables in Macro Expansions
13.6.4 Evaluating Macro Arguments in Expansion
13.6.5 How Many Times is the Macro Expanded?

14. Writing Customization Definitions

14.1 Common Item Keywords
14.2 Defining Custom Groups
14.3 Defining Customization Variables
14.4 Customization Types

14.4.1 Simple Types
14.4.2 Composite Types
14.4.3 Splicing into Lists
14.4.4 Type Keywords

15. Loading

15.1 How Programs Do Loading
15.2 Library Search
15.3 Loading Non-ASCII Characters
15.4 Autoload
15.5 Repeated Loading
15.6 Features
15.7 Unloading
15.8 Hooks for Loading

16. Byte Compilation

16.1 Performance of Byte-Compiled Code
16.2 The Compilation Functions
16.3 Documentation Strings and Compilation
16.4 Dynamic Loading of Individual Functions
16.5 Evaluation During Compilation
16.6 Byte-Code Function Objects
16.7 Disassembled Byte-Code

17. Advising Emacs Lisp Functions

17.1 A Simple Advice Example
17.2 Defining Advice
17.3 Around-Advice
17.4 Computed Advice
17.5 Activation of Advice
17.6 Enabling and Disabling Advice
17.7 Preactivation
17.8 Argument Access in Advice
17.9 Definition of Subr Argument Lists
17.10 The Combined Definition

18. Debugging Lisp Programs

18.1 The Lisp Debugger

18.1.1 Entering the Debugger on an Error
18.1.2 Debugging Infinite Loops
18.1.3 Entering the Debugger on a Function Call
18.1.4 Explicit Entry to the Debugger
18.1.5 Using the Debugger
18.1.6 Debugger Commands
18.1.7 Invoking the Debugger
18.1.8 Internals of the Debugger

18.2 Edebug

18.2.1 Using Edebug
18.2.2 Instrumenting for Edebug
18.2.3 Edebug Execution Modes
18.2.4 Jumping
18.2.5 Miscellaneous Edebug Commands
18.2.6 Breakpoints

18.2.6.1 Global Break Condition
18.2.6.2 Source Breakpoints

18.2.7 Trapping Errors
18.2.8 Edebug Views
18.2.9 Evaluation
18.2.10 Evaluation List Buffer
18.2.11 Printing in Edebug
18.2.12 Trace Buffer
18.2.13 Coverage Testing
18.2.14 The Outside Context

18.2.14.1 Checking Whether to Stop
18.2.14.2 Edebug Display Update
18.2.14.3 Edebug Recursive Edit

18.2.15 Instrumenting Macro Calls

18.2.15.1 Specification List
18.2.15.2 Backtracking in Specifications
18.2.15.3 Specification Examples

18.2.16 Edebug Options

18.3 Debugging Invalid Lisp Syntax

18.3.1 Excess Open Parentheses
18.3.2 Excess Close Parentheses

18.4 Debugging Problems in Compilation

19. Reading and Printing Lisp Objects

19.1 Introduction to Reading and Printing
19.2 Input Streams
19.3 Input Functions
19.4 Output Streams
19.5 Output Functions
19.6 Variables Affecting Output

20. Minibuffers

20.1 Introduction to Minibuffers
20.2 Reading Text Strings with the Minibuffer
20.3 Reading Lisp Objects with the Minibuffer
20.4 Minibuffer History
20.5 Completion

20.5.1 Basic Completion Functions
20.5.2 Completion and the Minibuffer
20.5.3 Minibuffer Commands that Do Completion
20.5.4 High-Level Completion Functions
20.5.5 Reading File Names
20.5.6 Programmed Completion

20.6 Yes-or-No Queries
20.7 Asking Multiple Y-or-N Questions
20.8 Reading a Password
20.9 Minibuffer Miscellany

21. Command Loop

21.1 Command Loop Overview
21.2 Defining Commands

21.2.1 Using interactive
21.2.2 Code Characters for interactive
21.2.3 Examples of Using interactive

21.3 Interactive Call
21.4 Information from the Command Loop
21.5 Adjusting Point After Commands
21.6 Input Events

21.6.1 Keyboard Events
21.6.2 Function Keys
21.6.3 Mouse Events
21.6.4 Click Events
21.6.5 Drag Events
21.6.6 Button-Down Events
21.6.7 Repeat Events
21.6.8 Motion Events
21.6.9 Focus Events
21.6.10 Miscellaneous Window System Events
21.6.11 Event Examples
21.6.12 Classifying Events
21.6.13 Accessing Events
21.6.14 Putting Keyboard Events in Strings

21.7 Reading Input

21.7.1 Key Sequence Input
21.7.2 Reading One Event
21.7.3 Invoking the Input Method
21.7.4 Quoted Character Input
21.7.5 Miscellaneous Event Input Features

21.8 Special Events
21.9 Waiting for Elapsed Time or Input
21.10 Quitting
21.11 Prefix Command Arguments
21.12 Recursive Editing
21.13 Disabling Commands
21.14 Command History
21.15 Keyboard Macros

22. Keymaps

22.1 Keymap Terminology
22.2 Format of Keymaps
22.3 Creating Keymaps
22.4 Inheritance and Keymaps
22.5 Prefix Keys
22.6 Active Keymaps
22.7 Key Lookup
22.8 Functions for Key Lookup
22.9 Changing Key Bindings
22.10 Commands for Binding Keys
22.11 Scanning Keymaps
22.12 Menu Keymaps

22.12.1 Defining Menus

22.12.1.1 Simple Menu Items
22.12.1.2 Extended Menu Items
22.12.1.3 Menu Separators
22.12.1.4 Alias Menu Items

22.12.2 Menus and the Mouse
22.12.3 Menus and the Keyboard
22.12.4 Menu Example
22.12.5 The Menu Bar
22.12.6 Tool bars
22.12.7 Modifying Menus

23. Major and Minor Modes

23.1 Major Modes

23.1.1 Major Mode Conventions
23.1.2 Major Mode Examples
23.1.3 How Emacs Chooses a Major Mode
23.1.4 Getting Help about a Major Mode
23.1.5 Defining Derived Modes

23.2 Minor Modes

23.2.1 Conventions for Writing Minor Modes
23.2.2 Keymaps and Minor Modes
23.2.3 Defining Minor Modes

23.3 Mode Line Format

23.3.1 The Data Structure of the Mode Line
23.3.2 Variables Used in the Mode Line
23.3.3 %-Constructs in the Mode Line
23.3.4 Properties in the Mode Line
23.3.5 Window Header Lines

23.4 Imenu
23.5 Font Lock Mode

23.5.1 Font Lock Basics
23.5.2 Search-based Fontification
23.5.3 Other Font Lock Variables
23.5.4 Levels of Font Lock
23.5.5 Faces for Font Lock
23.5.6 Syntactic Font Lock

23.6 Hooks

24. Documentation

24.1 Documentation Basics
24.2 Access to Documentation Strings
24.3 Substituting Key Bindings in Documentation
24.4 Describing Characters for Help Messages
24.5 Help Functions

25. Files

25.1 Visiting Files

25.1.1 Functions for Visiting Files
25.1.2 Subroutines of Visiting

25.2 Saving Buffers
25.3 Reading from Files
25.4 Writing to Files
25.5 File Locks
25.6 Information about Files

25.6.1 Testing Accessibility
25.6.2 Distinguishing Kinds of Files
25.6.3 Truenames
25.6.4 Other Information about Files

25.7 Changing File Names and Attributes
25.8 File Names

25.8.1 File Name Components
25.8.2 Directory Names
25.8.3 Absolute and Relative File Names
25.8.4 Functions that Expand Filenames
25.8.5 Generating Unique File Names
25.8.6 File Name Completion
25.8.7 Standard File Names

25.9 Contents of Directories
25.10 Creating and Deleting Directories
25.11 Making Certain File Names "Magic"
25.12 File Format Conversion

26. Backups and Auto-Saving

26.1 Backup Files

26.1.1 Making Backup Files
26.1.2 Backup by Renaming or by Copying?
26.1.3 Making and Deleting Numbered Backup Files
26.1.4 Naming Backup Files

26.2 Auto-Saving
26.3 Reverting

27. Buffers

27.1 Buffer Basics
27.2 The Current Buffer
27.3 Buffer Names
27.4 Buffer File Name
27.5 Buffer Modification
27.6 Comparison of Modification Time
27.7 Read-Only Buffers
27.8 The Buffer List
27.9 Creating Buffers
27.10 Killing Buffers
27.11 Indirect Buffers
27.12 The Buffer Gap

28. Windows

28.1 Basic Concepts of Emacs Windows
28.2 Splitting Windows
28.3 Deleting Windows
28.4 Selecting Windows
28.5 Cyclic Ordering of Windows
28.6 Buffers and Windows
28.7 Displaying Buffers in Windows
28.8 Choosing a Window for Display
28.9 Windows and Point
28.10 The Window Start Position
28.11 Textual Scrolling
28.12 Vertical Fractional Scrolling
28.13 Horizontal Scrolling
28.14 The Size of a Window
28.15 Changing the Size of a Window
28.16 Coordinates and Windows
28.17 Window Configurations
28.18 Hooks for Window Scrolling and Changes

29. Frames

29.1 Creating Frames
29.2 Multiple Displays
29.3 Frame Parameters

29.3.1 Access to Frame Parameters
29.3.2 Initial Frame Parameters
29.3.3 Window Frame Parameters
29.3.4 Frame Size And Position

29.4 Frame Titles
29.5 Deleting Frames
29.6 Finding All Frames
29.7 Frames and Windows
29.8 Minibuffers and Frames
29.9 Input Focus
29.10 Visibility of Frames
29.11 Raising and Lowering Frames
29.12 Frame Configurations
29.13 Mouse Tracking
29.14 Mouse Position
29.15 Pop-Up Menus
29.16 Dialog Boxes
29.17 Pointer Shapes
29.18 Window System Selections
29.19 Color Names
29.20 Text Terminal Colors
29.21 X Resources
29.22 Display Feature Testing

30. Positions

30.1 Point
30.2 Motion

30.2.1 Motion by Characters
30.2.2 Motion by Words
30.2.3 Motion to an End of the Buffer
30.2.4 Motion by Text Lines
30.2.5 Motion by Screen Lines
30.2.6 Moving over Balanced Expressions
30.2.7 Skipping Characters

30.3 Excursions
30.4 Narrowing

31. Markers

31.1 Overview of Markers
31.2 Predicates on Markers
31.3 Functions that Create Markers
31.4 Information from Markers
31.5 Marker Insertion Types
31.6 Moving Marker Positions
31.7 The Mark
31.8 The Region

32. Text

32.1 Examining Text Near Point
32.2 Examining Buffer Contents
32.3 Comparing Text
32.4 Inserting Text
32.5 User-Level Insertion Commands
32.6 Deleting Text
32.7 User-Level Deletion Commands
32.8 The Kill Ring

32.8.1 Kill Ring Concepts
32.8.2 Functions for Killing
32.8.3 Functions for Yanking
32.8.4 Low-Level Kill Ring
32.8.5 Internals of the Kill Ring

32.9 Undo
32.10 Maintaining Undo Lists
32.11 Filling
32.12 Margins for Filling
32.13 Adaptive Fill Mode
32.14 Auto Filling
32.15 Sorting Text
32.16 Counting Columns
32.17 Indentation

32.17.1 Indentation Primitives
32.17.2 Indentation Controlled by Major Mode
32.17.3 Indenting an Entire Region
32.17.4 Indentation Relative to Previous Lines
32.17.5 Adjustable "Tab Stops"
32.17.6 Indentation-Based Motion Commands

32.18 Case Changes
32.19 Text Properties

32.19.1 Examining Text Properties
32.19.2 Changing Text Properties
32.19.3 Text Property Search Functions
32.19.4 Properties with Special Meanings
32.19.5 Formatted Text Properties
32.19.6 Stickiness of Text Properties
32.19.7 Saving Text Properties in Files
32.19.8 Lazy Computation of Text Properties
32.19.9 Defining Clickable Text
32.19.10 Defining and Using Fields
32.19.11 Why Text Properties are not Intervals

32.20 Substituting for a Character Code
32.21 Registers
32.22 Transposition of Text
32.23 Base 64 Encoding
32.24 MD5 Checksum
32.25 Change Hooks

33. Non-ASCII Characters

33.1 Text Representations
33.2 Converting Text Representations
33.3 Selecting a Representation
33.4 Character Codes
33.5 Character Sets
33.6 Characters and Bytes
33.7 Splitting Characters
33.8 Scanning for Character Sets
33.9 Translation of Characters
33.10 Coding Systems

33.10.1 Basic Concepts of Coding Systems
33.10.2 Encoding and I/O
33.10.3 Coding Systems in Lisp
33.10.4 User-Chosen Coding Systems
33.10.5 Default Coding Systems
33.10.6 Specifying a Coding System for One Operation
33.10.7 Explicit Encoding and Decoding
33.10.8 Terminal I/O Encoding
33.10.9 MS-DOS File Types

33.11 Input Methods
33.12 Locales

34. Searching and Matching

34.1 Searching for Strings
34.2 Regular Expressions

34.2.1 Syntax of Regular Expressions

34.2.1.1 Special Characters in Regular Expressions
34.2.1.2 Character Classes
34.2.1.3 Backslash Constructs in Regular Expressions

34.2.2 Complex Regexp Example
34.2.3 Regular Expression Functions

34.3 Regular Expression Searching
34.4 POSIX Regular Expression Searching
34.5 Search and Replace
34.6 The Match Data

34.6.1 Replacing the Text that Matched
34.6.2 Simple Match Data Access
34.6.3 Accessing the Entire Match Data
34.6.4 Saving and Restoring the Match Data

34.7 Searching and Case
34.8 Standard Regular Expressions Used in Editing

35. Syntax Tables

35.1 Syntax Table Concepts
35.2 Syntax Descriptors

35.2.1 Table of Syntax Classes
35.2.2 Syntax Flags

35.3 Syntax Table Functions
35.4 Syntax Properties
35.5 Motion and Syntax
35.6 Parsing Balanced Expressions
35.7 Some Standard Syntax Tables
35.8 Syntax Table Internals
35.9 Categories

36. Abbrevs and Abbrev Expansion

36.1 Setting Up Abbrev Mode
36.2 Abbrev Tables
36.3 Defining Abbrevs
36.4 Saving Abbrevs in Files
36.5 Looking Up and Expanding Abbreviations
36.6 Standard Abbrev Tables

37. Processes

37.1 Functions that Create Subprocesses
37.2 Shell Arguments
37.3 Creating a Synchronous Process
37.4 Creating an Asynchronous Process
37.5 Deleting Processes
37.6 Process Information
37.7 Sending Input to Processes
37.8 Sending Signals to Processes
37.9 Receiving Output from Processes

37.9.1 Process Buffers
37.9.2 Process Filter Functions
37.9.3 Accepting Output from Processes

37.10 Sentinels: Detecting Process Status Changes
37.11 Transaction Queues
37.12 Network Connections

38. Emacs Display

38.1 Refreshing the Screen
38.2 Forcing Redisplay
38.3 Truncation
38.4 The Echo Area
38.5 Invisible Text
38.6 Selective Display
38.7 The Overlay Arrow
38.8 Temporary Displays
38.9 Overlays

38.9.1 Overlay Properties
38.9.2 Managing Overlays
38.9.3 Searching for Overlays

38.10 Width
38.11 Faces

38.11.1 Standard Faces
38.11.2 Defining Faces
38.11.3 Face Attributes
38.11.4 Face Attribute Functions
38.11.5 Merging Faces for Display
38.11.6 Font Selection
38.11.7 Functions for Working with Faces
38.11.8 Automatic Face Assignment
38.11.9 Looking Up Fonts
38.11.10 Fontsets

38.12 The display Property

38.12.1 Specified Spaces
38.12.2 Other Display Specifications
38.12.3 Displaying in the Margins
38.12.4 Conditional Display Specifications

38.13 Images

38.13.1 Image Descriptors
38.13.2 XBM Images
38.13.3 XPM Images
38.13.4 GIF Images
38.13.5 Postscript Images
38.13.6 Other Image Types
38.13.7 Defining Images
38.13.8 Showing Images
38.13.9 Image Cache

38.14 Blinking Parentheses
38.15 Inverse Video
38.16 Usual Display Conventions
38.17 Display Tables

38.17.1 Display Table Format
38.17.2 Active Display Table
38.17.3 Glyphs

38.18 Beeping
38.19 Window Systems

39. Customizing the Calendar and Diary

39.1 Customizing the Calendar
39.2 Customizing the Holidays
39.3 Date Display Format
39.4 Time Display Format
39.5 Daylight Savings Time
39.6 Customizing the Diary
39.7 Hebrew- and Islamic-Date Diary Entries
39.8 Fancy Diary Display
39.9 Sexp Entries and the Fancy Diary Display
39.10 Customizing Appointment Reminders

40. Operating System Interface

40.1 Starting Up Emacs

40.1.1 Summary: Sequence of Actions at Startup
40.1.2 The Init File, `.emacs'
40.1.3 Terminal-Specific Initialization
40.1.4 Command-Line Arguments

40.2 Getting Out of Emacs

40.2.1 Killing Emacs
40.2.2 Suspending Emacs

40.3 Operating System Environment
40.4 User Identification
40.5 Time of Day
40.6 Time Conversion
40.7 Timers for Delayed Execution
40.8 Terminal Input

40.8.1 Input Modes
40.8.2 Translating Input Events
40.8.3 Recording Input

40.9 Terminal Output
40.10 Sound Output
40.11 System-Specific X11 Keysyms
40.12 Flow Control
40.13 Batch Mode

A. Emacs 20 Antinews

A.1 Old Lisp Features in Emacs 20
A.2 Old Lisp Features in Emacs 20.3

B. GNU Free Documentation License

ADDENDUM: How to use this License for your documents

C. GNU General Public License

Preamble
How to Apply These Terms to Your New Programs

D. Tips and Conventions

D.1 Emacs Lisp Coding Conventions
D.2 Tips for Making Compiled Code Fast
D.3 Tips for Documentation Strings
D.4 Tips on Writing Comments
D.5 Conventional Headers for Emacs Libraries

E. GNU Emacs Internals

E.1 Building Emacs
E.2 Pure Storage
E.3 Garbage Collection
E.4 Memory Usage
E.5 Writing Emacs Primitives
E.6 Object Internals

E.6.1 Buffer Internals
E.6.2 Window Internals
E.6.3 Process Internals

F. Standard Errors
G. Buffer-Local Variables
H. Standard Keymaps
I. Standard Hooks
Index
New Symbols Since the Previous Edition

[Top]

[Contents]

[Index]

[ ? ]

Short Table of Contents

1. Introduction
2. Lisp Data Types
3. Numbers
4. Strings and Characters
5. Lists
6. Sequences, Arrays, and Vectors
7. Hash Tables
8. Symbols
9. Evaluation
10. Control Structures
11. Variables
12. Functions
13. Macros
14. Writing Customization Definitions
15. Loading
16. Byte Compilation
17. Advising Emacs Lisp Functions
18. Debugging Lisp Programs
19. Reading and Printing Lisp Objects
20. Minibuffers
21. Command Loop
22. Keymaps
23. Major and Minor Modes
24. Documentation
25. Files
26. Backups and Auto-Saving
27. Buffers
28. Windows
29. Frames
30. Positions
31. Markers
32. Text
33. Non-ASCII Characters
34. Searching and Matching
35. Syntax Tables
36. Abbrevs and Abbrev Expansion
37. Processes
38. Emacs Display
39. Customizing the Calendar and Diary
40. Operating System Interface
A. Emacs 20 Antinews
B. GNU Free Documentation License
C. GNU General Public License
D. Tips and Conventions
E. GNU Emacs Internals
F. Standard Errors
G. Buffer-Local Variables
H. Standard Keymaps
I. Standard Hooks
Index
New Symbols Since the Previous Edition

[Top]

[Contents]

[Index]

[ ? ]

About this document
This document was generated on May 2, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button

Name

Go to

From 1.2.3 go to

[ < ]

Back

previous section in reading order

1.2.2

[ > ]

Forward

next section in reading order

1.2.4

[ << ]

FastBack

previous or up-and-previous section

1.1

[ Up ]

Up

up section

1.2

[ >> ]

FastForward

next or up-and-next section

1.3

[Top]

Top

cover (top) of document

[Contents]

Contents

table of contents

[Index]

Index

concept index

[ ? ]

About

this page

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

1. Section One

1.1 Subsection One-One

...

1.2 Subsection One-Two

1.2.1 Subsubsection One-Two-One

1.2.2 Subsubsection One-Two-Two

1.2.3 Subsubsection One-Two-Three <== Current Position

1.2.4 Subsubsection One-Two-Four

1.3 Subsection One-Three

...

1.4 Subsection One-Four

This document was generated on May 2, 2002 using texi2html


GNU Emacs Lisp Reference Manual

For Emacs Version 20.3

Revision 2.5, May 1998
by Bil Lewis, Dan LaLiberte, Richard Stallman and the GNU Manual Group

Table of Contents

GNU GENERAL PUBLIC LICENSE

Preamble
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
How to Apply These Terms to Your New Programs

Introduction

Caveats
Lisp History
Conventions

Some Terms
nil and t
Evaluation Notation
Printing Notation
Error Messages
Buffer Text Notation
Format of Descriptions

A Sample Function Description
A Sample Variable Description

Version Information
Acknowledgements

Lisp Data Types

Printed Representation and Read Syntax
Comments
Programming Types

Integer Type
Floating Point Type
Character Type
Symbol Type
Sequence Types
Cons Cell and List Types

Dotted Pair Notation
Association List Type

Array Type
String Type

Syntax for Strings
Non-ASCII Characters in Strings
Nonprinting Characters in Strings
Text Properties in Strings

Vector Type
Char-Table Type
Bool-Vector Type
Function Type
Macro Type
Primitive Function Type
Byte-Code Function Type
Autoload Type

Editing Types

Buffer Type
Marker Type
Window Type
Frame Type
Window Configuration Type
Frame Configuration Type
Process Type
Stream Type
Keymap Type
Overlay Type

Type Predicates
Equality Predicates

Numbers

Integer Basics
Floating Point Basics
Type Predicates for Numbers
Comparison of Numbers
Numeric Conversions
Arithmetic Operations
Rounding Operations
Bitwise Operations on Integers
Standard Mathematical Functions
Random Numbers

Strings and Characters

String and Character Basics
The Predicates for Strings
Creating Strings
Modifying Strings
Comparison of Characters and Strings
Conversion of Characters and Strings
Formatting Strings
Case Conversion in Lisp
The Case Table

Lists

Lists and Cons Cells
Lists as Linked Pairs of Boxes
Predicates on Lists
Accessing Elements of Lists
Building Cons Cells and Lists
Modifying Existing List Structure

Altering List Elements with setcar
Altering the CDR of a List
Functions that Rearrange Lists

Using Lists as Sets
Association Lists

Sequences, Arrays, and Vectors

Sequences
Arrays
Functions that Operate on Arrays
Vectors
Functions for Vectors
Char-Tables
Bool-vectors

Symbols

Symbol Components
Defining Symbols
Creating and Interning Symbols
Property Lists

Property Lists and Association Lists
Property List Functions for Symbols
Property Lists Outside Symbols

Evaluation

Kinds of Forms

Self-Evaluating Forms
Symbol Forms
Classification of List Forms
Symbol Function Indirection
Evaluation of Function Forms
Lisp Macro Evaluation
Special Forms
Autoloading

Quoting
Eval

Control Structures

Sequencing
Conditionals
Constructs for Combining Conditions
Iteration
Nonlocal Exits

Explicit Nonlocal Exits: catch and throw
Examples of catch and throw
Errors

How to Signal an Error
How Emacs Processes Errors
Writing Code to Handle Errors
Error Symbols and Condition Names

Cleaning Up from Nonlocal Exits

Variables

Global Variables
Variables That Never Change
Local Variables
When a Variable is "Void"
Defining Global Variables
Tips for Defining Variables Robustly
Accessing Variable Values
How to Alter a Variable Value
Scoping Rules for Variable Bindings

Scope
Extent
Implementation of Dynamic Scoping
Proper Use of Dynamic Scoping

Buffer-Local Variables

Introduction to Buffer-Local Variables
Creating and Deleting Buffer-Local Bindings
The Default Value of a Buffer-Local Variable

Frame-Local Variables
Possible Future Local Variables

Functions

What Is a Function?
Lambda Expressions

Components of a Lambda Expression
A Simple Lambda-Expression Example
Other Features of Argument Lists
Documentation Strings of Functions

Naming a Function
Defining Functions
Calling Functions
Mapping Functions
Anonymous Functions
Accessing Function Cell Contents
Inline Functions
Other Topics Related to Functions

Macros

A Simple Example of a Macro
Expansion of a Macro Call
Macros and Byte Compilation
Defining Macros
Backquote
Common Problems Using Macros

Evaluating Macro Arguments Repeatedly
Local Variables in Macro Expansions
Evaluating Macro Arguments in Expansion
How Many Times is the Macro Expanded?

Writing Customization Definitions

Common Keywords for All Kinds of Items
Defining Custom Groups
Defining Customization Variables
Customization Types

Simple Types
Composite Types
Splicing into Lists
Type Keywords

Loading

How Programs Do Loading
Library Search
Loading Non-ASCII Characters
Autoload
Repeated Loading
Features
Unloading
Hooks for Loading

Byte Compilation

Performance of Byte-Compiled Code
The Compilation Functions
Documentation Strings and Compilation
Dynamic Loading of Individual Functions
Evaluation During Compilation
Byte-Code Function Objects
Disassembled Byte-Code

Advising Emacs Lisp Functions

A Simple Advice Example
Defining Advice
Around-Advice
Computed Advice
Activation of Advice
Enabling and Disabling Advice
Preactivation
Argument Access in Advice
Definition of Subr Argument Lists
The Combined Definition

Debugging Lisp Programs

The Lisp Debugger

Entering the Debugger on an Error
Debugging Infinite Loops
Entering the Debugger on a Function Call
Explicit Entry to the Debugger
Using the Debugger
Debugger Commands
Invoking the Debugger
Internals of the Debugger

Edebug

Using Edebug
Instrumenting for Edebug
Edebug Execution Modes
Jumping
Miscellaneous Edebug Commands
Breakpoints

Global Break Condition
Source Breakpoints

Trapping Errors
Edebug Views
Evaluation
Evaluation List Buffer
Printing in Edebug
Trace Buffer
Coverage Testing
The Outside Context

Checking Whether to Stop
Edebug Display Update
Edebug Recursive Edit

Instrumenting Macro Calls

Specification List
Backtracking in Specifications
Specification Examples

Edebug Options

Debugging Invalid Lisp Syntax

Excess Open Parentheses
Excess Close Parentheses

Debugging Problems in Compilation

Reading and Printing Lisp Objects

Introduction to Reading and Printing
Input Streams
Input Functions
Output Streams
Output Functions
Variables Affecting Output

Minibuffers

Introduction to Minibuffers
Reading Text Strings with the Minibuffer
Reading Lisp Objects with the Minibuffer
Minibuffer History
Completion

Basic Completion Functions
Completion and the Minibuffer
Minibuffer Commands That Do Completion
High-Level Completion Functions
Reading File Names
Programmed Completion

Yes-or-No Queries
Asking Multiple Y-or-N Questions
Reading a Password
Minibuffer Miscellany

Command Loop

Command Loop Overview
Defining Commands

Using interactive
Code Characters for interactive
Examples of Using interactive

Interactive Call
Information from the Command Loop
Input Events

Keyboard Events
Function Keys
Mouse Events
Click Events
Drag Events
Button-Down Events
Repeat Events
Motion Events
Focus Events
Miscellaneous Window System Events
Event Examples
Classifying Events
Accessing Events
Putting Keyboard Events in Strings

Reading Input

Key Sequence Input
Reading One Event
Quoted Character Input
Miscellaneous Event Input Features

Special Events
Waiting for Elapsed Time or Input
Quitting
Prefix Command Arguments
Recursive Editing
Disabling Commands
Command History
Keyboard Macros

Keymaps

Keymap Terminology
Format of Keymaps
Creating Keymaps
Inheritance and Keymaps
Prefix Keys
Active Keymaps
Key Lookup
Functions for Key Lookup
Changing Key Bindings
Commands for Binding Keys
Scanning Keymaps
Menu Keymaps

Defining Menus

Simple Menu Items
Extended Menu Items
Alias Menu Items

Menus and the Mouse
Menus and the Keyboard
Menu Example
The Menu Bar
Modifying Menus

Major and Minor Modes

Major Modes

Major Mode Conventions
Major Mode Examples
How Emacs Chooses a Major Mode
Getting Help about a Major Mode
Defining Derived Modes

Minor Modes

Conventions for Writing Minor Modes
Keymaps and Minor Modes
Easy-Mmode

Mode Line Format

The Data Structure of the Mode Line
Variables Used in the Mode Line
%-Constructs in the Mode Line

Imenu
Font Lock Mode

Font Lock Basics
Search-based Fontification
Other Font Lock Variables
Levels of Font Lock
Faces for Font Lock
Syntactic Font Lock

Hooks

Documentation

Documentation Basics
Access to Documentation Strings
Substituting Key Bindings in Documentation
Describing Characters for Help Messages
Help Functions

Files

Visiting Files

Functions for Visiting Files
Subroutines of Visiting

Saving Buffers
Reading from Files
Writing to Files
File Locks
Information about Files

Testing Accessibility
Distinguishing Kinds of Files
Truenames
Other Information about Files

Changing File Names and Attributes
File Names

File Name Components
Directory Names
Absolute and Relative File Names
Functions that Expand Filenames
Generating Unique File Names
File Name Completion
Standard File Names

Contents of Directories
Creating and Deleting Directories
Making Certain File Names "Magic"
File Format Conversion

Backups and Auto-Saving

Backup Files

Making Backup Files
Backup by Renaming or by Copying?
Making and Deleting Numbered Backup Files
Naming Backup Files

Auto-Saving
Reverting

Buffers

Buffer Basics
The Current Buffer
Buffer Names
Buffer File Name
Buffer Modification
Comparison of Modification Time
Read-Only Buffers
The Buffer List
Creating Buffers
Killing Buffers
Indirect Buffers

Windows

Basic Concepts of Emacs Windows
Splitting Windows
Deleting Windows
Selecting Windows
Cyclic Ordering of Windows
Buffers and Windows
Displaying Buffers in Windows
Choosing a Window for Display
Windows and Point
The Window Start Position
Vertical Scrolling
Horizontal Scrolling
The Size of a Window
Changing the Size of a Window
Coordinates and Windows
Window Configurations
Hooks for Window Scrolling and Changes

Frames

Creating Frames
Multiple Displays
Frame Parameters

Access to Frame Parameters
Initial Frame Parameters
Window Frame Parameters
Frame Size And Position

Frame Titles
Deleting Frames
Finding All Frames
Frames and Windows
Minibuffers and Frames
Input Focus
Visibility of Frames
Raising and Lowering Frames
Frame Configurations
Mouse Tracking
Mouse Position
Pop-Up Menus
Dialog Boxes
Pointer Shapes
Window System Selections
Looking up Font Names
Fontsets
Color Names
X Resources
Data about the X Server

Positions

Point
Motion

Motion by Characters
Motion by Words
Motion to an End of the Buffer
Motion by Text Lines
Motion by Screen Lines
Moving over Balanced Expressions
Skipping Characters

Excursions
Narrowing

Markers

Overview of Markers
Predicates on Markers
Functions That Create Markers
Information from Markers
Marker Insertion Types
Moving Marker Positions
The Mark
The Region

Text

Examining Text Near Point
Examining Buffer Contents
Comparing Text
Inserting Text
User-Level Insertion Commands
Deleting Text
User-Level Deletion Commands
The Kill Ring

Kill Ring Concepts
Functions for Killing
Functions for Yanking
Low-Level Kill Ring
Internals of the Kill Ring

Undo
Maintaining Undo Lists
Filling
Margins for Filling
Adaptive Fill Mode
Auto Filling
Sorting Text
Counting Columns
Indentation

Indentation Primitives
Indentation Controlled by Major Mode
Indenting an Entire Region
Indentation Relative to Previous Lines
Adjustable "Tab Stops"
Indentation-Based Motion Commands

Case Changes
Text Properties

Examining Text Properties
Changing Text Properties
Text Property Search Functions
Properties with Special Meanings
Formatted Text Properties
Stickiness of Text Properties
Saving Text Properties in Files
Lazy Computation of Text Properties
Defining Clickable Text
Why Text Properties are not Intervals

Substituting for a Character Code
Registers
Transposition of Text
Change Hooks

Non-ASCII Characters

Text Representations
Converting Text Representations
Selecting a Representation
Character Codes
Character Sets
Characters and Bytes
Splitting Characters
Scanning for Character Sets
Translation of Characters
Coding Systems

Basic Concepts of Coding Systems
Encoding and I/O
Coding Systems in Lisp
User-Chosen Coding Systems
Default Coding Systems
Specifying a Coding System for One Operation
Explicit Encoding and Decoding
Terminal I/O Encoding
MS-DOS File Types

Input Methods

Searching and Matching

Searching for Strings
Regular Expressions

Syntax of Regular Expressions
Complex Regexp Example

Regular Expression Searching
POSIX Regular Expression Searching
Search and Replace
The Match Data

Replacing the Text That Matched
Simple Match Data Access
Accessing the Entire Match Data
Saving and Restoring the Match Data

Searching and Case
Standard Regular Expressions Used in Editing

Syntax Tables

Syntax Table Concepts
Syntax Descriptors

Table of Syntax Classes
Syntax Flags

Syntax Table Functions
Syntax Properties
Motion and Syntax
Parsing Balanced Expressions
Some Standard Syntax Tables
Syntax Table Internals
Categories

Abbrevs And Abbrev Expansion

Setting Up Abbrev Mode
Abbrev Tables
Defining Abbrevs
Saving Abbrevs in Files
Looking Up and Expanding Abbreviations
Standard Abbrev Tables

Processes

Functions that Create Subprocesses
Shell Arguments
Creating a Synchronous Process
Creating an Asynchronous Process
Deleting Processes
Process Information
Sending Input to Processes
Sending Signals to Processes
Receiving Output from Processes

Process Buffers
Process Filter Functions
Accepting Output from Processes

Sentinels: Detecting Process Status Changes
Transaction Queues
Network Connections

Operating System Interface

Starting Up Emacs

Summary: Sequence of Actions at Start Up
The Init File: `.emacs'
Terminal-Specific Initialization
Command Line Arguments

Getting Out of Emacs

Killing Emacs
Suspending Emacs

Operating System Environment
User Identification
Time of Day
Time Conversion
Timers for Delayed Execution
Terminal Input

Input Modes
Translating Input Events
Recording Input

Terminal Output
System-Specific X11 Keysyms
Flow Control
Batch Mode

Emacs Display

Refreshing the Screen
Truncation
The Echo Area
Invisible Text
Selective Display
The Overlay Arrow
Temporary Displays
Overlays

Overlay Properties
Managing Overlays

Width
Faces

Standard Faces
Defining Faces
Merging Faces for Display
Functions for Working with Faces

Blinking Parentheses
Inverse Video
Usual Display Conventions
Display Tables

Display Table Format
Active Display Table
Glyphs

Beeping
Window Systems

Customizing the Calendar and Diary

Customizing the Calendar
Customizing the Holidays
Date Display Format
Time Display Format
Daylight Savings Time
Customizing the Diary
Hebrew- and Islamic-Date Diary Entries
Fancy Diary Display
Sexp Entries and the Fancy Diary Display
Customizing Appointment Reminders

Tips and Conventions

Emacs Lisp Coding Conventions
Tips for Making Compiled Code Fast
Tips for Documentation Strings
Tips on Writing Comments
Conventional Headers for Emacs Libraries

GNU Emacs Internals

Building Emacs
Pure Storage
Garbage Collection
Memory Usage
Writing Emacs Primitives
Object Internals

Buffer Internals
Window Internals
Process Internals

Standard Errors
Buffer-Local Variables
Standard Keymaps
Standard Hooks
New Symbols Since the Previous Edition

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does.
Copyright (C) 19yy  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

Introduction

Most of the GNU Emacs text editor is written in the programming language called Emacs Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor. However, Emacs Lisp is more than a mere "extension language"; it is a full computer programming language in its own right. You can use it as you would any other programming language.

Because Emacs Lisp is designed for use in an editor, it has special features for scanning and parsing text as well as features for handling files, buffers, displays, subprocesses, and so on. Emacs Lisp is closely integrated with the editing facilities; thus, editing commands are functions that can also conveniently be called from Lisp programs, and parameters for customization are ordinary Lisp variables.

This manual attempts to be a full description of Emacs Lisp. For a beginner's introduction to Emacs Lisp, see An Introduction to Emacs Lisp Programming, by Bob Chassell, also published by the Free Software Foundation. This manual presumes considerable familiarity with the use of Emacs for editing; see The GNU Emacs Manual for this basic information.

Generally speaking, the earlier chapters describe features of Emacs Lisp that have counterparts in many programming languages, and later chapters describe features that are peculiar to Emacs Lisp or relate specifically to editing.

This is edition 2.5.

Caveats

This manual has gone through numerous drafts. It is nearly complete but not flawless. There are a few topics that are not covered, either because we consider them secondary (such as most of the individual modes) or because they are yet to be written. Because we are not able to deal with them completely, we have left out several parts intentionally. This includes most information about usage on VMS.

The manual should be fully correct in what it does cover, and it is therefore open to criticism on anything it says--from specific examples and descriptive text, to the ordering of chapters and sections. If something is confusing, or you find that you have to look at the sources or experiment to learn something not covered in the manual, then perhaps the manual should be fixed. Please let us know.

As you use the manual, we ask that you mark pages with corrections so you can later look them up and send them in. If you think of a simple, real-life example for a function or group of functions, please make an effort to write it up and send it in. Please reference any comments to the chapter name, section name, and function name, as appropriate, since page numbers and chapter and section numbers will change and we may have trouble finding the text you are talking about. Also state the number of the edition you are criticizing.

Please mail comments and corrections to
bug-lisp-manual@gnu.org
We let mail to this list accumulate unread until someone decides to apply the corrections. Months, and sometimes years, go by between updates. So please attach no significance to the lack of a reply--your mail will be acted on in due time. If you want to contact the Emacs maintainers more quickly, send mail to bug-gnu-emacs@gnu.org.

Lisp History

Lisp (LISt Processing language) was first developed in the late 1950s at the Massachusetts Institute of Technology for research in artificial intelligence. The great power of the Lisp language makes it ideal for other purposes as well, such as writing editing commands.

Dozens of Lisp implementations have been built over the years, each with its own idiosyncrasies. Many of them were inspired by Maclisp, which was written in the 1960s at MIT's Project MAC. Eventually the implementors of the descendants of Maclisp came together and developed a standard for Lisp systems, called Common Lisp. In the meantime, Gerry Sussman and Guy Steele at MIT developed a simplified but very powerful dialect of Lisp, called Scheme.

GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common Lisp. If you know Common Lisp, you will notice many similarities. However, many features of Common Lisp have been omitted or simplified in order to reduce the memory requirements of GNU Emacs. Sometimes the simplifications are so drastic that a Common Lisp user might be very confused. We will occasionally point out how GNU Emacs Lisp differs from Common Lisp. If you don't know Common Lisp, don't worry about it; this manual is self-contained.

A certain amount of Common Lisp emulation is available via the `cl' library See section `Common Lisp Extension' in Common Lisp Extensions.

Emacs Lisp is not at all influenced by Scheme; but the GNU project has an implementation of Scheme, called Guile. We use Guile in all new GNU software that calls for extensibility.

Conventions

This section explains the notational conventions that are used in this manual. You may want to skip this section and refer back to it later.

Some Terms

Throughout this manual, the phrases "the Lisp reader" and "the Lisp printer" refer to those routines in Lisp that convert textual representations of Lisp objects into actual Lisp objects, and vice versa. See section Printed Representation and Read Syntax, for more details. You, the person reading this manual, are thought of as "the programmer" and are addressed as "you". "The user" is the person who uses Lisp programs, including those you write.

Examples of Lisp code appear in this font or form: (list 1 2 3). Names that represent metasyntactic variables, or arguments to a function being described, appear in this font or form: first-number.

nil and t

In Lisp, the symbol nil has three separate meanings: it is a symbol with the name `nil'; it is the logical truth value false; and it is the empty list--the list of zero elements. When used as a variable, nil always has the value nil.

As far as the Lisp reader is concerned, `()' and `nil' are identical: they stand for the same object, the symbol nil. The different ways of writing the symbol are intended entirely for human readers. After the Lisp reader has read either `()' or `nil', there is no way to determine which representation was actually written by the programmer.

In this manual, we use () when we wish to emphasize that it means the empty list, and we use nil when we wish to emphasize that it means the truth value false. That is a good convention to use in Lisp programs also.
(cons 'foo ())                ; Emphasize the empty list
(not nil)                     ; Emphasize the truth value false
In contexts where a truth value is expected, any non-nil value is considered to be true. However, t is the preferred way to represent the truth value true. When you need to choose a value which represents true, and there is no other basis for choosing, use t. The symbol t always has the value t.

In Emacs Lisp, nil and t are special symbols that always evaluate to themselves. This is so that you do not need to quote them to use them as constants in a program. An attempt to change their values results in a setting-constant error. The same is true of any symbol whose name starts with a colon (`:'). See section Variables That Never Change.

Evaluation Notation

A Lisp expression that you can evaluate is called a form. Evaluating a form always produces a result, which is a Lisp object. In the examples in this manual, this is indicated with `=>':
(car '(1 2))
     => 1
You can read this as "(car '(1 2)) evaluates to 1".

When a form is a macro call, it expands into a new form for Lisp to evaluate. We show the result of the expansion with `==>'. We may or may not show the result of the evaluation of the expanded form.
(third '(a b c))
     ==> (car (cdr (cdr '(a b c))))
     => c
Sometimes to help describe one form we show another form that produces identical results. The exact equivalence of two forms is indicated with `=='.
(make-sparse-keymap) == (list 'keymap)
Printing Notation

Many of the examples in this manual print text when they are evaluated. If you execute example code in a Lisp Interaction buffer (such as the buffer `*scratch*'), the printed text is inserted into the buffer. If you execute the example by other means (such as by evaluating the function eval-region), the printed text is displayed in the echo area. You should be aware that text displayed in the echo area is truncated to a single line.

Examples in this manual indicate printed text with `-|', irrespective of where that text goes. The value returned by evaluating the form (here bar) follows on a separate line.
(progn (print 'foo) (print 'bar))
     -| foo
     -| bar
     => bar
Error Messages

Some examples signal errors. This normally displays an error message in the echo area. We show the error message on a line starting with `error-->'. Note that `error-->' itself does not appear in the echo area.
(+ 23 'x)
error--> Wrong type argument: number-or-marker-p, x
Buffer Text Notation

Some examples show modifications to text in a buffer, with "before" and "after" versions of the text. These examples show the contents of the buffer in question between two lines of dashes containing the buffer name. In addition, `-!-' indicates the location of point. (The symbol for point, of course, is not part of the text in the buffer; it indicates the place between two characters where point is currently located.)
---------- Buffer: foo ----------
This is the -!-contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     => nil
---------- Buffer: foo ----------
This is the changed -!-contents of foo.
---------- Buffer: foo ----------
Format of Descriptions

Functions, variables, macros, commands, user options, and special forms are described in this manual in a uniform format. The first line of a description contains the name of the item followed by its arguments, if any. The category--function, variable, or whatever--is printed next to the right margin. The description follows on succeeding lines, sometimes with examples.

A Sample Function Description

In a function description, the name of the function being described appears first. It is followed on the same line by a list of argument names. These names are also used in the body of the description, to stand for the values of the arguments.

The appearance of the keyword &optional in the argument list indicates that the subsequent arguments may be omitted (omitted arguments default to nil). Do not write &optional when you call the function.

The keyword &rest (which must be followed by a single argument name) indicates that any number of arguments can follow. The single following argument name will have a value, as a variable, which is a list of all these remaining arguments. Do not write &rest when you call the function.

Here is a description of an imaginary function foo:

Function: foo integer1 &optional integer2 &rest integers
The function foo subtracts integer1 from integer2, then adds all the rest of the arguments to the result. If integer2 is not supplied, then the number 19 is used by default.
(foo 1 5 3 9)
     => 16
(foo 5)
     => 14
More generally,
(foo w x y...)
==
(+ (- x w) y...)
Any argument whose name contains the name of a type (e.g., integer, integer1 or buffer) is expected to be of that type. A plural of a type (such as buffers) often means a list of objects of that type. Arguments named object may be of any type. (See section Lisp Data Types, for a list of Emacs object types.) Arguments with other sorts of names (e.g., new-file) are discussed specifically in the description of the function. In some sections, features common to the arguments of several functions are described at the beginning.

See section Lambda Expressions, for a more complete description of optional and rest arguments.

Command, macro, and special form descriptions have the same format, but the word `Function' is replaced by `Command', `Macro', or `Special Form', respectively. Commands are simply functions that may be called interactively; macros process their arguments differently from functions (the arguments are not evaluated), but are presented the same way.

Special form descriptions use a more complex notation to specify optional and repeated arguments because they can break the argument list down into separate arguments in more complicated ways. `[optional-arg]' means that optional-arg is optional and `repeated-args...' stands for zero or more arguments. Parentheses are used when several arguments are grouped into additional levels of list structure. Here is an example:

Special Form: count-loop (var [from to [inc]]) body...
This imaginary special form implements a loop that executes the body forms and then increments the variable var on each iteration. On the first iteration, the variable has the value from; on subsequent iterations, it is incremented by one (or by inc if that is given). The loop exits before executing body if var equals to. Here is an example:
(count-loop (i 0 10)
  (prin1 i) (princ " ")
  (prin1 (aref vector i))
  (terpri))
If from and to are omitted, var is bound to nil before the loop begins, and the loop exits if var is non-nil at the beginning of an iteration. Here is an example:
(count-loop (done)
  (if (pending)
      (fixit)
    (setq done t)))
In this special form, the arguments from and to are optional, but must both be present or both absent. If they are present, inc may optionally be specified as well. These arguments are grouped with the argument var into a list, to distinguish them from body, which includes all remaining elements of the form.

A Sample Variable Description

A variable is a name that can hold a value. Although any variable can be set by the user, certain variables that exist specifically so that users can change them are called user options. Ordinary variables and user options are described using a format like that for functions except that there are no arguments.

Here is a description of the imaginary electric-future-map variable.

Variable: electric-future-map
The value of this variable is a full keymap used by Electric Command Future mode. The functions in this map allow you to edit commands you have not yet thought about executing.

User option descriptions have the same format, but `Variable' is replaced by `User Option'.

Version Information

These facilities provide information about which version of Emacs is in use.

Command: emacs-version
This function returns a string describing the version of Emacs that is running. It is useful to include this string in bug reports.
(emacs-version)
  => "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
 of Sat Feb 14 1998 on psilocin.gnu.org"
Called interactively, the function prints the same information in the echo area.

Variable: emacs-build-time
The value of this variable indicates the time at which Emacs was built at the local site. It is a list of three integers, like the value of current-time (see section Time of Day).
emacs-build-time
     => (13623 62065 344633)
Variable: emacs-version
The value of this variable is the version of Emacs being run. It is a string such as "20.3.1". The last number in this string is not really part of the Emacs release version number; it is incremented each time you build Emacs in any given directory.

The following two variables have existed since Emacs version 19.23:

Variable: emacs-major-version
The major version number of Emacs, as an integer. For Emacs version 20.3, the value is 20.

Variable: emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version 20.3, the value is 3.

Acknowledgements

This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, Richard M. Stallman and Chris Welty, the volunteers of the GNU manual group, in an effort extending over several years. Robert J. Chassell helped to review and edit the manual, with the support of the Defense Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren A. Hunt, Jr. of Computational Logic, Inc.

Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Per Starback, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.
Lisp Data Types

A Lisp object is a piece of data used and manipulated by Lisp programs. For our purposes, a type or data type is a set of possible objects.

Every object belongs to at least one type. Objects of the same type have similar structures and may usually be used in the same contexts. Types can overlap, and objects can belong to two or more types. Consequently, we can ask whether an object belongs to a particular type, but not for "the" type of an object.

A few fundamental object types are built into Emacs. These, from which all other types are constructed, are called primitive types. Each object belongs to one and only one primitive type. These types include integer, float, cons, symbol, string, vector, subr, byte-code function, plus several special types, such as buffer, that are related to editing. (See section Editing Types.)

Each primitive type has a corresponding Lisp function that checks whether an object is a member of that type.

Note that Lisp is unlike many other languages in that Lisp objects are self-typing: the primitive type of the object is implicit in the object itself. For example, if an object is a vector, nothing can treat it as a number; Lisp knows it is a vector, not a number.

In most languages, the programmer must declare the data type of each variable, and the type is known by the compiler but not represented in the data. Such type declarations do not exist in Emacs Lisp. A Lisp variable can have any type of value, and it remembers whatever value you store in it, type and all.

This chapter describes the purpose, printed representation, and read syntax of each of the standard types in GNU Emacs Lisp. Details on how to use these types can be found in later chapters.

Printed Representation and Read Syntax

The printed representation of an object is the format of the output generated by the Lisp printer (the function prin1) for that object. The read syntax of an object is the format of the input accepted by the Lisp reader (the function read) for that object. See section Reading and Printing Lisp Objects.

Most objects have more than one possible read syntax. Some types of object have no read syntax, since it may not make sense to enter objects of these types directly in a Lisp program. Except for these cases, the printed representation of an object is also a read syntax for it.

In other languages, an expression is text; it has no other form. In Lisp, an expression is primarily a Lisp object and only secondarily the text that is the object's read syntax. Often there is no need to emphasize this distinction, but you must keep it in the back of your mind, or you will occasionally be very confused.

Every type has a printed representation. Some types have no read syntax--for example, the buffer type has none. Objects of these types are printed in hash notation: the characters `#<' followed by a descriptive string (typically the type name followed by the name of the object), and closed with a matching `>'. Hash notation cannot be read at all, so the Lisp reader signals the error invalid-read-syntax whenever it encounters `#<'.
(current-buffer)
     => #<buffer objects.texi>
When you evaluate an expression interactively, the Lisp interpreter first reads the textual representation of it, producing a Lisp object, and then evaluates that object (see section Evaluation). However, evaluation and reading are separate activities. Reading returns the Lisp object represented by the text that is read; the object may or may not be evaluated later. See section Input Functions, for a description of read, the basic function for reading objects.

Comments

A comment is text that is written in a program only for the sake of humans that read the program, and that has no effect on the meaning of the program. In Lisp, a semicolon (`;') starts a comment if it is not within a string or character constant. The comment continues to the end of line. The Lisp reader discards comments; they do not become part of the Lisp objects which represent the program within the Lisp system.

The `#@count' construct, which skips the next count characters, is useful for program-generated comments containing binary data. The Emacs Lisp byte compiler uses this in its output files (see section Byte Compilation). It isn't meant for source files, however.

See section Tips on Writing Comments, for conventions for formatting comments.

Programming Types

There are two general categories of types in Emacs Lisp: those having to do with Lisp programming, and those having to do with editing. The former exist in many Lisp implementations, in one form or another. The latter are unique to Emacs Lisp.

Integer Type

The range of values for integers in Emacs Lisp is -134217728 to 134217727 (28 bits; i.e., to on most machines. (Some machines may provide a wider range.) It is important to note that the Emacs Lisp arithmetic functions do not check for overflow. Thus (1+ 134217727) is -134217728 on most machines.

The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The printed representation produced by the Lisp interpreter never has a leading `+' or a final `.'.
-1               ; The integer -1.
1                ; The integer 1.
1.               ; Also The integer 1.
+1               ; Also the integer 1.
268435457        ; Also the integer 1 on a 28-bit implementation.
See section Numbers, for more information.

Floating Point Type

Emacs supports floating point numbers (though there is a compilation option to disable them). The precise range of floating point numbers is machine-specific.

The printed representation for floating point numbers requires either a decimal point (with at least one digit following), an exponent, or both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4' are five ways of writing a floating point number whose value is 1500. They are all equivalent.

See section Numbers, for more information.

Character Type

A character in Emacs Lisp is nothing more than an integer. In other words, characters are represented by their character codes. For example, the character A is represented as the integer 65.

Individual characters are not often used in programs. It is far more common to work with strings, which are sequences composed of characters. See section String Type.

Characters in strings, buffers, and files are currently limited to the range of 0 to 524287--nineteen bits. But not all values in that range are valid character codes. Codes 0 through 127 are ASCII codes; the rest are non-ASCII (see section Non-ASCII Characters). Characters that represent keyboard input have a much wider range, to encode modifier keys such as Control, Meta and Shift.

Since characters are really integers, the printed representation of a character is a decimal number. This is also a possible read syntax for a character, but writing characters that way in Lisp programs is a very bad idea. You should always use the special read syntax formats that Emacs Lisp provides for characters. These syntax formats start with a question mark.

The usual read syntax for alphanumeric characters is a question mark followed by the character; thus, `?A' for the character A, `?B' for the character B, and `?a' for the character a.

For example:
?Q => 81     ?q => 113
You can use the same syntax for punctuation characters, but it is often a good idea to add a `\' so that the Emacs commands for editing Lisp code don't get confused. For example, `?\ ' is the way to write the space character. If the character is `\', you must use a second `\' to quote it: `?\\'.

You can express the characters Control-g, backspace, tab, newline, vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t', `?\n', `?\v', `?\f', `?\r', `?\e', respectively. Thus,
?\a => 7                 ; C-g
?\b => 8                 ; backspace, BS, C-h
?\t => 9                 ; tab, TAB, C-i
?\n => 10                ; newline, C-j
?\v => 11                ; vertical tab, C-k
?\f => 12                ; formfeed character, C-l
?\r => 13                ; carriage return, RET, C-m
?\e => 27                ; escape character, ESC, C-[
?\\ => 92                ; backslash character, \
These sequences which start with backslash are also known as escape sequences, because backslash plays the role of an escape character; this usage has nothing to do with the character ESC.

Control characters may be represented using yet another read syntax. This consists of a question mark followed by a backslash, caret, and the corresponding non-control character, in either upper or lower case. For example, both `?\^I' and `?\^i' are valid read syntax for the character C-i, the character whose value is 9.

Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to `?\^I' and to `?\^i':
?\^I => 9     ?\C-I => 9
In strings and buffers, the only control characters allowed are those that exist in ASCII; but for keyboard input purposes, you can turn any character into a control character with `C-'. The character codes for these non-ASCII control characters include the bit as well as the code for the corresponding non-control character. Ordinary terminals have no way of generating non-ASCII control characters, but you can generate them straightforwardly using X and other window systems.

For historical reasons, Emacs treats the DEL character as the control equivalent of ?:
?\^? => 127     ?\C-? => 127
As a result, it is currently not possible to represent the character Control-?, which is a meaningful input character under X, using `\C-'. It is not easy to change this, as various Lisp files refer to DEL in this way.

For representing control characters to be found in files or strings, we recommend the `^' syntax; for control characters in keyboard input, we prefer the `C-' syntax. Which one you use does not affect the meaning of the program, but may guide the understanding of people who read it.

A meta character is a character typed with the META modifier key. The integer that represents such a character has the bit set (which on most machines makes it a negative number). We use high bits for this and other modifiers to make possible a wide range of basic character codes.

In a string, the bit attached to an ASCII character indicates a meta character; thus, the meta characters that can fit in a string have codes in the range from 128 to 255, and are the meta versions of the ordinary ASCII characters. (In Emacs versions 18 and older, this convention was used for characters outside of strings as well.)

The read syntax for meta characters uses `\M-'. For example, `?\M-A' stands for M-A. You can use `\M-' together with octal character codes (see below), with `\C-', or with any other syntax for a character. Thus, you can write M-A as `?\M-A', or as `?\M-\101'. Likewise, you can write C-M-b as `?\M-\C-b', `?\C-\M-b', or `?\M-\002'.

The case of a graphic character is indicated by its character code; for example, ASCII distinguishes between the characters `a' and `A'. But ASCII has no way to represent whether a control character is upper case or lower case. Emacs uses the bit to indicate that the shift key was used in typing a control character. This distinction is possible only when you use X terminals or other special terminals; ordinary terminals do not report the distinction to the computer in any way.

The X Window System defines three other modifier bits that can be set in a character: hyper, super and alt. The syntaxes for these bits are `\H-', `\s-' and `\A-'. (Case is significant in these prefixes.) Thus, `?\H-\M-\A-x' represents Alt-Hyper-Meta-x.

Finally, the most general read syntax for a character represents the character code in either octal or hex. To use octal, write a question mark followed by a backslash and the octal character code (up to three octal digits); thus, `?\101' for the character A, `?\001' for the character C-a, and ?\002 for the character C-b. Although this syntax can represent any ASCII character, it is preferred only when the precise octal value is more important than the ASCII representation.
?\012 => 10         ?\n => 10         ?\C-j => 10
?\101 => 65         ?A => 65
To use hex, write a question mark followed by a backslash, `x', and the hexadecimal character code. You can use any number of hex digits, so you can represent any character code in this way. Thus, `?\x41' for the character A, `?\x1' for the character C-a, and ?\x8e0 for the character ``a'.

A backslash is allowed, and harmless, preceding any character without a special escape meaning; thus, `?\+' is equivalent to `?+'. There is no reason to add a backslash before most characters. However, you should add a backslash before any of the characters `()\|;'`"#.,' to avoid confusing the Emacs commands for editing Lisp code. Also add a backslash before whitespace characters such as space, tab, newline and formfeed. However, it is cleaner to use one of the easily readable escape sequences, such as `\t', instead of an actual whitespace character such as a tab.

Symbol Type

A symbol in GNU Emacs Lisp is an object with a name. The symbol name serves as the printed representation of the symbol. In ordinary use, the name is unique--no two symbols have the same name.

A symbol can serve as a variable, as a function name, or to hold a property list. Or it may serve only to be distinct from all other Lisp objects, so that its presence in a data structure may be recognized reliably. In a given context, usually only one of these uses is intended. But you can use one symbol in all of these ways, independently.

A symbol name can contain any characters whatever. Most symbol names are written with letters, digits, and the punctuation characters `-+=*/'. Such names require no special punctuation; the characters of the name suffice as long as the name does not look like a number. (If it does, write a `\' at the beginning of the name to force interpretation as a symbol.) The characters `_~!@$%^&:<>{}' are less often used but also require no special punctuation. Any other characters may be included in a symbol's name by escaping them with a backslash. In contrast to its use in strings, however, a backslash in the name of a symbol simply quotes the single character that follows the backslash. For example, in a string, `\t' represents a tab character; in the name of a symbol, however, `\t' merely quotes the letter `t'. To have a symbol with a tab character in its name, you must actually use a tab (preceded with a backslash). But it's rare to do such a thing.

Common Lisp note: In Common Lisp, lower case letters are always "folded" to upper case, unless they are explicitly escaped. In Emacs Lisp, upper case and lower case letters are distinct.

Here are several examples of symbol names. Note that the `+' in the fifth example is escaped to prevent it from being read as a number. This is not necessary in the sixth example because the rest of the name makes it invalid as a number.
foo                 ; A symbol named `foo'.
FOO                 ; A symbol named `FOO', different from `foo'.
char-to-string      ; A symbol named `char-to-string'.
1+                  ; A symbol named `1+'
                    ;   (not `+1', which is an integer).
\+1                 ; A symbol named `+1'
                    ;   (not a very readable name).
\(*\ 1\ 2\)         ; A symbol named `(* 1 2)' (a worse name).
+-*/_~!@$%^&=:<>{}  ; A symbol named `+-*/_~!@$%^&=:<>{}'.
                    ;   These characters need not be escaped.
Sequence Types

A sequence is a Lisp object that represents an ordered set of elements. There are two kinds of sequence in Emacs Lisp, lists and arrays. Thus, an object of type list or of type array is also considered a sequence.

Arrays are further subdivided into strings, vectors, char-tables and bool-vectors. Vectors can hold elements of any type, but string elements must be characters, and bool-vector elements must be t or nil. The characters in a string can have text properties like characters in a buffer (see section Text Properties); vectors and bool-vectors do not support text properties even when their elements happen to be characters. Char-tables are like vectors except that they are indexed by any valid character code.

Lists, strings and the other array types are different, but they have important similarities. For example, all have a length l, and all have elements which can be indexed from zero to l minus one. Several functions, called sequence functions, accept any kind of sequence. For example, the function elt can be used to extract an element of a sequence, given its index. See section Sequences, Arrays, and Vectors.

It is generally impossible to read the same sequence twice, since sequences are always created anew upon reading. If you read the read syntax for a sequence twice, you get two sequences with equal contents. There is one exception: the empty list () always stands for the same object, nil.

Cons Cell and List Types

A cons cell is an object that consists of two pointers or slots, called the CAR slot and the CDR slot. Each slot can point to or hold to any Lisp object. We also say that the "the CAR of this cons cell is" whatever object its CAR slot currently points to, and likewise for the CDR.

A list is a series of cons cells, linked together so that the CDR slot of each cons cell holds either the next cons cell or the empty list. See section Lists, for functions that work on lists. Because most cons cells are used as part of lists, the phrase list structure has come to refer to any structure made out of cons cells.

The names CAR and CDR derive from the history of Lisp. The original Lisp implementation ran on an IBM 704 computer which divided words into two parts, called the "address" part and the "decrement"; CAR was an instruction to extract the contents of the address part of a register, and CDR an instruction to extract the contents of the decrement. By contrast, "cons cells" are named for the function cons that creates them, which in turn is named for its purpose, the construction of cells.

Because cons cells are so central to Lisp, we also have a word for "an object which is not a cons cell". These objects are called atoms.

The read syntax and printed representation for lists are identical, and consist of a left parenthesis, an arbitrary number of elements, and a right parenthesis.

Upon reading, each object inside the parentheses becomes an element of the list. That is, a cons cell is made for each element. The CAR slot of the cons cell points to the element, and its CDR slot points to the next cons cell of the list, which holds the next element in the list. The CDR slot of the last cons cell is set to point to nil.

A list can be illustrated by a diagram in which the cons cells are shown as pairs of boxes, like dominoes. (The Lisp reader cannot read such an illustration; unlike the textual notation, which can be understood by both humans and computers, the box illustrations can be understood only by humans.) This picture represents the three-element list (rose violet buttercup):
    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup
In this diagram, each box represents a slot that can point to any Lisp object. Each pair of boxes represents a cons cell. Each arrow is a pointer to a Lisp object, either an atom or another cons cell.

In this example, the first box, which holds the CAR of the first cons cell, points to or "contains" rose (a symbol). The second box, holding the CDR of the first cons cell, points to the next pair of boxes, the second cons cell. The CAR of the second cons cell is violet, and its CDR is the third cons cell. The CDR of the third (and last) cons cell is nil.

Here is another diagram of the same list, (rose violet buttercup), sketched in a different manner:
 ---------------       ----------------       -------------------
| car   | cdr   |     | car    | cdr   |     | car       | cdr   |
| rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
|       |       |     |        |       |     |           |       |
 ---------------       ----------------       -------------------
A list with no elements in it is the empty list; it is identical to the symbol nil. In other words, nil is both a symbol and a list.

Here are examples of lists written in Lisp syntax:
(A 2 "A")            ; A list of three elements.
()                   ; A list of no elements (the empty list).
nil                  ; A list of no elements (the empty list).
("A ()")             ; A list of one element: the string "A ()".
(A ())               ; A list of two elements: A and the empty list.
(A nil)              ; Equivalent to the previous.
((A B C))            ; A list of one element
                     ;   (which is a list of three elements).
Here is the list (A ()), or equivalently (A nil), depicted with boxes and arrows:
    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> A        --> nil
Dotted Pair Notation

Dotted pair notation is an alternative syntax for cons cells that represents the CAR and CDR explicitly. In this syntax, (a . b) stands for a cons cell whose CAR is the object a, and whose CDR is the object b. Dotted pair notation is therefore more general than list syntax. In the dotted pair notation, the list `(1 2 3)' is written as `(1 . (2 . (3 . nil)))'. For nil-terminated lists, you can use either notation, but list notation is usually clearer and more convenient. When printing a list, the dotted pair notation is only used if the CDR of a cons cell is not a list.

Here's an example using boxes to illustrate dotted pair notation. This example shows the pair (rose . violet):
    --- ---
   |   |   |--> violet
    --- ---
     |
     |
      --> rose
You can combine dotted pair notation with list notation to represent conveniently a chain of cons cells with a non-nil final CDR. You write a dot after the last element of the list, followed by the CDR of the final cons cell. For example, (rose violet . buttercup) is equivalent to (rose . (violet . buttercup)). The object looks like this:
    --- ---      --- ---
   |   |   |--> |   |   |--> buttercup
    --- ---      --- ---
     |            |
     |            |
      --> rose     --> violet
The syntax (rose . violet . buttercup) is invalid because there is nothing that it could mean. If anything, it would say to put buttercup in the CDR of a cons cell whose CDR is already used for violet.

The list (rose violet) is equivalent to (rose . (violet)), and looks like this:
    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> rose     --> violet
Similarly, the three-element list (rose violet buttercup) is equivalent to (rose . (violet . (buttercup))).

Association List Type

An association list or alist is a specially-constructed list whose elements are cons cells. In each element, the CAR is considered a key, and the CDR is considered an associated value. (In some cases, the associated value is stored in the CAR of the CDR.) Association lists are often used as stacks, since it is easy to add or remove associations at the front of the list.

For example,
(setq alist-of-colors
      '((rose . red) (lily . white)  (buttercup . yellow)))
sets the variable alist-of-colors to an alist of three elements. In the first element, rose is the key and red is the value.

See section Association Lists, for a further explanation of alists and for functions that work on alists.

Array Type

An array is composed of an arbitrary number of slots for pointing to other Lisp objects, arranged in a contiguous block of memory. Accessing any element of an array takes approximately the same amount of time. In contrast, accessing an element of a list requires time proportional to the position of the element in the list. (Elements at the end of a list take longer to access than elements at the beginning of a list.)

Emacs defines four types of array: strings, vectors, bool-vectors, and char-tables.

A string is an array of characters and a vector is an array of arbitrary objects. A bool-vector can hold only t or nil. These kinds of array may have any length up to the largest integer. Char-tables are sparse arrays indexed by any valid character code; they can hold arbitrary objects.

The first element of an array has index zero, the second element has index 1, and so on. This is called zero-origin indexing. For example, an array of four elements has indices 0, 1, 2, and 3. The largest possible index value is one less than the length of the array. Once an array is created, its length is fixed.

All Emacs Lisp arrays are one-dimensional. (Most other programming languages support multidimensional arrays, but they are not essential; you can get the same effect with an array of arrays.) Each type of array has its own read syntax; see the following sections for details.

The array type is contained in the sequence type and contains the string type, the vector type, the bool-vector type, and the char-table type.

String Type

A string is an array of characters. Strings are used for many purposes in Emacs, as can be expected in a text editor; for example, as the names of Lisp symbols, as messages for the user, and to represent text extracted from buffers. Strings in Lisp are constants: evaluation of a string returns the same string.

See section Strings and Characters, for functions that operate on strings.

Syntax for Strings

The read syntax for strings is a double-quote, an arbitrary number of characters, and another double-quote, "like this". To include a double-quote in a string, precede it with a backslash; thus, "\"" is a string containing just a single double-quote character. Likewise, you can include a backslash by preceding it with another backslash, like this: "this \\ is a single embedded backslash".

The newline character is not special in the read syntax for strings; if you write a new line between the double-quotes, it becomes a character in the string. But an escaped newline--one that is preceded by `\'---does not become part of the string; i.e., the Lisp reader ignores an escaped newline while reading a string. An escaped space `\ ' is likewise ignored.
"It is useful to include newlines
in documentation strings,
but the newline is \
ignored if escaped."
     => "It is useful to include newlines
in documentation strings,
but the newline is ignored if escaped."
Non-ASCII Characters in Strings

You can include a non-ASCII international character in a string constant by writing it literally. There are two text representations for non-ASCII characters in Emacs strings (and in buffers): unibyte and multibyte. If the string constant is read from a multibyte source, such as a multibyte buffer or string, or a file that would be visited as multibyte, then the character is read as a multibyte character, and that makes the string multibyte. If the string constant is read from a unibyte source, then the character is read as unibyte and that makes the string unibyte.

You can also represent a multibyte non-ASCII character with its character code, using a hex escape, `\xnnnnnnn', with as many digits as necessary. (Multibyte non-ASCII character codes are all greater than 256.) Any character which is not a valid hex digit terminates this construct. If the character that would follow is a hex digit, write `\ ' (backslash and space) to terminate the hex escape--for example, `\x8e0\ ' represents one character, `a' with grave accent. `\ ' in a string constant is just like backslash-newline; it does not contribute any character to the string, but it does terminate the preceding hex escape.

Using a multibyte hex escape forces the string to multibyte. You can represent a unibyte non-ASCII character with its character code, which must be in the range from 128 (0200 octal) to 255 (0377 octal). This forces a unibyte string. See section Text Representations, for more information about the two text representations.

Nonprinting Characters in Strings

You can use the same backslash escape-sequences in a string constant as in character literals (but do not use the question mark that begins a character constant). For example, you can write a string containing the nonprinting characters tab and C-a, with commas and spaces between them, like this: "\t, \C-a". See section Character Type, for a description of the read syntax for characters.

However, not all of the characters you can write with backslash escape-sequences are valid in strings. The only control characters that a string can hold are the ASCII control characters. Strings do not distinguish case in ASCII control characters.

Properly speaking, strings cannot hold meta characters; but when a string is to be used as a key sequence, there is a special convention that provides a way to represent meta versions of ASCII characters in a string. If you use the `\M-' syntax to indicate a meta character in a string constant, this sets the bit of the character in the string. If the string is used in define-key or lookup-key, this numeric code is translated into the equivalent meta character. See section Character Type.

Strings cannot hold characters that have the hyper, super, or alt modifiers.

Text Properties in Strings

A string can hold properties for the characters it contains, in addition to the characters themselves. This enables programs that copy text between strings and buffers to copy the text's properties with no special effort. See section Text Properties, for an explanation of what text properties mean. Strings with text properties use a special read and print syntax:
#("characters" property-data...)
where property-data consists of zero or more elements, in groups of three as follows:
beg end plist
The elements beg and end are integers, and together specify a range of indices in the string; plist is the property list for that range. For example,
#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
represents a string whose textual contents are `foo bar', in which the first three characters have a face property with value bold, and the last three have a face property with value italic. (The fourth character has no text properties, so its property list is nil. It is not actually necessary to mention ranges with nil as the property list, since any characters not mentioned in any range will default to having no properties.)

Vector Type

A vector is a one-dimensional array of elements of any type. It takes a constant amount of time to access any element of a vector. (In a list, the access time of an element is proportional to the distance of the element from the beginning of the list.)

The printed representation of a vector consists of a left square bracket, the elements, and a right square bracket. This is also the read syntax. Like numbers and strings, vectors are considered constants for evaluation.
[1 "two" (three)]      ; A vector of three elements.
     => [1 "two" (three)]
See section Vectors, for functions that work with vectors.

Char-Table Type

A char-table is a one-dimensional array of elements of any type, indexed by character codes. Char-tables have certain extra features to make them more useful for many jobs that involve assigning information to character codes--for example, a char-table can have a parent to inherit from, a default value, and a small number of extra slots to use for special purposes. A char-table can also specify a single value for a whole character set.

The printed representation of a char-table is like a vector except that there is an extra `#^' at the beginning.

See section Char-Tables, for special functions to operate on char-tables. Uses of char-tables include:

Case tables (see section The Case Table).
Character category tables (see section Categories).
Display Tables (see section Display Tables).
Syntax tables (see section Syntax Tables).

Bool-Vector Type

A bool-vector is a one-dimensional array of elements that must be t or nil.

The printed representation of a Bool-vector is like a string, except that it begins with `#&' followed by the length. The string constant that follows actually specifies the contents of the bool-vector as a bitmap--each "character" in the string contains 8 bits, which specify the next 8 elements of the bool-vector (1 stands for t, and 0 for nil). The least significant bits of the character correspond to the lowest indices in the bool-vector. If the length is not a multiple of 8, the printed representation shows extra elements, but these extras really make no difference.
(make-bool-vector 3 t)
     => #&3"\007"
(make-bool-vector 3 nil)
     => #&3"\0"
;; These are equal since only the first 3 bits are used.
(equal #&3"\377" #&3"\007")
     => t
Function Type

Just as functions in other programming languages are executable, Lisp function objects are pieces of executable code. However, functions in Lisp are primarily Lisp objects, and only secondarily the text which represents them. These Lisp objects are lambda expressions: lists whose first element is the symbol lambda (see section Lambda Expressions).

In most programming languages, it is impossible to have a function without a name. In Lisp, a function has no intrinsic name. A lambda expression is also called an anonymous function (see section Anonymous Functions). A named function in Lisp is actually a symbol with a valid function in its function cell (see section Defining Functions).

Most of the time, functions are called when their names are written in Lisp expressions in Lisp programs. However, you can construct or obtain a function object at run time and then call it with the primitive functions funcall and apply. See section Calling Functions.

Macro Type

A Lisp macro is a user-defined construct that extends the Lisp language. It is represented as an object much like a function, but with different argument-passing semantics. A Lisp macro has the form of a list whose first element is the symbol macro and whose CDR is a Lisp function object, including the lambda symbol.

Lisp macro objects are usually defined with the built-in defmacro function, but any list that begins with macro is a macro as far as Emacs is concerned. See section Macros, for an explanation of how to write a macro.

Warning: Lisp macros and keyboard macros (see section Keyboard Macros) are entirely different things. When we use the word "macro" without qualification, we mean a Lisp macro, not a keyboard macro.

Primitive Function Type

A primitive function is a function callable from Lisp but written in the C programming language. Primitive functions are also called subrs or built-in functions. (The word "subr" is derived from "subroutine".) Most primitive functions evaluate all their arguments when they are called. A primitive function that does not evaluate all its arguments is called a special form (see section Special Forms).

It does not matter to the caller of a function whether the function is primitive. However, this does matter if you try to redefine a primitive with a function written in Lisp. The reason is that the primitive function may be called directly from C code. Calls to the redefined function from Lisp will use the new definition, but calls from C code may still use the built-in definition. Therefore, we discourage redefinition of primitive functions.

The term function refers to all Emacs functions, whether written in Lisp or C. See section Function Type, for information about the functions written in Lisp.

Primitive functions have no read syntax and print in hash notation with the name of the subroutine.
(symbol-function 'car)          ; Access the function cell
                                ;   of the symbol.
     => #<subr car>
(subrp (symbol-function 'car))  ; Is this a primitive function?
     => t                       ; Yes.
Byte-Code Function Type

The byte compiler produces byte-code function objects. Internally, a byte-code function object is much like a vector; however, the evaluator handles this data type specially when it appears as a function to be called. See section Byte Compilation, for information about the byte compiler.

The printed representation and read syntax for a byte-code function object is like that for a vector, with an additional `#' before the opening `['.

Autoload Type

An autoload object is a list whose first element is the symbol autoload. It is stored as the function definition of a symbol as a placeholder for the real definition; it says that the real definition is found in a file of Lisp code that should be loaded when necessary. The autoload object contains the name of the file, plus some other information about the real definition.

After the file has been loaded, the symbol should have a new function definition that is not an autoload object. The new definition is then called as if it had been there to begin with. From the user's point of view, the function call works as expected, using the function definition in the loaded file.

An autoload object is usually created with the function autoload, which stores the object in the function cell of a symbol. See section Autoload, for more details.

Editing Types

The types in the previous section are used for general programming purposes, and most of them are common to most Lisp dialects. Emacs Lisp provides several additional data types for purposes connected with editing.

Buffer Type

A buffer is an object that holds text that can be edited (see section Buffers). Most buffers hold the contents of a disk file (see section Files) so they can be edited, but some are used for other purposes. Most buffers are also meant to be seen by the user, and therefore displayed, at some time, in a window (see section Windows). But a buffer need not be displayed in any window.

The contents of a buffer are much like a string, but buffers are not used like strings in Emacs Lisp, and the available operations are different. For example, you can insert text efficiently into an existing buffer, whereas "inserting" text into a string requires concatenating substrings, and the result is an entirely new string object.

Each buffer has a designated position called point (see section Positions). At any time, one buffer is the current buffer. Most editing commands act on the contents of the current buffer in the neighborhood of point. Many of the standard Emacs functions manipulate or test the characters in the current buffer; a whole chapter in this manual is devoted to describing these functions (see section Text).

Several other data structures are associated with each buffer:

a local syntax table (see section Syntax Tables);
a local keymap (see section Keymaps); and,
a list of buffer-local variable bindings (see section Buffer-Local Variables).
overlays (see section Overlays).
text properties for the text in the buffer (see section Text Properties).

The local keymap and variable list contain entries that individually override global bindings or values. These are used to customize the behavior of programs in different buffers, without actually changing the programs.

A buffer may be indirect, which means it shares the text of another buffer, but presents it differently. See section Indirect Buffers.

Buffers have no read syntax. They print in hash notation, showing the buffer name.
(current-buffer)
     => #<buffer objects.texi>
Marker Type

A marker denotes a position in a specific buffer. Markers therefore have two components: one for the buffer, and one for the position. Changes in the buffer's text automatically relocate the position value as necessary to ensure that the marker always points between the same two characters in the buffer.

Markers have no read syntax. They print in hash notation, giving the current character position and the name of the buffer.
(point-marker)
     => #<marker at 10779 in objects.texi>
See section Markers, for information on how to test, create, copy, and move markers.

Window Type

A window describes the portion of the terminal screen that Emacs uses to display a buffer. Every window has one associated buffer, whose contents appear in the window. By contrast, a given buffer may appear in one window, no window, or several windows.

Though many windows may exist simultaneously, at any time one window is designated the selected window. This is the window where the cursor is (usually) displayed when Emacs is ready for a command. The selected window usually displays the current buffer, but this is not necessarily the case.

Windows are grouped on the screen into frames; each window belongs to one and only one frame. See section Frame Type.

Windows have no read syntax. They print in hash notation, giving the window number and the name of the buffer being displayed. The window numbers exist to identify windows uniquely, since the buffer displayed in any given window can change frequently.
(selected-window)
     => #<window 1 on objects.texi>
See section Windows, for a description of the functions that work on windows.

Frame Type

A frame is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window) which you can subdivide vertically or horizontally into smaller windows.

Frames have no read syntax. They print in hash notation, giving the frame's title, plus its address in core (useful to identify the frame uniquely).
(selected-frame)
     => #<frame emacs@psilocin.gnu.org 0xdac80>
See section Frames, for a description of the functions that work on frames.

Window Configuration Type

A window configuration stores information about the positions, sizes, and contents of the windows in a frame, so you can recreate the same arrangement of windows later.

Window configurations do not have a read syntax; their print syntax looks like `#<window-configuration>'. See section Window Configurations, for a description of several functions related to window configurations.

Frame Configuration Type

A frame configuration stores information about the positions, sizes, and contents of the windows in all frames. It is actually a list whose CAR is frame-configuration and whose CDR is an alist. Each alist element describes one frame, which appears as the CAR of that element.

See section Frame Configurations, for a description of several functions related to frame configurations.

Process Type

The word process usually means a running program. Emacs itself runs in a process of this sort. However, in Emacs Lisp, a process is a Lisp object that designates a subprocess created by the Emacs process. Programs such as shells, GDB, ftp, and compilers, running in subprocesses of Emacs, extend the capabilities of Emacs.

An Emacs subprocess takes textual input from Emacs and returns textual output to Emacs for further manipulation. Emacs can also send signals to the subprocess.

Process objects have no read syntax. They print in hash notation, giving the name of the process:
(process-list)
     => (#<process shell>)
See section Processes, for information about functions that create, delete, return information about, send input or signals to, and receive output from processes.

Stream Type

A stream is an object that can be used as a source or sink for characters--either to supply characters for input or to accept them as output. Many different types can be used this way: markers, buffers, strings, and functions. Most often, input streams (character sources) obtain characters from the keyboard, a buffer, or a file, and output streams (character sinks) send characters to a buffer, such as a `*Help*' buffer, or to the echo area.

The object nil, in addition to its other meanings, may be used as a stream. It stands for the value of the variable standard-input or standard-output. Also, the object t as a stream specifies input using the minibuffer (see section Minibuffers) or output in the echo area (see section The Echo Area).

Streams have no special printed representation or read syntax, and print as whatever primitive type they are.

See section Reading and Printing Lisp Objects, for a description of functions related to streams, including parsing and printing functions.

Keymap Type

A keymap maps keys typed by the user to commands. This mapping controls how the user's command input is executed. A keymap is actually a list whose CAR is the symbol keymap.

See section Keymaps, for information about creating keymaps, handling prefix keys, local as well as global keymaps, and changing key bindings.

Overlay Type

An overlay specifies properties that apply to a part of a buffer. Each overlay applies to a specified range of the buffer, and contains a property list (a list whose elements are alternating property names and values). Overlay properties are used to present parts of the buffer temporarily in a different display style. Overlays have no read syntax, and print in hash notation, giving the buffer name and range of positions.

See section Overlays, for how to create and use overlays.

Type Predicates

The Emacs Lisp interpreter itself does not perform type checking on the actual arguments passed to functions when they are called. It could not do so, since function arguments in Lisp do not have declared data types, as they do in other programming languages. It is therefore up to the individual function to test whether each actual argument belongs to a type that the function can use.

All built-in functions do check the types of their actual arguments when appropriate, and signal a wrong-type-argument error if an argument is of the wrong type. For example, here is what happens if you pass an argument to + that it cannot handle:
(+ 2 'a)
     error--> Wrong type argument: number-or-marker-p, a
If you want your program to handle different types differently, you must do explicit type checking. The most common way to check the type of an object is to call a type predicate function. Emacs has a type predicate for each type, as well as some predicates for combinations of types.

A type predicate function takes one argument; it returns t if the argument belongs to the appropriate type, and nil otherwise. Following a general Lisp convention for predicate functions, most type predicates' names end with `p'.

Here is an example which uses the predicates listp to check for a list and symbolp to check for a symbol.
(defun add-on (x)
  (cond ((symbolp x)
         ;; If X is a symbol, put it on LIST.
         (setq list (cons x list)))
        ((listp x)
         ;; If X is a list, add its elements to LIST.
         (setq list (append x list)))
        (t
         ;; We handle only symbols and lists.
         (error "Invalid argument %s in add-on" x))))
Here is a table of predefined type predicates, in alphabetical order, with references to further information.

atom
See section Predicates on Lists.
arrayp
See section Functions that Operate on Arrays.
bool-vector-p
See section Bool-vectors.
bufferp
See section Buffer Basics.
byte-code-function-p
See section Byte-Code Function Type.
case-table-p
See section The Case Table.
char-or-string-p
See section The Predicates for Strings.
char-table-p
See section Char-Tables.
commandp
See section Interactive Call.
consp
See section Predicates on Lists.
display-table-p
See section Display Tables.
floatp
See section Type Predicates for Numbers.
frame-configuration-p
See section Frame Configurations.
frame-live-p
See section Deleting Frames.
framep
See section Frames.
functionp
See section Functions.
integer-or-marker-p
See section Predicates on Markers.
integerp
See section Type Predicates for Numbers.
keymapp
See section Creating Keymaps.
listp
See section Predicates on Lists.
markerp
See section Predicates on Markers.
wholenump
See section Type Predicates for Numbers.
nlistp
See section Predicates on Lists.
numberp
See section Type Predicates for Numbers.
number-or-marker-p
See section Predicates on Markers.
overlayp
See section Overlays.
processp
See section Processes.
sequencep
See section Sequences.
stringp
See section The Predicates for Strings.
subrp
See section Accessing Function Cell Contents.
symbolp
See section Symbols.
syntax-table-p
See section Syntax Tables.
user-variable-p
See section Defining Global Variables.
vectorp
See section Vectors.
window-configuration-p
See section Window Configurations.
window-live-p
See section Deleting Windows.
windowp
See section Basic Concepts of Emacs Windows.
The most general way to check the type of an object is to call the function type-of. Recall that each object belongs to one and only one primitive type; type-of tells you which one (see section Lisp Data Types). But type-of knows nothing about non-primitive types. In most cases, it is more convenient to use type predicates than type-of.

Function: type-of object
This function returns a symbol naming the primitive type of object. The value is one of the symbols symbol, integer, float, string, cons, vector, char-table, bool-vector, subr, compiled-function, marker, overlay, window, buffer, frame, process, or window-configuration.
(type-of 1)
     => integer
(type-of 'nil)
     => symbol
(type-of '())    ; () is nil.
     => symbol
(type-of '(x))
     => cons
Equality Predicates

Here we describe two functions that test for equality between any two objects. Other functions test equality between objects of specific types, e.g., strings. For these predicates, see the appropriate chapter describing the data type.

Function: eq object1 object2
This function returns t if object1 and object2 are the same object, nil otherwise. The "same object" means that a change in one will be reflected by the same change in the other.

eq returns t if object1 and object2 are integers with the same value. Also, since symbol names are normally unique, if the arguments are symbols with the same name, they are eq. For other types (e.g., lists, vectors, strings), two arguments with the same contents or elements are not necessarily eq to each other: they are eq only if they are the same object.
(eq 'foo 'foo)
     => t

(eq 456 456)
     => t

(eq "asdf" "asdf")
     => nil

(eq '(1 (2 (3))) '(1 (2 (3))))
     => nil

(setq foo '(1 (2 (3))))
     => (1 (2 (3)))
(eq foo foo)
     => t
(eq foo '(1 (2 (3))))
     => nil

(eq [(1 2) 3] [(1 2) 3])
     => nil

(eq (point-marker) (point-marker))
     => nil
The make-symbol function returns an uninterned symbol, distinct from the symbol that is used if you write the name in a Lisp expression. Distinct symbols with the same name are not eq. See section Creating and Interning Symbols.
(eq (make-symbol "foo") 'foo)
     => nil
Function: equal object1 object2
This function returns t if object1 and object2 have equal components, nil otherwise. Whereas eq tests if its arguments are the same object, equal looks inside nonidentical arguments to see if their elements are the same. So, if two objects are eq, they are equal, but the converse is not always true.
(equal 'foo 'foo)
     => t

(equal 456 456)
     => t

(equal "asdf" "asdf")
     => t
(eq "asdf" "asdf")
     => nil

(equal '(1 (2 (3))) '(1 (2 (3))))
     => t
(eq '(1 (2 (3))) '(1 (2 (3))))
     => nil

(equal [(1 2) 3] [(1 2) 3])
     => t
(eq [(1 2) 3] [(1 2) 3])
     => nil

(equal (point-marker) (point-marker))
     => t

(eq (point-marker) (point-marker))
     => nil
Comparison of strings is case-sensitive, but does not take account of text properties--it compares only the characters in the strings. A unibyte string never equals a multibyte string unless the contents are entirely ASCII (see section Text Representations).
(equal "asdf" "ASDF")
     => nil
Two distinct buffers are never equal, even if their contents are the same.

The test for equality is implemented recursively, and circular lists may therefore cause infinite recursion (leading to an error).
Numbers

GNU Emacs supports two numeric data types: integers and floating point numbers. Integers are whole numbers such as -3, 0, 7, 13, and 511. Their values are exact. Floating point numbers are numbers with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be expressed in exponential notation: 1.5e2 equals 150; in this example, `e2' stands for ten to the second power, and that is multiplied by 1.5. Floating point values are not exact; they have a fixed, limited amount of precision.

Integer Basics

The range of values for an integer depends on the machine. The minimum range is -134217728 to 134217727 (28 bits; i.e., to but some machines may provide a wider range. Many examples in this chapter assume an integer has 28 bits.

The Lisp reader reads an integer as a sequence of digits with optional initial sign and optional final period.
 1               ; The integer 1.
 1.              ; The integer 1.
+1               ; Also the integer 1.
-1               ; The integer -1.
 268435457       ; Also the integer 1, due to overflow.
 0               ; The integer 0.
-0               ; The integer 0.
To understand how various functions work on integers, especially the bitwise operators (see section Bitwise Operations on Integers), it is often helpful to view the numbers in their binary form.

In 28-bit binary, the decimal integer 5 looks like this:
0000  0000 0000  0000 0000  0000 0101
(We have inserted spaces between groups of 4 bits, and two spaces between groups of 8 bits, to make the binary integer easier to read.)

The integer -1 looks like this:
1111  1111 1111  1111 1111  1111 1111
-1 is represented as 28 ones. (This is called two's complement notation.)

The negative integer, -5, is creating by subtracting 4 from -1. In binary, the decimal integer 4 is 100. Consequently, -5 looks like this:
1111  1111 1111  1111 1111  1111 1011
In this implementation, the largest 28-bit binary integer value is 134,217,727 in decimal. In binary, it looks like this:
0111  1111 1111  1111 1111  1111 1111
Since the arithmetic functions do not check whether integers go outside their range, when you add 1 to 134,217,727, the value is the negative integer -134,217,728:
(+ 1 134217727)
     => -134217728
     => 1000  0000 0000  0000 0000  0000 0000
Many of the functions described in this chapter accept markers for arguments in place of numbers. (See section Markers.) Since the actual arguments to such functions may be either numbers or markers, we often give these arguments the name number-or-marker. When the argument value is a marker, its position value is used and its buffer is ignored.

Floating Point Basics

Floating point numbers are useful for representing numbers that are not integral. The precise range of floating point numbers is machine-specific; it is the same as the range of the C data type double on the machine you are using.

The read-syntax for floating point numbers requires either a decimal point (with at least one digit following), an exponent, or both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4' are five ways of writing a floating point number whose value is 1500. They are all equivalent. You can also use a minus sign to write negative floating point numbers, as in `-1.0'.

Most modern computers support the IEEE floating point standard, which provides for positive infinity and negative infinity as floating point values. It also provides for a class of values called NaN or "not-a-number"; numerical functions return such values in cases where there is no correct answer. For example, (sqrt -1.0) returns a NaN. For practical purposes, there's no significant difference between different NaN values in Emacs Lisp, and there's no rule for precisely which NaN value should be used in a particular case, so Emacs Lisp doesn't try to distinguish them. Here are the read syntaxes for these special floating point values:

positive infinity
`1.0e+INF'
negative infinity
`-1.0e+INF'
Not-a-number
`0.0e+NaN'.
In addition, the value -0.0 is distinguishable from ordinary zero in IEEE floating point (although equal and = consider them equal values).

You can use logb to extract the binary exponent of a floating point number (or estimate the logarithm of an integer):

Function: logb number
This function returns the binary exponent of number. More precisely, the value is the logarithm of number base 2, rounded down to an integer.
(logb 10)
     => 3
(logb 10.0e20)
     => 69
Type Predicates for Numbers

The functions in this section test whether the argument is a number or whether it is a certain sort of number. The functions integerp and floatp can take any type of Lisp object as argument (the predicates would not be of much use otherwise); but the zerop predicate requires a number as its argument. See also integer-or-marker-p and number-or-marker-p, in section Predicates on Markers.

Function: floatp object
This predicate tests whether its argument is a floating point number and returns t if so, nil otherwise.

floatp does not exist in Emacs versions 18 and earlier.

Function: integerp object
This predicate tests whether its argument is an integer, and returns t if so, nil otherwise.

Function: numberp object
This predicate tests whether its argument is a number (either integer or floating point), and returns t if so, nil otherwise.

Function: wholenump object
The wholenump predicate (whose name comes from the phrase "whole-number-p") tests to see whether its argument is a nonnegative integer, and returns t if so, nil otherwise. 0 is considered non-negative.

natnump is an obsolete synonym for wholenump.

Function: zerop number
This predicate tests whether its argument is zero, and returns t if so, nil otherwise. The argument must be a number.

These two forms are equivalent: (zerop x) == (= x 0).

Comparison of Numbers

To test numbers for numerical equality, you should normally use =, not eq. There can be many distinct floating point number objects with the same numeric value. If you use eq to compare them, then you test whether two values are the same object. By contrast, = compares only the numeric values of the objects.

At present, each integer value has a unique Lisp object in Emacs Lisp. Therefore, eq is equivalent to = where integers are concerned. It is sometimes convenient to use eq for comparing an unknown value with an integer, because eq does not report an error if the unknown value is not a number--it accepts arguments of any type. By contrast, = signals an error if the arguments are not numbers or markers. However, it is a good idea to use = if you can, even for comparing integers, just in case we change the representation of integers in a future Emacs version.

Sometimes it is useful to compare numbers with equal; it treats two numbers as equal if they have the same data type (both integers, or both floating point) and the same value. By contrast, = can treat an integer and a floating point number as equal.

There is another wrinkle: because floating point arithmetic is not exact, it is often a bad idea to check for equality of two floating point values. Usually it is better to test for approximate equality. Here's a function to do this:
(defvar fuzz-factor 1.0e-6)
(defun approx-equal (x y)
  (or (and (= x 0) (= y 0))
      (< (/ (abs (- x y))
            (max (abs x) (abs y)))
         fuzz-factor)))
Common Lisp note: Comparing numbers in Common Lisp always requires = because Common Lisp implements multi-word integers, and two distinct integer objects can have the same numeric value. Emacs Lisp can have just one integer object for any given value because it has a limited range of integer values.

Function: = number-or-marker1 number-or-marker2
This function tests whether its arguments are numerically equal, and returns t if so, nil otherwise.

Function: /= number-or-marker1 number-or-marker2
This function tests whether its arguments are numerically equal, and returns t if they are not, and nil if they are.

Function: < number-or-marker1 number-or-marker2
This function tests whether its first argument is strictly less than its second argument. It returns t if so, nil otherwise.

Function: <= number-or-marker1 number-or-marker2
This function tests whether its first argument is less than or equal to its second argument. It returns t if so, nil otherwise.

Function: > number-or-marker1 number-or-marker2
This function tests whether its first argument is strictly greater than its second argument. It returns t if so, nil otherwise.

Function: >= number-or-marker1 number-or-marker2
This function tests whether its first argument is greater than or equal to its second argument. It returns t if so, nil otherwise.

Function: max number-or-marker &rest numbers-or-markers
This function returns the largest of its arguments.
(max 20)
     => 20
(max 1 2.5)
     => 2.5
(max 1 3 2.5)
     => 3
Function: min number-or-marker &rest numbers-or-markers
This function returns the smallest of its arguments.
(min -4 1)
     => -4
Function: abs number
This function returns the absolute value of number.

Numeric Conversions

To convert an integer to floating point, use the function float.

Function: float number
This returns number converted to floating point. If number is already a floating point number, float returns it unchanged.

There are four functions to convert floating point numbers to integers; they differ in how they round. These functions accept integer arguments also, and return such arguments unchanged.

Function: truncate number
This returns number, converted to an integer by rounding towards zero.

Function: floor number &optional divisor
This returns number, converted to an integer by rounding downward (towards negative infinity).

If divisor is specified, number is divided by divisor before the floor is taken; this uses the kind of division operation that corresponds to mod, rounding downward. An arith-error results if divisor is 0.

Function: ceiling number
This returns number, converted to an integer by rounding upward (towards positive infinity).

Function: round number
This returns number, converted to an integer by rounding towards the nearest integer. Rounding a value equidistant between two integers may choose the integer closer to zero, or it may prefer an even integer, depending on your machine.

Arithmetic Operations

Emacs Lisp provides the traditional four arithmetic operations: addition, subtraction, multiplication, and division. Remainder and modulus functions supplement the division functions. The functions to add or subtract 1 are provided because they are traditional in Lisp and commonly used.

All of these functions except % return a floating point value if any argument is floating.

It is important to note that in Emacs Lisp, arithmetic functions do not check for overflow. Thus (1+ 134217727) may evaluate to -134217728, depending on your hardware.

Function: 1+ number-or-marker
This function returns number-or-marker plus 1. For example,
(setq foo 4)
     => 4
(1+ foo)
     => 5
This function is not analogous to the C operator ++---it does not increment a variable. It just computes a sum. Thus, if we continue,
foo
     => 4
If you want to increment the variable, you must use setq, like this:
(setq foo (1+ foo))
     => 5
Function: 1- number-or-marker
This function returns number-or-marker minus 1.

Function: + &rest numbers-or-markers
This function adds its arguments together. When given no arguments, + returns 0.
(+)
     => 0
(+ 1)
     => 1
(+ 1 2 3 4)
     => 10
Function: - &optional number-or-marker &rest more-numbers-or-markers
The - function serves two purposes: negation and subtraction. When - has a single argument, the value is the negative of the argument. When there are multiple arguments, - subtracts each of the more-numbers-or-markers from number-or-marker, cumulatively. If there are no arguments, the result is 0.
(- 10 1 2 3 4)
     => 0
(- 10)
     => -10
(-)
     => 0
Function: * &rest numbers-or-markers
This function multiplies its arguments together, and returns the product. When given no arguments, * returns 1.
(*)
     => 1
(* 1)
     => 1
(* 1 2 3 4)
     => 24
Function: / dividend divisor &rest divisors
This function divides dividend by divisor and returns the quotient. If there are additional arguments divisors, then it divides dividend by each divisor in turn. Each argument may be a number or a marker.

If all the arguments are integers, then the result is an integer too. This means the result has to be rounded. On most machines, the result is rounded towards zero after each division, but some machines may round differently with negative arguments. This is because the Lisp function / is implemented using the C division operator, which also permits machine-dependent rounding. As a practical matter, all known machines round in the standard fashion.

If you divide an integer by 0, an arith-error error is signaled. (See section Errors.) Floating point division by zero returns either infinity or a NaN if your machine supports IEEE floating point; otherwise, it signals an arith-error error.
(/ 6 2)
     => 3
(/ 5 2)
     => 2
(/ 5.0 2)
     => 2.5
(/ 5 2.0)
     => 2.5
(/ 5.0 2.0)
     => 2.5
(/ 25 3 2)
     => 4
(/ -17 6)
     => -2
The result of (/ -17 6) could in principle be -3 on some machines.

Function: % dividend divisor
This function returns the integer remainder after division of dividend by divisor. The arguments must be integers or markers.

For negative arguments, the remainder is in principle machine-dependent since the quotient is; but in practice, all known machines behave alike.

An arith-error results if divisor is 0.
(% 9 4)
     => 1
(% -9 4)
     => -1
(% 9 -4)
     => 1
(% -9 -4)
     => -1
For any two integers dividend and divisor,
(+ (% dividend divisor)
   (* (/ dividend divisor) divisor))
always equals dividend.

Function: mod dividend divisor
This function returns the value of dividend modulo divisor; in other words, the remainder after division of dividend by divisor, but with the same sign as divisor. The arguments must be numbers or markers.

Unlike %, mod returns a well-defined result for negative arguments. It also permits floating point arguments; it rounds the quotient downward (towards minus infinity) to an integer, and uses that quotient to compute the remainder.

An arith-error results if divisor is 0.
(mod 9 4)
     => 1
(mod -9 4)
     => 3
(mod 9 -4)
     => -3
(mod -9 -4)
     => -1
(mod 5.5 2.5)
     => .5
For any two numbers dividend and divisor,
(+ (mod dividend divisor)
   (* (floor dividend divisor) divisor))
always equals dividend, subject to rounding error if either argument is floating point. For floor, see section Numeric Conversions.

Rounding Operations

The functions ffloor, fceiling, fround, and ftruncate take a floating point argument and return a floating point result whose value is a nearby integer. ffloor returns the nearest integer below; fceiling, the nearest integer above; ftruncate, the nearest integer in the direction towards zero; fround, the nearest integer.

Function: ffloor float
This function rounds float to the next lower integral value, and returns that value as a floating point number.

Function: fceiling float
This function rounds float to the next higher integral value, and returns that value as a floating point number.

Function: ftruncate float
This function rounds float towards zero to an integral value, and returns that value as a floating point number.

Function: fround float
This function rounds float to the nearest integral value, and returns that value as a floating point number.

Bitwise Operations on Integers

In a computer, an integer is represented as a binary number, a sequence of bits (digits which are either zero or one). A bitwise operation acts on the individual bits of such a sequence. For example, shifting moves the whole sequence left or right one or more places, reproducing the same pattern "moved over".

The bitwise operations in Emacs Lisp apply only to integers.

Function: lsh integer1 count
lsh, which is an abbreviation for logical shift, shifts the bits in integer1 to the left count places, or to the right if count is negative, bringing zeros into the vacated bits. If count is negative, lsh shifts zeros into the leftmost (most-significant) bit, producing a positive result even if integer1 is negative. Contrast this with ash, below.

Here are two examples of lsh, shifting a pattern of bits one place to the left. We show only the low-order eight bits of the binary pattern; the rest are all zero.
(lsh 5 1)
     => 10
;; Decimal 5 becomes decimal 10.
00000101 => 00001010

(lsh 7 1)
     => 14
;; Decimal 7 becomes decimal 14.
00000111 => 00001110
As the examples illustrate, shifting the pattern of bits one place to the left produces a number that is twice the value of the previous number.

Shifting a pattern of bits two places to the left produces results like this (with 8-bit binary numbers):
(lsh 3 2)
     => 12
;; Decimal 3 becomes decimal 12.
00000011 => 00001100
On the other hand, shifting one place to the right looks like this:
(lsh 6 -1)
     => 3
;; Decimal 6 becomes decimal 3.
00000110 => 00000011

(lsh 5 -1)
     => 2
;; Decimal 5 becomes decimal 2.
00000101 => 00000010
As the example illustrates, shifting one place to the right divides the value of a positive integer by two, rounding downward.

The function lsh, like all Emacs Lisp arithmetic functions, does not check for overflow, so shifting left can discard significant bits and change the sign of the number. For example, left shifting 134,217,727 produces -2 on a 28-bit machine:
(lsh 134217727 1)          ; left shift
     => -2
In binary, in the 28-bit implementation, the argument looks like this:
;; Decimal 134,217,727
0111  1111 1111  1111 1111  1111 1111
which becomes the following when left shifted:
;; Decimal -2
1111  1111 1111  1111 1111  1111 1110
Function: ash integer1 count
ash (arithmetic shift) shifts the bits in integer1 to the left count places, or to the right if count is negative.

ash gives the same results as lsh except when integer1 and count are both negative. In that case, ash puts ones in the empty bit positions on the left, while lsh puts zeros in those bit positions.

Thus, with ash, shifting the pattern of bits one place to the right looks like this:
(ash -6 -1) => -3
;; Decimal -6 becomes decimal -3.
1111  1111 1111  1111 1111  1111 1010
     =>
1111  1111 1111  1111 1111  1111 1101
In contrast, shifting the pattern of bits one place to the right with lsh looks like this:
(lsh -6 -1) => 134217725
;; Decimal -6 becomes decimal 134,217,725.
1111  1111 1111  1111 1111  1111 1010
     =>
0111  1111 1111  1111 1111  1111 1101
Here are other examples:
                   ;               28-bit binary values

(lsh 5 2)          ;   5  =  0000  0000 0000  0000 0000  0000 0101
     => 20         ;      =  0000  0000 0000  0000 0000  0001 0100
(ash 5 2)
     => 20
(lsh -5 2)         ;  -5  =  1111  1111 1111  1111 1111  1111 1011
     => -20        ;      =  1111  1111 1111  1111 1111  1110 1100
(ash -5 2)
     => -20
(lsh 5 -2)         ;   5  =  0000  0000 0000  0000 0000  0000 0101
     => 1          ;      =  0000  0000 0000  0000 0000  0000 0001
(ash 5 -2)
     => 1
(lsh -5 -2)        ;  -5  =  1111  1111 1111  1111 1111  1111 1011
     => 4194302    ;      =  0011  1111 1111  1111 1111  1111 1110
(ash -5 -2)        ;  -5  =  1111  1111 1111  1111 1111  1111 1011
     => -2         ;      =  1111  1111 1111  1111 1111  1111 1110
Function: logand &rest ints-or-markers
This function returns the "logical and" of the arguments: the nth bit is set in the result if, and only if, the nth bit is set in all the arguments. ("Set" means that the value of the bit is 1 rather than 0.)

For example, using 4-bit binary numbers, the "logical and" of 13 and 12 is 12: 1101 combined with 1100 produces 1100. In both the binary numbers, the leftmost two bits are set (i.e., they are 1's), so the leftmost two bits of the returned value are set. However, for the rightmost two bits, each is zero in at least one of the arguments, so the rightmost two bits of the returned value are 0's.

Therefore,
(logand 13 12)
     => 12
If logand is not passed any argument, it returns a value of -1. This number is an identity element for logand because its binary representation consists entirely of ones. If logand is passed just one argument, it returns that argument.
                   ;                28-bit binary values

(logand 14 13)     ; 14  =  0000  0000 0000  0000 0000  0000 1110
                   ; 13  =  0000  0000 0000  0000 0000  0000 1101
     => 12         ; 12  =  0000  0000 0000  0000 0000  0000 1100

(logand 14 13 4)   ; 14  =  0000  0000 0000  0000 0000  0000 1110
                   ; 13  =  0000  0000 0000  0000 0000  0000 1101
                   ;  4  =  0000  0000 0000  0000 0000  0000 0100
     => 4          ;  4  =  0000  0000 0000  0000 0000  0000 0100

(logand)
     => -1         ; -1  =  1111  1111 1111  1111 1111  1111 1111
Function: logior &rest ints-or-markers
This function returns the "inclusive or" of its arguments: the nth bit is set in the result if, and only if, the nth bit is set in at least one of the arguments. If there are no arguments, the result is zero, which is an identity element for this operation. If logior is passed just one argument, it returns that argument.
                   ;               28-bit binary values

(logior 12 5)      ; 12  =  0000  0000 0000  0000 0000  0000 1100
                   ;  5  =  0000  0000 0000  0000 0000  0000 0101
     => 13         ; 13  =  0000  0000 0000  0000 0000  0000 1101

(logior 12 5 7)    ; 12  =  0000  0000 0000  0000 0000  0000 1100
                   ;  5  =  0000  0000 0000  0000 0000  0000 0101
                   ;  7  =  0000  0000 0000  0000 0000  0000 0111
     => 15         ; 15  =  0000  0000 0000  0000 0000  0000 1111
Function: logxor &rest ints-or-markers
This function returns the "exclusive or" of its arguments: the nth bit is set in the result if, and only if, the nth bit is set in an odd number of the arguments. If there are no arguments, the result is 0, which is an identity element for this operation. If logxor is passed just one argument, it returns that argument.
                   ;               28-bit binary values

(logxor 12 5)      ; 12  =  0000  0000 0000  0000 0000  0000 1100
                   ;  5  =  0000  0000 0000  0000 0000  0000 0101
     => 9          ;  9  =  0000  0000 0000  0000 0000  0000 1001

(logxor 12 5 7)    ; 12  =  0000  0000 0000  0000 0000  0000 1100
                   ;  5  =  0000  0000 0000  0000 0000  0000 0101
                   ;  7  =  0000  0000 0000  0000 0000  0000 0111
     => 14         ; 14  =  0000  0000 0000  0000 0000  0000 1110
Function: lognot integer
This function returns the logical complement of its argument: the nth bit is one in the result if, and only if, the nth bit is zero in integer, and vice-versa.
(lognot 5)
     => -6
;;  5  =  0000  0000 0000  0000 0000  0000 0101
;; becomes
;; -6  =  1111  1111 1111  1111 1111  1111 1010
Standard Mathematical Functions

These mathematical functions allow integers as well as floating point numbers as arguments.

Function: sin arg

Function: cos arg

Function: tan arg
These are the ordinary trigonometric functions, with argument measured in radians.

Function: asin arg
The value of (asin arg) is a number between -pi/2 and pi/2 (inclusive) whose sine is arg; if, however, arg is out of range (outside [-1, 1]), then the result is a NaN.

Function: acos arg
The value of (acos arg) is a number between 0 and pi (inclusive) whose cosine is arg; if, however, arg is out of range (outside [-1, 1]), then the result is a NaN.

Function: atan arg
The value of (atan arg) is a number between -pi/2 and pi/2 (exclusive) whose tangent is arg.

Function: exp arg
This is the exponential function; it returns to the power arg. is a fundamental mathematical constant also called the base of natural logarithms.

Function: log arg &optional base
This function returns the logarithm of arg, with base base. If you don't specify base, the base is used. If arg is negative, the result is a NaN.

Function: log10 arg
This function returns the logarithm of arg, with base 10. If arg is negative, the result is a NaN. (log10 x) == (log x 10), at least approximately.

Function: expt x y
This function returns x raised to power y. If both arguments are integers and y is positive, the result is an integer; in this case, it is truncated to fit the range of possible integer values.

Function: sqrt arg
This returns the square root of arg. If arg is negative, the value is a NaN.

Random Numbers

A deterministic computer program cannot generate true random numbers. For most purposes, pseudo-random numbers suffice. A series of pseudo-random numbers is generated in a deterministic fashion. The numbers are not truly random, but they have certain properties that mimic a random series. For example, all possible values occur equally often in a pseudo-random series.

In Emacs, pseudo-random numbers are generated from a "seed" number. Starting from any given seed, the random function always generates the same sequence of numbers. Emacs always starts with the same seed value, so the sequence of values of random is actually the same in each Emacs run! For example, in one operating system, the first call to (random) after you start Emacs always returns -1457731, and the second one always returns -7692030. This repeatability is helpful for debugging.

If you want truly unpredictable random numbers, execute (random t). This chooses a new seed based on the current time of day and on Emacs's process ID number.

Function: random &optional limit
This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers.

If limit is a positive integer, the value is chosen to be nonnegative and less than limit.

If limit is t, it means to choose a new seed based on the current time of day and on Emacs's process ID number.

On some machines, any integer representable in Lisp may be the result of random. On other machines, the result can never be larger than a certain maximum or less than a certain (negative) minimum.
Strings and Characters

A string in Emacs Lisp is an array that contains an ordered sequence of characters. Strings are used as names of symbols, buffers, and files, to send messages to users, to hold text being copied between buffers, and for many other purposes. Because strings are so important, Emacs Lisp has many functions expressly for manipulating them. Emacs Lisp programs use strings more often than individual characters.

See section Putting Keyboard Events in Strings, for special considerations for strings of keyboard character events.

String and Character Basics

Strings in Emacs Lisp are arrays that contain an ordered sequence of characters. Characters are represented in Emacs Lisp as integers; whether an integer is a character or not is determined only by how it is used. Thus, strings really contain integers.

The length of a string (like any array) is fixed, and cannot be altered once the string exists. Strings in Lisp are not terminated by a distinguished character code. (By contrast, strings in C are terminated by a character with ASCII code 0.)

Since strings are arrays, and therefore sequences as well, you can operate on them with the general array and sequence functions. (See section Sequences, Arrays, and Vectors.) For example, you can access or change individual characters in a string using the functions aref and aset (see section Functions that Operate on Arrays).

There are two text representations for non-ASCII characters in Emacs strings (and in buffers): unibyte and multibyte (see section Text Representations). ASCII characters always occupy one byte in a string; in fact, there is no real difference between the two representation for a string which is all ASCII. For most Lisp programming, you don't need to be concerned with these two representations.

Sometimes key sequences are represented as strings. When a string is a key sequence, string elements in the range 128 to 255 represent meta characters (which are extremely large integers) rather than character codes in the range 128 to 255.

Strings cannot hold characters that have the hyper, super or alt modifiers; they can hold ASCII control characters, but no other control characters. They do not distinguish case in ASCII control characters. If you want to store such characters in a sequence, such as a key sequence, you must use a vector instead of a string. See section Character Type, for more information about representation of meta and other modifiers for keyboard input characters.

Strings are useful for holding regular expressions. You can also match regular expressions against strings (see section Regular Expression Searching). The functions match-string (see section Simple Match Data Access) and replace-match (see section Replacing the Text That Matched) are useful for decomposing and modifying strings based on regular expression matching.

Like a buffer, a string can contain text properties for the characters in it, as well as the characters themselves. See section Text Properties. All the Lisp primitives that copy text from strings to buffers or other strings also copy the properties of the characters being copied.

See section Text, for information about functions that display strings or copy them into buffers. See section Character Type, and section String Type, for information about the syntax of characters and strings. See section Non-ASCII Characters, for functions to convert between text representations and encode and decode character codes.

The Predicates for Strings

For more information about general sequence and array predicates, see section Sequences, Arrays, and Vectors, and section Arrays.

Function: stringp object
This function returns t if object is a string, nil otherwise.

Function: char-or-string-p object
This function returns t if object is a string or a character (i.e., an integer), nil otherwise.

Creating Strings

The following functions create strings, either from scratch, or by putting strings together, or by taking them apart.

Function: make-string count character
This function returns a string made up of count repetitions of character. If count is negative, an error is signaled.
(make-string 5 ?x)
     => "xxxxx"
(make-string 0 ?x)
     => ""
Other functions to compare with this one include char-to-string (see section Conversion of Characters and Strings), make-vector (see section Vectors), and make-list (see section Building Cons Cells and Lists).

Function: string &rest characters
This returns a string containing the characters characters.
(string ?a ?b ?c)
     => "abc"
Function: substring string start &optional end
This function returns a new string which consists of those characters from string in the range from (and including) the character at the index start up to (but excluding) the character at the index end. The first character is at index zero.
(substring "abcdefg" 0 3)
     => "abc"
Here the index for `a' is 0, the index for `b' is 1, and the index for `c' is 2. Thus, three letters, `abc', are copied from the string "abcdefg". The index 3 marks the character position up to which the substring is copied. The character whose index is 3 is actually the fourth character in the string.

A negative number counts from the end of the string, so that -1 signifies the index of the last character of the string. For example:
(substring "abcdefg" -3 -1)
     => "ef"
In this example, the index for `e' is -3, the index for `f' is -2, and the index for `g' is -1. Therefore, `e' and `f' are included, and `g' is excluded.

When nil is used as an index, it stands for the length of the string. Thus,
(substring "abcdefg" -3 nil)
     => "efg"
Omitting the argument end is equivalent to specifying nil. It follows that (substring string 0) returns a copy of all of string.
(substring "abcdefg" 0)
     => "abcdefg"
But we recommend copy-sequence for this purpose (see section Sequences).

If the characters copied from string have text properties, the properties are copied into the new string also. See section Text Properties.

substring also allows vectors for the first argument. For example:
(substring [a b (c) "d"] 1 3)
     => [b (c)]
A wrong-type-argument error is signaled if either start or end is not an integer or nil. An args-out-of-range error is signaled if start indicates a character following end, or if either integer is out of range for string.

Contrast this function with buffer-substring (see section Examining Buffer Contents), which returns a string containing a portion of the text in the current buffer. The beginning of a string is at index 0, but the beginning of a buffer is at index 1.

Function: concat &rest sequences
This function returns a new string consisting of the characters in the arguments passed to it (along with their text properties, if any). The arguments may be strings, lists of numbers, or vectors of numbers; they are not themselves changed. If concat receives no arguments, it returns an empty string.
(concat "abc" "-def")
     => "abc-def"
(concat "abc" (list 120 121) [122])
     => "abcxyz"
;; nil is an empty sequence.
(concat "abc" nil "-def")
     => "abc-def"
(concat "The " "quick brown " "fox.")
     => "The quick brown fox."
(concat)
     => ""
The concat function always constructs a new string that is not eq to any existing string.

When an argument is an integer (not a sequence of integers), it is converted to a string of digits making up the decimal printed representation of the integer. Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now! The proper way to convert an integer to a decimal number in this way is with format (see section Formatting Strings) or number-to-string (see section Conversion of Characters and Strings).
(concat 137)
     => "137"
(concat 54 321)
     => "54321"
For information about other concatenation functions, see the description of mapconcat in section Mapping Functions, vconcat in section Vectors, and append in section Building Cons Cells and Lists.

Function: split-string string separators
Split string into substrings in between matches for the regular expression separators. Each match for separators defines a splitting point; the substrings between the splitting points are made into a list, which is the value. If separators is nil (or omitted), the default is "[ \f\t\n\r\v]+".

For example,
(split-string "Soup is good food" "o")
=> ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o+")
=> ("S" "up is g" "d f" "d")
When there is a match adjacent to the beginning or end of the string, this does not cause a null string to appear at the beginning or end of the list:
(split-string "out to moo" "o+")
=> ("ut t" " m")
Empty matches do count, when not adjacent to another match:
(split-string "Soup is good food" "o*")
=>("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
(split-string "Nice doggy!" "")
=>("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
Modifying Strings

The most basic way to alter the contents of an existing string is with aset (see section Functions that Operate on Arrays). (aset string idx char) stores char into string at index idx. Each character occupies one or more bytes, and if char needs a different number of bytes from the character already present at that index, aset signals an error.

A more powerful function is store-substring:

Function: store-substring string idx obj
This function alters part of the contents of the string string, by storing obj starting at index idx. The argument obj may be either a character or a (smaller) string.

Since it is impossible to change the length of an existing string, it is an error if obj doesn't fit within string's actual length, of if any new character requires a different number of bytes from the character currently present at that point in string.

Comparison of Characters and Strings

Function: char-equal character1 character2
This function returns t if the arguments represent the same character, nil otherwise. This function ignores differences in case if case-fold-search is non-nil.
(char-equal ?x ?x)
     => t
(let ((case-fold-search nil))
  (char-equal ?x ?X))
     => nil
Function: string= string1 string2
This function returns t if the characters of the two strings match exactly; case is significant.
(string= "abc" "abc")
     => t
(string= "abc" "ABC")
     => nil
(string= "ab" "ABC")
     => nil
The function string= ignores the text properties of the two strings. When equal (see section Equality Predicates) compares two strings, it uses string=.

If the strings contain non-ASCII characters, and one is unibyte while the other is multibyte, then they cannot be equal. See section Text Representations.

Function: string-equal string1 string2
string-equal is another name for string=.

Function: string< string1 string2
This function compares two strings a character at a time. First it scans both the strings at once to find the first pair of corresponding characters that do not match. If the lesser character of those two is the character from string1, then string1 is less, and this function returns t. If the lesser character is the one from string2, then string1 is greater, and this function returns nil. If the two strings match entirely, the value is nil.

Pairs of characters are compared according to their character codes. Keep in mind that lower case letters have higher numeric values in the ASCII character set than their upper case counterparts; digits and many punctuation characters have a lower numeric value than upper case letters. An ASCII character is less than any non-ASCII character; a unibyte non-ASCII character is always less than any multibyte non-ASCII character (see section Text Representations).
(string< "abc" "abd")
     => t
(string< "abd" "abc")
     => nil
(string< "123" "abc")
     => t
When the strings have different lengths, and they match up to the length of string1, then the result is t. If they match up to the length of string2, the result is nil. A string of no characters is less than any other string.
(string< "" "abc")
     => t
(string< "ab" "abc")
     => t
(string< "abc" "")
     => nil
(string< "abc" "ab")
     => nil
(string< "" "")
     => nil
Function: string-lessp string1 string2
string-lessp is another name for string<.

Function: compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
This function compares a specified part of string1 with a specified part of string2. The specified part of string1 runs from index start1 up to index end1 (default, the end of the string). The specified part of string2 runs from index start2 up to index end2 (default, the end of the string).

The strings are both converted to multibyte for the comparison (see section Text Representations) so that a unibyte string can be equal to a multibyte string. If ignore-case is non-nil, then case is ignored, so that upper case letters can be equal to lower case letters.

If the specified portions of the two strings match, the value is t. Otherwise, the value is an integer which indicates how many leading characters agree, and which string is less. Its absolute value is one plus the number of characters that agree at the beginning of the two strings. The sign is negative if string1 (or its specified portion) is less.

Function: assoc-ignore-case key alist
This function works like assoc, except that key must be a string, and comparison is done using compare-strings. Case differences are ignored in this comparison.

Function: assoc-ignore-representation key alist
This function works like assoc, except that key must be a string, and comparison is done using compare-strings. Case differences are significant.

See also compare-buffer-substrings in section Comparing Text, for a way to compare text in buffers. The function string-match, which matches a regular expression against a string, can be used for a kind of string comparison; see section Regular Expression Searching.

Conversion of Characters and Strings

This section describes functions for conversions between characters, strings and integers. format and prin1-to-string (see section Output Functions) can also convert Lisp objects into strings. read-from-string (see section Input Functions) can "convert" a string representation of a Lisp object into an object. The functions string-make-multibyte and string-make-unibyte convert the text representation of a string (see section Converting Text Representations).

See section Documentation, for functions that produce textual descriptions of text characters and general input events (single-key-description and text-char-description). These functions are used primarily for making help messages.

Function: char-to-string character
This function returns a new string containing one character, character. This function is semi-obsolete because the function string is more general. See section Creating Strings.

Function: string-to-char string
This function returns the first character in string. If the string is empty, the function returns 0. The value is also 0 when the first character of string is the null character, ASCII code 0.
(string-to-char "ABC")
     => 65
(string-to-char "xyz")
     => 120
(string-to-char "")
     => 0
(string-to-char "\000")
     => 0
This function may be eliminated in the future if it does not seem useful enough to retain.

Function: number-to-string number
This function returns a string consisting of the printed representation of number, which may be an integer or a floating point number. The value starts with a sign if the argument is negative.
(number-to-string 256)
     => "256"
(number-to-string -23)
     => "-23"
(number-to-string -23.5)
     => "-23.5"
int-to-string is a semi-obsolete alias for this function.

See also the function format in section Formatting Strings.

Function: string-to-number string &optional base
This function returns the numeric value of the characters in string. If base is non-nil, integers are converted in that base. If base is nil, then base ten is used. Floating point conversion always uses base ten; we have not implemented other radices for floating point numbers, because that would be much more work and does not seem useful.

The parsing skips spaces and tabs at the beginning of string, then reads as much of string as it can interpret as a number. (On some systems it ignores other whitespace at the beginning, not just spaces and tabs.) If the first character after the ignored whitespace is not a digit or a plus or minus sign, this function returns 0.
(string-to-number "256")
     => 256
(string-to-number "25 is a perfect square.")
     => 25
(string-to-number "X256")
     => 0
(string-to-number "-4.5")
     => -4.5
string-to-int is an obsolete alias for this function.

Here are some other functions that can convert to or from a string:

concat
concat can convert a vector or a list into a string. See section Creating Strings.
vconcat
vconcat can convert a string into a vector. See section Functions for Vectors.
append
append can convert a string into a list. See section Building Cons Cells and Lists.
Formatting Strings

Formatting means constructing a string by substitution of computed values at various places in a constant string. This string controls how the other values are printed as well as where they appear; it is called a format string.

Formatting is often useful for computing messages to be displayed. In fact, the functions message and error provide the same formatting feature described here; they differ from format only in how they use the result of formatting.

Function: format string &rest objects
This function returns a new string that is made by copying string and then replacing any format specification in the copy with encodings of the corresponding objects. The arguments objects are the computed values to be formatted.

A format specification is a sequence of characters beginning with a `%'. Thus, if there is a `%d' in string, the format function replaces it with the printed representation of one of the values to be formatted (one of the arguments objects). For example:
(format "The value of fill-column is %d." fill-column)
     => "The value of fill-column is 72."
If string contains more than one format specification, the format specifications correspond with successive values from objects. Thus, the first format specification in string uses the first such value, the second format specification uses the second such value, and so on. Any extra format specifications (those for which there are no corresponding values) cause unpredictable behavior. Any extra values to be formatted are ignored.

Certain format specifications require values of particular types. If you supply a value that doesn't fit the requirements, an error is signaled.

Here is a table of valid format specifications:

`%s'
Replace the specification with the printed representation of the object, made without quoting (that is, using princ, not prin1---see section Output Functions). Thus, strings are represented by their contents alone, with no `"' characters, and symbols appear without `\' characters. If there is no corresponding object, the empty string is used.
`%S'
Replace the specification with the printed representation of the object, made with quoting (that is, using prin1---see section Output Functions). Thus, strings are enclosed in `"' characters, and `\' characters appear where necessary before special characters. If there is no corresponding object, the empty string is used.
`%o'
Replace the specification with the base-eight representation of an integer.
`%d'
Replace the specification with the base-ten representation of an integer.
`%x'
Replace the specification with the base-sixteen representation of an integer.
`%c'
Replace the specification with the character which is the value given.
`%e'
Replace the specification with the exponential notation for a floating point number.
`%f'
Replace the specification with the decimal-point notation for a floating point number.
`%g'
Replace the specification with notation for a floating point number, using either exponential notation or decimal-point notation, whichever is shorter.
`%%'
A single `%' is placed in the string. This format specification is unusual in that it does not use a value. For example, (format "%% %d" 30) returns "% 30".
Any other format character results in an `Invalid format operation' error.

Here are several examples:
(format "The name of this buffer is %s." (buffer-name))
     => "The name of this buffer is strings.texi."

(format "The buffer object prints as %s." (current-buffer))
     => "The buffer object prints as strings.texi."

(format "The octal value of %d is %o,
         and the hex value is %x." 18 18 18)
     => "The octal value of 18 is 22,
         and the hex value is 12."
All the specification characters allow an optional numeric prefix between the `%' and the character. The optional numeric prefix defines the minimum width for the object. If the printed representation of the object contains fewer characters than this, then it is padded. The padding is on the left if the prefix is positive (or starts with zero) and on the right if the prefix is negative. The padding character is normally a space, but if the numeric prefix starts with a zero, zeros are used for padding. Here are some examples of padding:
(format "%06d is padded on the left with zeros" 123)
     => "000123 is padded on the left with zeros"

(format "%-6d is padded on the right" 123)
     => "123    is padded on the right"
format never truncates an object's printed representation, no matter what width you specify. Thus, you can use a numeric prefix to specify a minimum spacing between columns with no risk of losing information.

In the following three examples, `%7s' specifies a minimum width of 7. In the first case, the string inserted in place of `%7s' has only 3 letters, so 4 blank spaces are inserted for padding. In the second case, the string "specification" is 13 letters wide but is not truncated. In the third case, the padding is on the right.
(format "The word `%7s' actually has %d letters in it."
        "foo" (length "foo"))
     => "The word `    foo' actually has 3 letters in it."

(format "The word `%7s' actually has %d letters in it."
        "specification" (length "specification"))
     => "The word `specification' actually has 13 letters in it."

(format "The word `%-7s' actually has %d letters in it."
        "foo" (length "foo"))
     => "The word `foo    ' actually has 3 letters in it."
Case Conversion in Lisp

The character case functions change the case of single characters or of the contents of strings. The functions normally convert only alphabetic characters (the letters `A' through `Z' and `a' through `z', as well as non-ASCII letters); other characters are not altered. (You can specify a different case conversion mapping by specifying a case table---see section The Case Table.)

These functions do not modify the strings that are passed to them as arguments.

The examples below use the characters `X' and `x' which have ASCII codes 88 and 120 respectively.

Function: downcase string-or-char
This function converts a character or a string to lower case.

When the argument to downcase is a string, the function creates and returns a new string in which each letter in the argument that is upper case is converted to lower case. When the argument to downcase is a character, downcase returns the corresponding lower case character. This value is an integer. If the original character is lower case, or is not a letter, then the value equals the original character.
(downcase "The cat in the hat")
     => "the cat in the hat"

(downcase ?X)
     => 120
Function: upcase string-or-char
This function converts a character or a string to upper case.

When the argument to upcase is a string, the function creates and returns a new string in which each letter in the argument that is lower case is converted to upper case.

When the argument to upcase is a character, upcase returns the corresponding upper case character. This value is an integer. If the original character is upper case, or is not a letter, then the value equals the original character.
(upcase "The cat in the hat")
     => "THE CAT IN THE HAT"

(upcase ?x)
     => 88
Function: capitalize string-or-char
This function capitalizes strings or characters. If string-or-char is a string, the function creates and returns a new string, whose contents are a copy of string-or-char in which each word has been capitalized. This means that the first character of each word is converted to upper case, and the rest are converted to lower case.

The definition of a word is any sequence of consecutive characters that are assigned to the word constituent syntax class in the current syntax table (See section Table of Syntax Classes).

When the argument to capitalize is a character, capitalize has the same result as upcase.
(capitalize "The cat in the hat")
     => "The Cat In The Hat"

(capitalize "THE 77TH-HATTED CAT")
     => "The 77th-Hatted Cat"

(capitalize ?x)
     => 88
Function: upcase-initials string
This function capitalizes the initials of the words in string. without altering any letters other than the initials. It returns a new string whose contents are a copy of string, in which each word has been converted to upper case.

The definition of a word is any sequence of consecutive characters that are assigned to the word constituent syntax class in the current syntax table (See section Table of Syntax Classes).
(upcase-initials "The CAT in the hAt")
     => "The CAT In The HAt"
See section Comparison of Characters and Strings, for functions that compare strings; some of them ignore case differences, or can optionally ignore case differences.

The Case Table

You can customize case conversion by installing a special case table. A case table specifies the mapping between upper case and lower case letters. It affects both the case conversion functions for Lisp objects (see the previous section) and those that apply to text in the buffer (see section Case Changes). Each buffer has a case table; there is also a standard case table which is used to initialize the case table of new buffers.

A case table is a char-table (see section Char-Tables) whose subtype is case-table. This char-table maps each character into the corresponding lower case character. It has three extra slots, which hold related tables:

upcase
The upcase table maps each character into the corresponding upper case character.
canonicalize
The canonicalize table maps all of a set of case-related characters into a particular member of that set.
equivalences
The equivalences table maps each one of a set of case-related characters into the next character in that set.
In simple cases, all you need to specify is the mapping to lower-case; the three related tables will be calculated automatically from that one.

For some languages, upper and lower case letters are not in one-to-one correspondence. There may be two different lower case letters with the same upper case equivalent. In these cases, you need to specify the maps for both lower case and upper case.

The extra table canonicalize maps each character to a canonical equivalent; any two characters that are related by case-conversion have the same canonical equivalent character. For example, since `a' and `A' are related by case-conversion, they should have the same canonical equivalent character (which should be either `a' for both of them, or `A' for both of them).

The extra table equivalences is a map that cyclicly permutes each equivalence class (of characters with the same canonical equivalent). (For ordinary ASCII, this would map `a' into `A' and `A' into `a', and likewise for each set of equivalent characters.)

When you construct a case table, you can provide nil for canonicalize; then Emacs fills in this slot from the lower case and upper case mappings. You can also provide nil for equivalences; then Emacs fills in this slot from canonicalize. In a case table that is actually in use, those components are non-nil. Do not try to specify equivalences without also specifying canonicalize.

Here are the functions for working with case tables:

Function: case-table-p object
This predicate returns non-nil if object is a valid case table.

Function: set-standard-case-table table
This function makes table the standard case table, so that it will be used in any buffers created subsequently.

Function: standard-case-table
This returns the standard case table.

Function: current-case-table
This function returns the current buffer's case table.

Function: set-case-table table
This sets the current buffer's case table to table.

The following three functions are convenient subroutines for packages that define non-ASCII character sets. They modify the specified case table case-table; they also modify the standard syntax table. See section Syntax Tables. Normally you would use these functions to change the standard case table.

Function: set-case-syntax-pair uc lc case-table
This function specifies a pair of corresponding letters, one upper case and one lower case.

Function: set-case-syntax-delims l r case-table
This function makes characters l and r a matching pair of case-invariant delimiters.

Function: set-case-syntax char syntax case-table
This function makes char case-invariant, with syntax syntax.

Command: describe-buffer-case-table
This command displays a description of the contents of the current buffer's case table.

Lists

A list represents a sequence of zero or more elements (which may be any Lisp objects). The important difference between lists and vectors is that two or more lists can share part of their structure; in addition, you can insert or delete elements in a list without copying the whole list.

Lists and Cons Cells

Lists in Lisp are not a primitive data type; they are built up from cons cells. A cons cell is a data object that represents an ordered pair. It holds, or "points to," two Lisp objects, one labeled as the CAR, and the other labeled as the CDR. These names are traditional; see section Cons Cell and List Types. CDR is pronounced "could-er."

A list is a series of cons cells chained together, one cons cell per element of the list. By convention, the CARs of the cons cells are the elements of the list, and the CDRs are used to chain the list: the CDR of each cons cell is the following cons cell. The CDR of the last cons cell is nil. This asymmetry between the CAR and the CDR is entirely a matter of convention; at the level of cons cells, the CAR and CDR slots have the same characteristics.

Because most cons cells are used as part of lists, the phrase list structure has come to mean any structure made out of cons cells.

The symbol nil is considered a list as well as a symbol; it is the list with no elements. For convenience, the symbol nil is considered to have nil as its CDR (and also as its CAR).

The CDR of any nonempty list l is a list containing all the elements of l except the first.

Lists as Linked Pairs of Boxes

A cons cell can be illustrated as a pair of boxes. The first box represents the CAR and the second box represents the CDR. Here is an illustration of the two-element list, (tulip lily), made from two cons cells:
 ---------------         ---------------
| car   | cdr   |       | car   | cdr   |
| tulip |   o---------->| lily  |  nil  |
|       |       |       |       |       |
 ---------------         ---------------
Each pair of boxes represents a cons cell. Each box "refers to", "points to" or "contains" a Lisp object. (These terms are synonymous.) The first box, which describes the CAR of the first cons cell, contains the symbol tulip. The arrow from the CDR box of the first cons cell to the second cons cell indicates that the CDR of the first cons cell is the second cons cell.

The same list can be illustrated in a different sort of box notation like this:
    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> tulip    --> lily
Here is a more complex illustration, showing the three-element list, ((pine needles) oak maple), the first element of which is a two-element list:
    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
     |             --> oak      --> maple
     |
     |     --- ---      --- ---
      --> |   |   |--> |   |   |--> nil
           --- ---      --- ---
            |            |
            |            |
             --> pine     --> needles
The same list represented in the first box notation looks like this:
 --------------       --------------       --------------
| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
|   o   |   o------->| oak   |   o------->| maple |  nil |
|   |   |      |     |       |      |     |       |      |
 -- | ---------       --------------       --------------
    |
    |
    |        --------------       ----------------
    |       | car   | cdr  |     | car     | cdr  |
     ------>| pine  |   o------->| needles |  nil |
            |       |      |     |         |      |
             --------------       ----------------
See section Cons Cell and List Types, for the read and print syntax of cons cells and lists, and for more "box and arrow" illustrations of lists.

Predicates on Lists

The following predicates test whether a Lisp object is an atom, is a cons cell or is a list, or whether it is the distinguished object nil. (Many of these predicates can be defined in terms of the others, but they are used so often that it is worth having all of them.)

Function: consp object
This function returns t if object is a cons cell, nil otherwise. nil is not a cons cell, although it is a list.

Function: atom object
This function returns t if object is an atom, nil otherwise. All objects except cons cells are atoms. The symbol nil is an atom and is also a list; it is the only Lisp object that is both.
(atom object) == (not (consp object))
Function: listp object
This function returns t if object is a cons cell or nil. Otherwise, it returns nil.
(listp '(1))
     => t
(listp '())
     => t
Function: nlistp object
This function is the opposite of listp: it returns t if object is not a list. Otherwise, it returns nil.
(listp object) == (not (nlistp object))
Function: null object
This function returns t if object is nil, and returns nil otherwise. This function is identical to not, but as a matter of clarity we use null when object is considered a list and not when it is considered a truth value (see not in section Constructs for Combining Conditions).
(null '(1))
     => nil
(null '())
     => t
Accessing Elements of Lists

Function: car cons-cell
This function returns the value pointed to by the first pointer of the cons cell cons-cell. Expressed another way, this function returns the CAR of cons-cell.

As a special case, if cons-cell is nil, then car is defined to return nil; therefore, any list is a valid argument for car. An error is signaled if the argument is not a cons cell or nil.
(car '(a b c))
     => a
(car '())
     => nil
Function: cdr cons-cell
This function returns the value pointed to by the second pointer of the cons cell cons-cell. Expressed another way, this function returns the CDR of cons-cell.

As a special case, if cons-cell is nil, then cdr is defined to return nil; therefore, any list is a valid argument for cdr. An error is signaled if the argument is not a cons cell or nil.
(cdr '(a b c))
     => (b c)
(cdr '())
     => nil
Function: car-safe object
This function lets you take the CAR of a cons cell while avoiding errors for other data types. It returns the CAR of object if object is a cons cell, nil otherwise. This is in contrast to car, which signals an error if object is not a list.
(car-safe object)
==
(let ((x object))
  (if (consp x)
      (car x)
    nil))
Function: cdr-safe object
This function lets you take the CDR of a cons cell while avoiding errors for other data types. It returns the CDR of object if object is a cons cell, nil otherwise. This is in contrast to cdr, which signals an error if object is not a list.
(cdr-safe object)
==
(let ((x object))
  (if (consp x)
      (cdr x)
    nil))
Function: nth n list
This function returns the nth element of list. Elements are numbered starting with zero, so the CAR of list is element number zero. If the length of list is n or less, the value is nil.

If n is negative, nth returns the first element of list.
(nth 2 '(1 2 3 4))
     => 3
(nth 10 '(1 2 3 4))
     => nil
(nth -3 '(1 2 3 4))
     => 1

(nth n x) == (car (nthcdr n x))
The function elt is similar, but applies to any kind of sequence. For historical reasons, it takes its arguments in the opposite order. See section Sequences.

Function: nthcdr n list
This function returns the nth CDR of list. In other words, it skips past the first n links of list and returns what follows.

If n is zero or negative, nthcdr returns all of list. If the length of list is n or less, nthcdr returns nil.
(nthcdr 1 '(1 2 3 4))
     => (2 3 4)
(nthcdr 10 '(1 2 3 4))
     => nil
(nthcdr -3 '(1 2 3 4))
     => (1 2 3 4)
Function: safe-length list
This function returns the length of list, with no risk of either an error or an infinite loop.

If list is not really a list, safe-length returns 0. If list is circular, it returns a finite value which is at least the number of distinct elements.

The most common way to compute the length of a list, when you are not worried that it may be circular, is with length. See section Sequences.

Function: caar cons-cell
This is the same as (car (car cons-cell)).

Function: cadr cons-cell
This is the same as (car (cdr cons-cell)) or (nth 1 cons-cell).

Function: cdar cons-cell
This is the same as (cdr (car cons-cell)).

Function: cddr cons-cell
This is the same as (cdr (cdr cons-cell)) or (nthcdr 2 cons-cell).

Building Cons Cells and Lists

Many functions build lists, as lists reside at the very heart of Lisp. cons is the fundamental list-building function; however, it is interesting to note that list is used more times in the source code for Emacs than cons.

Function: cons object1 object2
This function is the fundamental function used to build new list structure. It creates a new cons cell, making object1 the CAR, and object2 the CDR. It then returns the new cons cell. The arguments object1 and object2 may be any Lisp objects, but most often object2 is a list.
(cons 1 '(2))
     => (1 2)
(cons 1 '())
     => (1)
(cons 1 2)
     => (1 . 2)
cons is often used to add a single element to the front of a list. This is called consing the element onto the list. For example:
(setq list (cons newelt list))
Note that there is no conflict between the variable named list used in this example and the function named list described below; any symbol can serve both purposes.

Function: list &rest objects
This function creates a list with objects as its elements. The resulting list is always nil-terminated. If no objects are given, the empty list is returned.
(list 1 2 3 4 5)
     => (1 2 3 4 5)
(list 1 2 '(3 4 5) 'foo)
     => (1 2 (3 4 5) foo)
(list)
     => nil
Function: make-list length object
This function creates a list of length length, in which all the elements have the identical value object. Compare make-list with make-string (see section Creating Strings).
(make-list 3 'pigs)
     => (pigs pigs pigs)
(make-list 0 'pigs)
     => nil
Function: append &rest sequences
This function returns a list containing all the elements of sequences. The sequences may be lists, vectors, bool-vectors, or strings, but the last one should usually be a list. All arguments except the last one are copied, so none of the arguments is altered. (See nconc in section Functions that Rearrange Lists, for a way to join lists with no copying.)

More generally, the final argument to append may be any Lisp object. The final argument is not copied or converted; it becomes the CDR of the last cons cell in the new list. If the final argument is itself a list, then its elements become in effect elements of the result list. If the final element is not a list, the result is a "dotted list" since its final CDR is not nil as required in a true list.

The append function also allows integers as arguments. It converts them to strings of digits, making up the decimal print representation of the integer, and then uses the strings instead of the original integers. Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now! The proper way to convert an integer to a decimal number in this way is with format (see section Formatting Strings) or number-to-string (see section Conversion of Characters and Strings).

Here is an example of using append:
(setq trees '(pine oak))
     => (pine oak)
(setq more-trees (append '(maple birch) trees))
     => (maple birch pine oak)

trees
     => (pine oak)
more-trees
     => (maple birch pine oak)
(eq trees (cdr (cdr more-trees)))
     => t
You can see how append works by looking at a box diagram. The variable trees is set to the list (pine oak) and then the variable more-trees is set to the list (maple birch pine oak). However, the variable trees continues to refer to the original list:
more-trees                trees
|                           |
|     --- ---      --- ---   -> --- ---      --- ---
 --> |   |   |--> |   |   |--> |   |   |--> |   |   |--> nil
      --- ---      --- ---      --- ---      --- ---
       |            |            |            |
       |            |            |            |
        --> maple    -->birch     --> pine     --> oak
An empty sequence contributes nothing to the value returned by append. As a consequence of this, a final nil argument forces a copy of the previous argument:
trees
     => (pine oak)
(setq wood (append trees nil))
     => (pine oak)
wood
     => (pine oak)
(eq wood trees)
     => nil
This once was the usual way to copy a list, before the function copy-sequence was invented. See section Sequences, Arrays, and Vectors.

Here we show the use of vectors and strings as arguments to append:
(append [a b] "cd" nil)
     => (a b 99 100)
With the help of apply (see section Calling Functions), we can append all the lists in a list of lists:
(apply 'append '((a b c) nil (x y z) nil))
     => (a b c x y z)
If no sequences are given, nil is returned:
(append)
     => nil
Here are some examples where the final argument is not a list:
(append '(x y) 'z)
     => (x y . z)
(append '(x y) [z])
     => (x y . [z])
The second example shows that when the final argument is a sequence but not a list, the sequence's elements do not become elements of the resulting list. Instead, the sequence becomes the final CDR, like any other non-list final argument.

Function: reverse list
This function creates a new list whose elements are the elements of list, but in reverse order. The original argument list is not altered.
(setq x '(1 2 3 4))
     => (1 2 3 4)
(reverse x)
     => (4 3 2 1)
x
     => (1 2 3 4)
Modifying Existing List Structure

You can modify the CAR and CDR contents of a cons cell with the primitives setcar and setcdr. We call these "destructive" operations because they change existing list structure.

Common Lisp note: Common Lisp uses functions rplaca and rplacd to alter list structure; they change structure the same way as setcar and setcdr, but the Common Lisp functions return the cons cell while setcar and setcdr return the new CAR or CDR.

Altering List Elements with setcar

Changing the CAR of a cons cell is done with setcar. When used on a list, setcar replaces one element of a list with a different element.

Function: setcar cons object
This function stores object as the new CAR of cons, replacing its previous CAR. In other words, it changes the CAR slot of cons to point to object. It returns the value object. For example:
(setq x '(1 2))
     => (1 2)
(setcar x 4)
     => 4
x
     => (4 2)
When a cons cell is part of the shared structure of several lists, storing a new CAR into the cons changes one element of each of these lists. Here is an example:
;; Create two lists that are partly shared.
(setq x1 '(a b c))
     => (a b c)
(setq x2 (cons 'z (cdr x1)))
     => (z b c)

;; Replace the CAR of a shared link.
(setcar (cdr x1) 'foo)
     => foo
x1                           ; Both lists are changed.
     => (a foo c)
x2
     => (z foo c)

;; Replace the CAR of a link that is not shared.
(setcar x1 'baz)
     => baz
x1                           ; Only one list is changed.
     => (baz foo c)
x2
     => (z foo c)
Here is a graphical depiction of the shared structure of the two lists in the variables x1 and x2, showing why replacing b changes them both:
        --- ---        --- ---      --- ---
x1---> |   |   |----> |   |   |--> |   |   |--> nil
        --- ---        --- ---      --- ---
         |        -->   |            |
         |       |      |            |
          --> a  |       --> b        --> c
                 |
       --- ---   |
x2--> |   |   |--
       --- ---
        |
        |
         --> z
Here is an alternative form of box diagram, showing the same relationship:
x1:
 --------------       --------------       --------------
| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
|   a   |   o------->|   b   |   o------->|   c   |  nil |
|       |      |  -->|       |      |     |       |      |
 --------------  |    --------------       --------------
                 |
x2:              |
 --------------  |
| car   | cdr  | |
|   z   |   o----
|       |      |
 --------------
Altering the CDR of a List

The lowest-level primitive for modifying a CDR is setcdr:

Function: setcdr cons object
This function stores object as the new CDR of cons, replacing its previous CDR. In other words, it changes the CDR slot of cons to point to object. It returns the value object.

Here is an example of replacing the CDR of a list with a different list. All but the first element of the list are removed in favor of a different sequence of elements. The first element is unchanged, because it resides in the CAR of the list, and is not reached via the CDR.
(setq x '(1 2 3))
     => (1 2 3)
(setcdr x '(4))
     => (4)
x
     => (1 4)
You can delete elements from the middle of a list by altering the CDRs of the cons cells in the list. For example, here we delete the second element, b, from the list (a b c), by changing the CDR of the first cons cell:
(setq x1 '(a b c))
     => (a b c)
(setcdr x1 (cdr (cdr x1)))
     => (c)
x1
     => (a c)
Here is the result in box notation:
                   --------------------
                  |                    |
 --------------   |   --------------   |    --------------
| car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
|   a   |   o-----   |   b   |   o-------->|   c   |  nil |
|       |      |     |       |      |      |       |      |
 --------------       --------------        --------------
The second cons cell, which previously held the element b, still exists and its CAR is still b, but it no longer forms part of this list.

It is equally easy to insert a new element by changing CDRs:
(setq x1 '(a b c))
     => (a b c)
(setcdr x1 (cons 'd (cdr x1)))
     => (d b c)
x1
     => (a d b c)
Here is this result in box notation:
 --------------        -------------       -------------
| car  | cdr   |      | car  | cdr  |     | car  | cdr  |
|   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
|      |   |   |  |   |      |      |     |      |      |
 --------- | --   |    -------------       -------------
           |      |
     -----         --------
    |                      |
    |    ---------------   |
    |   | car   | cdr   |  |
     -->|   d   |   o------
        |       |       |
         ---------------
Functions that Rearrange Lists

Here are some functions that rearrange lists "destructively" by modifying the CDRs of their component cons cells. We call these functions "destructive" because they chew up the original lists passed to them as arguments, relinking their cons cells to form a new list that is the returned value.

The function delq in the following section is another example of destructive list manipulation.

Function: nconc &rest lists
This function returns a list containing all the elements of lists. Unlike append (see section Building Cons Cells and Lists), the lists are not copied. Instead, the last CDR of each of the lists is changed to refer to the following list. The last of the lists is not altered. For example:
(setq x '(1 2 3))
     => (1 2 3)
(nconc x '(4 5))
     => (1 2 3 4 5)
x
     => (1 2 3 4 5)
Since the last argument of nconc is not itself modified, it is reasonable to use a constant list, such as '(4 5), as in the above example. For the same reason, the last argument need not be a list:
(setq x '(1 2 3))
     => (1 2 3)
(nconc x 'z)
     => (1 2 3 . z)
x
     => (1 2 3 . z)
However, the other arguments (all but the last) must be lists.

A common pitfall is to use a quoted constant list as a non-last argument to nconc. If you do this, your program will change each time you run it! Here is what happens:
(defun add-foo (x)            ; We want this function to add
  (nconc '(foo) x))           ;   foo to the front of its arg.

(symbol-function 'add-foo)
     => (lambda (x) (nconc (quote (foo)) x))

(setq xx (add-foo '(1 2)))    ; It seems to work.
     => (foo 1 2)
(setq xy (add-foo '(3 4)))    ; What happened?
     => (foo 1 2 3 4)
(eq xx xy)
     => t

(symbol-function 'add-foo)
     => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
Function: nreverse list
This function reverses the order of the elements of list. Unlike reverse, nreverse alters its argument by reversing the CDRs in the cons cells forming the list. The cons cell that used to be the last one in list becomes the first cons cell of the value.

For example:
(setq x '(1 2 3 4))
     => (1 2 3 4)
x
     => (1 2 3 4)
(nreverse x)
     => (4 3 2 1)
;; The cons cell that was first is now last.
x
     => (1)
To avoid confusion, we usually store the result of nreverse back in the same variable which held the original list:
(setq x (nreverse x))
Here is the nreverse of our favorite example, (a b c), presented graphically:
Original list head:                       Reversed list:
 -------------        -------------        ------------
| car  | cdr  |      | car  | cdr  |      | car | cdr  |
|   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
|      |      |   |  |      |   |  |   |  |     |   |  |
 -------------    |   --------- | -    |   -------- | -
                  |             |      |            |
                   -------------        ------------
Function: sort list predicate
This function sorts list stably, though destructively, and returns the sorted list. It compares elements using predicate. A stable sort is one in which elements with equal sort keys maintain their relative order before and after the sort. Stability is important when successive sorts are used to order elements according to different criteria.

The argument predicate must be a function that accepts two arguments. It is called with two elements of list. To get an increasing order sort, the predicate should return t if the first element is "less than" the second, or nil if not.

The comparison function predicate must give reliable results for any given pair of arguments, at least within a single call to sort. It must be antisymmetric; that is, if a is less than b, b must not be less than a. It must be transitive---that is, if a is less than b, and b is less than c, then a must be less than c. If you use a comparison function which does not meet these requirements, the result of sort is unpredictable.

The destructive aspect of sort is that it rearranges the cons cells forming list by changing CDRs. A nondestructive sort function would create new cons cells to store the elements in their sorted order. If you wish to make a sorted copy without destroying the original, copy it first with copy-sequence and then sort.

Sorting does not change the CARs of the cons cells in list; the cons cell that originally contained the element a in list still has a in its CAR after sorting, but it now appears in a different position in the list due to the change of CDRs. For example:
(setq nums '(1 3 2 6 5 4 0))
     => (1 3 2 6 5 4 0)
(sort nums '<)
     => (0 1 2 3 4 5 6)
nums
     => (1 2 3 4 5 6)
Warning: Note that the list in nums no longer contains 0; this is the same cons cell that it was before, but it is no longer the first one in the list. Don't assume a variable that formerly held the argument now holds the entire sorted list! Instead, save the result of sort and use that. Most often we store the result back into the variable that held the original list:
(setq nums (sort nums '<))
See section Sorting Text, for more functions that perform sorting. See documentation in section Access to Documentation Strings, for a useful example of sort.

Using Lists as Sets

A list can represent an unordered mathematical set--simply consider a value an element of a set if it appears in the list, and ignore the order of the list. To form the union of two sets, use append (as long as you don't mind having duplicate elements). Other useful functions for sets include memq and delq, and their equal versions, member and delete.

Common Lisp note: Common Lisp has functions union (which avoids duplicate elements) and intersection for set operations, but GNU Emacs Lisp does not have them. You can write them in Lisp if you wish.

Function: memq object list
This function tests to see whether object is a member of list. If it is, memq returns a list starting with the first occurrence of object. Otherwise, it returns nil. The letter `q' in memq says that it uses eq to compare object against the elements of the list. For example:
(memq 'b '(a b c b a))
     => (b c b a)
(memq '(2) '((1) (2)))    ; (2) and (2) are not eq.
     => nil
Function: delq object list
This function destructively removes all elements eq to object from list. The letter `q' in delq says that it uses eq to compare object against the elements of the list, like memq.

When delq deletes elements from the front of the list, it does so simply by advancing down the list and returning a sublist that starts after those elements:
(delq 'a '(a b c)) == (cdr '(a b c))
When an element to be deleted appears in the middle of the list, removing it involves changing the CDRs (see section Altering the CDR of a List).
(setq sample-list '(a b c (4)))
     => (a b c (4))
(delq 'a sample-list)
     => (b c (4))
sample-list
     => (a b c (4))
(delq 'c sample-list)
     => (a b (4))
sample-list
     => (a b (4))
Note that (delq 'c sample-list) modifies sample-list to splice out the third element, but (delq 'a sample-list) does not splice anything--it just returns a shorter list. Don't assume that a variable which formerly held the argument list now has fewer elements, or that it still holds the original list! Instead, save the result of delq and use that. Most often we store the result back into the variable that held the original list:
(setq flowers (delq 'rose flowers))
In the following example, the (4) that delq attempts to match and the (4) in the sample-list are not eq:
(delq '(4) sample-list)
     => (a c (4))
The following two functions are like memq and delq but use equal rather than eq to compare elements. See section Equality Predicates.

Function: member object list
The function member tests to see whether object is a member of list, comparing members with object using equal. If object is a member, member returns a list starting with its first occurrence in list. Otherwise, it returns nil.

Compare this with memq:
(member '(2) '((1) (2)))  ; (2) and (2) are equal.
     => ((2))
(memq '(2) '((1) (2)))    ; (2) and (2) are not eq.
     => nil
;; Two strings with the same contents are equal.
(member "foo" '("foo" "bar"))
     => ("foo" "bar")
Function: delete object list
This function destructively removes all elements equal to object from list. It is to delq as member is to memq: it uses equal to compare elements with object, like member; when it finds an element that matches, it removes the element just as delq would. For example:
(delete '(2) '((2) (1) (2)))
     => ((1))
Common Lisp note: The functions member and delete in GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common Lisp versions do not use equal to compare elements.

See also the function add-to-list, in section How to Alter a Variable Value, for another way to add an element to a list stored in a variable.

Association Lists

An association list, or alist for short, records a mapping from keys to values. It is a list of cons cells called associations: the CAR of each cons cell is the key, and the CDR is the associated value.(1)

Here is an example of an alist. The key pine is associated with the value cones; the key oak is associated with acorns; and the key maple is associated with seeds.
'((pine . cones)
  (oak . acorns)
  (maple . seeds))
The associated values in an alist may be any Lisp objects; so may the keys. For example, in the following alist, the symbol a is associated with the number 1, and the string "b" is associated with the list (2 3), which is the CDR of the alist element:
((a . 1) ("b" 2 3))
Sometimes it is better to design an alist to store the associated value in the CAR of the CDR of the element. Here is an example:
'((rose red) (lily white) (buttercup yellow))
Here we regard red as the value associated with rose. One advantage of this kind of alist is that you can store other related information--even a list of other items--in the CDR of the CDR. One disadvantage is that you cannot use rassq (see below) to find the element containing a given value. When neither of these considerations is important, the choice is a matter of taste, as long as you are consistent about it for any given alist.

Note that the same alist shown above could be regarded as having the associated value in the CDR of the element; the value associated with rose would be the list (red).

Association lists are often used to record information that you might otherwise keep on a stack, since new associations may be added easily to the front of the list. When searching an association list for an association with a given key, the first one found is returned, if there is more than one.

In Emacs Lisp, it is not an error if an element of an association list is not a cons cell. The alist search functions simply ignore such elements. Many other versions of Lisp signal errors in such cases.

Note that property lists are similar to association lists in several respects. A property list behaves like an association list in which each key can occur only once. See section Property Lists, for a comparison of property lists and association lists.

Function: assoc key alist
This function returns the first association for key in alist. It compares key against the alist elements using equal (see section Equality Predicates). It returns nil if no association in alist has a CAR equal to key. For example:
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
     => ((pine . cones) (oak . acorns) (maple . seeds))
(assoc 'oak trees)
     => (oak . acorns)
(cdr (assoc 'oak trees))
     => acorns
(assoc 'birch trees)
     => nil
Here is another example, in which the keys and values are not symbols:
(setq needles-per-cluster
      '((2 "Austrian Pine" "Red Pine")
        (3 "Pitch Pine")
        (5 "White Pine")))

(cdr (assoc 3 needles-per-cluster))
     => ("Pitch Pine")
(cdr (assoc 2 needles-per-cluster))
     => ("Austrian Pine" "Red Pine")
The functions assoc-ignore-representation and assoc-ignore-case are much like assoc except using compare-strings to do the comparison. See section Comparison of Characters and Strings.

Function: rassoc value alist
This function returns the first association with value value in alist. It returns nil if no association in alist has a CDR equal to value.

rassoc is like assoc except that it compares the CDR of each alist association instead of the CAR. You can think of this as "reverse assoc", finding the key for a given value.

Function: assq key alist
This function is like assoc in that it returns the first association for key in alist, but it makes the comparison using eq instead of equal. assq returns nil if no association in alist has a CAR eq to key. This function is used more often than assoc, since eq is faster than equal and most alists use symbols as keys. See section Equality Predicates.
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
     => ((pine . cones) (oak . acorns) (maple . seeds))
(assq 'pine trees)
     => (pine . cones)
On the other hand, assq is not usually useful in alists where the keys may not be symbols:
(setq leaves
      '(("simple leaves" . oak)
        ("compound leaves" . horsechestnut)))

(assq "simple leaves" leaves)
     => nil
(assoc "simple leaves" leaves)
     => ("simple leaves" . oak)
Function: rassq value alist
This function returns the first association with value value in alist. It returns nil if no association in alist has a CDR eq to value.

rassq is like assq except that it compares the CDR of each alist association instead of the CAR. You can think of this as "reverse assq", finding the key for a given value.

For example:
(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))

(rassq 'acorns trees)
     => (oak . acorns)
(rassq 'spores trees)
     => nil
Note that rassq cannot search for a value stored in the CAR of the CDR of an element:
(setq colors '((rose red) (lily white) (buttercup yellow)))

(rassq 'white colors)
     => nil
In this case, the CDR of the association (lily white) is not the symbol white, but rather the list (white). This becomes clearer if the association is written in dotted pair notation:
(lily white) == (lily . (white))
Function: assoc-default key alist test default
This function searches alist for a match for key. For each element of alist, it compares the element (if it is an atom) or the element's CAR (if it is a cons) against key, by calling test with two arguments: the element or its CAR, and key. The arguments are passed in that order so that you can get useful results using string-match with an alist that contains regular expressions (see section Regular Expression Searching). If test is omitted or nil, equal is used for comparison.

If an alist element matches key by this criterion, then assoc-default returns a value based on this element. If the element is a cons, then the value is the element's CDR. Otherwise, the return value is default.

If no alist element matches key, assoc-default returns nil.

Function: copy-alist alist
This function returns a two-level deep copy of alist: it creates a new copy of each association, so that you can alter the associations of the new alist without changing the old one.
(setq needles-per-cluster
      '((2 . ("Austrian Pine" "Red Pine"))
        (3 . ("Pitch Pine"))
        (5 . ("White Pine"))))
=>
((2 "Austrian Pine" "Red Pine")
 (3 "Pitch Pine")
 (5 "White Pine"))

(setq copy (copy-alist needles-per-cluster))
=>
((2 "Austrian Pine" "Red Pine")
 (3 "Pitch Pine")
 (5 "White Pine"))

(eq needles-per-cluster copy)
     => nil
(equal needles-per-cluster copy)
     => t
(eq (car needles-per-cluster) (car copy))
     => nil
(cdr (car (cdr needles-per-cluster)))
     => ("Pitch Pine")
(eq (cdr (car (cdr needles-per-cluster)))
    (cdr (car (cdr copy))))
     => t
This example shows how copy-alist makes it possible to change the associations of one copy without affecting the other:
(setcdr (assq 3 copy) '("Martian Vacuum Pine"))
(cdr (assq 3 needles-per-cluster))
     => ("Pitch Pine")
Sequences, Arrays, and Vectors

Recall that the sequence type is the union of two other Lisp types: lists and arrays. In other words, any list is a sequence, and any array is a sequence. The common property that all sequences have is that each is an ordered collection of elements.

An array is a single primitive object that has a slot for each of its elements. All the elements are accessible in constant time, but the length of an existing array cannot be changed. Strings, vectors, char-tables and bool-vectors are the four types of arrays.

A list is a sequence of elements, but it is not a single primitive object; it is made of cons cells, one cell per element. Finding the nth element requires looking through n cons cells, so elements farther from the beginning of the list take longer to access. But it is possible to add elements to the list, or remove elements.

The following diagram shows the relationship between these types:
          _____________________________________________
         |                                             |
         |          Sequence                           |
         |  ______   ________________________________  |
         | |      | |                                | |
         | | List | |             Array              | |
         | |      | |    ________       ________     | |
         | |______| |   |        |     |        |    | |
         |          |   | Vector |     | String |    | |
         |          |   |________|     |________|    | |
         |          |  ____________   _____________  | |
         |          | |            | |             | | |
         |          | | Char-table | | Bool-vector | | |
         |          | |____________| |_____________| | |
         |          |________________________________| |
         |_____________________________________________|
The elements of vectors and lists may be any Lisp objects. The elements of strings are all characters.

Sequences

In Emacs Lisp, a sequence is either a list or an array. The common property of all sequences is that they are ordered collections of elements. This section describes functions that accept any kind of sequence.

Function: sequencep object
Returns t if object is a list, vector, or string, nil otherwise.

Function: length sequence
This function returns the number of elements in sequence. If sequence is a cons cell that is not a list (because the final CDR is not nil), a wrong-type-argument error is signaled.

See section Accessing Elements of Lists, for the related function safe-length.
(length '(1 2 3))
    => 3
(length ())
    => 0
(length "foobar")
    => 6
(length [1 2 3])
    => 3
(length (make-bool-vector 5 nil))
    => 5
Function: elt sequence index
This function returns the element of sequence indexed by index. Legitimate values of index are integers ranging from 0 up to one less than the length of sequence. If sequence is a list, then out-of-range values of index return nil; otherwise, they trigger an args-out-of-range error.
(elt [1 2 3 4] 2)
     => 3
(elt '(1 2 3 4) 2)
     => 3
;; We use string to show clearly which character elt returns.
(string (elt "1234" 2))
     => "3"
(elt [1 2 3 4] 4)
     error--> Args out of range: [1 2 3 4], 4
(elt [1 2 3 4] -1)
     error--> Args out of range: [1 2 3 4], -1
This function generalizes aref (see section Functions that Operate on Arrays) and nth (see section Accessing Elements of Lists).

Function: copy-sequence sequence
Returns a copy of sequence. The copy is the same type of object as the original sequence, and it has the same elements in the same order.

Storing a new element into the copy does not affect the original sequence, and vice versa. However, the elements of the new sequence are not copies; they are identical (eq) to the elements of the original. Therefore, changes made within these elements, as found via the copied sequence, are also visible in the original sequence.

If the sequence is a string with text properties, the property list in the copy is itself a copy, not shared with the original's property list. However, the actual values of the properties are shared. See section Text Properties.

See also append in section Building Cons Cells and Lists, concat in section Creating Strings, and vconcat in section Vectors, for others ways to copy sequences.
(setq bar '(1 2))
     => (1 2)
(setq x (vector 'foo bar))
     => [foo (1 2)]
(setq y (copy-sequence x))
     => [foo (1 2)]

(eq x y)
     => nil
(equal x y)
     => t
(eq (elt x 1) (elt y 1))
     => t

;; Replacing an element of one sequence.
(aset x 0 'quux)
x => [quux (1 2)]
y => [foo (1 2)]

;; Modifying the inside of a shared element.
(setcar (aref x 1) 69)
x => [quux (69 2)]
y => [foo (69 2)]
Arrays

An array object has slots that hold a number of other Lisp objects, called the elements of the array. Any element of an array may be accessed in constant time. In contrast, an element of a list requires access time that is proportional to the position of the element in the list.

Emacs defines four types of array, all one-dimensional: strings, vectors, bool-vectors and char-tables. A vector is a general array; its elements can be any Lisp objects. A string is a specialized array; its elements must be characters (i.e., integers between 0 and 255). Each type of array has its own read syntax. See section String Type, and section Vector Type.

All four kinds of array share these characteristics:

The first element of an array has index zero, the second element has index 1, and so on. This is called zero-origin indexing. For example, an array of four elements has indices 0, 1, 2, and 3.
The length of the array is fixed once you create it; you cannot change the length of an existing array.
The array is a constant, for evaluation--in other words, it evaluates to itself.
The elements of an array may be referenced or changed with the functions aref and aset, respectively (see section Functions that Operate on Arrays).

When you create an array, other than a char-table, you must specify its length. You cannot specify the length of a char-table, because that is determined by the range of character codes.

In principle, if you want an array of text characters, you could use either a string or a vector. In practice, we always choose strings for such applications, for four reasons:

They occupy one-fourth the space of a vector of the same elements.
Strings are printed in a way that shows the contents more clearly as text.
Strings can hold text properties. See section Text Properties.
Many of the specialized editing and I/O facilities of Emacs accept only strings. For example, you cannot insert a vector of characters into a buffer the way you can insert a string. See section Strings and Characters.

By contrast, for an array of keyboard input characters (such as a key sequence), a vector may be necessary, because many keyboard input characters are outside the range that will fit in a string. See section Key Sequence Input.

Functions that Operate on Arrays

In this section, we describe the functions that accept all types of arrays.

Function: arrayp object
This function returns t if object is an array (i.e., a vector, a string, a bool-vector or a char-table).
(arrayp [a])
     => t
(arrayp "asdf")
     => t
(arrayp (syntax-table))    ;; A char-table.
     => t
Function: aref array index
This function returns the indexth element of array. The first element is at index zero.
(setq primes [2 3 5 7 11 13])
     => [2 3 5 7 11 13]
(aref primes 4)
     => 11
(aref "abcdefg" 1)
     => 98           ; `b' is ASCII code 98.
See also the function elt, in section Sequences.

Function: aset array index object
This function sets the indexth element of array to be object. It returns object.
(setq w [foo bar baz])
     => [foo bar baz]
(aset w 0 'fu)
     => fu
w
     => [fu bar baz]

(setq x "asdfasfd")
     => "asdfasfd"
(aset x 3 ?Z)
     => 90
x
     => "asdZasfd"
If array is a string and object is not a character, a wrong-type-argument error results. If array is a string and object is character, but object does not use the same number of bytes as the character currently stored in (aref object index), that is also an error. See section Splitting Characters.

Function: fillarray array object
This function fills the array array with object, so that each element of array is object. It returns array.
(setq a [a b c d e f g])
     => [a b c d e f g]
(fillarray a 0)
     => [0 0 0 0 0 0 0]
a
     => [0 0 0 0 0 0 0]
(setq s "When in the course")
     => "When in the course"
(fillarray s ?-)
     => "------------------"
If array is a string and object is not a character, a wrong-type-argument error results.

The general sequence functions copy-sequence and length are often useful for objects known to be arrays. See section Sequences.

Vectors

Arrays in Lisp, like arrays in most languages, are blocks of memory whose elements can be accessed in constant time. A vector is a general-purpose array of specified length; its elements can be any Lisp objects. (By contrast, a string can hold only characters as elements.) Vectors in Emacs are used for obarrays (vectors of symbols), and as part of keymaps (vectors of commands). They are also used internally as part of the representation of a byte-compiled function; if you print such a function, you will see a vector in it.

In Emacs Lisp, the indices of the elements of a vector start from zero and count up from there.

Vectors are printed with square brackets surrounding the elements. Thus, a vector whose elements are the symbols a, b and a is printed as [a b a]. You can write vectors in the same way in Lisp input.

A vector, like a string or a number, is considered a constant for evaluation: the result of evaluating it is the same vector. This does not evaluate or even examine the elements of the vector. See section Self-Evaluating Forms.

Here are examples illustrating these principles:
(setq avector [1 two '(three) "four" [five]])
     => [1 two (quote (three)) "four" [five]]
(eval avector)
     => [1 two (quote (three)) "four" [five]]
(eq avector (eval avector))
     => t
Functions for Vectors

Here are some functions that relate to vectors:

Function: vectorp object
This function returns t if object is a vector.
(vectorp [a])
     => t
(vectorp "asdf")
     => nil
Function: vector &rest objects
This function creates and returns a vector whose elements are the arguments, objects.
(vector 'foo 23 [bar baz] "rats")
     => [foo 23 [bar baz] "rats"]
(vector)
     => []
Function: make-vector length object
This function returns a new vector consisting of length elements, each initialized to object.
(setq sleepy (make-vector 9 'Z))
     => [Z Z Z Z Z Z Z Z Z]
Function: vconcat &rest sequences
This function returns a new vector containing all the elements of the sequences. The arguments sequences may be any kind of arrays, including lists, vectors, or strings. If no sequences are given, an empty vector is returned.

The value is a newly constructed vector that is not eq to any existing vector.
(setq a (vconcat '(A B C) '(D E F)))
     => [A B C D E F]
(eq a (vconcat a))
     => nil
(vconcat)
     => []
(vconcat [A B C] "aa" '(foo (6 7)))
     => [A B C 97 97 foo (6 7)]
The vconcat function also allows byte-code function objects as arguments. This is a special feature to make it easy to access the entire contents of a byte-code function object. See section Byte-Code Function Objects.

The vconcat function also allows integers as arguments. It converts them to strings of digits, making up the decimal print representation of the integer, and then uses the strings instead of the original integers. Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now! The proper way to convert an integer to a decimal number in this way is with format (see section Formatting Strings) or number-to-string (see section Conversion of Characters and Strings).

For other concatenation functions, see mapconcat in section Mapping Functions, concat in section Creating Strings, and append in section Building Cons Cells and Lists.

The append function provides a way to convert a vector into a list with the same elements (see section Building Cons Cells and Lists):
(setq avector [1 two (quote (three)) "four" [five]])
     => [1 two (quote (three)) "four" [five]]
(append avector nil)
     => (1 two (quote (three)) "four" [five])
Char-Tables

A char-table is much like a vector, except that it is indexed by character codes. Any valid character code, without modifiers, can be used as an index in a char-table. You can access a char-table's elements with aref and aset, as with any array. In addition, a char-table can have extra slots to hold additional data not associated with particular character codes. Char-tables are constants when evaluated.

Each char-table has a subtype which is a symbol. The subtype has two purposes: to distinguish char-tables meant for different uses, and to control the number of extra slots. For example, display tables are char-tables with display-table as the subtype, and syntax tables are char-tables with syntax-table as the subtype. A valid subtype must have a char-table-extra-slots property which is an integer between 0 and 10. This integer specifies the number of extra slots in the char-table.

A char-table can have a parent. which is another char-table. If it does, then whenever the char-table specifies nil for a particular character c, it inherits the value specified in the parent. In other words, (aref char-table c) returns the value from the parent of char-table if char-table itself specifies nil.

A char-table can also have a default value. If so, then (aref char-table c) returns the default value whenever the char-table does not specify any other non-nil value.

Function: make-char-table subtype &optional init
Return a newly created char-table, with subtype subtype. Each element is initialized to init, which defaults to nil. You cannot alter the subtype of a char-table after the char-table is created.

There is no argument to specify the length of the char-table, because all char-tables have room for any valid character code as an index.

Function: char-table-p object
This function returns t if object is a char-table, otherwise nil.

Function: char-table-subtype char-table
This function returns the subtype symbol of char-table.

Function: set-char-table-default char-table new-default
This function sets the default value of char-table to new-default.

There is no special function to access the default value of a char-table. To do that, use (char-table-range char-table nil).

Function: char-table-parent char-table
This function returns the parent of char-table. The parent is always either nil or another char-table.

Function: set-char-table-parent char-table new-parent
This function sets the parent of char-table to new-parent.

Function: char-table-extra-slot char-table n
This function returns the contents of extra slot n of char-table. The number of extra slots in a char-table is determined by its subtype.

Function: set-char-table-extra-slot char-table n value
This function stores value in extra slot n of char-table.

A char-table can specify an element value for a single character code; it can also specify a value for an entire character set.

Function: char-table-range char-table range
This returns the value specified in char-table for a range of characters range. Here are the possibilities for range:

nil
Refers to the default value.
char
Refers to the element for character char (supposing char is a valid character code).
charset
Refers to the value specified for the whole character set charset (see section Character Sets).
generic-char
A generic character stands for a character set; specifying the generic character as argument is equivalent to specifying the character set name. See section Splitting Characters, for a description of generic characters.

Function: set-char-table-range char-table range value
This function sets the value in char-table for a range of characters range. Here are the possibilities for range:

nil
Refers to the default value.
t
Refers to the whole range of character codes.
char
Refers to the element for character char (supposing char is a valid character code).
charset
Refers to the value specified for the whole character set charset (see section Character Sets).
generic-char
A generic character stands for a character set; specifying the generic character as argument is equivalent to specifying the character set name. See section Splitting Characters, for a description of generic characters.

Function: map-char-table function char-table
This function calls function for each element of char-table. function is called with two arguments, a key and a value. The key is a possible range argument for char-table-range---either a valid character or a generic character--and the value is (char-table-range char-table key).

Overall, the key-value pairs passed to function describe all the values stored in char-table.

The return value is always nil; to make this function useful, function should have side effects. For example, here is how to examine each element of the syntax table:
(let (accumulator)
  (map-char-table
   #'(lambda (key value)
       (setq accumulator
             (cons (list key value) accumulator)))
   (syntax-table))
  accumulator)
=>
((475008 nil) (474880 nil) (474752 nil) (474624 nil)
 ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
Bool-vectors

A bool-vector is much like a vector, except that it stores only the values t and nil. If you try to store any non-nil value into an element of the bool-vector, the effect is to store t there. As with all arrays, bool-vector indices start from 0, and the length cannot be changed once the bool-vector is created. Bool-vectors are constants when evaluated.

There are two special functions for working with bool-vectors; aside from that, you manipulate them with same functions used for other kinds of arrays.

Function: make-bool-vector length initial
Return a new book-vector of length elements, each one initialized to initial.

Function: bool-vector-p object
This returns t if object is a bool-vector, and nil otherwise.

Symbols

A symbol is an object with a unique name. This chapter describes symbols, their components, their property lists, and how they are created and interned. Separate chapters describe the use of symbols as variables and as function names; see section Variables, and section Functions. For the precise read syntax for symbols, see section Symbol Type.

You can test whether an arbitrary Lisp object is a symbol with symbolp:

Function: symbolp object
This function returns t if object is a symbol, nil otherwise.

Symbol Components

Each symbol has four components (or "cells"), each of which references another object:

Print name
The print name cell holds a string that names the symbol for reading and printing. See symbol-name in section Creating and Interning Symbols.
Value
The value cell holds the current value of the symbol as a variable. When a symbol is used as a form, the value of the form is the contents of the symbol's value cell. See symbol-value in section Accessing Variable Values.
Function
The function cell holds the function definition of the symbol. When a symbol is used as a function, its function definition is used in its place. This cell is also used to make a symbol stand for a keymap or a keyboard macro, for editor command execution. Because each symbol has separate value and function cells, variables and function names do not conflict. See symbol-function in section Accessing Function Cell Contents.
Property list
The property list cell holds the property list of the symbol. See symbol-plist in section Property Lists.
The print name cell always holds a string, and cannot be changed. The other three cells can be set individually to any specified Lisp object.

The print name cell holds the string that is the name of the symbol. Since symbols are represented textually by their names, it is important not to have two symbols with the same name. The Lisp reader ensures this: every time it reads a symbol, it looks for an existing symbol with the specified name before it creates a new one. (In GNU Emacs Lisp, this lookup uses a hashing algorithm and an obarray; see section Creating and Interning Symbols.)

In normal usage, the function cell usually contains a function (see section Functions) or a macro (see section Macros), as that is what the Lisp interpreter expects to see there (see section Evaluation). Keyboard macros (see section Keyboard Macros), keymaps (see section Keymaps) and autoload objects (see section Autoloading) are also sometimes stored in the function cells of symbols. We often refer to "the function foo" when we really mean the function stored in the function cell of the symbol foo. We make the distinction only when necessary.

The property list cell normally should hold a correctly formatted property list (see section Property Lists), as a number of functions expect to see a property list there.

The function cell or the value cell may be void, which means that the cell does not reference any object. (This is not the same thing as holding the symbol void, nor the same as holding the symbol nil.) Examining a function or value cell that is void results in an error, such as `Symbol's value as variable is void'.

The four functions symbol-name, symbol-value, symbol-plist, and symbol-function return the contents of the four cells of a symbol. Here as an example we show the contents of the four cells of the symbol buffer-file-name:
(symbol-name 'buffer-file-name)
     => "buffer-file-name"
(symbol-value 'buffer-file-name)
     => "/gnu/elisp/symbols.texi"
(symbol-plist 'buffer-file-name)
     => (variable-documentation 29529)
(symbol-function 'buffer-file-name)
     => #<subr buffer-file-name>
Because this symbol is the variable which holds the name of the file being visited in the current buffer, the value cell contents we see are the name of the source file of this chapter of the Emacs Lisp Manual. The property list cell contains the list (variable-documentation 29529) which tells the documentation functions where to find the documentation string for the variable buffer-file-name in the `DOC-version' file. (29529 is the offset from the beginning of the `DOC-version' file to where that documentation string begins--see section Documentation Basics.) The function cell contains the function for returning the name of the file. buffer-file-name names a primitive function, which has no read syntax and prints in hash notation (see section Primitive Function Type). A symbol naming a function written in Lisp would have a lambda expression (or a byte-code object) in this cell.

Defining Symbols

A definition in Lisp is a special form that announces your intention to use a certain symbol in a particular way. In Emacs Lisp, you can define a symbol as a variable, or define it as a function (or macro), or both independently.

A definition construct typically specifies a value or meaning for the symbol for one kind of use, plus documentation for its meaning when used in this way. Thus, when you define a symbol as a variable, you can supply an initial value for the variable, plus documentation for the variable.

defvar and defconst are special forms that define a symbol as a global variable. They are documented in detail in section Defining Global Variables. For defining user option variables that can be customized, use defcustom (see section Writing Customization Definitions).

defun defines a symbol as a function, creating a lambda expression and storing it in the function cell of the symbol. This lambda expression thus becomes the function definition of the symbol. (The term "function definition", meaning the contents of the function cell, is derived from the idea that defun gives the symbol its definition as a function.) defsubst and defalias are two other ways of defining a function. See section Functions.

defmacro defines a symbol as a macro. It creates a macro object and stores it in the function cell of the symbol. Note that a given symbol can be a macro or a function, but not both at once, because both macro and function definitions are kept in the function cell, and that cell can hold only one Lisp object at any given time. See section Macros.

In Emacs Lisp, a definition is not required in order to use a symbol as a variable or function. Thus, you can make a symbol a global variable with setq, whether you define it first or not. The real purpose of definitions is to guide programmers and programming tools. They inform programmers who read the code that certain symbols are intended to be used as variables, or as functions. In addition, utilities such as `etags' and `make-docfile' recognize definitions, and add appropriate information to tag tables and the `DOC-version' file. See section Access to Documentation Strings.

Creating and Interning Symbols

To understand how symbols are created in GNU Emacs Lisp, you must know how Lisp reads them. Lisp must ensure that it finds the same symbol every time it reads the same set of characters. Failure to do so would cause complete confusion.

When the Lisp reader encounters a symbol, it reads all the characters of the name. Then it "hashes" those characters to find an index in a table called an obarray. Hashing is an efficient method of looking something up. For example, instead of searching a telephone book cover to cover when looking up Jan Jones, you start with the J's and go from there. That is a simple version of hashing. Each element of the obarray is a bucket which holds all the symbols with a given hash code; to look for a given name, it is sufficient to look through all the symbols in the bucket for that name's hash code.

If a symbol with the desired name is found, the reader uses that symbol. If the obarray does not contain a symbol with that name, the reader makes a new symbol and adds it to the obarray. Finding or adding a symbol with a certain name is called interning it, and the symbol is then called an interned symbol.

Interning ensures that each obarray has just one symbol with any particular name. Other like-named symbols may exist, but not in the same obarray. Thus, the reader gets the same symbols for the same names, as long as you keep reading with the same obarray.

No obarray contains all symbols; in fact, some symbols are not in any obarray. They are called uninterned symbols. An uninterned symbol has the same four cells as other symbols; however, the only way to gain access to it is by finding it in some other object or as the value of a variable.

In Emacs Lisp, an obarray is actually a vector. Each element of the vector is a bucket; its value is either an interned symbol whose name hashes to that bucket, or 0 if the bucket is empty. Each interned symbol has an internal link (invisible to the user) to the next symbol in the bucket. Because these links are invisible, there is no way to find all the symbols in an obarray except using mapatoms (below). The order of symbols in a bucket is not significant.

In an empty obarray, every element is 0, and you can create an obarray with (make-vector length 0). This is the only valid way to create an obarray. Prime numbers as lengths tend to result in good hashing; lengths one less than a power of two are also good.

Do not try to put symbols in an obarray yourself. This does not work--only intern can enter a symbol in an obarray properly.

Common Lisp note: In Common Lisp, a single symbol may be interned in several obarrays.

Most of the functions below take a name and sometimes an obarray as arguments. A wrong-type-argument error is signaled if the name is not a string, or if the obarray is not a vector.

Function: symbol-name symbol
This function returns the string that is symbol's name. For example:
(symbol-name 'foo)
     => "foo"
Warning: Changing the string by substituting characters does change the name of the symbol, but fails to update the obarray, so don't do it!

Function: make-symbol name
This function returns a newly-allocated, uninterned symbol whose name is name (which must be a string). Its value and function definition are void, and its property list is nil. In the example below, the value of sym is not eq to foo because it is a distinct uninterned symbol whose name is also `foo'.
(setq sym (make-symbol "foo"))
     => foo
(eq sym 'foo)
     => nil
Function: intern name &optional obarray
This function returns the interned symbol whose name is name. If there is no such symbol in the obarray obarray, intern creates a new one, adds it to the obarray, and returns it. If obarray is omitted, the value of the global variable obarray is used.
(setq sym (intern "foo"))
     => foo
(eq sym 'foo)
     => t

(setq sym1 (intern "foo" other-obarray))
     => foo
(eq sym 'foo)
     => nil
Common Lisp note: In Common Lisp, you can intern an existing symbol in an obarray. In Emacs Lisp, you cannot do this, because the argument to intern must be a string, not a symbol.

Function: intern-soft name &optional obarray
This function returns the symbol in obarray whose name is name, or nil if obarray has no symbol with that name. Therefore, you can use intern-soft to test whether a symbol with a given name is already interned. If obarray is omitted, the value of the global variable obarray is used.
(intern-soft "frazzle")        ; No such symbol exists.
     => nil
(make-symbol "frazzle")        ; Create an uninterned one.
     => frazzle
(intern-soft "frazzle")        ; That one cannot be found.
     => nil
(setq sym (intern "frazzle"))  ; Create an interned one.
     => frazzle
(intern-soft "frazzle")        ; That one can be found!
     => frazzle
(eq sym 'frazzle)              ; And it is the same one.
     => t
Variable: obarray
This variable is the standard obarray for use by intern and read.

Function: mapatoms function &optional obarray
This function calls function once with each symbol in the obarray obarray. Then it returns nil. If obarray is omitted, it defaults to the value of obarray, the standard obarray for ordinary symbols.
(setq count 0)
     => 0
(defun count-syms (s)
  (setq count (1+ count)))
     => count-syms
(mapatoms 'count-syms)
     => nil
count
     => 1871
See documentation in section Access to Documentation Strings, for another example using mapatoms.

Function: unintern symbol &optional obarray
This function deletes symbol from the obarray obarray. If symbol is not actually in the obarray, unintern does nothing. If obarray is nil, the current obarray is used.

If you provide a string instead of a symbol as symbol, it stands for a symbol name. Then unintern deletes the symbol (if any) in the obarray which has that name. If there is no such symbol, unintern does nothing.

If unintern does delete a symbol, it returns t. Otherwise it returns nil.

Property Lists

A property list (plist for short) is a list of paired elements stored in the property list cell of a symbol. Each of the pairs associates a property name (usually a symbol) with a property or value. Property lists are generally used to record information about a symbol, such as its documentation as a variable, the name of the file where it was defined, or perhaps even the grammatical class of the symbol (representing a word) in a language-understanding system.

Character positions in a string or buffer can also have property lists. See section Text Properties.

The property names and values in a property list can be any Lisp objects, but the names are usually symbols. Property list functions compare the property names using eq. Here is an example of a property list, found on the symbol progn when the compiler is loaded:
(lisp-indent-function 0 byte-compile byte-compile-progn)
Here lisp-indent-function and byte-compile are property names, and the other two elements are the corresponding values.

Property Lists and Association Lists

Association lists (see section Association Lists) are very similar to property lists. In contrast to association lists, the order of the pairs in the property list is not significant since the property names must be distinct.

Property lists are better than association lists for attaching information to various Lisp function names or variables. If your program keeps all of its associations in one association list, it will typically need to search that entire list each time it checks for an association. This could be slow. By contrast, if you keep the same information in the property lists of the function names or variables themselves, each search will scan only the length of one property list, which is usually short. This is why the documentation for a variable is recorded in a property named variable-documentation. The byte compiler likewise uses properties to record those functions needing special treatment.

However, association lists have their own advantages. Depending on your application, it may be faster to add an association to the front of an association list than to update a property. All properties for a symbol are stored in the same property list, so there is a possibility of a conflict between different uses of a property name. (For this reason, it is a good idea to choose property names that are probably unique, such as by beginning the property name with the program's usual name-prefix for variables and functions.) An association list may be used like a stack where associations are pushed on the front of the list and later discarded; this is not possible with a property list.

Property List Functions for Symbols

Function: symbol-plist symbol
This function returns the property list of symbol.

Function: setplist symbol plist
This function sets symbol's property list to plist. Normally, plist should be a well-formed property list, but this is not enforced.
(setplist 'foo '(a 1 b (2 3) c nil))
     => (a 1 b (2 3) c nil)
(symbol-plist 'foo)
     => (a 1 b (2 3) c nil)
For symbols in special obarrays, which are not used for ordinary purposes, it may make sense to use the property list cell in a nonstandard fashion; in fact, the abbrev mechanism does so (see section Abbrevs And Abbrev Expansion).

Function: get symbol property
This function finds the value of the property named property in symbol's property list. If there is no such property, nil is returned. Thus, there is no distinction between a value of nil and the absence of the property.

The name property is compared with the existing property names using eq, so any object is a legitimate property.

See put for an example.

Function: put symbol property value
This function puts value onto symbol's property list under the property name property, replacing any previous property value. The put function returns value.
(put 'fly 'verb 'transitive)
     =>'transitive
(put 'fly 'noun '(a buzzing little bug))
     => (a buzzing little bug)
(get 'fly 'verb)
     => transitive
(symbol-plist 'fly)
     => (verb transitive noun (a buzzing little bug))
Property Lists Outside Symbols

These two functions are useful for manipulating property lists that are stored in places other than symbols:

Function: plist-get plist property
This returns the value of the property property stored in the property list plist. For example,
(plist-get '(foo 4) 'foo)
     => 4
Function: plist-put plist property value
This stores value as the value of the property property in the property list plist. It may modify plist destructively, or it may construct a new list structure without altering the old. The function returns the modified property list, so you can store that back in the place where you got plist. For example,
(setq my-plist '(bar t foo 4))
     => (bar t foo 4)
(setq my-plist (plist-put my-plist 'foo 69))
     => (bar t foo 69)
(setq my-plist (plist-put my-plist 'quux '(a)))
     => (bar t foo 69 quux (a))
You could define put in terms of plist-put as follows:
(defun put (symbol prop value)
  (setplist symbol
            (plist-put (symbol-plist symbol) prop value)))
Evaluation

The evaluation of expressions in Emacs Lisp is performed by the Lisp interpreter---a program that receives a Lisp object as input and computes its value as an expression. How it does this depends on the data type of the object, according to rules described in this chapter. The interpreter runs automatically to evaluate portions of your program, but can also be called explicitly via the Lisp primitive function eval.

A Lisp object that is intended for evaluation is called an expression or a form. The fact that expressions are data objects and not merely text is one of the fundamental differences between Lisp-like languages and typical programming languages. Any object can be evaluated, but in practice only numbers, symbols, lists and strings are evaluated very often.

It is very common to read a Lisp expression and then evaluate the expression, but reading and evaluation are separate activities, and either can be performed alone. Reading per se does not evaluate anything; it converts the printed representation of a Lisp object to the object itself. It is up to the caller of read whether this object is a form to be evaluated, or serves some entirely different purpose. See section Input Functions.

Do not confuse evaluation with command key interpretation. The editor command loop translates keyboard input into a command (an interactively callable function) using the active keymaps, and then uses call-interactively to invoke the command. The execution of the command itself involves evaluation if the command is written in Lisp, but that is not a part of command key interpretation itself. See section Command Loop.

Evaluation is a recursive process. That is, evaluation of a form may call eval to evaluate parts of the form. For example, evaluation of a function call first evaluates each argument of the function call, and then evaluates each form in the function body. Consider evaluation of the form (car x): the subform x must first be evaluated recursively, so that its value can be passed as an argument to the function car.

Evaluation of a function call ultimately calls the function specified in it. See section Functions. The execution of the function may itself work by evaluating the function definition; or the function may be a Lisp primitive implemented in C, or it may be a byte-compiled function (see section Byte Compilation).

The evaluation of forms takes place in a context called the environment, which consists of the current values and bindings of all Lisp variables.(2) Whenever a form refers to a variable without creating a new binding for it, the value of the variable's binding in the current environment is used. See section Variables.

Evaluation of a form may create new environments for recursive evaluation by binding variables (see section Local Variables). These environments are temporary and vanish by the time evaluation of the form is complete. The form may also make changes that persist; these changes are called side effects. An example of a form that produces side effects is (setq foo 1).

The details of what evaluation means for each kind of form are described below (see section Kinds of Forms).

Kinds of Forms

A Lisp object that is intended to be evaluated is called a form. How Emacs evaluates a form depends on its data type. Emacs has three different kinds of form that are evaluated differently: symbols, lists, and "all other types". This section describes all three kinds, one by one, starting with the "all other types" which are self-evaluating forms.

Self-Evaluating Forms

A self-evaluating form is any form that is not a list or symbol. Self-evaluating forms evaluate to themselves: the result of evaluation is the same object that was evaluated. Thus, the number 25 evaluates to 25, and the string "foo" evaluates to the string "foo". Likewise, evaluation of a vector does not cause evaluation of the elements of the vector--it returns the same vector with its contents unchanged.
'123               ; A number, shown without evaluation.
     => 123
123                ; Evaluated as usual---result is the same.
     => 123
(eval '123)        ; Evaluated ``by hand''---result is the same.
     => 123
(eval (eval '123)) ; Evaluating twice changes nothing.
     => 123
It is common to write numbers, characters, strings, and even vectors in Lisp code, taking advantage of the fact that they self-evaluate. However, it is quite unusual to do this for types that lack a read syntax, because there's no way to write them textually. It is possible to construct Lisp expressions containing these types by means of a Lisp program. Here is an example:
;; Build an expression containing a buffer object.
(setq print-exp (list 'print (current-buffer)))
     => (print #<buffer eval.texi>)
;; Evaluate it.
(eval print-exp)
     -| #<buffer eval.texi>
     => #<buffer eval.texi>
Symbol Forms

When a symbol is evaluated, it is treated as a variable. The result is the variable's value, if it has one. If it has none (if its value cell is void), an error is signaled. For more information on the use of variables, see section Variables.

In the following example, we set the value of a symbol with setq. Then we evaluate the symbol, and get back the value that setq stored.
(setq a 123)
     => 123
(eval 'a)
     => 123
a
     => 123
The symbols nil and t are treated specially, so that the value of nil is always nil, and the value of t is always t; you cannot set or bind them to any other values. Thus, these two symbols act like self-evaluating forms, even though eval treats them like any other symbol. A symbol whose name starts with `:' also self-evaluates in the same way; likewise, its value ordinarily cannot be changed. See section Variables That Never Change.

Classification of List Forms

A form that is a nonempty list is either a function call, a macro call, or a special form, according to its first element. These three kinds of forms are evaluated in different ways, described below. The remaining list elements constitute the arguments for the function, macro, or special form.

The first step in evaluating a nonempty list is to examine its first element. This element alone determines what kind of form the list is and how the rest of the list is to be processed. The first element is not evaluated, as it would be in some Lisp dialects such as Scheme.

Symbol Function Indirection

If the first element of the list is a symbol then evaluation examines the symbol's function cell, and uses its contents instead of the original symbol. If the contents are another symbol, this process, called symbol function indirection, is repeated until it obtains a non-symbol. See section Naming a Function, for more information about using a symbol as a name for a function stored in the function cell of the symbol.

One possible consequence of this process is an infinite loop, in the event that a symbol's function cell refers to the same symbol. Or a symbol may have a void function cell, in which case the subroutine symbol-function signals a void-function error. But if neither of these things happens, we eventually obtain a non-symbol, which ought to be a function or other suitable object.

More precisely, we should now have a Lisp function (a lambda expression), a byte-code function, a primitive function, a Lisp macro, a special form, or an autoload object. Each of these types is a case described in one of the following sections. If the object is not one of these types, the error invalid-function is signaled.

The following example illustrates the symbol indirection process. We use fset to set the function cell of a symbol and symbol-function to get the function cell contents (see section Accessing Function Cell Contents). Specifically, we store the symbol car into the function cell of first, and the symbol first into the function cell of erste.
;; Build this function cell linkage:
;;   -------------       -----        -------        -------
;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
;;   -------------       -----        -------        -------
(symbol-function 'car)
     => #<subr car>
(fset 'first 'car)
     => car
(fset 'erste 'first)
     => first
(erste '(1 2 3))   ; Call the function referenced by erste.
     => 1
By contrast, the following example calls a function without any symbol function indirection, because the first element is an anonymous Lisp function, not a symbol.
((lambda (arg) (erste arg))
 '(1 2 3))
     => 1
Executing the function itself evaluates its body; this does involve symbol function indirection when calling erste.

The built-in function indirect-function provides an easy way to perform symbol function indirection explicitly.

Function: indirect-function function
This function returns the meaning of function as a function. If function is a symbol, then it finds function's function definition and starts over with that value. If function is not a symbol, then it returns function itself.

Here is how you could define indirect-function in Lisp:
(defun indirect-function (function)
  (if (symbolp function)
      (indirect-function (symbol-function function))
    function))
Evaluation of Function Forms

If the first element of a list being evaluated is a Lisp function object, byte-code object or primitive function object, then that list is a function call. For example, here is a call to the function +:
(+ 1 x)
The first step in evaluating a function call is to evaluate the remaining elements of the list from left to right. The results are the actual argument values, one value for each list element. The next step is to call the function with this list of arguments, effectively using the function apply (see section Calling Functions). If the function is written in Lisp, the arguments are used to bind the argument variables of the function (see section Lambda Expressions); then the forms in the function body are evaluated in order, and the value of the last body form becomes the value of the function call.

Lisp Macro Evaluation

If the first element of a list being evaluated is a macro object, then the list is a macro call. When a macro call is evaluated, the elements of the rest of the list are not initially evaluated. Instead, these elements themselves are used as the arguments of the macro. The macro definition computes a replacement form, called the expansion of the macro, to be evaluated in place of the original form. The expansion may be any sort of form: a self-evaluating constant, a symbol, or a list. If the expansion is itself a macro call, this process of expansion repeats until some other sort of form results.

Ordinary evaluation of a macro call finishes by evaluating the expansion. However, the macro expansion is not necessarily evaluated right away, or at all, because other programs also expand macro calls, and they may or may not evaluate the expansions.

Normally, the argument expressions are not evaluated as part of computing the macro expansion, but instead appear as part of the expansion, so they are computed when the expansion is evaluated.

For example, given a macro defined as follows:
(defmacro cadr (x)
  (list 'car (list 'cdr x)))
an expression such as (cadr (assq 'handler list)) is a macro call, and its expansion is:
(car (cdr (assq 'handler list)))
Note that the argument (assq 'handler list) appears in the expansion.

See section Macros, for a complete description of Emacs Lisp macros.

Special Forms

A special form is a primitive function specially marked so that its arguments are not all evaluated. Most special forms define control structures or perform variable bindings--things which functions cannot do.

Each special form has its own rules for which arguments are evaluated and which are used without evaluation. Whether a particular argument is evaluated may depend on the results of evaluating other arguments.

Here is a list, in alphabetical order, of all of the special forms in Emacs Lisp with a reference to where each is described.

and
see section Constructs for Combining Conditions
catch
see section Explicit Nonlocal Exits: catch and throw
cond
see section Conditionals
condition-case
see section Writing Code to Handle Errors
defconst
see section Defining Global Variables
defmacro
see section Defining Macros
defun
see section Defining Functions
defvar
see section Defining Global Variables
function
see section Anonymous Functions
if
see section Conditionals
interactive
see section Interactive Call
let

let*
see section Local Variables
or
see section Constructs for Combining Conditions
prog1

prog2

progn
see section Sequencing
quote
see section Quoting
save-current-buffer
see section The Current Buffer
save-excursion
see section Excursions
save-restriction
see section Narrowing
save-window-excursion
see section Window Configurations
setq
see section How to Alter a Variable Value
setq-default
see section Creating and Deleting Buffer-Local Bindings
track-mouse
see section Mouse Tracking
unwind-protect
see section Nonlocal Exits
while
see section Iteration
with-output-to-temp-buffer
see section Temporary Displays

Common Lisp note: Here are some comparisons of special forms in GNU Emacs Lisp and Common Lisp. setq, if, and catch are special forms in both Emacs Lisp and Common Lisp. defun is a special form in Emacs Lisp, but a macro in Common Lisp. save-excursion is a special form in Emacs Lisp, but doesn't exist in Common Lisp. throw is a special form in Common Lisp (because it must be able to throw multiple values), but it is a function in Emacs Lisp (which doesn't have multiple values).

Autoloading

The autoload feature allows you to call a function or macro whose function definition has not yet been loaded into Emacs. It specifies which file contains the definition. When an autoload object appears as a symbol's function definition, calling that symbol as a function automatically loads the specified file; then it calls the real definition loaded from that file. See section Autoload.

Quoting

The special form quote returns its single argument, as written, without evaluating it. This provides a way to include constant symbols and lists, which are not self-evaluating objects, in a program. (It is not necessary to quote self-evaluating objects such as numbers, strings, and vectors.)

Special Form: quote object
This special form returns object, without evaluating it.

Because quote is used so often in programs, Lisp provides a convenient read syntax for it. An apostrophe character (`'') followed by a Lisp object (in read syntax) expands to a list whose first element is quote, and whose second element is the object. Thus, the read syntax 'x is an abbreviation for (quote x).

Here are some examples of expressions that use quote:
(quote (+ 1 2))
     => (+ 1 2)
(quote foo)
     => foo
'foo
     => foo
''foo
     => (quote foo)
'(quote foo)
     => (quote foo)
['foo]
     => [(quote foo)]
Other quoting constructs include function (see section Anonymous Functions), which causes an anonymous lambda expression written in Lisp to be compiled, and ``' (see section Backquote), which is used to quote only part of a list, while computing and substituting other parts.

Eval

Most often, forms are evaluated automatically, by virtue of their occurrence in a program being run. On rare occasions, you may need to write code that evaluates a form that is computed at run time, such as after reading a form from text being edited or getting one from a property list. On these occasions, use the eval function.

The functions and variables described in this section evaluate forms, specify limits to the evaluation process, or record recently returned values. Loading a file also does evaluation (see section Loading).

Note: it is generally cleaner and more flexible to store a function in a data structure, and call it with funcall or apply, than to store an expression in the data structure and evaluate it. Using functions provides the ability to pass information to them as arguments.

Function: eval form
This is the basic function evaluating an expression. It evaluates form in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (see section Kinds of Forms).

Since eval is a function, the argument expression that appears in a call to eval is evaluated twice: once as preparation before eval is called, and again by the eval function itself. Here is an example:
(setq foo 'bar)
     => bar
(setq bar 'baz)
     => baz
;; Here eval receives argument foo
(eval 'foo)
     => bar
;; Here eval receives argument bar, which is the value of foo
(eval foo)
     => baz
The number of currently active calls to eval is limited to max-lisp-eval-depth (see below).

Command: eval-region start end &optional stream read-function
This function evaluates the forms in the current buffer in the region defined by the positions start and end. It reads forms from the region and calls eval on them until the end of the region is reached, or until an error is signaled and not handled.

If stream is non-nil, the values that result from evaluating the expressions in the region are printed using stream. See section Output Streams.

If read-function is non-nil, it should be a function, which is used instead of read to read expressions one by one. This function is called with one argument, the stream for reading input. You can also use the variable load-read-function (see section How Programs Do Loading) to specify this function, but it is more robust to use the read-function argument.

eval-region always returns nil.

Command: eval-current-buffer &optional stream
This is like eval-region except that it operates on the whole buffer.

Variable: max-lisp-eval-depth
This variable defines the maximum depth allowed in calls to eval, apply, and funcall before an error is signaled (with error message "Lisp nesting exceeds max-lisp-eval-depth"). This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function.

The depth limit counts internal uses of eval, apply, and funcall, such as for calling the functions mentioned in Lisp expressions, and recursive evaluation of function call arguments and function body forms, as well as explicit calls in Lisp code.

The default value of this variable is 300. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute.

max-specpdl-size provides another limit on nesting. See section Local Variables.

Variable: values
The value of this variable is a list of the values returned by all the expressions that were read, evaluated, and printed from buffers (including the minibuffer) by the standard Emacs commands which do this. The elements are ordered most recent first.
(setq x 1)
     => 1
(list 'A (1+ 2) auto-save-default)
     => (A 3 t)
values
     => ((A 3 t) 1 ...)
This variable is useful for referring back to values of forms recently evaluated. It is generally a bad idea to print the value of values itself, since this may be very long. Instead, examine particular elements, like this:
;; Refer to the most recent evaluation result.
(nth 0 values)
     => (A 3 t)
;; That put a new element on,
;;   so all elements move back one.
(nth 1 values)
     => (A 3 t)
;; This gets the element that was next-to-most-recent
;;   before this example.
(nth 3 values)
     => 1
Control Structures

A Lisp program consists of expressions or forms (see section Kinds of Forms). We control the order of execution of the forms by enclosing them in control structures. Control structures are special forms which control when, whether, or how many times to execute the forms they contain.

The simplest order of execution is sequential execution: first form a, then form b, and so on. This is what happens when you write several forms in succession in the body of a function, or at top level in a file of Lisp code--the forms are executed in the order written. We call this textual order. For example, if a function body consists of two forms a and b, evaluation of the function evaluates first a and then b, and the function's value is the value of b.

Explicit control structures make possible an order of execution other than sequential.

Emacs Lisp provides several kinds of control structure, including other varieties of sequencing, conditionals, iteration, and (controlled) jumps--all discussed below. The built-in control structures are special forms since their subforms are not necessarily evaluated or not evaluated sequentially. You can use macros to define your own control structure constructs (see section Macros).

Sequencing

Evaluating forms in the order they appear is the most common way control passes from one form to another. In some contexts, such as in a function body, this happens automatically. Elsewhere you must use a control structure construct to do this: progn, the simplest control construct of Lisp.

A progn special form looks like this:
(progn a b c ...)
and it says to execute the forms a, b, c and so on, in that order. These forms are called the body of the progn form. The value of the last form in the body becomes the value of the entire progn.

In the early days of Lisp, progn was the only way to execute two or more forms in succession and use the value of the last of them. But programmers found they often needed to use a progn in the body of a function, where (at that time) only one form was allowed. So the body of a function was made into an "implicit progn": several forms are allowed just as in the body of an actual progn. Many other control structures likewise contain an implicit progn. As a result, progn is not used as often as it used to be. It is needed now most often inside an unwind-protect, and, or, or in the then-part of an if.

Special Form: progn forms...
This special form evaluates all of the forms, in textual order, returning the result of the final form.
(progn (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
=> "The third form"
Two other control constructs likewise evaluate a series of forms but return a different value:

Special Form: prog1 form1 forms...
This special form evaluates form1 and all of the forms, in textual order, returning the result of form1.
(prog1 (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
=> "The first form"
Here is a way to remove the first element from a list in the variable x, then return the value of that former element:
(prog1 (car x) (setq x (cdr x)))
Special Form: prog2 form1 form2 forms...
This special form evaluates form1, form2, and all of the following forms, in textual order, returning the result of form2.
(prog2 (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
=> "The second form"
Conditionals

Conditional control structures choose among alternatives. Emacs Lisp has four conditional forms: if, which is much the same as in other languages; when and unless, which are variants of if; and cond, which is a generalized case statement.

Special Form: if condition then-form else-forms...
if chooses between the then-form and the else-forms based on the value of condition. If the evaluated condition is non-nil, then-form is evaluated and the result returned. Otherwise, the else-forms are evaluated in textual order, and the value of the last one is returned. (The else part of if is an example of an implicit progn. See section Sequencing.)

If condition has the value nil, and no else-forms are given, if returns nil.

if is a special form because the branch that is not selected is never evaluated--it is ignored. Thus, in the example below, true is not printed because print is never called.
(if nil
    (print 'true)
  'very-false)
=> very-false
Macro: when condition then-forms...
This is a variant of if where there are no else-forms, and possibly several then-forms. In particular,
(when condition a b c)
is entirely equivalent to
(if condition (progn a b c) nil)
Macro: unless condition forms...
This is a variant of if where there is no then-form:
(unless condition a b c)
is entirely equivalent to
(if condition nil
   a b c)
Special Form: cond clause...
cond chooses among an arbitrary number of alternatives. Each clause in the cond must be a list. The CAR of this list is the condition; the remaining elements, if any, the body-forms. Thus, a clause looks like this:
(condition body-forms...)
cond tries the clauses in textual order, by evaluating the condition of each clause. If the value of condition is non-nil, the clause "succeeds"; then cond evaluates its body-forms, and the value of the last of body-forms becomes the value of the cond. The remaining clauses are ignored.

If the value of condition is nil, the clause "fails", so the cond moves on to the following clause, trying its condition.

If every condition evaluates to nil, so that every clause fails, cond returns nil.

A clause may also look like this:
(condition)
Then, if condition is non-nil when tested, the value of condition becomes the value of the cond form.

The following example has four clauses, which test for the cases where the value of x is a number, string, buffer and symbol, respectively:
(cond ((numberp x) x)
      ((stringp x) x)
      ((bufferp x)
       (setq temporary-hack x) ; multiple body-forms
       (buffer-name x))        ; in one clause
      ((symbolp x) (symbol-value x)))
Often we want to execute the last clause whenever none of the previous clauses was successful. To do this, we use t as the condition of the last clause, like this: (t body-forms). The form t evaluates to t, which is never nil, so this clause never fails, provided the cond gets to it at all.

For example,
(cond ((eq a 'hack) 'foo)
      (t "default"))
=> "default"
This expression is a cond which returns foo if the value of a is hack, and returns the string "default" otherwise.

Any conditional construct can be expressed with cond or with if. Therefore, the choice between them is a matter of style. For example:
(if a b c)
==
(cond (a b) (t c))
Constructs for Combining Conditions

This section describes three constructs that are often used together with if and cond to express complicated conditions. The constructs and and or can also be used individually as kinds of multiple conditional constructs.

Function: not condition
This function tests for the falsehood of condition. It returns t if condition is nil, and nil otherwise. The function not is identical to null, and we recommend using the name null if you are testing for an empty list.

Special Form: and conditions...
The and special form tests whether all the conditions are true. It works by evaluating the conditions one by one in the order written.

If any of the conditions evaluates to nil, then the result of the and must be nil regardless of the remaining conditions; so and returns right away, ignoring the remaining conditions.

If all the conditions turn out non-nil, then the value of the last of them becomes the value of the and form.

Here is an example. The first condition returns the integer 1, which is not nil. Similarly, the second condition returns the integer 2, which is not nil. The third condition is nil, so the remaining condition is never evaluated.
(and (print 1) (print 2) nil (print 3))
     -| 1
     -| 2
=> nil
Here is a more realistic example of using and:
(if (and (consp foo) (eq (car foo) 'x))
    (message "foo is a list starting with x"))
Note that (car foo) is not executed if (consp foo) returns nil, thus avoiding an error.

and can be expressed in terms of either if or cond. For example:
(and arg1 arg2 arg3)
==
(if arg1 (if arg2 arg3))
==
(cond (arg1 (cond (arg2 arg3))))
Special Form: or conditions...
The or special form tests whether at least one of the conditions is true. It works by evaluating all the conditions one by one in the order written.

If any of the conditions evaluates to a non-nil value, then the result of the or must be non-nil; so or returns right away, ignoring the remaining conditions. The value it returns is the non-nil value of the condition just evaluated.

If all the conditions turn out nil, then the or expression returns nil.

For example, this expression tests whether x is either 0 or nil:
(or (eq x nil) (eq x 0))
Like the and construct, or can be written in terms of cond. For example:
(or arg1 arg2 arg3)
==
(cond (arg1)
      (arg2)
      (arg3))
You could almost write or in terms of if, but not quite:
(if arg1 arg1
  (if arg2 arg2
    arg3))
This is not completely equivalent because it can evaluate arg1 or arg2 twice. By contrast, (or arg1 arg2 arg3) never evaluates any argument more than once.

Iteration

Iteration means executing part of a program repetitively. For example, you might want to repeat some computation once for each element of a list, or once for each integer from 0 to n. You can do this in Emacs Lisp with the special form while:

Special Form: while condition forms...
while first evaluates condition. If the result is non-nil, it evaluates forms in textual order. Then it reevaluates condition, and if the result is non-nil, it evaluates forms again. This process repeats until condition evaluates to nil.

There is no limit on the number of iterations that may occur. The loop will continue until either condition evaluates to nil or until an error or throw jumps out of it (see section Nonlocal Exits).

The value of a while form is always nil.
(setq num 0)
     => 0
(while (< num 4)
  (princ (format "Iteration %d." num))
  (setq num (1+ num)))
     -| Iteration 0.
     -| Iteration 1.
     -| Iteration 2.
     -| Iteration 3.
     => nil
If you would like to execute something on each iteration before the end-test, put it together with the end-test in a progn as the first argument of while, as shown here:
(while (progn
         (forward-line 1)
         (not (looking-at "^$"))))
This moves forward one line and continues moving by lines until it reaches an empty line. It is peculiar in that the while has no body, just the end test (which also does the real work of moving point).

Nonlocal Exits

A nonlocal exit is a transfer of control from one point in a program to another remote point. Nonlocal exits can occur in Emacs Lisp as a result of errors; you can also use them under explicit control. Nonlocal exits unbind all variable bindings made by the constructs being exited.

Explicit Nonlocal Exits: catch and throw

Most control constructs affect only the flow of control within the construct itself. The function throw is the exception to this rule of normal program execution: it performs a nonlocal exit on request. (There are other exceptions, but they are for error handling only.) throw is used inside a catch, and jumps back to that catch. For example:
(defun foo-outer ()
  (catch 'foo
    (foo-inner)))

(defun foo-inner ()
  ...
  (if x
      (throw 'foo t))
  ...)
The throw form, if executed, transfers control straight back to the corresponding catch, which returns immediately. The code following the throw is not executed. The second argument of throw is used as the return value of the catch.

The function throw finds the matching catch based on the first argument: it searches for a catch whose first argument is eq to the one specified in the throw. If there is more than one applicable catch, the innermost one takes precedence. Thus, in the above example, the throw specifies foo, and the catch in foo-outer specifies the same symbol, so that catch is the applicable one (assuming there is no other matching catch in between).

Executing throw exits all Lisp constructs up to the matching catch, including function calls. When binding constructs such as let or function calls are exited in this way, the bindings are unbound, just as they are when these constructs exit normally (see section Local Variables). Likewise, throw restores the buffer and position saved by save-excursion (see section Excursions), and the narrowing status saved by save-restriction and the window selection saved by save-window-excursion (see section Window Configurations). It also runs any cleanups established with the unwind-protect special form when it exits that form (see section Cleaning Up from Nonlocal Exits).

The throw need not appear lexically within the catch that it jumps to. It can equally well be called from another function called within the catch. As long as the throw takes place chronologically after entry to the catch, and chronologically before exit from it, it has access to that catch. This is why throw can be used in commands such as exit-recursive-edit that throw back to the editor command loop (see section Recursive Editing).

Common Lisp note: Most other versions of Lisp, including Common Lisp, have several ways of transferring control nonsequentially: return, return-from, and go, for example. Emacs Lisp has only throw.

Special Form: catch tag body...
catch establishes a return point for the throw function. The return point is distinguished from other such return points by tag, which may be any Lisp object except nil. The argument tag is evaluated normally before the return point is established.

With the return point in effect, catch evaluates the forms of the body in textual order. If the forms execute normally, without error or nonlocal exit, the value of the last body form is returned from the catch.

If a throw is done within body specifying the same value tag, the catch exits immediately; the value it returns is whatever was specified as the second argument of throw.

Function: throw tag value
The purpose of throw is to return from a return point previously established with catch. The argument tag is used to choose among the various existing return points; it must be eq to the value specified in the catch. If multiple return points match tag, the innermost one is used.

The argument value is used as the value to return from that catch.

If no return point is in effect with tag tag, then a no-catch error is signaled with data (tag value).

Examples of catch and throw

One way to use catch and throw is to exit from a doubly nested loop. (In most languages, this would be done with a "go to".) Here we compute (foo i j) for i and j varying from 0 to 9:
(defun search-foo ()
  (catch 'loop
    (let ((i 0))
      (while (< i 10)
        (let ((j 0))
          (while (< j 10)
            (if (foo i j)
                (throw 'loop (list i j)))
            (setq j (1+ j))))
        (setq i (1+ i))))))
If foo ever returns non-nil, we stop immediately and return a list of i and j. If foo always returns nil, the catch returns normally, and the value is nil, since that is the result of the while.

Here are two tricky examples, slightly different, showing two return points at once. First, two return points with the same tag, hack:
(defun catch2 (tag)
  (catch tag
    (throw 'hack 'yes)))
=> catch2

(catch 'hack
  (print (catch2 'hack))
  'no)
-| yes
=> no
Since both return points have tags that match the throw, it goes to the inner one, the one established in catch2. Therefore, catch2 returns normally with value yes, and this value is printed. Finally the second body form in the outer catch, which is 'no, is evaluated and returned from the outer catch.

Now let's change the argument given to catch2:
(defun catch2 (tag)
  (catch tag
    (throw 'hack 'yes)))
=> catch2

(catch 'hack
  (print (catch2 'quux))
  'no)
=> yes
We still have two return points, but this time only the outer one has the tag hack; the inner one has the tag quux instead. Therefore, throw makes the outer catch return the value yes. The function print is never called, and the body-form 'no is never evaluated.

Errors

When Emacs Lisp attempts to evaluate a form that, for some reason, cannot be evaluated, it signals an error.

When an error is signaled, Emacs's default reaction is to print an error message and terminate execution of the current command. This is the right thing to do in most cases, such as if you type C-f at the end of the buffer.

In complicated programs, simple termination may not be what you want. For example, the program may have made temporary changes in data structures, or created temporary buffers that should be deleted before the program is finished. In such cases, you would use unwind-protect to establish cleanup expressions to be evaluated in case of error. (See section Cleaning Up from Nonlocal Exits.) Occasionally, you may wish the program to continue execution despite an error in a subroutine. In these cases, you would use condition-case to establish error handlers to recover control in case of error.

Resist the temptation to use error handling to transfer control from one part of the program to another; use catch and throw instead. See section Explicit Nonlocal Exits: catch and throw.

How to Signal an Error

Most errors are signaled "automatically" within Lisp primitives which you call for other purposes, such as if you try to take the CAR of an integer or move forward a character at the end of the buffer; you can also signal errors explicitly with the functions error and signal.

Quitting, which happens when the user types C-g, is not considered an error, but it is handled almost like an error. See section Quitting.

Function: error format-string &rest args
This function signals an error with an error message constructed by applying format (see section Conversion of Characters and Strings) to format-string and args.

These examples show typical uses of error:
(error "That is an error -- try something else")
     error--> That is an error -- try something else

(error "You have committed %d errors" 10)
     error--> You have committed 10 errors
error works by calling signal with two arguments: the error symbol error, and a list containing the string returned by format.

Warning: If you want to use your own string as an error message verbatim, don't just write (error string). If string contains `%', it will be interpreted as a format specifier, with undesirable results. Instead, use (error "%s" string).

Function: signal error-symbol data
This function signals an error named by error-symbol. The argument data is a list of additional Lisp objects relevant to the circumstances of the error.

The argument error-symbol must be an error symbol---a symbol bearing a property error-conditions whose value is a list of condition names. This is how Emacs Lisp classifies different sorts of errors.

The number and significance of the objects in data depends on error-symbol. For example, with a wrong-type-arg error, there should be two objects in the list: a predicate that describes the type that was expected, and the object that failed to fit that type. See section Error Symbols and Condition Names, for a description of error symbols.

Both error-symbol and data are available to any error handlers that handle the error: condition-case binds a local variable to a list of the form (error-symbol . data) (see section Writing Code to Handle Errors). If the error is not handled, these two values are used in printing the error message.

The function signal never returns (though in older Emacs versions it could sometimes return).
(signal 'wrong-number-of-arguments '(x y))
     error--> Wrong number of arguments: x, y

(signal 'no-such-error '("My unknown error condition"))
     error--> peculiar error: "My unknown error condition"
Common Lisp note: Emacs Lisp has nothing like the Common Lisp concept of continuable errors.

How Emacs Processes Errors

When an error is signaled, signal searches for an active handler for the error. A handler is a sequence of Lisp expressions designated to be executed if an error happens in part of the Lisp program. If the error has an applicable handler, the handler is executed, and control resumes following the handler. The handler executes in the environment of the condition-case that established it; all functions called within that condition-case have already been exited, and the handler cannot return to them.

If there is no applicable handler for the error, the current command is terminated and control returns to the editor command loop, because the command loop has an implicit handler for all kinds of errors. The command loop's handler uses the error symbol and associated data to print an error message.

An error that has no explicit handler may call the Lisp debugger. The debugger is enabled if the variable debug-on-error (see section Entering the Debugger on an Error) is non-nil. Unlike error handlers, the debugger runs in the environment of the error, so that you can examine values of variables precisely as they were at the time of the error.

Writing Code to Handle Errors

The usual effect of signaling an error is to terminate the command that is running and return immediately to the Emacs editor command loop. You can arrange to trap errors occurring in a part of your program by establishing an error handler, with the special form condition-case. A simple example looks like this:
(condition-case nil
    (delete-file filename)
  (error nil))
This deletes the file named filename, catching any error and returning nil if an error occurs.

The second argument of condition-case is called the protected form. (In the example above, the protected form is a call to delete-file.) The error handlers go into effect when this form begins execution and are deactivated when this form returns. They remain in effect for all the intervening time. In particular, they are in effect during the execution of functions called by this form, in their subroutines, and so on. This is a good thing, since, strictly speaking, errors can be signaled only by Lisp primitives (including signal and error) called by the protected form, not by the protected form itself.

The arguments after the protected form are handlers. Each handler lists one or more condition names (which are symbols) to specify which errors it will handle. The error symbol specified when an error is signaled also defines a list of condition names. A handler applies to an error if they have any condition names in common. In the example above, there is one handler, and it specifies one condition name, error, which covers all errors.

The search for an applicable handler checks all the established handlers starting with the most recently established one. Thus, if two nested condition-case forms offer to handle the same error, the inner of the two will actually handle it.

If an error is handled by some condition-case form, this ordinarily prevents the debugger from being run, even if debug-on-error says this error should invoke the debugger. See section Entering the Debugger on an Error. If you want to be able to debug errors that are caught by a condition-case, set the variable debug-on-signal to a non-nil value.

When an error is handled, control returns to the handler. Before this happens, Emacs unbinds all variable bindings made by binding constructs that are being exited and executes the cleanups of all unwind-protect forms that are exited. Once control arrives at the handler, the body of the handler is executed.

After execution of the handler body, execution returns from the condition-case form. Because the protected form is exited completely before execution of the handler, the handler cannot resume execution at the point of the error, nor can it examine variable bindings that were made within the protected form. All it can do is clean up and proceed.

The condition-case construct is often used to trap errors that are predictable, such as failure to open a file in a call to insert-file-contents. It is also used to trap errors that are totally unpredictable, such as when the program evaluates an expression read from the user.

Error signaling and handling have some resemblance to throw and catch, but they are entirely separate facilities. An error cannot be caught by a catch, and a throw cannot be handled by an error handler (though using throw when there is no suitable catch signals an error that can be handled).

Special Form: condition-case var protected-form handlers...
This special form establishes the error handlers handlers around the execution of protected-form. If protected-form executes without error, the value it returns becomes the value of the condition-case form; in this case, the condition-case has no effect. The condition-case form makes a difference when an error occurs during protected-form.

Each of the handlers is a list of the form (conditions body...). Here conditions is an error condition name to be handled, or a list of condition names; body is one or more Lisp expressions to be executed when this handler handles an error. Here are examples of handlers:
(error nil)

(arith-error (message "Division by zero"))

((arith-error file-error)
 (message
  "Either division by zero or failure to open a file"))
Each error that occurs has an error symbol that describes what kind of error it is. The error-conditions property of this symbol is a list of condition names (see section Error Symbols and Condition Names). Emacs searches all the active condition-case forms for a handler that specifies one or more of these condition names; the innermost matching condition-case handles the error. Within this condition-case, the first applicable handler handles the error.

After executing the body of the handler, the condition-case returns normally, using the value of the last form in the handler body as the overall value.

The argument var is a variable. condition-case does not bind this variable when executing the protected-form, only when it handles an error. At that time, it binds var locally to an error description, which is a list giving the particulars of the error. The error description has the form (error-symbol . data). The handler can refer to this list to decide what to do. For example, if the error is for failure opening a file, the file name is the second element of data---the third element of the error description.

If var is nil, that means no variable is bound. Then the error symbol and associated data are not available to the handler.

Function: error-message-string error-description
This function returns the error message string for a given error descriptor. It is useful if you want to handle an error by printing the usual error message for that error.

Here is an example of using condition-case to handle the error that results from dividing by zero. The handler displays the error message (but without a beep), then returns a very large number.
(defun safe-divide (dividend divisor)
  (condition-case err
      ;; Protected form.
      (/ dividend divisor)
    ;; The handler.
    (arith-error                        ; Condition.
     ;; Display the usual message for this error.
     (message "%s" (error-message-string err))
     1000000)))
=> safe-divide

(safe-divide 5 0)
     -| Arithmetic error: (arith-error)
=> 1000000
The handler specifies condition name arith-error so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this condition-case. Thus,
(safe-divide nil 3)
     error--> Wrong type argument: number-or-marker-p, nil
Here is a condition-case that catches all kinds of errors, including those signaled with error:
(setq baz 34)
     => 34

(condition-case err
    (if (eq baz 35)
        t
      ;; This is a call to the function error.
      (error "Rats!  The variable %s was %s, not 35" 'baz baz))
  ;; This is the handler; it is not a form.
  (error (princ (format "The error was: %s" err))
         2))
-| The error was: (error "Rats!  The variable baz was 34, not 35")
=> 2
Error Symbols and Condition Names

When you signal an error, you specify an error symbol to specify the kind of error you have in mind. Each error has one and only one error symbol to categorize it. This is the finest classification of errors defined by the Emacs Lisp language.

These narrow classifications are grouped into a hierarchy of wider classes called error conditions, identified by condition names. The narrowest such classes belong to the error symbols themselves: each error symbol is also a condition name. There are also condition names for more extensive classes, up to the condition name error which takes in all kinds of errors. Thus, each error has one or more condition names: error, the error symbol if that is distinct from error, and perhaps some intermediate classifications.

In order for a symbol to be an error symbol, it must have an error-conditions property which gives a list of condition names. This list defines the conditions that this kind of error belongs to. (The error symbol itself, and the symbol error, should always be members of this list.) Thus, the hierarchy of condition names is defined by the error-conditions properties of the error symbols.

In addition to the error-conditions list, the error symbol should have an error-message property whose value is a string to be printed when that error is signaled but not handled. If the error-message property exists, but is not a string, the error message `peculiar error' is used.

Here is how we define a new error symbol, new-error:
(put 'new-error
     'error-conditions
     '(error my-own-errors new-error))
=> (error my-own-errors new-error)
(put 'new-error 'error-message "A new error")
=> "A new error"
This error has three condition names: new-error, the narrowest classification; my-own-errors, which we imagine is a wider classification; and error, which is the widest of all.

The error string should start with a capital letter but it should not end with a period. This is for consistency with the rest of Emacs. Naturally, Emacs will never signal new-error on its own; only an explicit call to signal (see section How to Signal an Error) in your code can do this:
(signal 'new-error '(x y))
     error--> A new error: x, y
This error can be handled through any of the three condition names. This example handles new-error and any other errors in the class my-own-errors:
(condition-case foo
    (bar nil t)
  (my-own-errors nil))
The significant way that errors are classified is by their condition names--the names used to match errors with handlers. An error symbol serves only as a convenient way to specify the intended error message and list of condition names. It would be cumbersome to give signal a list of condition names rather than one error symbol.

By contrast, using only error symbols without condition names would seriously decrease the power of condition-case. Condition names make it possible to categorize errors at various levels of generality when you write an error handler. Using error symbols alone would eliminate all but the narrowest level of classification.

See section Standard Errors, for a list of all the standard error symbols and their conditions.

Cleaning Up from Nonlocal Exits

The unwind-protect construct is essential whenever you temporarily put a data structure in an inconsistent state; it permits you to make the data consistent again in the event of an error or throw.

Special Form: unwind-protect body cleanup-forms...
unwind-protect executes the body with a guarantee that the cleanup-forms will be evaluated if control leaves body, no matter how that happens. The body may complete normally, or execute a throw out of the unwind-protect, or cause an error; in all cases, the cleanup-forms will be evaluated.

If the body forms finish normally, unwind-protect returns the value of the last body form, after it evaluates the cleanup-forms. If the body forms do not finish, unwind-protect does not return any value in the normal sense.

Only the body is actually protected by the unwind-protect. If any of the cleanup-forms themselves exits nonlocally (e.g., via a throw or an error), unwind-protect is not guaranteed to evaluate the rest of them. If the failure of one of the cleanup-forms has the potential to cause trouble, then protect it with another unwind-protect around that form.

The number of currently active unwind-protect forms counts, together with the number of local variable bindings, against the limit max-specpdl-size (see section Local Variables).

For example, here we make an invisible buffer for temporary use, and make sure to kill it before finishing:
(save-excursion
  (let ((buffer (get-buffer-create " *temp*")))
    (set-buffer buffer)
    (unwind-protect
        body
      (kill-buffer buffer))))
You might think that we could just as well write (kill-buffer (current-buffer)) and dispense with the variable buffer. However, the way shown above is safer, if body happens to get an error after switching to a different buffer! (Alternatively, you could write another save-excursion around the body, to ensure that the temporary buffer becomes current again in time to kill it.)

Emacs includes a standard macro called with-temp-buffer which expands into more or less the code shown above (see section The Current Buffer). Several of the macros defined in this manual use unwind-protect in this way.

Here is an actual example taken from the file `ftp.el'. It creates a process (see section Processes) to try to establish a connection to a remote machine. As the function ftp-login is highly susceptible to numerous problems that the writer of the function cannot anticipate, it is protected with a form that guarantees deletion of the process in the event of failure. Otherwise, Emacs might fill up with useless subprocesses.
(let ((win nil))
  (unwind-protect
      (progn
        (setq process (ftp-setup-buffer host file))
        (if (setq win (ftp-login process host user password))
            (message "Logged in")
          (error "Ftp login failed")))
    (or win (and process (delete-process process)))))
This example actually has a small bug: if the user types C-g to quit, and the quit happens immediately after the function ftp-setup-buffer returns but before the variable process is set, the process will not be killed. There is no easy way to fix this bug, but at least it is very unlikely.
Variables

A variable is a name used in a program to stand for a value. Nearly all programming languages have variables of some sort. In the text of a Lisp program, variables are written using the syntax for symbols.

In Lisp, unlike most programming languages, programs are represented primarily as Lisp objects and only secondarily as text. The Lisp objects used for variables are symbols: the symbol name is the variable name, and the variable's value is stored in the value cell of the symbol. The use of a symbol as a variable is independent of its use as a function name. See section Symbol Components.

The Lisp objects that constitute a Lisp program determine the textual form of the program--it is simply the read syntax for those Lisp objects. This is why, for example, a variable in a textual Lisp program is written using the read syntax for the symbol that represents the variable.

Global Variables

The simplest way to use a variable is globally. This means that the variable has just one value at a time, and this value is in effect (at least for the moment) throughout the Lisp system. The value remains in effect until you specify a new one. When a new value replaces the old one, no trace of the old value remains in the variable.

You specify a value for a symbol with setq. For example,
(setq x '(a b))
gives the variable x the value (a b). Note that setq does not evaluate its first argument, the name of the variable, but it does evaluate the second argument, the new value.

Once the variable has a value, you can refer to it by using the symbol by itself as an expression. Thus,
x => (a b)
assuming the setq form shown above has already been executed.

If you do set the same variable again, the new value replaces the old one:
x
     => (a b)
(setq x 4)
     => 4
x
     => 4
Variables That Never Change

In Emacs Lisp, certain symbols normally evaluate to themselves. These include nil and t, as well as any symbol whose name starts with `:'. These symbols cannot be rebound, nor can their values be changed. Any attempt to set or bind nil or t signals a setting-constant error. The same is true for a symbol whose name starts with `:', except that you are allowed to set such a symbol to itself.
nil == 'nil
     => nil
(setq nil 500)
error--> Attempt to set constant symbol: nil
Variable: keyword-symbols-constant-flag
If this variable is nil, you are allowed to set and bind symbols whose names start with `:' as you wish. This is to make it possible to run old Lisp programs which do that.

Local Variables

Global variables have values that last until explicitly superseded with new values. Sometimes it is useful to create variable values that exist temporarily--only until a certain part of the program finishes. These values are called local, and the variables so used are called local variables.

For example, when a function is called, its argument variables receive new local values that last until the function exits. The let special form explicitly establishes new local values for specified variables; these last until exit from the let form.

Establishing a local value saves away the previous value (or lack of one) of the variable. When the life span of the local value is over, the previous value is restored. In the mean time, we say that the previous value is shadowed and not visible. Both global and local values may be shadowed (see section Scope).

If you set a variable (such as with setq) while it is local, this replaces the local value; it does not alter the global value, or previous local values, that are shadowed. To model this behavior, we speak of a local binding of the variable as well as a local value.

The local binding is a conceptual place that holds a local value. Entry to a function, or a special form such as let, creates the local binding; exit from the function or from the let removes the local binding. As long as the local binding lasts, the variable's value is stored within it. Use of setq or set while there is a local binding stores a different value into the local binding; it does not create a new binding.

We also speak of the global binding, which is where (conceptually) the global value is kept.

A variable can have more than one local binding at a time (for example, if there are nested let forms that bind it). In such a case, the most recently created local binding that still exists is the current binding of the variable. (This rule is called dynamic scoping; see section Scoping Rules for Variable Bindings.) If there are no local bindings, the variable's global binding is its current binding. We sometimes call the current binding the most-local existing binding, for emphasis. Ordinary evaluation of a symbol always returns the value of its current binding.

The special forms let and let* exist to create local bindings.

Special Form: let (bindings...) forms...
This special form binds variables according to bindings and then evaluates all of the forms in textual order. The let-form returns the value of the last form in forms.

Each of the bindings is either (i) a symbol, in which case that symbol is bound to nil; or (ii) a list of the form (symbol value-form), in which case symbol is bound to the result of evaluating value-form. If value-form is omitted, nil is used.

All of the value-forms in bindings are evaluated in the order they appear and before binding any of the symbols to them. Here is an example of this: Z is bound to the old value of Y, which is 2, not the new value of Y, which is 1.
(setq Y 2)
     => 2
(let ((Y 1)
      (Z Y))
  (list Y Z))
     => (1 2)
Special Form: let* (bindings...) forms...
This special form is like let, but it binds each variable right after computing its local value, before computing the local value for the next variable. Therefore, an expression in bindings can reasonably refer to the preceding symbols bound in this let* form. Compare the following example with the example above for let.
(setq Y 2)
     => 2
(let* ((Y 1)
       (Z Y))    ; Use the just-established value of Y.
  (list Y Z))
     => (1 1)
Here is a complete list of the other facilities that create local bindings:

Function calls (see section Functions).
Macro calls (see section Macros).
condition-case (see section Errors).

Variables can also have buffer-local bindings (see section Buffer-Local Variables) and frame-local bindings (see section Frame-Local Variables); a few variables have terminal-local bindings (see section Multiple Displays). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on "where" you are in Emacs, rather than localized in time.

Variable: max-specpdl-size
This variable defines the limit on the total number of local variable bindings and unwind-protect cleanups (see section Nonlocal Exits) that are allowed before signaling an error (with data "Variable binding depth exceeds max-specpdl-size").

This limit, with the associated error when it is exceeded, is one way that Lisp avoids infinite recursion on an ill-defined function. max-lisp-eval-depth provides another limit on depth of nesting. See section Eval.

The default value is 600. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute.

When a Variable is "Void"

If you have never given a symbol any value as a global variable, we say that that symbol's global value is void. In other words, the symbol's value cell does not have any Lisp object in it. If you try to evaluate the symbol, you get a void-variable error rather than a value.

Note that a value of nil is not the same as void. The symbol nil is a Lisp object and can be the value of a variable just as any other object can be; but it is a value. A void variable does not have any value.

After you have given a variable a value, you can make it void once more using makunbound.

Function: makunbound symbol
This function makes the current variable binding of symbol void. Subsequent attempts to use this symbol's value as a variable will signal the error void-variable, unless and until you set it again.

makunbound returns symbol.
(makunbound 'x)      ; Make the global value of x void.
     => x
x
error--> Symbol's value as variable is void: x
If symbol is locally bound, makunbound affects the most local existing binding. This is the only way a symbol can have a void local binding, since all the constructs that create local bindings create them with values. In this case, the voidness lasts at most as long as the binding does; when the binding is removed due to exit from the construct that made it, the previous local or global binding is reexposed as usual, and the variable is no longer void unless the newly reexposed binding was void all along.
(setq x 1)               ; Put a value in the global binding.
     => 1
(let ((x 2))             ; Locally bind it.
  (makunbound 'x)        ; Void the local binding.
  x)
error--> Symbol's value as variable is void: x
x                        ; The global binding is unchanged.
     => 1

(let ((x 2))             ; Locally bind it.
  (let ((x 3))           ; And again.
    (makunbound 'x)      ; Void the innermost-local binding.
    x))                  ; And refer: it's void.
error--> Symbol's value as variable is void: x

(let ((x 2))
  (let ((x 3))
    (makunbound 'x))     ; Void inner binding, then remove it.
  x)                     ; Now outer let binding is visible.
     => 2
A variable that has been made void with makunbound is indistinguishable from one that has never received a value and has always been void.

You can use the function boundp to test whether a variable is currently void.

Function: boundp variable
boundp returns t if variable (a symbol) is not void; more precisely, if its current binding is not void. It returns nil otherwise.
(boundp 'abracadabra)          ; Starts out void.
     => nil
(let ((abracadabra 5))         ; Locally bind it.
  (boundp 'abracadabra))
     => t
(boundp 'abracadabra)          ; Still globally void.
     => nil
(setq abracadabra 5)           ; Make it globally nonvoid.
     => 5
(boundp 'abracadabra)
     => t
Defining Global Variables

You may announce your intention to use a symbol as a global variable with a variable definition: a special form, either defconst or defvar.

In Emacs Lisp, definitions serve three purposes. First, they inform people who read the code that certain symbols are intended to be used a certain way (as variables). Second, they inform the Lisp system of these things, supplying a value and documentation. Third, they provide information to utilities such as etags and make-docfile, which create data bases of the functions and variables in a program.

The difference between defconst and defvar is primarily a matter of intent, serving to inform human readers of whether the value should ever change. Emacs Lisp does not restrict the ways in which a variable can be used based on defconst or defvar declarations. However, it does make a difference for initialization: defconst unconditionally initializes the variable, while defvar initializes it only if it is void.

Special Form: defvar symbol [value [doc-string]]
This special form defines symbol as a variable and can also initialize and document it. The definition informs a person reading your code that symbol is used as a variable that might be set or changed. Note that symbol is not evaluated; the symbol to be defined must appear explicitly in the defvar.

If symbol is void and value is specified, defvar evaluates it and sets symbol to the result. But if symbol already has a value (i.e., it is not void), value is not even evaluated, and symbol's value remains unchanged. If value is omitted, the value of symbol is not changed in any case.

If symbol has a buffer-local binding in the current buffer, defvar operates on the default value, which is buffer-independent, not the current (buffer-local) binding. It sets the default value if the default value is void. See section Buffer-Local Variables.

When you evaluate a top-level defvar form with C-M-x in Emacs Lisp mode (eval-defun), a special feature of eval-defun arranges to set the variable unconditionally, without testing whether its value is void.

If the doc-string argument appears, it specifies the documentation for the variable. (This opportunity to specify documentation is one of the main benefits of defining the variable.) The documentation is stored in the symbol's variable-documentation property. The Emacs help functions (see section Documentation) look for this property.

If the first character of doc-string is `*', it means that this variable is considered a user option. This lets users set the variable conveniently using the commands set-variable and edit-options. However, it is better to use defcustom instead of defvar for user option variables, so you can specify customization information. See section Writing Customization Definitions.

Here are some examples. This form defines foo but does not initialize it:
(defvar foo)
     => foo
This example initializes the value of bar to 23, and gives it a documentation string:
(defvar bar 23
  "The normal weight of a bar.")
     => bar
The following form changes the documentation string for bar, making it a user option, but does not change the value, since bar already has a value. (The addition (1+ nil) would get an error if it were evaluated, but since it is not evaluated, there is no error.)
(defvar bar (1+ nil)
  "*The normal weight of a bar.")
     => bar
bar
     => 23
Here is an equivalent expression for the defvar special form:
(defvar symbol value doc-string)
==
(progn
  (if (not (boundp 'symbol))
      (setq symbol value))
  (if 'doc-string
    (put 'symbol 'variable-documentation 'doc-string))
  'symbol)
The defvar form returns symbol, but it is normally used at top level in a file where its value does not matter.

Special Form: defconst symbol [value [doc-string]]
This special form defines symbol as a value and initializes it. It informs a person reading your code that symbol has a standard global value, established here, that should not be changed by the user or by other programs. Note that symbol is not evaluated; the symbol to be defined must appear explicitly in the defconst.

defconst always evaluates value, and sets the value of symbol to the result if value is given. If symbol does have a buffer-local binding in the current buffer, defconst sets the default value, not the buffer-local value. (But you should not be making buffer-local bindings for a symbol that is defined with defconst.)

Here, pi is a constant that presumably ought not to be changed by anyone (attempts by the Indiana State Legislature notwithstanding). As the second form illustrates, however, this is only advisory.
(defconst pi 3.1415 "Pi to five places.")
     => pi
(setq pi 3)
     => pi
pi
     => 3
Function: user-variable-p variable
This function returns t if variable is a user option--a variable intended to be set by the user for customization--and nil otherwise. (Variables other than user options exist for the internal purposes of Lisp programs, and users need not know about them.)

User option variables are distinguished from other variables by the first character of the variable-documentation property. If the property exists and is a string, and its first character is `*', then the variable is a user option.

If a user option variable has a variable-interactive property, the set-variable command uses that value to control reading the new value for the variable. The property's value is used as if it were to interactive (see section Using interactive). However, this feature is largely obsoleted by defcustom (see section Writing Customization Definitions).

Warning: If the defconst and defvar special forms are used while the variable has a local binding, they set the local binding's value; the global binding is not changed. This is not what we really want. To prevent it, use these special forms at top level in a file, where normally no local binding is in effect, and make sure to load the file before making a local binding for the variable.

Tips for Defining Variables Robustly

When defining and initializing a variable that holds a complicated value (such as a keymap with bindings in it), it's best to put the entire computation of the value into the defvar, like this:
(defvar my-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\C-c\C-a" 'my-command)
    ...
    map)
  docstring)
This method has several benefits. First, if the user quits while loading the file, the variable is either still uninitialized or initialized properly, never in-between. If it is still uninitialized, reloading the file will initialize it properly. Second, reloading the file once the variable is initialized will not alter it; that is important if the user has run hooks to alter part of the contents (such as, to rebind keys). Third, evaluating the defvar form with C-M-x will reinitialize the map completely.

Putting so much code in the defvar form has one disadvantage: it puts the documentation string far away from the line which names the variable. Here's a safe way to avoid that:
(defvar my-mode-map nil
  docstring)
(if my-mode-map
    nil
  (let ((map (make-sparse-keymap)))
    (define-key my-mode-map "\C-c\C-a" 'my-command)
    ...
    (setq my-mode-map map)))
This has all the same advantages as putting the initialization inside the defvar, except that you must type C-M-x twice, once on each form, if you do want to reinitialize the variable.

But be careful not to write the code like this:
(defvar my-mode-map nil
  docstring)
(if my-mode-map
    nil
  (setq my-mode-map (make-sparse-keymap))
  (define-key my-mode-map "\C-c\C-a" 'my-command)
  ...)
This code sets the variable, then alters it, but it does so in more than one step. If the user quits just after the setq, that leaves the variable neither correctly initialized nor void nor nil. Once that happens, reloading the file will not initialize the variable; it will remain incomplete.

Accessing Variable Values

The usual way to reference a variable is to write the symbol which names it (see section Symbol Forms). This requires you to specify the variable name when you write the program. Usually that is exactly what you want to do. Occasionally you need to choose at run time which variable to reference; then you can use symbol-value.

Function: symbol-value symbol
This function returns the value of symbol. This is the value in the innermost local binding of the symbol, or its global value if it has no local bindings.
(setq abracadabra 5)
     => 5
(setq foo 9)
     => 9

;; Here the symbol abracadabra
;;   is the symbol whose value is examined.
(let ((abracadabra 'foo))
  (symbol-value 'abracadabra))
     => foo

;; Here the value of abracadabra,
;;   which is foo,
;;   is the symbol whose value is examined.
(let ((abracadabra 'foo))
  (symbol-value abracadabra))
     => 9

(symbol-value 'abracadabra)
     => 5
A void-variable error is signaled if the current binding of symbol is void.

How to Alter a Variable Value

The usual way to change the value of a variable is with the special form setq. When you need to compute the choice of variable at run time, use the function set.

Special Form: setq [symbol form]...
This special form is the most common method of changing a variable's value. Each symbol is given a new value, which is the result of evaluating the corresponding form. The most-local existing binding of the symbol is changed.

setq does not evaluate symbol; it sets the symbol that you write. We say that this argument is automatically quoted. The `q' in setq stands for "quoted."

The value of the setq form is the value of the last form.
(setq x (1+ 2))
     => 3
x                   ; x now has a global value.
     => 3
(let ((x 5))
  (setq x 6)        ; The local binding of x is set.
  x)
     => 6
x                   ; The global value is unchanged.
     => 3
Note that the first form is evaluated, then the first symbol is set, then the second form is evaluated, then the second symbol is set, and so on:
(setq x 10          ; Notice that x is set before
      y (1+ x))     ;   the value of y is computed.
     => 11
Function: set symbol value
This function sets symbol's value to value, then returns value. Since set is a function, the expression written for symbol is evaluated to obtain the symbol to set.

The most-local existing binding of the variable is the binding that is set; shadowed bindings are not affected.
(set one 1)
error--> Symbol's value as variable is void: one
(set 'one 1)
     => 1
(set 'two 'one)
     => one
(set two 2)         ; two evaluates to symbol one.
     => 2
one                 ; So it is one that was set.
     => 2
(let ((one 1))      ; This binding of one is set,
  (set 'one 3)      ;   not the global value.
  one)
     => 3
one
     => 2
If symbol is not actually a symbol, a wrong-type-argument error is signaled.
(set '(x y) 'z)
error--> Wrong type argument: symbolp, (x y)
Logically speaking, set is a more fundamental primitive than setq. Any use of setq can be trivially rewritten to use set; setq could even be defined as a macro, given the availability of set. However, set itself is rarely used; beginners hardly need to know about it. It is useful only for choosing at run time which variable to set. For example, the command set-variable, which reads a variable name from the user and then sets the variable, needs to use set.

Common Lisp note: In Common Lisp, set always changes the symbol's "special" or dynamic value, ignoring any lexical bindings. In Emacs Lisp, all variables and all bindings are dynamic, so set always affects the most local existing binding.

One other function for setting a variable is designed to add an element to a list if it is not already present in the list.

Function: add-to-list symbol element
This function sets the variable symbol by consing element onto the old value, if element is not already a member of that value. It returns the resulting list, whether updated or not. The value of symbol had better be a list already before the call.

The argument symbol is not implicitly quoted; add-to-list is an ordinary function, like set and unlike setq. Quote the argument yourself if that is what you want.

Here's a scenario showing how to use add-to-list:
(setq foo '(a b))
     => (a b)

(add-to-list 'foo 'c)     ;; Add c.
     => (c a b)

(add-to-list 'foo 'b)     ;; No effect.
     => (c a b)

foo                       ;; foo was changed.
     => (c a b)
An equivalent expression for (add-to-list 'var value) is this:
(or (member value var)
    (setq var (cons value var)))
Scoping Rules for Variable Bindings

A given symbol foo can have several local variable bindings, established at different places in the Lisp program, as well as a global binding. The most recently established binding takes precedence over the others.

Local bindings in Emacs Lisp have indefinite scope and dynamic extent. Scope refers to where textually in the source code the binding can be accessed. Indefinite scope means that any part of the program can potentially access the variable binding. Extent refers to when, as the program is executing, the binding exists. Dynamic extent means that the binding lasts as long as the activation of the construct that established it.

The combination of dynamic extent and indefinite scope is called dynamic scoping. By contrast, most programming languages use lexical scoping, in which references to a local variable must be located textually within the function or block that binds the variable.

Common Lisp note: Variables declared "special" in Common Lisp are dynamically scoped, like all variables in Emacs Lisp.

Scope

Emacs Lisp uses indefinite scope for local variable bindings. This means that any function anywhere in the program text might access a given binding of a variable. Consider the following function definitions:
(defun binder (x)   ; x is bound in binder.
   (foo 5))         ; foo is some other function.

(defun user ()      ; x is used ``free'' in user.
  (list x))
In a lexically scoped language, the binding of x in binder would never be accessible in user, because user is not textually contained within the function binder. However, in dynamically scoped Emacs Lisp, user may or may not refer to the binding of x established in binder, depending on circumstances:

If we call user directly without calling binder at all, then whatever binding of x is found, it cannot come from binder.
If we define foo as follows and then call binder, then the binding made in binder will be seen in user:
(defun foo (lose)
  (user))
However, if we define foo as follows and then call binder, then the binding made in binder will not be seen in user:
(defun foo (x)
  (user))
Here, when foo is called by binder, it binds x. (The binding in foo is said to shadow the one made in binder.) Therefore, user will access the x bound by foo instead of the one bound by binder.

Emacs Lisp uses dynamic scoping because simple implementations of lexical scoping are slow. In addition, every Lisp system needs to offer dynamic scoping at least as an option; if lexical scoping is the norm, there must be a way to specify dynamic scoping instead for a particular variable. It might not be a bad thing for Emacs to offer both, but implementing it with dynamic scoping only was much easier.

Extent

Extent refers to the time during program execution that a variable name is valid. In Emacs Lisp, a variable is valid only while the form that bound it is executing. This is called dynamic extent. "Local" or "automatic" variables in most languages, including C and Pascal, have dynamic extent.

One alternative to dynamic extent is indefinite extent. This means that a variable binding can live on past the exit from the form that made the binding. Common Lisp and Scheme, for example, support this, but Emacs Lisp does not.

To illustrate this, the function below, make-add, returns a function that purports to add n to its own argument m. This would work in Common Lisp, but it does not do the job in Emacs Lisp, because after the call to make-add exits, the variable n is no longer bound to the actual argument 2.
(defun make-add (n)
    (function (lambda (m) (+ n m))))  ; Return a function.
     => make-add
(fset 'add2 (make-add 2))  ; Define function add2
                           ;   with (make-add 2).
     => (lambda (m) (+ n m))
(add2 4)                   ; Try to add 2 to 4.
error--> Symbol's value as variable is void: n
Some Lisp dialects have "closures", objects that are like functions but record additional variable bindings. Emacs Lisp does not have closures.

Implementation of Dynamic Scoping

A simple sample implementation (which is not how Emacs Lisp actually works) may help you understand dynamic binding. This technique is called deep binding and was used in early Lisp systems.

Suppose there is a stack of bindings, which are variable-value pairs. At entry to a function or to a let form, we can push bindings onto the stack for the arguments or local variables created there. We can pop those bindings from the stack at exit from the binding construct.

We can find the value of a variable by searching the stack from top to bottom for a binding for that variable; the value from that binding is the value of the variable. To set the variable, we search for the current binding, then store the new value into that binding.

As you can see, a function's bindings remain in effect as long as it continues execution, even during its calls to other functions. That is why we say the extent of the binding is dynamic. And any other function can refer to the bindings, if it uses the same variables while the bindings are in effect. That is why we say the scope is indefinite.

The actual implementation of variable scoping in GNU Emacs Lisp uses a technique called shallow binding. Each variable has a standard place in which its current value is always found--the value cell of the symbol.

In shallow binding, setting the variable works by storing a value in the value cell. Creating a new binding works by pushing the old value (belonging to a previous binding) onto a stack, and storing the new local value in the value cell. Eliminating a binding works by popping the old value off the stack, into the value cell.

We use shallow binding because it has the same results as deep binding, but runs faster, since there is never a need to search for a binding.

Proper Use of Dynamic Scoping

Binding a variable in one function and using it in another is a powerful technique, but if used without restraint, it can make programs hard to understand. There are two clean ways to use this technique:

Use or bind the variable only in a few related functions, written close together in one file. Such a variable is used for communication within one program. You should write comments to inform other programmers that they can see all uses of the variable before them, and to advise them not to add uses elsewhere.
Give the variable a well-defined, documented meaning, and make all appropriate functions refer to it (but not bind it or set it) wherever that meaning is relevant. For example, the variable case-fold-search is defined as "non-nil means ignore case when searching"; various search and replace functions refer to it directly or through their subroutines, but do not bind or set it. Then you can bind the variable in other programs, knowing reliably what the effect will be.

In either case, you should define the variable with defvar. This helps other people understand your program by telling them to look for inter-function usage. It also avoids a warning from the byte compiler. Choose the variable's name to avoid name conflicts--don't use short names like x.

Buffer-Local Variables

Global and local variable bindings are found in most programming languages in one form or another. Emacs also supports additional, unusual kinds of variable binding: buffer-local bindings, which apply only in one buffer, and frame-local bindings, which apply only in one frame. Having different values for a variable in different buffers and/or frames is an important customization method.

This section describes buffer-local bindings; for frame-local bindings, see the following section, section Frame-Local Variables. (A few variables have bindings that are local to each terminal; see section Multiple Displays.)

Introduction to Buffer-Local Variables

A buffer-local variable has a buffer-local binding associated with a particular buffer. The binding is in effect when that buffer is current; otherwise, it is not in effect. If you set the variable while a buffer-local binding is in effect, the new value goes in that binding, so its other bindings are unchanged. This means that the change is visible only in the buffer where you made it.

The variable's ordinary binding, which is not associated with any specific buffer, is called the default binding. In most cases, this is the global binding.

A variable can have buffer-local bindings in some buffers but not in other buffers. The default binding is shared by all the buffers that don't have their own bindings for the variable. (This includes all newly created buffers.) If you set the variable in a buffer that does not have a buffer-local binding for it, this sets the default binding (assuming there are no frame-local bindings to complicate the matter), so the new value is visible in all the buffers that see the default binding.

The most common use of buffer-local bindings is for major modes to change variables that control the behavior of commands. For example, C mode and Lisp mode both set the variable paragraph-start to specify that only blank lines separate paragraphs. They do this by making the variable buffer-local in the buffer that is being put into C mode or Lisp mode, and then setting it to the new value for that mode. See section Major Modes.

The usual way to make a buffer-local binding is with make-local-variable, which is what major mode commands typically use. This affects just the current buffer; all other buffers (including those yet to be created) will continue to share the default value unless they are explicitly given their own buffer-local bindings.

A more powerful operation is to mark the variable as automatically buffer-local by calling make-variable-buffer-local. You can think of this as making the variable local in all buffers, even those yet to be created. More precisely, the effect is that setting the variable automatically makes the variable local to the current buffer if it is not already so. All buffers start out by sharing the default value of the variable as usual, but setting the variable creates a buffer-local binding for the current buffer. The new value is stored in the buffer-local binding, leaving the default binding untouched. This means that the default value cannot be changed with setq in any buffer; the only way to change it is with setq-default.

Warning: When a variable has buffer-local values in one or more buffers, you can get Emacs very confused by binding the variable with let, changing to a different current buffer in which a different binding is in effect, and then exiting the let. This can scramble the values of the buffer-local and default bindings.

To preserve your sanity, avoid using a variable in that way. If you use save-excursion around each piece of code that changes to a different current buffer, you will not have this problem (see section Excursions). Here is an example of what to avoid:
(setq foo 'b)
(set-buffer "a")
(make-local-variable 'foo)
(setq foo 'a)
(let ((foo 'temp))
  (set-buffer "b")
  body...)
foo => 'a      ; The old buffer-local value from buffer `a'
               ;   is now the default value.
(set-buffer "a")
foo => 'temp   ; The local let value that should be gone
               ;   is now the buffer-local value in buffer `a'.
But save-excursion as shown here avoids the problem:
(let ((foo 'temp))
  (save-excursion
    (set-buffer "b")
    body...))
Note that references to foo in body access the buffer-local binding of buffer `b'.

When a file specifies local variable values, these become buffer-local values when you visit the file. See section `File Variables' in The GNU Emacs Manual.

Creating and Deleting Buffer-Local Bindings

Command: make-local-variable variable
This function creates a buffer-local binding in the current buffer for variable (a symbol). Other buffers are not affected. The value returned is variable.

The buffer-local value of variable starts out as the same value variable previously had. If variable was void, it remains void.
;; In buffer `b1':
(setq foo 5)                ; Affects all buffers.
     => 5
(make-local-variable 'foo)  ; Now it is local in `b1'.
     => foo
foo                         ; That did not change
     => 5                   ;   the value.
(setq foo 6)                ; Change the value
     => 6                   ;   in `b1'.
foo
     => 6

;; In buffer `b2', the value hasn't changed.
(save-excursion
  (set-buffer "b2")
  foo)
     => 5
Making a variable buffer-local within a let-binding for that variable does not work reliably, unless the buffer in which you do this is not current either on entry to or exit from the let. This is because let does not distinguish between different kinds of bindings; it knows only which variable the binding was made for.

If the variable is terminal-local, this function signals an error. Such variables cannot have buffer-local bindings as well. See section Multiple Displays.

Note: do not use make-local-variable for a hook variable. Instead, use make-local-hook. See section Hooks.

Command: make-variable-buffer-local variable
This function marks variable (a symbol) automatically buffer-local, so that any subsequent attempt to set it will make it local to the current buffer at the time.

A peculiar wrinkle of this feature is that binding the variable (with let or other binding constructs) does not create a buffer-local binding for it. Only setting the variable (with set or setq) does so.

The value returned is variable.

Warning: Don't assume that you should use make-variable-buffer-local for user-option variables, simply because users might want to customize them differently in different buffers. Users can make any variable local, when they wish to. It is better to leave the choice to them.

The time to use make-variable-buffer-local is when it is crucial that no two buffers ever share the same binding. For example, when a variable is used for internal purposes in a Lisp program which depends on having separate values in separate buffers, then using make-variable-buffer-local can be the best solution.

Function: local-variable-p variable &optional buffer
This returns t if variable is buffer-local in buffer buffer (which defaults to the current buffer); otherwise, nil.

Function: buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in buffer buffer. (If buffer is omitted, the current buffer is used.) It returns an association list (see section Association Lists) in which each element contains one buffer-local variable and its value. However, when a variable's buffer-local binding in buffer is void, then the variable appears directly in the resulting list.
(make-local-variable 'foobar)
(makunbound 'foobar)
(make-local-variable 'bind-me)
(setq bind-me 69)
(setq lcl (buffer-local-variables))
    ;; First, built-in variables local in all buffers:
=> ((mark-active . nil)
    (buffer-undo-list . nil)
    (mode-name . "Fundamental")
    ...
    ;; Next, non-built-in buffer-local variables.
    ;; This one is buffer-local and void:
    foobar
    ;; This one is buffer-local and nonvoid:
    (bind-me . 69))
Note that storing new values into the CDRs of cons cells in this list does not change the buffer-local values of the variables.

Command: kill-local-variable variable
This function deletes the buffer-local binding (if any) for variable (a symbol) in the current buffer. As a result, the default binding of variable becomes visible in this buffer. This typically results in a change in the value of variable, since the default value is usually different from the buffer-local value just eliminated.

If you kill the buffer-local binding of a variable that automatically becomes buffer-local when set, this makes the default value visible in the current buffer. However, if you set the variable again, that will once again create a buffer-local binding for it.

kill-local-variable returns variable.

This function is a command because it is sometimes useful to kill one buffer-local variable interactively, just as it is useful to create buffer-local variables interactively.

Function: kill-all-local-variables
This function eliminates all the buffer-local variable bindings of the current buffer except for variables marked as "permanent". As a result, the buffer will see the default values of most variables.

This function also resets certain other information pertaining to the buffer: it sets the local keymap to nil, the syntax table to the value of (standard-syntax-table), the case table to (standard-case-table), and the abbrev table to the value of fundamental-mode-abbrev-table.

The very first thing this function does is run the normal hook change-major-mode-hook (see below).

Every major mode command begins by calling this function, which has the effect of switching to Fundamental mode and erasing most of the effects of the previous major mode. To ensure that this does its job, the variables that major modes set should not be marked permanent.

kill-all-local-variables returns nil.

Variable: change-major-mode-hook
The function kill-all-local-variables runs this normal hook before it does anything else. This gives major modes a way to arrange for something special to be done if the user switches to a different major mode. For best results, make this variable buffer-local, so that it will disappear after doing its job and will not interfere with the subsequent major mode. See section Hooks.

A buffer-local variable is permanent if the variable name (a symbol) has a permanent-local property that is non-nil. Permanent locals are appropriate for data pertaining to where the file came from or how to save it, rather than with how to edit the contents.

The Default Value of a Buffer-Local Variable

The global value of a variable with buffer-local bindings is also called the default value, because it is the value that is in effect whenever neither the current buffer nor the selected frame has its own binding for the variable.

The functions default-value and setq-default access and change a variable's default value regardless of whether the current buffer has a buffer-local binding. For example, you could use setq-default to change the default setting of paragraph-start for most buffers; and this would work even when you are in a C or Lisp mode buffer that has a buffer-local value for this variable.

The special forms defvar and defconst also set the default value (if they set the variable at all), rather than any buffer-local or frame-local value.

Function: default-value symbol
This function returns symbol's default value. This is the value that is seen in buffers and frames that do not have their own values for this variable. If symbol is not buffer-local, this is equivalent to symbol-value (see section Accessing Variable Values).

Function: default-boundp symbol
The function default-boundp tells you whether symbol's default value is nonvoid. If (default-boundp 'foo) returns nil, then (default-value 'foo) would get an error.

default-boundp is to default-value as boundp is to symbol-value.

Special Form: setq-default [symbol form]...
This special form gives each symbol a new default value, which is the result of evaluating the corresponding form. It does not evaluate symbol, but does evaluate form. The value of the setq-default form is the value of the last form.

If a symbol is not buffer-local for the current buffer, and is not marked automatically buffer-local, setq-default has the same effect as setq. If symbol is buffer-local for the current buffer, then this changes the value that other buffers will see (as long as they don't have a buffer-local value), but not the value that the current buffer sees.
;; In buffer `foo':
(make-local-variable 'buffer-local)
     => buffer-local
(setq buffer-local 'value-in-foo)
     => value-in-foo
(setq-default buffer-local 'new-default)
     => new-default
buffer-local
     => value-in-foo
(default-value 'buffer-local)
     => new-default

;; In (the new) buffer `bar':
buffer-local
     => new-default
(default-value 'buffer-local)
     => new-default
(setq buffer-local 'another-default)
     => another-default
(default-value 'buffer-local)
     => another-default

;; Back in buffer `foo':
buffer-local
     => value-in-foo
(default-value 'buffer-local)
     => another-default
Function: set-default symbol value
This function is like setq-default, except that symbol is an ordinary evaluated argument.
(set-default (car '(a b c)) 23)
     => 23
(default-value 'a)
     => 23
Frame-Local Variables

Just as variables can have buffer-local bindings, they can also have frame-local bindings. These bindings belong to one frame, and are in effect when that frame is selected. Frame-local bindings are actually frame parameters: you create a frame-local binding in a specific frame by calling modify-frame-parameters and specifying the variable name as the parameter name.

To enable frame-local bindings for a certain variable, call the function make-variable-frame-local.

Command: make-variable-frame-local variable
Enable the use of frame-local bindings for variable. This does not in itself create any frame-local bindings for the variable; however, if some frame already has a value for variable as a frame parameter, that value automatically becomes a frame-local binding.

If the variable is terminal-local, this function signals an error, because such variables cannot have frame-local bindings as well. See section Multiple Displays. A few variables that are implemented specially in Emacs can be (and usually are) buffer-local, but can never be frame-local.

Buffer-local bindings take precedence over frame-local bindings. Thus, consider a variable foo: if the current buffer has a buffer-local binding for foo, that binding is active; otherwise, if the selected frame has a frame-local binding for foo, that binding is active; otherwise, the default binding of foo is active.

Here is an example. First we prepare a few bindings for foo:
(setq f1 (selected-frame))
(make-variable-frame-local 'foo)

;; Make a buffer-local binding for foo in `b1'.
(set-buffer (get-buffer-create "b1"))
(make-local-variable 'foo)
(setq foo '(b 1))

;; Make a frame-local binding for foo in a new frame.
;; Store that frame in f2.
(setq f2 (make-frame))
(modify-frame-parameters f2 '((foo . (f 2))))
Now we examine foo in various contexts. Whenever the buffer `b1' is current, its buffer-local binding is in effect, regardless of the selected frame:
(select-frame f1)
(set-buffer (get-buffer-create "b1"))
foo
     => (b 1)

(select-frame f2)
(set-buffer (get-buffer-create "b1"))
foo
     => (b 1)
Otherwise, the frame gets a chance to provide the binding; when frame f2 is selected, its frame-local binding is in effect:
(select-frame f2)
(set-buffer (get-buffer "*scratch*"))
foo
     => (f 2)
When neither the current buffer nor the selected frame provides a binding, the default binding is used:
(select-frame f1)
(set-buffer (get-buffer "*scratch*"))
foo
     => nil
When the active binding of a variable is a frame-local binding, setting the variable changes that binding. You can observe the result with frame-parameters:
(select-frame f2)
(set-buffer (get-buffer "*scratch*"))
(setq foo 'nobody)
(assq 'foo (frame-parameters f2))
     => (foo . nobody)
Possible Future Local Variables

We have considered the idea of bindings that are local to a category of frames--for example, all color frames, or all frames with dark backgrounds. We have not implemented them because it is not clear that this feature is really useful. You can get more or less the same results by adding a function to after-make-frame-hook, set up to define a particular frame parameter according to the appropriate conditions for each frame.

It would also be possible to implement window-local bindings. We don't know of many situations where they would be useful, and it seems that indirect buffers (see section Indirect Buffers) with buffer-local bindings offer a way to handle these situations more robustly.

If sufficient application is found for either of these two kinds of local bindings, we will provide it in a subsequent Emacs version.

Functions

A Lisp program is composed mainly of Lisp functions. This chapter explains what functions are, how they accept arguments, and how to define them.

What Is a Function?

In a general sense, a function is a rule for carrying on a computation given several values called arguments. The result of the computation is called the value of the function. The computation can also have side effects: lasting changes in the values of variables or the contents of data structures.

Here are important terms for functions in Emacs Lisp and for other function-like objects.

function
In Emacs Lisp, a function is anything that can be applied to arguments in a Lisp program. In some cases, we use it more specifically to mean a function written in Lisp. Special forms and macros are not functions.
primitive
A primitive is a function callable from Lisp that is written in C, such as car or append. These functions are also called built-in functions or subrs. (Special forms are also considered primitives.) Usually the reason we implement a function as a primitive is either because it is fundamental, because it provides a low-level interface to operating system services, or because it needs to run fast. Primitives can be modified or added only by changing the C sources and recompiling the editor. See section Writing Emacs Primitives.
lambda expression
A lambda expression is a function written in Lisp. These are described in the following section.
special form
A special form is a primitive that is like a function but does not evaluate all of its arguments in the usual way. It may evaluate only some of the arguments, or may evaluate them in an unusual order, or several times. Many special forms are described in section Control Structures.
macro
A macro is a construct defined in Lisp by the programmer. It differs from a function in that it translates a Lisp expression that you write into an equivalent expression to be evaluated instead of the original expression. Macros enable Lisp programmers to do the sorts of things that special forms can do. See section Macros, for how to define and use macros.
command
A command is an object that command-execute can invoke; it is a possible definition for a key sequence. Some functions are commands; a function written in Lisp is a command if it contains an interactive declaration (see section Defining Commands). Such a function can be called from Lisp expressions like other functions; in this case, the fact that the function is a command makes no difference. Keyboard macros (strings and vectors) are commands also, even though they are not functions. A symbol is a command if its function definition is a command; such symbols can be invoked with M-x. The symbol is a function as well if the definition is a function. See section Command Loop Overview.
keystroke command
A keystroke command is a command that is bound to a key sequence (typically one to three keystrokes). The distinction is made here merely to avoid confusion with the meaning of "command" in non-Emacs editors; for Lisp programs, the distinction is normally unimportant.
byte-code function
A byte-code function is a function that has been compiled by the byte compiler. See section Byte-Code Function Type.

Function: functionp object
This function returns t if object is any kind of function, or a special form or macro.

Function: subrp object
This function returns t if object is a built-in function (i.e., a Lisp primitive).
(subrp 'message)            ; message is a symbol,
     => nil                 ;   not a subr object.
(subrp (symbol-function 'message))
     => t
Function: byte-code-function-p object
This function returns t if object is a byte-code function. For example:
(byte-code-function-p (symbol-function 'next-line))
     => t
Lambda Expressions

A function written in Lisp is a list that looks like this:
(lambda (arg-variables...)
  [documentation-string]
  [interactive-declaration]
  body-forms...)
Such a list is called a lambda expression. In Emacs Lisp, it actually is valid as an expression--it evaluates to itself. In some other Lisp dialects, a lambda expression is not a valid expression at all. In either case, its main use is not to be evaluated as an expression, but to be called as a function.

Components of a Lambda Expression

The first element of a lambda expression is always the symbol lambda. This indicates that the list represents a function. The reason functions are defined to start with lambda is so that other lists, intended for other uses, will not accidentally be valid as functions.

The second element is a list of symbols--the argument variable names. This is called the lambda list. When a Lisp function is called, the argument values are matched up against the variables in the lambda list, which are given local bindings with the values provided. See section Local Variables.

The documentation string is a Lisp string object placed within the function definition to describe the function for the Emacs help facilities. See section Documentation Strings of Functions.

The interactive declaration is a list of the form (interactive code-string). This declares how to provide arguments if the function is used interactively. Functions with this declaration are called commands; they can be called using M-x or bound to a key. Functions not intended to be called in this way should not have interactive declarations. See section Defining Commands, for how to write an interactive declaration.

The rest of the elements are the body of the function: the Lisp code to do the work of the function (or, as a Lisp programmer would say, "a list of Lisp forms to evaluate"). The value returned by the function is the value returned by the last element of the body.

A Simple Lambda-Expression Example

Consider for example the following function:
(lambda (a b c) (+ a b c))
We can call this function by writing it as the CAR of an expression, like this:
((lambda (a b c) (+ a b c))
 1 2 3)
This call evaluates the body of the lambda expression with the variable a bound to 1, b bound to 2, and c bound to 3. Evaluation of the body adds these three numbers, producing the result 6; therefore, this call to the function returns the value 6.

Note that the arguments can be the results of other function calls, as in this example:
((lambda (a b c) (+ a b c))
 1 (* 2 3) (- 5 4))
This evaluates the arguments 1, (* 2 3), and (- 5 4) from left to right. Then it applies the lambda expression to the argument values 1, 6 and 1 to produce the value 8.

It is not often useful to write a lambda expression as the CAR of a form in this way. You can get the same result, of making local variables and giving them values, using the special form let (see section Local Variables). And let is clearer and easier to use. In practice, lambda expressions are either stored as the function definitions of symbols, to produce named functions, or passed as arguments to other functions (see section Anonymous Functions).

However, calls to explicit lambda expressions were very useful in the old days of Lisp, before the special form let was invented. At that time, they were the only way to bind and initialize local variables.

Other Features of Argument Lists

Our simple sample function, (lambda (a b c) (+ a b c)), specifies three argument variables, so it must be called with three arguments: if you try to call it with only two arguments or four arguments, you get a wrong-number-of-arguments error.

It is often convenient to write a function that allows certain arguments to be omitted. For example, the function substring accepts three arguments--a string, the start index and the end index--but the third argument defaults to the length of the string if you omit it. It is also convenient for certain functions to accept an indefinite number of arguments, as the functions list and + do.

To specify optional arguments that may be omitted when a function is called, simply include the keyword &optional before the optional arguments. To specify a list of zero or more extra arguments, include the keyword &rest before one final argument.

Thus, the complete syntax for an argument list is as follows:
(required-vars...
 [&optional optional-vars...]
 [&rest rest-var])
The square brackets indicate that the &optional and &rest clauses, and the variables that follow them, are optional.

A call to the function requires one actual argument for each of the required-vars. There may be actual arguments for zero or more of the optional-vars, and there cannot be any actual arguments beyond that unless the lambda list uses &rest. In that case, there may be any number of extra actual arguments.

If actual arguments for the optional and rest variables are omitted, then they always default to nil. There is no way for the function to distinguish between an explicit argument of nil and an omitted argument. However, the body of the function is free to consider nil an abbreviation for some other meaningful value. This is what substring does; nil as the third argument to substring means to use the length of the string supplied.

Common Lisp note: Common Lisp allows the function to specify what default value to use when an optional argument is omitted; Emacs Lisp always uses nil. Emacs Lisp does not support "supplied-p" variables that tell you whether an argument was explicitly passed.

For example, an argument list that looks like this:
(a b &optional c d &rest e)
binds a and b to the first two actual arguments, which are required. If one or two more arguments are provided, c and d are bound to them respectively; any arguments after the first four are collected into a list and e is bound to that list. If there are only two arguments, c is nil; if two or three arguments, d is nil; if four arguments or fewer, e is nil.

There is no way to have required arguments following optional ones--it would not make sense. To see why this must be so, suppose that c in the example were optional and d were required. Suppose three actual arguments are given; which variable would the third argument be for? Similarly, it makes no sense to have any more arguments (either required or optional) after a &rest argument.

Here are some examples of argument lists and proper calls:
((lambda (n) (1+ n))                ; One required:
 1)                                 ; requires exactly one argument.
     => 2
((lambda (n &optional n1)           ; One required and one optional:
         (if n1 (+ n n1) (1+ n)))   ; 1 or 2 arguments.
 1 2)
     => 3
((lambda (n &rest ns)               ; One required and one rest:
         (+ n (apply '+ ns)))       ; 1 or more arguments.
 1 2 3 4 5)
     => 15
Documentation Strings of Functions

A lambda expression may optionally have a documentation string just after the lambda list. This string does not affect execution of the function; it is a kind of comment, but a systematized comment which actually appears inside the Lisp world and can be used by the Emacs help facilities. See section Documentation, for how the documentation-string is accessed.

It is a good idea to provide documentation strings for all the functions in your program, even those that are called only from within your program. Documentation strings are like comments, except that they are easier to access.

The first line of the documentation string should stand on its own, because apropos displays just this first line. It should consist of one or two complete sentences that summarize the function's purpose.

The start of the documentation string is usually indented in the source file, but since these spaces come before the starting double-quote, they are not part of the string. Some people make a practice of indenting any additional lines of the string so that the text lines up in the program source. This is a mistake. The indentation of the following lines is inside the string; what looks nice in the source code will look ugly when displayed by the help commands.

You may wonder how the documentation string could be optional, since there are required components of the function that follow it (the body). Since evaluation of a string returns that string, without any side effects, it has no effect if it is not the last form in the body. Thus, in practice, there is no confusion between the first form of the body and the documentation string; if the only body form is a string then it serves both as the return value and as the documentation.

Naming a Function

In most computer languages, every function has a name; the idea of a function without a name is nonsensical. In Lisp, a function in the strictest sense has no name. It is simply a list whose first element is lambda, a byte-code function object, or a primitive subr-object.

However, a symbol can serve as the name of a function. This happens when you put the function in the symbol's function cell (see section Symbol Components). Then the symbol itself becomes a valid, callable function, equivalent to the list or subr-object that its function cell refers to. The contents of the function cell are also called the symbol's function definition. The procedure of using a symbol's function definition in place of the symbol is called symbol function indirection; see section Symbol Function Indirection.

In practice, nearly all functions are given names in this way and referred to through their names. For example, the symbol car works as a function and does what it does because the primitive subr-object #<subr car> is stored in its function cell.

We give functions names because it is convenient to refer to them by their names in Lisp expressions. For primitive subr-objects such as #<subr car>, names are the only way you can refer to them: there is no read syntax for such objects. For functions written in Lisp, the name is more convenient to use in a call than an explicit lambda expression. Also, a function with a name can refer to itself--it can be recursive. Writing the function's name in its own definition is much more convenient than making the function definition point to itself (something that is not impossible but that has various disadvantages in practice).

We often identify functions with the symbols used to name them. For example, we often speak of "the function car", not distinguishing between the symbol car and the primitive subr-object that is its function definition. For most purposes, there is no need to distinguish.

Even so, keep in mind that a function need not have a unique name. While a given function object usually appears in the function cell of only one symbol, this is just a matter of convenience. It is easy to store it in several symbols using fset; then each of the symbols is equally well a name for the same function.

A symbol used as a function name may also be used as a variable; these two uses of a symbol are independent and do not conflict. (Some Lisp dialects, such as Scheme, do not distinguish between a symbol's value and its function definition; a symbol's value as a variable is also its function definition.) If you have not given a symbol a function definition, you cannot use it as a function; whether the symbol has a value as a variable makes no difference to this.

Defining Functions

We usually give a name to a function when it is first created. This is called defining a function, and it is done with the defun special form.

Special Form: defun name argument-list body-forms
defun is the usual way to define new Lisp functions. It defines the symbol name as a function that looks like this:
(lambda argument-list . body-forms)
defun stores this lambda expression in the function cell of name. It returns the value name, but usually we ignore this value.

As described previously (see section Lambda Expressions), argument-list is a list of argument names and may include the keywords &optional and &rest. Also, the first two of the body-forms may be a documentation string and an interactive declaration.

There is no conflict if the same symbol name is also used as a variable, since the symbol's value cell is independent of the function cell. See section Symbol Components.

Here are some examples:
(defun foo () 5)
     => foo
(foo)
     => 5

(defun bar (a &optional b &rest c)
    (list a b c))
     => bar
(bar 1 2 3 4 5)
     => (1 2 (3 4 5))
(bar 1)
     => (1 nil nil)
(bar)
error--> Wrong number of arguments.

(defun capitalize-backwards ()
  "Upcase the last letter of a word."
  (interactive)
  (backward-word 1)
  (forward-word 1)
  (backward-char 1)
  (capitalize-word 1))
     => capitalize-backwards
Be careful not to redefine existing functions unintentionally. defun redefines even primitive functions such as car without any hesitation or notification. Redefining a function already defined is often done deliberately, and there is no way to distinguish deliberate redefinition from unintentional redefinition.

Function: defalias name definition
This special form defines the symbol name as a function, with definition definition (which can be any valid Lisp function).

The proper place to use defalias is where a specific function name is being defined--especially where that name appears explicitly in the source file being loaded. This is because defalias records which file defined the function, just like defun (see section Unloading).

By contrast, in programs that manipulate function definitions for other purposes, it is better to use fset, which does not keep such records.

See also defsubst, which defines a function like defun and tells the Lisp compiler to open-code it. See section Inline Functions.

Calling Functions

Defining functions is only half the battle. Functions don't do anything until you call them, i.e., tell them to run. Calling a function is also known as invocation.

The most common way of invoking a function is by evaluating a list. For example, evaluating the list (concat "a" "b") calls the function concat with arguments "a" and "b". See section Evaluation, for a description of evaluation.

When you write a list as an expression in your program, the function name it calls is written in your program. This means that you choose which function to call, and how many arguments to give it, when you write the program. Usually that's just what you want. Occasionally you need to compute at run time which function to call. To do that, use the function funcall. When you also need to determine at run time how many arguments to pass, use apply.

Function: funcall function &rest arguments
funcall calls function with arguments, and returns whatever function returns.

Since funcall is a function, all of its arguments, including function, are evaluated before funcall is called. This means that you can use any expression to obtain the function to be called. It also means that funcall does not see the expressions you write for the arguments, only their values. These values are not evaluated a second time in the act of calling function; funcall enters the normal procedure for calling a function at the place where the arguments have already been evaluated.

The argument function must be either a Lisp function or a primitive function. Special forms and macros are not allowed, because they make sense only when given the "unevaluated" argument expressions. funcall cannot provide these because, as we saw above, it never knows them in the first place.
(setq f 'list)
     => list
(funcall f 'x 'y 'z)
     => (x y z)
(funcall f 'x 'y '(z))
     => (x y (z))
(funcall 'and t nil)
error--> Invalid function: #<subr and>
Compare these example with the examples of apply.

Function: apply function &rest arguments
apply calls function with arguments, just like funcall but with one difference: the last of arguments is a list of objects, which are passed to function as separate arguments, rather than a single list. We say that apply spreads this list so that each individual element becomes an argument.

apply returns the result of calling function. As with funcall, function must either be a Lisp function or a primitive function; special forms and macros do not make sense in apply.
(setq f 'list)
     => list
(apply f 'x 'y 'z)
error--> Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     => 10
(apply '+ '(1 2 3 4))
     => 10

(apply 'append '((a b c) nil (x y z) nil))
     => (a b c x y z)
For an interesting example of using apply, see the description of mapcar, in section Mapping Functions.

It is common for Lisp functions to accept functions as arguments or find them in data structures (especially in hook variables and property lists) and call them using funcall or apply. Functions that accept function arguments are often called functionals.

Sometimes, when you call a functional, it is useful to supply a no-op function as the argument. Here are two different kinds of no-op function:

Function: identity arg
This function returns arg and has no side effects.

Function: ignore &rest args
This function ignores any arguments and returns nil.

Mapping Functions

A mapping function applies a given function to each element of a list or other collection. Emacs Lisp has several such functions; mapcar and mapconcat, which scan a list, are described here. See section Creating and Interning Symbols, for the function mapatoms which maps over the symbols in an obarray.

These mapping functions do not allow char-tables because a char-table is a sparse array whose nominal range of indices is very large. To map over a char-table in a way that deals properly with its sparse nature, use the function map-char-table (see section Char-Tables).

Function: mapcar function sequence
mapcar applies function to each element of sequence in turn, and returns a list of the results.

The argument sequence can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string. The result is always a list. The length of the result is the same as the length of sequence.
For example:

(mapcar 'car '((a b) (c d) (e f)))
     => (a c e)
(mapcar '1+ [1 2 3])
     => (2 3 4)
(mapcar 'char-to-string "abc")
     => ("a" "b" "c")

;; Call each function in my-hooks.
(mapcar 'funcall my-hooks)

(defun mapcar* (function &rest args)
  "Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
  ;; If no list is exhausted,
  (if (not (memq 'nil args))
      ;; apply function to CARs.
      (cons (apply function (mapcar 'car args))
            (apply 'mapcar* function
                   ;; Recurse for rest of elements.
                   (mapcar 'cdr args)))))

(mapcar* 'cons '(a b c) '(1 2 3 4))
     => ((a . 1) (b . 2) (c . 3))
Function: mapconcat function sequence separator
mapconcat applies function to each element of sequence: the results, which must be strings, are concatenated. Between each pair of result strings, mapconcat inserts the string separator. Usually separator contains a space or comma or other suitable punctuation.

The argument function must be a function that can take one argument and return a string. The argument sequence can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string.
(mapconcat 'symbol-name
           '(The cat in the hat)
           " ")
     => "The cat in the hat"

(mapconcat (function (lambda (x) (format "%c" (1+ x))))
           "HAL-8000"
           "")
     => "IBM.9111"
Anonymous Functions

In Lisp, a function is a list that starts with lambda, a byte-code function compiled from such a list, or alternatively a primitive subr-object; names are "extra". Although usually functions are defined with defun and given names at the same time, it is occasionally more concise to use an explicit lambda expression--an anonymous function. Such a list is valid wherever a function name is.

Any method of creating such a list makes a valid function. Even this:
(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
=> (lambda (x) (+ 12 x))
This computes a list that looks like (lambda (x) (+ 12 x)) and makes it the value (not the function definition!) of silly.

Here is how we might call this function:
(funcall silly 1)
=> 13
(It does not work to write (silly 1), because this function is not the function definition of silly. We have not given silly any function definition, just a value as a variable.)

Most of the time, anonymous functions are constants that appear in your program. For example, you might want to pass one as an argument to the function mapcar, which applies any given function to each element of a list.

Here we define a function change-property which uses a function as its third argument:
(defun change-property (symbol prop function)
  (let ((value (get symbol prop)))
    (put symbol prop (funcall function value))))
Here we define a function that uses change-property, passing it a function to double a number:
(defun double-property (symbol prop)
  (change-property symbol prop '(lambda (x) (* 2 x))))
In such cases, we usually use the special form function instead of simple quotation to quote the anonymous function, like this:
(defun double-property (symbol prop)
  (change-property symbol prop
                   (function (lambda (x) (* 2 x)))))
Using function instead of quote makes a difference if you compile the function double-property. For example, if you compile the second definition of double-property, the anonymous function is compiled as well. By contrast, if you compile the first definition which uses ordinary quote, the argument passed to change-property is the precise list shown:
(lambda (x) (* x 2))
The Lisp compiler cannot assume this list is a function, even though it looks like one, since it does not know what change-property will do with the list. Perhaps it will check whether the CAR of the third element is the symbol *! Using function tells the compiler it is safe to go ahead and compile the constant function.

We sometimes write function instead of quote when quoting the name of a function, but this usage is just a sort of comment:
(function symbol) == (quote symbol) == 'symbol
The read syntax #' is a short-hand for using function. For example,
#'(lambda (x) (* x x))
is equivalent to
(function (lambda (x) (* x x)))
Special Form: function function-object
This special form returns function-object without evaluating it. In this, it is equivalent to quote. However, it serves as a note to the Emacs Lisp compiler that function-object is intended to be used only as a function, and therefore can safely be compiled. Contrast this with quote, in section Quoting.

See documentation in section Access to Documentation Strings, for a realistic example using function and an anonymous function.

Accessing Function Cell Contents

The function definition of a symbol is the object stored in the function cell of the symbol. The functions described here access, test, and set the function cell of symbols.

See also the function indirect-function in section Symbol Function Indirection.

Function: symbol-function symbol
This returns the object in the function cell of symbol. If the symbol's function cell is void, a void-function error is signaled.

This function does not check that the returned object is a legitimate function.
(defun bar (n) (+ n 2))
     => bar
(symbol-function 'bar)
     => (lambda (n) (+ n 2))
(fset 'baz 'bar)
     => bar
(symbol-function 'baz)
     => bar
If you have never given a symbol any function definition, we say that that symbol's function cell is void. In other words, the function cell does not have any Lisp object in it. If you try to call such a symbol as a function, it signals a void-function error.

Note that void is not the same as nil or the symbol void. The symbols nil and void are Lisp objects, and can be stored into a function cell just as any other object can be (and they can be valid functions if you define them in turn with defun). A void function cell contains no object whatsoever.

You can test the voidness of a symbol's function definition with fboundp. After you have given a symbol a function definition, you can make it void once more using fmakunbound.

Function: fboundp symbol
This function returns t if the symbol has an object in its function cell, nil otherwise. It does not check that the object is a legitimate function.

Function: fmakunbound symbol
This function makes symbol's function cell void, so that a subsequent attempt to access this cell will cause a void-function error. (See also makunbound, in section When a Variable is "Void".)
(defun foo (x) x)
     => foo
(foo 1)
     =>1
(fmakunbound 'foo)
     => foo
(foo 1)
error--> Symbol's function definition is void: foo
Function: fset symbol definition
This function stores definition in the function cell of symbol. The result is definition. Normally definition should be a function or the name of a function, but this is not checked. The argument symbol is an ordinary evaluated argument.

There are three normal uses of this function:

Copying one symbol's function definition to another--in other words, making an alternate name for a function. (If you think of this as the definition of the new name, you should use defalias instead of fset; see section Defining Functions.)
Giving a symbol a function definition that is not a list and therefore cannot be made with defun. For example, you can use fset to give a symbol s1 a function definition which is another symbol s2; then s1 serves as an alias for whatever definition s2 presently has. (Once again use defalias instead of fset if you think of this as the definition of s1.)
In constructs for defining or altering functions. If defun were not a primitive, it could be written in Lisp (as a macro) using fset.

Here are examples of these uses:
;; Save foo's definition in old-foo.
(fset 'old-foo (symbol-function 'foo))

;; Make the symbol car the function definition of xfirst.
;; (Most likely, defalias would be better than fset here.)
(fset 'xfirst 'car)
     => car
(xfirst '(1 2 3))
     => 1
(symbol-function 'xfirst)
     => car
(symbol-function (symbol-function 'xfirst))
     => #<subr car>

;; Define a named keyboard macro.
(fset 'kill-two-lines "\^u2\^k")
     => "\^u2\^k"

;; Here is a function that alters other functions.
(defun copy-function-definition (new old)
  "Define NEW with the same function definition as OLD."
  (fset new (symbol-function old)))
When writing a function that extends a previously defined function, the following idiom is sometimes used:
(fset 'old-foo (symbol-function 'foo))
(defun foo ()
  "Just like old-foo, except more so."
  (old-foo)
  (more-so))
This does not work properly if foo has been defined to autoload. In such a case, when foo calls old-foo, Lisp attempts to define old-foo by loading a file. Since this presumably defines foo rather than old-foo, it does not produce the proper results. The only way to avoid this problem is to make sure the file is loaded before moving aside the old definition of foo.

But it is unmodular and unclean, in any case, for a Lisp file to redefine a function defined elsewhere. It is cleaner to use the advice facility (see section Advising Emacs Lisp Functions).

Inline Functions

You can define an inline function by using defsubst instead of defun. An inline function works just like an ordinary function except for one thing: when you compile a call to the function, the function's definition is open-coded into the caller.

Making a function inline makes explicit calls run faster. But it also has disadvantages. For one thing, it reduces flexibility; if you change the definition of the function, calls already inlined still use the old definition until you recompile them. Since the flexibility of redefining functions is an important feature of Emacs, you should not make a function inline unless its speed is really crucial.

Another disadvantage is that making a large function inline can increase the size of compiled code both in files and in memory. Since the speed advantage of inline functions is greatest for small functions, you generally should not make large functions inline.

It's possible to define a macro to expand into the same code that an inline function would execute. (See section Macros.) But the macro would be limited to direct use in expressions--a macro cannot be called with apply, mapcar and so on. Also, it takes some work to convert an ordinary function into a macro. To convert it into an inline function is very easy; simply replace defun with defsubst. Since each argument of an inline function is evaluated exactly once, you needn't worry about how many times the body uses the arguments, as you do for macros. (See section Evaluating Macro Arguments Repeatedly.)

Inline functions can be used and open-coded later on in the same file, following the definition, just like macros.

Other Topics Related to Functions

Here is a table of several functions that do things related to function calling and function definitions. They are documented elsewhere, but we provide cross references here.

apply
See section Calling Functions.
autoload
See section Autoload.
call-interactively
See section Interactive Call.
commandp
See section Interactive Call.
documentation
See section Access to Documentation Strings.
eval
See section Eval.
funcall
See section Calling Functions.
function
See section Anonymous Functions.
ignore
See section Calling Functions.
indirect-function
See section Symbol Function Indirection.
interactive
See section Using interactive.
interactive-p
See section Interactive Call.
mapatoms
See section Creating and Interning Symbols.
mapcar
See section Mapping Functions.
map-char-table
See section Char-Tables.
mapconcat
See section Mapping Functions.
undefined
See section Key Lookup.
Macros

Macros enable you to define new control constructs and other language features. A macro is defined much like a function, but instead of telling how to compute a value, it tells how to compute another Lisp expression which will in turn compute the value. We call this expression the expansion of the macro.

Macros can do this because they operate on the unevaluated expressions for the arguments, not on the argument values as functions do. They can therefore construct an expansion containing these argument expressions or parts of them.

If you are using a macro to do something an ordinary function could do, just for the sake of speed, consider using an inline function instead. See section Inline Functions.

A Simple Example of a Macro

Suppose we would like to define a Lisp construct to increment a variable value, much like the ++ operator in C. We would like to write (inc x) and have the effect of (setq x (1+ x)). Here's a macro definition that does the job:
(defmacro inc (var)
   (list 'setq var (list '1+ var)))
When this is called with (inc x), the argument var is the symbol x---not the value of x, as it would be in a function. The body of the macro uses this to construct the expansion, which is (setq x (1+ x)). Once the macro definition returns this expansion, Lisp proceeds to evaluate it, thus incrementing x.

Expansion of a Macro Call

A macro call looks just like a function call in that it is a list which starts with the name of the macro. The rest of the elements of the list are the arguments of the macro.

Evaluation of the macro call begins like evaluation of a function call except for one crucial difference: the macro arguments are the actual expressions appearing in the macro call. They are not evaluated before they are given to the macro definition. By contrast, the arguments of a function are results of evaluating the elements of the function call list.

Having obtained the arguments, Lisp invokes the macro definition just as a function is invoked. The argument variables of the macro are bound to the argument values from the macro call, or to a list of them in the case of a &rest argument. And the macro body executes and returns its value just as a function body does.

The second crucial difference between macros and functions is that the value returned by the macro body is not the value of the macro call. Instead, it is an alternate expression for computing that value, also known as the expansion of the macro. The Lisp interpreter proceeds to evaluate the expansion as soon as it comes back from the macro.

Since the expansion is evaluated in the normal manner, it may contain calls to other macros. It may even be a call to the same macro, though this is unusual.

You can see the expansion of a given macro call by calling macroexpand.

Function: macroexpand form &optional environment
This function expands form, if it is a macro call. If the result is another macro call, it is expanded in turn, until something which is not a macro call results. That is the value returned by macroexpand. If form is not a macro call to begin with, it is returned as given.

Note that macroexpand does not look at the subexpressions of form (although some macro definitions may do so). Even if they are macro calls themselves, macroexpand does not expand them.

The function macroexpand does not expand calls to inline functions. Normally there is no need for that, since a call to an inline function is no harder to understand than a call to an ordinary function.

If environment is provided, it specifies an alist of macro definitions that shadow the currently defined macros. Byte compilation uses this feature.
(defmacro inc (var)
    (list 'setq var (list '1+ var)))
     => inc

(macroexpand '(inc r))
     => (setq r (1+ r))

(defmacro inc2 (var1 var2)
    (list 'progn (list 'inc var1) (list 'inc var2)))
     => inc2

(macroexpand '(inc2 r s))
     => (progn (inc r) (inc s))  ; inc not expanded here.
Macros and Byte Compilation

You might ask why we take the trouble to compute an expansion for a macro and then evaluate the expansion. Why not have the macro body produce the desired results directly? The reason has to do with compilation.

When a macro call appears in a Lisp program being compiled, the Lisp compiler calls the macro definition just as the interpreter would, and receives an expansion. But instead of evaluating this expansion, it compiles the expansion as if it had appeared directly in the program. As a result, the compiled code produces the value and side effects intended for the macro, but executes at full compiled speed. This would not work if the macro body computed the value and side effects itself--they would be computed at compile time, which is not useful.

In order for compilation of macro calls to work, the macros must already be defined in Lisp when the calls to them are compiled. The compiler has a special feature to help you do this: if a file being compiled contains a defmacro form, the macro is defined temporarily for the rest of the compilation of that file. To make this feature work, you must put the defmacro in the same file where it is used, and before its first use.

Byte-compiling a file executes any require calls at top-level in the file. This is in case the file needs the required packages for proper compilation. One way to ensure that necessary macro definitions are available during compilation is to require the files that define them (see section Features). To avoid loading the macro definition files when someone runs the compiled program, write eval-when-compile around the require calls (see section Evaluation During Compilation).

Defining Macros

A Lisp macro is a list whose CAR is macro. Its CDR should be a function; expansion of the macro works by applying the function (with apply) to the list of unevaluated argument-expressions from the macro call.

It is possible to use an anonymous Lisp macro just like an anonymous function, but this is never done, because it does not make sense to pass an anonymous macro to functionals such as mapcar. In practice, all Lisp macros have names, and they are usually defined with the special form defmacro.

Special Form: defmacro name argument-list body-forms...
defmacro defines the symbol name as a macro that looks like this:
(macro lambda argument-list . body-forms)
(Note that the CDR of this list is a function--a lambda expression.) This macro object is stored in the function cell of name. The value returned by evaluating the defmacro form is name, but usually we ignore this value.

The shape and meaning of argument-list is the same as in a function, and the keywords &rest and &optional may be used (see section Other Features of Argument Lists). Macros may have a documentation string, but any interactive declaration is ignored since macros cannot be called interactively.

Backquote

Macros often need to construct large list structures from a mixture of constants and nonconstant parts. To make this easier, use the ``' syntax (usually called backquote).

Backquote allows you to quote a list, but selectively evaluate elements of that list. In the simplest case, it is identical to the special form quote (see section Quoting). For example, these two forms yield identical results:
`(a list of (+ 2 3) elements)
     => (a list of (+ 2 3) elements)
'(a list of (+ 2 3) elements)
     => (a list of (+ 2 3) elements)
The special marker `,' inside of the argument to backquote indicates a value that isn't constant. Backquote evaluates the argument of `,' and puts the value in the list structure:
(list 'a 'list 'of (+ 2 3) 'elements)
     => (a list of 5 elements)
`(a list of ,(+ 2 3) elements)
     => (a list of 5 elements)
Substitution with `,' is allowed at deeper levels of the list structure also. For example:
(defmacro t-becomes-nil (variable)
  `(if (eq ,variable t)
       (setq ,variable nil)))

(t-becomes-nil foo)
     == (if (eq foo t) (setq foo nil))
You can also splice an evaluated value into the resulting list, using the special marker `,@'. The elements of the spliced list become elements at the same level as the other elements of the resulting list. The equivalent code without using ``' is often unreadable. Here are some examples:
(setq some-list '(2 3))
     => (2 3)
(cons 1 (append some-list '(4) some-list))
     => (1 2 3 4 2 3)
`(1 ,@some-list 4 ,@some-list)
     => (1 2 3 4 2 3)

(setq list '(hack foo bar))
     => (hack foo bar)
(cons 'use
  (cons 'the
    (cons 'words (append (cdr list) '(as elements)))))
     => (use the words foo bar as elements)
`(use the words ,@(cdr list) as elements)
     => (use the words foo bar as elements)
In old Emacs versions, before version 19.29, ``' used a different syntax which required an extra level of parentheses around the entire backquote construct. Likewise, each `,' or `,@' substitution required an extra level of parentheses surrounding both the `,' or `,@' and the following expression. The old syntax required whitespace between the ``', `,' or `,@' and the following expression.

This syntax is still accepted, for compatibility with old Emacs versions, but we recommend not using it in new programs.

Common Problems Using Macros

The basic facts of macro expansion have counterintuitive consequences. This section describes some important consequences that can lead to trouble, and rules to follow to avoid trouble.

Evaluating Macro Arguments Repeatedly

When defining a macro you must pay attention to the number of times the arguments will be evaluated when the expansion is executed. The following macro (used to facilitate iteration) illustrates the problem. This macro allows us to write a simple "for" loop such as one might find in Pascal.
(defmacro for (var from init to final do &rest body)
  "Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
  (list 'let (list (list var init))
        (cons 'while (cons (list '<= var final)
                           (append body (list (list 'inc var)))))))
=> for

(for i from 1 to 3 do
   (setq square (* i i))
   (princ (format "\n%d %d" i square)))
==>
(let ((i 1))
  (while (<= i 3)
    (setq square (* i i))
    (princ (format "%d      %d" i square))
    (inc i)))

     -|1       1
     -|2       4
     -|3       9
=> nil
The arguments from, to, and do in this macro are "syntactic sugar"; they are entirely ignored. The idea is that you will write noise words (such as from, to, and do) in those positions in the macro call.

Here's an equivalent definition simplified through use of backquote:
(defmacro for (var from init to final do &rest body)
  "Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
  `(let ((,var ,init))
     (while (<= ,var ,final)
       ,@body
       (inc ,var))))
Both forms of this definition (with backquote and without) suffer from the defect that final is evaluated on every iteration. If final is a constant, this is not a problem. If it is a more complex form, say (long-complex-calculation x), this can slow down the execution significantly. If final has side effects, executing it more than once is probably incorrect.

A well-designed macro definition takes steps to avoid this problem by producing an expansion that evaluates the argument expressions exactly once unless repeated evaluation is part of the intended purpose of the macro. Here is a correct expansion for the for macro:
(let ((i 1)
      (max 3))
  (while (<= i max)
    (setq square (* i i))
    (princ (format "%d      %d" i square))
    (inc i)))
Here is a macro definition that creates this expansion:
(defmacro for (var from init to final do &rest body)
  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  `(let ((,var ,init)
         (max ,final))
     (while (<= ,var max)
       ,@body
       (inc ,var))))
Unfortunately, this fix introduces another problem, described in the following section.

Local Variables in Macro Expansions

The new definition of for has a new problem: it introduces a local variable named max which the user does not expect. This causes trouble in examples such as the following:
(let ((max 0))
  (for x from 0 to 10 do
    (let ((this (frob x)))
      (if (< max this)
          (setq max this)))))
The references to max inside the body of the for, which are supposed to refer to the user's binding of max, really access the binding made by for.

The way to correct this is to use an uninterned symbol instead of max (see section Creating and Interning Symbols). The uninterned symbol can be bound and referred to just like any other symbol, but since it is created by for, we know that it cannot already appear in the user's program. Since it is not interned, there is no way the user can put it into the program later. It will never appear anywhere except where put by for. Here is a definition of for that works this way:
(defmacro for (var from init to final do &rest body)
  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  (let ((tempvar (make-symbol "max")))
    `(let ((,var ,init)
           (,tempvar ,final))
       (while (<= ,var ,tempvar)
         ,@body
         (inc ,var)))))
This creates an uninterned symbol named max and puts it in the expansion instead of the usual interned symbol max that appears in expressions ordinarily.

Evaluating Macro Arguments in Expansion

Another problem can happen if the macro definition itself evaluates any of the macro argument expressions, such as by calling eval (see section Eval). If the argument is supposed to refer to the user's variables, you may have trouble if the user happens to use a variable with the same name as one of the macro arguments. Inside the macro body, the macro argument binding is the most local binding of this variable, so any references inside the form being evaluated do refer to it. Here is an example:
(defmacro foo (a)
  (list 'setq (eval a) t))
     => foo
(setq x 'b)
(foo x) ==> (setq b t)
     => t                  ; and b has been set.
;; but
(setq a 'c)
(foo a) ==> (setq a t)
     => t                  ; but this set a, not c.
It makes a difference whether the user's variable is named a or x, because a conflicts with the macro argument variable a.

Another problem with calling eval in a macro definition is that it probably won't do what you intend in a compiled program. The byte-compiler runs macro definitions while compiling the program, when the program's own computations (which you might have wished to access with eval) don't occur and its local variable bindings don't exist.

To avoid these problems, don't evaluate an argument expression while computing the macro expansion. Instead, substitute the expression into the macro expansion, so that its value will be computed as part of executing the expansion. This is how the other examples in this chapter work.

How Many Times is the Macro Expanded?

Occasionally problems result from the fact that a macro call is expanded each time it is evaluated in an interpreted function, but is expanded only once (during compilation) for a compiled function. If the macro definition has side effects, they will work differently depending on how many times the macro is expanded.

Therefore, you should avoid side effects in computation of the macro expansion, unless you really know what you are doing.

One special kind of side effect can't be avoided: constructing Lisp objects. Almost all macro expansions include constructed lists; that is the whole point of most macros. This is usually safe; there is just one case where you must be careful: when the object you construct is part of a quoted constant in the macro expansion.

If the macro is expanded just once, in compilation, then the object is constructed just once, during compilation. But in interpreted execution, the macro is expanded each time the macro call runs, and this means a new object is constructed each time.

In most clean Lisp code, this difference won't matter. It can matter only if you perform side-effects on the objects constructed by the macro definition. Thus, to avoid trouble, avoid side effects on objects constructed by macro definitions. Here is an example of how such side effects can get you into trouble:
(defmacro empty-object ()
  (list 'quote (cons nil nil)))

(defun initialize (condition)
  (let ((object (empty-object)))
    (if condition
        (setcar object condition))
    object))
If initialize is interpreted, a new list (nil) is constructed each time initialize is called. Thus, no side effect survives between calls. If initialize is compiled, then the macro empty-object is expanded during compilation, producing a single "constant" (nil) that is reused and altered each time initialize is called.

One way to avoid pathological cases like this is to think of empty-object as a funny kind of constant, not as a memory allocation construct. You wouldn't use setcar on a constant such as '(nil), so naturally you won't use it on (empty-object) either.

Writing Customization Definitions

This chapter describes how to declare user options for customization, and also customization groups for classifying them. We use the term customization item to include both kinds of customization definitions--as well as face definitions (see section Defining Faces).

Common Keywords for All Kinds of Items

All kinds of customization declarations (for variables and groups, and for faces) accept keyword arguments for specifying various information. This section describes some keywords that apply to all kinds.

All of these keywords, except :tag, can be used more than once in a given item. Each use of the keyword has an independent effect. The keyword :tag is an exception because any given item can only display one name.

:tag name
Use name, a string, instead of the item's name, to label the item in customization menus and buffers.
:group group
Put this customization item in group group. When you use :group in a defgroup, it makes the new group a subgroup of group. If you use this keyword more than once, you can put a single item into more than one group. Displaying any of those groups will show this item. Be careful not to overdo this!
:link link-data
Include an external link after the documentation string for this item. This is a sentence containing an active field which references some other documentation. There are three alternatives you can use for link-data:
(custom-manual info-node)
Link to an Info node; info-node is a string which specifies the node name, as in "(emacs)Top". The link appears as `[manual]' in the customization buffer.
(info-link info-node)
Like custom-manual except that the link appears in the customization buffer with the Info node name.
(url-link url)
Link to a web page; url is a string which specifies the URL. The link appears in the customization buffer as url. You can specify the text to use in the customization buffer by adding :tag name after the first element of the link-data; for example, (info-link :tag "foo" "(emacs)Top") makes a link to the Emacs manual which appears in the buffer as `foo'. An item can have more than one external link; however, most items have none at all.
:load file
Load file file (a string) before displaying this customization item. Loading is done with load-library, and only if the file is not already loaded.
:require feature
Require feature feature (a symbol) when installing a value for this item (an option or a face) that was saved using the customization feature. This is done by calling require. The most common reason to use :require is when a variable enables a feature such as a minor mode, and just setting the variable won't have any effect unless the code which implements the mode is loaded.
Defining Custom Groups

Each Emacs Lisp package should have one main customization group which contains all the options, faces and other groups in the package. If the package has a small number of options and faces, use just one group and put everything in it. When there are more than twelve or so options and faces, then you should structure them into subgroups, and put the subgroups under the package's main customization group. It is OK to put some of the options and faces in the package's main group alongside the subgroups.

The package's main or only group should be a member of one or more of the standard customization groups. (To display the full list of them, use M-x customize.) Choose one or more of them (but not too many), and add your group to each of them using the :group keyword.

The way to declare new customization groups is with defgroup.

Macro: defgroup group members doc [keyword value]...
Declare group as a customization group containing members. Do not quote the symbol group. The argument doc specifies the documentation string for the group.

The argument members is a list specifying an initial set of customization items to be members of the group. However, most often members is nil, and you specify the group's members by using the :group keyword when defining those members.

If you want to specify group members through members, each element should have the form (name widget). Here name is a symbol, and widget is a widget type for editing that symbol. Useful widgets are custom-variable for a variable, custom-face for a face, and custom-group for a group.

In addition to the common keywords (see section Common Keywords for All Kinds of Items), you can use this keyword in defgroup:

:prefix prefix
If the name of an item in the group starts with prefix, then the tag for that item is constructed (by default) by omitting prefix. One group can have any number of prefixes.
The prefix-discarding feature is currently turned off, which means that :prefix currently has no effect. We did this because we found that discarding the specified prefixes often led to confusing names for options. This happened because the people who wrote the defgroup definitions for various groups added :prefix keywords whenever they make logical sense--that is, whenever the variables in the library have a common prefix.

In order to obtain good results with :prefix, it would be necessary to check the specific effects of discarding a particular prefix, given the specific items in a group and their names and documentation. If the resulting text is not clear, then :prefix should not be used in that case.

It should be possible to recheck all the customization groups, delete the :prefix specifications which give unclear results, and then turn this feature back on, if someone would like to do the work.

Defining Customization Variables

Use defcustom to declare user-editable variables.

Macro: defcustom option default doc [keyword value]...
Declare option as a customizable user option variable. Do not quote option. The argument doc specifies the documentation string for the variable.

If option is void, defcustom initializes it to default. default should be an expression to compute the value; be careful in writing it, because it can be evaluated on more than one occasion.

defcustom accepts the following additional keywords:

:type type
Use type as the data type for this option. It specifies which values are legitimate, and how to display the value. See section Customization Types, for more information.
:options list
Specify list as the list of reasonable values for use in this option. Currently this is meaningful only when the type is hook. In that case, the elements of list should be functions that are useful as elements of the hook value. The user is not restricted to using only these functions, but they are offered as convenient alternatives.
:version version
This option specifies that the variable was first introduced, or its default value was changed, in Emacs version version. The value version must be a string. For example,
(defcustom foo-max 34
  "*Maximum number of foo's allowed."
  :type 'integer
  :group 'foo
  :version "20.3")
:set setfunction
Specify setfunction as the way to change the value of this option. The function setfunction should take two arguments, a symbol and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting the option as a Lisp variable). The default for setfunction is set-default.
:get getfunction
Specify getfunction as the way to extract the value of this option. The function getfunction should take one argument, a symbol, and should return the "current value" for that symbol (which need not be the symbol's Lisp value). The default is default-value.
:initialize function
function should be a function used to initialize the variable when the defcustom is evaluated. It should take two arguments, the symbol and value. Here are some predefined functions meant for use in this way:
custom-initialize-set
Use the variable's :set function to initialize the variable, but do not reinitialize it if it is already non-void. This is the default :initialize function.
custom-initialize-default
Like custom-initialize-set, but use the function set-default to set the variable, instead of the variable's :set function. This is the usual choice for a variable whose :set function enables or disables a minor mode; with this choice, defining the variable will not call the minor mode function, but customizing the variable will do so.
custom-initialize-reset
Always use the :set function to initialize the variable. If the variable is already non-void, reset it by calling the :set function using the current value (returned by the :get method).
custom-initialize-changed
Use the :set function to initialize the variable, if it is already set or has been customized; otherwise, just use set-default.
The :require option is useful for an option that turns on the operation of a certain feature. Assuming that the package is coded to check the value of the option, you still need to arrange for the package to be loaded. You can do that with :require. See section Common Keywords for All Kinds of Items. Here is an example, from the library `paren.el':
(defcustom show-paren-mode nil
  "Toggle Show Paren mode@enddots{}"
  :set (lambda (symbol value)
         (show-paren-mode (or value 0)))
  :initialize 'custom-initialize-default
  :type 'boolean
  :group 'paren-showing
  :require 'paren)
Internally, defcustom uses the symbol property standard-value to record the expression for the default value, and saved-value to record the value saved by the user with the customization buffer. The saved-value property is actually a list whose car is an expression which evaluates to the value.

Customization Types

When you define a user option with defcustom, you must specify its customization type. That is a Lisp object which describes (1) which values are legitimate and (2) how to display the value in the customization buffer for editing.

You specify the customization type in defcustom with the :type keyword. The argument of :type is evaluated; since types that vary at run time are rarely useful, normally you use a quoted constant. For example:
(defcustom diff-command "diff"
  "*The command to use to run diff."
  :type '(string)
  :group 'diff)
In general, a customization type is a list whose first element is a symbol, one of the customization type names defined in the following sections. After this symbol come a number of arguments, depending on the symbol. Between the type symbol and its arguments, you can optionally write keyword-value pairs (see section Type Keywords).

Some of the type symbols do not use any arguments; those are called simple types. For a simple type, if you do not use any keyword-value pairs, you can omit the parentheses around the type symbol. For example just string as a customization type is equivalent to (string).

Simple Types

This section describes all the simple customization types.

sexp
The value may be any Lisp object that can be printed and read back. You can use sexp as a fall-back for any option, if you don't want to take the time to work out a more specific type to use.
integer
The value must be an integer, and is represented textually in the customization buffer.
number
The value must be a number, and is represented textually in the customization buffer.
string
The value must be a string, and the customization buffer shows just the contents, with no delimiting `"' characters and no quoting with `\'.
regexp
Like string except that the string must be a valid regular expression.
character
The value must be a character code. A character code is actually an integer, but this type shows the value by inserting the character in the buffer, rather than by showing the number.
file
The value must be a file name, and you can do completion with M-TAB.
(file :must-match t)
The value must be a file name for an existing file, and you can do completion with M-TAB.
directory
The value must be a directory name, and you can do completion with M-TAB.
hook
The value must be a list of functions (or a single function, but that is obsolete usage). This customization type is used for hook variables. You can use the :options keyword in a hook variable's defcustom to specify a list of functions recommended for use in the hook; see section Defining Customization Variables.
symbol
The value must be a symbol. It appears in the customization buffer as the name of the symbol.
function
The value must be either a lambda expression or a function name. When it is a function name, you can do completion with M-TAB.
variable
The value must be a variable name, and you can do completion with M-TAB.
face
The value must be a symbol which is a face name, and you can do completion with M-TAB.
boolean
The value is boolean--either nil or t. Note that by using choice and const together (see the next section), you can specify that the value must be nil or t, but also specify the text to describe each value in a way that fits the specific meaning of the alternative.
Composite Types

When none of the simple types is appropriate, you can use composite types, which build new types from other types. Here are several ways of doing that:

(restricted-sexp :match-alternatives criteria)
The value may be any Lisp object that satisfies one of criteria. criteria should be a list, and each element should be one of these possibilities:

A predicate--that is, a function of one argument that has no side effects, and returns either nil or non-nil according to the argument. Using a predicate in the list says that objects for which the predicate returns non-nil are acceptable.
A quoted constant--that is, 'object. This sort of element in the list says that object itself is an acceptable value.
For example,
(restricted-sexp :match-alternatives
                 (integerp 't 'nil))
allows integers, t and nil as legitimate values. The customization buffer shows all legitimate values using their read syntax, and the user edits them textually.
(cons car-type cdr-type)
The value must be a cons cell, its CAR must fit car-type, and its CDR must fit cdr-type. For example, (cons string symbol) is a customization type which matches values such as ("foo" . foo). In the customization buffer, the CAR and the CDR are displayed and edited separately, each according to the type that you specify for it.
(list element-types...)
The value must be a list with exactly as many elements as the element-types you have specified; and each element must fit the corresponding element-type. For example, (list integer string function) describes a list of three elements; the first element must be an integer, the second a string, and the third a function. In the customization buffer, each element is displayed and edited separately, according to the type specified for it.
(vector element-types...)
Like list except that the value must be a vector instead of a list. The elements work the same as in list.
(choice alternative-types...)
The value must fit at least one of alternative-types. For example, (choice integer string) allows either an integer or a string. In the customization buffer, the user selects one of the alternatives using a menu, and can then edit the value in the usual way for that alternative. Normally the strings in this menu are determined automatically from the choices; however, you can specify different strings for the menu by including the :tag keyword in the alternatives. For example, if an integer stands for a number of spaces, while a string is text to use verbatim, you might write the customization type this way,
(choice (integer :tag "Number of spaces")
        (string :tag "Literal text"))
so that the menu offers `Number of spaces' and `Literal Text'. In any alternative for which nil is not a valid value, other than a const, you should specify a valid default for that alternative using the :value keyword. See section Type Keywords.
(const value)
The value must be value---nothing else is allowed. The main use of const is inside of choice. For example, (choice integer (const nil)) allows either an integer or nil. :tag is often used with const, inside of choice. For example,
(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (const :tag "Ask" foo))
describes a variable for which t means yes, nil means no, and foo means "ask."
(other value)
This alternative can match any Lisp value, but if the user chooses this alternative, that selects the value value. The main use of other is as the last element of choice. For example,
(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (other :tag "Ask" foo))
describes a variable for which t means yes, nil means no, and anything else means "ask." If the user chooses `Ask' from the menu of alternatives, that specifies the value foo; but any other value (not t, nil or foo) displays as `Ask', just like foo.
(function-item function)
Like const, but used for values which are functions. This displays the documentation string as well as the function name. The documentation string is either the one you specify with :doc, or function's own documentation string.
(variable-item variable)
Like const, but used for values which are variable names. This displays the documentation string as well as the variable name. The documentation string is either the one you specify with :doc, or variable's own documentation string.
(set elements...)
The value must be a list and each element of the list must be one of the elements specified. This appears in the customization buffer as a checklist.
(repeat element-type)
The value must be a list and each element of the list must fit the type element-type. This appears in the customization buffer as a list of elements, with `[INS]' and `[DEL]' buttons for adding more elements or removing elements.
Splicing into Lists

The :inline feature lets you splice a variable number of elements into the middle of a list or vector. You use it in a set, choice or repeat type which appears among the element-types of a list or vector.

Normally, each of the element-types in a list or vector describes one and only one element of the list or vector. Thus, if an element-type is a repeat, that specifies a list of unspecified length which appears as one element.

But when the element-type uses :inline, the value it matches is merged directly into the containing sequence. For example, if it matches a list with three elements, those become three elements of the overall sequence. This is analogous to using `,@' in the backquote construct.

For example, to specify a list whose first element must be t and whose remaining arguments should be zero or more of foo and bar, use this customization type:
(list (const t) (set :inline t foo bar))
This matches values such as (t), (t foo), (t bar) and (t foo bar).

When the element-type is a choice, you use :inline not in the choice itself, but in (some of) the alternatives of the choice. For example, to match a list which must start with a file name, followed either by the symbol t or two strings, use this customization type:
(list file
      (choice (const t)
              (list :inline t string string)))
If the user chooses the first alternative in the choice, then the overall list has two elements and the second element is t. If the user chooses the second alternative, then the overall list has three elements and the second and third must be strings.

Type Keywords

You can specify keyword-argument pairs in a customization type after the type name symbol. Here are the keywords you can use, and their meanings:

:value default
This is used for a type that appears as an alternative inside of choice; it specifies the default value to use, at first, if and when the user selects this alternative with the menu in the customization buffer. Of course, if the actual value of the option fits this alternative, it will appear showing the actual value, not default. If nil is not a valid value for the alternative, then it is essential to specify a valid default with :value.
:format format-string
This string will be inserted in the buffer to represent the value corresponding to the type. The following `%' escapes are available for use in format-string:
`%[button%]'
Display the text button marked as a button. The :action attribute specifies what the button will do if the user invokes it; its value is a function which takes two arguments--the widget which the button appears in, and the event. There is no way to specify two different buttons with different actions.
`%{sample%}'
Show sample in a special face specified by :sample-face.
`%v'
Substitute the item's value. How the value is represented depends on the kind of item, and (for variables) on the customization type.
`%d'
Substitute the item's documentation string.
`%h'
Like `%d', but if the documentation string is more than one line, add an active field to control whether to show all of it or just the first line.
`%t'
Substitute the tag here. You specify the tag with the :tag keyword.
`%%'
Display a literal `%'.
:action action
Perform action if the user clicks on a button.
:button-face face
Use the face face (a face name or a list of face names) for button text displayed with `%[...%]'.
:button-prefix prefix

:button-suffix suffix
These specify the text to display before and after a button. Each can be:
nil
No text is inserted.
a string
The string is inserted literally.
a symbol
The symbol's value is used.
:tag tag
Use tag (a string) as the tag for the value (or part of the value) that corresponds to this type.
:doc doc
Use doc as the documentation string for this value (or part of the value) that corresponds to this type. In order for this to work, you must specify a value for :format, and use `%d' or `%h' in that value. The usual reason to specify a documentation string for a type is to provide more information about the meanings of alternatives inside a :choice type or the parts of some other composite type.
:help-echo motion-doc
When you move to this item with widget-forward or widget-backward, it will display the string motion-doc in the echo area.
:match function
Specify how to decide whether a value matches the type. The corresponding value, function, should be a function that accepts two arguments, a widget and a value; it should return non-nil if the value is acceptable.
Loading

Loading a file of Lisp code means bringing its contents into the Lisp environment in the form of Lisp objects. Emacs finds and opens the file, reads the text, evaluates each form, and then closes the file.

The load functions evaluate all the expressions in a file just as the eval-current-buffer function evaluates all the expressions in a buffer. The difference is that the load functions read and evaluate the text in the file as found on disk, not the text in an Emacs buffer.

The loaded file must contain Lisp expressions, either as source code or as byte-compiled code. Each form in the file is called a top-level form. There is no special format for the forms in a loadable file; any form in a file may equally well be typed directly into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions.

A file containing Lisp code is often called a library. Thus, the "Rmail library" is a file containing code for Rmail mode. Similarly, a "Lisp library directory" is a directory of files containing Lisp code.

How Programs Do Loading

Emacs Lisp has several interfaces for loading. For example, autoload creates a placeholder object for a function defined in a file; trying to call the autoloading function loads the file to get the function's real definition (see section Autoload). require loads a file if it isn't already loaded (see section Features). Ultimately, all these facilities call the load function to do the work.

Function: load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file.

To find the file, load first looks for a file named `filename.elc', that is, for a file whose name is filename with `.elc' appended. If such a file exists, it is loaded. If there is no file by that name, then load looks for a file named `filename.el'. If that file exists, it is loaded. Finally, if neither of those names is found, load looks for a file named filename with nothing appended, and loads it if it exists. (The load function is not clever about looking at filename. In the perverse case of a file named `foo.el.el', evaluation of (load "foo.el") will indeed find it.)

If the optional argument nosuffix is non-nil, then the suffixes `.elc' and `.el' are not tried. In this case, you must specify the precise file name you want. By specifying the precise file name and using t for nosuffix, you can prevent perverse file names such as `foo.el.el' from being tried.

If the optional argument must-suffix is non-nil, then load insists that the file name used must end in either `.el' or `.elc', unless it contains an explicit directory name. If filename does not contain an explicit directory name, and does not end in a suffix, then load insists on adding one.

If filename is a relative file name, such as `foo' or `baz/foo.bar', load searches for the file using the variable load-path. It appends filename to each of the directories listed in load-path, and loads the first file it finds whose name matches. The current default directory is tried only if it is specified in load-path, where nil stands for the default directory. load tries all three possible suffixes in the first directory in load-path, then all three suffixes in the second directory, and so on. See section Library Search.

If you get a warning that `foo.elc' is older than `foo.el', it means you should consider recompiling `foo.el'. See section Byte Compilation.

When loading a source file (not compiled), load performs character set translation just as Emacs would do when visiting the file. See section Coding Systems.

Messages like `Loading foo...' and `Loading foo...done' appear in the echo area during loading unless nomessage is non-nil.

Any unhandled errors while loading a file terminate loading. If the load was done for the sake of autoload, any function definitions made during the loading are undone.

If load can't find the file to load, then normally it signals the error file-error (with `Cannot open load file filename'). But if missing-ok is non-nil, then load just returns nil.

You can use the variable load-read-function to specify a function for load to use instead of read for reading expressions. See below.

load returns t if the file loads successfully.

Command: load-file filename
This command loads the file filename. If filename is a relative file name, then the current default directory is assumed. load-path is not used, and suffixes are not appended. Use this command if you wish to specify precisely the file name to load.

Command: load-library library
This command loads the library named library. It is equivalent to load, except in how it reads its argument interactively.

Variable: load-in-progress
This variable is non-nil if Emacs is in the process of loading a file, and it is nil otherwise.

Variable: load-read-function
This variable specifies an alternate expression-reading function for load and eval-region to use instead of read. The function should accept one argument, just as read does.

Normally, the variable's value is nil, which means those functions should use read.

Note: Instead of using this variable, it is cleaner to use another, newer feature: to pass the function as the read-function argument to eval-region. See section Eval.

For information about how load is used in building Emacs, see section Building Emacs.

Library Search

When Emacs loads a Lisp library, it searches for the library in a list of directories specified by the variable load-path.

User Option: load-path
The value of this variable is a list of directories to search when loading files with load. Each element is a string (which must be a directory name) or nil (which stands for the current working directory).

The value of load-path is initialized from the environment variable EMACSLOADPATH, if that exists; otherwise its default value is specified in `emacs/src/paths.h' when Emacs is built. Then the list is expanded by adding subdirectories of the directories in the list.

The syntax of EMACSLOADPATH is the same as used for PATH; `:' (or `;', according to the operating system) separates directory names, and `.' is used for the current default directory. Here is an example of how to set your EMACSLOADPATH variable from a csh `.login' file:
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
Here is how to set it using sh:
export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
Here is an example of code you can place in a `.emacs' file to add several directories to the front of your default load-path:
(setq load-path
      (append (list nil "/user/bil/emacs"
                    "/usr/local/lisplib"
                    "~/emacs")
              load-path))
In this example, the path searches the current working directory first, followed then by the `/user/bil/emacs' directory, the `/usr/local/lisplib' directory, and the `~/emacs' directory, which are then followed by the standard directories for Lisp code.

Dumping Emacs uses a special value of load-path. If the value of load-path at the end of dumping is unchanged (that is, still the same special value), the dumped Emacs switches to the ordinary load-path value when it starts up, as described above. But if load-path has any other value at the end of dumping, that value is used for execution of the dumped Emacs also.

Therefore, if you want to change load-path temporarily for loading a few libraries in `site-init.el' or `site-load.el', you should bind load-path locally with let around the calls to load.

The default value of load-path, when running an Emacs which has been installed on the system, includes two special directories (and their subdirectories as well):
"/usr/local/share/emacs/version/site-lisp"
and
"/usr/local/share/emacs/site-lisp"
The first one is for locally installed packages for a particular Emacs version; the second is for locally installed packages meant for use with all installed Emacs versions.

There are several reasons why a Lisp package that works well in one Emacs version can cause trouble in another. Sometimes packages need updating for incompatible changes in Emacs; sometimes they depend on undocumented internal Emacs data that can change without notice; sometimes a newer Emacs version incorporates a version of the package, and should be used only with that version.

Emacs finds these directories' subdirectories and adds them to load-path when it starts up. Both immediate subdirectories and subdirectories multiple levels down are added to load-path.

Not all subdirectories are included, though. Subdirectories whose names do not start with a letter or digit are excluded. Subdirectories named `RCS' are excluded. Also, a subdirectory which contains a file named `.nosearch' is excluded. You can use these methods to prevent certain subdirectories of the `site-lisp' directories from being searched.

If you run Emacs from the directory where it was built--that is, an executable that has not been formally installed--then load-path normally contains two additional directories. These are the lisp and site-lisp subdirectories of the main build directory. (Both are represented as absolute file names.)

Command: locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library library. It searches for the library in the same way load does, and the argument nosuffix has the same meaning as in load: don't add suffixes `.elc' or `.el' to the specified name library.

If the path is non-nil, that list of directories is used instead of load-path.

When locate-library is called from a program, it returns the file name as a string. When the user runs locate-library interactively, the argument interactive-call is t, and this tells locate-library to display the file name in the echo area.

Loading Non-ASCII Characters

When Emacs Lisp programs contain string constants with non-ASCII characters, these can be represented within Emacs either as unibyte strings or as multibyte strings (see section Text Representations). Which representation is used depends on how the file is read into Emacs. If it is read with decoding into multibyte representation, the text of the Lisp program will be multibyte text, and its string constants will be multibyte strings. If a file containing Latin-1 characters (for example) is read without decoding, the text of the program will be unibyte text, and its string constants will be unibyte strings. See section Coding Systems.

To make the results more predictable, Emacs always performs decoding into the multibyte representation when loading Lisp files, even if it was started with the `--unibyte' option. This means that string constants with non-ASCII characters translate into multibyte strings. The only exception is when a particular file specifies no decoding.

The reason Emacs is designed this way is so that Lisp programs give predictable results, regardless of how Emacs was started. In addition, this enables programs that depend on using multibyte text to work even in a unibyte Emacs. Of course, such programs should be designed to notice whether the user prefers unibyte or multibyte text, by checking default-enable-multibyte-characters, and convert representations appropriately.

In most Emacs Lisp programs, the fact that non-ASCII strings are multibyte strings should not be noticeable, since inserting them in unibyte buffers converts them to unibyte automatically. However, if this does make a difference, you can force a particular Lisp file to be interpreted as unibyte by writing `-*-unibyte: t;-*-' in a comment on the file's first line. With that designator, the file will be unconditionally be interpreted as unibyte, even in an ordinary multibyte Emacs session.

Autoload

The autoload facility allows you to make a function or macro known in Lisp, but put off loading the file that defines it. The first call to the function automatically reads the proper file to install the real definition and other associated code, then runs the real definition as if it had been loaded all along.

There are two ways to set up an autoloaded function: by calling autoload, and by writing a special "magic" comment in the source before the real definition. autoload is the low-level primitive for autoloading; any Lisp program can call autoload at any time. Magic comments are the most convenient way to make a function autoload, for packages installed along with Emacs. These comments do nothing on their own, but they serve as a guide for the command update-file-autoloads, which constructs calls to autoload and arranges to execute them when Emacs is built.

Function: autoload function filename &optional docstring interactive type
This function defines the function (or macro) named function so as to load automatically from filename. The string filename specifies the file to load to get the real definition of function.

If filename does not contain either a directory name, or the suffix .el or .elc, then autoload insists on adding one of these suffixes, and it will not load from a file whose name is just filename with no added suffix.

The argument docstring is the documentation string for the function. Normally, this should be identical to the documentation string in the function definition itself. Specifying the documentation string in the call to autoload makes it possible to look at the documentation without loading the function's real definition.

If interactive is non-nil, that says function can be called interactively. This lets completion in M-x work without loading function's real definition. The complete interactive specification is not given here; it's not needed unless the user actually calls function, and when that happens, it's time to load the real definition.

You can autoload macros and keymaps as well as ordinary functions. Specify type as macro if function is really a macro. Specify type as keymap if function is really a keymap. Various parts of Emacs need to know this information without loading the real definition.

An autoloaded keymap loads automatically during key lookup when a prefix key's binding is the symbol function. Autoloading does not occur for other kinds of access to the keymap. In particular, it does not happen when a Lisp program gets the keymap from the value of a variable and calls define-key; not even if the variable name is the same symbol function.

If function already has a non-void function definition that is not an autoload object, autoload does nothing and returns nil. If the function cell of function is void, or is already an autoload object, then it is defined as an autoload object like this:
(autoload filename docstring interactive type)
For example,
(symbol-function 'run-prolog)
     => (autoload "prolog" 169681 t nil)
In this case, "prolog" is the name of the file to load, 169681 refers to the documentation string in the `emacs/etc/DOC-version' file (see section Documentation Basics), t means the function is interactive, and nil that it is not a macro or a keymap.

The autoloaded file usually contains other definitions and may require or provide one or more features. If the file is not completely loaded (due to an error in the evaluation of its contents), any function definitions or provide calls that occurred during the load are undone. This is to ensure that the next attempt to call any function autoloading from this file will try again to load the file. If not for this, then some of the functions in the file might be defined by the aborted load, but fail to work properly for the lack of certain subroutines not loaded successfully because they come later in the file.

If the autoloaded file fails to define the desired Lisp function or macro, then an error is signaled with data "Autoloading failed to define function function-name".

A magic autoload comment consists of `;;;###autoload', on a line by itself, just before the real definition of the function in its autoloadable source file. The command M-x update-file-autoloads writes a corresponding autoload call into `loaddefs.el'. Building Emacs loads `loaddefs.el' and thus calls autoload. M-x update-directory-autoloads is even more powerful; it updates autoloads for all files in the current directory.

The same magic comment can copy any kind of form into `loaddefs.el'. If the form following the magic comment is not a function definition, it is copied verbatim. You can also use a magic comment to execute a form at build time without executing it when the file itself is loaded. To do this, write the form on the same line as the magic comment. Since it is in a comment, it does nothing when you load the source file; but M-x update-file-autoloads copies it to `loaddefs.el', where it is executed while building Emacs.

The following example shows how doctor is prepared for autoloading with a magic comment:
;;;###autoload
(defun doctor ()
  "Switch to *doctor* buffer and start giving psychotherapy."
  (interactive)
  (switch-to-buffer "*doctor*")
  (doctor-mode))
Here's what that produces in `loaddefs.el':
(autoload 'doctor "doctor"
  "\
Switch to *doctor* buffer and start giving psychotherapy."
  t)
The backslash and newline immediately following the double-quote are a convention used only in the preloaded Lisp files such as `loaddefs.el'; they tell make-docfile to put the documentation string in the `etc/DOC' file. See section Building Emacs.

Repeated Loading

You can load a given file more than once in an Emacs session. For example, after you have rewritten and reinstalled a function definition by editing it in a buffer, you may wish to return to the original version; you can do this by reloading the file it came from.

When you load or reload files, bear in mind that the load and load-library functions automatically load a byte-compiled file rather than a non-compiled file of similar name. If you rewrite a file that you intend to save and reinstall, you need to byte-compile the new version; otherwise Emacs will load the older, byte-compiled file instead of your newer, non-compiled file! If that happens, the message displayed when loading the file includes, `(compiled; note, source is newer)', to remind you to recompile it.

When writing the forms in a Lisp library file, keep in mind that the file might be loaded more than once. For example, think about whether each variable should be reinitialized when you reload the library; defvar does not change the value if the variable is already initialized. (See section Defining Global Variables.)

The simplest way to add an element to an alist is like this:
(setq minor-mode-alist
      (cons '(leif-mode " Leif") minor-mode-alist))
But this would add multiple elements if the library is reloaded. To avoid the problem, write this:
(or (assq 'leif-mode minor-mode-alist)
    (setq minor-mode-alist
          (cons '(leif-mode " Leif") minor-mode-alist)))
To add an element to a list just once, you can also use add-to-list (see section How to Alter a Variable Value).

Occasionally you will want to test explicitly whether a library has already been loaded. Here's one way to test, in a library, whether it has been loaded before:
(defvar foo-was-loaded nil)

(unless foo-was-loaded
  execute-first-time-only
  (setq foo-was-loaded t))
If the library uses provide to provide a named feature, you can use featurep earlier in the file to test whether the provide call has been executed before.

Features

provide and require are an alternative to autoload for loading files automatically. They work in terms of named features. Autoloading is triggered by calling a specific function, but a feature is loaded the first time another program asks for it by name.

A feature name is a symbol that stands for a collection of functions, variables, etc. The file that defines them should provide the feature. Another program that uses them may ensure they are defined by requiring the feature. This loads the file of definitions if it hasn't been loaded already.

To require the presence of a feature, call require with the feature name as argument. require looks in the global variable features to see whether the desired feature has been provided already. If not, it loads the feature from the appropriate file. This file should call provide at the top level to add the feature to features; if it fails to do so, require signals an error.

For example, in `emacs/lisp/prolog.el', the definition for run-prolog includes the following code:
(defun run-prolog ()
  "Run an inferior Prolog process, with I/O via buffer *prolog*."
  (interactive)
  (require 'comint)
  (switch-to-buffer (make-comint "prolog" prolog-program-name))
  (inferior-prolog-mode))
The expression (require 'comint) loads the file `comint.el' if it has not yet been loaded. This ensures that make-comint is defined. Features are normally named after the files that provide them, so that require need not be given the file name.

The `comint.el' file contains the following top-level expression:
(provide 'comint)
This adds comint to the global features list, so that (require 'comint) will henceforth know that nothing needs to be done.

When require is used at top level in a file, it takes effect when you byte-compile that file (see section Byte Compilation) as well as when you load it. This is in case the required package contains macros that the byte compiler must know about.

Although top-level calls to require are evaluated during byte compilation, provide calls are not. Therefore, you can ensure that a file of definitions is loaded before it is byte-compiled by including a provide followed by a require for the same feature, as in the following example.
(provide 'my-feature)  ; Ignored by byte compiler,
                       ;   evaluated by load.
(require 'my-feature)  ; Evaluated by byte compiler.
The compiler ignores the provide, then processes the require by loading the file in question. Loading the file does execute the provide call, so the subsequent require call does nothing when the file is loaded.

Function: provide feature
This function announces that feature is now loaded, or being loaded, into the current Emacs session. This means that the facilities associated with feature are or will be available for other Lisp programs.

The direct effect of calling provide is to add feature to the front of the list features if it is not already in the list. The argument feature must be a symbol. provide returns feature.
features
     => (bar bish)

(provide 'foo)
     => foo
features
     => (foo bar bish)
When a file is loaded to satisfy an autoload, and it stops due to an error in the evaluating its contents, any function definitions or provide calls that occurred during the load are undone. See section Autoload.

Function: require feature &optional filename
This function checks whether feature is present in the current Emacs session (using (featurep feature); see below). The argument feature must be a symbol.

If the feature is not present, then require loads filename with load. If filename is not supplied, then the name of the symbol feature is used as the base file name to load. However, in this case, require insists on finding feature with an added suffix; a file whose name is just feature won't be used.

If loading the file fails to provide feature, require signals an error, `Required feature feature was not provided'.

Function: featurep feature
This function returns t if feature has been provided in the current Emacs session (i.e., if feature is a member of features.)

Variable: features
The value of this variable is a list of symbols that are the features loaded in the current Emacs session. Each symbol was put in this list with a call to provide. The order of the elements in the features list is not significant.

Unloading

You can discard the functions and variables loaded by a library to reclaim memory for other Lisp objects. To do this, use the function unload-feature:

Command: unload-feature feature &optional force
This command unloads the library that provided feature feature. It undefines all functions, macros, and variables defined in that library with defun, defalias, defsubst, defmacro, defconst, defvar, and defcustom. It then restores any autoloads formerly associated with those symbols. (Loading saves these in the autoload property of the symbol.)

Before restoring the previous definitions, unload-feature runs remove-hook to remove functions in the library from certain hooks. These hooks include variables whose names end in `hook' or `-hooks', plus those listed in loadhist-special-hooks. This is to prevent Emacs from ceasing to function because important hooks refer to functions that are no longer defined.

If these measures are not sufficient to prevent malfunction, a library can define an explicit unload hook. If feature-unload-hook is defined, it is run as a normal hook before restoring the previous definitions, instead of the usual hook-removing actions. The unload hook ought to undo all the global state changes made by the library that might cease to work once the library is unloaded.

Ordinarily, unload-feature refuses to unload a library on which other loaded libraries depend. (A library a depends on library b if a contains a require for b.) If the optional argument force is non-nil, dependencies are ignored and you can unload any library.

The unload-feature function is written in Lisp; its actions are based on the variable load-history.

Variable: load-history
This variable's value is an alist connecting library names with the names of functions and variables they define, the features they provide, and the features they require.

Each element is a list and describes one library. The CAR of the list is the name of the library, as a string. The rest of the list is composed of these kinds of objects:

Symbols that were defined by this library.
Lists of the form (require . feature) indicating features that were required.
Lists of the form (provide . feature) indicating features that were provided.

The value of load-history may have one element whose CAR is nil. This element describes definitions made with eval-buffer on a buffer that is not visiting a file.

The command eval-region updates load-history, but does so by adding the symbols defined to the element for the file being visited, rather than replacing that element. See section Eval.

Preloaded libraries don't contribute to load-history.

Variable: loadhist-special-hooks
This variable holds a list of hooks to be scanned before unloading a library, to remove functions defined in the library.

Hooks for Loading

You can ask for code to be executed if and when a particular library is loaded, by calling eval-after-load.

Function: eval-after-load library form
This function arranges to evaluate form at the end of loading the library library, if and when library is loaded. If library is already loaded, it evaluates form right away.

The library name library must exactly match the argument of load. To get the proper results when an installed library is found by searching load-path, you should not include any directory names in library.

An error in form does not undo the load, but does prevent execution of the rest of form.

In general, well-designed Lisp programs should not use this feature. The clean and modular ways to interact with a Lisp library are (1) examine and set the library's variables (those which are meant for outside use), and (2) call the library's functions. If you wish to do (1), you can do it immediately--there is no need to wait for when the library is loaded. To do (2), you must load the library (preferably with require).

But it is OK to use eval-after-load in your personal customizations if you don't feel they must meet the design standards for programs meant for wider use.

Variable: after-load-alist
An alist of expressions to evaluate if and when particular libraries are loaded. Each element looks like this:
(filename forms...)
The function load checks after-load-alist in order to implement eval-after-load.

Byte Compilation

Emacs Lisp has a compiler that translates functions written in Lisp into a special representation called byte-code that can be executed more efficiently. The compiler replaces Lisp function definitions with byte-code. When a byte-code function is called, its definition is evaluated by the byte-code interpreter.

Because the byte-compiled code is evaluated by the byte-code interpreter, instead of being executed directly by the machine's hardware (as true compiled code is), byte-code is completely transportable from machine to machine without recompilation. It is not, however, as fast as true compiled code.

Compiling a Lisp file with the Emacs byte compiler always reads the file as multibyte text, even if Emacs was started with `--unibyte', unless the file specifies otherwise. This is so that compilation gives results compatible with running the same file without compilation. See section Loading Non-ASCII Characters.

In general, any version of Emacs can run byte-compiled code produced by recent earlier versions of Emacs, but the reverse is not true. A major incompatible change was introduced in Emacs version 19.29, and files compiled with versions since that one will definitely not run in earlier versions unless you specify a special option. See section Documentation Strings and Compilation. In addition, the modifier bits in keyboard characters were renumbered in Emacs 19.29; as a result, files compiled in versions before 19.29 will not work in subsequent versions if they contain character constants with modifier bits.

See section Debugging Problems in Compilation, for how to investigate errors occurring in byte compilation.

Performance of Byte-Compiled Code

A byte-compiled function is not as efficient as a primitive function written in C, but runs much faster than the version written in Lisp. Here is an example:
(defun silly-loop (n)
  "Return time before and after N iterations of a loop."
  (let ((t1 (current-time-string)))
    (while (> (setq n (1- n))
              0))
    (list t1 (current-time-string))))
=> silly-loop

(silly-loop 100000)
=> ("Fri Mar 18 17:25:57 1994"
    "Fri Mar 18 17:26:28 1994")  ; 31 seconds

(byte-compile 'silly-loop)
=> [Compiled code not shown]

(silly-loop 100000)
=> ("Fri Mar 18 17:26:52 1994"
    "Fri Mar 18 17:26:58 1994")  ; 6 seconds
In this example, the interpreted code required 31 seconds to run, whereas the byte-compiled code required 6 seconds. These results are representative, but actual results will vary greatly.

The Compilation Functions

You can byte-compile an individual function or macro definition with the byte-compile function. You can compile a whole file with byte-compile-file, or several files with byte-recompile-directory or batch-byte-compile.

The byte compiler produces error messages and warnings about each file in a buffer called `*Compile-Log*'. These report things in your program that suggest a problem but are not necessarily erroneous.

Be careful when writing macro calls in files that you may someday byte-compile. Macro calls are expanded when they are compiled, so the macros must already be defined for proper compilation. For more details, see section Macros and Byte Compilation.

Normally, compiling a file does not evaluate the file's contents or load the file. But it does execute any require calls at top level in the file. One way to ensure that necessary macro definitions are available during compilation is to require the file that defines them (see section Features). To avoid loading the macro definition files when someone runs the compiled program, write eval-when-compile around the require calls (see section Evaluation During Compilation).

Function: byte-compile symbol
This function byte-compiles the function definition of symbol, replacing the previous definition with the compiled one. The function definition of symbol must be the actual code for the function; i.e., the compiler does not follow indirection to another symbol. byte-compile returns the new, compiled definition of symbol.

If symbol's definition is a byte-code function object, byte-compile does nothing and returns nil. Lisp records only one function definition for any symbol, and if that is already compiled, non-compiled code is not available anywhere. So there is no way to "compile the same definition again."
(defun factorial (integer)
  "Compute factorial of INTEGER."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
=> factorial

(byte-compile 'factorial)
=>
#[(integer)
  "^H\301U\203^H^@\301\207\302^H\303^HS!\"\207"
  [integer 1 * factorial]
  4 "Compute factorial of INTEGER."]
The result is a byte-code function object. The string it contains is the actual byte-code; each character in it is an instruction or an operand of an instruction. The vector contains all the constants, variable names and function names used by the function, except for certain primitives that are coded as special instructions.

Command: compile-defun
This command reads the defun containing point, compiles it, and evaluates the result. If you use this on a defun that is actually a function definition, the effect is to install a compiled version of that function.

Command: byte-compile-file filename
This function compiles a file of Lisp code named filename into a file of byte-code. The output file's name is made by changing the `.el' suffix into `.elc'; if filename does not end in `.el', it adds `.elc' to the end of filename.

Compilation works by reading the input file one form at a time. If it is a definition of a function or macro, the compiled function or macro definition is written out. Other forms are batched together, then each batch is compiled, and written so that its compiled code will be executed when the file is read. All comments are discarded when the input file is read.

This command returns t. When called interactively, it prompts for the file name.
% ls -l push*
-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el

(byte-compile-file "~/emacs/push.el")
     => t

% ls -l push*
-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
-rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc
Command: byte-recompile-directory directory flag
This function recompiles every `.el' file in directory that needs recompilation. A file needs recompilation if a `.elc' file exists but is older than the `.el' file.

When a `.el' file has no corresponding `.elc' file, flag says what to do. If it is nil, these files are ignored. If it is non-nil, the user is asked whether to compile each such file.

The returned value of this command is unpredictable.

Function: batch-byte-compile
This function runs byte-compile-file on files specified on the command line. This function must be used only in a batch execution of Emacs, as it kills Emacs on completion. An error in one file does not prevent processing of subsequent files, but no output file will be generated for it, and the Emacs process will terminate with a nonzero status code.
% emacs -batch -f batch-byte-compile *.el
Function: byte-code code-string data-vector max-stack
This function actually interprets byte-code. A byte-compiled function is actually defined with a body that calls byte-code. Don't call this function yourself--only the byte compiler knows how to generate valid calls to this function.

In Emacs version 18, byte-code was always executed by way of a call to the function byte-code. Nowadays, byte-code is usually executed as part of a byte-code function object, and only rarely through an explicit call to byte-code.

Documentation Strings and Compilation

Functions and variables loaded from a byte-compiled file access their documentation strings dynamically from the file whenever needed. This saves space within Emacs, and makes loading faster because the documentation strings themselves need not be processed while loading the file. Actual access to the documentation strings becomes slower as a result, but this normally is not enough to bother users.

Dynamic access to documentation strings does have drawbacks:

If you delete or move the compiled file after loading it, Emacs can no longer access the documentation strings for the functions and variables in the file.
If you alter the compiled file (such as by compiling a new version), then further access to documentation strings in this file will give nonsense results.

If your site installs Emacs following the usual procedures, these problems will never normally occur. Installing a new version uses a new directory with a different name; as long as the old version remains installed, its files will remain unmodified in the places where they are expected to be.

However, if you have built Emacs yourself and use it from the directory where you built it, you will experience this problem occasionally if you edit and recompile Lisp files. When it happens, you can cure the problem by reloading the file after recompiling it.

Byte-compiled files made with recent versions of Emacs (since 19.29) will not load into older versions because the older versions don't support this feature. You can turn off this feature at compile time by setting byte-compile-dynamic-docstrings to nil; then you can compile files that will load into older Emacs versions. You can do this globally, or for one source file by specifying a file-local binding for the variable. One way to do that is by adding this string to the file's first line:
-*-byte-compile-dynamic-docstrings: nil;-*-
Variable: byte-compile-dynamic-docstrings
If this is non-nil, the byte compiler generates compiled files that are set up for dynamic loading of documentation strings.

The dynamic documentation string feature writes compiled files that use a special Lisp reader construct, `#@count'. This construct skips the next count characters. It also uses the `#$' construct, which stands for "the name of this file, as a string." It is usually best not to use these constructs in Lisp source files, since they are not designed to be clear to humans reading the file.

Dynamic Loading of Individual Functions

When you compile a file, you can optionally enable the dynamic function loading feature (also known as lazy loading). With dynamic function loading, loading the file doesn't fully read the function definitions in the file. Instead, each function definition contains a place-holder which refers to the file. The first time each function is called, it reads the full definition from the file, to replace the place-holder.

The advantage of dynamic function loading is that loading the file becomes much faster. This is a good thing for a file which contains many separate user-callable functions, if using one of them does not imply you will probably also use the rest. A specialized mode which provides many keyboard commands often has that usage pattern: a user may invoke the mode, but use only a few of the commands it provides.

The dynamic loading feature has certain disadvantages:

If you delete or move the compiled file after loading it, Emacs can no longer load the remaining function definitions not already loaded.
If you alter the compiled file (such as by compiling a new version), then trying to load any function not already loaded will yield nonsense results.

These problems will never happen in normal circumstances with installed Emacs files. But they are quite likely to happen with Lisp files that you are changing. The easiest way to prevent these problems is to reload the new compiled file immediately after each recompilation.

The byte compiler uses the dynamic function loading feature if the variable byte-compile-dynamic is non-nil at compilation time. Do not set this variable globally, since dynamic loading is desirable only for certain files. Instead, enable the feature for specific source files with file-local variable bindings. For example, you could do it by writing this text in the source file's first line:
-*-byte-compile-dynamic: t;-*-
Variable: byte-compile-dynamic
If this is non-nil, the byte compiler generates compiled files that are set up for dynamic function loading.

Function: fetch-bytecode function
This immediately finishes loading the definition of function from its byte-compiled file, if it is not fully loaded already. The argument function may be a byte-code function object or a function name.

Evaluation During Compilation

These features permit you to write code to be evaluated during compilation of a program.

Special Form: eval-and-compile body
This form marks body to be evaluated both when you compile the containing code and when you run it (whether compiled or not).

You can get a similar result by putting body in a separate file and referring to that file with require. That method is preferable when body is large.

Special Form: eval-when-compile body
This form marks body to be evaluated at compile time but not when the compiled program is loaded. The result of evaluation by the compiler becomes a constant which appears in the compiled program. If you load the source file, rather than compiling it, body is evaluated normally.

Common Lisp Note: At top level, this is analogous to the Common Lisp idiom (eval-when (compile eval) ...). Elsewhere, the Common Lisp `#.' reader macro (but not when interpreting) is closer to what eval-when-compile does.

Byte-Code Function Objects

Byte-compiled functions have a special data type: they are byte-code function objects.

Internally, a byte-code function object is much like a vector; however, the evaluator handles this data type specially when it appears as a function to be called. The printed representation for a byte-code function object is like that for a vector, with an additional `#' before the opening `['.

A byte-code function object must have at least four elements; there is no maximum number, but only the first six elements have any normal use. They are:

arglist
The list of argument symbols.
byte-code
The string containing the byte-code instructions.
constants
The vector of Lisp objects referenced by the byte code. These include symbols used as function names and variable names.
stacksize
The maximum stack size this function needs.
docstring
The documentation string (if any); otherwise, nil. The value may be a number or a list, in case the documentation string is stored in a file. Use the function documentation to get the real documentation string (see section Access to Documentation Strings).
interactive
The interactive spec (if any). This can be a string or a Lisp expression. It is nil for a function that isn't interactive.
Here's an example of a byte-code function object, in printed representation. It is the definition of the command backward-sexp.
#[(&optional arg)
  "^H\204^F^@\301^P\302^H[!\207"
  [arg 1 forward-sexp]
  2
  254435
  "p"]
The primitive way to create a byte-code object is with make-byte-code:

Function: make-byte-code &rest elements
This function constructs and returns a byte-code function object with elements as its elements.

You should not try to come up with the elements for a byte-code function yourself, because if they are inconsistent, Emacs may crash when you call the function. Always leave it to the byte compiler to create these objects; it makes the elements consistent (we hope).

You can access the elements of a byte-code object using aref; you can also use vconcat to create a vector with the same elements.

Disassembled Byte-Code

People do not write byte-code; that job is left to the byte compiler. But we provide a disassembler to satisfy a cat-like curiosity. The disassembler converts the byte-compiled code into humanly readable form.

The byte-code interpreter is implemented as a simple stack machine. It pushes values onto a stack of its own, then pops them off to use them in calculations whose results are themselves pushed back on the stack. When a byte-code function returns, it pops a value off the stack and returns it as the value of the function.

In addition to the stack, byte-code functions can use, bind, and set ordinary Lisp variables, by transferring values between variables and the stack.

Command: disassemble object &optional stream
This function prints the disassembled code for object. If stream is supplied, then output goes there. Otherwise, the disassembled code is printed to the stream standard-output. The argument object can be a function name or a lambda expression.

As a special exception, if this function is used interactively, it outputs to a buffer named `*Disassemble*'.

Here are two examples of using the disassemble function. We have added explanatory comments to help you relate the byte-code to the Lisp source; these do not appear in the output of disassemble. These examples show unoptimized byte-code. Nowadays byte-code is usually optimized, but we did not want to rewrite these examples, since they still serve their purpose.
(defun factorial (integer)
  "Compute factorial of an integer."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
     => factorial

(factorial 4)
     => 24

(disassemble 'factorial)
     -| byte-code for factorial:
 doc: Compute factorial of an integer.
 args: (integer)

0   constant 1              ; Push 1 onto stack.

1   varref   integer        ; Get value of integer
                            ;   from the environment
                            ;   and push the value
                            ;   onto the stack.

2   eqlsign                 ; Pop top two values off stack,
                            ;   compare them,
                            ;   and push result onto stack.

3   goto-if-nil 10          ; Pop and test top of stack;
                            ;   if nil, go to 10,
                            ;   else continue.

6   constant 1              ; Push 1 onto top of stack.

7   goto     17             ; Go to 17 (in this case, 1 will be
                            ;   returned by the function).

10  constant *              ; Push symbol * onto stack.

11  varref   integer        ; Push value of integer onto stack.

12  constant factorial      ; Push factorial onto stack.

13  varref   integer        ; Push value of integer onto stack.

14  sub1                    ; Pop integer, decrement value,
                            ;   push new value onto stack.

                            ; Stack now contains:
                            ;   - decremented value of integer
                            ;   - factorial
                            ;   - value of integer
                            ;   - *

15  call     1              ; Call function factorial using
                            ;   the first (i.e., the top) element
                            ;   of the stack as the argument;
                            ;   push returned value onto stack.

                            ; Stack now contains:
                            ;   - result of recursive
                            ;        call to factorial
                            ;   - value of integer
                            ;   - *

16  call     2              ; Using the first two
                            ;   (i.e., the top two)
                            ;   elements of the stack
                            ;   as arguments,
                            ;   call the function *,
                            ;   pushing the result onto the stack.

17  return                  ; Return the top element
                            ;   of the stack.
     => nil
The silly-loop function is somewhat more complex:
(defun silly-loop (n)
  "Return time before and after N iterations of a loop."
  (let ((t1 (current-time-string)))
    (while (> (setq n (1- n))
              0))
    (list t1 (current-time-string))))
     => silly-loop

(disassemble 'silly-loop)
     -| byte-code for silly-loop:
 doc: Return time before and after N iterations of a loop.
 args: (n)

0   constant current-time-string  ; Push
                                  ;   current-time-string
                                  ;   onto top of stack.

1   call     0              ; Call current-time-string
                            ;    with no argument,
                            ;    pushing result onto stack.

2   varbind  t1             ; Pop stack and bind t1
                            ;   to popped value.

3   varref   n              ; Get value of n from
                            ;   the environment and push
                            ;   the value onto the stack.

4   sub1                    ; Subtract 1 from top of stack.

5   dup                     ; Duplicate the top of the stack;
                            ;   i.e., copy the top of
                            ;   the stack and push the
                            ;   copy onto the stack.

6   varset   n              ; Pop the top of the stack,
                            ;   and bind n to the value.

                            ; In effect, the sequence dup varset
                            ;   copies the top of the stack
                            ;   into the value of n
                            ;   without popping it.

7   constant 0              ; Push 0 onto stack.

8   gtr                     ; Pop top two values off stack,
                            ;   test if n is greater than 0
                            ;   and push result onto stack.

9   goto-if-nil-else-pop 17 ; Goto 17 if n <= 0
                            ;   (this exits the while loop).
                            ;   else pop top of stack
                            ;   and continue

12  constant nil            ; Push nil onto stack
                            ;   (this is the body of the loop).

13  discard                 ; Discard result of the body
                            ;   of the loop (a while loop
                            ;   is always evaluated for
                            ;   its side effects).

14  goto     3              ; Jump back to beginning
                            ;   of while loop.

17  discard                 ; Discard result of while loop
                            ;   by popping top of stack.
                            ;   This result is the value nil that
                            ;   was not popped by the goto at 9.

18  varref   t1             ; Push value of t1 onto stack.

19  constant current-time-string  ; Push
                                  ;   current-time-string
                                  ;   onto top of stack.

20  call     0              ; Call current-time-string again.

21  list2                   ; Pop top two elements off stack,
                            ;   create a list of them,
                            ;   and push list onto stack.

22  unbind   1              ; Unbind t1 in local environment.

23  return                  ; Return value of the top of stack.

     => nil
Advising Emacs Lisp Functions

The advice feature lets you add to the existing definition of a function, by advising the function. This is a clean method for a library to customize functions defined by other parts of Emacs--cleaner than redefining the whole function.

Each function can have multiple pieces of advice, separately defined. Each defined piece of advice can be enabled or disabled explicitly. The enabled pieces of advice for any given function actually take effect when you activate advice for that function, or when that function is subsequently defined or redefined.

Usage Note: Advice is useful for altering the behavior of existing calls to an existing function. If you want the new behavior for new calls, or for key bindings, it is cleaner to define a new function (or a new command) which uses the existing function.

A Simple Advice Example

The command next-line moves point down vertically one or more lines; it is the standard binding of C-n. When used on the last line of the buffer, this command inserts a newline to create a line to move to (if next-line-add-newlines is non-nil).

Suppose you wanted to add a similar feature to previous-line, which would insert a new line at the beginning of the buffer for the command to move to. How could you do this?

You could do it by redefining the whole function, but that is not modular. The advice feature provides a cleaner alternative: you can effectively add your code to the existing function definition, without actually changing or even seeing that definition. Here is how to do this:
(defadvice previous-line (before next-line-at-end (arg))
  "Insert an empty line when moving up from the top line."
  (if (and next-line-add-newlines (= arg 1)
           (save-excursion (beginning-of-line) (bobp)))
      (progn
        (beginning-of-line)
        (newline))))
This expression defines a piece of advice for the function previous-line. This piece of advice is named next-line-at-end, and the symbol before says that it is before-advice which should run before the regular definition of previous-line. (arg) specifies how the advice code can refer to the function's arguments.

When this piece of advice runs, it creates an additional line, in the situation where that is appropriate, but does not move point to that line. This is the correct way to write the advice, because the normal definition will run afterward and will move back to the newly inserted line.

Defining the advice doesn't immediately change the function previous-line. That happens when you activate the advice, like this:
(ad-activate 'previous-line)
This is what actually begins to use the advice that has been defined so far for the function previous-line. Henceforth, whenever that function is run, whether invoked by the user with C-p or M-x, or called from Lisp, it runs the advice first, and its regular definition second.

This example illustrates before-advice, which is one class of advice: it runs before the function's base definition. There are two other advice classes: after-advice, which runs after the base definition, and around-advice, which lets you specify an expression to wrap around the invocation of the base definition.

Defining Advice

To define a piece of advice, use the macro defadvice. A call to defadvice has the following syntax, which is based on the syntax of defun and defmacro, but adds more:
(defadvice function (class name
                         [position] [arglist]
                         flags...)
  [documentation-string]
  [interactive-form]
  body-forms...)
Here, function is the name of the function (or macro or special form) to be advised. From now on, we will write just "function" when describing the entity being advised, but this always includes macros and special forms.

class specifies the class of the advice--one of before, after, or around. Before-advice runs before the function itself; after-advice runs after the function itself; around-advice is wrapped around the execution of the function itself. After-advice and around-advice can override the return value by setting ad-return-value.

Variable: ad-return-value
While advice is executing, after the function's original definition has been executed, this variable holds its return value, which will ultimately be returned to the caller after finishing all the advice. After-advice and around-advice can arrange to return some other value by storing it in this variable.

The argument name is the name of the advice, a non-nil symbol. The advice name uniquely identifies one piece of advice, within all the pieces of advice in a particular class for a particular function. The name allows you to refer to the piece of advice--to redefine it, or to enable or disable it.

In place of the argument list in an ordinary definition, an advice definition calls for several different pieces of information.

The optional position specifies where, in the current list of advice of the specified class, this new advice should be placed. It should be either first, last or a number that specifies a zero-based position (first is equivalent to 0). If no position is specified, the default is first. Position values outside the range of existing positions in this class are mapped to the beginning or the end of the range, whichever is closer. The position value is ignored when redefining an existing piece of advice.

The optional arglist can be used to define the argument list for the sake of advice. This becomes the argument list of the combined definition that is generated in order to run the advice (see section The Combined Definition). Therefore, the advice expressions can use the argument variables in this list to access argument values.

This argument list must be compatible with the argument list of the original function, so that it can handle the ways the function is actually called. If more than one piece of advice specifies an argument list, then the first one (the one with the smallest position) found in the list of all classes of advice is used.

The remaining elements, flags, are symbols that specify further information about how to use this piece of advice. Here are the valid symbols and their meanings:

activate
Activate the advice for function now. Changes in a function's advice always take effect the next time you activate advice for the function; this flag says to do so, for function, immediately after defining this piece of advice. This flag has no effect if function itself is not defined yet (a situation known as forward advice), because it is impossible to activate an undefined function's advice. However, defining function will automatically activate its advice.
protect
Protect this piece of advice against non-local exits and errors in preceding code and advice. Protecting advice places it as a cleanup in an unwind-protect form, so that it will execute even if the previous code gets an error or uses throw. See section Cleaning Up from Nonlocal Exits.
compile
Compile the combined definition that is used to run the advice. This flag is ignored unless activate is also specified. See section The Combined Definition.
disable
Initially disable this piece of advice, so that it will not be used unless subsequently explicitly enabled. See section Enabling and Disabling Advice.
preactivate
Activate advice for function when this defadvice is compiled or macroexpanded. This generates a compiled advised definition according to the current advice state, which will be used during activation if appropriate. This is useful only if this defadvice is byte-compiled.
The optional documentation-string serves to document this piece of advice. When advice is active for function, the documentation for function (as returned by documentation) combines the documentation strings of all the advice for function with the documentation string of its original function definition.

The optional interactive-form form can be supplied to change the interactive behavior of the original function. If more than one piece of advice has an interactive-form, then the first one (the one with the smallest position) found among all the advice takes precedence.

The possibly empty list of body-forms specifies the body of the advice. The body of an advice can access or change the arguments, the return value, the binding environment, and perform any other kind of side effect.

Warning: When you advise a macro, keep in mind that macros are expanded when a program is compiled, not when a compiled program is run. All subroutines used by the advice need to be available when the byte compiler expands the macro.

Around-Advice

Around-advice lets you "wrap" a Lisp expression "around" the original function definition. You specify where the original function definition should go by means of the special symbol ad-do-it. Where this symbol occurs inside the around-advice body, it is replaced with a progn containing the forms of the surrounded code. Here is an example:
(defadvice foo (around foo-around)
  "Ignore case in `foo'."
  (let ((case-fold-search t))
    ad-do-it))
Its effect is to make sure that case is ignored in searches when the original definition of foo is run.

Variable: ad-do-it
This is not really a variable, but it is somewhat used like one in around-advice. It specifies the place to run the function's original definition and other "earlier" around-advice.

If the around-advice does not use ad-do-it, then it does not run the original function definition. This provides a way to override the original definition completely. (It also overrides lower-positioned pieces of around-advice).

Computed Advice

The macro defadvice resembles defun in that the code for the advice, and all other information about it, are explicitly stated in the source code. You can also create advice whose details are computed, using the function ad-add-advice.

Function: ad-add-advice function advice class position
Calling ad-add-advice adds advice as a piece of advice to function in class class. The argument advice has this form:
(name protected enabled definition)
Here protected and enabled are flags, and definition is the expression that says what the advice should do. If enabled is nil, this piece of advice is initially disabled (see section Enabling and Disabling Advice).

If function already has one or more pieces of advice in the specified class, then position specifies where in the list to put the new piece of advice. The value of position can either be first, last, or a number (counting from 0 at the beginning of the list). Numbers outside the range are mapped to the closest extreme position.

If function already has a piece of advice with the same name, then the position argument is ignored and the old advice is replaced with the new one.

Activation of Advice

By default, advice does not take effect when you define it--only when you activate advice for the function that was advised. You can request the activation of advice for a function when you define the advice, by specifying the activate flag in the defadvice. But normally you activate the advice for a function by calling the function ad-activate or one of the other activation commands listed below.

Separating the activation of advice from the act of defining it permits you to add several pieces of advice to one function efficiently, without redefining the function over and over as each advice is added. More importantly, it permits defining advice for a function before that function is actually defined.

When a function's advice is first activated, the function's original definition is saved, and all enabled pieces of advice for that function are combined with the original definition to make a new definition. (Pieces of advice that are currently disabled are not used; see section Enabling and Disabling Advice.) This definition is installed, and optionally byte-compiled as well, depending on conditions described below.

In all of the commands to activate advice, if compile is t, the command also compiles the combined definition which implements the advice.

Command: ad-activate function &optional compile
This command activates the advice for function.

To activate advice for a function whose advice is already active is not a no-op. It is a useful operation which puts into effect any changes in that function's advice since the previous activation of advice for that function.

Command: ad-deactivate function
This command deactivates the advice for function.

Command: ad-activate-all &optional compile
This command activates the advice for all functions.

Command: ad-deactivate-all
This command deactivates the advice for all functions.

Command: ad-activate-regexp regexp &optional compile
This command activates all pieces of advice whose names match regexp. More precisely, it activates all advice for any function which has at least one piece of advice that matches regexp.

Command: ad-deactivate-regexp regexp
This command deactivates all pieces of advice whose names match regexp. More precisely, it deactivates all advice for any function which has at least one piece of advice that matches regexp.

Command: ad-update-regexp regexp &optional compile
This command activates pieces of advice whose names match regexp, but only those for functions whose advice is already activated.

Reactivating a function's advice is useful for putting into effect all the changes that have been made in its advice (including enabling and disabling specific pieces of advice; see section Enabling and Disabling Advice) since the last time it was activated.

Command: ad-start-advice
Turn on automatic advice activation when a function is defined or redefined. If you turn on this mode, then advice really does take effect immediately when defined.

Command: ad-stop-advice
Turn off automatic advice activation when a function is defined or redefined.

User Option: ad-default-compilation-action
This variable controls whether to compile the combined definition that results from activating advice for a function.

If the advised definition was constructed during "preactivation" (see section Preactivation), then that definition must already be compiled, because it was constructed during byte-compilation of the file that contained the defadvice with the preactivate flag.

Enabling and Disabling Advice

Each piece of advice has a flag that says whether it is enabled or not. By enabling or disabling a piece of advice, you can turn it on and off without having to undefine and redefine it. For example, here is how to disable a particular piece of advice named my-advice for the function foo:
(ad-disable-advice 'foo 'before 'my-advice)
This function by itself only changes the enable flag for a piece of advice. To make the change take effect in the advised definition, you must activate the advice for foo again:
(ad-activate 'foo)
Command: ad-disable-advice function class name
This command disables the piece of advice named name in class class on function.

Command: ad-enable-advice function class name
This command enables the piece of advice named name in class class on function.

You can also disable many pieces of advice at once, for various functions, using a regular expression. As always, the changes take real effect only when you next reactivate advice for the functions in question.

Command: ad-disable-regexp regexp
This command disables all pieces of advice whose names match regexp, in all classes, on all functions.

Command: ad-enable-regexp regexp
This command enables all pieces of advice whose names match regexp, in all classes, on all functions.

Preactivation

Constructing a combined definition to execute advice is moderately expensive. When a library advises many functions, this can make loading the library slow. In that case, you can use preactivation to construct suitable combined definitions in advance.

To use preactivation, specify the preactivate flag when you define the advice with defadvice. This defadvice call creates a combined definition which embodies this piece of advice (whether enabled or not) plus any other currently enabled advice for the same function, and the function's own definition. If the defadvice is compiled, that compiles the combined definition also.

When the function's advice is subsequently activated, if the enabled advice for the function matches what was used to make this combined definition, then the existing combined definition is used, thus avoiding the need to construct one. Thus, preactivation never causes wrong results--but it may fail to do any good, if the enabled advice at the time of activation doesn't match what was used for preactivation.

Here are some symptoms that can indicate that a preactivation did not work properly, because of a mismatch.

Activation of the advised function takes longer than usual.
The byte-compiler gets loaded while an advised function gets activated.
byte-compile is included in the value of features even though you did not ever explicitly use the byte-compiler.

Compiled preactivated advice works properly even if the function itself is not defined until later; however, the function needs to be defined when you compile the preactivated advice.

There is no elegant way to find out why preactivated advice is not being used. What you can do is to trace the function ad-cache-id-verification-code (with the function trace-function-background) before the advised function's advice is activated. After activation, check the value returned by ad-cache-id-verification-code for that function: verified means that the preactivated advice was used, while other values give some information about why they were considered inappropriate.

Warning: There is one known case that can make preactivation fail, in that a preconstructed combined definition is used even though it fails to match the current state of advice. This can happen when two packages define different pieces of advice with the same name, in the same class, for the same function. But you should avoid that anyway.

Argument Access in Advice

The simplest way to access the arguments of an advised function in the body of a piece of advice is to use the same names that the function definition uses. To do this, you need to know the names of the argument variables of the original function.

While this simple method is sufficient in many cases, it has a disadvantage: it is not robust, because it hard-codes the argument names into the advice. If the definition of the original function changes, the advice might break.

Another method is to specify an argument list in the advice itself. This avoids the need to know the original function definition's argument names, but it has a limitation: all the advice on any particular function must use the same argument list, because the argument list actually used for all the advice comes from the first piece of advice for that function.

A more robust method is to use macros that are translated into the proper access forms at activation time, i.e., when constructing the advised definition. Access macros access actual arguments by position regardless of how these actual arguments get distributed onto the argument variables of a function. This is robust because in Emacs Lisp the meaning of an argument is strictly determined by its position in the argument list.

Macro: ad-get-arg position
This returns the actual argument that was supplied at position.

Macro: ad-get-args position
This returns the list of actual arguments supplied starting at position.

Macro: ad-set-arg position value
This sets the value of the actual argument at position to value

Macro: ad-set-args position value-list
This sets the list of actual arguments starting at position to value-list.

Now an example. Suppose the function foo is defined as
(defun foo (x y &optional z &rest r) ...)
and is then called with
(foo 0 1 2 3 4 5 6)
which means that x is 0, y is 1, z is 2 and r is (3 4 5 6) within the body of foo. Here is what ad-get-arg and ad-get-args return in this case:
(ad-get-arg 0) => 0
(ad-get-arg 1) => 1
(ad-get-arg 2) => 2
(ad-get-arg 3) => 3
(ad-get-args 2) => (2 3 4 5 6)
(ad-get-args 4) => (4 5 6)
Setting arguments also makes sense in this example:
(ad-set-arg 5 "five")
has the effect of changing the sixth argument to "five". If this happens in advice executed before the body of foo is run, then r will be (3 4 "five" 6) within that body.

Here is an example of setting a tail of the argument list:
(ad-set-args 0 '(5 4 3 2 1 0))
If this happens in advice executed before the body of foo is run, then within that body, x will be 5, y will be 4, z will be 3, and r will be (2 1 0) inside the body of foo.

These argument constructs are not really implemented as Lisp macros. Instead they are implemented specially by the advice mechanism.

Definition of Subr Argument Lists

When the advice facility constructs the combined definition, it needs to know the argument list of the original function. This is not always possible for primitive functions. When advice cannot determine the argument list, it uses (&rest ad-subr-args), which always works but is inefficient because it constructs a list of the argument values. You can use ad-define-subr-args to declare the proper argument names for a primitive function:

Function: ad-define-subr-args function arglist
This function specifies that arglist should be used as the argument list for function function.

For example,
(ad-define-subr-args 'fset '(sym newdef))
specifies the argument list for the function fset.

The Combined Definition

Suppose that a function has n pieces of before-advice, m pieces of around-advice and k pieces of after-advice. Assuming no piece of advice is protected, the combined definition produced to implement the advice for a function looks like this:
(lambda arglist
  [ [advised-docstring] [(interactive ...)] ]
  (let (ad-return-value)
    before-0-body-form...
         ....
    before-n-1-body-form...
    around-0-body-form...
       around-1-body-form...
             ....
          around-m-1-body-form...
             (setq ad-return-value
                   apply original definition to arglist)
          other-around-m-1-body-form...
             ....
       other-around-1-body-form...
    other-around-0-body-form...
    after-0-body-form...
          ....
    after-k-1-body-form...
    ad-return-value))
Macros are redefined as macros, which means adding macro to the beginning of the combined definition.

The interactive form is present if the original function or some piece of advice specifies one. When an interactive primitive function is advised, a special method is used: to call the primitive with call-interactively so that it will read its own arguments. In this case, the advice cannot access the arguments.

The body forms of the various advice in each class are assembled according to their specified order. The forms of around-advice l are included in one of the forms of around-advice l - 1.

The innermost part of the around advice onion is
apply original definition to arglist
whose form depends on the type of the original function. The variable ad-return-value is set to whatever this returns. The variable is visible to all pieces of advice, which can access and modify it before it is actually returned from the advised function.

The semantic structure of advised functions that contain protected pieces of advice is the same. The only difference is that unwind-protect forms ensure that the protected advice gets executed even if some previous piece of advice had an error or a non-local exit. If any around-advice is protected, then the whole around-advice onion is protected as a result.

Debugging Lisp Programs

There are three ways to investigate a problem in an Emacs Lisp program, depending on what you are doing with the program when the problem appears.

If the problem occurs when you run the program, you can use a Lisp debugger to investigate what is happening during execution. In addition to the ordinary debugger, Emacs comes with a source level debugger, Edebug. This chapter describes both of them.
If the problem is syntactic, so that Lisp cannot even read the program, you can use the Emacs facilities for editing Lisp to localize it.
If the problem occurs when trying to compile the program with the byte compiler, you need to know how to examine the compiler's input buffer.

Another useful debugging tool is the dribble file. When a dribble file is open, Emacs copies all keyboard input characters to that file. Afterward, you can examine the file to find out what input was used. See section Terminal Input.

For debugging problems in terminal descriptions, the open-termscript function can be useful. See section Terminal Output.

The Lisp Debugger

The ordinary Lisp debugger provides the ability to suspend evaluation of a form. While evaluation is suspended (a state that is commonly known as a break), you may examine the run time stack, examine the values of local or global variables, or change those values. Since a break is a recursive edit, all the usual editing facilities of Emacs are available; you can even run programs that will enter the debugger recursively. See section Recursive Editing.

Entering the Debugger on an Error

The most important time to enter the debugger is when a Lisp error happens. This allows you to investigate the immediate causes of the error.

However, entry to the debugger is not a normal consequence of an error. Many commands frequently cause Lisp errors when invoked inappropriately (such as C-f at the end of the buffer), and during ordinary editing it would be very inconvenient to enter the debugger each time this happens. So if you want errors to enter the debugger, set the variable debug-on-error to non-nil. (The command toggle-debug-on-error provides an easy way to do this.)

User Option: debug-on-error
This variable determines whether the debugger is called when an error is signaled and not handled. If debug-on-error is t, all kinds of errors call the debugger (except those listed in debug-ignored-errors). If it is nil, none call the debugger.

The value can also be a list of error conditions that should call the debugger. For example, if you set it to the list (void-variable), then only errors about a variable that has no value invoke the debugger.

When this variable is non-nil, Emacs does not create an error handler around process filter functions and sentinels. Therefore, errors in these functions also invoke the debugger. See section Processes.

User Option: debug-ignored-errors
This variable specifies certain kinds of errors that should not enter the debugger. Its value is a list of error condition symbols and/or regular expressions. If the error has any of those condition symbols, or if the error message matches any of the regular expressions, then that error does not enter the debugger, regardless of the value of debug-on-error.

The normal value of this variable lists several errors that happen often during editing but rarely result from bugs in Lisp programs. However, "rarely" is not "never"; if your program fails with an error that matches this list, you will need to change this list in order to debug the error. The easiest way is usually to set debug-ignored-errors to nil.

User Option: debug-on-signal
Normally, errors that are caught by condition-case never run the debugger, even if debug-on-error is non-nil. In other words, condition-case gets a chance to handle the error before the debugger gets a chance.

If you set debug-on-signal to a non-nil value, then the debugger gets the first chance at every error; an error will invoke the debugger regardless of any condition-case, if it fits the criteria specified by the values of debug-on-error and debug-ignored-errors.

Warning: This variable is strong medicine! Various parts of Emacs handle errors in the normal course of affairs, and you may not even realize that errors happen there. If you set debug-on-signal to a non-nil value, those errors will enter the debugger.

Warning: debug-on-signal has no effect when debug-on-error is nil.

To debug an error that happens during loading of the `.emacs' file, use the option `--debug-init', which binds debug-on-error to t while loading `.emacs', and bypasses the condition-case which normally catches errors in the init file.

If your `.emacs' file sets debug-on-error, the effect may not last past the end of loading `.emacs'. (This is an undesirable byproduct of the code that implements the `--debug-init' command line option.) The best way to make `.emacs' set debug-on-error permanently is with after-init-hook, like this:
(add-hook 'after-init-hook
          '(lambda () (setq debug-on-error t)))
Debugging Infinite Loops

When a program loops infinitely and fails to return, your first problem is to stop the loop. On most operating systems, you can do this with C-g, which causes quit.

Ordinary quitting gives no information about why the program was looping. To get more information, you can set the variable debug-on-quit to non-nil. Quitting with C-g is not considered an error, and debug-on-error has no effect on the handling of C-g. Likewise, debug-on-quit has no effect on errors.

Once you have the debugger running in the middle of the infinite loop, you can proceed from the debugger using the stepping commands. If you step through the entire loop, you will probably get enough information to solve the problem.

User Option: debug-on-quit
This variable determines whether the debugger is called when quit is signaled and not handled. If debug-on-quit is non-nil, then the debugger is called whenever you quit (that is, type C-g). If debug-on-quit is nil, then the debugger is not called when you quit. See section Quitting.

Entering the Debugger on a Function Call

To investigate a problem that happens in the middle of a program, one useful technique is to enter the debugger whenever a certain function is called. You can do this to the function in which the problem occurs, and then step through the function, or you can do this to a function called shortly before the problem, step quickly over the call to that function, and then step through its caller.

Command: debug-on-entry function-name
This function requests function-name to invoke the debugger each time it is called. It works by inserting the form (debug 'debug) into the function definition as the first form.

Any function defined as Lisp code may be set to break on entry, regardless of whether it is interpreted code or compiled code. If the function is a command, it will enter the debugger when called from Lisp and when called interactively (after the reading of the arguments). You can't debug primitive functions (i.e., those written in C) this way.

When debug-on-entry is called interactively, it prompts for function-name in the minibuffer. If the function is already set up to invoke the debugger on entry, debug-on-entry does nothing. debug-on-entry always returns function-name.

Note: if you redefine a function after using debug-on-entry on it, the code to enter the debugger is discarded by the redefinition. In effect, redefining the function cancels the break-on-entry feature for that function.
(defun fact (n)
  (if (zerop n) 1
      (* n (fact (1- n)))))
     => fact
(debug-on-entry 'fact)
     => fact
(fact 3)

------ Buffer: *Backtrace* ------
Entering:
* fact(3)
  eval-region(4870 4878 t)
  byte-code("...")
  eval-last-sexp(nil)
  (let ...)
  eval-insert-last-sexp(nil)
* call-interactively(eval-insert-last-sexp)
------ Buffer: *Backtrace* ------

(symbol-function 'fact)
     => (lambda (n)
          (debug (quote debug))
          (if (zerop n) 1 (* n (fact (1- n)))))
Command: cancel-debug-on-entry function-name
This function undoes the effect of debug-on-entry on function-name. When called interactively, it prompts for function-name in the minibuffer. If function-name is nil or the empty string, it cancels break-on-entry for all functions.

Calling cancel-debug-on-entry does nothing to a function which is not currently set up to break on entry. It always returns function-name.

Explicit Entry to the Debugger

You can cause the debugger to be called at a certain point in your program by writing the expression (debug) at that point. To do this, visit the source file, insert the text `(debug)' at the proper place, and type C-M-x. Warning: if you do this for temporary debugging purposes, be sure to undo this insertion before you save the file!

The place where you insert `(debug)' must be a place where an additional form can be evaluated and its value ignored. (If the value of (debug) isn't ignored, it will alter the execution of the program!) The most common suitable places are inside a progn or an implicit progn (see section Sequencing).

Using the Debugger

When the debugger is entered, it displays the previously selected buffer in one window and a buffer named `*Backtrace*' in another window. The backtrace buffer contains one line for each level of Lisp function execution currently going on. At the beginning of this buffer is a message describing the reason that the debugger was invoked (such as the error message and associated data, if it was invoked due to an error).

The backtrace buffer is read-only and uses a special major mode, Debugger mode, in which letters are defined as debugger commands. The usual Emacs editing commands are available; thus, you can switch windows to examine the buffer that was being edited at the time of the error, switch buffers, visit files, or do any other sort of editing. However, the debugger is a recursive editing level (see section Recursive Editing) and it is wise to go back to the backtrace buffer and exit the debugger (with the q command) when you are finished with it. Exiting the debugger gets out of the recursive edit and kills the backtrace buffer.

The backtrace buffer shows you the functions that are executing and their argument values. It also allows you to specify a stack frame by moving point to the line describing that frame. (A stack frame is the place where the Lisp interpreter records information about a particular invocation of a function.) The frame whose line point is on is considered the current frame. Some of the debugger commands operate on the current frame.

The debugger itself must be run byte-compiled, since it makes assumptions about how many stack frames are used for the debugger itself. These assumptions are false if the debugger is running interpreted.

Debugger Commands

Inside the debugger (in Debugger mode), these special commands are available in addition to the usual cursor motion commands. (Keep in mind that all the usual facilities of Emacs, such as switching windows or buffers, are still available.)

The most important use of debugger commands is for stepping through code, so that you can see how control flows. The debugger can step through the control structures of an interpreted function, but cannot do so in a byte-compiled function. If you would like to step through a byte-compiled function, replace it with an interpreted definition of the same function. (To do this, visit the source for the function and type C-M-x on its definition.)

Here is a list of Debugger mode commands:

c
Exit the debugger and continue execution. When continuing is possible, it resumes execution of the program as if the debugger had never been entered (aside from any side-effects that you caused by changing variable values or data structures while inside the debugger). Continuing is possible after entry to the debugger due to function entry or exit, explicit invocation, or quitting. You cannot continue if the debugger was entered because of an error.
d
Continue execution, but enter the debugger the next time any Lisp function is called. This allows you to step through the subexpressions of an expression, seeing what values the subexpressions compute, and what else they do. The stack frame made for the function call which enters the debugger in this way will be flagged automatically so that the debugger will be called again when the frame is exited. You can use the u command to cancel this flag.
b
Flag the current frame so that the debugger will be entered when the frame is exited. Frames flagged in this way are marked with stars in the backtrace buffer.
u
Don't enter the debugger when the current frame is exited. This cancels a b command on that frame. The visible effect is to remove the star from the line in the backtrace buffer.
e
Read a Lisp expression in the minibuffer, evaluate it, and print the value in the echo area. The debugger alters certain important variables, and the current buffer, as part of its operation; e temporarily restores their values from outside the debugger, so you can examine and change them. This makes the debugger more transparent. By contrast, M-: does nothing special in the debugger; it shows you the variable values within the debugger.
R
Like e, but also save the result of evaluation in the buffer `*Debugger-record*'.
q
Terminate the program being debugged; return to top-level Emacs command execution. If the debugger was entered due to a C-g but you really want to quit, and not debug, use the q command.
r
Return a value from the debugger. The value is computed by reading an expression with the minibuffer and evaluating it. The r command is useful when the debugger was invoked due to exit from a Lisp call frame (as requested with b or by entering the frame with d); then the value specified in the r command is used as the value of that frame. It is also useful if you call debug and use its return value. Otherwise, r has the same effect as c, and the specified return value does not matter. You can't use r when the debugger was entered due to an error.
Invoking the Debugger

Here we describe in full detail the function debug that is used to invoke the debugger.

Function: debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer named `*Backtrace*' (or `*Backtrace*<2>' if it is the second recursive entry to the debugger, etc.), and fills it with information about the stack of Lisp function calls. It then enters a recursive edit, showing the backtrace buffer in Debugger mode.

The Debugger mode c and r commands exit the recursive edit; then debug switches back to the previous buffer and returns to whatever called debug. This is the only way the function debug can return to its caller.

The use of the debugger-args is that debug displays the rest of its arguments at the top of the `*Backtrace*' buffer, so that the user can see them. Except as described below, this is the only way these arguments are used.

However, certain values for first argument to debug have a special significance. (Normally, these values are used only by the internals of Emacs, and not by programmers calling debug.) Here is a table of these special values:

lambda
A first argument of lambda means debug was called because of entry to a function when debug-on-next-call was non-nil. The debugger displays `Entering:' as a line of text at the top of the buffer.
debug
debug as first argument indicates a call to debug because of entry to a function that was set to debug on entry. The debugger displays `Entering:', just as in the lambda case. It also marks the stack frame for that function so that it will invoke the debugger when exited.
t
When the first argument is t, this indicates a call to debug due to evaluation of a list form when debug-on-next-call is non-nil. The debugger displays the following as the top line in the buffer:
Beginning evaluation of function call form:
exit
When the first argument is exit, it indicates the exit of a stack frame previously marked to invoke the debugger on exit. The second argument given to debug in this case is the value being returned from the frame. The debugger displays `Return value:' in the top line of the buffer, followed by the value being returned.
error
When the first argument is error, the debugger indicates that it is being entered because an error or quit was signaled and not handled, by displaying `Signaling:' followed by the error signaled and any arguments to signal. For example,
(let ((debug-on-error t))
  (/ 1 0))

------ Buffer: *Backtrace* ------
Signaling: (arith-error)
  /(1 0)
...
------ Buffer: *Backtrace* ------
If an error was signaled, presumably the variable debug-on-error is non-nil. If quit was signaled, then presumably the variable debug-on-quit is non-nil.
nil
Use nil as the first of the debugger-args when you want to enter the debugger explicitly. The rest of the debugger-args are printed on the top line of the buffer. You can use this feature to display messages--for example, to remind yourself of the conditions under which debug is called.
Internals of the Debugger

This section describes functions and variables used internally by the debugger.

Variable: debugger
The value of this variable is the function to call to invoke the debugger. Its value must be a function of any number of arguments (or, more typically, the name of a function). Presumably this function will enter some kind of debugger. The default value of the variable is debug.

The first argument that Lisp hands to the function indicates why it was called. The convention for arguments is detailed in the description of debug.

Command: backtrace
This function prints a trace of Lisp function calls currently active. This is the function used by debug to fill up the `*Backtrace*' buffer. It is written in C, since it must have access to the stack to determine which function calls are active. The return value is always nil.

In the following example, a Lisp expression calls backtrace explicitly. This prints the backtrace to the stream standard-output: in this case, to the buffer `backtrace-output'. Each line of the backtrace represents one function call. The line shows the values of the function's arguments if they are all known. If they are still being computed, the line says so. The arguments of special forms are elided.
(with-output-to-temp-buffer "backtrace-output"
  (let ((var 1))
    (save-excursion
      (setq var (eval '(progn
                         (1+ var)
                         (list 'testing (backtrace))))))))

     => nil

----------- Buffer: backtrace-output ------------
  backtrace()
  (list ...computing arguments...)
  (progn ...)
  eval((progn (1+ var) (list (quote testing) (backtrace))))
  (setq ...)
  (save-excursion ...)
  (let ...)
  (with-output-to-temp-buffer ...)
  eval-region(1973 2142 #<buffer *scratch*>)
  byte-code("...  for eval-print-last-sexp ...")
  eval-print-last-sexp(nil)
* call-interactively(eval-print-last-sexp)
----------- Buffer: backtrace-output ------------
The character `*' indicates a frame whose debug-on-exit flag is set.

Variable: debug-on-next-call
If this variable is non-nil, it says to call the debugger before the next eval, apply or funcall. Entering the debugger sets debug-on-next-call to nil.

The d command in the debugger works by setting this variable.

Function: backtrace-debug level flag
This function sets the debug-on-exit flag of the stack frame level levels down the stack, giving it the value flag. If flag is non-nil, this will cause the debugger to be entered when that frame later exits. Even a nonlocal exit through that frame will enter the debugger.

This function is used only by the debugger.

Variable: command-debug-status
This variable records the debugging status of the current interactive command. Each time a command is called interactively, this variable is bound to nil. The debugger can set this variable to leave information for future debugger invocations during the same command invocation.

The advantage, for the debugger, of using this variable rather than an ordinary global variable is that the data will never carry over to a subsequent command invocation.

Function: backtrace-frame frame-number
The function backtrace-frame is intended for use in Lisp debuggers. It returns information about what computation is happening in the stack frame frame-number levels down.

If that frame has not evaluated the arguments yet (or is a special form), the value is (nil function arg-forms...).

If that frame has evaluated its arguments and called its function already, the value is (t function arg-values...).

In the return value, function is whatever was supplied as the CAR of the evaluated list, or a lambda expression in the case of a macro call. If the function has a &rest argument, that is represented as the tail of the list arg-values.

If frame-number is out of range, backtrace-frame returns nil.

Edebug

Edebug is a source-level debugger for Emacs Lisp programs with which you can:

Step through evaluation, stopping before and after each expression.
Set conditional or unconditional breakpoints.
Stop when a specified condition is true (the global break event).
Trace slow or fast, stopping briefly at each stop point, or at each breakpoint.
Display expression results and evaluate expressions as if outside of Edebug.
Automatically re-evaluate a list of expressions and display their results each time Edebug updates the display.
Output trace info on function enter and exit.
Stop when an error occurs.
Display a backtrace, omitting Edebug's own frames.
Specify argument evaluation for macros and defining forms.
Obtain rudimentary coverage testing and frequency counts.

The first three sections below should tell you enough about Edebug to enable you to use it.

Using Edebug

To debug a Lisp program with Edebug, you must first instrument the Lisp code that you want to debug. A simple way to do this is to first move point into the definition of a function or macro and then do C-u C-M-x (eval-defun with a prefix argument). See section Instrumenting for Edebug, for alternative ways to instrument code.

Once a function is instrumented, any call to the function activates Edebug. Activating Edebug may stop execution and let you step through the function, or it may update the display and continue execution while checking for debugging commands, depending on which Edebug execution mode you have selected. The default execution mode is step, which does stop execution. See section Edebug Execution Modes.

Within Edebug, you normally view an Emacs buffer showing the source of the Lisp code you are debugging. This is referred to as the source code buffer. This buffer is temporarily read-only.

An arrow at the left margin indicates the line where the function is executing. Point initially shows where within the line the function is executing, but this ceases to be true if you move point yourself.

If you instrument the definition of fac (shown below) and then execute (fac 3), here is what you normally see. Point is at the open-parenthesis before if.
(defun fac (n)
=>-!-(if (< 0 n)
      (* n (fac (1- n)))
    1))
The places within a function where Edebug can stop execution are called stop points. These occur both before and after each subexpression that is a list, and also after each variable reference. Here we show with periods the stop points found in the function fac:
(defun fac (n)
  .(if .(< 0 n.).
      .(* n. .(fac (1- n.).).).
    1).)
The special commands of Edebug are available in the source code buffer in addition to the commands of Emacs Lisp mode. For example, you can type the Edebug command SPC to execute until the next stop point. If you type SPC once after entry to fac, here is the display you will see:
(defun fac (n)
=>(if -!-(< 0 n)
      (* n (fac (1- n)))
    1))
When Edebug stops execution after an expression, it displays the expression's value in the echo area.

Other frequently used commands are b to set a breakpoint at a stop point, g to execute until a breakpoint is reached, and q to exit Edebug and return to the top-level command loop. Type ? to display a list of all Edebug commands.

Instrumenting for Edebug

In order to use Edebug to debug Lisp code, you must first instrument the code. Instrumenting code inserts additional code into it, to invoke Edebug at the proper places.

Once you have loaded Edebug, the command C-M-x (eval-defun) is redefined so that when invoked with a prefix argument on a definition, it instruments the definition before evaluating it. (The source code itself is not modified.) If the variable edebug-all-defs is non-nil, that inverts the meaning of the prefix argument: then C-M-x instruments the definition unless it has a prefix argument. The default value of edebug-all-defs is nil. The command M-x edebug-all-defs toggles the value of the variable edebug-all-defs.

If edebug-all-defs is non-nil, then the commands eval-region, eval-current-buffer, and eval-buffer also instrument any definitions they evaluate. Similarly, edebug-all-forms controls whether eval-region should instrument any form, even non-defining forms. This doesn't apply to loading or evaluations in the minibuffer. The command M-x edebug-all-forms toggles this option.

Another command, M-x edebug-eval-top-level-form, is available to instrument any top-level form regardless of the values of edebug-all-defs and edebug-all-forms.

While Edebug is active, the command I (edebug-instrument-callee) instruments the definition of the function or macro called by the list form after point, if is not already instrumented. This is possible only if Edebug knows where to find the source for that function; after loading Edebug, eval-region records the position of every definition it evaluates, even if not instrumenting it. See also the i command (see section Jumping), which steps into the call after instrumenting the function.

Edebug knows how to instrument all the standard special forms, interactive forms with an expression argument, anonymous lambda expressions, and other defining forms. Edebug cannot know what a user-defined macro will do with the arguments of a macro call, so you must tell it; see section Instrumenting Macro Calls, for details.

When Edebug is about to instrument code for the first time in a session, it runs the hook edebug-setup-hook, then sets it to nil. You can use this to arrange to load Edebug specifications (see section Instrumenting Macro Calls) associated with a package you are using, but actually load them only if you use Edebug.

To remove instrumentation from a definition, simply re-evaluate its definition in a way that does not instrument. There are two ways of evaluating forms that never instrument them: from a file with load, and from the minibuffer with eval-expression (M-:).

If Edebug detects a syntax error while instrumenting, it leaves point at the erroneous code and signals an invalid-read-syntax error.

See section Evaluation, for other evaluation functions available inside of Edebug.

Edebug Execution Modes

Edebug supports several execution modes for running the program you are debugging. We call these alternatives Edebug execution modes; do not confuse them with major or minor modes. The current Edebug execution mode determines how far Edebug continues execution before stopping--whether it stops at each stop point, or continues to the next breakpoint, for example--and how much Edebug displays the progress of the evaluation before it stops.

Normally, you specify the Edebug execution mode by typing a command to continue the program in a certain mode. Here is a table of these commands. All except for S resume execution of the program, at least for a certain distance.

S
Stop: don't execute any more of the program for now, just wait for more Edebug commands (edebug-stop).
SPC
Step: stop at the next stop point encountered (edebug-step-mode).
n
Next: stop at the next stop point encountered after an expression (edebug-next-mode). Also see edebug-forward-sexp in section Miscellaneous Edebug Commands.
t
Trace: pause one second at each Edebug stop point (edebug-trace-mode).
T
Rapid trace: update the display at each stop point, but don't actually pause (edebug-Trace-fast-mode).
g
Go: run until the next breakpoint (edebug-go-mode). See section Breakpoints.
c
Continue: pause one second at each breakpoint, and then continue (edebug-continue-mode).
C
Rapid continue: move point to each breakpoint, but don't pause (edebug-Continue-fast-mode).
G
Go non-stop: ignore breakpoints (edebug-Go-nonstop-mode). You can still stop the program by typing S, or any editing command.
In general, the execution modes earlier in the above list run the program more slowly or stop sooner than the modes later in the list.

While executing or tracing, you can interrupt the execution by typing any Edebug command. Edebug stops the program at the next stop point and then executes the command you typed. For example, typing t during execution switches to trace mode at the next stop point. You can use S to stop execution without doing anything else.

If your function happens to read input, a character you type intending to interrupt execution may be read by the function instead. You can avoid such unintended results by paying attention to when your program wants input.

Keyboard macros containing the commands in this section do not completely work: exiting from Edebug, to resume the program, loses track of the keyboard macro. This is not easy to fix. Also, defining or executing a keyboard macro outside of Edebug does not affect commands inside Edebug. This is usually an advantage. But see the edebug-continue-kbd-macro option (see section Edebug Options).

When you enter a new Edebug level, the initial execution mode comes from the value of the variable edebug-initial-mode. By default, this specifies step mode. Note that you may reenter the same Edebug level several times if, for example, an instrumented function is called several times from one command.

Jumping

The commands described in this section execute until they reach a specified location. All except i make a temporary breakpoint to establish the place to stop, then switch to go mode. Any other breakpoint reached before the intended stop point will also stop execution. See section Breakpoints, for the details on breakpoints.

These commands may fail to work as expected in case of nonlocal exit, because a nonlocal exit can bypass the temporary breakpoint where you expected the program to stop.

h
Proceed to the stop point near where point is (edebug-goto-here).
f
Run the program forward over one expression (edebug-forward-sexp).
o
Run the program until the end of the containing sexp.
i
Step into the function or macro called by the form after point.
The h command proceeds to the stop point near the current location of point, using a temporary breakpoint. See section Breakpoints, for more information about breakpoints.

The f command runs the program forward over one expression. More precisely, it sets a temporary breakpoint at the position that C-M-f would reach, then executes in go mode so that the program will stop at breakpoints.

With a prefix argument n, the temporary breakpoint is placed n sexps beyond point. If the containing list ends before n more elements, then the place to stop is after the containing expression.

Be careful that the position C-M-f finds is a place that the program will really get to; this may not be true in a cond, for example.

The f command does forward-sexp starting at point, rather than at the stop point, for flexibility. If you want to execute one expression from the current stop point, type w first, to move point there, and then type f.

The o command continues "out of" an expression. It places a temporary breakpoint at the end of the sexp containing point. If the containing sexp is a function definition itself, o continues until just before the last sexp in the definition. If that is where you are now, it returns from the function and then stops. In other words, this command does not exit the currently executing function unless you are positioned after the last sexp.

The i command steps into the function or macro called by the list form after point, and stops at its first stop point. Note that the form need not be the one about to be evaluated. But if the form is a function call about to be evaluated, remember to use this command before any of the arguments are evaluated, since otherwise it will be too late.

The i command instruments the function or macro it's supposed to step into, if it isn't instrumented already. This is convenient, but keep in mind that the function or macro remains instrumented unless you explicitly arrange to deinstrument it.

Miscellaneous Edebug Commands

Some miscellaneous Edebug commands are described here.

?
Display the help message for Edebug (edebug-help).
C-]
Abort one level back to the previous command level (abort-recursive-edit).
q
Return to the top level editor command loop (top-level). This exits all recursive editing levels, including all levels of Edebug activity. However, instrumented code protected with unwind-protect or condition-case forms may resume debugging.
Q
Like q but don't stop even for protected code (top-level-nonstop).
r
Redisplay the most recently known expression result in the echo area (edebug-previous-result).
d
Display a backtrace, excluding Edebug's own functions for clarity (edebug-backtrace). You cannot use debugger commands in the backtrace buffer in Edebug as you would in the standard debugger. The backtrace buffer is killed automatically when you continue execution.
From the Edebug recursive edit, you may invoke commands that activate Edebug again recursively. Any time Edebug is active, you can quit to the top level with q or abort one recursive edit level with C-]. You can display a backtrace of all the pending evaluations with d.

Breakpoints

Edebug's step mode stops execution at the next stop point reached. There are three other ways to stop Edebug execution once it has started: breakpoints, the global break condition, and source breakpoints.

While using Edebug, you can specify breakpoints in the program you are testing: points where execution should stop. You can set a breakpoint at any stop point, as defined in section Using Edebug. For setting and unsetting breakpoints, the stop point that is affected is the first one at or after point in the source code buffer. Here are the Edebug commands for breakpoints:

b
Set a breakpoint at the stop point at or after point (edebug-set-breakpoint). If you use a prefix argument, the breakpoint is temporary (it turns off the first time it stops the program).
u
Unset the breakpoint (if any) at the stop point at or after point (edebug-unset-breakpoint).
x condition RET
Set a conditional breakpoint which stops the program only if condition evaluates to a non-nil value (edebug-set-conditional-breakpoint). With a prefix argument, the breakpoint is temporary.
B
Move point to the next breakpoint in the current definition (edebug-next-breakpoint).
While in Edebug, you can set a breakpoint with b and unset one with u. First move point to the Edebug stop point of your choice, then type b or u to set or unset a breakpoint there. Unsetting a breakpoint where none has been set has no effect.

Re-evaluating or reinstrumenting a definition forgets all its breakpoints.

A conditional breakpoint tests a condition each time the program gets there. Any errors that occur as a result of evaluating the condition are ignored, as if the result were nil. To set a conditional breakpoint, use x, and specify the condition expression in the minibuffer. Setting a conditional breakpoint at a stop point that has a previously established conditional breakpoint puts the previous condition expression in the minibuffer so you can edit it.

You can make a conditional or unconditional breakpoint temporary by using a prefix argument with the command to set the breakpoint. When a temporary breakpoint stops the program, it is automatically unset.

Edebug always stops or pauses at a breakpoint except when the Edebug mode is Go-nonstop. In that mode, it ignores breakpoints entirely.

To find out where your breakpoints are, use the B command, which moves point to the next breakpoint following point, within the same function, or to the first breakpoint if there are no following breakpoints. This command does not continue execution--it just moves point in the buffer.

Global Break Condition

A global break condition stops execution when a specified condition is satisfied, no matter where that may occur. Edebug evaluates the global break condition at every stop point. If it evaluates to a non-nil value, then execution stops or pauses depending on the execution mode, as if a breakpoint had been hit. If evaluating the condition gets an error, execution does not stop.

The condition expression is stored in edebug-global-break-condition. You can specify a new expression using the X command (edebug-set-global-break-condition).

The global break condition is the simplest way to find where in your code some event occurs, but it makes code run much more slowly. So you should reset the condition to nil when not using it.

Source Breakpoints

All breakpoints in a definition are forgotten each time you reinstrument it. To make a breakpoint that won't be forgotten, you can write a source breakpoint, which is simply a call to the function edebug in your source code. You can, of course, make such a call conditional. For example, in the fac function, insert the first line as shown below to stop when the argument reaches zero:
(defun fac (n)
  (if (= n 0) (edebug))
  (if (< 0 n)
      (* n (fac (1- n)))
    1))
When the fac definition is instrumented and the function is called, the call to edebug acts as a breakpoint. Depending on the execution mode, Edebug stops or pauses there.

If no instrumented code is being executed when edebug is called, that function calls debug.

Trapping Errors

Emacs normally displays an error message when an error is signaled and not handled with condition-case. While Edebug is active and executing instrumented code, it normally responds to all unhandled errors. You can customize this with the options edebug-on-error and edebug-on-quit; see section Edebug Options.

When Edebug responds to an error, it shows the last stop point encountered before the error. This may be the location of a call to a function which was not instrumented, within which the error actually occurred. For an unbound variable error, the last known stop point might be quite distant from the offending variable reference. In that case you might want to display a full backtrace (see section Miscellaneous Edebug Commands).

If you change debug-on-error or debug-on-quit while Edebug is active, these changes will be forgotten when Edebug becomes inactive. Furthermore, during Edebug's recursive edit, these variables are bound to the values they had outside of Edebug.

Edebug Views

These Edebug commands let you view aspects of the buffer and window status as they were before entry to Edebug. The outside window configuration is the collection of windows and contents that were in effect outside of Edebug.

v
Temporarily view the outside window configuration (edebug-view-outside).
p
Temporarily display the outside current buffer with point at its outside position (edebug-bounce-point). With a prefix argument n, pause for n seconds instead.
w
Move point back to the current stop point in the source code buffer (edebug-where). If you use this command in a different window displaying the same buffer, that window will be used instead to display the current definition in the future.
W
Toggle whether Edebug saves and restores the outside window configuration (edebug-toggle-save-windows). With a prefix argument, W only toggles saving and restoring of the selected window. To specify a window that is not displaying the source code buffer, you must use C-x X W from the global keymap.
You can view the outside window configuration with v or just bounce to the point in the current buffer with p, even if it is not normally displayed. After moving point, you may wish to jump back to the stop point with w from a source code buffer.

Each time you use W to turn saving off, Edebug forgets the saved outside window configuration--so that even if you turn saving back on, the current window configuration remains unchanged when you next exit Edebug (by continuing the program). However, the automatic redisplay of `*edebug*' and `*edebug-trace*' may conflict with the buffers you wish to see unless you have enough windows open.

Evaluation

While within Edebug, you can evaluate expressions "as if" Edebug were not running. Edebug tries to be invisible to the expression's evaluation and printing. Evaluation of expressions that cause side effects will work as expected except for things that Edebug explicitly saves and restores. See section The Outside Context, for details on this process.

e exp RET
Evaluate expression exp in the context outside of Edebug (edebug-eval-expression). That is, Edebug tries to minimize its interference with the evaluation.
M-: exp RET
Evaluate expression exp in the context of Edebug itself.
C-x C-e
Evaluate the expression before point, in the context outside of Edebug (edebug-eval-last-sexp).
Edebug supports evaluation of expressions containing references to lexically bound symbols created by the following constructs in `cl.el' (version 2.03 or later): lexical-let, macrolet, and symbol-macrolet.

Evaluation List Buffer

You can use the evaluation list buffer, called `*edebug*', to evaluate expressions interactively. You can also set up the evaluation list of expressions to be evaluated automatically each time Edebug updates the display.

E
Switch to the evaluation list buffer `*edebug*' (edebug-visit-eval-list).
In the `*edebug*' buffer you can use the commands of Lisp Interaction mode (see section `Lisp Interaction' in The GNU Emacs Manual) as well as these special commands:

C-j
Evaluate the expression before point, in the outside context, and insert the value in the buffer (edebug-eval-print-last-sexp).
C-x C-e
Evaluate the expression before point, in the context outside of Edebug (edebug-eval-last-sexp).
C-c C-u
Build a new evaluation list from the contents of the buffer (edebug-update-eval-list).
C-c C-d
Delete the evaluation list group that point is in (edebug-delete-eval-item).
C-c C-w
Switch back to the source code buffer at the current stop point (edebug-where).
You can evaluate expressions in the evaluation list window with C-j or C-x C-e, just as you would in `*scratch*'; but they are evaluated in the context outside of Edebug.

The expressions you enter interactively (and their results) are lost when you continue execution; but you can set up an evaluation list consisting of expressions to be evaluated each time execution stops.

To do this, write one or more evaluation list groups in the evaluation list buffer. An evaluation list group consists of one or more Lisp expressions. Groups are separated by comment lines.

The command C-c C-u (edebug-update-eval-list) rebuilds the evaluation list, scanning the buffer and using the first expression of each group. (The idea is that the second expression of the group is the value previously computed and displayed.)

Each entry to Edebug redisplays the evaluation list by inserting each expression in the buffer, followed by its current value. It also inserts comment lines so that each expression becomes its own group. Thus, if you type C-c C-u again without changing the buffer text, the evaluation list is effectively unchanged.

If an error occurs during an evaluation from the evaluation list, the error message is displayed in a string as if it were the result. Therefore, expressions that use variables not currently valid do not interrupt your debugging.

Here is an example of what the evaluation list window looks like after several expressions have been added to it:
(current-buffer)
#<buffer *scratch*>
;---------------------------------------------------------------
(selected-window)
#<window 16 on *scratch*>
;---------------------------------------------------------------
(point)
196
;---------------------------------------------------------------
bad-var
"Symbol's value as variable is void: bad-var"
;---------------------------------------------------------------
(recursion-depth)
0
;---------------------------------------------------------------
this-command
eval-last-sexp
;---------------------------------------------------------------
To delete a group, move point into it and type C-c C-d, or simply delete the text for the group and update the evaluation list with C-c C-u. To add a new expression to the evaluation list, insert the expression at a suitable place, and insert a new comment line. (You need not insert dashes in the comment line--its contents don't matter.) Then type C-c C-u.

After selecting `*edebug*', you can return to the source code buffer with C-c C-w. The `*edebug*' buffer is killed when you continue execution, and recreated next time it is needed.

Printing in Edebug

If an expression in your program produces a value containing circular list structure, you may get an error when Edebug attempts to print it.

One way to cope with circular structure is to set print-length or print-level to truncate the printing. Edebug does this for you; it binds print-length and print-level to 50 if they were nil. (Actually, the variables edebug-print-length and edebug-print-level specify the values to use within Edebug.) See section Variables Affecting Output.

User Option: edebug-print-length
If non-nil, bind print-length to this while printing results in Edebug. The default value is 50.

User Option: edebug-print-level
If non-nil, bind print-level to this while printing results in Edebug. The default value is 50.

You can also print circular structures and structures that share elements more informatively by using the `cust-print' package.

To load `cust-print' and activate custom printing only for Edebug, simply use the command M-x edebug-install-custom-print. To restore the standard print functions, use M-x edebug-uninstall-custom-print.

Here is an example of code that creates a circular structure:
(setq a '(x y))
(setcar a a)
Custom printing prints this as `Result: #1=(#1# y)'. The `#1=' notation labels the structure that follows it with the label `1', and the `#1#' notation references the previously labeled structure. This notation is used for any shared elements of lists or vectors.

User Option: edebug-print-circle
If non-nil, bind print-circle to this while printing results in Edebug. The default value is nil.

Other programs can also use custom printing; see `cust-print.el' for details.

Trace Buffer

Edebug can record an execution trace, storing it in a buffer named `*edebug-trace*'. This is a log of function calls and returns, showing the function names and their arguments and values. To enable trace recording, set edebug-trace to a non-nil value.

Making a trace buffer is not the same thing as using trace execution mode (see section Edebug Execution Modes).

When trace recording is enabled, each function entry and exit adds lines to the trace buffer. A function entry record looks like `::::{' followed by the function name and argument values. A function exit record looks like `::::}' followed by the function name and result of the function.

The number of `:'s in an entry shows its recursion depth. You can use the braces in the trace buffer to find the matching beginning or end of function calls.

You can customize trace recording for function entry and exit by redefining the functions edebug-print-trace-before and edebug-print-trace-after.

Macro: edebug-tracing string body...
This macro requests additional trace information around the execution of the body forms. The argument string specifies text to put in the trace buffer. All the arguments are evaluated. edebug-tracing returns the value of the last form in body.

Function: edebug-trace format-string &rest format-args
This function inserts text in the trace buffer. It computes the text with (apply 'format format-string format-args). It also appends a newline to separate entries.

edebug-tracing and edebug-trace insert lines in the trace buffer whenever they are called, even if Edebug is not active. Adding text to the trace buffer also scrolls its window to show the last lines inserted.

Coverage Testing

Edebug provides rudimentary coverage testing and display of execution frequency.

Coverage testing works by comparing the result of each expression with the previous result; each form in the program is considered "covered" if it has returned two different values since you began testing coverage in the current Emacs session. Thus, to do coverage testing on your program, execute it under various conditions and note whether it behaves correctly; Edebug will tell you when you have tried enough different conditions that each form has returned two different values.

Coverage testing makes execution slower, so it is only done if edebug-test-coverage is non-nil. Frequency counting is performed for all execution of an instrumented function, even if the execution mode is Go-nonstop, and regardless of whether coverage testing is enabled.

Use M-x edebug-display-freq-count to display both the coverage information and the frequency counts for a definition.

Command: edebug-display-freq-count
This command displays the frequency count data for each line of the current definition.

The frequency counts appear as comment lines after each line of code, and you can undo all insertions with one undo command. The counts appear under the `(' before an expression or the `)' after an expression, or on the last character of a variable. To simplify the display, a count is not shown if it is equal to the count of an earlier expression on the same line.

The character `=' following the count for an expression says that the expression has returned the same value each time it was evaluated. In other words, it is not yet "covered" for coverage testing purposes.

To clear the frequency count and coverage data for a definition, simply reinstrument it with eval-defun.

For example, after evaluating (fac 5) with a source breakpoint, and setting edebug-test-coverage to t, when the breakpoint is reached, the frequency data looks like this:
(defun fac (n)
  (if (= n 0) (edebug))
;#6           1      0 =5
  (if (< 0 n)
;#5         =
      (* n (fac (1- n)))
;#    5               0
    1))
;#   0
The comment lines show that fac was called 6 times. The first if statement returned 5 times with the same result each time; the same is true of the condition on the second if. The recursive call of fac did not return at all.

The Outside Context

Edebug tries to be transparent to the program you are debugging, but it does not succeed completely. Edebug also tries to be transparent when you evaluate expressions with e or with the evaluation list buffer, by temporarily restoring the outside context. This section explains precisely what context Edebug restores, and how Edebug fails to be completely transparent.

Checking Whether to Stop

Whenever Edebug is entered, it needs to save and restore certain data before even deciding whether to make trace information or stop the program.

max-lisp-eval-depth and max-specpdl-size are both incremented once to reduce Edebug's impact on the stack. You could, however, still run out of stack space when using Edebug.
The state of keyboard macro execution is saved and restored. While Edebug is active, executing-macro is bound to edebug-continue-kbd-macro.

Edebug Display Update

When Edebug needs to display something (e.g., in trace mode), it saves the current window configuration from "outside" Edebug (see section Window Configurations). When you exit Edebug (by continuing the program), it restores the previous window configuration.

Emacs redisplays only when it pauses. Usually, when you continue execution, the program comes back into Edebug at a breakpoint or after stepping without pausing or reading input in between. In such cases, Emacs never gets a chance to redisplay the "outside" configuration. What you see is the same window configuration as the last time Edebug was active, with no interruption.

Entry to Edebug for displaying something also saves and restores the following data, but some of these are deliberately not restored if an error or quit signal occurs.

Which buffer is current, and the positions of point and the mark in the current buffer, are saved and restored.
The outside window configuration is saved and restored if edebug-save-windows is non-nil (see section Edebug Display Update). The window configuration is not restored on error or quit, but the outside selected window is reselected even on error or quit in case a save-excursion is active. If the value of edebug-save-windows is a list, only the listed windows are saved and restored. The window start and horizontal scrolling of the source code buffer are not restored, however, so that the display remains coherent within Edebug.
The value of point in each displayed buffer is saved and restored if edebug-save-displayed-buffer-points is non-nil.
The variables overlay-arrow-position and overlay-arrow-string are saved and restored. So you can safely invoke Edebug from the recursive edit elsewhere in the same buffer.
cursor-in-echo-area is locally bound to nil so that the cursor shows up in the window.

Edebug Recursive Edit

When Edebug is entered and actually reads commands from the user, it saves (and later restores) these additional data:

The current match data. See section The Match Data.
last-command, this-command, last-command-char, last-input-char, last-input-event, last-command-event, last-event-frame, last-nonmenu-event, and track-mouse. Commands used within Edebug do not affect these variables outside of Edebug. The key sequence returned by this-command-keys is changed by executing commands within Edebug and there is no way to reset the key sequence from Lisp. Edebug cannot save and restore the value of unread-command-events. Entering Edebug while this variable has a nontrivial value can interfere with execution of the program you are debugging.
Complex commands executed while in Edebug are added to the variable command-history. In rare cases this can alter execution.
Within Edebug, the recursion depth appears one deeper than the recursion depth outside Edebug. This is not true of the automatically updated evaluation list window.
standard-output and standard-input are bound to nil by the recursive-edit, but Edebug temporarily restores them during evaluations.
The state of keyboard macro definition is saved and restored. While Edebug is active, defining-kbd-macro is bound to edebug-continue-kbd-macro.

Instrumenting Macro Calls

When Edebug instruments an expression that calls a Lisp macro, it needs additional information about the macro to do the job properly. This is because there is no a-priori way to tell which subexpressions of the macro call are forms to be evaluated. (Evaluation may occur explicitly in the macro body, or when the resulting expansion is evaluated, or any time later.)

Therefore, you must define an Edebug specification for each macro that Edebug will encounter, to explain the format of calls to that macro. To do this, use def-edebug-spec.

Macro: def-edebug-spec macro specification
Specify which expressions of a call to macro macro are forms to be evaluated. For simple macros, the specification often looks very similar to the formal argument list of the macro definition, but specifications are much more general than macro arguments.

The macro argument can actually be any symbol, not just a macro name.

Here is a simple example that defines the specification for the for example macro (see section Evaluating Macro Arguments Repeatedly), followed by an alternative, equivalent specification.
(def-edebug-spec for
  (symbolp "from" form "to" form "do" &rest form))

(def-edebug-spec for
  (symbolp ['from form] ['to form] ['do body]))
Here is a table of the possibilities for specification and how each directs processing of arguments.

t
All arguments are instrumented for evaluation.
0
None of the arguments is instrumented.
a symbol
The symbol must have an Edebug specification which is used instead. This indirection is repeated until another kind of specification is found. This allows you to inherit the specification from another macro.
a list
The elements of the list describe the types of the arguments of a calling form. The possible elements of a specification list are described in the following sections.
Specification List

A specification list is required for an Edebug specification if some arguments of a macro call are evaluated while others are not. Some elements in a specification list match one or more arguments, but others modify the processing of all following elements. The latter, called specification keywords, are symbols beginning with `&' (such as &optional).

A specification list may contain sublists which match arguments that are themselves lists, or it may contain vectors used for grouping. Sublists and groups thus subdivide the specification list into a hierarchy of levels. Specification keywords apply only to the remainder of the sublist or group they are contained in.

When a specification list involves alternatives or repetition, matching it against an actual macro call may require backtracking. See section Backtracking in Specifications, for more details.

Edebug specifications provide the power of regular expression matching, plus some context-free grammar constructs: the matching of sublists with balanced parentheses, recursive processing of forms, and recursion via indirect specifications.

Here's a table of the possible elements of a specification list, with their meanings:

sexp
A single unevaluated Lisp object, which is not instrumented.
form
A single evaluated expression, which is instrumented.
place
A place to store a value, as in the Common Lisp setf construct.
body
Short for &rest form. See &rest below.
function-form
A function form: either a quoted function symbol, a quoted lambda expression, or a form (that should evaluate to a function symbol or lambda expression). This is useful when an argument that's a lambda expression might be quoted with quote rather than function, since it instruments the body of the lambda expression either way.
lambda-expr
A lambda expression with no quoting.
&optional
All following elements in the specification list are optional; as soon as one does not match, Edebug stops matching at this level. To make just a few elements optional followed by non-optional elements, use [&optional specs...]. To specify that several elements must all match or none, use &optional [specs...]. See the defun example below.
&rest
All following elements in the specification list are repeated zero or more times. In the last repetition, however, it is not a problem if the expression runs out before matching all of the elements of the specification list. To repeat only a few elements, use [&rest specs...]. To specify several elements that must all match on every repetition, use &rest [specs...].
&or
Each of the following elements in the specification list is an alternative. One of the alternatives must match, or the &or specification fails. Each list element following &or is a single alternative. To group two or more list elements as a single alternative, enclose them in [...].
&not
Each of the following elements is matched as alternatives as if by using &or, but if any of them match, the specification fails. If none of them match, nothing is matched, but the &not specification succeeds.
&define
Indicates that the specification is for a defining form. The defining form itself is not instrumented (that is, Edebug does not stop before and after the defining form), but forms inside it typically will be instrumented. The &define keyword should be the first element in a list specification.
nil
This is successful when there are no more arguments to match at the current argument list level; otherwise it fails. See sublist specifications and the backquote example below.
gate
No argument is matched but backtracking through the gate is disabled while matching the remainder of the specifications at this level. This is primarily used to generate more specific syntax error messages. See section Backtracking in Specifications, for more details. Also see the let example below.
other-symbol
Any other symbol in a specification list may be a predicate or an indirect specification. If the symbol has an Edebug specification, this indirect specification should be either a list specification that is used in place of the symbol, or a function that is called to process the arguments. The specification may be defined with def-edebug-spec just as for macros. See the defun example below. Otherwise, the symbol should be a predicate. The predicate is called with the argument and the specification fails if the predicate returns nil. In either case, that argument is not instrumented. Some suitable predicates include symbolp, integerp, stringp, vectorp, and atom.
[elements...]
A vector of elements groups the elements into a single group specification. Its meaning has nothing to do with vectors.
"string"
The argument should be a symbol named string. This specification is equivalent to the quoted symbol, 'symbol, where the name of symbol is the string, but the string form is preferred.
(vector elements...)
The argument should be a vector whose elements must match the elements in the specification. See the backquote example below.
(elements...)
Any other list is a sublist specification and the argument must be a list whose elements match the specification elements. A sublist specification may be a dotted list and the corresponding list argument may then be a dotted list. Alternatively, the last CDR of a dotted list specification may be another sublist specification (via a grouping or an indirect specification, e.g., (spec . [(more specs...)])) whose elements match the non-dotted list arguments. This is useful in recursive specifications such as in the backquote example below. Also see the description of a nil specification above for terminating such recursion. Note that a sublist specification written as (specs . nil) is equivalent to (specs), and (specs . (sublist-elements...)) is equivalent to (specs sublist-elements...).
Here is a list of additional specifications that may appear only after &define. See the defun example below.

name
The argument, a symbol, is the name of the defining form. A defining form is not required to have a name field; and it may have multiple name fields.
:name
This construct does not actually match an argument. The element following :name should be a symbol; it is used as an additional name component for the definition. You can use this to add a unique, static component to the name of the definition. It may be used more than once.
arg
The argument, a symbol, is the name of an argument of the defining form. However, lambda-list keywords (symbols starting with `&') are not allowed.
lambda-list
This matches a lambda list--the argument list of a lambda expression.
def-body
The argument is the body of code in a definition. This is like body, described above, but a definition body must be instrumented with a different Edebug call that looks up information associated with the definition. Use def-body for the highest level list of forms within the definition.
def-form
The argument is a single, highest-level form in a definition. This is like def-body, except use this to match a single form rather than a list of forms. As a special case, def-form also means that tracing information is not output when the form is executed. See the interactive example below.
Backtracking in Specifications

If a specification fails to match at some point, this does not necessarily mean a syntax error will be signaled; instead, backtracking will take place until all alternatives have been exhausted. Eventually every element of the argument list must be matched by some element in the specification, and every required element in the specification must match some argument. When a syntax error is detected, it might not be reported until much later after higher-level alternatives have been exhausted, and with the point positioned further from the real error. But if backtracking is disabled when an error occurs, it can be reported immediately. Note that backtracking is also reenabled automatically in several situations; it is reenabled when a new alternative is established by &optional, &rest, or &or, or at the start of processing a sublist, group, or indirect specification. The effect of enabling or disabling backtracking is limited to the remainder of the level currently being processed and lower levels.

Backtracking is disabled while matching any of the form specifications (that is, form, body, def-form, and def-body). These specifications will match any form so any error must be in the form itself rather than at a higher level.

Backtracking is also disabled after successfully matching a quoted symbol or string specification, since this usually indicates a recognized construct. But if you have a set of alternative constructs that all begin with the same symbol, you can usually work around this constraint by factoring the symbol out of the alternatives, e.g., ["foo" &or [first case] [second case] ...].

Most needs are satisfied by these two ways that bactracking is automatically disabled, but occasionally it is useful to explicitly disable backtracking by using the gate specification. This is useful when you know that no higher alternatives could apply. See the example of the let specification.

Specification Examples

It may be easier to understand Edebug specifications by studying the examples provided here.

A let special form has a sequence of bindings and a body. Each of the bindings is either a symbol or a sublist with a symbol and optional expression. In the specification below, notice the gate inside of the sublist to prevent backtracking once a sublist is found.
(def-edebug-spec let
  ((&rest
    &or symbolp (gate symbolp &optional form))
   body))
Edebug uses the following specifications for defun and defmacro and the associated argument list and interactive specifications. It is necessary to handle interactive forms specially since an expression argument it is actually evaluated outside of the function body.
(def-edebug-spec defmacro defun) ; Indirect ref to defun spec.
(def-edebug-spec defun
  (&define name lambda-list
           [&optional stringp]   ; Match the doc string, if present.
           [&optional ("interactive" interactive)]
           def-body))

(def-edebug-spec lambda-list
  (([&rest arg]
    [&optional ["&optional" arg &rest arg]]
    &optional ["&rest" arg]
    )))

(def-edebug-spec interactive
  (&optional &or stringp def-form))    ; Notice: def-form
The specification for backquote below illustrates how to match dotted lists and use nil to terminate recursion. It also illustrates how components of a vector may be matched. (The actual specification defined by Edebug does not support dotted lists because doing so causes very deep recursion that could fail.)
(def-edebug-spec ` (backquote-form))   ; Alias just for clarity.

(def-edebug-spec backquote-form
  (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
       (backquote-form . [&or nil backquote-form])
       (vector &rest backquote-form)
       sexp))
Edebug Options

These options affect the behavior of Edebug:

User Option: edebug-setup-hook
Functions to call before Edebug is used. Each time it is set to a new value, Edebug will call those functions once and then edebug-setup-hook is reset to nil. You could use this to load up Edebug specifications associated with a package you are using but only when you also use Edebug. See section Instrumenting for Edebug.

User Option: edebug-all-defs
If this is non-nil, normal evaluation of defining forms such as defun and defmacro instruments them for Edebug. This applies to eval-defun, eval-region, eval-buffer, and eval-current-buffer.

Use the command M-x edebug-all-defs to toggle the value of this option. See section Instrumenting for Edebug.

User Option: edebug-all-forms
If this is non-nil, the commands eval-defun, eval-region, eval-buffer, and eval-current-buffer instrument all forms, even those that don't define anything. This doesn't apply to loading or evaluations in the minibuffer.

Use the command M-x edebug-all-forms to toggle the value of this option. See section Instrumenting for Edebug.

User Option: edebug-save-windows
If this is non-nil, Edebug saves and restores the window configuration. That takes some time, so if your program does not care what happens to the window configurations, it is better to set this variable to nil.

If the value is a list, only the listed windows are saved and restored.

You can use the W command in Edebug to change this variable interactively. See section Edebug Display Update.

User Option: edebug-save-displayed-buffer-points
If this is non-nil, Edebug saves and restores point in all displayed buffers.

Saving and restoring point in other buffers is necessary if you are debugging code that changes the point of a buffer which is displayed in a non-selected window. If Edebug or the user then selects the window, point in that buffer will move to the window's value of point.

Saving and restoring point in all buffers is expensive, since it requires selecting each window twice, so enable this only if you need it. See section Edebug Display Update.

User Option: edebug-initial-mode
If this variable is non-nil, it specifies the initial execution mode for Edebug when it is first activated. Possible values are step, next, go, Go-nonstop, trace, Trace-fast, continue, and Continue-fast.

The default value is step. See section Edebug Execution Modes.

User Option: edebug-trace
Non-nil means display a trace of function entry and exit. Tracing output is displayed in a buffer named `*edebug-trace*', one function entry or exit per line, indented by the recursion level.

The default value is nil.

Also see edebug-tracing, in section Trace Buffer.

User Option: edebug-test-coverage
If non-nil, Edebug tests coverage of all expressions debugged. See section Coverage Testing.

User Option: edebug-continue-kbd-macro
If non-nil, continue defining or executing any keyboard macro that is executing outside of Edebug. Use this with caution since it is not debugged. See section Edebug Execution Modes.

User Option: edebug-on-error
Edebug binds debug-on-error to this value, if debug-on-error was previously nil. See section Trapping Errors.

User Option: edebug-on-quit
Edebug binds debug-on-quit to this value, if debug-on-quit was previously nil. See section Trapping Errors.

If you change the values of edebug-on-error or edebug-on-quit while Edebug is active, their values won't be used until the next time Edebug is invoked via a new command.

User Option: edebug-global-break-condition
If non-nil, an expression to test for at every stop point. If the result is non-nil, then break. Errors are ignored. See section Global Break Condition.

Debugging Invalid Lisp Syntax

The Lisp reader reports invalid syntax, but cannot say where the real problem is. For example, the error "End of file during parsing" in evaluating an expression indicates an excess of open parentheses (or square brackets). The reader detects this imbalance at the end of the file, but it cannot figure out where the close parenthesis should have been. Likewise, "Invalid read syntax: ")"" indicates an excess close parenthesis or missing open parenthesis, but does not say where the missing parenthesis belongs. How, then, to find what to change?

If the problem is not simply an imbalance of parentheses, a useful technique is to try C-M-e at the beginning of each defun, and see if it goes to the place where that defun appears to end. If it does not, there is a problem in that defun.

However, unmatched parentheses are the most common syntax errors in Lisp, and we can give further advice for those cases. (In addition, just moving point through the code with Show Paren mode enabled might find the mismatch.)

Excess Open Parentheses

The first step is to find the defun that is unbalanced. If there is an excess open parenthesis, the way to do this is to insert a close parenthesis at the end of the file and type C-M-b (backward-sexp). This will move you to the beginning of the defun that is unbalanced. (Then type C-SPC C-_ C-u C-SPC to set the mark there, undo the insertion of the close parenthesis, and finally return to the mark.)

The next step is to determine precisely what is wrong. There is no way to be sure of this except by studying the program, but often the existing indentation is a clue to where the parentheses should have been. The easiest way to use this clue is to reindent with C-M-q and see what moves. But don't do this yet! Keep reading, first.

Before you do this, make sure the defun has enough close parentheses. Otherwise, C-M-q will get an error, or will reindent all the rest of the file until the end. So move to the end of the defun and insert a close parenthesis there. Don't use C-M-e to move there, since that too will fail to work until the defun is balanced.

Now you can go to the beginning of the defun and type C-M-q. Usually all the lines from a certain point to the end of the function will shift to the right. There is probably a missing close parenthesis, or a superfluous open parenthesis, near that point. (However, don't assume this is true; study the code to make sure.) Once you have found the discrepancy, undo the C-M-q with C-_, since the old indentation is probably appropriate to the intended parentheses.

After you think you have fixed the problem, use C-M-q again. If the old indentation actually fit the intended nesting of parentheses, and you have put back those parentheses, C-M-q should not change anything.

Excess Close Parentheses

To deal with an excess close parenthesis, first insert an open parenthesis at the beginning of the file, back up over it, and type C-M-f to find the end of the unbalanced defun. (Then type C-SPC C-_ C-u C-SPC to set the mark there, undo the insertion of the open parenthesis, and finally return to the mark.)

Then find the actual matching close parenthesis by typing C-M-f at the beginning of that defun. This will leave you somewhere short of the place where the defun ought to end. It is possible that you will find a spurious close parenthesis in that vicinity.

If you don't see a problem at that point, the next thing to do is to type C-M-q at the beginning of the defun. A range of lines will probably shift left; if so, the missing open parenthesis or spurious close parenthesis is probably near the first of those lines. (However, don't assume this is true; study the code to make sure.) Once you have found the discrepancy, undo the C-M-q with C-_, since the old indentation is probably appropriate to the intended parentheses.

After you think you have fixed the problem, use C-M-q again. If the old indentation actually fit the intended nesting of parentheses, and you have put back those parentheses, C-M-q should not change anything.

Debugging Problems in Compilation

When an error happens during byte compilation, it is normally due to invalid syntax in the program you are compiling. The compiler prints a suitable error message in the `*Compile-Log*' buffer, and then stops. The message may state a function name in which the error was found, or it may not. Either way, here is how to find out where in the file the error occurred.

What you should do is switch to the buffer ` *Compiler Input*'. (Note that the buffer name starts with a space, so it does not show up in M-x list-buffers.) This buffer contains the program being compiled, and point shows how far the byte compiler was able to read.

If the error was due to invalid Lisp syntax, point shows exactly where the invalid syntax was detected. The cause of the error is not necessarily near by! Use the techniques in the previous section to find the error.

If the error was detected while compiling a form that had been read successfully, then point is located at the end of the form. In this case, this technique can't localize the error precisely, but can still show you which function to check.
Reading and Printing Lisp Objects

Printing and reading are the operations of converting Lisp objects to textual form and vice versa. They use the printed representations and read syntax described in section Lisp Data Types.

This chapter describes the Lisp functions for reading and printing. It also describes streams, which specify where to get the text (if reading) or where to put it (if printing).

Introduction to Reading and Printing

Reading a Lisp object means parsing a Lisp expression in textual form and producing a corresponding Lisp object. This is how Lisp programs get into Lisp from files of Lisp code. We call the text the read syntax of the object. For example, the text `(a . 5)' is the read syntax for a cons cell whose CAR is a and whose CDR is the number 5.

Printing a Lisp object means producing text that represents that object--converting the object to its printed representation (see section Printed Representation and Read Syntax). Printing the cons cell described above produces the text `(a . 5)'.

Reading and printing are more or less inverse operations: printing the object that results from reading a given piece of text often produces the same text, and reading the text that results from printing an object usually produces a similar-looking object. For example, printing the symbol foo produces the text `foo', and reading that text returns the symbol foo. Printing a list whose elements are a and b produces the text `(a b)', and reading that text produces a list (but not the same list) with elements a and b.

However, these two operations are not precisely inverses. There are three kinds of exceptions:

Printing can produce text that cannot be read. For example, buffers, windows, frames, subprocesses and markers print as text that starts with `#'; if you try to read this text, you get an error. There is no way to read those data types.
One object can have multiple textual representations. For example, `1' and `01' represent the same integer, and `(a b)' and `(a . (b))' represent the same list. Reading will accept any of the alternatives, but printing must choose one of them.
Comments can appear at certain points in the middle of an object's read sequence without affecting the result of reading it.

Input Streams

Most of the Lisp functions for reading text take an input stream as an argument. The input stream specifies where or how to get the characters of the text to be read. Here are the possible types of input stream:

buffer
The input characters are read from buffer, starting with the character directly after point. Point advances as characters are read.
marker
The input characters are read from the buffer that marker is in, starting with the character directly after the marker. The marker position advances as characters are read. The value of point in the buffer has no effect when the stream is a marker.
string
The input characters are taken from string, starting at the first character in the string and using as many characters as required.
function
The input characters are generated by function, which must support two kinds of calls:

When it is called with no arguments, it should return the next character.
When it is called with one argument (always a character), function should save the argument and arrange to return it on the next call. This is called unreading the character; it happens when the Lisp reader reads one character too many and wants to "put it back where it came from". In this case, it makes no difference what value function returns.

t
t used as a stream means that the input is read from the minibuffer. In fact, the minibuffer is invoked once and the text given by the user is made into a string that is then used as the input stream.
nil
nil supplied as an input stream means to use the value of standard-input instead; that value is the default input stream, and must be a non-nil input stream.
symbol
A symbol as input stream is equivalent to the symbol's function definition (if any).
Here is an example of reading from a stream that is a buffer, showing where point is located before and after:
---------- Buffer: foo ----------
This-!- is the contents of foo.
---------- Buffer: foo ----------

(read (get-buffer "foo"))
     => is
(read (get-buffer "foo"))
     => the

---------- Buffer: foo ----------
This is the-!- contents of foo.
---------- Buffer: foo ----------
Note that the first read skips a space. Reading skips any amount of whitespace preceding the significant text.

Here is an example of reading from a stream that is a marker, initially positioned at the beginning of the buffer shown. The value read is the symbol This.
---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------

(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
     => #<marker at 1 in foo>
(read m)
     => This
m
     => #<marker at 5 in foo>   ;; Before the first space.
Here we read from the contents of a string:
(read "(When in) the course")
     => (When in)
The following example reads from the minibuffer. The prompt is: `Lisp expression: '. (That is always the prompt used when you read from the stream t.) The user's input is shown following the prompt.
(read t)
     => 23
---------- Buffer: Minibuffer ----------
Lisp expression: 23 RET
---------- Buffer: Minibuffer ----------
Finally, here is an example of a stream that is a function, named useless-stream. Before we use the stream, we initialize the variable useless-list to a list of characters. Then each call to the function useless-stream obtains the next character in the list or unreads a character by adding it to the front of the list.
(setq useless-list (append "XY()" nil))
     => (88 89 40 41)

(defun useless-stream (&optional unread)
  (if unread
      (setq useless-list (cons unread useless-list))
    (prog1 (car useless-list)
           (setq useless-list (cdr useless-list)))))
     => useless-stream
Now we read using the stream thus constructed:
(read 'useless-stream)
     => XY

useless-list
     => (40 41)
Note that the open and close parentheses remain in the list. The Lisp reader encountered the open parenthesis, decided that it ended the input, and unread it. Another attempt to read from the stream at this point would read `()' and return nil.

Function: get-file-char
This function is used internally as an input stream to read from the input file opened by the function load. Don't use this function yourself.

Input Functions

This section describes the Lisp functions and variables that pertain to reading.

In the functions below, stream stands for an input stream (see the previous section). If stream is nil or omitted, it defaults to the value of standard-input.

An end-of-file error is signaled if reading encounters an unterminated list, vector, or string.

Function: read &optional stream
This function reads one textual Lisp expression from stream, returning it as a Lisp object. This is the basic Lisp input function.

Function: read-from-string string &optional start end
This function reads the first textual Lisp expression from the text in string. It returns a cons cell whose CAR is that expression, and whose CDR is an integer giving the position of the next remaining character in the string (i.e., the first one not read).

If start is supplied, then reading begins at index start in the string (where the first character is at index 0). If you specify end, then reading is forced to stop just before that index, as if the rest of the string were not there.

For example:
(read-from-string "(setq x 55) (setq y 5)")
     => ((setq x 55) . 11)
(read-from-string "\"A short string\"")
     => ("A short string" . 16)

;; Read starting at the first character.
(read-from-string "(list 112)" 0)
     => ((list 112) . 10)
;; Read starting at the second character.
(read-from-string "(list 112)" 1)
     => (list . 5)
;; Read starting at the seventh character,
;;   and stopping at the ninth.
(read-from-string "(list 112)" 6 8)
     => (11 . 8)
Variable: standard-input
This variable holds the default input stream--the stream that read uses when the stream argument is nil.

Output Streams

An output stream specifies what to do with the characters produced by printing. Most print functions accept an output stream as an optional argument. Here are the possible types of output stream:

buffer
The output characters are inserted into buffer at point. Point advances as characters are inserted.
marker
The output characters are inserted into the buffer that marker points into, at the marker position. The marker position advances as characters are inserted. The value of point in the buffer has no effect on printing when the stream is a marker, and this kind of printing does not move point.
function
The output characters are passed to function, which is responsible for storing them away. It is called with a single character as argument, as many times as there are characters to be output, and is responsible for storing the characters wherever you want to put them.
t
The output characters are displayed in the echo area.
nil
nil specified as an output stream means to use the value of standard-output instead; that value is the default output stream, and must not be nil.
symbol
A symbol as output stream is equivalent to the symbol's function definition (if any).
Many of the valid output streams are also valid as input streams. The difference between input and output streams is therefore more a matter of how you use a Lisp object, than of different types of object.

Here is an example of a buffer used as an output stream. Point is initially located as shown immediately before the `h' in `the'. At the end, point is located directly before that same `h'.
---------- Buffer: foo ----------
This is t-!-he contents of foo.
---------- Buffer: foo ----------

(print "This is the output" (get-buffer "foo"))
     => "This is the output"

---------- Buffer: foo ----------
This is t
"This is the output"
-!-he contents of foo.
---------- Buffer: foo ----------
Now we show a use of a marker as an output stream. Initially, the marker is in buffer foo, between the `t' and the `h' in the word `the'. At the end, the marker has advanced over the inserted text so that it remains positioned before the same `h'. Note that the location of point, shown in the usual fashion, has no effect.
---------- Buffer: foo ----------
This is the -!-output
---------- Buffer: foo ----------

(setq m (copy-marker 10))
     => #<marker at 10 in foo>

(print "More output for foo." m)
     => "More output for foo."

---------- Buffer: foo ----------
This is t
"More output for foo."
he -!-output
---------- Buffer: foo ----------

m
     => #<marker at 34 in foo>
The following example shows output to the echo area:
(print "Echo Area output" t)
     => "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------
Finally, we show the use of a function as an output stream. The function eat-output takes each character that it is given and conses it onto the front of the list last-output (see section Building Cons Cells and Lists). At the end, the list contains all the characters output, but in reverse order.
(setq last-output nil)
     => nil

(defun eat-output (c)
  (setq last-output (cons c last-output)))
     => eat-output

(print "This is the output" 'eat-output)
     => "This is the output"

last-output
     => (10 34 116 117 112 116 117 111 32 101 104
    116 32 115 105 32 115 105 104 84 34 10)
Now we can put the output in the proper order by reversing the list:
(concat (nreverse last-output))
     => "
\"This is the output\"
"
Calling concat converts the list to a string so you can see its contents more clearly.

Output Functions

This section describes the Lisp functions for printing Lisp objects--converting objects into their printed representation.

Some of the Emacs printing functions add quoting characters to the output when necessary so that it can be read properly. The quoting characters used are `"' and `\'; they distinguish strings from symbols, and prevent punctuation characters in strings and symbols from being taken as delimiters when reading. See section Printed Representation and Read Syntax, for full details. You specify quoting or no quoting by the choice of printing function.

If the text is to be read back into Lisp, then you should print with quoting characters to avoid ambiguity. Likewise, if the purpose is to describe a Lisp object clearly for a Lisp programmer. However, if the purpose of the output is to look nice for humans, then it is usually better to print without quoting.

Lisp objects can refer to themselves. Printing a self-referential object in the normal way would require an infinite amount of text, and the attempt could cause infinite recursion. Emacs detects such recursion and prints `#level' instead of recursively printing an object already being printed. For example, here `#0' indicates a recursive reference to the object at level 0 of the current print operation:
(setq foo (list nil))
     => (nil)
(setcar foo foo)
     => (#0)
In the functions below, stream stands for an output stream. (See the previous section for a description of output streams.) If stream is nil or omitted, it defaults to the value of standard-output.

Function: print object &optional stream
The print function is a convenient way of printing. It outputs the printed representation of object to stream, printing in addition one newline before object and another after it. Quoting characters are used. print returns object. For example:
(progn (print 'The\ cat\ in)
       (print "the hat")
       (print " came back"))
     -|
     -| The\ cat\ in
     -|
     -| "the hat"
     -|
     -| " came back"
     -|
     => " came back"
Function: prin1 object &optional stream
This function outputs the printed representation of object to stream. It does not print newlines to separate output as print does, but it does use quoting characters just like print. It returns object.
(progn (prin1 'The\ cat\ in)
       (prin1 "the hat")
       (prin1 " came back"))
     -| The\ cat\ in"the hat"" came back"
     => " came back"
Function: princ object &optional stream
This function outputs the printed representation of object to stream. It returns object.

This function is intended to produce output that is readable by people, not by read, so it doesn't insert quoting characters and doesn't put double-quotes around the contents of strings. It does not add any spacing between calls.
(progn
  (princ 'The\ cat)
  (princ " in the \"hat\""))
     -| The cat in the "hat"
     => " in the \"hat\""
Function: terpri &optional stream
This function outputs a newline to stream. The name stands for "terminate print".

Function: write-char character &optional stream
This function outputs character to stream. It returns character.

Function: prin1-to-string object &optional noescape
This function returns a string containing the text that prin1 would have printed for the same argument.
(prin1-to-string 'foo)
     => "foo"
(prin1-to-string (mark-marker))
     => "#<marker at 2773 in strings.texi>"
If noescape is non-nil, that inhibits use of quoting characters in the output. (This argument is supported in Emacs versions 19 and later.)
(prin1-to-string "foo")
     => "\"foo\""
(prin1-to-string "foo" t)
     => "foo"
See format, in section Conversion of Characters and Strings, for other ways to obtain the printed representation of a Lisp object as a string.

Macro: with-output-to-string body...
This macro executes the body forms with standard-output set up to feed output into a string. Then it returns that string.

For example, if the current buffer name is `foo',
(with-output-to-string
  (princ "The buffer is ")
  (princ (buffer-name)))
returns "The buffer is foo".

Variables Affecting Output

Variable: standard-output
The value of this variable is the default output stream--the stream that print functions use when the stream argument is nil.

Variable: print-escape-newlines
If this variable is non-nil, then newline characters in strings are printed as `\n' and formfeeds are printed as `\f'. Normally these characters are printed as actual newlines and formfeeds.

This variable affects the print functions prin1 and print that print with quoting. It does not affect princ. Here is an example using prin1:
(prin1 "a\nb")
     -| "a
     -| b"
     => "a
b"

(let ((print-escape-newlines t))
  (prin1 "a\nb"))
     -| "a\nb"
     => "a
b"
In the second expression, the local binding of print-escape-newlines is in effect during the call to prin1, but not during the printing of the result.

Variable: print-escape-nonascii
If this variable is non-nil, then unibyte non-ASCII characters in strings are unconditionally printed as backslash sequences by the print functions prin1 and print that print with quoting.

Those functions also use backslash sequences for unibyte non-ASCII characters, regardless of the value of this variable, when the output stream is a multibyte buffer or a marker pointing into one.

Variable: print-escape-multibyte
If this variable is non-nil, then multibyte non-ASCII characters in strings are unconditionally printed as backslash sequences by the print functions prin1 and print that print with quoting.

Those functions also use backslash sequences for multibyte non-ASCII characters, regardless of the value of this variable, when the output stream is a unibyte buffer or a marker pointing into one.

Variable: print-length
The value of this variable is the maximum number of elements to print in any list, vector or bool-vector. If an object being printed has more than this many elements, it is abbreviated with an ellipsis.

If the value is nil (the default), then there is no limit.
(setq print-length 2)
     => 2
(print '(1 2 3 4 5))
     -| (1 2 ...)
     => (1 2 ...)
Variable: print-level
The value of this variable is the maximum depth of nesting of parentheses and brackets when printed. Any list or vector at a depth exceeding this limit is abbreviated with an ellipsis. A value of nil (which is the default) means no limit.
Minibuffers

A minibuffer is a special buffer that Emacs commands use to read arguments more complicated than the single numeric prefix argument. These arguments include file names, buffer names, and command names (as in M-x). The minibuffer is displayed on the bottom line of the frame, in the same place as the echo area, but only while it is in use for reading an argument.

Introduction to Minibuffers

In most ways, a minibuffer is a normal Emacs buffer. Most operations within a buffer, such as editing commands, work normally in a minibuffer. However, many operations for managing buffers do not apply to minibuffers. The name of a minibuffer always has the form ` *Minibuf-number', and it cannot be changed. Minibuffers are displayed only in special windows used only for minibuffers; these windows always appear at the bottom of a frame. (Sometimes frames have no minibuffer window, and sometimes a special kind of frame contains nothing but a minibuffer window; see section Minibuffers and Frames.)

The minibuffer's window is normally a single line. You can resize it temporarily with the window sizing commands; it reverts to its normal size when the minibuffer is exited. You can resize it permanently by using the window sizing commands in the frame's other window, when the minibuffer is not active. If the frame contains just a minibuffer, you can change the minibuffer's size by changing the frame's size.

If a command uses a minibuffer while there is an active minibuffer, this is called a recursive minibuffer. The first minibuffer is named ` *Minibuf-0*'. Recursive minibuffers are named by incrementing the number at the end of the name. (The names begin with a space so that they won't show up in normal buffer lists.) Of several recursive minibuffers, the innermost (or most recently entered) is the active minibuffer. We usually call this "the" minibuffer. You can permit or forbid recursive minibuffers by setting the variable enable-recursive-minibuffers or by putting properties of that name on command symbols (see section Minibuffer Miscellany).

Like other buffers, a minibuffer may use any of several local keymaps (see section Keymaps); these contain various exit commands and in some cases completion commands (see section Completion).

minibuffer-local-map is for ordinary input (no completion).
minibuffer-local-ns-map is similar, except that SPC exits just like RET. This is used mainly for Mocklisp compatibility.
minibuffer-local-completion-map is for permissive completion.
minibuffer-local-must-match-map is for strict completion and for cautious completion.

Reading Text Strings with the Minibuffer

Most often, the minibuffer is used to read text as a string. It can also be used to read a Lisp object in textual form. The most basic primitive for minibuffer input is read-from-minibuffer; it can do either one.

In most cases, you should not call minibuffer input functions in the middle of a Lisp function. Instead, do all minibuffer input as part of reading the arguments for a command, in the interactive specification. See section Defining Commands.

Function: read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
This function is the most general way to get input through the minibuffer. By default, it accepts arbitrary text and returns it as a string; however, if read is non-nil, then it uses read to convert the text into a Lisp object (see section Input Functions).

The first thing this function does is to activate a minibuffer and display it with prompt-string as the prompt. This value must be a string. Then the user can edit text in the minibuffer.

When the user types a command to exit the minibuffer, read-from-minibuffer constructs the return value from the text in the minibuffer. Normally it returns a string containing that text. However, if read is non-nil, read-from-minibuffer reads the text and returns the resulting Lisp object, unevaluated. (See section Input Functions, for information about reading.)

The argument default specifies a default value to make available through the history commands. It should be a string, or nil. If read is non-nil, then default is also used as the input to read, if the user enters empty input. However, in the usual case (where read is nil), read-from-minibuffer does not return default when the user enters empty input; it returns an empty string, "". In this respect, it is different from all the other minibuffer input functions in this chapter.

If keymap is non-nil, that keymap is the local keymap to use in the minibuffer. If keymap is omitted or nil, the value of minibuffer-local-map is used as the keymap. Specifying a keymap is the most important way to customize the minibuffer for various applications such as completion.

The argument hist specifies which history list variable to use for saving the input and for history commands used in the minibuffer. It defaults to minibuffer-history. See section Minibuffer History.

If the variable minibuffer-allow-text-properties is non-nil, then the string which is returned includes whatever text properties were present in the minibuffer. Otherwise all the text properties are stripped when the value is returned.

If the argument inherit-input-method is non-nil, then the minibuffer inherits the current input method (see section Input Methods) and the setting of enable-multibyte-characters (see section Text Representations) from whichever buffer was current before entering the minibuffer.

If initial-contents is a string, read-from-minibuffer inserts it into the minibuffer, leaving point at the end, before the user starts to edit the text. The minibuffer appears with this text as its initial contents.

Alternatively, initial-contents can be a cons cell of the form (string . position). This means to insert string in the minibuffer but put point position characters from the beginning, rather than at the end.

Usage note: The initial-contents argument and the default argument are two alternative features for more or less the same job. It does not make sense to use both features in a single call to read-from-minibuffer. In general, we recommend using default, since this permits the user to insert the default value when it is wanted, but does not burden the user with deleting it from the minibuffer on other occasions.

Function: read-string prompt &optional initial history default inherit-input-method
This function reads a string from the minibuffer and returns it. The arguments prompt and initial are used as in read-from-minibuffer. The keymap used is minibuffer-local-map.

The optional argument history, if non-nil, specifies a history list and optionally the initial position in the list. The optional argument default specifies a default value to return if the user enters null input; it should be a string. The optional argument inherit-input-method specifies whether to inherit the current buffer's input method.

This function is a simplified interface to the read-from-minibuffer function:
(read-string prompt initial history default inherit)
==
(let ((value
       (read-from-minibuffer prompt initial nil nil
                             history default inherit)))
  (if (equal value "")
      default
    value))
Variable: minibuffer-allow-text-properties
If this variable is nil, then read-from-minibuffer strips all text properties from the minibuffer input before returning it. Since all minibuffer input uses read-from-minibuffer, this variable applies to all minibuffer input.

Note that the completion functions discard text properties unconditionally, regardless of the value of this variable.

Variable: minibuffer-local-map
This is the default local keymap for reading from the minibuffer. By default, it makes the following bindings:

C-j
exit-minibuffer
RET
exit-minibuffer
C-g
abort-recursive-edit
M-n
next-history-element
M-p
previous-history-element
M-r
next-matching-history-element
M-s
previous-matching-history-element

Function: read-no-blanks-input prompt &optional initial inherit-input-method
This function reads a string from the minibuffer, but does not allow whitespace characters as part of the input: instead, those characters terminate the input. The arguments prompt, initial, and inherit-input-method are used as in read-from-minibuffer.

This is a simplified interface to the read-from-minibuffer function, and passes the value of the minibuffer-local-ns-map keymap as the keymap argument for that function. Since the keymap minibuffer-local-ns-map does not rebind C-q, it is possible to put a space into the string, by quoting it.
(read-no-blanks-input prompt initial)
==
(read-from-minibuffer prompt initial minibuffer-local-ns-map)
Variable: minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local keymap in the function read-no-blanks-input. By default, it makes the following bindings, in addition to those of minibuffer-local-map:

SPC
exit-minibuffer
TAB
exit-minibuffer
?
self-insert-and-exit
Reading Lisp Objects with the Minibuffer

This section describes functions for reading Lisp objects with the minibuffer.

Function: read-minibuffer prompt &optional initial
This function reads a Lisp object using the minibuffer, and returns it without evaluating it. The arguments prompt and initial are used as in read-from-minibuffer.

This is a simplified interface to the read-from-minibuffer function:
(read-minibuffer prompt initial)
==
(read-from-minibuffer prompt initial nil t)
Here is an example in which we supply the string "(testing)" as initial input:
(read-minibuffer
 "Enter an expression: " (format "%s" '(testing)))

;; Here is how the minibuffer is displayed:

---------- Buffer: Minibuffer ----------
Enter an expression: (testing)-!-
---------- Buffer: Minibuffer ----------
The user can type RET immediately to use the initial input as a default, or can edit the input.

Function: eval-minibuffer prompt &optional initial
This function reads a Lisp expression using the minibuffer, evaluates it, then returns the result. The arguments prompt and initial are used as in read-from-minibuffer.

This function simply evaluates the result of a call to read-minibuffer:
(eval-minibuffer prompt initial)
==
(eval (read-minibuffer prompt initial))
Function: edit-and-eval-command prompt form
This function reads a Lisp expression in the minibuffer, and then evaluates it. The difference between this command and eval-minibuffer is that here the initial form is not optional and it is treated as a Lisp object to be converted to printed representation rather than as a string of text. It is printed with prin1, so if it is a string, double-quote characters (`"') appear in the initial text. See section Output Functions.

The first thing edit-and-eval-command does is to activate the minibuffer with prompt as the prompt. Then it inserts the printed representation of form in the minibuffer, and lets the user edit it. When the user exits the minibuffer, the edited text is read with read and then evaluated. The resulting value becomes the value of edit-and-eval-command.

In the following example, we offer the user an expression with initial text which is a valid form already:
(edit-and-eval-command "Please edit: " '(forward-word 1))

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)-!-
---------- Buffer: Minibuffer ----------
Typing RET right away would exit the minibuffer and evaluate the expression, thus moving point forward one word. edit-and-eval-command returns nil in this example.

Minibuffer History

A minibuffer history list records previous minibuffer inputs so the user can reuse them conveniently. A history list is actually a symbol, not a list; it is a variable whose value is a list of strings (previous inputs), most recent first.

There are many separate history lists, used for different kinds of inputs. It's the Lisp programmer's job to specify the right history list for each use of the minibuffer.

The basic minibuffer input functions read-from-minibuffer and completing-read both accept an optional argument named hist which is how you specify the history list. Here are the possible values:

variable
Use variable (a symbol) as the history list.
(variable . startpos)
Use variable (a symbol) as the history list, and assume that the initial history position is startpos (an integer, counting from zero which specifies the most recent element of the history). If you specify startpos, then you should also specify that element of the history as the initial minibuffer contents, for consistency.
If you don't specify hist, then the default history list minibuffer-history is used. For other standard history lists, see below. You can also create your own history list variable; just initialize it to nil before the first use.

Both read-from-minibuffer and completing-read add new elements to the history list automatically, and provide commands to allow the user to reuse items on the list. The only thing your program needs to do to use a history list is to initialize it and to pass its name to the input functions when you wish. But it is safe to modify the list by hand when the minibuffer input functions are not using it.

Here are some of the standard minibuffer history list variables:

Variable: minibuffer-history
The default history list for minibuffer history input.

Variable: query-replace-history
A history list for arguments to query-replace (and similar arguments to other commands).

Variable: file-name-history
A history list for file-name arguments.

Variable: buffer-name-history
A history list for buffer-name arguments.

Variable: regexp-history
A history list for regular expression arguments.

Variable: extended-command-history
A history list for arguments that are names of extended commands.

Variable: shell-command-history
A history list for arguments that are shell commands.

Variable: read-expression-history
A history list for arguments that are Lisp expressions to evaluate.

Completion

Completion is a feature that fills in the rest of a name starting from an abbreviation for it. Completion works by comparing the user's input against a list of valid names and determining how much of the name is determined uniquely by what the user has typed. For example, when you type C-x b (switch-to-buffer) and then type the first few letters of the name of the buffer to which you wish to switch, and then type TAB (minibuffer-complete), Emacs extends the name as far as it can.

Standard Emacs commands offer completion for names of symbols, files, buffers, and processes; with the functions in this section, you can implement completion for other kinds of names.

The try-completion function is the basic primitive for completion: it returns the longest determined completion of a given initial string, with a given set of strings to match against.

The function completing-read provides a higher-level interface for completion. A call to completing-read specifies how to determine the list of valid names. The function then activates the minibuffer with a local keymap that binds a few keys to commands useful for completion. Other functions provide convenient simple interfaces for reading certain kinds of names with completion.

Basic Completion Functions

The two functions try-completion and all-completions have nothing in themselves to do with minibuffers. We describe them in this chapter so as to keep them near the higher-level completion features that do use the minibuffer.

Function: try-completion string collection &optional predicate
This function returns the longest common substring of all possible completions of string in collection. The value of collection must be an alist, an obarray, or a function that implements a virtual set of strings (see below).

Completion compares string against each of the permissible completions specified by collection; if the beginning of the permissible completion equals string, it matches. If no permissible completions match, try-completion returns nil. If only one permissible completion matches, and the match is exact, then try-completion returns t. Otherwise, the value is the longest initial sequence common to all the permissible completions that match.

If collection is an alist (see section Association Lists), the CARs of the alist elements form the set of permissible completions.

If collection is an obarray (see section Creating and Interning Symbols), the names of all symbols in the obarray form the set of permissible completions. The global variable obarray holds an obarray containing the names of all interned Lisp symbols.

Note that the only valid way to make a new obarray is to create it empty and then add symbols to it one by one using intern. Also, you cannot intern a given symbol in more than one obarray.

If the argument predicate is non-nil, then it must be a function of one argument. It is used to test each possible match, and the match is accepted only if predicate returns non-nil. The argument given to predicate is either a cons cell from the alist (the CAR of which is a string) or else it is a symbol (not a symbol name) from the obarray.

You can also use a symbol that is a function as collection. Then the function is solely responsible for performing completion; try-completion returns whatever this function returns. The function is called with three arguments: string, predicate and nil. (The reason for the third argument is so that the same function can be used in all-completions and do the appropriate thing in either case.) See section Programmed Completion.

In the first of the following examples, the string `foo' is matched by three of the alist CARs. All of the matches begin with the characters `fooba', so that is the result. In the second example, there is only one possible match, and it is exact, so the value is t.
(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
     => "fooba"

(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
     => t
In the following example, numerous symbols begin with the characters `forw', and all of them begin with the word `forward'. In most of the symbols, this is followed with a `-', but not in all, so no more than `forward' can be completed.
(try-completion "forw" obarray)
     => "forward"
Finally, in the following example, only two of the three possible matches pass the predicate test (the string `foobaz' is too short). Both of those begin with the string `foobar'.
(defun test (s)
  (> (length (car s)) 6))
     => test
(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     => "foobar"
Function: all-completions string collection &optional predicate nospace
This function returns a list of all possible completions of string. The arguments to this function are the same as those of try-completion.

If collection is a function, it is called with three arguments: string, predicate and t; then all-completions returns whatever the function returns. See section Programmed Completion.

If nospace is non-nil, completions that start with a space are ignored unless string also starts with a space.

Here is an example, using the function test shown in the example for try-completion:
(defun test (s)
  (> (length (car s)) 6))
     => test

(all-completions
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     => ("foobar1" "foobar2")
Variable: completion-ignore-case
If the value of this variable is non-nil, Emacs does not consider case significant in completion.

Completion and the Minibuffer

This section describes the basic interface for reading from the minibuffer with completion.

Function: completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
This function reads a string in the minibuffer, assisting the user by providing completion. It activates the minibuffer with prompt prompt, which must be a string.

The actual completion is done by passing collection and predicate to the function try-completion. This happens in certain commands bound in the local keymaps used for completion.

If require-match is nil, the exit commands work regardless of the input in the minibuffer. If require-match is t, the usual minibuffer exit commands won't exit unless the input completes to an element of collection. If require-match is neither nil nor t, then the exit commands won't exit unless the input already in the buffer matches an element of collection.

However, empty input is always permitted, regardless of the value of require-match; in that case, completing-read returns default. The value of default (if non-nil) is also available to the user through the history commands.

The user can exit with null input by typing RET with an empty minibuffer. Then completing-read returns "". This is how the user requests whatever default the command uses for the value being read. The user can return using RET in this way regardless of the value of require-match, and regardless of whether the empty string is included in collection.

The function completing-read works by calling read-minibuffer. It uses minibuffer-local-completion-map as the keymap if require-match is nil, and uses minibuffer-local-must-match-map if require-match is non-nil. See section Minibuffer Commands That Do Completion.

The argument hist specifies which history list variable to use for saving the input and for minibuffer history commands. It defaults to minibuffer-history. See section Minibuffer History.

If initial is non-nil, completing-read inserts it into the minibuffer as part of the input. Then it allows the user to edit the input, providing several commands to attempt completion. In most cases, we recommend using default, and not initial.

If the argument inherit-input-method is non-nil, then the minibuffer inherits the current input method (see section Input Methods) and the setting of enable-multibyte-characters (see section Text Representations) from whichever buffer was current before entering the minibuffer.

Completion ignores case when comparing the input against the possible matches, if the built-in variable completion-ignore-case is non-nil. See section Basic Completion Functions.

Here's an example of using completing-read:
(completing-read
 "Complete a foo: "
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 nil t "fo")

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
Complete a foo: fo-!-
---------- Buffer: Minibuffer ----------
If the user then types DEL DEL b RET, completing-read returns barfoo.

The completing-read function binds three variables to pass information to the commands that actually do completion. These variables are minibuffer-completion-table, minibuffer-completion-predicate and minibuffer-completion-confirm. For more information about them, see section Minibuffer Commands That Do Completion.

Minibuffer Commands That Do Completion

This section describes the keymaps, commands and user options used in the minibuffer to do completion.

Variable: minibuffer-local-completion-map
completing-read uses this value as the local keymap when an exact match of one of the completions is not required. By default, this keymap makes the following bindings:

?
minibuffer-completion-help
SPC
minibuffer-complete-word
TAB
minibuffer-complete
with other characters bound as in minibuffer-local-map (see section Reading Text Strings with the Minibuffer).

Variable: minibuffer-local-must-match-map
completing-read uses this value as the local keymap when an exact match of one of the completions is required. Therefore, no keys are bound to exit-minibuffer, the command that exits the minibuffer unconditionally. By default, this keymap makes the following bindings:

?
minibuffer-completion-help
SPC
minibuffer-complete-word
TAB
minibuffer-complete
C-j
minibuffer-complete-and-exit
RET
minibuffer-complete-and-exit
with other characters bound as in minibuffer-local-map.

Variable: minibuffer-completion-table
The value of this variable is the alist or obarray used for completion in the minibuffer. This is the global variable that contains what completing-read passes to try-completion. It is used by minibuffer completion commands such as minibuffer-complete-word.

Variable: minibuffer-completion-predicate
This variable's value is the predicate that completing-read passes to try-completion. The variable is also used by the other minibuffer completion functions.

Command: minibuffer-complete-word
This function completes the minibuffer contents by at most a single word. Even if the minibuffer contents have only one completion, minibuffer-complete-word does not add any characters beyond the first character that is not a word constituent. See section Syntax Tables.

Command: minibuffer-complete
This function completes the minibuffer contents as far as possible.

Command: minibuffer-complete-and-exit
This function completes the minibuffer contents, and exits if confirmation is not required, i.e., if minibuffer-completion-confirm is nil. If confirmation is required, it is given by repeating this command immediately--the command is programmed to work without confirmation when run twice in succession.

Variable: minibuffer-completion-confirm
When the value of this variable is non-nil, Emacs asks for confirmation of a completion before exiting the minibuffer. The function minibuffer-complete-and-exit checks the value of this variable before it exits.

Command: minibuffer-completion-help
This function creates a list of the possible completions of the current minibuffer contents. It works by calling all-completions using the value of the variable minibuffer-completion-table as the collection argument, and the value of minibuffer-completion-predicate as the predicate argument. The list of completions is displayed as text in a buffer named `*Completions*'.

Function: display-completion-list completions
This function displays completions to the stream in standard-output, usually a buffer. (See section Reading and Printing Lisp Objects, for more information about streams.) The argument completions is normally a list of completions just returned by all-completions, but it does not have to be. Each element may be a symbol or a string, either of which is simply printed, or a list of two strings, which is printed as if the strings were concatenated.

This function is called by minibuffer-completion-help. The most common way to use it is together with with-output-to-temp-buffer, like this:
(with-output-to-temp-buffer "*Completions*"
  (display-completion-list
    (all-completions (buffer-string) my-alist)))
User Option: completion-auto-help
If this variable is non-nil, the completion commands automatically display a list of possible completions whenever nothing can be completed because the next character is not uniquely determined.

High-Level Completion Functions

This section describes the higher-level convenient functions for reading certain sorts of names with completion.

In most cases, you should not call these functions in the middle of a Lisp function. When possible, do all minibuffer input as part of reading the arguments for a command, in the interactive specification. See section Defining Commands.

Function: read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a string. The argument default is the default name to use, the value to return if the user exits with an empty minibuffer. If non-nil, it should be a string or a buffer. It is mentioned in the prompt, but is not inserted in the minibuffer as initial input.

If existing is non-nil, then the name specified must be that of an existing buffer. The usual commands to exit the minibuffer do not exit if the text is not valid, and RET does completion to attempt to find a valid name. (However, default is not checked for validity; it is returned, whatever it is, if the user exits with the minibuffer empty.)

In the following example, the user enters `minibuffer.t', and then types RET. The argument existing is t, and the only buffer name starting with the given input is `minibuffer.texi', so that name is the value.
(read-buffer "Buffer name? " "foo" t)
;; After evaluation of the preceding expression,
;;   the following prompt appears,
;;   with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Buffer name? (default foo) -!-
---------- Buffer: Minibuffer ----------

;; The user types minibuffer.t RET.
     => "minibuffer.texi"
Variable: read-buffer-function
This variable specifies how to read buffer names. For example, if you set this variable to iswitchb-read-buffer, all Emacs commands that call read-buffer to read a buffer name will actually use the iswitchb package to read it.

Function: read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp symbol. The argument prompt is used as in read-from-minibuffer. Recall that a command is anything for which commandp returns t, and a command name is a symbol for which commandp returns t. See section Interactive Call.

The argument default specifies what to return if the user enters null input. It can be a symbol or a string; if it is a string, read-command interns it before returning it. If default is nil, that means no default has been specified; then if the user enters null input, the return value is nil.
(read-command "Command name? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------
If the user types forward-c RET, then this function returns forward-char.

The read-command function is a simplified interface to completing-read. It uses the variable obarray so as to complete in the set of extant Lisp symbols, and it uses the commandp predicate so as to accept only command names:
(read-command prompt)
==
(intern (completing-read prompt obarray
                         'commandp t nil))
Function: read-variable prompt &optional default
This function reads the name of a user variable and returns it as a symbol.

The argument default specifies what to return if the user enters null input. It can be a symbol or a string; if it is a string, read-variable interns it before returning it. If default is nil, that means no default has been specified; then if the user enters null input, the return value is nil.
(read-variable "Variable name? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears,
;;   with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Variable name? -!-
---------- Buffer: Minibuffer ----------
If the user then types fill-p RET, read-variable returns fill-prefix.

This function is similar to read-command, but uses the predicate user-variable-p instead of commandp:
(read-variable prompt)
==
(intern
 (completing-read prompt obarray
                  'user-variable-p t nil))
See also the functions read-coding-system and read-non-nil-coding-system, in section User-Chosen Coding Systems.

Reading File Names

Here is another high-level completion function, designed for reading a file name. It provides special features including automatic insertion of the default directory.

Function: read-file-name prompt &optional directory default existing initial
This function reads a file name in the minibuffer, prompting with prompt and providing completion. If default is non-nil, then the function returns default if the user just types RET. default is not checked for validity; it is returned, whatever it is, if the user exits with the minibuffer empty.

If existing is non-nil, then the user must specify the name of an existing file; RET performs completion to make the name valid if possible, and then refuses to exit if it is not valid. If the value of existing is neither nil nor t, then RET also requires confirmation after completion. If existing is nil, then the name of a nonexistent file is acceptable.

The argument directory specifies the directory to use for completion of relative file names. If insert-default-directory is non-nil, directory is also inserted in the minibuffer as initial input. It defaults to the current buffer's value of default-directory.

If you specify initial, that is an initial file name to insert in the buffer (after directory, if that is inserted). In this case, point goes at the beginning of initial. The default for initial is nil---don't insert any file name. To see what initial does, try the command C-x C-v. Note: we recommend using default rather than initial in most cases.

Here is an example:
(read-file-name "The file is ")

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/-!-
---------- Buffer: Minibuffer ----------
Typing manual TAB results in the following:
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texi-!-
---------- Buffer: Minibuffer ----------
If the user types RET, read-file-name returns the file name as the string "/gp/gnu/elisp/manual.texi".

User Option: insert-default-directory
This variable is used by read-file-name. Its value controls whether read-file-name starts by placing the name of the default directory in the minibuffer, plus the initial file name if any. If the value of this variable is nil, then read-file-name does not place any initial input in the minibuffer (unless you specify initial input with the initial argument). In that case, the default directory is still used for completion of relative file names, but is not displayed.

For example:
;; Here the minibuffer starts out with the default directory.
(let ((insert-default-directory t))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/-!-
---------- Buffer: Minibuffer ----------

;; Here the minibuffer is empty and only the prompt
;;   appears on its line.
(let ((insert-default-directory nil))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is -!-
---------- Buffer: Minibuffer ----------
Programmed Completion

Sometimes it is not possible to create an alist or an obarray containing all the intended possible completions. In such a case, you can supply your own function to compute the completion of a given string. This is called programmed completion.

To use this feature, pass a symbol with a function definition as the collection argument to completing-read. The function completing-read arranges to pass your completion function along to try-completion and all-completions, which will then let your function do all the work.

The completion function should accept three arguments:

The string to be completed.
The predicate function to filter possible matches, or nil if none. Your function should call the predicate for each possible match, and ignore the possible match if the predicate returns nil.
A flag specifying the type of operation.

There are three flag values for three operations:

nil specifies try-completion. The completion function should return the completion of the specified string, or t if the string is a unique and exact match already, or nil if the string matches no possibility. If the string is an exact match for one possibility, but also matches other longer possibilities, the function should return the string, not t.
t specifies all-completions. The completion function should return a list of all possible completions of the specified string.
lambda specifies a test for an exact match. The completion function should return t if the specified string is an exact match for some possibility; nil otherwise.

It would be consistent and clean for completion functions to allow lambda expressions (lists that are functions) as well as function symbols as collection, but this is impossible. Lists as completion tables are already assigned another meaning--as alists. It would be unreliable to fail to handle an alist normally because it is also a possible function. So you must arrange for any function you wish to use for completion to be encapsulated in a symbol.

Emacs uses programmed completion when completing file names. See section File Name Completion.

Yes-or-No Queries

This section describes functions used to ask the user a yes-or-no question. The function y-or-n-p can be answered with a single character; it is useful for questions where an inadvertent wrong answer will not have serious consequences. yes-or-no-p is suitable for more momentous questions, since it requires three or four characters to answer.

If either of these functions is called in a command that was invoked using the mouse--more precisely, if last-nonmenu-event (see section Information from the Command Loop) is either nil or a list--then it uses a dialog box or pop-up menu to ask the question. Otherwise, it uses keyboard input. You can force use of the mouse or use of keyboard input by binding last-nonmenu-event to a suitable value around the call.

Strictly speaking, yes-or-no-p uses the minibuffer and y-or-n-p does not; but it seems best to describe them together.

Function: y-or-n-p prompt
This function asks the user a question, expecting input in the echo area. It returns t if the user types y, nil if the user types n. This function also accepts SPC to mean yes and DEL to mean no. It accepts C-] to mean "quit", like C-g, because the question might look like a minibuffer and for that reason the user might try to use C-] to get out. The answer is a single character, with no RET needed to terminate it. Upper and lower case are equivalent.

"Asking the question" means printing prompt in the echo area, followed by the string `(y or n) '. If the input is not one of the expected answers (y, n, SPC, DEL, or something that quits), the function responds `Please answer y or n.', and repeats the request.

This function does not actually use the minibuffer, since it does not allow editing of the answer. It actually uses the echo area (see section The Echo Area), which uses the same screen space as the minibuffer. The cursor moves to the echo area while the question is being asked.

The answers and their meanings, even `y' and `n', are not hardwired. The keymap query-replace-map specifies them. See section Search and Replace.

In the following example, the user first types q, which is invalid. At the next prompt the user types y.
(y-or-n-p "Do you need a lift? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears in the echo area:

---------- Echo area ----------
Do you need a lift? (y or n)
---------- Echo area ----------

;; If the user then types q, the following appears:

---------- Echo area ----------
Please answer y or n.  Do you need a lift? (y or n)
---------- Echo area ----------

;; When the user types a valid answer,
;;   it is displayed after the question:

---------- Echo area ----------
Do you need a lift? (y or n) y
---------- Echo area ----------
We show successive lines of echo area messages, but only one actually appears on the screen at a time.

Function: y-or-n-p-with-timeout prompt seconds default-value
Like y-or-n-p, except that if the user fails to answer within seconds seconds, this function stops waiting and returns default-value. It works by setting up a timer; see section Timers for Delayed Execution. The argument seconds may be an integer or a floating point number.

Function: yes-or-no-p prompt
This function asks the user a question, expecting input in the minibuffer. It returns t if the user enters `yes', nil if the user types `no'. The user must type RET to finalize the response. Upper and lower case are equivalent.

yes-or-no-p starts by displaying prompt in the echo area, followed by `(yes or no) '. The user must type one of the expected responses; otherwise, the function responds `Please answer yes or no.', waits about two seconds and repeats the request.

yes-or-no-p requires more work from the user than y-or-n-p and is appropriate for more crucial decisions.

Here is an example:
(yes-or-no-p "Do you really want to remove everything? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears,
;;   with an empty minibuffer:

---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
If the user first types y RET, which is invalid because this function demands the entire word `yes', it responds by displaying these prompts, with a brief pause between them:
---------- Buffer: minibuffer ----------
Please answer yes or no.
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
Asking Multiple Y-or-N Questions

When you have a series of similar questions to ask, such as "Do you want to save this buffer" for each buffer in turn, you should use map-y-or-n-p to ask the collection of questions, rather than asking each question individually. This gives the user certain convenient facilities such as the ability to answer the whole series at once.

Function: map-y-or-n-p prompter actor list &optional help action-alist
This function asks the user a series of questions, reading a single-character answer in the echo area for each one.

The value of list specifies the objects to ask questions about. It should be either a list of objects or a generator function. If it is a function, it should expect no arguments, and should return either the next object to ask about, or nil meaning stop asking questions.

The argument prompter specifies how to ask each question. If prompter is a string, the question text is computed like this:
(format prompter object)
where object is the next object to ask about (as obtained from list).

If not a string, prompter should be a function of one argument (the next object to ask about) and should return the question text. If the value is a string, that is the question to ask the user. The function can also return t meaning do act on this object (and don't ask the user), or nil meaning ignore this object (and don't ask the user).

The argument actor says how to act on the answers that the user gives. It should be a function of one argument, and it is called with each object that the user says yes for. Its argument is always an object obtained from list.

If the argument help is given, it should be a list of this form:
(singular plural action)
where singular is a string containing a singular noun that describes the objects conceptually being acted on, plural is the corresponding plural noun, and action is a transitive verb describing what actor does.

If you don't specify help, the default is ("object" "objects" "act on").

Each time a question is asked, the user may enter y, Y, or SPC to act on that object; n, N, or DEL to skip that object; ! to act on all following objects; ESC or q to exit (skip all following objects); . (period) to act on the current object and then exit; or C-h to get help. These are the same answers that query-replace accepts. The keymap query-replace-map defines their meaning for map-y-or-n-p as well as for query-replace; see section Search and Replace.

You can use action-alist to specify additional possible answers and what they mean. It is an alist of elements of the form (char function help), each of which defines one additional answer. In this element, char is a character (the answer); function is a function of one argument (an object from list); help is a string.

When the user responds with char, map-y-or-n-p calls function. If it returns non-nil, the object is considered "acted upon", and map-y-or-n-p advances to the next object in list. If it returns nil, the prompt is repeated for the same object.

If map-y-or-n-p is called in a command that was invoked using the mouse--more precisely, if last-nonmenu-event (see section Information from the Command Loop) is either nil or a list--then it uses a dialog box or pop-up menu to ask the question. In this case, it does not use keyboard input or the echo area. You can force use of the mouse or use of keyboard input by binding last-nonmenu-event to a suitable value around the call.

The return value of map-y-or-n-p is the number of objects acted on.

Reading a Password

To read a password to pass to another program, you can use the function read-passwd.

Function: read-passwd prompt &optional confirm default
This function reads a password, prompting with prompt. It does not echo the password as the user types it; instead, it echoes `.' for each character in the password.

The optional argument confirm, if non-nil, says to read the password twice and insist it must be the same both times. If it isn't the same, the user has to type it over and over until the last two times match.

The optional argument default specifies the default password to return if the user enters empty input. If default is nil, then read-passwd returns the null string in that case.

Minibuffer Miscellany

This section describes some basic functions and variables related to minibuffers.

Command: exit-minibuffer
This command exits the active minibuffer. It is normally bound to keys in minibuffer local keymaps.

Command: self-insert-and-exit
This command exits the active minibuffer after inserting the last character typed on the keyboard (found in last-command-char; see section Information from the Command Loop).

Command: previous-history-element n
This command replaces the minibuffer contents with the value of the nth previous (older) history element.

Command: next-history-element n
This command replaces the minibuffer contents with the value of the nth more recent history element.

Command: previous-matching-history-element pattern
This command replaces the minibuffer contents with the value of the previous (older) history element that matches pattern (a regular expression).

Command: next-matching-history-element pattern
This command replaces the minibuffer contents with the value of the next (newer) history element that matches pattern (a regular expression).

Function: minibuffer-prompt
This function returns the prompt string of the currently active minibuffer. If no minibuffer is active, it returns nil.

Function: minibuffer-prompt-width
This function returns the display width of the prompt string of the currently active minibuffer. If no minibuffer is active, it returns 0.

Variable: minibuffer-setup-hook
This is a normal hook that is run whenever the minibuffer is entered. See section Hooks.

Variable: minibuffer-exit-hook
This is a normal hook that is run whenever the minibuffer is exited. See section Hooks.

Variable: minibuffer-help-form
The current value of this variable is used to rebind help-form locally inside the minibuffer (see section Help Functions).

Function: active-minibuffer-window
This function returns the currently active minibuffer window, or nil if none is currently active.

Function: minibuffer-window &optional frame
This function returns the minibuffer window used for frame frame. If frame is nil, that stands for the current frame. Note that the minibuffer window used by a frame need not be part of that frame--a frame that has no minibuffer of its own necessarily uses some other frame's minibuffer window.

Function: window-minibuffer-p window
This function returns non-nil if window is a minibuffer window.

It is not correct to determine whether a given window is a minibuffer by comparing it with the result of (minibuffer-window), because there can be more than one minibuffer window if there is more than one frame.

Function: minibuffer-window-active-p window
This function returns non-nil if window, assumed to be a minibuffer window, is currently active.

Variable: minibuffer-scroll-window
If the value of this variable is non-nil, it should be a window object. When the function scroll-other-window is called in the minibuffer, it scrolls this window.

Finally, some functions and variables deal with recursive minibuffers (see section Recursive Editing):

Function: minibuffer-depth
This function returns the current depth of activations of the minibuffer, a nonnegative integer. If no minibuffers are active, it returns zero.

User Option: enable-recursive-minibuffers
If this variable is non-nil, you can invoke commands (such as find-file) that use minibuffers even while the minibuffer window is active. Such invocation produces a recursive editing level for a new minibuffer. The outer-level minibuffer is invisible while you are editing the inner one.

If this variable is nil, you cannot invoke minibuffer commands when the minibuffer window is active, not even if you switch to another window to do it.

If a command name has a property enable-recursive-minibuffers that is non-nil, then the command can use the minibuffer to read arguments even if it is invoked from the minibuffer. The minibuffer command next-matching-history-element (normally M-s in the minibuffer) uses this feature.
Command Loop

When you run Emacs, it enters the editor command loop almost immediately. This loop reads key sequences, executes their definitions, and displays the results. In this chapter, we describe how these things are done, and the subroutines that allow Lisp programs to do them.

Command Loop Overview

The first thing the command loop must do is read a key sequence, which is a sequence of events that translates into a command. It does this by calling the function read-key-sequence. Your Lisp code can also call this function (see section Key Sequence Input). Lisp programs can also do input at a lower level with read-event (see section Reading One Event) or discard pending input with discard-input (see section Miscellaneous Event Input Features).

The key sequence is translated into a command through the currently active keymaps. See section Key Lookup, for information on how this is done. The result should be a keyboard macro or an interactively callable function. If the key is M-x, then it reads the name of another command, which it then calls. This is done by the command execute-extended-command (see section Interactive Call).

To execute a command requires first reading the arguments for it. This is done by calling command-execute (see section Interactive Call). For commands written in Lisp, the interactive specification says how to read the arguments. This may use the prefix argument (see section Prefix Command Arguments) or may read with prompting in the minibuffer (see section Minibuffers). For example, the command find-file has an interactive specification which says to read a file name using the minibuffer. The command's function body does not use the minibuffer; if you call this command from Lisp code as a function, you must supply the file name string as an ordinary Lisp function argument.

If the command is a string or vector (i.e., a keyboard macro) then execute-kbd-macro is used to execute it. You can call this function yourself (see section Keyboard Macros).

To terminate the execution of a running command, type C-g. This character causes quitting (see section Quitting).

Variable: pre-command-hook
The editor command loop runs this normal hook before each command. At that time, this-command contains the command that is about to run, and last-command describes the previous command. See section Hooks.

Variable: post-command-hook
The editor command loop runs this normal hook after each command (including commands terminated prematurely by quitting or by errors), and also when the command loop is first entered. At that time, this-command describes the command that just ran, and last-command describes the command before that. See section Hooks.

Quitting is suppressed while running pre-command-hook and post-command-hook. If an error happens while executing one of these hooks, it terminates execution of the hook, and clears the hook variable to nil so as to prevent an infinite loop of errors.

Defining Commands

A Lisp function becomes a command when its body contains, at top level, a form that calls the special form interactive. This form does nothing when actually executed, but its presence serves as a flag to indicate that interactive calling is permitted. Its argument controls the reading of arguments for an interactive call.

Using interactive

This section describes how to write the interactive form that makes a Lisp function an interactively-callable command.

Special Form: interactive arg-descriptor
This special form declares that the function in which it appears is a command, and that it may therefore be called interactively (via M-x or by entering a key sequence bound to it). The argument arg-descriptor declares how to compute the arguments to the command when the command is called interactively.

A command may be called from Lisp programs like any other function, but then the caller supplies the arguments and arg-descriptor has no effect.

The interactive form has its effect because the command loop (actually, its subroutine call-interactively) scans through the function definition looking for it, before calling the function. Once the function is called, all its body forms including the interactive form are executed, but at this time interactive simply returns nil without even evaluating its argument.

There are three possibilities for the argument arg-descriptor:

It may be omitted or nil; then the command is called with no arguments. This leads quickly to an error if the command requires one or more arguments.
It may be a Lisp expression that is not a string; then it should be a form that is evaluated to get a list of arguments to pass to the command. If this expression reads keyboard input (this includes using the minibuffer), keep in mind that the integer value of point or the mark before reading input may be incorrect after reading input. This is because the current buffer may be receiving subprocess output; if subprocess output arrives while the command is waiting for input, it could relocate point and the mark. Here's an example of what not to do:
(interactive
 (list (region-beginning) (region-end)
       (read-string "Foo: " nil 'my-history)))
Here's how to avoid the problem, by examining point and the mark only after reading the keyboard input:
(interactive
 (let ((string (read-string "Foo: " nil 'my-history)))
   (list (region-beginning) (region-end) string)))
It may be a string; then its contents should consist of a code character followed by a prompt (which some code characters use and some ignore). The prompt ends either with the end of the string or with a newline. Here is a simple example:
(interactive "bFrobnicate buffer: ")
The code letter `b' says to read the name of an existing buffer, with completion. The buffer name is the sole argument passed to the command. The rest of the string is a prompt. If there is a newline character in the string, it terminates the prompt. If the string does not end there, then the rest of the string should contain another code character and prompt, specifying another argument. You can specify any number of arguments in this way. The prompt string can use `%' to include previous argument values (starting with the first argument) in the prompt. This is done using format (see section Formatting Strings). For example, here is how you could read the name of an existing buffer followed by a new name to give to that buffer:
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
If the first character in the string is `*', then an error is signaled if the buffer is read-only. If the first character in the string is `@', and if the key sequence used to invoke the command includes any mouse events, then the window associated with the first of those events is selected before the command is run. You can use `*' and `@' together; the order does not matter. Actual reading of arguments is controlled by the rest of the prompt string (starting with the first character that is not `*' or `@').

Code Characters for interactive

The code character descriptions below contain a number of key words, defined here as follows:

Completion
Provide completion. TAB, SPC, and RET perform name completion because the argument is read using completing-read (see section Completion). ? displays a list of possible completions.
Existing
Require the name of an existing object. An invalid name is not accepted; the commands to exit the minibuffer do not exit if the current input is not valid.
Default
A default value of some sort is used if the user enters no text in the minibuffer. The default depends on the code character.
No I/O
This code letter computes an argument without reading any input. Therefore, it does not use a prompt string, and any prompt string you supply is ignored. Even though the code letter doesn't use a prompt string, you must follow it with a newline if it is not the last code character in the string.
Prompt
A prompt immediately follows the code character. The prompt ends either with the end of the string or with a newline.
Special
This code character is meaningful only at the beginning of the interactive string, and it does not look for a prompt or a newline. It is a single, isolated character.
Here are the code character descriptions for use with interactive:

`*'
Signal an error if the current buffer is read-only. Special.
`@'
Select the window mentioned in the first mouse event in the key sequence that invoked this command. Special.
`a'
A function name (i.e., a symbol satisfying fboundp). Existing, Completion, Prompt.
`b'
The name of an existing buffer. By default, uses the name of the current buffer (see section Buffers). Existing, Completion, Default, Prompt.
`B'
A buffer name. The buffer need not exist. By default, uses the name of a recently used buffer other than the current buffer. Completion, Default, Prompt.
`c'
A character. The cursor does not move into the echo area. Prompt.
`C'
A command name (i.e., a symbol satisfying commandp). Existing, Completion, Prompt.
`d'
The position of point, as an integer (see section Point). No I/O.
`D'
A directory name. The default is the current default directory of the current buffer, default-directory (see section Operating System Environment). Existing, Completion, Default, Prompt.
`e'
The first or next mouse event in the key sequence that invoked the command. More precisely, `e' gets events that are lists, so you can look at the data in the lists. See section Input Events. No I/O. You can use `e' more than once in a single command's interactive specification. If the key sequence that invoked the command has n events that are lists, the nth `e' provides the nth such event. Events that are not lists, such as function keys and ASCII characters, do not count where `e' is concerned.
`f'
A file name of an existing file (see section File Names). The default directory is default-directory. Existing, Completion, Default, Prompt.
`F'
A file name. The file need not exist. Completion, Default, Prompt.
`i'
An irrelevant argument. This code always supplies nil as the argument's value. No I/O.
`k'
A key sequence (see section Keymap Terminology). This keeps reading events until a command (or undefined command) is found in the current key maps. The key sequence argument is represented as a string or vector. The cursor does not move into the echo area. Prompt. This kind of input is used by commands such as describe-key and global-set-key.
`K'
A key sequence, whose definition you intend to change. This works like `k', except that it suppresses, for the last input event in the key sequence, the conversions that are normally used (when necessary) to convert an undefined key into a defined one.
`m'
The position of the mark, as an integer. No I/O.
`M'
Arbitrary text, read in the minibuffer using the current buffer's input method, and returned as a string (see section `Input Methods' in The GNU Emacs Manual). Prompt.
`n'
A number read with the minibuffer. If the input is not a number, the user is asked to try again. The prefix argument, if any, is not used. Prompt.
`N'
The numeric prefix argument; but if there is no prefix argument, read a number as with n. Requires a number. See section Prefix Command Arguments. Prompt.
`p'
The numeric prefix argument. (Note that this `p' is lower case.) No I/O.
`P'
The raw prefix argument. (Note that this `P' is upper case.) No I/O.
`r'
Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one. No I/O.
`s'
Arbitrary text, read in the minibuffer and returned as a string (see section Reading Text Strings with the Minibuffer). Terminate the input with either C-j or RET. (C-q may be used to include either of these characters in the input.) Prompt.
`S'
An interned symbol whose name is read in the minibuffer. Any whitespace character terminates the input. (Use C-q to include whitespace in the string.) Other characters that normally terminate a symbol (e.g., parentheses and brackets) do not do so here. Prompt.
`v'
A variable declared to be a user option (i.e., satisfying the predicate user-variable-p). See section High-Level Completion Functions. Existing, Completion, Prompt.
`x'
A Lisp object, specified with its read syntax, terminated with a C-j or RET. The object is not evaluated. See section Reading Lisp Objects with the Minibuffer. Prompt.
`X'
A Lisp form is read as with x, but then evaluated so that its value becomes the argument for the command. Prompt.
`z'
A coding system name (a symbol). If the user enters null input, the argument value is nil. See section Coding Systems. Completion, Existing, Prompt.
`Z'
A coding system name (a symbol)---but only if this command has a prefix argument. With no prefix argument, `Z' provides nil as the argument value. Completion, Existing, Prompt.
Examples of Using interactive

Here are some examples of interactive:
(defun foo1 ()              ; foo1 takes no arguments,
    (interactive)           ;   just moves forward two words.
    (forward-word 2))
     => foo1

(defun foo2 (n)             ; foo2 takes one argument,
    (interactive "p")       ;   which is the numeric prefix.
    (forward-word (* 2 n)))
     => foo2

(defun foo3 (n)             ; foo3 takes one argument,
    (interactive "nCount:") ;   which is read with the Minibuffer.
    (forward-word (* 2 n)))
     => foo3

(defun three-b (b1 b2 b3)
  "Select three existing buffers.
Put them into three windows, selecting the last one."
    (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
    (delete-other-windows)
    (split-window (selected-window) 8)
    (switch-to-buffer b1)
    (other-window 1)
    (split-window (selected-window) 8)
    (switch-to-buffer b2)
    (other-window 1)
    (switch-to-buffer b3))
     => three-b
(three-b "*scratch*" "declarations.texi" "*mail*")
     => nil
Interactive Call

After the command loop has translated a key sequence into a command it invokes that command using the function command-execute. If the command is a function, command-execute calls call-interactively, which reads the arguments and calls the command. You can also call these functions yourself.

Function: commandp object
Returns t if object is suitable for calling interactively; that is, if object is a command. Otherwise, returns nil.

The interactively callable objects include strings and vectors (treated as keyboard macros), lambda expressions that contain a top-level call to interactive, byte-code function objects made from such lambda expressions, autoload objects that are declared as interactive (non-nil fourth argument to autoload), and some of the primitive functions.

A symbol satisfies commandp if its function definition satisfies commandp.

Keys and keymaps are not commands. Rather, they are used to look up commands (see section Keymaps).

See documentation in section Access to Documentation Strings, for a realistic example of using commandp.

Function: call-interactively command &optional record-flag keys
This function calls the interactively callable function command, reading arguments according to its interactive calling specifications. An error is signaled if command is not a function or if it cannot be called interactively (i.e., is not a command). Note that keyboard macros (strings and vectors) are not accepted, even though they are considered commands, because they are not functions.

If record-flag is non-nil, then this command and its arguments are unconditionally added to the list command-history. Otherwise, the command is added only if it uses the minibuffer to read an argument. See section Command History.

The argument keys, if given, specifies the sequence of events to supply if the command inquires which events were used to invoke it.

Function: command-execute command &optional record-flag keys
This function executes command. The argument command must satisfy the commandp predicate; i.e., it must be an interactively callable function or a keyboard macro.

A string or vector as command is executed with execute-kbd-macro. A function is passed to call-interactively, along with the optional record-flag.

A symbol is handled by using its function definition in its place. A symbol with an autoload definition counts as a command if it was declared to stand for an interactively callable function. Such a definition is handled by loading the specified library and then rechecking the definition of the symbol.

The argument keys, if given, specifies the sequence of events to supply if the command inquires which events were used to invoke it.

Command: execute-extended-command prefix-argument
This function reads a command name from the minibuffer using completing-read (see section Completion). Then it uses command-execute to call the specified command. Whatever that command returns becomes the value of execute-extended-command.

If the command asks for a prefix argument, it receives the value prefix-argument. If execute-extended-command is called interactively, the current raw prefix argument is used for prefix-argument, and thus passed on to whatever command is run.

execute-extended-command is the normal definition of M-x, so it uses the string `M-x ' as a prompt. (It would be better to take the prompt from the events used to invoke execute-extended-command, but that is painful to implement.) A description of the value of the prefix argument, if any, also becomes part of the prompt.
(execute-extended-command 1)
---------- Buffer: Minibuffer ----------
1 M-x forward-word RET
---------- Buffer: Minibuffer ----------
     => t
Function: interactive-p
This function returns t if the containing function (the one whose code includes the call to interactive-p) was called interactively, with the function call-interactively. (It makes no difference whether call-interactively was called from Lisp or directly from the editor command loop.) If the containing function was called by Lisp evaluation (or with apply or funcall), then it was not called interactively.

The most common use of interactive-p is for deciding whether to print an informative message. As a special exception, interactive-p returns nil whenever a keyboard macro is being run. This is to suppress the informative messages and speed execution of the macro.

For example:
(defun foo ()
  (interactive)
  (when (interactive-p)
    (message "foo")))
     => foo

(defun bar ()
  (interactive)
  (setq foobar (list (foo) (interactive-p))))
     => bar

;; Type M-x foo.
     -| foo

;; Type M-x bar.
;; This does not print anything.

foobar
     => (nil t)
The other way to do this sort of job is to make the command take an argument print-message which should be non-nil in an interactive call, and use the interactive spec to make sure it is non-nil. Here's how:
(defun foo (&optional print-message)
  (interactive "p")
  (when print-message
    (message "foo")))
The numeric prefix argument, provided by `p', is never nil.

Information from the Command Loop

The editor command loop sets several Lisp variables to keep status records for itself and for commands that are run.

Variable: last-command
This variable records the name of the previous command executed by the command loop (the one before the current command). Normally the value is a symbol with a function definition, but this is not guaranteed.

The value is copied from this-command when a command returns to the command loop, except when the command has specified a prefix argument for the following command.

This variable is always local to the current terminal and cannot be buffer-local. See section Multiple Displays.

Variable: real-last-command
This variable is set up by Emacs just like last-command, but never altered by Lisp programs.

Variable: this-command
This variable records the name of the command now being executed by the editor command loop. Like last-command, it is normally a symbol with a function definition.

The command loop sets this variable just before running a command, and copies its value into last-command when the command finishes (unless the command specified a prefix argument for the following command).

Some commands set this variable during their execution, as a flag for whatever command runs next. In particular, the functions for killing text set this-command to kill-region so that any kill commands immediately following will know to append the killed text to the previous kill.

If you do not want a particular command to be recognized as the previous command in the case where it got an error, you must code that command to prevent this. One way is to set this-command to t at the beginning of the command, and set this-command back to its proper value at the end, like this:
(defun foo (args...)
  (interactive ...)
  (let ((old-this-command this-command))
    (setq this-command t)
    ...do the work...
    (setq this-command old-this-command)))
We do not bind this-command with let because that would restore the old value in case of error--a feature of let which in this case does precisely what we want to avoid.

Function: this-command-keys
This function returns a string or vector containing the key sequence that invoked the present command, plus any previous commands that generated the prefix argument for this command. The value is a string if all those events were characters. See section Input Events.
(this-command-keys)
;; Now use C-u C-x C-e to evaluate that.
     => "^U^X^E"
Function: this-command-keys-vector
Like this-command-keys, except that it always returns the events in a vector, so you do never need to deal with the complexities of storing input events in a string (see section Putting Keyboard Events in Strings).

Variable: last-nonmenu-event
This variable holds the last input event read as part of a key sequence, not counting events resulting from mouse menus.

One use of this variable is for telling x-popup-menu where to pop up a menu. It is also used internally by y-or-n-p (see section Yes-or-No Queries).

Variable: last-command-event

Variable: last-command-char
This variable is set to the last input event that was read by the command loop as part of a command. The principal use of this variable is in self-insert-command, which uses it to decide which character to insert.
last-command-event
;; Now use C-u C-x C-e to evaluate that.
     => 5
The value is 5 because that is the ASCII code for C-e.

The alias last-command-char exists for compatibility with Emacs version 18.

Variable: last-event-frame
This variable records which frame the last input event was directed to. Usually this is the frame that was selected when the event was generated, but if that frame has redirected input focus to another frame, the value is the frame to which the event was redirected. See section Input Focus.

Input Events

The Emacs command loop reads a sequence of input events that represent keyboard or mouse activity. The events for keyboard activity are characters or symbols; mouse events are always lists. This section describes the representation and meaning of input events in detail.

Function: eventp object
This function returns non-nil if object is an input event or event type.

Note that any symbol might be used as an event or an event type. eventp cannot distinguish whether a symbol is intended by Lisp code to be used as an event. Instead, it distinguishes whether the symbol has actually been used in an event that has been read as input in the current Emacs session. If a symbol has not yet been so used, eventp returns nil.

Keyboard Events

There are two kinds of input you can get from the keyboard: ordinary keys, and function keys. Ordinary keys correspond to characters; the events they generate are represented in Lisp as characters. The event type of a character event is the character itself (an integer); see section Classifying Events.

An input character event consists of a basic code between 0 and 524287, plus any or all of these modifier bits:

meta
The bit in the character code indicates a character typed with the meta key held down.
control
The bit in the character code indicates a non-ASCII control character. ASCII control characters such as C-a have special basic codes of their own, so Emacs needs no special bit to indicate them. Thus, the code for C-a is just 1. But if you type a control combination not in ASCII, such as % with the control key, the numeric value you get is the code for % plus (assuming the terminal supports non-ASCII control characters).
shift
The bit in the character code indicates an ASCII control character typed with the shift key held down. For letters, the basic code itself indicates upper versus lower case; for digits and punctuation, the shift key selects an entirely different character with a different basic code. In order to keep within the ASCII character set whenever possible, Emacs avoids using the bit for those characters. However, ASCII provides no way to distinguish C-A from C-a, so Emacs uses the bit in C-A and not in C-a.
hyper
The bit in the character code indicates a character typed with the hyper key held down.
super
The bit in the character code indicates a character typed with the super key held down.
alt
The bit in the character code indicates a character typed with the alt key held down. (On some terminals, the key labeled ALT is actually the meta key.)
It is best to avoid mentioning specific bit numbers in your program. To test the modifier bits of a character, use the function event-modifiers (see section Classifying Events). When making key bindings, you can use the read syntax for characters with modifier bits (`\C-', `\M-', and so on). For making key bindings with define-key, you can use lists such as (control hyper ?x) to specify the characters (see section Changing Key Bindings). The function event-convert-list converts such a list into an event type (see section Classifying Events).

Function Keys

Most keyboards also have function keys---keys that have names or symbols that are not characters. Function keys are represented in Emacs Lisp as symbols; the symbol's name is the function key's label, in lower case. For example, pressing a key labeled F1 places the symbol f1 in the input stream.

The event type of a function key event is the event symbol itself. See section Classifying Events.

Here are a few special cases in the symbol-naming convention for function keys:

backspace, tab, newline, return, delete
These keys correspond to common ASCII control characters that have special keys on most keyboards. In ASCII, C-i and TAB are the same character. If the terminal can distinguish between them, Emacs conveys the distinction to Lisp programs by representing the former as the integer 9, and the latter as the symbol tab. Most of the time, it's not useful to distinguish the two. So normally function-key-map (see section Translating Input Events) is set up to map tab into 9. Thus, a key binding for character code 9 (the character C-i) also applies to tab. Likewise for the other symbols in this group. The function read-char likewise converts these events into characters. In ASCII, BS is really C-h. But backspace converts into the character code 127 (DEL), not into code 8 (BS). This is what most users prefer.
left, up, right, down
Cursor arrow keys
kp-add, kp-decimal, kp-divide, ...
Keypad keys (to the right of the regular keyboard).
kp-0, kp-1, ...
Keypad keys with digits.
kp-f1, kp-f2, kp-f3, kp-f4
Keypad PF keys.
kp-home, kp-left, kp-up, kp-right, kp-down
Keypad arrow keys. Emacs normally translates these into the corresponding non-keypad keys home, left, ...
kp-prior, kp-next, kp-end, kp-begin, kp-insert, kp-delete
Additional keypad duplicates of keys ordinarily found elsewhere. Emacs normally translates these into the like-named non-keypad keys.
You can use the modifier keys ALT, CTRL, HYPER, META, SHIFT, and SUPER with function keys. The way to represent them is with prefixes in the symbol name:

`A-'
The alt modifier.
`C-'
The control modifier.
`H-'
The hyper modifier.
`M-'
The meta modifier.
`S-'
The shift modifier.
`s-'
The super modifier.
Thus, the symbol for the key F3 with META held down is M-f3. When you use more than one prefix, we recommend you write them in alphabetical order; but the order does not matter in arguments to the key-binding lookup and modification functions.

Mouse Events

Emacs supports four kinds of mouse events: click events, drag events, button-down events, and motion events. All mouse events are represented as lists. The CAR of the list is the event type; this says which mouse button was involved, and which modifier keys were used with it. The event type can also distinguish double or triple button presses (see section Repeat Events). The rest of the list elements give position and time information.

For key lookup, only the event type matters: two events of the same type necessarily run the same command. The command can access the full values of these events using the `e' interactive code. See section Code Characters for interactive.

A key sequence that starts with a mouse event is read using the keymaps of the buffer in the window that the mouse was in, not the current buffer. This does not imply that clicking in a window selects that window or its buffer--that is entirely under the control of the command binding of the key sequence.

Click Events

When the user presses a mouse button and releases it at the same location, that generates a click event. Mouse click events have this form:
(event-type
 (window buffer-pos (x . y) timestamp)
 click-count)
Here is what the elements normally mean:

event-type
This is a symbol that indicates which mouse button was used. It is one of the symbols mouse-1, mouse-2, ..., where the buttons are numbered left to right. You can also use prefixes `A-', `C-', `H-', `M-', `S-' and `s-' for modifiers alt, control, hyper, meta, shift and super, just as you would with function keys. This symbol also serves as the event type of the event. Key bindings describe events by their types; thus, if there is a key binding for mouse-1, that binding would apply to all events whose event-type is mouse-1.
window
This is the window in which the click occurred.
x, y
These are the pixel-denominated coordinates of the click, relative to the top left corner of window, which is (0 . 0).
buffer-pos
This is the buffer position of the character clicked on.
timestamp
This is the time at which the event occurred, in milliseconds. (Since this value wraps around the entire range of Emacs Lisp integers in about five hours, it is useful only for relating the times of nearby events.)
click-count
This is the number of rapid repeated presses so far of the same mouse button. See section Repeat Events.
The meanings of buffer-pos, x and y are somewhat different when the event location is in a special part of the screen, such as the mode line or a scroll bar.

If the location is in a scroll bar, then buffer-pos is the symbol vertical-scroll-bar or horizontal-scroll-bar, and the pair (x . y) is replaced with a pair (portion . whole), where portion is the distance of the click from the top or left end of the scroll bar, and whole is the length of the entire scroll bar.

If the position is on a mode line or the vertical line separating window from its neighbor to the right, then buffer-pos is the symbol mode-line or vertical-line. For the mode line, y does not have meaningful data. For the vertical line, x does not have meaningful data.

In one special case, buffer-pos is a list containing a symbol (one of the symbols listed above) instead of just the symbol. This happens after the imaginary prefix keys for the event are inserted into the input stream. See section Key Sequence Input.

Drag Events

With Emacs, you can have a drag event without even changing your clothes. A drag event happens every time the user presses a mouse button and then moves the mouse to a different character position before releasing the button. Like all mouse events, drag events are represented in Lisp as lists. The lists record both the starting mouse position and the final position, like this:
(event-type
 (window1 buffer-pos1 (x1 . y1) timestamp1)
 (window2 buffer-pos2 (x2 . y2) timestamp2)
 click-count)
For a drag event, the name of the symbol event-type contains the prefix `drag-'. For example, dragging the mouse with button 2 held down generates a drag-mouse-2 event. The second and third elements of the event give the starting and ending position of the drag. Aside from that, the data have the same meanings as in a click event (see section Click Events). You can access the second element of any mouse event in the same way, with no need to distinguish drag events from others.

The `drag-' prefix follows the modifier key prefixes such as `C-' and `M-'.

If read-key-sequence receives a drag event that has no key binding, and the corresponding click event does have a binding, it changes the drag event into a click event at the drag's starting position. This means that you don't have to distinguish between click and drag events unless you want to.

Button-Down Events

Click and drag events happen when the user releases a mouse button. They cannot happen earlier, because there is no way to distinguish a click from a drag until the button is released.

If you want to take action as soon as a button is pressed, you need to handle button-down events.(3) These occur as soon as a button is pressed. They are represented by lists that look exactly like click events (see section Click Events), except that the event-type symbol name contains the prefix `down-'. The `down-' prefix follows modifier key prefixes such as `C-' and `M-'.

The function read-key-sequence ignores any button-down events that don't have command bindings; therefore, the Emacs command loop ignores them too. This means that you need not worry about defining button-down events unless you want them to do something. The usual reason to define a button-down event is so that you can track mouse motion (by reading motion events) until the button is released. See section Motion Events.

Repeat Events

If you press the same mouse button more than once in quick succession without moving the mouse, Emacs generates special repeat mouse events for the second and subsequent presses.

The most common repeat events are double-click events. Emacs generates a double-click event when you click a button twice; the event happens when you release the button (as is normal for all click events).

The event type of a double-click event contains the prefix `double-'. Thus, a double click on the second mouse button with meta held down comes to the Lisp program as M-double-mouse-2. If a double-click event has no binding, the binding of the corresponding ordinary click event is used to execute it. Thus, you need not pay attention to the double click feature unless you really want to.

When the user performs a double click, Emacs generates first an ordinary click event, and then a double-click event. Therefore, you must design the command binding of the double click event to assume that the single-click command has already run. It must produce the desired results of a double click, starting from the results of a single click.

This is convenient, if the meaning of a double click somehow "builds on" the meaning of a single click--which is recommended user interface design practice for double clicks.

If you click a button, then press it down again and start moving the mouse with the button held down, then you get a double-drag event when you ultimately release the button. Its event type contains `double-drag' instead of just `drag'. If a double-drag event has no binding, Emacs looks for an alternate binding as if the event were an ordinary drag.

Before the double-click or double-drag event, Emacs generates a double-down event when the user presses the button down for the second time. Its event type contains `double-down' instead of just `down'. If a double-down event has no binding, Emacs looks for an alternate binding as if the event were an ordinary button-down event. If it finds no binding that way either, the double-down event is ignored.

To summarize, when you click a button and then press it again right away, Emacs generates a down event and a click event for the first click, a double-down event when you press the button again, and finally either a double-click or a double-drag event.

If you click a button twice and then press it again, all in quick succession, Emacs generates a triple-down event, followed by either a triple-click or a triple-drag. The event types of these events contain `triple' instead of `double'. If any triple event has no binding, Emacs uses the binding that it would use for the corresponding double event.

If you click a button three or more times and then press it again, the events for the presses beyond the third are all triple events. Emacs does not have separate event types for quadruple, quintuple, etc. events. However, you can look at the event list to find out precisely how many times the button was pressed.

Function: event-click-count event
This function returns the number of consecutive button presses that led up to event. If event is a double-down, double-click or double-drag event, the value is 2. If event is a triple event, the value is 3 or greater. If event is an ordinary mouse event (not a repeat event), the value is 1.

Variable: double-click-time
To generate repeat events, successive mouse button presses must be at the same screen position, and the number of milliseconds between successive button presses must be less than the value of double-click-time. Setting double-click-time to nil disables multi-click detection entirely. Setting it to t removes the time limit; Emacs then detects multi-clicks by position only.

Motion Events

Emacs sometimes generates mouse motion events to describe motion of the mouse without any button activity. Mouse motion events are represented by lists that look like this:
(mouse-movement (window buffer-pos (x . y) timestamp))
The second element of the list describes the current position of the mouse, just as in a click event (see section Click Events).

The special form track-mouse enables generation of motion events within its body. Outside of track-mouse forms, Emacs does not generate events for mere motion of the mouse, and these events do not appear. See section Mouse Tracking.

Focus Events

Window systems provide general ways for the user to control which window gets keyboard input. This choice of window is called the focus. When the user does something to switch between Emacs frames, that generates a focus event. The normal definition of a focus event, in the global keymap, is to select a new frame within Emacs, as the user would expect. See section Input Focus.

Focus events are represented in Lisp as lists that look like this:
(switch-frame new-frame)
where new-frame is the frame switched to.

Most X window managers are set up so that just moving the mouse into a window is enough to set the focus there. Emacs appears to do this, because it changes the cursor to solid in the new frame. However, there is no need for the Lisp program to know about the focus change until some other kind of input arrives. So Emacs generates a focus event only when the user actually types a keyboard key or presses a mouse button in the new frame; just moving the mouse between frames does not generate a focus event.

A focus event in the middle of a key sequence would garble the sequence. So Emacs never generates a focus event in the middle of a key sequence. If the user changes focus in the middle of a key sequence--that is, after a prefix key--then Emacs reorders the events so that the focus event comes either before or after the multi-event key sequence, and not within it.

Miscellaneous Window System Events

A few other event types represent occurrences within the window system.

(delete-frame (frame))
This kind of event indicates that the user gave the window manager a command to delete a particular window, which happens to be an Emacs frame. The standard definition of the delete-frame event is to delete frame.
(iconify-frame (frame))
This kind of event indicates that the user iconified frame using the window manager. Its standard definition is ignore; since the frame has already been iconified, Emacs has no work to do. The purpose of this event type is so that you can keep track of such events if you want to.
(make-frame-visible (frame))
This kind of event indicates that the user deiconified frame using the window manager. Its standard definition is ignore; since the frame has already been made visible, Emacs has no work to do.
(mouse-wheel position delta)
This kind of event is generated by moving a wheel on a mouse (such as the MS Intellimouse). Its effect is typically a kind of scroll or zoom. The element delta describes the amount and direction of the wheel rotation. Its absolute value is the number of increments by which the wheel was rotated. A negative delta indicates that the wheel was rotated backwards, towards the user, and a positive delta indicates that the wheel was rotated forward, away from the user. The element position is a list describing the position of the event, in the same format as used in a mouse-click event. This kind of event is generated only on some kinds of systems.
(drag-n-drop position files)
This kind of event is generated when a group of files is selected in an application outside of Emacs, and then dragged and dropped onto an Emacs frame. The element position is a list describing the position of the event, in the same format as used in a mouse-click event, and files is the list of file names that were dragged and dropped. The usual way to handle this event is by visiting these files. This kind of event is generated, at present, only on some kinds of systems.
If one of these events arrives in the middle of a key sequence--that is, after a prefix key--then Emacs reorders the events so that this event comes either before or after the multi-event key sequence, not within it.

Event Examples

If the user presses and releases the left mouse button over the same location, that generates a sequence of events like this:
(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
(mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))
While holding the control key down, the user might hold down the second mouse button, and drag the mouse from one line to the next. That produces two events, as shown here:
(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
                (#<window 18 on NEWS> 3510 (0 . 28) -729648))
While holding down the meta and shift keys, the user might press the second mouse button on the window's mode line, and then drag the mouse into another window. That produces a pair of events like these:
(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
                  (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
                   -453816))
Classifying Events

Every event has an event type, which classifies the event for key binding purposes. For a keyboard event, the event type equals the event value; thus, the event type for a character is the character, and the event type for a function key symbol is the symbol itself. For events that are lists, the event type is the symbol in the CAR of the list. Thus, the event type is always a symbol or a character.

Two events of the same type are equivalent where key bindings are concerned; thus, they always run the same command. That does not necessarily mean they do the same things, however, as some commands look at the whole event to decide what to do. For example, some commands use the location of a mouse event to decide where in the buffer to act.

Sometimes broader classifications of events are useful. For example, you might want to ask whether an event involved the META key, regardless of which other key or mouse button was used.

The functions event-modifiers and event-basic-type are provided to get such information conveniently.

Function: event-modifiers event
This function returns a list of the modifiers that event has. The modifiers are symbols; they include shift, control, meta, alt, hyper and super. In addition, the modifiers list of a mouse event symbol always contains one of click, drag, and down.

The argument event may be an entire event object, or just an event type.

Here are some examples:
(event-modifiers ?a)
     => nil
(event-modifiers ?\C-a)
     => (control)
(event-modifiers ?\C-%)
     => (control)
(event-modifiers ?\C-\S-a)
     => (control shift)
(event-modifiers 'f5)
     => nil
(event-modifiers 's-f5)
     => (super)
(event-modifiers 'M-S-f5)
     => (meta shift)
(event-modifiers 'mouse-1)
     => (click)
(event-modifiers 'down-mouse-1)
     => (down)
The modifiers list for a click event explicitly contains click, but the event symbol name itself does not contain `click'.

Function: event-basic-type event
This function returns the key or mouse button that event describes, with all modifiers removed. For example:
(event-basic-type ?a)
     => 97
(event-basic-type ?A)
     => 97
(event-basic-type ?\C-a)
     => 97
(event-basic-type ?\C-\S-a)
     => 97
(event-basic-type 'f5)
     => f5
(event-basic-type 's-f5)
     => f5
(event-basic-type 'M-S-f5)
     => f5
(event-basic-type 'down-mouse-1)
     => mouse-1
Function: mouse-movement-p object
This function returns non-nil if object is a mouse movement event.

Function: event-convert-list list
This function converts a list of modifier names and a basic event type to an event type which specifies all of them. For example,
(event-convert-list '(control ?a))
     => 1
(event-convert-list '(control meta ?a))
     => -134217727
(event-convert-list '(control super f1))
     => C-s-f1
Accessing Events

This section describes convenient functions for accessing the data in a mouse button or motion event.

These two functions return the starting or ending position of a mouse-button event, as a list of this form:
(window buffer-position (x . y) timestamp)
Function: event-start event
This returns the starting position of event.

If event is a click or button-down event, this returns the location of the event. If event is a drag event, this returns the drag's starting position.

Function: event-end event
This returns the ending position of event.

If event is a drag event, this returns the position where the user released the mouse button. If event is a click or button-down event, the value is actually the starting position, which is the only position such events have.

These five functions take a position list as described above, and return various parts of it.

Function: posn-window position
Return the window that position is in.

Function: posn-point position
Return the buffer position in position. This is an integer.

Function: posn-x-y position
Return the pixel-based x and y coordinates in position, as a cons cell (x . y).

Function: posn-col-row position
Return the row and column (in units of characters) of position, as a cons cell (col . row). These are computed from the x and y values actually found in position.

Function: posn-timestamp position
Return the timestamp in position.

These functions are useful for decoding scroll bar events.

Function: scroll-bar-event-ratio event
This function returns the fractional vertical position of a scroll bar event within the scroll bar. The value is a cons cell (portion . whole) containing two integers whose ratio is the fractional position.

Function: scroll-bar-scale ratio total
This function multiplies (in effect) ratio by total, rounding the result to an integer. The argument ratio is not a number, but rather a pair (num . denom)---typically a value returned by scroll-bar-event-ratio.

This function is handy for scaling a position on a scroll bar into a buffer position. Here's how to do that:
(+ (point-min)
   (scroll-bar-scale
      (posn-x-y (event-start event))
      (- (point-max) (point-min))))
Recall that scroll bar events have two integers forming a ratio, in place of a pair of x and y coordinates.

Putting Keyboard Events in Strings

In most of the places where strings are used, we conceptualize the string as containing text characters--the same kind of characters found in buffers or files. Occasionally Lisp programs use strings that conceptually contain keyboard characters; for example, they may be key sequences or keyboard macro definitions. However, storing keyboard characters in a string is a complex matter, for reasons of historical compatibility, and it is not always possible.

We recommend that new programs avoid dealing with these complexities by not storing keyboard events in strings. Here is how to do that:

Use vectors instead of strings for key sequences, when you plan to use them for anything other than as arguments to lookup-key and define-key. For example, you can use read-key-sequence-vector instead of read-key-sequence, and this-command-keys-vector instead of this-command-keys.
Use vectors to write key sequence constants containing meta characters, even when passing them directly to define-key.
When you have to look at the contents of a key sequence that might be a string, use listify-key-sequence (see section Miscellaneous Event Input Features) first, to convert it to a list.

The complexities stem from the modifier bits that keyboard input characters can include. Aside from the Meta modifier, none of these modifier bits can be included in a string, and the Meta modifier is allowed only in special cases.

The earliest GNU Emacs versions represented meta characters as codes in the range of 128 to 255. At that time, the basic character codes ranged from 0 to 127, so all keyboard character codes did fit in a string. Many Lisp programs used `\M-' in string constants to stand for meta characters, especially in arguments to define-key and similar functions, and key sequences and sequences of events were always represented as strings.

When we added support for larger basic character codes beyond 127, and additional modifier bits, we had to change the representation of meta characters. Now the flag that represents the Meta modifier in a character is and such numbers cannot be included in a string.

To support programs with `\M-' in string constants, there are special rules for including certain meta characters in a string. Here are the rules for interpreting a string as a sequence of input characters:

If the keyboard character value is in the range of 0 to 127, it can go in the string unchanged.
The meta variants of those characters, with codes in the range of to can also go in the string, but you must change their numeric values. You must set the bit instead of the bit, resulting in a value between 128 and 255. Only a unibyte string can include these codes.
Non-ASCII characters above 256 can be included in a multibyte string.
Other keyboard character events cannot fit in a string. This includes keyboard events in the range of 128 to 255.

Functions such as read-key-sequence that construct strings of keyboard input characters follow these rules: they construct vectors instead of strings, when the events won't fit in a string.

When you use the read syntax `\M-' in a string, it produces a code in the range of 128 to 255--the same code that you get if you modify the corresponding keyboard event to put it in the string. Thus, meta events in strings work consistently regardless of how they get into the strings.

However, most programs would do well to avoid these issues by following the recommendations at the beginning of this section.

Reading Input

The editor command loop reads key sequences using the function read-key-sequence, which uses read-event. These and other functions for event input are also available for use in Lisp programs. See also momentary-string-display in section Temporary Displays, and sit-for in section Waiting for Elapsed Time or Input. See section Terminal Input, for functions and variables for controlling terminal input modes and debugging terminal input. See section Translating Input Events, for features you can use for translating or modifying input events while reading them.

For higher-level input facilities, see section Minibuffers.

Key Sequence Input

The command loop reads input a key sequence at a time, by calling read-key-sequence. Lisp programs can also call this function; for example, describe-key uses it to read the key to describe.

Function: read-key-sequence prompt
This function reads a key sequence and returns it as a string or vector. It keeps reading events until it has accumulated a complete key sequence; that is, enough to specify a non-prefix command using the currently active keymaps.

If the events are all characters and all can fit in a string, then read-key-sequence returns a string (see section Putting Keyboard Events in Strings). Otherwise, it returns a vector, since a vector can hold all kinds of events--characters, symbols, and lists. The elements of the string or vector are the events in the key sequence.

The argument prompt is either a string to be displayed in the echo area as a prompt, or nil, meaning not to display a prompt.

In the example below, the prompt `?' is displayed in the echo area, and the user types C-x C-f.
(read-key-sequence "?")

---------- Echo Area ----------
?C-x C-f
---------- Echo Area ----------

     => "^X^F"
The function read-key-sequence suppresses quitting: C-g typed while reading with this function works like any other character, and does not set quit-flag. See section Quitting.

Function: read-key-sequence-vector prompt
This is like read-key-sequence except that it always returns the key sequence as a vector, never as a string. See section Putting Keyboard Events in Strings.

If an input character is an upper-case letter and has no key binding, but its lower-case equivalent has one, then read-key-sequence converts the character to lower case. Note that lookup-key does not perform case conversion in this way.

The function read-key-sequence also transforms some mouse events. It converts unbound drag events into click events, and discards unbound button-down events entirely. It also reshuffles focus events and miscellaneous window events so that they never appear in a key sequence with any other events.

When mouse events occur in special parts of a window, such as a mode line or a scroll bar, the event type shows nothing special--it is the same symbol that would normally represent that combination of mouse button and modifier keys. The information about the window part is kept elsewhere in the event--in the coordinates. But read-key-sequence translates this information into imaginary "prefix keys", all of which are symbols: mode-line, vertical-line, horizontal-scroll-bar and vertical-scroll-bar. You can define meanings for mouse clicks in special window parts by defining key sequences using these imaginary prefix keys.

For example, if you call read-key-sequence and then click the mouse on the window's mode line, you get two events, like this:
(read-key-sequence "Click on the mode line: ")
     => [mode-line
         (mouse-1
          (#<window 6 on NEWS> mode-line
           (40 . 63) 5959987))]
Variable: num-input-keys
This variable's value is the number of key sequences processed so far in this Emacs session. This includes key sequences read from the terminal and key sequences read from keyboard macros being executed.

Variable: num-nonmacro-input-events
This variable holds the total number of input events received so far from the terminal--not counting those generated by keyboard macros.

Reading One Event

The lowest level functions for command input are those that read a single event.

Function: read-event &optional prompt suppress-input-method
This function reads and returns the next event of command input, waiting if necessary until an event is available. Events can come directly from the user or from a keyboard macro.

If prompt is non-nil, it should be a string to display in the echo area as a prompt. Otherwise, read-event does not display any message to indicate it is waiting for input; instead, it prompts by echoing: it displays descriptions of the events that led to or were read by the current command. See section The Echo Area.

If suppress-input-method is non-nil, then the current input method is disabled for reading this event. If you want to read an event without input-method processing, always do it this way; don't try binding input-method-function (see below).

If cursor-in-echo-area is non-nil, then read-event moves the cursor temporarily to the echo area, to the end of any message displayed there. Otherwise read-event does not move the cursor.

If read-event gets an event that is defined as a help character, in some cases read-event processes the event directly without returning. See section Help Functions. Certain other events, called special events, are also processed directly within read-event (see section Special Events).

Here is what happens if you call read-event and then press the right-arrow function key:
(read-event)
     => right
Function: read-char
This function reads and returns a character of command input. It discards any events that are not characters, until it gets a character.

In the first example, the user types the character 1 (ASCII code 49). The second example shows a keyboard macro definition that calls read-char from the minibuffer using eval-expression. read-char reads the keyboard macro's very next character, which is 1. Then eval-expression displays its return value in the echo area.
(read-char)
     => 49

;; We assume here you use M-: to evaluate this.
(symbol-function 'foo)
     => "^[:(read-char)^M1"
(execute-kbd-macro 'foo)
     -| 49
     => nil
read-event also invokes the current input method, if any. If the value of input-method-function is non-nil, it should be a function; when read-event reads a printing character (including SPC) with no modifier bits, it calls that function, passing the event as an argument.

Variable: input-method-function
If this is non-nil, its value specifies the current input method function.

Note: Don't bind this variable with let. It is often buffer-local, and if you bind it around reading input (which is exactly when you would bind it), switching buffers asynchronously while Emacs is waiting will cause the value to be restored in the wrong buffer.

The input method function should return a list of events which should be used as input. (If the list is nil, that means there is no input, so read-event waits for another event.) These events are processed before the events in unread-command-events. Events returned by the input method function are not passed to the input method function again, even if they are printing characters with no modifier bits.

If the input method function calls read-event or read-key-sequence, it should bind input-method-function to nil first, to prevent recursion.

The input method function is not called when reading the second and subsequent event of a key sequence. Thus, these characters are not subject to input method processing. It is usually a good idea for the input method processing to test the values of overriding-local-map and overriding-terminal-local-map; if either of these variables is non-nil, the input method should put its argument into a list and return that list with no further processing.

Quoted Character Input

You can use the function read-quoted-char to ask the user to specify a character, and allow the user to specify a control or meta character conveniently, either literally or as an octal character code. The command quoted-insert uses this function.

Function: read-quoted-char &optional prompt
This function is like read-char, except that if the first character read is an octal digit (0-7), it reads any number of octal digits (but stopping if a non-octal digit is found), and returns the character represented by that numeric character code.

Quitting is suppressed when the first character is read, so that the user can enter a C-g. See section Quitting.

If prompt is supplied, it specifies a string for prompting the user. The prompt string is always displayed in the echo area, followed by a single `-'.

In the following example, the user types in the octal number 177 (which is 127 in decimal).
(read-quoted-char "What character")

---------- Echo Area ----------
What character-177
---------- Echo Area ----------

     => 127
Miscellaneous Event Input Features

This section describes how to "peek ahead" at events without using them up, how to check for pending input, and how to discard pending input. See also the function read-passwd (see section Reading a Password).

Variable: unread-command-events
This variable holds a list of events waiting to be read as command input. The events are used in the order they appear in the list, and removed one by one as they are used.

The variable is needed because in some cases a function reads an event and then decides not to use it. Storing the event in this variable causes it to be processed normally, by the command loop or by the functions to read command input.

For example, the function that implements numeric prefix arguments reads any number of digits. When it finds a non-digit event, it must unread the event so that it can be read normally by the command loop. Likewise, incremental search uses this feature to unread events with no special meaning in a search, because these events should exit the search and then execute normally.

The reliable and easy way to extract events from a key sequence so as to put them in unread-command-events is to use listify-key-sequence (see section Putting Keyboard Events in Strings).

Normally you add events to the front of this list, so that the events most recently unread will be reread first.

Function: listify-key-sequence key
This function converts the string or vector key to a list of individual events, which you can put in unread-command-events.

Variable: unread-command-char
This variable holds a character to be read as command input. A value of -1 means "empty".

This variable is mostly obsolete now that you can use unread-command-events instead; it exists only to support programs written for Emacs versions 18 and earlier.

Function: input-pending-p
This function determines whether any command input is currently available to be read. It returns immediately, with value t if there is available input, nil otherwise. On rare occasions it may return t when no input is available.

Variable: last-input-event

Variable: last-input-char
This variable records the last terminal input event read, whether as part of a command or explicitly by a Lisp program.

In the example below, the Lisp program reads the character 1, ASCII code 49. It becomes the value of last-input-event, while C-e (we assume C-x C-e command is used to evaluate this expression) remains the value of last-command-event.
(progn (print (read-char))
       (print last-command-event)
       last-input-event)
     -| 49
     -| 5
     => 49
The alias last-input-char exists for compatibility with Emacs version 18.

Function: discard-input
This function discards the contents of the terminal input buffer and cancels any keyboard macro that might be in the process of definition. It returns nil.

In the following example, the user may type a number of characters right after starting the evaluation of the form. After the sleep-for finishes sleeping, discard-input discards any characters typed during the sleep.
(progn (sleep-for 2)
       (discard-input))
     => nil
Special Events

Special events are handled at a very low level--as soon as they are read. The read-event function processes these events itself, and never returns them.

Events that are handled in this way do not echo, they are never grouped into key sequences, and they never appear in the value of last-command-event or (this-command-keys). They do not discard a numeric argument, they cannot be unread with unread-command-events, they may not appear in a keyboard macro, and they are not recorded in a keyboard macro while you are defining one.

These events do, however, appear in last-input-event immediately after they are read, and this is the way for the event's definition to find the actual event.

The events types iconify-frame, make-frame-visible and delete-frame are normally handled in this way. The keymap which defines how to handle special events--and which events are special--is in the variable special-event-map (see section Active Keymaps).

Waiting for Elapsed Time or Input

The wait functions are designed to wait for a certain amount of time to pass or until there is input. For example, you may wish to pause in the middle of a computation to allow the user time to view the display. sit-for pauses and updates the screen, and returns immediately if input comes in, while sleep-for pauses without updating the screen.

Function: sit-for seconds &optional millisec nodisp
This function performs redisplay (provided there is no pending input from the user), then waits seconds seconds, or until input is available. The value is t if sit-for waited the full time with no input arriving (see input-pending-p in section Miscellaneous Event Input Features). Otherwise, the value is nil.

The argument seconds need not be an integer. If it is a floating point number, sit-for waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, seconds is rounded down.

The optional argument millisec specifies an additional waiting period measured in milliseconds. This adds to the period specified by seconds. If the system doesn't support waiting fractions of a second, you get an error if you specify nonzero millisec.

Redisplay is always preempted if input arrives, and does not happen at all if input is available before it starts. Thus, there is no way to force screen updating if there is pending input; however, if there is no input pending, you can force an update with no delay by using (sit-for 0).

If nodisp is non-nil, then sit-for does not redisplay, but it still returns as soon as input is available (or when the timeout elapses).

Iconifying or deiconifying a frame makes sit-for return, because that generates an event. See section Miscellaneous Window System Events.

The usual purpose of sit-for is to give the user time to read text that you display.

Function: sleep-for seconds &optional millisec
This function simply pauses for seconds seconds without updating the display. It pays no attention to available input. It returns nil.

The argument seconds need not be an integer. If it is a floating point number, sleep-for waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, seconds is rounded down.

The optional argument millisec specifies an additional waiting period measured in milliseconds. This adds to the period specified by seconds. If the system doesn't support waiting fractions of a second, you get an error if you specify nonzero millisec.

Use sleep-for when you wish to guarantee a delay.

See section Time of Day, for functions to get the current time.

Quitting

Typing C-g while a Lisp function is running causes Emacs to quit whatever it is doing. This means that control returns to the innermost active command loop.

Typing C-g while the command loop is waiting for keyboard input does not cause a quit; it acts as an ordinary input character. In the simplest case, you cannot tell the difference, because C-g normally runs the command keyboard-quit, whose effect is to quit. However, when C-g follows a prefix key, they combine to form an undefined key. The effect is to cancel the prefix key as well as any prefix argument.

In the minibuffer, C-g has a different definition: it aborts out of the minibuffer. This means, in effect, that it exits the minibuffer and then quits. (Simply quitting would return to the command loop within the minibuffer.) The reason why C-g does not quit directly when the command reader is reading input is so that its meaning can be redefined in the minibuffer in this way. C-g following a prefix key is not redefined in the minibuffer, and it has its normal effect of canceling the prefix key and prefix argument. This too would not be possible if C-g always quit directly.

When C-g does directly quit, it does so by setting the variable quit-flag to t. Emacs checks this variable at appropriate times and quits if it is not nil. Setting quit-flag non-nil in any way thus causes a quit.

At the level of C code, quitting cannot happen just anywhere; only at the special places that check quit-flag. The reason for this is that quitting at other places might leave an inconsistency in Emacs's internal state. Because quitting is delayed until a safe place, quitting cannot make Emacs crash.

Certain functions such as read-key-sequence or read-quoted-char prevent quitting entirely even though they wait for input. Instead of quitting, C-g serves as the requested input. In the case of read-key-sequence, this serves to bring about the special behavior of C-g in the command loop. In the case of read-quoted-char, this is so that C-q can be used to quote a C-g.

You can prevent quitting for a portion of a Lisp function by binding the variable inhibit-quit to a non-nil value. Then, although C-g still sets quit-flag to t as usual, the usual result of this--a quit--is prevented. Eventually, inhibit-quit will become nil again, such as when its binding is unwound at the end of a let form. At that time, if quit-flag is still non-nil, the requested quit happens immediately. This behavior is ideal when you wish to make sure that quitting does not happen within a "critical section" of the program.

In some functions (such as read-quoted-char), C-g is handled in a special way that does not involve quitting. This is done by reading the input with inhibit-quit bound to t, and setting quit-flag to nil before inhibit-quit becomes nil again. This excerpt from the definition of read-quoted-char shows how this is done; it also shows that normal quitting is permitted after the first character of input.
(defun read-quoted-char (&optional prompt)
  "...documentation..."
  (let ((message-log-max nil) done (first t) (code 0) char)
    (while (not done)
      (let ((inhibit-quit first)
            ...)
    (and prompt (message "%s-" prompt))
    (setq char (read-event))
    (if inhibit-quit (setq quit-flag nil)))
      ...set the variable code...)
    code))
Variable: quit-flag
If this variable is non-nil, then Emacs quits immediately, unless inhibit-quit is non-nil. Typing C-g ordinarily sets quit-flag non-nil, regardless of inhibit-quit.

Variable: inhibit-quit
This variable determines whether Emacs should quit when quit-flag is set to a value other than nil. If inhibit-quit is non-nil, then quit-flag has no special effect.

Command: keyboard-quit
This function signals the quit condition with (signal 'quit nil). This is the same thing that quitting does. (See signal in section Errors.)

You can specify a character other than C-g to use for quitting. See the function set-input-mode in section Terminal Input.
Prefix Command Arguments

Most Emacs commands can use a prefix argument, a number specified before the command itself. (Don't confuse prefix arguments with prefix keys.) The prefix argument is at all times represented by a value, which may be nil, meaning there is currently no prefix argument. Each command may use the prefix argument or ignore it.

There are two representations of the prefix argument: raw and numeric. The editor command loop uses the raw representation internally, and so do the Lisp variables that store the information, but commands can request either representation.

Here are the possible values of a raw prefix argument:

nil, meaning there is no prefix argument. Its numeric value is 1, but numerous commands make a distinction between nil and the integer 1.
An integer, which stands for itself.
A list of one element, which is an integer. This form of prefix argument results from one or a succession of C-u's with no digits. The numeric value is the integer in the list, but some commands make a distinction between such a list and an integer alone.
The symbol -. This indicates that M-- or C-u - was typed, without following digits. The equivalent numeric value is -1, but some commands make a distinction between the integer -1 and the symbol -.

We illustrate these possibilities by calling the following function with various prefixes:
(defun display-prefix (arg)
  "Display the value of the raw prefix arg."
  (interactive "P")
  (message "%s" arg))
Here are the results of calling display-prefix with various raw prefix arguments:
        M-x display-prefix  -| nil

C-u     M-x display-prefix  -| (4)

C-u C-u M-x display-prefix  -| (16)

C-u 3   M-x display-prefix  -| 3

M-3     M-x display-prefix  -| 3      ; (Same as C-u 3.)

C-u -   M-x display-prefix  -| -

M--     M-x display-prefix  -| -      ; (Same as C-u -.)

C-u - 7 M-x display-prefix  -| -7

M-- 7   M-x display-prefix  -| -7     ; (Same as C-u -7.)
Emacs uses two variables to store the prefix argument: prefix-arg and current-prefix-arg. Commands such as universal-argument that set up prefix arguments for other commands store them in prefix-arg. In contrast, current-prefix-arg conveys the prefix argument to the current command, so setting it has no effect on the prefix arguments for future commands.

Normally, commands specify which representation to use for the prefix argument, either numeric or raw, in the interactive declaration. (See section Using interactive.) Alternatively, functions may look at the value of the prefix argument directly in the variable current-prefix-arg, but this is less clean.

Function: prefix-numeric-value arg
This function returns the numeric meaning of a valid raw prefix argument value, arg. The argument may be a symbol, a number, or a list. If it is nil, the value 1 is returned; if it is -, the value -1 is returned; if it is a number, that number is returned; if it is a list, the CAR of that list (which should be a number) is returned.

Variable: current-prefix-arg
This variable holds the raw prefix argument for the current command. Commands may examine it directly, but the usual method for accessing it is with (interactive "P").

Variable: prefix-arg
The value of this variable is the raw prefix argument for the next editing command. Commands such as universal-argument that specify prefix arguments for the following command work by setting this variable.

Variable: last-prefix-arg
The raw prefix argument value used by the previous command.

The following commands exist to set up prefix arguments for the following command. Do not call them for any other reason.

Command: universal-argument
This command reads input and specifies a prefix argument for the following command. Don't call this command yourself unless you know what you are doing.

Command: digit-argument arg
This command adds to the prefix argument for the following command. The argument arg is the raw prefix argument as it was before this command; it is used to compute the updated prefix argument. Don't call this command yourself unless you know what you are doing.

Command: negative-argument arg
This command adds to the numeric argument for the next command. The argument arg is the raw prefix argument as it was before this command; its value is negated to form the new prefix argument. Don't call this command yourself unless you know what you are doing.

Recursive Editing

The Emacs command loop is entered automatically when Emacs starts up. This top-level invocation of the command loop never exits; it keeps running as long as Emacs does. Lisp programs can also invoke the command loop. Since this makes more than one activation of the command loop, we call it recursive editing. A recursive editing level has the effect of suspending whatever command invoked it and permitting the user to do arbitrary editing before resuming that command.

The commands available during recursive editing are the same ones available in the top-level editing loop and defined in the keymaps. Only a few special commands exit the recursive editing level; the others return to the recursive editing level when they finish. (The special commands for exiting are always available, but they do nothing when recursive editing is not in progress.)

All command loops, including recursive ones, set up all-purpose error handlers so that an error in a command run from the command loop will not exit the loop.

Minibuffer input is a special kind of recursive editing. It has a few special wrinkles, such as enabling display of the minibuffer and the minibuffer window, but fewer than you might suppose. Certain keys behave differently in the minibuffer, but that is only because of the minibuffer's local map; if you switch windows, you get the usual Emacs commands.

To invoke a recursive editing level, call the function recursive-edit. This function contains the command loop; it also contains a call to catch with tag exit, which makes it possible to exit the recursive editing level by throwing to exit (see section Explicit Nonlocal Exits: catch and throw). If you throw a value other than t, then recursive-edit returns normally to the function that called it. The command C-M-c (exit-recursive-edit) does this. Throwing a t value causes recursive-edit to quit, so that control returns to the command loop one level up. This is called aborting, and is done by C-] (abort-recursive-edit).

Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you change the major mode of the current buffer temporarily to a special major mode, which should have a command to go back to the previous mode. (The e command in Rmail uses this technique.) Or, if you wish to give the user different text to edit "recursively", create and select a new buffer in a special mode. In this mode, define a command to complete the processing and go back to the previous buffer. (The m command in Rmail does this.)

Recursive edits are useful in debugging. You can insert a call to debug into a function definition as a sort of breakpoint, so that you can look around when the function gets there. debug invokes a recursive edit but also provides the other features of the debugger.

Recursive editing levels are also used when you type C-r in query-replace or use C-x q (kbd-macro-query).

Function: recursive-edit
This function invokes the editor command loop. It is called automatically by the initialization of Emacs, to let the user begin editing. When called from a Lisp program, it enters a recursive editing level.

In the following example, the function simple-rec first advances point one word, then enters a recursive edit, printing out a message in the echo area. The user can then do any editing desired, and then type C-M-c to exit and continue executing simple-rec.
(defun simple-rec ()
  (forward-word 1)
  (message "Recursive edit in progress")
  (recursive-edit)
  (forward-word 1))
     => simple-rec
(simple-rec)
     => nil
Command: exit-recursive-edit
This function exits from the innermost recursive edit (including minibuffer input). Its definition is effectively (throw 'exit nil).

Command: abort-recursive-edit
This function aborts the command that requested the innermost recursive edit (including minibuffer input), by signaling quit after exiting the recursive edit. Its definition is effectively (throw 'exit t). See section Quitting.

Command: top-level
This function exits all recursive editing levels; it does not return a value, as it jumps completely out of any computation directly back to the main command loop.

Function: recursion-depth
This function returns the current depth of recursive edits. When no recursive edit is active, it returns 0.

Disabling Commands

Disabling a command marks the command as requiring user confirmation before it can be executed. Disabling is used for commands which might be confusing to beginning users, to prevent them from using the commands by accident.

The low-level mechanism for disabling a command is to put a non-nil disabled property on the Lisp symbol for the command. These properties are normally set up by the user's `.emacs' file with Lisp expressions such as this:
(put 'upcase-region 'disabled t)
For a few commands, these properties are present by default and may be removed by the `.emacs' file.

If the value of the disabled property is a string, the message saying the command is disabled includes that string. For example:
(put 'delete-region 'disabled
     "Text deleted this way cannot be yanked back!\n")
See section `Disabling' in The GNU Emacs Manual, for the details on what happens when a disabled command is invoked interactively. Disabling a command has no effect on calling it as a function from Lisp programs.

Command: enable-command command
Allow command to be executed without special confirmation from now on, and (if the user confirms) alter the user's `.emacs' file so that this will apply to future sessions.

Command: disable-command command
Require special confirmation to execute command from now on, and (if the user confirms) alter the user's `.emacs' file so that this will apply to future sessions.

Variable: disabled-command-hook
When the user invokes a disabled command interactively, this normal hook is run instead of the disabled command. The hook functions can use this-command-keys to determine what the user typed to run the command, and thus find the command itself. See section Hooks.

By default, disabled-command-hook contains a function that asks the user whether to proceed.

Command History

The command loop keeps a history of the complex commands that have been executed, to make it convenient to repeat these commands. A complex command is one for which the interactive argument reading uses the minibuffer. This includes any M-x command, any M-: command, and any command whose interactive specification reads an argument from the minibuffer. Explicit use of the minibuffer during the execution of the command itself does not cause the command to be considered complex.

Variable: command-history
This variable's value is a list of recent complex commands, each represented as a form to evaluate. It continues to accumulate all complex commands for the duration of the editing session, but when it reaches the maximum size (specified by the variable history-length), the oldest elements are deleted as new ones are added.
command-history
=> ((switch-to-buffer "chistory.texi")
    (describe-key "^X^[")
    (visit-tags-table "~/emacs/src/")
    (find-tag "repeat-complex-command"))
This history list is actually a special case of minibuffer history (see section Minibuffer History), with one special twist: the elements are expressions rather than strings.

There are a number of commands devoted to the editing and recall of previous commands. The commands repeat-complex-command, and list-command-history are described in the user manual (see section `Repetition' in The GNU Emacs Manual). Within the minibuffer, the usual minibuffer history commands are available.

Keyboard Macros

A keyboard macro is a canned sequence of input events that can be considered a command and made the definition of a key. The Lisp representation of a keyboard macro is a string or vector containing the events. Don't confuse keyboard macros with Lisp macros (see section Macros).

Function: execute-kbd-macro kbdmacro &optional count
This function executes kbdmacro as a sequence of events. If kbdmacro is a string or vector, then the events in it are executed exactly as if they had been input by the user. The sequence is not expected to be a single key sequence; normally a keyboard macro definition consists of several key sequences concatenated.

If kbdmacro is a symbol, then its function definition is used in place of kbdmacro. If that is another symbol, this process repeats. Eventually the result should be a string or vector. If the result is not a symbol, string, or vector, an error is signaled.

The argument count is a repeat count; kbdmacro is executed that many times. If count is omitted or nil, kbdmacro is executed once. If it is 0, kbdmacro is executed over and over until it encounters an error or a failing search.

See section Reading One Event, for an example of using execute-kbd-macro.

Variable: executing-macro
This variable contains the string or vector that defines the keyboard macro that is currently executing. It is nil if no macro is currently executing. A command can test this variable so as to behave differently when run from an executing macro. Do not set this variable yourself.

Variable: defining-kbd-macro
This variable indicates whether a keyboard macro is being defined. A command can test this variable so as to behave differently while a macro is being defined. The commands start-kbd-macro and end-kbd-macro set this variable--do not set it yourself.

The variable is always local to the current terminal and cannot be buffer-local. See section Multiple Displays.

Variable: last-kbd-macro
This variable is the definition of the most recently defined keyboard macro. Its value is a string or vector, or nil.

The variable is always local to the current terminal and cannot be buffer-local. See section Multiple Displays.

Keymaps

The bindings between input events and commands are recorded in data structures called keymaps. Each binding in a keymap associates (or binds) an individual event type either to another keymap or to a command. When an event type is bound to a keymap, that keymap is used to look up the next input event; this continues until a command is found. The whole process is called key lookup.

Keymap Terminology

A keymap is a table mapping event types to definitions (which can be any Lisp objects, though only certain types are meaningful for execution by the command loop). Given an event (or an event type) and a keymap, Emacs can get the event's definition. Events include characters, function keys, and mouse actions (see section Input Events).

A sequence of input events that form a unit is called a key sequence, or key for short. A sequence of one event is always a key sequence, and so are some multi-event sequences.

A keymap determines a binding or definition for any key sequence. If the key sequence is a single event, its binding is the definition of the event in the keymap. The binding of a key sequence of more than one event is found by an iterative process: the binding of the first event is found, and must be a keymap; then the second event's binding is found in that keymap, and so on until all the events in the key sequence are used up.

If the binding of a key sequence is a keymap, we call the key sequence a prefix key. Otherwise, we call it a complete key (because no more events can be added to it). If the binding is nil, we call the key undefined. Examples of prefix keys are C-c, C-x, and C-x 4. Examples of defined complete keys are X, RET, and C-x 4 C-f. Examples of undefined complete keys are C-x C-g, and C-c 3. See section Prefix Keys, for more details.

The rule for finding the binding of a key sequence assumes that the intermediate bindings (found for the events before the last) are all keymaps; if this is not so, the sequence of events does not form a unit--it is not really one key sequence. In other words, removing one or more events from the end of any valid key sequence must always yield a prefix key. For example, C-f C-n is not a key sequence; C-f is not a prefix key, so a longer sequence starting with C-f cannot be a key sequence.

The set of possible multi-event key sequences depends on the bindings for prefix keys; therefore, it can be different for different keymaps, and can change when bindings are changed. However, a one-event sequence is always a key sequence, because it does not depend on any prefix keys for its well-formedness.

At any time, several primary keymaps are active---that is, in use for finding key bindings. These are the global map, which is shared by all buffers; the local keymap, which is usually associated with a specific major mode; and zero or more minor mode keymaps, which belong to currently enabled minor modes. (Not all minor modes have keymaps.) The local keymap bindings shadow (i.e., take precedence over) the corresponding global bindings. The minor mode keymaps shadow both local and global keymaps. See section Active Keymaps, for details.

Format of Keymaps

A keymap is a list whose CAR is the symbol keymap. The remaining elements of the list define the key bindings of the keymap. Use the function keymapp (see below) to test whether an object is a keymap.

Several kinds of elements may appear in a keymap, after the symbol keymap that begins it:

(type . binding)
This specifies one binding, for events of type type. Each ordinary binding applies to events of a particular event type, which is always a character or a symbol. See section Classifying Events.
(t . binding)
This specifies a default key binding; any event not bound by other elements of the keymap is given binding as its binding. Default bindings allow a keymap to bind all possible event types without having to enumerate all of them. A keymap that has a default binding completely masks any lower-precedence keymap.
vector
If an element of a keymap is a vector, the vector counts as bindings for all the ASCII characters, codes 0 through 127; vector element n is the binding for the character with code n. This is a compact way to record lots of bindings. A keymap with such a vector is called a full keymap. Other keymaps are called sparse keymaps. When a keymap contains a vector, it always defines a binding for each ASCII character, even if the vector contains nil for that character. Such a binding of nil overrides any default key binding in the keymap, for ASCII characters. However, default bindings are still meaningful for events other than ASCII characters. A binding of nil does not override lower-precedence keymaps; thus, if the local map gives a binding of nil, Emacs uses the binding from the global map.
string
Aside from bindings, a keymap can also have a string as an element. This is called the overall prompt string and makes it possible to use the keymap as a menu. See section Menu Keymaps.
Keymaps do not directly record bindings for the meta characters. Instead, meta characters are regarded for purposes of key lookup as sequences of two characters, the first of which is ESC (or whatever is currently the value of meta-prefix-char). Thus, the key M-a is really represented as ESC a, and its global binding is found at the slot for a in esc-map (see section Prefix Keys).

Here as an example is the local keymap for Lisp mode, a sparse keymap. It defines bindings for DEL and TAB, plus C-c C-l, M-C-q, and M-C-x.
lisp-mode-map
=>
(keymap
 ;; TAB
 (9 . lisp-indent-line)
 ;; DEL
 (127 . backward-delete-char-untabify)
 (3 keymap
    ;; C-c C-l
    (12 . run-lisp))
 (27 keymap
     ;; M-C-q, treated as ESC C-q
     (17 . indent-sexp)
     ;; M-C-x, treated as ESC C-x
     (24 . lisp-send-defun)))
Function: keymapp object
This function returns t if object is a keymap, nil otherwise. More precisely, this function tests for a list whose CAR is keymap.
(keymapp '(keymap))
    => t
(keymapp (current-global-map))
    => t
Creating Keymaps

Here we describe the functions for creating keymaps.

Function: make-keymap &optional prompt
This function creates and returns a new full keymap (i.e., one containing a vector of length 128 for defining all the ASCII characters). The new keymap initially binds all ASCII characters to nil, and does not bind any other kind of event.
(make-keymap)
    => (keymap [nil nil nil ... nil nil])
If you specify prompt, that becomes the overall prompt string for the keymap. The prompt string is useful for menu keymaps (see section Menu Keymaps).

Function: make-sparse-keymap &optional prompt
This function creates and returns a new sparse keymap with no entries. The new keymap does not bind any events. The argument prompt specifies a prompt string, as in make-keymap.
(make-sparse-keymap)
    => (keymap)
Function: copy-keymap keymap
This function returns a copy of keymap. Any keymaps that appear directly as bindings in keymap are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function definition is a keymap; the same symbol appears in the new copy.
(setq map (copy-keymap (current-local-map)))
=> (keymap
     ;; (This implements meta characters.)
     (27 keymap
         (83 . center-paragraph)
         (115 . center-line))
     (9 . tab-to-tab-stop))

(eq map (current-local-map))
    => nil
(equal map (current-local-map))
    => t
Inheritance and Keymaps

A keymap can inherit the bindings of another keymap, which we call the parent keymap. Such a keymap looks like this:
(keymap bindings... . parent-keymap)
The effect is that this keymap inherits all the bindings of parent-keymap, whatever they may be at the time a key is looked up, but can add to them or override them with bindings.

If you change the bindings in parent-keymap using define-key or other key-binding functions, these changes are visible in the inheriting keymap unless shadowed by bindings. The converse is not true: if you use define-key to change the inheriting keymap, that affects bindings, but has no effect on parent-keymap.

The proper way to construct a keymap with a parent is to use set-keymap-parent; if you have code that directly constructs a keymap with a parent, please convert the program to use set-keymap-parent instead.

Function: keymap-parent keymap
This returns the parent keymap of keymap. If keymap has no parent, keymap-parent returns nil.

Function: set-keymap-parent keymap parent
This sets the parent keymap of keymap to parent, and returns parent. If parent is nil, this function gives keymap no parent at all.

If keymap has submaps (bindings for prefix keys), they too receive new parent keymaps that reflect what parent specifies for those prefix keys.

Here is an example showing how to make a keymap that inherits from text-mode-map:
(let ((map (make-sparse-keymap)))
  (set-keymap-parent map text-mode-map)
  map)
Prefix Keys

A prefix key is a key sequence whose binding is a keymap. The keymap defines what to do with key sequences that extend the prefix key. For example, C-x is a prefix key, and it uses a keymap that is also stored in the variable ctl-x-map. This keymap defines bindings for key sequences starting with C-x.

Some of the standard Emacs prefix keys use keymaps that are also found in Lisp variables:

esc-map is the global keymap for the ESC prefix key. Thus, the global definitions of all meta characters are actually found here. This map is also the function definition of ESC-prefix.
help-map is the global keymap for the C-h prefix key.
mode-specific-map is the global keymap for the prefix key C-c. This map is actually global, not mode-specific, but its name provides useful information about C-c in the output of C-h b (display-bindings), since the main use of this prefix key is for mode-specific bindings.
ctl-x-map is the global keymap used for the C-x prefix key. This map is found via the function cell of the symbol Control-X-prefix.
mule-keymap is the global keymap used for the C-x RET prefix key.
ctl-x-4-map is the global keymap used for the C-x 4 prefix key.
ctl-x-5-map is the global keymap used for the C-x 5 prefix key.
2C-mode-map is the global keymap used for the C-x 6 prefix key.
vc-prefix-map is the global keymap used for the C-x v prefix key.
facemenu-keymap is the global keymap used for the M-g prefix key.
The other Emacs prefix keys are C-x @, C-x a i, C-x ESC and ESC ESC. They use keymaps that have no special names.

The keymap binding of a prefix key is used for looking up the event that follows the prefix key. (It may instead be a symbol whose function definition is a keymap. The effect is the same, but the symbol serves as a name for the prefix key.) Thus, the binding of C-x is the symbol Control-X-prefix, whose function cell holds the keymap for C-x commands. (The same keymap is also the value of ctl-x-map.)

Prefix key definitions can appear in any active keymap. The definitions of C-c, C-x, C-h and ESC as prefix keys appear in the global map, so these prefix keys are always available. Major and minor modes can redefine a key as a prefix by putting a prefix key definition for it in the local map or the minor mode's map. See section Active Keymaps.

If a key is defined as a prefix in more than one active map, then its various definitions are in effect merged: the commands defined in the minor mode keymaps come first, followed by those in the local map's prefix definition, and then by those from the global map.

In the following example, we make C-p a prefix key in the local keymap, in such a way that C-p is identical to C-x. Then the binding for C-p C-f is the function find-file, just like C-x C-f. The key sequence C-p 6 is not found in any active keymap.
(use-local-map (make-sparse-keymap))
    => nil
(local-set-key "\C-p" ctl-x-map)
    => nil
(key-binding "\C-p\C-f")
    => find-file

(key-binding "\C-p6")
    => nil
Function: define-prefix-command symbol
This function prepares symbol for use as a prefix key's binding: it creates a full keymap and stores it as symbol's function definition. Subsequently binding a key sequence to symbol will make that key sequence into a prefix key.

This function also sets symbol as a variable, with the keymap as its value. It returns symbol.

Active Keymaps

Emacs normally contains many keymaps; at any given time, just a few of them are active in that they participate in the interpretation of user input. These are the global keymap, the current buffer's local keymap, and the keymaps of any enabled minor modes.

The global keymap holds the bindings of keys that are defined regardless of the current buffer, such as C-f. The variable global-map holds this keymap, which is always active.

Each buffer may have another keymap, its local keymap, which may contain new or overriding definitions for keys. The current buffer's local keymap is always active except when overriding-local-map overrides it. Text properties can specify an alternative local map for certain parts of the buffer; see section Properties with Special Meanings.

Each minor mode can have a keymap; if it does, the keymap is active when the minor mode is enabled.

The variable overriding-local-map, if non-nil, specifies another local keymap that overrides the buffer's local map and all the minor mode keymaps.

All the active keymaps are used together to determine what command to execute when a key is entered. Emacs searches these maps one by one, in order of decreasing precedence, until it finds a binding in one of the maps. The procedure for searching a single keymap is called key lookup; see section Key Lookup.

Normally, Emacs first searches for the key in the minor mode maps, in the order specified by minor-mode-map-alist; if they do not supply a binding for the key, Emacs searches the local map; if that too has no binding, Emacs then searches the global map. However, if overriding-local-map is non-nil, Emacs searches that map first, before the global map.

Since every buffer that uses the same major mode normally uses the same local keymap, you can think of the keymap as local to the mode. A change to the local keymap of a buffer (using local-set-key, for example) is seen also in the other buffers that share that keymap.

The local keymaps that are used for Lisp mode and some other major modes exist even if they have not yet been used. These local maps are the values of variables such as lisp-mode-map. For most major modes, which are less frequently used, the local keymap is constructed only when the mode is used for the first time in a session.

The minibuffer has local keymaps, too; they contain various completion and exit commands. See section Introduction to Minibuffers.

Emacs has other keymaps that are used in a different way--translating events within read-key-sequence. See section Translating Input Events.

See section Standard Keymaps, for a list of standard keymaps.

Variable: global-map
This variable contains the default global keymap that maps Emacs keyboard input to commands. The global keymap is normally this keymap. The default global keymap is a full keymap that binds self-insert-command to all of the printing characters.

It is normal practice to change the bindings in the global map, but you should not assign this variable any value other than the keymap it starts out with.

Function: current-global-map
This function returns the current global keymap. This is the same as the value of global-map unless you change one or the other.
(current-global-map)
=> (keymap [set-mark-command beginning-of-line ...
            delete-backward-char])
Function: current-local-map
This function returns the current buffer's local keymap, or nil if it has none. In the following example, the keymap for the `*scratch*' buffer (using Lisp Interaction mode) is a sparse keymap in which the entry for ESC, ASCII code 27, is another sparse keymap.
(current-local-map)
=> (keymap
    (10 . eval-print-last-sexp)
    (9 . lisp-indent-line)
    (127 . backward-delete-char-untabify)
    (27 keymap
        (24 . eval-defun)
        (17 . indent-sexp)))
Function: current-minor-mode-maps
This function returns a list of the keymaps of currently enabled minor modes.

Function: use-global-map keymap
This function makes keymap the new current global keymap. It returns nil.

It is very unusual to change the global keymap.

Function: use-local-map keymap
This function makes keymap the new local keymap of the current buffer. If keymap is nil, then the buffer has no local keymap. use-local-map returns nil. Most major mode commands use this function.

Variable: minor-mode-map-alist
This variable is an alist describing keymaps that may or may not be active according to the values of certain variables. Its elements look like this:
(variable . keymap)
The keymap keymap is active whenever variable has a non-nil value. Typically variable is the variable that enables or disables a minor mode. See section Keymaps and Minor Modes.

Note that elements of minor-mode-map-alist do not have the same structure as elements of minor-mode-alist. The map must be the CDR of the element; a list with the map as the CADR will not do. The CADR can be either a keymap (a list) or a symbol whose function definition is a keymap.

When more than one minor mode keymap is active, their order of priority is the order of minor-mode-map-alist. But you should design minor modes so that they don't interfere with each other. If you do this properly, the order will not matter.

See section Keymaps and Minor Modes, for more information about minor modes. See also minor-mode-key-binding (see section Functions for Key Lookup).

Variable: minor-mode-overriding-map-alist
This variable allows major modes to override the key bindings for particular minor modes. The elements of this alist look like the elements of minor-mode-map-alist: (variable . keymap).

If a variable appears as an element of minor-mode-overriding-map-alist, the map specified by that element totally replaces any map specified for the same variable in minor-mode-map-alist.

minor-mode-overriding-map-alist is automatically buffer-local in all buffers.

Variable: overriding-local-map
If non-nil, this variable holds a keymap to use instead of the buffer's local keymap and instead of all the minor mode keymaps. This keymap, if any, overrides all other maps that would have been active, except for the current global map.

Variable: overriding-terminal-local-map
If non-nil, this variable holds a keymap to use instead of overriding-local-map, the buffer's local keymap and all the minor mode keymaps.

This variable is always local to the current terminal and cannot be buffer-local. See section Multiple Displays. It is used to implement incremental search mode.

Variable: overriding-local-map-menu-flag
If this variable is non-nil, the value of overriding-local-map or overriding-terminal-local-map can affect the display of the menu bar. The default value is nil, so those map variables have no effect on the menu bar.

Note that these two map variables do affect the execution of key sequences entered using the menu bar, even if they do not affect the menu bar display. So if a menu bar key sequence comes in, you should clear the variables before looking up and executing that key sequence. Modes that use the variables would typically do this anyway; normally they respond to events that they do not handle by "unreading" them and exiting.

Variable: special-event-map
This variable holds a keymap for special events. If an event type has a binding in this keymap, then it is special, and the binding for the event is run directly by read-event. See section Special Events.

Key Lookup

Key lookup is the process of finding the binding of a key sequence from a given keymap. Actual execution of the binding is not part of key lookup.

Key lookup uses just the event type of each event in the key sequence; the rest of the event is ignored. In fact, a key sequence used for key lookup may designate mouse events with just their types (symbols) instead of with entire mouse events (lists). See section Input Events. Such a "key-sequence" is insufficient for command-execute to run, but it is sufficient for looking up or rebinding a key.

When the key sequence consists of multiple events, key lookup processes the events sequentially: the binding of the first event is found, and must be a keymap; then the second event's binding is found in that keymap, and so on until all the events in the key sequence are used up. (The binding thus found for the last event may or may not be a keymap.) Thus, the process of key lookup is defined in terms of a simpler process for looking up a single event in a keymap. How that is done depends on the type of object associated with the event in that keymap.

Let's use the term keymap entry to describe the value found by looking up an event type in a keymap. (This doesn't include the item string and other extra elements in menu key bindings, because lookup-key and other key lookup functions don't include them in the returned value.) While any Lisp object may be stored in a keymap as a keymap entry, not all make sense for key lookup. Here is a table of the meaningful kinds of keymap entries:

nil
nil means that the events used so far in the lookup form an undefined key. When a keymap fails to mention an event type at all, and has no default binding, that is equivalent to a binding of nil for that event type.
command
The events used so far in the lookup form a complete key, and command is its binding. See section What Is a Function?.
array
The array (either a string or a vector) is a keyboard macro. The events used so far in the lookup form a complete key, and the array is its binding. See section Keyboard Macros, for more information.
keymap
The events used so far in the lookup form a prefix key. The next event of the key sequence is looked up in keymap.
list
The meaning of a list depends on the types of the elements of the list.

If the CAR of list is the symbol keymap, then the list is a keymap, and is treated as a keymap (see above).
If the CAR of list is lambda, then the list is a lambda expression. This is presumed to be a command, and is treated as such (see above).
If the CAR of list is a keymap and the CDR is an event type, then this is an indirect entry:
(othermap . othertype)
When key lookup encounters an indirect entry, it looks up instead the binding of othertype in othermap and uses that. This feature permits you to define one key as an alias for another key. For example, an entry whose CAR is the keymap called esc-map and whose CDR is 32 (the code for SPC) means, "Use the global binding of Meta-SPC, whatever that may be."

symbol
The function definition of symbol is used in place of symbol. If that too is a symbol, then this process is repeated, any number of times. Ultimately this should lead to an object that is a keymap, a command, or a keyboard macro. A list is allowed if it is a keymap or a command, but indirect entries are not understood when found via symbols. Note that keymaps and keyboard macros (strings and vectors) are not valid functions, so a symbol with a keymap, string, or vector as its function definition is invalid as a function. It is, however, valid as a key binding. If the definition is a keyboard macro, then the symbol is also valid as an argument to command-execute (see section Interactive Call). The symbol undefined is worth special mention: it means to treat the key as undefined. Strictly speaking, the key is defined, and its binding is the command undefined; but that command does the same thing that is done automatically for an undefined key: it rings the bell (by calling ding) but does not signal an error. undefined is used in local keymaps to override a global key binding and make the key "undefined" locally. A local binding of nil would fail to do this because it would not override the global binding.
anything else
If any other type of object is found, the events used so far in the lookup form a complete key, and the object is its binding, but the binding is not executable as a command.
In short, a keymap entry may be a keymap, a command, a keyboard macro, a symbol that leads to one of them, or an indirection or nil. Here is an example of a sparse keymap with two characters bound to commands and one bound to another keymap. This map is the normal value of emacs-lisp-mode-map. Note that 9 is the code for TAB, 127 for DEL, 27 for ESC, 17 for C-q and 24 for C-x.
(keymap (9 . lisp-indent-line)
        (127 . backward-delete-char-untabify)
        (27 keymap (17 . indent-sexp) (24 . eval-defun)))
Functions for Key Lookup

Here are the functions and variables pertaining to key lookup.

Function: lookup-key keymap key &optional accept-defaults
This function returns the definition of key in keymap. All the other functions described in this chapter that look up keys use lookup-key. Here are examples:
(lookup-key (current-global-map) "\C-x\C-f")
    => find-file
(lookup-key (current-global-map) "\C-x\C-f12345")
    => 2
If the string or vector key is not a valid key sequence according to the prefix keys specified in keymap, it must be "too long" and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of key that compose a complete key.

If accept-defaults is non-nil, then lookup-key considers default bindings as well as bindings for the specific events in key. Otherwise, lookup-key reports only bindings for the specific sequence key, ignoring default bindings except when you explicitly ask about them. (To do this, supply t as an element of key; see section Format of Keymaps.)

If key contains a meta character, that character is implicitly replaced by a two-character sequence: the value of meta-prefix-char, followed by the corresponding non-meta character. Thus, the first example below is handled by conversion into the second example.
(lookup-key (current-global-map) "\M-f")
    => forward-word
(lookup-key (current-global-map) "\ef")
    => forward-word
Unlike read-key-sequence, this function does not modify the specified events in ways that discard information (see section Key Sequence Input). In particular, it does not convert letters to lower case and it does not change drag events to clicks.

Command: undefined
Used in keymaps to undefine keys. It calls ding, but does not cause an error.

Function: key-binding key &optional accept-defaults
This function returns the binding for key in the current keymaps, trying all the active keymaps. The result is nil if key is undefined in the keymaps.

The argument accept-defaults controls checking for default bindings, as in lookup-key (above).

An error is signaled if key is not a string or a vector.
(key-binding "\C-x\C-f")
    => find-file
Function: local-key-binding key &optional accept-defaults
This function returns the binding for key in the current local keymap, or nil if it is undefined there.

The argument accept-defaults controls checking for default bindings, as in lookup-key (above).

Function: global-key-binding key &optional accept-defaults
This function returns the binding for command key in the current global keymap, or nil if it is undefined there.

The argument accept-defaults controls checking for default bindings, as in lookup-key (above).

Function: minor-mode-key-binding key &optional accept-defaults
This function returns a list of all the active minor mode bindings of key. More precisely, it returns an alist of pairs (modename . binding), where modename is the variable that enables the minor mode, and binding is key's binding in that mode. If key has no minor-mode bindings, the value is nil.

If the first binding found is not a prefix definition (a keymap or a symbol defined as a keymap), all subsequent bindings from other minor modes are omitted, since they would be completely shadowed. Similarly, the list omits non-prefix bindings that follow prefix bindings.

The argument accept-defaults controls checking for default bindings, as in lookup-key (above).

Variable: meta-prefix-char
This variable is the meta-prefix character code. It is used when translating a meta character to a two-character sequence so it can be looked up in a keymap. For useful results, the value should be a prefix event (see section Prefix Keys). The default value is 27, which is the ASCII code for ESC.

As long as the value of meta-prefix-char remains 27, key lookup translates M-b into ESC b, which is normally defined as the backward-word command. However, if you set meta-prefix-char to 24, the code for C-x, then Emacs will translate M-b into C-x b, whose standard binding is the switch-to-buffer command. Here is an illustration:
meta-prefix-char                    ; The default value.
     => 27
(key-binding "\M-b")
     => backward-word
?\C-x                               ; The print representation
     => 24                          ;   of a character.
(setq meta-prefix-char 24)
     => 24
(key-binding "\M-b")
     => switch-to-buffer            ; Now, typing M-b is
                                    ;   like typing C-x b.

(setq meta-prefix-char 27)          ; Avoid confusion!
     => 27                          ; Restore the default value!
Changing Key Bindings

The way to rebind a key is to change its entry in a keymap. If you change a binding in the global keymap, the change is effective in all buffers (though it has no direct effect in buffers that shadow the global binding with a local one). If you change the current buffer's local map, that usually affects all buffers using the same major mode. The global-set-key and local-set-key functions are convenient interfaces for these operations (see section Commands for Binding Keys). You can also use define-key, a more general function; then you must specify explicitly the map to change.

In writing the key sequence to rebind, it is good to use the special escape sequences for control and meta characters (see section String Type). The syntax `\C-' means that the following character is a control character and `\M-' means that the following character is a meta character. Thus, the string "\M-x" is read as containing a single M-x, "\C-f" is read as containing a single C-f, and "\M-\C-x" and "\C-\M-x" are both read as containing a single C-M-x. You can also use this escape syntax in vectors, as well as others that aren't allowed in strings; one example is `[?\C-\H-x home]'. See section Character Type.

The key definition and lookup functions accept an alternate syntax for event types in a key sequence that is a vector: you can use a list containing modifier names plus one base event (a character or function key name). For example, (control ?a) is equivalent to ?\C-a and (hyper control left) is equivalent to C-H-left. One advantage of such lists is that the precise numeric codes for the modifier bits don't appear in compiled files.

For the functions below, an error is signaled if keymap is not a keymap or if key is not a string or vector representing a key sequence. You can use event types (symbols) as shorthand for events that are lists.

Function: define-key keymap key binding
This function sets the binding for key in keymap. (If key is more than one event long, the change is actually made in another keymap reached from keymap.) The argument binding can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see section Key Lookup.) The value returned by define-key is binding.

Every prefix of key must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of key is undefined, then define-key defines it as a prefix key so that the rest of key can be defined as specified.

If there was previously no binding for key in keymap, the new binding is added at the beginning of keymap. The order of bindings in a keymap makes no difference in most cases, but it does matter for menu keymaps (see section Menu Keymaps).

Here is an example that creates a sparse keymap and makes a number of bindings in it:
(setq map (make-sparse-keymap))
    => (keymap)
(define-key map "\C-f" 'forward-char)
    => forward-char
map
    => (keymap (6 . forward-char))

;; Build sparse submap for C-x and bind f in that.
(define-key map "\C-xf" 'forward-word)
    => forward-word
map
=> (keymap
    (24 keymap                ; C-x
        (102 . forward-word)) ;      f
    (6 . forward-char))       ; C-f

;; Bind C-p to the ctl-x-map.
(define-key map "\C-p" ctl-x-map)
;; ctl-x-map
=> [nil ... find-file ... backward-kill-sentence]

;; Bind C-f to foo in the ctl-x-map.
(define-key map "\C-p\C-f" 'foo)
=> 'foo
map
=> (keymap     ; Note foo in ctl-x-map.
    (16 keymap [nil ... foo ... backward-kill-sentence])
    (24 keymap
        (102 . forward-word))
    (6 . forward-char))
Note that storing a new binding for C-p C-f actually works by changing an entry in ctl-x-map, and this has the effect of changing the bindings of both C-p C-f and C-x C-f in the default global map.

Function: substitute-key-definition olddef newdef keymap &optional oldmap
This function replaces olddef with newdef for any keys in keymap that were bound to olddef. In other words, olddef is replaced with newdef wherever it appears. The function returns nil.

For example, this redefines C-x C-f, if you do it in an Emacs with standard bindings:
(substitute-key-definition
 'find-file 'find-file-read-only (current-global-map))
If oldmap is non-nil, then its bindings determine which keys to rebind. The rebindings still happen in keymap, not in oldmap. Thus, you can change one map under the control of the bindings in another. For example,
(substitute-key-definition
  'delete-backward-char 'my-funny-delete
  my-map global-map)
puts the special deletion command in my-map for whichever keys are globally bound to the standard deletion command.

Here is an example showing a keymap before and after substitution:
(setq map '(keymap
            (?1 . olddef-1)
            (?2 . olddef-2)
            (?3 . olddef-1)))
=> (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))

(substitute-key-definition 'olddef-1 'newdef map)
=> nil
map
=> (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
Function: suppress-keymap keymap &optional nodigits
This function changes the contents of the full keymap keymap by making all the printing characters undefined. More precisely, it binds them to the command undefined. This makes ordinary insertion of text impossible. suppress-keymap returns nil.

If nodigits is nil, then suppress-keymap defines digits to run digit-argument, and - to run negative-argument. Otherwise it makes them undefined like the rest of the printing characters.

The suppress-keymap function does not make it impossible to modify a buffer, as it does not suppress commands such as yank and quoted-insert. To prevent any modification of a buffer, make it read-only (see section Read-Only Buffers).

Since this function modifies keymap, you would normally use it on a newly created keymap. Operating on an existing keymap that is used for some other purpose is likely to cause trouble; for example, suppressing global-map would make it impossible to use most of Emacs.

Most often, suppress-keymap is used to initialize local keymaps of modes such as Rmail and Dired where insertion of text is not desirable and the buffer is read-only. Here is an example taken from the file `emacs/lisp/dired.el', showing how the local keymap for Dired mode is set up:
(setq dired-mode-map (make-keymap))
(suppress-keymap dired-mode-map)
(define-key dired-mode-map "r" 'dired-rename-file)
(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
(define-key dired-mode-map "d" 'dired-flag-file-deleted)
(define-key dired-mode-map "v" 'dired-view-file)
(define-key dired-mode-map "e" 'dired-find-file)
(define-key dired-mode-map "f" 'dired-find-file)
...
Commands for Binding Keys

This section describes some convenient interactive interfaces for changing key bindings. They work by calling define-key.

People often use global-set-key in their `.emacs' file for simple customization. For example,
(global-set-key "\C-x\C-\\" 'next-line)
or
(global-set-key [?\C-x ?\C-\\] 'next-line)
or
(global-set-key [(control ?x) (control ?\\)] 'next-line)
redefines C-x C-\ to move down a line.
(global-set-key [M-mouse-1] 'mouse-set-point)
redefines the first (leftmost) mouse button, typed with the Meta key, to set point where you click.

Command: global-set-key key definition
This function sets the binding of key in the current global map to definition.
(global-set-key key definition)
==
(define-key (current-global-map) key definition)
Command: global-unset-key key
This function removes the binding of key from the current global map.

One use of this function is in preparation for defining a longer key that uses key as a prefix--which would not be allowed if key has a non-prefix binding. For example:
(global-unset-key "\C-l")
    => nil
(global-set-key "\C-l\C-l" 'redraw-display)
    => nil
This function is implemented simply using define-key:
(global-unset-key key)
==
(define-key (current-global-map) key nil)
Command: local-set-key key definition
This function sets the binding of key in the current local keymap to definition.
(local-set-key key definition)
==
(define-key (current-local-map) key definition)
Command: local-unset-key key
This function removes the binding of key from the current local map.
(local-unset-key key)
==
(define-key (current-local-map) key nil)
Scanning Keymaps

This section describes functions used to scan all the current keymaps for the sake of printing help information.

Function: accessible-keymaps keymap &optional prefix
This function returns a list of all the keymaps that can be reached (via zero or more prefix keys) from keymap. The value is an association list with elements of the form (key . map), where key is a prefix key whose definition in keymap is map.

The elements of the alist are ordered so that the key increases in length. The first element is always ("" . keymap), because the specified keymap is accessible from itself with a prefix of no events.

If prefix is given, it should be a prefix key sequence; then accessible-keymaps includes only the submaps whose prefixes start with prefix. These elements look just as they do in the value of (accessible-keymaps); the only difference is that some elements are omitted.

In the example below, the returned alist indicates that the key ESC, which is displayed as `^[', is a prefix key whose definition is the sparse keymap (keymap (83 . center-paragraph) (115 . foo)).
(accessible-keymaps (current-local-map))
=>(("" keymap
      (27 keymap   ; Note this keymap for ESC is repeated below.
          (83 . center-paragraph)
          (115 . center-line))
      (9 . tab-to-tab-stop))

   ("^[" keymap
    (83 . center-paragraph)
    (115 . foo)))
In the following example, C-h is a prefix key that uses a sparse keymap starting with (keymap (118 . describe-variable)...). Another prefix, C-x 4, uses a keymap which is also the value of the variable ctl-x-4-map. The event mode-line is one of several dummy events used as prefixes for mouse actions in special parts of a window.
(accessible-keymaps (current-global-map))
=> (("" keymap [set-mark-command beginning-of-line ...
                   delete-backward-char])
    ("^H" keymap (118 . describe-variable) ...
     (8 . help-for-help))
    ("^X" keymap [x-flush-mouse-queue ...
     backward-kill-sentence])
    ("^[" keymap [mark-sexp backward-sexp ...
     backward-kill-word])
    ("^X4" keymap (15 . display-buffer) ...)
    ([mode-line] keymap
     (S-mouse-2 . mouse-split-window-horizontally) ...))
These are not all the keymaps you would see in actuality.

Function: where-is-internal command &optional keymap firstonly noindirect
This function is a subroutine used by the where-is command (see section `Help' in The GNU Emacs Manual). It returns a list of key sequences (of any length) that are bound to command in a set of keymaps.

The argument command can be any object; it is compared with all keymap entries using eq.

If keymap is nil, then the maps used are the current active keymaps, disregarding overriding-local-map (that is, pretending its value is nil). If keymap is non-nil, then the maps searched are keymap and the global keymap.

Usually it's best to use overriding-local-map as the expression for keymap. Then where-is-internal searches precisely the keymaps that are active. To search only the global map, pass (keymap) (an empty keymap) as keymap.

If firstonly is non-ascii, then the value is a single string representing the first key sequence found, rather than a list of all possible key sequences. If firstonly is t, then the value is the first key sequence, except that key sequences consisting entirely of ASCII characters (or meta variants of ASCII characters) are preferred to all other key sequences.

If noindirect is non-nil, where-is-internal doesn't follow indirect keymap bindings. This makes it possible to search for an indirect definition itself.
(where-is-internal 'describe-function)
    => ("\^hf" "\^hd")
Command: describe-bindings &optional prefix
This function creates a listing of all current key bindings, and displays it in a buffer named `*Help*'. The text is grouped by modes--minor modes first, then the major mode, then global bindings.

If prefix is non-nil, it should be a prefix key; then the listing includes only keys that start with prefix.

The listing describes meta characters as ESC followed by the corresponding non-meta character.

When several characters with consecutive ASCII codes have the same definition, they are shown together, as `firstchar..lastchar'. In this instance, you need to know the ASCII codes to understand which characters this means. For example, in the default global map, the characters `SPC .. ~' are described by a single line. SPC is ASCII 32, ~ is ASCII 126, and the characters between them include all the normal printing characters, (e.g., letters, digits, punctuation, etc.); all these characters are bound to self-insert-command.

Menu Keymaps

A keymap can define a menu as well as bindings for keyboard keys and mouse button. Menus are usually actuated with the mouse, but they can work with the keyboard also.

Defining Menus

A keymap is suitable for menu use if it has an overall prompt string, which is a string that appears as an element of the keymap. (See section Format of Keymaps.) The string should describe the purpose of the menu. The easiest way to construct a keymap with a prompt string is to specify the string as an argument when you call make-keymap or make-sparse-keymap (see section Creating Keymaps).

The order of items in the menu is the same as the order of bindings in the keymap. Since define-key puts new bindings at the front, you should define the menu items starting at the bottom of the menu and moving to the top, if you care about the order. When you add an item to an existing menu, you can specify its position in the menu using define-key-after (see section Modifying Menus).

Simple Menu Items

The simpler and older way to define a menu keymap binding looks like this:
(item-string . real-binding)
The CAR, item-string, is the string to be displayed in the menu. It should be short--preferably one to three words. It should describe the action of the command it corresponds to.

You can also supply a second string, called the help string, as follows:
(item-string help-string . real-binding)
Currently Emacs does not actually use help-string; it knows only how to ignore help-string in order to extract real-binding. In the future we may use help-string as extended documentation for the menu item, available on request.

As far as define-key is concerned, item-string and help-string are part of the event's binding. However, lookup-key returns just real-binding, and only real-binding is used for executing the key.

If real-binding is nil, then item-string appears in the menu but cannot be selected.

If real-binding is a symbol and has a non-nil menu-enable property, that property is an expression that controls whether the menu item is enabled. Every time the keymap is used to display a menu, Emacs evaluates the expression, and it enables the menu item only if the expression's value is non-nil. When a menu item is disabled, it is displayed in a "fuzzy" fashion, and cannot be selected.

The menu bar does not recalculate which items are enabled every time you look at a menu. This is because the X toolkit requires the whole tree of menus in advance. To force recalculation of the menu bar, call force-mode-line-update (see section Mode Line Format).

You've probably noticed that menu items show the equivalent keyboard key sequence (if any) to invoke the same command. To save time on recalculation, menu display caches this information in a sublist in the binding, like this:
(item-string [help-string] (key-binding-data) . real-binding)
Don't put these sublists in the menu item yourself; menu display calculates them automatically. Don't mention keyboard equivalents in the item strings themselves, since that is redundant.

Extended Menu Items

An extended-format menu item is a more flexible and also cleaner alternative to the simple format. It consists of a list that starts with the symbol menu-item. To define a non-selectable string, the item looks like this:
(menu-item item-name)
where a string consisting of two or more dashes specifies a separator line.

To define a real menu item which can be selected, the extended format item looks like this:
(menu-item item-name real-binding
    . item-property-list)
Here, item-name is an expression which evaluates to the menu item string. Thus, the string need not be a constant. The third element, real-binding, is the command to execute. The tail of the list, item-property-list, has the form of a property list which contains other information. Here is a table of the properties that are supported:

:enable FORM
The result of evaluating form determines whether the item is enabled (non-nil means yes).
:visible FORM
The result of evaluating form determines whether the item should actually appear in the menu (non-nil means yes). If the item does not appear, then the menu is displayed as if this item were not defined at all.
:help help
The value of this property, help, is the extra help string (not currently used by Emacs).
:button (type . selected)
This property provides a way to define radio buttons and toggle buttons. The CAR, type, says which: is should be :toggle or :radio. The CDR, selected, should be a form; the result of evaluating it says whether this button is currently selected. A toggle is a menu item which is labeled as either "on" or "off" according to the value of selected. The command itself should toggle selected, setting it to t if it is nil, and to nil if it is t. Here is how the menu item to toggle the debug-on-error flag is defined:
(menu-item "Debug on Error" toggle-debug-on-error
           :button (:toggle
                    . (and (boundp 'debug-on-error)
                           debug-on-error))
This works because toggle-debug-on-error is defined as a command which toggles the variable debug-on-error. Radio buttons are a group of menu items, in which at any time one and only one is "selected." There should be a variable whose value says which one is selected at any time. The selected form for each radio button in the group should check whether the variable has the right value for selecting that button. Clicking on the button should set the variable so that the button you clicked on becomes selected.
:key-sequence key-sequence
This property specifies which key sequence is likely to be bound to the same command invoked by this menu item. If you specify the right key sequence, that makes preparing the menu for display run much faster. If you specify the wrong key sequence, it has no effect; before Emacs displays key-sequence in the menu, it verifies that key-sequence is really equivalent to this menu item.
:key-sequence nil
This property indicates that there is normally no key binding which is equivalent to this menu item. Using this property saves time in preparing the menu for display, because Emacs does not need to search the keymaps for a keyboard equivalent for this menu item. However, if the user has rebound this item's definition to a key sequence, Emacs ignores the :keys property and finds the keyboard equivalent anyway.
:keys string
This property specifies that string is the string to display as the keyboard equivalent for this menu item. You can use the `\\[...]' documentation construct in string.
:filter filter-fn
This property provides a way to compute the menu item dynamically. The property value filter-fn should be a function of one argument; when it is called, its argument will be real-binding. The function should return the binding to use instead.
Alias Menu Items

Sometimes it is useful to make menu items that use the "same" command but with different enable conditions. The best way to do this in Emacs now is with extended menu items; before that feature existed, it could be done by defining alias commands and using them in menu items. Here's an example that makes two aliases for toggle-read-only and gives them different enable conditions:
(defalias 'make-read-only 'toggle-read-only)
(put 'make-read-only 'menu-enable '(not buffer-read-only))
(defalias 'make-writable 'toggle-read-only)
(put 'make-writable 'menu-enable 'buffer-read-only)
When using aliases in menus, often it is useful to display the equivalent key bindings for the "real" command name, not the aliases (which typically don't have any key bindings except for the menu itself). To request this, give the alias symbol a non-nil menu-alias property. Thus,
(put 'make-read-only 'menu-alias t)
(put 'make-writable 'menu-alias t)
causes menu items for make-read-only and make-writable to show the keyboard bindings for toggle-read-only.

Menus and the Mouse

The usual way to make a menu keymap produce a menu is to make it the definition of a prefix key. (A Lisp program can explicitly pop up a menu and receive the user's choice--see section Pop-Up Menus.)

If the prefix key ends with a mouse event, Emacs handles the menu keymap by popping up a visible menu, so that the user can select a choice with the mouse. When the user clicks on a menu item, the event generated is whatever character or symbol has the binding that brought about that menu item. (A menu item may generate a series of events if the menu has multiple levels or comes from the menu bar.)

It's often best to use a button-down event to trigger the menu. Then the user can select a menu item by releasing the button.

A single keymap can appear as multiple menu panes, if you explicitly arrange for this. The way to do this is to make a keymap for each pane, then create a binding for each of those maps in the main keymap of the menu. Give each of these bindings an item string that starts with `@'. The rest of the item string becomes the name of the pane. See the file `lisp/mouse.el' for an example of this. Any ordinary bindings with `@'-less item strings are grouped into one pane, which appears along with the other panes explicitly created for the submaps.

X toolkit menus don't have panes; instead, they can have submenus. Every nested keymap becomes a submenu, whether the item string starts with `@' or not. In a toolkit version of Emacs, the only thing special about `@' at the beginning of an item string is that the `@' doesn't appear in the menu item.

You can also produce multiple panes or submenus from separate keymaps. The full definition of a prefix key always comes from merging the definitions supplied by the various active keymaps (minor mode, local, and global). When more than one of these keymaps is a menu, each of them makes a separate pane or panes (when Emacs does not use an X-toolkit) or a separate submenu (when using an X-toolkit). See section Active Keymaps.

Menus and the Keyboard

When a prefix key ending with a keyboard event (a character or function key) has a definition that is a menu keymap, the user can use the keyboard to choose a menu item.

Emacs displays the menu alternatives (the item strings of the bindings) in the echo area. If they don't all fit at once, the user can type SPC to see the next line of alternatives. Successive uses of SPC eventually get to the end of the menu and then cycle around to the beginning. (The variable menu-prompt-more-char specifies which character is used for this; SPC is the default.)

When the user has found the desired alternative from the menu, he or she should type the corresponding character--the one whose binding is that alternative.

This way of using menus in an Emacs-like editor was inspired by the Hierarkey system.

Variable: menu-prompt-more-char
This variable specifies the character to use to ask to see the next line of a menu. Its initial value is 32, the code for SPC.

Menu Example

Here is a complete example of defining a menu keymap. It is the definition of the `Print' submenu in the `Tools' menu in the menu bar, and it uses the simple menu item format (see section Simple Menu Items). First we create the keymap, and give it a name:
(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
Next we define the menu items:
(define-key menu-bar-print-menu [ps-print-region]
  '("Postscript Print Region" . ps-print-region-with-faces))
(define-key menu-bar-print-menu [ps-print-buffer]
  '("Postscript Print Buffer" . ps-print-buffer-with-faces))
(define-key menu-bar-print-menu [separator-ps-print]
  '("--"))
(define-key menu-bar-print-menu [print-region]
  '("Print Region" . print-region))
(define-key menu-bar-print-menu [print-buffer]
  '("Print Buffer" . print-buffer))
Note the symbols which the bindings are "made for"; these appear inside square brackets, in the key sequence being defined. In some cases, this symbol is the same as the command name; sometimes it is different. These symbols are treated as "function keys", but they are not real function keys on the keyboard. They do not affect the functioning of the menu itself, but they are "echoed" in the echo area when the user selects from the menu, and they appear in the output of where-is and apropos.

The binding whose definition is ("--") is a separator line. Like a real menu item, the separator has a key symbol, in this case separator-ps-print. If one menu has two separators, they must have two different key symbols.

Here is code to define enable conditions for two of the commands in the menu:
(put 'print-region 'menu-enable 'mark-active)
(put 'ps-print-region-with-faces 'menu-enable 'mark-active)
Here is how we make this menu appear as an item in the parent menu:
(define-key menu-bar-tools-menu [print]
  (cons "Print" menu-bar-print-menu))
Note that this incorporates the submenu keymap, which is the value of the variable menu-bar-print-menu, rather than the symbol menu-bar-print-menu itself. Using that symbol in the parent menu item would be meaningless because menu-bar-print-menu is not a command.

If you wanted to attach the same print menu to a mouse click, you can do it this way:
(define-key global-map [C-S-down-mouse-1]
   menu-bar-print-menu)
We could equally well use an extended menu item (see section Extended Menu Items) for print-region, like this:
(define-key menu-bar-print-menu [print-region]
  '(menu-item "Print Region" print-region
              :enable (mark-active)))
With the extended menu item, the enable condition is specified inside the menu item itself. If we wanted to make this item disappear from the menu entirely when the mark is inactive, we could do it this way:
(define-key menu-bar-print-menu [print-region]
  '(menu-item "Print Region" print-region
              :visible (mark-active)))
The Menu Bar

Most window systems allow each frame to have a menu bar---a permanently displayed menu stretching horizontally across the top of the frame. The items of the menu bar are the subcommands of the fake "function key" menu-bar, as defined by all the active keymaps.

To add an item to the menu bar, invent a fake "function key" of your own (let's call it key), and make a binding for the key sequence [menu-bar key]. Most often, the binding is a menu keymap, so that pressing a button on the menu bar item leads to another menu.

When more than one active keymap defines the same fake function key for the menu bar, the item appears just once. If the user clicks on that menu bar item, it brings up a single, combined menu containing all the subcommands of that item--the global subcommands, the local subcommands, and the minor mode subcommands.

The variable overriding-local-map is normally ignored when determining the menu bar contents. That is, the menu bar is computed from the keymaps that would be active if overriding-local-map were nil. See section Active Keymaps.

In order for a frame to display a menu bar, its menu-bar-lines parameter must be greater than zero. Emacs uses just one line for the menu bar itself; if you specify more than one line, the other lines serve to separate the menu bar from the windows in the frame. We recommend 1 or 2 as the value of menu-bar-lines. See section Window Frame Parameters.

Here's an example of setting up a menu bar item:
(modify-frame-parameters (selected-frame)
                         '((menu-bar-lines . 2)))

;; Make a menu keymap (with a prompt string)
;; and make it the menu bar item's definition.
(define-key global-map [menu-bar words]
  (cons "Words" (make-sparse-keymap "Words")))

;; Define specific subcommands in this menu.
(define-key global-map
  [menu-bar words forward]
  '("Forward word" . forward-word))
(define-key global-map
  [menu-bar words backward]
  '("Backward word" . backward-word))
A local keymap can cancel a menu bar item made by the global keymap by rebinding the same fake function key with undefined as the binding. For example, this is how Dired suppresses the `Edit' menu bar item:
(define-key dired-mode-map [menu-bar edit] 'undefined)
edit is the fake function key used by the global map for the `Edit' menu bar item. The main reason to suppress a global menu bar item is to regain space for mode-specific items.

Variable: menu-bar-final-items
Normally the menu bar shows global items followed by items defined by the local maps.

This variable holds a list of fake function keys for items to display at the end of the menu bar rather than in normal sequence. The default value is (help-menu); thus, the `Help' menu item normally appears at the end of the menu bar, following local menu items.

Variable: menu-bar-update-hook
This normal hook is run whenever the user clicks on the menu bar, before displaying a submenu. You can use it to update submenus whose contents should vary.

Modifying Menus

When you insert a new item in an existing menu, you probably want to put it in a particular place among the menu's existing items. If you use define-key to add the item, it normally goes at the front of the menu. To put it elsewhere in the menu, use define-key-after:

Function: define-key-after map key binding after
Define a binding in map for key, with value binding, just like define-key, but position the binding in map after the binding for the event after. The argument key should be of length one--a vector or string with just one element. But after should be a single event type--a symbol or a character, not a sequence. The new binding goes after the binding for after. If after is t, then the new binding goes last, at the end of the keymap.

Here is an example:
(define-key-after my-menu [drink]
                  '("Drink" . drink-command) 'eat)
makes a binding for the fake function key DRINK and puts it right after the binding for EAT.

Here is how to insert an item called `Work' in the `Signals' menu of Shell mode, after the item break:
(define-key-after
  (lookup-key shell-mode-map [menu-bar signals])
  [work] '("Work" . work-command) 'break)
Major and Minor Modes

A mode is a set of definitions that customize Emacs and can be turned on and off while you edit. There are two varieties of modes: major modes, which are mutually exclusive and used for editing particular kinds of text, and minor modes, which provide features that users can enable individually.

This chapter describes how to write both major and minor modes, how to indicate them in the mode line, and how they run hooks supplied by the user. For related topics such as keymaps and syntax tables, see section Keymaps, and section Syntax Tables.

Major Modes

Major modes specialize Emacs for editing particular kinds of text. Each buffer has only one major mode at a time.

The least specialized major mode is called Fundamental mode. This mode has no mode-specific definitions or variable settings, so each Emacs command behaves in its default manner, and each option is in its default state. All other major modes redefine various keys and options. For example, Lisp Interaction mode provides special key bindings for C-j (eval-print-last-sexp), TAB (lisp-indent-line), and other keys.

When you need to write several editing commands to help you perform a specialized editing task, creating a new major mode is usually a good idea. In practice, writing a major mode is easy (in contrast to writing a minor mode, which is often difficult).

If the new mode is similar to an old one, it is often unwise to modify the old one to serve two purposes, since it may become harder to use and maintain. Instead, copy and rename an existing major mode definition and alter the copy--or define a derived mode (see section Defining Derived Modes). For example, Rmail Edit mode, which is in `emacs/lisp/rmailedit.el', is a major mode that is very similar to Text mode except that it provides three additional commands. Its definition is distinct from that of Text mode, but was derived from it.

Rmail Edit mode offers an example of changing the major mode temporarily for a buffer, so it can be edited in a different way (with ordinary Emacs commands rather than Rmail commands). In such cases, the temporary major mode usually has a command to switch back to the buffer's usual mode (Rmail mode, in this case). You might be tempted to present the temporary redefinitions inside a recursive edit and restore the usual ones when the user exits; but this is a bad idea because it constrains the user's options when it is done in more than one buffer: recursive edits must be exited most-recently-entered first. Using an alternative major mode avoids this limitation. See section Recursive Editing.

The standard GNU Emacs Lisp library directory contains the code for several major modes, in files such as `text-mode.el', `texinfo.el', `lisp-mode.el', `c-mode.el', and `rmail.el'. You can study these libraries to see how modes are written. Text mode is perhaps the simplest major mode aside from Fundamental mode. Rmail mode is a complicated and specialized mode.

Major Mode Conventions

The code for existing major modes follows various coding conventions, including conventions for local keymap and syntax table initialization, global names, and hooks. Please follow these conventions when you define a new major mode:

Define a command whose name ends in `-mode', with no arguments, that switches to the new mode in the current buffer. This command should set up the keymap, syntax table, and buffer-local variables in an existing buffer, without changing the buffer's contents.
Write a documentation string for this command that describes the special commands available in this mode. C-h m (describe-mode) in your mode will display this string. The documentation string may include the special documentation substrings, `\[command]', `\{keymap}', and `\<keymap>', that enable the documentation to adapt automatically to the user's own key bindings. See section Substituting Key Bindings in Documentation.
The major mode command should start by calling kill-all-local-variables. This is what gets rid of the buffer-local variables of the major mode previously in effect.
The major mode command should set the variable major-mode to the major mode command symbol. This is how describe-mode discovers which documentation to print.
The major mode command should set the variable mode-name to the "pretty" name of the mode, as a string. This string appears in the mode line.
Since all global names are in the same name space, all the global variables, constants, and functions that are part of the mode should have names that start with the major mode name (or with an abbreviation of it if the name is long). See section Emacs Lisp Coding Conventions.
The major mode should usually have its own keymap, which is used as the local keymap in all buffers in that mode. The major mode command should call use-local-map to install this local map. See section Active Keymaps, for more information. This keymap should be stored permanently in a global variable named modename-mode-map. Normally the library that defines the mode sets this variable. See section Tips for Defining Variables Robustly, for advice about how to write the code to set up the mode's keymap variable.
The key sequences bound in a major mode keymap should usually start with C-c, followed by a control character, a digit, or {, }, <, >, : or ;. The other punctuation characters are reserved for minor modes, and ordinary letters are reserved for users. It is reasonable for a major mode to rebind a key sequence with a standard meaning, if it implements a command that does "the same job" in a way that fits the major mode better. For example, a major mode for editing a programming language might redefine C-M-a to "move to the beginning of a function" in a way that works better for that language. Major modes such as Dired or Rmail that do not allow self-insertion of text can reasonably redefine letters and other printing characters as editing commands. Dired and Rmail both do this.
The mode may have its own syntax table or may share one with other related modes. If it has its own syntax table, it should store this in a variable named modename-mode-syntax-table. See section Syntax Tables.
If the mode handles a language that has a syntax for comments, it should set the variables that define the comment syntax. See section `Options Controlling Comments' in The GNU Emacs Manual.
The mode may have its own abbrev table or may share one with other related modes. If it has its own abbrev table, it should store this in a variable named modename-mode-abbrev-table. See section Abbrev Tables.
The mode should specify how to do highlighting for Font Lock mode, by setting up a buffer-local value for the variable font-lock-defaults (see section Font Lock Mode).
The mode should specify how Imenu should find the definitions or sections of a buffer, by setting up a buffer-local value for the variable imenu-generic-expression or imenu-create-index-function (see section Imenu).
Use defvar or defcustom to set mode-related variables, so that they are not reinitialized if they already have a value. (Such reinitialization could discard customizations made by the user.)
To make a buffer-local binding for an Emacs customization variable, use make-local-variable in the major mode command, not make-variable-buffer-local. The latter function would make the variable local to every buffer in which it is subsequently set, which would affect buffers that do not use this mode. It is undesirable for a mode to have such global effects. See section Buffer-Local Variables. It's OK to use make-variable-buffer-local, if you wish, for a variable used only within a single Lisp package.
Each major mode should have a mode hook named modename-mode-hook. The major mode command should run that hook, with run-hooks, as the very last thing it does. See section Hooks.
The major mode command may also run the hooks of some more basic modes. For example, indented-text-mode runs text-mode-hook as well as indented-text-mode-hook. It may run these other hooks immediately before the mode's own hook (that is, after everything else), or it may run them earlier.
If something special should be done if the user switches a buffer from this mode to any other major mode, this mode can set up a buffer-local value for change-major-mode-hook (see section Creating and Deleting Buffer-Local Bindings).
If this mode is appropriate only for specially-prepared text, then the major mode command symbol should have a property named mode-class with value special, put on as follows:
(put 'funny-mode 'mode-class 'special)
This tells Emacs that new buffers created while the current buffer has Funny mode should not inherit Funny mode. Modes such as Dired, Rmail, and Buffer List use this feature.
If you want to make the new mode the default for files with certain recognizable names, add an element to auto-mode-alist to select the mode for those file names. If you define the mode command to autoload, you should add this element in the same file that calls autoload. Otherwise, it is sufficient to add the element in the file that contains the mode definition. See section How Emacs Chooses a Major Mode.
In the documentation, you should provide a sample autoload form and an example of how to add to auto-mode-alist, that users can include in their `.emacs' files.
The top-level forms in the file defining the mode should be written so that they may be evaluated more than once without adverse consequences. Even if you never load the file more than once, someone else will.

Major Mode Examples

Text mode is perhaps the simplest mode besides Fundamental mode. Here are excerpts from `text-mode.el' that illustrate many of the conventions listed above:
;; Create mode-specific tables.
(defvar text-mode-syntax-table nil
  "Syntax table used while in text mode.")

(if text-mode-syntax-table
    ()              ; Do not change the table if it is already set up.
  (setq text-mode-syntax-table (make-syntax-table))
  (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
  (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
  (modify-syntax-entry ?' "w   " text-mode-syntax-table))

(defvar text-mode-abbrev-table nil
  "Abbrev table used while in text mode.")
(define-abbrev-table 'text-mode-abbrev-table ())

(defvar text-mode-map nil)   ; Create a mode-specific keymap.

(if text-mode-map
    ()              ; Do not change the keymap if it is already set up.
  (setq text-mode-map (make-sparse-keymap))
  (define-key text-mode-map "\t" 'indent-relative)
  (define-key text-mode-map "\es" 'center-line)
  (define-key text-mode-map "\eS" 'center-paragraph))
Here is the complete major mode function definition for Text mode:
(defun text-mode ()
  "Major mode for editing text intended for humans to read@enddots{}
 Special commands: \\{text-mode-map}
Turning on text-mode runs the hook `text-mode-hook'."
  (interactive)
  (kill-all-local-variables)
  (use-local-map text-mode-map)
  (setq local-abbrev-table text-mode-abbrev-table)
  (set-syntax-table text-mode-syntax-table)
  (make-local-variable 'paragraph-start)
  (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
  (make-local-variable 'paragraph-separate)
  (setq paragraph-separate paragraph-start)
  (setq mode-name "Text")
  (setq major-mode 'text-mode)
  (run-hooks 'text-mode-hook))      ; Finally, this permits the user to
                                    ;   customize the mode with a hook.
The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction mode) have more features than Text mode and the code is correspondingly more complicated. Here are excerpts from `lisp-mode.el' that illustrate how these modes are written.
;; Create mode-specific table variables.
(defvar lisp-mode-syntax-table nil "")
(defvar emacs-lisp-mode-syntax-table nil "")
(defvar lisp-mode-abbrev-table nil "")

(if (not emacs-lisp-mode-syntax-table) ; Do not change the table
                                       ;   if it is already set.
    (let ((i 0))
      (setq emacs-lisp-mode-syntax-table (make-syntax-table))

      ;; Set syntax of chars up to 0 to class of chars that are
      ;;   part of symbol names but not words.
      ;;   (The number 0 is 48 in the ASCII character set.)
      (while (< i ?0)
        (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
        (setq i (1+ i)))
      ...
      ;; Set the syntax for other characters.
      (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
      (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
      ...
      (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
      (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
      ...))
;; Create an abbrev table for lisp-mode.
(define-abbrev-table 'lisp-mode-abbrev-table ())
Much code is shared among the three Lisp modes. The following function sets various variables; it is called by each of the major Lisp mode functions:
(defun lisp-mode-variables (lisp-syntax)
  (cond (lisp-syntax
      (set-syntax-table lisp-mode-syntax-table)))
  (setq local-abbrev-table lisp-mode-abbrev-table)
  ...
Functions such as forward-paragraph use the value of the paragraph-start variable. Since Lisp code is different from ordinary text, the paragraph-start variable needs to be set specially to handle Lisp. Also, comments are indented in a special fashion in Lisp and the Lisp modes need their own mode-specific comment-indent-function. The code to set these variables is the rest of lisp-mode-variables.
  (make-local-variable 'paragraph-start)
  (setq paragraph-start (concat page-delimiter "\\|$" ))
  (make-local-variable 'paragraph-separate)
  (setq paragraph-separate paragraph-start)
  ...
  (make-local-variable 'comment-indent-function)
  (setq comment-indent-function 'lisp-comment-indent))
Each of the different Lisp modes has a slightly different keymap. For example, Lisp mode binds C-c C-z to run-lisp, but the other Lisp modes do not. However, all Lisp modes have some commands in common. The following code sets up the common commands:
(defvar shared-lisp-mode-map ()
  "Keymap for commands shared by all sorts of Lisp modes.")

(if shared-lisp-mode-map
    ()
   (setq shared-lisp-mode-map (make-sparse-keymap))
   (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
   (define-key shared-lisp-mode-map "\177"
               'backward-delete-char-untabify))
And here is the code to set up the keymap for Lisp mode:
(defvar lisp-mode-map ()
  "Keymap for ordinary Lisp mode@enddots{}")

(if lisp-mode-map
    ()
  (setq lisp-mode-map (make-sparse-keymap))
  (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
  (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
  (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
Finally, here is the complete major mode function definition for Emacs Lisp mode.
(defun lisp-mode ()
  "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
Commands:
Delete converts tabs to spaces as it moves back.
Blank lines separate paragraphs.  Semicolons start comments.
\\{lisp-mode-map}
Note that `run-lisp' may be used either to start an inferior Lisp job
or to switch back to an existing one.

Entry to this mode calls the value of `lisp-mode-hook'
if that value is non-nil."
  (interactive)
  (kill-all-local-variables)
  (use-local-map lisp-mode-map)          ; Select the mode's keymap.
  (setq major-mode 'lisp-mode)           ; This is how describe-mode
                                         ;   finds out what to describe.
  (setq mode-name "Lisp")                ; This goes into the mode line.
  (lisp-mode-variables t)                ; This defines various variables.
  (setq imenu-case-fold-search t)
  (set-syntax-table lisp-mode-syntax-table)
  (run-hooks 'lisp-mode-hook))           ; This permits the user to use a
                                         ;   hook to customize the mode.
How Emacs Chooses a Major Mode

Based on information in the file name or in the file itself, Emacs automatically selects a major mode for the new buffer when a file is visited. It also processes local variables specified in the file text.

Command: fundamental-mode
Fundamental mode is a major mode that is not specialized for anything in particular. Other major modes are defined in effect by comparison with this one--their definitions say what to change, starting from Fundamental mode. The fundamental-mode function does not run any hooks; you're not supposed to customize it. (If you want Emacs to behave differently in Fundamental mode, change the global state of Emacs.)

Command: normal-mode &optional find-file
This function establishes the proper major mode and buffer-local variable bindings for the current buffer. First it calls set-auto-mode, then it runs hack-local-variables to parse, and bind or evaluate as appropriate, the file's local variables.

If the find-file argument to normal-mode is non-nil, normal-mode assumes that the find-file function is calling it. In this case, it may process a local variables list at the end of the file and in the `-*-' line. The variable enable-local-variables controls whether to do so. See section `Local Variables in Files' in The GNU Emacs Manual, for the syntax of the local variables section of a file.

If you run normal-mode interactively, the argument find-file is normally nil. In this case, normal-mode unconditionally processes any local variables list.

normal-mode uses condition-case around the call to the major mode function, so errors are caught and reported as a `File mode specification error', followed by the original error message.

User Option: enable-local-variables
This variable controls processing of local variables lists in files being visited. A value of t means process the local variables lists unconditionally; nil means ignore them; anything else means ask the user what to do for each file. The default value is t.

Variable: ignored-local-variables
This variable holds a list of variables that should not be set by a file's local variables list. Any value specified for one of these variables is ignored.

In addition to this list, any variable whose name has a non-nil risky-local-variable property is also ignored.

User Option: enable-local-eval
This variable controls processing of `Eval:' in local variables lists in files being visited. A value of t means process them unconditionally; nil means ignore them; anything else means ask the user what to do for each file. The default value is maybe.

Function: set-auto-mode
This function selects the major mode that is appropriate for the current buffer. It may base its decision on the value of the `-*-' line, on the visited file name (using auto-mode-alist), on the `#!' line (using interpreter-mode-alist), or on the file's local variables list. However, this function does not look for the `mode:' local variable near the end of a file; the hack-local-variables function does that. See section `How Major Modes are Chosen' in The GNU Emacs Manual.

User Option: default-major-mode
This variable holds the default major mode for new buffers. The standard value is fundamental-mode.

If the value of default-major-mode is nil, Emacs uses the (previously) current buffer's major mode for the major mode of a new buffer. However, if that major mode symbol has a mode-class property with value special, then it is not used for new buffers; Fundamental mode is used instead. The modes that have this property are those such as Dired and Rmail that are useful only with text that has been specially prepared.

Function: set-buffer-major-mode buffer
This function sets the major mode of buffer to the value of default-major-mode. If that variable is nil, it uses the current buffer's major mode (if that is suitable).

The low-level primitives for creating buffers do not use this function, but medium-level commands such as switch-to-buffer and find-file-noselect use it whenever they create buffers.

Variable: initial-major-mode
The value of this variable determines the major mode of the initial `*scratch*' buffer. The value should be a symbol that is a major mode command. The default value is lisp-interaction-mode.

Variable: auto-mode-alist
This variable contains an association list of file name patterns (regular expressions; see section Regular Expressions) and corresponding major mode commands. Usually, the file name patterns test for suffixes, such as `.el' and `.c', but this need not be the case. An ordinary element of the alist looks like (regexp . mode-function).

For example,
(("\\`/tmp/fol/" . text-mode)
 ("\\.texinfo\\'" . texinfo-mode)
 ("\\.texi\\'" . texinfo-mode)
 ("\\.el\\'" . emacs-lisp-mode)
 ("\\.c\\'" . c-mode)
 ("\\.h\\'" . c-mode)
 ...)
When you visit a file whose expanded file name (see section Functions that Expand Filenames) matches a regexp, set-auto-mode calls the corresponding mode-function. This feature enables Emacs to select the proper major mode for most files.

If an element of auto-mode-alist has the form (regexp function t), then after calling function, Emacs searches auto-mode-alist again for a match against the portion of the file name that did not match before. This feature is useful for uncompression packages: an entry of the form ("\\.gz\\'" function t) can uncompress the file and then put the uncompressed file in the proper mode according to the name sans `.gz'.

Here is an example of how to prepend several pattern pairs to auto-mode-alist. (You might use this sort of expression in your `.emacs' file.)
(setq auto-mode-alist
  (append
   ;; File name (within directory) starts with a dot.
   '(("/\\.[^/]*\\'" . fundamental-mode)
     ;; File name has no dot.
     ("[^\\./]*\\'" . fundamental-mode)
     ;; File name ends in `.C'.
     ("\\.C\\'" . c++-mode))
   auto-mode-alist))
Variable: interpreter-mode-alist
This variable specifies major modes to use for scripts that specify a command interpreter in an `#!' line. Its value is a list of elements of the form (interpreter . mode); for example, ("perl" . perl-mode) is one element present by default. The element says to use mode mode if the file specifies an interpreter which matches interpreter. The value of interpreter is actually a regular expression.

This variable is applicable only when the auto-mode-alist does not indicate which major mode to use.

Function: hack-local-variables &optional force
This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer.

The handling of enable-local-variables documented for normal-mode actually takes place here. The argument force usually comes from the argument find-file given to normal-mode.

Getting Help about a Major Mode

The describe-mode function is used to provide information about major modes. It is normally called with C-h m. The describe-mode function uses the value of major-mode, which is why every major mode function needs to set the major-mode variable.

Command: describe-mode
This function displays the documentation of the current major mode.

The describe-mode function calls the documentation function using the value of major-mode as an argument. Thus, it displays the documentation string of the major mode function. (See section Access to Documentation Strings.)

Variable: major-mode
This variable holds the symbol for the current buffer's major mode. This symbol should have a function definition that is the command to switch to that major mode. The describe-mode function uses the documentation string of the function as the documentation of the major mode.

Defining Derived Modes

It's often useful to define a new major mode in terms of an existing one. An easy way to do this is to use define-derived-mode.

Macro: define-derived-mode variant parent name docstring body...
This construct defines variant as a major mode command, using name as the string form of the mode name.

The new command variant is defined to call the function parent, then override certain aspects of that parent mode:

The new mode has its own keymap, named variant-map. define-derived-mode initializes this map to inherit from parent-map, if it is not already set.
The new mode has its own syntax table, kept in the variable variant-syntax-table. define-derived-mode initializes this variable by copying parent-syntax-table, if it is not already set.
The new mode has its own abbrev table, kept in the variable variant-abbrev-table. define-derived-mode initializes this variable by copying parent-abbrev-table, if it is not already set.
The new mode has its own mode hook, variant-hook, which it runs in standard fashion as the very last thing that it does. (The new mode also runs the mode hook of parent as part of calling parent.)

In addition, you can specify how to override other aspects of parent with body. The command variant evaluates the forms in body after setting up all its usual overrides, just before running variant-hook.

The argument docstring specifies the documentation string for the new mode. If you omit docstring, define-derived-mode generates a documentation string.

Here is a hypothetical example:
(define-derived-mode hypertext-mode
  text-mode "Hypertext"
  "Major mode for hypertext.
\\{hypertext-mode-map}"
  (setq case-fold-search nil))

(define-key hypertext-mode-map
  [down-mouse-3] 'do-hyper-link)
Minor Modes

A minor mode provides features that users may enable or disable independently of the choice of major mode. Minor modes can be enabled individually or in combination. Minor modes would be better named "generally available, optional feature modes," except that such a name would be unwieldy.

A minor mode is not usually a modification of single major mode. For example, Auto Fill mode works with any major mode that permits text insertion. To be general, a minor mode must be effectively independent of the things major modes do.

A minor mode is often much more difficult to implement than a major mode. One reason is that you should be able to activate and deactivate minor modes in any order. A minor mode should be able to have its desired effect regardless of the major mode and regardless of the other minor modes in effect.

Often the biggest problem in implementing a minor mode is finding a way to insert the necessary hook into the rest of Emacs. Minor mode keymaps make this easier than it used to be.

Conventions for Writing Minor Modes

There are conventions for writing minor modes just as there are for major modes. Several of the major mode conventions apply to minor modes as well: those regarding the name of the mode initialization function, the names of global symbols, and the use of keymaps and other tables.

In addition, there are several conventions that are specific to minor modes.

Make a variable whose name ends in `-mode' to control the minor mode. We call this the mode variable. The minor mode command should set this variable (nil to disable; anything else to enable). If it is possible, implement the mode so that setting the variable automatically enables or disables the mode. Then the minor mode command does not need to do anything except set the variable. This variable is used in conjunction with the minor-mode-alist to display the minor mode name in the mode line. It can also enable or disable a minor mode keymap. Individual commands or hooks can also check the variable's value. If you want the minor mode to be enabled separately in each buffer, make the variable buffer-local.
Define a command whose name is the same as the mode variable. Its job is to enable and disable the mode by setting the variable. The command should accept one optional argument. If the argument is nil, it should toggle the mode (turn it on if it is off, and off if it is on). Otherwise, it should turn the mode on if the argument is a positive integer, a symbol other than nil or -, or a list whose CAR is such an integer or symbol; it should turn the mode off otherwise. Here is an example taken from the definition of transient-mark-mode. It shows the use of transient-mark-mode as a variable that enables or disables the mode's behavior, and also shows the proper way to toggle, enable or disable the minor mode based on the raw prefix argument value.
(setq transient-mark-mode
      (if (null arg) (not transient-mark-mode)
        (> (prefix-numeric-value arg) 0)))
Add an element to minor-mode-alist for each minor mode (see section Variables Used in the Mode Line), if you want to indicate the minor mode in the mode line. This element should be a list of the following form:
(mode-variable string)
Here mode-variable is the variable that controls enabling of the minor mode, and string is a short string, starting with a space, to represent the mode in the mode line. These strings must be short so that there is room for several of them at once. When you add an element to minor-mode-alist, use assq to check for an existing element, to avoid duplication. For example:
(or (assq 'leif-mode minor-mode-alist)
    (setq minor-mode-alist
          (cons '(leif-mode " Leif") minor-mode-alist)))
You can also use add-to-list to add an element to this list just once (see section How to Alter a Variable Value).

Keymaps and Minor Modes

Each minor mode can have its own keymap, which is active when the mode is enabled. To set up a keymap for a minor mode, add an element to the alist minor-mode-map-alist. See section Active Keymaps.

One use of minor mode keymaps is to modify the behavior of certain self-inserting characters so that they do something else as well as self-insert. In general, this is the only way to do that, since the facilities for customizing self-insert-command are limited to special cases (designed for abbrevs and Auto Fill mode). (Do not try substituting your own definition of self-insert-command for the standard one. The editor command loop handles this function specially.)

The key sequences bound in a minor mode should consist of C-c followed by a punctuation character other than {, }, <, >, : or ;. (Those few punctuation characters are reserved for major modes.)

Easy-Mmode

The easy-mmode package provides a convenient way of implementing a minor mode; with it, you can specify all about a simple minor mode in one self-contained definition.

Macro: easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
This macro defines a new minor mode whose name is mode (a symbol).

This macro defines a command named mode which toggles the minor mode, and has doc as its documentation string.

It also defines a variable named mode, which is set to t or nil by enabling or disabling the mode. The variable is initialized to init-value.

The string mode-indicator says what to display in the mode line when the mode is enabled; if it is nil, the mode is not displayed in the mode line.

The optional argument keymap specifies the keymap for the minor mode. It can be a variable name, whose value is the keymap, or it can be an alist specifying bindings in this form:
(key-sequence . definition)
Here is an example of using easy-mmode-define-minor-mode:
(easy-mmode-define-minor-mode hungry-mode
  "Toggle Hungry mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.

When Hungry mode is enabled, the control delete key
gobbles all preceding whitespace except the last.
See the command \\[hungry-electric-delete]."
 ;; The initial value.
 nil
 ;; The indicator for the mode line.
 " Hungry"
 ;; The minor mode bindings.
 '(("\C-\^?" . hungry-electric-delete)
   ("\C-\M-\^?"
    . (lambda ()
        (interactive)
        (hungry-electric-delete t)))))
This defines a minor mode named "Hungry mode", a command named hungry-mode to toggle it, a variable named hungry-mode which indicates whether the mode is enabled, and a variable named hungry-mode-map which holds the keymap that is active when the mode is enabled. It initializes the keymap with key bindings for C-DEL and C-M-DEL.

Mode Line Format

Each Emacs window (aside from minibuffer windows) includes a mode line, which displays status information about the buffer displayed in the window. The mode line contains information about the buffer, such as its name, associated file, depth of recursive editing, and the major and minor modes.

This section describes how the contents of the mode line are controlled. We include it in this chapter because much of the information displayed in the mode line relates to the enabled major and minor modes.

mode-line-format is a buffer-local variable that holds a template used to display the mode line of the current buffer. All windows for the same buffer use the same mode-line-format and their mode lines appear the same (except for scrolling percentages, and line and column numbers).

The mode line of a window is normally updated whenever a different buffer is shown in the window, or when the buffer's modified-status changes from nil to t or vice-versa. If you modify any of the variables referenced by mode-line-format (see section Variables Used in the Mode Line), or any other variables and data structures that affect how text is displayed (see section Emacs Display), you may want to force an update of the mode line so as to display the new information or display it in the new way.

Function: force-mode-line-update
Force redisplay of the current buffer's mode line.

The mode line is usually displayed in inverse video; see mode-line-inverse-video in section Inverse Video.

The Data Structure of the Mode Line

The mode line contents are controlled by a data structure of lists, strings, symbols, and numbers kept in the buffer-local variable mode-line-format. The data structure is called a mode line construct, and it is built in recursive fashion out of simpler mode line constructs. The same data structure is used for constructing frame titles (see section Frame Titles).

Variable: mode-line-format
The value of this variable is a mode line construct with overall responsibility for the mode line format. The value of this variable controls which other variables are used to form the mode line text, and where they appear.

A mode line construct may be as simple as a fixed string of text, but it usually specifies how to use other variables to construct the text. Many of these variables are themselves defined to have mode line constructs as their values.

The default value of mode-line-format incorporates the values of variables such as mode-name and minor-mode-alist. Because of this, very few modes need to alter mode-line-format itself. For most purposes, it is sufficient to alter some of the variables that mode-line-format refers to.

A mode line construct may be a list, a symbol, or a string. If the value is a list, each element may be a list, a symbol, or a string.

string
A string as a mode line construct is displayed verbatim in the mode line except for %-constructs. Decimal digits after the `%' specify the field width for space filling on the right (i.e., the data is left justified). See section %-Constructs in the Mode Line.
symbol
A symbol as a mode line construct stands for its value. The value of symbol is used as a mode line construct, in place of symbol. However, the symbols t and nil are ignored; so is any symbol whose value is void. There is one exception: if the value of symbol is a string, it is displayed verbatim: the %-constructs are not recognized.
(string rest...) or (list rest...)
A list whose first element is a string or list means to process all the elements recursively and concatenate the results. This is the most common form of mode line construct.
(symbol then else)
A list whose first element is a symbol is a conditional. Its meaning depends on the value of symbol. If the value is non-nil, the second element, then, is processed recursively as a mode line element. But if the value of symbol is nil, the third element, else, is processed recursively. You may omit else; then the mode line element displays nothing if the value of symbol is nil.
(width rest...)
A list whose first element is an integer specifies truncation or padding of the results of rest. The remaining elements rest are processed recursively as mode line constructs and concatenated together. Then the result is space filled (if width is positive) or truncated (to -width columns, if width is negative) on the right. For example, the usual way to show what percentage of a buffer is above the top of the window is to use a list like this: (-3 "%p").
If you do alter mode-line-format itself, the new value should use the same variables that appear in the default value (see section Variables Used in the Mode Line), rather than duplicating their contents or displaying the information in another fashion. This way, customizations made by the user or by Lisp programs (such as display-time and major modes) via changes to those variables remain effective.

Here is an example of a mode-line-format that might be useful for shell-mode, since it contains the host name and default directory.
(setq mode-line-format
  (list "-"
   'mode-line-mule-info
   'mode-line-modified
   'mode-line-frame-identification
   "%b--"
   ;; Note that this is evaluated while making the list.
   ;; It makes a mode line construct which is just a string.
   (getenv "HOST")
   ":"
   'default-directory
   "   "
   'global-mode-string
   "   %[("
   'mode-name
   'mode-line-process
   'minor-mode-alist
   "%n"
   ")%]--"
   '(which-func-mode ("" which-func-format "--"))
   '(line-number-mode "L%l--")
   '(column-number-mode "C%c--")
   '(-3 . "%p")
   "-%-"))
(The variables line-number-mode, column-number-mode and which-func-mode enable particular minor modes; as usual, these variable names are also the minor mode command names.)

Variables Used in the Mode Line

This section describes variables incorporated by the standard value of mode-line-format into the text of the mode line. There is nothing inherently special about these variables; any other variables could have the same effects on the mode line if mode-line-format were changed to use them.

Variable: mode-line-mule-info
This variable holds the value of the mode-line construct that displays information about the language environment, buffer coding system, and current input method. See section Non-ASCII Characters.

Variable: mode-line-modified
This variable holds the value of the mode-line construct that displays whether the current buffer is modified.

The default value of mode-line-modified is ("%1*%1+"). This means that the mode line displays `**' if the buffer is modified, `--' if the buffer is not modified, `%%' if the buffer is read only, and `%*' if the buffer is read only and modified.

Changing this variable does not force an update of the mode line.

Variable: mode-line-frame-identification
This variable identifies the current frame. The default value is " " if you are using a window system which can show multiple frames, or "-%F " on an ordinary terminal which shows only one frame at a time.

Variable: mode-line-buffer-identification
This variable identifies the buffer being displayed in the window. Its default value is ("%12b"), which displays the buffer name, padded with spaces to at least 12 columns.

Variable: global-mode-string
This variable holds a mode line spec that appears in the mode line by default, just after the buffer name. The command display-time sets global-mode-string to refer to the variable display-time-string, which holds a string containing the time and load information.

The `%M' construct substitutes the value of global-mode-string, but that is obsolete, since the variable is included in the mode line from mode-line-format.

Variable: mode-name
This buffer-local variable holds the "pretty" name of the current buffer's major mode. Each major mode should set this variable so that the mode name will appear in the mode line.

Variable: minor-mode-alist
This variable holds an association list whose elements specify how the mode line should indicate that a minor mode is active. Each element of the minor-mode-alist should be a two-element list:
(minor-mode-variable mode-line-string)
More generally, mode-line-string can be any mode line spec. It appears in the mode line when the value of minor-mode-variable is non-nil, and not otherwise. These strings should begin with spaces so that they don't run together. Conventionally, the minor-mode-variable for a specific mode is set to a non-nil value when that minor mode is activated.

The default value of minor-mode-alist is:
minor-mode-alist
=> ((vc-mode vc-mode)
    (abbrev-mode " Abbrev")
    (overwrite-mode overwrite-mode)
    (auto-fill-function " Fill")
    (defining-kbd-macro " Def")
    (isearch-mode isearch-mode))
minor-mode-alist itself is not buffer-local. Each variable mentioned in the alist should be buffer-local if its minor mode can be enabled separately in each buffer.

Variable: mode-line-process
This buffer-local variable contains the mode line information on process status in modes used for communicating with subprocesses. It is displayed immediately following the major mode name, with no intervening space. For example, its value in the `*shell*' buffer is (":%s"), which allows the shell to display its status along with the major mode as: `(Shell: run)'. Normally this variable is nil.

Variable: default-mode-line-format
This variable holds the default mode-line-format for buffers that do not override it. This is the same as (default-value 'mode-line-format).

The default value of default-mode-line-format is this list:
("-"
 mode-line-mule-info
 mode-line-modified
 mode-line-frame-identification
 mode-line-buffer-identification
 "   "
 global-mode-string
 "   %[("
 mode-name
 mode-line-process
 minor-mode-alist
 "%n"
 ")%]--"
 (which-func-mode ("" which-func-format "--"))
 (line-number-mode "L%l--")
 (column-number-mode "C%c--")
 (-3 . "%p")
 "-%-")
Variable: vc-mode
The variable vc-mode, buffer-local in each buffer, records whether the buffer's visited file is maintained with version control, and, if so, which kind. Its value is nil for no version control, or a string that appears in the mode line.

%-Constructs in the Mode Line

The following table lists the recognized %-constructs and what they mean. In any construct except `%%', you can add a decimal integer after the `%' to specify how many characters to display.

%b
The current buffer name, obtained with the buffer-name function. See section Buffer Names.
%f
The visited file name, obtained with the buffer-file-name function. See section Buffer File Name.
%F
The title (only on a window system) or the name of the selected frame. See section Window Frame Parameters.
%c
The current column number of point.
%l
The current line number of point.
%*
`%' if the buffer is read only (see buffer-read-only);
`*' if the buffer is modified (see buffer-modified-p);
`-' otherwise. See section Buffer Modification.
%+
`*' if the buffer is modified (see buffer-modified-p);
`%' if the buffer is read only (see buffer-read-only);
`-' otherwise. This differs from `%*' only for a modified read-only buffer. See section Buffer Modification.
%&
`*' if the buffer is modified, and `-' otherwise.
%s
The status of the subprocess belonging to the current buffer, obtained with process-status. See section Process Information.
%t
Whether the visited file is a text file or a binary file. (This is a meaningful distinction only on certain operating systems.)
%p
The percentage of the buffer text above the top of window, or `Top', `Bottom' or `All'.
%P
The percentage of the buffer text that is above the bottom of the window (which includes the text visible in the window, as well as the text above the top), plus `Top' if the top of the buffer is visible on screen; or `Bottom' or `All'.
%n
`Narrow' when narrowing is in effect; nothing otherwise (see narrow-to-region in section Narrowing).
%[
An indication of the depth of recursive editing levels (not counting minibuffer levels): one `[' for each editing level. See section Recursive Editing.
%]
One `]' for each recursive editing level (not counting minibuffer levels).
%%
The character `%'---this is how to include a literal `%' in a string in which %-constructs are allowed.
%-
Dashes sufficient to fill the remainder of the mode line.
The following two %-constructs are still supported, but they are obsolete, since you can get the same results with the variables mode-name and global-mode-string.

%m
The value of mode-name.
%M
The value of global-mode-string. Currently, only display-time modifies the value of global-mode-string.
Imenu

Imenu is a feature that lets users select a definition or section in the buffer, from a menu which lists all of them, to go directly to that location in the buffer. Imenu works by constructing a buffer index which lists the names and positions of the definitions or portions of in the buffer, so the user can pick one of them to move to. This section explains how to customize Imenu for a major mode.

The usual and simplest way is to set the variable imenu-generic-expression:

Variable: imenu-generic-expression
This variable, if non-nil, specifies regular expressions for finding definitions for Imenu. In the simplest case, elements should look like this:
(menu-title regexp subexp)
Here, if menu-title is non-nil, it says that the matches for this element should go in a submenu of the buffer index; menu-title itself specifies the name for the submenu. If menu-title is nil, the matches for this element go directly in the top level of the buffer index.

The second item in the list, regexp, is a regular expression (see section Regular Expressions); wherever it matches, that is a definition to mention in the buffer index. The third item, subexp, indicates which subexpression in regexp matches the definition's name.

An element can also look like this:
(menu-title regexp index function arguments...)
Each match for this element creates a special index item which, if selected by the user, calls function with arguments item-name, the buffer position, and arguments.

For Emacs Lisp mode, pattern could look like this:
((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
 ("*Types*"
  "^\\s-*\
(def\\(type\\|struct\\|class\\|ine-condition\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2))
Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-case-fold-search
This variable controls whether matching against imenu-generic-expression is case-sensitive: t, the default, means matching should ignore case.

Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-syntax-alist
This variable is an alist of syntax table modifiers to use while processing imenu-generic-expression, to override the syntax table of the current buffer. Each element should have this form:
(characters . syntax-description)
The CAR, characters, can be either a character or a string. The element says to give that character or characters the syntax specified by syntax-description, which is passed to modify-syntax-entry (see section Syntax Table Functions).

This feature is typically used to give word syntax to characters which normally have symbol syntax, and thus to simplify imenu-generic-expression and speed up matching. For example, Fortran mode uses it this way:
  (setq imenu-syntax-alist '(("_$" . "w")))
The imenu-generic-expression patterns can then use `\\sw+' instead of `\\(\\sw\\|\\s_\\)+'. Note that this technique may be inconvenient to use when the mode needs to limit the initial character of a name to a smaller set of characters than are allowed in the rest of a name.

Setting this variable makes it buffer-local in the current buffer.

Another way to customize Imenu for a major mode is to set the variables imenu-prev-index-position-function and imenu-extract-index-name-function:

Variable: imenu-prev-index-position-function
If this variable is non-nil, its value should be a function for finding the next definition to mention in the buffer index, moving backwards in the file.

The function should leave point at the place to be connected to the index item; it should return nil if it doesn't find another item.

Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-extract-index-name-function
If this variable is non-nil, its value should be a function to return the name for a definition, assuming point is in that definition as the imenu-prev-index-position-function function would leave it.

Setting this variable makes it buffer-local in the current buffer.

The last way to customize Imenu for a major mode is to set the variables imenu-create-index-function:

Variable: imenu-create-index-function
This variable specifies the function to use for creating a buffer index. The function should take no arguments, and return an index for the current buffer. It is called within save-excursion, so where it leaves point makes no difference.

The default value is a function that uses imenu-generic-expression to produce the index alist. If you specify a different function, then imenu-generic-expression is not used.

Setting this variable makes it buffer-local in the current buffer.

Variable: imenu-index-alist
This variable holds the index alist for the current buffer. Setting it makes it buffer-local in the current buffer.

Simple elements in the alist look like (index-name . index-position). Selecting a simple element has the effect of moving to position index-position in the buffer.

Special elements look like (index-name position function arguments...). Selecting a special element performs
(funcall function index-name position arguments...)
A nested sub-alist element looks like (index-name sub-alist).

Font Lock Mode

Font Lock mode is a feature that automatically attaches face properties to certain parts of the buffer based on their syntactic role. How it parses the buffer depends on the major mode; most major modes define syntactic criteria for which faces to use, in which contexts. This section explains how to customize Font Lock for a particular language--in other words, for a particular major mode.

Font Lock mode finds text to highlight in two ways: through syntactic parsing based on the syntax table, and through searching (usually for regular expressions). Syntactic fontification happens first; it finds comments and string constants, and highlights them using font-lock-comment-face and font-lock-string-face (see section Faces for Font Lock); search-based fontification follows.

Font Lock Basics

There are several variables that control how Font Lock mode highlights text. But major modes should not set any of these variables directly. Instead, it should set font-lock-defaults as a buffer-local variable. The value assigned to this variable is used, if and when Font Lock mode is enabled, to set all the other variables.

Variable: font-lock-defaults
This variable is set by major modes, as a buffer-local variable, to specify how to fontify text in that mode. The value should look like this:
(keywords keywords-only case-fold
 syntax-alist syntax-begin other-vars...)
The first element, keywords, indirectly specifies the value of font-lock-keywords. It can be a symbol, a variable whose value is list to use for font-lock-keywords. It can also be a list of several such symbols, one for each possible level of fontification. The first symbol specifies how to do level 1 fontification, the second symbol how to do level 2, and so on.

The second element, keywords-only, specifies the value of the variable font-lock-keywords-only. If this is non-nil, syntactic fontification (of strings and comments) is not performed.

The third element, case-fold, specifies the value of font-lock-case-fold-search. If it is non-nil, Font Lock mode ignores case when searching as directed by font-lock-keywords.

If the fourth element, syntax-alist, is non-nil, it should be a list of cons cells of the form (char-or-string . string). These are used to set up a syntax table for fontification (see section Syntax Table Functions). The resulting syntax table is stored in font-lock-syntax-table.

The fifth element, syntax-begin, specifies the value of font-lock-beginning-of-syntax-function (see below).

Any further elements other-vars are have form (variable . value). This kind of element means to make variable buffer-local and then set it to value. This is used to set other variables that affect fontification.

Search-based Fontification

The most important variable for customizing Font Lock mode is font-lock-keywords. It specifies the search criteria for search-based fontification.

Variable: font-lock-keywords
This variable's value is a list of the keywords to highlight. Be careful when composing regular expressions for this list; a poorly written pattern can dramatically slow things down!

Each element of font-lock-keywords specifies how to find certain cases of text, and how to highlight those cases. Font Lock mode processes the elements of font-lock-keywords one by one, and for each element, it finds and handles all matches. Ordinarily, once part of the text has been fontified already, this cannot be overridden by a subsequent match in the same text; but you can specify different behavior using the override element of a highlighter.

Each element of font-lock-keywords should have one of these forms:

regexp
Highlight all matches for regexp using font-lock-keyword-face. For example,
;; Highlight discrete occurrences of `foo'
;; using font-lock-keyword-face.
"\\<foo\\>"
The function regexp-opt (see section Syntax of Regular Expressions) is useful for calculating optimal regular expressions to match a number of different keywords.
function
Find text by calling function, and highlight the matches it finds using font-lock-keyword-face. When function is called, it receives one argument, the limit of the search. It should return non-nil if it succeeds, and set the match data to describe the match that was found.
(matcher . match)
In this kind of element, matcher stands for either a regular expression or a function, as described above. The CDR, match, specifies which subexpression of matcher should be highlighted (instead of the entire text that matcher matched).
;; Highlight the `bar' in each occurrences of `fubar',
;; using font-lock-keyword-face.
("fu\\(bar\\)" . 1)
If you use regexp-opt to produce the regular expression matcher, then you can use regexp-opt-depth (see section Syntax of Regular Expressions) to calculate the value for match.
(matcher . facename)
In this kind of element, facename is an expression whose value specifies the face name to use for highlighting.
;; Highlight occurrences of `fubar',
;; using the face which is the value of fubar-face.
("fubar" . fubar-face)
(matcher . highlighter)
In this kind of element, highlighter is a list which specifies how to highlight matches found by matcher. It has the form
(subexp facename override laxmatch)
The CAR, subexp, is an integer specifying which subexpression of the match to fontify (0 means the entire matching text). The second subelement, facename, specifies the face, as described above. The last two values in highlighter, override and laxmatch, are flags. If override is t, this element can override existing fontification made by previous elements of font-lock-keywords. If it is keep, then each character is fontified if it has not been fontified already by some other element. If it is prepend, the face facename is added to the beginning of the face property. If it is append, the face facename is added to the end of the face property. If laxmatch is non-nil, it means there should be no error if there is no subexpression numbered subexp in matcher. Here are some examples of elements of this kind, and what they do:
;; Highlight occurrences of either `foo' or `bar',
;; using foo-bar-face, even if they have already been highlighted.
;; foo-bar-face should be a variable whose value is a face.
("foo\\|bar" 0 foo-bar-face t)

;; Highlight the first subexpression within each occurrences
;; that the function fubar-match finds,
;; using the face which is the value of fubar-face.
(fubar-match 1 fubar-face)
(matcher highlighters...)
This sort of element specifies several highlighter lists for a single matcher. In order for this to be useful, each highlighter should have a different value of subexp; that is, each one should apply to a different subexpression of matcher.
(eval . form)
Here form is an expression to be evaluated the first time this value of font-lock-keywords is used in a buffer. Its value should have one of the forms described in this table.
Warning: Do not design an element of font-lock-keywords to match text which spans lines; this does not work reliably. While font-lock-fontify-buffer handles multi-line patterns correctly, updating when you edit the buffer does not, since it considers text one line at a time.

Other Font Lock Variables

This section describes additional variables that a major mode can set by means of font-lock-defaults.

Variable: font-lock-keywords-only
Non-nil means Font Lock should not fontify comments or strings syntactically; it should only fontify based on font-lock-keywords.

Variable: font-lock-keywords-case-fold-search
Non-nil means that regular expression matching for the sake of font-lock-keywords should be case-insensitive.

Variable: font-lock-syntax-table
This variable specifies the syntax table to use for fontification of comments and strings.

Variable: font-lock-beginning-of-syntax-function
If this variable is non-nil, it should be a function to move point back to a position that is syntactically at "top level" and outside of strings or comments. Font Lock uses this when necessary to get the right results for syntactic fontification.

This function is called with no arguments. It should leave point at the beginning of any enclosing syntactic block. Typical values are beginning-of-line (i.e., the start of the line is known to be outside a syntactic block), or beginning-of-defun for programming modes or backward-paragraph for textual modes (i.e., the mode-dependent function is known to move outside a syntactic block).

If the value is nil, the beginning of the buffer is used as a position outside of a syntactic block. This cannot be wrong, but it can be slow.

Variable: font-lock-mark-block-function
If this variable is non-nil, it should be a function that is called with no arguments, to choose an enclosing range of text for refontification for the command M-g M-g (font-lock-fontify-block).

The function should report its choice by placing the region around it. A good choice is a range of text large enough to give proper results, but not too large so that refontification becomes slow. Typical values are mark-defun for programming modes or mark-paragraph for textual modes.

Levels of Font Lock

Many major modes offer three different levels of fontification. You can define multiple levels by using a list of symbols for keywords in font-lock-defaults. Each symbol specifies one level of fontification; it is up to the user to choose one of these levels. The chosen level's symbol value is used to initialize font-lock-keywords.

Here are the conventions for how to define the levels of fontification:

Level 1: highlight function declarations, file directives (such as include or import directives), strings and comments. The idea is speed, so only the most important and top-level components are fontified.
Level 2: in addition to level 1, highlight all language keywords, including type names that act like keywords, as well as named constant values. The idea is that all keywords (either syntactic or semantic) should be fontified appropriately.
Level 3: in addition to level 2, highlight the symbols being defined in function and variable declarations, and all builtin function names, wherever they appear.

Faces for Font Lock

You can make Font Lock mode use any face, but several faces are defined specifically for Font Lock mode. Each of these symbols is both a face name, and a variable whose default value is the symbol itself. Thus, the default value of font-lock-comment-face is font-lock-comment-face. This means you can write font-lock-comment-face in a context such as font-lock-keywords where a face-name-valued expression is used.

font-lock-comment-face
Used (typically) for comments.
font-lock-string-face
Used (typically) for string constants.
font-lock-keyword-face
Used (typically) for keywords--names that have special syntactic significance, like for and if in C.
font-lock-builtin-face
Used (typically) for built-in function names.
font-lock-function-name-face
Used (typically) for the name of a function being defined or declared, in a function definition or declaration.
font-lock-variable-name-face
Used (typically) for the name of a variable being defined or declared, in a variable definition or declaration.
font-lock-type-face
Used (typically) for names of user-defined data types, where they are defined and where they are used.
font-lock-constant-face
Used (typically) for constant names.
font-lock-warning-face
Used (typically) for constructs that are peculiar, or that greatly change the meaning of other text. For example, this is used for `;;;###autoload' cookies in Emacs Lisp, and for #error directives in C.
Syntactic Font Lock

Font Lock mode can be used to update syntax-table properties automatically. This is useful in languages for which a single syntax table by itself is not sufficient.

Variable: font-lock-syntactic-keywords
This variable enables and controls syntactic Font Lock. Its value should be a list of elements of this form:
(matcher subexp syntax override laxmatch)
The parts of this element have the same meanings as in the corresponding sort of element of font-lock-keywords,
(matcher subexp facename override laxmatch)
However, instead of specifying the value facename to use for the face property, it specifies the value syntax to use for the syntax-table property. Here, syntax can be a variable whose value is a syntax table, a syntax entry of the form (syntax-code . matching-char), or an expression whose value is one of those two types.

Hooks

A hook is a variable where you can store a function or functions to be called on a particular occasion by an existing program. Emacs provides hooks for the sake of customization. Most often, hooks are set up in the `.emacs' file, but Lisp programs can set them also. See section Standard Hooks, for a list of standard hook variables.

Most of the hooks in Emacs are normal hooks. These variables contain lists of functions to be called with no arguments. When the hook name ends in `-hook', that tells you it is normal. We try to make all hooks normal, as much as possible, so that you can use them in a uniform way.

Every major mode function is supposed to run a normal hook called the mode hook as the last step of initialization. This makes it easy for a user to customize the behavior of the mode, by overriding the buffer-local variable assignments already made by the mode. But hooks are used in other contexts too. For example, the hook suspend-hook runs just before Emacs suspends itself (see section Suspending Emacs).

The recommended way to add a hook function to a normal hook is by calling add-hook (see below). The hook functions may be any of the valid kinds of functions that funcall accepts (see section What Is a Function?). Most normal hook variables are initially void; add-hook knows how to deal with this.

If the hook variable's name does not end with `-hook', that indicates it is probably an abnormal hook; you should look at its documentation to see how to use the hook properly.

If the variable's name ends in `-functions' or `-hooks', then the value is a list of functions, but it is abnormal in that either these functions are called with arguments or their values are used in some way. You can use add-hook to add a function to the list, but you must take care in writing the function. (A few of these variables are actually normal hooks which were named before we established the convention of using `-hook' for them.)

If the variable's name ends in `-function', then its value is just a single function, not a list of functions.

Here's an example that uses a mode hook to turn on Auto Fill mode when in Lisp Interaction mode:
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
At the appropriate time, Emacs uses the run-hooks function to run particular hooks. This function calls the hook functions that have been added with add-hook.

Function: run-hooks &rest hookvar
This function takes one or more hook variable names as arguments, and runs each hook in turn. Each hookvar argument should be a symbol that is a hook variable. These arguments are processed in the order specified.

If a hook variable has a non-nil value, that value may be a function or a list of functions. If the value is a function (either a lambda expression or a symbol with a function definition), it is called. If it is a list, the elements are called, in order. The hook functions are called with no arguments. Nowadays, storing a single function in the hook variable is semi-obsolete; you should always use a list of functions.

For example, here's how emacs-lisp-mode runs its mode hook:
(run-hooks 'emacs-lisp-mode-hook)
Function: run-hook-with-args hook &rest args
This function is the way to run an abnormal hook which passes arguments to the hook functions. It calls each of the hook functions, passing each of them the arguments args.

Function: run-hook-with-args-until-failure hook &rest args
This function is the way to run an abnormal hook which passes arguments to the hook functions, and stops as soon as any hook function fails. It calls each of the hook functions, passing each of them the arguments args, until some hook function returns nil. Then it stops, and returns nil if some hook function did, and otherwise returns a non-nil value.

Function: run-hook-with-args-until-success hook &rest args
This function is the way to run an abnormal hook which passes arguments to the hook functions, and stops as soon as any hook function succeeds. It calls each of the hook functions, passing each of them the arguments args, until some hook function returns non-nil. Then it stops, and returns whatever was returned by the last hook function that was called.

Function: add-hook hook function &optional append local
This function is the handy way to add function function to hook variable hook. The argument function may be any valid Lisp function with the proper number of arguments. For example,
(add-hook 'text-mode-hook 'my-text-hook-function)
adds my-text-hook-function to the hook called text-mode-hook.

You can use add-hook for abnormal hooks as well as for normal hooks.

It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is "asking for trouble." However, the order is predictable: normally, function goes at the front of the hook list, so it will be executed first (barring another add-hook call). If the optional argument append is non-nil, the new hook function goes at the end of the hook list and will be executed last.

If local is non-nil, that says to make the new hook function buffer-local in the current buffer. Before you can do this, you must make the hook itself buffer-local by calling make-local-hook (not make-local-variable). If the hook itself is not buffer-local, then the value of local makes no difference--the hook function is always global.

Function: remove-hook hook function &optional local
This function removes function from the hook variable hook.

If local is non-nil, that says to remove function from the buffer-local hook list instead of from the global hook list. If the hook variable itself is not buffer-local, then the value of local makes no difference.

Function: make-local-hook hook
This function makes the hook variable hook buffer-local in the current buffer. When a hook variable is buffer-local, it can have buffer-local and global hook functions, and run-hooks runs all of them.

This function works by making t an element of the buffer-local value. That serves as a flag to use the hook functions in the default value of the hook variable as well as those in the buffer-local value. Since run-hooks understands this flag, make-local-hook works with all normal hooks. It works for only some non-normal hooks--those whose callers have been updated to understand this meaning of t.

Do not use make-local-variable directly for hook variables; it is not sufficient.
Documentation

GNU Emacs Lisp has convenient on-line help facilities, most of which derive their information from the documentation strings associated with functions and variables. This chapter describes how to write good documentation strings for your Lisp programs, as well as how to write programs to access documentation.

Note that the documentation strings for Emacs are not the same thing as the Emacs manual. Manuals have their own source files, written in the Texinfo language; documentation strings are specified in the definitions of the functions and variables they apply to. A collection of documentation strings is not sufficient as a manual because a good manual is not organized in that fashion; it is organized in terms of topics of discussion.

Documentation Basics

A documentation string is written using the Lisp syntax for strings, with double-quote characters surrounding the text of the string. This is because it really is a Lisp string object. The string serves as documentation when it is written in the proper place in the definition of a function or variable. In a function definition, the documentation string follows the argument list. In a variable definition, the documentation string follows the initial value of the variable.

When you write a documentation string, make the first line a complete sentence (or two complete sentences) since some commands, such as apropos, show only the first line of a multi-line documentation string. Also, you should not indent the second line of a documentation string, if it has one, because that looks odd when you use C-h f (describe-function) or C-h v (describe-variable) to view the documentation string. See section Tips for Documentation Strings.

Documentation strings can contain several special substrings, which stand for key bindings to be looked up in the current keymaps when the documentation is displayed. This allows documentation strings to refer to the keys for related commands and be accurate even when a user rearranges the key bindings. (See section Access to Documentation Strings.)

In Emacs Lisp, a documentation string is accessible through the function or variable that it describes:

The documentation for a function is stored in the function definition itself (see section Lambda Expressions). The function documentation knows how to extract it.
The documentation for a variable is stored in the variable's property list under the property name variable-documentation. The function documentation-property knows how to retrieve it.

To save space, the documentation for preloaded functions and variables (including primitive functions and autoloaded functions) is stored in the file `emacs/etc/DOC-version'---not inside Emacs. The documentation strings for functions and variables loaded during the Emacs session from byte-compiled files are stored in those files (see section Documentation Strings and Compilation).

The data structure inside Emacs has an integer offset into the file, or a list containing a file name and an integer, in place of the documentation string. The functions documentation and documentation-property use that information to fetch the documentation string from the appropriate file; this is transparent to the user.

For information on the uses of documentation strings, see section `Help' in The GNU Emacs Manual.

The `emacs/lib-src' directory contains two utilities that you can use to print nice-looking hardcopy for the file `emacs/etc/DOC-version'. These are `sorted-doc' and `digest-doc'.

Access to Documentation Strings

Function: documentation-property symbol property &optional verbatim
This function returns the documentation string that is recorded in symbol's property list under property property. It retrieves the text from a file if necessary, and runs substitute-command-keys to substitute actual key bindings. (This substitution is not done if verbatim is non-nil.)
(documentation-property 'command-line-processed
   'variable-documentation)
     => "Non-nil once command line has been processed"
(symbol-plist 'command-line-processed)
     => (variable-documentation 188902)
Function: documentation function &optional verbatim
This function returns the documentation string of function. It reads the text from a file if necessary. Then (unless verbatim is non-nil) it calls substitute-command-keys, to return a value containing the actual (current) key bindings.

The function documentation signals a void-function error if function has no function definition. However, it is OK if the function definition has no documentation string. In that case, documentation returns nil.

Here is an example of using the two functions, documentation and documentation-property, to display the documentation strings for several symbols in a `*Help*' buffer.
(defun describe-symbols (pattern)
  "Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the `*Help*' buffer."
  (interactive "sDescribe symbols matching: ")
  (let ((describe-func
         (function
          (lambda (s)
            ;; Print description of symbol.
            (if (fboundp s)             ; It is a function.
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (commandp s)
                       (let ((keys (where-is-internal s)))
                         (if keys
                             (concat
                              "Keys: "
                              (mapconcat 'key-description
                                         keys " "))
                           "Keys: none"))
                     "Function")
                   (or (documentation s)
                       "not documented"))))

            (if (boundp s)              ; It is a variable.
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (user-variable-p s)
                       "Option " "Variable")
                   (or (documentation-property
                         s 'variable-documentation)
                       "not documented")))))))
        sym-list)

    ;; Build a list of symbols that match pattern.
    (mapatoms (function
               (lambda (sym)
                 (if (string-match pattern (symbol-name sym))
                     (setq sym-list (cons sym sym-list))))))

    ;; Display the data.
    (with-output-to-temp-buffer "*Help*"
      (mapcar describe-func (sort sym-list 'string<))
      (print-help-return-message))))
The describe-symbols function works like apropos, but provides more information.
(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option
*Semipermanent goal column for vertical motion, as set by ...

set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.

temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was
at the start of current run of vertical motion commands.
When the `track-eol' feature is doing its job, the value is 9999.
---------- Buffer: *Help* ----------
Function: Snarf-documentation filename
This function is used only during Emacs initialization, just before the runnable Emacs is dumped. It finds the file offsets of the documentation strings stored in the file filename, and records them in the in-core function definitions and variable property lists in place of the actual strings. See section Building Emacs.

Emacs reads the file filename from the `emacs/etc' directory. When the dumped Emacs is later executed, the same file will be looked for in the directory doc-directory. Usually filename is "DOC-version".

Variable: doc-directory
This variable holds the name of the directory which should contain the file "DOC-version" that contains documentation strings for built-in and preloaded functions and variables.

In most cases, this is the same as data-directory. They may be different when you run Emacs from the directory where you built it, without actually installing it. See data-directory in section Help Functions.

In older Emacs versions, exec-directory was used for this.

Substituting Key Bindings in Documentation

When documentation strings refer to key sequences, they should use the current, actual key bindings. They can do so using certain special text sequences described below. Accessing documentation strings in the usual way substitutes current key binding information for these special sequences. This works by calling substitute-command-keys. You can also call that function yourself.

Here is a list of the special sequences and what they mean:

\[command]
stands for a key sequence that will invoke command, or `M-x command' if command has no key bindings.
\{mapvar}
stands for a summary of the keymap which is the value of the variable mapvar. The summary is made using describe-bindings.
\<mapvar>
stands for no text itself. It is used only for a side effect: it specifies mapvar's value as the keymap for any following `\[command]' sequences in this documentation string.
\=
quotes the following character and is discarded; thus, `\=\[' puts `\[' into the output, and `\=\=' puts `\=' into the output.
Please note: Each `\' must be doubled when written in a string in Emacs Lisp.

Function: substitute-command-keys string
This function scans string for the above special sequences and replaces them by what they stand for, returning the result as a string. This permits display of documentation that refers accurately to the user's own customized key bindings.

Here are examples of the special sequences:
(substitute-command-keys
   "To abort recursive edit, type: \\[abort-recursive-edit]")
=> "To abort recursive edit, type: C-]"

(substitute-command-keys
   "The keys that are defined for the minibuffer here are:
  \\{minibuffer-local-must-match-map}")
=> "The keys that are defined for the minibuffer here are:

?               minibuffer-completion-help
SPC             minibuffer-complete-word
TAB             minibuffer-complete
C-j             minibuffer-complete-and-exit
RET             minibuffer-complete-and-exit
C-g             abort-recursive-edit
"

(substitute-command-keys
   "To abort a recursive edit from the minibuffer, type\
\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
=> "To abort a recursive edit from the minibuffer, type C-g."
Describing Characters for Help Messages

These functions convert events, key sequences, or characters to textual descriptions. These descriptions are useful for including arbitrary text characters or key sequences in messages, because they convert non-printing and whitespace characters to sequences of printing characters. The description of a non-whitespace printing character is the character itself.

Function: key-description sequence
This function returns a string containing the Emacs standard notation for the input events in sequence. The argument sequence may be a string, vector or list. See section Input Events, for more information about valid events. See also the examples for single-key-description, below.

Function: single-key-description event
This function returns a string describing event in the standard Emacs notation for keyboard input. A normal printing character appears as itself, but a control character turns into a string starting with `C-', a meta character turns into a string starting with `M-', and space, tab, etc. appear as `SPC', `TAB', etc. A function key symbol appears as itself. An event that is a list appears as the name of the symbol in the CAR of the list.
(single-key-description ?\C-x)
     => "C-x"
(key-description "\C-x \M-y \n \t \r \f123")
     => "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
(single-key-description 'C-mouse-1)
     => "C-mouse-1"
Function: text-char-description character
This function returns a string describing character in the standard Emacs notation for characters that appear in text--like single-key-description, except that control characters are represented with a leading caret (which is how control characters in Emacs buffers are usually displayed).
(text-char-description ?\C-c)
     => "^C"
(text-char-description ?\M-m)
     => "M-m"
(text-char-description ?\C-\M-m)
     => "M-^M"
Function: read-kbd-macro string
This function is used mainly for operating on keyboard macros, but it can also be used as a rough inverse for key-description. You call it with a string containing key descriptions, separated by spaces; it returns a string or vector containing the corresponding events. (This may or may not be a single valid key sequence, depending on what events you use; see section Keymap Terminology.)

Help Functions

Emacs provides a variety of on-line help functions, all accessible to the user as subcommands of the prefix C-h. For more information about them, see section `Help' in The GNU Emacs Manual. Here we describe some program-level interfaces to the same information.

Command: apropos regexp &optional do-all
This function finds all symbols whose names contain a match for the regular expression regexp, and returns a list of them (see section Regular Expressions). It also displays the symbols in a buffer named `*Help*', each with a one-line description taken from the beginning of its documentation string.

If do-all is non-nil, then apropos also shows key bindings for the functions that are found; it also shows all symbols, even those that are neither functions nor variables.

In the first of the following examples, apropos finds all the symbols with names containing `exec'. (We don't show here the output that results in the `*Help*' buffer.)
(apropos "exec")
     => (Buffer-menu-execute command-execute exec-directory
    exec-path execute-extended-command execute-kbd-macro
    executing-kbd-macro executing-macro)
Variable: help-map
The value of this variable is a local keymap for characters following the Help key, C-h.

Prefix Command: help-command
This symbol is not a function; its function definition cell holds the keymap known as help-map. It is defined in `help.el' as follows:
(define-key global-map "\C-h" 'help-command)
(fset 'help-command help-map)
Function: print-help-return-message &optional function
This function builds a string that explains how to restore the previous state of the windows after a help command. After building the message, it applies function to it if function is non-nil. Otherwise it calls message to display it in the echo area.

This function expects to be called inside a with-output-to-temp-buffer special form, and expects standard-output to have the value bound by that special form. For an example of its use, see the long example in section Access to Documentation Strings.

Variable: help-char
The value of this variable is the help character--the character that Emacs recognizes as meaning Help. By default, its value is 8, which stands for C-h. When Emacs reads this character, if help-form is a non-nil Lisp expression, it evaluates that expression, and displays the result in a window if it is a string.

Usually the value of help-form is nil. Then the help character has no special meaning at the level of command input, and it becomes part of a key sequence in the normal way. The standard key binding of C-h is a prefix key for several general-purpose help features.

The help character is special after prefix keys, too. If it has no binding as a subcommand of the prefix key, it runs describe-prefix-bindings, which displays a list of all the subcommands of the prefix key.

Variable: help-event-list
The value of this variable is a list of event types that serve as alternative "help characters." These events are handled just like the event specified by help-char.

Variable: help-form
If this variable is non-nil, its value is a form to evaluate whenever the character help-char is read. If evaluating the form produces a string, that string is displayed.

A command that calls read-event or read-char probably should bind help-form to a non-nil expression while it does input. (The time when you should not do this is when C-h has some other meaning.) Evaluating this expression should result in a string that explains what the input is for and how to enter it properly.

Entry to the minibuffer binds this variable to the value of minibuffer-help-form (see section Minibuffer Miscellany).

Variable: prefix-help-command
This variable holds a function to print help for a prefix key. The function is called when the user types a prefix key followed by the help character, and the help character has no binding after that prefix. The variable's default value is describe-prefix-bindings.

Function: describe-prefix-bindings
This function calls describe-bindings to display a list of all the subcommands of the prefix key of the most recent key sequence. The prefix described consists of all but the last event of that key sequence. (The last event is, presumably, the help character.)

The following two functions are meant for modes that want to provide help without relinquishing control, such as the "electric" modes. Their names begin with `Helper' to distinguish them from the ordinary help functions.

Command: Helper-describe-bindings
This command pops up a window displaying a help buffer containing a listing of all of the key bindings from both the local and global keymaps. It works by calling describe-bindings.

Command: Helper-help
This command provides help for the current mode. It prompts the user in the minibuffer with the message `Help (Type ? for further options)', and then provides assistance in finding out what the key bindings are, and what the mode is intended for. It returns nil.

This can be customized by changing the map Helper-help-map.

Variable: data-directory
This variable holds the name of the directory in which Emacs finds certain documentation and text files that come with Emacs. In older Emacs versions, exec-directory was used for this.

Macro: make-help-screen fname help-line help-text help-map
This macro defines a help command named fname that acts like a prefix key that shows a list of the subcommands it offers.

When invoked, fname displays help-text in a window, then reads and executes a key sequence according to help-map. The string help-text should describe the bindings available in help-map.

The command fname is defined to handle a few events itself, by scrolling the display of help-text. When fname reads one of those special events, it does the scrolling and then reads another event. When it reads an event that is not one of those few, and which has a binding in help-map, it executes that key's binding and then returns.

The argument help-line should be a single-line summary of the alternatives in help-map. In the current version of Emacs, this argument is used only if you set the option three-step-help to t.

This macro is used in the command help-for-help which is the binding of C-h C-h.

User Option: three-step-help
If this variable is non-nil, commands defined with make-help-screen display their help-line strings in the echo area at first, and display the longer help-text strings only if the user types the help character again.
Files

In Emacs, you can find, create, view, save, and otherwise work with files and file directories. This chapter describes most of the file-related functions of Emacs Lisp, but a few others are described in section Buffers, and those related to backups and auto-saving are described in section Backups and Auto-Saving.

Many of the file functions take one or more arguments that are file names. A file name is actually a string. Most of these functions expand file name arguments by calling expand-file-name, so that `~' is handled correctly, as are relative file names (including `../'). These functions don't recognize environment variable substitutions such as `$HOME'. See section Functions that Expand Filenames.

Visiting Files

Visiting a file means reading a file into a buffer. Once this is done, we say that the buffer is visiting that file, and call the file "the visited file" of the buffer.

A file and a buffer are two different things. A file is information recorded permanently in the computer (unless you delete it). A buffer, on the other hand, is information inside of Emacs that will vanish at the end of the editing session (or when you kill the buffer). Usually, a buffer contains information that you have copied from a file; then we say the buffer is visiting that file. The copy in the buffer is what you modify with editing commands. Such changes to the buffer do not change the file; therefore, to make the changes permanent, you must save the buffer, which means copying the altered buffer contents back into the file.

In spite of the distinction between files and buffers, people often refer to a file when they mean a buffer and vice-versa. Indeed, we say, "I am editing a file," rather than, "I am editing a buffer that I will soon save as a file of the same name." Humans do not usually need to make the distinction explicit. When dealing with a computer program, however, it is good to keep the distinction in mind.

Functions for Visiting Files

This section describes the functions normally used to visit files. For historical reasons, these functions have names starting with `find-' rather than `visit-'. See section Buffer File Name, for functions and variables that access the visited file name of a buffer or that find an existing buffer by its visited file name.

In a Lisp program, if you want to look at the contents of a file but not alter it, the fastest way is to use insert-file-contents in a temporary buffer. Visiting the file is not necessary and takes longer. See section Reading from Files.

Command: find-file filename
This command selects a buffer visiting the file filename, using an existing buffer if there is one, and otherwise creating a new buffer and reading the file into it. It also returns that buffer.

The body of the find-file function is very simple and looks like this:
(switch-to-buffer (find-file-noselect filename))
(See switch-to-buffer in section Displaying Buffers in Windows.)

When find-file is called interactively, it prompts for filename in the minibuffer.

Function: find-file-noselect filename &optional nowarn rawfile
This function is the guts of all the file-visiting functions. It finds or creates a buffer visiting the file filename, and returns it. It uses an existing buffer if there is one, and otherwise creates a new buffer and reads the file into it. You may make the buffer current or display it in a window if you wish, but this function does not do so.

When find-file-noselect uses an existing buffer, it first verifies that the file has not changed since it was last visited or saved in that buffer. If the file has changed, then this function asks the user whether to reread the changed file. If the user says `yes', any changes previously made in the buffer are lost.

This function displays warning or advisory messages in various peculiar cases, unless the optional argument nowarn is non-nil. For example, if it needs to create a buffer, and there is no file named filename, it displays the message `New file' in the echo area, and leaves the buffer empty.

The find-file-noselect function normally calls after-find-file after reading the file (see section Subroutines of Visiting). That function sets the buffer major mode, parses local variables, warns the user if there exists an auto-save file more recent than the file just visited, and finishes by running the functions in find-file-hooks.

If the optional argument rawfile is non-nil, then after-find-file is not called, and the find-file-not-found-hooks are not run in case of failure. What's more, a non-nil rawfile value suppresses coding system conversion (see section Coding Systems) and format conversion (see section File Format Conversion).

The find-file-noselect function returns the buffer that is visiting the file filename.
(find-file-noselect "/etc/fstab")
     => #<buffer fstab>
Command: find-file-other-window filename
This command selects a buffer visiting the file filename, but does so in a window other than the selected window. It may use another existing window or split a window; see section Displaying Buffers in Windows.

When this command is called interactively, it prompts for filename.

Command: find-file-read-only filename
This command selects a buffer visiting the file filename, like find-file, but it marks the buffer as read-only. See section Read-Only Buffers, for related functions and variables.

When this command is called interactively, it prompts for filename.

Command: view-file filename
This command visits filename using View mode, returning to the previous buffer when you exit View mode. View mode is a minor mode that provides commands to skim rapidly through the file, but does not let you modify the text. Entering View mode runs the normal hook view-mode-hook. See section Hooks.

When view-file is called interactively, it prompts for filename.

Variable: find-file-hooks
The value of this variable is a list of functions to be called after a file is visited. The file's local-variables specification (if any) will have been processed before the hooks are run. The buffer visiting the file is current when the hook functions are run.

This variable works just like a normal hook, but we think that renaming it would not be advisable. See section Hooks.

Variable: find-file-not-found-hooks
The value of this variable is a list of functions to be called when find-file or find-file-noselect is passed a nonexistent file name. find-file-noselect calls these functions as soon as it detects a nonexistent file. It calls them in the order of the list, until one of them returns non-nil. buffer-file-name is already set up.

This is not a normal hook because the values of the functions are used, and in many cases only some of the functions are called.

Subroutines of Visiting

The find-file-noselect function uses two important subroutines which are sometimes useful in user Lisp code: create-file-buffer and after-find-file. This section explains how to use them.

Function: create-file-buffer filename
This function creates a suitably named buffer for visiting filename, and returns it. It uses filename (sans directory) as the name if that name is free; otherwise, it appends a string such as `<2>' to get an unused name. See also section Creating Buffers.

Please note: create-file-buffer does not associate the new buffer with a file and does not select the buffer. It also does not use the default major mode.
(create-file-buffer "foo")
     => #<buffer foo>
(create-file-buffer "foo")
     => #<buffer foo<2>>
(create-file-buffer "foo")
     => #<buffer foo<3>>
This function is used by find-file-noselect. It uses generate-new-buffer (see section Creating Buffers).

Function: after-find-file &optional error warn
This function sets the buffer major mode, and parses local variables (see section How Emacs Chooses a Major Mode). It is called by find-file-noselect and by the default revert function (see section Reverting).

If reading the file got an error because the file does not exist, but its directory does exist, the caller should pass a non-nil value for error. In that case, after-find-file issues a warning: `(New File)'. For more serious errors, the caller should usually not call after-find-file.

If warn is non-nil, then this function issues a warning if an auto-save file exists and is more recent than the visited file.

The last thing after-find-file does is call all the functions in the list find-file-hooks.

Saving Buffers

When you edit a file in Emacs, you are actually working on a buffer that is visiting that file--that is, the contents of the file are copied into the buffer and the copy is what you edit. Changes to the buffer do not change the file until you save the buffer, which means copying the contents of the buffer into the file.

Command: save-buffer &optional backup-option
This function saves the contents of the current buffer in its visited file if the buffer has been modified since it was last visited or saved. Otherwise it does nothing.

save-buffer is responsible for making backup files. Normally, backup-option is nil, and save-buffer makes a backup file only if this is the first save since visiting the file. Other values for backup-option request the making of backup files in other circumstances:

With an argument of 4 or 64, reflecting 1 or 3 C-u's, the save-buffer function marks this version of the file to be backed up when the buffer is next saved.
With an argument of 16 or 64, reflecting 2 or 3 C-u's, the save-buffer function unconditionally backs up the previous version of the file before saving it.

Command: save-some-buffers &optional save-silently-p exiting
This command saves some modified file-visiting buffers. Normally it asks the user about each buffer. But if save-silently-p is non-nil, it saves all the file-visiting buffers without querying the user.

The optional exiting argument, if non-nil, requests this function to offer also to save certain other buffers that are not visiting files. These are buffers that have a non-nil buffer-local value of buffer-offer-save. (A user who says yes to saving one of these is asked to specify a file name to use.) The save-buffers-kill-emacs function passes a non-nil value for this argument.

Command: write-file filename
This function writes the current buffer into file filename, makes the buffer visit that file, and marks it not modified. Then it renames the buffer based on filename, appending a string like `<2>' if necessary to make a unique buffer name. It does most of this work by calling set-visited-file-name (see section Buffer File Name) and save-buffer.

Saving a buffer runs several hooks. It also performs format conversion (see section File Format Conversion), and may save text properties in "annotations" (see section Saving Text Properties in Files).

Variable: write-file-hooks
The value of this variable is a list of functions to be called before writing out a buffer to its visited file. If one of them returns non-nil, the file is considered already written and the rest of the functions are not called, nor is the usual code for writing the file executed.

If a function in write-file-hooks returns non-nil, it is responsible for making a backup file (if that is appropriate). To do so, execute the following code:
(or buffer-backed-up (backup-buffer))
You might wish to save the file modes value returned by backup-buffer and use that to set the mode bits of the file that you write. This is what save-buffer normally does.

The hook functions in write-file-hooks are also responsible for encoding the data (if desired): they must choose a suitable coding system (see section Coding Systems in Lisp), perform the encoding (see section Explicit Encoding and Decoding), and set last-coding-system-used to the coding system that was used (see section Encoding and I/O).

Do not make this variable buffer-local. To set up buffer-specific hook functions, use write-contents-hooks instead.

Even though this is not a normal hook, you can use add-hook and remove-hook to manipulate the list. See section Hooks.

Variable: local-write-file-hooks
This works just like write-file-hooks, but it is intended to be made buffer-local in particular buffers, and used for hooks that pertain to the file name or the way the buffer contents were obtained.

The variable is marked as a permanent local, so that changing the major mode does not alter a buffer-local value. This is convenient for packages that read "file" contents in special ways, and set up hooks to save the data in a corresponding way.

Variable: write-contents-hooks
This works just like write-file-hooks, but it is intended for hooks that pertain to the contents of the file, as opposed to hooks that pertain to where the file came from. Such hooks are usually set up by major modes, as buffer-local bindings for this variable.

This variable automatically becomes buffer-local whenever it is set; switching to a new major mode always resets this variable. When you use add-hooks to add an element to this hook, you should not specify a non-nil local argument, since this variable is used only buffer-locally.

Variable: after-save-hook
This normal hook runs after a buffer has been saved in its visited file. One use of this hook is in Fast Lock mode; it uses this hook to save the highlighting information in a cache file.

Variable: file-precious-flag
If this variable is non-nil, then save-buffer protects against I/O errors while saving by writing the new file to a temporary name instead of the name it is supposed to have, and then renaming it to the intended name after it is clear there are no errors. This procedure prevents problems such as a lack of disk space from resulting in an invalid file.

As a side effect, backups are necessarily made by copying. See section Backup by Renaming or by Copying?. Yet, at the same time, saving a precious file always breaks all hard links between the file you save and other file names.

Some modes give this variable a non-nil buffer-local value in particular buffers.

User Option: require-final-newline
This variable determines whether files may be written out that do not end with a newline. If the value of the variable is t, then save-buffer silently adds a newline at the end of the file whenever the buffer being saved does not already end in one. If the value of the variable is non-nil, but not t, then save-buffer asks the user whether to add a newline each time the case arises.

If the value of the variable is nil, then save-buffer doesn't add newlines at all. nil is the default value, but a few major modes set it to t in particular buffers.

See also the function set-visited-file-name (see section Buffer File Name).

Reading from Files

You can copy a file from the disk and insert it into a buffer using the insert-file-contents function. Don't use the user-level command insert-file in a Lisp program, as that sets the mark.

Function: insert-file-contents filename &optional visit beg end replace
This function inserts the contents of file filename into the current buffer after point. It returns a list of the absolute file name and the length of the data inserted. An error is signaled if filename is not the name of a file that can be read.

The function insert-file-contents checks the file contents against the defined file formats, and converts the file contents if appropriate. See section File Format Conversion. It also calls the functions in the list after-insert-file-functions; see section Saving Text Properties in Files.

If visit is non-nil, this function additionally marks the buffer as unmodified and sets up various fields in the buffer so that it is visiting the file filename: these include the buffer's visited file name and its last save file modtime. This feature is used by find-file-noselect and you probably should not use it yourself.

If beg and end are non-nil, they should be integers specifying the portion of the file to insert. In this case, visit must be nil. For example,
(insert-file-contents filename nil 0 500)
inserts the first 500 characters of a file.

If the argument replace is non-nil, it means to replace the contents of the buffer (actually, just the accessible portion) with the contents of the file. This is better than simply deleting the buffer contents and inserting the whole file, because (1) it preserves some marker positions and (2) it puts less data in the undo list.

It is possible to read a special file (such as a FIFO or an I/O device) with insert-file-contents, as long as replace and visit are nil.

Function: insert-file-contents-literally filename &optional visit beg end replace
This function works like insert-file-contents except that it does not do format decoding (see section File Format Conversion), does not do character code conversion (see section Coding Systems), does not run find-file-hooks, does not perform automatic uncompression, and so on.

If you want to pass a file name to another process so that another program can read the file, use the function file-local-copy; see section Making Certain File Names "Magic".

Writing to Files

You can write the contents of a buffer, or part of a buffer, directly to a file on disk using the append-to-file and write-region functions. Don't use these functions to write to files that are being visited; that could cause confusion in the mechanisms for visiting.

Command: append-to-file start end filename
This function appends the contents of the region delimited by start and end in the current buffer to the end of file filename. If that file does not exist, it is created. This function returns nil.

An error is signaled if filename specifies a nonwritable file, or a nonexistent file in a directory where files cannot be created.

Command: write-region start end filename &optional append visit confirm
This function writes the region delimited by start and end in the current buffer into the file specified by filename.

If start is a string, then write-region writes or appends that string, rather than text from the buffer.

If append is non-nil, then the specified text is appended to the existing file contents (if any).

If confirm is non-nil, then write-region asks for confirmation if filename names an existing file.

If visit is t, then Emacs establishes an association between the buffer and the file: the buffer is then visiting that file. It also sets the last file modification time for the current buffer to filename's modtime, and marks the buffer as not modified. This feature is used by save-buffer, but you probably should not use it yourself.

If visit is a string, it specifies the file name to visit. This way, you can write the data to one file (filename) while recording the buffer as visiting another file (visit). The argument visit is used in the echo area message and also for file locking; visit is stored in buffer-file-name. This feature is used to implement file-precious-flag; don't use it yourself unless you really know what you're doing.

The function write-region converts the data which it writes to the appropriate file formats specified by buffer-file-format. See section File Format Conversion. It also calls the functions in the list write-region-annotate-functions; see section Saving Text Properties in Files.

Normally, write-region displays the message `Wrote filename' in the echo area. If visit is neither t nor nil nor a string, then this message is inhibited. This feature is useful for programs that use files for internal purposes, files that the user does not need to know about.

Macro: with-temp-file file body...
The with-temp-file macro evaluates the body forms with a temporary buffer as the current buffer; then, at the end, it writes the buffer contents into file file. It kills the temporary buffer when finished, restoring the buffer that was current before the with-temp-file form. Then it returns the value of the last form in body.

The current buffer is restored even in case of an abnormal exit via throw or error (see section Nonlocal Exits).

See also with-temp-buffer in section The Current Buffer.

File Locks

When two users edit the same file at the same time, they are likely to interfere with each other. Emacs tries to prevent this situation from arising by recording a file lock when a file is being modified. Emacs can then detect the first attempt to modify a buffer visiting a file that is locked by another Emacs job, and ask the user what to do.

File locks are not completely reliable when multiple machines can share file systems. When file locks do not work, it is possible for two users to make changes simultaneously, but Emacs can still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed on disk catches some cases of simultaneous editing; see section Comparison of Modification Time.

Function: file-locked-p filename
This function returns nil if the file filename is not locked. It returns t if it is locked by this Emacs process, and it returns the name of the user who has locked it if it is locked by some other job.
(file-locked-p "foo")
     => nil
Function: lock-buffer &optional filename
This function locks the file filename, if the current buffer is modified. The argument filename defaults to the current buffer's visited file. Nothing is done if the current buffer is not visiting a file, or is not modified.

Function: unlock-buffer
This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also does nothing if the current buffer is not visiting a file.

Function: ask-user-about-lock file other-user
This function is called when the user tries to modify file, but it is locked by another user named other-user. The default definition of this function asks the user to say what to do. The value this function returns determines what Emacs does next:

A value of t says to grab the lock on the file. Then this user may edit the file and other-user loses the lock.
A value of nil says to ignore the lock and let this user edit the file anyway.
This function may instead signal a file-locked error, in which case the change that the user was about to make does not take place. The error message for this error looks like this:
error--> File is locked: file other-user
where file is the name of the file and other-user is the name of the user who has locked the file.

If you wish, you can replace the ask-user-about-lock function with your own version that makes the decision in another way. The code for its usual definition is in `userlock.el'.

Information about Files

The functions described in this section all operate on strings that designate file names. All the functions have names that begin with the word `file'. These functions all return information about actual files or directories, so their arguments must all exist as actual files or directories unless otherwise noted.

Testing Accessibility

These functions test for permission to access a file in specific ways.

Function: file-exists-p filename
This function returns t if a file named filename appears to exist. This does not mean you can necessarily read the file, only that you can find out its attributes. (On Unix, this is true if the file exists and you have execute permission on the containing directories, regardless of the protection of the file itself.)

If the file does not exist, or if fascist access control policies prevent you from finding the attributes of the file, this function returns nil.

Function: file-readable-p filename
This function returns t if a file named filename exists and you can read it. It returns nil otherwise.
(file-readable-p "files.texi")
     => t
(file-exists-p "/usr/spool/mqueue")
     => t
(file-readable-p "/usr/spool/mqueue")
     => nil
Function: file-executable-p filename
This function returns t if a file named filename exists and you can execute it. It returns nil otherwise. If the file is a directory, execute permission means you can check the existence and attributes of files inside the directory, and open those files if their modes permit.

Function: file-writable-p filename
This function returns t if the file filename can be written or created by you, and nil otherwise. A file is writable if the file exists and you can write it. It is creatable if it does not exist, but the specified directory does exist and you can write in that directory.

In the third example below, `foo' is not writable because the parent directory does not exist, even though the user could create such a directory.
(file-writable-p "~/foo")
     => t
(file-writable-p "/foo")
     => nil
(file-writable-p "~/no-such-dir/foo")
     => nil
Function: file-accessible-directory-p dirname
This function returns t if you have permission to open existing files in the directory whose name as a file is dirname; otherwise (or if there is no such directory), it returns nil. The value of dirname may be either a directory name or the file name of a file which is a directory.

Example: after the following,
(file-accessible-directory-p "/foo")
     => nil
we can deduce that any attempt to read a file in `/foo/' will give an error.

Function: access-file filename string
This function opens file filename for reading, then closes it and returns nil. However, if the open fails, it signals an error using string as the error message text.

Function: file-ownership-preserved-p filename
This function returns t if deleting the file filename and then creating it anew would keep the file's owner unchanged.

Function: file-newer-than-file-p filename1 filename2
This function returns t if the file filename1 is newer than file filename2. If filename1 does not exist, it returns nil. If filename2 does not exist, it returns t.

In the following example, assume that the file `aug-19' was written on the 19th, `aug-20' was written on the 20th, and the file `no-file' doesn't exist at all.
(file-newer-than-file-p "aug-19" "aug-20")
     => nil
(file-newer-than-file-p "aug-20" "aug-19")
     => t
(file-newer-than-file-p "aug-19" "no-file")
     => t
(file-newer-than-file-p "no-file" "aug-19")
     => nil
You can use file-attributes to get a file's last modification time as a list of two numbers. See section Other Information about Files.

Distinguishing Kinds of Files

This section describes how to distinguish various kinds of files, such as directories, symbolic links, and ordinary files.

Function: file-symlink-p filename
If the file filename is a symbolic link, the file-symlink-p function returns the file name to which it is linked. This may be the name of a text file, a directory, or even another symbolic link, or it may be a nonexistent file name.

If the file filename is not a symbolic link (or there is no such file), file-symlink-p returns nil.
(file-symlink-p "foo")
     => nil
(file-symlink-p "sym-link")
     => "foo"
(file-symlink-p "sym-link2")
     => "sym-link"
(file-symlink-p "/bin")
     => "/pub/bin"
Function: file-directory-p filename
This function returns t if filename is the name of an existing directory, nil otherwise.
(file-directory-p "~rms")
     => t
(file-directory-p "~rms/lewis/files.texi")
     => nil
(file-directory-p "~rms/lewis/no-such-file")
     => nil
(file-directory-p "$HOME")
     => nil
(file-directory-p
 (substitute-in-file-name "$HOME"))
     => t
Function: file-regular-p filename
This function returns t if the file filename exists and is a regular file (not a directory, symbolic link, named pipe, terminal, or other I/O device).

Truenames

The truename of a file is the name that you get by following symbolic links until none remain, then simplifying away `.' and `..' appearing as components. Strictly speaking, a file need not have a unique truename; the number of distinct truenames a file has is equal to the number of hard links to the file. However, truenames are useful because they eliminate symbolic links as a cause of name variation.

Function: file-truename filename
The function file-truename returns the true name of the file filename. This is the name that you get by following symbolic links until none remain. The argument must be an absolute file name.

See section Buffer File Name, for related information.

Other Information about Files

This section describes the functions for getting detailed information about a file, other than its contents. This information includes the mode bits that control access permission, the owner and group numbers, the number of names, the inode number, the size, and the times of access and modification.

Function: file-modes filename
This function returns the mode bits of filename, as an integer. The mode bits are also called the file permissions, and they specify access control in the usual Unix fashion. If the low-order bit is 1, then the file is executable by all users, if the second-lowest-order bit is 1, then the file is writable by all users, etc.

The highest value returnable is 4095 (7777 octal), meaning that everyone has read, write, and execute permission, that the SUID bit is set for both others and group, and that the sticky bit is set.
(file-modes "~/junk/diffs")
     => 492               ; Decimal integer.
(format "%o" 492)
     => "754"             ; Convert to octal.

(set-file-modes "~/junk/diffs" 438)
     => nil

(format "%o" 438)
     => "666"             ; Convert to octal.

% ls -l diffs
  -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
Function: file-nlinks filename
This functions returns the number of names (i.e., hard links) that file filename has. If the file does not exist, then this function returns nil. Note that symbolic links have no effect on this function, because they are not considered to be names of the files they link to.
% ls -l foo*
-rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
-rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1

(file-nlinks "foo")
     => 2
(file-nlinks "doesnt-exist")
     => nil
Function: file-attributes filename
This function returns a list of attributes of file filename. If the specified file cannot be opened, it returns nil.

The elements of the list, in order, are:

t for a directory, a string for a symbolic link (the name linked to), or nil for a text file.
The number of names the file has. Alternate names, also known as hard links, can be created by using the add-name-to-file function (see section Changing File Names and Attributes).
The file's UID.
The file's GID.
The time of last access, as a list of two integers. The first integer has the high-order 16 bits of time, the second has the low 16 bits. (This is similar to the value of current-time; see section Time of Day.)
The time of last modification as a list of two integers (as above).
The time of last status change as a list of two integers (as above).
The size of the file in bytes.
The file's modes, as a string of ten letters or dashes, as in `ls -l'.
t if the file's GID would change if file were deleted and recreated; nil otherwise.
The file's inode number. If possible, this is an integer. If the inode number is too large to be represented as an integer in Emacs Lisp, then the value has the form (high . low), where low holds the low 16 bits.
The file system number of the file system that the file is in. This element and the file's inode number together give enough information to distinguish any two files on the system--no two files can have the same values for both of these numbers.

For example, here are the file attributes for `files.texi':
(file-attributes "files.texi")
     =>  (nil 1 2235 75
          (8489 20284)
          (8489 20284)
          (8489 20285)
          14906 "-rw-rw-rw-"
          nil 129500 -32252)
and here is how the result is interpreted:

nil
is neither a directory nor a symbolic link.
1
has only one name (the name `files.texi' in the current default directory).
2235
is owned by the user with UID 2235.
75
is in the group with GID 75.
(8489 20284)
was last accessed on Aug 19 00:09.
(8489 20284)
was last modified on Aug 19 00:09.
(8489 20285)
last had its inode changed on Aug 19 00:09.
14906
is 14906 characters long.
"-rw-rw-rw-"
has a mode of read and write access for the owner, group, and world.
nil
would retain the same GID if it were recreated.
129500
has an inode number of 129500.
-32252
is on file system number -32252.
Changing File Names and Attributes

The functions in this section rename, copy, delete, link, and set the modes of files.

In the functions that have an argument newname, if a file by the name of newname already exists, the actions taken depend on the value of the argument ok-if-already-exists:

Signal a file-already-exists error if ok-if-already-exists is nil.
Request confirmation if ok-if-already-exists is a number.
Replace the old file without confirmation if ok-if-already-exists is any other value.

Function: add-name-to-file oldname newname &optional ok-if-already-exists
This function gives the file named oldname the additional name newname. This means that newname becomes a new "hard link" to oldname.

In the first part of the following example, we list two files, `foo' and `foo3'.
% ls -li fo*
81908 -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
Now we create a hard link, by calling add-name-to-file, then list the files again. This shows two names for one file, `foo' and `foo2'.
(add-name-to-file "foo" "foo2")
     => nil

% ls -li fo*
81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
81908 -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
84302 -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
Finally, we evaluate the following:
(add-name-to-file "foo" "foo3" t)
and list the files again. Now there are three names for one file: `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
(add-name-to-file "foo1" "foo3")
     => nil

% ls -li fo*
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
81908 -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
This function is meaningless on operating systems where multiple names for one file are not allowed.

See also file-nlinks in section Other Information about Files.

Command: rename-file filename newname &optional ok-if-already-exists
This command renames the file filename as newname.

If filename has additional names aside from filename, it continues to have those names. In fact, adding the name newname with add-name-to-file and then deleting filename has the same effect as renaming, aside from momentary intermediate states.

In an interactive call, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

Command: copy-file oldname newname &optional ok-if-exists time
This command copies the file oldname to newname. An error is signaled if oldname does not exist.

If time is non-nil, then this function gives the new file the same last-modified time that the old one has. (This works on only some operating systems.) If setting the time gets an error, copy-file signals a file-date-error error.

In an interactive call, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

Command: delete-file filename
This command deletes the file filename, like the shell command `rm filename'. If the file has multiple names, it continues to exist under the other names.

A suitable kind of file-error error is signaled if the file does not exist, or is not deletable. (On Unix, a file is deletable if its directory is writable.)

See also delete-directory in section Creating and Deleting Directories.

Command: make-symbolic-link filename newname &optional ok-if-exists
This command makes a symbolic link to filename, named newname. This is like the shell command `ln -s filename newname'.

In an interactive call, this function prompts for filename and newname in the minibuffer; also, it requests confirmation if newname already exists.

Function: define-logical-name varname string
This function defines the logical name name to have the value string. It is available only on VMS.

Function: set-file-modes filename mode
This function sets mode bits of filename to mode (which must be an integer). Only the low 12 bits of mode are used.

Function: set-default-file-modes mode
This function sets the default file protection for new files created by Emacs and its subprocesses. Every file created with Emacs initially has this protection. On Unix, the default protection is the bitwise complement of the "umask" value.

The argument mode must be an integer. On most systems, only the low 9 bits of mode are meaningful.

Saving a modified version of an existing file does not count as creating the file; it does not change the file's mode, and does not use the default file protection.

Function: default-file-modes
This function returns the current default protection value.

On MS-DOS, there is no such thing as an "executable" file mode bit. So Emacs considers a file executable if its name ends in `.com', `.bat' or `.exe'. This is reflected in the values returned by file-modes and file-attributes.

File Names

Files are generally referred to by their names, in Emacs as elsewhere. File names in Emacs are represented as strings. The functions that operate on a file all expect a file name argument.

In addition to operating on files themselves, Emacs Lisp programs often need to operate on file names; i.e., to take them apart and to use part of a name to construct related file names. This section describes how to manipulate file names.

The functions in this section do not actually access files, so they can operate on file names that do not refer to an existing file or directory.

On VMS, all these functions understand both VMS file-name syntax and Unix syntax. This is so that all the standard Lisp libraries can specify file names in Unix syntax and work properly on VMS without change. On MS-DOS and MS-Windows, these functions understand MS-DOS or MS-Windows file-name syntax as well as Unix syntax.

File Name Components

The operating system groups files into directories. To specify a file, you must specify the directory and the file's name within that directory. Therefore, Emacs considers a file name as having two main parts: the directory name part, and the nondirectory part (or file name within the directory). Either part may be empty. Concatenating these two parts reproduces the original file name.

On Unix, the directory part is everything up to and including the last slash; the nondirectory part is the rest. The rules in VMS syntax are complicated.

For some purposes, the nondirectory part is further subdivided into the name proper and the version number. On Unix, only backup files have version numbers in their names. On VMS, every file has a version number, but most of the time the file name actually used in Emacs omits the version number, so that version numbers in Emacs are found mostly in directory lists.

Function: file-name-directory filename
This function returns the directory part of filename (or nil if filename does not include a directory part). On Unix, the function returns a string ending in a slash. On VMS, it returns a string ending in one of the three characters `:', `]', or `>'.
(file-name-directory "lewis/foo")  ; Unix example
     => "lewis/"
(file-name-directory "foo")        ; Unix example
     => nil
(file-name-directory "[X]FOO.TMP") ; VMS example
     => "[X]"
Function: file-name-nondirectory filename
This function returns the nondirectory part of filename.
(file-name-nondirectory "lewis/foo")
     => "foo"
(file-name-nondirectory "foo")
     => "foo"
;; The following example is accurate only on VMS.
(file-name-nondirectory "[X]FOO.TMP")
     => "FOO.TMP"
Function: file-name-sans-versions filename
This function returns filename with any file version numbers, backup version numbers, or trailing tildes deleted.
(file-name-sans-versions "~rms/foo.~1~")
     => "~rms/foo"
(file-name-sans-versions "~rms/foo~")
     => "~rms/foo"
(file-name-sans-versions "~rms/foo")
     => "~rms/foo"
;; The following example applies to VMS only.
(file-name-sans-versions "foo;23")
     => "foo"
Function: file-name-sans-extension filename
This function returns filename minus its "extension," if any. The extension, in a file name, is the part that starts with the last `.' in the last name component. For example,
(file-name-sans-extension "foo.lose.c")
     => "foo.lose"
(file-name-sans-extension "big.hack/foo")
     => "big.hack/foo"
Directory Names

A directory name is the name of a directory. A directory is a kind of file, and it has a file name, which is related to the directory name but not identical to it. (This is not quite the same as the usual Unix terminology.) These two different names for the same entity are related by a syntactic transformation. On Unix, this is simple: a directory name ends in a slash, whereas the directory's name as a file lacks that slash. On VMS, the relationship is more complicated.

The difference between a directory name and its name as a file is subtle but crucial. When an Emacs variable or function argument is described as being a directory name, a file name of a directory is not acceptable.

The following two functions convert between directory names and file names. They do nothing special with environment variable substitutions such as `$HOME', and the constructs `~', and `..'.

Function: file-name-as-directory filename
This function returns a string representing filename in a form that the operating system will interpret as the name of a directory. In Unix, this means appending a slash to the string (if it does not already end in one). On VMS, the function converts a string of the form `[X]Y.DIR.1' to the form `[X.Y]'.
(file-name-as-directory "~rms/lewis")
     => "~rms/lewis/"
Function: directory-file-name dirname
This function returns a string representing dirname in a form that the operating system will interpret as the name of a file. On Unix, this means removing the final slash from the string. On VMS, the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
(directory-file-name "~lewis/")
     => "~lewis"
Directory name abbreviations are useful for directories that are normally accessed through symbolic links. Sometimes the users recognize primarily the link's name as "the name" of the directory, and find it annoying to see the directory's "real" name. If you define the link name as an abbreviation for the "real" name, Emacs shows users the abbreviation instead.

Variable: directory-abbrev-alist
The variable directory-abbrev-alist contains an alist of abbreviations to use for file directories. Each element has the form (from . to), and says to replace from with to when it appears in a directory name. The from string is actually a regular expression; it should always start with `^'. The function abbreviate-file-name performs these substitutions.

You can set this variable in `site-init.el' to describe the abbreviations appropriate for your site.

Here's an example, from a system on which file system `/home/fsf' and so on are normally accessed through symbolic links named `/fsf' and so on.
(("^/home/fsf" . "/fsf")
 ("^/home/gp" . "/gp")
 ("^/home/gd" . "/gd"))
To convert a directory name to its abbreviation, use this function:

Function: abbreviate-file-name dirname
This function applies abbreviations from directory-abbrev-alist to its argument, and substitutes `~' for the user's home directory.

Absolute and Relative File Names

All the directories in the file system form a tree starting at the root directory. A file name can specify all the directory names starting from the root of the tree; then it is called an absolute file name. Or it can specify the position of the file in the tree relative to a default directory; then it is called a relative file name. On Unix, an absolute file name starts with a slash or a tilde (`~'), and a relative one does not. The rules on VMS are complicated.

Function: file-name-absolute-p filename
This function returns t if file filename is an absolute file name, nil otherwise. On VMS, this function understands both Unix syntax and VMS syntax.
(file-name-absolute-p "~rms/foo")
     => t
(file-name-absolute-p "rms/foo")
     => nil
(file-name-absolute-p "/user/rms/foo")
     => t
Functions that Expand Filenames

Expansion of a file name means converting a relative file name to an absolute one. Since this is done relative to a default directory, you must specify the default directory name as well as the file name to be expanded. Expansion also simplifies file names by eliminating redundancies such as `./' and `name/../'.

Function: expand-file-name filename &optional directory
This function converts filename to an absolute file name. If directory is supplied, it is the default directory to start with if filename is relative. (The value of directory should itself be an absolute directory name; it may start with `~'.) Otherwise, the current buffer's value of default-directory is used. For example:
(expand-file-name "foo")
     => "/xcssun/users/rms/lewis/foo"
(expand-file-name "../foo")
     => "/xcssun/users/rms/foo"
(expand-file-name "foo" "/usr/spool/")
     => "/usr/spool/foo"
(expand-file-name "$HOME/foo")
     => "/xcssun/users/rms/lewis/$HOME/foo"
Filenames containing `.' or `..' are simplified to their canonical form:
(expand-file-name "bar/../foo")
     => "/xcssun/users/rms/lewis/foo"
Note that expand-file-name does not expand environment variables; only substitute-in-file-name does that.

Function: file-relative-name filename directory
This function does the inverse of expansion--it tries to return a relative name that is equivalent to filename when interpreted relative to directory.

On some operating systems, an absolute file name begins with a device name. On such systems, filename has no relative equivalent based on directory if they start with two different device names. In this case, file-relative-name returns filename in absolute form.
(file-relative-name "/foo/bar" "/foo/")
     => "bar"
(file-relative-name "/foo/bar" "/hack/")
     => "/foo/bar"
Variable: default-directory
The value of this buffer-local variable is the default directory for the current buffer. It should be an absolute directory name; it may start with `~'. This variable is buffer-local in every buffer.

expand-file-name uses the default directory when its second argument is nil.

On Unix systems, the value is always a string ending with a slash.
default-directory
     => "/user/lewis/manual/"
Function: substitute-in-file-name filename
This function replaces environment variables references in filename with the environment variable values. Following standard Unix shell syntax, `$' is the prefix to substitute an environment variable value.

The environment variable name is the series of alphanumeric characters (including underscores) that follow the `$'. If the character following the `$' is a `{', then the variable name is everything up to the matching `}'.

Here we assume that the environment variable HOME, which holds the user's home directory name, has value `/xcssun/users/rms'.
(substitute-in-file-name "$HOME/foo")
     => "/xcssun/users/rms/foo"
After substitution, if a `~' or a `/' appears following a `/', everything before the following `/' is discarded:
(substitute-in-file-name "bar/~/foo")
     => "~/foo"
(substitute-in-file-name "/usr/local/$HOME/foo")
     => "/xcssun/users/rms/foo"
     ;; `/usr/local/' has been discarded.
On VMS, `$' substitution is not done, so this function does nothing on VMS except discard superfluous initial components as shown above.

Generating Unique File Names

Some programs need to write temporary files. Here is the usual way to construct a name for such a file:
(make-temp-name
 (expand-file-name name-of-application
                   temporary-file-directory))
The job of make-temp-name is to prevent two different users or two different jobs from trying to use the exact same file name. This example uses the variable temporary-file-directory to decide where to put the temporary file. All Emacs Lisp programs should use temporary-file-directory for this purpose, to give the user a uniform way to specify the directory for all temporary files.

Function: make-temp-name string
This function generates a string that can be used as a unique file name. The name starts with string, and contains a number that is different in each Emacs job.
(make-temp-name "/tmp/foo")
     => "/tmp/foo232J6v"
To prevent conflicts among different libraries running in the same Emacs, each Lisp program that uses make-temp-name should have its own string. The number added to the end of string distinguishes between the same application running in different Emacs jobs. Additional added characters permit a large number of distinct names even in one Emacs job.

Variable: temporary-file-directory
This variable specifies the directory name for creating temporary files. Its value should be a directory name (see section Directory Names), but it is good for Lisp programs to cope if the value is a directory's file name instead. Using the value as the second argument to expand-file-name is a good way to achieve that.

The default value is determined in a reasonable way for your operating system; on GNU and Unix systems it is based on the TMP and TMPDIR environment variables.

Even if you do not use make-temp-name to choose the temporary file's name, you should still use this variable to decide which directory to put the file in.

File Name Completion

This section describes low-level subroutines for completing a file name. For other completion functions, see section Completion.

Function: file-name-all-completions partial-filename directory
This function returns a list of all possible completions for a file whose name starts with partial-filename in directory directory. The order of the completions is the order of the files in the directory, which is unpredictable and conveys no useful information.

The argument partial-filename must be a file name containing no directory part and no slash. The current buffer's default directory is prepended to directory, if directory is not absolute.

In the following example, suppose that `~rms/lewis' is the current default directory, and has five files whose names begin with `f': `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
(file-name-all-completions "f" "")
     => ("foo" "file~" "file.c.~2~"
                "file.c.~1~" "file.c")

(file-name-all-completions "fo" "")
     => ("foo")
Function: file-name-completion filename directory
This function completes the file name filename in directory directory. It returns the longest prefix common to all file names in directory directory that start with filename.

If only one match exists and filename matches it exactly, the function returns t. The function returns nil if directory directory contains no name starting with filename.

In the following example, suppose that the current default directory has five files whose names begin with `f': `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
(file-name-completion "fi" "")
     => "file"

(file-name-completion "file.c.~1" "")
     => "file.c.~1~"

(file-name-completion "file.c.~1~" "")
     => t

(file-name-completion "file.c.~3" "")
     => nil
User Option: completion-ignored-extensions
file-name-completion usually ignores file names that end in any string in this list. It does not ignore them when all the possible completions end in one of these suffixes or when a buffer showing all possible completions is displayed.

A typical value might look like this:
completion-ignored-extensions
     => (".o" ".elc" "~" ".dvi")
Standard File Names

Most of the file names used in Lisp programs are entered by the user. But occasionally a Lisp program needs to specify a standard file name for a particular use--typically, to hold customization information about each user. For example, abbrev definitions are stored (by default) in the file `~/.abbrev_defs'; the completion package stores completions in the file `~/.completions'. These are two of the many standard file names used by parts of Emacs for certain purposes.

Various operating systems have their own conventions for valid file names and for which file names to use for user profile data. A Lisp program which reads a file using a standard file name ought to use, on each type of system, a file name suitable for that system. The function convert-standard-filename makes this easy to do.

Function: convert-standard-filename filename
This function alters the file name filename to fit the conventions of the operating system in use, and returns the result as a new string.

The recommended way to specify a standard file name in a Lisp program is to choose a name which fits the conventions of GNU and Unix systems, usually with a nondirectory part that starts with a period, and pass it to convert-standard-filename instead of using it directly. Here is an example from the completion package:
(defvar save-completions-file-name
        (convert-standard-filename "~/.completions")
  "*The file name to save completions to.")
On GNU and Unix systems, and on some other systems as well, convert-standard-filename returns its argument unchanged. On some other systems, it alters the name to fit the system's conventions.

For example, on MS-DOS the alterations made by this function include converting a leading `.' to `_', converting a `_' in the middle of the name to `.' if there is no other `.', inserting a `.' after eight characters if there is none, and truncating to three characters after the `.'. (It makes other changes as well.) Thus, `.abbrev_defs' becomes `_abbrev.def', and `.completions' becomes `_complet.ion'.

Contents of Directories

A directory is a kind of file that contains other files entered under various names. Directories are a feature of the file system.

Emacs can list the names of the files in a directory as a Lisp list, or display the names in a buffer using the ls shell command. In the latter case, it can optionally display information about each file, depending on the options passed to the ls command.

Function: directory-files directory &optional full-name match-regexp nosort
This function returns a list of the names of the files in the directory directory. By default, the list is in alphabetical order.

If full-name is non-nil, the function returns the files' absolute file names. Otherwise, it returns the names relative to the specified directory.

If match-regexp is non-nil, this function returns only those file names that contain a match for that regular expression--the other file names are excluded from the list.

If nosort is non-nil, directory-files does not sort the list, so you get the file names in no particular order. Use this if you want the utmost possible speed and don't care what order the files are processed in. If the order of processing is visible to the user, then the user will probably be happier if you do sort the names.
(directory-files "~lewis")
     => ("#foo#" "#foo.el#" "." ".."
         "dired-mods.el" "files.texi"
         "files.texi.~1~")
An error is signaled if directory is not the name of a directory that can be read.

Function: file-name-all-versions file dirname
This function returns a list of all versions of the file named file in directory dirname.

Function: insert-directory file switches &optional wildcard full-directory-p
This function inserts (in the current buffer) a directory listing for directory file, formatted with ls according to switches. It leaves point after the inserted text.

The argument file may be either a directory name or a file specification including wildcard characters. If wildcard is non-nil, that means treat file as a file specification with wildcards.

If full-directory-p is non-nil, that means the directory listing is expected to show the full contents of a directory. You should specify t when file is a directory and switches do not contain `-d'. (The `-d' option to ls says to describe a directory itself as a file, rather than showing its contents.)

This function works by running a directory listing program whose name is in the variable insert-directory-program. If wildcard is non-nil, it also runs the shell specified by shell-file-name, to expand the wildcards.

Variable: insert-directory-program
This variable's value is the program to run to generate a directory listing for the function insert-directory.

Creating and Deleting Directories

Most Emacs Lisp file-manipulation functions get errors when used on files that are directories. For example, you cannot delete a directory with delete-file. These special functions exist to create and delete directories.

Function: make-directory dirname
This function creates a directory named dirname.

Function: delete-directory dirname
This function deletes the directory named dirname. The function delete-file does not work for files that are directories; you must use delete-directory for them. If the directory contains any files, delete-directory signals an error.

Making Certain File Names "Magic"

You can implement special handling for certain file names. This is called making those names magic. The principal use for this feature is in implementing remote file names (see section `Remote Files' in The GNU Emacs Manual).

To define a kind of magic file name, you must supply a regular expression to define the class of names (all those that match the regular expression), plus a handler that implements all the primitive Emacs file operations for file names that do match.

The variable file-name-handler-alist holds a list of handlers, together with regular expressions that determine when to apply each handler. Each element has this form:
(regexp . handler)
All the Emacs primitives for file access and file name transformation check the given file name against file-name-handler-alist. If the file name matches regexp, the primitives handle that file by calling handler.

The first argument given to handler is the name of the primitive; the remaining arguments are the arguments that were passed to that operation. (The first of these arguments is typically the file name itself.) For example, if you do this:
(file-exists-p filename)
and filename has handler handler, then handler is called like this:
(funcall handler 'file-exists-p filename)
Here are the operations that a magic file name handler gets to handle:

add-name-to-file, copy-file, delete-directory, delete-file, diff-latest-backup-file, directory-file-name, directory-files, dired-call-process, dired-compress-file, dired-uncache, expand-file-name, file-accessible-direc@discretionary{{}{}tory-p}, file-attributes, file-direct@discretionary{{}{}ory-p}, file-executable-p, file-exists-p, file-local-copy, file-modes, file-name-all-completions, file-name-as-directory, file-name-completion, file-name-directory, file-name-nondirec@discretionary{{}{}tory}, file-name-sans-versions, file-newer-than-file-p, file-ownership-pre@discretionary{{}{}served-p}, file-readable-p, file-regular-p, file-symlink-p, file-truename, file-writable-p, find-backup-file-name, get-file-buffer, insert-directory, insert-file-contents, load, make-direc@discretionary{{}{}tory}, make-symbolic-link, rename-file, set-file-modes, set-visited-file-modtime, shell-command, unhandled-file-name-directory, vc-regis@discretionary{{}{}tered}, verify-visited-file-modtime, write-region.

Handlers for insert-file-contents typically need to clear the buffer's modified flag, with (set-buffer-modified-p nil), if the visit argument is non-nil. This also has the effect of unlocking the buffer if it is locked.

The handler function must handle all of the above operations, and possibly others to be added in the future. It need not implement all these operations itself--when it has nothing special to do for a certain operation, it can reinvoke the primitive, to handle the operation "in the usual way". It should always reinvoke the primitive for an operation it does not recognize. Here's one way to do this:
(defun my-file-handler (operation &rest args)
  ;; First check for the specific operations
  ;; that we have special handling for.
  (cond ((eq operation 'insert-file-contents) ...)
        ((eq operation 'write-region) ...)
        ...
        ;; Handle any operation we don't know about.
        (t (let ((inhibit-file-name-handlers
                  (cons 'my-file-handler
                        (and (eq inhibit-file-name-operation operation)
                             inhibit-file-name-handlers)))
                 (inhibit-file-name-operation operation))
             (apply operation args)))))
When a handler function decides to call the ordinary Emacs primitive for the operation at hand, it needs to prevent the primitive from calling the same handler once again, thus leading to an infinite recursion. The example above shows how to do this, with the variables inhibit-file-name-handlers and inhibit-file-name-operation. Be careful to use them exactly as shown above; the details are crucial for proper behavior in the case of multiple handlers, and for operations that have two file names that may each have handlers.

Variable: inhibit-file-name-handlers
This variable holds a list of handlers whose use is presently inhibited for a certain operation.

Variable: inhibit-file-name-operation
The operation for which certain handlers are presently inhibited.

Function: find-file-name-handler file operation
This function returns the handler function for file name file, or nil if there is none. The argument operation should be the operation to be performed on the file--the value you will pass to the handler as its first argument when you call it. The operation is needed for comparison with inhibit-file-name-operation.

Function: file-local-copy filename
This function copies file filename to an ordinary non-magic file, if it isn't one already.

If filename specifies a magic file name, which programs outside Emacs cannot directly read or write, this copies the contents to an ordinary file and returns that file's name.

If filename is an ordinary file name, not magic, then this function does nothing and returns nil.

Function: unhandled-file-name-directory filename
This function returns the name of a directory that is not magic. It uses the directory part of filename if that is not magic. For a magic file name, it invokes the file name handler, which therefore decides what value to return.

This is useful for running a subprocess; every subprocess must have a non-magic directory to serve as its current directory, and this function is a good way to come up with one.

File Format Conversion

The variable format-alist defines a list of file formats, which describe textual representations used in files for the data (text, text-properties, and possibly other information) in an Emacs buffer. Emacs performs format conversion if appropriate when reading and writing files.

Variable: format-alist
This list contains one format definition for each defined file format.

Each format definition is a list of this form:
(name doc-string regexp from-fn to-fn modify mode-fn)
Here is what the elements in a format definition mean:

name
The name of this format.
doc-string
A documentation string for the format.
regexp
A regular expression which is used to recognize files represented in this format.
from-fn
A shell command or function to decode data in this format (to convert file data into the usual Emacs data representation). A shell command is represented as a string; Emacs runs the command as a filter to perform the conversion. If from-fn is a function, it is called with two arguments, begin and end, which specify the part of the buffer it should convert. It should convert the text by editing it in place. Since this can change the length of the text, from-fn should return the modified end position. One responsibility of from-fn is to make sure that the beginning of the file no longer matches regexp. Otherwise it is likely to get called again.
to-fn
A shell command or function to encode data in this format--that is, to convert the usual Emacs data representation into this format. If to-fn is a string, it is a shell command; Emacs runs the command as a filter to perform the conversion. If to-fn is a function, it is called with two arguments, begin and end, which specify the part of the buffer it should convert. There are two ways it can do the conversion:

By editing the buffer in place. In this case, to-fn should return the end-position of the range of text, as modified.
By returning a list of annotations. This is a list of elements of the form (position . string), where position is an integer specifying the relative position in the text to be written, and string is the annotation to add there. The list must be sorted in order of position when to-fn returns it. When write-region actually writes the text from the buffer to the file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer.

modify
A flag, t if the encoding function modifies the buffer, and nil if it works by returning a list of annotations.
mode
A mode function to call after visiting a file converted from this format.
The function insert-file-contents automatically recognizes file formats when it reads the specified file. It checks the text of the beginning of the file against the regular expressions of the format definitions, and if it finds a match, it calls the decoding function for that format. Then it checks all the known formats over again. It keeps checking them until none of them is applicable.

Visiting a file, with find-file-noselect or the commands that use it, performs conversion likewise (because it calls insert-file-contents); it also calls the mode function for each format that it decodes. It stores a list of the format names in the buffer-local variable buffer-file-format.

Variable: buffer-file-format
This variable states the format of the visited file. More precisely, this is a list of the file format names that were decoded in the course of visiting the current buffer's file. It is always buffer-local in all buffers.

When write-region writes data into a file, it first calls the encoding functions for the formats listed in buffer-file-format, in the order of appearance in the list.

Command: format-write-file file format
This command writes the current buffer contents into the file file in format format, and makes that format the default for future saves of the buffer. The argument format is a list of format names.

Command: format-find-file file format
This command finds the file file, converting it according to format format. It also makes format the default if the buffer is saved later.

The argument format is a list of format names. If format is nil, no conversion takes place. Interactively, typing just RET for format specifies nil.

Command: format-insert-file file format &optional beg end
This command inserts the contents of file file, converting it according to format format. If beg and end are non-nil, they specify which part of the file to read, as in insert-file-contents (see section Reading from Files).

The return value is like what insert-file-contents returns: a list of the absolute file name and the length of the data inserted (after conversion).

The argument format is a list of format names. If format is nil, no conversion takes place. Interactively, typing just RET for format specifies nil.

Variable: auto-save-file-format
This variable specifies the format to use for auto-saving. Its value is a list of format names, just like the value of buffer-file-format; however, it is used instead of buffer-file-format for writing auto-save files. This variable is always buffer-local in all buffers.

Backups and Auto-Saving

Backup files and auto-save files are two methods by which Emacs tries to protect the user from the consequences of crashes or of the user's own errors. Auto-saving preserves the text from earlier in the current editing session; backup files preserve file contents prior to the current session.

Backup Files

A backup file is a copy of the old contents of a file you are editing. Emacs makes a backup file the first time you save a buffer into its visited file. Normally, this means that the backup file contains the contents of the file as it was before the current editing session. The contents of the backup file normally remain unchanged once it exists.

Backups are usually made by renaming the visited file to a new name. Optionally, you can specify that backup files should be made by copying the visited file. This choice makes a difference for files with multiple names; it also can affect whether the edited file remains owned by the original owner or becomes owned by the user editing it.

By default, Emacs makes a single backup file for each file edited. You can alternatively request numbered backups; then each new backup file gets a new name. You can delete old numbered backups when you don't want them any more, or Emacs can delete them automatically.

Making Backup Files

Function: backup-buffer
This function makes a backup of the file visited by the current buffer, if appropriate. It is called by save-buffer before saving the buffer the first time.

Variable: buffer-backed-up
This buffer-local variable indicates whether this buffer's file has been backed up on account of this buffer. If it is non-nil, then the backup file has been written. Otherwise, the file should be backed up when it is next saved (if backups are enabled). This is a permanent local; kill-local-variables does not alter it.

User Option: make-backup-files
This variable determines whether or not to make backup files. If it is non-nil, then Emacs creates a backup of each file when it is saved for the first time--provided that backup-inhibited is nil (see below).

The following example shows how to change the make-backup-files variable only in the Rmail buffers and not elsewhere. Setting it nil stops Emacs from making backups of these files, which may save disk space. (You would put this code in your `.emacs' file.)
(add-hook 'rmail-mode-hook
          (function (lambda ()
                      (make-local-variable
                       'make-backup-files)
                      (setq make-backup-files nil))))
Variable: backup-enable-predicate
This variable's value is a function to be called on certain occasions to decide whether a file should have backup files. The function receives one argument, a file name to consider. If the function returns nil, backups are disabled for that file. Otherwise, the other variables in this section say whether and how to make backups.

The default value is this:
(lambda (name)
  (or (< (length name) 5)
      (not (string-equal "/tmp/"
                         (substring name 0 5)))))
Variable: backup-inhibited
If this variable is non-nil, backups are inhibited. It records the result of testing backup-enable-predicate on the visited file name. It can also coherently be used by other mechanisms that inhibit backups based on which file is visited. For example, VC sets this variable non-nil to prevent making backups for files managed with a version control system.

This is a permanent local, so that changing the major mode does not lose its value. Major modes should not set this variable--they should set make-backup-files instead.

Backup by Renaming or by Copying?

There are two ways that Emacs can make a backup file:

Emacs can rename the original file so that it becomes a backup file, and then write the buffer being saved into a new file. After this procedure, any other names (i.e., hard links) of the original file now refer to the backup file. The new file is owned by the user doing the editing, and its group is the default for new files written by the user in that directory.
Emacs can copy the original file into a backup file, and then overwrite the original file with new contents. After this procedure, any other names (i.e., hard links) of the original file continue to refer to the current (updated) version of the file. The file's owner and group will be unchanged.

The first method, renaming, is the default.

The variable backup-by-copying, if non-nil, says to use the second method, which is to copy the original file and overwrite it with the new buffer contents. The variable file-precious-flag, if non-nil, also has this effect (as a sideline of its main significance). See section Saving Buffers.

Variable: backup-by-copying
If this variable is non-nil, Emacs always makes backup files by copying.

The following two variables, when non-nil, cause the second method to be used in certain special cases. They have no effect on the treatment of files that don't fall into the special cases.

Variable: backup-by-copying-when-linked
If this variable is non-nil, Emacs makes backups by copying for files with multiple names (hard links).

This variable is significant only if backup-by-copying is nil, since copying is always used when that variable is non-nil.

Variable: backup-by-copying-when-mismatch
If this variable is non-nil, Emacs makes backups by copying in cases where renaming would change either the owner or the group of the file.

The value has no effect when renaming would not alter the owner or group of the file; that is, for files which are owned by the user and whose group matches the default for a new file created there by the user.

This variable is significant only if backup-by-copying is nil, since copying is always used when that variable is non-nil.

Making and Deleting Numbered Backup Files

If a file's name is `foo', the names of its numbered backup versions are `foo.~v~', for various integers v, like this: `foo.~1~', `foo.~2~', `foo.~3~', ..., `foo.~259~', and so on.

User Option: version-control
This variable controls whether to make a single non-numbered backup file or multiple numbered backups.

nil
Make numbered backups if the visited file already has numbered backups; otherwise, do not.
never
Do not make numbered backups.
anything else
Make numbered backups.
The use of numbered backups ultimately leads to a large number of backup versions, which must then be deleted. Emacs can do this automatically or it can ask the user whether to delete them.

User Option: kept-new-versions
The value of this variable is the number of newest versions to keep when a new numbered backup is made. The newly made backup is included in the count. The default value is 2.

User Option: kept-old-versions
The value of this variable is the number of oldest versions to keep when a new numbered backup is made. The default value is 2.

If there are backups numbered 1, 2, 3, 5, and 7, and both of these variables have the value 2, then the backups numbered 1 and 2 are kept as old versions and those numbered 5 and 7 are kept as new versions; backup version 3 is excess. The function find-backup-file-name (see section Naming Backup Files) is responsible for determining which backup versions to delete, but does not delete them itself.

User Option: delete-old-versions
If this variable is non-nil, then saving a file deletes excess backup versions silently. Otherwise, it asks the user whether to delete them.

User Option: dired-kept-versions
This variable specifies how many of the newest backup versions to keep in the Dired command . (dired-clean-directory). That's the same thing kept-new-versions specifies when you make a new backup file. The default value is 2.

Naming Backup Files

The functions in this section are documented mainly because you can customize the naming conventions for backup files by redefining them. If you change one, you probably need to change the rest.

Function: backup-file-name-p filename
This function returns a non-nil value if filename is a possible name for a backup file. A file with the name filename need not exist; the function just checks the name.
(backup-file-name-p "foo")
     => nil
(backup-file-name-p "foo~")
     => 3
The standard definition of this function is as follows:
(defun backup-file-name-p (file)
  "Return non-nil if FILE is a backup file \
name (numeric or not)..."
  (string-match "~$" file))
Thus, the function returns a non-nil value if the file name ends with a `~'. (We use a backslash to split the documentation string's first line into two lines in the text, but produce just one line in the string itself.)

This simple expression is placed in a separate function to make it easy to redefine for customization.

Function: make-backup-file-name filename
This function returns a string that is the name to use for a non-numbered backup file for file filename. On Unix, this is just filename with a tilde appended.

The standard definition of this function, on most operating systems, is as follows:
(defun make-backup-file-name (file)
  "Create the non-numeric backup file name for FILE@enddots{}"
  (concat file "~"))
You can change the backup-file naming convention by redefining this function. The following example redefines make-backup-file-name to prepend a `.' in addition to appending a tilde:
(defun make-backup-file-name (filename)
  (expand-file-name
    (concat "." (file-name-nondirectory filename) "~")
    (file-name-directory filename)))

(make-backup-file-name "backups.texi")
     => ".backups.texi~"
Some parts of Emacs, including some Dired commands, assume that backup file names end with `~'. If you do not follow that convention, it will not cause serious problems, but these commands may give less-than-desirable results.

Function: find-backup-file-name filename
This function computes the file name for a new backup file for filename. It may also propose certain existing backup files for deletion. find-backup-file-name returns a list whose CAR is the name for the new backup file and whose CDR is a list of backup files whose deletion is proposed.

Two variables, kept-old-versions and kept-new-versions, determine which backup versions should be kept. This function keeps those versions by excluding them from the CDR of the value. See section Making and Deleting Numbered Backup Files.

In this example, the value says that `~rms/foo.~5~' is the name to use for the new backup file, and `~rms/foo.~3~' is an "excess" version that the caller should consider deleting now.
(find-backup-file-name "~rms/foo")
     => ("~rms/foo.~5~" "~rms/foo.~3~")
Function: file-newest-backup filename
This function returns the name of the most recent backup file for filename, or nil if that file has no backup files.

Some file comparison commands use this function so that they can automatically compare a file with its most recent backup.

Auto-Saving

Emacs periodically saves all files that you are visiting; this is called auto-saving. Auto-saving prevents you from losing more than a limited amount of work if the system crashes. By default, auto-saves happen every 300 keystrokes, or after around 30 seconds of idle time. See section `Auto-Saving: Protection Against Disasters' in The GNU Emacs Manual, for information on auto-save for users. Here we describe the functions used to implement auto-saving and the variables that control them.

Variable: buffer-auto-save-file-name
This buffer-local variable is the name of the file used for auto-saving the current buffer. It is nil if the buffer should not be auto-saved.
buffer-auto-save-file-name
=> "/xcssun/users/rms/lewis/#files.texi#"
Command: auto-save-mode arg
When used interactively without an argument, this command is a toggle switch: it turns on auto-saving of the current buffer if it is off, and vice-versa. With an argument arg, the command turns auto-saving on if the value of arg is t, a nonempty list, or a positive integer. Otherwise, it turns auto-saving off.

Function: auto-save-file-name-p filename
This function returns a non-nil value if filename is a string that could be the name of an auto-save file. It works based on knowledge of the naming convention for auto-save files: a name that begins and ends with hash marks (`#') is a possible auto-save file name. The argument filename should not contain a directory part.
(make-auto-save-file-name)
     => "/xcssun/users/rms/lewis/#files.texi#"
(auto-save-file-name-p "#files.texi#")
     => 0
(auto-save-file-name-p "files.texi")
     => nil
The standard definition of this function is as follows:
(defun auto-save-file-name-p (filename)
  "Return non-nil if FILENAME can be yielded by..."
  (string-match "^#.*#$" filename))
This function exists so that you can customize it if you wish to change the naming convention for auto-save files. If you redefine it, be sure to redefine the function make-auto-save-file-name correspondingly.

Function: make-auto-save-file-name
This function returns the file name to use for auto-saving the current buffer. This is just the file name with hash marks (`#') appended and prepended to it. This function does not look at the variable auto-save-visited-file-name (described below); you should check that before calling this function.
(make-auto-save-file-name)
     => "/xcssun/users/rms/lewis/#backup.texi#"
The standard definition of this function is as follows:
(defun make-auto-save-file-name ()
  "Return file name to use for auto-saves \
of current buffer@enddots{}"
  (if buffer-file-name
      (concat
       (file-name-directory buffer-file-name)
       "#"
       (file-name-nondirectory buffer-file-name)
       "#")
    (expand-file-name
     (concat "#%" (buffer-name) "#"))))
This exists as a separate function so that you can redefine it to customize the naming convention for auto-save files. Be sure to change auto-save-file-name-p in a corresponding way.

Variable: auto-save-visited-file-name
If this variable is non-nil, Emacs auto-saves buffers in the files they are visiting. That is, the auto-save is done in the same file that you are editing. Normally, this variable is nil, so auto-save files have distinct names that are created by make-auto-save-file-name.

When you change the value of this variable, the value does not take effect until the next time auto-save mode is reenabled in any given buffer. If auto-save mode is already enabled, auto-saves continue to go in the same file name until auto-save-mode is called again.

Function: recent-auto-save-p
This function returns t if the current buffer has been auto-saved since the last time it was read in or saved.

Function: set-buffer-auto-saved
This function marks the current buffer as auto-saved. The buffer will not be auto-saved again until the buffer text is changed again. The function returns nil.

User Option: auto-save-interval
The value of this variable is the number of characters that Emacs reads from the keyboard between auto-saves. Each time this many more characters are read, auto-saving is done for all buffers in which it is enabled.

User Option: auto-save-timeout
The value of this variable is the number of seconds of idle time that should cause auto-saving. Each time the user pauses for this long, Emacs auto-saves any buffers that need it. (Actually, the specified timeout is multiplied by a factor depending on the size of the current buffer.)

Variable: auto-save-hook
This normal hook is run whenever an auto-save is about to happen.

User Option: auto-save-default
If this variable is non-nil, buffers that are visiting files have auto-saving enabled by default. Otherwise, they do not.

Command: do-auto-save &optional no-message current-only
This function auto-saves all buffers that need to be auto-saved. It saves all buffers for which auto-saving is enabled and that have been changed since the previous auto-save.

Normally, if any buffers are auto-saved, a message that says `Auto-saving...' is displayed in the echo area while auto-saving is going on. However, if no-message is non-nil, the message is inhibited.

If current-only is non-nil, only the current buffer is auto-saved.

Function: delete-auto-save-file-if-necessary
This function deletes the current buffer's auto-save file if delete-auto-save-files is non-nil. It is called every time a buffer is saved.

Variable: delete-auto-save-files
This variable is used by the function delete-auto-save-file-if-necessary. If it is non-nil, Emacs deletes auto-save files when a true save is done (in the visited file). This saves disk space and unclutters your directory.

Function: rename-auto-save-file
This function adjusts the current buffer's auto-save file name if the visited file name has changed. It also renames an existing auto-save file. If the visited file name has not changed, this function does nothing.

Variable: buffer-saved-size
The value of this buffer-local variable is the length of the current buffer as of the last time it was read in, saved, or auto-saved. This is used to detect a substantial decrease in size, and turn off auto-saving in response.

If it is -1, that means auto-saving is temporarily shut off in this buffer due to a substantial deletion. Explicitly saving the buffer stores a positive value in this variable, thus reenabling auto-saving. Turning auto-save mode off or on also alters this variable.

Variable: auto-save-list-file-name
This variable (if non-nil) specifies a file for recording the names of all the auto-save files. Each time Emacs does auto-saving, it writes two lines into this file for each buffer that has auto-saving enabled. The first line gives the name of the visited file (it's empty if the buffer has none), and the second gives the name of the auto-save file.

If Emacs exits normally, it deletes this file. If Emacs crashes, you can look in the file to find all the auto-save files that might contain work that was otherwise lost. The recover-session command uses these files.

The default name for this file is in your home directory and starts with `.saves-'. It also contains the Emacs process ID and the host name.

Reverting

If you have made extensive changes to a file and then change your mind about them, you can get rid of them by reading in the previous version of the file with the revert-buffer command. See section `Reverting a Buffer' in The GNU Emacs Manual.

Command: revert-buffer &optional ignore-auto noconfirm
This command replaces the buffer text with the text of the visited file on disk. This action undoes all changes since the file was visited or saved.

By default, if the latest auto-save file is more recent than the visited file, revert-buffer asks the user whether to use that instead. But if the argument ignore-auto is non-nil, then only the the visited file itself is used. Interactively, ignore-auto is t unless there is a numeric prefix argument; thus, the interactive default is to check the auto-save file.

Normally, revert-buffer asks for confirmation before it changes the buffer; but if the argument noconfirm is non-nil, revert-buffer does not ask for confirmation.

Reverting tries to preserve marker positions in the buffer by using the replacement feature of insert-file-contents. If the buffer contents and the file contents are identical before the revert operation, reverting preserves all the markers. If they are not identical, reverting does change the buffer; then it preserves the markers in the unchanged text (if any) at the beginning and end of the buffer. Preserving any additional markers would be problematical.

You can customize how revert-buffer does its work by setting these variables--typically, as buffer-local variables.

Variable: revert-without-query
This variable holds a list of files that should be reverted without query. The value is a list of regular expressions. If a file name matches one of these regular expressions, then revert-buffer reverts the file without asking the user for confirmation, if the file has changed on disk and the buffer is not modified.

Variable: revert-buffer-function
The value of this variable is the function to use to revert this buffer. If non-nil, it is called as a function with no arguments to do the work of reverting. If the value is nil, reverting works the usual way.

Modes such as Dired mode, in which the text being edited does not consist of a file's contents but can be regenerated in some other fashion, give this variable a buffer-local value that is a function to regenerate the contents.

Variable: revert-buffer-insert-file-contents-function
The value of this variable, if non-nil, is the function to use to insert the updated contents when reverting this buffer. The function receives two arguments: first the file name to use; second, t if the user has asked to read the auto-save file.

Variable: before-revert-hook
This normal hook is run by revert-buffer before actually inserting the modified contents--but only if revert-buffer-function is nil.

Font Lock mode uses this hook to record that the buffer contents are no longer fontified.

Variable: after-revert-hook
This normal hook is run by revert-buffer after actually inserting the modified contents--but only if revert-buffer-function is nil.

Font Lock mode uses this hook to recompute the fonts for the updated buffer contents.

Buffers

A buffer is a Lisp object containing text to be edited. Buffers are used to hold the contents of files that are being visited; there may also be buffers that are not visiting files. While several buffers may exist at one time, exactly one buffer is designated the current buffer at any time. Most editing commands act on the contents of the current buffer. Each buffer, including the current buffer, may or may not be displayed in any windows.

Buffer Basics

Buffers in Emacs editing are objects that have distinct names and hold text that can be edited. Buffers appear to Lisp programs as a special data type. You can think of the contents of a buffer as a string that you can extend; insertions and deletions may occur in any part of the buffer. See section Text.

A Lisp buffer object contains numerous pieces of information. Some of this information is directly accessible to the programmer through variables, while other information is accessible only through special-purpose functions. For example, the visited file name is directly accessible through a variable, while the value of point is accessible only through a primitive function.

Buffer-specific information that is directly accessible is stored in buffer-local variable bindings, which are variable values that are effective only in a particular buffer. This feature allows each buffer to override the values of certain variables. Most major modes override variables such as fill-column or comment-column in this way. For more information about buffer-local variables and functions related to them, see section Buffer-Local Variables.

For functions and variables related to visiting files in buffers, see section Visiting Files and section Saving Buffers. For functions and variables related to the display of buffers in windows, see section Buffers and Windows.

Function: bufferp object
This function returns t if object is a buffer, nil otherwise.

The Current Buffer

There are, in general, many buffers in an Emacs session. At any time, one of them is designated as the current buffer. This is the buffer in which most editing takes place, because most of the primitives for examining or changing text in a buffer operate implicitly on the current buffer (see section Text). Normally the buffer that is displayed on the screen in the selected window is the current buffer, but this is not always so: a Lisp program can temporarily designate any buffer as current in order to operate on its contents, without changing what is displayed on the screen.

The way to designate a current buffer in a Lisp program is by calling set-buffer. The specified buffer remains current until a new one is designated.

When an editing command returns to the editor command loop, the command loop designates the buffer displayed in the selected window as current, to prevent confusion: the buffer that the cursor is in when Emacs reads a command is the buffer that the command will apply to. (See section Command Loop.) Therefore, set-buffer is not the way to switch visibly to a different buffer so that the user can edit it. For this, you must use the functions described in section Displaying Buffers in Windows.

However, Lisp functions that change to a different current buffer should not depend on the command loop to set it back afterwards. Editing commands written in Emacs Lisp can be called from other programs as well as from the command loop. It is convenient for the caller if the subroutine does not change which buffer is current (unless, of course, that is the subroutine's purpose). Therefore, you should normally use set-buffer within a save-current-buffer or save-excursion (see section Excursions) form that will restore the current buffer when your function is done. Here is an example, the code for the command append-to-buffer (with the documentation string abridged):
(defun append-to-buffer (buffer start end)
  "Append to specified buffer the text of the region.
..."
  (interactive "BAppend to buffer: \nr")
  (let ((oldbuf (current-buffer)))
    (save-current-buffer
      (set-buffer (get-buffer-create buffer))
      (insert-buffer-substring oldbuf start end))))
This function binds a local variable to record the current buffer, and then save-current-buffer arranges to make it current again. Next, set-buffer makes the specified buffer current. Finally, insert-buffer-substring copies the string from the original current buffer to the specified (and now current) buffer.

If the buffer appended to happens to be displayed in some window, the next redisplay will show how its text has changed. Otherwise, you will not see the change immediately on the screen. The buffer becomes current temporarily during the execution of the command, but this does not cause it to be displayed.

If you make local bindings (with let or function arguments) for a variable that may also have buffer-local bindings, make sure that the same buffer is current at the beginning and at the end of the local binding's scope. Otherwise you might bind it in one buffer and unbind it in another! There are two ways to do this. In simple cases, you may see that nothing ever changes the current buffer within the scope of the binding. Otherwise, use save-current-buffer or save-excursion to make sure that the buffer current at the beginning is current again whenever the variable is unbound.

It is not reliable to change the current buffer back with set-buffer, because that won't do the job if a quit happens while the wrong buffer is current. Here is what not to do:
(let (buffer-read-only
      (obuf (current-buffer)))
  (set-buffer ...)
  ...
  (set-buffer obuf))
Using save-current-buffer, as shown here, handles quitting, errors, and throw, as well as ordinary evaluation.
(let (buffer-read-only)
  (save-current-buffer
    (set-buffer ...)
    ...))
Function: current-buffer
This function returns the current buffer.
(current-buffer)
     => #<buffer buffers.texi>
Function: set-buffer buffer-or-name
This function makes buffer-or-name the current buffer. It does not display the buffer in the currently selected window or in any other window, so the user cannot necessarily see the buffer. But Lisp programs can in any case work on it.

This function returns the buffer identified by buffer-or-name. An error is signaled if buffer-or-name does not identify an existing buffer.

Special Form: save-current-buffer body...
The save-current-buffer macro saves the identity of the current buffer, evaluates the body forms, and finally restores that buffer as current. The return value is the value of the last form in body. The current buffer is restored even in case of an abnormal exit via throw or error (see section Nonlocal Exits).

If the buffer that used to be current has been killed by the time of exit from save-current-buffer, then it is not made current again, of course. Instead, whichever buffer was current just before exit remains current.

Macro: with-current-buffer buffer body...
The with-current-buffer macro saves the identity of the current buffer, makes buffer current, evaluates the body forms, and finally restores the buffer. The return value is the value of the last form in body. The current buffer is restored even in case of an abnormal exit via throw or error (see section Nonlocal Exits).

Macro: with-temp-buffer body...
The with-temp-buffer macro evaluates the body forms with a temporary buffer as the current buffer. It saves the identity of the current buffer, creates a temporary buffer and makes it current, evaluates the body forms, and finally restores the previous current buffer while killing the temporary buffer.

The return value is the value of the last form in body. You can return the contents of the temporary buffer by using (buffer-string) as the last form.

The current buffer is restored even in case of an abnormal exit via throw or error (see section Nonlocal Exits).

See also with-temp-file in section Writing to Files.

Buffer Names

Each buffer has a unique name, which is a string. Many of the functions that work on buffers accept either a buffer or a buffer name as an argument. Any argument called buffer-or-name is of this sort, and an error is signaled if it is neither a string nor a buffer. Any argument called buffer must be an actual buffer object, not a name.

Buffers that are ephemeral and generally uninteresting to the user have names starting with a space, so that the list-buffers and buffer-menu commands don't mention them. A name starting with space also initially disables recording undo information; see section Undo.

Function: buffer-name &optional buffer
This function returns the name of buffer as a string. If buffer is not supplied, it defaults to the current buffer.

If buffer-name returns nil, it means that buffer has been killed. See section Killing Buffers.
(buffer-name)
     => "buffers.texi"

(setq foo (get-buffer "temp"))
     => #<buffer temp>
(kill-buffer foo)
     => nil
(buffer-name foo)
     => nil
foo
     => #<killed buffer>
Command: rename-buffer newname &optional unique
This function renames the current buffer to newname. An error is signaled if newname is not a string, or if there is already a buffer with that name. The function returns newname.

Ordinarily, rename-buffer signals an error if newname is already in use. However, if unique is non-nil, it modifies newname to make a name that is not in use. Interactively, you can make unique non-nil with a numeric prefix argument.

One application of this command is to rename the `*shell*' buffer to some other name, thus making it possible to create a second shell buffer under the name `*shell*'.

Function: get-buffer buffer-or-name
This function returns the buffer specified by buffer-or-name. If buffer-or-name is a string and there is no buffer with that name, the value is nil. If buffer-or-name is a buffer, it is returned as given. (That is not very useful, so the argument is usually a name.) For example:
(setq b (get-buffer "lewis"))
     => #<buffer lewis>
(get-buffer b)
     => #<buffer lewis>
(get-buffer "Frazzle-nots")
     => nil
See also the function get-buffer-create in section Creating Buffers.

Function: generate-new-buffer-name starting-name
This function returns a name that would be unique for a new buffer--but does not create the buffer. It starts with starting-name, and produces a name not currently in use for any buffer by appending a number inside of `<...>'.

See the related function generate-new-buffer in section Creating Buffers.

Buffer File Name

The buffer file name is the name of the file that is visited in that buffer. When a buffer is not visiting a file, its buffer file name is nil. Most of the time, the buffer name is the same as the nondirectory part of the buffer file name, but the buffer file name and the buffer name are distinct and can be set independently. See section Visiting Files.

Function: buffer-file-name &optional buffer
This function returns the absolute file name of the file that buffer is visiting. If buffer is not visiting any file, buffer-file-name returns nil. If buffer is not supplied, it defaults to the current buffer.
(buffer-file-name (other-buffer))
     => "/usr/user/lewis/manual/files.texi"
Variable: buffer-file-name
This buffer-local variable contains the name of the file being visited in the current buffer, or nil if it is not visiting a file. It is a permanent local, unaffected by kill-local-variables.
buffer-file-name
     => "/usr/user/lewis/manual/buffers.texi"
It is risky to change this variable's value without doing various other things. Normally it is better to use set-visited-file-name (see below); some of the things done there, such as changing the buffer name, are not strictly necessary, but others are essential to avoid confusing Emacs.

Variable: buffer-file-truename
This buffer-local variable holds the truename of the file visited in the current buffer, or nil if no file is visited. It is a permanent local, unaffected by kill-local-variables. See section Truenames.

Variable: buffer-file-number
This buffer-local variable holds the file number and directory device number of the file visited in the current buffer, or nil if no file or a nonexistent file is visited. It is a permanent local, unaffected by kill-local-variables.

The value is normally a list of the form (filenum devnum). This pair of numbers uniquely identifies the file among all files accessible on the system. See the function file-attributes, in section Other Information about Files, for more information about them.

Function: get-file-buffer filename
This function returns the buffer visiting file filename. If there is no such buffer, it returns nil. The argument filename, which must be a string, is expanded (see section Functions that Expand Filenames), then compared against the visited file names of all live buffers.
(get-file-buffer "buffers.texi")
    => #<buffer buffers.texi>
In unusual circumstances, there can be more than one buffer visiting the same file name. In such cases, this function returns the first such buffer in the buffer list.

Command: set-visited-file-name filename &optional no-query along-with-file
If filename is a non-empty string, this function changes the name of the file visited in current buffer to filename. (If the buffer had no visited file, this gives it one.) The next time the buffer is saved it will go in the newly-specified file. This command marks the buffer as modified, since it does not (as far as Emacs knows) match the contents of filename, even if it matched the former visited file.

If filename is nil or the empty string, that stands for "no visited file". In this case, set-visited-file-name marks the buffer as having no visited file.

Normally, this function asks the user for confirmation if the specified file already exists. If no-query is non-nil, that prevents asking this question.

If along-with-file is non-nil, that means to assume that the former visited file has been renamed to filename.

When the function set-visited-file-name is called interactively, it prompts for filename in the minibuffer.

Variable: list-buffers-directory
This buffer-local variable specifies a string to display in a buffer listing where the visited file name would go, for buffers that don't have a visited file name. Dired buffers use this variable.

Buffer Modification

Emacs keeps a flag called the modified flag for each buffer, to record whether you have changed the text of the buffer. This flag is set to t whenever you alter the contents of the buffer, and cleared to nil when you save it. Thus, the flag shows whether there are unsaved changes. The flag value is normally shown in the mode line (see section Variables Used in the Mode Line), and controls saving (see section Saving Buffers) and auto-saving (see section Auto-Saving).

Some Lisp programs set the flag explicitly. For example, the function set-visited-file-name sets the flag to t, because the text does not match the newly-visited file, even if it is unchanged from the file formerly visited.

The functions that modify the contents of buffers are described in section Text.

Function: buffer-modified-p &optional buffer
This function returns t if the buffer buffer has been modified since it was last read in from a file or saved, or nil otherwise. If buffer is not supplied, the current buffer is tested.

Function: set-buffer-modified-p flag
This function marks the current buffer as modified if flag is non-nil, or as unmodified if the flag is nil.

Another effect of calling this function is to cause unconditional redisplay of the mode line for the current buffer. In fact, the function force-mode-line-update works by doing this:
(set-buffer-modified-p (buffer-modified-p))
Command: not-modified
This command marks the current buffer as unmodified, and not needing to be saved. With prefix arg, it marks the buffer as modified, so that it will be saved at the next suitable occasion.

Don't use this function in programs, since it prints a message in the echo area; use set-buffer-modified-p (above) instead.

Function: buffer-modified-tick &optional buffer
This function returns buffer's modification-count. This is a counter that increments every time the buffer is modified. If buffer is nil (or omitted), the current buffer is used.

Comparison of Modification Time

Suppose that you visit a file and make changes in its buffer, and meanwhile the file itself is changed on disk. At this point, saving the buffer would overwrite the changes in the file. Occasionally this may be what you want, but usually it would lose valuable information. Emacs therefore checks the file's modification time using the functions described below before saving the file.

Function: verify-visited-file-modtime buffer
This function compares what buffer has recorded for the modification time of its visited file against the actual modification time of the file as recorded by the operating system. The two should be the same unless some other process has written the file since Emacs visited or saved it.

The function returns t if the last actual modification time and Emacs's recorded modification time are the same, nil otherwise.

Function: clear-visited-file-modtime
This function clears out the record of the last modification time of the file being visited by the current buffer. As a result, the next attempt to save this buffer will not complain of a discrepancy in file modification times.

This function is called in set-visited-file-name and other exceptional places where the usual test to avoid overwriting a changed file should not be done.

Function: visited-file-modtime
This function returns the buffer's recorded last file modification time, as a list of the form (high . low). (This is the same format that file-attributes uses to return time values; see section Other Information about Files.)

Function: set-visited-file-modtime &optional time
This function updates the buffer's record of the last modification time of the visited file, to the value specified by time if time is not nil, and otherwise to the last modification time of the visited file.

If time is not nil, it should have the form (high . low) or (high low), in either case containing two integers, each of which holds 16 bits of the time.

This function is useful if the buffer was not read from the file normally, or if the file itself has been changed for some known benign reason.

Function: ask-user-about-supersession-threat filename
This function is used to ask a user how to proceed after an attempt to modify an obsolete buffer visiting file filename. An obsolete buffer is an unmodified buffer for which the associated file on disk is newer than the last save-time of the buffer. This means some other program has probably altered the file.

Depending on the user's answer, the function may return normally, in which case the modification of the buffer proceeds, or it may signal a file-supersession error with data (filename), in which case the proposed buffer modification is not allowed.

This function is called automatically by Emacs on the proper occasions. It exists so you can customize Emacs by redefining it. See the file `userlock.el' for the standard definition.

See also the file locking mechanism in section File Locks.

Read-Only Buffers

If a buffer is read-only, then you cannot change its contents, although you may change your view of the contents by scrolling and narrowing.

Read-only buffers are used in two kinds of situations:

A buffer visiting a write-protected file is normally read-only. Here, the purpose is to inform the user that editing the buffer with the aim of saving it in the file may be futile or undesirable. The user who wants to change the buffer text despite this can do so after clearing the read-only flag with C-x C-q.
Modes such as Dired and Rmail make buffers read-only when altering the contents with the usual editing commands is probably a mistake. The special commands of these modes bind buffer-read-only to nil (with let) or bind inhibit-read-only to t around the places where they themselves change the text.

Variable: buffer-read-only
This buffer-local variable specifies whether the buffer is read-only. The buffer is read-only if this variable is non-nil.

Variable: inhibit-read-only
If this variable is non-nil, then read-only buffers and read-only characters may be modified. Read-only characters in a buffer are those that have non-nil read-only properties (either text properties or overlay properties). See section Properties with Special Meanings, for more information about text properties. See section Overlays, for more information about overlays and their properties.

If inhibit-read-only is t, all read-only character properties have no effect. If inhibit-read-only is a list, then read-only character properties have no effect if they are members of the list (comparison is done with eq).

Command: toggle-read-only
This command changes whether the current buffer is read-only. It is intended for interactive use; don't use it in programs. At any given point in a program, you should know whether you want the read-only flag on or off; so you can set buffer-read-only explicitly to the proper value, t or nil.

Function: barf-if-buffer-read-only
This function signals a buffer-read-only error if the current buffer is read-only. See section Interactive Call, for another way to signal an error if the current buffer is read-only.

The Buffer List

The buffer list is a list of all live buffers. Creating a buffer adds it to this list, and killing a buffer excises it. The order of the buffers in the list is based primarily on how recently each buffer has been displayed in the selected window. Buffers move to the front of the list when they are selected and to the end when they are buried (see bury-buffer, below). Several functions, notably other-buffer, use this ordering. A buffer list displayed for the user also follows this order.

In addition to the fundamental Emacs buffer list, each frame has its own version of the buffer list, in which the buffers that have been selected in that frame come first, starting with the buffers most recently selected in that frame. (This order is recorded in frame's buffer-list frame parameter; see section Window Frame Parameters.) The buffers that were never selected in frame come afterward, ordered according to the fundamental Emacs buffer list.

Function: buffer-list &optional frame
This function returns the buffer list, including all buffers, even those whose names begin with a space. The elements are actual buffers, not their names.

If frame is a frame, this returns frame's buffer list. If frame is nil, the fundamental Emacs buffer list is used: all the buffers appear in order of most recent selection, regardless of which frames they were selected in.
(buffer-list)
     => (#<buffer buffers.texi>
         #<buffer  *Minibuf-1*> #<buffer buffer.c>
         #<buffer *Help*> #<buffer TAGS>)

;; Note that the name of the minibuffer
;;   begins with a space!
(mapcar (function buffer-name) (buffer-list))
    => ("buffers.texi" " *Minibuf-1*"
        "buffer.c" "*Help*" "TAGS")
The list that buffer-list returns is constructed specifically by buffer-list; it is not an internal Emacs data structure, and modifying it has no effect on the order of buffers. If you want to change the order of buffers in the frame-independent buffer list, here is an easy way:
(defun reorder-buffer-list (new-list)
  (while new-list
    (bury-buffer (car new-list))
    (setq new-list (cdr new-list))))
With this method, you can specify any order for the list, but there is no danger of losing a buffer or adding something that is not a valid live buffer.

To change the order or value of a frame's buffer list, set the frame's buffer-list frame parameter with modify-frame-parameters (see section Access to Frame Parameters).

Function: other-buffer &optional buffer visible-ok frame
This function returns the first buffer in the buffer list other than buffer. Usually this is the buffer selected most recently (in frame frame or else the currently selected frame), aside from buffer. Buffers whose names start with a space are not considered at all.

If buffer is not supplied (or if it is not a buffer), then other-buffer returns the first buffer in the selected frame's buffer list that is not now visible in any window in a visible frame.

If frame has a non-nil buffer-predicate parameter, then other-buffer uses that predicate to decide which buffers to consider. It calls the predicate once for each buffer, and if the value is nil, that buffer is ignored. See section Window Frame Parameters.

If visible-ok is nil, other-buffer avoids returning a buffer visible in any window on any visible frame, except as a last resort. If visible-ok is non-nil, then it does not matter whether a buffer is displayed somewhere or not.

If no suitable buffer exists, the buffer `*scratch*' is returned (and created, if necessary).

Command: bury-buffer &optional buffer-or-name
This function puts buffer-or-name at the end of the buffer list, without changing the order of any of the other buffers on the list. This buffer therefore becomes the least desirable candidate for other-buffer to return.

bury-buffer operates on each frame's buffer-list parameter as well as the frame-independent Emacs buffer list; therefore, the buffer that you bury will come last in the value of (buffer-list frame) and in the value of (buffer-list nil).

If buffer-or-name is nil or omitted, this means to bury the current buffer. In addition, if the buffer is displayed in the selected window, this switches to some other buffer (obtained using other-buffer) in the selected window. But if the buffer is displayed in some other window, it remains displayed there.

To replace a buffer in all the windows that display it, use replace-buffer-in-windows. See section Buffers and Windows.

Creating Buffers

This section describes the two primitives for creating buffers. get-buffer-create creates a buffer if it finds no existing buffer with the specified name; generate-new-buffer always creates a new buffer and gives it a unique name.

Other functions you can use to create buffers include with-output-to-temp-buffer (see section Temporary Displays) and create-file-buffer (see section Visiting Files). Starting a subprocess can also create a buffer (see section Processes).

Function: get-buffer-create name
This function returns a buffer named name. It returns an existing buffer with that name, if one exists; otherwise, it creates a new buffer. The buffer does not become the current buffer--this function does not change which buffer is current.

An error is signaled if name is not a string.
(get-buffer-create "foo")
     => #<buffer foo>
The major mode for the new buffer is set to Fundamental mode. The variable default-major-mode is handled at a higher level. See section How Emacs Chooses a Major Mode.

Function: generate-new-buffer name
This function returns a newly created, empty buffer, but does not make it current. If there is no buffer named name, then that is the name of the new buffer. If that name is in use, this function adds suffixes of the form `<n>' to name, where n is an integer. It tries successive integers starting with 2 until it finds an available name.

An error is signaled if name is not a string.
(generate-new-buffer "bar")
     => #<buffer bar>
(generate-new-buffer "bar")
     => #<buffer bar<2>>
(generate-new-buffer "bar")
     => #<buffer bar<3>>
The major mode for the new buffer is set to Fundamental mode. The variable default-major-mode is handled at a higher level. See section How Emacs Chooses a Major Mode.

See the related function generate-new-buffer-name in section Buffer Names.

Killing Buffers

Killing a buffer makes its name unknown to Emacs and makes its text space available for other use.

The buffer object for the buffer that has been killed remains in existence as long as anything refers to it, but it is specially marked so that you cannot make it current or display it. Killed buffers retain their identity, however; two distinct buffers, when killed, remain distinct according to eq.

If you kill a buffer that is current or displayed in a window, Emacs automatically selects or displays some other buffer instead. This means that killing a buffer can in general change the current buffer. Therefore, when you kill a buffer, you should also take the precautions associated with changing the current buffer (unless you happen to know that the buffer being killed isn't current). See section The Current Buffer.

If you kill a buffer that is the base buffer of one or more indirect buffers, the indirect buffers are automatically killed as well.

The buffer-name of a killed buffer is nil. You can use this feature to test whether a buffer has been killed:
(defun buffer-killed-p (buffer)
  "Return t if BUFFER is killed."
  (not (buffer-name buffer)))
Command: kill-buffer buffer-or-name
This function kills the buffer buffer-or-name, freeing all its memory for other uses or to be returned to the operating system. It returns nil.

Any processes that have this buffer as the process-buffer are sent the SIGHUP signal, which normally causes them to terminate. (The basic meaning of SIGHUP is that a dialup line has been disconnected.) See section Deleting Processes.

If the buffer is visiting a file and contains unsaved changes, kill-buffer asks the user to confirm before the buffer is killed. It does this even if not called interactively. To prevent the request for confirmation, clear the modified flag before calling kill-buffer. See section Buffer Modification.

Killing a buffer that is already dead has no effect.
(kill-buffer "foo.unchanged")
     => nil
(kill-buffer "foo.changed")

---------- Buffer: Minibuffer ----------
Buffer foo.changed modified; kill anyway? (yes or no) yes
---------- Buffer: Minibuffer ----------

     => nil
Variable: kill-buffer-query-functions
After confirming unsaved changes, kill-buffer calls the functions in the list kill-buffer-query-functions, in order of appearance, with no arguments. The buffer being killed is the current buffer when they are called. The idea is that these functions ask for confirmation from the user for various nonstandard reasons. If any of them returns nil, kill-buffer spares the buffer's life.

Variable: kill-buffer-hook
This is a normal hook run by kill-buffer after asking all the questions it is going to ask, just before actually killing the buffer. The buffer to be killed is current when the hook functions run. See section Hooks.

Variable: buffer-offer-save
This variable, if non-nil in a particular buffer, tells save-buffers-kill-emacs and save-some-buffers to offer to save that buffer, just as they offer to save file-visiting buffers. The variable buffer-offer-save automatically becomes buffer-local when set for any reason. See section Buffer-Local Variables.

Indirect Buffers

An indirect buffer shares the text of some other buffer, which is called the base buffer of the indirect buffer. In some ways it is the analogue, for buffers, of a symbolic link among files. The base buffer may not itself be an indirect buffer.

The text of the indirect buffer is always identical to the text of its base buffer; changes made by editing either one are visible immediately in the other. This includes the text properties as well as the characters themselves.

But in all other respects, the indirect buffer and its base buffer are completely separate. They have different names, different values of point, different narrowing, different markers and overlays (though inserting or deleting text in either buffer relocates the markers and overlays for both), different major modes, and different buffer-local variables.

An indirect buffer cannot visit a file, but its base buffer can. If you try to save the indirect buffer, that actually works by saving the base buffer.

Killing an indirect buffer has no effect on its base buffer. Killing the base buffer effectively kills the indirect buffer in that it cannot ever again be the current buffer.

Command: make-indirect-buffer base-buffer name
This creates an indirect buffer named name whose base buffer is base-buffer. The argument base-buffer may be a buffer or a string. If base-buffer is an indirect buffer, its base buffer is used as the base for the new buffer.

Function: buffer-base-buffer buffer
This function returns the base buffer of buffer. If buffer is not indirect, the value is nil. Otherwise, the value is another buffer, which is never an indirect buffer.

Windows

This chapter describes most of the functions and variables related to Emacs windows. See section Emacs Display, for information on how text is displayed in windows.

Basic Concepts of Emacs Windows

A window in Emacs is the physical area of the screen in which a buffer is displayed. The term is also used to refer to a Lisp object that represents that screen area in Emacs Lisp. It should be clear from the context which is meant.

Emacs groups windows into frames. A frame represents an area of screen available for Emacs to use. Each frame always contains at least one window, but you can subdivide it vertically or horizontally into multiple nonoverlapping Emacs windows.

In each frame, at any time, one and only one window is designated as selected within the frame. The frame's cursor appears in that window. At any time, one frame is the selected frame; and the window selected within that frame is the selected window. The selected window's buffer is usually the current buffer (except when set-buffer has been used). See section The Current Buffer.

For practical purposes, a window exists only while it is displayed in a frame. Once removed from the frame, the window is effectively deleted and should not be used, even though there may still be references to it from other Lisp objects. Restoring a saved window configuration is the only way for a window no longer on the screen to come back to life. (See section Deleting Windows.)

Each window has the following attributes:

containing frame
window height
window width
window edges with respect to the screen or frame
the buffer it displays
position within the buffer at the upper left of the window
amount of horizontal scrolling, in columns
point
the mark
how recently the window was selected

Users create multiple windows so they can look at several buffers at once. Lisp libraries use multiple windows for a variety of reasons, but most often to display related information. In Rmail, for example, you can move through a summary buffer in one window while the other window shows messages one at a time as they are reached.

The meaning of "window" in Emacs is similar to what it means in the context of general-purpose window systems such as X, but not identical. The X Window System places X windows on the screen; Emacs uses one or more X windows as frames, and subdivides them into Emacs windows. When you use Emacs on a character-only terminal, Emacs treats the whole terminal screen as one frame.

Most window systems support arbitrarily located overlapping windows. In contrast, Emacs windows are tiled; they never overlap, and together they fill the whole screen or frame. Because of the way in which Emacs creates new windows and resizes them, not all conceivable tilings of windows on an Emacs frame are actually possible. See section Splitting Windows, and section The Size of a Window.

See section Emacs Display, for information on how the contents of the window's buffer are displayed in the window.

Function: windowp object
This function returns t if object is a window.

Splitting Windows

The functions described here are the primitives used to split a window into two windows. Two higher level functions sometimes split a window, but not always: pop-to-buffer and display-buffer (see section Displaying Buffers in Windows).

The functions described here do not accept a buffer as an argument. The two "halves" of the split window initially display the same buffer previously visible in the window that was split.

Command: split-window &optional window size horizontal
This function splits window into two windows. The original window window remains the selected window, but occupies only part of its former screen area. The rest is occupied by a newly created window which is returned as the value of this function.

If horizontal is non-nil, then window splits into two side by side windows. The original window window keeps the leftmost size columns, and gives the rest of the columns to the new window. Otherwise, it splits into windows one above the other, and window keeps the upper size lines and gives the rest of the lines to the new window. The original window is therefore the left-hand or upper of the two, and the new window is the right-hand or lower.

If window is omitted or nil, then the selected window is split. If size is omitted or nil, then window is divided evenly into two parts. (If there is an odd line, it is allocated to the new window.) When split-window is called interactively, all its arguments are nil.

The following example starts with one window on a screen that is 50 lines high by 80 columns wide; then the window is split.
(setq w (selected-window))
     => #<window 8 on windows.texi>
(window-edges)          ; Edges in order:
     => (0 0 80 50)     ;   left--top--right--bottom

;; Returns window created
(setq w2 (split-window w 15))
     => #<window 28 on windows.texi>
(window-edges w2)
     => (0 15 80 50)    ; Bottom window;
                        ;   top is line 15
(window-edges w)
     => (0 0 80 15)     ; Top window
The screen looks like this:
         __________
        |          |  line 0
        |    w     |
        |__________|
        |          |  line 15
        |    w2    |
        |__________|
                      line 50
 column 0   column 80
Next, the top window is split horizontally:
(setq w3 (split-window w 35 t))
     => #<window 32 on windows.texi>
(window-edges w3)
     => (35 0 80 15)  ; Left edge at column 35
(window-edges w)
     => (0 0 35 15)   ; Right edge at column 35
(window-edges w2)
     => (0 15 80 50)  ; Bottom window unchanged
Now, the screen looks like this:
     column 35
         __________
        |   |      |  line 0
        | w |  w3  |
        |___|______|
        |          |  line 15
        |    w2    |
        |__________|
                      line 50
 column 0   column 80
Normally, Emacs indicates the border between two side-by-side windows with a scroll bar (see section Window Frame Parameters) or `|' characters. The display table can specify alternative border characters; see section Display Tables.

Command: split-window-vertically size
This function splits the selected window into two windows, one above the other, leaving the upper of the two windows selected, with size lines. (If size is negative, then the lower of the two windows gets - size lines and the upper window gets the rest, but the upper window is still the one selected.)

This function is simply an interface to split-window. Here is the complete function definition for it:
(defun split-window-vertically (&optional arg)
  "Split current window into two windows, ..."
  (interactive "P")
  (split-window nil (and arg (prefix-numeric-value arg))))
Command: split-window-horizontally size
This function splits the selected window into two windows side-by-side, leaving the selected window with size columns.

This function is simply an interface to split-window. Here is the complete definition for split-window-horizontally (except for part of the documentation string):
(defun split-window-horizontally (&optional arg)
  "Split selected window into two windows, side by side..."
  (interactive "P")
  (split-window nil (and arg (prefix-numeric-value arg)) t))
Function: one-window-p &optional no-mini all-frames
This function returns non-nil if there is only one window. The argument no-mini, if non-nil, means don't count the minibuffer even if it is active; otherwise, the minibuffer window is included, if active, in the total number of windows, which is compared against one.

The argument all-frames specifies which frames to consider. Here are the possible values and their meanings:

nil
Count the windows in the selected frame, plus the minibuffer used by that frame even if it lies in some other frame.
t
Count all windows in all existing frames.
visible
Count all windows in all visible frames.
0
Count all windows in all visible or iconified frames.
anything else
Count precisely the windows in the selected frame, and no others.
Deleting Windows

A window remains visible on its frame unless you delete it by calling certain functions that delete windows. A deleted window cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a window aside from restoring a saved window configuration (see section Window Configurations). Restoring a window configuration also deletes any windows that aren't part of that configuration.

When you delete a window, the space it took up is given to one adjacent sibling.

Function: window-live-p window
This function returns nil if window is deleted, and t otherwise.

Warning: Erroneous information or fatal errors may result from using a deleted window as if it were live.

Command: delete-window &optional window
This function removes window from display, and returns nil. If window is omitted, then the selected window is deleted. An error is signaled if there is only one window when delete-window is called.

Command: delete-other-windows &optional window
This function makes window the only window on its frame, by deleting the other windows in that frame. If window is omitted or nil, then the selected window is used by default.

The return value is nil.

Command: delete-windows-on buffer &optional frame
This function deletes all windows showing buffer. If there are no windows showing buffer, it does nothing.

delete-windows-on operates frame by frame. If a frame has several windows showing different buffers, then those showing buffer are removed, and the others expand to fill the space. If all windows in some frame are showing buffer (including the case where there is only one window), then the frame reverts to having a single window showing another buffer chosen with other-buffer. See section The Buffer List.

The argument frame controls which frames to operate on. This function does not use it in quite the same way as the other functions which scan all windows; specifically, the values t and nil have the opposite of their meanings in other functions. Here are the full details:

If it is nil, operate on all frames.
If it is t, operate on the selected frame.
If it is visible, operate on all visible frames.
If it is 0, operate on all visible or iconified frames.
If it is a frame, operate on that frame.

This function always returns nil.

Selecting Windows

When a window is selected, the buffer in the window becomes the current buffer, and the cursor will appear in it.

Function: selected-window
This function returns the selected window. This is the window in which the cursor appears and to which many commands apply.

Function: select-window window
This function makes window the selected window. The cursor then appears in window (on redisplay). The buffer being displayed in window is immediately designated the current buffer.

The return value is window.
(setq w (next-window))
(select-window w)
     => #<window 65 on windows.texi>
Macro: save-selected-window forms...
This macro records the selected window, executes forms in sequence, then restores the earlier selected window.

This macro does not save or restore anything about the sizes, arrangement or contents of windows; therefore, if the forms change them, the change persists.

Each frame, at any time, has a window selected within the frame. This macro saves only the selected window; it does not save anything about other frames. If the forms select some other frame and alter the window selected within it, the change persists.

The following functions choose one of the windows on the screen, offering various criteria for the choice.

Function: get-lru-window &optional frame
This function returns the window least recently "used" (that is, selected). The selected window is always the most recently used window.

The selected window can be the least recently used window if it is the only window. A newly created window becomes the least recently used window until it is selected. A minibuffer window is never a candidate.

The argument frame controls which windows are considered.

If it is nil, consider windows on the selected frame.
If it is t, consider windows on all frames.
If it is visible, consider windows on all visible frames.
If it is 0, consider windows on all visible or iconified frames.
If it is a frame, consider windows on that frame.

Function: get-largest-window &optional frame
This function returns the window with the largest area (height times width). If there are no side-by-side windows, then this is the window with the most lines. A minibuffer window is never a candidate.

If there are two windows of the same size, then the function returns the window that is first in the cyclic ordering of windows (see following section), starting from the selected window.

The argument frame controls which set of windows to consider. See get-lru-window, above.

Cyclic Ordering of Windows

When you use the command C-x o (other-window) to select the next window, it moves through all the windows on the screen in a specific cyclic order. For any given configuration of windows, this order never varies. It is called the cyclic ordering of windows.

This ordering generally goes from top to bottom, and from left to right. But it may go down first or go right first, depending on the order in which the windows were split.

If the first split was vertical (into windows one above each other), and then the subwindows were split horizontally, then the ordering is left to right in the top of the frame, and then left to right in the next lower part of the frame, and so on. If the first split was horizontal, the ordering is top to bottom in the left part, and so on. In general, within each set of siblings at any level in the window tree, the order is left to right, or top to bottom.

Function: next-window &optional window minibuf all-frames
This function returns the window following window in the cyclic ordering of windows. This is the window that C-x o would select if typed when window is selected. If window is the only window visible, then this function returns window. If omitted, window defaults to the selected window.

The value of the argument minibuf determines whether the minibuffer is included in the window order. Normally, when minibuf is nil, the minibuffer is included if it is currently active; this is the behavior of C-x o. (The minibuffer window is active while the minibuffer is in use. See section Minibuffers.)

If minibuf is t, then the cyclic ordering includes the minibuffer window even if it is not active.

If minibuf is neither t nor nil, then the minibuffer window is not included even if it is active.

The argument all-frames specifies which frames to consider. Here are the possible values and their meanings:

nil
Consider all the windows in window's frame, plus the minibuffer used by that frame even if it lies in some other frame.
t
Consider all windows in all existing frames.
visible
Consider all windows in all visible frames. (To get useful results, you must ensure window is in a visible frame.)
0
Consider all windows in all visible or iconified frames.
anything else
Consider precisely the windows in window's frame, and no others.
This example assumes there are two windows, both displaying the buffer `windows.texi':
(selected-window)
     => #<window 56 on windows.texi>
(next-window (selected-window))
     => #<window 52 on windows.texi>
(next-window (next-window (selected-window)))
     => #<window 56 on windows.texi>
Function: previous-window &optional window minibuf all-frames
This function returns the window preceding window in the cyclic ordering of windows. The other arguments specify which windows to include in the cycle, as in next-window.

Command: other-window count
This function selects the countth following window in the cyclic order. If count is negative, then it moves back -count windows in the cycle, rather than forward. It returns nil.

In an interactive call, count is the numeric prefix argument.

Function: walk-windows proc &optional minibuf all-frames
This function cycles through all windows, calling proc once for each window with the window as its sole argument.

The optional arguments minibuf and all-frames specify the set of windows to include in the scan. See next-window, above, for details.

Buffers and Windows

This section describes low-level functions to examine windows or to display buffers in windows in a precisely controlled fashion. See the following section for related functions that find a window to use and specify a buffer for it. The functions described there are easier to use than these, but they employ heuristics in choosing or creating a window; use these functions when you need complete control.

Function: set-window-buffer window buffer-or-name
This function makes window display buffer-or-name as its contents. It returns nil. This is the fundamental primitive for changing which buffer is displayed in a window, and all ways of doing that call this function.
(set-window-buffer (selected-window) "foo")
     => nil
Function: window-buffer &optional window
This function returns the buffer that window is displaying. If window is omitted, this function returns the buffer for the selected window.
(window-buffer)
     => #<buffer windows.texi>
Function: get-buffer-window buffer-or-name &optional all-frames
This function returns a window currently displaying buffer-or-name, or nil if there is none. If there are several such windows, then the function returns the first one in the cyclic ordering of windows, starting from the selected window. See section Cyclic Ordering of Windows.

The argument all-frames controls which windows to consider.

If it is nil, consider windows on the selected frame.
If it is t, consider windows on all frames.
If it is visible, consider windows on all visible frames.
If it is 0, consider windows on all visible or iconified frames.
If it is a frame, consider windows on that frame.

Function: get-buffer-window-list buffer-or-name &optional minibuf all-frames
This function returns a list of all the windows currently displaying buffer-or-name.

The two optional arguments work like the optional arguments of next-window (see section Cyclic Ordering of Windows); they are not like the single optional argument of get-buffer-window. Perhaps we should change get-buffer-window in the future to make it compatible with the other functions.

The argument all-frames controls which windows to consider.

If it is nil, consider windows on the selected frame.
If it is t, consider windows on all frames.
If it is visible, consider windows on all visible frames.
If it is 0, consider windows on all visible or iconified frames.
If it is a frame, consider windows on that frame.

Variable: buffer-display-time
This variable records the time at which a buffer was last made visible in a window. It is always local in each buffer; each time set-window-buffer is called, it sets this variable to (current-time) in the specified buffer (see section Time of Day). When a buffer is first created, buffer-display-time starts out with the value nil.

Displaying Buffers in Windows

In this section we describe convenient functions that choose a window automatically and use it to display a specified buffer. These functions can also split an existing window in certain circumstances. We also describe variables that parameterize the heuristics used for choosing a window. See the preceding section for low-level functions that give you more precise control. All of these functions work by calling set-window-buffer.

Do not use the functions in this section in order to make a buffer current so that a Lisp program can access or modify it; they are too drastic for that purpose, since they change the display of buffers in windows, which would be gratuitous and surprise the user. Instead, use set-buffer and save-current-buffer (see section The Current Buffer), which designate buffers as current for programmed access without affecting the display of buffers in windows.

Command: switch-to-buffer buffer-or-name &optional norecord
This function makes buffer-or-name the current buffer, and also displays the buffer in the selected window. This means that a human can see the buffer and subsequent keyboard commands will apply to it. Contrast this with set-buffer, which makes buffer-or-name the current buffer but does not display it in the selected window. See section The Current Buffer.

If buffer-or-name does not identify an existing buffer, then a new buffer by that name is created. The major mode for the new buffer is set according to the variable default-major-mode. See section How Emacs Chooses a Major Mode.

Normally the specified buffer is put at the front of the buffer list (both the selected frame's buffer list and the frame-independent buffer list). This affects the operation of other-buffer. However, if norecord is non-nil, this is not done. See section The Buffer List.

The switch-to-buffer function is often used interactively, as the binding of C-x b. It is also used frequently in programs. It always returns nil.

Command: switch-to-buffer-other-window buffer-or-name &optional norecord
This function makes buffer-or-name the current buffer and displays it in a window not currently selected. It then selects that window. The handling of the buffer is the same as in switch-to-buffer.

The currently selected window is absolutely never used to do the job. If it is the only window, then it is split to make a distinct window for this purpose. If the selected window is already displaying the buffer, then it continues to do so, but another window is nonetheless found to display it in as well.

This function updates the buffer list just like switch-to-buffer unless norecord is non-nil.

Function: pop-to-buffer buffer-or-name &optional other-window norecord
This function makes buffer-or-name the current buffer and switches to it in some window, preferably not the window previously selected. The "popped-to" window becomes the selected window within its frame.

If the variable pop-up-frames is non-nil, pop-to-buffer looks for a window in any visible frame already displaying the buffer; if there is one, it returns that window and makes it be selected within its frame. If there is none, it creates a new frame and displays the buffer in it.

If pop-up-frames is nil, then pop-to-buffer operates entirely within the selected frame. (If the selected frame has just a minibuffer, pop-to-buffer operates within the most recently selected frame that was not just a minibuffer.)

If the variable pop-up-windows is non-nil, windows may be split to create a new window that is different from the original window. For details, see section Choosing a Window for Display.

If other-window is non-nil, pop-to-buffer finds or creates another window even if buffer-or-name is already visible in the selected window. Thus buffer-or-name could end up displayed in two windows. On the other hand, if buffer-or-name is already displayed in the selected window and other-window is nil, then the selected window is considered sufficient display for buffer-or-name, so that nothing needs to be done.

All the variables that affect display-buffer affect pop-to-buffer as well. See section Choosing a Window for Display.

If buffer-or-name is a string that does not name an existing buffer, a buffer by that name is created. The major mode for the new buffer is set according to the variable default-major-mode. See section How Emacs Chooses a Major Mode.

This function updates the buffer list just like switch-to-buffer unless norecord is non-nil.

Command: replace-buffer-in-windows buffer
This function replaces buffer with some other buffer in all windows displaying it. The other buffer used is chosen with other-buffer. In the usual applications of this function, you don't care which other buffer is used; you just want to make sure that buffer is no longer displayed.

This function returns nil.

Choosing a Window for Display

This section describes the basic facility that chooses a window to display a buffer in---display-buffer. All the higher-level functions and commands use this subroutine. Here we describe how to use display-buffer and how to customize it.

Command: display-buffer buffer-or-name &optional not-this-window frame
This command makes buffer-or-name appear in some window, like pop-to-buffer, but it does not select that window and does not make the buffer current. The identity of the selected window is unaltered by this function.

If not-this-window is non-nil, it means to display the specified buffer in a window other than the selected one, even if it is already on display in the selected window. This can cause the buffer to appear in two windows at once. Otherwise, if buffer-or-name is already being displayed in any window, that is good enough, so this function does nothing.

display-buffer returns the window chosen to display buffer-or-name.

If the argument frame is non-nil, it specifies which frames to check when deciding whether the buffer is already displayed. If the buffer is already displayed in some window on one of these frames, display-buffer simply returns that window. Here are the possible values of frame:

If it is nil, consider windows on the selected frame.
If it is t, consider windows on all frames.
If it is visible, consider windows on all visible frames.
If it is 0, consider windows on all visible or iconified frames.
If it is a frame, consider windows on that frame.

Precisely how display-buffer finds or creates a window depends on the variables described below.

User Option: pop-up-windows
This variable controls whether display-buffer makes new windows. If it is non-nil and there is only one window, then that window is split. If it is nil, then display-buffer does not split the single window, but uses it whole.

User Option: split-height-threshold
This variable determines when display-buffer may split a window, if there are multiple windows. display-buffer always splits the largest window if it has at least this many lines. If the largest window is not this tall, it is split only if it is the sole window and pop-up-windows is non-nil.

User Option: pop-up-frames
This variable controls whether display-buffer makes new frames. If it is non-nil, display-buffer looks for an existing window already displaying the desired buffer, on any visible frame. If it finds one, it returns that window. Otherwise it makes a new frame. The variables pop-up-windows and split-height-threshold do not matter if pop-up-frames is non-nil.

If pop-up-frames is nil, then display-buffer either splits a window or reuses one.

See section Frames, for more information.

Variable: pop-up-frame-function
This variable specifies how to make a new frame if pop-up-frames is non-nil.

Its value should be a function of no arguments. When display-buffer makes a new frame, it does so by calling that function, which should return a frame. The default value of the variable is a function that creates a frame using parameters from pop-up-frame-alist.

Variable: pop-up-frame-alist
This variable holds an alist specifying frame parameters used when display-buffer makes a new frame. See section Frame Parameters, for more information about frame parameters.

User Option: special-display-buffer-names
A list of buffer names for buffers that should be displayed specially. If the buffer's name is in this list, display-buffer handles the buffer specially.

By default, special display means to give the buffer a dedicated frame.

If an element is a list, instead of a string, then the CAR of the list is the buffer name, and the rest of the list says how to create the frame. There are two possibilities for the rest of the list. It can be an alist, specifying frame parameters, or it can contain a function and arguments to give to it. (The function's first argument is always the buffer to be displayed; the arguments from the list come after that.)

User Option: special-display-regexps
A list of regular expressions that specify buffers that should be displayed specially. If the buffer's name matches any of the regular expressions in this list, display-buffer handles the buffer specially.

By default, special display means to give the buffer a dedicated frame.

If an element is a list, instead of a string, then the CAR of the list is the regular expression, and the rest of the list says how to create the frame. See above, under special-display-buffer-names.

Variable: special-display-function
This variable holds the function to call to display a buffer specially. It receives the buffer as an argument, and should return the window in which it is displayed.

The default value of this variable is special-display-popup-frame.

Function: special-display-popup-frame buffer
This function makes buffer visible in a frame of its own. If buffer is already displayed in a window in some frame, it makes the frame visible and raises it, to use that window. Otherwise, it creates a frame that will be dedicated to buffer.

This function uses an existing window displaying buffer whether or not it is in a frame of its own; but if you set up the above variables in your init file, before buffer was created, then presumably the window was previously made by this function.

User Option: special-display-frame-alist
This variable holds frame parameters for special-display-popup-frame to use when it creates a frame.

User Option: same-window-buffer-names
A list of buffer names for buffers that should be displayed in the selected window. If the buffer's name is in this list, display-buffer handles the buffer by switching to it in the selected window.

User Option: same-window-regexps
A list of regular expressions that specify buffers that should be displayed in the selected window. If the buffer's name matches any of the regular expressions in this list, display-buffer handles the buffer by switching to it in the selected window.

Variable: display-buffer-function
This variable is the most flexible way to customize the behavior of display-buffer. If it is non-nil, it should be a function that display-buffer calls to do the work. The function should accept two arguments, the same two arguments that display-buffer received. It should choose or create a window, display the specified buffer, and then return the window.

This hook takes precedence over all the other options and hooks described above.

A window can be marked as "dedicated" to its buffer. Then display-buffer will not try to use that window to display any other buffer.

Function: window-dedicated-p window
This function returns t if window is marked as dedicated; otherwise nil.

Function: set-window-dedicated-p window flag
This function marks window as dedicated if flag is non-nil, and nondedicated otherwise.

Windows and Point

Each window has its own value of point, independent of the value of point in other windows displaying the same buffer. This makes it useful to have multiple windows showing one buffer.

The window point is established when a window is first created; it is initialized from the buffer's point, or from the window point of another window opened on the buffer if such a window exists.
Selecting a window sets the value of point in its buffer from the window's value of point. Conversely, deselecting a window sets the window's value of point from that of the buffer. Thus, when you switch between windows that display a given buffer, the point value for the selected window is in effect in the buffer, while the point values for the other windows are stored in those windows.
As long as the selected window displays the current buffer, the window's point and the buffer's point always move together; they remain equal.
See section Positions, for more details on buffer positions.

As far as the user is concerned, point is where the cursor is, and when the user switches to another buffer, the cursor jumps to the position of point in that buffer.

Function: window-point window
This function returns the current position of point in window. For a nonselected window, this is the value point would have (in that window's buffer) if that window were selected.

When window is the selected window and its buffer is also the current buffer, the value returned is the same as point in that buffer.

Strictly speaking, it would be more correct to return the "top-level" value of point, outside of any save-excursion forms. But that value is hard to find.

Function: set-window-point window position
This function positions point in window at position position in window's buffer.

The Window Start Position

Each window contains a marker used to keep track of a buffer position that specifies where in the buffer display should start. This position is called the display-start position of the window (or just the start). The character after this position is the one that appears at the upper left corner of the window. It is usually, but not inevitably, at the beginning of a text line.

Function: window-start &optional window
This function returns the display-start position of window window. If window is nil, the selected window is used. For example,
(window-start)
     => 7058
When you create a window, or display a different buffer in it, the display-start position is set to a display-start position recently used for the same buffer, or 1 if the buffer doesn't have any.

Redisplay updates the window-start position (if you have not specified it explicitly since the previous redisplay) so that point appears on the screen. Nothing except redisplay automatically changes the window-start position; if you move point, do not expect the window-start position to change in response until after the next redisplay.

For a realistic example of using window-start, see the description of count-lines in section Motion by Text Lines.

Function: window-end &optional window update
This function returns the position of the end of the display in window window. If window is nil, the selected window is used.

Simply changing the buffer text or moving point does not update the value that window-end returns. The value is updated only when Emacs redisplays and redisplay completes without being preempted.

If the last redisplay of window was preempted, and did not finish, Emacs does not know the position of the end of display in that window. In that case, this function returns nil.

If update is non-nil, window-end always returns an up-to-date value for where the window ends. If the saved value is valid, window-end returns that; otherwise it computes the correct value by scanning the buffer text.

Function: set-window-start window position &optional noforce
This function sets the display-start position of window to position in window's buffer. It returns position.

The display routines insist that the position of point be visible when a buffer is displayed. Normally, they change the display-start position (that is, scroll the window) whenever necessary to make point visible. However, if you specify the start position with this function using nil for noforce, it means you want display to start at position even if that would put the location of point off the screen. If this does place point off screen, the display routines move point to the left margin on the middle line in the window.

For example, if point is 1 and you set the start of the window to 2, then point would be "above" the top of the window. The display routines will automatically move point if it is still 1 when redisplay occurs. Here is an example:
;; Here is what `foo' looks like before executing
;;   the set-window-start expression.

---------- Buffer: foo ----------
-!-This is the contents of buffer foo.
2
3
4
5
6
---------- Buffer: foo ----------

(set-window-start
 (selected-window)
 (1+ (window-start)))
=> 2

;; Here is what `foo' looks like after executing
;;   the set-window-start expression.
---------- Buffer: foo ----------
his is the contents of buffer foo.
2
3
-!-4
5
6
---------- Buffer: foo ----------
If noforce is non-nil, and position would place point off screen at the next redisplay, then redisplay computes a new window-start position that works well with point, and thus position is not used.

Function: pos-visible-in-window-p &optional position window
This function returns t if position is within the range of text currently visible on the screen in window. It returns nil if position is scrolled vertically out of view. The argument position defaults to the current position of point; window, to the selected window. Here is an example:
(or (pos-visible-in-window-p
     (point) (selected-window))
    (recenter 0))
The pos-visible-in-window-p function considers only vertical scrolling. If position is out of view only because window has been scrolled horizontally, pos-visible-in-window-p returns t. See section Horizontal Scrolling.

Vertical Scrolling

Vertical scrolling means moving the text up or down in a window. It works by changing the value of the window's display-start location. It may also change the value of window-point to keep it on the screen.

In the commands scroll-up and scroll-down, the directions "up" and "down" refer to the motion of the text in the buffer at which you are looking through the window. Imagine that the text is written on a long roll of paper and that the scrolling commands move the paper up and down. Thus, if you are looking at text in the middle of a buffer and repeatedly call scroll-down, you will eventually see the beginning of the buffer.

Some people have urged that the opposite convention be used: they imagine that the window moves over text that remains in place. Then "down" commands would take you to the end of the buffer. This view is more consistent with the actual relationship between windows and the text in the buffer, but it is less like what the user sees. The position of a window on the terminal does not move, and short scrolling commands clearly move the text up or down on the screen. We have chosen names that fit the user's point of view.

The scrolling functions (aside from scroll-other-window) have unpredictable results if the current buffer is different from the buffer that is displayed in the selected window. See section The Current Buffer.

Command: scroll-up &optional count
This function scrolls the text in the selected window upward count lines. If count is negative, scrolling is actually downward.

If count is nil (or omitted), then the length of scroll is next-screen-context-lines lines less than the usable height of the window (not counting its mode line).

scroll-up returns nil.

Command: scroll-down &optional count
This function scrolls the text in the selected window downward count lines. If count is negative, scrolling is actually upward.

If count is omitted or nil, then the length of the scroll is next-screen-context-lines lines less than the usable height of the window (not counting its mode line).

scroll-down returns nil.

Command: scroll-other-window &optional count
This function scrolls the text in another window upward count lines. Negative values of count, or nil, are handled as in scroll-up.

You can specify a buffer to scroll with the variable other-window-scroll-buffer. When the selected window is the minibuffer, the next window is normally the one at the top left corner. You can specify a different window to scroll with the variable minibuffer-scroll-window. This variable has no effect when any other window is selected. See section Minibuffer Miscellany.

When the minibuffer is active, it is the next window if the selected window is the one at the bottom right corner. In this case, scroll-other-window attempts to scroll the minibuffer. If the minibuffer contains just one line, it has nowhere to scroll to, so the line reappears after the echo area momentarily displays the message "Beginning of buffer".

Variable: other-window-scroll-buffer
If this variable is non-nil, it tells scroll-other-window which buffer to scroll.

User Option: scroll-margin
This option specifies the size of the scroll margin--a minimum number of lines between point and the top or bottom of a window. Whenever point gets within this many lines of the top or bottom of the window, the window scrolls automatically (if possible) to move point out of the margin, closer to the center of the window.

User Option: scroll-conservatively
This variable controls how scrolling is done automatically when point moves off the screen (or into the scroll margin). If the value is zero, then redisplay scrolls the text to center point vertically in the window. If the value is a positive integer n, then redisplay scrolls the window up to n lines in either direction, if that will bring point back into view. Otherwise, it centers point. The default value is zero.

User Option: scroll-step
This variable is an older variant of scroll-conservatively. The difference is that it if its value is n, that permits scrolling only by precisely n lines, not a smaller number. This feature does not work with scroll-margin. The default value is zero.

User Option: scroll-preserve-screen-position
If this option is non-nil, the scroll functions move point so that the vertical position of the cursor is unchanged, when that is possible.

User Option: next-screen-context-lines
The value of this variable is the number of lines of continuity to retain when scrolling by full screens. For example, scroll-up with an argument of nil scrolls so that this many lines at the bottom of the window appear instead at the top. The default value is 2.

Command: recenter &optional count
This function scrolls the selected window to put the text where point is located at a specified vertical position within the window.

If count is a nonnegative number, it puts the line containing point count lines down from the top of the window. If count is a negative number, then it counts upward from the bottom of the window, so that -1 stands for the last usable line in the window. If count is a non-nil list, then it stands for the line in the middle of the window.

If count is nil, recenter puts the line containing point in the middle of the window, then clears and redisplays the entire selected frame.

When recenter is called interactively, count is the raw prefix argument. Thus, typing C-u as the prefix sets the count to a non-nil list, while typing C-u 4 sets count to 4, which positions the current line four lines from the top.

With an argument of zero, recenter positions the current line at the top of the window. This action is so handy that some people make a separate key binding to do this. For example,
(defun line-to-top-of-window ()
  "Scroll current line to top of window.
Replaces three keystroke sequence C-u 0 C-l."
  (interactive)
  (recenter 0))

(global-set-key [kp-multiply] 'line-to-top-of-window)
Horizontal Scrolling

Because we read English from left to right in the "inner loop", and from top to bottom in the "outer loop", horizontal scrolling is not like vertical scrolling. Vertical scrolling involves selection of a contiguous portion of text to display, but horizontal scrolling causes part of each line to go off screen. The amount of horizontal scrolling is therefore specified as a number of columns rather than as a position in the buffer. It has nothing to do with the display-start position returned by window-start.

Usually, no horizontal scrolling is in effect; then the leftmost column is at the left edge of the window. In this state, scrolling to the right is meaningless, since there is no data to the left of the screen to be revealed by it; so this is not allowed. Scrolling to the left is allowed; it scrolls the first columns of text off the edge of the window and can reveal additional columns on the right that were truncated before. Once a window has a nonzero amount of leftward horizontal scrolling, you can scroll it back to the right, but only so far as to reduce the net horizontal scroll to zero. There is no limit to how far left you can scroll, but eventually all the text will disappear off the left edge.

Command: scroll-left count
This function scrolls the selected window count columns to the left (or to the right if count is negative). The return value is the total amount of leftward horizontal scrolling in effect after the change--just like the value returned by window-hscroll (below).

Command: scroll-right count
This function scrolls the selected window count columns to the right (or to the left if count is negative). The return value is the total amount of leftward horizontal scrolling in effect after the change--just like the value returned by window-hscroll (below).

Once you scroll a window as far right as it can go, back to its normal position where the total leftward scrolling is zero, attempts to scroll any farther right have no effect.

Function: window-hscroll &optional window
This function returns the total leftward horizontal scrolling of window---the number of columns by which the text in window is scrolled left past the left margin.

The value is never negative. It is zero when no horizontal scrolling has been done in window (which is usually the case).

If window is nil, the selected window is used.
(window-hscroll)
     => 0
(scroll-left 5)
     => 5
(window-hscroll)
     => 5
Function: set-window-hscroll window columns
This function sets the number of columns from the left margin that window is scrolled from the value of columns. The argument columns should be zero or positive; if not, it is taken as zero.

The value returned is columns.
(set-window-hscroll (selected-window) 10)
     => 10
Here is how you can determine whether a given position position is off the screen due to horizontal scrolling:
(defun hscroll-on-screen (window position)
  (save-excursion
    (goto-char position)
    (and
     (>= (- (current-column) (window-hscroll window)) 0)
     (< (- (current-column) (window-hscroll window))
        (window-width window)))))
The Size of a Window

An Emacs window is rectangular, and its size information consists of the height (the number of lines) and the width (the number of character positions in each line). The mode line is included in the height. But the width does not count the scroll bar or the column of `|' characters that separates side-by-side windows.

The following three functions return size information about a window:

Function: window-height &optional window
This function returns the number of lines in window, including its mode line. If window fills its entire frame, this is typically one less than the value of frame-height on that frame (since the last line is always reserved for the minibuffer).

If window is nil, the function uses the selected window.
(window-height)
     => 23
(split-window-vertically)
     => #<window 4 on windows.texi>
(window-height)
     => 11
Function: window-width &optional window
This function returns the number of columns in window. If window fills its entire frame, this is the same as the value of frame-width on that frame. The width does not include the window's scroll bar or the column of `|' characters that separates side-by-side windows.

If window is nil, the function uses the selected window.
(window-width)
     => 80
Function: window-edges &optional window
This function returns a list of the edge coordinates of window. If window is nil, the selected window is used.

The order of the list is (left top right bottom), all elements relative to 0, 0 at the top left corner of the frame. The element right of the value is one more than the rightmost column used by window, and bottom is one more than the bottommost row used by window and its mode-line.

When you have side-by-side windows, the right edge value for a window with a neighbor on the right includes the width of the separator between the window and that neighbor. This separator may be a column of `|' characters or it may be a scroll bar. Since the width of the window does not include this separator, the width does not equal the difference between the right and left edges in this case.

Here is the result obtained on a typical 24-line terminal with just one window:
(window-edges (selected-window))
     => (0 0 80 23)
The bottom edge is at line 23 because the last line is the echo area.

If window is at the upper left corner of its frame, then bottom is the same as the value of (window-height), right is almost the same as the value of (window-width) (4), and top and left are zero. For example, the edges of the following window are `0 0 5 8'. Assuming that the frame has more than 8 columns, the last column of the window (column 7) holds a border rather than text. The last row (row 4) holds the mode line, shown here with `xxxxxxxxx'.
           0
           _______
        0 |       |
          |       |
          |       |
          |       |
          xxxxxxxxx  4

                  7
When there are side-by-side windows, any window not at the right edge of its frame has a separator in its last column or columns. The separator counts as one or two columns in the width of the window. A window never includes a separator on its left, since that belongs to the window to the left.

In the following example, let's suppose that the frame is 7 columns wide. Then the edges of the left window are `0 0 4 3' and the edges of the right window are `4 0 7 3'.
           ___ ___
          |   |   |
          |   |   |
          xxxxxxxxx

           0  34  7
Changing the Size of a Window

The window size functions fall into two classes: high-level commands that change the size of windows and low-level functions that access window size. Emacs does not permit overlapping windows or gaps between windows, so resizing one window affects other windows.

Command: enlarge-window size &optional horizontal
This function makes the selected window size lines taller, stealing lines from neighboring windows. It takes the lines from one window at a time until that window is used up, then takes from another. If a window from which lines are stolen shrinks below window-min-height lines, that window disappears.

If horizontal is non-nil, this function makes window wider by size columns, stealing columns instead of lines. If a window from which columns are stolen shrinks below window-min-width columns, that window disappears.

If the requested size would exceed that of the window's frame, then the function makes the window occupy the entire height (or width) of the frame.

If size is negative, this function shrinks the window by -size lines or columns. If that makes the window smaller than the minimum size (window-min-height and window-min-width), enlarge-window deletes the window.

enlarge-window returns nil.

Command: enlarge-window-horizontally columns
This function makes the selected window columns wider. It could be defined as follows:
(defun enlarge-window-horizontally (columns)
  (enlarge-window columns t))
Command: shrink-window size &optional horizontal
This function is like enlarge-window but negates the argument size, making the selected window smaller by giving lines (or columns) to the other windows. If the window shrinks below window-min-height or window-min-width, then it disappears.

If size is negative, the window is enlarged by -size lines or columns.

Command: shrink-window-horizontally columns
This function makes the selected window columns narrower. It could be defined as follows:
(defun shrink-window-horizontally (columns)
  (shrink-window columns t))
Command: shrink-window-if-larger-than-buffer window
This command shrinks window to be as small as possible while still showing the full contents of its buffer--but not less than window-min-height lines.

However, the command does nothing if the window is already too small to display the whole text of the buffer, or if part of the contents are currently scrolled off screen, or if the window is not the full width of its frame, or if the window is the only window in its frame.

The following two variables constrain the window-size-changing functions to a minimum height and width.

User Option: window-min-height
The value of this variable determines how short a window may become before it is automatically deleted. Making a window smaller than window-min-height automatically deletes it, and no window may be created shorter than this. The absolute minimum height is two (allowing one line for the mode line, and one line for the buffer display). Actions that change window sizes reset this variable to two if it is less than two. The default value is 4.

User Option: window-min-width
The value of this variable determines how narrow a window may become before it is automatically deleted. Making a window smaller than window-min-width automatically deletes it, and no window may be created narrower than this. The absolute minimum width is one; any value below that is ignored. The default value is 10.

Coordinates and Windows

This section describes how to relate screen coordinates to windows.

Function: window-at x y &optional frame
This function returns the window containing the specified cursor position in the frame frame. The coordinates x and y are measured in characters and count from the top left corner of the frame. If they are out of range, window-at returns nil.

If you omit frame, the selected frame is used.

Function: coordinates-in-window-p coordinates window
This function checks whether a particular frame position falls within the window window.

The argument coordinates is a cons cell of the form (x . y). The coordinates x and y are measured in characters, and count from the top left corner of the screen or frame.

The value returned by coordinates-in-window-p is non-nil if the coordinates are inside window. The value also indicates what part of the window the position is in, as follows:

(relx . rely)
The coordinates are inside window. The numbers relx and rely are the equivalent window-relative coordinates for the specified position, counting from 0 at the top left corner of the window.
mode-line
The coordinates are in the mode line of window.
vertical-split
The coordinates are in the vertical line between window and its neighbor to the right. This value occurs only if the window doesn't have a scroll bar; positions in a scroll bar are considered outside the window.
nil
The coordinates are not in any part of window.
The function coordinates-in-window-p does not require a frame as argument because it always uses the frame that window is on.

Window Configurations

A window configuration records the entire layout of one frame--all windows, their sizes, which buffers they contain, what part of each buffer is displayed, and the values of point and the mark. You can bring back an entire previous layout by restoring a window configuration previously saved.

If you want to record all frames instead of just one, use a frame configuration instead of a window configuration. See section Frame Configurations.

Function: current-window-configuration
This function returns a new object representing the selected frame's current window configuration, including the number of windows, their sizes and current buffers, which window is the selected window, and for each window the displayed buffer, the display-start position, and the positions of point and the mark. It also includes the values of window-min-height, window-min-width and minibuffer-scroll-window. An exception is made for point in the current buffer, whose value is not saved.

Function: set-window-configuration configuration
This function restores the configuration of windows and buffers as specified by configuration. The argument configuration must be a value that was previously returned by current-window-configuration. This configuration is restored in the frame from which configuration was made, whether that frame is selected or not. This always counts as a window size change and triggers execution of the window-size-change-functions (see section Hooks for Window Scrolling and Changes), because set-window-configuration doesn't know how to tell whether the new configuration actually differs from the old one.

If the frame which configuration was saved from is dead, all this function does is restore the three variables window-min-height, window-min-width and minibuffer-scroll-window.

Here is a way of using this function to get the same effect as save-window-excursion:
(let ((config (current-window-configuration)))
  (unwind-protect
      (progn (split-window-vertically nil)
             ...)
    (set-window-configuration config)))
Special Form: save-window-excursion forms...
This special form records the window configuration, executes forms in sequence, then restores the earlier window configuration. The window configuration includes the value of point and the portion of the buffer that is visible. It also includes the choice of selected window. However, it does not include the value of point in the current buffer; use save-excursion also, if you wish to preserve that.

Don't use this construct when save-selected-window is all you need.

Exit from save-window-excursion always triggers execution of the window-size-change-functions. (It doesn't know how to tell whether the restored configuration actually differs from the one in effect at the end of the forms.)

The return value is the value of the final form in forms. For example:
(split-window)
     => #<window 25 on control.texi>
(setq w (selected-window))
     => #<window 19 on control.texi>
(save-window-excursion
  (delete-other-windows w)
  (switch-to-buffer "foo")
  'do-something)
     => do-something
     ;; The screen is now split again.
Function: window-configuration-p object
This function returns t if object is a window configuration.

Function: compare-window-configurations config1 config2
This function compares two window configurations as regards the structure of windows, but ignores the values of point and mark and the saved scrolling positions--it can return t even if those aspects differ.

The function equal can also compare two window configurations; it regards configurations as unequal if they differ in any respect, even a saved point or mark.

Primitives to look inside of window configurations would make sense, but none are implemented. It is not clear they are useful enough to be worth implementing.

Hooks for Window Scrolling and Changes

This section describes how a Lisp program can take action whenever a window displays a different part of its buffer or a different buffer. There are three actions that can change this: scrolling the window, switching buffers in the window, and changing the size of the window. The first two actions run window-scroll-functions; the last runs window-size-change-functions. The paradigmatic use of these hooks is in the implementation of Lazy Lock mode; see section `Font Lock Support Modes' in The GNU Emacs Manual.

Variable: window-scroll-functions
This variable holds a list of functions that Emacs should call before redisplaying a window with scrolling. It is not a normal hook, because each function is called with two arguments: the window, and its new display-start position.

Displaying a different buffer in the window also runs these functions.

These functions must be careful in using window-end (see section The Window Start Position); if you need an up-to-date value, you must use the update argument to ensure you get it.

Variable: window-size-change-functions
This variable holds a list of functions to be called if the size of any window changes for any reason. The functions are called just once per redisplay, and just once for each frame on which size changes have occurred.

Each function receives the frame as its sole argument. There is no direct way to find out which windows on that frame have changed size, or precisely how. However, if a size-change function records, at each call, the existing windows and their sizes, it can also compare the present sizes and the previous sizes.

Creating or deleting windows counts as a size change, and therefore causes these functions to be called. Changing the frame size also counts, because it changes the sizes of the existing windows.

It is not a good idea to use save-window-excursion (see section Window Configurations) in these functions, because that always counts as a size change, and it would cause these functions to be called over and over. In most cases, save-selected-window (see section Selecting Windows) is what you need here.

Variable: redisplay-end-trigger-functions
This abnormal hook is run whenever redisplay in a window uses text that extends past a specified end trigger position. You set the end trigger position with the function set-window-redisplay-end-trigger. The functions are called with two arguments: the window, and the end trigger position. Storing nil for the end trigger position turns off the feature, and the trigger value is automatically reset to nil just after the hook is run.

Function: set-window-redisplay-end-trigger window position
This function sets window's end trigger position at position.

Function: window-redisplay-end-trigger window
This function returns window's current end trigger position.

Variable: window-configuration-change-hook
A normal hook that is run every time you change the window configuration of an existing frame. This includes splitting or deleting windows, changing the sizes of windows, or displaying a different buffer in a window. The frame whose window configuration has changed is the selected frame when this hook runs.
Frames

A frame is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window), which you can subdivide vertically or horizontally into smaller windows.

When Emacs runs on a text-only terminal, it starts with one terminal frame. If you create additional ones, Emacs displays one and only one at any given time--on the terminal screen, of course.

When Emacs communicates directly with a supported window system, such as X Windows, it does not have a terminal frame; instead, it starts with a single window frame, but you can create more, and Emacs can display several such frames at once as is usual for window systems.

Function: framep object
This predicate returns t if object is a frame, and nil otherwise.

See section Emacs Display, for information about the related topic of controlling Emacs redisplay.

Creating Frames

To create a new frame, call the function make-frame.

Function: make-frame &optional alist
This function creates a new frame. If you are using a supported window system, it makes a window frame; otherwise, it makes a terminal frame.

The argument is an alist specifying frame parameters. Any parameters not mentioned in alist default according to the value of the variable default-frame-alist; parameters not specified even there default from the standard X resources or whatever is used instead on your system.

The set of possible parameters depends in principle on what kind of window system Emacs uses to display its frames. See section Window Frame Parameters, for documentation of individual parameters you can specify.

Variable: before-make-frame-hook
A normal hook run by make-frame before it actually creates the frame.

Variable: after-make-frame-hook
An abnormal hook run by make-frame after it creates the frame. Each function in after-make-frame-hook receives one argument, the frame just created.

Multiple Displays

A single Emacs can talk to more than one X display. Initially, Emacs uses just one display--the one chosen with the DISPLAY environment variable or with the `--display' option (see section `Initial Options' in The GNU Emacs Manual). To connect to another display, use the command make-frame-on-display or specify the display frame parameter when you create the frame.

Emacs treats each X server as a separate terminal, giving each one its own selected frame and its own minibuffer windows.

A few Lisp variables are terminal-local; that is, they have a separate binding for each terminal. The binding in effect at any time is the one for the terminal that the currently selected frame belongs to. These variables include default-minibuffer-frame, defining-kbd-macro, last-kbd-macro, and system-key-alist. They are always terminal-local, and can never be buffer-local (see section Buffer-Local Variables) or frame-local.

A single X server can handle more than one screen. A display name `host:server.screen' has three parts; the last part specifies the screen number for a given server. When you use two screens belonging to one server, Emacs knows by the similarity in their names that they share a single keyboard, and it treats them as a single terminal.

Command: make-frame-on-display display &optional parameters
This creates a new frame on display display, taking the other frame parameters from parameters. Aside from the display argument, it is like make-frame (see section Creating Frames).

Function: x-display-list
This returns a list that indicates which X displays Emacs has a connection to. The elements of the list are strings, and each one is a display name.

Function: x-open-connection display &optional xrm-string
This function opens a connection to the X display display. It does not create a frame on that display, but it permits you to check that communication can be established with that display.

The optional argument xrm-string, if not nil, is a string of resource names and values, in the same format used in the `.Xresources' file. The values you specify override the resource values recorded in the X server itself; they apply to all Emacs frames created on this display. Here's an example of what this string might look like:
"*BorderWidth: 3\n*InternalBorder: 2\n"
See section X Resources.

Function: x-close-connection display
This function closes the connection to display display. Before you can do this, you must first delete all the frames that were open on that display (see section Deleting Frames).

Frame Parameters

A frame has many parameters that control its appearance and behavior. Just what parameters a frame has depends on what display mechanism it uses.

Frame parameters exist for the sake of window systems. A terminal frame has a few parameters, mostly for compatibility's sake; only the height, width, name, title, buffer-list and buffer-predicate parameters do something special.

Access to Frame Parameters

These functions let you read and change the parameter values of a frame.

Function: frame-parameters frame
The function frame-parameters returns an alist listing all the parameters of frame and their values.

Function: modify-frame-parameters frame alist
This function alters the parameters of frame frame based on the elements of alist. Each element of alist has the form (parm . value), where parm is a symbol naming a parameter. If you don't mention a parameter in alist, its value doesn't change.

Initial Frame Parameters

You can specify the parameters for the initial startup frame by setting initial-frame-alist in your `.emacs' file.

Variable: initial-frame-alist
This variable's value is an alist of parameter values used when creating the initial window frame. You can set this variable to specify the appearance of the initial frame without altering subsequent frames. Each element has the form:
(parameter . value)
Emacs creates the initial frame before it reads your `~/.emacs' file. After reading that file, Emacs checks initial-frame-alist, and applies the parameter settings in the altered value to the already created initial frame.

If these settings affect the frame geometry and appearance, you'll see the frame appear with the wrong ones and then change to the specified ones. If that bothers you, you can specify the same geometry and appearance with X resources; those do take affect before the frame is created. See section `X Resources' in The GNU Emacs Manual.

X resource settings typically apply to all frames. If you want to specify some X resources solely for the sake of the initial frame, and you don't want them to apply to subsequent frames, here's how to achieve this. Specify parameters in default-frame-alist to override the X resources for subsequent frames; then, to prevent these from affecting the initial frame, specify the same parameters in initial-frame-alist with values that match the X resources.

If these parameters specify a separate minibuffer-only frame with (minibuffer . nil), and you have not created one, Emacs creates one for you.

Variable: minibuffer-frame-alist
This variable's value is an alist of parameter values used when creating an initial minibuffer-only frame--if such a frame is needed, according to the parameters for the main initial frame.

Variable: default-frame-alist
This is an alist specifying default values of frame parameters for all Emacs frames--the first frame, and subsequent frames. When using the X Window System, you can get the same results by means of X resources in many cases.

See also special-display-frame-alist, in section Choosing a Window for Display.

If you use options that specify window appearance when you invoke Emacs, they take effect by adding elements to default-frame-alist. One exception is `-geometry', which adds the specified position to initial-frame-alist instead. See section `Command Arguments' in The GNU Emacs Manual.

Window Frame Parameters

Just what parameters a frame has depends on what display mechanism it uses. Here is a table of the parameters that have special meanings in a window frame; of these, name, title, height, width, buffer-list and buffer-predicate provide meaningful information in terminal frames.

display
The display on which to open this frame. It should be a string of the form "host:dpy.screen", just like the DISPLAY environment variable.
title
If a frame has a non-nil title, it appears in the window system's border for the frame, and also in the mode line of windows in that frame if mode-line-frame-identification uses `%F' (see section %-Constructs in the Mode Line). This is normally the case when Emacs is not using a window system, and can only display one frame at a time. See section Frame Titles.
name
The name of the frame. The frame name serves as a default for the frame title, if the title parameter is unspecified or nil. If you don't specify a name, Emacs sets the frame name automatically (see section Frame Titles). If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame.
left
The screen position of the left edge, in pixels, with respect to the left edge of the screen. The value may be a positive number pos, or a list of the form (+ pos) which permits specifying a negative pos value. A negative number -pos, or a list of the form (- pos), actually specifies the position of the right edge of the window with respect to the right edge of the screen. A positive value of pos counts toward the left. Reminder: if the parameter is a negative integer -pos, then pos is positive. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as well.
top
The screen position of the top edge, in pixels, with respect to the top edge of the screen. The value may be a positive number pos, or a list of the form (+ pos) which permits specifying a negative pos value. A negative number -pos, or a list of the form (- pos), actually specifies the position of the bottom edge of the window with respect to the bottom edge of the screen. A positive value of pos counts toward the top. Reminder: if the parameter is a negative integer -pos, then pos is positive. Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as well.
icon-left
The screen position of the left edge of the frame's icon, in pixels, counting from the left edge of the screen. This takes effect if and when the frame is iconified.
icon-top
The screen position of the top edge of the frame's icon, in pixels, counting from the top edge of the screen. This takes effect if and when the frame is iconified.
user-position
When you create a frame and specify its screen position with the left and top parameters, use this parameter to say whether the specified position was user-specified (explicitly requested in some way by a human user) or merely program-specified (chosen by a program). A non-nil value says the position was user-specified. Window managers generally heed user-specified positions, and some heed program-specified positions too. But many ignore program-specified positions, placing the window in a default fashion or letting the user place it with the mouse. Some window managers, including twm, let the user specify whether to obey program-specified positions or ignore them. When you call make-frame, you should specify a non-nil value for this parameter if the values of the left and top parameters represent the user's stated preference; otherwise, use nil.
height
The height of the frame contents, in characters. (To get the height in pixels, call frame-pixel-height; see section Frame Size And Position.)
width
The width of the frame contents, in characters. (To get the height in pixels, call frame-pixel-width; see section Frame Size And Position.)
window-id
The number of the window-system window used by the frame.
minibuffer
Whether this frame has its own minibuffer. The value t means yes, nil means no, only means this frame is just a minibuffer. If the value is a minibuffer window (in some other frame), the new frame uses that minibuffer.
buffer-predicate
The buffer-predicate function for this frame. The function other-buffer uses this predicate (from the selected frame) to decide which buffers it should consider, if the predicate is not nil. It calls the predicate with one argument, a buffer, once for each buffer; if the predicate returns a non-nil value, it considers that buffer.
buffer-list
A list of buffers that have been selected in this frame, ordered most-recently-selected first.
font
The name of the font for displaying text in the frame. This is a string, either a valid font name for your system or the name of an Emacs fontset (see section Fontsets).
auto-raise
Whether selecting the frame raises it (non-nil means yes).
auto-lower
Whether deselecting the frame lowers it (non-nil means yes).
vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling, and which side of the frame they should be on. The possible values are left, right, and nil for no scroll bars.
horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling (non-nil means yes). (Horizontal scroll bars are not currently implemented.)
scroll-bar-width
The width of the vertical scroll bar, in pixels.
icon-type
The type of icon to use for this frame when it is iconified. If the value is a string, that specifies a file containing a bitmap to use. Any other non-nil value specifies the default bitmap icon (a picture of a gnu); nil specifies a text icon.
icon-name
The name to use in the icon for this frame, when and if the icon appears. If this is nil, the frame's title is used.
foreground-color
The color to use for the image of a character. This is a string; the window system defines the meaningful color names. If you set the foreground-color frame parameter, you should call frame-update-face-colors to update faces accordingly.
background-color
The color to use for the background of characters. If you set the background-color frame parameter, you should call frame-update-face-colors to update faces accordingly. See section Functions for Working with Faces.
background-mode
This parameter is either dark or light, according to whether the background color is a light one or a dark one.
mouse-color
The color for the mouse pointer.
cursor-color
The color for the cursor that shows point.
border-color
The color for the border of the frame.
display-type
This parameter describes the range of possible colors that can be used in this frame. Its value is color, grayscale or mono.
cursor-type
The way to display the cursor. The legitimate values are bar, box, and (bar . width). The symbol box specifies an ordinary black box overlaying the character after point; that is the default. The symbol bar specifies a vertical bar between characters as the cursor. (bar . width) specifies a bar width pixels wide.
border-width
The width in pixels of the window border.
internal-border-width
The distance in pixels between text and border.
unsplittable
If non-nil, this frame's window is never split automatically.
visibility
The state of visibility of the frame. There are three possibilities: nil for invisible, t for visible, and icon for iconified. See section Visibility of Frames.
menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar. The default is 1. See section The Menu Bar. (In Emacs versions that use the X toolkit, there is only one menu bar line; all that matters about the number you specify is whether it is greater than zero.)
Frame Size And Position

You can read or change the size and position of a frame using the frame parameters left, top, height, and width. Whatever geometry parameters you don't specify are chosen by the window manager in its usual fashion.

Here are some special features for working with sizes and positions:

Function: set-frame-position frame left top
This function sets the position of the top left corner of frame to left and top. These arguments are measured in pixels, and normally count from the top left corner of the screen.

Negative parameter values position the bottom edge of the window up from the bottom edge of the screen, or the right window edge to the left of the right edge of the screen. It would probably be better if the values were always counted from the left and top, so that negative arguments would position the frame partly off the top or left edge of the screen, but it seems inadvisable to change that now.

Function: frame-height &optional frame

Function: frame-width &optional frame
These functions return the height and width of frame, measured in lines and columns. If you don't supply frame, they use the selected frame.

Function: screen-height

Function: screen-width
These functions are old aliases for frame-height and frame-width. When you are using a non-window terminal, the size of the frame is normally the same as the size of the terminal screen.

Function: frame-pixel-height &optional frame

Function: frame-pixel-width &optional frame
These functions return the height and width of frame, measured in pixels. If you don't supply frame, they use the selected frame.

Function: frame-char-height &optional frame

Function: frame-char-width &optional frame
These functions return the height and width of a character in frame, measured in pixels. The values depend on the choice of font. If you don't supply frame, these functions use the selected frame.

Function: set-frame-size frame cols rows
This function sets the size of frame, measured in characters; cols and rows specify the new width and height.

To set the size based on values measured in pixels, use frame-char-height and frame-char-width to convert them to units of characters.

Function: set-frame-height frame lines &optional pretend
This function resizes frame to a height of lines lines. The sizes of existing windows in frame are altered proportionally to fit.

If pretend is non-nil, then Emacs displays lines lines of output in frame, but does not change its value for the actual height of the frame. This is only useful for a terminal frame. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame height "for real" does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on a terminal frame.

Function: set-frame-width frame width &optional pretend
This function sets the width of frame, measured in characters. The argument pretend has the same meaning as in set-frame-height.

The older functions set-screen-height and set-screen-width were used to specify the height and width of the screen, in Emacs versions that did not support multiple frames. They are semi-obsolete, but still work; they apply to the selected frame.

Function: x-parse-geometry geom
The function x-parse-geometry converts a standard X window geometry string to an alist that you can use as part of the argument to make-frame.

The alist describes which parameters were specified in geom, and gives the values specified for them. Each element looks like (parameter . value). The possible parameter values are left, top, width, and height.

For the size parameters, the value must be an integer. The position parameter names left and top are not totally accurate, because some values indicate the position of the right or bottom edges instead. These are the value possibilities for the position parameters:

an integer
A positive integer relates the left edge or top edge of the window to the left or top edge of the screen. A negative integer relates the right or bottom edge of the window to the right or bottom edge of the screen.
(+ position)
This specifies the position of the left or top edge of the window relative to the left or top edge of the screen. The integer position may be positive or negative; a negative value specifies a position outside the screen.
(- position)
This specifies the position of the right or bottom edge of the window relative to the right or bottom edge of the screen. The integer position may be positive or negative; a negative value specifies a position outside the screen.
Here is an example:
(x-parse-geometry "35x70+0-0")
     => ((height . 70) (width . 35)
         (top - 0) (left . 0))
Frame Titles

Every frame has a name parameter; this serves as the default for the frame title which window systems typically display at the top of the frame. You can specify a name explicitly by setting the name frame property.

Normally you don't specify the name explicitly, and Emacs computes the frame name automatically based on a template stored in the variable frame-title-format. Emacs recomputes the name each time the frame is redisplayed.

Variable: frame-title-format
This variable specifies how to compute a name for a frame when you have not explicitly specified one. The variable's value is actually a mode line construct, just like mode-line-format. See section The Data Structure of the Mode Line.

Variable: icon-title-format
This variable specifies how to compute the name for an iconified frame, when you have not explicitly specified the frame title. This title appears in the icon itself.

Variable: multiple-frames
This variable is set automatically by Emacs. Its value is t when there are two or more frames (not counting minibuffer-only frames or invisible frames). The default value of frame-title-format uses multiple-frames so as to put the buffer name in the frame title only when there is more than one frame.

Deleting Frames

Frames remain potentially visible until you explicitly delete them. A deleted frame cannot appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a frame aside from restoring a saved frame configuration (see section Frame Configurations); this is similar to the way windows behave.

Command: delete-frame &optional frame
This function deletes the frame frame. By default, frame is the selected frame.

Function: frame-live-p frame
The function frame-live-p returns non-nil if the frame frame has not been deleted.

Some window managers provide a command to delete a window. These work by sending a special message to the program that operates the window. When Emacs gets one of these commands, it generates a delete-frame event, whose normal definition is a command that calls the function delete-frame. See section Miscellaneous Window System Events.

Finding All Frames

Function: frame-list
The function frame-list returns a list of all the frames that have not been deleted. It is analogous to buffer-list for buffers. The list that you get is newly created, so modifying the list doesn't have any effect on the internals of Emacs.

Function: visible-frame-list
This function returns a list of just the currently visible frames. See section Visibility of Frames. (Terminal frames always count as "visible", even though only the selected one is actually displayed.)

Function: next-frame &optional frame minibuf
The function next-frame lets you cycle conveniently through all the frames from an arbitrary starting point. It returns the "next" frame after frame in the cycle. If frame is omitted or nil, it defaults to the selected frame.

The second argument, minibuf, says which frames to consider:

nil
Exclude minibuffer-only frames.
visible
Consider all visible frames.
0
Consider all visible or iconified frames.
a window
Consider only the frames using that particular window as their minibuffer.
anything else
Consider all frames.

Function: previous-frame &optional frame minibuf
Like next-frame, but cycles through all frames in the opposite direction.

See also next-window and previous-window, in section Cyclic Ordering of Windows.

Frames and Windows

Each window is part of one and only one frame; you can get the frame with window-frame.

Function: window-frame window
This function returns the frame that window is on.

All the non-minibuffer windows in a frame are arranged in a cyclic order. The order runs from the frame's top window, which is at the upper left corner, down and to the right, until it reaches the window at the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top. See section Cyclic Ordering of Windows.

Function: frame-top-window frame
This returns the topmost, leftmost window of frame frame.

At any time, exactly one window on any frame is selected within the frame. The significance of this designation is that selecting the frame also selects this window. You can get the frame's current selected window with frame-selected-window.

Function: frame-selected-window frame
This function returns the window on frame that is selected within frame.

Conversely, selecting a window for Emacs with select-window also makes that window selected within its frame. See section Selecting Windows.

Another function that (usually) returns one of the windows in a given frame is minibuffer-window. See section Minibuffer Miscellany.

Minibuffers and Frames

Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. If the frame has a minibuffer, you can get it with minibuffer-window (see section Minibuffer Miscellany).

However, you can also create a frame with no minibuffer. Such a frame must use the minibuffer window of some other frame. When you create the frame, you can specify explicitly the minibuffer window to use (in some other frame). If you don't, then the minibuffer is found in the frame which is the value of the variable default-minibuffer-frame. Its value should be a frame that does have a minibuffer.

If you use a minibuffer-only frame, you might want that frame to raise when you enter the minibuffer. If so, set the variable minibuffer-auto-raise to t. See section Raising and Lowering Frames.

Variable: default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by default. It is always local to the current terminal and cannot be buffer-local. See section Multiple Displays.

Input Focus

At any time, one frame in Emacs is the selected frame. The selected window always resides on the selected frame.

Function: selected-frame
This function returns the selected frame.

Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to shift the focus to various window objects. Either way, Emacs automatically keeps track of which frame has the focus.

Lisp programs can also switch frames "temporarily" by calling the function select-frame. This does not alter the window system's concept of focus; rather, it escapes from the window manager's control until that control is somehow reasserted.

When using a text-only terminal, only the selected terminal frame is actually displayed on the terminal. switch-frame is the only way to switch frames, and the change lasts until overridden by a subsequent call to switch-frame. Each terminal screen except for the initial one has a number, and the number of the selected frame appears in the mode line before the buffer name (see section Variables Used in the Mode Line).

Function: select-frame frame
This function selects frame frame, temporarily disregarding the focus of the X server if any. The selection of frame lasts until the next time the user does something to select a different frame, or until the next time this function is called.

Emacs cooperates with the window system by arranging to select frames as the server and window manager request. It does so by generating a special kind of input event, called a focus event, when appropriate. The command loop handles a focus event by calling handle-switch-frame. See section Focus Events.

Command: handle-switch-frame frame
This function handles a focus event by selecting frame frame.

Focus events normally do their job by invoking this command. Don't call it for any other reason.

Function: redirect-frame-focus frame focus-frame
This function redirects focus from frame to focus-frame. This means that focus-frame will receive subsequent keystrokes and events intended for frame. After such an event, the value of last-event-frame will be focus-frame. Also, switch-frame events specifying frame will instead select focus-frame.

If focus-frame is nil, that cancels any existing redirection for frame, which therefore once again receives its own events.

One use of focus redirection is for frames that don't have minibuffers. These frames use minibuffers on other frames. Activating a minibuffer on another frame redirects focus to that frame. This puts the focus on the minibuffer's frame, where it belongs, even though the mouse remains in the frame that activated the minibuffer.

Selecting a frame can also change focus redirections. Selecting frame bar, when foo had been selected, changes any redirections pointing to foo so that they point to bar instead. This allows focus redirection to work properly when the user switches from one frame to another using select-window.

This means that a frame whose focus is redirected to itself is treated differently from a frame whose focus is not redirected. select-frame affects the former but not the latter.

The redirection lasts until redirect-frame-focus is called to change it.

User Option: focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers focus when the user moves the mouse. Non-nil says that it does. When this is so, the command other-frame moves the mouse to a position consistent with the new selected frame.

Visibility of Frames

A window frame may be visible, invisible, or iconified. If it is visible, you can see its contents. If it is iconified, the frame's contents do not appear on the screen, but an icon does. If the frame is invisible, it doesn't show on the screen, not even as an icon.

Visibility is meaningless for terminal frames, since only the selected one is actually displayed in any case.

Command: make-frame-visible &optional frame
This function makes frame frame visible. If you omit frame, it makes the selected frame visible.

Command: make-frame-invisible &optional frame
This function makes frame frame invisible. If you omit frame, it makes the selected frame invisible.

Command: iconify-frame &optional frame
This function iconifies frame frame. If you omit frame, it iconifies the selected frame.

Function: frame-visible-p frame
This returns the visibility status of frame frame. The value is t if frame is visible, nil if it is invisible, and icon if it is iconified.

The visibility status of a frame is also available as a frame parameter. You can read or change it as such. See section Window Frame Parameters.

The user can iconify and deiconify frames with the window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. See section Miscellaneous Window System Events.

Raising and Lowering Frames

Most window systems use a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from "highest" to "lowest". Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it.

A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. Raising a window means moving it "up", to the top of the stack. Lowering a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen.

You can raise and lower Emacs frame Windows with these functions:

Command: raise-frame &optional frame
This function raises frame frame (default, the selected frame).

Command: lower-frame &optional frame
This function lowers frame frame (default, the selected frame).

User Option: minibuffer-auto-raise
If this is non-nil, activation of the minibuffer raises the frame that the minibuffer window is in.

You can also enable auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected) for any frame using frame parameters. See section Window Frame Parameters.

Frame Configurations

A frame configuration records the current arrangement of frames, all their properties, and the window configuration of each one. (See section Window Configurations.)

Function: current-frame-configuration
This function returns a frame configuration list that describes the current arrangement of frames and their contents.

Function: set-frame-configuration configuration
This function restores the state of frames described in configuration.

Mouse Tracking

Sometimes it is useful to track the mouse, which means to display something to indicate where the mouse is and move the indicator as the mouse moves. For efficient mouse tracking, you need a way to wait until the mouse actually moves.

The convenient way to track the mouse is to ask for events to represent mouse motion. Then you can wait for motion by waiting for an event. In addition, you can easily handle any other sorts of events that may occur. That is useful, because normally you don't want to track the mouse forever--only until some other event, such as the release of a button.

Special Form: track-mouse body...
This special form executes body, with generation of mouse motion events enabled. Typically body would use read-event to read the motion events and modify the display accordingly. See section Motion Events, for the format of mouse motion events.

The value of track-mouse is that of the last form in body. You should design body to return when it sees the up-event that indicates the release of the button, or whatever kind of event means it is time to stop tracking.

The usual purpose of tracking mouse motion is to indicate on the screen the consequences of pushing or releasing a button at the current position.

In many cases, you can avoid the need to track the mouse by using the mouse-face text property (see section Properties with Special Meanings). That works at a much lower level and runs more smoothly than Lisp-level mouse tracking.

Mouse Position

The functions mouse-position and set-mouse-position give access to the current position of the mouse.

Function: mouse-position
This function returns a description of the position of the mouse. The value looks like (frame x . y), where x and y are integers giving the position in characters relative to the top left corner of the inside of frame.

Function: set-mouse-position frame x y
This function warps the mouse to position x, y in frame frame. The arguments x and y are integers, giving the position in characters relative to the top left corner of the inside of frame. If frame is not visible, this function does nothing. The return value is not significant.

Function: mouse-pixel-position
This function is like mouse-position except that it returns coordinates in units of pixels rather than units of characters.

Function: set-mouse-pixel-position frame x y
This function warps the mouse like set-mouse-position except that x and y are in units of pixels rather than units of characters. These coordinates are not required to be within the frame.

If frame is not visible, this function does nothing. The return value is not significant.

Pop-Up Menus

When using a window system, a Lisp program can pop up a menu so that the user can choose an alternative with the mouse.

Function: x-popup-menu position menu
This function displays a pop-up menu and returns an indication of what selection the user makes.

The argument position specifies where on the screen to put the menu. It can be either a mouse button event (which says to put the menu where the user actuated the button) or a list of this form:
((xoffset yoffset) window)
where xoffset and yoffset are coordinates, measured in pixels, counting from the top left corner of window's frame.

If position is t, it means to use the current mouse position. If position is nil, it means to precompute the key binding equivalents for the keymaps specified in menu, without actually displaying or popping up the menu.

The argument menu says what to display in the menu. It can be a keymap or a list of keymaps (see section Menu Keymaps). Alternatively, it can have the following form:
(title pane1 pane2...)
where each pane is a list of form
(title (line . item)...)
Each line should be a string, and each item should be the value to return if that line is chosen.

Usage note: Don't use x-popup-menu to display a menu if you could do the job with a prefix key defined with a menu keymap. If you use a menu keymap to implement a menu, C-h c and C-h a can see the individual items in that menu and provide help for them. If instead you implement the menu by defining a command that calls x-popup-menu, the help facilities cannot know what happens inside that command, so they cannot give any help for the menu's items.

The menu bar mechanism, which lets you switch between submenus by moving the mouse, cannot look within the definition of a command to see that it calls x-popup-menu. Therefore, if you try to implement a submenu using x-popup-menu, it cannot work with the menu bar in an integrated fashion. This is why all menu bar submenus are implemented with menu keymaps within the parent menu, and never with x-popup-menu. See section The Menu Bar,

If you want a menu bar submenu to have contents that vary, you should still use a menu keymap to implement it. To make the contents vary, add a hook function to menu-bar-update-hook to update the contents of the menu keymap as necessary.

Dialog Boxes

A dialog box is a variant of a pop-up menu--it looks a little different, it always appears in the center of a frame, and it has just one level and one pane. The main use of dialog boxes is for asking questions that the user can answer with "yes", "no", and a few other alternatives. The functions y-or-n-p and yes-or-no-p use dialog boxes instead of the keyboard, when called from commands invoked by mouse clicks.

Function: x-popup-dialog position contents
This function displays a pop-up dialog box and returns an indication of what selection the user makes. The argument contents specifies the alternatives to offer; it has this format:
(title (string . value)...)
which looks like the list that specifies a single pane for x-popup-menu.

The return value is value from the chosen alternative.

An element of the list may be just a string instead of a cons cell (string . value). That makes a box that cannot be selected.

If nil appears in the list, it separates the left-hand items from the right-hand items; items that precede the nil appear on the left, and items that follow the nil appear on the right. If you don't include a nil in the list, then approximately half the items appear on each side.

Dialog boxes always appear in the center of a frame; the argument position specifies which frame. The possible values are as in x-popup-menu, but the precise coordinates don't matter; only the frame matters.

In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the frame.

Pointer Shapes

These variables specify which shape to use for the mouse pointer in various situations, when using the X Window System:

x-pointer-shape
This variable specifies the pointer shape to use ordinarily in the Emacs frame.
x-sensitive-text-pointer-shape
This variable specifies the pointer shape to use when the mouse is over mouse-sensitive text.
These variables affect newly created frames. They do not normally affect existing frames; however, if you set the mouse color of a frame, that also updates its pointer shapes based on the current values of these variables. See section Window Frame Parameters.

The values you can use, to specify either of these pointer shapes, are defined in the file `lisp/term/x-win.el'. Use M-x apropos RET x-pointer RET to see a list of them.

Window System Selections

The X server records a set of selections which permit transfer of data between application programs. The various selections are distinguished by selection types, represented in Emacs by symbols. X clients including Emacs can read or set the selection for any given type.

Function: x-set-selection type data
This function sets a "selection" in the X server. It takes two arguments: a selection type type, and the value to assign to it, data. If data is nil, it means to clear out the selection. Otherwise, data may be a string, a symbol, an integer (or a cons of two integers or list of two integers), an overlay, or a cons of two markers pointing to the same buffer. An overlay or a pair of markers stands for text in the overlay or between the markers.

The argument data may also be a vector of valid non-vector selection values.

Each possible type has its own selection value, which changes independently. The usual values of type are PRIMARY and SECONDARY; these are symbols with upper-case names, in accord with X Window System conventions. The default is PRIMARY.

Function: x-get-selection &optional type data-type
This function accesses selections set up by Emacs or by other X clients. It takes two optional arguments, type and data-type. The default for type, the selection type, is PRIMARY.

The data-type argument specifies the form of data conversion to use, to convert the raw data obtained from another X client into Lisp data. Meaningful values include TEXT, STRING, TARGETS, LENGTH, DELETE, FILE_NAME, CHARACTER_POSITION, LINE_NUMBER, COLUMN_NUMBER, OWNER_OS, HOST_NAME, USER, CLASS, NAME, ATOM, and INTEGER. (These are symbols with upper-case names in accord with X conventions.) The default for data-type is STRING.

The X server also has a set of numbered cut buffers which can store text or other data being moved between applications. Cut buffers are considered obsolete, but Emacs supports them for the sake of X clients that still use them.

Function: x-get-cut-buffer n
This function returns the contents of cut buffer number n.

Function: x-set-cut-buffer string
This function stores string into the first cut buffer (cut buffer 0), moving the other values down through the series of cut buffers, much like the way successive kills in Emacs move down the kill ring.

Variable: selection-coding-system
This variable specifies the coding system to use when reading and writing a selections, the clipboard, or a cut buffer. See section Coding Systems. The default is compound-text.

Looking up Font Names

Function: x-list-font pattern &optional face frame maximum
This function returns a list of available font names that match pattern. If the optional arguments face and frame are specified, then the list is limited to fonts that are the same size as face currently is on frame.

The argument pattern should be a string, perhaps with wildcard characters: the `*' character matches any substring, and the `?' character matches any single character. Pattern matching of font names ignores case.

If you specify face and frame, face should be a face name (a symbol) and frame should be a frame.

The optional argument maximum sets a limit on how many fonts to return. If this is non-nil, then the return value is truncated after the first maximum matching fonts. Specifying a small value for maximum can make this function much faster, in cases where many fonts match the pattern.

Fontsets

A fontset is a list of fonts, each assigned to a range of character codes. An individual font cannot display the whole range of characters that Emacs supports, but a fontset can. Fontsets have names, just as fonts do, and you can use a fontset name in place of a font name when you specify the "font" for a frame or a face. Here is information about defining a fontset under Lisp program control.

Function: create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
This function defines a new fontset according to the specification string fontset-spec. The string should have this format:
fontpattern, [charsetname:fontname]...
Whitespace characters before and after the commas are ignored.

The first part of the string, fontpattern, should have the form of a standard X font name, except that the last two fields should be `fontset-alias'.

The new fontset has two names, one long and one short. The long name is fontpattern in its entirety. The short name is `fontset-alias'. You can refer to the fontset by either name. If a fontset with the same name already exists, an error is signaled, unless noerror is non-nil, in which case this function does nothing.

If optional argument style-variant-p is non-nil, that says to create bold, italic and bold-italic variants of the fontset as well. These variant fontsets do not have a short name, only a long one, which is made by altering fontpattern to indicate the bold or italic status.

The specification string also says which fonts to use in the fontset. See below for the details.

The construct `charset:font' specifies which font to use (in this fontset) for one particular character set. Here, charset is the name of a character set, and font is the font to use for that character set. You can use this construct any number of times in the specification string.

For the remaining character sets, those that you don't specify explicitly, Emacs chooses a font based on fontpattern: it replaces `fontset-alias' with a value that names one character set. For the ASCII character set, `fontset-alias' is replaced with `ISO8859-1'.

In addition, when several consecutive fields are wildcards, Emacs collapses them into a single wildcard. This is to prevent use of auto-scaled fonts. Fonts made by scaling larger fonts are not usable for editing, and scaling a smaller font is not useful because it is better to use the smaller font in its own size, which Emacs does.

Thus if fontpattern is this,
-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
the font specification for ASCII characters would be this:
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
and the font specification for Chinese GB2312 characters would be this:
-*-fixed-medium-r-normal-*-24-*-gb2312*-*
You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that have `song ti' or `fangsong ti' in the family field. In such a case, `Fontset-n' can be specified as below:
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
Then, the font specifications for all but Chinese GB2312 characters have `fixed' in the family field, and the font specification for Chinese GB2312 characters has a wild card `*' in the family field.

Color Names

Function: x-color-defined-p color &optional frame
This function reports whether a color name is meaningful. It returns t if so; otherwise, nil. The argument frame says which frame's display to ask about; if frame is omitted or nil, the selected frame is used.

Note that this does not tell you whether the display you are using really supports that color. You can ask for any defined color on any kind of display, and you will get some result--that is how the X server works. Here's an approximate way to test whether your display supports the color color:
(defun x-color-supported-p (color &optional frame)
  (and (x-color-defined-p color frame)
       (or (x-display-color-p frame)
           (member color '("black" "white"))
           (and (> (x-display-planes frame) 1)
                (equal color "gray")))))
Function: x-color-values color &optional frame
This function returns a value that describes what color should ideally look like. If color is defined, the value is a list of three integers, which give the amount of red, the amount of green, and the amount of blue. Each integer ranges in principle from 0 to 65535, but in practice no value seems to be above 65280. If color is not defined, the value is nil.
(x-color-values "black")
     => (0 0 0)
(x-color-values "white")
     => (65280 65280 65280)
(x-color-values "red")
     => (65280 0 0)
(x-color-values "pink")
     => (65280 49152 51968)
(x-color-values "hungry")
     => nil
The color values are returned for frame's display. If frame is omitted or nil, the information is returned for the selected frame's display.

X Resources

Function: x-get-resource attribute class &optional component subclass
The function x-get-resource retrieves a resource value from the X Windows defaults database.

Resources are indexed by a combination of a key and a class. This function searches using a key of the form `instance.attribute' (where instance is the name under which Emacs was invoked), and using `Emacs.class' as the class.

The optional arguments component and subclass add to the key and the class, respectively. You must specify both of them or neither. If you specify them, the key is `instance.component.attribute', and the class is `Emacs.class.subclass'.

Variable: x-resource-class
This variable specifies the application name that x-get-resource should look up. The default value is "Emacs". You can examine X resources for application names other than "Emacs" by binding this variable to some other string, around a call to x-get-resource.

See section `X Resources' in The GNU Emacs Manual.

Data about the X Server

This section describes functions you can use to get information about the capabilities and origin of an X display that Emacs is using. Each of these functions lets you specify the display you are interested in: the display argument can be either a display name, or a frame (meaning use the display that frame is on). If you omit the display argument, or specify nil, that means to use the selected frame's display.

Function: x-display-screens &optional display
This function returns the number of screens associated with the display.

Function: x-server-version &optional display
This function returns the list of version numbers of the X server running the display.

Function: x-server-vendor &optional display
This function returns the vendor that provided the X server software.

Function: x-display-pixel-height &optional display
This function returns the height of the screen in pixels.

Function: x-display-mm-height &optional display
This function returns the height of the screen in millimeters.

Function: x-display-pixel-width &optional display
This function returns the width of the screen in pixels.

Function: x-display-mm-width &optional display
This function returns the width of the screen in millimeters.

Function: x-display-backing-store &optional display
This function returns the backing store capability of the screen. Values can be the symbols always, when-mapped, or not-useful.

Function: x-display-save-under &optional display
This function returns non-nil if the display supports the SaveUnder feature.

Function: x-display-planes &optional display
This function returns the number of planes the display supports.

Function: x-display-visual-class &optional display
This function returns the visual class for the screen. The value is one of the symbols static-gray, gray-scale, static-color, pseudo-color, true-color, and direct-color.

Function: x-display-grayscale-p &optional display
This function returns t if the screen can display shades of gray.

Function: x-display-color-p &optional display
This function returns t if the screen is a color screen.

Function: x-display-color-cells &optional display
This function returns the number of color cells the screen supports.

Positions

A position is the index of a character in the text of a buffer. More precisely, a position identifies the place between two characters (or before the first character, or after the last character), so we can speak of the character before or after a given position. However, we often speak of the character "at" a position, meaning the character after that position.

Positions are usually represented as integers starting from 1, but can also be represented as markers---special objects that relocate automatically when text is inserted or deleted so they stay with the surrounding characters. See section Markers.

Point

Point is a special buffer position used by many editing commands, including the self-inserting typed characters and text insertion functions. Other commands move point through the text to allow editing and insertion at different places.

Like other positions, point designates a place between two characters (or before the first character, or after the last character), rather than a particular character. Usually terminals display the cursor over the character that immediately follows point; point is actually before the character on which the cursor sits.

The value of point is a number between 1 and the buffer size plus 1. If narrowing is in effect (see section Narrowing), then point is constrained to fall within the accessible portion of the buffer (possibly at one end of it).

Each buffer has its own value of point, which is independent of the value of point in other buffers. Each window also has a value of point, which is independent of the value of point in other windows on the same buffer. This is why point can have different values in various windows that display the same buffer. When a buffer appears in only one window, the buffer's point and the window's point normally have the same value, so the distinction is rarely important. See section Windows and Point, for more details.

Function: point
This function returns the value of point in the current buffer, as an integer.
(point)
     => 175
Function: point-min
This function returns the minimum accessible value of point in the current buffer. This is normally 1, but if narrowing is in effect, it is the position of the start of the region that you narrowed to. (See section Narrowing.)

Function: point-max
This function returns the maximum accessible value of point in the current buffer. This is (1+ (buffer-size)), unless narrowing is in effect, in which case it is the position of the end of the region that you narrowed to. (See section Narrowing).

Function: buffer-end flag
This function returns (point-min) if flag is less than 1, (point-max) otherwise. The argument flag must be a number.

Function: buffer-size
This function returns the total number of characters in the current buffer. In the absence of any narrowing (see section Narrowing), point-max returns a value one larger than this.
(buffer-size)
     => 35
(point-max)
     => 36
Motion

Motion functions change the value of point, either relative to the current value of point, relative to the beginning or end of the buffer, or relative to the edges of the selected window. See section Point.

Motion by Characters

These functions move point based on a count of characters. goto-char is the fundamental primitive; the other functions use that.

Command: goto-char position
This function sets point in the current buffer to the value position. If position is less than 1, it moves point to the beginning of the buffer. If position is greater than the length of the buffer, it moves point to the end.

If narrowing is in effect, position still counts from the beginning of the buffer, but point cannot go outside the accessible portion. If position is out of range, goto-char moves point to the beginning or the end of the accessible portion.

When this function is called interactively, position is the numeric prefix argument, if provided; otherwise it is read from the minibuffer.

goto-char returns position.

Command: forward-char &optional count
This function moves point count characters forward, towards the end of the buffer (or backward, towards the beginning of the buffer, if count is negative). If the function attempts to move point past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), an error is signaled with error code beginning-of-buffer or end-of-buffer.

In an interactive call, count is the numeric prefix argument.

Command: backward-char &optional count
This function moves point count characters backward, towards the beginning of the buffer (or forward, towards the end of the buffer, if count is negative). If the function attempts to move point past the beginning or end of the buffer (or the limits of the accessible portion, when narrowing is in effect), an error is signaled with error code beginning-of-buffer or end-of-buffer.

In an interactive call, count is the numeric prefix argument.

Motion by Words

These functions for parsing words use the syntax table to decide whether a given character is part of a word. See section Syntax Tables.

Command: forward-word count
This function moves point forward count words (or backward if count is negative). "Moving one word" means moving until point crosses a word-constituent character and then encounters a word-separator character (or the boundary of the accessible part of the buffer).

If it is possible to move count words, without being stopped by the buffer boundary (except perhaps after the last word), the value is t. Otherwise, the return value is nil and point stops at the buffer boundary.

In an interactive call, count is set to the numeric prefix argument.

Command: backward-word count
This function is just like forward-word, except that it moves backward until encountering the front of a word, rather than forward.

In an interactive call, count is set to the numeric prefix argument.

This function is rarely used in programs, as it is more efficient to call forward-word with a negative argument.

Variable: words-include-escapes
This variable affects the behavior of forward-word and everything that uses it. If it is non-nil, then characters in the "escape" and "character quote" syntax classes count as part of words. Otherwise, they do not.

Motion to an End of the Buffer

To move point to the beginning of the buffer, write:
(goto-char (point-min))
Likewise, to move to the end of the buffer, use:
(goto-char (point-max))
Here are two commands that users use to do these things. They are documented here to warn you not to use them in Lisp programs, because they set the mark and display messages in the echo area.

Command: beginning-of-buffer &optional n
This function moves point to the beginning of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If n is non-nil, then it puts point n tenths of the way from the beginning of the buffer.

In an interactive call, n is the numeric prefix argument, if provided; otherwise n defaults to nil.

Warning: Don't use this function in Lisp programs!

Command: end-of-buffer &optional n
This function moves point to the end of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If n is non-nil, then it puts point n tenths of the way from the end of the buffer.

In an interactive call, n is the numeric prefix argument, if provided; otherwise n defaults to nil.

Warning: Don't use this function in Lisp programs!

Motion by Text Lines

Text lines are portions of the buffer delimited by newline characters, which are regarded as part of the previous line. The first text line begins at the beginning of the buffer, and the last text line ends at the end of the buffer whether or not the last character is a newline. The division of the buffer into text lines is not affected by the width of the window, by line continuation in display, or by how tabs and control characters are displayed.

Command: goto-line line
This function moves point to the front of the lineth line, counting from line 1 at beginning of the buffer. If line is less than 1, it moves point to the beginning of the buffer. If line is greater than the number of lines in the buffer, it moves point to the end of the buffer--that is, the end of the last line of the buffer. This is the only case in which goto-line does not necessarily move to the beginning of a line.

If narrowing is in effect, then line still counts from the beginning of the buffer, but point cannot go outside the accessible portion. So goto-line moves point to the beginning or end of the accessible portion, if the line number specifies an inaccessible position.

The return value of goto-line is the difference between line and the line number of the line to which point actually was able to move (in the full buffer, before taking account of narrowing). Thus, the value is positive if the scan encounters the real end of the buffer before finding the specified line. The value is zero if scan encounters the end of the accessible portion but not the real end of the buffer.

In an interactive call, line is the numeric prefix argument if one has been provided. Otherwise line is read in the minibuffer.

Command: beginning-of-line &optional count
This function moves point to the beginning of the current line. With an argument count not nil or 1, it moves forward count-1 lines and then to the beginning of the line.

If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled.

Command: end-of-line &optional count
This function moves point to the end of the current line. With an argument count not nil or 1, it moves forward count-1 lines and then to the end of the line.

If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled.

Command: forward-line &optional count
This function moves point forward count lines, to the beginning of the line. If count is negative, it moves point -count lines backward, to the beginning of a line. If count is zero, it moves point to the beginning of the current line.

If forward-line encounters the beginning or end of the buffer (or of the accessible portion) before finding that many lines, it sets point there. No error is signaled.

forward-line returns the difference between count and the number of lines actually moved. If you attempt to move down five lines from the beginning of a buffer that has only three lines, point stops at the end of the last line, and the value will be 2.

In an interactive call, count is the numeric prefix argument.

Function: count-lines start end
This function returns the number of lines between the positions start and end in the current buffer. If start and end are equal, then it returns 0. Otherwise it returns at least 1, even if start and end are on the same line. This is because the text between them, considered in isolation, must contain at least one line unless it is empty.

Here is an example of using count-lines:
(defun current-line ()
  "Return the vertical position of point..."
  (+ (count-lines (window-start) (point))
     (if (= (current-column) 0) 1 0)
     -1))
Also see the functions bolp and eolp in section Examining Text Near Point. These functions do not move point, but test whether it is already at the beginning or end of a line.

Motion by Screen Lines

The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen lines, which are defined by the way the text appears on the screen. A text line is a single screen line if it is short enough to fit the width of the selected window, but otherwise it may occupy several screen lines.

In some cases, text lines are truncated on the screen rather than continued onto additional screen lines. In these cases, vertical-motion moves point much like forward-line. See section Truncation.

Because the width of a given string depends on the flags that control the appearance of certain characters, vertical-motion behaves differently, for a given piece of text, depending on the buffer it is in, and even on the selected window (because the width, the truncation flag, and display table may vary between windows). See section Usual Display Conventions.

These functions scan text to determine where screen lines break, and thus take time proportional to the distance scanned. If you intend to use them heavily, Emacs provides caches which may improve the performance of your code. See section Truncation.

Function: vertical-motion count &optional window
This function moves point to the start of the screen line count screen lines down from the screen line containing point. If count is negative, it moves up instead.

vertical-motion returns the number of screen lines over which it moved point. The value may be less in absolute value than count if the beginning or end of the buffer was reached.

The window window is used for obtaining parameters such as the width, the horizontal scrolling, and the display table. But vertical-motion always operates on the current buffer, even if window currently displays some other buffer.

Command: move-to-window-line count
This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen line count screen lines from the top of the window. If count is negative, that specifies a position -count lines from the bottom (or the last line of the buffer, if the buffer ends above the specified screen position).

If count is nil, then point moves to the beginning of the line in the middle of the window. If the absolute value of count is greater than the size of the window, then point moves to the place that would appear on that screen line if the window were tall enough. This will probably cause the next redisplay to scroll to bring that location onto the screen.

In an interactive call, count is the numeric prefix argument.

The value returned is the window line number point has moved to, with the top line in the window numbered 0.

Function: compute-motion from frompos to topos width offsets window
This function scans the current buffer, calculating screen positions. It scans the buffer forward from position from, assuming that is at screen coordinates frompos, to position to or coordinates topos, whichever comes first. It returns the ending buffer position and screen coordinates.

The coordinate arguments frompos and topos are cons cells of the form (hpos . vpos).

The argument width is the number of columns available to display text; this affects handling of continuation lines. Use the value returned by window-width for the window of your choice; normally, use (window-width window).

The argument offsets is either nil or a cons cell of the form (hscroll . tab-offset). Here hscroll is the number of columns not being displayed at the left margin; most callers get this by calling window-hscroll. Meanwhile, tab-offset is the offset between column numbers on the screen and column numbers in the buffer. This can be nonzero in a continuation line, when the previous screen lines' widths do not add up to a multiple of tab-width. It is always zero in a non-continuation line.

The window window serves only to specify which display table to use. compute-motion always operates on the current buffer, regardless of what buffer is displayed in window.

The return value is a list of five elements:
(pos vpos hpos prevhpos contin)
Here pos is the buffer position where the scan stopped, vpos is the vertical screen position, and hpos is the horizontal screen position.

The result prevhpos is the horizontal position one character back from pos. The result contin is t if the last line was continued after (or within) the previous character.

For example, to find the buffer position of column col of screen line line of a certain window, pass the window's display start location as from and the window's upper-left coordinates as frompos. Pass the buffer's (point-max) as to, to limit the scan to the end of the accessible portion of the buffer, and pass line and col as topos. Here's a function that does this:
(defun coordinates-of-position (col line)
  (car (compute-motion (window-start)
                       '(0 . 0)
                       (point-max)
                       (cons col line)
                       (window-width)
                       (cons (window-hscroll) 0)
                       (selected-window))))
When you use compute-motion for the minibuffer, you need to use minibuffer-prompt-width to get the horizontal position of the beginning of the first screen line. See section Minibuffer Miscellany.

Moving over Balanced Expressions

Here are several functions concerned with balanced-parenthesis expressions (also called sexps in connection with moving across them in Emacs). The syntax table controls how these functions interpret various characters; see section Syntax Tables. See section Parsing Balanced Expressions, for lower-level primitives for scanning sexps or parts of sexps. For user-level commands, see section `Lists Commands' in GNU Emacs Manual.

Command: forward-list arg
This function moves forward across arg balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.)

Command: backward-list arg
This function moves backward across arg balanced groups of parentheses. (Other syntactic entities such as words or paired string quotes are ignored.)

Command: up-list arg
This function moves forward out of arg levels of parentheses. A negative argument means move backward but still to a less deep spot.

Command: down-list arg
This function moves forward into arg levels of parentheses. A negative argument means move backward but still go deeper in parentheses (-arg levels).

Command: forward-sexp arg
This function moves forward across arg balanced expressions. Balanced expressions include both those delimited by parentheses and other kinds, such as words and string constants. For example,
---------- Buffer: foo ----------
(concat-!- "foo " (car x) y z)
---------- Buffer: foo ----------

(forward-sexp 3)
     => nil

---------- Buffer: foo ----------
(concat "foo " (car x) y-!- z)
---------- Buffer: foo ----------
Command: backward-sexp arg
This function moves backward across arg balanced expressions.

Command: beginning-of-defun arg
This function moves back to the argth beginning of a defun. If arg is negative, this actually moves forward, but it still moves to the beginning of a defun, not to the end of one.

Command: end-of-defun arg
This function moves forward to the argth end of a defun. If arg is negative, this actually moves backward, but it still moves to the end of a defun, not to the beginning of one.

User Option: defun-prompt-regexp
If non-nil, this variable holds a regular expression that specifies what text can appear before the open-parenthesis that starts a defun. That is to say, a defun begins on a line that starts with a match for this regular expression, followed by a character with open-parenthesis syntax.

Skipping Characters

The following two functions move point over a specified set of characters. For example, they are often used to skip whitespace. For related functions, see section Motion and Syntax.

Function: skip-chars-forward character-set &optional limit
This function moves point in the current buffer forward, skipping over a given set of characters. It examines the character following point, then advances point if the character matches character-set. This continues until it reaches a character that does not match. The function returns the number of characters moved over.

The argument character-set is like the inside of a `[...]' in a regular expression except that `]' is never special and `\' quotes `^', `-' or `\'. Thus, "a-zA-Z" skips over all letters, stopping before the first nonletter, and "^a-zA-Z" skips nonletters stopping before the first letter. See section Regular Expressions.

If limit is supplied (it must be a number or a marker), it specifies the maximum position in the buffer that point can be skipped to. Point will stop at or before limit.

In the following example, point is initially located directly before the `T'. After the form is evaluated, point is located at the end of that line (between the `t' of `hat' and the newline). The function skips all letters and spaces, but not newlines.
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(skip-chars-forward "a-zA-Z ")
     => nil

---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
Function: skip-chars-backward character-set &optional limit
This function moves point backward, skipping characters that match character-set, until limit. It is just like skip-chars-forward except for the direction of motion.

The return value indicates the distance traveled. It is an integer that is zero or less.

Excursions

It is often useful to move point "temporarily" within a localized portion of the program, or to switch buffers temporarily. This is called an excursion, and it is done with the save-excursion special form. This construct saves the current buffer and its values of point and the mark so they can be restored after the completion of the excursion.

The forms for saving and restoring the configuration of windows are described elsewhere (see section Window Configurations, and see section Frame Configurations).

Special Form: save-excursion forms...
The save-excursion special form saves the identity of the current buffer and the values of point and the mark in it, evaluates forms, and finally restores the buffer and its saved values of point and the mark. All three saved values are restored even in case of an abnormal exit via throw or error (see section Nonlocal Exits).

The save-excursion special form is the standard way to switch buffers or move point within one part of a program and avoid affecting the rest of the program. It is used more than 4000 times in the Lisp sources of Emacs.

save-excursion does not save the values of point and the mark for other buffers, so changes in other buffers remain in effect after save-excursion exits.

Likewise, save-excursion does not restore window-buffer correspondences altered by functions such as switch-to-buffer. One way to restore these correspondences, and the selected window, is to use save-window-excursion inside save-excursion (see section Window Configurations).

The value returned by save-excursion is the result of the last of forms, or nil if no forms are given.
(save-excursion forms)
==
(let ((old-buf (current-buffer))
      (old-pnt (point-marker))
      (old-mark (copy-marker (mark-marker))))
  (unwind-protect
      (progn forms)
    (set-buffer old-buf)
    (goto-char old-pnt)
    (set-marker (mark-marker) old-mark)))
Warning: Ordinary insertion of text adjacent to the saved point value relocates the saved value, just as it relocates all markers. Therefore, when the saved point value is restored, it normally comes before the inserted text.

Although save-excursion saves the location of the mark, it does not prevent functions which modify the buffer from setting deactivate-mark, and thus causing the deactivation of the mark after the command finishes. See section The Mark.

Narrowing

Narrowing means limiting the text addressable by Emacs editing commands to a limited range of characters in a buffer. The text that remains addressable is called the accessible portion of the buffer.

Narrowing is specified with two buffer positions which become the beginning and end of the accessible portion. For most editing commands and most Emacs primitives, these positions replace the values of the beginning and end of the buffer. While narrowing is in effect, no text outside the accessible portion is displayed, and point cannot move outside the accessible portion.

Values such as positions or line numbers, which usually count from the beginning of the buffer, do so despite narrowing, but the functions which use them refuse to operate on text that is inaccessible.

The commands for saving buffers are unaffected by narrowing; they save the entire buffer regardless of any narrowing.

Command: narrow-to-region start end
This function sets the accessible portion of the current buffer to start at start and end at end. Both arguments should be character positions.

In an interactive call, start and end are set to the bounds of the current region (point and the mark, with the smallest first).

Command: narrow-to-page move-count
This function sets the accessible portion of the current buffer to include just the current page. An optional first argument move-count non-nil means to move forward or backward by move-count pages and then narrow to one page. The variable page-delimiter specifies where pages start and end (see section Standard Regular Expressions Used in Editing).

In an interactive call, move-count is set to the numeric prefix argument.

Command: widen
This function cancels any narrowing in the current buffer, so that the entire contents are accessible. This is called widening. It is equivalent to the following expression:
(narrow-to-region 1 (1+ (buffer-size)))
Special Form: save-restriction body...
This special form saves the current bounds of the accessible portion, evaluates the body forms, and finally restores the saved bounds, thus restoring the same state of narrowing (or absence thereof) formerly in effect. The state of narrowing is restored even in the event of an abnormal exit via throw or error (see section Nonlocal Exits). Therefore, this construct is a clean way to narrow a buffer temporarily.

The value returned by save-restriction is that returned by the last form in body, or nil if no body forms were given.

Caution: it is easy to make a mistake when using the save-restriction construct. Read the entire description here before you try it.

If body changes the current buffer, save-restriction still restores the restrictions on the original buffer (the buffer whose restrictions it saved from), but it does not restore the identity of the current buffer.

save-restriction does not restore point and the mark; use save-excursion for that. If you use both save-restriction and save-excursion together, save-excursion should come first (on the outside). Otherwise, the old point value would be restored with temporary narrowing still in effect. If the old point value were outside the limits of the temporary narrowing, this would fail to restore it accurately.

The save-restriction special form records the values of the beginning and end of the accessible portion as distances from the beginning and end of the buffer. In other words, it records the amount of inaccessible text before and after the accessible portion.

This method yields correct results if body does further narrowing. However, save-restriction can become confused if the body widens and then makes changes outside the range of the saved narrowing. When this is what you want to do, save-restriction is not the right tool for the job. Here is what you must use instead:
(let ((beg (point-min-marker))
      (end (point-max-marker)))
  (unwind-protect
      (progn body)
    (save-excursion
      (set-buffer (marker-buffer beg))
      (narrow-to-region beg end))))
Here is a simple example of correct use of save-restriction:
---------- Buffer: foo ----------
This is the contents of foo
This is the contents of foo
This is the contents of foo-!-
---------- Buffer: foo ----------

(save-excursion
  (save-restriction
    (goto-char 1)
    (forward-line 2)
    (narrow-to-region 1 (point))
    (goto-char (point-min))
    (replace-string "foo" "bar")))

---------- Buffer: foo ----------
This is the contents of bar
This is the contents of bar
This is the contents of foo-!-
---------- Buffer: foo ----------
Markers

A marker is a Lisp object used to specify a position in a buffer relative to the surrounding text. A marker changes its offset from the beginning of the buffer automatically whenever text is inserted or deleted, so that it stays with the two characters on either side of it.

Overview of Markers

A marker specifies a buffer and a position in that buffer. The marker can be used to represent a position in the functions that require one, just as an integer could be used. See section Positions, for a complete description of positions.

A marker has two attributes: the marker position, and the marker buffer. The marker position is an integer that is equivalent (at a given time) to the marker as a position in that buffer. But the marker's position value can change often during the life of the marker. Insertion and deletion of text in the buffer relocate the marker. The idea is that a marker positioned between two characters remains between those two characters despite insertion and deletion elsewhere in the buffer. Relocation changes the integer equivalent of the marker.

Deleting text around a marker's position leaves the marker between the characters immediately before and after the deleted text. Inserting text at the position of a marker normally leaves the marker either in front of or after the new text, depending on the marker's insertion type (see section Marker Insertion Types)---unless the insertion is done with insert-before-markers (see section Inserting Text).

Insertion and deletion in a buffer must check all the markers and relocate them if necessary. This slows processing in a buffer with a large number of markers. For this reason, it is a good idea to make a marker point nowhere if you are sure you don't need it any more. Unreferenced markers are garbage collected eventually, but until then will continue to use time if they do point somewhere.

Because it is common to perform arithmetic operations on a marker position, most of the arithmetic operations (including + and -) accept markers as arguments. In such cases, the marker stands for its current position.

Here are examples of creating markers, setting markers, and moving point to markers:
;; Make a new marker that initially does not point anywhere:
(setq m1 (make-marker))
     => #<marker in no buffer>

;; Set m1 to point between the 99th and 100th characters
;;   in the current buffer:
(set-marker m1 100)
     => #<marker at 100 in markers.texi>

;; Now insert one character at the beginning of the buffer:
(goto-char (point-min))
     => 1
(insert "Q")
     => nil

;; m1 is updated appropriately.
m1
     => #<marker at 101 in markers.texi>

;; Two markers that point to the same position
;;   are not eq, but they are equal.
(setq m2 (copy-marker m1))
     => #<marker at 101 in markers.texi>
(eq m1 m2)
     => nil
(equal m1 m2)
     => t

;; When you are finished using a marker, make it point nowhere.
(set-marker m1 nil)
     => #<marker in no buffer>
Predicates on Markers

You can test an object to see whether it is a marker, or whether it is either an integer or a marker. The latter test is useful in connection with the arithmetic functions that work with both markers and integers.

Function: markerp object
This function returns t if object is a marker, nil otherwise. Note that integers are not markers, even though many functions will accept either a marker or an integer.

Function: integer-or-marker-p object
This function returns t if object is an integer or a marker, nil otherwise.

Function: number-or-marker-p object
This function returns t if object is a number (either integer or floating point) or a marker, nil otherwise.

Functions That Create Markers

When you create a new marker, you can make it point nowhere, or point to the present position of point, or to the beginning or end of the accessible portion of the buffer, or to the same place as another given marker.

Function: make-marker
This function returns a newly created marker that does not point anywhere.
(make-marker)
     => #<marker in no buffer>
Function: point-marker
This function returns a new marker that points to the present position of point in the current buffer. See section Point. For an example, see copy-marker, below.

Function: point-min-marker
This function returns a new marker that points to the beginning of the accessible portion of the buffer. This will be the beginning of the buffer unless narrowing is in effect. See section Narrowing.

Function: point-max-marker
This function returns a new marker that points to the end of the accessible portion of the buffer. This will be the end of the buffer unless narrowing is in effect. See section Narrowing.

Here are examples of this function and point-min-marker, shown in a buffer containing a version of the source file for the text of this chapter.
(point-min-marker)
     => #<marker at 1 in markers.texi>
(point-max-marker)
     => #<marker at 15573 in markers.texi>

(narrow-to-region 100 200)
     => nil
(point-min-marker)
     => #<marker at 100 in markers.texi>
(point-max-marker)
     => #<marker at 200 in markers.texi>
Function: copy-marker marker-or-integer insertion-type
If passed a marker as its argument, copy-marker returns a new marker that points to the same place and the same buffer as does marker-or-integer. If passed an integer as its argument, copy-marker returns a new marker that points to position marker-or-integer in the current buffer.

The new marker's insertion type is specified by the argument insertion-type. See section Marker Insertion Types.

If passed an integer argument less than 1, copy-marker returns a new marker that points to the beginning of the current buffer. If passed an integer argument greater than the length of the buffer, copy-marker returns a new marker that points to the end of the buffer.
(copy-marker 0)
     => #<marker at 1 in markers.texi>

(copy-marker 20000)
     => #<marker at 7572 in markers.texi>
An error is signaled if marker is neither a marker nor an integer.

Two distinct markers are considered equal (even though not eq) to each other if they have the same position and buffer, or if they both point nowhere.
(setq p (point-marker))
     => #<marker at 2139 in markers.texi>

(setq q (copy-marker p))
     => #<marker at 2139 in markers.texi>

(eq p q)
     => nil

(equal p q)
     => t
Information from Markers

This section describes the functions for accessing the components of a marker object.

Function: marker-position marker
This function returns the position that marker points to, or nil if it points nowhere.

Function: marker-buffer marker
This function returns the buffer that marker points into, or nil if it points nowhere.
(setq m (make-marker))
     => #<marker in no buffer>
(marker-position m)
     => nil
(marker-buffer m)
     => nil

(set-marker m 3770 (current-buffer))
     => #<marker at 3770 in markers.texi>
(marker-buffer m)
     => #<buffer markers.texi>
(marker-position m)
     => 3770
Marker Insertion Types

When you insert text directly at the place where a marker points, there are two possible ways to relocate that marker: it can point before the inserted text, or point after it. You can specify which one a given marker should do by setting its insertion type. Note that use of insert-before-markers ignores markers' insertion types, always relocating a marker to point after the inserted text.

Function: set-marker-insertion-type marker type
This function sets the insertion type of marker marker to type. If type is t, marker will advance when text is inserted at its position. If type is nil, marker does not advance when text is inserted there.

Function: marker-insertion-type marker
This function reports the current insertion type of marker.

Moving Marker Positions

This section describes how to change the position of an existing marker. When you do this, be sure you know whether the marker is used outside of your program, and, if so, what effects will result from moving it--otherwise, confusing things may happen in other parts of Emacs.

Function: set-marker marker position &optional buffer
This function moves marker to position in buffer. If buffer is not provided, it defaults to the current buffer.

If position is less than 1, set-marker moves marker to the beginning of the buffer. If position is greater than the size of the buffer, set-marker moves marker to the end of the buffer. If position is nil or a marker that points nowhere, then marker is set to point nowhere.

The value returned is marker.
(setq m (point-marker))
     => #<marker at 4714 in markers.texi>
(set-marker m 55)
     => #<marker at 55 in markers.texi>
(setq b (get-buffer "foo"))
     => #<buffer foo>
(set-marker m 0 b)
     => #<marker at 1 in foo>
Function: move-marker marker position &optional buffer
This is another name for set-marker.

The Mark

One special marker in each buffer is designated the mark. It records a position for the user for the sake of commands such as kill-region and indent-rigidly. Lisp programs should set the mark only to values that have a potential use to the user, and never for their own internal purposes. For example, the replace-regexp command sets the mark to the value of point before doing any replacements, because this enables the user to move back there conveniently after the replace is finished.

Many commands are designed so that when called interactively they operate on the text between point and the mark. If you are writing such a command, don't examine the mark directly; instead, use interactive with the `r' specification. This provides the values of point and the mark as arguments to the command in an interactive call, but permits other Lisp programs to specify arguments explicitly. See section Code Characters for interactive.

Each buffer has its own value of the mark that is independent of the value of the mark in other buffers. When a buffer is created, the mark exists but does not point anywhere. We consider this state as "the absence of a mark in that buffer."

Once the mark "exists" in a buffer, it normally never ceases to exist. However, it may become inactive, if Transient Mark mode is enabled. The variable mark-active, which is always buffer-local in all buffers, indicates whether the mark is active: non-nil means yes. A command can request deactivation of the mark upon return to the editor command loop by setting deactivate-mark to a non-nil value (but this causes deactivation only if Transient Mark mode is enabled).

The main motivation for using Transient Mark mode is that this mode also enables highlighting of the region when the mark is active. See section Emacs Display.

In addition to the mark, each buffer has a mark ring which is a list of markers containing previous values of the mark. When editing commands change the mark, they should normally save the old value of the mark on the mark ring. The variable mark-ring-max specifies the maximum number of entries in the mark ring; once the list becomes this long, adding a new element deletes the last element.

Function: mark &optional force
This function returns the current buffer's mark position as an integer.

If the mark is inactive, mark normally signals an error. However, if force is non-nil, then mark returns the mark position anyway--or nil, if the mark is not yet set for this buffer.

Function: mark-marker
This function returns the current buffer's mark. This is the very marker that records the mark location inside Emacs, not a copy. Therefore, changing this marker's position will directly affect the position of the mark. Don't do it unless that is the effect you want.
(setq m (mark-marker))
     => #<marker at 3420 in markers.texi>
(set-marker m 100)
     => #<marker at 100 in markers.texi>
(mark-marker)
     => #<marker at 100 in markers.texi>
Like any marker, this marker can be set to point at any buffer you like. We don't recommend that you make it point at any buffer other than the one of which it is the mark. If you do, it will yield perfectly consistent, but rather odd, results.

Function: set-mark position
This function sets the mark to position, and activates the mark. The old value of the mark is not pushed onto the mark ring.

Please note: Use this function only if you want the user to see that the mark has moved, and you want the previous mark position to be lost. Normally, when a new mark is set, the old one should go on the mark-ring. For this reason, most applications should use push-mark and pop-mark, not set-mark.

Novice Emacs Lisp programmers often try to use the mark for the wrong purposes. The mark saves a location for the user's convenience. An editing command should not alter the mark unless altering the mark is part of the user-level functionality of the command. (And, in that case, this effect should be documented.) To remember a location for internal use in the Lisp program, store it in a Lisp variable. For example:
(let ((beg (point)))
  (forward-line 1)
  (delete-region beg (point))).
Function: push-mark &optional position nomsg activate
This function sets the current buffer's mark to position, and pushes a copy of the previous mark onto mark-ring. If position is nil, then the value of point is used. push-mark returns nil.

The function push-mark normally does not activate the mark. To do that, specify t for the argument activate.

A `Mark set' message is displayed unless nomsg is non-nil.

Function: pop-mark
This function pops off the top element of mark-ring and makes that mark become the buffer's actual mark. This does not move point in the buffer, and it does nothing if mark-ring is empty. It deactivates the mark.

The return value is not meaningful.

User Option: transient-mark-mode
This variable if non-nil enables Transient Mark mode, in which every buffer-modifying primitive sets deactivate-mark. The consequence of this is that commands that modify the buffer normally make the mark inactive.

User Option: mark-even-if-inactive
If this is non-nil, Lisp programs and the Emacs user can use the mark even when it is inactive. This option affects the behavior of Transient Mark mode. When the option is non-nil, deactivation of the mark turns off region highlighting, but commands that use the mark behave as if the mark were still active.

Variable: deactivate-mark
If an editor command sets this variable non-nil, then the editor command loop deactivates the mark after the command returns (if Transient Mark mode is enabled). All the primitives that change the buffer set deactivate-mark, to deactivate the mark when the command is finished.

Function: deactivate-mark
This function deactivates the mark, if Transient Mark mode is enabled. Otherwise it does nothing.

Variable: mark-active
The mark is active when this variable is non-nil. This variable is always buffer-local in each buffer.

Variable: activate-mark-hook

Variable: deactivate-mark-hook
These normal hooks are run, respectively, when the mark becomes active and when it becomes inactive. The hook activate-mark-hook is also run at the end of a command if the mark is active and it is possible that the region may have changed.

Variable: mark-ring
The value of this buffer-local variable is the list of saved former marks of the current buffer, most recent first.
mark-ring
=> (#<marker at 11050 in markers.texi>
    #<marker at 10832 in markers.texi>
    ...)
User Option: mark-ring-max
The value of this variable is the maximum size of mark-ring. If more marks than this are pushed onto the mark-ring, push-mark discards an old mark when it adds a new one.

The Region

The text between point and the mark is known as the region. Various functions operate on text delimited by point and the mark, but only those functions specifically related to the region itself are described here.

Function: region-beginning
This function returns the position of the beginning of the region (as an integer). This is the position of either point or the mark, whichever is smaller.

If the mark does not point anywhere, an error is signaled.

Function: region-end
This function returns the position of the end of the region (as an integer). This is the position of either point or the mark, whichever is larger.

If the mark does not point anywhere, an error is signaled.

Few programs need to use the region-beginning and region-end functions. A command designed to operate on a region should normally use interactive with the `r' specification to find the beginning and end of the region. This lets other Lisp programs specify the bounds explicitly as arguments. (See section Code Characters for interactive.)
Text

This chapter describes the functions that deal with the text in a buffer. Most examine, insert, or delete text in the current buffer, often in the vicinity of point. Many are interactive. All the functions that change the text provide for undoing the changes (see section Undo).

Many text-related functions operate on a region of text defined by two buffer positions passed in arguments named start and end. These arguments should be either markers (see section Markers) or numeric character positions (see section Positions). The order of these arguments does not matter; it is all right for start to be the end of the region and end the beginning. For example, (delete-region 1 10) and (delete-region 10 1) are equivalent. An args-out-of-range error is signaled if either start or end is outside the accessible portion of the buffer. In an interactive call, point and the mark are used for these arguments.

Throughout this chapter, "text" refers to the characters in the buffer, together with their properties (when relevant).

Examining Text Near Point

Many functions are provided to look at the characters around point. Several simple functions are described here. See also looking-at in section Regular Expression Searching.

Function: char-after &optional position
This function returns the character in the current buffer at (i.e., immediately after) position position. If position is out of range for this purpose, either before the beginning of the buffer, or at or beyond the end, then the value is nil. The default for position is point.

In the following example, assume that the first character in the buffer is `@':
(char-to-string (char-after 1))
     => "@"
Function: char-before &optional position
This function returns the character in the current buffer immediately before position position. If position is out of range for this purpose, either before the beginning of the buffer, or at or beyond the end, then the value is nil. The default for position is point.

Function: following-char
This function returns the character following point in the current buffer. This is similar to (char-after (point)). However, if point is at the end of the buffer, then following-char returns 0.

Remember that point is always between characters, and the terminal cursor normally appears over the character following point. Therefore, the character returned by following-char is the character the cursor is over.

In this example, point is between the `a' and the `c'.
---------- Buffer: foo ----------
Gentlemen may cry ``Pea-!-ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(char-to-string (preceding-char))
     => "a"
(char-to-string (following-char))
     => "c"
Function: preceding-char
This function returns the character preceding point in the current buffer. See above, under following-char, for an example. If point is at the beginning of the buffer, preceding-char returns 0.

Function: bobp
This function returns t if point is at the beginning of the buffer. If narrowing is in effect, this means the beginning of the accessible portion of the text. See also point-min in section Point.

Function: eobp
This function returns t if point is at the end of the buffer. If narrowing is in effect, this means the end of accessible portion of the text. See also point-max in See section Point.

Function: bolp
This function returns t if point is at the beginning of a line. See section Motion by Text Lines. The beginning of the buffer (or of its accessible portion) always counts as the beginning of a line.

Function: eolp
This function returns t if point is at the end of a line. The end of the buffer (or of its accessible portion) is always considered the end of a line.

Examining Buffer Contents

This section describes two functions that allow a Lisp program to convert any portion of the text in the buffer into a string.

Function: buffer-substring start end
This function returns a string containing a copy of the text of the region defined by positions start and end in the current buffer. If the arguments are not positions in the accessible portion of the buffer, buffer-substring signals an args-out-of-range error.

It is not necessary for start to be less than end; the arguments can be given in either order. But most often the smaller argument is written first.

If the text being copied has any text properties, these are copied into the string along with the characters they belong to. See section Text Properties. However, overlays (see section Overlays) in the buffer and their properties are ignored, not copied.
---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-substring 1 10)
=> "This is t"
(buffer-substring (point-max) 10)
=> "he contents of buffer foo
"
Function: buffer-substring-no-properties start end
This is like buffer-substring, except that it does not copy text properties, just the characters themselves. See section Text Properties.

Function: buffer-string
This function returns the contents of the entire accessible portion of the current buffer as a string. It is equivalent to
(buffer-substring (point-min) (point-max))
---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-string)
     => "This is the contents of buffer foo
"
Function: thing-at-point thing
Return the thing around or next to point, as a string.

The argument thing is a symbol which specifies a kind of syntactic entity. Possibilities include symbol, list, sexp, defun, filename, url, word, sentence, whitespace, line, page, and others.
---------- Buffer: foo ----------
Gentlemen may cry ``Pea-!-ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(thing-at-point 'word)
     => "Peace"
(thing-at-point 'line)
     => "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
     => nil
Comparing Text

This function lets you compare portions of the text in a buffer, without copying them into strings first.

Function: compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
This function lets you compare two substrings of the same buffer or two different buffers. The first three arguments specify one substring, giving a buffer and two positions within the buffer. The last three arguments specify the other substring in the same way. You can use nil for buffer1, buffer2, or both to stand for the current buffer.

The value is negative if the first substring is less, positive if the first is greater, and zero if they are equal. The absolute value of the result is one plus the index of the first differing characters within the substrings.

This function ignores case when comparing characters if case-fold-search is non-nil. It always ignores text properties.

Suppose the current buffer contains the text `foobarbar haha!rara!'; then in this example the two substrings are `rbar ' and `rara!'. The value is 2 because the first substring is greater at the second character.
(compare-buffer-substring nil 6 11 nil 16 21)
     => 2
Inserting Text

Insertion means adding new text to a buffer. The inserted text goes at point--between the character before point and the character after point. Some insertion functions leave point before the inserted text, while other functions leave it after. We call the former insertion after point and the latter insertion before point.

Insertion relocates markers that point at positions after the insertion point, so that they stay with the surrounding text (see section Markers). When a marker points at the place of insertion, insertion may or may not relocate the marker, depending on the marker's insertion type (see section Marker Insertion Types). Certain special functions such as insert-before-markers relocate all such markers to point after the inserted text, regardless of the markers' insertion type.

Insertion functions signal an error if the current buffer is read-only.

These functions copy text characters from strings and buffers along with their properties. The inserted characters have exactly the same properties as the characters they were copied from. By contrast, characters specified as separate arguments, not part of a string or buffer, inherit their text properties from the neighboring text.

The insertion functions convert text from unibyte to multibyte in order to insert in a multibyte buffer, and vice versa--if the text comes from a string or from a buffer. However, they do not convert unibyte character codes 128 through 255 to multibyte characters, not even if the current buffer is a multibyte buffer. See section Converting Text Representations.

Function: insert &rest args
This function inserts the strings and/or characters args into the current buffer, at point, moving point forward. In other words, it inserts the text before point. An error is signaled unless all args are either strings or characters. The value is nil.

Function: insert-before-markers &rest args
This function inserts the strings and/or characters args into the current buffer, at point, moving point forward. An error is signaled unless all args are either strings or characters. The value is nil.

This function is unlike the other insertion functions in that it relocates markers initially pointing at the insertion point, to point after the inserted text. If an overlay begins the insertion point, the inserted text falls outside the overlay; if a nonempty overlay ends at the insertion point, the inserted text falls inside that overlay.

Function: insert-char character &optional count inherit
This function inserts count instances of character into the current buffer before point. The argument count should be a number (nil means 1), and character must be a character. The value is nil.

This function does not convert unibyte character codes 128 through 255 to multibyte characters, not even if the current buffer is a multibyte buffer. See section Converting Text Representations.

If inherit is non-nil, then the inserted characters inherit sticky text properties from the two characters before and after the insertion point. See section Stickiness of Text Properties.

Function: insert-buffer-substring from-buffer-or-name &optional start end
This function inserts a portion of buffer from-buffer-or-name (which must already exist) into the current buffer before point. The text inserted is the region from start and end. (These arguments default to the beginning and end of the accessible portion of that buffer.) This function returns nil.

In this example, the form is executed with buffer `bar' as the current buffer. We assume that buffer `bar' is initially empty.
---------- Buffer: foo ----------
We hold these truths to be self-evident, that all
---------- Buffer: foo ----------

(insert-buffer-substring "foo" 1 20)
     => nil

---------- Buffer: bar ----------
We hold these truth-!-
---------- Buffer: bar ----------
See section Stickiness of Text Properties, for other insertion functions that inherit text properties from the nearby text in addition to inserting it. Whitespace inserted by indentation functions also inherits text properties.

User-Level Insertion Commands

This section describes higher-level commands for inserting text, commands intended primarily for the user but useful also in Lisp programs.

Command: insert-buffer from-buffer-or-name
This command inserts the entire contents of from-buffer-or-name (which must exist) into the current buffer after point. It leaves the mark after the inserted text. The value is nil.

Command: self-insert-command count
This command inserts the last character typed; it does so count times, before point, and returns nil. Most printing characters are bound to this command. In routine use, self-insert-command is the most frequently called function in Emacs, but programs rarely use it except to install it on a keymap.

In an interactive call, count is the numeric prefix argument.

This command calls auto-fill-function whenever that is non-nil and the character inserted is a space or a newline (see section Auto Filling).

This command performs abbrev expansion if Abbrev mode is enabled and the inserted character does not have word-constituent syntax. (See section Abbrevs And Abbrev Expansion, and section Table of Syntax Classes.)

This is also responsible for calling blink-paren-function when the inserted character has close parenthesis syntax (see section Blinking Parentheses).

Command: newline &optional number-of-newlines
This command inserts newlines into the current buffer before point. If number-of-newlines is supplied, that many newline characters are inserted.

This function calls auto-fill-function if the current column number is greater than the value of fill-column and number-of-newlines is nil. Typically what auto-fill-function does is insert a newline; thus, the overall result in this case is to insert two newlines at different places: one at point, and another earlier in the line. newline does not auto-fill if number-of-newlines is non-nil.

This command indents to the left margin if that is not zero. See section Margins for Filling.

The value returned is nil. In an interactive call, count is the numeric prefix argument.

Command: split-line
This command splits the current line, moving the portion of the line after point down vertically so that it is on the next line directly below where it was before. Whitespace is inserted as needed at the beginning of the lower line, using the indent-to function. split-line returns the position of point.

Programs hardly ever use this function.

Variable: overwrite-mode
This variable controls whether overwrite mode is in effect. The value should be overwrite-mode-textual, overwrite-mode-binary, or nil. overwrite-mode-textual specifies textual overwrite mode (treats newlines and tabs specially), and overwrite-mode-binary specifies binary overwrite mode (treats newlines and tabs like any other characters).

Deleting Text

Deletion means removing part of the text in a buffer, without saving it in the kill ring (see section The Kill Ring). Deleted text can't be yanked, but can be reinserted using the undo mechanism (see section Undo). Some deletion functions do save text in the kill ring in some special cases.

All of the deletion functions operate on the current buffer, and all return a value of nil.

Command: erase-buffer
This function deletes the entire text of the current buffer, leaving it empty. If the buffer is read-only, it signals a buffer-read-only error. Otherwise, it deletes the text without asking for any confirmation. It returns nil.

Normally, deleting a large amount of text from a buffer inhibits further auto-saving of that buffer "because it has shrunk". However, erase-buffer does not do this, the idea being that the future text is not really related to the former text, and its size should not be compared with that of the former text.

Command: delete-region start end
This command deletes the text in the current buffer in the region defined by start and end. The value is nil. If point was inside the deleted region, its value afterward is start. Otherwise, point relocates with the surrounding text, as markers do.

Command: delete-char count &optional killp
This command deletes count characters directly after point, or before point if count is negative. If killp is non-nil, then it saves the deleted characters in the kill ring.

In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.

The value returned is always nil.

Command: delete-backward-char count &optional killp
This command deletes count characters directly before point, or after point if count is negative. If killp is non-nil, then it saves the deleted characters in the kill ring.

In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.

The value returned is always nil.

Command: backward-delete-char-untabify count &optional killp
This command deletes count characters backward, changing tabs into spaces. When the next character to be deleted is a tab, it is first replaced with the proper number of spaces to preserve alignment and then one of those spaces is deleted instead of the tab. If killp is non-nil, then the command saves the deleted characters in the kill ring.

Conversion of tabs to spaces happens only if count is positive. If it is negative, exactly -count characters after point are deleted.

In an interactive call, count is the numeric prefix argument, and killp is the unprocessed prefix argument. Therefore, if a prefix argument is supplied, the text is saved in the kill ring. If no prefix argument is supplied, then one character is deleted, but not saved in the kill ring.

The value returned is always nil.

User Option: backward-delete-char-untabify-method
This option specifies how backward-delete-char-untabify should deal with whitespace. Possible values include untabify, the default, meaning convert a tab to many spaces and delete one; hungry, meaning delete all the whitespace characters before point with one command, and nil, meaning do nothing special for whitespace characters.

User-Level Deletion Commands

This section describes higher-level commands for deleting text, commands intended primarily for the user but useful also in Lisp programs.

Command: delete-horizontal-space
This function deletes all spaces and tabs around point. It returns nil.

In the following examples, we call delete-horizontal-space four times, once on each line, with point between the second and third characters on the line each time.
---------- Buffer: foo ----------
I -!-thought
I -!-     thought
We-!- thought
Yo-!-u thought
---------- Buffer: foo ----------

(delete-horizontal-space)   ; Four times.
     => nil

---------- Buffer: foo ----------
Ithought
Ithought
Wethought
You thought
---------- Buffer: foo ----------
Command: delete-indentation &optional join-following-p
This function joins the line point is on to the previous line, deleting any whitespace at the join and in some cases replacing it with one space. If join-following-p is non-nil, delete-indentation joins this line to the following line instead. The function returns nil.

If there is a fill prefix, and the second of the lines being joined starts with the prefix, then delete-indentation deletes the fill prefix before joining the lines. See section Margins for Filling.

In the example below, point is located on the line starting `events', and it makes no difference if there are trailing spaces in the preceding line.
---------- Buffer: foo ----------
When in the course of human
-!-    events, it becomes necessary
---------- Buffer: foo ----------

(delete-indentation)
     => nil

---------- Buffer: foo ----------
When in the course of human-!- events, it becomes necessary
---------- Buffer: foo ----------
After the lines are joined, the function fixup-whitespace is responsible for deciding whether to leave a space at the junction.

Function: fixup-whitespace
This function replaces all the whitespace surrounding point with either one space or no space, according to the context. It returns nil.

At the beginning or end of a line, the appropriate amount of space is none. Before a character with close parenthesis syntax, or after a character with open parenthesis or expression-prefix syntax, no space is also appropriate. Otherwise, one space is appropriate. See section Table of Syntax Classes.

In the example below, fixup-whitespace is called the first time with point before the word `spaces' in the first line. For the second invocation, point is directly after the `('.
---------- Buffer: foo ----------
This has too many     -!-spaces
This has too many spaces at the start of (-!-   this list)
---------- Buffer: foo ----------

(fixup-whitespace)
     => nil
(fixup-whitespace)
     => nil

---------- Buffer: foo ----------
This has too many spaces
This has too many spaces at the start of (this list)
---------- Buffer: foo ----------
Command: just-one-space
This command replaces any spaces and tabs around point with a single space. It returns nil.

Command: delete-blank-lines
This function deletes blank lines surrounding point. If point is on a blank line with one or more blank lines before or after it, then all but one of them are deleted. If point is on an isolated blank line, then it is deleted. If point is on a nonblank line, the command deletes all blank lines following it.

A blank line is defined as a line containing only tabs and spaces.

delete-blank-lines returns nil.

The Kill Ring

Kill functions delete text like the deletion functions, but save it so that the user can reinsert it by yanking. Most of these functions have `kill-' in their name. By contrast, the functions whose names start with `delete-' normally do not save text for yanking (though they can still be undone); these are "deletion" functions.

Most of the kill commands are primarily for interactive use, and are not described here. What we do describe are the functions provided for use in writing such commands. You can use these functions to write commands for killing text. When you need to delete text for internal purposes within a Lisp function, you should normally use deletion functions, so as not to disturb the kill ring contents. See section Deleting Text.

Killed text is saved for later yanking in the kill ring. This is a list that holds a number of recent kills, not just the last text kill. We call this a "ring" because yanking treats it as having elements in a cyclic order. The list is kept in the variable kill-ring, and can be operated on with the usual functions for lists; there are also specialized functions, described in this section, that treat it as a ring.

Some people think this use of the word "kill" is unfortunate, since it refers to operations that specifically do not destroy the entities "killed". This is in sharp contrast to ordinary life, in which death is permanent and "killed" entities do not come back to life. Therefore, other metaphors have been proposed. For example, the term "cut ring" makes sense to people who, in pre-computer days, used scissors and paste to cut up and rearrange manuscripts. However, it would be difficult to change the terminology now.

Kill Ring Concepts

The kill ring records killed text as strings in a list, most recent first. A short kill ring, for example, might look like this:
("some text" "a different piece of text" "even older text")
When the list reaches kill-ring-max entries in length, adding a new entry automatically deletes the last entry.

When kill commands are interwoven with other commands, each kill command makes a new entry in the kill ring. Multiple kill commands in succession build up a single kill-ring entry, which would be yanked as a unit; the second and subsequent consecutive kill commands add text to the entry made by the first one.

For yanking, one entry in the kill ring is designated the "front" of the ring. Some yank commands "rotate" the ring by designating a different element as the "front." But this virtual rotation doesn't change the list itself--the most recent entry always comes first in the list.

Functions for Killing

kill-region is the usual subroutine for killing text. Any command that calls this function is a "kill command" (and should probably have `kill' in its name). kill-region puts the newly killed text in a new element at the beginning of the kill ring or adds it to the most recent element. It determines automatically (using last-command) whether the previous command was a kill command, and if so appends the killed text to the most recent entry.

Command: kill-region start end
This function kills the text in the region defined by start and end. The text is deleted but saved in the kill ring, along with its text properties. The value is always nil.

In an interactive call, start and end are point and the mark.

If the buffer is read-only, kill-region modifies the kill ring just the same, then signals an error without modifying the buffer. This is convenient because it lets the user use all the kill commands to copy text into the kill ring from a read-only buffer.

User Option: kill-read-only-ok
If this option is non-nil, kill-region does not get an error if the buffer is read-only. Instead, it simply returns, updating the kill ring but not changing the buffer.

Command: copy-region-as-kill start end
This command saves the region defined by start and end on the kill ring (including text properties), but does not delete the text from the buffer. It returns nil. It also indicates the extent of the text copied by moving the cursor momentarily, or by displaying a message in the echo area.

The command does not set this-command to kill-region, so a subsequent kill command does not append to the same kill ring entry.

Don't call copy-region-as-kill in Lisp programs unless you aim to support Emacs 18. For newer Emacs versions, it is better to use kill-new or kill-append instead. See section Low-Level Kill Ring.

Functions for Yanking

Yanking means reinserting an entry of previously killed text from the kill ring. The text properties are copied too.

Command: yank &optional arg
This command inserts before point the text in the first entry in the kill ring. It positions the mark at the beginning of that text, and point at the end.

If arg is a list (which occurs interactively when the user types C-u with no digits), then yank inserts the text as described above, but puts point before the yanked text and puts the mark after it.

If arg is a number, then yank inserts the argth most recently killed text--the argth element of the kill ring list.

yank does not alter the contents of the kill ring or rotate it. It returns nil.

Command: yank-pop arg
This command replaces the just-yanked entry from the kill ring with a different entry from the kill ring.

This is allowed only immediately after a yank or another yank-pop. At such a time, the region contains text that was just inserted by yanking. yank-pop deletes that text and inserts in its place a different piece of killed text. It does not add the deleted text to the kill ring, since it is already in the kill ring somewhere.

If arg is nil, then the replacement text is the previous element of the kill ring. If arg is numeric, the replacement is the argth previous kill. If arg is negative, a more recent kill is the replacement.

The sequence of kills in the kill ring wraps around, so that after the oldest one comes the newest one, and before the newest one goes the oldest.

The return value is always nil.

Low-Level Kill Ring

These functions and variables provide access to the kill ring at a lower level, but still convenient for use in Lisp programs, because they take care of interaction with window system selections (see section Window System Selections).

Function: current-kill n &optional do-not-move
The function current-kill rotates the yanking pointer, which designates the "front" of the kill ring, by n places (from newer kills to older ones), and returns the text at that place in the ring.

If the optional second argument do-not-move is non-nil, then current-kill doesn't alter the yanking pointer; it just returns the nth kill, counting from the current yanking pointer.

If n is zero, indicating a request for the latest kill, current-kill calls the value of interprogram-paste-function (documented below) before consulting the kill ring.

Function: kill-new string
This function puts the text string into the kill ring as a new entry at the front of the ring. It discards the oldest entry if appropriate. It also invokes the value of interprogram-cut-function (see below).

Function: kill-append string before-p
This function appends the text string to the first entry in the kill ring. Normally string goes at the end of the entry, but if before-p is non-nil, it goes at the beginning. This function also invokes the value of interprogram-cut-function (see below).

Variable: interprogram-paste-function
This variable provides a way of transferring killed text from other programs, when you are using a window system. Its value should be nil or a function of no arguments.

If the value is a function, current-kill calls it to get the "most recent kill". If the function returns a non-nil value, then that value is used as the "most recent kill". If it returns nil, then the first element of kill-ring is used.

The normal use of this hook is to get the window system's primary selection as the most recent kill, even if the selection belongs to another application. See section Window System Selections.

Variable: interprogram-cut-function
This variable provides a way of communicating killed text to other programs, when you are using a window system. Its value should be nil or a function of one argument.

If the value is a function, kill-new and kill-append call it with the new first element of the kill ring as an argument.

The normal use of this hook is to set the window system's primary selection from the newly killed text. See section Window System Selections.

Internals of the Kill Ring

The variable kill-ring holds the kill ring contents, in the form of a list of strings. The most recent kill is always at the front of the list.

The kill-ring-yank-pointer variable points to a link in the kill ring list, whose CAR is the text to yank next. We say it identifies the "front" of the ring. Moving kill-ring-yank-pointer to a different link is called rotating the kill ring. We call the kill ring a "ring" because the functions that move the yank pointer wrap around from the end of the list to the beginning, or vice-versa. Rotation of the kill ring is virtual; it does not change the value of kill-ring.

Both kill-ring and kill-ring-yank-pointer are Lisp variables whose values are normally lists. The word "pointer" in the name of the kill-ring-yank-pointer indicates that the variable's purpose is to identify one element of the list for use by the next yank command.

The value of kill-ring-yank-pointer is always eq to one of the links in the kill ring list. The element it identifies is the CAR of that link. Kill commands, which change the kill ring, also set this variable to the value of kill-ring. The effect is to rotate the ring so that the newly killed text is at the front.

Here is a diagram that shows the variable kill-ring-yank-pointer pointing to the second entry in the kill ring ("some text" "a different piece of text" "yet older text").
kill-ring                  ---- kill-ring-yank-pointer
  |                       |
  |                       v
  |     --- ---          --- ---      --- ---
   --> |   |   |------> |   |   |--> |   |   |--> nil
        --- ---          --- ---      --- ---
         |                |            |
         |                |            |
         |                |             -->"yet older text"
         |                |
         |                 --> "a different piece of text"
         |
          --> "some text"
This state of affairs might occur after C-y (yank) immediately followed by M-y (yank-pop).

Variable: kill-ring
This variable holds the list of killed text sequences, most recently killed first.

Variable: kill-ring-yank-pointer
This variable's value indicates which element of the kill ring is at the "front" of the ring for yanking. More precisely, the value is a tail of the value of kill-ring, and its CAR is the kill string that C-y should yank.

User Option: kill-ring-max
The value of this variable is the maximum length to which the kill ring can grow, before elements are thrown away at the end. The default value for kill-ring-max is 30.

Undo

Most buffers have an undo list, which records all changes made to the buffer's text so that they can be undone. (The buffers that don't have one are usually special-purpose buffers for which Emacs assumes that undoing is not useful.) All the primitives that modify the text in the buffer automatically add elements to the front of the undo list, which is in the variable buffer-undo-list.

Variable: buffer-undo-list
This variable's value is the undo list of the current buffer. A value of t disables the recording of undo information.

Here are the kinds of elements an undo list can have:

position
This kind of element records a previous value of point; undoing this element moves point to position. Ordinary cursor motion does not make any sort of undo record, but deletion operations use these entries to record where point was before the command.
(beg . end)
This kind of element indicates how to delete text that was inserted. Upon insertion, the text occupied the range beg--end in the buffer.
(text . position)
This kind of element indicates how to reinsert text that was deleted. The deleted text itself is the string text. The place to reinsert it is (abs position).
(t high . low)
This kind of element indicates that an unmodified buffer became modified. The elements high and low are two integers, each recording 16 bits of the visited file's modification time as of when it was previously visited or saved. primitive-undo uses those values to determine whether to mark the buffer as unmodified once again; it does so only if the file's modification time matches those numbers.
(nil property value beg . end)
This kind of element records a change in a text property. Here's how you might undo the change:
(put-text-property beg end property value)
(marker . adjustment)
This kind of element records the fact that the marker marker was relocated due to deletion of surrounding text, and that it moved adjustment character positions. Undoing this element moves marker - adjustment characters.
nil
This element is a boundary. The elements between two boundaries are called a change group; normally, each change group corresponds to one keyboard command, and undo commands normally undo an entire group as a unit.

Function: undo-boundary
This function places a boundary element in the undo list. The undo command stops at such a boundary, and successive undo commands undo to earlier and earlier boundaries. This function returns nil.

The editor command loop automatically creates an undo boundary before each key sequence is executed. Thus, each undo normally undoes the effects of one command. Self-inserting input characters are an exception. The command loop makes a boundary for the first such character; the next 19 consecutive self-inserting input characters do not make boundaries, and then the 20th does, and so on as long as self-inserting characters continue.

All buffer modifications add a boundary whenever the previous undoable change was made in some other buffer. This is to ensure that each command makes a boundary in each buffer where it makes changes.

Calling this function explicitly is useful for splitting the effects of a command into more than one unit. For example, query-replace calls undo-boundary after each replacement, so that the user can undo individual replacements one by one.

Function: primitive-undo count list
This is the basic function for undoing elements of an undo list. It undoes the first count elements of list, returning the rest of list. You could write this function in Lisp, but it is convenient to have it in C.

primitive-undo adds elements to the buffer's undo list when it changes the buffer. Undo commands avoid confusion by saving the undo list value at the beginning of a sequence of undo operations. Then the undo operations use and update the saved value. The new elements added by undoing are not part of this saved value, so they don't interfere with continuing to undo.

Maintaining Undo Lists

This section describes how to enable and disable undo information for a given buffer. It also explains how the undo list is truncated automatically so it doesn't get too big.

Recording of undo information in a newly created buffer is normally enabled to start with; but if the buffer name starts with a space, the undo recording is initially disabled. You can explicitly enable or disable undo recording with the following two functions, or by setting buffer-undo-list yourself.

Command: buffer-enable-undo &optional buffer-or-name
This command enables recording undo information for buffer buffer-or-name, so that subsequent changes can be undone. If no argument is supplied, then the current buffer is used. This function does nothing if undo recording is already enabled in the buffer. It returns nil.

In an interactive call, buffer-or-name is the current buffer. You cannot specify any other buffer.

Command: buffer-disable-undo &optional buffer

Command: buffer-flush-undo &optional buffer
This function discards the undo list of buffer, and disables further recording of undo information. As a result, it is no longer possible to undo either previous changes or any subsequent changes. If the undo list of buffer is already disabled, this function has no effect.

This function returns nil.

The name buffer-flush-undo is not considered obsolete, but the preferred name is buffer-disable-undo.

As editing continues, undo lists get longer and longer. To prevent them from using up all available memory space, garbage collection trims them back to size limits you can set. (For this purpose, the "size" of an undo list measures the cons cells that make up the list, plus the strings of deleted text.) Two variables control the range of acceptable sizes: undo-limit and undo-strong-limit.

Variable: undo-limit
This is the soft limit for the acceptable size of an undo list. The change group at which this size is exceeded is the last one kept.

Variable: undo-strong-limit
This is the upper limit for the acceptable size of an undo list. The change group at which this size is exceeded is discarded itself (along with all older change groups). There is one exception: the very latest change group is never discarded no matter how big it is.

Filling

Filling means adjusting the lengths of lines (by moving the line breaks) so that they are nearly (but no greater than) a specified maximum width. Additionally, lines can be justified, which means inserting spaces to make the left and/or right margins line up precisely. The width is controlled by the variable fill-column. For ease of reading, lines should be no longer than 70 or so columns.

You can use Auto Fill mode (see section Auto Filling) to fill text automatically as you insert it, but changes to existing text may leave it improperly filled. Then you must fill the text explicitly.

Most of the commands in this section return values that are not meaningful. All the functions that do filling take note of the current left margin, current right margin, and current justification style (see section Margins for Filling). If the current justification style is none, the filling functions don't actually do anything.

Several of the filling functions have an argument justify. If it is non-nil, that requests some kind of justification. It can be left, right, full, or center, to request a specific style of justification. If it is t, that means to use the current justification style for this part of the text (see current-justification, below). Any other value is treated as full.

When you call the filling functions interactively, using a prefix argument implies the value full for justify.

Command: fill-paragraph justify
This command fills the paragraph at or after point. If justify is non-nil, each line is justified as well. It uses the ordinary paragraph motion commands to find paragraph boundaries. See section `Paragraphs' in The Emacs Manual.

Command: fill-region start end &optional justify nosqueeze
This command fills each of the paragraphs in the region from start to end. It justifies as well if justify is non-nil.

If nosqueeze is non-nil, that means to leave whitespace other than line breaks untouched. If to-eop is non-nil, that means to keep filling to the end of the paragraph--or the next hard newline, if use-hard-newlines is enabled (see below).

The variable paragraph-separate controls how to distinguish paragraphs. See section Standard Regular Expressions Used in Editing.

Command: fill-individual-paragraphs start end &optional justify mail-flag
This command fills each paragraph in the region according to its individual fill prefix. Thus, if the lines of a paragraph were indented with spaces, the filled paragraph will remain indented in the same fashion.

The first two arguments, start and end, are the beginning and end of the region to be filled. The third and fourth arguments, justify and mail-flag, are optional. If justify is non-nil, the paragraphs are justified as well as filled. If mail-flag is non-nil, it means the function is operating on a mail message and therefore should not fill the header lines.

Ordinarily, fill-individual-paragraphs regards each change in indentation as starting a new paragraph. If fill-individual-varying-indent is non-nil, then only separator lines separate paragraphs. That mode can handle indented paragraphs with additional indentation on the first line.

User Option: fill-individual-varying-indent
This variable alters the action of fill-individual-paragraphs as described above.

Command: fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
This command considers a region of text as a single paragraph and fills it. If the region was made up of many paragraphs, the blank lines between paragraphs are removed. This function justifies as well as filling when justify is non-nil.

In an interactive call, any prefix argument requests justification.

If nosqueeze is non-nil, that means to leave whitespace other than line breaks untouched. If squeeze-after is non-nil, it specifies a position in the region, and means don't canonicalize spaces before that position.

In Adaptive Fill mode, this command calls fill-context-prefix to choose a fill prefix by default. See section Adaptive Fill Mode.

Command: justify-current-line how eop nosqueeze
This command inserts spaces between the words of the current line so that the line ends exactly at fill-column. It returns nil.

The argument how, if non-nil specifies explicitly the style of justification. It can be left, right, full, center, or none. If it is t, that means to do follow specified justification style (see current-justification, below). nil means to do full justification.

If eop is non-nil, that means do left-justification if current-justification specifies full justification. This is used for the last line of a paragraph; even if the paragraph as a whole is fully justified, the last line should not be.

If nosqueeze is non-nil, that means do not change interior whitespace.

User Option: default-justification
This variable's value specifies the style of justification to use for text that doesn't specify a style with a text property. The possible values are left, right, full, center, or none. The default value is left.

Function: current-justification
This function returns the proper justification style to use for filling the text around point.

User Option: sentence-end-double-space
If this variable is non-nil, a period followed by just one space does not count as the end of a sentence, and the filling functions avoid breaking the line at such a place.

Variable: fill-paragraph-function
This variable provides a way for major modes to override the filling of paragraphs. If the value is non-nil, fill-paragraph calls this function to do the work. If the function returns a non-nil value, fill-paragraph assumes the job is done, and immediately returns that value.

The usual use of this feature is to fill comments in programming language modes. If the function needs to fill a paragraph in the usual way, it can do so as follows:
(let ((fill-paragraph-function nil))
  (fill-paragraph arg))
Variable: use-hard-newlines
If this variable is non-nil, the filling functions do not delete newlines that have the hard text property. These "hard newlines" act as paragraph separators.

Margins for Filling

User Option: fill-prefix
This buffer-local variable specifies a string of text that appears at the beginning of normal text lines and should be disregarded when filling them. Any line that fails to start with the fill prefix is considered the start of a paragraph; so is any line that starts with the fill prefix followed by additional whitespace. Lines that start with the fill prefix but no additional whitespace are ordinary text lines that can be filled together. The resulting filled lines also start with the fill prefix.

The fill prefix follows the left margin whitespace, if any.

User Option: fill-column
This buffer-local variable specifies the maximum width of filled lines. Its value should be an integer, which is a number of columns. All the filling, justification, and centering commands are affected by this variable, including Auto Fill mode (see section Auto Filling).

As a practical matter, if you are writing text for other people to read, you should set fill-column to no more than 70. Otherwise the line will be too long for people to read comfortably, and this can make the text seem clumsy.

Variable: default-fill-column
The value of this variable is the default value for fill-column in buffers that do not override it. This is the same as (default-value 'fill-column).

The default value for default-fill-column is 70.

Command: set-left-margin from to margin
This sets the left-margin property on the text from from to to to the value margin. If Auto Fill mode is enabled, this command also refills the region to fit the new margin.

Command: set-right-margin from to margin
This sets the right-margin property on the text from from to to to the value margin. If Auto Fill mode is enabled, this command also refills the region to fit the new margin.

Function: current-left-margin
This function returns the proper left margin value to use for filling the text around point. The value is the sum of the left-margin property of the character at the start of the current line (or zero if none), and the value of the variable left-margin.

Function: current-fill-column
This function returns the proper fill column value to use for filling the text around point. The value is the value of the fill-column variable, minus the value of the right-margin property of the character after point.

Command: move-to-left-margin &optional n force
This function moves point to the left margin of the current line. The column moved to is determined by calling the function current-left-margin. If the argument n is non-nil, move-to-left-margin moves forward n-1 lines first.

If force is non-nil, that says to fix the line's indentation if that doesn't match the left margin value.

Function: delete-to-left-margin from to
This function removes left margin indentation from the text between from and to. The amount of indentation to delete is determined by calling current-left-margin. In no case does this function delete non-whitespace.

Function: indent-to-left-margin
This is the default indent-line-function, used in Fundamental mode, Text mode, etc. Its effect is to adjust the indentation at the beginning of the current line to the value specified by the variable left-margin. This may involve either inserting or deleting whitespace.

Variable: left-margin
This variable specifies the base left margin column. In Fundamental mode, C-j indents to this column. This variable automatically becomes buffer-local when set in any fashion.

Variable: fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line at certain places. Its value should be a function. This function is called during filling, with no arguments and with point located at the place where a break is being considered. If the function returns non-nil, then the line won't be broken there.

Adaptive Fill Mode

Adaptive Fill mode chooses a fill prefix automatically from the text in each paragraph being filled.

User Option: adaptive-fill-mode
Adaptive Fill mode is enabled when this variable is non-nil. It is t by default.

Function: fill-context-prefix from to
This function implements the heart of Adaptive Fill mode; it chooses a fill prefix based on the text between from and to. It does this by looking at the first two lines of the paragraph, based on the variables described below.

User Option: adaptive-fill-regexp
This variable holds a regular expression to control Adaptive Fill mode. Adaptive Fill mode matches this regular expression against the text starting after the left margin whitespace (if any) on a line; the characters it matches are that line's candidate for the fill prefix.

User Option: adaptive-fill-first-line-regexp
In a one-line paragraph, if the candidate fill prefix matches this regular expression, or if it matches comment-start-skip, then it is used--otherwise, spaces amounting to the same width are used instead.

However, the fill prefix is never taken from a one-line paragraph if it would act as a paragraph starter on subsequent lines.

User Option: adaptive-fill-function
You can specify more complex ways of choosing a fill prefix automatically by setting this variable to a function. The function is called when adaptive-fill-regexp does not match, with point after the left margin of a line, and it should return the appropriate fill prefix based on that line. If it returns nil, that means it sees no fill prefix in that line.

Auto Filling

Auto Fill mode is a minor mode that fills lines automatically as text is inserted. This section describes the hook used by Auto Fill mode. For a description of functions that you can call explicitly to fill and justify existing text, see section Filling.

Auto Fill mode also enables the functions that change the margins and justification style to refill portions of the text. See section Margins for Filling.

Variable: auto-fill-function
The value of this variable should be a function (of no arguments) to be called after self-inserting a space or a newline. It may be nil, in which case nothing special is done in that case.

The value of auto-fill-function is do-auto-fill when Auto-Fill mode is enabled. That is a function whose sole purpose is to implement the usual strategy for breaking a line.

In older Emacs versions, this variable was named auto-fill-hook, but since it is not called with the standard convention for hooks, it was renamed to auto-fill-function in version 19.

Variable: normal-auto-fill-function
This variable specifies the function to use for auto-fill-function, if and when Auto Fill is turned on. Major modes can set buffer-local values for this variable to alter how Auto Fill works.

Sorting Text

The sorting functions described in this section all rearrange text in a buffer. This is in contrast to the function sort, which rearranges the order of the elements of a list (see section Functions that Rearrange Lists). The values returned by these functions are not meaningful.

Function: sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
This function is the general text-sorting routine that subdivides a buffer into records and then sorts them. Most of the commands in this section use this function.

To understand how sort-subr works, consider the whole accessible portion of the buffer as being divided into disjoint pieces called sort records. The records may or may not be contiguous, but they must not overlap. A portion of each sort record (perhaps all of it) is designated as the sort key. Sorting rearranges the records in order by their sort keys.

Usually, the records are rearranged in order of ascending sort key. If the first argument to the sort-subr function, reverse, is non-nil, the sort records are rearranged in order of descending sort key.

The next four arguments to sort-subr are functions that are called to move point across a sort record. They are called many times from within sort-subr.

nextrecfun is called with point at the end of a record. This function moves point to the start of the next record. The first record is assumed to start at the position of point when sort-subr is called. Therefore, you should usually move point to the beginning of the buffer before calling sort-subr. This function can indicate there are no more sort records by leaving point at the end of the buffer.
endrecfun is called with point within a record. It moves point to the end of the record.
startkeyfun is called to move point from the start of a record to the start of the sort key. This argument is optional; if it is omitted, the whole record is the sort key. If supplied, the function should either return a non-nil value to be used as the sort key, or return nil to indicate that the sort key is in the buffer starting at point. In the latter case, endkeyfun is called to find the end of the sort key.
endkeyfun is called to move point from the start of the sort key to the end of the sort key. This argument is optional. If startkeyfun returns nil and this argument is omitted (or nil), then the sort key extends to the end of the record. There is no need for endkeyfun if startkeyfun returns a non-nil value.

As an example of sort-subr, here is the complete function definition for sort-lines:
;; Note that the first two lines of doc string
;; are effectively one line when viewed by a user.
(defun sort-lines (reverse beg end)
  "Sort lines in region alphabetically;\
 argument means descending order.
Called from a program, there are three arguments:
REVERSE (non-nil means reverse order),\
 BEG and END (region to sort).
The variable `sort-fold-case' determines\
 whether alphabetic case affects
the sort order.
  (interactive "P\nr")
  (save-excursion
    (save-restriction
      (narrow-to-region beg end)
      (goto-char (point-min))
      (sort-subr reverse 'forward-line 'end-of-line))))
Here forward-line moves point to the start of the next record, and end-of-line moves point to the end of record. We do not pass the arguments startkeyfun and endkeyfun, because the entire record is used as the sort key.

The sort-paragraphs function is very much the same, except that its sort-subr call looks like this:
(sort-subr reverse
           (function
             (lambda ()
               (while (and (not (eobp))
                      (looking-at paragraph-separate))
                 (forward-line 1))))
           'forward-paragraph)
Markers pointing into any sort records are left with no useful position after sort-subr returns.

User Option: sort-fold-case
If this variable is non-nil, sort-subr and the other buffer sorting functions ignore case when comparing strings.

Command: sort-regexp-fields reverse record-regexp key-regexp start end
This command sorts the region between start and end alphabetically as specified by record-regexp and key-regexp. If reverse is a negative integer, then sorting is in reverse order.

Alphabetical sorting means that two sort keys are compared by comparing the first characters of each, the second characters of each, and so on. If a mismatch is found, it means that the sort keys are unequal; the sort key whose character is less at the point of first mismatch is the lesser sort key. The individual characters are compared according to their numerical character codes in the Emacs character set.

The value of the record-regexp argument specifies how to divide the buffer into sort records. At the end of each record, a search is done for this regular expression, and the text that matches it is taken as the next record. For example, the regular expression `^.+$', which matches lines with at least one character besides a newline, would make each such line into a sort record. See section Regular Expressions, for a description of the syntax and meaning of regular expressions.

The value of the key-regexp argument specifies what part of each record is the sort key. The key-regexp could match the whole record, or only a part. In the latter case, the rest of the record has no effect on the sorted order of records, but it is carried along when the record moves to its new position.

The key-regexp argument can refer to the text matched by a subexpression of record-regexp, or it can be a regular expression on its own.

If key-regexp is:

`\digit'
then the text matched by the digitth `\(...\)' parenthesis grouping in record-regexp is the sort key.
`\&'
then the whole record is the sort key.
a regular expression
then sort-regexp-fields searches for a match for the regular expression within the record. If such a match is found, it is the sort key. If there is no match for key-regexp within a record then that record is ignored, which means its position in the buffer is not changed. (The other records may move around it.)
For example, if you plan to sort all the lines in the region by the first word on each line starting with the letter `f', you should set record-regexp to `^.*$' and set key-regexp to `\<f\w*\>'. The resulting expression looks like this:
(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
                    (region-beginning)
                    (region-end))
If you call sort-regexp-fields interactively, it prompts for record-regexp and key-regexp in the minibuffer.

Command: sort-lines reverse start end
This command alphabetically sorts lines in the region between start and end. If reverse is non-nil, the sort is in reverse order.

Command: sort-paragraphs reverse start end
This command alphabetically sorts paragraphs in the region between start and end. If reverse is non-nil, the sort is in reverse order.

Command: sort-pages reverse start end
This command alphabetically sorts pages in the region between start and end. If reverse is non-nil, the sort is in reverse order.

Command: sort-fields field start end
This command sorts lines in the region between start and end, comparing them alphabetically by the fieldth field of each line. Fields are separated by whitespace and numbered starting from 1. If field is negative, sorting is by the -fieldth field from the end of the line. This command is useful for sorting tables.

Command: sort-numeric-fields field start end
This command sorts lines in the region between start and end, comparing them numerically by the fieldth field of each line. The specified field must contain a number in each line of the region. Fields are separated by whitespace and numbered starting from 1. If field is negative, sorting is by the -fieldth field from the end of the line. This command is useful for sorting tables.

Command: sort-columns reverse &optional beg end
This command sorts the lines in the region between beg and end, comparing them alphabetically by a certain range of columns. The column positions of beg and end bound the range of columns to sort on.

If reverse is non-nil, the sort is in reverse order.

One unusual thing about this command is that the entire line containing position beg, and the entire line containing position end, are included in the region sorted.

Note that sort-columns uses the sort utility program, and so cannot work properly on text containing tab characters. Use M-x untabify to convert tabs to spaces before sorting.

Counting Columns

The column functions convert between a character position (counting characters from the beginning of the buffer) and a column position (counting screen characters from the beginning of a line).

These functions count each character according to the number of columns it occupies on the screen. This means control characters count as occupying 2 or 4 columns, depending upon the value of ctl-arrow, and tabs count as occupying a number of columns that depends on the value of tab-width and on the column where the tab begins. See section Usual Display Conventions.

Column number computations ignore the width of the window and the amount of horizontal scrolling. Consequently, a column value can be arbitrarily high. The first (or leftmost) column is numbered 0.

Function: current-column
This function returns the horizontal position of point, measured in columns, counting from 0 at the left margin. The column position is the sum of the widths of all the displayed representations of the characters between the start of the current line and point.

For an example of using current-column, see the description of count-lines in section Motion by Text Lines.

Function: move-to-column column &optional force
This function moves point to column in the current line. The calculation of column takes into account the widths of the displayed representations of the characters between the start of the line and point.

If column column is beyond the end of the line, point moves to the end of the line. If column is negative, point moves to the beginning of the line.

If it is impossible to move to column column because that is in the middle of a multicolumn character such as a tab, point moves to the end of that character. However, if force is non-nil, and column is in the middle of a tab, then move-to-column converts the tab into spaces so that it can move precisely to column column. Other multicolumn characters can cause anomalies despite force, since there is no way to split them.

The argument force also has an effect if the line isn't long enough to reach column column; in that case, it says to add whitespace at the end of the line to reach that column.

If column is not an integer, an error is signaled.

The return value is the column number actually moved to.

Indentation

The indentation functions are used to examine, move to, and change whitespace that is at the beginning of a line. Some of the functions can also change whitespace elsewhere on a line. Columns and indentation count from zero at the left margin.

Indentation Primitives

This section describes the primitive functions used to count and insert indentation. The functions in the following sections use these primitives. See section Width, for related functions.

Function: current-indentation
This function returns the indentation of the current line, which is the horizontal position of the first nonblank character. If the contents are entirely blank, then this is the horizontal position of the end of the line.

Command: indent-to column &optional minimum
This function indents from point with tabs and spaces until column is reached. If minimum is specified and non-nil, then at least that many spaces are inserted even if this requires going beyond column. Otherwise the function does nothing if point is already beyond column. The value is the column at which the inserted indentation ends.

The inserted whitespace characters inherit text properties from the surrounding text (usually, from the preceding text only). See section Stickiness of Text Properties.

User Option: indent-tabs-mode
If this variable is non-nil, indentation functions can insert tabs as well as spaces. Otherwise, they insert only spaces. Setting this variable automatically makes it buffer-local in the current buffer.

Indentation Controlled by Major Mode

An important function of each major mode is to customize the TAB key to indent properly for the language being edited. This section describes the mechanism of the TAB key and how to control it. The functions in this section return unpredictable values.

Variable: indent-line-function
This variable's value is the function to be used by TAB (and various commands) to indent the current line. The command indent-according-to-mode does no more than call this function.

In Lisp mode, the value is the symbol lisp-indent-line; in C mode, c-indent-line; in Fortran mode, fortran-indent-line. In Fundamental mode, Text mode, and many other modes with no standard for indentation, the value is indent-to-left-margin (which is the default value).

Command: indent-according-to-mode
This command calls the function in indent-line-function to indent the current line in a way appropriate for the current major mode.

Command: indent-for-tab-command
This command calls the function in indent-line-function to indent the current line; however, if that function is indent-to-left-margin, insert-tab is called instead. (That is a trivial command that inserts a tab character.)

Command: newline-and-indent
This function inserts a newline, then indents the new line (the one following the newline just inserted) according to the major mode.

It does indentation by calling the current indent-line-function. In programming language modes, this is the same thing TAB does, but in some text modes, where TAB inserts a tab, newline-and-indent indents to the column specified by left-margin.

Command: reindent-then-newline-and-indent
This command reindents the current line, inserts a newline at point, and then indents the new line (the one following the newline just inserted).

This command does indentation on both lines according to the current major mode, by calling the current value of indent-line-function. In programming language modes, this is the same thing TAB does, but in some text modes, where TAB inserts a tab, reindent-then-newline-and-indent indents to the column specified by left-margin.

Indenting an Entire Region

This section describes commands that indent all the lines in the region. They return unpredictable values.

Command: indent-region start end to-column
This command indents each nonblank line starting between start (inclusive) and end (exclusive). If to-column is nil, indent-region indents each nonblank line by calling the current mode's indentation function, the value of indent-line-function.

If to-column is non-nil, it should be an integer specifying the number of columns of indentation; then this function gives each line exactly that much indentation, by either adding or deleting whitespace.

If there is a fill prefix, indent-region indents each line by making it start with the fill prefix.

Variable: indent-region-function
The value of this variable is a function that can be used by indent-region as a short cut. It should take two arguments, the start and end of the region. You should design the function so that it will produce the same results as indenting the lines of the region one by one, but presumably faster.

If the value is nil, there is no short cut, and indent-region actually works line by line.

A short-cut function is useful in modes such as C mode and Lisp mode, where the indent-line-function must scan from the beginning of the function definition: applying it to each line would be quadratic in time. The short cut can update the scan information as it moves through the lines indenting them; this takes linear time. In a mode where indenting a line individually is fast, there is no need for a short cut.

indent-region with a non-nil argument to-column has a different meaning and does not use this variable.

Command: indent-rigidly start end count
This command indents all lines starting between start (inclusive) and end (exclusive) sideways by count columns. This "preserves the shape" of the affected region, moving it as a rigid unit. Consequently, this command is useful not only for indenting regions of unindented text, but also for indenting regions of formatted code.

For example, if count is 3, this command adds 3 columns of indentation to each of the lines beginning in the region specified.

In Mail mode, C-c C-y (mail-yank-original) uses indent-rigidly to indent the text copied from the message being replied to.

Function: indent-code-rigidly start end columns &optional nochange-regexp
This is like indent-rigidly, except that it doesn't alter lines that start within strings or comments.

In addition, it doesn't alter a line if nochange-regexp matches at the beginning of the line (if nochange-regexp is non-nil).

Indentation Relative to Previous Lines

This section describes two commands that indent the current line based on the contents of previous lines.

Command: indent-relative &optional unindented-ok
This command inserts whitespace at point, extending to the same column as the next indent point of the previous nonblank line. An indent point is a non-whitespace character following whitespace. The next indent point is the first one at a column greater than the current column of point. For example, if point is underneath and to the left of the first non-blank character of a line of text, it moves to that column by inserting whitespace.

If the previous nonblank line has no next indent point (i.e., none at a great enough column position), indent-relative either does nothing (if unindented-ok is non-nil) or calls tab-to-tab-stop. Thus, if point is underneath and to the right of the last column of a short line of text, this command ordinarily moves point to the next tab stop by inserting whitespace.

The return value of indent-relative is unpredictable.

In the following example, point is at the beginning of the second line:
            This line is indented twelve spaces.
-!-The quick brown fox jumped.
Evaluation of the expression (indent-relative nil) produces the following:
            This line is indented twelve spaces.
            -!-The quick brown fox jumped.
In this next example, point is between the `m' and `p' of `jumped':
            This line is indented twelve spaces.
The quick brown fox jum-!-ped.
Evaluation of the expression (indent-relative nil) produces the following:
            This line is indented twelve spaces.
The quick brown fox jum  -!-ped.
Command: indent-relative-maybe
This command indents the current line like the previous nonblank line, by calling indent-relative with t as the unindented-ok argument. The return value is unpredictable.

If the previous nonblank line has no indent points beyond the current column, this command does nothing.

Adjustable "Tab Stops"

This section explains the mechanism for user-specified "tab stops" and the mechanisms that use and set them. The name "tab stops" is used because the feature is similar to that of the tab stops on a typewriter. The feature works by inserting an appropriate number of spaces and tab characters to reach the next tab stop column; it does not affect the display of tab characters in the buffer (see section Usual Display Conventions). Note that the TAB character as input uses this tab stop feature only in a few major modes, such as Text mode.

Command: tab-to-tab-stop
This command inserts spaces or tabs before point, up to the next tab stop column defined by tab-stop-list. It searches the list for an element greater than the current column number, and uses that element as the column to indent to. It does nothing if no such element is found.

User Option: tab-stop-list
This variable is the list of tab stop columns used by tab-to-tab-stops. The elements should be integers in increasing order. The tab stop columns need not be evenly spaced.

Use M-x edit-tab-stops to edit the location of tab stops interactively.

Indentation-Based Motion Commands

These commands, primarily for interactive use, act based on the indentation in the text.

Command: back-to-indentation
This command moves point to the first non-whitespace character in the current line (which is the line in which point is located). It returns nil.

Command: backward-to-indentation arg
This command moves point backward arg lines and then to the first nonblank character on that line. It returns nil.

Command: forward-to-indentation arg
This command moves point forward arg lines and then to the first nonblank character on that line. It returns nil.

Case Changes

The case change commands described here work on text in the current buffer. See section Case Conversion in Lisp, for case conversion functions that work on strings and characters. See section The Case Table, for how to customize which characters are upper or lower case and how to convert them.

Command: capitalize-region start end
This function capitalizes all words in the region defined by start and end. To capitalize means to convert each word's first character to upper case and convert the rest of each word to lower case. The function returns nil.

If one end of the region is in the middle of a word, the part of the word within the region is treated as an entire word.

When capitalize-region is called interactively, start and end are point and the mark, with the smallest first.
---------- Buffer: foo ----------
This is the contents of the 5th foo.
---------- Buffer: foo ----------

(capitalize-region 1 44)
=> nil

---------- Buffer: foo ----------
This Is The Contents Of The 5th Foo.
---------- Buffer: foo ----------
Command: downcase-region start end
This function converts all of the letters in the region defined by start and end to lower case. The function returns nil.

When downcase-region is called interactively, start and end are point and the mark, with the smallest first.

Command: upcase-region start end
This function converts all of the letters in the region defined by start and end to upper case. The function returns nil.

When upcase-region is called interactively, start and end are point and the mark, with the smallest first.

Command: capitalize-word count
This function capitalizes count words after point, moving point over as it does. To capitalize means to convert each word's first character to upper case and convert the rest of each word to lower case. If count is negative, the function capitalizes the -count previous words but does not move point. The value is nil.

If point is in the middle of a word, the part of the word before point is ignored when moving forward. The rest is treated as an entire word.

When capitalize-word is called interactively, count is set to the numeric prefix argument.

Command: downcase-word count
This function converts the count words after point to all lower case, moving point over as it does. If count is negative, it converts the -count previous words but does not move point. The value is nil.

When downcase-word is called interactively, count is set to the numeric prefix argument.

Command: upcase-word count
This function converts the count words after point to all upper case, moving point over as it does. If count is negative, it converts the -count previous words but does not move point. The value is nil.

When upcase-word is called interactively, count is set to the numeric prefix argument.

Text Properties

Each character position in a buffer or a string can have a text property list, much like the property list of a symbol (see section Property Lists). The properties belong to a particular character at a particular place, such as, the letter `T' at the beginning of this sentence or the first `o' in `foo'---if the same character occurs in two different places, the two occurrences generally have different properties.

Each property has a name and a value. Both of these can be any Lisp object, but the name is normally a symbol. The usual way to access the property list is to specify a name and ask what value corresponds to it.

If a character has a category property, we call it the category of the character. It should be a symbol. The properties of the symbol serve as defaults for the properties of the character.

Copying text between strings and buffers preserves the properties along with the characters; this includes such diverse functions as substring, insert, and buffer-substring.

Examining Text Properties

The simplest way to examine text properties is to ask for the value of a particular property of a particular character. For that, use get-text-property. Use text-properties-at to get the entire property list of a character. See section Text Property Search Functions, for functions to examine the properties of a number of characters at once.

These functions handle both strings and buffers. Keep in mind that positions in a string start from 0, whereas positions in a buffer start from 1.

Function: get-text-property pos prop &optional object
This function returns the value of the prop property of the character after position pos in object (a buffer or string). The argument object is optional and defaults to the current buffer.

If there is no prop property strictly speaking, but the character has a category that is a symbol, then get-text-property returns the prop property of that symbol.

Function: get-char-property pos prop &optional object
This function is like get-text-property, except that it checks overlays first and then text properties. See section Overlays.

The argument object may be a string, a buffer, or a window. If it is a window, then the buffer displayed in that window is used for text properties and overlays, but only the overlays active for that window are considered. If object is a buffer, then all overlays in that buffer are considered, as well as text properties. If object is a string, only text properties are considered, since strings never have overlays.

Function: text-properties-at position &optional object
This function returns the entire property list of the character at position in the string or buffer object. If object is nil, it defaults to the current buffer.

Variable: default-text-properties
This variable holds a property list giving default values for text properties. Whenever a character does not specify a value for a property, neither directly nor through a category symbol, the value stored in this list is used instead. Here is an example:
(setq default-text-properties '(foo 69))
;; Make sure character 1 has no properties of its own.
(set-text-properties 1 2 nil)
;; What we get, when we ask, is the default value.
(get-text-property 1 'foo)
     => 69
Changing Text Properties

The primitives for changing properties apply to a specified range of text in a buffer or string. The function set-text-properties (see end of section) sets the entire property list of the text in that range; more often, it is useful to add, change, or delete just certain properties specified by name.

Since text properties are considered part of the contents of the buffer (or string), and can affect how a buffer looks on the screen, any change in buffer text properties mark the buffer as modified. Buffer text property changes are undoable also (see section Undo).

Function: put-text-property start end prop value &optional object
This function sets the prop property to value for the text between start and end in the string or buffer object. If object is nil, it defaults to the current buffer.

Function: add-text-properties start end props &optional object
This function adds or overrides text properties for the text between start and end in the string or buffer object. If object is nil, it defaults to the current buffer.

The argument props specifies which properties to add. It should have the form of a property list (see section Property Lists): a list whose elements include the property names followed alternately by the corresponding values.

The return value is t if the function actually changed some property's value; nil otherwise (if props is nil or its values agree with those in the text).

For example, here is how to set the comment and face properties of a range of text:
(add-text-properties start end
                     '(comment t face highlight))
Function: remove-text-properties start end props &optional object
This function deletes specified text properties from the text between start and end in the string or buffer object. If object is nil, it defaults to the current buffer.

The argument props specifies which properties to delete. It should have the form of a property list (see section Property Lists): a list whose elements are property names alternating with corresponding values. But only the names matter--the values that accompany them are ignored. For example, here's how to remove the face property.
(remove-text-properties start end '(face nil))
The return value is t if the function actually changed some property's value; nil otherwise (if props is nil or if no character in the specified text had any of those properties).

To remove all text properties from certain text, use set-text-properties and specify nil for the new property list.

Function: set-text-properties start end props &optional object
This function completely replaces the text property list for the text between start and end in the string or buffer object. If object is nil, it defaults to the current buffer.

The argument props is the new property list. It should be a list whose elements are property names alternating with corresponding values.

After set-text-properties returns, all the characters in the specified range have identical properties.

If props is nil, the effect is to get rid of all properties from the specified range of text. Here's an example:
(set-text-properties start end nil)
See also the function buffer-substring-no-properties (see section Examining Buffer Contents) which copies text from the buffer but does not copy its properties.

Text Property Search Functions

In typical use of text properties, most of the time several or many consecutive characters have the same value for a property. Rather than writing your programs to examine characters one by one, it is much faster to process chunks of text that have the same property value.

Here are functions you can use to do this. They use eq for comparing property values. In all cases, object defaults to the current buffer.

For high performance, it's very important to use the limit argument to these functions, especially the ones that search for a single property--otherwise, they may spend a long time scanning to the end of the buffer, if the property you are interested in does not change.

These functions do not move point; instead, they return a position (or nil). Remember that a position is always between two characters; the position returned by these functions is between two characters with different properties.

Function: next-property-change pos &optional object limit
The function scans the text forward from position pos in the string or buffer object till it finds a change in some text property, then returns the position of the change. In other words, it returns the position of the first character beyond pos whose properties are not identical to those of the character just after pos.

If limit is non-nil, then the scan ends at position limit. If there is no property change before that point, next-property-change returns limit.

The value is nil if the properties remain unchanged all the way to the end of object and limit is nil. If the value is non-nil, it is a position greater than or equal to pos. The value equals pos only when limit equals pos.

Here is an example of how to scan the buffer by chunks of text within which all properties are constant:
(while (not (eobp))
  (let ((plist (text-properties-at (point)))
        (next-change
         (or (next-property-change (point) (current-buffer))
             (point-max))))
    Process text from point to next-change...
    (goto-char next-change)))
Function: next-single-property-change pos prop &optional object limit
The function scans the text forward from position pos in the string or buffer object till it finds a change in the prop property, then returns the position of the change. In other words, it returns the position of the first character beyond pos whose prop property differs from that of the character just after pos.

If limit is non-nil, then the scan ends at position limit. If there is no property change before that point, next-single-property-change returns limit.

The value is nil if the property remains unchanged all the way to the end of object and limit is nil. If the value is non-nil, it is a position greater than or equal to pos; it equals pos only if limit equals pos.

Function: previous-property-change pos &optional object limit
This is like next-property-change, but scans back from pos instead of forward. If the value is non-nil, it is a position less than or equal to pos; it equals pos only if limit equals pos.

Function: previous-single-property-change pos prop &optional object limit
This is like next-single-property-change, but scans back from pos instead of forward. If the value is non-nil, it is a position less than or equal to pos; it equals pos only if limit equals pos.

Function: next-char-property-change position &optional limit
This is like next-property-change except that it considers overlay properties as well as text properties. There is no object operand because this function operates only on the current buffer. It returns the next address at which either kind of property changes.

Function: previous-char-property-change position &optional limit
This is like next-char-property-change, but scans back from position instead of forward.

Function: text-property-any start end prop value &optional object
This function returns non-nil if at least one character between start and end has a property prop whose value is value. More precisely, it returns the position of the first such character. Otherwise, it returns nil.

The optional fifth argument, object, specifies the string or buffer to scan. Positions are relative to object. The default for object is the current buffer.

Function: text-property-not-all start end prop value &optional object
This function returns non-nil if at least one character between start and end does not have a property prop with value value. More precisely, it returns the position of the first such character. Otherwise, it returns nil.

The optional fifth argument, object, specifies the string or buffer to scan. Positions are relative to object. The default for object is the current buffer.

Properties with Special Meanings

Here is a table of text property names that have special built-in meanings. The following sections list a few additional special property names that control filling and property inheritance. All other names have no standard meaning, and you can use them as you like.

category
If a character has a category property, we call it the category of the character. It should be a symbol. The properties of the symbol serve as defaults for the properties of the character.
face
You can use the property face to control the font and color of text. Its value is a face name or a list of face names. See section Faces, for more information. If the property value is a list, elements may also have the form (foreground-color . color-name) or (background-color . color-name). These elements specify just the foreground color or just the background color; therefore, there is no need to create a face for each color that you want to use. See section Font Lock Mode, for information on how to update face properties automatically based on the contents of the text.
mouse-face
The property mouse-face is used instead of face when the mouse is on or near the character. For this purpose, "near" means that all text between the character and where the mouse is have the same mouse-face property value.
local-map
You can specify a different keymap for some of the text in a buffer by means of the local-map property. The property's value for the character after point, if non-nil, is used for key lookup instead of the buffer's local map. If the property value is a symbol, the symbol's function definition is used as the keymap. See section Active Keymaps.
syntax-table
The syntax-table property overrides what the syntax table says about this particular character. See section Syntax Properties.
read-only
If a character has the property read-only, then modifying that character is not allowed. Any command that would do so gets an error. Insertion next to a read-only character is an error if inserting ordinary text there would inherit the read-only property due to stickiness. Thus, you can control permission to insert next to read-only text by controlling the stickiness. See section Stickiness of Text Properties. Since changing properties counts as modifying the buffer, it is not possible to remove a read-only property unless you know the special trick: bind inhibit-read-only to a non-nil value and then remove the property. See section Read-Only Buffers.
invisible
A non-nil invisible property can make a character invisible on the screen. See section Invisible Text, for details.
intangible
If a group of consecutive characters have equal and non-nil intangible properties, then you cannot place point between them. If you try to move point forward into the group, point actually moves to the end of the group. If you try to move point backward into the group, point actually moves to the start of the group. When the variable inhibit-point-motion-hooks is non-nil, the intangible property is ignored.
modification-hooks
If a character has the property modification-hooks, then its value should be a list of functions; modifying that character calls all of those functions. Each function receives two arguments: the beginning and end of the part of the buffer being modified. Note that if a particular modification hook function appears on several characters being modified by a single primitive, you can't predict how many times the function will be called.
insert-in-front-hooks

insert-behind-hooks
The operation of inserting text in a buffer also calls the functions listed in the insert-in-front-hooks property of the following character and in the insert-behind-hooks property of the preceding character. These functions receive two arguments, the beginning and end of the inserted text. The functions are called after the actual insertion takes place. See also section Change Hooks, for other hooks that are called when you change text in a buffer.
point-entered

point-left
The special properties point-entered and point-left record hook functions that report motion of point. Each time point moves, Emacs compares these two property values:

the point-left property of the character after the old location, and
the point-entered property of the character after the new location.
If these two values differ, each of them is called (if not nil) with two arguments: the old value of point, and the new one. The same comparison is made for the characters before the old and new locations. The result may be to execute two point-left functions (which may be the same function) and/or two point-entered functions (which may be the same function). In any case, all the point-left functions are called first, followed by all the point-entered functions. It is possible using char-after to examine characters at various positions without moving point to those positions. Only an actual change in the value of point runs these hook functions.

Variable: inhibit-point-motion-hooks
When this variable is non-nil, point-left and point-entered hooks are not run, and the intangible property has no effect. Do not set this variable globally; bind it with let.

Formatted Text Properties

These text properties affect the behavior of the fill commands. They are used for representing formatted text. See section Filling, and section Margins for Filling.

hard
If a newline character has this property, it is a "hard" newline. The fill commands do not alter hard newlines and do not move words across them. However, this property takes effect only if the variable use-hard-newlines is non-nil.
right-margin
This property specifies an extra right margin for filling this part of the text.
left-margin
This property specifies an extra left margin for filling this part of the text.
justification
This property specifies the style of justification for filling this part of the text.
Stickiness of Text Properties

Self-inserting characters normally take on the same properties as the preceding character. This is called inheritance of properties.

In a Lisp program, you can do insertion with inheritance or without, depending on your choice of insertion primitive. The ordinary text insertion functions such as insert do not inherit any properties. They insert text with precisely the properties of the string being inserted, and no others. This is correct for programs that copy text from one context to another--for example, into or out of the kill ring. To insert with inheritance, use the special primitives described in this section. Self-inserting characters inherit properties because they work using these primitives.

When you do insertion with inheritance, which properties are inherited depends on two specific properties: front-sticky and rear-nonsticky.

Insertion after a character inherits those of its properties that are rear-sticky. Insertion before a character inherits those of its properties that are front-sticky. By default, a text property is rear-sticky but not front-sticky. Thus, the default is to inherit all the properties of the preceding character, and nothing from the following character. You can request different behavior by specifying the stickiness of certain properties.

If a character's front-sticky property is t, then all its properties are front-sticky. If the front-sticky property is a list, then the sticky properties of the character are those whose names are in the list. For example, if a character has a front-sticky property whose value is (face read-only), then insertion before the character can inherit its face property and its read-only property, but no others.

The rear-nonsticky works the opposite way. Every property is rear-sticky by default, so the rear-nonsticky property says which properties are not rear-sticky. If a character's rear-nonsticky property is t, then none of its properties are rear-sticky. If the rear-nonsticky property is a list, properties are rear-sticky unless their names are in the list.

When you insert text with inheritance, it inherits all the rear-sticky properties of the preceding character, and all the front-sticky properties of the following character. The previous character's properties take precedence when both sides offer different sticky values for the same property.

Here are the functions that insert text with inheritance of properties:

Function: insert-and-inherit &rest strings
Insert the strings strings, just like the function insert, but inherit any sticky properties from the adjoining text.

Function: insert-before-markers-and-inherit &rest strings
Insert the strings strings, just like the function insert-before-markers, but inherit any sticky properties from the adjoining text.

See section Inserting Text, for the ordinary insertion functions which do not inherit.

Saving Text Properties in Files

You can save text properties in files (along with the text itself), and restore the same text properties when visiting or inserting the files, using these two hooks:

Variable: write-region-annotate-functions
This variable's value is a list of functions for write-region to run to encode text properties in some fashion as annotations to the text being written in the file. See section Writing to Files.

Each function in the list is called with two arguments: the start and end of the region to be written. These functions should not alter the contents of the buffer. Instead, they should return lists indicating annotations to write in the file in addition to the text in the buffer.

Each function should return a list of elements of the form (position . string), where position is an integer specifying the relative position within the text to be written, and string is the annotation to add there.

Each list returned by one of these functions must be already sorted in increasing order by position. If there is more than one function, write-region merges the lists destructively into one sorted list.

When write-region actually writes the text from the buffer to the file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer.

Variable: after-insert-file-functions
This variable holds a list of functions for insert-file-contents to call after inserting a file's contents. These functions should scan the inserted text for annotations, and convert them to the text properties they stand for.

Each function receives one argument, the length of the inserted text; point indicates the start of that text. The function should scan that text for annotations, delete them, and create the text properties that the annotations specify. The function should return the updated length of the inserted text, as it stands after those changes. The value returned by one function becomes the argument to the next function.

These functions should always return with point at the beginning of the inserted text.

The intended use of after-insert-file-functions is for converting some sort of textual annotations into actual text properties. But other uses may be possible.

We invite users to write Lisp programs to store and retrieve text properties in files, using these hooks, and thus to experiment with various data formats and find good ones. Eventually we hope users will produce good, general extensions we can install in Emacs.

We suggest not trying to handle arbitrary Lisp objects as text property names or values--because a program that general is probably difficult to write, and slow. Instead, choose a set of possible data types that are reasonably flexible, and not too hard to encode.

See section File Format Conversion, for a related feature.

Lazy Computation of Text Properties

Instead of computing text properties for all the text in the buffer, you can arrange to compute the text properties for parts of the text when and if something depends on them.

The primitive that extracts text from the buffer along with its properties is buffer-substring. Before examining the properties, this function runs the abnormal hook buffer-access-fontify-functions.

Variable: buffer-access-fontify-functions
This variable holds a list of functions for computing text properties. Before buffer-substring copies the text and text properties for a portion of the buffer, it calls all the functions in this list. Each of the functions receives two arguments that specify the range of the buffer being accessed. (The buffer itself is always the current buffer.)

The function buffer-substring-no-properties does not call these functions, since it ignores text properties anyway.

In order to prevent the hook functions from being called more than once for the same part of the buffer, you can use the variable buffer-access-fontified-property.

Variable: buffer-access-fontified-property
If this value's variable is non-nil, it is a symbol which is used as a text property name. A non-nil value for that text property means, "the other text properties for this character have already been computed."

If all the characters in the range specified for buffer-substring have a non-nil value for this property, buffer-substring does not call the buffer-access-fontify-functions functions. It assumes these characters already have the right text properties, and just copies the properties they already have.

The normal way to use this feature is that the buffer-access-fontify-functions functions add this property, as well as others, to the characters they operate on. That way, they avoid being called over and over for the same text.

Defining Clickable Text

There are two ways to set up clickable text in a buffer. There are typically two parts of this: to make the text highlight when the mouse is over it, and to make a mouse button do something when you click it on that part of the text.

Highlighting is done with the mouse-face text property. Here is an example of how Dired does it:
(condition-case nil
    (if (dired-move-to-filename)
        (put-text-property (point)
                           (save-excursion
                             (dired-move-to-end-of-filename)
                             (point))
                           'mouse-face 'highlight))
  (error nil))
The first two arguments to put-text-property specify the beginning and end of the text.

The usual way to make the mouse do something when you click it on this text is to define mouse-2 in the major mode's keymap. The job of checking whether the click was on clickable text is done by the command definition. Here is how Dired does it:
(defun dired-mouse-find-file-other-window (event)
  "In dired, visit the file or directory name you click on."
  (interactive "e")
  (let (file)
    (save-excursion
      (set-buffer (window-buffer (posn-window (event-end event))))
      (save-excursion
        (goto-char (posn-point (event-end event)))
        (setq file (dired-get-filename))))
    (select-window (posn-window (event-end event)))
    (find-file-other-window (file-name-sans-versions file t))))
The reason for the outer save-excursion construct is to avoid changing the current buffer; the reason for the inner one is to avoid permanently altering point in the buffer you click on. In this case, Dired uses the function dired-get-filename to determine which file to visit, based on the position found in the event.

Instead of defining a mouse command for the major mode, you can define a key binding for the clickable text itself, using the local-map text property:
(let ((map (make-sparse-keymap)))
  (define-key-binding map [mouse-2] 'operate-this-button)
  (put-text-property (point)
                     (save-excursion
                       (dired-move-to-end-of-filename)
                       (point))
                     'local-map map))
This method makes it possible to define different commands for various clickable pieces of text. Also, the major mode definition (or the global definition) remains available for the rest of the text in the buffer.

Why Text Properties are not Intervals

Some editors that support adding attributes to text in the buffer do so by letting the user specify "intervals" within the text, and adding the properties to the intervals. Those editors permit the user or the programmer to determine where individual intervals start and end. We deliberately provided a different sort of interface in Emacs Lisp to avoid certain paradoxical behavior associated with text modification.

If the actual subdivision into intervals is meaningful, that means you can distinguish between a buffer that is just one interval with a certain property, and a buffer containing the same text subdivided into two intervals, both of which have that property.

Suppose you take the buffer with just one interval and kill part of the text. The text remaining in the buffer is one interval, and the copy in the kill ring (and the undo list) becomes a separate interval. Then if you yank back the killed text, you get two intervals with the same properties. Thus, editing does not preserve the distinction between one interval and two.

Suppose we "fix" this problem by coalescing the two intervals when the text is inserted. That works fine if the buffer originally was a single interval. But suppose instead that we have two adjacent intervals with the same properties, and we kill the text of one interval and yank it back. The same interval-coalescence feature that rescues the other case causes trouble in this one: after yanking, we have just one interval. One again, editing does not preserve the distinction between one interval and two.

Insertion of text at the border between intervals also raises questions that have no satisfactory answer.

However, it is easy to arrange for editing to behave consistently for questions of the form, "What are the properties of this character?" So we have decided these are the only questions that make sense; we have not implemented asking questions about where intervals start or end.

In practice, you can usually use the text property search functions in place of explicit interval boundaries. You can think of them as finding the boundaries of intervals, assuming that intervals are always coalesced whenever possible. See section Text Property Search Functions.

Emacs also provides explicit intervals as a presentation feature; see section Overlays.

Substituting for a Character Code

The following functions replace characters within a specified region based on their character codes.

Function: subst-char-in-region start end old-char new-char &optional noundo
This function replaces all occurrences of the character old-char with the character new-char in the region of the current buffer defined by start and end.

If noundo is non-nil, then subst-char-in-region does not record the change for undo and does not mark the buffer as modified. This feature is used for controlling selective display (see section Selective Display).

subst-char-in-region does not move point and returns nil.
---------- Buffer: foo ----------
This is the contents of the buffer before.
---------- Buffer: foo ----------

(subst-char-in-region 1 20 ?i ?X)
     => nil

---------- Buffer: foo ----------
ThXs Xs the contents of the buffer before.
---------- Buffer: foo ----------
Function: translate-region start end table
This function applies a translation table to the characters in the buffer between positions start and end.

The translation table table is a string; (aref table ochar) gives the translated character corresponding to ochar. If the length of table is less than 256, any characters with codes larger than the length of table are not altered by the translation.

The return value of translate-region is the number of characters that were actually changed by the translation. This does not count characters that were mapped into themselves in the translation table.

Registers

A register is a sort of variable used in Emacs editing that can hold a variety of different kinds of values. Each register is named by a single character. All ASCII characters and their meta variants (but with the exception of C-g) can be used to name registers. Thus, there are 255 possible registers. A register is designated in Emacs Lisp by the character that is its name.

Variable: register-alist
This variable is an alist of elements of the form (name . contents). Normally, there is one element for each Emacs register that has been used.

The object name is a character (an integer) identifying the register.

The contents of a register can have several possible types:

a number
A number stands for itself. If insert-register finds a number in the register, it converts the number to decimal.
a marker
A marker represents a buffer position to jump to.
a string
A string is text saved in the register.
a rectangle
A rectangle is represented by a list of strings.
(window-configuration position)
This represents a window configuration to restore in one frame, and a position to jump to in the current buffer.
(frame-configuration position)
This represents a frame configuration to restore, and a position to jump to in the current buffer.
(file filename)
This represents a file to visit; jumping to this value visits file filename.
(file-query filename position)
This represents a file to visit and a position in it; jumping to this value visits file filename and goes to buffer position position. Restoring this type of position asks the user for confirmation first.
The functions in this section return unpredictable values unless otherwise stated.

Function: get-register reg
This function returns the contents of the register reg, or nil if it has no contents.

Function: set-register reg value
This function sets the contents of register reg to value. A register can be set to any value, but the other register functions expect only certain data types. The return value is value.

Command: view-register reg
This command displays what is contained in register reg.

Command: insert-register reg &optional beforep
This command inserts contents of register reg into the current buffer.

Normally, this command puts point before the inserted text, and the mark after it. However, if the optional second argument beforep is non-nil, it puts the mark before and point after. You can pass a non-nil second argument beforep to this function interactively by supplying any prefix argument.

If the register contains a rectangle, then the rectangle is inserted with its upper left corner at point. This means that text is inserted in the current line and underneath it on successive lines.

If the register contains something other than saved text (a string) or a rectangle (a list), currently useless things happen. This may be changed in the future.

Transposition of Text

This subroutine is used by the transposition commands.

Function: transpose-regions start1 end1 start2 end2 &optional leave-markers
This function exchanges two nonoverlapping portions of the buffer. Arguments start1 and end1 specify the bounds of one portion and arguments start2 and end2 specify the bounds of the other portion.

Normally, transpose-regions relocates markers with the transposed text; a marker previously positioned within one of the two transposed portions moves along with that portion, thus remaining between the same two characters in their new position. However, if leave-markers is non-nil, transpose-regions does not do this--it leaves all markers unrelocated.

Change Hooks

These hook variables let you arrange to take notice of all changes in all buffers (or in a particular buffer, if you make them buffer-local). See also section Properties with Special Meanings, for how to detect changes to specific parts of the text.

The functions you use in these hooks should save and restore the match data if they do anything that uses regular expressions; otherwise, they will interfere in bizarre ways with the editing operations that call them.

Variable: before-change-functions
This variable holds a list of functions to call before any buffer modification. Each function gets two arguments, the beginning and end of the region that is about to change, represented as integers. The buffer that is about to change is always the current buffer.

Variable: after-change-functions
This variable holds a list of functions to call after any buffer modification. Each function receives three arguments: the beginning and end of the region just changed, and the length of the text that existed before the change. All three arguments are integers. The buffer that's about to change is always the current buffer.

The length of the old text is the difference between the buffer positions before and after that text as it was before the change. As for the changed text, its length is simply the difference between the first two arguments.

Macro: combine-after-change-calls body...
The macro executes body normally, but arranges to call the after-change functions just once for a series of several changes--if that seems safe.

If a program makes several text changes in the same area of the buffer, using the macro combine-after-change-calls around that part of the program can make it run considerably faster when after-change hooks are in use. When the after-change hooks are ultimately called, the arguments specify a portion of the buffer including all of the changes made within the combine-after-change-calls body.

Warning: You must not alter the values of after-change-functions and after-change-function within the body of a combine-after-change-calls form.

Note: If the changes you combine occur in widely scattered parts of the buffer, this will still work, but it is not advisable, because it may lead to inefficient behavior for some change hook functions.

Variable: before-change-function
This obsolete variable holds one function to call before any buffer modification (or nil for no function). It is called just like the functions in before-change-functions.

Variable: after-change-function
This obsolete variable holds one function to call after any buffer modification (or nil for no function). It is called just like the functions in after-change-functions.

The four variables above are temporarily bound to nil during the time that any of these functions is running. This means that if one of these functions changes the buffer, that change won't run these functions. If you do want a hook function to make changes that run these functions, make it bind these variables back to their usual values.

One inconvenient result of this protective feature is that you cannot have a function in after-change-functions or before-change-functions which changes the value of that variable. But that's not a real limitation. If you want those functions to change the list of functions to run, simply add one fixed function to the hook, and code that function to look in another variable for other functions to call. Here is an example:
(setq my-own-after-change-functions nil)
(defun indirect-after-change-function (beg end len)
  (let ((list my-own-after-change-functions))
    (while list
      (funcall (car list) beg end len)
      (setq list (cdr list)))))

(add-hooks 'after-change-functions
           'indirect-after-change-function)
Variable: first-change-hook
This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state.
Non-ASCII Characters

This chapter covers the special issues relating to non-ASCII characters and how they are stored in strings and buffers.

Text Representations

Emacs has two text representations---two ways to represent text in a string or buffer. These are called unibyte and multibyte. Each string, and each buffer, uses one of these two representations. For most purposes, you can ignore the issue of representations, because Emacs converts text between them as appropriate. Occasionally in Lisp programming you will need to pay attention to the difference.

In unibyte representation, each character occupies one byte and therefore the possible character codes range from 0 to 255. Codes 0 through 127 are ASCII characters; the codes from 128 through 255 are used for one non-ASCII character set (you can choose which character set by setting the variable nonascii-insert-offset).

In multibyte representation, a character may occupy more than one byte, and as a result, the full range of Emacs character codes can be stored. The first byte of a multibyte character is always in the range 128 through 159 (octal 0200 through 0237). These values are called leading codes. The second and subsequent bytes of a multibyte character are always in the range 160 through 255 (octal 0240 through 0377); these values are trailing codes.

In a buffer, the buffer-local value of the variable enable-multibyte-characters specifies the representation used. The representation for a string is determined based on the string contents when the string is constructed.

Variable: enable-multibyte-characters
This variable specifies the current buffer's text representation. If it is non-nil, the buffer contains multibyte text; otherwise, it contains unibyte text.

You cannot set this variable directly; instead, use the function set-buffer-multibyte to change a buffer's representation.

Variable: default-enable-multibyte-characters
This variable's value is entirely equivalent to (default-value 'enable-multibyte-characters), and setting this variable changes that default value. Setting the local binding of enable-multibyte-characters in a specific buffer is not allowed, but changing the default value is supported, and it is a reasonable thing to do, because it has no effect on existing buffers.

The `--unibyte' command line option does its job by setting the default value to nil early in startup.

Function: multibyte-string-p string
Return t if string contains multibyte characters.

Converting Text Representations

Emacs can convert unibyte text to multibyte; it can also convert multibyte text to unibyte, though this conversion loses information. In general these conversions happen when inserting text into a buffer, or when putting text from several strings together in one string. You can also explicitly convert a string's contents to either representation.

Emacs chooses the representation for a string based on the text that it is constructed from. The general rule is to convert unibyte text to multibyte text when combining it with other multibyte text, because the multibyte representation is more general and can hold whatever characters the unibyte text has.

When inserting text into a buffer, Emacs converts the text to the buffer's representation, as specified by enable-multibyte-characters in that buffer. In particular, when you insert multibyte text into a unibyte buffer, Emacs converts the text to unibyte, even though this conversion cannot in general preserve all the characters that might be in the multibyte text. The other natural alternative, to convert the buffer contents to multibyte, is not acceptable because the buffer's representation is a choice made by the user that cannot be overridden automatically.

Converting unibyte text to multibyte text leaves ASCII characters unchanged, and likewise 128 through 159. It converts the non-ASCII codes 160 through 255 by adding the value nonascii-insert-offset to each character code. By setting this variable, you specify which character set the unibyte characters correspond to (see section Character Sets). For example, if nonascii-insert-offset is 2048, which is (- (make-char 'latin-iso8859-1) 128), then the unibyte non-ASCII characters correspond to Latin 1. If it is 2688, which is (- (make-char 'greek-iso8859-7) 128), then they correspond to Greek letters.

Converting multibyte text to unibyte is simpler: it performs logical-and of each character code with 255. If nonascii-insert-offset has a reasonable value, corresponding to the beginning of some character set, this conversion is the inverse of the other: converting unibyte text to multibyte and back to unibyte reproduces the original unibyte text.

Variable: nonascii-insert-offset
This variable specifies the amount to add to a non-ASCII character when converting unibyte text to multibyte. It also applies when self-insert-command inserts a character in the unibyte non-ASCII range, 128 through 255. However, the function insert-char does not perform this conversion.

The right value to use to select character set cs is (- (make-char cs) 128). If the value of nonascii-insert-offset is zero, then conversion actually uses the value for the Latin 1 character set, rather than zero.

Variable: nonascii-translation-table
This variable provides a more general alternative to nonascii-insert-offset. You can use it to specify independently how to translate each code in the range of 128 through 255 into a multibyte character. The value should be a vector, or nil. If this is non-nil, it overrides nonascii-insert-offset.

Function: string-make-unibyte string
This function converts the text of string to unibyte representation, if it isn't already, and returns the result. If string is a unibyte string, it is returned unchanged.

Function: string-make-multibyte string
This function converts the text of string to multibyte representation, if it isn't already, and returns the result. If string is a multibyte string, it is returned unchanged.

Selecting a Representation

Sometimes it is useful to examine an existing buffer or string as multibyte when it was unibyte, or vice versa.

Function: set-buffer-multibyte multibyte
Set the representation type of the current buffer. If multibyte is non-nil, the buffer becomes multibyte. If multibyte is nil, the buffer becomes unibyte.

This function leaves the buffer contents unchanged when viewed as a sequence of bytes. As a consequence, it can change the contents viewed as characters; a sequence of two bytes which is treated as one character in multibyte representation will count as two characters in unibyte representation.

This function sets enable-multibyte-characters to record which representation is in use. It also adjusts various data in the buffer (including overlays, text properties and markers) so that they cover the same text as they did before.

Function: string-as-unibyte string
This function returns a string with the same bytes as string but treating each byte as a character. This means that the value may have more characters than string has.

If string is unibyte already, then the value is string itself.

Function: string-as-multibyte string
This function returns a string with the same bytes as string but treating each multibyte sequence as one character. This means that the value may have fewer characters than string has.

If string is multibyte already, then the value is string itself.

Character Codes

The unibyte and multibyte text representations use different character codes. The valid character codes for unibyte representation range from 0 to 255--the values that can fit in one byte. The valid character codes for multibyte representation range from 0 to 524287, but not all values in that range are valid. In particular, the values 128 through 255 are not legitimate in multibyte text (though they can occur in "raw bytes"; see section Explicit Encoding and Decoding). Only the ASCII codes 0 through 127 are fully legitimate in both representations.

Function: char-valid-p charcode
This returns t if charcode is valid for either one of the two text representations.
(char-valid-p 65)
     => t
(char-valid-p 256)
     => nil
(char-valid-p 2248)
     => t
Character Sets

Emacs classifies characters into various character sets, each of which has a name which is a symbol. Each character belongs to one and only one character set.

In general, there is one character set for each distinct script. For example, latin-iso8859-1 is one character set, greek-iso8859-7 is another, and ascii is another. An Emacs character set can hold at most 9025 characters; therefore, in some cases, characters that would logically be grouped together are split into several character sets. For example, one set of Chinese characters, generally known as Big 5, is divided into two Emacs character sets, chinese-big5-1 and chinese-big5-2.

Function: charsetp object
Return t if object is a character set name symbol, nil otherwise.

Function: charset-list
This function returns a list of all defined character set names.

Function: char-charset character
This function returns the name of the character set that character belongs to.

Characters and Bytes

In multibyte representation, each character occupies one or more bytes. Each character set has an introduction sequence, which is normally one or two bytes long. (Exception: the ASCII character set has a zero-length introduction sequence.) The introduction sequence is the beginning of the byte sequence for any character in the character set. The rest of the character's bytes distinguish it from the other characters in the same character set. Depending on the character set, there are either one or two distinguishing bytes; the number of such bytes is called the dimension of the character set.

Function: charset-dimension charset
This function returns the dimension of charset; at present, the dimension is always 1 or 2.

This is the simplest way to determine the byte length of a character set's introduction sequence:
(- (char-bytes (make-char charset))
   (charset-dimension charset))
Splitting Characters

The functions in this section convert between characters and the byte values used to represent them. For most purposes, there is no need to be concerned with the sequence of bytes used to represent a character, because Emacs translates automatically when necessary.

Function: char-bytes character
This function returns the number of bytes used to represent the character character. This depends only on the character set that character belongs to; it equals the dimension of that character set (see section Character Sets), plus the length of its introduction sequence.
(char-bytes 2248)
     => 2
(char-bytes 65)
     => 1
(char-bytes 192)
     => 1
The reason this function can give correct results for both multibyte and unibyte representations is that the non-ASCII character codes used in those two representations do not overlap.

Function: split-char character
Return a list containing the name of the character set of character, followed by one or two byte values (integers) which identify character within that character set. The number of byte values is the character set's dimension.
(split-char 2248)
     => (latin-iso8859-1 72)
(split-char 65)
     => (ascii 65)
Unibyte non-ASCII characters are considered as part of the ascii character set:
(split-char 192)
     => (ascii 192)
Function: make-char charset &rest byte-values
This function returns the character in character set charset identified by byte-values. This is roughly the inverse of split-char. Normally, you should specify either one or two byte-values, according to the dimension of charset. For example,
(make-char 'latin-iso8859-1 72)
     => 2248
If you call make-char with no byte-values, the result is a generic character which stands for charset. A generic character is an integer, but it is not valid for insertion in the buffer as a character. It can be used in char-table-range to refer to the whole character set (see section Char-Tables). char-valid-p returns nil for generic characters. For example:
(make-char 'latin-iso8859-1)
     => 2176
(char-valid-p 2176)
     => nil
(split-char 2176)
     => (latin-iso8859-1 0)
Scanning for Character Sets

Sometimes it is useful to find out which character sets appear in a part of a buffer or a string. One use for this is in determining which coding systems (see section Coding Systems) are capable of representing all of the text in question.

Function: find-charset-region beg end &optional translation
This function returns a list of the character sets that appear in the current buffer between positions beg and end.

The optional argument translation specifies a translation table to be used in scanning the text (see section Translation of Characters). If it is non-nil, then each character in the region is translated through this table, and the value returned describes the translated characters instead of the characters actually in the buffer.

Function: find-charset-string string &optional translation
This function returns a list of the character sets that appear in the string string.

The optional argument translation specifies a translation table; see find-charset-region, above.

Translation of Characters

A translation table specifies a mapping of characters into characters. These tables are used in encoding and decoding, and for other purposes. Some coding systems specify their own particular translation tables; there are also default translation tables which apply to all other coding systems.

Function: make-translation-table translations
This function returns a translation table based on the arguments translations. Each argument--each element of translations---should be a list of the form (from . to); this says to translate the character from into to.

You can also map one whole character set into another character set with the same dimension. To do this, you specify a generic character (which designates a character set) for from (see section Splitting Characters). In this case, to should also be a generic character, for another character set of the same dimension. Then the translation table translates each character of from's character set into the corresponding character of to's character set.

In decoding, the translation table's translations are applied to the characters that result from ordinary decoding. If a coding system has property character-translation-table-for-decode, that specifies the translation table to use. Otherwise, if standard-character-translation-table-for-decode is non-nil, decoding uses that table.

In encoding, the translation table's translations are applied to the characters in the buffer, and the result of translation is actually encoded. If a coding system has property character-translation-table-for-encode, that specifies the translation table to use. Otherwise the variable standard-character-translation-table-for-encode specifies the translation table.

Variable: standard-character-translation-table-for-decode
This is the default translation table for decoding, for coding systems that don't specify any other translation table.

Variable: standard-character-translation-table-for-encode
This is the default translation table for encoding, for coding systems that don't specify any other translation table.

Coding Systems

When Emacs reads or writes a file, and when Emacs sends text to a subprocess or receives text from a subprocess, it normally performs character code conversion and end-of-line conversion as specified by a particular coding system.

Basic Concepts of Coding Systems

Character code conversion involves conversion between the encoding used inside Emacs and some other encoding. Emacs supports many different encodings, in that it can convert to and from them. For example, it can convert text to or from encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and several variants of ISO 2022. In some cases, Emacs supports several alternative encodings for the same characters; for example, there are three coding systems for the Cyrillic (Russian) alphabet: ISO, Alternativnyj, and KOI8.

Most coding systems specify a particular character code for conversion, but some of them leave this unspecified--to be chosen heuristically based on the data.

End of line conversion handles three different conventions used on various systems for representing end of line in files. The Unix convention is to use the linefeed character (also called newline). The DOS convention is to use the two character sequence, carriage-return linefeed, at the end of a line. The Mac convention is to use just carriage-return.

Base coding systems such as latin-1 leave the end-of-line conversion unspecified, to be chosen based on the data. Variant coding systems such as latin-1-unix, latin-1-dos and latin-1-mac specify the end-of-line conversion explicitly as well. Most base coding systems have three corresponding variants whose names are formed by adding `-unix', `-dos' and `-mac'.

The coding system raw-text is special in that it prevents character code conversion, and causes the buffer visited with that coding system to be a unibyte buffer. It does not specify the end-of-line conversion, allowing that to be determined as usual by the data, and has the usual three variants which specify the end-of-line conversion. no-conversion is equivalent to raw-text-unix: it specifies no conversion of either character codes or end-of-line.

The coding system emacs-mule specifies that the data is represented in the internal Emacs encoding. This is like raw-text in that no code conversion happens, but different in that the result is multibyte data.

Function: coding-system-get coding-system property
This function returns the specified property of the coding system coding-system. Most coding system properties exist for internal purposes, but one that you might find useful is mime-charset. That property's value is the name used in MIME for the character coding which this coding system can read and write. Examples:
(coding-system-get 'iso-latin-1 'mime-charset)
     => iso-8859-1
(coding-system-get 'iso-2022-cn 'mime-charset)
     => iso-2022-cn
(coding-system-get 'cyrillic-koi8 'mime-charset)
     => koi8-r
The value of the mime-charset property is also defined as an alias for the coding system.

Encoding and I/O

The principal purpose of coding systems is for use in reading and writing files. The function insert-file-contents uses a coding system for decoding the file data, and write-region uses one to encode the buffer contents.

You can specify the coding system to use either explicitly (see section Specifying a Coding System for One Operation), or implicitly using the defaulting mechanism (see section Default Coding Systems). But these methods may not completely specify what to do. For example, they may choose a coding system such as undefined which leaves the character code conversion to be determined from the data. In these cases, the I/O operation finishes the job of choosing a coding system. Very often you will want to find out afterwards which coding system was chosen.

Variable: buffer-file-coding-system
This variable records the coding system that was used for visiting the current buffer. It is used for saving the buffer, and for writing part of the buffer with write-region. When those operations ask the user to specify a different coding system, buffer-file-coding-system is updated to the coding system specified.

Variable: save-buffer-coding-system
This variable specifies the coding system for saving the buffer--but it is not used for write-region. When saving the buffer asks the user to specify a different coding system, and save-buffer-coding-system was used, then it is updated to the coding system that was specified.

Variable: last-coding-system-used
I/O operations for files and subprocesses set this variable to the coding system name that was used. The explicit encoding and decoding functions (see section Explicit Encoding and Decoding) set it too.

Warning: Since receiving subprocess output sets this variable, it can change whenever Emacs waits; therefore, you should use copy the value shortly after the function call which stores the value you are interested in.

The variable selection-coding-system specifies how to encode selections for the window system. See section Window System Selections.

Coding Systems in Lisp

Here are Lisp facilities for working with coding systems;

Function: coding-system-list &optional base-only
This function returns a list of all coding system names (symbols). If base-only is non-nil, the value includes only the base coding systems. Otherwise, it includes variant coding systems as well.

Function: coding-system-p object
This function returns t if object is a coding system name.

Function: check-coding-system coding-system
This function checks the validity of coding-system. If that is valid, it returns coding-system. Otherwise it signals an error with condition coding-system-error.

Function: coding-system-change-eol-conversion coding-system eol-type
This function returns a coding system which is like coding-system except for its eol conversion, which is specified by eol-type. eol-type should be unix, dos, mac, or nil. If it is nil, the returned coding system determines the end-of-line conversion from the data.

Function: coding-system-change-text-conversion eol-coding text-coding
This function returns a coding system which uses the end-of-line conversion of eol-coding, and the text conversion of text-coding. If text-coding is nil, it returns undecided, or one of its variants according to eol-coding.

Function: find-coding-systems-region from to
This function returns a list of coding systems that could be used to encode a text between from and to. All coding systems in the list can safely encode any multibyte characters in that portion of the text.

If the text contains no multibyte characters, the function returns the list (undecided).

Function: find-coding-systems-string string
This function returns a list of coding systems that could be used to encode the text of string. All coding systems in the list can safely encode any multibyte characters in string. If the text contains no multibyte characters, this returns the list (undecided).

Function: find-coding-systems-for-charsets charsets
This function returns a list of coding systems that could be used to encode all the character sets in the list charsets.

Function: detect-coding-region start end &optional highest
This function chooses a plausible coding system for decoding the text from start to end. This text should be "raw bytes" (see section Explicit Encoding and Decoding).

Normally this function returns a list of coding systems that could handle decoding the text that was scanned. They are listed in order of decreasing priority. But if highest is non-nil, then the return value is just one coding system, the one that is highest in priority.

If the region contains only ASCII characters, the value is undecided or (undecided).

Function: detect-coding-string string highest
This function is like detect-coding-region except that it operates on the contents of string instead of bytes in the buffer.

See section Process Information, for how to examine or set the coding systems used for I/O to a subprocess.

User-Chosen Coding Systems

Function: select-safe-coding-system from to &optional preferred-coding-system
This function selects a coding system for encoding the text between from and to, asking the user to choose if necessary.

The optional argument preferred-coding-system specifies a coding system to try first. If that one can handle the text in the specified region, then it is used. If this argument is omitted, the current buffer's value of buffer-file-coding-system is tried first.

If the region contains some multibyte characters that the preferred coding system cannot encode, this function asks the user to choose from a list of coding systems which can encode the text, and returns the user's choice.

One other kludgy feature: if from is a string, the string is the target text, and to is ignored.

Here are two functions you can use to let the user specify a coding system, with completion. See section Completion.

Function: read-coding-system prompt &optional default
This function reads a coding system using the minibuffer, prompting with string prompt, and returns the coding system name as a symbol. If the user enters null input, default specifies which coding system to return. It should be a symbol or a string.

Function: read-non-nil-coding-system prompt
This function reads a coding system using the minibuffer, prompting with string prompt, and returns the coding system name as a symbol. If the user tries to enter null input, it asks the user to try again. See section Coding Systems.

Default Coding Systems

This section describes variables that specify the default coding system for certain files or when running certain subprograms, and the function that I/O operations use to access them.

The idea of these variables is that you set them once and for all to the defaults you want, and then do not change them again. To specify a particular coding system for a particular operation in a Lisp program, don't change these variables; instead, override them using coding-system-for-read and coding-system-for-write (see section Specifying a Coding System for One Operation).

Variable: file-coding-system-alist
This variable is an alist that specifies the coding systems to use for reading and writing particular files. Each element has the form (pattern . coding), where pattern is a regular expression that matches certain file names. The element applies to file names that match pattern.

The CDR of the element, coding, should be either a coding system, a cons cell containing two coding systems, or a function symbol. If val is a coding system, that coding system is used for both reading the file and writing it. If val is a cons cell containing two coding systems, its CAR specifies the coding system for decoding, and its CDR specifies the coding system for encoding.

If val is a function symbol, the function must return a coding system or a cons cell containing two coding systems. This value is used as described above.

Variable: process-coding-system-alist
This variable is an alist specifying which coding systems to use for a subprocess, depending on which program is running in the subprocess. It works like file-coding-system-alist, except that pattern is matched against the program name used to start the subprocess. The coding system or systems specified in this alist are used to initialize the coding systems used for I/O to the subprocess, but you can specify other coding systems later using set-process-coding-system.

Warning: Coding systems such as undecided which determine the coding system from the data do not work entirely reliably with asynchronous subprocess output. This is because Emacs handles asynchronous subprocess output in batches, as it arrives. If the coding system leaves the character code conversion unspecified, or leaves the end-of-line conversion unspecified, Emacs must try to detect the proper conversion from one batch at a time, and this does not always work.

Therefore, with an asynchronous subprocess, if at all possible, use a coding system which determines both the character code conversion and the end of line conversion--that is, one like latin-1-unix, rather than undecided or latin-1.

Variable: network-coding-system-alist
This variable is an alist that specifies the coding system to use for network streams. It works much like file-coding-system-alist, with the difference that the pattern in an element may be either a port number or a regular expression. If it is a regular expression, it is matched against the network service name used to open the network stream.

Variable: default-process-coding-system
This variable specifies the coding systems to use for subprocess (and network stream) input and output, when nothing else specifies what to do.

The value should be a cons cell of the form (input-coding . output-coding). Here input-coding applies to input from the subprocess, and output-coding applies to output to it.

Function: find-operation-coding-system operation &rest arguments
This function returns the coding system to use (by default) for performing operation with arguments. The value has this form:
(decoding-system encoding-system)
The first element, decoding-system, is the coding system to use for decoding (in case operation does decoding), and encoding-system is the coding system for encoding (in case operation does encoding).

The argument operation should be an Emacs I/O primitive: insert-file-contents, write-region, call-process, call-process-region, start-process, or open-network-stream.

The remaining arguments should be the same arguments that might be given to that I/O primitive. Depending on which primitive, one of those arguments is selected as the target. For example, if operation does file I/O, whichever argument specifies the file name is the target. For subprocess primitives, the process name is the target. For open-network-stream, the target is the service name or port number.

This function looks up the target in file-coding-system-alist, process-coding-system-alist, or network-coding-system-alist, depending on operation. See section Default Coding Systems.

Specifying a Coding System for One Operation

You can specify the coding system for a specific operation by binding the variables coding-system-for-read and/or coding-system-for-write.

Variable: coding-system-for-read
If this variable is non-nil, it specifies the coding system to use for reading a file, or for input from a synchronous subprocess.

It also applies to any asynchronous subprocess or network stream, but in a different way: the value of coding-system-for-read when you start the subprocess or open the network stream specifies the input decoding method for that subprocess or network stream. It remains in use for that subprocess or network stream unless and until overridden.

The right way to use this variable is to bind it with let for a specific I/O operation. Its global value is normally nil, and you should not globally set it to any other value. Here is an example of the right way to use the variable:
;; Read the file with no character code conversion.
;; Assume CRLF represents end-of-line.
(let ((coding-system-for-write 'emacs-mule-dos))
  (insert-file-contents filename))
When its value is non-nil, coding-system-for-read takes precedence over all other methods of specifying a coding system to use for input, including file-coding-system-alist, process-coding-system-alist and network-coding-system-alist.

Variable: coding-system-for-write
This works much like coding-system-for-read, except that it applies to output rather than input. It affects writing to files, subprocesses, and net connections.

When a single operation does both input and output, as do call-process-region and start-process, both coding-system-for-read and coding-system-for-write affect it.

Variable: inhibit-eol-conversion
When this variable is non-nil, no end-of-line conversion is done, no matter which coding system is specified. This applies to all the Emacs I/O and subprocess primitives, and to the explicit encoding and decoding functions (see section Explicit Encoding and Decoding).

Explicit Encoding and Decoding

All the operations that transfer text in and out of Emacs have the ability to use a coding system to encode or decode the text. You can also explicitly encode and decode text using the functions in this section.

The result of encoding, and the input to decoding, are not ordinary text. They are "raw bytes"---bytes that represent text in the same way that an external file would. When a buffer contains raw bytes, it is most natural to mark that buffer as using unibyte representation, using set-buffer-multibyte (see section Selecting a Representation), but this is not required. If the buffer's contents are only temporarily raw, leave the buffer multibyte, which will be correct after you decode them.

The usual way to get raw bytes in a buffer, for explicit decoding, is to read them from a file with insert-file-contents-literally (see section Reading from Files) or specify a non-nil rawfile argument when visiting a file with find-file-noselect.

The usual way to use the raw bytes that result from explicitly encoding text is to copy them to a file or process--for example, to write them with write-region (see section Writing to Files), and suppress encoding for that write-region call by binding coding-system-for-write to no-conversion.

Raw bytes sometimes contain overlong byte-sequences that look like a proper multibyte character plus extra bytes containing trailing codes. For most purposes, Emacs treats such a sequence in a buffer or string as a single character, and if you look at its character code, you get the value that corresponds to the multibyte character sequence--the extra bytes are disregarded. This behavior is not quite clean, but raw bytes are used only in limited places in Emacs, so as a practical matter problems can be avoided.

Function: encode-coding-region start end coding-system
This function encodes the text from start to end according to coding system coding-system. The encoded text replaces the original text in the buffer. The result of encoding is "raw bytes," but the buffer remains multibyte if it was multibyte before.

Function: encode-coding-string string coding-system
This function encodes the text in string according to coding system coding-system. It returns a new string containing the encoded text. The result of encoding is a unibyte string of "raw bytes."

Function: decode-coding-region start end coding-system
This function decodes the text from start to end according to coding system coding-system. The decoded text replaces the original text in the buffer. To make explicit decoding useful, the text before decoding ought to be "raw bytes."

Function: decode-coding-string string coding-system
This function decodes the text in string according to coding system coding-system. It returns a new string containing the decoded text. To make explicit decoding useful, the contents of string ought to be "raw bytes."

Terminal I/O Encoding

Emacs can decode keyboard input using a coding system, and encode terminal output. This is useful for terminals that transmit or display text using a particular encoding such as Latin-1. Emacs does not set last-coding-system-used for encoding or decoding for the terminal.

Function: keyboard-coding-system
This function returns the coding system that is in use for decoding keyboard input--or nil if no coding system is to be used.

Function: set-keyboard-coding-system coding-system
This function specifies coding-system as the coding system to use for decoding keyboard input. If coding-system is nil, that means do not decode keyboard input.

Function: terminal-coding-system
This function returns the coding system that is in use for encoding terminal output--or nil for no encoding.

Function: set-terminal-coding-system coding-system
This function specifies coding-system as the coding system to use for encoding terminal output. If coding-system is nil, that means do not encode terminal output.

MS-DOS File Types

Emacs on MS-DOS and on MS-Windows recognizes certain file names as text files or binary files. By "binary file" we mean a file of literal byte values that are not necessary meant to be characters. Emacs does no end-of-line conversion and no character code conversion for a binary file. Meanwhile, when you create a new file which is marked by its name as a "text file", Emacs uses DOS end-of-line conversion.

Variable: buffer-file-type
This variable, automatically buffer-local in each buffer, records the file type of the buffer's visited file. When a buffer does not specify a coding system with buffer-file-coding-system, this variable is used to determine which coding system to use when writing the contents of the buffer. It should be nil for text, t for binary. If it is t, the coding system is no-conversion. Otherwise, undecided-dos is used.

Normally this variable is set by visiting a file; it is set to nil if the file was visited without any actual conversion.

User Option: file-name-buffer-file-type-alist
This variable holds an alist for recognizing text and binary files. Each element has the form (regexp . type), where regexp is matched against the file name, and type may be nil for text, t for binary, or a function to call to compute which. If it is a function, then it is called with a single argument (the file name) and should return t or nil.

Emacs when running on MS-DOS or MS-Windows checks this alist to decide which coding system to use when reading a file. For a text file, undecided-dos is used. For a binary file, no-conversion is used.

If no element in this alist matches a given file name, then default-buffer-file-type says how to treat the file.

User Option: default-buffer-file-type
This variable says how to handle files for which file-name-buffer-file-type-alist says nothing about the type.

If this variable is non-nil, then these files are treated as binary: the coding system no-conversion is used. Otherwise, nothing special is done for them--the coding system is deduced solely from the file contents, in the usual Emacs fashion.

Input Methods

Input methods provide convenient ways of entering non-ASCII characters from the keyboard. Unlike coding systems, which translate non-ASCII characters to and from encodings meant to be read by programs, input methods provide human-friendly commands. (See section `Input Methods' in The GNU Emacs Manual, for information on how users use input methods to enter text.) How to define input methods is not yet documented in this manual, but here we describe how to use them.

Each input method has a name, which is currently a string; in the future, symbols may also be usable as input method names.

Variable: current-input-method
This variable holds the name of the input method now active in the current buffer. (It automatically becomes local in each buffer when set in any fashion.) It is nil if no input method is active in the buffer now.

Variable: default-input-method
This variable holds the default input method for commands that choose an input method. Unlike current-input-method, this variable is normally global.

Function: set-input-method input-method
This function activates input method input-method for the current buffer. It also sets default-input-method to input-method. If input-method is nil, this function deactivates any input method for the current buffer.

Function: read-input-method-name prompt &optional default inhibit-null
This function reads an input method name with the minibuffer, prompting with prompt. If default is non-nil, that is returned by default, if the user enters empty input. However, if inhibit-null is non-nil, empty input signals an error.

The returned value is a string.

Variable: input-method-alist
This variable defines all the supported input methods. Each element defines one input method, and should have the form:
(input-method language-env activate-func
 title description args...)
Here input-method is the input method name, a string; language-env is another string, the name of the language environment this input method is recommended for. (That serves only for documentation purposes.)

title is a string to display in the mode line while this method is active. description is a string describing this method and what it is good for.

activate-func is a function to call to activate this method. The args, if any, are passed as arguments to activate-func. All told, the arguments to activate-func are input-method and the args.

The fundamental interface to input methods is through the variable input-method-function. See section Reading One Event.

Searching and Matching

GNU Emacs provides two ways to search through a buffer for specified text: exact string searches and regular expression searches. After a regular expression search, you can examine the match data to determine which text matched the whole regular expression or various portions of it.

The `skip-chars...' functions also perform a kind of searching. See section Skipping Characters.

Searching for Strings

These are the primitive functions for searching through the text in a buffer. They are meant for use in programs, but you may call them interactively. If you do so, they prompt for the search string; limit and noerror are set to nil, and repeat is set to 1.

These search functions convert the search string to multibyte if the buffer is multibyte; they convert the search string to unibyte if the buffer is unibyte. See section Text Representations.

Command: search-forward string &optional limit noerror repeat
This function searches forward from point for an exact match for string. If successful, it sets point to the end of the occurrence found, and returns the new value of point. If no match is found, the value and side effects depend on noerror (see below).

In the following example, point is initially at the beginning of the line. Then (search-forward "fox") moves point after the last letter of `fox':
---------- Buffer: foo ----------
-!-The quick brown fox jumped over the lazy dog.
---------- Buffer: foo ----------

(search-forward "fox")
     => 20

---------- Buffer: foo ----------
The quick brown fox-!- jumped over the lazy dog.
---------- Buffer: foo ----------
The argument limit specifies the upper bound to the search. (It must be a position in the current buffer.) No match extending after that position is accepted. If limit is omitted or nil, it defaults to the end of the accessible portion of the buffer.

What happens when the search fails depends on the value of noerror. If noerror is nil, a search-failed error is signaled. If noerror is t, search-forward returns nil and does nothing. If noerror is neither nil nor t, then search-forward moves point to the upper bound and returns nil. (It would be more consistent now to return the new position of point in that case, but some existing programs may depend on a value of nil.)

If repeat is supplied (it must be a positive number), then the search is repeated that many times (each time starting at the end of the previous time's match). If these successive searches succeed, the function succeeds, moving point and returning its new value. Otherwise the search fails.

Command: search-backward string &optional limit noerror repeat
This function searches backward from point for string. It is just like search-forward except that it searches backwards and leaves point at the beginning of the match.

Command: word-search-forward string &optional limit noerror repeat
This function searches forward from point for a "word" match for string. If it finds a match, it sets point to the end of the match found, and returns the new value of point.

Word matching regards string as a sequence of words, disregarding punctuation that separates them. It searches the buffer for the same sequence of words. Each word must be distinct in the buffer (searching for the word `ball' does not match the word `balls'), but the details of punctuation and spacing are ignored (searching for `ball boy' does match `ball. Boy!').

In this example, point is initially at the beginning of the buffer; the search leaves it between the `y' and the `!'.
---------- Buffer: foo ----------
-!-He said "Please!  Find
the ball boy!"
---------- Buffer: foo ----------

(word-search-forward "Please find the ball, boy.")
     => 35

---------- Buffer: foo ----------
He said "Please!  Find
the ball boy-!-!"
---------- Buffer: foo ----------
If limit is non-nil (it must be a position in the current buffer), then it is the upper bound to the search. The match found must not extend after that position.

If noerror is nil, then word-search-forward signals an error if the search fails. If noerror is t, then it returns nil instead of signaling an error. If noerror is neither nil nor t, it moves point to limit (or the end of the buffer) and returns nil.

If repeat is non-nil, then the search is repeated that many times. Point is positioned at the end of the last match.

Command: word-search-backward string &optional limit noerror repeat
This function searches backward from point for a word match to string. This function is just like word-search-forward except that it searches backward and normally leaves point at the beginning of the match.

Regular Expressions

A regular expression (regexp, for short) is a pattern that denotes a (possibly infinite) set of strings. Searching for matches for a regexp is a very powerful operation. This section explains how to write regexps; the following section says how to search for them.

Syntax of Regular Expressions

Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character is a simple regular expression that matches that character and nothing else. The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and `\'; no new special characters will be defined in the future. Any other character appearing in a regular expression is ordinary, unless a `\' precedes it.

For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does not match the string `ff'.) Likewise, `o' is a regular expression that matches only `o'.

Any two regular expressions a and b can be concatenated. The result is a regular expression that matches a string if a matches some amount of the beginning of that string and b matches the rest of the string.

As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial. To do something more powerful, you need to use one of the special characters. Here is a list of them:

`.' (Period)
is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like `a.b', which matches any three-character string that begins with `a' and ends with `b'.
`*'
is not a construct by itself; it is a postfix operator that means to match the preceding regular expression repetitively as many times as possible. Thus, `o*' matches any number of `o's (including no `o's). `*' always applies to the smallest possible preceding expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. It matches `f', `fo', `foo', and so on. The matcher processes a `*' construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the `*'-modified construct in the hope that that will make it possible to match the rest of the pattern. For example, in matching `ca*ar' against the string `caaar', the `a*' first tries to match all three `a's; but the rest of the pattern is `ar' and there is only `r' left to match, so this try fails. The next alternative is for `a*' to match only two `a's. With this choice, the rest of the regexp matches successfully. Nested repetition operators can be extremely slow if they specify backtracking loops. For example, it could take hours for the regular expression `\(x+y*\)*a' to try to match the sequence `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz', before it ultimately fails. The slowness is because Emacs must try each imaginable way of grouping the 35 `x's before concluding that none of them can work. To make sure your regular expressions run fast, check nested repetitions carefully.
`+'
is a postfix operator, similar to `*' except that it must match the preceding expression at least once. So, for example, `ca+r' matches the strings `car' and `caaaar' but not the string `cr', whereas `ca*r' matches all three strings.
`?'
is a postfix operator, similar to `*' except that it must match the preceding expression either once or not at all. For example, `ca?r' matches `car' or `cr'; nothing else.
`[ ... ]'
is a character alternative, which begins with `[' and is terminated by `]'. In the simplest case, the characters between the two brackets are what this character alternative can match. Thus, `[ad]' matches either one `a' or one `d', and `[ad]*' matches any string composed of just `a's and `d's (including the empty string), from which it follows that `c[ad]*r' matches `cr', `car', `cdr', `caddaar', etc. You can also include character ranges in a character alternative, by writing the starting and ending characters with a `-' between them. Thus, `[a-z]' matches any lower-case ASCII letter. Ranges may be intermixed freely with individual characters, as in `[a-z$%.]', which matches any lower case ASCII letter or `$', `%' or period. You cannot always match all non-ASCII characters with the regular expression `[\200-\377]'. This works when searching a unibyte buffer or string (see section Text Representations), but not in a multibyte buffer or string, because many non-ASCII characters have codes above octal 0377. However, the regular expression `[^\000-\177]' does match all non-ASCII characters, in both multibyte and unibyte representations, because only the ASCII characters are excluded. The beginning and end of a range must be in the same character set (see section Character Sets). Thus, `[a-\x8e0]' is invalid because `a' is in the ASCII character set but the character 0x8e0 (`a' with grave accent) is in the Emacs character set for Latin-1. Note that the usual regexp special characters are not special inside a character alternative. A completely different set of characters are special inside character alternatives: `]', `-' and `^'. To include a `]' in a character alternative, you must make it the first character. For example, `[]a]' matches `]' or `a'. To include a `-', write `-' as the first or last character of the character alternative, or put it after a range. Thus, `[]-]' matches both `]' and `-'. To include `^' in a character alternative, put it anywhere but at the beginning.
`[^ ... ]'
`[^' begins a complemented character alternative, which matches any character except the ones specified. Thus, `[^a-z0-9A-Z]' matches all characters except letters and digits. `^' is not special in a character alternative unless it is the first character. The character following the `^' is treated as if it were first (in other words, `-' and `]' are not special there). A complemented character alternative can match a newline, unless newline is mentioned as one of the characters not to match. This is in contrast to the handling of regexps in programs such as grep.
`^'
is a special character that matches the empty string, but only at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, `^foo' matches a `foo' that occurs at the beginning of a line. When matching a string instead of a buffer, `^' matches at the beginning of the string or after a newline character `\n'.
`$'
is similar to `^' but matches only at the end of a line. Thus, `x+$' matches a string of one `x' or more at the end of a line. When matching a string instead of a buffer, `$' matches at the end of the string or before a newline character `\n'.
`\'
has two functions: it quotes the special characters (including `\'), and it introduces additional special constructs. Because `\' quotes special characters, `\$' is a regular expression that matches only `$', and `\[' is a regular expression that matches only `[', and so on. Note that `\' also has special meaning in the read syntax of Lisp strings (see section String Type), and must be quoted with `\'. For example, the regular expression that matches the `\' character is `\\'. To write a Lisp string that contains the characters `\\', Lisp syntax requires you to quote each `\' with another `\'. Therefore, the read syntax for a regular expression matching `\' is "\\\\".
Please note: For historical compatibility, special characters are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, `*foo' treats `*' as ordinary since there is no preceding expression on which the `*' can act. It is poor practice to depend on this behavior; quote the special character anyway, regardless of where it appears.

For the most part, `\' followed by any character matches only that character. However, there are several exceptions: two-character sequences starting with `\' which have special meanings. (The second character in such a sequence is always ordinary when used on its own.) Here is a table of `\' constructs.

`\|'
specifies an alternative. Two regular expressions a and b with `\|' in between form an expression that matches anything that either a or b matches. Thus, `foo\|bar' matches either `foo' or `bar' but no other string. `\|' applies to the largest possible surrounding expressions. Only a surrounding `\( ... \)' grouping can limit the grouping power of `\|'. Full backtracking capability exists to handle multiple uses of `\|'.
`\( ... \)'
is a grouping construct that serves three purposes:

To enclose a set of `\|' alternatives for other operations. Thus, the regular expression `\(foo\|bar\)x' matches either `foox' or `barx'.
To enclose a complicated expression for the postfix operators `*', `+' and `?' to operate on. Thus, `ba\(na\)*' matches `ba', `bana', `banana', `bananana', etc., with any number (zero or more) of `na' strings.
To record a matched substring for future reference.
This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that happens to be assigned as a second meaning to the same `\( ... \)' construct because there is no conflict in practice between the two meanings. Here is an explanation of this feature:
`\digit'
matches the same text that matched the digitth occurrence of a `\( ... \)' construct. In other words, after the end of a `\( ... \)' construct, the matcher remembers the beginning and end of the text matched by that construct. Then, later on in the regular expression, you can use `\' followed by digit to match that same text, whatever it may have been. The strings matching the first nine `\( ... \)' constructs appearing in a regular expression are assigned numbers 1 through 9 in the order that the open parentheses appear in the regular expression. So you can use `\1' through `\9' to refer to the text matched by the corresponding `\( ... \)' constructs. For example, `\(.*\)\1' matches any newline-free string that is composed of two identical halves. The `\(.*\)' matches the first half, which may be anything, but the `\1' that follows must match the same exact text.
`\w'
matches any word-constituent character. The editor syntax table determines which characters these are. See section Syntax Tables.
`\W'
matches any character that is not a word constituent.
`\scode'
matches any character whose syntax is code. Here code is a character that represents a syntax code: thus, `w' for word constituent, `-' for whitespace, `(' for open parenthesis, etc. To represent whitespace syntax, use either `-' or a space character. See section Table of Syntax Classes, for a list of syntax codes and the characters that stand for them.
`\Scode'
matches any character whose syntax is not code.
The following regular expression constructs match the empty string--that is, they don't use up any characters--but whether they match depends on the context.

`\`'
matches the empty string, but only at the beginning of the buffer or string being matched against.
`\''
matches the empty string, but only at the end of the buffer or string being matched against.
`\='
matches the empty string, but only at point. (This construct is not defined when matching against a string.)
`\b'
matches the empty string, but only at the beginning or end of a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a separate word. `\bballs?\b' matches `ball' or `balls' as a separate word. `\b' matches at the beginning or end of the buffer regardless of what text appears next to it.
`\B'
matches the empty string, but not at the beginning or end of a word.
`\<'
matches the empty string, but only at the beginning of a word. `\<' matches at the beginning of the buffer only if a word-constituent character follows.
`\>'
matches the empty string, but only at the end of a word. `\>' matches at the end of the buffer only if the contents end with a word-constituent character.
Not every string is a valid regular expression. For example, a string with unbalanced square brackets is invalid (with a few exceptions, such as `[]]'), and so is a string that ends with a single `\'. If an invalid regular expression is passed to any of the search functions, an invalid-regexp error is signaled.

Function: regexp-quote string
This function returns a regular expression string that matches exactly string and nothing else. This allows you to request an exact string match when calling a function that wants a regular expression.
(regexp-quote "^The cat$")
     => "\\^The cat\\$"
One use of regexp-quote is to combine an exact string match with context described as a regular expression. For example, this searches for the string that is the value of string, surrounded by whitespace:
(re-search-forward
 (concat "\\s-" (regexp-quote string) "\\s-"))
Function: regexp-opt strings &optional paren
This function returns an efficient regular expression that will match any of the strings strings. This is useful when you need to make matching or searching as fast as possible--for example, for Font Lock mode.

If the optional argument paren is non-nil, then the returned regular expression is always enclosed by at least one parentheses-grouping construct.

This simplified definition of regexp-opt produces a regular expression which is equivalent to the actual value (but not as efficient):
(defun regexp-opt (strings paren)
  (let ((open-paren (if paren "\\(" ""))
        (close-paren (if paren "\\)" "")))
    (concat open-paren
            (mapconcat 'regexp-quote strings "\\|")
            close-paren)))
Function: regexp-opt-depth regexp
This function returns the total number of grouping constructs (parenthesized expressions) in regexp.

Complex Regexp Example

Here is a complicated regexp, used by Emacs to recognize the end of a sentence together with any whitespace that follows. It is the value of the variable sentence-end.

First, we show the regexp as a string in Lisp syntax to distinguish spaces from tab characters. The string constant begins and ends with a double-quote. `\"' stands for a double-quote as part of the string, `\\' for a backslash as part of the string, `\t' for a tab and `\n' for a newline.
"[.?!][]\"')}]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
In contrast, if you evaluate the variable sentence-end, you will see the following:
sentence-end
     => "[.?!][]\"')}]*\\($\\| $\\|  \\|  \\)[
]*"
In this output, tab and newline appear as themselves.

This regular expression contains four parts in succession and can be deciphered as follows:

[.?!]
The first part of the pattern is a character alternative that matches any one of three characters: period, question mark, and exclamation mark. The match must begin with one of these three characters.
[]\"')}]*
The second part of the pattern matches any closing braces and quotation marks, zero or more of them, that may follow the period, question mark or exclamation mark. The \" is Lisp syntax for a double-quote in a string. The `*' at the end indicates that the immediately preceding regular expression (a character alternative, in this case) may be repeated zero or more times.
\\($\\| $\\|\t\\| \\)
The third part of the pattern matches the whitespace that follows the end of a sentence: the end of a line (optionally with a space), or a tab, or two spaces. The double backslashes mark the parentheses and vertical bars as regular expression syntax; the parentheses delimit a group and the vertical bars separate alternatives. The dollar sign is used to match the end of a line.
[ \t\n]*
Finally, the last part of the pattern matches any additional whitespace beyond the minimum needed to end a sentence.
Regular Expression Searching

In GNU Emacs, you can search for the next match for a regular expression either incrementally or not. For incremental search commands, see section `Regular Expression Search' in The GNU Emacs Manual. Here we describe only the search functions useful in programs. The principal one is re-search-forward.

These search functions convert the regular expression to multibyte if the buffer is multibyte; they convert the regular expression to unibyte if the buffer is unibyte. See section Text Representations.

Command: re-search-forward regexp &optional limit noerror repeat
This function searches forward in the current buffer for a string of text that is matched by the regular expression regexp. The function skips over any amount of text that is not matched by regexp, and leaves point at the end of the first match found. It returns the new value of point.

If limit is non-nil (it must be a position in the current buffer), then it is the upper bound to the search. No match extending after that position is accepted.

If repeat is supplied (it must be a positive number), then the search is repeated that many times (each time starting at the end of the previous time's match). If all these successive searches succeed, the function succeeds, moving point and returning its new value. Otherwise the function fails.

What happens when the function fails depends on the value of noerror. If noerror is nil, a search-failed error is signaled. If noerror is t, re-search-forward does nothing and returns nil. If noerror is neither nil nor t, then re-search-forward moves point to limit (or the end of the buffer) and returns nil.

In the following example, point is initially before the `T'. Evaluating the search call moves point to the end of that line (between the `t' of `hat' and the newline).
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(re-search-forward "[a-z]+" nil t 5)
     => 27

---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
Command: re-search-backward regexp &optional limit noerror repeat
This function searches backward in the current buffer for a string of text that is matched by the regular expression regexp, leaving point at the beginning of the first text found.

This function is analogous to re-search-forward, but they are not simple mirror images. re-search-forward finds the match whose beginning is as close as possible to the starting point. If re-search-backward were a perfect mirror image, it would find the match whose end is as close as possible. However, in fact it finds the match whose beginning is as close as possible. The reason is that matching a regular expression at a given spot always works from beginning to end, and starts at a specified beginning position.

A true mirror-image of re-search-forward would require a special feature for matching regular expressions from end to beginning. It's not worth the trouble of implementing that.

Function: string-match regexp string &optional start
This function returns the index of the start of the first match for the regular expression regexp in string, or nil if there is no match. If start is non-nil, the search starts at that index in string.

For example,
(string-match
 "quick" "The quick brown fox jumped quickly.")
     => 4
(string-match
 "quick" "The quick brown fox jumped quickly." 8)
     => 27
The index of the first character of the string is 0, the index of the second character is 1, and so on.

After this function returns, the index of the first character beyond the match is available as (match-end 0). See section The Match Data.
(string-match
 "quick" "The quick brown fox jumped quickly." 8)
     => 27

(match-end 0)
     => 32
Function: looking-at regexp
This function determines whether the text in the current buffer directly following point matches the regular expression regexp. "Directly following" means precisely that: the search is "anchored" and it can succeed only starting with the first character following point. The result is t if so, nil otherwise.

This function does not move point, but it updates the match data, which you can access using match-beginning and match-end. See section The Match Data.

In this example, point is located directly before the `T'. If it were anywhere else, the result would be nil.
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(looking-at "The cat in the hat$")
     => t
POSIX Regular Expression Searching

The usual regular expression functions do backtracking when necessary to handle the `\|' and repetition constructs, but they continue this only until they find some match. Then they succeed and report the first match found.

This section describes alternative search functions which perform the full backtracking specified by the POSIX standard for regular expression matching. They continue backtracking until they have tried all possibilities and found all matches, so they can report the longest match, as required by POSIX. This is much slower, so use these functions only when you really need the longest match.

Function: posix-search-forward regexp &optional limit noerror repeat
This is like re-search-forward except that it performs the full backtracking specified by the POSIX standard for regular expression matching.

Function: posix-search-backward regexp &optional limit noerror repeat
This is like re-search-backward except that it performs the full backtracking specified by the POSIX standard for regular expression matching.

Function: posix-looking-at regexp
This is like looking-at except that it performs the full backtracking specified by the POSIX standard for regular expression matching.

Function: posix-string-match regexp string &optional start
This is like string-match except that it performs the full backtracking specified by the POSIX standard for regular expression matching.

Search and Replace

Function: perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map
This function is the guts of query-replace and related commands. It searches for occurrences of from-string and replaces some or all of them. If query-flag is nil, it replaces all occurrences; otherwise, it asks the user what to do about each one.

If regexp-flag is non-nil, then from-string is considered a regular expression; otherwise, it must match literally. If delimited-flag is non-nil, then only replacements surrounded by word boundaries are considered.

The argument replacements specifies what to replace occurrences with. If it is a string, that string is used. It can also be a list of strings, to be used in cyclic order.

If repeat-count is non-nil, it should be an integer. Then it specifies how many times to use each of the strings in the replacements list before advancing cyclicly to the next one.

Normally, the keymap query-replace-map defines the possible user responses for queries. The argument map, if non-nil, is a keymap to use instead of query-replace-map.

Variable: query-replace-map
This variable holds a special keymap that defines the valid user responses for query-replace and related functions, as well as y-or-n-p and map-y-or-n-p. It is unusual in two ways:

The "key bindings" are not commands, just symbols that are meaningful to the functions that use this map.
Prefix keys are not supported; each key binding must be for a single-event key sequence. This is because the functions don't use read-key-sequence to get the input; instead, they read a single event and look it up "by hand."

Here are the meaningful "bindings" for query-replace-map. Several of them are meaningful only for query-replace and friends.

act
Do take the action being considered--in other words, "yes."
skip
Do not take action for this question--in other words, "no."
exit
Answer this question "no," and give up on the entire series of questions, assuming that the answers will be "no."
act-and-exit
Answer this question "yes," and give up on the entire series of questions, assuming that subsequent answers will be "no."
act-and-show
Answer this question "yes," but show the results--don't advance yet to the next question.
automatic
Answer this question and all subsequent questions in the series with "yes," without further user interaction.
backup
Move back to the previous place that a question was asked about.
edit
Enter a recursive edit to deal with this question--instead of any other action that would normally be taken.
delete-and-edit
Delete the text being considered, then enter a recursive edit to replace it.
recenter
Redisplay and center the window, then ask the same question again.
quit
Perform a quit right away. Only y-or-n-p and related functions use this answer.
help
Display some help, then ask again.
The Match Data

Emacs keeps track of the positions of the start and end of segments of text found during a regular expression search. This means, for example, that you can search for a complex pattern, such as a date in an Rmail message, and then extract parts of the match under control of the pattern.

Because the match data normally describe the most recent search only, you must be careful not to do another search inadvertently between the search you wish to refer back to and the use of the match data. If you can't avoid another intervening search, you must save and restore the match data around it, to prevent it from being overwritten.

Replacing the Text That Matched

This function replaces the text matched by the last search with replacement.

Function: replace-match replacement &optional fixedcase literal string subexp
This function replaces the text in the buffer (or in string) that was matched by the last search. It replaces that text with replacement.

If you did the last search in a buffer, you should specify nil for string. Then replace-match does the replacement by editing the buffer; it leaves point at the end of the replacement text, and returns t.

If you did the search in a string, pass the same string as string. Then replace-match does the replacement by constructing and returning a new string.

If fixedcase is non-nil, then the case of the replacement text is not changed; otherwise, the replacement text is converted to a different case depending upon the capitalization of the text to be replaced. If the original text is all upper case, the replacement text is converted to upper case. If the first word of the original text is capitalized, then the first word of the replacement text is capitalized. If the original text contains just one word, and that word is a capital letter, replace-match considers this a capitalized first word rather than all upper case.

If case-replace is nil, then case conversion is not done, regardless of the value of fixed-case. See section Searching and Case.

If literal is non-nil, then replacement is inserted exactly as it is, the only alterations being case changes as needed. If it is nil (the default), then the character `\' is treated specially. If a `\' appears in replacement, then it must be part of one of the following sequences:

`\&'
`\&' stands for the entire text being replaced.
`\n'
`\n', where n is a digit, stands for the text that matched the nth subexpression in the original regexp. Subexpressions are those expressions grouped inside `\(...\)'.
`\\'
`\\' stands for a single `\' in the replacement text.
If subexp is non-nil, that says to replace just subexpression number subexp of the regexp that was matched, not the entire match. For example, after matching `foo \(ba*r\)', calling replace-match with 1 as subexp means to replace just the text that matched `\(ba*r\)'.

Simple Match Data Access

This section explains how to use the match data to find out what was matched by the last search or match operation.

You can ask about the entire matching text, or about a particular parenthetical subexpression of a regular expression. The count argument in the functions below specifies which. If count is zero, you are asking about the entire match. If count is positive, it specifies which subexpression you want.

Recall that the subexpressions of a regular expression are those expressions grouped with escaped parentheses, `\(...\)'. The countth subexpression is found by counting occurrences of `\(' from the beginning of the whole regular expression. The first subexpression is numbered 1, the second 2, and so on. Only regular expressions can have subexpressions--after a simple string search, the only information available is about the entire match.

A search which fails may or may not alter the match data. In the past, a failing search did not do this, but we may change it in the future.

Function: match-string count &optional in-string
This function returns, as a string, the text matched in the last search or match operation. It returns the entire text if count is zero, or just the portion corresponding to the countth parenthetical subexpression, if count is positive. If count is out of range, or if that subexpression didn't match anything, the value is nil.

If the last such operation was done against a string with string-match, then you should pass the same string as the argument in-string. After a buffer search or match, you should omit in-string or pass nil for it; but you should make sure that the current buffer when you call match-string is the one in which you did the searching or matching.

Function: match-string-no-properties count
This function is like match-string except that the result has no text properties.

Function: match-beginning count
This function returns the position of the start of text matched by the last regular expression searched for, or a subexpression of it.

If count is zero, then the value is the position of the start of the entire match. Otherwise, count specifies a subexpression in the regular expression, and the value of the function is the starting position of the match for that subexpression.

The value is nil for a subexpression inside a `\|' alternative that wasn't used in the match.

Function: match-end count
This function is like match-beginning except that it returns the position of the end of the match, rather than the position of the beginning.

Here is an example of using the match data, with a comment showing the positions within the text:
(string-match "\\(qu\\)\\(ick\\)"
              "The quick fox jumped quickly.")
              ;0123456789
     => 4

(match-string 0 "The quick fox jumped quickly.")
     => "quick"
(match-string 1 "The quick fox jumped quickly.")
     => "qu"
(match-string 2 "The quick fox jumped quickly.")
     => "ick"

(match-beginning 1)       ; The beginning of the match
     => 4                 ;   with `qu' is at index 4.

(match-beginning 2)       ; The beginning of the match
     => 6                 ;   with `ick' is at index 6.

(match-end 1)             ; The end of the match
     => 6                 ;   with `qu' is at index 6.

(match-end 2)             ; The end of the match
     => 9                 ;   with `ick' is at index 9.
Here is another example. Point is initially located at the beginning of the line. Searching moves point to between the space and the word `in'. The beginning of the entire match is at the 9th character of the buffer (`T'), and the beginning of the match for the first subexpression is at the 13th character (`c').
(list
  (re-search-forward "The \\(cat \\)")
  (match-beginning 0)
  (match-beginning 1))
    => (9 9 13)

---------- Buffer: foo ----------
I read "The cat -!-in the hat comes back" twice.
        ^   ^
        9  13
---------- Buffer: foo ----------
(In this case, the index returned is a buffer position; the first character of the buffer counts as 1.)

Accessing the Entire Match Data

The functions match-data and set-match-data read or write the entire match data, all at once.

Function: match-data
This function returns a newly constructed list containing all the information on what text the last search matched. Element zero is the position of the beginning of the match for the whole expression; element one is the position of the end of the match for the expression. The next two elements are the positions of the beginning and end of the match for the first subexpression, and so on. In general, element corresponds to (match-beginning n); and element corresponds to (match-end n).

All the elements are markers or nil if matching was done on a buffer, and all are integers or nil if matching was done on a string with string-match.

As always, there must be no possibility of intervening searches between the call to a search function and the call to match-data that is intended to access the match data for that search.
(match-data)
     =>  (#<marker at 9 in foo>
          #<marker at 17 in foo>
          #<marker at 13 in foo>
          #<marker at 17 in foo>)
Function: set-match-data match-list
This function sets the match data from the elements of match-list, which should be a list that was the value of a previous call to match-data.

If match-list refers to a buffer that doesn't exist, you don't get an error; that sets the match data in a meaningless but harmless way.

store-match-data is a semi-obsolete alias for set-match-data.

Saving and Restoring the Match Data

When you call a function that may do a search, you may need to save and restore the match data around that call, if you want to preserve the match data from an earlier search for later use. Here is an example that shows the problem that arises if you fail to save the match data:
(re-search-forward "The \\(cat \\)")
     => 48
(foo)                   ; Perhaps foo does
                        ;   more searching.
(match-end 0)
     => 61              ; Unexpected result---not 48!
You can save and restore the match data with save-match-data:

Macro: save-match-data body...
This macro executes body, saving and restoring the match data around it.

You could use set-match-data together with match-data to imitate the effect of the special form save-match-data. Here is how:
(let ((data (match-data)))
  (unwind-protect
      ...   ; Ok to change the original match data.
    (set-match-data data)))
Emacs automatically saves and restores the match data when it runs process filter functions (see section Process Filter Functions) and process sentinels (see section Sentinels: Detecting Process Status Changes).

Searching and Case

By default, searches in Emacs ignore the case of the text they are searching through; if you specify searching for `FOO', then `Foo' or `foo' is also considered a match. This applies to regular expressions, too; thus, `[aB]' would match `a' or `A' or `b' or `B'.

If you do not want this feature, set the variable case-fold-search to nil. Then all letters must match exactly, including case. This is a buffer-local variable; altering the variable affects only the current buffer. (See section Introduction to Buffer-Local Variables.) Alternatively, you may change the value of default-case-fold-search, which is the default value of case-fold-search for buffers that do not override it.

Note that the user-level incremental search feature handles case distinctions differently. When given a lower case letter, it looks for a match of either case, but when given an upper case letter, it looks for an upper case letter only. But this has nothing to do with the searching functions used in Lisp code.

User Option: case-replace
This variable determines whether the replacement functions should preserve case. If the variable is nil, that means to use the replacement text verbatim. A non-nil value means to convert the case of the replacement text according to the text being replaced.

The function replace-match is where this variable actually has its effect. See section Replacing the Text That Matched.

User Option: case-fold-search
This buffer-local variable determines whether searches should ignore case. If the variable is nil they do not ignore case; otherwise they do ignore case.

Variable: default-case-fold-search
The value of this variable is the default value for case-fold-search in buffers that do not override it. This is the same as (default-value 'case-fold-search).

Standard Regular Expressions Used in Editing

This section describes some variables that hold regular expressions used for certain purposes in editing:

Variable: page-delimiter
This is the regular expression describing line-beginnings that separate pages. The default value is "^\014" (i.e., "^^L" or "^\C-l"); this matches a line that starts with a formfeed character.

The following two regular expressions should not assume the match always starts at the beginning of a line; they should not use `^' to anchor the match. Most often, the paragraph commands do check for a match only at the beginning of a line, which means that `^' would be superfluous. When there is a nonzero left margin, they accept matches that start after the left margin. In that case, a `^' would be incorrect. However, a `^' is harmless in modes where a left margin is never used.

Variable: paragraph-separate
This is the regular expression for recognizing the beginning of a line that separates paragraphs. (If you change this, you may have to change paragraph-start also.) The default value is "[ \t\f]*$", which matches a line that consists entirely of spaces, tabs, and form feeds (after its left margin).

Variable: paragraph-start
This is the regular expression for recognizing the beginning of a line that starts or separates paragraphs. The default value is "[ \t\n\f]", which matches a line starting with a space, tab, newline, or form feed (after its left margin).

Variable: sentence-end
This is the regular expression describing the end of a sentence. (All paragraph boundaries also end sentences, regardless.) The default value is:
"[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
This means a period, question mark or exclamation mark, followed optionally by a closing parenthetical character, followed by tabs, spaces or new lines.

For a detailed explanation of this regular expression, see section Complex Regexp Example.
Syntax Tables

A syntax table specifies the syntactic textual function of each character. This information is used by the parsing functions, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. The current syntax table controls the meaning of the word motion functions (see section Motion by Words) and the list motion functions (see section Moving over Balanced Expressions), as well as the functions in this chapter.

Syntax Table Concepts

A syntax table is a char-table (see section Char-Tables). The element at index c describes the character with code c. The element's value should be a list that encodes the syntax of the character in question.

Syntax tables are used only for moving across text, not for the Emacs Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp expressions, and these rules cannot be changed. (Some Lisp systems provide ways to redefine the read syntax, but we decided to leave this feature out of Emacs Lisp for simplicity.)

Each buffer has its own major mode, and each major mode has its own idea of the syntactic class of various characters. For example, in Lisp mode, the character `;' begins a comment, but in C mode, it terminates a statement. To support these variations, Emacs makes the choice of syntax table local to each buffer. Typically, each major mode has its own syntax table and installs that table in each buffer that uses that mode. Changing this table alters the syntax in all those buffers as well as in any buffers subsequently put in that mode. Occasionally several similar modes share one syntax table. See section Major Mode Examples, for an example of how to set up a syntax table.

A syntax table can inherit the data for some characters from the standard syntax table, while specifying other characters itself. The "inherit" syntax class means "inherit this character's syntax from the standard syntax table." Just changing the standard syntax for a characters affects all syntax tables which inherit from it.

Function: syntax-table-p object
This function returns t if object is a syntax table.

Syntax Descriptors

This section describes the syntax classes and flags that denote the syntax of a character, and how they are represented as a syntax descriptor, which is a Lisp string that you pass to modify-syntax-entry to specify the syntax you want.

The syntax table specifies a syntax class for each character. There is no necessary relationship between the class of a character in one syntax table and its class in any other table.

Each class is designated by a mnemonic character, which serves as the name of the class when you need to specify a class. Usually the designator character is one that is frequently in that class; however, its meaning as a designator is unvarying and independent of what syntax that character currently has.

A syntax descriptor is a Lisp string that specifies a syntax class, a matching character (used only for the parenthesis classes) and flags. The first character is the designator for a syntax class. The second character is the character to match; if it is unused, put a space there. Then come the characters for any desired flags. If no matching character or flags are needed, one character is sufficient.

For example, the syntax descriptor for the character `*' in C mode is `. 23' (i.e., punctuation, matching character slot unused, second character of a comment-starter, first character of an comment-ender), and the entry for `/' is `. 14' (i.e., punctuation, matching character slot unused, first character of a comment-starter, second character of a comment-ender).

Table of Syntax Classes

Here is a table of syntax classes, the characters that stand for them, their meanings, and examples of their use.

Syntax class: whitespace character
Whitespace characters (designated by ` ' or `-') separate symbols and words from each other. Typically, whitespace characters have no other syntactic significance, and multiple whitespace characters are syntactically equivalent to a single one. Space, tab, newline and formfeed are classified as whitespace in almost all major modes.

Syntax class: word constituent
Word constituents (designated by `w') are parts of normal English words and are typically used in variable and command names in programs. All upper- and lower-case letters, and the digits, are typically word constituents.

Syntax class: symbol constituent
Symbol constituents (designated by `_') are the extra characters that are used in variable and command names along with word constituents. For example, the symbol constituents class is used in Lisp mode to indicate that certain characters may be part of symbol names even though they are not part of English words. These characters are `$&*+-_<>'. In standard C, the only non-word-constituent character that is valid in symbols is underscore (`_').

Syntax class: punctuation character
Punctuation characters (designated by `.') are those characters that are used as punctuation in English, or are used in some way in a programming language to separate symbols from one another. Most programming language modes, including Emacs Lisp mode, have no characters in this class since the few characters that are not symbol or word constituents all have other uses.

Syntax class: open parenthesis character

Syntax class: close parenthesis character
Open and close parenthesis characters are characters used in dissimilar pairs to surround sentences or expressions. Such a grouping is begun with an open parenthesis character and terminated with a close. Each open parenthesis character matches a particular close parenthesis character, and vice versa. Normally, Emacs indicates momentarily the matching open parenthesis when you insert a close parenthesis. See section Blinking Parentheses.

The class of open parentheses is designated by `(', and that of close parentheses by `)'.

In English text, and in C code, the parenthesis pairs are `()', `[]', and `{}'. In Emacs Lisp, the delimiters for lists and vectors (`()' and `[]') are classified as parenthesis characters.

Syntax class: string quote
String quote characters (designated by `"') are used in many languages, including Lisp and C, to delimit string constants. The same string quote character appears at the beginning and the end of a string. Such quoted strings do not nest.

The parsing facilities of Emacs consider a string as a single token. The usual syntactic meanings of the characters in the string are suppressed.

The Lisp modes have two string quote characters: double-quote (`"') and vertical bar (`|'). `|' is not used in Emacs Lisp, but it is used in Common Lisp. C also has two string quote characters: double-quote for strings, and single-quote (`'') for character constants.

English text has no string quote characters because English is not a programming language. Although quotation marks are used in English, we do not want them to turn off the usual syntactic properties of other characters in the quotation.

Syntax class: escape
An escape character (designated by `\') starts an escape sequence such as is used in C string and character constants. The character `\' belongs to this class in both C and Lisp. (In C, it is used thus only inside strings, but it turns out to cause no trouble to treat it this way throughout C code.)

Characters in this class count as part of words if words-include-escapes is non-nil. See section Motion by Words.

Syntax class: character quote
A character quote character (designated by `/') quotes the following character so that it loses its normal syntactic meaning. This differs from an escape character in that only the character immediately following is ever affected.

Characters in this class count as part of words if words-include-escapes is non-nil. See section Motion by Words.

This class is used for backslash in TeX mode.

Syntax class: paired delimiter
Paired delimiter characters (designated by `$') are like string quote characters except that the syntactic properties of the characters between the delimiters are not suppressed. Only TeX mode uses a paired delimiter presently--the `$' that both enters and leaves math mode.

Syntax class: expression prefix
An expression prefix operator (designated by `'') is used for syntactic operators that are considered as part of an expression if they appear next to one. In Lisp modes, these characters include the apostrophe, `'' (used for quoting), the comma, `,' (used in macros), and `#' (used in the read syntax for certain data types).

Syntax class: comment starter

Syntax class: comment ender
The comment starter and comment ender characters are used in various languages to delimit comments. These classes are designated by `<' and `>', respectively.

English text has no comment characters. In Lisp, the semicolon (`;') starts a comment and a newline or formfeed ends one.

Syntax class: inherit
This syntax class does not specify a particular syntax. It says to look in the standard syntax table to find the syntax of this character. The designator for this syntax code is `@'.

Syntax class: generic comment delimiter
A generic comment delimiter character starts or ends a special kind of comment. Any generic comment delimiter matches any generic comment delimiter, but they cannot match a comment starter or comment ender; generic comment delimiters can only match each other.

This syntax class is primarily meant for use with the syntax-table text property (see section Syntax Properties). You can mark any range of characters as forming a comment, by giving the first and last characters of the range syntax-table properties identifying them as generic comment delimiters.

Syntax class: generic string delimiter
A generic string delimiter character starts or ends a string. This class differs from the string quote class in that any generic string delimiter can match any other generic string delimiter; but they do not match ordinary string quote characters.

This syntax class is primarily meant for use with the syntax-table text property (see section Syntax Properties). You can mark any range of characters as forming a string constant, by giving the first and last characters of the range syntax-table properties identifying them as generic string delimiters.

Syntax Flags

In addition to the classes, entries for characters in a syntax table can specify flags. There are six possible flags, represented by the characters `1', `2', `3', `4', `b' and `p'.

All the flags except `p' are used to describe multi-character comment delimiters. The digit flags indicate that a character can also be part of a comment sequence, in addition to the syntactic properties associated with its character class. The flags are independent of the class and each other for the sake of characters such as `*' in C mode, which is a punctuation character, and the second character of a start-of-comment sequence (`/*'), and the first character of an end-of-comment sequence (`*/').

Here is a table of the possible flags for a character c, and what they mean:

`1' means c is the start of a two-character comment-start sequence.
`2' means c is the second character of such a sequence.
`3' means c is the start of a two-character comment-end sequence.
`4' means c is the second character of such a sequence.
`b' means that c as a comment delimiter belongs to the alternative "b" comment style. Emacs supports two comment styles simultaneously in any one syntax table. This is for the sake of C++. Each style of comment syntax has its own comment-start sequence and its own comment-end sequence. Each comment must stick to one style or the other; thus, if it starts with the comment-start sequence of style "b", it must also end with the comment-end sequence of style "b". The two comment-start sequences must begin with the same character; only the second character may differ. Mark the second character of the "b"-style comment-start sequence with the `b' flag. A comment-end sequence (one or two characters) applies to the "b" style if its first character has the `b' flag set; otherwise, it applies to the "a" style. The appropriate comment syntax settings for C++ are as follows:
`/'
`124b'
`*'
`23'
newline
`>b' This defines four comment-delimiting sequences:
`/*'
This is a comment-start sequence for "a" style because the second character, `*', does not have the `b' flag.
`//'
This is a comment-start sequence for "b" style because the second character, `/', does have the `b' flag.
`*/'
This is a comment-end sequence for "a" style because the first character, `*', does not have the `b' flag.
newline
This is a comment-end sequence for "b" style, because the newline character has the `b' flag.
`p' identifies an additional "prefix character" for Lisp syntax. These characters are treated as whitespace when they appear between expressions. When they appear within an expression, they are handled according to their usual syntax codes. The function backward-prefix-chars moves back over these characters, as well as over characters whose primary syntax class is prefix (`''). See section Motion and Syntax.

Syntax Table Functions

In this section we describe functions for creating, accessing and altering syntax tables.

Function: make-syntax-table
This function creates a new syntax table. It inherits the syntax for letters and control characters from the standard syntax table. For other characters, the syntax is copied from the standard syntax table.

Most major mode syntax tables are created in this way.

Function: copy-syntax-table &optional table
This function constructs a copy of table and returns it. If table is not supplied (or is nil), it returns a copy of the current syntax table. Otherwise, an error is signaled if table is not a syntax table.

Command: modify-syntax-entry char syntax-descriptor &optional table
This function sets the syntax entry for char according to syntax-descriptor. The syntax is changed only for table, which defaults to the current buffer's syntax table, and not in any other syntax table. The argument syntax-descriptor specifies the desired syntax; this is a string beginning with a class designator character, and optionally containing a matching character and flags as well. See section Syntax Descriptors.

This function always returns nil. The old syntax information in the table for this character is discarded.

An error is signaled if the first character of the syntax descriptor is not one of the twelve syntax class designator characters. An error is also signaled if char is not a character.
Examples:

;; Put the space character in class whitespace.
(modify-syntax-entry ?\  " ")
     => nil

;; Make `$' an open parenthesis character,
;;   with `^' as its matching close.
(modify-syntax-entry ?$ "(^")
     => nil

;; Make `^' a close parenthesis character,
;;   with `$' as its matching open.
(modify-syntax-entry ?^ ")$")
     => nil

;; Make `/' a punctuation character,
;;   the first character of a start-comment sequence,
;;   and the second character of an end-comment sequence.
;;   This is used in C mode.
(modify-syntax-entry ?/ ". 14")
     => nil
Function: char-syntax character
This function returns the syntax class of character, represented by its mnemonic designator character. This returns only the class, not any matching parenthesis or flags.

An error is signaled if char is not a character.

The following examples apply to C mode. The first example shows that the syntax class of space is whitespace (represented by a space). The second example shows that the syntax of `/' is punctuation. This does not show the fact that it is also part of comment-start and -end sequences. The third example shows that open parenthesis is in the class of open parentheses. This does not show the fact that it has a matching character, `)'.
(string (char-syntax ?\ ))
     => " "

(string (char-syntax ?/))
     => "."

(string (char-syntax ?\())
     => "("
We use string to make it easier to see the character returned by char-syntax.

Function: set-syntax-table table
This function makes table the syntax table for the current buffer. It returns table.

Function: syntax-table
This function returns the current syntax table, which is the table for the current buffer.

Syntax Properties

When the syntax table is not flexible enough to specify the syntax of a language, you can use syntax-table text properties to override the syntax table for specific character occurrences in the buffer. See section Text Properties.

The valid values of syntax-table text property are:

syntax-table
If the property value is a syntax table, that table is used instead of the current buffer's syntax table to determine the syntax for this occurrence of the character.
(syntax-code . matching-char)
A cons cell of this format specifies the syntax for this occurrence of the character.
nil
If the property is nil, the character's syntax is determined from the current syntax table in the usual way.

Variable: parse-sexp-lookup-properties
If this is non-nil, the syntax scanning functions pay attention to syntax text properties. Otherwise they use only the current syntax table.

Motion and Syntax

This section describes functions for moving across characters that have certain syntax classes.

Function: skip-syntax-forward syntaxes &optional limit
This function moves point forward across characters having syntax classes mentioned in syntaxes. It stops when it encounters the end of the buffer, or position limit (if specified), or a character it is not supposed to skip. The return value is the distance traveled, which is a nonnegative integer.

Function: skip-syntax-backward syntaxes &optional limit
This function moves point backward across characters whose syntax classes are mentioned in syntaxes. It stops when it encounters the beginning of the buffer, or position limit (if specified), or a character it is not supposed to skip.

The return value indicates the distance traveled. It is an integer that is zero or less.

Function: backward-prefix-chars
This function moves point backward over any number of characters with expression prefix syntax. This includes both characters in the expression prefix syntax class, and characters with the `p' flag.

Parsing Balanced Expressions

Here are several functions for parsing and scanning balanced expressions, also known as sexps, in which parentheses match in pairs. The syntax table controls the interpretation of characters, so these functions can be used for Lisp expressions when in Lisp mode and for C expressions when in C mode. See section Moving over Balanced Expressions, for convenient higher-level functions for moving over balanced expressions.

Function: parse-partial-sexp start limit &optional target-depth stop-before state stop-comment
This function parses a sexp in the current buffer starting at start, not scanning past limit. It stops at position limit or when certain criteria described below are met, and sets point to the location where parsing stops. It returns a value describing the status of the parse at the point where it stops.

If state is nil, start is assumed to be at the top level of parenthesis structure, such as the beginning of a function definition. Alternatively, you might wish to resume parsing in the middle of the structure. To do this, you must provide a state argument that describes the initial status of parsing.

If the third argument target-depth is non-nil, parsing stops if the depth in parentheses becomes equal to target-depth. The depth starts at 0, or at whatever is given in state.

If the fourth argument stop-before is non-nil, parsing stops when it comes to any character that starts a sexp. If stop-comment is non-nil, parsing stops when it comes to the start of a comment. If stop-comment is the symbol syntax-table, parsing stops after the start of a comment or a string, or the end of a comment or a string, whichever comes first.

The fifth argument state is a nine-element list of the same form as the value of this function, described below. (It is OK to omit the last element of the nine.) The return value of one call may be used to initialize the state of the parse on another call to parse-partial-sexp.

The result is a list of nine elements describing the final state of the parse:

The depth in parentheses, counting from 0.
The character position of the start of the innermost parenthetical grouping containing the stopping point; nil if none.
The character position of the start of the last complete subexpression terminated; nil if none.
Non-nil if inside a string. More precisely, this is the character that will terminate the string, or t if a generic string delimiter character should terminate it.
t if inside a comment (of either style).
t if point is just after a quote character.
The minimum parenthesis depth encountered during this scan.
What kind of comment is active: nil for a comment of style "a", t for a comment of style "b", and syntax-table for a comment that should be ended by a generic comment delimiter character.
The string or comment start position. While inside a comment, this is the position where the comment began; while inside a string, this is the position where the string began. When outside of strings and comments, this element is nil.

Elements 0, 3, 4, 5 and 7 are significant in the argument state.

This function is most often used to compute indentation for languages that have nested parentheses.

Function: scan-lists from count depth
This function scans forward count balanced parenthetical groupings from position from. It returns the position where the scan stops. If count is negative, the scan moves backwards.

If depth is nonzero, parenthesis depth counting begins from that value. The only candidates for stopping are places where the depth in parentheses becomes zero; scan-lists counts count such places and then stops. Thus, a positive value for depth means go out depth levels of parenthesis.

Scanning ignores comments if parse-sexp-ignore-comments is non-nil.

If the scan reaches the beginning or end of the buffer (or its accessible portion), and the depth is not zero, an error is signaled. If the depth is zero but the count is not used up, nil is returned.

Function: scan-sexps from count
This function scans forward count sexps from position from. It returns the position where the scan stops. If count is negative, the scan moves backwards.

Scanning ignores comments if parse-sexp-ignore-comments is non-nil.

If the scan reaches the beginning or end of (the accessible part of) the buffer while in the middle of a parenthetical grouping, an error is signaled. If it reaches the beginning or end between groupings but before count is used up, nil is returned.

Variable: parse-sexp-ignore-comments
If the value is non-nil, then comments are treated as whitespace by the functions in this section and by forward-sexp.

In older Emacs versions, this feature worked only when the comment terminator is something like `*/', and appears only to end a comment. In languages where newlines terminate comments, it was necessary make this variable nil, since not every newline is the end of a comment. This limitation no longer exists.

You can use forward-comment to move forward or backward over one comment or several comments.

Function: forward-comment count
This function moves point forward across count comments (backward, if count is negative). If it finds anything other than a comment or whitespace, it stops, leaving point at the place where it stopped. It also stops after satisfying count.

To move forward over all comments and whitespace following point, use (forward-comment (buffer-size)). (buffer-size) is a good argument to use, because the number of comments in the buffer cannot exceed that many.

Some Standard Syntax Tables

Most of the major modes in Emacs have their own syntax tables. Here are several of them:

Function: standard-syntax-table
This function returns the standard syntax table, which is the syntax table used in Fundamental mode.

Variable: text-mode-syntax-table
The value of this variable is the syntax table used in Text mode.

Variable: c-mode-syntax-table
The value of this variable is the syntax table for C-mode buffers.

Variable: emacs-lisp-mode-syntax-table
The value of this variable is the syntax table used in Emacs Lisp mode by editing commands. (It has no effect on the Lisp read function.)

Syntax Table Internals

Lisp programs don't usually work with the elements directly; the Lisp-level syntax table functions usually work with syntax descriptors (see section Syntax Descriptors). Nonetheless, here we document the internal format.

Each element of a syntax table is a cons cell of the form (syntax-code . matching-char). The CAR, syntax-code, is an integer that encodes the syntax class, and any flags. The CDR, matching-char, is non-nil if a character to match was specified.

This table gives the value of syntax-code which corresponds to each syntactic type.

Integer Class

Integer Class

Integer Class

0 whitespace

5 close parenthesis

10 character quote

1 punctuation

6 expression prefix

11 comment-start

2 word

7 string quote

12 comment-end

3 symbol

8 paired delimiter

13 inherit

4 open parenthesis

9 escape

14 comment-fence

15 string-fence

For example, the usual syntax value for `(' is (4 . 41). (41 is the character code for `)'.)

The flags are encoded in higher order bits, starting 16 bits from the least significant bit. This table gives the power of two which corresponds to each syntax flag.

Prefix Flag

Prefix Flag

Prefix Flag

`1' (lsh 1 16)

`3' (lsh 1 18)

`p' (lsh 1 20)

`2' (lsh 1 17)

`4' (lsh 1 19)

`b' (lsh 1 21)

Categories

Categories provide an alternate way of classifying characters syntactically. You can define several categories as needed, then independently assign each character to one or more categories. Unlike syntax classes, categories are not mutually exclusive; it is normal for one character to belong to several categories.

Each buffer has a category table which records which categories are defined and also which characters belong to each category. Each category table defines its own categories, but normally these are initialized by copying from the standard categories table, so that the standard categories are available in all modes.

Each category has a name, which is an ASCII printing character in the range ` ' to `~'. You specify the name of a category when you define it with define-category.

The category table is actually a char-table (see section Char-Tables). The element of the category table at index c is a category set---a bool-vector--that indicates which categories character c belongs to. In this category set, if the element at index cat is t, that means category cat is a member of the set, and that character c belongs to category cat.

Function: define-category char docstring &optional table
This function defines a new category, with name char and documentation docstring.

The new category is defined for category table table, which defaults to the current buffer's category table.

Function: category-docstring category &optional table
This function returns the documentation string of category category in category table table.
(category-docstring ?a)
     => "ASCII"
(category-docstring ?l)
     => "Latin"
Function: get-unused-category table
This function returns a category name (a character) which is not currently defined in table. If all possible categories are in use in table, it returns nil.

Function: category-table
This function returns the current buffer's category table.

Function: category-table-p object
This function returns t if object is a category table, otherwise nil.

Function: standard-category-table
This function returns the standard category table.

Function: copy-category-table &optional table
This function constructs a copy of table and returns it. If table is not supplied (or is nil), it returns a copy of the current category table. Otherwise, an error is signaled if table is not a category table.

Function: set-category-table table
This function makes table the category table for the current buffer. It returns table.

Function: make-category-set categories
This function returns a new category set--a bool-vector--whose initial contents are the categories listed in the string categories. The elements of categories should be category names; the new category set has t for each of those categories, and nil for all other categories.
(make-category-set "al")
     => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
Function: char-category-set char
This function returns the category set for character char. This is the bool-vector which records which categories the character char belongs to. The function char-category-set does not allocate storage, because it returns the same bool-vector that exists in the category table.
(char-category-set ?a)
     => #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
Function: category-set-mnemonics category-set
This function converts the category set category-set into a string containing the names of all the categories that are members of the set.
(category-set-mnemonics (char-category-set ?a))
     => "al"
Function: modify-category-entry character category &optional table reset
This function modifies the category set of character in category table table (which defaults to the current buffer's category table).

Normally, it modifies the category set by adding category to it. But if reset is non-nil, then it deletes category instead.
Abbrevs And Abbrev Expansion

An abbreviation or abbrev is a string of characters that may be expanded to a longer string. The user can insert the abbrev string and find it replaced automatically with the expansion of the abbrev. This saves typing.

The set of abbrevs currently in effect is recorded in an abbrev table. Each buffer has a local abbrev table, but normally all buffers in the same major mode share one abbrev table. There is also a global abbrev table. Normally both are used.

An abbrev table is represented as an obarray containing a symbol for each abbreviation. The symbol's name is the abbreviation; its value is the expansion; its function definition is the hook function to do the expansion (see section Defining Abbrevs); its property list cell contains the use count, the number of times the abbreviation has been expanded. Because these symbols are not interned in the usual obarray, they will never appear as the result of reading a Lisp expression; in fact, normally they are never used except by the code that handles abbrevs. Therefore, it is safe to use them in an extremely nonstandard way. See section Creating and Interning Symbols.

For the user-level commands for abbrevs, see section `Abbrev Mode' in The GNU Emacs Manual.

Setting Up Abbrev Mode

Abbrev mode is a minor mode controlled by the value of the variable abbrev-mode.

Variable: abbrev-mode
A non-nil value of this variable turns on the automatic expansion of abbrevs when their abbreviations are inserted into a buffer. If the value is nil, abbrevs may be defined, but they are not expanded automatically.

This variable automatically becomes buffer-local when set in any fashion.

Variable: default-abbrev-mode
This is the value of abbrev-mode for buffers that do not override it. This is the same as (default-value 'abbrev-mode).

Abbrev Tables

This section describes how to create and manipulate abbrev tables.

Function: make-abbrev-table
This function creates and returns a new, empty abbrev table--an obarray containing no symbols. It is a vector filled with zeros.

Function: clear-abbrev-table table
This function undefines all the abbrevs in abbrev table table, leaving it empty. The function returns nil.

Function: define-abbrev-table tabname definitions
This function defines tabname (a symbol) as an abbrev table name, i.e., as a variable whose value is an abbrev table. It defines abbrevs in the table according to definitions, a list of elements of the form (abbrevname expansion hook usecount). The return value is always nil.

Variable: abbrev-table-name-list
This is a list of symbols whose values are abbrev tables. define-abbrev-table adds the new abbrev table name to this list.

Function: insert-abbrev-table-description name &optional human
This function inserts before point a description of the abbrev table named name. The argument name is a symbol whose value is an abbrev table. The return value is always nil.

If human is non-nil, the description is human-oriented. Otherwise the description is a Lisp expression--a call to define-abbrev-table that would define name exactly as it is currently defined.

Defining Abbrevs

These functions define an abbrev in a specified abbrev table. define-abbrev is the low-level basic function, while add-abbrev is used by commands that ask for information from the user.

Function: add-abbrev table type arg
This function adds an abbreviation to abbrev table table based on information from the user. The argument type is a string describing in English the kind of abbrev this will be (typically, "global" or "mode-specific"); this is used in prompting the user. The argument arg is the number of words in the expansion.

The return value is the symbol that internally represents the new abbrev, or nil if the user declines to confirm redefining an existing abbrev.

Function: define-abbrev table name expansion hook
This function defines an abbrev named name, in table, to expand to expansion and call hook. The return value is a symbol that represents the abbrev inside Emacs; its name is name.

The argument name should be a string. The argument expansion is normally the desired expansion (a string), or nil to undefine the abbrev. If it is anything but a string or nil, then the abbreviation "expands" solely by running hook.

The argument hook is a function or nil. If hook is non-nil, then it is called with no arguments after the abbrev is replaced with expansion; point is located at the end of expansion when hook is called.

The use count of the abbrev is initialized to zero.

User Option: only-global-abbrevs
If this variable is non-nil, it means that the user plans to use global abbrevs only. This tells the commands that define mode-specific abbrevs to define global ones instead. This variable does not alter the behavior of the functions in this section; it is examined by their callers.

Saving Abbrevs in Files

A file of saved abbrev definitions is actually a file of Lisp code. The abbrevs are saved in the form of a Lisp program to define the same abbrev tables with the same contents. Therefore, you can load the file with load (see section How Programs Do Loading). However, the function quietly-read-abbrev-file is provided as a more convenient interface.

User-level facilities such as save-some-buffers can save abbrevs in a file automatically, under the control of variables described here.

User Option: abbrev-file-name
This is the default file name for reading and saving abbrevs.

Function: quietly-read-abbrev-file filename
This function reads abbrev definitions from a file named filename, previously written with write-abbrev-file. If filename is nil, the file specified in abbrev-file-name is used. save-abbrevs is set to t so that changes will be saved.

This function does not display any messages. It returns nil.

User Option: save-abbrevs
A non-nil value for save-abbrev means that Emacs should save abbrevs when files are saved. abbrev-file-name specifies the file to save the abbrevs in.

Variable: abbrevs-changed
This variable is set non-nil by defining or altering any abbrevs. This serves as a flag for various Emacs commands to offer to save your abbrevs.

Command: write-abbrev-file filename
Save all abbrev definitions, in all abbrev tables, in the file filename, in the form of a Lisp program that when loaded will define the same abbrevs. This function returns nil.

Looking Up and Expanding Abbreviations

Abbrevs are usually expanded by certain interactive commands, including self-insert-command. This section describes the subroutines used in writing such commands, as well as the variables they use for communication.

Function: abbrev-symbol abbrev &optional table
This function returns the symbol representing the abbrev named abbrev. The value returned is nil if that abbrev is not defined. The optional second argument table is the abbrev table to look it up in. If table is nil, this function tries first the current buffer's local abbrev table, and second the global abbrev table.

Function: abbrev-expansion abbrev &optional table
This function returns the string that abbrev would expand into (as defined by the abbrev tables used for the current buffer). The optional argument table specifies the abbrev table to use, as in abbrev-symbol.

Command: expand-abbrev
This command expands the abbrev before point, if any. If point does not follow an abbrev, this command does nothing. The command returns t if it did expansion, nil otherwise.

Command: abbrev-prefix-mark &optional arg
Mark current point as the beginning of an abbrev. The next call to expand-abbrev will use the text from here to point (where it is then) as the abbrev to expand, rather than using the previous word as usual.

User Option: abbrev-all-caps
When this is set non-nil, an abbrev entered entirely in upper case is expanded using all upper case. Otherwise, an abbrev entered entirely in upper case is expanded by capitalizing each word of the expansion.

Variable: abbrev-start-location
This is the buffer position for expand-abbrev to use as the start of the next abbrev to be expanded. (nil means use the word before point instead.) abbrev-start-location is set to nil each time expand-abbrev is called. This variable is also set by abbrev-prefix-mark.

Variable: abbrev-start-location-buffer
The value of this variable is the buffer for which abbrev-start-location has been set. Trying to expand an abbrev in any other buffer clears abbrev-start-location. This variable is set by abbrev-prefix-mark.

Variable: last-abbrev
This is the abbrev-symbol of the most recent abbrev expanded. This information is left by expand-abbrev for the sake of the unexpand-abbrev command (see section `Expanding Abbrevs' in The GNU Emacs Manual).

Variable: last-abbrev-location
This is the location of the most recent abbrev expanded. This contains information left by expand-abbrev for the sake of the unexpand-abbrev command.

Variable: last-abbrev-text
This is the exact expansion text of the most recent abbrev expanded, after case conversion (if any). Its value is nil if the abbrev has already been unexpanded. This contains information left by expand-abbrev for the sake of the unexpand-abbrev command.

Variable: pre-abbrev-expand-hook
This is a normal hook whose functions are executed, in sequence, just before any expansion of an abbrev. See section Hooks. Since it is a normal hook, the hook functions receive no arguments. However, they can find the abbrev to be expanded by looking in the buffer before point.

The following sample code shows a simple use of pre-abbrev-expand-hook. If the user terminates an abbrev with a punctuation character, the hook function asks for confirmation. Thus, this hook allows the user to decide whether to expand the abbrev, and aborts expansion if it is not confirmed.
(add-hook 'pre-abbrev-expand-hook 'query-if-not-space)

;; This is the function invoked by pre-abbrev-expand-hook.

;; If the user terminated the abbrev with a space, the function does
;; nothing (that is, it returns so that the abbrev can expand).  If the
;; user entered some other character, this function asks whether
;; expansion should continue.

;; If the user answers the prompt with y, the function returns
;; nil (because of the not function), but that is
;; acceptable; the return value has no effect on expansion.

(defun query-if-not-space ()
  (if (/= ?\  (preceding-char))
      (if (not (y-or-n-p "Do you want to expand this abbrev? "))
          (error "Not expanding this abbrev"))))
Standard Abbrev Tables

Here we list the variables that hold the abbrev tables for the preloaded major modes of Emacs.

Variable: global-abbrev-table
This is the abbrev table for mode-independent abbrevs. The abbrevs defined in it apply to all buffers. Each buffer may also have a local abbrev table, whose abbrev definitions take precedence over those in the global table.

Variable: local-abbrev-table
The value of this buffer-local variable is the (mode-specific) abbreviation table of the current buffer.

Variable: fundamental-mode-abbrev-table
This is the local abbrev table used in Fundamental mode; in other words, it is the local abbrev table in all buffers in Fundamental mode.

Variable: text-mode-abbrev-table
This is the local abbrev table used in Text mode.

Variable: lisp-mode-abbrev-table
This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
Processes

In the terminology of operating systems, a process is a space in which a program can execute. Emacs runs in a process. Emacs Lisp programs can invoke other programs in processes of their own. These are called subprocesses or child processes of the Emacs process, which is their parent process.

A subprocess of Emacs may be synchronous or asynchronous, depending on how it is created. When you create a synchronous subprocess, the Lisp program waits for the subprocess to terminate before continuing execution. When you create an asynchronous subprocess, it can run in parallel with the Lisp program. This kind of subprocess is represented within Emacs by a Lisp object which is also called a "process". Lisp programs can use this object to communicate with the subprocess or to control it. For example, you can send signals, obtain status information, receive output from the process, or send input to it.

Function: processp object
This function returns t if object is a process, nil otherwise.

Functions that Create Subprocesses

There are three functions that create a new subprocess in which to run a program. One of them, start-process, creates an asynchronous process and returns a process object (see section Creating an Asynchronous Process). The other two, call-process and call-process-region, create a synchronous process and do not return a process object (see section Creating a Synchronous Process).

Synchronous and asynchronous processes are explained in following sections. Since the three functions are all called in a similar fashion, their common arguments are described here.

In all cases, the function's program argument specifies the program to be run. An error is signaled if the file is not found or cannot be executed. If the file name is relative, the variable exec-path contains a list of directories to search. Emacs initializes exec-path when it starts up, based on the value of the environment variable PATH. The standard file name constructs, `~', `.', and `..', are interpreted as usual in exec-path, but environment variable substitutions (`$HOME', etc.) are not recognized; use substitute-in-file-name to perform them (see section Functions that Expand Filenames).

Each of the subprocess-creating functions has a buffer-or-name argument which specifies where the standard output from the program will go. It should be a buffer or a buffer name; if it is a buffer name, that will create the buffer if it does not already exist. It can also be nil, which says to discard the output unless a filter function handles it. (See section Process Filter Functions, and section Reading and Printing Lisp Objects.) Normally, you should avoid having multiple processes send output to the same buffer because their output would be intermixed randomly.

All three of the subprocess-creating functions have a &rest argument, args. The args must all be strings, and they are supplied to program as separate command line arguments. Wildcard characters and other shell constructs have no special meanings in these strings, since the whole strings are passed directly to the specified program.

Please note: The argument program contains only the name of the program; it may not contain any command-line arguments. You must use args to provide those.

The subprocess gets its current directory from the value of default-directory (see section Functions that Expand Filenames).

The subprocess inherits its environment from Emacs, but you can specify overrides for it with process-environment. See section Operating System Environment.

Variable: exec-directory
The value of this variable is the name of a directory (a string) that contains programs that come with GNU Emacs, programs intended for Emacs to invoke. The program movemail is an example of such a program; Rmail uses it to fetch new mail from an inbox.

User Option: exec-path
The value of this variable is a list of directories to search for programs to run in subprocesses. Each element is either the name of a directory (i.e., a string), or nil, which stands for the default directory (which is the value of default-directory).

The value of exec-path is used by call-process and start-process when the program argument is not an absolute file name.

Shell Arguments

Lisp programs sometimes need to run a shell and give it a command which contains file names that were specified by the user. These programs ought to be able to support any valid file name. But the shell gives special treatment to certain characters, and if these characters occur in the file name, they will confuse the shell. To handle these characters, use the function shell-quote-argument:

Function: shell-quote-argument argument
This function returns a string which represents, in shell syntax, an argument whose actual contents are argument. It should work reliably to concatenate the return value into a shell command and then pass it to a shell for execution.

Precisely what this function does depends on your operating system. The function is designed to work with the usual shell syntax; if you use an unusual shell, you will need to redefine this function. On MS-DOS, the function returns argument unchanged; while this is not really correct, it is the best one can do, since the MS-DOS shell has no quoting features.
;; This example shows the behavior on GNU and Unix systems.
(shell-quote-argument "foo > bar")
     => "foo\\ \\>\\ bar"
Here's an example of using shell-quote-argument to construct a shell command:
(concat "diff -c "
        (shell-quote-argument oldfile)
        " "
        (shell-quote-argument newfile))
Creating a Synchronous Process

After a synchronous process is created, Emacs waits for the process to terminate before continuing. Starting Dired is an example of this: it runs ls in a synchronous process, then modifies the output slightly. Because the process is synchronous, the entire directory listing arrives in the buffer before Emacs tries to do anything with it.

While Emacs waits for the synchronous subprocess to terminate, the user can quit by typing C-g. The first C-g tries to kill the subprocess with a SIGINT signal; but it waits until the subprocess actually terminates before quitting. If during that time the user types another C-g, that kills the subprocess instantly with SIGKILL and quits immediately. See section Quitting.

The synchronous subprocess functions return an indication of how the process terminated.

The output from a synchronous subprocess is generally decoded using a coding system, much like text read from a file. The input sent to a subprocess by call-process-region is encoded using a coding system, much like text written into a file. See section Coding Systems.

Function: call-process program &optional infile destination display &rest args
This function calls program in a separate process and waits for it to finish.

The standard input for the process comes from file infile if infile is not nil, and from `/dev/null' otherwise. The argument destination says where to put the process output. Here are the possibilities:

a buffer
Insert the output in that buffer, before point. This includes both the standard output stream and the standard error stream of the process.
a string
Insert the output in a buffer with that name, before point.
t
Insert the output in the current buffer, before point.
nil
Discard the output.
0
Discard the output, and return immediately without waiting for the subprocess to finish. In this case, the process is not truly synchronous, since it can run in parallel with Emacs; but you can think of it as synchronous in that Emacs is essentially finished with the subprocess as soon as this function returns.
(real-destination error-destination)
Keep the standard output stream separate from the standard error stream; deal with the ordinary output as specified by real-destination, and dispose of the error output according to error-destination. If error-destination is nil, that means to discard the error output, t means mix it with the ordinary output, and a string specifies a file name to redirect error output into. You can't directly specify a buffer to put the error output in; that is too difficult to implement. But you can achieve this result by sending the error output to a temporary file and then inserting the file into a buffer.
If display is non-nil, then call-process redisplays the buffer as output is inserted. (However, if the coding system chosen for decoding output is undecided, meaning deduce the encoding from the actual data, then redisplay sometimes cannot continue once non-ASCII characters are encountered. There are fundamental reasons why it is hard to fix this.) Otherwise the function call-process does no redisplay, and the results become visible on the screen only when Emacs redisplays that buffer in the normal course of events.

The remaining arguments, args, are strings that specify command line arguments for the program.

The value returned by call-process (unless you told it not to wait) indicates the reason for process termination. A number gives the exit status of the subprocess; 0 means success, and any other value means failure. If the process terminated with a signal, call-process returns a string describing the signal.

In the examples below, the buffer `foo' is current.
(call-process "pwd" nil t)
     => nil

---------- Buffer: foo ----------
/usr/user/lewis/manual
---------- Buffer: foo ----------

(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
     => nil

---------- Buffer: bar ----------
lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh

---------- Buffer: bar ----------
Here is a good example of the use of call-process, which used to be found in the definition of insert-directory:
(call-process insert-directory-program nil t nil switches
              (if full-directory-p
                  (concat (file-name-as-directory file) ".")
                file))
Function: call-process-region start end program &optional delete destination display &rest args
This function sends the text between start to end as standard input to a process running program. It deletes the text sent if delete is non-nil; this is useful when destination is t, to insert the output in the current buffer in place of the input.

The arguments destination and display control what to do with the output from the subprocess, and whether to update the display as it comes in. For details, see the description of call-process, above. If destination is the integer 0, call-process-region discards the output and returns nil immediately, without waiting for the subprocess to finish.

The remaining arguments, args, are strings that specify command line arguments for the program.

The return value of call-process-region is just like that of call-process: nil if you told it to return without waiting; otherwise, a number or string which indicates how the subprocess terminated.

In the following example, we use call-process-region to run the cat utility, with standard input being the first five characters in buffer `foo' (the word `input'). cat copies its standard input into its standard output. Since the argument destination is t, this output is inserted in the current buffer.
---------- Buffer: foo ----------
input-!-
---------- Buffer: foo ----------

(call-process-region 1 6 "cat" nil t)
     => nil

---------- Buffer: foo ----------
inputinput-!-
---------- Buffer: foo ----------
The shell-command-on-region command uses call-process-region like this:
(call-process-region
 start end
 shell-file-name      ; Name of program.
 nil                  ; Do not delete region.
 buffer               ; Send output to buffer.
 nil                  ; No redisplay during output.
 "-c" command)        ; Arguments for the shell.
Function: shell-command-to-string command
This function executes command (a string) as a shell command, then returns the command's output as a string.

Creating an Asynchronous Process

After an asynchronous process is created, Emacs and the subprocess both continue running immediately. The process thereafter runs in parallel with Emacs, and the two can communicate with each other using the functions described in following sections. However, communication is only partially asynchronous: Emacs sends data to the process only when certain functions are called, and Emacs accepts data from the process only when Emacs is waiting for input or for a time delay.

Here we describe how to create an asynchronous process.

Function: start-process name buffer-or-name program &rest args
This function creates a new asynchronous subprocess and starts the program program running in it. It returns a process object that stands for the new subprocess in Lisp. The argument name specifies the name for the process object; if a process with this name already exists, then name is modified (by appending `<1>', etc.) to be unique. The buffer buffer-or-name is the buffer to associate with the process.

The remaining arguments, args, are strings that specify command line arguments for the program.

In the example below, the first process is started and runs (rather, sleeps) for 100 seconds. Meanwhile, the second process is started, and given the name `my-process<1>' for the sake of uniqueness. It inserts the directory listing at the end of the buffer `foo', before the first process finishes. Then it finishes, and a message to that effect is inserted in the buffer. Much later, the first process finishes, and another message is inserted in the buffer for it.
(start-process "my-process" "foo" "sleep" "100")
     => #<process my-process>

(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
     => #<process my-process<1>>

---------- Buffer: foo ----------
total 2
lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
-rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon

Process my-process<1> finished

Process my-process finished
---------- Buffer: foo ----------
Function: start-process-shell-command name buffer-or-name command &rest command-args
This function is like start-process except that it uses a shell to execute the specified command. The argument command is a shell command name, and command-args are the arguments for the shell command. The variable shell-file-name specifies which shell to use.

The point of running a program through the shell, rather than directly with start-process, is so that you can employ shell features such as wildcards in the arguments. It follows that if you include an arbitrary user-specified filename in the command, you should quote it with shell-quote-argument first, so that any special shell characters in the file name do not have their special shell meanings. See section Shell Arguments.

Variable: process-connection-type
This variable controls the type of device used to communicate with asynchronous subprocesses. If it is non-nil, then PTYs are used, when available. Otherwise, pipes are used.

PTYs are usually preferable for processes visible to the user, as in Shell mode, because they allow job control (C-c, C-z, etc.) to work between the process and its children, whereas pipes do not. For subprocesses used for internal purposes by programs, it is often better to use a pipe, because they are more efficient. In addition, the total number of PTYs is limited on many systems and it is good not to waste them.

The value process-connection-type is used when start-process is called. So you can specify how to communicate with one subprocess by binding the variable around the call to start-process.
(let ((process-connection-type nil))  ; Use a pipe.
  (start-process ...))
To determine whether a given subprocess actually got a pipe or a PTY, use the function process-tty-name (see section Process Information).

Deleting Processes

Deleting a process disconnects Emacs immediately from the subprocess, and removes it from the list of active processes. It sends a signal to the subprocess to make the subprocess terminate, but this is not guaranteed to happen immediately. The process object itself continues to exist as long as other Lisp objects point to it. The process mark continues to point to the same place as before (usually into a buffer where output from the process was being inserted).

You can delete a process explicitly at any time. Processes are deleted automatically after they terminate, but not necessarily right away. If you delete a terminated process explicitly before it is deleted automatically, no harm results.

User Option: delete-exited-processes
This variable controls automatic deletion of processes that have terminated (due to calling exit or to a signal). If it is nil, then they continue to exist until the user runs list-processes. Otherwise, they are deleted immediately after they exit.

Function: delete-process name
This function deletes the process associated with name, killing it with a SIGHUP signal. The argument name may be a process, the name of a process, a buffer, or the name of a buffer.
(delete-process "*shell*")
     => nil
Function: process-kill-without-query process &optional do-query
This function specifies whether Emacs should query the user if process is still running when Emacs is exited. If do-query is nil, the process will be deleted silently. Otherwise, Emacs will query about killing it.

The value is t if the process was formerly set up to require query, nil otherwise. A newly-created process always requires query.
(process-kill-without-query (get-process "shell"))
     => t
Process Information

Several functions return information about processes. list-processes is provided for interactive use.

Command: list-processes
This command displays a listing of all living processes. In addition, it finally deletes any process whose status was `Exited' or `Signaled'. It returns nil.

Function: process-list
This function returns a list of all processes that have not been deleted.
(process-list)
     => (#<process display-time> #<process shell>)
Function: get-process name
This function returns the process named name, or nil if there is none. An error is signaled if name is not a string.
(get-process "shell")
     => #<process shell>
Function: process-command process
This function returns the command that was executed to start process. This is a list of strings, the first string being the program executed and the rest of the strings being the arguments that were given to the program.
(process-command (get-process "shell"))
     => ("/bin/csh" "-i")
Function: process-id process
This function returns the PID of process. This is an integer that distinguishes the process process from all other processes running on the same computer at the current time. The PID of a process is chosen by the operating system kernel when the process is started and remains constant as long as the process exists.

Function: process-name process
This function returns the name of process.

Function: process-contact process
This function returns t for an ordinary child process, and (hostname service) for a net connection (see section Network Connections).

Function: process-status process-name
This function returns the status of process-name as a symbol. The argument process-name must be a process, a buffer, a process name (string) or a buffer name (string).

The possible values for an actual subprocess are:

run
for a process that is running.
stop
for a process that is stopped but continuable.
exit
for a process that has exited.
signal
for a process that has received a fatal signal.
open
for a network connection that is open.
closed
for a network connection that is closed. Once a connection is closed, you cannot reopen it, though you might be able to open a new connection to the same place.
nil
if process-name is not the name of an existing process.
(process-status "shell")
     => run
(process-status (get-buffer "*shell*"))
     => run
x
     => #<process xx<1>>
(process-status x)
     => exit
For a network connection, process-status returns one of the symbols open or closed. The latter means that the other side closed the connection, or Emacs did delete-process.

Function: process-exit-status process
This function returns the exit status of process or the signal number that killed it. (Use the result of process-status to determine which of those it is.) If process has not yet terminated, the value is 0.

Function: process-tty-name process
This function returns the terminal name that process is using for its communication with Emacs--or nil if it is using pipes instead of a terminal (see process-connection-type in section Creating an Asynchronous Process).

Function: process-coding-system process
This function returns a cons cell describing the coding systems in use for decoding output from process and for encoding input to process (see section Coding Systems). The value has this form:
(coding-system-for-decoding . coding-system-for-encoding)
Function: set-process-coding-system process decoding-system encoding-system
This function specifies the coding systems to use for subsequent output from and input to process. It will use decoding-system to decode subprocess output, and encoding-system to encode subprocess input.

Sending Input to Processes

Asynchronous subprocesses receive input when it is sent to them by Emacs, which is done with the functions in this section. You must specify the process to send input to, and the input data to send. The data appears on the "standard input" of the subprocess.

Some operating systems have limited space for buffered input in a PTY. On these systems, Emacs sends an EOF periodically amidst the other characters, to force them through. For most programs, these EOFs do no harm.

Subprocess input is normally encoded using a coding system before the subprocess receives it, much like text written into a file. You can use set-process-coding-system to specify which coding system to use (see section Process Information). Otherwise, the coding system comes from coding-system-for-write, if that is non-nil; or else from the defaulting mechanism (see section Default Coding Systems).

Function: process-send-string process-name string
This function sends process-name the contents of string as standard input. The argument process-name must be a process or the name of a process. If it is nil, the current buffer's process is used.

The function returns nil.
(process-send-string "shell<1>" "ls\n")
     => nil

---------- Buffer: *shell* ----------
...
introduction.texi               syntax-tables.texi~
introduction.texi~              text.texi
introduction.txt                text.texi~
...
---------- Buffer: *shell* ----------
Command: process-send-region process-name start end
This function sends the text in the region defined by start and end as standard input to process-name, which is a process or a process name. (If it is nil, the current buffer's process is used.)

An error is signaled unless both start and end are integers or markers that indicate positions in the current buffer. (It is unimportant which number is larger.)

Function: process-send-eof &optional process-name
This function makes process-name see an end-of-file in its input. The EOF comes after any text already sent to it.

If process-name is not supplied, or if it is nil, then this function sends the EOF to the current buffer's process. An error is signaled if the current buffer has no process.

The function returns process-name.
(process-send-eof "shell")
     => "shell"
Sending Signals to Processes

Sending a signal to a subprocess is a way of interrupting its activities. There are several different signals, each with its own meaning. The set of signals and their names is defined by the operating system. For example, the signal SIGINT means that the user has typed C-c, or that some analogous thing has happened.

Each signal has a standard effect on the subprocess. Most signals kill the subprocess, but some stop or resume execution instead. Most signals can optionally be handled by programs; if the program handles the signal, then we can say nothing in general about its effects.

You can send signals explicitly by calling the functions in this section. Emacs also sends signals automatically at certain times: killing a buffer sends a SIGHUP signal to all its associated processes; killing Emacs sends a SIGHUP signal to all remaining processes. (SIGHUP is a signal that usually indicates that the user hung up the phone.)

Each of the signal-sending functions takes two optional arguments: process-name and current-group.

The argument process-name must be either a process, the name of one, or nil. If it is nil, the process defaults to the process associated with the current buffer. An error is signaled if process-name does not identify a process.

The argument current-group is a flag that makes a difference when you are running a job-control shell as an Emacs subprocess. If it is non-nil, then the signal is sent to the current process-group of the terminal that Emacs uses to communicate with the subprocess. If the process is a job-control shell, this means the shell's current subjob. If it is nil, the signal is sent to the process group of the immediate subprocess of Emacs. If the subprocess is a job-control shell, this is the shell itself.

The flag current-group has no effect when a pipe is used to communicate with the subprocess, because the operating system does not support the distinction in the case of pipes. For the same reason, job-control shells won't work when a pipe is used. See process-connection-type in section Creating an Asynchronous Process.

Function: interrupt-process &optional process-name current-group
This function interrupts the process process-name by sending the signal SIGINT. Outside of Emacs, typing the "interrupt character" (normally C-c on some systems, and DEL on others) sends this signal. When the argument current-group is non-nil, you can think of this function as "typing C-c" on the terminal by which Emacs talks to the subprocess.

Function: kill-process &optional process-name current-group
This function kills the process process-name by sending the signal SIGKILL. This signal kills the subprocess immediately, and cannot be handled by the subprocess.

Function: quit-process &optional process-name current-group
This function sends the signal SIGQUIT to the process process-name. This signal is the one sent by the "quit character" (usually C-b or C-\) when you are not inside Emacs.

Function: stop-process &optional process-name current-group
This function stops the process process-name by sending the signal SIGTSTP. Use continue-process to resume its execution.

Outside of Emacs, on systems with job control, the "stop character" (usually C-z) normally sends this signal. When current-group is non-nil, you can think of this function as "typing C-z" on the terminal Emacs uses to communicate with the subprocess.

Function: continue-process &optional process-name current-group
This function resumes execution of the process process by sending it the signal SIGCONT. This presumes that process-name was stopped previously.

Function: signal-process pid signal
This function sends a signal to process pid, which need not be a child of Emacs. The argument signal specifies which signal to send; it should be an integer.

Receiving Output from Processes

There are two ways to receive the output that a subprocess writes to its standard output stream. The output can be inserted in a buffer, which is called the associated buffer of the process, or a function called the filter function can be called to act on the output. If the process has no buffer and no filter function, its output is discarded.

Output from a subprocess can arrive only while Emacs is waiting: when reading terminal input, in sit-for and sleep-for (see section Waiting for Elapsed Time or Input), and in accept-process-output (see section Accepting Output from Processes). This minimizes the problem of timing errors that usually plague parallel programming. For example, you can safely create a process and only then specify its buffer or filter function; no output can arrive before you finish, if the code in between does not call any primitive that waits.

Subprocess output is normally decoded using a coding system before the buffer or filter function receives it, much like text read from a file. You can use set-process-coding-system to specify which coding system to use (see section Process Information). Otherwise, the coding system comes from coding-system-for-read, if that is non-nil; or else from the defaulting mechanism (see section Default Coding Systems).

Warning: Coding systems such as undecided which determine the coding system from the data do not work entirely reliably with asynchronous subprocess output. This is because Emacs has to process asynchronous subprocess output in batches, as it arrives. Emacs must try to detect the proper coding system from one batch at a time, and this does not always work. Therefore, if at all possible, use a coding system which determines both the character code conversion and the end of line conversion--that is, one like latin-1-unix, rather than undecided or latin-1.

Process Buffers

A process can (and usually does) have an associated buffer, which is an ordinary Emacs buffer that is used for two purposes: storing the output from the process, and deciding when to kill the process. You can also use the buffer to identify a process to operate on, since in normal practice only one process is associated with any given buffer. Many applications of processes also use the buffer for editing input to be sent to the process, but this is not built into Emacs Lisp.

Unless the process has a filter function (see section Process Filter Functions), its output is inserted in the associated buffer. The position to insert the output is determined by the process-mark, which is then updated to point to the end of the text just inserted. Usually, but not always, the process-mark is at the end of the buffer.

Function: process-buffer process
This function returns the associated buffer of the process process.
(process-buffer (get-process "shell"))
     => #<buffer *shell*>
Function: process-mark process
This function returns the process marker for process, which is the marker that says where to insert output from the process.

If process does not have a buffer, process-mark returns a marker that points nowhere.

Insertion of process output in a buffer uses this marker to decide where to insert, and updates it to point after the inserted text. That is why successive batches of output are inserted consecutively.

Filter functions normally should use this marker in the same fashion as is done by direct insertion of output in the buffer. A good example of a filter function that uses process-mark is found at the end of the following section.

When the user is expected to enter input in the process buffer for transmission to the process, the process marker separates the new input from previous output.

Function: set-process-buffer process buffer
This function sets the buffer associated with process to buffer. If buffer is nil, the process becomes associated with no buffer.

Function: get-buffer-process buffer-or-name
This function returns the process associated with buffer-or-name. If there are several processes associated with it, then one is chosen. (Currently, the one chosen is the one most recently created.) It is usually a bad idea to have more than one process associated with the same buffer.
(get-buffer-process "*shell*")
     => #<process shell>
Killing the process's buffer deletes the process, which kills the subprocess with a SIGHUP signal (see section Sending Signals to Processes).

Process Filter Functions

A process filter function is a function that receives the standard output from the associated process. If a process has a filter, then all output from that process is passed to the filter. The process buffer is used directly for output from the process only when there is no filter.

The filter function can only be called when Emacs is waiting for something, because process output arrives only at such times. Emacs waits when reading terminal input, in sit-for and sleep-for (see section Waiting for Elapsed Time or Input), and in accept-process-output (see section Accepting Output from Processes).

A filter function must accept two arguments: the associated process and a string, which is output just received from it. The function is then free to do whatever it chooses with the output.

Quitting is normally inhibited within a filter function--otherwise, the effect of typing C-g at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a filter function, bind inhibit-quit to nil. See section Quitting.

If an error happens during execution of a filter function, it is caught automatically, so that it doesn't stop the execution of whatever program was running when the filter function was started. However, if debug-on-error is non-nil, the error-catching is turned off. This makes it possible to use the Lisp debugger to debug the filter function. See section The Lisp Debugger.

Many filter functions sometimes or always insert the text in the process's buffer, mimicking the actions of Emacs when there is no filter. Such filter functions need to use set-buffer in order to be sure to insert in that buffer. To avoid setting the current buffer semipermanently, these filter functions must save and restore the current buffer. They should also update the process marker, and in some cases update the value of point. Here is how to do these things:
(defun ordinary-insertion-filter (proc string)
  (with-current-buffer (process-buffer proc)
    (let ((moving (= (point) (process-mark proc))))
      (save-excursion
        ;; Insert the text, advancing the process marker.
        (goto-char (process-mark proc))
        (insert string)
        (set-marker (process-mark proc) (point)))
      (if moving (goto-char (process-mark proc))))))
The reason to use with-current-buffer, rather than using save-excursion to save and restore the current buffer, is so as to preserve the change in point made by the second call to goto-char.

To make the filter force the process buffer to be visible whenever new text arrives, insert the following line just before the with-current-buffer construct:
(display-buffer (process-buffer proc))
To force point to the end of the new output, no matter where it was previously, eliminate the variable moving and call goto-char unconditionally.

In earlier Emacs versions, every filter function that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for filter functions; they never need to do it explicitly. See section The Match Data.

A filter function that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. The expression (buffer-name (process-buffer process)) returns nil if the buffer is dead.

The output to the function may come in chunks of any size. A program that produces the same output twice in a row may send it as one batch of 200 characters one time, and five batches of 40 characters the next. If the filter looks for certain text strings in the subprocess output, make sure to handle the case where one of these strings is split across two or more batches of output.

Function: set-process-filter process filter
This function gives process the filter function filter. If filter is nil, it gives the process no filter.

Function: process-filter process
This function returns the filter function of process, or nil if it has none.

Here is an example of use of a filter function:
(defun keep-output (process output)
   (setq kept (cons output kept)))
     => keep-output
(setq kept nil)
     => nil
(set-process-filter (get-process "shell") 'keep-output)
     => keep-output
(process-send-string "shell" "ls ~/other\n")
     => nil
kept
     => ("lewis@slug[8] % "
"FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
address.txt             backup.psf              kolstad.psf
backup.bib~             david.mss               resume-Dec-86.mss~
backup.err              david.psf               resume-Dec.psf
backup.mss              dland                   syllabus.mss
"
"#backups.mss#          backup.mss~             kolstad.mss
")
Accepting Output from Processes

Output from asynchronous subprocesses normally arrives only while Emacs is waiting for some sort of external event, such as elapsed time or terminal input. Occasionally it is useful in a Lisp program to explicitly permit output to arrive at a specific point, or even to wait until output arrives from a process.

Function: accept-process-output &optional process seconds millisec
This function allows Emacs to read pending output from processes. The output is inserted in the associated buffers or given to their filter functions. If process is non-nil then this function does not return until some output has been received from process.

The arguments seconds and millisec let you specify timeout periods. The former specifies a period measured in seconds and the latter specifies one measured in milliseconds. The two time periods thus specified are added together, and accept-process-output returns after that much time whether or not there has been any subprocess output.

The argument seconds need not be an integer. If it is a floating point number, this function waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, seconds is rounded down.

Not all operating systems support waiting periods other than multiples of a second; on those that do not, you get an error if you specify nonzero millisec.

The function accept-process-output returns non-nil if it did get some output, or nil if the timeout expired before output arrived.

Sentinels: Detecting Process Status Changes

A process sentinel is a function that is called whenever the associated process changes status for any reason, including signals (whether sent by Emacs or caused by the process's own actions) that terminate, stop, or continue the process. The process sentinel is also called if the process exits. The sentinel receives two arguments: the process for which the event occurred, and a string describing the type of event.

The string describing the event looks like one of the following:

"finished\n".
"exited abnormally with code exitcode\n".
"name-of-signal\n".
"name-of-signal (core dumped)\n".

A sentinel runs only while Emacs is waiting (e.g., for terminal input, or for time to elapse, or for process output). This avoids the timing errors that could result from running them at random places in the middle of other Lisp programs. A program can wait, so that sentinels will run, by calling sit-for or sleep-for (see section Waiting for Elapsed Time or Input), or accept-process-output (see section Accepting Output from Processes). Emacs also allows sentinels to run when the command loop is reading input.

Quitting is normally inhibited within a sentinel--otherwise, the effect of typing C-g at command level or to quit a user command would be unpredictable. If you want to permit quitting inside a sentinel, bind inhibit-quit to nil. See section Quitting.

A sentinel that writes the output into the buffer of the process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. If the buffer is dead, (buffer-name (process-buffer process)) returns nil.

If an error happens during execution of a sentinel, it is caught automatically, so that it doesn't stop the execution of whatever programs was running when the sentinel was started. However, if debug-on-error is non-nil, the error-catching is turned off. This makes it possible to use the Lisp debugger to debug the sentinel. See section The Lisp Debugger.

In earlier Emacs versions, every sentinel that did regular expression searching or matching had to explicitly save and restore the match data. Now Emacs does this automatically for sentinels; they never need to do it explicitly. See section The Match Data.

Function: set-process-sentinel process sentinel
This function associates sentinel with process. If sentinel is nil, then the process will have no sentinel. The default behavior when there is no sentinel is to insert a message in the process's buffer when the process status changes.
(defun msg-me (process event)
   (princ
     (format "Process: %s had the event `%s'" process event)))
(set-process-sentinel (get-process "shell") 'msg-me)
     => msg-me
(kill-process (get-process "shell"))
     -| Process: #<process shell> had the event `killed'
     => #<process shell>
Function: process-sentinel process
This function returns the sentinel of process, or nil if it has none.

Function: waiting-for-user-input-p
While a sentinel or filter function is running, this function returns non-nil if Emacs was waiting for keyboard input from the user at the time the sentinel or filter function was called, nil if it was not.

Transaction Queues

You can use a transaction queue to communicate with a subprocess using transactions. First use tq-create to create a transaction queue communicating with a specified process. Then you can call tq-enqueue to send a transaction.

Function: tq-create process
This function creates and returns a transaction queue communicating with process. The argument process should be a subprocess capable of sending and receiving streams of bytes. It may be a child process, or it may be a TCP connection to a server, possibly on another machine.

Function: tq-enqueue queue question regexp closure fn
This function sends a transaction to queue queue. Specifying the queue has the effect of specifying the subprocess to talk to.

The argument question is the outgoing message that starts the transaction. The argument fn is the function to call when the corresponding answer comes back; it is called with two arguments: closure, and the answer received.

The argument regexp is a regular expression that should match the entire answer, but nothing less; that's how tq-enqueue determines where the answer ends.

The return value of tq-enqueue itself is not meaningful.

Function: tq-close queue
Shut down transaction queue queue, waiting for all pending transactions to complete, and then terminate the connection or child process.

Transaction queues are implemented by means of a filter function. See section Process Filter Functions.

Network Connections

Emacs Lisp programs can open TCP network connections to other processes on the same machine or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object. However, the process you are communicating with is not a child of the Emacs process, so you can't kill it or send it signals. All you can do is send and receive data. delete-process closes the connection, but does not kill the process at the other end; that process must decide what to do about closure of the connection.

You can distinguish process objects representing network connections from those representing subprocesses with the process-status function. It always returns either open or closed for a network connection, and it never returns either of those values for a real subprocess. See section Process Information.

Function: open-network-stream name buffer-or-name host service
This function opens a TCP connection for a service to a host. It returns a process object to represent the connection.

The name argument specifies the name for the process object. It is modified as necessary to make it unique.

The buffer-or-name argument is the buffer to associate with the connection. Output from the connection is inserted in the buffer, unless you specify a filter function to handle the output. If buffer-or-name is nil, it means that the connection is not associated with any buffer.

The arguments host and service specify where to connect to; host is the host name (a string), and service is the name of a defined network service (a string) or a port number (an integer).

Operating System Interface

This chapter is about starting and getting out of Emacs, access to values in the operating system environment, and terminal input, output, and flow control.

See section Building Emacs, for related information. See also section Emacs Display, for additional operating system status information pertaining to the terminal and the screen.

Starting Up Emacs

This section describes what Emacs does when it is started, and how you can customize these actions.

Summary: Sequence of Actions at Start Up

The order of operations performed (in `startup.el') by Emacs when it is started up is as follows:

It adds subdirectories to load-path, by running the file named `subdirs.el' in each directory that is listed.
It sets the language environment and the terminal coding system, if requested by environment variables such as LANG.
It loads the initialization library for the window system, if you are using a window system. This library's name is `term/windowsystem-win.el'.
It processes the initial options. (Some of them are handled even earlier than this.)
It initializes the window frame and faces, if appropriate.
It runs the normal hook before-init-hook.
It loads the library `site-start', unless the option `-no-site-file' was specified. The library's file name is usually `site-start.el'.
It loads the file `~/.emacs', unless `-q' or `-batch' was specified on the command line. The `-u' option can specify another user name whose home directory should be used instead of `~'.
It loads the library `default', unless inhibit-default-init is non-nil. (This is not done in `-batch' mode or if `-q' was specified on the command line.) The library's file name is usually `default.el'.
It runs the normal hook after-init-hook.
It sets the major mode according to initial-major-mode, provided the buffer `*scratch*' is still current and still in Fundamental mode.
It loads the terminal-specific Lisp file, if any, except when in batch mode or using a window system.
It displays the initial echo area message, unless you have suppressed that with inhibit-startup-echo-area-message.
It processes the action arguments from the command line.
It runs term-setup-hook.
It calls frame-notice-user-settings, which modifies the parameters of the selected frame according to whatever the init files specify.
It runs window-setup-hook. See section Window Systems.
It displays copyleft, nonwarranty, and basic use information, provided there were no remaining command line arguments (a few steps above), the value of inhibit-startup-message is nil, and the buffer is still empty.

User Option: inhibit-startup-message
This variable inhibits the initial startup messages (the nonwarranty, etc.). If it is non-nil, then the messages are not printed.

This variable exists so you can set it in your personal init file, once you are familiar with the contents of the startup message. Do not set this variable in the init file of a new user, or in a way that affects more than one user, because that would prevent new users from receiving the information they are supposed to see.

User Option: inhibit-startup-echo-area-message
This variable controls the display of the startup echo area message. You can suppress the startup echo area message by adding text with this form to your `.emacs' file:
(setq inhibit-startup-echo-area-message
      "your-login-name")
Emacs explicitly checks for an expression as shown above in your `.emacs' file; your login name must appear in the expression as a Lisp string constant. Other methods of setting inhibit-startup-echo-area-message to the same value do not inhibit the startup message.

This way, you can easily inhibit the message for yourself if you wish, but thoughtless copying of your `.emacs' file will not inhibit the message for someone else.

The Init File: `.emacs'

When you start Emacs, it normally attempts to load the file `.emacs' from your home directory. This file, if it exists, must contain Lisp code. It is called your init file. The command line switches `-q' and `-u' affect the use of the init file; `-q' says not to load an init file, and `-u' says to load a specified user's init file instead of yours. See section `Entering Emacs' in The GNU Emacs Manual.

A site may have a default init file, which is the library named `default.el'. Emacs finds the `default.el' file through the standard search path for libraries (see section How Programs Do Loading). The Emacs distribution does not come with this file; sites may provide one for local customizations. If the default init file exists, it is loaded whenever you start Emacs, except in batch mode or if `-q' is specified. But your own personal init file, if any, is loaded first; if it sets inhibit-default-init to a non-nil value, then Emacs does not subsequently load the `default.el' file.

Another file for site-customization is `site-start.el'. Emacs loads this before the user's init file. You can inhibit the loading of this file with the option `-no-site-file'.

Variable: site-run-file
This variable specifies the site-customization file to load before the user's init file. Its normal value is "site-start". The only way you can change it with real effect is to do so before dumping Emacs.

If there is a great deal of code in your `.emacs' file, you should move it into another file named `something.el', byte-compile it (see section Byte Compilation), and make your `.emacs' file load the other file using load (see section Loading).

See section `Init File Examples' in The GNU Emacs Manual, for examples of how to make various commonly desired customizations in your `.emacs' file.

User Option: inhibit-default-init
This variable prevents Emacs from loading the default initialization library file for your session of Emacs. If its value is non-nil, then the default library is not loaded. The default value is nil.

Variable: before-init-hook
This normal hook is run, once, just before loading all the init files (the user's init file, `default.el', and/or `site-start.el'). (The only way to change it with real effect is before dumping Emacs.)

Variable: after-init-hook
This normal hook is run, once, just after loading all the init files (the user's init file, `default.el', and/or `site-start.el'), before the terminal-specific initialization.

Terminal-Specific Initialization

Each terminal type can have its own Lisp library that Emacs loads when run on that type of terminal. The library's name is constructed by concatenating the value of the variable term-file-prefix and the terminal type. Normally, term-file-prefix has the value "term/"; changing this is not recommended. Emacs finds the file in the normal manner, by searching the load-path directories, and trying the `.elc' and `.el' suffixes.

The usual function of a terminal-specific library is to enable special keys to send sequences that Emacs can recognize. It may also need to set or add to function-key-map if the Termcap entry does not specify all the terminal's function keys. See section Terminal Input.

When the name of the terminal type contains a hyphen, only the part of the name before the first hyphen is significant in choosing the library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use the `term/aaa' library. If necessary, the library can evaluate (getenv "TERM") to find the full name of the terminal type.

Your `.emacs' file can prevent the loading of the terminal-specific library by setting the variable term-file-prefix to nil. This feature is useful when experimenting with your own peculiar customizations.

You can also arrange to override some of the actions of the terminal-specific library by setting the variable term-setup-hook. This is a normal hook which Emacs runs using run-hooks at the end of Emacs initialization, after loading both your `.emacs' file and any terminal-specific libraries. You can use this variable to define initializations for terminals that do not have their own libraries. See section Hooks.

Variable: term-file-prefix
If the term-file-prefix variable is non-nil, Emacs loads a terminal-specific initialization file as follows:
(load (concat term-file-prefix (getenv "TERM")))
You may set the term-file-prefix variable to nil in your `.emacs' file if you do not wish to load the terminal-initialization file. To do this, put the following in your `.emacs' file: (setq term-file-prefix nil).

Variable: term-setup-hook
This variable is a normal hook that Emacs runs after loading your `.emacs' file, the default initialization file (if any) and the terminal-specific Lisp file.

You can use term-setup-hook to override the definitions made by a terminal-specific file.

See window-setup-hook in section Window Systems, for a related feature.

Command Line Arguments

You can use command line arguments to request various actions when you start Emacs. Since you do not need to start Emacs more than once per day, and will often leave your Emacs session running longer than that, command line arguments are hardly ever used. As a practical matter, it is best to avoid making the habit of using them, since this habit would encourage you to kill and restart Emacs unnecessarily often. These options exist for two reasons: to be compatible with other editors (for invocation by other programs) and to enable shell scripts to run specific Lisp programs.

This section describes how Emacs processes command line arguments, and how you can customize them.

Function: command-line
This function parses the command line that Emacs was called with, processes it, loads the user's `.emacs' file and displays the startup messages.

Variable: command-line-processed
The value of this variable is t once the command line has been processed.

If you redump Emacs by calling dump-emacs, you may wish to set this variable to nil first in order to cause the new dumped Emacs to process its new command line arguments.

Variable: command-switch-alist
The value of this variable is an alist of user-defined command-line options and associated handler functions. This variable exists so you can add elements to it.

A command line option is an argument on the command line of the form:
-option
The elements of the command-switch-alist look like this:
(option . handler-function)
The handler-function is called to handle option and receives the option name as its sole argument.

In some cases, the option is followed in the command line by an argument. In these cases, the handler-function can find all the remaining command-line arguments in the variable command-line-args-left. (The entire list of command-line arguments is in command-line-args.)

The command line arguments are parsed by the command-line-1 function in the `startup.el' file. See also section `Command Line Switches and Arguments' in The GNU Emacs Manual.

Variable: command-line-args
The value of this variable is the list of command line arguments passed to Emacs.

Variable: command-line-functions
This variable's value is a list of functions for handling an unrecognized command-line argument. Each time the next argument to be processed has no special meaning, the functions in this list are called, in order of appearance, until one of them returns a non-nil value.

These functions are called with no arguments. They can access the command-line argument under consideration through the variable argi, which is bound temporarily at this point. The remaining arguments (not including the current one) are in the variable command-line-args-left.

When a function recognizes and processes the argument in argi, it should return a non-nil value to say it has dealt with that argument. If it has also dealt with some of the following arguments, it can indicate that by deleting them from command-line-args-left.

If all of these functions return nil, then the argument is used as a file name to visit.

Getting Out of Emacs

There are two ways to get out of Emacs: you can kill the Emacs job, which exits permanently, or you can suspend it, which permits you to reenter the Emacs process later. As a practical matter, you seldom kill Emacs--only when you are about to log out. Suspending is much more common.

Killing Emacs

Killing Emacs means ending the execution of the Emacs process. The parent process normally resumes control. The low-level primitive for killing Emacs is kill-emacs.

Function: kill-emacs &optional exit-data
This function exits the Emacs process and kills it.

If exit-data is an integer, then it is used as the exit status of the Emacs process. (This is useful primarily in batch operation; see section Batch Mode.)

If exit-data is a string, its contents are stuffed into the terminal input buffer so that the shell (or whatever program next reads input) can read them.

All the information in the Emacs process, aside from files that have been saved, is lost when the Emacs is killed. Because killing Emacs inadvertently can lose a lot of work, Emacs queries for confirmation before actually terminating if you have buffers that need saving or subprocesses that are running. This is done in the function save-buffers-kill-emacs.

Variable: kill-emacs-query-functions
After asking the standard questions, save-buffers-kill-emacs calls the functions in the list kill-emacs-query-functions, in order of appearance, with no arguments. These functions can ask for additional confirmation from the user. If any of them returns nil, Emacs is not killed.

Variable: kill-emacs-hook
This variable is a normal hook; once save-buffers-kill-emacs is finished with all file saving and confirmation, it runs the functions in this hook.

Suspending Emacs

Suspending Emacs means stopping Emacs temporarily and returning control to its superior process, which is usually the shell. This allows you to resume editing later in the same Emacs process, with the same buffers, the same kill ring, the same undo history, and so on. To resume Emacs, use the appropriate command in the parent shell--most likely fg.

Some operating systems do not support suspension of jobs; on these systems, "suspension" actually creates a new shell temporarily as a subprocess of Emacs. Then you would exit the shell to return to Emacs.

Suspension is not useful with window systems, because the Emacs job may not have a parent that can resume it again, and in any case you can give input to some other job such as a shell merely by moving to a different window. Therefore, suspending is not allowed when Emacs is using a window system.

Function: suspend-emacs string
This function stops Emacs and returns control to the superior process. If and when the superior process resumes Emacs, suspend-emacs returns nil to its caller in Lisp.

If string is non-nil, its characters are sent to be read as terminal input by Emacs's superior shell. The characters in string are not echoed by the superior shell; only the results appear.

Before suspending, suspend-emacs runs the normal hook suspend-hook.

After the user resumes Emacs, suspend-emacs runs the normal hook suspend-resume-hook. See section Hooks.

The next redisplay after resumption will redraw the entire screen, unless the variable no-redraw-on-reenter is non-nil (see section Refreshing the Screen).

In the following example, note that `pwd' is not echoed after Emacs is suspended. But it is read and executed by the shell.
(suspend-emacs)
     => nil

(add-hook 'suspend-hook
          (function (lambda ()
                      (or (y-or-n-p
                            "Really suspend? ")
                          (error "Suspend cancelled")))))
     => (lambda nil
          (or (y-or-n-p "Really suspend? ")
              (error "Suspend cancelled")))
(add-hook 'suspend-resume-hook
          (function (lambda () (message "Resumed!"))))
     => (lambda nil (message "Resumed!"))
(suspend-emacs "pwd")
     => nil
---------- Buffer: Minibuffer ----------
Really suspend? y
---------- Buffer: Minibuffer ----------

---------- Parent Shell ----------
lewis@slug[23] % /user/lewis/manual
lewis@slug[24] % fg

---------- Echo Area ----------
Resumed!
Variable: suspend-hook
This variable is a normal hook run before suspending.

Variable: suspend-resume-hook
This variable is a normal hook run after suspending.

Operating System Environment

Emacs provides access to variables in the operating system environment through various functions. These variables include the name of the system, the user's UID, and so on.

Variable: system-configuration
This variable holds the GNU configuration name for the hardware/software configuration of your system, as a string. The convenient way to test parts of this string is with string-match.

Variable: system-type
The value of this variable is a symbol indicating the type of operating system Emacs is operating on. Here is a table of the possible values:

alpha-vms
VMS on the Alpha.
aix-v3
AIX.
berkeley-unix
Berkeley BSD.
dgux
Data General DGUX operating system.
gnu
the GNU system (using the GNU kernel, which consists of the HURD and Mach).
gnu/linux
A GNU/Linux system--that is, a variant GNU system, using the Linux kernel. (These systems are the ones people often call "Linux," but actually Linux is just the kernel, not the whole system.)
hpux
Hewlett-Packard HPUX operating system.
irix
Silicon Graphics Irix system.
ms-dos
Microsoft MS-DOS "operating system."
next-mach
NeXT Mach-based system.
rtu
Masscomp RTU, UCB universe.
unisoft-unix
UniSoft UniPlus.
usg-unix-v
AT&T System V.
vax-vms
VAX VMS.
windows-nt
Microsoft windows NT.
xenix
SCO Xenix 386.
We do not wish to add new symbols to make finer distinctions unless it is absolutely necessary! In fact, we hope to eliminate some of these alternatives in the future. We recommend using system-configuration to distinguish between different operating systems.

Function: system-name
This function returns the name of the machine you are running on.
(system-name)
     => "www.gnu.org"
The symbol system-name is a variable as well as a function. In fact, the function returns whatever value the variable system-name currently holds. Thus, you can set the variable system-name in case Emacs is confused about the name of your system. The variable is also useful for constructing frame titles (see section Frame Titles).

Variable: mail-host-address
If this variable is non-nil, it is used instead of system-name for purposes of generating email addresses. For example, it is used when constructing the default value of user-mail-address. See section User Identification. (Since this is done when Emacs starts up, the value actually used is the one saved when Emacs was dumped. See section Building Emacs.)

Function: getenv var
This function returns the value of the environment variable var, as a string. Within Emacs, the environment variable values are kept in the Lisp variable process-environment.
(getenv "USER")
     => "lewis"

lewis@slug[10] % printenv
PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
USER=lewis
TERM=ibmapa16
SHELL=/bin/csh
HOME=/user/lewis
Command: setenv variable value
This command sets the value of the environment variable named variable to value. Both arguments should be strings. This function works by modifying process-environment; binding that variable with let is also reasonable practice.

Variable: process-environment
This variable is a list of strings, each describing one environment variable. The functions getenv and setenv work by means of this variable.
process-environment
=> ("l=/usr/stanford/lib/gnuemacs/lisp"
    "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
    "USER=lewis"
    "TERM=ibmapa16"
    "SHELL=/bin/csh"
    "HOME=/user/lewis")
Variable: path-separator
This variable holds a string which says which character separates directories in a search path (as found in an environment variable). Its value is ":" for Unix and GNU systems, and ";" for MS-DOS and Windows NT.

Variable: invocation-name
This variable holds the program name under which Emacs was invoked. The value is a string, and does not include a directory name.

Variable: invocation-directory
This variable holds the directory from which the Emacs executable was invoked, or perhaps nil if that directory cannot be determined.

Variable: installation-directory
If non-nil, this is a directory within which to look for the `lib-src' and `etc' subdirectories. This is non-nil when Emacs can't find those directories in their standard installed locations, but can find them in a directory related somehow to the one containing the Emacs executable.

Function: load-average &optional use-float
This function returns the current 1-minute, 5-minute, and 15-minute load averages, in a list.

By default, the values are integers that are 100 times the system load averages, which indicate the average number of processes trying to run. If use-float is non-nil, then they are returned as floating point numbers and without multiplying by 100.
(load-average)
     => (169 48 36)
(load-average t)
     => (1.69 0.48 0.36)

lewis@rocky[5] % uptime
 11:55am  up 1 day, 19:37,  3 users,
 load average: 1.69, 0.48, 0.36
Function: emacs-pid
This function returns the process ID of the Emacs process.

Variable: tty-erase-char
This variable holds the erase character that was selected in the system's terminal driver, before Emacs was started.

Function: setprv privilege-name &optional setp getprv
This function sets or resets a VMS privilege. (It does not exist on Unix.) The first arg is the privilege name, as a string. The second argument, setp, is t or nil, indicating whether the privilege is to be turned on or off. Its default is nil. The function returns t if successful, nil otherwise.

If the third argument, getprv, is non-nil, setprv does not change the privilege, but returns t or nil indicating whether the privilege is currently enabled.

User Identification

Variable: init-file-user
This variable says which user's init files should be used by Emacs--or nil if none. The value reflects command line options such as `-q' or `-u user'.

Lisp packages that load files of customizations, or any other sort of user profile, should obey this variable in deciding where to find it. They should load the profile of the user name found in this variable. If init-file-user is nil, meaning that the `-q' option was used, then Lisp packages should not load any customization files or user profile.

Variable: user-mail-address
This holds the nominal email address of the user who is using Emacs. Emacs normally sets this variable to a default value after reading your init files, but not if you have already set it. So you can set the variable to some other value in your `~/.emacs' file if you do not want to use the default value.

Function: user-login-name &optional uid
If you don't specify uid, this function returns the name under which the user is logged in. If the environment variable LOGNAME is set, that value is used. Otherwise, if the environment variable USER is set, that value is used. Otherwise, the value is based on the effective UID, not the real UID.

If you specify uid, the value is the user name that corresponds to uid (which should be an integer).
(user-login-name)
     => "lewis"
Function: user-real-login-name
This function returns the user name corresponding to Emacs's real UID. This ignores the effective UID and ignores the environment variables LOGNAME and USER.

Function: user-full-name &optional uid
This function returns the full name of the logged-in user--or the value of the environment variables NAME, if that is set.
(user-full-name)
     => "Bil Lewis"
If uid is non-nil, then it should be an integer, a user-id, or a string, a login name. Then user-full-name returns the full name corresponding to that user-id or login name.

The symbols user-login-name, user-real-login-name and user-full-name are variables as well as functions. The functions return the same values that the variables hold. These variables allow you to "fake out" Emacs by telling the functions what to return. The variables are also useful for constructing frame titles (see section Frame Titles).

Function: user-real-uid
This function returns the real UID of the user.
(user-real-uid)
     => 19
Function: user-uid
This function returns the effective UID of the user.

Time of Day

This section explains how to determine the current time and the time zone.

Function: current-time-string &optional time-value
This function returns the current time and date as a human-readable string. The format of the string is unvarying; the number of characters used for each part is always the same, so you can reliably use substring to extract pieces of it. It is wise to count the characters from the beginning of the string rather than from the end, as additional information may some day be added at the end.

The argument time-value, if given, specifies a time to format instead of the current time. The argument should be a list whose first two elements are integers. Thus, you can use times obtained from current-time (see below) and from file-attributes (see section Other Information about Files).
(current-time-string)
     => "Wed Oct 14 22:21:05 1987"
Function: current-time
This function returns the system's time value as a list of three integers: (high low microsec). The integers high and low combine to give the number of seconds since 0:00 January 1, 1970, which is

The third element, microsec, gives the microseconds since the start of the current second (or 0 for systems that return time only on the resolution of a second).

The first two elements can be compared with file time values such as you get with the function file-attributes. See section Other Information about Files.

Function: current-time-zone &optional time-value
This function returns a list describing the time zone that the user is in.

The value has the form (offset name). Here offset is an integer giving the number of seconds ahead of UTC (east of Greenwich). A negative value means west of Greenwich. The second element, name is a string giving the name of the time zone. Both elements change when daylight savings time begins or ends; if the user has specified a time zone that does not use a seasonal time adjustment, then the value is constant through time.

If the operating system doesn't supply all the information necessary to compute the value, both elements of the list are nil.

The argument time-value, if given, specifies a time to analyze instead of the current time. The argument should be a cons cell containing two integers, or a list whose first two elements are integers. Thus, you can use times obtained from current-time (see above) and from file-attributes (see section Other Information about Files).

Time Conversion

These functions convert time values (lists of two or three integers) to strings or to calendrical information. There is also a function to convert calendrical information to a time value. You can get time values from the functions current-time (see section Time of Day) and file-attributes (see section Other Information about Files).

Many operating systems are limited to time values that contain 32 bits of information; these systems typically handle only the times from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some operating systems have larger time values, and can represent times far in the past or future.

Time conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers count the number of years since the year 1 B.C., and do not skip zero as traditional Gregorian years do; for example, the year number -37 represents the Gregorian year 38 B.C.

Function: format-time-string format-string time
This function converts time to a string according to format-string. The argument format-string may contain `%'-sequences which say to substitute parts of the time. Here is a table of what the `%'-sequences mean:

`%a'
This stands for the abbreviated name of the day of week.
`%A'
This stands for the full name of the day of week.
`%b'
This stands for the abbreviated name of the month.
`%B'
This stands for the full name of the month.
`%c'
This is a synonym for `%x %X'.
`%C'
This has a locale-specific meaning. In the default locale (named C), it is equivalent to `%A, %B %e, %Y'.
`%d'
This stands for the day of month, zero-padded.
`%D'
This is a synonym for `%m/%d/%y'.
`%e'
This stands for the day of month, blank-padded.
`%h'
This is a synonym for `%b'.
`%H'
This stands for the hour (00-23).
`%I'
This stands for the hour (00-12).
`%j'
This stands for the day of the year (001-366).
`%k'
This stands for the hour (0-23), blank padded.
`%l'
This stands for the hour (1-12), blank padded.
`%m'
This stands for the month (01-12).
`%M'
This stands for the minute (00-59).
`%n'
This stands for a newline.
`%p'
This stands for `AM' or `PM', as appropriate.
`%r'
This is a synonym for `%I:%M:%S %p'.
`%R'
This is a synonym for `%H:%M'.
`%S'
This stands for the seconds (00-60).
`%t'
This stands for a tab character.
`%T'
This is a synonym for `%H:%M:%S'.
`%U'
This stands for the week of the year (01-52), assuming that weeks start on Sunday.
`%w'
This stands for the numeric day of week (0-6). Sunday is day 0.
`%W'
This stands for the week of the year (01-52), assuming that weeks start on Monday.
`%x'
This has a locale-specific meaning. In the default locale (named `C'), it is equivalent to `%D'.
`%X'
This has a locale-specific meaning. In the default locale (named `C'), it is equivalent to `%T'.
`%y'
This stands for the year without century (00-99).
`%Y'
This stands for the year with century.
`%Z'
This stands for the time zone abbreviation.
You can also specify the field width and type of padding for any of these `%'-sequences. This works as in printf: you write the field width as digits in the middle of a `%'-sequences. If you start the field width with `0', it means to pad with zeros. If you start the field width with `_', it means to pad with spaces.

For example, `%S' specifies the number of seconds since the minute; `%03S' means to pad this with zeros to 3 positions, `%_3S' to pad with spaces to 3 positions. Plain `%3S' pads with zeros, because that is how `%S' normally pads to two positions.

Function: decode-time time
This function converts a time value into calendrical information. The return value is a list of nine elements, as follows:
(seconds minutes hour day month year dow dst zone)
Here is what the elements mean:

sec
The number of seconds past the minute, as an integer between 0 and 59.
minute
The number of minutes past the hour, as an integer between 0 and 59.
hour
The hour of the day, as an integer between 0 and 23.
day
The day of the month, as an integer between 1 and 31.
month
The month of the year, as an integer between 1 and 12.
year
The year, an integer typically greater than 1900.
dow
The day of week, as an integer between 0 and 6, where 0 stands for Sunday.
dst
t if daylight savings time is effect, otherwise nil.
zone
An integer indicating the time zone, as the number of seconds east of Greenwich.
Common Lisp Note: Common Lisp has different meanings for dow and zone.

Function: encode-time seconds minutes hour day month year &optional ...zone
This function is the inverse of decode-time. It converts seven items of calendrical data into a time value. For the meanings of the arguments, see the table above under decode-time.

Year numbers less than 100 are treated just like other year numbers. If you want them to stand for years above 1900, you must alter them yourself before you call encode-time.

The optional argument zone defaults to the current time zone and its daylight savings time rules. If specified, it can be either a list (as you would get from current-time-zone), a string as in the TZ environment variable, or an integer (as you would get from decode-time). The specified zone is used without any further alteration for daylight savings time.

If you pass more than seven arguments to encode-time, the first six are used as seconds through year, the last argument is used as zone, and the arguments in between are ignored. This feature makes it possible to use the elements of a list returned by decode-time as the arguments to encode-time, like this:
(apply 'encode-time (decode-time ...))
You can perform simple date arithmetic by using out-of-range values for the sec, minute, hour, day, and month arguments; for example, day 0 means the day preceding the given month.

The operating system puts limits on the range of possible time values; if you try to encode a time that is out of range, an error results.

Timers for Delayed Execution

You can set up a timer to call a function at a specified future time or after a certain length of idleness.

Emacs cannot run timers at any arbitrary point in a Lisp program; it can run them only when Emacs could accept output from a subprocess: namely, while waiting or inside certain primitive functions such as sit-for or read-event which can wait. Therefore, a timer's execution may be delayed if Emacs is busy. However, the time of execution is very precise if Emacs is idle.

Function: run-at-time time repeat function &rest args
This function arranges to call function with arguments args at time time. The argument function is a function to call later, and args are the arguments to give it when it is called. The time time is specified as a string.

Absolute times may be specified in a wide variety of formats; this function tries to accept all the commonly used date formats. Valid formats include these two,
year-month-day hour:min:sec timezone

hour:min:sec timezone month/day/year
where in both examples all fields are numbers; the format that current-time-string returns is also allowed, and many others as well.

To specify a relative time, use numbers followed by units. For example:

`1 min'
denotes 1 minute from now.
`1 min 5 sec'
denotes 65 seconds from now.
`1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year'
denotes exactly 103 months, 123 days, and 10862 seconds from now.
If time is a number (integer or floating point), that specifies a relative time measured in seconds.

The argument repeat specifies how often to repeat the call. If repeat is nil, there are no repetitions; function is called just once, at time. If repeat is a number, it specifies a repetition period measured in seconds.

In most cases, repeat has no effect on when first call takes place---time alone specifies that. There is one exception: if time is t, then the timer runs whenever the time is a multiple of repeat seconds after the epoch. This is useful for functions like display-time.

The function run-at-time returns a timer value that identifies the particular scheduled future action. You can use this value to call cancel-timer (see below).

Macro: with-timeout (seconds timeout-forms...) body...
Execute body, but give up after seconds seconds. If body finishes before the time is up, with-timeout returns the value of the last form in body. If, however, the execution of body is cut short by the timeout, then with-timeout executes all the timeout-forms and returns the value of the last of them.

This macro works by setting a timer to run after seconds seconds. If body finishes before that time, it cancels the timer. If the timer actually runs, it terminates execution of body, then executes timeout-forms.

Since timers can run within a Lisp program only when the program calls a primitive that can wait, with-timeout cannot stop executing body while it is in the midst of a computation--only when it calls one of those primitives. So use with-timeout only with a body that waits for input, not one that does a long computation.

The function y-or-n-p-with-timeout provides a simple way to use a timer to avoid waiting too long for an answer. See section Yes-or-No Queries.

Function: run-with-idle-timer secs repeat function &rest args
Set up a timer which runs when Emacs has been idle for secs seconds. The value of secs may be an integer or a floating point number.

If repeat is nil, the timer runs just once, the first time Emacs remains idle for a long enough time. More often repeat is non-nil, which means to run the timer each time Emacs remains idle for secs seconds.

The function run-with-idle-timer returns a timer value which you can use in calling cancel-timer (see below).

Emacs becomes "idle" when it starts waiting for user input, and it remains idle until the user provides some input. If a timer is set for five seconds of idleness, it runs approximately five seconds after Emacs first became idle. Even if its repeat is true, this timer will not run again as long as Emacs remains idle, because the duration of idleness will continue to increase and will not go down to five seconds again.

Emacs can do various things while idle: garbage collect, autosave or handle data from a subprocess. But these interludes during idleness do not interfere with idle timers, because they do not reset the clock of idleness to zero. An idle timer set for 600 seconds will run when ten minutes have elapsed since the last user command was finished, even if subprocess output has been accepted thousands of times within those ten minutes, even if there have been garbage collections and autosaves.

When the user supplies input, Emacs becomes non-idle while executing the input. Then it becomes idle again, and all the idle timers that are set up to repeat will subsequently run another time, one by one.

Function: cancel-timer timer
Cancel the requested action for timer, which should be a value previously returned by run-at-time or run-with-idle-timer. This cancels the effect of that call to run-at-time; the arrival of the specified time will not cause anything special to happen.

Terminal Input

This section describes functions and variables for recording or manipulating terminal input. See section Emacs Display, for related functions.

Input Modes

Function: set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input. If interrupt is non-null, then Emacs uses input interrupts. If it is nil, then it uses CBREAK mode. The default setting is system dependent. Some systems always use CBREAK mode regardless of what is specified.

When Emacs communicates directly with X, it ignores this argument and uses interrupts if that is the way it knows how to communicate.

If flow is non-nil, then Emacs uses XON/XOFF (C-q, C-s) flow control for output to the terminal. This has no effect except in CBREAK mode. See section Flow Control.

The argument meta controls support for input character codes above 127. If meta is t, Emacs converts characters with the 8th bit set into Meta characters. If meta is nil, Emacs disregards the 8th bit; this is necessary when the terminal uses it as a parity bit. If meta is neither t nor nil, Emacs uses all 8 bits of input unchanged. This is good for terminals that use 8-bit character sets.

If quit-char is non-nil, it specifies the character to use for quitting. Normally this character is C-g. See section Quitting.

The current-input-mode function returns the input mode settings Emacs is currently using.

Function: current-input-mode
This function returns current mode for reading keyboard input. It returns a list, corresponding to the arguments of set-input-mode, of the form (interrupt flow meta quit) in which:
interrupt
is non-nil when Emacs is using interrupt-driven input. If nil, Emacs is using CBREAK mode.
flow
is non-nil if Emacs uses XON/XOFF (C-q, C-s) flow control for output to the terminal. This value is meaningful only when interrupt is nil.
meta
is t if Emacs treats the eighth bit of input characters as the meta bit; nil means Emacs clears the eighth bit of every input character; any other value means Emacs uses all eight bits as the basic character code.
quit
is the character Emacs currently uses for quitting, usually C-g.
Translating Input Events

This section describes features for translating input events into other input events before they become part of key sequences. These features apply to each event in the order they are described here: each event is first modified according to extra-keyboard-modifiers, then translated through keyboard-translate-table (if applicable), and finally decoded with the specified keyboard coding system. If it is being read as part of a key sequence, it is then added to the sequence being read; then subsequences containing it are checked first with function-key-map and then with key-translation-map.

Variable: extra-keyboard-modifiers
This variable lets Lisp programs "press" the modifier keys on the keyboard. The value is a bit mask:

1
The SHIFT key.
2
The LOCK key.
4
The CTL key.
8
The META key.
Each time the user types a keyboard key, it is altered as if the modifier keys specified in the bit mask were held down.

When using a window system, the program can "press" any of the modifier keys in this way. Otherwise, only the CTL and META keys can be virtually pressed.

Variable: keyboard-translate-table
This variable is the translate table for keyboard characters. It lets you reshuffle the keys on the keyboard without changing any command bindings. Its value is normally a char-table, or else nil.

If keyboard-translate-table is a char-table, then each character read from the keyboard is looked up in this character. If the value found there is non-nil, then it is used instead of the actual input character.

In the example below, we set keyboard-translate-table to a char-table. Then we fill it in to swap the characters C-s and C-\ and the characters C-q and C-^. Subsequently, typing C-\ has all the usual effects of typing C-s, and vice versa. (See section Flow Control for more information on this subject.)
(defun evade-flow-control ()
  "Replace C-s with C-\ and C-q with C-^."
  (interactive)
  (setq keyboard-translate-table
        (make-char-table 'keyboard-translate-table nil))
  ;; Swap C-s and C-\.
  (aset keyboard-translate-table ?\034 ?\^s)
  (aset keyboard-translate-table ?\^s ?\034)
  ;; Swap C-q and C-^.
  (aset keyboard-translate-table ?\036 ?\^q)
  (aset keyboard-translate-table ?\^q ?\036))
Note that this translation is the first thing that happens to a character after it is read from the terminal. Record-keeping features such as recent-keys and dribble files record the characters after translation.

Function: keyboard-translate from to
This function modifies keyboard-translate-table to translate character code from into character code to. It creates the keyboard translate table if necessary.

The remaining translation features translate subsequences of key sequences being read. They are implemented in read-key-sequence and have no effect on input read with read-event.

Variable: function-key-map
This variable holds a keymap that describes the character sequences sent by function keys on an ordinary character terminal. This keymap has the same structure as other keymaps, but is used differently: it specifies translations to make while reading key sequences, rather than bindings for key sequences.

If function-key-map "binds" a key sequence k to a vector v, then when k appears as a subsequence anywhere in a key sequence, it is replaced with the events in v.

For example, VT100 terminals send ESC O P when the keypad PF1 key is pressed. Therefore, we want Emacs to translate that sequence of events into the single event pf1. We accomplish this by "binding" ESC O P to [pf1] in function-key-map, when using a VT100.

Thus, typing C-c PF1 sends the character sequence C-c ESC O P; later the function read-key-sequence translates this back into C-c PF1, which it returns as the vector [?\C-c pf1].

Entries in function-key-map are ignored if they conflict with bindings made in the minor mode, local, or global keymaps. The intent is that the character sequences that function keys send should not have command bindings in their own right--but if they do, the ordinary bindings take priority.

The value of function-key-map is usually set up automatically according to the terminal's Terminfo or Termcap entry, but sometimes those need help from terminal-specific Lisp files. Emacs comes with terminal-specific files for many common terminals; their main purpose is to make entries in function-key-map beyond those that can be deduced from Termcap and Terminfo. See section Terminal-Specific Initialization.

Variable: key-translation-map
This variable is another keymap used just like function-key-map to translate input events into other events. It differs from function-key-map in two ways:

key-translation-map goes to work after function-key-map is finished; it receives the results of translation by function-key-map.
key-translation-map overrides actual key bindings. For example, if C-x f has a binding in key-translation-map, that translation takes effect even though C-x f also has a key binding in the global map.

The intent of key-translation-map is for users to map one character set to another, including ordinary characters normally bound to self-insert-command.

You can use function-key-map or key-translation-map for more than simple aliases, by using a function, instead of a key sequence, as the "translation" of a key. Then this function is called to compute the translation of that key.

The key translation function receives one argument, which is the prompt that was specified in read-key-sequence---or nil if the key sequence is being read by the editor command loop. In most cases you can ignore the prompt value.

If the function reads input itself, it can have the effect of altering the event that follows. For example, here's how to define C-c h to turn the character that follows into a Hyper character:
(defun hyperify (prompt)
  (let ((e (read-event)))
    (vector (if (numberp e)
                (logior (lsh 1 24) e)
              (if (memq 'hyper (event-modifiers e))
                  e
                (add-event-modifier "H-" e))))))

(defun add-event-modifier (string e)
  (let ((symbol (if (symbolp e) e (car e))))
    (setq symbol (intern (concat string
                                 (symbol-name symbol))))
    (if (symbolp e)
        symbol
      (cons symbol (cdr e)))))

(define-key function-key-map "\C-ch" 'hyperify)
Finally, if you have enabled keyboard character set decoding using set-keyboard-coding-system, decoding is done after the translations listed above. See section Specifying a Coding System for One Operation. In future Emacs versions, character set decoding may be done before the other translations.

Recording Input

Function: recent-keys
This function returns a vector containing the last 100 input events from the keyboard or mouse. All input events are included, whether or not they were used as parts of key sequences. Thus, you always get the last 100 input events, not counting events generated by keyboard macros. (These are excluded because they are less interesting for debugging; it should be enough to see the events that invoked the macros.)

Command: open-dribble-file filename
This function opens a dribble file named filename. When a dribble file is open, each input event from the keyboard or mouse (but not those from keyboard macros) is written in that file. A non-character event is expressed using its printed representation surrounded by `<...>'.

You close the dribble file by calling this function with an argument of nil.

This function is normally used to record the input necessary to trigger an Emacs bug, for the sake of a bug report.
(open-dribble-file "~/dribble")
     => nil
See also the open-termscript function (see section Terminal Output).

Terminal Output

The terminal output functions send output to the terminal or keep track of output sent to the terminal. The variable baud-rate tells you what Emacs thinks is the output speed of the terminal.

Variable: baud-rate
This variable's value is the output speed of the terminal, as far as Emacs knows. Setting this variable does not change the speed of actual data transmission, but the value is used for calculations such as padding. It also affects decisions about whether to scroll part of the screen or repaint--even when using a window system. (We designed it this way despite the fact that a window system has no true "output speed", to give you a way to tune these decisions.)

The value is measured in baud.

If you are running across a network, and different parts of the network work at different baud rates, the value returned by Emacs may be different from the value used by your local terminal. Some network protocols communicate the local terminal speed to the remote machine, so that Emacs and other programs can get the proper value, but others do not. If Emacs has the wrong value, it makes decisions that are less than optimal. To fix the problem, set baud-rate.

Function: baud-rate
This obsolete function returns the value of the variable baud-rate.

Function: send-string-to-terminal string
This function sends string to the terminal without alteration. Control characters in string have terminal-dependent effects.

One use of this function is to define function keys on terminals that have downloadable function key definitions. For example, this is how on certain terminals to define function key 4 to move forward four characters (by transmitting the characters C-u C-f to the computer):
(send-string-to-terminal "\eF4\^U\^F")
     => nil
Command: open-termscript filename
This function is used to open a termscript file that will record all the characters sent by Emacs to the terminal. It returns nil. Termscript files are useful for investigating problems where Emacs garbles the screen, problems that are due to incorrect Termcap entries or to undesirable settings of terminal options more often than to actual Emacs bugs. Once you are certain which characters were actually output, you can determine reliably whether they correspond to the Termcap specifications in use.

See also open-dribble-file in section Terminal Input.
(open-termscript "../junk/termscript")
     => nil
System-Specific X11 Keysyms

To define system-specific X11 keysyms, set the variable system-key-alist.

Variable: system-key-alist
This variable's value should be an alist with one element for each system-specific keysym. An element has this form: (code . symbol), where code is the numeric keysym code (not including the "vendor specific" bit, and symbol is the name for the function key.

For example (168 . mute-acute) defines a system-specific key used by HP X servers whose numeric code is + 168.

It is not crucial to exclude from the alist the keysyms of other X servers; those do no harm, as long as they don't conflict with the ones used by the X server actually in use.

The variable is always local to the current terminal, and cannot be buffer-local. See section Multiple Displays.

Flow Control

This section attempts to answer the question "Why does Emacs use flow-control characters in its command character set?" For a second view on this issue, read the comments on flow control in the `emacs/INSTALL' file from the distribution; for help with Termcap entries and DEC terminal concentrators, see `emacs/etc/TERMS'.

At one time, most terminals did not need flow control, and none used C-s and C-q for flow control. Therefore, the choice of C-s and C-q as command characters for searching and quoting was natural and uncontroversial. With so many commands needing key assignments, of course we assigned meanings to nearly all ASCII control characters.

Later, some terminals were introduced which required these characters for flow control. They were not very good terminals for full-screen editing, so Emacs maintainers ignored them. In later years, flow control with C-s and C-q became widespread among terminals, but by this time it was usually an option. And the majority of Emacs users, who can turn flow control off, did not want to switch to less mnemonic key bindings for the sake of flow control.

So which usage is "right"---Emacs's or that of some terminal and concentrator manufacturers? This question has no simple answer.

One reason why we are reluctant to cater to the problems caused by C-s and C-q is that they are gratuitous. There are other techniques (albeit less common in practice) for flow control that preserve transparency of the character stream. Note also that their use for flow control is not an official standard. Interestingly, on the model 33 teletype with a paper tape punch (around 1970), C-s and C-q were sent by the computer to turn the punch on and off!

As window systems and PC terminal emulators replace character-only terminals, the flow control problem is gradually disappearing. For the mean time, Emacs provides a convenient way of enabling flow control if you want it: call the function enable-flow-control.

Command: enable-flow-control
This function enables use of C-s and C-q for output flow control, and provides the characters C-\ and C-^ as aliases for them using keyboard-translate-table (see section Translating Input Events).

You can use the function enable-flow-control-on in your `.emacs' file to enable flow control automatically on certain terminal types.

Function: enable-flow-control-on &rest termtypes
This function enables flow control, and the aliases C-\ and C-^, if the terminal type is one of termtypes. For example:
(enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
Here is how enable-flow-control does its job:

It sets CBREAK mode for terminal input, and tells the operating system to handle flow control, with (set-input-mode nil t).
It sets up keyboard-translate-table to translate C-\ and C-^ into C-s and C-q. Except at its very lowest level, Emacs never knows that the characters typed were anything but C-s and C-q, so you can in effect type them as C-\ and C-^ even when they are input for other commands. See section Translating Input Events.

If the terminal is the source of the flow control characters, then once you enable kernel flow control handling, you probably can make do with less padding than normal for that terminal. You can reduce the amount of padding by customizing the Termcap entry. You can also reduce it by setting baud-rate to a smaller value so that Emacs uses a smaller speed when calculating the padding needed. See section Terminal Output.

Batch Mode

The command line option `-batch' causes Emacs to run noninteractively. In this mode, Emacs does not read commands from the terminal, it does not alter the terminal modes, and it does not expect to be outputting to an erasable screen. The idea is that you specify Lisp programs to run; when they are finished, Emacs should exit. The way to specify the programs to run is with `-l file', which loads the library named file, and `-f function', which calls function with no arguments.

Any Lisp program output that would normally go to the echo area, either using message or using prin1, etc., with t as the stream, goes instead to Emacs's standard error descriptor when in batch mode. Thus, Emacs behaves much like a noninteractive application program. (The echo area output that Emacs itself normally generates, such as command echoing, is suppressed entirely.)

Variable: noninteractive
This variable is non-nil when Emacs is running in batch mode.
Emacs Display

This chapter describes a number of features related to the display that Emacs presents to the user.

Refreshing the Screen

The function redraw-frame redisplays the entire contents of a given frame (see section Frames).

Function: redraw-frame frame
This function clears and redisplays frame frame.

Even more powerful is redraw-display:

Command: redraw-display
This function clears and redisplays all visible frames.

Processing user input takes absolute priority over redisplay. If you call these functions when input is available, they do nothing immediately, but a full redisplay does happen eventually--after all the input has been processed.

Normally, suspending and resuming Emacs also refreshes the screen. Some terminal emulators record separate contents for display-oriented programs such as Emacs and for ordinary sequential display. If you are using such a terminal, you might want to inhibit the redisplay on resumption.

Variable: no-redraw-on-reenter
This variable controls whether Emacs redraws the entire screen after it has been suspended and resumed. Non-nil means there is no need to redraw, nil means redrawing is needed. The default is nil.

Truncation

When a line of text extends beyond the right edge of a window, the line can either be continued on the next screen line, or truncated to one screen line. The additional screen lines used to display a long text line are called continuation lines. Normally, a `$' in the rightmost column of the window indicates truncation; a `\' on the rightmost column indicates a line that "wraps" onto the next line, which is also called continuing the line. (The display table can specify alternative indicators; see section Display Tables.)

Note that continuation is different from filling; continuation happens on the screen only, not in the buffer contents, and it breaks a line precisely at the right margin, not at a word boundary. See section Filling.

User Option: truncate-lines
This buffer-local variable controls how Emacs displays lines that extend beyond the right edge of the window. The default is nil, which specifies continuation. If the value is non-nil, then these lines are truncated.

If the variable truncate-partial-width-windows is non-nil, then truncation is always used for side-by-side windows (within one frame) regardless of the value of truncate-lines.

User Option: default-truncate-lines
This variable is the default value for truncate-lines, for buffers that do not have buffer-local values for it.

User Option: truncate-partial-width-windows
This variable controls display of lines that extend beyond the right edge of the window, in side-by-side windows (see section Splitting Windows). If it is non-nil, these lines are truncated; otherwise, truncate-lines says what to do with them.

When horizontal scrolling (see section Horizontal Scrolling) is in use in a window, that forces truncation.

You can override the glyphs that indicate continuation or truncation using the display table; see section Display Tables.

If your buffer contains very long lines, and you use continuation to display them, just thinking about them can make Emacs redisplay slow. The column computation and indentation functions also become slow. Then you might find it advisable to set cache-long-line-scans to t.

Variable: cache-long-line-scans
If this variable is non-nil, various indentation and motion functions, and Emacs redisplay, cache the results of scanning the buffer, and consult the cache to avoid rescanning regions of the buffer unless they are modified.

Turning on the cache slows down processing of short lines somewhat.

This variable is automatically buffer-local in every buffer.

The Echo Area

The echo area is used for displaying messages made with the message primitive, and for echoing keystrokes. It is not the same as the minibuffer, despite the fact that the minibuffer appears (when active) in the same place on the screen as the echo area. The GNU Emacs Manual specifies the rules for resolving conflicts between the echo area and the minibuffer for use of that screen space (see section `The Minibuffer' in The GNU Emacs Manual). Error messages appear in the echo area; see section Errors.

You can write output in the echo area by using the Lisp printing functions with t as the stream (see section Output Functions), or as follows:

Function: message string &rest arguments
This function displays a one-line message in the echo area. The argument string is similar to a C language printf control string. See format in section Conversion of Characters and Strings, for the details on the conversion specifications. message returns the constructed string.

In batch mode, message prints the message text on the standard error stream, followed by a newline.

If string is nil, message clears the echo area. If the minibuffer is active, this brings the minibuffer contents back onto the screen immediately.
(message "Minibuffer depth is %d."
         (minibuffer-depth))
 -| Minibuffer depth is 0.
=> "Minibuffer depth is 0."

---------- Echo Area ----------
Minibuffer depth is 0.
---------- Echo Area ----------
Function: message-or-box string &rest arguments
This function displays a message like message, but may display it in a dialog box instead of the echo area. If this function is called in a command that was invoked using the mouse--more precisely, if last-nonmenu-event (see section Information from the Command Loop) is either nil or a list--then it uses a dialog box or pop-up menu to display the message. Otherwise, it uses the echo area. (This is the same criterion that y-or-n-p uses to make a similar decision; see section Yes-or-No Queries.)

You can force use of the mouse or of the echo area by binding last-nonmenu-event to a suitable value around the call.

Function: message-box string &rest arguments
This function displays a message like message, but uses a dialog box (or a pop-up menu) whenever that is possible. If it is impossible to use a dialog box or pop-up menu, because the terminal does not support them, then message-box uses the echo area, like message.

Function: current-message
This function returns the message currently being displayed in the echo area, or nil if there is none.

Variable: cursor-in-echo-area
This variable controls where the cursor appears when a message is displayed in the echo area. If it is non-nil, then the cursor appears at the end of the message. Otherwise, the cursor appears at point--not in the echo area at all.

The value is normally nil; Lisp programs bind it to t for brief periods of time.

Variable: echo-area-clear-hook
This normal hook is run whenever the echo area is cleared--either by (message nil) or for any other reason.

Almost all the messages displayed in the echo area are also recorded in the `*Messages*' buffer.

User Option: message-log-max
This variable specifies how many lines to keep in the `*Messages*' buffer. The value t means there is no limit on how many lines to keep. The value nil disables message logging entirely. Here's how to display a message and prevent it from being logged:
(let (message-log-max)
  (message ...))
Variable: echo-keystrokes
This variable determines how much time should elapse before command characters echo. Its value must be an integer, which specifies the number of seconds to wait before echoing. If the user types a prefix key (such as C-x) and then delays this many seconds before continuing, the prefix key is echoed in the echo area. (Once echoing begins in a key sequence, all subsequent characters in the same key sequence are echoed immediately.)

If the value is zero, then command input is not echoed.

Invisible Text

You can make characters invisible, so that they do not appear on the screen, with the invisible property. This can be either a text property (see section Text Properties) or a property of an overlay (see section Overlays).

In the simplest case, any non-nil invisible property makes a character invisible. This is the default case--if you don't alter the default value of buffer-invisibility-spec, this is how the invisible property works.

More generally, you can use the variable buffer-invisibility-spec to control which values of the invisible property make text invisible. This permits you to classify the text into different subsets in advance, by giving them different invisible values, and subsequently make various subsets visible or invisible by changing the value of buffer-invisibility-spec.

Controlling visibility with buffer-invisibility-spec is especially useful in a program to display the list of entries in a data base. It permits the implementation of convenient filtering commands to view just a part of the entries in the data base. Setting this variable is very fast, much faster than scanning all the text in the buffer looking for properties to change.

Variable: buffer-invisibility-spec
This variable specifies which kinds of invisible properties actually make a character invisible.

t
A character is invisible if its invisible property is non-nil. This is the default.
a list
Each element of the list specifies a criterion for invisibility; if a character's invisible property fits any one of these criteria, the character is invisible. The list can have two kinds of elements:
atom
A character is invisible if its invisible property value is atom or if it is a list with atom as a member.
(atom . t)
A character is invisible if its invisible property value is atom or if it is a list with atom as a member. Moreover, if this character is at the end of a line and is followed by a visible newline, it displays an ellipsis.
Two functions are specifically provided for adding elements to buffer-invisibility-spec and removing elements from it.

Function: add-to-invisibility-spec element
Add the element element to buffer-invisibility-spec (if it is not already present in that list).

Function: remove-from-invisibility-spec element
Remove the element element from buffer-invisibility-spec.

One convention about the use of buffer-invisibility-spec is that a major mode should use the mode's own name as an element of buffer-invisibility-spec and as the value of the invisible property:
;; If you want to display an ellipsis:
(add-to-invisibility-spec '(my-symbol . t))
;; If you don't want ellipsis:
(add-to-invisibility-spec 'my-symbol)

(overlay-put (make-overlay beginning end)
             'invisible 'my-symbol)

;; When done with the overlays:
(remove-from-invisibility-spec '(my-symbol . t))
;; Or respectively:
(remove-from-invisibility-spec 'my-symbol)
Ordinarily, commands that operate on text or move point do not care whether the text is invisible. The user-level line motion commands explicitly ignore invisible newlines if line-move-ignore-invisible is non-nil, but only because they are explicitly programmed to do so.

Incremental search can make invisible overlays visible temporarily and/or permanently when a match includes invisible text. To enable this, the overlay should have a non-nil isearch-open-invisible property. The property value should be a function to be called with the overlay as an argument. This function should make the overlay visible permanently; it is used when the match overlaps the overlay on exit from the search.

During the search, such overlays are made temporarily visible by temporarily modifying their invisible and intangible properties. If you want this to be done differently for a certain overlay, give it an isearch-open-invisible-temporary property which is a function. The function is called with two arguments: the first is the overlay, and the second is t to make the overlay visible, or nil to make it invisible again.

Selective Display

Selective display refers to a pair of related features for hiding certain lines on the screen.

The first variant, explicit selective display, is designed for use in a Lisp program: it controls which lines are hidden by altering the text. The invisible text feature (see section Invisible Text) has partially replaced this feature.

In the second variant, the choice of lines to hide is made automatically based on indentation. This variant is designed to be a user-level feature.

The way you control explicit selective display is by replacing a newline (control-j) with a carriage return (control-m). The text that was formerly a line following that newline is now invisible. Strictly speaking, it is temporarily no longer a line at all, since only newlines can separate lines; it is now part of the previous line.

Selective display does not directly affect editing commands. For example, C-f (forward-char) moves point unhesitatingly into invisible text. However, the replacement of newline characters with carriage return characters affects some editing commands. For example, next-line skips invisible lines, since it searches only for newlines. Modes that use selective display can also define commands that take account of the newlines, or that make parts of the text visible or invisible.

When you write a selectively displayed buffer into a file, all the control-m's are output as newlines. This means that when you next read in the file, it looks OK, with nothing invisible. The selective display effect is seen only within Emacs.

Variable: selective-display
This buffer-local variable enables selective display. This means that lines, or portions of lines, may be made invisible.

If the value of selective-display is t, then any portion of a line that follows a control-m is not displayed. This is explicit selective display.
If the value of selective-display is a positive integer, then lines that start with more than that many columns of indentation are not displayed.

When some portion of a buffer is invisible, the vertical movement commands operate as if that portion did not exist, allowing a single next-line command to skip any number of invisible lines. However, character movement commands (such as forward-char) do not skip the invisible portion, and it is possible (if tricky) to insert or delete text in an invisible portion.

In the examples below, we show the display appearance of the buffer foo, which changes with the value of selective-display. The contents of the buffer do not change.
(setq selective-display nil)
     => nil

---------- Buffer: foo ----------
1 on this column
 2on this column
  3n this column
  3n this column
 2on this column
1 on this column
---------- Buffer: foo ----------

(setq selective-display 2)
     => 2

---------- Buffer: foo ----------
1 on this column
 2on this column
 2on this column
1 on this column
---------- Buffer: foo ----------
Variable: selective-display-ellipses
If this buffer-local variable is non-nil, then Emacs displays `...' at the end of a line that is followed by invisible text. This example is a continuation of the previous one.
(setq selective-display-ellipses t)
     => t

---------- Buffer: foo ----------
1 on this column
 2on this column ...
 2on this column
1 on this column
---------- Buffer: foo ----------
You can use a display table to substitute other text for the ellipsis (`...'). See section Display Tables.

The Overlay Arrow

The overlay arrow is useful for directing the user's attention to a particular line in a buffer. For example, in the modes used for interface to debuggers, the overlay arrow indicates the line of code about to be executed.

Variable: overlay-arrow-string
This variable holds the string to display to call attention to a particular line, or nil if the arrow feature is not in use.

Variable: overlay-arrow-position
This variable holds a marker that indicates where to display the overlay arrow. It should point at the beginning of a line. The arrow text appears at the beginning of that line, overlaying any text that would otherwise appear. Since the arrow is usually short, and the line usually begins with indentation, normally nothing significant is overwritten.

The overlay string is displayed only in the buffer that this marker points into. Thus, only one buffer can have an overlay arrow at any given time.

You can do a similar job by creating an overlay with a before-string property. See section Overlay Properties.

Temporary Displays

Temporary displays are used by Lisp programs to put output into a buffer and then present it to the user for perusal rather than for editing. Many help commands use this feature.

Special Form: with-output-to-temp-buffer buffer-name forms...
This function executes forms while arranging to insert any output they print into the buffer named buffer-name. The buffer is then shown in some window for viewing, displayed but not selected.

The string buffer-name specifies the temporary buffer, which need not already exist. The argument must be a string, not a buffer. The buffer is erased initially (with no questions asked), and it is marked as unmodified after with-output-to-temp-buffer exits.

with-output-to-temp-buffer binds standard-output to the temporary buffer, then it evaluates the forms in forms. Output using the Lisp output functions within forms goes by default to that buffer (but screen display and messages in the echo area, although they are "output" in the general sense of the word, are not affected). See section Output Functions.

The value of the last form in forms is returned.
---------- Buffer: foo ----------
 This is the contents of foo.
---------- Buffer: foo ----------

(with-output-to-temp-buffer "foo"
    (print 20)
    (print standard-output))
=> #<buffer foo>

---------- Buffer: foo ----------
20

#<buffer foo>

---------- Buffer: foo ----------
Variable: temp-buffer-show-function
If this variable is non-nil, with-output-to-temp-buffer calls it as a function to do the job of displaying a help buffer. The function gets one argument, which is the buffer it should display.

It is a good idea for this function to run temp-buffer-show-hook just as with-output-to-temp-buffer normally would, inside of save-window-excursion and with the chosen window and buffer selected.

Variable: temp-buffer-show-hook
This normal hook is run by with-output-to-temp-buffer after displaying the help buffer. When the hook runs, the help buffer is current, and the window it was displayed in is selected.

Function: momentary-string-display string position &optional char message
This function momentarily displays string in the current buffer at position. It has no effect on the undo list or on the buffer's modification status.

The momentary display remains until the next input event. If the next input event is char, momentary-string-display ignores it and returns. Otherwise, that event remains buffered for subsequent use as input. Thus, typing char will simply remove the string from the display, while typing (say) C-f will remove the string from the display and later (presumably) move point forward. The argument char is a space by default.

The return value of momentary-string-display is not meaningful.

If the string string does not contain control characters, you can do the same job in a more general way by creating (and then subsequently deleting) an overlay with a before-string property. See section Overlay Properties.

If message is non-nil, it is displayed in the echo area while string is displayed in the buffer. If it is nil, a default message says to type char to continue.

In this example, point is initially located at the beginning of the second line:
---------- Buffer: foo ----------
This is the contents of foo.
-!-Second line.
---------- Buffer: foo ----------

(momentary-string-display
  "**** Important Message! ****"
  (point) ?\r
  "Type RET when done reading")
=> t

---------- Buffer: foo ----------
This is the contents of foo.
**** Important Message! ****Second line.
---------- Buffer: foo ----------

---------- Echo Area ----------
Type RET when done reading
---------- Echo Area ----------
Overlays

You can use overlays to alter the appearance of a buffer's text on the screen, for the sake of presentation features. An overlay is an object that belongs to a particular buffer, and has a specified beginning and end. It also has properties that you can examine and set; these affect the display of the text within the overlay.

Overlay Properties

Overlay properties are like text properties in that the properties that alter how a character is displayed can come from either source. But in most respects they are different. Text properties are considered a part of the text; overlays are specifically considered not to be part of the text. Thus, copying text between various buffers and strings preserves text properties, but does not try to preserve overlays. Changing a buffer's text properties marks the buffer as modified, while moving an overlay or changing its properties does not. Unlike text property changes, overlay changes are not recorded in the buffer's undo list. See section Text Properties, for comparison.

priority
This property's value (which should be a nonnegative number) determines the priority of the overlay. The priority matters when two or more overlays cover the same character and both specify a face for display; the one whose priority value is larger takes priority over the other, and its face attributes override the face attributes of the lower priority overlay. Currently, all overlays take priority over text properties. Please avoid using negative priority values, as we have not yet decided just what they should mean.
window
If the window property is non-nil, then the overlay applies only on that window.
category
If an overlay has a category property, we call it the category of the overlay. It should be a symbol. The properties of the symbol serve as defaults for the properties of the overlay.
face
This property controls the way text is displayed--for example, which font and which colors. Its value is a face name or a list of face names. See section Faces, for more information. If the property value is a list, elements may also have the form (foreground-color . color-name) or (background-color . color-name). These elements specify just the foreground color or just the background color; therefore, there is no need to create a face for each color that you want to use.
mouse-face
This property is used instead of face when the mouse is within the range of the overlay.
modification-hooks
This property's value is a list of functions to be called if any character within the overlay is changed or if text is inserted strictly within the overlay. The hook functions are called both before and after each change. If the functions save the information they receive, and compare notes between calls, they can determine exactly what change has been made in the buffer text. When called before a change, each function receives four arguments: the overlay, nil, and the beginning and end of the text range to be modified. When called after a change, each function receives five arguments: the overlay, t, the beginning and end of the text range just modified, and the length of the pre-change text replaced by that range. (For an insertion, the pre-change length is zero; for a deletion, that length is the number of characters deleted, and the post-change beginning and end are equal.)
insert-in-front-hooks
This property's value is a list of functions to be called before and after inserting text right at the beginning of the overlay. The calling conventions are the same as for the modification-hooks functions.
insert-behind-hooks
This property's value is a list of functions to be called before and after inserting text right at the end of the overlay. The calling conventions are the same as for the modification-hooks functions.
invisible
The invisible property can make the text in the overlay invisible, which means that it does not appear on the screen. See section Invisible Text, for details.
intangible
The intangible property on an overlay works just like the intangible text property. See section Properties with Special Meanings, for details.
isearch-open-invisible
This property tells incremental search how to make an invisible overlay visible, permanently, if the final match overlaps it. See section Invisible Text.
isearch-open-invisible-temporary
This property tells incremental search how to make an invisible overlay visible, temporarily, during the search. See section Invisible Text.
before-string
This property's value is a string to add to the display at the beginning of the overlay. The string does not appear in the buffer in any sense--only on the screen. The string should contain only characters that display as a single column--control characters, including tabs or newlines, will give strange results.
after-string
This property's value is a string to add to the display at the end of the overlay. The string does not appear in the buffer in any sense--only on the screen. The string should contain only characters that display as a single column--control characters, including tabs or newlines, will give strange results.
evaporate
If this property is non-nil, the overlay is deleted automatically if it ever becomes empty (i.e., if it spans no characters).
local-map
If this property is non-nil, it specifies a keymap for a portion of the text. The property's value replaces the buffer's local map, when the character after point is within the overlay. See section Active Keymaps.
These are the functions for reading and writing the properties of an overlay.

Function: overlay-get overlay prop
This function returns the value of property prop recorded in overlay, if any. If overlay does not record any value for that property, but it does have a category property which is a symbol, that symbol's prop property is used. Otherwise, the value is nil.

Function: overlay-put overlay prop value
This function sets the value of property prop recorded in overlay to value. It returns value.

See also the function get-char-property which checks both overlay properties and text properties for a given character. See section Examining Text Properties.

Managing Overlays

This section describes the functions to create, delete and move overlays, and to examine their contents.

Function: make-overlay start end &optional buffer front-advance rear-advance
This function creates and returns an overlay that belongs to buffer and ranges from start to end. Both start and end must specify buffer positions; they may be integers or markers. If buffer is omitted, the overlay is created in the current buffer.

The arguments front-advance and rear-advance specify the insertion type for the start of the overlay and for the end of the overlay. See section Marker Insertion Types.

Function: overlay-start overlay
This function returns the position at which overlay starts, as an integer.

Function: overlay-end overlay
This function returns the position at which overlay ends, as an integer.

Function: overlay-buffer overlay
This function returns the buffer that overlay belongs to.

Function: delete-overlay overlay
This function deletes overlay. The overlay continues to exist as a Lisp object, but ceases to be attached to the buffer it belonged to, and ceases to have any effect on display.

A deleted overlay is not permanently useless. You can give it a new buffer position by calling move-overlay.

Function: move-overlay overlay start end &optional buffer
This function moves overlay to buffer, and places its bounds at start and end. Both arguments start and end must specify buffer positions; they may be integers or markers. If buffer is omitted, the overlay stays in the same buffer.

The return value is overlay.

This is the only valid way to change the endpoints of an overlay. Do not try modifying the markers in the overlay by hand, as that fails to update other vital data structures and can cause some overlays to be "lost".

Function: overlays-at pos
This function returns a list of all the overlays that contain position pos in the current buffer. The list is in no particular order. An overlay contains position pos if it begins at or before pos, and ends after pos.

Function: overlays-in beg end
This function returns a list of the overlays that overlap the region beg through end. "Overlap" means that at least one character is contained within the overlay and also contained within the specified region; however, empty overlays are included in the result if they are located at beg or between beg and end.

Function: next-overlay-change pos
This function returns the buffer position of the next beginning or end of an overlay, after pos.

Function: previous-overlay-change pos
This function returns the buffer position of the previous beginning or end of an overlay, before pos.

Width

Since not all characters have the same width, these functions let you check the width of a character. See section Indentation Primitives, and section Motion by Screen Lines, for related functions.

Function: char-width char
This function returns the width in columns of the character char, if it were displayed in the current buffer and the selected window.

Function: string-width string
This function returns the width in columns of the string string, if it were displayed in the current buffer and the selected window.

Function: truncate-string-to-width string width &optional start-column padding
This function returns the part of string that fits within width columns, as a new string.

If string does not reach width, then the result ends where string ends. If one multi-column character in string extends across the column width, that character is not included in the result. Thus, the result can fall short of width but cannot go beyond it.

The optional argument start-column specifies the starting column. If this is non-nil, then the first start-column columns of the string are omitted from the value. If one multi-column character in string extends across the column start-column, that character is not included.

The optional argument padding, if non-nil, is a padding character added at the beginning and end of the result string, to extend it to exactly width columns. The padding character is used at the end of the result if it falls short of width. It is also used at the beginning of the result if one multi-column character in string extends across the column start-column.
(truncate-string-to-width "\tab\t" 12 4)
     => "ab"
(truncate-string-to-width "\tab\t" 12 4 ?\ )
     => "    ab  "
Faces

A face is a named collection of graphical attributes: font, foreground color, background color, and optional underlining. Faces control the display of text on the screen.

Each face has its own face number, which distinguishes faces at low levels within Emacs. However, for most purposes, you can refer to faces in Lisp programs by their names.

Function: facep object
This function returns t if object is a face name symbol (or if it is a vector of the kind used internally to record face data). It returns nil otherwise.

Each face name is meaningful for all frames, and by default it has the same meaning in all frames. But you can arrange to give a particular face name a special meaning in one frame if you wish.

Standard Faces

This table lists all the standard faces and their uses.

default
This face is used for ordinary text.
modeline
This face is used for mode lines and menu bars.
region
This face is used for highlighting the region in Transient Mark mode.
secondary-selection
This face is used to show any secondary selection you have made.
highlight
This face is meant to be used for highlighting for various purposes.
underline
This face underlines text.
bold
This face uses a bold font, if possible. It uses the bold variant of the frame's font, if it has one. It's up to you to choose a default font that has a bold variant, if you want to use one.
italic
This face uses the italic variant of the frame's font, if it has one.
bold-italic
This face uses the bold italic variant of the frame's font, if it has one.
Defining Faces

The way to define a new face is with defface. This creates a kind of customization item (see section Writing Customization Definitions) which the user can customize using the Customization buffer (see section `Easy Customization' in The GNU Emacs Manual).

Macro: defface face spec doc [keyword value]...
Declare face as a customizable face that defaults according to spec. Do not quote the symbol face. The argument doc specifies the face documentation.

When defface executes, it defines the face according to spec, then uses any customizations that were read from the `.emacs' file to override that specification.

The purpose of spec is to specify how the face should appear on different kinds of terminals. It should be an alist whose elements have the form (display atts). The element's CAR, display, specifies a class of terminals. The CDR, atts, is a list of face attributes and their values; it specifies what the face should look like on that kind of terminal. The possible attributes are defined in the value of custom-face-attributes.

The display part of an element of spec determines which frames the element applies to. If more than one element of spec matches a given frame, the first matching element is the only one used for that frame. There are two possibilities for display:

t
This element of spec matches all frames. Therefore, any subsequent elements of spec are never used. Normally t is used in the last (or only) element of spec.
a list
If display is a list, each element should have the form (characteristic value...). Here characteristic specifies a way of classifying frames, and the values are possible classifications which display should apply to. Here are the possible values of characteristic:
type
The kind of window system the frame uses--either x, pc (for the MS-DOS console), w32 (for MS Windows 9X/NT), or tty.
class
What kinds of colors the frame supports--either color, grayscale, or mono.
background
The kind of background--either light or dark. If an element of display specifies more than one value for a given characteristic, any of those values is acceptable. If display has more than one element, each element should specify a different characteristic; then each characteristic of the frame must match one of the values specified for it in display.
Here's how the standard face region could be defined with defface:
(defface region
         ((((class color) (background dark))
           (:background "blue"))
          (t (:background "gray")))
  "Used for displaying the region.")
Internally, defface uses the symbol property face-defface-spec to record the face attributes specified in defface, saved-face for the attributes saved by the user with the customization buffer, and face-documentation for the documentation string.

User Option: frame-background-mode
This option, if non-nil, specifies the background type to use for interpreting face definitions. If it is dark, then Emacs treats all frames as if they had a dark background, regardless of their actual background colors. If it is light, then Emacs treats all frames as if they had a light background.

Merging Faces for Display

Here are all the ways to specify which face to use for display of text:

With defaults. Each frame has a default face, which is used for all text that doesn't somehow specify another face. (We may change this in a forthcoming Emacs version to serve as a default for all text.)
With text properties. A character may have a face property; if so, it is displayed with that face. See section Properties with Special Meanings. If the character has a mouse-face property, that is used instead of the face property when the mouse is "near enough" to the character.
With overlays. An overlay may have face and mouse-face properties too; they apply to all the text covered by the overlay.
With a region that is active. In Transient Mark mode, the region is highlighted with a particular face (see region-face, below).
With special glyphs. Each glyph can specify a particular face number. See section Glyphs.

If these various sources together specify more than one face for a particular character, Emacs merges the attributes of the various faces specified. The attributes of the faces of special glyphs come first; then comes the face for region highlighting, if appropriate; then come attributes of faces from overlays, followed by those from text properties, and last the default face.

When multiple overlays cover one character, an overlay with higher priority overrides those with lower priority. See section Overlays.

If an attribute such as the font or a color is not specified in any of the above ways, the frame's own font or color is used.

Functions for Working with Faces

The attributes a face can specify include the font, the foreground color, the background color, and underlining. The face can also leave these unspecified by giving the value nil for them.

Here are the primitives for creating and changing faces.

Function: make-face name
This function defines a new face named name, initially with all attributes nil. It does nothing if there is already a face named name.

Function: face-list
This function returns a list of all defined face names.

Function: copy-face old-face new-name &optional frame new-frame
This function defines the face new-name as a copy of the existing face named old-face. It creates the face new-name if that doesn't already exist.

If the optional argument frame is given, this function applies only to that frame. Otherwise it applies to each frame individually, copying attributes from old-face in each frame to new-face in the same frame.

If the optional argument new-frame is given, then copy-face copies the attributes of old-face in frame to new-name in new-frame.

You can modify the attributes of an existing face with the following functions. If you specify frame, they affect just that frame; otherwise, they affect all frames as well as the defaults that apply to new frames.

Function: set-face-foreground face color &optional frame

Function: set-face-background face color &optional frame
These functions set the foreground (or background, respectively) color of face face to color. The argument color should be a string, the name of a color.

Certain shades of gray are implemented by stipple patterns on black-and-white screens.

Function: set-face-stipple face pattern &optional frame
This function sets the background stipple pattern of face face to pattern. The argument pattern should be the name of a stipple pattern defined by the X server, or nil meaning don't use stipple.

Normally there is no need to pay attention to stipple patterns, because they are used automatically to handle certain shades of gray.

Function: set-face-font face font &optional frame
This function sets the font of face face. The argument font should be a string, either a valid font name for your system or the name of an Emacs fontset (see section Fontsets). Note that if you set the font explicitly, the bold and italic attributes cease to have any effect, because the precise font that you specified is always used.

Function: set-face-bold-p face bold-p &optional frame
This function sets the bold attribute of face face. Non-nil means bold; nil means non-bold.

Function: set-face-italic-p face italic-p &optional frame
This function sets the italic attribute of face face. Non-nil means italic; nil means non-italic.

Function: set-face-underline-p face underline-p &optional frame
This function sets the underline attribute of face face. Non-nil means do underline; nil means don't.

Function: invert-face face &optional frame
Swap the foreground and background colors of face face. If the face doesn't specify both foreground and background, then its foreground and background are set to the default background and foreground, respectively.

These functions examine the attributes of a face. If you don't specify frame, they refer to the default data for new frames.

Function: face-foreground face &optional frame

Function: face-background face &optional frame
These functions return the foreground color (or background color, respectively) of face face, as a string.

Function: face-stipple face &optional frame
This function returns the name of the background stipple pattern of face face, or nil if it doesn't have one.

Function: face-font face &optional frame
This function returns the name of the font of face face.

Function: face-bold-p face &optional frame
This function returns the bold attribute of face face.

Function: face-italic-p face &optional frame
This function returns the italic attribute of face face.

Function: face-underline-p face &optional frame
This function returns the underline attribute of face face.

Function: face-id face
This function returns the face number of face face.

Function: face-documentation face
This function returns the documentation string of face face, or nil if none was specified for it.

Function: face-equal face1 face2 &optional frame
This returns t if the faces face1 and face2 have the same attributes for display.

Function: face-differs-from-default-p face &optional frame
This returns t if the face face displays differently from the default face. A face is considered to be "the same" as the normal face if each attribute is either the same as that of the default face or nil (meaning to inherit from the default).

Variable: region-face
This variable's value specifies the face number to use to display characters in the region when it is active (in Transient Mark mode only). The face thus specified takes precedence over all faces that come from text properties and overlays, for characters in the region. See section The Mark, for more information about Transient Mark mode.

Normally, the value is the face number of the face named region.

Function: frame-update-face-colors frame
This function updates the way faces display on frame, for a change in frame's foreground or background color.

Blinking Parentheses

This section describes the mechanism by which Emacs shows a matching open parenthesis when the user inserts a close parenthesis.

Variable: blink-paren-function
The value of this variable should be a function (of no arguments) to be called whenever a character with close parenthesis syntax is inserted. The value of blink-paren-function may be nil, in which case nothing is done.

User Option: blink-matching-paren
If this variable is nil, then blink-matching-open does nothing.

User Option: blink-matching-paren-distance
This variable specifies the maximum distance to scan for a matching parenthesis before giving up.

User Option: blink-matching-delay
This variable specifies the number of seconds for the cursor to remain at the matching parenthesis. A fraction of a second often gives good results, but the default is 1, which works on all systems.

Command: blink-matching-open
This function is the default value of blink-paren-function. It assumes that point follows a character with close parenthesis syntax and moves the cursor momentarily to the matching opening character. If that character is not already on the screen, it displays the character's context in the echo area. To avoid long delays, this function does not search farther than blink-matching-paren-distance characters.

Here is an example of calling this function explicitly.
(defun interactive-blink-matching-open ()
  "Indicate momentarily the start of sexp before point."
  (interactive)
  (let ((blink-matching-paren-distance
         (buffer-size))
        (blink-matching-paren t))
    (blink-matching-open)))
Inverse Video

User Option: inverse-video
This variable controls whether Emacs uses inverse video for all text on the screen. Non-nil means yes, nil means no. The default is nil.

User Option: mode-line-inverse-video
This variable controls the use of inverse video for mode lines. If it is non-nil, then mode lines are displayed in inverse video. Otherwise, mode lines are displayed normally, just like text. The default is t.

For window frames, this displays mode lines using the face named modeline, which is normally the inverse of the default face unless you change it.

Usual Display Conventions

The usual display conventions define how to display each character code. You can override these conventions by setting up a display table (see section Display Tables). Here are the usual display conventions:

Character codes 32 through 126 map to glyph codes 32 through 126. Normally this means they display as themselves.
Character code 9 is a horizontal tab. It displays as whitespace up to a position determined by tab-width.
Character code 10 is a newline.
All other codes in the range 0 through 31, and code 127, display in one of two ways according to the value of ctl-arrow. If it is non-nil, these codes map to sequences of two glyphs, where the first glyph is the ASCII code for `^'. (A display table can specify a glyph to use instead of `^'.) Otherwise, these codes map just like the codes in the range 128 to 255.
Character codes 128 through 255 map to sequences of four glyphs, where the first glyph is the ASCII code for `\', and the others are digit characters representing the character code in octal. (A display table can specify a glyph to use instead of `\'.)
Multibyte character codes above 256 are displayed as themselves, or as a question mark or empty box if the terminal cannot display that character.

The usual display conventions apply even when there is a display table, for any character whose entry in the active display table is nil. Thus, when you set up a display table, you need only specify the characters for which you want special behavior.

These variables affect the way certain characters are displayed on the screen. Since they change the number of columns the characters occupy, they also affect the indentation functions. These variables also affect how the mode line is displayed; if you want to force redisplay of the mode line using the new values, call the function force-mode-line-update (see section Mode Line Format).

User Option: ctl-arrow
This buffer-local variable controls how control characters are displayed. If it is non-nil, they are displayed as a caret followed by the character: `^A'. If it is nil, they are displayed as a backslash followed by three octal digits: `\001'.

Variable: default-ctl-arrow
The value of this variable is the default value for ctl-arrow in buffers that do not override it. See section The Default Value of a Buffer-Local Variable.

User Option: tab-width
The value of this variable is the spacing between tab stops used for displaying tab characters in Emacs buffers. The default is 8. Note that this feature is completely independent of the user-settable tab stops used by the command tab-to-tab-stop. See section Adjustable "Tab Stops".

Display Tables

You can use the display table feature to control how all possible character codes display on the screen. This is useful for displaying European languages that have letters not in the ASCII character set.

The display table maps each character code into a sequence of glyphs, each glyph being an image that takes up one character position on the screen. You can also define how to display each glyph on your terminal, using the glyph table.

Display tables affect how the mode line is displayed; if you want to force redisplay of the mode line using a new display table, call force-mode-line-update (see section Mode Line Format).

Display Table Format

A display table is actually a char-table (see section Char-Tables) with display-table as its subtype.

Function: make-display-table
This creates and returns a display table. The table initially has nil in all elements.

The ordinary elements of the display table are indexed by character codes; the element at index c says how to display the character code c. The value should be nil or a vector of glyph values (see section Glyphs). If an element is nil, it says to display that character according to the usual display conventions (see section Usual Display Conventions).

If you use the display table to change the display of newline characters, the whole buffer will be displayed as one long "line."

The display table also has six "extra slots" which serve special purposes. Here is a table of their meanings; nil in any slot means to use the default for that slot, as stated below.

0
The glyph for the end of a truncated screen line (the default for this is `$'). See section Glyphs.
1
The glyph for the end of a continued line (the default is `\').
2
The glyph for indicating a character displayed as an octal character code (the default is `\').
3
The glyph for indicating a control character (the default is `^').
4
A vector of glyphs for indicating the presence of invisible lines (the default is `...'). See section Selective Display.
5
The glyph used to draw the border between side-by-side windows (the default is `|'). See section Splitting Windows.
For example, here is how to construct a display table that mimics the effect of setting ctl-arrow to a non-nil value:
(setq disptab (make-display-table))
(let ((i 0))
  (while (< i 32)
    (or (= i ?\t) (= i ?\n)
        (aset disptab i (vector ?^ (+ i 64))))
    (setq i (1+ i)))
  (aset disptab 127 (vector ?^ ??)))
Function: display-table-slot display-table slot
This function returns the value of the extra slot slot of display-table. The argument slot may be a number from 0 to 5 inclusive, or a slot name (symbol). Valid symbols are truncation, wrap, escape, control, selective-display, and vertical-border.

Function: set-display-table-slot display-table slot value
This function stores value in the extra slot slot of display-table. The argument slot may be a number from 0 to 5 inclusive, or a slot name (symbol). Valid symbols are truncation, wrap, escape, control, selective-display, and vertical-border.

Active Display Table

Each window can specify a display table, and so can each buffer. When a buffer b is displayed in window w, display uses the display table for window w if it has one; otherwise, the display table for buffer b if it has one; otherwise, the standard display table if any. The display table chosen is called the active display table.

Function: window-display-table window
This function returns window's display table, or nil if window does not have an assigned display table.

Function: set-window-display-table window table
This function sets the display table of window to table. The argument table should be either a display table or nil.

Variable: buffer-display-table
This variable is automatically buffer-local in all buffers; its value in a particular buffer specifies the display table for that buffer. If it is nil, that means the buffer does not have an assigned display table.

Variable: standard-display-table
This variable's value is the default display table, used whenever a window has no display table and neither does the buffer displayed in that window. This variable is nil by default.

If there is no display table to use for a particular window--that is, if the window specifies none, its buffer specifies none, and standard-display-table is nil---then Emacs uses the usual display conventions for all character codes in that window. See section Usual Display Conventions.

Glyphs

A glyph is a generalization of a character; it stands for an image that takes up a single character position on the screen. Glyphs are represented in Lisp as integers, just as characters are.

The meaning of each integer, as a glyph, is defined by the glyph table, which is the value of the variable glyph-table.

Variable: glyph-table
The value of this variable is the current glyph table. It should be a vector; the gth element defines glyph code g. If the value is nil instead of a vector, then all glyphs are simple (see below).

Here are the possible types of elements in the glyph table:

string
Send the characters in string to the terminal to output this glyph. This alternative is available on character terminals, but not under a window system.
integer
Define this glyph code as an alias for glyph code integer. You can use an alias to specify a face code for the glyph; see below.
nil
This glyph is simple. On an ordinary terminal, the glyph code mod 524288 is the character to output. In a window system, the glyph code mod 524288 is the character to output, and the glyph code divided by 524288 specifies the face number (see section Functions for Working with Faces) to use while outputting it. (524288 is See section Faces.
If a glyph code is greater than or equal to the length of the glyph table, that code is automatically simple.

Beeping

This section describes how to make Emacs ring the bell (or blink the screen) to attract the user's attention. Be conservative about how often you do this; frequent bells can become irritating. Also be careful not to use just beeping when signaling an error is more appropriate. (See section Errors.)

Function: ding &optional do-not-terminate
This function beeps, or flashes the screen (see visible-bell below). It also terminates any keyboard macro currently executing unless do-not-terminate is non-nil.

Function: beep &optional do-not-terminate
This is a synonym for ding.

User Option: visible-bell
This variable determines whether Emacs should flash the screen to represent a bell. Non-nil means yes, nil means no. This is effective on a window system, and on a character-only terminal provided the terminal's Termcap entry defines the visible bell capability (`vb').

Variable: ring-bell-function
If this is non-nil, it specifies how Emacs should "ring the bell." Its value should be a function of no arguments.

Window Systems

Emacs works with several window systems, most notably the X Window System. Both Emacs and X use the term "window", but use it differently. An Emacs frame is a single window as far as X is concerned; the individual Emacs windows are not known to X at all.

Variable: window-system
This variable tells Lisp programs what window system Emacs is running under. The possible values are

x
Emacs is displaying using X.
pc
Emacs is displaying using MSDOS.
w32
Emacs is displaying using Windows NT or Windows 95.
nil
Emacs is using a character-based terminal.

Variable: window-setup-hook
This variable is a normal hook which Emacs runs after handling the initialization files. Emacs runs this hook after it has completed loading your `.emacs' file, the default initialization file (if any), and the terminal-specific Lisp code, and running the hook term-setup-hook.

This hook is used for internal purposes: setting up communication with the window system, and creating the initial window. Users should not interfere with it.
Customizing the Calendar and Diary

There are many customizations that you can use to make the calendar and diary suit your personal tastes.

Customizing the Calendar

If you set the variable view-diary-entries-initially to t, calling up the calendar automatically displays the diary entries for the current date as well. The diary dates appear only if the current date is visible. If you add both of the following lines to your `.emacs' file:
(setq view-diary-entries-initially t)
(calendar)
this displays both the calendar and diary windows whenever you start Emacs.

Similarly, if you set the variable view-calendar-holidays-initially to t, entering the calendar automatically displays a list of holidays for the current three-month period. The holiday list appears in a separate window.

You can set the variable mark-diary-entries-in-calendar to t in order to mark any dates with diary entries. This takes effect whenever the calendar window contents are recomputed. There are two ways of marking these dates: by changing the face (see section Faces), if the display supports that, or by placing a plus sign (`+') beside the date otherwise.

Similarly, setting the variable mark-holidays-in-calendar to t marks holiday dates, either with a change of face or with an asterisk (`*').

The variable calendar-holiday-marker specifies how to mark a date as being a holiday. Its value may be a character to insert next to the date, or a face name to use for displaying the date. Likewise, the variable diary-entry-marker specifies how to mark a date that has diary entries. The calendar creates faces named holiday-face and diary-face for these purposes; those symbols are the default values of these variables, when Emacs supports multiple faces on your terminal.

The variable calendar-load-hook is a normal hook run when the calendar package is first loaded (before actually starting to display the calendar).

Starting the calendar runs the normal hook initial-calendar-window-hook. Recomputation of the calendar display does not run this hook. But if you leave the calendar with the q command and reenter it, the hook runs again.

The variable today-visible-calendar-hook is a normal hook run after the calendar buffer has been prepared with the calendar when the current date is visible in the window. One use of this hook is to replace today's date with asterisks; to do that, use the hook function calendar-star-date.
(add-hook 'today-visible-calendar-hook 'calendar-star-date)
Another standard hook function marks the current date, either by changing its face or by adding an asterisk. Here's how to use it:
(add-hook 'today-visible-calendar-hook 'calendar-mark-today)
The variable calendar-today-marker specifies how to mark today's date. Its value should be a character to insert next to the date or a face name to use for displaying the date. A face named calendar-today-face is provided for this purpose; that symbol is the default for this variable when Emacs supports multiple faces on your terminal.

A similar normal hook, today-invisible-calendar-hook is run if the current date is not visible in the window.

Customizing the Holidays

Emacs knows about holidays defined by entries on one of several lists. You can customize these lists of holidays to your own needs, adding or deleting holidays. The lists of holidays that Emacs uses are for general holidays (general-holidays), local holidays (local-holidays), Christian holidays (christian-holidays), Hebrew (Jewish) holidays (hebrew-holidays), Islamic (Moslem) holidays (islamic-holidays), and other holidays (other-holidays).

The general holidays are, by default, holidays common throughout the United States. To eliminate these holidays, set general-holidays to nil.

There are no default local holidays (but sites may supply some). You can set the variable local-holidays to any list of holidays, as described below.

By default, Emacs does not include all the holidays of the religions that it knows, only those commonly found in secular calendars. For a more extensive collection of religious holidays, you can set any (or all) of the variables all-christian-calendar-holidays, all-hebrew-calendar-holidays, or all-islamic-calendar-holidays to t. If you want to eliminate the religious holidays, set any or all of the corresponding variables christian-holidays, hebrew-holidays, and islamic-holidays to nil.

You can set the variable other-holidays to any list of holidays. This list, normally empty, is intended for individual use.

Each of the lists (general-holidays, local-holidays, christian-holidays, hebrew-holidays, islamic-holidays, and other-holidays) is a list of holiday forms, each holiday form describing a holiday (or sometimes a list of holidays).

Here is a table of the possible kinds of holiday form. Day numbers and month numbers count starting from 1, but "dayname" numbers count Sunday as 0. The element string is always the name of the holiday, as a string.

(holiday-fixed month day string)
A fixed date on the Gregorian calendar.
(holiday-float month dayname k string)
The kth dayname in month on the Gregorian calendar (dayname=0 for Sunday, and so on); negative k means count back from the end of the month.
(holiday-hebrew month day string)
A fixed date on the Hebrew calendar.
(holiday-islamic month day string)
A fixed date on the Islamic calendar.
(holiday-julian month day string)
A fixed date on the Julian calendar.
(holiday-sexp sexp string)
A date calculated by the Lisp expression sexp. The expression should use the variable year to compute and return the date of a holiday, or nil if the holiday doesn't happen this year. The value of sexp must represent the date as a list of the form (month day year).
(if condition holiday-form)
A holiday that happens only if condition is true.
(function [args])
A list of dates calculated by the function function, called with arguments args.
For example, suppose you want to add Bastille Day, celebrated in France on July 14. You can do this as follows:
(setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
The holiday form (holiday-fixed 7 14 "Bastille Day") specifies the fourteenth day of the seventh month (July).

Many holidays occur on a specific day of the week, at a specific time of month. Here is a holiday form describing Hurricane Supplication Day, celebrated in the Virgin Islands on the fourth Monday in August:
(holiday-float 8 1 4 "Hurricane Supplication Day")
Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in the month (1 specifies the first occurrence, 2 the second occurrence, -1 the last occurrence, -2 the second-to-last occurrence, and so on).

You can specify holidays that occur on fixed days of the Hebrew, Islamic, and Julian calendars too. For example,
(setq other-holidays
      '((holiday-hebrew 10 2 "Last day of Hanukkah")
        (holiday-islamic 3 12 "Mohammed's Birthday")
        (holiday-julian 4 2 "Jefferson's Birthday")))
adds the last day of Hanukkah (since the Hebrew months are numbered with 1 starting from Nisan), the Islamic feast celebrating Mohammed's birthday (since the Islamic months are numbered from 1 starting with Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the Julian calendar.

To include a holiday conditionally, use either Emacs Lisp's if or the holiday-sexp form. For example, American presidential elections occur on the first Tuesday after the first Monday in November of years divisible by 4:
(holiday-sexp (if (= 0 (% year 4))
                   (calendar-gregorian-from-absolute
                    (1+ (calendar-dayname-on-or-before
                          1 (+ 6 (calendar-absolute-from-gregorian
                                  (list 11 1 year))))))
              "US Presidential Election"))
or
(if (= 0 (% displayed-year 4))
    (fixed 11
           (extract-calendar-day
             (calendar-gregorian-from-absolute
               (1+ (calendar-dayname-on-or-before
                     1 (+ 6 (calendar-absolute-from-gregorian
                              (list 11 1 displayed-year)))))))
           "US Presidential Election"))
Some holidays just don't fit into any of these forms because special calculations are involved in their determination. In such cases you must write a Lisp function to do the calculation. To include eclipses, for example, add (eclipses) to other-holidays and write an Emacs Lisp function eclipses that returns a (possibly empty) list of the relevant Gregorian dates among the range visible in the calendar window, with descriptive strings, like this:
(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
Date Display Format

You can customize the manner of displaying dates in the diary, in mode lines, and in messages by setting calendar-date-display-form. This variable holds a list of expressions that can involve the variables month, day, and year, which are all numbers in string form, and monthname and dayname, which are both alphabetic strings. In the American style, the default value of this list is as follows:
((if dayname (concat dayname ", ")) monthname " " day ", " year)
while in the European style this value is the default:
((if dayname (concat dayname ", ")) day " " monthname " " year)
The ISO standard date representation is this:
(year "-" month "-" day)
This specifies a typical American format:
(month "/" day "/" (substring year -2))
Time Display Format

The calendar and diary by default display times of day in the conventional American style with the hours from 1 through 12, minutes, and either `am' or `pm'. If you prefer the European style, also known in the US as military, in which the hours go from 00 to 23, you can alter the variable calendar-time-display-form. This variable is a list of expressions that can involve the variables 12-hours, 24-hours, and minutes, which are all numbers in string form, and am-pm and time-zone, which are both alphabetic strings. The default value of calendar-time-display-form is as follows:
(12-hours ":" minutes am-pm
          (if time-zone " (") time-zone (if time-zone ")"))
Here is a value that provides European style times:
(24-hours ":" minutes
          (if time-zone " (") time-zone (if time-zone ")"))
Daylight Savings Time

Emacs understands the difference between standard time and daylight savings time--the times given for sunrise, sunset, solstices, equinoxes, and the phases of the moon take that into account. The rules for daylight savings time vary from place to place and have also varied historically from year to year. To do the job properly, Emacs needs to know which rules to use.

Some operating systems keep track of the rules that apply to the place where you are; on these systems, Emacs gets the information it needs from the system automatically. If some or all of this information is missing, Emacs fills in the gaps with the rules currently used in Cambridge, Massachusetts, which is the center of GNU's world.

If the default choice of rules is not appropriate for your location, you can tell Emacs the rules to use by setting the variables calendar-daylight-savings-starts and calendar-daylight-savings-ends. Their values should be Lisp expressions that refer to the variable year, and evaluate to the Gregorian date on which daylight savings time starts or (respectively) ends, in the form of a list (month day year). The values should be nil if your area does not use daylight savings time.

Emacs uses these expressions to determine the start and end dates of daylight savings time as holidays and for correcting times of day in the solar and lunar calculations.

The values for Cambridge, Massachusetts are as follows:
(calendar-nth-named-day 1 0 4 year)
(calendar-nth-named-day -1 0 10 year)
i.e., the first 0th day (Sunday) of the fourth month (April) in the year specified by year, and the last Sunday of the tenth month (October) of that year. If daylight savings time were changed to start on October 1, you would set calendar-daylight-savings-starts to this:
(list 10 1 year)
For a more complex example, suppose daylight savings time begins on the first of Nisan on the Hebrew calendar. You should set calendar-daylight-savings-starts to this value:
(calendar-gregorian-from-absolute
  (calendar-absolute-from-hebrew
    (list 1 1 (+ year 3760))))
because Nisan is the first month in the Hebrew calendar and the Hebrew year differs from the Gregorian year by 3760 at Nisan.

If there is no daylight savings time at your location, or if you want all times in standard time, set calendar-daylight-savings-starts and calendar-daylight-savings-ends to nil.

The variable calendar-daylight-time-offset specifies the difference between daylight savings time and standard time, measured in minutes. The value for Cambridge is 60.

The variable calendar-daylight-savings-starts-time and the variable calendar-daylight-savings-ends-time specify the number of minutes after midnight local time when the transition to and from daylight savings time should occur. For Cambridge, both variables' values are 120.

Customizing the Diary

Ordinarily, the mode line of the diary buffer window indicates any holidays that fall on the date of the diary entries. The process of checking for holidays can take several seconds, so including holiday information delays the display of the diary buffer noticeably. If you'd prefer to have a faster display of the diary buffer but without the holiday information, set the variable holidays-in-diary-buffer to nil.

The variable number-of-diary-entries controls the number of days of diary entries to be displayed at one time. It affects the initial display when view-diary-entries-initially is t, as well as the command M-x diary. For example, the default value is 1, which says to display only the current day's diary entries. If the value is 2, both the current day's and the next day's entries are displayed. The value can also be a vector of seven elements: for example, if the value is [0 2 2 2 2 4 1] then no diary entries appear on Sunday, the current date's and the next day's diary entries appear Monday through Thursday, Friday through Monday's entries appear on Friday, while on Saturday only that day's entries appear.

The variable print-diary-entries-hook is a normal hook run after preparation of a temporary buffer containing just the diary entries currently visible in the diary buffer. (The other, irrelevant diary entries are really absent from the temporary buffer; in the diary buffer, they are merely hidden.) The default value of this hook does the printing with the command lpr-buffer. If you want to use a different command to do the printing, just change the value of this hook. Other uses might include, for example, rearranging the lines into order by day and time.

You can customize the form of dates in your diary file, if neither the standard American nor European styles suits your needs, by setting the variable diary-date-forms. This variable is a list of patterns for recognizing a date. Each date pattern is a list whose elements may be regular expressions (see section Regular Expressions) or the symbols month, day, year, monthname, and dayname. All these elements serve as patterns that match certain kinds of text in the diary file. In order for the date pattern, as a whole, to match, all of its elements must match consecutively.

A regular expression in a date pattern matches in its usual fashion, using the standard syntax table altered so that `*' is a word constituent.

The symbols month, day, year, monthname, and dayname match the month number, day number, year number, month name, and day name of the date being considered. The symbols that match numbers allow leading zeros; those that match names allow three-letter abbreviations and capitalization. All the symbols can match `*'; since `*' in a diary entry means "any day", "any month", and so on, it should match regardless of the date being considered.

The default value of diary-date-forms in the American style is this:
((month "/" day "[^/0-9]")
 (month "/" day "/" year "[^0-9]")
 (monthname " *" day "[^,0-9]")
 (monthname " *" day ", *" year "[^0-9]")
 (dayname "\\W"))
The date patterns in the list must be mutually exclusive and must not match any portion of the diary entry itself, just the date and one character of whitespace. If, to be mutually exclusive, the pattern must match a portion of the diary entry text--beyond the whitespace that ends the date--then the first element of the date pattern must be backup. This causes the date recognizer to back up to the beginning of the current word of the diary entry, after finishing the match. Even if you use backup, the date pattern must absolutely not match more than a portion of the first word of the diary entry. The default value of diary-date-forms in the European style is this list:
((day "/" month "[^/0-9]")
 (day "/" month "/" year "[^0-9]")
 (backup day " *" monthname "\\W+\\<[^*0-9]")
 (day " *" monthname " *" year "[^0-9]")
 (dayname "\\W"))
Notice the use of backup in the third pattern, because it needs to match part of a word beyond the date itself to distinguish it from the fourth pattern.

Hebrew- and Islamic-Date Diary Entries

Your diary file can have entries based on Hebrew or Islamic dates, as well as entries based on the world-standard Gregorian calendar. However, because recognition of such entries is time-consuming and most people don't use them, you must explicitly enable their use. If you want the diary to recognize Hebrew-date diary entries, for example, you must do this:
(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
If you want Islamic-date entries, do this:
(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
Hebrew- and Islamic-date diary entries have the same formats as Gregorian-date diary entries, except that `H' precedes a Hebrew date and `I' precedes an Islamic date. Moreover, because the Hebrew and Islamic month names are not uniquely specified by the first three letters, you may not abbreviate them. For example, a diary entry for the Hebrew date Heshvan 25 could look like this:
HHeshvan 25 Happy Hebrew birthday!
and would appear in the diary for any date that corresponds to Heshvan 25 on the Hebrew calendar. And here is an Islamic-date diary entry that matches Dhu al-Qada 25:
IDhu al-Qada 25 Happy Islamic birthday!
As with Gregorian-date diary entries, Hebrew- and Islamic-date entries are nonmarking if they are preceded with an ampersand (`&').

Here is a table of commands used in the calendar to create diary entries that match the selected date and other dates that are similar in the Hebrew or Islamic calendar:

i h d
Add a diary entry for the Hebrew date corresponding to the selected date (insert-hebrew-diary-entry).
i h m
Add a diary entry for the day of the Hebrew month corresponding to the selected date (insert-monthly-hebrew-diary-entry). This diary entry matches any date that has the same Hebrew day-within-month as the selected date.
i h y
Add a diary entry for the day of the Hebrew year corresponding to the selected date (insert-yearly-hebrew-diary-entry). This diary entry matches any date which has the same Hebrew month and day-within-month as the selected date.
i i d
Add a diary entry for the Islamic date corresponding to the selected date (insert-islamic-diary-entry).
i i m
Add a diary entry for the day of the Islamic month corresponding to the selected date (insert-monthly-islamic-diary-entry).
i i y
Add a diary entry for the day of the Islamic year corresponding to the selected date (insert-yearly-islamic-diary-entry).
These commands work much like the corresponding commands for ordinary diary entries: they apply to the date that point is on in the calendar window, and what they do is insert just the date portion of a diary entry at the end of your diary file. You must then insert the rest of the diary entry.

Fancy Diary Display

Diary display works by preparing the diary buffer and then running the hook diary-display-hook. The default value of this hook (simple-diary-display) hides the irrelevant diary entries and then displays the buffer. However, if you specify the hook as follows,
(add-hook 'diary-display-hook 'fancy-diary-display)
this enables fancy diary display. It displays diary entries and holidays by copying them into a special buffer that exists only for the sake of display. Copying to a separate buffer provides an opportunity to change the displayed text to make it prettier--for example, to sort the entries by the dates they apply to.

As with simple diary display, you can print a hard copy of the buffer with print-diary-entries. To print a hard copy of a day-by-day diary for a week by positioning point on Sunday of that week, type 7 d and then do M-x print-diary-entries. As usual, the inclusion of the holidays slows down the display slightly; you can speed things up by setting the variable holidays-in-diary-buffer to nil.

Ordinarily, the fancy diary buffer does not show days for which there are no diary entries, even if that day is a holiday. If you want such days to be shown in the fancy diary buffer, set the variable diary-list-include-blanks to t.

If you use the fancy diary display, you can use the normal hook list-diary-entries-hook to sort each day's diary entries by their time of day. Here's how:
(add-hook 'list-diary-entries-hook 'sort-diary-entries t)
For each day, this sorts diary entries that begin with a recognizable time of day according to their times. Diary entries without times come first within each day.

Fancy diary display also has the ability to process included diary files. This permits a group of people to share a diary file for events that apply to all of them. Lines in the diary file of this form:
#include "filename"
includes the diary entries from the file filename in the fancy diary buffer. The include mechanism is recursive, so that included files can include other files, and so on; you must be careful not to have a cycle of inclusions, of course. Here is how to enable the include facility:
(add-hook 'list-diary-entries-hook 'include-other-diary-files)
(add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
The include mechanism works only with the fancy diary display, because ordinary diary display shows the entries directly from your diary file.

Sexp Entries and the Fancy Diary Display

Sexp diary entries allow you to do more than just have complicated conditions under which a diary entry applies. If you use the fancy diary display, sexp entries can generate the text of the entry depending on the date itself. For example, an anniversary diary entry can insert the number of years since the anniversary date into the text of the diary entry. Thus the `%d' in this dairy entry:
%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
gets replaced by the age, so on October 31, 1990 the entry appears in the fancy diary buffer like this:
Arthur's birthday (42 years old)
If the diary file instead contains this entry:
%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
the entry in the fancy diary buffer for October 31, 1990 appears like this:
Arthur's 42nd birthday
Similarly, cyclic diary entries can interpolate the number of repetitions that have occurred:
%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
looks like this:
Renew medication (5th time)
in the fancy diary display on September 8, 1990.

There is an early reminder diary sexp that includes its entry in the diary not only on the date of occurrence, but also on earlier dates. For example, if you want a reminder a week before your anniversary, you can use
%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
and the fancy diary will show
Ruth & Ed's anniversary
both on December 15 and on December 22.

The function diary-date applies to dates described by a month, day, year combination, each of which can be an integer, a list of integers, or t. The value t means all values. For example,
%%(diary-date '(10 11 12) 22 t) Rake leaves
causes the fancy diary to show
Rake leaves
on October 22, November 22, and December 22 of every year.

The function diary-float allows you to describe diary entries that apply to dates like the third Friday of November, or the last Tuesday in April. The parameters are the month, dayname, and an index n. The entry appears on the nth dayname of month, where dayname=0 means Sunday, 1 means Monday, and so on. If n is negative it counts backward from the end of month. The value of month can be a list of months, a single month, or t to specify all months. You can also use an optional parameter day to specify the nth dayname of month on or after/before day; the value of day defaults to 1 if n is positive and to the last day of month if n is negative. For example,
%%(diary-float t 1 -1) Pay rent
causes the fancy diary to show
Pay rent
on the last Monday of every month.

The generality of sexp diary entries lets you specify any diary entry that you can describe algorithmically. A sexp diary entry contains an expression that computes whether the entry applies to any given date. If its value is non-nil, the entry applies to that date; otherwise, it does not. The expression can use the variable date to find the date being considered; its value is a list (month day year) that refers to the Gregorian calendar.

Suppose you get paid on the 21st of the month if it is a weekday, and on the Friday before if the 21st is on a weekend. Here is how to write a sexp diary entry that matches those dates:
&%%(let ((dayname (calendar-day-of-week date))
         (day (car (cdr date))))
      (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
          (and (memq day '(19 20)) (= dayname 5)))
         ) Pay check deposited
The following sexp diary entries take advantage of the ability (in the fancy diary display) to concoct diary entries whose text varies based on the date:

%%(diary-sunrise-sunset)
Make a diary entry for the local times of today's sunrise and sunset.
%%(diary-phases-of-moon)
Make a diary entry for the phases (quarters) of the moon.
%%(diary-day-of-year)
Make a diary entry with today's day number in the current year and the number of days remaining in the current year.
%%(diary-iso-date)
Make a diary entry with today's equivalent ISO commercial date.
%%(diary-julian-date)
Make a diary entry with today's equivalent date on the Julian calendar.
%%(diary-astro-day-number)
Make a diary entry with today's equivalent astronomical (Julian) day number.
%%(diary-hebrew-date)
Make a diary entry with today's equivalent date on the Hebrew calendar.
%%(diary-islamic-date)
Make a diary entry with today's equivalent date on the Islamic calendar.
%%(diary-french-date)
Make a diary entry with today's equivalent date on the French Revolutionary calendar.
%%(diary-mayan-date)
Make a diary entry with today's equivalent date on the Mayan calendar.
Thus including the diary entry
&%%(diary-hebrew-date)
causes every day's diary display to contain the equivalent date on the Hebrew calendar, if you are using the fancy diary display. (With simple diary display, the line `&%%(diary-hebrew-date)' appears in the diary for any date, but does nothing particularly useful.)

These functions can be used to construct sexp diary entries based on the Hebrew calendar in certain standard ways:

%%(diary-rosh-hodesh)
Make a diary entry that tells the occurrence and ritual announcement of each new Hebrew month.
%%(diary-parasha)
Make a Saturday diary entry that tells the weekly synagogue scripture reading.
%%(diary-sabbath-candles)
Make a Friday diary entry that tells the local time of Sabbath candle lighting.
%%(diary-omer)
Make a diary entry that gives the omer count, when appropriate.
%%(diary-yahrzeit month day year) name
Make a diary entry marking the anniversary of a date of death. The date is the Gregorian (civil) date of death. The diary entry appears on the proper Hebrew calendar anniversary and on the day before. (In the European style, the order of the parameters is changed to day, month, year.)
Customizing Appointment Reminders

You can specify exactly how Emacs reminds you of an appointment, and how far in advance it begins doing so, by setting these variables:

appt-message-warning-time
The time in minutes before an appointment that the reminder begins. The default is 10 minutes.
appt-audible
If this is non-nil, Emacs rings the terminal bell for appointment reminders. The default is t.
appt-visible
If this is non-nil, Emacs displays the appointment message in the echo area. The default is t.
appt-display-mode-line
If this is non-nil, Emacs displays the number of minutes to the appointment on the mode line. The default is t.
appt-msg-window
If this is non-nil, Emacs displays the appointment message in another window. The default is t.
appt-disp-window-function
This variable holds a function to use to create the other window for the appointment message.
appt-delete-window-function
This variable holds a function to use to get rid of the appointment message window, when its time is up.
appt-display-duration
The number of seconds to display an appointment message. The default is 5 seconds.
Tips and Conventions

This chapter describes no additional features of Emacs Lisp. Instead it gives advice on making effective use of the features described in the previous chapters, and describes conventions Emacs Lisp programmers should follow.

Emacs Lisp Coding Conventions

Here are conventions that you should follow when writing Emacs Lisp code intended for widespread use:

Since all global variables share the same name space, and all functions share another name space, you should choose a short word to distinguish your program from other Lisp programs. Then take care to begin the names of all global variables, constants, and functions with the chosen prefix. This helps avoid name conflicts. This recommendation applies even to names for traditional Lisp primitives that are not primitives in Emacs Lisp--even to copy-list. Believe it or not, there is more than one plausible way to define copy-list. Play it safe; append your name prefix to produce a name like foo-copy-list or mylib-copy-list instead. If you write a function that you think ought to be added to Emacs under a certain name, such as twiddle-files, don't call it by that name in your program. Call it mylib-twiddle-files in your program, and send mail to `bug-gnu-emacs@gnu.org' suggesting we add it to Emacs. If and when we do, we can change the name easily enough. If one prefix is insufficient, your package may use two or three alternative common prefixes, so long as they make sense. Separate the prefix from the rest of the symbol name with a hyphen, `-'. This will be consistent with Emacs itself and with most Emacs Lisp programs.
It is often useful to put a call to provide in each separate library program, at least if there is more than one entry point to the program.
If a file requires certain other library programs to be loaded beforehand, then the comments at the beginning of the file should say so. Also, use require to make sure they are loaded.
If one file foo uses a macro defined in another file bar, foo should contain this expression before the first use of the macro:
(eval-when-compile (require 'bar))
(And the library bar should contain (provide 'bar), to make the require work.) This will cause bar to be loaded when you byte-compile foo. Otherwise, you risk compiling foo without the necessary macro loaded, and that would produce compiled code that won't work right. See section Macros and Byte Compilation. Using eval-when-compile avoids loading bar when the compiled version of foo is used.
When defining a major mode, please follow the major mode conventions. See section Major Mode Conventions.
When defining a minor mode, please follow the minor mode conventions. See section Conventions for Writing Minor Modes.
If the purpose of a function is to tell you whether a certain condition is true or false, give the function a name that ends in `p'. If the name is one word, add just `p'; if the name is multiple words, add `-p'. Examples are framep and frame-live-p.
If a user option variable records a true-or-false condition, give it a name that ends in `-flag'.
Please do not define C-c letter as a key in your major modes. These sequences are reserved for users; they are the only sequences reserved for users, so do not block them. Instead, define sequences consisting of C-c followed by a control character, a digit, or certain punctuation characters. These sequences are reserved for major modes. Changing all the Emacs major modes to follow this convention was a lot of work. Abandoning this convention would make that work go to waste, and inconvenience users.
Sequences consisting of C-c followed by {, }, <, >, : or ; are also reserved for major modes.
Sequences consisting of C-c followed by any other punctuation character are allocated for minor modes. Using them in a major mode is not absolutely prohibited, but if you do that, the major mode binding may be shadowed from time to time by minor modes.
Function keys F5 through F9 without modifier keys are reserved for users to define.
Do not bind C-h following any prefix character (including C-c). If you don't bind C-h, it is automatically available as a help character for listing the subcommands of the prefix character.
Do not bind a key sequence ending in ESC except following another ESC. (That is, it is OK to bind a sequence ending in ESC ESC.) The reason for this rule is that a non-prefix binding for ESC in any context prevents recognition of escape sequences as function keys in that context.
Anything which acts like a temporary mode or state which the user can enter and leave should define ESC ESC of ESC ESC ESC as a way to escape. For a state which accepts ordinary Emacs commands, or more generally any kind of state in which ESC followed by a function key or arrow key is potentially meaningful, then you must not define ESC ESC, since that would preclude recognizing an escape sequence after ESC. In these states, you should define ESC ESC ESC as the way to escape. Otherwise, define ESC ESC instead.
Applications should not bind mouse events based on button 1 with the shift key held down. These events include S-mouse-1, M-S-mouse-1, C-S-mouse-1, and so on. They are reserved for users.
Special major modes used for read-only text should usually redefine mouse-2 and RET to trace some sort of reference in the text. Modes such as Dired, Info, Compilation, and Occur redefine it in this way.
When a package provides a modification of ordinary Emacs behavior, it is good to include a command to enable and disable the feature, Provide a command named whatever-mode which turns the feature on or off, and make it autoload (see section Autoload). Design the package so that simply loading it has no visible effect--that should not enable the feature. Users will request the feature by invoking the command.
It is a bad idea to define aliases for the Emacs primitives. Use the standard names instead.
Redefining (or advising) an Emacs primitive is discouraged. It may do the right thing for a particular program, but there is no telling what other programs might break as a result.
If a file does replace any of the functions or library programs of standard Emacs, prominent comments at the beginning of the file should say which functions are replaced, and how the behavior of the replacements differs from that of the originals.
Please keep the names of your Emacs Lisp source files to 13 characters or less. This way, if the files are compiled, the compiled files' names will be 14 characters or less, which is short enough to fit on all kinds of Unix systems.
Don't use next-line or previous-line in programs; nearly always, forward-line is more convenient as well as more predictable and robust. See section Motion by Text Lines.
Don't call functions that set the mark, unless setting the mark is one of the intended features of your program. The mark is a user-level feature, so it is incorrect to change the mark except to supply a value for the user's benefit. See section The Mark. In particular, don't use any of these functions:

beginning-of-buffer, end-of-buffer
replace-string, replace-regexp
If you just want to move point, or replace a certain string, without any of the other features intended for interactive users, you can replace these functions with one or two lines of simple Lisp code.
Use lists rather than vectors, except when there is a particular reason to use a vector. Lisp has more facilities for manipulating lists than for vectors, and working with lists is usually more convenient. Vectors are advantageous for tables that are substantial in size and are accessed in random order (not searched front to back), provided there is no need to insert or delete elements (only lists allow that).
The recommended way to print a message in the echo area is with the message function, not princ. See section The Echo Area.
When you encounter an error condition, call the function error (or signal). The function error does not return. See section How to Signal an Error. Do not use message, throw, sleep-for, or beep to report errors.
An error message should start with a capital letter but should not end with a period.
Many commands that take a long time to execute display a message that says `Operating...' when they start, and change it to `Operating...done' when they finish. Please keep the style of these messages uniform: no space around the ellipsis, and no period at the end.
Try to avoid using recursive edits. Instead, do what the Rmail e command does: use a new local keymap that contains one command defined to switch back to the old local keymap. Or do what the edit-options command does: switch to another buffer and let the user switch back at will. See section Recursive Editing.
In some other systems there is a convention of choosing variable names that begin and end with `*'. We don't use that convention in Emacs Lisp, so please don't use it in your programs. (Emacs uses such names only for special-purpose buffers.) The users will find Emacs more coherent if all libraries use the same conventions.
Try to avoid compiler warnings about undefined free variables, by adding defvar definitions for these variables. If you bind a variable in one function, and use it or set it in another function, the compiler warns about the latter function unless the variable has a definition. But often these variables have short names, and it is not clean for Lisp packages to define such variable names. Therefore, you should rename the variable to start with the name prefix used for the other functions and variables in your package.
Indent each function with C-M-q (indent-sexp) using the default indentation parameters.
Don't make a habit of putting close-parentheses on lines by themselves; Lisp programmers find this disconcerting. Once in a while, when there is a sequence of many consecutive close-parentheses, it may make sense to split the sequence in one or two significant places.
Please put a copyright notice on the file if you give copies to anyone. Use a message like this one:
;; Copyright (C) year name

;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2 of
;; the License, or (at your option) any later version.

;; This program is distributed in the hope that it will be
;; useful, but WITHOUT ANY WARRANTY; without even the implied
;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
;; PURPOSE.  See the GNU General Public License for more details.

;; You should have received a copy of the GNU General Public
;; License along with this program; if not, write to the Free
;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
;; MA 02111-1307 USA
If you have signed papers to assign the copyright to the Foundation, then use `Free Software Foundation, Inc.' as name. Otherwise, use your name.

Tips for Making Compiled Code Fast

Here are ways of improving the execution speed of byte-compiled Lisp programs.

Profile your program with the `profile' library or the `elp' library. See the files `profile.el' and `elp.el' for instructions.
Use iteration rather than recursion whenever possible. Function calls are slow in Emacs Lisp even when a compiled function is calling another compiled function.
Using the primitive list-searching functions memq, member, assq, or assoc is even faster than explicit iteration. It can be worth rearranging a data structure so that one of these primitive search functions can be used.
Certain built-in functions are handled specially in byte-compiled code, avoiding the need for an ordinary function call. It is a good idea to use these functions rather than alternatives. To see whether a function is handled specially by the compiler, examine its byte-compile property. If the property is non-nil, then the function is handled specially. For example, the following input will show you that aref is compiled specially (see section Functions that Operate on Arrays):
(get 'aref 'byte-compile)
     => byte-compile-two-args
If calling a small function accounts for a substantial part of your program's running time, make the function inline. This eliminates the function call overhead. Since making a function inline reduces the flexibility of changing the program, don't do it unless it gives a noticeable speedup in something slow enough that users care about the speed. See section Inline Functions.

Tips for Documentation Strings

Here are some tips and conventions for the writing of documentation strings. You can check many of these conventions by running the command M-x checkdoc-minor-mode.

Every command, function, or variable intended for users to know about should have a documentation string.
An internal variable or subroutine of a Lisp program might as well have a documentation string. In earlier Emacs versions, you could save space by using a comment instead of a documentation string, but that is no longer the case.
The first line of the documentation string should consist of one or two complete sentences that stand on their own as a summary. M-x apropos displays just the first line, and if it doesn't stand on its own, the result looks bad. In particular, start the first line with a capital letter and end with a period. The documentation string can have additional lines that expand on the details of how to use the function or variable. The additional lines should be made up of complete sentences also, but they may be filled if that looks good.
For consistency, phrase the verb in the first sentence of a function's documentation string as an infinitive with "to" omitted. For instance, use "Return the cons of A and B." in preference to "Returns the cons of A and B." Usually it looks good to do likewise for the rest of the first paragraph. Subsequent paragraphs usually look better if they have proper subjects.
Write documentation strings in the active voice, not the passive, and in the present tense, not the future. For instance, use "Return a list containing A and B." instead of "A list containing A and B will be returned."
Avoid using the word "cause" (or its equivalents) unnecessarily. Instead of, "Cause Emacs to display text in boldface," write just "Display text in boldface."
Do not start or end a documentation string with whitespace.
Format the documentation string so that it fits in an Emacs window on an 80-column screen. It is a good idea for most lines to be no wider than 60 characters. The first line can be wider if necessary to fit the information that ought to be there. However, rather than simply filling the entire documentation string, you can make it much more readable by choosing line breaks with care. Use blank lines between topics if the documentation string is long.
Do not indent subsequent lines of a documentation string so that the text is lined up in the source code with the text of the first line. This looks nice in the source code, but looks bizarre when users view the documentation. Remember that the indentation before the starting double-quote is not part of the string!
When the user tries to use a disabled command, Emacs displays just the first paragraph of its documentation string--everything through the first blank line. If you wish, you can choose which information to include before the first blank line so as to make this display useful.
A variable's documentation string should start with `*' if the variable is one that users would often want to set interactively. If the value is a long list, or a function, or if the variable would be set only in init files, then don't start the documentation string with `*'. See section Defining Global Variables.
The documentation string for a variable that is a yes-or-no flag should start with words such as "Non-nil means...", to make it clear that all non-nil values are equivalent and indicate explicitly what nil and non-nil mean.
When a function's documentation string mentions the value of an argument of the function, use the argument name in capital letters as if it were a name for that value. Thus, the documentation string of the function / refers to its second argument as `DIVISOR', because the actual argument name is divisor. Also use all caps for meta-syntactic variables, such as when you show the decomposition of a list or vector into subunits, some of which may vary.
When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), with single-quotes around it. For example: ``lambda''. There are two exceptions: write t and nil without single-quotes. Help mode automatically creates a hyperlink when a documentation string uses a symbol name inside single quotes, if the symbol has either a function or a variable definition. You do not need to do anything special to make use of this feature. However, when a symbol has both a function definition and a variable definition, and you want to refer to just one of them, you can specify which one by writing one of the words `variable', `option', `function', or `command', immediately before the symbol name. (Case makes no difference in recognizing these indicator words.) For example, if you write
This function sets the variable `buffer-file-name'.
then the hyperlink will refer only to the variable documentation of buffer-file-name, and not to its function documentation. If a symbol has a function definition and/or a variable definition, but those are irrelevant to the use of the symbol that you are documenting, you can write the word `symbol' before the symbol name to prevent making any hyperlink. For example,
If the argument KIND-OF-RESULT is the symbol `list',
this function returns a list of all the objects
that satisfy the criterion.
does not make a hyperlink to the documentation, irrelevant here, of the function list.
Don't write key sequences directly in documentation strings. Instead, use the `\\[...]' construct to stand for them. For example, instead of writing `C-f', write the construct `\\[forward-char]'. When Emacs displays the documentation string, it substitutes whatever key is currently bound to forward-char. (This is normally `C-f', but it may be some other character if the user has moved key bindings.) See section Substituting Key Bindings in Documentation.
In documentation strings for a major mode, you will want to refer to the key bindings of that mode's local map, rather than global ones. Therefore, use the construct `\\<...>' once in the documentation string to specify which key map to use. Do this before the first use of `\\[...]'. The text inside the `\\<...>' should be the name of the variable containing the local keymap for the major mode. It is not practical to use `\\[...]' very many times, because display of the documentation string will become slow. So use this to describe the most important commands in your major mode, and then use `\\{...}' to display the rest of the mode's keymap.

Tips on Writing Comments

We recommend these conventions for where to put comments and how to indent them:

`;'
Comments that start with a single semicolon, `;', should all be aligned to the same column on the right of the source code. Such comments usually explain how the code on the same line does its job. In Lisp mode and related modes, the M-; (indent-for-comment) command automatically inserts such a `;' in the right place, or aligns such a comment if it is already present. This and following examples are taken from the Emacs sources.
(setq base-version-list                 ; there was a base
      (assoc (substring fn 0 start-vn)  ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion
`;;'
Comments that start with two semicolons, `;;', should be aligned to the same level of indentation as the code. Such comments usually describe the purpose of the following lines or the state of the program at that point. For example:
(prog1 (setq auto-fill-function
             ...
             ...
  ;; update mode line
  (force-mode-line-update)))
Every function that has no documentation string (presumably one that is used only internally within the package it belongs to), should have instead a two-semicolon comment right before the function, explaining what the function does and how to call it properly. Explain precisely what each argument means and how the function interprets its possible values.
`;;;'
Comments that start with three semicolons, `;;;', should start at the left margin. Such comments are used outside function definitions to make general statements explaining the design principles of the program. For example:
;;; This Lisp code is run in Emacs
;;; when it is to operate as a server
;;; for other processes.
Another use for triple-semicolon comments is for commenting out lines within a function. We use triple-semicolons for this precisely so that they remain at the left margin.
(defun foo (a)
;;; This is no longer necessary.
;;;  (force-mode-line-update)
  (message "Finished with %s" a))
`;;;;'
Comments that start with four semicolons, `;;;;', should be aligned to the left margin and are used for headings of major sections of a program. For example:
;;;; The kill ring
The indentation commands of the Lisp modes in Emacs, such as M-; (indent-for-comment) and TAB (lisp-indent-line), automatically indent comments according to these conventions, depending on the number of semicolons. See section `Manipulating Comments' in The GNU Emacs Manual.

Conventional Headers for Emacs Libraries

Emacs has conventions for using special comments in Lisp libraries to divide them into sections and give information such as who wrote them. This section explains these conventions. First, an example:
;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers

;; Copyright (C) 1992 Free Software Foundation, Inc.

;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
;; Created: 14 Jul 1992
;; Version: 1.2
;; Keywords: docs

;; This file is part of GNU Emacs.
...
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
The very first line should have this format:
;;; filename --- description
The description should be complete in one line.

After the copyright notice come several header comment lines, each beginning with `;; header-name:'. Here is a table of the conventional possibilities for header-name:

`Author'
This line states the name and net address of at least the principal author of the library. If there are multiple authors, you can list them on continuation lines led by ;; and a tab character, like this:
;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
;;      Dave Sill <de5@ornl.gov>
;;      Dave Brennan <brennan@hal.com>
;;      Eric Raymond <esr@snark.thyrsus.com>
`Maintainer'
This line should contain a single name/address as in the Author line, or an address only, or the string `FSF'. If there is no maintainer line, the person(s) in the Author field are presumed to be the maintainers. The example above is mildly bogus because the maintainer line is redundant. The idea behind the `Author' and `Maintainer' lines is to make possible a Lisp function to "send mail to the maintainer" without having to mine the name out by hand. Be sure to surround the network address with `<...>' if you include the person's full name as well as the network address.
`Created'
This optional line gives the original creation date of the file. For historical interest only.
`Version'
If you wish to record version numbers for the individual Lisp program, put them in this line.
`Adapted-By'
In this header line, place the name of the person who adapted the library for installation (to make it fit the style conventions, for example).
`Keywords'
This line lists keywords for the finder-by-keyword help command. Please use that command to see a list of the meaningful keywords. This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both.
Just about every Lisp library ought to have the `Author' and `Keywords' header comment lines. Use the others if they are appropriate. You can also put in header lines with other header names--they have no standard meanings, so they can't do any harm.

We use additional stylized comments to subdivide the contents of the library file. Here is a table of them:

`;;; Commentary:'
This begins introductory comments that explain how the library works. It should come right after the copying permissions, terminated by a `Change Log', `History' or `Code' comment line. This text is used by the Finder package, so it should make sense in that context.
`;;; Documentation'
This has been used in some files in place of `;;; Commentary:', but `;;; Commentary:' is preferred.
`;;; Change Log:'
This begins change log information stored in the library file (if you store the change history there). For most of the Lisp files distributed with Emacs, the change history is kept in the file `ChangeLog' and not in the source file at all; these files do not have a `;;; Change Log:' line.
`;;; Code:'
This begins the actual code of the program.
`;;; filename ends here'
This is the footer line; it appears at the very end of the file. Its purpose is to enable people to detect truncated versions of the file from the lack of a footer line.
GNU Emacs Internals

This chapter describes how the runnable Emacs executable is dumped with the preloaded Lisp libraries in it, how storage is allocated, and some internal aspects of GNU Emacs that may be of interest to C programmers.

Building Emacs

This section explains the steps involved in building the Emacs executable. You don't have to know this material to build and install Emacs, since the makefiles do all these things automatically. This information is pertinent to Emacs maintenance.

Compilation of the C source files in the `src' directory produces an executable file called `temacs', also called a bare impure Emacs. It contains the Emacs Lisp interpreter and I/O routines, but not the editing commands.

The command `temacs -l loadup' uses `temacs' to create the real runnable Emacs executable. These arguments direct `temacs' to evaluate the Lisp files specified in the file `loadup.el'. These files set up the normal Emacs editing environment, resulting in an Emacs that is still impure but no longer bare.

It takes a substantial time to load the standard Lisp files. Luckily, you don't have to do this each time you run Emacs; `temacs' can dump out an executable program called `emacs' that has these files preloaded. `emacs' starts more quickly because it does not need to load the files. This is the Emacs executable that is normally installed.

To create `emacs', use the command `temacs -batch -l loadup dump'. The purpose of `-batch' here is to prevent `temacs' from trying to initialize any of its data on the terminal; this ensures that the tables of terminal information are empty in the dumped Emacs. The argument `dump' tells `loadup.el' to dump a new executable named `emacs'.

Some operating systems don't support dumping. On those systems, you must start Emacs with the `temacs -l loadup' command each time you use it. This takes a substantial time, but since you need to start Emacs once a day at most--or once a week if you never log out--the extra time is not too severe a problem.

You can specify additional files to preload by writing a library named `site-load.el' that loads them. You may need to increase the value of PURESIZE, in `src/puresize.h', to make room for the additional data. (Try adding increments of 20000 until it is big enough.) However, the advantage of preloading additional files decreases as machines get faster. On modern machines, it is usually not advisable.

After `loadup.el' reads `site-load.el', it finds the documentation strings for primitive and preloaded functions (and variables) in the file `etc/DOC' where they are stored, by calling Snarf-documentation (see section Access to Documentation Strings).

You can specify other Lisp expressions to execute just before dumping by putting them in a library named `site-init.el'. This file is executed after the documentation strings are found.

If you want to preload function or variable definitions, there are three ways you can do this and make their documentation strings accessible when you subsequently run Emacs:

Arrange to scan these files when producing the `etc/DOC' file, and load them with `site-load.el'.
Load the files with `site-init.el', then copy the files into the installation directory for Lisp files when you install Emacs.
Specify a non-nil value for byte-compile-dynamic-docstrings as a local variable in each these files, and load them with either `site-load.el' or `site-init.el'. (This method has the drawback that the documentation strings take up space in Emacs all the time.)

It is not advisable to put anything in `site-load.el' or `site-init.el' that would alter any of the features that users expect in an ordinary unmodified Emacs. If you feel you must override normal features for your site, do it with `default.el', so that users can override your changes if they wish. See section Summary: Sequence of Actions at Start Up.

Function: dump-emacs to-file from-file
This function dumps the current state of Emacs into an executable file to-file. It takes symbols from from-file (this is normally the executable file `temacs').

If you want to use this function in an Emacs that was already dumped, you must run Emacs with `-batch'.

Pure Storage

Emacs Lisp uses two kinds of storage for user-created Lisp objects: normal storage and pure storage. Normal storage is where all the new data created during an Emacs session is kept; see the following section for information on normal storage. Pure storage is used for certain data in the preloaded standard Lisp files--data that should never change during actual use of Emacs.

Pure storage is allocated only while `temacs' is loading the standard preloaded Lisp libraries. In the file `emacs', it is marked as read-only (on operating systems that permit this), so that the memory space can be shared by all the Emacs jobs running on the machine at once. Pure storage is not expandable; a fixed amount is allocated when Emacs is compiled, and if that is not sufficient for the preloaded libraries, `temacs' crashes. If that happens, you must increase the compilation parameter PURESIZE in the file `src/puresize.h'. This normally won't happen unless you try to preload additional libraries or add features to the standard ones.

Function: purecopy object
This function makes a copy of object in pure storage and returns it. It copies strings by simply making a new string with the same characters in pure storage. It recursively copies the contents of vectors and cons cells. It does not make copies of other objects such as symbols, but just returns them unchanged. It signals an error if asked to copy markers.

This function is a no-op except while Emacs is being built and dumped; it is usually called only in the file `emacs/lisp/loaddefs.el', but a few packages call it just in case you decide to preload them.

Variable: pure-bytes-used
The value of this variable is the number of bytes of pure storage allocated so far. Typically, in a dumped Emacs, this number is very close to the total amount of pure storage available--if it were not, we would preallocate less.

Variable: purify-flag
This variable determines whether defun should make a copy of the function definition in pure storage. If it is non-nil, then the function definition is copied into pure storage.

This flag is t while loading all of the basic functions for building Emacs initially (allowing those functions to be sharable and non-collectible). Dumping Emacs as an executable always writes nil in this variable, regardless of the value it actually has before and after dumping.

You should not change this flag in a running Emacs.

Garbage Collection

When a program creates a list or the user defines a new function (such as by loading a library), that data is placed in normal storage. If normal storage runs low, then Emacs asks the operating system to allocate more memory in blocks of 1k bytes. Each block is used for one type of Lisp object, so symbols, cons cells, markers, etc., are segregated in distinct blocks in memory. (Vectors, long strings, buffers and certain other editing types, which are fairly large, are allocated in individual blocks, one per object, while small strings are packed into blocks of 8k bytes.)

It is quite common to use some storage for a while, then release it by (for example) killing a buffer or deleting the last pointer to an object. Emacs provides a garbage collector to reclaim this abandoned storage. (This name is traditional, but "garbage recycler" might be a more intuitive metaphor for this facility.)

The garbage collector operates by finding and marking all Lisp objects that are still accessible to Lisp programs. To begin with, it assumes all the symbols, their values and associated function definitions, and any data presently on the stack, are accessible. Any objects that can be reached indirectly through other accessible objects are also accessible.

When marking is finished, all objects still unmarked are garbage. No matter what the Lisp program or the user does, it is impossible to refer to them, since there is no longer a way to reach them. Their space might as well be reused, since no one will miss them. The second ("sweep") phase of the garbage collector arranges to reuse them.

The sweep phase puts unused cons cells onto a free list for future allocation; likewise for symbols and markers. It compacts the accessible strings so they occupy fewer 8k blocks; then it frees the other 8k blocks. Vectors, buffers, windows, and other large objects are individually allocated and freed using malloc and free.

Common Lisp note: Unlike other Lisps, GNU Emacs Lisp does not call the garbage collector when the free list is empty. Instead, it simply requests the operating system to allocate more storage, and processing continues until gc-cons-threshold bytes have been used.

This means that you can make sure that the garbage collector will not run during a certain portion of a Lisp program by calling the garbage collector explicitly just before it (provided that portion of the program does not use so much space as to force a second garbage collection).

Command: garbage-collect
This command runs a garbage collection, and returns information on the amount of space in use. (Garbage collection can also occur spontaneously if you use more than gc-cons-threshold bytes of Lisp data since the previous garbage collection.)

garbage-collect returns a list containing the following information:
((used-conses . free-conses)
 (used-syms . free-syms)
 (used-miscs . free-miscs)
 used-string-chars
 used-vector-slots
 (used-floats . free-floats)
 (used-intervals . free-intervals))
Here is an example:
(garbage-collect)
     => ((106886 . 13184) (9769 . 0)
                (7731 . 4651) 347543 121628
                (31 . 94) (1273 . 168))
Here is a table explaining each element:

used-conses
The number of cons cells in use.
free-conses
The number of cons cells for which space has been obtained from the operating system, but that are not currently being used.
used-syms
The number of symbols in use.
free-syms
The number of symbols for which space has been obtained from the operating system, but that are not currently being used.
used-miscs
The number of miscellaneous objects in use. These include markers and overlays, plus certain objects not visible to users.
free-miscs
The number of miscellaneous objects for which space has been obtained from the operating system, but that are not currently being used.
used-string-chars
The total size of all strings, in characters.
used-vector-slots
The total number of elements of existing vectors.
used-floats
The number of floats in use.
free-floats
The number of floats for which space has been obtained from the operating system, but that are not currently being used.
used-intervals
The number of intervals in use. Intervals are an internal data structure used for representing text properties.
free-intervals
The number of intervals for which space has been obtained from the operating system, but that are not currently being used.

User Option: garbage-collection-messages
If this variable is non-nil, Emacs displays a message at the beginning and end of garbage collection. The default value is nil, meaning there are no such messages.

User Option: gc-cons-threshold
The value of this variable is the number of bytes of storage that must be allocated for Lisp objects after one garbage collection in order to trigger another garbage collection. A cons cell counts as eight bytes, a string as one byte per character plus a few bytes of overhead, and so on; space allocated to the contents of buffers does not count. Note that the subsequent garbage collection does not happen immediately when the threshold is exhausted, but only the next time the Lisp evaluator is called.

The initial threshold value is 400,000. If you specify a larger value, garbage collection will happen less often. This reduces the amount of time spent garbage collecting, but increases total memory use. You may want to do this when running a program that creates lots of Lisp data.

You can make collections more frequent by specifying a smaller value, down to 10,000. A value less than 10,000 will remain in effect only until the subsequent garbage collection, at which time garbage-collect will set the threshold back to 10,000.

The value return by garbage-collect describes the amount of memory used by Lisp data, broken down by data type. By contrast, the function memory-limit provides information on the total amount of memory Emacs is currently using.

Function: memory-limit
This function returns the address of the last byte Emacs has allocated, divided by 1024. We divide the value by 1024 to make sure it fits in a Lisp integer.

You can use this to get a general idea of how your actions affect the memory usage.

Memory Usage

These functions and variables give information about the total amount of memory allocation that Emacs has done, broken down by data type. Note the difference between these and the values returned by (garbage-collect); those count objects that currently exist, but these count the number or size of all allocations, including those for objects that have since been freed.

Variable: cons-cells-consed
The total number of cons cells that have been allocated so far in this Emacs session.

Variable: floats-consed
The total number of floats that have been allocated so far in this Emacs session.

Variable: vector-cells-consed
The total number of vector cells that have been allocated so far in this Emacs session.

Variable: symbols-consed
The total number of symbols that have been allocated so far in this Emacs session.

Variable: string-chars-consed
The total number of string characters that have been allocated so far in this Emacs session.

Variable: misc-objects-consed
The total number of miscellaneous objects that have been allocated so far in this Emacs session. These include markers and overlays, plus certain objects not visible to users.

Variable: intervals-consed
The total number of intervals that have been allocated so far in this Emacs session.

Writing Emacs Primitives

Lisp primitives are Lisp functions implemented in C. The details of interfacing the C function so that Lisp can call it are handled by a few C macros. The only way to really understand how to write new C code is to read the source, but we can explain some things here.

An example of a special form is the definition of or, from `eval.c'. (An ordinary function would have the same general appearance.)
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
  "Eval args until one of them yields non-nil; return that value.\n\
The remaining args are not evalled at all.\n\
If all args return nil, return nil.")
  (args)
     Lisp_Object args;
{
  register Lisp_Object val;
  Lisp_Object args_left;
  struct gcpro gcpro1;

  if (NULL (args))
    return Qnil;

  args_left = args;
  GCPRO1 (args_left);

  do
    {
      val = Feval (Fcar (args_left));
      if (!NULL (val))
        break;
      args_left = Fcdr (args_left);
    }
  while (!NULL (args_left));

  UNGCPRO;
  return val;
}
Let's start with a precise explanation of the arguments to the DEFUN macro. Here is a template for them:
DEFUN (lname, fname, sname, min, max, interactive, doc)
lname
This is the name of the Lisp symbol to define as the function name; in the example above, it is or.
fname
This is the C function name for this function. This is the name that is used in C code for calling the function. The name is, by convention, `F' prepended to the Lisp name, with all dashes (`-') in the Lisp name changed to underscores. Thus, to call this function from C code, call For. Remember that the arguments must be of type Lisp_Object; various macros and functions for creating values of type Lisp_Object are declared in the file `lisp.h'.
sname
This is a C variable name to use for a structure that holds the data for the subr object that represents the function in Lisp. This structure conveys the Lisp symbol name to the initialization routine that will create the symbol and store the subr object as its definition. By convention, this name is always fname with `F' replaced with `S'.
min
This is the minimum number of arguments that the function requires. The function or allows a minimum of zero arguments.
max
This is the maximum number of arguments that the function accepts, if there is a fixed maximum. Alternatively, it can be UNEVALLED, indicating a special form that receives unevaluated arguments, or MANY, indicating an unlimited number of evaluated arguments (the equivalent of &rest). Both UNEVALLED and MANY are macros. If max is a number, it may not be less than min and it may not be greater than seven.
interactive
This is an interactive specification, a string such as might be used as the argument of interactive in a Lisp function. In the case of or, it is 0 (a null pointer), indicating that or cannot be called interactively. A value of "" indicates a function that should receive no arguments when called interactively.
doc
This is the documentation string. It is written just like a documentation string for a function defined in Lisp, except you must write `\n\' at the end of each line. In particular, the first line should be a single sentence.
After the call to the DEFUN macro, you must write the argument name list that every C function must have, followed by ordinary C declarations for the arguments. For a function with a fixed maximum number of arguments, declare a C argument for each Lisp argument, and give them all type Lisp_Object. When a Lisp function has no upper limit on the number of arguments, its implementation in C actually receives exactly two arguments: the first is the number of Lisp arguments, and the second is the address of a block containing their values. They have types int and Lisp_Object *.

Within the function For itself, note the use of the macros GCPRO1 and UNGCPRO. GCPRO1 is used to "protect" a variable from garbage collection--to inform the garbage collector that it must look in that variable and regard its contents as an accessible object. This is necessary whenever you call Feval or anything that can directly or indirectly call Feval. At such a time, any Lisp object that you intend to refer to again must be protected somehow. UNGCPRO cancels the protection of the variables that are protected in the current function. It is necessary to do this explicitly.

For most data types, it suffices to protect at least one pointer to the object; as long as the object is not recycled, all pointers to it remain valid. This is not so for strings, because the garbage collector can move them. When the garbage collector moves a string, it relocates all the pointers it knows about; any other pointers become invalid. Therefore, you must protect all pointers to strings across any point where garbage collection may be possible.

The macro GCPRO1 protects just one local variable. If you want to protect two, use GCPRO2 instead; repeating GCPRO1 will not work. Macros GCPRO3 and GCPRO4 also exist.

These macros implicitly use local variables such as gcpro1; you must declare these explicitly, with type struct gcpro. Thus, if you use GCPRO2, you must declare gcpro1 and gcpro2. Alas, we can't explain all the tricky details here.

You must not use C initializers for static or global variables unless they are never written once Emacs is dumped. These variables with initializers are allocated in an area of memory that becomes read-only (on certain operating systems) as a result of dumping Emacs. See section Pure Storage.

Do not use static variables within functions--place all static variables at top level in the file. This is necessary because Emacs on some operating systems defines the keyword static as a null macro. (This definition is used because those systems put all variables declared static in a place that becomes read-only after dumping, whether they have initializers or not.)

Defining the C function is not enough to make a Lisp primitive available; you must also create the Lisp symbol for the primitive and store a suitable subr object in its function cell. The code looks like this:
defsubr (&subr-structure-name);
Here subr-structure-name is the name you used as the third argument to DEFUN.

If you add a new primitive to a file that already has Lisp primitives defined in it, find the function (near the end of the file) named syms_of_something, and add the call to defsubr there. If the file doesn't have this function, or if you create a new file, add to it a syms_of_filename (e.g., syms_of_myfile). Then find the spot in `emacs.c' where all of these functions are called, and add a call to syms_of_filename there.

The function syms_of_filename is also the place to define any C variables that are to be visible as Lisp variables. DEFVAR_LISP makes a C variable of type Lisp_Object visible in Lisp. DEFVAR_INT makes a C variable of type int visible in Lisp with a value that is always an integer. DEFVAR_BOOL makes a C variable of type int visible in Lisp with a value that is either t or nil.

If you define a file-scope C variable of type Lisp_Object, you must protect it for garbage-collection by calling staticpro in syms_of_filename, like this:
staticpro (&variable);
Here is another example function, with more complicated arguments. This comes from the code in `window.c', and it demonstrates the use of macros and functions to manipulate Lisp objects.
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
  Scoordinates_in_window_p, 2, 2,
  "xSpecify coordinate pair: \nXExpression which evals to window: ",
  "Return non-nil if COORDINATES is in WINDOW.\n\
COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
...
If they are on the border between WINDOW and its right sibling,\n\
   `vertical-line' is returned.")
  (coordinates, window)
     register Lisp_Object coordinates, window;
{
  int x, y;

  CHECK_LIVE_WINDOW (window, 0);
  CHECK_CONS (coordinates, 1);
  x = XINT (Fcar (coordinates));
  y = XINT (Fcdr (coordinates));

  switch (coordinates_in_window (XWINDOW (window), &x, &y))
    {
    case 0:			/* NOT in window at all. */
      return Qnil;

    case 1:			/* In text part of window. */
      return Fcons (make_number (x), make_number (y));

    case 2:			/* In mode line of window. */
      return Qmode_line;

    case 3:			/* On right border of window.  */
      return Qvertical_line;

    default:
      abort ();
    }
}
Note that C code cannot call functions by name unless they are defined in C. The way to call a function written in Lisp is to use Ffuncall, which embodies the Lisp function funcall. Since the Lisp function funcall accepts an unlimited number of arguments, in C it takes two: the number of Lisp-level arguments, and a one-dimensional array containing their values. The first Lisp-level argument is the Lisp function to call, and the rest are the arguments to pass to it. Since Ffuncall can call the evaluator, you must protect pointers from garbage collection around the call to Ffuncall.

The C functions call0, call1, call2, and so on, provide handy ways to call a Lisp function conveniently with a fixed number of arguments. They work by calling Ffuncall.

`eval.c' is a very good file to look through for examples; `lisp.h' contains the definitions for some important macros and functions.

Object Internals

GNU Emacs Lisp manipulates many different types of data. The actual data are stored in a heap and the only access that programs have to it is through pointers. Pointers are thirty-two bits wide in most implementations. Depending on the operating system and type of machine for which you compile Emacs, twenty-eight bits are used to address the object, and the remaining four bits are used for a GC mark bit and the tag that identifies the object's type.

Because Lisp objects are represented as tagged pointers, it is always possible to determine the Lisp data type of any object. The C data type Lisp_Object can hold any Lisp object of any data type. Ordinary variables have type Lisp_Object, which means they can hold any type of Lisp value; you can determine the actual data type only at run time. The same is true for function arguments; if you want a function to accept only a certain type of argument, you must check the type explicitly using a suitable predicate (see section Type Predicates).

Buffer Internals

Buffers contain fields not directly accessible by the Lisp programmer. We describe them here, naming them by the names used in the C code. Many are accessible indirectly in Lisp programs via Lisp primitives.

name
The buffer name is a string that names the buffer. It is guaranteed to be unique. See section Buffer Names.
save_modified
This field contains the time when the buffer was last saved, as an integer. See section Buffer Modification.
modtime
This field contains the modification time of the visited file. It is set when the file is written or read. Every time the buffer is written to the file, this field is compared to the modification time of the file. See section Buffer Modification.
auto_save_modified
This field contains the time when the buffer was last auto-saved.
last_window_start
This field contains the window-start position in the buffer as of the last time the buffer was displayed in a window.
undo_list
This field points to the buffer's undo list. See section Undo.
syntax_table_v
This field contains the syntax table for the buffer. See section Syntax Tables.
downcase_table
This field contains the conversion table for converting text to lower case. See section The Case Table.
upcase_table
This field contains the conversion table for converting text to upper case. See section The Case Table.
case_canon_table
This field contains the conversion table for canonicalizing text for case-folding search. See section The Case Table.
case_eqv_table
This field contains the equivalence table for case-folding search. See section The Case Table.
display_table
This field contains the buffer's display table, or nil if it doesn't have one. See section Display Tables.
markers
This field contains the chain of all markers that currently point into the buffer. Deletion of text in the buffer, and motion of the buffer's gap, must check each of these markers and perhaps update it. See section Markers.
backed_up
This field is a flag that tells whether a backup file has been made for the visited file of this buffer.
mark
This field contains the mark for the buffer. The mark is a marker, hence it is also included on the list markers. See section The Mark.
mark_active
This field is non-nil if the buffer's mark is active.
local_var_alist
This field contains the association list describing the buffer-local variable bindings of this buffer, not including the built-in buffer-local bindings that have special slots in the buffer object. (Those slots are omitted from this table.) See section Buffer-Local Variables.
base_buffer
This field holds the buffer's base buffer (if it is an indirect buffer), or nil.
keymap
This field holds the buffer's local keymap. See section Keymaps.
overlay_center
This field holds the current overlay center position. See section Overlays.
overlays_before
This field holds a list of the overlays in this buffer that end at or before the current overlay center position. They are sorted in order of decreasing end position.
overlays_after
This field holds a list of the overlays in this buffer that end after the current overlay center position. They are sorted in order of increasing beginning position.
enable_multibyte_characters
This field holds the buffer's local value of enable-multibyte-characters---either t or nil.
Window Internals

Windows have the following accessible fields:

frame
The frame that this window is on.
mini_p
Non-nil if this window is a minibuffer window.
buffer
The buffer that the window is displaying. This may change often during the life of the window.
dedicated
Non-nil if this window is dedicated to its buffer.
pointm
This is the value of point in the current buffer when this window is selected; when it is not selected, it retains its previous value.
start
The position in the buffer that is the first character to be displayed in the window.
force_start
If this flag is non-nil, it says that the window has been scrolled explicitly by the Lisp program. This affects what the next redisplay does if point is off the screen: instead of scrolling the window to show the text around point, it moves point to a location that is on the screen.
last_modified
The modified field of the window's buffer, as of the last time a redisplay completed in this window.
last_point
The buffer's value of point, as of the last time a redisplay completed in this window.
left
This is the left-hand edge of the window, measured in columns. (The leftmost column on the screen is column 0.)
top
This is the top edge of the window, measured in lines. (The top line on the screen is line 0.)
height
The height of the window, measured in lines.
width
The width of the window, measured in columns.
next
This is the window that is the next in the chain of siblings. It is nil in a window that is the rightmost or bottommost of a group of siblings.
prev
This is the window that is the previous in the chain of siblings. It is nil in a window that is the leftmost or topmost of a group of siblings.
parent
Internally, Emacs arranges windows in a tree; each group of siblings has a parent window whose area includes all the siblings. This field points to a window's parent. Parent windows do not display buffers, and play little role in display except to shape their child windows. Emacs Lisp programs usually have no access to the parent windows; they operate on the windows at the leaves of the tree, which actually display buffers.
hscroll
This is the number of columns that the display in the window is scrolled horizontally to the left. Normally, this is 0.
use_time
This is the last time that the window was selected. The function get-lru-window uses this field.
display_table
The window's display table, or nil if none is specified for it.
update_mode_line
Non-nil means this window's mode line needs to be updated.
base_line_number
The line number of a certain position in the buffer, or nil. This is used for displaying the line number of point in the mode line.
base_line_pos
The position in the buffer for which the line number is known, or nil meaning none is known.
region_showing
If the region (or part of it) is highlighted in this window, this field holds the mark position that made one end of that region. Otherwise, this field is nil.
Process Internals

The fields of a process are:

name
A string, the name of the process.
command
A list containing the command arguments that were used to start this process.
filter
A function used to accept output from the process instead of a buffer, or nil.
sentinel
A function called whenever the process receives a signal, or nil.
buffer
The associated buffer of the process.
pid
An integer, the Unix process ID.
childp
A flag, non-nil if this is really a child process. It is nil for a network connection.
mark
A marker indicating the position of the end of the last output from this process inserted into the buffer. This is often but not always the end of the buffer.
kill_without_query
If this is non-nil, killing Emacs while this process is still running does not ask for confirmation about killing the process.
raw_status_low

raw_status_high
These two fields record 16 bits each of the process status returned by the wait system call.
status
The process status, as process-status should return it.
tick

update_tick
If these two fields are not equal, a change in the status of the process needs to be reported, either by running the sentinel or by inserting a message in the process buffer.
pty_flag
Non-nil if communication with the subprocess uses a PTY; nil if it uses a pipe.
infd
The file descriptor for input from the process.
outfd
The file descriptor for output to the process.
subtty
The file descriptor for the terminal that the subprocess is using. (On some systems, there is no need to record this, so the value is nil.)
tty_name
The name of the terminal that the subprocess is using, or nil if it is using pipes.
Standard Errors

Here is the complete list of the error symbols in standard Emacs, grouped by concept. The list includes each symbol's message (on the error-message property of the symbol) and a cross reference to a description of how the error can occur.

Each error symbol has an error-conditions property that is a list of symbols. Normally this list includes the error symbol itself and the symbol error. Occasionally it includes additional symbols, which are intermediate classifications, narrower than error but broader than a single error symbol. For example, all the errors in accessing files have the condition file-error. If we do not say here that a certain error symbol has additional error conditions, that means it has none.

As a special exception, the error symbol quit does not have the condition error, because quitting is not considered an error.

See section Errors, for an explanation of how errors are generated and handled.

symbol
string; reference.
error
"error"
See section Errors.
quit
"Quit"
See section Quitting.
args-out-of-range
"Args out of range"
See section Sequences, Arrays, and Vectors.
arith-error
"Arithmetic error"
See / and % in section Numbers.
beginning-of-buffer
"Beginning of buffer"
See section Motion.
buffer-read-only
"Buffer is read-only"
See section Read-Only Buffers.
cyclic-function-indirection
"Symbol's chain of function indirections\
contains a loop"
See section Symbol Function Indirection.
end-of-buffer
"End of buffer"
See section Motion.
end-of-file
"End of file during parsing"
Note that this is not a file-error because it pertains to the Lisp reader, not to file I/O. See section Input Functions.
file-already-exists
This is a file-error.
See section Writing to Files.
file-date-error
This is a subcategory of file-error. It occurs when copy-file tries and fails to set the last-modification time of the output file. See section Changing File Names and Attributes.
file-error
This error and its subcategories do not have error-strings, because the error message is constructed from the data items alone when the error condition file-error is present.
See section Files.
file-locked
This is a file-error.
See section File Locks.
file-supersession
This is a file-error.
See section Comparison of Modification Time.
invalid-function
"Invalid function"
See section Classification of List Forms.
invalid-read-syntax
"Invalid read syntax"
See section Input Functions.
invalid-regexp
"Invalid regexp"
See section Regular Expressions.
mark-inactive
"Mark inactive"
See section The Mark.
no-catch
"No catch for tag"
See section Explicit Nonlocal Exits: catch and throw.
scan-error
"Scan error"
This happens when certain syntax-parsing functions find invalid syntax or mismatched parentheses.
See section Moving over Balanced Expressions, and section Parsing Balanced Expressions.
search-failed
"Search failed"
See section Searching and Matching.
setting-constant
"Attempt to set a constant symbol"
The values of the symbols nil and t, and any symbols that start with `:', may not be changed.
See section Variables That Never Change.
undefined-color
"Undefined color"
See section Color Names.
void-function
"Symbol's function definition is void"
See section Accessing Function Cell Contents.
void-variable
"Symbol's value as variable is void"
See section Accessing Variable Values.
wrong-number-of-arguments
"Wrong number of arguments"
See section Classification of List Forms.
wrong-type-argument
"Wrong type argument"
See section Type Predicates.
These kinds of error, which are classified as special cases of arith-error, can occur on certain systems for invalid use of mathematical functions.

domain-error
"Arithmetic domain error"
See section Standard Mathematical Functions.
overflow-error
"Arithmetic overflow error"
See section Standard Mathematical Functions.
range-error
"Arithmetic range error"
See section Standard Mathematical Functions.
singularity-error
"Arithmetic singularity error"
See section Standard Mathematical Functions.
underflow-error
"Arithmetic underflow error"
See section Standard Mathematical Functions.
Buffer-Local Variables

The table below lists the general-purpose Emacs variables that automatically become buffer-local in each buffer. Most become buffer-local only when set; a few of them are always local in every buffer. Many Lisp packages define such variables for their internal use, but we don't try to list them all here.

abbrev-mode
See section Abbrevs And Abbrev Expansion.
auto-fill-function
See section Auto Filling.
buffer-auto-save-file-name
See section Auto-Saving.
buffer-backed-up
See section Backup Files.
buffer-display-count
See section Displaying Buffers in Windows.
buffer-display-table
See section Display Tables.
buffer-file-format
See section File Format Conversion.
buffer-file-name
See section Buffer File Name.
buffer-file-number
See section Buffer File Name.
buffer-file-truename
See section Buffer File Name.
buffer-file-type
See section MS-DOS File Types.
buffer-invisibility-spec
See section Invisible Text.
buffer-offer-save
See section Saving Buffers.
buffer-read-only
See section Read-Only Buffers.
buffer-saved-size
See section Point.
buffer-undo-list
See section Undo.
cache-long-line-scans
See section Motion by Text Lines.
case-fold-search
See section Searching and Case.
ctl-arrow
See section Usual Display Conventions.
comment-column
See section `Comments' in The GNU Emacs Manual.
default-directory
See section Operating System Environment.
defun-prompt-regexp
See section Moving over Balanced Expressions.
enable-multibyte-characters
section Non-ASCII Characters.
fill-column
See section Auto Filling.
goal-column
See section `Moving Point' in The GNU Emacs Manual.
left-margin
See section Indentation.
local-abbrev-table
See section Abbrevs And Abbrev Expansion.
local-write-file-hooks
See section Saving Buffers.
major-mode
See section Getting Help about a Major Mode.
mark-active
See section The Mark.
mark-ring
See section The Mark.
minor-modes
See section Minor Modes.
mode-line-buffer-identification
See section Variables Used in the Mode Line.
mode-line-format
See section The Data Structure of the Mode Line.
mode-line-modified
See section Variables Used in the Mode Line.
mode-line-process
See section Variables Used in the Mode Line.
mode-name
See section Variables Used in the Mode Line.
overwrite-mode
See section Inserting Text.
paragraph-separate
See section Standard Regular Expressions Used in Editing.
paragraph-start
See section Standard Regular Expressions Used in Editing.
point-before-scroll
Ued for communication between mouse commands and scroll-bar commands..
require-final-newline
See section Inserting Text.
selective-display
See section Selective Display.
selective-display-ellipses
See section Selective Display.
tab-width
See section Usual Display Conventions.
truncate-lines
See section Truncation.
vc-mode
See section Variables Used in the Mode Line.
Standard Keymaps

The following symbols are used as the names for various keymaps. Some of these exist when Emacs is first started, others are loaded only when their respective mode is used. This is not an exhaustive list.

Almost all of these maps are used as local maps. Indeed, of the modes that presently exist, only Vip mode and Terminal mode ever change the global keymap.

Buffer-menu-mode-map
A full keymap used by Buffer Menu mode.
c-mode-map
A sparse keymap used by C mode.
command-history-map
A full keymap used by Command History mode.
ctl-x-4-map
A sparse keymap for subcommands of the prefix C-x 4.
ctl-x-5-map
A sparse keymap for subcommands of the prefix C-x 5.
ctl-x-map
A full keymap for C-x commands.
debugger-mode-map
A full keymap used by Debugger mode.
dired-mode-map
A full keymap for dired-mode buffers.
edit-abbrevs-map
A sparse keymap used in edit-abbrevs.
edit-tab-stops-map
A sparse keymap used in edit-tab-stops.
electric-buffer-menu-mode-map
A full keymap used by Electric Buffer Menu mode.
electric-history-map
A full keymap used by Electric Command History mode.
emacs-lisp-mode-map
A sparse keymap used by Emacs Lisp mode.
facemenu-menu
The keymap that displays the Text Properties menu.
facemenu-background-menu
The keymap that displays the Background Color submenu of the Text Properties menu.
facemenu-face-menu
The keymap that displays the Face submenu of the Text Properties menu.
facemenu-foreground-menu
The keymap that displays the Foreground Color submenu of the Text Properties menu.
facemenu-indentation-menu
The keymap that displays the Indentation submenu of the Text Properties menu.
facemenu-justification-menu
The keymap that displays the Justification submenu of the Text Properties menu.
facemenu-special-menu
The keymap that displays the Special Props submenu of the Text Properties menu.
function-key-map
The keymap for translating keypad and function keys.
If there are none, then it contains an empty sparse keymap. See section Translating Input Events.
fundamental-mode-map
The local keymap for Fundamental mode.
It is empty and should not be changed.
Helper-help-map
A full keymap used by the help utility package.
It has the same keymap in its value cell and in its function cell.
Info-edit-map
A sparse keymap used by the e command of Info.
Info-mode-map
A sparse keymap containing Info commands.
isearch-mode-map
A keymap that defines the characters you can type within incremental search.
key-translation-map
A keymap for translating keys. This one overrides ordinary key bindings, unlike function-key-map. See section Translating Input Events.
lisp-interaction-mode-map
A sparse keymap used by Lisp mode.
lisp-mode-map
A sparse keymap used by Lisp mode.
menu-bar-edit-menu
The keymap which displays the Edit menu in the menu bar.
menu-bar-files-menu
The keymap which displays the Files menu in the menu bar.
menu-bar-help-menu
The keymap which displays the Help menu in the menu bar.
menu-bar-mule-menu
The keymap which displays the Mule menu in the menu bar.
menu-bar-search-menu
The keymap which displays the Search menu in the menu bar.
menu-bar-tools-menu
The keymap which displays the Tools menu in the menu bar.
mode-specific-map
The keymap for characters following C-c. Note, this is in the global map. This map is not actually mode specific: its name was chosen to be informative for the user in C-h b (display-bindings), where it describes the main use of the C-c prefix key.
occur-mode-map
A local keymap used by Occur mode.
query-replace-map
A local keymap used for responses in query-replace and related commands; also for y-or-n-p and map-y-or-n-p. The functions that use this map do not support prefix keys; they look up one event at a time.
text-mode-map
A sparse keymap used by Text mode.
view-mode-map
A full keymap used by View mode.
Standard Hooks

The following is a list of hook variables that let you provide functions to be called from within Emacs on suitable occasions.

Most of these variables have names ending with `-hook'. They are normal hooks, run by means of run-hooks. The value of such a hook is a list of functions; the functions are called with no arguments and their values are completely ignored. The recommended way to put a new function on such a hook is to call add-hook. See section Hooks, for more information about using hooks.

The variables whose names end in `-hooks' or `-functions' are usually abnormal hooks; their values are lists of functions, but these functions are called in a special way (they are passed arguments, or their values are used). A few of these variables are actually normal hooks which were named before we established the convention that normal hooks' names should end in `-hook'.

The variables whose names end in `-function' have single functions as their values. (In older Emacs versions, some of these variables had names ending in `-hook' even though they were not normal hooks; however, we have renamed all of those.)

activate-mark-hook

after-change-function

after-change-functions

after-init-hook

after-insert-file-functions

after-make-frame-hook

after-revert-hook

after-save-hook

auto-fill-function

auto-save-hook

before-change-function

before-change-functions

before-init-hook

before-make-frame-hook

before-revert-hook

blink-paren-function

buffer-access-fontify-functions

c-mode-hook

calendar-load-hook

change-major-mode-hook

command-history-hook

command-line-functions

comment-indent-function

deactivate-mark-hook

diary-display-hook

diary-hook

dired-mode-hook

disabled-command-hook

echo-area-clear-hook

edit-picture-hook

electric-buffer-menu-mode-hook

electric-command-history-hook

electric-help-mode-hook

emacs-lisp-mode-hook

find-file-hooks

find-file-not-found-hooks

first-change-hook

fortran-comment-hook

fortran-mode-hook

ftp-setup-write-file-hooks

ftp-write-file-hook

indent-mim-hook

initial-calendar-window-hook

kill-buffer-hook

kill-buffer-query-functions

kill-emacs-hook

kill-emacs-query-functions

LaTeX-mode-hook

ledit-mode-hook

lisp-indent-function

lisp-interaction-mode-hook

lisp-mode-hook

list-diary-entries-hook

local-write-file-hooks

m2-mode-hook

mail-mode-hook

mail-setup-hook

mark-diary-entries-hook

medit-mode-hook

menu-bar-update-hook

minibuffer-setup-hook

minibuffer-exit-hook

news-mode-hook

news-reply-mode-hook

news-setup-hook

nongregorian-diary-listing-hook

nongregorian-diary-marking-hook

nroff-mode-hook

outline-mode-hook

plain-TeX-mode-hook

post-command-hook

pre-abbrev-expand-hook

pre-command-hook

print-diary-entries-hook

prolog-mode-hook

protect-innocence-hook

redisplay-end-trigger-functions

rmail-edit-mode-hook

rmail-mode-hook

rmail-summary-mode-hook

scheme-indent-hook

scheme-mode-hook

scribe-mode-hook

shell-mode-hook

shell-set-directory-error-hook

suspend-hook

suspend-resume-hook

temp-buffer-show-function

term-setup-hook

terminal-mode-hook

terminal-mode-break-hook

TeX-mode-hook

text-mode-hook

today-visible-calendar-hook

today-invisible-calendar-hook

vi-mode-hook

view-hook

window-configuration-change-hook

window-scroll-functions

window-setup-hook

window-size-change-functions

write-contents-hooks

write-file-hooks

write-region-annotate-functions

New Symbols Since the Previous Edition

Jump to: a - b - c - d - e - f - h - i - k - l - m - n - o - p - r - s - t - w

a

access-file
add-to-invisibility-spec
after-make-frame-hook
assoc-default
assoc-ignore-case
assoc-ignore-representation
b

backward-delete-char-untabify-method
before-make-frame-hook
bool-vector-p
buffer-display-time
buffer-file-coding-system
buffer-name-history
c

caar
cadr
cdar
cddr
char-bytes
char-charset
char-table-extra-slot
char-table-p
char-table-parent
char-table-range
char-table-subtype
char-width
charset-dimension
charset-list
charsetp
check-coding-system
checkdoc-minor-mode
coding-system-change-eol-conversion
coding-system-change-text-conversion
coding-system-for-read
coding-system-for-write
coding-system-get
coding-system-list
coding-system-p
combine-after-change-calls
compare-strings
condition
current-input-method
current-message
d

decode-coding-region
decode-coding-string
default-enable-multibyte-characters
default-input-method
default-process-coding-system
defcustom
defface
defgroup
delete-old-versions
detect-coding-region
detect-coding-string
display-table-slot
e

easy-mmode-define-minor-mode
echo-area-clear-hook
enable-multibyte-characters
encode-coding-region
encode-coding-string
f

face-bold-p
face-documentation
face-italic-p
file-coding-system-alist
fill-nobreak-predicate
find-charset-region
find-charset-string
find-coding-systems-for-charsets
find-coding-systems-region
find-coding-systems-string
find-operation-coding-system
focus-follows-mouse
frame-background-mode
frame-update-face-colors
functionp
h

help-event-list
i

inhibit-eol-conversion
input-method-alist
insert-file-contents-literally
k

keyboard-coding-system
keyword-symbols-constant-flag
l

last-coding-system-used
last-prefix-arg
loadhist-special-hooks
m

make-bool-vector
make-char
make-char-table
map-char-table
marker-insertion-type
menu-bar-mule-menu
minor-mode-overriding-map-alist
mode-line-frame-identification
mode-line-mule-info
multibyte-string-p
n

network-coding-system-alist
next-char-property-change
nonascii-insert-offset
nonascii-translation-table
num-nonmacro-input-events
o

overlays-in
p

parse-sexp-lookup-properties
previous-char-property-change
print-escape-multibyte
print-escape-nonascii
process-coding-system
process-coding-system-alist
process-contact
r

read-coding-system
read-input-method-name
read-non-nil-coding-system
read-passwd
real-last-command
redisplay-end-trigger-functions
regexp-opt
regexp-opt-depth
remove-from-invisibility-spec
ring-bell-function
s

safe-length
save-buffer-coding-system
save-current-buffer
scroll-conservatively
scroll-margin
scroll-preserve-screen-position
select-safe-coding-system
selection-coding-system
set-buffer-multibyte
set-char-table-default
set-char-table-extra-slot
set-char-table-parent
set-char-table-range
set-display-table-slot
set-face-bold-p
set-face-italic-p
set-input-method
set-keyboard-coding-system
set-marker-insertion-type
set-process-coding-system
set-terminal-coding-system
set-window-redisplay-end-trigger
shell-command-to-string
split-char
split-string
store-substring
string
string-as-multibyte
string-as-unibyte
string-make-multibyte
string-make-unibyte
string-width
t

terminal-coding-system
truncate-string-to-width
tty-erase-char
w

when
window-configuration-change-hook
window-redisplay-end-trigger
with-current-buffer
with-output-to-string
with-temp-buffer
with-temp-file

Footnotes

(1)

This usage of "key" is not related to the term "key sequence"; it means a value used to look up an item in a table. In this case, the table is the alist, and the alist associations are the items.
(2)

This definition of "environment" is specifically not intended to include all the data that can affect the result of a program.
(3)

Button-down is the conservative antithesis of drag.
(4)

They are not exactly equal because right includes the vertical separator line or scroll bar, while (window-width) does not.

This document was generated on 7 November 1998 using the texi2html translator version 1.52.


Programming in Emacs Lisp

Node:Top, Next:Preface

An Introduction to Programming in Emacs Lisp

This is an introduction to Programming in Emacs Lisp, for people who are not programmers.

This master menu first lists each chapter and index; then it lists every node in every chapter.

  • Preface: What to look for.
  • List Processing: What is Lisp?
  • Practicing Evaluation: Running several programs.
  • Writing Defuns: How to write function definitions.
  • Buffer Walk Through: Exploring a few buffer-related functions.
  • More Complex: A few, even more complex functions.
  • Narrowing & Widening: Restricting your and Emacs attention to a region.
  • car cdr & cons: Fundamental functions in Lisp.
  • Cutting & Storing Text: Removing text and saving it.
  • List Implementation: How lists are implemented in the computer.
  • Yanking: Pasting stored text.
  • Loops & Recursion: How to repeat a process.
  • Regexp Search: Regular expression searches.
  • Counting Words: A review of repetition and regexps.
  • Words in a defun: Counting words in a defun.
  • Readying a Graph: A prototype graph printing function.
  • Emacs Initialization: How to write a .emacs file.
  • Debugging: How to run the Emacs Lisp debuggers.
  • Conclusion: Now you have the basics.
  • the-the: An appendix: how to find reduplicated words.
  • Kill Ring: An appendix: how the kill ring works.
  • Full Graph: How to create a graph with labelled axes.
  • GNU Free Documentation License:
  • Index:
  • About the Author:

    --- The Detailed Node Listing ---

    Preface

  • Why: Why learn Emacs Lisp?
  • On Reading this Text: Read, gain familiarity, pick up habits....
  • Who You Are: For whom this is written.
  • Lisp History:
  • Note for Novices: You can read this as a novice.
  • Thank You:

    List Processing

  • Lisp Lists: What are lists?
  • Run a Program: Any list in Lisp is a program ready to run.
  • Making Errors: Generating an error message.
  • Names & Definitions: Names of symbols and function definitions.
  • Lisp Interpreter: What the Lisp interpreter does.
  • Evaluation: Running a program.
  • Variables: Returning a value from a variable.
  • Arguments: Passing information to a function.
  • set & setq: Setting the value of a variable.
  • Summary: The major points.
  • Error Message Exercises:

    Lisp Lists

  • Numbers Lists: List have numbers, other lists, in them.
  • Lisp Atoms: Elemental entities.
  • Whitespace in Lists: Formating lists to be readable.
  • Typing Lists: How GNU Emacs helps you type lists.

    The Lisp Interpreter

  • Complications: Variables, Special forms, Lists within.
  • Byte Compiling: Specially processing code for speed.

    Evaluation

  • Evaluating Inner Lists: Lists within lists...

    Variables

  • fill-column Example:
  • Void Function: The error message for a symbol without a function.
  • Void Variable: The error message for a symbol without a value.

    Arguments

  • Data types: Types of data passed to a function.
  • Args as Variable or List: An argument can be the value of a variable or list.
  • Variable Number of Arguments: Some functions may take a variable number of arguments.
  • Wrong Type of Argument: Passing an argument of the wrong type to a function.
  • message: A useful function for sending messages.

    Setting the Value of a Variable

  • Using set: Setting values.
  • Using setq: Setting a quoted value.
  • Counting: Using setq to count.

    Practicing Evaluation

  • How to Evaluate: Typing editing commands or C-x C-e causes evaluation.
  • Buffer Names: Buffers and files are different.
  • Getting Buffers: Getting a buffer itself, not merely its name.
  • Switching Buffers: How to change to another buffer.
  • Buffer Size & Locations: Where point is located and the size of the buffer.
  • Evaluation Exercise:

    How To Write Function Definitions

  • Primitive Functions:
  • defun: The defun special form.
  • Install: Install a function definition.
  • Interactive: Making a function interactive.
  • Interactive Options: Different options for interactive.
  • Permanent Installation: Installing code permanently.
  • let: Creating and initializing local variables.
  • if: What if?
  • else: If--then--else expressions.
  • Truth & Falsehood: What Lisp considers false and true.
  • save-excursion: Keeping track of point, mark, and buffer.
  • Review:
  • defun Exercises:

    Install a Function Definition

  • Effect of installation:
  • Change a defun: How to change a function definition.

    Make a Function Interactive

  • Interactive multiply-by-seven: An overview.
  • multiply-by-seven in detail: The interactive version.

    let

  • Prevent confusion:
  • Parts of let Expression:
  • Sample let Expression:
  • Uninitialized let Variables:

    The if Special Form

  • if in more detail:
  • type-of-animal in detail: An example of an if expression.

    Truth and Falsehood in Emacs Lisp

  • nil explained: nil has two meanings.

    save-excursion

  • Point and mark: A review of various locations.
  • Template for save-excursion:

    A Few Buffer--Related Functions

  • Finding More: How to find more information.
  • simplified-beginning-of-buffer: Shows goto-char, point-min, and push-mark.
  • mark-whole-buffer: Almost the same as beginning-of-buffer.
  • append-to-buffer: Uses save-excursion and insert-buffer-substring.
  • Buffer Related Review: Review.
  • Buffer Exercises:

    The Definition of mark-whole-buffer

  • mark-whole-buffer overview:
  • Body of mark-whole-buffer: Only three lines of code.

    The Definition of append-to-buffer

  • append-to-buffer overview:
  • append interactive: A two part interactive expression.
  • append-to-buffer body: Incorporates a let expression.
  • append save-excursion: How the save-excursion works.

    A Few More Complex Functions

  • copy-to-buffer: With set-buffer, get-buffer-create.
  • insert-buffer: Read-only, and with or.
  • beginning-of-buffer: Shows goto-char, point-min, and push-mark.
  • Second Buffer Related Review:
  • optional Exercise:

    The Definition of insert-buffer

  • insert-buffer code:
  • insert-buffer interactive: When you can read, but not write.
  • insert-buffer body: The body has an or and a let.
  • if & or: Using an if instead of an or.
  • Insert or: How the or expression works.
  • Insert let: Two save-excursion expressions.

    The Interactive Expression in insert-buffer

  • Read-only buffer: When a buffer cannot be modified.
  • b for interactive: An existing buffer or else its name.

    Complete Definition of beginning-of-buffer

  • Optional Arguments:
  • beginning-of-buffer opt arg: Example with optional argument.
  • beginning-of-buffer complete:

    beginning-of-buffer with an Argument

  • Disentangle beginning-of-buffer:
  • Large buffer case:
  • Small buffer case:

    Narrowing and Widening

  • Narrowing advantages: The advantages of narrowing
  • save-restriction: The save-restriction special form.
  • what-line: The number of the line that point is on.
  • narrow Exercise:

    car, cdr, cons: Fundamental Functions

  • Strange Names: An historical aside: why the strange names?
  • car & cdr: Functions for extracting part of a list.
  • cons: Constructing a list.
  • nthcdr: Calling cdr repeatedly.
  • nth:
  • setcar: Changing the first element of a list.
  • setcdr: Changing the rest of a list.
  • cons Exercise:

    cons

  • Build a list:
  • length: How to find the length of a list.

    Cutting and Storing Text

  • Storing Text: Text is stored in a list.
  • zap-to-char: Cutting out text up to a character.
  • kill-region: Cutting text out of a region.
  • Digression into C: Minor note on C programming language macros.
  • defvar: How to give a variable an initial value.
  • copy-region-as-kill: A definition for copying text.
  • cons & search-fwd Review:
  • search Exercises:

    zap-to-char

  • Complete zap-to-char: The complete implementation.
  • zap-to-char interactive: A three part interactive expression.
  • zap-to-char body: A short overview.
  • search-forward: How to search for a string.
  • progn: The progn special form.
  • Summing up zap-to-char: Using point and search-forward.

    kill-region

  • Complete kill-region: The function definition.
  • condition-case: Dealing with a problem.
  • delete-and-extract-region: Doing the work.

    Initializing a Variable with defvar

  • See variable current value:
  • defvar and asterisk: An old-time convention.

    copy-region-as-kill

  • Complete copy-region-as-kill: The complete function definition.
  • copy-region-as-kill body: The body of copy-region-as-kill.

    The Body of copy-region-as-kill

  • last-command & this-command:
  • kill-append function:
  • kill-new function:

    How Lists are Implemented

  • Lists diagrammed:
  • Symbols as Chest: Exploring a powerful metaphor.
  • List Exercise:

    Yanking Text Back

  • Kill Ring Overview: The kill ring is a list.
  • kill-ring-yank-pointer: The kill-ring-yank-pointer variable.
  • yank nthcdr Exercises:

    Loops and Recursion

  • while: Causing a stretch of code to repeat.
  • dolist dotimes:
  • Recursion: Causing a function to call itself.
  • Looping exercise:

    while

  • Looping with while: Repeat so long as test returns true.
  • Loop Example: A while loop that uses a list.
  • print-elements-of-list: Uses while, car, cdr.
  • Incrementing Loop: A loop with an incrementing counter.
  • Decrementing Loop: A loop with a decrementing counter.

    A Loop with an Incrementing Counter

  • Incrementing Example: Counting pebbles in a triangle.
  • Inc Example parts: The parts of the function definition.
  • Inc Example altogether: Putting the function definition together.

    Loop with a Decrementing Counter

  • Decrementing Example: More pebbles on the beach.
  • Dec Example parts: The parts of the function definition.
  • Dec Example altogether: Putting the function definition together.

    Save your time: dolist and dotimes

  • dolist:
  • dotimes:

    Recursion

  • Building Robots: Same model, different serial number ...
  • Recursive Definition Parts: Walk until you stop ...
  • Recursion with list: Using a list as the test whether to recurse.
  • Recursive triangle function:
  • Recursion with cond:
  • Recursive Patterns: Often used templates.
  • No Deferment: Don't store up work ...
  • No deferment solution:

    Recursion in Place of a Counter

  • Recursive Example arg of 1 or 2:
  • Recursive Example arg of 3 or 4:

    Recursive Patterns

  • Every:
  • Accumulate:
  • Keep:

    Regular Expression Searches

  • sentence-end: The regular expression for sentence-end.
  • re-search-forward: Very similar to search-forward.
  • forward-sentence: A straightforward example of regexp search.
  • forward-paragraph: A somewhat complex example.
  • etags: How to create your own TAGS table.
  • Regexp Review:
  • re-search Exercises:

    forward-sentence

  • Complete forward-sentence:
  • fwd-sentence while loops: Two while loops.
  • fwd-sentence re-search: A regular expression search.

    forward-paragraph: a Goldmine of Functions

  • forward-paragraph in brief: Key parts of the function definition.
  • fwd-para let: The let* expression.
  • fwd-para while: The forward motion while loop.
  • fwd-para between paragraphs: Movement between paragraphs.
  • fwd-para within paragraph: Movement within paragraphs.
  • fwd-para no fill prefix: When there is no fill prefix.
  • fwd-para with fill prefix: When there is a fill prefix.
  • fwd-para summary: Summary of forward-paragraph code.

    Counting: Repetition and Regexps

  • Why Count Words:
  • count-words-region: Use a regexp, but find a problem.
  • recursive-count-words: Start with case of no words in region.
  • Counting Exercise:

    The count-words-region Function

  • Design count-words-region: The definition using a while loop.
  • Whitespace Bug: The Whitespace Bug in count-words-region.

    Counting Words in a defun

  • Divide and Conquer:
  • Words and Symbols: What to count?
  • Syntax: What constitutes a word or symbol?
  • count-words-in-defun: Very like count-words.
  • Several defuns: Counting several defuns in a file.
  • Find a File: Do you want to look at a file?
  • lengths-list-file: A list of the lengths of many definitions.
  • Several files: Counting in definitions in different files.
  • Several files recursively: Recursively counting in different files.
  • Prepare the data: Prepare the data for display in a graph.

    Count Words in defuns in Different Files

  • lengths-list-many-files: Return a list of the lengths of defuns.
  • append: Attach one list to another.

    Prepare the Data for Display in a Graph

  • Sorting: Sorting lists.
  • Files List: Making a list of files.
  • Counting function definitions:

    Readying a Graph

  • Columns of a graph:
  • graph-body-print: How to print the body of a graph.
  • recursive-graph-body-print:
  • Printed Axes:
  • Line Graph Exercise:

    Your .emacs File

  • Default Configuration:
  • Site-wide Init: You can write site-wide init files.
  • defcustom: Emacs will write code for you.
  • Beginning a .emacs File: How to write a .emacs file.
  • Text and Auto-fill: Automatically wrap lines.
  • Mail Aliases: Use abbreviations for email addresses.
  • Indent Tabs Mode: Don't use tabs with TeX
  • Keybindings: Create some personal keybindings.
  • Keymaps: More about key binding.
  • Loading Files: Load (i.e., evaluate) files automatically.
  • Autoload: Make functions available.
  • Simple Extension: Define a function; bind it to a key.
  • X11 Colors: Colors in version 19 in X.
  • Miscellaneous:
  • Mode Line: How to customize your mode line.

    Debugging

  • debug: How to use the built-in debugger.
  • debug-on-entry: Start debugging when you call a function.
  • debug-on-quit: Start debugging when you quit with C-g.
  • edebug: How to use Edebug, a source level debugger.
  • Debugging Exercises:

    Handling the Kill Ring

  • rotate-yank-pointer: Move a pointer along a list and around.
  • yank: Paste a copy of a clipped element.
  • yank-pop: Insert first element pointed to.

    The rotate-yank-pointer Function

  • Understanding rotate-yk-ptr:
  • rotate-yk-ptr body: The body of rotate-yank-pointer.

    The Body of rotate-yank-pointer

  • Digression concerning error: How to mislead humans, but not computers.
  • rotate-yk-ptr else-part: The else-part of the if expression.
  • Remainder Function: The remainder, %, function.
  • rotate-yk-ptr remainder: Using % in rotate-yank-pointer.
  • kill-rng-yk-ptr last elt: Pointing to the last element.

    yank

  • rotate-yk-ptr arg: Pass the argument to rotate-yank-pointer.
  • rotate-yk-ptr negative arg: Pass a negative argument.

    A Graph with Labelled Axes

  • Labelled Example:
  • print-graph Varlist: let expression in print-graph.
  • print-Y-axis: Print a label for the vertical axis.
  • print-X-axis: Print a horizontal label.
  • Print Whole Graph: The function to print a complete graph.

    The print-Y-axis Function

  • Height of label: What height for the Y axis?
  • Compute a Remainder: How to compute the remainder of a division.
  • Y Axis Element: Construct a line for the Y axis.
  • Y-axis-column: Generate a list of Y axis labels.
  • print-Y-axis Penultimate: A not quite final version.

    The print-X-axis Function

  • Similarities differences: Much like print-Y-axis, but not exactly.
  • X Axis Tic Marks: Create tic marks for the horizontal axis.

    Printing the Whole Graph

  • The final version: A few changes.
  • Test print-graph: Run a short test.
  • Graphing words in defuns: Executing the final code.
  • lambda: How to write an anonymous function.
  • mapcar: Apply a function to elements of a list.
  • Another Bug: Yet another bug ... most insidious.
  • Final printed graph: The graph itself!

Node:Preface, Next:List Processing, Previous:Top, Up:Top

Preface

Most of the GNU Emacs integrated environment is written in the programming language called Emacs Lisp. The code written in this programming language is the software--the sets of instructions--that tell the computer what to do when you give it commands. Emacs is designed so that you can write new code in Emacs Lisp and easily install it as an extension to the editor.

(GNU Emacs is sometimes called an "extensible editor", but it does much more than provide editing capabilities. It is better to refer to Emacs as an "extensible computing environment". However, that phrase is quite a mouthful. It is easier to refer to Emacs simply as an editor. Moreover, everything you do in Emacs--find the Mayan date and phases of the moon, simplify polynomials, debug code, manage files, read letters, write books--all these activities are kinds of editing in the most general sense of the word.)

  • Why: Why learn Emacs Lisp?
  • On Reading this Text: Read, gain familiarity, pick up habits....
  • Who You Are: For whom this is written.
  • Lisp History:
  • Note for Novices: You can read this as a novice.
  • Thank You:

Node:Why, Next:On Reading this Text, Previous:Preface, Up:Preface

Why Study Emacs Lisp?

Although Emacs Lisp is usually thought of in association only with Emacs, it is a full computer programming language. You can use Emacs Lisp as you would any other programming language.

Perhaps you want to understand programming; perhaps you want to extend Emacs; or perhaps you want to become a programmer. This introduction to Emacs Lisp is designed to get you started: to guide you in learning the fundamentals of programming, and more importantly, to show you how you can teach yourself to go further.

Node:On Reading this Text, Next:Who You Are, Previous:Why, Up:Preface

On Reading this Text

All through this document, you will see little sample programs you can run inside of Emacs. If you read this document in Info inside of GNU Emacs, you can run the programs as they appear. (This is easy to do and is explained when the examples are presented.) Alternatively, you can read this introduction as a printed book while sitting beside a computer running Emacs. (This is what I like to do; I like printed books.) If you don't have a running Emacs beside you, you can still read this book, but in this case, it is best to treat it as a novel or as a travel guide to a country not yet visited: interesting, but not the same as being there.

Much of this introduction is dedicated to walk-throughs or guided tours of code used in GNU Emacs. These tours are designed for two purposes: first, to give you familiarity with real, working code (code you use every day); and, second, to give you familiarity with the way Emacs works. It is interesting to see how a working environment is implemented. Also, I hope that you will pick up the habit of browsing through source code. You can learn from it and mine it for ideas. Having GNU Emacs is like having a dragon's cave of treasures.

In addition to learning about Emacs as an editor and Emacs Lisp as a programming language, the examples and guided tours will give you an opportunity to get acquainted with Emacs as a Lisp programming environment. GNU Emacs supports programming and provides tools that you will want to become comfortable using, such as M-. (the key which invokes the find-tag command). You will also learn about buffers and other objects that are part of the environment. Learning about these features of Emacs is like learning new routes around your home town.

Finally, I hope to convey some of the skills for using Emacs to learn aspects of programming that you don't know. You can often use Emacs to help you understand what puzzles you or to find out how to do something new. This self-reliance is not only a pleasure, but an advantage.

Node:Who You Are, Next:Lisp History, Previous:On Reading this Text, Up:Preface

For Whom This is Written

This text is written as an elementary introduction for people who are not programmers. If you are a programmer, you may not be satisfied with this primer. The reason is that you may have become expert at reading reference manuals and be put off by the way this text is organized.

An expert programmer who reviewed this text said to me:

I prefer to learn from reference manuals. I "dive into" each paragraph, and "come up for air" between paragraphs.

When I get to the end of a paragraph, I assume that that subject is done, finished, that I know everything I need (with the possible exception of the case when the next paragraph starts talking about it in more detail). I expect that a well written reference manual will not have a lot of redundancy, and that it will have excellent pointers to the (one) place where the information I want is.

This introduction is not written for this person!

Firstly, I try to say everything at least three times: first, to introduce it; second, to show it in context; and third, to show it in a different context, or to review it.

Secondly, I hardly ever put all the information about a subject in one place, much less in one paragraph. To my way of thinking, that imposes too heavy a burden on the reader. Instead I try to explain only what you need to know at the time. (Sometimes I include a little extra information so you won't be surprised later when the additional information is formally introduced.)

When you read this text, you are not expected to learn everything the first time. Frequently, you need only make, as it were, a `nodding acquaintance' with some of the items mentioned. My hope is that I have structured the text and given you enough hints that you will be alert to what is important, and concentrate on it.

You will need to "dive into" some paragraphs; there is no other way to read them. But I have tried to keep down the number of such paragraphs. This book is intended as an approachable hill, rather than as a daunting mountain.

This introduction to Programming in Emacs Lisp has a companion document, Top. The reference manual has more detail than this introduction. In the reference manual, all the information about one topic is concentrated in one place. You should turn to it if you are like the programmer quoted above. And, of course, after you have read this Introduction, you will find the Reference Manual useful when you are writing your own programs.

Node:Lisp History, Next:Note for Novices, Previous:Who You Are, Up:Preface

Lisp History

Lisp was first developed in the late 1950s at the Massachusetts Institute of Technology for research in artificial intelligence. The great power of the Lisp language makes it superior for other purposes as well, such as writing editor commands and integrated environments.

GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT in the 1960s. It is somewhat inspired by Common Lisp, which became a standard in the 1980s. However, Emacs Lisp is much simpler than Common Lisp. (The standard Emacs distribution contains an optional extensions file, cl.el, that adds many Common Lisp features to Emacs Lisp.)

Node:Note for Novices, Next:Thank You, Previous:Lisp History, Up:Preface

A Note for Novices

If you don't know GNU Emacs, you can still read this document profitably. However, I recommend you learn Emacs, if only to learn to move around your computer screen. You can teach yourself how to use Emacs with the on-line tutorial. To use it, type C-h t. (This means you press and release the <CTRL> key and the h at the same time, and then press and release t.)

Also, I often refer to one of Emacs' standard commands by listing the keys which you press to invoke the command and then giving the name of the command in parentheses, like this: M-C-\ (indent-region). What this means is that the indent-region command is customarily invoked by typing M-C-\. (You can, if you wish, change the keys that are typed to invoke the command; this is called rebinding. See Keymaps.) The abbreviation M-C-\ means that you type your <META> key, <CTRL> key and <\> key all at the same time. (On many modern keyboards the <META> key is labelled <ALT>.) Sometimes a combination like this is called a keychord, since it is similar to the way you play a chord on a piano. If your keyboard does not have a <META> key, the <ESC> key prefix is used in place of it. In this case, M-C-\ means that you press and release your <ESC> key and then type the <CTRL> key and the <\> key at the same time. But usually M-C-\ means press the <CTRL> key along with the key that is labelled <ALT> and, at the same time, press the <\> key.

In addition to typing a lone keychord, you can prefix what you type with C-u, which is called the `universal argument'. The C-u keychord passes an argument to the subsequent command. Thus, to indent a region of plain text by 6 spaces, mark the region, and then type C-u 6 M-C-\. (If you do not specify a number, Emacs either passes the number 4 to the command or otherwise runs the command differently than it would otherwise.) See Arguments.

If you are reading this in Info using GNU Emacs, you can read through this whole document just by pressing the space bar, <SPC>. (To learn about Info, type C-h i and then select Info.)

A note on terminology: when I use the word Lisp alone, I often am referring to the various dialects of Lisp in general, but when I speak of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.

Node:Thank You, Previous:Note for Novices, Up:Preface

Thank You

My thanks to all who helped me with this book. My especial thanks to Jim Blandy, Noah Friedman, Jim Kingdon, Roland McGrath, Frank Ritter, Randy Smith, Richard M. Stallman, and Melissa Weisshaus. My thanks also go to both Philip Johnson and David Stampe for their patient encouragement. My mistakes are my own.

Robert J. Chassell

Node:List Processing, Next:Practicing Evaluation, Previous:Preface, Up:Top

1 List Processing

To the untutored eye, Lisp is a strange programming language. In Lisp code there are parentheses everywhere. Some people even claim that the name stands for `Lots of Isolated Silly Parentheses'. But the claim is unwarranted. Lisp stands for LISt Processing, and the programming language handles lists (and lists of lists) by putting them between parentheses. The parentheses mark the boundaries of the list. Sometimes a list is preceded by a single apostrophe or quotation mark, '. Lists are the basis of Lisp.

  • Lisp Lists: What are lists?
  • Run a Program: Any list in Lisp is a program ready to run.
  • Making Errors: Generating an error message.
  • Names & Definitions: Names of symbols and function definitions.
  • Lisp Interpreter: What the Lisp interpreter does.
  • Evaluation: Running a program.
  • Variables: Returning a value from a variable.
  • Arguments: Passing information to a function.
  • set & setq: Setting the value of a variable.
  • Summary: The major points.
  • Error Message Exercises:

Node:Lisp Lists, Next:Run a Program, Previous:List Processing, Up:List Processing

1.1 Lisp Lists

In Lisp, a list looks like this: '(rose violet daisy buttercup). This list is preceded by a single apostrophe. It could just as well be written as follows, which looks more like the kind of list you are likely to be familiar with:

'(rose
  violet
  daisy
  buttercup)

The elements of this list are the names of the four different flowers, separated from each other by whitespace and surrounded by parentheses, like flowers in a field with a stone wall around them.

  • Numbers Lists: List have numbers, other lists, in them.
  • Lisp Atoms: Elemental entities.
  • Whitespace in Lists: Formating lists to be readable.
  • Typing Lists: How GNU Emacs helps you type lists.

Node:Numbers Lists, Next:Lisp Atoms, Previous:Lisp Lists, Up:Lisp Lists

Numbers, Lists inside of Lists

Lists can also have numbers in them, as in this list: (+ 2 2). This list has a plus-sign, +, followed by two 2s, each separated by whitespace.

In Lisp, both data and programs are represented the same way; that is, they are both lists of words, numbers, or other lists, separated by whitespace and surrounded by parentheses. (Since a program looks like data, one program may easily serve as data for another; this is a very powerful feature of Lisp.) (Incidentally, these two parenthetical remarks are not Lisp lists, because they contain ; and . as punctuation marks.)

Here is another list, this time with a list inside of it:

'(this list has (a list inside of it))

The components of this list are the words this, list, has, and the list (a list inside of it). The interior list is made up of the words a, list, inside, of, it.

Node:Lisp Atoms, Next:Whitespace in Lists, Previous:Numbers Lists, Up:Lisp Lists

1.1.1 Lisp Atoms

In Lisp, what we have been calling words are called atoms. This term comes from the historical meaning of the word atom, which means `indivisible'. As far as Lisp is concerned, the words we have been using in the lists cannot be divided into any smaller parts and still mean the same thing as part of a program; likewise with numbers and single character symbols like +. On the other hand, unlike an atom, a list can be split into parts. (See car cdr & cons Fundamental Functions.)

In a list, atoms are separated from each other by whitespace. They can be right next to a parenthesis.

Technically speaking, a list in Lisp consists of parentheses surrounding atoms separated by whitespace or surrounding other lists or surrounding both atoms and other lists. A list can have just one atom in it or have nothing in it at all. A list with nothing in it looks like this: (), and is called the empty list. Unlike anything else, an empty list is considered both an atom and a list at the same time.

The printed representation of both atoms and lists are called symbolic expressions or, more concisely, s-expressions. The word expression by itself can refer to either the printed representation, or to the atom or list as it is held internally in the computer. Often, people use the term expression indiscriminately. (Also, in many texts, the word form is used as a synonym for expression.)

Incidentally, the atoms that make up our universe were named such when they were thought to be indivisible; but it has been found that physical atoms are not indivisible. Parts can split off an atom or it can fission into two parts of roughly equal size. Physical atoms were named prematurely, before their truer nature was found. In Lisp, certain kinds of atom, such as an array, can be separated into parts; but the mechanism for doing this is different from the mechanism for splitting a list. As far as list operations are concerned, the atoms of a list are unsplittable.

As in English, the meanings of the component letters of a Lisp atom are different from the meaning the letters make as a word. For example, the word for the South American sloth, the ai, is completely different from the two words, a, and i.

There are many kinds of atom in nature but only a few in Lisp: for example, numbers, such as 37, 511, or 1729, and symbols, such as +, foo, or forward-line. The words we have listed in the examples above are all symbols. In everyday Lisp conversation, the word "atom" is not often used, because programmers usually try to be more specific about what kind of atom they are dealing with. Lisp programming is mostly about symbols (and sometimes numbers) within lists. (Incidentally, the preceding three word parenthetical remark is a proper list in Lisp, since it consists of atoms, which in this case are symbols, separated by whitespace and enclosed by parentheses, without any non-Lisp punctuation.)

In addition, text between double quotation marks--even sentences or paragraphs--is an atom. Here is an example:

'(this list includes "text between quotation marks.")

In Lisp, all of the quoted text including the punctuation mark and the blank spaces is a single atom. This kind of atom is called a string (for `string of characters') and is the sort of thing that is used for messages that a computer can print for a human to read. Strings are a different kind of atom than numbers or symbols and are used differently.

Node:Whitespace in Lists, Next:Typing Lists, Previous:Lisp Atoms, Up:Lisp Lists

1.1.2 Whitespace in Lists

The amount of whitespace in a list does not matter. From the point of view of the Lisp language,

'(this list
   looks like this)

is exactly the same as this:

'(this list looks like this)

Both examples show what to Lisp is the same list, the list made up of the symbols this, list, looks, like, and this in that order.

Extra whitespace and newlines are designed to make a list more readable by humans. When Lisp reads the expression, it gets rid of all the extra whitespace (but it needs to have at least one space between atoms in order to tell them apart.)

Odd as it seems, the examples we have seen cover almost all of what Lisp lists look like! Every other list in Lisp looks more or less like one of these examples, except that the list may be longer and more complex. In brief, a list is between parentheses, a string is between quotation marks, a symbol looks like a word, and a number looks like a number. (For certain situations, square brackets, dots and a few other special characters may be used; however, we will go quite far without them.)

Node:Typing Lists, Previous:Whitespace in Lists, Up:Lisp Lists

1.1.3 GNU Emacs Helps You Type Lists

When you type a Lisp expression in GNU Emacs using either Lisp Interaction mode or Emacs Lisp mode, you have available to you several commands to format the Lisp expression so it is easy to read. For example, pressing the <TAB> key automatically indents the line the cursor is on by the right amount. A command to properly indent the code in a region is customarily bound to M-C-\. Indentation is designed so that you can see which elements of a list belongs to which list--elements of a sub-list are indented more than the elements of the enclosing list.

In addition, when you type a closing parenthesis, Emacs momentarily jumps the cursor back to the matching opening parenthesis, so you can see which one it is. This is very useful, since every list you type in Lisp must have its closing parenthesis match its opening parenthesis. (See Major Modes, for more information about Emacs' modes.)

Node:Run a Program, Next:Making Errors, Previous:Lisp Lists, Up:List Processing

1.2 Run a Program

A list in Lisp--any list--is a program ready to run. If you run it (for which the Lisp jargon is evaluate), the computer will do one of three things: do nothing except return to you the list itself; send you an error message; or, treat the first symbol in the list as a command to do something. (Usually, of course, it is the last of these three things that you really want!)

The single apostrophe, ', that I put in front of some of the example lists in preceding sections is called a quote; when it precedes a list, it tells Lisp to do nothing with the list, other than take it as it is written. But if there is no quote preceding a list, the first item of the list is special: it is a command for the computer to obey. (In Lisp, these commands are called functions.) The list (+ 2 2) shown above did not have a quote in front of it, so Lisp understands that the + is an instruction to do something with the rest of the list: add the numbers that follow.

If you are reading this inside of GNU Emacs in Info, here is how you can evaluate such a list: place your cursor immediately after the right hand parenthesis of the following list and then type C-x C-e:

(+ 2 2)

You will see the number 4 appear in the echo area. (In the jargon, what you have just done is "evaluate the list." The echo area is the line at the bottom of the screen that displays or "echoes" text.) Now try the same thing with a quoted list: place the cursor right after the following list and type C-x C-e:

'(this is a quoted list)

You will see (this is a quoted list) appear in the echo area.

In both cases, what you are doing is giving a command to the program inside of GNU Emacs called the Lisp interpreter--giving the interpreter a command to evaluate the expression. The name of the Lisp interpreter comes from the word for the task done by a human who comes up with the meaning of an expression--who "interprets" it.

You can also evaluate an atom that is not part of a list--one that is not surrounded by parentheses; again, the Lisp interpreter translates from the humanly readable expression to the language of the computer. But before discussing this (see Variables), we will discuss what the Lisp interpreter does when you make an error.

Node:Making Errors, Next:Names & Definitions, Previous:Run a Program, Up:List Processing

1.3 Generate an Error Message

Partly so you won't worry if you do it accidentally, we will now give a command to the Lisp interpreter that generates an error message. This is a harmless activity; and indeed, we will often try to generate error messages intentionally. Once you understand the jargon, error messages can be informative. Instead of being called "error" messages, they should be called "help" messages. They are like signposts to a traveller in a strange country; deciphering them can be hard, but once understood, they can point the way.

The error message is generated by a built-in GNU Emacs debugger. We will `enter the debugger'. You get out of the debugger by typing q.

What we will do is evaluate a list that is not quoted and does not have a meaningful command as its first element. Here is a list almost exactly the same as the one we just used, but without the single-quote in front of it. Position the cursor right after it and type C-x C-e:

(this is an unquoted list)

What you see depends on which version of Emacs you are running. GNU Emacs version 21 provides more information than version 20 and before. First, the more recent result of generating an error; then the earlier, version 20 result.

In GNU Emacs version 21, a *Backtrace* window will open up and you will see the following in it:

---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function this)
  (this is an unquoted list)
  eval((this is an unquoted list))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

Your cursor will be in this window (you may have to wait a few seconds before it becomes visible). To quit the debugger and make the debugger window go away, type:

q

Please type q right now, so you become confident that you can get out of the debugger. Then, type C-x C-e again to re-enter it.

Based on what we already know, we can almost read this error message.

You read the *Backtrace* buffer from the bottom up; it tells you what Emacs did. When you typed C-x C-e, you made an interactive call to the command eval-last-sexp. eval is an abbreviation for `evaluate' and sexp is an abbreviation for `symbolic expression'. The command means `evaluate last symbolic expression', which is the expression just before your cursor.

Each line above tells you what the Lisp interpreter evaluated next. The most recent action is at the top. The buffer is called the *Backtrace* buffer because it enables you to track Emacs backwards.

At the top of the *Backtrace* buffer, you see the line:

Debugger entered--Lisp error: (void-function this)

The Lisp interpreter tried to evaluate the first atom of the list, the word this. It is this action that generated the error message void-function this.

The message contains the words void-function and this.

The word function was mentioned once before. It is a very important word. For our purposes, we can define it by saying that a function is a set of instructions to the computer that tell the computer to do something.

Now we can begin to understand the error message: void-function this. The function (that is, the word this) does not have a definition of any set of instructions for the computer to carry out.

The slightly odd word, void-function, is designed to cover the way Emacs Lisp is implemented, which is that when a symbol does not have a function definition attached to it, the place that should contain the instructions is `void'.

On the other hand, since we were able to add 2 plus 2 successfully, by evaluating (+ 2 2), we can infer that the symbol + must have a set of instructions for the computer to obey and those instructions must be to add the numbers that follow the +.

In GNU Emacs version 20, and in earlier versions, you will see only one line of error message; it will appear in the echo area and look like this:

Symbol's function definition is void: this

(Also, your terminal may beep at you--some do, some don't; and others blink. This is just a device to get your attention.) The message goes away as soon as you type another key, even just to move the cursor.

We know the meaning of the word Symbol. It refers to the first atom of the list, the word this. The word function refers to the instructions that tell the computer what to do. (Technically, the symbol tells the computer where to find the instructions, but this is a complication we can ignore for the moment.)

The error message can be understood: Symbol's function definition is void: this. The symbol (that is, the word this) lacks instructions for the computer to carry out.

Node:Names & Definitions, Next:Lisp Interpreter, Previous:Making Errors, Up:List Processing

1.4 Symbol Names and Function Definitions

We can articulate another characteristic of Lisp based on what we have discussed so far--an important characteristic: a symbol, like +, is not itself the set of instructions for the computer to carry out. Instead, the symbol is used, perhaps temporarily, as a way of locating the definition or set of instructions. What we see is the name through which the instructions can be found. Names of people work the same way. I can be referred to as Bob; however, I am not the letters B, o, b but am the consciousness consistently associated with a particular life-form. The name is not me, but it can be used to refer to me.

In Lisp, one set of instructions can be attached to several names. For example, the computer instructions for adding numbers can be linked to the symbol plus as well as to the symbol + (and are in some dialects of Lisp). Among humans, I can be referred to as Robert as well as Bob and by other words as well.

On the other hand, a symbol can have only one function definition attached to it at a time. Otherwise, the computer would be confused as to which definition to use. If this were the case among people, only one person in the world could be named Bob. However, the function definition to which the name refers can be changed readily. (See Install a Function Definition.)

Since Emacs Lisp is large, it is customary to name symbols in a way that identifies the part of Emacs to which the function belongs. Thus, all the names for functions that deal with Texinfo start with texinfo- and those for functions that deal with reading mail start with rmail-.

Node:Lisp Interpreter, Next:Evaluation, Previous:Names & Definitions, Up:List Processing

1.5 The Lisp Interpreter

Based on what we have seen, we can now start to figure out what the Lisp interpreter does when we command it to evaluate a list. First, it looks to see whether there is a quote before the list; if there is, the interpreter just gives us the list. On the other hand, if there is no quote, the interpreter looks at the first element in the list and sees whether it has a function definition. If it does, the interpreter carries out the instructions in the function definition. Otherwise, the interpreter prints an error message.

This is how Lisp works. Simple. There are added complications which we will get to in a minute, but these are the fundamentals. Of course, to write Lisp programs, you need to know how to write function definitions and attach them to names, and how to do this without confusing either yourself or the computer.

  • Complications: Variables, Special forms, Lists within.
  • Byte Compiling: Specially processing code for speed.

Node:Complications, Next:Byte Compiling, Previous:Lisp Interpreter, Up:Lisp Interpreter

Complications

Now, for the first complication. In addition to lists, the Lisp interpreter can evaluate a symbol that is not quoted and does not have parentheses around it. The Lisp interpreter will attempt to determine the symbol's value as a variable. This situation is described in the section on variables. (See Variables.)

The second complication occurs because some functions are unusual and do not work in the usual manner. Those that don't are called special forms. They are used for special jobs, like defining a function, and there are not many of them. In the next few chapters, you will be introduced to several of the more important special forms.

The third and final complication is this: if the function that the Lisp interpreter is looking at is not a special form, and if it is part of a list, the Lisp interpreter looks to see whether the list has a list inside of it. If there is an inner list, the Lisp interpreter first figures out what it should do with the inside list, and then it works on the outside list. If there is yet another list embedded inside the inner list, it works on that one first, and so on. It always works on the innermost list first. The interpreter works on the innermost list first, to evaluate the result of that list. The result may be used by the enclosing expression.

Otherwise, the interpreter works left to right, from one expression to the next.

Node:Byte Compiling, Previous:Complications, Up:Lisp Interpreter

1.5.1 Byte Compiling

One other aspect of interpreting: the Lisp interpreter is able to interpret two kinds of entity: humanly readable code, on which we will focus exclusively, and specially processed code, called byte compiled code, which is not humanly readable. Byte compiled code runs faster than humanly readable code.

You can transform humanly readable code into byte compiled code by running one of the compile commands such as byte-compile-file. Byte compiled code is usually stored in a file that ends with a .elc extension rather than a .el extension. You will see both kinds of file in the emacs/lisp directory; the files to read are those with .el extensions.

As a practical matter, for most things you might do to customize or extend Emacs, you do not need to byte compile; and I will not discuss the topic here. See Byte Compilation, for a full description of byte compilation.

Node:Evaluation, Next:Variables, Previous:Lisp Interpreter, Up:List Processing

1.6 Evaluation

When the Lisp interpreter works on an expression, the term for the activity is called evaluation. We say that the interpreter `evaluates the expression'. I've used this term several times before. The word comes from its use in everyday language, `to ascertain the value or amount of; to appraise', according to Webster's New Collegiate Dictionary.

After evaluating an expression, the Lisp interpreter will most likely return the value that the computer produces by carrying out the instructions it found in the function definition, or perhaps it will give up on that function and produce an error message. (The interpreter may also find itself tossed, so to speak, to a different function or it may attempt to repeat continually what it is doing for ever and ever in what is called an `infinite loop'. These actions are less common; and we can ignore them.) Most frequently, the interpreter returns a value.

At the same time the interpreter returns a value, it may do something else as well, such as move a cursor or copy a file; this other kind of action is called a side effect. Actions that we humans think are important, such as printing results, are often "side effects" to the Lisp interpreter. The jargon can sound peculiar, but it turns out that it is fairly easy to learn to use side effects.

In summary, evaluating a symbolic expression most commonly causes the Lisp interpreter to return a value and perhaps carry out a side effect; or else produce an error.

  • Evaluating Inner Lists: Lists within lists...

Node:Evaluating Inner Lists, Previous:Evaluation, Up:Evaluation

1.6.1 Evaluating Inner Lists

If evaluation applies to a list that is inside another list, the outer list may use the value returned by the first evaluation as information when the outer list is evaluated. This explains why inner expressions are evaluated first: the values they return are used by the outer expressions.

We can investigate this process by evaluating another addition example. Place your cursor after the following expression and type C-x C-e:

(+ 2 (+ 3 3))

The number 8 will appear in the echo area.

What happens is that the Lisp interpreter first evaluates the inner expression, (+ 3 3), for which the value 6 is returned; then it evaluates the outer expression as if it were written (+ 2 6), which returns the value 8. Since there are no more enclosing expressions to evaluate, the interpreter prints that value in the echo area.

Now it is easy to understand the name of the command invoked by the keystrokes C-x C-e: the name is eval-last-sexp. The letters sexp are an abbreviation for `symbolic expression', and eval is an abbreviation for `evaluate'. The command means `evaluate last symbolic expression'.

As an experiment, you can try evaluating the expression by putting the cursor at the beginning of the next line immediately following the expression, or inside the expression.

Here is another copy of the expression:

(+ 2 (+ 3 3))

If you place the cursor at the beginning of the blank line that immediately follows the expression and type C-x C-e, you will still get the value 8 printed in the echo area. Now try putting the cursor inside the expression. If you put it right after the next to last parenthesis (so it appears to sit on top of the last parenthesis), you will get a 6 printed in the echo area! This is because the command evaluates the expression (+ 3 3).

Now put the cursor immediately after a number. Type C-x C-e and you will get the number itself. In Lisp, if you evaluate a number, you get the number itself--this is how numbers differ from symbols. If you evaluate a list starting with a symbol like +, you will get a value returned that is the result of the computer carrying out the instructions in the function definition attached to that name. If a symbol by itself is evaluated, something different happens, as we will see in the next section.

Node:Variables, Next:Arguments, Previous:Evaluation, Up:List Processing

1.7 Variables

In Emacs Lisp, a symbol can have a value attached to it just as it can have a function definition attached to it. The two are different. The function definition is a set of instructions that a computer will obey. A value, on the other hand, is something, such as number or a name, that can vary (which is why such a symbol is called a variable). The value of a symbol can be any expression in Lisp, such as a symbol, number, list, or string. A symbol that has a value is often called a variable.

A symbol can have both a function definition and a value attached to it at the same time. Or it can have just one or the other. The two are separate. This is somewhat similar to the way the name Cambridge can refer to the city in Massachusetts and have some information attached to the name as well, such as "great programming center".

Another way to think about this is to imagine a symbol as being a chest of drawers. The function definition is put in one drawer, the value in another, and so on. What is put in the drawer holding the value can be changed without affecting the contents of the drawer holding the function definition, and vice-versa.

  • fill-column Example:
  • Void Function: The error message for a symbol without a function.
  • Void Variable: The error message for a symbol without a value.

Node:fill-column Example, Next:Void Function, Previous:Variables, Up:Variables

fill-column, an Example Variable

The variable fill-column illustrates a symbol with a value attached to it: in every GNU Emacs buffer, this symbol is set to some value, usually 72 or 70, but sometimes to some other value. To find the value of this symbol, evaluate it by itself. If you are reading this in Info inside of GNU Emacs, you can do this by putting the cursor after the symbol and typing C-x C-e:

fill-column

After I typed C-x C-e, Emacs printed the number 72 in my echo area. This is the value for which fill-column is set for me as I write this. It may be different for you in your Info buffer. Notice that the value returned as a variable is printed in exactly the same way as the value returned by a function carrying out its instructions. From the point of view of the Lisp interpreter, a value returned is a value returned. What kind of expression it came from ceases to matter once the value is known.

A symbol can have any value attached to it or, to use the jargon, we can bind the variable to a value: to a number, such as 72; to a string, "such as this"; to a list, such as (spruce pine oak); we can even bind a variable to a function definition.

A symbol can be bound to a value in several ways. See Setting the Value of a Variable, for information about one way to do this.

Node:Void Function, Next:Void Variable, Previous:fill-column Example, Up:Variables

1.7.1 Error Message for a Symbol Without a Function

When we evaluated fill-column to find its value as a variable, we did not place parentheses around the word. This is because we did not intend to use it as a function name.

If fill-column were the first or only element of a list, the Lisp interpreter would attempt to find the function definition attached to it. But fill-column has no function definition. Try evaluating this:

(fill-column)

In GNU Emacs version 21, you will create a *Backtrace* buffer that says:

---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function fill-column)
  (fill-column)
  eval((fill-column))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

(Remember, to quit the debugger and make the debugger window go away, type q in the *Backtrace* buffer.)

In GNU Emacs 20 and before, you will produce an error message that says:

Symbol's function definition is void: fill-column

(The message will go away away as soon as you move the cursor or type another key.)

Node:Void Variable, Previous:Void Function, Up:Variables

1.7.2 Error Message for a Symbol Without a Value

If you attempt to evaluate a symbol that does not have a value bound to it, you will receive an error message. You can see this by experimenting with our 2 plus 2 addition. In the following expression, put your cursor right after the +, before the first number 2, type C-x C-e:

(+ 2 2)

In GNU Emacs 21, you will create a *Backtrace* buffer that says:

---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-variable +)
  eval(+)
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

(As with the other times we entered the debugger, you can quit by typing q in the *Backtrace* buffer.)

This backtrace is different from the very first error message we saw, which said, Debugger entered--Lisp error: (void-function this). In this case, the function does not have a value as a variable; while in the other error message, the function (the word `this') did not have a definition.

In this experiment with the +, what we did was cause the Lisp interpreter to evaluate the + and look for the value of the variable instead of the function definition. We did this by placing the cursor right after the symbol rather than after the parenthesis of the enclosing list as we did before. As a consequence, the Lisp interpreter evaluated the preceding s-expression, which in this case was the + by itself.

Since + does not have a value bound to it, just the function definition, the error message reported that the symbol's value as a variable was void.

In GNU Emacs version 20 and before, your error message will say:

Symbol's value as variable is void: +

The meaning is the same as in GNU Emacs 21.

Node:Arguments, Next:set & setq, Previous:Variables, Up:List Processing

1.8 Arguments

To see how information is passed to functions, let's look again at our old standby, the addition of two plus two. In Lisp, this is written as follows:

(+ 2 2)

If you evaluate this expression, the number 4 will appear in your echo area. What the Lisp interpreter does is add the numbers that follow the +.

The numbers added by + are called the arguments of the function +. These numbers are the information that is given to or passed to the function.

The word `argument' comes from the way it is used in mathematics and does not refer to a disputation between two people; instead it refers to the information presented to the function, in this case, to the +. In Lisp, the arguments to a function are the atoms or lists that follow the function. The values returned by the evaluation of these atoms or lists are passed to the function. Different functions require different numbers of arguments; some functions require none at all.1

  • Data types: Types of data passed to a function.
  • Args as Variable or List: An argument can be the value of a variable or list.
  • Variable Number of Arguments: Some functions may take a variable number of arguments.
  • Wrong Type of Argument: Passing an argument of the wrong type to a function.
  • message: A useful function for sending messages.

Node:Data types, Next:Args as Variable or List, Previous:Arguments, Up:Arguments

1.8.1 Arguments' Data Types

The type of data that should be passed to a function depends on what kind of information it uses. The arguments to a function such as + must have values that are numbers, since + adds numbers. Other functions use different kinds of data for their arguments.

For example, the concat function links together or unites two or more strings of text to produce a string. The arguments are strings. Concatenating the two character strings abc, def produces the single string abcdef. This can be seen by evaluating the following:

(concat "abc" "def")

The value produced by evaluating this expression is "abcdef".

A function such as substring uses both a string and numbers as arguments. The function returns a part of the string, a substring of the first argument. This function takes three arguments. Its first argument is the string of characters, the second and third arguments are numbers that indicate the beginning and end of the substring. The numbers are a count of the number of characters (including spaces and punctuations) from the beginning of the string.

For example, if you evaluate the following:

(substring "The quick brown fox jumped." 16 19)

you will see "fox" appear in the echo area. The arguments are the string and the two numbers.

Note that the string passed to substring is a single atom even though it is made up of several words separated by spaces. Lisp counts everything between the two quotation marks as part of the string, including the spaces. You can think of the substring function as a kind of `atom smasher' since it takes an otherwise indivisible atom and extracts a part. However, substring is only able to extract a substring from an argument that is a string, not from another type of atom such as a number or symbol.

Node:Args as Variable or List, Next:Variable Number of Arguments, Previous:Data types, Up:Arguments

1.8.2 An Argument as the Value of a Variable or List

An argument can be a symbol that returns a value when it is evaluated. For example, when the symbol fill-column by itself is evaluated, it returns a number. This number can be used in an addition.

Position the cursor after the following expression and type C-x C-e:

(+ 2 fill-column)

The value will be a number two more than what you get by evaluating fill-column alone. For me, this is 74, because the value of fill-column is 72.

As we have just seen, an argument can be a symbol that returns a value when evaluated. In addition, an argument can be a list that returns a value when it is evaluated. For example, in the following expression, the arguments to the function concat are the strings "The " and " red foxes." and the list (number-to-string (+ 2 fill-column)).

(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")

If you evaluate this expression--and if, as with my Emacs, fill-column evaluates to 72--"The 74 red foxes." will appear in the echo area. (Note that you must put spaces after the word The and before the word red so they will appear in the final string. The function number-to-string converts the integer that the addition function returns to a string. number-to-string is also known as int-to-string.)

Node:Variable Number of Arguments, Next:Wrong Type of Argument, Previous:Args as Variable or List, Up:Arguments

1.8.3 Variable Number of Arguments

Some functions, such as concat, + or *, take any number of arguments. (The * is the symbol for multiplication.) This can be seen by evaluating each of the following expressions in the usual way. What you will see in the echo area is printed in this text after =>, which you may read as `evaluates to'.

In the first set, the functions have no arguments:

(+)       => 0

(*)       => 1

In this set, the functions have one argument each:

(+ 3)     => 3

(* 3)     => 3

In this set, the functions have three arguments each:

(+ 3 4 5) => 12

(* 3 4 5) => 60

Node:Wrong Type of Argument, Next:message, Previous:Variable Number of Arguments, Up:Arguments

1.8.4 Using the Wrong Type Object as an Argument

When a function is passed an argument of the wrong type, the Lisp interpreter produces an error message. For example, the + function expects the values of its arguments to be numbers. As an experiment we can pass it the quoted symbol hello instead of a number. Position the cursor after the following expression and type C-x C-e:

(+ 2 'hello)

When you do this you will generate an error message. What has happened is that + has tried to add the 2 to the value returned by 'hello, but the value returned by 'hello is the symbol hello, not a number. Only numbers can be added. So + could not carry out its addition.

In GNU Emacs version 21, you will create and enter a *Backtrace* buffer that says:

---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error:
         (wrong-type-argument number-or-marker-p hello)
  +(2 hello)
  eval((+ 2 (quote hello)))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

As usual, the error message tries to be helpful and makes sense after you learn how to read it.

The first part of the error message is straightforward; it says wrong type argument. Next comes the mysterious jargon word number-or-marker-p. This word is trying to tell you what kind of argument the + expected.

The symbol number-or-marker-p says that the Lisp interpreter is trying to determine whether the information presented it (the value of the argument) is a number or a marker (a special object representing a buffer position). What it does is test to see whether the + is being given numbers to add. It also tests to see whether the argument is something called a marker, which is a specific feature of Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. When the mark is set with the C-@ or C-<SPC> command, its position is kept as a marker. The mark can be considered a number--the number of characters the location is from the beginning of the buffer.) In Emacs Lisp, + can be used to add the numeric value of marker positions as numbers.

The p of number-or-marker-p is the embodiment of a practice started in the early days of Lisp programming. The p stands for `predicate'. In the jargon used by the early Lisp researchers, a predicate refers to a function to determine whether some property is true or false. So the p tells us that number-or-marker-p is the name of a function that determines whether it is true or false that the argument supplied is a number or a marker. Other Lisp symbols that end in p include zerop, a function that tests whether its argument has the value of zero, and listp, a function that tests whether its argument is a list.

Finally, the last part of the error message is the symbol hello. This is the value of the argument that was passed to +. If the addition had been passed the correct type of object, the value passed would have been a number, such as 37, rather than a symbol like hello. But then you would not have got the error message.

In GNU Emacs version 20 and before, the echo area displays an error message that says:

Wrong type argument: number-or-marker-p, hello

This says, in different words, the same as the top line of the *Backtrace* buffer.

Node:message, Previous:Wrong Type of Argument, Up:Arguments

1.8.5 The message Function

Like +, the message function takes a variable number of arguments. It is used to send messages to the user and is so useful that we will describe it here.

A message is printed in the echo area. For example, you can print a message in your echo area by evaluating the following list:

(message "This message appears in the echo area!")

The whole string between double quotation marks is a single argument and is printed in toto. (Note that in this example, the message itself will appear in the echo area within double quotes; that is because you see the value returned by the message function. In most uses of message in programs that you write, the text will be printed in the echo area as a side-effect, without the quotes. See multiply-by-seven in detail, for an example of this.)

However, if there is a %s in the quoted string of characters, the message function does not print the %s as such, but looks to the argument that follows the string. It evaluates the second argument and prints the value at the location in the string where the %s is.

You can see this by positioning the cursor after the following expression and typing C-x C-e:

(message "The name of this buffer is: %s." (buffer-name))

In Info, "The name of this buffer is: *info*." will appear in the echo area. The function buffer-name returns the name of the buffer as a string, which the message function inserts in place of %s.

To print a value as an integer, use %d in the same way as %s. For example, to print a message in the echo area that states the value of the fill-column, evaluate the following:

(message "The value of fill-column is %d." fill-column)

On my system, when I evaluate this list, "The value of fill-column is 72." appears in my echo area2.

If there is more than one %s in the quoted string, the value of the first argument following the quoted string is printed at the location of the first %s and the value of the second argument is printed at the location of the second %s, and so on.

For example, if you evaluate the following,

(message "There are %d %s in the office!"
         (- fill-column 14) "pink elephants")

a rather whimsical message will appear in your echo area. On my system it says, "There are 58 pink elephants in the office!".

The expression (- fill-column 14) is evaluated and the resulting number is inserted in place of the %d; and the string in double quotes, "pink elephants", is treated as a single argument and inserted in place of the %s. (That is to say, a string between double quotes evaluates to itself, like a number.)

Finally, here is a somewhat complex example that not only illustrates the computation of a number, but also shows how you can use an expression within an expression to generate the text that is substituted for %s:

(message "He saw %d %s"
         (- fill-column 34)
         (concat "red "
                 (substring
                  "The quick brown foxes jumped." 16 21)
                 " leaping."))

In this example, message has three arguments: the string, "He saw %d %s", the expression, (- fill-column 32), and the expression beginning with the function concat. The value resulting from the evaluation of (- fill-column 32) is inserted in place of the %d; and the value returned by the expression beginning with concat is inserted in place of the %s.

When I evaluate the expression, the message "He saw 38 red foxes leaping." appears in my echo area.

Node:set & setq, Next:Summary, Previous:Arguments, Up:List Processing

1.9 Setting the Value of a Variable

There are several ways by which a variable can be given a value. One of the ways is to use either the function set or the function setq. Another way is to use let (see let). (The jargon for this process is to bind a variable to a value.)

The following sections not only describe how set and setq work but also illustrate how arguments are passed.

  • Using set: Setting values.
  • Using setq: Setting a quoted value.
  • Counting: Using setq to count.

Node:Using set, Next:Using setq, Previous:set & setq, Up:set & setq

1.9.1 Using set

To set the value of the symbol flowers to the list '(rose violet daisy buttercup), evaluate the following expression by positioning the cursor after the expression and typing C-x C-e.

(set 'flowers '(rose violet daisy buttercup))

The list (rose violet daisy buttercup) will appear in the echo area. This is what is returned by the set function. As a side effect, the symbol flowers is bound to the list ; that is, the symbol flowers, which can be viewed as a variable, is given the list as its value. (This process, by the way, illustrates how a side effect to the Lisp interpreter, setting the value, can be the primary effect that we humans are interested in. This is because every Lisp function must return a value if it does not get an error, but it will only have a side effect if it is designed to have one.)

After evaluating the set expression, you can evaluate the symbol flowers and it will return the value you just set. Here is the symbol. Place your cursor after it and type C-x C-e.

flowers

When you evaluate flowers, the list (rose violet daisy buttercup) appears in the echo area.

Incidentally, if you evaluate 'flowers, the variable with a quote in front of it, what you will see in the echo area is the symbol itself, flowers. Here is the quoted symbol, so you can try this:

'flowers

Note also, that when you use set, you need to quote both arguments to set, unless you want them evaluated. Since we do not want either argument evaluated, neither the variable flowers nor the list (rose violet daisy buttercup), both are quoted. (When you use set without quoting its first argument, the first argument is evaluated before anything else is done. If you did this and flowers did not have a value already, you would get an error message that the Symbol's value as variable is void; on the other hand, if flowers did return a value after it was evaluated, the set would attempt to set the value that was returned. There are situations where this is the right thing for the function to do; but such situations are rare.)

Node:Using setq, Next:Counting, Previous:Using set, Up:set & setq

1.9.2 Using setq

As a practical matter, you almost always quote the first argument to set. The combination of set and a quoted first argument is so common that it has its own name: the special form setq. This special form is just like set except that the first argument is quoted automatically, so you don't need to type the quote mark yourself. Also, as an added convenience, setq permits you to set several different variables to different values, all in one expression.

To set the value of the variable carnivores to the list '(lion tiger leopard) using setq, the following expression is used:

(setq carnivores '(lion tiger leopard))

This is exactly the same as using set except the first argument is automatically quoted by setq. (The q in setq means quote.)

With set, the expression would look like this:

(set 'carnivores '(lion tiger leopard))

Also, setq can be used to assign different values to different variables. The first argument is bound to the value of the second argument, the third argument is bound to the value of the fourth argument, and so on. For example, you could use the following to assign a list of trees to the symbol trees and a list of herbivores to the symbol herbivores:

(setq trees '(pine fir oak maple)
      herbivores '(gazelle antelope zebra))

(The expression could just as well have been on one line, but it might not have fit on a page; and humans find it easier to read nicely formatted lists.)

Although I have been using the term `assign', there is another way of thinking about the workings of set and setq; and that is to say that set and setq make the symbol point to the list. This latter way of thinking is very common and in forthcoming chapters we shall come upon at least one symbol that has `pointer' as part of its name. The name is chosen because the symbol has a value, specifically a list, attached to it; or, expressed another way, the symbol is set to "point" to the list.

Node:Counting, Previous:Using setq, Up:set & setq

1.9.3 Counting

Here is an example that shows how to use setq in a counter. You might use this to count how many times a part of your program repeats itself. First set a variable to zero; then add one to the number each time the program repeats itself. To do this, you need a variable that serves as a counter, and two expressions: an initial setq expression that sets the counter variable to zero; and a second setq expression that increments the counter each time it is evaluated.

(setq counter 0)                ; Let's call this the initializer.

(setq counter (+ counter 1))    ; This is the incrementer.

counter                         ; This is the counter.

(The text following the ; are comments. See Change a Function Definition.)

If you evaluate the first of these expressions, the initializer, (setq counter 0), and then evaluate the third expression, counter, the number 0 will appear in the echo area. If you then evaluate the second expression, the incrementer, (setq counter (+ counter 1)), the counter will get the value 1. So if you again evaluate counter, the number 1 will appear in the echo area. Each time you evaluate the second expression, the value of the counter will be incremented.

When you evaluate the incrementer, (setq counter (+ counter 1)), the Lisp interpreter first evaluates the innermost list; this is the addition. In order to evaluate this list, it must evaluate the variable counter and the number 1. When it evaluates the variable counter, it receives its current value. It passes this value and the number 1 to the + which adds them together. The sum is then returned as the value of the inner list and passed to the setq which sets the variable counter to this new value. Thus, the value of the variable, counter, is changed.

Node:Summary, Next:Error Message Exercises, Previous:set & setq, Up:List Processing

1.10 Summary

Learning Lisp is like climbing a hill in which the first part is the steepest. You have now climbed the most difficult part; what remains becomes easier as you progress onwards.

In summary,

  • Lisp programs are made up of expressions, which are lists or single atoms.
  • Lists are made up of zero or more atoms or inner lists, separated by whitespace and surrounded by parentheses. A list can be empty.
  • Atoms are multi-character symbols, like forward-paragraph, single character symbols like +, strings of characters between double quotation marks, or numbers.
  • A number evaluates to itself.
  • A string between double quotes also evaluates to itself.
  • When you evaluate a symbol by itself, its value is returned.
  • When you evaluate a list, the Lisp interpreter looks at the first symbol in the list and then at the function definition bound to that symbol. Then the instructions in the function definition are carried out.
  • A single-quote, ', tells the Lisp interpreter that it should return the following expression as written, and not evaluate it as it would if the quote were not there.
  • Arguments are the information passed to a function. The arguments to a function are computed by evaluating the rest of the elements of the list of which the function is the first element.
  • A function always returns a value when it is evaluated (unless it gets an error); in addition, it may also carry out some action called a "side effect". In many cases, a function's primary purpose is to create a side effect.

Node:Error Message Exercises, Previous:Summary, Up:List Processing

1.11 Exercises

A few simple exercises:

  • Generate an error message by evaluating an appropriate symbol that is not within parentheses.
  • Generate an error message by evaluating an appropriate symbol that is between parentheses.
  • Create a counter that increments by two rather than one.
  • Write an expression that prints a message in the echo area when evaluated.

Node:Practicing Evaluation, Next:Writing Defuns, Previous:List Processing, Up:Top

2 Practicing Evaluation

Before learning how to write a function definition in Emacs Lisp, it is useful to spend a little time evaluating various expressions that have already been written. These expressions will be lists with the functions as their first (and often only) element. Since some of the functions associated with buffers are both simple and interesting, we will start with those. In this section, we will evaluate a few of these. In another section, we will study the code of several other buffer-related functions, to see how they were written.

  • How to Evaluate: Typing editing commands or C-x C-e causes evaluation.
  • Buffer Names: Buffers and files are different.
  • Getting Buffers: Getting a buffer itself, not merely its name.
  • Switching Buffers: How to change to another buffer.
  • Buffer Size & Locations: Where point is located and the size of the buffer.
  • Evaluation Exercise:

Node:How to Evaluate, Next:Buffer Names, Previous:Practicing Evaluation, Up:Practicing Evaluation

How to Evaluate

Whenever you give an editing command to Emacs Lisp, such as the command to move the cursor or to scroll the screen, you are evaluating an expression, the first element of which is a function. This is how Emacs works.

When you type keys, you cause the Lisp interpreter to evaluate an expression and that is how you get your results. Even typing plain text involves evaluating an Emacs Lisp function, in this case, one that uses self-insert-command, which simply inserts the character you typed. The functions you evaluate by typing keystrokes are called interactive functions, or commands; how you make a function interactive will be illustrated in the chapter on how to write function definitions. See Making a Function Interactive.

In addition to typing keyboard commands, we have seen a second way to evaluate an expression: by positioning the cursor after a list and typing C-x C-e. This is what we will do in the rest of this section. There are other ways to evaluate an expression as well; these will be described as we come to them.

Besides being used for practicing evaluation, the functions shown in the next few sections are important in their own right. A study of these functions makes clear the distinction between buffers and files, how to switch to a buffer, and how to determine a location within it.

Node:Buffer Names, Next:Getting Buffers, Previous:How to Evaluate, Up:Practicing Evaluation

2.1 Buffer Names

The two functions, buffer-name and buffer-file-name, show the difference between a file and a buffer. When you evaluate the following expression, (buffer-name), the name of the buffer appears in the echo area. When you evaluate (buffer-file-name), the name of the file to which the buffer refers appears in the echo area. Usually, the name returned by (buffer-name) is the same as the name of the file to which it refers, and the name returned by (buffer-file-name) is the full path-name of the file.

A file and a buffer are two different entities. A file is information recorded permanently in the computer (unless you delete it). A buffer, on the other hand, is information inside of Emacs that will vanish at the end of the editing session (or when you kill the buffer). Usually, a buffer contains information that you have copied from a file; we say the buffer is visiting that file. This copy is what you work on and modify. Changes to the buffer do not change the file, until you save the buffer. When you save the buffer, the buffer is copied to the file and is thus saved permanently.

If you are reading this in Info inside of GNU Emacs, you can evaluate each of the following expressions by positioning the cursor after it and typing C-x C-e.

(buffer-name)

(buffer-file-name)

When I do this, "introduction.texinfo" is the value returned by evaluating (buffer-name), and "/gnu/work/intro/introduction.texinfo" is the value returned by evaluating (buffer-file-name). The former is the name of the buffer and the latter is the name of the file. (In the expressions, the parentheses tell the Lisp interpreter to treat buffer-name and buffer-file-name as functions; without the parentheses, the interpreter would attempt to evaluate the symbols as variables. See Variables.)

In spite of the distinction between files and buffers, you will often find that people refer to a file when they mean a buffer and vice-versa. Indeed, most people say, "I am editing a file," rather than saying, "I am editing a buffer which I will soon save to a file." It is almost always clear from context what people mean. When dealing with computer programs, however, it is important to keep the distinction in mind, since the computer is not as smart as a person.

The word `buffer', by the way, comes from the meaning of the word as a cushion that deadens the force of a collision. In early computers, a buffer cushioned the interaction between files and the computer's central processing unit. The drums or tapes that held a file and the central processing unit were pieces of equipment that were very different from each other, working at their own speeds, in spurts. The buffer made it possible for them to work together effectively. Eventually, the buffer grew from being an intermediary, a temporary holding place, to being the place where work is done. This transformation is rather like that of a small seaport that grew into a great city: once it was merely the place where cargo was warehoused temporarily before being loaded onto ships; then it became a business and cultural center in its own right.

Not all buffers are associated with files. For example, when you start an Emacs session by typing the command emacs alone, without naming any files, Emacs will start with the *scratch* buffer on the screen. This buffer is not visiting any file. Similarly, a *Help* buffer is not associated with any file.

If you switch to the *scratch* buffer, type (buffer-name), position the cursor after it, and type C-x C-e to evaluate the expression, the name "*scratch*" is returned and will appear in the echo area. "*scratch*" is the name of the buffer. However, if you type (buffer-file-name) in the *scratch* buffer and evaluate that, nil will appear in the echo area. nil is from the Latin word for `nothing'; in this case, it means that the *scratch* buffer is not associated with any file. (In Lisp, nil is also used to mean `false' and is a synonym for the empty list, ().)

Incidentally, if you are in the *scratch* buffer and want the value returned by an expression to appear in the *scratch* buffer itself rather than in the echo area, type C-u C-x C-e instead of C-x C-e. This causes the value returned to appear after the expression. The buffer will look like this:

(buffer-name)"*scratch*"

You cannot do this in Info since Info is read-only and it will not allow you to change the contents of the buffer. But you can do this in any buffer you can edit; and when you write code or documentation (such as this book), this feature is very useful.

Node:Getting Buffers, Next:Switching Buffers, Previous:Buffer Names, Up:Practicing Evaluation

2.2 Getting Buffers

The buffer-name function returns the name of the buffer; to get the buffer itself, a different function is needed: the current-buffer function. If you use this function in code, what you get is the buffer itself.

A name and the object or entity to which the name refers are different from each other. You are not your name. You are a person to whom others refer by name. If you ask to speak to George and someone hands you a card with the letters G, e, o, r, g, and e written on it, you might be amused, but you would not be satisfied. You do not want to speak to the name, but to the person to whom the name refers. A buffer is similar: the name of the scratch buffer is *scratch*, but the name is not the buffer. To get a buffer itself, you need to use a function such as current-buffer.

However, there is a slight complication: if you evaluate current-buffer in an expression on its own, as we will do here, what you see is a printed representation of the name of the buffer without the contents of the buffer. Emacs works this way for two reasons: the buffer may be thousands of lines long--too long to be conveniently displayed; and, another buffer may have the same contents but a different name, and it is important to distinguish between them.

Here is an expression containing the function:

(current-buffer)

If you evaluate the expression in the usual way, #<buffer *info*> appears in the echo area. The special format indicates that the buffer itself is being returned, rather than just its name.

Incidentally, while you can type a number or symbol into a program, you cannot do that with the printed representation of a buffer: the only way to get a buffer itself is with a function such as current-buffer.

A related function is other-buffer. This returns the most recently selected buffer other than the one you are in currently. If you have recently switched back and forth from the *scratch* buffer, other-buffer will return that buffer.

You can see this by evaluating the expression:

(other-buffer)

You should see #<buffer *scratch*> appear in the echo area, or the name of whatever other buffer you switched back from most recently3.

Node:Switching Buffers, Next:Buffer Size & Locations, Previous:Getting Buffers, Up:Practicing Evaluation

2.3 Switching Buffers

The other-buffer function actually provides a buffer when it is used as an argument to a function that requires one. We can see this by using other-buffer and switch-to-buffer to switch to a different buffer.

But first, a brief introduction to the switch-to-buffer function. When you switched back and forth from Info to the *scratch* buffer to evaluate (buffer-name), you most likely typed C-x b and then typed *scratch* 4 when prompted in the minibuffer for the name of the buffer to which you wanted to switch. The keystrokes, C-x b, cause the Lisp interpreter to evaluate the interactive function switch-to-buffer. As we said before, this is how Emacs works: different keystrokes call or run different functions. For example, C-f calls forward-char, M-e calls forward-sentence, and so on.

By writing switch-to-buffer in an expression, and giving it a buffer to switch to, we can switch buffers just the way C-x b does.

Here is the Lisp expression:

(switch-to-buffer (other-buffer))

The symbol switch-to-buffer is the first element of the list, so the Lisp interpreter will treat it as a function and carry out the instructions that are attached to it. But before doing that, the interpreter will note that other-buffer is inside parentheses and work on that symbol first. other-buffer is the first (and in this case, the only) element of this list, so the Lisp interpreter calls or runs the function. It returns another buffer. Next, the interpreter runs switch-to-buffer, passing to it, as an argument, the other buffer, which is what Emacs will switch to. If you are reading this in Info, try this now. Evaluate the expression. (To get back, type C-x b <RET>.)5

In the programming examples in later sections of this document, you will see the function set-buffer more often than switch-to-buffer. This is because of a difference between computer programs and humans: humans have eyes and expect to see the buffer on which they are working on their computer terminals. This is so obvious, it almost goes without saying. However, programs do not have eyes. When a computer program works on a buffer, that buffer does not need to be visible on the screen.

switch-to-buffer is designed for humans and does two different things: it switches the buffer to which Emacs' attention is directed; and it switches the buffer displayed in the window to the new buffer. set-buffer, on the other hand, does only one thing: it switches the attention of the computer program to a different buffer. The buffer on the screen remains unchanged (of course, normally nothing happens there until the command finishes running).

Also, we have just introduced another jargon term, the word call. When you evaluate a list in which the first symbol is a function, you are calling that function. The use of the term comes from the notion of the function as an entity that can do something for you if you `call' it--just as a plumber is an entity who can fix a leak if you call him or her.

Node:Buffer Size & Locations, Next:Evaluation Exercise, Previous:Switching Buffers, Up:Practicing Evaluation

2.4 Buffer Size and the Location of Point

Finally, let's look at several rather simple functions, buffer-size, point, point-min, and point-max. These give information about the size of a buffer and the location of point within it.

The function buffer-size tells you the size of the current buffer; that is, the function returns a count of the number of characters in the buffer.

(buffer-size)

You can evaluate this in the usual way, by positioning the cursor after the expression and typing C-x C-e.

In Emacs, the current position of the cursor is called point. The expression (point) returns a number that tells you where the cursor is located as a count of the number of characters from the beginning of the buffer up to point.

You can see the character count for point in this buffer by evaluating the following expression in the usual way:

(point)

As I write this, the value of point is 65724. The point function is frequently used in some of the examples later in this book.

The value of point depends, of course, on its location within the buffer. If you evaluate point in this spot, the number will be larger:

(point)

For me, the value of point in this location is 66043, which means that there are 319 characters (including spaces) between the two expressions.

The function point-min is somewhat similar to point, but it returns the value of the minimum permissible value of point in the current buffer. This is the number 1 unless narrowing is in effect. (Narrowing is a mechanism whereby you can restrict yourself, or a program, to operations on just a part of a buffer. See Narrowing and Widening.) Likewise, the function point-max returns the value of the maximum permissible value of point in the current buffer.

Node:Evaluation Exercise, Previous:Buffer Size & Locations, Up:Practicing Evaluation

2.5 Exercise

Find a file with which you are working and move towards its middle. Find its buffer name, file name, length, and your position in the file.

Node:Writing Defuns, Next:Buffer Walk Through, Previous:Practicing Evaluation, Up:Top

3 How To Write Function Definitions

When the Lisp interpreter evaluates a list, it looks to see whether the first symbol on the list has a function definition attached to it; or, put another way, whether the symbol points to a function definition. If it does, the computer carries out the instructions in the definition. A symbol that has a function definition is called, simply, a function (although, properly speaking, the definition is the function and the symbol refers to it.)

  • Primitive Functions:
  • defun: The defun special form.
  • Install: Install a function definition.
  • Interactive: Making a function interactive.
  • Interactive Options: Different options for interactive.
  • Permanent Installation: Installing code permanently.
  • let: Creating and initializing local variables.
  • if: What if?
  • else: If--then--else expressions.
  • Truth & Falsehood: What Lisp considers false and true.
  • save-excursion: Keeping track of point, mark, and buffer.
  • Review:
  • defun Exercises:

Node:Primitive Functions, Next:defun, Previous:Writing Defuns, Up:Writing Defuns

An Aside about Primitive Functions

All functions are defined in terms of other functions, except for a few primitive functions that are written in the C programming language. When you write functions' definitions, you will write them in Emacs Lisp and use other functions as your building blocks. Some of the functions you will use will themselves be written in Emacs Lisp (perhaps by you) and some will be primitives written in C. The primitive functions are used exactly like those written in Emacs Lisp and behave like them. They are written in C so we can easily run GNU Emacs on any computer that has sufficient power and can run C.

Let me re-emphasize this: when you write code in Emacs Lisp, you do not distinguish between the use of functions written in C and the use of functions written in Emacs Lisp. The difference is irrelevant. I mention the distinction only because it is interesting to know. Indeed, unless you investigate, you won't know whether an already-written function is written in Emacs Lisp or C.

Node:defun, Next:Install, Previous:Primitive Functions, Up:Writing Defuns

3.1 The defun Special Form

In Lisp, a symbol such as mark-whole-buffer has code attached to it that tells the computer what to do when the function is called. This code is called the function definition and is created by evaluating a Lisp expression that starts with the symbol defun (which is an abbreviation for define function). Because defun does not evaluate its arguments in the usual way, it is called a special form.

In subsequent sections, we will look at function definitions from the Emacs source code, such as mark-whole-buffer. In this section, we will describe a simple function definition so you can see how it looks. This function definition uses arithmetic because it makes for a simple example. Some people dislike examples using arithmetic; however, if you are such a person, do not despair. Hardly any of the code we will study in the remainder of this introduction involves arithmetic or mathematics. The examples mostly involve text in one way or another.

A function definition has up to five parts following the word defun:

  1. The name of the symbol to which the function definition should be attached.
  2. A list of the arguments that will be passed to the function. If no arguments will be passed to the function, this is an empty list, ().
  3. Documentation describing the function. (Technically optional, but strongly recommended.)
  4. Optionally, an expression to make the function interactive so you can use it by typing M-x and then the name of the function; or by typing an appropriate key or keychord.
  5. The code that instructs the computer what to do: the body of the function definition.

It is helpful to think of the five parts of a function definition as being organized in a template, with slots for each part:

(defun function-name (arguments...)
  "optional-documentation..."
  (interactive argument-passing-info)     ; optional
  body...)

As an example, here is the code for a function that multiplies its argument by 7. (This example is not interactive. See Making a Function Interactive, for that information.)

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

This definition begins with a parenthesis and the symbol defun, followed by the name of the function.

The name of the function is followed by a list that contains the arguments that will be passed to the function. This list is called the argument list. In this example, the list has only one element, the symbol, number. When the function is used, the symbol will be bound to the value that is used as the argument to the function.

Instead of choosing the word number for the name of the argument, I could have picked any other name. For example, I could have chosen the word multiplicand. I picked the word `number' because it tells what kind of value is intended for this slot; but I could just as well have chosen the word `multiplicand' to indicate the role that the value placed in this slot will play in the workings of the function. I could have called it foogle, but that would have been a bad choice because it would not tell humans what it means. The choice of name is up to the programmer and should be chosen to make the meaning of the function clear.

Indeed, you can choose any name you wish for a symbol in an argument list, even the name of a symbol used in some other function: the name you use in an argument list is private to that particular definition. In that definition, the name refers to a different entity than any use of the same name outside the function definition. Suppose you have a nick-name `Shorty' in your family; when your family members refer to `Shorty', they mean you. But outside your family, in a movie, for example, the name `Shorty' refers to someone else. Because a name in an argument list is private to the function definition, you can change the value of such a symbol inside the body of a function without changing its value outside the function. The effect is similar to that produced by a let expression. (See let.)

The argument list is followed by the documentation string that describes the function. This is what you see when you type C-h f and the name of a function. Incidentally, when you write a documentation string like this, you should make the first line a complete sentence since some commands, such as apropos, print only the first line of a multi-line documentation string. Also, you should not indent the second line of a documentation string, if you have one, because that looks odd when you use C-h f (describe-function). The documentation string is optional, but it is so useful, it should be included in almost every function you write.

The third line of the example consists of the body of the function definition. (Most functions' definitions, of course, are longer than this.) In this function, the body is the list, (* 7 number), which says to multiply the value of number by 7. (In Emacs Lisp, * is the function for multiplication, just as + is the function for addition.)

When you use the multiply-by-seven function, the argument number evaluates to the actual number you want used. Here is an example that shows how multiply-by-seven is used; but don't try to evaluate this yet!

(multiply-by-seven 3)

The symbol number, specified in the function definition in the next section, is given or "bound to" the value 3 in the actual use of the function. Note that although number was inside parentheses in the function definition, the argument passed to the multiply-by-seven function is not in parentheses. The parentheses are written in the function definition so the computer can figure out where the argument list ends and the rest of the function definition begins.

If you evaluate this example, you are likely to get an error message. (Go ahead, try it!) This is because we have written the function definition, but not yet told the computer about the definition--we have not yet installed (or `loaded') the function definition in Emacs. Installing a function is the process that tells the Lisp interpreter the definition of the function. Installation is described in the next section.

Node:Install, Next:Interactive, Previous:defun, Up:Writing Defuns

3.2 Install a Function Definition

If you are reading this inside of Info in Emacs, you can try out the multiply-by-seven function by first evaluating the function definition and then evaluating (multiply-by-seven 3). A copy of the function definition follows. Place the cursor after the last parenthesis of the function definition and type C-x C-e. When you do this, multiply-by-seven will appear in the echo area. (What this means is that when a function definition is evaluated, the value it returns is the name of the defined function.) At the same time, this action installs the function definition.

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

By evaluating this defun, you have just installed multiply-by-seven in Emacs. The function is now just as much a part of Emacs as forward-word or any other editing function you use. (multiply-by-seven will stay installed until you quit Emacs. To reload code automatically whenever you start Emacs, see Installing Code Permanently.)

  • Effect of installation:
  • Change a defun: How to change a function definition.

Node:Effect of installation, Next:Change a defun, Previous:Install, Up:Install

The effect of installation

You can see the effect of installing multiply-by-seven by evaluating the following sample. Place the cursor after the following expression and type C-x C-e. The number 21 will appear in the echo area.

(multiply-by-seven 3)

If you wish, you can read the documentation for the function by typing C-h f (describe-function) and then the name of the function, multiply-by-seven. When you do this, a *Help* window will appear on your screen that says:

multiply-by-seven:
Multiply NUMBER by seven.

(To return to a single window on your screen, type C-x 1.)

Node:Change a defun, Previous:Effect of installation, Up:Install

3.2.1 Change a Function Definition

If you want to change the code in multiply-by-seven, just rewrite it. To install the new version in place of the old one, evaluate the function definition again. This is how you modify code in Emacs. It is very simple.

As an example, you can change the multiply-by-seven function to add the number to itself seven times instead of multiplying the number by seven. It produces the same answer, but by a different path. At the same time, we will add a comment to the code; a comment is text that the Lisp interpreter ignores, but that a human reader may find useful or enlightening. The comment is that this is the "second version".

(defun multiply-by-seven (number)       ; Second version.
  "Multiply NUMBER by seven."
  (+ number number number number number number number))

The comment follows a semicolon, ;. In Lisp, everything on a line that follows a semicolon is a comment. The end of the line is the end of the comment. To stretch a comment over two or more lines, begin each line with a semicolon.

See Beginning a .emacs File, and Comments, for more about comments.

You can install this version of the multiply-by-seven function by evaluating it in the same way you evaluated the first function: place the cursor after the last parenthesis and type C-x C-e.

In summary, this is how you write code in Emacs Lisp: you write a function; install it; test it; and then make fixes or enhancements and install it again.

Node:Interactive, Next:Interactive Options, Previous:Install, Up:Writing Defuns

3.3 Make a Function Interactive

You make a function interactive by placing a list that begins with the special form interactive immediately after the documentation. A user can invoke an interactive function by typing M-x and then the name of the function; or by typing the keys to which it is bound, for example, by typing C-n for next-line or C-x h for mark-whole-buffer.

Interestingly, when you call an interactive function interactively, the value returned is not automatically displayed in the echo area. This is because you often call an interactive function for its side effects, such as moving forward by a word or line, and not for the value returned. If the returned value were displayed in the echo area each time you typed a key, it would be very distracting.

  • Interactive multiply-by-seven: An overview.
  • multiply-by-seven in detail: The interactive version.

Node:Interactive multiply-by-seven, Next:multiply-by-seven in detail, Previous:Interactive, Up:Interactive

An Interactive multiply-by-seven, An Overview

Both the use of the special form interactive and one way to display a value in the echo area can be illustrated by creating an interactive version of multiply-by-seven.

Here is the code:

(defun multiply-by-seven (number)       ; Interactive version.
  "Multiply NUMBER by seven."
  (interactive "p")
  (message "The result is %d" (* 7 number)))

You can install this code by placing your cursor after it and typing C-x C-e. The name of the function will appear in your echo area. Then, you can use this code by typing C-u and a number and then typing M-x multiply-by-seven and pressing <RET>. The phrase The result is ... followed by the product will appear in the echo area.

Speaking more generally, you invoke a function like this in either of two ways:

  1. By typing a prefix argument that contains the number to be passed, and then typing M-x and the name of the function, as with C-u 3 M-x forward-sentence; or,
  2. By typing whatever key or keychord the function is bound to, as with C-u 3 M-e.

Both the examples just mentioned work identically to move point forward three sentences. (Since multiply-by-seven is not bound to a key, it could not be used as an example of key binding.)

(See Some Keybindings, to learn how to bind a command to a key.)

A prefix argument is passed to an interactive function by typing the <META> key followed by a number, for example, M-3 M-e, or by typing C-u and then a number, for example, C-u 3 M-e (if you type C-u without a number, it defaults to 4).

Node:multiply-by-seven in detail, Previous:Interactive multiply-by-seven, Up:Interactive

3.3.1 An Interactive multiply-by-seven

Let's look at the use of the special form interactive and then at the function message in the interactive version of multiply-by-seven. You will recall that the function definition looks like this:

(defun multiply-by-seven (number)       ; Interactive version.
  "Multiply NUMBER by seven."
  (interactive "p")
  (message "The result is %d" (* 7 number)))

In this function, the expression, (interactive "p"), is a list of two elements. The "p" tells Emacs to pass the prefix argument to the function and use its value for the argument of the function.

The argument will be a number. This means that the symbol number will be bound to a number in the line:

(message "The result is %d" (* 7 number))

For example, if your prefix argument is 5, the Lisp interpreter will evaluate the line as if it were:

(message "The result is %d" (* 7 5))

(If you are reading this in GNU Emacs, you can evaluate this expression yourself.) First, the interpreter will evaluate the inner list, which is (* 7 5). This returns a value of 35. Next, it will evaluate the outer list, passing the values of the second and subsequent elements of the list to the function message.

As we have seen, message is an Emacs Lisp function especially designed for sending a one line message to a user. (See The message function.) In summary, the message function prints its first argument in the echo area as is, except for occurrences of %d, %s, or %c. When it sees one of these control sequences, the function looks to the second and subsequent arguments and prints the value of the argument in the location in the string where the control sequence is located.

In the interactive multiply-by-seven function, the control string is %d, which requires a number, and the value returned by evaluating (* 7 5) is the number 35. Consequently, the number 35 is printed in place of the %d and the message is The result is 35.

(Note that when you call the function multiply-by-seven, the message is printed without quotes, but when you call message, the text is printed in double quotes. This is because the value returned by message is what appears in the echo area when you evaluate an expression whose first element is message; but when embedded in a function, message prints the text as a side effect without quotes.)

Node:Interactive Options, Next:Permanent Installation, Previous:Interactive, Up:Writing Defuns

3.4 Different Options for interactive

In the example, multiply-by-seven used "p" as the argument to interactive. This argument told Emacs to interpret your typing either C-u followed by a number or <META> followed by a number as a command to pass that number to the function as its argument. Emacs has more than twenty characters predefined for use with interactive. In almost every case, one of these options will enable you to pass the right information interactively to a function. (See Interactive Codes.)

For example, the character r causes Emacs to pass the beginning and end of the region (the current values of point and mark) to the function as two separate arguments. It is used as follows:

(interactive "r")

On the other hand, a B tells Emacs to ask for the name of a buffer that will be passed to the function. When it sees a B, Emacs will ask for the name by prompting the user in the minibuffer, using a string that follows the B, as in "BAppend to buffer: ". Not only will Emacs prompt for the name, but Emacs will complete the name if you type enough of it and press <TAB>.

A function with two or more arguments can have information passed to each argument by adding parts to the string that follows interactive. When you do this, the information is passed to each argument in the same order it is specified in the interactive list. In the string, each part is separated from the next part by a \n, which is a newline. For example, you could follow "BAppend to buffer: " with a \n) and an r. This would cause Emacs to pass the values of point and mark to the function as well as prompt you for the buffer--three arguments in all.

In this case, the function definition would look like the following, where buffer, start, and end are the symbols to which interactive binds the buffer and the current values of the beginning and ending of the region:

(defun name-of-function (buffer start end)
  "documentation..."
  (interactive "BAppend to buffer: \nr")
  body-of-function...)

(The space after the colon in the prompt makes it look better when you are prompted. The append-to-buffer function looks exactly like this. See The Definition of append-to-buffer.)

If a function does not have arguments, then interactive does not require any. Such a function contains the simple expression (interactive). The mark-whole-buffer function is like this.

Alternatively, if the special letter-codes are not right for your application, you can pass your own arguments to interactive as a list. See interactive, for more information about this advanced technique.

Node:Permanent Installation, Next:let, Previous:Interactive Options, Up:Writing Defuns

3.5 Install Code Permanently

When you install a function definition by evaluating it, it will stay installed until you quit Emacs. The next time you start a new session of Emacs, the function will not be installed unless you evaluate the function definition again.

At some point, you may want to have code installed automatically whenever you start a new session of Emacs. There are several ways of doing this:

  • If you have code that is just for yourself, you can put the code for the function definition in your .emacs initialization file. When you start Emacs, your .emacs file is automatically evaluated and all the function definitions within it are installed. See Your .emacs File.
  • Alternatively, you can put the function definitions that you want installed in one or more files of their own and use the load function to cause Emacs to evaluate and thereby install each of the functions in the files. See Loading Files.
  • On the other hand, if you have code that your whole site will use, it is usual to put it in a file called site-init.el that is loaded when Emacs is built. This makes the code available to everyone who uses your machine. (See the INSTALL file that is part of the Emacs distribution.)

Finally, if you have code that everyone who uses Emacs may want, you can post it on a computer network or send a copy to the Free Software Foundation. (When you do this, please license the code and its documentation under a license that permits other people to run, copy, study, modify, and redistribute the code and which protects you from having your work taken from you.) If you send a copy of your code to the Free Software Foundation, and properly protect yourself and others, it may be included in the next release of Emacs. In large part, this is how Emacs has grown over the past years, by donations.

Node:let, Next:if, Previous:Permanent Installation, Up:Writing Defuns

3.6 let

The let expression is a special form in Lisp that you will need to use in most function definitions.

let is used to attach or bind a symbol to a value in such a way that the Lisp interpreter will not confuse the variable with a variable of the same name that is not part of the function.

To understand why the let special form is necessary, consider the situation in which you own a home that you generally refer to as `the house', as in the sentence, "The house needs painting." If you are visiting a friend and your host refers to `the house', he is likely to be referring to his house, not yours, that is, to a different house.

If your friend is referring to his house and you think he is referring to your house, you may be in for some confusion. The same thing could happen in Lisp if a variable that is used inside of one function has the same name as a variable that is used inside of another function, and the two are not intended to refer to the same value. The let special form prevents this kind of confusion.

  • Prevent confusion:
  • Parts of let Expression:
  • Sample let Expression:
  • Uninitialized let Variables:

Node:Prevent confusion, Next:Parts of let Expression, Previous:let, Up:let

let Prevents Confusion

The let special form prevents confusion. let creates a name for a local variable that overshadows any use of the same name outside the let expression. This is like understanding that whenever your host refers to `the house', he means his house, not yours. (Symbols used in argument lists work the same way. See The defun Special Form.)

Local variables created by a let expression retain their value only within the let expression itself (and within expressions called within the let expression); the local variables have no effect outside the let expression.

Another way to think about let is that it is like a setq that is temporary and local. The values set by let are automatically undone when the let is finished. The setting only effects expressions that are inside the bounds of the let expression. In computer science jargon, we would say "the binding of a symbol is visible only in functions called in the let form; in Emacs Lisp, scoping is dynamic, not lexical."

let can create more than one variable at once. Also, let gives each variable it creates an initial value, either a value specified by you, or nil. (In the jargon, this is called `binding the variable to the value'.) After let has created and bound the variables, it executes the code in the body of the let, and returns the value of the last expression in the body, as the value of the whole let expression. (`Execute' is a jargon term that means to evaluate a list; it comes from the use of the word meaning `to give practical effect to' (Oxford English Dictionary). Since you evaluate an expression to perform an action, `execute' has evolved as a synonym to `evaluate'.)

Node:Parts of let Expression, Next:Sample let Expression, Previous:Prevent confusion, Up:let

3.6.1 The Parts of a let Expression

A let expression is a list of three parts. The first part is the symbol let. The second part is a list, called a varlist, each element of which is either a symbol by itself or a two-element list, the first element of which is a symbol. The third part of the let expression is the body of the let. The body usually consists of one or more lists.

A template for a let expression looks like this:

(let varlist body...)

The symbols in the varlist are the variables that are given initial values by the let special form. Symbols by themselves are given the initial value of nil; and each symbol that is the first element of a two-element list is bound to the value that is returned when the Lisp interpreter evaluates the second element.

Thus, a varlist might look like this: (thread (needles 3)). In this case, in a let expression, Emacs binds the symbol thread to an initial value of nil, and binds the symbol needles to an initial value of 3.

When you write a let expression, what you do is put the appropriate expressions in the slots of the let expression template.

If the varlist is composed of two-element lists, as is often the case, the template for the let expression looks like this:

(let ((variable value)
      (variable value)
      ...)
  body...)

Node:Sample let Expression, Next:Uninitialized let Variables, Previous:Parts of let Expression, Up:let

3.6.2 Sample let Expression

The following expression creates and gives initial values to the two variables zebra and tiger. The body of the let expression is a list which calls the message function.

(let ((zebra 'stripes)
      (tiger 'fierce))
  (message "One kind of animal has %s and another is %s."
           zebra tiger))

Here, the varlist is ((zebra 'stripes) (tiger 'fierce)).

The two variables are zebra and tiger. Each variable is the first element of a two-element list and each value is the second element of its two-element list. In the varlist, Emacs binds the variable zebra to the value stripes, and binds the variable tiger to the value fierce. In this example, both values are symbols preceded by a quote. The values could just as well have been another list or a string. The body of the let follows after the list holding the variables. In this example, the body is a list that uses the message function to print a string in the echo area.

You may evaluate the example in the usual fashion, by placing the cursor after the last parenthesis and typing C-x C-e. When you do this, the following will appear in the echo area:

"One kind of animal has stripes and another is fierce."

As we have seen before, the message function prints its first argument, except for %s. In this example, the value of the variable zebra is printed at the location of the first %s and the value of the variable tiger is printed at the location of the second %s.

Node:Uninitialized let Variables, Previous:Sample let Expression, Up:let

3.6.3 Uninitialized Variables in a let Statement

If you do not bind the variables in a let statement to specific initial values, they will automatically be bound to an initial value of nil, as in the following expression:

(let ((birch 3)
      pine
      fir
      (oak 'some))
  (message
   "Here are %d variables with %s, %s, and %s value."
   birch pine fir oak))

Here, the varlist is ((birch 3) pine fir (oak 'some)).

If you evaluate this expression in the usual way, the following will appear in your echo area:

"Here are 3 variables with nil, nil, and some value."

In this example, Emacs binds the symbol birch to the number 3, binds the symbols pine and fir to nil, and binds the symbol oak to the value some.

Note that in the first part of the let, the variables pine and fir stand alone as atoms that are not surrounded by parentheses; this is because they are being bound to nil, the empty list. But oak is bound to some and so is a part of the list (oak 'some). Similarly, birch is bound to the number 3 and so is in a list with that number. (Since a number evaluates to itself, the number does not need to be quoted. Also, the number is printed in the message using a %d rather than a %s.) The four variables as a group are put into a list to delimit them from the body of the let.

Node:if, Next:else, Previous:let, Up:Writing Defuns

3.7 The if Special Form

A third special form, in addition to defun and let, is the conditional if. This form is used to instruct the computer to make decisions. You can write function definitions without using if, but it is used often enough, and is important enough, to be included here. It is used, for example, in the code for the function beginning-of-buffer.

The basic idea behind an if, is that "if a test is true, then an expression is evaluated." If the test is not true, the expression is not evaluated. For example, you might make a decision such as, "if it is warm and sunny, then go to the beach!"

  • if in more detail:
  • type-of-animal in detail: An example of an if expression.

Node:if in more detail, Next:type-of-animal in detail, Previous:if, Up:if

if in more detail

An if expression written in Lisp does not use the word `then'; the test and the action are the second and third elements of the list whose first element is if. Nonetheless, the test part of an if expression is often called the if-part and the second argument is often called the then-part.

Also, when an if expression is written, the true-or-false-test is usually written on the same line as the symbol if, but the action to carry out if the test is true, the "then-part", is written on the second and subsequent lines. This makes the if expression easier to read.

(if true-or-false-test
    action-to-carry-out-if-test-is-true)

The true-or-false-test will be an expression that is evaluated by the Lisp interpreter.

Here is an example that you can evaluate in the usual manner. The test is whether the number 5 is greater than the number 4. Since it is, the message 5 is greater than 4! will be printed.

(if (> 5 4)                             ; if-part
    (message "5 is greater than 4!"))   ; then-part

(The function > tests whether its first argument is greater than its second argument and returns true if it is.)

Of course, in actual use, the test in an if expression will not be fixed for all time as it is by the expression (> 5 4). Instead, at least one of the variables used in the test will be bound to a value that is not known ahead of time. (If the value were known ahead of time, we would not need to run the test!)

For example, the value may be bound to an argument of a function definition. In the following function definition, the character of the animal is a value that is passed to the function. If the value bound to characteristic is fierce, then the message, It's a tiger! will be printed; otherwise, nil will be returned.

(defun type-of-animal (characteristic)
  "Print message in echo area depending on CHARACTERISTIC.
If the CHARACTERISTIC is the symbol `fierce',
then warn of a tiger."
  (if (equal characteristic 'fierce)
      (message "It's a tiger!")))

If you are reading this inside of GNU Emacs, you can evaluate the function definition in the usual way to install it in Emacs, and then you can evaluate the following two expressions to see the results:

(type-of-animal 'fierce)

(type-of-animal 'zebra)

When you evaluate (type-of-animal 'fierce), you will see the following message printed in the echo area: "It's a tiger!"; and when you evaluate (type-of-animal 'zebra) you will see nil printed in the echo area.

Node:type-of-animal in detail, Previous:if in more detail, Up:if

3.7.1 The type-of-animal Function in Detail

Let's look at the type-of-animal function in detail.

The function definition for type-of-animal was written by filling the slots of two templates, one for a function definition as a whole, and a second for an if expression.

The template for every function that is not interactive is:

(defun name-of-function (argument-list)
  "documentation..."
  body...)

The parts of the function that match this template look like this:

(defun type-of-animal (characteristic)
  "Print message in echo area depending on CHARACTERISTIC.
If the CHARACTERISTIC is the symbol `fierce',
then warn of a tiger."
  body: the if expression)

The name of function is type-of-animal; it is passed the value of one argument. The argument list is followed by a multi-line documentation string. The documentation string is included in the example because it is a good habit to write documentation string for every function definition. The body of the function definition consists of the if expression.

The template for an if expression looks like this:

(if true-or-false-test
    action-to-carry-out-if-the-test-returns-true)

In the type-of-animal function, the code for the if looks like this:

(if (equal characteristic 'fierce)
    (message "It's a tiger!")))

Here, the true-or-false-test is the expression:

(equal characteristic 'fierce)

In Lisp, equal is a function that determines whether its first argument is equal to its second argument. The second argument is the quoted symbol 'fierce and the first argument is the value of the symbol characteristic--in other words, the argument passed to this function.

In the first exercise of type-of-animal, the argument fierce is passed to type-of-animal. Since fierce is equal to fierce, the expression, (equal characteristic 'fierce), returns a value of true. When this happens, the if evaluates the second argument or then-part of the if: (message "It's tiger!").

On the other hand, in the second exercise of type-of-animal, the argument zebra is passed to type-of-animal. zebra is not equal to fierce, so the then-part is not evaluated and nil is returned by the if expression.

Node:else, Next:Truth & Falsehood, Previous:if, Up:Writing Defuns

3.8 If-then-else Expressions

An if expression may have an optional third argument, called the else-part, for the case when the true-or-false-test returns false. When this happens, the second argument or then-part of the overall if expression is not evaluated, but the third or else-part is evaluated. You might think of this as the cloudy day alternative for the decision `if it is warm and sunny, then go to the beach, else read a book!".

The word "else" is not written in the Lisp code; the else-part of an if expression comes after the then-part. In the written Lisp, the else-part is usually written to start on a line of its own and is indented less than the then-part:

(if true-or-false-test
    action-to-carry-out-if-the-test-returns-true
  action-to-carry-out-if-the-test-returns-false)

For example, the following if expression prints the message 4 is not greater than 5! when you evaluate it in the usual way:

(if (> 4 5)                             ; if-part
    (message "5 is greater than 4!")    ; then-part
  (message "4 is not greater than 5!")) ; else-part

Note that the different levels of indentation make it easy to distinguish the then-part from the else-part. (GNU Emacs has several commands that automatically indent if expressions correctly. See GNU Emacs Helps You Type Lists.)

We can extend the type-of-animal function to include an else-part by simply incorporating an additional part to the if expression.

You can see the consequences of doing this if you evaluate the following version of the type-of-animal function definition to install it and then evaluate the two subsequent expressions to pass different arguments to the function.

(defun type-of-animal (characteristic)  ; Second version.
  "Print message in echo area depending on CHARACTERISTIC.
If the CHARACTERISTIC is the symbol `fierce',
then warn of a tiger;
else say it's not fierce."
  (if (equal characteristic 'fierce)
      (message "It's a tiger!")
    (message "It's not fierce!")))

(type-of-animal 'fierce)

(type-of-animal 'zebra)

When you evaluate (type-of-animal 'fierce), you will see the following message printed in the echo area: "It's a tiger!"; but when you evaluate (type-of-animal 'zebra), you will see "It's not fierce!".

(Of course, if the characteristic were ferocious, the message "It's not fierce!" would be printed; and it would be misleading! When you write code, you need to take into account the possibility that some such argument will be tested by the if and write your program accordingly.)

Node:Truth & Falsehood, Next:save-excursion, Previous:else, Up:Writing Defuns

3.9 Truth and Falsehood in Emacs Lisp

There is an important aspect to the truth test in an if expression. So far, we have spoken of `true' and `false' as values of predicates as if they were new kinds of Emacs Lisp objects. In fact, `false' is just our old friend nil. Anything else--anything at all--is `true'.

The expression that tests for truth is interpreted as true if the result of evaluating it is a value that is not nil. In other words, the result of the test is considered true if the value returned is a number such as 47, a string such as "hello", or a symbol (other than nil) such as flowers, or a list, or even a buffer!

  • nil explained: nil has two meanings.

Node:nil explained, Previous:Truth & Falsehood, Up:Truth & Falsehood

An explanation of nil

Before illustrating a test for truth, we need an explanation of nil.

In Emacs Lisp, the symbol nil has two meanings. First, it means the empty list. Second, it means false and is the value returned when a true-or-false-test tests false. nil can be written as an empty list, (), or as nil. As far as the Lisp interpreter is concerned, () and nil are the same. Humans, however, tend to use nil for false and () for the empty list.

In Emacs Lisp, any value that is not nil--is not the empty list--is considered true. This means that if an evaluation returns something that is not an empty list, an if expression will test true. For example, if a number is put in the slot for the test, it will be evaluated and will return itself, since that is what numbers do when evaluated. In this conditional, the if expression will test true. The expression tests false only when nil, an empty list, is returned by evaluating the expression.

You can see this by evaluating the two expressions in the following examples.

In the first example, the number 4 is evaluated as the test in the if expression and returns itself; consequently, the then-part of the expression is evaluated and returned: true appears in the echo area. In the second example, the nil indicates false; consequently, the else-part of the expression is evaluated and returned: false appears in the echo area.

(if 4
    'true
  'false)

(if nil
    'true
  'false)

Incidentally, if some other useful value is not available for a test that returns true, then the Lisp interpreter will return the symbol t for true. For example, the expression (> 5 4) returns t when evaluated, as you can see by evaluating it in the usual way:

(> 5 4)

On the other hand, this function returns nil if the test is false.

(> 4 5)

Node:save-excursion, Next:Review, Previous:Truth & Falsehood, Up:Writing Defuns

3.10 save-excursion

The save-excursion function is the fourth and final special form that we will discuss in this chapter.

In Emacs Lisp programs used for editing, the save-excursion function is very common. It saves the location of point and mark, executes the body of the function, and then restores point and mark to their previous positions if their locations were changed. Its primary purpose is to keep the user from being surprised and disturbed by unexpected movement of point or mark.

  • Point and mark: A review of various locations.
  • Template for save-excursion:

Node:Point and mark, Next:Template for save-excursion, Previous:save-excursion, Up:save-excursion

Point and Mark

Before discussing save-excursion, however, it may be useful first to review what point and mark are in GNU Emacs. Point is the current location of the cursor. Wherever the cursor is, that is point. More precisely, on terminals where the cursor appears to be on top of a character, point is immediately before the character. In Emacs Lisp, point is an integer. The first character in a buffer is number one, the second is number two, and so on. The function point returns the current position of the cursor as a number. Each buffer has its own value for point.

The mark is another position in the buffer; its value can be set with a command such as C-<SPC> (set-mark-command). If a mark has been set, you can use the command C-x C-x (exchange-point-and-mark) to cause the cursor to jump to the mark and set the mark to be the previous position of point. In addition, if you set another mark, the position of the previous mark is saved in the mark ring. Many mark positions can be saved this way. You can jump the cursor to a saved mark by typing C-u C-<SPC> one or more times.

The part of the buffer between point and mark is called the region. Numerous commands work on the region, including center-region, count-lines-region, kill-region, and print-region.

The save-excursion special form saves the locations of point and mark and restores those positions after the code within the body of the special form is evaluated by the Lisp interpreter. Thus, if point were in the beginning of a piece of text and some code moved point to the end of the buffer, the save-excursion would put point back to where it was before, after the expressions in the body of the function were evaluated.

In Emacs, a function frequently moves point as part of its internal workings even though a user would not expect this. For example, count-lines-region moves point. To prevent the user from being bothered by jumps that are both unexpected and (from the user's point of view) unnecessary, save-excursion is often used to keep point and mark in the location expected by the user. The use of save-excursion is good housekeeping.

To make sure the house stays clean, save-excursion restores the values of point and mark even if something goes wrong in the code inside of it (or, to be more precise and to use the proper jargon, "in case of abnormal exit"). This feature is very helpful.

In addition to recording the values of point and mark, save-excursion keeps track of the current buffer, and restores it, too. This means you can write code that will change the buffer and have save-excursion switch you back to the original buffer. This is how save-excursion is used in append-to-buffer. (See The Definition of append-to-buffer.)

Node:Template for save-excursion, Previous:Point and mark, Up:save-excursion

3.10.1 Template for a save-excursion Expression

The template for code using save-excursion is simple:

(save-excursion
  body...)

The body of the function is one or more expressions that will be evaluated in sequence by the Lisp interpreter. If there is more than one expression in the body, the value of the last one will be returned as the value of the save-excursion function. The other expressions in the body are evaluated only for their side effects; and save-excursion itself is used only for its side effect (which is restoring the positions of point and mark).

In more detail, the template for a save-excursion expression looks like this:

(save-excursion
  first-expression-in-body
  second-expression-in-body
  third-expression-in-body
   ...
  last-expression-in-body)

An expression, of course, may be a symbol on its own or a list.

In Emacs Lisp code, a save-excursion expression often occurs within the body of a let expression. It looks like this:

(let varlist
  (save-excursion
    body...))

Node:Review, Next:defun Exercises, Previous:save-excursion, Up:Writing Defuns

3.11 Review

In the last few chapters we have introduced a fair number of functions and special forms. Here they are described in brief, along with a few similar functions that have not been mentioned yet.

eval-last-sexp
Evaluate the last symbolic expression before the current location of point. The value is printed in the echo area unless the function is invoked with an argument; in that case, the output is printed in the current buffer. This command is normally bound to C-x C-e.
defun
Define function. This special form has up to five parts: the name, a template for the arguments that will be passed to the function, documentation, an optional interactive declaration, and the body of the definition.

For example:

(defun back-to-indentation ()
  "Move point to first visible character on line."
  (interactive)
  (beginning-of-line 1)
  (skip-chars-forward " \t"))

interactive
Declare to the interpreter that the function can be used interactively. This special form may be followed by a string with one or more parts that pass the information to the arguments of the function, in sequence. These parts may also tell the interpreter to prompt for information. Parts of the string are separated by newlines, \n.

Common code characters are:

b
The name of an existing buffer.
f
The name of an existing file.
p
The numeric prefix argument. (Note that this `p' is lower case.)
r
Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one.

See Interactive Codes, for a complete list of code characters.

let
Declare that a list of variables is for use within the body of the let and give them an initial value, either nil or a specified value; then evaluate the rest of the expressions in the body of the let and return the value of the last one. Inside the body of the let, the Lisp interpreter does not see the values of the variables of the same names that are bound outside of the let.

For example,

(let ((foo (buffer-name))
      (bar (buffer-size)))
  (message
   "This buffer is %s and has %d characters."
   foo bar))

save-excursion
Record the values of point and mark and the current buffer before evaluating the body of this special form. Restore the values of point and mark and buffer afterward.

For example,

(message "We are %d characters into this buffer."
         (- (point)
            (save-excursion
              (goto-char (point-min)) (point))))

if
Evaluate the first argument to the function; if it is true, evaluate the second argument; else evaluate the third argument, if there is one.

The if special form is called a conditional. There are other conditionals in Emacs Lisp, but if is perhaps the most commonly used.

For example,

(if (string-equal
     (number-to-string 21)
     (substring (emacs-version) 10 12))
    (message "This is version 21 Emacs")
  (message "This is not version 21 Emacs"))

equal
eq
Test whether two objects are the same. equal uses one meaning of the word `same' and eq uses another: equal returns true if the two objects have a similar structure and contents, such as two copies of the same book. On the other hand, eq, returns true if both arguments are actually the same object.
<
>
<=
>=
The < function tests whether its first argument is smaller than its second argument. A corresponding function, >, tests whether the first argument is greater than the second. Likewise, <= tests whether the first argument is less than or equal to the second and >= tests whether the first argument is greater than or equal to the second. In all cases, both arguments must be numbers or markers (markers indicate positions in buffers).
string<
string-lessp
string=
string-equal
The string-lessp function tests whether its first argument is smaller than the second argument. A shorter, alternative name for the same function (a defalias) is string<.

The arguments to string-lessp must be strings or symbols; the ordering is lexicographic, so case is significant. The print names of symbols are used instead of the symbols themselves.

An empty string, "", a string with no characters in it, is smaller than any string of characters.

string-equal provides the corresponding test for equality. Its shorter, alternative name is string=. There are no string test functions that correspond to >, >=, or <=.

message
Print a message in the echo area. The first argument is a string that can contain %s, %d, or %c to print the value of arguments that follow the string. The argument used by %s must be a string or a symbol; the argument used by %d must be a number. The argument used by %c must be an ascii code number; it will be printed as the character with that ASCII code.
setq
set
The setq function sets the value of its first argument to the value of the second argument. The first argument is automatically quoted by setq. It does the same for succeeding pairs of arguments. Another function, set, takes only two arguments and evaluates both of them before setting the value returned by its first argument to the value returned by its second argument.
buffer-name
Without an argument, return the name of the buffer, as a string.
buffer-file-name
Without an argument, return the name of the file the buffer is visiting.
current-buffer
Return the buffer in which Emacs is active; it may not be the buffer that is visible on the screen.
other-buffer
Return the most recently selected buffer (other than the buffer passed to other-buffer as an argument and other than the current buffer).
switch-to-buffer
Select a buffer for Emacs to be active in and display it in the current window so users can look at it. Usually bound to C-x b.
set-buffer
Switch Emacs' attention to a buffer on which programs will run. Don't alter what the window is showing.
buffer-size
Return the number of characters in the current buffer.
point
Return the value of the current position of the cursor, as an integer counting the number of characters from the beginning of the buffer.
point-min
Return the minimum permissible value of point in the current buffer. This is 1, unless narrowing is in effect.
point-max
Return the value of the maximum permissible value of point in the current buffer. This is the end of the buffer, unless narrowing is in effect.

Node:defun Exercises, Previous:Review, Up:Writing Defuns

3.12 Exercises

  • Write a non-interactive function that doubles the value of its argument, a number. Make that function interactive.
  • Write a function that tests whether the current value of fill-column is greater than the argument passed to the function, and if so, prints an appropriate message.

Node:Buffer Walk Through, Next:More Complex, Previous:Writing Defuns, Up:Top

4 A Few Buffer-Related Functions

In this chapter we study in detail several of the functions used in GNU Emacs. This is called a "walk-through". These functions are used as examples of Lisp code, but are not imaginary examples; with the exception of the first, simplified function definition, these functions show the actual code used in GNU Emacs. You can learn a great deal from these definitions. The functions described here are all related to buffers. Later, we will study other functions.

  • Finding More: How to find more information.
  • simplified-beginning-of-buffer: Shows goto-char, point-min, and push-mark.
  • mark-whole-buffer: Almost the same as beginning-of-buffer.
  • append-to-buffer: Uses save-excursion and insert-buffer-substring.
  • Buffer Related Review: Review.
  • Buffer Exercises:

Node:Finding More, Next:simplified-beginning-of-buffer, Previous:Buffer Walk Through, Up:Buffer Walk Through

4.1 Finding More Information

In this walk-through, I will describe each new function as we come to it, sometimes in detail and sometimes briefly. If you are interested, you can get the full documentation of any Emacs Lisp function at any time by typing C-h f and then the name of the function (and then <RET>). Similarly, you can get the full documentation for a variable by typing C-h v and then the name of the variable (and then <RET>).

In versions 20 and higher, when a function is written in Emacs Lisp, describe-function will also tell you the location of the function definition. If you move point over the file name and press the <RET> key, which is this case means help-follow rather than `return' or `enter', Emacs will take you directly to the function definition.

More generally, if you want to see a function in its original source file, you can use the find-tags function to jump to it. find-tags works with a wide variety of languages, not just Lisp, and C, and it works with non-programming text as well. For example, find-tags will jump to the various nodes in the Texinfo source file of this document.

The find-tags function depends on `tags tables' that record the locations of the functions, variables, and other items to which find-tags jumps.

To use the find-tags command, type M-. (i.e., type the <META> key and the period key at the same time, or else type the <ESC> key and then type the period key), and then, at the prompt, type in the name of the function whose source code you want to see, such as mark-whole-buffer, and then type <RET>. Emacs will switch buffers and display the source code for the function on your screen. To switch back to your current buffer, type C-x b <RET>. (On some keyboards, the <META> key is labelled <ALT>.)

Depending on how the initial default values of your copy of Emacs are set, you may also need to specify the location of your `tags table', which is a file called TAGS. For example, if you are interested in Emacs sources, the tags table you will most likely want, if it has already been created for you, will be in a subdirectory of the /usr/local/share/emacs/ directory; thus you would use the M-x visit-tags-table command and specify a pathname such as /usr/local/share/emacs/21.0.100/lisp/TAGS or /usr/local/src/emacs/lisp/TAGS. If the tags table has not already been created, you will have to create it yourself.

To create a TAGS file in a specific directory, switch to that directory in Emacs using M-x cd command, or list the directory with C-x d (dired). Then run the compile command, with etags *.el as the command to execute

M-x compile RET etags *.el RET

For more information, see Create Your Own TAGS File.

After you become more familiar with Emacs Lisp, you will find that you will frequently use find-tags to navigate your way around source code; and you will create your own TAGS tables.

Incidentally, the files that contain Lisp code are conventionally called libraries. The metaphor is derived from that of a specialized library, such as a law library or an engineering library, rather than a general library. Each library, or file, contains functions that relate to a particular topic or activity, such as abbrev.el for handling abbreviations and other typing shortcuts, and help.el for on-line help. (Sometimes several libraries provide code for a single activity, as the various rmail... files provide code for reading electronic mail.) In The GNU Emacs Manual, you will see sentences such as "The C-h p command lets you search the standard Emacs Lisp libraries by topic keywords."

Node:simplified-beginning-of-buffer, Next:mark-whole-buffer, Previous:Finding More, Up:Buffer Walk Through

4.2 A Simplified beginning-of-buffer Definition

The beginning-of-buffer command is a good function to start with since you are likely to be familiar with it and it is easy to understand. Used as an interactive command, beginning-of-buffer moves the cursor to the beginning of the buffer, leaving the mark at the previous position. It is generally bound to M-<.

In this section, we will discuss a shortened version of the function that shows how it is most frequently used. This shortened function works as written, but it does not contain the code for a complex option. In another section, we will describe the entire function. (See Complete Definition of beginning-of-buffer.)

Before looking at the code, let's consider what the function definition has to contain: it must include an expression that makes the function interactive so it can be called by typing M-x beginning-of-buffer or by typing a keychord such as C-<; it must include code to leave a mark at the original position in the buffer; and it must include code to move the cursor to the beginning of the buffer.

Here is the complete text of the shortened version of the function:

(defun simplified-beginning-of-buffer ()
  "Move point to the beginning of the buffer;
leave mark at previous position."
  (interactive)
  (push-mark)
  (goto-char (point-min)))

Like all function definitions, this definition has five parts following the special form defun:

  1. The name: in this example, simplified-beginning-of-buffer.
  2. A list of the arguments: in this example, an empty list, (),
  3. The documentation string.
  4. The interactive expression.
  5. The body.

In this function definition, the argument list is empty; this means that this function does not require any arguments. (When we look at the definition for the complete function, we will see that it may be passed an optional argument.)

The interactive expression tells Emacs that the function is intended to be used interactively. In this example, interactive does not have an argument because simplified-beginning-of-buffer does not require one.

The body of the function consists of the two lines:

(push-mark)
(goto-char (point-min))

The first of these lines is the expression, (push-mark). When this expression is evaluated by the Lisp interpreter, it sets a mark at the current position of the cursor, wherever that may be. The position of this mark is saved in the mark ring.

The next line is (goto-char (point-min)). This expression jumps the cursor to the minimum point in the buffer, that is, to the beginning of the buffer (or to the beginning of the accessible portion of the buffer if it is narrowed. See Narrowing and Widening.)

The push-mark command sets a mark at the place where the cursor was located before it was moved to the beginning of the buffer by the (goto-char (point-min)) expression. Consequently, you can, if you wish, go back to where you were originally by typing C-x C-x.

That is all there is to the function definition!

When you are reading code such as this and come upon an unfamiliar function, such as goto-char, you can find out what it does by using the describe-function command. To use this command, type C-h f and then type in the name of the function and press <RET>. The describe-function command will print the function's documentation string in a *Help* window. For example, the documentation for goto-char is:

One arg, a number.  Set point to that number.
Beginning of buffer is position (point-min),
end is (point-max).

(The prompt for describe-function will offer you the symbol under or preceding the cursor, so you can save typing by positioning the cursor right over or after the function and then typing C-h f <RET>.)

The end-of-buffer function definition is written in the same way as the beginning-of-buffer definition except that the body of the function contains the expression (goto-char (point-max)) in place of (goto-char (point-min)).

Node:mark-whole-buffer, Next:append-to-buffer, Previous:simplified-beginning-of-buffer, Up:Buffer Walk Through

4.3 The Definition of mark-whole-buffer

The mark-whole-buffer function is no harder to understand than the simplified-beginning-of-buffer function. In this case, however, we will look at the complete function, not a shortened version.

The mark-whole-buffer function is not as commonly used as the beginning-of-buffer function, but is useful nonetheless: it marks a whole buffer as a region by putting point at the beginning and a mark at the end of the buffer. It is generally bound to C-x h.

  • mark-whole-buffer overview:
  • Body of mark-whole-buffer: Only three lines of code.

Node:mark-whole-buffer overview, Next:Body of mark-whole-buffer, Previous:mark-whole-buffer, Up:mark-whole-buffer

An overview of mark-whole-buffer

In GNU Emacs 20, the code for the complete function looks like this:

(defun mark-whole-buffer ()
  "Put point at beginning and mark at end of buffer."
  (interactive)
  (push-mark (point))
  (push-mark (point-max))
  (goto-char (point-min)))

Like all other functions, the mark-whole-buffer function fits into the template for a function definition. The template looks like this:

(defun name-of-function (argument-list)
  "documentation..."
  (interactive-expression...)
  body...)

Here is how the function works: the name of the function is mark-whole-buffer; it is followed by an empty argument list, (), which means that the function does not require arguments. The documentation comes next.

The next line is an (interactive) expression that tells Emacs that the function will be used interactively. These details are similar to the simplified-beginning-of-buffer function described in the previous section.

Node:Body of mark-whole-buffer, Previous:mark-whole-buffer overview, Up:mark-whole-buffer

4.3.1 Body of mark-whole-buffer

The body of the mark-whole-buffer function consists of three lines of code:

(push-mark (point))
(push-mark (point-max))
(goto-char (point-min))

The first of these lines is the expression, (push-mark (point)).

This line does exactly the same job as the first line of the body of the simplified-beginning-of-buffer function, which is written (push-mark). In both cases, the Lisp interpreter sets a mark at the current position of the cursor.

I don't know why the expression in mark-whole-buffer is written (push-mark (point)) and the expression in beginning-of-buffer is written (push-mark). Perhaps whoever wrote the code did not know that the arguments for push-mark are optional and that if push-mark is not passed an argument, the function automatically sets mark at the location of point by default. Or perhaps the expression was written so as to parallel the structure of the next line. In any case, the line causes Emacs to determine the position of point and set a mark there.

The next line of mark-whole-buffer is (push-mark (point-max). This expression sets a mark at the point in the buffer that has the highest number. This will be the end of the buffer (or, if the buffer is narrowed, the end of the accessible portion of the buffer. See Narrowing and Widening, for more about narrowing.) After this mark has been set, the previous mark, the one set at point, is no longer set, but Emacs remembers its position, just as all other recent marks are always remembered. This means that you can, if you wish, go back to that position by typing C-u C-<SPC> twice.

(In GNU Emacs 21, the (push-mark (point-max) is slightly more complicated than shown here. The line reads

(push-mark (point-max) nil t)

(The expression works nearly the same as before. It sets a mark at the highest numbered place in the buffer that it can. However, in this version, push-mark has two additional arguments. The second argument to push-mark is nil. This tells the function it should display a message that says `Mark set' when it pushes the mark. The third argument is t. This tells push-mark to activate the mark when Transient Mark mode is turned on. Transient Mark mode highlights the currently active region. It is usually turned off.)

Finally, the last line of the function is (goto-char (point-min))). This is written exactly the same way as it is written in beginning-of-buffer. The expression moves the cursor to the minimum point in the buffer, that is, to the beginning of the buffer (or to the beginning of the accessible portion of the buffer). As a result of this, point is placed at the beginning of the buffer and mark is set at the end of the buffer. The whole buffer is, therefore, the region.

Node:append-to-buffer, Next:Buffer Related Review, Previous:mark-whole-buffer, Up:Buffer Walk Through

4.4 The Definition of append-to-buffer

The append-to-buffer command is very nearly as simple as the mark-whole-buffer command. What it does is copy the region (that is, the part of the buffer between point and mark) from the current buffer to a specified buffer.

  • append-to-buffer overview:
  • append interactive: A two part interactive expression.
  • append-to-buffer body: Incorporates a let expression.
  • append save-excursion: How the save-excursion works.

Node:append-to-buffer overview, Next:append interactive, Previous:append-to-buffer, Up:append-to-buffer

An Overview of append-to-buffer

The append-to-buffer command uses the insert-buffer-substring function to copy the region. insert-buffer-substring is described by its name: it takes a string of characters from part of a buffer, a "substring", and inserts them into another buffer. Most of append-to-buffer is concerned with setting up the conditions for insert-buffer-substring to work: the code must specify both the buffer to which the text will go and the region that will be copied. Here is the complete text of the function:

(defun append-to-buffer (buffer start end)
  "Append to specified buffer the text of the region.
It is inserted into that buffer before its point.

When calling from a program, give three arguments:
a buffer or the name of one, and two character numbers
specifying the portion of the current buffer to be copied."
  (interactive "BAppend to buffer: \nr")
  (let ((oldbuf (current-buffer)))
    (save-excursion
      (set-buffer (get-buffer-create buffer))
      (insert-buffer-substring oldbuf start end))))

The function can be understood by looking at it as a series of filled-in templates.

The outermost template is for the function definition. In this function, it looks like this (with several slots filled in):

(defun append-to-buffer (buffer start end)
  "documentation..."
  (interactive "BAppend to buffer: \nr")
  body...)

The first line of the function includes its name and three arguments. The arguments are the buffer to which the text will be copied, and the start and end of the region in the current buffer that will be copied.

The next part of the function is the documentation, which is clear and complete.

Node:append interactive, Next:append-to-buffer body, Previous:append-to-buffer overview, Up:append-to-buffer

4.4.1 The append-to-buffer Interactive Expression

Since the append-to-buffer function will be used interactively, the function must have an interactive expression. (For a review of interactive, see Making a Function Interactive.) The expression reads as follows:

(interactive "BAppend to buffer: \nr")

This expression has an argument inside of quotation marks and that argument has two parts, separated by \n.

The first part is BAppend to buffer: . Here, the B tells Emacs to ask for the name of the buffer that will be passed to the function. Emacs will ask for the name by prompting the user in the minibuffer, using the string following the B, which is the string Append to buffer: . Emacs then binds the variable buffer in the function's argument list to the specified buffer.

The newline, \n, separates the first part of the argument from the second part. It is followed by an r that tells Emacs to bind the two arguments that follow the symbol buffer in the function's argument list (that is, start and end) to the values of point and mark.

Node:append-to-buffer body, Next:append save-excursion, Previous:append interactive, Up:append-to-buffer

4.4.2 The Body of append-to-buffer

The body of the append-to-buffer function begins with let.

As we have seen before (see let), the purpose of a let expression is to create and give initial values to one or more variables that will only be used within the body of the let. This means that such a variable will not be confused with any variable of the same name outside the let expression.

We can see how the let expression fits into the function as a whole by showing a template for append-to-buffer with the let expression in outline:

(defun append-to-buffer (buffer start end)
  "documentation..."
  (interactive "BAppend to buffer: \nr")
  (let ((variable value))
        body...)

The let expression has three elements:

  1. The symbol let;
  2. A varlist containing, in this case, a single two-element list, (variable value);
  3. The body of the let expression.

In the append-to-buffer function, the varlist looks like this:

(oldbuf (current-buffer))

In this part of the let expression, the one variable, oldbuf, is bound to the value returned by the (current-buffer) expression. The variable, oldbuf, is used to keep track of the buffer in which you are working and from which you will copy.

The element or elements of a varlist are surrounded by a set of parentheses so the Lisp interpreter can distinguish the varlist from the body of the let. As a consequence, the two-element list within the varlist is surrounded by a circumscribing set of parentheses. The line looks like this:

(let ((oldbuf (current-buffer)))
  ... )

The two parentheses before oldbuf might surprise you if you did not realize that the first parenthesis before oldbuf marks the boundary of the varlist and the second parenthesis marks the beginning of the two-element list, (oldbuf (current-buffer)).

Node:append save-excursion, Previous:append-to-buffer body, Up:append-to-buffer

4.4.3 save-excursion in append-to-buffer

The body of the let expression in append-to-buffer consists of a save-excursion expression.

The save-excursion function saves the locations of point and mark, and restores them to those positions after the expressions in the body of the save-excursion complete execution. In addition, save-excursion keeps track of the original buffer, and restores it. This is how save-excursion is used in append-to-buffer.

Incidentally, it is worth noting here that a Lisp function is normally formatted so that everything that is enclosed in a multi-line spread is indented more to the right than the first symbol. In this function definition, the let is indented more than the defun, and the save-excursion is indented more than the let, like this:

(defun ...
  ...
  ...
  (let...
    (save-excursion
      ...

This formatting convention makes it easy to see that the two lines in the body of the save-excursion are enclosed by the parentheses associated with save-excursion, just as the save-excursion itself is enclosed by the parentheses associated with the let:

(let ((oldbuf (current-buffer)))
  (save-excursion
    (set-buffer (get-buffer-create buffer))
    (insert-buffer-substring oldbuf start end))))

The use of the save-excursion function can be viewed as a process of filling in the slots of a template:

(save-excursion
  first-expression-in-body
  second-expression-in-body
   ...
  last-expression-in-body)

In this function, the body of the save-excursion contains only two expressions. The body looks like this:

(set-buffer (get-buffer-create buffer))
(insert-buffer-substring oldbuf start end)

When the append-to-buffer function is evaluated, the two expressions in the body of the save-excursion are evaluated in sequence. The value of the last expression is returned as the value of the save-excursion function; the other expression is evaluated only for its side effects.

The first line in the body of the save-excursion uses the set-buffer function to change the current buffer to the one specified in the first argument to append-to-buffer. (Changing the buffer is the side effect; as we have said before, in Lisp, a side effect is often the primary thing we want.) The second line does the primary work of the function.

The set-buffer function changes Emacs' attention to the buffer to which the text will be copied and from which save-excursion will return.

The line looks like this:

(set-buffer (get-buffer-create buffer))

The innermost expression of this list is (get-buffer-create buffer). This expression uses the get-buffer-create function, which either gets the named buffer, or if it does not exist, creates one with the given name. This means you can use append-to-buffer to put text into a buffer that did not previously exist.

get-buffer-create also keeps set-buffer from getting an unnecessary error: set-buffer needs a buffer to go to; if you were to specify a buffer that does not exist, Emacs would baulk. Since get-buffer-create will create a buffer if none exists, set-buffer is always provided with a buffer.

The last line of append-to-buffer does the work of appending the text:

(insert-buffer-substring oldbuf start end)

The insert-buffer-substring function copies a string from the buffer specified as its first argument and inserts the string into the present buffer. In this case, the argument to insert-buffer-substring is the value of the variable created and bound by the let, namely the value of oldbuf, which was the current buffer when you gave the append-to-buffer command.

After insert-buffer-substring has done its work, save-excursion will restore the action to the original buffer and append-to-buffer will have done its job.

Written in skeletal form, the workings of the body look like this:

(let (bind-oldbuf-to-value-of-current-buffer)
  (save-excursion                       ; Keep track of buffer.
    change-buffer
    insert-substring-from-oldbuf-into-buffer)

  change-back-to-original-buffer-when-finished
let-the-local-meaning-of-oldbuf-disappear-when-finished

In summary, append-to-buffer works as follows: it saves the value of the current buffer in the variable called oldbuf. It gets the new buffer, creating one if need be, and switches Emacs to it. Using the value of oldbuf, it inserts the region of text from the old buffer into the new buffer; and then using save-excursion, it brings you back to your original buffer.

In looking at append-to-buffer, you have explored a fairly complex function. It shows how to use let and save-excursion, and how to change to and come back from another buffer. Many function definitions use let, save-excursion, and set-buffer this way.

Node:Buffer Related Review, Next:Buffer Exercises, Previous:append-to-buffer, Up:Buffer Walk Through

4.5 Review

Here is a brief summary of the various functions discussed in this chapter.

describe-function
describe-variable
Print the documentation for a function or variable. Conventionally bound to C-h f and C-h v.
find-tag
Find the file containing the source for a function or variable and switch buffers to it, positioning point at the beginning of the item. Conventionally bound to M-. (that's a period following the <META> key).
save-excursion
Save the location of point and mark and restore their values after the arguments to save-excursion have been evaluated. Also, remember the current buffer and return to it.
push-mark
Set mark at a location and record the value of the previous mark on the mark ring. The mark is a location in the buffer that will keep its relative position even if text is added to or removed from the buffer.
goto-char
Set point to the location specified by the value of the argument, which can be a number, a marker, or an expression that returns the number of a position, such as (point-min).
insert-buffer-substring
Copy a region of text from a buffer that is passed to the function as an argument and insert the region into the current buffer.
mark-whole-buffer
Mark the whole buffer as a region. Normally bound to C-x h.
set-buffer
Switch the attention of Emacs to another buffer, but do not change the window being displayed. Used when the program rather than a human is to work on a different buffer.
get-buffer-create
get-buffer
Find a named buffer or create one if a buffer of that name does not exist. The get-buffer function returns nil if the named buffer does not exist.

Node:Buffer Exercises, Previous:Buffer Related Review, Up:Buffer Walk Through

4.6 Exercises

  • Write your own simplified-end-of-buffer function definition; then test it to see whether it works.
  • Use if and get-buffer to write a function that prints a message telling you whether a buffer exists.
  • Using find-tag, find the source for the copy-to-buffer function.

Node:More Complex, Next:Narrowing & Widening, Previous:Buffer Walk Through, Up:Top

5 A Few More Complex Functions

In this chapter, we build on what we have learned in previous chapters by looking at more complex functions. The copy-to-buffer function illustrates use of two save-excursion expressions in one definition, while the insert-buffer function illustrates use of an asterisk in an interactive expression, use of or, and the important distinction between a name and the object to which the name refers.

  • copy-to-buffer: With set-buffer, get-buffer-create.
  • insert-buffer: Read-only, and with or.
  • beginning-of-buffer: Shows goto-char, point-min, and push-mark.
  • Second Buffer Related Review:
  • optional Exercise:

Node:copy-to-buffer, Next:insert-buffer, Previous:More Complex, Up:More Complex

5.1 The Definition of copy-to-buffer

After understanding how append-to-buffer works, it is easy to understand copy-to-buffer. This function copies text into a buffer, but instead of adding to the second buffer, it replaces the previous text in the second buffer. The code for the copy-to-buffer function is almost the same as the code for append-to-buffer, except that erase-buffer and a second save-excursion are used. (See The Definition of append-to-buffer, for the description of append-to-buffer.)

The body of copy-to-buffer looks like this

...
(interactive "BCopy to buffer: \nr")
  (let ((oldbuf (current-buffer)))
    (save-excursion
      (set-buffer (get-buffer-create buffer))
      (erase-buffer)
      (save-excursion
        (insert-buffer-substring oldbuf start end)))))

This code is similar to the code in append-to-buffer: it is only after changing to the buffer to which the text will be copied that the definition for this function diverges from the definition for append-to-buffer: the copy-to-buffer function erases the buffer's former contents. (This is what is meant by `replacement'; to replace text, Emacs erases the previous text and then inserts new text.) After erasing the previous contents of the buffer, save-excursion is used for a second time and the new text is inserted.

Why is save-excursion used twice? Consider again what the function does.

In outline, the body of copy-to-buffer looks like this:

(let (bind-oldbuf-to-value-of-current-buffer)
  (save-excursion         ; First use of save-excursion.
    change-buffer
      (erase-buffer)
      (save-excursion     ; Second use of save-excursion.
        insert-substring-from-oldbuf-into-buffer)))

The first use of save-excursion returns Emacs to the buffer from which the text is being copied. That is clear, and is just like its use in append-to-buffer. Why the second use? The reason is that insert-buffer-substring always leaves point at the end of the region being inserted. The second save-excursion causes Emacs to leave point at the beginning of the text being inserted. In most circumstances, users prefer to find point at the beginning of inserted text. (Of course, the copy-to-buffer function returns the user to the original buffer when done--but if the user then switches to the copied-to buffer, point will go to the beginning of the text. Thus, this use of a second save-excursion is a little nicety.)

Node:insert-buffer, Next:beginning-of-buffer, Previous:copy-to-buffer, Up:More Complex

5.2 The Definition of insert-buffer

insert-buffer is yet another buffer-related function. This command copies another buffer into the current buffer. It is the reverse of append-to-buffer or copy-to-buffer, since they copy a region of text from the current buffer to another buffer.

In addition, this code illustrates the use of interactive with a buffer that might be read-only and the important distinction between the name of an object and the object actually referred to.

  • insert-buffer code:
  • insert-buffer interactive: When you can read, but not write.
  • insert-buffer body: The body has an or and a let.
  • if & or: Using an if instead of an or.
  • Insert or: How the or expression works.
  • Insert let: Two save-excursion expressions.

Node:insert-buffer code, Next:insert-buffer interactive, Previous:insert-buffer, Up:insert-buffer

The Code for insert-buffer

Here is the code:

(defun insert-buffer (buffer)
  "Insert after point the contents of BUFFER.
Puts mark after the inserted text.
BUFFER may be a buffer or a buffer name."
  (interactive "*bInsert buffer: ")
  (or (bufferp buffer)
      (setq buffer (get-buffer buffer)))
  (let (start end newmark)
    (save-excursion
      (save-excursion
        (set-buffer buffer)
        (setq start (point-min) end (point-max)))
      (insert-buffer-substring buffer start end)
      (setq newmark (point)))
    (push-mark newmark)))

As with other function definitions, you can use a template to see an outline of the function:

(defun insert-buffer (buffer)
  "documentation..."
  (interactive "*bInsert buffer: ")
  body...)

Node:insert-buffer interactive, Next:insert-buffer body, Previous:insert-buffer code, Up:insert-buffer

5.2.1 The Interactive Expression in insert-buffer

In insert-buffer, the argument to the interactive declaration has two parts, an asterisk, *, and bInsert buffer: .

  • Read-only buffer: When a buffer cannot be modified.
  • b for interactive: An existing buffer or else its name.

Node:Read-only buffer, Next:b for interactive, Previous:insert-buffer interactive, Up:insert-buffer interactive

A Read-only Buffer

The asterisk is for the situation when the buffer is a read-only buffer--a buffer that cannot be modified. If insert-buffer is called on a buffer that is read-only, a message to this effect is printed in the echo area and the terminal may beep or blink at you; you will not be permitted to insert anything into current buffer. The asterisk does not need to be followed by a newline to separate it from the next argument.

Node:b for interactive, Previous:Read-only buffer, Up:insert-buffer interactive

b in an Interactive Expression

The next argument in the interactive expression starts with a lower case b. (This is different from the code for append-to-buffer, which uses an upper-case B. See The Definition of append-to-buffer.) The lower-case b tells the Lisp interpreter that the argument for insert-buffer should be an existing buffer or else its name. (The upper-case B option provides for the possibility that the buffer does not exist.) Emacs will prompt you for the name of the buffer, offering you a default buffer, with name completion enabled. If the buffer does not exist, you receive a message that says "No match"; your terminal may beep at you as well.

Node:insert-buffer body, Next:if & or, Previous:insert-buffer interactive, Up:insert-buffer

5.2.2 The Body of the insert-buffer Function

The body of the insert-buffer function has two major parts: an or expression and a let expression. The purpose of the or expression is to ensure that the argument buffer is bound to a buffer and not just the name of a buffer. The body of the let expression contains the code which copies the other buffer into the current buffer.

In outline, the two expressions fit into the insert-buffer function like this:

(defun insert-buffer (buffer)
  "documentation..."
  (interactive "*bInsert buffer: ")
  (or ...
      ...
  (let (varlist)
      body-of-let... )

To understand how the or expression ensures that the argument buffer is bound to a buffer and not to the name of a buffer, it is first necessary to understand the or function.

Before doing this, let me rewrite this part of the function using if so that you can see what is done in a manner that will be familiar.

Node:if & or, Next:Insert or, Previous:insert-buffer body, Up:insert-buffer

5.2.3 insert-buffer With an if Instead of an or

The job to be done is to make sure the value of buffer is a buffer itself and not the name of a buffer. If the value is the name, then the buffer itself must be got.

You can imagine yourself at a conference where an usher is wandering around holding a list with your name on it and looking for you: the usher is "bound" to your name, not to you; but when the usher finds you and takes your arm, the usher becomes "bound" to you.

In Lisp, you might describe this situation like this:

(if (not (holding-on-to-guest))
    (find-and-take-arm-of-guest))

We want to do the same thing with a buffer--if we do not have the buffer itself, we want to get it.

Using a predicate called bufferp that tells us whether we have a buffer (rather than its name), we can write the code like this:

(if (not (bufferp buffer))              ; if-part
    (setq buffer (get-buffer buffer)))  ; then-part

Here, the true-or-false-test of the if expression is (not (bufferp buffer)); and the then-part is the expression (setq buffer (get-buffer buffer)).

In the test, the function bufferp returns true if its argument is a buffer--but false if its argument is the name of the buffer. (The last character of the function name bufferp is the character p; as we saw earlier, such use of p is a convention that indicates that the function is a predicate, which is a term that means that the function will determine whether some property is true or false. See Using the Wrong Type Object as an Argument.)

The function not precedes the expression (bufferp buffer), so the true-or-false-test looks like this:

(not (bufferp buffer))

not is a function that returns true if its argument is false and false if its argument is true. So if (bufferp buffer) returns true, the not expression returns false and vice-versa: what is "not true" is false and what is "not false" is true.

Using this test, the if expression works as follows: when the value of the variable buffer is actually a buffer rather then its name, the true-or-false-test returns false and the if expression does not evaluate the then-part. This is fine, since we do not need to do anything to the variable buffer if it really is a buffer.

On the other hand, when the value of buffer is not a buffer itself, but the name of a buffer, the true-or-false-test returns true and the then-part of the expression is evaluated. In this case, the then-part is (setq buffer (get-buffer buffer)). This expression uses the get-buffer function to return an actual buffer itself, given its name. The setq then sets the variable buffer to the value of the buffer itself, replacing its previous value (which was the name of the buffer).

Node:Insert or, Next:Insert let, Previous:if & or, Up:insert-buffer

5.2.4 The or in the Body

The purpose of the or expression in the insert-buffer function is to ensure that the argument buffer is bound to a buffer and not just to the name of a buffer. The previous section shows how the job could have been done using an if expression. However, the insert-buffer function actually uses or. To understand this, it is necessary to understand how or works.

An or function can have any number of arguments. It evaluates each argument in turn and returns the value of the first of its arguments that is not nil. Also, and this is a crucial feature of or, it does not evaluate any subsequent arguments after returning the first non-nil value.

The or expression looks like this:

(or (bufferp buffer)
    (setq buffer (get-buffer buffer)))

The first argument to or is the expression (bufferp buffer). This expression returns true (a non-nil value) if the buffer is actually a buffer, and not just the name of a buffer. In the or expression, if this is the case, the or expression returns this true value and does not evaluate the next expression--and this is fine with us, since we do not want to do anything to the value of buffer if it really is a buffer.

On the other hand, if the value of (bufferp buffer) is nil, which it will be if the value of buffer is the name of a buffer, the Lisp interpreter evaluates the next element of the or expression. This is the expression (setq buffer (get-buffer buffer)). This expression returns a non-nil value, which is the value to which it sets the variable buffer--and this value is a buffer itself, not the name of a buffer.

The result of all this is that the symbol buffer is always bound to a buffer itself rather than to the name of a buffer. All this is necessary because the set-buffer function in a following line only works with a buffer itself, not with the name to a buffer.

Incidentally, using or, the situation with the usher would be written like this:

(or (holding-on-to-guest) (find-and-take-arm-of-guest))

Node:Insert let, Previous:Insert or, Up:insert-buffer

5.2.5 The let Expression in insert-buffer

After ensuring that the variable buffer refers to a buffer itself and not just to the name of a buffer, the insert-buffer function continues with a let expression. This specifies three local variables, start, end, and newmark and binds them to the initial value nil. These variables are used inside the remainder of the let and temporarily hide any other occurrence of variables of the same name in Emacs until the end of the let.

The body of the let contains two save-excursion expressions. First, we will look at the inner save-excursion expression in detail. The expression looks like this:

(save-excursion
  (set-buffer buffer)
  (setq start (point-min) end (point-max)))

The expression (set-buffer buffer) changes Emacs' attention from the current buffer to the one from which the text will copied. In that buffer, the variables start and end are set to the beginning and end of the buffer, using the commands point-min and point-max. Note that we have here an illustration of how setq is able to set two variables in the same expression. The first argument of setq is set to the value of its second, and its third argument is set to the value of its fourth.

After the body of the inner save-excursion is evaluated, the save-excursion restores the original buffer, but start and end remain set to the values of the beginning and end of the buffer from which the text will be copied.

The outer save-excursion expression looks like this:

(save-excursion
  (inner-save-excursion-expression
     (go-to-new-buffer-and-set-start-and-end)
  (insert-buffer-substring buffer start end)
  (setq newmark (point)))

The insert-buffer-substring function copies the text into the current buffer from the region indicated by start and end in buffer. Since the whole of the second buffer lies between start and end, the whole of the second buffer is copied into the buffer you are editing. Next, the value of point, which will be at the end of the inserted text, is recorded in the variable newmark.

After the body of the outer save-excursion is evaluated, point and mark are relocated to their original places.

However, it is convenient to locate a mark at the end of the newly inserted text and locate point at its beginning. The newmark variable records the end of the inserted text. In the last line of the let expression, the (push-mark newmark) expression function sets a mark to this location. (The previous location of the mark is still accessible; it is recorded on the mark ring and you can go back to it with C-u C-<SPC>.) Meanwhile, point is located at the beginning of the inserted text, which is where it was before you called the insert function.

The whole let expression looks like this:

(let (start end newmark)
  (save-excursion
    (save-excursion
      (set-buffer buffer)
      (setq start (point-min) end (point-max)))
    (insert-buffer-substring buffer start end)
    (setq newmark (point)))
  (push-mark newmark))

Like the append-to-buffer function, the insert-buffer function uses let, save-excursion, and set-buffer. In addition, the function illustrates one way to use or. All these functions are building blocks that we will find and use again and again.

Node:beginning-of-buffer, Next:Second Buffer Related Review, Previous:insert-buffer, Up:More Complex

5.3 Complete Definition of beginning-of-buffer

The basic structure of the beginning-of-buffer function has already been discussed. (See A Simplified beginning-of-buffer Definition.) This section describes the complex part of the definition.

As previously described, when invoked without an argument, beginning-of-buffer moves the cursor to the beginning of the buffer, leaving the mark at the previous position. However, when the command is invoked with a number between one and ten, the function considers that number to be a fraction of the length of the buffer, measured in tenths, and Emacs moves the cursor that fraction of the way from the beginning of the buffer. Thus, you can either call this function with the key command M-<, which will move the cursor to the beginning of the buffer, or with a key command such as C-u 7 M-< which will move the cursor to a point 70% of the way through the buffer. If a number bigger than ten is used for the argument, it moves to the end of the buffer.

The beginning-of-buffer function can be called with or without an argument. The use of the argument is optional.

  • Optional Arguments:
  • beginning-of-buffer opt arg: Example with optional argument.
  • beginning-of-buffer complete:

Node:Optional Arguments, Next:beginning-of-buffer opt arg, Previous:beginning-of-buffer, Up:beginning-of-buffer

5.3.1 Optional Arguments

Unless told otherwise, Lisp expects that a function with an argument in its function definition will be called with a value for that argument. If that does not happen, you get an error and a message that says Wrong number of arguments.

However, optional arguments are a feature of Lisp: a keyword may be used to tell the Lisp interpreter that an argument is optional. The keyword is &optional. (The & in front of optional is part of the keyword.) In a function definition, if an argument follows the keyword &optional, a value does not need to be passed to that argument when the function is called.

The first line of the function definition of beginning-of-buffer therefore looks like this:

(defun beginning-of-buffer (&optional arg)

In outline, the whole function looks like this:

(defun beginning-of-buffer (&optional arg)
  "documentation..."
  (interactive "P")
  (push-mark)
  (goto-char
    (if-there-is-an-argument
        figure-out-where-to-go
      else-go-to
      (point-min))))

The function is similar to the simplified-beginning-of-buffer function except that the interactive expression has "P" as an argument and the goto-char function is followed by an if-then-else expression that figures out where to put the cursor if there is an argument.

The "P" in the interactive expression tells Emacs to pass a prefix argument, if there is one, to the function. A prefix argument is made by typing the <META> key followed by a number, or by typing C-u and then a number (if you don't type a number, C-u defaults to 4).

The true-or-false-test of the if expression is simple: it is simply the argument arg. If arg has a value that is not nil, which will be the case if beginning-of-buffer is called with an argument, then this true-or-false-test will return true and the then-part of the if expression will be evaluated. On the other hand, if beginning-of-buffer is not called with an argument, the value of arg will be nil and the else-part of the if expression will be evaluated. The else-part is simply point-min, and when this is the outcome, the whole goto-char expression is (goto-char (point-min)), which is how we saw the beginning-of-buffer function in its simplified form.

Node:beginning-of-buffer opt arg, Next:beginning-of-buffer complete, Previous:Optional Arguments, Up:beginning-of-buffer

5.3.2 beginning-of-buffer with an Argument

When beginning-of-buffer is called with an argument, an expression is evaluated which calculates what value to pass to goto-char. This expression is rather complicated at first sight. It includes an inner if expression and much arithmetic. It looks like this:

(if (> (buffer-size) 10000)
    ;; Avoid overflow for large buffer sizes!
    (* (prefix-numeric-value arg) (/ (buffer-size) 10))
  (/
   (+ 10
      (*
       (buffer-size) (prefix-numeric-value arg))) 10))
  • Disentangle beginning-of-buffer:
  • Large buffer case:
  • Small buffer case:

Node:Disentangle beginning-of-buffer, Next:Large buffer case, Previous:beginning-of-buffer opt arg, Up:beginning-of-buffer opt arg

Disentangle beginning-of-buffer

Like other complex-looking expressions, the conditional expression within beginning-of-buffer can be disentangled by looking at it as parts of a template, in this case, the template for an if-then-else expression. In skeletal form, the expression looks like this:

(if (buffer-is-large
    divide-buffer-size-by-10-and-multiply-by-arg
  else-use-alternate-calculation

The true-or-false-test of this inner if expression checks the size of the buffer. The reason for this is that the old Version 18 Emacs used numbers that are no bigger than eight million or so and in the computation that followed, the programmer feared that Emacs might try to use over-large numbers if the buffer were large. The term `overflow', mentioned in the comment, means numbers that are over large. Version 21 Emacs uses larger numbers, but this code has not been touched, if only because people now look at buffers that are far, far larger than ever before.

There are two cases: if the buffer is large and if it is not.

Node:Large buffer case, Next:Small buffer case, Previous:Disentangle beginning-of-buffer, Up:beginning-of-buffer opt arg

What happens in a large buffer

In beginning-of-buffer, the inner if expression tests whether the size of the buffer is greater than 10,000 characters. To do this, it uses the > function and the buffer-size function.

The line looks like this:

(if (> (buffer-size) 10000)

When the buffer is large, the then-part of the if expression is evaluated. It reads like this (after formatting for easy reading):

(*
  (prefix-numeric-value arg)
  (/ (buffer-size) 10))

This expression is a multiplication, with two arguments to the function *.

The first argument is (prefix-numeric-value arg). When "P" is used as the argument for interactive, the value passed to the function as its argument is passed a "raw prefix argument", and not a number. (It is a number in a list.) To perform the arithmetic, a conversion is necessary, and prefix-numeric-value does the job.

The second argument is (/ (buffer-size) 10). This expression divides the numeric value of the buffer by ten. This produces a number that tells how many characters make up one tenth of the buffer size. (In Lisp, / is used for division, just as * is used for multiplication.)

In the multiplication expression as a whole, this amount is multiplied by the value of the prefix argument--the multiplication looks like this:

(* numeric-value-of-prefix-arg
   number-of-characters-in-one-tenth-of-the-buffer)

If, for example, the prefix argument is 7, the one-tenth value will be multiplied by 7 to give a position 70% of the way through the buffer.

The result of all this is that if the buffer is large, the goto-char expression reads like this:

(goto-char (* (prefix-numeric-value arg)
              (/ (buffer-size) 10)))

This puts the cursor where we want it.

Node:Small buffer case, Previous:Large buffer case, Up:beginning-of-buffer opt arg

What happens in a small buffer

If the buffer contains fewer than 10,000 characters, a slightly different computation is performed. You might think this is not necessary, since the first computation could do the job. However, in a small buffer, the first method may not put the cursor on exactly the desired line; the second method does a better job.

The code looks like this:

(/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10))

This is code in which you figure out what happens by discovering how the functions are embedded in parentheses. It is easier to read if you reformat it with each expression indented more deeply than its enclosing expression:

  (/
   (+ 10
      (*
       (buffer-size)
       (prefix-numeric-value arg)))
   10))

Looking at parentheses, we see that the innermost operation is (prefix-numeric-value arg), which converts the raw argument to a number. This number is multiplied by the buffer size in the following expression:

(* (buffer-size) (prefix-numeric-value arg)

This multiplication creates a number that may be larger than the size of the buffer--seven times larger if the argument is 7, for example. Ten is then added to this number and finally the large number is divided by ten to provide a value that is one character larger than the percentage position in the buffer.

The number that results from all this is passed to goto-char and the cursor is moved to that point.

Node:beginning-of-buffer complete, Previous:beginning-of-buffer opt arg, Up:beginning-of-buffer

5.3.3 The Complete beginning-of-buffer

Here is the complete text of the beginning-of-buffer function:

(defun beginning-of-buffer (&optional arg)
  "Move point to the beginning of the buffer;
leave mark at previous position.
With arg N, put point N/10 of the way
from the true beginning.
Don't use this in Lisp programs!
\(goto-char (point-min)) is faster
and does not set the mark."
  (interactive "P")
  (push-mark)
  (goto-char
   (if arg
       (if (> (buffer-size) 10000)
           ;; Avoid overflow for large buffer sizes!
           (* (prefix-numeric-value arg)
              (/ (buffer-size) 10))
         (/ (+ 10 (* (buffer-size)
                     (prefix-numeric-value arg)))
            10))
     (point-min)))
  (if arg (forward-line 1)))

Except for two small points, the previous discussion shows how this function works. The first point deals with a detail in the documentation string, and the second point concerns the last line of the function.

In the documentation string, there is reference to an expression:

\(goto-char (point-min))

A \ is used before the first parenthesis of this expression. This \ tells the Lisp interpreter that the expression should be printed as shown in the documentation rather than evaluated as a symbolic expression, which is what it looks like.

Finally, the last line of the beginning-of-buffer command says to move point to the beginning of the next line if the command is invoked with an argument:

(if arg (forward-line 1)))

This puts the cursor at the beginning of the first line after the appropriate tenths position in the buffer. This is a flourish that means that the cursor is always located at least the requested tenths of the way through the buffer, which is a nicety that is, perhaps, not necessary, but which, if it did not occur, would be sure to draw complaints.

Node:Second Buffer Related Review, Next:optional Exercise, Previous:beginning-of-buffer, Up:More Complex

5.4 Review

Here is a brief summary of some of the topics covered in this chapter.

or
Evaluate each argument in sequence, and return the value of the first argument that is not nil; if none return a value that is not nil, return nil. In brief, return the first true value of the arguments; return a true value if one or any of the other are true.
and
Evaluate each argument in sequence, and if any are nil, return nil; if none are nil, return the value of the last argument. In brief, return a true value only if all the arguments are true; return a true value if one and each of the others is true.
&optional
A keyword used to indicate that an argument to a function definition is optional; this means that the function can be evaluated without the argument, if desired.
prefix-numeric-value
Convert the `raw prefix argument' produced by (interactive "P") to a numeric value.
forward-line
Move point forward to the beginning of the next line, or if the argument is greater than one, forward that many lines. If it can't move as far forward as it is supposed to, forward-line goes forward as far as it can and then returns a count of the number of additional lines it was supposed to move but couldn't.
erase-buffer
Delete the entire contents of the current buffer.
bufferp
Return t if its argument is a buffer; otherwise return nil.

Node:optional Exercise, Previous:Second Buffer Related Review, Up:More Complex

5.5 optional Argument Exercise

Write an interactive function with an optional argument that tests whether its argument, a number, is greater or less than the value of fill-column, and tells you which, in a message. However, if you do not pass an argument to the function, use 56 as a default value.

Node:Narrowing & Widening, Next:car cdr & cons, Previous:More Complex, Up:Top

6 Narrowing and Widening

Narrowing is a feature of Emacs that makes it possible for you to focus on a specific part of a buffer, and work without accidentally changing other parts. Narrowing is normally disabled since it can confuse novices.

  • Narrowing advantages: The advantages of narrowing
  • save-restriction: The save-restriction special form.
  • what-line: The number of the line that point is on.
  • narrow Exercise:

Node:Narrowing advantages, Next:save-restriction, Previous:Narrowing & Widening, Up:Narrowing & Widening

The Advantages of Narrowing

With narrowing, the rest of a buffer is made invisible, as if it weren't there. This is an advantage if, for example, you want to replace a word in one part of a buffer but not in another: you narrow to the part you want and the replacement is carried out only in that section, not in the rest of the buffer. Searches will only work within a narrowed region, not outside of one, so if you are fixing a part of a document, you can keep yourself from accidentally finding parts you do not need to fix by narrowing just to the region you want. (The key binding for narrow-to-region is C-x n n.)

However, narrowing does make the rest of the buffer invisible, which can scare people who inadvertently invoke narrowing and think they have deleted a part of their file. Moreover, the undo command (which is usually bound to C-x u) does not turn off narrowing (nor should it), so people can become quite desperate if they do not know that they can return the rest of a buffer to visibility with the widen command. (The key binding for widen is C-x n w.)

Narrowing is just as useful to the Lisp interpreter as to a human. Often, an Emacs Lisp function is designed to work on just part of a buffer; or conversely, an Emacs Lisp function needs to work on all of a buffer that has been narrowed. The what-line function, for example, removes the narrowing from a buffer, if it has any narrowing and when it has finished its job, restores the narrowing to what it was. On the other hand, the count-lines function, which is called by what-line, uses narrowing to restrict itself to just that portion of the buffer in which it is interested and then restores the previous situation.

Node:save-restriction, Next:what-line, Previous:Narrowing advantages, Up:Narrowing & Widening

6.1 The save-restriction Special Form

In Emacs Lisp, you can use the save-restriction special form to keep track of whatever narrowing is in effect, if any. When the Lisp interpreter meets with save-restriction, it executes the code in the body of the save-restriction expression, and then undoes any changes to narrowing that the code caused. If, for example, the buffer is narrowed and the code that follows save-restriction gets rid of the narrowing, save-restriction returns the buffer to its narrowed region afterwards. In the what-line command, any narrowing the buffer may have is undone by the widen command that immediately follows the save-restriction command. Any original narrowing is restored just before the completion of the function.

The template for a save-restriction expression is simple:

(save-restriction
  body... )

The body of the save-restriction is one or more expressions that will be evaluated in sequence by the Lisp interpreter.

Finally, a point to note: when you use both save-excursion and save-restriction, one right after the other, you should use save-excursion outermost. If you write them in reverse order, you may fail to record narrowing in the buffer to which Emacs switches after calling save-excursion. Thus, when written together, save-excursion and save-restriction should be written like this:

(save-excursion
  (save-restriction
    body...))

In other circumstances, when not written together, the save-excursion and save-restriction special forms must be written in the order appropriate to the function.

For example,

  (save-restriction
    (widen)
    (save-excursion
    body...))

Node:what-line, Next:narrow Exercise, Previous:save-restriction, Up:Narrowing & Widening

6.2 what-line

The what-line command tells you the number of the line in which the cursor is located. The function illustrates the use of the save-restriction and save-excursion commands. Here is the text of the function in full:

(defun what-line ()
  "Print the current line number (in the buffer) of point."
  (interactive)
  (save-restriction
    (widen)
    (save-excursion
      (beginning-of-line)
      (message "Line %d"
               (1+ (count-lines 1 (point)))))))

The function has a documentation line and is interactive, as you would expect. The next two lines use the functions save-restriction and widen.

The save-restriction special form notes whatever narrowing is in effect, if any, in the current buffer and restores that narrowing after the code in the body of the save-restriction has been evaluated.

The save-restriction special form is followed by widen. This function undoes any narrowing the current buffer may have had when what-line was called. (The narrowing that was there is the narrowing that save-restriction remembers.) This widening makes it possible for the line counting commands to count from the beginning of the buffer. Otherwise, they would have been limited to counting within the accessible region. Any original narrowing is restored just before the completion of the function by the save-restriction special form.

The call to widen is followed by save-excursion, which saves the location of the cursor (i.e., of point) and of the mark, and restores them after the code in the body of the save-excursion uses the beginning-of-line function to move point.

(Note that the (widen) expression comes between the save-restriction and save-excursion special forms. When you write the two save- ... expressions in sequence, write save-excursion outermost.)

The last two lines of the what-line function are functions to count the number of lines in the buffer and then print the number in the echo area.

(message "Line %d"
         (1+ (count-lines 1 (point)))))))

The message function prints a one-line message at the bottom of the Emacs screen. The first argument is inside of quotation marks and is printed as a string of characters. However, it may contain %d, %s, or %c to print arguments that follow the string. %d prints the argument as a decimal, so the message will say something such as Line 243.

The number that is printed in place of the %d is computed by the last line of the function:

(1+ (count-lines 1 (point)))

What this does is count the lines from the first position of the buffer, indicated by the 1, up to (point), and then add one to that number. (The 1+ function adds one to its argument.) We add one to it because line 2 has only one line before it, and count-lines counts only the lines before the current line.

After count-lines has done its job, and the message has been printed in the echo area, the save-excursion restores point and mark to their original positions; and save-restriction restores the original narrowing, if any.

Node:narrow Exercise, Previous:what-line, Up:Narrowing & Widening

6.3 Exercise with Narrowing

Write a function that will display the first 60 characters of the current buffer, even if you have narrowed the buffer to its latter half so that the first line is inaccessible. Restore point, mark, and narrowing. For this exercise, you need to use save-restriction, widen, goto-char, point-min, buffer-substring, message, and other functions, a whole potpourri.

Node:car cdr & cons, Next:Cutting & Storing Text, Previous:Narrowing & Widening, Up:Top

7 car, cdr, cons: Fundamental Functions

In Lisp, car, cdr, and cons are fundamental functions. The cons function is used to construct lists, and the car and cdr functions are used to take them apart.

In the walk through of the copy-region-as-kill function, we will see cons as well as two variants on cdr, namely, setcdr and nthcdr. (See copy-region-as-kill.)

  • Strange Names: An historical aside: why the strange names?
  • car & cdr: Functions for extracting part of a list.
  • cons: Constructing a list.
  • nthcdr: Calling cdr repeatedly.
  • nth:
  • setcar: Changing the first element of a list.
  • setcdr: Changing the rest of a list.
  • cons Exercise:

Node:Strange Names, Next:car & cdr, Previous:car cdr & cons, Up:car cdr & cons

Strange Names

The name of the cons function is not unreasonable: it is an abbreviation of the word `construct'. The origins of the names for car and cdr, on the other hand, are esoteric: car is an acronym from the phrase `Contents of the Address part of the Register'; and cdr (pronounced `could-er') is an acronym from the phrase `Contents of the Decrement part of the Register'. These phrases refer to specific pieces of hardware on the very early computer on which the original Lisp was developed. Besides being obsolete, the phrases have been completely irrelevant for more than 25 years to anyone thinking about Lisp. Nonetheless, although a few brave scholars have begun to use more reasonable names for these functions, the old terms are still in use. In particular, since the terms are used in the Emacs Lisp source code, we will use them in this introduction.

Node:car & cdr, Next:cons, Previous:Strange Names, Up:car cdr & cons

7.1 car and cdr

The CAR of a list is, quite simply, the first item in the list. Thus the CAR of the list (rose violet daisy buttercup) is rose.

If you are reading this in Info in GNU Emacs, you can see this by evaluating the following:

(car '(rose violet daisy buttercup))

After evaluating the expression, rose will appear in the echo area.

Clearly, a more reasonable name for the car function would be first and this is often suggested.

car does not remove the first item from the list; it only reports what it is. After car has been applied to a list, the list is still the same as it was. In the jargon, car is `non-destructive'. This feature turns out to be important.

The CDR of a list is the rest of the list, that is, the cdr function returns the part of the list that follows the first item. Thus, while the CAR of the list '(rose violet daisy buttercup) is rose, the rest of the list, the value returned by the cdr function, is (violet daisy buttercup).

You can see this by evaluating the following in the usual way:

(cdr '(rose violet daisy buttercup))

When you evaluate this, (violet daisy buttercup) will appear in the echo area.

Like car, cdr does not remove any elements from the list--it just returns a report of what the second and subsequent elements are.

Incidentally, in the example, the list of flowers is quoted. If it were not, the Lisp interpreter would try to evaluate the list by calling rose as a function. In this example, we do not want to do that.

Clearly, a more reasonable name for cdr would be rest.

(There is a lesson here: when you name new functions, consider very carefully what you are doing, since you may be stuck with the names for far longer than you expect. The reason this document perpetuates these names is that the Emacs Lisp source code uses them, and if I did not use them, you would have a hard time reading the code; but do, please, try to avoid using these terms yourself. The people who come after you will be grateful to you.)

When car and cdr are applied to a list made up of symbols, such as the list (pine fir oak maple), the element of the list returned by the function car is the symbol pine without any parentheses around it. pine is the first element in the list. However, the CDR of the list is a list itself, (fir oak maple), as you can see by evaluating the following expressions in the usual way:

(car '(pine fir oak maple))

(cdr '(pine fir oak maple))

On the other hand, in a list of lists, the first element is itself a list. car returns this first element as a list. For example, the following list contains three sub-lists, a list of carnivores, a list of herbivores and a list of sea mammals:

(car '((lion tiger cheetah)
       (gazelle antelope zebra)
       (whale dolphin seal)))

In this example, the first element or CAR of the list is the list of carnivores, (lion tiger cheetah), and the rest of the list is ((gazelle antelope zebra) (whale dolphin seal)).

(cdr '((lion tiger cheetah)
       (gazelle antelope zebra)
       (whale dolphin seal)))

It is worth saying again that car and cdr are non-destructive--that is, they do not modify or change lists to which they are applied. This is very important for how they are used.

Also, in the first chapter, in the discussion about atoms, I said that in Lisp, "certain kinds of atom, such as an array, can be separated into parts; but the mechanism for doing this is different from the mechanism for splitting a list. As far as Lisp is concerned, the atoms of a list are unsplittable." (See Lisp Atoms.) The car and cdr functions are used for splitting lists and are considered fundamental to Lisp. Since they cannot split or gain access to the parts of an array, an array is considered an atom. Conversely, the other fundamental function, cons, can put together or construct a list, but not an array. (Arrays are handled by array-specific functions. See Arrays.)

Node:cons, Next:nthcdr, Previous:car & cdr, Up:car cdr & cons

7.2 cons

The cons function constructs lists; it is the inverse of car and cdr. For example, cons can be used to make a four element list from the three element list, (fir oak maple):

(cons 'pine '(fir oak maple))

After evaluating this list, you will see

(pine fir oak maple)

appear in the echo area. cons puts a new element at the beginning of a list; it attaches or pushes elements onto the list.

  • Build a list:
  • length: How to find the length of a list.

Node:Build a list, Next:length, Previous:cons, Up:cons

Build a list

cons must have a list to attach to.6 You cannot start from absolutely nothing. If you are building a list, you need to provide at least an empty list at the beginning. Here is a series of cons expressions that build up a list of flowers. If you are reading this in Info in GNU Emacs, you can evaluate each of the expressions in the usual way; the value is printed in this text after =>, which you may read as `evaluates to'.

(cons 'buttercup ())
     => (buttercup)

(cons 'daisy '(buttercup))
     => (daisy buttercup)

(cons 'violet '(daisy buttercup))
     => (violet daisy buttercup)

(cons 'rose '(violet daisy buttercup))
     => (rose violet daisy buttercup)

In the first example, the empty list is shown as () and a list made up of buttercup followed by the empty list is constructed. As you can see, the empty list is not shown in the list that was constructed. All that you see is (buttercup). The empty list is not counted as an element of a list because there is nothing in an empty list. Generally speaking, an empty list is invisible.

The second example, (cons 'daisy '(buttercup)) constructs a new, two element list by putting daisy in front of buttercup; and the third example constructs a three element list by putting violet in front of daisy and buttercup.

Node:length, Previous:Build a list, Up:cons

7.2.1 Find the Length of a List: length

You can find out how many elements there are in a list by using the Lisp function length, as in the following examples:

(length '(buttercup))
     => 1

(length '(daisy buttercup))
     => 2

(length (cons 'violet '(daisy buttercup)))
     => 3

In the third example, the cons function is used to construct a three element list which is then passed to the length function as its argument.

We can also use length to count the number of elements in an empty list:

(length ())
     => 0

As you would expect, the number of elements in an empty list is zero.

An interesting experiment is to find out what happens if you try to find the length of no list at all; that is, if you try to call length without giving it an argument, not even an empty list:

(length )

What you see, if you evaluate this, is the error message

Wrong number of arguments: #<subr length>, 0

This means that the function receives the wrong number of arguments, zero, when it expects some other number of arguments. In this case, one argument is expected, the argument being a list whose length the function is measuring. (Note that one list is one argument, even if the list has many elements inside it.)

The part of the error message that says #<subr length> is the name of the function. This is written with a special notation, #<subr, that indicates that the function length is one of the primitive functions written in C rather than in Emacs Lisp. (subr is an abbreviation for `subroutine'.) See What Is a Function, for more about subroutines.

Node:nthcdr, Next:nth, Previous:cons, Up:car cdr & cons

7.3 nthcdr

The nthcdr function is associated with the cdr function. What it does is take the CDR of a list repeatedly.

If you take the CDR of the list (pine fir oak maple), you will be returned the list (fir oak maple). If you repeat this on what was returned, you will be returned the list (oak maple). (Of course, repeated CDRing on the original list will just give you the original CDR since the function does not change the list. You need to evaluate the CDR of the CDR and so on.) If you continue this, eventually you will be returned an empty list, which in this case, instead of being shown as () is shown as nil.

For review, here is a series of repeated CDRs, the text following the => shows what is returned.

(cdr '(pine fir oak maple))
     =>(fir oak maple)

(cdr '(fir oak maple))
     => (oak maple)

(cdr '(oak maple))
     =>(maple)

(cdr '(maple))
     => nil

(cdr 'nil)
     => nil

(cdr ())
     => nil

You can also do several CDRs without printing the values in between, like this:

(cdr (cdr '(pine fir oak maple)))
     => (oak maple)

In this example, the Lisp interpreter evaluates the innermost list first. The innermost list is quoted, so it just passes the list as it is to the innermost cdr. This cdr passes a list made up of the second and subsequent elements of the list to the outermost cdr, which produces a list composed of the third and subsequent elements of the original list. In this example, the cdr function is repeated and returns a list that consists of the original list without its first two elements.

The nthcdr function does the same as repeating the call to cdr. In the following example, the argument 2 is passed to the function nthcdr, along with the list, and the value returned is the list without its first two items, which is exactly the same as repeating cdr twice on the list:

(nthcdr 2 '(pine fir oak maple))
     => (oak maple)

Using the original four element list, we can see what happens when various numeric arguments are passed to nthcdr, including 0, 1, and 5:

;; Leave the list as it was.
(nthcdr 0 '(pine fir oak maple))
     => (pine fir oak maple)

;; Return a copy without the first element.
(nthcdr 1 '(pine fir oak maple))
     => (fir oak maple)

;; Return a copy of the list without three elements.
(nthcdr 3 '(pine fir oak maple))
     => (maple)

;; Return a copy lacking all four elements.
(nthcdr 4 '(pine fir oak maple))
     => nil

;; Return a copy lacking all elements.
(nthcdr 5 '(pine fir oak maple))
     => nil

Node:nth, Next:setcar, Previous:nthcdr, Up:car cdr & cons

7.4 nth

The nthcdr function takes the CDR of a list repeatedly. The nth function takes the CAR of the result returned by nthcdr. It returns the Nth element of the list.

Thus, if it were not defined in C for speed, the definition of nth would be:

(defun nth (n list)
  "Returns the Nth element of LIST.
N counts from zero.  If LIST is not that long, nil is returned."
  (car (nthcdr n list)))

(Originally, nth was defined in Emacs Lisp in subr.el, but its definition was redone in C in the 1980s.)

The nth function returns a single element of a list. This can be very convenient.

Note that the elements are numbered from zero, not one. That is to say, the first element of a list, its CAR is the zeroth element. This is called `zero-based' counting and often bothers people who are accustomed to the first element in a list being number one, which is `one-based'.

For example:

(nth 0 '("one" "two" "three"))
    => "one"

(nth 1 '("one" "two" "three"))
    => "two"

It is worth mentioning that nth, like nthcdr and cdr, does not change the original list--the function is non-destructive. This is in sharp contrast to the setcar and setcdr functions.

Node:setcar, Next:setcdr, Previous:nth, Up:car cdr & cons

7.5 setcar

As you might guess from their names, the setcar and setcdr functions set the CAR or the CDR of a list to a new value. They actually change the original list, unlike car and cdr which leave the original list as it was. One way to find out how this works is to experiment. We will start with the setcar function.

First, we can make a list and then set the value of a variable to the list, using the setq function. Here is a list of animals:

(setq animals '(antelope giraffe lion tiger))

If you are reading this in Info inside of GNU Emacs, you can evaluate this expression in the usual fashion, by positioning the cursor after the expression and typing C-x C-e. (I'm doing this right here as I write this. This is one of the advantages of having the interpreter built into the computing environment.)

When we evaluate the variable animals, we see that it is bound to the list (antelope giraffe lion tiger):

animals
     => (antelope giraffe lion tiger)

Put another way, the variable animals points to the list (antelope giraffe lion tiger).

Next, evaluate the function setcar while passing it two arguments, the variable animals and the quoted symbol hippopotamus; this is done by writing the three element list (setcar animals 'hippopotamus) and then evaluating it in the usual fashion:

(setcar animals 'hippopotamus)

After evaluating this expression, evaluate the variable animals again. You will see that the list of animals has changed:

animals
     => (hippopotamus giraffe lion tiger)

The first element on the list, antelope is replaced by hippopotamus.

So we can see that setcar did not add a new element to the list as cons would have; it replaced giraffe with hippopotamus; it changed the list.

Node:setcdr, Next:cons Exercise, Previous:setcar, Up:car cdr & cons

7.6 setcdr

The setcdr function is similar to the setcar function, except that the function replaces the second and subsequent elements of a list rather than the first element.

To see how this works, set the value of the variable to a list of domesticated animals by evaluating the following expression:

(setq domesticated-animals '(horse cow sheep goat))

If you now evaluate the list, you will be returned the list (horse cow sheep goat):

domesticated-animals
     => (horse cow sheep goat)

Next, evaluate setcdr with two arguments, the name of the variable which has a list as its value, and the list to which the CDR of the first list will be set;

(setcdr domesticated-animals '(cat dog))

If you evaluate this expression, the list (cat dog) will appear in the echo area. This is the value returned by the function. The result we are interested in is the "side effect", which we can see by evaluating the variable domesticated-animals:

domesticated-animals
     => (horse cat dog)

Indeed, the list is changed from (horse cow sheep goat) to (horse cat dog). The CDR of the list is changed from (cow sheep goat) to (cat dog).

Node:cons Exercise, Previous:setcdr, Up:car cdr & cons

7.7 Exercise

Construct a list of four birds by evaluating several expressions with cons. Find out what happens when you cons a list onto itself. Replace the first element of the list of four birds with a fish. Replace the rest of that list with a list of other fish.

Node:Cutting & Storing Text, Next:List Implementation, Previous:car cdr & cons, Up:Top

8 Cutting and Storing Text

Whenever you cut or clip text out of a buffer with a `kill' command in GNU Emacs, it is stored in a list and you can bring it back with a `yank' command.

(The use of the word `kill' in Emacs for processes which specifically do not destroy the values of the entities is an unfortunate historical accident. A much more appropriate word would be `clip' since that is what the kill commands do; they clip text out of a buffer and put it into storage from which it can be brought back. I have often been tempted to replace globally all occurrences of `kill' in the Emacs sources with `clip' and all occurrences of `killed' with `clipped'.)

  • Storing Text: Text is stored in a list.
  • zap-to-char: Cutting out text up to a character.
  • kill-region: Cutting text out of a region.
  • Digression into C: Minor note on C programming language macros.
  • defvar: How to give a variable an initial value.
  • copy-region-as-kill: A definition for copying text.
  • cons & search-fwd Review:
  • search Exercises:

Node:Storing Text, Next:zap-to-char, Previous:Cutting & Storing Text, Up:Cutting & Storing Text

Storing Text in a List

When text is cut out of a buffer, it is stored on a list. Successive pieces of text are stored on the list successively, so the list might look like this:

("a piece of text" "previous piece")

The function cons can be used to add a piece of text to the list, like this:

(cons "another piece"
      '("a piece of text" "previous piece"))

If you evaluate this expression, a list of three elements will appear in the echo area:

("another piece" "a piece of text" "previous piece")

With the car and nthcdr functions, you can retrieve whichever piece of text you want. For example, in the following code, nthcdr 1 ... returns the list with the first item removed; and the car returns the first element of that remainder--the second element of the original list:

(car (nthcdr 1 '("another piece"
                 "a piece of text"
                 "previous piece")))
     => "a piece of text"

The actual functions in Emacs are more complex than this, of course. The code for cutting and retrieving text has to be written so that Emacs can figure out which element in the list you want--the first, second, third, or whatever. In addition, when you get to the end of the list, Emacs should give you the first element of the list, rather than nothing at all.

The list that holds the pieces of text is called the kill ring. This chapter leads up to a description of the kill ring and how it is used by first tracing how the zap-to-char function works. This function uses (or `calls') a function that invokes a function that manipulates the kill ring. Thus, before reaching the mountains, we climb the foothills.

A subsequent chapter describes how text that is cut from the buffer is retrieved. See Yanking Text Back.

Node:zap-to-char, Next:kill-region, Previous:Storing Text, Up:Cutting & Storing Text

8.1 zap-to-char

The zap-to-char function barely changed between GNU Emacs version 19 and GNU Emacs version 21. However, zap-to-char calls another function, kill-region, which enjoyed a major rewrite on the way to version 21.

The kill-region function in Emacs 19 is complex, but does not use code that is important at this time. We will skip it.

The kill-region function in Emacs 21 is easier to read than the same function in Emacs 19 and introduces a very important concept, that of error handling. We will walk through the function.

But first, let us look at the interactive zap-to-char function.

  • Complete zap-to-char: The complete implementation.
  • zap-to-char interactive: A three part interactive expression.
  • zap-to-char body: A short overview.
  • search-forward: How to search for a string.
  • progn: The progn special form.
  • Summing up zap-to-char: Using point and search-forward.

Node:Complete zap-to-char, Next:zap-to-char interactive, Previous:zap-to-char, Up:zap-to-char

The Complete zap-to-char Implementation

The GNU Emacs version 19 and version 21 implementations of the zap-to-char function are nearly identical in form, and they work alike. The function removes the text in the region between the location of the cursor (i.e., of point) up to and including the next occurrence of a specified character. The text that zap-to-char removes is put in the kill ring; and it can be retrieved from the kill ring by typing C-y (yank). If the command is given an argument, it removes text through that number of occurrences. Thus, if the cursor were at the beginning of this sentence and the character were s, Thus would be removed. If the argument were two, Thus, if the curs would be removed, up to and including the s in cursor.

If the specified character is not found, zap-to-char will say "Search failed", tell you the character you typed, and not remove any text.

In order to determine how much text to remove, zap-to-char uses a search function. Searches are used extensively in code that manipulates text, and we will focus attention on them as well as on the deletion command.

Here is the complete text of the version 19 implementation of the function:

(defun zap-to-char (arg char)  ; version 19 implementation
  "Kill up to and including ARG'th occurrence of CHAR.
Goes backward if ARG is negative; error if CHAR not found."
  (interactive "*p\ncZap to char: ")
  (kill-region (point)
               (progn
                 (search-forward
                  (char-to-string char) nil nil arg)
                 (point))))

Node:zap-to-char interactive, Next:zap-to-char body, Previous:Complete zap-to-char, Up:zap-to-char

8.1.1 The interactive Expression

The interactive expression in the zap-to-char command looks like this:

(interactive "*p\ncZap to char: ")

The part within quotation marks, "*p\ncZap to char: ", specifies three different things. First, and most simply, the asterisk, *, causes an error to be signalled if the buffer is read-only. This means that if you try zap-to-char in a read-only buffer you will not be able to remove text, and you will receive a message that says "Buffer is read-only"; your terminal may beep at you as well.

The version 21 implementation does not have the asterisk, *. The function works the same as in version 19: in both cases, it cannot remove text from a read-only buffer but the function does copy the text that would have been removed to the kill ring. Also, in both cases, you see an error message.

However, the version 19 implementation copies text from a read-only buffer only because of a mistake in the implementation of interactive. According to the documentation for interactive, the asterisk, *, should prevent the zap-to-char function from doing anything at all when the buffer is read only. The function should not copy the text to the kill ring. It is a bug that it does.

In version 21, interactive is implemented correctly. So the asterisk, *, had to be removed from the interactive specification. If you insert an * and evaluate the function definition, then the next time you run the zap-to-char function on a read-only buffer, you will not copy any text.

That change aside, and a change to the documentation, the two versions of the zap-to-char function are identical.

Let us continue with the interactive specification.

The second part of "*p\ncZap to char: " is the p. This part is separated from the next part by a newline, \n. The p means that the first argument to the function will be passed the value of a `processed prefix'. The prefix argument is passed by typing C-u and a number, or M- and a number. If the function is called interactively without a prefix, 1 is passed to this argument.

The third part of "*p\ncZap to char: " is cZap to char: . In this part, the lower case c indicates that interactive expects a prompt and that the argument will be a character. The prompt follows the c and is the string Zap to char: (with a space after the colon to make it look good).

What all this does is prepare the arguments to zap-to-char so they are of the right type, and give the user a prompt.

Node:zap-to-char body, Next:search-forward, Previous:zap-to-char interactive, Up:zap-to-char

8.1.2 The Body of zap-to-char

The body of the zap-to-char function contains the code that kills (that is, removes) the text in the region from the current position of the cursor up to and including the specified character. The first part of the code looks like this:

(kill-region (point) ...

(point) is the current position of the cursor.

The next part of the code is an expression using progn. The body of the progn consists of calls to search-forward and point.

It is easier to understand how progn works after learning about search-forward, so we will look at search-forward and then at progn.

Node:search-forward, Next:progn, Previous:zap-to-char body, Up:zap-to-char

8.1.3 The search-forward Function

The search-forward function is used to locate the zapped-for-character in zap-to-char. If the search is successful, search-forward leaves point immediately after the last character in the target string. (In zap-to-char, the target string is just one character long.) If the search is backwards, search-forward leaves point just before the first character in the target. Also, search-forward returns t for true. (Moving point is therefore a `side effect'.)

In zap-to-char, the search-forward function looks like this:

(search-forward (char-to-string char) nil nil arg)

The search-forward function takes four arguments:

  1. The first argument is the target, what is searched for. This must be a string, such as "z".

    As it happens, the argument passed to zap-to-char is a single character. Because of the way computers are built, the Lisp interpreter may treat a single character as being different from a string of characters. Inside the computer, a single character has a different electronic format than a string of one character. (A single character can often be recorded in the computer using exactly one byte; but a string may be longer, and the computer needs to be ready for this.) Since the search-forward function searches for a string, the character that the zap-to-char function receives as its argument must be converted inside the computer from one format to the other; otherwise the search-forward function will fail. The char-to-string function is used to make this conversion.

  2. The second argument bounds the search; it is specified as a position in the buffer. In this case, the search can go to the end of the buffer, so no bound is set and the second argument is nil.
  3. The third argument tells the function what it should do if the search fails--it can signal an error (and print a message) or it can return nil. A nil as the third argument causes the function to signal an error when the search fails.
  4. The fourth argument to search-forward is the repeat count--how many occurrences of the string to look for. This argument is optional and if the function is called without a repeat count, this argument is passed the value 1. If this argument is negative, the search goes backwards.

In template form, a search-forward expression looks like this:

(search-forward "target-string"
                limit-of-search
                what-to-do-if-search-fails
                repeat-count)

We will look at progn next.

Node:progn, Next:Summing up zap-to-char, Previous:search-forward, Up:zap-to-char

8.1.4 The progn Special Form

progn is a special form that causes each of its arguments to be evaluated in sequence and then returns the value of the last one. The preceding expressions are evaluated only for the side effects they perform. The values produced by them are discarded.

The template for a progn expression is very simple:

(progn
  body...)

In zap-to-char, the progn expression has to do two things: put point in exactly the right position; and return the location of point so that kill-region will know how far to kill to.

The first argument to the progn is search-forward. When search-forward finds the string, the function leaves point immediately after the last character in the target string. (In this case the target string is just one character long.) If the search is backwards, search-forward leaves point just before the first character in the target. The movement of point is a side effect.

The second and last argument to progn is the expression (point). This expression returns the value of point, which in this case will be the location to which it has been moved by search-forward. This value is returned by the progn expression and is passed to kill-region as kill-region's second argument.

Node:Summing up zap-to-char, Previous:progn, Up:zap-to-char

8.1.5 Summing up zap-to-char

Now that we have seen how search-forward and progn work, we can see how the zap-to-char function works as a whole.

The first argument to kill-region is the position of the cursor when the zap-to-char command is given--the value of point at that time. Within the progn, the search function then moves point to just after the zapped-to-character and point returns the value of this location. The kill-region function puts together these two values of point, the first one as the beginning of the region and the second one as the end of the region, and removes the region.

The progn special form is necessary because the kill-region command takes two arguments; and it would fail if search-forward and point expressions were written in sequence as two additional arguments. The progn expression is a single argument to kill-region and returns the one value that kill-region needs for its second argument.

Node:kill-region, Next:Digression into C, Previous:zap-to-char, Up:Cutting & Storing Text

8.2 kill-region

The zap-to-char function uses the kill-region function. This function clips text from a region and copies that text to the kill ring, from which it may be retrieved.

The Emacs 21 version of that function uses condition-case and copy-region-as-kill, both of which we will explain. condition-case is an important special form.

In essence, the kill-region function calls condition-case, which takes three arguments. In this function, the first argument does nothing. The second argument contains the code that does the work when all goes well. The third argument contains the code that is called in the event of an error.

  • Complete kill-region: The function definition.
  • condition-case: Dealing with a problem.
  • delete-and-extract-region: Doing the work.

Node:Complete kill-region, Next:condition-case, Previous:kill-region, Up:kill-region

The Complete kill-region Definition

We will go through the condition-case code in a moment. First, let us look at the complete definition of kill-region, with comments added:

(defun kill-region (beg end)
  "Kill between point and mark.
The text is deleted but saved in the kill ring."
  (interactive "r")

  ;; 1. `condition-case' takes three arguments.
  ;;    If the first argument is nil, as it is here,
  ;;    information about the error signal is not
  ;;    stored for use by another function.
  (condition-case nil

      ;; 2. The second argument to `condition-case'
      ;;    tells the Lisp interpreter what to do when all goes well.

      ;;    The `delete-and-extract-region' function usually does the
      ;;    work.  If the beginning and ending of the region are both
      ;;    the same, then the variable `string' will be empty, or nil
      (let ((string (delete-and-extract-region beg end)))

        ;; `when' is an `if' clause that cannot take an `else-part'.
        ;; Emacs normally sets the value of `last-command' to the
        ;; previous command.
        ;; `kill-append' concatenates the new string and the old.
        ;; `kill-new' inserts text into a new item in the kill ring.
        (when string
          (if (eq last-command 'kill-region)
              ;; if true, prepend string
              (kill-append string (< end beg))
            (kill-new string)))
        (setq this-command 'kill-region))

    ;; 3. The third argument to `condition-case' tells the interpreter
    ;;    what to do with an error.
    ;;    The third argument has a conditions part and a body part.
    ;;    If the conditions are met (in this case,
    ;;             if text or buffer is read-only)
    ;;    then the body is executed.
    ((buffer-read-only text-read-only) ;; this is the if-part
     ;; then...
     (copy-region-as-kill beg end)
     (if kill-read-only-ok            ;; usually this variable is nil
         (message "Read only text copied to kill ring")
       ;; or else, signal an error if the buffer is read-only;
       (barf-if-buffer-read-only)
       ;; and, in any case, signal that the text is read-only.
       (signal 'text-read-only (list (current-buffer)))))))

Node:condition-case, Next:delete-and-extract-region, Previous:Complete kill-region, Up:kill-region

8.2.1 condition-case

As we have seen earlier (see Generate an Error Message), when the Emacs Lisp interpreter has trouble evaluating an expression, it provides you with help; in the jargon, this is called "signaling an error". Usually, the computer stops the program and shows you a message.

However, some programs undertake complicated actions. They should not simply stop on an error. In the kill-region function, the most likely error is that you will try to kill text that is read-only and cannot be removed. So the kill-region function contains code to handle this circumstance. This code, which makes up the body of the kill-region function, is inside of a condition-case special form.

The template for condition-case looks like this:

(condition-case
  var
  bodyform
  error-handler...)

The second argument, bodyform, is straightforward. The condition-case special form causes the Lisp interpreter to evaluate the code in bodyform. If no error occurs, the special form returns the code's value and produces the side-effects, if any.

In short, the bodyform part of a condition-case expression determines what should happen when everything works correctly.

However, if an error occurs, among its other actions, the function generating the error signal will define one or more error condition names.

An error handler is the third argument to condition case. An error handler has two parts, a condition-name and a body. If the condition-name part of an error handler matches a condition name generated by an error, then the body part of the error handler is run.

As you will expect, the condition-name part of an error handler may be either a single condition name or a list of condition names.

Also, a complete condition-case expression may contain more than one error handler. When an error occurs, the first applicable handler is run.

Lastly, the first argument to the condition-case expression, the var argument, is sometimes bound to a variable that contains information about the error. However, if that argument is nil, as is the case in kill-region, that information is discarded.

In brief, in the kill-region function, the code condition-case works like this:

If no errors, run only this code
    but, if errors, run this other code.

Node:delete-and-extract-region, Previous:condition-case, Up:kill-region

8.2.2 delete-and-extract-region

A condition-case expression has two parts, a part that is evaluated in the expectation that all will go well, but which may generate an error; and a part that is evaluated when there is an error.

First, let us look at the code in kill-region that is run in the expectation that all goes well. This is the core of the function. The code looks like this:

(let ((string (delete-and-extract-region beg end)))
  (when string
    (if (eq last-command 'kill-region)
        (kill-append string (< end beg))
      (kill-new string)))
  (setq this-command 'kill-region))

It looks complicated because we have the new functions delete-and-extract-region, kill-append, and kill-new as well as the new variables, last-command and this-command.

The delete-and-extract-region function is straightforward. It is a built-in function that deletes the text in a region (a side effect) and also returns that text. This is the function that actually removes the text. (And if it cannot do that, it signals the error.)

In this let expression, the text that delete-and-extract-region returns is placed in the local variable called string. This is the text that is removed from the buffer. (To be more precise, the variable is set to point to the address of the extracted text; to say it is `placed in' the variable is simply a shorthand.)

If the variable string does point to text, that text is added to the kill ring. The variable will have a nil value if no text was removed.

The code uses when to determine whether the variable string points to text. A when statement is simply a programmers' convenience. A when statement is an if statement without the possibility of an else clause. In your mind, you can replace when with if and understand what goes on. That is what the Lisp interpreter does.

Technically speaking, when is a Lisp macro. A Lisp macro enables you to define new control constructs and other language features. It tells the interpreter how to compute another Lisp expression which will in turn compute the value. In this case, the `other expression' is an if expression. For more about Lisp macros, see Macros. The C programming language also provides macros. These are different, but also useful. We will briefly look at C macros in delete-and-extract-region: Digressing into C.

If the string has content, then another conditional expression is executed. This is an if with both a then-part and an else-part.

(if (eq last-command 'kill-region)
    (kill-append string (< end beg))
  (kill-new string)))

The then-part is evaluated if the previous command was another call to kill-region; if not, the else-part is evaluated.

last-command is a variable that comes with Emacs that we have not seen before. Normally, whenever a function is executed, Emacs sets the value of last-command to the previous command.

In this segment of the definition, the if expression checks whether the previous command was kill-region. If it was,

(kill-append string (< end beg))

concatenates a copy of the newly clipped text to the just previously clipped text in the kill ring. (If the (< end beg)) expression is true, kill-append prepends the string to the just previously clipped text. For a detailed discussion, see The kill-append function.)

If you then yank back the text, i.e., `paste' it, you get both pieces of text at once. That way, if you delete two words in a row, and then yank them back, you get both words, in their proper order, with one yank. (The (< end beg)) expression makes sure the order is correct.)

On the other hand, if the previous command is not kill-region, then the kill-new function is called, which adds the text to the kill ring as the latest item, and sets the kill-ring-yank-pointer variable to point to it.

Node:Digression into C, Next:defvar, Previous:kill-region, Up:Cutting & Storing Text

8.3 delete-and-extract-region: Digressing into C

The zap-to-char command uses the delete-and-extract-region function, which in turn uses two other functions, copy-region-as-kill and del_range_1. The copy-region-as-kill function will be described in a following section; it puts a copy of the region in the kill ring so it can be yanked back. (See copy-region-as-kill.)

The delete-and-extract-region function removes the contents of a region and you cannot get them back.

Unlike the other code discussed here, delete-and-extract-region is not written in Emacs Lisp; it is written in C and is one of the primitives of the GNU Emacs system. Since it is very simple, I will digress briefly from Lisp and describe it here.

Like many of the other Emacs primitives, delete-and-extract-region is written as an instance of a C macro, a macro being a template for code. The complete macro looks like this:

DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
       Sdelete_and_extract_region, 2, 2, 0,
  "Delete the text between START and END and return it.")
  (start, end)
     Lisp_Object start, end;
{
  validate_region (&start, &end);
  return del_range_1 (XINT (start), XINT (end), 1, 1);
}

Without going into the details of the macro writing process, let me point out that this macro starts with the word DEFUN. The word DEFUN was chosen since the code serves the same purpose as defun does in Lisp. The word DEFUN is followed by seven parts inside of parentheses:

  • The first part is the name given to the function in Lisp, delete-and-extract-region.
  • The second part is the name of the function in C, Fdelete_and_extract_region. By convention, it starts with F. Since C does not use hyphens in names, underscores are used instead.
  • The third part is the name for the C constant structure that records information on this function for internal use. It is the name of the function in C but begins with an S instead of an F.
  • The fourth and fifth parts specify the minimum and maximum number of arguments the function can have. This function demands exactly 2 arguments.
  • The sixth part is nearly like the argument that follows the interactive declaration in a function written in Lisp: a letter followed, perhaps, by a prompt. The only difference from the Lisp is when the macro is called with no arguments. Then you write a 0 (which is a `null string'), as in this macro.

    If you were to specify arguments, you would place them between quotation marks. The C macro for goto-char includes "NGoto char: " in this position to indicate that the function expects a raw prefix, in this case, a numerical location in a buffer, and provides a prompt.

  • The seventh part is a documentation string, just like the one for a function written in Emacs Lisp, except that every newline must be written explicitly as \n followed by a backslash and carriage return.

    Thus, the first two lines of documentation for goto-char are written like this:

      "Set point to POSITION, a number or marker.\n\
Beginning of buffer is position (point-min), end is (point-max).

In a C macro, the formal parameters come next, with a statement of what kind of object they are, followed by what might be called the `body' of the macro. For delete-and-extract-region the `body' consists of the following two lines:

validate_region (&start, &end);
return del_range_1 (XINT (start), XINT (end), 1, 1);

The first function, validate_region checks whether the values passed as the beginning and end of the region are the proper type and are within range. The second function, del_range_1, actually deletes the text.

del_range_1 is a complex function we will not look into. It updates the buffer and does other things.

However, it is worth looking at the two arguments passed to del_range. These are XINT (start) and XINT (end).

As far as the C language is concerned, start and end are two integers that mark the beginning and end of the region to be deleted7.

In early versions of Emacs, these two numbers were thirty-two bits long, but the code is slowly being generalized to handle other lengths. Three of the available bits are used to specify the type of information and a fourth bit is used for handling the computer's memory; the remaining bits are used as `content'.

XINT is a C macro that extracts the relevant number from the longer collection of bits; the four other bits are discarded.

The command in delete-and-extract-region looks like this:

del_range_1 (XINT (start), XINT (end), 1, 1);

It deletes the region between the beginning position, start, and the ending position, end.

From the point of view of the person writing Lisp, Emacs is all very simple; but hidden underneath is a great deal of complexity to make it all work.

Node:defvar, Next:copy-region-as-kill, Previous:Digression into C, Up:Cutting & Storing Text

8.4 Initializing a Variable with defvar

Unlike the delete-and-extract-region function, the copy-region-as-kill function is written in Emacs Lisp. Two functions within it, kill-append and kill-new, copy a region in a buffer and save it in a variable called the kill-ring. This section describes how the kill-ring variable is created and initialized using the defvar special form.

(Again we note that the term kill-ring is a misnomer. The text that is clipped out of the buffer can be brought back; it is not a ring of corpses, but a ring of resurrectable text.)

In Emacs Lisp, a variable such as the kill-ring is created and given an initial value by using the defvar special form. The name comes from "define variable".

The defvar special form is similar to setq in that it sets the value of a variable. It is unlike setq in two ways: first, it only sets the value of the variable if the variable does not already have a value. If the variable already has a value, defvar does not override the existing value. Second, defvar has a documentation string.

(Another special form, defcustom, is designed for variables that people customize. It has more features than defvar. (See Setting Variables with defcustom.)

  • See variable current value:
  • defvar and asterisk: An old-time convention.

Node:See variable current value, Next:defvar and asterisk, Previous:defvar, Up:defvar

Seeing the Current Value of a Variable

You can see the current value of a variable, any variable, by using the describe-variable function, which is usually invoked by typing C-h v. If you type C-h v and then kill-ring (followed by <RET>) when prompted, you will see what is in your current kill ring--this may be quite a lot! Conversely, if you have been doing nothing this Emacs session except read this document, you may have nothing in it. Also, you will see the documentation for kill-ring:

Documentation:
List of killed text sequences.
Since the kill ring is supposed to interact nicely with cut-and-paste
facilities offered by window systems, use of this variable should
interact nicely with `interprogram-cut-function' and
`interprogram-paste-function'.  The functions `kill-new',
`kill-append', and `current-kill' are supposed to implement this
interaction; you may want to use them instead of manipulating the kill
ring directly.

The kill ring is defined by a defvar in the following way:

(defvar kill-ring nil
  "List of killed text sequences.
...")

In this variable definition, the variable is given an initial value of nil, which makes sense, since if you have saved nothing, you want nothing back if you give a yank command. The documentation string is written just like the documentation string of a defun. As with the documentation string of the defun, the first line of the documentation should be a complete sentence, since some commands, like apropos, print only the first line of documentation. Succeeding lines should not be indented; otherwise they look odd when you use C-h v (describe-variable).

Node:defvar and asterisk, Previous:See variable current value, Up:defvar

8.4.1 defvar and an asterisk

In the past, Emacs used the defvar special form both for internal variables that you would not expect a user to change and for variables that you do expect a user to change. Although you can still use defvar for user customizable variables, please use defcustom instead, since that special form provides a path into the Customization commands. (See Setting Variables with defcustom.)

When you specified a variable using the defvar special form, you could distinguish a readily settable variable from others by typing an asterisk, *, in the first column of its documentation string. For example:

(defvar shell-command-default-error-buffer nil
  "*Buffer name for `shell-command' ... error output.
... ")

This means that you could (and still can) use the edit-options command to change the value of shell-command-default-error-buffer temporarily.

However, options set using edit-options are set only for the duration of your editing session. The new values are not saved between sessions. Each time Emacs starts, it reads the original value, unless you change the value within your .emacs file, either by setting it manually or by using customize. See Your .emacs File.

For me, the major use of the edit-options command is to suggest variables that I might want to set in my .emacs file. I urge you to look through the list. (See Edit Options.)

Node:copy-region-as-kill, Next:cons & search-fwd Review, Previous:defvar, Up:Cutting & Storing Text

8.5 copy-region-as-kill

The copy-region-as-kill function copies a region of text from a buffer and (via either kill-append or kill-new) saves it in the kill-ring.

If you call copy-region-as-kill immediately after a kill-region command, Emacs appends the newly copied text to the previously copied text. This means that if you yank back the text, you get it all, from both this and the previous operation. On the other hand, if some other command precedes the copy-region-as-kill, the function copies the text into a separate entry in the kill ring.

  • Complete copy-region-as-kill: The complete function definition.
  • copy-region-as-kill body: The body of copy-region-as-kill.

Node:Complete copy-region-as-kill, Next:copy-region-as-kill body, Previous:copy-region-as-kill, Up:copy-region-as-kill

The complete copy-region-as-kill function definition

Here is the complete text of the version 21 copy-region-as-kill function:

(defun copy-region-as-kill (beg end)
  "Save the region as if killed, but don't kill it.
In Transient Mark mode, deactivate the mark.
If `interprogram-cut-function' is non-nil, also save
the text for a window system cut and paste."
  (interactive "r")
  (if (eq last-command 'kill-region)
      (kill-append (buffer-substring beg end) (< end beg))
    (kill-new (buffer-substring beg end)))
  (if transient-mark-mode
      (setq deactivate-mark t))
  nil)

As usual, this function can be divided into its component parts:

(defun copy-region-as-kill (argument-list)
  "documentation..."
  (interactive "r")
  body...)

The arguments are beg and end and the function is interactive with "r", so the two arguments must refer to the beginning and end of the region. If you have been reading though this document from the beginning, understanding these parts of a function is almost becoming routine.

The documentation is somewhat confusing unless you remember that the word `kill' has a meaning different from its usual meaning. The `Transient Mark' and interprogram-cut-function comments explain certain side-effects.

After you once set a mark, a buffer always contains a region. If you wish, you can use Transient Mark mode to highlight the region temporarily. (No one wants to highlight the region all the time, so Transient Mark mode highlights it only at appropriate times. Many people turn off Transient Mark mode, so the region is never highlighted.)

Also, a windowing system allows you to copy, cut, and paste among different programs. In the X windowing system, for example, the interprogram-cut-function function is x-select-text, which works with the windowing system's equivalent of the Emacs kill ring.

The body of the copy-region-as-kill function starts with an if clause. What this clause does is distinguish between two different situations: whether or not this command is executed immediately after a previous kill-region command. In the first case, the new region is appended to the previously copied text. Otherwise, it is inserted into the beginning of the kill ring as a separate piece of text from the previous piece.

The last two lines of the function prevent the region from lighting up if Transient Mark mode is turned on.

The body of copy-region-as-kill merits discussion in detail.

Node:copy-region-as-kill body, Previous:Complete copy-region-as-kill, Up:copy-region-as-kill

8.5.1 The Body of copy-region-as-kill

The copy-region-as-kill function works in much the same way as the kill-region function (see kill-region). Both are written so that two or more kills in a row combine their text into a single entry. If you yank back the text from the kill ring, you get it all in one piece. Moreover, kills that kill forward from the current position of the cursor are added to the end of the previously copied text and commands that copy text backwards add it to the beginning of the previously copied text. This way, the words in the text stay in the proper order.

Like kill-region, the copy-region-as-kill function makes use of the last-command variable that keeps track of the previous Emacs command.

  • last-command & this-command:
  • kill-append function:
  • kill-new function:

Node:last-command & this-command, Next:kill-append function, Previous:copy-region-as-kill body, Up:copy-region-as-kill body

last-command and this-command

Normally, whenever a function is executed, Emacs sets the value of this-command to the function being executed (which in this case would be copy-region-as-kill). At the same time, Emacs sets the value of last-command to the previous value of this-command.

In the first part of the body of the copy-region-as-kill function, an if expression determines whether the value of last-command is kill-region. If so, the then-part of the if expression is evaluated; it uses the kill-append function to concatenate the text copied at this call to the function with the text already in the first element (the CAR) of the kill ring. On the other hand, if the value of last-command is not kill-region, then the copy-region-as-kill function attaches a new element to the kill ring using the kill-new function.

The if expression reads as follows; it uses eq, which is a function we have not yet seen:

  (if (eq last-command 'kill-region)
      ;; then-part
      (kill-append (buffer-substring beg end) (< end beg))
    ;; else-part
    (kill-new (buffer-substring beg end)))

The eq function tests whether its first argument is the same Lisp object as its second argument. The eq function is similar to the equal function in that it is used to test for equality, but differs in that it determines whether two representations are actually the same object inside the computer, but with different names. equal determines whether the structure and contents of two expressions are the same.

If the previous command was kill-region, then the Emacs Lisp interpreter calls the kill-append function

Node:kill-append function, Next:kill-new function, Previous:last-command & this-command, Up:copy-region-as-kill body

The kill-append function

The kill-append function looks like this:

(defun kill-append (string before-p)
  "Append STRING to the end of the latest kill in the kill ring.
If BEFORE-P is non-nil, prepend STRING to the kill.
If `interprogram-cut-function' is set, pass the resulting kill to
it."
  (kill-new (if before-p
                (concat string (car kill-ring))
              (concat (car kill-ring) string))
            t))

The kill-append function is fairly straightforward. It uses the kill-new function, which we will discuss in more detail in a moment.

First, let us look at the conditional that is one of the two arguments to kill-new. It uses concat to concatenate the new text to the CAR of the kill ring. Whether it prepends or appends the text depends on the results of an if expression:

(if before-p                            ; if-part
    (concat string (car kill-ring))     ; then-part
  (concat (car kill-ring) string))      ; else-part

If the region being killed is before the region that was killed in the last command, then it should be prepended before the material that was saved in the previous kill; and conversely, if the killed text follows what was just killed, it should be appended after the previous text. The if expression depends on the predicate before-p to decide whether the newly saved text should be put before or after the previously saved text.

The symbol before-p is the name of one of the arguments to kill-append. When the kill-append function is evaluated, it is bound to the value returned by evaluating the actual argument. In this case, this is the expression (< end beg). This expression does not directly determine whether the killed text in this command is located before or after the kill text of the last command; what is does is determine whether the value of the variable end is less than the value of the variable beg. If it is, it means that the user is most likely heading towards the beginning of the buffer. Also, the result of evaluating the predicate expression, (< end beg), will be true and the text will be prepended before the previous text. On the other hand, if the value of the variable end is greater than the value of the variable beg, the text will be appended after the previous text.

When the newly saved text will be prepended, then the string with the new text will be concatenated before the old text:

(concat string (car kill-ring))

But if the text will be appended, it will be concatenated after the old text:

(concat (car kill-ring) string))

To understand how this works, we first need to review the concat function. The concat function links together or unites two strings of text. The result is a string. For example:

(concat "abc" "def")
     => "abcdef"

(concat "new "
        (car '("first element" "second element")))
     => "new first element"

(concat (car
        '("first element" "second element")) " modified")
     => "first element modified"

We can now make sense of kill-append: it modifies the contents of the kill ring. The kill ring is a list, each element of which is saved text. The kill-append function uses the kill-new function which in turn uses the setcar function.

Node:kill-new function, Previous:kill-append function, Up:copy-region-as-kill body

The kill-new function

The kill-new function looks like this:

(defun kill-new (string &optional replace)
  "Make STRING the latest kill in the kill ring.
Set the kill-ring-yank pointer to point to it.
If `interprogram-cut-function' is non-nil, apply it to STRING.
Optional second argument REPLACE non-nil means that STRING will replace
the front of the kill ring, rather than being added to the list."
  (and (fboundp 'menu-bar-update-yank-menu)
       (menu-bar-update-yank-menu string (and replace (car kill-ring))))
  (if (and replace kill-ring)
      (setcar kill-ring string)
    (setq kill-ring (cons string kill-ring))
    (if (> (length kill-ring) kill-ring-max)
        (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
  (setq kill-ring-yank-pointer kill-ring)
  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))

As usual, we can look at this function in parts.

The first line of the documentation makes sense:

Make STRING the latest kill in the kill ring.

Let's skip over the rest of the documentation for the moment.

Also, let's skip over the first two lines of code, those involving menu-bar-update-yank-menu. We will explain them below.

The critical lines are these:

  (if (and replace kill-ring)
      ;; then
      (setcar kill-ring string)
    ;; else
    (setq kill-ring (cons string kill-ring))
    (if (> (length kill-ring) kill-ring-max)
        ;; avoid overly long kill ring
        (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
  (setq kill-ring-yank-pointer kill-ring)
  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))

The conditional test is (and replace kill-ring). This will be true when two conditions are met: the kill ring has something in it, and the replace variable is true.

The kill-append function sets replace to be true; then, when the kill ring has at least one item in it, the setcar expression is executed:

(setcar kill-ring string)

The setcar function actually changes the first element of the kill-ring list to the value of string. It replaces the first element.

On the other hand, if the kill ring is empty, or replace is false, the else-part of the condition is executed:

(setq kill-ring (cons string kill-ring))
(if (> (length kill-ring) kill-ring-max)
    (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))

This expression first constructs a new version of the kill ring by prepending string to the existing kill ring as a new element. Then it executes a second if clause. This second if clause keeps the kill ring from growing too long.

Let's look at these two expressions in order.

The setq line of the else-part sets the new value of the kill ring to what results from adding the string being killed to the old kill ring.

We can see how this works with an example:

(setq example-list '("here is a clause" "another clause"))

After evaluating this expression with C-x C-e, you can evaluate example-list and see what it returns:

example-list
     => ("here is a clause" "another clause")

Now, we can add a new element on to this list by evaluating the following expression:

(setq example-list (cons "a third clause" example-list))

When we evaluate example-list, we find its value is:

example-list
     => ("a third clause" "here is a clause" "another clause")

Thus, the third clause was added to the list by cons.

This is exactly similar to what the setq and cons do in the function. Here is the line again:

(setq kill-ring (cons string kill-ring))

Now for the second part of the if clause. This expression keeps the kill ring from growing too long. It looks like this:

(if (> (length kill-ring) kill-ring-max)
    (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))

The code checks whether the length of the kill ring is greater than the maximum permitted length. This is the value of kill-ring-max (which is 60, by default). If the length of the kill ring is too long, then this code sets the last element of the kill ring to nil. It does this by using two functions, nthcdr and setcdr.

We looked at setcdr earlier (see setcdr). It sets the CDR of a list, just as setcar sets the CAR of a list. In this case, however, setcdr will not be setting the CDR of the whole kill ring; the nthcdr function is used to cause it to set the CDR of the next to last element of the kill ring--this means that since the CDR of the next to last element is the last element of the kill ring, it will set the last element of the kill ring.

The nthcdr function works by repeatedly taking the CDR of a list--it takes the CDR of the CDR of the CDR ... It does this N times and returns the results.

Thus, if we had a four element list that was supposed to be three elements long, we could set the CDR of the next to last element to nil, and thereby shorten the list.

You can see this by evaluating the following three expressions in turn. First set the value of trees to (maple oak pine birch), then set the CDR of its second CDR to nil and then find the value of trees:

(setq trees '(maple oak pine birch))
     => (maple oak pine birch)

(setcdr (nthcdr 2 trees) nil)
     => nil

trees
     => (maple oak pine)

(The value returned by the setcdr expression is nil since that is what the CDR is set to.)

To repeat, in kill-new, the nthcdr function takes the CDR a number of times that is one less than the maximum permitted size of the kill ring and sets the CDR of that element (which will be the rest of the elements in the kill ring) to nil. This prevents the kill ring from growing too long.

The next to last expression in the kill-new function is

(setq kill-ring-yank-pointer kill-ring)

The kill-ring-yank-pointer is a global variable that is set to be the kill-ring.

Even though the kill-ring-yank-pointer is called a pointer, it is a variable just like the kill ring. However, the name has been chosen to help humans understand how the variable is used. The variable is used in functions such as yank and yank-pop (see Yanking Text Back).

Now, to return to the first two lines in the body of the function:

  (and (fboundp 'menu-bar-update-yank-menu)
       (menu-bar-update-yank-menu string (and replace (car kill-ring))))

This is an expression whose first element is the function and.

The and special form evaluates each of its arguments until one of the arguments returns a value of nil, in which case the and expression returns nil; however, if none of the arguments returns a value of nil, the value resulting from evaluating the last argument is returned. (Since such a value is not nil, it is considered true in Emacs Lisp.) In other words, an and expression returns a true value only if all its arguments are true.

In this case, the expression tests first to see whether menu-bar-update-yank-menu exists as a function, and if so, calls it. The fboundp function returns true if the symbol it is testing has a function definition that `is not void'. If the symbol's function definition were void, we would receive an error message, as we did when we created errors intentionally (see Generate an Error Message).

Essentially, the and is an if expression that reads like this:

if the-menu-bar-function-exists
  then execute-it

menu-bar-update-yank-menu is one of the functions that make it possible to use the `Select and Paste' menu in the Edit item of a menu bar; using a mouse, you can look at the various pieces of text you have saved and select one piece to paste.

Finally, the last expression in the kill-new function adds the newly copied string to whatever facility exists for copying and pasting among different programs running in a windowing system. In the X Windowing system, for example, the x-select-text function takes the string and stores it in memory operated by X. You can paste the string in another program, such as an Xterm.

The expression looks like this:

  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))

If an interprogram-cut-function exists, then Emacs executes funcall, which in turn calls its first argument as a function and passes the remaining arguments to it. (Incidentally, as far as I can see, this if expression could be replaced by an and expression similar to the one in the first part of the function.)

We are not going to discuss windowing systems and other programs further, but merely note that this is a mechanism that enables GNU Emacs to work easily and well with other programs.

This code for placing text in the kill ring, either concatenated with an existing element or as a new element, leads us to the code for bringing back text that has been cut out of the buffer--the yank commands. However, before discussing the yank commands, it is better to learn how lists are implemented in a computer. This will make clear such mysteries as the use of the term `pointer'.

Node:cons & search-fwd Review, Next:search Exercises, Previous:copy-region-as-kill, Up:Cutting & Storing Text

8.6 Review

Here is a brief summary of some recently introduced functions.

car
cdr
car returns the first element of a list; cdr returns the second and subsequent elements of a list.

For example:

(car '(1 2 3 4 5 6 7))
     => 1
(cdr '(1 2 3 4 5 6 7))
     => (2 3 4 5 6 7)

cons
cons constructs a list by prepending its first argument to its second argument.

For example:

(cons 1 '(2 3 4))
     => (1 2 3 4)

nthcdr
Return the result of taking CDR `n' times on a list. The `rest of the rest', as it were.

For example:

(nthcdr 3 '(1 2 3 4 5 6 7))
     => (4 5 6 7)

setcar
setcdr
setcar changes the first element of a list; setcdr changes the second and subsequent elements of a list.

For example:

(setq triple '(1 2 3))

(setcar triple '37)

triple
     => (37 2 3)

(setcdr triple '("foo" "bar"))

triple
     => (37 "foo" "bar")

progn
Evaluate each argument in sequence and then return the value of the last.

For example:

(progn 1 2 3 4)
     => 4

save-restriction
Record whatever narrowing is in effect in the current buffer, if any, and restore that narrowing after evaluating the arguments.
search-forward
Search for a string, and if the string is found, move point.

Takes four arguments:

  1. The string to search for.
  2. Optionally, the limit of the search.
  3. Optionally, what to do if the search fails, return nil or an error message.
  4. Optionally, how many times to repeat the search; if negative, the search goes backwards.

kill-region
delete-region
copy-region-as-kill
kill-region cuts the text between point and mark from the buffer and stores that text in the kill ring, so you can get it back by yanking.

delete-and-extract-region removes the text between point and mark from the buffer and throws it away. You cannot get it back.

copy-region-as-kill copies the text between point and mark into the kill ring, from which you can get it by yanking. The function does not cut or remove the text from the buffer.

Node:search Exercises, Previous:cons & search-fwd Review, Up:Cutting & Storing Text

8.7 Searching Exercises

  • Write an interactive function that searches for a string. If the search finds the string, leave point after it and display a message that says "Found!". (Do not use search-forward for the name of this function; if you do, you will overwrite the existing version of search-forward that comes with Emacs. Use a name such as test-search instead.)
  • Write a function that prints the third element of the kill ring in the echo area, if any; if the kill ring does not contain a third element, print an appropriate message.

Node:List Implementation, Next:Yanking, Previous:Cutting & Storing Text, Up:Top

9 How Lists are Implemented

In Lisp, atoms are recorded in a straightforward fashion; if the implementation is not straightforward in practice, it is, nonetheless, straightforward in theory. The atom rose, for example, is recorded as the four contiguous letters r, o, s, e. A list, on the other hand, is kept differently. The mechanism is equally simple, but it takes a moment to get used to the idea. A list is kept using a series of pairs of pointers. In the series, the first pointer in each pair points to an atom or to another list, and the second pointer in each pair points to the next pair, or to the symbol nil, which marks the end of the list.

A pointer itself is quite simply the electronic address of what is pointed to. Hence, a list is kept as a series of electronic addresses.

  • Lists diagrammed:
  • Symbols as Chest: Exploring a powerful metaphor.
  • List Exercise:

Node:Lists diagrammed, Next:Symbols as Chest, Previous:List Implementation, Up:List Implementation

Lists diagrammed

For example, the list (rose violet buttercup) has three elements, rose, violet, and buttercup. In the computer, the electronic address of rose is recorded in a segment of computer memory along with the address that gives the electronic address of where the atom violet is located; and that address (the one that tells where violet is located) is kept along with an address that tells where the address for the atom buttercup is located.

This sounds more complicated than it is and is easier seen in a diagram:

    ___ ___      ___ ___      ___ ___
   |___|___|--> |___|___|--> |___|___|--> nil
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup

In the diagram, each box represents a word of computer memory that holds a Lisp object, usually in the form of a memory address. The boxes, i.e. the addresses, are in pairs. Each arrow points to what the address is the address of, either an atom or another pair of addresses. The first box is the electronic address of rose and the arrow points to rose; the second box is the address of the next pair of boxes, the first part of which is the address of violet and the second part of which is the address of the next pair. The very last box points to the symbol nil, which marks the end of the list.

When a variable is set to a list with a function such as setq, it stores the address of the first box in the variable. Thus, evaluation of the expression

(setq bouquet '(rose violet buttercup))

creates a situation like this:

bouquet
     |
     |     ___ ___      ___ ___      ___ ___
      --> |___|___|--> |___|___|--> |___|___|--> nil
            |            |            |
            |            |            |
             --> rose     --> violet   --> buttercup

In this example, the symbol bouquet holds the address of the first pair of boxes.

This same list can be illustrated in a different sort of box notation like this:

bouquet
 |
 |    --------------       ---------------       ----------------
 |   | car   | cdr  |     | car    | cdr  |     | car     | cdr  |
  -->| rose  |   o------->| violet |   o------->| butter- |  nil |
     |       |      |     |        |      |     | cup     |      |
      --------------       ---------------       ----------------

(Symbols consist of more than pairs of addresses, but the structure of a symbol is made up of addresses. Indeed, the symbol bouquet consists of a group of address-boxes, one of which is the address of the printed word bouquet, a second of which is the address of a function definition attached to the symbol, if any, a third of which is the address of the first pair of address-boxes for the list (rose violet buttercup), and so on. Here we are showing that the symbol's third address-box points to the first pair of address-boxes for the list.)

If a symbol is set to the CDR of a list, the list itself is not changed; the symbol simply has an address further down the list. (In the jargon, CAR and CDR are `non-destructive'.) Thus, evaluation of the following expression

(setq flowers (cdr bouquet))

produces this:

bouquet        flowers
  |              |
  |     ___ ___  |     ___ ___      ___ ___
   --> |   |   |  --> |   |   |    |   |   |
       |___|___|----> |___|___|--> |___|___|--> nil
         |              |            |
         |              |            |
          --> rose       --> violet   --> buttercup

The value of flowers is (violet buttercup), which is to say, the symbol flowers holds the address of the pair of address-boxes, the first of which holds the address of violet, and the second of which holds the address of buttercup.

A pair of address-boxes is called a cons cell or dotted pair. See List Type, and Dotted Pair Notation, for more information about cons cells and dotted pairs.

The function cons adds a new pair of addresses to the front of a series of addresses like that shown above. For example, evaluating the expression

(setq bouquet (cons 'lily bouquet))

produces:

bouquet                       flowers
  |                             |
  |     ___ ___        ___ ___  |     ___ ___       ___ ___
   --> |   |   |      |   |   |  --> |   |   |     |   |   |
       |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
         |              |              |             |
         |              |              |             |
          --> lily      --> rose       --> violet    --> buttercup

However, this does not change the value of the symbol flowers, as you can see by evaluating the following,

(eq (cdr (cdr bouquet)) flowers)

which returns t for true.

Until it is reset, flowers still has the value (violet buttercup); that is, it has the address of the cons cell whose first address is of violet. Also, this does not alter any of the pre-existing cons cells; they are all still there.

Thus, in Lisp, to get the CDR of a list, you just get the address of the next cons cell in the series; to get the CAR of a list, you get the address of the first element of the list; to cons a new element on a list, you add a new cons cell to the front of the list. That is all there is to it! The underlying structure of Lisp is brilliantly simple!

And what does the last address in a series of cons cells refer to? It is the address of the empty list, of nil.

In summary, when a Lisp variable is set to a value, it is provided with the address of the list to which the variable refers.

Node:Symbols as Chest, Next:List Exercise, Previous:Lists diagrammed, Up:List Implementation

9.1 Symbols as a Chest of Drawers

In an earlier section, I suggested that you might imagine a symbol as being a chest of drawers. The function definition is put in one drawer, the value in another, and so on. What is put in the drawer holding the value can be changed without affecting the contents of the drawer holding the function definition, and vice-versa.

Actually, what is put in each drawer is the address of the value or function definition. It is as if you found an old chest in the attic, and in one of its drawers you found a map giving you directions to where the buried treasure lies.

(In addition to its name, symbol definition, and variable value, a symbol has a `drawer' for a property list which can be used to record other information. Property lists are not discussed here; see Property Lists.)

Here is a fanciful representation:

            Chest of Drawers            Contents of Drawers

            __   o0O0o   __
          /                 \
         ---------------------
        |    directions to    |            [map to]
        |     symbol name     |             bouquet
        |                     |
        +---------------------+
        |    directions to    |
        |  symbol definition  |             [none]
        |                     |
        +---------------------+
        |    directions to    |            [map to]
        |    variable value   |             (rose violet buttercup)
        |                     |
        +---------------------+
        |    directions to    |
        |    property list    |             [not described here]
        |                     |
        +---------------------+
        |/                   \|

Node:List Exercise, Previous:Symbols as Chest, Up:List Implementation

9.2 Exercise

Set flowers to violet and buttercup. Cons two more flowers on to this list and set this new list to more-flowers. Set the CAR of flowers to a fish. What does the more-flowers list now contain?

Node:Yanking, Next:Loops & Recursion, Previous:List Implementation, Up:Top

10 Yanking Text Back

Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, you can bring it back with a `yank' command. The text that is cut out of the buffer is put in the kill ring and the yank commands insert the appropriate contents of the kill ring back into a buffer (not necessarily the original buffer).

A simple C-y (yank) command inserts the first item from the kill ring into the current buffer. If the C-y command is followed immediately by M-y, the first element is replaced by the second element. Successive M-y commands replace the second element with the third, fourth, or fifth element, and so on. When the last element in the kill ring is reached, it is replaced by the first element and the cycle is repeated. (Thus the kill ring is called a `ring' rather than just a `list'. However, the actual data structure that holds the text is a list. See Handling the Kill Ring, for the details of how the list is handled as a ring.)

  • Kill Ring Overview: The kill ring is a list.
  • kill-ring-yank-pointer: The kill-ring-yank-pointer variable.
  • yank nthcdr Exercises:

Node:Kill Ring Overview, Next:kill-ring-yank-pointer, Previous:Yanking, Up:Yanking

10.1 Kill Ring Overview

The kill ring is a list of textual strings. This is what it looks like:

("some text" "a different piece of text" "yet more text")

If this were the contents of my kill ring and I pressed C-y, the string of characters saying some text would be inserted in this buffer where my cursor is located.

The yank command is also used for duplicating text by copying it. The copied text is not cut from the buffer, but a copy of it is put on the kill ring and is inserted by yanking it back.

Three functions are used for bringing text back from the kill ring: yank, which is usually bound to C-y; yank-pop, which is usually bound to M-y; and rotate-yank-pointer, which is used by the two other functions.

These functions refer to the kill ring through a variable called the kill-ring-yank-pointer. Indeed, the insertion code for both the yank and yank-pop functions is:

(insert (car kill-ring-yank-pointer))

To begin to understand how yank and yank-pop work, it is first necessary to look at the kill-ring-yank-pointer variable and the rotate-yank-pointer function.

Node:kill-ring-yank-pointer, Next:yank nthcdr Exercises, Previous:Kill Ring Overview, Up:Yanking

10.2 The kill-ring-yank-pointer Variable

kill-ring-yank-pointer is a variable, just as kill-ring is a variable. It points to something by being bound to the value of what it points to, like any other Lisp variable.

Thus, if the value of the kill ring is:

("some text" "a different piece of text" "yet more text")

and the kill-ring-yank-pointer points to the second clause, the value of kill-ring-yank-pointer is:

("a different piece of text" "yet more text")

As explained in the previous chapter (see List Implementation), the computer does not keep two different copies of the text being pointed to by both the kill-ring and the kill-ring-yank-pointer. The words "a different piece of text" and "yet more text" are not duplicated. Instead, the two Lisp variables point to the same pieces of text. Here is a diagram:

kill-ring     kill-ring-yank-pointer
    |               |
    |      ___ ___  |     ___ ___      ___ ___
     ---> |   |   |  --> |   |   |    |   |   |
          |___|___|----> |___|___|--> |___|___|--> nil
            |              |            |
            |              |            |
            |              |             --> "yet more text"
            |              |
            |               --> "a different piece of text
            |
             --> "some text"

Both the variable kill-ring and the variable kill-ring-yank-pointer are pointers. But the kill ring itself is usually described as if it were actually what it is composed of. The kill-ring is spoken of as if it were the list rather than that it points to the list. Conversely, the kill-ring-yank-pointer is spoken of as pointing to a list.

These two ways of talking about the same thing sound confusing at first but make sense on reflection. The kill ring is generally thought of as the complete structure of data that holds the information of what has recently been cut out of the Emacs buffers. The kill-ring-yank-pointer on the other hand, serves to indicate--that is, to `point to'--that part of the kill ring of which the first element (the CAR) will be inserted.

The rotate-yank-pointer function changes the element in the kill ring to which the kill-ring-yank-pointer points; when the pointer is set to point to the next element beyond the end of the kill ring, it automatically sets it to point to the first element of the kill ring. This is how the list is transformed into a ring. The rotate-yank-pointer function itself is not difficult, but contains many details. It and the much simpler yank and yank-pop functions are described in an appendix. See Handling the Kill Ring.

Node:yank nthcdr Exercises, Previous:kill-ring-yank-pointer, Up:Yanking

10.3 Exercises with yank and nthcdr

  • Using C-h v (describe-variable), look at the value of your kill ring. Add several items to your kill ring; look at its value again. Using M-y (yank-pop), move all the way around the kill ring. How many items were in your kill ring? Find the value of kill-ring-max. Was your kill ring full, or could you have kept more blocks of text within it?
  • Using nthcdr and car, construct a series of expressions to return the first, second, third, and fourth elements of a list.

Node:Loops & Recursion, Next:Regexp Search, Previous:Yanking, Up:Top

11 Loops and Recursion

Emacs Lisp has two primary ways to cause an expression, or a series of expressions, to be evaluated repeatedly: one uses a while loop, and the other uses recursion.

Repetition can be very valuable. For example, to move forward four sentences, you need only write a program that will move forward one sentence and then repeat the process four times. Since a computer does not get bored or tired, such repetitive action does not have the deleterious effects that excessive or the wrong kinds of repetition can have on humans.

People mostly write Emacs Lisp functions using while loops and their kin; but you can use recursion, which provides a very powerful way to think about and then to solve problems8.

  • while: Causing a stretch of code to repeat.
  • dolist dotimes:
  • Recursion: Causing a function to call itself.
  • Looping exercise:

Node:while, Next:dolist dotimes, Previous:Loops & Recursion, Up:Loops & Recursion

11.1 while

The while special form tests whether the value returned by evaluating its first argument is true or false. This is similar to what the Lisp interpreter does with an if; what the interpreter does next, however, is different.

In a while expression, if the value returned by evaluating the first argument is false, the Lisp interpreter skips the rest of the expression (the body of the expression) and does not evaluate it. However, if the value is true, the Lisp interpreter evaluates the body of the expression and then again tests whether the first argument to while is true or false. If the value returned by evaluating the first argument is again true, the Lisp interpreter again evaluates the body of the expression.

The template for a while expression looks like this:

(while true-or-false-test
  body...)
  • Looping with while: Repeat so long as test returns true.
  • Loop Example: A while loop that uses a list.
  • print-elements-of-list: Uses while, car, cdr.
  • Incrementing Loop: A loop with an incrementing counter.
  • Decrementing Loop: A loop with a decrementing counter.

Node:Looping with while, Next:Loop Example, Previous:while, Up:while

Looping with while

So long as the true-or-false-test of the while expression returns a true value when it is evaluated, the body is repeatedly evaluated. This process is called a loop since the Lisp interpreter repeats the same thing again and again, like an airplane doing a loop. When the result of evaluating the true-or-false-test is false, the Lisp interpreter does not evaluate the rest of the while expression and `exits the loop'.

Clearly, if the value returned by evaluating the first argument to while is always true, the body following will be evaluated again and again ... and again ... forever. Conversely, if the value returned is never true, the expressions in the body will never be evaluated. The craft of writing a while loop consists of choosing a mechanism such that the true-or-false-test returns true just the number of times that you want the subsequent expressions to be evaluated, and then have the test return false.

The value returned by evaluating a while is the value of the true-or-false-test. An interesting consequence of this is that a while loop that evaluates without error will return nil or false regardless of whether it has looped 1 or 100 times or none at all. A while expression that evaluates successfully never returns a true value! What this means is that while is always evaluated for its side effects, which is to say, the consequences of evaluating the expressions within the body of the while loop. This makes sense. It is not the mere act of looping that is desired, but the consequences of what happens when the expressions in the loop are repeatedly evaluated.

Node:Loop Example, Next:print-elements-of-list, Previous:Looping with while, Up:while

11.1.1 A while Loop and a List

A common way to control a while loop is to test whether a list has any elements. If it does, the loop is repeated; but if it does not, the repetition is ended. Since this is an important technique, we will create a short example to illustrate it.

A simple way to test whether a list has elements is to evaluate the list: if it has no elements, it is an empty list and will return the empty list, (), which is a synonym for nil or false. On the other hand, a list with elements will return those elements when it is evaluated. Since Emacs Lisp considers as true any value that is not nil, a list that returns elements will test true in a while loop.

For example, you can set the variable empty-list to nil by evaluating the following setq expression:

(setq empty-list ())

After evaluating the setq expression, you can evaluate the variable empty-list in the usual way, by placing the cursor after the symbol and typing C-x C-e; nil will appear in your echo area:

empty-list

On the other hand, if you set a variable to be a list with elements, the list will appear when you evaluate the variable, as you can see by evaluating the following two expressions:

(setq animals '(gazelle giraffe lion tiger))

animals

Thus, to create a while loop that tests whether there are any items in the list animals, the first part of the loop will be written like this:

(while animals
       ...

When the while tests its first argument, the variable animals is evaluated. It returns a list. So long as the list has elements, the while considers the results of the test to be true; but when the list is empty, it considers the results of the test to be false.

To prevent the while loop from running forever, some mechanism needs to be provided to empty the list eventually. An oft-used technique is to have one of the subsequent forms in the while expression set the value of the list to be the CDR of the list. Each time the cdr function is evaluated, the list will be made shorter, until eventually only the empty list will be left. At this point, the test of the while loop will return false, and the arguments to the while will no longer be evaluated.

For example, the list of animals bound to the variable animals can be set to be the CDR of the original list with the following expression:

(setq animals (cdr animals))

If you have evaluated the previous expressions and then evaluate this expression, you will see (giraffe lion tiger) appear in the echo area. If you evaluate the expression again, (lion tiger) will appear in the echo area. If you evaluate it again and yet again, (tiger) appears and then the empty list, shown by nil.

A template for a while loop that uses the cdr function repeatedly to cause the true-or-false-test eventually to test false looks like this:

(while test-whether-list-is-empty
  body...
  set-list-to-cdr-of-list)

This test and use of cdr can be put together in a function that goes through a list and prints each element of the list on a line of its own.

Node:print-elements-of-list, Next:Incrementing Loop, Previous:Loop Example, Up:while

11.1.2 An Example: print-elements-of-list

The print-elements-of-list function illustrates a while loop with a list.

The function requires several lines for its output. If you are reading this in Emacs 21 or a later version, you can evaluate the following expression inside of Info, as usual.

If you are using an earlier version of Emacs, you need to copy the necessary expressions to your *scratch* buffer and evaluate them there. This is because the echo area had only one line in the earlier versions.

You can copy the expressions by marking the beginning of the region with C-<SPC> (set-mark-command), moving the cursor to the end of the region and then copying the region using M-w (copy-region-as-kill). In the *scratch* buffer, you can yank the expressions back by typing C-y (yank).

After you have copied the expressions to the *scratch* buffer, evaluate each expression in turn. Be sure to evaluate the last expression, (print-elements-of-list animals), by typing C-u C-x C-e, that is, by giving an argument to eval-last-sexp. This will cause the result of the evaluation to be printed in the *scratch* buffer instead of being printed in the echo area. (Otherwise you will see something like this in your echo area: ^Jgiraffe^J^Jgazelle^J^Jlion^J^Jtiger^Jnil, in which each ^J stands for a `newline'.)

If you are using Emacs 21 or later, you can evaluate these expressions directly in the Info buffer, and the echo area will grow to show the results.

(setq animals '(gazelle giraffe lion tiger))

(defun print-elements-of-list (list)
  "Print each element of LIST on a line of its own."
  (while list
    (print (car list))
    (setq list (cdr list))))

(print-elements-of-list animals)

When you evaluate the three expressions in sequence, you will see this:

giraffe

gazelle

lion

tiger
nil

Each element of the list is printed on a line of its own (that is what the function print does) and then the value returned by the function is printed. Since the last expression in the function is the while loop, and since while loops always return nil, a nil is printed after the last element of the list.

Node:Incrementing Loop, Next:Decrementing Loop, Previous:print-elements-of-list, Up:while

11.1.3 A Loop with an Incrementing Counter

A loop is not useful unless it stops when it ought. Besides controlling a loop with a list, a common way of stopping a loop is to write the first argument as a test that returns false when the correct number of repetitions are complete. This means that the loop must have a counter--an expression that counts how many times the loop repeats itself.

The test can be an expression such as (< count desired-number) which returns t for true if the value of count is less than the desired-number of repetitions and nil for false if the value of count is equal to or is greater than the desired-number. The expression that increments the count can be a simple setq such as (setq count (1+ count)), where 1+ is a built-in function in Emacs Lisp that adds 1 to its argument. (The expression (1+ count) has the same result as (+ count 1), but is easier for a human to read.)

The template for a while loop controlled by an incrementing counter looks like this:

set-count-to-initial-value
(while (< count desired-number)         ; true-or-false-test
  body...
  (setq count (1+ count)))              ; incrementer

Note that you need to set the initial value of count; usually it is set to 1.

  • Incrementing Example: Counting pebbles in a triangle.
  • Inc Example parts: The parts of the function definition.
  • Inc Example altogether: Putting the function definition together.

Node:Incrementing Example, Next:Inc Example parts, Previous:Incrementing Loop, Up:Incrementing Loop

Example with incrementing counter

Suppose you are playing on the beach and decide to make a triangle of pebbles, putting one pebble in the first row, two in the second row, three in the third row and so on, like this:

               *
              * *
             * * *
            * * * *

(About 2500 years ago, Pythagoras and others developed the beginnings of number theory by considering questions such as this.)

Suppose you want to know how many pebbles you will need to make a triangle with 7 rows?

Clearly, what you need to do is add up the numbers from 1 to 7. There are two ways to do this; start with the smallest number, one, and add up the list in sequence, 1, 2, 3, 4 and so on; or start with the largest number and add the list going down: 7, 6, 5, 4 and so on. Because both mechanisms illustrate common ways of writing while loops, we will create two examples, one counting up and the other counting down. In this first example, we will start with 1 and add 2, 3, 4 and so on.

If you are just adding up a short list of numbers, the easiest way to do it is to add up all the numbers at once. However, if you do not know ahead of time how many numbers your list will have, or if you want to be prepared for a very long list, then you need to design your addition so that what you do is repeat a simple process many times instead of doing a more complex process once.

For example, instead of adding up all the pebbles all at once, what you can do is add the number of pebbles in the first row, 1, to the number in the second row, 2, and then add the total of those two rows to the third row, 3. Then you can add the number in the fourth row, 4, to the total of the first three rows; and so on.

The critical characteristic of the process is that each repetitive action is simple. In this case, at each step we add only two numbers, the number of pebbles in the row and the total already found. This process of adding two numbers is repeated again and again until the last row has been added to the total of all the preceding rows. In a more complex loop the repetitive action might not be so simple, but it will be simpler than doing everything all at once.

Node:Inc Example parts, Next:Inc Example altogether, Previous:Incrementing Example, Up:Incrementing Loop

The parts of the function definition

The preceding analysis gives us the bones of our function definition: first, we will need a variable that we can call total that will be the total number of pebbles. This will be the value returned by the function.

Second, we know that the function will require an argument: this argument will be the total number of rows in the triangle. It can be called number-of-rows.

Finally, we need a variable to use as a counter. We could call this variable counter, but a better name is row-number. That is because what the counter does is count rows, and a program should be written to be as understandable as possible.

When the Lisp interpreter first starts evaluating the expressions in the function, the value of total should be set to zero, since we have not added anything to it. Then the function should add the number of pebbles in the first row to the total, and then add the number of pebbles in the second to the total, and then add the number of pebbles in the third row to the total, and so on, until there are no more rows left to add.

Both total and row-number are used only inside the function, so they can be declared as local variables with let and given initial values. Clearly, the initial value for total should be 0. The initial value of row-number should be 1, since we start with the first row. This means that the let statement will look like this:

  (let ((total 0)
        (row-number 1))
    body...)

After the internal variables are declared and bound to their initial values, we can begin the while loop. The expression that serves as the test should return a value of t for true so long as the row-number is less than or equal to the number-of-rows. (If the expression tests true only so long as the row number is less than the number of rows in the triangle, the last row will never be added to the total; hence the row number has to be either less than or equal to the number of rows.)

Lisp provides the <= function that returns true if the value of its first argument is less than or equal to the value of its second argument and false otherwise. So the expression that the while will evaluate as its test should look like this:

(<= row-number number-of-rows)

The total number of pebbles can be found by repeatedly adding the number of pebbles in a row to the total already found. Since the number of pebbles in the row is equal to the row number, the total can be found by adding the row number to the total. (Clearly, in a more complex situation, the number of pebbles in the row might be related to the row number in a more complicated way; if this were the case, the row number would be replaced by the appropriate expression.)

(setq total (+ total row-number))

What this does is set the new value of total to be equal to the sum of adding the number of pebbles in the row to the previous total.

After setting the value of total, the conditions need to be established for the next repetition of the loop, if there is one. This is done by incrementing the value of the row-number variable, which serves as a counter. After the row-number variable has been incremented, the true-or-false-test at the beginning of the while loop tests whether its value is still less than or equal to the value of the number-of-rows and if it is, adds the new value of the row-number variable to the total of the previous repetition of the loop.

The built-in Emacs Lisp function 1+ adds 1 to a number, so the row-number variable can be incremented with this expression:

(setq row-number (1+ row-number))

Node:Inc Example altogether, Previous:Inc Example parts, Up:Incrementing Loop

Putting the function definition together

We have created the parts for the function definition; now we need to put them together.

First, the contents of the while expression:

(while (<= row-number number-of-rows)   ; true-or-false-test
  (setq total (+ total row-number))
  (setq row-number (1+ row-number)))    ; incrementer

Along with the let expression varlist, this very nearly completes the body of the function definition. However, it requires one final element, the need for which is somewhat subtle.

The final touch is to place the variable total on a line by itself after the while expression. Otherwise, the value returned by the whole function is the value of the last expression that is evaluated in the body of the let, and this is the value returned by the while, which is always nil.

This may not be evident at first sight. It almost looks as if the incrementing expression is the last expression of the whole function. But that expression is part of the body of the while; it is the last element of the list that starts with the symbol while. Moreover, the whole of the while loop is a list within the body of the let.

In outline, the function will look like this:

(defun name-of-function (argument-list)
  "documentation..."
  (let (varlist)
    (while (true-or-false-test)
      body-of-while... )
    ... )                     ; Need final expression here.

The result of evaluating the let is what is going to be returned by the defun since the let is not embedded within any containing list, except for the defun as a whole. However, if the while is the last element of the let expression, the function will always return nil. This is not what we want! Instead, what we want is the value of the variable total. This is returned by simply placing the symbol as the last element of the list starting with let. It gets evaluated after the preceding elements of the list are evaluated, which means it gets evaluated after it has been assigned the correct value for the total.

It may be easier to see this by printing the list starting with let all on one line. This format makes it evident that the varlist and while expressions are the second and third elements of the list starting with let, and the total is the last element:

(let (varlist) (while (true-or-false-test) body-of-while... ) total)

Putting everything together, the triangle function definition looks like this:

(defun triangle (number-of-rows)    ; Version with
                                    ;   incrementing counter.
  "Add up the number of pebbles in a triangle.
The first row has one pebble, the second row two pebbles,
the third row three pebbles, and so on.
The argument is NUMBER-OF-ROWS."
  (let ((total 0)
        (row-number 1))
    (while (<= row-number number-of-rows)
      (setq total (+ total row-number))
      (setq row-number (1+ row-number)))
    total))

After you have installed triangle by evaluating the function, you can try it out. Here are two examples:

(triangle 4)

(triangle 7)

The sum of the first four numbers is 10 and the sum of the first seven numbers is 28.

Node:Decrementing Loop, Previous:Incrementing Loop, Up:while

11.1.4 Loop with a Decrementing Counter

Another common way to write a while loop is to write the test so that it determines whether a counter is greater than zero. So long as the counter is greater than zero, the loop is repeated. But when the counter is equal to or less than zero, the loop is stopped. For this to work, the counter has to start out greater than zero and then be made smaller and smaller by a form that is evaluated repeatedly.

The test will be an expression such as (> counter 0) which returns t for true if the value of counter is greater than zero, and nil for false if the value of counter is equal to or less than zero. The expression that makes the number smaller and smaller can be a simple setq such as (setq counter (1- counter)), where 1- is a built-in function in Emacs Lisp that subtracts 1 from its argument.

The template for a decrementing while loop looks like this:

(while (> counter 0)                    ; true-or-false-test
  body...
  (setq counter (1- counter)))          ; decrementer
  • Decrementing Example: More pebbles on the beach.
  • Dec Example parts: The parts of the function definition.
  • Dec Example altogether: Putting the function definition together.

Node:Decrementing Example, Next:Dec Example parts, Previous:Decrementing Loop, Up:Decrementing Loop

Example with decrementing counter

To illustrate a loop with a decrementing counter, we will rewrite the triangle function so the counter decreases to zero.

This is the reverse of the earlier version of the function. In this case, to find out how many pebbles are needed to make a triangle with 3 rows, add the number of pebbles in the third row, 3, to the number in the preceding row, 2, and then add the total of those two rows to the row that precedes them, which is 1.

Likewise, to find the number of pebbles in a triangle with 7 rows, add the number of pebbles in the seventh row, 7, to the number in the preceding row, which is 6, and then add the total of those two rows to the row that precedes them, which is 5, and so on. As in the previous example, each addition only involves adding two numbers, the total of the rows already added up and the number of pebbles in the row that is being added to the total. This process of adding two numbers is repeated again and again until there are no more pebbles to add.

We know how many pebbles to start with: the number of pebbles in the last row is equal to the number of rows. If the triangle has seven rows, the number of pebbles in the last row is 7. Likewise, we know how many pebbles are in the preceding row: it is one less than the number in the row.

Node:Dec Example parts, Next:Dec Example altogether, Previous:Decrementing Example, Up:Decrementing Loop

The parts of the function definition

We start with three variables: the total number of rows in the triangle; the number of pebbles in a row; and the total number of pebbles, which is what we want to calculate. These variables can be named number-of-rows, number-of-pebbles-in-row, and total, respectively.

Both total and number-of-pebbles-in-row are used only inside the function and are declared with let. The initial value of total should, of course, be zero. However, the initial value of number-of-pebbles-in-row should be equal to the number of rows in the triangle, since the addition will start with the longest row.

This means that the beginning of the let expression will look like this:

(let ((total 0)
      (number-of-pebbles-in-row number-of-rows))
  body...)

The total number of pebbles can be found by repeatedly adding the number of pebbles in a row to the total already found, that is, by repeatedly evaluating the following expression:

(setq total (+ total number-of-pebbles-in-row))

After the number-of-pebbles-in-row is added to the total, the number-of-pebbles-in-row should be decremented by one, since the next time the loop repeats, the preceding row will be added to the total.

The number of pebbles in a preceding row is one less than the number of pebbles in a row, so the built-in Emacs Lisp function 1- can be used to compute the number of pebbles in the preceding row. This can be done with the following expression:

(setq number-of-pebbles-in-row
      (1- number-of-pebbles-in-row))

Finally, we know that the while loop should stop making repeated additions when there are no pebbles in a row. So the test for the while loop is simply:

(while (> number-of-pebbles-in-row 0)

Node:Dec Example altogether, Previous:Dec Example parts, Up:Decrementing Loop

Putting the function definition together

We can put these expressions together to create a function definition that works. However, on examination, we find that one of the local variables is unneeded!

The function definition looks like this:

;;; First subtractive version.
(defun triangle (number-of-rows)
  "Add up the number of pebbles in a triangle."
  (let ((total 0)
        (number-of-pebbles-in-row number-of-rows))
    (while (> number-of-pebbles-in-row 0)
      (setq total (+ total number-of-pebbles-in-row))
      (setq number-of-pebbles-in-row
            (1- number-of-pebbles-in-row)))
    total))

As written, this function works.

However, we do not need number-of-pebbles-in-row.

When the triangle function is evaluated, the symbol number-of-rows will be bound to a number, giving it an initial value. That number can be changed in the body of the function as if it were a local variable, without any fear that such a change will effect the value of the variable outside of the function. This is a very useful characteristic of Lisp; it means that the variable number-of-rows can be used anywhere in the function where number-of-pebbles-in-row is used.

Here is a second version of the function written a bit more cleanly:

(defun triangle (number)                ; Second version.
  "Return sum of numbers 1 through NUMBER inclusive."
  (let ((total 0))
    (while (> number 0)
      (setq total (+ total number))
      (setq number (1- number)))
    total))

In brief, a properly written while loop will consist of three parts:

  1. A test that will return false after the loop has repeated itself the correct number of times.
  2. An expression the evaluation of which will return the value desired after being repeatedly evaluated.
  3. An expression to change the value passed to the true-or-false-test so that the test returns false after the loop has repeated itself the right number of times.

Node:dolist dotimes, Next:Recursion, Previous:while, Up:Loops & Recursion

11.2 Save your time: dolist and dotimes

In addition to while, both dolist and dotimes provide for looping. Sometimes these are quicker to write than the equivalent while loop. Both are Lisp macros. (See Macros. )

dolist works like a while loop that `CDRs down a list': dolist automatically shortens the list each time it loops--takes the CDR of the list--and binds the CAR of each shorter version of the list to the first of its arguments.

dotimes loops a specific number of time: you specify the number.

  • dolist:
  • dotimes:

Node:dolist, Next:dotimes, Previous:dolist dotimes, Up:dolist dotimes

The dolist Macro

Suppose, for example, you want to reverse a list, so that "first" "second" "third" becomes "third" "second" "first".

In practice, you would use the reverse function, like this:

(setq animals '(gazelle giraffe lion tiger))

(reverse animals)

Here is how you could reverse the list using a while loop:

(setq animals '(gazelle giraffe lion tiger))

(defun reverse-list-with-while (list)
  "Using while, reverse the order of LIST."
  (let (value)  ; make sure list starts empty
    (while list
      (setq value (cons (car list) value))
      (setq list (cdr list)))
    value))

(reverse-list-with-while animals)

And here is how you could use the dolist macro:

(setq animals '(gazelle giraffe lion tiger))

(defun reverse-list-with-dolist (list)
  "Using dolist, reverse the order of LIST."
  (let (value)  ; make sure list starts empty
    (dolist (element list value)
      (setq value (cons element value)))))

(reverse-list-with-dolist animals)

In Info, you can place your cursor after the closing parenthesis of each expression and type C-x C-e; in each case, you should see

(tiger lion giraffe gazelle)

in the echo area.

For this example, the existing reverse function is obviously best. The while loop is just like our first example (see A while Loop and a List). The while first checks whether the list has elements; if so, it constructs a new list by adding the first element of the list to the existing list (which in the first iteration of the loop is nil). Since the second element is prepended in front of the first element, and the third element is prepended in front of the second element, the list is reversed.

In the expression using a while loop, the (setq list (cdr list)) expression shortens the list, so the while loop eventually stops. In addition, it provides the cons expression with a new first element by creating a new and shorter list at each repetition of the loop.

The dolist expression does very much the same as the while expression, except that the dolist macro does some of the work you have to do when writing a while expression.

Like a while loop, a dolist loops. What is different is that it automatically shortens the list each time it loops -- it `CDRs down the list' on its own -- and it automatically binds the CAR of each shorter version of the list to the first of its arguments.

In the example, the CAR of each shorter version of the list is referred to using the symbol element, the list itself is called list, and the value returned is called value. The remainder of the dolist expression is the body.

The dolist expression binds the CAR of each shorter version of the list to element and then evaluates the body of the expression; and repeats the loop. The result is returned in value.

Node:dotimes, Previous:dolist, Up:dolist dotimes

The dotimes Macro

The dotimes macro is similar to dolist, except that it loops a specific number of times.

The first argument to dotimes is assigned the numbers 0, 1, 2 and so forth each time around the loop, and the value of the third argument is returned. You need to provide the value of the second argument, which is how many times the macro loops.

For example, the following binds the numbers from 0 up to, but not including, the number 3 to the first argument, number, and then constructs a list of the three numbers. (The first number is 0, the second number is 1, and the third number is 2; this makes a total of three numbers in all, starting with zero as the first number.)

(let (value)      ; otherwise a value is a void variable
  (dotimes (number 3 value)
    (setq value (cons number value))))

=> (2 1 0)

dotimes returns value, so the way to use dotimes is to operate on some expression number number of times and then return the result, either as a list or an atom.

Here is an example of a defun that uses dotimes to add up the number of pebbles in a triangle.

(defun triangle-using-dotimes (number-of-rows)
  "Using dotimes, add up the number of pebbles in a triangle."
(let ((total 0))  ; otherwise a total is a void variable
  (dotimes (number number-of-rows total)
    (setq total (+ total (1+ number))))))

(triangle-using-dotimes 4)

Node:Recursion, Next:Looping exercise, Previous:dolist dotimes, Up:Loops & Recursion

11.3 Recursion

A recursive function contains code that tells the Lisp interpreter to call a program that runs exactly like itself, but with slightly different arguments. The code runs exactly the same because it has the same name. However, even though it has the same name, it is not the same thread of execution. It is different. In the jargon, it is a different `instance'.

Eventually, if the program is written correctly, the `slightly different arguments' will become sufficiently different from the first arguments that the final instance will stop.

  • Building Robots: Same model, different serial number ...
  • Recursive Definition Parts: Walk until you stop ...
  • Recursion with list: Using a list as the test whether to recurse.
  • Recursive triangle function:
  • Recursion with cond:
  • Recursive Patterns: Often used templates.
  • No Deferment: Don't store up work ...
  • No deferment solution:

Node:Building Robots, Next:Recursive Definition Parts, Previous:Recursion, Up:Recursion

11.3.1 Building Robots: Extending the Metaphor

It is sometimes helpful to think of a running program as a robot that does a job. In doing its job, a recursive function calls on a second robot to help it. The second robot is identical to the first in every way, except that the second robot helps the first and has been passed different arguments than the first.

In a recursive function, the second robot may call a third; and the third may call a fourth, and so on. Each of these is a different entity; but all are clones.

Since each robot has slightly different instructions--the arguments will differ from one robot to the next--the last robot should know when to stop.

Let's expand on the metaphor in which a computer program is a robot.

A function definition provides the blueprints for a robot. When you install a function definition, that is, when you evaluate a defun special form, you install the necessary equipment to build robots. It is as if you were in a factory, setting up an assembly line. Robots with the same name are built according to the same blueprints. So they have, as it were, the same `model number', but a different `serial number'.

We often say that a recursive function `calls itself'. What we mean is that the instructions in a recursive function cause the Lisp interpreter to run a different function that has the same name and does the same job as the first, but with different arguments.

It is important that the arguments differ from one instance to the next; otherwise, the process will never stop.

Node:Recursive Definition Parts, Next:Recursion with list, Previous:Building Robots, Up:Recursion

11.3.2 The Parts of a Recursive Definition

A recursive function typically contains a conditional expression which has three parts:

  1. A true-or-false-test that determines whether the function is called again, here called the do-again-test.
  2. The name of the function. When this name is called, a new instance of the function--a new robot, as it were--is created and told what to do.
  3. An expression that returns a different value each time the function is called, here called the next-step-expression. Consequently, the argument (or arguments) passed to the new instance of the function will be different from that passed to the previous instance. This causes the conditional expression, the do-again-test, to test false after the correct number of repetitions.

Recursive functions can be much simpler than any other kind of function. Indeed, when people first start to use them, they often look so mysteriously simple as to be incomprehensible. Like riding a bicycle, reading a recursive function definition takes a certain knack which is hard at first but then seems simple.

There are several different common recursive patterns. A very simple pattern looks like this:

(defun name-of-recursive-function (argument-list)
  "documentation..."
  (if do-again-test
    body...
    (name-of-recursive-function
         next-step-expression)))

Each time a recursive function is evaluated, a new instance of it is created and told what to do. The arguments tell the instance what to do.

An argument is bound to the value of the next-step-expression. Each instance runs with a different value of the next-step-expression.

The value in the next-step-expression is used in the do-again-test.

The value returned by the next-step-expression is passed to the new instance of the function, which evaluates it (or some transmogrification of it) to determine whether to continue or stop. The next-step-expression is designed so that the do-again-test returns false when the function should no longer be repeated.

The do-again-test is sometimes called the stop condition, since it stops the repetitions when it tests false.

Node:Recursion with list, Next:Recursive triangle function, Previous:Recursive Definition Parts, Up:Recursion

11.3.3 Recursion with a List

The example of a while loop that printed the elements of a list of numbers can be written recursively. Here is the code, including an expression to set the value of the variable animals to a list.

If you are using Emacs 20 or before, this example must be copied to the *scratch* buffer and each expression must be evaluated there. Use C-u C-x C-e to evaluate the (print-elements-recursively animals) expression so that the results are printed in the buffer; otherwise the Lisp interpreter will try to squeeze the results into the one line of the echo area.

Also, place your cursor immediately after the last closing parenthesis of the print-elements-recursively function, before the comment. Otherwise, the Lisp interpreter will try to evaluate the comment.

If you are using Emacs 21 or later, you can evaluate this expression directly in Info.

(setq animals '(gazelle giraffe lion tiger))

(defun print-elements-recursively (list)
  "Print each element of LIST on a line of its own.
Uses recursion."
  (if list                              ; do-again-test
      (progn
        (print (car list))              ; body
        (print-elements-recursively     ; recursive call
         (cdr list)))))                 ; next-step-expression

(print-elements-recursively animals)

The print-elements-recursively function first tests whether there is any content in the list; if there is, the function prints the first element of the list, the CAR of the list. Then the function `invokes itself', but gives itself as its argument, not the whole list, but the second and subsequent elements of the list, the CDR of the list.

Put another way, if the list is not empty, the function invokes another instance of code that is similar to the initial code, but is a different thread of execution, with different arguments than the first instance.

Put in yet another way, if the list is not empty, the first robot assemblies a second robot and tells it what to do; the second robot is a different individual from the first, but is the same model.

When the second evaluation occurs, the if expression is evaluated and if true, prints the first element of the list it receives as its argument (which is the second element of the original list). Then the function `calls itself' with the CDR of the list it is invoked with, which (the second time around) is the CDR of the CDR of the original list.

Note that although we say that the function `calls itself', what we mean is that the Lisp interpreter assembles and instructs a new instance of the program. The new instance is a clone of the first, but is a separate individual.

Each time the function `invokes itself', it invokes itself on a shorter version of the original list. It creates a new instance that works on a shorter list.

Eventually, the function invokes itself on an empty list. It creates a new instance whose argument is nil. The conditional expression tests the value of list. Since the value of list is nil, the if expression tests false so the then-part is not evaluated. The function as a whole then returns nil.

When you evaluate (print-elements-recursively animals) in the *scratch* buffer, you see this result:

giraffe

gazelle

lion

tiger
nil

Node:Recursive triangle function, Next:Recursion with cond, Previous:Recursion with list, Up:Recursion

11.3.4 Recursion in Place of a Counter

The triangle function described in a previous section can also be written recursively. It looks like this:

(defun triangle-recursively (number)
  "Return the sum of the numbers 1 through NUMBER inclusive.
Uses recursion."
  (if (= number 1)                    ; do-again-test
      1                               ; then-part
    (+ number                         ; else-part
       (triangle-recursively          ; recursive call
        (1- number)))))               ; next-step-expression

(triangle-recursively 7)

You can install this function by evaluating it and then try it by evaluating (triangle-recursively 7). (Remember to put your cursor immediately after the last parenthesis of the function definition, before the comment.) The function evaluates to 28.

To understand how this function works, let's consider what happens in the various cases when the function is passed 1, 2, 3, or 4 as the value of its argument.

  • Recursive Example arg of 1 or 2:
  • Recursive Example arg of 3 or 4:

Node:Recursive Example arg of 1 or 2, Next:Recursive Example arg of 3 or 4, Previous:Recursive triangle function, Up:Recursive triangle function

An argument of 1 or 2

First, what happens if the value of the argument is 1?

The function has an if expression after the documentation string. It tests whether the value of number is equal to 1; if so, Emacs evaluates the then-part of the if expression, which returns the number 1 as the value of the function. (A triangle with one row has one pebble in it.)

Suppose, however, that the value of the argument is 2. In this case, Emacs evaluates the else-part of the if expression.

The else-part consists of an addition, the recursive call to triangle-recursively and a decrementing action; and it looks like this:

(+ number (triangle-recursively (1- number)))

When Emacs evaluates this expression, the innermost expression is evaluated first; then the other parts in sequence. Here are the steps in detail:

Step 1 Evaluate the innermost expression.
The innermost expression is (1- number) so Emacs decrements the value of number from 2 to 1.
Step 2 Evaluate the triangle-recursively function.
The Lisp interpreter creates an individual instance of triangle-recursively. It does not matter that this function is contained within itself. Emacs passes the result Step 1 as the argument used by this instance of the triangle-recursively function

In this case, Emacs evaluates triangle-recursively with an argument of 1. This means that this evaluation of triangle-recursively returns 1.

Step 3 Evaluate the value of number.
The variable number is the second element of the list that starts with +; its value is 2.
Step 4 Evaluate the + expression.
The + expression receives two arguments, the first from the evaluation of number (Step 3) and the second from the evaluation of triangle-recursively (Step 2).

The result of the addition is the sum of 2 plus 1, and the number 3 is returned, which is correct. A triangle with two rows has three pebbles in it.

Node:Recursive Example arg of 3 or 4, Previous:Recursive Example arg of 1 or 2, Up:Recursive triangle function

An argument of 3 or 4

Suppose that triangle-recursively is called with an argument of 3.

Step 1 Evaluate the do-again-test.
The if expression is evaluated first. This is the do-again test and returns false, so the else-part of the if expression is evaluated. (Note that in this example, the do-again-test causes the function to call itself when it tests false, not when it tests true.)
Step 2 Evaluate the innermost expression of the else-part.
The innermost expression of the else-part is evaluated, which decrements 3 to 2. This is the next-step-expression.
Step 3 Evaluate the triangle-recursively function.
The number 2 is passed to the triangle-recursively function.

We know what happens when Emacs evaluates triangle-recursively with an argument of 2. After going through the sequence of actions described earlier, it returns a value of 3. So that is what will happen here.

Step 4 Evaluate the addition.
3 will be passed as an argument to the addition and will be added to the number with which the function was called, which is 3.

The value returned by the function as a whole will be 6.

Now that we know what will happen when triangle-recursively is called with an argument of 3, it is evident what will happen if it is called with an argument of 4:

In the recursive call, the evaluation of
(triangle-recursively (1- 4))

will return the value of evaluating

(triangle-recursively 3)

which is 6 and this value will be added to 4 by the addition in the third line.

The value returned by the function as a whole will be 10.

Each time triangle-recursively is evaluated, it evaluates a version of itself--a different instance of itself--with a smaller argument, until the argument is small enough so that it does not evaluate itself.

Note that this particular design for a recursive function requires that operations be deferred.

Before (triangle-recursively 7) can calculate its answer, it must call (triangle-recursively 6); and before (triangle-recursively 6) can calculate its answer, it must call (triangle-recursively 5); and so on. That is to say, the calculation that (triangle-recursively 7) makes must be deferred until (triangle-recursively 6) makes its calculation; and (triangle-recursively 6) must defer until (triangle-recursively 5) completes; and so on.

If each of these instances of triangle-recursively are thought of as different robots, the first robot must wait for the second to complete its job, which must wait until the third completes, and so on.

There is a way around this kind of waiting, which we will discuss in Recursion without Deferments.

Node:Recursion with cond, Next:Recursive Patterns, Previous:Recursive triangle function, Up:Recursion

11.3.5 Recursion Example Using cond

The version of triangle-recursively described earlier is written with the if special form. It can also be written using another special form called cond. The name of the special form cond is an abbreviation of the word conditional.

Although the cond special form is not used as often in the Emacs Lisp sources as if, it is used often enough to justify explaining it.

The template for a cond expression looks like this:

(cond
 body...)

where the body is a series of lists.

Written out more fully, the template looks like this:

(cond
 (first-true-or-false-test first-consequent)
 (second-true-or-false-test second-consequent)
 (third-true-or-false-test third-consequent)
  ...)

When the Lisp interpreter evaluates the cond expression, it evaluates the first element (the CAR or true-or-false-test) of the first expression in a series of expressions within the body of the cond.

If the true-or-false-test returns nil the rest of that expression, the consequent, is skipped and the true-or-false-test of the next expression is evaluated. When an expression is found whose true-or-false-test returns a value that is not nil, the consequent of that expression is evaluated. The consequent can be one or more expressions. If the consequent consists of more than one expression, the expressions are evaluated in sequence and the value of the last one is returned. If the expression does not have a consequent, the value of the true-or-false-test is returned.

If none of the true-or-false-tests test true, the cond expression returns nil.

Written using cond, the triangle function looks like this:

(defun triangle-using-cond (number)
  (cond ((<= number 0) 0)
        ((= number 1) 1)
        ((> number 1)
         (+ number (triangle-using-cond (1- number))))))

In this example, the cond returns 0 if the number is less than or equal to 0, it returns 1 if the number is 1 and it evaluates (+ number (triangle-using-cond (1- number))) if the number is greater than 1.

Node:Recursive Patterns, Next:No Deferment, Previous:Recursion with cond, Up:Recursion

11.3.6 Recursive Patterns

Here are three common recursive patterns. Each involves a list. Recursion does not need to involve lists, but Lisp is designed for lists and this provides a sense of its primal capabilities.

  • Every:
  • Accumulate:
  • Keep:

Node:Every, Next:Accumulate, Previous:Recursive Patterns, Up:Recursive Patterns

Recursive Pattern: every

In the every recursive pattern, an action is performed on every element of a list.

The basic pattern is:

  • If a list be empty, return nil.
  • Else, act on the beginning of the list (the CAR of the list)
    • through a recursive call by the function on the rest (the CDR) of the list,
    • and, optionally, combine the acted-on element, using cons, with the results of acting on the rest.

Here is example:

(defun square-each (numbers-list)
  "Square each of a NUMBERS LIST, recursively."
  (if (not numbers-list)                ; do-again-test
      nil
    (cons
     (* (car numbers-list) (car numbers-list))
     (square-each (cdr numbers-list))))) ; next-step-expression

(square-each '(1 2 3))
    => (1 4 9)

If numbers-list is empty, do nothing. But if it has content, construct a list combining the square of the first number in the list with the result of the recursive call.

(The example follows the pattern exactly: nil is returned if the numbers' list is empty. In practice, you would write the conditional so it carries out the action when the numbers' list is not empty.)

The print-elements-recursively function (see Recursion with a List) is another example of an every pattern, except in this case, rather than bring the results together using cons, we print each element of output.

The print-elements-recursively function looks like this:

(setq animals '(gazelle giraffe lion tiger))

(defun print-elements-recursively (list)
  "Print each element of LIST on a line of its own.
Uses recursion."
  (if list                              ; do-again-test
      (progn
        (print (car list))              ; body
        (print-elements-recursively     ; recursive call
         (cdr list)))))                 ; next-step-expression

(print-elements-recursively animals)

The pattern for print-elements-recursively is:

  • If the list be empty, do nothing.
  • But if the list has at least one element,
    • act on the beginning of the list (the CAR of the list),
    • and make a recursive call on the rest (the CDR) of the list.

Node:Accumulate, Next:Keep, Previous:Every, Up:Recursive Patterns

Recursive Pattern: accumulate

Another recursive pattern is called the accumulate pattern. In the accumulate recursive pattern, an action is performed on every element of a list and the result of that action is accumulated with the results of performing the action on the other elements.

This is very like the `every' pattern using cons, except that cons is not used, but some other combiner.

The pattern is:

  • If a list be empty, return zero or some other constant.
  • Else, act on the beginning of the list (the CAR of the list),
    • and combine that acted-on element, using + or some other combining function, with
    • a recursive call by the function on the rest (the CDR) of the list.

Here is an example:

(defun add-elements (numbers-list)
  "Add the elements of NUMBERS-LIST together."
  (if (not numbers-list)
      0
    (+ (car numbers-list) (add-elements (cdr numbers-list)))))

(add-elements '(1 2 3 4))
    => 10

See Making a List of Files, for an example of the accumulate pattern.

Node:Keep, Previous:Accumulate, Up:Recursive Patterns

Recursive Pattern: keep

A third recursive pattern is called the keep pattern. In the keep recursive pattern, each element of a list is tested; the element is acted on and the results are kept only if the element meets a criterion.

Again, this is very like the `every' pattern, except the element is skipped unless it meets a criterion.

The pattern has three parts:

  • If a list be empty, return nil.
  • Else, if the beginning of the list (the CAR of the list) passes a test
    • act on that element and combine it, using cons with
    • a recursive call by the function on the rest (the CDR) of the list.
  • Otherwise, if the beginning of the list (the CAR of the list) fails the test
    • skip on that element,
    • and, recursively call the function on the rest (the CDR) of the list.

Here is an example that uses cond:

(defun keep-three-letter-words (word-list)
  "Keep three letter words in WORD-LIST."
  (cond
   ;; First do-again-test: stop-condition
   ((not word-list) nil)

   ;; Second do-again-test: when to act
   ((eq 3 (length (symbol-name (car word-list))))
    ;; combine acted-on element with recursive call on shorter list
    (cons (car word-list) (keep-three-letter-words (cdr word-list))))

   ;; Third do-again-test: when to skip element;
   ;;   recursively call shorter list with next-step expression
   (t  (keep-three-letter-words (cdr word-list)))))

(keep-three-letter-words '(one two three four five six))
    => (one two six)

It goes without saying that you need not use nil as the test for when to stop; and you can, of course, combine these patterns.

Node:No Deferment, Next:No deferment solution, Previous:Recursive Patterns, Up:Recursion

11.3.7 Recursion without Deferments

Let's consider again what happens with the triangle-recursively function. We will find that the intermediate calculations are deferred until all can be done.

Here is the function definition:

(defun triangle-recursively (number)
  "Return the sum of the numbers 1 through NUMBER inclusive.
Uses recursion."
  (if (= number 1)                    ; do-again-test
      1                               ; then-part
    (+ number                         ; else-part
       (triangle-recursively          ; recursive call
        (1- number)))))               ; next-step-expression

What happens when we call this function with a argument of 7?

The first instance of the triangle-recursively function adds the number 7 to the value returned by a second instance of triangle-recursively, an instance that has been passed an argument of 6. That is to say, the first calculation is:

(+ 7 (triangle-recursively 6)

The first instance of triangle-recursively--you may want to think of it as a little robot--cannot complete its job. It must hand off the calculation for (triangle-recursively 6) to a second instance of the program, to a second robot. This second individual is completely different from the first one; it is, in the jargon, a `different instantiation'. Or, put another way, it is a different robot. It is the same model as the first; it calculates triangle numbers recursively; but it has a different serial number.

And what does (triangle-recursively 6) return? It returns the number 6 added to the value returned by evaluating triangle-recursively with an argument of 5. Using the robot metaphor, it asks yet another robot to help it.

Now the total is:

(+ 7 6 (triangle-recursively 5)

And what happens next?

(+ 7 6 5 (triangle-recursively 4)

Each time triangle-recursively is called, except for the last time, it creates another instance of the program--another robot--and asks it to make a calculation.

Eventually, the full addition is set up and performed:

(+ 7 6 5 4 3 2 1)

This design for the function defers the calculation of the first step until the second can be done, and defers that until the third can be done, and so on. Each deferment means the computer must remember what is being waited on. This is not a problem when there are only a few steps, as in this example. But it can be a problem when there are more steps.

Node:No deferment solution, Previous:No Deferment, Up:Recursion

11.3.8 No Deferment Solution

The solution to the problem of deferred operations is to write in a manner that does not defer operations9. This requires writing to a different pattern, often one that involves writing two function definitions, an `initialization' function and a `helper' function.

The `initialization' function sets up the job; the `helper' function does the work.

Here are the two function definitions for adding up numbers. They are so simple, I find them hard to understand.

(defun triangle-initialization (number)
  "Return the sum of the numbers 1 through NUMBER inclusive.
This is the `initialization' component of a two function
duo that uses recursion."
  (triangle-recursive-helper 0 0 number))

(defun triangle-recursive-helper (sum counter number)
  "Return SUM, using COUNTER, through NUMBER inclusive.
This is the `helper' component of a two function duo
that uses recursion."
  (if (> counter number)
      sum
    (triangle-recursive-helper (+ sum counter)  ; sum
                               (1+ counter)     ; counter
                               number)))        ; number

Install both function definitions by evaluating them, then call triangle-initialization with 2 rows:

(triangle-initialization 2)
    => 3

The `initialization' function calls the first instance of the `helper' function with three arguments: zero, zero, and a number which is the number of rows in the triangle.

The first two arguments passed to the `helper' function are initialization values. These values are changed when triangle-recursive-helper invokes new instances.10

Let's see what happens when we have a triangle that has one row. (This triangle will have one pebble in it!)

triangle-initialization will call its helper with the arguments 0 0 1. That function will run the conditional test whether (> counter number):

(> 0 1)

and find that the result is false, so it will invoke the then-part of the if clause:

    (triangle-recursive-helper
     (+ sum counter)  ; sum plus counter => sum
     (1+ counter)     ; increment counter => counter
     number)          ; number stays the same

which will first compute:

(triangle-recursive-helper (+ 0 0)  ; sum
                           (1+ 0)   ; counter
                           1)       ; number

which is:

(triangle-recursive-helper 0 1 1)

Again, (> counter number) will be false, so again, the Lisp interpreter will evaluate triangle-recursive-helper, creating a new instance with new arguments.

This new instance will be;

    (triangle-recursive-helper
     (+ sum counter)  ; sum plus counter => sum
     (1+ counter)     ; increment counter => counter
     number)          ; number stays the same

which is:

(triangle-recursive-helper 1 2 1)

In this case, the (> counter number) test will be true! So the instance will return the value of the sum, which will be 1, as expected.

Now, let's pass triangle-initialization an argument of 2, to find out how many pebbles there are in a triangle with two rows.

That function calls (triangle-recursive-helper 0 0 2).

In stages, the instances called will be:

                          sum counter number
(triangle-recursive-helper 0    1       2)

(triangle-recursive-helper 1    2       2)

(triangle-recursive-helper 3    3       2)

When the last instance is called, the (> counter number) test will be true, so the instance will return the value of sum, which will be 3.

This kind of pattern helps when you are writing functions that can use many resources in a computer.

Node:Looping exercise, Previous:Recursion, Up:Loops & Recursion

11.4 Looping Exercise

  • Write a function similar to triangle in which each row has a value which is the square of the row number. Use a while loop.
  • Write a function similar to triangle that multiplies instead of adds the values.
  • Rewrite these two functions recursively. Rewrite these functions using cond.
  • Write a function for Texinfo mode that creates an index entry at the beginning of a paragraph for every @dfn within the paragraph. (In a Texinfo file, @dfn marks a definition. For more information, see Indicating.)

Node:Regexp Search, Next:Counting Words, Previous:Loops & Recursion, Up:Top

12 Regular Expression Searches

Regular expression searches are used extensively in GNU Emacs. The two functions, forward-sentence and forward-paragraph, illustrate these searches well. They use regular expressions to find where to move point. The phrase `regular expression' is often written as `regexp'.

Regular expression searches are described in Regexp Search, as well as in Regular Expressions. In writing this chapter, I am presuming that you have at least a mild acquaintance with them. The major point to remember is that regular expressions permit you to search for patterns as well as for literal strings of characters. For example, the code in forward-sentence searches for the pattern of possible characters that could mark the end of a sentence, and moves point to that spot.

Before looking at the code for the forward-sentence function, it is worth considering what the pattern that marks the end of a sentence must be. The pattern is discussed in the next section; following that is a description of the regular expression search function, re-search-forward. The forward-sentence function is described in the section following. Finally, the forward-paragraph function is described in the last section of this chapter. forward-paragraph is a complex function that introduces several new features.

  • sentence-end: The regular expression for sentence-end.
  • re-search-forward: Very similar to search-forward.
  • forward-sentence: A straightforward example of regexp search.
  • forward-paragraph: A somewhat complex example.
  • etags: How to create your own TAGS table.
  • Regexp Review:
  • re-search Exercises:

Node:sentence-end, Next:re-search-forward, Previous:Regexp Search, Up:Regexp Search

12.1 The Regular Expression for sentence-end

The symbol sentence-end is bound to the pattern that marks the end of a sentence. What should this regular expression be?

Clearly, a sentence may be ended by a period, a question mark, or an exclamation mark. Indeed, only clauses that end with one of those three characters should be considered the end of a sentence. This means that the pattern should include the character set:

[.?!]

However, we do not want forward-sentence merely to jump to a period, a question mark, or an exclamation mark, because such a character might be used in the middle of a sentence. A period, for example, is used after abbreviations. So other information is needed.

According to convention, you type two spaces after every sentence, but only one space after a period, a question mark, or an exclamation mark in the body of a sentence. So a period, a question mark, or an exclamation mark followed by two spaces is a good indicator of an end of sentence. However, in a file, the two spaces may instead be a tab or the end of a line. This means that the regular expression should include these three items as alternatives.

This group of alternatives will look like this:

\\($\\| \\|  \\)
       ^   ^^
      TAB  SPC

Here, $ indicates the end of the line, and I have pointed out where the tab and two spaces are inserted in the expression. Both are inserted by putting the actual characters into the expression.

Two backslashes, \\, are required before the parentheses and vertical bars: the first backslash quotes the following backslash in Emacs; and the second indicates that the following character, the parenthesis or the vertical bar, is special.

Also, a sentence may be followed by one or more carriage returns, like this:

[
]*

Like tabs and spaces, a carriage return is inserted into a regular expression by inserting it literally. The asterisk indicates that the <RET> is repeated zero or more times.

But a sentence end does not consist only of a period, a question mark or an exclamation mark followed by appropriate space: a closing quotation mark or a closing brace of some kind may precede the space. Indeed more than one such mark or brace may precede the space. These require a expression that looks like this:

[]\"')}]*

In this expression, the first ] is the first character in the expression; the second character is ", which is preceded by a \ to tell Emacs the " is not special. The last three characters are ', ), and }.

All this suggests what the regular expression pattern for matching the end of a sentence should be; and, indeed, if we evaluate sentence-end we find that it returns the following value:

sentence-end
     => "[.?!][]\"')}]*\\($\\|     \\|  \\)[
]*"

Node:re-search-forward, Next:forward-sentence, Previous:sentence-end, Up:Regexp Search

12.2 The re-search-forward Function

The re-search-forward function is very like the search-forward function. (See The search-forward Function.)

re-search-forward searches for a regular expression. If the search is successful, it leaves point immediately after the last character in the target. If the search is backwards, it leaves point just before the first character in the target. You may tell re-search-forward to return t for true. (Moving point is therefore a `side effect'.)

Like search-forward, the re-search-forward function takes four arguments:

  1. The first argument is the regular expression that the function searches for. The regular expression will be a string between quotations marks.
  2. The optional second argument limits how far the function will search; it is a bound, which is specified as a position in the buffer.
  3. The optional third argument specifies how the function responds to failure: nil as the third argument causes the function to signal an error (and print a message) when the search fails; any other value causes it to return nil if the search fails and t if the search succeeds.
  4. The optional fourth argument is the repeat count. A negative repeat count causes re-search-forward to search backwards.

The template for re-search-forward looks like this:

(re-search-forward "regular-expression"
                limit-of-search
                what-to-do-if-search-fails
                repeat-count)

The second, third, and fourth arguments are optional. However, if you want to pass a value to either or both of the last two arguments, you must also pass a value to all the preceding arguments. Otherwise, the Lisp interpreter will mistake which argument you are passing the value to.

In the forward-sentence function, the regular expression will be the value of the variable sentence-end, namely:

"[.?!][]\"')}]*\\($\\|  \\|  \\)[
]*"

The limit of the search will be the end of the paragraph (since a sentence cannot go beyond a paragraph). If the search fails, the function will return nil; and the repeat count will be provided by the argument to the forward-sentence function.

Node:forward-sentence, Next:forward-paragraph, Previous:re-search-forward, Up:Regexp Search

12.3 forward-sentence

The command to move the cursor forward a sentence is a straightforward illustration of how to use regular expression searches in Emacs Lisp. Indeed, the function looks longer and more complicated than it is; this is because the function is designed to go backwards as well as forwards; and, optionally, over more than one sentence. The function is usually bound to the key command M-e.

  • Complete forward-sentence:
  • fwd-sentence while loops: Two while loops.
  • fwd-sentence re-search: A regular expression search.

Node:Complete forward-sentence, Next:fwd-sentence while loops, Previous:forward-sentence, Up:forward-sentence

Complete forward-sentence function definition

Here is the code for forward-sentence:

(defun forward-sentence (&optional arg)
  "Move forward to next sentence-end.  With argument, repeat.
With negative argument, move backward repeatedly to sentence-beginning.
Sentence ends are identified by the value of sentence-end
treated as a regular expression.  Also, every paragraph boundary
terminates sentences as well."
  (interactive "p")
  (or arg (setq arg 1))
  (while (< arg 0)
    (let ((par-beg
           (save-excursion (start-of-paragraph-text) (point))))
      (if (re-search-backward
           (concat sentence-end "[^ \t\n]") par-beg t)
          (goto-char (1- (match-end 0)))
        (goto-char par-beg)))
    (setq arg (1+ arg)))
  (while (> arg 0)
    (let ((par-end
           (save-excursion (end-of-paragraph-text) (point))))
      (if (re-search-forward sentence-end par-end t)
          (skip-chars-backward " \t\n")
        (goto-char par-end)))
    (setq arg (1- arg))))

The function looks long at first sight and it is best to look at its skeleton first, and then its muscle. The way to see the skeleton is to look at the expressions that start in the left-most columns:

(defun forward-sentence (&optional arg)
  "documentation..."
  (interactive "p")
  (or arg (setq arg 1))
  (while (< arg 0)
    body-of-while-loop
  (while (> arg 0)
    body-of-while-loop

This looks much simpler! The function definition consists of documentation, an interactive expression, an or expression, and while loops.

Let's look at each of these parts in turn.

We note that the documentation is thorough and understandable.

The function has an interactive "p" declaration. This means that the processed prefix argument, if any, is passed to the function as its argument. (This will be a number.) If the function is not passed an argument (it is optional) then the argument arg will be bound to 1. When forward-sentence is called non-interactively without an argument, arg is bound to nil.

The or expression handles the prefix argument. What it does is either leave the value of arg as it is, but only if arg is bound to a value; or it sets the value of arg to 1, in the case when arg is bound to nil.

Node:fwd-sentence while loops, Next:fwd-sentence re-search, Previous:Complete forward-sentence, Up:forward-sentence

The while loops

Two while loops follow the or expression. The first while has a true-or-false-test that tests true if the prefix argument for forward-sentence is a negative number. This is for going backwards. The body of this loop is similar to the body of the second while clause, but it is not exactly the same. We will skip this while loop and concentrate on the second while loop.

The second while loop is for moving point forward. Its skeleton looks like this:

(while (> arg 0)            ; true-or-false-test
  (let varlist
    (if (true-or-false-test)
        then-part
      else-part
  (setq arg (1- arg))))     ; while loop decrementer

The while loop is of the decrementing kind. (See A Loop with a Decrementing Counter.) It has a true-or-false-test that tests true so long as the counter (in this case, the variable arg) is greater than zero; and it has a decrementer that subtracts 1 from the value of the counter every time the loop repeats.

If no prefix argument is given to forward-sentence, which is the most common way the command is used, this while loop will run once, since the value of arg will be 1.

The body of the while loop consists of a let expression, which creates and binds a local variable, and has, as its body, an if expression.

The body of the while loop looks like this:

(let ((par-end
       (save-excursion (end-of-paragraph-text) (point))))
  (if (re-search-forward sentence-end par-end t)
      (skip-chars-backward " \t\n")
    (goto-char par-end)))

The let expression creates and binds the local variable par-end. As we shall see, this local variable is designed to provide a bound or limit to the regular expression search. If the search fails to find a proper sentence ending in the paragraph, it will stop on reaching the end of the paragraph.

But first, let us examine how par-end is bound to the value of the end of the paragraph. What happens is that the let sets the value of par-end to the value returned when the Lisp interpreter evaluates the expression

(save-excursion (end-of-paragraph-text) (point))

In this expression, (end-of-paragraph-text) moves point to the end of the paragraph, (point) returns the value of point, and then save-excursion restores point to its original position. Thus, the let binds par-end to the value returned by the save-excursion expression, which is the position of the end of the paragraph. (The (end-of-paragraph-text) function uses forward-paragraph, which we will discuss shortly.)

Emacs next evaluates the body of the let, which is an if expression that looks like this:

(if (re-search-forward sentence-end par-end t) ; if-part
    (skip-chars-backward " \t\n")              ; then-part
  (goto-char par-end)))                        ; else-part

The if tests whether its first argument is true and if so, evaluates its then-part; otherwise, the Emacs Lisp interpreter evaluates the else-part. The true-or-false-test of the if expression is the regular expression search.

It may seem odd to have what looks like the `real work' of the forward-sentence function buried here, but this is a common way this kind of operation is carried out in Lisp.

Node:fwd-sentence re-search, Previous:fwd-sentence while loops, Up:forward-sentence

The regular expression search

The re-search-forward function searches for the end of the sentence, that is, for the pattern defined by the sentence-end regular expression. If the pattern is found--if the end of the sentence is found--then the re-search-forward function does two things:

  1. The re-search-forward function carries out a side effect, which is to move point to the end of the occurrence found.
  2. The re-search-forward function returns a value of true. This is the value received by the if, and means that the search was successful.

The side effect, the movement of point, is completed before the if function is handed the value returned by the successful conclusion of the search.

When the if function receives the value of true from a successful call to re-search-forward, the if evaluates the then-part, which is the expression (skip-chars-backward " \t\n"). This expression moves backwards over any blank spaces, tabs or carriage returns until a printed character is found and then leaves point after the character. Since point has already been moved to the end of the pattern that marks the end of the sentence, this action leaves point right after the closing printed character of the sentence, which is usually a period.

On the other hand, if the re-search-forward function fails to find a pattern marking the end of the sentence, the function returns false. The false then causes the if to evaluate its third argument, which is (goto-char par-end): it moves point to the end of the paragraph.

Regular expression searches are exceptionally useful and the pattern illustrated by re-search-forward, in which the search is the test of an if expression, is handy. You will see or write code incorporating this pattern often.

Node:forward-paragraph, Next:etags, Previous:forward-sentence, Up:Regexp Search

12.4 forward-paragraph: a Goldmine of Functions

The forward-paragraph function moves point forward to the end of the paragraph. It is usually bound to M-} and makes use of a number of functions that are important in themselves, including let*, match-beginning, and looking-at.

The function definition for forward-paragraph is considerably longer than the function definition for forward-sentence because it works with a paragraph, each line of which may begin with a fill prefix.

A fill prefix consists of a string of characters that are repeated at the beginning of each line. For example, in Lisp code, it is a convention to start each line of a paragraph-long comment with ;;; . In Text mode, four blank spaces make up another common fill prefix, creating an indented paragraph. (See Fill Prefix, for more information about fill prefixes.)

The existence of a fill prefix means that in addition to being able to find the end of a paragraph whose lines begin on the left-most column, the forward-paragraph function must be able to find the end of a paragraph when all or many of the lines in the buffer begin with the fill prefix.

Moreover, it is sometimes practical to ignore a fill prefix that exists, especially when blank lines separate paragraphs. This is an added complication.

  • forward-paragraph in brief: Key parts of the function definition.
  • fwd-para let: The let* expression.
  • fwd-para while: The forward motion while loop.
  • fwd-para between paragraphs: Movement between paragraphs.
  • fwd-para within paragraph: Movement within paragraphs.
  • fwd-para no fill prefix: When there is no fill prefix.
  • fwd-para with fill prefix: When there is a fill prefix.
  • fwd-para summary: Summary of forward-paragraph code.

Node:forward-paragraph in brief, Next:fwd-para let, Previous:forward-paragraph, Up:forward-paragraph

Shortened forward-paragraph function definition

Rather than print all of the forward-paragraph function, we will only print parts of it. Read without preparation, the function can be daunting!

In outline, the function looks like this:

(defun forward-paragraph (&optional arg)
  "documentation..."
  (interactive "p")
  (or arg (setq arg 1))
  (let*
      varlist
    (while (< arg 0)        ; backward-moving-code
      ...
      (setq arg (1+ arg)))
    (while (> arg 0)        ; forward-moving-code
      ...
      (setq arg (1- arg)))))

The first parts of the function are routine: the function's argument list consists of one optional argument. Documentation follows.

The lower case p in the interactive declaration means that the processed prefix argument, if any, is passed to the function. This will be a number, and is the repeat count of how many paragraphs point will move. The or expression in the next line handles the common case when no argument is passed to the function, which occurs if the function is called from other code rather than interactively. This case was described earlier. (See The forward-sentence function.) Now we reach the end of the familiar part of this function.

Node:fwd-para let, Next:fwd-para while, Previous:forward-paragraph in brief, Up:forward-paragraph

The let* expression

The next line of the forward-paragraph function begins a let* expression. This is a different kind of expression than we have seen so far. The symbol is let* not let.

The let* special form is like let except that Emacs sets each variable in sequence, one after another, and variables in the latter part of the varlist can make use of the values to which Emacs set variables in the earlier part of the varlist.

In the let* expression in this function, Emacs binds two variables: fill-prefix-regexp and paragraph-separate. The value to which paragraph-separate is bound depends on the value of fill-prefix-regexp.

Let's look at each in turn. The symbol fill-prefix-regexp is set to the value returned by evaluating the following list:

(and fill-prefix
     (not (equal fill-prefix ""))
     (not paragraph-ignore-fill-prefix)
     (regexp-quote fill-prefix))

This is an expression whose first element is the and special form.

As we learned earlier (see The kill-new function), the and special form evaluates each of its arguments until one of the arguments returns a value of nil, in which case the and expression returns nil; however, if none of the arguments returns a value of nil, the value resulting from evaluating the last argument is returned. (Since such a value is not nil, it is considered true in Lisp.) In other words, an and expression returns a true value only if all its arguments are true.

In this case, the variable fill-prefix-regexp is bound to a non-nil value only if the following four expressions produce a true (i.e., a non-nil) value when they are evaluated; otherwise, fill-prefix-regexp is bound to nil.

fill-prefix
When this variable is evaluated, the value of the fill prefix, if any, is returned. If there is no fill prefix, this variable returns nil.
(not (equal fill-prefix "")
This expression checks whether an existing fill prefix is an empty string, that is, a string with no characters in it. An empty string is not a useful fill prefix.
(not paragraph-ignore-fill-prefix)
This expression returns nil if the variable paragraph-ignore-fill-prefix has been turned on by being set to a true value such as t.
(regexp-quote fill-prefix)
This is the last argument to the and special form. If all the arguments to the and are true, the value resulting from evaluating this expression will be returned by the and expression and bound to the variable fill-prefix-regexp,

The result of evaluating this and expression successfully is that fill-prefix-regexp will be bound to the value of fill-prefix as modified by the regexp-quote function. What regexp-quote does is read a string and return a regular expression that will exactly match the string and match nothing else. This means that fill-prefix-regexp will be set to a value that will exactly match the fill prefix if the fill prefix exists. Otherwise, the variable will be set to nil.

The second local variable in the let* expression is paragraph-separate. It is bound to the value returned by evaluating the expression:

(if fill-prefix-regexp
    (concat paragraph-separate
            "\\|^" fill-prefix-regexp "[ \t]*$")
  paragraph-separate)))

This expression shows why let* rather than let was used. The true-or-false-test for the if depends on whether the variable fill-prefix-regexp evaluates to nil or some other value.

If fill-prefix-regexp does not have a value, Emacs evaluates the else-part of the if expression and binds paragraph-separate to its local value. (paragraph-separate is a regular expression that matches what separates paragraphs.)

But if fill-prefix-regexp does have a value, Emacs evaluates the then-part of the if expression and binds paragraph-separate to a regular expression that includes the fill-prefix-regexp as part of the pattern.

Specifically, paragraph-separate is set to the original value of the paragraph separate regular expression concatenated with an alternative expression that consists of the fill-prefix-regexp followed by a blank line. The ^ indicates that the fill-prefix-regexp must begin a line, and the optional whitespace to the end of the line is defined by "[ \t]*$".) The \\| defines this portion of the regexp as an alternative to paragraph-separate.

Now we get into the body of the let*. The first part of the body of the let* deals with the case when the function is given a negative argument and is therefore moving backwards. We will skip this section.

Node:fwd-para while, Next:fwd-para between paragraphs, Previous:fwd-para let, Up:forward-paragraph

The forward motion while loop

The second part of the body of the let* deals with forward motion. It is a while loop that repeats itself so long as the value of arg is greater than zero. In the most common use of the function, the value of the argument is 1, so the body of the while loop is evaluated exactly once, and the cursor moves forward one paragraph.

This part handles three situations: when point is between paragraphs, when point is within a paragraph and there is a fill prefix, and when point is within a paragraph and there is no fill prefix.

The while loop looks like this:

(while (> arg 0)
  (beginning-of-line)

  ;; between paragraphs
  (while (prog1 (and (not (eobp))
                     (looking-at paragraph-separate))
           (forward-line 1)))

  ;; within paragraphs, with a fill prefix
  (if fill-prefix-regexp
      ;; There is a fill prefix; it overrides paragraph-start.
      (while (and (not (eobp))
                  (not (looking-at paragraph-separate))
                  (looking-at fill-prefix-regexp))
        (forward-line 1))

    ;; within paragraphs, no fill prefix
    (if (re-search-forward paragraph-start nil t)
        (goto-char (match-beginning 0))
      (goto-char (point-max))))

  (setq arg (1- arg)))

We can see immediately that this is a decrementing counter while loop, using the expression (setq arg (1- arg)) as the decrementer.

The body of the loop consists of three expressions:

;; between paragraphs
(beginning-of-line)
(while
    body-of-while)

;; within paragraphs, with fill prefix
(if true-or-false-test
    then-part

;; within paragraphs, no fill prefix
  else-part

When the Emacs Lisp interpreter evaluates the body of the while loop, the first thing it does is evaluate the (beginning-of-line) expression and move point to the beginning of the line. Then there is an inner while loop. This while loop is designed to move the cursor out of the blank space between paragraphs, if it should happen to be there. Finally, there is an if expression that actually moves point to the end of the paragraph.

Node:fwd-para between paragraphs, Next:fwd-para within paragraph, Previous:fwd-para while, Up:forward-paragraph

Between paragraphs

First, let us look at the inner while loop. This loop handles the case when point is between paragraphs; it uses three functions that are new to us: prog1, eobp and looking-at.

  • prog1 is similar to the progn special form, except that prog1 evaluates its arguments in sequence and then returns the value of its first argument as the value of the whole expression. (progn returns the value of its last argument as the value of the expression.) The second and subsequent arguments to prog1 are evaluated only for their side effects.
  • eobp is an abbreviation of End Of Buffer P and is a function that returns true if point is at the end of the buffer.
  • looking-at is a function that returns true if the text following point matches the regular expression passed looking-at as its argument.

The while loop we are studying looks like this:

(while (prog1 (and (not (eobp))
                   (looking-at paragraph-separate))
              (forward-line 1)))

This is a while loop with no body! The true-or-false-test of the loop is the expression:

(prog1 (and (not (eobp))
            (looking-at paragraph-separate))
       (forward-line 1))

The first argument to the prog1 is the and expression. It has within in it a test of whether point is at the end of the buffer and also a test of whether the pattern following point matches the regular expression for separating paragraphs.

If the cursor is not at the end of the buffer and if the characters following the cursor mark the separation between two paragraphs, then the and expression is true. After evaluating the and expression, the Lisp interpreter evaluates the second argument to prog1, which is forward-line. This moves point forward one line. The value returned by the prog1 however, is the value of its first argument, so the while loop continues so long as point is not at the end of the buffer and is between paragraphs. When, finally, point is moved to a paragraph, the and expression tests false. Note however, that the forward-line command is carried out anyhow. This means that when point is moved from between paragraphs to a paragraph, it is left at the beginning of the second line of the paragraph.

Node:fwd-para within paragraph, Next:fwd-para no fill prefix, Previous:fwd-para between paragraphs, Up:forward-paragraph

Within paragraphs

The next expression in the outer while loop is an if expression. The Lisp interpreter evaluates the then-part of the if when the fill-prefix-regexp variable has a value other than nil, and it evaluates the else-part when the value of if fill-prefix-regexp is nil, that is, when there is no fill prefix.

Node:fwd-para no fill prefix, Next:fwd-para with fill prefix, Previous:fwd-para within paragraph, Up:forward-paragraph

No fill prefix

It is simplest to look at the code for the case when there is no fill prefix first. This code consists of yet another inner if expression, and reads as follows:

(if (re-search-forward paragraph-start nil t)
    (goto-char (match-beginning 0))
  (goto-char (point-max)))

This expression actually does the work that most people think of as the primary purpose of the forward-paragraph command: it causes a regular expression search to occur that searches forward to the start of the next paragraph and if it is found, moves point there; but if the start of another paragraph if not found, it moves point to the end of the accessible region of the buffer.

The only unfamiliar part of this is the use of match-beginning. This is another function that is new to us. The match-beginning function returns a number specifying the location of the start of the text that was matched by the last regular expression search.

The match-beginning function is used here because of a characteristic of a forward search: a successful forward search, regardless of whether it is a plain search or a regular expression search, will move point to the end of the text that is found. In this case, a successful search will move point to the end of the pattern for paragraph-start, which will be the beginning of the next paragraph rather than the end of the current one.

However, we want to put point at the end of the current paragraph, not at the beginning of the next one. The two positions may be different, because there may be several blank lines between paragraphs.

When given an argument of 0, match-beginning returns the position that is the start of the text that the most recent regular expression search matched. In this case, the most recent regular expression search is the one looking for paragraph-start, so match-beginning returns the beginning position of the pattern, rather than the end of the pattern. The beginning position is the end of the paragraph.

(Incidentally, when passed a positive number as an argument, the match-beginning function will place point at that parenthesized expression in the last regular expression. It is a useful function.)

Node:fwd-para with fill prefix, Next:fwd-para summary, Previous:fwd-para no fill prefix, Up:forward-paragraph

With a fill prefix

The inner if expression just discussed is the else-part of an enclosing if expression which tests whether there is a fill prefix. If there is a fill prefix, the then-part of this if is evaluated. It looks like this:

(while (and (not (eobp))
            (not (looking-at paragraph-separate))
            (looking-at fill-prefix-regexp))
  (forward-line 1))

What this expression does is move point forward line by line so long as three conditions are true:

  1. Point is not at the end of the buffer.
  2. The text following point does not separate paragraphs.
  3. The pattern following point is the fill prefix regular expression.

The last condition may be puzzling, until you remember that point was moved to the beginning of the line early in the forward-paragraph function. This means that if the text has a fill prefix, the looking-at function will see it.

Node:fwd-para summary, Previous:fwd-para with fill prefix, Up:forward-paragraph

Summary

In summary, when moving forward, the forward-paragraph function does the following:

  • Move point to the beginning of the line.
  • Skip over lines between paragraphs.
  • Check whether there is a fill prefix, and if there is:
    • Go forward line by line so long as the line is not a paragraph separating line.
  • But if there is no fill prefix,
    • Search for the next paragraph start pattern.
    • Go to the beginning of the paragraph start pattern, which will be the end of the previous paragraph.
    • Or else go to the end of the accessible portion of the buffer.

For review, here is the code we have just been discussing, formatted for clarity:

(interactive "p")
(or arg (setq arg 1))
(let* (
       (fill-prefix-regexp
        (and fill-prefix (not (equal fill-prefix ""))
             (not paragraph-ignore-fill-prefix)
             (regexp-quote fill-prefix)))

       (paragraph-separate
        (if fill-prefix-regexp
            (concat paragraph-separate
                    "\\|^"
                    fill-prefix-regexp
                    "[ \t]*$")
          paragraph-separate)))

  omitted-backward-moving-code ...

  (while (> arg 0)                ; forward-moving-code
    (beginning-of-line)

    (while (prog1 (and (not (eobp))
                       (looking-at paragraph-separate))
             (forward-line 1)))

    (if fill-prefix-regexp
        (while (and (not (eobp))  ; then-part
                    (not (looking-at paragraph-separate))
                    (looking-at fill-prefix-regexp))
          (forward-line 1))
                                  ; else-part: the inner-if
      (if (re-search-forward paragraph-start nil t)
          (goto-char (match-beginning 0))
        (goto-char (point-max))))

    (setq arg (1- arg)))))        ; decrementer

The full definition for the forward-paragraph function not only includes this code for going forwards, but also code for going backwards.

If you are reading this inside of GNU Emacs and you want to see the whole function, you can type C-h f (describe-function) and the name of the function. This gives you the function documentation and the name of the library containing the function's source. Place point over the name of the library and press the RET key; you will be taken directly to the source. (Be sure to install your sources! Without them, you are like a person who tries to drive a car with his eyes shut!)

Or - a good habit to get into - you can type M-. (find-tag) and the name of the function when prompted for it. This will take you directly to the source. If the find-tag function first asks you for the name of a TAGS table, give it the name of the TAGS file such as /usr/local/share/emacs/21.0.100/lisp/TAGS. (The exact path to your TAGS file depends on how your copy of Emacs was installed.)

You can also create your own TAGS file for directories that lack one. See Create Your Own TAGS File.

Node:etags, Next:Regexp Review, Previous:forward-paragraph, Up:Regexp Search

12.5 Create Your Own TAGS File

The M-. (find-tag) command takes you directly to the source for a function, variable, node, or other source. The function depends on tags tables to tell it where to go.

You often need to build and install tags tables yourself. They are not built automatically. A tags table is called a TAGS file; the name is in upper case letters.

You can create a TAGS file by calling the etags program that comes as a part of the Emacs distribution. Usually, etags is compiled and installed when Emacs is built. (etags is not an Emacs Lisp function or a part of Emacs; it is a C program.)

To create a TAGS file, first switch to the directory in which you want to create the file. In Emacs you can do this with the M-x cd command, or by visiting a file in the directory, or by listing the directory with C-x d (dired). Then run the compile command, with etags *.el as the command to execute

M-x compile RET etags *.el RET

to create a TAGS file.

For example, if you have a large number of files in your ~/emacs directory, as I do--I have 137 .el files in it, of which I load 12--you can create a TAGS file for the Emacs Lisp files in that directory.

The etags program takes all the usual shell `wildcards'. For example, if you have two directories for which you want a single TAGS file, type etags *.el ../elisp/*.el, where ../elisp/ is the second directory:

M-x compile RET etags *.el ../elisp/*.el RET

Type

M-x compile RET etags --help RET

to see a list of the options accepted by etags as well as a list of supported languages.

The etags program handles more than 20 languages, including Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, Java, LaTeX, Pascal, Perl, Python, Texinfo, makefiles, and most assemblers. The program has no switches for specifying the language; it recognizes the language in an input file according to its file name and contents.

etags is very helpful when you are writing code yourself and want to refer back to functions you have already written. Just run etags again at intervals as you write new functions, so they become part of the TAGS file.

If you think an appropriate TAGS file already exists for what you want, but do not know where it is, you can use the locate program to attempt to find it.

Type M-x locate RET TAGS RET and Emacs will list for you the full path names of all your TAGS files. On my system, this command lists 34 TAGS files. On the other hand, a `plain vanilla' system I recently installed did not contain any TAGS files.

If the tags table you want has been created, you can use the M-x visit-tags-table command to specify it. Otherwise, you will need to create the tag table yourself and then use M-x visit-tags-table.

Building Tags in the Emacs sources

The GNU Emacs sources come with a Makefile that contains a sophisticated etags command that creates, collects, and merges tags tables from all over the Emacs sources and puts the information into one TAGS file in the src/ directory below the top level of your Emacs source directory.

To build this TAGS file, go to the top level of your Emacs source directory and run the compile command make tags:

M-x compile RET make tags RET

(The make tags command works well with the GNU Emacs sources, as well as with some other source packages.)

For more information, see Tags.

Node:Regexp Review, Next:re-search Exercises, Previous:etags, Up:Regexp Search

12.6 Review

Here is a brief summary of some recently introduced functions.

while
Repeatedly evaluate the body of the expression so long as the first element of the body tests true. Then return nil. (The expression is evaluated only for its side effects.)

For example:

(let ((foo 2))
  (while (> foo 0)
    (insert (format "foo is %d.\n" foo))
    (setq foo (1- foo))))

     =>      foo is 2.
             foo is 1.
             nil

(The insert function inserts its arguments at point; the format function returns a string formatted from its arguments the way message formats its arguments; \n produces a new line.)

re-search-forward
Search for a pattern, and if the pattern is found, move point to rest just after it.

Takes four arguments, like search-forward:

  1. A regular expression that specifies the pattern to search for.
  2. Optionally, the limit of the search.
  3. Optionally, what to do if the search fails, return nil or an error message.
  4. Optionally, how many times to repeat the search; if negative, the search goes backwards.

let*
Bind some variables locally to particular values, and then evaluate the remaining arguments, returning the value of the last one. While binding the local variables, use the local values of variables bound earlier, if any.

For example:

(let* ((foo 7)
      (bar (* 3 foo)))
  (message "`bar' is %d." bar))
     => `bar' is 21.

match-beginning
Return the position of the start of the text found by the last regular expression search.
looking-at
Return t for true if the text after point matches the argument, which should be a regular expression.
eobp
Return t for true if point is at the end of the accessible part of a buffer. The end of the accessible part is the end of the buffer if the buffer is not narrowed; it is the end of the narrowed part if the buffer is narrowed.
prog1
Evaluate each argument in sequence and then return the value of the first.

For example:

(prog1 1 2 3 4)
     => 1

Node:re-search Exercises, Previous:Regexp Review, Up:Regexp Search

12.7 Exercises with re-search-forward

  • Write a function to search for a regular expression that matches two or more blank lines in sequence.
  • Write a function to search for duplicated words, such as `the the'. See Regexps, for information on how to write a regexp (a regular expression) to match a string that is composed of two identical halves. You can devise several regexps; some are better than others. The function I use is described in an appendix, along with several regexps. See the-the Duplicated Words Function.

Node:Counting Words, Next:Words in a defun, Previous:Regexp Search, Up:Top

13 Counting: Repetition and Regexps

Repetition and regular expression searches are powerful tools that you often use when you write code in Emacs Lisp. This chapter illustrates the use of regular expression searches through the construction of word count commands using while loops and recursion.

  • Why Count Words:
  • count-words-region: Use a regexp, but find a problem.
  • recursive-count-words: Start with case of no words in region.
  • Counting Exercise:

Node:Why Count Words, Next:count-words-region, Previous:Counting Words, Up:Counting Words

Counting words

The standard Emacs distribution contains a function for counting the number of lines within a region. However, there is no corresponding function for counting words.

Certain types of writing ask you to count words. Thus, if you write an essay, you may be limited to 800 words; if you write a novel, you may discipline yourself to write 1000 words a day. It seems odd to me that Emacs lacks a word count command. Perhaps people use Emacs mostly for code or types of documentation that do not require word counts; or perhaps they restrict themselves to the operating system word count command, wc. Alternatively, people may follow the publishers' convention and compute a word count by dividing the number of characters in a document by five. In any event, here are commands to count words.

Node:count-words-region, Next:recursive-count-words, Previous:Why Count Words, Up:Counting Words

13.1 The count-words-region Function

A word count command could count words in a line, paragraph, region, or buffer. What should the command cover? You could design the command to count the number of words in a complete buffer. However, the Emacs tradition encourages flexibility--you may want to count words in just a section, rather than all of a buffer. So it makes more sense to design the command to count the number of words in a region. Once you have a count-words-region command, you can, if you wish, count words in a whole buffer by marking it with C-x h (mark-whole-buffer).

Clearly, counting words is a repetitive act: starting from the beginning of the region, you count the first word, then the second word, then the third word, and so on, until you reach the end of the region. This means that word counting is ideally suited to recursion or to a while loop.

  • Design count-words-region: The definition using a while loop.
  • Whitespace Bug: The Whitespace Bug in count-words-region.

Node:Design count-words-region, Next:Whitespace Bug, Previous:count-words-region, Up:count-words-region

Designing count-words-region

First, we will implement the word count command with a while loop, then with recursion. The command will, of course, be interactive.

The template for an interactive function definition is, as always:

(defun name-of-function (argument-list)
  "documentation..."
  (interactive-expression...)
  body...)

What we need to do is fill in the slots.

The name of the function should be self-explanatory and similar to the existing count-lines-region name. This makes the name easier to remember. count-words-region is a good choice.

The function counts words within a region. This means that the argument list must contain symbols that are bound to the two positions, the beginning and end of the region. These two positions can be called beginning and end respectively. The first line of the documentation should be a single sentence, since that is all that is printed as documentation by a command such as apropos. The interactive expression will be of the form (interactive "r"), since that will cause Emacs to pass the beginning and end of the region to the function's argument list. All this is routine.

The body of the function needs to be written to do three tasks: first, to set up conditions under which the while loop can count words, second, to run the while loop, and third, to send a message to the user.

When a user calls count-words-region, point may be at the beginning or the end of the region. However, the counting process must start at the beginning of the region. This means we will want to put point there if it is not already there. Executing (goto-char beginning) ensures this. Of course, we will want to return point to its expected position when the function finishes its work. For this reason, the body must be enclosed in a save-excursion expression.

The central part of the body of the function consists of a while loop in which one expression jumps point forward word by word, and another expression counts those jumps. The true-or-false-test of the while loop should test true so long as point should jump forward, and false when point is at the end of the region.

We could use (forward-word 1) as the expression for moving point forward word by word, but it is easier to see what Emacs identifies as a `word' if we use a regular expression search.

A regular expression search that finds the pattern for which it is searching leaves point after the last character matched. This means that a succession of successful word searches will move point forward word by word.

As a practical matter, we want the regular expression search to jump over whitespace and punctuation between words as well as over the words themselves. A regexp that refuses to jump over interword whitespace would never jump more than one word! This means that the regexp should include the whitespace and punctuation that follows a word, if any, as well as the word itself. (A word may end a buffer and not have any following whitespace or punctuation, so that part of the regexp must be optional.)

Thus, what we want for the regexp is a pattern defining one or more word constituent characters followed, optionally, by one or more characters that are not word constituents. The regular expression for this is:

\w+\W*

The buffer's syntax table determines which characters are and are not word constituents. (See What Constitutes a Word or Symbol?, for more about syntax. Also, see Syntax, and Syntax Tables.)

The search expression looks like this:

(re-search-forward "\\w+\\W*")

(Note that paired backslashes precede the w and W. A single backslash has special meaning to the Emacs Lisp interpreter. It indicates that the following character is interpreted differently than usual. For example, the two characters, \n, stand for newline, rather than for a backslash followed by n. Two backslashes in a row stand for an ordinary, `unspecial' backslash.)

We need a counter to count how many words there are; this variable must first be set to 0 and then incremented each time Emacs goes around the while loop. The incrementing expression is simply:

(setq count (1+ count))

Finally, we want to tell the user how many words there are in the region. The message function is intended for presenting this kind of information to the user. The message has to be phrased so that it reads properly regardless of how many words there are in the region: we don't want to say that "there are 1 words in the region". The conflict between singular and plural is ungrammatical. We can solve this problem by using a conditional expression that evaluates different messages depending on the number of words in the region. There are three possibilities: no words in the region, one word in the region, and more than one word. This means that the cond special form is appropriate.

All this leads to the following function definition:

;;; First version; has bugs!
(defun count-words-region (beginning end)
  "Print number of words in the region.
Words are defined as at least one word-constituent
character followed by at least one character that
is not a word-constituent.  The buffer's syntax
table determines which characters these are."
  (interactive "r")
  (message "Counting words in region ... ")

;;; 1. Set up appropriate conditions.
  (save-excursion
    (goto-char beginning)
    (let ((count 0))

;;; 2. Run the while loop.
      (while (< (point) end)
        (re-search-forward "\\w+\\W*")
        (setq count (1+ count)))

;;; 3. Send a message to the user.
      (cond ((zerop count)
             (message
              "The region does NOT have any words."))
            ((= 1 count)
             (message
              "The region has 1 word."))
            (t
             (message
              "The region has %d words." count))))))

As written, the function works, but not in all circumstances.

Node:Whitespace Bug, Previous:Design count-words-region, Up:count-words-region

13.1.1 The Whitespace Bug in count-words-region

The count-words-region command described in the preceding section has two bugs, or rather, one bug with two manifestations. First, if you mark a region containing only whitespace in the middle of some text, the count-words-region command tells you that the region contains one word! Second, if you mark a region containing only whitespace at the end of the buffer or the accessible portion of a narrowed buffer, the command displays an error message that looks like this:

Search failed: "\\w+\\W*"

If you are reading this in Info in GNU Emacs, you can test for these bugs yourself.

First, evaluate the function in the usual manner to install it.

If you wish, you can also install this keybinding by evaluating it:

(global-set-key "\C-c=" 'count-words-region)

To conduct the first test, set mark and point to the beginning and end of the following line and then type C-c = (or M-x count-words-region if you have not bound C-c =):

    one   two  three

Emacs will tell you, correctly, that the region has three words.

Repeat the test, but place mark at the beginning of the line and place point just before the word one. Again type the command C-c = (or M-x count-words-region). Emacs should tell you that the region has no words, since it is composed only of the whitespace at the beginning of the line. But instead Emacs tells you that the region has one word!

For the third test, copy the sample line to the end of the *scratch* buffer and then type several spaces at the end of the line. Place mark right after the word three and point at the end of line. (The end of the line will be the end of the buffer.) Type C-c = (or M-x count-words-region) as you did before. Again, Emacs should tell you that the region has no words, since it is composed only of the whitespace at the end of the line. Instead, Emacs displays an error message saying Search failed.

The two bugs stem from the same problem.

Consider the first manifestation of the bug, in which the command tells you that the whitespace at the beginning of the line contains one word. What happens is this: The M-x count-words-region command moves point to the beginning of the region. The while tests whether the value of point is smaller than the value of end, which it is. Consequently, the regular expression search looks for and finds the first word. It leaves point after the word. count is set to one. The while loop repeats; but this time the value of point is larger than the value of end, the loop is exited; and the function displays a message saying the number of words in the region is one. In brief, the regular expression search looks for and finds the word even though it is outside the marked region.

In the second manifestation of the bug, the region is whitespace at the end of the buffer. Emacs says Search failed. What happens is that the true-or-false-test in the while loop tests true, so the search expression is executed. But since there are no more words in the buffer, the search fails.

In both manifestations of the bug, the search extends or attempts to extend outside of the region.

The solution is to limit the search to the region--this is a fairly simple action, but as you may have come to expect, it is not quite as simple as you might think.

As we have seen, the re-search-forward function takes a search pattern as its first argument. But in addition to this first, mandatory argument, it accepts three optional arguments. The optional second argument bounds the search. The optional third argument, if t, causes the function to return nil rather than signal an error if the search fails. The optional fourth argument is a repeat count. (In Emacs, you can see a function's documentation by typing C-h f, the name of the function, and then <RET>.)

In the count-words-region definition, the value of the end of the region is held by the variable end which is passed as an argument to the function. Thus, we can add end as an argument to the regular expression search expression:

(re-search-forward "\\w+\\W*" end)

However, if you make only this change to the count-words-region definition and then test the new version of the definition on a stretch of whitespace, you will receive an error message saying Search failed.

What happens is this: the search is limited to the region, and fails as you expect because there are no word-constituent characters in the region. Since it fails, we receive an error message. But we do not want to receive an error message in this case; we want to receive the message that "The region does NOT have any words."

The solution to this problem is to provide re-search-forward with a third argument of t, which causes the function to return nil rather than signal an error if the search fails.

However, if you make this change and try it, you will see the message "Counting words in region ... " and ... you will keep on seeing that message ..., until you type C-g (keyboard-quit).

Here is what happens: the search is limited to the region, as before, and it fails because there are no word-constituent characters in the region, as expected. Consequently, the re-search-forward expression returns nil. It does nothing else. In particular, it does not move point, which it does as a side effect if it finds the search target. After the re-search-forward expression returns nil, the next expression in the while loop is evaluated. This expression increments the count. Then the loop repeats. The true-or-false-test tests true because the value of point is still less than the value of end, since the re-search-forward expression did not move point. ... and the cycle repeats ...

The count-words-region definition requires yet another modification, to cause the true-or-false-test of the while loop to test false if the search fails. Put another way, there are two conditions that must be satisfied in the true-or-false-test before the word count variable is incremented: point must still be within the region and the search expression must have found a word to count.

Since both the first condition and the second condition must be true together, the two expressions, the region test and the search expression, can be joined with an and special form and embedded in the while loop as the true-or-false-test, like this:

(and (< (point) end) (re-search-forward "\\w+\\W*" end t))

The re-search-forward expression returns t if the search succeeds and as a side effect moves point. Consequently, as words are found, point is moved through the region. When the search expression fails to find another word, or when point reaches the end of the region, the true-or-false-test tests false, the while loop exists, and the count-words-region function displays one or other of its messages.

After incorporating these final changes, the count-words-region works without bugs (or at least, without bugs that I have found!). Here is what it looks like:

;;; Final version: while
(defun count-words-region (beginning end)
  "Print number of words in the region."
  (interactive "r")
  (message "Counting words in region ... ")

;;; 1. Set up appropriate conditions.
  (save-excursion
    (let ((count 0))
      (goto-char beginning)

;;; 2. Run the while loop.
      (while (and (< (point) end)
                  (re-search-forward "\\w+\\W*" end t))
        (setq count (1+ count)))

;;; 3. Send a message to the user.
      (cond ((zerop count)
             (message
              "The region does NOT have any words."))
            ((= 1 count)
             (message
              "The region has 1 word."))
            (t
             (message
              "The region has %d words." count))))))

Node:recursive-count-words, Next:Counting Exercise, Previous:count-words-region, Up:Counting Words

13.2 Count Words Recursively

You can write the function for counting words recursively as well as with a while loop. Let's see how this is done.

First, we need to recognize that the count-words-region function has three jobs: it sets up the appropriate conditions for counting to occur; it counts the words in the region; and it sends a message to the user telling how many words there are.

If we write a single recursive function to do everything, we will receive a message for every recursive call. If the region contains 13 words, we will receive thirteen messages, one right after the other. We don't want this! Instead, we must write two functions to do the job, one of which (the recursive function) will be used inside of the other. One function will set up the conditions and display the message; the other will return the word count.

Let us start with the function that causes the message to be displayed. We can continue to call this count-words-region.

This is the function that the user will call. It will be interactive. Indeed, it will be similar to our previous versions of this function, except that it will call recursive-count-words to determine how many words are in the region.

We can readily construct a template for this function, based on our previous versions:

;; Recursive version; uses regular expression search
(defun count-words-region (beginning end)
  "documentation..."
  (interactive-expression...)

;;; 1. Set up appropriate conditions.
  (explanatory message)
  (set-up functions...

;;; 2. Count the words.
    recursive call

;;; 3. Send a message to the user.
    message providing word count))

The definition looks straightforward, except that somehow the count returned by the recursive call must be passed to the message displaying the word count. A little thought suggests that this can be done by making use of a let expression: we can bind a variable in the varlist of a let expression to the number of words in the region, as returned by the recursive call; and then the cond expression, using binding, can display the value to the user.

Often, one thinks of the binding within a let expression as somehow secondary to the `primary' work of a function. But in this case, what you might consider the `primary' job of the function, counting words, is done within the let expression.

Using let, the function definition looks like this:

(defun count-words-region (beginning end)
  "Print number of words in the region."
  (interactive "r")

;;; 1. Set up appropriate conditions.
  (message "Counting words in region ... ")
  (save-excursion
    (goto-char beginning)

;;; 2. Count the words.
    (let ((count (recursive-count-words end)))

;;; 3. Send a message to the user.
      (cond ((zerop count)
             (message
              "The region does NOT have any words."))
            ((= 1 count)
             (message
              "The region has 1 word."))
            (t
             (message
              "The region has %d words." count))))))

Next, we need to write the recursive counting function.

A recursive function has at least three parts: the `do-again-test', the `next-step-expression', and the recursive call.

The do-again-test determines whether the function will or will not be called again. Since we are counting words in a region and can use a function that moves point forward for every word, the do-again-test can check whether point is still within the region. The do-again-test should find the value of point and determine whether point is before, at, or after the value of the end of the region. We can use the point function to locate point. Clearly, we must pass the value of the end of the region to the recursive counting function as an argument.

In addition, the do-again-test should also test whether the search finds a word. If it does not, the function should not call itself again.

The next-step-expression changes a value so that when the recursive function is supposed to stop calling itself, it stops. More precisely, the next-step-expression changes a value so that at the right time, the do-again-test stops the recursive function from calling itself again. In this case, the next-step-expression can be the expression that moves point forward, word by word.

The third part of a recursive function is the recursive call.

Somewhere, also, we also need a part that does the `work' of the function, a part that does the counting. A vital part!

But already, we have an outline of the recursive counting function:

(defun recursive-count-words (region-end)
  "documentation..."
   do-again-test
   next-step-expression
   recursive call)

Now we need to fill in the slots. Let's start with the simplest cases first: if point is at or beyond the end of the region, there cannot be any words in the region, so the function should return zero. Likewise, if the search fails, there are no words to count, so the function should return zero.

On the other hand, if point is within the region and the search succeeds, the function should call itself again.

Thus, the do-again-test should look like this:

(and (< (point) region-end)
     (re-search-forward "\\w+\\W*" region-end t))

Note that the search expression is part of the do-again-test--the function returns t if its search succeeds and nil if it fails. (See The Whitespace Bug in count-words-region, for an explanation of how re-search-forward works.)

The do-again-test is the true-or-false test of an if clause. Clearly, if the do-again-test succeeds, the then-part of the if clause should call the function again; but if it fails, the else-part should return zero since either point is outside the region or the search failed because there were no words to find.

But before considering the recursive call, we need to consider the next-step-expression. What is it? Interestingly, it is the search part of the do-again-test.

In addition to returning t or nil for the do-again-test, re-search-forward moves point forward as a side effect of a successful search. This is the action that changes the value of point so that the recursive function stops calling itself when point completes its movement through the region. Consequently, the re-search-forward expression is the next-step-expression.

In outline, then, the body of the recursive-count-words function looks like this:

(if do-again-test-and-next-step-combined
    ;; then
    recursive-call-returning-count
  ;; else
  return-zero)

How to incorporate the mechanism that counts?

If you are not used to writing recursive functions, a question like this can be troublesome. But it can and should be approached systematically.

We know that the counting mechanism should be associated in some way with the recursive call. Indeed, since the next-step-expression moves point forward by one word, and since a recursive call is made for each word, the counting mechanism must be an expression that adds one to the value returned by a call to recursive-count-words.

Consider several cases:

  • If there are two words in the region, the function should return a value resulting from adding one to the value returned when it counts the first word, plus the number returned when it counts the remaining words in the region, which in this case is one.
  • If there is one word in the region, the function should return a value resulting from adding one to the value returned when it counts that word, plus the number returned when it counts the remaining words in the region, which in this case is zero.
  • If there are no words in the region, the function should return zero.

From the sketch we can see that the else-part of the if returns zero for the case of no words. This means that the then-part of the if must return a value resulting from adding one to the value returned from a count of the remaining words.

The expression will look like this, where 1+ is a function that adds one to its argument.

(1+ (recursive-count-words region-end))

The whole recursive-count-words function will then look like this:

(defun recursive-count-words (region-end)
  "documentation..."

;;; 1. do-again-test
  (if (and (< (point) region-end)
           (re-search-forward "\\w+\\W*" region-end t))

;;; 2. then-part: the recursive call
      (1+ (recursive-count-words region-end))

;;; 3. else-part
    0))

Let's examine how this works:

If there are no words in the region, the else part of the if expression is evaluated and consequently the function returns zero.

If there is one word in the region, the value of point is less than the value of region-end and the search succeeds. In this case, the true-or-false-test of the if expression tests true, and the then-part of the if expression is evaluated. The counting expression is evaluated. This expression returns a value (which will be the value returned by the whole function) that is the sum of one added to the value returned by a recursive call.

Meanwhile, the next-step-expression has caused point to jump over the first (and in this case only) word in the region. This means that when (recursive-count-words region-end) is evaluated a second time, as a result of the recursive call, the value of point will be equal to or greater than the value of region end. So this time, recursive-count-words will return zero. The zero will be added to one, and the original evaluation of recursive-count-words will return one plus zero, which is one, which is the correct amount.

Clearly, if there are two words in the region, the first call to recursive-count-words returns one added to the value returned by calling recursive-count-words on a region containing the remaining word--that is, it adds one to one, producing two, which is the correct amount.

Similarly, if there are three words in the region, the first call to recursive-count-words returns one added to the value returned by calling recursive-count-words on a region containing the remaining two words--and so on and so on.

With full documentation the two functions look like this:

The recursive function:

(defun recursive-count-words (region-end)
  "Number of words between point and REGION-END."

;;; 1. do-again-test
  (if (and (< (point) region-end)
           (re-search-forward "\\w+\\W*" region-end t))

;;; 2. then-part: the recursive call
      (1+ (recursive-count-words region-end))

;;; 3. else-part
    0))

The wrapper:

;;; Recursive version
(defun count-words-region (beginning end)
  "Print number of words in the region.

Words are defined as at least one word-constituent
character followed by at least one character that is
not a word-constituent.  The buffer's syntax table
determines which characters these are."
  (interactive "r")
  (message "Counting words in region ... ")
  (save-excursion
    (goto-char beginning)
    (let ((count (recursive-count-words end)))
      (cond ((zerop count)
             (message
              "The region does NOT have any words."))
            ((= 1 count)
             (message "The region has 1 word."))
            (t
             (message
              "The region has %d words." count))))))

Node:Counting Exercise, Previous:recursive-count-words, Up:Counting Words

13.3 Exercise: Counting Punctuation

Using a while loop, write a function to count the number of punctuation marks in a region--period, comma, semicolon, colon, exclamation mark, and question mark. Do the same using recursion.

Node:Words in a defun, Next:Readying a Graph, Previous:Counting Words, Up:Top

14 Counting Words in a defun

Our next project is to count the number of words in a function definition. Clearly, this can be done using some variant of count-word-region. See Counting Words: Repetition and Regexps. If we are just going to count the words in one definition, it is easy enough to mark the definition with the C-M-h (mark-defun) command, and then call count-word-region.

However, I am more ambitious: I want to count the words and symbols in every definition in the Emacs sources and then print a graph that shows how many functions there are of each length: how many contain 40 to 49 words or symbols, how many contain 50 to 59 words or symbols, and so on. I have often been curious how long a typical function is, and this will tell.

  • Divide and Conquer:
  • Words and Symbols: What to count?
  • Syntax: What constitutes a word or symbol?
  • count-words-in-defun: Very like count-words.
  • Several defuns: Counting several defuns in a file.
  • Find a File: Do you want to look at a file?
  • lengths-list-file: A list of the lengths of many definitions.
  • Several files: Counting in definitions in different files.
  • Several files recursively: Recursively counting in different files.
  • Prepare the data: Prepare the data for display in a graph.

Node:Divide and Conquer, Next:Words and Symbols, Previous:Words in a defun, Up:Words in a defun

Divide and Conquer

Described in one phrase, the histogram project is daunting; but divided into numerous small steps, each of which we can take one at a time, the project becomes less fearsome. Let us consider what the steps must be:

  • First, write a function to count the words in one definition. This includes the problem of handling symbols as well as words.
  • Second, write a function to list the numbers of words in each function in a file. This function can use the count-words-in-defun function.
  • Third, write a function to list the numbers of words in each function in each of several files. This entails automatically finding the various files, switching to them, and counting the words in the definitions within them.
  • Fourth, write a function to convert the list of numbers that we created in step three to a form that will be suitable for printing as a graph.
  • Fifth, write a function to print the results as a graph.

This is quite a project! But if we take each step slowly, it will not be difficult.

Node:Words and Symbols, Next:Syntax, Previous:Divide and Conquer, Up:Words in a defun

14.1 What to Count?

When we first start thinking about how to count the words in a function definition, the first question is (or ought to be) what are we going to count? When we speak of `words' with respect to a Lisp function definition, we are actually speaking, in large part, of `symbols'. For example, the following multiply-by-seven function contains the five symbols defun, multiply-by-seven, number, *, and 7. In addition, in the documentation string, it contains the four words Multiply, NUMBER, by, and seven. The symbol number is repeated, so the definition contains a total of ten words and symbols.

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

However, if we mark the multiply-by-seven definition with C-M-h (mark-defun), and then call count-words-region on it, we will find that count-words-region claims the definition has eleven words, not ten! Something is wrong!

The problem is twofold: count-words-region does not count the * as a word, and it counts the single symbol, multiply-by-seven, as containing three words. The hyphens are treated as if they were interword spaces rather than intraword connectors: multiply-by-seven is counted as if it were written multiply by seven.

The cause of this confusion is the regular expression search within the count-words-region definition that moves point forward word by word. In the canonical version of count-words-region, the regexp is:

"\\w+\\W*"

This regular expression is a pattern defining one or more word constituent characters possibly followed by one or more characters that are not word constituents. What is meant by `word constituent characters' brings us to the issue of syntax, which is worth a section of its own.

Node:Syntax, Next:count-words-in-defun, Previous:Words and Symbols, Up:Words in a defun

14.2 What Constitutes a Word or Symbol?

Emacs treats different characters as belonging to different syntax categories. For example, the regular expression, \\w+, is a pattern specifying one or more word constituent characters. Word constituent characters are members of one syntax category. Other syntax categories include the class of punctuation characters, such as the period and the comma, and the class of whitespace characters, such as the blank space and the tab character. (For more information, see Syntax, and Syntax Tables.)

Syntax tables specify which characters belong to which categories. Usually, a hyphen is not specified as a `word constituent character'. Instead, it is specified as being in the `class of characters that are part of symbol names but not words.' This means that the count-words-region function treats it in the same way it treats an interword white space, which is why count-words-region counts multiply-by-seven as three words.

There are two ways to cause Emacs to count multiply-by-seven as one symbol: modify the syntax table or modify the regular expression.

We could redefine a hyphen as a word constituent character by modifying the syntax table that Emacs keeps for each mode. This action would serve our purpose, except that a hyphen is merely the most common character within symbols that is not typically a word constituent character; there are others, too.

Alternatively, we can redefine the regular expression used in the count-words definition so as to include symbols. This procedure has the merit of clarity, but the task is a little tricky.

The first part is simple enough: the pattern must match "at least one character that is a word or symbol constituent". Thus:

"\\(\\w\\|\\s_\\)+"

The \\( is the first part of the grouping construct that includes the \\w and the \\s_ as alternatives, separated by the \\|. The \\w matches any word-constituent character and the \\s_ matches any character that is part of a symbol name but not a word-constituent character. The + following the group indicates that the word or symbol constituent characters must be matched at least once.

However, the second part of the regexp is more difficult to design. What we want is to follow the first part with "optionally one or more characters that are not constituents of a word or symbol". At first, I thought I could define this with the following:

"\\(\\W\\|\\S_\\)*"

The upper case W and S match characters that are not word or symbol constituents. Unfortunately, this expression matches any character that is either not a word constituent or not a symbol constituent. This matches any character!

I then noticed that every word or symbol in my test region was followed by white space (blank space, tab, or newline). So I tried placing a pattern to match one or more blank spaces after the pattern for one or more word or symbol constituents. This failed, too. Words and symbols are often separated by whitespace, but in actual code parentheses may follow symbols and punctuation may follow words. So finally, I designed a pattern in which the word or symbol constituents are followed optionally by characters that are not white space and then followed optionally by white space.

Here is the full regular expression:

"\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"

Node:count-words-in-defun, Next:Several defuns, Previous:Syntax, Up:Words in a defun

14.3 The count-words-in-defun Function

We have seen that there are several ways to write a count-word-region function. To write a count-words-in-defun, we need merely adapt one of these versions.

The version that uses a while loop is easy to understand, so I am going to adapt that. Because count-words-in-defun will be part of a more complex program, it need not be interactive and it need not display a message but just return the count. These considerations simplify the definition a little.

On the other hand, count-words-in-defun will be used within a buffer that contains function definitions. Consequently, it is reasonable to ask that the function determine whether it is called when point is within a function definition, and if it is, to return the count for that definition. This adds complexity to the definition, but saves us from needing to pass arguments to the function.

These considerations lead us to prepare the following template:

(defun count-words-in-defun ()
  "documentation..."
  (set up...
     (while loop...)
   return count)

As usual, our job is to fill in the slots.

First, the set up.

We are presuming that this function will be called within a buffer containing function definitions. Point will either be within a function definition or not. For count-words-in-defun to work, point must move to the beginning of the definition, a counter must start at zero, and the counting loop must stop when point reaches the end of the definition.

The beginning-of-defun function searches backwards for an opening delimiter such as a ( at the beginning of a line, and moves point to that position, or else to the limit of the search. In practice, this means that beginning-of-defun moves point to the beginning of an enclosing or preceding function definition, or else to the beginning of the buffer. We can use beginning-of-defun to place point where we wish to start.

The while loop requires a counter to keep track of the words or symbols being counted. A let expression can be used to create a local variable for this purpose, and bind it to an initial value of zero.

The end-of-defun function works like beginning-of-defun except that it moves point to the end of the definition. end-of-defun can be used as part of an expression that determines the position of the end of the definition.

The set up for count-words-in-defun takes shape rapidly: first we move point to the beginning of the definition, then we create a local variable to hold the count, and finally, we record the position of the end of the definition so the while loop will know when to stop looping.

The code looks like this:

(beginning-of-defun)
(let ((count 0)
      (end (save-excursion (end-of-defun) (point))))

The code is simple. The only slight complication is likely to concern end: it is bound to the position of the end of the definition by a save-excursion expression that returns the value of point after end-of-defun temporarily moves it to the end of the definition.

The second part of the count-words-in-defun, after the set up, is the while loop.

The loop must contain an expression that jumps point forward word by word and symbol by symbol, and another expression that counts the jumps. The true-or-false-test for the while loop should test true so long as point should jump forward, and false when point is at the end of the definition. We have already redefined the regular expression for this (see Syntax), so the loop is straightforward:

(while (and (< (point) end)
            (re-search-forward
             "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
  (setq count (1+ count)))

The third part of the function definition returns the count of words and symbols. This part is the last expression within the body of the let expression, and can be, very simply, the local variable count, which when evaluated returns the count.

Put together, the count-words-in-defun definition looks like this:

(defun count-words-in-defun ()
  "Return the number of words and symbols in a defun."
  (beginning-of-defun)
  (let ((count 0)
        (end (save-excursion (end-of-defun) (point))))
    (while
        (and (< (point) end)
             (re-search-forward
              "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
              end t))
      (setq count (1+ count)))
    count))

How to test this? The function is not interactive, but it is easy to put a wrapper around the function to make it interactive; we can use almost the same code as for the recursive version of count-words-region:

;;; Interactive version.
(defun count-words-defun ()
  "Number of words and symbols in a function definition."
  (interactive)
  (message
   "Counting words and symbols in function definition ... ")
  (let ((count (count-words-in-defun)))
    (cond
     ((zerop count)
      (message
       "The definition does NOT have any words or symbols."))
     ((= 1 count)
      (message
       "The definition has 1 word or symbol."))
     (t
      (message
       "The definition has %d words or symbols." count)))))

Let's re-use C-c = as a convenient keybinding:

(global-set-key "\C-c=" 'count-words-defun)

Now we can try out count-words-defun: install both count-words-in-defun and count-words-defun, and set the keybinding, and then place the cursor within the following definition:

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))
     => 10

Success! The definition has 10 words and symbols.

The next problem is to count the numbers of words and symbols in several definitions within a single file.

Node:Several defuns, Next:Find a File, Previous:count-words-in-defun, Up:Words in a defun

14.4 Count Several defuns Within a File

A file such as simple.el may have 80 or more function definitions within it. Our long term goal is to collect statistics on many files, but as a first step, our immediate goal is to collect statistics on one file.

The information will be a series of numbers, each number being the length of a function definition. We can store the numbers in a list.

We know that we will want to incorporate the information regarding one file with information about many other files; this means that the function for counting definition lengths within one file need only return the list of lengths. It need not and should not display any messages.

The word count commands contain one expression to jump point forward word by word and another expression to count the jumps. The function to return the lengths of definitions can be designed to work the same way, with one expression to jump point forward definition by definition and another expression to construct the lengths' list.

This statement of the problem makes it elementary to write the function definition. Clearly, we will start the count at the beginning of the file, so the first command will be (goto-char (point-min)). Next, we start the while loop; and the true-or-false test of the loop can be a regular expression search for the next function definition--so long as the search succeeds, point is moved forward and then the body of the loop is evaluated. The body needs an expression that constructs the lengths' list. cons, the list construction command, can be used to create the list. That is almost all there is to it.

Here is what this fragment of code looks like:

(goto-char (point-min))
(while (re-search-forward "^(defun" nil t)
  (setq lengths-list
        (cons (count-words-in-defun) lengths-list)))

What we have left out is the mechanism for finding the file that contains the function definitions.

In previous examples, we either used this, the Info file, or we switched back and forth to some other buffer, such as the *scratch* buffer.

Finding a file is a new process that we have not yet discussed.

Node:Find a File, Next:lengths-list-file, Previous:Several defuns, Up:Words in a defun

14.5 Find a File

To find a file in Emacs, you use the C-x C-f (find-file) command. This command is almost, but not quite right for the lengths problem.

Let's look at the source for find-file (you can use the find-tag command or C-h f (describe-function) to find the source of a function):

(defun find-file (filename)
  "Edit file FILENAME.
Switch to a buffer visiting file FILENAME,
creating one if none already exists."
  (interactive "FFind file: ")
  (switch-to-buffer (find-file-noselect filename)))

The definition possesses short but complete documentation and an interactive specification that prompts you for a file name when you use the command interactively. The body of the definition contains two functions, find-file-noselect and switch-to-buffer.

According to its documentation as shown by C-h f (the describe-function command), the find-file-noselect function reads the named file into a buffer and returns the buffer. However, the buffer is not selected. Emacs does not switch its attention (or yours if you are using find-file-noselect) to the named buffer. That is what switch-to-buffer does: it switches the buffer to which Emacs attention is directed; and it switches the buffer displayed in the window to the new buffer. We have discussed buffer switching elsewhere. (See Switching Buffers.)

In this histogram project, we do not need to display each file on the screen as the program determines the length of each definition within it. Instead of employing switch-to-buffer, we can work with set-buffer, which redirects the attention of the computer program to a different buffer but does not redisplay it on the screen. So instead of calling on find-file to do the job, we must write our own expression.

The task is easy: use find-file-noselect and set-buffer.

Node:lengths-list-file, Next:Several files, Previous:Find a File, Up:Words in a defun

14.6 lengths-list-file in Detail

The core of the lengths-list-file function is a while loop containing a function to move point forward `defun by defun' and a function to count the number of words and symbols in each defun. This core must be surrounded by functions that do various other tasks, including finding the file, and ensuring that point starts out at the beginning of the file. The function definition looks like this:

(defun lengths-list-file (filename)
  "Return list of definitions' lengths within FILE.
The returned list is a list of numbers.
Each number is the number of words or
symbols in one function definition."
  (message "Working on `%s' ... " filename)
  (save-excursion
    (let ((buffer (find-file-noselect filename))
          (lengths-list))
      (set-buffer buffer)
      (setq buffer-read-only t)
      (widen)
      (goto-char (point-min))
      (while (re-search-forward "^(defun" nil t)
        (setq lengths-list
              (cons (count-words-in-defun) lengths-list)))
      (kill-buffer buffer)
      lengths-list)))

The function is passed one argument, the name of the file on which it will work. It has four lines of documentation, but no interactive specification. Since people worry that a computer is broken if they don't see anything going on, the first line of the body is a message.

The next line contains a save-excursion that returns Emacs' attention to the current buffer when the function completes. This is useful in case you embed this function in another function that presumes point is restored to the original buffer.

In the varlist of the let expression, Emacs finds the file and binds the local variable buffer to the buffer containing the file. At the same time, Emacs creates lengths-list as a local variable.

Next, Emacs switches its attention to the buffer.

In the following line, Emacs makes the buffer read-only. Ideally, this line is not necessary. None of the functions for counting words and symbols in a function definition should change the buffer. Besides, the buffer is not going to be saved, even if it were changed. This line is entirely the consequence of great, perhaps excessive, caution. The reason for the caution is that this function and those it calls work on the sources for Emacs and it is very inconvenient if they are inadvertently modified. It goes without saying that I did not realize a need for this line until an experiment went awry and started to modify my Emacs source files ...

Next comes a call to widen the buffer if it is narrowed. This function is usually not needed--Emacs creates a fresh buffer if none already exists; but if a buffer visiting the file already exists Emacs returns that one. In this case, the buffer may be narrowed and must be widened. If we wanted to be fully `user-friendly', we would arrange to save the restriction and the location of point, but we won't.

The (goto-char (point-min)) expression moves point to the beginning of the buffer.

Then comes a while loop in which the `work' of the function is carried out. In the loop, Emacs determines the length of each definition and constructs a lengths' list containing the information.

Emacs kills the buffer after working through it. This is to save space inside of Emacs. My version of Emacs 19 contained over 300 source files of interest; Emacs 21 contains over 800 source files. Another function will apply lengths-list-file to each of the files.

Finally, the last expression within the let expression is the lengths-list variable; its value is returned as the value of the whole function.

You can try this function by installing it in the usual fashion. Then place your cursor after the following expression and type C-x C-e (eval-last-sexp).

(lengths-list-file
 "/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el")

(You may need to change the pathname of the file; the one here worked with GNU Emacs version 21.0.100. To change the expression, copy it to the *scratch* buffer and edit it.

(Also, to see the full length of the list, rather than a truncated version, you may have to evaluate the following:

(custom-set-variables '(eval-expression-print-length nil))

(See Setting Variables with defcustom. Then evaluate the lengths-list-file expression.)

The lengths' list for debug.el takes less than a second to produce and looks like this:

(77 95 85 87 131 89 50 25 44 44 68 35 64 45 17 34 167 457)

(Using my old machine, the version 19 lengths' list for debug.el took seven seconds to produce and looked like this:

(75 41 80 62 20 45 44 68 45 12 34 235)

(The newer version of debug.el contains more defuns than the earlier one; and my new machine is much faster than the old one.)

Note that the length of the last definition in the file is first in the list.

Node:Several files, Next:Several files recursively, Previous:lengths-list-file, Up:Words in a defun

14.7 Count Words in defuns in Different Files

In the previous section, we created a function that returns a list of the lengths of each definition in a file. Now, we want to define a function to return a master list of the lengths of the definitions in a list of files.

Working on each of a list of files is a repetitious act, so we can use either a while loop or recursion.

  • lengths-list-many-files: Return a list of the lengths of defuns.
  • append: Attach one list to another.

Node:lengths-list-many-files, Next:append, Previous:Several files, Up:Several files

Determine the lengths of defuns

The design using a while loop is routine. The argument passed the function is a list of files. As we saw earlier (see Loop Example), you can write a while loop so that the body of the loop is evaluated if such a list contains elements, but to exit the loop if the list is empty. For this design to work, the body of the loop must contain an expression that shortens the list each time the body is evaluated, so that eventually the list is empty. The usual technique is to set the value of the list to the value of the CDR of the list each time the body is evaluated.

The template looks like this:

(while test-whether-list-is-empty
  body...
  set-list-to-cdr-of-list)

Also, we remember that a while loop returns nil (the result of evaluating the true-or-false-test), not the result of any evaluation within its body. (The evaluations within the body of the loop are done for their side effects.) However, the expression that sets the lengths' list is part of the body--and that is the value that we want returned by the function as a whole. To do this, we enclose the while loop within a let expression, and arrange that the last element of the let expression contains the value of the lengths' list. (See Loop Example with an Incrementing Counter.)

These considerations lead us directly to the function itself:

;;; Use while loop.
(defun lengths-list-many-files (list-of-files)
  "Return list of lengths of defuns in LIST-OF-FILES."
  (let (lengths-list)

;;; true-or-false-test
    (while list-of-files
      (setq lengths-list
            (append
             lengths-list

;;; Generate a lengths' list.
             (lengths-list-file
              (expand-file-name (car list-of-files)))))

;;; Make files' list shorter.
      (setq list-of-files (cdr list-of-files)))

;;; Return final value of lengths' list.
    lengths-list))

expand-file-name is a built-in function that converts a file name to the absolute, long, path name form of the directory in which the function is called.

Thus, if expand-file-name is called on debug.el when Emacs is visiting the /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/ directory,

debug.el

becomes

/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el

The only other new element of this function definition is the as yet unstudied function append, which merits a short section for itself.

Node:append, Previous:lengths-list-many-files, Up:Several files

14.7.1 The append Function

The append function attaches one list to another. Thus,

(append '(1 2 3 4) '(5 6 7 8))

produces the list

(1 2 3 4 5 6 7 8)

This is exactly how we want to attach two lengths' lists produced by lengths-list-file to each other. The results contrast with cons,

(cons '(1 2 3 4) '(5 6 7 8))

which constructs a new list in which the first argument to cons becomes the first element of the new list:

((1 2 3 4) 5 6 7 8)

Node:Several files recursively, Next:Prepare the data, Previous:Several files, Up:Words in a defun

14.8 Recursively Count Words in Different Files

Besides a while loop, you can work on each of a list of files with recursion. A recursive version of lengths-list-many-files is short and simple.

The recursive function has the usual parts: the `do-again-test', the `next-step-expression', and the recursive call. The `do-again-test' determines whether the function should call itself again, which it will do if the list-of-files contains any remaining elements; the `next-step-expression' resets the list-of-files to the CDR of itself, so eventually the list will be empty; and the recursive call calls itself on the shorter list. The complete function is shorter than this description!

(defun recursive-lengths-list-many-files (list-of-files)
  "Return list of lengths of each defun in LIST-OF-FILES."
  (if list-of-files                     ; do-again-test
      (append
       (lengths-list-file
        (expand-file-name (car list-of-files)))
       (recursive-lengths-list-many-files
        (cdr list-of-files)))))

In a sentence, the function returns the lengths' list for the first of the list-of-files appended to the result of calling itself on the rest of the list-of-files.

Here is a test of recursive-lengths-list-many-files, along with the results of running lengths-list-file on each of the files individually.

Install recursive-lengths-list-many-files and lengths-list-file, if necessary, and then evaluate the following expressions. You may need to change the files' pathnames; those here work when this Info file and the Emacs sources are located in their customary places. To change the expressions, copy them to the *scratch* buffer, edit them, and then evaluate them.

The results are shown after the =>. (These results are for files from Emacs Version 21.0.100; files from other versions of Emacs may produce different results.)

(cd "/usr/local/share/emacs/21.0.100/")

(lengths-list-file "./lisp/macros.el")
     => (273 263 456 90)

(lengths-list-file "./lisp/mail/mailalias.el")
     => (38 32 26 77 174 180 321 198 324)

(lengths-list-file "./lisp/makesum.el")
     => (85 181)

(recursive-lengths-list-many-files
 '("./lisp/macros.el"
   "./lisp/mail/mailalias.el"
   "./lisp/makesum.el"))
       => (273 263 456 90 38 32 26 77 174 180 321 198 324 85 181)

The recursive-lengths-list-many-files function produces the output we want.

The next step is to prepare the data in the list for display in a graph.

Node:Prepare the data, Previous:Several files recursively, Up:Words in a defun

14.9 Prepare the Data for Display in a Graph

The recursive-lengths-list-many-files function returns a list of numbers. Each number records the length of a function definition. What we need to do now is transform this data into a list of numbers suitable for generating a graph. The new list will tell how many functions definitions contain less than 10 words and symbols, how many contain between 10 and 19 words and symbols, how many contain between 20 and 29 words and symbols, and so on.

In brief, we need to go through the lengths' list produced by the recursive-lengths-list-many-files function and count the number of defuns within each range of lengths, and produce a list of those numbers.

Based on what we have done before, we can readily foresee that it should not be too hard to write a function that `CDRs' down the lengths' list, looks at each element, determines which length range it is in, and increments a counter for that range.

However, before beginning to write such a function, we should consider the advantages of sorting the lengths' list first, so the numbers are ordered from smallest to largest. First, sorting will make it easier to count the numbers in each range, since two adjacent numbers will either be in the same length range or in adjacent ranges. Second, by inspecting a sorted list, we can discover the highest and lowest number, and thereby determine the largest and smallest length range that we will need.

  • Sorting: Sorting lists.
  • Files List: Making a list of files.
  • Counting function definitions:

Node:Sorting, Next:Files List, Previous:Prepare the data, Up:Prepare the data

14.9.1 Sorting Lists

Emacs contains a function to sort lists, called (as you might guess) sort. The sort function takes two arguments, the list to be sorted, and a predicate that determines whether the first of two list elements is "less" than the second.

As we saw earlier (see Using the Wrong Type Object as an Argument), a predicate is a function that determines whether some property is true or false. The sort function will reorder a list according to whatever property the predicate uses; this means that sort can be used to sort non-numeric lists by non-numeric criteria--it can, for example, alphabetize a list.

The < function is used when sorting a numeric list. For example,

(sort '(4 8 21 17 33 7 21 7) '<)

produces this:

(4 7 7 8 17 21 21 33)

(Note that in this example, both the arguments are quoted so that the symbols are not evaluated before being passed to sort as arguments.)

Sorting the list returned by the recursive-lengths-list-many-files function is straightforward; it uses the < function:

(sort
 (recursive-lengths-list-many-files
  '("../lisp/macros.el"
    "../lisp/mailalias.el"
    "../lisp/makesum.el"))
 '<

which produces:

(85 86 116 122 154 176 179 265)

(Note that in this example, the first argument to sort is not quoted, since the expression must be evaluated so as to produce the list that is passed to sort.)

Node:Files List, Next:Counting function definitions, Previous:Sorting, Up:Prepare the data

14.9.2 Making a List of Files

The recursive-lengths-list-many-files function requires a list of files as its argument. For our test examples, we constructed such a list by hand; but the Emacs Lisp source directory is too large for us to do for that. Instead, we will write a function to do the job for us. In this function, we will use both a while loop and a recursive call.

We did not have to write a function like this for older versions of GNU Emacs, since they placed all the .el files in one directory. Instead, we were able to use the directory-files function, which lists the names of files that match a specified pattern within a single directory.

However, recent versions of Emacs place Emacs Lisp files in sub-directories of the top level lisp directory. This re-arrangement eases navigation. For example, all the mail related files are in a lisp sub-directory called mail. But at the same time, this arrangement forces us to create a file listing function that descends into the sub-directories.

We can create this function, called files-in-below-directory, using familiar functions such as car, nthcdr, and substring in conjunction with an existing function called directory-files-and-attributes. This latter function not only lists all the filenames in a directory, including the names of sub-directories, but also their attributes.

To restate our goal: to create a function that will enable us to feed filenames to recursive-lengths-list-many-files as a list that looks like this (but with more elements):

("../lisp/macros.el"
 "../lisp/mail/rmail.el"
 "../lisp/makesum.el")

The directory-files-and-attributes function returns a list of lists. Each of the lists within the main list consists of 13 elements. The first element is a string that contains the name of the file - which, in GNU/Linux, may be a `directory file', that is to say, a file with the special attributes of a directory. The second element of the list is t for a directory, a string for symbolic link (the string is the name linked to), or nil.

For example, the first .el file in the lisp/ directory is abbrev.el. Its name is /usr/local/share/emacs/21.0.100/lisp/abbrev.el and it is not a directory or a symbolic link.

This is how directory-files-and-attributes lists that file and its attributes:

("/usr/local/share/emacs/21.0.100/lisp/abbrev.el"
nil
1
1000
100
(15019 32380)
(14883 48041)
(15214 49336)
11583
"-rw-rw-r--"
t
341385
776)

On the other hand, mail/ is a directory within the lisp/ directory. The beginning of its listing looks like this:

("/usr/local/share/emacs/21.0.100/lisp/mail"
t
...
)

(Look at the documentation of file-attributes to learn about the different attributes. Bear in mind that the file-attributes function does not list the filename, so its first element is directory-files-and-attributes's second element.)

We will want our new function, files-in-below-directory, to list the .el files in the directory it is told to check, and in any directories below that directory.

This gives us a hint on how to construct files-in-below-directory: within a directory, the function should add .el filenames to a list; and if, within a directory, the function comes upon a sub-directory, it should go into that sub-directory and repeat its actions.

However, we should note that every directory contains a name that refers to itself, called ., ("dot") and a name that refers to its parent directory, called .. ("double dot"). (In /, the root directory, .. refers to itself, since / has no parent.) Clearly, we do not want our files-in-below-directory function to enter those directories, since they always lead us, directly or indirectly, to the current directory.

Consequently, our files-in-below-directory function must do several tasks:

  • Check to see whether it is looking at a filename that ends in .el; and if so, add its name to a list.
  • Check to see whether it is looking at a filename that is the name of a directory; and if so,
    • Check to see whether it is looking at . or ..; and if so skip it.
    • Or else, go into that directory and repeat the process.

Let's write a function definition to do these tasks. We will use a while loop to move from one filename to another within a directory, checking what needs to be done; and we will use a recursive call to repeat the actions on each sub-directory. The recursive pattern is `accumulate' (see Recursive Pattern: accumulate), using append as the combiner.

Here is the function:

(defun files-in-below-directory (directory)
  "List the .el files in DIRECTORY and in its sub-directories."
  ;; Although the function will be used non-interactively,
  ;; it will be easier to test if we make it interactive.
  ;; The directory will have a name such as
  ;;  "/usr/local/share/emacs/21.0.100/lisp/"
  (interactive "DDirectory name: ")
  (let (el-files-list
        (current-directory-list
         (directory-files-and-attributes directory t)))
    ;; while we are in the current directory
    (while current-directory-list
      (cond
       ;; check to see whether filename ends in `.el'
       ;; and if so, append its name to a list.
       ((equal ".el" (substring (car (car current-directory-list)) -3))
        (setq el-files-list
              (cons (car (car current-directory-list)) el-files-list)))
       ;; check whether filename is that of a directory
       ((eq t (car (cdr (car current-directory-list))))
        ;; decide whether to skip or recurse
        (if
            (equal (or "." "..")
                   (substring (car (car current-directory-list)) -1))
            ;; then do nothing if filename is that of
            ;;   current directory or parent
            ()
          ;; else descend into the directory and repeat the process
          (setq el-files-list
                (append
                 (files-in-below-directory
                  (car (car current-directory-list)))
                 el-files-list)))))
      ;; move to the next filename in the list; this also
      ;; shortens the list so the while loop eventually comes to an end
      (setq current-directory-list (cdr current-directory-list)))
    ;; return the filenames
    el-files-list))

The files-in-below-directory directory-files function takes one argument, the name of a directory.

Thus, on my system,

(length
 (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/"))

tells me that my version 21.0.100 Lisp sources directory contains 754 .el files.

files-in-below-directory returns a list in reverse alphabetical order. An expression to sort the list in alphabetical order looks like this:

(sort
 (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
 'string-lessp)

Node:Counting function definitions, Previous:Files List, Up:Prepare the data

14.9.3 Counting function definitions

Our immediate goal is to generate a list that tells us how many function definitions contain fewer than 10 words and symbols, how many contain between 10 and 19 words and symbols, how many contain between 20 and 29 words and symbols, and so on.

With a sorted list of numbers, this is easy: count how many elements of the list are smaller than 10, then, after moving past the numbers just counted, count how many are smaller than 20, then, after moving past the numbers just counted, count how many are smaller than 30, and so on. Each of the numbers, 10, 20, 30, 40, and the like, is one larger than the top of that range. We can call the list of such numbers the top-of-ranges list.

If we wished, we could generate this list automatically, but it is simpler to write a list manually. Here it is:

(defvar top-of-ranges
 '(10  20  30  40  50
   60  70  80  90 100
  110 120 130 140 150
  160 170 180 190 200
  210 220 230 240 250
  260 270 280 290 300)
 "List specifying ranges for `defuns-per-range'.")

To change the ranges, we edit this list.

Next, we need to write the function that creates the list of the number of definitions within each range. Clearly, this function must take the sorted-lengths and the top-of-ranges lists as arguments.

The defuns-per-range function must do two things again and again: it must count the number of definitions within a range specified by the current top-of-range value; and it must shift to the next higher value in the top-of-ranges list after counting the number of definitions in the current range. Since each of these actions is repetitive, we can use while loops for the job. One loop counts the number of definitions in the range defined by the current top-of-range value, and the other loop selects each of the top-of-range values in turn.

Several entries of the sorted-lengths list are counted for each range; this means that the loop for the sorted-lengths list will be inside the loop for the top-of-ranges list, like a small gear inside a big gear.

The inner loop counts the number of definitions within the range. It is a simple counting loop of the type we have seen before. (See A loop with an incrementing counter.) The true-or-false test of the loop tests whether the value from the sorted-lengths list is smaller than the current value of the top of the range. If it is, the function increments the counter and tests the next value from the sorted-lengths list.

The inner loop looks like this:

(while length-element-smaller-than-top-of-range
  (setq number-within-range (1+ number-within-range))
  (setq sorted-lengths (cdr sorted-lengths)))

The outer loop must start with the lowest value of the top-of-ranges list, and then be set to each of the succeeding higher values in turn. This can be done with a loop like this:

(while top-of-ranges
  body-of-loop...
  (setq top-of-ranges (cdr top-of-ranges)))

Put together, the two loops look like this:

(while top-of-ranges

  ;; Count the number of elements within the current range.
  (while length-element-smaller-than-top-of-range
    (setq number-within-range (1+ number-within-range))
    (setq sorted-lengths (cdr sorted-lengths)))

  ;; Move to next range.
  (setq top-of-ranges (cdr top-of-ranges)))

In addition, in each circuit of the outer loop, Emacs should record the number of definitions within that range (the value of number-within-range) in a list. We can use cons for this purpose. (See cons.)

The cons function works fine, except that the list it constructs will contain the number of definitions for the highest range at its beginning and the number of definitions for the lowest range at its end. This is because cons attaches new elements of the list to the beginning of the list, and since the two loops are working their way through the lengths' list from the lower end first, the defuns-per-range-list will end up largest number first. But we will want to print our graph with smallest values first and the larger later. The solution is to reverse the order of the defuns-per-range-list. We can do this using the nreverse function, which reverses the order of a list.

For example,

(nreverse '(1 2 3 4))

produces:

(4 3 2 1)

Note that the nreverse function is "destructive"--that is, it changes the list to which it is applied; this contrasts with the car and cdr functions, which are non-destructive. In this case, we do not want the original defuns-per-range-list, so it does not matter that it is destroyed. (The reverse function provides a reversed copy of a list, leaving the original list as is.)

Put all together, the defuns-per-range looks like this:

(defun defuns-per-range (sorted-lengths top-of-ranges)
  "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
  (let ((top-of-range (car top-of-ranges))
        (number-within-range 0)
        defuns-per-range-list)

    ;; Outer loop.
    (while top-of-ranges

      ;; Inner loop.
      (while (and
              ;; Need number for numeric test.
              (car sorted-lengths)
              (< (car sorted-lengths) top-of-range))

        ;; Count number of definitions within current range.
        (setq number-within-range (1+ number-within-range))
        (setq sorted-lengths (cdr sorted-lengths)))

      ;; Exit inner loop but remain within outer loop.

      (setq defuns-per-range-list
            (cons number-within-range defuns-per-range-list))
      (setq number-within-range 0)      ; Reset count to zero.

      ;; Move to next range.
      (setq top-of-ranges (cdr top-of-ranges))
      ;; Specify next top of range value.
      (setq top-of-range (car top-of-ranges)))

    ;; Exit outer loop and count the number of defuns larger than
    ;;   the largest top-of-range value.
    (setq defuns-per-range-list
          (cons
           (length sorted-lengths)
           defuns-per-range-list))

    ;; Return a list of the number of definitions within each range,
    ;;   smallest to largest.
    (nreverse defuns-per-range-list)))

The function is straightforward except for one subtle feature. The true-or-false test of the inner loop looks like this:

(and (car sorted-lengths)
     (< (car sorted-lengths) top-of-range))

instead of like this:

(< (car sorted-lengths) top-of-range)

The purpose of the test is to determine whether the first item in the sorted-lengths list is less than the value of the top of the range.

The simple version of the test works fine unless the sorted-lengths list has a nil value. In that case, the (car sorted-lengths) expression function returns nil. The < function cannot compare a number to nil, which is an empty list, so Emacs signals an error and stops the function from attempting to continue to execute.

The sorted-lengths list always becomes nil when the counter reaches the end of the list. This means that any attempt to use the defuns-per-range function with the simple version of the test will fail.

We solve the problem by using the (car sorted-lengths) expression in conjunction with the and expression. The (car sorted-lengths) expression returns a non-nil value so long as the list has at least one number within it, but returns nil if the list is empty. The and expression first evaluates the (car sorted-lengths) expression, and if it is nil, returns false without evaluating the < expression. But if the (car sorted-lengths) expression returns a non-nil value, the and expression evaluates the < expression, and returns that value as the value of the and expression.

This way, we avoid an error.

Here is a short test of the defuns-per-range function. First, evaluate the expression that binds (a shortened) top-of-ranges list to the list of values, then evaluate the expression for binding the sorted-lengths list, and then evaluate the defuns-per-range function.

;; (Shorter list than we will use later.)
(setq top-of-ranges
 '(110 120 130 140 150
   160 170 180 190 200))

(setq sorted-lengths
      '(85 86 110 116 122 129 154 176 179 200 265 300 300))

(defuns-per-range sorted-lengths top-of-ranges)

The list returned looks like this:

(2 2 2 0 0 1 0 2 0 0 4)

Indeed, there are two elements of the sorted-lengths list smaller than 110, two elements between 110 and 119, two elements between 120 and 129, and so on. There are four elements with a value of 200 or larger.

Node:Readying a Graph, Next:Emacs Initialization, Previous:Words in a defun, Up:Top

15 Readying a Graph

Our goal is to construct a graph showing the numbers of function definitions of various lengths in the Emacs lisp sources.

As a practical matter, if you were creating a graph, you would probably use a program such as gnuplot to do the job. (gnuplot is nicely integrated into GNU Emacs.) In this case, however, we create one from scratch, and in the process we will re-acquaint ourselves with some of what we learned before and learn more.

In this chapter, we will first write a simple graph printing function. This first definition will be a prototype, a rapidly written function that enables us to reconnoiter this unknown graph-making territory. We will discover dragons, or find that they are myth. After scouting the terrain, we will feel more confident and enhance the function to label the axes automatically.

  • Columns of a graph:
  • graph-body-print: How to print the body of a graph.
  • recursive-graph-body-print:
  • Printed Axes:
  • Line Graph Exercise:

Node:Columns of a graph, Next:graph-body-print, Previous:Readying a Graph, Up:Readying a Graph

Printing the Columns of a Graph

Since Emacs is designed to be flexible and work with all kinds of terminals, including character-only terminals, the graph will need to be made from one of the `typewriter' symbols. An asterisk will do; as we enhance the graph-printing function, we can make the choice of symbol a user option.

We can call this function graph-body-print; it will take a numbers-list as its only argument. At this stage, we will not label the graph, but only print its body.

The graph-body-print function inserts a vertical column of asterisks for each element in the numbers-list. The height of each line is determined by the value of that element of the numbers-list.

Inserting columns is a repetitive act; that means that this function can be written either with a while loop or recursively.

Our first challenge is to discover how to print a column of asterisks. Usually, in Emacs, we print characters onto a screen horizontally, line by line, by typing. We have two routes we can follow: write our own column-insertion function or discover whether one exists in Emacs.

To see whether there is one in Emacs, we can use the M-x apropos command. This command is like the C-h a (command-apropos) command, except that the latter finds only those functions that are commands. The M-x apropos command lists all symbols that match a regular expression, including functions that are not interactive.

What we want to look for is some command that prints or inserts columns. Very likely, the name of the function will contain either the word `print' or the word `insert' or the word `column'. Therefore, we can simply type M-x apropos RET print\|insert\|column RET and look at the result. On my system, this command takes quite some time, and then produces a list of 79 functions and variables. Scanning down the list, the only function that looks as if it might do the job is insert-rectangle.

Indeed, this is the function we want; its documentation says:

insert-rectangle:
Insert text of RECTANGLE with upper left corner at point.
RECTANGLE's first line is inserted at point,
its second line is inserted at a point vertically under point, etc.
RECTANGLE should be a list of strings.

We can run a quick test, to make sure it does what we expect of it.

Here is the result of placing the cursor after the insert-rectangle expression and typing C-u C-x C-e (eval-last-sexp). The function inserts the strings "first", "second", and "third" at and below point. Also the function returns nil.

(insert-rectangle '("first" "second" "third"))first
                                              second
                                              third
nil

Of course, we won't be inserting the text of the insert-rectangle expression itself into the buffer in which we are making the graph, but will call the function from our program. We shall, however, have to make sure that point is in the buffer at the place where the insert-rectangle function will insert its column of strings.

If you are reading this in Info, you can see how this works by switching to another buffer, such as the *scratch* buffer, placing point somewhere in the buffer, typing M-:, typing the insert-rectangle expression into the minibuffer at the prompt, and then typing <RET>. This causes Emacs to evaluate the expression in the minibuffer, but to use as the value of point the position of point in the *scratch* buffer. (M-: is the keybinding for eval-expression.)

We find when we do this that point ends up at the end of the last inserted line--that is to say, this function moves point as a side-effect. If we were to repeat the command, with point at this position, the next insertion would be below and to the right of the previous insertion. We don't want this! If we are going to make a bar graph, the columns need to be beside each other.

So we discover that each cycle of the column-inserting while loop must reposition point to the place we want it, and that place will be at the top, not the bottom, of the column. Moreover, we remember that when we print a graph, we do not expect all the columns to be the same height. This means that the top of each column may be at a different height from the previous one. We cannot simply reposition point to the same line each time, but moved over to the right--or perhaps we can...

We are planning to make the columns of the bar graph out of asterisks. The number of asterisks in the column is the number specified by the current element of the numbers-list. We need to construct a list of asterisks of the right length for each call to insert-rectangle. If this list consists solely of the requisite number of asterisks, then we will have position point the right number of lines above the base for the graph to print correctly. This could be difficult.

Alternatively, if we can figure out some way to pass insert-rectangle a list of the same length each time, then we can place point on the same line each time, but move it over one column to the right for each new column. If we do this, however, some of the entries in the list passed to insert-rectangle must be blanks rather than asterisks. For example, if the maximum height of the graph is 5, but the height of the column is 3, then insert-rectangle requires an argument that looks like this:

(" " " " "*" "*" "*")

This last proposal is not so difficult, so long as we can determine the column height. There are two ways for us to specify the column height: we can arbitrarily state what it will be, which would work fine for graphs of that height; or we can search through the list of numbers and use the maximum height of the list as the maximum height of the graph. If the latter operation were difficult, then the former procedure would be easiest, but there is a function built into Emacs that determines the maximum of its arguments. We can use that function. The function is called max and it returns the largest of all its arguments, which must be numbers. Thus, for example,

(max  3 4 6 5 7 3)

returns 7. (A corresponding function called min returns the smallest of all its arguments.)

However, we cannot simply call max on the numbers-list; the max function expects numbers as its argument, not a list of numbers. Thus, the following expression,

(max  '(3 4 6 5 7 3))

produces the following error message;

Wrong type of argument:  number-or-marker-p, (3 4 6 5 7 3)

We need a function that passes a list of arguments to a function. This function is apply. This function `applies' its first argument (a function) to its remaining arguments, the last of which may be a list.

For example,

(apply 'max 3 4 7 3 '(4 8 5))

returns 8.

(Incidentally, I don't know how you would learn of this function without a book such as this. It is possible to discover other functions, like search-forward or insert-rectangle, by guessing at a part of their names and then using apropos. Even though its base in metaphor is clear--`apply' its first argument to the rest--I doubt a novice would come up with that particular word when using apropos or other aid. Of course, I could be wrong; after all, the function was first named by someone who had to invent it.)

The second and subsequent arguments to apply are optional, so we can use apply to call a function and pass the elements of a list to it, like this, which also returns 8:

(apply 'max '(4 8 5))

This latter way is how we will use apply. The recursive-lengths-list-many-files function returns a numbers' list to which we can apply max (we could also apply max to the sorted numbers' list; it does not matter whether the list is sorted or not.)

Hence, the operation for finding the maximum height of the graph is this:

(setq max-graph-height (apply 'max numbers-list))

Now we can return to the question of how to create a list of strings for a column of the graph. Told the maximum height of the graph and the number of asterisks that should appear in the column, the function should return a list of strings for the insert-rectangle command to insert.

Each column is made up of asterisks or blanks. Since the function is passed the value of the height of the column and the number of asterisks in the column, the number of blanks can be found by subtracting the number of asterisks from the height of the column. Given the number of blanks and the number of asterisks, two while loops can be used to construct the list:

;;; First version.
(defun column-of-graph (max-graph-height actual-height)
  "Return list of strings that is one column of a graph."
  (let ((insert-list nil)
        (number-of-top-blanks
         (- max-graph-height actual-height)))

    ;; Fill in asterisks.
    (while (> actual-height 0)
      (setq insert-list (cons "*" insert-list))
      (setq actual-height (1- actual-height)))

    ;; Fill in blanks.
    (while (> number-of-top-blanks 0)
      (setq insert-list (cons " " insert-list))
      (setq number-of-top-blanks
            (1- number-of-top-blanks)))

    ;; Return whole list.
    insert-list))

If you install this function and then evaluate the following expression you will see that it returns the list as desired:

(column-of-graph 5 3)

returns

(" " " " "*" "*" "*")

As written, column-of-graph contains a major flaw: the symbols used for the blank and for the marked entries in the column are `hard-coded' as a space and asterisk. This is fine for a prototype, but you, or another user, may wish to use other symbols. For example, in testing the graph function, you many want to use a period in place of the space, to make sure the point is being repositioned properly each time the insert-rectangle function is called; or you might want to substitute a + sign or other symbol for the asterisk. You might even want to make a graph-column that is more than one display column wide. The program should be more flexible. The way to do that is to replace the blank and the asterisk with two variables that we can call graph-blank and graph-symbol and define those variables separately.

Also, the documentation is not well written. These considerations lead us to the second version of the function:

(defvar graph-symbol "*"
  "String used as symbol in graph, usually an asterisk.")

(defvar graph-blank " "
  "String used as blank in graph, usually a blank space.
graph-blank must be the same number of columns wide
as graph-symbol.")

(For an explanation of defvar, see Initializing a Variable with defvar.)

;;; Second version.
(defun column-of-graph (max-graph-height actual-height)
  "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
The graph-symbols are contiguous entries at the end
of the list.
The list will be inserted as one column of a graph.
The strings are either graph-blank or graph-symbol."

  (let ((insert-list nil)
        (number-of-top-blanks
         (- max-graph-height actual-height)))

    ;; Fill in graph-symbols.
    (while (> actual-height 0)
      (setq insert-list (cons graph-symbol insert-list))
      (setq actual-height (1- actual-height)))

    ;; Fill in graph-blanks.
    (while (> number-of-top-blanks 0)
      (setq insert-list (cons graph-blank insert-list))
      (setq number-of-top-blanks
            (1- number-of-top-blanks)))

    ;; Return whole list.
    insert-list))

If we wished, we could rewrite column-of-graph a third time to provide optionally for a line graph as well as for a bar graph. This would not be hard to do. One way to think of a line graph is that it is no more than a bar graph in which the part of each bar that is below the top is blank. To construct a column for a line graph, the function first constructs a list of blanks that is one shorter than the value, then it uses cons to attach a graph symbol to the list; then it uses cons again to attach the `top blanks' to the list.

It is easy to see how to write such a function, but since we don't need it, we will not do it. But the job could be done, and if it were done, it would be done with column-of-graph. Even more important, it is worth noting that few changes would have to be made anywhere else. The enhancement, if we ever wish to make it, is simple.

Now, finally, we come to our first actual graph printing function. This prints the body of a graph, not the labels for the vertical and horizontal axes, so we can call this graph-body-print.

Node:graph-body-print, Next:recursive-graph-body-print, Previous:Columns of a graph, Up:Readying a Graph

15.1 The graph-body-print Function

After our preparation in the preceding section, the graph-body-print function is straightforward. The function will print column after column of asterisks and blanks, using the elements of a numbers' list to specify the number of asterisks in each column. This is a repetitive act, which means we can use a decrementing while loop or recursive function for the job. In this section, we will write the definition using a while loop.

The column-of-graph function requires the height of the graph as an argument, so we should determine and record that as a local variable.

This leads us to the following template for the while loop version of this function:

(defun graph-body-print (numbers-list)
  "documentation..."
  (let ((height  ...
         ...))

    (while numbers-list
      insert-columns-and-reposition-point
      (setq numbers-list (cdr numbers-list)))))

We need to fill in the slots of the template.

Clearly, we can use the (apply 'max numbers-list) expression to determine the height of the graph.

The while loop will cycle through the numbers-list one element at a time. As it is shortened by the (setq numbers-list (cdr numbers-list)) expression, the CAR of each instance of the list is the value of the argument for column-of-graph.

At each cycle of the while loop, the insert-rectangle function inserts the list returned by column-of-graph. Since the insert-rectangle function moves point to the lower right of the inserted rectangle, we need to save the location of point at the time the rectangle is inserted, move back to that position after the rectangle is inserted, and then move horizontally to the next place from which insert-rectangle is called.

If the inserted columns are one character wide, as they will be if single blanks and asterisks are used, the repositioning command is simply (forward-char 1); however, the width of a column may be greater than one. This means that the repositioning command should be written (forward-char symbol-width). The symbol-width itself is the length of a graph-blank and can be found using the expression (length graph-blank). The best place to bind the symbol-width variable to the value of the width of graph column is in the varlist of the let expression.

These considerations lead to the following function definition:

(defun graph-body-print (numbers-list)
  "Print a bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values."

  (let ((height (apply 'max numbers-list))
        (symbol-width (length graph-blank))
        from-position)

    (while numbers-list
      (setq from-position (point))
      (insert-rectangle
       (column-of-graph height (car numbers-list)))
      (goto-char from-position)
      (forward-char symbol-width)
      ;; Draw graph column by column.
      (sit-for 0)
      (setq numbers-list (cdr numbers-list)))
    ;; Place point for X axis labels.
    (forward-line height)
    (insert "\n")
))

The one unexpected expression in this function is the (sit-for 0) expression in the while loop. This expression makes the graph printing operation more interesting to watch than it would be otherwise. The expression causes Emacs to `sit' or do nothing for a zero length of time and then redraw the screen. Placed here, it causes Emacs to redraw the screen column by column. Without it, Emacs would not redraw the screen until the function exits.

We can test graph-body-print with a short list of numbers.

  1. Install graph-symbol, graph-blank, column-of-graph, which are in and graph-body-print.
  2. Copy the following expression:
    (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
  3. Switch to the *scratch* buffer and place the cursor where you want the graph to start.
  4. Type M-: (eval-expression).
  5. Yank the graph-body-print expression into the minibuffer with C-y (yank).
  6. Press <RET> to evaluate the graph-body-print expression.

Emacs will print a graph like this:

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

Node:recursive-graph-body-print, Next:Printed Axes, Previous:graph-body-print, Up:Readying a Graph

15.2 The recursive-graph-body-print Function

The graph-body-print function may also be written recursively. The recursive solution is divided into two parts: an outside `wrapper' that uses a let expression to determine the values of several variables that need only be found once, such as the maximum height of the graph, and an inside function that is called recursively to print the graph.

The `wrapper' is uncomplicated:

(defun recursive-graph-body-print (numbers-list)
  "Print a bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values."
  (let ((height (apply 'max numbers-list))
        (symbol-width (length graph-blank))
        from-position)
    (recursive-graph-body-print-internal
     numbers-list
     height
     symbol-width)))

The recursive function is a little more difficult. It has four parts: the `do-again-test', the printing code, the recursive call, and the `next-step-expression'. The `do-again-test' is an if expression that determines whether the numbers-list contains any remaining elements; if it does, the function prints one column of the graph using the printing code and calls itself again. The function calls itself again according to the value produced by the `next-step-expression' which causes the call to act on a shorter version of the numbers-list.

(defun recursive-graph-body-print-internal
  (numbers-list height symbol-width)
  "Print a bar graph.
Used within recursive-graph-body-print function."

  (if numbers-list
      (progn
        (setq from-position (point))
        (insert-rectangle
         (column-of-graph height (car numbers-list)))
        (goto-char from-position)
        (forward-char symbol-width)
        (sit-for 0)     ; Draw graph column by column.
        (recursive-graph-body-print-internal
         (cdr numbers-list) height symbol-width))))

After installation, this expression can be tested; here is a sample:

(recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))

Here is what recursive-graph-body-print produces:

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

Either of these two functions, graph-body-print or recursive-graph-body-print, create the body of a graph.

Node:Printed Axes, Next:Line Graph Exercise, Previous:recursive-graph-body-print, Up:Readying a Graph

15.3 Need for Printed Axes

A graph needs printed axes, so you can orient yourself. For a do-once project, it may be reasonable to draw the axes by hand using Emacs' Picture mode; but a graph drawing function may be used more than once.

For this reason, I have written enhancements to the basic print-graph-body function that automatically print labels for the horizontal and vertical axes. Since the label printing functions do not contain much new material, I have placed their description in an appendix. See A Graph with Labelled Axes.

Node:Line Graph Exercise, Previous:Printed Axes, Up:Readying a Graph

15.4 Exercise

Write a line graph version of the graph printing functions.

Node:Emacs Initialization, Next:Debugging, Previous:Readying a Graph, Up:Top

16 Your .emacs File

"You don't have to like Emacs to like it" - this seemingly paradoxical statement is the secret of GNU Emacs. The plain, `out of the box' Emacs is a generic tool. Most people who use it, customize it to suit themselves.

GNU Emacs is mostly written in Emacs Lisp; this means that by writing expressions in Emacs Lisp you can change or extend Emacs.

  • Default Configuration:
  • Site-wide Init: You can write site-wide init files.
  • defcustom: Emacs will write code for you.
  • Beginning a .emacs File: How to write a .emacs file.
  • Text and Auto-fill: Automatically wrap lines.
  • Mail Aliases: Use abbreviations for email addresses.
  • Indent Tabs Mode: Don't use tabs with TeX
  • Keybindings: Create some personal keybindings.
  • Keymaps: More about key binding.
  • Loading Files: Load (i.e., evaluate) files automatically.
  • Autoload: Make functions available.
  • Simple Extension: Define a function; bind it to a key.
  • X11 Colors: Colors in version 19 in X.
  • Miscellaneous:
  • Mode Line: How to customize your mode line.

Node:Default Configuration, Next:Site-wide Init, Previous:Emacs Initialization, Up:Emacs Initialization

Emacs' Default Configuration

There are those who appreciate Emacs' default configuration. After all, Emacs starts you in C mode when you edit a C file, starts you in Fortran mode when you edit a Fortran file, and starts you in Fundamental mode when you edit an unadorned file. This all makes sense, if you do not know who is going to use Emacs. Who knows what a person hopes to do with an unadorned file? Fundamental mode is the right default for such a file, just as C mode is the right default for editing C code. But when you do know who is going to use Emacs--you, yourself--then it makes sense to customize Emacs.

For example, I seldom want Fundamental mode when I edit an otherwise undistinguished file; I want Text mode. This is why I customize Emacs: so it suits me.

You can customize and extend Emacs by writing or adapting a ~/.emacs file. This is your personal initialization file; its contents, written in Emacs Lisp, tell Emacs what to do.11

A ~/.emacs file contains Emacs Lisp code. You can write this code yourself; or you can use Emacs' customize feature to write the code for you. You can combine your own expressions and auto-written Customize expressions in your .emacs file.

(I myself prefer to write my own expressions, except for those, particularly fonts, that I find easier to manipulate using the customize command. I combine the two methods.)

Most of this chapter is about writing expressions yourself. It describes a simple .emacs file; for more information, see Init File, and Init File.

Node:Site-wide Init, Next:defcustom, Previous:Default Configuration, Up:Emacs Initialization

16.1 Site-wide Initialization Files

In addition to your personal initialization file, Emacs automatically loads various site-wide initialization files, if they exist. These have the same form as your .emacs file, but are loaded by everyone.

Two site-wide initialization files, site-load.el and site-init.el, are loaded into Emacs and then `dumped' if a `dumped' version of Emacs is created, as is most common. (Dumped copies of Emacs load more quickly. However, once a file is loaded and dumped, a change to it does not lead to a change in Emacs unless you load it yourself or re-dump Emacs. See Building Emacs, and the INSTALL file.)

Three other site-wide initialization files are loaded automatically each time you start Emacs, if they exist. These are site-start.el, which is loaded before your .emacs file, and default.el, and the terminal type file, which are both loaded after your .emacs file.

Settings and definitions in your .emacs file will overwrite conflicting settings and definitions in a site-start.el file, if it exists; but the settings and definitions in a default.el or terminal type file will overwrite those in your .emacs file. (You can prevent interference from a terminal type file by setting term-file-prefix to nil. See A Simple Extension.)

The INSTALL file that comes in the distribution contains descriptions of the site-init.el and site-load.el files.

The loadup.el, startup.el, and loaddefs.el files control loading. These files are in the lisp directory of the Emacs distribution and are worth perusing.

The loaddefs.el file contains a good many suggestions as to what to put into your own .emacs file, or into a site-wide initialization file.

Node:defcustom, Next:Beginning a .emacs File, Previous:Site-wide Init, Up:Emacs Initialization

16.2 Specifying Variables using defcustom

You can specify variables using defcustom so that you and others can then can use Emacs' customize feature to set their values. (You cannot use customize to write function definitions; but you can write defuns in your .emacs file. Indeed, you can write any Lisp expression in your .emacs file.)

The customize feature depends on the defcustom special form. Although you can use defvar or setq for variables that users set, the defcustom special form is designed for the job.

You can use your knowledge of defvar for writing the first three arguments for defcustom. The first argument to defcustom is the name of the variable. The second argument is the variable's initial value, if any; and this value is set only if the value has not already been set. The third argument is the documentation.

The fourth and subsequent arguments to defcustom specify types and options; these are not featured in defvar. (These arguments are optional.)

Each of these arguments consists of a keyword followed by a value. Each keyword starts with the character :.

For example, the customizable user option variable text-mode-hook looks like this:

(defcustom text-mode-hook nil
  "Normal hook run when entering Text mode and many related modes."
  :type 'hook
  :options '(turn-on-auto-fill flyspell-mode)
  :group 'data)

The name of the variable is text-mode-hook; it has no default value; and its documentation string tells you what it does.

The :type keyword tells Emacs what kind of data text-mode-hook should be set to and how to display the value in a Customization buffer.

The :options keyword specifies a suggested list of values for the variable. Currently, you can use :options only for a hook. The list is only a suggestion; it is not exclusive; a person who sets the variable may set it to other values; the list shown following the :options keyword is intended to offer convenient choices to a user.

Finally, the :group keyword tells the Emacs Customization command in which group the variable is located. This tells where to find it.

For more information, see Customization.

Consider text-mode-hook as an example.

There are two ways to customize this variable. You can use the customization command or write the appropriate expressions yourself.

Using the customization command, you can type:

M-x customize

and find that the group for editing files of data is called `data'. Enter that group. Text Mode Hook is the first member. You can click on its various options to set the values. After you click on the button to

Save for Future Sessions

Emacs will write an expression into your .emacs file. It will look like this:

(custom-set-variables
  ;; custom-set-variables was added by Custom --
  ;;                           don't edit or cut/paste it!
  ;; Your init file should contain only one such instance.
 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))

(The text-mode-hook-identify function tells toggle-text-mode-auto-fill which buffers are in Text mode.)

In spite of the warning, you certainly may edit, cut, and paste the expression! I do all time. The purpose of the warning is to scare those who do not know what they are doing, so they do not inadvertently generate an error.

The custom-set-variables works somewhat differently than a setq. While I have never learned the differences, I do modify the custom-set-variables expressions in my .emacs file by hand: I make the changes in what appears to me to be a reasonable manner and have not had any problems. Others prefer to use the Customization command and let Emacs do the work for them.

Another custom-set-... function is custom-set-faces. This function sets the various font faces. Over time, I have set a considerable number of faces. Some of the time, I re-set them using customize; other times, I simply edit the custom-set-faces expression in my .emacs file itself.

The second way to customize your text-mode-hook is to set it yourself in your .emacs file using code that has nothing to do with the custom-set-... functions.

When you do this, and later use customize, you will see a message that says

this option has been changed outside the customize buffer.

This message is only a warning. If you click on the button to

Save for Future Sessions

Emacs will write a custom-set-... expression near the end of your .emacs file that will be evaluated after your hand-written expression. It will, therefore, overrule your hand-written expression. No harm will be done. When you do this, however, be careful to remember which expression is active; if you forget, you may confuse yourself.

So long as you remember where the values are set, you will have no trouble. In any event, the values are always set in your initialization file, which is usually called .emacs.

I myself use customize for hardly anything. Mostly, I write expressions myself.

Node:Beginning a .emacs File, Next:Text and Auto-fill, Previous:defcustom, Up:Emacs Initialization

16.3 Beginning a .emacs File

When you start Emacs, it loads your .emacs file unless you tell it not to by specifying -q on the command line. (The emacs -q command gives you a plain, out-of-the-box Emacs.)

A .emacs file contains Lisp expressions. Often, these are no more than expressions to set values; sometimes they are function definitions.

See Init File, for a short description of initialization files.

This chapter goes over some of the same ground, but is a walk among extracts from a complete, long-used .emacs file--my own.

The first part of the file consists of comments: reminders to myself. By now, of course, I remember these things, but when I started, I did not.

;;;; Bob's .emacs file
; Robert J. Chassell
; 26 September 1985

Look at that date! I started this file a long time ago. I have been adding to it ever since.

; Each section in this file is introduced by a
; line beginning with four semicolons; and each
; entry is introduced by a line beginning with
; three semicolons.

This describes the usual conventions for comments in Emacs Lisp. Everything on a line that follows a semicolon is a comment. Two, three, and four semicolons are used as section and subsection markers. (See Comments, for more about comments.)

;;;; The Help Key
; Control-h is the help key;
; after typing control-h, type a letter to
; indicate the subject about which you want help.
; For an explanation of the help facility,
; type control-h two times in a row.

Just remember: type C-h two times for help.

; To find out about any mode, type control-h m
; while in that mode.  For example, to find out
; about mail mode, enter mail mode and then type
; control-h m.

`Mode help', as I call this, is very helpful. Usually, it tells you all you need to know.

Of course, you don't need to include comments like these in your .emacs file. I included them in mine because I kept forgetting about Mode help or the conventions for comments--but I was able to remember to look here to remind myself.

Node:Text and Auto-fill, Next:Mail Aliases, Previous:Beginning a .emacs File, Up:Emacs Initialization

16.4 Text and Auto Fill Mode

Now we come to the part that `turns on' Text mode and Auto Fill mode.

;;; Text mode and Auto Fill mode
; The next three lines put Emacs into Text mode
; and Auto Fill mode, and are for writers who
; want to start writing prose rather than code.

(setq default-major-mode 'text-mode)
(add-hook 'text-mode-hook 'text-mode-hook-identify)
(add-hook 'text-mode-hook 'turn-on-auto-fill)

Here is the first part of this .emacs file that does something besides remind a forgetful human!

The first of the two lines in parentheses tells Emacs to turn on Text mode when you find a file, unless that file should go into some other mode, such as C mode.

When Emacs reads a file, it looks at the extension to the file name, if any. (The extension is the part that comes after a ..) If the file ends with a .c or .h extension then Emacs turns on C mode. Also, Emacs looks at first nonblank line of the file; if the line says -*- C -*-, Emacs turns on C mode. Emacs possesses a list of extensions and specifications that it uses automatically. In addition, Emacs looks near the last page for a per-buffer, "local variables list", if any.

Now, back to the .emacs file.

Here is the line again; how does it work?

(setq default-major-mode 'text-mode)

This line is a short, but complete Emacs Lisp expression.

We are already familiar with setq. It sets the following variable, default-major-mode, to the subsequent value, which is text-mode. The single quote mark before text-mode tells Emacs to deal directly with the text-mode variable, not with whatever it might stand for. See Setting the Value of a Variable, for a reminder of how setq works. The main point is that there is no difference between the procedure you use to set a value in your .emacs file and the procedure you use anywhere else in Emacs.

Here are the next two lines:

(add-hook 'text-mode-hook 'text-mode-hook-identify)
(add-hook 'text-mode-hook 'turn-on-auto-fill)

In these two lines, the add-hook command first adds text-mode-hook-identify to the variable called text-mode-hook and then adds turn-on-auto-fill to the variable.

turn-on-auto-fill is the name of a program, that, you guessed it!, turns on Auto Fill mode. text-mode-hook-identify is a function that tells toggle-text-mode-auto-fill which buffers are in Text mode.

Every time Emacs turns on Text mode, Emacs runs the commands `hooked' onto Text mode. So every time Emacs turns on Text mode, Emacs also turns on Auto Fill mode.

In brief, the first line causes Emacs to enter Text mode when you edit a file, unless the file name extension, first non-blank line, or local variables tell Emacs otherwise.

Text mode among other actions, sets the syntax table to work conveniently for writers. In Text mode, Emacs considers an apostrophe as part of a word like a letter; but Emacs does not consider a period or a space as part of a word. Thus, M-f moves you over it's. On the other hand, in C mode, M-f stops just after the t of it's.

The second and third lines causes Emacs to turn on Auto Fill mode when it turns on Text mode. In Auto Fill mode, Emacs automatically breaks a line that is too wide and brings the excessively wide part of the line down to the next line. Emacs breaks lines between words, not within them.

When Auto Fill mode is turned off, lines continue to the right as you type them. Depending on how you set the value of truncate-lines, the words you type either disappear off the right side of the screen, or else are shown, in a rather ugly and unreadable manner, as a continuation line on the screen.

In addition, in this part of my .emacs file, I tell the Emacs fill commands to insert two spaces after a colon:

(setq colon-double-space t)

Node:Mail Aliases, Next:Indent Tabs Mode, Previous:Text and Auto-fill, Up:Emacs Initialization

16.5 Mail Aliases

Here is a setq that `turns on' mail aliases, along with more reminders.

;;; Mail mode
; To enter mail mode, type `C-x m'
; To enter RMAIL (for reading mail),
; type `M-x rmail'

(setq mail-aliases t)

This setq command sets the value of the variable mail-aliases to t. Since t means true, the line says, in effect, "Yes, use mail aliases."

Mail aliases are convenient short names for long email addresses or for lists of email addresses. The file where you keep your `aliases' is ~/.mailrc. You write an alias like this:

alias geo george@foobar.wiz.edu

When you write a message to George, address it to geo; the mailer will automatically expand geo to the full address.

Node:Indent Tabs Mode, Next:Keybindings, Previous:Mail Aliases, Up:Emacs Initialization

16.6 Indent Tabs Mode

By default, Emacs inserts tabs in place of multiple spaces when it formats a region. (For example, you might indent many lines of text all at once with the indent-region command.) Tabs look fine on a terminal or with ordinary printing, but they produce badly indented output when you use TeX or Texinfo since TeX ignores tabs.

The following turns off Indent Tabs mode:

;;; Prevent Extraneous Tabs
(setq-default indent-tabs-mode nil)

Note that this line uses setq-default rather than the setq command that we have seen before. The setq-default command sets values only in buffers that do not have their own local values for the variable.

Node:Keybindings, Next:Keymaps, Previous:Indent Tabs Mode, Up:Emacs Initialization

16.7 Some Keybindings

Now for some personal keybindings:

;;; Compare windows
(global-set-key "\C-cw" 'compare-windows)

compare-windows is a nifty command that compares the text in your current window with text in the next window. It makes the comparison by starting at point in each window, moving over text in each window as far as they match. I use this command all the time.

This also shows how to set a key globally, for all modes.

The command is global-set-key. It is followed by the keybinding. In a .emacs file, the keybinding is written as shown: \C-c stands for `control-c', which means `press the control key and the c key at the same time'. The w means `press the w key'. The keybinding is surrounded by double quotation marks. In documentation, you would write this as C-c w. (If you were binding a <META> key, such as M-c, rather than a <CTL> key, you would write \M-c. See Init Rebinding, for details.)

The command invoked by the keys is compare-windows. Note that compare-windows is preceded by a single quote; otherwise, Emacs would first try to evaluate the symbol to determine its value.

These three things, the double quotation marks, the backslash before the C, and the single quote mark are necessary parts of keybinding that I tend to forget. Fortunately, I have come to remember that I should look at my existing .emacs file, and adapt what is there.

As for the keybinding itself: C-c w. This combines the prefix key, C-c, with a single character, in this case, w. This set of keys, C-c followed by a single character, is strictly reserved for individuals' own use. (I call these `own' keys, since these are for my own use.) You should always be able to create such a keybinding for your own use without stomping on someone else's keybinding. If you ever write an extension to Emacs, please avoid taking any of these keys for public use. Create a key like C-c C-w instead. Otherwise, we will run out of `own' keys.

Here is another keybinding, with a comment:

;;; Keybinding for `occur'
; I use occur a lot, so let's bind it to a key:
(global-set-key "\C-co" 'occur)

The occur command shows all the lines in the current buffer that contain a match for a regular expression. Matching lines are shown in a buffer called *Occur*. That buffer serves as a menu to jump to occurrences.

Here is how to unbind a key, so it does not work:

;;; Unbind `C-x f'
(global-unset-key "\C-xf")

There is a reason for this unbinding: I found I inadvertently typed C-x f when I meant to type C-x C-f. Rather than find a file, as I intended, I accidentally set the width for filled text, almost always to a width I did not want. Since I hardly ever reset my default width, I simply unbound the key.

The following rebinds an existing key:

;;; Rebind `C-x C-b' for `buffer-menu'
(global-set-key "\C-x\C-b" 'buffer-menu)

By default, C-x C-b runs the list-buffers command. This command lists your buffers in another window. Since I almost always want to do something in that window, I prefer the buffer-menu command, which not only lists the buffers, but moves point into that window.

Node:Keymaps, Next:Loading Files, Previous:Keybindings, Up:Emacs Initialization

16.8 Keymaps

Emacs uses keymaps to record which keys call which commands. When you use global-set-key to set the keybinding for a single command in all parts of Emacs, you are specifying the keybinding in current-global-map.

Specific modes, such as C mode or Text mode, have their own keymaps; the mode-specific keymaps override the global map that is shared by all buffers.

The global-set-key function binds, or rebinds, the global keymap. For example, the following binds the key C-x C-b to the function buffer-menu:

(global-set-key "\C-x\C-b" 'buffer-menu)

Mode-specific keymaps are bound using the define-key function, which takes a specific keymap as an argument, as well as the key and the command. For example, my .emacs file contains the following expression to bind the texinfo-insert-@group command to C-c C-c g:

(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@group)

The texinfo-insert-@group function itself is a little extension to Texinfo mode that inserts @group into a Texinfo file. I use this command all the time and prefer to type the three strokes C-c C-c g rather than the six strokes @ g r o u p. (@group and its matching @end group are commands that keep all enclosed text together on one page; many multi-line examples in this book are surrounded by @group ... @end group.)

Here is the texinfo-insert-@group function definition:

(defun texinfo-insert-@group ()
  "Insert the string @group in a Texinfo buffer."
  (interactive)
  (beginning-of-line)
  (insert "@group\n"))

(Of course, I could have used Abbrev mode to save typing, rather than write a function to insert a word; but I prefer key strokes consistent with other Texinfo mode key bindings.)

You will see numerous define-key expressions in loaddefs.el as well as in the various mode libraries, such as cc-mode.el and lisp-mode.el.

See Key Bindings, and Keymaps, for more information about keymaps.

Node:Loading Files, Next:Autoload, Previous:Keymaps, Up:Emacs Initialization

16.9 Loading Files

Many people in the GNU Emacs community have written extensions to Emacs. As time goes by, these extensions are often included in new releases. For example, the Calendar and Diary packages are now part of the standard GNU Emacs.

(Calc, which I consider a vital part of Emacs, would be part of the standard distribution except that it was so large it was packaged separately and no one has changed that.)

You can use a load command to evaluate a complete file and thereby install all the functions and variables in the file into Emacs. For example:

(load "~/emacs/slowsplit")

This evaluates, i.e. loads, the slowsplit.el file or if it exists, the faster, byte compiled slowsplit.elc file from the emacs sub-directory of your home directory. The file contains the function split-window-quietly, which John Robinson wrote in 1989.

The split-window-quietly function splits a window with the minimum of redisplay. I installed it in 1989 because it worked well with the slow 1200 baud terminals I was then using. Nowadays, I only occasionally come across such a slow connection, but I continue to use the function because I like the way it leaves the bottom half of a buffer in the lower of the new windows and the top half in the upper window.

To replace the key binding for the default split-window-vertically, you must also unset that key and bind the keys to split-window-quietly, like this:

(global-unset-key "\C-x2")
(global-set-key "\C-x2" 'split-window-quietly)

If you load many extensions, as I do, then instead of specifying the exact location of the extension file, as shown above, you can specify that directory as part of Emacs' load-path. Then, when Emacs loads a file, it will search that directory as well as its default list of directories. (The default list is specified in paths.h when Emacs is built.)

The following command adds your ~/emacs directory to the existing load path:

;;; Emacs Load Path
(setq load-path (cons "~/emacs" load-path))

Incidentally, load-library is an interactive interface to the load function. The complete function looks like this:

(defun load-library (library)
  "Load the library named LIBRARY.
This is an interface to the function `load'."
  (interactive "sLoad library: ")
  (load library))

The name of the function, load-library, comes from the use of `library' as a conventional synonym for `file'. The source for the load-library command is in the files.el library.

Another interactive command that does a slightly different job is load-file. See Lisp Libraries, for information on the distinction between load-library and this command.

Node:Autoload, Next:Simple Extension, Previous:Loading Files, Up:Emacs Initialization

16.10 Autoloading

Instead of installing a function by loading the file that contains it, or by evaluating the function definition, you can make the function available but not actually install it until it is first called. This is called autoloading.

When you execute an autoloaded function, Emacs automatically evaluates the file that contains the definition, and then calls the function.

Emacs starts quicker with autoloaded functions, since their libraries are not loaded right away; but you need to wait a moment when you first use such a function, while its containing file is evaluated.

Rarely used functions are frequently autoloaded. The loaddefs.el library contains hundreds of autoloaded functions, from bookmark-set to wordstar-mode. Of course, you may come to use a `rare' function frequently. When you do, you should load that function's file with a load expression in your .emacs file.

In my .emacs file for Emacs version 21, I load 12 libraries that contain functions that would otherwise be autoloaded. (Actually, it would have been better to include these files in my `dumped' Emacs when I built it, but I forgot. See Building Emacs, and the INSTALL file for more about dumping.)

You may also want to include autoloaded expressions in your .emacs file. autoload is a built-in function that takes up to five arguments, the final three of which are optional. The first argument is the name of the function to be autoloaded; the second is the name of the file to be loaded. The third argument is documentation for the function, and the fourth tells whether the function can be called interactively. The fifth argument tells what type of object--autoload can handle a keymap or macro as well as a function (the default is a function).

Here is a typical example:

(autoload 'html-helper-mode
  "html-helper-mode" "Edit HTML documents" t)

(html-helper-mode is an alternative to html-mode, which is a standard part of the distribution).

This expression autoloads the html-helper-mode function. It takes it from the html-helper-mode.el file (or from the byte compiled file html-helper-mode.elc, if it exists.) The file must be located in a directory specified by load-path. The documentation says that this is a mode to help you edit documents written in the HyperText Markup Language. You can call this mode interactively by typing M-x html-helper-mode. (You need to duplicate the function's regular documentation in the autoload expression because the regular function is not yet loaded, so its documentation is not available.)

See Autoload, for more information.

Node:Simple Extension, Next:X11 Colors, Previous:Autoload, Up:Emacs Initialization

16.11 A Simple Extension: line-to-top-of-window

Here is a simple extension to Emacs that moves the line point is on to the top of the window. I use this all the time, to make text easier to read.

You can put the following code into a separate file and then load it from your .emacs file, or you can include it within your .emacs file.

Here is the definition:

;;; Line to top of window;
;;; replace three keystroke sequence  C-u 0 C-l
(defun line-to-top-of-window ()
  "Move the line point is on to top of window."
  (interactive)
  (recenter 0))

Now for the keybinding.

Nowadays, function keys as well as mouse button events and non-ASCII characters are written within square brackets, without quotation marks. (In Emacs version 18 and before, you had to write different function key bindings for each different make of terminal.)

I bind line-to-top-of-window to my <F6> function key like this:

(global-set-key [f6] 'line-to-top-of-window)

For more information, see Init Rebinding.

If you run two versions of GNU Emacs, such as versions 20 and 21, and use one .emacs file, you can select which code to evaluate with the following conditional:

(cond
 ((string-equal (number-to-string 20) (substring (emacs-version) 10 12))
  ;; evaluate version 20 code
  ( ... ))
 ((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
  ;; evaluate version 21 code
  ( ... )))

For example, in contrast to version 20, version 21 blinks its cursor by default. I hate such blinking, as well as some other features in version 21, so I placed the following in my .emacs file12:

(if (string-equal "21" (substring (emacs-version) 10 12))
    (progn
      (blink-cursor-mode 0)
      ;; Insert newline when you press `C-n' (next-line)
      ;; at the end of the buffer
      (setq next-line-add-newlines t)
      ;; Turn on image viewing
      (auto-image-file-mode t)
      ;; Turn on menu bar (this bar has text)
      ;; (Use numeric argument to turn on)
      (menu-bar-mode 1)
      ;; Turn off tool bar (this bar has icons)
      ;; (Use numeric argument to turn on)
      (tool-bar-mode nil)
      ;; Turn off tooltip mode for tool bar
      ;; (This mode causes icon explanations to pop up)
      ;; (Use numeric argument to turn on)
      (tooltip-mode nil)
      ;; If tooltips turned on, make tips appear promptly
      (setq tooltip-delay 0.1)  ; default is one second
       ))

(You will note that instead of typing (number-to-string 21), I decided to save typing and wrote `21' as a string, "21", rather than convert it from an integer to a string. In this instance, this expression is better than the longer, but more general (number-to-string 21). However, if you do not know ahead of time what type of information will be returned, then the number-to-string function will be needed.)

Node:X11 Colors, Next:Miscellaneous, Previous:Simple Extension, Up:Emacs Initialization

16.12 X11 Colors

You can specify colors when you use Emacs with the MIT X Windowing system.

I dislike the default colors and specify my own.

Here are the expressions in my .emacs file that set values:

;; Set cursor color
(set-cursor-color "white")

;; Set mouse color
(set-mouse-color "white")

;; Set foreground and background
(set-foreground-color "white")
(set-background-color "darkblue")

;;; Set highlighting colors for isearch and drag
(set-face-foreground 'highlight "white")
(set-face-background 'highlight "blue")

(set-face-foreground 'region "cyan")
(set-face-background 'region "blue")

(set-face-foreground 'secondary-selection "skyblue")
(set-face-background 'secondary-selection "darkblue")

;; Set calendar highlighting colors
(setq calendar-load-hook
      '(lambda ()
         (set-face-foreground 'diary-face   "skyblue")
         (set-face-background 'holiday-face "slate blue")
         (set-face-foreground 'holiday-face "white")))

The various shades of blue soothe my eye and prevent me from seeing the screen flicker.

Alternatively, I could have set my specifications in various X initialization files. For example, I could set the foreground, background, cursor, and pointer (i.e., mouse) colors in my ~/.Xresources file like this:

Emacs*foreground:   white
Emacs*background:   darkblue
Emacs*cursorColor:  white
Emacs*pointerColor: white

In any event, since it is not part of Emacs, I set the root color of my X window in my ~/.xinitrc file, like this13:

# I use TWM for window manager.
xsetroot -solid Navy -fg white &

Node:Miscellaneous, Next:Mode Line, Previous:X11 Colors, Up:Emacs Initialization

16.13 Miscellaneous Settings for a .emacs File

Here are a few miscellaneous settings:

  • Set the shape and color of the mouse cursor:
    ; Cursor shapes are defined in
; `/usr/include/X11/cursorfont.h';
; for example, the `target' cursor is number 128;
; the `top_left_arrow' cursor is number 132.

(let ((mpointer (x-get-resource "*mpointer"
                                "*emacs*mpointer")))
  ;; If you have not set your mouse pointer
  ;;     then set it, otherwise leave as is:
  (if (eq mpointer nil)
      (setq mpointer "132")) ; top_left_arrow
  (setq x-pointer-shape (string-to-int mpointer))
  (set-mouse-color "white"))

Node:Mode Line, Previous:Miscellaneous, Up:Emacs Initialization

16.14 A Modified Mode Line

Finally, a feature I really like: a modified mode line.

When I work over a network, I forget which machine I am using. Also, I tend to I lose track of where I am, and which line point is on.

So I reset my mode line to look like this:

-:-- foo.texi   rattlesnake:/home/bob/  Line 1  (Texinfo Fill) Top

I am visiting a file called foo.texi, on my machine rattlesnake in my /home/bob buffer. I am on line 1, in Texinfo mode, and am at the top of the buffer.

My .emacs file has a section that looks like this:

;; Set a Mode Line that tells me which machine, which directory,
;; and which line I am on, plus the other customary information.
(setq default-mode-line-format
 (quote
  (#("-" 0 1
     (help-echo
      "mouse-1: select window, mouse-2: delete others ..."))
   mode-line-mule-info
   mode-line-modified
   mode-line-frame-identification
   "    "
   mode-line-buffer-identification
   "    "
   (:eval (substring
           (system-name) 0 (string-match "\\..+" (system-name))))
   ":"
   default-directory
   #(" " 0 1
     (help-echo
      "mouse-1: select window, mouse-2: delete others ..."))
   (line-number-mode " Line %l ")
   global-mode-string
   #("   %[(" 0 6
     (help-echo
      "mouse-1: select window, mouse-2: delete others ..."))
   (:eval (mode-line-mode-name))
   mode-line-process
   minor-mode-alist
   #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
   ")%] "
   (-3 . "%P")
   ;;   "-%-"
   )))

Here, I redefine the default mode line. Most of the parts are from the original; but I make a few changes. I set the default mode line format so as to permit various modes, such as Info, to override it.

Many elements in the list are self-explanatory: mode-line-modified is a variable that tells whether the buffer has been modified, mode-name tells the name of the mode, and so on. However, the format looks complicated because of two features we have not discussed.

The first string in the mode line is a dash or hyphen, -. In the old days, it would have been specified simply as "-". But nowadays, Emacs can add properties to a string, such as highlighting or, as in this case, a help feature. If you place your mouse cursor over the hyphen, some help information appears (By default, you must wait one second before the information appears. You can change that timing by changing the value of tooltip-delay.)

The new string format has a special syntax:

#("-" 0 1 (help-echo "mouse-1: select window, ..."))

The #( begins a list. The first element of the list is the string itself, just one -. The second and third elements specify the range over which the fourth element applies. A range starts after a character, so a zero means the range starts just before the first character; a 1 means that the range ends just after the first character. The third element is the property for the range. It consists of a property list, a property name, in this case, help-echo, followed by a value, in this case, a string. The second, third, and fourth elements of this new string format can be repeated.

See Text Props and Strings, and see Mode Line Format, for more information.

mode-line-buffer-identification displays the current buffer name. It is a list beginning (#("%12b" 0 4 .... The #( begins the list.

The "%12b" displays the current buffer name, using the buffer-name function with which we are familiar; the `12' specifies the maximum number of characters that will be displayed. When a name has fewer characters, whitespace is added to fill out to this number. (Buffer names can and often should be longer than 12 characters; this length works well in a typical 80 column wide window.)

:eval is a new feature in GNU Emacs version 21. It says to evaluate the following form and use the result as a string to display. In this case, the expression displays the first component of the full system name. The end of the first component is a . (`period'), so I use the string-match function to tell me the length of the first component. The substring from the zeroth character to that length is the name of the machine.

This is the expression:

(:eval (substring
        (system-name) 0 (string-match "\\..+" (system-name))))

%[ and %] cause a pair of square brackets to appear for each recursive editing level. %n says `Narrow' when narrowing is in effect. %P tells you the percentage of the buffer that is above the bottom of the window, or `Top', `Bottom', or `All'. (A lower case p tell you the percentage above the top of the window.) %- inserts enough dashes to fill out the line.

Remember, "You don't have to like Emacs to like it" -- your own Emacs can have different colors, different commands, and different keys than a default Emacs.

On the other hand, if you want to bring up a plain `out of the box' Emacs, with no customization, type:

emacs -q

This will start an Emacs that does not load your ~/.emacs initialization file. A plain, default Emacs. Nothing more.

Node:Debugging, Next:Conclusion, Previous:Emacs Initialization, Up:Top

17 Debugging

GNU Emacs has two debuggers, debug and edebug. The first is built into the internals of Emacs and is always with you; the second requires that you instrument a function before you can use it.

Both debuggers are described extensively in Debugging. In this chapter, I will walk through a short example of each.

  • debug: How to use the built-in debugger.
  • debug-on-entry: Start debugging when you call a function.
  • debug-on-quit: Start debugging when you quit with C-g.
  • edebug: How to use Edebug, a source level debugger.
  • Debugging Exercises:

Node:debug, Next:debug-on-entry, Previous:Debugging, Up:Debugging

17.1 debug

Suppose you have written a function definition that is intended to return the sum of the numbers 1 through a given number. (This is the triangle function discussed earlier. See Example with Decrementing Counter, for a discussion.)

However, your function definition has a bug. You have mistyped 1= for 1-. Here is the broken definition:

(defun triangle-bugged (number)
  "Return sum of numbers 1 through NUMBER inclusive."
  (let ((total 0))
    (while (> number 0)
      (setq total (+ total number))
      (setq number (1= number)))      ; Error here.
    total))

If you are reading this in Info, you can evaluate this definition in the normal fashion. You will see triangle-bugged appear in the echo area.

Now evaluate the triangle-bugged function with an argument of 4:

(triangle-bugged 4)

In GNU Emacs version 21, you will create and enter a *Backtrace* buffer that says:

---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function 1=)
  (1= number)
  (setq number (1= number))
  (while (> number 0) (setq total (+ total number))
        (setq number (1= number)))
  (let ((total 0)) (while (> number 0) (setq total ...)
    (setq number ...)) total)
  triangle-bugged(4)
  eval((triangle-bugged 4))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

(I have reformatted this example slightly; the debugger does not fold long lines. As usual, you can quit the debugger by typing q in the *Backtrace* buffer.)

In practice, for a bug as simple as this, the `Lisp error' line will tell you what you need to know to correct the definition. The function 1= is `void'.

In GNU Emacs 20 and before, you will see:

Symbol's function definition is void: 1=

which has the same meaning as the *Backtrace* buffer line in version 21.

However, suppose you are not quite certain what is going on? You can read the complete backtrace.

In this case, you need to run GNU Emacs 21, which automatically starts the debugger that puts you in the *Backtrace* buffer; or else, you need to start the debugger manually as described below.

Read the *Backtrace* buffer from the bottom up; it tells you what Emacs did that led to the error. Emacs made an interactive call to C-x C-e (eval-last-sexp), which led to the evaluation of the triangle-bugged expression. Each line above tells you what the Lisp interpreter evaluated next.

The third line from the top of the buffer is

(setq number (1= number))

Emacs tried to evaluate this expression; in order to do so, it tried to evaluate the inner expression shown on the second line from the top:

(1= number)

This is where the error occurred; as the top line says:

Debugger entered--Lisp error: (void-function 1=)

You can correct the mistake, re-evaluate the function definition, and then run your test again.

Node:debug-on-entry, Next:debug-on-quit, Previous:debug, Up:Debugging

17.2 debug-on-entry

GNU Emacs 21 starts the debugger automatically when your function has an error. GNU Emacs version 20 and before did not; it simply presented you with an error message. You had to start the debugger manually.

You can start the debugger manually for all versions of Emacs; the advantage is that the debugger runs even if you do not have a bug in your code. Sometimes your code will be free of bugs!

You can enter the debugger when you call the function by calling debug-on-entry.

Type:

M-x debug-on-entry RET triangle-bugged RET

Now, evaluate the following:

(triangle-bugged 5)

All versions of Emacs will create a *Backtrace* buffer and tell you that it is beginning to evaluate the triangle-bugged function:

---------- Buffer: *Backtrace* ----------
Debugger entered--entering a function:
* triangle-bugged(5)
  eval((triangle-bugged 5))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

In the *Backtrace* buffer, type d. Emacs will evaluate the first expression in triangle-bugged; the buffer will look like this:

---------- Buffer: *Backtrace* ----------
Debugger entered--beginning evaluation of function call form:
* (let ((total 0)) (while (> number 0) (setq total ...)
        (setq number ...)) total)
* triangle-bugged(5)
  eval((triangle-bugged 5))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

Now, type d again, eight times, slowly. Each time you type d, Emacs will evaluate another expression in the function definition.

Eventually, the buffer will look like this:

---------- Buffer: *Backtrace* ----------
Debugger entered--beginning evaluation of function call form:
* (setq number (1= number))
* (while (> number 0) (setq total (+ total number))
        (setq number (1= number)))
* (let ((total 0)) (while (> number 0) (setq total ...)
        (setq number ...)) total)
* triangle-bugged(5)
  eval((triangle-bugged 5))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
---------- Buffer: *Backtrace* ----------

Finally, after you type d two more times, Emacs will reach the error, and the top two lines of the *Backtrace* buffer will look like this:

---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function 1=)
* (1= number)
...
---------- Buffer: *Backtrace* ----------

By typing d, you were able to step through the function.

You can quit a *Backtrace* buffer by typing q in it; this quits the trace, but does not cancel debug-on-entry.

To cancel the effect of debug-on-entry, call cancel-debug-on-entry and the name of the function, like this:

M-x cancel-debug-on-entry RET triangle-bugged RET

(If you are reading this in Info, cancel debug-on-entry now.)

Node:debug-on-quit, Next:edebug, Previous:debug-on-entry, Up:Debugging

17.3 debug-on-quit and (debug)

In addition to setting debug-on-error or calling debug-on-entry, there are two other ways to start debug.

You can start debug whenever you type C-g (keyboard-quit) by setting the variable debug-on-quit to t. This is useful for debugging infinite loops.

Or, you can insert a line that says (debug) into your code where you want the debugger to start, like this:

(defun triangle-bugged (number)
  "Return sum of numbers 1 through NUMBER inclusive."
  (let ((total 0))
    (while (> number 0)
      (setq total (+ total number))
      (debug)                         ; Start debugger.
      (setq number (1= number)))      ; Error here.
    total))

The debug function is described in detail in Debugger.

Node:edebug, Next:Debugging Exercises, Previous:debug-on-quit, Up:Debugging

17.4 The edebug Source Level Debugger

Edebug is a source level debugger. Edebug normally displays the source of the code you are debugging, with an arrow at the left that shows which line you are currently executing.

You can walk through the execution of a function, line by line, or run quickly until reaching a breakpoint where execution stops.

Edebug is described in edebug.

Here is a bugged function definition for triangle-recursively. See Recursion in place of a counter, for a review of it.

(defun triangle-recursively-bugged (number)
  "Return sum of numbers 1 through NUMBER inclusive.
Uses recursion."
  (if (= number 1)
      1
    (+ number
       (triangle-recursively-bugged
        (1= number)))))               ; Error here.

Normally, you would install this definition by positioning your cursor after the function's closing parenthesis and typing C-x C-e (eval-last-sexp) or else by positioning your cursor within the definition and typing C-M-x (eval-defun). (By default, the eval-defun command works only in Emacs Lisp mode or in Lisp Interactive mode.)

However, to prepare this function definition for Edebug, you must first instrument the code using a different command. You can do this by positioning your cursor within the definition and typing

M-x edebug-defun RET

This will cause Emacs to load Edebug automatically if it is not already loaded, and properly instrument the function.

After instrumenting the function, place your cursor after the following expression and type C-x C-e (eval-last-sexp):

(triangle-recursively-bugged 3)

You will be jumped back to the source for triangle-recursively-bugged and the cursor positioned at the beginning of the if line of the function. Also, you will see an arrowhead at the left hand side of that line. The arrowhead marks the line where the function is executing. (In the following examples, we show the arrowhead with =>; in a windowing system, you may see the arrowhead as a solid triangle in the window `fringe'.)

=>-!-(if (= number 1)

In the example, the location of point is displayed as -!- (in a printed book, it is displayed with a five pointed star).

If you now press <SPC>, point will move to the next expression to be executed; the line will look like this:

=>(if -!-(= number 1)

As you continue to press <SPC>, point will move from expression to expression. At the same time, whenever an expression returns a value, that value will be displayed in the echo area. For example, after you move point past number, you will see the following:

Result: 3 = C-c

This means the value of number is 3, which is ASCII `control-c' (the third letter of the alphabet).

You can continue moving through the code until you reach the line with the error. Before evaluation, that line looks like this:

=>        -!-(1= number)))))               ; Error here.

When you press <SPC> once again, you will produce an error message that says:

Symbol's function definition is void: 1=

This is the bug.

Press q to quit Edebug.

To remove instrumentation from a function definition, simply re-evaluate it with a command that does not instrument it. For example, you could place your cursor after the definition's closing parenthesis and type C-x C-e.

Edebug does a great deal more than walk with you through a function. You can set it so it races through on its own, stopping only at an error or at specified stopping points; you can cause it to display the changing values of various expressions; you can find out how many times a function is called, and more.

Edebug is described in edebug.

Node:Debugging Exercises, Previous:edebug, Up:Debugging

17.5 Debugging Exercises

  • Install the count-words-region function and then cause it to enter the built-in debugger when you call it. Run the command on a region containing two words. You will need to press d a remarkable number of times. On your system, is a `hook' called after the command finishes? (For information on hooks, see Command Overview.)
  • Copy count-words-region into the *scratch* buffer, instrument the function for Edebug, and walk through its execution. The function does not need to have a bug, although you can introduce one if you wish. If the function lacks a bug, the walk-through completes without problems.
  • While running Edebug, type ? to see a list of all the Edebug commands. (The global-edebug-prefix is usually C-x X, i.e. <CTL>-x followed by an upper case X; use this prefix for commands made outside of the Edebug debugging buffer.)
  • In the Edebug debugging buffer, use the p (edebug-bounce-point) command to see where in the region the count-words-region is working.
  • Move point to some spot further down function and then type the h (edebug-goto-here) command to jump to that location.
  • Use the t (edebug-trace-mode) command to cause Edebug to walk through the function on its own; use an upper case T for edebug-Trace-fast-mode.
  • Set a breakpoint, then run Edebug in Trace mode until it reaches the stopping point.

Node:Conclusion, Next:the-the, Previous:Debugging, Up:Top

18 Conclusion

We have now reached the end of this Introduction. You have now learned enough about programming in Emacs Lisp to set values, to write simple .emacs files for yourself and your friends, and write simple customizations and extensions to Emacs.

This is a place to stop. Or, if you wish, you can now go onward, and teach yourself.

You have learned some of the basic nuts and bolts of programming. But only some. There are a great many more brackets and hinges that are easy to use that we have not touched.

A path you can follow right now lies among the sources to GNU Emacs and in The GNU Emacs Lisp Reference Manual.

The Emacs Lisp sources are an adventure. When you read the sources and come across a function or expression that is unfamiliar, you need to figure out or find out what it does.

Go to the Reference Manual. It is a thorough, complete, and fairly easy-to-read description of Emacs Lisp. It is written not only for experts, but for people who know what you know. (The Reference Manual comes with the standard GNU Emacs distribution. Like this introduction, it comes as a Texinfo source file, so you can read it on-line and as a typeset, printed book.)

Go to the other on-line help that is part of GNU Emacs: the on-line documentation for all functions, and find-tags, the program that takes you to sources.

Here is an example of how I explore the sources. Because of its name, simple.el is the file I looked at first, a long time ago. As it happens some of the functions in simple.el are complicated, or at least look complicated at first sight. The open-line function, for example, looks complicated.

You may want to walk through this function slowly, as we did with the forward-sentence function. (See forward-sentence.) Or you may want to skip that function and look at another, such as split-line. You don't need to read all the functions. According to count-words-in-defun, the split-line function contains 27 words and symbols.

Even though it is short, split-line contains four expressions we have not studied: skip-chars-forward, indent-to, current-column and ?\n.

Consider the skip-chars-forward function. (It is part of the function definition for back-to-indentation, which is shown in Review.)

In GNU Emacs, you can find out more about skip-chars-forward by typing C-h f (describe-function) and the name of the function. This gives you the function documentation.

You may be able to guess what is done by a well named function such as indent-to; or you can look it up, too. Incidentally, the describe-function function itself is in help.el; it is one of those long, but decipherable functions. You can look up describe-function using the C-h f command!

In this instance, since the code is Lisp, the *Help* buffer contains the name of the library containing the function's source. You can put point over the name of the library and press the RET key, which in this situation is bound to help-follow, and be taken directly to the source, in the same way as M-. (find-tag).

The definition for describe-function illustrates how to customize the interactive expression without using the standard character codes; and it shows how to create a temporary buffer.

(The indent-to function is written in C rather than Emacs Lisp; it is a `built-in' function. help-follow only provides you with the documentation of a built-in function; it does not take you to the source. But find-tag will take you to the source, if properly set up.)

You can look at a function's source using find-tag, which is bound to M-. Finally, you can find out what the Reference Manual has to say by visiting the manual in Info, and typing i (Info-index) and the name of the function, or by looking up skip-chars-forward in the index to a printed copy of the manual.

Similarly, you can find out what is meant by ?\n. You can try using Info-index with ?\n. It turns out that this action won't help; but don't give up. If you search the index for \n without the ?, you will be taken directly to the relevant section of the manual. (See Character Type. ?\n stands for the newline character.)

Other interesting source files include paragraphs.el, loaddefs.el, and loadup.el. The paragraphs.el file includes short, easily understood functions as well as longer ones. The loaddefs.el file contains the many standard autoloads and many keymaps. I have never looked at it all; only at parts. loadup.el is the file that loads the standard parts of Emacs; it tells you a great deal about how Emacs is built. (See Building Emacs, for more about building.)

As I said, you have learned some nuts and bolts; however, and very importantly, we have hardly touched major aspects of programming; I have said nothing about how to sort information, except to use the predefined sort function; I have said nothing about how to store information, except to use variables and lists; I have said nothing about how to write programs that write programs. These are topics for another, and different kind of book, a different kind of learning.

What you have done is learn enough for much practical work with GNU Emacs. What you have done is get started. This is the end of a beginning.

Node:the-the, Next:Kill Ring, Previous:Conclusion, Up:Top

Appendix A The the-the Function

Sometimes when you you write text, you duplicate words--as with "you you" near the beginning of this sentence. I find that most frequently, I duplicate "the'; hence, I call the function for detecting duplicated words, the-the.

As a first step, you could use the following regular expression to search for duplicates:

\\(\\w+[ \t\n]+\\)\\1

This regexp matches one or more word-constituent characters followed by one or more spaces, tabs, or newlines. However, it does not detect duplicated words on different lines, since the ending of the first word, the end of the line, is different from the ending of the second word, a space. (For more information about regular expressions, see Regular Expression Searches, as well as Regexps, and Regular Expressions.)

You might try searching just for duplicated word-constituent characters but that does not work since the pattern detects doubles such as the two occurrences of `th' in `with the'.

Another possible regexp searches for word-constituent characters followed by non-word-constituent characters, reduplicated. Here, \\w+ matches one or more word-constituent characters and \\W* matches zero or more non-word-constituent characters.

\\(\\(\\w+\\)\\W*\\)\\1

Again, not useful.

Here is the pattern that I use. It is not perfect, but good enough. \\b matches the empty string, provided it is at the beginning or end of a word; [^@ \n\t]+ matches one or more occurrences of any characters that are not an @-sign, space, newline, or tab.

\\b\\([^@ \n\t]+\\)[ \n\t]+\\1\\b

One can write more complicated expressions, but I found that this expression is good enough, so I use it.

Here is the the-the function, as I include it in my .emacs file, along with a handy global key binding:

(defun the-the ()
  "Search forward for for a duplicated word."
  (interactive)
  (message "Searching for for duplicated words ...")
  (push-mark)
  ;; This regexp is not perfect
  ;; but is fairly good over all:
  (if (re-search-forward
       "\\b\\([^@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
      (message "Found duplicated word.")
    (message "End of buffer")))

;; Bind `the-the' to  C-c \
(global-set-key "\C-c\\" 'the-the)

Here is test text:

one two two three four five
five six seven

You can substitute the other regular expressions shown above in the function definition and try each of them on this list.

Node:Kill Ring, Next:Full Graph, Previous:the-the, Up:Top

Appendix B Handling the Kill Ring

The kill ring is a list that is transformed into a ring by the workings of the rotate-yank-pointer function. The yank and yank-pop commands use the rotate-yank-pointer function. This appendix describes the rotate-yank-pointer function as well as both the yank and the yank-pop commands.

  • rotate-yank-pointer: Move a pointer along a list and around.
  • yank: Paste a copy of a clipped element.
  • yank-pop: Insert first element pointed to.

Node:rotate-yank-pointer, Next:yank, Previous:Kill Ring, Up:Kill Ring

B.1 The rotate-yank-pointer Function

The rotate-yank-pointer function changes the element in the kill ring to which kill-ring-yank-pointer points. For example, it can change kill-ring-yank-pointer from pointing to the second element to point to the third element.

Here is the code for rotate-yank-pointer:

(defun rotate-yank-pointer (arg)
  "Rotate the yanking point in the kill ring."
  (interactive "p")
  (let ((length (length kill-ring)))
    (if (zerop length)
        ;; then-part
        (error "Kill ring is empty")
      ;; else-part
      (setq kill-ring-yank-pointer
            (nthcdr (% (+ arg
                          (- length
                             (length
                              kill-ring-yank-pointer)))
                       length)
                    kill-ring)))))
  • Understanding rotate-yk-ptr:
  • rotate-yk-ptr body: The body of rotate-yank-pointer.

Node:Understanding rotate-yk-ptr, Next:rotate-yk-ptr body, Previous:rotate-yank-pointer, Up:rotate-yank-pointer

rotate-yank-pointer in Outline

The rotate-yank-pointer function looks complex, but as usual, it can be understood by taking it apart piece by piece. First look at it in skeletal form:

(defun rotate-yank-pointer (arg)
  "Rotate the yanking point in the kill ring."
  (interactive "p")
  (let varlist
    body...)

This function takes one argument, called arg. It has a brief documentation string; and it is interactive with a small p, which means that the argument must be a processed prefix passed to the function as a number.

The body of the function definition is a let expression, which itself has a body as well as a varlist.

The let expression declares a variable that will be only usable within the bounds of this function. This variable is called length and is bound to a value that is equal to the number of items in the kill ring. This is done by using the function called length. (Note that this function has the same name as the variable called length; but one use of the word is to name the function and the other is to name the variable. The two are quite distinct. Similarly, an English speaker will distinguish between the meanings of the word ship when he says: "I must ship this package immediately." and "I must get aboard the ship immediately.")

The function length tells the number of items there are in a list, so (length kill-ring) returns the number of items there are in the kill ring.

Node:rotate-yk-ptr body, Previous:Understanding rotate-yk-ptr, Up:rotate-yank-pointer

B.1.1 The Body of rotate-yank-pointer

The body of rotate-yank-pointer is a let expression and the body of the let expression is an if expression.

The purpose of the if expression is to find out whether there is anything in the kill ring. If the kill ring is empty, the error function stops evaluation of the function and prints a message in the echo area. On the other hand, if the kill ring has something in it, the work of the function is done.

Here is the if-part and then-part of the if expression:

(if (zerop length)                      ; if-part
    (error "Kill ring is empty")        ; then-part
  ...

If there is not anything in the kill ring, its length must be zero and an error message sent to the user: Kill ring is empty. The if expression uses the function zerop which returns true if the value it is testing is zero. When zerop tests true, the then-part of the if is evaluated. The then-part is a list starting with the function error, which is a function that is similar to the message function (see message), in that it prints a one-line message in the echo area. However, in addition to printing a message, error also stops evaluation of the function within which it is embedded. This means that the rest of the function will not be evaluated if the length of the kill ring is zero.

  • Digression concerning error: How to mislead humans, but not computers.
  • rotate-yk-ptr else-part: The else-part of the if expression.
  • Remainder Function: The remainder, %, function.
  • rotate-yk-ptr remainder: Using % in rotate-yank-pointer.
  • kill-rng-yk-ptr last elt: Pointing to the last element.

Node:Digression concerning error, Next:rotate-yk-ptr else-part, Previous:rotate-yk-ptr body, Up:rotate-yk-ptr body

Digression about the word `error'

(In my opinion, it is slightly misleading, at least to humans, to use the term `error' as the name of the error function. A better term would be `cancel'. Strictly speaking, of course, you cannot point to, much less rotate a pointer to a list that has no length, so from the point of view of the computer, the word `error' is correct. But a human expects to attempt this sort of thing, if only to find out whether the kill ring is full or empty. This is an act of exploration.

(From the human point of view, the act of exploration and discovery is not necessarily an error, and therefore should not be labelled as one, even in the bowels of a computer. As it is, the code in Emacs implies that a human who is acting virtuously, by exploring his or her environment, is making an error. This is bad. Even though the computer takes the same steps as it does when there is an `error', a term such as `cancel' would have a clearer connotation.)

Node:rotate-yk-ptr else-part, Next:Remainder Function, Previous:Digression concerning error, Up:rotate-yk-ptr body

The else-part of the if expression

The else-part of the if expression is dedicated to setting the value of kill-ring-yank-pointer when the kill ring has something in it. The code looks like this:

(setq kill-ring-yank-pointer
      (nthcdr (% (+ arg
                    (- length
                       (length kill-ring-yank-pointer)))
                 length)
              kill-ring)))))

This needs some examination. Clearly, kill-ring-yank-pointer is being set to be equal to some CDR of the kill ring, using the nthcdr function that is described in an earlier section. (See copy-region-as-kill.) But exactly how does it do this?

Before looking at the details of the code let's first consider the purpose of the rotate-yank-pointer function.

The rotate-yank-pointer function changes what kill-ring-yank-pointer points to. If kill-ring-yank-pointer starts by pointing to the first element of a list, a call to rotate-yank-pointer causes it to point to the second element; and if kill-ring-yank-pointer points to the second element, a call to rotate-yank-pointer causes it to point to the third element. (And if rotate-yank-pointer is given an argument greater than 1, it jumps the pointer that many elements.)

The rotate-yank-pointer function uses setq to reset what the kill-ring-yank-pointer points to. If kill-ring-yank-pointer points to the first element of the kill ring, then, in the simplest case, the rotate-yank-pointer function must cause it to point to the second element. Put another way, kill-ring-yank-pointer must be reset to have a value equal to the CDR of the kill ring.

That is, under these circumstances,

(setq kill-ring-yank-pointer
   ("some text" "a different piece of text" "yet more text"))

(setq kill-ring
   ("some text" "a different piece of text" "yet more text"))

the code should do this:

(setq kill-ring-yank-pointer (cdr kill-ring))

As a result, the kill-ring-yank-pointer will look like this:

kill-ring-yank-pointer
     => ("a different piece of text" "yet more text"))

The actual setq expression uses the nthcdr function to do the job.

As we have seen before (see nthcdr), the nthcdr function works by repeatedly taking the CDR of a list--it takes the CDR of the CDR of the CDR ...

The two following expressions produce the same result:

(setq kill-ring-yank-pointer (cdr kill-ring))

(setq kill-ring-yank-pointer (nthcdr 1 kill-ring))

In the rotate-yank-pointer function, however, the first argument to nthcdr is a rather complex looking expression with lots of arithmetic inside of it:

(% (+ arg
      (- length
         (length kill-ring-yank-pointer)))
   length)

As usual, we need to look at the most deeply embedded expression first and then work our way towards the light.

The most deeply embedded expression is (length kill-ring-yank-pointer). This finds the length of the current value of the kill-ring-yank-pointer. (Remember that the kill-ring-yank-pointer is the name of a variable whose value is a list.)

The measurement of the length is inside the expression:

(- length (length kill-ring-yank-pointer))

In this expression, the first length is the variable that was assigned the length of the kill ring in the let statement at the beginning of the function. (One might think this function would be clearer if the variable length were named length-of-kill-ring instead; but if you look at the text of the whole function, you will see that it is so short that naming this variable length is not a bother, unless you are pulling the function apart into very tiny pieces as we are doing here.)

So the line (- length (length kill-ring-yank-pointer)) tells the difference between the length of the kill ring and the length of the list whose name is kill-ring-yank-pointer.

To see how all this fits into the rotate-yank-pointer function, let's begin by analyzing the case where kill-ring-yank-pointer points to the first element of the kill ring, just as kill-ring does, and see what happens when rotate-yank-pointer is called with an argument of 1.

The variable length and the value of the expression (length kill-ring-yank-pointer) will be the same since the variable length is the length of the kill ring and the kill-ring-yank-pointer is pointing to the whole kill ring. Consequently, the value of

(- length (length kill-ring-yank-pointer))

will be zero. Since the value of arg will be 1, this will mean that the value of the whole expression

(+ arg (- length (length kill-ring-yank-pointer)))

will be 1.

Consequently, the argument to nthcdr will be found as the result of the expression

(% 1 length)

Node:Remainder Function, Next:rotate-yk-ptr remainder, Previous:rotate-yk-ptr else-part, Up:rotate-yk-ptr body

The % remainder function

To understand (% 1 length), we need to understand %. According to its documentation (which I just found by typing C-h f % <RET>), the % function returns the remainder of its first argument divided by its second argument. For example, the remainder of 5 divided by 2 is 1. (2 goes into 5 twice with a remainder of 1.)

What surprises people who don't often do arithmetic is that a smaller number can be divided by a larger number and have a remainder. In the example we just used, 5 was divided by 2. We can reverse that and ask, what is the result of dividing 2 by 5? If you can use fractions, the answer is obviously 2/5 or .4; but if, as here, you can only use whole numbers, the result has to be something different. Clearly, 5 can go into 2 zero times, but what of the remainder? To see what the answer is, consider a case that has to be familiar from childhood:

  • 5 divided by 5 is 1 with a remainder of 0;
  • 6 divided by 5 is 1 with a remainder of 1;
  • 7 divided by 5 is 1 with a remainder of 2.
  • Similarly, 10 divided by 5 is 2 with a remainder of 0;
  • 11 divided by 5 is 2 with a remainder of 1;
  • 12 divided by 5 is 1 with a remainder of 2.

By considering the cases as parallel, we can see that

  • zero divided by 5 must be zero with a remainder of zero;
  • 1 divided by 5 must be zero with a remainder of 1;
  • 2 divided by 5 must be zero with a remainder of 2;

and so on.

So, in this code, if the value of length is 5, then the result of evaluating

(% 1 5)

is 1. (I just checked this by placing the cursor after the expression and typing C-x C-e. Indeed, 1 is printed in the echo area.)

Node:rotate-yk-ptr remainder, Next:kill-rng-yk-ptr last elt, Previous:Remainder Function, Up:rotate-yk-ptr body

Using % in rotate-yank-pointer

When the kill-ring-yank-pointer points to the beginning of the kill ring, and the argument passed to rotate-yank-pointer is 1, the % expression returns 1:

(- length (length kill-ring-yank-pointer))
     => 0

therefore,

(+ arg (- length (length kill-ring-yank-pointer)))
     => 1

and consequently:

(% (+ arg (- length (length kill-ring-yank-pointer)))
   length)
     => 1

regardless of the value of length.

As a result of this, the setq kill-ring-yank-pointer expression simplifies to:

(setq kill-ring-yank-pointer (nthcdr 1 kill-ring))

What it does is now easy to understand. Instead of pointing as it did to the first element of the kill ring, the kill-ring-yank-pointer is set to point to the second element.

Clearly, if the argument passed to rotate-yank-pointer is two, then the kill-ring-yank-pointer is set to (nthcdr 2 kill-ring); and so on for different values of the argument.

Similarly, if the kill-ring-yank-pointer starts out pointing to the second element of the kill ring, its length is shorter than the length of the kill ring by 1, so the computation of the remainder is based on the expression (% (+ arg 1) length). This means that the kill-ring-yank-pointer is moved from the second element of the kill ring to the third element if the argument passed to rotate-yank-pointer is 1.

Node:kill-rng-yk-ptr last elt, Previous:rotate-yk-ptr remainder, Up:rotate-yk-ptr body

Pointing to the last element

The final question is, what happens if the kill-ring-yank-pointer is set to the last element of the kill ring? Will a call to rotate-yank-pointer mean that nothing more can be taken from the kill ring? The answer is no. What happens is different and useful. The kill-ring-yank-pointer is set to point to the beginning of the kill ring instead.

Let's see how this works by looking at the code, assuming the length of the kill ring is 5 and the argument passed to rotate-yank-pointer is 1. When the kill-ring-yank-pointer points to the last element of the kill ring, its length is 1. The code looks like this:

(% (+ arg (- length (length kill-ring-yank-pointer))) length)

When the variables are replaced by their numeric values, the expression looks like this:

(% (+ 1 (- 5 1)) 5)

This expression can be evaluated by looking at the most embedded inner expression first and working outwards: The value of (- 5 1) is 4; the sum of (+ 1 4) is 5; and the remainder of dividing 5 by 5 is zero. So what rotate-yank-pointer will do is

(setq kill-ring-yank-pointer (nthcdr 0 kill-ring))

which will set the kill-ring-yank-pointer to point to the beginning of the kill ring.

So what happens with successive calls to rotate-yank-pointer is that it moves the kill-ring-yank-pointer from element to element in the kill ring until it reaches the end; then it jumps back to the beginning. And this is why the kill ring is called a ring, since by jumping back to the beginning, it is as if the list has no end! (And what is a ring, but an entity with no end?)

Node:yank, Next:yank-pop, Previous:rotate-yank-pointer, Up:Kill Ring

B.2 yank

After learning about rotate-yank-pointer, the code for the yank function is almost easy. It has only one tricky part, which is the computation of the argument to be passed to rotate-yank-pointer.

The code looks like this:

(defun yank (&optional arg)
  "Reinsert the last stretch of killed text.
More precisely, reinsert the stretch of killed text most
recently killed OR yanked.
With just C-U as argument, same but put point in front
(and mark at end).  With argument n, reinsert the nth
most recently killed stretch of killed text.
See also the command \\[yank-pop]."

  (interactive "*P")
  (rotate-yank-pointer (if (listp arg) 0
                         (if (eq arg '-) -1
                           (1- arg))))
  (push-mark (point))
  (insert (car kill-ring-yank-pointer))
  (if (consp arg)
      (exchange-point-and-mark)))

Glancing over this code, we can understand the last few lines readily enough. The mark is pushed, that is, remembered; then the first element (the CAR) of what the kill-ring-yank-pointer points to is inserted; and then, if the argument passed the function is a cons, point and mark are exchanged so the point is put in the front of the inserted text rather than at the end. This option is explained in the documentation. The function itself is interactive with "*P". This means it will not work on a read-only buffer, and that the unprocessed prefix argument is passed to the function.

  • rotate-yk-ptr arg: Pass the argument to rotate-yank-pointer.
  • rotate-yk-ptr negative arg: Pass a negative argument.

Node:rotate-yk-ptr arg, Next:rotate-yk-ptr negative arg, Previous:yank, Up:yank

Passing the argument

The hard part of yank is understanding the computation that determines the value of the argument passed to rotate-yank-pointer. Fortunately, it is not so difficult as it looks at first sight.

What happens is that the result of evaluating one or both of the if expressions will be a number and that number will be the argument passed to rotate-yank-pointer.

Laid out with comments, the code looks like this:

(if (listp arg)                         ; if-part
    0                                   ; then-part
  (if (eq arg '-)                       ; else-part, inner if
      -1                                ; inner if's then-part
    (1- arg))))                         ; inner if's else-part

This code consists of two if expression, one the else-part of the other.

The first or outer if expression tests whether the argument passed to yank is a list. Oddly enough, this will be true if yank is called without an argument--because then it will be passed the value of nil for the optional argument and an evaluation of (listp nil) returns true! So, if no argument is passed to yank, the argument passed to rotate-yank-pointer inside of yank is zero. This means the pointer is not moved and the first element to which kill-ring-yank-pointer points is inserted, as we expect. Similarly, if the argument for yank is C-u, this will be read as a list, so again, a zero will be passed to rotate-yank-pointer. (C-u produces an unprocessed prefix argument of (4), which is a list of one element.) At the same time, later in the function, this argument will be read as a cons so point will be put in the front and mark at the end of the insertion. (The P argument to interactive is designed to provide these values for the case when an optional argument is not provided or when it is C-u.)

The then-part of the outer if expression handles the case when there is no argument or when it is C-u. The else-part handles the other situations. The else-part is itself another if expression.

The inner if expression tests whether the argument is a minus sign. (This is done by pressing the <META> and - keys at the same time, or the <ESC> key and then the - key). In this case, the rotate-yank-pointer function is passed -1 as an argument. This moves the kill-ring-yank-pointer backwards, which is what is desired.

If the true-or-false-test of the inner if expression is false (that is, if the argument is not a minus sign), the else-part of the expression is evaluated. This is the expression (1- arg). Because of the two if expressions, it will only occur when the argument is a positive number or when it is a negative number (not just a minus sign on its own). What (1- arg) does is decrement the number and return it. (The 1- function subtracts one from its argument.) This means that if the argument to rotate-yank-pointer is 1, it is reduced to zero, which means the first element to which kill-ring-yank-pointer points is yanked back, as you would expect.

Node:rotate-yk-ptr negative arg, Previous:rotate-yk-ptr arg, Up:yank

Passing a negative argument

Finally, the question arises, what happens if either the remainder function, %, or the nthcdr function is passed a negative argument, as they quite well may?

The answers can be found by a quick test. When (% -1 5) is evaluated, a negative number is returned; and if nthcdr is called with a negative number, it returns the same value as if it were called with a first argument of zero. This can be seen be evaluating the following code.

Here the => points to the result of evaluating the code preceding it. This was done by positioning the cursor after the code and typing C-x C-e (eval-last-sexp) in the usual fashion. You can do this if you are reading this in Info inside of GNU Emacs.

(% -1 5)
     => -1

(setq animals '(cats dogs elephants))
     => (cats dogs elephants)

(nthcdr 1 animals)
     => (dogs elephants)

(nthcdr 0 animals)
     => (cats dogs elephants)

(nthcdr -1 animals)
     => (cats dogs elephants)

So, if a minus sign or a negative number is passed to yank, the kill-ring-yank-point is rotated backwards until it reaches the beginning of the list. Then it stays there. Unlike the other case, when it jumps from the end of the list to the beginning of the list, making a ring, it stops. This makes sense. You often want to get back to the most recently clipped out piece of text, but you don't usually want to insert text from as many as thirty kill commands ago. So you need to work through the ring to get to the end, but won't cycle around it inadvertently if you are trying to come back to the beginning.

Incidentally, any number passed to yank with a minus sign preceding it will be treated as -1. This is evidently a simplification for writing the program. You don't need to jump back towards the beginning of the kill ring more than one place at a time and doing this is easier than writing a function to determine the magnitude of the number that follows the minus sign.

Node:yank-pop, Previous:yank, Up:Kill Ring

B.3 yank-pop

After understanding yank, the yank-pop function is easy. Leaving out the documentation to save space, it looks like this:

(defun yank-pop (arg)
  (interactive "*p")
  (if (not (eq last-command 'yank))
      (error "Previous command was not a yank"))
  (setq this-command 'yank)
  (let ((before (< (point) (mark))))
    (delete-region (point) (mark))
    (rotate-yank-pointer arg)
    (set-mark (point))
    (insert (car kill-ring-yank-pointer))
    (if before (exchange-point-and-mark))))

The function is interactive with a small p so the prefix argument is processed and passed to the function. The command can only be used after a previous yank; otherwise an error message is sent. This check uses the variable last-command which is discussed elsewhere. (See copy-region-as-kill.)

The let clause sets the variable before to true or false depending whether point is before or after mark and then the region between point and mark is deleted. This is the region that was just inserted by the previous yank and it is this text that will be replaced. Next the kill-ring-yank-pointer is rotated so that the previously inserted text is not reinserted yet again. Mark is set at the beginning of the place the new text will be inserted and then the first element to which kill-ring-yank-pointer points is inserted. This leaves point after the new text. If in the previous yank, point was left before the inserted text, point and mark are now exchanged so point is again left in front of the newly inserted text. That is all there is to it!

Node:Full Graph, Next:GNU Free Documentation License, Previous:Kill Ring, Up:Top

Appendix C A Graph with Labelled Axes

Printed axes help you understand a graph. They convey scale. In an earlier chapter (see Readying a Graph), we wrote the code to print the body of a graph. Here we write the code for printing and labelling vertical and horizontal axes, along with the body itself.

  • Labelled Example:
  • print-graph Varlist: let expression in print-graph.
  • print-Y-axis: Print a label for the vertical axis.
  • print-X-axis: Print a horizontal label.
  • Print Whole Graph: The function to print a complete graph.

Node:Labelled Example, Next:print-graph Varlist, Previous:Full Graph, Up:Full Graph

Labelled Example Graph

Since insertions fill a buffer to the right and below point, the new graph printing function should first print the Y or vertical axis, then the body of the graph, and finally the X or horizontal axis. This sequence lays out for us the contents of the function:

  1. Set up code.
  2. Print Y axis.
  3. Print body of graph.
  4. Print X axis.

Here is an example of how a finished graph should look:

    10 -
                  *
                  *  *
                  *  **
                  *  ***
     5 -      *   *******
            * *** *******
            *************
          ***************
     1 - ****************
         |   |    |    |
         1   5   10   15

In this graph, both the vertical and the horizontal axes are labelled with numbers. However, in some graphs, the horizontal axis is time and would be better labelled with months, like this:

     5 -      *
            * ** *
            *******
          ********** **
     1 - **************
         |    ^      |
         Jan  June   Jan

Indeed, with a little thought, we can easily come up with a variety of vertical and horizontal labelling schemes. Our task could become complicated. But complications breed confusion. Rather than permit this, it is better choose a simple labelling scheme for our first effort, and to modify or replace it later.

These considerations suggest the following outline for the print-graph function:

(defun print-graph (numbers-list)
  "documentation..."
  (let ((height  ...
        ...))
    (print-Y-axis height ... )
    (graph-body-print numbers-list)
    (print-X-axis ... )))

We can work on each part of the print-graph function definition in turn.

Node:print-graph Varlist, Next:print-Y-axis, Previous:Labelled Example, Up:Full Graph

C.1 The print-graph Varlist

In writing the print-graph function, the first task is to write the varlist in the let expression. (We will leave aside for the moment any thoughts about making the function interactive or about the contents of its documentation string.)

The varlist should set several values. Clearly, the top of the label for the vertical axis must be at least the height of the graph, which means that we must obtain this information here. Note that the print-graph-body function also requires this information. There is no reason to calculate the height of the graph in two different places, so we should change print-graph-body from the way we defined it earlier to take advantage of the calculation.

Similarly, both the function for printing the X axis labels and the print-graph-body function need to learn the value of the width of each symbol. We can perform the calculation here and change the definition for print-graph-body from the way we defined it in the previous chapter.

The length of the label for the horizontal axis must be at least as long as the graph. However, this information is used only in the function that prints the horizontal axis, so it does not need to be calculated here.

These thoughts lead us directly to the following form for the varlist in the let for print-graph:

(let ((height (apply 'max numbers-list)) ; First version.
      (symbol-width (length graph-blank)))

As we shall see, this expression is not quite right.

Node:print-Y-axis, Next:print-X-axis, Previous:print-graph Varlist, Up:Full Graph

C.2 The print-Y-axis Function

The job of the print-Y-axis function is to print a label for the vertical axis that looks like this:

    10 -

     5 -

     1 -

The function should be passed the height of the graph, and then should construct and insert the appropriate numbers and marks.

It is easy enough to see in the figure what the Y axis label should look like; but to say in words, and then to write a function definition to do the job is another matter. It is not quite true to say that we want a number and a tic every five lines: there are only three lines between the 1 and the 5 (lines 2, 3, and 4), but four lines between the 5 and the 10 (lines 6, 7, 8, and 9). It is better to say that we want a number and a tic mark on the base line (number 1) and then that we want a number and a tic on the fifth line from the bottom and on every line that is a multiple of five.

  • Height of label: What height for the Y axis?
  • Compute a Remainder: How to compute the remainder of a division.
  • Y Axis Element: Construct a line for the Y axis.
  • Y-axis-column: Generate a list of Y axis labels.
  • print-Y-axis Penultimate: A not quite final version.

Node:Height of label, Next:Compute a Remainder, Previous:print-Y-axis, Up:print-Y-axis

What height should the label be?

The next issue is what height the label should be? Suppose the maximum height of tallest column of the graph is seven. Should the highest label on the Y axis be 5 -, and should the graph stick up above the label? Or should the highest label be 7 -, and mark the peak of the graph? Or should the highest label be 10 -, which is a multiple of five, and be higher than the topmost value of the graph?

The latter form is preferred. Most graphs are drawn within rectangles whose sides are an integral number of steps long--5, 10, 15, and so on for a step distance of five. But as soon as we decide to use a step height for the vertical axis, we discover that the simple expression in the varlist for computing the height is wrong. The expression is (apply 'max numbers-list). This returns the precise height, not the maximum height plus whatever is necessary to round up to the nearest multiple of five. A more complex expression is required.

As usual in cases like this, a complex problem becomes simpler if it is divided into several smaller problems.

First, consider the case when the highest value of the graph is an integral multiple of five--when it is 5, 10, 15 ,or some higher multiple of five. We can use this value as the Y axis height.

A fairly simply way to determine whether a number is a multiple of five is to divide it by five and see if the division results in a remainder. If there is no remainder, the number is a multiple of five. Thus, seven divided by five has a remainder of two, and seven is not an integral multiple of five. Put in slightly different language, more reminiscent of the classroom, five goes into seven once, with a remainder of two. However, five goes into ten twice, with no remainder: ten is an integral multiple of five.

Node:Compute a Remainder, Next:Y Axis Element, Previous:Height of label, Up:print-Y-axis

C.2.1 Side Trip: Compute a Remainder

In Lisp, the function for computing a remainder is %. The function returns the remainder of its first argument divided by its second argument. As it happens, % is a function in Emacs Lisp that you cannot discover using apropos: you find nothing if you type M-x apropos <RET> remainder <RET>. The only way to learn of the existence of % is to read about it in a book such as this or in the Emacs Lisp sources. The % function is used in the code for rotate-yank-pointer, which is described in an appendix. (See The Body of rotate-yank-pointer.)

You can try the % function by evaluating the following two expressions:

(% 7 5)

(% 10 5)

The first expression returns 2 and the second expression returns 0.

To test whether the returned value is zero or some other number, we can use the zerop function. This function returns t if its argument, which must be a number, is zero.

(zerop (% 7 5))
     => nil

(zerop (% 10 5))
     => t

Thus, the following expression will return t if the height of the graph is evenly divisible by five:

(zerop (% height 5))

(The value of height, of course, can be found from (apply 'max numbers-list).)

On the other hand, if the value of height is not a multiple of five, we want to reset the value to the next higher multiple of five. This is straightforward arithmetic using functions with which we are already familiar. First, we divide the value of height by five to determine how many times five goes into the number. Thus, five goes into twelve twice. If we add one to this quotient and multiply by five, we will obtain the value of the next multiple of five that is larger than the height. Five goes into twelve twice. Add one to two, and multiply by five; the result is fifteen, which is the next multiple of five that is higher than twelve. The Lisp expression for this is:

(* (1+ (/ height 5)) 5)

For example, if you evaluate the following, the result is 15:

(* (1+ (/ 12 5)) 5)

All through this discussion, we have been using `five' as the value for spacing labels on the Y axis; but we may want to use some other value. For generality, we should replace `five' with a variable to which we can assign a value. The best name I can think of for this variable is Y-axis-label-spacing.

Using this term, and an if expression, we produce the following:

(if (zerop (% height Y-axis-label-spacing))
    height
  ;; else
  (* (1+ (/ height Y-axis-label-spacing))
     Y-axis-label-spacing))

This expression returns the value of height itself if the height is an even multiple of the value of the Y-axis-label-spacing or else it computes and returns a value of height that is equal to the next higher multiple of the value of the Y-axis-label-spacing.

We can now include this expression in the let expression of the print-graph function (after first setting the value of Y-axis-label-spacing):

(defvar Y-axis-label-spacing 5
  "Number of lines from one Y axis label to next.")

...
(let* ((height (apply 'max numbers-list))
       (height-of-top-line
        (if (zerop (% height Y-axis-label-spacing))
            height
          ;; else
          (* (1+ (/ height Y-axis-label-spacing))
             Y-axis-label-spacing)))
       (symbol-width (length graph-blank))))
...

(Note use of the let* function: the initial value of height is computed once by the (apply 'max numbers-list) expression and then the resulting value of height is used to compute its final value. See The let* expression, for more about let*.)

Node:Y Axis Element, Next:Y-axis-column, Previous:Compute a Remainder, Up:print-Y-axis

C.2.2 Construct a Y Axis Element

When we print the vertical axis, we want to insert strings such as 5 - and 10 -  every five lines. Moreover, we want the numbers and dashes to line up, so shorter numbers must be padded with leading spaces. If some of the strings use two digit numbers, the strings with single digit numbers must include a leading blank space before the number.

To figure out the length of the number, the length function is used. But the length function works only with a string, not with a number. So the number has to be converted from being a number to being a string. This is done with the number-to-string function. For example,

(length (number-to-string 35))
     => 2

(length (number-to-string 100))
     => 3

(number-to-string is also called int-to-string; you will see this alternative name in various sources.)

In addition, in each label, each number is followed by a string such as  - , which we will call the Y-axis-tic marker. This variable is defined with defvar:

(defvar Y-axis-tic " - "
   "String that follows number in a Y axis label.")

The length of the Y label is the sum of the length of the Y axis tic mark and the length of the number of the top of the graph.

(length (concat (number-to-string height) Y-axis-tic)))

This value will be calculated by the print-graph function in its varlist as full-Y-label-width and passed on. (Note that we did not think to include this in the varlist when we first proposed it.)

To make a complete vertical axis label, a tic mark is concatenated with a number; and the two together may be preceded by one or more spaces depending on how long the number is. The label consists of three parts: the (optional) leading spaces, the number, and the tic mark. The function is passed the value of the number for the specific row, and the value of the width of the top line, which is calculated (just once) by print-graph.

(defun Y-axis-element (number full-Y-label-width)
  "Construct a NUMBERed label element.
A numbered element looks like this `  5 - ',
and is padded as needed so all line up with
the element for the largest number."
  (let* ((leading-spaces
         (- full-Y-label-width
            (length
             (concat (number-to-string number)
                     Y-axis-tic)))))
    (concat
     (make-string leading-spaces ? )
     (number-to-string number)
     Y-axis-tic)))

The Y-axis-element function concatenates together the leading spaces, if any; the number, as a string; and the tic mark.

To figure out how many leading spaces the label will need, the function subtracts the actual length of the label--the length of the number plus the length of the tic mark--from the desired label width.

Blank spaces are inserted using the make-string function. This function takes two arguments: the first tells it how long the string will be and the second is a symbol for the character to insert, in a special format. The format is a question mark followed by a blank space, like this, ? . See Character Type, for a description of the syntax for characters.

The number-to-string function is used in the concatenation expression, to convert the number to a string that is concatenated with the leading spaces and the tic mark.

Node:Y-axis-column, Next:print-Y-axis Penultimate, Previous:Y Axis Element, Up:print-Y-axis

C.2.3 Create a Y Axis Column

The preceding functions provide all the tools needed to construct a function that generates a list of numbered and blank strings to insert as the label for the vertical axis:

(defun Y-axis-column (height width-of-label)
  "Construct list of Y axis labels and blank strings.
For HEIGHT of line above base and WIDTH-OF-LABEL."
  (let (Y-axis)
    (while (> height 1)
      (if (zerop (% height Y-axis-label-spacing))
          ;; Insert label.
          (setq Y-axis
                (cons
                 (Y-axis-element height width-of-label)
                 Y-axis))
        ;; Else, insert blanks.
        (setq Y-axis
              (cons
               (make-string width-of-label ? )
               Y-axis)))
      (setq height (1- height)))
    ;; Insert base line.
    (setq Y-axis
          (cons (Y-axis-element 1 width-of-label) Y-axis))
    (nreverse Y-axis)))

In this function, we start with the value of height and repetitively subtract one from its value. After each subtraction, we test to see whether the value is an integral multiple of the Y-axis-label-spacing. If it is, we construct a numbered label using the Y-axis-element function; if not, we construct a blank label using the make-string function. The base line consists of the number one followed by a tic mark.

Node:print-Y-axis Penultimate, Previous:Y-axis-column, Up:print-Y-axis

C.2.4 The Not Quite Final Version of print-Y-axis

The list constructed by the Y-axis-column function is passed to the print-Y-axis function, which inserts the list as a column.

(defun print-Y-axis (height full-Y-label-width)
  "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
Height must be the maximum height of the graph.
Full width is the width of the highest label element."
;; Value of height and full-Y-label-width
;; are passed by `print-graph'.
  (let ((start (point)))
    (insert-rectangle
     (Y-axis-column height full-Y-label-width))
    ;; Place point ready for inserting graph.
    (goto-char start)
    ;; Move point forward by value of full-Y-label-width
    (forward-char full-Y-label-width)))

The print-Y-axis uses the insert-rectangle function to insert the Y axis labels created by the Y-axis-column function. In addition, it places point at the correct position for printing the body of the graph.

You can test print-Y-axis:

  1. Install
    Y-axis-label-spacing
Y-axis-tic
Y-axis-element
Y-axis-column
print-Y-axis
  2. Copy the following expression:
    (print-Y-axis 12 5)
  3. Switch to the *scratch* buffer and place the cursor where you want the axis labels to start.
  4. Type M-: (eval-expression).
  5. Yank the graph-body-print expression into the minibuffer with C-y (yank).
  6. Press <RET> to evaluate the expression.

Emacs will print labels vertically, the top one being 10 - . (The print-graph function will pass the value of height-of-top-line, which in this case would end up as 15.)

Node:print-X-axis, Next:Print Whole Graph, Previous:print-Y-axis, Up:Full Graph

C.3 The print-X-axis Function

X axis labels are much like Y axis labels, except that the tics are on a line above the numbers. Labels should look like this:

    |   |    |    |
    1   5   10   15

The first tic is under the first column of the graph and is preceded by several blank spaces. These spaces provide room in rows above for the Y axis labels. The second, third, fourth, and subsequent tics are all spaced equally, according to the value of X-axis-label-spacing.

The second row of the X axis consists of numbers, preceded by several blank spaces and also separated according to the value of the variable X-axis-label-spacing.

The value of the variable X-axis-label-spacing should itself be measured in units of symbol-width, since you may want to change the width of the symbols that you are using to print the body of the graph without changing the ways the graph is labelled.

  • Similarities differences: Much like print-Y-axis, but not exactly.
  • X Axis Tic Marks: Create tic marks for the horizontal axis.

Node:Similarities differences, Next:X Axis Tic Marks, Previous:print-X-axis, Up:print-X-axis

Similarities and differences

The print-X-axis function is constructed in more or less the same fashion as the print-Y-axis function except that it has two lines: the line of tic marks and the numbers. We will write a separate function to print each line and then combine them within the print-X-axis function.

This is a three step process:

  1. Write a function to print the X axis tic marks, print-X-axis-tic-line.
  2. Write a function to print the X numbers, print-X-axis-numbered-line.
  3. Write a function to print both lines, the print-X-axis function, using print-X-axis-tic-line and print-X-axis-numbered-line.

Node:X Axis Tic Marks, Previous:Similarities differences, Up:print-X-axis

C.3.1 X Axis Tic Marks

The first function should print the X axis tic marks. We must specify the tic marks themselves and their spacing:

(defvar X-axis-label-spacing
  (if (boundp 'graph-blank)
      (* 5 (length graph-blank)) 5)
  "Number of units from one X axis label to next.")

(Note that the value of graph-blank is set by another defvar. The boundp predicate checks whether it has already been set; boundp returns nil if it has not. If graph-blank were unbound and we did not use this conditional construction, in GNU Emacs 21, we would enter the debugger and see an error message saying Debugger entered--Lisp error: (void-variable graph-blank).)

Here is the defvar for X-axis-tic-symbol:

(defvar X-axis-tic-symbol "|"
  "String to insert to point to a column in X axis.")

The goal is to make a line that looks like this:

       |   |    |    |

The first tic is indented so that it is under the first column, which is indented to provide space for the Y axis labels.

A tic element consists of the blank spaces that stretch from one tic to the next plus a tic symbol. The number of blanks is determined by the width of the tic symbol and the X-axis-label-spacing.

The code looks like this:

;;; X-axis-tic-element
...
(concat
 (make-string
  ;; Make a string of blanks.
  (-  (* symbol-width X-axis-label-spacing)
      (length X-axis-tic-symbol))
  ? )
 ;; Concatenate blanks with tic symbol.
 X-axis-tic-symbol)
...

Next, we determine how many blanks are needed to indent the first tic mark to the first column of the graph. This uses the value of full-Y-label-width passed it by the print-graph function.

The code to make X-axis-leading-spaces looks like this:

;; X-axis-leading-spaces
...
(make-string full-Y-label-width ? )
...

We also need to determine the length of the horizontal axis, which is the length of the numbers list, and the number of tics in the horizontal axis:

;; X-length
...
(length numbers-list)

;; tic-width
...
(* symbol-width X-axis-label-spacing)

;; number-of-X-tics
(if (zerop (% (X-length tic-width)))
    (/ (X-length tic-width))
  (1+ (/ (X-length tic-width))))

All this leads us directly to the function for printing the X axis tic line:

(defun print-X-axis-tic-line
  (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
  "Print tics for X axis."
    (insert X-axis-leading-spaces)
    (insert X-axis-tic-symbol)  ; Under first column.
    ;; Insert second tic in the right spot.
    (insert (concat
             (make-string
              (-  (* symbol-width X-axis-label-spacing)
                  ;; Insert white space up to second tic symbol.
                  (* 2 (length X-axis-tic-symbol)))
              ? )
             X-axis-tic-symbol))
    ;; Insert remaining tics.
    (while (> number-of-X-tics 1)
      (insert X-axis-tic-element)
      (setq number-of-X-tics (1- number-of-X-tics))))

The line of numbers is equally straightforward:

First, we create a numbered element with blank spaces before each number:

(defun X-axis-element (number)
  "Construct a numbered X axis element."
  (let ((leading-spaces
         (-  (* symbol-width X-axis-label-spacing)
             (length (number-to-string number)))))
    (concat (make-string leading-spaces ? )
            (number-to-string number))))

Next, we create the function to print the numbered line, starting with the number "1" under the first column:

(defun print-X-axis-numbered-line
  (number-of-X-tics X-axis-leading-spaces)
  "Print line of X-axis numbers"
  (let ((number X-axis-label-spacing))
    (insert X-axis-leading-spaces)
    (insert "1")
    (insert (concat
             (make-string
              ;; Insert white space up to next number.
              (-  (* symbol-width X-axis-label-spacing) 2)
              ? )
             (number-to-string number)))
    ;; Insert remaining numbers.
    (setq number (+ number X-axis-label-spacing))
    (while (> number-of-X-tics 1)
      (insert (X-axis-element number))
      (setq number (+ number X-axis-label-spacing))
      (setq number-of-X-tics (1- number-of-X-tics)))))

Finally, we need to write the print-X-axis that uses print-X-axis-tic-line and print-X-axis-numbered-line.

The function must determine the local values of the variables used by both print-X-axis-tic-line and print-X-axis-numbered-line, and then it must call them. Also, it must print the carriage return that separates the two lines.

The function consists of a varlist that specifies five local variables, and calls to each of the two line printing functions:

(defun print-X-axis (numbers-list)
  "Print X axis labels to length of NUMBERS-LIST."
  (let* ((leading-spaces
          (make-string full-Y-label-width ? ))
       ;; symbol-width is provided by graph-body-print
       (tic-width (* symbol-width X-axis-label-spacing))
       (X-length (length numbers-list))
       (X-tic
        (concat
         (make-string
          ;; Make a string of blanks.
          (-  (* symbol-width X-axis-label-spacing)
              (length X-axis-tic-symbol))
          ? )
         ;; Concatenate blanks with tic symbol.
         X-axis-tic-symbol))
       (tic-number
        (if (zerop (% X-length tic-width))
            (/ X-length tic-width)
          (1+ (/ X-length tic-width)))))
    (print-X-axis-tic-line tic-number leading-spaces X-tic)
    (insert "\n")
    (print-X-axis-numbered-line tic-number leading-spaces)))

You can test print-X-axis:

  1. Install X-axis-tic-symbol, X-axis-label-spacing, print-X-axis-tic-line, as well as X-axis-element, print-X-axis-numbered-line, and print-X-axis.
  2. Copy the following expression:
    (progn
 (let ((full-Y-label-width 5)
       (symbol-width 1))
   (print-X-axis
    '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
  3. Switch to the *scratch* buffer and place the cursor where you want the axis labels to start.
  4. Type M-: (eval-expression).
  5. Yank the test expression into the minibuffer with C-y (yank).
  6. Press <RET> to evaluate the expression.

Emacs will print the horizontal axis like this:

     |   |    |    |    |
     1   5   10   15   20

Node:Print Whole Graph, Previous:print-X-axis, Up:Full Graph

C.4 Printing the Whole Graph

Now we are nearly ready to print the whole graph.

The function to print the graph with the proper labels follows the outline we created earlier (see A Graph with Labelled Axes), but with additions.

Here is the outline:

(defun print-graph (numbers-list)
  "documentation..."
  (let ((height  ...
        ...))
    (print-Y-axis height ... )
    (graph-body-print numbers-list)
    (print-X-axis ... )))
  • The final version: A few changes.
  • Test print-graph: Run a short test.
  • Graphing words in defuns: Executing the final code.
  • lambda: How to write an anonymous function.
  • mapcar: Apply a function to elements of a list.
  • Another Bug: Yet another bug ... most insidious.
  • Final printed graph: The graph itself!

Node:The final version, Next:Test print-graph, Previous:Print Whole Graph, Up:Print Whole Graph

Changes for the Final Version

The final version is different from what we planned in two ways: first, it contains additional values calculated once in the varlist; second, it carries an option to specify the labels' increment per row. This latter feature turns out to be essential; otherwise, a graph may have more rows than fit on a display or on a sheet of paper.

This new feature requires a change to the Y-axis-column function, to add vertical-step to it. The function looks like this:

;;; Final version.
(defun Y-axis-column
  (height width-of-label &optional vertical-step)
  "Construct list of labels for Y axis.
HEIGHT is maximum height of graph.
WIDTH-OF-LABEL is maximum width of label.
VERTICAL-STEP, an option, is a positive integer
that specifies how much a Y axis label increments
for each line.  For example, a step of 5 means
that each line is five units of the graph."
  (let (Y-axis
        (number-per-line (or vertical-step 1)))
    (while (> height 1)
      (if (zerop (% height Y-axis-label-spacing))
          ;; Insert label.
          (setq Y-axis
                (cons
                 (Y-axis-element
                  (* height number-per-line)
                  width-of-label)
                 Y-axis))
        ;; Else, insert blanks.
        (setq Y-axis
              (cons
               (make-string width-of-label ? )
               Y-axis)))
      (setq height (1- height)))
    ;; Insert base line.
    (setq Y-axis (cons (Y-axis-element
                        (or vertical-step 1)
                        width-of-label)
                       Y-axis))
    (nreverse Y-axis)))

The values for the maximum height of graph and the width of a symbol are computed by print-graph in its let expression; so graph-body-print must be changed to accept them.

;;; Final version.
(defun graph-body-print (numbers-list height symbol-width)
  "Print a bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values.
HEIGHT is maximum height of graph.
SYMBOL-WIDTH is number of each column."
  (let (from-position)
    (while numbers-list
      (setq from-position (point))
      (insert-rectangle
       (column-of-graph height (car numbers-list)))
      (goto-char from-position)
      (forward-char symbol-width)
      ;; Draw graph column by column.
      (sit-for 0)
      (setq numbers-list (cdr numbers-list)))
    ;; Place point for X axis labels.
    (forward-line height)
    (insert "\n")))

Finally, the code for the print-graph function:

;;; Final version.
(defun print-graph
  (numbers-list &optional vertical-step)
  "Print labelled bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values.

Optionally, VERTICAL-STEP, a positive integer,
specifies how much a Y axis label increments for
each line.  For example, a step of 5 means that
each row is five units."
  (let* ((symbol-width (length graph-blank))
         ;; height is both the largest number
         ;; and the number with the most digits.
         (height (apply 'max numbers-list))
         (height-of-top-line
          (if (zerop (% height Y-axis-label-spacing))
              height
            ;; else
            (* (1+ (/ height Y-axis-label-spacing))
               Y-axis-label-spacing)))
         (vertical-step (or vertical-step 1))
         (full-Y-label-width
          (length
           (concat
            (number-to-string
             (* height-of-top-line vertical-step))
            Y-axis-tic))))

    (print-Y-axis
     height-of-top-line full-Y-label-width vertical-step)
    (graph-body-print
     numbers-list height-of-top-line symbol-width)
    (print-X-axis numbers-list)))

Node:Test print-graph, Next:Graphing words in defuns, Previous:The final version, Up:Print Whole Graph

C.4.1 Testing print-graph

We can test the print-graph function with a short list of numbers:

  1. Install the final versions of Y-axis-column, graph-body-print, and print-graph (in addition to the rest of the code.)
  2. Copy the following expression:
    (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
  3. Switch to the *scratch* buffer and place the cursor where you want the axis labels to start.
  4. Type M-: (eval-expression).
  5. Yank the test expression into the minibuffer with C-y (yank).
  6. Press <RET> to evaluate the expression.

Emacs will print a graph that looks like this:

10 -

         *
        **   *
 5 -   ****  *
       **** ***
     * *********
     ************
 1 - *************

     |   |    |    |
     1   5   10   15

On the other hand, if you pass print-graph a vertical-step value of 2, by evaluating this expression:

(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)

The graph looks like this:

20 -

         *
        **   *
10 -   ****  *
       **** ***
     * *********
     ************
 2 - *************

     |   |    |    |
     1   5   10   15

(A question: is the `2' on the bottom of the vertical axis a bug or a feature? If you think it is a bug, and should be a `1' instead, (or even a `0'), you can modify the sources.)

Node:Graphing words in defuns, Next:lambda, Previous:Test print-graph, Up:Print Whole Graph

C.4.2 Graphing Numbers of Words and Symbols

Now for the graph for which all this code was written: a graph that shows how many function definitions contain fewer than 10 words and symbols, how many contain between 10 and 19 words and symbols, how many contain between 20 and 29 words and symbols, and so on.

This is a multi-step process. First make sure you have loaded all the requisite code.

It is a good idea to reset the value of top-of-ranges in case you have set it to some different value. You can evaluate the following:

(setq top-of-ranges
 '(10  20  30  40  50
   60  70  80  90 100
  110 120 130 140 150
  160 170 180 190 200
  210 220 230 240 250
  260 270 280 290 300)

Next create a list of the number of words and symbols in each range.

Evaluate the following:

(setq list-for-graph
       (defuns-per-range
         (sort
          (recursive-lengths-list-many-files
           (directory-files "/usr/local/emacs/lisp"
                            t ".+el$"))
          '<)
         top-of-ranges))

On my machine, this takes about an hour. It looks though 303 Lisp files in my copy of Emacs version 19.23. After all that computing, the list-for-graph has this value:

(537 1027 955 785 594 483 349 292 224 199 166 120 116 99
90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)

This means that my copy of Emacs has 537 function definitions with fewer than 10 words or symbols in them, 1,027 function definitions with 10 to 19 words or symbols in them, 955 function definitions with 20 to 29 words or symbols in them, and so on.

Clearly, just by looking at this list we can see that most function definitions contain ten to thirty words and symbols.

Now for printing. We do not want to print a graph that is 1,030 lines high ... Instead, we should print a graph that is fewer than twenty-five lines high. A graph that height can be displayed on almost any monitor, and easily printed on a sheet of paper.

This means that each value in list-for-graph must be reduced to one-fiftieth its present value.

Here is a short function to do just that, using two functions we have not yet seen, mapcar and lambda.

(defun one-fiftieth (full-range)
  "Return list, each number one-fiftieth of previous."
 (mapcar '(lambda (arg) (/ arg 50)) full-range))

Node:lambda, Next:mapcar, Previous:Graphing words in defuns, Up:Print Whole Graph

C.4.3 A lambda Expression: Useful Anonymity

lambda is the symbol for an anonymous function, a function without a name. Every time you use an anonymous function, you need to include its whole body.

Thus,

(lambda (arg) (/ arg 50))

is a function definition that says `return the value resulting from dividing whatever is passed to me as arg by 50'.

Earlier, for example, we had a function multiply-by-seven; it multiplied its argument by 7. This function is similar, except it divides its argument by 50; and, it has no name. The anonymous equivalent of multiply-by-seven is:

(lambda (number) (* 7 number))

(See The defun Special Form.)

If we want to multiply 3 by 7, we can write:

(multiply-by-seven 3)
 \_______________/ ^
         |         |
      function  argument

This expression returns 21.

Similarly, we can write:

((lambda (number) (* 7 number)) 3)
 \____________________________/ ^
               |                |
      anonymous function     argument

If we want to divide 100 by 50, we can write:

((lambda (arg) (/ arg 50)) 100)
 \______________________/  \_/
             |              |
    anonymous function   argument

This expression returns 2. The 100 is passed to the function, which divides that number by 50.

See Lambda Expressions, for more about lambda. Lisp and lambda expressions derive from the Lambda Calculus.

Node:mapcar, Next:Another Bug, Previous:lambda, Up:Print Whole Graph

C.4.4 The mapcar Function

mapcar is a function that calls its first argument with each element of its second argument, in turn. The second argument must be a sequence.

The map part of the name comes from the mathematical phrase, `mapping over a domain', meaning to apply a function to each of the elements in a domain. The mathematical phrase is based on the metaphor of a surveyor walking, one step at a time, over an area he is mapping. And car, of course, comes from the Lisp notion of the first of a list.

For example,

(mapcar '1+ '(2 4 6))
     => (3 5 7)

The function 1+ which adds one to its argument, is executed on each element of the list, and a new list is returned.

Contrast this with apply, which applies its first argument to all the remaining. (See Readying a Graph, for a explanation of apply.)

In the definition of one-fiftieth, the first argument is the anonymous function:

(lambda (arg) (/ arg 50))

and the second argument is full-range, which will be bound to list-for-graph.

The whole expression looks like this:

(mapcar '(lambda (arg) (/ arg 50)) full-range))

See Mapping Functions, for more about mapcar.

Using the one-fiftieth function, we can generate a list in which each element is one-fiftieth the size of the corresponding element in list-for-graph.

(setq fiftieth-list-for-graph
      (one-fiftieth list-for-graph))

The resulting list looks like this:

(10 20 19 15 11 9 6 5 4 3 3 2 2
1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)

This, we are almost ready to print! (We also notice the loss of information: many of the higher ranges are 0, meaning that fewer than 50 defuns had that many words or symbols--but not necessarily meaning that none had that many words or symbols.)

Node:Another Bug, Next:Final printed graph, Previous:mapcar, Up:Print Whole Graph

C.4.5 Another Bug ... Most Insidious

I said `almost ready to print'! Of course, there is a bug in the print-graph function ... It has a vertical-step option, but not a horizontal-step option. The top-of-range scale goes from 10 to 300 by tens. But the print-graph function will print only by ones.

This is a classic example of what some consider the most insidious type of bug, the bug of omission. This is not the kind of bug you can find by studying the code, for it is not in the code; it is an omitted feature. Your best actions are to try your program early and often; and try to arrange, as much as you can, to write code that is easy to understand and easy to change. Try to be aware, whenever you can, that whatever you have written, will be rewritten, if not soon, eventually. A hard maxim to follow.

It is the print-X-axis-numbered-line function that needs the work; and then the print-X-axis and the print-graph functions need to be adapted. Not much needs to be done; there is one nicety: the numbers ought to line up under the tic marks. This takes a little thought.

Here is the corrected print-X-axis-numbered-line:

(defun print-X-axis-numbered-line
  (number-of-X-tics X-axis-leading-spaces
   &optional horizontal-step)
  "Print line of X-axis numbers"
  (let ((number X-axis-label-spacing)
        (horizontal-step (or horizontal-step 1)))
    (insert X-axis-leading-spaces)
    ;; Delete extra leading spaces.
    (delete-char
     (- (1-
         (length (number-to-string horizontal-step)))))
    (insert (concat
             (make-string
              ;; Insert white space.
              (-  (* symbol-width
                     X-axis-label-spacing)
                  (1-
                   (length
                    (number-to-string horizontal-step)))
                  2)
              ? )
             (number-to-string
              (* number horizontal-step))))
    ;; Insert remaining numbers.
    (setq number (+ number X-axis-label-spacing))
    (while (> number-of-X-tics 1)
      (insert (X-axis-element
               (* number horizontal-step)))
      (setq number (+ number X-axis-label-spacing))
      (setq number-of-X-tics (1- number-of-X-tics)))))

If you are reading this in Info, you can see the new versions of print-X-axis print-graph and evaluate them. If you are reading this in a printed book, you can see the changed lines here (the full text is too much to print).

(defun print-X-axis (numbers-list horizontal-step)
  "Print X axis labels to length of NUMBERS-LIST.
Optionally, HORIZONTAL-STEP, a positive integer,
specifies how much an X  axis label increments for
each column."
;; Value of symbol-width and full-Y-label-width
;; are passed by `print-graph'.
  (let* ((leading-spaces
          (make-string full-Y-label-width ? ))
       ;; symbol-width is provided by graph-body-print
       (tic-width (* symbol-width X-axis-label-spacing))
       (X-length (length numbers-list))
       (X-tic
        (concat
         (make-string
          ;; Make a string of blanks.
          (-  (* symbol-width X-axis-label-spacing)
              (length X-axis-tic-symbol))
          ? )
         ;; Concatenate blanks with tic symbol.
         X-axis-tic-symbol))
       (tic-number
        (if (zerop (% X-length tic-width))
            (/ X-length tic-width)
          (1+ (/ X-length tic-width)))))

    (print-X-axis-tic-line
     tic-number leading-spaces X-tic)
    (insert "\n")
    (print-X-axis-numbered-line
     tic-number leading-spaces horizontal-step)))

(defun print-graph
  (numbers-list &optional vertical-step horizontal-step)
  "Print labelled bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values.

Optionally, VERTICAL-STEP, a positive integer,
specifies how much a Y axis label increments for
each line.  For example, a step of 5 means that
each row is five units.

Optionally, HORIZONTAL-STEP, a positive integer,
specifies how much an X  axis label increments for
each column."
  (let* ((symbol-width (length graph-blank))
         ;; height is both the largest number
         ;; and the number with the most digits.
         (height (apply 'max numbers-list))
         (height-of-top-line
          (if (zerop (% height Y-axis-label-spacing))
              height
            ;; else
            (* (1+ (/ height Y-axis-label-spacing))
               Y-axis-label-spacing)))
         (vertical-step (or vertical-step 1))
         (full-Y-label-width
          (length
           (concat
            (number-to-string
             (* height-of-top-line vertical-step))
            Y-axis-tic))))
    (print-Y-axis
     height-of-top-line full-Y-label-width vertical-step)
    (graph-body-print
        numbers-list height-of-top-line symbol-width)
    (print-X-axis numbers-list horizontal-step)))

Node:Final printed graph, Previous:Another Bug, Up:Print Whole Graph

C.4.6 The Printed Graph

When made and installed, you can call the print-graph command like this:

(print-graph fiftieth-list-for-graph 50 10)

Here is the graph:

1000 -  *
        **
        **
        **
        **
 750 -  ***
        ***
        ***
        ***
        ****
 500 - *****
       ******
       ******
       ******
       *******
 250 - ********
       *********                     *
       ***********                   *
       *************                 *
  50 - ***************** *           *
       |   |    |    |    |    |    |    |
      10  50  100  150  200  250  300  350

The largest group of functions contain 10 - 19 words and symbols each.

Node:GNU Free Documentation License, Next:Index, Previous:Full Graph, Up:Top

Appendix D GNU Free Documentation License

Version 1.1, March 2000
Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

Node:Index, Next:About the Author, Previous:GNU Free Documentation License, Up:Top

Index

  • % (remainder function): Compute a Remainder
  • (debug) in code: debug-on-quit
  • * (multiplication): defun
  • * for read-only buffer: Read-only buffer
  • *scratch* buffer: print-elements-of-list
  • .emacs file: Emacs Initialization
  • .emacs file, beginning of: Beginning a .emacs File
  • / (division): Large buffer case
  • <= (less than or equal): Inc Example parts
  • > (greater than): if in more detail
  • Accumulate, type of recursive pattern: Accumulate
  • add-hook: Text and Auto-fill
  • and: fwd-para let, kill-new function
  • and, introduced: kill-new function
  • Anonymous function: lambda
  • append-to-buffer: append-to-buffer
  • apply: Columns of a graph
  • apropos: Columns of a graph
  • Argument as local variable: Dec Example altogether
  • argument defined: Arguments
  • argument list defined: defun
  • Argument, wrong type of: Wrong Type of Argument
  • Arguments: Arguments
  • Arguments' data types: Data types
  • Arguments, variable number of: Variable Number of Arguments
  • Asterisk for read-only buffer: Read-only buffer
  • Auto Fill mode turned on: Text and Auto-fill
  • autoload: Autoload
  • Automatic mode selection: Text and Auto-fill
  • Axis, print horizontal: print-X-axis
  • Axis, print vertical: print-Y-axis
  • beginning-of-buffer: beginning-of-buffer
  • bind defined: set & setq
  • body defined: defun
  • Body of graph: Readying a Graph
  • Buffer size: Buffer Size & Locations
  • Buffer, history of word: Buffer Names
  • buffer-file-name: Buffer Names
  • buffer-menu, bound to key: Keybindings
  • buffer-name: Buffer Names
  • Bug, most insidious type: Another Bug
  • Building robots: Building Robots
  • Building Tags in the Emacs sources: etags
  • Byte compiling: Byte Compiling
  • C language primitives: Primitive Functions
  • C, a digression into: Digression into C
  • call defined: Switching Buffers
  • cancel-debug-on-entry: debug-on-entry
  • car, introduced: car cdr & cons
  • cdr, introduced: car cdr & cons
  • Changing a function definition: Change a defun
  • Chest of Drawers, metaphor for a symbol: Symbols as Chest
  • Clipping text: Cutting & Storing Text
  • Code installation: Permanent Installation
  • command defined: How to Evaluate
  • Comments in Lisp code: Change a defun
  • Common Lisp: Lisp History
  • compare-windows: Keybindings
  • concat: Data types
  • cond: Recursion with cond
  • condition-case: condition-case
  • Conditional 'twixt two versions of Emacs: Simple Extension
  • Conditional with if: if
  • cons, example: kill-new function
  • cons, introduced: cons
  • copy-region-as-kill: copy-region-as-kill
  • copy-to-buffer: copy-to-buffer
  • Count words recursively: recursive-count-words
  • count-words-in-defun: count-words-in-defun
  • count-words-region: count-words-region
  • Counting: Counting
  • Counting words in a defun: count-words-in-defun, Words in a defun
  • current-buffer: Getting Buffers
  • Customizing your .emacs file: Emacs Initialization
  • Cutting and storing text: Cutting & Storing Text
  • Data types: Data types
  • debug: debug
  • debug-on-entry: debug-on-entry
  • debug-on-quit: debug-on-quit
  • debugging: Debugging
  • default-mode-line-format: Mode Line
  • default.el init file: Site-wide Init
  • defcustom: defcustom
  • Deferment in recursion: No Deferment
  • Defermentless solution: No deferment solution
  • Definition installation: Install
  • Definition writing: Writing Defuns
  • Definition, how to change: Change a defun
  • defun: defun
  • defvar: defvar
  • defvar for a user customizable variable: defvar and asterisk
  • defvar with an asterisk: defvar and asterisk
  • delete-and-extract-region: Digression into C, delete-and-extract-region
  • Deleting text: Cutting & Storing Text
  • describe-function: simplified-beginning-of-buffer
  • describe-function, introduced: Finding More
  • Digression into C: Digression into C
  • directory-files: Files List
  • Division: Large buffer case
  • dolist: dolist
  • dotimes: dotimes
  • Drawers, Chest of, metaphor for a symbol: Symbols as Chest
  • Duplicated words function: the-the
  • edebug: edebug
  • edit-options: defvar and asterisk
  • Else: else
  • Emacs version, choosing: Simple Extension
  • empty list defined: Lisp Atoms
  • empty string defined: Review
  • eobp: fwd-para between paragraphs
  • eq: Review
  • eq (example of use): last-command & this-command
  • equal: Review
  • Erasing text: Cutting & Storing Text
  • error: rotate-yk-ptr body
  • Error for symbol without function: Void Function
  • Error for symbol without value: Void Variable
  • Error message generation: Making Errors
  • etags: etags
  • evaluate defined: Run a Program
  • Evaluating inner lists: Evaluating Inner Lists
  • Evaluation: Evaluation
  • Evaluation practice: Practicing Evaluation
  • Every, type of recursive pattern: Every
  • Example variable, fill-column: fill-column Example
  • expression defined: Lisp Atoms
  • Falsehood and truth in Emacs Lisp: Truth & Falsehood
  • FDL, GNU Free Documentation License: GNU Free Documentation License
  • files-in-below-directory: Files List
  • fill-column, an example variable: fill-column Example
  • Find a File: Find a File
  • Find function documentation: Finding More
  • Find source of function: Finding More
  • find-tags: Finding More
  • Flowers in a field: Lisp Lists
  • Focusing attention (narrowing): Narrowing & Widening
  • form defined: Lisp Atoms
  • Formatting convention: append save-excursion
  • Formatting help: Typing Lists
  • forward-paragraph: forward-paragraph
  • forward-sentence: forward-sentence
  • function defined: Making Errors
  • function definition defined: defun
  • Function definition installation: Install
  • Function definition writing: Writing Defuns
  • Function definition, how to change: Change a defun
  • Functions, primitive: Primitive Functions
  • Generate an error message: Making Errors
  • Getting a buffer: Getting Buffers
  • Global set key: Keybindings
  • global-set-key: Keybindings
  • global-unset-key: Keybindings
  • Graph prototype: Readying a Graph
  • Graph, printing all: Print Whole Graph
  • graph-body-print: graph-body-print
  • graph-body-print Final version.: The final version
  • Handling the kill ring: Kill Ring
  • Help typing lists: Typing Lists
  • Horizontal axis printing: print-X-axis
  • if: if
  • if-part defined: if in more detail
  • indent-tabs-mode: Indent Tabs Mode
  • Indentation for formatting: append save-excursion
  • Initialization file: Emacs Initialization
  • Initializing a variable: defvar
  • Inner list evaluation: Evaluating Inner Lists
  • insert-buffer: insert-buffer
  • insert-buffer-substring: append-to-buffer overview
  • Insidious type of bug: Another Bug
  • Install a Function Definition: Install
  • Install code permanently: Permanent Installation
  • interactive: Interactive
  • interactive function defined: How to Evaluate
  • Interactive functions: Interactive
  • Interactive options: Interactive Options
  • interactive, example use of: insert-buffer interactive
  • Interpreter, Lisp, explained: Run a Program
  • Interpreter, what it does: Lisp Interpreter
  • Keep, type of recursive pattern: Keep
  • Key setting globally: Keybindings
  • Key unbinding: Keybindings
  • Keymaps: Keymaps
  • Keyword: Optional Arguments
  • Kill ring handling: Kill Ring
  • Kill ring overview: Kill Ring Overview
  • kill-append: kill-append function
  • kill-new: kill-new function
  • kill-region: kill-region
  • Killing text: Cutting & Storing Text
  • lambda: lambda
  • length: length
  • lengths-list-file: lengths-list-file
  • lengths-list-many-files: lengths-list-many-files
  • let: let
  • let expression sample: Sample let Expression
  • let expression, parts of: Parts of let Expression
  • let variables uninitialized: Uninitialized let Variables
  • Library, as term for `file': Finding More
  • line-to-top-of-window: Simple Extension
  • Lisp Atoms: Lisp Atoms
  • Lisp history: Lisp History
  • Lisp interpreter, explained: Run a Program
  • Lisp interpreter, what it does: Lisp Interpreter
  • Lisp Lists: Lisp Lists
  • Lisp macro: delete-and-extract-region
  • list-buffers, rebound: Keybindings
  • Lists in a computer: List Implementation
  • load-library: Loading Files
  • load-path: Loading Files
  • Loading files: Loading Files
  • local variable defined: Prevent confusion
  • Local variables list, per-buffer,: Text and Auto-fill
  • Location of point: Buffer Size & Locations
  • looking-at: fwd-para between paragraphs
  • Loops: while
  • Loops and recursion: Loops & Recursion
  • Maclisp: Lisp History
  • Macro, lisp: delete-and-extract-region
  • Mail aliases: Mail Aliases
  • make tags: etags
  • make-string: Y Axis Element
  • mapcar: mapcar
  • mark: save-excursion
  • mark-whole-buffer: mark-whole-buffer
  • match-beginning: fwd-para no fill prefix
  • max: Columns of a graph
  • message: message
  • min: Columns of a graph
  • Mode line format: Mode Line
  • Mode selection, automatic: Text and Auto-fill
  • Motion by sentence and paragraph: Regexp Search
  • Narrowing: Narrowing & Widening
  • narrowing defined: Buffer Size & Locations
  • nil: Truth & Falsehood
  • nil, history of word: Buffer Names
  • No deferment solution: No deferment solution
  • nreverse: Counting function definitions
  • nth: nth
  • nthcdr: copy-region-as-kill, nthcdr
  • nthcdr, example: kill-new function
  • number-to-string: Y Axis Element
  • occur: Keybindings
  • optional: Optional Arguments
  • Optional arguments: Optional Arguments
  • Options for interactive: Interactive Options
  • or: Insert or
  • other-buffer: Getting Buffers
  • Paragraphs, movement by: Regexp Search
  • Parts of a Recursive Definition: Recursive Definition Parts
  • Parts of let expression: Parts of let Expression
  • Passing information to functions: Arguments
  • Pasting text: Yanking
  • Patterns, searching for: Regexp Search
  • Per-buffer, local variables list: Text and Auto-fill
  • Permanent code installation: Permanent Installation
  • point: save-excursion
  • point defined: Buffer Size & Locations
  • Point location: Buffer Size & Locations
  • Point, mark, buffer preservation: save-excursion
  • Practicing evaluation: Practicing Evaluation
  • Preserving point, mark, and buffer: save-excursion
  • Primitive functions: Primitive Functions
  • Primitives written in C: Primitive Functions
  • Print horizontal axis: print-X-axis
  • Print vertical axis: print-Y-axis
  • print-elements-of-list: print-elements-of-list
  • print-elements-recursively: Recursion with list
  • print-graph Final version.: The final version
  • print-graph varlist: print-graph Varlist
  • print-X-axis: X Axis Tic Marks
  • print-X-axis-numbered-line: X Axis Tic Marks
  • print-X-axis-tic-line: X Axis Tic Marks
  • print-Y-axis: print-Y-axis Penultimate
  • Printing the whole graph: Print Whole Graph
  • prog1: fwd-para between paragraphs
  • progn: progn
  • Program, running one: Run a Program
  • Prototype graph: Readying a Graph
  • re-search-forward: re-search-forward
  • Read-only buffer: Read-only buffer
  • Readying a graph: Readying a Graph
  • Rebinding keys: Keymaps
  • Recursion: Recursion
  • Recursion and loops: Loops & Recursion
  • Recursion without Deferments: No Deferment
  • Recursive Definition Parts: Recursive Definition Parts
  • Recursive pattern: accumulate: Accumulate
  • Recursive pattern: every: Every
  • Recursive pattern: keep: Keep
  • Recursive Patterns: Recursive Patterns
  • recursive-count-words: recursive-count-words
  • recursive-graph-body-print: recursive-graph-body-print
  • recursive-lengths-list-many-files: Several files recursively
  • Recursively counting words: recursive-count-words
  • regexp-quote: fwd-para let
  • Region, what it is: save-excursion
  • Regular expression searches: Regexp Search
  • Regular expressions for word counting: Counting Words
  • Remainder function, %: Compute a Remainder
  • Repetition (loops): Loops & Recursion
  • Repetition for word counting: Counting Words
  • Retrieving text: Yanking
  • reverse: Counting function definitions
  • Ring, making a list like a: Kill Ring
  • Robots, building: Building Robots
  • rotate-yank-pointer: rotate-yank-pointer, Yanking
  • Run a program: Run a Program
  • Sample let expression: Sample let Expression
  • save-excursion: save-excursion
  • save-restriction: save-restriction
  • search-forward: search-forward
  • Searches, illustrating: Regexp Search
  • sentence-end: sentence-end
  • Sentences, movement by: Regexp Search
  • set: Using set
  • set-buffer: Switching Buffers
  • setcar: setcar
  • setcdr: setcdr
  • setcdr, example: kill-new function
  • setq: Using setq
  • Setting a key globally: Keybindings
  • Setting value of variable: set & setq
  • side effect defined: Evaluation
  • Simple extension in .emacs file: Simple Extension
  • simplified-beginning-of-buffer: simplified-beginning-of-buffer
  • site-init.el init file: Site-wide Init
  • site-load.el init file: Site-wide Init
  • Size of buffer: Buffer Size & Locations
  • Solution without deferment: No deferment solution
  • sort: Sorting
  • Source level debugger: edebug
  • Special form: Complications
  • Special form of defun: defun
  • Storing and cutting text: Cutting & Storing Text
  • string defined: Lisp Atoms
  • switch-to-buffer: Switching Buffers
  • Switching to a buffer: Switching Buffers
  • Symbol names: Names & Definitions
  • Symbol without function error: Void Function
  • Symbol without value error: Void Variable
  • Symbolic expressions, introduced: Lisp Atoms
  • Symbols as a Chest of Drawers: Symbols as Chest
  • Syntax categories and tables: Syntax
  • Tabs, preventing: Indent Tabs Mode
  • TAGS file, create own: etags
  • Tags in the Emacs sources: etags
  • TAGS table, specifying: Finding More
  • Text between double quotation marks: Lisp Atoms
  • Text Mode turned on: Text and Auto-fill
  • Text retrieval: Yanking
  • the-the: the-the
  • then-part defined: if in more detail
  • top-of-ranges: Counting function definitions
  • triangle-bugged: debug
  • triangle-recursively: Recursive triangle function
  • Truth and falsehood in Emacs Lisp: Truth & Falsehood
  • Types of data: Data types
  • Unbinding key: Keybindings
  • Uninitialized let variables: Uninitialized let Variables
  • Variable initialization: defvar
  • Variable number of arguments: Variable Number of Arguments
  • Variable, example of, fill-column: fill-column Example
  • Variable, setting value: set & setq
  • Variables: Variables
  • varlist defined: Parts of let Expression
  • Version of Emacs, choosing: Simple Extension
  • Vertical axis printing: print-Y-axis
  • what-line: what-line
  • while: while
  • Whitespace in lists: Whitespace in Lists
  • Whole graph printing: Print Whole Graph
  • Widening: Narrowing & Widening
  • Widening, example of: what-line
  • Word counting in a defun: Words in a defun
  • Words and symbols in defun: Words and Symbols
  • Words, counted recursively: recursive-count-words
  • Words, duplicated: the-the
  • Writing a function definition: Writing Defuns
  • Wrong type of argument: Wrong Type of Argument
  • X axis printing: print-X-axis
  • X-axis-element: X Axis Tic Marks
  • Y axis printing: print-Y-axis
  • Y-axis-column: Y-axis-column
  • Y-axis-column Final version.: The final version
  • Y-axis-label-spacing: Compute a Remainder
  • Y-axis-tic: Y Axis Element
  • yank: yank, Yanking
  • yank-pop: yank-pop
  • zap-to-char: zap-to-char
  • zerop: rotate-yk-ptr body

Node:About the Author, Previous:Index, Up:Top

About the Author

Robert J. Chassell has worked with GNU Emacs since 1985. He writes and edits, teaches Emacs and Emacs Lisp, and speaks throughout the world on software freedom. Chassell was a founding Director and Treasurer of the Free Software Foundation, Inc. He is co-author of the Texinfo manual, and has edited more than a dozen other books. He graduated from Cambridge University, in England. He has an abiding interest in social and economic history and flies his own airplane.

Footnotes

  1. It is curious to track the path by which the word `argument' came to have two different meanings, one in mathematics and the other in everyday English. According to the Oxford English Dictionary, the word derives from the Latin for to make clear, prove; thus it came to mean, by one thread of derivation, `the evidence offered as proof', which is to say, `the information offered', which led to its meaning in Lisp. But in the other thread of derivation, it came to mean `to assert in a manner against which others may make counter assertions', which led to the meaning of the word as a disputation. (Note here that the English word has two different definitions attached to it at the same time. By contrast, in Emacs Lisp, a symbol cannot have two different function definitions at the same time.)

  2. Actually, you can use %s to print a number. It is non-specific. %d prints only the part of a number left of a decimal point, and not anything that is not a number.

  3. Actually, by default, if the buffer from which you just switched is visible to you in another window, other-buffer will choose the most recent buffer that you cannot see; this is a subtlety that I often forget.

  4. Or rather, to save typing, you probably typed just part of the name, such as *sc, and then pressed your TAB key to cause it to expand to the full name; and then typed your RET key.

  5. Remember, this expression will move you to your most recent other buffer that you cannot see. If you really want to go to your most recently selected buffer, even if you can still see it, you need to evaluate the following more complex expression:

    (switch-to-buffer (other-buffer (current-buffer) t))

    In this case, the first argument to other-buffer tells it which buffer to skip--the current one--and the second argument tells other-buffer it is OK to switch to a visible buffer. In regular use, switch-to-buffer takes you to an invisible window since you would most likely use C-x o (other-window) to go to another visible buffer.

  6. Actually, you can cons an element to an atom to produce a dotted pair. Dotted pairs are not discussed here; see Dotted Pair Notation.

  7. More precisely, and requiring more expert knowledge to understand, the two integers are of type `Lisp_Object', which can also be a C union instead of an integer type.

  8. You can write recursive functions to be frugal or wasteful of mental or computer resources; as it happens, methods that people find easy--that are frugal of `mental resources'--sometimes use considerable computer resources. Emacs was designed to run on machines that we now consider limited and its default settings are conservative. You may want to increase the values of max-specpdl-size and max-lisp-eval-depth. In my .emacs file, I set them to 15 and 30 times their default value.

  9. The phrase tail recursive is used to describe such a process, one that uses `constant space'.

  10. The jargon is mildly confusing: triangle-recursive-helper uses a process that is iterative in a procedure that is recursive. The process is called iterative because the computer need only record the three values, sum, counter, and number; the procedure is recursive because the function `calls itself'. On the other hand, both the process and the procedure used by triangle-recursively are called recursive. The word `recursive' has different meanings in the two contexts.

  11. You may also add .el to ~/.emacs and call it a ~/.emacs.el file. In the past, you were forbidden to type the extra keystrokes that the name ~/.emacs.el requires, but now you may. The new format is consistent with the Emacs Lisp file naming conventions; the old format saves typing.

  12. When I start instances of Emacs that do not load my .emacs file or any site file, I also turn off blinking:

    emacs -q --no-site-file -eval '(blink-cursor-mode nil)'

  13. I occasionally run more modern window managers, such as Sawfish with GNOME, Enlightenment, SCWM, or KDE; in those cases, I often specify an image rather than a plain color.


GNU Emacs Manual:

[Top]

[Contents]

[Index]

[ ? ]

GNU Emacs Manual

Emacs is the extensible, customizable, self-documenting real-time display editor. This Info file describes how to edit with Emacs and some of how to customize it; it corresponds to GNU Emacs version 21.2. For information on extending Emacs, see section `Top' in The Emacs Lisp Reference Manual.

Distribution

How to get the latest Emacs distribution.

GNU GENERAL PUBLIC LICENSE

The GNU General Public License gives you permission to redistribute GNU Emacs on certain terms; it also explains that there is no warranty.

A. GNU Free Documentation License

The license for this documentation.

Introduction

An introduction to Emacs concepts.

Glossary

The glossary.

AF. Emacs 20 Antinews

Information about Emacs version 20.

AG. Emacs and the Mac OS

Using Emacs in the Mac.

AH. Emacs and MS-DOS

Using Emacs on MS-DOS (otherwise known as "MS-DOG").

The GNU Manifesto

What's GNU? Gnu's Not Unix!

AI. Acknowledgments

Major contributors to GNU Emacs.

Indexes (nodes containing large menus)

Key (Character) Index

An item for each standard Emacs key sequence.

Command and Function Index

An item for each command name.

Variable Index

An item for each documented variable.

Concept Index

An item for each concept.

Command-Line Options Index

An item for every command-line option.

Important General Concepts

B. The Organization of the Screen

How to interpret what you see on the screen.

B.5 Kinds of User Input

Kinds of input events (characters, buttons, function keys).

B.6 Keys

Key sequences: what you type to request one editing action.

B.7 Keys and Commands

Named functions run by key sequences to do editing.

B.8 Character Set for Text

Character set for text (the contents of buffers and strings).

C. Entering and Exiting Emacs

Starting Emacs from the shell.

C.1 Exiting Emacs

Stopping or killing Emacs.

AE. Command Line Arguments

Hairy startup options.

Fundamental Editing Commands

D. Basic Editing Commands

The most basic editing commands.

E. The Minibuffer

Entering arguments that are prompted for.

F. Running Commands by Name

Invoking commands by their names.

G. Help

Commands for asking Emacs about its commands.

Important Text-Changing Commands

H. The Mark and the Region

The mark: how to delimit a "region" of text.

H.7 Deletion and Killing

Killing text.

H.8 Yanking

Recovering killed text. Moving text.

H.9 Accumulating Text

Other ways of copying text.

H.10 Rectangles

Operating on the text inside a rectangle on the screen.

I. Registers

Saving a text string or a location in the buffer.

J. Controlling the Display

Controlling what text is displayed.

K. Searching and Replacement

Finding or replacing occurrences of a string.

L. Commands for Fixing Typos

Commands especially useful for fixing typos.

Major Structures of Emacs

M. File Handling

All about handling files.

N. Using Multiple Buffers

Multiple buffers; editing several files at once.

O. Multiple Windows

Viewing two pieces of text at once.

P. Frames and X Windows

Running the same Emacs session in multiple X windows.

Q. International Character Set Support

Using non-ASCII character sets (the MULE features).

Advanced Features

R. Major Modes

Text mode vs. Lisp mode vs. C mode ...

S. Indentation

Editing the white space at the beginnings of lines.

T. Commands for Human Languages

Commands and modes for editing English.

U. Editing Programs

Commands and modes for editing programs.

V. Compiling and Testing Programs

Compiling, running and debugging programs.

W. Maintaining Programs

Features for maintaining large programs.

X. Abbrevs

How to define text abbreviations to reduce the number of characters you must type.

Y. Editing Pictures

Editing pictures made up of characters using the quarter-plane screen model.

Z. Sending Mail

Sending mail in Emacs.

AA. Reading Mail with Rmail

Reading mail in Emacs.

AB. Dired, the Directory Editor

You can "edit" a directory to manage files in it.

AC. The Calendar and the Diary

The calendar and diary facilities.

AC.14 Gnus

How to read netnews with Emacs.

AC.15 Running Shell Commands from Emacs

Executing shell commands from Emacs.

AC.16 Using Emacs as a Server

Using Emacs as an editing server for mail, etc.

AC.18 Hardcopy Output

Printing buffers or regions.

AC.19 PostScript Hardcopy

Printing buffers or regions as PostScript.

AC.20 Variables for PostScript Hardcopy

Customizing the PostScript printing commands.

AC.21 Sorting Text

Sorting lines, paragraphs or pages within Emacs.

AC.22 Narrowing

Restricting display and editing to a portion of the buffer.

AC.23 Two-Column Editing

Splitting apart columns to edit them in side-by-side windows.

AC.24 Editing Binary Files

Using Hexl mode to edit binary files.

AC.25 Saving Emacs Sessions

Saving Emacs state from one session to the next.

AC.26 Recursive Editing Levels

A command can allow you to do editing

"within the command". This is called a
"recursive editing level".

AC.27 Emulation

Emulating some other editors with Emacs.

AC.28 Hyperlinking and Navigation Features

Following links in buffers.

AC.29 Dissociated Press

Dissociating text for fun.

AC.30 Other Amusements

Various games and hacks.

AD. Customization

Modifying the behavior of Emacs.

Recovery from Problems

AD.8 Quitting and Aborting

Quitting and aborting.

AD.9 Dealing with Emacs Trouble

What to do if Emacs is hung or malfunctioning.

AD.10 Reporting Bugs

How and when to report a bug.

AD.11 Contributing to Emacs Development

How to contribute improvements to Emacs.

AD.12 How To Get Help with GNU Emacs

How to get help for your own Emacs needs.

Here are some other nodes which are really inferiors of the ones
already listed, mentioned here so you can get to them in one step:

-- The Detailed Node Listing ---

The Organization of the Screen

B.1 Point

The place in the text where editing commands operate.

B.2 The Echo Area

Short messages appear at the bottom of the screen.

B.3 The Mode Line

Interpreting the mode line.

B.4 The Menu Bar

How to use the menu bar.

Basic Editing Commands

D.1 Inserting Text

Inserting text by simply typing it.

D.2 Changing the Location of Point

How to move the cursor to the place where you want to change something.

D.3 Erasing Text

Deleting and killing text.

D.4 Undoing Changes

Undoing recent changes in the text.

D.5 Files

Visiting, creating, and saving files.

D.6 Help

Asking what a character does.

D.7 Blank Lines

Commands to make or delete blank lines.

D.8 Continuation Lines

Lines too wide for the screen.

D.9 Cursor Position Information

What page, line, row, or column is point on?

D.10 Numeric Arguments

Numeric arguments for repeating a command.

The Minibuffer

E.1 Minibuffers for File Names

Entering file names with the minibuffer.

E.2 Editing in the Minibuffer

How to edit in the minibuffer.

E.3 Completion

An abbreviation facility for minibuffer input.

E.4 Minibuffer History

Reusing recent minibuffer arguments.

E.5 Repeating Minibuffer Commands

Re-executing commands that used the minibuffer.

Help

G.1 Help Summary

Brief list of all Help commands.

G.2 Documentation for a Key

Asking what a key does in Emacs.

G.3 Help by Command or Variable Name

Asking about a command, variable or function name.

G.4 Apropos

Asking what pertains to a given topic.

G.5 Keyword Search for Lisp Libraries

Finding Lisp libraries by keywords (topics).

G.6 Help for International Language Support

Help relating to international language support.

G.8 Other Help Commands

Other help commands.

The Mark and the Region

H.1 Setting the Mark

Commands to set the mark.

H.2 Transient Mark Mode

How to make Emacs highlight the region-- when there is one.

H.3 Operating on the Region

Summary of ways to operate on contents of the region.

H.4 Commands to Mark Textual Objects

Commands to put region around textual units.

H.5 The Mark Ring

Previous mark positions saved so you can go back there.

H.6 The Global Mark Ring

Previous mark positions in various buffers.

Deletion and Killing

H.7.1 Deletion

Commands for deleting small amounts of text and blank areas.

H.7.2 Killing by Lines

How to kill entire lines of text at one time.

H.7.3 Other Kill Commands

Commands to kill large regions of text and syntactic units such as words and sentences.

Yanking

H.8.1 The Kill Ring

Where killed text is stored. Basic yanking.

H.8.2 Appending Kills

Several kills in a row all yank together.

H.8.3 Yanking Earlier Kills

Yanking something killed some time ago.

Registers

I.1 Saving Positions in Registers

Saving positions in registers.

I.2 Saving Text in Registers

Saving text in registers.

I.3 Saving Rectangles in Registers

Saving rectangles in registers.

I.4 Saving Window Configurations in Registers

Saving window configurations in registers.

I.6 Keeping File Names in Registers

File names in registers.

I.7 Bookmarks

Bookmarks are like registers, but persistent.

Controlling the Display

J.6 Scrolling

Moving text up and down in a window.

J.7 Horizontal Scrolling

Moving text left and right in a window.

J.8 Follow Mode

Follow mode lets two windows scroll as one.

J.9 Selective Display

Hiding lines with lots of indentation.

J.10 Optional Mode Line Features

Optional mode line display features.

J.11 How Text Is Displayed

How text is normally displayed.

J.12 Customization of Display

Information on variables for customizing display.

Searching and Replacement

K.1 Incremental Search

Search happens as you type the string.

K.2 Nonincremental Search

Specify entire string and then search.

K.3 Word Search

Search for sequence of words.

K.4 Regular Expression Search

Search for match for a regexp.

K.5 Syntax of Regular Expressions

Syntax of regular expressions.

K.6 Searching and Case

To ignore case while searching, or not.

K.7 Replacement Commands

Search, and replace some or all matches.

K.8 Other Search-and-Loop Commands

Operating on all matches for some regexp.

Replacement Commands

K.7.1 Unconditional Replacement

Replacing all matches for a string.

K.7.2 Regexp Replacement

Replacing all matches for a regexp.

K.7.3 Replace Commands and Case

How replacements preserve case of letters.

K.7.4 Query Replace

How to use querying.

Commands for Fixing Typos

L.1 Killing Your Mistakes

Commands to kill a batch of recently entered text.

L.2 Transposing Text

Exchanging two characters, words, lines, lists...

L.3 Case Conversion

Correcting case of last word entered.

L.4 Checking and Correcting Spelling

Apply spelling checker to a word or a whole buffer.

File Handling

M.1 File Names

How to type and edit file-name arguments.

M.2 Visiting Files

Visiting a file prepares Emacs to edit the file.

M.3 Saving Files

Saving makes your changes permanent.

M.4 Reverting a Buffer

Reverting cancels all the changes not saved.

M.5 Auto-Saving: Protection Against Disasters

Auto Save periodically protects against loss of data.

M.6 File Name Aliases

Handling multiple names for one file.

M.7 Version Control

Version control systems (RCS, CVS and SCCS).

M.8 File Directories

Creating, deleting, and listing file directories.

M.9 Comparing Files

Finding where two files differ.

M.10 Miscellaneous File Operations

Other things you can do on files.

M.11 Accessing Compressed Files

Accessing compressed files.

M.13 Remote Files

Accessing files on other sites.

M.14 Quoted File Names

Quoting special characters in file names.

Saving Files

M.3.1 Backup Files

How Emacs saves the old version of your file.

M.3.2 Protection against Simultaneous Editing

How Emacs protects against simultaneous editing of one file by two users.

Version Control

M.7.1 Introduction to Version Control

How version control works in general.

M.7.2 Version Control and the Mode Line

How the mode line shows version control status.

M.7.3 Basic Editing under Version Control

How to edit a file under version control.

M.7.4 Examining And Comparing Old Versions

Examining and comparing old versions.

M.7.5 The Secondary Commands of VC

The commands used a little less frequently.

M.7.6 Multiple Branches of a File

Multiple lines of development.

M.7.8 Snapshots

Sets of file versions treated as a unit.

M.7.9 Miscellaneous Commands and Features of VC

Various other commands and features of VC.

M.7.10 Customizing VC

Variables that change VC's behavior.

Using Multiple Buffers

N.1 Creating and Selecting Buffers

Creating a new buffer or reselecting an old one.

N.2 Listing Existing Buffers

Getting a list of buffers that exist.

N.3 Miscellaneous Buffer Operations

Renaming; changing read-onliness; copying text.

N.4 Killing Buffers

Killing buffers you no longer need.

N.5 Operating on Several Buffers

How to go through the list of all buffers and operate variously on several of them.

N.6 Indirect Buffers

An indirect buffer shares the text of another buffer.

Multiple Windows

O.1 Concepts of Emacs Windows

Introduction to Emacs windows.

O.2 Splitting Windows

New windows are made by splitting existing windows.

O.3 Using Other Windows

Moving to another window or doing something to it.

O.4 Displaying in Another Window

Finding a file or buffer in another window.

O.5 Forcing Display in the Same Window

Forcing certain buffers to appear in the selected window rather than in another window.

O.6 Deleting and Rearranging Windows

Deleting windows and changing their sizes.

Frames and X Windows

P.1 Mouse Commands for Editing

Moving, cutting, and pasting, with the mouse.

P.2 Secondary Selection

Cutting without altering point and mark.

P.3 Using the Clipboard

Using the clipboard for selections.

P.4 Following References with the Mouse

Using the mouse to select an item from a list.

P.5 Mouse Clicks for Menus

Mouse clicks that bring up menus.

P.6 Mode Line Mouse Commands

Mouse clicks on the mode line.

P.7 Creating Frames

Creating additional Emacs frames with various contents.

P.8 Frame Commands

Iconifying, deleting, and switching frames.

P.9 Making and Using a Speedbar Frame

How to make and use a speedbar frame.

P.10 Multiple Displays

How one Emacs job can talk to several displays.

P.11 Special Buffer Frames

You can make certain buffers have their own frames.

P.12 Setting Frame Parameters

Changing the colors and other modes of frames.

P.13 Scroll Bars

How to enable and disable scroll bars; how to use them.

P.14 Scrolling With "Wheeled" Mice

Using mouse wheels for scrolling.

P.15 Menu Bars

Enabling and disabling the menu bar.

P.16 Tool Bars

Enabling and disabling the tool bar.

P.17 Using Dialog Boxes

Controlling use of dialog boxes.

J.1 Using Multiple Typefaces

How to change the display style using faces.

J.2 Font Lock mode

Minor mode for syntactic highlighting using faces.

J.3 Highlight Changes Mode

Using colors to show where you changed the buffer.

J.4 Interactive Highlighting by Matching

Tell Emacs what text to highlight.

J.5 Trailing Whitespace

Showing possibly-spurious trailing whitespace.

P.18 Tooltips (or "Balloon Help")

Showing "tooltips", AKA "ballon help" for active text.

P.19 Mouse Avoidance

Moving the mouse pointer out of the way.

P.20 Non-Window Terminals

Multiple frames on terminals that show only one.

P.21 Using a Mouse in Terminal Emulators

Using the mouse in an XTerm terminal emulator.

International Character Set Support

Q.1 Introduction to International Character Sets

Basic concepts of multibyte characters.

Q.2 Enabling Multibyte Characters

Controlling whether to use multibyte characters.

Q.3 Language Environments

Setting things up for the language you use.

Q.4 Input Methods

Entering text characters not on your keyboard.

Q.5 Selecting an Input Method

Specifying your choice of input methods.

Q.7 Coding Systems

Character set conversion when you read and write files, and so on.

Q.8 Recognizing Coding Systems

How Emacs figures out which conversion to use.

Q.9 Specifying a Coding System

Various ways to choose which conversion to use.

Q.10 Fontsets

Fontsets are collections of fonts that cover the whole spectrum of characters.

Q.11 Defining fontsets

Defining a new fontset.

Q.13 Single-byte Character Set Support

You can pick one European character set to use without multibyte characters.

Major Modes

R.1 How Major Modes are Chosen

How major modes are specified or chosen.

Indentation

S.1 Indentation Commands and Techniques

Various commands and techniques for indentation.

S.2 Tab Stops

You can set arbitrary "tab stops" and then indent to the next tab stop when you want to.

S.3 Tabs vs. Spaces

You can request indentation using just spaces.

Commands for Human Languages

T.1 Words

Moving over and killing words.

T.2 Sentences

Moving over and killing sentences.

T.3 Paragraphs

Moving over paragraphs.

T.4 Pages

Moving over pages.

T.5 Filling Text

Filling or justifying text.

T.6 Case Conversion Commands

Changing the case of text.

T.7 Text Mode

The major modes for editing text files.

T.8 Outline Mode

Editing outlines.

T.9 TeX Mode

Editing input to the formatter TeX.

T.10 Nroff Mode

Editing input to the formatter nroff.

T.11 Editing Formatted Text

Editing formatted text directly in WYSIWYG fashion.

Filling Text

T.5.1 Auto Fill Mode

Auto Fill mode breaks long lines automatically.

T.5.3 Explicit Fill Commands

Commands to refill paragraphs and center lines.

T.5.4 The Fill Prefix

Filling paragraphs that are indented or in a comment, etc.

T.5.5 Adaptive Filling

How Emacs can determine the fill prefix automatically.

Editing Programs

U.1 Major Modes for Programming Languages

Major modes for editing programs.

U.2 Top-Level Definitions, or Defuns

Commands to operate on major top-level parts of a program.

U.3 Indentation for Programs

Adjusting indentation to show the nesting.

U.5 Manipulating Comments

Inserting, killing, and aligning comments.

U.4 Commands for Editing with Parentheses

Commands that operate on parentheses.

U.6 Documentation Lookup

Getting documentation of functions you plan to call.

U.7 Hideshow minor mode

Displaying blocks selectively.

U.8 Completion for Symbol Names

Completion on symbol names of your program or language.

U.9 Glasses minor mode

Making identifiersLikeThis more readable.

U.10 Other Features Useful for Editing Programs

Other Emacs features useful for editing programs.

U.11 C and Related Modes

Special commands of C, C++, Objective-C, Java, and Pike modes.

U.12 Fortran Mode

Fortran mode and its special features.

U.13 Asm Mode

Asm mode and its special features.

Top-Level Definitions, or Defuns

U.2.1 Left Margin Convention

An open-paren or similar opening delimiter starts a defun if it is at the left margin.

U.2.2 Moving by Defuns

Commands to move over or mark a major definition.

U.2.3 Imenu

Making buffer indexes as menus.

U.2.4 Which Function Mode

Which Function mode shows which function you are in.

Indentation for Programs

U.3.1 Basic Program Indentation Commands

Indenting a single line.

U.3.2 Indenting Several Lines

Commands to reindent many lines at once.

U.3.3 Customizing Lisp Indentation

Specifying how each Lisp function should be indented.

U.3.4 Commands for C Indentation

Extra features for indenting C and related modes.

U.3.5 Customizing C Indentation

Controlling indentation style for C and related modes.

Commands for Editing with Parentheses

U.4.1 Expressions with Balanced Parentheses

Expressions with balanced parentheses.

U.4.2 Moving in the Parenthesis Structure

Commands for moving up, down and across in the structure of parentheses.

U.4.3 Automatic Display Of Matching Parentheses

Insertion of a close-delimiter flashes matching open.

Manipulating Comments

U.5.1 Comment Commands

Inserting, killing, and indenting comments.

U.5.2 Multiple Lines of Comments

Commands for adding and editing multi-line comments.

U.5.3 Options Controlling Comments

Customizing the comment features.

Documentation Lookup

U.6.1 Info Documentation Lookup

Looking up library functions and commands in Info files.

U.6.2 Man Page Lookup

Looking up man pages of library functions and commands.

U.6.3 Emacs Lisp Documentation Lookup

Looking up Emacs Lisp functions, etc.

C and Related Modes

U.11.1 C Mode Motion Commands

Commands to move by C statements, etc.

U.11.2 Electric C Characters

Colon and other chars can automatically reindent.

U.11.3 Hungry Delete Feature in C

A more powerful DEL command.

U.11.4 Other Commands for C Mode

Filling comments, viewing expansion of macros, and other neat features.

U.11.5 Comments in C Modes

Options for customizing comment style.

Fortran Mode

U.12.1 Motion Commands

Moving point by statements or subprograms.

U.12.2 Fortran Indentation

Indentation commands for Fortran.

U.12.3 Fortran Comments

Inserting and aligning comments.

U.12.4 Fortran Auto Fill Mode

Auto fill minor mode for Fortran.

U.12.5 Checking Columns in Fortran

Measuring columns for valid Fortran.

U.12.6 Fortran Keyword Abbrevs

Built-in abbrevs for Fortran keywords.

Compiling and Testing Programs

V.1 Running Compilations under Emacs

Compiling programs in languages other than Lisp (C, Pascal, etc.).

V.3 Compilation Mode

The mode for visiting compiler errors.

V.4 Subshells for Compilation

Customizing your shell properly for use in the compilation buffer.

V.5 Running Debuggers Under Emacs

Running symbolic debuggers for non-Lisp programs.

V.6 Executing Lisp Expressions

Various modes for editing Lisp programs, with different facilities for running the Lisp programs.

V.7 Libraries of Lisp Code for Emacs

Creating Lisp programs to run in Emacs.

V.9 Lisp Interaction Buffers

Executing Lisp in an Emacs buffer.

V.8 Evaluating Emacs-Lisp Expressions

Executing a single Lisp expression in Emacs.

V.10 Running an External Lisp

Communicating through Emacs with a separate Lisp.

Running Debuggers Under Emacs

V.5.1 Starting GUD

How to start a debugger subprocess.

V.5.2 Debugger Operation

Connection between the debugger and source buffers.

V.5.3 Commands of GUD

Key bindings for common commands.

V.5.4 GUD Customization

Defining your own commands for GUD.

Maintaining Programs

W.1 Change Logs

Maintaining a change history for your program.

W.2 Tags Tables

Go direct to any function in your program in one command. Tags remembers which file it is in.

W.3 Merging Files with Emerge

A convenient way of merging two versions of a program.

Tags Tables

W.2.1 Source File Tag Syntax

Tag syntax for various types of code and text files.

W.2.2 Creating Tags Tables

Creating a tags table with etags.

W.2.4 Selecting a Tags Table

How to visit a tags table.

W.2.5 Finding a Tag

Commands to find the definition of a specific tag.

W.2.6 Searching and Replacing with Tags Tables

Using a tags table for searching and replacing.

W.2.7 Tags Table Inquiries

Listing and finding tags defined in a file.

Merging Files with Emerge

W.3.1 Overview of Emerge

How to start Emerge. Basic concepts.

W.3.2 Submodes of Emerge

Fast mode vs. Edit mode. Skip Prefers mode and Auto Advance mode.

W.3.3 State of a Difference

You do the merge by specifying state A or B for each difference.

W.3.4 Merge Commands

Commands for selecting a difference, changing states of differences, etc.

W.3.5 Exiting Emerge

What to do when you've finished the merge.

W.3.6 Combining the Two Versions

How to keep both alternatives for a difference.

W.3.7 Fine Points of Emerge

Misc.

Abbrevs

X.1 Abbrev Concepts

Fundamentals of defined abbrevs.

X.2 Defining Abbrevs

Defining an abbrev, so it will expand when typed.

X.3 Controlling Abbrev Expansion

Controlling expansion: prefixes, canceling expansion.

X.4 Examining and Editing Abbrevs

Viewing or editing the entire list of defined abbrevs.

X.5 Saving Abbrevs

Saving the entire list of abbrevs for another session.

X.6 Dynamic Abbrev Expansion

Abbreviations for words already in the buffer.

Editing Pictures

Y.1 Basic Editing in Picture Mode

Basic concepts and simple commands of Picture Mode.

Y.2 Controlling Motion after Insert

Controlling direction of cursor motion after "self-inserting" characters.

Y.3 Picture Mode Tabs

Various features for tab stops and indentation.

Y.4 Picture Mode Rectangle Commands

Clearing and superimposing rectangles.

Sending Mail

Z.1 The Format of the Mail Buffer

Format of the mail being composed.

Z.2 Mail Header Fields

Details of permitted mail header fields.

Z.3 Mail Aliases

Abbreviating and grouping mail addresses.

Z.4 Mail Mode

Special commands for editing mail being composed.

Z.5 Mail Amusements

Distract the NSA's attention; add a fortune to a msg.

Z.6 Mail-Composition Methods

Using alternative mail-composition methods.

Reading Mail with Rmail

AA.1 Basic Concepts of Rmail

Basic concepts of Rmail, and simple use.

AA.2 Scrolling Within a Message

Scrolling through a message.

AA.3 Moving Among Messages

Moving to another message.

AA.4 Deleting Messages

Deleting and expunging messages.

AA.5 Rmail Files and Inboxes

How mail gets into the Rmail file.

AA.6 Multiple Rmail Files

Using multiple Rmail files.

AA.7 Copying Messages Out to Files

Copying message out to files.

AA.8 Labels

Classifying messages by labeling them.

AA.9 Rmail Attributes

Certain standard labels, called attributes.

AA.10 Sending Replies

Sending replies to messages you are viewing.

AA.11 Summaries

Summaries show brief info on many messages.

AA.12 Sorting the Rmail File

Sorting messages in Rmail.

AA.13 Display of Messages

How Rmail displays a message; customization.

AA.15 Editing Within a Message

Editing message text and headers in Rmail.

AA.16 Digest Messages

Extracting the messages from a digest message.

AA.17 Converting an Rmail File to Inbox Format

Converting an Rmail file to mailbox format.

AA.18 Reading Rot13 Messages

Reading messages encoded in the rot13 code.

AA.19 movemail and POP

More details of fetching new mail.

Dired, the Directory Editor

AB.1 Entering Dired

How to invoke Dired.

AB.2 Navigation in the Dired Buffer

How to move in the Dired buffer.

AB.3 Deleting Files with Dired

Deleting files with Dired.

AB.4 Flagging Many Files at Once

Flagging files based on their names.

AB.5 Visiting Files in Dired

Other file operations through Dired.

AB.6 Dired Marks vs. Flags

Flagging for deletion vs marking.

AB.7 Operating on Files

How to copy, rename, print, compress, etc. either one file or several files.

AB.8 Shell Commands in Dired

Running a shell command on the marked files.

AB.9 Transforming File Names in Dired

Using patterns to rename multiple files.

AB.10 File Comparison with Dired

Running `diff' by way of Dired.

AB.11 Subdirectories in Dired

Adding subdirectories to the Dired buffer.

AB.12 Moving Over Subdirectories

Moving across subdirectories, and up and down.

AB.13 Hiding Subdirectories

Making subdirectories visible or invisible.

AB.14 Updating the Dired Buffer

Discarding lines for files of no interest.

AB.15 Dired and find

Using `find' to choose the files for Dired.

The Calendar and the Diary

AC.1 Movement in the Calendar

Moving through the calendar; selecting a date.

AC.2 Scrolling in the Calendar

Bringing earlier or later months onto the screen.

AC.3 Counting Days

How many days are there between two dates?

AC.4 Miscellaneous Calendar Commands

Exiting or recomputing the calendar.

AC.5 LaTeX Calendar

Print a calendar using LaTeX.

AC.6 Holidays

Displaying dates of holidays.

AC.7 Times of Sunrise and Sunset

Displaying local times of sunrise and sunset.

AC.8 Phases of the Moon

Displaying phases of the moon.

AC.9 Conversion To and From Other Calendars

Converting dates to other calendar systems.

AC.10 The Diary

Displaying events from your diary.

AC.11 Appointments

Reminders when it's time to do something.

AC.12 Daylight Savings Time

How to specify when daylight savings time is active.

Movement in the Calendar

AC.1.1 Motion by Standard Lengths of Time

Moving by days, weeks, months, and years.

AC.1.2 Beginning or End of Week, Month or Year

Moving to start/end of weeks, months, and years.

AC.1.3 Specified Dates

Moving to the current date or another specific date.

Conversion To and From Other Calendars

AC.9.1 Supported Calendar Systems

The calendars Emacs understands

(aside from Gregorian).

AC.9.2 Converting To Other Calendars

Converting the selected date to various calendars.

AC.9.3 Converting From Other Calendars

Moving to a date specified in another calendar.

AC.9.4 Converting from the Mayan Calendar

Moving to a date specified in a Mayan calendar.

The Diary

AC.10.1 Commands Displaying Diary Entries

Viewing diary entries and associated calendar dates.

AC.10.2 The Diary File

Entering events in your diary.

AC.10.3 Date Formats

Various ways you can specify dates.

AC.10.4 Commands to Add to the Diary

Commands to create diary entries.

AC.10.5 Special Diary Entries

Anniversaries, blocks of dates, cyclic entries, etc.

GNUS

AC.14.1 Gnus Buffers

The group, summary, and article buffers.

AC.14.2 When Gnus Starts Up

What you should know about starting Gnus.

AC.14.3 Summary of Gnus Commands

A short description of the basic Gnus commands.

Running Shell Commands from Emacs

AC.15.1 Single Shell Commands

How to run one shell command and return.

AC.15.2 Interactive Inferior Shell

Permanent shell taking input via Emacs.

AC.15.3 Shell Mode

Special Emacs commands used with permanent shell.

AC.15.4 Shell Command History

Repeating previous commands in a shell buffer.

AC.15.6 Shell Mode Options

Options for customizing Shell mode.

AC.15.10 Remote Host Shell

Connecting to another computer.

Customization

AD.1 Minor Modes

Each minor mode is one feature you can turn on independently of any others.

AD.2 Variables

Many Emacs commands examine Emacs variables to decide what to do; by setting variables, you can control their functioning.

AD.3 Keyboard Macros

A keyboard macro records a sequence of keystrokes to be replayed with a single command.

AD.4 Customizing Key Bindings

The keymaps say what command each key runs. By changing them, you can "redefine keys".

AD.5 Keyboard Translations

If your keyboard passes an undesired code for a key, you can tell Emacs to substitute another code.

AD.6 The Syntax Table

The syntax table controls how words and expressions are parsed.

AD.7 The Init File, `~/.emacs'

How to write common customizations in the

`.emacs' file.

Variables

AD.2.1 Examining and Setting Variables

Examining or setting one variable's value.

AD.2.2 Easy Customization Interface

Convenient and easy customization of variables.

AD.2.3 Hooks

Hook variables let you specify programs for parts of Emacs to run on particular occasions.

AD.2.4 Local Variables

Per-buffer values of variables.

AD.2.5 Local Variables in Files

How files can specify variable values.

Keyboard Macros

AD.3.1 Basic Use

Defining and running keyboard macros.

AD.3.2 Naming and Saving Keyboard Macros

Giving keyboard macros names; saving them in files.

AD.3.3 Executing Macros with Variations

Making keyboard macros do different things each time.

Customizing Key Bindings

AD.4.1 Keymaps

Generalities. The global keymap.

AD.4.2 Prefix Keymaps

Keymaps for prefix keys.

AD.4.3 Local Keymaps

Major and minor modes have their own keymaps.

AD.4.4 Minibuffer Keymaps

The minibuffer uses its own local keymaps.

AD.4.5 Changing Key Bindings Interactively

How to redefine one key's meaning conveniently.

AD.4.6 Rebinding Keys in Your Init File

Rebinding keys with your init file, `.emacs'.

AD.4.7 Rebinding Function Keys

Rebinding terminal function keys.

AD.4.8 Named ASCII Control Characters

Distinguishing TAB from C-i, and so on.

AD.4.10 Rebinding Mouse Buttons

Rebinding mouse buttons in Emacs.

AD.4.11 Disabling Commands

Disabling a command means confirmation is required before it can be executed. This is done to protect beginners from surprises.

The Init File, `~/.emacs'

AD.7.1 Init File Syntax

Syntax of constants in Emacs Lisp.

AD.7.2 Init File Examples

How to do some things with an init file.

AD.7.3 Terminal-specific Initialization

Each terminal type can have an init file.

AD.7.4 How Emacs Finds Your Init File

How Emacs finds the init file.

Dealing with Emacs Trouble

AD.9.1 If DEL Fails to Delete

What to do if DEL doesn't delete.

AD.9.2 Recursive Editing Levels

`[...]' in mode line around the parentheses.

AD.9.3 Garbage on the Screen

Garbage on the screen.

AD.9.4 Garbage in the Text

Garbage in the text.

AD.9.5 Spontaneous Entry to Incremental Search

Spontaneous entry to incremental search.

AD.9.6 Running out of Memory

How to cope when you run out of memory.

AD.9.8 Emergency Escape

Emergency escape--- What to do if Emacs stops responding.

AD.9.9 Help for Total Frustration

When you are at your wits' end.

Reporting Bugs

AD.10.1 When Is There a Bug

Have you really found a bug?

AD.10.2 Understanding Bug Reporting

How to report a bug effectively.

AD.10.3 Checklist for Bug Reports

Steps to follow for a good bug report.

AD.10.4 Sending Patches for GNU Emacs

How to send a patch for GNU Emacs.

Command Line Options and Arguments

AE.1 Action Arguments

Arguments to visit files, load libraries, and call functions.

AE.2 Initial Options

Arguments that take effect while starting Emacs.

AE.3 Command Argument Example

Examples of using command line arguments.

AE.4 Resuming Emacs with Arguments

Specifying arguments when you resume a running Emacs.

AE.5 Environment Variables

Environment variables that Emacs uses.

AE.6 Specifying the Display Name

Changing the default display and using remote login.

AE.7 Font Specification Options

Choosing a font for text, under X.

AE.8 Window Color Options

Choosing colors, under X.

AE.9 Options for Window Geometry

Start-up window size, under X.

AE.10 Internal and External Borders

Internal and external borders, under X.

AE.11 Frame Titles

Specifying the initial frame's title.

AE.12 Icons

Choosing what sort of icon to use, under X.

AE.13 X Resources

Advanced use of classes and resources, under X.

AE.14 Lucid Menu X Resources

X resources for Lucid menus.

AE.15 LessTif Menu X Resources

X resources for LessTif and Motif menus.

Environment Variables

AE.5.1 General Variables

Environment variables that all versions of Emacs use.

AE.5.2 Miscellaneous Variables

Certain system specific variables.

MS-DOS and Windows 95/98/NT

AH.1 Keyboard and Mouse on MS-DOS

Keyboard and mouse usage on MS-DOS.

AH.2 Display on MS-DOS

Fonts, frames and display size on MS-DOS.

AH.3 File Names on MS-DOS

File-name conventions on MS-DOS.

AH.4 Text Files and Binary Files

Text files on MS-DOS use CRLF to separate lines.

AH.5 Printing and MS-DOS

How to specify the printer on MS-DOS.

AH.7 Subprocesses on MS-DOS

Running subprocesses on MS-DOS.

AH.8 Subprocesses on Windows 9X/ME and Windows NT/2K

Running subprocesses on Windows.

AH.9 Using the System Menu on Windows

Controlling what the ALT key does.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Distribution

GNU Emacs is free software; this means that everyone is free to use it and free to redistribute it on certain conditions. GNU Emacs is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of GNU Emacs that they might get from you. The precise conditions are found in the GNU General Public License that comes with Emacs and also appears following this section.

One way to get a copy of GNU Emacs is from someone else who has it. You need not ask for our permission to do so, or tell any one else; just copy it. If you have access to the Internet, you can get the latest distribution version of GNU Emacs by anonymous FTP; see the file `etc/FTP' in the Emacs distribution for more information.

You may also receive GNU Emacs when you buy a computer. Computer manufacturers are free to distribute copies on the same terms that apply to everyone else. These terms require them to give you the full sources, including whatever changes they may have made, and to permit you to redistribute the GNU Emacs received from them under the usual terms of the General Public License. In other words, the program must be free for you when you get it, not just free for the manufacturer.

You can also order copies of GNU Emacs from the Free Software Foundation on CD-ROM. This is a convenient and reliable way to get a copy; it is also a good way to help fund our work. (The Foundation has always received most of its funds in this way.) An order form is included in the file `etc/ORDERS' in the Emacs distribution, and on our web site in http://www.gnu.org/order/order.html. For further information, write to
Free Software Foundation
59 Temple Place, Suite 330
Boston, MA  02111-1307 USA
USA
The income from distribution fees goes to support the foundation's purpose: the development of new free software, and improvements to our existing programs including GNU Emacs.

If you find GNU Emacs useful, please send a donation to the Free Software Foundation to support our work. Donations to the Free Software Foundation are tax deductible in the US. If you use GNU Emacs at your workplace, please suggest that the company make a donation. If company policy is unsympathetic to the idea of donating to charity, you might instead suggest ordering a CD-ROM from the Foundation occasionally, or subscribing to periodic updates.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program," below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification.") Each licensee is addressed as "you."
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version," you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does.
Copyright (C) 19yy  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 20yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

A. GNU Free Documentation License
Version 1.1, March 2000
Copyright (C) 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
PREAMBLE
The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you."

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque."

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.
COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section entitled "Endorsements." Such a section may not be included in the Modified Version.
N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications." You must delete all sections entitled "Endorsements."
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C)  year  your name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being list their titles, with the
Front-Cover Texts being list, and with the Back-Cover Texts being list.
A copy of the license is included in the section entitled "GNU
Free Documentation License."
If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Introduction

You are reading about GNU Emacs, the GNU incarnation of the advanced, self-documenting, customizable, extensible real-time display editor Emacs. (The `G' in `GNU' is not silent.)

We say that Emacs is a display editor because normally the text being edited is visible on the screen and is updated automatically as you type your commands. See section Display.

We call it a real-time editor because the display is updated very frequently, usually after each character or pair of characters you type. This minimizes the amount of information you must keep in your head as you edit. See section Basic Editing.

We call Emacs advanced because it provides facilities that go beyond simple insertion and deletion: controlling subprocesses; automatic indentation of programs; viewing two or more files at once; editing formatted text; and dealing in terms of characters, words, lines, sentences, paragraphs, and pages, as well as expressions and comments in several different programming languages.

Self-documenting means that at any time you can type a special character, Control-h, to find out what your options are. You can also use it to find out what any command does, or to find all the commands that pertain to a topic. See section G. Help.

Customizable means that you can change the definitions of Emacs commands in little ways. For example, if you use a programming language in which comments start with `<**' and end with `**>', you can tell the Emacs comment manipulation commands to use those strings (see section U.5 Manipulating Comments). Another sort of customization is rearrangement of the command set. For example, if you prefer the four basic cursor motion commands (up, down, left and right) on keys in a diamond pattern on the keyboard, you can rebind the keys that way. See section AD. Customization.

Extensible means that you can go beyond simple customization and write entirely new commands, programs in the Lisp language to be run by Emacs's own Lisp interpreter. Emacs is an "on-line extensible" system, which means that it is divided into many functions that call each other, any of which can be redefined in the middle of an editing session. Almost any part of Emacs can be replaced without making a separate copy of all of Emacs. Most of the editing commands of Emacs are written in Lisp; the few exceptions could have been written in Lisp but are written in C for efficiency. Although only a programmer can write an extension, anybody can use it afterward. If you want to learn Emacs Lisp programming, we recommend the Introduction to Emacs Lisp by Robert J. Chassell, also published by the Free Software Foundation.

When run under the X Window System, Emacs provides its own menus and convenient bindings to mouse buttons. But Emacs can provide many of the benefits of a window system on a text-only terminal. For instance, you can look at or edit several files at once, move text between files, and edit files while running shell commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B. The Organization of the Screen

On a text-only terminal, the Emacs display occupies the whole screen. On the X Window System, Emacs creates its own X windows to use. We use the term frame to mean an entire text-only screen or an entire X window used by Emacs. Emacs uses both kinds of frames in the same way to display your editing. Emacs normally starts out with just one frame, but you can create additional frames if you wish. See section P. Frames and X Windows.

When you start Emacs, the entire frame except for the top and bottom is devoted to the text you are editing. This area is called the window. At the top there is normally a menu bar where you can access a series of menus; then there may be a tool bar, a row of icons that perform editing commands if you click on them. Below this, the window begins. The last line is a special echo area or minibuffer window, where prompts appear and where you can enter information when Emacs asks for it. See below for more information about these special lines.

You can subdivide the large text window horizontally or vertically into multiple text windows, each of which can be used for a different file (see section O. Multiple Windows). In this manual, the word "window" always refers to the subdivisions of a frame within Emacs.

The window that the cursor is in is the selected window, in which editing takes place. Most Emacs commands implicitly apply to the text in the selected window (though mouse commands generally operate on whatever window you click them in, whether selected or not). The other windows display text for reference only, unless/until you select them. If you use multiple frames under the X Window System, then giving the input focus to a particular frame selects a window in that frame.

Each window's last line is a mode line, which describes what is going on in that window. It appears in inverse video, if the terminal supports that; its contents normally begin with `--:-- *scratch*' when Emacs starts. The mode line displays status information such as what buffer is being displayed above it in the window, what major and minor modes are in use, and whether the buffer contains unsaved changes.

B.1 Point

The place in the text where editing commands operate.

B.2 The Echo Area

Short messages appear at the bottom of the screen.

B.3 The Mode Line

Interpreting the mode line.

B.4 The Menu Bar

How to use the menu bar.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B.1 Point

Within Emacs, the terminal's cursor shows the location at which editing commands will take effect. This location is called point. Many Emacs commands move point through the text, so that you can edit at different places in it. You can also place point by clicking mouse button 1.

While the cursor appears to point at a character, you should think of point as between two characters; it points before the character that appears under the cursor. For example, if your text looks like `frob' with the cursor over the `b', then point is between the `o' and the `b'. If you insert the character `!' at that position, the result is `fro!b', with point between the `!' and the `b'. Thus, the cursor remains over the `b', as before.

Sometimes people speak of "the cursor" when they mean "point," or speak of commands that move point as "cursor motion" commands.

Text-only terminals have only one cursor, and when output is in progress it must appear where the output is being displayed. This does not mean that point is moving. It is only that Emacs has no way to show you the location of point except when the terminal is idle.

If you are editing several files in Emacs, each in its own buffer, each buffer has its own point location. A buffer that is not currently displayed remembers where point is in case you display it again later.

When Emacs displays multiple windows, each window has its own point location. On text-only terminals, the cursor shows the location of point in the selected window. On graphical terminals, Emacs shows a cursor in each window; the selected window's cursor is solid, and the other cursors are hollow. Either way, the cursor or cursors tell you which window is selected. If the same buffer appears in more than one window, each window has its own position for point in that buffer, and (when possible) its own cursor.

See section J.13 Displaying the Cursor, for customization options that control display of the cursor or cursors.

The term "point" comes from the character `.', which was the command in TECO (the language in which the original Emacs was written) for accessing the value now called "point."

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B.2 The Echo Area

The line at the bottom of the frame (below the mode line) is the echo area. It is used to display small amounts of text for several purposes.

Echoing means displaying the characters that you type. Outside Emacs, the operating system normally echoes all your input. Emacs handles echoing differently.

Single-character commands do not echo in Emacs, and multi-character commands echo only if you pause while typing them. As soon as you pause for more than a second in the middle of a command, Emacs echoes all the characters of the command so far. This is to prompt you for the rest of the command. Once echoing has started, the rest of the command echoes immediately as you type it. This behavior is designed to give confident users fast response, while giving hesitant users maximum feedback. You can change this behavior by setting a variable (see section J.12 Customization of Display).

If a command cannot be executed, it may display an error message in the echo area. Error messages are accompanied by beeping or by flashing the screen. The error also discards any input you have typed ahead.

Some commands display informative messages in the echo area. These messages look much like error messages, but they are not announced with a beep and do not throw away input. Sometimes the message tells you what the command has done, when this is not obvious from looking at the text being edited. Sometimes the sole purpose of a command is to show you a message giving you specific information--for example, C-x = displays a message describing the character position of point in the text and its current column in the window. Commands that take a long time often display messages ending in `...' while they are working, and add `done' at the end when they are finished.

Echo-area informative messages are saved in an editor buffer named `*Messages*'. (We have not explained buffers yet; see N. Using Multiple Buffers, for more information about them.) If you miss a message that appears briefly on the screen, you can switch to the `*Messages*' buffer to see it again. (Successive progress messages are often collapsed into one in that buffer.)

The size of `*Messages*' is limited to a certain number of lines. The variable message-log-max specifies how many lines. Once the buffer has that many lines, each line added at the end deletes one line from the beginning. See section AD.2 Variables, for how to set variables such as message-log-max.

The echo area is also used to display the minibuffer, a window that is used for reading arguments to commands, such as the name of a file to be edited. When the minibuffer is in use, the echo area begins with a prompt string that usually ends with a colon; also, the cursor appears in that line because it is the selected window. You can always get out of the minibuffer by typing C-g. See section E. The Minibuffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B.3 The Mode Line

Each text window's last line is a mode line, which describes what is going on in that window. When there is only one text window, the mode line appears right above the echo area; it is the next-to-last line in the frame. The mode line starts and ends with dashes. On a text-mode display, the mode line is in inverse video if the terminal supports that; on a graphics display, the mode line has a 3D box appearance to help it stand out.

Normally, the mode line looks like this:
-cs:ch  buf      (major minor)--line--pos------
This gives information about the buffer being displayed in the window: the buffer's name, what major and minor modes are in use, whether the buffer's text has been changed, and how far down the buffer you are currently looking.

ch contains two stars `**' if the text in the buffer has been edited (the buffer is "modified"), or `--' if the buffer has not been edited. For a read-only buffer, it is `%*' if the buffer is modified, and `%%' otherwise.

buf is the name of the window's buffer. In most cases this is the same as the name of a file you are editing. See section N. Using Multiple Buffers.

The buffer displayed in the selected window (the window that the cursor is in) is also Emacs's current buffer, the one that editing takes place in. When we speak of what some command does to "the buffer," we are talking about the current buffer.

line is `L' followed by the current line number of point. This is present when Line Number mode is enabled (which it normally is). You can optionally display the current column number too, by turning on Column Number mode (which is not enabled by default because it is somewhat slower). See section J.10 Optional Mode Line Features.

pos tells you whether there is additional text above the top of the window, or below the bottom. If your buffer is small and it is all visible in the window, pos is `All'. Otherwise, it is `Top' if you are looking at the beginning of the buffer, `Bot' if you are looking at the end of the buffer, or `nn%', where nn is the percentage of the buffer above the top of the window.

major is the name of the major mode in effect in the buffer. At any time, each buffer is in one and only one of the possible major modes. The major modes available include Fundamental mode (the least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many others. See section R. Major Modes, for details of how the modes differ and how to select one.

Some major modes display additional information after the major mode name. For example, Rmail buffers display the current message number and the total number of messages. Compilation buffers and Shell buffers display the status of the subprocess.

minor is a list of some of the minor modes that are turned on at the moment in the window's chosen buffer. For example, `Fill' means that Auto Fill mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means that Overwrite mode is on. See section AD.1 Minor Modes, for more information. `Narrow' means that the buffer being displayed has editing restricted to only a portion of its text. This is not really a minor mode, but is like one. See section AC.22 Narrowing. `Def' means that a keyboard macro is being defined. See section AD.3 Keyboard Macros.

In addition, if Emacs is currently inside a recursive editing level, square brackets (`[...]') appear around the parentheses that surround the modes. If Emacs is in one recursive editing level within another, double square brackets appear, and so on. Since recursive editing levels affect Emacs globally, not just one buffer, the square brackets appear in every window's mode line or not in any of them. See section AC.26 Recursive Editing Levels.

Non-windowing terminals can only show a single Emacs frame at a time (see section P. Frames and X Windows). On such terminals, the mode line displays the name of the selected frame, after ch. The initial frame's name is `F1'.

cs states the coding system used for the file you are editing. A dash indicates the default state of affairs: no code conversion, except for end-of-line translation if the file contents call for that. `=' means no conversion whatsoever. Nontrivial code conversions are represented by various letters--for example, `1' refers to ISO Latin-1. See section Q.7 Coding Systems, for more information. If you are using an input method, a string of the form `i>' is added to the beginning of cs; i identifies the input method. (Some input methods show `+' or `@' instead of `>'.) See section Q.4 Input Methods.

When you are using a character-only terminal (not a window system), cs uses three characters to describe, respectively, the coding system for keyboard input, the coding system for terminal output, and the coding system used for the file you are editing.

When multibyte characters are not enabled, cs does not appear at all. See section Q.2 Enabling Multibyte Characters.

The colon after cs can change to another string in certain circumstances. Emacs uses newline characters to separate lines in the buffer. Some files use different conventions for separating lines: either carriage-return linefeed (the MS-DOS convention) or just carriage-return (the Macintosh convention). If the buffer's file uses carriage-return linefeed, the colon changes to either a backslash (`\') or `(DOS)', depending on the operating system. If the file uses just carriage-return, the colon indicator changes to either a forward slash (`/') or `(Mac)'. On some systems, Emacs displays `(Unix)' instead of the colon even for files that use newline to separate lines.

You can customize the mode line display for each of the end-of-line formats by setting each of the variables eol-mnemonic-unix, eol-mnemonic-dos, eol-mnemonic-mac, and eol-mnemonic-undecided to any string you find appropriate. See section AD.2 Variables, for an explanation of how to set variables.

See section J.10 Optional Mode Line Features, for features that add other handy information to the mode line, such as the current column number of point, the current time, and whether new mail for you has arrived.

The mode line is mouse-sensitive; when you move the mouse across various parts of it, Emacs displays help text to say what a click in that place will do. See section P.6 Mode Line Mouse Commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B.4 The Menu Bar

Each Emacs frame normally has a menu bar at the top which you can use to perform certain common operations. There's no need to list them here, as you can more easily see for yourself.

When you are using a window system, you can use the mouse to choose a command from the menu bar. An arrow pointing right, after the menu item, indicates that the item leads to a subsidiary menu; `...' at the end means that the command will read arguments from the keyboard before it actually does anything.

To view the full command name and documentation for a menu item, type C-h k, and then select the menu bar with the mouse in the usual way (see section G.2 Documentation for a Key).

On text-only terminals with no mouse, you can use the menu bar by typing M-` or F10 (these run the command tmm-menubar). This command enters a mode in which you can select a menu item from the keyboard. A provisional choice appears in the echo area. You can use the left and right arrow keys to move through the menu to different choices. When you have found the choice you want, type RET to select it.

Each menu item also has an assigned letter or digit which designates that item; it is usually the initial of some word in the item's name. This letter or digit is separated from the item name by `=>'. You can type the item's letter or digit to select the item.

Some of the commands in the menu bar have ordinary key bindings as well; if so, the menu lists one equivalent key binding in parentheses after the item itself.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B.5 Kinds of User Input

GNU Emacs uses an extension of the ASCII character set for keyboard input; it also accepts non-character input events including function keys and mouse button actions.

ASCII consists of 128 character codes. Some of these codes are assigned graphic symbols such as `a' and `='; the rest are control characters, such as Control-a (usually written C-a for short). C-a gets its name from the fact that you type it by holding down the CTRL key while pressing a.

Some ASCII control characters have special names, and most terminals have special keys you can type them with: for example, RET, TAB, DEL and ESC. The space character is usually referred to below as SPC, even though strictly speaking it is a graphic character whose graphic happens to be blank. Some keyboards have a key labeled "linefeed" which is an alias for C-j.

Emacs extends the ASCII character set with thousands more printing characters (see section Q. International Character Set Support), additional control characters, and a few more modifiers that can be combined with any character.

On ASCII terminals, there are only 32 possible control characters. These are the control variants of letters and `@[]\^_'. In addition, the shift key is meaningless with control characters: C-a and C-A are the same character, and Emacs cannot distinguish them.

But the Emacs character set has room for control variants of all printing characters, and for distinguishing between C-a and C-A. The X Window System makes it possible to enter all these characters. For example, C-- (that's Control-Minus) and C-5 are meaningful Emacs commands under X.

Another Emacs character-set extension is additional modifier bits. Only one modifier bit is commonly used; it is called Meta. Every character has a Meta variant; examples include Meta-a (normally written M-a, for short), M-A (not the same character as M-a, but those two characters normally have the same meaning in Emacs), M-RET, and M-C-a. For reasons of tradition, we usually write C-M-a rather than M-C-a; logically speaking, the order in which the modifier keys CTRL and META are mentioned does not matter.

Some terminals have a META key, and allow you to type Meta characters by holding this key down. Thus, Meta-a is typed by holding down META and pressing a. The META key works much like the SHIFT key. Such a key is not always labeled META, however, as this function is often a special option for a key with some other primary purpose. Sometimes it is labeled ALT or EDIT; on a Sun keyboard, it may have a diamond on it.

If there is no META key, you can still type Meta characters using two-character sequences starting with ESC. Thus, you can enter M-a by typing ESC a. You can enter C-M-a by typing ESC C-a. ESC is allowed on terminals with META keys, too, in case you have formed a habit of using it. The X Window System provides several other modifier keys that can be applied to any input character. These are called SUPER, HYPER and ALT. We write `s-', `H-' and `A-' to say that a character uses these modifiers. Thus, s-H-C-x is short for Super-Hyper-Control-x. Not all X terminals actually provide keys for these modifier flags--in fact, many terminals have a key labeled ALT which is really a META key. The standard key bindings of Emacs do not include any characters with these modifiers. But you can assign them meanings of your own by customizing Emacs.

Keyboard input includes keyboard keys that are not characters at all: for example function keys and arrow keys. Mouse buttons are also outside the gamut of characters. You can modify these events with the modifier keys CTRL, META, SUPER, HYPER and ALT, just like keyboard characters.

Input characters and non-character inputs are collectively called input events. See section `Input Events' in The Emacs Lisp Reference Manual, for more information. If you are not doing Lisp programming, but simply want to redefine the meaning of some characters or non-character events, see AD. Customization.

ASCII terminals cannot really send anything to the computer except ASCII characters. These terminals use a sequence of characters to represent each function key. But that is invisible to the Emacs user, because the keyboard input routines recognize these special sequences and convert them to function key events before any other part of Emacs gets to see them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B.6 Keys

A key sequence (key, for short) is a sequence of input events that are meaningful as a unit--as "a single command." Some Emacs command sequences are just one character or one event; for example, just C-f is enough to move forward one character in the buffer. But Emacs also has commands that take two or more events to invoke.

If a sequence of events is enough to invoke a command, it is a complete key. Examples of complete keys include C-a, X, RET, NEXT (a function key), DOWN (an arrow key), C-x C-f, and C-x 4 C-f. If it isn't long enough to be complete, we call it a prefix key. The above examples show that C-x and C-x 4 are prefix keys. Every key sequence is either a complete key or a prefix key.

Most single characters constitute complete keys in the standard Emacs command bindings. A few of them are prefix keys. A prefix key combines with the following input event to make a longer key sequence, which may itself be complete or a prefix. For example, C-x is a prefix key, so C-x and the next input event combine to make a two-event key sequence. Most of these key sequences are complete keys, including C-x C-f and C-x b. A few, such as C-x 4 and C-x r, are themselves prefix keys that lead to three-event key sequences. There's no limit to the length of a key sequence, but in practice people rarely use sequences longer than four events.

By contrast, you can't add more events onto a complete key. For example, the two-event sequence C-f C-k is not a key, because the C-f is a complete key in itself. It's impossible to give C-f C-k an independent meaning as a command. C-f C-k is two key sequences, not one.

All told, the prefix keys in Emacs are C-c, C-h, C-x, C-x RET, C-x @, C-x a, C-x n, C-x r, C-x v, C-x 4, C-x 5, C-x 6, ESC, and M-g. But this list is not cast in concrete; it is just a matter of Emacs's standard key bindings. If you customize Emacs, you can make new prefix keys, or eliminate these. See section AD.4 Customizing Key Bindings.

If you do make or eliminate prefix keys, that changes the set of possible key sequences. For example, if you redefine C-f as a prefix, C-f C-k automatically becomes a key (complete, unless you define that too as a prefix). Conversely, if you remove the prefix definition of C-x 4, then C-x 4 f (or C-x 4 anything) is no longer a key.

Typing the help character (C-h or F1) after a prefix key displays a list of the commands starting with that prefix. There are a few prefix keys for which C-h does not work--for historical reasons, they have other meanings for C-h which are not easy to change. But F1 should work for all prefix keys.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B.7 Keys and Commands

This manual is full of passages that tell you what particular keys do. But Emacs does not assign meanings to keys directly. Instead, Emacs assigns meanings to named commands, and then gives keys their meanings by binding them to commands.

Every command has a name chosen by a programmer. The name is usually made of a few English words separated by dashes; for example, next-line or forward-word. A command also has a function definition which is a Lisp program; this is what makes the command do what it does. In Emacs Lisp, a command is actually a special kind of Lisp function; one which specifies how to read arguments for it and call it interactively. For more information on commands and functions, see section `What Is a Function' in The Emacs Lisp Reference Manual. (The definition we use in this manual is simplified slightly.)

The bindings between keys and commands are recorded in various tables called keymaps. See section AD.4.1 Keymaps.

When we say that "C-n moves down vertically one line" we are glossing over a distinction that is irrelevant in ordinary use but is vital in understanding how to customize Emacs. It is the command next-line that is programmed to move down vertically. C-n has this effect because it is bound to that command. If you rebind C-n to the command forward-word then C-n will move forward by words instead. Rebinding keys is a common method of customization.

In the rest of this manual, we usually ignore this subtlety to keep things simple. To give the information needed for customization, we state the name of the command which really does the work in parentheses after mentioning the key that runs it. For example, we will say that "The command C-n (next-line) moves point vertically down," meaning that next-line is a command that moves vertically down, and C-n is a key that is normally bound to it.

While we are on the subject of information for customization only, it's a good time to tell you about variables. Often the description of a command will say, "To change this, set the variable mumble-foo." A variable is a name used to remember a value. Most of the variables documented in this manual exist just to facilitate customization: some command or other part of Emacs examines the variable and behaves differently according to the value that you set. Until you are interested in customizing, you can ignore the information about variables. When you are ready to be interested, read the basic information on variables, and then the information on individual variables will make sense. See section AD.2 Variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

B.8 Character Set for Text

Text in Emacs buffers is a sequence of 8-bit bytes. Each byte can hold a single ASCII character. Both ASCII control characters (octal codes 000 through 037, and 0177) and ASCII printing characters (codes 040 through 0176) are allowed; however, non-ASCII control characters cannot appear in a buffer. The other modifier flags used in keyboard input, such as Meta, are not allowed in buffers either.

Some ASCII control characters serve special purposes in text, and have special names. For example, the newline character (octal code 012) is used in the buffer to end a line, and the tab character (octal code 011) is used for indenting to the next tab stop column (normally every 8 columns). See section J.11 How Text Is Displayed.

Non-ASCII printing characters can also appear in buffers. When multibyte characters are enabled, you can use any of the non-ASCII printing characters that Emacs supports. They have character codes starting at 256, octal 0400, and each one is represented as a sequence of two or more bytes. See section Q. International Character Set Support. Single-byte characters with codes 128 through 255 can also appear in multibyte buffers.

If you disable multibyte characters, then you can use only one alphabet of non-ASCII characters, but they all fit in one byte. They use codes 0200 through 0377. See section Q.13 Single-byte Character Set Support.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

C. Entering and Exiting Emacs

The usual way to invoke Emacs is with the shell command emacs. Emacs clears the screen and then displays an initial help message and copyright notice. Some operating systems discard all type-ahead when Emacs starts up; they give Emacs no way to prevent this. Therefore, it is advisable to wait until Emacs clears the screen before typing your first editing command.

If you run Emacs from a shell window under the X Window System, run it in the background with emacs&. This way, Emacs does not tie up the shell window, so you can use that to run other shell commands while Emacs operates its own X windows. You can begin typing Emacs commands as soon as you direct your keyboard input to the Emacs frame.

When Emacs starts up, it creates a buffer named `*scratch*'. That's the buffer you start out in. The `*scratch*' buffer uses Lisp Interaction mode; you can use it to type Lisp expressions and evaluate them, or you can ignore that capability and simply doodle. (You can specify a different major mode for this buffer by setting the variable initial-major-mode in your init file. See section AD.7 The Init File, `~/.emacs'.)

It is possible to specify files to be visited, Lisp files to be loaded, and functions to be called, by giving Emacs arguments in the shell command line. See section AE. Command Line Arguments. But we don't recommend doing this. The feature exists mainly for compatibility with other editors.

Many other editors are designed to be started afresh each time you want to edit. You edit one file and then exit the editor. The next time you want to edit either another file or the same one, you must run the editor again. With these editors, it makes sense to use a command-line argument to say which file to edit.

But starting a new Emacs each time you want to edit a different file does not make sense. For one thing, this would be annoyingly slow. For another, this would fail to take advantage of Emacs's ability to visit more than one file in a single editing session. And it would lose the other accumulated context, such as the kill ring, registers, undo history, and mark ring.

The recommended way to use GNU Emacs is to start it only once, just after you log in, and do all your editing in the same Emacs session. Each time you want to edit a different file, you visit it with the existing Emacs, which eventually comes to have many files in it ready for editing. Usually you do not kill the Emacs until you are about to log out. See section M. File Handling, for more information on visiting more than one file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

C.1 Exiting Emacs

There are two commands for exiting Emacs because there are two kinds of exiting: suspending Emacs and killing Emacs.

Suspending means stopping Emacs temporarily and returning control to its parent process (usually a shell), allowing you to resume editing later in the same Emacs job, with the same buffers, same kill ring, same undo history, and so on. This is the usual way to exit.

Killing Emacs means destroying the Emacs job. You can run Emacs again later, but you will get a fresh Emacs; there is no way to resume the same editing session after it has been killed.

C-z
Suspend Emacs (suspend-emacs) or iconify a frame (iconify-or-deiconify-frame).
C-x C-c
Kill Emacs (save-buffers-kill-emacs).
To suspend Emacs, type C-z (suspend-emacs). This takes you back to the shell from which you invoked Emacs. You can resume Emacs with the shell command %emacs in most common shells.

On systems that do not support suspending programs, C-z starts an inferior shell that communicates directly with the terminal. Emacs waits until you exit the subshell. (The way to do that is probably with C-d or exit, but it depends on which shell you use.) The only way on these systems to get back to the shell from which Emacs was run (to log out, for example) is to kill Emacs.

Suspending also fails if you run Emacs under a shell that doesn't support suspending programs, even if the system itself does support it. In such a case, you can set the variable cannot-suspend to a non-nil value to force C-z to start an inferior shell. (One might also describe Emacs's parent shell as "inferior" for failing to support job control properly, but that is a matter of taste.)

When Emacs communicates directly with an X server and creates its own dedicated X windows, C-z has a different meaning. Suspending an application that uses its own X windows is not meaningful or useful. Instead, C-z runs the command iconify-or-deiconify-frame, which temporarily iconifies (or "minimizes") the selected Emacs frame (see section P. Frames and X Windows). Then you can use the window manager to get back to a shell window.

To exit and kill Emacs, type C-x C-c (save-buffers-kill-emacs). A two-character key is used for this to make it harder to type by accident. This command first offers to save any modified file-visiting buffers. If you do not save them all, it asks for reconfirmation with yes before killing Emacs, since any changes not saved will be lost forever. Also, if any subprocesses are still running, C-x C-c asks for confirmation about them, since killing Emacs will also kill the subprocesses.

If the value of the variable confirm-kill-emacs is non-nil, C-x C-c assumes that its value is a predicate function, and calls that function. If the result is non-nil, the session is killed, otherwise Emacs continues to run. One convenient function to use as the value of confirm-kill-emacs is the function yes-or-no-p. The default value of confirm-kill-emacs is nil.

There is no way to resume an Emacs session once you have killed it. You can, however, arrange for Emacs to record certain session information when you kill it, such as which files are visited, so that the next time you start Emacs it will try to visit the same files and so on. See section AC.25 Saving Emacs Sessions.

The operating system usually listens for certain special characters whose meaning is to kill or suspend the program you are running. This operating system feature is turned off while you are in Emacs. The meanings of C-z and C-x C-c as keys in Emacs were inspired by the use of C-z and C-c on several operating systems as the characters for stopping or killing a program, but that is their only relationship with the operating system. You can customize these keys to run any commands of your choice (see section AD.4.1 Keymaps).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D. Basic Editing Commands

We now give the basics of how to enter text, make corrections, and save the text in a file. If this material is new to you, you might learn it more easily by running the Emacs learn-by-doing tutorial. To use the tutorial, run Emacs and type Control-h t (help-with-tutorial).

To clear the screen and redisplay, type C-l (recenter).

D.1 Inserting Text

Inserting text by simply typing it.

D.2 Changing the Location of Point

How to move the cursor to the place where you want to change something.

D.3 Erasing Text

Deleting and killing text.

D.4 Undoing Changes

Undoing recent changes in the text.

D.5 Files

Visiting, creating, and saving files.

D.6 Help

Asking what a character does.

D.7 Blank Lines

Commands to make or delete blank lines.

D.8 Continuation Lines

Lines too wide for the screen.

D.9 Cursor Position Information

What page, line, row, or column is point on?

D.10 Numeric Arguments

Numeric arguments for repeating a command.

D.11 Repeating a Command

A short-cut for repeating the previous command.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.1 Inserting Text

To insert printing characters into the text you are editing, just type them. This inserts the characters you type into the buffer at the cursor (that is, at point; see section B.1 Point). The cursor moves forward, and any text after the cursor moves forward too. If the text in the buffer is `FOOBAR', with the cursor before the `B', then if you type XX, you get `FOOXXBAR', with the cursor still before the `B'.

To delete text you have just inserted, use the large key labeled DEL, BACKSPACE or DELETE which is a short distance above the RET or ENTER key. This is the key you normally use, outside Emacs, for erasing the last character that you typed. Regardless of the label on that key, Emacs thinks of it as DEL, and that's what we call it in this manual.

The DEL key deletes the character before the cursor. As a consequence, the cursor and all the characters after it move backwards. If you type a printing character and then type DEL, they cancel out.

On most computers, Emacs recognizes automatically which key ought to be DEL, and sets it up that way. But in some cases, especially with text-only terminals, you will need to tell Emacs which key to use for that purpose. If the large key not far above the RET or ENTER key doesn't delete backwards, you need to do this. See section AD.9.1 If DEL Fails to Delete, for an explanation of how.

Most PC keyboards have both a BACKSPACE key a short ways above RET or ENTER, and a DELETE key elsewhere. On these keyboards, Emacs supports when possible the usual convention that the BACKSPACE key deletes backwards (it is DEL), while the DELETE key deletes "forwards," deleting the character after point, the one underneath the cursor, like C-d (see below).

To end a line and start typing a new one, type RET. This inserts a newline character in the buffer. If point is in the middle of a line, RET splits the line. Typing DEL when the cursor is at the beginning of a line deletes the preceding newline, thus joining the line with the preceding line.

Emacs can split lines automatically when they become too long, if you turn on a special minor mode called Auto Fill mode. See section T.5 Filling Text, for how to use Auto Fill mode.

If you prefer to have text characters replace (overwrite) existing text rather than shove it to the right, you can enable Overwrite mode, a minor mode. See section AD.1 Minor Modes.

Direct insertion works for printing characters and SPC, but other characters act as editing commands and do not insert themselves. If you need to insert a control character or a character whose code is above 200 octal, you must quote it by typing the character Control-q (quoted-insert) first. (This character's name is normally written C-q for short.) There are two ways to use C-q:

C-q followed by any non-graphic character (even C-g) inserts that character.

C-q followed by a sequence of octal digits inserts the character with the specified octal character code. You can use any number of octal digits; any non-digit terminates the sequence. If the terminating character is RET, it serves only to terminate the sequence. Any other non-digit terminates the sequence and then acts as normal input--thus, C-q 1 0 1 B inserts `AB'.
The use of octal sequences is disabled in ordinary non-binary Overwrite mode, to give you a convenient way to insert a digit instead of overwriting with it.

When multibyte characters are enabled, if you specify a code in the range 0200 through 0377 octal, C-q assumes that you intend to use some ISO 8859-n character set, and converts the specified code to the corresponding Emacs character code. See section Q.2 Enabling Multibyte Characters. You select which of the ISO 8859 character sets to use through your choice of language environment (see section Q.3 Language Environments).

To use decimal or hexadecimal instead of octal, set the variable read-quoted-char-radix to 10 or 16. If the radix is greater than 10, some letters starting with a serve as part of a character code, just like digits.

A numeric argument to C-q specifies how many copies of the quoted character should be inserted (see section D.10 Numeric Arguments).

Customization information: DEL in most modes runs the command delete-backward-char; RET runs the command newline, and self-inserting printing characters run the command self-insert, which inserts whatever character was typed to invoke it. Some major modes rebind DEL to other commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.2 Changing the Location of Point

To do more than insert characters, you have to know how to move point (see section B.1 Point). The simplest way to do this is with arrow keys, or by clicking the left mouse button where you want to move to.

There are also control and meta characters for cursor motion. Some are equivalent to the arrow keys (these date back to the days before terminals had arrow keys, and are usable on terminals which don't have them). Others do more sophisticated things.

C-a
Move to the beginning of the line (beginning-of-line).
C-e
Move to the end of the line (end-of-line).
C-f
Move forward one character (forward-char). The right-arrow key does the same thing.
C-b
Move backward one character (backward-char). The left-arrow key has the same effect.
M-f
Move forward one word (forward-word).
M-b
Move backward one word (backward-word).
C-n
Move down one line, vertically (next-line). This command attempts to keep the horizontal position unchanged, so if you start in the middle of one line, you end in the middle of the next. The down-arrow key does the same thing.
C-p
Move up one line, vertically (previous-line). The up-arrow key has the same effect.
M-r
Move point to left margin, vertically centered in the window (move-to-window-line). Text does not move on the screen.
A numeric argument says which screen line to place point on. It counts screen lines down from the top of the window (zero for the top line). A negative argument counts lines from the bottom (-1 for the bottom line).
M-<
Move to the top of the buffer (beginning-of-buffer). With numeric argument n, move to n/10 of the way from the top. See section D.10 Numeric Arguments, for more information on numeric arguments.
M->
Move to the end of the buffer (end-of-buffer).
C-v
Scroll the display one screen forward, and move point if necessary to put it on the screen (scroll-up). This doesn't always move point, but it is commonly used to do so. If your keyboard has a PAGEDOWN key, it does the same thing.
Scrolling commands are further described in J.6 Scrolling.
M-v
Scroll one screen backward, and move point if necessary to put it on the screen (scroll-down). This doesn't always move point, but it is commonly used to do so. The PAGEUP key has the same effect.
M-x goto-char
Read a number n and move point to buffer position n. Position 1 is the beginning of the buffer.
M-x goto-line
Read a number n and move point to line number n. Line 1 is the beginning of the buffer.
C-x C-n
Use the current column of point as the semipermanent goal column for C-n and C-p (set-goal-column). Henceforth, those commands always move to this column in each line moved into, or as close as possible given the contents of the line. This goal column remains in effect until canceled.
C-u C-x C-n
Cancel the goal column. Henceforth, C-n and C-p once again try to stick to a fixed horizontal position, as usual.
If you set the variable track-eol to a non-nil value, then C-n and C-p, when starting at the end of the line, move to the end of another line. Normally, track-eol is nil. See section AD.2 Variables, for how to set variables such as track-eol.

C-n normally gets an error when you use it on the last line of the buffer (just as C-p gets an error on the first line). But if you set the variable next-line-add-newlines to a non-nil value, C-n on the last line of a buffer creates an additional line at the end and moves down onto it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.3 Erasing Text

DEL
Delete the character before point (delete-backward-char).
C-d
Delete the character after point (delete-char).
DELETE

BACKSPACE
One of these keys, whichever is the large key above the RET or ENTER key, deletes the character before point, like DEL. If that is BACKSPACE, and your keyboard also has DELETE, then DELETE deletes forwards, like C-d.
C-k
Kill to the end of the line (kill-line).
M-d
Kill forward to the end of the next word (kill-word).
M-DEL
Kill back to the beginning of the previous word (backward-kill-word).
You already know about the DEL key which deletes the character before point (that is, before the cursor). Another key, Control-d (C-d for short), deletes the character after point (that is, the character that the cursor is on). This shifts the rest of the text on the line to the left. If you type C-d at the end of a line, it joins together that line and the next line.

To erase a larger amount of text, use the C-k key, which kills a line at a time. If you type C-k at the beginning or middle of a line, it kills all the text up to the end of the line. If you type C-k at the end of a line, it joins that line and the next line.

See section H.7 Deletion and Killing, for more flexible ways of killing text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.4 Undoing Changes

You can undo all the recent changes in the buffer text, up to a certain point. Each buffer records changes individually, and the undo command always applies to the current buffer. Usually each editing command makes a separate entry in the undo records, but some commands such as query-replace make many entries, and very simple commands such as self-inserting characters are often grouped to make undoing less tedious.

C-x u
Undo one batch of changes--usually, one command worth (undo).
C-_
The same.
C-u C-x u
Undo one batch of changes in the region.
The command C-x u or C-_ is how you undo. The first time you give this command, it undoes the last change. Point moves back to where it was before the command that made the change.

Consecutive repetitions of C-_ or C-x u undo earlier and earlier changes, back to the limit of the undo information available. If all recorded changes have already been undone, the undo command displays an error message and does nothing.

Any command other than an undo command breaks the sequence of undo commands. Starting from that moment, the previous undo commands become ordinary changes that you can undo. Thus, to redo changes you have undone, type C-f or any other command that will harmlessly break the sequence of undoing, then type more undo commands.

Ordinary undo applies to all changes made in the current buffer. You can also perform selective undo, limited to the current region. To do this, specify the region you want, then run the undo command with a prefix argument (the value does not matter): C-u C-x u or C-u C-_. This undoes the most recent change in the region. To undo further changes in the same region, repeat the undo command (no prefix argument is needed). In Transient Mark mode, any use of undo when there is an active region performs selective undo; you do not need a prefix argument.

If you notice that a buffer has been modified accidentally, the easiest way to recover is to type C-_ repeatedly until the stars disappear from the front of the mode line. At this time, all the modifications you made have been canceled. Whenever an undo command makes the stars disappear from the mode line, it means that the buffer contents are the same as they were when the file was last read in or saved.

If you do not remember whether you changed the buffer deliberately, type C-_ once. When you see the last change you made undone, you will see whether it was an intentional change. If it was an accident, leave it undone. If it was deliberate, redo the change as described above.

Not all buffers record undo information. Buffers whose names start with spaces don't; these buffers are used internally by Emacs and its extensions to hold text that users don't normally look at or edit.

You cannot undo mere cursor motion; only changes in the buffer contents save undo information. However, some cursor motion commands set the mark, so if you use these commands from time to time, you can move back to the neighborhoods you have moved through by popping the mark ring (see section H.5 The Mark Ring).

When the undo information for a buffer becomes too large, Emacs discards the oldest undo information from time to time (during garbage collection). You can specify how much undo information to keep by setting two variables: undo-limit and undo-strong-limit. Their values are expressed in units of bytes of space.

The variable undo-limit sets a soft limit: Emacs keeps undo data for enough commands to reach this size, and perhaps exceed it, but does not keep data for any earlier commands beyond that. Its default value is 20000. The variable undo-strong-limit sets a stricter limit: the command which pushes the size past this amount is itself forgotten. Its default value is 30000.

Regardless of the values of those variables, the most recent change is never discarded, so there is no danger that garbage collection occurring right after an unintentional large change might prevent you from undoing it.

The reason the undo command has two keys, C-x u and C-_, set up to run it is that it is worthy of a single-character key, but on some keyboards it is not obvious how to type C-_. C-x u is an alternative you can type straightforwardly on any terminal.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.5 Files

The commands described above are sufficient for creating and altering text in an Emacs buffer; the more advanced Emacs commands just make things easier. But to keep any text permanently you must put it in a file. Files are named units of text which are stored by the operating system for you to retrieve later by name. To look at or use the contents of a file in any way, including editing the file with Emacs, you must specify the file name.

Consider a file named `/usr/rms/foo.c'. In Emacs, to begin editing this file, type
C-x C-f /usr/rms/foo.c RET
Here the file name is given as an argument to the command C-x C-f (find-file). That command uses the minibuffer to read the argument, and you type RET to terminate the argument (see section E. The Minibuffer).

Emacs obeys the command by visiting the file: creating a buffer, copying the contents of the file into the buffer, and then displaying the buffer for you to edit. If you alter the text, you can save the new text in the file by typing C-x C-s (save-buffer). This makes the changes permanent by copying the altered buffer contents back into the file `/usr/rms/foo.c'. Until you save, the changes exist only inside Emacs, and the file `foo.c' is unaltered.

To create a file, just visit the file with C-x C-f as if it already existed. This creates an empty buffer in which you can insert the text you want to put in the file. The file is actually created when you save this buffer with C-x C-s.

Of course, there is a lot more to learn about using files. See section M. File Handling.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.6 Help

If you forget what a key does, you can find out with the Help character, which is C-h (or F1, which is an alias for C-h). Type C-h k followed by the key you want to know about; for example, C-h k C-n tells you all about what C-n does. C-h is a prefix key; C-h k is just one of its subcommands (the command describe-key). The other subcommands of C-h provide different kinds of help. Type C-h twice to get a description of all the help facilities. See section G. Help.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.7 Blank Lines

Here are special commands and techniques for putting in and taking out blank lines.

C-o
Insert one or more blank lines after the cursor (open-line).
C-x C-o
Delete all but one of many consecutive blank lines (delete-blank-lines).
When you want to insert a new line of text before an existing line, you can do it by typing the new line of text, followed by RET. However, it may be easier to see what you are doing if you first make a blank line and then insert the desired text into it. This is easy to do using the key C-o (open-line), which inserts a newline after point but leaves point in front of the newline. After C-o, type the text for the new line. C-o F O O has the same effect as F O O RET, except for the final location of point.

You can make several blank lines by typing C-o several times, or by giving it a numeric argument to tell it how many blank lines to make. See section D.10 Numeric Arguments, for how. If you have a fill prefix, then C-o command inserts the fill prefix on the new line, when you use it at the beginning of a line. See section T.5.4 The Fill Prefix.

The easy way to get rid of extra blank lines is with the command C-x C-o (delete-blank-lines). C-x C-o in a run of several blank lines deletes all but one of them. C-x C-o on a solitary blank line deletes that blank line. When point is on a nonblank line, C-x C-o deletes any blank lines following that nonblank line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.8 Continuation Lines

If you add too many characters to one line without breaking it with RET, the line grows to occupy two (or more) lines on the screen. On graphical displays, Emacs indicates line wrapping with small bent arrows in the fringes to the left and right of the window. On text-only terminals, Emacs displays a `\' character at the right margin of a screen line if it is not the last in its text line. This `\' character says that the following screen line is not really a distinct line in the text, just a continuation of a line too long to fit the screen. Continuation is also called line wrapping.

When line wrapping occurs before a character that is wider than one column, some columns at the end of the previous screen line may be "empty." In this case, Emacs displays additional `\' characters in the "empty" columns, just before the `\' character that indicates continuation.

Sometimes it is nice to have Emacs insert newlines automatically when a line gets too long. Continuation on the screen does not do that. Use Auto Fill mode (see section T.5 Filling Text) if that's what you want.

As an alternative to continuation, Emacs can display long lines by truncation. This means that all the characters that do not fit in the width of the screen or window do not appear at all. They remain in the buffer, temporarily invisible. On terminals, `$' in the last column informs you that the line has been truncated on the display. On window systems, a small straight arrow in the fringe to the right of the window indicates a truncated line.

Truncation instead of continuation happens whenever horizontal scrolling is in use, and optionally in all side-by-side windows (see section O. Multiple Windows). You can enable or disable truncation for a particular buffer with the command M-x toggle-truncate-lines.

See section J.12 Customization of Display, for additional variables that affect how text is displayed.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.9 Cursor Position Information

Here are commands to get information about the size and position of parts of the buffer, and to count lines.

M-x what-page
Display the page number of point, and the line number within the page.
M-x what-line
Display the line number of point in the buffer.
M-x line-number-mode

M-x column-number-mode
Toggle automatic display of current line number or column number. See section J.10 Optional Mode Line Features.
M-=
Display the number of lines in the current region (count-lines-region). See section H. The Mark and the Region, for information about the region.
C-x =
Display the character code of character after point, character position of point, and column of point (what-cursor-position).
M-x hl-line-mode
Enable or disable highlighting of the current line. See section J.13 Displaying the Cursor.
There are two commands for working with line numbers. M-x what-line computes the current line number and displays it in the echo area. To go to a given line by number, use M-x goto-line; it prompts you for the number. These line numbers count from one at the beginning of the buffer.

You can also see the current line number in the mode line; see B.3 The Mode Line. If you narrow the buffer, then the line number in the mode line is relative to the accessible portion (see section AC.22 Narrowing). By contrast, what-line shows both the line number relative to the narrowed region and the line number relative to the whole buffer.

M-x what-page counts pages from the beginning of the file, and counts lines within the page, showing both numbers in the echo area. See section T.4 Pages.

While on this subject, we might as well mention M-= (count-lines-region), which displays the number of lines in the region (see section H. The Mark and the Region). See section T.4 Pages, for the command C-x l which counts the lines in the current page.

The command C-x = (what-cursor-position) can be used to find out the column that the cursor is in, and other miscellaneous information about point. It displays a line in the echo area that looks like this:
Char: c (0143, 99, 0x63)  point=21044 of 26883(78%)  column 53
(In fact, this is the output produced when point is before the `column' in the example.)

The four values after `Char:' describe the character that follows point, first by showing it and then by giving its character code in octal, decimal and hex. For a non-ASCII multibyte character, these are followed by `ext' and the character's representation, in hex, in the buffer's coding system, if that coding system encodes the character safely and with a single byte (see section Q.7 Coding Systems). If the character's encoding is longer than one byte, Emacs shows `ext ...'.

`point=' is followed by the position of point expressed as a character count. The front of the buffer counts as position 1, one character later as 2, and so on. The next, larger, number is the total number of characters in the buffer. Afterward in parentheses comes the position expressed as a percentage of the total size.

`column' is followed by the horizontal position of point, in columns from the left edge of the window.

If the buffer has been narrowed, making some of the text at the beginning and the end temporarily inaccessible, C-x = displays additional text describing the currently accessible range. For example, it might display this:
Char: C (0103, 67, 0x43)  point=252 of 889(28%) <231 - 599>  column 0
where the two extra numbers give the smallest and largest character position that point is allowed to assume. The characters between those two positions are the accessible ones. See section AC.22 Narrowing.

If point is at the end of the buffer (or the end of the accessible part), the C-x = output does not describe a character after point. The output might look like this:
point=26957 of 26956(100%)  column 0
C-u C-x = displays additional information about a character, in place of the buffer coordinates and column: the character set name and the codes that identify the character within that character set; ASCII characters are identified as belonging to the ASCII character set. In addition, the full character encoding, even if it takes more than a single byte, is shown after `ext'. Here's an example for a Latin-1 character A with a grave accent in a buffer whose coding system is iso-2022-7bit(1):
Char: À (04300, 2240, 0x8c0, ext ESC , A @) (latin-iso8859-1 64)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.10 Numeric Arguments

In mathematics and computer usage, the word argument means "data provided to a function or operation." You can give any Emacs command a numeric argument (also called a prefix argument). Some commands interpret the argument as a repetition count. For example, C-f with an argument of ten moves forward ten characters instead of one. With these commands, no argument is equivalent to an argument of one. Negative arguments tell most such commands to move or act in the opposite direction.

If your terminal keyboard has a META key, the easiest way to specify a numeric argument is to type digits and/or a minus sign while holding down the META key. For example,
M-5 C-n
would move down five lines. The characters Meta-1, Meta-2, and so on, as well as Meta--, do this because they are keys bound to commands (digit-argument and negative-argument) that are defined to contribute to an argument for the next command. Meta-- without digits normally means -1. Digits and - modified with Control, or Control and Meta, also specify numeric arguments.

Another way of specifying an argument is to use the C-u (universal-argument) command followed by the digits of the argument. With C-u, you can type the argument digits without holding down modifier keys; C-u works on all terminals. To type a negative argument, type a minus sign after C-u. Just a minus sign without digits normally means -1.

C-u followed by a character which is neither a digit nor a minus sign has the special meaning of "multiply by four." It multiplies the argument for the next command by four. C-u twice multiplies it by sixteen. Thus, C-u C-u C-f moves forward sixteen characters. This is a good way to move forward "fast," since it moves about 1/5 of a line in the usual size screen. Other useful combinations are C-u C-n, C-u C-u C-n (move down a good fraction of a screen), C-u C-u C-o (make "a lot" of blank lines), and C-u C-k (kill four lines).

Some commands care only about whether there is an argument, and not about its value. For example, the command M-q (fill-paragraph) with no argument fills text; with an argument, it justifies the text as well. (See section T.5 Filling Text, for more information on M-q.) Plain C-u is a handy way of providing an argument for such commands.

Some commands use the value of the argument as a repeat count, but do something peculiar when there is no argument. For example, the command C-k (kill-line) with argument n kills n lines, including their terminating newlines. But C-k with no argument is special: it kills the text up to the next newline, or, if point is right at the end of the line, it kills the newline itself. Thus, two C-k commands with no arguments can kill a nonblank line, just like C-k with an argument of one. (See section H.7 Deletion and Killing, for more information on C-k.)

A few commands treat a plain C-u differently from an ordinary argument. A few others may treat an argument of just a minus sign differently from an argument of -1. These unusual cases are described when they come up; they are always for reasons of convenience of use of the individual command.

You can use a numeric argument to insert multiple copies of a character. This is straightforward unless the character is a digit; for example, C-u 6 4 a inserts 64 copies of the character `a'. But this does not work for inserting digits; C-u 6 4 1 specifies an argument of 641, rather than inserting anything. To separate the digit to insert from the argument, type another C-u; for example, C-u 6 4 C-u 1 does insert 64 copies of the character `1'.

We use the term "prefix argument" as well as "numeric argument" to emphasize that you type the argument before the command, and to distinguish these arguments from minibuffer arguments that come after the command.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

D.11 Repeating a Command

Many simple commands, such as those invoked with a single key or with M-x command-name RET, can be repeated by invoking them with a numeric argument that serves as a repeat count (see section D.10 Numeric Arguments). However, if the command you want to repeat prompts for some input, or uses a numeric argument in another way, repetition using a numeric argument might be problematical.

The command C-x z (repeat) provides another way to repeat an Emacs command many times. This command repeats the previous Emacs command, whatever that was. Repeating a command uses the same arguments that were used before; it does not read new arguments each time.

To repeat the command more than once, type additional z's: each z repeats the command one more time. Repetition ends when you type a character other than z, or press a mouse button.

For example, suppose you type C-u 2 0 C-d to delete 20 characters. You can repeat that command (including its argument) three additional times, to delete a total of 80 characters, by typing C-x z z z. The first C-x z repeats the command once, and each subsequent z repeats it once again.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E. The Minibuffer

The minibuffer is the facility used by Emacs commands to read arguments more complicated than a single number. Minibuffer arguments can be file names, buffer names, Lisp function names, Emacs command names, Lisp expressions, and many other things, depending on the command reading the argument. You can use the usual Emacs editing commands in the minibuffer to edit the argument text.

When the minibuffer is in use, it appears in the echo area, and the terminal's cursor moves there. The beginning of the minibuffer line displays a prompt which says what kind of input you should supply and how it will be used. Often this prompt is derived from the name of the command that the argument is for. The prompt normally ends with a colon.

Sometimes a default argument appears in parentheses after the colon; it too is part of the prompt. The default will be used as the argument value if you enter an empty argument (that is, just type RET). For example, commands that read buffer names always show a default, which is the name of the buffer that will be used if you type just RET.

The simplest way to enter a minibuffer argument is to type the text you want, terminated by RET which exits the minibuffer. You can cancel the command that wants the argument, and get out of the minibuffer, by typing C-g.

Since the minibuffer uses the screen space of the echo area, it can conflict with other ways Emacs customarily uses the echo area. Here is how Emacs handles such conflicts:

If a command gets an error while you are in the minibuffer, this does not cancel the minibuffer. However, the echo area is needed for the error message and therefore the minibuffer itself is hidden for a while. It comes back after a few seconds, or as soon as you type anything.

If in the minibuffer you use a command whose purpose is to display a message in the echo area, such as C-x =, the message hides the minibuffer for a while. The minibuffer contents come back after a few seconds, or as soon as you type anything.

Echoing of keystrokes does not take place while the minibuffer is in use.

E.1 Minibuffers for File Names

Entering file names with the minibuffer.

E.2 Editing in the Minibuffer

How to edit in the minibuffer.

E.3 Completion

An abbreviation facility for minibuffer input.

E.4 Minibuffer History

Reusing recent minibuffer arguments.

E.5 Repeating Minibuffer Commands

Re-executing commands that used the minibuffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.1 Minibuffers for File Names

Sometimes the minibuffer starts out with text in it. For example, when you are supposed to give a file name, the minibuffer starts out containing the default directory, which ends with a slash. This is to inform you which directory the file will be found in if you do not specify a directory.

For example, the minibuffer might start out with these contents:
Find File: /u2/emacs/src/
where `Find File: ' is the prompt. Typing buffer.c specifies the file `/u2/emacs/src/buffer.c'. To find files in nearby directories, use ..; thus, if you type ../lisp/simple.el, you will get the file named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with M-DEL the directory names you don't want (see section T.1 Words).

If you don't want any of the default, you can kill it with C-a C-k. But you don't need to kill the default; you can simply ignore it. Insert an absolute file name, one starting with a slash or a tilde, after the default directory. For example, to specify the file `/etc/termcap', just insert that name, giving these minibuffer contents:
Find File: /u2/emacs/src//etc/termcap
GNU Emacs gives a special meaning to a double slash (which is not normally a useful thing to write): it means, "ignore everything before the second slash in the pair." Thus, `/u2/emacs/src/' is ignored in the example above, and you get the file `/etc/termcap'.

If you set insert-default-directory to nil, the default directory is not inserted in the minibuffer. This way, the minibuffer starts out empty. But the name you type, if relative, is still interpreted with respect to the same default directory.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.2 Editing in the Minibuffer

The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual Emacs commands are available for editing the text of an argument you are entering.

Since RET in the minibuffer is defined to exit the minibuffer, you can't use it to insert a newline in the minibuffer. To do that, type C-o or C-q C-j. (Recall that a newline is really the character control-J.)

The minibuffer has its own window which always has space on the screen but acts as if it were not there when the minibuffer is not in use. When the minibuffer is in use, its window is just like the others; you can switch to another window with C-x o, edit text in other windows and perhaps even visit more files, before returning to the minibuffer to submit the argument. You can kill text in another window, return to the minibuffer window, and then yank the text to use it in the argument. See section O. Multiple Windows.

There are some restrictions on the use of the minibuffer window, however. You cannot switch buffers in it--the minibuffer and its window are permanently attached. Also, you cannot split or kill the minibuffer window. But you can make it taller in the normal fashion with C-x ^.

The minibuffer window expands vertically as necessary to hold the text that you put in the minibuffer, if resize-mini-windows is non-nil. If resize-mini-windows is t, the window is always resized to fit the size of the text it displays. If resize-mini-windows is the symbol grow-only, the window grows when the size of displayed text increases, but shrinks (back to the normal size) only when the minibuffer becomes inactive.

The variable max-mini-window-height controls the maximum height for resizing the minibuffer window: a floating-point number specifies a fraction of the frame's height; an integer specifies the maximum number of lines; nil means do not resize the minibuffer window automatically. The default value is 0.25.

If while in the minibuffer you issue a command that displays help text of any sort in another window, you can use the C-M-v command while in the minibuffer to scroll the help text. This lasts until you exit the minibuffer. This feature is especially useful when you display a buffer listing possible completions. See section O.3 Using Other Windows.

Emacs normally disallows most commands that use the minibuffer while the minibuffer is active. This rule is to prevent recursive minibuffers from confusing novice users. If you want to be able to use such commands in the minibuffer, set the variable enable-recursive-minibuffers to a non-nil value.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.3 Completion

For certain kinds of arguments, you can use completion to enter the argument value. Completion means that you type part of the argument, then Emacs visibly fills in the rest, or as much as can be determined from the part you have typed.

When completion is available, certain keys---TAB, RET, and SPC---are rebound to complete the text present in the minibuffer into a longer string that it stands for, by matching it against a set of completion alternatives provided by the command reading the argument. ? is defined to display a list of possible completions of what you have inserted.

For example, when M-x uses the minibuffer to read the name of a command, it provides a list of all available Emacs command names to complete against. The completion keys match the text in the minibuffer against all the command names, find any additional name characters implied by the ones already present in the minibuffer, and add those characters to the ones you have given. This is what makes it possible to type M-x ins SPC b RET instead of M-x insert-buffer RET (for example).

Case is normally significant in completion, because it is significant in most of the names that you can complete (buffer names, file names and command names). Thus, `fo' does not complete to `Foo'. Completion does ignore case distinctions for certain arguments in which case does not matter.

E.3.1 Completion Example

E.3.2 Completion Commands

E.3.3 Strict Completion

E.3.4 Completion Options

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.3.1 Completion Example

A concrete example may help here. If you type M-x au TAB, the TAB looks for alternatives (in this case, command names) that start with `au'. There are several, including auto-fill-mode and auto-save-mode---but they are all the same as far as auto-, so the `au' in the minibuffer changes to `auto-'.

If you type TAB again immediately, there are multiple possibilities for the very next character--it could be any of `cfilrs'---so no more characters are added; instead, TAB displays a list of all possible completions in another window.

If you go on to type f TAB, this TAB sees `auto-f'. The only command name starting this way is auto-fill-mode, so completion fills in the rest of that. You now have `auto-fill-mode' in the minibuffer after typing just au TAB f TAB. Note that TAB has this effect because in the minibuffer it is bound to the command minibuffer-complete when completion is available.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.3.2 Completion Commands

Here is a list of the completion commands defined in the minibuffer when completion is available.

TAB
Complete the text in the minibuffer as much as possible (minibuffer-complete).
SPC
Complete the minibuffer text, but don't go beyond one word (minibuffer-complete-word).
RET
Submit the text in the minibuffer as the argument, possibly completing first as described below (minibuffer-complete-and-exit).
?
Display a list of all possible completions of the text in the minibuffer (minibuffer-list-completions).
SPC completes much like TAB, but never goes beyond the next hyphen or space. If you have `auto-f' in the minibuffer and type SPC, it finds that the completion is `auto-fill-mode', but it stops completing after `fill-'. This gives `auto-fill-'. Another SPC at this point completes all the way to `auto-fill-mode'. The command that implements this behavior is called minibuffer-complete-word.

Here are some commands you can use to choose a completion from a window that displays a list of completions:

Mouse-2
Clicking mouse button 2 on a completion in the list of possible completions chooses that completion (mouse-choose-completion). You normally use this command while point is in the minibuffer, but you must click in the list of completions, not in the minibuffer itself.

PRIOR

M-v
Typing PRIOR or PAGE-UP, or M-v, while in the minibuffer, selects the window showing the completion list buffer (switch-to-completions). This paves the way for using the commands below. (Selecting that window in the usual ways has the same effect, but this way is more convenient.)

RET
Typing RET in the completion list buffer chooses the completion that point is in or next to (choose-completion). To use this command, you must first switch windows to the window that shows the list of completions.

RIGHT
Typing the right-arrow key RIGHT in the completion list buffer moves point to the following completion (next-completion).

LEFT
Typing the left-arrow key LEFT in the completion list buffer moves point toward the beginning of the buffer, to the previous completion (previous-completion).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.3.3 Strict Completion

There are three different ways that RET can work in completing minibuffers, depending on how the argument will be used.

Strict completion is used when it is meaningless to give any argument except one of the known alternatives. For example, when C-x k reads the name of a buffer to kill, it is meaningless to give anything but the name of an existing buffer. In strict completion, RET refuses to exit if the text in the minibuffer does not complete to an exact match.

Cautious completion is similar to strict completion, except that RET exits only if the text was an exact match already, not needing completion. If the text is not an exact match, RET does not exit, but it does complete the text. If it completes to an exact match, a second RET will exit.
Cautious completion is used for reading file names for files that must already exist.

Permissive completion is used when any string whatever is meaningful, and the list of completion alternatives is just a guide. For example, when C-x C-f reads the name of a file to visit, any file name is allowed, in case you want to create a file. In permissive completion, RET takes the text in the minibuffer exactly as given, without completing it.

The completion commands display a list of all possible completions in a window whenever there is more than one possibility for the very next character. Also, typing ? explicitly requests such a list. If the list of completions is long, you can scroll it with C-M-v (see section O.3 Using Other Windows).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.3.4 Completion Options

When completion is done on file names, certain file names are usually ignored. The variable completion-ignored-extensions contains a list of strings; a file whose name ends in any of those strings is ignored as a possible completion. The standard value of this variable has several elements including ".o", ".elc", ".dvi" and "~". The effect is that, for example, `foo' can complete to `foo.c' even though `foo.o' exists as well. However, if all the possible completions end in "ignored" strings, then they are not ignored. Ignored extensions do not apply to lists of completions--those always mention all possible completions.

Normally, a completion command that cannot determine even one additional character automatically displays a list of all possible completions. If the variable completion-auto-help is set to nil, this automatic display is disabled, so you must type ? to display the list of completions.

Partial Completion mode implements a more powerful kind of completion that can complete multiple words in parallel. For example, it can complete the command name abbreviation p-b into print-buffer, because no other command starts with two words whose initials are `p' and `b'.

Partial completion of directories in file names uses `*' to indicate the places for completion; thus, `/u*/b*/f*' might complete to `/usr/bin/foo'.

To enable this mode, use the command M-x partial-completion-mode, or customize the option partial-completion-mode. This binds the partial completion commands to TAB, SPC, RET, and ?. The usual completion commands are available on M-TAB, M-SPC, M-RET and M-?.

Another feature of Partial Completion mode is to extend find-file so that the `<include>' stands for the file named include in some directory in the path PC-include-file-path. If you set PC-disable-includes to non-nil, this feature is disabled.

Icomplete mode presents a constantly-updated display that tells you what completions are available for the text you've entered so far. The command to enable or disable this minor mode is M-x icomplete-mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.4 Minibuffer History

Every argument that you enter with the minibuffer is saved on a minibuffer history list so that you can use it again later in another argument. Special commands load the text of an earlier argument in the minibuffer. They discard the old minibuffer contents, so you can think of them as moving through the history of previous arguments.

UP

M-p
Move to the next earlier argument string saved in the minibuffer history (previous-history-element).
DOWN

M-n
Move to the next later argument string saved in the minibuffer history (next-history-element).
M-r regexp RET
Move to an earlier saved argument in the minibuffer history that has a match for regexp (previous-matching-history-element).
M-s regexp RET
Move to a later saved argument in the minibuffer history that has a match for regexp (next-matching-history-element).
The simplest way to reuse the saved arguments in the history list is to move through the history list one element at a time. While in the minibuffer, use M-p or up-arrow (previous-history-element) to "move to" the next earlier minibuffer input, and use M-n or down-arrow (next-history-element) to "move to" the next later input.

The previous input that you fetch from the history entirely replaces the contents of the minibuffer. To use it as the argument, exit the minibuffer as usual with RET. You can also edit the text before you reuse it; this does not change the history element that you "moved" to, but your new argument does go at the end of the history list in its own right.

For many minibuffer arguments there is a "default" value. In some cases, the minibuffer history commands know the default value. Then you can insert the default value into the minibuffer as text by using M-n to move "into the future" in the history. Eventually we hope to make this feature available whenever the minibuffer has a default value.

There are also commands to search forward or backward through the history; they search for history elements that match a regular expression that you specify with the minibuffer. M-r (previous-matching-history-element) searches older elements in the history, while M-s (next-matching-history-element) searches newer elements. By special dispensation, these commands can use the minibuffer to read their arguments even though you are already in the minibuffer when you issue them. As with incremental searching, an upper-case letter in the regular expression makes the search case-sensitive (see section K.6 Searching and Case).

All uses of the minibuffer record your input on a history list, but there are separate history lists for different kinds of arguments. For example, there is a list for file names, used by all the commands that read file names. (As a special feature, this history list records the absolute file name, no more and no less, even if that is not how you entered the file name.)

There are several other very specific history lists, including one for command names read by M-x, one for buffer names, one for arguments of commands like query-replace, and one for compilation commands read by compile. Finally, there is one "miscellaneous" history list that most minibuffer arguments use.

The variable history-length specifies the maximum length of a minibuffer history list; once a list gets that long, the oldest element is deleted each time an element is added. If the value of history-length is t, though, there is no maximum length and elements are never deleted.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

E.5 Repeating Minibuffer Commands

Every command that uses the minibuffer at least once is recorded on a special history list, together with the values of its arguments, so that you can repeat the entire command. In particular, every use of M-x is recorded there, since M-x uses the minibuffer to read the command name.

C-x ESC ESC
Re-execute a recent minibuffer command (repeat-complex-command).
M-x list-command-history
Display the entire command history, showing all the commands C-x ESC ESC can repeat, most recent first.
C-x ESC ESC is used to re-execute a recent minibuffer-using command. With no argument, it repeats the last such command. A numeric argument specifies which command to repeat; one means the last one, and larger numbers specify earlier ones.

C-x ESC ESC works by turning the previous command into a Lisp expression and then entering a minibuffer initialized with the text for that expression. If you type just RET, the command is repeated as before. You can also change the command by editing the Lisp expression. Whatever expression you finally submit is what will be executed. The repeated command is added to the front of the command history unless it is identical to the most recently executed command already there.

Even if you don't understand Lisp syntax, it will probably be obvious which command is displayed for repetition. If you do not change the text, it will repeat exactly as before.

Once inside the minibuffer for C-x ESC ESC, you can use the minibuffer history commands (M-p, M-n, M-r, M-s; see section E.4 Minibuffer History) to move through the history list of saved entire commands. After finding the desired previous command, you can edit its expression as usual and then resubmit it by typing RET as usual.

The list of previous minibuffer-using commands is stored as a Lisp list in the variable command-history. Each element is a Lisp expression which describes one command and its arguments. Lisp programs can re-execute a command by calling eval with the command-history element.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

F. Running Commands by Name

Every Emacs command has a name that you can use to run it. Commands that are used often, or that must be quick to type, are also bound to keys--short sequences of characters--for convenient use. You can run them by name if you don't remember the keys. Other Emacs commands that do not need to be quick are not bound to keys; the only way to run them is by name. See section AD.4 Customizing Key Bindings, for the description of how to bind commands to keys.

By convention, a command name consists of one or more words, separated by hyphens; for example, auto-fill-mode or manual-entry. The use of English words makes the command name easier to remember than a key made up of obscure characters, even though it is more characters to type.

The way to run a command by name is to start with M-x, type the command name, and finish it with RET. M-x uses the minibuffer to read the command name. RET exits the minibuffer and runs the command. The string `M-x' appears at the beginning of the minibuffer as a prompt to remind you to enter the name of a command to be run. See section E. The Minibuffer, for full information on the features of the minibuffer.

You can use completion to enter the command name. For example, you can invoke the command forward-char by name by typing either
M-x forward-char RET
or
M-x forw TAB c RET
Note that forward-char is the same command that you invoke with the key C-f. You can run any Emacs command by name using M-x, whether or not any keys are bound to it.

If you type C-g while the command name is being read, you cancel the M-x command and get out of the minibuffer, ending up at top level.

To pass a numeric argument to the command you are invoking with M-x, specify the numeric argument before the M-x. M-x passes the argument along to the command it runs. The argument value appears in the prompt while the command name is being read.

If the command you type has a key binding of its own, Emacs mentions this in the echo area, two seconds after the command finishes (if you don't type anything else first). For example, if you type M-x forward-word, the message says that you can run the same command more easily by typing M-f. You can turn off these messages by setting suggest-key-bindings to nil.

Normally, when describing in this manual a command that is run by name, we omit the RET that is needed to terminate the name. Thus we might speak of M-x auto-fill-mode rather than M-x auto-fill-mode RET. We mention the RET only when there is a need to emphasize its presence, such as when we show the command together with following arguments.

M-x works by running the command execute-extended-command, which is responsible for reading the name of another command and invoking it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G. Help

Emacs provides extensive help features accessible through a single character, C-h. C-h is a prefix key that is used for commands that display documentation. The characters that you can type after C-h are called help options. One help option is C-h; that is how you ask for help about using C-h. To cancel, type C-g. The function key F1 is equivalent to C-h.

C-h C-h (help-for-help) displays a list of the possible help options, each with a brief description. Before you type a help option, you can use SPC or DEL to scroll through the list.

C-h or F1 means "help" in various other contexts as well. For example, in the middle of query-replace, it describes the options available for how to operate on the current match. After a prefix key, it displays a list of the alternatives that can follow the prefix key. (A few prefix keys don't support C-h, because they define other meanings for it, but they all support F1.)

Most help buffers use a special major mode, Help mode, which lets you scroll conveniently with SPC and DEL. It also offers hyperlinks to further help regarding cross-referenced names, Info nodes, customization buffers and the like. See section G.7 Help Mode Commands.

If you are looking for a certain feature, but don't know where exactly it is documented, and aren't sure of the name of a related command or option, we recommend trying these methods. Usually it is best to start with an apropos command, then try searching the manual index, then finally look in the FAQ and the package keywords.

C-h a topic RET
This searches for commands whose names match topic, which should be a regular expression (see section K.5 Syntax of Regular Expressions). Browse the buffer that this command displays to find what you are looking for. See section G.4 Apropos.

M-x apropos RET topic RET
This works like C-h a, but it also searches for user options and other variables, in case the feature you are looking for is controlled by an option, not a command. See section G.4 Apropos.

M-x apropos-documentation RET topic RET
This searches the documentation strings (the built-in short descriptions) of all variables and functions (not their names) for a match for topic, a regular expression. See section G.4 Apropos.

C-h i d m emacs RET i topic RET
This looks up topic in the indices of the Emacs on-line manual. If there are several matches, Emacs displays the first one. You can then press , to move to other matches, until you find what you are looking for.

C-h i d m emacs RET s topic RET
Similar, but searches for topic (which can be a regular expression) in the text of the manual rather than in its indices.

C-h F
This brings up the Emacs FAQ, where you can use the usual search commands (see section K. Searching and Replacement) to find the information.

C-h p
Finally, you can try looking up a suitable package using keywords pertinent to the feature you need. See section G.5 Keyword Search for Lisp Libraries.
To find the documentation of a key sequence or a menu item, type C-h C-k and then type that key sequence or select the menu item. This looks up the description of the command invoked by the key or the menu in the appropriate manual (not necessarily the Emacs manual). Likewise, use C-h C-f for reading documentation of a command.

G.1 Help Summary

Brief list of all Help commands.

G.2 Documentation for a Key

Asking what a key does in Emacs.

G.3 Help by Command or Variable Name

Asking about a command, variable or function name.

G.4 Apropos

Asking what pertains to a given topic.

G.5 Keyword Search for Lisp Libraries

Finding Lisp libraries by keywords (topics).

G.6 Help for International Language Support

Help relating to international language support.

G.7 Help Mode Commands

Special features of Help mode and Help buffers.

G.8 Other Help Commands

Other help commands.

G.9 Help on Active Text and Tooltips

Help on active text and tooltips (`balloon help')

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.1 Help Summary

Here is a summary of the defined help commands.

C-h a regexp RET
Display a list of commands whose names match regexp (apropos-command).
C-h b
Display a table of all key bindings in effect now, in this order: minor mode bindings, major mode bindings, and global bindings (describe-bindings).
C-h c key
Show the name of the command that key runs (describe-key-briefly). Here c stands for "character." For more extensive information on key, use C-h k.
C-h f function RET
Display documentation on the Lisp function named function (describe-function). Since commands are Lisp functions, a command name may be used.
C-h h
Display the `HELLO' file, which shows examples of various character sets.
C-h i
Run Info, the program for browsing documentation files (info). The complete Emacs manual is available on-line in Info.
C-h k key
Display the name and documentation of the command that key runs (describe-key).
C-h l
Display a description of the last 100 characters you typed (view-lossage).
C-h m
Display documentation of the current major mode (describe-mode).
C-h n
Display documentation of Emacs changes, most recent first (view-emacs-news).
C-h P
Display info on known problems with Emacs and possible workarounds (view-emacs-problems).
C-h p
Find packages by topic keyword (finder-by-keyword).
C-h s
Display the current contents of the syntax table, plus an explanation of what they mean (describe-syntax). See section AD.6 The Syntax Table.
C-h t
Enter the Emacs interactive tutorial (help-with-tutorial).
C-h v var RET
Display the documentation of the Lisp variable var (describe-variable).
C-h w command RET
Show which keys run the command named command (where-is).
C-h C coding RET
Describe coding system coding (describe-coding-system).
C-h C RET
Describe the coding systems currently in use.
C-h I method RET
Describe an input method (describe-input-method).
C-h L language-env RET
Display information on the character sets, coding systems, and input methods used for language environment language-env (describe-language-environment).
C-h C-c
Display the copying conditions for GNU Emacs.
C-h C-d
Display information about getting new versions of GNU Emacs.
C-h C-f function RET
Enter Info and go to the node documenting the Emacs function function (Info-goto-emacs-command-node).
C-h C-k key
Enter Info and go to the node where the key sequence key is documented (Info-goto-emacs-key-command-node).
C-h C-p
Display information about the GNU Project.
C-h TAB symbol RET
Display the Info documentation on symbol symbol according to the programming language you are editing (info-lookup-symbol).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.2 Documentation for a Key

The most basic C-h options are C-h c (describe-key-briefly) and C-h k (describe-key). C-h c key displays in the echo area the name of the command that key is bound to. For example, C-h c C-f displays `forward-char'. Since command names are chosen to describe what the commands do, this is a good way to get a very brief description of what key does.

C-h k key is similar but gives more information: it displays the documentation string of the command as well as its name. This is too big for the echo area, so a window is used for the display.

C-h c and C-h k work for any sort of key sequences, including function keys and mouse events.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.3 Help by Command or Variable Name

C-h f (describe-function) reads the name of a Lisp function using the minibuffer, then displays that function's documentation string in a window. Since commands are Lisp functions, you can use this to get the documentation of a command that you know by name. For example,
C-h f auto-fill-mode RET
displays the documentation of auto-fill-mode. This is the only way to get the documentation of a command that is not bound to any key (one which you would normally run using M-x).

C-h f is also useful for Lisp functions that you are planning to use in a Lisp program. For example, if you have just written the expression (make-vector len) and want to check that you are using make-vector properly, type C-h f make-vector RET. Because C-h f allows all function names, not just command names, you may find that some of your favorite abbreviations that work in M-x don't work in C-h f. An abbreviation may be unique among command names yet fail to be unique when other function names are allowed.

The default function name for C-h f to describe, if you type just RET, is the name of the function called by the innermost Lisp expression in the buffer around point, provided that is a valid, defined Lisp function name. For example, if point is located following the text `(make-vector (car x)', the innermost list containing point is the one that starts with `(make-vector', so the default is to describe the function make-vector.

C-h f is often useful just to verify that you have the right spelling for the function name. If C-h f mentions a name from the buffer as the default, that name must be defined as a Lisp function. If that is all you want to know, just type C-g to cancel the C-h f command, then go on editing.

C-h w command RET tells you what keys are bound to command. It displays a list of the keys in the echo area. If it says the command is not on any key, you must use M-x to run it. C-h w runs the command where-is.

C-h v (describe-variable) is like C-h f but describes Lisp variables instead of Lisp functions. Its default is the Lisp symbol around or before point, but only if that is the name of a known Lisp variable. See section AD.2 Variables.

Help buffers describing variables or functions defined in Lisp normally have hyperlinks to the Lisp definition, if you have the Lisp source files installed. If you know Lisp, this provides the ultimate documentation. If you don't know Lisp, you should learn it. If you are treating Emacs as an object file, then you are just using Emacs. For real intimacy with Emacs, you must read the source code.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.4 Apropos

A more sophisticated sort of question to ask is, "What are the commands for working with files?" To ask this question, type C-h a file RET, which displays a list of all command names that contain `file', including copy-file, find-file, and so on. With each command name appears a brief description of how to use the command, and what keys you can currently invoke it with. For example, it would say that you can invoke find-file by typing C-x C-f. The a in C-h a stands for "Apropos"; C-h a runs the command apropos-command. This command normally checks only commands (interactive functions); if you specify a prefix argument, it checks noninteractive functions as well.

Because C-h a looks only for functions whose names contain the string you specify, you must use ingenuity in choosing the string. If you are looking for commands for killing backwards and C-h a kill-backwards RET doesn't reveal any, don't give up. Try just kill, or just backwards, or just back. Be persistent. Also note that you can use a regular expression as the argument, for more flexibility (see section K.5 Syntax of Regular Expressions).

Here is a set of arguments to give to C-h a that covers many classes of Emacs commands, since there are strong conventions for naming the standard Emacs commands. By giving you a feel for the naming conventions, this set should also serve to aid you in developing a technique for picking apropos strings.

char, line, word, sentence, paragraph, region, page, sexp, list, defun, rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, forward, backward, next, previous, up, down, search, goto, kill, delete, mark, insert, yank, fill, indent, case, change, set, what, list, find, view, describe, default.

To list all user variables that match a regexp, use the command M-x apropos-variable. This command shows only user variables and customization options by default; if you specify a prefix argument, it checks all variables.

To list all Lisp symbols that contain a match for a regexp, not just the ones that are defined as commands, use the command M-x apropos instead of C-h a. This command does not check key bindings by default; specify a numeric argument if you want it to check them.

The apropos-documentation command is like apropos except that it searches documentation strings as well as symbol names for matches for the specified regular expression.

The apropos-value command is like apropos except that it searches symbols' values for matches for the specified regular expression. This command does not check function definitions or property lists by default; specify a numeric argument if you want it to check them.

If the variable apropos-do-all is non-nil, the commands above all behave as if they had been given a prefix argument.

If you want more information about a function definition, variable or symbol property listed in the Apropos buffer, you can click on it with Mouse-2 or move there and type RET.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.5 Keyword Search for Lisp Libraries

The C-h p command lets you search the standard Emacs Lisp libraries by topic keywords. Here is a partial list of keywords you can use:
abbrev --- abbreviation handling, typing shortcuts, macros.
bib --- support for the bibliography processor bib.
c --- C and C++ language support.
calendar --- calendar and time management support.
comm --- communications, networking, remote access to files.
data --- support for editing files of data.
docs --- support for Emacs documentation.
emulations --- emulations of other editors.
extensions --- Emacs Lisp language extensions.
faces --- support for using faces (fonts and colors; see section J.1 Using Multiple Typefaces).
frames --- support for Emacs frames and window systems.
games --- games, jokes and amusements.
hardware --- support for interfacing with exotic hardware.
help --- support for on-line help systems.
hypermedia --- support for links within text, or other media types.
i18n --- internationalization and alternate character-set support.
internal --- code for Emacs internals, build process, defaults.
languages --- specialized modes for editing programming languages.
lisp --- support for using Lisp (including Emacs Lisp).
local --- libraries local to your site.
maint --- maintenance aids for the Emacs development group.
mail --- modes for electronic-mail handling.
matching --- searching and matching.
news --- support for netnews reading and posting.
non-text --- support for editing files that are not ordinary text.
oop --- support for object-oriented programming.
outlines --- hierarchical outlining.
processes --- process, subshell, compilation, and job control support.
terminals --- support for terminal types.
tex --- support for the TeX formatter.
tools --- programming tools.
unix --- front-ends/assistants for, or emulators of, system features.
vms --- support code for VMS.
wp --- word processing.
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.6 Help for International Language Support

You can use the command C-h L (describe-language-environment) to find out information about the support for a specific language environment. See section Q.3 Language Environments. This tells you which languages this language environment is useful for, and lists the character sets, coding systems, and input methods that go with it. It also shows some sample text to illustrate scripts.

The command C-h h (view-hello-file) displays the file `etc/HELLO', which shows how to say "hello" in many languages.

The command C-h I (describe-input-method) describes information about input methods--either a specified input method, or by default the input method in use. See section Q.4 Input Methods.

The command C-h C (describe-coding-system) describes information about coding systems--either a specified coding system, or the ones currently in use. See section Q.7 Coding Systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.7 Help Mode Commands

Help buffers provide the same commands as View mode (see section M.10 Miscellaneous File Operations), plus a few special commands of their own.

SPC
Scroll forward.
DEL

BS
Scroll backward. On some keyboards, this key is known as BS or backspace.
RET
Follow a cross reference at point.
TAB
Move point forward to the next cross reference.
S-TAB
Move point back to the previous cross reference.
Mouse-2
Follow a cross reference that you click on.
When a command name (see section Running Commands by Name) or variable name (see section AD.2 Variables) appears in the documentation, it normally appears inside paired single-quotes. You can click on the name with Mouse-2, or move point there and type RET, to view the documentation of that command or variable. Use C-c C-b to retrace your steps.

There are convenient commands for moving point to cross references in the help text. TAB (help-next-ref) moves point down to the next cross reference. Use S-TAB to move point up to the previous cross reference (help-previous-ref).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.8 Other Help Commands

C-h i (info) runs the Info program, which is used for browsing through structured documentation files. The entire Emacs manual is available within Info. Eventually all the documentation of the GNU system will be available. Type h after entering Info to run a tutorial on using Info.

If you specify a numeric argument, C-h i prompts for the name of a documentation file. This way, you can browse a file which doesn't have an entry in the top-level Info menu. It is also handy when you need to get to the documentation quickly, and you know the exact name of the file.

There are two special help commands for accessing Emacs documentation through Info. C-h C-f function RET enters Info and goes straight to the documentation of the Emacs function function. C-h C-k key enters Info and goes straight to the documentation of the key key. These two keys run the commands Info-goto-emacs-command-node and Info-goto-emacs-key-command-node. You can use C-h C-k to find the documentation of a menu item: just select that menu item when C-h C-k prompts for a key.

C-h C-f and C-h C-k know about commands and keys described in manuals other than the Emacs manual. Thus, they make it easier to find the documentation of commands and keys when you are not sure which manual describes them, like when using some specialized mode.

When editing a program, if you have an Info version of the manual for the programming language, you can use the command C-h C-i to refer to the manual documentation for a symbol (keyword, function or variable). The details of how this command works depend on the major mode.

If something surprising happens, and you are not sure what commands you typed, use C-h l (view-lossage). C-h l displays the last 100 command characters you typed in. If you see commands that you don't know, you can use C-h c to find out what they do.

Emacs has numerous major modes, each of which redefines a few keys and makes a few other changes in how editing works. C-h m (describe-mode) displays documentation on the current major mode, which normally describes all the commands that are changed in this mode.

C-h b (describe-bindings) and C-h s (describe-syntax) present other information about the current Emacs mode. C-h b displays a list of all the key bindings now in effect, showing the local bindings defined by the current minor modes first, then the local bindings defined by the current major mode, and finally the global bindings (see section AD.4 Customizing Key Bindings). C-h s displays the contents of the syntax table, with explanations of each character's syntax (see section AD.6 The Syntax Table).

You can get a similar list for a particular prefix key by typing C-h after the prefix key. (There are a few prefix keys for which this does not work--those that provide their own bindings for C-h. One of these is ESC, because ESC C-h is actually C-M-h, which marks a defun.)

The other C-h options display various files containing useful information. C-h C-w displays the full details on the complete absence of warranty for GNU Emacs. C-h n (view-emacs-news) displays the file `emacs/etc/NEWS', which contains documentation on Emacs changes arranged chronologically. C-h F (view-emacs-FAQ) displays the Emacs frequently-answered-questions list. C-h t (help-with-tutorial) displays the learn-by-doing Emacs tutorial. C-h C-c (describe-copying) displays the file `emacs/etc/COPYING', which tells you the conditions you must obey in distributing copies of Emacs. C-h C-d (describe-distribution) displays the file `emacs/etc/DISTRIB', which tells you how you can order a copy of the latest version of Emacs. C-h C-p (describe-project) displays general information about the GNU Project. C-h P (view-emacs-problems) displays the file `emacs/etc/PROBLEMS', which lists known problems with Emacs in various situations with solutions or workarounds in many cases.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

G.9 Help on Active Text and Tooltips

When a region of text is "active," so that you can select it with the mouse or a key like RET, it often has associated help text. Areas of the mode line are examples. This help will normally be shown in the echo area when you move point into the active text. In a window system you can display the help text as a "tooltip" (sometimes known as "balloon help"). See section P.18 Tooltips (or "Balloon Help").

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H. The Mark and the Region

Many Emacs commands operate on an arbitrary contiguous part of the current buffer. To specify the text for such a command to operate on, you set the mark at one end of it, and move point to the other end. The text between point and the mark is called the region. Emacs highlights the region whenever there is one, if you enable Transient Mark mode (see section H.2 Transient Mark Mode).

Certain Emacs commands set the mark; other editing commands do not affect it, so the mark remains where you set it last. Each Emacs buffer has its own mark, and setting the mark in one buffer has no effect on other buffers' marks. When you return to a buffer that was current earlier, its mark is at the same place as before.

The ends of the region are always point and the mark. It doesn't matter which of them was put in its current place first, or which one comes earlier in the text--the region starts from point or the mark (whichever comes first), and ends at point or the mark (whichever comes last). Every time you move point, or set the mark in a new place, the region changes.

Many commands that insert text, such as C-y (yank) and M-x insert-buffer, position point and the mark at opposite ends of the inserted text, so that the region consists of the text just inserted.

Aside from delimiting the region, the mark is also useful for remembering a spot that you may want to go back to. To make this feature more useful, each buffer remembers 16 previous locations of the mark in the mark ring.

H.1 Setting the Mark

Commands to set the mark.

H.2 Transient Mark Mode

How to make Emacs highlight the region-- when there is one.

H.3 Operating on the Region

Summary of ways to operate on contents of the region.

H.4 Commands to Mark Textual Objects

Commands to put region around textual units.

H.5 The Mark Ring

Previous mark positions saved so you can go back there.

H.6 The Global Mark Ring

Previous mark positions in various buffers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.1 Setting the Mark

Here are some commands for setting the mark:

C-SPC
Set the mark where point is (set-mark-command).
C-@
The same.
C-x C-x
Interchange mark and point (exchange-point-and-mark).
Drag-Mouse-1
Set point and the mark around the text you drag across.
Mouse-3
Set the mark where point is, then move point to where you click (mouse-save-then-kill).
For example, suppose you wish to convert part of the buffer to upper case, using the C-x C-u (upcase-region) command, which operates on the text in the region. You can first go to the beginning of the text to be capitalized, type C-SPC to put the mark there, move to the end, and then type C-x C-u. Or, you can set the mark at the end of the text, move to the beginning, and then type C-x C-u.

The most common way to set the mark is with the C-SPC command (set-mark-command). This sets the mark where point is. Then you can move point away, leaving the mark behind.

There are two ways to set the mark with the mouse. You can drag mouse button one across a range of text; that puts point where you release the mouse button, and sets the mark at the other end of that range. Or you can click mouse button three, which sets the mark at point (like C-SPC) and then moves point (like Mouse-1). Both of these methods copy the region into the kill ring in addition to setting the mark; that gives behavior consistent with other window-driven applications, but if you don't want to modify the kill ring, you must use keyboard commands to set the mark. See section P.1 Mouse Commands for Editing.

Ordinary terminals have only one cursor, so there is no way for Emacs to show you where the mark is located. You have to remember. The usual solution to this problem is to set the mark and then use it soon, before you forget where it is. Alternatively, you can see where the mark is with the command C-x C-x (exchange-point-and-mark) which puts the mark where point was and point where the mark was. The extent of the region is unchanged, but the cursor and point are now at the previous position of the mark. In Transient Mark mode, this command reactivates the mark.

C-x C-x is also useful when you are satisfied with the position of point but want to move the other end of the region (where the mark is); do C-x C-x to put point at that end of the region, and then move it. Using C-x C-x a second time, if necessary, puts the mark at the new position with point back at its original position.

For more facilities that allow you to go to previously set marks, see H.5 The Mark Ring.

There is no such character as C-SPC in ASCII; when you type SPC while holding down CTRL, what you get on most ordinary terminals is the character C-@. This key is actually bound to set-mark-command. But unless you are unlucky enough to have a terminal where typing C-SPC does not produce C-@, you might as well think of this character as C-SPC. Under X, C-SPC is actually a distinct character, but its binding is still set-mark-command.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.2 Transient Mark Mode

On a terminal that supports colors, Emacs can highlight the current region. But normally it does not. Why not?

Highlighting the region whenever it exists would not be desirable in Emacs, because once you have set a mark, there is always a region (in that buffer). And highlighting the region all the time would be a nuisance. So normally Emacs highlights the region only immediately after you have selected one with the mouse.

You can turn on region highlighting by enabling Transient Mark mode. This is a more rigid mode of operation in which the region "lasts" only temporarily, so you must set up a region for each command that uses one. In Transient Mark mode, most of the time there is no region; therefore, highlighting the region when it exists is useful and not annoying.

To enable Transient Mark mode, type M-x transient-mark-mode. This command toggles the mode, so you can repeat the command to turn off the mode.

Here are the details of Transient Mark mode:

To set the mark, type C-SPC (set-mark-command). This makes the mark active and thus begins highlighting of the region. As you move point, you will see the highlighted region grow and shrink.

The mouse commands for specifying the mark also make it active. So do keyboard commands whose purpose is to specify a region, including M-@, C-M-@, M-h, C-M-h, C-x C-p, and C-x h.

When the mark is active, you can execute commands that operate on the region, such as killing, indenting, or writing to a file.

Any change to the buffer, such as inserting or deleting a character, deactivates the mark. This means any subsequent command that operates on a region will get an error and refuse to operate. You can make the region active again by typing C-x C-x.

Commands like M-> and C-s, that "leave the mark behind" in addition to some other primary purpose, do not activate the new mark. You can activate the new region by executing C-x C-x (exchange-point-and-mark).

C-s when the mark is active does not alter the mark.

Quitting with C-g deactivates the mark.

Some commands operate on the region whenever it is active. For instance, C-x u in Transient Mark mode operates on the region when there is a region. Outside Transient Mark mode, you must type C-u C-x u if you want it to operate on the region. See section D.4 Undoing Changes. Other commands that act this way are identified in their own documentation.

The highlighting of the region uses the region face; you can customize the appearance of the highlighted region by changing this face. See section AD.2.2.3 Customizing Faces.

When multiple windows show the same buffer, they can have different regions, because they can have different values of point (though they all share one common mark position). Ordinarily, only the selected window highlights its region (see section O. Multiple Windows). However, if the variable highlight-nonselected-windows is non-nil, then each window highlights its own region (provided that Transient Mark mode is enabled and the mark in the window's buffer is active).

When Transient Mark mode is not enabled, every command that sets the mark also activates it, and nothing ever deactivates it.

If the variable mark-even-if-inactive is non-nil in Transient Mark mode, then commands can use the mark and the region even when it is inactive. Region highlighting appears and disappears just as it normally does in Transient Mark mode, but the mark doesn't really go away when the highlighting disappears.

Transient Mark mode is also sometimes known as "Zmacs mode" because the Zmacs editor on the MIT Lisp Machine handled the mark in a similar way.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.3 Operating on the Region

Once you have a region and the mark is active, here are some of the ways you can operate on the region:

Kill it with C-w (see section H.7 Deletion and Killing).
Save it in a register with C-x r s (see section I. Registers).
Save it in a buffer or a file (see section H.9 Accumulating Text).
Convert case with C-x C-l or C-x C-u (see section T.6 Case Conversion Commands).
Indent it with C-x TAB or C-M-\ (see section S. Indentation).
Fill it as text with M-x fill-region (see section T.5 Filling Text).
Print hardcopy with M-x print-region (see section AC.18 Hardcopy Output).
Evaluate it as Lisp code with M-x eval-region (see section V.8 Evaluating Emacs-Lisp Expressions).

Most commands that operate on the text in the region have the word region in their names.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.4 Commands to Mark Textual Objects

Here are the commands for placing point and the mark around a textual object such as a word, list, paragraph or page.

M-@
Set mark after end of next word (mark-word). This command and the following one do not move point.
C-M-@
Set mark after end of following balanced expression (mark-sexp).
M-h
Put region around current paragraph (mark-paragraph).
C-M-h
Put region around current defun (mark-defun).
C-x h
Put region around the entire buffer (mark-whole-buffer).
C-x C-p
Put region around current page (mark-page).
M-@ (mark-word) puts the mark at the end of the next word, while C-M-@ (mark-sexp) puts it at the end of the next balanced expression (see section U.4.1 Expressions with Balanced Parentheses). These commands handle arguments just like M-f and C-M-f.

Other commands set both point and mark, to delimit an object in the buffer. For example, M-h (mark-paragraph) moves point to the beginning of the paragraph that surrounds or follows point, and puts the mark at the end of that paragraph (see section T.3 Paragraphs). It prepares the region so you can indent, case-convert, or kill a whole paragraph.

C-M-h (mark-defun) similarly puts point before, and the mark after, the current (or following) major top-level definition, or defun (see section U.2.2 Moving by Defuns). C-x C-p (mark-page) puts point before the current page, and mark at the end (see section T.4 Pages). The mark goes after the terminating page delimiter (to include it in the region), while point goes after the preceding page delimiter (to exclude it). A numeric argument specifies a later page (if positive) or an earlier page (if negative) instead of the current page.

Finally, C-x h (mark-whole-buffer) sets up the entire buffer as the region, by putting point at the beginning and the mark at the end.

In Transient Mark mode, all of these commands activate the mark.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.5 The Mark Ring

Aside from delimiting the region, the mark is also useful for remembering a spot that you may want to go back to. To make this feature more useful, each buffer remembers 16 previous locations of the mark, in the mark ring. Commands that set the mark also push the old mark onto this ring. To return to a marked location, use C-u C-SPC (or C-u C-@); this is the command set-mark-command given a numeric argument. It moves point to where the mark was, and restores the mark from the ring of former marks. Thus, repeated use of this command moves point to all of the old marks on the ring, one by one. The mark positions you move through in this way are not lost; they go to the end of the ring.

Each buffer has its own mark ring. All editing commands use the current buffer's mark ring. In particular, C-u C-SPC always stays in the same buffer.

Many commands that can move long distances, such as M-< (beginning-of-buffer), start by setting the mark and saving the old mark on the mark ring. This is to make it easier for you to move back later. Searches set the mark if they move point. You can tell when a command sets the mark because it displays `Mark set' in the echo area.

If you want to move back to the same place over and over, the mark ring may not be convenient enough. If so, you can record the position in a register for later retrieval (see section Saving Positions in Registers).

The variable mark-ring-max specifies the maximum number of entries to keep in the mark ring. If that many entries exist and another one is pushed, the earliest one in the list is discarded. Repeating C-u C-SPC cycles through the positions currently in the ring.

The variable mark-ring holds the mark ring itself, as a list of marker objects, with the most recent first. This variable is local in every buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.6 The Global Mark Ring

In addition to the ordinary mark ring that belongs to each buffer, Emacs has a single global mark ring. It records a sequence of buffers in which you have recently set the mark, so you can go back to those buffers.

Setting the mark always makes an entry on the current buffer's mark ring. If you have switched buffers since the previous mark setting, the new mark position makes an entry on the global mark ring also. The result is that the global mark ring records a sequence of buffers that you have been in, and, for each buffer, a place where you set the mark.

The command C-x C-SPC (pop-global-mark) jumps to the buffer and position of the latest entry in the global ring. It also rotates the ring, so that successive uses of C-x C-SPC take you to earlier and earlier buffers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.7 Deletion and Killing

Most commands which erase text from the buffer save it in the kill ring so that you can move or copy it to other parts of the buffer. These commands are known as kill commands. The rest of the commands that erase text do not save it in the kill ring; they are known as delete commands. (This distinction is made only for erasure of text in the buffer.) If you do a kill or delete command by mistake, you can use the C-x u (undo) command to undo it (see section D.4 Undoing Changes).

You cannot kill read-only text, since such text does not allow any kind of modification. But some users like to use the kill commands to copy read-only text into the kill ring, without actually changing it. If you set the variable kill-read-only-ok to a non-nil value, the kill commands work specially in a read-only buffer: they move over text, and copy it to the kill ring, without actually deleting it from the buffer. When this happens, a message in the echo area tells you what is happening.

The delete commands include C-d (delete-char) and DEL (delete-backward-char), which delete only one character at a time, and those commands that delete only spaces or newlines. Commands that can destroy significant amounts of nontrivial data generally do a kill operation instead. The commands' names and individual descriptions use the words `kill' and `delete' to say which kind of operation they perform.

Many window systems follow the convention that insertion while text is selected deletes the selected text. You can make Emacs behave this way by enabling Delete Selection mode, with M-x delete-selection-mode, or using Custom. Another effect of this mode is that DEL, C-d and some other keys, when a selection exists, will kill the whole selection. It also enables Transient Mark mode (see section H.2 Transient Mark Mode).

H.7.1 Deletion

Commands for deleting small amounts of text and blank areas.

H.7.2 Killing by Lines

How to kill entire lines of text at one time.

H.7.3 Other Kill Commands

Commands to kill large regions of text and syntactic units such as words and sentences.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.7.1 Deletion

Deletion means erasing text and not saving it in the kill ring. For the most part, the Emacs commands that delete text are those that erase just one character or only whitespace.

C-d

Delete
Delete next character (delete-char). If your keyboard has a Delete function key (usually located in the edit keypad), Emacs binds it to delete-char as well.
DEL

BS
Delete previous character (delete-backward-char). Some keyboards refer to this key as a "backspace key" and label it with a left arrow.
M-\
Delete spaces and tabs around point (delete-horizontal-space).
M-SPC
Delete spaces and tabs around point, leaving one space (just-one-space).
C-x C-o
Delete blank lines around the current line (delete-blank-lines).
M-^
Join two lines by deleting the intervening newline, along with any indentation following it (delete-indentation).
The most basic delete commands are C-d (delete-char) and DEL (delete-backward-char). C-d deletes the character after point, the one the cursor is "on top of." This doesn't move point. DEL deletes the character before the cursor, and moves point back. You can delete newlines like any other characters in the buffer; deleting a newline joins two lines. Actually, C-d and DEL aren't always delete commands; when given arguments, they kill instead, since they can erase more than one character this way.

Every keyboard has a large key, labeled DEL, BACKSPACE, BS or DELETE, which is a short distance above the RET or ENTER key and is normally used for erasing what you have typed. Regardless of the actual name on the key, in Emacs it is equivalent to DEL---or it should be.

Many keyboards (including standard PC keyboards) have a BACKSPACE key a short ways above RET or ENTER, and a DELETE key elsewhere. In that case, the BACKSPACE key is DEL, and the DELETE key is equivalent to C-d---or it should be.

Why do we say "or it should be"? When Emacs starts up using a window system, it determines automatically which key or keys should be equivalent to DEL. As a result, BACKSPACE and/or DELETE keys normally do the right things. But in some unusual cases Emacs gets the wrong information from the system. If these keys don't do what they ought to do, you need to tell Emacs which key to use for DEL. See section AD.9.1 If DEL Fails to Delete, for how to do this.

On most text-only terminals, Emacs cannot tell which keys the keyboard really has, so it follows a uniform plan which may or may not fit your keyboard. The uniform plan is that the ASCII DEL character deletes, and the ASCII BS (backspace) character asks for help (it is the same as C-h). If this is not right for your keyboard, such as if you find that the key which ought to delete backwards enters Help instead, see AD.9.1 If DEL Fails to Delete.

The other delete commands are those which delete only whitespace characters: spaces, tabs and newlines. M-\ (delete-horizontal-space) deletes all the spaces and tab characters before and after point. M-SPC (just-one-space) does likewise but leaves a single space after point, regardless of the number of spaces that existed previously (even if there were none before).

C-x C-o (delete-blank-lines) deletes all blank lines after the current line. If the current line is blank, it deletes all blank lines preceding the current line as well (leaving one blank line, the current line).

M-^ (delete-indentation) joins the current line and the previous line, by deleting a newline and all surrounding spaces, usually leaving a single space. See section M-^.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.7.2 Killing by Lines

C-k
Kill rest of line or one or more lines (kill-line).
The simplest kill command is C-k. If given at the beginning of a line, it kills all the text on the line, leaving it blank. When used on a blank line, it kills the whole line including its newline. To kill an entire non-blank line, go to the beginning and type C-k twice.

More generally, C-k kills from point up to the end of the line, unless it is at the end of a line. In that case it kills the newline following point, thus merging the next line into the current one. Spaces and tabs that you can't see at the end of the line are ignored when deciding which case applies, so if point appears to be at the end of the line, you can be sure C-k will kill the newline.

When C-k is given a positive argument, it kills that many lines and the newlines that follow them (however, text on the current line before point is not killed). With a negative argument -n, it kills n lines preceding the current line (together with the text on the current line before point). Thus, C-u - 2 C-k at the front of a line kills the two previous lines.

C-k with an argument of zero kills the text before point on the current line.

If the variable kill-whole-line is non-nil, C-k at the very beginning of a line kills the entire line including the following newline. This variable is normally nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.7.3 Other Kill Commands

C-w
Kill region (from point to the mark) (kill-region).
M-d
Kill word (kill-word). See section T.1 Words.
M-DEL
Kill word backwards (backward-kill-word).
C-x DEL
Kill back to beginning of sentence (backward-kill-sentence). See section T.2 Sentences.
M-k
Kill to end of sentence (kill-sentence).
C-M-k
Kill the following balanced expression (kill-sexp). See section U.4.1 Expressions with Balanced Parentheses.
M-z char
Kill through the next occurrence of char (zap-to-char).
A kill command which is very general is C-w (kill-region), which kills everything between point and the mark. With this command, you can kill any contiguous sequence of characters, if you first set the region around them.

A convenient way of killing is combined with searching: M-z (zap-to-char) reads a character and kills from point up to (and including) the next occurrence of that character in the buffer. A numeric argument acts as a repeat count. A negative argument means to search backward and kill text before point.

Other syntactic units can be killed: words, with M-DEL and M-d (see section T.1 Words); balanced expressions, with C-M-k (see section U.4.1 Expressions with Balanced Parentheses); and sentences, with C-x DEL and M-k (see section T.2 Sentences).

You can use kill commands in read-only buffers. They don't actually change the buffer, and they beep to warn you of that, but they do copy the text you tried to kill into the kill ring, so you can yank it into other buffers. Most of the kill commands move point across the text they copy in this way, so that successive kill commands build up a single kill ring entry as usual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.8 Yanking

Yanking means reinserting text previously killed. This is what some systems call "pasting." The usual way to move or copy text is to kill it and then yank it elsewhere one or more times.

C-y
Yank last killed text (yank).
M-y
Replace text just yanked with an earlier batch of killed text (yank-pop).
M-w
Save region as last killed text without actually killing it (kill-ring-save).
C-M-w
Append next kill to last batch of killed text (append-next-kill).

H.8.1 The Kill Ring

Where killed text is stored. Basic yanking.

H.8.2 Appending Kills

Several kills in a row all yank together.

H.8.3 Yanking Earlier Kills

Yanking something killed some time ago.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.8.1 The Kill Ring

All killed text is recorded in the kill ring, a list of blocks of text that have been killed. There is only one kill ring, shared by all buffers, so you can kill text in one buffer and yank it in another buffer. This is the usual way to move text from one file to another. (See section H.9 Accumulating Text, for some other ways.)

The command C-y (yank) reinserts the text of the most recent kill. It leaves the cursor at the end of the text. It sets the mark at the beginning of the text. See section H. The Mark and the Region.

C-u C-y leaves the cursor in front of the text, and sets the mark after it. This happens only if the argument is specified with just a C-u, precisely. Any other sort of argument, including C-u and digits, specifies an earlier kill to yank (see section H.8.3 Yanking Earlier Kills).

To copy a block of text, you can use M-w (kill-ring-save), which copies the region into the kill ring without removing it from the buffer. This is approximately equivalent to C-w followed by C-x u, except that M-w does not alter the undo history and does not temporarily change the screen.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.8.2 Appending Kills

Normally, each kill command pushes a new entry onto the kill ring. However, two or more kill commands in a row combine their text into a single entry, so that a single C-y yanks all the text as a unit, just as it was before it was killed.

Thus, if you want to yank text as a unit, you need not kill all of it with one command; you can keep killing line after line, or word after word, until you have killed it all, and you can still get it all back at once.

Commands that kill forward from point add onto the end of the previous killed text. Commands that kill backward from point add text onto the beginning. This way, any sequence of mixed forward and backward kill commands puts all the killed text into one entry without rearrangement. Numeric arguments do not break the sequence of appending kills. For example, suppose the buffer contains this text:
This is a line -!-of sample text.
with point shown by -!-. If you type M-d M-DEL M-d M-DEL, killing alternately forward and backward, you end up with `a line of sample' as one entry in the kill ring, and `This is text.' in the buffer. (Note the double space between `is' and `text', which you can clean up with M-SPC or M-q.)

Another way to kill the same text is to move back two words with M-b M-b, then kill all four words forward with C-u M-d. This produces exactly the same results in the buffer and in the kill ring. M-f M-f C-u M-DEL kills the same text, all going backward; once again, the result is the same. The text in the kill ring entry always has the same order that it had in the buffer before you killed it.

If a kill command is separated from the last kill command by other commands (not just numeric arguments), it starts a new entry on the kill ring. But you can force it to append by first typing the command C-M-w (append-next-kill) right before it. The C-M-w tells the following command, if it is a kill command, to append the text it kills to the last killed text, instead of starting a new entry. With C-M-w, you can kill several separated pieces of text and accumulate them to be yanked back in one place.

A kill command following M-w does not append to the text that M-w copied into the kill ring.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.8.3 Yanking Earlier Kills

To recover killed text that is no longer the most recent kill, use the M-y command (yank-pop). It takes the text previously yanked and replaces it with the text from an earlier kill. So, to recover the text of the next-to-the-last kill, first use C-y to yank the last kill, and then use M-y to replace it with the previous kill. M-y is allowed only after a C-y or another M-y.

You can understand M-y in terms of a "last yank" pointer which points at an entry in the kill ring. Each time you kill, the "last yank" pointer moves to the newly made entry at the front of the ring. C-y yanks the entry which the "last yank" pointer points to. M-y moves the "last yank" pointer to a different entry, and the text in the buffer changes to match. Enough M-y commands can move the pointer to any entry in the ring, so you can get any entry into the buffer. Eventually the pointer reaches the end of the ring; the next M-y loops back around to the first entry again.

M-y moves the "last yank" pointer around the ring, but it does not change the order of the entries in the ring, which always runs from the most recent kill at the front to the oldest one still remembered.

M-y can take a numeric argument, which tells it how many entries to advance the "last yank" pointer by. A negative argument moves the pointer toward the front of the ring; from the front of the ring, it moves "around" to the last entry and continues forward from there.

Once the text you are looking for is brought into the buffer, you can stop doing M-y commands and it will stay there. It's just a copy of the kill ring entry, so editing it in the buffer does not change what's in the ring. As long as no new killing is done, the "last yank" pointer remains at the same place in the kill ring, so repeating C-y will yank another copy of the same previous kill.

If you know how many M-y commands it would take to find the text you want, you can yank that text in one step using C-y with a numeric argument. C-y with an argument restores the text from the specified kill ring entry, counting back from the most recent as 1. Thus, C-u 2 C-y gets the next-to-the-last block of killed text--it is equivalent to C-y M-y. C-y with a numeric argument starts counting from the "last yank" pointer, and sets the "last yank" pointer to the entry that it yanks.

The length of the kill ring is controlled by the variable kill-ring-max; no more than that many blocks of killed text are saved.

The actual contents of the kill ring are stored in a variable named kill-ring; you can view the entire contents of the kill ring with the command C-h v kill-ring.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.9 Accumulating Text

Usually we copy or move text by killing it and yanking it, but there are other methods convenient for copying one block of text in many places, or for copying many scattered blocks of text into one place. To copy one block to many places, store it in a register (see section I. Registers). Here we describe the commands to accumulate scattered pieces of text into a buffer or into a file.

M-x append-to-buffer
Append region to the contents of a specified buffer.
M-x prepend-to-buffer
Prepend region to the contents of a specified buffer.
M-x copy-to-buffer
Copy region into a specified buffer, deleting that buffer's old contents.
M-x insert-buffer
Insert the contents of a specified buffer into current buffer at point.
M-x append-to-file
Append region to the contents of a specified file, at the end.
To accumulate text into a buffer, use M-x append-to-buffer. This reads a buffer name, then inserts a copy of the region into the buffer specified. If you specify a nonexistent buffer, append-to-buffer creates the buffer. The text is inserted wherever point is in that buffer. If you have been using the buffer for editing, the copied text goes into the middle of the text of the buffer, starting from wherever point happens to be at that moment.

Point in that buffer is left at the end of the copied text, so successive uses of append-to-buffer accumulate the text in the specified buffer in the same order as they were copied. Strictly speaking, append-to-buffer does not always append to the text already in the buffer--it appends only if point in that buffer is at the end. However, if append-to-buffer is the only command you use to alter a buffer, then point is always at the end.

M-x prepend-to-buffer is just like append-to-buffer except that point in the other buffer is left before the copied text, so successive prependings add text in reverse order. M-x copy-to-buffer is similar, except that any existing text in the other buffer is deleted, so the buffer is left containing just the text newly copied into it.

To retrieve the accumulated text from another buffer, use the command M-x insert-buffer; this too takes buffername as an argument. It inserts a copy of the whole text in buffer buffername into the current buffer at point, and sets the mark after the inserted text. Alternatively, you can select the other buffer for editing, then copy text from it by killing. See section N. Using Multiple Buffers, for background information on buffers.

Instead of accumulating text within Emacs, in a buffer, you can append text directly into a file with M-x append-to-file, which takes filename as an argument. It adds the text of the region to the end of the specified file. The file is changed immediately on disk.

You should use append-to-file only with files that are not being visited in Emacs. Using it on a file that you are editing in Emacs would change the file behind Emacs's back, which can lead to losing some of your editing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

H.10 Rectangles

The rectangle commands operate on rectangular areas of the text: all the characters between a certain pair of columns, in a certain range of lines. Commands are provided to kill rectangles, yank killed rectangles, clear them out, fill them with blanks or text, or delete them. Rectangle commands are useful with text in multicolumn formats, and for changing text into or out of such formats.

When you must specify a rectangle for a command to work on, you do it by putting the mark at one corner and point at the opposite corner. The rectangle thus specified is called the region-rectangle because you control it in much the same way as the region is controlled. But remember that a given combination of point and mark values can be interpreted either as a region or as a rectangle, depending on the command that uses them.

If point and the mark are in the same column, the rectangle they delimit is empty. If they are in the same line, the rectangle is one line high. This asymmetry between lines and columns comes about because point (and likewise the mark) is between two columns, but within a line.

C-x r k
Kill the text of the region-rectangle, saving its contents as the "last killed rectangle" (kill-rectangle).
C-x r d
Delete the text of the region-rectangle (delete-rectangle).
C-x r y
Yank the last killed rectangle with its upper left corner at point (yank-rectangle).
C-x r o
Insert blank space to fill the space of the region-rectangle (open-rectangle). This pushes the previous contents of the region-rectangle rightward.
M-x clear-rectangle
Clear the region-rectangle by replacing its contents with spaces.
M-x delete-whitespace-rectangle
Delete whitespace in each of the lines on the specified rectangle, starting from the left edge column of the rectangle.
C-x r t string RET
Replace rectangle contents with string on each line. (string-rectangle).
M-x string-insert-rectangle RET string RET
Insert string on each line of the rectangle.
The rectangle operations fall into two classes: commands for deleting and inserting rectangles, and commands for blank rectangles.

There are two ways to get rid of the text in a rectangle: you can discard the text (delete it) or save it as the "last killed" rectangle. The commands for these two ways are C-x r d (delete-rectangle) and C-x r k (kill-rectangle). In either case, the portion of each line that falls inside the rectangle's boundaries is deleted, causing any following text on the line to move left into the gap.

Note that "killing" a rectangle is not killing in the usual sense; the rectangle is not stored in the kill ring, but in a special place that can only record the most recent rectangle killed. This is because yanking a rectangle is so different from yanking linear text that different yank commands have to be used and yank-popping is hard to make sense of.

To yank the last killed rectangle, type C-x r y (yank-rectangle). Yanking a rectangle is the opposite of killing one. Point specifies where to put the rectangle's upper left corner. The rectangle's first line is inserted there, the rectangle's second line is inserted at the same horizontal position, but one line vertically down, and so on. The number of lines affected is determined by the height of the saved rectangle.

You can convert single-column lists into double-column lists using rectangle killing and yanking; kill the second half of the list as a rectangle and then yank it beside the first line of the list. See section AC.23 Two-Column Editing, for another way to edit multi-column text.

You can also copy rectangles into and out of registers with C-x r r r and C-x r i r. See section Rectangle Registers.

There are two commands you can use for making blank rectangles: M-x clear-rectangle which blanks out existing text, and C-x r o (open-rectangle) which inserts a blank rectangle. Clearing a rectangle is equivalent to deleting it and then inserting a blank rectangle of the same size.

The command M-x delete-whitespace-rectangle deletes horizontal whitespace starting from a particular column. This applies to each of the lines in the rectangle, and the column is specified by the left edge of the rectangle. The right edge of the rectangle does not make any difference to this command.

The command C-x r t (string-rectangle) replaces the contents of a region-rectangle with a string on each line. The string's width need not be the same as the width of the rectangle. If the string's width is less, the text after the rectangle shifts left; if the string is wider than the rectangle, the text after the rectangle shifts right.

The command M-x string-insert-rectangle is similar to string-rectangle, but inserts the string on each line, shifting the original text to the right.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I. Registers

Emacs registers are compartments where you can save text, rectangles, positions, and other things for later use. Once you save text or a rectangle in a register, you can copy it into the buffer once, or many times; you can move point to a position saved in a register once, or many times.

Each register has a name, which consists of a single character. A register can store a piece of text, a rectangle, a position, a window configuration, or a file name, but only one thing at any given time. Whatever you store in a register remains there until you store something else in that register. To see what a register r contains, use M-x view-register.

M-x view-register RET r
Display a description of what register r contains.

I.1 Saving Positions in Registers

Saving positions in registers.

I.2 Saving Text in Registers

Saving text in registers.

I.3 Saving Rectangles in Registers

Saving rectangles in registers.

I.4 Saving Window Configurations in Registers

Saving window configurations in registers.

I.6 Keeping File Names in Registers

File names in registers.

I.5 Keeping Numbers in Registers

Numbers in registers.

I.7 Bookmarks

Bookmarks are like registers, but persistent.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I.1 Saving Positions in Registers

Saving a position records a place in a buffer so that you can move back there later. Moving to a saved position switches to that buffer and moves point to that place in it.

C-x r SPC r
Save position of point in register r (point-to-register).
C-x r j r
Jump to the position saved in register r (jump-to-register).
To save the current position of point in a register, choose a name r and type C-x r SPC r. The register r retains the position thus saved until you store something else in that register.

The command C-x r j r moves point to the position recorded in register r. The register is not affected; it continues to hold the same position. You can jump to the saved position any number of times.

If you use C-x r j to go to a saved position, but the buffer it was saved from has been killed, C-x r j tries to create the buffer again by visiting the same file. Of course, this works only for buffers that were visiting files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I.2 Saving Text in Registers

When you want to insert a copy of the same piece of text several times, it may be inconvenient to yank it from the kill ring, since each subsequent kill moves that entry further down the ring. An alternative is to store the text in a register and later retrieve it.

C-x r s r
Copy region into register r (copy-to-register).
C-x r i r
Insert text from register r (insert-register).
M-x append-to-register RET r
Append region to text in register r.
M-x prepend-to-register RET r
Prepend region to text in register r.
C-x r s r stores a copy of the text of the region into the register named r. C-u C-x r s r, the same command with a numeric argument, deletes the text from the buffer as well; you can think of this as "moving" the region text into the register.

M-x append-to-register RET r appends the copy of the text in the region to the text already stored in the register named r. If invoked with a numeric argument, it deletes the region after appending it to the register. A similar command prepend-to-register works the same, except that it prepends the region text to the text in the register, rather than appending it.

C-x r i r inserts in the buffer the text from register r. Normally it leaves point before the text and places the mark after, but with a numeric argument (C-u) it puts point after the text and the mark before.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I.3 Saving Rectangles in Registers

A register can contain a rectangle instead of linear text. The rectangle is represented as a list of strings. See section H.10 Rectangles, for basic information on how to specify a rectangle in the buffer.

C-x r r r
Copy the region-rectangle into register r (copy-rectangle-to-register). With numeric argument, delete it as well.
C-x r i r
Insert the rectangle stored in register r (if it contains a rectangle) (insert-register).
The C-x r i r command inserts a text string if the register contains one, and inserts a rectangle if the register contains one.

See also the command sort-columns, which you can think of as sorting a rectangle. See section AC.21 Sorting Text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I.4 Saving Window Configurations in Registers

You can save the window configuration of the selected frame in a register, or even the configuration of all windows in all frames, and restore the configuration later.

C-x r w r
Save the state of the selected frame's windows in register r (window-configuration-to-register).
C-x r f r
Save the state of all frames, including all their windows, in register r (frame-configuration-to-register).
Use C-x r j r to restore a window or frame configuration. This is the same command used to restore a cursor position. When you restore a frame configuration, any existing frames not included in the configuration become invisible. If you wish to delete these frames instead, use C-u C-x r j r.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I.5 Keeping Numbers in Registers

There are commands to store a number in a register, to insert the number in the buffer in decimal, and to increment it. These commands can be useful in keyboard macros (see section AD.3 Keyboard Macros).

C-u number C-x r n r
Store number into register r (number-to-register).
C-u number C-x r + r
Increment the number in register r by number (increment-register).
C-x r g r
Insert the number from register r into the buffer.
C-x r g is the same command used to insert any other sort of register contents into the buffer. C-x r + with no numeric argument increments the register value by 1; C-x r n with no numeric argument stores zero in the register.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I.6 Keeping File Names in Registers

If you visit certain file names frequently, you can visit them more conveniently if you put their names in registers. Here's the Lisp code used to put a file name in a register:
(set-register ?r '(file . name))
For example,
(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))
puts the file name shown in register `z'.

To visit the file whose name is in register r, type C-x r j r. (This is the same command used to jump to a position or restore a frame configuration.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

I.7 Bookmarks

Bookmarks are somewhat like registers in that they record positions you can jump to. Unlike registers, they have long names, and they persist automatically from one Emacs session to the next. The prototypical use of bookmarks is to record "where you were reading" in various files.

C-x r m RET
Set the bookmark for the visited file, at point.

C-x r m bookmark RET
Set the bookmark named bookmark at point (bookmark-set).

C-x r b bookmark RET
Jump to the bookmark named bookmark (bookmark-jump).

C-x r l
List all bookmarks (list-bookmarks).

M-x bookmark-save
Save all the current bookmark values in the default bookmark file.
The prototypical use for bookmarks is to record one current position in each of several files. So the command C-x r m, which sets a bookmark, uses the visited file name as the default for the bookmark name. If you name each bookmark after the file it points to, then you can conveniently revisit any of those files with C-x r b, and move to the position of the bookmark at the same time.

To display a list of all your bookmarks in a separate buffer, type C-x r l (list-bookmarks). If you switch to that buffer, you can use it to edit your bookmark definitions or annotate the bookmarks. Type C-h m in the bookmark buffer for more information about its special editing commands.

When you kill Emacs, Emacs offers to save your bookmark values in your default bookmark file, `~/.emacs.bmk', if you have changed any bookmark values. You can also save the bookmarks at any time with the M-x bookmark-save command. The bookmark commands load your default bookmark file automatically. This saving and loading is how bookmarks persist from one Emacs session to the next.

If you set the variable bookmark-save-flag to 1, then each command that sets a bookmark will also save your bookmarks; this way, you don't lose any bookmark values even if Emacs crashes. (The value, if a number, says how many bookmark modifications should go by between saving.)

Bookmark position values are saved with surrounding context, so that bookmark-jump can find the proper position even if the file is modified slightly. The variable bookmark-search-size says how many characters of context to record on each side of the bookmark's position.

Here are some additional commands for working with bookmarks:

M-x bookmark-load RET filename RET
Load a file named filename that contains a list of bookmark values. You can use this command, as well as bookmark-write, to work with other files of bookmark values in addition to your default bookmark file.

M-x bookmark-write RET filename RET
Save all the current bookmark values in the file filename.

M-x bookmark-delete RET bookmark RET
Delete the bookmark named bookmark.

M-x bookmark-insert-location RET bookmark RET
Insert in the buffer the name of the file that bookmark bookmark points to.

M-x bookmark-insert RET bookmark RET
Insert in the buffer the contents of the file that bookmark bookmark points to.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J. Controlling the Display

Since only part of a large buffer fits in the window, Emacs tries to show a part that is likely to be interesting. Display-control commands allow you to specify which part of the text you want to see, and how to display it.

J.1 Using Multiple Typefaces

How to change the display style using faces.

J.2 Font Lock mode

Minor mode for syntactic highlighting using faces.

J.3 Highlight Changes Mode

Using colors to show where you changed the buffer.

J.4 Interactive Highlighting by Matching

Tell Emacs what text to highlight.

J.5 Trailing Whitespace

Showing possibly-spurious trailing whitespace.

J.6 Scrolling

Moving text up and down in a window.

J.7 Horizontal Scrolling

Moving text left and right in a window.

J.8 Follow Mode

Follow mode lets two windows scroll as one.

J.9 Selective Display

Hiding lines with lots of indentation.

J.10 Optional Mode Line Features

Optional mode line display features.

J.11 How Text Is Displayed

How text characters are normally displayed.

J.12 Customization of Display

Information on variables for customizing display.

J.13 Displaying the Cursor

Features for displaying the cursor.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.1 Using Multiple Typefaces

When using Emacs with a window system, you can set up multiple styles of displaying characters. Each style is called a face. Each face can specify various attributes, such as the height, weight and slant of the characters, the foreground and background color, and underlining. But it does not have to specify all of them.

Emacs on a character terminal supports only part of face attributes. Which attributes are supported depends on your display type, but many displays support inverse video, bold, and underline attributes, and some support colors.

Features which rely on text in multiple faces (such as Font Lock mode) will also work on non-windowed terminals that can display more than one face, whether by colors or underlining and emboldening. This includes the console on GNU/Linux, an xterm which supports colors, the MS-DOS display (see section AH. Emacs and MS-DOS), and the MS-Windows version invoked with the `-nw' option. Emacs determines automatically whether the terminal has this capability.

You control the appearance of a part of the text in the buffer by specifying the face or faces to use for it. The style of display used for any given character is determined by combining the attributes of all the applicable faces specified for that character. Any attribute that isn't specified by these faces is taken from the default face, whose attributes reflect the default settings of the frame itself.

Enriched mode, the mode for editing formatted text, includes several commands and menus for specifying faces for text in the buffer. See section T.11.4 Faces in Formatted Text, for how to specify the font for text in the buffer. See section T.11.5 Colors in Formatted Text, for how to specify the foreground and background color.

To alter the appearance of a face, use the customization buffer. See section AD.2.2.3 Customizing Faces. You can also use X resources to specify attributes of particular faces (see section AE.13 X Resources). Alternatively, you can change the foreground and background colors of a specific face with M-x set-face-foreground and M-x set-face-background. These commands prompt in the minibuffer for a face name and a color name, with completion, and then set that face to use the specified color. Changing the colors of the default face also changes the foreground and background colors on all frames, both existing and those to be created in the future. (You can also set foreground and background colors for the current frame only; see P.12 Setting Frame Parameters.)

Emacs 21 can correctly display variable-width fonts, but Emacs commands that calculate width and indentation do not know how to calculate variable widths. This can sometimes lead to incorrect results when you use variable-width fonts. In particular, indentation commands can give inconsistent results, so we recommend you avoid variable-width fonts for editing program source code. Filling will sometimes make lines too long or too short. We plan to address these issues in future Emacs versions.

To see what faces are currently defined, and what they look like, type M-x list-faces-display. It's possible for a given face to look different in different frames; this command shows the appearance in the frame in which you type it. Here's a list of the standard defined faces:

default
This face is used for ordinary text that doesn't specify any other face.
mode-line
This face is used for mode lines. By default, it's drawn with shadows for a "raised" effect on window systems, and drawn as the inverse of the default face on non-windowed terminals. See section J.12 Customization of Display.
header-line
Similar to mode-line for a window's header line. Most modes don't use the header line, but the Info mode does.
highlight
This face is used for highlighting portions of text, in various modes. For example, mouse-sensitive text is highlighted using this face.
isearch
This face is used for highlighting Isearch matches.
isearch-lazy-highlight-face
This face is used for lazy highlighting of Isearch matches other than the current one.
region
This face is used for displaying a selected region (when Transient Mark mode is enabled--see below).
secondary-selection
This face is used for displaying a secondary X selection (see section P.2 Secondary Selection).
bold
This face uses a bold variant of the default font, if it has one.
italic
This face uses an italic variant of the default font, if it has one.
bold-italic
This face uses a bold italic variant of the default font, if it has one.
underline
This face underlines text.
fixed-pitch
The basic fixed-pitch face.
fringe
The face for the fringes to the left and right of windows on graphic displays. (The fringes are the narrow portions of the Emacs frame between the text area and the window's right and left borders.)
scroll-bar
This face determines the visual appearance of the scroll bar.
border
This face determines the color of the frame border.
cursor
This face determines the color of the cursor.
mouse
This face determines the color of the mouse pointer.
tool-bar
This is the basic tool-bar face. No text appears in the tool bar, but the colors of this face affect the appearance of tool bar icons.
tooltip
This face is used for tooltips.
menu
This face determines the colors and font of Emacs's menus. Setting the font of LessTif/Motif menus is currently not supported; attempts to set the font are ignored in this case.
trailing-whitespace
The face for highlighting trailing whitespace when show-trailing-whitespace is non-nil; see J.5 Trailing Whitespace.
variable-pitch
The basic variable-pitch face.
When Transient Mark mode is enabled, the text of the region is highlighted when the mark is active. This uses the face named region; you can control the style of highlighting by changing the style of this face (see section AD.2.2.3 Customizing Faces). See section H.2 Transient Mark Mode, for more information about Transient Mark mode and activation and deactivation of the mark.

One easy way to use faces is to turn on Font Lock mode. This minor mode, which is always local to a particular buffer, arranges to choose faces according to the syntax of the text you are editing. It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs. See section J.2 Font Lock mode, for more information about Font Lock mode and syntactic highlighting.

You can print out the buffer with the highlighting that appears on your screen using the command ps-print-buffer-with-faces. See section AC.19 PostScript Hardcopy.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.2 Font Lock mode

Font Lock mode is a minor mode, always local to a particular buffer, which highlights (or "fontifies") using various faces according to the syntax of the text you are editing. It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs--for example, names of functions being defined or reserved keywords.

The command M-x font-lock-mode turns Font Lock mode on or off according to the argument, and toggles the mode when it has no argument. The function turn-on-font-lock unconditionally enables Font Lock mode. This is useful in mode-hook functions. For example, to enable Font Lock mode whenever you edit a C file, you can do this:
(add-hook 'c-mode-hook 'turn-on-font-lock)
To turn on Font Lock mode automatically in all modes which support it, customize the user option global-font-lock-mode or use the function global-font-lock-mode in your `.emacs' file, like this:
(global-font-lock-mode 1)
Font Lock mode uses several specifically named faces to do its job, including font-lock-string-face, font-lock-comment-face, and others. The easiest way to find them all is to use completion on the face name in set-face-foreground.

To change the colors or the fonts used by Font Lock mode to fontify different parts of text, just change these faces. There are two ways to do it:

Invoke M-x set-face-foreground or M-x set-face-background to change the colors of a particular face used by Font Lock. See section J.1 Using Multiple Typefaces. The command M-x list-faces-display displays all the faces currently known to Emacs, including those used by Font Lock.

Customize the faces interactively with M-x customize-face, as described in AD.2.2.3 Customizing Faces.

To get the full benefit of Font Lock mode, you need to choose a default font which has bold, italic, and bold-italic variants; or else you need to have a color or gray-scale screen.

The variable font-lock-maximum-decoration specifies the preferred level of fontification, for modes that provide multiple levels. Level 1 is the least amount of fontification; some modes support levels as high as 3. The normal default is "as high as possible." You can specify an integer, which applies to all modes, or you can specify different numbers for particular major modes; for example, to use level 1 for C/C++ modes, and the default level otherwise, use this:
(setq font-lock-maximum-decoration
      '((c-mode . 1) (c++-mode . 1)))
Fontification can be too slow for large buffers, so you can suppress it. The variable font-lock-maximum-size specifies a buffer size, beyond which buffer fontification is suppressed.

Comment and string fontification (or "syntactic" fontification) relies on analysis of the syntactic structure of the buffer text. For the sake of speed, some modes, including C mode and Lisp mode, rely on a special convention: an open-parenthesis or open-brace in the leftmost column always defines the beginning of a defun, and is thus always outside any string or comment. (See section U.2.1 Left Margin Convention.) If you don't follow this convention, Font Lock mode can misfontify the text that follows an open-parenthesis or open-brace in the leftmost column that is inside a string or comment.

The variable font-lock-beginning-of-syntax-function (always buffer-local) specifies how Font Lock mode can find a position guaranteed to be outside any comment or string. In modes which use the leftmost column parenthesis convention, the default value of the variable is beginning-of-defun---that tells Font Lock mode to use the convention. If you set this variable to nil, Font Lock no longer relies on the convention. This avoids incorrect results, but the price is that, in some cases, fontification for a changed text must rescan buffer text from the beginning of the buffer. This can considerably slow down redisplay while scrolling, particularly if you are close to the end of a large buffer.

Font Lock highlighting patterns already exist for many modes, but you may want to fontify additional patterns. You can use the function font-lock-add-keywords, to add your own highlighting patterns for a particular mode. For example, to highlight `FIXME:' words in C comments, use this:
(font-lock-add-keywords
 'c-mode
 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))
To remove keywords from the font-lock highlighting patterns, use the function font-lock-remove-keywords.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.3 Highlight Changes Mode

Use M-x highlight-changes-mode to enable a minor mode that uses faces (colors, typically) to indicate which parts of the buffer were changed most recently.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.4 Interactive Highlighting by Matching

It is sometimes useful to highlight the strings that match a certain regular expression. For example, you might wish to see all the references to a certain variable in a program source file, or highlight certain parts in a voluminous output of some program, or make certain cliches stand out in an article.

Use the M-x hi-lock-mode command to turn on a minor mode that allows you to specify regular expressions of the text to be highlighted. Hi-lock mode works like Font Lock (see section J.2 Font Lock mode), except that it lets you specify explicitly what parts of text to highlight. You control Hi-lock mode with these commands:

C-x w h regexp RET face RET
Highlight text that matches regexp using face face (highlight-regexp). By using this command more than once, you can highlight various parts of the text in different ways.

C-x w r regexp RET
Unhighlight regexp (unhighlight-regexp). You must enter one of the regular expressions currently specified for highlighting. (You can use completion, or choose from a menu, to enter one of them conveniently.)

C-x w l regexp RET face RET
Highlight entire lines containing a match for regexp, using face face (highlight-lines-matching-regexp).

C-x w b
Insert all the current highlighting regexp/face pairs into the buffer at point, with comment delimiters to prevent them from changing your program. This key binding runs the hi-lock-write-interactive-patterns command.
These patterns will be read the next time you visit the file while Hi-lock mode is enabled, or whenever you use the M-x hi-lock-find-patterns command.

C-x w i
Re-read regexp/face pairs in the current buffer (hi-lock-write-interactive-patterns). The list of pairs is found no matter where in the buffer it may be.
This command does nothing if the major mode is a member of the list hi-lock-exclude-modes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.5 Trailing Whitespace

It is easy to leave unnecessary spaces at the end of a line without realizing it. In most cases, this trailing whitespace has no effect, but there are special circumstances where it matters.

You can make trailing whitespace visible on the screen by setting the buffer-local variable show-trailing-whitespace to t. Then Emacs displays trailing whitespace in the face trailing-whitespace.

Trailing whitespace is defined as spaces or tabs at the end of a line. But trailing whitespace is not displayed specially if point is at the end of the line containing the whitespace. (Doing that looks ugly while you are typing in new text, and the location of point is enough in that case to show you that the spaces are present.)

To delete all trailing whitespace within the current buffer's restriction (see section AC.22 Narrowing), type M-x delete-trailing-whitespace RET. (This command does not remove the form-feed characters.)

Emacs can indicate empty lines at the end of the buffer with a special bitmap on the left fringe of the window. To enable this feature, set the buffer-local variable indicate-empty-lines to a non-nil value. The default value of this variable is controlled by the variable default-indicate-empty-lines; by setting that variable, you can enable or disable this feature for all new buffers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.6 Scrolling

If a buffer contains text that is too large to fit entirely within a window that is displaying the buffer, Emacs shows a contiguous portion of the text. The portion shown always contains point.

Scrolling means moving text up or down in the window so that different parts of the text are visible. Scrolling forward means that text moves up, and new text appears at the bottom. Scrolling backward moves text down and new text appears at the top.

Scrolling happens automatically if you move point past the bottom or top of the window. You can also explicitly request scrolling with the commands in this section.

C-l
Clear screen and redisplay, scrolling the selected window to center point vertically within it (recenter).
C-v
Scroll forward (a windowful or a specified number of lines) (scroll-up).
NEXT

PAGEDOWN
Likewise, scroll forward.
M-v
Scroll backward (scroll-down).
PRIOR

PAGEUP
Likewise, scroll backward.
arg C-l
Scroll so point is on line arg (recenter).
C-M-l
Scroll heuristically to bring useful information onto the screen (reposition-window).
The most basic scrolling command is C-l (recenter) with no argument. It clears the entire screen and redisplays all windows. In addition, it scrolls the selected window so that point is halfway down from the top of the window.

To read the buffer a windowful at a time, use C-v (scroll-up) with no argument. This scrolls forward by nearly the whole window height. The effect is to take the two lines at the bottom of the window and put them at the top, followed by nearly a whole windowful of lines that were not previously visible. If point was in the text that scrolled off the top, it ends up at the new top of the window.

M-v (scroll-down) with no argument scrolls backward in a similar way, also with overlap. The number of lines of overlap across a C-v or M-v is controlled by the variable next-screen-context-lines; by default, it is 2. The function keys NEXT and PRIOR, or PAGEDOWN and PAGEUP, are equivalent to C-v and M-v.

The commands C-v and M-v with a numeric argument scroll the text in the selected window up or down a few lines. C-v with an argument moves the text and point up, together, that many lines; it brings the same number of new lines into view at the bottom of the window. M-v with numeric argument scrolls the text downward, bringing that many new lines into view at the top of the window. C-v with a negative argument is like M-v and vice versa.

The names of scroll commands are based on the direction that the text moves in the window. Thus, the command to scroll forward is called scroll-up because it moves the text upward on the screen. The keys PAGEDOWN and PAGEUP derive their names and customary meanings from a different convention that developed elsewhere; hence the strange result that PAGEDOWN runs scroll-up.

Some users like the full-screen scroll commands to keep point at the same screen line. To enable this behavior, set the variable scroll-preserve-screen-position to a non-nil value. This mode is convenient for browsing through a file by scrolling by screenfuls; if you come back to the screen where you started, point goes back to the line where it started. However, this mode is inconvenient when you move to the next screen in order to move point to the text there.

Another way to do scrolling is with C-l with a numeric argument. C-l does not clear the screen when given an argument; it only scrolls the selected window. With a positive argument n, it repositions text to put point n lines down from the top. An argument of zero puts point on the very top line. Point does not move with respect to the text; rather, the text and point move rigidly on the screen. C-l with a negative argument puts point that many lines from the bottom of the window. For example, C-u - 1 C-l puts point on the bottom line, and C-u - 5 C-l puts it five lines from the bottom. C-u C-l scrolls to put point at the center (vertically) of the selected window.

The C-M-l command (reposition-window) scrolls the current window heuristically in a way designed to get useful information onto the screen. For example, in a Lisp file, this command tries to get the entire current defun onto the screen if possible.

Scrolling happens automatically when point moves out of the visible portion of the text. Normally, automatic scrolling centers point vertically within the window. However, if you set scroll-conservatively to a small number n, then if you move point just a little off the screen--less than n lines--then Emacs scrolls the text just far enough to bring point back on screen. By default, scroll-conservatively is 0.

When the window does scroll by a longer distance, you can control how aggressively it scrolls, by setting the variables scroll-up-aggressively and scroll-down-aggressively. The value of scroll-up-aggressively should be either nil, or a fraction f between 0 and 1. A fraction specifies where on the screen to put point when scrolling upward. More precisely, when a window scrolls up because point is above the window start, the new start position is chosen to put point f part of the window height from the top. The larger f, the more aggressive the scrolling.

nil, which is the default, scrolls to put point at the center. So it is equivalent to .5.

Likewise, scroll-down-aggressively is used for scrolling down. The value, f, specifies how far point should be placed from the bottom of the window; thus, as with scroll-up-aggressively, a larger value is more aggressive.

The variable scroll-margin restricts how close point can come to the top or bottom of a window. Its value is a number of screen lines; if point comes within that many lines of the top or bottom of the window, Emacs recenters the window. By default, scroll-margin is 0.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.7 Horizontal Scrolling

Horizontal scrolling means shifting all the lines sideways within a window--so that some of the text near the left margin is not displayed at all. Emacs does this automatically in any window that uses line truncation rather than continuation: whenever point moves off the left or right edge of the screen, Emacs scrolls the buffer horizontally to make point visible.

When a window has been scrolled horizontally, text lines are truncated rather than continued (see section D.8 Continuation Lines), with a `$' appearing in the first column when there is text truncated to the left, and in the last column when there is text truncated to the right.

You can use these commands to do explicit horizontal scrolling.

C-x <
Scroll text in current window to the left (scroll-left).
C-x >
Scroll to the right (scroll-right).
The command C-x < (scroll-left) scrolls the selected window to the left by n columns with argument n. This moves part of the beginning of each line off the left edge of the window. With no argument, it scrolls by almost the full width of the window (two columns less, to be precise).

C-x > (scroll-right) scrolls similarly to the right. The window cannot be scrolled any farther to the right once it is displayed normally (with each line starting at the window's left margin); attempting to do so has no effect. This means that you don't have to calculate the argument precisely for C-x >; any sufficiently large argument will restore the normal display.

If you scroll a window horizontally by hand, that sets a lower bound for automatic horizontal scrolling. Automatic scrolling will continue to scroll the window, but never farther to the right than the amount you previously set by scroll-left.

To disable automatic horizontal scrolling, set the variable automatic-hscrolling to nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.8 Follow Mode

Follow mode is a minor mode that makes two windows showing the same buffer scroll as one tall "virtual window." To use Follow mode, go to a frame with just one window, split it into two side-by-side windows using C-x 3, and then type M-x follow-mode. From then on, you can edit the buffer in either of the two windows, or scroll either one; the other window follows it.

In Follow mode, if you move point outside the portion visible in one window and into the portion visible in the other window, that selects the other window--again, treating the two as if they were parts of one large window.

To turn off Follow mode, type M-x follow-mode a second time.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.9 Selective Display

Emacs has the ability to hide lines indented more than a certain number of columns (you specify how many columns). You can use this to get an overview of a part of a program.

To hide lines, type C-x $ (set-selective-display) with a numeric argument n. Then lines with at least n columns of indentation disappear from the screen. The only indication of their presence is that three dots (`...') appear at the end of each visible line that is followed by one or more hidden ones.

The commands C-n and C-p move across the hidden lines as if they were not there.

The hidden lines are still present in the buffer, and most editing commands see them as usual, so you may find point in the middle of the hidden text. When this happens, the cursor appears at the end of the previous line, after the three dots. If point is at the end of the visible line, before the newline that ends it, the cursor appears before the three dots.

To make all lines visible again, type C-x $ with no argument.

If you set the variable selective-display-ellipses to nil, the three dots do not appear at the end of a line that precedes hidden lines. Then there is no visible indication of the hidden lines. This variable becomes local automatically when set.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.10 Optional Mode Line Features

The current line number of point appears in the mode line when Line Number mode is enabled. Use the command M-x line-number-mode to turn this mode on and off; normally it is on. The line number appears before the buffer percentage pos, with the letter `L' to indicate what it is. See section AD.1 Minor Modes, for more information about minor modes and about how to use this command.

If you have narrowed the buffer (see section AC.22 Narrowing), the displayed line number is relative to the accessible portion of the buffer.

If the buffer is very large (larger than the value of line-number-display-limit), then the line number doesn't appear. Emacs doesn't compute the line number when the buffer is large, because that would be too slow. Set it to nil to remove the limit.

Line-number computation can also be slow if the lines in the buffer are too long. For this reason, Emacs normally doesn't display line numbers if the average width, in characters, of lines near point is larger than the value of the variable line-number-display-limit-width. The default value is 200 characters.

You can also display the current column number by turning on Column Number mode. It displays the current column number preceded by the letter `C'. Type M-x column-number-mode to toggle this mode.

Emacs can optionally display the time and system load in all mode lines. To enable this feature, type M-x display-time or customize the option display-time-mode. The information added to the mode line usually appears after the buffer name, before the mode names and their parentheses. It looks like this:
hh:mmpm l.ll
Here hh and mm are the hour and minute, followed always by `am' or `pm'. l.ll is the average number of running processes in the whole system recently. (Some fields may be missing if your operating system cannot support them.) If you prefer time display in 24-hour format, set the variable display-time-24hr-format to t.

The word `Mail' appears after the load level if there is mail for you that you have not read yet. On a graphical display you can use an icon instead of `Mail' by customizing display-time-use-mail-icon; this may save some space on the mode line. You can customize display-time-mail-face to make the mail indicator prominent.

By default, the mode line is drawn on graphics displays with 3D-style highlighting, like that of a button when it is not being pressed. If you don't like this effect, you can disable the 3D highlighting of the mode line, by customizing the attributes of the mode-line face in your `.emacs' init file, like this:
(set-face-attribute 'mode-line nil :box nil)
Alternatively, you can turn off the box attribute in your `.Xdefaults' file:
Emacs.mode-line.AttributeBox: off
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.11 How Text Is Displayed

ASCII printing characters (octal codes 040 through 0176) in Emacs buffers are displayed with their graphics, as are non-ASCII multibyte printing characters (octal codes above 0400).

Some ASCII control characters are displayed in special ways. The newline character (octal code 012) is displayed by starting a new line. The tab character (octal code 011) is displayed by moving to the next tab stop column (normally every 8 columns).

Other ASCII control characters are normally displayed as a caret (`^') followed by the non-control version of the character; thus, control-A is displayed as `^A'.

Non-ASCII characters 0200 through 0237 (octal) are displayed with octal escape sequences; thus, character code 0230 (octal) is displayed as `\230'. The display of character codes 0240 through 0377 (octal) may be either as escape sequences or as graphics. They do not normally occur in multibyte buffers, but if they do, they are displayed as Latin-1 graphics. In unibyte mode, if you enable European display they are displayed using their graphics (assuming your terminal supports them), otherwise as escape sequences. See section Q.13 Single-byte Character Set Support.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.12 Customization of Display

This section contains information for customization only. Beginning users should skip it.

The variable mode-line-inverse-video is an obsolete way of controlling whether the mode line is displayed in inverse video; the preferred way of doing this is to change the mode-line face. See section B.3 The Mode Line. However, if mode-line-inverse-video has a value of nil, then the mode-line face will be ignored, and mode-lines will be drawn using the default text face. See section J.1 Using Multiple Typefaces.

If the variable inverse-video is non-nil, Emacs attempts to invert all the lines of the display from what they normally are.

If the variable visible-bell is non-nil, Emacs attempts to make the whole screen blink when it would normally make an audible bell sound. This variable has no effect if your terminal does not have a way to make the screen blink.

When you reenter Emacs after suspending, Emacs normally clears the screen and redraws the entire display. On some terminals with more than one page of memory, it is possible to arrange the termcap entry so that the `ti' and `te' strings (output to the terminal when Emacs is entered and exited, respectively) switch between pages of memory so as to use one page for Emacs and another page for other output. Then you might want to set the variable no-redraw-on-reenter non-nil; this tells Emacs to assume, when resumed, that the screen page it is using still contains what Emacs last wrote there.

The variable echo-keystrokes controls the echoing of multi-character keys; its value is the number of seconds of pause required to cause echoing to start, or zero meaning don't echo at all. See section B.2 The Echo Area.

If the variable ctl-arrow is nil, all control characters in the buffer are displayed with octal escape sequences, except for newline and tab. Altering the value of ctl-arrow makes it local to the current buffer; until that time, the default value is in effect. The default is initially t. See section `Display Tables' in The Emacs Lisp Reference Manual.

Normally, a tab character in the buffer is displayed as whitespace which extends to the next display tab stop position, and display tab stops come at intervals equal to eight spaces. The number of spaces per tab is controlled by the variable tab-width, which is made local by changing it, just like ctl-arrow. Note that how the tab character in the buffer is displayed has nothing to do with the definition of TAB as a command. The variable tab-width must have an integer value between 1 and 1000, inclusive.

If the variable truncate-lines is non-nil, then each line of text gets just one screen line for display; if the text line is too long, display shows only the part that fits. If truncate-lines is nil, then long text lines display as more than one screen line, enough to show the whole text of the line. See section D.8 Continuation Lines. Altering the value of truncate-lines makes it local to the current buffer; until that time, the default value is in effect. The default is initially nil.

If the variable truncate-partial-width-windows is non-nil, it forces truncation rather than continuation in any window less than the full width of the screen or frame, regardless of the value of truncate-lines. For information about side-by-side windows, see O.2 Splitting Windows. See also section `Display' in The Emacs Lisp Reference Manual.

The variable baud-rate holds the output speed of the terminal, as far as Emacs knows. Setting this variable does not change the speed of actual data transmission, but the value is used for calculations. On terminals, it affects padding, and decisions about whether to scroll part of the screen or redraw it instead. It also affects the behavior of incremental search.

On window-systems, baud-rate is only used to determine how frequently to look for pending input during display updating. A higher value of baud-rate means that check for pending input will be done less frequently.

You can customize the way any particular character code is displayed by means of a display table. See section `Display Tables' in The Emacs Lisp Reference Manual.

On a window system, Emacs can optionally display the mouse pointer in a special shape to say that Emacs is busy. To turn this feature on or off, customize the group cursor. You can also control the amount of time Emacs must remain busy before the busy indicator is displayed, by setting the variable hourglass-delay.

On some text-only terminals, bold face and inverse video together result in text that is hard to read. Call the function tty-suppress-bold-inverse-default-colors with a non-nil argument to suppress the effect of bold-face in this case.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

J.13 Displaying the Cursor

There are a number of ways to customize the display of the cursor. M-x hl-line-mode enables or disables a minor mode which highlights the line containing point. On window systems, the command M-x blink-cursor-mode turns on or off the blinking of the cursor. (On terminals, the terminal itself blinks the cursor, and Emacs has no control over it.)

You can customize the cursor's color, and whether it blinks, using the cursor Custom group (see section AD.2.2 Easy Customization Interface).

When displaying on a window system, Emacs can optionally draw the block cursor as wide as the character under the cursor--for example, if the cursor is on a tab character, it would cover the full width occupied by that tab character. To enable this feature, set the variable x-stretch-cursor to a non-nil value.

Normally, the cursor in non-selected windows is shown as a hollow box. To turn off cursor display in non-selected windows, customize the option cursor-in-non-selected-windows to assign it a nil value.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K. Searching and Replacement

Like other editors, Emacs has commands for searching for occurrences of a string. The principal search command is unusual in that it is incremental; it begins to search before you have finished typing the search string. There are also nonincremental search commands more like those of other editors.

Besides the usual replace-string command that finds all occurrences of one string and replaces them with another, Emacs has a more flexible replacement command called query-replace, which asks interactively which occurrences to replace.

K.1 Incremental Search

Search happens as you type the string.

K.2 Nonincremental Search

Specify entire string and then search.

K.3 Word Search

Search for sequence of words.

K.4 Regular Expression Search

Search for match for a regexp.

K.5 Syntax of Regular Expressions

Syntax of regular expressions.

K.6 Searching and Case

To ignore case while searching, or not.

K.7 Replacement Commands

Search, and replace some or all matches.

K.8 Other Search-and-Loop Commands

Operating on all matches for some regexp.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.1 Incremental Search

An incremental search begins searching as soon as you type the first character of the search string. As you type in the search string, Emacs shows you where the string (as you have typed it so far) would be found. When you have typed enough characters to identify the place you want, you can stop. Depending on what you plan to do next, you may or may not need to terminate the search explicitly with RET.

C-s
Incremental search forward (isearch-forward).
C-r
Incremental search backward (isearch-backward).
C-s starts a forward incremental search. It reads characters from the keyboard, and moves point past the next occurrence of those characters. If you type C-s and then F, that puts the cursor after the first `F' (the first following the starting point, since this is a forward search). Then if you type an O, you will see the cursor move just after the first `FO' (the `F' in that `FO' may or may not be the first `F'). After another O, the cursor moves after the first `FOO' after the place where you started the search. At each step, the buffer text that matches the search string is highlighted, if the terminal can do that; the current search string is always displayed in the echo area.

If you make a mistake in typing the search string, you can cancel characters with DEL. Each DEL cancels the last character of search string. This does not happen until Emacs is ready to read another input character; first it must either find, or fail to find, the character you want to erase. If you do not want to wait for this to happen, use C-g as described below.

When you are satisfied with the place you have reached, you can type RET, which stops searching, leaving the cursor where the search brought it. Also, any command not specially meaningful in searches stops the searching and is then executed. Thus, typing C-a would exit the search and then move to the beginning of the line. RET is necessary only if the next command you want to type is a printing character, DEL, RET, or another character that is special within searches (C-q, C-w, C-r, C-s, C-y, M-y, M-r, M-s, and some other meta-characters).

Sometimes you search for `FOO' and find one, but not the one you expected to find. There was a second `FOO' that you forgot about, before the one you were aiming for. In this event, type another C-s to move to the next occurrence of the search string. You can repeat this any number of times. If you overshoot, you can cancel some C-s characters with DEL.

After you exit a search, you can search for the same string again by typing just C-s C-s: the first C-s is the key that invokes incremental search, and the second C-s means "search again."

To reuse earlier search strings, use the search ring. The commands M-p and M-n move through the ring to pick a search string to reuse. These commands leave the selected search ring element in the minibuffer, where you can edit it. Type C-s or C-r to terminate editing the string and search for it.

If your string is not found at all, the echo area says `Failing I-Search'. The cursor is after the place where Emacs found as much of your string as it could. Thus, if you search for `FOOT', and there is no `FOOT', you might see the cursor after the `FOO' in `FOOL'. At this point there are several things you can do. If your string was mistyped, you can rub some of it out and correct it. If you like the place you have found, you can type RET or some other Emacs command to remain there. Or you can type C-g, which removes from the search string the characters that could not be found (the `T' in `FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second C-g at that point cancels the search entirely, returning point to where it was when the search started.

An upper-case letter in the search string makes the search case-sensitive. If you delete the upper-case character from the search string, it ceases to have this effect. See section K.6 Searching and Case.

To search for a newline, type C-j. To search for another control character, such as control-S or carriage return, you must quote it by typing C-q first. This function of C-q is analogous to its use for insertion (see section D.1 Inserting Text): it causes the following character to be treated the way any "ordinary" character is treated in the same context. You can also specify a character by its octal code: enter C-q followed by a sequence of octal digits.

To search for non-ASCII characters, you must use an input method (see section Q.4 Input Methods). If an input method is enabled in the current buffer when you start the search, you can use it while you type the search string also. Emacs indicates that by including the input method mnemonic in its prompt, like this:
I-search [im]:
where im is the mnemonic of the active input method. You can toggle (enable or disable) the input method while you type the search string with C-\ (isearch-toggle-input-method). You can turn on a certain (non-default) input method with C-^ (isearch-toggle-specified-input-method), which prompts for the name of the input method. The input method you enable during incremental search remains enabled in the current buffer afterwards.

If a search is failing and you ask to repeat it by typing another C-s, it starts again from the beginning of the buffer. Repeating a failing reverse search with C-r starts again from the end. This is called wrapping around, and `Wrapped' appears in the search prompt once this has happened. If you keep on going past the original starting point of the search, it changes to `Overwrapped', which means that you are revisiting matches that you have already seen.

The C-g "quit" character does special things during searches; just what it does depends on the status of the search. If the search has found what you specified and is waiting for input, C-g cancels the entire search. The cursor moves back to where you started the search. If C-g is typed when there are characters in the search string that have not been found--because Emacs is still searching for them, or because it has failed to find them--then the search string characters which have not been found are discarded from the search string. With them gone, the search is now successful and waiting for more input, so a second C-g will cancel the entire search.

You can change to searching backwards with C-r. If a search fails because the place you started was too late in the file, you should do this. Repeated C-r keeps looking for more occurrences backwards. A C-s starts going forwards again. C-r in a search can be canceled with DEL.

If you know initially that you want to search backwards, you can use C-r instead of C-s to start the search, because C-r as a key runs a command (isearch-backward) to search backward. A backward search finds matches that are entirely before the starting point, just as a forward search finds matches that begin after it.

The characters C-y and C-w can be used in incremental search to grab text from the buffer into the search string. This makes it convenient to search for another occurrence of text at point. C-w copies the word after point as part of the search string, advancing point over that word. Another C-s to repeat the search will then search for a string including that word. C-y is similar to C-w but copies all the rest of the current line into the search string. Both C-y and C-w convert the text they copy to lower case if the search is currently not case-sensitive; this is so the search remains case-insensitive.

The character M-y copies text from the kill ring into the search string. It uses the same text that C-y as a command would yank. Mouse-2 in the echo area does the same. See section H.8 Yanking.

When you exit the incremental search, it sets the mark to where point was, before the search. That is convenient for moving back there. In Transient Mark mode, incremental search sets the mark without activating it, and does so only if the mark is not already active.

When you pause for a little while during incremental search, it highlights all other possible matches for the search string. This makes it easier to anticipate where you can get to by typing C-s or C-r to repeat the search. The short delay before highlighting other matches helps indicate which match is the current one. If you don't like this feature, you can turn it off by setting isearch-lazy-highlight to nil.

You can control how this highlighting looks by customizing the faces isearch (used for the current match) and isearch-lazy-highlight-face (for all the other matches).

To customize the special characters that incremental search understands, alter their bindings in the keymap isearch-mode-map. For a list of bindings, look at the documentation of isearch-mode with C-h f isearch-mode RET.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.1.1 Slow Terminal Incremental Search

Incremental search on a slow terminal uses a modified style of display that is designed to take less time. Instead of redisplaying the buffer at each place the search gets to, it creates a new single-line window and uses that to display the line that the search has found. The single-line window comes into play as soon as point moves outside of the text that is already on the screen.

When you terminate the search, the single-line window is removed. Emacs then redisplays the window in which the search was done, to show its new position of point.

The slow terminal style of display is used when the terminal baud rate is less than or equal to the value of the variable search-slow-speed, initially 1200. See baud-rate in J.12 Customization of Display.

The number of lines to use in slow terminal search display is controlled by the variable search-slow-window-lines. Its normal value is 1.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.2 Nonincremental Search

Emacs also has conventional nonincremental search commands, which require you to type the entire search string before searching begins.

C-s RET string RET
Search for string.
C-r RET string RET
Search backward for string.
To do a nonincremental search, first type C-s RET. This enters the minibuffer to read the search string; terminate the string with RET, and then the search takes place. If the string is not found, the search command signals an error.

When you type C-s RET, the C-s invokes incremental search as usual. That command is specially programmed to invoke nonincremental search, search-forward, if the string you specify is empty. (Such an empty argument would otherwise be useless.) But it does not call search-forward right away. First it checks the next input character to see if is C-w, which specifies a word search. See section K.3 Word Search. C-r RET does likewise, for a reverse incremental search.

Forward and backward nonincremental searches are implemented by the commands search-forward and search-backward. These commands may be bound to keys in the usual manner. The feature that you can get to them via the incremental search commands exists for historical reasons, and to avoid the need to find key sequences for them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.3 Word Search

Word search searches for a sequence of words without regard to how the words are separated. More precisely, you type a string of many words, using single spaces to separate them, and the string can be found even if there are multiple spaces, newlines, or other punctuation characters between these words.

Word search is useful for editing a printed document made with a text formatter. If you edit while looking at the printed, formatted version, you can't tell where the line breaks are in the source file. With word search, you can search without having to know them.

C-s RET C-w words RET
Search for words, ignoring details of punctuation.
C-r RET C-w words RET
Search backward for words, ignoring details of punctuation.
Word search is a special case of nonincremental search and is invoked with C-s RET C-w. This is followed by the search string, which must always be terminated with RET. Being nonincremental, this search does not start until the argument is terminated. It works by constructing a regular expression and searching for that; see K.4 Regular Expression Search.

Use C-r RET C-w to do backward word search.

Forward and backward word searches are implemented by the commands word-search-forward and word-search-backward. These commands may be bound to keys in the usual manner. They are available via the incremental search commands both for historical reasons and to avoid the need to find suitable key sequences for them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.4 Regular Expression Search

A regular expression (regexp, for short) is a pattern that denotes a class of alternative strings to match, possibly infinitely many. GNU Emacs provides both incremental and nonincremental ways to search for a match for a regexp.

Incremental search for a regexp is done by typing C-M-s (isearch-forward-regexp), or by invoking C-s with a prefix argument (whose value does not matter). This command reads a search string incrementally just like C-s, but it treats the search string as a regexp rather than looking for an exact match against the text in the buffer. Each time you add text to the search string, you make the regexp longer, and the new regexp is searched for. To search backward for a regexp, use C-M-r (isearch-backward-regexp), or C-r with a prefix argument.

All of the control characters that do special things within an ordinary incremental search have the same function in incremental regexp search. Typing C-s or C-r immediately after starting the search retrieves the last incremental search regexp used; that is to say, incremental regexp and non-regexp searches have independent defaults. They also have separate search rings that you can access with M-p and M-n.

If you type SPC in incremental regexp search, it matches any sequence of whitespace characters, including newlines. If you want to match just a space, type C-q SPC.

Note that adding characters to the regexp in an incremental regexp search can make the cursor move back and start again. For example, if you have searched for `foo' and you add `\|bar', the cursor backs up in case the first `bar' precedes the first `foo'.

Nonincremental search for a regexp is done by the functions re-search-forward and re-search-backward. You can invoke these with M-x, or bind them to keys, or invoke them by way of incremental regexp search with C-M-s RET and C-M-r RET.

If you use the incremental regexp search commands with a prefix argument, they perform ordinary string search, like isearch-forward and isearch-backward. See section K.1 Incremental Search.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.5 Syntax of Regular Expressions

Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character is a simple regular expression which matches that same character and nothing else. The special characters are `$', `^', `.', `*', `+', `?', `[', `]' and `\'. Any other character appearing in a regular expression is ordinary, unless a `\' precedes it. (When you use regular expressions in a Lisp program, each `\' must be doubled, see the example near the end of this section.)

For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does not match the string `ff'.) Likewise, `o' is a regular expression that matches only `o'. (When case distinctions are being ignored, these regexps also match `F' and `O', but we consider this a generalization of "the same string," rather than an exception.)

Any two regular expressions a and b can be concatenated. The result is a regular expression which matches a string if a matches some amount of the beginning of that string and b matches the rest of the string.

As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial. To do something nontrivial, you need to use one of the special characters. Here is a list of them.

. (Period)
is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like `a.b', which matches any three-character string that begins with `a' and ends with `b'.

*
is not a construct by itself; it is a postfix operator that means to match the preceding regular expression repetitively as many times as possible. Thus, `o*' matches any number of `o's (including no `o's).
`*' always applies to the smallest possible preceding expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. It matches `f', `fo', `foo', and so on.

The matcher processes a `*' construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the `*'-modified construct in case that makes it possible to match the rest of the pattern. For example, in matching `ca*ar' against the string `caaar', the `a*' first tries to match all three `a's; but the rest of the pattern is `ar' and there is only `r' left to match, so this try fails. The next alternative is for `a*' to match only two `a's. With this choice, the rest of the regexp matches successfully.

+
is a postfix operator, similar to `*' except that it must match the preceding expression at least once. So, for example, `ca+r' matches the strings `car' and `caaaar' but not the string `cr', whereas `ca*r' matches all three strings.

?
is a postfix operator, similar to `*' except that it can match the preceding expression either once or not at all. For example, `ca?r' matches `car' or `cr'; nothing else.

*?, +?, ??
are non-greedy variants of the operators above. The normal operators `*', `+', `?' are greedy in that they match as much as they can, as long as the overall regexp can still match. With a following `?', they are non-greedy: they will match as little as possible.
Thus, both `ab*' and `ab*?' can match the string `a' and the string `abbbb'; but if you try to match them both against the text `abbb', `ab*' will match it all (the longest valid match), while `ab*?' will match just `a' (the shortest valid match).

\{n\}
is a postfix operator that specifies repetition n times--that is, the preceding regular expression must match exactly n times in a row. For example, `x\{4\}' matches the string `xxxx' and nothing else.

\{n,m\}
is a postfix operator that specifies repetition between n and m times--that is, the preceding regular expression must match at least n times, but no more than m times. If m is omitted, then there is no upper limit, but the preceding regular expression must match at least n times.
`\{0,1\}' is equivalent to `?'.
`\{0,\}' is equivalent to `*'.
`\{1,\}' is equivalent to `+'.

[ ... ]
is a character set, which begins with `[' and is terminated by `]'. In the simplest case, the characters between the two brackets are what this set can match.
Thus, `[ad]' matches either one `a' or one `d', and `[ad]*' matches any string composed of just `a's and `d's (including the empty string), from which it follows that `c[ad]*r' matches `cr', `car', `cdr', `caddaar', etc.

You can also include character ranges in a character set, by writing the starting and ending characters with a `-' between them. Thus, `[a-z]' matches any lower-case ASCII letter. Ranges may be intermixed freely with individual characters, as in `[a-z$%.]', which matches any lower-case ASCII letter or `$', `%' or period.

Note that the usual regexp special characters are not special inside a character set. A completely different set of special characters exists inside character sets: `]', `-' and `^'.

To include a `]' in a character set, you must make it the first character. For example, `[]a]' matches `]' or `a'. To include a `-', write `-' as the first or last character of the set, or put it after a range. Thus, `[]-]' matches both `]' and `-'.

To include `^' in a set, put it anywhere but at the beginning of the set. (At the beginning, it complements the set--see below.)

When you use a range in case-insensitive search, you should write both ends of the range in upper case, or both in lower case, or both should be non-letters. The behavior of a mixed-case range such as `A-z' is somewhat ill-defined, and it may change in future Emacs versions.

[^ ... ]
`[^' begins a complemented character set, which matches any character except the ones specified. Thus, `[^a-z0-9A-Z]' matches all characters except ASCII letters and digits.
`^' is not special in a character set unless it is the first character. The character following the `^' is treated as if it were first (in other words, `-' and `]' are not special there).

A complemented character set can match a newline, unless newline is mentioned as one of the characters not to match. This is in contrast to the handling of regexps in programs such as grep.

^
is a special character that matches the empty string, but only at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, `^foo' matches a `foo' that occurs at the beginning of a line.

$
is similar to `^' but matches only at the end of a line. Thus, `x+$' matches a string of one `x' or more at the end of a line.

\
has two functions: it quotes the special characters (including `\'), and it introduces additional special constructs.
Because `\' quotes special characters, `\$' is a regular expression that matches only `$', and `\[' is a regular expression that matches only `[', and so on.
Note: for historical compatibility, special characters are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, `*foo' treats `*' as ordinary since there is no preceding expression on which the `*' can act. It is poor practice to depend on this behavior; it is better to quote the special character anyway, regardless of where it appears.

For the most part, `\' followed by any character matches only that character. However, there are several exceptions: two-character sequences starting with `\' that have special meanings. The second character in the sequence is always an ordinary character when used on its own. Here is a table of `\' constructs.

\|
specifies an alternative. Two regular expressions a and b with `\|' in between form an expression that matches some text if either a matches it or b matches it. It works by trying to match a, and if that fails, by trying to match b.
Thus, `foo\|bar' matches either `foo' or `bar' but no other string.

`\|' applies to the largest possible surrounding expressions. Only a surrounding `\( ... \)' grouping can limit the grouping power of `\|'.

Full backtracking capability exists to handle multiple uses of `\|'.

\( ... \)
is a grouping construct that serves three purposes:

To enclose a set of `\|' alternatives for other operations. Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.

To enclose a complicated expression for the postfix operators `*', `+' and `?' to operate on. Thus, `ba\(na\)*' matches `bananana', etc., with any (zero or more) number of `na' strings.

To record a matched substring for future reference.

This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that is assigned as a second meaning to the same `\( ... \)' construct. In practice there is usually no conflict between the two meanings; when there is a conflict, you can use a "shy" group.

\(?: ... \)
specifies a "shy" group that does not record the matched substring; you can't refer back to it with `\d'. This is useful in mechanically combining regular expressions, so that you can add groups for syntactic purposes without interfering with the numbering of the groups that were written by the user.

\d
matches the same text that matched the dth occurrence of a `\( ... \)' construct.
After the end of a `\( ... \)' construct, the matcher remembers the beginning and end of the text matched by that construct. Then, later on in the regular expression, you can use `\' followed by the digit d to mean "match the same text matched the dth time by the `\( ... \)' construct."

The strings matching the first nine `\( ... \)' constructs appearing in a regular expression are assigned numbers 1 through 9 in the order that the open-parentheses appear in the regular expression. So you can use `\1' through `\9' to refer to the text matched by the corresponding `\( ... \)' constructs.

For example, `\(.*\)\1' matches any newline-free string that is composed of two identical halves. The `\(.*\)' matches the first half, which may be anything, but the `\1' that follows must match the same exact text.

If a particular `\( ... \)' construct matches more than once (which can easily happen if it is followed by `*'), only the last match is recorded.

\`
matches the empty string, but only at the beginning of the buffer or string being matched against.

\'
matches the empty string, but only at the end of the buffer or string being matched against.

\=
matches the empty string, but only at point.

\b
matches the empty string, but only at the beginning or end of a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a separate word. `\bballs?\b' matches `ball' or `balls' as a separate word.
`\b' matches at the beginning or end of the buffer regardless of what text appears next to it.

\B
matches the empty string, but not at the beginning or end of a word.

\<
matches the empty string, but only at the beginning of a word. `\<' matches at the beginning of the buffer only if a word-constituent character follows.

\>
matches the empty string, but only at the end of a word. `\>' matches at the end of the buffer only if the contents end with a word-constituent character.

\w
matches any word-constituent character. The syntax table determines which characters these are. See section AD.6 The Syntax Table.

\W
matches any character that is not a word-constituent.

\sc
matches any character whose syntax is c. Here c is a character that designates a particular syntax class: thus, `w' for word constituent, `-' or ` ' for whitespace, `.' for ordinary punctuation, etc. See section AD.6 The Syntax Table.

\Sc
matches any character whose syntax is not c.

\cc
matches any character that belongs to the category c. For example, `\cc' matches Chinese characters, `\cg' matches Greek characters, etc. For the description of the known categories, type M-x describe-categories RET.

\Cc
matches any character that does not belong to category c.
The constructs that pertain to words and syntax are controlled by the setting of the syntax table (see section AD.6 The Syntax Table).

Here is a complicated regexp, stored in sentence-end and used by Emacs to recognize the end of a sentence together with any whitespace that follows. We show its Lisp syntax to distinguish the spaces from the tab characters. In Lisp syntax, the string constant begins and ends with a double-quote. `\"' stands for a double-quote as part of the regexp, `\\' for a backslash as part of the regexp, `\t' for a tab, and `\n' for a newline.
"[.?!][]\"')]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
This contains four parts in succession: a character set matching period, `?', or `!'; a character set matching close-brackets, quotes, or parentheses, repeated zero or more times; a set of alternatives within backslash-parentheses that matches either end-of-line, a space at the end of a line, a tab, or two spaces; and a character set matching whitespace characters, repeated any number of times.

To enter the same regexp interactively, you would type TAB to enter a tab, and C-j to enter a newline. (When typed interactively, C-j should be preceded by a C-q, to prevent Emacs from running the command bound to a newline.) You would also type single backslashes as themselves, instead of doubling them for Lisp syntax.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.6 Searching and Case

Incremental searches in Emacs normally ignore the case of the text they are searching through, if you specify the text in lower case. Thus, if you specify searching for `foo', then `Foo' and `foo' are also considered a match. Regexps, and in particular character sets, are included: `[ab]' would match `a' or `A' or `b' or `B'.

An upper-case letter anywhere in the incremental search string makes the search case-sensitive. Thus, searching for `Foo' does not find `foo' or `FOO'. This applies to regular expression search as well as to string search. The effect ceases if you delete the upper-case letter from the search string.

Typing M-c within an incremental search toggles the case sensitivity of that search. The effect does not extend beyond the current incremental search to the next one, but it does override the effect of including an upper-case letter in the current search.

If you set the variable case-fold-search to nil, then all letters must match exactly, including case. This is a per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. See section AD.2.4 Local Variables. This variable applies to nonincremental searches also, including those performed by the replace commands (see section K.7 Replacement Commands) and the minibuffer history matching commands (see section E.4 Minibuffer History).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.7 Replacement Commands

Global search-and-replace operations are not needed often in Emacs, but they are available. In addition to the simple M-x replace-string command which is like that found in most editors, there is a M-x query-replace command which finds each occurrence of the pattern and asks you whether to replace it.

The replace commands normally operate on the text from point to the end of the buffer; however, in Transient Mark mode, when the mark is active, they operate on the region. The replace commands all replace one string (or regexp) with one replacement string. It is possible to perform several replacements in parallel using the command expand-region-abbrevs (see section X.3 Controlling Abbrev Expansion).

K.7.1 Unconditional Replacement

Replacing all matches for a string.

K.7.2 Regexp Replacement

Replacing all matches for a regexp.

K.7.3 Replace Commands and Case

How replacements preserve case of letters.

K.7.4 Query Replace

How to use querying.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.7.1 Unconditional Replacement

M-x replace-string RET string RET newstring RET
Replace every occurrence of string with newstring.
M-x replace-regexp RET regexp RET newstring RET
Replace every match for regexp with newstring.
To replace every instance of `foo' after point with `bar', use the command M-x replace-string with the two arguments `foo' and `bar'. Replacement happens only in the text after point, so if you want to cover the whole buffer you must go to the beginning first. All occurrences up to the end of the buffer are replaced; to limit replacement to part of the buffer, narrow to that part of the buffer before doing the replacement (see section AC.22 Narrowing). In Transient Mark mode, when the region is active, replacement is limited to the region (see section H.2 Transient Mark Mode).

When replace-string exits, it leaves point at the last occurrence replaced. It sets the mark to the prior position of point (where the replace-string command was issued); use C-u C-SPC to move back there.

A numeric argument restricts replacement to matches that are surrounded by word boundaries. The argument's value doesn't matter.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.7.2 Regexp Replacement

The M-x replace-string command replaces exact matches for a single string. The similar command M-x replace-regexp replaces any match for a specified pattern.

In replace-regexp, the newstring need not be constant: it can refer to all or part of what is matched by the regexp. `\&' in newstring stands for the entire match being replaced. `\d' in newstring, where d is a digit, stands for whatever matched the dth parenthesized grouping in regexp. To include a `\' in the text to replace with, you must enter `\\'. For example,
M-x replace-regexp RET c[ad]+r RET \&-safe RET
replaces (for example) `cadr' with `cadr-safe' and `cddr' with `cddr-safe'.
M-x replace-regexp RET \(c[ad]+r\)-safe RET \1 RET
performs the inverse transformation.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.7.3 Replace Commands and Case

If the first argument of a replace command is all lower case, the command ignores case while searching for occurrences to replace--provided case-fold-search is non-nil. If case-fold-search is set to nil, case is always significant in all searches.

In addition, when the newstring argument is all or partly lower case, replacement commands try to preserve the case pattern of each occurrence. Thus, the command
M-x replace-string RET foo RET bar RET
replaces a lower case `foo' with a lower case `bar', an all-caps `FOO' with `BAR', and a capitalized `Foo' with `Bar'. (These three alternatives--lower case, all caps, and capitalized, are the only ones that replace-string can distinguish.)

If upper-case letters are used in the replacement string, they remain upper case every time that text is inserted. If upper-case letters are used in the first argument, the second argument is always substituted exactly as given, with no case conversion. Likewise, if either case-replace or case-fold-search is set to nil, replacement is done without case conversion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.7.4 Query Replace

M-% string RET newstring RET

M-x query-replace RET string RET newstring RET
Replace some occurrences of string with newstring.
C-M-% regexp RET newstring RET

M-x query-replace-regexp RET regexp RET newstring RET
Replace some matches for regexp with newstring.
If you want to change only some of the occurrences of `foo' to `bar', not all of them, then you cannot use an ordinary replace-string. Instead, use M-% (query-replace). This command finds occurrences of `foo' one by one, displays each occurrence and asks you whether to replace it. Aside from querying, query-replace works just like replace-string. It preserves case, like replace-string, provided case-replace is non-nil, as it normally is. A numeric argument means consider only occurrences that are bounded by word-delimiter characters.

C-M-% performs regexp search and replace (query-replace-regexp).

The characters you can type when you are shown a match for the string or regexp are:

SPC
to replace the occurrence with newstring.

DEL
to skip to the next occurrence without replacing this one.

, (Comma)
to replace this occurrence and display the result. You are then asked for another input character to say what to do next. Since the replacement has already been made, DEL and SPC are equivalent in this situation; both move to the next occurrence.
You can type C-r at this point (see below) to alter the replaced text. You can also type C-x u to undo the replacement; this exits the query-replace, so if you want to do further replacement you must use C-x ESC ESC RET to restart (see section E.5 Repeating Minibuffer Commands).

RET
to exit without doing any more replacements.

. (Period)
to replace this occurrence and then exit without searching for more occurrences.

!
to replace all remaining occurrences without asking again.

^
to go back to the position of the previous occurrence (or what used to be an occurrence), in case you changed it by mistake. This works by popping the mark ring. Only one ^ in a row is meaningful, because only one previous replacement position is kept during query-replace.

C-r
to enter a recursive editing level, in case the occurrence needs to be edited rather than just replaced with newstring. When you are done, exit the recursive editing level with C-M-c to proceed to the next occurrence. See section AC.26 Recursive Editing Levels.

C-w
to delete the occurrence, and then enter a recursive editing level as in C-r. Use the recursive edit to insert text to replace the deleted occurrence of string. When done, exit the recursive editing level with C-M-c to proceed to the next occurrence.

e
to edit the replacement string in the minibuffer. When you exit the minibuffer by typing RET, the minibuffer contents replace the current occurrence of the pattern. They also become the new replacement string for any further occurrences.

C-l
to redisplay the screen. Then you must type another character to specify what to do with this occurrence.

C-h
to display a message summarizing these options. Then you must type another character to specify what to do with this occurrence.
Some other characters are aliases for the ones listed above: y, n and q are equivalent to SPC, DEL and RET.

Aside from this, any other character exits the query-replace, and is then reread as part of a key sequence. Thus, if you type C-k, it exits the query-replace and then kills to end of line.

To restart a query-replace once it is exited, use C-x ESC ESC, which repeats the query-replace because it used the minibuffer to read its arguments. See section C-x ESC ESC.

See also AB.9 Transforming File Names in Dired, for Dired commands to rename, copy, or link files by replacing regexp matches in file names.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

K.8 Other Search-and-Loop Commands

Here are some other commands that find matches for a regular expression. They all ignore case in matching, if the pattern contains no upper-case letters and case-fold-search is non-nil. Aside from occur, all operate on the text from point to the end of the buffer, or on the active region in Transient Mark mode.

M-x occur RET regexp RET
Display a list showing each line in the buffer that contains a match for regexp. To limit the search to part of the buffer, narrow to that part (see section AC.22 Narrowing). A numeric argument n specifies that n lines of context are to be displayed before and after each matching line.
The buffer `*Occur*' containing the output serves as a menu for finding the occurrences in their original context. Click Mouse-2 on an occurrence listed in `*Occur*', or position point there and type RET; this switches to the buffer that was searched and moves point to the original of the chosen occurrence.

M-x list-matching-lines
Synonym for M-x occur.

M-x how-many RET regexp RET
Print the number of matches for regexp that exist in the buffer after point. In Transient Mark mode, if the region is active, the command operates on the region instead.

M-x flush-lines RET regexp RET
Delete each line that contains a match for regexp, operating on the text after point. In Transient Mark mode, if the region is active, the command operates on the region instead.

M-x keep-lines RET regexp RET
Delete each line that does not contain a match for regexp, operating on the text after point. In Transient Mark mode, if the region is active, the command operates on the region instead.
You can also search multiple files under control of a tags table (see section W.2.6 Searching and Replacing with Tags Tables) or through Dired A command (see section AB.7 Operating on Files), or ask the grep program to do it (see section V.2 Searching with Grep under Emacs).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

L. Commands for Fixing Typos

In this chapter we describe the commands that are especially useful for the times when you catch a mistake in your text just after you have made it, or change your mind while composing text on the fly.

The most fundamental command for correcting erroneous editing is the undo command, C-x u or C-_. This command undoes a single command (usually), a part of a command (in the case of query-replace), or several consecutive self-inserting characters. Consecutive repetitions of C-_ or C-x u undo earlier and earlier changes, back to the limit of the undo information available. See section D.4 Undoing Changes, for more information.

L.1 Killing Your Mistakes

Commands to kill a batch of recently entered text.

L.2 Transposing Text

Exchanging two characters, words, lines, lists...

L.3 Case Conversion

Correcting case of last word entered.

L.4 Checking and Correcting Spelling

Apply spelling checker to a word, or a whole file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

L.1 Killing Your Mistakes

DEL
Delete last character (delete-backward-char).
M-DEL
Kill last word (backward-kill-word).
C-x DEL
Kill to beginning of sentence (backward-kill-sentence).
The DEL character (delete-backward-char) is the most important correction command. It deletes the character before point. When DEL follows a self-inserting character command, you can think of it as canceling that command. However, avoid the mistake of thinking of DEL as a general way to cancel a command!

When your mistake is longer than a couple of characters, it might be more convenient to use M-DEL or C-x DEL. M-DEL kills back to the start of the last word, and C-x DEL kills back to the start of the last sentence. C-x DEL is particularly useful when you change your mind about the phrasing of the text you are writing. M-DEL and C-x DEL save the killed text for C-y and M-y to retrieve. See section H.8 Yanking.

M-DEL is often useful even when you have typed only a few characters wrong, if you know you are confused in your typing and aren't sure exactly what you typed. At such a time, you cannot correct with DEL except by looking at the screen to see what you did. Often it requires less thought to kill the whole word and start again.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

L.2 Transposing Text

C-t
Transpose two characters (transpose-chars).
M-t
Transpose two words (transpose-words).
C-M-t
Transpose two balanced expressions (transpose-sexps).
C-x C-t
Transpose two lines (transpose-lines).
The common error of transposing two characters can be fixed, when they are adjacent, with the C-t command (transpose-chars). Normally, C-t transposes the two characters on either side of point. When given at the end of a line, rather than transposing the last character of the line with the newline, which would be useless, C-t transposes the last two characters on the line. So, if you catch your transposition error right away, you can fix it with just a C-t. If you don't catch it so fast, you must move the cursor back between the two transposed characters before you type C-t. If you transposed a space with the last character of the word before it, the word motion commands are a good way of getting there. Otherwise, a reverse search (C-r) is often the best way. See section K. Searching and Replacement.

M-t transposes the word before point with the word after point (transpose-words). It moves point forward over a word, dragging the word preceding or containing point forward as well. The punctuation characters between the words do not move. For example, `FOO, BAR' transposes into `BAR, FOO' rather than `BAR FOO,'.

C-M-t (transpose-sexps) is a similar command for transposing two expressions (see section U.4.1 Expressions with Balanced Parentheses), and C-x C-t (transpose-lines) exchanges lines. They work like M-t except as regards what units of text they transpose.

A numeric argument to a transpose command serves as a repeat count: it tells the transpose command to move the character (word, expression, line) before or containing point across several other characters (words, expressions, lines). For example, C-u 3 C-t moves the character before point forward across three other characters. It would change `f-!-oobar' into `oobf-!-ar'. This is equivalent to repeating C-t three times. C-u - 4 M-t moves the word before point backward across four words. C-u - C-M-t would cancel the effect of plain C-M-t.

A numeric argument of zero is assigned a special meaning (because otherwise a command with a repeat count of zero would do nothing): to transpose the character (word, expression, line) ending after point with the one ending after the mark.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

L.3 Case Conversion

M-- M-l
Convert last word to lower case. Note Meta-- is Meta-minus.
M-- M-u
Convert last word to all upper case.
M-- M-c
Convert last word to lower case with capital initial.
A very common error is to type words in the wrong case. Because of this, the word case-conversion commands M-l, M-u and M-c have a special feature when used with a negative argument: they do not move the cursor. As soon as you see you have mistyped the last word, you can simply case-convert it and go on typing. See section T.6 Case Conversion Commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

L.4 Checking and Correcting Spelling

This section describes the commands to check the spelling of a single word or of a portion of a buffer. These commands work with the spelling checker program Ispell, which is not part of Emacs. See section `Overview ispell' in The Ispell Manual.

M-x flyspell-mode
Enable Flyspell mode, which highlights all misspelled words.
M-$
Check and correct spelling of the word at point (ispell-word).
M-TAB
Complete the word before point based on the spelling dictionary (ispell-complete-word).
M-x ispell
Spell-check the active region or the current buffer.
M-x ispell-buffer
Check and correct spelling of each word in the buffer.
M-x ispell-region
Check and correct spelling of each word in the region.
M-x ispell-message
Check and correct spelling of each word in a draft mail message, excluding cited material.
M-x ispell-change-dictionary RET dict RET
Restart the Ispell process, using dict as the dictionary.
M-x ispell-kill-ispell
Kill the Ispell subprocess.
Flyspell mode is a fully-automatic way to check spelling as you edit in Emacs. It operates by checking words as you change or insert them. When it finds a word that it does not recognize, it highlights that word. This does not interfere with your editing, but when you see the highlighted word, you can move to it and fix it. Type M-x flyspell-mode to enable or disable this mode in the current buffer.

When Flyspell mode highlights a word as misspelled, you can click on it with Mouse-2 to display a menu of possible corrections and actions. You can also correct the word by editing it manually in any way you like.

The other Emacs spell-checking features check or look up words when you give an explicit command to do so. Checking all or part of the buffer is useful when you have text that was written outside of this Emacs session and might contain any number of misspellings.

To check the spelling of the word around or next to point, and optionally correct it as well, use the command M-$ (ispell-word). If the word is not correct, the command offers you various alternatives for what to do about it.

To check the entire current buffer, use M-x ispell-buffer. Use M-x ispell-region to check just the current region. To check spelling in an email message you are writing, use M-x ispell-message; that command checks the whole buffer, except for material that is indented or appears to be cited from other messages.

The M-x ispell command spell-checks the active region if the Transient Mark mode is on (see section H.2 Transient Mark Mode), otherwise it spell-checks the current buffer.

Each time these commands encounter an incorrect word, they ask you what to do. They display a list of alternatives, usually including several "near-misses"---words that are close to the word being checked. Then you must type a single-character response. Here are the valid responses:

SPC
Skip this word--continue to consider it incorrect, but don't change it here.

r new RET
Replace the word (just this time) with new.

R new RET
Replace the word with new, and do a query-replace so you can replace it elsewhere in the buffer if you wish.

digit
Replace the word (just this time) with one of the displayed near-misses. Each near-miss is listed with a digit; type that digit to select it.

a
Accept the incorrect word--treat it as correct, but only in this editing session.

A
Accept the incorrect word--treat it as correct, but only in this editing session and for this buffer.

i
Insert this word in your private dictionary file so that Ispell will consider it correct from now on, even in future sessions.

u
Insert the lower-case version of this word in your private dictionary file.

m
Like i, but you can also specify dictionary completion information.

l word RET
Look in the dictionary for words that match word. These words become the new list of "near-misses"; you can select one of them as the replacement by typing a digit. You can use `*' in word as a wildcard.

C-g
Quit interactive spell checking. You can restart it again afterward with C-u M-$.

X
Same as C-g.

x
Quit interactive spell checking and move point back to where it was when you started spell checking.

q
Quit interactive spell checking and kill the Ispell subprocess.

C-l
Refresh the screen.

C-z
This key has its normal command meaning (suspend Emacs or iconify this frame).
The command ispell-complete-word, which is bound to the key M-TAB in Text mode and related modes, shows a list of completions based on spelling correction. Insert the beginning of a word, and then type M-TAB; the command displays a completion list window. To choose one of the completions listed, click Mouse-2 on it, or move the cursor there in the completions window and type RET. See section T.7 Text Mode.

Once started, the Ispell subprocess continues to run (waiting for something to do), so that subsequent spell checking commands complete more quickly. If you want to get rid of the Ispell process, use M-x ispell-kill-ispell. This is not usually necessary, since the process uses no time except when you do spelling correction.

Ispell uses two dictionaries: the standard dictionary and your private dictionary. The variable ispell-dictionary specifies the file name of the standard dictionary to use. A value of nil says to use the default dictionary. The command M-x ispell-change-dictionary sets this variable and then restarts the Ispell subprocess, so that it will use a different dictionary.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M. File Handling

The operating system stores data permanently in named files, so most of the text you edit with Emacs comes from a file and is ultimately stored in a file.

To edit a file, you must tell Emacs to read the file and prepare a buffer containing a copy of the file's text. This is called visiting the file. Editing commands apply directly to text in the buffer; that is, to the copy inside Emacs. Your changes appear in the file itself only when you save the buffer back into the file.

In addition to visiting and saving files, Emacs can delete, copy, rename, and append to files, keep multiple versions of them, and operate on file directories.

M.1 File Names

How to type and edit file-name arguments.

M.2 Visiting Files

Visiting a file prepares Emacs to edit the file.

M.3 Saving Files

Saving makes your changes permanent.

M.4 Reverting a Buffer

Reverting cancels all the changes not saved.

M.5 Auto-Saving: Protection Against Disasters

Auto Save periodically protects against loss of data.

M.6 File Name Aliases

Handling multiple names for one file.

M.7 Version Control

Version control systems (RCS, CVS and SCCS).

M.8 File Directories

Creating, deleting, and listing file directories.

M.9 Comparing Files

Finding where two files differ.

M.10 Miscellaneous File Operations

Other things you can do on files.

M.11 Accessing Compressed Files

Accessing compressed files.

M.12 File Archives

Operating on tar, zip, jar etc. archive files.

M.13 Remote Files

Accessing files on other sites.

M.14 Quoted File Names

Quoting special characters in file names.

M.15 File Name Cache

Completion against a list of files you often use.

M.16 Convenience Features for Finding Files

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.1 File Names

Most Emacs commands that operate on a file require you to specify the file name. (Saving and reverting are exceptions; the buffer knows which file name to use for them.) You enter the file name using the minibuffer (see section E. The Minibuffer). Completion is available (see section E.3 Completion) to make it easier to specify long file names. When completing file names, Emacs ignores those whose file-name extensions appear in the variable completion-ignored-extensions; see E.3.4 Completion Options.

For most operations, there is a default file name which is used if you type just RET to enter an empty argument. Normally the default file name is the name of the file visited in the current buffer; this makes it easy to operate on that file with any of the Emacs file commands.

Each buffer has a default directory which is normally the same as the directory of the file visited in that buffer. When you enter a file name without a directory, the default directory is used. If you specify a directory in a relative fashion, with a name that does not start with a slash, it is interpreted with respect to the default directory. The default directory is kept in the variable default-directory, which has a separate value in every buffer.

For example, if the default file name is `/u/rms/gnu/gnu.tasks' then the default directory is `/u/rms/gnu/'. If you type just `foo', which does not specify a directory, it is short for `/u/rms/gnu/foo'. `../.login' would stand for `/u/rms/.login'. `new/foo' would stand for the file name `/u/rms/gnu/new/foo'.

The command M-x pwd displays the current buffer's default directory, and the command M-x cd sets it (to a value read using the minibuffer). A buffer's default directory changes only when the cd command is used. A file-visiting buffer's default directory is initialized to the directory of the file that is visited in that buffer. If you create a buffer with C-x b, its default directory is copied from that of the buffer that was current at the time.

The default directory actually appears in the minibuffer when the minibuffer becomes active to read a file name. This serves two purposes: it shows you what the default is, so that you can type a relative file name and know with certainty what it will mean, and it allows you to edit the default to specify a different directory. This insertion of the default directory is inhibited if the variable insert-default-directory is set to nil.

Note that it is legitimate to type an absolute file name after you enter the minibuffer, ignoring the presence of the default directory name as part of the text. The final minibuffer contents may look invalid, but that is not so. For example, if the minibuffer starts out with `/usr/tmp/' and you add `/x1/rms/foo', you get `/usr/tmp//x1/rms/foo'; but Emacs ignores everything through the first slash in the double slash; the result is `/x1/rms/foo'. See section E.1 Minibuffers for File Names.

`$' in a file name is used to substitute environment variables. For example, if you have used the shell command export FOO=rms/hacks to set up an environment variable named FOO, then you can use `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for `/u/rms/hacks/test.c'. The environment variable name consists of all the alphanumeric characters after the `$'; alternatively, it may be enclosed in braces after the `$'. Note that shell commands to set environment variables affect Emacs only if done before Emacs is started.

You can use the `~/' in a file name to mean your home directory, or `~user-id/' to mean the home directory of a user whose login name is user-id. (On DOS and Windows systems, where a user doesn't have a home directory, Emacs substitutes `~/' with the value of the environment variable HOME; see AE.5.1 General Variables.)

To access a file with `$' in its name, type `$$'. This pair is converted to a single `$' at the same time as variable substitution is performed for a single `$'. Alternatively, quote the whole file name with `/:' (see section M.14 Quoted File Names). File names which begin with a literal `~' should also be quoted with `/:'.

The Lisp function that performs the substitution is called substitute-in-file-name. The substitution is performed only on file names read as such using the minibuffer.

You can include non-ASCII characters in file names if you set the variable file-name-coding-system to a non-nil value. See section Q.9 Specifying a Coding System.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.2 Visiting Files

C-x C-f
Visit a file (find-file).
C-x C-r
Visit a file for viewing, without allowing changes to it (find-file-read-only).
C-x C-v
Visit a different file instead of the one visited last (find-alternate-file).
C-x 4 f
Visit a file, in another window (find-file-other-window). Don't alter what is displayed in the selected window.
C-x 5 f
Visit a file, in a new frame (find-file-other-frame). Don't alter what is displayed in the selected frame.
M-x find-file-literally
Visit a file with no conversion of the contents.
Visiting a file means copying its contents into an Emacs buffer so you can edit them. Emacs makes a new buffer for each file that you visit. We often say that this buffer "is visiting" that file, or that the buffer's "visited file" is that file. Emacs constructs the buffer name from the file name by throwing away the directory, keeping just the name proper. For example, a file named `/usr/rms/emacs.tex' would get a buffer named `emacs.tex'. If there is already a buffer with that name, Emacs constructs a unique name--the normal method is to append `<2>', `<3>', and so on, but you can select other methods (see section N.7.1 Making Buffer Names Unique).

Each window's mode line shows the name of the buffer that is being displayed in that window, so you can always tell what buffer you are editing.

The changes you make with editing commands are made in the Emacs buffer. They do not take effect in the file that you visited, or any place permanent, until you save the buffer. Saving the buffer means that Emacs writes the current contents of the buffer into its visited file. See section M.3 Saving Files.

If a buffer contains changes that have not been saved, we say the buffer is modified. This is important because it implies that some changes will be lost if the buffer is not saved. The mode line displays two stars near the left margin to indicate that the buffer is modified.

To visit a file, use the command C-x C-f (find-file). Follow the command with the name of the file you wish to visit, terminated by a RET.

The file name is read using the minibuffer (see section E. The Minibuffer), with defaulting and completion in the standard manner (see section M.1 File Names). While in the minibuffer, you can abort C-x C-f by typing C-g. File-name completion ignores certain filenames; for more about this, see E.3.4 Completion Options.

When Emacs is built with a suitable GUI toolkit, it pops up the standard File Selection dialog of that toolkit instead of prompting for the file name in the minibuffer. On Unix and GNU/Linux platforms, Emacs does that when built with LessTif and Motif toolkits; on MS-Windows, the GUI version does that by default.

Your confirmation that C-x C-f has completed successfully is the appearance of new text on the screen and a new buffer name in the mode line. If the specified file does not exist and could not be created, or cannot be read, then you get an error, with an error message displayed in the echo area.

If you visit a file that is already in Emacs, C-x C-f does not make another copy. It selects the existing buffer containing that file. However, before doing so, it checks that the file itself has not changed since you visited or saved it last. If the file has changed, a warning message is shown. See section Simultaneous Editing.

Since Emacs reads the visited file in its entirety, files whose size is larger than the maximum Emacs buffer size (see section N. Using Multiple Buffers) cannot be visited; if you try, Emacs will display an error message saying that the maximum buffer size has been exceeded.

What if you want to create a new file? Just visit it. Emacs displays `(New file)' in the echo area, but in other respects behaves as if you had visited an existing empty file. If you make any changes and save them, the file is created.

Emacs recognizes from the contents of a file which convention it uses to separate lines--newline (used on GNU/Linux and on Unix), carriage-return linefeed (used on Microsoft systems), or just carriage-return (used on the Macintosh)---and automatically converts the contents to the normal Emacs convention, which is that the newline character separates lines. This is a part of the general feature of coding system conversion (see section Q.7 Coding Systems), and makes it possible to edit files imported from different operating systems with equal convenience. If you change the text and save the file, Emacs performs the inverse conversion, changing newlines back into carriage-return linefeed or just carriage-return if appropriate.

If the file you specify is actually a directory, C-x C-f invokes Dired, the Emacs directory browser, so that you can "edit" the contents of the directory (see section AB. Dired, the Directory Editor). Dired is a convenient way to delete, look at, or operate on the files in the directory. However, if the variable find-file-run-dired is nil, then it is an error to try to visit a directory.

Files which are actually collections of other files, or file archives, are visited in special modes which invoke a Dired-like environment to allow operations on archive members. See section M.12 File Archives, for more about these features.

If the file name you specify contains shell-style wildcard characters, Emacs visits all the files that match it. Wildcards include `?', `*', and `[...]' sequences. See section M.14 Quoted File Names, for information on how to visit a file whose name actually contains wildcard characters. You can disable the wildcard feature by customizing find-file-wildcards.

If you visit a file that the operating system won't let you modify, Emacs makes the buffer read-only, so that you won't go ahead and make changes that you'll have trouble saving afterward. You can make the buffer writable with C-x C-q (vc-toggle-read-only). See section N.3 Miscellaneous Buffer Operations.

Occasionally you might want to visit a file as read-only in order to protect yourself from entering changes accidentally; do so by visiting the file with the command C-x C-r (find-file-read-only).

If you visit a nonexistent file unintentionally (because you typed the wrong file name), use the C-x C-v command (find-alternate-file) to visit the file you really wanted. C-x C-v is similar to C-x C-f, but it kills the current buffer (after first offering to save it if it is modified). When C-x C-v reads the file name to visit, it inserts the entire default file name in the buffer, with point just after the directory part; this is convenient if you made a slight error in typing the name.

If you find a file which exists but cannot be read, C-x C-f signals an error.

C-x 4 f (find-file-other-window) is like C-x C-f except that the buffer containing the specified file is selected in another window. The window that was selected before C-x 4 f continues to show the same buffer it was already showing. If this command is used when only one window is being displayed, that window is split in two, with one window showing the same buffer as before, and the other one showing the newly requested file. See section O. Multiple Windows.

C-x 5 f (find-file-other-frame) is similar, but opens a new frame, or makes visible any existing frame showing the file you seek. This feature is available only when you are using a window system. See section P. Frames and X Windows.

If you wish to edit a file as a sequence of ASCII characters with no special encoding or conversion, use the M-x find-file-literally command. It visits a file, like C-x C-f, but does not do format conversion (see section T.11 Editing Formatted Text), character code conversion (see section Q.7 Coding Systems), or automatic uncompression (see section M.11 Accessing Compressed Files), and does not add a final newline because of require-final-newline. If you already have visited the same file in the usual (non-literal) manner, this command asks you whether to visit it literally instead.

Two special hook variables allow extensions to modify the operation of visiting files. Visiting a file that does not exist runs the functions in the list find-file-not-found-hooks; this variable holds a list of functions, and the functions are called one by one (with no arguments) until one of them returns non-nil. This is not a normal hook, and the name ends in `-hooks' rather than `-hook' to indicate that fact.

Successful visiting of any file, whether existing or not, calls the functions in the list find-file-hooks, with no arguments. This variable is really a normal hook, but it has an abnormal name for historical compatibility. In the case of a nonexistent file, the find-file-not-found-hooks are run first. See section AD.2.3 Hooks.

There are several ways to specify automatically the major mode for editing the file (see section R.1 How Major Modes are Chosen), and to specify local variables defined for that file (see section AD.2.5 Local Variables in Files).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.3 Saving Files

Saving a buffer in Emacs means writing its contents back into the file that was visited in the buffer.

C-x C-s
Save the current buffer in its visited file on disk (save-buffer).
C-x s
Save any or all buffers in their visited files (save-some-buffers).
M-~
Forget that the current buffer has been changed (not-modified). With prefix argument (C-u), mark the current buffer as changed.
C-x C-w
Save the current buffer as a specified file name (write-file).
M-x set-visited-file-name
Change the file name under which the current buffer will be saved.
When you wish to save the file and make your changes permanent, type C-x C-s (save-buffer). After saving is finished, C-x C-s displays a message like this:
Wrote /u/rms/gnu/gnu.tasks
If the selected buffer is not modified (no changes have been made in it since the buffer was created or last saved), saving is not really done, because it would have no effect. Instead, C-x C-s displays a message like this in the echo area:
(No changes need to be saved)
The command C-x s (save-some-buffers) offers to save any or all modified buffers. It asks you what to do with each buffer. The possible responses are analogous to those of query-replace:

y
Save this buffer and ask about the rest of the buffers.
n
Don't save this buffer, but ask about the rest of the buffers.
!
Save this buffer and all the rest with no more questions.
RET
Terminate save-some-buffers without any more saving.
.
Save this buffer, then exit save-some-buffers without even asking about other buffers.
C-r
View the buffer that you are currently being asked about. When you exit View mode, you get back to save-some-buffers, which asks the question again.
C-h
Display a help message about these options.
C-x C-c, the key sequence to exit Emacs, invokes save-some-buffers and therefore asks the same questions.

If you have changed a buffer but you do not want to save the changes, you should take some action to prevent it. Otherwise, each time you use C-x s or C-x C-c, you are liable to save this buffer by mistake. One thing you can do is type M-~ (not-modified), which clears out the indication that the buffer is modified. If you do this, none of the save commands will believe that the buffer needs to be saved. (`~' is often used as a mathematical symbol for `not'; thus M-~ is `not', metafied.) You could also use set-visited-file-name (see below) to mark the buffer as visiting a different file name, one which is not in use for anything important. Alternatively, you can cancel all the changes made since the file was visited or saved, by reading the text from the file again. This is called reverting. See section M.4 Reverting a Buffer. You could also undo all the changes by repeating the undo command C-x u until you have undone all the changes; but reverting is easier.

M-x set-visited-file-name alters the name of the file that the current buffer is visiting. It reads the new file name using the minibuffer. Then it marks the buffer as visiting that file name, and changes the buffer name correspondingly. set-visited-file-name does not save the buffer in the newly visited file; it just alters the records inside Emacs in case you do save later. It also marks the buffer as "modified" so that C-x C-s in that buffer will save.

If you wish to mark the buffer as visiting a different file and save it right away, use C-x C-w (write-file). It is precisely equivalent to set-visited-file-name followed by C-x C-s. C-x C-s used on a buffer that is not visiting a file has the same effect as C-x C-w; that is, it reads a file name, marks the buffer as visiting that file, and saves it there. The default file name in a buffer that is not visiting a file is made by combining the buffer name with the buffer's default directory (see section M.1 File Names).

If the new file name implies a major mode, then C-x C-w switches to that major mode, in most cases. The command set-visited-file-name also does this. See section R.1 How Major Modes are Chosen.

If Emacs is about to save a file and sees that the date of the latest version on disk does not match what Emacs last read or wrote, Emacs notifies you of this fact, because it probably indicates a problem caused by simultaneous editing and requires your immediate attention. See section Simultaneous Editing.

If the value of the variable require-final-newline is t, Emacs silently puts a newline at the end of any file that doesn't already end in one, every time a file is saved or written. If the value is nil, Emacs leaves the end of the file unchanged; if it's neither nil nor t, Emacs asks you whether to add a newline. The default is nil.

M.3.1 Backup Files

How Emacs saves the old version of your file.

M.3.2 Protection against Simultaneous Editing

How Emacs protects against simultaneous editing of one file by two users.

M.3.3 Shadowing Files

Copying files to "shadows" automatically.

M.3.4 Updating Time Stamps Automatically

Emacs can update time stamps on saved files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.3.1 Backup Files

On most operating systems, rewriting a file automatically destroys all record of what the file used to contain. Thus, saving a file from Emacs throws away the old contents of the file--or it would, except that Emacs carefully copies the old contents to another file, called the backup file, before actually saving.

For most files, the variable make-backup-files determines whether to make backup files. On most operating systems, its default value is t, so that Emacs does write backup files.

For files managed by a version control system (see section M.7 Version Control), the variable vc-make-backup-files determines whether to make backup files. By default it is nil, since backup files are redundant when you store all the previous versions in a version control system. See section M.7.10.1 General Options.

The default value of the backup-enable-predicate variable prevents backup files being written for files in the directories used for temporary files, specified by temporary-file-directory or small-temporary-file-directory.

At your option, Emacs can keep either a single backup file or a series of numbered backup files for each file that you edit.

Emacs makes a backup for a file only the first time the file is saved from one buffer. No matter how many times you save a file, its backup file continues to contain the contents from before the file was visited. Normally this means that the backup file contains the contents from before the current editing session; however, if you kill the buffer and then visit the file again, a new backup file will be made by the next save.

You can also explicitly request making another backup file from a buffer even though it has already been saved at least once. If you save the buffer with C-u C-x C-s, the version thus saved will be made into a backup file if you save the buffer again. C-u C-u C-x C-s saves the buffer, but first makes the previous file contents into a new backup file. C-u C-u C-u C-x C-s does both things: it makes a backup from the previous contents, and arranges to make another from the newly saved contents if you save again.

M.3.1.1 Single or Numbered Backups

How backup files are named; choosing single or numbered backup files.

M.3.1.2 Automatic Deletion of Backups

Emacs deletes excess numbered backups.

M.3.1.3 Copying vs. Renaming

Backups can be made by copying or renaming.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.3.1.1 Single or Numbered Backups

If you choose to have a single backup file (this is the default), the backup file's name is normally constructed by appending `~' to the file name being edited; thus, the backup file for `eval.c' would be `eval.c~'.

You can change this behavior by defining the variable make-backup-file-name-function to a suitable function. Alternatively you can customize the variable backup-directory-alist to specify that files matching certain patterns should be backed up in specific directories.

A typical use is to add an element ("." . dir) to make all backups in the directory with absolute name dir; Emacs modifies the backup file names to avoid clashes between files with the same names originating in different directories. Alternatively, adding, say, ("." . ".~") would make backups in the invisible subdirectory `.~' of the original file's directory. Emacs creates the directory, if necessary, to make the backup.

If access control stops Emacs from writing backup files under the usual names, it writes the backup file as `%backup%~' in your home directory. Only one such file can exist, so only the most recently made such backup is available.

If you choose to have a series of numbered backup files, backup file names contain `.~', the number, and another `~' after the original file name. Thus, the backup files of `eval.c' would be called `eval.c.~1~', `eval.c.~2~', and so on, all the way through names like `eval.c.~259~' and beyond. The variable backup-directory-alist applies to numbered backups just as usual.

The choice of single backup or numbered backups is controlled by the variable version-control. Its possible values are

t
Make numbered backups.
nil
Make numbered backups for files that have numbered backups already. Otherwise, make single backups.
never
Never make numbered backups; always make single backups.
You can set version-control locally in an individual buffer to control the making of backups for that buffer's file. For example, Rmail mode locally sets version-control to never to make sure that there is only one backup for an Rmail file. See section AD.2.4 Local Variables.

If you set the environment variable VERSION_CONTROL, to tell various GNU utilities what to do with backup files, Emacs also obeys the environment variable by setting the Lisp variable version-control accordingly at startup. If the environment variable's value is `t' or `numbered', then version-control becomes t; if the value is `nil' or `existing', then version-control becomes nil; if it is `never' or `simple', then version-control becomes never.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.3.1.2 Automatic Deletion of Backups

To prevent excessive consumption of disk space, Emacs can delete numbered backup versions automatically. Generally Emacs keeps the first few backups and the latest few backups, deleting any in between. This happens every time a new backup is made.

The two variables kept-old-versions and kept-new-versions control this deletion. Their values are, respectively, the number of oldest (lowest-numbered) backups to keep and the number of newest (highest-numbered) ones to keep, each time a new backup is made. The backups in the middle (excluding those oldest and newest) are the excess middle versions--those backups are deleted. These variables' values are used when it is time to delete excess versions, just after a new backup version is made; the newly made backup is included in the count in kept-new-versions. By default, both variables are 2.

If delete-old-versions is non-nil, Emacs deletes the excess backup files silently. If it is nil, the default, Emacs asks you whether it should delete the excess backup versions.

Dired's . (Period) command can also be used to delete old versions. See section AB.3 Deleting Files with Dired.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.3.1.3 Copying vs. Renaming

Backup files can be made by copying the old file or by renaming it. This makes a difference when the old file has multiple names (hard links). If the old file is renamed into the backup file, then the alternate names become names for the backup file. If the old file is copied instead, then the alternate names remain names for the file that you are editing, and the contents accessed by those names will be the new contents.

The method of making a backup file may also affect the file's owner and group. If copying is used, these do not change. If renaming is used, you become the file's owner, and the file's group becomes the default (different operating systems have different defaults for the group).

Having the owner change is usually a good idea, because then the owner always shows who last edited the file. Also, the owners of the backups show who produced those versions. Occasionally there is a file whose owner should not change; it is a good idea for such files to contain local variable lists to set backup-by-copying-when-mismatch locally (see section AD.2.5 Local Variables in Files).

The choice of renaming or copying is controlled by four variables. Renaming is the default choice. If the variable backup-by-copying is non-nil, copying is used. Otherwise, if the variable backup-by-copying-when-linked is non-nil, then copying is used for files that have multiple names, but renaming may still be used when the file being edited has only one name. If the variable backup-by-copying-when-mismatch is non-nil, then copying is used if renaming would cause the file's owner or group to change. backup-by-copying-when-mismatch is t by default if you start Emacs as the superuser. The fourth variable, backup-by-copying-when-privileged-mismatch, gives the highest numeric user-id for which backup-by-copying-when-mismatch will be forced on. This is useful when low-numbered user-ids are assigned to special system users, such as root, bin, daemon, etc., which must maintain ownership of files.

When a file is managed with a version control system (see section M.7 Version Control), Emacs does not normally make backups in the usual way for that file. But check-in and check-out are similar in some ways to making backups. One unfortunate similarity is that these operations typically break hard links, disconnecting the file name you visited from any alternate names for the same file. This has nothing to do with Emacs--the version control system does it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.3.2 Protection against Simultaneous Editing

Simultaneous editing occurs when two users visit the same file, both make changes, and then both save them. If nobody were informed that this was happening, whichever user saved first would later find that his changes were lost.

On some systems, Emacs notices immediately when the second user starts to change the file, and issues an immediate warning. On all systems, Emacs checks when you save the file, and warns if you are about to overwrite another user's changes. You can prevent loss of the other user's work by taking the proper corrective action instead of saving the file.

When you make the first modification in an Emacs buffer that is visiting a file, Emacs records that the file is locked by you. (It does this by creating a symbolic link in the same directory with a different name.) Emacs removes the lock when you save the changes. The idea is that the file is locked whenever an Emacs buffer visiting it has unsaved changes.

If you begin to modify the buffer while the visited file is locked by someone else, this constitutes a collision. When Emacs detects a collision, it asks you what to do, by calling the Lisp function ask-user-about-lock. You can redefine this function for the sake of customization. The standard definition of this function asks you a question and accepts three possible answers:

s
Steal the lock. Whoever was already changing the file loses the lock, and you gain the lock.
p
Proceed. Go ahead and edit the file despite its being locked by someone else.
q
Quit. This causes an error (file-locked), and the buffer contents remain unchanged--the modification you were trying to make does not actually take place.
Note that locking works on the basis of a file name; if a file has multiple names, Emacs does not realize that the two names are the same file and cannot prevent two users from editing it simultaneously under different names. However, basing locking on names means that Emacs can interlock the editing of new files that will not really exist until they are saved.

Some systems are not configured to allow Emacs to make locks, and there are cases where lock files cannot be written. In these cases, Emacs cannot detect trouble in advance, but it still can detect the collision when you try to save a file and overwrite someone else's changes.

If Emacs or the operating system crashes, this may leave behind lock files which are stale, so you may occasionally get warnings about spurious collisions. When you determine that the collision is spurious, just use p to tell Emacs to go ahead anyway.

Every time Emacs saves a buffer, it first checks the last-modification date of the existing file on disk to verify that it has not changed since the file was last visited or saved. If the date does not match, it implies that changes were made in the file in some other way, and these changes are about to be lost if Emacs actually does save. To prevent this, Emacs displays a warning message and asks for confirmation before saving. Occasionally you will know why the file was changed and know that it does not matter; then you can answer yes and proceed. Otherwise, you should cancel the save with C-g and investigate the situation.

The first thing you should do when notified that simultaneous editing has already taken place is to list the directory with C-u C-x C-d (see section M.8 File Directories). This shows the file's current author. You should attempt to contact him to warn him not to continue editing. Often the next step is to save the contents of your Emacs buffer under a different name, and use diff to compare the two files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.3.3 Shadowing Files

M-x shadow-initialize
Set up file shadowing.
M-x shadow-define-literal-group
Declare a single file to be shared between sites.
M-x shadow-define-regexp-group
Make all files that match each of a group of files be shared between hosts.
M-x shadow-define-cluster RET name RET
Define a shadow file cluster name.
M-x shadow-copy-files
Copy all pending shadow files.
M-x shadow-cancel
Cancel the instruction to shadow some files.
You can arrange to keep identical shadow copies of certain files in more than one place--possibly on different machines. To do this, first you must set up a shadow file group, which is a set of identically-named files shared between a list of sites. The file group is permanent and applies to further Emacs sessions as well as the current one. Once the group is set up, every time you exit Emacs, it will copy the file you edited to the other files in its group. You can also do the copying without exiting Emacs, by typing M-x shadow-copy-files.

To set up a shadow file group, use M-x shadow-define-literal-group or M-x shadow-define-regexp-group. See their documentation strings for further information.

Before copying a file to its shadows, Emacs asks for confirmation. You can answer "no" to bypass copying of this file, this time. If you want to cancel the shadowing permanently for a certain file, use M-x shadow-cancel to eliminate or change the shadow file group.

A shadow cluster is a group of hosts that share directories, so that copying to or from one of them is sufficient to update the file on all of them. Each shadow cluster has a name, and specifies the network address of a primary host (the one we copy files to), and a regular expression that matches the host names of all the other hosts in the cluster. You can define a shadow cluster with M-x shadow-define-cluster.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.3.4 Updating Time Stamps Automatically

You can arrange to put a time stamp in a file, so that it will be updated automatically each time you edit and save the file. The time stamp has to be in the first eight lines of the file, and you should insert it like this:
Time-stamp: <>
or like this:
Time-stamp: ""
Then add the hook function time-stamp to the hook write-file-hooks; that hook function will automatically update the time stamp, inserting the current date and time when you save the file. You can also use the command M-x time-stamp to update the time stamp manually. For other customizations, see the Custom group time-stamp. Note that non-numeric fields in the time stamp are formatted according to your locale setting (see section AE.5 Environment Variables).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.4 Reverting a Buffer

If you have made extensive changes to a file and then change your mind about them, you can get rid of them by reading in the previous version of the file. To do this, use M-x revert-buffer, which operates on the current buffer. Since reverting a buffer unintentionally could lose a lot of work, you must confirm this command with yes.

revert-buffer keeps point at the same distance (measured in characters) from the beginning of the file. If the file was edited only slightly, you will be at approximately the same piece of text after reverting as before. If you have made drastic changes, the same value of point in the old file may address a totally different piece of text.

Reverting marks the buffer as "not modified" until another change is made.

Some kinds of buffers whose contents reflect data bases other than files, such as Dired buffers, can also be reverted. For them, reverting means recalculating their contents from the appropriate data base. Buffers created explicitly with C-x b cannot be reverted; revert-buffer reports an error when asked to do so.

When you edit a file that changes automatically and frequently--for example, a log of output from a process that continues to run--it may be useful for Emacs to revert the file without querying you, whenever you visit the file again with C-x C-f.

To request this behavior, set the variable revert-without-query to a list of regular expressions. When a file name matches one of these regular expressions, find-file and revert-buffer will revert it automatically if it has changed--provided the buffer itself is not modified. (If you have edited the text, it would be wrong to discard your changes.)

You may find it useful to have Emacs revert files automatically when they change. Two minor modes are available to do this. In Global Auto-Revert mode, Emacs periodically checks all file buffers and reverts any when the corresponding file has changed. The local variant, Auto-Revert mode, applies only to buffers in which it was activated. Checking the files is done at intervals determined by the variable auto-revert-interval.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.5 Auto-Saving: Protection Against Disasters

Emacs saves all the visited files from time to time (based on counting your keystrokes) without being asked. This is called auto-saving. It prevents you from losing more than a limited amount of work if the system crashes.

When Emacs determines that it is time for auto-saving, each buffer is considered, and is auto-saved if auto-saving is turned on for it and it has been changed since the last time it was auto-saved. The message `Auto-saving...' is displayed in the echo area during auto-saving, if any files are actually auto-saved. Errors occurring during auto-saving are caught so that they do not interfere with the execution of commands you have been typing.

M.5.1 Auto-Save Files

The file where auto-saved changes are actually made until you save the file.

M.5.2 Controlling Auto-Saving

Controlling when and how often to auto-save.

M.5.3 Recovering Data from Auto-Saves

Recovering text from auto-save files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.5.1 Auto-Save Files

Auto-saving does not normally save in the files that you visited, because it can be very undesirable to save a program that is in an inconsistent state when you have made half of a planned change. Instead, auto-saving is done in a different file called the auto-save file, and the visited file is changed only when you request saving explicitly (such as with C-x C-s).

Normally, the auto-save file name is made by appending `#' to the front and rear of the visited file name. Thus, a buffer visiting file `foo.c' is auto-saved in a file `#foo.c#'. Most buffers that are not visiting files are auto-saved only if you request it explicitly; when they are auto-saved, the auto-save file name is made by appending `#%' to the front and `#' to the rear of buffer name. For example, the `*mail*' buffer in which you compose messages to be sent is auto-saved in a file named `#%*mail*#'. Auto-save file names are made this way unless you reprogram parts of Emacs to do something different (the functions make-auto-save-file-name and auto-save-file-name-p). The file name to be used for auto-saving in a buffer is calculated when auto-saving is turned on in that buffer.

When you delete a substantial part of the text in a large buffer, auto save turns off temporarily in that buffer. This is because if you deleted the text unintentionally, you might find the auto-save file more useful if it contains the deleted text. To reenable auto-saving after this happens, save the buffer with C-x C-s, or use C-u 1 M-x auto-save.

If you want auto-saving to be done in the visited file rather than in a separate auto-save file, set the variable auto-save-visited-file-name to a non-nil value. In this mode, there is no real difference between auto-saving and explicit saving.

A buffer's auto-save file is deleted when you save the buffer in its visited file. To inhibit this, set the variable delete-auto-save-files to nil. Changing the visited file name with C-x C-w or set-visited-file-name renames any auto-save file to go with the new visited name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.5.2 Controlling Auto-Saving

Each time you visit a file, auto-saving is turned on for that file's buffer if the variable auto-save-default is non-nil (but not in batch mode; see section C. Entering and Exiting Emacs). The default for this variable is t, so auto-saving is the usual practice for file-visiting buffers. Auto-saving can be turned on or off for any existing buffer with the command M-x auto-save-mode. Like other minor mode commands, M-x auto-save-mode turns auto-saving on with a positive argument, off with a zero or negative argument; with no argument, it toggles.

Emacs does auto-saving periodically based on counting how many characters you have typed since the last time auto-saving was done. The variable auto-save-interval specifies how many characters there are between auto-saves. By default, it is 300.

Auto-saving also takes place when you stop typing for a while. The variable auto-save-timeout says how many seconds Emacs should wait before it does an auto save (and perhaps also a garbage collection). (The actual time period is longer if the current buffer is long; this is a heuristic which aims to keep out of your way when you are editing long buffers, in which auto-save takes an appreciable amount of time.) Auto-saving during idle periods accomplishes two things: first, it makes sure all your work is saved if you go away from the terminal for a while; second, it may avoid some auto-saving while you are actually typing.

Emacs also does auto-saving whenever it gets a fatal error. This includes killing the Emacs job with a shell command such as `kill %emacs', or disconnecting a phone line or network connection.

You can request an auto-save explicitly with the command M-x do-auto-save.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.5.3 Recovering Data from Auto-Saves

You can use the contents of an auto-save file to recover from a loss of data with the command M-x recover-file RET file RET. This visits file and then (after your confirmation) restores the contents from its auto-save file `#file#'. You can then save with C-x C-s to put the recovered text into file itself. For example, to recover file `foo.c' from its auto-save file `#foo.c#', do:
M-x recover-file RET foo.c RET
yes RET
C-x C-s
Before asking for confirmation, M-x recover-file displays a directory listing describing the specified file and the auto-save file, so you can compare their sizes and dates. If the auto-save file is older, M-x recover-file does not offer to read it.

If Emacs or the computer crashes, you can recover all the files you were editing from their auto save files with the command M-x recover-session. This first shows you a list of recorded interrupted sessions. Move point to the one you choose, and type C-c C-c.

Then recover-session asks about each of the files that were being edited during that session, asking whether to recover that file. If you answer y, it calls recover-file, which works in its normal fashion. It shows the dates of the original file and its auto-save file, and asks once again whether to recover that file.

When recover-session is done, the files you've chosen to recover are present in Emacs buffers. You should then save them. Only this--saving them--updates the files themselves.

Emacs records interrupted sessions for later recovery in files named `~/.emacs.d/auto-save-list/.saves-pid-hostname'. The `~/.emacs.d/auto-save-list/.saves-' portion of these names comes from the value of auto-save-list-file-prefix. You can record sessions in a different place by customizing that variable. If you set auto-save-list-file-prefix to nil in your `.emacs' file, sessions are not recorded for recovery.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.6 File Name Aliases

Symbolic links and hard links both make it possible for several file names to refer to the same file. Hard links are alternate names that refer directly to the file; all the names are equally valid, and no one of them is preferred. By contrast, a symbolic link is a kind of defined alias: when `foo' is a symbolic link to `bar', you can use either name to refer to the file, but `bar' is the real name, while `foo' is just an alias. More complex cases occur when symbolic links point to directories.

If you visit two names for the same file, normally Emacs makes two different buffers, but it warns you about the situation.

Normally, if you visit a file which Emacs is already visiting under a different name, Emacs displays a message in the echo area and uses the existing buffer visiting that file. This can happen on systems that support symbolic links, or if you use a long file name on a system that truncates long file names. You can suppress the message by setting the variable find-file-suppress-same-file-warnings to a non-nil value. You can disable this feature entirely by setting the variable find-file-existing-other-name to nil: then if you visit the same file under two different names, you get a separate buffer for each file name.

If the variable find-file-visit-truename is non-nil, then the file name recorded for a buffer is the file's truename (made by replacing all symbolic links with their target names), rather than the name you specify. Setting find-file-visit-truename also implies the effect of find-file-existing-other-name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7 Version Control

Version control systems are packages that can record multiple versions of a source file, usually storing the unchanged parts of the file just once. Version control systems also record history information such as the creation time of each version, who created it, and a description of what was changed in that version.

The Emacs version control interface is called VC. Its commands work with three version control systems--RCS, CVS, and SCCS. The GNU project recommends RCS and CVS, which are free software and available from the Free Software Foundation. We also have free software to replace SCCS, known as CSSC; if you are using SCCS and don't want to make the incompatible change to RCS or CVS, you can switch to CSSC.

M.7.1 Introduction to Version Control

How version control works in general.

M.7.2 Version Control and the Mode Line

How the mode line shows version control status.

M.7.3 Basic Editing under Version Control

How to edit a file under version control.

M.7.4 Examining And Comparing Old Versions

Examining and comparing old versions.

M.7.5 The Secondary Commands of VC

The commands used a little less frequently.

M.7.6 Multiple Branches of a File

Multiple lines of development.

M.7.7 Remote Repositories

Efficient access to remote CVS servers.

M.7.8 Snapshots

Sets of file versions treated as a unit.

M.7.9 Miscellaneous Commands and Features of VC

Various other commands and features of VC.

M.7.10 Customizing VC

Variables that change VC's behavior.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.1 Introduction to Version Control

VC allows you to use a version control system from within Emacs, integrating the version control operations smoothly with editing. VC provides a uniform interface to version control, so that regardless of which version control system is in use, you can use it the same way.

This section provides a general overview of version control, and describes the version control systems that VC supports. You can skip this section if you are already familiar with the version control system you want to use.

M.7.1.1 Supported Version Control Systems

Supported version control back-end systems.

M.7.1.2 Concepts of Version Control

Words and concepts related to version control.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.1.1 Supported Version Control Systems

VC currently works with three different version control systems or "back ends": RCS, CVS, and SCCS.

RCS is a free version control system that is available from the Free Software Foundation. It is perhaps the most mature of the supported back ends, and the VC commands are conceptually closest to RCS. Almost everything you can do with RCS can be done through VC.

CVS is built on top of RCS, and extends the features of RCS, allowing for more sophisticated release management, and concurrent multi-user development. VC supports basic editing operations under CVS, but for some less common tasks you still need to call CVS from the command line. Note also that before using CVS you must set up a repository, which is a subject too complex to treat here.

SCCS is a proprietary but widely used version control system. In terms of capabilities, it is the weakest of the three that VC supports. VC compensates for certain features missing in SCCS (snapshots, for example) by implementing them itself, but some other VC features, such as multiple branches, are not available with SCCS. You should use SCCS only if for some reason you cannot use RCS.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.1.2 Concepts of Version Control

When a file is under version control, we also say that it is registered in the version control system. Each registered file has a corresponding master file which represents the file's present state plus its change history--enough to reconstruct the current version or any earlier version. Usually the master file also records a log entry for each version, describing in words what was changed in that version.

The file that is maintained under version control is sometimes called the work file corresponding to its master file. You edit the work file and make changes in it, as you would with an ordinary file. (With SCCS and RCS, you must lock the file before you start to edit it.) After you are done with a set of changes, you check the file in, which records the changes in the master file, along with a log entry for them.

With CVS, there are usually multiple work files corresponding to a single master file--often each user has his own copy. It is also possible to use RCS in this way, but this is not the usual way to use RCS.

A version control system typically has some mechanism to coordinate between users who want to change the same file. One method is locking (analogous to the locking that Emacs uses to detect simultaneous editing of a file, but distinct from it). The other method is to merge your changes with other people's changes when you check them in.

With version control locking, work files are normally read-only so that you cannot change them. You ask the version control system to make a work file writable for you by locking it; only one user can do this at any given time. When you check in your changes, that unlocks the file, making the work file read-only again. This allows other users to lock the file to make further changes. SCCS always uses locking, and RCS normally does.

The other alternative for RCS is to let each user modify the work file at any time. In this mode, locking is not required, but it is permitted; check-in is still the way to record a new version.

CVS normally allows each user to modify his own copy of the work file at any time, but requires merging with changes from other users at check-in time. However, CVS can also be set up to require locking. (see section M.7.10.3 Options specific for CVS).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.2 Version Control and the Mode Line

When you visit a file that is under version control, Emacs indicates this on the mode line. For example, `RCS-1.3' says that RCS is used for that file, and the current version is 1.3.

The character between the back-end name and the version number indicates the version control status of the file. `-' means that the work file is not locked (if locking is in use), or not modified (if locking is not in use). `:' indicates that the file is locked, or that it is modified. If the file is locked by some other user (for instance, `jim'), that is displayed as `RCS:jim:1.3'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.3 Basic Editing under Version Control

The principal VC command is an all-purpose command that performs either locking or check-in, depending on the situation.

C-x C-q

C-x v v
Perform the next logical version control operation on this file.
Strictly speaking, the command for this job is vc-next-action, bound to C-x v v. However, the normal meaning of C-x C-q is to make a read-only buffer writable, or vice versa; we have extended it to do the same job properly for files managed by version control, by performing the appropriate version control operations. When you type C-x C-q on a registered file, it acts like C-x v v.

The precise action of this command depends on the state of the file, and whether the version control system uses locking or not. SCCS and RCS normally use locking; CVS normally does not use locking.

M.7.3.1 Basic Version Control with Locking

RCS in its default mode, SCCS, and optionally CVS.

M.7.3.2 Basic Version Control without Locking

Without locking: default mode for CVS.

M.7.3.3 Advanced Control in C-x C-q

Advanced features available with a prefix argument.

M.7.3.4 Features of the Log Entry Buffer

Features available in log entry buffers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.3.1 Basic Version Control with Locking

If locking is used for the file (as with SCCS, and RCS in its default mode), C-x C-q can either lock a file or check it in:

If the file is not locked, C-x C-q locks it, and makes it writable so that you can change it.

If the file is locked by you, and contains changes, C-x C-q checks in the changes. In order to do this, it first reads the log entry for the new version. See section M.7.3.4 Features of the Log Entry Buffer.

If the file is locked by you, but you have not changed it since you locked it, C-x C-q releases the lock and makes the file read-only again.

If the file is locked by some other user, C-x C-q asks you whether you want to "steal the lock" from that user. If you say yes, the file becomes locked by you, but a message is sent to the person who had formerly locked the file, to inform him of what has happened.

These rules also apply when you use CVS in locking mode, except that there is no such thing as stealing a lock.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.3.2 Basic Version Control without Locking

When there is no locking--the default for CVS--work files are always writable; you do not need to do anything before you begin to edit a file. The status indicator on the mode line is `-' if the file is unmodified; it flips to `:' as soon as you save any changes in the work file.

Here is what C-x C-q does when using CVS:

If some other user has checked in changes into the master file, Emacs asks you whether you want to merge those changes into your own work file. You must do this before you can check in your own changes. (To pick up any recent changes from the master file without trying to commit your own changes, type C-x v m RET.) See section M.7.6.3 Merging Branches.

If there are no new changes in the master file, but you have made modifications in your work file, C-x C-q checks in your changes. In order to do this, it first reads the log entry for the new version. See section M.7.3.4 Features of the Log Entry Buffer.

If the file is not modified, the C-x C-q does nothing.

These rules also apply when you use RCS in the mode that does not require locking, except that automatic merging of changes from the master file is not implemented. Unfortunately, this means that nothing informs you if another user has checked in changes in the same file since you began editing it, and when this happens, his changes will be effectively removed when you check in your version (though they will remain in the master file, so they will not be entirely lost). You must therefore verify the current version is unchanged, before you check in your changes. We hope to eliminate this risk and provide automatic merging with RCS in a future Emacs version.

In addition, locking is possible with RCS even in this mode, although it is not required; C-x C-q with an unmodified file locks the file, just as it does with RCS in its normal (locking) mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.3.3 Advanced Control in C-x C-q

When you give a prefix argument to vc-next-action (C-u C-x C-q), it still performs the next logical version control operation, but accepts additional arguments to specify precisely how to do the operation.

If the file is modified (or locked), you can specify the version number to use for the new version that you check in. This is one way to create a new branch (see section M.7.6 Multiple Branches of a File).

If the file is not modified (and unlocked), you can specify the version to select; this lets you start working from an older version, or on another branch. If you do not enter any version, that takes you to the highest version on the current branch; therefore C-u C-x C-q RET is a convenient way to get the latest version of a file from the repository.

Instead of the version number, you can also specify the name of a version control system. This is useful when one file is being managed with two version control systems at the same time (see section M.7.7.2 Local Version Control).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.3.4 Features of the Log Entry Buffer

When you check in changes, C-x C-q first reads a log entry. It pops up a buffer called `*VC-Log*' for you to enter the log entry. When you are finished, type C-c C-c in the `*VC-Log*' buffer. That is when check-in really happens.

To abort check-in, just don't type C-c C-c in that buffer. You can switch buffers and do other editing. As long as you don't try to check in another file, the entry you were editing remains in the `*VC-Log*' buffer, and you can go back to that buffer at any time to complete the check-in.

If you change several source files for the same reason, it is often convenient to specify the same log entry for many of the files. To do this, use the history of previous log entries. The commands M-n, M-p, M-s and M-r for doing this work just like the minibuffer history commands (except that these versions are used outside the minibuffer).

Each time you check in a file, the log entry buffer is put into VC Log mode, which involves running two hooks: text-mode-hook and vc-log-mode-hook. See section AD.2.3 Hooks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.4 Examining And Comparing Old Versions

One of the convenient features of version control is the ability to examine any version of a file, or compare two versions.

C-x v ~ version RET
Examine version version of the visited file, in a buffer of its own.

C-x v =
Compare the current buffer contents with the latest checked-in version of the file.

C-u C-x v = file RET oldvers RET newvers RET
Compare the specified two versions of file.

C-x v g
Display the result of the CVS annotate command using colors.
To examine an old version in its entirety, visit the file and then type C-x v ~ version RET (vc-version-other-window). This puts the text of version version in a file named `filename.~version~', and visits it in its own buffer in a separate window. (In RCS, you can also select an old version and create a branch from it. See section M.7.6 Multiple Branches of a File.)

It is usually more convenient to compare two versions of the file, with the command C-x v = (vc-diff). Plain C-x v = compares the current buffer contents (saving them in the file if necessary) with the last checked-in version of the file. C-u C-x v =, with a numeric argument, reads a file name and two version numbers, then compares those versions of the specified file. Both forms display the output in a special buffer in another window.

You can specify a checked-in version by its number; an empty input specifies the current contents of the work file (which may be different from all the checked-in versions). You can also specify a snapshot name (see section M.7.8 Snapshots) instead of one or both version numbers.

If you supply a directory name instead of the name of a registered file, this command compares the two specified versions of all registered files in that directory and its subdirectories.

C-x v = works by running a variant of the diff utility designed to work with the version control system in use. When you invoke diff this way, in addition to the options specified by diff-switches (see section M.9 Comparing Files), it receives those specified by vc-diff-switches, plus those specified for the specific back end by vc-backend-diff-switches. For instance, when the version control back end is RCS, diff uses the options in vc-rcs-diff-switches. The `vc...diff-switches' variables are nil by default.

Unlike the M-x diff command, C-x v = does not try to locate the changes in the old and new versions. This is because normally one or both versions do not exist as files when you compare them; they exist only in the records of the master file. See section M.9 Comparing Files, for more information about M-x diff.

For CVS-controlled files, you can display the result of the CVS annotate command, using colors to enhance the visual appearance. Use the command M-x vc-annotate to do this. It creates a new buffer to display file's text, colored to show how old each part is. Text colored red is new, blue means old, and intermediate colors indicate intermediate ages. By default, the time scale is 360 days, so that everything more than one year old is shown in blue.

When you give a prefix argument to this command, it uses the minibuffer to read two arguments: which version number to display and annotate (instead of the current file contents), and a stretch factor for the time scale. A stretch factor of 0.1 means that the color range from red to blue spans the past 36 days instead of 360 days. A stretch factor greater than 1 means the color range spans more than a year.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.5 The Secondary Commands of VC

This section explains the secondary commands of VC; those that you might use once a day.

M.7.5.1 Registering a File for Version Control

Putting a file under version control.

M.7.5.2 VC Status Commands

Viewing the VC status of files.

M.7.5.3 Undoing Version Control Actions

Cancelling changes before or after check-in.

M.7.5.4 Dired under VC

Listing files managed by version control.

M.7.5.5 VC Dired Commands

Commands to use in a VC Dired buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.5.1 Registering a File for Version Control

You can put any file under version control by simply visiting it, and then typing C-x v i (vc-register).

C-x v i
Register the visited file for version control.
To register the file, Emacs must choose which version control system to use for it. If the file's directory already contains files registered in a version control system, Emacs uses that system. If there is more than one system in use for a directory, Emacs uses the one that appears first in vc-handled-backends (see section M.7.10 Customizing VC). On the other hand, if there are no files already registered, Emacs uses the first system from vc-handled-backends that could register the file--for example, you cannot register a file under CVS if its directory is not already part of a CVS tree.

With the default value of vc-handled-backends, this means that Emacs uses RCS if there are any files under RCS control, CVS if there are any files under CVS, SCCS if any files are under SCCS, or RCS as the ultimate default.

If locking is in use, C-x v i leaves the file unlocked and read-only. Type C-x C-q if you wish to start editing it. After registering a file with CVS, you must subsequently commit the initial version by typing C-x C-q.

The initial version number for a newly registered file is 1.1, by default. You can specify a different default by setting the variable vc-default-init-version, or you can give C-x v i a numeric argument; then it reads the initial version number for this particular file using the minibuffer.

If vc-initial-comment is non-nil, C-x v i reads an initial comment to describe the purpose of this source file. Reading the initial comment works like reading a log entry (see section M.7.3.4 Features of the Log Entry Buffer).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.5.2 VC Status Commands

C-x v l
Display version control state and change history.
To view the detailed version control status and history of a file, type C-x v l (vc-print-log). It displays the history of changes to the current file, including the text of the log entries. The output appears in a separate window.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.5.3 Undoing Version Control Actions

C-x v u
Revert the buffer and the file to the last checked-in version.

C-x v c
Remove the last-entered change from the master for the visited file. This undoes your last check-in.
If you want to discard your current set of changes and revert to the last version checked in, use C-x v u (vc-revert-buffer). This leaves the file unlocked; if locking is in use, you must first lock the file again before you change it again. C-x v u requires confirmation, unless it sees that you haven't made any changes since the last checked-in version.

C-x v u is also the command to unlock a file if you lock it and then decide not to change it.

To cancel a change that you already checked in, use C-x v c (vc-cancel-version). This command discards all record of the most recent checked-in version. C-x v c also offers to revert your work file and buffer to the previous version (the one that precedes the version that is deleted).

If you answer no, VC keeps your changes in the buffer, and locks the file. The no-revert option is useful when you have checked in a change and then discover a trivial error in it; you can cancel the erroneous check-in, fix the error, and check the file in again.

When C-x v c does not revert the buffer, it unexpands all version control headers in the buffer instead (see section M.7.9.3 Inserting Version Control Headers). This is because the buffer no longer corresponds to any existing version. If you check it in again, the check-in process will expand the headers properly for the new version number.

However, it is impossible to unexpand the RCS `$Log$' header automatically. If you use that header feature, you have to unexpand it by hand--by deleting the entry for the version that you just canceled.

Be careful when invoking C-x v c, as it is easy to lose a lot of work with it. To help you be careful, this command always requires confirmation with yes. Note also that this command is disabled under CVS, because canceling versions is very dangerous and discouraged with CVS.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.5.4 Dired under VC

The VC Dired Mode described here works with all the version control systems that VC supports. Another more powerful facility, designed specifically for CVS, is called PCL-CVS. See section `About PCL-CVS' in PCL-CVS -- The Emacs Front-End to CVS.

When you are working on a large program, it is often useful to find out which files have changed within an entire directory tree, or to view the status of all files under version control at once, and to perform version control operations on collections of files. You can use the command C-x v d (vc-directory) to make a directory listing that includes only files relevant for version control.

C-x v d creates a buffer which uses VC Dired Mode. This looks much like an ordinary Dired buffer (see section AB. Dired, the Directory Editor); however, normally it shows only the noteworthy files (those locked or not up-to-date). This is called terse display. If you set the variable vc-dired-terse-display to nil, then VC Dired shows all relevant files--those managed under version control, plus all subdirectories (full display). The command v t in a VC Dired buffer toggles between terse display and full display (see section M.7.5.5 VC Dired Commands).

By default, VC Dired produces a recursive listing of noteworthy or relevant files at or below the given directory. You can change this by setting the variable vc-dired-recurse to nil; then VC Dired shows only the files in the given directory.

The line for an individual file shows the version control state in the place of the hard link count, owner, group, and size of the file. If the file is unmodified, in sync with the master file, the version control state shown is blank. Otherwise it consists of text in parentheses. Under RCS and SCCS, the name of the user locking the file is shown; under CVS, an abbreviated version of the `cvs status' output is used. Here is an example using RCS:
  /home/jim/project:

  -rw-r--r-- (jim)      Apr  2 23:39 file1
  -r--r--r--            Apr  5 20:21 file2
The files `file1' and `file2' are under version control, `file1' is locked by user jim, and `file2' is unlocked.

Here is an example using CVS:
  /home/joe/develop:

  -rw-r--r-- (modified) Aug  2  1997 file1.c
  -rw-r--r--            Apr  4 20:09 file2.c
  -rw-r--r-- (merge)    Sep 13  1996 file3.c
Here `file1.c' is modified with respect to the repository, and `file2.c' is not. `file3.c' is modified, but other changes have also been checked in to the repository--you need to merge them with the work file before you can check it in.

When VC Dired displays subdirectories (in the "full" display mode), it omits some that should never contain any files under version control. By default, this includes Version Control subdirectories such as `RCS' and `CVS'; you can customize this by setting the variable vc-directory-exclusion-list.

You can fine-tune VC Dired's format by typing C-u C-x v d---as in ordinary Dired, that allows you to specify additional switches for the `ls' command.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.5.5 VC Dired Commands

All the usual Dired commands work normally in VC Dired mode, except for v, which is redefined as the version control prefix. You can invoke VC commands such as vc-diff and vc-print-log by typing v =, or v l, and so on. Most of these commands apply to the file name on the current line.

The command v v (vc-next-action) operates on all the marked files, so that you can lock or check in several files at once. If it operates on more than one file, it handles each file according to its current state; thus, it might lock one file, but check in another file. This could be confusing; it is up to you to avoid confusing behavior by marking a set of files that are in a similar state.

If any files call for check-in, v v reads a single log entry, then uses it for all the files being checked in. This is convenient for registering or checking in several files at once, as part of the same change.

You can toggle between terse display (only locked files, or files not up-to-date) and full display at any time by typing v t (vc-dired-toggle-terse-mode). There is also a special command * l (vc-dired-mark-locked), which marks all files currently locked (or, with CVS, all files not up-to-date). Thus, typing * l t k is another way to delete from the buffer all files except those currently locked.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.6 Multiple Branches of a File

One use of version control is to maintain multiple "current" versions of a file. For example, you might have different versions of a program in which you are gradually adding various unfinished new features. Each such independent line of development is called a branch. VC allows you to create branches, switch between different branches, and merge changes from one branch to another. Please note, however, that branches are only supported for RCS at the moment.

A file's main line of development is usually called the trunk. The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At any such version, you can start an independent branch. A branch starting at version 1.2 would have version number 1.2.1.1, and consecutive versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is a second branch also starting at version 1.2, it would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.

If you omit the final component of a version number, that is called a branch number. It refers to the highest existing version on that branch--the head version of that branch. The branches in the example above have branch numbers 1.2.1 and 1.2.2.

M.7.6.1 Switching between Branches

How to get to another existing branch.

M.7.6.2 Creating New Branches

How to start a new branch.

M.7.6.3 Merging Branches

Transferring changes between branches.

M.7.6.4 Multi-User Branching

Multiple users working at multiple branches in parallel.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.6.1 Switching between Branches

To switch between branches, type C-u C-x C-q and specify the version number you want to select. This version is then visited unlocked (write-protected), so you can examine it before locking it. Switching branches in this way is allowed only when the file is not locked.

You can omit the minor version number, thus giving only the branch number; this takes you to the head version on the chosen branch. If you only type RET, Emacs goes to the highest version on the trunk.

After you have switched to any branch (including the main branch), you stay on it for subsequent VC commands, until you explicitly select some other branch.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.6.2 Creating New Branches

To create a new branch from a head version (one that is the latest in the branch that contains it), first select that version if necessary, lock it with C-x C-q, and make whatever changes you want. Then, when you check in the changes, use C-u C-x C-q. This lets you specify the version number for the new version. You should specify a suitable branch number for a branch starting at the current version. For example, if the current version is 2.5, the branch number should be 2.5.1, 2.5.2, and so on, depending on the number of existing branches at that point.

To create a new branch at an older version (one that is no longer the head of a branch), first select that version (see section M.7.6.1 Switching between Branches), then lock it with C-x C-q. You'll be asked to confirm, when you lock the old version, that you really mean to create a new branch--if you say no, you'll be offered a chance to lock the latest version instead.

Then make your changes and type C-x C-q again to check in a new version. This automatically creates a new branch starting from the selected version. You need not specially request a new branch, because that's the only way to add a new version at a point that is not the head of a branch.

After the branch is created, you "stay" on it. That means that subsequent check-ins create new versions on that branch. To leave the branch, you must explicitly select a different version with C-u C-x C-q. To transfer changes from one branch to another, use the merge command, described in the next section.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.6.3 Merging Branches

When you have finished the changes on a certain branch, you will often want to incorporate them into the file's main line of development (the trunk). This is not a trivial operation, because development might also have proceeded on the trunk, so that you must merge the changes into a file that has already been changed otherwise. VC allows you to do this (and other things) with the vc-merge command.

C-x v m (vc-merge)
Merge changes into the work file.
C-x v m (vc-merge) takes a set of changes and merges it into the current version of the work file. It firsts asks you in the minibuffer where the changes should come from. If you just type RET, Emacs merges any changes that were made on the same branch since you checked the file out (we call this merging the news). This is the common way to pick up recent changes from the repository, regardless of whether you have already changed the file yourself.

You can also enter a branch number or a pair of version numbers in the minibuffer. Then C-x v m finds the changes from that branch, or the differences between the two versions you specified, and merges them into the current version of the current file.

As an example, suppose that you have finished a certain feature on branch 1.3.1. In the meantime, development on the trunk has proceeded to version 1.5. To merge the changes from the branch to the trunk, first go to the head version of the trunk, by typing C-u C-x C-q RET. Version 1.5 is now current. If locking is used for the file, type C-x C-q to lock version 1.5 so that you can change it. Next, type C-x v m 1.3.1 RET. This takes the entire set of changes on branch 1.3.1 (relative to version 1.3, where the branch started, up to the last version on the branch) and merges it into the current version of the work file. You can now check in the changed file, thus creating version 1.6 containing the changes from the branch.

It is possible to do further editing after merging the branch, before the next check-in. But it is usually wiser to check in the merged version, then lock it and make the further changes. This will keep a better record of the history of changes.

When you merge changes into a file that has itself been modified, the changes might overlap. We call this situation a conflict, and reconciling the conflicting changes is called resolving a conflict.

Whenever conflicts occur during merging, VC detects them, tells you about them in the echo area, and asks whether you want help in merging. If you say yes, it starts an Ediff session (see section `Ediff' in The Ediff Manual).

If you say no, the conflicting changes are both inserted into the file, surrounded by conflict markers. The example below shows how a conflict region looks; the file is called `name' and the current master file version with user B's changes in it is 1.11.
<<<<<<< name
  User A's version
=======
  User B's version
>>>>>>> 1.11
Then you can resolve the conflicts by editing the file manually. Or you can type M-x vc-resolve-conflicts after visiting the file. This starts an Ediff session, as described above. Don't forget to check in the merged version afterwards.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.6.4 Multi-User Branching

It is often useful for multiple developers to work simultaneously on different branches of a file. CVS allows this by default; for RCS, it is possible if you create multiple source directories. Each source directory should have a link named `RCS' which points to a common directory of RCS master files. Then each source directory can have its own choice of selected versions, but all share the same common RCS records.

This technique works reliably and automatically, provided that the source files contain RCS version headers (see section M.7.9.3 Inserting Version Control Headers). The headers enable Emacs to be sure, at all times, which version number is present in the work file.

If the files do not have version headers, you must instead tell Emacs explicitly in each session which branch you are working on. To do this, first find the file, then type C-u C-x C-q and specify the correct branch number. This ensures that Emacs knows which branch it is using during this particular editing session.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.7 Remote Repositories

A common way of using CVS is to set up a central CVS repository on some Internet host, then have each developer check out a personal working copy of the files on his local machine. Committing changes to the repository, and picking up changes from other users into one's own working area, then works by direct interactions with the CVS server.

One difficulty is that access to the CVS server is often slow, and that developers might need to work off-line as well. VC is designed to reduce the amount of network interaction necessary.

M.7.7.1 Version Backups

Keeping local copies of repository versions.

M.7.7.2 Local Version Control

Using another version system for local editing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.7.1 Version Backups

When VC sees that the CVS repository for a file is on a remote machine, it automatically makes local backups of unmodified versions of the file---automatic version backups. This means that you can compare the file to the repository version (C-x v =), or revert to that version (C-x v u), without any network interactions.

The local copy of the unmodified file is called a version backup to indicate that it corresponds exactly to a version that is stored in the repository. Note that version backups are not the same as ordinary Emacs backup files (see section M.3.1 Backup Files). But they follow a similar naming convention.

For a file that comes from a remote CVS repository, VC makes a version backup whenever you save the first changes to the file, and removes it after you have committed your modified version to the repository. You can disable the making of automatic version backups by setting vc-cvs-stay-local to nil (see section M.7.10.3 Options specific for CVS).

The name of the automatic version backup for version version of file file is file.~version.~. This is almost the same as the name used by C-x v ~ (see section M.7.4 Examining And Comparing Old Versions), the only difference being the additional dot (`.') after the version number. This similarity is intentional, because both kinds of files store the same kind of information. The file made by C-x v ~ acts as a manual version backup.

All the VC commands that operate on old versions of a file can use both kinds of version backups. For instance, C-x v ~ uses either an automatic or a manual version backup, if possible, to get the contents of the version you request. Likewise, C-x v = and C-x v u use either an automatic or a manual version backup, if one of them exists, to get the contents of a version to compare or revert to. If you changed a file outside of Emacs, so that no automatic version backup was created for the previous text, you can create a manual backup of that version using C-x v ~, and thus obtain the benefit of the local copy for Emacs commands.

The only difference in Emacs's handling of manual and automatic version backups, once they exist, is that Emacs deletes automatic version backups when you commit to the repository. By contrast, manual version backups remain until you delete them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.7.2 Local Version Control

When you make many changes to a file that comes from a remote repository, it can be convenient to have version control on your local machine as well. You can then record intermediate versions, revert to a previous state, etc., before you actually commit your changes to the remote server.

VC lets you do this by putting a file under a second, local version control system, so that the file is effectively registered in two systems at the same time. For the description here, we will assume that the remote system is CVS, and you use RCS locally, although the mechanism works with any combination of version control systems (back ends).

To make it work with other back ends, you must make sure that the "more local" back end comes before the "more remote" back end in the setting of vc-handled-backends (see section M.7.10 Customizing VC). By default, this variable is set up so that you can use remote CVS and local RCS as described here.

To start using local RCS for a file that comes from a remote CVS server, you must register the file in RCS, by typing C-u C-x v v rcs RET. (In other words, use vc-next-action with a prefix argument, and specify RCS as the back end.)

You can do this at any time; it does not matter whether you have already modified the file with respect to the version in the CVS repository. If possible, VC tries to make the RCS master start with the unmodified repository version, then checks in any local changes as a new version. This works if you have not made any changes yet, or if the unmodified repository version exists locally as a version backup (see section M.7.7.1 Version Backups). If the unmodified version is not available locally, the RCS master starts with the modified version; the only drawback to this is that you cannot compare your changes locally to what is stored in the repository.

The version number of the RCS master is derived from the current CVS version, starting a branch from it. For example, if the current CVS version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in the RCS master will be identical to version 1.23 under CVS; your first changes are checked in as 1.23.1.1. (If the unmodified file is not available locally, VC will check in the modified file twice, both as 1.23 and 1.23.1.1, to make the revision numbers consistent.)

If you do not use locking under CVS (the default), locking is also disabled for RCS, so that editing under RCS works exactly as under CVS.

When you are done with local editing, you can commit the final version back to the CVS repository by typing C-u C-x v v cvs RET. This initializes the log entry buffer (see section M.7.3.4 Features of the Log Entry Buffer) to contain all the log entries you have recorded in the RCS master; you can edit them as you wish, and then commit in CVS by typing C-c C-c. If the commit is successful, VC removes the RCS master, so that the file is once again registered under CVS only. (The RCS master is not actually deleted, just renamed by appending `~' to the name, so that you can refer to it later if you wish.)

While using local RCS, you can pick up recent changes from the CVS repository into your local file, or commit some of your changes back to CVS, without terminating local RCS version control. To do this, switch to the CVS back end temporarily, with the C-x v b command:

C-x v b
Switch to another back end that the current file is registered under (vc-switch-backend).

C-u C-x v b backend RET
Switch to backend for the current file.
C-x v b does not change the buffer contents, or any files; it only changes VC's perspective on how to handle the file. Any subsequent VC commands for that file will operate on the back end that is currently selected.

If the current file is registered in more than one back end, typing C-x v b "cycles" through all of these back ends. With a prefix argument, it asks for the back end to use in the minibuffer.

Thus, if you are using local RCS, and you want to pick up some recent changes in the file from remote CVS, first visit the file, then type C-x v b to switch to CVS, and finally use C-x v m RET to merge the news (see section M.7.6.3 Merging Branches). You can then switch back to RCS by typing C-x v b again, and continue to edit locally.

But if you do this, the revision numbers in the RCS master no longer correspond to those of CVS. Technically, this is not a problem, but it can become difficult to keep track of what is in the CVS repository and what is not. So we suggest that you return from time to time to CVS-only operation, using C-u C-x v v cvs RET.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.8 Snapshots

A snapshot is a named set of file versions (one for each registered file) that you can treat as a unit. One important kind of snapshot is a release, a (theoretically) stable version of the system that is ready for distribution to users.

M.7.8.1 Making and Using Snapshots

The snapshot facilities.

M.7.8.2 Snapshot Caveats

Things to be careful of when using snapshots.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.8.1 Making and Using Snapshots

There are two basic commands for snapshots; one makes a snapshot with a given name, the other retrieves a named snapshot.

C-x v s name RET
Define the last saved versions of every registered file in or under the current directory as a snapshot named name (vc-create-snapshot).

C-x v r name RET
For all registered files at or below the current directory level, select whatever versions correspond to the snapshot name (vc-retrieve-snapshot).
This command reports an error if any files are locked at or below the current directory, without changing anything; this is to avoid overwriting work in progress.
A snapshot uses a very small amount of resources--just enough to record the list of file names and which version belongs to the snapshot. Thus, you need not hesitate to create snapshots whenever they are useful.

You can give a snapshot name as an argument to C-x v = or C-x v ~ (see section M.7.4 Examining And Comparing Old Versions). Thus, you can use it to compare a snapshot against the current files, or two snapshots against each other, or a snapshot against a named version.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.8.2 Snapshot Caveats

VC's snapshot facilities are modeled on RCS's named-configuration support. They use RCS's native facilities for this, so under VC snapshots made using RCS are visible even when you bypass VC.

For SCCS, VC implements snapshots itself. The files it uses contain name/file/version-number triples. These snapshots are visible only through VC.

A snapshot is a set of checked-in versions. So make sure that all the files are checked in and not locked when you make a snapshot.

File renaming and deletion can create some difficulties with snapshots. This is not a VC-specific problem, but a general design issue in version control systems that no one has solved very well yet.

If you rename a registered file, you need to rename its master along with it (the command vc-rename-file does this automatically). If you are using SCCS, you must also update the records of the snapshot, to mention the file by its new name (vc-rename-file does this, too). An old snapshot that refers to a master file that no longer exists under the recorded name is invalid; VC can no longer retrieve it. It would be beyond the scope of this manual to explain enough about RCS and SCCS to explain how to update the snapshots by hand.

Using vc-rename-file makes the snapshot remain valid for retrieval, but it does not solve all problems. For example, some of the files in your program probably refer to others by name. At the very least, the makefile probably mentions the file that you renamed. If you retrieve an old snapshot, the renamed file is retrieved under its new name, which is not the name that the makefile expects. So the program won't really work as retrieved.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.9 Miscellaneous Commands and Features of VC

This section explains the less-frequently-used features of VC.

M.7.9.1 Change Logs and VC

Generating a change log file from log entries.

M.7.9.2 Renaming VC Work Files and Master Files

A command to rename both the source and master file correctly.

M.7.9.3 Inserting Version Control Headers

Inserting version control headers into working files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.9.1 Change Logs and VC

If you use RCS or CVS for a program and also maintain a change log file for it (see section W.1 Change Logs), you can generate change log entries automatically from the version control log entries:

C-x v a
Visit the current directory's change log file and, for registered files in that directory, create new entries for versions checked in since the most recent entry in the change log file. (vc-update-change-log).
This command works with RCS or CVS only, not with SCCS.

C-u C-x v a
As above, but only find entries for the current buffer's file.

M-1 C-x v a
As above, but find entries for all the currently visited files that are maintained with version control. This works only with RCS, and it puts all entries in the log for the default directory, which may not be appropriate.
For example, suppose the first line of `ChangeLog' is dated 1999-04-10, and that the only check-in since then was by Nathaniel Bowditch to `rcs2log' on 1999-05-22 with log text `Ignore log messages that start with `#'.'. Then C-x v a visits `ChangeLog' and inserts text like this:
1999-05-22  Nathaniel Bowditch  <nat@apn.org>

        * rcs2log: Ignore log messages that start with `#'.
You can then edit the new change log entry further as you wish.

Some of the new change log entries may duplicate what's already in ChangeLog. You will have to remove these duplicates by hand.

Normally, the log entry for file `foo' is displayed as `* foo: text of log entry'. The `:' after `foo' is omitted if the text of the log entry starts with `(functionname): '. For example, if the log entry for `vc.el' is `(vc-do-command): Check call-process status.', then the text in `ChangeLog' looks like this:
1999-05-06  Nathaniel Bowditch  <nat@apn.org>

        * vc.el (vc-do-command): Check call-process status.
When C-x v a adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time. If the log entries for several such files all have the same text, it coalesces them into a single entry. For example, suppose the most recent check-ins have the following log entries:
* For `vc.texinfo': `Fix expansion typos.'
* For `vc.el': `Don't call expand-file-name.'
* For `vc-hooks.el': `Don't call expand-file-name.'
They appear like this in `ChangeLog':
1999-04-01  Nathaniel Bowditch  <nat@apn.org>

        * vc.texinfo: Fix expansion typos.

        * vc.el, vc-hooks.el: Don't call expand-file-name.
Normally, C-x v a separates log entries by a blank line, but you can mark several related log entries to be clumped together (without an intervening blank line) by starting the text of each related log entry with a label of the form `{clumpname} '. The label itself is not copied to `ChangeLog'. For example, suppose the log entries are:
* For `vc.texinfo': `{expand} Fix expansion typos.'
* For `vc.el': `{expand} Don't call expand-file-name.'
* For `vc-hooks.el': `{expand} Don't call expand-file-name.'
Then the text in `ChangeLog' looks like this:
1999-04-01  Nathaniel Bowditch  <nat@apn.org>

        * vc.texinfo: Fix expansion typos.
        * vc.el, vc-hooks.el: Don't call expand-file-name.
A log entry whose text begins with `#' is not copied to `ChangeLog'. For example, if you merely fix some misspellings in comments, you can log the change with an entry beginning with `#' to avoid putting such trivia into `ChangeLog'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.9.2 Renaming VC Work Files and Master Files

When you rename a registered file, you must also rename its master file correspondingly to get proper results. Use vc-rename-file to rename the source file as you specify, and rename its master file accordingly. It also updates any snapshots (see section M.7.8 Snapshots) that mention the file, so that they use the new name; despite this, the snapshot thus modified may not completely work (see section M.7.8.2 Snapshot Caveats).

You cannot use vc-rename-file on a file that is locked by someone else.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.9.3 Inserting Version Control Headers

Sometimes it is convenient to put version identification strings directly into working files. Certain special strings called version headers are replaced in each successive version by the number of that version.

If you are using RCS, and version headers are present in your working files, Emacs can use them to determine the current version and the locking state of the files. This is more reliable than referring to the master files, which is done when there are no version headers. Note that in a multi-branch environment, version headers are necessary to make VC behave correctly (see section M.7.6.4 Multi-User Branching).

Searching for version headers is controlled by the variable vc-consult-headers. If it is non-nil (the default), Emacs searches for headers to determine the version number you are editing. Setting it to nil disables this feature.

You can use the C-x v h command (vc-insert-headers) to insert a suitable header string.

C-x v h
Insert headers in a file for use with your version-control system.
The default header string is `$Id$' for RCS and `%W%' for SCCS. You can specify other headers to insert by setting the variable vc-header-alist. Its value is a list of elements of the form (program . string) where program is RCS or SCCS and string is the string to use.

Instead of a single string, you can specify a list of strings; then each string in the list is inserted as a separate header on a line of its own.

It is often necessary to use "superfluous" backslashes when writing the strings that you put in this variable. For instance, you might write "$Id\$" rather than "$Id$". The extra backslash prevents the string constant from being interpreted as a header, if the Emacs Lisp file containing it is maintained with version control.

Each header is inserted surrounded by tabs, inside comment delimiters, on a new line at point. Normally the ordinary comment start and comment end strings of the current mode are used, but for certain modes, there are special comment delimiters for this purpose; the variable vc-comment-alist specifies them. Each element of this list has the form (mode starter ender).

The variable vc-static-header-alist specifies further strings to add based on the name of the buffer. Its value should be a list of elements of the form (regexp . format). Whenever regexp matches the buffer name, format is inserted as part of the header. A header line is inserted for each element that matches the buffer name, and for each string specified by vc-header-alist. The header line is made by processing the string from vc-header-alist with the format taken from the element. The default value for vc-static-header-alist is as follows:
(("\\.c$" .
  "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
#endif /* lint */\n"))
It specifies insertion of text of this form:
#ifndef lint
static char vcid[] = "string";
#endif /* lint */
Note that the text above starts with a blank line.

If you use more than one version header in a file, put them close together in the file. The mechanism in revert-buffer that preserves markers may not handle markers positioned between two version headers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.10 Customizing VC

The variable vc-handled-backends determines which version control systems VC should handle. The default value is (RCS CVS SCCS), so it contains all three version systems that are currently supported. If you want VC to ignore one or more of these systems, exclude its name from the list.

The order of systems in the list is significant: when you visit a file registered in more than one system (see section M.7.7.2 Local Version Control), VC uses the system that comes first in vc-handled-backends by default. The order is also significant when you register a file for the first time, see section M.7.5.1 Registering a File for Version Control for details.

M.7.10.1 General Options

Options that apply to multiple back ends.

M.7.10.2 Options for RCS and SCCS

M.7.10.3 Options specific for CVS

Options for CVS.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.10.1 General Options

Emacs normally does not save backup files for source files that are maintained with version control. If you want to make backup files even for files that use version control, set the variable vc-make-backup-files to a non-nil value.

Normally the work file exists all the time, whether it is locked or not. If you set vc-keep-workfiles to nil, then checking in a new version with C-x C-q deletes the work file; but any attempt to visit the file with Emacs creates it again. (With CVS, work files are always kept.)

Editing a version-controlled file through a symbolic link can be dangerous. It bypasses the version control system--you can edit the file without locking it, and fail to check your changes in. Also, your changes might overwrite those of another user. To protect against this, VC checks each symbolic link that you visit, to see if it points to a file under version control.

The variable vc-follow-symlinks controls what to do when a symbolic link points to a version-controlled file. If it is nil, VC only displays a warning message. If it is t, VC automatically follows the link, and visits the real file instead, telling you about this in the echo area. If the value is ask (the default), VC asks you each time whether to follow the link.

If vc-suppress-confirm is non-nil, then C-x C-q and C-x v i can save the current buffer without asking, and C-x v u also operates without asking for confirmation. (This variable does not affect C-x v c; that operation is so drastic that it should always ask for confirmation.)

VC mode does much of its work by running the shell commands for RCS, CVS and SCCS. If vc-command-messages is non-nil, VC displays messages to indicate which shell commands it runs, and additional messages when the commands finish.

You can specify additional directories to search for version control programs by setting the variable vc-path. These directories are searched before the usual search path. It is rarely necessary to set this variable, because VC normally finds the proper files automatically.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.10.2 Options for RCS and SCCS

By default, RCS uses locking to coordinate the activities of several users, but there is a mode called non-strict locking in which you can check-in changes without locking the file first. Use `rcs -U' to switch to non-strict locking for a particular file, see the rcs manual page for details.

When deducing the version control state of an RCS file, VC first looks for an RCS version header string in the file (see section M.7.9.3 Inserting Version Control Headers). If there is no header string, VC normally looks at the file permissions of the work file; this is fast. But there might be situations when the file permissions cannot be trusted. In this case the master file has to be consulted, which is rather expensive. Also the master file can only tell you if there's any lock on the file, but not whether your work file really contains that locked version.

You can tell VC not to use version headers to determine the file status by setting vc-consult-headers to nil. VC then always uses the file permissions (if it is supposed to trust them), or else checks the master file.

You can specify the criterion for whether to trust the file permissions by setting the variable vc-mistrust-permissions. Its value can be t (always mistrust the file permissions and check the master file), nil (always trust the file permissions), or a function of one argument which makes the decision. The argument is the directory name of the `RCS' subdirectory. A non-nil value from the function says to mistrust the file permissions. If you find that the file permissions of work files are changed erroneously, set vc-mistrust-permissions to t. Then VC always checks the master file to determine the file's status.

VC determines the version control state of files under SCCS much as with RCS. It does not consider SCCS version headers, though. Thus, the variable vc-mistrust-permissions affects SCCS use, but vc-consult-headers does not.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.7.10.3 Options specific for CVS

By default, CVS does not use locking to coordinate the activities of several users; anyone can change a work file at any time. However, there are ways to restrict this, resulting in behavior that resembles locking.

For one thing, you can set the CVSREAD environment variable (the value you use makes no difference). If this variable is defined, CVS makes your work files read-only by default. In Emacs, you must type C-x C-q to make the file writable, so that editing works in fact similar as if locking was used. Note however, that no actual locking is performed, so several users can make their files writable at the same time. When setting CVSREAD for the first time, make sure to check out all your modules anew, so that the file protections are set correctly.

Another way to achieve something similar to locking is to use the watch feature of CVS. If a file is being watched, CVS makes it read-only by default, and you must also use C-x C-q in Emacs to make it writable. VC calls cvs edit to make the file writable, and CVS takes care to notify other developers of the fact that you intend to change the file. See the CVS documentation for details on using the watch feature.

When a file's repository is on a remote machine, VC tries to keep network interactions to a minimum. This is controlled by the variable vc-cvs-stay-local. If it is t (the default), then VC uses only the entry in the local CVS subdirectory to determine the file's state (and possibly information returned by previous CVS commands). One consequence of this is that when you have modified a file, and somebody else has already checked in other changes to the file, you are not notified of it until you actually try to commit. (But you can try to pick up any recent changes from the repository first, using C-x v m RET, see section M.7.6.3 Merging Branches).

When vc-cvs-stay-local is t, VC also makes local version backups, so that simple diff and revert operations are completely local (see section M.7.7.1 Version Backups).

On the other hand, if you set vc-cvs-stay-local to nil, then VC queries the remote repository before it decides what to do in vc-next-action (C-x v v), just as it does for local repositories. It also does not make any version backups.

You can also set vc-cvs-stay-local to a regular expression that is matched against the repository host name; VC then stays local only for repositories from hosts that match the pattern.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.8 File Directories

The file system groups files into directories. A directory listing is a list of all the files in a directory. Emacs provides commands to create and delete directories, and to make directory listings in brief format (file names only) and verbose format (sizes, dates, and authors included). There is also a directory browser called Dired; see AB. Dired, the Directory Editor.

C-x C-d dir-or-pattern RET
Display a brief directory listing (list-directory).
C-u C-x C-d dir-or-pattern RET
Display a verbose directory listing.
M-x make-directory RET dirname RET
Create a new directory named dirname.
M-x delete-directory RET dirname RET
Delete the directory named dirname. It must be empty, or you get an error.
The command to display a directory listing is C-x C-d (list-directory). It reads using the minibuffer a file name which is either a directory to be listed or a wildcard-containing pattern for the files to be listed. For example,
C-x C-d /u2/emacs/etc RET
lists all the files in directory `/u2/emacs/etc'. Here is an example of specifying a file name pattern:
C-x C-d /u2/emacs/src/*.c RET
Normally, C-x C-d displays a brief directory listing containing just file names. A numeric argument (regardless of value) tells it to make a verbose listing including sizes, dates, and owners (like `ls -l').

The text of a directory listing is obtained by running ls in an inferior process. Two Emacs variables control the switches passed to ls: list-directory-brief-switches is a string giving the switches to use in brief listings ("-CF" by default), and list-directory-verbose-switches is a string giving the switches to use in a verbose listing ("-l" by default).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.9 Comparing Files

The command M-x diff compares two files, displaying the differences in an Emacs buffer named `*diff*'. It works by running the diff program, using options taken from the variable diff-switches. The value of diff-switches should be a string; the default is "-c" to specify a context diff.

The buffer `*diff*' has Compilation mode as its major mode, so you can use C-x ` to visit successive changed locations in the two source files. You can also move to a particular hunk of changes and type RET or C-c C-c, or click Mouse-2 on it, to move to the corresponding source location. You can also use the other special commands of Compilation mode: SPC and DEL for scrolling, and M-p and M-n for cursor motion. See section V.1 Running Compilations under Emacs.

The command M-x diff-backup compares a specified file with its most recent backup. If you specify the name of a backup file, diff-backup compares it with the source file that it is a backup of.

The command M-x compare-windows compares the text in the current window with that in the next window. Comparison starts at point in each window, and each starting position is pushed on the mark ring in its respective buffer. Then point moves forward in each window, a character at a time, until a mismatch between the two windows is reached. Then the command is finished. For more information about windows in Emacs, O. Multiple Windows.

With a numeric argument, compare-windows ignores changes in whitespace. If the variable compare-ignore-case is non-nil, it ignores differences in case as well.

Differences between versions of files are often distributed as patches, which are the output from diff or a version control system that uses diff. M-x diff-mode turns on Diff mode, a major mode for viewing and editing patches, either as "unified diffs" or "context diffs."

You can use M-x smerge-mode to turn on Smerge mode, a minor mode for editing output from the diff3 program. This is typically the result of a failed merge from a version control system "update" outside VC, due to conflicting changes to a file. Smerge mode provides commands to resolve conflicts by selecting specific changes.

See also W.3 Merging Files with Emerge, and section `Top' in The Ediff Manual, for convenient facilities for merging two similar files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.10 Miscellaneous File Operations

Emacs has commands for performing many other operations on files. All operate on one file; they do not accept wildcard file names.

M-x view-file allows you to scan or read a file by sequential screenfuls. It reads a file name argument using the minibuffer. After reading the file into an Emacs buffer, view-file displays the beginning. You can then type SPC to scroll forward one windowful, or DEL to scroll backward. Various other commands are provided for moving around in the file, but none for changing it; type ? while viewing for a list of them. They are mostly the same as normal Emacs cursor motion commands. To exit from viewing, type q. The commands for viewing are defined by a special major mode called View mode.

A related command, M-x view-buffer, views a buffer already present in Emacs. See section N.3 Miscellaneous Buffer Operations.

M-x insert-file (also C-x i) inserts a copy of the contents of the specified file into the current buffer at point, leaving point unchanged before the contents and the mark after them.

M-x write-region is the inverse of M-x insert-file; it copies the contents of the region into the specified file. M-x append-to-file adds the text of the region to the end of the specified file. See section H.9 Accumulating Text.

M-x delete-file deletes the specified file, like the rm command in the shell. If you are deleting many files in one directory, it may be more convenient to use Dired (see section AB. Dired, the Directory Editor).

M-x rename-file reads two file names old and new using the minibuffer, then renames file old as new. If the file name new already exists, you must confirm with yes or renaming is not done; this is because renaming causes the old meaning of the name new to be lost. If old and new are on different file systems, the file old is copied and deleted.

The similar command M-x add-name-to-file is used to add an additional name to an existing file without removing its old name. The new name is created as a "hard link" to the existing file. The new name must belong on the same file system that the file is on. On Windows, this command works only if the file resides in an NTFS file system. On MS-DOS, it works by copying the file.

M-x copy-file reads the file old and writes a new file named new with the same contents. Confirmation is required if a file named new already exists, because copying has the consequence of overwriting the old contents of the file new.

M-x make-symbolic-link reads two file names target and linkname, then creates a symbolic link named linkname, which points at target. The effect is that future attempts to open file linkname will refer to whatever file is named target at the time the opening is done, or will get an error if the name target is not in use at that time. This command does not expand the argument target, so that it allows you to specify a relative name as the target of the link.

Confirmation is required when creating the link if linkname is in use. Note that not all systems support symbolic links; on systems that don't support them, this command is not defined.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.11 Accessing Compressed Files

Emacs comes with a library that can automatically uncompress compressed files when you visit them, and automatically recompress them if you alter them and save them. To enable this feature, type the command M-x auto-compression-mode. You can enable it permanently by customizing the option auto-compression-mode.

When automatic compression (which implies automatic uncompression as well) is enabled, Emacs recognizes compressed files by their file names. File names ending in `.gz' indicate a file compressed with gzip. Other endings indicate other compression programs.

Automatic uncompression and compression apply to all the operations in which Emacs uses the contents of a file. This includes visiting it, saving it, inserting its contents into a buffer, loading it, and byte compiling it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.12 File Archives

A file whose name ends in `.tar' is normally an archive made by the tar program. Emacs views these files in a special mode called Tar mode which provides a Dired-like list of the contents (see section AB. Dired, the Directory Editor). You can move around through the list just as you would in Dired, and visit the subfiles contained in the archive. However, not all Dired commands are available in Tar mode.

If you enable Auto Compression mode (see section M.11 Accessing Compressed Files), then Tar mode is used also for compressed archives--files with extensions `.tgz', .tar.Z and .tar.gz.

The keys e, f and RET all extract a component file into its own buffer. You can edit it there and when you save the buffer the edited version will replace the version in the Tar buffer. v extracts a file into a buffer in View mode. o extracts the file and displays it in another window, so you could edit the file and operate on the archive simultaneously. d marks a file for deletion when you later use x, and u unmarks a file, as in Dired. C copies a file from the archive to disk and R renames a file. g reverts the buffer from the archive on disk.

The keys M, G, and O change the file's permission bits, group, and owner, respectively.

If your display supports colors and the mouse, moving the mouse pointer across a file name highlights that file name, indicating that you can click on it. Clicking Mouse-2 on the highlighted file name extracts the file into a buffer and displays that buffer.

Saving the Tar buffer writes a new version of the archive to disk with the changes you made to the components.

You don't need the tar program to use Tar mode--Emacs reads the archives directly. However, accessing compressed archives requires the appropriate uncompression program.

A separate but similar Archive mode is used for archives produced by the programs arc, jar, lzh, zip, and zoo, which have extensions corresponding to the program names.

The key bindings of Archive mode are similar to those in Tar mode, with the addition of the m key which marks a file for subsequent operations, and M-DEL which unmarks all the marked files. Also, the a key toggles the display of detailed file information, for those archive types where it won't fit in a single line. Operations such as renaming a subfile, or changing its mode or owner, are supported only for some of the archive formats.

Unlike Tar mode, Archive mode runs the archiving program to unpack and repack archives. Details of the program names and their options can be set in the `Archive' Customize group. However, you don't need these programs to look at the archive table of contents, only to extract or manipulate the subfiles in the archive.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.13 Remote Files

You can refer to files on other machines using a special file name syntax:
/host:filename
/user@host:filename
/user@host#port:filename
When you do this, Emacs uses the FTP program to read and write files on the specified host. It logs in through FTP using your user name or the name user. It may ask you for a password from time to time; this is used for logging in on host. The form using port allows you to access servers running on a non-default TCP port.

If you want to disable backups for remote files, set the variable ange-ftp-make-backup-files to nil.

Normally, if you do not specify a user name in a remote file name, that means to use your own user name. But if you set the variable ange-ftp-default-user to a string, that string is used instead. (The Emacs package that implements FTP file access is called ange-ftp.)

To visit files accessible by anonymous FTP, you use special user names `anonymous' or `ftp'. Passwords for these user names are handled specially. The variable ange-ftp-generate-anonymous-password controls what happens: if the value of this variable is a string, then that string is used as the password; if non-nil (the default), then the value of user-mail-address is used; if nil, the user is prompted for a password as normal.

Sometimes you may be unable to access files on a remote machine because a firewall in between blocks the connection for security reasons. If you can log in on a gateway machine from which the target files are accessible, and whose FTP server supports gatewaying features, you can still use remote file names; all you have to do is specify the name of the gateway machine by setting the variable ange-ftp-gateway-host, and set ange-ftp-smart-gateway to t. Otherwise you may be able to make remote file names work, but the procedure is complex. You can read the instructions by typing M-x finder-commentary RET ange-ftp RET.

You can entirely turn off the FTP file name feature by removing the entries ange-ftp-completion-hook-function and ange-ftp-hook-function from the variable file-name-handler-alist. You can turn off the feature in individual cases by quoting the file name with `/:' (see section M.14 Quoted File Names).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.14 Quoted File Names

You can quote an absolute file name to prevent special characters and syntax in it from having their special effects. The way to do this is to add `/:' at the beginning.

For example, you can quote a local file name which appears remote, to prevent it from being treated as a remote file name. Thus, if you have a directory named `/foo:' and a file named `bar' in it, you can refer to that file in Emacs as `/:/foo:/bar'.

`/:' can also prevent `~' from being treated as a special character for a user's home directory. For example, `/:/tmp/~hack' refers to a file whose name is `~hack' in directory `/tmp'.

Likewise, quoting with `/:' is one way to enter in the minibuffer a file name that contains `$'. However, the `/:' must be at the beginning of the minibuffer in order to quote `$'.

You can also quote wildcard characters with `/:', for visiting. For example, `/:/tmp/foo*bar' visits the file `/tmp/foo*bar'. However, in most cases you can simply type the wildcard characters for themselves. For example, if the only file name in `/tmp' that starts with `foo' and ends with `bar' is `foo*bar', then specifying `/tmp/foo*bar' will visit just `/tmp/foo*bar'. Another way is to specify `/tmp/foo[*]bar'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.15 File Name Cache

You can use the file name cache to make it easy to locate a file by name, without having to remember exactly where it is located. When typing a file name in the minibuffer, C-tab (file-cache-minibuffer-complete) completes it using the file name cache. If you repeat C-tab, that cycles through the possible completions of what you had originally typed. Note that the C-tab character cannot be typed on most text-only terminals.

The file name cache does not fill up automatically. Instead, you load file names into the cache using these commands:

M-x file-cache-add-directory RET directory RET
Add each file name in directory to the file name cache.
M-x file-cache-add-directory-using-find RET directory RET
Add each file name in directory and all of its nested subdirectories to the file name cache.
M-x file-cache-add-directory-using-locate RET directory RET
Add each file name in directory and all of its nested subdirectories to the file name cache, using locate to find them all.
M-x file-cache-add-directory-list RET variable RET
Add each file name in each directory listed in variable to the file name cache. variable should be a Lisp variable such as load-path or exec-path, whose value is a list of directory names.
M-x file-cache-clear-cache RET
Clear the cache; that is, remove all file names from it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

M.16 Convenience Features for Finding Files

If you enable Recentf mode, with M-x recentf-mode, the `File' menu includes a submenu containing a list of recently opened files. M-x recentf-save-list saves the current recent-file-list to a file, and M-x recentf-edit-list edits it.

When Auto-image-file minor mode is enabled, visiting an image file displays it as an image, not as text. Likewise, inserting an image file into a buffer inserts it as an image. This works only when Emacs can display the relevant image type. The variables image-file-name-extensions or image-file-name-regexps control which file names are recognized as containing images.

The M-x ffap command generalizes find-file with more powerful heuristic defaults (see section AC.28.3 Finding Files and URLs at Point), often based on the text at point. Partial Completion mode offers other features extending find-file, which can be used with ffap. See section E.3.4 Completion Options.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N. Using Multiple Buffers

The text you are editing in Emacs resides in an object called a buffer. Each time you visit a file, a buffer is created to hold the file's text. Each time you invoke Dired, a buffer is created to hold the directory listing. If you send a message with C-x m, a buffer named `*mail*' is used to hold the text of the message. When you ask for a command's documentation, that appears in a buffer called `*Help*'.

At any time, one and only one buffer is current. It is also called the selected buffer. Often we say that a command operates on "the buffer" as if there were only one; but really this means that the command operates on the current buffer (most commands do).

When Emacs has multiple windows, each window has its own chosen buffer and displays it; at any time, only one of the windows is selected, and its chosen buffer is the current buffer. Each window's mode line normally displays the name of the window's chosen buffer (see section O. Multiple Windows).

Each buffer has a name, which can be of any length, and you can select any buffer by giving its name. Most buffers are made by visiting files, and their names are derived from the files' names. But you can also create an empty buffer with any name you want. A newly started Emacs has a buffer named `*scratch*' which can be used for evaluating Lisp expressions in Emacs. The distinction between upper and lower case matters in buffer names.

Each buffer records individually what file it is visiting, whether it is modified, and what major mode and minor modes are in effect in it (see section R. Major Modes). Any Emacs variable can be made local to a particular buffer, meaning its value in that buffer can be different from the value in other buffers. See section AD.2.4 Local Variables.

A buffer's size cannot be larger than some maximum, which is defined by the largest buffer position representable by the Emacs integer data type. This is because Emacs tracks buffer positions using that data type. For 32-bit machines, the largest buffer size is 128 megabytes.

N.1 Creating and Selecting Buffers

Creating a new buffer or reselecting an old one.

N.2 Listing Existing Buffers

Getting a list of buffers that exist.

N.3 Miscellaneous Buffer Operations

Renaming; changing read-onlyness; copying text.

N.4 Killing Buffers

Killing buffers you no longer need.

N.5 Operating on Several Buffers

How to go through the list of all buffers and operate variously on several of them.

N.6 Indirect Buffers

An indirect buffer shares the text of another buffer.

N.7 Convenience Features and Customization of Buffer Handling

Convenience and customization features for buffer handling.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.1 Creating and Selecting Buffers

C-x b buffer RET
Select or create a buffer named buffer (switch-to-buffer).
C-x 4 b buffer RET
Similar, but select buffer in another window (switch-to-buffer-other-window).
C-x 5 b buffer RET
Similar, but select buffer in a separate frame (switch-to-buffer-other-frame).
To select the buffer named bufname, type C-x b bufname RET. This runs the command switch-to-buffer with argument bufname. You can use completion on an abbreviation for the buffer name you want (see section E.3 Completion). An empty argument to C-x b specifies the buffer that was current most recently among those not now displayed in any window.

To select a buffer in a window other than the current one, type C-x 4 b bufname RET. This runs the command switch-to-buffer-other-window which displays the buffer bufname in another window. By default, if displaying the buffer causes two vertically adjacent windows to be displayed, the heights of those windows are evened out; to countermand that and preserve the window configuration, set the variable even-window-heights to nil.

Similarly, C-x 5 b buffer RET runs the command switch-to-buffer-other-frame which selects a buffer in another frame.

You can control how certain buffers are handled by these commands by customizing the variables special-display-buffer-names, special-display-regexps, same-window-buffer-names, and same-window-regexps. See O.5 Forcing Display in the Same Window, and P.11 Special Buffer Frames, for more about these variables. In addition, if the value of display-buffer-reuse-frames is non-nil, and the buffer you want to switch to is already displayed in some frame, Emacs will raise that frame.

Most buffers are created by visiting files, or by Emacs commands that want to display some text, but you can also create a buffer explicitly by typing C-x b bufname RET. This makes a new, empty buffer that is not visiting any file, and selects it for editing. Such buffers are used for making notes to yourself. If you try to save one, you are asked for the file name to use. The new buffer's major mode is determined by the value of default-major-mode (see section R. Major Modes).

Note that C-x C-f, and any other command for visiting a file, can also be used to switch to an existing file-visiting buffer. See section M.2 Visiting Files.

Emacs uses buffer names that start with a space for internal purposes. It treats these buffers specially in minor ways--for example, by default they do not record undo information. It is best to avoid using such buffer names yourself.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.2 Listing Existing Buffers

C-x C-b
List the existing buffers (list-buffers).
To display a list of all the buffers that exist, type C-x C-b. Each line in the list shows one buffer's name, major mode and visited file. The buffers are listed in the order that they were current; the buffers that were current most recently come first.

`*' at the beginning of a line indicates the buffer is "modified." If several buffers are modified, it may be time to save some with C-x s (see section M.3 Saving Files). `%' indicates a read-only buffer. `.' marks the current buffer. Here is an example of a buffer list:
 MR Buffer         Size  Mode           File
 -- ------         ----  ----           ----
.*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
    *Help*         1287  Fundamental
    files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
  % RMAIL          64042 RMAIL          /u/rms/RMAIL
 *% man            747   Dired          /u2/emacs/man/
    net.emacs      343885 Fundamental   /u/rms/net.emacs
    fileio.c       27691 C              /u2/emacs/src/fileio.c
    NEWS           67340 Text           /u2/emacs/etc/NEWS
    *scratch*	   0	 Lisp Interaction
Note that the buffer `*Help*' was made by a help request; it is not visiting any file. The buffer man was made by Dired on the directory `/u2/emacs/man/'. You can list only buffers that are visiting files by giving the command a prefix; for instance, by typing C-u C-x C-b.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.3 Miscellaneous Buffer Operations

C-x C-q
Toggle read-only status of buffer (vc-toggle-read-only).
M-x rename-buffer RET name RET
Change the name of the current buffer.
M-x rename-uniquely
Rename the current buffer by adding `<number>' to the end.
M-x view-buffer RET buffer RET
Scroll through buffer buffer.
A buffer can be read-only, which means that commands to change its contents are not allowed. The mode line indicates read-only buffers with `%%' or `%*' near the left margin. Read-only buffers are usually made by subsystems such as Dired and Rmail that have special commands to operate on the text; also by visiting a file whose access control says you cannot write it.

If you wish to make changes in a read-only buffer, use the command C-x C-q (vc-toggle-read-only). It makes a read-only buffer writable, and makes a writable buffer read-only. In most cases, this works by setting the variable buffer-read-only, which has a local value in each buffer and makes the buffer read-only if its value is non-nil. If the file is maintained with version control, C-x C-q works through the version control system to change the read-only status of the file as well as the buffer. See section M.7 Version Control.

M-x rename-buffer changes the name of the current buffer. Specify the new name as a minibuffer argument. There is no default. If you specify a name that is in use for some other buffer, an error happens and no renaming is done.

M-x rename-uniquely renames the current buffer to a similar name with a numeric suffix added to make it both different and unique. This command does not need an argument. It is useful for creating multiple shell buffers: if you rename the `*Shell*' buffer, then do M-x shell again, it makes a new shell buffer named `*Shell*'; meanwhile, the old shell buffer continues to exist under its new name. This method is also good for mail buffers, compilation buffers, and most Emacs features that create special buffers with particular names.

M-x view-buffer is much like M-x view-file (see section M.10 Miscellaneous File Operations) except that it examines an already existing Emacs buffer. View mode provides commands for scrolling through the buffer conveniently but not for changing it. When you exit View mode with q, that switches back to the buffer (and the position) which was previously displayed in the window. Alternatively, if you exit View mode with e, the buffer and the value of point that resulted from your perusal remain in effect.

The commands M-x append-to-buffer and M-x insert-buffer can be used to copy text from one buffer to another. See section H.9 Accumulating Text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.4 Killing Buffers

If you continue an Emacs session for a while, you may accumulate a large number of buffers. You may then find it convenient to kill the buffers you no longer need. On most operating systems, killing a buffer releases its space back to the operating system so that other programs can use it. Here are some commands for killing buffers:

C-x k bufname RET
Kill buffer bufname (kill-buffer).
M-x kill-some-buffers
Offer to kill each buffer, one by one.

C-x k (kill-buffer) kills one buffer, whose name you specify in the minibuffer. The default, used if you type just RET in the minibuffer, is to kill the current buffer. If you kill the current buffer, another buffer becomes current: one that was current in the recent past but is not displayed in any window now. If you ask to kill a file-visiting buffer that is modified (has unsaved editing), then you must confirm with yes before the buffer is killed.

The command M-x kill-some-buffers asks about each buffer, one by one. An answer of y means to kill the buffer. Killing the current buffer or a buffer containing unsaved changes selects a new buffer or asks for confirmation just like kill-buffer.

The buffer menu feature (see section N.5 Operating on Several Buffers) is also convenient for killing various buffers.

If you want to do something special every time a buffer is killed, you can add hook functions to the hook kill-buffer-hook (see section AD.2.3 Hooks).

If you run one Emacs session for a period of days, as many people do, it can fill up with buffers that you used several days ago. The command M-x clean-buffer-list is a convenient way to purge them; it kills all the unmodified buffers that you have not used for a long time. An ordinary buffer is killed if it has not been displayed for three days; however, you can specify certain buffers that should never be killed automatically, and others that should be killed if they have been unused for a mere hour.

You can also have this buffer purging done for you, every day at midnight, by enabling Midnight mode. Midnight mode operates each day at midnight; at that time, it runs clean-buffer-list, or whichever functions you have placed in the normal hook midnight-hook (see section AD.2.3 Hooks).

To enable Midnight mode, use the Customization buffer to set the variable midnight-mode to t. See section AD.2.2 Easy Customization Interface.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.5 Operating on Several Buffers

The buffer-menu facility is like a "Dired for buffers"; it allows you to request operations on various Emacs buffers by editing an Emacs buffer containing a list of them. You can save buffers, kill them (here called deleting them, for consistency with Dired), or display them.

M-x buffer-menu
Begin editing a buffer listing all Emacs buffers.
The command buffer-menu writes a list of all Emacs buffers into the buffer `*Buffer List*', and selects that buffer in Buffer Menu mode. The buffer is read-only, and can be changed only through the special commands described in this section. The usual Emacs cursor motion commands can be used in the `*Buffer List*' buffer. The following commands apply to the buffer described on the current line.

d
Request to delete (kill) the buffer, then move down. The request shows as a `D' on the line, before the buffer name. Requested deletions take place when you type the x command.
C-d
Like d but move up afterwards instead of down.
s
Request to save the buffer. The request shows as an `S' on the line. Requested saves take place when you type the x command. You may request both saving and deletion for the same buffer.
x
Perform previously requested deletions and saves.
u
Remove any request made for the current line, and move down.
DEL
Move to previous line and remove any request made for that line.
The d, C-d, s and u commands to add or remove flags also move down (or up) one line. They accept a numeric argument as a repeat count.

These commands operate immediately on the buffer listed on the current line:

~
Mark the buffer "unmodified." The command ~ does this immediately when you type it.
%
Toggle the buffer's read-only flag. The command % does this immediately when you type it.
t
Visit the buffer as a tags table. See section W.2.4 Selecting a Tags Table.
There are also commands to select another buffer or buffers:

q
Quit the buffer menu--immediately display the most recent formerly visible buffer in its place.
RET

f
Immediately select this line's buffer in place of the `*Buffer List*' buffer.
o
Immediately select this line's buffer in another window as if by C-x 4 b, leaving `*Buffer List*' visible.
C-o
Immediately display this line's buffer in another window, but don't select the window.
1
Immediately select this line's buffer in a full-screen window.
2
Immediately set up two windows, with this line's buffer in one, and the previously current buffer (aside from the buffer `*Buffer List*') in the other.
b
Bury the buffer listed on this line.
m
Mark this line's buffer to be displayed in another window if you exit with the v command. The request shows as a `>' at the beginning of the line. (A single buffer may not have both a delete request and a display request.)
v
Immediately select this line's buffer, and also display in other windows any buffers previously marked with the m command. If you have not marked any buffers, this command is equivalent to 1.
All that buffer-menu does directly is create and switch to a suitable buffer, and turn on Buffer Menu mode. Everything else described above is implemented by the special commands provided in Buffer Menu mode. One consequence of this is that you can switch from the `*Buffer List*' buffer to another Emacs buffer, and edit there. You can reselect the `*Buffer List*' buffer later, to perform the operations already requested, or you can kill it, or pay no further attention to it.

The only difference between buffer-menu and list-buffers is that buffer-menu switches to the `*Buffer List*' buffer in the selected window; list-buffers displays it in another window. If you run list-buffers (that is, type C-x C-b) and select the buffer list manually, you can use all of the commands described here.

The buffer `*Buffer List*' is not updated automatically when buffers are created and killed; its contents are just text. If you have created, deleted or renamed buffers, the way to update `*Buffer List*' to show what you have done is to type g (revert-buffer) or repeat the buffer-menu command.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.6 Indirect Buffers

An indirect buffer shares the text of some other buffer, which is called the base buffer of the indirect buffer. In some ways it is the analogue, for buffers, of a symbolic link between files.

M-x make-indirect-buffer RET base-buffer RET indirect-name RET
Create an indirect buffer named indirect-name whose base buffer is base-buffer.
M-x clone-indirect-buffer RET
Create an indirect buffer that is a twin copy of the current buffer.
C-x 4 c
Create an indirect buffer that is a twin copy of the current buffer, and select it in another window (clone-indirect-buffer-other-window).
The text of the indirect buffer is always identical to the text of its base buffer; changes made by editing either one are visible immediately in the other. But in all other respects, the indirect buffer and its base buffer are completely separate. They have different names, different values of point, different narrowing, different markers, different major modes, and different local variables.

An indirect buffer cannot visit a file, but its base buffer can. If you try to save the indirect buffer, that actually works by saving the base buffer. Killing the base buffer effectively kills the indirect buffer, but killing an indirect buffer has no effect on its base buffer.

One way to use indirect buffers is to display multiple views of an outline. See section T.8.4 Viewing One Outline in Multiple Views.

A quick and handy way to make an indirect buffer is with the command M-x clone-indirect-buffer. It creates and selects an indirect buffer whose base buffer is the current buffer. With a numeric argument, it prompts for the name of the indirect buffer; otherwise it defaults to the name of the current buffer, modifying it by adding a `<n>' prefix if required. C-x 4 c (clone-indirect-buffer-other-window) works like M-x clone-indirect-buffer, but it selects the cloned buffer in another window. These commands come in handy if you want to create new `*info*' or `*Help*' buffers, for example.

The more general way is with the command M-x make-indirect-buffer. It creates an indirect buffer from buffer base-buffer, under the name indirect-name. It prompts for both base-buffer and indirect-name using the minibuffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.7 Convenience Features and Customization of Buffer Handling

This section describes several modes and features that make it more convenient to switch between buffers.

N.7.1 Making Buffer Names Unique

Buffer names can contain directory parts.

N.7.2 Switching Between Buffers using Substrings

Switching between buffers with substrings.

N.7.3 Customizing Buffer Menus

Configurable buffer menu.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.7.1 Making Buffer Names Unique

When several buffers visit identically-named files, Emacs must give the buffers distinct names. The usual method for making buffer names unique adds `<2>', `<3>', etc. to the end of the buffer names (all but one of them).

Other methods work by adding parts of each file's directory to the buffer name. To select one, customize the variable uniquify-buffer-name-style (see section AD.2.2 Easy Customization Interface).

For instance, the forward naming method puts part of the directory name at the beginning of the buffer name; using this method, buffers visiting `/u/mernst/tmp/Makefile' and `/usr/projects/zaphod/Makefile' would be named `tmp/Makefile' and `zaphod/Makefile', respectively (instead of `Makefile' and `Makefile<2>').

By contrast, the post-forward naming method would call the buffers `Makefile|tmp' and `Makefile|zaphod', and the reverse naming method would call them `Makefile\tmp' and `Makefile\zaphod'. The nontrivial difference between post-forward and reverse occurs when just one directory name is not enough to distinguish two files; then reverse puts the directory names in reverse order, so that `/top/middle/file' becomes `file\middle\top', while post-forward puts them in forward order after the file name, as in `file|top/middle'.

Which rule to follow for putting the directory names in the buffer name is not very important if you are going to look at the buffer names before you type one. But as an experienced user, if you know the rule, you won't have to look. And then you may find that one rule or another is easier for you to remember and utilize fast.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.7.2 Switching Between Buffers using Substrings

Iswitchb global minor mode provides convenient switching between buffers using substrings of their names. It replaces the normal definitions of C-x b, C-x 4 b, C-x 5 b, and C-x 4 C-o with alternative commands that are somewhat "smarter."

When one of these commands prompts you for a buffer name, you can type in just a substring of the name you want to choose. As you enter the substring, Iswitchb mode continuously displays a list of buffers that match the substring you have typed.

At any time, you can type RET to select the first buffer in the list. So the way to select a particular buffer is to make it the first in the list. There are two ways to do this. You can type more of the buffer name and thus narrow down the list, excluding unwanted buffers above the desired one. Alternatively, you can use C-s and C-r to rotate the list until the desired buffer is first.

TAB while entering the buffer name performs completion on the string you have entered, based on the displayed list of buffers.

To enable Iswitchb mode, type M-x iswitchb-mode, or customize the variable iswitchb-mode to t (see section AD.2.2 Easy Customization Interface).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

N.7.3 Customizing Buffer Menus

M-x bs-show
Make a list of buffers similarly to M-x list-buffers but customizable.
M-x bs-show pops up a buffer list similar to the one normally displayed by C-x C-b but which you can customize. If you prefer this to the usual buffer list, you can bind this command to C-x C-b. To customize this buffer list, use the bs Custom group (see section AD.2.2 Easy Customization Interface).

MSB global minor mode ("MSB" stands for "mouse select buffer") provides a different and customizable mouse buffer menu which you may prefer. It replaces the bindings of mouse-buffer-menu, normally on C-Down-Mouse-1, and the menu bar buffer menu. You can customize the menu in the msb Custom group.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

O. Multiple Windows

Emacs can split a frame into two or many windows. Multiple windows can display parts of different buffers, or different parts of one buffer. Multiple frames always imply multiple windows, because each frame has its own set of windows. Each window belongs to one and only one frame.

O.1 Concepts of Emacs Windows

Introduction to Emacs windows.

O.2 Splitting Windows

New windows are made by splitting existing windows.

O.3 Using Other Windows

Moving to another window or doing something to it.

O.4 Displaying in Another Window

Finding a file or buffer in another window.

O.5 Forcing Display in the Same Window

Forcing certain buffers to appear in the selected window rather than in another window.

O.6 Deleting and Rearranging Windows

Deleting windows and changing their sizes.

O.7 Window Handling Convenience Features and Customization

Convenience functions for window handling.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

O.1 Concepts of Emacs Windows

Each Emacs window displays one Emacs buffer at any time. A single buffer may appear in more than one window; if it does, any changes in its text are displayed in all the windows where it appears. But the windows showing the same buffer can show different parts of it, because each window has its own value of point.

At any time, one of the windows is the selected window; the buffer this window is displaying is the current buffer. The terminal's cursor shows the location of point in this window. Each other window has a location of point as well, but since the terminal has only one cursor there is no way to show where those locations are. When multiple frames are visible in X, each frame has a cursor which appears in the frame's selected window. The cursor in the selected frame is solid; the cursor in other frames is a hollow box.

Commands to move point affect the value of point for the selected Emacs window only. They do not change the value of point in any other Emacs window, even one showing the same buffer. The same is true for commands such as C-x b to change the current buffer in the selected window; they do not affect other windows at all. However, there are other commands such as C-x 4 b that select a different window and switch buffers in it. Also, all commands that display information in a window, including (for example) C-h f (describe-function) and C-x C-b (list-buffers), work by switching buffers in a nonselected window without affecting the selected window.

When multiple windows show the same buffer, they can have different regions, because they can have different values of point. However, they all have the same value for the mark, because each buffer has only one mark position.

Each window has its own mode line, which displays the buffer name, modification status and major and minor modes of the buffer that is displayed in the window. See section B.3 The Mode Line, for full details on the mode line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

O.2 Splitting Windows

C-x 2
Split the selected window into two windows, one above the other (split-window-vertically).
C-x 3
Split the selected window into two windows positioned side by side (split-window-horizontally).
C-Mouse-2
In the mode line or scroll bar of a window, split that window.
The command C-x 2 (split-window-vertically) breaks the selected window into two windows, one above the other. Both windows start out displaying the same buffer, with the same value of point. By default the two windows each get half the height of the window that was split; a numeric argument specifies how many lines to give to the top window.

C-x 3 (split-window-horizontally) breaks the selected window into two side-by-side windows. A numeric argument specifies how many columns to give the one on the left. A line of vertical bars separates the two windows. Windows that are not the full width of the screen have mode lines, but they are truncated. On terminals where Emacs does not support highlighting, truncated mode lines sometimes do not appear in inverse video.

You can split a window horizontally or vertically by clicking C-Mouse-2 in the mode line or the scroll bar. (This does not work in scroll bars implemented by X toolkits.) The line of splitting goes through the place where you click: if you click on the mode line, the new scroll bar goes above the spot; if you click in the scroll bar, the mode line of the split window is side by side with your click.

When a window is less than the full width, text lines too long to fit are frequent. Continuing all those lines might be confusing. The variable truncate-partial-width-windows can be set non-nil to force truncation in all windows less than the full width of the screen, independent of the buffer being displayed and its value for truncate-lines. See section D.8 Continuation Lines.

Horizontal scrolling is often used in side-by-side windows. See section J. Controlling the Display.

If split-window-keep-point is non-nil, the default, both of the windows resulting from C-x 2 inherit the value of point from the window that was split. This means that scrolling is inevitable. If this variable is nil, then C-x 2 tries to avoid scrolling the text currently visible on the screen, by putting point in each window at a position already visible in the window. It also selects whichever window contain the screen line that the cursor was previously on. Some users prefer the latter mode on slow terminals.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

O.3 Using Other Windows

C-x o
Select another window (other-window). That is o, not zero.
C-M-v
Scroll the next window (scroll-other-window).
M-x compare-windows
Find next place where the text in the selected window does not match the text in the next window.
Mouse-1
Mouse-1, in a window's mode line, selects that window but does not move point in it (mouse-select-window).
To select a different window, click with Mouse-1 on its mode line. With the keyboard, you can switch windows by typing C-x o (other-window). That is an o, for "other," not a zero. When there are more than two windows, this command moves through all the windows in a cyclic order, generally top to bottom and left to right. After the rightmost and bottommost window, it goes back to the one at the upper left corner. A numeric argument means to move several steps in the cyclic order of windows. A negative argument moves around the cycle in the opposite order. When the minibuffer is active, the minibuffer is the last window in the cycle; you can switch from the minibuffer window to one of the other windows, and later switch back and finish supplying the minibuffer argument that is requested. See section E.2 Editing in the Minibuffer.

The usual scrolling commands (see section J. Controlling the Display) apply to the selected window only, but there is one command to scroll the next window. C-M-v (scroll-other-window) scrolls the window that C-x o would select. It takes arguments, positive and negative, like C-v. (In the minibuffer, C-M-v scrolls the window that contains the minibuffer help display, if any, rather than the next window in the standard cyclic order.)

The command M-x compare-windows lets you compare two files or buffers visible in two windows, by moving through them to the next mismatch. See section M.9 Comparing Files, for details.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

O.4 Displaying in Another Window

C-x 4 is a prefix key for commands that select another window (splitting the window if there is only one) and select a buffer in that window. Different C-x 4 commands have different ways of finding the buffer to select.

C-x 4 b bufname RET
Select buffer bufname in another window. This runs switch-to-buffer-other-window.
C-x 4 C-o bufname RET
Display buffer bufname in another window, but don't select that buffer or that window. This runs display-buffer.
C-x 4 f filename RET
Visit file filename and select its buffer in another window. This runs find-file-other-window. See section M.2 Visiting Files.
C-x 4 d directory RET
Select a Dired buffer for directory directory in another window. This runs dired-other-window. See section AB. Dired, the Directory Editor.
C-x 4 m
Start composing a mail message in another window. This runs mail-other-window; its same-window analogue is C-x m (see section Z. Sending Mail).
C-x 4 .
Find a tag in the current tags table, in another window. This runs find-tag-other-window, the multiple-window variant of M-. (see section W.2 Tags Tables).
C-x 4 r filename RET
Visit file filename read-only, and select its buffer in another window. This runs find-file-read-only-other-window. See section M.2 Visiting Files.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

O.5 Forcing Display in the Same Window

Certain Emacs commands switch to a specific buffer with special contents. For example, M-x shell switches to a buffer named `*Shell*'. By convention, all these commands are written to pop up the buffer in a separate window. But you can specify that certain of these buffers should appear in the selected window.

If you add a buffer name to the list same-window-buffer-names, the effect is that such commands display that particular buffer by switching to it in the selected window. For example, if you add the element "*grep*" to the list, the grep command will display its output buffer in the selected window.

The default value of same-window-buffer-names is not nil: it specifies buffer names `*info*', `*mail*' and `*shell*' (as well as others used by more obscure Emacs packages). This is why M-x shell normally switches to the `*shell*' buffer in the selected window. If you delete this element from the value of same-window-buffer-names, the behavior of M-x shell will change--it will pop up the buffer in another window instead.

You can specify these buffers more generally with the variable same-window-regexps. Set it to a list of regular expressions; then any buffer whose name matches one of those regular expressions is displayed by switching to it in the selected window. (Once again, this applies only to buffers that normally get displayed for you in a separate window.) The default value of this variable specifies Telnet and rlogin buffers.

An analogous feature lets you specify buffers which should be displayed in their own individual frames. See section P.11 Special Buffer Frames.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

O.6 Deleting and Rearranging Windows

C-x 0
Delete the selected window (delete-window). The last character in this key sequence is a zero.
C-x 1
Delete all windows in the selected frame except the selected window (delete-other-windows).
C-x 4 0
Delete the selected window and kill the buffer that was showing in it (kill-buffer-and-window). The last character in this key sequence is a zero.
C-x ^
Make selected window taller (enlarge-window).
C-x }
Make selected window wider (enlarge-window-horizontally).
C-x {
Make selected window narrower (shrink-window-horizontally).
C-x -
Shrink this window if its buffer doesn't need so many lines (shrink-window-if-larger-than-buffer).
C-x +
Make all windows the same height (balance-windows).
Drag-Mouse-1
Dragging a window's mode line up or down with Mouse-1 changes window heights.
Mouse-2
Mouse-2 in a window's mode line deletes all other windows in the frame (mouse-delete-other-windows).
Mouse-3
Mouse-3 in a window's mode line deletes that window (mouse-delete-window), unless the frame has only one window, in which case it buries the current buffer instead and switches to another buffer.
To delete a window, type C-x 0 (delete-window). (That is a zero.) The space occupied by the deleted window is given to an adjacent window (but not the minibuffer window, even if that is active at the time). Once a window is deleted, its attributes are forgotten; only restoring a window configuration can bring it back. Deleting the window has no effect on the buffer it used to display; the buffer continues to exist, and you can select it in any window with C-x b.

C-x 4 0 (kill-buffer-and-window) is a stronger command than C-x 0; it kills the current buffer and then deletes the selected window.

C-x 1 (delete-other-windows) is more powerful in a different way; it deletes all the windows except the selected one (and the minibuffer); the selected window expands to use the whole frame except for the echo area.

You can also delete a window by clicking on its mode line with Mouse-2, and delete all the windows in a frame except one window by clicking on that window's mode line with Mouse-3.

The easiest way to adjust window heights is with a mouse. If you press Mouse-1 on a mode line, you can drag that mode line up or down, changing the heights of the windows above and below it.

To readjust the division of space among vertically adjacent windows, use C-x ^ (enlarge-window). It makes the currently selected window get one line bigger, or as many lines as is specified with a numeric argument. With a negative argument, it makes the selected window smaller. C-x } (enlarge-window-horizontally) makes the selected window wider by the specified number of columns. C-x { (shrink-window-horizontally) makes the selected window narrower by the specified number of columns.

When you make a window bigger, the space comes from one of its neighbors. If this makes any window too small, it is deleted and its space is given to an adjacent window. The minimum size is specified by the variables window-min-height and window-min-width.

The command C-x - (shrink-window-if-larger-than-buffer) reduces the height of the selected window, if it is taller than necessary to show the whole text of the buffer it is displaying. It gives the extra lines to other windows in the frame.

You can also use C-x + (balance-windows) to even out the heights of all the windows in the selected frame.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

O.7 Window Handling Convenience Features and Customization

M-x winner-mode is a global minor mode that records the changes in the window configuration (i.e. how the frames are partitioned into windows), so that you can "undo" them. To undo, use C-x left (winner-undo). If you change your mind while undoing, you can redo the changes you had undone using C-x right (M-x winner-redo). Another way to enable Winner mode is by customizing the variable winner-mode.

The Windmove commands move directionally between neighboring windows in a frame. M-x windmove-right selects the window immediately to the right of the currently selected one, and similarly for the "left," "up," and "down" counterparts. M-x windmove-default-keybindings binds these commands to S-right etc. (Not all terminals support shifted arrow keys, however.)

Follow minor mode (M-x follow-mode) synchronizes several windows on the same buffer so that they always display adjacent sections of that buffer. See section J.8 Follow Mode.

M-x scroll-all-mode provides commands to scroll all visible windows together. You can also turn it on by customizing the variable scroll-all-mode. The commands provided are M-x scroll-all-scroll-down-all, M-x scroll-all-page-down-all and their corresponding "up" equivalents. To make this mode useful, you should bind these commands to appropriate keys.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P. Frames and X Windows

When using the X Window System, you can create multiple windows at the X level in a single Emacs session. Each X window that belongs to Emacs displays a frame which can contain one or several Emacs windows. A frame initially contains a single general-purpose Emacs window which you can subdivide vertically or horizontally into smaller windows. A frame normally contains its own echo area and minibuffer, but you can make frames that don't have these--they use the echo area and minibuffer of another frame.

Editing you do in one frame also affects the other frames. For instance, if you put text in the kill ring in one frame, you can yank it in another frame. If you exit Emacs through C-x C-c in one frame, it terminates all the frames. To delete just one frame, use C-x 5 0 (that is zero, not o).

To avoid confusion, we reserve the word "window" for the subdivisions that Emacs implements, and never use it to refer to a frame.

Emacs compiled for MS-DOS emulates some aspects of the window system so that you can use many of the features described in this chapter. See section AH.1 Keyboard and Mouse on MS-DOS, for more information.

Emacs compiled for MS Windows mostly supports the same features as under X. However, images, tool bars, and tooltips are not yet available in Emacs version 21.1 on MS-Windows.

P.1 Mouse Commands for Editing

Moving, cutting, and pasting, with the mouse.

P.2 Secondary Selection

Cutting without altering point and mark.

P.3 Using the Clipboard

Using the clipboard for selections.

P.4 Following References with the Mouse

Using the mouse to select an item from a list.

P.5 Mouse Clicks for Menus

Mouse clicks that bring up menus.

P.6 Mode Line Mouse Commands

Mouse clicks on the mode line.

P.7 Creating Frames

Creating additional Emacs frames with various contents.

P.8 Frame Commands

Iconifying, deleting, and switching frames.

P.9 Making and Using a Speedbar Frame

How to make and use a speedbar frame.

P.10 Multiple Displays

How one Emacs job can talk to several displays.

P.11 Special Buffer Frames

You can make certain buffers have their own frames.

P.12 Setting Frame Parameters

Changing the colors and other modes of frames.

P.13 Scroll Bars

How to enable and disable scroll bars; how to use them.

P.14 Scrolling With "Wheeled" Mice

Using mouse wheels for scrolling.

P.15 Menu Bars

Enabling and disabling the menu bar.

P.16 Tool Bars

Enabling and disabling the tool bar.

P.17 Using Dialog Boxes

Controlling use of dialog boxes.

P.18 Tooltips (or "Balloon Help")

Showing "tooltips", AKA "balloon help" for active text.

P.19 Mouse Avoidance

Moving the mouse pointer out of the way.

P.20 Non-Window Terminals

Multiple frames on terminals that show only one.

P.21 Using a Mouse in Terminal Emulators

Using the mouse in an XTerm terminal emulator.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.1 Mouse Commands for Editing

The mouse commands for selecting and copying a region are mostly compatible with the xterm program. You can use the same mouse commands for copying between Emacs and other X client programs.

If you select a region with any of these mouse commands, and then immediately afterward type the DELETE function key, it deletes the region that you selected. The BACKSPACE function key and the ASCII character DEL do not do this; if you type any other key in between the mouse command and DELETE, it does not do this.

Mouse-1
Move point to where you click (mouse-set-point). This is normally the left button.

Drag-Mouse-1
Set the region to the text you select by dragging, and copy it to the kill ring (mouse-set-region). You can specify both ends of the region with this single command.
If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse back into the window. This way, you can select regions that don't fit entirely on the screen. The number of lines scrolled per step depends on how far away from the window edge the mouse has gone; the variable mouse-scroll-min-lines specifies a minimum step size.

Mouse-2
Yank the last killed text, where you click (mouse-yank-at-click). This is normally the middle button.

Mouse-3
This command, mouse-save-then-kill, has several functions depending on where you click and the status of the region.
The most basic case is when you click Mouse-1 in one place and then Mouse-3 in another. This selects the text between those two positions as the region. It also copies the new region to the kill ring, so that you can copy it to someplace else.

If you click Mouse-1 in the text, scroll with the scroll bar, and then click Mouse-3, it remembers where point was before scrolling (where you put it with Mouse-1), and uses that position as the other end of the region. This is so that you can select a region that doesn't fit entirely on the screen.

More generally, if you do not have a highlighted region, Mouse-3 selects the text between point and the click position as the region. It does this by setting the mark where point was, and moving point to where you click.

If you have a highlighted region, or if the region was set just before by dragging button 1, Mouse-3 adjusts the nearer end of the region by moving it to where you click. The adjusted region's text also replaces the old region's text in the kill ring.

If you originally specified the region using a double or triple Mouse-1, so that the region is defined to consist of entire words or lines, then adjusting the region with Mouse-3 also proceeds by entire words or lines.

If you use Mouse-3 a second time consecutively, at the same place, that kills the region already selected.

Double-Mouse-1
This key sets the region around the word which you click on. If you click on a character with "symbol" syntax (such as underscore, in C mode), it sets the region around the symbol surrounding that character.
If you click on a character with open-parenthesis or close-parenthesis syntax, it sets the region around the parenthetical grouping which that character starts or ends. If you click on a character with string-delimiter syntax (such as a singlequote or doublequote in C), it sets the region around the string constant (using heuristics to figure out whether that character is the beginning or the end of it).

Double-Drag-Mouse-1
This key selects a region made up of the words you drag across.

Triple-Mouse-1
This key sets the region around the line you click on.

Triple-Drag-Mouse-1
This key selects a region made up of the lines you drag across.
The simplest way to kill text with the mouse is to press Mouse-1 at one end, then press Mouse-3 twice at the other end. See section H.7 Deletion and Killing. To copy the text into the kill ring without deleting it from the buffer, press Mouse-3 just once--or just drag across the text with Mouse-1. Then you can copy it elsewhere by yanking it.

To yank the killed or copied text somewhere else, move the mouse there and press Mouse-2. See section H.8 Yanking. However, if mouse-yank-at-point is non-nil, Mouse-2 yanks at point. Then it does not matter where you click, or even which of the frame's windows you click on. The default value is nil. This variable also affects yanking the secondary selection.

To copy text to another X window, kill it or save it in the kill ring. Under X, this also sets the primary selection. Then use the "paste" or "yank" command of the program operating the other window to insert the text from the selection.

To copy text from another X window, use the "cut" or "copy" command of the program operating the other window, to select the text you want. Then yank it in Emacs with C-y or Mouse-2.

The standard coding system for X selections is compound-text. To specify another coding system for X selections, use C-x RET x or C-x RET X. See section Q.9 Specifying a Coding System.

These cutting and pasting commands also work on MS-Windows.

When Emacs puts text into the kill ring, or rotates text to the front of the kill ring, it sets the primary selection in the X server. This is how other X clients can access the text. Emacs also stores the text in the cut buffer, but only if the text is short enough (the value of x-cut-buffer-max specifies the maximum number of characters); putting long strings in the cut buffer can be slow.

The commands to yank the first entry in the kill ring actually check first for a primary selection in another program; after that, they check for text in the cut buffer. If neither of those sources provides text to yank, the kill ring contents are used.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.2 Secondary Selection

The secondary selection is another way of selecting text using X. It does not use point or the mark, so you can use it to kill text without setting point or the mark.

M-Drag-Mouse-1
Set the secondary selection, with one end at the place where you press down the button, and the other end at the place where you release it (mouse-set-secondary). The highlighting appears and changes as you drag. You can control the appearance of the highlighting by customizing the secondary-selection face (see section AD.2.2.3 Customizing Faces).
If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse back into the window. This way, you can mark regions that don't fit entirely on the screen.

M-Mouse-1
Set one endpoint for the secondary selection (mouse-start-secondary).

M-Mouse-3
Make a secondary selection, using the place specified with M-Mouse-1 as the other end (mouse-secondary-save-then-kill). A second click at the same place kills the secondary selection just made.

M-Mouse-2
Insert the secondary selection where you click (mouse-yank-secondary). This places point at the end of the yanked text.
Double or triple clicking of M-Mouse-1 operates on words and lines, much like Mouse-1.

If mouse-yank-at-point is non-nil, M-Mouse-2 yanks at point. Then it does not matter precisely where you click; all that matters is which window you click on. See section P.1 Mouse Commands for Editing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.3 Using the Clipboard

As well as the primary and secondary selection types, X supports a clipboard selection type which is used by some applications, particularly under OpenWindows and Gnome.

The command M-x menu-bar-enable-clipboard makes the Cut, Paste and Copy menu items, as well as the keys of the same names, all use the clipboard. You can customize the option x-select-enable-clipboard to make the Emacs yank functions consult the clipboard before the primary selection, and to make the kill functions to store in the clipboard as well as the primary selection. Otherwise they do not access the clipboard at all. Using the clipboard is the default on MS-Windows, unlike most systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.4 Following References with the Mouse

Some Emacs buffers display lists of various sorts. These include lists of files, of buffers, of possible completions, of matches for a pattern, and so on.

Since yanking text into these buffers is not very useful, most of them define Mouse-2 specially, as a command to use or view the item you click on.

For example, if you click Mouse-2 on a file name in a Dired buffer, you visit that file. If you click Mouse-2 on an error message in the `*Compilation*' buffer, you go to the source code for that error message. If you click Mouse-2 on a completion in the `*Completions*' buffer, you choose that completion.

You can usually tell when Mouse-2 has this special sort of meaning because the sensitive text highlights when you move the mouse over it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.5 Mouse Clicks for Menus

Mouse clicks modified with the CTRL and SHIFT keys bring up menus.

C-Mouse-1
This menu is for selecting a buffer.
The MSB ("mouse select buffer") global minor mode makes this menu smarter and more customizable. See section N.7.3 Customizing Buffer Menus.

C-Mouse-2
This menu is for specifying faces and other text properties for editing formatted text. See section T.11 Editing Formatted Text.

C-Mouse-3
This menu is mode-specific. For most modes if Menu-bar mode is on, this menu has the same items as all the mode-specific menu-bar menus put together. Some modes may specify a different menu for this button.(2) If Menu-bar mode is off, this menu contains all the items which would be present in the menu bar--not just the mode-specific ones--so that you can access them without having to display the menu bar.

S-Mouse-1
This menu is for specifying the frame's principal font.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.6 Mode Line Mouse Commands

You can use mouse clicks on window mode lines to select and manipulate windows.

Mouse-1
Mouse-1 on a mode line selects the window above. By dragging Mouse-1 on the mode line, you can move it, thus changing the height of the windows above and below.

Mouse-2
Mouse-2 on a mode line expands that window to fill its frame.

Mouse-3
Mouse-3 on a mode line deletes the window above. If the frame has only one window, it buries the current buffer instead and switches to another buffer.

C-Mouse-2
C-Mouse-2 on a mode line splits the window above horizontally, above the place in the mode line where you click.
C-Mouse-2 on a scroll bar splits the corresponding window vertically, unless you are using an X toolkit's implementation of scroll bars. See section O.2 Splitting Windows.

The commands above apply to areas of the mode line which do not have special mouse bindings of their own. Some areas, such as the buffer name and the major mode name, have their own special mouse bindings. Emacs displays information about these bindings when you hold the mouse over such a place (see section P.18 Tooltips (or "Balloon Help")).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.7 Creating Frames

The prefix key C-x 5 is analogous to C-x 4, with parallel subcommands. The difference is that C-x 5 commands create a new frame rather than just a new window in the selected frame (see section O.4 Displaying in Another Window). If an existing visible or iconified frame already displays the requested material, these commands use the existing frame, after raising or deiconifying as necessary.

The various C-x 5 commands differ in how they find or create the buffer to select:

C-x 5 2
Create a new frame (make-frame-command).
C-x 5 b bufname RET
Select buffer bufname in another frame. This runs switch-to-buffer-other-frame.
C-x 5 f filename RET
Visit file filename and select its buffer in another frame. This runs find-file-other-frame. See section M.2 Visiting Files.
C-x 5 d directory RET
Select a Dired buffer for directory directory in another frame. This runs dired-other-frame. See section AB. Dired, the Directory Editor.
C-x 5 m
Start composing a mail message in another frame. This runs mail-other-frame. It is the other-frame variant of C-x m. See section Z. Sending Mail.
C-x 5 .
Find a tag in the current tag table in another frame. This runs find-tag-other-frame, the multiple-frame variant of M-.. See section W.2 Tags Tables.
C-x 5 r filename RET
Visit file filename read-only, and select its buffer in another frame. This runs find-file-read-only-other-frame. See section M.2 Visiting Files.
You can control the appearance of new frames you create by setting the frame parameters in default-frame-alist. You can use the variable initial-frame-alist to specify parameters that affect only the initial frame. See section `Initial Parameters' in The Emacs Lisp Reference Manual, for more information.

The easiest way to specify the principal font for all your Emacs frames is with an X resource (see section AE.7 Font Specification Options), but you can also do it by modifying default-frame-alist to specify the font parameter, as shown here:
(add-to-list 'default-frame-alist '(font . "10x20"))
Here's a similar example for specifying a foreground color:
(add-to-list 'default-frame-alist '(background-color . "blue"))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.8 Frame Commands

The following commands let you create, delete and operate on frames:

C-z
Iconify the selected Emacs frame (iconify-or-deiconify-frame). The normal meaning of C-z, to suspend Emacs, is not useful under a window system, so it has a different binding in that case.
If you type this command on an Emacs frame's icon, it deiconifies the frame.

C-x 5 0
Delete the selected frame (delete-frame). This is not allowed if there is only one frame.

C-x 5 o
Select another frame, raise it, and warp the mouse to it so that it stays selected. If you repeat this command, it cycles through all the frames on your terminal.

C-x 5 1
Delete all frames except the selected one.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.9 Making and Using a Speedbar Frame

An Emacs frame can have a speedbar, which is a vertical window that serves as a scrollable menu of files you could visit and tags within those files. To create a speedbar, type M-x speedbar; this creates a speedbar window for the selected frame. From then on, you can click on a file name in the speedbar to visit that file in the corresponding Emacs frame, or click on a tag name to jump to that tag in the Emacs frame.

Initially the speedbar lists the immediate contents of the current directory, one file per line. Each line also has a box, `[+]' or `<+>', that you can click on with Mouse-2 to "open up" the contents of that item. If the line names a directory, opening it adds the contents of that directory to the speedbar display, underneath the directory's own line. If the line lists an ordinary file, opening it up adds a list of the tags in that file to the speedbar display. When a file is opened up, the `[+]' changes to `[-]'; you can click on that box to "close up" that file (hide its contents).

Some major modes, including Rmail mode, Info, and GUD, have specialized ways of putting useful items into the speedbar for you to select. For example, in Rmail mode, the speedbar shows a list of Rmail files, and lets you move the current message to another Rmail file by clicking on its `<M>' box.

A speedbar belongs to one Emacs frame, and always operates on that frame. If you use multiple frames, you can make a speedbar for some or all of the frames; type M-x speedbar in any given frame to make a speedbar for it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.10 Multiple Displays

A single Emacs can talk to more than one X display. Initially, Emacs uses just one display--the one specified with the DISPLAY environment variable or with the `--display' option (see section AE.2 Initial Options). To connect to another display, use the command make-frame-on-display:

M-x make-frame-on-display RET display RET
Create a new frame on display display.
A single X server can handle more than one screen. When you open frames on two screens belonging to one server, Emacs knows they share a single keyboard, and it treats all the commands arriving from these screens as a single stream of input.

When you open frames on different X servers, Emacs makes a separate input stream for each server. This way, two users can type simultaneously on the two displays, and Emacs will not garble their input. Each server also has its own selected frame. The commands you enter with a particular X server apply to that server's selected frame.

Despite these features, people using the same Emacs job from different displays can still interfere with each other if they are not careful. For example, if any one types C-x C-c, that exits the Emacs job for all of them!

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.11 Special Buffer Frames

You can make certain chosen buffers, for which Emacs normally creates a second window when you have just one window, appear in special frames of their own. To do this, set the variable special-display-buffer-names to a list of buffer names; any buffer whose name is in that list automatically gets a special frame, when an Emacs command wants to display it "in another window."

For example, if you set the variable this way,
(setq special-display-buffer-names
      '("*Completions*" "*grep*" "*tex-shell*"))
then completion lists, grep output and the TeX mode shell buffer get individual frames of their own. These frames, and the windows in them, are never automatically split or reused for any other buffers. They continue to show the buffers they were created for, unless you alter them by hand. Killing the special buffer deletes its frame automatically.

More generally, you can set special-display-regexps to a list of regular expressions; then a buffer gets its own frame if its name matches any of those regular expressions. (Once again, this applies only to buffers that normally get displayed for you in a separate window.)

The variable special-display-frame-alist specifies the frame parameters for these frames. It has a default value, so you don't need to set it.

For those who know Lisp, an element of special-display-buffer-names or special-display-regexps can also be a list. Then the first element is the buffer name or regular expression; the rest of the list specifies how to create the frame. It can be an association list specifying frame parameter values; these values take precedence over parameter values specified in special-display-frame-alist. Alternatively, it can have this form:
(function args...)
where function is a symbol. Then the frame is constructed by calling function; its first argument is the buffer, and its remaining arguments are args.

An analogous feature lets you specify buffers which should be displayed in the selected window. See section O.5 Forcing Display in the Same Window. The same-window feature takes precedence over the special-frame feature; therefore, if you add a buffer name to special-display-buffer-names and it has no effect, check to see whether that feature is also in use for the same buffer name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.12 Setting Frame Parameters

This section describes commands for altering the display style and window management behavior of the selected frame.

M-x set-foreground-color RET color RET
Specify color color for the foreground of the selected frame. (This also changes the foreground color of the default face.)

M-x set-background-color RET color RET
Specify color color for the background of the selected frame. (This also changes the background color of the default face.)

M-x set-cursor-color RET color RET
Specify color color for the cursor of the selected frame.

M-x set-mouse-color RET color RET
Specify color color for the mouse cursor when it is over the selected frame.

M-x set-border-color RET color RET
Specify color color for the border of the selected frame.

M-x list-colors-display
Display the defined color names and show what the colors look like. This command is somewhat slow.

M-x auto-raise-mode
Toggle whether or not the selected frame should auto-raise. Auto-raise means that every time you move the mouse onto the frame, it raises the frame.
Note that this auto-raise feature is implemented by Emacs itself. Some window managers also implement auto-raise. If you enable auto-raise for Emacs frames in your X window manager, it should work, but it is beyond Emacs's control and therefore auto-raise-mode has no effect on it.

M-x auto-lower-mode
Toggle whether or not the selected frame should auto-lower. Auto-lower means that every time you move the mouse off the frame, the frame moves to the bottom of the stack of X windows.
The command auto-lower-mode has no effect on auto-lower implemented by the X window manager. To control that, you must use the appropriate window manager features.

M-x set-frame-font RET font RET
Specify font font as the principal font for the selected frame. The principal font controls several face attributes of the default face (see section J.1 Using Multiple Typefaces). For example, if the principal font has a height of 12 pt, all text will be drawn in 12 pt fonts, unless you use another face that specifies a different height. See section AE.7 Font Specification Options, for ways to list the available fonts on your system.
You can also set a frame's principal font through a pop-up menu. Press S-Mouse-1 to activate this menu.
In Emacs versions that use an X toolkit, the color-setting and font-setting functions don't affect menus and the menu bar, since they are displayed by their own widget classes. To change the appearance of the menus and menu bar, you must use X resources (see section AE.13 X Resources). See section AE.8 Window Color Options, regarding colors. See section AE.7 Font Specification Options, regarding choice of font.

Colors, fonts, and other attributes of the frame's display can also be customized by setting frame parameters in the variable default-frame-alist (see section P.7 Creating Frames). For a detailed description of frame parameters and customization, see section `Frame Parameters' in The Emacs Lisp Reference Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.13 Scroll Bars

When using X, Emacs normally makes a scroll bar at the left of each Emacs window.(3) The scroll bar runs the height of the window, and shows a moving rectangular inner box which represents the portion of the buffer currently displayed. The entire height of the scroll bar represents the entire length of the buffer.

You can use Mouse-2 (normally, the middle button) in the scroll bar to move or drag the inner box up and down. If you move it to the top of the scroll bar, you see the top of the buffer. If you move it to the bottom of the scroll bar, you see the bottom of the buffer.

The left and right buttons in the scroll bar scroll by controlled increments. Mouse-1 (normally, the left button) moves the line at the level where you click up to the top of the window. Mouse-3 (normally, the right button) moves the line at the top of the window down to the level where you click. By clicking repeatedly in the same place, you can scroll by the same distance over and over.

If you are using Emacs's own implementation of scroll bars, as opposed to scroll bars from an X toolkit, you can also click C-Mouse-2 in the scroll bar to split a window vertically. The split occurs on the line where you click.

You can enable or disable Scroll Bar mode with the command M-x scroll-bar-mode. With no argument, it toggles the use of scroll bars. With an argument, it turns use of scroll bars on if and only if the argument is positive. This command applies to all frames, including frames yet to be created. Customize the option scroll-bar-mode to control the use of scroll bars at startup. You can use it to specify that they are placed at the right of windows if you prefer that. You can use the X resource `verticalScrollBars' to control the initial setting of Scroll Bar mode similarly. See section AE.13 X Resources.

To enable or disable scroll bars for just the selected frame, use the M-x toggle-scroll-bar command.

You can control the scroll bar width by changing the value of the scroll-bar-width frame parameter.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.14 Scrolling With "Wheeled" Mice

Some mice have a "wheel" instead of a third button. You can usually click the wheel to act as either Mouse-2 or Mouse-3, depending on the setup. You can also use the wheel to scroll windows instead of using the scroll bar or keyboard commands. To do so, turn on Mouse Wheel global minor mode with the command M-x mouse-wheel-mode or by customizing the option mouse-wheel-mode. Support for the wheel depends on the system generating appropriate events for Emacs.

The variables mouse-wheel-follow-mouse and mouse-wheel-scroll-amount determine where and by how much buffers are scrolled.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.15 Menu Bars

You can turn display of menu bars on or off with M-x menu-bar-mode or by customizing the option menu-bar-mode. With no argument, this command toggles Menu Bar mode, a minor mode. With an argument, the command turns Menu Bar mode on if the argument is positive, off if the argument is not positive. You can use the X resource `menuBarLines' to control the initial setting of Menu Bar mode. See section AE.13 X Resources.

Expert users often turn off the menu bar, especially on text-only terminals, where this makes one additional line available for text. If the menu bar is off, you can still pop up a menu of its contents with C-Mouse-3 on a display which supports pop-up menus. See section P.5 Mouse Clicks for Menus.

See section B.4 The Menu Bar, for information on how to invoke commands with the menu bar.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.16 Tool Bars

The tool bar is a line (or multiple lines) of icons at the top of the Emacs window. You can click on these icons with the mouse to do various jobs.

The global tool bar contains general commands. Some major modes define their own tool bars to replace it. A few "special" modes that are not designed for ordinary editing remove some items from the global tool bar.

Tool bars work only on a graphical display. The tool bar uses colored XPM icons if Emacs was built with XPM support. Otherwise, the tool bar uses monochrome icons (PBM or XBM format).

You can turn display of tool bars on or off with M-x tool-bar-mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.17 Using Dialog Boxes

A dialog box is a special kind of menu for asking you a yes-or-no question or some other special question. Many Emacs commands use a dialog box to ask a yes-or-no question, if you used the mouse to invoke the command to begin with.

You can customize the option use-dialog-box to suppress the use of dialog boxes. This also controls whether to use file selection windows (but those are not supported on all platforms).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.18 Tooltips (or "Balloon Help")

Tooltips are small X windows displaying a help string at the current mouse position, typically over text--including the mode line--which can be activated with the mouse or other keys. (This facility is sometimes known as balloon help.) Help text may be available for menu items too.

To use tooltips, enable Tooltip mode with the command M-x tooltip-mode. The customization group tooltip controls various aspects of how tooltips work. When Tooltip mode is disabled, the help text is displayed in the echo area instead.

As of Emacs 21.1, tooltips are not supported on MS-Windows. So help text always appears in the echo area.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.19 Mouse Avoidance

Mouse Avoidance mode keeps the window system mouse pointer away from point, to avoid obscuring text. Whenever it moves the mouse, it also raises the frame. To use Mouse Avoidance mode, customize the option mouse-avoidance-mode. You can set this to various values to move the mouse in several ways:

banish
Move the mouse to the upper-right corner on any key-press;
exile
Move the mouse to the corner only if the cursor gets too close, and allow it to return once the cursor is out of the way;
jump
If the cursor gets too close to the mouse, displace the mouse a random distance & direction;
animate
As jump, but shows steps along the way for illusion of motion;
cat-and-mouse
The same as animate;
proteus
As animate, but changes the shape of the mouse pointer too.
You can also use the command M-x mouse-avoidance-mode to enable the mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.20 Non-Window Terminals

If your terminal does not have a window system that Emacs supports, then it can display only one Emacs frame at a time. However, you can still create multiple Emacs frames, and switch between them. Switching frames on these terminals is much like switching between different window configurations.

Use C-x 5 2 to create a new frame and switch to it; use C-x 5 o to cycle through the existing frames; use C-x 5 0 to delete the current frame.

Each frame has a number to distinguish it. If your terminal can display only one frame at a time, the selected frame's number n appears near the beginning of the mode line, in the form `Fn'.

`Fn' is actually the frame's name. You can also specify a different name if you wish, and you can select a frame by its name. Use the command M-x set-frame-name RET name RET to specify a new name for the selected frame, and use M-x select-frame-by-name RET name RET to select a frame according to its name. The name you specify appears in the mode line when the frame is selected.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

P.21 Using a Mouse in Terminal Emulators

Some terminal emulators under X support mouse clicks in the terminal window. In a terminal emulator which is compatible with xterm, you can use M-x xterm-mouse-mode to enable simple use of the mouse--only single clicks are supported. The normal xterm mouse functionality is still available by holding down the SHIFT key when you press the mouse button. The Linux console supports this mode if it has support for the mouse enabled, e.g. using the gpm daemon.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q. International Character Set Support

Emacs supports a wide variety of international character sets, including European variants of the Latin alphabet, as well as Chinese, Cyrillic, Devanagari (Hindi and Marathi), Ethiopic, Greek, Hebrew, IPA, Japanese, Korean, Lao, Thai, Tibetan, and Vietnamese scripts. These features have been merged from the modified version of Emacs known as MULE (for "MULti-lingual Enhancement to GNU Emacs")

Emacs also supports various encodings of these characters used by other internationalized software, such as word processors and mailers.

Emacs allows editing text with international characters by supporting all the related activities:

You can visit files with non-ASCII characters, save non-ASCII text, and pass non-ASCII text between Emacs and programs it invokes (such as compilers, spell-checkers, and mailers). Setting your language environment (see section Q.3 Language Environments) takes care of setting up the coding systems and other options for a specific language or culture. Alternatively, you can specify how Emacs should encode or decode text for each command; see Q.9 Specifying a Coding System.

You can display non-ASCII characters encoded by the various scripts. This works by using appropriate fonts on X and similar graphics displays (see section Q.11 Defining fontsets), and by sending special codes to text-only displays (see section Q.9 Specifying a Coding System). If some characters are displayed incorrectly, refer to Q.12 Undisplayable Characters, which describes possible problems and explains how to solve them.

You can insert non-ASCII characters or search for them. To do that, you can specify an input method (see section Q.5 Selecting an Input Method) suitable for your language, or use the default input method set up when you set your language environment. (Emacs input methods are part of the Leim package, which must be installed for you to be able to use them.) If your keyboard can produce non-ASCII characters, you can select an appropriate keyboard coding system (see section Q.9 Specifying a Coding System), and Emacs will accept those characters. Latin-1 characters can also be input by using the C-x 8 prefix, see C-x 8. On X Window systems, your locale should be set to an appropriate value to make sure Emacs interprets keyboard input correctly, see locales.

The rest of this chapter describes these issues in detail.

Q.1 Introduction to International Character Sets

Basic concepts of multibyte characters.

Q.2 Enabling Multibyte Characters

Controlling whether to use multibyte characters.

Q.3 Language Environments

Setting things up for the language you use.

Q.4 Input Methods

Entering text characters not on your keyboard.

Q.5 Selecting an Input Method

Specifying your choice of input methods.

Q.6 Unibyte and Multibyte Non-ASCII characters

How single-byte characters convert to multibyte.

Q.7 Coding Systems

Character set conversion when you read and write files, and so on.

Q.8 Recognizing Coding Systems

How Emacs figures out which conversion to use.

Q.9 Specifying a Coding System

Various ways to choose which conversion to use.

Q.10 Fontsets

Fontsets are collections of fonts that cover the whole spectrum of characters.

Q.11 Defining fontsets

Defining a new fontset.

Q.12 Undisplayable Characters

When characters don't display.

Q.13 Single-byte Character Set Support

You can pick one European character set to use without multibyte characters.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.1 Introduction to International Character Sets

The users of international character sets and scripts have established many more-or-less standard coding systems for storing files. Emacs internally uses a single multibyte character encoding, so that it can intermix characters from all these scripts in a single buffer or string. This encoding represents each non-ASCII character as a sequence of bytes in the range 0200 through 0377. Emacs translates between the multibyte character encoding and various other coding systems when reading and writing files, when exchanging data with subprocesses, and (in some cases) in the C-q command (see section Q.6 Unibyte and Multibyte Non-ASCII characters).

The command C-h h (view-hello-file) displays the file `etc/HELLO', which shows how to say "hello" in many languages. This illustrates various scripts. If some characters can't be displayed on your terminal, they appear as `?' or as hollow boxes (see section Q.12 Undisplayable Characters).

Keyboards, even in the countries where these character sets are used, generally don't have keys for all the characters in them. So Emacs supports various input methods, typically one for each script or language, to make it convenient to type them.

The prefix key C-x RET is used for commands that pertain to multibyte characters, coding systems, and input methods.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.2 Enabling Multibyte Characters

You can enable or disable multibyte character support, either for Emacs as a whole, or for a single buffer. When multibyte characters are disabled in a buffer, then each byte in that buffer represents a character, even codes 0200 through 0377. The old features for supporting the European character sets, ISO Latin-1 and ISO Latin-2, work as they did in Emacs 19 and also work for the other ISO 8859 character sets.

However, there is no need to turn off multibyte character support to use ISO Latin; the Emacs multibyte character set includes all the characters in these character sets, and Emacs can translate automatically to and from the ISO codes.

By default, Emacs starts in multibyte mode, because that allows you to use all the supported languages and scripts without limitations.

To edit a particular file in unibyte representation, visit it using find-file-literally. See section M.2 Visiting Files. To convert a buffer in multibyte representation into a single-byte representation of the same characters, the easiest way is to save the contents in a file, kill the buffer, and find the file again with find-file-literally. You can also use C-x RET c (universal-coding-system-argument) and specify `raw-text' as the coding system with which to find or save a file. See section Q.9 Specifying a Coding System. Finding a file as `raw-text' doesn't disable format conversion, uncompression and auto mode selection as find-file-literally does.

To turn off multibyte character support by default, start Emacs with the `--unibyte' option (see section AE.2 Initial Options), or set the environment variable EMACS_UNIBYTE. You can also customize enable-multibyte-characters or, equivalently, directly set the variable default-enable-multibyte-characters to nil in your init file to have basically the same effect as `--unibyte'.

To convert a unibyte session to a multibyte session, set default-enable-multibyte-characters to t. Buffers which were created in the unibyte session before you turn on multibyte support will stay unibyte. You can turn on multibyte support in a specific buffer by invoking the command toggle-enable-multibyte-characters in that buffer.

With `--unibyte', multibyte strings are not created during initialization from the values of environment variables, `/etc/passwd' entries etc. that contain non-ASCII 8-bit characters.

Emacs normally loads Lisp files as multibyte, regardless of whether you used `--unibyte'. This includes the Emacs initialization file, `.emacs', and the initialization files of Emacs packages such as Gnus. However, you can specify unibyte loading for a particular Lisp file, by putting `-*-unibyte: t;-*-' in a comment on the first line. Then that file is always loaded as unibyte text, even if you did not start Emacs with `--unibyte'. The motivation for these conventions is that it is more reliable to always load any particular Lisp file in the same way. However, you can load a Lisp file as unibyte, on any one occasion, by typing C-x RET c raw-text RET immediately before loading it.

The mode line indicates whether multibyte character support is enabled in the current buffer. If it is, there are two or more characters (most often two dashes) before the colon near the beginning of the mode line. When multibyte characters are not enabled, just one dash precedes the colon.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.3 Language Environments

All supported character sets are supported in Emacs buffers whenever multibyte characters are enabled; there is no need to select a particular language in order to display its characters in an Emacs buffer. However, it is important to select a language environment in order to set various defaults. The language environment really represents a choice of preferred script (more or less) rather than a choice of language.

The language environment controls which coding systems to recognize when reading text (see section Q.8 Recognizing Coding Systems). This applies to files, incoming mail, netnews, and any other text you read into Emacs. It may also specify the default coding system to use when you create a file. Each language environment also specifies a default input method.

To select a language environment, customize the option current-language-environment or use the command M-x set-language-environment. It makes no difference which buffer is current when you use this command, because the effects apply globally to the Emacs session. The supported language environments include:

Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8, Czech, Devanagari, Dutch, English, Ethiopic, German, Greek, Hebrew, IPA, Japanese, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Latin-8 (Celtic), Latin-9 (updated Latin-1, with the Euro sign), Polish, Romanian, Slovak, Slovenian, Spanish, Thai, Tibetan, Turkish, and Vietnamese.

To display the script(s) used by your language environment on a graphical display, you need to have a suitable font. If some of the characters appear as empty boxes, you should install the GNU Intlfonts package, which includes fonts for all supported scripts.(4) See section Q.10 Fontsets, for more details about setting up your fonts.

Some operating systems let you specify the character-set locale you are using by setting the locale environment variables LC_ALL, LC_CTYPE, or LANG.(5) During startup, Emacs looks up your character-set locale's name in the system locale alias table, matches its canonical name against entries in the value of the variables locale-charset-language-names and locale-language-names, and selects the corresponding language environment if a match is found. (The former variable overrides the latter.) It also adjusts the display table and terminal coding system, the locale coding system, the preferred coding system as needed for the locale, and--last but not least--the way Emacs decodes non-ASCII characters sent by your keyboard.

If you modify the LC_ALL, LC_CTYPE, or LANG environment variables while running Emacs, you may want to invoke the set-locale-environment function afterwards to readjust the language environment from the new locale.

The set-locale-environment function normally uses the preferred coding system established by the language environment to decode system messages. But if your locale matches an entry in the variable locale-preferred-coding-systems, Emacs uses the corresponding coding system instead. For example, if the locale `ja_JP.PCK' matches japanese-shift-jis in locale-preferred-coding-systems, Emacs uses that encoding even though it might normally use japanese-iso-8bit.

You can override the language environment chosen at startup with explicit use of the command set-language-environment, or with customization of current-language-environment in your init file.

To display information about the effects of a certain language environment lang-env, use the command C-h L lang-env RET (describe-language-environment). This tells you which languages this language environment is useful for, and lists the character sets, coding systems, and input methods that go with it. It also shows some sample text to illustrate scripts used in this language environment. By default, this command describes the chosen language environment.

You can customize any language environment with the normal hook set-language-environment-hook. The command set-language-environment runs that hook after setting up the new language environment. The hook functions can test for a specific language environment by checking the variable current-language-environment. This hook is where you should put non-default settings for specific language environment, such as coding systems for keyboard input and terminal output, the default input method, etc.

Before it starts to set up the new language environment, set-language-environment first runs the hook exit-language-environment-hook. This hook is useful for undoing customizations that were made with set-language-environment-hook. For instance, if you set up a special key binding in a specific language environment using set-language-environment-hook, you should set up exit-language-environment-hook to restore the normal binding for that key.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.4 Input Methods

An input method is a kind of character conversion designed specifically for interactive input. In Emacs, typically each language has its own input method; sometimes several languages which use the same characters can share one input method. A few languages support several input methods.

The simplest kind of input method works by mapping ASCII letters into another alphabet; this allows you to use one other alphabet instead of ASCII. The Greek and Russian input methods work this way.

A more powerful technique is composition: converting sequences of characters into one letter. Many European input methods use composition to produce a single non-ASCII letter from a sequence that consists of a letter followed by accent characters (or vice versa). For example, some methods convert the sequence a' into a single accented letter. These input methods have no special commands of their own; all they do is compose sequences of printing characters.

The input methods for syllabic scripts typically use mapping followed by composition. The input methods for Thai and Korean work this way. First, letters are mapped into symbols for particular sounds or tone marks; then, sequences of these which make up a whole syllable are mapped into one syllable sign.

Chinese and Japanese require more complex methods. In Chinese input methods, first you enter the phonetic spelling of a Chinese word (in input method chinese-py, among others), or a sequence of portions of the character (input methods chinese-4corner and chinese-sw, and others). One input sequence typically corresponds to many possible Chinese characters. You select the one you mean using keys such as C-f, C-b, C-n, C-p, and digits, which have special meanings in this situation.

The possible characters are conceptually arranged in several rows, with each row holding up to 10 alternatives. Normally, Emacs displays just one row at a time, in the echo area; (i/j) appears at the beginning, to indicate that this is the ith row out of a total of j rows. Type C-n or C-p to display the next row or the previous row.

Type C-f and C-b to move forward and backward among the alternatives in the current row. As you do this, Emacs highlights the current alternative with a special color; type C-SPC to select the current alternative and use it as input. The alternatives in the row are also numbered; the number appears before the alternative. Typing a digit n selects the nth alternative of the current row and uses it as input.

TAB in these Chinese input methods displays a buffer showing all the possible characters at once; then clicking Mouse-2 on one of them selects that alternative. The keys C-f, C-b, C-n, C-p, and digits continue to work as usual, but they do the highlighting in the buffer showing the possible characters, rather than in the echo area.

In Japanese input methods, first you input a whole word using phonetic spelling; then, after the word is in the buffer, Emacs converts it into one or more characters using a large dictionary. One phonetic spelling corresponds to a number of different Japanese words; to select one of them, use C-n and C-p to cycle through the alternatives.

Sometimes it is useful to cut off input method processing so that the characters you have just entered will not combine with subsequent characters. For example, in input method latin-1-postfix, the sequence e ' combines to form an `e' with an accent. What if you want to enter them as separate characters?

One way is to type the accent twice; this is a special feature for entering the separate letter and accent. For example, e ' ' gives you the two characters `e''. Another way is to type another letter after the e---something that won't combine with that--and immediately delete it. For example, you could type e e DEL ' to get separate `e' and `''.

Another method, more general but not quite as easy to type, is to use C-\ C-\ between two characters to stop them from combining. This is the command C-\ (toggle-input-method) used twice. See section Q.5 Selecting an Input Method.

C-\ C-\ is especially useful inside an incremental search, because it stops waiting for more characters to combine, and starts searching for what you have already entered.

The variables input-method-highlight-flag and input-method-verbose-flag control how input methods explain what is happening. If input-method-highlight-flag is non-nil, the partial sequence is highlighted in the buffer (for most input methods--some disable this feature). If input-method-verbose-flag is non-nil, the list of possible characters to type next is displayed in the echo area (but not when you are in the minibuffer).

Input methods are implemented in the separate Leim package: they are available only if the system administrator used Leim when building Emacs. If Emacs was built without Leim, you will find that no input methods are defined.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.5 Selecting an Input Method

C-\
Enable or disable use of the selected input method.

C-x RET C-\ method RET
Select a new input method for the current buffer.

C-h I method RET

C-h C-\ method RET
Describe the input method method (describe-input-method). By default, it describes the current input method (if any). This description should give you the full details of how to use any particular input method.

M-x list-input-methods
Display a list of all the supported input methods.
To choose an input method for the current buffer, use C-x RET C-\ (set-input-method). This command reads the input method name from the minibuffer; the name normally starts with the language environment that it is meant to be used with. The variable current-input-method records which input method is selected. Input methods use various sequences of ASCII characters to stand for non-ASCII characters. Sometimes it is useful to turn off the input method temporarily. To do this, type C-\ (toggle-input-method). To reenable the input method, type C-\ again.

If you type C-\ and you have not yet selected an input method, it prompts for you to specify one. This has the same effect as using C-x RET C-\ to specify an input method.

When invoked with a numeric argument, as in C-u C-\, toggle-input-method always prompts you for an input method, suggesting the most recently selected one as the default.

Selecting a language environment specifies a default input method for use in various buffers. When you have a default input method, you can select it in the current buffer by typing C-\. The variable default-input-method specifies the default input method (nil means there is none).

In some language environments, which support several different input methods, you might want to use an input method different from the default chosen by set-language-environment. You can instruct Emacs to select a different default input method for a certain language environment, if you wish, by using set-language-environment-hook (see section set-language-environment-hook). For example:
(defun my-chinese-setup ()
  "Set up my private Chinese environment."
  (if (equal current-language-environment "Chinese-GB")
      (setq default-input-method "chinese-tonepy")))
(add-hook 'set-language-environment-hook 'my-chinese-setup)
This sets the default input method to be chinese-tonepy whenever you choose a Chinese-GB language environment.

Some input methods for alphabetic scripts work by (in effect) remapping the keyboard to emulate various keyboard layouts commonly used for those scripts. How to do this remapping properly depends on your actual keyboard layout. To specify which layout your keyboard has, use the command M-x quail-set-keyboard-layout.

To display a list of all the supported input methods, type M-x list-input-methods. The list gives information about each input method, including the string that stands for it in the mode line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.6 Unibyte and Multibyte Non-ASCII characters

When multibyte characters are enabled, character codes 0240 (octal) through 0377 (octal) are not really legitimate in the buffer. The valid non-ASCII printing characters have codes that start from 0400.

If you type a self-inserting character in the range 0240 through 0377, or if you use C-q to insert one, Emacs assumes you intended to use one of the ISO Latin-n character sets, and converts it to the Emacs code representing that Latin-n character. You select which ISO Latin character set to use through your choice of language environment (see section Q.3 Language Environments). If you do not specify a choice, the default is Latin-1.

If you insert a character in the range 0200 through 0237, which forms the eight-bit-control character set, it is inserted literally. You should normally avoid doing this since buffers containing such characters have to be written out in either the emacs-mule or raw-text coding system, which is usually not what you want.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.7 Coding Systems

Users of various languages have established many more-or-less standard coding systems for representing them. Emacs does not use these coding systems internally; instead, it converts from various coding systems to its own system when reading data, and converts the internal coding system to other coding systems when writing data. Conversion is possible in reading or writing files, in sending or receiving from the terminal, and in exchanging data with subprocesses.

Emacs assigns a name to each coding system. Most coding systems are used for one language, and the name of the coding system starts with the language name. Some coding systems are used for several languages; their names usually start with `iso'. There are also special coding systems no-conversion, raw-text and emacs-mule which do not convert printing characters at all.

A special class of coding systems, collectively known as codepages, is designed to support text encoded by MS-Windows and MS-DOS software. To use any of these systems, you need to create it with M-x codepage-setup. See section AH.6 International Support on MS-DOS. After creating the coding system for the codepage, you can use it as any other coding system. For example, to visit a file encoded in codepage 850, type C-x RET c cp850 RET C-x C-f filename RET.

In addition to converting various representations of non-ASCII characters, a coding system can perform end-of-line conversion. Emacs handles three different conventions for how to separate lines in a file: newline, carriage-return linefeed, and just carriage-return.

C-h C coding RET
Describe coding system coding.

C-h C RET
Describe the coding systems currently in use.

M-x list-coding-systems
Display a list of all the supported coding systems.
The command C-h C (describe-coding-system) displays information about particular coding systems. You can specify a coding system name as the argument; alternatively, with an empty argument, it describes the coding systems currently selected for various purposes, both in the current buffer and as the defaults, and the priority list for recognizing coding systems (see section Q.8 Recognizing Coding Systems).

To display a list of all the supported coding systems, type M-x list-coding-systems. The list gives information about each coding system, including the letter that stands for it in the mode line (see section B.3 The Mode Line).

Each of the coding systems that appear in this list--except for no-conversion, which means no conversion of any kind--specifies how and whether to convert printing characters, but leaves the choice of end-of-line conversion to be decided based on the contents of each file. For example, if the file appears to use the sequence carriage-return linefeed to separate lines, DOS end-of-line conversion will be used.

Each of the listed coding systems has three variants which specify exactly what to do for end-of-line conversion:

...-unix
Don't do any end-of-line conversion; assume the file uses newline to separate lines. (This is the convention normally used on Unix and GNU systems.)

...-dos
Assume the file uses carriage-return linefeed to separate lines, and do the appropriate conversion. (This is the convention normally used on Microsoft systems.(6))

...-mac
Assume the file uses carriage-return to separate lines, and do the appropriate conversion. (This is the convention normally used on the Macintosh system.)
These variant coding systems are omitted from the list-coding-systems display for brevity, since they are entirely predictable. For example, the coding system iso-latin-1 has variants iso-latin-1-unix, iso-latin-1-dos and iso-latin-1-mac.

The coding system raw-text is good for a file which is mainly ASCII text, but may contain byte values above 127 which are not meant to encode non-ASCII characters. With raw-text, Emacs copies those byte values unchanged, and sets enable-multibyte-characters to nil in the current buffer so that they will be interpreted properly. raw-text handles end-of-line conversion in the usual way, based on the data encountered, and has the usual three variants to specify the kind of end-of-line conversion to use.

In contrast, the coding system no-conversion specifies no character code conversion at all--none for non-ASCII byte values and none for end of line. This is useful for reading or writing binary files, tar files, and other files that must be examined verbatim. It, too, sets enable-multibyte-characters to nil.

The easiest way to edit a file with no conversion of any kind is with the M-x find-file-literally command. This uses no-conversion, and also suppresses other Emacs features that might convert the file contents before you see them. See section M.2 Visiting Files.

The coding system emacs-mule means that the file contains non-ASCII characters stored with the internal Emacs encoding. It handles end-of-line conversion based on the data encountered, and has the usual three variants to specify the kind of end-of-line conversion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.8 Recognizing Coding Systems

Emacs tries to recognize which coding system to use for a given text as an integral part of reading that text. (This applies to files being read, output from subprocesses, text from X selections, etc.) Emacs can select the right coding system automatically most of the time--once you have specified your preferences.

Some coding systems can be recognized or distinguished by which byte sequences appear in the data. However, there are coding systems that cannot be distinguished, not even potentially. For example, there is no way to distinguish between Latin-1 and Latin-2; they use the same byte values with different meanings.

Emacs handles this situation by means of a priority list of coding systems. Whenever Emacs reads a file, if you do not specify the coding system to use, Emacs checks the data against each coding system, starting with the first in priority and working down the list, until it finds a coding system that fits the data. Then it converts the file contents assuming that they are represented in this coding system.

The priority list of coding systems depends on the selected language environment (see section Q.3 Language Environments). For example, if you use French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use Czech, you probably want Latin-2 to be preferred. This is one of the reasons to specify a language environment.

However, you can alter the priority list in detail with the command M-x prefer-coding-system. This command reads the name of a coding system from the minibuffer, and adds it to the front of the priority list, so that it is preferred to all others. If you use this command several times, each use adds one element to the front of the priority list.

If you use a coding system that specifies the end-of-line conversion type, such as iso-8859-1-dos, what this means is that Emacs should attempt to recognize iso-8859-1 with priority, and should use DOS end-of-line conversion when it does recognize iso-8859-1.

Sometimes a file name indicates which coding system to use for the file. The variable file-coding-system-alist specifies this correspondence. There is a special function modify-coding-system-alist for adding elements to this list. For example, to read and write all `.txt' files using the coding system china-iso-8bit, you can execute this Lisp expression:
(modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
The first argument should be file, the second argument should be a regular expression that determines which files this applies to, and the third argument says which coding system to use for these files.

Emacs recognizes which kind of end-of-line conversion to use based on the contents of the file: if it sees only carriage-returns, or only carriage-return linefeed sequences, then it chooses the end-of-line conversion accordingly. You can inhibit the automatic use of end-of-line conversion by setting the variable inhibit-eol-conversion to non-nil. If you do that, DOS-style files will be displayed with the `^M' characters visible in the buffer; some people prefer this to the more subtle `(DOS)' end-of-line type indication near the left edge of the mode line (see section eol-mnemonic).

By default, the automatic detection of coding system is sensitive to escape sequences. If Emacs sees a sequence of characters that begin with an escape character, and the sequence is valid as an ISO-2022 code, that tells Emacs to use one of the ISO-2022 encodings to decode the file.

However, there may be cases that you want to read escape sequences in a file as is. In such a case, you can set the variable inhibit-iso-escape-detection to non-nil. Then the code detection ignores any escape sequences, and never uses an ISO-2022 encoding. The result is that all escape sequences become visible in the buffer.

The default value of inhibit-iso-escape-detection is nil. We recommend that you not change it permanently, only for one specific operation. That's because many Emacs Lisp source files in the Emacs distribution contain non-ASCII characters encoded in the coding system iso-2022-7bit, and they won't be decoded correctly when you visit those files if you suppress the escape sequence detection.

You can specify the coding system for a particular file using the `-*-...-*-' construct at the beginning of a file, or a local variables list at the end (see section AD.2.5 Local Variables in Files). You do this by defining a value for the "variable" named coding. Emacs does not really have a variable coding; instead of setting a variable, this uses the specified coding system for the file. For example, `-*-mode: C; coding: latin-1;-*-' specifies use of the Latin-1 coding system, as well as C mode. When you specify the coding explicitly in the file, that overrides file-coding-system-alist.

The variables auto-coding-alist and auto-coding-regexp-alist are the strongest way to specify the coding system for certain patterns of file names, or for files containing certain patterns; these variables even override `-*-coding:-*-' tags in the file itself. Emacs uses auto-coding-alist for tar and archive files, to prevent it from being confused by a `-*-coding:-*-' tag in a member of the archive and thinking it applies to the archive file as a whole. Likewise, Emacs uses auto-coding-regexp-alist to ensure that RMAIL files, whose names in general don't match any particular pattern, are decoded correctly.

If Emacs recognizes the encoding of a file incorrectly, you can reread the file using the correct coding system by typing C-x RET c coding-system RET M-x revert-buffer RET. To see what coding system Emacs actually used to decode the file, look at the coding system mnemonic letter near the left edge of the mode line (see section B.3 The Mode Line), or type C-h C RET.

Once Emacs has chosen a coding system for a buffer, it stores that coding system in buffer-file-coding-system and uses that coding system, by default, for operations that write from this buffer into a file. This includes the commands save-buffer and write-region. If you want to write files from this buffer using a different coding system, you can specify a different coding system for the buffer using set-buffer-file-coding-system (see section Q.9 Specifying a Coding System).

You can insert any possible character into any Emacs buffer, but most coding systems can only handle some of the possible characters. This means that it is possible for you to insert characters that cannot be encoded with the coding system that will be used to save the buffer. For example, you could start with an ASCII file and insert a few Latin-1 characters into it, or you could edit a text file in Polish encoded in iso-8859-2 and add some Russian words to it. When you save the buffer, Emacs cannot use the current value of buffer-file-coding-system, because the characters you added cannot be encoded by that coding system.

When that happens, Emacs tries the most-preferred coding system (set by M-x prefer-coding-system or M-x set-language-environment), and if that coding system can safely encode all of the characters in the buffer, Emacs uses it, and stores its value in buffer-file-coding-system. Otherwise, Emacs displays a list of coding systems suitable for encoding the buffer's contents, and asks you to choose one of those coding systems.

If you insert the unsuitable characters in a mail message, Emacs behaves a bit differently. It additionally checks whether the most-preferred coding system is recommended for use in MIME messages; if not, Emacs tells you that the most-preferred coding system is not recommended and prompts you for another coding system. This is so you won't inadvertently send a message encoded in a way that your recipient's mail software will have difficulty decoding. (If you do want to use the most-preferred coding system, you can still type its name in response to the question.)

When you send a message with Mail mode (see section Z. Sending Mail), Emacs has four different ways to determine the coding system to use for encoding the message text. It tries the buffer's own value of buffer-file-coding-system, if that is non-nil. Otherwise, it uses the value of sendmail-coding-system, if that is non-nil. The third way is to use the default coding system for new files, which is controlled by your choice of language environment, if that is non-nil. If all of these three values are nil, Emacs encodes outgoing mail using the Latin-1 coding system.

When you get new mail in Rmail, each message is translated automatically from the coding system it is written in, as if it were a separate file. This uses the priority list of coding systems that you have specified. If a MIME message specifies a character set, Rmail obeys that specification, unless rmail-decode-mime-charset is nil.

For reading and saving Rmail files themselves, Emacs uses the coding system specified by the variable rmail-file-coding-system. The default value is nil, which means that Rmail files are not translated (they are read and written in the Emacs internal character code).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.9 Specifying a Coding System

In cases where Emacs does not automatically choose the right coding system, you can use these commands to specify one:

C-x RET f coding RET
Use coding system coding for the visited file in the current buffer.

C-x RET c coding RET
Specify coding system coding for the immediately following command.

C-x RET k coding RET
Use coding system coding for keyboard input.

C-x RET t coding RET
Use coding system coding for terminal output.

C-x RET p input-coding RET output-coding RET
Use coding systems input-coding and output-coding for subprocess input and output in the current buffer.

C-x RET x coding RET
Use coding system coding for transferring selections to and from other programs through the window system.

C-x RET X coding RET
Use coding system coding for transferring one selection--the next one--to or from the window system.
The command C-x RET f (set-buffer-file-coding-system) specifies the file coding system for the current buffer--in other words, which coding system to use when saving or rereading the visited file. You specify which coding system using the minibuffer. Since this command applies to a file you have already visited, it affects only the way the file is saved.

Another way to specify the coding system for a file is when you visit the file. First use the command C-x RET c (universal-coding-system-argument); this command uses the minibuffer to read a coding system name. After you exit the minibuffer, the specified coding system is used for the immediately following command.

So if the immediately following command is C-x C-f, for example, it reads the file using that coding system (and records the coding system for when the file is saved). Or if the immediately following command is C-x C-w, it writes the file using that coding system. Other file commands affected by a specified coding system include C-x C-i and C-x C-v, as well as the other-window variants of C-x C-f.

C-x RET c also affects commands that start subprocesses, including M-x shell (see section AC.15 Running Shell Commands from Emacs).

However, if the immediately following command does not use the coding system, then C-x RET c ultimately has no effect.

An easy way to visit a file with no conversion is with the M-x find-file-literally command. See section M.2 Visiting Files.

The variable default-buffer-file-coding-system specifies the choice of coding system to use when you create a new file. It applies when you find a new file, and when you create a buffer and then save it in a file. Selecting a language environment typically sets this variable to a good choice of default coding system for that language environment.

The command C-x RET t (set-terminal-coding-system) specifies the coding system for terminal output. If you specify a character code for terminal output, all characters output to the terminal are translated into that coding system.

This feature is useful for certain character-only terminals built to support specific languages or character sets--for example, European terminals that support one of the ISO Latin character sets. You need to specify the terminal coding system when using multibyte text, so that Emacs knows which characters the terminal can actually handle.

By default, output to the terminal is not translated at all, unless Emacs can deduce the proper coding system from your terminal type or your locale specification (see section Q.3 Language Environments).

The command C-x RET k (set-keyboard-coding-system) or the Custom option keyboard-coding-system specifies the coding system for keyboard input. Character-code translation of keyboard input is useful for terminals with keys that send non-ASCII graphic characters--for example, some terminals designed for ISO Latin-1 or subsets of it.

By default, keyboard input is not translated at all.

There is a similarity between using a coding system translation for keyboard input, and using an input method: both define sequences of keyboard input that translate into single characters. However, input methods are designed to be convenient for interactive use by humans, and the sequences that are translated are typically sequences of ASCII printing characters. Coding systems typically translate sequences of non-graphic characters.

The command C-x RET x (set-selection-coding-system) specifies the coding system for sending selected text to the window system, and for receiving the text of selections made in other applications. This command applies to all subsequent selections, until you override it by using the command again. The command C-x RET X (set-next-selection-coding-system) specifies the coding system for the next selection made in Emacs or read by Emacs.

The command C-x RET p (set-buffer-process-coding-system) specifies the coding system for input and output to a subprocess. This command applies to the current buffer; normally, each subprocess has its own buffer, and thus you can use this command to specify translation to and from a particular subprocess by giving the command in the corresponding buffer.

The default for translation of process input and output depends on the current language environment.

The variable file-name-coding-system specifies a coding system to use for encoding file names. If you set the variable to a coding system name (as a Lisp symbol or a string), Emacs encodes file names using that coding system for all file operations. This makes it possible to use non-ASCII characters in file names--or, at least, those non-ASCII characters which the specified coding system can encode.

If file-name-coding-system is nil, Emacs uses a default coding system determined by the selected language environment. In the default language environment, any non-ASCII characters in file names are not encoded specially; they appear in the file system using the internal Emacs representation.

Warning: if you change file-name-coding-system (or the language environment) in the middle of an Emacs session, problems can result if you have already visited files whose names were encoded using the earlier coding system and cannot be encoded (or are encoded differently) under the new coding system. If you try to save one of these buffers under the visited file name, saving may use the wrong file name, or it may get an error. If such a problem happens, use C-x C-w to specify a new file name for that buffer.

The variable locale-coding-system specifies a coding system to use when encoding and decoding system strings such as system error messages and format-time-string formats and time stamps. That coding system is also used for decoding non-ASCII keyboard input on X Window systems. You should choose a coding system that is compatible with the underlying system's text representation, which is normally specified by one of the environment variables LC_ALL, LC_CTYPE, and LANG. (The first one, in the order specified above, whose value is nonempty is the one that determines the text representation.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.10 Fontsets

A font for X typically defines shapes for a single alphabet or script. Therefore, displaying the entire range of scripts that Emacs supports requires a collection of many fonts. In Emacs, such a collection is called a fontset. A fontset is defined by a list of fonts, each assigned to handle a range of character codes.

Each fontset has a name, like a font. The available X fonts are defined by the X server; fontsets, however, are defined within Emacs itself. Once you have defined a fontset, you can use it within Emacs by specifying its name, anywhere that you could use a single font. Of course, Emacs fontsets can use only the fonts that the X server supports; if certain characters appear on the screen as hollow boxes, this means that the fontset in use for them has no font for those characters.(7)

Emacs creates two fontsets automatically: the standard fontset and the startup fontset. The standard fontset is most likely to have fonts for a wide variety of non-ASCII characters; however, this is not the default for Emacs to use. (By default, Emacs tries to find a font that has bold and italic variants.) You can specify use of the standard fontset with the `-fn' option, or with the `Font' X resource (see section AE.7 Font Specification Options). For example,
emacs -fn fontset-standard
A fontset does not necessarily specify a font for every character code. If a fontset specifies no font for a certain character, or if it specifies a font that does not exist on your system, then it cannot display that character properly. It will display that character as an empty box instead.

The fontset height and width are determined by the ASCII characters (that is, by the font used for ASCII characters in that fontset). If another font in the fontset has a different height, or a different width, then characters assigned to that font are clipped to the fontset's size. If highlight-wrong-size-font is non-nil, a box is displayed around these wrong-size characters as well.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.11 Defining fontsets

Emacs creates a standard fontset automatically according to the value of standard-fontset-spec. This fontset's name is
-*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
or just `fontset-standard' for short.

Bold, italic, and bold-italic variants of the standard fontset are created automatically. Their names have `bold' instead of `medium', or `i' instead of `r', or both.

If you specify a default ASCII font with the `Font' resource or the `-fn' argument, Emacs generates a fontset from it automatically. This is the startup fontset and its name is fontset-startup. It does this by replacing the foundry, family, add_style, and average_width fields of the font name with `*', replacing charset_registry field with `fontset', and replacing charset_encoding field with `startup', then using the resulting string to specify a fontset.

For instance, if you start Emacs this way,
emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
Emacs generates the following fontset and uses it for the initial X window frame:
-*-*-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
With the X resource `Emacs.Font', you can specify a fontset name just like an actual font name. But be careful not to specify a fontset name in a wildcard resource like `Emacs*Font'---that wildcard specification matches various other resources, such as for menus, and menus cannot handle fontsets.

You can specify additional fontsets using X resources named `Fontset-n', where n is an integer starting from 0. The resource value should have this form:
fontpattern, [charsetname:fontname]...
fontpattern should have the form of a standard X font name, except for the last two fields. They should have the form `fontset-alias'.

The fontset has two names, one long and one short. The long name is fontpattern. The short name is `fontset-alias'. You can refer to the fontset by either name.

The construct `charset:font' specifies which font to use (in this fontset) for one particular character set. Here, charset is the name of a character set, and font is the font to use for that character set. You can use this construct any number of times in defining one fontset.

For the other character sets, Emacs chooses a font based on fontpattern. It replaces `fontset-alias' with values that describe the character set. For the ASCII character font, `fontset-alias' is replaced with `ISO8859-1'.

In addition, when several consecutive fields are wildcards, Emacs collapses them into a single wildcard. This is to prevent use of auto-scaled fonts. Fonts made by scaling larger fonts are not usable for editing, and scaling a smaller font is not useful because it is better to use the smaller font in its own size, which is what Emacs does.

Thus if fontpattern is this,
-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
the font specification for ASCII characters would be this:
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
and the font specification for Chinese GB2312 characters would be this:
-*-fixed-medium-r-normal-*-24-*-gb2312*-*
You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that have `song ti' or `fangsong ti' in family field. In such a case, `Fontset-n' can be specified as below:
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
Then, the font specifications for all but Chinese GB2312 characters have `fixed' in the family field, and the font specification for Chinese GB2312 characters has a wild card `*' in the family field.

The function that processes the fontset resource value to create the fontset is called create-fontset-from-fontset-spec. You can also call this function explicitly to create a fontset.

See section AE.7 Font Specification Options, for more information about font naming in X.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.12 Undisplayable Characters

Your terminal may be unable to display some non-ASCII characters. Most non-windowing terminals can only use a single character set (use the variable default-terminal-coding-system (see section Q.9 Specifying a Coding System) to tell Emacs which one); characters which can't be encoded in that coding system are displayed as `?' by default.

Windowing terminals can display a broader range of characters, but you may not have fonts installed for all of them; characters that have no font appear as a hollow box.

If you use Latin-1 characters but your terminal can't display Latin-1, you can arrange to display mnemonic ASCII sequences instead, e.g. `"o' for o-umlaut. Load the library `iso-ascii' to do this.

If your terminal can display Latin-1, you can display characters from other European character sets using a mixture of equivalent Latin-1 characters and ASCII mnemonics. Use the Custom option latin1-display to enable this. The mnemonic ASCII sequences mostly correspond to those of the prefix input methods.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Q.13 Single-byte Character Set Support

The ISO 8859 Latin-n character sets define character codes in the range 0240 to 0377 octal (160 to 255 decimal) to handle the accented letters and punctuation needed by various European languages (and some non-European ones). If you disable multibyte characters, Emacs can still handle one of these character codes at a time. To specify which of these codes to use, invoke M-x set-language-environment and specify a suitable language environment such as `Latin-n'.

For more information about unibyte operation, see Q.2 Enabling Multibyte Characters. Note particularly that you probably want to ensure that your initialization files are read as unibyte if they contain non-ASCII characters.

Emacs can also display those characters, provided the terminal or font in use supports them. This works automatically. Alternatively, if you are using a window system, Emacs can also display single-byte characters through fontsets, in effect by displaying the equivalent multibyte characters according to the current language environment. To request this, set the variable unibyte-display-via-language-environment to a non-nil value.

If your terminal does not support display of the Latin-1 character set, Emacs can display these characters as ASCII sequences which at least give you a clear idea of what the characters are. To do this, load the library iso-ascii. Similar libraries for other Latin-n character sets could be implemented, but we don't have them yet.

Normally non-ISO-8859 characters (decimal codes between 128 and 159 inclusive) are displayed as octal escapes. You can change this for non-standard "extended" versions of ISO-8859 character sets by using the function standard-display-8bit in the disp-table library.

There are several ways you can input single-byte non-ASCII characters:

If your keyboard can generate character codes 128 (decimal) and up, representing non-ASCII characters, you can type those character codes directly.
On a windowing terminal, you should not need to do anything special to use these keys; they should simply work. On a text-only terminal, you should use the command M-x set-keyboard-coding-system or the Custom option keyboard-coding-system to specify which coding system your keyboard uses (see section Q.9 Specifying a Coding System). Enabling this feature will probably require you to use ESC to type Meta characters; however, on a Linux console or in xterm, you can arrange for Meta to be converted to ESC and still be able type 8-bit characters present directly on the keyboard or using Compose or AltGr keys. See section B.5 Kinds of User Input.

You can use an input method for the selected language environment. See section Q.4 Input Methods. When you use an input method in a unibyte buffer, the non-ASCII character you specify with it is converted to unibyte.

For Latin-1 only, you can use the key C-x 8 as a "compose character" prefix for entry of non-ASCII Latin-1 printing characters. C-x 8 is good for insertion (in the minibuffer as well as other buffers), for searching, and in any other context where a key sequence is allowed.
C-x 8 works by loading the iso-transl library. Once that library is loaded, the ALT modifier key, if you have one, serves the same purpose as C-x 8; use ALT together with an accent character to modify the following letter. In addition, if you have keys for the Latin-1 "dead accent characters," they too are defined to compose with the following character, once iso-transl is loaded. Use C-x 8 C-h to list the available translations as mnemonic command names.

For Latin-1, Latin-2 and Latin-3, M-x iso-accents-mode enables a minor mode that works much like the latin-1-prefix input method, but does not depend on having the input methods installed. This mode is buffer-local. It can be customized for various languages with M-x iso-accents-customize.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

R. Major Modes

Emacs provides many alternative major modes, each of which customizes Emacs for editing text of a particular sort. The major modes are mutually exclusive, and each buffer has one major mode at any time. The mode line normally shows the name of the current major mode, in parentheses (see section B.3 The Mode Line).

The least specialized major mode is called Fundamental mode. This mode has no mode-specific redefinitions or variable settings, so that each Emacs command behaves in its most general manner, and each option is in its default state. For editing text of a specific type that Emacs knows about, such as Lisp code or English text, you should switch to the appropriate major mode, such as Lisp mode or Text mode.

Selecting a major mode changes the meanings of a few keys to become more specifically adapted to the language being edited. The ones that are changed frequently are TAB, DEL, and C-j. The prefix key C-c normally contains mode-specific commands. In addition, the commands which handle comments use the mode to determine how comments are to be delimited. Many major modes redefine the syntactical properties of characters appearing in the buffer. See section AD.6 The Syntax Table.

The major modes fall into three major groups. The first group contains modes for normal text, either plain or with mark-up. It includes Text mode, HTML mode, SGML mode, TeX mode and Outline mode. The second group contains modes for specific programming languages. These include Lisp mode (which has several variants), C mode, Fortran mode, and others. The remaining major modes are not intended for use on users' files; they are used in buffers created for specific purposes by Emacs, such as Dired mode for buffers made by Dired (see section AB. Dired, the Directory Editor), Mail mode for buffers made by C-x m (see section Z. Sending Mail), and Shell mode for buffers used for communicating with an inferior shell process (see section AC.15.2 Interactive Inferior Shell).

Most programming-language major modes specify that only blank lines separate paragraphs. This is to make the paragraph commands useful. (See section T.3 Paragraphs.) They also cause Auto Fill mode to use the definition of TAB to indent the new lines it creates. This is because most lines in a program are usually indented (see section S. Indentation).

R.1 How Major Modes are Chosen

How major modes are specified or chosen.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

R.1 How Major Modes are Chosen

You can select a major mode explicitly for the current buffer, but most of the time Emacs determines which mode to use based on the file name or on special text in the file.

Explicit selection of a new major mode is done with a M-x command. From the name of a major mode, add -mode to get the name of a command to select that mode. Thus, you can enter Lisp mode by executing M-x lisp-mode.

When you visit a file, Emacs usually chooses the right major mode based on the file's name. For example, files whose names end in `.c' are edited in C mode. The correspondence between file names and major modes is controlled by the variable auto-mode-alist. Its value is a list in which each element has this form,
(regexp . mode-function)
or this form,
(regexp mode-function flag)
For example, one element normally found in the list has the form ("\\.c\\'" . c-mode), and it is responsible for selecting C mode for files whose names end in `.c'. (Note that `\\' is needed in Lisp syntax to include a `\' in the string, which must be used to suppress the special meaning of `.' in regexps.) If the element has the form (regexp mode-function flag) and flag is non-nil, then after calling mode-function, the suffix that matched regexp is discarded and the list is searched again for another match.

You can specify which major mode should be used for editing a certain file by a special sort of text in the first nonblank line of the file. The mode name should appear in this line both preceded and followed by `-*-'. Other text may appear on the line as well. For example,
;-*-Lisp-*-
tells Emacs to use Lisp mode. Such an explicit specification overrides any defaults based on the file name. Note how the semicolon is used to make Lisp treat this line as a comment.

Another format of mode specification is
-*- mode: modename;-*-
which allows you to specify local variables as well, like this:
-*- mode: modename; var: value; ... -*-
See section AD.2.5 Local Variables in Files, for more information about this.

When a file's contents begin with `#!', it can serve as an executable shell command, which works by running an interpreter named on the file's first line. The rest of the file is used as input to the interpreter.

When you visit such a file in Emacs, if the file's name does not specify a major mode, Emacs uses the interpreter name on the first line to choose a mode. If the first line is the name of a recognized interpreter program, such as `perl' or `tcl', Emacs uses a mode appropriate for programs for that interpreter. The variable interpreter-mode-alist specifies the correspondence between interpreter program names and major modes.

When the first line starts with `#!', you cannot (on many systems) use the `-*-' feature on the first line, because the system would get confused when running the interpreter. So Emacs looks for `-*-' on the second line in such files as well as on the first line.

When you visit a file that does not specify a major mode to use, or when you create a new buffer with C-x b, the variable default-major-mode specifies which major mode to use. Normally its value is the symbol fundamental-mode, which specifies Fundamental mode. If default-major-mode is nil, the major mode is taken from the previously current buffer.

If you change the major mode of a buffer, you can go back to the major mode Emacs would choose automatically: use the command M-x normal-mode to do this. This is the same function that find-file calls to choose the major mode. It also processes the file's local variables list (if any).

The commands C-x C-w and set-visited-file-name change to a new major mode if the new file name implies a mode (see section M.3 Saving Files). However, this does not happen if the buffer contents specify a major mode, and certain "special" major modes do not allow the mode to change. You can turn off this mode-changing feature by setting change-major-mode-with-file-name to nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

S. Indentation

This chapter describes the Emacs commands that add, remove, or adjust indentation.

TAB
Indent the current line "appropriately" in a mode-dependent fashion.
C-j
Perform RET followed by TAB (newline-and-indent).
M-^
Merge the previous and the current line (delete-indentation). This would cancel out the effect of C-j.
C-M-o
Split the current line at point; text on the line after point becomes a new line indented to the same column where point is located (split-line).
M-m
Move (forward or back) to the first nonblank character on the current line (back-to-indentation).
C-M-\
Indent several lines to the same column (indent-region).
C-x TAB
Shift a block of lines rigidly right or left (indent-rigidly).
M-i
Indent from point to the next prespecified tab stop column (tab-to-tab-stop).
M-x indent-relative
Indent from point to under an indentation point in the previous line.
Most programming languages have some indentation convention. For Lisp code, lines are indented according to their nesting in parentheses. The same general idea is used for C code, though many details are different.

Whatever the language, to indent a line, use the TAB command. Each major mode defines this command to perform the sort of indentation appropriate for the particular language. In Lisp mode, TAB aligns the line according to its depth in parentheses. No matter where in the line you are when you type TAB, it aligns the line as a whole. In C mode, TAB implements a subtle and sophisticated indentation style that knows about many aspects of C syntax.

In Text mode, TAB runs the command tab-to-tab-stop, which indents to the next tab stop column. You can set the tab stops with M-x edit-tab-stops.

Normally, TAB inserts an optimal mix of tabs and spaces for the intended indentation. See section S.3 Tabs vs. Spaces, for how to prevent use of tabs.

S.1 Indentation Commands and Techniques

Various commands and techniques for indentation.

S.2 Tab Stops

You can set arbitrary "tab stops" and then indent to the next tab stop when you want to.

S.3 Tabs vs. Spaces

You can request indentation using just spaces.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

S.1 Indentation Commands and Techniques

To move over the indentation on a line, do M-m (back-to-indentation). This command, given anywhere on a line, positions point at the first nonblank character on the line.

To insert an indented line before the current line, do C-a C-o TAB. To make an indented line after the current line, use C-e C-j.

If you just want to insert a tab character in the buffer, you can type C-q TAB.

C-M-o (split-line) moves the text from point to the end of the line vertically down, so that the current line becomes two lines. C-M-o first moves point forward over any spaces and tabs. Then it inserts after point a newline and enough indentation to reach the same column point is on. Point remains before the inserted newline; in this regard, C-M-o resembles C-o.

To join two lines cleanly, use the M-^ (delete-indentation) command. It deletes the indentation at the front of the current line, and the line boundary as well, replacing them with a single space. As a special case (useful for Lisp code) the single space is omitted if the characters to be joined are consecutive open parentheses or closing parentheses, or if the junction follows another newline. To delete just the indentation of a line, go to the beginning of the line and use M-\ (delete-horizontal-space), which deletes all spaces and tabs around the cursor.

If you have a fill prefix, M-^ deletes the fill prefix if it appears after the newline that is deleted. See section T.5.4 The Fill Prefix.

There are also commands for changing the indentation of several lines at once. C-M-\ (indent-region) applies to all the lines that begin in the region; it indents each line in the "usual" way, as if you had typed TAB at the beginning of the line. A numeric argument specifies the column to indent to, and each line is shifted left or right so that its first nonblank character appears in that column. C-x TAB (indent-rigidly) moves all of the lines in the region right by its argument (left, for negative arguments). The whole group of lines moves rigidly sideways, which is how the command gets its name.

M-x indent-relative indents at point based on the previous line (actually, the last nonempty line). It inserts whitespace at point, moving point, until it is underneath an indentation point in the previous line. An indentation point is the end of a sequence of whitespace or the end of the line. If point is farther right than any indentation point in the previous line, the whitespace before point is deleted and the first indentation point then applicable is used. If no indentation point is applicable even then, indent-relative runs tab-to-tab-stop (see section S.2 Tab Stops), unless it is called with a numeric argument, in which case it does nothing.

indent-relative is the definition of TAB in Indented Text mode. See section T. Commands for Human Languages.

See section T.11.6 Indentation in Formatted Text, for another way of specifying the indentation for part of your text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

S.2 Tab Stops

For typing in tables, you can use Text mode's definition of TAB, tab-to-tab-stop. This command inserts indentation before point, enough to reach the next tab stop column. If you are not in Text mode, this command can be found on the key M-i.

You can specify the tab stops used by M-i. They are stored in a variable called tab-stop-list, as a list of column-numbers in increasing order.

The convenient way to set the tab stops is with M-x edit-tab-stops, which creates and selects a buffer containing a description of the tab stop settings. You can edit this buffer to specify different tab stops, and then type C-c C-c to make those new tab stops take effect. edit-tab-stops records which buffer was current when you invoked it, and stores the tab stops back in that buffer; normally all buffers share the same tab stops and changing them in one buffer affects all, but if you happen to make tab-stop-list local in one buffer then edit-tab-stops in that buffer will edit the local settings.

Here is what the text representing the tab stops looks like for ordinary tab stops every eight columns.
        :       :       :       :       :       :
0         1         2         3         4
0123456789012345678901234567890123456789012345678
To install changes, type C-c C-c
The first line contains a colon at each tab stop. The remaining lines are present just to help you see where the colons are and know what to do.

Note that the tab stops that control tab-to-tab-stop have nothing to do with displaying tab characters in the buffer. See section J.12 Customization of Display, for more information on that.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

S.3 Tabs vs. Spaces

Emacs normally uses both tabs and spaces to indent lines. If you prefer, all indentation can be made from spaces only. To request this, set indent-tabs-mode to nil. This is a per-buffer variable, so altering the variable affects only the current buffer, but there is a default value which you can change as well. See section AD.2.4 Local Variables.

There are also commands to convert tabs to spaces or vice versa, always preserving the columns of all nonblank text. M-x tabify scans the region for sequences of spaces, and converts sequences of at least three spaces to tabs if that can be done without changing indentation. M-x untabify changes all tabs in the region to appropriate numbers of spaces.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T. Commands for Human Languages

The term text has two widespread meanings in our area of the computer field. One is data that is a sequence of characters. Any file that you edit with Emacs is text, in this sense of the word. The other meaning is more restrictive: a sequence of characters in a human language for humans to read (possibly after processing by a text formatter), as opposed to a program or commands for a program.

Human languages have syntactic/stylistic conventions that can be supported or used to advantage by editor commands: conventions involving words, sentences, paragraphs, and capital letters. This chapter describes Emacs commands for all of these things. There are also commands for filling, which means rearranging the lines of a paragraph to be approximately equal in length. The commands for moving over and killing words, sentences and paragraphs, while intended primarily for editing text, are also often useful for editing programs.

Emacs has several major modes for editing human-language text. If the file contains text pure and simple, use Text mode, which customizes Emacs in small ways for the syntactic conventions of text. Outline mode provides special commands for operating on text with an outline structure.

For text which contains embedded commands for text formatters, Emacs has other major modes, each for a particular text formatter. Thus, for input to TeX, you would use TeX mode. For input to nroff, use Nroff mode.

Instead of using a text formatter, you can edit formatted text in WYSIWYG style ("what you see is what you get"), with Enriched mode. Then the formatting appears on the screen in Emacs while you edit.

The "automatic typing" features may be useful when writing text. See section `Autotyping' in Features for Automatic Typing.

T.1 Words

Moving over and killing words.

T.2 Sentences

Moving over and killing sentences.

T.3 Paragraphs

Moving over paragraphs.

T.4 Pages

Moving over pages.

T.5 Filling Text

Filling or justifying text.

T.6 Case Conversion Commands

Changing the case of text.

T.7 Text Mode

The major modes for editing text files.

T.8 Outline Mode

Editing outlines.

T.9 TeX Mode

Editing input to the formatter TeX.

T.10 Nroff Mode

Editing input to the formatter nroff.

T.11 Editing Formatted Text

Editing formatted text directly in WYSIWYG fashion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.1 Words

Emacs has commands for moving over or operating on words. By convention, the keys for them are all Meta characters.

M-f
Move forward over a word (forward-word).
M-b
Move backward over a word (backward-word).
M-d
Kill up to the end of a word (kill-word).
M-DEL
Kill back to the beginning of a word (backward-kill-word).
M-@
Mark the end of the next word (mark-word).
M-t
Transpose two words or drag a word across other words (transpose-words).
Notice how these keys form a series that parallels the character-based C-f, C-b, C-d, DEL and C-t. M-@ is cognate to C-@, which is an alias for C-SPC.

The commands M-f (forward-word) and M-b (backward-word) move forward and backward over words. These Meta characters are thus analogous to the corresponding control characters, C-f and C-b, which move over single characters in the text. The analogy extends to numeric arguments, which serve as repeat counts. M-f with a negative argument moves backward, and M-b with a negative argument moves forward. Forward motion stops right after the last letter of the word, while backward motion stops right before the first letter.

M-d (kill-word) kills the word after point. To be precise, it kills everything from point to the place M-f would move to. Thus, if point is in the middle of a word, M-d kills just the part after point. If some punctuation comes between point and the next word, it is killed along with the word. (If you wish to kill only the next word but not the punctuation before it, simply do M-f to get the end, and kill the word backwards with M-DEL.) M-d takes arguments just like M-f.

M-DEL (backward-kill-word) kills the word before point. It kills everything from point back to where M-b would move to. If point is after the space in `FOO, BAR', then `FOO, ' is killed. (If you wish to kill just `FOO', and not the comma and the space, use M-b M-d instead of M-DEL.)

M-t (transpose-words) exchanges the word before or containing point with the following word. The delimiter characters between the words do not move. For example, `FOO, BAR' transposes into `BAR, FOO' rather than `BAR FOO,'. See section L.2 Transposing Text, for more on transposition and on arguments to transposition commands.

To operate on the next n words with an operation which applies between point and mark, you can either set the mark at point and then move over the words, or you can use the command M-@ (mark-word) which does not move point, but sets the mark where M-f would move to. M-@ accepts a numeric argument that says how many words to scan for the place to put the mark. In Transient Mark mode, this command activates the mark.

The word commands' understanding of syntax is completely controlled by the syntax table. Any character can, for example, be declared to be a word delimiter. See section AD.6 The Syntax Table.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.2 Sentences

The Emacs commands for manipulating sentences and paragraphs are mostly on Meta keys, so as to be like the word-handling commands.

M-a
Move back to the beginning of the sentence (backward-sentence).
M-e
Move forward to the end of the sentence (forward-sentence).
M-k
Kill forward to the end of the sentence (kill-sentence).
C-x DEL
Kill back to the beginning of the sentence (backward-kill-sentence).
The commands M-a and M-e (backward-sentence and forward-sentence) move to the beginning and end of the current sentence, respectively. They were chosen to resemble C-a and C-e, which move to the beginning and end of a line. Unlike them, M-a and M-e if repeated or given numeric arguments move over successive sentences.

Moving backward over a sentence places point just before the first character of the sentence; moving forward places point right after the punctuation that ends the sentence. Neither one moves over the whitespace at the sentence boundary.

Just as C-a and C-e have a kill command, C-k, to go with them, so M-a and M-e have a corresponding kill command M-k (kill-sentence) which kills from point to the end of the sentence. With minus one as an argument it kills back to the beginning of the sentence. Larger arguments serve as a repeat count. There is also a command, C-x DEL (backward-kill-sentence), for killing back to the beginning of a sentence. This command is useful when you change your mind in the middle of composing text.

The sentence commands assume that you follow the American typist's convention of putting two spaces at the end of a sentence; they consider a sentence to end wherever there is a `.', `?' or `!' followed by the end of a line or two spaces, with any number of `)', `]', `'', or `"' characters allowed in between. A sentence also begins or ends wherever a paragraph begins or ends.

The variable sentence-end controls recognition of the end of a sentence. It is a regexp that matches the last few characters of a sentence, together with the whitespace following the sentence. Its normal value is
"[.?!][]\"')]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
This example is explained in the section on regexps. See section K.5 Syntax of Regular Expressions.

If you want to use just one space between sentences, you should set sentence-end to this value:
"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
You should also set the variable sentence-end-double-space to nil so that the fill commands expect and leave just one space at the end of a sentence. Note that this makes it impossible to distinguish between periods that end sentences and those that indicate abbreviations.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.3 Paragraphs

The Emacs commands for manipulating paragraphs are also Meta keys.

M-{
Move back to previous paragraph beginning (backward-paragraph).
M-}
Move forward to next paragraph end (forward-paragraph).
M-h
Put point and mark around this or next paragraph (mark-paragraph).
M-{ moves to the beginning of the current or previous paragraph, while M-} moves to the end of the current or next paragraph. Blank lines and text-formatter command lines separate paragraphs and are not considered part of any paragraph. In Fundamental mode, but not in Text mode, an indented line also starts a new paragraph. (If a paragraph is preceded by a blank line, these commands treat that blank line as the beginning of the paragraph.)

In major modes for programs, paragraphs begin and end only at blank lines. This makes the paragraph commands continue to be useful even though there are no paragraphs per se.

When there is a fill prefix, then paragraphs are delimited by all lines which don't start with the fill prefix. See section T.5 Filling Text.

When you wish to operate on a paragraph, you can use the command M-h (mark-paragraph) to set the region around it. Thus, for example, M-h C-w kills the paragraph around or after point. The M-h command puts point at the beginning and mark at the end of the paragraph point was in. In Transient Mark mode, it activates the mark. If point is between paragraphs (in a run of blank lines, or at a boundary), the paragraph following point is surrounded by point and mark. If there are blank lines preceding the first line of the paragraph, one of these blank lines is included in the region.

The precise definition of a paragraph boundary is controlled by the variables paragraph-separate and paragraph-start. The value of paragraph-start is a regexp that should match any line that either starts or separates paragraphs. The value of paragraph-separate is another regexp that should match only lines that separate paragraphs without being part of any paragraph (for example, blank lines). Lines that start a new paragraph and are contained in it must match only paragraph-start, not paragraph-separate. For example, in Fundamental mode, paragraph-start is "[ \t\n\f]", and paragraph-separate is "[ \t\f]*$".

Normally it is desirable for page boundaries to separate paragraphs. The default values of these variables recognize the usual separator for pages.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.4 Pages

Files are often thought of as divided into pages by the formfeed character (ASCII control-L, octal code 014). When you print hardcopy for a file, this character forces a page break; thus, each page of the file goes on a separate page on paper. Most Emacs commands treat the page-separator character just like any other character: you can insert it with C-q C-l, and delete it with DEL. Thus, you are free to paginate your file or not. However, since pages are often meaningful divisions of the file, Emacs provides commands to move over them and operate on them.

C-x [
Move point to previous page boundary (backward-page).
C-x ]
Move point to next page boundary (forward-page).
C-x C-p
Put point and mark around this page (or another page) (mark-page).
C-x l
Count the lines in this page (count-lines-page).
The C-x [ (backward-page) command moves point to immediately after the previous page delimiter. If point is already right after a page delimiter, it skips that one and stops at the previous one. A numeric argument serves as a repeat count. The C-x ] (forward-page) command moves forward past the next page delimiter.

The C-x C-p command (mark-page) puts point at the beginning of the current page and the mark at the end. The page delimiter at the end is included (the mark follows it). The page delimiter at the front is excluded (point follows it). In Transient Mark mode, this command activates the mark.

C-x C-p C-w is a handy way to kill a page to move it elsewhere. If you move to another page delimiter with C-x [ and C-x ], then yank the killed page, all the pages will be properly delimited once again. The reason C-x C-p includes only the following page delimiter in the region is to ensure that.

A numeric argument to C-x C-p is used to specify which page to go to, relative to the current one. Zero means the current page. One means the next page, and -1 means the previous one.

The C-x l command (count-lines-page) is good for deciding where to break a page in two. It displays in the echo area the total number of lines in the current page, and then divides it up into those preceding the current line and those following, as in
Page has 96 (72+25) lines
Notice that the sum is off by one; this is correct if point is not at the beginning of a line.

The variable page-delimiter controls where pages begin. Its value is a regexp that matches the beginning of a line that separates pages. The normal value of this variable is "^\f", which matches a formfeed character at the beginning of a line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.5 Filling Text

Filling text means breaking it up into lines that fit a specified width. Emacs does filling in two ways. In Auto Fill mode, inserting text with self-inserting characters also automatically fills it. There are also explicit fill commands that you can use when editing text leaves it unfilled. When you edit formatted text, you can specify a style of filling for each portion of the text (see section T.11 Editing Formatted Text).

T.5.1 Auto Fill Mode

Auto Fill mode breaks long lines automatically.

T.5.2 Refill Mode

Keeping paragraphs filled.

T.5.3 Explicit Fill Commands

Commands to refill paragraphs and center lines.

T.5.4 The Fill Prefix

Filling paragraphs that are indented or in a comment, etc.

T.5.5 Adaptive Filling

How Emacs can determine the fill prefix automatically.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.5.1 Auto Fill Mode

Auto Fill mode is a minor mode in which lines are broken automatically when they become too wide. Breaking happens only when you type a SPC or RET.

M-x auto-fill-mode
Enable or disable Auto Fill mode.
SPC

RET
In Auto Fill mode, break lines when appropriate.
M-x auto-fill-mode turns Auto Fill mode on if it was off, or off if it was on. With a positive numeric argument it always turns Auto Fill mode on, and with a negative argument always turns it off. You can see when Auto Fill mode is in effect by the presence of the word `Fill' in the mode line, inside the parentheses. Auto Fill mode is a minor mode which is enabled or disabled for each buffer individually. See section AD.1 Minor Modes.

In Auto Fill mode, lines are broken automatically at spaces when they get longer than the desired width. Line breaking and rearrangement takes place only when you type SPC or RET. If you wish to insert a space or newline without permitting line-breaking, type C-q SPC or C-q C-j (recall that a newline is really a control-J). Also, C-o inserts a newline without line breaking.

Auto Fill mode works well with programming-language modes, because it indents new lines with TAB. If a line ending in a comment gets too long, the text of the comment is split into two comment lines. Optionally, new comment delimiters are inserted at the end of the first line and the beginning of the second so that each line is a separate comment; the variable comment-multi-line controls the choice (see section U.5 Manipulating Comments).

Adaptive filling (see section T.5.5 Adaptive Filling) works for Auto Filling as well as for explicit fill commands. It takes a fill prefix automatically from the second or first line of a paragraph.

Auto Fill mode does not refill entire paragraphs; it can break lines but cannot merge lines. So editing in the middle of a paragraph can result in a paragraph that is not correctly filled. The easiest way to make the paragraph properly filled again is usually with the explicit fill commands. See section T.5.3 Explicit Fill Commands.

Many users like Auto Fill mode and want to use it in all text files. The section on init files says how to arrange this permanently for yourself. See section AD.7 The Init File, `~/.emacs'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.5.2 Refill Mode

Refill minor mode provides support for keeping paragraphs filled as you type or modify them in other ways. It provides an effect similar to typical word processor behavior. This works by running a paragraph-filling command at suitable times.

When you are typing text, only characters which normally trigger auto filling, like the space character, will trigger refilling. This is to avoid making it too slow. Apart from self-inserting characters, other commands which modify the text cause refilling.

The current implementation is preliminary and probably not robust. We expect to improve on it.

To toggle the use of Refill mode in the current buffer, type M-x refill-mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.5.3 Explicit Fill Commands

M-q
Fill current paragraph (fill-paragraph).
C-x f
Set the fill column (set-fill-column).
M-x fill-region
Fill each paragraph in the region (fill-region).
M-x fill-region-as-paragraph
Fill the region, considering it as one paragraph.
M-s
Center a line.
To refill a paragraph, use the command M-q (fill-paragraph). This operates on the paragraph that point is inside, or the one after point if point is between paragraphs. Refilling works by removing all the line-breaks, then inserting new ones where necessary.

To refill many paragraphs, use M-x fill-region, which divides the region into paragraphs and fills each of them.

M-q and fill-region use the same criteria as M-h for finding paragraph boundaries (see section T.3 Paragraphs). For more control, you can use M-x fill-region-as-paragraph, which refills everything between point and mark. This command deletes any blank lines within the region, so separate blocks of text end up combined into one block.

A numeric argument to M-q causes it to justify the text as well as filling it. This means that extra spaces are inserted to make the right margin line up exactly at the fill column. To remove the extra spaces, use M-q with no argument. (Likewise for fill-region.) Another way to control justification, and choose other styles of filling, is with the justification text property; see T.11.7 Justification in Formatted Text.

The command M-s (center-line) centers the current line within the current fill column. With an argument n, it centers n lines individually and moves past them.

The maximum line width for filling is in the variable fill-column. Altering the value of fill-column makes it local to the current buffer; until that time, the default value is in effect. The default is initially 70. See section AD.2.4 Local Variables. The easiest way to set fill-column is to use the command C-x f (set-fill-column). With a numeric argument, it uses that as the new fill column. With just C-u as argument, it sets fill-column to the current horizontal position of point.

Emacs commands normally consider a period followed by two spaces or by a newline as the end of a sentence; a period followed by just one space indicates an abbreviation and not the end of a sentence. To preserve the distinction between these two ways of using a period, the fill commands do not break a line after a period followed by just one space.

If the variable sentence-end-double-space is nil, the fill commands expect and leave just one space at the end of a sentence. Ordinarily this variable is t, so the fill commands insist on two spaces for the end of a sentence, as explained above. See section T.2 Sentences.

If the variable colon-double-space is non-nil, the fill commands put two spaces after a colon.

Some languages do not use period to indicate end of sentence. For example, a sentence in Thai text ends with double space but without a period. Set the variable sentence-end-without-period to t to tell the sentence commands that a period is not necessary.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.5.4 The Fill Prefix

To fill a paragraph in which each line starts with a special marker (which might be a few spaces, giving an indented paragraph), you can use the fill prefix feature. The fill prefix is a string that Emacs expects every line to start with, and which is not included in filling. You can specify a fill prefix explicitly; Emacs can also deduce the fill prefix automatically (see section T.5.5 Adaptive Filling).

C-x .
Set the fill prefix (set-fill-prefix).
M-q
Fill a paragraph using current fill prefix (fill-paragraph).
M-x fill-individual-paragraphs
Fill the region, considering each change of indentation as starting a new paragraph.
M-x fill-nonuniform-paragraphs
Fill the region, considering only paragraph-separator lines as starting a new paragraph.
To specify a fill prefix, move to a line that starts with the desired prefix, put point at the end of the prefix, and give the command C-x . (set-fill-prefix). That's a period after the C-x. To turn off the fill prefix, specify an empty prefix: type C-x . with point at the beginning of a line.

When a fill prefix is in effect, the fill commands remove the fill prefix from each line before filling and insert it on each line after filling. Auto Fill mode also inserts the fill prefix automatically when it makes a new line. The C-o command inserts the fill prefix on new lines it creates, when you use it at the beginning of a line (see section D.7 Blank Lines). Conversely, the command M-^ deletes the prefix (if it occurs) after the newline that it deletes (see section S. Indentation).

For example, if fill-column is 40 and you set the fill prefix to `;; ', then M-q in the following text
;; This is an
;; example of a paragraph
;; inside a Lisp-style comment.
produces this:
;; This is an example of a paragraph
;; inside a Lisp-style comment.
Lines that do not start with the fill prefix are considered to start paragraphs, both in M-q and the paragraph commands; this gives good results for paragraphs with hanging indentation (every line indented except the first one). Lines which are blank or indented once the prefix is removed also separate or start paragraphs; this is what you want if you are writing multi-paragraph comments with a comment delimiter on each line.

You can use M-x fill-individual-paragraphs to set the fill prefix for each paragraph automatically. This command divides the region into paragraphs, treating every change in the amount of indentation as the start of a new paragraph, and fills each of these paragraphs. Thus, all the lines in one "paragraph" have the same amount of indentation. That indentation serves as the fill prefix for that paragraph.

M-x fill-nonuniform-paragraphs is a similar command that divides the region into paragraphs in a different way. It considers only paragraph-separating lines (as defined by paragraph-separate) as starting a new paragraph. Since this means that the lines of one paragraph may have different amounts of indentation, the fill prefix used is the smallest amount of indentation of any of the lines of the paragraph. This gives good results with styles that indent a paragraph's first line more or less that the rest of the paragraph.

The fill prefix is stored in the variable fill-prefix. Its value is a string, or nil when there is no fill prefix. This is a per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. See section AD.2.4 Local Variables.

The indentation text property provides another way to control the amount of indentation paragraphs receive. See section T.11.6 Indentation in Formatted Text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.5.5 Adaptive Filling

The fill commands can deduce the proper fill prefix for a paragraph automatically in certain cases: either whitespace or certain punctuation characters at the beginning of a line are propagated to all lines of the paragraph.

If the paragraph has two or more lines, the fill prefix is taken from the paragraph's second line, but only if it appears on the first line as well.

If a paragraph has just one line, fill commands may take a prefix from that line. The decision is complicated because there are three reasonable things to do in such a case:

Use the first line's prefix on all the lines of the paragraph.

Indent subsequent lines with whitespace, so that they line up under the text that follows the prefix on the first line, but don't actually copy the prefix from the first line.

Don't do anything special with the second and following lines.

All three of these styles of formatting are commonly used. So the fill commands try to determine what you would like, based on the prefix that appears and on the major mode. Here is how.

If the prefix found on the first line matches adaptive-fill-first-line-regexp, or if it appears to be a comment-starting sequence (this depends on the major mode), then the prefix found is used for filling the paragraph, provided it would not act as a paragraph starter on subsequent lines.

Otherwise, the prefix found is converted to an equivalent number of spaces, and those spaces are used as the fill prefix for the rest of the lines, provided they would not act as a paragraph starter on subsequent lines.

In Text mode, and other modes where only blank lines and page delimiters separate paragraphs, the prefix chosen by adaptive filling never acts as a paragraph starter, so it can always be used for filling.

The variable adaptive-fill-regexp determines what kinds of line beginnings can serve as a fill prefix: any characters at the start of the line that match this regular expression are used. If you set the variable adaptive-fill-mode to nil, the fill prefix is never chosen automatically.

You can specify more complex ways of choosing a fill prefix automatically by setting the variable adaptive-fill-function to a function. This function is called with point after the left margin of a line, and it should return the appropriate fill prefix based on that line. If it returns nil, that means it sees no fill prefix in that line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.6 Case Conversion Commands

Emacs has commands for converting either a single word or any arbitrary range of text to upper case or to lower case.

M-l
Convert following word to lower case (downcase-word).
M-u
Convert following word to upper case (upcase-word).
M-c
Capitalize the following word (capitalize-word).
C-x C-l
Convert region to lower case (downcase-region).
C-x C-u
Convert region to upper case (upcase-region).
The word conversion commands are the most useful. M-l (downcase-word) converts the word after point to lower case, moving past it. Thus, repeating M-l converts successive words. M-u (upcase-word) converts to all capitals instead, while M-c (capitalize-word) puts the first letter of the word into upper case and the rest into lower case. All these commands convert several words at once if given an argument. They are especially convenient for converting a large amount of text from all upper case to mixed case, because you can move through the text using M-l, M-u or M-c on each word as appropriate, occasionally using M-f instead to skip a word.

When given a negative argument, the word case conversion commands apply to the appropriate number of words before point, but do not move point. This is convenient when you have just typed a word in the wrong case: you can give the case conversion command and continue typing.

If a word case conversion command is given in the middle of a word, it applies only to the part of the word which follows point. This is just like what M-d (kill-word) does. With a negative argument, case conversion applies only to the part of the word before point.

The other case conversion commands are C-x C-u (upcase-region) and C-x C-l (downcase-region), which convert everything between point and mark to the specified case. Point and mark do not move.

The region case conversion commands upcase-region and downcase-region are normally disabled. This means that they ask for confirmation if you try to use them. When you confirm, you may enable the command, which means it will not ask for confirmation again. See section AD.4.11 Disabling Commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.7 Text Mode

When you edit files of text in a human language, it's more convenient to use Text mode rather than Fundamental mode. To enter Text mode, type M-x text-mode.

In Text mode, only blank lines and page delimiters separate paragraphs. As a result, paragraphs can be indented, and adaptive filling determines what indentation to use when filling a paragraph. See section T.5.5 Adaptive Filling.

Text mode defines TAB to run indent-relative (see section S. Indentation), so that you can conveniently indent a line like the previous line. When the previous line is not indented, indent-relative runs tab-to-tab-stop, which uses Emacs tab stops that you can set (see section S.2 Tab Stops).

Text mode turns off the features concerned with comments except when you explicitly invoke them. It changes the syntax table so that periods are not considered part of a word, while apostrophes, backspaces and underlines are considered part of words.

If you indent the first lines of paragraphs, then you should use Paragraph-Indent Text mode rather than Text mode. In this mode, you do not need to have blank lines between paragraphs, because the first-line indentation is sufficient to start a paragraph; however paragraphs in which every line is indented are not supported. Use M-x paragraph-indent-text-mode to enter this mode. Use M-x paragraph-indent-minor-mode to enter an equivalent minor mode, for instance during mail composition.

Text mode, and all the modes based on it, define M-TAB as the command ispell-complete-word, which performs completion of the partial word in the buffer before point, using the spelling dictionary as the space of possible words. See section L.4 Checking and Correcting Spelling.

Entering Text mode runs the hook text-mode-hook. Other major modes related to Text mode also run this hook, followed by hooks of their own; this includes Paragraph-Indent Text mode, Nroff mode, TeX mode, Outline mode, and Mail mode. Hook functions on text-mode-hook can look at the value of major-mode to see which of these modes is actually being entered. See section AD.2.3 Hooks.

Emacs provides two other modes for editing text that is to be passed through a text formatter to produce fancy formatted printed output. See section T.10 Nroff Mode, for editing input to the formatter nroff. See section T.9 TeX Mode, for editing input to the formatter TeX.

Another mode is used for editing outlines. It allows you to view the text at various levels of detail. You can view either the outline headings alone or both headings and text; you can also hide some of the headings at lower levels from view to make the high level structure more visible. See section T.8 Outline Mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.8 Outline Mode

Outline mode is a major mode much like Text mode but intended for editing outlines. It allows you to make parts of the text temporarily invisible so that you can see the outline structure. Type M-x outline-mode to switch to Outline mode as the major mode of the current buffer.

When Outline mode makes a line invisible, the line does not appear on the screen. The screen appears exactly as if the invisible line were deleted, except that an ellipsis (three periods in a row) appears at the end of the previous visible line (only one ellipsis no matter how many invisible lines follow).

Editing commands that operate on lines, such as C-n and C-p, treat the text of the invisible line as part of the previous visible line. Killing an entire visible line, including its terminating newline, really kills all the following invisible lines along with it.

Outline minor mode provides the same commands as the major mode, Outline mode, but you can use it in conjunction with other major modes. Type M-x outline-minor-mode to enable the Outline minor mode in the current buffer. You can also specify this in the text of a file, with a file local variable of the form `mode: outline-minor' (see section AD.2.5 Local Variables in Files).

The major mode, Outline mode, provides special key bindings on the C-c prefix. Outline minor mode provides similar bindings with C-c @ as the prefix; this is to reduce the conflicts with the major mode's special commands. (The variable outline-minor-mode-prefix controls the prefix used.)

Entering Outline mode runs the hook text-mode-hook followed by the hook outline-mode-hook (see section AD.2.3 Hooks).

T.8.1 Format of Outlines

What the text of an outline looks like.

T.8.2 Outline Motion Commands

Special commands for moving through outlines.

T.8.3 Outline Visibility Commands

Commands to control what is visible.

T.8.4 Viewing One Outline in Multiple Views

Outlines and multiple views.

T.8.5 Folding Editing

Folding editing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.8.1 Format of Outlines

Outline mode assumes that the lines in the buffer are of two types: heading lines and body lines. A heading line represents a topic in the outline. Heading lines start with one or more stars; the number of stars determines the depth of the heading in the outline structure. Thus, a heading line with one star is a major topic; all the heading lines with two stars between it and the next one-star heading are its subtopics; and so on. Any line that is not a heading line is a body line. Body lines belong with the preceding heading line. Here is an example:
* Food
This is the body,
which says something about the topic of food.

** Delicious Food
This is the body of the second-level header.

** Distasteful Food
This could have
a body too, with
several lines.

*** Dormitory Food

* Shelter
Another first-level topic with its header line.
A heading line together with all following body lines is called collectively an entry. A heading line together with all following deeper heading lines and their body lines is called a subtree.

You can customize the criterion for distinguishing heading lines by setting the variable outline-regexp. Any line whose beginning has a match for this regexp is considered a heading line. Matches that start within a line (not at the left margin) do not count. The length of the matching text determines the level of the heading; longer matches make a more deeply nested level. Thus, for example, if a text formatter has commands `@chapter', `@section' and `@subsection' to divide the document into chapters and sections, you could make those lines count as heading lines by setting outline-regexp to `"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words `chapter' and `section' are equally long, but by defining the regexp to match only `chap' we ensure that the length of the text matched on a chapter heading is shorter, so that Outline mode will know that sections are contained in chapters. This works as long as no other command starts with `@chap'.

You can change the rule for calculating the level of a heading line by setting the variable outline-level. The value of outline-level should be a function that takes no arguments and returns the level of the current heading. Some major modes such as C, Nroff, and Emacs Lisp mode set this variable and outline-regexp in order to work with Outline minor mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.8.2 Outline Motion Commands

Outline mode provides special motion commands that move backward and forward to heading lines.

C-c C-n
Move point to the next visible heading line (outline-next-visible-heading).
C-c C-p
Move point to the previous visible heading line (outline-previous-visible-heading).
C-c C-f
Move point to the next visible heading line at the same level as the one point is on (outline-forward-same-level).
C-c C-b
Move point to the previous visible heading line at the same level (outline-backward-same-level).
C-c C-u
Move point up to a lower-level (more inclusive) visible heading line (outline-up-heading).
C-c C-n (outline-next-visible-heading) moves down to the next heading line. C-c C-p (outline-previous-visible-heading) moves similarly backward. Both accept numeric arguments as repeat counts. The names emphasize that invisible headings are skipped, but this is not really a special feature. All editing commands that look for lines ignore the invisible lines automatically.

More powerful motion commands understand the level structure of headings. C-c C-f (outline-forward-same-level) and C-c C-b (outline-backward-same-level) move from one heading line to another visible heading at the same depth in the outline. C-c C-u (outline-up-heading) moves backward to another heading that is less deeply nested.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.8.3 Outline Visibility Commands

The other special commands of outline mode are used to make lines visible or invisible. Their names all start with hide or show. Most of them fall into pairs of opposites. They are not undoable; instead, you can undo right past them. Making lines visible or invisible is simply not recorded by the undo mechanism.

C-c C-t
Make all body lines in the buffer invisible (hide-body).
C-c C-a
Make all lines in the buffer visible (show-all).
C-c C-d
Make everything under this heading invisible, not including this heading itself (hide-subtree).
C-c C-s
Make everything under this heading visible, including body, subheadings, and their bodies (show-subtree).
C-c C-l
Make the body of this heading line, and of all its subheadings, invisible (hide-leaves).
C-c C-k
Make all subheadings of this heading line, at all levels, visible (show-branches).
C-c C-i
Make immediate subheadings (one level down) of this heading line visible (show-children).
C-c C-c
Make this heading line's body invisible (hide-entry).
C-c C-e
Make this heading line's body visible (show-entry).
C-c C-q
Hide everything except the top n levels of heading lines (hide-sublevels).
C-c C-o
Hide everything except for the heading or body that point is in, plus the headings leading up from there to the top level of the outline (hide-other).
Two commands that are exact opposites are C-c C-c (hide-entry) and C-c C-e (show-entry). They are used with point on a heading line, and apply only to the body lines of that heading. Subheadings and their bodies are not affected.

Two more powerful opposites are C-c C-d (hide-subtree) and C-c C-s (show-subtree). Both expect to be used when point is on a heading line, and both apply to all the lines of that heading's subtree: its body, all its subheadings, both direct and indirect, and all of their bodies. In other words, the subtree contains everything following this heading line, up to and not including the next heading of the same or higher rank.

Intermediate between a visible subtree and an invisible one is having all the subheadings visible but none of the body. There are two commands for doing this, depending on whether you want to hide the bodies or make the subheadings visible. They are C-c C-l (hide-leaves) and C-c C-k (show-branches).

A little weaker than show-branches is C-c C-i (show-children). It makes just the direct subheadings visible--those one level down. Deeper subheadings remain invisible, if they were invisible.

Two commands have a blanket effect on the whole file. C-c C-t (hide-body) makes all body lines invisible, so that you see just the outline structure. C-c C-a (show-all) makes all lines visible. These commands can be thought of as a pair of opposites even though C-c C-a applies to more than just body lines.

The command C-c C-q (hide-sublevels) hides all but the top level headings. With a numeric argument n, it hides everything except the top n levels of heading lines.

The command C-c C-o (hide-other) hides everything except the heading or body text that point is in, plus its parents (the headers leading up from there to top level in the outline).

You can turn off the use of ellipses at the ends of visible lines by setting selective-display-ellipses to nil. Then there is no visible indication of the presence of invisible lines.

When incremental search finds text that is hidden by Outline mode, it makes that part of the buffer visible. If you exit the search at that position, the text remains visible.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.8.4 Viewing One Outline in Multiple Views

You can display two views of a single outline at the same time, in different windows. To do this, you must create an indirect buffer using M-x make-indirect-buffer. The first argument of this command is the existing outline buffer name, and its second argument is the name to use for the new indirect buffer. See section N.6 Indirect Buffers.

Once the indirect buffer exists, you can display it in a window in the normal fashion, with C-x 4 b or other Emacs commands. The Outline mode commands to show and hide parts of the text operate on each buffer independently; as a result, each buffer can have its own view. If you want more than two views on the same outline, create additional indirect buffers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.8.5 Folding Editing

The Foldout package extends Outline mode and Outline minor mode with "folding" commands. The idea of folding is that you zoom in on a nested portion of the outline, while hiding its relatives at higher levels.

Consider an Outline mode buffer all the text and subheadings under level-1 headings hidden. To look at what is hidden under one of these headings, you could use C-c C-e (M-x show-entry) to expose the body, or C-c C-i to expose the child (level-2) headings.

With Foldout, you use C-c C-z (M-x foldout-zoom-subtree). This exposes the body and child subheadings, and narrows the buffer so that only the level-1 heading, the body and the level-2 headings are visible. Now to look under one of the level-2 headings, position the cursor on it and use C-c C-z again. This exposes the level-2 body and its level-3 child subheadings and narrows the buffer again. Zooming in on successive subheadings can be done as much as you like. A string in the mode line shows how deep you've gone.

When zooming in on a heading, to see only the child subheadings specify a numeric argument: C-u C-c C-z. The number of levels of children can be specified too (compare M-x show-children), e.g. M-2 C-c C-z exposes two levels of child subheadings. Alternatively, the body can be specified with a negative argument: M-- C-c C-z. The whole subtree can be expanded, similarly to C-c C-s (M-x show-subtree), by specifying a zero argument: M-0 C-c C-z.

While you're zoomed in, you can still use Outline mode's exposure and hiding functions without disturbing Foldout. Also, since the buffer is narrowed, "global" editing actions will only affect text under the zoomed-in heading. This is useful for restricting changes to a particular chapter or section of your document.

To unzoom (exit) a fold, use C-c C-x (M-x foldout-exit-fold). This hides all the text and subheadings under the top-level heading and returns you to the previous view of the buffer. Specifying a numeric argument exits that many levels of folds. Specifying a zero argument exits all folds.

To cancel the narrowing of a fold without hiding the text and subheadings, specify a negative argument. For example, M--2 C-c C-x exits two folds and leaves the text and subheadings exposed.

Foldout mode also provides mouse commands for entering and exiting folds, and for showing and hiding text:

M-C-Mouse-1 zooms in on the heading clicked on

single click: expose body.
double click: expose subheadings.
triple click: expose body and subheadings.
quad click: expose entire subtree.

M-C-Mouse-2 exposes text under the heading clicked on

single click: expose body.
double click: expose subheadings.
triple click: expose body and subheadings.
quad click: expose entire subtree.

M-C-Mouse-3 hides text under the heading clicked on or exits fold

single click: hide subtree.
double click: exit fold and hide text.
triple click: exit fold without hiding text.
quad click: exit all folds and hide text.

You can specify different modifier keys (instead of Control-Meta-) by setting foldout-mouse-modifiers; but if you have already loaded the `foldout.el' library, you must reload it in order for this to take effect.

To use the Foldout package, you can type M-x load-library RET foldout RET; or you can arrange for to do that automatically by putting this in your `.emacs' file:
(eval-after-load "outline" '(require 'foldout))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.9 TeX Mode

TeX is a powerful text formatter written by Donald Knuth; it is also free, like GNU Emacs. LaTeX is a simplified input format for TeX, implemented by TeX macros; it comes with TeX. SliTeX is a special form of LaTeX.(8)

Emacs has a special TeX mode for editing TeX input files. It provides facilities for checking the balance of delimiters and for invoking TeX on all or part of the file.

TeX mode has three variants, Plain TeX mode, LaTeX mode, and SliTeX mode (these three distinct major modes differ only slightly). They are designed for editing the three different formats. The command M-x tex-mode looks at the contents of the buffer to determine whether the contents appear to be either LaTeX input or SliTeX input; if so, it selects the appropriate mode. If the file contents do not appear to be LaTeX or SliTeX, it selects Plain TeX mode. If the contents are insufficient to determine this, the variable tex-default-mode controls which mode is used.

When M-x tex-mode does not guess right, you can use the commands M-x plain-tex-mode, M-x latex-mode, and M-x slitex-mode to select explicitly the particular variants of TeX mode.

T.9.1 TeX Editing Commands

Special commands for editing in TeX mode.

T.9.2 LaTeX Editing Commands

Additional commands for LaTeX input files.

T.9.3 TeX Printing Commands

Commands for printing part of a file with TeX.

T.9.4 TeX Mode Miscellany

Customization of TeX mode, and related features.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.9.1 TeX Editing Commands

Here are the special commands provided in TeX mode for editing the text of the file.

"
Insert, according to context, either `"' or `"' or `"' (tex-insert-quote).
C-j
Insert a paragraph break (two newlines) and check the previous paragraph for unbalanced braces or dollar signs (tex-terminate-paragraph).
M-x tex-validate-region
Check each paragraph in the region for unbalanced braces or dollar signs.
C-c {
Insert `{}' and position point between them (tex-insert-braces).
C-c }
Move forward past the next unmatched close brace (up-list).
In TeX, the character `"' is not normally used; we use `"' to start a quotation and `"' to end one. To make editing easier under this formatting convention, TeX mode overrides the normal meaning of the key " with a command that inserts a pair of single-quotes or backquotes (tex-insert-quote). To be precise, this command inserts `"' after whitespace or an open brace, `"' after a backslash, and `"' after any other character.

If you need the character `"' itself in unusual contexts, use C-q to insert it. Also, " with a numeric argument always inserts that number of `"' characters. You can turn off the feature of " expansion by eliminating that binding in the local map (see section AD.4 Customizing Key Bindings).

In TeX mode, `$' has a special syntax code which attempts to understand the way TeX math mode delimiters match. When you insert a `$' that is meant to exit math mode, the position of the matching `$' that entered math mode is displayed for a second. This is the same feature that displays the open brace that matches a close brace that is inserted. However, there is no way to tell whether a `$' enters math mode or leaves it; so when you insert a `$' that enters math mode, the previous `$' position is shown as if it were a match, even though they are actually unrelated.

TeX uses braces as delimiters that must match. Some users prefer to keep braces balanced at all times, rather than inserting them singly. Use C-c { (tex-insert-braces) to insert a pair of braces. It leaves point between the two braces so you can insert the text that belongs inside. Afterward, use the command C-c } (up-list) to move forward past the close brace.

There are two commands for checking the matching of braces. C-j (tex-terminate-paragraph) checks the paragraph before point, and inserts two newlines to start a new paragraph. It outputs a message in the echo area if any mismatch is found. M-x tex-validate-region checks a region, paragraph by paragraph. The errors are listed in the `*Occur*' buffer, and you can use C-c C-c or Mouse-2 in that buffer to go to a particular mismatch.

Note that Emacs commands count square brackets and parentheses in TeX mode, not just braces. This is not strictly correct for the purpose of checking TeX syntax. However, parentheses and square brackets are likely to be used in text as matching delimiters and it is useful for the various motion commands and automatic match display to work with them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.9.2 LaTeX Editing Commands

LaTeX mode, and its variant, SliTeX mode, provide a few extra features not applicable to plain TeX.

C-c C-o
Insert `\begin' and `\end' for LaTeX block and position point on a line between them (tex-latex-block).
C-c C-e
Close the innermost LaTeX block not yet closed (tex-close-latex-block).
In LaTeX input, `\begin' and `\end' commands are used to group blocks of text. To insert a `\begin' and a matching `\end' (on a new line following the `\begin'), use C-c C-o (tex-latex-block). A blank line is inserted between the two, and point is left there. You can use completion when you enter the block type; to specify additional block type names beyond the standard list, set the variable latex-block-names. For example, here's how to add `theorem', `corollary', and `proof':
(setq latex-block-names '("theorem" "corollary" "proof"))
In LaTeX input, `\begin' and `\end' commands must balance. You can use C-c C-e (tex-close-latex-block) to insert automatically a matching `\end' to match the last unmatched `\begin'. It indents the `\end' to match the corresponding `\begin'. It inserts a newline after `\end' if point is at the beginning of a line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.9.3 TeX Printing Commands

You can invoke TeX as an inferior of Emacs on either the entire contents of the buffer or just a region at a time. Running TeX in this way on just one chapter is a good way to see what your changes look like without taking the time to format the entire file.

C-c C-r
Invoke TeX on the current region, together with the buffer's header (tex-region).
C-c C-b
Invoke TeX on the entire current buffer (tex-buffer).
C-c TAB
Invoke BibTeX on the current file (tex-bibtex-file).
C-c C-f
Invoke TeX on the current file (tex-file).
C-c C-l
Recenter the window showing output from the inferior TeX so that the last line can be seen (tex-recenter-output-buffer).
C-c C-k
Kill the TeX subprocess (tex-kill-job).
C-c C-p
Print the output from the last C-c C-r, C-c C-b, or C-c C-f command (tex-print).
C-c C-v
Preview the output from the last C-c C-r, C-c C-b, or C-c C-f command (tex-view).
C-c C-q
Show the printer queue (tex-show-print-queue).
You can pass the current buffer through an inferior TeX by means of C-c C-b (tex-buffer). The formatted output appears in a temporary file; to print it, type C-c C-p (tex-print). Afterward, you can use C-c C-q (tex-show-print-queue) to view the progress of your output towards being printed. If your terminal has the ability to display TeX output files, you can preview the output on the terminal with C-c C-v (tex-view).

You can specify the directory to use for running TeX by setting the variable tex-directory. "." is the default value. If your environment variable TEXINPUTS contains relative directory names, or if your files contains `\input' commands with relative file names, then tex-directory must be "." or you will get the wrong results. Otherwise, it is safe to specify some other directory, such as "/tmp".

If you want to specify which shell commands are used in the inferior TeX, you can do so by setting the values of the variables tex-run-command, latex-run-command, slitex-run-command, tex-dvi-print-command, tex-dvi-view-command, and tex-show-queue-command. You must set the value of tex-dvi-view-command for your particular terminal; this variable has no default value. The other variables have default values that may (or may not) be appropriate for your system.

Normally, the file name given to these commands comes at the end of the command string; for example, `latex filename'. In some cases, however, the file name needs to be embedded in the command; an example is when you need to provide the file name as an argument to one command whose output is piped to another. You can specify where to put the file name with `*' in the command string. For example,
(setq tex-dvi-print-command "dvips -f * | lpr")
The terminal output from TeX, including any error messages, appears in a buffer called `*tex-shell*'. If TeX gets an error, you can switch to this buffer and feed it input (this works as in Shell mode; see section AC.15.2 Interactive Inferior Shell). Without switching to this buffer you can scroll it so that its last line is visible by typing C-c C-l.

Type C-c C-k (tex-kill-job) to kill the TeX process if you see that its output is no longer useful. Using C-c C-b or C-c C-r also kills any TeX process still running.

You can also pass an arbitrary region through an inferior TeX by typing C-c C-r (tex-region). This is tricky, however, because most files of TeX input contain commands at the beginning to set parameters and define macros, without which no later part of the file will format correctly. To solve this problem, C-c C-r allows you to designate a part of the file as containing essential commands; it is included before the specified region as part of the input to TeX. The designated part of the file is called the header.

To indicate the bounds of the header in Plain TeX mode, you insert two special strings in the file. Insert `%**start of header' before the header, and `%**end of header' after it. Each string must appear entirely on one line, but there may be other text on the line before or after. The lines containing the two strings are included in the header. If `%**start of header' does not appear within the first 100 lines of the buffer, C-c C-r assumes that there is no header.

In LaTeX mode, the header begins with `\documentclass' or `\documentstyle' and ends with `\begin{document}'. These are commands that LaTeX requires you to use in any case, so nothing special needs to be done to identify the header.

The commands (tex-buffer) and (tex-region) do all of their work in a temporary directory, and do not have available any of the auxiliary files needed by TeX for cross-references; these commands are generally not suitable for running the final copy in which all of the cross-references need to be correct.

When you want the auxiliary files for cross references, use C-c C-f (tex-file) which runs TeX on the current buffer's file, in that file's directory. Before running TeX, it offers to save any modified buffers. Generally, you need to use (tex-file) twice to get the cross-references right.

The value of the variable tex-start-options-string specifies options for the TeX run. The default value causes TeX to run in nonstop mode. To run TeX interactively, set the variable to "".

Large TeX documents are often split into several files--one main file, plus subfiles. Running TeX on a subfile typically does not work; you have to run it on the main file. In order to make tex-file useful when you are editing a subfile, you can set the variable tex-main-file to the name of the main file. Then tex-file runs TeX on that file.

The most convenient way to use tex-main-file is to specify it in a local variable list in each of the subfiles. See section AD.2.5 Local Variables in Files.

For LaTeX files, you can use BibTeX to process the auxiliary file for the current buffer's file. BibTeX looks up bibliographic citations in a data base and prepares the cited references for the bibliography section. The command C-c TAB (tex-bibtex-file) runs the shell command (tex-bibtex-command) to produce a `.bbl' file for the current buffer's file. Generally, you need to do C-c C-f (tex-file) once to generate the `.aux' file, then do C-c TAB (tex-bibtex-file), and then repeat C-c C-f (tex-file) twice more to get the cross-references correct.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.9.4 TeX Mode Miscellany

Entering any variant of TeX mode runs the hooks text-mode-hook and tex-mode-hook. Then it runs either plain-tex-mode-hook, latex-mode-hook, or slitex-mode-hook, whichever is appropriate. Starting the TeX shell runs the hook tex-shell-hook. See section AD.2.3 Hooks.

TeX encoding The commands M-x iso-iso2tex, M-x iso-tex2iso, M-x iso-iso2gtex and M-x iso-gtex2iso can be used to convert between Latin-1 encoded files and TeX-encoded equivalents.

For managing all kinds of references for LaTeX, you can use RefTeX. @xref{Top, , RefTeX, reftex}.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.10 Nroff Mode

Nroff mode is a mode like Text mode but modified to handle nroff commands present in the text. Invoke M-x nroff-mode to enter this mode. It differs from Text mode in only a few ways. All nroff command lines are considered paragraph separators, so that filling will never garble the nroff commands. Pages are separated by `.bp' commands. Comments start with backslash-doublequote. Also, three special commands are provided that are not in Text mode:

M-n
Move to the beginning of the next line that isn't an nroff command (forward-text-line). An argument is a repeat count.
M-p
Like M-n but move up (backward-text-line).
M-?
Displays in the echo area the number of text lines (lines that are not nroff commands) in the region (count-text-lines).
The other feature of Nroff mode is that you can turn on Electric Nroff mode. This is a minor mode that you can turn on or off with M-x electric-nroff-mode (see section AD.1 Minor Modes). When the mode is on, each time you use RET to end a line that contains an nroff command that opens a kind of grouping, the matching nroff command to close that grouping is automatically inserted on the following line. For example, if you are at the beginning of a line and type . ( b RET, this inserts the matching command `.)b' on a new line following point.

If you use Outline minor mode with Nroff mode (see section T.8 Outline Mode), heading lines are lines of the form `.H' followed by a number (the header level).

Entering Nroff mode runs the hook text-mode-hook, followed by the hook nroff-mode-hook (see section AD.2.3 Hooks).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11 Editing Formatted Text

Enriched mode is a minor mode for editing files that contain formatted text in WYSIWYG fashion, as in a word processor. Currently, formatted text in Enriched mode can specify fonts, colors, underlining, margins, and types of filling and justification. In the future, we plan to implement other formatting features as well.

Enriched mode is a minor mode (see section AD.1 Minor Modes). It is typically used in conjunction with Text mode (see section T.7 Text Mode), but you can also use it with other major modes such as Outline mode and Paragraph-Indent Text mode.

Potentially, Emacs can store formatted text files in various file formats. Currently, only one format is implemented: text/enriched format, which is defined by the MIME protocol. See section `Format Conversion' in the Emacs Lisp Reference Manual, for details of how Emacs recognizes and converts file formats.

The Emacs distribution contains a formatted text file that can serve as an example. Its name is `etc/enriched.doc'. It contains samples illustrating all the features described in this section. It also contains a list of ideas for future enhancements.

T.11.1 Requesting to Edit Formatted Text

Entering and exiting Enriched mode.

T.11.2 Hard and Soft Newlines

There are two different kinds of newlines.

T.11.3 Editing Format Information

How to edit text properties.

T.11.4 Faces in Formatted Text

Bold, italic, underline, etc.

T.11.5 Colors in Formatted Text

Changing the color of text.

T.11.6 Indentation in Formatted Text

Changing the left and right margins.

T.11.7 Justification in Formatted Text

Centering, setting text flush with the left or right margin, etc.

T.11.8 Setting Other Text Properties

The "special" text properties submenu.

T.11.9 Forcing Enriched Mode

How to force use of Enriched mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.1 Requesting to Edit Formatted Text

Whenever you visit a file that Emacs saved in the text/enriched format, Emacs automatically converts the formatting information in the file into Emacs's own internal format (text properties), and turns on Enriched mode.

To create a new file of formatted text, first visit the nonexistent file, then type M-x enriched-mode before you start inserting text. This command turns on Enriched mode. Do this before you begin inserting text, to ensure that the text you insert is handled properly.

More generally, the command enriched-mode turns Enriched mode on if it was off, and off if it was on. With a prefix argument, this command turns Enriched mode on if the argument is positive, and turns the mode off otherwise.

When you save a buffer while Enriched mode is enabled in it, Emacs automatically converts the text to text/enriched format while writing it into the file. When you visit the file again, Emacs will automatically recognize the format, reconvert the text, and turn on Enriched mode again.

Normally, after visiting a file in text/enriched format, Emacs refills each paragraph to fit the specified right margin. You can turn off this refilling, to save time, by setting the variable enriched-fill-after-visiting to nil or to ask.

However, when visiting a file that was saved from Enriched mode, there is no need for refilling, because Emacs saves the right margin settings along with the text.

You can add annotations for saving additional text properties, which Emacs normally does not save, by adding to enriched-translations. Note that the text/enriched standard requires any non-standard annotations to have names starting with `x-', as in `x-read-only'. This ensures that they will not conflict with standard annotations that may be added later.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.2 Hard and Soft Newlines

In formatted text, Emacs distinguishes between two different kinds of newlines, hard newlines and soft newlines.

Hard newlines are used to separate paragraphs, or items in a list, or anywhere that there should always be a line break regardless of the margins. The RET command (newline) and C-o (open-line) insert hard newlines.

Soft newlines are used to make text fit between the margins. All the fill commands, including Auto Fill, insert soft newlines--and they delete only soft newlines.

Although hard and soft newlines look the same, it is important to bear the difference in mind. Do not use RET to break lines in the middle of filled paragraphs, or else you will get hard newlines that are barriers to further filling. Instead, let Auto Fill mode break lines, so that if the text or the margins change, Emacs can refill the lines properly. See section T.5.1 Auto Fill Mode.

On the other hand, in tables and lists, where the lines should always remain as you type them, you can use RET to end lines. For these lines, you may also want to set the justification style to unfilled. See section T.11.7 Justification in Formatted Text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.3 Editing Format Information

There are two ways to alter the formatting information for a formatted text file: with keyboard commands, and with the mouse.

The easiest way to add properties to your document is with the Text Properties menu. You can get to this menu in two ways: from the Edit menu in the menu bar (use F10 e t if you have no mouse), or with C-Mouse-2 (hold the CTRL key and press the middle mouse button). There are also keyboard commands described in the following section.

Most of the items in the Text Properties menu lead to other submenus. These are described in the sections that follow. Some items run commands directly:

Remove Face Properties
Delete from the region all the text properties that the Text Properties menu works with (facemenu-remove-face-props).

Remove All
Delete all text properties from the region (facemenu-remove-all).

List Properties
List all the text properties of the character following point (list-text-properties-at).

Display Faces
Display a list of all the defined faces (list-faces-display).

Display Colors
Display a list of all the defined colors (list-colors-display).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.4 Faces in Formatted Text

The Faces submenu lists various Emacs faces including bold, italic, and underline. Selecting one of these adds the chosen face to the region. See section J.1 Using Multiple Typefaces. You can also specify a face with these keyboard commands:

M-g d
Set the region, or the next inserted character, to the default face (facemenu-set-default).
M-g b
Set the region, or the next inserted character, to the bold face (facemenu-set-bold).
M-g i
Set the region, or the next inserted character, to the italic face (facemenu-set-italic).
M-g l
Set the region, or the next inserted character, to the bold-italic face (facemenu-set-bold-italic).
M-g u
Set the region, or the next inserted character, to the underline face (facemenu-set-underline).
M-g o face RET
Set the region, or the next inserted character, to the face face (facemenu-set-face).
If you use these commands with a prefix argument--or, in Transient Mark mode, if the region is not active--then these commands specify a face to use for your next self-inserting input. See section H.2 Transient Mark Mode. This applies to both the keyboard commands and the menu commands.

Enriched mode defines two additional faces: excerpt and fixed. These correspond to codes used in the text/enriched file format.

The excerpt face is intended for quotations. This face is the same as italic unless you customize it (see section AD.2.2.3 Customizing Faces).

The fixed face means, "Use a fixed-width font for this part of the text." This makes a visible difference only if you have specified a variable-width font in the default face; however, even if the default font is fixed-width, applying the fixed face to a part of the text will cause that part of the text to appear in a fixed-width font, if the file is ever displayed with a variable-width default font. This applies to Emacs and to other systems that display text/enriched format. So if you specifically want a certain part of the text to use a fixed-width font, you should specify the fixed face for that part.

The fixed face is normally set up to use a different font from the default, even if the default face is also fixed-width. Different systems have different fonts installed, so you may need to customize this. See section AD.2.2.3 Customizing Faces.

If your terminal cannot display different faces, you will not be able to see them, but you can still edit documents containing faces, and even add faces and colors to documents. The faces you specify will be visible when the file is viewed on a terminal that can display them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.5 Colors in Formatted Text

You can specify foreground and background colors for portions of the text. There is a menu for specifying the foreground color and a menu for specifying the background color. Each color menu lists all the colors that you have used in Enriched mode in the current Emacs session.

If you specify a color with a prefix argument--or, in Transient Mark mode, if the region is not active--then it applies to your next self-inserting input. See section H.2 Transient Mark Mode. Otherwise, the command applies to the region.

Each color menu contains one additional item: `Other'. You can use this item to specify a color that is not listed in the menu; it reads the color name with the minibuffer. To display list of available colors and their names, use the `Display Colors' menu item in the Text Properties menu (see section T.11.3 Editing Format Information).

Any color that you specify in this way, or that is mentioned in a formatted text file that you read in, is added to both color menus for the duration of the Emacs session.

There are no key bindings for specifying colors, but you can do so with the extended commands M-x facemenu-set-foreground and M-x facemenu-set-background. Both of these commands read the name of the color with the minibuffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.6 Indentation in Formatted Text

When editing formatted text, you can specify different amounts of indentation for the right or left margin of an entire paragraph or a part of a paragraph. The margins you specify automatically affect the Emacs fill commands (see section T.5 Filling Text) and line-breaking commands.

The Indentation submenu provides a convenient interface for specifying these properties. The submenu contains four items:

Indent More
Indent the region by 4 columns (increase-left-margin). In Enriched mode, this command is also available on C-x TAB; if you supply a numeric argument, that says how many columns to add to the margin (a negative argument reduces the number of columns).

Indent Less
Remove 4 columns of indentation from the region.

Indent Right More
Make the text narrower by indenting 4 columns at the right margin.

Indent Right Less
Remove 4 columns of indentation from the right margin.
You can use these commands repeatedly to increase or decrease the indentation.

The most common way to use these commands is to change the indentation of an entire paragraph. However, that is not the only use. You can change the margins at any point; the new values take effect at the end of the line (for right margins) or the beginning of the next line (for left margins).

This makes it possible to format paragraphs with hanging indents, which means that the first line is indented less than subsequent lines. To set up a hanging indent, increase the indentation of the region starting after the first word of the paragraph and running until the end of the paragraph.

Indenting the first line of a paragraph is easier. Set the margin for the whole paragraph where you want it to be for the body of the paragraph, then indent the first line by inserting extra spaces or tabs.

Sometimes, as a result of editing, the filling of a paragraph becomes messed up--parts of the paragraph may extend past the left or right margins. When this happens, use M-q (fill-paragraph) to refill the paragraph.

The variable standard-indent specifies how many columns these commands should add to or subtract from the indentation. The default value is 4. The overall default right margin for Enriched mode is controlled by the variable fill-column, as usual.

The fill prefix, if any, works in addition to the specified paragraph indentation: C-x . does not include the specified indentation's whitespace in the new value for the fill prefix, and the fill commands look for the fill prefix after the indentation on each line. See section T.5.4 The Fill Prefix.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.7 Justification in Formatted Text
When editing formatted text, you can specify various styles of justification for a paragraph. The style you specify automatically affects the Emacs fill commands.
The Justification submenu provides a convenient interface for specifying the style. The submenu contains five items:

Flush Left
This is the most common style of justification (at least for English). Lines are aligned at the left margin but left uneven at the right.

Flush Right
This aligns each line with the right margin. Spaces and tabs are added on the left, if necessary, to make lines line up on the right.

Full
This justifies the text, aligning both edges of each line. Justified text looks very nice in a printed book, where the spaces can all be adjusted equally, but it does not look as nice with a fixed-width font on the screen. Perhaps a future version of Emacs will be able to adjust the width of spaces in a line to achieve elegant justification.

Center
This centers every line between the current margins.

None
This turns off filling entirely. Each line will remain as you wrote it; the fill and auto-fill functions will have no effect on text which has this setting. You can, however, still indent the left margin. In unfilled regions, all newlines are treated as hard newlines (see section T.11.2 Hard and Soft Newlines) .
In Enriched mode, you can also specify justification from the keyboard using the M-j prefix character:

M-j l
Make the region left-filled (set-justification-left).
M-j r
Make the region right-filled (set-justification-right).
M-j f
Make the region fully-justified (set-justification-full).
M-j c

M-S
Make the region centered (set-justification-center).
M-j u
Make the region unfilled (set-justification-none).
Justification styles apply to entire paragraphs. All the justification-changing commands operate on the paragraph containing point, or, if the region is active, on all paragraphs which overlap the region.

The default justification style is specified by the variable default-justification. Its value should be one of the symbols left, right, full, center, or none.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.8 Setting Other Text Properties

The Other Properties menu lets you add or remove three other useful text properties: read-only, invisible and intangible. The intangible property disallows moving point within the text, the invisible text property hides text from display, and the read-only property disallows alteration of the text.

Each of these special properties has a menu item to add it to the region. The last menu item, `Remove Special', removes all of these special properties from the text in the region.

Currently, the invisible and intangible properties are not saved in the text/enriched format. The read-only property is saved, but it is not a standard part of the text/enriched format, so other editors may not respect it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

T.11.9 Forcing Enriched Mode

Normally, Emacs knows when you are editing formatted text because it recognizes the special annotations used in the file that you visited. However, there are situations in which you must take special actions to convert file contents or turn on Enriched mode:

When you visit a file that was created with some other editor, Emacs may not recognize the file as being in the text/enriched format. In this case, when you visit the file you will see the formatting commands rather than the formatted text. Type M-x format-decode-buffer to translate it.

When you insert a file into a buffer, rather than visiting it. Emacs does the necessary conversions on the text which you insert, but it does not enable Enriched mode. If you wish to do that, type M-x enriched-mode.

The command format-decode-buffer translates text in various formats into Emacs's internal format. It asks you to specify the format to translate from; however, normally you can type just RET, which tells Emacs to guess the format.

If you wish to look at text/enriched file in its raw form, as a sequence of characters rather than as formatted text, use the M-x find-file-literally command. This visits a file, like find-file, but does not do format conversion. It also inhibits character code conversion (see section Q.7 Coding Systems) and automatic uncompression (see section M.11 Accessing Compressed Files). To disable format conversion but allow character code conversion and/or automatic uncompression if appropriate, use format-find-file with suitable arguments.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U. Editing Programs

Emacs provides many features to facilitate editing programs. Some of these features can

Find or move over top-level definitions (see section U.2 Top-Level Definitions, or Defuns).
Apply the usual indentation conventions of the language (see section U.3 Indentation for Programs).
Insert, kill or align comments (see section U.5 Manipulating Comments).
Balance parentheses (see section U.4 Commands for Editing with Parentheses).
Highlight program syntax (see section J.2 Font Lock mode).

This chapter describes these features and many more.

U.1 Major Modes for Programming Languages

Major modes for editing programs.

U.2 Top-Level Definitions, or Defuns

Commands to operate on major top-level parts of a program.

U.3 Indentation for Programs

Adjusting indentation to show the nesting.

U.5 Manipulating Comments

Inserting, killing, and aligning comments.

U.4 Commands for Editing with Parentheses

Commands that operate on parentheses.

U.6 Documentation Lookup

Getting documentation of functions you plan to call.

U.7 Hideshow minor mode

Displaying blocks selectively.

U.8 Completion for Symbol Names

Completion on symbol names of your program or language.

U.9 Glasses minor mode

Making identifiersLikeThis more readable.

U.10 Other Features Useful for Editing Programs

Other Emacs features useful for editing programs.

U.11 C and Related Modes

Special commands of C, C++, Objective-C, Java, and Pike modes.

U.12 Fortran Mode

Fortran mode and its special features.

U.13 Asm Mode

Asm mode and its special features.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.1 Major Modes for Programming Languages

Emacs has specialized major modes for various programming languages. See section R. Major Modes. A programming language major mode typically specifies the syntax of expressions, the customary rules for indentation, how to do syntax highlighting for the language, and how to find the beginning of a function definition. It often customizes or provides facilities for compiling and debugging programs as well.

Ideally, Emacs should provide a major mode for each programming language that you might want to edit; if it doesn't have a mode for your favorite language, you can contribute one. But often the mode for one language can serve for other syntactically similar languages. The major mode for language l is called l-mode, and you can select it by typing M-x l-mode RET. See section R.1 How Major Modes are Chosen.

The existing programming language major modes include Lisp, Scheme (a variant of Lisp) and the Scheme-based DSSSL expression language, Ada, Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixed format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (TeX's companion for font creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Simula, Tcl, and VHDL. There is also a major mode for makefiles, called Makefile mode. An alternative mode for Perl is called CPerl mode. Modes are available for the scripting languages of the common GNU and Unix shells, VMS DCL, and MS-DOS/MS-Windows `BAT' files. There are also major modes for editing various sorts of configuration files.

In most programming languages, indentation should vary from line to line to illustrate the structure of the program. So the major modes for programming languages arrange for TAB to update the indentation of the current line. They also rebind DEL to treat a tab as if it were the equivalent number of spaces; this lets you delete one column of indentation without worrying whether the whitespace consists of spaces or tabs. Use C-b C-d to delete a tab character before point, in these modes.

Separate manuals are available for the modes for Ada (see section `Ada Mode' in Ada Mode), C/C++/Objective C/Java/Corba IDL (see section `CC Mode' in CC Mode) and the IDLWAVE modes (see section `IDLWAVE' in IDLWAVE User Manual).

Turning on a major mode runs a normal hook called the mode hook, which is the value of a Lisp variable. Each major mode has a mode hook, and the hook's name is always made from the mode command's name by adding `-hook'. For example, turning on C mode runs the hook c-mode-hook, while turning on Lisp mode runs the hook lisp-mode-hook. The purpose of the mode hook is to give you a place to set up customizations for that major mode. See section AD.2.3 Hooks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.2 Top-Level Definitions, or Defuns

In Emacs, a major definition at the top level in the buffer is called a defun. The name comes from Lisp, but in Emacs we use it for all languages.

In most programming language modes, Emacs assumes that a defun is any pair of parentheses (or braces, if the language uses braces this way) that starts at the left margin. For example, in C, the body of a function definition is normally a defun, because the open-brace that begins it is normally at the left margin. A variable's initializer can also count as a defun, if the open-brace that begins the initializer is at the left margin.

However, some language modes provide their own code for recognizing defuns in a way that suits the language syntax and conventions better.

U.2.1 Left Margin Convention

An open-paren or similar opening delimiter starts a defun if it is at the left margin.

U.2.2 Moving by Defuns

Commands to move over or mark a major definition.

U.2.3 Imenu

Making buffer indexes as menus.

U.2.4 Which Function Mode

Which Function mode shows which function you are in.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.2.1 Left Margin Convention

In most major modes, Emacs assumes that any opening delimiter found at the left margin is the start of a top-level definition, or defun. Therefore, never put an opening delimiter at the left margin unless it should have that significance. For instance, never put an open-parenthesis at the left margin in a Lisp file unless it is the start of a top-level list. Never put an open-brace or other opening delimiter at the beginning of a line of C code unless it is at top level.

If you don't follow this convention, not only will you have trouble when you explicitly use the commands for motion by defuns; other features that use them will also give you trouble. This includes the indentation commands (see section U.3 Indentation for Programs) and Font Lock mode (see section J.2 Font Lock mode).

The most likely problem case is when you want an opening delimiter at the start of a line inside a string. To avoid trouble, put an escape character (`\', in C and Emacs Lisp, `/' in some other Lisp dialects) before the opening delimiter. This will not affect the contents of the string, but will prevent that opening delimiter from starting a defun. Here's an example:
  (insert "Foo:
\(bar)
")
In the earliest days, the original Emacs found defuns by moving upward a level of parentheses or braces until there were no more levels to go up. This always required scanning all the way back to the beginning of the buffer, even for a small function. To speed up the operation, we changed Emacs to assume that any opening delimiter at the left margin is the start of a defun. This heuristic is nearly always right, and avoids the need to scan back to the beginning of the buffer. However, it mandates following the convention described above.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.2.2 Moving by Defuns

These commands move point or set up the region based on top-level major definitions, also called defuns.

C-M-a
Move to beginning of current or preceding defun (beginning-of-defun).
C-M-e
Move to end of current or following defun (end-of-defun).
C-M-h
Put region around whole current or following defun (mark-defun).
The commands to move to the beginning and end of the current defun are C-M-a (beginning-of-defun) and C-M-e (end-of-defun). If you repeat one of these commands, or use a positive numeric argument, each repetition moves to the next defun in the direction of motion.

C-M-a with a negative argument -n moves forward n times to the next beginning of a defun. This is not exactly the same place that C-M-e with argument n would move to; the end of this defun is not usually exactly the same place as the beginning of the following defun. (Whitespace, comments, and perhaps declarations can separate them.) Likewise, C-M-e with a negative argument moves back to an end of a defun, which is not quite the same as C-M-a with a positive argument.

To operate on the current defun, use C-M-h (mark-defun) which puts point at the beginning and mark at the end of the current defun. This is the easiest way to get ready to kill the defun in order to move it to a different place in the file. If you use the command while point is between defuns, it uses the following defun.

In C mode, C-M-h runs the function c-mark-function, which is almost the same as mark-defun; the difference is that it backs up over the argument declarations, function name and returned data type so that the entire C function is inside the region. This is an example of how major modes adjust the standard key bindings so that they do their standard jobs in a way better fitting a particular language. Other major modes may replace any or all of these key bindings for that purpose.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.2.3 Imenu

The Imenu facility offers a way to find the the major definitions in a file by name. It is also useful in text formatter major modes, where it treats each chapter, section, etc., as a definition. (See section W.2 Tags Tables, for a more powerful feature that handles multiple files together.)

If you type M-x imenu, it reads the name of a definition using the minibuffer, then moves point to that definition. You can use completion to specify the name; the command always displays the whole list of valid names.

Alternatively, you can bind the command imenu to a mouse click. Then it displays mouse menus for you to select a definition name. You can also add the buffer's index to the menu bar by calling imenu-add-menubar-index. If you want to have this menu bar item available for all buffers in a certain major mode, you can do this by adding imenu-add-menubar-index to its mode hook. But if you have done that, you will have to wait each time you visit a file in that mode, while Emacs finds all the definitions in that buffer.

When you change the contents of a buffer, if you add or delete definitions, you can update the buffer's index based on the new contents by invoking the `*Rescan*' item in the menu. Rescanning happens automatically if you set imenu-auto-rescan to a non-nil value. There is no need to rescan because of small changes in the text.

You can customize the way the menus are sorted by setting the variable imenu-sort-function. By default, names are ordered as they occur in the buffer; if you want alphabetic sorting, use the symbol imenu--sort-by-name as the value. You can also define your own comparison function by writing Lisp code.

Imenu provides the information to guide Which Function mode (see section U.2.4 Which Function Mode). The Speedbar can also use it (see section P.9 Making and Using a Speedbar Frame).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.2.4 Which Function Mode

Which Function mode is a minor mode that displays the current function name in the mode line, updating it as you move around in a buffer.

To enable (or disable) Which Function mode, use the command M-x which-function-mode. This command is global; it applies to all buffers, both existing ones and those yet to be created. However, it only takes effect in certain major modes, those listed in the value of which-func-modes. If the value is t, then Which Function mode applies to all major modes that know how to support it--in other words, all the major modes that support Imenu.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.3 Indentation for Programs

The best way to keep a program properly indented is to use Emacs to reindent it as you change it. Emacs has commands to indent properly either a single line, a specified number of lines, or all of the lines inside a single parenthetical grouping.

U.3.1 Basic Program Indentation Commands

Indenting a single line.

U.3.2 Indenting Several Lines

Commands to reindent many lines at once.

U.3.3 Customizing Lisp Indentation

Specifying how each Lisp function should be indented.

U.3.4 Commands for C Indentation

Extra features for indenting C and related modes.

U.3.5 Customizing C Indentation

Controlling indentation style for C and related modes.

Emacs also provides a Lisp pretty-printer in the library pp. This program reformats a Lisp object with indentation chosen to look nice.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.3.1 Basic Program Indentation Commands

The basic indentation commands indent a single line according to the usual conventions of the language you are editing.

TAB
Adjust indentation of current line.
C-j
Equivalent to RET followed by TAB (newline-and-indent).
LINEFEED
This key, if the keyboard has it, is another way to enter C-j.
The basic indentation command is TAB, which gives the current line the correct indentation as determined from the previous lines. The function that TAB runs depends on the major mode; it is indent-for-tab-command in Lisp mode, c-indent-command in C mode, etc. These functions understand the syntax and conventions of different languages, but they all do conceptually the same job: TAB in any programming-language major mode inserts or deletes whitespace at the beginning of the current line, independent of where point is in the line. If point was inside the whitespace at the beginning of the line, TAB puts it at the end of that whitespace; otherwise, TAB keeps point fixed with respect to the characters around it.

Use C-q TAB to insert a tab at point.

When entering lines of new code, use C-j (newline-and-indent), which is equivalent to a RET followed by a TAB. C-j at the end of a line creates a blank line and then gives it the appropriate indentation.

TAB indents lines that start within a parenthetical grouping each under the preceding line (or the text after the parenthesis). Therefore, if you manually give one of these lines a nonstandard indentation, the lines below will tend to follow it. This behavior is convenient in cases where you have overridden the standard result of TAB because you find it unaesthetic for a particular line.

Remember that an open-parenthesis, open-brace or other opening delimiter at the left margin is assumed by Emacs (including the indentation routines) to be the start of a function. Therefore, you must never have an opening delimiter in column zero that is not the beginning of a function, not even inside a string. This restriction is vital for making the indentation commands fast; you must simply accept it. See section U.2.1 Left Margin Convention, for more information on this.

Normally, lines are indented with tabs and spaces. If you want Emacs to use spaces only, see S.3 Tabs vs. Spaces.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.3.2 Indenting Several Lines

When you wish to reindent several lines of code which have been altered or moved to a different level in the parenthesis structure, you have several commands available.

C-M-q
Reindent all the lines within one parenthetical grouping(indent-sexp).
C-M-\
Reindent all lines in the region (indent-region).
C-u TAB
Shift an entire parenthetical grouping rigidly sideways so that its first line is properly indented.
M-x indent-code-rigidly
Shift all the lines in the region rigidly sideways, but do not alter lines that start inside comments and strings.
You can reindent the contents of a single parenthetical grouping by positioning point before the beginning of it and typing C-M-q (indent-sexp in Lisp mode, c-indent-exp in C mode; also bound to other suitable commands in other modes). The indentation of the line where the grouping starts is not changed; therefore, this changes only the relative indentation within the grouping, not its overall indentation. To correct that as well, type TAB first.

Another way to specify the range to be reindented is with the region. The command C-M-\ (indent-region) applies TAB to every line whose first character is between point and mark.

If you like the relative indentation within a grouping, but not the indentation of its first line, you can type C-u TAB to reindent the whole grouping as a rigid unit. (This works in Lisp modes and C and related modes.) TAB with a numeric argument reindents the current line as usual, then reindents by the same amount all the lines in the parenthetical grouping starting on the current line. It is clever, though, and does not alter lines that start inside strings, or C preprocessor lines when in C mode.

You can also perform this operation on the region, using the command M-x indent-code-rigidly. It rigidly shifts all the lines in the region sideways, like indent-rigidly does (see section S.1 Indentation Commands and Techniques). It doesn't alter the indentation of lines that start inside a comment or a string, unless the region starts inside that comment or string.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.3.3 Customizing Lisp Indentation

The indentation pattern for a Lisp expression can depend on the function called by the expression. For each Lisp function, you can choose among several predefined patterns of indentation, or define an arbitrary one with a Lisp program.

The standard pattern of indentation is as follows: the second line of the expression is indented under the first argument, if that is on the same line as the beginning of the expression; otherwise, the second line is indented underneath the function name. Each following line is indented under the previous line whose nesting depth is the same.

If the variable lisp-indent-offset is non-nil, it overrides the usual indentation pattern for the second line of an expression, so that such lines are always indented lisp-indent-offset more columns than the containing list.

Certain functions override the standard pattern. Functions whose names start with def treat the the second lines as the start of a body, by indenting the second line lisp-body-indent additional columns beyond the open-parenthesis that starts the expression.

You can override the standard pattern in various ways for individual functions, according to the lisp-indent-function property of the function name. There are four possibilities for this property:

nil
This is the same as no property--use the standard indentation pattern.
defun
Handle this function like a `def' construct: treat the second line as the start of a body.
a number, number
The first number arguments of the function are distinguished arguments; the rest are considered the body of the expression. A line in the expression is indented according to whether the first argument on it is distinguished or not. If the argument is part of the body, the line is indented lisp-body-indent more columns than the open-parenthesis starting the containing expression. If the argument is distinguished and is either the first or second argument, it is indented twice that many extra columns. If the argument is distinguished and not the first or second argument, the line uses the standard pattern.
a symbol, symbol
symbol should be a function name; that function is called to calculate the indentation of a line within this expression. The function receives two arguments:
state
The value returned by parse-partial-sexp (a Lisp primitive for indentation and nesting computation) when it parses up to the beginning of this line.
pos
The position at which the line being indented begins. It should return either a number, which is the number of columns of indentation for that line, or a list whose car is such a number. The difference between returning a number and returning a list is that a number says that all following lines at the same nesting level should be indented just like this one; a list says that following lines might call for different indentations. This makes a difference when the indentation is being computed by C-M-q; if the value is a number, C-M-q need not recalculate indentation for the following lines until the end of the list.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.3.4 Commands for C Indentation

Here are special features for indentation in C mode and related modes:

C-c C-q
Reindent the current top-level function definition or aggregate type declaration (c-indent-defun).

C-M-q
Reindent each line in the balanced expression that follows point (c-indent-exp). A prefix argument inhibits error checking and warning messages about invalid syntax.

TAB
Reindent the current line, and/or in some cases insert a tab character (c-indent-command).
If c-tab-always-indent is t, this command always reindents the current line and does nothing else. This is the default.

If that variable is nil, this command reindents the current line only if point is at the left margin or in the line's indentation; otherwise, it inserts a tab (or the equivalent number of spaces, if indent-tabs-mode is nil).

Any other value (not nil or t) means always reindent the line, and also insert a tab if within a comment, a string, or a preprocessor directive.
To reindent the whole current buffer, type C-x h C-M-\. This first selects the whole buffer as the region, then reindents that region.

To reindent the current block, use C-M-u C-M-q. This moves to the front of the block and then reindents it all.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.3.5 Customizing C Indentation

C mode and related modes use a simple yet flexible mechanism for customizing indentation. The mechanism works in two steps: first it classifies the line syntactically according to its contents and context; second, it associates each kind of syntactic construct with an indentation offset based on your selected style.

M-x c-set-style RET style RET
Select predefined indentation style style.
A style is a named collection of indentation customizations that can be used in C mode and the related modes. Emacs comes with several predefined styles, including gnu, k&r, bsd, stroustrup, linux, python, java, whitesmith, ellemtel, cc-mode, and user. Some of these styles are primarily intended for one language, but any of them can be used with any of the languages supported by these modes. To find out what a style looks like, select it and reindent some code, e.g., by typing C-M-q at the start of a function definition.

To choose a style for the current buffer, use the command M-x c-set-style. Specify a style name as an argument (case is not significant). This command affects the current buffer only, and it affects only future invocations of the indentation commands; it does not reindent the code in the buffer. To reindent the whole buffer in the new style, you can type C-x h C-M-\.

You can also set the variable c-default-style to specify the default style for various major modes. Its value should be an alist, in which each element specifies one major mode and which indentation style to use for it. For example,
(setq c-default-style
      '((java-mode . "java") (other . "gnu")))
specifies an explicit choice for Java mode, and the default `gnu' style for the other C-like modes. This variable takes effect when you select one of the C-like major modes; thus, if you specify a new default style for Java mode, you can make it take effect in an existing Java mode buffer by typing M-x java-mode there.

The gnu style specifies the formatting recommended by the GNU Project for C; it is the default, so as to encourage use of our recommended style.

See section `Customizing Indentation' in the CC Mode Manual, for more information on customizing indentation for C and related modes, including how to override parts of an existing style and how to define your own styles.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.4 Commands for Editing with Parentheses

This section describes the commands and features that take advantage of the parenthesis structure in a program, or help you keep it balanced.

When talking about these facilities, the term "parenthesis" also includes braces, brackets, or whatever delimiters are defined to match in pairs. The major mode controls which delimiters are significant, through the syntax table (see section AD.6 The Syntax Table). In Lisp, only parentheses count; in C, these commands apply to braces and brackets too.

You can use M-x check-parens to find any unbalanced parentheses and unbalanced string quotes in the buffer.

U.4.1 Expressions with Balanced Parentheses

Expressions with balanced parentheses.

U.4.2 Moving in the Parenthesis Structure

Commands for moving up, down and across in the structure of parentheses.

U.4.3 Automatic Display Of Matching Parentheses

Insertion of a close-delimiter flashes matching open.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.4.1 Expressions with Balanced Parentheses

These commands deal with balanced expressions, also called sexps (9).

C-M-f
Move forward over a balanced expression (forward-sexp).
C-M-b
Move backward over a balanced expression(backward-sexp).
C-M-k
Kill balanced expression forward (kill-sexp).
C-M-DEL
Kill balanced expression backward (backward-kill-sexp).
C-M-t
Transpose expressions (transpose-sexps).
C-M-@
Put mark after following expression (mark-sexp).
Each programming language major mode customizes the definition of balanced expressions to suit that language. Balanced expressions typically include symbols, numbers, and string constants, as well as any pair of matching delimiters and their contents. Some languages have obscure forms of expression syntax that nobody has bothered to implement in Emacs.

By convention, the keys for these commands are all Control-Meta characters. They usually act on expressions just as the corresponding Meta characters act on words. For instance, the command C-M-b moves backward over a balanced expression, just as M-b moves back over a word.

To move forward over a balanced expression, use C-M-f (forward-sexp). If the first significant character after point is an opening delimiter (`(' in Lisp; `(', `[' or `{' in C), C-M-f moves past the matching closing delimiter. If the character begins a symbol, string, or number, C-M-f moves over that.

The command C-M-b (backward-sexp) moves backward over a balanced expression. The detailed rules are like those above for C-M-f, but with directions reversed. If there are prefix characters (single-quote, backquote and comma, in Lisp) preceding the expression, C-M-b moves back over them as well. The balanced expression commands move across comments as if they were whitespace, in most modes.

C-M-f or C-M-b with an argument repeats that operation the specified number of times; with a negative argument, it moves in the opposite direction.

Killing a whole balanced expression can be done with C-M-k (kill-sexp) or C-M-DEL (backward-kill-sexp). C-M-k kills the characters that C-M-f would move over, and C-M-DEL kills the characters that C-M-b would move over. On some machines, C-M-DEL typed on the console is a command to reboot; when that is so, you cannot use it as an Emacs command. This conflict is rare, though: usually the DEL key for Emacs is really BACKSPACE, and the reboot command is C-M-DELETE, so there is no conflict.

A somewhat random-sounding command which is nevertheless handy is C-M-t (transpose-sexps), which drags the previous balanced expression across the next one. An argument serves as a repeat count, and a negative argument drags the previous balanced expression backwards across those before it (thus canceling out the effect of C-M-t with a positive argument). An argument of zero, rather than doing nothing, transposes the balanced expressions ending at or after point and the mark.

To set the region around the next balanced expression in the buffer, use C-M-@ (mark-sexp), which sets mark at the same place that C-M-f would move to. C-M-@ takes arguments like C-M-f. In particular, a negative argument is useful for putting the mark at the beginning of the previous balanced expression.

In languages that use infix operators, such as C, it is not possible to recognize all balanced expressions as such because there can be multiple possibilities at a given position. For example, C mode does not treat `foo + bar' as a single expression, even though it is one C expression; instead, it recognizes `foo' as one expression and `bar' as another, with the `+' as punctuation between them. Both `foo + bar' and `foo' are legitimate choices for "the expression following point" when point is at the `f', so the expression commands must perforce choose one or the other to operate on. Note that `(foo + bar)' is recognized as a single expression in C mode, because of the parentheses.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.4.2 Moving in the Parenthesis Structure

The Emacs commands for handling parenthetical groupings see nothing except parentheses (or whatever characters must balance in the language you are working with), and the escape characters that might be used to quote those. They are mainly intended for editing programs, but can be useful for editing any text that has parentheses. They are sometimes called "list" commands because in Lisp these groupings are lists.

C-M-n
Move forward over a parenthetical group (forward-list).
C-M-p
Move backward over a parenthetical group(backward-list).
C-M-u
Move up in parenthesis structure (backward-up-list).
C-M-d
Move down in parenthesis structure (down-list).
The "list" commands C-M-n (forward-list) and C-M-p (backward-list) move over one (or n) parenthetical groupings, skipping blithely over any amount of text that doesn't include meaningful parentheses (symbols, strings, etc.).

C-M-n and C-M-p try to stay at the same level in the parenthesis structure. To move up one (or n) levels, use C-M-u (backward-up-list). C-M-u moves backward up past one unmatched opening delimiter. A positive argument serves as a repeat count; a negative argument reverses the direction of motion, so that the command moves forward and up one or more levels.

To move down in the parenthesis structure, use C-M-d (down-list). In Lisp mode, where `(' is the only opening delimiter, this is nearly the same as searching for a `('. An argument specifies the number of levels to go down.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.4.3 Automatic Display Of Matching Parentheses

The Emacs parenthesis-matching feature is designed to show automatically how parentheses (and other matching delimiters) match in the text. Whenever you type a self-inserting character that is a closing delimiter, the cursor moves momentarily to the location of the matching opening delimiter, provided that is on the screen. If it is not on the screen, Emacs displays some of the text near it in the echo area. Either way, you can tell which grouping you are closing off.

If the opening delimiter and closing delimiter are mismatched--such as in `[x)'---a warning message is displayed in the echo area.

Three variables control parenthesis match display. blink-matching-paren turns the feature on or off: nil disables it, but the default is t to enable match display.

blink-matching-delay says how many seconds to leave the cursor on the matching opening delimiter, before bringing it back to the real location of point; the default is 1, but on some systems it is useful to specify a fraction of a second.

blink-matching-paren-distance specifies how many characters back to search to find the matching opening delimiter. If the match is not found in that distance, scanning stops, and nothing is displayed. This is to prevent the scan for the matching delimiter from wasting lots of time when there is no match. The default is 25600.

Show Paren mode provides a more powerful kind of automatic matching. Whenever point is after a closing delimiter, that delimiter and its matching opening delimiter are both highlighted; otherwise, if point is before an opening delimiter, the matching closing delimiter is highlighted. (There is no need to highlight the opening delimiter in that case, because the cursor appears on top of that character.) Use the command M-x show-paren-mode to enable or disable this mode.

By default, show-paren-mode uses colors to highlight the parentheses. However, if your display doesn't support colors, you can customize the faces show-paren-match-face and show-paren-mismatch-face to use other attributes, such as bold or underline. See section AD.2.2.3 Customizing Faces.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.5 Manipulating Comments

Because comments are such an important part of programming, Emacs provides special commands for editing and inserting comments.

U.5.1 Comment Commands

Inserting, killing, and indenting comments.

U.5.2 Multiple Lines of Comments

Commands for adding and editing multi-line comments.

U.5.3 Options Controlling Comments

Customizing the comment features.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.5.1 Comment Commands

The comment commands in this table insert, kill and align comments. They are described in this section and following sections.

M-;
Insert or realign comment on current line; alternatively, comment or uncomment the region (comment-dwim).
C-u M-;
Kill comment on current line (comment-kill).
C-x ;
Set comment column (comment-set-column).
C-M-j
Like RET followed by inserting and aligning a comment (comment-indent-new-line).
M-x comment-region
Add or remove comment delimiters on all the lines in the region.
The command to create or align a comment is M-; (comment-dwim). The word "dwim" is an acronym for "Do What I Mean"; it indicates that this command can be used for many different jobs relating to comments, depending on the situation where you use it.

If there is no comment already on the line, M-; inserts a new comment, aligned at a specific column called the comment column. The new comment begins with the string Emacs thinks comments should start with (the value of comment-start; see below). Point is after that string, so you can insert the text of the comment right away. If the major mode has specified a string to terminate comments, M-; inserts that too, to keep the syntax valid.

If the text of the line extends past the comment column, then the comment start string is indented to a suitable boundary (usually, at least one space is inserted).

You can also use M-; to align an existing comment. If a line already contains the comment-start string, M-; reindents it to the conventional alignment and moves point after it. (Exception: comments starting in column 0 are not moved.) Even when an existing comment is properly aligned, M-; is still useful for moving directly to the start of the text inside the comment.

C-u M-; kills any comment on the current line, along with the whitespace before it. To reinsert the comment on another line, move to the end of that line, do C-y, and then do M-; to realign it.

Note that C-u M-; is not a distinct key; it is M-; (comment-dwim) with a prefix argument. That command is programmed so that when it receives a prefix argument it calls comment-kill. However, comment-kill is a valid command in its own right, and you can bind it directly to a key if you wish.

M-; does two other jobs when used with an active region in Transient Mark mode (see section H.2 Transient Mark Mode). Then it either adds or removes comment delimiters on each line of the region. (If every line is a comment, it removes comment delimiters from each; otherwise, it adds comment delimiters to each.) If you are not using Transient Mark mode, then you should use the commands comment-region and uncomment-region to do these jobs (see section U.5.2 Multiple Lines of Comments). A prefix argument used in these circumstances specifies how many comment delimiters to add or how many to delete.

Some major modes have special rules for indenting certain kinds of comments in certain contexts. For example, in Lisp code, comments which start with two semicolons are indented as if they were lines of code, instead of at the comment column. Comments which start with three semicolons are supposed to start at the left margin. Emacs understands these conventions by indenting a double-semicolon comment using TAB, and by not changing the indentation of a triple-semicolon comment at all.
;; This function is just an example
;;; Here either two or three semicolons are appropriate.
(defun foo (x)
;;; And now, the first part of the function:
  ;; The following line adds one.
  (1+ x))           ; This line adds one.
In C code, a comment preceded on its line by nothing but whitespace is indented like a line of code.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.5.2 Multiple Lines of Comments

If you are typing a comment and wish to continue it on another line, you can use the command C-M-j (comment-indent-new-line). This terminates the comment you are typing, creates a new blank line afterward, and begins a new comment indented under the old one. When Auto Fill mode is on, going past the fill column while typing a comment causes the comment to be continued in just this fashion. If point is not at the end of the line when C-M-j is typed, the text on the rest of the line becomes part of the new comment line.

To turn existing lines into comment lines, use the M-x comment-region command. It adds comment delimiters to the lines that start in the region, thus commenting them out. With a negative argument, it does the opposite--it deletes comment delimiters from the lines in the region.

With a positive argument, comment-region duplicates the last character of the comment start sequence it adds; the argument specifies how many copies of the character to insert. Thus, in Lisp mode, C-u 2 M-x comment-region adds `;;' to each line. Duplicating the comment delimiter is a way of calling attention to the comment. It can also affect how the comment is indented. In Lisp, for proper indentation, you should use an argument of two or three, if between defuns; if within a defun, it must be three.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.5.3 Options Controlling Comments

The comment column is stored in the variable comment-column. You can set it to a number explicitly. Alternatively, the command C-x ; (comment-set-column) sets the comment column to the column point is at. C-u C-x ; sets the comment column to match the last comment before point in the buffer, and then does a M-; to align the current line's comment under the previous one.

The variable comment-column is per-buffer: setting the variable in the normal fashion affects only the current buffer, but there is a default value which you can change with setq-default. See section AD.2.4 Local Variables. Many major modes initialize this variable for the current buffer.

The comment commands recognize comments based on the regular expression that is the value of the variable comment-start-skip. Make sure this regexp does not match the null string. It may match more than the comment starting delimiter in the strictest sense of the word; for example, in C mode the value of the variable is "/\\*+ *\\|//+ *"", which matches extra stars and spaces after the `/*' itself, and accepts C++ style comments also. (Note that `\\' is needed in Lisp syntax to include a `\' in the string, which is needed to deny the first star its special meaning in regexp syntax. See section K.5 Syntax of Regular Expressions.)

When a comment command makes a new comment, it inserts the value of comment-start to begin it. The value of comment-end is inserted after point, so that it will follow the text that you will insert into the comment. In C mode, comment-start has the value "/* " and comment-end has the value " */".

The variable comment-padding specifies how many spaces comment-region should insert on each line between the comment delimiter and the line's original text. The default is 1, to insert one space.

The variable comment-multi-line controls how C-M-j (indent-new-comment-line) behaves when used inside a comment. If comment-multi-line is nil, as it normally is, then the comment on the starting line is terminated and a new comment is started on the new following line. If comment-multi-line is not nil, then the new following line is set up as part of the same comment that was found on the starting line. This is done by not inserting a terminator on the old line, and not inserting a starter on the new line. In languages where multi-line comments work, the choice of value for this variable is a matter of taste.

The variable comment-indent-function should contain a function that will be called to compute the indentation for a newly inserted comment or for aligning an existing comment. It is set differently by various major modes. The function is called with no arguments, but with point at the beginning of the comment, or at the end of a line if a new comment is to be inserted. It should return the column in which the comment ought to start. For example, in Lisp mode, the indent hook function bases its decision on how many semicolons begin an existing comment, and on the code in the preceding lines.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.6 Documentation Lookup

Emacs provides several features you can use to look up the documentation of functions, variables and commands that you plan to use in your program.

U.6.1 Info Documentation Lookup

Looking up library functions and commands in Info files.

U.6.2 Man Page Lookup

Looking up man pages of library functions and commands.

U.6.3 Emacs Lisp Documentation Lookup

Looking up Emacs Lisp functions, etc.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.6.1 Info Documentation Lookup

For C, Lisp, and other languages that have documentation in Info, you can use C-h C-i (info-lookup-symbol) to view the Info documentation for a symbol. You specify the symbol with the minibuffer; the default is the symbol appearing in the buffer at point.

The major mode determines where to look for documentation for the symbol--which Info files to look in, and which indices to search. You can also use M-x info-lookup-file to look for documentation for a file name.

This feature currently supports the modes Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo, provided you have installed the relevant Info files, which are typically available with the appropriate GNU package.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.6.2 Man Page Lookup

On Unix, the main form of on-line documentation was the manual page or man page. In the GNU operating system, we hope to replace man pages with better-organized manuals that you can browse with Info (see section G.8 Other Help Commands). This process is not finished, so it is still useful to read manual pages.

You can read the man page for an operating system command, library function, or system call, with the M-x manual-entry command. It runs the man program to format the man page; if the system permits, it runs man asynchronously, so that you can keep on editing while the page is being formatted. (On MS-DOS and MS-Windows 3, you cannot edit while Emacs waits for man to finish.) The result goes in a buffer named `*Man topic*'. These buffers use a special major mode, Man mode, that facilitates scrolling and jumping to other manual pages. For details, type C-h m while in a man page buffer.

Each man page belongs to one of ten or more sections, each named by a digit or by a digit and a letter. Sometimes there are multiple man pages with the same name in different sections. To read a man page from a specific section, type `topic(section)' or `section topic' when M-x manual-entry prompts for the topic. For example, to read the man page for the C library function chmod (as opposed to a command of the same name), type M-x manual-entry RET chmod(2) RET (chmod is a system call, so it is in section `2').

If you do not specify a section, the results depend on how the man program works on your system. Some of them display only the first man page they find. Others display all man pages that have the specified name, so you can move between them with the M-n and M-p keys(10). The mode line shows how many manual pages are present in the Man buffer.

By default, Emacs highlights the text in man pages. For a long man page, highlighting can take substantial time. You can turn off highlighting of man pages by setting the variable Man-fontify-manpage-flag to nil.

If you insert the text of a man page into an Emacs buffer in some other fashion, you can use the command M-x Man-fontify-manpage to perform the same conversions that M-x manual-entry does.

An alternative way of reading manual pages is the M-x woman command(11). Unlike M-x man, it does not run any external programs to format and display the man pages; instead it does the job in Emacs Lisp, so it works on systems such as MS-Windows, where the man program (and the other programs it uses) are not generally available.

M-x woman prompts for a name of a manual page, and provides completion based on the list of manual pages that are installed on your machine; the list of available manual pages is computed automatically the first time you invoke woman. The word at point in the current buffer is used to suggest the default for the name the manual page.

With a numeric argument, M-x woman recomputes the list of the manual pages used for completion. This is useful if you add or delete manual pages.

If you type a name of a manual page and M-x woman finds that several manual pages by the same name exist in different sections, it pops up a window with possible candidates asking you to choose one of them.

By default, M-x woman looks for manual pages in the directories specified in the MANPATH environment variable. (If MANPATH is not set, woman uses a suitable default value, which can be customized.) More precisely, woman looks for subdirectories that match the shell wildcard pattern `man*' in each one of these directories, and tries to find the manual pages in those subdirectories. When first invoked, M-x woman converts the value of MANPATH to a list of directory names and stores that list in the woman-manpath variable. Changing the value of this variable is another way to control the list of directories used.

You can also augment the list of directories searched by woman by setting the value of the woman-path variable. This variable should hold a list of specific directories which woman should search, in addition to those in woman-manpath. Unlike woman-manpath, the directories in woman-path are searched for the manual pages, not for `man*' subdirectories.

Occasionally, you might need to display manual pages that are not in any of the directories listed by woman-manpath and woman-path. The M-x woman-find-file command prompts for a name of a manual page file, with completion, and then formats and displays that file like M-x woman does.

The first time you invoke M-x woman, it defines the Dired W key to run the woman-find-file command on the current line's file. You can disable this by setting the variable woman-dired-keys to nil. See section AB. Dired, the Directory Editor. In addition, the Tar-mode w key is define to invoke woman-find-file on the current line's archive member.

For more information about setting up and using M-x woman, see section `Browse UN*X Manual Pages WithOut Man' in The WoMan Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.6.3 Emacs Lisp Documentation Lookup

As you edit Lisp code to be run in Emacs, you can use the commands C-h f (describe-function) and C-h v (describe-variable) to view documentation of functions and variables that you want to use. These commands use the minibuffer to read the name of a function or variable to document, and display the documentation in a window. Their default arguments are based on the code in the neighborhood of point. For C-h f, the default is the function called in the innermost list containing point. C-h v uses the symbol name around or adjacent to point as its default.

A more automatic but less powerful method is Eldoc mode. This minor mode constantly displays in the echo area the argument list for the function being called at point. (In other words, it finds the function call that point is contained in, and displays the argument list of that function.) Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use the command M-x eldoc-mode to enable or disable this feature.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.7 Hideshow minor mode

Hideshow minor mode provides selective display of portions of a program, known as blocks. You can use M-x hs-minor-mode to enable or disable this mode, or add hs-minor-mode to the mode hook for certain major modes in order to enable it automatically for those modes.

Just what constitutes a block depends on the major mode. In C mode or C++ mode, they are delimited by braces, while in Lisp mode and similar modes they are delimited by parentheses. Multi-line comments also count as blocks.

C-c @ C-h
Hide the current block (hs-hide-block).
C-c @ C-s
Show the current block (hs-show-block).
C-c @ C-c
Either hide or show the current block (hs-toggle-hiding)
S-Mouse-2
Either hide or show the block you click on (hs-mouse-toggle-hiding)
C-c @ C-M-h
Hide all top-level blocks (hs-hide-all).
C-c @ C-M-s
Show everything in the buffer (hs-show-all).
C-c @ C-l
Hide all blocks n levels below this block (hs-hide-level).
These user options exist for customizing Hideshow mode.

hs-hide-comments-when-hiding-all
Non-nil says that hs-hide-all should hide comments too.

hs-isearch-open
Specifies what kind of hidden blocks to open in Isearch mode. The value should be one of these four symbols.

code
Open only code blocks.
comment
Open only comments.
t
Open both code blocks and comments.
nil
Open neither code blocks nor comments.

hs-special-modes-alist
A list of elements, each specifying how to initialize Hideshow variables for one major mode. See the variable's documentation string for more information.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.8 Completion for Symbol Names

In Emacs, completion is something you normally do in the minibuffer. But one kind of completion is available in all buffers: completion for symbol names.

The character M-TAB runs a command to complete the partial symbol before point against the set of meaningful symbol names. This command inserts at point any additional characters that it can determine from the partial name.

If the partial name in the buffer has multiple possible completions that differ in the very next character, so that it is impossible to complete even one more character, M-TAB displays a list of all possible completions in another window.

In most programming language major modes, M-TAB runs the command complete-symbol, which provides two kinds of completion. Normally it does completion based on a tags table (see section W.2 Tags Tables); with a numeric argument (regardless of the value), it does completion based on the names listed in the Info file indexes for your language. Thus, to complete the name of a symbol defined in your own program, use M-TAB with no argument; to complete the name of a standard library function, use C-u M-TAB. Of course, Info-based completion works only if there is an Info file for the standard library functions of your language, and only if it is installed at your site.

In Emacs-Lisp mode, the name space for completion normally consists of nontrivial symbols present in Emacs--those that have function definitions, values or properties. However, if there is an open-parenthesis immediately before the beginning of the partial symbol, only symbols with function definitions are considered as completions. The command which implements this is lisp-complete-symbol.

In Text mode and related modes, M-TAB completes words based on the spell-checker's dictionary. See section L.4 Checking and Correcting Spelling.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.9 Glasses minor mode

Glasses minor mode makes `unreadableIdentifiersLikeThis' readable by altering the way they display. It knows two different ways to do this: by displaying underscores between a lower-case letter and the following capital letter, and by emboldening the capital letters. It does not alter the buffer text, only the way they display, so you can use it even on read-only buffers. You can use the command M-x glasses-mode to enable or disable the mode in the current buffer; you can also add glasses-mode to the mode hook of the programming language major modes in which you normally want to use Glasses mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.10 Other Features Useful for Editing Programs

A number of Emacs commands that aren't designed specifically for editing programs are useful for that nonetheless.

The Emacs commands that operate on words, sentences and paragraphs are useful for editing code. Most symbols names contain words (see section T.1 Words); sentences can be found in strings and comments (see section T.2 Sentences). Paragraphs in the strict sense can be found in program code (in long comments), but the paragraph commands are useful in other places too, because programming language major modes define paragraphs to begin and end at blank lines (see section T.3 Paragraphs). Judicious use of blank lines to make the program clearer will also provide useful chunks of text for the paragraph commands to work on. Auto Fill mode, if enabled in a programming language major mode, indents the new lines which it creates.

The selective display feature is useful for looking at the overall structure of a function (see section J.9 Selective Display). This feature hides the lines that are indented more than a specified amount. Programming modes often support Outline minor mode (see section T.8 Outline Mode). The Foldout package provides folding-editor features (see section T.8.5 Folding Editing).

The "automatic typing" features may be useful for writing programs. See section `Autotyping' in Autotyping.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.11 C and Related Modes

This section gives a brief description of the special features available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes. (These are called "C mode and related modes.") See section `ccmode' in CC Mode, for a more extensive description of these modes and their special features.

U.11.1 C Mode Motion Commands

Commands to move by C statements, etc.

U.11.2 Electric C Characters

Colon and other chars can automatically reindent.

U.11.3 Hungry Delete Feature in C

A more powerful DEL command.

U.11.4 Other Commands for C Mode

Filling comments, viewing expansion of macros, and other neat features.

U.11.5 Comments in C Modes

Options for customizing comment style.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.11.1 C Mode Motion Commands

This section describes commands for moving point, in C mode and related modes.

C-c C-u
Move point back to the containing preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move point forward to the end of the containing preprocessor conditional. When going backwards, #elif is treated like #else followed by #if. When going forwards, #elif is ignored.

C-c C-p
Move point back over a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move forward.

C-c C-n
Move point forward across a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move backward.

M-a
Move point to the beginning of the innermost C statement (c-beginning-of-statement). If point is already at the beginning of a statement, move to the beginning of the preceding statement. With prefix argument n, move back n - 1 statements.
If point is within a string or comment, or next to a comment (only whitespace between them), this command moves by sentences instead of statements.

When called from a program, this function takes three optional arguments: the numeric prefix argument, a buffer position limit (don't move back before that place), and a flag that controls whether to do sentence motion when inside of a comment.

M-e
Move point to the end of the innermost C statement; like M-a except that it moves in the other direction (c-end-of-statement).

M-x c-backward-into-nomenclature
Move point backward to beginning of a C++ nomenclature section or word. With prefix argument n, move n times. If n is negative, move forward. C++ nomenclature means a symbol name in the style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter begins a section or word.
In the GNU project, we recommend using underscores to separate words within an identifier in C or C++, rather than using case distinctions.

M-x c-forward-into-nomenclature
Move point forward to end of a C++ nomenclature section or word. With prefix argument n, move n times.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.11.2 Electric C Characters

In C mode and related modes, certain printing characters are "electric"---in addition to inserting themselves, they also reindent the current line and may insert newlines. This feature is controlled by the variable c-auto-newline. The "electric" characters are {, }, :, #, ;, ,, <, >, /, *, (, and ).

Electric characters insert newlines only when the auto-newline feature is enabled (indicated by `/a' in the mode line after the mode name). This feature is controlled by the variable c-auto-newline. You can turn this feature on or off with the command C-c C-a:

C-c C-a
Toggle the auto-newline feature (c-toggle-auto-state). With a prefix argument, this command turns the auto-newline feature on if the argument is positive, and off if it is negative.
The colon character is electric because that is appropriate for a single colon. But when you want to insert a double colon in C++, the electric behavior of colon is inconvenient. You can insert a double colon with no reindentation or newlines by typing C-c ::

C-c :
Insert a double colon scope operator at point, without reindenting the line or adding any newlines (c-scope-operator).
The electric # key reindents the line if it appears to be the beginning of a preprocessor directive. This happens when the value of c-electric-pound-behavior is (alignleft). You can turn this feature off by setting c-electric-pound-behavior to nil.

The variable c-hanging-braces-alist controls the insertion of newlines before and after inserted braces. It is an association list with elements of the following form: (syntactic-symbol . nl-list). Most of the syntactic symbols that appear in c-offsets-alist are meaningful here as well.

The list nl-list may contain either of the symbols before or after, or both; or it may be nil. When a brace is inserted, the syntactic context it defines is looked up in c-hanging-braces-alist; if it is found, the nl-list is used to determine where newlines are inserted: either before the brace, after, or both. If not found, the default is to insert a newline both before and after braces.

The variable c-hanging-colons-alist controls the insertion of newlines before and after inserted colons. It is an association list with elements of the following form: (syntactic-symbol . nl-list). The list nl-list may contain either of the symbols before or after, or both; or it may be nil.

When a colon is inserted, the syntactic symbol it defines is looked up in this list, and if found, the nl-list is used to determine where newlines are inserted: either before the brace, after, or both. If the syntactic symbol is not found in this list, no newlines are inserted.

Electric characters can also delete newlines automatically when the auto-newline feature is enabled. This feature makes auto-newline more acceptable, by deleting the newlines in the most common cases where you do not want them. Emacs can recognize several cases in which deleting a newline might be desirable; by setting the variable c-cleanup-list, you can specify which of these cases that should happen. The variable's value is a list of symbols, each describing one case for possible deletion of a newline. Here are the meaningful symbols, and their meanings:

brace-catch-brace
Clean up `} catch (condition) {' constructs by placing the entire construct on a single line. The clean-up occurs when you type the `{', if there is nothing between the braces aside from catch and condition.

brace-else-brace
Clean up `} else {' constructs by placing the entire construct on a single line. The clean-up occurs when you type the `{' after the else, but only if there is nothing but white space between the braces and the else.

brace-elseif-brace
Clean up `} else if (...) {' constructs by placing the entire construct on a single line. The clean-up occurs when you type the `{', if there is nothing but white space between the `}' and `{' aside from the keywords and the if-condition.

empty-defun-braces
Clean up empty defun braces by placing the braces on the same line. Clean-up occurs when you type the closing brace.

defun-close-semi
Clean up the semicolon after a struct or similar type declaration, by placing the semicolon on the same line as the closing brace. Clean-up occurs when you type the semicolon.

list-close-comma
Clean up commas following braces in array and aggregate initializers. Clean-up occurs when you type the comma.

scope-operator
Clean up double colons which may designate a C++ scope operator, by placing the colons together. Clean-up occurs when you type the second colon, but only when the two colons are separated by nothing but whitespace.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.11.3 Hungry Delete Feature in C

When the hungry-delete feature is enabled (indicated by `/h' or `/ah' in the mode line after the mode name), a single DEL command deletes all preceding whitespace, not just one space. To turn this feature on or off, use C-c C-d:

C-c C-d
Toggle the hungry-delete feature (c-toggle-hungry-state). With a prefix argument, this command turns the hungry-delete feature on if the argument is positive, and off if it is negative.

C-c C-t
Toggle the auto-newline and hungry-delete features, both at once (c-toggle-auto-hungry-state).
The variable c-hungry-delete-key controls whether the hungry-delete feature is enabled.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.11.4 Other Commands for C Mode

C-M-h
Put mark at the end of a function definition, and put point at the beginning (c-mark-function).

M-q
Fill a paragraph, handling C and C++ comments (c-fill-paragraph). If any part of the current line is a comment or within a comment, this command fills the comment or the paragraph of it that point is in, preserving the comment indentation and comment delimiters.

C-c C-e
Run the C preprocessor on the text in the region, and show the result, which includes the expansion of all the macro calls (c-macro-expand). The buffer text before the region is also included in preprocessing, for the sake of macros defined there, but the output from this part isn't shown.
When you are debugging C code that uses macros, sometimes it is hard to figure out precisely how the macros expand. With this command, you don't have to figure it out; you can see the expansions.

C-c C-\
Insert or align `\' characters at the ends of the lines of the region (c-backslash-region). This is useful after writing or editing a C macro definition.
If a line already ends in `\', this command adjusts the amount of whitespace before it. Otherwise, it inserts a new `\'. However, the last line in the region is treated specially; no `\' is inserted on that line, and any `\' there is deleted.

M-x cpp-highlight-buffer
Highlight parts of the text according to its preprocessor conditionals. This command displays another buffer named `*CPP Edit*', which serves as a graphic menu for selecting how to display particular kinds of conditionals and their contents. After changing various settings, click on `[A]pply these settings' (or go to that buffer and type a) to rehighlight the C mode buffer accordingly.

C-c C-s
Display the syntactic information about the current source line (c-show-syntactic-information). This is the information that directs how the line is indented.

M-x cwarn-mode

M-x global-cwarn-mode
CWarn minor mode highlights certain suspicious C and C++ constructions:

Assignments inside expressions.
Semicolon following immediately after `if', `for', and `while' (except after a `do ... while' statement);
C++ functions with reference parameters.

You can enable the mode for one buffer with the command M-x cwarn-mode, or for all suitable buffers with the command M-x global-cwarn-mode or by customizing the variable global-cwarn-mode. You must also enable Font Lock mode to make it work.

M-x hide-ifdef-mode
Hide-ifdef minor mode hides selected code within `#if' and `#ifdef' preprocessor blocks. See the documentation string of hide-ifdef-mode for more information.

M-x ff-find-related-file
Find a file "related" in a special way to the file visited by the current buffer. Typically this will be the header file corresponding to a C/C++ source file, or vice versa. The variable ff-related-file-alist specifies how to compute related file names.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.11.5 Comments in C Modes

C mode and related modes use a number of variables for controlling comment format.

c-comment-only-line-offset
Extra offset for line which contains only the start of a comment. It can be either an integer or a cons cell of the form (non-anchored-offset . anchored-offset), where non-anchored-offset is the amount of offset given to non-column-zero anchored comment-only lines, and anchored-offset is the amount of offset to give column-zero anchored comment-only lines. Just an integer as value is equivalent to (val . 0).

c-comment-start-regexp
This buffer-local variable specifies how to recognize the start of a comment.

c-hanging-comment-ender-p
If this variable is nil, c-fill-paragraph leaves the comment terminator of a block comment on a line by itself. The default value is t, which puts the comment-end delimiter `*/' at the end of the last line of the comment text.

c-hanging-comment-starter-p
If this variable is nil, c-fill-paragraph leaves the starting delimiter of a block comment on a line by itself. The default value is t, which puts the comment-start delimiter `/*' at the beginning of the first line of the comment text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12 Fortran Mode

Fortran mode provides special motion commands for Fortran statements and subprograms, and indentation commands that understand Fortran conventions of nesting, line numbers and continuation statements. Fortran mode has its own Auto Fill mode that breaks long lines into proper Fortran continuation lines.

Special commands for comments are provided because Fortran comments are unlike those of other languages. Built-in abbrevs optionally save typing when you insert Fortran keywords.

Use M-x fortran-mode to switch to this major mode. This command runs the hook fortran-mode-hook (see section AD.2.3 Hooks).

Fortan mode is meant for editing Fortran77 "fixed format" source code. For editing the modern Fortran90 "free format" source code, use F90 mode (f90-mode). Emacs normally uses Fortran mode for files with extension `.f', `.F' or `.for', and F90 mode for the extension `.f90'. GNU Fortran supports both kinds of format.

U.12.1 Motion Commands

Moving point by statements or subprograms.

U.12.2 Fortran Indentation

Indentation commands for Fortran.

U.12.3 Fortran Comments

Inserting and aligning comments.

U.12.4 Fortran Auto Fill Mode

Auto fill minor mode for Fortran.

U.12.5 Checking Columns in Fortran

Measuring columns for valid Fortran.

U.12.6 Fortran Keyword Abbrevs

Built-in abbrevs for Fortran keywords.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.1 Motion Commands

In addition to the normal commands for moving by and operating on "defuns" (Fortran subprograms--functions and subroutines), Fortran mode provides special commands to move by statements.

C-c C-n
Move to beginning of current or next statement (fortran-next-statement).

C-c C-p
Move to beginning of current or previous statement (fortran-previous-statement).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.2 Fortran Indentation

Special commands and features are needed for indenting Fortran code in order to make sure various syntactic entities (line numbers, comment line indicators and continuation line flags) appear in the columns that are required for standard Fortran.

U.12.2.1 Fortran Indentation and Filling Commands

Commands for indenting and filling Fortran.

U.12.2.2 Continuation Lines

How continuation lines indent.

U.12.2.3 Line Numbers

How line numbers auto-indent.

U.12.2.4 Syntactic Conventions

Conventions you must obey to avoid trouble.

U.12.2.5 Variables for Fortran Indentation

Variables controlling Fortran indent style.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.2.1 Fortran Indentation and Filling Commands

C-M-j
Break the current line and set up a continuation line (fortran-split-line).
M-^
Join this line to the previous line (fortran-join-line).
C-M-q
Indent all the lines of the subprogram point is in (fortran-indent-subprogram).
M-q
Fill a comment block or statement.
The key C-M-q runs fortran-indent-subprogram, a command to reindent all the lines of the Fortran subprogram (function or subroutine) containing point.

The key C-M-j runs fortran-split-line, which splits a line in the appropriate fashion for Fortran. In a non-comment line, the second half becomes a continuation line and is indented accordingly. In a comment line, both halves become separate comment lines.

M-^ or C-c C-d runs the command fortran-join-line, which joins a continuation line back to the previous line, roughly as the inverse of fortran-split-line. The point must be on a continuation line when this command is invoked.

M-q in Fortran mode fills the comment block or statement that point is in. This removes any excess statement continuations.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.2.2 Continuation Lines

Most modern Fortran compilers allow two ways of writing continuation lines. If the first non-space character on a line is in column 5, then that line is a continuation of the previous line. We call this fixed format. (In GNU Emacs we always count columns from 0.) The variable fortran-continuation-string specifies what character to put on column 5. A line that starts with a tab character followed by any digit except `0' is also a continuation line. We call this style of continuation tab format.

Fortran mode can make either style of continuation line, but you must specify which one you prefer. The value of the variable indent-tabs-mode controls the choice: nil for fixed format, and non-nil for tab format. You can tell which style is presently in effect by the presence or absence of the string `Tab' in the mode line.

If the text on a line starts with the conventional Fortran continuation marker `$', or if it begins with any non-whitespace character in column 5, Fortran mode treats it as a continuation line. When you indent a continuation line with TAB, it converts the line to the current continuation style. When you split a Fortran statement with C-M-j, the continuation marker on the newline is created according to the continuation style.

The setting of continuation style affects several other aspects of editing in Fortran mode. In fixed format mode, the minimum column number for the body of a statement is 6. Lines inside of Fortran blocks that are indented to larger column numbers always use only the space character for whitespace. In tab format mode, the minimum column number for the statement body is 8, and the whitespace before column 8 must always consist of one tab character.

When you enter Fortran mode for an existing file, it tries to deduce the proper continuation style automatically from the file contents. The first line that begins with either a tab character or six spaces determines the choice. The variable fortran-analyze-depth specifies how many lines to consider (at the beginning of the file); if none of those lines indicates a style, then the variable fortran-tab-mode-default specifies the style. If it is nil, that specifies fixed format, and non-nil specifies tab format.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.2.3 Line Numbers

If a number is the first non-whitespace in the line, Fortran indentation assumes it is a line number and moves it to columns 0 through 4. (Columns always count from 0 in GNU Emacs.)

Line numbers of four digits or less are normally indented one space. The variable fortran-line-number-indent controls this; it specifies the maximum indentation a line number can have. Line numbers are indented to right-justify them to end in column 4 unless that would require more than this maximum indentation. The default value of the variable is 1.

Simply inserting a line number is enough to indent it according to these rules. As each digit is inserted, the indentation is recomputed. To turn off this feature, set the variable fortran-electric-line-number to nil. Then inserting line numbers is like inserting anything else.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.2.4 Syntactic Conventions

Fortran mode assumes that you follow certain conventions that simplify the task of understanding a Fortran program well enough to indent it properly:

Two nested `do' loops never share a `continue' statement.

Fortran keywords such as `if', `else', `then', `do' and others are written without embedded whitespace or line breaks.
Fortran compilers generally ignore whitespace outside of string constants, but Fortran mode does not recognize these keywords if they are not contiguous. Constructs such as `else if' or `end do' are acceptable, but the second word should be on the same line as the first and not on a continuation line.

If you fail to follow these conventions, the indentation commands may indent some lines unaesthetically. However, a correct Fortran program retains its meaning when reindented even if the conventions are not followed.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.2.5 Variables for Fortran Indentation

Several additional variables control how Fortran indentation works:

fortran-do-indent
Extra indentation within each level of `do' statement (default 3).

fortran-if-indent
Extra indentation within each level of `if' statement (default 3). This value is also used for extra indentation within each level of the Fortran 90 `where' statement.

fortran-structure-indent
Extra indentation within each level of `structure', `union', or `map' statements (default 3).

fortran-continuation-indent
Extra indentation for bodies of continuation lines (default 5).

fortran-check-all-num-for-matching-do
If this is nil, indentation assumes that each `do' statement ends on a `continue' statement. Therefore, when computing indentation for a statement other than `continue', it can save time by not checking for a `do' statement ending there. If this is non-nil, indenting any numbered statement must check for a `do' that ends there. The default is nil.

fortran-blink-matching-if
If this is t, indenting an `endif' statement moves the cursor momentarily to the matching `if' statement to show where it is. The default is nil.

fortran-minimum-statement-indent-fixed
Minimum indentation for fortran statements when using fixed format continuation line style. Statement bodies are never indented less than this much. The default is 6.

fortran-minimum-statement-indent-tab
Minimum indentation for fortran statements for tab format continuation line style. Statement bodies are never indented less than this much. The default is 8.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.3 Fortran Comments

The usual Emacs comment commands assume that a comment can follow a line of code. In Fortran, the standard comment syntax requires an entire line to be just a comment. Therefore, Fortran mode replaces the standard Emacs comment commands and defines some new variables.

Fortran mode can also handle the Fortran90 comment syntax where comments start with `!' and can follow other text. Because only some Fortran77 compilers accept this syntax, Fortran mode will not insert such comments unless you have said in advance to do so. To do this, set the variable comment-start to `"!"' (see section AD.2 Variables).

M-;
Align comment or insert new comment (fortran-comment-indent).

C-x ;
Applies to nonstandard `!' comments only.

C-c ;
Turn all lines of the region into comments, or (with argument) turn them back into real code (fortran-comment-region).
M-; in Fortran mode is redefined as the command fortran-comment-indent. Like the usual M-; command, this recognizes any kind of existing comment and aligns its text appropriately; if there is no existing comment, a comment is inserted and aligned. But inserting and aligning comments are not the same in Fortran mode as in other modes.

When a new comment must be inserted, if the current line is blank, a full-line comment is inserted. On a non-blank line, a nonstandard `!' comment is inserted if you have said you want to use them. Otherwise a full-line comment is inserted on a new line before the current line.

Nonstandard `!' comments are aligned like comments in other languages, but full-line comments are different. In a standard full-line comment, the comment delimiter itself must always appear in column zero. What can be aligned is the text within the comment. You can choose from three styles of alignment by setting the variable fortran-comment-indent-style to one of these values:

fixed
Align the text at a fixed column, which is the sum of fortran-comment-line-extra-indent and the minimum statement indentation. This is the default.
The minimum statement indentation is fortran-minimum-statement-indent-fixed for fixed format continuation line style and fortran-minimum-statement-indent-tab for tab format style.

relative
Align the text as if it were a line of code, but with an additional fortran-comment-line-extra-indent columns of indentation.

nil
Don't move text in full-line comments automatically at all.
In addition, you can specify the character to be used to indent within full-line comments by setting the variable fortran-comment-indent-char to the single-character string you want to use.

Fortran mode introduces two variables comment-line-start and comment-line-start-skip, which play for full-line comments the same roles played by comment-start and comment-start-skip for ordinary text-following comments. Normally these are set properly by Fortran mode, so you do not need to change them.

The normal Emacs comment command C-x ; has not been redefined. If you use `!' comments, this command can be used with them. Otherwise it is useless in Fortran mode.

The command C-c ; (fortran-comment-region) turns all the lines of the region into comments by inserting the string `C$$$' at the front of each one. With a numeric argument, it turns the region back into live code by deleting `C$$$' from the front of each line in it. The string used for these comments can be controlled by setting the variable fortran-comment-region. Note that here we have an example of a command and a variable with the same name; these two uses of the name never conflict because in Lisp and in Emacs it is always clear from the context which one is meant.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.4 Fortran Auto Fill Mode

Fortran Auto Fill mode is a minor mode which automatically splits Fortran statements as you insert them when they become too wide. Splitting a statement involves making continuation lines using fortran-continuation-string (see section U.12.2.2 Continuation Lines). This splitting happens when you type SPC, RET, or TAB, and also in the Fortran indentation commands.

M-x fortran-auto-fill-mode turns Fortran Auto Fill mode on if it was off, or off if it was on. This command works the same as M-x auto-fill-mode does for normal Auto Fill mode (see section T.5 Filling Text). A positive numeric argument turns Fortran Auto Fill mode on, and a negative argument turns it off. You can see when Fortran Auto Fill mode is in effect by the presence of the word `Fill' in the mode line, inside the parentheses. Fortran Auto Fill mode is a minor mode, turned on or off for each buffer individually. See section AD.1 Minor Modes.

Fortran Auto Fill mode breaks lines at spaces or delimiters when the lines get longer than the desired width (the value of fill-column). The delimiters that Fortran Auto Fill mode may break at are `,', `'', `+', `-', `/', `*', `=', and `)'. The line break comes after the delimiter if the variable fortran-break-before-delimiters is nil. Otherwise (and by default), the break comes before the delimiter.

By default, Fortran Auto Fill mode is not enabled. If you want this feature turned on permanently, add a hook function to fortran-mode-hook to execute (fortran-auto-fill-mode 1). See section AD.2.3 Hooks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.5 Checking Columns in Fortran

C-c C-r
Display a "column ruler" momentarily above the current line (fortran-column-ruler).
C-c C-w
Split the current window horizontally temporarily so that it is 72 columns wide (fortran-window-create-momentarily). This may help you avoid making lines longer than the 72-character limit that some Fortran compilers impose.
C-u C-c C-w
Split the current window horizontally so that it is 72 columns wide (fortran-window-create). You can then continue editing.
M-x fortran-strip-sequence-nos
Delete all text in column 72 and beyond.
The command C-c C-r (fortran-column-ruler) shows a column ruler momentarily above the current line. The comment ruler is two lines of text that show you the locations of columns with special significance in Fortran programs. Square brackets show the limits of the columns for line numbers, and curly brackets show the limits of the columns for the statement body. Column numbers appear above them.

Note that the column numbers count from zero, as always in GNU Emacs. As a result, the numbers may be one less than those you are familiar with; but the positions they indicate in the line are standard for Fortran.

The text used to display the column ruler depends on the value of the variable indent-tabs-mode. If indent-tabs-mode is nil, then the value of the variable fortran-column-ruler-fixed is used as the column ruler. Otherwise, the variable fortran-column-ruler-tab is displayed. By changing these variables, you can change the column ruler display.

C-c C-w (fortran-window-create-momentarily) temporarily splits the current window horizontally, making a window 72 columns wide, so you can see which lines that is too long. Type a space to restore the normal width.

You can also split the window horizontally and continue editing with the split in place. To do this, use C-u C-c C-w (M-x fortran-window-create). By editing in this window you can immediately see when you make a line too wide to be correct Fortran.

The command M-x fortran-strip-sequence-nos deletes all text in column 72 and beyond, on all lines in the current buffer. This is the easiest way to get rid of old sequence numbers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.12.6 Fortran Keyword Abbrevs

Fortran mode provides many built-in abbrevs for common keywords and declarations. These are the same sort of abbrev that you can define yourself. To use them, you must turn on Abbrev mode. See section X. Abbrevs.

The built-in abbrevs are unusual in one way: they all start with a semicolon. You cannot normally use semicolon in an abbrev, but Fortran mode makes this possible by changing the syntax of semicolon to "word constituent."

For example, one built-in Fortran abbrev is `;c' for `continue'. If you insert `;c' and then insert a punctuation character such as a space or a newline, the `;c' expands automatically to `continue', provided Abbrev mode is enabled.

Type `;?' or `;C-h' to display a list of all the built-in Fortran abbrevs and what they stand for.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

U.13 Asm Mode

Asm mode is a major mode for editing files of assembler code. It defines these commands:

TAB
tab-to-tab-stop.
C-j
Insert a newline and then indent using tab-to-tab-stop.
:
Insert a colon and then remove the indentation from before the label preceding colon. Then do tab-to-tab-stop.
;
Insert or align a comment.
The variable asm-comment-char specifies which character starts comments in assembler syntax.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V. Compiling and Testing Programs

The previous chapter discusses the Emacs commands that are useful for making changes in programs. This chapter deals with commands that assist in the larger process of developing and maintaining programs.

V.1 Running Compilations under Emacs

Compiling programs in languages other than Lisp (C, Pascal, etc.).

V.2 Searching with Grep under Emacs

Running grep as if it were a compiler.

V.3 Compilation Mode

The mode for visiting compiler errors.

V.4 Subshells for Compilation

Customizing your shell properly for use in the compilation buffer.

V.5 Running Debuggers Under Emacs

Running symbolic debuggers for non-Lisp programs.

V.6 Executing Lisp Expressions

Various modes for editing Lisp programs, with different facilities for running the Lisp programs.

V.7 Libraries of Lisp Code for Emacs

Creating Lisp programs to run in Emacs.

V.9 Lisp Interaction Buffers

Executing Lisp in an Emacs buffer.

V.8 Evaluating Emacs-Lisp Expressions

Executing a single Lisp expression in Emacs.

V.10 Running an External Lisp

Communicating through Emacs with a separate Lisp.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.1 Running Compilations under Emacs

Emacs can run compilers for noninteractive languages such as C and Fortran as inferior processes, feeding the error log into an Emacs buffer. It can also parse the error messages and show you the source lines where compilation errors occurred.

M-x compile
Run a compiler asynchronously under Emacs, with error messages going to the `*compilation*' buffer.
M-x recompile
Invoke a compiler with the same command as in the last invocation of M-x compile.
M-x grep
Run grep asynchronously under Emacs, with matching lines listed in the buffer named `*grep*'.
M-x grep-find
Run grep via find, with user-specified arguments, and collect output in the buffer named `*grep*'.
M-x kill-compilation

M-x kill-grep
Kill the running compilation or grep subprocess.
To run make or another compilation command, do M-x compile. This command reads a shell command line using the minibuffer, and then executes the command in an inferior shell, putting output in the buffer named `*compilation*'. The current buffer's default directory is used as the working directory for the execution of the command; normally, therefore, the compilation happens in this directory.

When the shell command line is read, the minibuffer appears containing a default command line, which is the command you used the last time you did M-x compile. If you type just RET, the same command line is used again. For the first M-x compile, the default is `make -k'. The default compilation command comes from the variable compile-command; if the appropriate compilation command for a file is something other than `make -k', it can be useful for the file to specify a local value for compile-command (see section AD.2.5 Local Variables in Files).

Starting a compilation displays the buffer `*compilation*' in another window but does not select it. The buffer's mode line tells you whether compilation is finished, with the word `run' or `exit' inside the parentheses. You do not have to keep this buffer visible; compilation continues in any case. While a compilation is going on, the string `Compiling' appears in the mode lines of all windows. When this string disappears, the compilation is finished.

If you want to watch the compilation transcript as it appears, switch to the `*compilation*' buffer and move point to the end of the buffer. When point is at the end, new compilation output is inserted above point, which remains at the end. If point is not at the end of the buffer, it remains fixed while more compilation output is added at the end of the buffer.

If you set the variable compilation-scroll-output to a non-nil value, then the compilation buffer always scrolls to follow output as it comes in.

To kill the compilation process, do M-x kill-compilation. When the compiler process terminates, the mode line of the `*compilation*' buffer changes to say `signal' instead of `run'. Starting a new compilation also kills any running compilation, as only one can exist at any time. However, M-x compile asks for confirmation before actually killing a compilation that is running.

To rerun the last compilation with the same command, type M-x recompile. This automatically reuses the compilation command from the last invocation of M-x compile.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.2 Searching with Grep under Emacs

Just as you can run a compiler from Emacs and then visit the lines where there were compilation errors, you can also run grep and then visit the lines on which matches were found. This works by treating the matches reported by grep as if they were "errors."

To do this, type M-x grep, then enter a command line that specifies how to run grep. Use the same arguments you would give grep when running it normally: a grep-style regexp (usually in single-quotes to quote the shell's special characters) followed by file names, which may use wildcards. The output from grep goes in the `*grep*' buffer. You can find the corresponding lines in the original files using C-x ` and RET, as with compilation errors.

If you specify a prefix argument for M-x grep, it figures out the tag (see section W.2 Tags Tables) around point, and puts that into the default grep command.

The command M-x grep-find is similar to M-x grep, but it supplies a different initial default for the command--one that runs both find and grep, so as to search every file in a directory tree. See also the find-grep-dired command, in AB.15 Dired and find.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.3 Compilation Mode

The `*compilation*' buffer uses a special major mode, Compilation mode, whose main feature is to provide a convenient way to look at the source line where the error happened.

If you set the variable compilation-scroll-output to a non-nil value, then the compilation buffer always scrolls to follow output as it comes in.

C-x `
Visit the locus of the next compiler error message or grep match.
RET
Visit the locus of the error message that point is on. This command is used in the compilation buffer.
Mouse-2
Visit the locus of the error message that you click on.
You can visit the source for any particular error message by moving point in the `*compilation*' buffer to that error message and typing RET (compile-goto-error). Alternatively, you can click Mouse-2 on the error message; you need not switch to the `*compilation*' buffer first.

To parse the compiler error messages sequentially, type C-x ` (next-error). The character following the C-x is the backquote or "grave accent," not the single-quote. This command is available in all buffers, not just in `*compilation*'; it displays the next error message at the top of one window and source location of the error in another window.

The first time C-x ` is used after the start of a compilation, it moves to the first error's location. Subsequent uses of C-x ` advance down to subsequent errors. If you visit a specific error message with RET or Mouse-2, subsequent C-x ` commands advance from there. When C-x ` gets to the end of the buffer and finds no more error messages to visit, it fails and signals an Emacs error.

C-u C-x ` starts scanning from the beginning of the compilation buffer. This is one way to process the same set of errors again.

To parse messages from the compiler, Compilation mode uses the variable compilation-error-regexp-alist which lists various formats of error messages and tells Emacs how to extract the source file and the line number from the text of a message. If your compiler isn't supported, you can tailor Compilation mode to it by adding elements to that list. A similar variable grep-regexp-alist tells Emacs how to parse output of a grep command.

Compilation mode also redefines the keys SPC and DEL to scroll by screenfuls, and M-n and M-p to move to the next or previous error message. You can also use M-{ and M-} to move up or down to an error message for a different source file.

The features of Compilation mode are also available in a minor mode called Compilation Minor mode. This lets you parse error messages in any buffer, not just a normal compilation output buffer. Type M-x compilation-minor-mode to enable the minor mode. This defines the keys RET and Mouse-2, as in the Compilation major mode.

Compilation minor mode works in any buffer, as long as the contents are in a format that it understands. In an Rlogin buffer (see section AC.15.10 Remote Host Shell), Compilation minor mode automatically accesses remote source files by FTP (see section M.1 File Names).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.4 Subshells for Compilation

Emacs uses a shell to run the compilation command, but specifies the option for a noninteractive shell. This means, in particular, that the shell should start with no prompt. If you find your usual shell prompt making an unsightly appearance in the `*compilation*' buffer, it means you have made a mistake in your shell's init file by setting the prompt unconditionally. (This init file's name may be `.bashrc', `.profile', `.cshrc', `.shrc', or various other things, depending on the shell you use.) The shell init file should set the prompt only if there already is a prompt. In csh, here is how to do it:
if ($?prompt) set prompt = ...
And here's how to do it in bash:
if [ "${PS1+set}" = set ]
then PS1=...
fi
There may well be other things that your shell's init file ought to do only for an interactive shell. You can use the same method to conditionalize them.

The MS-DOS "operating system" does not support asynchronous subprocesses; to work around this lack, M-x compile runs the compilation command synchronously on MS-DOS. As a consequence, you must wait until the command finishes before you can do anything else in Emacs. See section AH. Emacs and MS-DOS.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.5 Running Debuggers Under Emacs

The GUD (Grand Unified Debugger) library provides an interface to various symbolic debuggers from within Emacs. We recommend the debugger GDB, which is free software, but you can also run DBX, SDB or XDB if you have them. GUD can also serve as an interface to the Perl's debugging mode, the Python debugger PDB, and to JDB, the Java Debugger. See section `The Lisp Debugger' in the Emacs Lisp Reference Manual, for information on debugging Emacs Lisp programs.

V.5.1 Starting GUD

How to start a debugger subprocess.

V.5.2 Debugger Operation

Connection between the debugger and source buffers.

V.5.3 Commands of GUD

Key bindings for common commands.

V.5.4 GUD Customization

Defining your own commands for GUD.

V.5.5 GUD Tooltips

Showing variable values by pointing with the mouse.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.5.1 Starting GUD

There are several commands for starting a debugger, each corresponding to a particular debugger program.

M-x gdb RET file RET
Run GDB as a subprocess of Emacs. This command creates a buffer for input and output to GDB, and switches to it. If a GDB buffer already exists, it just switches to that buffer.

M-x dbx RET file RET
Similar, but run DBX instead of GDB.

M-x xdb RET file RET
Similar, but run XDB instead of GDB. Use the variable gud-xdb-directories to specify directories to search for source files.

M-x sdb RET file RET
Similar, but run SDB instead of GDB.
Some versions of SDB do not mention source file names in their messages. When you use them, you need to have a valid tags table (see section W.2 Tags Tables) in order for GUD to find functions in the source code. If you have not visited a tags table or the tags table doesn't list one of the functions, you get a message saying `The sdb support requires a valid tags table to work'. If this happens, generate a valid tags table in the working directory and try again.

M-x perldb RET file RET
Run the Perl interpreter in debug mode to debug file, a Perl program.

M-x jdb RET file RET
Run the Java debugger to debug file.

M-x pdb RET file RET
Run the Python debugger to debug file.
Each of these commands takes one argument: a command line to invoke the debugger. In the simplest case, specify just the name of the executable file you want to debug. You may also use options that the debugger supports. However, shell wildcards and variables are not allowed. GUD assumes that the first argument not starting with a `-' is the executable file name.

Emacs can only run one debugger process at a time.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.5.2 Debugger Operation

When you run a debugger with GUD, the debugger uses an Emacs buffer for its ordinary input and output. This is called the GUD buffer. The debugger displays the source files of the program by visiting them in Emacs buffers. An arrow (`=>') in one of these buffers indicates the current execution line.(12) Moving point in this buffer does not move the arrow.

You can start editing these source files at any time in the buffers that display them. The arrow is not part of the file's text; it appears only on the screen. If you do modify a source file, keep in mind that inserting or deleting lines will throw off the arrow's positioning; GUD has no way of figuring out which line corresponded before your changes to the line number in a debugger message. Also, you'll typically have to recompile and restart the program for your changes to be reflected in the debugger's tables.

If you wish, you can control your debugger process entirely through the debugger buffer, which uses a variant of Shell mode. All the usual commands for your debugger are available, and you can use the Shell mode history commands to repeat them. See section AC.15.3 Shell Mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.5.3 Commands of GUD

The GUD interaction buffer uses a variant of Shell mode, so the commands of Shell mode are available (see section AC.15.3 Shell Mode). GUD mode also provides commands for setting and clearing breakpoints, for selecting stack frames, and for stepping through the program. These commands are available both in the GUD buffer and globally, but with different key bindings.

The breakpoint commands are normally used in source file buffers, because that is the easiest way to specify where to set or clear the breakpoint. Here's the global command to set a breakpoint:

C-x SPC
Set a breakpoint on the source line that point is on.
Here are the other special commands provided by GUD. The keys starting with C-c are available only in the GUD interaction buffer. The key bindings that start with C-x C-a are available in the GUD interaction buffer and also in source files.

C-c C-l

C-x C-a C-l
Display in another window the last line referred to in the GUD buffer (that is, the line indicated in the last location message). This runs the command gud-refresh.

C-c C-s

C-x C-a C-s
Execute a single line of code (gud-step). If the line contains a function call, execution stops after entering the called function.

C-c C-n

C-x C-a C-n
Execute a single line of code, stepping across entire function calls at full speed (gud-next).

C-c C-i

C-x C-a C-i
Execute a single machine instruction (gud-stepi).

C-c C-r

C-x C-a C-r
Continue execution without specifying any stopping point. The program will run until it hits a breakpoint, terminates, or gets a signal that the debugger is checking for (gud-cont).

C-c C-d

C-x C-a C-d
Delete the breakpoint(s) on the current source line, if any (gud-remove). If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped.

C-c C-t

C-x C-a C-t
Set a temporary breakpoint on the current source line, if any. If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped.
The above commands are common to all supported debuggers. If you are using GDB or (some versions of) DBX, these additional commands are available:

C-c <

C-x C-a <
Select the next enclosing stack frame (gud-up). This is equivalent to the `up' command.

C-c >

C-x C-a >
Select the next inner stack frame (gud-down). This is equivalent to the `down' command.
If you are using GDB, these additional key bindings are available:

TAB
With GDB, complete a symbol name (gud-gdb-complete-command). This key is available only in the GUD interaction buffer, and requires GDB versions 4.13 and later.

C-c C-f

C-x C-a C-f
Run the program until the selected stack frame returns (or until it stops for some other reason).
These commands interpret a numeric argument as a repeat count, when that makes sense.

Because TAB serves as a completion command, you can't use it to enter a tab as input to the program you are debugging with GDB. Instead, type C-q TAB to enter a tab.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.5.4 GUD Customization

On startup, GUD runs one of the following hooks: gdb-mode-hook, if you are using GDB; dbx-mode-hook, if you are using DBX; sdb-mode-hook, if you are using SDB; xdb-mode-hook, if you are using XDB; perldb-mode-hook, for Perl debugging mode; pdb-mode-hook, for PDB; jdb-mode-hook, for JDB. You can use these hooks to define custom key bindings for the debugger interaction buffer. See section AD.2.3 Hooks.

Here is a convenient way to define a command that sends a particular command string to the debugger, and set up a key binding for it in the debugger interaction buffer:
(gud-def function cmdstring binding docstring)
This defines a command named function which sends cmdstring to the debugger process, and gives it the documentation string docstring. You can then use the command function in any buffer. If binding is non-nil, gud-def also binds the command to C-c binding in the GUD buffer's mode and to C-x C-a binding generally.

The command string cmdstring may contain certain `%'-sequences that stand for data to be filled in at the time function is called:

`%f'
The name of the current source file. If the current buffer is the GUD buffer, then the "current source file" is the file that the program stopped in.

`%l'
The number of the current source line. If the current buffer is the GUD buffer, then the "current source line" is the line that the program stopped in.

`%e'
The text of the C lvalue or function-call expression at or adjacent to point.

`%a'
The text of the hexadecimal address at or adjacent to point.

`%p'
The numeric argument of the called function, as a decimal number. If the command is used without a numeric argument, `%p' stands for the empty string.
If you don't use `%p' in the command string, the command you define ignores any numeric argument.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.5.5 GUD Tooltips

The Tooltip facility (see section P.18 Tooltips (or "Balloon Help")) provides support for GUD. If GUD support is activated by customizing the tooltip group, variable values can be displayed in tooltips by pointing at them with the mouse in the GUD buffer or in source buffers with major modes in the customizable list tooltip-gud-modes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.6 Executing Lisp Expressions

Emacs has several different major modes for Lisp and Scheme. They are the same in terms of editing commands, but differ in the commands for executing Lisp expressions. Each mode has its own purpose.

Emacs-Lisp mode
The mode for editing source files of programs to run in Emacs Lisp. This mode defines C-M-x to evaluate the current defun. See section V.7 Libraries of Lisp Code for Emacs.
Lisp Interaction mode
The mode for an interactive session with Emacs Lisp. It defines C-j to evaluate the sexp before point and insert its value in the buffer. See section V.9 Lisp Interaction Buffers.
Lisp mode
The mode for editing source files of programs that run in Lisps other than Emacs Lisp. This mode defines C-M-x to send the current defun to an inferior Lisp process. See section V.10 Running an External Lisp.
Inferior Lisp mode
The mode for an interactive session with an inferior Lisp process. This mode combines the special features of Lisp mode and Shell mode (see section AC.15.3 Shell Mode).
Scheme mode
Like Lisp mode but for Scheme programs.
Inferior Scheme mode
The mode for an interactive session with an inferior Scheme process.
Most editing commands for working with Lisp programs are in fact available globally. See section U. Editing Programs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.7 Libraries of Lisp Code for Emacs

Lisp code for Emacs editing commands is stored in files whose names conventionally end in `.el'. This ending tells Emacs to edit them in Emacs-Lisp mode (see section V.6 Executing Lisp Expressions).

To execute a file of Emacs Lisp code, use M-x load-file. This command reads a file name using the minibuffer and then executes the contents of that file as Lisp code. It is not necessary to visit the file first; in any case, this command reads the file as found on disk, not text in an Emacs buffer.

Once a file of Lisp code is installed in the Emacs Lisp library directories, users can load it using M-x load-library. Programs can load it by calling load-library, or with load, a more primitive function that is similar but accepts some additional arguments.

M-x load-library differs from M-x load-file in that it searches a sequence of directories and tries three file names in each directory. Suppose your argument is lib; the three names are `lib.elc', `lib.el', and lastly just `lib'. If `lib.elc' exists, it is by convention the result of compiling `lib.el'; it is better to load the compiled file, since it will load and run faster.

If load-library finds that `lib.el' is newer than `lib.elc' file, it issues a warning, because it's likely that somebody made changes to the `.el' file and forgot to recompile it.

Because the argument to load-library is usually not in itself a valid file name, file name completion is not available. Indeed, when using this command, you usually do not know exactly what file name will be used.

The sequence of directories searched by M-x load-library is specified by the variable load-path, a list of strings that are directory names. The default value of the list contains the directory where the Lisp code for Emacs itself is stored. If you have libraries of your own, put them in a single directory and add that directory to load-path. nil in this list stands for the current default directory, but it is probably not a good idea to put nil in the list. If you find yourself wishing that nil were in the list, most likely what you really want to do is use M-x load-file this once.

Often you do not have to give any command to load a library, because the commands defined in the library are set up to autoload that library. Trying to run any of those commands calls load to load the library; this replaces the autoload definitions with the real ones from the library.

Emacs Lisp code can be compiled into byte-code which loads faster, takes up less space when loaded, and executes faster. See section `Byte Compilation' in the Emacs Lisp Reference Manual. By convention, the compiled code for a library goes in a separate file whose name consists of the library source file with `c' appended. Thus, the compiled code for `foo.el' goes in `foo.elc'. That's why load-library searches for `.elc' files first.

By default, Emacs refuses to load compiled Lisp files which were compiled with XEmacs, a modified versions of Emacs--they can cause Emacs to crash. Set the variable load-dangerous-libraries to t if you want to try loading them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.8 Evaluating Emacs-Lisp Expressions

Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp mode; this happens automatically for file names ending in `.el'. By contrast, Lisp mode itself is used for editing Lisp programs intended for other Lisp systems. To switch to Emacs-Lisp mode explicitly, use the command M-x emacs-lisp-mode.

For testing of Lisp programs to run in Emacs, it is often useful to evaluate part of the program as it is found in the Emacs buffer. For example, after changing the text of a Lisp function definition, evaluating the definition installs the change for future calls to the function. Evaluation of Lisp expressions is also useful in any kind of editing, for invoking noninteractive functions (functions that are not commands).

M-:
Read a single Lisp expression in the minibuffer, evaluate it, and print the value in the echo area (eval-expression).
C-x C-e
Evaluate the Lisp expression before point, and print the value in the echo area (eval-last-sexp).
C-M-x
Evaluate the defun containing or after point, and print the value in the echo area (eval-defun).
M-x eval-region
Evaluate all the Lisp expressions in the region.
M-x eval-current-buffer
Evaluate all the Lisp expressions in the buffer.
M-: (eval-expression) is the most basic command for evaluating a Lisp expression interactively. It reads the expression using the minibuffer, so you can execute any expression on a buffer regardless of what the buffer contains. When the expression is evaluated, the current buffer is once again the buffer that was current when M-: was typed.

In Emacs-Lisp mode, the key C-M-x is bound to the command eval-defun, which parses the defun containing or following point as a Lisp expression and evaluates it. The value is printed in the echo area. This command is convenient for installing in the Lisp environment changes that you have just made in the text of a function definition.

C-M-x treats defvar expressions specially. Normally, evaluating a defvar expression does nothing if the variable it defines already has a value. But C-M-x unconditionally resets the variable to the initial value specified in the defvar expression. defcustom expressions are treated similarly. This special feature is convenient for debugging Lisp programs.

The command C-x C-e (eval-last-sexp) evaluates the Lisp expression preceding point in the buffer, and displays the value in the echo area. It is available in all major modes, not just Emacs-Lisp mode. It does not treat defvar specially.

If C-M-x, C-x C-e, or M-: is given a numeric argument, it inserts the value into the current buffer at point, rather than displaying it in the echo area. The argument's value does not matter.

The most general command for evaluating Lisp expressions from a buffer is eval-region. M-x eval-region parses the text of the region as one or more Lisp expressions, evaluating them one by one. M-x eval-current-buffer is similar but evaluates the entire buffer. This is a reasonable way to install the contents of a file of Lisp code that you are ready to test. Later, as you find bugs and change individual functions, use C-M-x on each function that you change. This keeps the Lisp world in step with the source file.

The customizable variables eval-expression-print-level and eval-expression-print-length control the maximum depth and length of lists to print in the result of the evaluation commands before abbreviating them. eval-expression-debug-on-error controls whether evaluation errors invoke the debugger when these commands are used.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.9 Lisp Interaction Buffers

The buffer `*scratch*' which is selected when Emacs starts up is provided for evaluating Lisp expressions interactively inside Emacs.

The simplest way to use the `*scratch*' buffer is to insert Lisp expressions and type C-j after each expression. This command reads the Lisp expression before point, evaluates it, and inserts the value in printed representation before point. The result is a complete typescript of the expressions you have evaluated and their values.

The `*scratch*' buffer's major mode is Lisp Interaction mode, which is the same as Emacs-Lisp mode except for the binding of C-j.

The rationale for this feature is that Emacs must have a buffer when it starts up, but that buffer is not useful for editing files since a new buffer is made for every file that you visit. The Lisp interpreter typescript is the most useful thing I can think of for the initial buffer to do. Type M-x lisp-interaction-mode to put the current buffer in Lisp Interaction mode.

An alternative way of evaluating Emacs Lisp expressions interactively is to use Inferior Emacs-Lisp mode, which provides an interface rather like Shell mode (see section AC.15.3 Shell Mode) for evaluating Emacs Lisp expressions. Type M-x ielm to create an `*ielm*' buffer which uses this mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

V.10 Running an External Lisp

Emacs has facilities for running programs in other Lisp systems. You can run a Lisp process as an inferior of Emacs, and pass expressions to it to be evaluated. You can also pass changed function definitions directly from the Emacs buffers in which you edit the Lisp programs to the inferior Lisp process.

To run an inferior Lisp process, type M-x run-lisp. This runs the program named lisp, the same program you would run by typing lisp as a shell command, with both input and output going through an Emacs buffer named `*lisp*'. That is to say, any "terminal output" from Lisp will go into the buffer, advancing point, and any "terminal input" for Lisp comes from text in the buffer. (You can change the name of the Lisp executable file by setting the variable inferior-lisp-program.)

To give input to Lisp, go to the end of the buffer and type the input, terminated by RET. The `*lisp*' buffer is in Inferior Lisp mode, which combines the special characteristics of Lisp mode with most of the features of Shell mode (see section AC.15.3 Shell Mode). The definition of RET to send a line to a subprocess is one of the features of Shell mode.

For the source files of programs to run in external Lisps, use Lisp mode. This mode can be selected with M-x lisp-mode, and is used automatically for files whose names end in `.l', `.lsp', or `.lisp', as most Lisp systems usually expect.

When you edit a function in a Lisp program you are running, the easiest way to send the changed definition to the inferior Lisp process is the key C-M-x. In Lisp mode, this runs the function lisp-eval-defun, which finds the defun around or following point and sends it as input to the Lisp process. (Emacs can send input to any inferior process regardless of what buffer is current.)

Contrast the meanings of C-M-x in Lisp mode (for editing programs to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp programs to be run in Emacs): in both modes it has the effect of installing the function definition that point is in, but the way of doing so is different according to where the relevant Lisp environment is found. See section V.6 Executing Lisp Expressions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W. Maintaining Programs

This chapter describes Emacs features for maintaining programs. The version control features (see section M.7 Version Control) are also particularly useful for this purpose.

W.1 Change Logs

Maintaining a change history for your program.

W.2 Tags Tables

Go direct to any function in your program in one command. Tags remembers which file it is in.

W.3 Merging Files with Emerge

A convenient way of merging two versions of a program.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.1 Change Logs

The Emacs command C-x 4 a adds a new entry to the change log file for the file you are editing (add-change-log-entry-other-window). If that file is actually a backup file, it makes an entry appropriate for the file's parent--that is useful for making log entries for functions that have been deleted in the current version.

A change log file contains a chronological record of when and why you have changed a program, consisting of a sequence of entries describing individual changes. Normally it is kept in a file called `ChangeLog' in the same directory as the file you are editing, or one of its parent directories. A single `ChangeLog' file can record changes for all the files in its directory and all its subdirectories.

You should put a copyright notice and permission notice at the end of the change log file. Here is an example:
Copyright 1997, 1998 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification, are
permitted provided the copyright notice and this notice are preserved.
Of course, you should substitute the proper years and copyright holder.

A change log entry starts with a header line that contains the current date, your name, and your email address (taken from the variable user-mail-address). Aside from these header lines, every line in the change log starts with a space or a tab. The bulk of the entry consists of items, each of which starts with a line starting with whitespace and a star. Here are two entries, both dated in May 1993, each with two items:
1993-05-25  Richard Stallman  <rms@gnu.org>

        * man.el: Rename symbols `man-*' to `Man-*'.
        (manual-entry): Make prompt string clearer.

        * simple.el (blink-matching-paren-distance):
        Change default to 12,000.

1993-05-24  Richard Stallman  <rms@gnu.org>

        * vc.el (minor-mode-map-alist): Don't use it if it's void.
        (vc-cancel-version): Doc fix.
One entry can describe several changes; each change should have its own item. Normally there should be a blank line between items. When items are related (parts of the same change, in different places), group them by leaving no blank line between them. The second entry above contains two items grouped in this way.

C-x 4 a visits the change log file and creates a new entry unless the most recent entry is for today's date and your name. It also creates a new item for the current file. For many languages, it can even guess the name of the function or other object that was changed.

When the option add-log-keep-changes-together is non-nil, C-x 4 a adds to any existing entry for the file rather than starting a new entry.

If the value of the variable change-log-version-info-enabled is non-nil, C-x 4 a adds the file's version number to the change log entry. It finds the version number by searching the first ten percent of the file, using regular expressions from the variable change-log-version-number-regexp-list.

The change log file is visited in Change Log mode. In this major mode, each bunch of grouped items counts as one paragraph, and each entry is considered a page. This facilitates editing the entries. C-j and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry.

You can use the command M-x change-log-merge to merge other log files into a buffer in Change Log Mode, preserving the date ordering of entries.

Versions of Emacs before 20.1 used a different format for the time of the change log entry:
Fri May 25 11:23:23 1993 Richard Stallman  <rms@gnu.org>
The M-x change-log-redate command converts all the old-style date entries in the change log file visited in the current buffer to the new format, to make the file uniform in style. This is handy when entries are contributed by many different people, some of whom use old versions of Emacs.

Version control systems are another way to keep track of changes in your program and keep a change log. See section M.7.3.4 Features of the Log Entry Buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.2 Tags Tables

A tags table is a description of how a multi-file program is broken up into files. It lists the names of the component files and the names and positions of the functions (or other named subunits) in each file. Grouping the related files makes it possible to search or replace through all the files with one command. Recording the function names and positions makes possible the M-. command which finds the definition of a function by looking up which of the files it is in.

Tags tables are stored in files called tags table files. The conventional name for a tags table file is `TAGS'.

Each entry in the tags table records the name of one tag, the name of the file that the tag is defined in (implicitly), and the position in that file of the tag's definition.

Just what names from the described files are recorded in the tags table depends on the programming language of the described file. They normally include all file names, functions and subroutines, and may also include global variables, data types, and anything else convenient. Each name recorded is called a tag.

See also the Ebrowse facility, which is tailored for C++. See section `Ebrowse' in Ebrowse User's Manual.

W.2.1 Source File Tag Syntax

Tag syntax for various types of code and text files.

W.2.2 Creating Tags Tables

Creating a tags table with etags.

W.2.3 Etags Regexps

Create arbitrary tags using regular expressions.

W.2.4 Selecting a Tags Table

How to visit a tags table.

W.2.5 Finding a Tag

Commands to find the definition of a specific tag.

W.2.6 Searching and Replacing with Tags Tables

Using a tags table for searching and replacing.

W.2.7 Tags Table Inquiries

Listing and finding tags defined in a file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.2.1 Source File Tag Syntax

Here is how tag syntax is defined for the most popular languages:

In C code, any C function or typedef is a tag, and so are definitions of struct, union and enum. #define macro definitions and enum constants are also tags, unless you specify `--no-defines' when making the tags table. Similarly, global variables are tags, unless you specify `--no-globals'. Use of `--no-globals' and `--no-defines' can make the tags table file much smaller.
You can tag function declarations and external variables in addition to function definitions by giving the `--declarations' option to etags.

In C++ code, in addition to all the tag constructs of C code, member functions are also recognized, and optionally member variables if you use the `--members' option. Tags for variables and functions in classes are named `class::variable' and `class::function'. operator definitions have tag names like `operator+'.

In Java code, tags include all the constructs recognized in C++, plus the interface, extends and implements constructs. Tags for variables and functions in classes are named `class.variable' and `class.function'.

In LaTeX text, the argument of any of the commands \chapter, \section, \subsection, \subsubsection, \eqno, \label, \ref, \cite, \bibitem, \part, \appendix, \entry, or \index, is a tag.
Other commands can make tags as well, if you specify them in the environment variable TEXTAGS before invoking etags. The value of this environment variable should be a colon-separated list of command names. For example,
TEXTAGS="def:newcommand:newenvironment"
export TEXTAGS
specifies (using Bourne shell syntax) that the commands `\def', `\newcommand' and `\newenvironment' also define tags.

In Lisp code, any function defined with defun, any variable defined with defvar or defconst, and in general the first argument of any expression that starts with `(def' in column zero, is a tag.

In Scheme code, tags include anything defined with def or with a construct whose name starts with `def'. They also include variables set with set! at top level in the file.

Several other languages are also supported:

In Ada code, functions, procedures, packages, tasks, and types are tags. Use the `--packages-only' option to create tags for packages only.
In Ada, the same name can be used for different kinds of entity (e.g., for a procedure and for a function). Also, for things like packages, procedures and functions, there is the spec (i.e. the interface) and the body (i.e. the implementation). To make it easier to pick the definition you want, Ada tag name have suffixes indicating the type of entity:

`/b'
package body.
`/f'
function.
`/k'
task.
`/p'
procedure.
`/s'
package spec.
`/t'
type.
Thus, M-x find-tag RET bidule/b RET will go directly to the body of the package bidule, while M-x find-tag RET bidule RET will just search for any tag bidule.

In assembler code, labels appearing at the beginning of a line, followed by a colon, are tags.

In Bison or Yacc input files, each rule defines as a tag the nonterminal it constructs. The portions of the file that contain C code are parsed as C code.

In Cobol code, tags are paragraph names; that is, any word starting in column 8 and followed by a period.

In Erlang code, the tags are the functions, records, and macros defined in the file.

In Fortran code, functions, subroutines and block data are tags.

In makefiles, targets are tags.

In Objective C code, tags include Objective C definitions for classes, class categories, methods, and protocols.

In Pascal code, the tags are the functions and procedures defined in the file.

In Perl code, the tags are the procedures defined by the sub, my and local keywords. Use `--globals' if you want to tag global variables.

In PostScript code, the tags are the functions.

In Prolog code, a tag name appears at the left margin.

In Python code, def or class at the beginning of a line generate a tag.

You can also generate tags based on regexp matching (see section W.2.3 Etags Regexps) to handle other formats and languages.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.2.2 Creating Tags Tables

The etags program is used to create a tags table file. It knows the syntax of several languages, as described in W.2.1 Source File Tag Syntax. Here is how to run etags:
etags inputfiles...
The etags program reads the specified files, and writes a tags table named `TAGS' in the current working directory.

If the specified files don't exist, etags looks for compressed versions of them and uncompresses them to read them. Under MS-DOS, etags also looks for file names like `mycode.cgz' if it is given `mycode.c' on the command line and `mycode.c' does not exist.

etags recognizes the language used in an input file based on its file name and contents. You can specify the language with the `--language=name' option, described below.

If the tags table data become outdated due to changes in the files described in the table, the way to update the tags table is the same way it was made in the first place. If the tags table fails to record a tag, or records it for the wrong file, then Emacs cannot possibly find its definition until you update the tags table. However, if the position recorded in the tags table becomes a little bit wrong (due to other editing), the only consequence is a slight delay in finding the tag. Even if the stored position is very far wrong, Emacs will still find the tag, after searching most of the file for it. Even that delay is hardly noticeable with today's computers.

So you should update a tags table when you define new tags that you want to have listed, or when you move tag definitions from one file to another, or when changes become substantial. Normally there is no need to update the tags table after each edit, or even every day.

One tags table can virtually include another. Specify the included tags file name with the `--include=file' option when creating the file that is to include it. The latter file then acts as if it covered all the source files specified in the included file, as well as the files it directly contains.

If you specify the source files with relative file names when you run etags, the tags file will contain file names relative to the directory where the tags file was initially written. This way, you can move an entire directory tree containing both the tags file and the source files, and the tags file will still refer correctly to the source files.

If you specify absolute file names as arguments to etags, then the tags file will contain absolute file names. This way, the tags file will still refer to the same files even if you move it, as long as the source files remain in the same place. Absolute file names start with `/', or with `device:/' on MS-DOS and MS-Windows.

When you want to make a tags table from a great number of files, you may have problems listing them on the command line, because some systems have a limit on its length. The simplest way to circumvent this limit is to tell etags to read the file names from its standard input, by typing a dash in place of the file names, like this:
find . -name "*.[chCH]" -print | etags -
Use the option `--language=name' to specify the language explicitly. You can intermix these options with file names; each one applies to the file names that follow it. Specify `--language=auto' to tell etags to resume guessing the language from the file names and file contents. Specify `--language=none' to turn off language-specific processing entirely; then etags recognizes tags by regexp matching alone (see section W.2.3 Etags Regexps).

`etags --help' prints the list of the languages etags knows, and the file name rules for guessing the language. It also prints a list of all the available etags options, together with a short explanation.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.2.3 Etags Regexps

The `--regex' option provides a general way of recognizing tags based on regexp matching. You can freely intermix it with file names. Each `--regex' option adds to the preceding ones, and applies only to the following files. The syntax is:
--regex=/tagregexp[/nameregexp]/
where tagregexp is used to match the lines to tag. It is always anchored, that is, it behaves as if preceded by `^'. If you want to account for indentation, just match any initial number of blanks by beginning your regular expression with `[ \t]*'. In the regular expressions, `\' quotes the next character, and `\t' stands for the tab character. Note that etags does not handle the other C escape sequences for special characters.

The syntax of regular expressions in etags is the same as in Emacs, augmented with the interval operator, which works as in grep and ed. The syntax of an interval operator is `\{m,n\}', and its meaning is to match the preceding expression at least m times and up to n times.

You should not match more characters with tagregexp than that needed to recognize what you want to tag. If the match is such that more characters than needed are unavoidably matched by tagregexp (as will usually be the case), you should add a nameregexp, to pick out just the tag. This will enable Emacs to find tags more accurately and to do completion on tag names more reliably. You can find some examples below.

The option `--ignore-case-regex' (or `-c') works like `--regex', except that matching ignores case. This is appropriate for certain programming languages.

The `-R' option deletes all the regexps defined with `--regex' options. It applies to the file names following it, as you can see from the following example:
etags --regex=/reg1/ voo.doo --regex=/reg2/ \
    bar.ber -R --lang=lisp los.er
Here etags chooses the parsing language for `voo.doo' and `bar.ber' according to their contents. etags also uses reg1 to recognize additional tags in `voo.doo', and both reg1 and reg2 to recognize additional tags in `bar.ber'. etags uses the Lisp tags rules, and no regexp matching, to recognize tags in `los.er'.

You can specify a regular expression for a particular language, by writing `{lang}' in front of it. Then etags will use the regular expression only for files of that language. (`etags --help' prints the list of languages recognized by etags.) The following example tags the DEFVAR macros in the Emacs source files, for the C language only:
--regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
This feature is particularly useful when you store a list of regular expressions in a file. The following option syntax instructs etags to read two files of regular expressions. The regular expressions contained in the second file are matched without regard to case.
--regex=@first-file --ignore-case-regex=@second-file
A regex file contains one regular expressions per line. Empty lines, and lines beginning with space or tab are ignored. When the first character in a line is `@', etags assumes that the rest of the line is the name of a file of regular expressions; thus, one such file can include another file. All the other lines are taken to be regular expressions. If the first non-whitespace text on the line is `--', that line is a comment.

For example, one can create a file called `emacs.tags' with the following contents:
        -- This is for GNU Emacs C source files
{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
and then use it like this:
etags --regex=@emacs.tags *.[ch] */*.[ch]
Here are some more examples. The regexps are quoted to protect them from shell interpretation.

Tag Octave files:
etags --language=none \
      --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
      --regex='/###key \(.*\)/\1/' \
      --regex='/[ \t]*global[ \t].*/' \
      *.m
Note that tags are not generated for scripts, so that you have to add a line by yourself of the form `###key scriptname' if you want to jump to it.

Tag Tcl files:
etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
Tag VHDL files:
etags --language=none \
  --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
  --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
  \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.2.4 Selecting a Tags Table

Emacs has at any time one selected tags table, and all the commands for working with tags tables use the selected one. To select a tags table, type M-x visit-tags-table, which reads the tags table file name as an argument. The name `TAGS' in the default directory is used as the default file name.

All this command does is store the file name in the variable tags-file-name. Emacs does not actually read in the tags table contents until you try to use them. Setting this variable yourself is just as good as using visit-tags-table. The variable's initial value is nil; that value tells all the commands for working with tags tables that they must ask for a tags table file name to use.

Using visit-tags-table when a tags table is already loaded gives you a choice: you can add the new tags table to the current list of tags tables, or start a new list. The tags commands use all the tags tables in the current list. If you start a new list, the new tags table is used instead of others. If you add the new table to the current list, it is used as well as the others. When the tags commands scan the list of tags tables, they don't always start at the beginning of the list; they start with the first tags table (if any) that describes the current file, proceed from there to the end of the list, and then scan from the beginning of the list until they have covered all the tables in the list.

You can specify a precise list of tags tables by setting the variable tags-table-list to a list of strings, like this:
(setq tags-table-list
      '("~/emacs" "/usr/local/lib/emacs/src"))
This tells the tags commands to look at the `TAGS' files in your `~/emacs' directory and in the `/usr/local/lib/emacs/src' directory. The order depends on which file you are in and which tags table mentions that file, as explained above.

Do not set both tags-file-name and tags-table-list.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.2.5 Finding a Tag

The most important thing that a tags table enables you to do is to find the definition of a specific tag.

M-. tag RET
Find first definition of tag (find-tag).
C-u M-.
Find next alternate definition of last tag specified.
C-u - M-.
Go back to previous tag found.
C-M-. pattern RET
Find a tag whose name matches pattern (find-tag-regexp).
C-u C-M-.
Find the next tag whose name matches the last pattern used.
C-x 4 . tag RET
Find first definition of tag, but display it in another window (find-tag-other-window).
C-x 5 . tag RET
Find first definition of tag, and create a new frame to select the buffer (find-tag-other-frame).
M-*
Pop back to where you previously invoked M-. and friends.
M-. (find-tag) is the command to find the definition of a specified tag. It searches through the tags table for that tag, as a string, and then uses the tags table info to determine the file that the definition is in and the approximate character position in the file of the definition. Then find-tag visits that file, moves point to the approximate character position, and searches ever-increasing distances away to find the tag definition.

If an empty argument is given (just type RET), the balanced expression in the buffer before or around point is used as the tag argument. See section U.4.1 Expressions with Balanced Parentheses.

You don't need to give M-. the full name of the tag; a part will do. This is because M-. finds tags in the table which contain tag as a substring. However, it prefers an exact match to a substring match. To find other tags that match the same substring, give find-tag a numeric argument, as in C-u M-.; this does not read a tag name, but continues searching the tags table's text for another tag containing the same substring last used. If you have a real META key, M-0 M-. is an easier alternative to C-u M-..

Like most commands that can switch buffers, find-tag has a variant that displays the new buffer in another window, and one that makes a new frame for it. The former is C-x 4 ., which invokes the command find-tag-other-window. The latter is C-x 5 ., which invokes find-tag-other-frame.

To move back to places you've found tags recently, use C-u - M-.; more generally, M-. with a negative numeric argument. This command can take you to another buffer. C-x 4 . with a negative argument finds the previous tag location in another window.

As well as going back to places you've found tags recently, you can go back to places from where you found them. Use M-*, which invokes the command pop-tag-mark, for this. Typically you would find and study the definition of something with M-. and then return to where you were with M-*.

Both C-u - M-. and M-* allow you to retrace your steps to a depth determined by the variable find-tag-marker-ring-length.

The command C-M-. (find-tag-regexp) visits the tags that match a specified regular expression. It is just like M-. except that it does regexp matching instead of substring matching.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.2.6 Searching and Replacing with Tags Tables

The commands in this section visit and search all the files listed in the selected tags table, one by one. For these commands, the tags table serves only to specify a sequence of files to search.

M-x tags-search RET regexp RET
Search for regexp through the files in the selected tags table.
M-x tags-query-replace RET regexp RET replacement RET
Perform a query-replace-regexp on each file in the selected tags table.
M-,
Restart one of the commands above, from the current location of point (tags-loop-continue).
M-x tags-search reads a regexp using the minibuffer, then searches for matches in all the files in the selected tags table, one file at a time. It displays the name of the file being searched so you can follow its progress. As soon as it finds an occurrence, tags-search returns.

Having found one match, you probably want to find all the rest. To find one more match, type M-, (tags-loop-continue) to resume the tags-search. This searches the rest of the current buffer, followed by the remaining files of the tags table.

M-x tags-query-replace performs a single query-replace-regexp through all the files in the tags table. It reads a regexp to search for and a string to replace with, just like ordinary M-x query-replace-regexp. It searches much like M-x tags-search, but repeatedly, processing matches according to your input. See section K.7 Replacement Commands, for more information on query replace.

You can control the case-sensitivity of tags search commands by customizing the value of the variable tags-case-fold-search. The default is to use the same setting as the value of case-fold-search (see section K.6 Searching and Case).

It is possible to get through all the files in the tags table with a single invocation of M-x tags-query-replace. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query replace subsequently by typing M-,; this command resumes the last tags search or replace command that you did.

The commands in this section carry out much broader searches than the find-tag family. The find-tag commands search only for definitions of tags that match your substring or regexp. The commands tags-search and tags-query-replace find every occurrence of the regexp, as ordinary search commands and replace commands do in the current buffer.

These commands create buffers only temporarily for the files that they have to search (those which are not already visited in Emacs buffers). Buffers in which no match is found are quickly killed; the others continue to exist.

It may have struck you that tags-search is a lot like grep. You can also run grep itself as an inferior of Emacs and have Emacs show you the matching lines one by one. This works much like running a compilation; finding the source locations of the grep matches works like finding the compilation errors. See section V.1 Running Compilations under Emacs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.2.7 Tags Table Inquiries

M-x list-tags RET file RET
Display a list of the tags defined in the program file file.
M-x tags-apropos RET regexp RET
Display a list of all tags matching regexp.
M-x list-tags reads the name of one of the files described by the selected tags table, and displays a list of all the tags defined in that file. The "file name" argument is really just a string to compare against the file names recorded in the tags table; it is read as a string rather than as a file name. Therefore, completion and defaulting are not available, and you must enter the file name the same way it appears in the tags table. Do not include a directory as part of the file name unless the file name recorded in the tags table includes a directory.

M-x tags-apropos is like apropos for tags (see section G.4 Apropos). It finds all the tags in the selected tags table whose entries match regexp, and displays them. If the variable tags-apropos-verbose is non-nil, it displays the names of the tags files together with the tag names.

You can customize the appearance of the output with the face tags-tag-face. You can display additional output with M-x tags-apropos by customizing the variable tags-apropos-additional-actions---see its documentation for details.

You can also use the collection of tag names to complete a symbol name in the buffer. See section U.8 Completion for Symbol Names.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.3 Merging Files with Emerge

It's not unusual for programmers to get their signals crossed and modify the same program in two different directions. To recover from this confusion, you need to merge the two versions. Emerge makes this easier. See also M.9 Comparing Files, for commands to compare in a more manual fashion, and section `Top' in The Ediff Manual.

W.3.1 Overview of Emerge

How to start Emerge. Basic concepts.

W.3.2 Submodes of Emerge

Fast mode vs. Edit mode. Skip Prefers mode and Auto Advance mode.

W.3.3 State of a Difference

You do the merge by specifying state A or B for each difference.

W.3.4 Merge Commands

Commands for selecting a difference, changing states of differences, etc.

W.3.5 Exiting Emerge

What to do when you've finished the merge.

W.3.6 Combining the Two Versions

How to keep both alternatives for a difference.

W.3.7 Fine Points of Emerge

Misc.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.3.1 Overview of Emerge

To start Emerge, run one of these four commands:

M-x emerge-files
Merge two specified files.

M-x emerge-files-with-ancestor
Merge two specified files, with reference to a common ancestor.

M-x emerge-buffers
Merge two buffers.

M-x emerge-buffers-with-ancestor
Merge two buffers with reference to a common ancestor in a third buffer.
The Emerge commands compare two files or buffers, and display the comparison in three buffers: one for each input text (the A buffer and the B buffer), and one (the merge buffer) where merging takes place. The merge buffer shows the full merged text, not just the differences. Wherever the two input texts differ, you can choose which one of them to include in the merge buffer.

The Emerge commands that take input from existing buffers use only the accessible portions of those buffers, if they are narrowed (see section AC.22 Narrowing).

If a common ancestor version is available, from which the two texts to be merged were both derived, Emerge can use it to guess which alternative is right. Wherever one current version agrees with the ancestor, Emerge presumes that the other current version is a deliberate change which should be kept in the merged version. Use the `with-ancestor' commands if you want to specify a common ancestor text. These commands read three file or buffer names--variant A, variant B, and the common ancestor.

After the comparison is done and the buffers are prepared, the interactive merging starts. You control the merging by typing special merge commands in the merge buffer. The merge buffer shows you a full merged text, not just differences. For each run of differences between the input texts, you can choose which one of them to keep, or edit them both together.

The merge buffer uses a special major mode, Emerge mode, with commands for making these choices. But you can also edit the buffer with ordinary Emacs commands.

At any given time, the attention of Emerge is focused on one particular difference, called the selected difference. This difference is marked off in the three buffers like this:
vvvvvvvvvvvvvvvvvvvv
text that differs
^^^^^^^^^^^^^^^^^^^^
Emerge numbers all the differences sequentially and the mode line always shows the number of the selected difference.

Normally, the merge buffer starts out with the A version of the text. But when the A version of a difference agrees with the common ancestor, then the B version is initially preferred for that difference.

Emerge leaves the merged text in the merge buffer when you exit. At that point, you can save it in a file with C-x C-w. If you give a numeric argument to emerge-files or emerge-files-with-ancestor, it reads the name of the output file using the minibuffer. (This is the last file name those commands read.) Then exiting from Emerge saves the merged text in the output file.

Normally, Emerge commands save the output buffer in its file when you exit. If you abort Emerge with C-], the Emerge command does not save the output buffer, but you can save it yourself if you wish.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.3.2 Submodes of Emerge

You can choose between two modes for giving merge commands: Fast mode and Edit mode. In Fast mode, basic merge commands are single characters, but ordinary Emacs commands are disabled. This is convenient if you use only merge commands. In Edit mode, all merge commands start with the prefix key C-c C-c, and the normal Emacs commands are also available. This allows editing the merge buffer, but slows down Emerge operations.

Use e to switch to Edit mode, and C-c C-c f to switch to Fast mode. The mode line indicates Edit and Fast modes with `E' and `F'.

Emerge has two additional submodes that affect how particular merge commands work: Auto Advance mode and Skip Prefers mode.

If Auto Advance mode is in effect, the a and b commands advance to the next difference. This lets you go through the merge faster as long as you simply choose one of the alternatives from the input. The mode line indicates Auto Advance mode with `A'.

If Skip Prefers mode is in effect, the n and p commands skip over differences in states prefer-A and prefer-B (see section W.3.3 State of a Difference). Thus you see only differences for which neither version is presumed "correct." The mode line indicates Skip Prefers mode with `S'.

Use the command s a (emerge-auto-advance-mode) to set or clear Auto Advance mode. Use s s (emerge-skip-prefers-mode) to set or clear Skip Prefers mode. These commands turn on the mode with a positive argument, turns it off with a negative or zero argument, and toggle the mode with no argument.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.3.3 State of a Difference

In the merge buffer, a difference is marked with lines of `v' and `^' characters. Each difference has one of these seven states:

A
The difference is showing the A version. The a command always produces this state; the mode line indicates it with `A'.

B
The difference is showing the B version. The b command always produces this state; the mode line indicates it with `B'.

default-A

default-B
The difference is showing the A or the B state by default, because you haven't made a choice. All differences start in the default-A state (and thus the merge buffer is a copy of the A buffer), except those for which one alternative is "preferred" (see below).
When you select a difference, its state changes from default-A or default-B to plain A or B. Thus, the selected difference never has state default-A or default-B, and these states are never displayed in the mode line.

The command d a chooses default-A as the default state, and d b chooses default-B. This chosen default applies to all differences which you haven't ever selected and for which no alternative is preferred. If you are moving through the merge sequentially, the differences you haven't selected are those following the selected one. Thus, while moving sequentially, you can effectively make the A version the default for some sections of the merge buffer and the B version the default for others by using d a and d b between sections.

prefer-A

prefer-B
The difference is showing the A or B state because it is preferred. This means that you haven't made an explicit choice, but one alternative seems likely to be right because the other alternative agrees with the common ancestor. Thus, where the A buffer agrees with the common ancestor, the B version is preferred, because chances are it is the one that was actually changed.
These two states are displayed in the mode line as `A*' and `B*'.

combined
The difference is showing a combination of the A and B states, as a result of the x c or x C commands.
Once a difference is in this state, the a and b commands don't do anything to it unless you give them a numeric argument.

The mode line displays this state as `comb'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.3.4 Merge Commands

Here are the Merge commands for Fast mode; in Edit mode, precede them with C-c C-c:

p
Select the previous difference.

n
Select the next difference.

a
Choose the A version of this difference.

b
Choose the B version of this difference.

C-u n j
Select difference number n.

.
Select the difference containing point. You can use this command in the merge buffer or in the A or B buffer.

q
Quit--finish the merge.

C-]
Abort--exit merging and do not save the output.

f
Go into Fast mode. (In Edit mode, this is actually C-c C-c f.)

e
Go into Edit mode.

l
Recenter (like C-l) all three windows.

-
Specify part of a prefix numeric argument.

digit
Also specify part of a prefix numeric argument.

d a
Choose the A version as the default from here down in the merge buffer.

d b
Choose the B version as the default from here down in the merge buffer.

c a
Copy the A version of this difference into the kill ring.

c b
Copy the B version of this difference into the kill ring.

i a
Insert the A version of this difference at point.

i b
Insert the B version of this difference at point.

m
Put point and mark around the difference.

^
Scroll all three windows down (like M-v).

v
Scroll all three windows up (like C-v).

<
Scroll all three windows left (like C-x <).

>
Scroll all three windows right (like C-x >).

|
Reset horizontal scroll on all three windows.

x 1
Shrink the merge window to one line. (Use C-u l to restore it to full size.)

x c
Combine the two versions of this difference (see section W.3.6 Combining the Two Versions).

x f
Show the names of the files/buffers Emerge is operating on, in a Help window. (Use C-u l to restore windows.)

x j
Join this difference with the following one. (C-u x j joins this difference with the previous one.)

x s
Split this difference into two differences. Before you use this command, position point in each of the three buffers at the place where you want to split the difference.

x t
Trim identical lines off the top and bottom of the difference. Such lines occur when the A and B versions are identical but differ from the ancestor version.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.3.5 Exiting Emerge

The q command (emerge-quit) finishes the merge, storing the results into the output file if you specified one. It restores the A and B buffers to their proper contents, or kills them if they were created by Emerge and you haven't changed them. It also disables the Emerge commands in the merge buffer, since executing them later could damage the contents of the various buffers.

C-] aborts the merge. This means exiting without writing the output file. If you didn't specify an output file, then there is no real difference between aborting and finishing the merge.

If the Emerge command was called from another Lisp program, then its return value is t for successful completion, or nil if you abort.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.3.6 Combining the Two Versions

Sometimes you want to keep both alternatives for a particular difference. To do this, use x c, which edits the merge buffer like this:
#ifdef NEW
version from A buffer
#else /* not NEW */
version from B buffer
#endif /* not NEW */
While this example shows C preprocessor conditionals delimiting the two alternative versions, you can specify the strings to use by setting the variable emerge-combine-versions-template to a string of your choice. In the string, `%a' says where to put version A, and `%b' says where to put version B. The default setting, which produces the results shown above, looks like this:
"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

W.3.7 Fine Points of Emerge

During the merge, you mustn't try to edit the A and B buffers yourself. Emerge modifies them temporarily, but ultimately puts them back the way they were.

You can have any number of merges going at once--just don't use any one buffer as input to more than one merge at once, since the temporary changes made in these buffers would get in each other's way.

Starting Emerge can take a long time because it needs to compare the files fully. Emacs can't do anything else until diff finishes. Perhaps in the future someone will change Emerge to do the comparison in the background when the input files are large--then you could keep on doing other things with Emacs until Emerge is ready to accept commands.

After setting up the merge, Emerge runs the hook emerge-startup-hook (see section AD.2.3 Hooks).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

X. Abbrevs

A defined abbrev is a word which expands, if you insert it, into some different text. Abbrevs are defined by the user to expand in specific ways. For example, you might define `foo' as an abbrev expanding to `find outer otter'. Then you would be able to insert `find outer otter ' into the buffer by typing f o o SPC.

A second kind of abbreviation facility is called dynamic abbrev expansion. You use dynamic abbrev expansion with an explicit command to expand the letters in the buffer before point by looking for other words in the buffer that start with those letters. See section X.6 Dynamic Abbrev Expansion.

"Hippie" expansion generalizes abbreviation expansion. See section `Hippie Expansion' in Features for Automatic Typing.

X.1 Abbrev Concepts

Fundamentals of defined abbrevs.

X.2 Defining Abbrevs

Defining an abbrev, so it will expand when typed.

X.3 Controlling Abbrev Expansion

Controlling expansion: prefixes, canceling expansion.

X.4 Examining and Editing Abbrevs

Viewing or editing the entire list of defined abbrevs.

X.5 Saving Abbrevs

Saving the entire list of abbrevs for another session.

X.6 Dynamic Abbrev Expansion

Abbreviations for words already in the buffer.

X.7 Customizing Dynamic Abbreviation

What is a word, for dynamic abbrevs. Case handling.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

X.1 Abbrev Concepts

An abbrev is a word which has been defined to expand into a specified expansion. When you insert a word-separator character following the abbrev, that expands the abbrev--replacing the abbrev with its expansion. For example, if `foo' is defined as an abbrev expanding to `find outer otter', then you can insert `find outer otter.' into the buffer by typing f o o ..

Abbrevs expand only when Abbrev mode (a minor mode) is enabled. Disabling Abbrev mode does not cause abbrev definitions to be forgotten, but they do not expand until Abbrev mode is enabled again. The command M-x abbrev-mode toggles Abbrev mode; with a numeric argument, it turns Abbrev mode on if the argument is positive, off otherwise. See section AD.1 Minor Modes. abbrev-mode is also a variable; Abbrev mode is on when the variable is non-nil. The variable abbrev-mode automatically becomes local to the current buffer when it is set.

Abbrev definitions can be mode-specific---active only in one major mode. Abbrevs can also have global definitions that are active in all major modes. The same abbrev can have a global definition and various mode-specific definitions for different major modes. A mode-specific definition for the current major mode overrides a global definition.

Abbrevs can be defined interactively during the editing session. Lists of abbrev definitions can also be saved in files and reloaded in later sessions. Some users keep extensive lists of abbrevs that they load in every session.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

X.2 Defining Abbrevs

C-x a g
Define an abbrev, using one or more words before point as its expansion (add-global-abbrev).
C-x a l
Similar, but define an abbrev specific to the current major mode (add-mode-abbrev).
C-x a i g
Define a word in the buffer as an abbrev (inverse-add-global-abbrev).
C-x a i l
Define a word in the buffer as a mode-specific abbrev (inverse-add-mode-abbrev).
M-x kill-all-abbrevs
This command discards all abbrev definitions currently in effect, leaving a blank slate.
The usual way to define an abbrev is to enter the text you want the abbrev to expand to, position point after it, and type C-x a g (add-global-abbrev). This reads the abbrev itself using the minibuffer, and then defines it as an abbrev for one or more words before point. Use a numeric argument to say how many words before point should be taken as the expansion. For example, to define the abbrev `foo' as mentioned above, insert the text `find outer otter' and then type C-u 3 C-x a g f o o RET.

An argument of zero to C-x a g means to use the contents of the region as the expansion of the abbrev being defined.

The command C-x a l (add-mode-abbrev) is similar, but defines a mode-specific abbrev. Mode-specific abbrevs are active only in a particular major mode. C-x a l defines an abbrev for the major mode in effect at the time C-x a l is typed. The arguments work the same as for C-x a g.

If the text already in the buffer is the abbrev, rather than its expansion, use command C-x a i g (inverse-add-global-abbrev) instead of C-x a g, or use C-x a i l (inverse-add-mode-abbrev) instead of C-x a l. These commands are called "inverse" because they invert the meaning of the two text strings they use (one from the buffer and one read with the minibuffer).

To change the definition of an abbrev, just define a new definition. When the abbrev has a prior definition, the abbrev definition commands ask for confirmation before replacing it.

To remove an abbrev definition, give a negative argument to the abbrev definition command: C-u - C-x a g or C-u - C-x a l. The former removes a global definition, while the latter removes a mode-specific definition.

M-x kill-all-abbrevs removes all the abbrev definitions there are, both global and local.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

X.3 Controlling Abbrev Expansion

An abbrev expands whenever it is present in the buffer just before point and you type a self-inserting whitespace or punctuation character (SPC, comma, etc.). More precisely, any character that is not a word constituent expands an abbrev, and any word-constituent character can be part of an abbrev. The most common way to use an abbrev is to insert it and then insert a punctuation character to expand it.

Abbrev expansion preserves case; thus, `foo' expands into `find outer otter'; `Foo' into `Find outer otter', and `FOO' into `FIND OUTER OTTER' or `Find Outer Otter' according to the variable abbrev-all-caps (a non-nil value chooses the first of the two expansions).

These commands are used to control abbrev expansion:

M-'
Separate a prefix from a following abbrev to be expanded (abbrev-prefix-mark).
C-x a e
Expand the abbrev before point (expand-abbrev). This is effective even when Abbrev mode is not enabled.
M-x expand-region-abbrevs
Expand some or all abbrevs found in the region.
You may wish to expand an abbrev with a prefix attached; for example, if `cnst' expands into `construction', you might want to use it to enter `reconstruction'. It does not work to type recnst, because that is not necessarily a defined abbrev. What you can do is use the command M-' (abbrev-prefix-mark) in between the prefix `re' and the abbrev `cnst'. First, insert `re'. Then type M-'; this inserts a hyphen in the buffer to indicate that it has done its work. Then insert the abbrev `cnst'; the buffer now contains `re-cnst'. Now insert a non-word character to expand the abbrev `cnst' into `construction'. This expansion step also deletes the hyphen that indicated M-' had been used. The result is the desired `reconstruction'.

If you actually want the text of the abbrev in the buffer, rather than its expansion, you can accomplish this by inserting the following punctuation with C-q. Thus, foo C-q , leaves `foo,' in the buffer.

If you expand an abbrev by mistake, you can undo the expansion and bring back the abbrev itself by typing C-_ to undo (see section D.4 Undoing Changes). This also undoes the insertion of the non-word character that expanded the abbrev. If the result you want is the terminating non-word character plus the unexpanded abbrev, you must reinsert the terminating character, quoting it with C-q. You can also use the command M-x unexpand-abbrev to cancel the last expansion without deleting the terminating character.

M-x expand-region-abbrevs searches through the region for defined abbrevs, and for each one found offers to replace it with its expansion. This command is useful if you have typed in text using abbrevs but forgot to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. This command is effective even if Abbrev mode is not enabled.

Expanding an abbrev runs the hook pre-abbrev-expand-hook (see section AD.2.3 Hooks).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

X.4 Examining and Editing Abbrevs

M-x list-abbrevs
Display a list of all abbrev definitions. With a numeric argument, list only local abbrevs.
M-x edit-abbrevs
Edit a list of abbrevs; you can add, alter or remove definitions.
The output from M-x list-abbrevs looks like this:
(lisp-mode-abbrev-table)
"dk"	       0    "define-key"
(global-abbrev-table)
"dfn"	       0    "definition"
(Some blank lines of no semantic significance, and some other abbrev tables, have been omitted.)

A line containing a name in parentheses is the header for abbrevs in a particular abbrev table; global-abbrev-table contains all the global abbrevs, and the other abbrev tables that are named after major modes contain the mode-specific abbrevs.

Within each abbrev table, each nonblank line defines one abbrev. The word at the beginning of the line is the abbrev. The number that follows is the number of times the abbrev has been expanded. Emacs keeps track of this to help you see which abbrevs you actually use, so that you can eliminate those that you don't use often. The string at the end of the line is the expansion.

M-x edit-abbrevs allows you to add, change or kill abbrev definitions by editing a list of them in an Emacs buffer. The list has the same format described above. The buffer of abbrevs is called `*Abbrevs*', and is in Edit-Abbrevs mode. Type C-c C-c in this buffer to install the abbrev definitions as specified in the buffer--and delete any abbrev definitions not listed.

The command edit-abbrevs is actually the same as list-abbrevs except that it selects the buffer `*Abbrevs*' whereas list-abbrevs merely displays it in another window.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

X.5 Saving Abbrevs

These commands allow you to keep abbrev definitions between editing sessions.

M-x write-abbrev-file RET file RET
Write a file file describing all defined abbrevs.
M-x read-abbrev-file RET file RET
Read the file file and define abbrevs as specified therein.
M-x quietly-read-abbrev-file RET file RET
Similar but do not display a message about what is going on.
M-x define-abbrevs
Define abbrevs from definitions in current buffer.
M-x insert-abbrevs
Insert all abbrevs and their expansions into current buffer.
M-x write-abbrev-file reads a file name using the minibuffer and then writes a description of all current abbrev definitions into that file. This is used to save abbrev definitions for use in a later session. The text stored in the file is a series of Lisp expressions that, when executed, define the same abbrevs that you currently have.

M-x read-abbrev-file reads a file name using the minibuffer and then reads the file, defining abbrevs according to the contents of the file. M-x quietly-read-abbrev-file is the same except that it does not display a message in the echo area saying that it is doing its work; it is actually useful primarily in the `.emacs' file. If an empty argument is given to either of these functions, they use the file name specified in the variable abbrev-file-name, which is by default "~/.abbrev_defs".

Emacs will offer to save abbrevs automatically if you have changed any of them, whenever it offers to save all files (for C-x s or C-x C-c). This feature can be inhibited by setting the variable save-abbrevs to nil.

The commands M-x insert-abbrevs and M-x define-abbrevs are similar to the previous commands but work on text in an Emacs buffer. M-x insert-abbrevs inserts text into the current buffer before point, describing all current abbrev definitions; M-x define-abbrevs parses the entire current buffer and defines abbrevs accordingly.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

X.6 Dynamic Abbrev Expansion

The abbrev facility described above operates automatically as you insert text, but all abbrevs must be defined explicitly. By contrast, dynamic abbrevs allow the meanings of abbrevs to be determined automatically from the contents of the buffer, but dynamic abbrev expansion happens only when you request it explicitly.

M-/
Expand the word in the buffer before point as a dynamic abbrev, by searching in the buffer for words starting with that abbreviation (dabbrev-expand).

C-M-/
Complete the word before point as a dynamic abbrev (dabbrev-completion).
For example, if the buffer contains `does this follow ' and you type f o M-/, the effect is to insert `follow' because that is the last word in the buffer that starts with `fo'. A numeric argument to M-/ says to take the second, third, etc. distinct expansion found looking backward from point. Repeating M-/ searches for an alternative expansion by looking farther back. After scanning all the text before point, it searches the text after point. The variable dabbrev-limit, if non-nil, specifies how far in the buffer to search for an expansion.

After scanning the current buffer, M-/ normally searches other buffers, unless you have set dabbrev-check-all-buffers to nil.

For finer control over which buffers to scan, customize the variable dabbrev-ignored-buffer-regexps. Its value is a list of regular expressions. If a buffer's name matches any of these regular expressions, dynamic abbrev expansion skips that buffer.

A negative argument to M-/, as in C-u - M-/, says to search first for expansions after point, and second for expansions before point. If you repeat the M-/ to look for another expansion, do not specify an argument. This tries all the expansions after point and then the expansions before point.

After you have expanded a dynamic abbrev, you can copy additional words that follow the expansion in its original context. Simply type SPC M-/ for each word you want to copy. The spacing and punctuation between words is copied along with the words.

The command C-M-/ (dabbrev-completion) performs completion of a dynamic abbreviation. Instead of trying the possible expansions one by one, it finds all of them, then inserts the text that they have in common. If they have nothing in common, C-M-/ displays a list of completions, from which you can select a choice in the usual manner. See section E.3 Completion.

Dynamic abbrev expansion is completely independent of Abbrev mode; the expansion of a word with M-/ is completely independent of whether it has a definition as an ordinary abbrev.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

X.7 Customizing Dynamic Abbreviation

Normally, dynamic abbrev expansion ignores case when searching for expansions. That is, the expansion need not agree in case with the word you are expanding.

This feature is controlled by the variable dabbrev-case-fold-search. If it is t, case is ignored in this search; if it is nil, the word and the expansion must match in case. If the value of dabbrev-case-fold-search is case-fold-search, which is true by default, then the variable case-fold-search controls whether to ignore case while searching for expansions.

Normally, dynamic abbrev expansion preserves the case pattern of the abbrev you have typed, by converting the expansion to that case pattern.

The variable dabbrev-case-replace controls whether to preserve the case pattern of the abbrev. If it is t, the abbrev's case pattern is preserved in most cases; if it is nil, the expansion is always copied verbatim. If the value of dabbrev-case-replace is case-replace, which is true by default, then the variable case-replace controls whether to copy the expansion verbatim.

However, if the expansion contains a complex mixed case pattern, and the abbrev matches this pattern as far as it goes, then the expansion is always copied verbatim, regardless of those variables. Thus, for example, if the buffer contains variableWithSillyCasePattern, and you type v a M-/, it copies the expansion verbatim including its case pattern.

The variable dabbrev-abbrev-char-regexp, if non-nil, controls which characters are considered part of a word, for dynamic expansion purposes. The regular expression must match just one character, never two or more. The same regular expression also determines which characters are part of an expansion. The value nil has a special meaning: abbreviations are made of word characters, but expansions are made of word and symbol characters.

In shell scripts and makefiles, a variable name is sometimes prefixed with `$' and sometimes not. Major modes for this kind of text can customize dynamic abbreviation to handle optional prefixes by setting the variable dabbrev-abbrev-skip-leading-regexp. Its value should be a regular expression that matches the optional prefix that dynamic abbreviation should ignore.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Y. Editing Pictures

To edit a picture made out of text characters (for example, a picture of the division of a register into fields, as a comment in a program), use the command M-x edit-picture to enter Picture mode.

In Picture mode, editing is based on the quarter-plane model of text, according to which the text characters lie studded on an area that stretches infinitely far to the right and downward. The concept of the end of a line does not exist in this model; the most you can say is where the last nonblank character on the line is found.

Of course, Emacs really always considers text as a sequence of characters, and lines really do have ends. But Picture mode replaces the most frequently-used commands with variants that simulate the quarter-plane model of text. They do this by inserting spaces or by converting tabs to spaces.

Most of the basic editing commands of Emacs are redefined by Picture mode to do essentially the same thing but in a quarter-plane way. In addition, Picture mode defines various keys starting with the C-c prefix to run special picture editing commands.

One of these keys, C-c C-c, is pretty important. Often a picture is part of a larger file that is usually edited in some other major mode. M-x edit-picture records the name of the previous major mode so you can use the C-c C-c command (picture-mode-exit) later to go back to that mode. C-c C-c also deletes spaces from the ends of lines, unless given a numeric argument.

The special commands of Picture mode all work in other modes (provided the `picture' library is loaded), but are not bound to keys except in Picture mode. The descriptions below talk of moving "one column" and so on, but all the picture mode commands handle numeric arguments as their normal equivalents do.

Turning on Picture mode runs the hook picture-mode-hook (see section AD.2.3 Hooks).

Y.1 Basic Editing in Picture Mode

Basic concepts and simple commands of Picture Mode.

Y.2 Controlling Motion after Insert

Controlling direction of cursor motion after "self-inserting" characters.

Y.3 Picture Mode Tabs

Various features for tab stops and indentation.

Y.4 Picture Mode Rectangle Commands

Clearing and superimposing rectangles.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Y.1 Basic Editing in Picture Mode

Most keys do the same thing in Picture mode that they usually do, but do it in a quarter-plane style. For example, C-f is rebound to run picture-forward-column, a command which moves point one column to the right, inserting a space if necessary so that the actual end of the line makes no difference. C-b is rebound to run picture-backward-column, which always moves point left one column, converting a tab to multiple spaces if necessary. C-n and C-p are rebound to run picture-move-down and picture-move-up, which can either insert spaces or convert tabs as necessary to make sure that point stays in exactly the same column. C-e runs picture-end-of-line, which moves to after the last nonblank character on the line. There is no need to change C-a, as the choice of screen model does not affect beginnings of lines.

Insertion of text is adapted to the quarter-plane screen model through the use of Overwrite mode (see section AD.1 Minor Modes). Self-inserting characters replace existing text, column by column, rather than pushing existing text to the right. RET runs picture-newline, which just moves to the beginning of the following line so that new text will replace that line.

Picture mode provides erasure instead of deletion and killing of text. DEL (picture-backward-clear-column) replaces the preceding character with a space rather than removing it; this moves point backwards. C-d (picture-clear-column) replaces the next character or characters with spaces, but does not move point. (If you want to clear characters to spaces and move forward over them, use SPC.) C-k (picture-clear-line) really kills the contents of lines, but does not delete the newlines from the buffer.

To do actual insertion, you must use special commands. C-o (picture-open-line) creates a blank line after the current line; it never splits a line. C-M-o (split-line) makes sense in Picture mode, so it is not changed. C-j (picture-duplicate-line) inserts below the current line another line with the same contents.

To do actual deletion in Picture mode, use C-w, C-c C-d (which is defined as delete-char, as C-d is in other modes), or one of the picture rectangle commands (see section Y.4 Picture Mode Rectangle Commands).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Y.2 Controlling Motion after Insert

Since "self-inserting" characters in Picture mode overwrite and move point, there is no essential restriction on how point should be moved. Normally point moves right, but you can specify any of the eight orthogonal or diagonal directions for motion after a "self-inserting" character. This is useful for drawing lines in the buffer.

C-c <
Move left after insertion (picture-movement-left).
C-c >
Move right after insertion (picture-movement-right).
C-c ^
Move up after insertion (picture-movement-up).
C-c .
Move down after insertion (picture-movement-down).
C-c `
Move up and left ("northwest") after insertion (picture-movement-nw).
C-c '
Move up and right ("northeast") after insertion (picture-movement-ne).
C-c /
Move down and left ("southwest") after insertion
(picture-movement-sw).
C-c \
Move down and right ("southeast") after insertion
(picture-movement-se).
Two motion commands move based on the current Picture insertion direction. The command C-c C-f (picture-motion) moves in the same direction as motion after "insertion" currently does, while C-c C-b (picture-motion-reverse) moves in the opposite direction.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Y.3 Picture Mode Tabs

Two kinds of tab-like action are provided in Picture mode. Use M-TAB (picture-tab-search) for context-based tabbing. With no argument, it moves to a point underneath the next "interesting" character that follows whitespace in the previous nonblank line. "Next" here means "appearing at a horizontal position greater than the one point starts out at." With an argument, as in C-u M-TAB, this command moves to the next such interesting character in the current line. M-TAB does not change the text; it only moves point. "Interesting" characters are defined by the variable picture-tab-chars, which should define a set of characters. The syntax for this variable is like the syntax used inside of `[...]' in a regular expression--but without the `[' and the `]'. Its default value is "!-~".

TAB itself runs picture-tab, which operates based on the current tab stop settings; it is the Picture mode equivalent of tab-to-tab-stop. Normally it just moves point, but with a numeric argument it clears the text that it moves over.

The context-based and tab-stop-based forms of tabbing are brought together by the command C-c TAB (picture-set-tab-stops). This command sets the tab stops to the positions which M-TAB would consider significant in the current line. The use of this command, together with TAB, can get the effect of context-based tabbing. But M-TAB is more convenient in the cases where it is sufficient.

It may be convenient to prevent use of actual tab characters in pictures. For example, this prevents C-x TAB from messing up the picture. You can do this by setting the variable indent-tabs-mode to nil. See section S.3 Tabs vs. Spaces.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Y.4 Picture Mode Rectangle Commands

Picture mode defines commands for working on rectangular pieces of the text in ways that fit with the quarter-plane model. The standard rectangle commands may also be useful (see section H.10 Rectangles).

C-c C-k
Clear out the region-rectangle with spaces (picture-clear-rectangle). With argument, delete the text.
C-c C-w r
Similar, but save rectangle contents in register r first (picture-clear-rectangle-to-register).
C-c C-y
Copy last killed rectangle into the buffer by overwriting, with upper left corner at point (picture-yank-rectangle). With argument, insert instead.
C-c C-x r
Similar, but use the rectangle in register r (picture-yank-rectangle-from-register).
The picture rectangle commands C-c C-k (picture-clear-rectangle) and C-c C-w (picture-clear-rectangle-to-register) differ from the standard rectangle commands in that they normally clear the rectangle instead of deleting it; this is analogous with the way C-d is changed in Picture mode.

However, deletion of rectangles can be useful in Picture mode, so these commands delete the rectangle if given a numeric argument. C-c C-k either with or without a numeric argument saves the rectangle for C-c C-y.

The Picture mode commands for yanking rectangles differ from the standard ones in that they overwrite instead of inserting. This is the same way that Picture mode insertion of other text differs from other modes. C-c C-y (picture-yank-rectangle) inserts (by overwriting) the rectangle that was most recently killed, while C-c C-x (picture-yank-rectangle-from-register) does likewise for the rectangle found in a specified register.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z. Sending Mail

To send a message in Emacs, you start by typing a command (C-x m) to select and initialize the `*mail*' buffer. Then you edit the text and headers of the message in this buffer, and type another command (C-c C-s or C-c C-c) to send the message.

C-x m
Begin composing a message to send (compose-mail).
C-x 4 m
Likewise, but display the message in another window (compose-mail-other-window).
C-x 5 m
Likewise, but make a new frame (compose-mail-other-frame).
C-c C-s
In Mail mode, send the message (mail-send).
C-c C-c
Send the message and bury the mail buffer (mail-send-and-exit).
The command C-x m (compose-mail) selects a buffer named `*mail*' and initializes it with the skeleton of an outgoing message. C-x 4 m (compose-mail-other-window) selects the `*mail*' buffer in a different window, leaving the previous current buffer visible. C-x 5 m (compose-mail-other-frame) creates a new frame to select the `*mail*' buffer.

Because the mail-composition buffer is an ordinary Emacs buffer, you can switch to other buffers while in the middle of composing mail, and switch back later (or never). If you use the C-x m command again when you have been composing another message but have not sent it, you are asked to confirm before the old message is erased. If you answer n, the `*mail*' buffer is left selected with its old contents, so you can finish the old message and send it. C-u C-x m is another way to do this. Sending the message marks the `*mail*' buffer "unmodified," which avoids the need for confirmation when C-x m is next used.

If you are composing a message in the `*mail*' buffer and want to send another message before finishing the first, rename the `*mail*' buffer using M-x rename-uniquely (see section N.3 Miscellaneous Buffer Operations). Then you can use C-x m or its variants described above to make a new `*mail*' buffer. Once you've done that, you can work with each mail buffer independently.

Z.1 The Format of the Mail Buffer

Format of the mail being composed.

Z.2 Mail Header Fields

Details of permitted mail header fields.

Z.3 Mail Aliases

Abbreviating and grouping mail addresses.

Z.4 Mail Mode

Special commands for editing mail being composed.

Z.5 Mail Amusements

Distracting the NSA; adding fortune messages.

Z.6 Mail-Composition Methods

Using alternative mail-composition methods.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.1 The Format of the Mail Buffer

In addition to the text or body, a message has header fields which say who sent it, when, to whom, why, and so on. Some header fields, such as `Date' and `Sender', are created automatically when you send the message. Others, such as the recipient names, must be specified by you in order to send the message properly.

Mail mode provides a few commands to help you edit some header fields, and some are preinitialized in the buffer automatically at times. You can insert and edit header fields using ordinary editing commands.

The line in the buffer that says
--text follows this line--
is a special delimiter that separates the headers you have specified from the text. Whatever follows this line is the text of the message; the headers precede it. The delimiter line itself does not appear in the message actually sent. The text used for the delimiter line is controlled by the variable mail-header-separator.

Here is an example of what the headers and text in the mail buffer might look like.
To: gnu@gnu.org
CC: lungfish@spam.org, byob@spam.org
Subject: The Emacs Manual
--Text follows this line--
Please ignore this message.
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.2 Mail Header Fields

A header field in the mail buffer starts with a field name at the beginning of a line, terminated by a colon. Upper and lower case are equivalent in field names (and in mailing addresses also). After the colon and optional whitespace comes the contents of the field.

You can use any name you like for a header field, but normally people use only standard field names with accepted meanings. Here is a table of fields commonly used in outgoing messages.

`To'
This field contains the mailing addresses to which the message is addressed. If you list more than one address, use commas, not spaces, to separate them.

`Subject'
The contents of the `Subject' field should be a piece of text that says what the message is about. The reason `Subject' fields are useful is that most mail-reading programs can provide a summary of messages, listing the subject of each message but not its text.

`CC'
This field contains additional mailing addresses to send the message to, like `To' except that these readers should not regard the message as directed at them.

`BCC'
This field contains additional mailing addresses to send the message to, which should not appear in the header of the message actually sent. Copies sent this way are called blind carbon copies.
To send a blind carbon copy of every outgoing message to yourself, set the variable mail-self-blind to t. To send a blind carbon copy of every message to some other address, set the variable mail-default-headers to "Bcc: address\n".

`FCC'
This field contains the name of one file and directs Emacs to append a copy of the message to that file when you send the message. If the file is in Rmail format, Emacs writes the message in Rmail format; otherwise, Emacs writes the message in system mail file format. To specify more than one file, use several `FCC' fields, with one file name in each field.
To put a fixed file name in the `FCC' field each time you start editing an outgoing message, set the variable mail-archive-file-name to that file name. Unless you remove the `FCC' field before sending, the message will be written into that file when it is sent.

`From'
Use the `From' field to say who you are, when the account you are using to send the mail is not your own. The contents of the `From' field should be a valid mailing address, since replies will normally go there. If you don't specify the `From' field yourself, Emacs uses the value of user-mail-address as the default.

`Reply-to'
Use this field to direct replies to a different address. Most mail-reading programs (including Rmail) automatically send replies to the `Reply-to' address in preference to the `From' address. By adding a `Reply-to' field to your header, you can work around any problems your `From' address may cause for replies.
To put a fixed `Reply-to' address into every outgoing message, set the variable mail-default-reply-to to that address (as a string). Then mail initializes the message with a `Reply-to' field as specified. You can delete or alter that header field before you send the message, if you wish. When Emacs starts up, if the environment variable REPLYTO is set, mail-default-reply-to is initialized from that environment variable.

`In-reply-to'
This field contains a piece of text describing the message you are replying to. Some mail systems can use this information to correlate related pieces of mail. Normally this field is filled in by Rmail when you reply to a message in Rmail, and you never need to think about it (see section AA. Reading Mail with Rmail).

`References'
This field lists the message IDs of related previous messages. Rmail sets up this field automatically when you reply to a message.
The `To', `CC', and `BCC' header fields can appear any number of times, and each such header field can contain multiple addresses, separated by commas. This way, you can specify any number of places to send the message. These fields can also have continuation lines: one or more lines starting with whitespace, following the starting line of the field, are considered part of the field. Here's an example of a `To' field with a continuation line:
To: foo@here.net, this@there.net,
  me@gnu.cambridge.mass.usa.earth.spiral3281
When you send the message, if you didn't write a `From' field yourself, Emacs puts in one for you. The variable mail-from-style controls the format:

nil
Use just the email address, as in `king@grassland.com'.
parens
Use both email address and full name, as in `king@grassland.com (Elvis Parsley)'.
angles
Use both email address and full name, as in `Elvis Parsley <king@grassland.com>'.
system-default
Allow the system to insert the `From' field.
You can direct Emacs to insert certain default headers into the outgoing message by setting the variable mail-default-headers to a string. Then C-x m inserts this string into the message headers. If the default header fields are not appropriate for a particular message, edit them as appropriate before sending the message.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.3 Mail Aliases

You can define mail aliases in a file named `~/.mailrc'. These are short mnemonic names which stand for mail addresses or groups of mail addresses. Like many other mail programs, Emacs expands aliases when they occur in the `To', `From', `CC', `BCC', and `Reply-to' fields, plus their `Resent-' variants.

To define an alias in `~/.mailrc', write a line in the following format:
alias shortaddress fulladdresses
Here fulladdresses stands for one or more mail addresses for shortaddress to expand into. Separate multiple addresses with spaces; if an address contains a space, quote the whole address with a pair of double-quotes.

For instance, to make maingnu stand for gnu@gnu.org plus a local address of your own, put in this line:
alias maingnu gnu@gnu.org local-gnu
Emacs also recognizes include commands in `.mailrc' files. They look like this:
source filename
The file `~/.mailrc' is used primarily by other mail-reading programs; it can contain various other commands. Emacs ignores everything in it except for alias definitions and include commands.

Another way to define a mail alias, within Emacs alone, is with the define-mail-alias command. It prompts for the alias and then the full address. You can use it to define aliases in your `.emacs' file, like this:
(define-mail-alias "maingnu" "gnu@gnu.org")
define-mail-alias records aliases by adding them to a variable named mail-aliases. If you are comfortable with manipulating Lisp lists, you can set mail-aliases directly. The initial value of mail-aliases is t, which means that Emacs should read `.mailrc' to get the proper value.

You can specify a different file name to use instead of `~/.mailrc' by setting the variable mail-personal-alias-file.

Normally, Emacs expands aliases when you send the message. You do not need to expand mail aliases before sending the message, but you can expand them if you want to see where the mail will actually go. To do this, use the command M-x expand-mail-aliases; it expands all mail aliases currently present in the mail headers that hold addresses.

If you like, you can have mail aliases expand as abbrevs, as soon as you type them in (see section X. Abbrevs). To enable this feature, execute the following:
(add-hook 'mail-mode-hook 'mail-abbrevs-setup)
This can go in your `.emacs' file. See section AD.2.3 Hooks. If you use this feature, you must use define-mail-abbrev instead of define-mail-alias; the latter does not work with this package. Note that the mail abbreviation package uses the variable mail-abbrevs instead of mail-aliases, and that all alias names are converted to lower case.

The mail abbreviation package also provides the C-c C-a (mail-interactive-insert-alias) command, which reads an alias name (with completion) and inserts its definition at point. This is useful when editing the message text itself or a header field such as `Subject' in which Emacs does not normally expand aliases.

Note that abbrevs expand only if you insert a word-separator character afterward. However, you can rebind C-n and M-> to cause expansion as well. Here's how to do that:
(add-hook 'mail-mode-hook
          (lambda ()
            (substitute-key-definition
              'next-line 'mail-abbrev-next-line
              mail-mode-map global-map)
            (substitute-key-definition
              'end-of-buffer 'mail-abbrev-end-of-buffer
              mail-mode-map global-map)))
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.4 Mail Mode

The major mode used in the mail buffer is Mail mode, which is much like Text mode except that various special commands are provided on the C-c prefix. These commands all have to do specifically with editing or sending the message. In addition, Mail mode defines the character `%' as a word separator; this is helpful for using the word commands to edit mail addresses.

Mail mode is normally used in buffers set up automatically by the mail command and related commands. However, you can also switch to Mail mode in a file-visiting buffer. This is a useful thing to do if you have saved the text of a draft message in a file.

Z.4.1 Mail Sending

Commands to send the message.

Z.4.2 Mail Header Editing

Commands to move to header fields and edit them.

Z.4.3 Citing Mail

Copying all or part of a message you are replying to.

Z.4.4 Mail Mode Miscellany

Spell checking, signatures, etc.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.4.1 Mail Sending

Mail mode has two commands for sending the message you have been editing:

C-c C-s
Send the message, and leave the mail buffer selected (mail-send).
C-c C-c
Send the message, and select some other buffer (mail-send-and-exit).
C-c C-s (mail-send) sends the message and marks the mail buffer unmodified, but leaves that buffer selected so that you can modify the message (perhaps with new recipients) and send it again. C-c C-c (mail-send-and-exit) sends and then deletes the window or switches to another buffer. It puts the mail buffer at the lowest priority for reselection by default, since you are finished with using it. This is the usual way to send the message.

In a file-visiting buffer, sending the message does not clear the modified flag, because only saving the file should do that. As a result, you don't get a warning if you try to send the same message twice.

When you send a message that contains non-ASCII characters, they need to be encoded with a coding system (see section Q.7 Coding Systems). Usually the coding system is specified automatically by your chosen language environment (see section Q.3 Language Environments). You can explicitly specify the coding system for outgoing mail by setting the variable sendmail-coding-system (see section Q.8 Recognizing Coding Systems).

If the coding system thus determined does not handle the characters in a particular message, Emacs asks you to select the coding system to use, showing a list of possible coding systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.4.2 Mail Header Editing

Mail mode provides special commands to move to particular header fields and to complete addresses in headers.

C-c C-f C-t
Move to the `To' header field, creating one if there is none (mail-to).
C-c C-f C-s
Move to the `Subject' header field, creating one if there is none (mail-subject).
C-c C-f C-c
Move to the `CC' header field, creating one if there is none (mail-cc).
C-c C-f C-b
Move to the `BCC' header field, creating one if there is none (mail-bcc).
C-c C-f C-f
Move to the `FCC' header field, creating one if there is none (mail-fcc).
M-TAB
Complete a mailing address (mail-complete).
There are five commands to move point to particular header fields, all based on the prefix C-c C-f (`C-f' is for "field"). They are listed in the table above. If the field in question does not exist, these commands create one. We provide special motion commands for these particular fields because they are the fields users most often want to edit.

While editing a header field that contains mailing addresses, such as `To:', `CC:' and `BCC:', you can complete a mailing address by typing M-TAB (mail-complete). It inserts the full name corresponding to the address, if it can determine the full name. The variable mail-complete-style controls whether to insert the full name, and what style to use, as in mail-from-style (see section Z.2 Mail Header Fields).

For completion purposes, the valid mailing addresses are taken to be the local users' names plus your personal mail aliases. You can specify additional sources of valid addresses; look at the customization group `mailalias' to see the options for this (see section AD.2.2.1 Customization Groups).

If you type M-TAB in the body of the message, mail-complete invokes ispell-complete-word, as in Text mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.4.3 Citing Mail

Mail mode also has commands for yanking or citing all or part of a message that you are replying to. These commands are active only when you started sending a message using an Rmail command.

C-c C-y
Yank the selected message from Rmail (mail-yank-original).
C-c C-r
Yank the region from the Rmail buffer (mail-yank-region).
C-c C-q
Fill each paragraph cited from another message (mail-fill-yanked-message).
When mail sending is invoked from the Rmail mail reader using an Rmail command, C-c C-y can be used inside the mail buffer to insert the text of the message you are replying to. Normally it indents each line of that message three spaces and eliminates most header fields. A numeric argument specifies the number of spaces to indent. An argument of just C-u says not to indent at all and not to eliminate anything. C-c C-y always uses the current message from the Rmail buffer, so you can insert several old messages by selecting one in Rmail, switching to `*mail*' and yanking it, then switching back to Rmail to select another.

You can specify the text for C-c C-y to insert at the beginning of each line: set mail-yank-prefix to the desired string. (A value of nil means to use indentation; this is the default.) However, C-u C-c C-y never adds anything at the beginning of the inserted lines, regardless of the value of mail-yank-prefix.

To yank just a part of an incoming message, set the region in Rmail to the part you want; then go to the `*Mail*' message and type C-c C-r (mail-yank-region). Each line that is copied is indented or prefixed according to mail-yank-prefix.

After using C-c C-y or C-c C-r, you can type C-c C-q (mail-fill-yanked-message) to fill the paragraphs of the yanked old message or messages. One use of C-c C-q fills all such paragraphs, each one individually. To fill a single paragraph of the quoted message, use M-q. If filling does not automatically handle the type of citation prefix you use, try setting the fill prefix explicitly. See section T.5 Filling Text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.4.4 Mail Mode Miscellany

C-c C-t
Move to the beginning of the message body text (mail-text).
C-c C-w
Insert the file `~/.signature' at the end of the message text (mail-signature).
C-c C-i file RET
Insert the contents of file at the end of the outgoing message (mail-attach-file).
M-x ispell-message
Perform spelling correction on the message text, but not on citations from other messages.
C-c C-t (mail-text) moves point to just after the header separator line--that is, to the beginning of the message body text.

C-c C-w (mail-signature) adds a standard piece of text at the end of the message to say more about who you are. The text comes from the file `~/.signature' in your home directory. To insert your signature automatically, set the variable mail-signature to t; after that, starting a mail message automatically inserts the contents of your `~/.signature' file. If you want to omit your signature from a particular message, delete it from the buffer before you send the message.

You can also set mail-signature to a string; then that string is inserted automatically as your signature when you start editing a message to send. If you set it to some other Lisp expression, the expression is evaluated each time, and its value (which should be a string) specifies the signature.

You can do spelling correction on the message text you have written with the command M-x ispell-message. If you have yanked an incoming message into the outgoing draft, this command skips what was yanked, but it checks the text that you yourself inserted. (It looks for indentation or mail-yank-prefix to distinguish the cited lines from your input.) See section L.4 Checking and Correcting Spelling.

To include a file in the outgoing message, you can use C-x i, the usual command to insert a file in the current buffer. But it is often more convenient to use a special command, C-c C-i (mail-attach-file). This command inserts the file contents at the end of the buffer, after your signature if any, with a delimiter line that includes the file name.

Turning on Mail mode (which C-x m does automatically) runs the normal hooks text-mode-hook and mail-mode-hook. Initializing a new outgoing message runs the normal hook mail-setup-hook; if you want to add special fields to your mail header or make other changes to the appearance of the mail buffer, use that hook. See section AD.2.3 Hooks.

The main difference between these hooks is just when they are invoked. Whenever you type M-x mail, mail-mode-hook runs as soon as the `*mail*' buffer is created. Then the mail-setup function inserts the default contents of the buffer. After these default contents are inserted, mail-setup-hook runs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.5 Mail Amusements

M-x spook adds a line of randomly chosen keywords to an outgoing mail message. The keywords are chosen from a list of words that suggest you are discussing something subversive.

The idea behind this feature is the suspicion that the NSA(13) snoops on all electronic mail messages that contain keywords suggesting they might find them interesting. (The NSA says they don't, but that's what they would say.) The idea is that if lots of people add suspicious words to their messages, the NSA will get so busy with spurious input that they will have to give up reading it all.

Here's how to insert spook keywords automatically whenever you start entering an outgoing message:
(add-hook 'mail-setup-hook 'spook)
Whether or not this confuses the NSA, it at least amuses people.

You can use the fortune program to put a "fortune cookie" message into outgoing mail. To do this, add fortune-to-signature to mail-setup-hook:
(add-hook 'mail-setup-hook 'fortune-to-signature)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Z.6 Mail-Composition Methods

In this chapter we have described the usual Emacs mode for editing and sending mail--Mail mode. Emacs has alternative facilities for editing and sending mail, including MH-E and Message mode, not documented in this manual. See section `MH-E' in The Emacs Interface to MH. See section `Message' in Message Manual. You can choose any of them as your preferred method. The commands C-x m, C-x 4 m and C-x 5 m use whichever agent you have specified, as do various other Emacs commands and facilities that send mail.

To specify your mail-composition method, customize the variable mail-user-agent. Currently legitimate values include sendmail-user-agent (Mail mode), mh-e-user-agent, message-user-agent and gnus-user-agent.

If you select a different mail-composition method, the information in this chapter about the `*mail*' buffer and Mail mode does not apply; the other methods use a different format of text in a different buffer, and their commands are different as well.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA. Reading Mail with Rmail

Rmail is an Emacs subsystem for reading and disposing of mail that you receive. Rmail stores mail messages in files called Rmail files. Reading the message in an Rmail file is done in a special major mode, Rmail mode, which redefines most letters to run commands for managing mail. The command rmail-mode is used to switch into Rmail mode, and it runs the hook rmail-mode-hook as usual, but don't run this command by hand; it can't do a reasonable job unless the buffer is visiting a proper Rmail file.

AA.1 Basic Concepts of Rmail

Basic concepts of Rmail, and simple use.

AA.2 Scrolling Within a Message

Scrolling through a message.

AA.3 Moving Among Messages

Moving to another message.

AA.4 Deleting Messages

Deleting and expunging messages.

AA.5 Rmail Files and Inboxes

How mail gets into the Rmail file.

AA.6 Multiple Rmail Files

Using multiple Rmail files.

AA.7 Copying Messages Out to Files

Copying message out to files.

AA.8 Labels

Classifying messages by labeling them.

AA.9 Rmail Attributes

Certain standard labels, called attributes.

AA.10 Sending Replies

Sending replies to messages you are viewing.

AA.11 Summaries

Summaries show brief info on many messages.

AA.12 Sorting the Rmail File

Sorting messages in Rmail.

AA.13 Display of Messages

How Rmail displays a message; customization.

AA.14 Rmail and Coding Systems

How Rmail handles decoding character sets.

AA.15 Editing Within a Message

Editing message text and headers in Rmail.

AA.16 Digest Messages

Extracting the messages from a digest message.

AA.17 Converting an Rmail File to Inbox Format

Converting an Rmail file to mailbox format.

AA.18 Reading Rot13 Messages

Reading messages encoded in the rot13 code.

AA.19 movemail and POP

More details of fetching new mail.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.1 Basic Concepts of Rmail

Using Rmail in the simplest fashion, you have one Rmail file `~/RMAIL' in which all of your mail is saved. It is called your primary Rmail file. The command M-x rmail reads your primary Rmail file, merges new mail in from your inboxes, displays the first message you haven't read yet, and lets you begin reading. The variable rmail-file-name specifies the name of the primary Rmail file.

Rmail uses narrowing to hide all but one message in the Rmail file. The message that is shown is called the current message. Rmail mode's special commands can do such things as delete the current message, copy it into another file, send a reply, or move to another message. You can also create multiple Rmail files and use Rmail to move messages between them.

Within the Rmail file, messages are normally arranged sequentially in order of receipt; you can specify other ways to sort them. Messages are assigned consecutive integers as their message numbers. The number of the current message is displayed in Rmail's mode line, followed by the total number of messages in the file. You can move to a message by specifying its message number with the j key (see section AA.3 Moving Among Messages).

Following the usual conventions of Emacs, changes in an Rmail file become permanent only when the file is saved. You can save it with s (rmail-expunge-and-save), which also expunges deleted messages from the file first (see section AA.4 Deleting Messages). To save the file without expunging, use C-x C-s. Rmail also saves the Rmail file after merging new mail from an inbox file (see section AA.5 Rmail Files and Inboxes).

You can exit Rmail with q (rmail-quit); this expunges and saves the Rmail file and then switches to another buffer. But there is no need to "exit" formally. If you switch from Rmail to editing in other buffers, and never happen to switch back, you have exited. (The Rmail command b, rmail-bury, does this for you.) Just make sure to save the Rmail file eventually (like any other file you have changed). C-x s is a good enough way to do this (see section M.3 Saving Files).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.2 Scrolling Within a Message

When Rmail displays a message that does not fit on the screen, you must scroll through it to read the rest. You could do this with C-v, M-v and M-<, but in Rmail scrolling is so frequent that it deserves to be easier to type.

SPC
Scroll forward (scroll-up).
DEL
Scroll backward (scroll-down).
.
Scroll to start of message (rmail-beginning-of-message).
Since the most common thing to do while reading a message is to scroll through it by screenfuls, Rmail makes SPC and DEL synonyms of C-v (scroll-up) and M-v (scroll-down)

The command . (rmail-beginning-of-message) scrolls back to the beginning of the selected message. This is not quite the same as M-<: for one thing, it does not set the mark; for another, it resets the buffer boundaries to the current message if you have changed them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.3 Moving Among Messages

The most basic thing to do with a message is to read it. The way to do this in Rmail is to make the message current. The usual practice is to move sequentially through the file, since this is the order of receipt of messages. When you enter Rmail, you are positioned at the first message that you have not yet made current (that is, the first one that has the `unseen' attribute; see section AA.9 Rmail Attributes). Move forward to see the other new messages; move backward to re-examine old messages.

n
Move to the next nondeleted message, skipping any intervening deleted messages (rmail-next-undeleted-message).
p
Move to the previous nondeleted message (rmail-previous-undeleted-message).
M-n
Move to the next message, including deleted messages (rmail-next-message).
M-p
Move to the previous message, including deleted messages (rmail-previous-message).
j
Move to the first message. With argument n, move to message number n (rmail-show-message).
>
Move to the last message (rmail-last-message).
<
Move to the first message (rmail-first-message).

M-s regexp RET
Move to the next message containing a match for regexp (rmail-search).

- M-s regexp RET
Move to the previous message containing a match for regexp.
n and p are the usual way of moving among messages in Rmail. They move through the messages sequentially, but skip over deleted messages, which is usually what you want to do. Their command definitions are named rmail-next-undeleted-message and rmail-previous-undeleted-message. If you do not want to skip deleted messages--for example, if you want to move to a message to undelete it--use the variants M-n and M-p (rmail-next-message and rmail-previous-message). A numeric argument to any of these commands serves as a repeat count.

In Rmail, you can specify a numeric argument by typing just the digits. You don't need to type C-u first.

The M-s (rmail-search) command is Rmail's version of search. The usual incremental search command C-s works in Rmail, but it searches only within the current message. The purpose of M-s is to search for another message. It reads a regular expression (see section K.5 Syntax of Regular Expressions) nonincrementally, then searches starting at the beginning of the following message for a match. It then selects that message. If regexp is empty, M-s reuses the regexp used the previous time.

To search backward in the file for another message, give M-s a negative argument. In Rmail you can do this with - M-s.

It is also possible to search for a message based on labels. See section AA.8 Labels.

To move to a message specified by absolute message number, use j (rmail-show-message) with the message number as argument. With no argument, j selects the first message. < (rmail-first-message) also selects the first message. > (rmail-last-message) selects the last message.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.4 Deleting Messages

When you no longer need to keep a message, you can delete it. This flags it as ignorable, and some Rmail commands pretend it is no longer present; but it still has its place in the Rmail file, and still has its message number.

Expunging the Rmail file actually removes the deleted messages. The remaining messages are renumbered consecutively. Expunging is the only action that changes the message number of any message, except for undigestifying (see section AA.16 Digest Messages).

d
Delete the current message, and move to the next nondeleted message (rmail-delete-forward).
C-d
Delete the current message, and move to the previous nondeleted message (rmail-delete-backward).
u
Undelete the current message, or move back to a deleted message and undelete it (rmail-undelete-previous-message).
x
Expunge the Rmail file (rmail-expunge).
There are two Rmail commands for deleting messages. Both delete the current message and select another message. d (rmail-delete-forward) moves to the following message, skipping messages already deleted, while C-d (rmail-delete-backward) moves to the previous nondeleted message. If there is no nondeleted message to move to in the specified direction, the message that was just deleted remains current. A numeric argument to either command reverses the direction of motion after deletion.

Whenever Rmail deletes a message, it runs the hook rmail-delete-message-hook. When the hook functions are invoked, the message has been marked deleted, but it is still the current message in the Rmail buffer.

To make all the deleted messages finally vanish from the Rmail file, type x (rmail-expunge). Until you do this, you can still undelete the deleted messages. The undeletion command, u (rmail-undelete-previous-message), is designed to cancel the effect of a d command in most cases. It undeletes the current message if the current message is deleted. Otherwise it moves backward to previous messages until a deleted message is found, and undeletes that message.

You can usually undo a d with a u because the u moves back to and undeletes the message that the d deleted. But this does not work when the d skips a few already-deleted messages that follow the message being deleted; then the u command undeletes the last of the messages that were skipped. There is no clean way to avoid this problem. However, by repeating the u command, you can eventually get back to the message that you intend to undelete. You can also select a particular deleted message with the M-p command, then type u to undelete it.

A deleted message has the `deleted' attribute, and as a result `deleted' appears in the mode line when the current message is deleted. In fact, deleting or undeleting a message is nothing more than adding or removing this attribute. See section AA.9 Rmail Attributes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.5 Rmail Files and Inboxes

The operating system places incoming mail for you in a file that we call your inbox. When you start up Rmail, it runs a C program called movemail to copy the new messages from your inbox into your primary Rmail file, which also contains other messages saved from previous Rmail sessions. It is in this file that you actually read the mail with Rmail. This operation is called getting new mail. You can get new mail at any time in Rmail by typing g.

The variable rmail-primary-inbox-list contains a list of the files which are inboxes for your primary Rmail file. If you don't set this variable explicitly, it is initialized from the MAIL environment variable, or, as a last resort, set to nil, which means to use the default inbox. The default inbox is `/var/mail/username', `/usr/spool/mail/username', or `/usr/mail/username', depending on your operating system.

To see what the default is on your system, use C-h v rmail-primary-inbox RET. You can specify the inbox file(s) for any Rmail file with the command set-rmail-inbox-list; see AA.6 Multiple Rmail Files.

There are two reasons for having separate Rmail files and inboxes.

The inbox file format varies between operating systems and according to the other mail software in use. Only one part of Rmail needs to know about the alternatives, and it need only understand how to convert all of them to Rmail's own format.

It is very cumbersome to access an inbox file without danger of losing mail, because it is necessary to interlock with mail delivery. Moreover, different operating systems use different interlocking techniques. The strategy of moving mail out of the inbox once and for all into a separate Rmail file avoids the need for interlocking in all the rest of Rmail, since only Rmail operates on the Rmail file.

Rmail was written to use Babyl format as its internal format. Since then, we have recognized that the usual inbox format on Unix and GNU systems is adequate for the job, and we plan to change Rmail to use that as its internal format. However, the Rmail file will still be separate from the inbox file, even on systems where their format is the same.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.6 Multiple Rmail Files

Rmail operates by default on your primary Rmail file, which is named `~/RMAIL' and receives your incoming mail from your system inbox file. But you can also have other Rmail files and edit them with Rmail. These files can receive mail through their own inboxes, or you can move messages into them with explicit Rmail commands (see section AA.7 Copying Messages Out to Files).

i file RET
Read file into Emacs and run Rmail on it (rmail-input).

M-x set-rmail-inbox-list RET files RET
Specify inbox file names for current Rmail file to get mail from.

g
Merge new mail from current Rmail file's inboxes (rmail-get-new-mail).

C-u g file RET
Merge new mail from inbox file file.
To run Rmail on a file other than your primary Rmail file, you may use the i (rmail-input) command in Rmail. This visits the file in Rmail mode. You can use M-x rmail-input even when not in Rmail.

The file you read with i should normally be a valid Rmail file. If it is not, Rmail tries to decompose it into a stream of messages in various known formats. If it succeeds, it converts the whole file to an Rmail file. If you specify a file name that doesn't exist, i initializes a new buffer for creating a new Rmail file.

You can also select an Rmail file from a menu. Choose first the menu bar Classify item, then from the Classify menu choose the Input Rmail File item; then choose the Rmail file you want. The variables rmail-secondary-file-directory and rmail-secondary-file-regexp specify which files to offer in the menu: the first variable says which directory to find them in; the second says which files in that directory to offer (all those that match the regular expression). These variables also apply to choosing a file for output (see section AA.7 Copying Messages Out to Files).

Each Rmail file can contain a list of inbox file names; you can specify this list with M-x set-rmail-inbox-list RET files RET. The argument can contain any number of file names, separated by commas. It can also be empty, which specifies that this file should have no inboxes. Once a list of inboxes is specified, the Rmail file remembers it permanently until you specify a different list.

As a special exception, if your primary Rmail file does not specify any inbox files, it uses your standard system inbox.

The g command (rmail-get-new-mail) merges mail into the current Rmail file from its specified inboxes. If the Rmail file has no inboxes, g does nothing. The command M-x rmail also merges new mail into your primary Rmail file.

To merge mail from a file that is not the usual inbox, give the g key a numeric argument, as in C-u g. Then it reads a file name and merges mail from that file. The inbox file is not deleted or changed in any way when g with an argument is used. This is, therefore, a general way of merging one file of messages into another.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.7 Copying Messages Out to Files

These commands copy messages from an Rmail file into another file.

o file RET
Append a copy of the current message to the file file, using Rmail file format by default (rmail-output-to-rmail-file).

C-o file RET
Append a copy of the current message to the file file, using system inbox file format by default (rmail-output).

w file RET
Output just the message body to the file file, taking the default file name from the message `Subject' header.
The commands o and C-o copy the current message into a specified file. This file may be an Rmail file or it may be in system inbox format; the output commands ascertain the file's format and write the copied message in that format.

The o and C-o commands differ in two ways: each has its own separate default file name, and each specifies a choice of format to use when the file does not already exist. The o command uses Rmail format when it creates a new file, while C-o uses system inbox format for a new file. The default file name for o is the file name used last with o, and the default file name for C-o is the file name used last with C-o.

If the output file is an Rmail file currently visited in an Emacs buffer, the output commands copy the message into that buffer. It is up to you to save the buffer eventually in its file.

Sometimes you may receive a message whose body holds the contents of a file. You can save the body to a file (excluding the message header) with the w command (rmail-output-body-to-file). Often these messages contain the intended file name in the `Subject' field, so the w command uses the `Subject' field as the default for the output file name. However, the file name is read using the minibuffer, so you can specify a different name if you wish.

You can also output a message to an Rmail file chosen with a menu. Choose first the menu bar Classify item, then from the Classify menu choose the Output Rmail File menu item; then choose the Rmail file you want. This outputs the current message to that file, like the o command. The variables rmail-secondary-file-directory and rmail-secondary-file-regexp specify which files to offer in the menu: the first variable says which directory to find them in; the second says which files in that directory to offer (all those that match the regular expression).

Copying a message gives the original copy of the message the `filed' attribute, so that `filed' appears in the mode line when such a message is current. If you like to keep just a single copy of every mail message, set the variable rmail-delete-after-output to t; then the o and C-o commands delete the original message after copying it. (You can undelete the original afterward if you wish.)

Copying messages into files in system inbox format uses the header fields that are displayed in Rmail at the time. Thus, if you use the t command to view the entire header and then copy the message, the entire header is copied. See section AA.13 Display of Messages.

The variable rmail-output-file-alist lets you specify intelligent defaults for the output file, based on the contents of the current message. The value should be a list whose elements have this form:
(regexp . name-exp)
If there's a match for regexp in the current message, then the default file name for output is name-exp. If multiple elements match the message, the first matching element decides the default file name. The subexpression name-exp may be a string constant giving the file name to use, or more generally it may be any Lisp expression that returns a file name as a string. rmail-output-file-alist applies to both o and C-o.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.8 Labels

Each message can have various labels assigned to it as a means of classification. Each label has a name; different names are different labels. Any given label is either present or absent on a particular message. A few label names have standard meanings and are given to messages automatically by Rmail when appropriate; these special labels are called attributes. (See section AA.9 Rmail Attributes.) All other labels are assigned only by users.

a label RET
Assign the label label to the current message (rmail-add-label).
k label RET
Remove the label label from the current message (rmail-kill-label).
C-M-n labels RET
Move to the next message that has one of the labels labels (rmail-next-labeled-message).
C-M-p labels RET
Move to the previous message that has one of the labels labels (rmail-previous-labeled-message).
C-M-l labels RET
Make a summary of all messages containing any of the labels labels (rmail-summary-by-labels).
The a (rmail-add-label) and k (rmail-kill-label) commands allow you to assign or remove any label on the current message. If the label argument is empty, it means to assign or remove the same label most recently assigned or removed.

Once you have given messages labels to classify them as you wish, there are two ways to use the labels: in moving and in summaries.

The command C-M-n labels RET (rmail-next-labeled-message) moves to the next message that has one of the labels labels. The argument labels specifies one or more label names, separated by commas. C-M-p (rmail-previous-labeled-message) is similar, but moves backwards to previous messages. A numeric argument to either command serves as a repeat count.

The command C-M-l labels RET (rmail-summary-by-labels) displays a summary containing only the messages that have at least one of a specified set of labels. The argument labels is one or more label names, separated by commas. See section AA.11 Summaries, for information on summaries.

If the labels argument to C-M-n, C-M-p or C-M-l is empty, it means to use the last set of labels specified for any of these commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.9 Rmail Attributes

Some labels such as `deleted' and `filed' have built-in meanings and are assigned to or removed from messages automatically at appropriate times; these labels are called attributes. Here is a list of Rmail attributes:

`unseen'
Means the message has never been current. Assigned to messages when they come from an inbox file, and removed when a message is made current. When you start Rmail, it initially shows the first message that has this attribute.
`deleted'
Means the message is deleted. Assigned by deletion commands and removed by undeletion commands (see section AA.4 Deleting Messages).
`filed'
Means the message has been copied to some other file. Assigned by the file output commands (see section AA.6 Multiple Rmail Files).
`answered'
Means you have mailed an answer to the message. Assigned by the r command (rmail-reply). See section AA.10 Sending Replies.
`forwarded'
Means you have forwarded the message. Assigned by the f command (rmail-forward). See section AA.10 Sending Replies.
`edited'
Means you have edited the text of the message within Rmail. See section AA.15 Editing Within a Message.
`resent'
Means you have resent the message. Assigned by the command M-x rmail-resend. See section AA.10 Sending Replies.
All other labels are assigned or removed only by the user, and have no standard meaning.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.10 Sending Replies

Rmail has several commands that use Mail mode to send outgoing mail. See section Z. Sending Mail, for information on using Mail mode, including certain features meant to work with Rmail. What this section documents are the special commands of Rmail for entering Mail mode. Note that the usual keys for sending mail---C-x m, C-x 4 m, and C-x 5 m---are available in Rmail mode and work just as they usually do.

m
Send a message (rmail-mail).
c
Continue editing the already started outgoing message (rmail-continue).
r
Send a reply to the current Rmail message (rmail-reply).
f
Forward the current message to other users (rmail-forward).
C-u f
Resend the current message to other users (rmail-resend).
M-m
Try sending a bounced message a second time (rmail-retry-failure).
The most common reason to send a message while in Rmail is to reply to the message you are reading. To do this, type r (rmail-reply). This displays the `*mail*' buffer in another window, much like C-x 4 m, but preinitializes the `Subject', `To', `CC' and `In-reply-to' header fields based on the message you are replying to. The `To' field starts out as the address of the person who sent the message you received, and the `CC' field starts out with all the other recipients of that message.

You can exclude certain recipients from being placed automatically in the `CC', using the variable rmail-dont-reply-to-names. Its value should be a regular expression (as a string); any recipient that the regular expression matches, is excluded from the `CC' field. The default value matches your own name, and any name starting with `info-'. (Those names are excluded because there is a convention of using them for large mailing lists to broadcast announcements.)

To omit the `CC' field completely for a particular reply, enter the reply command with a numeric argument: C-u r or 1 r.

Once the `*mail*' buffer has been initialized, editing and sending the mail goes as usual (see section Z. Sending Mail). You can edit the presupplied header fields if they are not right for you. You can also use the commands of Mail mode (see section Z.4 Mail Mode), including C-c C-y which yanks in the message that you are replying to. You can switch to the Rmail buffer, select a different message there, switch back, and yank the new current message.

Sometimes a message does not reach its destination. Mailers usually send the failed message back to you, enclosed in a failure message. The Rmail command M-m (rmail-retry-failure) prepares to send the same message a second time: it sets up a `*mail*' buffer with the same text and header fields as before. If you type C-c C-c right away, you send the message again exactly the same as the first time. Alternatively, you can edit the text or headers and then send it. The variable rmail-retry-ignored-headers, in the same format as rmail-ignored-headers (see section AA.13 Display of Messages), controls which headers are stripped from the failed message when retrying it.

Another frequent reason to send mail in Rmail is to forward the current message to other users. f (rmail-forward) makes this easy by preinitializing the `*mail*' buffer with the current message as the text, and a subject designating a forwarded message. All you have to do is fill in the recipients and send. When you forward a message, recipients get a message which is "from" you, and which has the original message in its contents.

Forwarding a message encloses it between two delimiter lines. It also modifies every line that starts with a dash, by inserting `- ' at the start of the line. When you receive a forwarded message, if it contains something besides ordinary text--for example, program source code--you might find it useful to undo that transformation. You can do this by selecting the forwarded message and typing M-x unforward-rmail-message. This command extracts the original forwarded message, deleting the inserted `- ' strings, and inserts it into the Rmail file as a separate message immediately following the current one.

Resending is an alternative similar to forwarding; the difference is that resending sends a message that is "from" the original sender, just as it reached you--with a few added header fields `Resent-From' and `Resent-To' to indicate that it came via you. To resend a message in Rmail, use C-u f. (f runs rmail-forward, which is programmed to invoke rmail-resend if you provide a numeric argument.)

The m (rmail-mail) command is used to start editing an outgoing message that is not a reply. It leaves the header fields empty. Its only difference from C-x 4 m is that it makes the Rmail buffer accessible for C-c C-y, just as r does. Thus, m can be used to reply to or forward a message; it can do anything r or f can do.

The c (rmail-continue) command resumes editing the `*mail*' buffer, to finish editing an outgoing message you were already composing, or to alter a message you have sent.

If you set the variable rmail-mail-new-frame to a non-nil value, then all the Rmail commands to start sending a message create a new frame to edit it in. This frame is deleted when you send the message, or when you use the `Cancel' item in the `Mail' menu.

All the Rmail commands to send a message use the mail-composition method that you have chosen (see section Z.6 Mail-Composition Methods).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.11 Summaries

A summary is a buffer containing one line per message to give you an overview of the mail in an Rmail file. Each line shows the message number and date, the sender, the line count, the labels, and the subject. Moving point in the summary buffer selects messages as you move to their summary lines. Almost all Rmail commands are valid in the summary buffer also; when used there, they apply to the message described by the current line of the summary.

A summary buffer applies to a single Rmail file only; if you are editing multiple Rmail files, each one can have its own summary buffer. The summary buffer name is made by appending `-summary' to the Rmail buffer's name. Normally only one summary buffer is displayed at a time.

AA.11.1 Making Summaries

Making various sorts of summaries.

AA.11.2 Editing in Summaries

Manipulating messages from the summary.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.11.1 Making Summaries

Here are the commands to create a summary for the current Rmail file. Once the Rmail file has a summary buffer, changes in the Rmail file (such as deleting or expunging messages, and getting new mail) automatically update the summary.

h

C-M-h
Summarize all messages (rmail-summary).
l labels RET

C-M-l labels RET
Summarize messages that have one or more of the specified labels (rmail-summary-by-labels).
C-M-r rcpts RET
Summarize messages that have one or more of the specified recipients (rmail-summary-by-recipients).
C-M-t topic RET
Summarize messages that have a match for the specified regexp topic in their subjects (rmail-summary-by-topic).
C-M-s regexp
Summarize messages whose headers and the subject line match the specified regular expression regexp (rmail-summary-by-regexp).
The h or C-M-h (rmail-summary) command fills the summary buffer for the current Rmail file with a summary of all the messages in the file. It then displays and selects the summary buffer in another window.

C-M-l labels RET (rmail-summary-by-labels) makes a partial summary mentioning only the messages that have one or more of the labels labels. labels should contain label names separated by commas.

C-M-r rcpts RET (rmail-summary-by-recipients) makes a partial summary mentioning only the messages that have one or more of the recipients rcpts. rcpts should contain mailing addresses separated by commas.

C-M-t topic RET (rmail-summary-by-topic) makes a partial summary mentioning only the messages whose subjects have a match for the regular expression topic.

C-M-s regexp RET (rmail-summary-by-regexp) makes a partial summary which mentions only the messages whose headers (including the date and the subject lines) match the regular expression regexp.

Note that there is only one summary buffer for any Rmail file; making one kind of summary discards any previously made summary.

The variable rmail-summary-window-size says how many lines to use for the summary window. The variable rmail-summary-line-count-flag controls whether the summary line for a message should include the line count of the message.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.11.2 Editing in Summaries

You can use the Rmail summary buffer to do almost anything you can do in the Rmail buffer itself. In fact, once you have a summary buffer, there's no need to switch back to the Rmail buffer.

You can select and display various messages in the Rmail buffer, from the summary buffer, just by moving point in the summary buffer to different lines. It doesn't matter what Emacs command you use to move point; whichever line point is on at the end of the command, that message is selected in the Rmail buffer.

Almost all Rmail commands work in the summary buffer as well as in the Rmail buffer. Thus, d in the summary buffer deletes the current message, u undeletes, and x expunges. o and C-o output the current message to a file; r starts a reply to it. You can scroll the current message while remaining in the summary buffer using SPC and DEL.

The Rmail commands to move between messages also work in the summary buffer, but with a twist: they move through the set of messages included in the summary. They also ensure the Rmail buffer appears on the screen (unlike cursor motion commands, which update the contents of the Rmail buffer but don't display it in a window unless it already appears). Here is a list of these commands:

n
Move to next line, skipping lines saying `deleted', and select its message.
p
Move to previous line, skipping lines saying `deleted', and select its message.
M-n
Move to next line and select its message.
M-p
Move to previous line and select its message.
>
Move to the last line, and select its message.
<
Move to the first line, and select its message.
M-s pattern RET
Search through messages for pattern starting with the current message; select the message found, and move point in the summary buffer to that message's line.
Deletion, undeletion, and getting new mail, and even selection of a different message all update the summary buffer when you do them in the Rmail buffer. If the variable rmail-redisplay-summary is non-nil, these actions also bring the summary buffer back onto the screen.

When you are finished using the summary, type Q (rmail-summary-wipe) to delete the summary buffer's window. You can also exit Rmail while in the summary: q (rmail-summary-quit) deletes the summary window, then exits from Rmail by saving the Rmail file and switching to another buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.12 Sorting the Rmail File

M-x rmail-sort-by-date
Sort messages of current Rmail file by date.

M-x rmail-sort-by-subject
Sort messages of current Rmail file by subject.

M-x rmail-sort-by-author
Sort messages of current Rmail file by author's name.

M-x rmail-sort-by-recipient
Sort messages of current Rmail file by recipient's names.

M-x rmail-sort-by-correspondent
Sort messages of current Rmail file by the name of the other correspondent.

M-x rmail-sort-by-lines
Sort messages of current Rmail file by size (number of lines).

M-x rmail-sort-by-keywords RET labels RET
Sort messages of current Rmail file by labels. The argument labels should be a comma-separated list of labels. The order of these labels specifies the order of messages; messages with the first label come first, messages with the second label come second, and so on. Messages which have none of these labels come last.
The Rmail sort commands perform a stable sort: if there is no reason to prefer either one of two messages, their order remains unchanged. You can use this to sort by more than one criterion. For example, if you use rmail-sort-by-date and then rmail-sort-by-author, messages from the same author appear in order by date.

With a numeric argument, all these commands reverse the order of comparison. This means they sort messages from newest to oldest, from biggest to smallest, or in reverse alphabetical order.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.13 Display of Messages

Rmail reformats the header of each message before displaying it for the first time. Reformatting hides uninteresting header fields to reduce clutter. You can use the t command to show the entire header or to repeat the header reformatting operation.

t
Toggle display of complete header (rmail-toggle-header).
Reformatting the header involves deleting most header fields, on the grounds that they are not interesting. The variable rmail-ignored-headers holds a regular expression that specifies which header fields to hide in this way--if it matches the beginning of a header field, that whole field is hidden.

Rmail saves the complete original header before reformatting; to see it, use the t command (rmail-toggle-header). This discards the reformatted headers of the current message and displays it with the original header. Repeating t reformats the message again. Selecting the message again also reformats.

One consequence of this is that if you edit the reformatted header (using e; see section AA.15 Editing Within a Message), subsequent use of t will discard your edits. On the other hand, if you use e after t, to edit the original (unreformatted) header, those changes are permanent.

When the t command has a prefix argument, a positive argument means to show the reformatted header, and a zero or negative argument means to show the full header.

When the terminal supports multiple fonts or colors, Rmail highlights certain header fields that are especially interesting--by default, the `From' and `Subject' fields. The variable rmail-highlighted-headers holds a regular expression that specifies the header fields to highlight; if it matches the beginning of a header field, that whole field is highlighted.

If you specify unusual colors for your text foreground and background, the colors used for highlighting may not go well with them. If so, specify different colors for the face rmail-highlight-face. See section J.1 Using Multiple Typefaces, for how to do this. To turn off highlighting entirely in Rmail, set rmail-highlighted-headers to nil.

You can highlight and activate URLs in incoming messages by adding the function goto-address to the hook rmail-show-message-hook. Then you can browse these URLs by clicking on them with Mouse-2 or by moving to one and typing C-c RET. See section Activating URLs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.14 Rmail and Coding Systems

Rmail automatically decodes messages which contain non-ASCII characters, just as Emacs does with files you visit and with subprocess output. Rmail uses the standard `charset=charset' header in the message, if any, to determine how the message was encoded by the sender. It maps charset into the corresponding Emacs coding system (see section Q.7 Coding Systems), and uses that coding system to decode message text. If the message header doesn't have the `charset' specification, or if charset is not recognized, Rmail chooses the coding system with the usual Emacs heuristics and defaults (see section Q.8 Recognizing Coding Systems).

Occasionally, a message is decoded incorrectly, either because Emacs guessed the wrong coding system in the absence of the `charset' specification, or because the specification was inaccurate. For example, a misconfigured mailer could send a message with a `charset=iso-8859-1' header when the message is actually encoded in koi8-r. When you see the message text garbled, or some of its characters displayed as empty boxes, this may have happened.

You can correct the problem by decoding the message again using the right coding system, if you can figure out or guess which one is right. To do this, invoke the M-x rmail-redecode-body command. It reads the name of a coding system, encodes the message body using whichever coding system was used to decode it before, then redecodes it using the coding system you specified. If you specified the right coding system, the result should be readable.

Decoding and encoding using the wrong coding system is lossless for most encodings, in particular with 8-bit encodings such as iso-8859 or koi8. So, if the initial attempt to redecode the message didn't result in a legible text, you can try other coding systems until you succeed.

With some coding systems, notably those from the iso-2022 family, information can be lost in decoding, so that encoding the message again won't bring back the original incoming text. In such a case, rmail-redecode-body cannot work. However, the problems that call for use of rmail-redecode-body rarely occur with those coding systems. So in practice the command works when you need it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.15 Editing Within a Message

Most of the usual Emacs commands are available in Rmail mode, though a few, such as C-M-n and C-M-h, are redefined by Rmail for other purposes. However, the Rmail buffer is normally read only, and most of the letters are redefined as Rmail commands. If you want to edit the text of a message, you must use the Rmail command e.

e
Edit the current message as ordinary text.
The e command (rmail-edit-current-message) switches from Rmail mode into Rmail Edit mode, another major mode which is nearly the same as Text mode. The mode line indicates this change.

In Rmail Edit mode, letters insert themselves as usual and the Rmail commands are not available. When you are finished editing the message and are ready to go back to Rmail, type C-c C-c, which switches back to Rmail mode. Alternatively, you can return to Rmail mode but cancel all the editing that you have done, by typing C-c C-].

Entering Rmail Edit mode runs the hook text-mode-hook; then it runs the hook rmail-edit-mode-hook (see section AD.2.3 Hooks). It adds the attribute `edited' to the message. It also displays the full headers of the message, so that you can edit the headers as well as the body of the message, and your changes in the headers will be permanent.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.16 Digest Messages

A digest message is a message which exists to contain and carry several other messages. Digests are used on some moderated mailing lists; all the messages that arrive for the list during a period of time such as one day are put inside a single digest which is then sent to the subscribers. Transmitting the single digest uses much less computer time than transmitting the individual messages even though the total size is the same, because the per-message overhead in network mail transmission is considerable.

When you receive a digest message, the most convenient way to read it is to undigestify it: to turn it back into many individual messages. Then you can read and delete the individual messages as it suits you.

To do this, select the digest message and type the command M-x undigestify-rmail-message. This extracts the submessages as separate Rmail messages, and inserts them following the digest. The digest message itself is flagged as deleted.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.17 Converting an Rmail File to Inbox Format

The command M-x unrmail converts a file in Rmail format to inbox format (also known as the system mailbox, or mbox, format), so that you can use it with other mail-editing tools. You must specify two arguments, the name of the Rmail file and the name to use for the converted file. M-x unrmail does not alter the Rmail file itself.

M-x unrmail is useful if you can run Emacs on the machine where the Rmail file resides, or can access the Rmail file remotely (see section M.13 Remote Files) from a machine where Emacs is installed. If accessing Rmail files from Emacs is impossible, you can use the b2m program instead. b2m is part of the Emacs distribution, it is installed into the same directory where all the other auxiliary programs (etags etc.) are installed, and its source is available in the Emacs source distribution, so that you could copy the source to the target machine and compile it there.

To convert a file `babyl-file' into `mbox-file', invoke b2m like this:
 b2m < babyl-file > mbox-file
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.18 Reading Rot13 Messages

Mailing list messages that might offend some readers are sometimes encoded in a simple code called rot13---so named because it rotates the alphabet by 13 letters. This code is not for secrecy, as it provides none; rather, it enables those who might be offended to avoid ever seeing the real text of the message.

To view a buffer using the rot13 code, use the command M-x rot13-other-window. This displays the current buffer in another window which applies the code when displaying the text.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AA.19 movemail and POP

When getting new mail, Rmail first copies the new mail from the inbox file to the Rmail file; then it saves the Rmail file; then it truncates the inbox file. This way, a system crash may cause duplication of mail between the inbox and the Rmail file, but cannot lose mail. If rmail-preserve-inbox is non-nil, then Rmail will copy new mail from the inbox file to the Rmail file without truncating the inbox file. You may wish to set this, for example, on a portable computer you use to check your mail via POP while traveling, so that your mail will remain on the server and you can save it later on your workstation.

In some cases, Rmail copies the new mail from the inbox file indirectly. First it runs the movemail program to move the mail from the inbox to an intermediate file called `~/.newmail-inboxname'. Then Rmail merges the new mail from that file, saves the Rmail file, and only then deletes the intermediate file. If there is a crash at the wrong time, this file continues to exist, and Rmail will use it again the next time it gets new mail from that inbox.

If Rmail is unable to convert the data in `~/.newmail-inboxname' into Babyl format, it renames the file to `~/RMAILOSE.n' (n is an integer chosen to make the name unique) so that Rmail will not have trouble with the data again. You should look at the file, find whatever message confuses Rmail (probably one that includes the control-underscore character, octal code 037), and delete it. Then you can use 1 g to get new mail from the corrected file.

Some sites use a method called POP for accessing users' inbox data instead of storing the data in inbox files. movemail can work with POP if you compile it with the macro MAIL_USE_POP defined. (You can achieve that by specifying `--with-pop' when you run configure during the installation of Emacs.) movemail only works with POP3, not with older versions of POP.

Assuming you have compiled and installed movemail appropriately, you can specify a POP inbox by using a "file name" of the form `po:username', in the inbox list of an Rmail file. movemail handles such a name by opening a connection to the POP server. The MAILHOST environment variable specifies the machine to look for the server on; alternatively, you can specify the POP server host name as part of the mailbox name using the syntax `po:username:hostname'.

Accessing mail via POP may require a password. If the variable rmail-pop-password is non-nil, it specifies the password to use for POP. Alternatively, if rmail-pop-password-required is non-nil, then Rmail asks you for the password to use.

If you need to pass additional command-line flags to movemail, set the variable rmail-movemail-flags a list of the flags you wish to use. Do not use this variable to pass the `-p' flag to preserve your inbox contents; use rmail-preserve-inbox instead.

The movemail program installed at your site may support Kerberos authentication. If it is supported, it is used by default whenever you attempt to retrieve POP mail when rmail-pop-password and rmail-pop-password-required are unset.

Some POP servers store messages in reverse order. If your server does this, and you would rather read your mail in the order in which it was received, you can tell movemail to reverse the order of downloaded messages by adding the `-r' flag to rmail-movemail-flags.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB. Dired, the Directory Editor

Dired makes an Emacs buffer containing a listing of a directory, and optionally some of its subdirectories as well. You can use the normal Emacs commands to move around in this buffer, and special Dired commands to operate on the files listed.

The Dired buffer is "read-only," and inserting text in it is not useful, so ordinary printing characters such as d and x are used for special Dired commands. Some Dired commands mark or flag the current file (that is, the file on the current line); other commands operate on the marked files or on the flagged files.

The Dired-X package provides various extra features for Dired mode. See section `Top' in Dired Extra Version 2 User's Manual.

AB.1 Entering Dired

How to invoke Dired.

AB.2 Navigation in the Dired Buffer

Special motion commands in the Dired buffer.

AB.3 Deleting Files with Dired

Deleting files with Dired.

AB.4 Flagging Many Files at Once

Flagging files based on their names.

AB.5 Visiting Files in Dired

Other file operations through Dired.

AB.6 Dired Marks vs. Flags

Flagging for deletion vs marking.

AB.7 Operating on Files

How to copy, rename, print, compress, etc. either one file or several files.

AB.8 Shell Commands in Dired

Running a shell command on the marked files.

AB.9 Transforming File Names in Dired

Using patterns to rename multiple files.

AB.10 File Comparison with Dired

Running `diff' by way of Dired.

AB.11 Subdirectories in Dired

Adding subdirectories to the Dired buffer.

AB.12 Moving Over Subdirectories

Moving across subdirectories, and up and down.

AB.13 Hiding Subdirectories

Making subdirectories visible or invisible.

AB.14 Updating the Dired Buffer

Discarding lines for files of no interest.

AB.15 Dired and find

Using `find' to choose the files for Dired.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.1 Entering Dired

To invoke Dired, do C-x d or M-x dired. The command reads a directory name or wildcard file name pattern as a minibuffer argument to specify which files to list. Where dired differs from list-directory is in putting the buffer into Dired mode so that the special commands of Dired are available.

The variable dired-listing-switches specifies the options to give to ls for listing directory; this string must contain `-l'. If you use a numeric prefix argument with the dired command, you can specify the ls switches with the minibuffer before you enter the directory specification.

To display the Dired buffer in another window rather than in the selected window, use C-x 4 d (dired-other-window) instead of C-x d. C-x 5 d (dired-other-frame) uses a separate frame to display the Dired buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.2 Navigation in the Dired Buffer

All the usual Emacs cursor motion commands are available in Dired buffers. Some special-purpose cursor motion commands are also provided. The keys C-n and C-p are redefined to put the cursor at the beginning of the file name on the line, rather than at the beginning of the line.

For extra convenience, SPC and n in Dired are equivalent to C-n. p is equivalent to C-p. (Moving by lines is so common in Dired that it deserves to be easy to type.) DEL (move up and unflag) is often useful simply for moving up.

Some additional navigation commands are available when the Dired buffer includes several directories. See section AB.12 Moving Over Subdirectories.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.3 Deleting Files with Dired

One of the most frequent uses of Dired is to first flag files for deletion, then delete the files that were flagged.

d
Flag this file for deletion.
u
Remove deletion flag on this line.
DEL
Move point to previous line and remove the deletion flag on that line.
x
Delete the files that are flagged for deletion.
You can flag a file for deletion by moving to the line describing the file and typing d (dired-flag-file-deletion). The deletion flag is visible as a `D' at the beginning of the line. This command moves point to the next line, so that repeated d commands flag successive files. A numeric argument serves as a repeat count.

The variable dired-recursive-deletes controls whether the delete command will delete non-empty directories (including their contents). The default is to delete only empty directories.

The files are flagged for deletion rather than deleted immediately to reduce the danger of deleting a file accidentally. Until you direct Dired to delete the flagged files, you can remove deletion flags using the commands u and DEL. u (dired-unmark) works just like d, but removes flags rather than making flags. DEL (dired-unmark-backward) moves upward, removing flags; it is like u with argument -1.

To delete the flagged files, type x (dired-do-flagged-delete). (This is also known as expunging.) This command first displays a list of all the file names flagged for deletion, and requests confirmation with yes. If you confirm, Dired deletes the flagged files, then deletes their lines from the text of the Dired buffer. The shortened Dired buffer remains selected.

If you answer no or quit with C-g when asked to confirm, you return immediately to Dired, with the deletion flags still present in the buffer, and no files actually deleted.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.4 Flagging Many Files at Once

#
Flag all auto-save files (files whose names start and end with `#') for deletion (see section M.5 Auto-Saving: Protection Against Disasters).

~
Flag all backup files (files whose names end with `~') for deletion (see section M.3.1 Backup Files).

&
Flag for deletion all files with certain kinds of names, names that suggest you could easily create the files again.

. (Period)
Flag excess numeric backup files for deletion. The oldest and newest few backup files of any one file are exempt; the middle ones are flagged.

% d regexp RET
Flag for deletion all files whose names match the regular expression regexp.
The #, ~, &, and . commands flag many files for deletion, based on their file names. These commands are useful precisely because they do not themselves delete any files; you can remove the deletion flags from any flagged files that you really wish to keep.

& (dired-flag-garbage-files) flags files whose names match the regular expression specified by the variable dired-garbage-files-regexp. By default, this matches certain files produced by TeX, `.bak' files, and the `.orig' and `.rej' files produced by patch.

# (dired-flag-auto-save-files) flags for deletion all files whose names look like auto-save files (see section M.5 Auto-Saving: Protection Against Disasters)---that is, files whose names begin and end with `#'.

~ (dired-flag-backup-files) flags for deletion all files whose names say they are backup files (see section M.3.1 Backup Files)---that is, files whose names end in `~'.

. (period, dired-clean-directory) flags just some of the backup files for deletion: all but the oldest few and newest few backups of any one file. Normally dired-kept-versions (not kept-new-versions; that applies only when saving) specifies the number of newest versions of each file to keep, and kept-old-versions specifies the number of oldest versions to keep.

Period with a positive numeric argument, as in C-u 3 ., specifies the number of newest versions to keep, overriding dired-kept-versions. A negative numeric argument overrides kept-old-versions, using minus the value of the argument to specify the number of oldest versions of each file to keep.

The % d command flags all files whose names match a specified regular expression (dired-flag-files-regexp). Only the non-directory part of the file name is used in matching. You can use `^' and `$' to anchor matches. You can exclude subdirectories by hiding them (see section AB.13 Hiding Subdirectories).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.5 Visiting Files in Dired

There are several Dired commands for visiting or examining the files listed in the Dired buffer. All of them apply to the current line's file; if that file is really a directory, these commands invoke Dired on that subdirectory (making a separate Dired buffer).

f
Visit the file described on the current line, like typing C-x C-f and supplying that file name (dired-find-file). See section M.2 Visiting Files.

RET

e
Equivalent to f.

a
Like f, but replaces the contents of the Dired buffer with that of an alternate file or directory (dired-find-alternate-file).

o
Like f, but uses another window to display the file's buffer (dired-find-file-other-window). The Dired buffer remains visible in the first window. This is like using C-x 4 C-f to visit the file. See section O. Multiple Windows.

C-o
Visit the file described on the current line, and display the buffer in another window, but do not select that window (dired-display-file).

Mouse-2
Visit the file named by the line you click on (dired-mouse-find-file-other-window). This uses another window to display the file, like the o command.

v
View the file described on the current line, using M-x view-file (dired-view-file).
Viewing a file is like visiting it, but is slanted toward moving around in the file conveniently and does not allow changing the file. See section Miscellaneous File Operations.

^
Visit the parent directory of the current directory (dired-up-directory). This is more convenient than moving to the parent directory's line and typing f there.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.6 Dired Marks vs. Flags

Instead of flagging a file with `D', you can mark the file with some other character (usually `*'). Most Dired commands to operate on files use the files marked with `*', the exception being x which deletes the flagged files.

Here are some commands for marking with `*', or for unmarking or operating on marks. (See section AB.3 Deleting Files with Dired, for commands to flag and unflag files.)

m

* m
Mark the current file with `*' (dired-mark). With a numeric argument n, mark the next n files starting with the current file. (If n is negative, mark the previous -n files.)

* *
Mark all executable files with `*' (dired-mark-executables). With a numeric argument, unmark all those files.

* @
Mark all symbolic links with `*' (dired-mark-symlinks). With a numeric argument, unmark all those files.

* /
Mark with `*' all files which are actually directories, except for `.' and `..' (dired-mark-directories). With a numeric argument, unmark all those files.

* s
Mark all the files in the current subdirectory, aside from `.' and `..' (dired-mark-subdir-files).

u

* u
Remove any mark on this line (dired-unmark).

DEL

* DEL
Move point to previous line and remove any mark on that line (dired-unmark-backward).

* !
Remove all marks from all the files in this Dired buffer (dired-unmark-all-marks).

* ? markchar
Remove all marks that use the character markchar (dired-unmark-all-files). The argument is a single character--do not use RET to terminate it. See the description of the * c command below, which lets you replace one mark character with another.
With a numeric argument, this command queries about each marked file, asking whether to remove its mark. You can answer y meaning yes, n meaning no, or ! to remove the marks from the remaining files without asking about them.

* C-n
Move down to the next marked file (dired-next-marked-file) A file is "marked" if it has any kind of mark.

* C-p
Move up to the previous marked file (dired-prev-marked-file)

* t
Toggle all marks (dired-do-toggle): files marked with `*' become unmarked, and unmarked files are marked with `*'. Files marked in any other way are not affected.

* c old-markchar new-markchar
Replace all marks that use the character old-markchar with marks that use the character new-markchar (dired-change-marks). This command is the primary way to create or use marks other than `*' or `D'. The arguments are single characters--do not use RET to terminate them.
You can use almost any character as a mark character by means of this command, to distinguish various classes of files. If old-markchar is a space (` '), then the command operates on all unmarked files; if new-markchar is a space, then the command unmarks the files it acts on.

To illustrate the power of this command, here is how to put `D' flags on all the files that have no marks, while unflagging all those that already have `D' flags:
* c D t  * c SPC D  * c t SPC
This assumes that no files were already marked with `t'.

% m regexp RET

* % regexp RET
Mark (with `*') all files whose names match the regular expression regexp (dired-mark-files-regexp). This command is like % d, except that it marks files with `*' instead of flagging with `D'. See section AB.4 Flagging Many Files at Once.
Only the non-directory part of the file name is used in matching. Use `^' and `$' to anchor matches. Exclude subdirectories by hiding them (see section AB.13 Hiding Subdirectories).

% g regexp RET
Mark (with `*') all files whose contents contain a match for the regular expression regexp (dired-mark-files-containing-regexp). This command is like % m, except that it searches the file contents instead of the file name.

C-_
Undo changes in the Dired buffer, such as adding or removing marks (dired-undo). This command does not revert the actual file operations, nor recover lost files! It just undoes changes in the buffer itself. For example, if used after renaming one or more files, dired-undo restores the original names, which will get the Dired buffer out of sync with the actual contents of the directory.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.7 Operating on Files

This section describes the basic Dired commands to operate on one file or several files. All of these commands are capital letters; all of them use the minibuffer, either to read an argument or to ask for confirmation, before they act. All of them give you several ways to specify which files to manipulate:

If you give the command a numeric prefix argument n, it operates on the next n files, starting with the current file. (If n is negative, the command operates on the -n files preceding the current line.)

Otherwise, if some files are marked with `*', the command operates on all those files.

Otherwise, the command operates on the current file only.

Commands which ask for a destination directory, such as those which copy and rename files or create links for them, try to guess the default target directory for the operation. Normally, they suggest the Dired buffer's default directory, but if the variable dired-dwim-target is non-nil, and if there is another Dired buffer displayed in the next window, that other buffer's directory is suggested instead.

Here are the file-manipulating commands that operate on files in this way. (Some other Dired commands, such as ! and the `%' commands, also use these conventions to decide which files to work on.)

C new RET
Copy the specified files (dired-do-copy). The argument new is the directory to copy into, or (if copying a single file) the new name.
If dired-copy-preserve-time is non-nil, then copying with this command sets the modification time of the new file to be the same as that of the old file.

The variable dired-recursive-copies controls whether directories are copied recursively. The default is to not copy recursively, which means that directories cannot be copied.

D
Delete the specified files (dired-do-delete). Like the other commands in this section, this command operates on the marked files, or the next n files. By contrast, x (dired-do-flagged-delete) deletes all flagged files.

R new RET
Rename the specified files (dired-do-rename). The argument new is the directory to rename into, or (if renaming a single file) the new name.
Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names.

H new RET
Make hard links to the specified files (dired-do-hardlink). The argument new is the directory to make the links in, or (if making just one link) the name to give the link.

S new RET
Make symbolic links to the specified files (dired-do-symlink). The argument new is the directory to make the links in, or (if making just one link) the name to give the link.

M modespec RET
Change the mode (also called "permission bits") of the specified files (dired-do-chmod). This uses the chmod program, so modespec can be any argument that chmod can handle.

G newgroup RET
Change the group of the specified files to newgroup (dired-do-chgrp).

O newowner RET
Change the owner of the specified files to newowner (dired-do-chown). (On most systems, only the superuser can do this.)
The variable dired-chown-program specifies the name of the program to use to do the work (different systems put chown in different places).

P command RET
Print the specified files (dired-do-print). You must specify the command to print them with, but the minibuffer starts out with a suitable guess made using the variables lpr-command and lpr-switches (the same variables that lpr-buffer uses; see section AC.18 Hardcopy Output).

Z
Compress the specified files (dired-do-compress). If the file appears to be a compressed file already, it is uncompressed instead.

L
Load the specified Emacs Lisp files (dired-do-load). See section V.7 Libraries of Lisp Code for Emacs.

B
Byte compile the specified Emacs Lisp files (dired-do-byte-compile). See section `Byte Compilation' in The Emacs Lisp Reference Manual.

A regexp RET
Search all the specified files for the regular expression regexp (dired-do-search).
This command is a variant of tags-search. The search stops at the first match it finds; use M-, to resume the search and find the next match. See section W.2.6 Searching and Replacing with Tags Tables.

Q regexp RET to RET
Perform query-replace-regexp on each of the specified files, replacing matches for regexp with the string to (dired-do-query-replace-regexp).
This command is a variant of tags-query-replace. If you exit the query replace loop, you can use M-, to resume the scan and replace more matches. See section W.2.6 Searching and Replacing with Tags Tables.
One special file-operation command is + (dired-create-directory). This command reads a directory name and creates the directory if it does not already exist.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.8 Shell Commands in Dired

The Dired command ! (dired-do-shell-command) reads a shell command string in the minibuffer and runs that shell command on all the specified files. X is a synonym for !. You can specify the files to operate on in the usual ways for Dired commands (see section AB.7 Operating on Files). There are two ways of applying a shell command to multiple files:

If you use `*' in the shell command, then it runs just once, with the list of file names substituted for the `*'. The order of file names is the order of appearance in the Dired buffer.
Thus, ! tar cf foo.tar * RET runs tar on the entire list of file names, putting them into one tar file `foo.tar'.

If the command string doesn't contain `*', then it runs once for each file, with the file name added at the end.
For example, ! uudecode RET runs uudecode on each file.

What if you want to run the shell command once for each file, with the file name inserted in the middle? You can use `?' in the command instead of `*'. The current file name is substituted for `?'. You can use `?' more than once. For instance, here is how to uuencode each file, making the output file name by appending `.uu' to the input file name:
uuencode ? ? > ?.uu
To use the file names in a more complicated fashion, you can use a shell loop. For example, this shell command is another way to uuencode each file:
for file in *; do uuencode "$file" "$file" >"$file".uu; done
The working directory for the shell command is the top-level directory of the Dired buffer.

The ! command does not attempt to update the Dired buffer to show new or modified files, because it doesn't really understand shell commands, and does not know what files the shell command changed. Use the g command to update the Dired buffer (see section AB.14 Updating the Dired Buffer).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.9 Transforming File Names in Dired

This section describes Dired commands which alter file names in a systematic way.

Like the basic Dired file-manipulation commands (see section AB.7 Operating on Files), the commands described here operate either on the next n files, or on all files marked with `*', or on the current file. (To mark files, use the commands described in AB.6 Dired Marks vs. Flags.)

All of the commands described in this section work interactively: they ask you to confirm the operation for each candidate file. Thus, you can select more files than you actually need to operate on (e.g., with a regexp that matches many files), and then refine the selection by typing y or n when the command prompts for confirmation.

% u
Rename each of the selected files to an upper-case name (dired-upcase). If the old file names are `Foo' and `bar', the new names are `FOO' and `BAR'.

% l
Rename each of the selected files to a lower-case name (dired-downcase). If the old file names are `Foo' and `bar', the new names are `foo' and `bar'.

% R from RET to RET

% C from RET to RET

% H from RET to RET

% S from RET to RET
These four commands rename, copy, make hard links and make soft links, in each case computing the new name by regular-expression substitution from the name of the old file.
The four regular-expression substitution commands effectively perform a search-and-replace on the selected file names in the Dired buffer. They read two arguments: a regular expression from, and a substitution pattern to.

The commands match each "old" file name against the regular expression from, and then replace the matching part with to. You can use `\&' and `\digit' in to to refer to all or part of what the pattern matched in the old file name, as in replace-regexp (see section K.7.2 Regexp Replacement). If the regular expression matches more than once in a file name, only the first match is replaced.

For example, % R ^.*$ RET x-\& RET renames each selected file by prepending `x-' to its name. The inverse of this, removing `x-' from the front of each file name, is also possible: one method is % R ^x-\(.*\)$ RET \1 RET; another is % R ^x- RET RET. (Use `^' and `$' to anchor matches that should span the whole filename.)

Normally, the replacement process does not consider the files' directory names; it operates on the file name within the directory. If you specify a numeric argument of zero, then replacement affects the entire absolute file name including directory name. (Non-zero argument specifies the number of files to operate on.)

Often you will want to select the set of files to operate on using the same regexp that you will use to operate on them. To do this, mark those files with % m regexp RET, then use the same regular expression in the command to operate on the files. To make this easier, the % commands to operate on files use the last regular expression specified in any % command as a default.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.10 File Comparison with Dired

Here are two Dired commands that compare specified files using diff.

=
Compare the current file (the file at point) with another file (the file at the mark) using the diff program (dired-diff). The file at the mark is the first argument of diff, and the file at point is the second argument. Use C-SPC (set-mark-command) to set the mark at the first file's line (see section H.1 Setting the Mark), since dired-diff ignores the files marked with the Dired's m command.

M-=
Compare the current file with its latest backup file (dired-backup-diff). If the current file is itself a backup, compare it with the file it is a backup of; this way, you can compare a file with any backup version of your choice.
The backup file is the first file given to diff.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.11 Subdirectories in Dired

A Dired buffer displays just one directory in the normal case; but you can optionally include its subdirectories as well.

The simplest way to include multiple directories in one Dired buffer is to specify the options `-lR' for running ls. (If you give a numeric argument when you run Dired, then you can specify these options in the minibuffer.) That produces a recursive directory listing showing all subdirectories at all levels.

But usually all the subdirectories are too many; usually you will prefer to include specific subdirectories only. You can do this with the i command:

i
Insert the contents of a subdirectory later in the buffer.
Use the i (dired-maybe-insert-subdir) command on a line that describes a file which is a directory. It inserts the contents of that directory into the same Dired buffer, and moves there. Inserted subdirectory contents follow the top-level directory of the Dired buffer, just as they do in `ls -lR' output.

If the subdirectory's contents are already present in the buffer, the i command just moves to it.

In either case, i sets the Emacs mark before moving, so C-u C-SPC takes you back to the old position in the buffer (the line describing that subdirectory).

Use the l command (dired-do-redisplay) to update the subdirectory's contents. Use C-u k on the subdirectory header line to delete the subdirectory. See section AB.14 Updating the Dired Buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.12 Moving Over Subdirectories

When a Dired buffer lists subdirectories, you can use the page motion commands C-x [ and C-x ] to move by entire directories (see section T.4 Pages).

The following commands move across, up and down in the tree of directories within one Dired buffer. They move to directory header lines, which are the lines that give a directory's name, at the beginning of the directory's contents.

C-M-n
Go to next subdirectory header line, regardless of level (dired-next-subdir).

C-M-p
Go to previous subdirectory header line, regardless of level (dired-prev-subdir).

C-M-u
Go up to the parent directory's header line (dired-tree-up).

C-M-d
Go down in the directory tree, to the first subdirectory's header line (dired-tree-down).

<
Move up to the previous directory-file line (dired-prev-dirline). These lines are the ones that describe a directory as a file in its parent directory.

>
Move down to the next directory-file line (dired-prev-dirline).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.13 Hiding Subdirectories

Hiding a subdirectory means to make it invisible, except for its header line, via selective display (see section J.9 Selective Display).

$
Hide or reveal the subdirectory that point is in, and move point to the next subdirectory (dired-hide-subdir). A numeric argument serves as a repeat count.

M-$
Hide all subdirectories in this Dired buffer, leaving only their header lines (dired-hide-all). Or, if any subdirectory is currently hidden, make all subdirectories visible again. You can use this command to get an overview in very deep directory trees or to move quickly to subdirectories far away.
Ordinary Dired commands never consider files inside a hidden subdirectory. For example, the commands to operate on marked files ignore files in hidden directories even if they are marked. Thus you can use hiding to temporarily exclude subdirectories from operations without having to remove the markers.

The subdirectory hiding commands toggle; that is, they hide what was visible, and show what was hidden.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.14 Updating the Dired Buffer

This section describes commands to update the Dired buffer to reflect outside (non-Dired) changes in the directories and files, and to delete part of the Dired buffer.

g
Update the entire contents of the Dired buffer (revert-buffer).

l
Update the specified files (dired-do-redisplay).

k
Delete the specified file lines---not the files, just the lines (dired-do-kill-lines).

s
Toggle between alphabetical order and date/time order (dired-sort-toggle-or-edit).

C-u s switches RET
Refresh the Dired buffer using switches as dired-listing-switches.
Type g (revert-buffer) to update the contents of the Dired buffer, based on changes in the files and directories listed. This preserves all marks except for those on files that have vanished. Hidden subdirectories are updated but remain hidden.

To update only some of the files, type l (dired-do-redisplay). Like the Dired file-operating commands, this command operates on the next n files (or previous -n files), or on the marked files if any, or on the current file. Updating the files means reading their current status, then updating their lines in the buffer to indicate that status.

If you use l on a subdirectory header line, it updates the contents of the corresponding subdirectory.

To delete the specified file lines from the buffer--not delete the files--type k (dired-do-kill-lines). Like the file-operating commands, this command operates on the next n files, or on the marked files if any; but it does not operate on the current file as a last resort.

If you kill the line for a file that is a directory, the directory's contents are also deleted from the buffer. Typing C-u k on the header line for a subdirectory is another way to delete a subdirectory from the Dired buffer.

The g command brings back any individual lines that you have killed in this way, but not subdirectories--you must use i to reinsert a subdirectory.

The files in a Dired buffers are normally listed in alphabetical order by file names. Alternatively Dired can sort them by date/time. The Dired command s (dired-sort-toggle-or-edit) switches between these two sorting modes. The mode line in a Dired buffer indicates which way it is currently sorted--by name, or by date.

C-u s switches RET lets you specify a new value for dired-listing-switches.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AB.15 Dired and find

You can select a set of files for display in a Dired buffer more flexibly by using the find utility to choose the files.

To search for files with names matching a wildcard pattern use M-x find-name-dired. It reads arguments directory and pattern, and chooses all the files in directory or its subdirectories whose individual names match pattern.

The files thus chosen are displayed in a Dired buffer in which the ordinary Dired commands are available.

If you want to test the contents of files, rather than their names, use M-x find-grep-dired. This command reads two minibuffer arguments, directory and regexp; it chooses all the files in directory or its subdirectories that contain a match for regexp. It works by running the programs find and grep. See also M-x grep-find, in V.1 Running Compilations under Emacs. Remember to write the regular expression for grep, not for Emacs. (An alternative method of showing files whose contents match a given regexp is the % g regexp command, see AB.6 Dired Marks vs. Flags.)

The most general command in this series is M-x find-dired, which lets you specify any condition that find can test. It takes two minibuffer arguments, directory and find-args; it runs find in directory, passing find-args to tell find what condition to test. To use this command, you need to know how to use find.

M-x locate provides a similar interface to the locate program. M-x locate-with-filter is similar, but keeps only lines matching a given regular expression.

The format of listing produced by these commands is controlled by the variable find-ls-option, whose default value specifies using options `-ld' for ls. If your listings are corrupted, you may need to change the value of this variable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC. The Calendar and the Diary

Emacs provides the functions of a desk calendar, with a diary of planned or past events. It also has facilities for managing your appointments, and keeping track of how much time you spend working on certain projects.

To enter the calendar, type M-x calendar; this displays a three-month calendar centered on the current month, with point on the current date. With a numeric argument, as in C-u M-x calendar, it prompts you for the month and year to be the center of the three-month calendar. The calendar uses its own buffer, whose major mode is Calendar mode.

Mouse-2 in the calendar brings up a menu of operations on a particular date; C-Mouse-3 brings up a menu of commonly used calendar features that are independent of any particular date. To exit the calendar, type q. See section `Calendar' in The Emacs Lisp Reference Manual, for customization information about the calendar and diary.

AC.1 Movement in the Calendar

Moving through the calendar; selecting a date.

AC.2 Scrolling in the Calendar

Bringing earlier or later months onto the screen.

AC.3 Counting Days

How many days are there between two dates?

AC.4 Miscellaneous Calendar Commands

Exiting or recomputing the calendar.

AC.5 LaTeX Calendar

Print a calendar using LaTeX.

AC.6 Holidays

Displaying dates of holidays.

AC.7 Times of Sunrise and Sunset

Displaying local times of sunrise and sunset.

AC.8 Phases of the Moon

Displaying phases of the moon.

AC.9 Conversion To and From Other Calendars

Converting dates to other calendar systems.

AC.10 The Diary

Displaying events from your diary.

AC.11 Appointments

Reminders when it's time to do something.

AC.12 Daylight Savings Time

How to specify when daylight savings time is active.

AC.13 Summing Time Intervals

Keeping track of time intervals.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.1 Movement in the Calendar

Calendar mode lets you move through the calendar in logical units of time such as days, weeks, months, and years. If you move outside the three months originally displayed, the calendar display "scrolls" automatically through time to make the selected date visible. Moving to a date lets you view its holidays or diary entries, or convert it to other calendars; moving longer time periods is also useful simply to scroll the calendar.

AC.1.1 Motion by Standard Lengths of Time

Moving by days, weeks, months, and years.

AC.1.2 Beginning or End of Week, Month or Year

Moving to start/end of weeks, months, and years.

AC.1.3 Specified Dates

Moving to the current date or another specific date.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.1.1 Motion by Standard Lengths of Time

The commands for movement in the calendar buffer parallel the commands for movement in text. You can move forward and backward by days, weeks, months, and years.

C-f
Move point one day forward (calendar-forward-day).
C-b
Move point one day backward (calendar-backward-day).
C-n
Move point one week forward (calendar-forward-week).
C-p
Move point one week backward (calendar-backward-week).
M-}
Move point one month forward (calendar-forward-month).
M-{
Move point one month backward (calendar-backward-month).
C-x ]
Move point one year forward (calendar-forward-year).
C-x [
Move point one year backward (calendar-backward-year).
The day and week commands are natural analogues of the usual Emacs commands for moving by characters and by lines. Just as C-n usually moves to the same column in the following line, in Calendar mode it moves to the same day in the following week. And C-p moves to the same day in the previous week.

The arrow keys are equivalent to C-f, C-b, C-n and C-p, just as they normally are in other modes.

The commands for motion by months and years work like those for weeks, but move a larger distance. The month commands M-} and M-{ move forward or backward by an entire month's time. The year commands C-x ] and C-x [ move forward or backward a whole year.

The easiest way to remember these commands is to consider months and years analogous to paragraphs and pages of text, respectively. But the commands themselves are not quite analogous. The ordinary Emacs paragraph commands move to the beginning or end of a paragraph, whereas these month and year commands move by an entire month or an entire year, which usually involves skipping across the end of a month or year.

All these commands accept a numeric argument as a repeat count. For convenience, the digit keys and the minus sign specify numeric arguments in Calendar mode even without the Meta modifier. For example, 100 C-f moves point 100 days forward from its present location.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.1.2 Beginning or End of Week, Month or Year

A week (or month, or year) is not just a quantity of days; we think of weeks (months, years) as starting on particular dates. So Calendar mode provides commands to move to the beginning or end of a week, month or year:

C-a
Move point to start of week (calendar-beginning-of-week).
C-e
Move point to end of week (calendar-end-of-week).
M-a
Move point to start of month (calendar-beginning-of-month).
M-e
Move point to end of month (calendar-end-of-month).
M-<
Move point to start of year (calendar-beginning-of-year).
M->
Move point to end of year (calendar-end-of-year).
These commands also take numeric arguments as repeat counts, with the repeat count indicating how many weeks, months, or years to move backward or forward.

By default, weeks begin on Sunday. To make them begin on Monday instead, set the variable calendar-week-start-day to 1.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.1.3 Specified Dates

Calendar mode provides commands for moving to a particular date specified in various ways.

g d
Move point to specified date (calendar-goto-date).
o
Center calendar around specified month (calendar-other-month).
.
Move point to today's date (calendar-goto-today).
g d (calendar-goto-date) prompts for a year, a month, and a day of the month, and then moves to that date. Because the calendar includes all dates from the beginning of the current era, you must type the year in its entirety; that is, type `1990', not `90'.

o (calendar-other-month) prompts for a month and year, then centers the three-month calendar around that month.

You can return to today's date with . (calendar-goto-today).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.2 Scrolling in the Calendar

The calendar display scrolls automatically through time when you move out of the visible portion. You can also scroll it manually. Imagine that the calendar window contains a long strip of paper with the months on it. Scrolling the calendar means moving the strip horizontally, so that new months become visible in the window.

C-x <
Scroll calendar one month forward (scroll-calendar-left).
C-x >
Scroll calendar one month backward (scroll-calendar-right).
C-v

NEXT
Scroll calendar three months forward (scroll-calendar-left-three-months).
M-v

PRIOR
Scroll calendar three months backward (scroll-calendar-right-three-months).
The most basic calendar scroll commands scroll by one month at a time. This means that there are two months of overlap between the display before the command and the display after. C-x < scrolls the calendar contents one month to the left; that is, it moves the display forward in time. C-x > scrolls the contents to the right, which moves backwards in time.

The commands C-v and M-v scroll the calendar by an entire "screenful"---three months--in analogy with the usual meaning of these commands. C-v makes later dates visible and M-v makes earlier dates visible. These commands take a numeric argument as a repeat count; in particular, since C-u multiplies the next command by four, typing C-u C-v scrolls the calendar forward by a year and typing C-u M-v scrolls the calendar backward by a year.

The function keys NEXT and PRIOR are equivalent to C-v and M-v, just as they are in other modes.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.3 Counting Days

M-=
Display the number of days in the current region (calendar-count-days-region).
To determine the number of days in the region, type M-= (calendar-count-days-region). The numbers of days shown is inclusive; that is, it includes the days specified by mark and point.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.4 Miscellaneous Calendar Commands

p d
Display day-in-year (calendar-print-day-of-year).
C-c C-l
Regenerate the calendar window (redraw-calendar).
SPC
Scroll the next window (scroll-other-window).
q
Exit from calendar (exit-calendar).
To display the number of days elapsed since the start of the year, or the number of days remaining in the year, type the p d command (calendar-print-day-of-year). This displays both of those numbers in the echo area. The number of days elapsed includes the selected date. The number of days remaining does not include that date.

If the calendar window text gets corrupted, type C-c C-l (redraw-calendar) to redraw it. (This can only happen if you use non-Calendar-mode editing commands.)

In Calendar mode, you can use SPC (scroll-other-window) to scroll the other window. This is handy when you display a list of holidays or diary entries in another window.

To exit from the calendar, type q (exit-calendar). This buries all buffers related to the calendar, selecting other buffers. (If a frame contains a dedicated calendar window, exiting from the calendar iconifies that frame.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.5 LaTeX Calendar

The Calendar LaTeX commands produce a buffer of LaTeX code that prints as a calendar. Depending on the command you use, the printed calendar covers the day, week, month or year that point is in.

t m
Generate a one-month calendar (cal-tex-cursor-month).
t M
Generate a sideways-printing one-month calendar (cal-tex-cursor-month-landscape).
t d
Generate a one-day calendar (cal-tex-cursor-day).
t w 1
Generate a one-page calendar for one week (cal-tex-cursor-week).
t w 2
Generate a two-page calendar for one week (cal-tex-cursor-week2).
t w 3
Generate an ISO-style calendar for one week (cal-tex-cursor-week-iso).
t w 4
Generate a calendar for one Monday-starting week (cal-tex-cursor-week-monday).
t f w
Generate a Filofax-style two-weeks-at-a-glance calendar (cal-tex-cursor-filofax-2week).
t f W
Generate a Filofax-style one-week-at-a-glance calendar (cal-tex-cursor-filofax-week).
t y
Generate a calendar for one year (cal-tex-cursor-year).
t Y
Generate a sideways-printing calendar for one year (cal-tex-cursor-year-landscape).
t f y
Generate a Filofax-style calendar for one year (cal-tex-cursor-filofax-year).
Some of these commands print the calendar sideways (in "landscape mode"), so it can be wider than it is long. Some of them use Filofax paper size (3.75in x 6.75in). All of these commands accept a prefix argument which specifies how many days, weeks, months or years to print (starting always with the selected one).

If the variable cal-tex-holidays is non-nil (the default), then the printed calendars show the holidays in calendar-holidays. If the variable cal-tex-diary is non-nil (the default is nil), diary entries are included also (in weekly and monthly calendars only). If the variable cal-tex-rules is non-nil (the default is nil), the calendar displays ruled pages in styles that have sufficient room.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.6 Holidays

The Emacs calendar knows about all major and many minor holidays, and can display them.

h
Display holidays for the selected date (calendar-cursor-holidays).
Mouse-2 Holidays
Display any holidays for the date you click on.
x
Mark holidays in the calendar window (mark-calendar-holidays).
u
Unmark calendar window (calendar-unmark).
a
List all holidays for the displayed three months in another window (list-calendar-holidays).
M-x holidays
List all holidays for three months around today's date in another window.
M-x list-holidays
List holidays in another window for a specified range of years.
To see if any holidays fall on a given date, position point on that date in the calendar window and use the h command. Alternatively, click on that date with Mouse-2 and then choose Holidays from the menu that appears. Either way, this displays the holidays for that date, in the echo area if they fit there, otherwise in a separate window.

To view the distribution of holidays for all the dates shown in the calendar, use the x command. This displays the dates that are holidays in a different face (or places a `*' after these dates, if display with multiple faces is not available). The command applies both to the currently visible months and to other months that subsequently become visible by scrolling. To turn marking off and erase the current marks, type u, which also erases any diary marks (see section AC.10 The Diary).

To get even more detailed information, use the a command, which displays a separate buffer containing a list of all holidays in the current three-month range. You can use SPC in the calendar window to scroll that list.

The command M-x holidays displays the list of holidays for the current month and the preceding and succeeding months; this works even if you don't have a calendar window. If you want the list of holidays centered around a different month, use C-u M-x holidays, which prompts for the month and year.

The holidays known to Emacs include United States holidays and the major Christian, Jewish, and Islamic holidays; also the solstices and equinoxes.

The command M-x list-holidays displays the list of holidays for a range of years. This function asks you for the starting and stopping years, and allows you to choose all the holidays or one of several categories of holidays. You can use this command even if you don't have a calendar window.

The dates used by Emacs for holidays are based on current practice, not historical fact. Historically, for instance, the start of daylight savings time and even its existence have varied from year to year, but present United States law mandates that daylight savings time begins on the first Sunday in April. When the daylight savings rules are set up for the United States, Emacs always uses the present definition, even though it is wrong for some prior years.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.7 Times of Sunrise and Sunset

Special calendar commands can tell you, to within a minute or two, the times of sunrise and sunset for any date.

S
Display times of sunrise and sunset for the selected date (calendar-sunrise-sunset).
Mouse-2 Sunrise/sunset
Display times of sunrise and sunset for the date you click on.
M-x sunrise-sunset
Display times of sunrise and sunset for today's date.
C-u M-x sunrise-sunset
Display times of sunrise and sunset for a specified date.
Within the calendar, to display the local times of sunrise and sunset in the echo area, move point to the date you want, and type S. Alternatively, click Mouse-2 on the date, then choose `Sunrise/sunset' from the menu that appears. The command M-x sunrise-sunset is available outside the calendar to display this information for today's date or a specified date. To specify a date other than today, use C-u M-x sunrise-sunset, which prompts for the year, month, and day.

You can display the times of sunrise and sunset for any location and any date with C-u C-u M-x sunrise-sunset. This asks you for a longitude, latitude, number of minutes difference from Coordinated Universal Time, and date, and then tells you the times of sunrise and sunset for that location on that date.

Because the times of sunrise and sunset depend on the location on earth, you need to tell Emacs your latitude, longitude, and location name before using these commands. Here is an example of what to set:
(setq calendar-latitude 40.1)
(setq calendar-longitude -88.2)
(setq calendar-location-name "Urbana, IL")
Use one decimal place in the values of calendar-latitude and calendar-longitude.

Your time zone also affects the local time of sunrise and sunset. Emacs usually gets time zone information from the operating system, but if these values are not what you want (or if the operating system does not supply them), you must set them yourself. Here is an example:
(setq calendar-time-zone -360)
(setq calendar-standard-time-zone-name "CST")
(setq calendar-daylight-time-zone-name "CDT")
The value of calendar-time-zone is the number of minutes difference between your local standard time and Coordinated Universal Time (Greenwich time). The values of calendar-standard-time-zone-name and calendar-daylight-time-zone-name are the abbreviations used in your time zone. Emacs displays the times of sunrise and sunset corrected for daylight savings time. See section AC.12 Daylight Savings Time, for how daylight savings time is determined.

As a user, you might find it convenient to set the calendar location variables for your usual physical location in your `.emacs' file. And when you install Emacs on a machine, you can create a `default.el' file which sets them properly for the typical location of most users of that machine. See section AD.7 The Init File, `~/.emacs'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.8 Phases of the Moon

These calendar commands display the dates and times of the phases of the moon (new moon, first quarter, full moon, last quarter). This feature is useful for debugging problems that "depend on the phase of the moon."

M
Display the dates and times for all the quarters of the moon for the three-month period shown (calendar-phases-of-moon).
M-x phases-of-moon
Display dates and times of the quarters of the moon for three months around today's date.
Within the calendar, use the M command to display a separate buffer of the phases of the moon for the current three-month range. The dates and times listed are accurate to within a few minutes.

Outside the calendar, use the command M-x phases-of-moon to display the list of the phases of the moon for the current month and the preceding and succeeding months. For information about a different month, use C-u M-x phases-of-moon, which prompts for the month and year.

The dates and times given for the phases of the moon are given in local time (corrected for daylight savings, when appropriate); but if the variable calendar-time-zone is void, Coordinated Universal Time (the Greenwich time zone) is used. See section AC.12 Daylight Savings Time.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.9 Conversion To and From Other Calendars

The Emacs calendar displayed is always the Gregorian calendar, sometimes called the "new style" calendar, which is used in most of the world today. However, this calendar did not exist before the sixteenth century and was not widely used before the eighteenth century; it did not fully displace the Julian calendar and gain universal acceptance until the early twentieth century. The Emacs calendar can display any month since January, year 1 of the current era, but the calendar displayed is the Gregorian, even for a date at which the Gregorian calendar did not exist.

While Emacs cannot display other calendars, it can convert dates to and from several other calendars.

AC.9.1 Supported Calendar Systems

The calendars Emacs understands

(aside from Gregorian).

AC.9.2 Converting To Other Calendars

Converting the selected date to various calendars.

AC.9.3 Converting From Other Calendars

Moving to a date specified in another calendar.

AC.9.4 Converting from the Mayan Calendar

Moving to a date specified in a Mayan calendar.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.9.1 Supported Calendar Systems

The ISO commercial calendar is used largely in Europe.

The Julian calendar, named after Julius Caesar, was the one used in Europe throughout medieval times, and in many countries up until the nineteenth century.

Astronomers use a simple counting of days elapsed since noon, Monday, January 1, 4713 B.C. on the Julian calendar. The number of days elapsed is called the Julian day number or the Astronomical day number.

The Hebrew calendar is used by tradition in the Jewish religion. The Emacs calendar program uses the Hebrew calendar to determine the dates of Jewish holidays. Hebrew calendar dates begin and end at sunset.

The Islamic calendar is used in many predominantly Islamic countries. Emacs uses it to determine the dates of Islamic holidays. There is no universal agreement in the Islamic world about the calendar; Emacs uses a widely accepted version, but the precise dates of Islamic holidays often depend on proclamation by religious authorities, not on calculations. As a consequence, the actual dates of observance can vary slightly from the dates computed by Emacs. Islamic calendar dates begin and end at sunset.

The French Revolutionary calendar was created by the Jacobins after the 1789 revolution, to represent a more secular and nature-based view of the annual cycle, and to install a 10-day week in a rationalization measure similar to the metric system. The French government officially abandoned this calendar at the end of 1805.

The Maya of Central America used three separate, overlapping calendar systems, the long count, the tzolkin, and the haab. Emacs knows about all three of these calendars. Experts dispute the exact correlation between the Mayan calendar and our calendar; Emacs uses the Goodman-Martinez-Thompson correlation in its calculations.

The Copts use a calendar based on the ancient Egyptian solar calendar. Their calendar consists of twelve 30-day months followed by an extra five-day period. Once every fourth year they add a leap day to this extra period to make it six days. The Ethiopic calendar is identical in structure, but has different year numbers and month names.

The Persians use a solar calendar based on a design of Omar Khayyam. Their calendar consists of twelve months of which the first six have 31 days, the next five have 30 days, and the last has 29 in ordinary years and 30 in leap years. Leap years occur in a complicated pattern every four or five years.

The Chinese calendar is a complicated system of lunar months arranged into solar years. The years go in cycles of sixty, each year containing either twelve months in an ordinary year or thirteen months in a leap year; each month has either 29 or 30 days. Years, ordinary months, and days are named by combining one of ten "celestial stems" with one of twelve "terrestrial branches" for a total of sixty names that are repeated in a cycle of sixty.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.9.2 Converting To Other Calendars

The following commands describe the selected date (the date at point) in various other calendar systems:

Mouse-2 Other calendars
Display the date that you click on, expressed in various other calendars.
p c
Display ISO commercial calendar equivalent for selected day (calendar-print-iso-date).
p j
Display Julian date for selected day (calendar-print-julian-date).
p a
Display astronomical (Julian) day number for selected day (calendar-print-astro-day-number).
p h
Display Hebrew date for selected day (calendar-print-hebrew-date).
p i
Display Islamic date for selected day (calendar-print-islamic-date).
p f
Display French Revolutionary date for selected day (calendar-print-french-date).
p C
Display Chinese date for selected day (calendar-print-chinese-date).
p k
Display Coptic date for selected day (calendar-print-coptic-date).
p e
Display Ethiopic date for selected day (calendar-print-ethiopic-date).
p p
Display Persian date for selected day (calendar-print-persian-date).
p m
Display Mayan date for selected day (calendar-print-mayan-date).
If you are using X, the easiest way to translate a date into other calendars is to click on it with Mouse-2, then choose Other calendars from the menu that appears. This displays the equivalent forms of the date in all the calendars Emacs understands, in the form of a menu. (Choosing an alternative from this menu doesn't actually do anything--the menu is used only for display.)

Otherwise, move point to the date you want to convert, then type the appropriate command starting with p from the table above. The prefix p is a mnemonic for "print," since Emacs "prints" the equivalent date in the echo area.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.9.3 Converting From Other Calendars

You can use the other supported calendars to specify a date to move to. This section describes the commands for doing this using calendars other than Mayan; for the Mayan calendar, see the following section.

g c
Move to a date specified in the ISO commercial calendar (calendar-goto-iso-date).
g j
Move to a date specified in the Julian calendar (calendar-goto-julian-date).
g a
Move to a date specified with an astronomical (Julian) day number (calendar-goto-astro-day-number).
g h
Move to a date specified in the Hebrew calendar (calendar-goto-hebrew-date).
g i
Move to a date specified in the Islamic calendar (calendar-goto-islamic-date).
g f
Move to a date specified in the French Revolutionary calendar (calendar-goto-french-date).
g C
Move to a date specified in the Chinese calendar (calendar-goto-chinese-date).
g p
Move to a date specified in the Persian calendar (calendar-goto-persian-date).
g k
Move to a date specified in the Coptic calendar (calendar-goto-coptic-date).
g e
Move to a date specified in the Ethiopic calendar (calendar-goto-ethiopic-date).
These commands ask you for a date on the other calendar, move point to the Gregorian calendar date equivalent to that date, and display the other calendar's date in the echo area. Emacs uses strict completion (see section E.3 Completion) whenever it asks you to type a month name, so you don't have to worry about the spelling of Hebrew, Islamic, or French names.

One common question concerning the Hebrew calendar is the computation of the anniversary of a date of death, called a "yahrzeit." The Emacs calendar includes a facility for such calculations. If you are in the calendar, the command M-x list-yahrzeit-dates asks you for a range of years and then displays a list of the yahrzeit dates for those years for the date given by point. If you are not in the calendar, this command first asks you for the date of death and the range of years, and then displays the list of yahrzeit dates.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.9.4 Converting from the Mayan Calendar

Here are the commands to select dates based on the Mayan calendar:

g m l
Move to a date specified by the long count calendar (calendar-goto-mayan-long-count-date).
g m n t
Move to the next occurrence of a place in the tzolkin calendar (calendar-next-tzolkin-date).
g m p t
Move to the previous occurrence of a place in the tzolkin calendar (calendar-previous-tzolkin-date).
g m n h
Move to the next occurrence of a place in the haab calendar (calendar-next-haab-date).
g m p h
Move to the previous occurrence of a place in the haab calendar (calendar-previous-haab-date).
g m n c
Move to the next occurrence of a place in the calendar round (calendar-next-calendar-round-date).
g m p c
Move to the previous occurrence of a place in the calendar round (calendar-previous-calendar-round-date).
To understand these commands, you need to understand the Mayan calendars. The long count is a counting of days with these units:
1 kin = 1 day   1 uinal = 20 kin   1 tun = 18 uinal
1 katun = 20 tun   1 baktun = 20 katun
Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long count dates as early as 7.17.18.13.1, but no earlier. When you use the g m l command, type the Mayan long count date with the baktun, katun, tun, uinal, and kin separated by periods.

The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of independent cycles of 13 and 20 days. Since this cycle repeats endlessly, Emacs provides commands to move backward and forward to the previous or next point in the cycle. Type g m p t to go to the previous tzolkin date; Emacs asks you for a tzolkin date and moves point to the previous occurrence of that date. Similarly, type g m n t to go to the next occurrence of a tzolkin date.

The Mayan haab calendar is a cycle of 365 days arranged as 18 months of 20 days each, followed a 5-day monthless period. Like the tzolkin cycle, this cycle repeats endlessly, and there are commands to move backward and forward to the previous or next point in the cycle. Type g m p h to go to the previous haab date; Emacs asks you for a haab date and moves point to the previous occurrence of that date. Similarly, type g m n h to go to the next occurrence of a haab date.

The Maya also used the combination of the tzolkin date and the haab date. This combination is a cycle of about 52 years called a calendar round. If you type g m p c, Emacs asks you for both a haab and a tzolkin date and then moves point to the previous occurrence of that combination. Use g m n c to move point to the next occurrence of a combination. These commands signal an error if the haab/tzolkin date combination you have typed is impossible.

Emacs uses strict completion (see section E.3.3 Strict Completion) whenever it asks you to type a Mayan name, so you don't have to worry about spelling.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.10 The Diary

The Emacs diary keeps track of appointments or other events on a daily basis, in conjunction with the calendar. To use the diary feature, you must first create a diary file containing a list of events and their dates. Then Emacs can automatically pick out and display the events for today, for the immediate future, or for any specified date.

By default, Emacs uses `~/diary' as the diary file. This is the same file that the calendar utility uses. A sample `~/diary' file is:
12/22/1988  Twentieth wedding anniversary!!
&1/1.       Happy New Year!
10/22       Ruth's birthday.
* 21, *:    Payday
Tuesday--weekly meeting with grad students at 10am
         Supowit, Shen, Bitner, and Kapoor to attend.
1/13/89     Friday the thirteenth!!
&thu 4pm    squash game with Lloyd.
mar 16      Dad's birthday
April 15, 1989 Income tax due.
&* 15       time cards due.
This example uses extra spaces to align the event descriptions of most of the entries. Such formatting is purely a matter of taste.

Although you probably will start by creating a diary manually, Emacs provides a number of commands to let you view, add, and change diary entries.

AC.10.1 Commands Displaying Diary Entries

Viewing diary entries and associated calendar dates.

AC.10.2 The Diary File

Entering events in your diary.

AC.10.3 Date Formats

Various ways you can specify dates.

AC.10.4 Commands to Add to the Diary

Commands to create diary entries.

AC.10.5 Special Diary Entries

Anniversaries, blocks of dates, cyclic entries, etc.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.10.1 Commands Displaying Diary Entries

Once you have created a `~/diary' file, you can use the calendar to view it. You can also view today's events outside of Calendar mode.

d
Display all diary entries for the selected date (view-diary-entries).
Mouse-2 Diary
Display all diary entries for the date you click on.
s
Display the entire diary file (show-all-diary-entries).
m
Mark all visible dates that have diary entries (mark-diary-entries).
u
Unmark the calendar window (calendar-unmark).
M-x print-diary-entries
Print hard copy of the diary display as it appears.
M-x diary
Display all diary entries for today's date.
M-x diary-mail-entries
Mail yourself email reminders about upcoming diary entries.
Displaying the diary entries with d shows in a separate window the diary entries for the selected date in the calendar. The mode line of the new window shows the date of the diary entries and any holidays that fall on that date. If you specify a numeric argument with d, it shows all the diary entries for that many successive days. Thus, 2 d displays all the entries for the selected date and for the following day.

Another way to display the diary entries for a date is to click Mouse-2 on the date, and then choose Diary entries from the menu that appears.

To get a broader view of which days are mentioned in the diary, use the m command. This displays the dates that have diary entries in a different face (or places a `+' after these dates, if display with multiple faces is not available). The command applies both to the currently visible months and to other months that subsequently become visible by scrolling. To turn marking off and erase the current marks, type u, which also turns off holiday marks (see section AC.6 Holidays).

To see the full diary file, rather than just some of the entries, use the s command.

Display of selected diary entries uses the selective display feature to hide entries that don't apply.

The diary buffer as you see it is an illusion, so simply printing the buffer does not print what you see on your screen. There is a special command to print hard copy of the diary buffer as it appears; this command is M-x print-diary-entries. It sends the data directly to the printer. You can customize it like lpr-region (see section AC.18 Hardcopy Output).

The command M-x diary displays the diary entries for the current date, independently of the calendar display, and optionally for the next few days as well; the variable number-of-diary-entries specifies how many days to include. See section `Calendar' in The Emacs Lisp Reference Manual.

If you put (diary) in your `.emacs' file, this automatically displays a window with the day's diary entries, when you enter Emacs. The mode line of the displayed window shows the date and any holidays that fall on that date.

Many users like to receive notice of events in their diary as email. To send such mail to yourself, use the command M-x diary-mail-entries. A prefix argument specifies how many days (starting with today) to check; otherwise, the variable diary-mail-days says how many days.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.10.2 The Diary File

Your diary file is a file that records events associated with particular dates. The name of the diary file is specified by the variable diary-file; `~/diary' is the default. The calendar utility program supports a subset of the format allowed by the Emacs diary facilities, so you can use that utility to view the diary file, with reasonable results aside from the entries it cannot understand.

Each entry in the diary file describes one event and consists of one or more lines. An entry always begins with a date specification at the left margin. The rest of the entry is simply text to describe the event. If the entry has more than one line, then the lines after the first must begin with whitespace to indicate they continue a previous entry. Lines that do not begin with valid dates and do not continue a preceding entry are ignored.

You can inhibit the marking of certain diary entries in the calendar window; to do this, insert an ampersand (`&') at the beginning of the entry, before the date. This has no effect on display of the entry in the diary window; it affects only marks on dates in the calendar window. Nonmarking entries are especially useful for generic entries that would otherwise mark many different dates.

If the first line of a diary entry consists only of the date or day name with no following blanks or punctuation, then the diary window display doesn't include that line; only the continuation lines appear. For example, this entry:
02/11/1989
      Bill B. visits Princeton today
      2pm Cognitive Studies Committee meeting
      2:30-5:30 Liz at Lawrenceville
      4:00pm Dentist appt
      7:30pm Dinner at George's
      8:00-10:00pm concert
appears in the diary window without the date line at the beginning. This style of entry looks neater when you display just a single day's entries, but can cause confusion if you ask for more than one day's entries.

You can edit the diary entries as they appear in the window, but it is important to remember that the buffer displayed contains the entire diary file, with portions of it concealed from view. This means, for instance, that the C-f (forward-char) command can put point at what appears to be the end of the line, but what is in reality the middle of some concealed line.

Be careful when editing the diary entries! Inserting additional lines or adding/deleting characters in the middle of a visible line cannot cause problems, but editing at the end of a line may not do what you expect. Deleting a line may delete other invisible entries that follow it. Before editing the diary, it is best to display the entire file with s (show-all-diary-entries).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.10.3 Date Formats

Here are some sample diary entries, illustrating different ways of formatting a date. The examples all show dates in American order (month, day, year), but Calendar mode supports European order (day, month, year) as an option.
4/20/93  Switch-over to new tabulation system
apr. 25  Start tabulating annual results
4/30  Results for April are due
*/25  Monthly cycle finishes
Friday  Don't leave without backing up files
The first entry appears only once, on April 20, 1993. The second and third appear every year on the specified dates, and the fourth uses a wildcard (asterisk) for the month, so it appears on the 25th of every month. The final entry appears every week on Friday.

You can use just numbers to express a date, as in `month/day' or `month/day/year'. This must be followed by a nondigit. In the date itself, month and day are numbers of one or two digits. The optional year is also a number, and may be abbreviated to the last two digits; that is, you can use `11/12/1989' or `11/12/89'.

Dates can also have the form `monthname day' or `monthname day, year', where the month's name can be spelled in full or abbreviated to three characters (with or without a period). Case is not significant.

A date may be generic; that is, partially unspecified. Then the entry applies to all dates that match the specification. If the date does not contain a year, it is generic and applies to any year. Alternatively, month, day, or year can be a `*'; this matches any month, day, or year, respectively. Thus, a diary entry `3/*/*' matches any day in March of any year; so does `march *'.

If you prefer the European style of writing dates--in which the day comes before the month--type M-x european-calendar while in the calendar, or set the variable european-calendar-style to t before using any calendar or diary command. This mode interprets all dates in the diary in the European manner, and also uses European style for displaying diary dates. (Note that there is no comma after the monthname in the European style.) To go back to the (default) American style of writing dates, type M-x american-calendar.

You can use the name of a day of the week as a generic date which applies to any date falling on that day of the week. You can abbreviate the day of the week to three letters (with or without a period) or spell it in full; case is not significant.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.10.4 Commands to Add to the Diary

While in the calendar, there are several commands to create diary entries:

i d
Add a diary entry for the selected date (insert-diary-entry).
i w
Add a diary entry for the selected day of the week (insert-weekly-diary-entry).
i m
Add a diary entry for the selected day of the month (insert-monthly-diary-entry).
i y
Add a diary entry for the selected day of the year (insert-yearly-diary-entry).
You can make a diary entry for a specific date by selecting that date in the calendar window and typing the i d command. This command displays the end of your diary file in another window and inserts the date; you can then type the rest of the diary entry.

If you want to make a diary entry that applies to a specific day of the week, select that day of the week (any occurrence will do) and type i w. This inserts the day-of-week as a generic date; you can then type the rest of the diary entry. You can make a monthly diary entry in the same fashion: select the day of the month, use the i m command, and type the rest of the entry. Similarly, you can insert a yearly diary entry with the i y command.

All of the above commands make marking diary entries by default. To make a nonmarking diary entry, give a numeric argument to the command. For example, C-u i w makes a nonmarking weekly diary entry.

When you modify the diary file, be sure to save the file before exiting Emacs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.10.5 Special Diary Entries

In addition to entries based on calendar dates, the diary file can contain sexp entries for regular events such as anniversaries. These entries are based on Lisp expressions (sexps) that Emacs evaluates as it scans the diary file. Instead of a date, a sexp entry contains `%%' followed by a Lisp expression which must begin and end with parentheses. The Lisp expression determines which dates the entry applies to.

Calendar mode provides commands to insert certain commonly used sexp entries:

i a
Add an anniversary diary entry for the selected date (insert-anniversary-diary-entry).
i b
Add a block diary entry for the current region (insert-block-diary-entry).
i c
Add a cyclic diary entry starting at the date (insert-cyclic-diary-entry).
If you want to make a diary entry that applies to the anniversary of a specific date, move point to that date and use the i a command. This displays the end of your diary file in another window and inserts the anniversary description; you can then type the rest of the diary entry. The entry looks like this:
%%(diary-anniversary 10 31 1948) Arthur's birthday
This entry applies to October 31 in any year after 1948; `10 31 1948' specifies the date. (If you are using the European calendar style, the month and day are interchanged.) The reason this expression requires a beginning year is that advanced diary functions can use it to calculate the number of elapsed years.

A block diary entry applies to a specified range of consecutive dates. Here is a block diary entry that applies to all dates from June 24, 1990 through July 10, 1990:
%%(diary-block 6 24 1990 7 10 1990) Vacation
The `6 24 1990' indicates the starting date and the `7 10 1990' indicates the stopping date. (Again, if you are using the European calendar style, the month and day are interchanged.)

To insert a block entry, place point and the mark on the two dates that begin and end the range, and type i b. This command displays the end of your diary file in another window and inserts the block description; you can then type the diary entry.

Cyclic diary entries repeat after a fixed interval of days. To create one, select the starting date and use the i c command. The command prompts for the length of interval, then inserts the entry, which looks like this:
%%(diary-cyclic 50 3 1 1990) Renew medication
This entry applies to March 1, 1990 and every 50th day following; `3 1 1990' specifies the starting date. (If you are using the European calendar style, the month and day are interchanged.)

All three of these commands make marking diary entries. To insert a nonmarking entry, give a numeric argument to the command. For example, C-u i a makes a nonmarking anniversary diary entry.

Marking sexp diary entries in the calendar is extremely time-consuming, since every date visible in the calendar window must be individually checked. So it's a good idea to make sexp diary entries nonmarking (with `&') when possible.

Another sophisticated kind of sexp entry, a floating diary entry, specifies a regularly occurring event by offsets specified in days, weeks, and months. It is comparable to a crontab entry interpreted by the cron utility. Here is a nonmarking, floating diary entry that applies to the last Thursday in November:
&%%(diary-float 11 4 -1) American Thanksgiving
The 11 specifies November (the eleventh month), the 4 specifies Thursday (the fourth day of the week, where Sunday is numbered zero), and the -1 specifies "last" (1 would mean "first," 2 would mean "second," -2 would mean "second-to-last," and so on). The month can be a single month or a list of months. Thus you could change the 11 above to `'(1 2 3)' and have the entry apply to the last Thursday of January, February, and March. If the month is t, the entry applies to all months of the year.

Most generally, sexp diary entries can perform arbitrary computations to determine when they apply. See section `Sexp Diary Entries' in The Emacs Lisp Reference Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.11 Appointments

If you have a diary entry for an appointment, and that diary entry begins with a recognizable time of day, Emacs can warn you several minutes beforehand that that appointment is pending. Emacs alerts you to the appointment by displaying a message in the mode line.

To enable appointment notification, you must enable the time display feature of Emacs, M-x display-time (see section B.3 The Mode Line). You must also add the function appt-make-list to the diary-hook, like this:
(add-hook 'diary-hook 'appt-make-list)
Adding this text to your `.emacs' file does the whole job:
(display-time)
(add-hook 'diary-hook 'appt-make-list)
(diary 0)
With these preparations done, when you display the diary (either with the d command in the calendar window or with the M-x diary command), it sets up an appointment list of all the diary entries found with recognizable times of day, and reminds you just before each of them.

For example, suppose the diary file contains these lines:
Monday
  9:30am Coffee break
 12:00pm Lunch
Then on Mondays, after you have displayed the diary, you will be reminded at 9:20am about your coffee break and at 11:50am about lunch.

You can write times in am/pm style (with `12:00am' standing for midnight and `12:00pm' standing for noon), or 24-hour European/military style. You need not be consistent; your diary file can have a mixture of the two styles.

Emacs updates the appointments list automatically just after midnight. This also displays the next day's diary entries in the diary buffer, unless you set appt-display-diary to nil.

You can also use the appointment notification facility like an alarm clock. The command M-x appt-add adds entries to the appointment list without affecting your diary file. You delete entries from the appointment list with M-x appt-delete.

You can turn off the appointment notification feature at any time by setting appt-issue-message to nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.12 Daylight Savings Time

Emacs understands the difference between standard time and daylight savings time--the times given for sunrise, sunset, solstices, equinoxes, and the phases of the moon take that into account. The rules for daylight savings time vary from place to place and have also varied historically from year to year. To do the job properly, Emacs needs to know which rules to use.

Some operating systems keep track of the rules that apply to the place where you are; on these systems, Emacs gets the information it needs from the system automatically. If some or all of this information is missing, Emacs fills in the gaps with the rules currently used in Cambridge, Massachusetts. If the resulting rules are not what you want, you can tell Emacs the rules to use by setting certain variables: calendar-daylight-savings-starts and calendar-daylight-savings-ends.

These values should be Lisp expressions that refer to the variable year, and evaluate to the Gregorian date on which daylight savings time starts or (respectively) ends, in the form of a list (month day year). The values should be nil if your area does not use daylight savings time.

Emacs uses these expressions to determine the starting date of daylight savings time for the holiday list and for correcting times of day in the solar and lunar calculations.

The values for Cambridge, Massachusetts are as follows:
(calendar-nth-named-day 1 0 4 year)
(calendar-nth-named-day -1 0 10 year)
That is, the first 0th day (Sunday) of the fourth month (April) in the year specified by year, and the last Sunday of the tenth month (October) of that year. If daylight savings time were changed to start on October 1, you would set calendar-daylight-savings-starts to this:
(list 10 1 year)
If there is no daylight savings time at your location, or if you want all times in standard time, set calendar-daylight-savings-starts and calendar-daylight-savings-ends to nil.

The variable calendar-daylight-time-offset specifies the difference between daylight savings time and standard time, measured in minutes. The value for Cambridge, Massachusetts is 60.

The two variables calendar-daylight-savings-starts-time and calendar-daylight-savings-ends-time specify the number of minutes after midnight local time when the transition to and from daylight savings time should occur. For Cambridge, Massachusetts both variables' values are 120.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.13 Summing Time Intervals

The timeclock feature adds up time intervals, so you can (for instance) keep track of how much time you spend working.

Use the M-x timeclock-in command when you start working on a project, and M-x timeclock-out command when you're done. Each time you do this, it adds one time interval to the record of the project.

Once you've collected data from a number of time intervals, you can use M-x timeclock-workday-remaining to see how much time is left to work today (assuming a typical average of 8 hours a day), and M-x timeclock-when-to-leave which will calculate when you're "done."

If you want Emacs to display the amount of time "left" of your workday in the mode line, either customize the timeclock-modeline-display variable and set its value to t, or invoke the M-x timeclock-modeline-display command.

Terminating the current Emacs session might or might not mean that you have stopped working on the project. If you'd like Emacs to ask you about this, set the value of the variable timeclock-ask-before-exiting to t (via M-x customize). By default, only an explicit M-x timeclock-out tells Emacs that the current interval is over.

The timeclock functions work by accumulating the data in a file called `.timelog' in your home directory. (On MS-DOS, this file is called `_timelog', since an initial period is not allowed in file names on MS-DOS.) You can specify a different name for this file by customizing the variable timeclock-file. If you edit the timeclock file manually, or if you change the value of any of timeclock's customizable variables, you should run the command M-x timeclock-reread-log to update the data in Emacs from the file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.14 Gnus

Gnus is an Emacs package primarily designed for reading and posting Usenet news. It can also be used to read and respond to messages from a number of other sources--mail, remote directories, digests, and so on.

Here we introduce Gnus and describe several basic features. For full details, see section `Top' in The Gnus Manual.

To start Gnus, type M-x gnus RET.

AC.14.1 Gnus Buffers

The group, summary, and article buffers.

AC.14.2 When Gnus Starts Up

What you should know about starting Gnus.

AC.14.3 Summary of Gnus Commands

A short description of the basic Gnus commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.14.1 Gnus Buffers

As opposed to most normal Emacs packages, Gnus uses a number of different buffers to display information and to receive commands. The three buffers users spend most of their time in are the group buffer, the summary buffer and the article buffer.

The group buffer contains a list of groups. This is the first buffer Gnus displays when it starts up. It normally displays only the groups to which you subscribe and that contain unread articles. Use this buffer to select a specific group.

The summary buffer lists one line for each article in a single group. By default, the author, the subject and the line number are displayed for each article, but this is customizable, like most aspects of Gnus display. The summary buffer is created when you select a group in the group buffer, and is killed when you exit the group. Use this buffer to select an article.

The article buffer displays the article. In normal Gnus usage, you don't select this buffer--all useful article-oriented commands work in the summary buffer. But you can select the article buffer, and execute all Gnus commands from that buffer, if you want to.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.14.2 When Gnus Starts Up

At startup, Gnus reads your `.newsrc' news initialization file and attempts to communicate with the local news server, which is a repository of news articles. The news server need not be the same computer you are logged in on.

If you start Gnus and connect to the server, but do not see any newsgroups listed in the group buffer, type L or A k to get a listing of all the groups. Then type u to toggle subscription to groups.

The first time you start Gnus, Gnus subscribes you to a few selected groups. All other groups start out as killed groups for you; you can list them with A k. All new groups that subsequently come to exist at the news server become zombie groups for you; type A z to list them. You can subscribe to a group shown in these lists using the u command.

When you quit Gnus with q, it automatically records in your `.newsrc' and `.newsrc.eld' initialization files the subscribed or unsubscribed status of all groups. You should normally not edit these files manually, but you may if you know how.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.14.3 Summary of Gnus Commands

Reading news is a two-step process:

Choose a group in the group buffer.

Select articles from the summary buffer. Each article selected is displayed in the article buffer in a large window, below the summary buffer in its small window.

Each Gnus buffer has its own special commands; however, the meanings of any given key in the various Gnus buffers are usually analogous, even if not identical. Here are commands for the group and summary buffers:

q
In the group buffer, update your `.newsrc' initialization file and quit Gnus.
In the summary buffer, exit the current group and return to the group buffer. Thus, typing q twice quits Gnus.

L
In the group buffer, list all the groups available on your news server (except those you have killed). This may be a long list!

l
In the group buffer, list only the groups to which you subscribe and which contain unread articles.

u
In the group buffer, unsubscribe from (or subscribe to) the group listed in the line that point is on. When you quit Gnus by typing q, Gnus lists in your `.newsrc' file which groups you have subscribed to. The next time you start Gnus, you won't see this group, because Gnus normally displays only subscribed-to groups.

C-k
In the group buffer, "kill" the current line's group--don't even list it in `.newsrc' from now on. This affects future Gnus sessions as well as the present session.
When you quit Gnus by typing q, Gnus writes information in the file `.newsrc' describing all newsgroups except those you have "killed."

SPC
In the group buffer, select the group on the line under the cursor and display the first unread article in that group.
In the summary buffer,

Select the article on the line under the cursor if none is selected.

Scroll the text of the selected article (if there is one).

Select the next unread article if at the end of the current article.

Thus, you can move through all the articles by repeatedly typing SPC.

DEL
In the group buffer, move point to the previous group containing unread articles.
In the summary buffer, scroll the text of the article backwards.

n
Move point to the next unread group, or select the next unread article.

p
Move point to the previous unread group, or select the previous unread article.

C-n

C-p
Move point to the next or previous item, even if it is marked as read. This does not select the article or group on that line.

s
In the summary buffer, do an incremental search of the current text in the article buffer, just as if you switched to the article buffer and typed C-s.

M-s regexp RET
In the summary buffer, search forward for articles containing a match for regexp.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15 Running Shell Commands from Emacs

Emacs has commands for passing single command lines to inferior shell processes; it can also run a shell interactively with input and output to an Emacs buffer named `*shell*' or run a shell inside a terminal emulator window.

There is a shell implemented entirely in Emacs, documented in a separate manual. See section `Eshell' in Eshell: The Emacs Shell.

M-! cmd RET
Run the shell command line cmd and display the output (shell-command).
M-| cmd RET
Run the shell command line cmd with region contents as input; optionally replace the region with the output (shell-command-on-region).
M-x shell
Run a subshell with input and output through an Emacs buffer. You can then give commands interactively.
M-x term
Run a subshell with input and output through an Emacs buffer. You can then give commands interactively. Full terminal emulation is available.
M-x eshell
Start the Emacs shell.

AC.15.1 Single Shell Commands

How to run one shell command and return.

AC.15.2 Interactive Inferior Shell

Permanent shell taking input via Emacs.

AC.15.3 Shell Mode

Special Emacs commands used with permanent shell.

AC.15.4 Shell Command History

Repeating previous commands in a shell buffer.

AC.15.5 Directory Tracking

Keeping track when the subshell changes directory.

AC.15.6 Shell Mode Options

Options for customizing Shell mode.

AC.15.7 Emacs Terminal Emulator

An Emacs window as a terminal emulator.

AC.15.8 Term Mode

Special Emacs commands used in Term mode.

AC.15.9 Page-At-A-Time Output

Paging in the terminal emulator.

AC.15.10 Remote Host Shell

Connecting to another computer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.1 Single Shell Commands

M-! (shell-command) reads a line of text using the minibuffer and executes it as a shell command in a subshell made just for that command. Standard input for the command comes from the null device. If the shell command produces any output, the output appears either in the echo area (if it is short), or in an Emacs buffer named `*Shell Command Output*', which is displayed in another window but not selected (if the output is long).

For instance, one way to decompress a file `foo.gz' from Emacs is to type M-! gunzip foo.gz RET. That shell command normally creates the file `foo' and produces no terminal output.

A numeric argument, as in M-1 M-!, says to insert terminal output into the current buffer instead of a separate buffer. It puts point before the output, and sets the mark after the output. For instance, M-1 M-! gunzip < foo.gz RET would insert the uncompressed equivalent of `foo.gz' into the current buffer.

If the shell command line ends in `&', it runs asynchronously. For a synchronous shell command, shell-command returns the command's exit status (0 means success), when it is called from a Lisp program. You do not get any status information for an asynchronous command, since it hasn't finished yet.

M-| (shell-command-on-region) is like M-! but passes the contents of the region as the standard input to the shell command, instead of no input. If a numeric argument is used, meaning insert the output in the current buffer, then the old region is deleted first and the output replaces it as the contents of the region. It returns the command's exit status when it is called from a Lisp program.

One use for M-| is to run uudecode. For instance, if the buffer contains uuencoded text, type C-x h M-| uudecode RET to feed the entire buffer contents to the uudecode program. That program will ignore everything except the encoded text, and will store the decoded output into the file whose name is specified in the encoded text.

Both M-! and M-| use shell-file-name to specify the shell to use. This variable is initialized based on your SHELL environment variable when Emacs is started. If the file name does not specify a directory, the directories in the list exec-path are searched; this list is initialized based on the environment variable PATH when Emacs is started. Your `.emacs' file can override either or both of these default initializations.

Both M-! and M-| wait for the shell command to complete. To stop waiting, type C-g to quit; that terminates the shell command with the signal SIGINT---the same signal that C-c normally generates in the shell. Emacs waits until the command actually terminates. If the shell command doesn't stop (because it ignores the SIGINT signal), type C-g again; this sends the command a SIGKILL signal which is impossible to ignore.

To specify a coding system for M-! or M-|, use the command C-x RET c immediately beforehand. See section Q.9 Specifying a Coding System.

Error output from the command is normally intermixed with the regular output. If you set the variable shell-command-default-error-buffer to a string, which is a buffer name, error output is inserted before point in the buffer of that name.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.2 Interactive Inferior Shell

To run a subshell interactively, putting its typescript in an Emacs buffer, use M-x shell. This creates (or reuses) a buffer named `*shell*' and runs a subshell with input coming from and output going to that buffer. That is to say, any "terminal output" from the subshell goes into the buffer, advancing point, and any "terminal input" for the subshell comes from text in the buffer. To give input to the subshell, go to the end of the buffer and type the input, terminated by RET.

Emacs does not wait for the subshell to do anything. You can switch windows or buffers and edit them while the shell is waiting, or while it is running a command. Output from the subshell waits until Emacs has time to process it; this happens whenever Emacs is waiting for keyboard input or for time to elapse.

Input lines, once you submit them, are displayed using the face comint-highlight-input, and prompts are displayed using the face comint-highlight-prompt. This makes it easier to see previous input lines in the buffer. See section J.1 Using Multiple Typefaces.

To make multiple subshells, you can invoke M-x shell with a prefix argument (e.g. C-u M-x shell), which will read a buffer name and create (or reuse) a subshell in that buffer. You can also rename the `*shell*' buffer using M-x rename-uniquely, then create a new `*shell*' buffer using plain M-x shell. All the subshells in different buffers run independently and in parallel.

The file name used to load the subshell is the value of the variable explicit-shell-file-name, if that is non-nil. Otherwise, the environment variable ESHELL is used, or the environment variable SHELL if there is no ESHELL. If the file name specified is relative, the directories in the list exec-path are searched; this list is initialized based on the environment variable PATH when Emacs is started. Your `.emacs' file can override either or both of these default initializations.

Emacs sends the new shell the contents of the file `~/.emacs_shellname' as input, if it exists, where shellname is the name of the file that the shell was loaded from. For example, if you use bash, the file sent to it is `~/.emacs_bash'.

To specify a coding system for the shell, you can use the command C-x RET c immediately before M-x shell. You can also specify a coding system after starting the shell by using C-x RET p in the shell buffer. See section Q.9 Specifying a Coding System.

Unless the environment variable EMACS is already defined, Emacs defines it in the subshell, with value t. A shell script can check this variable to determine whether it has been run from an Emacs subshell.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.3 Shell Mode

Shell buffers use Shell mode, which defines several special keys attached to the C-c prefix. They are chosen to resemble the usual editing and job control characters present in shells that are not under Emacs, except that you must type C-c first. Here is a complete list of the special key bindings of Shell mode:

RET
At end of buffer send line as input; otherwise, copy current line to end of buffer and send it (comint-send-input). When a line is copied, any prompt at the beginning of the line (text output by programs preceding your input) is omitted. (See also the variable comint-use-prompt-regexp-instead-of-fields.)

TAB
Complete the command name or file name before point in the shell buffer (comint-dynamic-complete). TAB also completes history references (see section AC.15.4.3 Shell History References) and environment variable names.
The variable shell-completion-fignore specifies a list of file name extensions to ignore in Shell mode completion. The default setting is nil, but some users prefer ("~" "#" "%") to ignore file names ending in `~', `#' or `%'. Other related Comint modes use the variable comint-completion-fignore instead.

M-?
Display temporarily a list of the possible completions of the file name before point in the shell buffer (comint-dynamic-list-filename-completions).

C-d
Either delete a character or send EOF (comint-delchar-or-maybe-eof). Typed at the end of the shell buffer, C-d sends EOF to the subshell. Typed at any other position in the buffer, C-d deletes a character as usual.

C-c C-a
Move to the beginning of the line, but after the prompt if any (comint-bol-or-process-mark). If you repeat this command twice in a row, the second time it moves back to the process mark, which is the beginning of the input that you have not yet sent to the subshell. (Normally that is the same place--the end of the prompt on this line--but after C-c SPC the process mark may be in a previous line.)

C-c SPC
Accumulate multiple lines of input, then send them together. This command inserts a newline before point, but does not send the preceding text as input to the subshell--at least, not yet. Both lines, the one before this newline and the one after, will be sent together (along with the newline that separates them), when you type RET.

C-c C-u
Kill all text pending at end of buffer to be sent as input (comint-kill-input).

C-c C-w
Kill a word before point (backward-kill-word).

C-c C-c
Interrupt the shell or its current subjob if any (comint-interrupt-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.

C-c C-z
Stop the shell or its current subjob if any (comint-stop-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.

C-c C-\
Send quit signal to the shell or its current subjob if any (comint-quit-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.

C-c C-o
Delete the last batch of output from a shell command (comint-delete-output). This is useful if a shell command spews out lots of output that just gets in the way. This command used to be called comint-kill-output.

C-c C-s
Write the last batch of output from a shell command to a file (comint-write-output). With a prefix argument, the file is appended to instead. Any prompt at the end of the output is not written.

C-c C-r

C-M-l
Scroll to display the beginning of the last batch of output at the top of the window; also move the cursor there (comint-show-output).

C-c C-e
Scroll to put the end of the buffer at the bottom of the window (comint-show-maximum-output).

C-c C-f
Move forward across one shell command, but not beyond the current line (shell-forward-command). The variable shell-command-regexp specifies how to recognize the end of a command.

C-c C-b
Move backward across one shell command, but not beyond the current line (shell-backward-command).

C-c C-l
Display the buffer's history of shell commands in another window (comint-dynamic-list-input-ring).

M-x dirs
Ask the shell what its current directory is, so that Emacs can agree with the shell.

M-x send-invisible RET text RET
Send text as input to the shell, after reading it without echoing. This is useful when a shell command runs a program that asks for a password.
Alternatively, you can arrange for Emacs to notice password prompts and turn off echoing for them, as follows:
(add-hook 'comint-output-filter-functions
          'comint-watch-for-password-prompt)
M-x comint-continue-subjob
Continue the shell process. This is useful if you accidentally suspend the shell process.(14)

M-x comint-strip-ctrl-m
Discard all control-M characters from the current group of shell output. The most convenient way to use this command is to make it run automatically when you get output from the subshell. To do that, evaluate this Lisp expression:
(add-hook 'comint-output-filter-functions
          'comint-strip-ctrl-m)
M-x comint-truncate-buffer
This command truncates the shell buffer to a certain maximum number of lines, specified by the variable comint-buffer-maximum-size. Here's how to do this automatically each time you get output from the subshell:
(add-hook 'comint-output-filter-functions
          'comint-truncate-buffer)
Shell mode also customizes the paragraph commands so that only shell prompts start new paragraphs. Thus, a paragraph consists of an input command plus the output that follows it in the buffer.

Shell mode is a derivative of Comint mode, a general-purpose mode for communicating with interactive subprocesses. Most of the features of Shell mode actually come from Comint mode, as you can see from the command names listed above. The special features of Shell mode include the directory tracking feature, and a few user commands.

Other Emacs features that use variants of Comint mode include GUD (see section V.5 Running Debuggers Under Emacs) and M-x run-lisp (see section V.10 Running an External Lisp).

You can use M-x comint-run to execute any program of your choice in a subprocess using unmodified Comint mode--without the specializations of Shell mode.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.4 Shell Command History

Shell buffers support three ways of repeating earlier commands. You can use the same keys used in the minibuffer; these work much as they do in the minibuffer, inserting text from prior commands while point remains always at the end of the buffer. You can move through the buffer to previous inputs in their original place, then resubmit them or copy them to the end. Or you can use a `!'-style history reference.

AC.15.4.1 Shell History Ring

Fetching commands from the history list.

AC.15.4.2 Shell History Copying

Moving to a command and then copying it.

AC.15.4.3 Shell History References

Expanding `!'-style history references.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.4.1 Shell History Ring

M-p
Fetch the next earlier old shell command.

M-n
Fetch the next later old shell command.

M-r regexp RET

M-s regexp RET
Search backwards or forwards for old shell commands that match regexp.

C-c C-x (Shell mode)
Fetch the next subsequent command from the history.
Shell buffers provide a history of previously entered shell commands. To reuse shell commands from the history, use the editing commands M-p, M-n, M-r and M-s. These work just like the minibuffer history commands except that they operate on the text at the end of the shell buffer, where you would normally insert text to send to the shell.

M-p fetches an earlier shell command to the end of the shell buffer. Successive use of M-p fetches successively earlier shell commands, each replacing any text that was already present as potential shell input. M-n does likewise except that it finds successively more recent shell commands from the buffer.

The history search commands M-r and M-s read a regular expression and search through the history for a matching command. Aside from the choice of which command to fetch, they work just like M-p and M-n. If you enter an empty regexp, these commands reuse the same regexp used last time.

When you find the previous input you want, you can resubmit it by typing RET, or you can edit it first and then resubmit it if you wish.

Often it is useful to reexecute several successive shell commands that were previously executed in sequence. To do this, first find and reexecute the first command of the sequence. Then type C-c C-x; that will fetch the following command--the one that follows the command you just repeated. Then type RET to reexecute this command. You can reexecute several successive commands by typing C-c C-x RET over and over.

These commands get the text of previous shell commands from a special history list, not from the shell buffer itself. Thus, editing the shell buffer, or even killing large parts of it, does not affect the history that these commands access.

Some shells store their command histories in files so that you can refer to previous commands from previous shell sessions. Emacs reads the command history file for your chosen shell, to initialize its own command history. The file name is `~/.bash_history' for bash, `~/.sh_history' for ksh, and `~/.history' for other shells.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.4.2 Shell History Copying

C-c C-p
Move point to the previous prompt (comint-previous-prompt).

C-c C-n
Move point to the following prompt (comint-next-prompt).

C-c RET
Copy the input command which point is in, inserting the copy at the end of the buffer (comint-copy-old-input). This is useful if you move point back to a previous command. After you copy the command, you can submit the copy as input with RET. If you wish, you can edit the copy before resubmitting it.
Moving to a previous input and then copying it with C-c RET produces the same results--the same buffer contents--that you would get by using M-p enough times to fetch that previous input from the history list. However, C-c RET copies the text from the buffer, which can be different from what is in the history list if you edit the input text in the buffer after it has been sent.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.4.3 Shell History References

Various shells including csh and bash support history references that begin with `!' and `^'. Shell mode recognizes these constructs, and can perform the history substitution for you.

If you insert a history reference and type TAB, this searches the input history for a matching command, performs substitution if necessary, and places the result in the buffer in place of the history reference. For example, you can fetch the most recent command beginning with `mv' with ! m v TAB. You can edit the command if you wish, and then resubmit the command to the shell by typing RET.

Shell mode can optionally expand history references in the buffer when you send them to the shell. To request this, set the variable comint-input-autoexpand to input. You can make SPC perform history expansion by binding SPC to the command comint-magic-space.

Shell mode recognizes history references when they follow a prompt. Normally, any text output by a program at the beginning of an input line is considered a prompt. However, if the variable comint-use-prompt-regexp-instead-of-fields is non-nil, then Comint mode uses a regular expression to recognize prompts. In general, the variable comint-prompt-regexp specifies the regular expression; Shell mode uses the variable shell-prompt-pattern to set up comint-prompt-regexp in the shell buffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.5 Directory Tracking

Shell mode keeps track of `cd', `pushd' and `popd' commands given to the inferior shell, so it can keep the `*shell*' buffer's default directory the same as the shell's working directory. It recognizes these commands syntactically, by examining lines of input that are sent.

If you use aliases for these commands, you can tell Emacs to recognize them also. For example, if the value of the variable shell-pushd-regexp matches the beginning of a shell command line, that line is regarded as a pushd command. Change this variable when you add aliases for `pushd'. Likewise, shell-popd-regexp and shell-cd-regexp are used to recognize commands with the meaning of `popd' and `cd'. These commands are recognized only at the beginning of a shell command line.

If Emacs gets confused about changes in the current directory of the subshell, use the command M-x dirs to ask the shell what its current directory is. This command works for shells that support the most common command syntax; it may not work for unusual shells.

You can also use M-x dirtrack-mode to enable (or disable) an alternative and more aggressive method of tracking changes in the current directory.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.6 Shell Mode Options

If the variable comint-scroll-to-bottom-on-input is non-nil, insertion and yank commands scroll the selected window to the bottom before inserting.

If comint-scroll-show-maximum-output is non-nil, then scrolling due to the arrival of output tries to place the last line of text at the bottom line of the window, so as to show as much useful text as possible. (This mimics the scrolling behavior of many terminals.) The default is nil.

By setting comint-scroll-to-bottom-on-output, you can opt for having point jump to the end of the buffer whenever output arrives--no matter where in the buffer point was before. If the value is this, point jumps in the selected window. If the value is all, point jumps in each window that shows the Comint buffer. If the value is other, point jumps in all nonselected windows that show the current buffer. The default value is nil, which means point does not jump to the end.

The variable comint-input-ignoredups controls whether successive identical inputs are stored in the input history. A non-nil value means to omit an input that is the same as the previous input. The default is nil, which means to store each input even if it is equal to the previous input.

Three variables customize file name completion. The variable comint-completion-addsuffix controls whether completion inserts a space or a slash to indicate a fully completed file or directory name (non-nil means do insert a space or slash). comint-completion-recexact, if non-nil, directs TAB to choose the shortest possible completion if the usual Emacs completion algorithm cannot add even a single character. comint-completion-autolist, if non-nil, says to list all the possible completions whenever completion is not exact.

Command completion normally considers only executable files. If you set shell-completion-execonly to nil, it considers nonexecutable files as well.

You can configure the behavior of `pushd'. Variables control whether `pushd' behaves like `cd' if no argument is given (shell-pushd-tohome), pop rather than rotate with a numeric argument (shell-pushd-dextract), and only add directories to the directory stack if they are not already on it (shell-pushd-dunique). The values you choose should match the underlying shell, of course.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.7 Emacs Terminal Emulator

To run a subshell in a terminal emulator, putting its typescript in an Emacs buffer, use M-x term. This creates (or reuses) a buffer named `*terminal*', and runs a subshell with input coming from your keyboard, and output going to that buffer.

The terminal emulator uses Term mode, which has two input modes. In line mode, Term basically acts like Shell mode; see AC.15.3 Shell Mode.

In char mode, each character is sent directly to the inferior subshell, as "terminal input." Any "echoing" of your input is the responsibility of the subshell. The sole exception is the terminal escape character, which by default is C-c (see section AC.15.8 Term Mode). Any "terminal output" from the subshell goes into the buffer, advancing point.

Some programs (such as Emacs itself) need to control the appearance on the terminal screen in detail. They do this by sending special control codes. The exact control codes needed vary from terminal to terminal, but nowadays most terminals and terminal emulators (including xterm) understand the ANSI-standard (VT100-style) escape sequences. Term mode recognizes these escape sequences, and handles each one appropriately, changing the buffer so that the appearance of the window matches what it would be on a real terminal. You can actually run Emacs inside an Emacs Term window.

The file name used to load the subshell is determined the same way as for Shell mode. To make multiple terminal emulators, rename the buffer `*terminal*' to something different using M-x rename-uniquely, just as with Shell mode.

Unlike Shell mode, Term mode does not track the current directory by examining your input. But some shells can tell Term what the current directory is. This is done automatically by bash version 1.15 and later.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.8 Term Mode

The terminal emulator uses Term mode, which has two input modes. In line mode, Term basically acts like Shell mode; see AC.15.3 Shell Mode. In char mode, each character is sent directly to the inferior subshell, except for the Term escape character, normally C-c.

To switch between line and char mode, use these commands:

C-c C-k
Switch to line mode. Do nothing if already in line mode.

C-c C-j
Switch to char mode. Do nothing if already in char mode.
The following commands are only available in char mode:

C-c C-c
Send a literal C-c to the sub-shell.

C-c C-x
A prefix command to access the global C-x commands conveniently. For example, C-c C-x o invokes the global binding of C-x o, which is normally `other-window'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.9 Page-At-A-Time Output

Term mode has a page-at-a-time feature. When enabled it makes output pause at the end of each screenful.

C-c C-q
Toggle the page-at-a-time feature. This command works in both line and char modes. When page-at-a-time is enabled, the mode-line displays the word `page'.
With page-at-a-time enabled, whenever Term receives more than a screenful of output since your last input, it pauses, displaying `**MORE**' in the mode-line. Type SPC to display the next screenful of output. Type ? to see your other options. The interface is similar to the more program.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.15.10 Remote Host Shell

You can login to a remote computer, using whatever commands you would from a regular terminal (e.g. using the telnet or rlogin commands), from a Term window.

A program that asks you for a password will normally suppress echoing of the password, so the password will not show up in the buffer. This will happen just as if you were using a real terminal, if the buffer is in char mode. If it is in line mode, the password is temporarily visible, but will be erased when you hit return. (This happens automatically; there is no special password processing.)

When you log in to a different machine, you need to specify the type of terminal you're using. Terminal types `ansi' or `vt100' will work on most systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.16 Using Emacs as a Server

Various programs such as mail can invoke your choice of editor to edit a particular piece of text, such as a message that you are sending. By convention, most of these programs use the environment variable EDITOR to specify which editor to run. If you set EDITOR to `emacs', they invoke Emacs--but in an inconvenient fashion, by starting a new, separate Emacs process. This is inconvenient because it takes time and because the new Emacs process doesn't share the buffers in any existing Emacs process.

You can arrange to use your existing Emacs process as the editor for programs like mail by using the Emacs client and Emacs server programs. Here is how.

First, the preparation. Within Emacs, call the function server-start. (Your `.emacs' file can do this automatically if you add the expression (server-start) to it.) Then, outside Emacs, set the EDITOR environment variable to `emacsclient'. (Note that some programs use a different environment variable; for example, to make TeX use `emacsclient', you should set the TEXEDIT environment variable to `emacsclient +%d %s'.)

Then, whenever any program invokes your specified EDITOR program, the effect is to send a message to your principal Emacs telling it to visit a file. (That's what the program emacsclient does.) Emacs displays the buffer immediately and you can immediately begin editing it.

When you've finished editing that buffer, type C-x # (server-edit). This saves the file and sends a message back to the emacsclient program telling it to exit. The programs that use EDITOR wait for the "editor" (actually, emacsclient) to exit. C-x # also checks for other pending external requests to edit various files, and selects the next such file.

You can switch to a server buffer manually if you wish; you don't have to arrive at it with C-x #. But C-x # is the way to say that you are finished with one.

Finishing with a server buffer also kills the buffer, unless it already existed in the Emacs session before the server asked to create it. However, if you set server-kill-new-buffers to nil, then a different criterion is used: finishing with a server buffer kills it if the file name matches the regular expression server-temp-file-regexp. This is set up to distinguish certain "temporary" files.

If you set the variable server-window to a window or a frame, C-x # displays the server buffer in that window or in that frame.

While mail or another application is waiting for emacsclient to finish, emacsclient does not read terminal input. So the terminal that mail was using is effectively blocked for the duration. In order to edit with your principal Emacs, you need to be able to use it without using that terminal. There are three ways to do this:

Using a window system, run mail and the principal Emacs in two separate windows. While mail is waiting for emacsclient, the window where it was running is blocked, but you can use Emacs by switching windows.

Using virtual terminals, run mail in one virtual terminal and run Emacs in another.

Use Shell mode or Term mode in Emacs to run the other program such as mail; then, emacsclient blocks only the subshell under Emacs, and you can still use Emacs to edit the file.

If you run emacsclient with the option `--no-wait', it returns immediately without waiting for you to "finish" the buffer in Emacs. Note that server buffers created in this way are not killed automatically when you finish with them.

AC.17 Invoking emacsclient

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.17 Invoking emacsclient

To run the emacsclient program, specify file names as arguments, and optionally line numbers as well. Do it like this:
emacsclient {[+line[column]] filename}...
This tells Emacs to visit each of the specified files; if you specify a line number for a certain file, Emacs moves to that line in the file. If you specify a column number as well, Emacs puts point on that column in the line.

Ordinarily, emacsclient does not return until you use the C-x # command on each of these buffers. When that happens, Emacs sends a message to the emacsclient program telling it to return.

But if you use the option `-n' or `--no-wait' when running emacsclient, then it returns immediately. (You can take as long as you like to edit the files in Emacs.)

The option `--alternate-editor=command' is useful when running emacsclient in a script. It specifies a command to run if emacsclient fails to contact Emacs. For example, the following setting for the EDITOR environment variable will always give an editor, even if Emacs is not running:
EDITOR="emacsclient --alternate-editor vi +%d %s"
The environment variable ALTERNATE_EDITOR has the same effect, but the value of the `--alternate-editor' takes precedence.

Alternatively, the file `etc/emacs.bash' defines a bash function which will communicate with a running Emacs server, or start one if none exists.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.18 Hardcopy Output

The Emacs commands for making hardcopy let you print either an entire buffer or just part of one, either with or without page headers. See also the hardcopy commands of Dired (see section M.10 Miscellaneous File Operations) and the diary (see section AC.10.1 Commands Displaying Diary Entries).

M-x print-buffer
Print hardcopy of current buffer with page headings containing the file name and page number.
M-x lpr-buffer
Print hardcopy of current buffer without page headings.
M-x print-region
Like print-buffer but print only the current region.
M-x lpr-region
Like lpr-buffer but print only the current region.
The hardcopy commands (aside from the Postscript commands) pass extra switches to the lpr program based on the value of the variable lpr-switches. Its value should be a list of strings, each string an option starting with `-'. For example, to specify a line width of 80 columns for all the printing you do in Emacs, set lpr-switches like this:
(setq lpr-switches '("-w80"))
You can specify the printer to use by setting the variable printer-name.

The variable lpr-command specifies the name of the printer program to run; the default value depends on your operating system type. On most systems, the default is "lpr". The variable lpr-headers-switches similarly specifies the extra switches to use to make page headers. The variable lpr-add-switches controls whether to supply `-T' and `-J' options (suitable for lpr) to the printer program: nil means don't add them. lpr-add-switches should be nil if your printer program is not compatible with lpr.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.19 PostScript Hardcopy

These commands convert buffer contents to PostScript, either printing it or leaving it in another Emacs buffer.

M-x ps-print-buffer
Print hardcopy of the current buffer in PostScript form.
M-x ps-print-region
Print hardcopy of the current region in PostScript form.
M-x ps-print-buffer-with-faces
Print hardcopy of the current buffer in PostScript form, showing the faces used in the text by means of PostScript features.
M-x ps-print-region-with-faces
Print hardcopy of the current region in PostScript form, showing the faces used in the text.
M-x ps-spool-buffer
Generate PostScript for the current buffer text.
M-x ps-spool-region
Generate PostScript for the current region.
M-x ps-spool-buffer-with-faces
Generate PostScript for the current buffer, showing the faces used.
M-x ps-spool-region-with-faces
Generate PostScript for the current region, showing the faces used.
M-x handwrite
Generates/prints PostScript for the current buffer as if handwritten.
The PostScript commands, ps-print-buffer and ps-print-region, print buffer contents in PostScript form. One command prints the entire buffer; the other, just the region. The corresponding `-with-faces' commands, ps-print-buffer-with-faces and ps-print-region-with-faces, use PostScript features to show the faces (fonts and colors) in the text properties of the text being printed.

If you are using a color display, you can print a buffer of program code with color highlighting by turning on Font-Lock mode in that buffer, and using ps-print-buffer-with-faces.

The commands whose names have `spool' instead of `print' generate the PostScript output in an Emacs buffer instead of sending it to the printer.

M-x handwrite is more frivolous. It generates a PostScript rendition of the current buffer as a cursive handwritten document. It can be customized in group handwrite. This function only supports ISO 8859-1 characters.

The following section describes variables for customizing these commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.20 Variables for PostScript Hardcopy

All the PostScript hardcopy commands use the variables ps-lpr-command and ps-lpr-switches to specify how to print the output. ps-lpr-command specifies the command name to run, ps-lpr-switches specifies command line options to use, and ps-printer-name specifies the printer. If you don't set the first two variables yourself, they take their initial values from lpr-command and lpr-switches. If ps-printer-name is nil, printer-name is used.

The variable ps-print-header controls whether these commands add header lines to each page--set it to nil to turn headers off.

If your printer doesn't support colors, you should turn off color processing by setting ps-print-color-p to nil. By default, if the display supports colors, Emacs produces hardcopy output with color information; on black-and-white printers, colors are emulated with shades of gray. This might produce illegible output, even if your screen colors only use shades of gray.

By default, PostScript printing ignores the background colors of the faces, unless the variable ps-use-face-background is non-nil. This is to avoid unwanted interference with the zebra stripes and background image/text.

The variable ps-paper-type specifies which size of paper to format for; legitimate values include a4, a3, a4small, b4, b5, executive, ledger, legal, letter, letter-small, statement, tabloid. The default is letter. You can define additional paper sizes by changing the variable ps-page-dimensions-database.

The variable ps-landscape-mode specifies the orientation of printing on the page. The default is nil, which stands for "portrait" mode. Any non-nil value specifies "landscape" mode.

The variable ps-number-of-columns specifies the number of columns; it takes effect in both landscape and portrait mode. The default is 1.

The variable ps-font-family specifies which font family to use for printing ordinary text. Legitimate values include Courier, Helvetica, NewCenturySchlbk, Palatino and Times. The variable ps-font-size specifies the size of the font for ordinary text. It defaults to 8.5 points.

Emacs supports more scripts and characters than a typical PostScript printer. Thus, some of the characters in your buffer might not be printable using the fonts built into your printer. You can augment the fonts supplied with the printer with those from the GNU Intlfonts package, or you can instruct Emacs to use Intlfonts exclusively. The variable ps-multibyte-buffer controls this: the default value, nil, is appropriate for printing ASCII and Latin-1 characters; a value of non-latin-printer is for printers which have the fonts for ASCII, Latin-1, Japanese, and Korean characters built into them. A value of bdf-font arranges for the BDF fonts from the Intlfonts package to be used for all characters. Finally, a value of bdf-font-except-latin instructs the printer to use built-in fonts for ASCII and Latin-1 characters, and Intlfonts BDF fonts for the rest.

To be able to use the BDF fonts, Emacs needs to know where to find them. The variable bdf-directory-list holds the list of directories where Emacs should look for the fonts; the default value includes a single directory `/usr/local/share/emacs/fonts/bdf'.

Many other customization variables for these commands are defined and described in the Lisp files `ps-print.el' and `ps-mule.el'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.21 Sorting Text

Emacs provides several commands for sorting text in the buffer. All operate on the contents of the region (the text between point and the mark). They divide the text of the region into many sort records, identify a sort key for each record, and then reorder the records into the order determined by the sort keys. The records are ordered so that their keys are in alphabetical order, or, for numeric sorting, in numeric order. In alphabetic sorting, all upper-case letters `A' through `Z' come before lower-case `a', in accord with the ASCII character sequence.

The various sort commands differ in how they divide the text into sort records and in which part of each record is used as the sort key. Most of the commands make each line a separate sort record, but some commands use paragraphs or pages as sort records. Most of the sort commands use each entire sort record as its own sort key, but some use only a portion of the record as the sort key.

M-x sort-lines
Divide the region into lines, and sort by comparing the entire text of a line. A numeric argument means sort into descending order.

M-x sort-paragraphs
Divide the region into paragraphs, and sort by comparing the entire text of a paragraph (except for leading blank lines). A numeric argument means sort into descending order.

M-x sort-pages
Divide the region into pages, and sort by comparing the entire text of a page (except for leading blank lines). A numeric argument means sort into descending order.

M-x sort-fields
Divide the region into lines, and sort by comparing the contents of one field in each line. Fields are defined as separated by whitespace, so the first run of consecutive non-whitespace characters in a line constitutes field 1, the second such run constitutes field 2, etc.
Specify which field to sort by with a numeric argument: 1 to sort by field 1, etc. A negative argument means count fields from the right instead of from the left; thus, minus 1 means sort by the last field. If several lines have identical contents in the field being sorted, they keep the same relative order that they had in the original buffer.

M-x sort-numeric-fields
Like M-x sort-fields except the specified field is converted to an integer for each line, and the numbers are compared. `10' comes before `2' when considered as text, but after it when considered as a number. By default, numbers are interpreted according to sort-numeric-base, but numbers beginning with `0x' or `0' are interpreted as hexadecimal and octal, respectively.

M-x sort-columns
Like M-x sort-fields except that the text within each line used for comparison comes from a fixed range of columns. See below for an explanation.

M-x reverse-region
Reverse the order of the lines in the region. This is useful for sorting into descending order by fields or columns, since those sort commands do not have a feature for doing that.
For example, if the buffer contains this:
On systems where clash detection (locking of files being edited) is
implemented, Emacs also checks the first time you modify a buffer
whether the file has changed on disk since it was last visited or
saved.  If it has, you are asked to confirm that you want to change
the buffer.
applying M-x sort-lines to the entire buffer produces this:
On systems where clash detection (locking of files being edited) is
implemented, Emacs also checks the first time you modify a buffer
saved.  If it has, you are asked to confirm that you want to change
the buffer.
whether the file has changed on disk since it was last visited or
where the upper-case `O' sorts before all lower-case letters. If you use C-u 2 M-x sort-fields instead, you get this:
implemented, Emacs also checks the first time you modify a buffer
saved.  If it has, you are asked to confirm that you want to change
the buffer.
On systems where clash detection (locking of files being edited) is
whether the file has changed on disk since it was last visited or
where the sort keys were `Emacs', `If', `buffer', `systems' and `the'.

M-x sort-columns requires more explanation. You specify the columns by putting point at one of the columns and the mark at the other column. Because this means you cannot put point or the mark at the beginning of the first line of the text you want to sort, this command uses an unusual definition of "region": all of the line point is in is considered part of the region, and so is all of the line the mark is in, as well as all the lines in between.

For example, to sort a table by information found in columns 10 to 15, you could put the mark on column 10 in the first line of the table, and point on column 15 in the last line of the table, and then run sort-columns. Equivalently, you could run it with the mark on column 15 in the first line and point on column 10 in the last line.

This can be thought of as sorting the rectangle specified by point and the mark, except that the text on each line to the left or right of the rectangle moves along with the text inside the rectangle. See section H.10 Rectangles.

Many of the sort commands ignore case differences when comparing, if sort-fold-case is non-nil.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.22 Narrowing

Narrowing means focusing in on some portion of the buffer, making the rest temporarily inaccessible. The portion which you can still get to is called the accessible portion. Canceling the narrowing, which makes the entire buffer once again accessible, is called widening. The amount of narrowing in effect in a buffer at any time is called the buffer's restriction.

Narrowing can make it easier to concentrate on a single subroutine or paragraph by eliminating clutter. It can also be used to restrict the range of operation of a replace command or repeating keyboard macro.

C-x n n
Narrow down to between point and mark (narrow-to-region).
C-x n w
Widen to make the entire buffer accessible again (widen).
C-x n p
Narrow down to the current page (narrow-to-page).
C-x n d
Narrow down to the current defun (narrow-to-defun).
When you have narrowed down to a part of the buffer, that part appears to be all there is. You can't see the rest, you can't move into it (motion commands won't go outside the accessible part), you can't change it in any way. However, it is not gone, and if you save the file all the inaccessible text will be saved. The word `Narrow' appears in the mode line whenever narrowing is in effect.

The primary narrowing command is C-x n n (narrow-to-region). It sets the current buffer's restrictions so that the text in the current region remains accessible, but all text before the region or after the region is inaccessible. Point and mark do not change.

Alternatively, use C-x n p (narrow-to-page) to narrow down to the current page. See section T.4 Pages, for the definition of a page. C-x n d (narrow-to-defun) narrows down to the defun containing point (see section U.2 Top-Level Definitions, or Defuns).

The way to cancel narrowing is to widen with C-x n w (widen). This makes all text in the buffer accessible again.

You can get information on what part of the buffer you are narrowed down to using the C-x = command. See section D.9 Cursor Position Information.

Because narrowing can easily confuse users who do not understand it, narrow-to-region is normally a disabled command. Attempting to use this command asks for confirmation and gives you the option of enabling it; if you enable the command, confirmation will no longer be required for it. See section AD.4.11 Disabling Commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.23 Two-Column Editing

Two-column mode lets you conveniently edit two side-by-side columns of text. It uses two side-by-side windows, each showing its own buffer.

There are three ways to enter two-column mode:

F2 2 or C-x 6 2
Enter two-column mode with the current buffer on the left, and on the right, a buffer whose name is based on the current buffer's name (2C-two-columns). If the right-hand buffer doesn't already exist, it starts out empty; the current buffer's contents are not changed.
This command is appropriate when the current buffer is empty or contains just one column and you want to add another column.

F2 s or C-x 6 s
Split the current buffer, which contains two-column text, into two buffers, and display them side by side (2C-split). The current buffer becomes the left-hand buffer, but the text in the right-hand column is moved into the right-hand buffer. The current column specifies the split point. Splitting starts with the current line and continues to the end of the buffer.
This command is appropriate when you have a buffer that already contains two-column text, and you wish to separate the columns temporarily.

F2 b buffer RET

C-x 6 b buffer RET
Enter two-column mode using the current buffer as the left-hand buffer, and using buffer buffer as the right-hand buffer (2C-associate-buffer).
F2 s or C-x 6 s looks for a column separator, which is a string that appears on each line between the two columns. You can specify the width of the separator with a numeric argument to F2 s; that many characters, before point, constitute the separator string. By default, the width is 1, so the column separator is the character before point.

When a line has the separator at the proper place, F2 s puts the text after the separator into the right-hand buffer, and deletes the separator. Lines that don't have the column separator at the proper place remain unsplit; they stay in the left-hand buffer, and the right-hand buffer gets an empty line to correspond. (This is the way to write a line that "spans both columns while in two-column mode": write it in the left-hand buffer, and put an empty line in the right-hand buffer.)

The command C-x 6 RET or F2 RET (2C-newline) inserts a newline in each of the two buffers at corresponding positions. This is the easiest way to add a new line to the two-column text while editing it in split buffers.

When you have edited both buffers as you wish, merge them with F2 1 or C-x 6 1 (2C-merge). This copies the text from the right-hand buffer as a second column in the other buffer. To go back to two-column editing, use F2 s.

Use F2 d or C-x 6 d to dissociate the two buffers, leaving each as it stands (2C-dissociate). If the other buffer, the one not current when you type F2 d, is empty, F2 d kills it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.24 Editing Binary Files

There is a special major mode for editing binary files: Hexl mode. To use it, use M-x hexl-find-file instead of C-x C-f to visit the file. This command converts the file's contents to hexadecimal and lets you edit the translation. When you save the file, it is converted automatically back to binary.

You can also use M-x hexl-mode to translate an existing buffer into hex. This is useful if you visit a file normally and then discover it is a binary file.

Ordinary text characters overwrite in Hexl mode. This is to reduce the risk of accidentally spoiling the alignment of data in the file. There are special commands for insertion. Here is a list of the commands of Hexl mode:

C-M-d
Insert a byte with a code typed in decimal.

C-M-o
Insert a byte with a code typed in octal.

C-M-x
Insert a byte with a code typed in hex.

C-x [
Move to the beginning of a 1k-byte "page."

C-x ]
Move to the end of a 1k-byte "page."

M-g
Move to an address specified in hex.

M-j
Move to an address specified in decimal.

C-c C-c
Leave Hexl mode, going back to the major mode this buffer had before you invoked hexl-mode.
Other Hexl commands let you insert strings (sequences) of binary bytes, move by shorts or ints, etc.; type C-h a hexl-RET for details.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.25 Saving Emacs Sessions

You can use the Desktop library to save the state of Emacs from one session to another. Saving the state means that Emacs starts up with the same set of buffers, major modes, buffer positions, and so on that the previous Emacs session had.

To use Desktop, you should use the Customization buffer (see section AD.2.2 Easy Customization Interface) to set desktop-enable to a non-nil value, or add these lines at the end of your `.emacs' file:
(desktop-load-default)
(desktop-read)
The first time you save the state of the Emacs session, you must do it manually, with the command M-x desktop-save. Once you have done that, exiting Emacs will save the state again--not only the present Emacs session, but also subsequent sessions. You can also save the state at any time, without exiting Emacs, by typing M-x desktop-save again.

In order for Emacs to recover the state from a previous session, you must start it with the same current directory as you used when you started the previous session. This is because desktop-read looks in the current directory for the file to read. This means that you can have separate saved sessions in different directories; the directory in which you start Emacs will control which saved session to use.

The variable desktop-files-not-to-save controls which files are excluded from state saving. Its value is a regular expression that matches the files to exclude. By default, remote (ftp-accessed) files are excluded; this is because visiting them again in the subsequent session would be slow. If you want to include these files in state saving, set desktop-files-not-to-save to "^$". See section M.13 Remote Files.

The Saveplace library provides a simpler feature that records your position in each file when you kill its buffer (or kill Emacs), and jumps to the same position when you visit the file again (even in another Emacs session). Use M-x toggle-save-place to turn on place-saving in a given file. Customize the option save-place to turn it on for all files in each session.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.26 Recursive Editing Levels

A recursive edit is a situation in which you are using Emacs commands to perform arbitrary editing while in the middle of another Emacs command. For example, when you type C-r inside of a query-replace, you enter a recursive edit in which you can change the current buffer. On exiting from the recursive edit, you go back to the query-replace.

Exiting the recursive edit means returning to the unfinished command, which continues execution. The command to exit is C-M-c (exit-recursive-edit).

You can also abort the recursive edit. This is like exiting, but also quits the unfinished command immediately. Use the command C-] (abort-recursive-edit) to do this. See section AD.8 Quitting and Aborting.

The mode line shows you when you are in a recursive edit by displaying square brackets around the parentheses that always surround the major and minor mode names. Every window's mode line shows this in the same way, since being in a recursive edit is true of Emacs as a whole rather than any particular window or buffer.

It is possible to be in recursive edits within recursive edits. For example, after typing C-r in a query-replace, you may type a command that enters the debugger. This begins a recursive editing level for the debugger, within the recursive editing level for C-r. Mode lines display a pair of square brackets for each recursive editing level currently in progress.

Exiting the inner recursive edit (such as, with the debugger c command) resumes the command running in the next level up. When that command finishes, you can then use C-M-c to exit another recursive editing level, and so on. Exiting applies to the innermost level only. Aborting also gets out of only one level of recursive edit; it returns immediately to the command level of the previous recursive edit. If you wish, you can then abort the next recursive editing level.

Alternatively, the command M-x top-level aborts all levels of recursive edits, returning immediately to the top-level command reader.

The text being edited inside the recursive edit need not be the same text that you were editing at top level. It depends on what the recursive edit is for. If the command that invokes the recursive edit selects a different buffer first, that is the buffer you will edit recursively. In any case, you can switch buffers within the recursive edit in the normal manner (as long as the buffer-switching keys have not been rebound). You could probably do all the rest of your editing inside the recursive edit, visiting files and all. But this could have surprising effects (such as stack overflow) from time to time. So remember to exit or abort the recursive edit when you no longer need it.

In general, we try to minimize the use of recursive editing levels in GNU Emacs. This is because they constrain you to "go back" in a particular order--from the innermost level toward the top level. When possible, we present different activities in separate buffers so that you can switch between them as you please. Some commands switch to a new major mode which provides a command to switch back. These approaches give you more flexibility to go back to unfinished tasks in the order you choose.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.27 Emulation

GNU Emacs can be programmed to emulate (more or less) most other editors. Standard facilities can emulate these:

CRiSP/Brief (PC editor)
You can turn on key bindings to emulate the CRiSP/Brief editor with M-x crisp-mode. Note that this rebinds M-x to exit Emacs unless you change the user option crisp-override-meta-x. You can also use the command M-x scroll-all-mode or set the user option crisp-load-scroll-all to emulate CRiSP's scroll-all feature (scrolling all windows together).

EDT (DEC VMS editor)
Turn on EDT emulation with M-x edt-emulation-on. M-x edt-emulation-off restores normal Emacs command bindings.
Most of the EDT emulation commands are keypad keys, and most standard Emacs key bindings are still available. The EDT emulation rebindings are done in the global keymap, so there is no problem switching buffers or major modes while in EDT emulation.

"PC" bindings
The command M-x pc-bindings-mode sets up certain key bindings for "PC compatibility"---what people are often used to on PCs--as follows: Delete and its variants delete forward instead of backward, C-Backspace kills backward a word (as C-Delete normally would), M-Backspace does undo, Home and End move to beginning and end of line, C-Home and C-End move to beginning and end of buffer and C-Escape does list-buffers.

PC Selection mode
The command M-x pc-selection-mode enables a global minor mode that emulates the mark, copy, cut and paste commands of various other systems--an interface known as CUA. It establishes the key bindings of PC mode, and also modifies the bindings of the cursor keys and the next, prior, home and end keys. It does not provide the full set of CUA key bindings--the fundamental Emacs keys C-c, C-v and C-x are not changed.
The standard keys for moving around (right, left, up, down, home, end, prior, next, called "move-keys") deactivate the mark in PC selection mode. However, using Shift together with the "move keys" activates the region over which they move. The copy, cut and paste functions are available on C-insert, S-delete and S-insert respectively.

The s-region package provides similar, but less complete, facilities.

TPU (DEC VMS editor)
M-x tpu-edt-on turns on emulation of the TPU editor emulating EDT.

vi (Berkeley editor)
Viper is the newest emulator for vi. It implements several levels of emulation; level 1 is closest to vi itself, while level 5 departs somewhat from strict emulation to take advantage of the capabilities of Emacs. To invoke Viper, type M-x viper-mode; it will guide you the rest of the way and ask for the emulation level. See Info file `viper', node `Top'.

vi (another emulator)
M-x vi-mode enters a major mode that replaces the previously established major mode. All of the vi commands that, in real vi, enter "input" mode are programmed instead to return to the previous major mode. Thus, ordinary Emacs serves as vi's "input" mode.
Because vi emulation works through major modes, it does not work to switch buffers during emulation. Return to normal Emacs first.

If you plan to use vi emulation much, you probably want to bind a key to the vi-mode command.

vi (alternate emulator)
M-x vip-mode invokes another vi emulator, said to resemble real vi more thoroughly than M-x vi-mode. "Input" mode in this emulator is changed from ordinary Emacs so you can use ESC to go back to emulated vi command mode. To get from emulated vi command mode back to ordinary Emacs, type C-z.
This emulation does not work through major modes, and it is possible to switch buffers in various ways within the emulator. It is not so necessary to assign a key to the command vip-mode as it is with vi-mode because terminating insert mode does not use it.

See Info file `vip', node `Top', for full information.

WordStar (old wordprocessor)
M-x wordstar-mode provides a major mode with WordStar-like key bindings.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.28 Hyperlinking and Navigation Features

Various modes documented elsewhere have hypertext features so that you can follow links, usually by clicking Mouse-2 on the link or typing RET while point is on the link. Info mode, Help mode and the Dired-like modes are examples. The Tags facility links between uses and definitions in source files, see W.2 Tags Tables. Imenu provides navigation amongst items indexed in the current buffer, see U.2.3 Imenu. Info-lookup provides mode-specific lookup of definitions in Info indexes, see U.6 Documentation Lookup. Speedbar maintains a frame in which links to files, and locations in files are displayed, see P.9 Making and Using a Speedbar Frame.

Other non-mode-specific facilities described in this section enable following links from the current buffer in a context-sensitive fashion.

AC.28.1 Following URLs

Following URLs.

AC.28.2 Activating URLs

Activating URLs.

AC.28.3 Finding Files and URLs at Point

Finding files etc. at point.

AC.28.4 Finding Function and Variable Definitions

Finding function and variable definitions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.28.1 Following URLs

M-x browse-url RET url RET
Load a URL into a Web browser.
The Browse-URL package provides facilities for following URLs specifying links on the World Wide Web. Usually this works by invoking a web browser, but you can, for instance, arrange to invoke compose-mail from `mailto:' URLs.

The general way to use this feature is to type M-x browse-url, which displays a specified URL. If point is located near a plausible URL, that URL is used as the default. Other commands are available which you might like to bind to keys, such as browse-url-at-point and browse-url-at-mouse.

You can customize Browse-URL's behavior via various options in the browse-url Customize group, particularly browse-url-browser-function. You can invoke actions dependent on the type of URL by defining browse-url-browser-function as an association list. The package's commentary available via C-h p provides more information. Packages with facilities for following URLs should always go through Browse-URL, so that the customization options for Browse-URL will affect all browsing in Emacs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.28.2 Activating URLs

M-x goto-address
Activate URLs and e-mail addresses in the current buffer.
You can make URLs in the current buffer active with M-x goto-address. This finds all the URLs in the buffer, and establishes bindings for Mouse-2 and C-c RET on them. After activation, if you click on a URL with Mouse-2, or move to a URL and type C-c RET, that will display the web page that the URL specifies. For a `mailto' URL, it sends mail instead, using your selected mail-composition method (see section Z.6 Mail-Composition Methods).

It can be useful to add goto-address to mode hooks and the hooks used to display an incoming message. rmail-show-message-hook is the appropriate hook for Rmail, and mh-show-mode-hook for MH-E. This is not needed for Gnus, which has a similar feature of its own.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.28.3 Finding Files and URLs at Point

FFAP mode replaces certain key bindings for finding files, including C-x C-f, with commands that provide more sensitive defaults. These commands behave like the ordinary ones when given a prefix argument. Otherwise, they get the default file name or URL from the text around point. If what is found in the buffer has the form of a URL rather than a file name, the commands use browse-url to view it.

This feature is useful for following references in mail or news buffers, `README' files, `MANIFEST' files, and so on. The `ffap' package's commentary available via C-h p and the ffap Custom group provide details.

You can turn on FFAP minor mode to make the following key bindings and to install hooks for using ffap in Rmail, Gnus and VM article buffers.

C-x C-f filename RET
Find filename, guessing a default from text around point (find-file-at-point).
C-x 4 f
ffap-other-window, analogous to find-file-other-window.
C-x 5 f
ffap-other-frame, analogous to find-file-other-frame.
M-x ffap-next
Search buffer for next file name or URL, then find that file or URL.
C-x d directory RET
Start Dired on directory, defaulting to the directory name at point (ffap-dired-at-point).
S-Mouse-3
ffap-at-mouse finds the file guessed from text around the position of a mouse click.
C-S-Mouse-3
Display a menu of files and URLs mentioned in current buffer, then find the one you select (ffap-menu).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.28.4 Finding Function and Variable Definitions

M-x find-function RET function RET
Find the definition of function in its source file.
M-x find-variable RET variable RET
Find the definition of variable in its source file.
M-x find-function-on-key RET key
Find the definition of the function that key invokes.
These commands provide an easy way to find the definitions of Emacs Lisp functions and variables. They are similar in purpose to the Tags facility (see section W.2 Tags Tables), but don't require a tags table; on the other hand, they only work for function and variable definitions that are already loaded in the Emacs session.

To find the definition of a function, use M-x find-function. M-x find-variable finds the definition of a specified variable. M-x find-function-on-key finds the definition of the function bound to a specified key.

To use these commands, you must have the Lisp source (`.el') files available along with the compiled (`.elc') files, in directories in load-path. You can use compressed source files if you enable Auto Compression mode. These commands only handle definitions written in Lisp, not primitive functions or variables defined in the C code of Emacs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.29 Dissociated Press

M-x dissociated-press is a command for scrambling a file of text either word by word or character by character. Starting from a buffer of straight English, it produces extremely amusing output. The input comes from the current Emacs buffer. Dissociated Press writes its output in a buffer named `*Dissociation*', and redisplays that buffer after every couple of lines (approximately) so you can read the output as it comes out.

Dissociated Press asks every so often whether to continue generating output. Answer n to stop it. You can also stop at any time by typing C-g. The dissociation output remains in the `*Dissociation*' buffer for you to copy elsewhere if you wish.

Dissociated Press operates by jumping at random from one point in the buffer to another. In order to produce plausible output rather than gibberish, it insists on a certain amount of overlap between the end of one run of consecutive words or characters and the start of the next. That is, if it has just output `president' and then decides to jump to a different point in the file, it might spot the `ent' in `pentagon' and continue from there, producing `presidentagon'.(15) Long sample texts produce the best results.

A positive argument to M-x dissociated-press tells it to operate character by character, and specifies the number of overlap characters. A negative argument tells it to operate word by word and specifies the number of overlap words. In this mode, whole words are treated as the elements to be permuted, rather than characters. No argument is equivalent to an argument of two. For your againformation, the output goes only into the buffer `*Dissociation*'. The buffer you start with is not changed.

Dissociated Press produces nearly the same results as a Markov chain based on a frequency table constructed from the sample text. It is, however, an independent, ignoriginal invention. Dissociated Press techniquitously copies several consecutive characters from the sample between random choices, whereas a Markov chain would choose randomly for each word or character. This makes for more plausible sounding results, and runs faster.

It is a mustatement that too much use of Dissociated Press can be a developediment to your real work. Sometimes to the point of outragedy. And keep dissociwords out of your documentation, if you want it to be well userenced and properbose. Have fun. Your buggestions are welcome.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AC.30 Other Amusements

If you are a little bit bored, you can try M-x hanoi. If you are considerably bored, give it a numeric argument. If you are very, very bored, try an argument of 9. Sit back and watch.

If you want a little more personal involvement, try M-x gomoku, which plays the game Go Moku with you.

M-x blackbox, M-x mpuz and M-x 5x5 are kinds of puzzles. blackbox challenges you to determine the location of objects inside a box by tomography. mpuz displays a multiplication puzzle with letters standing for digits in a code that you must guess--to guess a value, type a letter and then the digit you think it stands for. The aim of 5x5 is to fill in all the squares.

M-x decipher helps you to cryptanalyze a buffer which is encrypted in a simple monoalphabetic substitution cipher.

M-x dunnet runs an adventure-style exploration game, which is a bigger sort of puzzle.

M-x lm runs a relatively non-participatory game in which a robot attempts to maneuver towards a tree at the center of the window based on unique olfactory cues from each of the four directions.

M-x life runs Conway's "Life" cellular automaton.

M-x morse-region converts text in a region to Morse code and M-x unmorse-region converts it back. No cause for remorse.

M-x pong plays a Pong-like game, bouncing the ball off opposing bats.

M-x solitaire plays a game of solitaire in which you jump pegs across other pegs.

M-x studlify-region studlify-cases the region, producing text like this:
M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region.
M-x tetris runs an implementation of the well-known Tetris game. Likewise, M-x snake provides an implementation of Snake.

When you are frustrated, try the famous Eliza program. Just do M-x doctor. End each input by typing RET twice.

When you are feeling strange, type M-x yow.

The command M-x zone plays games with the display when Emacs is idle.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD. Customization

This chapter talks about various topics relevant to adapting the behavior of Emacs in minor ways. See The Emacs Lisp Reference Manual for how to make more far-reaching changes.

Customization that you do within Emacs normally affects only the particular Emacs session that you do it in--it does not persist between sessions unless you save the customization in a file such as `.emacs' or `.Xdefaults' that will affect future sessions. See section AD.7 The Init File, `~/.emacs'. In the customization buffer, when you save customizations for future sessions, this actually works by editing `.emacs' for you.

AD.1 Minor Modes

Each minor mode is one feature you can turn on independently of any others.

AD.2 Variables

Many Emacs commands examine Emacs variables to decide what to do; by setting variables, you can control their functioning.

AD.3 Keyboard Macros

A keyboard macro records a sequence of keystrokes to be replayed with a single command.

AD.4 Customizing Key Bindings

The keymaps say what command each key runs. By changing them, you can "redefine keys".

AD.5 Keyboard Translations

If your keyboard passes an undesired code for a key, you can tell Emacs to substitute another code.

AD.6 The Syntax Table

The syntax table controls how words and expressions are parsed.

AD.7 The Init File, `~/.emacs'

How to write common customizations in the

`.emacs' file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.1 Minor Modes

Minor modes are optional features which you can turn on or off. For example, Auto Fill mode is a minor mode in which SPC breaks lines between words as you type. All the minor modes are independent of each other and of the selected major mode. Most minor modes say in the mode line when they are on; for example, `Fill' in the mode line means that Auto Fill mode is on.

Append -mode to the name of a minor mode to get the name of a command function that turns the mode on or off. Thus, the command to enable or disable Auto Fill mode is called M-x auto-fill-mode. These commands are usually invoked with M-x, but you can bind keys to them if you wish. With no argument, the function turns the mode on if it was off and off if it was on. This is known as toggling. A positive argument always turns the mode on, and an explicit zero argument or a negative argument always turns it off.

Some minor modes are global: while enabled, they affect everything you do in the Emacs session, in all buffers. Other minor modes are buffer-local; they apply only to the current buffer, so you can enable the mode in certain buffers and not others.

For most minor modes, the command name is also the name of a variable which directly controls the mode. The mode is enabled whenever this variable's value is non-nil, and the minor-mode command works by setting the variable. For example, the command outline-minor-mode works by setting the value of outline-minor-mode as a variable; it is this variable that directly turns Outline minor mode on and off. To check whether a given minor mode works this way, use C-h v to ask for documentation on the variable name.

These minor-mode variables provide a good way for Lisp programs to turn minor modes on and off; they are also useful in a file's local variables list. But please think twice before setting minor modes with a local variables list, because most minor modes are matter of user preference--other users editing the same file might not want the same minor modes you prefer.

The buffer-local minor modes include Abbrev mode, Auto Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents mode, Outline minor mode, Overwrite mode, and Binary Overwrite mode.

Abbrev mode allows you to define abbreviations that automatically expand as you type them. For example, `amd' might expand to `abbrev mode'. See section X. Abbrevs, for full information.

Auto Fill mode allows you to enter filled text without breaking lines explicitly. Emacs inserts newlines as necessary to prevent lines from becoming too long. See section T.5 Filling Text.

Auto Save mode causes the contents of a buffer to be saved periodically to reduce the amount of work you can lose in case of a system crash. See section M.5 Auto-Saving: Protection Against Disasters.

Enriched mode enables editing and saving of formatted text. See section T.11 Editing Formatted Text.

Flyspell mode automatically highlights misspelled words. See section L.4 Checking and Correcting Spelling.

Font-Lock mode automatically highlights certain textual units found in programs, such as comments, strings, and function names being defined. This requires a window system that can display multiple fonts. See section J.1 Using Multiple Typefaces.

ISO Accents mode makes the characters ``', `'', `"', `^', `/' and `~' combine with the following letter, to produce an accented letter in the ISO Latin-1 character set. The newer and more general feature of input methods more or less supersedes ISO Accents mode. See section Q.13 Single-byte Character Set Support.

Outline minor mode provides the same facilities as the major mode called Outline mode; but since it is a minor mode instead, you can combine it with any major mode. See section T.8 Outline Mode.

Overwrite mode causes ordinary printing characters to replace existing text instead of shoving it to the right. For example, if point is in front of the `B' in `FOOBAR', then in Overwrite mode typing a G changes it to `FOOGAR', instead of producing `FOOGBAR' as usual. In Overwrite mode, the command C-q inserts the next character whatever it may be, even if it is a digit--this gives you a way to insert a character instead of replacing an existing character.

The command overwrite-mode is an exception to the rule that commands which toggle minor modes are normally not bound to keys: it is bound to the INSERT function key. This is because many other programs bind INSERT to similar functions.

Binary Overwrite mode is a variant of Overwrite mode for editing binary files; it treats newlines and tabs like other characters, so that they overwrite other characters and can be overwritten by them. In Binary Overwrite mode, digits after C-q specify an octal character code, as usual.

The following minor modes normally apply to all buffers at once. Since each is enabled or disabled by the value of a variable, you can set them differently for particular buffers, by explicitly making the corresponding variables local in those buffers. See section AD.2.4 Local Variables.

Icomplete mode displays an indication of available completions when you are in the minibuffer and completion is active. See section E.3.4 Completion Options.

Line Number mode enables continuous display in the mode line of the line number of point, and Column Number mode enables display of the column number. See section B.3 The Mode Line.

Scroll Bar mode gives each window a scroll bar (see section P.13 Scroll Bars). Menu Bar mode gives each frame a menu bar (see section P.15 Menu Bars). Both of these modes are enabled by default when you use the X Window System.

In Transient Mark mode, every change in the buffer contents "deactivates" the mark, so that commands that operate on the region will get an error. This means you must either set the mark, or explicitly "reactivate" it, before each command that uses the region. The advantage of Transient Mark mode is that Emacs can display the region highlighted (currently only when using X). See section H. The Mark and the Region.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2 Variables

A variable is a Lisp symbol which has a value. The symbol's name is also called the name of the variable. A variable name can contain any characters that can appear in a file, but conventionally variable names consist of words separated by hyphens. A variable can have a documentation string which describes what kind of value it should have and how the value will be used.

Lisp allows any variable to have any kind of value, but most variables that Emacs uses require a value of a certain type. Often the value should always be a string, or should always be a number. Sometimes we say that a certain feature is turned on if a variable is "non-nil," meaning that if the variable's value is nil, the feature is off, but the feature is on for any other value. The conventional value to use to turn on the feature--since you have to pick one particular value when you set the variable--is t.

Emacs uses many Lisp variables for internal record keeping, as any Lisp program must, but the most interesting variables for you are the ones that exist for the sake of customization. Emacs does not (usually) change the values of these variables; instead, you set the values, and thereby alter and control the behavior of certain Emacs commands. These variables are called user options. Most user options are documented in this manual, and appear in the Variable Index (see section Variable Index).

One example of a variable which is a user option is fill-column, which specifies the position of the right margin (as a number of characters from the left margin) to be used by the fill commands (see section T.5 Filling Text).

AD.2.1 Examining and Setting Variables

Examining or setting one variable's value.

AD.2.2 Easy Customization Interface

Convenient and easy customization of variables.

AD.2.3 Hooks

Hook variables let you specify programs for parts of Emacs to run on particular occasions.

AD.2.4 Local Variables

Per-buffer values of variables.

AD.2.5 Local Variables in Files

How files can specify variable values.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.1 Examining and Setting Variables

C-h v var RET
Display the value and documentation of variable var (describe-variable).
M-x set-variable RET var RET value RET
Change the value of variable var to value.
To examine the value of a single variable, use C-h v (describe-variable), which reads a variable name using the minibuffer, with completion. It displays both the value and the documentation of the variable. For example,
C-h v fill-column RET
displays something like this:
fill-column's value is 70

Documentation:
*Column beyond which automatic line-wrapping should happen.
Automatically becomes buffer-local when set in any fashion.
The star at the beginning of the documentation indicates that this variable is a user option. C-h v is not restricted to user options; it allows any variable name.

The most convenient way to set a specific user option is with M-x set-variable. This reads the variable name with the minibuffer (with completion), and then reads a Lisp expression for the new value using the minibuffer a second time. For example,
M-x set-variable RET fill-column RET 75 RET
sets fill-column to 75.

M-x set-variable is limited to user option variables, but you can set any variable with a Lisp expression, using the function setq. Here is a setq expression to set fill-column:
(setq fill-column 75)
To execute an expression like this one, go to the `*scratch*' buffer, type in the expression, and then type C-j. See section V.9 Lisp Interaction Buffers.

Setting variables, like all means of customizing Emacs except where otherwise stated, affects only the current Emacs session.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.2 Easy Customization Interface

A convenient way to find the user option variables that you want to change, and then change them, is with M-x customize. This command creates a customization buffer with which you can browse through the Emacs user options in a logically organized structure, then edit and set their values. You can also use the customization buffer to save settings permanently. (Not all Emacs user options are included in this structure as of yet, but we are adding the rest.)

The appearance of the example buffers in the following is typically different under a window system where faces can be used to indicate the active fields and other features.

AD.2.2.1 Customization Groups

How options are classified in a structure.

AD.2.2.2 Changing an Option

How to edit a value and set an option.

AD.2.2.3 Customizing Faces

How to edit the attributes of a face.

AD.2.2.4 Customizing Specific Items

Making a customization buffer for specific options, faces, or groups.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.2.1 Customization Groups

For customization purposes, user options are organized into groups to help you find them. Groups are collected into bigger groups, all the way up to a master group called Emacs.

M-x customize creates a customization buffer that shows the top-level Emacs group and the second-level groups immediately under it. It looks like this, in part:
/- Emacs group: ---------------------------------------------------\
      [State]: visible group members are all at standard settings.
   Customization of the One True Editor.
   See also [Manual].

Confirm Kill Emacs: [Hide] [Value Menu] Don't confirm
   [State]: this option is unchanged from its standard setting.
How to ask for confirmation when leaving Emacs. [More]

Editing group: [Go to Group]
Basic text editing facilities.

External group: [Go to Group]
Interfacing to external utilities.

more second-level groups

\- Emacs group end ------------------------------------------------/
This says that the buffer displays the contents of the Emacs group. The other groups are listed because they are its contents. But they are listed differently, without indentation and dashes, because their contents are not included. Each group has a single-line documentation string; the Emacs group also has a `[State]' line.

Most of the text in the customization buffer is read-only, but it typically includes some editable fields that you can edit. There are also active fields; this means a field that does something when you invoke it. To invoke an active field, either click on it with Mouse-1, or move point to it and type RET.

For example, the phrase `[Go to Group]' that appears in a second-level group is an active field. Invoking the `[Go to Group]' field for a group creates a new customization buffer, which shows that group and its contents. This field is a kind of hypertext link to another group.

The Emacs group includes a few user options itself, but mainly it contains other groups, which contain more groups, which contain the user options. By browsing the hierarchy of groups, you will eventually find the feature you are interested in customizing. Then you can use the customization buffer to set the options and faces pertaining to that feature. You can also go straight to a particular group by name, using the command M-x customize-group.

You can view the structure of customization groups on a larger scale with M-x customize-browse. This command creates a special kind of customization buffer which shows only the names of the groups (and options and faces), and their structure.

In this buffer, you can show the contents of a group by invoking `[+]'. When the group contents are visible, this button changes to `[-]'; invoking that hides the group contents.

Each group, option or face name in this buffer has an active field which says `[Group]', `[Option]' or `[Face]'. Invoking that active field creates an ordinary customization buffer showing just that group and its contents, just that option, or just that face. This is the way to set values in it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.2.2 Changing an Option

Here is an example of what a user option looks like in the customization buffer:
Kill Ring Max: [Hide] 60
   [State]: this option is unchanged from its standard setting.
Maximum length of kill ring before oldest elements are thrown away.
The text following `[Hide]', `60' in this case, indicates the current value of the option. If you see `[Show]' instead of `[Hide]', it means that the value is hidden; the customization buffer initially hides values that take up several lines. Invoke `[Show]' to show the value.

The line after the option name indicates the customization state of the option: in the example above, it says you have not changed the option yet. The word `[State]' at the beginning of this line is active; you can get a menu of various operations by invoking it with Mouse-1 or RET. These operations are essential for customizing the variable.

The line after the `[State]' line displays the beginning of the option's documentation string. If there are more lines of documentation, this line ends with `[More]'; invoke this to show the full documentation string.

To enter a new value for `Kill Ring Max', move point to the value and edit it textually. For example, you can type M-d, then insert another number.

When you begin to alter the text, you will see the `[State]' line change to say that you have edited the value:
[State]: you have edited the value as text, but not set the option.
Editing the value does not actually set the option variable. To do that, you must set the option. To do this, invoke the word `[State]' and choose `Set for Current Session'.

The state of the option changes visibly when you set it:
[State]: you have set this option, but not saved it for future sessions.
You don't have to worry about specifying a value that is not valid; setting the option checks for validity and will not really install an unacceptable value.

While editing a value or field that is a file name, directory name, command name, or anything else for which completion is defined, you can type M-TAB (widget-complete) to do completion.

Some options have a small fixed set of possible legitimate values. These options don't let you edit the value textually. Instead, an active field `[Value Menu]' appears before the value; invoke this field to edit the value. For a boolean "on or off" value, the active field says `[Toggle]', and it changes to the other value. `[Value Menu]' and `[Toggle]' edit the buffer; the changes take effect when you use the `Set for Current Session' operation.

Some options have values with complex structure. For example, the value of file-coding-system-alist is an association list. Here is how it appears in the customization buffer:
File Coding System Alist: [Hide]
[INS] [DEL] File regexp: \.elc\'
            Choice: [Value Menu] Encoding/decoding pair:
            Decoding: emacs-mule
            Encoding: emacs-mule
[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
            Choice: [Value Menu] Encoding/decoding pair:
            Decoding: raw-text
            Encoding: raw-text-unix
[INS] [DEL] File regexp: \.tar\'
            Choice: [Value Menu] Encoding/decoding pair:
            Decoding: no-conversion
            Encoding: no-conversion
[INS] [DEL] File regexp:
            Choice: [Value Menu] Encoding/decoding pair:
            Decoding: undecided
            Encoding: nil
[INS]
   [State]: this option is unchanged from its standard setting.
Alist to decide a coding system to use for a file I/O operation. [Hide]
The format is ((PATTERN . VAL) ...),
where PATTERN is a regular expression matching a file name,
[...more lines of documentation...]
Each association in the list appears on four lines, with several editable or "active" fields. You can edit the regexps and coding systems using ordinary editing commands. You can also invoke `[Value Menu]' to switch to a kind of value--for instance, to specify a function instead of a pair of coding systems.

To delete an association from the list, invoke the `[DEL]' button for that item. To add an association, invoke `[INS]' at the position where you want to add it. There is an `[INS]' button between each pair of association, another at the beginning and another at the end, so you can add the new association at any position in the list.

Two special commands, TAB and S-TAB, are useful for moving through the customization buffer. TAB (widget-forward) moves forward to the next active or editable field; S-TAB (widget-backward) moves backward to the previous active or editable field.

Typing RET on an editable field also moves forward, just like TAB. We set it up this way because people often type RET when they are finished editing a field. To insert a newline within an editable field, use C-o or C-q C-j.

Setting the option changes its value in the current Emacs session; saving the value changes it for future sessions as well. This works by writing code into your `~/.emacs' file so as to set the option variable again each time you start Emacs. To save the option, invoke `[State]' and select the `Save for Future Sessions' operation.

If Emacs was invoked with the `-q' or `--no-init-file' options (see section AE.2 Initial Options), it will not let you save your customizations in your `~/.emacs' init file. This is because saving customizations from such a session would wipe out all the other customizations you might have on your init file.

You can also restore the option to its standard value by invoking `[State]' and selecting the `Erase Customization' operation. There are actually three reset operations:

`Reset'
If you have made some modifications and not yet set the option, this restores the text in the customization buffer to match the actual value.

`Reset to Saved'
This restores the value of the option to the last saved value, and updates the text accordingly.

`Erase Customization'
This sets the option to its standard value, and updates the text accordingly. This also eliminates any saved value for the option, so that you will get the standard value in future Emacs sessions.
Sometimes it is useful to record a comment about a specific customization. Use the `Add Comment' item from the `[State]' menu to create a field for entering the comment. The comment you enter will be saved, and displayed again if you again view the same option in a customization buffer, even in another session.

The state of a group indicates whether anything in that group has been edited, set or saved. You can select `Set for Current Session', `Save for Future Sessions' and the various kinds of `Reset' operation for the group; these operations on the group apply to all options in the group and its subgroups.

Near the top of the customization buffer there are two lines containing several active fields:
 [Set for Current Session] [Save for Future Sessions]
 [Reset] [Reset to Saved] [Erase Customization]   [Finish]
Invoking `[Finish]' either buries or kills this customization buffer according to the setting of the option custom-buffer-done-function; the default is to bury the buffer. Each of the other fields performs an operation--set, save or reset--on each of the items in the buffer that could meaningfully be set, saved or reset.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.2.3 Customizing Faces

In addition to user options, some customization groups also include faces. When you show the contents of a group, both the user options and the faces in the group appear in the customization buffer. Here is an example of how a face looks:
Custom Changed Face: (sample) [Hide]
   [State]: this face is unchanged from its standard setting.
Parent groups: [Custom Magic Faces]
Attributes: [ ] Font family: [Value Menu] *
            [ ] Width: [Value Menu] *
            [ ] Height: [Value Menu] *
            [ ] Weight: [Value Menu] *
            [ ] Slant: [Value Menu] *
            [ ] Underline: [Value Menu] *
            [ ] Overline: [Value Menu] *
            [ ] Strike-through: [Value Menu] *
            [ ] Box around text: [Value Menu] *
            [ ] Inverse-video: [Value Menu] *
            [X] Foreground: [Value Menu] Color: white       (sample)
            [X] Background: [Value Menu] Color: blue        (sample)
            [ ] Stipple: [Value Menu] *
            [ ] Inherit:
Each face attribute has its own line. The `[x]' field before the attribute name indicates whether the attribute is enabled; `X' means that it is. You can enable or disable the attribute by invoking that field. When the attribute is enabled, you can change the attribute value in the usual ways.

On a black-and-white display, the colors you can use for the background are `black', `white', `gray', `gray1', and `gray3'. Emacs supports these shades of gray by using background stipple patterns instead of a color.

Setting, saving and resetting a face work like the same operations for options (see section AD.2.2.2 Changing an Option).

A face can specify different appearances for different types of display. For example, a face can make text red on a color display, but use a bold font on a monochrome display. To specify multiple appearances for a face, select `Show all display specs' in the menu you get from invoking `[State]'.

Another more basic way to set the attributes of a specific face is with M-x modify-face. This command reads the name of a face, then reads the attributes one by one. For the color and stipple attributes, the attribute's current value is the default--type just RET if you don't want to change that attribute. Type `none' if you want to clear out the attribute.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.2.4 Customizing Specific Items

Instead of finding the options you want to change by moving down through the structure of groups, you can specify the particular option, face or group that you want to customize.

M-x customize-option RET option RET
Set up a customization buffer with just one option, option.
M-x customize-face RET face RET
Set up a customization buffer with just one face, face.
M-x customize-group RET group RET
Set up a customization buffer with just one group, group.
M-x customize-apropos RET regexp RET
Set up a customization buffer with all the options, faces and groups that match regexp.
M-x customize-changed-options RET version RET
Set up a customization buffer with all the options, faces and groups whose meaning has changed since Emacs version version.
M-x customize-saved
Set up a customization buffer containing all options and faces that you have saved with customization buffers.
M-x customize-customized
Set up a customization buffer containing all options and faces that you have customized but not saved.
If you want to alter a particular user option variable with the customization buffer, and you know its name, you can use the command M-x customize-option and specify the option name. This sets up the customization buffer with just one option--the one that you asked for. Editing, setting and saving the value work as described above, but only for the specified option.

Likewise, you can modify a specific face, chosen by name, using M-x customize-face.

You can also set up the customization buffer with a specific group, using M-x customize-group. The immediate contents of the chosen group, including option variables, faces, and other groups, all appear as well. However, these subgroups' own contents start out hidden. You can show their contents in the usual way, by invoking `[Show]'.

To control more precisely what to customize, you can use M-x customize-apropos. You specify a regular expression as argument; then all options, faces and groups whose names match this regular expression are set up in the customization buffer. If you specify an empty regular expression, this includes all groups, options and faces in the customization buffer (but that takes a long time).

When you upgrade to a new Emacs version, you might want to customize new options and options whose meanings or default values have changed. To do this, use M-x customize-changed-options and specify a previous Emacs version number using the minibuffer. It creates a customization buffer which shows all the options (and groups) whose definitions have been changed since the specified version.

If you change option values and then decide the change was a mistake, you can use two special commands to revisit your previous changes. Use M-x customize-saved to look at the options and faces that you have saved. Use M-x customize-customized to look at the options and faces that you have set but not saved.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.3 Hooks

Hooks are an important mechanism for customization of Emacs. A hook is a Lisp variable which holds a list of functions, to be called on some well-defined occasion. (This is called running the hook.) The individual functions in the list are called the hook functions of the hook. With rare exceptions, hooks in Emacs are empty when Emacs starts up, so the only hook functions in any given hook are the ones you explicitly put there as customization.

Most major modes run one or more mode hooks as the last step of initialization. This makes it easy for you to customize the behavior of the mode, by setting up a hook function to override the local variable assignments already made by the mode. But hooks are also used in other contexts. For example, the hook suspend-hook runs just before Emacs suspends itself (see section C.1 Exiting Emacs).

Most Emacs hooks are normal hooks. This means that running the hook operates by calling all the hook functions, unconditionally, with no arguments. We have made an effort to keep most hooks normal so that you can use them in a uniform way. Every variable in Emacs whose name ends in `-hook' is a normal hook.

There are also a few abnormal hooks. These variables' names end in `-hooks' or `-functions', instead of `-hook'. What makes these hooks abnormal is that there is something peculiar about the way its functions are called--perhaps they are given arguments, or perhaps the values they return are used in some way. For example, find-file-not-found-hooks (see section M.2 Visiting Files) is abnormal because as soon as one hook function returns a non-nil value, the rest are not called at all. The documentation of each abnormal hook variable explains in detail what is peculiar about it.

The recommended way to add a hook function to a hook (either normal or abnormal) is by calling add-hook. You can use any valid Lisp function as the hook function, provided it can handle the proper number of arguments (zero arguments, in the case of a normal hook). Of course, not every Lisp function is useful in any particular hook.

For example, here's how to set up a hook to turn on Auto Fill mode when entering Text mode and other modes based on Text mode:
(add-hook 'text-mode-hook 'turn-on-auto-fill)
The next example shows how to use a hook to customize the indentation of C code. (People often have strong personal preferences for one format compared to another.) Here the hook function is an anonymous lambda expression.
(setq my-c-style
  '((c-comment-only-line-offset . 4)
    (c-cleanup-list . (scope-operator
               empty-defun-braces
               defun-close-semi))
    (c-offsets-alist . ((arglist-close . c-lineup-arglist)
            (substatement-open . 0)))))

(add-hook 'c-mode-common-hook
  '(lambda ()
     (c-add-style "my-style" my-c-style t)))
It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is "asking for trouble." However, the order is predictable: the most recently added hook functions are executed first.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.4 Local Variables

M-x make-local-variable RET var RET
Make variable var have a local value in the current buffer.
M-x kill-local-variable RET var RET
Make variable var use its global value in the current buffer.
M-x make-variable-buffer-local RET var RET
Mark variable var so that setting it will make it local to the buffer that is current at that time.
Almost any variable can be made local to a specific Emacs buffer. This means that its value in that buffer is independent of its value in other buffers. A few variables are always local in every buffer. Every other Emacs variable has a global value which is in effect in all buffers that have not made the variable local.

M-x make-local-variable reads the name of a variable and makes it local to the current buffer. Further changes in this buffer will not affect others, and further changes in the global value will not affect this buffer.

M-x make-variable-buffer-local reads the name of a variable and changes the future behavior of the variable so that it will become local automatically when it is set. More precisely, once a variable has been marked in this way, the usual ways of setting the variable automatically do make-local-variable first. We call such variables per-buffer variables.

Major modes (see section R. Major Modes) always make variables local to the buffer before setting the variables. This is why changing major modes in one buffer has no effect on other buffers. Minor modes also work by setting variables--normally, each minor mode has one controlling variable which is non-nil when the mode is enabled (see section AD.1 Minor Modes). For most minor modes, the controlling variable is per buffer.

Emacs contains a number of variables that are always per-buffer. These include abbrev-mode, auto-fill-function, case-fold-search, comment-column, ctl-arrow, fill-column, fill-prefix, indent-tabs-mode, left-margin, mode-line-format, overwrite-mode, selective-display-ellipses, selective-display, tab-width, and truncate-lines. Some other variables are always local in every buffer, but they are used for internal purposes.

A few variables cannot be local to a buffer because they are always local to each display instead (see section P.10 Multiple Displays). If you try to make one of these variables buffer-local, you'll get an error message.

M-x kill-local-variable reads the name of a variable and makes it cease to be local to the current buffer. The global value of the variable henceforth is in effect in this buffer. Setting the major mode kills all the local variables of the buffer except for a few variables specially marked as permanent locals.

To set the global value of a variable, regardless of whether the variable has a local value in the current buffer, you can use the Lisp construct setq-default. This construct is used just like setq, but it sets variables' global values instead of their local values (if any). When the current buffer does have a local value, the new global value may not be visible until you switch to another buffer. Here is an example:
(setq-default fill-column 75)
setq-default is the only way to set the global value of a variable that has been marked with make-variable-buffer-local.

Lisp programs can use default-value to look at a variable's default value. This function takes a symbol as argument and returns its default value. The argument is evaluated; usually you must quote it explicitly. For example, here's how to obtain the default value of fill-column:
(default-value 'fill-column)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.2.5 Local Variables in Files

A file can specify local variable values for use when you edit the file with Emacs. Visiting the file checks for local variable specifications; it automatically makes these variables local to the buffer, and sets them to the values specified in the file.

There are two ways to specify local variable values: in the first line, or with a local variables list. Here's how to specify them in the first line:
-*- mode: modename; var: value; ... -*-
You can specify any number of variables/value pairs in this way, each pair with a colon and semicolon as shown above. mode: modename; specifies the major mode; this should come first in the line. The values are not evaluated; they are used literally. Here is an example that specifies Lisp mode and sets two variables with numeric values:
;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
You can also specify the coding system for a file in this way: just specify a value for the "variable" named coding. The "value" must be a coding system name that Emacs recognizes. See section Q.7 Coding Systems.

The eval pseudo-variable, described below, can be specified in the first line as well.

In shell scripts, the first line is used to identify the script interpreter, so you cannot put any local variables there. To accommodate for this, when Emacs visits a shell script, it looks for local variable specifications in the second line.

A local variables list goes near the end of the file, in the last page. (It is often best to put it on a page by itself.) The local variables list starts with a line containing the string `Local Variables:', and ends with a line containing the string `End:'. In between come the variable names and values, one set per line, as `variable: value'. The values are not evaluated; they are used literally. If a file has both a local variables list and a `-*-' line, Emacs processes everything in the `-*-' line first, and everything in the local variables list afterward.

Here is an example of a local variables list:
;;; Local Variables: ***
;;; mode:lisp ***
;;; comment-column:0 ***
;;; comment-start: ";;; "  ***
;;; comment-end:"***" ***
;;; End: ***
As you see, each line starts with the prefix `;;; ' and each line ends with the suffix ` ***'. Emacs recognizes these as the prefix and suffix based on the first line of the list, by finding them surrounding the magic string `Local Variables:'; then it automatically discards them from the other lines of the list.

The usual reason for using a prefix and/or suffix is to embed the local variables list in a comment, so it won't confuse other programs that the file is intended as input for. The example above is for a language where comment lines start with `;;; ' and end with `***'; the local values for comment-start and comment-end customize the rest of Emacs for this unusual syntax. Don't use a prefix (or a suffix) if you don't need one.

Two "variable names" have special meanings in a local variables list: a value for the variable mode really sets the major mode, and a value for the variable eval is simply evaluated as an expression and the value is ignored. mode and eval are not real variables; setting variables named mode and eval in any other context has no special meaning. If mode is used to set a major mode, it should be the first "variable" in the list. Otherwise, the entries that precede it in the list of the local variables are likely to be ignored, since most modes kill all local variables as part of their initialization.

You can use the mode "variable" to set minor modes as well as major modes; in fact, you can use it more than once, first to set the major mode and then to set minor modes which are specific to particular buffers. But most minor modes should not be specified in the file in any fashion, because they represent user preferences.

For example, you may be tempted to try to turn on Auto Fill mode with a local variable list. That is a mistake. The choice of Auto Fill mode or not is a matter of individual taste, not a matter of the contents of particular files. If you want to use Auto Fill, set up major mode hooks with your `.emacs' file to turn it on (when appropriate) for you alone (see section AD.7 The Init File, `~/.emacs'). Don't use a local variable list to impose your taste on everyone.

The start of the local variables list must be no more than 3000 characters from the end of the file, and must be in the last page if the file is divided into pages. Otherwise, Emacs will not notice it is there. The purpose of this rule is so that a stray `Local Variables:' not in the last page does not confuse Emacs, and so that visiting a long file that is all one page and has no local variables list need not take the time to search the whole file.

Use the command normal-mode to reset the local variables and major mode of a buffer according to the file name and contents, including the local variables list if any. See section R.1 How Major Modes are Chosen.

The variable enable-local-variables controls whether to process local variables in files, and thus gives you a chance to override them. Its default value is t, which means do process local variables in files. If you set the value to nil, Emacs simply ignores local variables in files. Any other value says to query you about each file that has local variables, showing you the local variable specifications so you can judge.

The eval "variable," and certain actual variables, create a special risk; when you visit someone else's file, local variable specifications for these could affect your Emacs in arbitrary ways. Therefore, the option enable-local-eval controls whether Emacs processes eval variables, as well variables with names that end in `-hook', `-hooks', `-function' or `-functions', and certain other variables. The three possibilities for the option's value are t, nil, and anything else, just as for enable-local-variables. The default is maybe, which is neither t nor nil, so normally Emacs does ask for confirmation about file settings for these variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.3 Keyboard Macros

A keyboard macro is a command defined by the user to stand for another sequence of keys. For example, if you discover that you are about to type C-n C-d forty times, you can speed your work by defining a keyboard macro to do C-n C-d and calling it with a repeat count of forty.

C-x (
Start defining a keyboard macro (start-kbd-macro).
C-x )
End the definition of a keyboard macro (end-kbd-macro).
C-x e
Execute the most recent keyboard macro (call-last-kbd-macro).
C-u C-x (
Re-execute last keyboard macro, then add more keys to its definition.
C-x q
When this point is reached during macro execution, ask for confirmation (kbd-macro-query).
M-x name-last-kbd-macro
Give a command name (for the duration of the session) to the most recently defined keyboard macro.
M-x insert-kbd-macro
Insert in the buffer a keyboard macro's definition, as Lisp code.
C-x C-k
Edit a previously defined keyboard macro (edit-kbd-macro).
M-x apply-macro-to-region-lines
Run the last keyboard macro on each complete line in the region.
Keyboard macros differ from ordinary Emacs commands in that they are written in the Emacs command language rather than in Lisp. This makes it easier for the novice to write them, and makes them more convenient as temporary hacks. However, the Emacs command language is not powerful enough as a programming language to be useful for writing anything intelligent or general. For such things, Lisp must be used.

You define a keyboard macro while executing the commands which are the definition. Put differently, as you define a keyboard macro, the definition is being executed for the first time. This way, you can see what the effects of your commands are, so that you don't have to figure them out in your head. When you are finished, the keyboard macro is defined and also has been, in effect, executed once. You can then do the whole thing over again by invoking the macro.

AD.3.1 Basic Use

Defining and running keyboard macros.

AD.3.2 Naming and Saving Keyboard Macros

Giving keyboard macros names; saving them in files.

AD.3.3 Executing Macros with Variations

Making keyboard macros do different things each time.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.3.1 Basic Use

To start defining a keyboard macro, type the C-x ( command (start-kbd-macro). From then on, your keys continue to be executed, but also become part of the definition of the macro. `Def' appears in the mode line to remind you of what is going on. When you are finished, the C-x ) command (end-kbd-macro) terminates the definition (without becoming part of it!). For example,
C-x ( M-f foo C-x )
defines a macro to move forward a word and then insert `foo'.

The macro thus defined can be invoked again with the C-x e command (call-last-kbd-macro), which may be given a repeat count as a numeric argument to execute the macro many times. C-x ) can also be given a repeat count as an argument, in which case it repeats the macro that many times right after defining it, but defining the macro counts as the first repetition (since it is executed as you define it). Therefore, giving C-x ) an argument of 4 executes the macro immediately 3 additional times. An argument of zero to C-x e or C-x ) means repeat the macro indefinitely (until it gets an error or you type C-g or, on MS-DOS, C-BREAK).

If you wish to repeat an operation at regularly spaced places in the text, define a macro and include as part of the macro the commands to move to the next place you want to use it. For example, if you want to change each line, you should position point at the start of a line, and define a macro to change that line and leave point at the start of the next line. Then repeating the macro will operate on successive lines.

When a command reads an argument with the minibuffer, your minibuffer input becomes part of the macro along with the command. So when you replay the macro, the command gets the same argument as when you entered the macro. For example,
C-x ( C-a C-SPC C-n M-w C-x b f o o RET C-y C-x b RET C-x )
defines a macro that copies the current line into the buffer `foo', then returns to the original buffer.

You can use function keys in a keyboard macro, just like keyboard keys. You can even use mouse events, but be careful about that: when the macro replays the mouse event, it uses the original mouse position of that event, the position that the mouse had while you were defining the macro. The effect of this may be hard to predict. (Using the current mouse position would be even less predictable.)

One thing that doesn't always work well in a keyboard macro is the command C-M-c (exit-recursive-edit). When this command exits a recursive edit that started within the macro, it works as you'd expect. But if it exits a recursive edit that started before you invoked the keyboard macro, it also necessarily exits the keyboard macro as part of the process.

After you have terminated the definition of a keyboard macro, you can add to the end of its definition by typing C-u C-x (. This is equivalent to plain C-x ( followed by retyping the whole definition so far. As a consequence it re-executes the macro as previously defined.

You can edit a keyboard macro already defined by typing C-x C-k (edit-kbd-macro). Follow that with the keyboard input that you would use to invoke the macro---C-x e or M-x name or some other key sequence. This formats the macro definition in a buffer and enters a specialized major mode for editing it. Type C-h m once in that buffer to display details of how to edit the macro. When you are finished editing, type C-c C-c.

The command M-x apply-macro-to-region-lines repeats the last defined keyboard macro on each complete line within the current region. It does this line by line, by moving point to the beginning of the line and then executing the macro.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.3.2 Naming and Saving Keyboard Macros

If you wish to save a keyboard macro for longer than until you define the next one, you must give it a name using M-x name-last-kbd-macro. This reads a name as an argument using the minibuffer and defines that name to execute the macro. The macro name is a Lisp symbol, and defining it in this way makes it a valid command name for calling with M-x or for binding a key to with global-set-key (see section AD.4.1 Keymaps). If you specify a name that has a prior definition other than another keyboard macro, an error message is shown and nothing is changed.

Once a macro has a command name, you can save its definition in a file. Then it can be used in another editing session. First, visit the file you want to save the definition in. Then use this command:
M-x insert-kbd-macro RET macroname RET
This inserts some Lisp code that, when executed later, will define the same macro with the same definition it has now. (You need not understand Lisp code to do this, because insert-kbd-macro writes the Lisp code for you.) Then save the file. You can load the file later with load-file (see section V.7 Libraries of Lisp Code for Emacs). If the file you save in is your init file `~/.emacs' (see section AD.7 The Init File, `~/.emacs') then the macro will be defined each time you run Emacs.

If you give insert-kbd-macro a numeric argument, it makes additional Lisp code to record the keys (if any) that you have bound to the keyboard macro, so that the macro will be reassigned the same keys when you load the file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.3.3 Executing Macros with Variations

Using C-x q (kbd-macro-query), you can get an effect similar to that of query-replace, where the macro asks you each time around whether to make a change. While defining the macro, type C-x q at the point where you want the query to occur. During macro definition, the C-x q does nothing, but when you run the macro later, C-x q asks you interactively whether to continue.

The valid responses when C-x q asks are SPC (or y), DEL (or n), RET (or q), C-l and C-r. The answers are the same as in query-replace, though not all of the query-replace options are meaningful.

These responses include SPC to continue, and DEL to skip the remainder of this repetition of the macro and start right away with the next repetition. RET means to skip the remainder of this repetition and cancel further repetitions. C-l redraws the screen and asks you again for a character to say what to do.

C-r enters a recursive editing level, in which you can perform editing which is not part of the macro. When you exit the recursive edit using C-M-c, you are asked again how to continue with the keyboard macro. If you type a SPC at this time, the rest of the macro definition is executed. It is up to you to leave point and the text in a state such that the rest of the macro will do what you want.

C-u C-x q, which is C-x q with a numeric argument, performs a completely different function. It enters a recursive edit reading input from the keyboard, both when you type it during the definition of the macro, and when it is executed from the macro. During definition, the editing you do inside the recursive edit does not become part of the macro. During macro execution, the recursive edit gives you a chance to do some particularized editing on each repetition. See section AC.26 Recursive Editing Levels.

Another way to vary the behavior of a keyboard macro is to use a register as a counter, incrementing it on each repetition of the macro. See section I.5 Keeping Numbers in Registers.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4 Customizing Key Bindings

This section describes key bindings, which map keys to commands, and keymaps, which record key bindings. It also explains how to customize key bindings.

Recall that a command is a Lisp function whose definition provides for interactive use. Like every Lisp function, a command has a function name which usually consists of lower-case letters and hyphens.

AD.4.1 Keymaps

Generalities. The global keymap.

AD.4.2 Prefix Keymaps

Keymaps for prefix keys.

AD.4.3 Local Keymaps

Major and minor modes have their own keymaps.

AD.4.4 Minibuffer Keymaps

The minibuffer uses its own local keymaps.

AD.4.5 Changing Key Bindings Interactively

How to redefine one key's meaning conveniently.

AD.4.6 Rebinding Keys in Your Init File

Rebinding keys with your init file, `.emacs'.

AD.4.7 Rebinding Function Keys

Rebinding terminal function keys.

AD.4.8 Named ASCII Control Characters

Distinguishing TAB from C-i, and so on.

AD.4.9 Non-ASCII Characters on the Keyboard

Rebinding non-ASCII characters such as Latin-1.

AD.4.10 Rebinding Mouse Buttons

Rebinding mouse buttons in Emacs.

AD.4.11 Disabling Commands

Disabling a command means confirmation is required before it can be executed. This is done to protect beginners from surprises.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.1 Keymaps

The bindings between key sequences and command functions are recorded in data structures called keymaps. Emacs has many of these, each used on particular occasions.

Recall that a key sequence (key, for short) is a sequence of input events that have a meaning as a unit. Input events include characters, function keys and mouse buttons--all the inputs that you can send to the computer with your terminal. A key sequence gets its meaning from its binding, which says what command it runs. The function of keymaps is to record these bindings.

The global keymap is the most important keymap because it is always in effect. The global keymap defines keys for Fundamental mode; most of these definitions are common to most or all major modes. Each major or minor mode can have its own keymap which overrides the global definitions of some keys.

For example, a self-inserting character such as g is self-inserting because the global keymap binds it to the command self-insert-command. The standard Emacs editing characters such as C-a also get their standard meanings from the global keymap. Commands to rebind keys, such as M-x global-set-key, actually work by storing the new binding in the proper place in the global map. See section AD.4.5 Changing Key Bindings Interactively.

Meta characters work differently; Emacs translates each Meta character into a pair of characters starting with ESC. When you type the character M-a in a key sequence, Emacs replaces it with ESC a. A meta key comes in as a single input event, but becomes two events for purposes of key bindings. The reason for this is historical, and we might change it someday.

Most modern keyboards have function keys as well as character keys. Function keys send input events just as character keys do, and keymaps can have bindings for them.

On many terminals, typing a function key actually sends the computer a sequence of characters; the precise details of the sequence depends on which function key and on the model of terminal you are using. (Often the sequence starts with ESC [.) If Emacs understands your terminal type properly, it recognizes the character sequences forming function keys wherever they occur in a key sequence (not just at the beginning). Thus, for most purposes, you can pretend the function keys reach Emacs directly and ignore their encoding as character sequences.

Mouse buttons also produce input events. These events come with other data--the window and position where you pressed or released the button, and a time stamp. But only the choice of button matters for key bindings; the other data matters only if a command looks at it. (Commands designed for mouse invocation usually do look at the other data.)

A keymap records definitions for single events. Interpreting a key sequence of multiple events involves a chain of keymaps. The first keymap gives a definition for the first event; this definition is another keymap, which is used to look up the second event in the sequence, and so on.

Key sequences can mix function keys and characters. For example, C-x SELECT is meaningful. If you make SELECT a prefix key, then SELECT C-n makes sense. You can even mix mouse events with keyboard events, but we recommend against it, because such key sequences are inconvenient to use.

As a user, you can redefine any key; but it is usually best to stick to key sequences that consist of C-c followed by a letter. These keys are "reserved for users," so they won't conflict with any properly designed Emacs extension. The function keys F5 through F9 are also reserved for users. If you redefine some other key, your definition may be overridden by certain extensions or major modes which redefine the same key.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.2 Prefix Keymaps

A prefix key such as C-x or ESC has its own keymap, which holds the definition for the event that immediately follows that prefix.

The definition of a prefix key is usually the keymap to use for looking up the following event. The definition can also be a Lisp symbol whose function definition is the following keymap; the effect is the same, but it provides a command name for the prefix key that can be used as a description of what the prefix key is for. Thus, the binding of C-x is the symbol Ctl-X-Prefix, whose function definition is the keymap for C-x commands. The definitions of C-c, C-x, C-h and ESC as prefix keys appear in the global map, so these prefix keys are always available.

Aside from ordinary prefix keys, there is a fictitious "prefix key" which represents the menu bar; see section `Menu Bar' in The Emacs Lisp Reference Manual, for special information about menu bar key bindings. Mouse button events that invoke pop-up menus are also prefix keys; see section `Menu Keymaps' in The Emacs Lisp Reference Manual, for more details.

Some prefix keymaps are stored in variables with names:

ctl-x-map is the variable name for the map used for characters that follow C-x.
help-map is for characters that follow C-h.
esc-map is for characters that follow ESC. Thus, all Meta characters are actually defined by this map.
ctl-x-4-map is for characters that follow C-x 4.
mode-specific-map is for characters that follow C-c.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.3 Local Keymaps

So far we have explained the ins and outs of the global map. Major modes customize Emacs by providing their own key bindings in local keymaps. For example, C mode overrides TAB to make it indent the current line for C code. Portions of text in the buffer can specify their own keymaps to substitute for the keymap of the buffer's major mode.

Minor modes can also have local keymaps. Whenever a minor mode is in effect, the definitions in its keymap override both the major mode's local keymap and the global keymap.

The local keymaps for Lisp mode and several other major modes always exist even when not in use. These are kept in variables named lisp-mode-map and so on. For major modes less often used, the local keymap is normally constructed only when the mode is used for the first time in a session. This is to save space. If you wish to change one of these keymaps, you must use the major mode's mode hook---see below.

All minor mode keymaps are created in advance. There is no way to defer their creation until the first time the minor mode is enabled.

A local keymap can locally redefine a key as a prefix key by defining it as a prefix keymap. If the key is also defined globally as a prefix, then its local and global definitions (both keymaps) effectively combine: both of them are used to look up the event that follows the prefix key. Thus, if the mode's local keymap defines C-c as another keymap, and that keymap defines C-z as a command, this provides a local meaning for C-c C-z. This does not affect other sequences that start with C-c; if those sequences don't have their own local bindings, their global bindings remain in effect.

Another way to think of this is that Emacs handles a multi-event key sequence by looking in several keymaps, one by one, for a binding of the whole key sequence. First it checks the minor mode keymaps for minor modes that are enabled, then it checks the major mode's keymap, and then it checks the global keymap. This is not precisely how key lookup works, but it's good enough for understanding ordinary circumstances.

To change the local bindings of a major mode, you must change the mode's local keymap. Normally you must wait until the first time the mode is used, because most major modes don't create their keymaps until then. If you want to specify something in your `~/.emacs' file to change a major mode's bindings, you must use the mode's mode hook to delay the change until the mode is first used.

For example, the command texinfo-mode to select Texinfo mode runs the hook texinfo-mode-hook. Here's how you can use the hook to add local bindings (not very useful, we admit) for C-c n and C-c p in Texinfo mode:
(add-hook 'texinfo-mode-hook
          '(lambda ()
             (define-key texinfo-mode-map "\C-cp"
                         'backward-paragraph)
             (define-key texinfo-mode-map "\C-cn"
                         'forward-paragraph)))
See section AD.2.3 Hooks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.4 Minibuffer Keymaps

The minibuffer has its own set of local keymaps; they contain various completion and exit commands.

minibuffer-local-map is used for ordinary input (no completion).
minibuffer-local-ns-map is similar, except that SPC exits just like RET. This is used mainly for Mocklisp compatibility.
minibuffer-local-completion-map is for permissive completion.
minibuffer-local-must-match-map is for strict completion and for cautious completion.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.5 Changing Key Bindings Interactively

The way to redefine an Emacs key is to change its entry in a keymap. You can change the global keymap, in which case the change is effective in all major modes (except those that have their own overriding local definitions for the same key). Or you can change the current buffer's local map, which affects all buffers using the same major mode.

M-x global-set-key RET key cmd RET
Define key globally to run cmd.
M-x local-set-key RET key cmd RET
Define key locally (in the major mode now in effect) to run cmd.
M-x global-unset-key RET key
Make key undefined in the global map.
M-x local-unset-key RET key
Make key undefined locally (in the major mode now in effect).
For example, suppose you like to execute commands in a subshell within an Emacs buffer, instead of suspending Emacs and executing commands in your login shell. Normally, C-z is bound to the function suspend-emacs (when not using the X Window System), but you can change C-z to invoke an interactive subshell within Emacs, by binding it to shell as follows:
M-x global-set-key RET C-z shell RET
global-set-key reads the command name after the key. After you press the key, a message like this appears so that you can confirm that you are binding the key you want:
Set key C-z to command:
You can redefine function keys and mouse events in the same way; just type the function key or click the mouse when it's time to specify the key to rebind.

You can rebind a key that contains more than one event in the same way. Emacs keeps reading the key to rebind until it is a complete key (that is, not a prefix key). Thus, if you type C-f for key, that's the end; the minibuffer is entered immediately to read cmd. But if you type C-x, another character is read; if that is 4, another character is read, and so on. For example,
M-x global-set-key RET C-x 4 $ spell-other-window RET
redefines C-x 4 $ to run the (fictitious) command spell-other-window.

The two-character keys consisting of C-c followed by a letter are reserved for user customizations. Lisp programs are not supposed to define these keys, so the bindings you make for them will be available in all major modes and will never get in the way of anything.

You can remove the global definition of a key with global-unset-key. This makes the key undefined; if you type it, Emacs will just beep. Similarly, local-unset-key makes a key undefined in the current major mode keymap, which makes the global definition (or lack of one) come back into effect in that major mode.

If you have redefined (or undefined) a key and you subsequently wish to retract the change, undefining the key will not do the job--you need to redefine the key with its standard definition. To find the name of the standard definition of a key, go to a Fundamental mode buffer and use C-h c. The documentation of keys in this manual also lists their command names.

If you want to prevent yourself from invoking a command by mistake, it is better to disable the command than to undefine the key. A disabled command is less work to invoke when you really want to. See section AD.4.11 Disabling Commands.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.6 Rebinding Keys in Your Init File

If you have a set of key bindings that you like to use all the time, you can specify them in your `.emacs' file by using their Lisp syntax. (See section AD.7 The Init File, `~/.emacs'.)

The simplest method for doing this works for ASCII characters and Meta-modified ASCII characters only. This method uses a string to represent the key sequence you want to rebind. For example, here's how to bind C-z to shell:
(global-set-key "\C-z" 'shell)
This example uses a string constant containing one character, C-z. The single-quote before the command name, shell, marks it as a constant symbol rather than a variable. If you omit the quote, Emacs would try to evaluate shell immediately as a variable. This probably causes an error; it certainly isn't what you want.

Here is another example that binds a key sequence two characters long:
(global-set-key "\C-xl" 'make-symbolic-link)
To put TAB, RET, ESC, or DEL in the string, you can use the Emacs Lisp escape sequences, `\t', `\r', `\e', and `\d'. Here is an example which binds C-x TAB:
(global-set-key "\C-x\t" 'indent-rigidly)
These examples show how to write some other special ASCII characters in strings for key bindings:
(global-set-key "\r" 'newline)               ;; RET
(global-set-key "\d" 'delete-backward-char)  ;; DEL
(global-set-key "\C-x\e\e" 'repeat-complex-command)  ;; ESC
When the key sequence includes function keys or mouse button events, or non-ASCII characters such as C-= or H-a, you must use the more general method of rebinding, which uses a vector to specify the key sequence.

The way to write a vector in Emacs Lisp is with square brackets around the vector elements. Use spaces to separate the elements. If an element is a symbol, simply write the symbol's name--no other delimiters or punctuation are needed. If a vector element is a character, write it as a Lisp character constant: `?' followed by the character as it would appear in a string.

Here are examples of using vectors to rebind C-= (a control character not in ASCII), C-M-= (not in ASCII because C-= is not), H-a (a Hyper character; ASCII doesn't have Hyper at all), F7 (a function key), and C-Mouse-1 (a keyboard-modified mouse button):
(global-set-key [?\C-=] 'make-symbolic-link)
(global-set-key [?\M-\C-=] 'make-symbolic-link)
(global-set-key [?\H-a] 'make-symbolic-link)
(global-set-key [f7] 'make-symbolic-link)
(global-set-key [C-mouse-1] 'make-symbolic-link)
You can use a vector for the simple cases too. Here's how to rewrite the first three examples above, using vectors to bind C-z, C-x l, and C-x TAB:
(global-set-key [?\C-z] 'shell)
(global-set-key [?\C-x ?l] 'make-symbolic-link)
(global-set-key [?\C-x ?\t] 'indent-rigidly)
(global-set-key [?\r] 'newline)
(global-set-key [?\d] 'delete-backward-char)
(global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command)
As you see, you represent a multi-character key sequence with a vector by listing each of the characters within the square brackets that delimit the vector.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.7 Rebinding Function Keys

Key sequences can contain function keys as well as ordinary characters. Just as Lisp characters (actually integers) represent keyboard characters, Lisp symbols represent function keys. If the function key has a word as its label, then that word is also the name of the corresponding Lisp symbol. Here are the conventional Lisp names for common function keys:

left, up, right, down
Cursor arrow keys.

begin, end, home, next, prior
Other cursor repositioning keys.

select, print, execute, backtab

insert, undo, redo, clearline

insertline, deleteline, insertchar, deletechar
Miscellaneous function keys.

f1, f2, ... f35
Numbered function keys (across the top of the keyboard).

kp-add, kp-subtract, kp-multiply, kp-divide

kp-backtab, kp-space, kp-tab, kp-enter

kp-separator, kp-decimal, kp-equal
Keypad keys (to the right of the regular keyboard), with names or punctuation.

kp-0, kp-1, ... kp-9
Keypad keys with digits.

kp-f1, kp-f2, kp-f3, kp-f4
Keypad PF keys.
These names are conventional, but some systems (especially when using X) may use different names. To make certain what symbol is used for a given function key on your terminal, type C-h c followed by that key.

A key sequence which contains function key symbols (or anything but ASCII characters) must be a vector rather than a string. The vector syntax uses spaces between the elements, and square brackets around the whole vector. Thus, to bind function key `f1' to the command rmail, write the following:
(global-set-key [f1] 'rmail)
To bind the right-arrow key to the command forward-char, you can use this expression:
(global-set-key [right] 'forward-char)
This uses the Lisp syntax for a vector containing the symbol right. (This binding is present in Emacs by default.)

See section AD.4.6 Rebinding Keys in Your Init File, for more information about using vectors for rebinding.

You can mix function keys and characters in a key sequence. This example binds C-x NEXT to the command forward-page.
(global-set-key [?\C-x next] 'forward-page)
where ?\C-x is the Lisp character constant for the character C-x. The vector element next is a symbol and therefore does not take a question mark.

You can use the modifier keys CTRL, META, HYPER, SUPER, ALT and SHIFT with function keys. To represent these modifiers, add the strings `C-', `M-', `H-', `s-', `A-' and `S-' at the front of the symbol name. Thus, here is how to make Hyper-Meta-RIGHT move forward a word:
(global-set-key [H-M-right] 'forward-word)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.8 Named ASCII Control Characters

TAB, RET, BS, LFD, ESC and DEL started out as names for certain ASCII control characters, used so often that they have special keys of their own. Later, users found it convenient to distinguish in Emacs between these keys and the "same" control characters typed with the CTRL key.

Emacs distinguishes these two kinds of input, when the keyboard reports these keys to Emacs. It treats the "special" keys as function keys named tab, return, backspace, linefeed, escape, and delete. These function keys translate automatically into the corresponding ASCII characters if they have no bindings of their own. As a result, neither users nor Lisp programs need to pay attention to the distinction unless they care to.

If you do not want to distinguish between (for example) TAB and C-i, make just one binding, for the ASCII character TAB (octal code 011). If you do want to distinguish, make one binding for this ASCII character, and another for the "function key" tab.

With an ordinary ASCII terminal, there is no way to distinguish between TAB and C-i (and likewise for other such pairs), because the terminal sends the same character in both cases.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.9 Non-ASCII Characters on the Keyboard

If your keyboard has keys that send non-ASCII characters, such as accented letters, rebinding these keys is a bit tricky. There are two solutions you can use. One is to specify a keyboard coding system, using set-keyboard-coding-system (see section Q.9 Specifying a Coding System). Then you can bind these keys in the usual way(16), like this:
(global-set-key [?char] 'some-function)
Type C-q followed by the key you want to bind, to insert char.

If you don't specify the keyboard coding system, that approach won't work. Instead, you need to find out the actual code that the terminal sends. The easiest way to do this in Emacs is to create an empty buffer with C-x b temp RET, make it unibyte with M-x toggle-enable-multibyte-characters RET, then type the key to insert the character into this buffer.

Move point before the character, then type C-x =. This displays a message in the minibuffer, showing the character code in three ways, octal, decimal and hexadecimal, all within a set of parentheses. Use the second of the three numbers, the decimal one, inside the vector to bind:
(global-set-key [decimal-code] 'some-function)
If you bind 8-bit characters like this in your init file, you may find it convenient to specify that it is unibyte. See section Q.2 Enabling Multibyte Characters.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.10 Rebinding Mouse Buttons

Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary mouse events in Emacs are click events; these happen when you press a button and release it without moving the mouse. You can also get drag events, when you move the mouse while holding the button down. Drag events happen when you finally let go of the button.

The symbols for basic click events are mouse-1 for the leftmost button, mouse-2 for the next, and so on. Here is how you can redefine the second mouse button to split the current window:
(global-set-key [mouse-2] 'split-window-vertically)
The symbols for drag events are similar, but have the prefix `drag-' before the word `mouse'. For example, dragging the first button generates a drag-mouse-1 event.

You can also define bindings for events that occur when a mouse button is pressed down. These events start with `down-' instead of `drag-'. Such events are generated only if they have key bindings. When you get a button-down event, a corresponding click or drag event will always follow.

If you wish, you can distinguish single, double, and triple clicks. A double click means clicking a mouse button twice in approximately the same place. The first click generates an ordinary click event. The second click, if it comes soon enough, generates a double-click event instead. The event type for a double-click event starts with `double-': for example, double-mouse-3.

This means that you can give a special meaning to the second click at the same place, but it must act on the assumption that the ordinary single click definition has run when the first click was received.

This constrains what you can do with double clicks, but user interface designers say that this constraint ought to be followed in any case. A double click should do something similar to the single click, only "more so." The command for the double-click event should perform the extra work for the double click.

If a double-click event has no binding, it changes to the corresponding single-click event. Thus, if you don't define a particular double click specially, it executes the single-click command twice.

Emacs also supports triple-click events whose names start with `triple-'. Emacs does not distinguish quadruple clicks as event types; clicks beyond the third generate additional triple-click events. However, the full number of clicks is recorded in the event list, so you can distinguish if you really want to. We don't recommend distinct meanings for more than three clicks, but sometimes it is useful for subsequent clicks to cycle through the same set of three meanings, so that four clicks are equivalent to one click, five are equivalent to two, and six are equivalent to three.

Emacs also records multiple presses in drag and button-down events. For example, when you press a button twice, then move the mouse while holding the button, Emacs gets a `double-drag-' event. And at the moment when you press it down for the second time, Emacs gets a `double-down-' event (which is ignored, like all button-down events, if it has no binding).

The variable double-click-time specifies how much time can elapse between clicks and still allow them to be grouped as a multiple click. Its value is in units of milliseconds. If the value is nil, double clicks are not detected at all. If the value is t, then there is no time limit. The default is 500.

The variable double-click-fuzz specifies how much the mouse can move between clicks still allow them to be grouped as a multiple click. Its value is in units of pixels on windowed displays and in units of 1/8 of a character cell on text-mode terminals; the default is 3.

The symbols for mouse events also indicate the status of the modifier keys, with the usual prefixes `C-', `M-', `H-', `s-', `A-' and `S-'. These always precede `double-' or `triple-', which always precede `drag-' or `down-'.

A frame includes areas that don't show text from the buffer, such as the mode line and the scroll bar. You can tell whether a mouse button comes from a special area of the screen by means of dummy "prefix keys." For example, if you click the mouse in the mode line, you get the prefix key mode-line before the ordinary mouse-button symbol. Thus, here is how to define the command for clicking the first button in a mode line to run scroll-up:
(global-set-key [mode-line mouse-1] 'scroll-up)
Here is the complete list of these dummy prefix keys and their meanings:

mode-line
The mouse was in the mode line of a window.
vertical-line
The mouse was in the vertical line separating side-by-side windows. (If you use scroll bars, they appear in place of these vertical lines.)
vertical-scroll-bar
The mouse was in a vertical scroll bar. (This is the only kind of scroll bar Emacs currently supports.)
You can put more than one mouse button in a key sequence, but it isn't usual to do so.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.4.11 Disabling Commands

Disabling a command marks the command as requiring confirmation before it can be executed. The purpose of disabling a command is to prevent beginning users from executing it by accident and being confused.

An attempt to invoke a disabled command interactively in Emacs displays a window containing the command's name, its documentation, and some instructions on what to do immediately; then Emacs asks for input saying whether to execute the command as requested, enable it and execute it, or cancel. If you decide to enable the command, you are asked whether to do this permanently or just for the current session. (Enabling permanently works by automatically editing your `.emacs' file.) You can also type ! to enable all commands, for the current session only.

The direct mechanism for disabling a command is to put a non-nil disabled property on the Lisp symbol for the command. Here is the Lisp program to do this:
(put 'delete-region 'disabled t)
If the value of the disabled property is a string, that string is included in the message displayed when the command is used:
(put 'delete-region 'disabled
     "It's better to use `kill-region' instead.\n")
You can make a command disabled either by editing the `.emacs' file directly or with the command M-x disable-command, which edits the `.emacs' file for you. Likewise, M-x enable-command edits `.emacs' to enable a command permanently. See section AD.7 The Init File, `~/.emacs'.

Whether a command is disabled is independent of what key is used to invoke it; disabling also applies if the command is invoked using M-x. Disabling a command has no effect on calling it as a function from Lisp programs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.5 Keyboard Translations

Some keyboards do not make it convenient to send all the special characters that Emacs uses. The most common problem case is the DEL character. Some keyboards provide no convenient way to type this very important character--usually because they were designed to expect the character C-h to be used for deletion. On these keyboards, if you press the key normally used for deletion, Emacs handles the C-h as a prefix character and offers you a list of help options, which is not what you want.

You can work around this problem within Emacs by setting up keyboard translations to turn C-h into DEL and DEL into C-h, as follows:
;; Translate C-h to DEL.
(keyboard-translate ?\C-h ?\C-?)

;; Translate DEL to C-h.
(keyboard-translate ?\C-? ?\C-h)
Keyboard translations are not the same as key bindings in keymaps (see section AD.4.1 Keymaps). Emacs contains numerous keymaps that apply in different situations, but there is only one set of keyboard translations, and it applies to every character that Emacs reads from the terminal. Keyboard translations take place at the lowest level of input processing; the keys that are looked up in keymaps contain the characters that result from keyboard translation.

On a window system, the keyboard key named DELETE is a function key and is distinct from the ASCII character named DEL. See section AD.4.8 Named ASCII Control Characters. Keyboard translations affect only ASCII character input, not function keys; thus, the above example used on a window system does not affect the DELETE key. However, the translation above isn't necessary on window systems, because Emacs can also distinguish between the BACKSPACE key and C-h; and it normally treats BACKSPACE as DEL.

For full information about how to use keyboard translations, see section `Translating Input' in The Emacs Lisp Reference Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.6 The Syntax Table

All the Emacs commands which parse words or balance parentheses are controlled by the syntax table. The syntax table says which characters are opening delimiters, which are parts of words, which are string quotes, and so on. It does this by assigning each character to one of fifteen-odd syntax classes. In some cases it specifies some additional information also.

Each major mode has its own syntax table (though related major modes sometimes share one syntax table) which it installs in each buffer that uses the mode. The syntax table installed in the current buffer is the one that all commands use, so we call it "the" syntax table.

To display a description of the contents of the current syntax table, type C-h s (describe-syntax). The description of each character includes both the string you would have to give to modify-syntax-entry to set up that character's current syntax, starting with the character which designates its syntax class, plus some English text to explain its meaning.

A syntax table is actually a Lisp object, a char-table, whose elements are cons cells. For full information on the syntax table, see section `Syntax Tables' in The Emacs Lisp Reference Manual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.7 The Init File, `~/.emacs'

When Emacs is started, it normally loads a Lisp program from the file `.emacs' or `.emacs.el' in your home directory. We call this file your init file because it specifies how to initialize Emacs for you. You can use the command line switch `-q' to prevent loading your init file, and `-u' (or `--user') to specify a different user's init file (see section C. Entering and Exiting Emacs).

There can also be a default init file, which is the library named `default.el', found via the standard search path for libraries. The Emacs distribution contains no such library; your site may create one for local customizations. If this library exists, it is loaded whenever you start Emacs (except when you specify `-q'). But your init file, if any, is loaded first; if it sets inhibit-default-init non-nil, then `default' is not loaded.

Your site may also have a site startup file; this is named `site-start.el', if it exists. Like `default.el', Emacs finds this file via the standard search path for Lisp libraries. Emacs loads this library before it loads your init file. To inhibit loading of this library, use the option `-no-site-file'. See section AE.2 Initial Options.

You can place `default.el' and `site-start.el' in any of the directories which Emacs searches for Lisp libraries. The variable load-path (see section V.7 Libraries of Lisp Code for Emacs) specifies these directories. Many sites put these files in the `site-lisp' subdirectory of the Emacs installation directory, typically `/usr/local/share/emacs/site-lisp'.

If you have a large amount of code in your `.emacs' file, you should rename it to `~/.emacs.el', and byte-compile it. See section `Byte Compilation' in the Emacs Lisp Reference Manual, for more information about compiling Emacs Lisp programs.

If you are going to write actual Emacs Lisp programs that go beyond minor customization, you should read the Emacs Lisp Reference Manual. See section `Emacs Lisp' in the Emacs Lisp Reference Manual.

AD.7.1 Init File Syntax

Syntax of constants in Emacs Lisp.

AD.7.2 Init File Examples

How to do some things with an init file.

AD.7.3 Terminal-specific Initialization

Each terminal type can have an init file.

AD.7.4 How Emacs Finds Your Init File

How Emacs finds the init file.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.7.1 Init File Syntax

The `.emacs' file contains one or more Lisp function call expressions. Each of these consists of a function name followed by arguments, all surrounded by parentheses. For example, (setq fill-column 60) calls the function setq to set the variable fill-column (see section T.5 Filling Text) to 60.

The second argument to setq is an expression for the new value of the variable. This can be a constant, a variable, or a function call expression. In `.emacs', constants are used most of the time. They can be:

Numbers:
Numbers are written in decimal, with an optional initial minus sign.

Strings:
Lisp string syntax is the same as C string syntax with a few extra features. Use a double-quote character to begin and end a string constant.
In a string, you can include newlines and special characters literally. But often it is cleaner to use backslash sequences for them: `\n' for newline, `\b' for backspace, `\r' for carriage return, `\t' for tab, `\f' for formfeed (control-L), `\e' for escape, `\\' for a backslash, `\"' for a double-quote, or `\ooo' for the character whose octal code is ooo. Backslash and double-quote are the only characters for which backslash sequences are mandatory.

`\C-' can be used as a prefix for a control character, as in `\C-s' for ASCII control-S, and `\M-' can be used as a prefix for a Meta character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A.

If you want to include non-ASCII characters in strings in your init file, you should consider putting a `-*-coding: coding-system-*-' tag on the first line which states the coding system used to save your `.emacs', as explained in Q.8 Recognizing Coding Systems. This is because the defaults for decoding non-ASCII text might not yet be set up by the time Emacs reads those parts of your init file which use such strings, possibly leading Emacs to decode those strings incorrectly.

Characters:
Lisp character constant syntax consists of a `?' followed by either a character or an escape sequence starting with `\'. Examples: ?x, ?\n, ?\", ?\). Note that strings and characters are not interchangeable in Lisp; some contexts require one and some contexts require the other.
See section AD.4.9 Non-ASCII Characters on the Keyboard, for information about binding commands to keys which send non-ASCII characters.

True:
t stands for `true'.

False:
nil stands for `false'.

Other Lisp objects:
Write a single-quote (') followed by the Lisp object you want.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.7.2 Init File Examples

Here are some examples of doing certain commonly desired things with Lisp expressions:

Make TAB in C mode just insert a tab if point is in the middle of a line.
(setq c-tab-always-indent nil)
Here we have a variable whose value is normally t for `true' and the alternative is nil for `false'.

Make searches case sensitive by default (in all buffers that do not override this).
(setq-default case-fold-search nil)
This sets the default value, which is effective in all buffers that do not have local values for the variable. Setting case-fold-search with setq affects only the current buffer's local value, which is not what you probably want to do in an init file.

Specify your own email address, if Emacs can't figure it out correctly.
(setq user-mail-address "coon@yoyodyne.com")
Various Emacs packages that need your own email address use the value of user-mail-address.

Make Text mode the default mode for new buffers.
(setq default-major-mode 'text-mode)
Note that text-mode is used because it is the command for entering Text mode. The single-quote before it makes the symbol a constant; otherwise, text-mode would be treated as a variable name.

Set up defaults for the Latin-1 character set which supports most of the languages of Western Europe.
(set-language-environment "Latin-1")
Turn on Auto Fill mode automatically in Text mode and related modes.
(add-hook 'text-mode-hook
  '(lambda () (auto-fill-mode 1)))
This shows how to add a hook function to a normal hook variable (see section AD.2.3 Hooks). The function we supply is a list starting with lambda, with a single-quote in front of it to make it a list constant rather than an expression.

It's beyond the scope of this manual to explain Lisp functions, but for this example it is enough to know that the effect is to execute (auto-fill-mode 1) when Text mode is entered. You can replace that with any other expression that you like, or with several expressions in a row.

Emacs comes with a function named turn-on-auto-fill whose definition is (lambda () (auto-fill-mode 1)). Thus, a simpler way to write the above example is as follows:
(add-hook 'text-mode-hook 'turn-on-auto-fill)
Load the installed Lisp library named `foo' (actually a file `foo.elc' or `foo.el' in a standard Emacs directory).
(load "foo")
When the argument to load is a relative file name, not starting with `/' or `~', load searches the directories in load-path (see section V.7 Libraries of Lisp Code for Emacs).

Load the compiled Lisp file `foo.elc' from your home directory.
(load "~/foo.elc")
Here an absolute file name is used, so no searching is done.

Tell Emacs to find the definition for the function myfunction by loading a Lisp library named `mypackage' (i.e. a file `mypackage.elc' or `mypackage.el'):
(autoload 'myfunction "mypackage" "Do what I say." t)
Here the string "Do what I say." is the function's documentation string. You specify it in the autoload definition so it will be available for help commands even when the package is not loaded. The last argument, t, indicates that this function is interactive; that is, it can be invoked interactively by typing M-x myfunction RET or by binding it to a key. If the function is not interactive, omit the t or use nil.

Rebind the key C-x l to run the function make-symbolic-link.
(global-set-key "\C-xl" 'make-symbolic-link)
or
(define-key global-map "\C-xl" 'make-symbolic-link)
Note once again the single-quote used to refer to the symbol make-symbolic-link instead of its value as a variable.

Do the same thing for Lisp mode only.
(define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
Redefine all keys which now run next-line in Fundamental mode so that they run forward-line instead.
(substitute-key-definition 'next-line 'forward-line
                           global-map)
Make C-x C-v undefined.
(global-unset-key "\C-x\C-v")
One reason to undefine a key is so that you can make it a prefix. Simply defining C-x C-v anything will make C-x C-v a prefix, but C-x C-v must first be freed of its usual non-prefix definition.

Make `$' have the syntax of punctuation in Text mode. Note the use of a character constant for `$'.
(modify-syntax-entry ?\$ "." text-mode-syntax-table)
Enable the use of the command narrow-to-region without confirmation.
(put 'narrow-to-region 'disabled nil)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.7.3 Terminal-specific Initialization

Each terminal type can have a Lisp library to be loaded into Emacs when it is run on that type of terminal. For a terminal type named termtype, the library is called `term/termtype' and it is found by searching the directories load-path as usual and trying the suffixes `.elc' and `.el'. Normally it appears in the subdirectory `term' of the directory where most Emacs libraries are kept.

The usual purpose of the terminal-specific library is to map the escape sequences used by the terminal's function keys onto more meaningful names, using function-key-map. See the file `term/lk201.el' for an example of how this is done. Many function keys are mapped automatically according to the information in the Termcap data base; the terminal-specific library needs to map only the function keys that Termcap does not specify.

When the terminal type contains a hyphen, only the part of the name before the first hyphen is significant in choosing the library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library `term/aaa'. The code in the library can use (getenv "TERM") to find the full terminal type name.

The library's name is constructed by concatenating the value of the variable term-file-prefix and the terminal type. Your `.emacs' file can prevent the loading of the terminal-specific library by setting term-file-prefix to nil.

Emacs runs the hook term-setup-hook at the end of initialization, after both your `.emacs' file and any terminal-specific library have been read in. Add hook functions to this hook if you wish to override part of any of the terminal-specific libraries and to define initializations for terminals that do not have a library. See section AD.2.3 Hooks.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.7.4 How Emacs Finds Your Init File

Normally Emacs uses the environment variable HOME to find `.emacs'; that's what `~' means in a file name. But if you run Emacs from a shell started by su, Emacs tries to find your own `.emacs', not that of the user you are currently pretending to be. The idea is that you should get your own editor customizations even if you are running as the super user.

More precisely, Emacs first determines which user's init file to use. It gets the user name from the environment variables LOGNAME and USER; if neither of those exists, it uses effective user-ID. If that user name matches the real user-ID, then Emacs uses HOME; otherwise, it looks up the home directory corresponding to that user name in the system's data base of users.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.8 Quitting and Aborting

C-g

C-BREAK (MS-DOS only)
Quit: cancel running or partially typed command.
C-]
Abort innermost recursive editing level and cancel the command which invoked it (abort-recursive-edit).
ESC ESC ESC
Either quit or abort, whichever makes sense (keyboard-escape-quit).
M-x top-level
Abort all recursive editing levels that are currently executing.
C-x u
Cancel a previously made change in the buffer contents (undo).
There are two ways of canceling commands which are not finished executing: quitting with C-g, and aborting with C-] or M-x top-level. Quitting cancels a partially typed command or one which is already running. Aborting exits a recursive editing level and cancels the command that invoked the recursive edit. (See section AC.26 Recursive Editing Levels.)

Quitting with C-g is used for getting rid of a partially typed command, or a numeric argument that you don't want. It also stops a running command in the middle in a relatively safe way, so you can use it if you accidentally give a command which takes a long time. In particular, it is safe to quit out of killing; either your text will all still be in the buffer, or it will all be in the kill ring (or maybe both). Quitting an incremental search does special things documented under searching; in general, it may take two successive C-g characters to get out of a search (see section K.1 Incremental Search).

On MS-DOS, the character C-BREAK serves as a quit character like C-g. The reason is that it is not feasible, on MS-DOS, to recognize C-g while a command is running, between interactions with the user. By contrast, it is feasible to recognize C-BREAK at all times. See section AH.1 Keyboard and Mouse on MS-DOS.

C-g works by setting the variable quit-flag to t the instant C-g is typed; Emacs Lisp checks this variable frequently and quits if it is non-nil. C-g is only actually executed as a command if you type it while Emacs is waiting for input. In that case, the command it runs is keyboard-quit.

If you quit with C-g a second time before the first C-g is recognized, you activate the "emergency escape" feature and return to the shell. See section AD.9.8 Emergency Escape.

There may be times when you cannot quit. When Emacs is waiting for the operating system to do something, quitting is impossible unless special pains are taken for the particular system call within Emacs where the waiting occurs. We have done this for the system calls that users are likely to want to quit from, but it's possible you will find another. In one very common case--waiting for file input or output using NFS--Emacs itself knows how to quit, but many NFS implementations simply do not allow user programs to stop waiting for NFS when the NFS server is hung.

Aborting with C-] (abort-recursive-edit) is used to get out of a recursive editing level and cancel the command which invoked it. Quitting with C-g does not do this, and could not do this, because it is used to cancel a partially typed command within the recursive editing level. Both operations are useful. For example, if you are in a recursive edit and type C-u 8 to enter a numeric argument, you can cancel that argument with C-g and remain in the recursive edit.

The command ESC ESC ESC (keyboard-escape-quit) can either quit or abort. This key was defined because ESC is used to "get out" in many PC programs. It can cancel a prefix argument, clear a selected region, or get out of a Query Replace, like C-g. It can get out of the minibuffer or a recursive edit, like C-]. It can also get out of splitting the frame into multiple windows, like C-x 1. One thing it cannot do, however, is stop a command that is running. That's because it executes as an ordinary command, and Emacs doesn't notice it until it is ready for a command.

The command M-x top-level is equivalent to "enough" C-] commands to get you out of all the levels of recursive edits that you are in. C-] gets you out one level at a time, but M-x top-level goes out all levels at once. Both C-] and M-x top-level are like all other commands, and unlike C-g, in that they take effect only when Emacs is ready for a command. C-] is an ordinary key and has its meaning only because of its binding in the keymap. See section AC.26 Recursive Editing Levels.

C-x u (undo) is not strictly speaking a way of canceling a command, but you can think of it as canceling a command that already finished executing. See section D.4 Undoing Changes, for more information about the undo facility.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9 Dealing with Emacs Trouble

This section describes various conditions in which Emacs fails to work normally, and how to recognize them and correct them. For a list of additional problems you might encounter, see section `Bugs and problems' in GNU Emacs FAQ, and the file `etc/PROBLEMS' in the Emacs distribution. Type C-h F to read the FAQ; type C-h P to read the `PROBLEMS' file.

AD.9.1 If DEL Fails to Delete

What to do if DEL doesn't delete.

AD.9.2 Recursive Editing Levels

`[...]' in mode line around the parentheses.

AD.9.3 Garbage on the Screen

Garbage on the screen.

AD.9.4 Garbage in the Text

Garbage in the text.

AD.9.5 Spontaneous Entry to Incremental Search

Spontaneous entry to incremental search.

AD.9.6 Running out of Memory

How to cope when you run out of memory.

AD.9.7 Recovery After a Crash

Recovering editing in an Emacs session that crashed.

AD.9.8 Emergency Escape

Emergency escape--- What to do if Emacs stops responding.

AD.9.9 Help for Total Frustration

When you are at your wits' end.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.1 If DEL Fails to Delete

Every keyboard has a large key, a little ways above the RET or ENTER key, which you normally use outside Emacs to erase the last character that you typed. We call this key the usual erasure key. In Emacs, it is supposed to be equivalent to DEL, and when Emacs is properly configured for your terminal, it translates that key into the character DEL.

When Emacs starts up using a window system, it determines automatically which key should be DEL. In some unusual cases Emacs gets the wrong information from the system. If the usual erasure key deletes forwards instead of backwards, that is probably what happened--Emacs ought to be treating the DELETE key as DEL, but it isn't.

With a window system, if the usual erasure key is labeled BACKSPACE and there is a DELETE key elsewhere, but the DELETE key deletes backward instead of forward, that too suggests Emacs got the wrong information--but in the opposite sense. It ought to be treating the BACKSPACE key as DEL, and treating DELETE differently, but it isn't.

On a text-only terminal, if you find the usual erasure key prompts for a Help command, like Control-h, instead of deleting a character, it means that key is actually sending the BS character. Emacs ought to be treating BS as DEL, but it isn't.

In all of those cases, the immediate remedy is the same: use the command M-x normal-erase-is-backspace-mode. This toggles between the two modes that Emacs supports for handling DEL, so if Emacs starts in the wrong mode, it should switch to the right mode. On a text-only terminal, if you want to ask for help when BS is treated as DEL, use F1; C-? may also work, if it sends character code 127.

To fix the problem automatically for every Emacs session, you can put one of the following lines into your `.emacs' file (see section AD.7 The Init File, `~/.emacs'). For the first case above, where DELETE deletes forwards instead of backwards, use this line to make DELETE act as DEL (resulting in behavior compatible with Emacs 20 and previous versions):
(normal-erase-is-backspace-mode 0)
For the other two cases, where BACKSPACE ought to act as DEL, use this line:
(normal-erase-is-backspace-mode 1)
Another way to fix the problem for every Emacs session is to customize the variable normal-erase-is-backspace: the value t specifies the mode where BS or BACKSPACE is DEL, and nil specifies the other mode. See section AD.2.2 Easy Customization Interface.

With a window system, it can also happen that the usual erasure key is labeled BACKSPACE, there is a DELETE key elsewhere, and both keys delete forward. This probably means that someone has redefined your BACKSPACE key as a DELETE key. With X, this is typically done with a command to the xmodmap program when you start the server or log in. The most likely motive for this customization was to support old versions of Emacs, so we recommend you simply remove it now.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.2 Recursive Editing Levels

Recursive editing levels are important and useful features of Emacs, but they can seem like malfunctions to the user who does not understand them.

If the mode line has square brackets `[...]' around the parentheses that contain the names of the major and minor modes, you have entered a recursive editing level. If you did not do this on purpose, or if you don't understand what that means, you should just get out of the recursive editing level. To do so, type M-x top-level. This is called getting back to top level. See section AC.26 Recursive Editing Levels.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.3 Garbage on the Screen

If the data on the screen looks wrong, the first thing to do is see whether the text is really wrong. Type C-l to redisplay the entire screen. If the screen appears correct after this, the problem was entirely in the previous screen update. (Otherwise, see the following section.)

Display updating problems often result from an incorrect termcap entry for the terminal you are using. The file `etc/TERMS' in the Emacs distribution gives the fixes for known problems of this sort. `INSTALL' contains general advice for these problems in one of its sections. Very likely there is simply insufficient padding for certain display operations. To investigate the possibility that you have this sort of problem, try Emacs on another terminal made by a different manufacturer. If problems happen frequently on one kind of terminal but not another kind, it is likely to be a bad termcap entry, though it could also be due to a bug in Emacs that appears for terminals that have or that lack specific features.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.4 Garbage in the Text

If C-l shows that the text is wrong, try undoing the changes to it using C-x u until it gets back to a state you consider correct. Also try C-h l to find out what command you typed to produce the observed results.

If a large portion of text appears to be missing at the beginning or end of the buffer, check for the word `Narrow' in the mode line. If it appears, the text you don't see is probably still present, but temporarily off-limits. To make it accessible again, type C-x n w. See section AC.22 Narrowing.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.5 Spontaneous Entry to Incremental Search

If Emacs spontaneously displays `I-search:' at the bottom of the screen, it means that the terminal is sending C-s and C-q according to the poorly designed xon/xoff "flow control" protocol.

If this happens to you, your best recourse is to put the terminal in a mode where it will not use flow control, or give it so much padding that it will never send a C-s. (One way to increase the amount of padding is to set the variable baud-rate to a larger value. Its value is the terminal output speed, measured in the conventional units of baud.)

If you don't succeed in turning off flow control, the next best thing is to tell Emacs to cope with it. To do this, call the function enable-flow-control.

Typically there are particular terminal types with which you must use flow control. You can conveniently ask for flow control on those terminal types only, using enable-flow-control-on. For example, if you find you must use flow control on VT-100 and H19 terminals, put the following in your `.emacs' file:
(enable-flow-control-on "vt100" "h19")
When flow control is enabled, you must type C-\ to get the effect of a C-s, and type C-^ to get the effect of a C-q. (These aliases work by means of keyboard translations; see AD.5 Keyboard Translations.)

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.6 Running out of Memory

If you get the error message `Virtual memory exceeded', save your modified buffers with C-x s. This method of saving them has the smallest need for additional memory. Emacs keeps a reserve of memory which it makes available when this error happens; that should be enough to enable C-x s to complete its work.

Once you have saved your modified buffers, you can exit this Emacs job and start another, or you can use M-x kill-some-buffers to free space in the current Emacs job. If you kill buffers containing a substantial amount of text, you can safely go on editing. Emacs refills its memory reserve automatically when it sees sufficient free space available, in case you run out of memory another time.

Do not use M-x buffer-menu to save or kill buffers when you run out of memory, because the buffer menu needs a fair amount of memory itself, and the reserve supply may not be enough.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.7 Recovery After a Crash

If Emacs or the computer crashes, you can recover the files you were editing at the time of the crash from their auto-save files. To do this, start Emacs again and type the command M-x recover-session.

This command initially displays a buffer which lists interrupted session files, each with its date. You must choose which session to recover from. Typically the one you want is the most recent one. Move point to the one you choose, and type C-c C-c.

Then recover-session asks about each of the files that you were editing during that session; it asks whether to recover that file. If you answer y for a file, it shows the dates of that file and its auto-save file, then asks once again whether to recover that file. For the second question, you must confirm with yes. If you do, Emacs visits the file but gets the text from the auto-save file.

When recover-session is done, the files you've chosen to recover are present in Emacs buffers. You should then save them. Only this--saving them--updates the files themselves.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.8 Emergency Escape

Because at times there have been bugs causing Emacs to loop without checking quit-flag, a special feature causes Emacs to be suspended immediately if you type a second C-g while the flag is already set, so you can always get out of GNU Emacs. Normally Emacs recognizes and clears quit-flag (and quits!) quickly enough to prevent this from happening. (On MS-DOS and compatible systems, type C-BREAK twice.)

When you resume Emacs after a suspension caused by multiple C-g, it asks two questions before going back to what it had been doing:
Auto-save? (y or n)
Abort (and dump core)? (y or n)
Answer each one with y or n followed by RET.

Saying y to `Auto-save?' causes immediate auto-saving of all modified buffers in which auto-saving is enabled.

Saying y to `Abort (and dump core)?' causes an illegal instruction to be executed, dumping core. This is to enable a wizard to figure out why Emacs was failing to quit in the first place. Execution does not continue after a core dump. If you answer n, execution does continue. With luck, GNU Emacs will ultimately check quit-flag and quit normally. If not, and you type another C-g, it is suspended again.

If Emacs is not really hung, just slow, you may invoke the double C-g feature without really meaning to. Then just resume and answer n to both questions, and you will arrive at your former state. Presumably the quit you requested will happen soon.

The double C-g feature is turned off when Emacs is running under the X Window System, since you can use the window manager to kill Emacs or to create another window and run another program.

On MS-DOS and compatible systems, the emergency escape feature is sometimes unavailable, even if you press C-BREAK twice, when some system call (MS-DOS or BIOS) hangs, or when Emacs is stuck in a very tight endless loop (in C code, not in Lisp code).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.9.9 Help for Total Frustration

If using Emacs (or something else) becomes terribly frustrating and none of the techniques described above solve the problem, Emacs can still help you.

First, if the Emacs you are using is not responding to commands, type C-g C-g to get out of it and then start a new one.

Second, type M-x doctor RET.

The doctor will help you feel better. Each time you say something to the doctor, you must end it by typing RET RET. This lets the doctor know you are finished.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.10 Reporting Bugs

Sometimes you will encounter a bug in Emacs. Although we cannot promise we can or will fix the bug, and we might not even agree that it is a bug, we want to hear about problems you encounter. Often we agree they are bugs and want to fix them.

To make it possible for us to fix a bug, you must report it. In order to do so effectively, you must know when and how to do it.

Before reporting a bug, it is a good idea to see if it is already known. You can find the list of known problems in the file `etc/PROBLEMS' in the Emacs distribution; type C-h P to read it. Some additional user-level problems can be found in section `Bugs and problems' in GNU Emacs FAQ. Looking up your problem in these two documents might provide you with a solution or a work-around, or give you additional information about related issues.

AD.10.1 When Is There a Bug

Have you really found a bug?

AD.10.2 Understanding Bug Reporting

How to report a bug effectively.

AD.10.3 Checklist for Bug Reports

Steps to follow for a good bug report.

AD.10.4 Sending Patches for GNU Emacs

How to send a patch for GNU Emacs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.10.1 When Is There a Bug

If Emacs executes an illegal instruction, or dies with an operating system error message that indicates a problem in the program (as opposed to something like "disk full"), then it is certainly a bug.

If Emacs updates the display in a way that does not correspond to what is in the buffer, then it is certainly a bug. If a command seems to do the wrong thing but the problem corrects itself if you type C-l, it is a case of incorrect display updating.

Taking forever to complete a command can be a bug, but you must make certain that it was really Emacs's fault. Some commands simply take a long time. Type C-g (C-BREAK on MS-DOS) and then C-h l to see whether the input Emacs received was what you intended to type; if the input was such that you know it should have been processed quickly, report a bug. If you don't know whether the command should take a long time, find out by looking in the manual or by asking for assistance.

If a command you are familiar with causes an Emacs error message in a case where its usual definition ought to be reasonable, it is probably a bug.

If a command does the wrong thing, that is a bug. But be sure you know for certain what it ought to have done. If you aren't familiar with the command, or don't know for certain how the command is supposed to work, then it might actually be working right. Rather than jumping to conclusions, show the problem to someone who knows for certain.

Finally, a command's intended definition may not be the best possible definition for editing with. This is a very important sort of problem, but it is also a matter of judgment. Also, it is easy to come to such a conclusion out of ignorance of some of the existing features. It is probably best not to complain about such a problem until you have checked the documentation in the usual ways, feel confident that you understand it, and know for certain that what you want is not available. If you are not sure what the command is supposed to do after a careful reading of the manual, check the index and glossary for any terms that may be unclear.

If after careful rereading of the manual you still do not understand what the command should do, that indicates a bug in the manual, which you should report. The manual's job is to make everything clear to people who are not Emacs experts--including you. It is just as important to report documentation bugs as program bugs.

If the on-line documentation string of a function or variable disagrees with the manual, one of them must be wrong; that is a bug.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.10.2 Understanding Bug Reporting

When you decide that there is a bug, it is important to report it and to report it in a way which is useful. What is most useful is an exact description of what commands you type, starting with the shell command to run Emacs, until the problem happens.

The most important principle in reporting a bug is to report facts. Hypotheses and verbal descriptions are no substitute for the detailed raw data. Reporting the facts is straightforward, but many people strain to posit explanations and report them instead of the facts. If the explanations are based on guesses about how Emacs is implemented, they will be useless; meanwhile, lacking the facts, we will have no real information about the bug.

For example, suppose that you type C-x C-f /glorp/baz.ugh RET, visiting a file which (you know) happens to be rather large, and Emacs displayed `I feel pretty today'. The best way to report the bug is with a sentence like the preceding one, because it gives all the facts.

A bad way would be to assume that the problem is due to the size of the file and say, "I visited a large file, and Emacs displayed `I feel pretty today'." This is what we mean by "guessing explanations." The problem is just as likely to be due to the fact that there is a `z' in the file name. If this is so, then when we got your report, we would try out the problem with some "large file," probably with no `z' in its name, and not see any problem. There is no way in the world that we could guess that we should try visiting a file with a `z' in its name.

Alternatively, the problem might be due to the fact that the file starts with exactly 25 spaces. For this reason, you should make sure that you inform us of the exact contents of any file that is needed to reproduce the bug. What if the problem only occurs when you have typed the C-x C-a command previously? This is why we ask you to give the exact sequence of characters you typed since starting the Emacs session.

You should not even say "visit a file" instead of C-x C-f unless you know that it makes no difference which visiting command is used. Similarly, rather than saying "if I have three characters on the line," say "after I type RET A B C RET C-p," if that is the way you entered the text.

So please don't guess any explanations when you report a bug. If you want to actually debug the problem, and report explanations that are more than guesses, that is useful--but please include the facts as well.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.10.3 Checklist for Bug Reports

The best way to send a bug report is to mail it electronically to the Emacs maintainers at bug-gnu-emacs@gnu.org, or to emacs-pretest-bug@gnu.org if you are pretesting an Emacs beta release. (If you want to suggest a change as an improvement, use the same address.)

If you'd like to read the bug reports, you can find them on the newsgroup `gnu.emacs.bug'; keep in mind, however, that as a spectator you should not criticize anything about what you see there. The purpose of bug reports is to give information to the Emacs maintainers. Spectators are welcome only as long as they do not interfere with this. In particular, some bug reports contain fairly large amounts of data; spectators should not complain about this.

Please do not post bug reports using netnews; mail is more reliable than netnews about reporting your correct address, which we may need in order to ask you for more information. If your data is more than 500,000 bytes, please don't include it directly in the bug report; instead, offer to send it on request, or make it available by ftp and say where.

If you can't send electronic mail, then mail the bug report on paper or machine-readable media to this address:
GNU Emacs Bugs
Free Software Foundation
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
We do not promise to fix the bug; but if the bug is serious, or ugly, or easy to fix, chances are we will want to.

A convenient way to send a bug report for Emacs is to use the command M-x report-emacs-bug. This sets up a mail buffer (see section Z. Sending Mail) and automatically inserts some of the essential information. However, it cannot supply all the necessary information; you should still read and follow the guidelines below, so you can enter the other crucial information by hand before you send the message.

To enable maintainers to investigate a bug, your report should include all these things:

The version number of Emacs. Without this, we won't know whether there is any point in looking for the bug in the current version of GNU Emacs.
You can get the version number by typing M-x emacs-version RET. If that command does not work, you probably have something other than GNU Emacs, so you will have to report the bug somewhere else.

The type of machine you are using, and the operating system name and version number. M-x emacs-version RET provides this information too. Copy its output from the `*Messages*' buffer, so that you get it all and get it accurately.

The operands given to the configure command when Emacs was installed.

A complete list of any modifications you have made to the Emacs source. (We may not have time to investigate the bug unless it happens in an unmodified Emacs. But if you've made modifications and you don't tell us, you are sending us on a wild goose chase.)
Be precise about these changes. A description in English is not enough--send a context diff for them.

Adding files of your own, or porting to another machine, is a modification of the source.

Details of any other deviations from the standard procedure for installing GNU Emacs.

The complete text of any files needed to reproduce the bug.
If you can tell us a way to cause the problem without visiting any files, please do so. This makes it much easier to debug. If you do need files, make sure you arrange for us to see their exact contents. For example, it can often matter whether there are spaces at the ends of lines, or a newline after the last line in the buffer (nothing ought to care whether the last line is terminated, but try telling the bugs that).

The precise commands we need to type to reproduce the bug.
The easy way to record the input to Emacs precisely is to write a dribble file. To start the file, execute the Lisp expression
(open-dribble-file "~/dribble")
using M-: or from the `*scratch*' buffer just after starting Emacs. From then on, Emacs copies all your input to the specified dribble file until the Emacs process is killed.

For possible display bugs, the terminal type (the value of environment variable TERM), the complete termcap entry for the terminal from `/etc/termcap' (since that file is not identical on all machines), and the output that Emacs actually sent to the terminal.
The way to collect the terminal output is to execute the Lisp expression
(open-termscript "~/termscript")
using M-: or from the `*scratch*' buffer just after starting Emacs. From then on, Emacs copies all terminal output to the specified termscript file as well, until the Emacs process is killed. If the problem happens when Emacs starts up, put this expression into your `.emacs' file so that the termscript file will be open when Emacs displays the screen for the first time.

Be warned: it is often difficult, and sometimes impossible, to fix a terminal-dependent bug without access to a terminal of the type that stimulates the bug.

If non-ASCII text or internationalization is relevant, the locale that was current when you started Emacs. On GNU/Linux and Unix systems, or if you use a Posix-style shell such as Bash, you can use this shell command to view the relevant values:
echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_TYPE=$LC_TYPE \
  LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG
Alternatively, use the locale command, if your system has it, to display your locale settings.

You can use the M-! command to execute these commands from Emacs, and then copy the output from the `*Messages*' buffer into the bug report. Alternatively, M-x getenv RET LC_ALL RET will display the value of LC_ALL in the echo area, and you can copy its output from the `*Messages*' buffer.

A description of what behavior you observe that you believe is incorrect. For example, "The Emacs process gets a fatal signal," or, "The resulting text is as follows, which I think is wrong."
Of course, if the bug is that Emacs gets a fatal signal, then one can't miss it. But if the bug is incorrect text, the maintainer might fail to notice what is wrong. Why leave it to chance?

Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of the source is out of sync, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and the copy here might not. If you said to expect a crash, then when Emacs here fails to crash, we would know that the bug was not happening. If you don't say to expect a crash, then we would not know whether the bug was happening--we would not be able to draw any conclusion from our observations.

If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual fails to describe the actual behavior of Emacs, or that the text is confusing, copy in the text from the online manual which you think is at fault. If the section is small, just the section name is enough.

If the manifestation of the bug is an Emacs error message, it is important to report the precise text of the error message, and a backtrace showing how the Lisp program in Emacs arrived at the error.
To get the error message text accurately, copy it from the `*Messages*' buffer into the bug report. Copy all of it, not just part.

To make a backtrace for the error, use M-x toggle-debug-on-error before the error happens (that is to say, you must give that command and then make the bug happen). This causes the error to run the Lisp debugger, which shows you a backtrace. Copy the text of the debugger's backtrace into the bug report. See section `The Lisp Debugger' in the Emacs Lisp Reference Manual, for information on debugging Emacs Lisp programs with the Edebug package.

This use of the debugger is possible only if you know how to make the bug happen again. If you can't make it happen again, at least copy the whole error message.

Check whether any programs you have loaded into the Lisp world, including your `.emacs' file, set any variables that may affect the functioning of Emacs. Also, see whether the problem happens in a freshly started Emacs without loading your `.emacs' file (start Emacs with the -q switch to prevent loading the init file). If the problem does not occur then, you must report the precise contents of any programs that you must load into the Lisp world in order to cause the problem to occur.

If the problem does depend on an init file or other Lisp programs that are not part of the standard Emacs system, then you should make sure it is not a bug in those programs by complaining to their maintainers first. After they verify that they are using Emacs in a way that is supposed to work, they should report the bug.

If you wish to mention something in the GNU Emacs source, show the line of code with a few lines of context. Don't just give a line number.
The line numbers in the development sources don't match those in your sources. It would take extra work for the maintainers to determine what code is in your version at a given line number, and we could not be certain.

Additional information from a C debugger such as GDB might enable someone to find a problem on a machine which he does not have available. If you don't know how to use GDB, please read the GDB manual--it is not very long, and using GDB is easy. You can find the GDB distribution, including the GDB manual in online form, in most of the same places you can find the Emacs distribution. To run Emacs under GDB, you should switch to the `src' subdirectory in which Emacs was compiled, then do `gdb emacs'. It is important for the directory `src' to be current so that GDB will read the `.gdbinit' file in this directory.
However, you need to think when you collect the additional information if you want it to show what causes the bug.

For example, many people send just a backtrace, but that is not very useful by itself. A simple backtrace with arguments often conveys little about what is happening inside GNU Emacs, because most of the arguments listed in the backtrace are pointers to Lisp objects. The numeric values of these pointers have no significance whatever; all that matters is the contents of the objects they point to (and most of the contents are themselves pointers).

To provide useful information, you need to show the values of Lisp objects in Lisp notation. Do this for each variable which is a Lisp object, in several stack frames near the bottom of the stack. Look at the source to see which variables are Lisp objects, because the debugger thinks of them as integers.

To show a variable's value in Lisp syntax, first print its value, then use the user-defined GDB command pr to print the Lisp object in Lisp syntax. (If you must use another debugger, call the function debug_print with the object as an argument.) The pr command is defined by the file `.gdbinit', and it works only if you are debugging a running process (not with a core dump).

To make Lisp errors stop Emacs and return to GDB, put a breakpoint at Fsignal.

For a short listing of Lisp functions running, type the GDB command xbacktrace.

The file `.gdbinit' defines several other commands that are useful for examining the data types and contents of Lisp objects. Their names begin with `x'. These commands work at a lower level than pr, and are less convenient, but they may work even when pr does not, such as when debugging a core dump or when Emacs has had a fatal signal.

More detailed advice and other useful techniques for debugging Emacs are available in the file `etc/DEBUG' in the Emacs distribution. That file also includes instructions for investigating problems whereby Emacs stops responding (many people assume that Emacs is "hung," whereas in fact it might be in an infinite loop).

To find the file `etc/DEBUG' in your Emacs installation, use the directory name stored in the variable data-directory.

Here are some things that are not necessary in a bug report:

A description of the envelope of the bug--this is not necessary for a reproducible bug.
Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it.

This is often time-consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. You might as well save time by not searching for additional examples. It is better to send the bug report right away, go back to editing, and find another bug to report.

Of course, if you can find a simpler example to report instead of the original one, that is a convenience. Errors in the output will be easier to spot, running under the debugger will take less time, etc.

However, simplification is not vital; if you can't do this or don't have time to try, please report the bug with your original test case.

A core dump file.
Debugging the core dump might be useful, but it can only be done on your machine, with your Emacs executable. Therefore, sending the core dump file to the Emacs maintainers won't be useful. Above all, don't include the core file in an email bug report! Such a large message can be extremely inconvenient.

A system-call trace of Emacs execution.
System-call traces are very useful for certain special kinds of debugging, but in most cases they give little useful information. It is therefore strange that many people seem to think that the way to report information about a crash is to send a system-call trace. Perhaps this is a habit formed from experience debugging programs that don't have source code or debugging symbols.

In most programs, a backtrace is normally far, far more informative than a system-call trace. Even in Emacs, a simple backtrace is generally more informative, though to give full information you should supplement the backtrace by displaying variable values and printing them as Lisp objects with pr (see above).

A patch for the bug.
A patch for the bug is useful if it is a good one. But don't omit the other information that a bug report needs, such as the test case, on the assumption that a patch is sufficient. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. And if we can't understand what bug you are trying to fix, or why your patch should be an improvement, we mustn't install it.

See section AD.10.4 Sending Patches for GNU Emacs, for guidelines on how to make it easy for us to understand and install your patches.

A guess about what the bug is or what it depends on.
Such guesses are usually wrong. Even experts can't guess right about such things without first using the debugger to find the facts.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.10.4 Sending Patches for GNU Emacs

If you would like to write bug fixes or improvements for GNU Emacs, that is very helpful. When you send your changes, please follow these guidelines to make it easy for the maintainers to use them. If you don't follow these guidelines, your information might still be useful, but using it will take extra work. Maintaining GNU Emacs is a lot of work in the best of circumstances, and we can't keep up unless you do your best to help.

Send an explanation with your changes of what problem they fix or what improvement they bring about. For a bug fix, just include a copy of the bug report, and explain why the change fixes the bug.
(Referring to a bug report is not as good as including it, because then we will have to look it up, and we have probably already deleted it if we've already fixed the bug.)

Always include a proper bug report for the problem you think you have fixed. We need to convince ourselves that the change is right before installing it. Even if it is correct, we might have trouble understanding it if we don't have a way to reproduce the problem.

Include all the comments that are appropriate to help people reading the source in the future understand why this change was needed.

Don't mix together changes made for different reasons. Send them individually.
If you make two changes for separate reasons, then we might not want to install them both. We might want to install just one. If you send them all jumbled together in a single set of diffs, we have to do extra work to disentangle them--to figure out which parts of the change serve which purpose. If we don't have time for this, we might have to ignore your changes entirely.

If you send each change as soon as you have written it, with its own explanation, then two changes never get tangled up, and we can consider each one properly without any extra work to disentangle them.

Send each change as soon as that change is finished. Sometimes people think they are helping us by accumulating many changes to send them all together. As explained above, this is absolutely the worst thing you could do.
Since you should send each change separately, you might as well send it right away. That gives us the option of installing it immediately if it is important.

Use `diff -c' to make your diffs. Diffs without context are hard to install reliably. More than that, they are hard to study; we must always study a patch to decide whether we want to install it. Unidiff format is better than contextless diffs, but not as easy to read as `-c' format.
If you have GNU diff, use `diff -c -F'^[_a-zA-Z0-9$]+ *('' when making diffs of C code. This shows the name of the function that each change occurs in.

Avoid any ambiguity as to which is the old version and which is the new. Please make the old version the first argument to diff, and the new version the second argument. And please give one version or the other a name that indicates whether it is the old version or your new changed one.

Write the change log entries for your changes. This is both to save us the extra work of writing them, and to help explain your changes so we can understand them.
The purpose of the change log is to show people where to find what was changed. So you need to be specific about what functions you changed; in large functions, it's often helpful to indicate where within the function the change was.

On the other hand, once you have shown people where to find the change, you need not explain its purpose in the change log. Thus, if you add a new function, all you need to say about it is that it is new. If you feel that the purpose needs explaining, it probably does--but put the explanation in comments in the code. It will be more useful there.

Please read the `ChangeLog' files in the `src' and `lisp' directories to see what sorts of information to put in, and to learn the style that we use. If you would like your name to appear in the header line, showing who made the change, send us the header line. See section W.1 Change Logs.

When you write the fix, keep in mind that we can't install a change that would break other systems. Please think about what effect your change will have if compiled on another type of system.
Sometimes people send fixes that might be an improvement in general--but it is hard to be sure of this. It's hard to install such changes because we have to study them very carefully. Of course, a good explanation of the reasoning by which you concluded the change was correct can help convince us.

The safest changes are changes to the configuration files for a particular machine. These are safe because they can't create new bugs on other machines.

Please help us keep up with the workload by designing the patch in a form that is clearly safe to install.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.11 Contributing to Emacs Development

If you would like to help pretest Emacs releases to assure they work well, or if you would like to work on improving Emacs, please contact the maintainers at bug-gnu-emacs@gnu.org. A pretester should be prepared to investigate bugs as well as report them. If you'd like to work on improving Emacs, please ask for suggested projects or suggest your own ideas.

If you have already written an improvement, please tell us about it. If you have not yet started work, it is useful to contact bug-gnu-emacs@gnu.org before you start; it might be possible to suggest ways to make your extension fit in better with the rest of Emacs.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AD.12 How To Get Help with GNU Emacs

If you need help installing, using or changing GNU Emacs, there are two ways to find it:

Send a message to the mailing list help-gnu-emacs@gnu.org, or post your request on newsgroup gnu.emacs.help. (This mailing list and newsgroup interconnect, so it does not matter which one you use.)

Look in the service directory for someone who might help you for a fee. The service directory is found in the file named `etc/SERVICE' in the Emacs distribution.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE. Command Line Arguments

GNU Emacs supports command line arguments to request various actions when invoking Emacs. These are for compatibility with other editors and for sophisticated activities. We don't recommend using them for ordinary editing.

Arguments starting with `-' are options. Other arguments specify files to visit. Emacs visits the specified files while it starts up. The last file name on your command line becomes the current buffer; the other files are also visited in other buffers. If there are two files, they are both displayed; otherwise the last file is displayed along with a buffer list that shows what other buffers there are. As with most programs, the special argument `--' says that all subsequent arguments are file names, not options, even if they start with `-'.

Emacs command options can specify many things, such as the size and position of the X window Emacs uses, its colors, and so on. A few options support advanced usage, such as running Lisp functions on files in batch mode. The sections of this chapter describe the available options, arranged according to their purpose.

There are two ways of writing options: the short forms that start with a single `-', and the long forms that start with `--'. For example, `-d' is a short form and `--display' is the corresponding long form.

The long forms with `--' are easier to remember, but longer to type. However, you don't have to spell out the whole option name; any unambiguous abbreviation is enough. When a long option takes an argument, you can use either a space or an equal sign to separate the option name and the argument. Thus, you can write either `--display sugar-bombs:0.0' or `--display=sugar-bombs:0.0'. We recommend an equal sign because it makes the relationship clearer, and the tables below always show an equal sign.

Most options specify how to initialize Emacs, or set parameters for the Emacs session. We call them initial options. A few options specify things to do: for example, load libraries, call functions, or terminate Emacs. These are called action options. These and file names together are called action arguments. Emacs processes all the action arguments in the order they are written.

AE.1 Action Arguments

Arguments to visit files, load libraries, and call functions.

AE.2 Initial Options

Arguments that take effect while starting Emacs.

AE.3 Command Argument Example

Examples of using command line arguments.

AE.4 Resuming Emacs with Arguments

Specifying arguments when you resume a running Emacs.

AE.5 Environment Variables

Environment variables that Emacs uses.

AE.6 Specifying the Display Name

Changing the default display and using remote login.

AE.7 Font Specification Options

Choosing a font for text, under X.

AE.8 Window Color Options

Choosing colors, under X.

AE.9 Options for Window Geometry

Start-up window size, under X.

AE.10 Internal and External Borders

Internal and external borders, under X.

AE.11 Frame Titles

Specifying the initial frame's title.

AE.12 Icons

Choosing what sort of icon to use, under X.

AE.13 X Resources

Advanced use of classes and resources, under X.

AE.14 Lucid Menu X Resources

X resources for Lucid menus.

AE.15 LessTif Menu X Resources

X resources for LessTif and Motif menus.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.1 Action Arguments

Here is a table of the action arguments and options:

`file'

`--visit=file'

`--file=file'
Visit file using find-file. See section M.2 Visiting Files.

`+linenum file'
Visit file using find-file, then go to line number linenum in it.

`+linenum:columnnum file'
Visit file using find-file, then go to line number linenum and put point at column number columnnum.

`-l file'

`--load=file'
Load a Lisp library named file with the function load. See section V.7 Libraries of Lisp Code for Emacs. The library can be found either in the current directory, or in the Emacs library search path as specified with EMACSLOADPATH (see section AE.5.1 General Variables).

`-f function'

`--funcall=function'
Call Lisp function function with no arguments.

`--eval=expression'

`--execute=expression'
Evaluate Lisp expression expression.

`--insert=file'
Insert the contents of file into the current buffer. This is like what M-x insert-file does. See section M.10 Miscellaneous File Operations.

`--kill'
Exit from Emacs without asking for confirmation.
The init file can access the values of the action arguments as the elements of a list in the variable command-line-args. The init file can override the normal processing of the action arguments, or define new ones, by reading and setting this variable.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.2 Initial Options

The initial options specify parameters for the Emacs session. This section describes the more general initial options; some other options specifically related to the X Window System appear in the following sections.

Some initial options affect the loading of init files. The normal actions of Emacs are to first load `site-start.el' if it exists, then your own init file `~/.emacs' if it exists, and finally `default.el' if it exists; certain options prevent loading of some of these files or substitute other files for them.

`-t device'

`--terminal=device'
Use device as the device for terminal input and output.

`-d display'

`--display=display'
Use the X Window System and use the display named display to open the initial Emacs frame. See section AE.6 Specifying the Display Name, for more details.

`-nw'

`--no-windows'
Don't communicate directly with the window system, disregarding the DISPLAY environment variable even if it is set. This forces Emacs to run as if the display were a text-only terminal.

`-batch'

`--batch'
Run Emacs in batch mode, which means that the text being edited is not displayed and the standard terminal interrupt characters such as C-z and C-c continue to have their normal effect. Emacs in batch mode outputs to stderr only what would normally be displayed in the echo area under program control, and functions which would normally read from the minibuffer take their input from stdin.
Batch mode is used for running programs written in Emacs Lisp from shell scripts, makefiles, and so on. Normally the `-l' option or `-f' option will be used as well, to invoke a Lisp program to do the batch processing.

`-batch' implies `-q' (do not load an init file). It also causes Emacs to exit after processing all the command options. In addition, it disables auto-saving except in buffers for which it has been explicitly requested.

`-q'

`--no-init-file'
Do not load your Emacs init file `~/.emacs', or `default.el' either. When invoked like this, Emacs does not allow saving options changed with the M-x customize command and its variants. See section AD.2.2 Easy Customization Interface.

`--no-site-file'
Do not load `site-start.el'. The options `-q', `-u' and `-batch' have no effect on the loading of this file--this is the only option that blocks it.

`-u user'

`--user=user'
Load user's Emacs init file `~user/.emacs' instead of your own.

`--debug-init'
Enable the Emacs Lisp debugger for errors in the init file.

`--unibyte'
Do almost everything with single-byte buffers and strings. All buffers and strings are unibyte unless you (or a Lisp program) explicitly ask for a multibyte buffer or string. (Note that Emacs always loads Lisp files in multibyte mode, even if `--unibyte' is specified; see Q.2 Enabling Multibyte Characters.) Setting the environment variable EMACS_UNIBYTE has the same effect.

`--multibyte'
Inhibit the effect of EMACS_UNIBYTE, so that Emacs uses multibyte characters by default, as usual.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.3 Command Argument Example

Here is an example of using Emacs with arguments and options. It assumes you have a Lisp program file called `hack-c.el' which, when loaded, performs some useful operation on the current buffer, expected to be a C program.
emacs -batch foo.c -l hack-c -f save-buffer >& log
This says to visit `foo.c', load `hack-c.el' (which makes changes in the visited file), save `foo.c' (note that save-buffer is the function that C-x C-s is bound to), and then exit back to the shell (because of `-batch'). `-batch' also guarantees there will be no problem redirecting output to `log', because Emacs will not assume that it has a display terminal to work with.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.4 Resuming Emacs with Arguments

You can specify action arguments for Emacs when you resume it after a suspension. To prepare for this, put the following code in your `.emacs' file (see section AD.2.3 Hooks):
(add-hook 'suspend-hook 'resume-suspend-hook)
(add-hook 'suspend-resume-hook 'resume-process-args)
As further preparation, you must execute the shell script `emacs.csh' (if you use csh as your shell) or `emacs.bash' (if you use bash as your shell). These scripts define an alias named edit, which will resume Emacs giving it new command line arguments such as files to visit. The scripts are found in the `etc' subdirectory of the Emacs distribution.

Only action arguments work properly when you resume Emacs. Initial arguments are not recognized--it's too late to execute them anyway.

Note that resuming Emacs (with or without arguments) must be done from within the shell that is the parent of the Emacs job. This is why edit is an alias rather than a program or a shell script. It is not possible to implement a resumption command that could be run from other subjobs of the shell; there is no way to define a command that could be made the value of EDITOR, for example. Therefore, this feature does not take the place of the Emacs Server feature (see section AC.16 Using Emacs as a Server).

The aliases use the Emacs Server feature if you appear to have a server Emacs running. However, they cannot determine this with complete accuracy. They may think that a server is still running when in actuality you have killed that Emacs, because the file `/tmp/esrv...' still exists. If this happens, find that file and delete it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.5 Environment Variables

The environment is a feature of the operating system; it consists of a collection of variables with names and values. Each variable is called an environment variable; environment variable names are case-sensitive, and it is conventional to use upper case letters only. The values are all text strings.

What makes the environment useful is that subprocesses inherit the environment automatically from their parent process. This means you can set up an environment variable in your login shell, and all the programs you run (including Emacs) will automatically see it. Subprocesses of Emacs (such as shells, compilers, and version-control software) inherit the environment from Emacs, too.

Inside Emacs, the command M-x getenv gets the value of an environment variable. M-x setenv sets a variable in the Emacs environment. The way to set environment variables outside of Emacs depends on the operating system, and especially the shell that you are using. For example, here's how to set the environment variable ORGANIZATION to `not very much' using Bash:
export ORGANIZATION="not very much"
and here's how to do it in csh or tcsh:
setenv ORGANIZATION "not very much"
When Emacs is uses the X Window System, it inherits the use of a large number of environment variables from the X libraries. See the X documentation for more information.

AE.5.1 General Variables

Environment variables that all versions of Emacs use.

AE.5.2 Miscellaneous Variables

Certain system-specific variables.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.5.1 General Variables

Here is an alphabetical list of specific environment variables that have special meanings in Emacs, giving the name of each variable and its meaning. Most of these variables are also used by some other programs. Emacs does not require any of these environment variables to be set, but it uses their values if they are set.

CDPATH
Used by the cd command to search for the directory you specify, when you specify a relative directory name.
EMACS_UNIBYTE
Defining this environment variable with a nonempty value directs Emacs to do almost everything with single-byte buffers and strings. It is equivalent to using the `--unibyte' command-line option on each invocation. See section AE.2 Initial Options.
EMACSDATA
Directory for the architecture-independent files that come with Emacs. This is used to initialize the Lisp variable data-directory.
EMACSDOC
Directory for the documentation string file, `DOC-emacsversion'. This is used to initialize the Lisp variable doc-directory.
EMACSLOADPATH
A colon-separated list of directories(17) to search for Emacs Lisp files--used to initialize load-path.
EMACSPATH
A colon-separated list of directories to search for executable files--used to initialize exec-path.
ESHELL
Used for shell-mode to override the SHELL environment variable.
HISTFILE
The name of the file that shell commands are saved in between logins. This variable defaults to `~/.bash_history' if you use Bash, to `~/.sh_history' if you use ksh, and to `~/.history' otherwise.
HOME
The location of the user's files in the directory tree; used for expansion of file names starting with a tilde (`~'). On MS-DOS, it defaults to the directory from which Emacs was started, with `/bin' removed from the end if it was present. On Windows, the default value of HOME is `C:/', the root directory of drive `C:'.
HOSTNAME
The name of the machine that Emacs is running on.
INCPATH
A colon-separated list of directories. Used by the complete package to search for files.
INFOPATH
A colon-separated list of directories in which to search for Info files.
LC_ALL

LC_COLLATE

LC_CTYPE

LC_MESSAGES

LC_MONETARY

LC_NUMERIC

LC_TIME

LANG
The user's preferred locale. The locale has six categories, specified by the environment variables LC_COLLATE for sorting, LC_CTYPE for character encoding, LC_MESSAGES for system messages, LC_MONETARY for monetary formats, LC_NUMERIC for numbers, and LC_TIME for dates and times. If one of these variables is not set, the category defaults to the value of the LANG environment variable, or to the default `C' locale if LANG is not set. But if LC_ALL is specified, it overrides the settings of all the other locale environment variables.
The value of the LC_CTYPE category is matched against entries in locale-language-names, locale-charset-language-names, and locale-preferred-coding-systems, to select a default language environment and coding system. See section Q.3 Language Environments.
LOGNAME
The user's login name. See also USER.
MAIL
The name of the user's system mail inbox.
MAILRC
Name of file containing mail aliases. (The default is `~/.mailrc'.)
MH
Name of setup file for the mh system. (The default is `~/.mh_profile'.)
NAME
The real-world name of the user.
NNTPSERVER
The name of the news server. Used by the mh and Gnus packages.
ORGANIZATION
The name of the organization to which you belong. Used for setting the `Organization:' header in your posts from the Gnus package.
PATH
A colon-separated list of directories in which executables reside. This is used to initialize the Emacs Lisp variable exec-path.
PWD
If set, this should be the default directory when Emacs was started.
REPLYTO
If set, this specifies an initial value for the variable mail-default-reply-to. See section Z.2 Mail Header Fields.
SAVEDIR
The name of a directory in which news articles are saved by default. Used by the Gnus package.
SHELL
The name of an interpreter used to parse and execute programs run from inside Emacs.
TERM
The type of the terminal that Emacs is using. This variable must be set unless Emacs is run in batch mode. On MS-DOS, it defaults to `internal', which specifies a built-in terminal emulation that handles the machine's own display. If the value of TERM indicates that Emacs runs in non-windowed mode from xterm or a similar terminal emulator, the background mode defaults to `light', and Emacs will choose colors that are appropriate for a light background.
TERMCAP
The name of the termcap library file describing how to program the terminal specified by the TERM variable. This defaults to `/etc/termcap'.
TMPDIR
Used by the Emerge package as a prefix for temporary files.
TZ
This specifies the current time zone and possibly also daylight saving time information. On MS-DOS, if TZ is not set in the environment when Emacs starts, Emacs defines a default value as appropriate for the country code returned by DOS. On MS-Windows, Emacs does not use TZ at all.
USER
The user's login name. See also LOGNAME. On MS-DOS, this defaults to `root'.
VERSION_CONTROL
Used to initialize the version-control variable (see section M.3.1.1 Single or Numbered Backups).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.5.2 Miscellaneous Variables

These variables are used only on particular configurations:

COMSPEC
On MS-DOS and MS-Windows, the name of the command interpreter to use when invoking batch files and commands internal to the shell. On MS-DOS this is also used to make a default value for the SHELL environment variable.

NAME
On MS-DOS, this variable defaults to the value of the USER variable.

TEMP

TMP
On MS-DOS and MS-Windows, these specify the name of the directory for storing temporary files in.

EMACSTEST
On MS-DOS, this specifies a file to use to log the operation of the internal terminal emulator. This feature is useful for submitting bug reports.

EMACSCOLORS
On MS-DOS, this specifies the screen colors. It is useful to set them this way, since otherwise Emacs would display the default colors momentarily when it starts up.
The value of this variable should be the two-character encoding of the foreground (the first character) and the background (the second character) colors of the default face. Each character should be the hexadecimal code for the desired color on a standard PC text-mode display. For example, to get blue text on a light gray background, specify `EMACSCOLORS=17', since 1 is the code of the blue color and 7 is the code of the light gray color.

The PC display usually supports only eight background colors. However, Emacs switches the DOS display to a mode where all 16 colors can be used for the background, so all four bits of the background color are actually used.

WINDOW_GFX
Used when initializing the Sun windows system.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.6 Specifying the Display Name

The environment variable DISPLAY tells all X clients, including Emacs, where to display their windows. Its value is set by default in ordinary circumstances, when you start an X server and run jobs locally. Occasionally you may need to specify the display yourself; for example, if you do a remote login and want to run a client program remotely, displaying on your local screen.

With Emacs, the main reason people change the default display is to let them log into another system, run Emacs on that system, but have the window displayed at their local terminal. You might need to log in to another system because the files you want to edit are there, or because the Emacs executable file you want to run is there.

The syntax of the DISPLAY environment variable is `host:display.screen', where host is the host name of the X Window System server machine, display is an arbitrarily-assigned number that distinguishes your server (X terminal) from other servers on the same machine, and screen is a rarely-used field that allows an X server to control multiple terminal screens. The period and the screen field are optional. If included, screen is usually zero.

For example, if your host is named `glasperle' and your server is the first (or perhaps the only) server listed in the configuration, your DISPLAY is `glasperle:0.0'.

You can specify the display name explicitly when you run Emacs, either by changing the DISPLAY variable, or with the option `-d display' or `--display=display'. Here is an example:
emacs --display=glasperle:0 &
You can inhibit the direct use of the window system and GUI with the `-nw' option. It tells Emacs to display using ordinary ASCII on its controlling terminal. This is also an initial option.

Sometimes, security arrangements prevent a program on a remote system from displaying on your local system. In this case, trying to run Emacs produces messages like this:
Xlib:  connection to "glasperle:0.0" refused by server
You might be able to overcome this problem by using the xhost command on the local system to give permission for access from your remote machine.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.7 Font Specification Options

By default, Emacs displays text in the font named `9x15', which makes each character nine pixels wide and fifteen pixels high. You can specify a different font on your command line through the option `-fn name' (or `--font', which is an alias for `-fn').

`-fn name'

`--font=name'
Use font name as the default font.
Under X, each font has a long name which consists of eleven words or numbers, separated by dashes. Some fonts also have shorter nicknames---`9x15' is such a nickname. You can use either kind of name. You can use wildcard patterns for the font name; then Emacs lets X choose one of the fonts that match the pattern. Here is an example, which happens to specify the font whose nickname is `6x13':
emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
You can also specify the font in your `.Xdefaults' file:
emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
A long font name has the following form:
-maker-family-weight-slant-widthtype-style...
...-pixels-height-horiz-vert-spacing-width-charset
maker
This is the name of the font manufacturer.
family
This is the name of the font family--for example, `courier'.
weight
This is normally `bold', `medium' or `light'. Other words may appear here in some font names.
slant
This is `r' (roman), `i' (italic), `o' (oblique), `ri' (reverse italic), or `ot' (other).
widthtype
This is normally `condensed', `extended', `semicondensed' or `normal'. Other words may appear here in some font names.
style
This is an optional additional style name. Usually it is empty--most long font names have two hyphens in a row at this point.
pixels
This is the font height, in pixels.
height
This is the font height on the screen, measured in tenths of a printer's point--approximately 1/720 of an inch. In other words, it is the point size of the font, times ten. For a given vertical resolution, height and pixels are proportional; therefore, it is common to specify just one of them and use `*' for the other.
horiz
This is the horizontal resolution, in pixels per inch, of the screen for which the font is intended.
vert
This is the vertical resolution, in pixels per inch, of the screen for which the font is intended. Normally the resolution of the fonts on your system is the right value for your screen; therefore, you normally specify `*' for this and horiz.
spacing
This is `m' (monospace), `p' (proportional) or `c' (character cell).
width
This is the average character width, in pixels, multiplied by ten.
charset
This is the character set that the font depicts. Normally you should use `iso8859-1'.
You will probably want to use a fixed-width default font--that is, a font in which all characters have the same width. Any font with `m' or `c' in the spacing field of the long name is a fixed-width font. Here's how to use the xlsfonts program to list all the fixed-width fonts available on your system:
xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
To see what a particular font looks like, use the xfd command. For example:
xfd -fn 6x13
displays the entire font `6x13'.

While running Emacs, you can set the font of the current frame (see section P.12 Setting Frame Parameters) or for a specific kind of text (see section J.1 Using Multiple Typefaces).

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.8 Window Color Options

On a color display, you can specify which color to use for various parts of the Emacs display. To find out what colors are available on your system, type M-x list-colors-display, or press C-Mouse-2 and select `Display Colors' from the pop-up menu. If you do not specify colors, on windowed displays the default for the background is white and the default for all other colors is black. On a monochrome display, the foreground is black, the background is white, and the border is gray if the display supports that. On terminals, the background is usually black and the foreground is white.

Here is a list of the command-line options for specifying colors:

`-fg color'

`--foreground-color=color'
Specify the foreground color. color should be a standard color name, or a numeric specification of the color's red, green, and blue components as in `#4682B4' or `RGB:46/82/B4'.
`-bg color'

`--background-color=color'
Specify the background color.
`-bd color'

`--border-color=color'
Specify the color of the border of the X window.
`-cr color'

`--cursor-color=color'
Specify the color of the Emacs cursor which indicates where point is.
`-ms color'

`--mouse-color=color'
Specify the color for the mouse cursor when the mouse is in the Emacs window.
`-r'

`-rv'

`--reverse-video'
Reverse video--swap the foreground and background colors.
For example, to use a coral mouse cursor and a slate blue text cursor, enter:
emacs -ms coral -cr 'slate blue' &
You can reverse the foreground and background colors through the `-rv' option or with the X resource `reverseVideo'.

The `-fg', `-bg', and `-rv' options function on text-only terminals as well as on window systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.9 Options for Window Geometry

The `--geometry' option controls the size and position of the initial Emacs frame. Here is the format for specifying the window geometry:

`-g widthxheight[{+-}xoffset{+-}yoffset]]'
Specify window size width and height (measured in character columns and lines), and positions xoffset and yoffset (measured in pixels).

`--geometry=widthxheight[{+-}xoffset{+-}yoffset]]'
This is another way of writing the same thing.
{+-} means either a plus sign or a minus sign. A plus sign before xoffset means it is the distance from the left side of the screen; a minus sign means it counts from the right side. A plus sign before yoffset means it is the distance from the top of the screen, and a minus sign there indicates the distance from the bottom. The values xoffset and yoffset may themselves be positive or negative, but that doesn't change their meaning, only their direction.

Emacs uses the same units as xterm does to interpret the geometry. The width and height are measured in characters, so a large font creates a larger frame than a small font. (If you specify a proportional font, Emacs uses its maximum bounds width as the width unit.) The xoffset and yoffset are measured in pixels.

Since the mode line and the echo area occupy the last 2 lines of the frame, the height of the initial text window is 2 less than the height specified in your geometry. In non-X-toolkit versions of Emacs, the menu bar also takes one line of the specified number. But in the X toolkit version, the menu bar is additional and does not count against the specified height. The tool bar, if present, is also additional.

You do not have to specify all of the fields in the geometry specification.

If you omit both xoffset and yoffset, the window manager decides where to put the Emacs frame, possibly by letting you place it with the mouse. For example, `164x55' specifies a window 164 columns wide, enough for two ordinary width windows side by side, and 55 lines tall.

The default width for Emacs is 80 characters and the default height is 40 lines. You can omit either the width or the height or both. If you start the geometry with an integer, Emacs interprets it as the width. If you start with an `x' followed by an integer, Emacs interprets it as the height. Thus, `81' specifies just the width; `x45' specifies just the height.

If you start with `+' or `-', that introduces an offset, which means both sizes are omitted. Thus, `-3' specifies the xoffset only. (If you give just one offset, it is always xoffset.) `+3-3' specifies both the xoffset and the yoffset, placing the frame near the bottom left of the screen.

You can specify a default for any or all of the fields in `.Xdefaults' file, and then override selected fields with a `--geometry' option.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.10 Internal and External Borders

An Emacs frame has an internal border and an external border. The internal border is an extra strip of the background color around the text portion of the frame. Emacs itself draws the internal border. The external border is added by the window manager outside the frame; depending on the window manager you use, it may contain various boxes you can click on to move or iconify the window.

`-ib width'

`--internal-border=width'
Specify width as the width of the internal border, in pixels.

`-bw width'

`--border-width=width'
Specify width as the width of the main border, in pixels.
When you specify the size of the frame, that does not count the borders. The frame's position is measured from the outside edge of the external border.

Use the `-ib n' option to specify an internal border n pixels wide. The default is 1. Use `-bw n' to specify the width of the external border (though the window manager may not pay attention to what you specify). The default width of the external border is 2.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.11 Frame Titles

An Emacs frame may or may not have a specified title. The frame title, if specified, appears in window decorations and icons as the name of the frame. If an Emacs frame has no specified title, the default title has the form `invocation-name@machine' (if there is only one frame) or the selected window's buffer name (if there is more than one frame).

You can specify a title for the initial Emacs frame with a command line option:

`-title title'

`--title=title'

`-T title'
Specify title as the title for the initial Emacs frame.
The `--name' option (see section AE.13 X Resources) also specifies the title for the initial Emacs frame.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.12 Icons

Most window managers allow the user to "iconify" a frame, removing it from sight, and leaving a small, distinctive "icon" window in its place. Clicking on the icon window makes the frame itself appear again. If you have many clients running at once, you can avoid cluttering up the screen by iconifying most of the clients.

`-i'

`--icon-type'
Use a picture of a gnu as the Emacs icon.

`-iconic'

`--iconic'
Start Emacs in iconified state.
The `-i' or `--icon-type' option tells Emacs to use an icon window containing a picture of the GNU gnu. If omitted, Emacs lets the window manager choose what sort of icon to use--usually just a small rectangle containing the frame's title.

The `-iconic' option tells Emacs to begin running as an icon, rather than showing a frame right away. In this situation, the icon is the only indication that Emacs has started; the text frame doesn't appear until you deiconify it.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.13 X Resources

Programs running under the X Window System organize their user options under a hierarchy of classes and resources. You can specify default values for these options in your X resources file, usually named `~/.Xdefaults'.

Each line in the file specifies a value for one option or for a collection of related options, for one program or for several programs (optionally even for all programs).

MS-Windows systems don't support `~/.Xdefaults' files, but Emacs compiled for Windows looks for X resources in the Windows Registry, under the keys `HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs' and `HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs'.

Programs define named resources with particular meanings. They also define how to group resources into named classes. For instance, in Emacs, the `internalBorder' resource controls the width of the internal border, and the `borderWidth' resource controls the width of the external border. Both of these resources are part of the `BorderWidth' class. Case distinctions are significant in these names.

In `~/.Xdefaults', you can specify a value for a single resource on one line, like this:
emacs.borderWidth: 2
Or you can use a class name to specify the same value for all resources in that class. Here's an example:
emacs.BorderWidth: 2
If you specify a value for a class, it becomes the default for all resources in that class. You can specify values for individual resources as well; these override the class value, for those particular resources. Thus, this example specifies 2 as the default width for all borders, but overrides this value with 4 for the external border:
emacs.BorderWidth: 2
emacs.borderWidth: 4
The order in which the lines appear in the file does not matter. Also, command-line options always override the X resources file.

The string `emacs' in the examples above is also a resource name. It actually represents the name of the executable file that you invoke to run Emacs. If Emacs is installed under a different name, it looks for resources under that name instead of `emacs'.

`-name name'

`--name=name'
Use name as the resource name (and the title) for the initial Emacs frame. This option does not affect subsequent frames, but Lisp programs can specify frame names when they create frames.
If you don't specify this option, the default is to use the Emacs executable's name as the resource name.

`-xrm resource-values'

`--xrm=resource-values'
Specify X resource values for this Emacs job (see below).
For consistency, `-name' also specifies the name to use for other resource values that do not belong to any particular frame.

The resources that name Emacs invocations also belong to a class; its name is `Emacs'. If you write `Emacs' instead of `emacs', the resource applies to all frames in all Emacs jobs, regardless of frame titles and regardless of the name of the executable file. Here is an example:
Emacs.BorderWidth: 2
Emacs.borderWidth: 4
You can specify a string of additional resource values for Emacs to use with the command line option `-xrm resources'. The text resources should have the same format that you would use inside a file of X resources. To include multiple resource specifications in resources, put a newline between them, just as you would in a file. You can also use `#include "filename"' to include a file full of resource specifications. Resource values specified with `-xrm' take precedence over all other resource specifications.

The following table lists the resource names that designate options for Emacs, each with the class that it belongs to:

background (class Background)
Background color name.

bitmapIcon (class BitmapIcon)
Use a bitmap icon (a picture of a gnu) if `on', let the window manager choose an icon if `off'.

borderColor (class BorderColor)
Color name for the external border.

borderWidth (class BorderWidth)
Width in pixels of the external border.

cursorColor (class Foreground)
Color name for text cursor (point).

font (class Font)
Font name for text (or fontset name, see section Q.10 Fontsets).

foreground (class Foreground)
Color name for text.

geometry (class Geometry)
Window size and position. Be careful not to specify this resource as `emacs*geometry', because that may affect individual menus as well as the Emacs frame itself.
If this resource specifies a position, that position applies only to the initial Emacs frame (or, in the case of a resource for a specific frame name, only that frame). However, the size, if specified here, applies to all frames.

iconName (class Title)
Name to display in the icon.

internalBorder (class BorderWidth)
Width in pixels of the internal border.

lineSpacing (class LineSpacing)
Additional space (leading) between lines, in pixels.

menuBar (class MenuBar)
Give frames menu bars if `on'; don't have menu bars if `off'.

toolBar (class ToolBar)
Number of lines to reserve for the tool bar. A zero value suppresses the tool bar. If the value is non-zero and auto-resize-tool-bars is non-nil, the tool bar's size will be changed automatically so that all tool bar items are visible.

minibuffer (class Minibuffer)
If `none', don't make a minibuffer in this frame. It will use a separate minibuffer frame instead.

paneFont (class Font)
Font name for menu pane titles, in non-toolkit versions of Emacs.

pointerColor (class Foreground)
Color of the mouse cursor.

reverseVideo (class ReverseVideo)
Switch foreground and background default colors if `on', use colors as specified if `off'.

screenGamma (class ScreenGamma)
Gamma correction for colors, equivalent to the frame parameter screen-gamma.

selectionFont (class Font)
Font name for pop-up menu items, in non-toolkit versions of Emacs. (For toolkit versions, see AE.14 Lucid Menu X Resources, also see AE.15 LessTif Menu X Resources.)

synchronous (class Synchronous)
Run Emacs in synchronous mode if `on'. Synchronous mode is useful for debugging X problems.

title (class Title)
Name to display in the title bar of the initial Emacs frame.

verticalScrollBars (class ScrollBars)
Give frames scroll bars if `on'; don't have scroll bars if `off'.
Here are resources for controlling the appearance of particular faces (see section J.1 Using Multiple Typefaces):

face.attributeFont
Font for face face.
face.attributeForeground
Foreground color for face face.
face.attributeBackground
Background color for face face.
face.attributeUnderline
Underline flag for face face. Use `on' or `true' for yes.
face.attributeFamily
Font family for face face.
face.attributeWidth
Relative proportional width of the font to use for face face. It should be one of ultra-condensed, extra-condensed, condensed, semi-condensed, normal, semi-expanded, expanded, extra-expanded, or ultra-expanded.
face.attributeHeight
Height of the font to use for face face: either an integer specifying the height in units of 1/10pt, or a floating point number that specifies a scale factor to scale the underlying face's default font, or a function to be called with the default height which will return a new height.
face.attributeWeight
A weight to use for the face face. It must be one of ultra-bold, extra-bold, bold, semi-bold, normal, semi-light, light, extra-light, ultra-light.
face.attributeSlant
The slant to use for the font of face face. It must be one of italic, oblique, normal, reverse-italic, or reverse-oblique.
face.attributeStrikeThrough
Whether the face face should be drawn with a line striking through the characters.
face.attributeOverline
Whether the characters in the face face should be overlined.
face.attributeBox
Whether to draw a box around the characters in face face.
face.attributeInverse
Whether to display the characters in face face in inverse video.
face.attributeStipple
The name of a pixmap data file to use for the stipple pattern, or false to not use stipple for the face face.
face.attributeBackgroundPixmap
The background pixmap for the face face. Should be a name of a pixmap file or false.
face.attributeBold
Whether to draw the characters in the face face as bold.
face.attributeItalic
Whether to draw the characters in the face face as italic.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.14 Lucid Menu X Resources

If the Emacs installed at your site was built to use the X toolkit with the Lucid menu widgets, then the menu bar is a separate widget and has its own resources. The resource names contain `pane.menubar' (following, as always, the name of the Emacs invocation, or `Emacs', which stands for all Emacs invocations). Specify them like this:
Emacs.pane.menubar.resource:  value
For example, to specify the font `8x16' for the menu-bar items, write this:
Emacs.pane.menubar.font:  8x16
Resources for non-menubar toolkit pop-up menus have `menu*', in like fashion. For example, to specify the font `8x16' for the pop-up menu items, write this:
Emacs.menu*.font:	8x16
For dialog boxes, use `dialog' instead of `menu':
Emacs.dialog*.font:	8x16
Experience shows that on some systems you may need to add `shell.' before the `pane.menubar' or `menu*'. On some other systems, you must not add `shell.'.

Here is a list of the specific resources for menu bars and pop-up menus:

font
Font for menu item text.
foreground
Color of the foreground.
background
Color of the background.
buttonForeground
In the menu bar, the color of the foreground for a selected item.
horizontalSpacing
Horizontal spacing in pixels between items. Default is 3.
verticalSpacing
Vertical spacing in pixels between items. Default is 1.
arrowSpacing
Horizontal spacing between the arrow (which indicates a submenu) and the associated text. Default is 10.
shadowThickness
Thickness of shadow line around the widget.
margin
The margin of the menu bar, in characters. The default of 4 makes the menu bar appear like the LessTif/Motif one.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AE.15 LessTif Menu X Resources

If the Emacs installed at your site was built to use the X toolkit with the LessTif or Motif widgets, then the menu bar, the dialog boxes, the pop-up menus, and the file-selection box are separate widgets and have their own resources.

The resource names for the menu bar contain `pane.menubar' (following, as always, the name of the Emacs invocation, or `Emacs', which stands for all Emacs invocations). Specify them like this:
Emacs.pane.menubar.subwidget.resource:  value
Each individual string in the menu bar is a subwidget; the subwidget's name is the same as the menu item string. For example, the word `File' in the menu bar is part of a subwidget named `emacs.pane.menubar.File'. Most likely, you want to specify the same resources for the whole menu bar. To do this, use `*' instead of a specific subwidget name. For example, to specify the font `8x16' for the menu-bar items, write this:
Emacs.pane.menubar.*.fontList:  8x16
This also specifies the resource value for submenus.

Each item in a submenu in the menu bar also has its own name for X resources; for example, the `File' submenu has an item named `Save (current buffer)'. A resource specification for a submenu item looks like this:
Emacs.pane.menubar.popup_*.menu.item.resource: value
For example, here's how to specify the font for the `Save (current buffer)' item:
Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16
For an item in a second-level submenu, such as `Complete Word' under `Spell Checking' under `Tools', the resource fits this template:
Emacs.pane.menubar.popup_*.popup_*.menu.resource: value
For example,
Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: value
(This should be one long line.) It's impossible to specify a resource for all the menu-bar items without also specifying it for the submenus as well. So if you want the submenu items to look different from the menu bar itself, you must ask for that in two steps. First, specify the resource for all of them; then, override the value for submenus alone. Here is an example:
Emacs.pane.menubar.*.fontList:  8x16
Emacs.pane.menubar.popup_*.fontList: 8x16
For LessTif pop-up menus, use `menu*' instead of `pane.menubar'. For example, to specify the font `8x16' for the pop-up menu items, write this:
Emacs.menu*.fontList:  8x16
For LessTif dialog boxes, use `dialog' instead of `menu':
Emacs.dialog*.fontList: 8x16
Emacs.dialog*.foreground: hotpink
To specify resources for the LessTif file-selection box, use `fsb*', like this:
Emacs.fsb*.fontList: 8x16
Here is a list of the specific resources for LessTif menu bars and pop-up menus:

armColor
The color to show in an armed button.
fontList
The font to use.
marginBottom

marginHeight

marginLeft

marginRight

marginTop

marginWidth
Amount of space to leave around the item, within the border.
borderWidth
The width of the border around the menu item, on all sides.
shadowThickness
The width of the border shadow.
bottomShadowColor
The color for the border shadow, on the bottom and the right.
topShadowColor
The color for the border shadow, on the top and the left.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AF. Emacs 20 Antinews

For those users who live backwards in time, here is information about downgrading to Emacs version 20. We hope you will enjoy the greater simplicity that results from the absence of many Emacs 21 features.

The display engine has been greatly simplified by eliminating support for variable-size characters and other non-text display features. This avoids the complexity of display layout in Emacs 21. To wit:

Variable-size characters are not supported in Emacs 20. You cannot use fonts which contain oversized characters, and using italic fonts can result in illegible display. However, text which uses variable-size fonts is unreadable anyway. With all characters in a frame laid out on a regular grid, each character having the same height and width, text is much easier to read.

Emacs does not display images, or play sounds. It just displays text, as you would expect from a text editor.

Specification of the font for a face now uses an XLFD font name, for compatibility with other X applications. This means that font attributes cannot be merged when combining faces; however, experience shows that mergers are bad economics. Face inheritance has also been removed, so no one can accumulate "too much face."

Several face appearance attributes, including 3D, strike-through, and overline, have been eliminated.

Emacs now provides its own "lean and mean" scroll bars instead of using those from the X toolkit. Toggle buttons and radio buttons in menus now look just like any other menu item, which simplifies them, and prevents them from standing out and distracting your attention from the other menu items.

There are no toolbars and no tooltips; in particular, GUD mode cannot display variable values in a tooltip when you click on that variable's name. Instead, Emacs 20 provides a direct interface to the debugger, so that you can type appropriate debugger commands, such as display foo and print bar. As these commands use explicit words, their meaning is more self-evident.

Colors are not available on text-only terminals. If you must have colors, but cannot afford to run X, you can now use the MS-DOG version of Emacs inside a DOS emulator.

The mode line is not mouse-sensitive, since it is meant only to display information. Use keyboard commands to switch between buffers, toggle read-only and modified status, switch minor modes on and off, etc.

The support for "wheeled" mice under X has been removed, because of their slow scroll rate, and because you will find fewer and fewer of these mice as you go back in time. Instead Emacs 20 provides the C-v and M-v keys for scrolling. (You can also use the scroll bar, but be advised that it, too, may be absent in yet earlier Emacs versions.)

Busy-cursor display is gone, as it was found to be too hard to draw on displays whose resolution is getting lower and lower. This means that you get the standard kind of cursor blinking that your terminal provides.

Some aspects of Emacs appearance, such as the colors of the scroll bar and the menus, can only be controlled via X resources. Since colors aren't supported except on X, it doesn't make any sense to do this in any way but the X way. For those users who aren't privy to X arcana, we've provided good default colors that should make everybody happy.

Emacs 20 adds new lines to the buffer when you move down from the last line with C-n or a down-arrow.

The variable show-trailing-whitespace has no special meaning, so trailing whitespace on a line is now always displayed correctly: as empty space. To see if a line ends with spaces or tabs, type C-e on that line. Likewise, empty lines at the end of the buffer are not marked in any way; use M-> to see where the end of the buffer is.

The spacing between text lines on the display now always follows the font design and the rules of your window manager. This provides for predictable appearance of the displayed text.

Emacs 20 has simpler support for multi-lingual editing. While not as radical a simplification as Emacs 19 will be, it goes a long way toward eliminating some of the annoying features:

Translations of the Emacs reference cards to other languages are no longer part of the distribution, because in the past we expect computer users to speak English.

To avoid extra confusion, many language environments have been eliminated. For example, `Polish' and `Celtic' (Latin-8) environments are not supported. The Latin-9 environment is gone, too, because you won't need the Euro sign in the past.

Emacs 20 always asks you which coding system to use when saving a buffer, unless it can use the same one that it used to read the buffer. It does not try to see if the preferred coding system is suitable.

Commands which provide detailed information about character sets and coding systems, such as list-charset-chars, describe-character-set, and the C-u C-x = key-sequence, no longer exist. The less said about non-ASCII characters, the better.

The terminal coding system cannot be set to something CCL-based, so keyboards which produce KOI8 and DOS/Windows codepage codes cannot be supported directly. Instead, you should use one of the input methods provided in the Leim package.

As you move back through time, some systems will become unimportant or enter the vaporware phase, so Emacs 20 does not support them:

Emacs 20 cannot be built on GNU/Linux systems running on IA64 machines, and you cannot build a 64-bit Emacs on Solaris or Irix even though there are still 64-bit versions of those OSes.

LynxOS is also not supported, and neither is the Macintosh, though they still exist.

The arrangement of menu bar items differs from most other GUI programs. We think that uniformity of look-and-feel is boring, and that Emacs' unique features require its unique menu-bar configuration.

You cannot save the options that you set from the `Options' menu-bar menu; instead, you need to set all the options again each time you start a new session. However, if you follow the recommended practice and keep a single Emacs session running until you log out, you won't have to set the options very often.

Emacs 20 does not pop up a buffer with error messages when an error is signaled during loading of the user's init file. Instead, it simply announces the fact that an error happened. To know where in the init file that was, insert (message "foo") lines judiciously into the file and look for those messages in the `*Messages*' buffer.

Some commands no longer treat Transient Mark mode specially. For example, ispell doesn't spell-check the region when Transient Mark mode is in effect and the mark is active; instead, it checks the current buffer. (Transient Mark mode is alien to the spirit of Emacs, so we are planning to remove it altogether in an earlier version.)

C-Down-Mouse-3 does not show what would be in the menu bar when the menu bar is not displayed.

For uniformity, the delete function key in Emacs 20 works exactly like the DEL key, on both text-only terminals and window systems--it always deletes backward. This eliminates the inconsistency of Emacs 21, where the key labeled delete deletes forward when you are using a window system, and backward on a text-only terminals.

The ability to place backup files in special subdirectories (controlled by backup-directory-alist) has been eliminated. This makes finding your backup files much easier: they are always in the same directory as the original files.

Emacs no longer refuses to load Lisp files compiled by incompatible versions of Emacs, which may contain invalid byte-code. Instead, Emacs now dumps core when it encounters such byte-code. However, this is a rare occurrence, and it won't happen at all when all Emacs versions merge together, in the distant past.

The C-x 5 1 command has been eliminated. If you want to delete all the frames but the current one, delete them one by one instead.

CC Mode now enforces identical values for some customizable options, such as indentation style, for better consistency. In particular, if you select an indentation style for Java, the same style is used for C and C++ buffers as well.

Isearch does not highlight other possible matches; it shows only the current match, to avoid distracting your attention. Mouse-2 in the echo area during incremental search now signals an error, instead of inserting the current selection into the search string. But you can accomplish more or less the same job by typing M-y.

The ability to specify a port number when editing remote files with ange-ftp was removed. Instead, Emacs 20 provides undocumented features in the function ange-ftp-normal-login (Use the source, Luke!) to specify the port.

Emacs 20 does not check for changing time stamps of remote files, since the old FTP programs you will encounter in the past could not provide the time stamp anyway. Windows-style FTP clients which output the `^M' character at the end of each line get special handling from ange-ftp in Emacs 20, with unexpected results that should make your life more interesting.

Many complicated display features, including highlighting of mouse-sensitive text regions and popping up help strings for menu items, don't work in the MS-DOS version. Spelling doesn't work on MS-DOS, and Eshell doesn't exist, so there's no workable shell-mode, either. This fits the spirit of MS-DOS, which resembles a dumb character terminal.

The woman package has been removed, so Emacs users on non-Posix systems will need a real man to read manual pages. (Users who are not macho can read the Info documentation instead.)

recentf has been removed, because we figure that you can remember the names of the files you edit frequently. With decreasing disk size, you should have fewer files anyway, so you won't notice the absence of this feature.

The field property does not exist in Emacs 20, so various packages that run subsidiary programs in Emacs buffers cannot in general distinguish which text was user input and which was output from the subprocess. If you need to try to do this nonetheless, Emacs 20 provides a variable comint-prompt-regexp, which lets you try to distinguish input by recognizing prompt strings.

We have eliminated the special major modes for Delphi sources, PostScript files, context diffs, and `TODO' files. Use Fundamental Mode instead.

Many additional packages that unnecessarily complicate your life in Emacs 21 are absent in Emacs 20. You cannot browse C++ classes with Ebrowse, access SQL data bases, access LDAP and other directory servers, or mix shell commands and Lisp functions using Eshell.

To keep up with decreasing computer memory capacity and disk space, many other functions and files have been eliminated in Emacs 20.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AG. Emacs and the Mac OS

Emacs built on the Mac OS supports many of its major features: multiple frames, colors, scroll bars, menu bars, use of the mouse, fontsets, international characters, input methods, coding systems, and synchronous subprocesses (call-process). Much of this works in the same way as on other platforms and is therefore documented in the rest of this manual. This section describes the peculiarities of using Emacs under the Mac OS.

The following features of Emacs are not yet supported on the Mac: unexec (dump-emacs), asynchronous subprocesses (start-process), and networking (open-network-stream). As a result, packages such as Gnus, GUD, and Comint do not work.

Since external programs to handle commands such as print-buffer and diff are not available on the Mac OS, they are not supported in the Mac OS version.

AG.1 Keyboard Input on the Mac

Keyboard input on the Mac.

AG.2 International Character Set Support on the Mac

International character sets on the Mac.

AG.3 Environment Variables and Command Line Arguments.

Setting environment variables for Emacs.

AG.4 Volumes and Directories on the Mac

Volumes and directories on the Mac.

AG.5 Specifying Fonts on the Mac

Specifying fonts on the Mac.

AG.6 Mac-Specific Lisp Functions

Mac-specific Lisp functions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AG.1 Keyboard Input on the Mac

On the Mac, Emacs can use either the option key or the command key as the META key. If the value of the variable mac-command-key-is-meta is non-nil (its default value), Emacs uses the command key as the META key. Otherwise it uses the option key as the META key.

Most people should want to use the command key as the META key, so that dead-key processing with the option key will still work. This is useful for entering non-ASCII Latin characters directly from the Mac keyboard, for example.

Emacs recognizes the setting in the Keyboard control panel and supports international and alternative keyboard layouts (e.g., Dvorak). Selecting one of the layouts from the keyboard layout pull-down menu will affect how the keys typed on the keyboard are interpreted.

The Mac OS intercepts and handles certain key combinations (e.g., command-SPC for switching input languages). These will not be passed to Emacs.

The Mac keyboard ordinarily generates characters in the Mac Roman encoding. To use it for entering ISO Latin-1 characters directly, set the value of the variable mac-keyboard-text-encoding to kTextEncodingISOLatin1. Note that not all Mac Roman characters that can be entered at the keyboard can be converted to ISO Latin-1 characters.

To enter ISO Latin-2 characters directly from the Mac keyboard, set the value of mac-keyboard-text-encoding to kTextEncodingISOLatin2. Then let Emacs know that the keyboard generates Latin-2 codes, by typing C-x RET k iso-latin-2 RET. To make this setting permanent, put this in your `.emacs' init file:
(set-keyboard-coding-system 'iso-latin-2)
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AG.2 International Character Set Support on the Mac

The Mac uses a non-standard encoding for the upper 128 single-byte characters. It also deviates from the ISO 2022 standard by using character codes in the range 128-159. The coding system mac-roman is used to represent this Mac encoding. It is used for editing files stored in this native encoding, and for displaying file names in Dired mode.

Any native (non-symbol) Mac font can be used to correctly display characters in the mac-roman coding system.

The fontset fontset-mac is created automatically when Emacs is run on the Mac. It displays characters in the mac-roman coding system using 12-point Monaco.

To insert characters directly in the mac-roman coding system, type C-x RET k mac-roman RET, customize the option keyboard-coding-system, or put this in your init file:
(set-keyboard-coding-system 'mac-roman)
This is useful for editing documents in native Mac encoding.

You can use input methods provided either by LEIM (see section Q.4 Input Methods) or the Mac OS to enter international characters.

To use the former, see the International Character Set Support section of the manual (see section Q. International Character Set Support).

To use input methods provided by the Mac OS, set the keyboard coding system accordingly using the C-x RET k command (set-keyboard-coding-system). For example, for Traditional Chinese, use `chinese-big5' as keyboard coding system; for Japanese, use `sjis', etc. Then select the desired input method in the keyboard layout pull-down menu.

The Mac clipboard and the Emacs kill ring (see section H.7 Deletion and Killing) are connected as follows: the most recent kill is copied to the clipboard when Emacs is suspended and the contents of the clipboard is inserted into the kill ring when Emacs resumes. The result is that you can yank a piece of text and paste it into another Mac application, or cut or copy one in another Mac application and yank it into a Emacs buffer.

The encoding of text selections must be specified using the commands C-x RET x (set-selection-coding-system) or C-x RET X (set-next-selection-coding-system) (e.g., for Traditional Chinese, use `chinese-big5-mac' and for Japanese, `sjis-mac'). See section Q.9 Specifying a Coding System, for more details.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AG.3 Environment Variables and Command Line Arguments.

Environment variables and command line arguments for Emacs can be set by modifying the `STR#' resources 128 and 129, respectively. A common environment variable that one may want to set is `HOME'.

The way to set an environment variable is by adding a string of the form
ENV_VAR=VALUE
to resource `STR#' number 128 using ResEdit. To set up the program to use unibyte characters exclusively, for example, add the string
EMACS_UNIBYTE=1
[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AG.4 Volumes and Directories on the Mac

The directory structure in the Mac OS is seen by Emacs as
/volumename/filename
So when Emacs requests a file name, doing file name completion on `/' will display all volumes on the system. You can use `..' to go up a directory level.

To access files and folders on the desktop, look in the folder `Desktop Folder' in your boot volume (this folder is usually invisible in the Mac Finder).

Emacs creates the Mac folder `:Preferences:Emacs:' in the `System Folder' and uses it as the temporary directory. Emacs maps the directory name `/tmp/' to that. Therefore it is best to avoid naming a volume `tmp'. If everything works correctly, the program should leave no files in it when it exits. You should be able to set the environment variable TMPDIR to use another directory but this folder will still be created.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AG.5 Specifying Fonts on the Mac

It is rare that you need to specify a font name in Emacs; usually you specify face attributes instead. But when you do need to specify a font name in Emacs on the Mac, use a standard X font name:
-maker-family-weight-slant-widthtype-style...
...-pixels-height-horiz-vert-spacing-width-charset
See section AE.7 Font Specification Options. Wildcards are supported as they are on X.

Native Apple fonts in Mac Roman encoding has maker name apple and charset mac-roman. For example 12-point Monaco can be specified by the name `-apple-monaco-*-12-*-mac-roman'.

Native Apple Traditional Chinese, Simplified Chinese, Japanese, and Korean fonts have charsets `big5-0', `gb2312.1980-0', `jisx0208.1983-sjis', and `ksc5601.1989-0', respectively.

Single-byte fonts converted from GNU fonts in BDF format, which are not in the Mac Roman encoding, have foundry, family, and character sets encoded in the names of their font suitcases. E.g., the font suitcase `ETL-Fixed-ISO8859-1' contains fonts which can be referred to by the name `-ETL-fixed-*-iso8859-1'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AG.6 Mac-Specific Lisp Functions

The function do-applescript takes a string argument, executes it as an AppleScript command, and returns the result as a string.

The function mac-file-name-to-posix takes a Mac file name and returns the GNU or Unix equivalent. The function posix-file-name-to-mac performs the opposite conversion. They are useful for constructing AppleScript commands to be passed to do-applescript.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH. Emacs and MS-DOS

This section briefly describes the peculiarities of using Emacs under the MS-DOS "operating system" (also known as "MS-DOG"). If you build Emacs for MS-DOS, the binary will also run on Windows 3.X, Windows NT, Windows 9X/ME, Windows 2000, or OS/2 as a DOS application; the information in this chapter applies for all of those systems, if you use an Emacs that was built for MS-DOS.

Note that it is possible to build Emacs specifically for Windows NT/2K or Windows 9X/ME. If you do that, most of this chapter does not apply; instead, you get behavior much closer to what is documented in the rest of the manual, including support for long file names, multiple frames, scroll bars, mouse menus, and subprocesses. However, the section on text files and binary files does still apply. There are also two sections at the end of this chapter which apply specifically for the Windows version.

AH.1 Keyboard and Mouse on MS-DOS

Keyboard and mouse usage on MS-DOS.

AH.2 Display on MS-DOS

Fonts, frames and display size on MS-DOS.

AH.3 File Names on MS-DOS

File name conventions on MS-DOS.

AH.4 Text Files and Binary Files

Text files on MS-DOS use CRLF to separate lines.

AH.5 Printing and MS-DOS

How to specify the printer on MS-DOS.

AH.6 International Support on MS-DOS

Support for internationalization on MS-DOS.

AH.7 Subprocesses on MS-DOS

Running subprocesses on MS-DOS.

AH.8 Subprocesses on Windows 9X/ME and Windows NT/2K

Running subprocesses on Windows.

AH.9 Using the System Menu on Windows

Controlling what the ALT key does.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.1 Keyboard and Mouse on MS-DOS

The PC keyboard maps use the left ALT key as the META key. You have two choices for emulating the SUPER and HYPER keys: choose either the right CTRL key or the right ALT key by setting the variables dos-hyper-key and dos-super-key to 1 or 2 respectively. If neither dos-super-key nor dos-hyper-key is 1, then by default the right ALT key is also mapped to the META key. However, if the MS-DOS international keyboard support program `KEYB.COM' is installed, Emacs will not map the right ALT to META, since it is used for accessing characters like ~ and @ on non-US keyboard layouts; in this case, you may only use the left ALT as META key.

The variable dos-keypad-mode is a flag variable that controls what key codes are returned by keys in the numeric keypad. You can also define the keypad ENTER key to act like C-j, by putting the following line into your `_emacs' file:
;; Make the ENTER key from the numeric keypad act as C-j.
(define-key function-key-map [kp-enter] [?\C-j])
The key that is called DEL in Emacs (because that's how it is designated on most workstations) is known as BS (backspace) on a PC. That is why the PC-specific terminal initialization remaps the BS key to act as DEL; the DEL key is remapped to act as C-d for the same reasons.

Emacs built for MS-DOS recognizes C-BREAK as a quit character, just like C-g. This is because Emacs cannot detect that you have typed C-g until it is ready for more input. As a consequence, you cannot use C-g to stop a running command (see section AD.8 Quitting and Aborting). By contrast, C-BREAK is detected as soon as you type it (as C-g is on other systems), so it can be used to stop a running command and for emergency escape (see section AD.9.8 Emergency Escape).

Emacs on MS-DOS supports a mouse (on the default terminal only). The mouse commands work as documented, including those that use menus and the menu bar (see section B.4 The Menu Bar). Scroll bars don't work in MS-DOS Emacs. PC mice usually have only two buttons; these act as Mouse-1 and Mouse-2, but if you press both of them together, that has the effect of Mouse-3. If the mouse does have 3 buttons, Emacs detects that at startup, and all the 3 buttons function normally, as on X.

Help strings for menu-bar and pop-up menus are displayed in the echo area when the mouse pointer moves across the menu items. Highlighting of mouse-sensitive text (see section P.4 Following References with the Mouse) is also supported.

Some versions of mouse drivers don't report the number of mouse buttons correctly. For example, mice with a wheel report that they have 3 buttons, but only 2 of them are passed to Emacs; the clicks on the wheel, which serves as the middle button, are not passed. In these cases, you can use the M-x msdos-set-mouse-buttons command to tell Emacs how many mouse buttons to expect. You could make such a setting permanent by adding this fragment to your `_emacs' init file:
;; Treat the mouse like a 2-button mouse.
(msdos-set-mouse-buttons 2)
Emacs built for MS-DOS supports clipboard operations when it runs on Windows. Commands that put text on the kill ring, or yank text from the ring, check the Windows clipboard first, just as Emacs does on the X Window System (see section P.1 Mouse Commands for Editing). Only the primary selection and the cut buffer are supported by MS-DOS Emacs on Windows; the secondary selection always appears as empty.

Due to the way clipboard access is implemented by Windows, the length of text you can put into the clipboard is limited by the amount of free DOS memory that is available to Emacs. Usually, up to 620KB of text can be put into the clipboard, but this limit depends on the system configuration and is lower if you run Emacs as a subprocess of another program. If the killed text does not fit, Emacs outputs a message saying so, and does not put the text into the clipboard.

Null characters also cannot be put into the Windows clipboard. If the killed text includes null characters, Emacs does not put such text into the clipboard, and displays in the echo area a message to that effect.

The variable dos-display-scancodes, when non-nil, directs Emacs to display the ASCII value and the keyboard scan code of each keystroke; this feature serves as a complement to the view-lossage command, for debugging.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.2 Display on MS-DOS

Display on MS-DOS cannot use font variants, like bold or italic, but it does support multiple faces, each of which can specify a foreground and a background color. Therefore, you can get the full functionality of Emacs packages that use fonts (such as font-lock, Enriched Text mode, and others) by defining the relevant faces to use different colors. Use the list-colors-display command (see section P.12 Setting Frame Parameters) and the list-faces-display command (see section J.1 Using Multiple Typefaces) to see what colors and faces are available and what they look like.

See section AH.6 International Support on MS-DOS, later in this chapter, for information on how Emacs displays glyphs and characters that aren't supported by the native font built into the DOS display.

When Emacs starts, it changes the cursor shape to a solid box. This is for compatibility with other systems, where the box cursor is the default in Emacs. This default shape can be changed to a bar by specifying the cursor-type parameter in the variable default-frame-alist (see section P.7 Creating Frames). The MS-DOS terminal doesn't support a vertical-bar cursor, so the bar cursor is horizontal, and the width parameter, if specified by the frame parameters, actually determines its height. As an extension, the bar cursor specification can include the starting scan line of the cursor as well as its width, like this:
 '(cursor-type bar width . start)
In addition, if the width parameter is negative, the cursor bar begins at the top of the character cell.

The MS-DOS terminal can only display a single frame at a time. The Emacs frame facilities work on MS-DOS much as they do on text-only terminals (see section P. Frames and X Windows). When you run Emacs from a DOS window on MS-Windows, you can make the visible frame smaller than the full screen, but Emacs still cannot display more than a single frame at a time.

The mode4350 command switches the display to 43 or 50 lines, depending on your hardware; the mode25 command switches to the default 80x25 screen size.

By default, Emacs only knows how to set screen sizes of 80 columns by 25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has special video modes that will switch the display to other sizes, you can have Emacs support those too. When you ask Emacs to switch the frame to n rows by m columns dimensions, it checks if there is a variable called screen-dimensions-nxm, and if so, uses its value (which must be an integer) as the video mode to switch to. (Emacs switches to that video mode by calling the BIOS Set Video Mode function with the value of screen-dimensions-nxm in the AL register.) For example, suppose your adapter will switch to 66x80 dimensions when put into video mode 85. Then you can make Emacs support this screen size by putting the following into your `_emacs' file:
(setq screen-dimensions-66x80 85)
Since Emacs on MS-DOS can only set the frame size to specific supported dimensions, it cannot honor every possible frame resizing request. When an unsupported size is requested, Emacs chooses the next larger supported size beyond the specified size. For example, if you ask for 36x80 frame, you will get 40x80 instead.

The variables screen-dimensions-nxm are used only when they exactly match the specified size; the search for the next larger supported size ignores them. In the above example, even if your VGA supports 38x80 dimensions and you define a variable screen-dimensions-38x80 with a suitable value, you will still get 40x80 screen when you ask for a 36x80 frame. If you want to get the 38x80 size in this case, you can do it by setting the variable named screen-dimensions-36x80 with the same video mode value as screen-dimensions-38x80.

Changing frame dimensions on MS-DOS has the effect of changing all the other frames to the new dimensions.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.3 File Names on MS-DOS

MS-DOS normally uses a backslash, `\', to separate name units within a file name, instead of the slash used on other systems. Emacs on MS-DOS permits use of either slash or backslash, and also knows about drive letters in file names.

On MS-DOS, file names are case-insensitive and limited to eight characters, plus optionally a period and three more characters. Emacs knows enough about these limitations to handle file names that were meant for other operating systems. For instance, leading dots `.' in file names are invalid in MS-DOS, so Emacs transparently converts them to underscores `_'; thus your default init file (see section AD.7 The Init File, `~/.emacs') is called `_emacs' on MS-DOS. Excess characters before or after the period are generally ignored by MS-DOS itself; thus, if you visit the file `LongFileName.EvenLongerExtension', you will silently get `longfile.eve', but Emacs will still display the long file name on the mode line. Other than that, it's up to you to specify file names which are valid under MS-DOS; the transparent conversion as described above only works on file names built into Emacs.

The above restrictions on the file names on MS-DOS make it almost impossible to construct the name of a backup file (see section M.3.1.1 Single or Numbered Backups) without losing some of the original file name characters. For example, the name of a backup file for `docs.txt' is `docs.tx~' even if single backup is used.

If you run Emacs as a DOS application under Windows 9X, Windows ME, or Windows 2000, you can turn on support for long file names. If you do that, Emacs doesn't truncate file names or convert them to lower case; instead, it uses the file names that you specify, verbatim. To enable long file name support, set the environment variable LFN to `y' before starting Emacs. Unfortunately, Windows NT doesn't allow DOS programs to access long file names, so Emacs built for MS-DOS will only see their short 8+3 aliases.

MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends that the directory where it is installed is the value of HOME environment variable. That is, if your Emacs binary, `emacs.exe', is in the directory `c:/utils/emacs/bin', then Emacs acts as if HOME were set to `c:/utils/emacs'. In particular, that is where Emacs looks for the init file `_emacs'. With this in mind, you can use `~' in file names as an alias for the home directory, as you would on GNU or Unix. You can also set HOME variable in the environment before starting Emacs; its value will then override the above default behavior.

Emacs on MS-DOS handles the directory name `/dev' specially, because of a feature in the emulator libraries of DJGPP that pretends I/O devices have names in that directory. We recommend that you avoid using an actual directory named `/dev' on any disk.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.4 Text Files and Binary Files

GNU Emacs uses newline characters to separate text lines. This is the convention used on GNU and Unix.

MS-DOS and MS-Windows normally use carriage-return linefeed, a two-character sequence, to separate text lines. (Linefeed is the same character as newline.) Therefore, convenient editing of typical files with Emacs requires conversion of these end-of-line (EOL) sequences. And that is what Emacs normally does: it converts carriage-return linefeed into newline when reading files, and converts newline into carriage-return linefeed when writing files. The same mechanism that handles conversion of international character codes does this conversion also (see section Q.7 Coding Systems).

One consequence of this special format-conversion of most files is that character positions as reported by Emacs (see section D.9 Cursor Position Information) do not agree with the file size information known to the operating system.

In addition, if Emacs recognizes from a file's contents that it uses newline rather than carriage-return linefeed as its line separator, it does not perform EOL conversion when reading or writing that file. Thus, you can read and edit files from GNU and Unix systems on MS-DOS with no special effort, and they will retain their Unix-style end-of-line convention after you edit them.

The mode line indicates whether end-of-line translation was used for the current buffer. If MS-DOS end-of-line translation is in use for the buffer, a backslash `\' is displayed after the coding system mnemonic near the beginning of the mode line (see section B.3 The Mode Line). If no EOL translation was performed, the string `(Unix)' is displayed instead of the backslash, to alert you that the file's EOL format is not the usual carriage-return linefeed.

To visit a file and specify whether it uses DOS-style or Unix-style end-of-line, specify a coding system (see section Q.9 Specifying a Coding System). For example, C-x RET c unix RET C-x C-f foobar.txt visits the file `foobar.txt' without converting the EOLs; if some line ends with a carriage-return linefeed pair, Emacs will display `^M' at the end of that line. Similarly, you can direct Emacs to save a buffer in a specified EOL format with the C-x RET f command. For example, to save a buffer with Unix EOL format, type C-x RET f unix RET C-x C-s. If you visit a file with DOS EOL conversion, then save it with Unix EOL format, that effectively converts the file to Unix EOL style, like dos2unix.

When you use NFS or Samba to access file systems that reside on computers using GNU or Unix systems, Emacs should not perform end-of-line translation on any files in these file systems--not even when you create a new file. To request this, designate these file systems as untranslated file systems by calling the function add-untranslated-filesystem. It takes one argument: the file system name, including a drive letter and optionally a directory. For example,
(add-untranslated-filesystem "Z:")
designates drive Z as an untranslated file system, and
(add-untranslated-filesystem "Z:\\foo")
designates directory `\foo' on drive Z as an untranslated file system.

Most often you would use add-untranslated-filesystem in your `_emacs' file, or in `site-start.el' so that all the users at your site get the benefit of it.

To countermand the effect of add-untranslated-filesystem, use the function remove-untranslated-filesystem. This function takes one argument, which should be a string just like the one that was used previously with add-untranslated-filesystem.

Designating a file system as untranslated does not affect character set conversion, only end-of-line conversion. Essentially, it directs Emacs to create new files with the Unix-style convention of using newline at the end of a line. See section Q.7 Coding Systems.

Some kinds of files should not be converted at all, because their contents are not really text. Therefore, Emacs on MS-DOS distinguishes certain files as binary files. (This distinction is not part of MS-DOS; it is made by Emacs only.) Binary files include executable programs, compressed archives, etc. Emacs uses the file name to decide whether to treat a file as binary: the variable file-name-buffer-file-type-alist defines the file-name patterns that indicate binary files. If a file name matches one of the patterns for binary files (those whose associations are of the type (pattern . t), Emacs reads and writes that file using the no-conversion coding system (see section Q.7 Coding Systems) which turns off all coding-system conversions, not only the EOL conversion. file-name-buffer-file-type-alist also includes file-name patterns for files which are known to be DOS-style text files with carriage-return linefeed EOL format, such as `CONFIG.SYS'; Emacs always writes those files with DOS-style EOLs.

If a file which belongs to an untranslated file system matches one of the file-name patterns in file-name-buffer-file-type-alist, the EOL conversion is determined by file-name-buffer-file-type-alist.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.5 Printing and MS-DOS

Printing commands, such as lpr-buffer (see section AC.18 Hardcopy Output) and ps-print-buffer (see section AC.19 PostScript Hardcopy) can work in MS-DOS and MS-Windows by sending the output to one of the printer ports, if a Posix-style lpr program is unavailable. The same Emacs variables control printing on all systems (see section AC.18 Hardcopy Output), but in some cases they have different default values on MS-DOS and MS-Windows.

If you want to use your local printer, printing on it in the usual DOS manner, then set the Lisp variable lpr-command to "" (its default value) and printer-name to the name of the printer port--for example, "PRN", the usual local printer port (that's the default), or "LPT2", or "COM1" for a serial printer. You can also set printer-name to a file name, in which case "printed" output is actually appended to that file. If you set printer-name to "NUL", printed output is silently discarded (sent to the system null device).

On MS-Windows, when the Windows network software is installed, you can also use a printer shared by another machine by setting printer-name to the UNC share name for that printer--for example, "//joes_pc/hp4si". (It doesn't matter whether you use forward slashes or backslashes here.) To find out the names of shared printers, run the command `net view' at a DOS command prompt to obtain a list of servers, and `net view server-name' to see the names of printers (and directories) shared by that server. Alternatively, click the `Network Neighborhood' icon on your desktop, and look for machines which share their printers via the network.

If the printer doesn't appear in the output of `net view', or if setting printer-name to the UNC share name doesn't produce a hardcopy on that printer, you can use the `net use' command to connect a local print port such as "LPT2" to the networked printer. For example, typing net use LPT2: \\joes_pc\hp4si (18) causes Windows to capture the LPT2 port and redirect the printed material to the printer connected to the machine joes_pc. After this command, setting printer-name to "LPT2" should produce the hardcopy on the networked printer.

With some varieties of Windows network software, you can instruct Windows to capture a specific printer port such as "LPT2", and redirect it to a networked printer via the Control Panel->Printers applet instead of `net use'.

Some printers expect DOS codepage encoding of non-ASCII text, even though they are connected to a Windows machine which uses a different encoding for the same locale. For example, in the Latin-1 locale, DOS uses codepage 850 whereas Windows uses codepage 1252. See section AH.6 International Support on MS-DOS. When you print to such printers from Windows, you can use the C-x RET c (universal-coding-system-argument) command before M-x lpr-buffer; Emacs will then convert the text to the DOS codepage that you specify. For example, C-x RET c cp850-dos RET M-x lpr-region RET will print the region while converting it to the codepage 850 encoding. You may need to create the cpnnn coding system with M-x codepage-setup.

If you set printer-name to a file name, it's best to use an absolute file name. Emacs changes the working directory according to the default directory of the current buffer, so if the file name in printer-name is relative, you will end up with several such files, each one in the directory of the buffer from which the printing was done.

The commands print-buffer and print-region call the pr program, or use special switches to the lpr program, to produce headers on each printed page. MS-DOS and MS-Windows don't normally have these programs, so by default, the variable lpr-headers-switches is set so that the requests to print page headers are silently ignored. Thus, print-buffer and print-region produce the same output as lpr-buffer and lpr-region, respectively. If you do have a suitable pr program (for example, from GNU Textutils), set lpr-headers-switches to nil; Emacs will then call pr to produce the page headers, and print the resulting output as specified by printer-name.

Finally, if you do have an lpr work-alike, you can set the variable lpr-command to "lpr". Then Emacs will use lpr for printing, as on other systems. (If the name of the program isn't lpr, set lpr-command to specify where to find it.) The variable lpr-switches has its standard meaning when lpr-command is not "". If the variable printer-name has a string value, it is used as the value for the -P option to lpr, as on Unix.

A parallel set of variables, ps-lpr-command, ps-lpr-switches, and ps-printer-name (see section AC.20 Variables for PostScript Hardcopy), defines how PostScript files should be printed. These variables are used in the same way as the corresponding variables described above for non-PostScript printing. Thus, the value of ps-printer-name is used as the name of the device (or file) to which PostScript output is sent, just as printer-name is used for non-PostScript printing. (There are two distinct sets of variables in case you have two printers attached to two different ports, and only one of them is a PostScript printer.)

The default value of the variable ps-lpr-command is "", which causes PostScript output to be sent to the printer port specified by ps-printer-name, but ps-lpr-command can also be set to the name of a program which will accept PostScript files. Thus, if you have a non-PostScript printer, you can set this variable to the name of a PostScript interpreter program (such as Ghostscript). Any switches that need to be passed to the interpreter program are specified using ps-lpr-switches. (If the value of ps-printer-name is a string, it will be added to the list of switches as the value for the -P option. This is probably only useful if you are using lpr, so when using an interpreter typically you would set ps-printer-name to something other than a string so it is ignored.)

For example, to use Ghostscript for printing on an Epson printer connected to the `LPT2' port, put this in your `_emacs' file:
(setq ps-printer-name t)  ; Ghostscript doesn't understand -P
(setq ps-lpr-command "c:/gs/gs386")
(setq ps-lpr-switches '("-q" "-dNOPAUSE"
            "-sDEVICE=epson"
            "-r240x72"
            "-sOutputFile=LPT2"
            "-Ic:/gs"))
(This assumes that Ghostscript is installed in the `"c:/gs"' directory.)

For backwards compatibility, the value of dos-printer (dos-ps-printer), if it has a value, overrides the value of printer-name (ps-printer-name), on MS-DOS and MS-Windows only.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.6 International Support on MS-DOS

Emacs on MS-DOS supports the same international character sets as it does on GNU, Unix and other platforms (see section Q. International Character Set Support), including coding systems for converting between the different character sets. However, due to incompatibilities between MS-DOS/MS-Windows and other systems, there are several DOS-specific aspects of this support that you should be aware of. This section describes these aspects.

M-x dos-codepage-setup
Set up Emacs display and coding systems as appropriate for the current DOS codepage.

M-x codepage-setup
Create a coding system for a certain DOS codepage.
MS-DOS is designed to support one character set of 256 characters at any given time, but gives you a variety of character sets to choose from. The alternative character sets are known as DOS codepages. Each codepage includes all 128 ASCII characters, but the other 128 characters (codes 128 through 255) vary from one codepage to another. Each DOS codepage is identified by a 3-digit number, such as 850, 862, etc.

In contrast to X, which lets you use several fonts at the same time, MS-DOS normally doesn't allow use of several codepages in a single session. MS-DOS was designed to load a single codepage at system startup, and require you to reboot in order to change it(19). Much the same limitation applies when you run DOS executables on other systems such as MS-Windows.

If you invoke Emacs on MS-DOS with the `--unibyte' option (see section AE.2 Initial Options), Emacs does not perform any conversion of non-ASCII characters. Instead, it reads and writes any non-ASCII characters verbatim, and sends their 8-bit codes to the display verbatim. Thus, unibyte Emacs on MS-DOS supports the current codepage, whatever it may be, but cannot even represent any other characters.

For multibyte operation on MS-DOS, Emacs needs to know which characters the chosen DOS codepage can display. So it queries the system shortly after startup to get the chosen codepage number, and stores the number in the variable dos-codepage. Some systems return the default value 437 for the current codepage, even though the actual codepage is different. (This typically happens when you use the codepage built into the display hardware.) You can specify a different codepage for Emacs to use by setting the variable dos-codepage in your init file.

Multibyte Emacs supports only certain DOS codepages: those which can display Far-Eastern scripts, like the Japanese codepage 932, and those that encode a single ISO 8859 character set.

The Far-Eastern codepages can directly display one of the MULE character sets for these countries, so Emacs simply sets up to use the appropriate terminal coding system that is supported by the codepage. The special features described in the rest of this section mostly pertain to codepages that encode ISO 8859 character sets.

For the codepages which correspond to one of the ISO character sets, Emacs knows the character set name based on the codepage number. Emacs automatically creates a coding system to support reading and writing files that use the current codepage, and uses this coding system by default. The name of this coding system is cpnnn, where nnn is the codepage number.(20)

All the cpnnn coding systems use the letter `D' (for "DOS") as their mode-line mnemonic. Since both the terminal coding system and the default coding system for file I/O are set to the proper cpnnn coding system at startup, it is normal for the mode line on MS-DOS to begin with `-DD\-'. See section B.3 The Mode Line. Far-Eastern DOS terminals do not use the cpnnn coding systems, and thus their initial mode line looks like the Emacs default.

Since the codepage number also indicates which script you are using, Emacs automatically runs set-language-environment to select the language environment for that script (see section Q.3 Language Environments).

If a buffer contains a character belonging to some other ISO 8859 character set, not the one that the chosen DOS codepage supports, Emacs displays it using a sequence of ASCII characters. For example, if the current codepage doesn't have a glyph for the letter `ò' (small `o' with a grave accent), it is displayed as `{`o}', where the braces serve as a visual indication that this is a single character. (This may look awkward for some non-Latin characters, such as those from Greek or Hebrew alphabets, but it is still readable by a person who knows the language.) Even though the character may occupy several columns on the screen, it is really still just a single character, and all Emacs commands treat it as one.

Not all characters in DOS codepages correspond to ISO 8859 characters--some are used for other purposes, such as box-drawing characters and other graphics. Emacs maps these characters to two special character sets called eight-bit-control and eight-bit-graphic, and displays them as their IBM glyphs. However, you should be aware that other systems might display these characters differently, so you should avoid them in text that might be copied to a different operating system, or even to another DOS machine that uses a different codepage.

Emacs supports many other characters sets aside from ISO 8859, but it cannot display them on MS-DOS. So if one of these multibyte characters appears in a buffer, Emacs on MS-DOS displays them as specified by the dos-unsupported-character-glyph variable; by default, this glyph is an empty triangle. Use the C-u C-x = command to display the actual code and character set of such characters. See section D.9 Cursor Position Information.

By default, Emacs defines a coding system to support the current codepage. To define a coding system for some other codepage (e.g., to visit a file written on a DOS machine in another country), use the M-x codepage-setup command. It prompts for the 3-digit code of the codepage, with completion, then creates the coding system for the specified codepage. You can then use the new coding system to read and write files, but you must specify it explicitly for the file command when you want to use it (see section Q.9 Specifying a Coding System).

These coding systems are also useful for visiting a file encoded using a DOS codepage, using Emacs running on some other operating system.

MS-Windows provides its own codepages, which are different from the DOS codepages for the same locale. For example, DOS codepage 850 supports the same character set as Windows codepage 1252; DOS codepage 855 supports the same character set as Windows codepage 1251, etc. The MS-Windows version of Emacs uses the current codepage for display when invoked with the `-nw' option.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.7 Subprocesses on MS-DOS

Because MS-DOS is a single-process "operating system," asynchronous subprocesses are not available. In particular, Shell mode and its variants do not work. Most Emacs features that use asynchronous subprocesses also don't work on MS-DOS, including Shell mode and GUD. When in doubt, try and see; commands that don't work output an error message saying that asynchronous processes aren't supported.

Compilation under Emacs with M-x compile, searching files with M-x grep and displaying differences between files with M-x diff do work, by running the inferior processes synchronously. This means you cannot do any more editing until the inferior process finishes.

Spell checking also works, by means of special support for synchronous invocation of the ispell program. This is slower than the asynchronous invocation on other platforms

Instead of the Shell mode, which doesn't work on MS-DOS, you can use the M-x eshell command. This invokes the Eshell package that implements a Posix-like shell entirely in Emacs Lisp.

By contrast, Emacs compiled as native Windows application does support asynchronous subprocesses. See section AH.8 Subprocesses on Windows 9X/ME and Windows NT/2K.

Printing commands, such as lpr-buffer (see section AC.18 Hardcopy Output) and ps-print-buffer (see section AC.19 PostScript Hardcopy), work in MS-DOS by sending the output to one of the printer ports. See section AH.5 Printing and MS-DOS.

When you run a subprocess synchronously on MS-DOS, make sure the program terminates and does not try to read keyboard input. If the program does not terminate on its own, you will be unable to terminate it, because MS-DOS provides no general way to terminate a process. Pressing C-c or C-BREAK might sometimes help in these cases.

Accessing files on other machines is not supported on MS-DOS. Other network-oriented commands such as sending mail, Web browsing, remote login, etc., don't work either, unless network access is built into MS-DOS with some network redirector.

Dired on MS-DOS uses the ls-lisp package where other platforms use the system ls command. Therefore, Dired on MS-DOS supports only some of the possible options you can mention in the dired-listing-switches variable. The options that work are `-A', `-a', `-c', `-i', `-r', `-S', `-s', `-t', and `-u'.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.8 Subprocesses on Windows 9X/ME and Windows NT/2K

Emacs compiled as a native Windows application (as opposed to the DOS version) includes full support for asynchronous subprocesses. In the Windows version, synchronous and asynchronous subprocesses work fine on both Windows 9X and Windows NT/2K as long as you run only 32-bit Windows applications. However, when you run a DOS application in a subprocess, you may encounter problems or be unable to run the application at all; and if you run two DOS applications at the same time in two subprocesses, you may have to reboot your system.

Since the standard command interpreter (and most command line utilities) on Windows 95 are DOS applications, these problems are significant when using that system. But there's nothing we can do about them; only Microsoft can fix them.

If you run just one DOS application subprocess, the subprocess should work as expected as long as it is "well-behaved" and does not perform direct screen access or other unusual actions. If you have a CPU monitor application, your machine will appear to be 100% busy even when the DOS application is idle, but this is only an artifact of the way CPU monitors measure processor load.

You must terminate the DOS application before you start any other DOS application in a different subprocess. Emacs is unable to interrupt or terminate a DOS subprocess. The only way you can terminate such a subprocess is by giving it a command that tells its program to exit.

If you attempt to run two DOS applications at the same time in separate subprocesses, the second one that is started will be suspended until the first one finishes, even if either or both of them are asynchronous.

If you can go to the first subprocess, and tell it to exit, the second subprocess should continue normally. However, if the second subprocess is synchronous, Emacs itself will be hung until the first subprocess finishes. If it will not finish without user input, then you have no choice but to reboot if you are running on Windows 9X. If you are running on Windows NT/2K, you can use a process viewer application to kill the appropriate instance of ntvdm instead (this will terminate both DOS subprocesses).

If you have to reboot Windows 9X in this situation, do not use the Shutdown command on the Start menu; that usually hangs the system. Instead, type CTL-ALT-DEL and then choose Shutdown. That usually works, although it may take a few minutes to do its job.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AH.9 Using the System Menu on Windows

Emacs compiled as a native Windows application normally turns off the Windows feature that tapping the ALT key invokes the Windows menu. The reason is that the ALT also serves as META in Emacs. When using Emacs, users often press the META key temporarily and then change their minds; if this has the effect of bringing up the Windows menu, it alters the meaning of subsequent commands. Many users find this frustrating.

You can reenable Windows's default handling of tapping the ALT key by setting w32-pass-alt-to-system to a non-nil value.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

The GNU Manifesto

The GNU Manifesto which appears below was written by Richard Stallman at the beginning of the GNU project, to ask for participation and support. For the first few years, it was updated in minor ways to account for developments, but now it seems best to leave it unchanged as most people have seen it.
Since that time, we have learned about certain common misunderstandings that different wording could help avoid. Footnotes added in 1993 help clarify these points.

For up-to-date information about the available GNU software, please see the latest issue of the GNU's Bulletin. The list is much too long to include here.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

What's GNU? Gnu's Not Unix!

GNU, which stands for Gnu's Not Unix, is the name for the complete Unix-compatible software system which I am writing so that I can give it away free to everyone who can use it.(21) Several other volunteers are helping me. Contributions of time, money, programs and equipment are greatly needed.

So far we have an Emacs text editor with Lisp for writing editor commands, a source level debugger, a yacc-compatible parser generator, a linker, and around 35 utilities. A shell (command interpreter) is nearly completed. A new portable optimizing C compiler has compiled itself and may be released this year. An initial kernel exists but many more features are needed to emulate Unix. When the kernel and compiler are finished, it will be possible to distribute a GNU system suitable for program development. We will use TeX as our text formatter, but an nroff is being worked on. We will use the free, portable X window system as well. After this we will add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of other things, plus on-line documentation. We hope to supply, eventually, everything useful that normally comes with a Unix system, and more.

GNU will be able to run Unix programs, but will not be identical to Unix. We will make all improvements that are convenient, based on our experience with other operating systems. In particular, we plan to have longer file names, file version numbers, a crashproof file system, file name completion perhaps, terminal-independent display support, and perhaps eventually a Lisp-based window system through which several Lisp programs and ordinary Unix programs can share a screen. Both C and Lisp will be available as system programming languages. We will try to support UUCP, MIT Chaosnet, and Internet protocols for communication.

GNU is aimed initially at machines in the 68000/16000 class with virtual memory, because they are the easiest machines to make it run on. The extra effort to make it run on smaller machines will be left to someone who wants to use it on them.

To avoid horrible confusion, please pronounce the `G' in the word `GNU' when it is the name of this project.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Why I Must Write GNU

I consider that the golden rule requires that if I like a program I must share it with other people who like it. Software sellers want to divide the users and conquer them, making each user agree not to share with others. I refuse to break solidarity with other users in this way. I cannot in good conscience sign a nondisclosure agreement or a software license agreement. For years I worked within the Artificial Intelligence Lab to resist such tendencies and other inhospitalities, but eventually they had gone too far: I could not remain in an institution where such things are done for me against my will.

So that I can continue to use computers without dishonor, I have decided to put together a sufficient body of free software so that I will be able to get along without any software that is not free. I have resigned from the AI lab to deny MIT any legal excuse to prevent me from giving GNU away.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Why GNU Will Be Compatible with Unix

Unix is not my ideal system, but it is not too bad. The essential features of Unix seem to be good ones, and I think I can fill in what Unix lacks without spoiling them. And a system compatible with Unix would be convenient for many other people to adopt.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

How GNU Will Be Available

GNU is not in the public domain. Everyone will be permitted to modify and redistribute GNU, but no distributor will be allowed to restrict its further redistribution. That is to say, proprietary modifications will not be allowed. I want to make sure that all versions of GNU remain free.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Why Many Other Programmers Want to Help

I have found many other programmers who are excited about GNU and want to help.

Many programmers are unhappy about the commercialization of system software. It may enable them to make more money, but it requires them to feel in conflict with other programmers in general rather than feel as comrades. The fundamental act of friendship among programmers is the sharing of programs; marketing arrangements now typically used essentially forbid programmers to treat others as friends. The purchaser of software must choose between friendship and obeying the law. Naturally, many decide that friendship is more important. But those who believe in law often do not feel at ease with either choice. They become cynical and think that programming is just a way of making money.

By working on and using GNU rather than proprietary programs, we can be hospitable to everyone and obey the law. In addition, GNU serves as an example to inspire and a banner to rally others to join us in sharing. This can give us a feeling of harmony which is impossible if we use software that is not free. For about half the programmers I talk to, this is an important happiness that money cannot replace.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

How You Can Contribute

I am asking computer manufacturers for donations of machines and money. I'm asking individuals for donations of programs and work.

One consequence you can expect if you donate machines is that GNU will run on them at an early date. The machines should be complete, ready to use systems, approved for use in a residential area, and not in need of sophisticated cooling or power.

I have found very many programmers eager to contribute part-time work for GNU. For most projects, such part-time distributed work would be very hard to coordinate; the independently-written parts would not work together. But for the particular task of replacing Unix, this problem is absent. A complete Unix system contains hundreds of utility programs, each of which is documented separately. Most interface specifications are fixed by Unix compatibility. If each contributor can write a compatible replacement for a single Unix utility, and make it work properly in place of the original on a Unix system, then these utilities will work right when put together. Even allowing for Murphy to create a few unexpected problems, assembling these components will be a feasible task. (The kernel will require closer communication and will be worked on by a small, tight group.)

If I get donations of money, I may be able to hire a few people full or part time. The salary won't be high by programmers' standards, but I'm looking for people for whom building community spirit is as important as making money. I view this as a way of enabling dedicated people to devote their full energies to working on GNU by sparing them the need to make a living in another way.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Why All Computer Users Will Benefit

Once GNU is written, everyone will be able to obtain good system software free, just like air.(22)

This means much more than just saving everyone the price of a Unix license. It means that much wasteful duplication of system programming effort will be avoided. This effort can go instead into advancing the state of the art.

Complete system sources will be available to everyone. As a result, a user who needs changes in the system will always be free to make them himself, or hire any available programmer or company to make them for him. Users will no longer be at the mercy of one programmer or company which owns the sources and is in sole position to make changes.

Schools will be able to provide a much more educational environment by encouraging all students to study and improve the system code. Harvard's computer lab used to have the policy that no program could be installed on the system if its sources were not on public display, and upheld it by actually refusing to install certain programs. I was very much inspired by this.

Finally, the overhead of considering who owns the system software and what one is or is not entitled to do with it will be lifted.

Arrangements to make people pay for using a program, including licensing of copies, always incur a tremendous cost to society through the cumbersome mechanisms necessary to figure out how much (that is, which programs) a person must pay for. And only a police state can force everyone to obey them. Consider a space station where air must be manufactured at great cost: charging each breather per liter of air may be fair, but wearing the metered gas mask all day and all night is intolerable even if everyone can afford to pay the air bill. And the TV cameras everywhere to see if you ever take the mask off are outrageous. It's better to support the air plant with a head tax and chuck the masks.

Copying all or parts of a program is as natural to a programmer as breathing, and as productive. It ought to be as free.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Some Easily Rebutted Objections to GNU's Goals

"Nobody will use it if it is free, because that means they can't rely on any support."
"You have to charge for the program to pay for providing the support."

If people would rather pay for GNU plus service than get GNU free without service, a company to provide just service to people who have obtained GNU free ought to be profitable.(23)

We must distinguish between support in the form of real programming work and mere handholding. The former is something one cannot rely on from a software vendor. If your problem is not shared by enough people, the vendor will tell you to get lost.

If your business needs to be able to rely on support, the only way is to have all the necessary sources and tools. Then you can hire any available person to fix your problem; you are not at the mercy of any individual. With Unix, the price of sources puts this out of consideration for most businesses. With GNU this will be easy. It is still possible for there to be no available competent person, but this problem cannot be blamed on distribution arrangements. GNU does not eliminate all the world's problems, only some of them.

Meanwhile, the users who know nothing about computers need handholding: doing things for them which they could easily do themselves but don't know how.

Such services could be provided by companies that sell just hand-holding and repair service. If it is true that users would rather spend money and get a product with service, they will also be willing to buy the service having got the product free. The service companies will compete in quality and price; users will not be tied to any particular one. Meanwhile, those of us who don't need the service should be able to use the program without paying for the service.

"You cannot reach many people without advertising, and you must charge for the program to support that."
"It's no use advertising a program people can get free."

There are various forms of free or very cheap publicity that can be used to inform numbers of computer users about something like GNU. But it may be true that one can reach more microcomputer users with advertising. If this is really so, a business which advertises the service of copying and mailing GNU for a fee ought to be successful enough to pay for its advertising and more. This way, only the users who benefit from the advertising pay for it.

On the other hand, if many people get GNU from their friends, and such companies don't succeed, this will show that advertising was not really necessary to spread GNU. Why is it that free market advocates don't want to let the free market decide this?(24)

"My company needs a proprietary operating system to get a competitive edge."

GNU will remove operating system software from the realm of competition. You will not be able to get an edge in this area, but neither will your competitors be able to get an edge over you. You and they will compete in other areas, while benefiting mutually in this one. If your business is selling an operating system, you will not like GNU, but that's tough on you. If your business is something else, GNU can save you from being pushed into the expensive business of selling operating systems.

I would like to see GNU development supported by gifts from many manufacturers and users, reducing the cost to each.(25)

"Don't programmers deserve a reward for their creativity?"

If anything deserves a reward, it is social contribution. Creativity can be a social contribution, but only in so far as society is free to use the results. If programmers deserve to be rewarded for creating innovative programs, by the same token they deserve to be punished if they restrict the use of these programs.

"Shouldn't a programmer be able to ask for a reward for his creativity?"

There is nothing wrong with wanting pay for work, or seeking to maximize one's income, as long as one does not use means that are destructive. But the means customary in the field of software today are based on destruction.

Extracting money from users of a program by restricting their use of it is destructive because the restrictions reduce the amount and the ways that the program can be used. This reduces the amount of wealth that humanity derives from the program. When there is a deliberate choice to restrict, the harmful consequences are deliberate destruction.

The reason a good citizen does not use such destructive means to become wealthier is that, if everyone did so, we would all become poorer from the mutual destructiveness. This is Kantian ethics; or, the Golden Rule. Since I do not like the consequences that result if everyone hoards information, I am required to consider it wrong for one to do so. Specifically, the desire to be rewarded for one's creativity does not justify depriving the world in general of all or part of that creativity.

"Won't programmers starve?"

I could answer that nobody is forced to be a programmer. Most of us cannot manage to get any money for standing on the street and making faces. But we are not, as a result, condemned to spend our lives standing on the street making faces, and starving. We do something else.

But that is the wrong answer because it accepts the questioner's implicit assumption: that without ownership of software, programmers cannot possibly be paid a cent. Supposedly it is all or nothing.

The real reason programmers will not starve is that it will still be possible for them to get paid for programming; just not paid as much as now.

Restricting copying is not the only basis for business in software. It is the most common basis because it brings in the most money. If it were prohibited, or rejected by the customer, software business would move to other bases of organization which are now used less often. There are always numerous ways to organize any kind of business.

Probably programming will not be as lucrative on the new basis as it is now. But that is not an argument against the change. It is not considered an injustice that sales clerks make the salaries that they now do. If programmers made the same, that would not be an injustice either. (In practice they would still make considerably more than that.)

"Don't people have a right to control how their creativity is used?"

"Control over the use of one's ideas" really constitutes control over other people's lives; and it is usually used to make their lives more difficult.

People who have studied the issue of intellectual property rights carefully (such as lawyers) say that there is no intrinsic right to intellectual property. The kinds of supposed intellectual property rights that the government recognizes were created by specific acts of legislation for specific purposes.

For example, the patent system was established to encourage inventors to disclose the details of their inventions. Its purpose was to help society rather than to help inventors. At the time, the life span of 17 years for a patent was short compared with the rate of advance of the state of the art. Since patents are an issue only among manufacturers, for whom the cost and effort of a license agreement are small compared with setting up production, the patents often do not do much harm. They do not obstruct most individuals who use patented products.

The idea of copyright did not exist in ancient times, when authors frequently copied other authors at length in works of non-fiction. This practice was useful, and is the only way many authors' works have survived even in part. The copyright system was created expressly for the purpose of encouraging authorship. In the domain for which it was invented--books, which could be copied economically only on a printing press--it did little harm, and did not obstruct most of the individuals who read the books.

All intellectual property rights are just licenses granted by society because it was thought, rightly or wrongly, that society as a whole would benefit by granting them. But in any particular situation, we have to ask: are we really better off granting such license? What kind of act are we licensing a person to do?

The case of programs today is very different from that of books a hundred years ago. The fact that the easiest way to copy a program is from one neighbor to another, the fact that a program has both source code and object code which are distinct, and the fact that a program is used rather than read and enjoyed, combine to create a situation in which a person who enforces a copyright is harming society as a whole both materially and spiritually; in which a person should not do so regardless of whether the law enables him to.

"Competition makes things get done better."

The paradigm of competition is a race: by rewarding the winner, we encourage everyone to run faster. When capitalism really works this way, it does a good job; but its defenders are wrong in assuming it always works this way. If the runners forget why the reward is offered and become intent on winning, no matter how, they may find other strategies--such as, attacking other runners. If the runners get into a fist fight, they will all finish late.

Proprietary and secret software is the moral equivalent of runners in a fist fight. Sad to say, the only referee we've got does not seem to object to fights; he just regulates them ("For every ten yards you run, you can fire one shot"). He really ought to break them up, and penalize runners for even trying to fight.

"Won't everyone stop programming without a monetary incentive?"

Actually, many people will program with absolutely no monetary incentive. Programming has an irresistible fascination for some people, usually the people who are best at it. There is no shortage of professional musicians who keep at it even though they have no hope of making a living that way.

But really this question, though commonly asked, is not appropriate to the situation. Pay for programmers will not disappear, only become less. So the right question is, will anyone program with a reduced monetary incentive? My experience shows that they will.

For more than ten years, many of the world's best programmers worked at the Artificial Intelligence Lab for far less money than they could have had anywhere else. They got many kinds of non-monetary rewards: fame and appreciation, for example. And creativity is also fun, a reward in itself.

Then most of them left when offered a chance to do the same interesting work for a lot of money.

What the facts show is that people will program for reasons other than riches; but if given a chance to make a lot of money as well, they will come to expect and demand it. Low-paying organizations do poorly in competition with high-paying ones, but they do not have to do badly if the high-paying ones are banned.

"We need the programmers desperately. If they demand that we stop helping our neighbors, we have to obey."

You're never so desperate that you have to obey this sort of demand. Remember: millions for defense, but not a cent for tribute!

"Programmers need to make a living somehow."

In the short run, this is true. However, there are plenty of ways that programmers could make a living without selling the right to use a program. This way is customary now because it brings programmers and businessmen the most money, not because it is the only way to make a living. It is easy to find other ways if you want to find them. Here are a number of examples.

A manufacturer introducing a new computer will pay for the porting of operating systems onto the new hardware.

The sale of teaching, hand-holding and maintenance services could also employ programmers.

People with new ideas could distribute programs as freeware, asking for donations from satisfied users, or selling hand-holding services. I have met people who are already working this way successfully.

Users with related needs can form users' groups, and pay dues. A group would contract with programming companies to write programs that the group's members would like to use.

All sorts of development can be funded with a Software Tax:

Suppose everyone who buys a computer has to pay x percent of the price as a software tax. The government gives this to an agency like the NSF to spend on software development.
But if the computer buyer makes a donation to software development himself, he can take a credit against the tax. He can donate to the project of his own choosing--often, chosen because he hopes to use the results when it is done. He can take a credit for any amount of donation up to the total tax he had to pay.

The total tax rate could be decided by a vote of the payers of the tax, weighted according to the amount they will be taxed on.

The consequences:

The computer-using community supports software development.
This community decides what level of support is needed.
Users who care which projects their share is spent on can choose this for themselves.

In the long run, making programs free is a step toward the post-scarcity world, where nobody will have to work very hard just to make a living. People will be free to devote themselves to activities that are fun, such as programming, after spending the necessary ten hours a week on required tasks such as legislation, family counseling, robot repair and asteroid prospecting. There will be no need to be able to make a living from programming.

We have already greatly reduced the amount of work that the whole society must do for its actual productivity, but only a little of this has translated itself into leisure for workers because much nonproductive activity is required to accompany productive activity. The main causes of this are bureaucracy and isometric struggles against competition. Free software will greatly reduce these drains in the area of software production. We must do this, in order for technical gains in productivity to translate into less work for us.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Glossary

Abbrev
An abbrev is a text string which expands into a different text string when present in the buffer. For example, you might define a few letters as an abbrev for a long phrase that you want to insert frequently. See section X. Abbrevs.

Aborting
Aborting means getting out of a recursive edit (q.v.). The commands C-] and M-x top-level are used for this. See section AD.8 Quitting and Aborting.

Alt
Alt is the name of a modifier bit which a keyboard input character may have. To make a character Alt, type it while holding down the ALT key. Such characters are given names that start with Alt- (usually written A- for short). (Note that many terminals have a key labeled ALT which is really a META key.) See section Alt.

Argument
See `numeric argument.'

ASCII character
An ASCII character is either an ASCII control character or an ASCII printing character. See section B.5 Kinds of User Input.

ASCII control character
An ASCII control character is the Control version of an upper-case letter, or the Control version of one of the characters `@[\]^_?'.

ASCII printing character
ASCII printing characters include letters, digits, space, and these punctuation characters: `!@#$%^& *()_-+=|\~` {}[]:;"' <>,.?/'.

Auto Fill Mode
Auto Fill mode is a minor mode in which text that you insert is automatically broken into lines of a given maximum width. See section T.5 Filling Text.

Auto Saving
Auto saving is the practice of saving the contents of an Emacs buffer in a specially-named file, so that the information will not be lost if the buffer is lost due to a system error or user error. See section M.5 Auto-Saving: Protection Against Disasters.

Autoloading
Emacs automatically loads Lisp libraries when a Lisp program requests a function or a variable from those libraries. This is called `autoloading'. See section V.7 Libraries of Lisp Code for Emacs.

Backtrace
A backtrace is a trace of a series of function calls showing how a program arrived to a certain point. It is used mainly for finding and correcting bugs (q.v.). Emacs can display a backtrace when it signals an error or when you type C-g (see `quitting'). See section AD.10.3 Checklist for Bug Reports.

Backup File
A backup file records the contents that a file had before the current editing session. Emacs makes backup files automatically to help you track down or cancel changes you later regret making. See section M.3.1 Backup Files.

Balance Parentheses
Emacs can balance parentheses (or other matching delimiters) either manually or automatically. You do manual balancing with the commands to move over parenthetical groupings (see section U.4.2 Moving in the Parenthesis Structure). Automatic balancing works by blinking or highlighting the delimiter that matches the one you just inserted (see section Matching Parens).

Balanced Expressions
A balanced expression is a syntactically recognizable expression, such as a symbol, number, string constant, block, or parenthesized expression in C. See section Balanced Expressions.

Balloon Help
See `tooltips.'

Base Buffer
A base buffer is a buffer whose text is shared by an indirect buffer (q.v.).

Bind
To bind a key sequence means to give it a binding (q.v.). See section AD.4.5 Changing Key Bindings Interactively.

Binding
A key sequence gets its meaning in Emacs by having a binding, which is a command (q.v.), a Lisp function that is run when the user types that sequence. See section Binding. Customization often involves rebinding a character to a different command function. The bindings of all key sequences are recorded in the keymaps (q.v.). See section AD.4.1 Keymaps.

Blank Lines
Blank lines are lines that contain only whitespace. Emacs has several commands for operating on the blank lines in the buffer.

Bookmark
Bookmarks are akin to registers (q.v.) in that they record positions in buffers to which you can return later. Unlike registers, bookmarks persist between Emacs sessions.

Buffer
The buffer is the basic editing unit; one buffer corresponds to one text being edited. You can have several buffers, but at any time you are editing only one, the `current buffer,' though several can be visible when you are using multiple windows (q.v.). Most buffers are visiting (q.v.) some file. See section N. Using Multiple Buffers.

Buffer Selection History
Emacs keeps a buffer selection history which records how recently each Emacs buffer has been selected. This is used for choosing a buffer to select. See section N. Using Multiple Buffers.

Bug
A bug is an incorrect or unreasonable behavior of a program, or inaccurate or confusing documentation. Emacs developers treat bug reports, both in Emacs code and its documentation, very seriously and ask you to report any bugs you find. See section AD.10 Reporting Bugs.

Button Down Event
A button down event is the kind of input event generated right away when you press down on a mouse button. See section AD.4.10 Rebinding Mouse Buttons.

By Default
See `default.'

C-
C- in the name of a character is an abbreviation for Control. See section C-.

C-M-
C-M- in the name of a character is an abbreviation for Control-Meta. See section C-M-.

Case Conversion
Case conversion means changing text from upper case to lower case or vice versa. See section T.6 Case Conversion Commands, for the commands for case conversion.

Character
Characters form the contents of an Emacs buffer; see B.8 Character Set for Text. Also, key sequences (q.v.) are usually made up of characters (though they may include other input events as well). See section B.5 Kinds of User Input.

Character Set
Emacs supports a number of character sets, each of which represents a particular alphabet or script. See section Q. International Character Set Support.

Character Terminal
See `text-only terminal.'

Click Event
A click event is the kind of input event generated when you press a mouse button and release it without moving the mouse. See section AD.4.10 Rebinding Mouse Buttons.

Clipboard
A clipboard is a buffer provided by the window system for transferring text between applications. On the X Window system, the clipboard is provided in addition to the primary selection (q.v.); on MS-Windows, the clipboard is used instead of the primary selection. See section P.3 Using the Clipboard.

Coding System
A coding system is an encoding for representing text characters in a file or in a stream of information. Emacs has the ability to convert text to or from a variety of coding systems when reading or writing it. See section Q.7 Coding Systems.

Command
A command is a Lisp function specially defined to be able to serve as a key binding in Emacs. When you type a key sequence (q.v.), its binding (q.v.) is looked up in the relevant keymaps (q.v.) to find the command to run. See section B.7 Keys and Commands.

Command History
See `minibuffer history.'

Command Name
A command name is the name of a Lisp symbol which is a command (see section B.7 Keys and Commands). You can invoke any command by its name using M-x (see section Running Commands by Name).

Comment
A comment is text in a program which is intended only for humans reading the program, and which is marked specially so that it will be ignored when the program is loaded or compiled. Emacs offers special commands for creating, aligning and killing comments. See section U.5 Manipulating Comments.

Common Lisp
Common Lisp is a dialect of Lisp (q.v.) much larger and more powerful than Emacs Lisp. Emacs provides a subset of Common Lisp in the CL package. See section `Common Lisp' in Common Lisp Extensions.

Compilation
Compilation is the process of creating an executable program from source code. Emacs has commands for compiling files of Emacs Lisp code (see section `Byte Compilation' in the Emacs Lisp Reference Manual) and programs in C and other languages (see section V.1 Running Compilations under Emacs).

Complete Key
A complete key is a key sequence which fully specifies one action to be performed by Emacs. For example, X and C-f and C-x m are complete keys. Complete keys derive their meanings from being bound (q.v.) to commands (q.v.). Thus, X is conventionally bound to a command to insert `X' in the buffer; C-x m is conventionally bound to a command to begin composing a mail message. See section B.6 Keys.

Completion
Completion is what Emacs does when it automatically fills out an abbreviation for a name into the entire name. Completion is done for minibuffer (q.v.) arguments when the set of possible valid inputs is known; for example, on command names, buffer names, and file names. Completion occurs when TAB, SPC or RET is typed. See section E.3 Completion.

Continuation Line
When a line of text is longer than the width of the window, it takes up more than one screen line when displayed. We say that the text line is continued, and all screen lines used for it after the first are called continuation lines. See section Basic Editing. A related Emacs feature is `filling' (q.v.).

Control Character
A control character is a character that you type by holding down the CTRL key. Some control characters also have their own keys, so that you can type them without using CTRL. For example, RET, TAB, ESC and DEL are all control characters. See section B.5 Kinds of User Input.

Copyleft
A copyleft is a notice giving the public legal permission to redistribute a program or other work of art. Copylefts are used by left-wing programmers to promote freedom and cooperation, just as copyrights are used by right-wing programmers to gain power over other people.
The particular form of copyleft used by the GNU project is called the GNU General Public License. See section GNU GENERAL PUBLIC LICENSE.

Current Buffer
The current buffer in Emacs is the Emacs buffer on which most editing commands operate. You can select any Emacs buffer as the current one. See section N. Using Multiple Buffers.

Current Line
The current line is a line point is on (see section B.1 Point).

Current Paragraph
The current paragraph is the paragraph that point is in. If point is between two paragraphs, the current paragraph is the one that follows point. See section T.3 Paragraphs.

Current Defun
The current defun is the defun (q.v.) that point is in. If point is between defuns, the current defun is the one that follows point. See section U.2 Top-Level Definitions, or Defuns.

Cursor
The cursor is the rectangle on the screen which indicates the position called point (q.v.) at which insertion and deletion takes place. The cursor is on or under the character that follows point. Often people speak of `the cursor' when, strictly speaking, they mean `point.' See section Basic Editing.

Customization
Customization is making minor changes in the way Emacs works. It is often done by setting variables (see section AD.2 Variables) or by rebinding key sequences (see section AD.4.1 Keymaps).

Cut and Paste
See `killing' and `yanking.'

Default Argument
The default for an argument is the value that will be assumed if you do not specify one. When the minibuffer is used to read an argument, the default argument is used if you just type RET. See section E. The Minibuffer.

Default
A default is the value that is used for a certain purpose if and when you do not specify a value to use.

Default Directory
When you specify a file name that does not start with `/' or `~', it is interpreted relative to the current buffer's default directory. (On MS-Windows and MS-DOS, file names which start with a drive letter `x:' are treated as absolute, not relative.) See section Default Directory.

Defun
A defun is a major definition at the top level in a program. The name `defun' comes from Lisp, where most such definitions use the construct defun. See section U.2 Top-Level Definitions, or Defuns.

DEL
DEL is a character that runs the command to delete one character of text. See section Basic Editing.

Deletion
Deletion means erasing text without copying it into the kill ring (q.v.). The alternative is killing (q.v.). See section Deletion.

Deletion of Files
Deleting a file means erasing it from the file system. See section Miscellaneous File Operations.

Deletion of Messages
Deleting a message means flagging it to be eliminated from your mail file. Until you expunge (q.v.) the Rmail file, you can still undelete the messages you have deleted. See section AA.4 Deleting Messages.

Deletion of Windows
Deleting a window means eliminating it from the screen. Other windows expand to use up the space. The deleted window can never come back, but no actual text is thereby lost. See section O. Multiple Windows.

Directory
File directories are named collections in the file system, within which you can place individual files or subdirectories. See section M.8 File Directories.

Dired
Dired is the Emacs facility that displays the contents of a file directory and allows you to "edit the directory," performing operations on the files in the directory. See section AB. Dired, the Directory Editor.

Disabled Command
A disabled command is one that you may not run without special confirmation. The usual reason for disabling a command is that it is confusing for beginning users. See section AD.4.11 Disabling Commands.

Down Event
Short for `button down event' (q.v.).

Drag Event
A drag event is the kind of input event generated when you press a mouse button, move the mouse, and then release the button. See section AD.4.10 Rebinding Mouse Buttons.

Dribble File
A dribble file is a file into which Emacs writes all the characters that the user types on the keyboard. Dribble files are used to make a record for debugging Emacs bugs. Emacs does not make a dribble file unless you tell it to. See section AD.10 Reporting Bugs.

Echo Area
The echo area is the bottom line of the screen, used for echoing the arguments to commands, for asking questions, and showing brief messages (including error messages). The messages are stored in the buffer `*Messages*' so you can review them later. See section B.2 The Echo Area.

Echoing
Echoing is acknowledging the receipt of commands by displaying them (in the echo area). Emacs never echoes single-character key sequences; longer key sequences echo only if you pause while typing them.

Electric
We say that a character is electric if it is normally self-inserting (q.v.), but the current major mode (q.v.) redefines it to do something else as well. For example, some programming language major modes define particular delimiter characters to reindent the line or insert one or more newlines in addition to self-insertion.

End Of Line
End of line is a character or a sequence of characters that indicate the end of a text line. On GNU and Unix systems, this is a newline (q.v.), but other systems have other conventions. See section end-of-line. Emacs can recognize several end-of-line conventions in files and convert between them.

Environment Variable
An environment variable is one of a collection of variables stored by the operating system, each one having a name and a value. Emacs can access environment variables set by its parent shell, and it can set variables in the environment it passes to programs it invokes. See section AE.5 Environment Variables.

EOL
See `end of line.'

Error
An error occurs when an Emacs command cannot execute in the current circumstances. When an error occurs, execution of the command stops (unless the command has been programmed to do otherwise) and Emacs reports the error by displaying an error message (q.v.). Type-ahead is discarded. Then Emacs is ready to read another editing command.

Error Message
An error message is a single line of output displayed by Emacs when the user asks for something impossible to do (such as, killing text forward when point is at the end of the buffer). They appear in the echo area, accompanied by a beep.

ESC
ESC is a character used as a prefix for typing Meta characters on keyboards lacking a META key. Unlike the META key (which, like the SHIFT key, is held down while another character is typed), you press the ESC key as you would press a letter key, and it applies to the next character you type.

Expression
See `balanced expression.'

Expunging
Expunging an Rmail file or Dired buffer or a Gnus newsgroup buffer is an operation that truly discards the messages or files you have previously flagged for deletion.

Face
A face is a style of displaying characters. It specifies attributes such as font family and size, foreground and background colors, underline and strike-through, background stipple, etc. Emacs provides features to associate specific faces with portions of buffer text, in order to display that text as specified by the face attributes.

File Locking
Emacs uses file locking to notice when two different users start to edit one file at the same time. See section M.3.2 Protection against Simultaneous Editing.

File Name
A file name is a name that refers to a file. File names may be relative or absolute; the meaning of a relative file name depends on the current directory, but an absolute file name refers to the same file regardless of which directory is current. On GNU and Unix systems, an absolute file name starts with a slash (the root directory) or with `~/' or `~user/' (a home directory). On MS-Windows/MS-DOS, and absolute file name can also start with a drive letter and a colon `d:'.
Some people use the term "pathname" for file names, but we do not; we use the word "path" only in the term "search path" (q.v.).

File-Name Component
A file-name component names a file directly within a particular directory. On GNU and Unix systems, a file name is a sequence of file-name components, separated by slashes. For example, `foo/bar' is a file name containing two components, `foo' and `bar'; it refers to the file named `bar' in the directory named `foo' in the current directory. MS-DOS/MS-Windows file names can also use backslashes to separate components, as in `foo\bar'.

Fill Prefix
The fill prefix is a string that should be expected at the beginning of each line when filling is done. It is not regarded as part of the text to be filled. See section T.5 Filling Text.

Filling
Filling text means shifting text between consecutive lines so that all the lines are approximately the same length. See section T.5 Filling Text. Some other editors call this feature `line wrapping.'

Font Lock
Font Lock is a mode that highlights parts of buffer text according to its syntax. See section J.2 Font Lock mode.

Fontset
A fontset is a named collection of fonts. A fontset specification lists character sets and which font to use to display each of them. Fontsets make it easy to change several fonts at once by specifying the name of a fontset, rather than changing each font separately. See section Q.10 Fontsets.

Formatted Text
Formatted text is text that displays with formatting information while you edit. Formatting information includes fonts, colors, and specified margins. See section T.11 Editing Formatted Text.

Formfeed Character
See `page.'

Frame
A frame is a rectangular cluster of Emacs windows. Emacs starts out with one frame, but you can create more. You can subdivide each frame into Emacs windows (q.v.). When you are using a windowing system, all the frames can be visible at the same time. See section P. Frames and X Windows. Some other editors use the term "window" for this, but in Emacs a window means something else.

Fringe
On windowed displays, there's a narrow portion of the frame (q.v.) between the text area and the window's border. Emacs displays the fringe using a special face (q.v.) called fringe. See section fringe.

FTP
FTP is an acronym for File Transfer Protocol. Emacs uses an FTP client program to provide access to remote files (q.v.).

Function Key
A function key is a key on the keyboard that sends input but does not correspond to any character. See section AD.4.7 Rebinding Function Keys.

Global
Global means "independent of the current environment; in effect throughout Emacs." It is the opposite of local (q.v.). Particular examples of the use of `global' appear below.

Global Abbrev
A global definition of an abbrev (q.v.) is effective in all major modes that do not have local (q.v.) definitions for the same abbrev. See section X. Abbrevs.

Global Keymap
The global keymap (q.v.) contains key bindings that are in effect except when overridden by local key bindings in a major mode's local keymap (q.v.). See section AD.4.1 Keymaps.

Global Mark Ring
The global mark ring records the series of buffers you have recently set a mark (q.v.) in. In many cases you can use this to backtrack through buffers you have been editing in, or in which you have found tags (see `tags table'). See section H.6 The Global Mark Ring.

Global Substitution
Global substitution means replacing each occurrence of one string by another string throughout a large amount of text. See section K.7 Replacement Commands.

Global Variable
The global value of a variable (q.v.) takes effect in all buffers that do not have their own local (q.v.) values for the variable. See section AD.2 Variables.

Graphic Character
Graphic characters are those assigned pictorial images rather than just names. All the non-Meta (q.v.) characters except for the Control (q.v.) characters are graphic characters. These include letters, digits, punctuation, and spaces; they do not include RET or ESC. In Emacs, typing a graphic character inserts that character (in ordinary editing modes). See section Basic Editing.

Highlighting
Highlighting text means displaying it with a different foreground and/or background color to make it stand out from the rest of the text in the buffer.

Hardcopy
Hardcopy means printed output. Emacs has commands for making printed listings of text in Emacs buffers. See section AC.18 Hardcopy Output.

HELP
HELP is the Emacs name for C-h or F1. You can type HELP at any time to ask what options you have, or to ask what any command does. See section G. Help.

Help Echo
Help echo is a short message displayed in the echo area when the mouse pointer is located on portions of display that require some explanations. Emacs displays help echo for menu items, parts of the mode line, tool-bar buttons, etc. On graphics displays, the messages can be displayed as tooltips (q.v.). See section P.18 Tooltips (or "Balloon Help").

Hook
A hook is a list of functions to be called on specific occasions, such as saving a buffer in a file, major mode activation, etc. By customizing the various hooks, you can modify Emacs's behavior without changing any of its code. See section AD.2.3 Hooks.

Hyper
Hyper is the name of a modifier bit which a keyboard input character may have. To make a character Hyper, type it while holding down the HYPER key. Such characters are given names that start with Hyper- (usually written H- for short). See section Hyper.

Inbox
An inbox is a file in which mail is delivered by the operating system. Rmail transfers mail from inboxes to Rmail files (q.v.) in which the mail is then stored permanently or until explicitly deleted. See section AA.5 Rmail Files and Inboxes.

Incremental Search
Emacs provides an incremental search facility, whereby Emacs searches for the string as you type it. See section K.1 Incremental Search.

Indentation
Indentation means blank space at the beginning of a line. Most programming languages have conventions for using indentation to illuminate the structure of the program, and Emacs has special commands to adjust indentation. See section S. Indentation.

Indirect Buffer
An indirect buffer is a buffer that shares the text of another buffer, called its base buffer (q.v.). See section N.6 Indirect Buffers.

Info
Info is the hypertext format used by the GNU project for writing documentation.

Input Event
An input event represents, within Emacs, one action taken by the user on the terminal. Input events include typing characters, typing function keys, pressing or releasing mouse buttons, and switching between Emacs frames. See section B.5 Kinds of User Input.

Input Method
An input method is a system for entering non-ASCII text characters by typing sequences of ASCII characters (q.v.). See section Q.4 Input Methods.

Insertion
Insertion means copying text into the buffer, either from the keyboard or from some other place in Emacs.

Interlocking
Interlocking is a feature for warning when you start to alter a file that someone else is already editing. See section Simultaneous Editing.

Isearch
See `incremental search.'

Justification
Justification means adding extra spaces within lines of text to make them extend exactly to a specified width. See section Justification.

Keyboard Macro
Keyboard macros are a way of defining new Emacs commands from sequences of existing ones, with no need to write a Lisp program. See section AD.3 Keyboard Macros.

Keyboard Shortcut
A keyboard shortcut is a key sequence (q.v.) which invokes a command. What other programs call "assign a keyboard shortcut" Emacs calls "bind a key sequence". See `binding.'

Key Sequence
A key sequence (key, for short) is a sequence of input events (q.v.) that are meaningful as a single unit. If the key sequence is enough to specify one action, it is a complete key (q.v.); if it is not enough, it is a prefix key (q.v.). See section B.6 Keys.

Keymap
The keymap is the data structure that records the bindings (q.v.) of key sequences to the commands that they run. For example, the global keymap binds the character C-n to the command function next-line. See section AD.4.1 Keymaps.

Keyboard Translation Table
The keyboard translation table is an array that translates the character codes that come from the terminal into the character codes that make up key sequences. See section AD.5 Keyboard Translations.

Kill Ring
The kill ring is where all text you have killed recently is saved. You can reinsert any of the killed text still in the ring; this is called yanking (q.v.). See section H.8 Yanking.

Killing
Killing means erasing text and saving it on the kill ring so it can be yanked (q.v.) later. Some other systems call this "cutting." Most Emacs commands that erase text perform killing, as opposed to deletion (q.v.). See section H.7 Deletion and Killing.

Killing a Job
Killing a job (such as, an invocation of Emacs) means making it cease to exist. Any data within it, if not saved in a file, is lost. See section C.1 Exiting Emacs.

Language Environment
Your choice of language environment specifies defaults for the input method (q.v.) and coding system (q.v.). See section Q.3 Language Environments. These defaults are relevant if you edit non-ASCII text (see section Q. International Character Set Support).

Line Wrapping
See `filling.'

Lisp
Lisp is a programming language. Most of Emacs is written in a dialect of Lisp, called Emacs Lisp, that is extended with special features which make it especially suitable for text editing tasks.

List
A list is, approximately, a text string beginning with an open parenthesis and ending with the matching close parenthesis. In C mode and other non-Lisp modes, groupings surrounded by other kinds of matched delimiters appropriate to the language, such as braces, are also considered lists. Emacs has special commands for many operations on lists. See section U.4.2 Moving in the Parenthesis Structure.

Local
Local means "in effect only in a particular context"; the relevant kind of context is a particular function execution, a particular buffer, or a particular major mode. It is the opposite of `global' (q.v.). Specific uses of `local' in Emacs terminology appear below.

Local Abbrev
A local abbrev definition is effective only if a particular major mode is selected. In that major mode, it overrides any global definition for the same abbrev. See section X. Abbrevs.

Local Keymap
A local keymap is used in a particular major mode; the key bindings (q.v.) in the current local keymap override global bindings of the same key sequences. See section AD.4.1 Keymaps.

Local Variable
A local value of a variable (q.v.) applies to only one buffer. See section AD.2.4 Local Variables.

M-
M- in the name of a character is an abbreviation for META, one of the modifier keys that can accompany any character. See section B.5 Kinds of User Input.

M-C-
M-C- in the name of a character is an abbreviation for Control-Meta; it means the same thing as C-M-. If your terminal lacks a real META key, you type a Control-Meta character by typing ESC and then typing the corresponding Control character. See section C-M-.

M-x
M-x is the key sequence which is used to call an Emacs command by name. This is how you run commands that are not bound to key sequences. See section Running Commands by Name.

Mail
Mail means messages sent from one user to another through the computer system, to be read at the recipient's convenience. Emacs has commands for composing and sending mail, and for reading and editing the mail you have received. See section Z. Sending Mail. See section AA. Reading Mail with Rmail, for how to read mail.

Mail Composition Method
A mail composition method is a program runnable within Emacs for editing and sending a mail message. Emacs lets you select from several alternative mail composition methods. See section Z.6 Mail-Composition Methods.

Major Mode
The Emacs major modes are a mutually exclusive set of options, each of which configures Emacs for editing a certain sort of text. Ideally, each programming language has its own major mode. See section R. Major Modes.

Mark
The mark points to a position in the text. It specifies one end of the region (q.v.), point being the other end. Many commands operate on all the text from point to the mark. Each buffer has its own mark. See section H. The Mark and the Region.

Mark Ring
The mark ring is used to hold several recent previous locations of the mark, just in case you want to move back to them. Each buffer has its own mark ring; in addition, there is a single global mark ring (q.v.). See section H.5 The Mark Ring.

Menu Bar
The menu bar is the line at the top of an Emacs frame. It contains words you can click on with the mouse to bring up menus, or you can use a keyboard interface to navigate it. See section P.15 Menu Bars.

Message
See `mail.'

Meta
Meta is the name of a modifier bit which a command character may have. It is present in a character if the character is typed with the META key held down. Such characters are given names that start with Meta- (usually written M- for short). For example, M-< is typed by holding down META and at the same time typing < (which itself is done, on most terminals, by holding down SHIFT and typing ,). See section Meta.

Meta Character
A Meta character is one whose character code includes the Meta bit.

Minibuffer
The minibuffer is the window that appears when necessary inside the echo area (q.v.), used for reading arguments to commands. See section E. The Minibuffer.

Minibuffer History
The minibuffer history records the text you have specified in the past for minibuffer arguments, so you can conveniently use the same text again. See section E.4 Minibuffer History.

Minor Mode
A minor mode is an optional feature of Emacs which can be switched on or off independently of all other features. Each minor mode has a command to turn it on or off. See section AD.1 Minor Modes.

Minor Mode Keymap
A minor mode keymap is a keymap that belongs to a minor mode and is active when that mode is enabled. Minor mode keymaps take precedence over the buffer's local keymap, just as the local keymap takes precedence over the global keymap. See section AD.4.1 Keymaps.

Mode Line
The mode line is the line at the bottom of each window (q.v.), giving status information on the buffer displayed in that window. See section B.3 The Mode Line.

Modified Buffer
A buffer (q.v.) is modified if its text has been changed since the last time the buffer was saved (or since when it was created, if it has never been saved). See section M.3 Saving Files.

Moving Text
Moving text means erasing it from one place and inserting it in another. The usual way to move text by killing (q.v.) and then yanking (q.v.). See section H.7 Deletion and Killing.

MULE
MULE refers to the Emacs features for editing multilingual non-ASCII text using multibyte characters (q.v.). See section Q. International Character Set Support.

Multibyte Character
A multibyte character is a character that takes up several bytes in a buffer. Emacs uses multibyte characters to represent non-ASCII text, since the number of non-ASCII characters is much more than 256. See section International Characters.

Named Mark
A named mark is a register (q.v.) in its role of recording a location in text so that you can move point to that location. See section I. Registers.

Narrowing
Narrowing means creating a restriction (q.v.) that limits editing in the current buffer to only a part of the text in the buffer. Text outside that part is inaccessible to the user until the boundaries are widened again, but it is still there, and saving the file saves it all. See section AC.22 Narrowing.

Newline
Control-J characters in the buffer terminate lines of text and are therefore also called newlines. See section Newline.

nil
nil is a value usually interpreted as a logical "false." Its opposite is t, interpreted as "true."

Numeric Argument
A numeric argument is a number, specified before a command, to change the effect of the command. Often the numeric argument serves as a repeat count. See section D.10 Numeric Arguments.

Overwrite Mode
Overwrite mode is a minor mode. When it is enabled, ordinary text characters replace the existing text after point rather than pushing it to the right. See section AD.1 Minor Modes.

Page
A page is a unit of text, delimited by formfeed characters (ASCII control-L, code 014) coming at the beginning of a line. Some Emacs commands are provided for moving over and operating on pages. See section T.4 Pages.

Paragraph
Paragraphs are the medium-size unit of human-language text. There are special Emacs commands for moving over and operating on paragraphs. See section T.3 Paragraphs.

Parsing
We say that certain Emacs commands parse words or expressions in the text being edited. Really, all they know how to do is find the other end of a word or expression. See section AD.6 The Syntax Table.

Point
Point is the place in the buffer at which insertion and deletion occur. Point is considered to be between two characters, not at one character. The terminal's cursor (q.v.) indicates the location of point. See section Basic Editing.
Prefix Argument
See `numeric argument.'

Prefix Key
A prefix key is a key sequence (q.v.) whose sole function is to introduce a set of longer key sequences. C-x is an example of prefix key; any two-character sequence starting with C-x is therefore a legitimate key sequence. See section B.6 Keys.

Primary Rmail File
Your primary Rmail file is the file named `RMAIL' in your home directory. That's where Rmail stores your incoming mail, unless you specify a different file name. See section AA. Reading Mail with Rmail.

Primary Selection
The primary selection is one particular X selection (q.v.); it is the selection that most X applications use for transferring text to and from other applications.
The Emacs kill commands set the primary selection and the yank command uses the primary selection when appropriate. See section H.7 Deletion and Killing.

Prompt
A prompt is text used to ask the user for input. Displaying a prompt is called prompting. Emacs prompts always appear in the echo area (q.v.). One kind of prompting happens when the minibuffer is used to read an argument (see section E. The Minibuffer); the echoing which happens when you pause in the middle of typing a multi-character key sequence is also a kind of prompting (see section B.2 The Echo Area).

Query-Replace
Query-replace is an interactive string replacement feature provided by Emacs. See section K.7.4 Query Replace.

Quitting
Quitting means canceling a partially typed command or a running command, using C-g (or C-BREAK on MS-DOS). See section AD.8 Quitting and Aborting.

Quoting
Quoting means depriving a character of its usual special significance. The most common kind of quoting in Emacs is with C-q. What constitutes special significance depends on the context and on convention. For example, an "ordinary" character as an Emacs command inserts itself; so in this context, a special character is any character that does not normally insert itself (such as DEL, for example), and quoting it makes it insert itself as if it were not special. Not all contexts allow quoting. See section Basic Editing.

Quoting File Names
Quoting a file name turns off the special significance of constructs such as `$', `~' and `:'. See section M.14 Quoted File Names.

Read-Only Buffer
A read-only buffer is one whose text you are not allowed to change. Normally Emacs makes buffers read-only when they contain text which has a special significance to Emacs; for example, Dired buffers. Visiting a file that is write-protected also makes a read-only buffer. See section N. Using Multiple Buffers.

Rectangle
A rectangle consists of the text in a given range of columns on a given range of lines. Normally you specify a rectangle by putting point at one corner and putting the mark at the diagonally opposite corner. See section H.10 Rectangles.

Recursive Editing Level
A recursive editing level is a state in which part of the execution of a command involves asking the user to edit some text. This text may or may not be the same as the text to which the command was applied. The mode line indicates recursive editing levels with square brackets (`[' and `]'). See section AC.26 Recursive Editing Levels.

Redisplay
Redisplay is the process of correcting the image on the screen to correspond to changes that have been made in the text being edited. See section Redisplay.

Regexp
See `regular expression.'

Region
The region is the text between point (q.v.) and the mark (q.v.). Many commands operate on the text of the region. See section Region.

Registers
Registers are named slots in which text or buffer positions or rectangles can be saved for later use. See section I. Registers. A related Emacs feature is `bookmarks' (q.v.).

Regular Expression
A regular expression is a pattern that can match various text strings; for example, `a[0-9]+' matches `a' followed by one or more digits. See section K.5 Syntax of Regular Expressions.

Remote File
A remote file is a file that is stored on a system other than your own. Emacs can access files on other computers provided that they are connected to the same network as your machine, and (obviously) that you have a supported method to gain access to those files. See section M.13 Remote Files.

Repeat Count
See `numeric argument.'

Replacement
See `global substitution.'

Restriction
A buffer's restriction is the amount of text, at the beginning or the end of the buffer, that is temporarily inaccessible. Giving a buffer a nonzero amount of restriction is called narrowing (q.v.); removing a restriction is called widening (q.v.). See section AC.22 Narrowing.

RET
RET is a character that in Emacs runs the command to insert a newline into the text. It is also used to terminate most arguments read in the minibuffer (q.v.). See section Return.

Reverting
Reverting means returning to the original state. Emacs lets you revert a buffer by re-reading its file from disk. See section M.4 Reverting a Buffer.

Rmail File
An Rmail file is a file containing text in a special format used by Rmail for storing mail. See section AA. Reading Mail with Rmail.

Saving
Saving a buffer means copying its text into the file that was visited (q.v.) in that buffer. This is the way text in files actually gets changed by your Emacs editing. See section M.3 Saving Files.

Scroll Bar
A scroll bar is a tall thin hollow box that appears at the side of a window. You can use mouse commands in the scroll bar to scroll the window. The scroll bar feature is supported only under windowing systems. See section P.13 Scroll Bars.

Scrolling
Scrolling means shifting the text in the Emacs window so as to see a different part of the buffer. See section Scrolling.

Searching
Searching means moving point to the next occurrence of a specified string or the next match for a specified regular expression. See section K. Searching and Replacement.

Search Path
A search path is a list of directory names, to be used for searching for files for certain purposes. For example, the variable load-path holds a search path for finding Lisp library files. See section V.7 Libraries of Lisp Code for Emacs.

Secondary Selection
The secondary selection is one particular X selection; some X applications can use it for transferring text to and from other applications. Emacs has special mouse commands for transferring text using the secondary selection. See section P.2 Secondary Selection.

Selecting
Selecting a buffer means making it the current (q.v.) buffer. See section Selecting.

Selection
Windowing systems allow an application program to specify selections whose values are text. A program can also read the selections that other programs have set up. This is the principal way of transferring text between window applications. Emacs has commands to work with the primary (q.v.) selection and the secondary (q.v.) selection, and also with the clipboard (q.v.).

Self-Documentation
Self-documentation is the feature of Emacs which can tell you what any command does, or give you a list of all commands related to a topic you specify. You ask for self-documentation with the help character, C-h. See section G. Help.

Self-Inserting Character
A character is self-inserting if typing that character inserts that character in the buffer. Ordinary printing and whitespace characters are self-inserting in Emacs, except in certain special major modes.

Sentences
Emacs has commands for moving by or killing by sentences. See section T.2 Sentences.

Sexp
A sexp (short for "s-expression") is the basic syntactic unit of Lisp in its textual form: either a list, or Lisp atom. Sexps are also the balanced expressions (q.v.) of the Lisp language; this is why the commands for editing balanced expressions have `sexp' in their name. See section Sexps.

Simultaneous Editing
Simultaneous editing means two users modifying the same file at once. Simultaneous editing, if not detected, can cause one user to lose his or her work. Emacs detects all cases of simultaneous editing, and warns one of the users to investigate. See section Simultaneous Editing.

Speedbar
Speedbar is a special tall frame that provides fast access to Emacs buffers, functions within those buffers, Info nodes, and other interesting parts of text within Emacs. See section P.9 Making and Using a Speedbar Frame.

Spell Checking
Spell checking means checking correctness of the written form of each one of the words in a text. Emacs uses the Ispell spelling-checker program to check the spelling of parts of a buffer via a convenient user interface. See section L.4 Checking and Correcting Spelling.

String
A string is a kind of Lisp data object which contains a sequence of characters. Many Emacs variables are intended to have strings as values. The Lisp syntax for a string consists of the characters in the string with a `"' before and another `"' after. A `"' that is part of the string must be written as `\"' and a `\' that is part of the string must be written as `\\'. All other characters, including newline, can be included just by writing them inside the string; however, backslash sequences as in C, such as `\n' for newline or `\241' using an octal character code, are allowed as well.

String Substitution
See `global substitution'.

Syntax Highlighting
See `font lock.'

Syntax Table
The syntax table tells Emacs which characters are part of a word, which characters balance each other like parentheses, etc. See section AD.6 The Syntax Table.

Super
Super is the name of a modifier bit which a keyboard input character may have. To make a character Super, type it while holding down the SUPER key. Such characters are given names that start with Super- (usually written s- for short). See section Super.

Suspending
Suspending Emacs means stopping it temporarily and returning control to its parent process, which is usually a shell. Unlike killing a job (q.v.), you can later resume the suspended Emacs job without losing your buffers, unsaved edits, undo history, etc. See section C.1 Exiting Emacs.

Tags Table
A tags table is a file that serves as an index to the function definitions in one or more other files. See section W.2 Tags Tables.

Termscript File
A termscript file contains a record of all characters sent by Emacs to the terminal. It is used for tracking down bugs in Emacs redisplay. Emacs does not make a termscript file unless you tell it to. See section AD.10 Reporting Bugs.

Text
`Text' has two meanings (see section T. Commands for Human Languages):

Data consisting of a sequence of characters, as opposed to binary numbers, executable programs, and the like. The basic contents of an Emacs buffer (aside from the text properties, q.v.) are always text in this sense.
Data consisting of written human language, as opposed to programs, or following the stylistic conventions of human language.

Text-only Terminal
A text-only terminal is a display that is limited to displaying text in character units. Such a terminal cannot control individual pixels it displays. Emacs supports a subset of display features on text-only terminals.

Text Properties
Text properties are annotations recorded for particular characters in the buffer. Images in the buffer are recorded as text properties; they also specify formatting information. See section T.11.3 Editing Format Information.

Tool Bar
The tool bar is a line (sometimes multiple lines) of icons at the top of an Emacs frame. Clicking on one of these icons executes a command. You can think of this as a graphical relative of the menu bar (q.v.). See section P.16 Tool Bars.

Tooltips
Tooltips are small windows displaying a help echo (q.v.) text that explains parts of the display, lists useful options available via mouse clicks, etc. See section P.18 Tooltips (or "Balloon Help").

Top Level
Top level is the normal state of Emacs, in which you are editing the text of the file you have visited. You are at top level whenever you are not in a recursive editing level (q.v.) or the minibuffer (q.v.), and not in the middle of a command. You can get back to top level by aborting (q.v.) and quitting (q.v.). See section AD.8 Quitting and Aborting.

Transposition
Transposing two units of text means putting each one into the place formerly occupied by the other. There are Emacs commands to transpose two adjacent characters, words, balanced expressions (q.v.) or lines (see section L.2 Transposing Text).

Truncation
Truncating text lines in the display means leaving out any text on a line that does not fit within the right margin of the window displaying it. See also `continuation line.' See section Basic Editing.

TTY
See `text-only terminal.'

Undoing
Undoing means making your previous editing go in reverse, bringing back the text that existed earlier in the editing session. See section D.4 Undoing Changes.

User Option
A user option is a variable (q.v.) that exists so that you can customize Emacs by setting it to a new value. See section AD.2 Variables.

Variable
A variable is an object in Lisp that can store an arbitrary value. Emacs uses some variables for internal purposes, and has others (known as `user options' (q.v.)) just so that you can set their values to control the behavior of Emacs. The variables used in Emacs that you are likely to be interested in are listed in the Variables Index in this manual (see section Variable Index). See section AD.2 Variables, for information on variables.

Version Control
Version control systems keep track of multiple versions of a source file. They provide a more powerful alternative to keeping backup files (q.v.). See section M.7 Version Control.

Visiting
Visiting a file means loading its contents into a buffer (q.v.) where they can be edited. See section M.2 Visiting Files.

Whitespace
Whitespace is any run of consecutive formatting characters (space, tab, newline, and backspace).

Widening
Widening is removing any restriction (q.v.) on the current buffer; it is the opposite of narrowing (q.v.). See section AC.22 Narrowing.

Window
Emacs divides a frame (q.v.) into one or more windows, each of which can display the contents of one buffer (q.v.) at any time. See section B. The Organization of the Screen, for basic information on how Emacs uses the screen. See section O. Multiple Windows, for commands to control the use of windows. Some other editors use the term "window" for what we call a `frame' (q.v.) in Emacs.

Word Abbrev
See `abbrev.'

Word Search
Word search is searching for a sequence of words, considering the punctuation between them as insignificant. See section K.3 Word Search.

WYSIWYG
WYSIWYG stands for "What you see is what you get." Emacs generally provides WYSIWYG editing for files of characters; in Enriched mode (see section T.11 Editing Formatted Text), it provides WYSIWYG editing for files that include text formatting information.

Yanking
Yanking means reinserting text previously killed. It can be used to undo a mistaken kill, or for copying or moving text. Some other systems call this "pasting." See section H.8 Yanking.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

AI. Acknowledgments

Many people have contributed code included in the Free Software Foundation's distribution of GNU Emacs. To show our appreciation for their public spirit, we list here in alphabetical order those who have written substantial portions.

Per Abrahamsen wrote the customization buffer facilities, as well as `double.el' for typing accented characters not normally available from the keyboard, `xt-mouse.el' which handles mouse commands through Xterm, `gnus-cus.el' which implements customization commands for Gnus, `gnus-cite.el', a citation-parsing facility for news articles and `cpp.el' which hides or highlights parts of C programs according to preprocessor conditionals.

Tomas Abrahamsson wrote `artist.el', a package for producing ASCII art with a mouse or with keyboard keys.

Jay K. Adams wrote `jka-compr.el', providing automatic decompression and recompression for compressed files.

Joe Arceneaux wrote the original text property implementation, and implemented support for X11.

Miles Bader wrote `image-file.el', support code for visiting image files; and `minibuf-eldef.el', a minor mode whereby the default value is shown in the minibuffer prompt only when appropriate.

David Bakhash wrote `strokes.el', a mode for controlling Emacs by moving the mouse in particular patterns.

Eli Barzilay wrote `calculator.el', a desktop calculator for Emacs.

Steven L. Baur wrote `footnote.el' which lets you include footnotes in email messages, and `gnus-audio.el' which provides sound effects for Gnus.

Boaz Ben-Zvi wrote `profile.el', to time Emacs Lisp functions.

Ray Blaak wrote `delphi.el', a major mode for editing Delphi (Object Pascal) source code.

Jim Blandy wrote Emacs 19's input system, brought its configuration and build process up to the GNU coding standards, and contributed to the frame support and multi-face support. Jim also wrote `tvi970.el', terminal support for the TeleVideo 970 terminals.

Per Bothner wrote `term.el', a terminal emulator in an Emacs buffer.

Terrence M. Brannon wrote `landmark.el', a neural-network robot that learns landmarks.

Frank Bresz wrote `diff.el', a program to display diff output.

Peter Breton implemented:

`dirtrack' which does better tracking of directory changes in shell buffers,
`filecache.el' which records which directories your files are in,
`locate.el' which interfaces to the locate command,
`find-lisp.el', an Emacs Lisp emulation of the find program,
`net-utils.el', and
the "generic mode" feature.

Emmanuel Briot wrote `xml.el', an XML parser for Emacs.

Kevin Broadey wrote `foldout.el', providing folding extensions to Emacs's outline modes.

David M. Brown wrote `array.el', for editing arrays and other tabular data.

W/lodek Bzyl and Ryszard Kubiak wrote `ogonek.el', a package for changing the encoding of Polish characters.

Bill Carpenter provided `feedmail.el', a package for massaging outgoing mail messages and sending them through various popular mailers.

Per Cederqvist and Inge Wallin wrote `ewoc.el', an Emacs widget for manipulating object collections.

Hans Chalupsky wrote `advice.el', an overloading mechanism for Emacs Lisp functions, and `trace.el', a tracing facility for Emacs Lisp.

Chris Chase and Carsten Dominik wrote `idlwave.el', an editing mode for IDL and WAVE CL.

Bob Chassell wrote `texnfo-upd.el' and `makeinfo.el', modes and utilities for working with Texinfo files; and `page-ext.el', commands for extended page handling.

Andrew Choi wrote the Macintosh support code, and contributed `mac-win.el', support for the Mac window system.

James Clark wrote `sgml-mode.el', a mode for editing SGML documents, and contributed to Emacs's dumping procedures.

Mike Clarkson wrote `edt.el', an emulation of DEC's EDT editor.

Glynn Clements provided `gamegrid.el' and a couple of games that use it, Snake and Tetris.

Georges Brun-Cottan and Stefan Monnier wrote `easy-mmode.el', a package for easy definition of major and minor modes.

Andrew Csillag wrote M4 mode (`m4-mode.el').

Doug Cutting and Jamie Zawinski wrote `disass.el', a disassembler for compiled Emacs Lisp code.

Michael DeCorte wrote `emacs.csh', a C-shell script that starts a new Emacs job, or restarts a paused Emacs if one exists.

Gary Delp wrote `mailpost.el', an interface between RMAIL and the `/usr/uci/post' mailer.

Matthieu Devin wrote `delsel.el', a package to make newly-typed text replace the current selection.

Eric Ding contributed `goto-addr.el',

Carsten Dominik wrote `reftex.el', a package for setting up labels and cross-references in LaTeX documents.

Scott Draves wrote `tq.el', help functions for maintaining transaction queues between Emacs and its subprocesses.

Benjamin Drieu wrote `pong.el', an implementation of the classical pong game.

Viktor Dukhovni wrote support for dumping under SunOS version 4.

John Eaton co-wrote Octave mode (`octave.el' and related files).

Rolf Ebert co-wrote Ada mode (`ada-mode.el').

Stephen Eglen implemented `mspools.el', for use with Procmail, which tells you which mail folders have mail waiting in them, and `iswitchb.el', a feature for incremental reading and completion of buffer names.

Torbjörn Einarsson contributed the Fortran 90 mode (`f90.el').

Tsugutomo Enami co-wrote the support for international character sets.

Hans Henrik Eriksen wrote `simula.el', a mode for editing SIMULA 87 code.

Michael Ernst wrote `reposition.el', a command for recentering a function's source code and preceding comment on the screen.

Ata Etemadi wrote `cdl.el', functions for working with Common Data Language source code.

Frederick Farnbach implemented `morse.el', which converts text to Morse code.

Oscar Figueiredo wrote EUDC, the Emacs Unified Directory Client, which is an interface to directory servers via LDAP, CCSO PH/QI, or BBDB; and `ldap.el', the LDAP client interface.

Fred Fish wrote the support for dumping COFF executable files.

Karl Fogel wrote:

`bookmark.el', for creating named placeholders, saving them and jumping to them later,
`mail-hist.el', a history mechanism for outgoing mail messages, and
`saveplace.el', for preserving point's location in files between editing sessions.

Gary Foster wrote `crisp.el', the emulation for CRiSP and Brief editors, and `scroll-lock.el' (now `scroll-all.el') a mode for scrolling several buffers together.

Noah Friedman wrote `rlogin.el', an interface to Rlogin, `type-break.el', which reminds you to take periodic breaks from typing, and eldoc-mode, a mode to show the defined parameters or the doc string for the Lisp function near point. With Roland McGrath, he wrote `rsz-mini.el', a minor mode to automatically resize the minibuffer to fit the text it contains.

Keith Gabryelski wrote `hexl.el', a mode for editing binary files.

Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote `flow-ctrl.el', a package for coping with unsuppressible XON/XOFF flow control.

Kevin Gallo added multiple-frame support for Windows NT and wrote `w32-win.el', support functions for the MS-Windows window system.

Howard Gayle wrote:

the C and lisp code for display tables and case tables,
`rot13.el', a command to display the plain-text form of a buffer encoded with the Caesar cipher,
`case-table.el', code to extend the character set and support case tables,
much of the support for the ISO-8859 European character sets (which includes `iso-ascii.el', `iso-insert.el', `iso-swed.el', `latin-1.el', `iso-syntax.el', `iso-transl.el', `swedish.el'), and
`vt100-led.el', a package for controlling the LED's on VT100-compatible terminals.

Stephen Gildea made the Emacs quick reference card, and made many contributions for `time-stamp.el', a package for maintaining last-change time stamps in files.

Julien Gilles wrote `gnus-ml.el', a mailing list minor mode for Gnus.

David Gillespie wrote:

Emacs 19's Common Lisp compatibility packages, replacing the old package by Cesar Augusto Quiroz Gonzalez,
`complete.el', a partial completion mechanism, and
`edmacro.el', a package for editing keyboard macros.

Bob Glickstein contributed the `sregex.el' feature, a facility for writing regexps using a Lisp-like syntax.

Boris Goldowsky wrote:

`avoid.el', a package to keep the mouse cursor out of the way of the text cursor,
`shadowfile.el', a package for keeping identical copies of files in more than one place,
`format.el', a package for reading and writing files in various formats,
`enriched.el', a package for saving text properties in files, and
`facemenu.el', a package for specifying faces.

Michelangelo Grigni wrote `ffap.el' which visits a file, taking the file name from the buffer.

Odd Gripenstam wrote `dcl-mode.el' for editing DCL command files.

Michael Gschwind wrote `iso-cvt.el', a package to convert between the ISO 8859-1 character set and the notations for non-ASCII characters used by TeX and net tradition, and `latin-2.el', code which sets up case-conversion and syntax tables for the ISO Latin-2 character set.

Henry Guillaume wrote `find-file.el', a package to visit files related to the currently visited file.

Doug Gwyn wrote the portable alloca implementation.

Ken'ichi Handa implemented most of the support for international character sets, and wrote `isearch-x.el', a facility for searching non-ASCII text. Together with Naoto Takahashi, he wrote `quail.el', a simple input facility for typing non-ASCII text from an ASCII keyboard. Ken'ichi also wrote `ps-bdf.el', a BDF font support for printing non-ASCII text on a PostScript printer.

Chris Hanson wrote `netuname.el', a package to use HP-UX's Remote File Access facility from Emacs.

K. Shane Hartman wrote:

`chistory.el' and `echistory.el', packages for browsing command history lists,
`electric.el' and `helper.el', providing an alternative command loop and appropriate help facilities,
`emacsbug.el', a package for reporting Emacs bugs,
`picture.el', a mode for editing ASCII pictures, and
`view.el', a package for perusing files and buffers without editing them.

John Heidemann wrote `mouse-copy.el' and `mouse-drag.el', which provide alternative mouse-based editing and scrolling features. He also contributed `zone-mode.el', a major mode for editing DNS zone files.

Jon K Hellan wrote `utf7.el', support for mail-safe transformation format of Unicode.

Markus Heritsch co-wrote Ada mode (`ada-mode.el').

Karl Heuer wrote the original blessmail script, implemented the intangible text property, and rearranged the structure of the Lisp_Object type to allow for more data bits.

Manabu Higashida ported Emacs to MS-DOS.

Anders Holst wrote `hippie-exp.el', a versatile completion and expansion package.

Kurt Hornik co-wrote Octave mode (`octave.el' and related files).

Tom Houlder wrote `mantemp.el', which generates manual C++ template instantiations.

Denis Howe wrote `browse-url.el', a package for invoking a WWW browser to display a URL.

Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and wrote many of its parts.

Andrew Innes contributed extensively to the MS-Windows support.

Seiichiro Inoue improved Emacs's XIM support.

Kyle Jones wrote `life.el', a package to play Conway's "life" game, and `mldrag.el', a package which allows the user to resize windows by dragging mode lines and vertical window separators with the mouse.

Terry Jones wrote `shadow.el', a package for finding potential load-path problems when some Lisp file "shadows" another.

Simon Josefsson wrote `flow-fill.el', a package for interpreting RFC2646 formatted text in messages, `imap.el', an Emacs Lips library for talking to IMAP servers, `nnimap', the IMAP back-end for Gnus, nd `rfc2104.el', a hashed message authentication facility.

Tomoji Kagatani implemented `smtpmail.el', used for sending out mail with SMTP.

David Kaufman wrote `yow.c', an essential utility program for the hopelessly pinheaded.

Henry Kautz wrote `bib-mode.el', a mode for maintaining bibliography databases compatible with refer (the troff version) and lookbib, and `refbib.el', a package to convert those databases to the format used by the LaTeX text formatting package.

Howard Kaye wrote `sort.el', commands to sort text in Emacs buffers.

Michael Kifer wrote `ediff.el', an interactive interface to the diff, patch, and merge programs, and Viper, the newest emulation for VI.

Richard King wrote the first version of `userlock.el' and `filelock.c', which provide simple support for multiple users editing the same file. He also wrote the initial version of `uniquify.el', a facility to make buffer names unique by adding parts of the file's name to the buffer name.

Peter Kleiweg wrote `ps-mode.el', a major mode for editing PostScript files and running a PostScript interpreter interactively from within Emacs.

Larry K. Kolodney wrote `cvtmail.c', a program to convert the mail directories used by Gosling Emacs into RMAIL format.

David M. Koppelman wrote `hi-lock.el', a minor mode for interactive automatic highlighting of parts of the buffer text.

Robert Krawitz wrote the original `xmenu.c', part of Emacs's pop-up menu support.

Sebastian Kremer wrote Emacs 19's dired-mode, with contributions by Lawrence R. Dodd. He also wrote `ls-lisp.el', a Lisp emulation of the ls command for platforms which don't have ls as a standard program.

Geoff Kuenning wrote Emacs 19's `ispell.el', based on work by Ken Stevens and others.

David Ka*gedal wrote `tempo.el', providing support for easy insertion of boilerplate text and other common constructions.

Daniel LaLiberte wrote:

`edebug.el', a source-level debugger for Emacs Lisp,
`cl-specs.el', specifications to help edebug debug code written using David Gillespie's Common Lisp support,
`cust-print.el', a customizable package for printing lisp objects,
`eval-reg.el', a re-implementation of eval-region in Emacs Lisp, and
`isearch.el', Emacs's incremental search minor mode.

James R. Larus wrote `mh-e.el', an interface to the MH mail system.

Vinicius Jose Latorre wrote:

ps-print, a package for pretty-printing Emacs buffers to PostScript printers,
`delim-col.el', a package to arrange text into columns,
`ebnf2ps.el', a package that translates EBNF grammar to a syntactic chart that can be printed to a PostScript printer.

Frederic Lepied contributed `expand.el', which uses the abbrev mechanism for inserting programming constructs.

Peter Liljenberg wrote `elint.el', a Lint-style code checker for Emacs Lisp programs.

Lars Lindberg wrote `msb.el', which provides more flexible menus for buffer selection, and rewrote `dabbrev.el'.

Anders Lindgren wrote `autorevert.el', a package for automatically reverting files visited by Emacs that were changed on disk; `cwarn.el', a package to highlight suspicious C and C++ constructs; and `follow.el', a minor mode to synchronize windows that show the same buffer.

Dave Love wrote:

autoarg-mode, a global minor mode whereby digit keys supply prefix arguments, and autoarg-kp-mode which redefines the keypad numeric keys to digit arguments,
`autoconf.el', a mode for editing Autoconf `configure.in' files,
`elide-head.el', a package for eliding boilerplate text, such as copyright notices, from file headers,
`hl-line.el', a package that provides a minor mode for highlighting the line in the current window on which point is,
`latin-8.el' and `latin-9.el', code which sets up case-conversion and syntax tables for the ISO Latin-8 and Latin-9 character sets,
`latin1-disp.el', a package that lets you display ISO 8859 characters on Latin-1 terminals by setting up appropriate display tables,
`refill.el', a mode for automatic paragraph refilling, akin to typical word processors,
`smiley-ems.el', a facility for displaying smiley faces, and
`tool-bar.el', a mode to control the display of the Emacs tool bar.

Eric Ludlam wrote the Speedbar package and `checkdoc.el', a package for checking doc strings in Emacs Lisp programs.

Christopher J. Madsen wrote `decipher.el', a package for cracking simple substitution ciphers.

Neil M. Mager wrote `appt.el', functions to notify users of their appointments. It finds appointments recorded in the diary files generated by Edward M. Reingold's calendar package.

Ken Manheimer wrote `allout.el', a mode for manipulating and formatting outlines, and `icomplete.el', which provides incremental completion feedback in the minibuffer.

Bill Mann wrote `perl-mode.el', a mode for editing Perl code.

Brian Marick and Daniel LaLiberte wrote `hideif.el', support for hiding selected code within C #ifdef clauses.

Simon Marshall wrote:

`fast-lock.el', which caches the face data computed by Font Lock mode,
`lazy-lock.el', which delays fontification in Font Lock mode until text is actually displayed, and
`regexp-opt.el', which generates a regular expression from a list of strings.

Simon also extended `comint.el', originally written by Olin Shivers.

Bengt Martensson, Mark Shapiro, Mike Newton, Aaron Larson, and Stefan Schoef, wrote `bibtex.el', a mode for editing BibTeX bibliography files.
Charlie Martin wrote `autoinsert.el', which provides automatic mode-sensitive insertion of text into new files.

Thomas May wrote `blackbox.el', a version of the traditional blackbox game.

Roland McGrath wrote:

`compile.el', a package for running compilations in a buffer, and then visiting the locations reported in error messages,
`etags.el', a package for jumping to function definitions and searching or replacing in all the files mentioned in a `TAGS' file,
`find-dired.el', for using dired commands on output from the find program, with Sebastian Kremer,
`map-ynp.el', a general purpose boolean question-asker,
`autoload.el', providing semi-automatic maintenance of autoload files, and
`upd-copyr.el', providing semi-automatic maintenance of copyright notices in source code.

David Megginson wrote `derived.el', which allows one to define new major modes by inheriting key bindings and commands from existing major modes.

Will Mengarini wrote `repeat.el', a command to repeat the preceding command with its arguments.

Wayne Mesard wrote `hscroll.el' which does horizontal scrolling automatically.

Brad Miller wrote `gnus-gl.el', a Gnus interface for GroupLens.

Richard Mlynarik wrote:

`cl-indent.el', a package for indenting Common Lisp code,
`ebuff-menu.el', an "electric" browser for buffer listings,
`ehelp.el', bindings for browsing help screens,
`rfc822.el', a parser for E-mail addresses in the RFC-822 format, used in mail messages and news articles,
`terminal.el', a terminal emulator for Emacs subprocesses, and
`yow.el', an essential utility (try M-x yow).

Gerd Moellmann wrote:

the new display engine for Emacs 21,
the asynchronous timers facility (`atimer.c'),
the ebrowse C++ browser,
`jit-lock.el', the Just-In-Time font-lock support mode,
`tooltip.el', a package for displaying tooltips, and
`authors.el' package for maintaining the `AUTHORS' files.

Gerd took over the Emacs maintenance as the head maintainer since the beginning of Emacs 21 development.

Stefan Monnier wrote:

PCL-CVS, a directory-level front end to the CVS version control system,
`smerge-mode.el', a minor mode for resolving diff3 conflicts, and
`diff-mode.el', a mode for viewing and editing context diffs.

Morioka Tomohiko wrote several packages for MIME support in Gnus and elsewhere.

Sen Nagata wrote `crm.el', a package for reading multiple strings with completion, and `rfc2368.el', support for mailto: URLs.

Erik Naggum wrote the time-conversion functions. He also wrote `disp-table.el', a package for dealing with display tables, `latin-4.el' and `latin-5.el', code which sets up case-conversion and syntax tables for the ISO Latin-4 and Latin-5 character sets, `mailheader.el', a pacakage for parsing email headers, and `parse-time.el', a package for parsing time strings.

Thomas Neumann and Eric Raymond wrote `makefile.el' (now `make-mode.el'), a mode for editing makefiles.

Thien-Thi Nguyen and Dan Nicolaescu wrote `hideshow.el', a minor mode for selectively displaying blocks of text.

Dan Nicolaescu wrote `romanian.el', support for editing Romanian text, and `iris-ansi.el', support for running Emacs on SGI's xwsh and winterm terminal emulators.

Jurgen Nickelsen wrote `ws-mode.el', providing WordStar emulation.

Jeff Norden wrote `kermit.el', a package to help the Kermit dialup communications program run comfortably in an Emacs shell buffer.

Andrew Norman wrote `ange-ftp.el', providing transparent FTP support.

Alexandre Oliva wrote `gnus-mlspl.el', a group params-based mail splitting mechanism.

David Pearson contributed `quickurl.el', a simple method of inserting a URL into the current buffer based on text at point; `5x5.el', a game to fill all squares on the field.

Jeff Peck wrote:

`emacstool.c', support for running Emacs under SunView/Sun Windows,
`sun.el', key bindings for sunterm keys,
`sun-curs.el', cursor definitions for Sun Windows, and
`sun-fns.el' and `sun-mouse.el', providing mouse support for Sun Windows.

Damon Anton Permezel wrote `hanoi.el', an animated demonstration of the "Towers of Hanoi" puzzle.

William M. Perry wrote `mailcap.el', a MIME media types configuration facility, and `mwheel.el', support for MS Intellimouse type mice with wheels.

Per Persson wrote `gnus-vm.el', the VM interface for Gnus.

Jens Petersen wrote `find-func.el', which makes it easy to find the source code for an Emacs Lisp function or variable.

Daniel Pfeiffer wrote:

`copyright.el', a package for updating copyright notices in files,
`executable.el', a package for executing interpreter scripts,
`sh-script.el', a mode for editing shell scripts,
`skeleton.el', implementing a concise language for writing statement skeletons, and
`two-column.el', a minor mode for simultaneous two-column editing.

Daniel also rewrote `apropos.el', originally written by Joe Wells, and, together with Jim Blandy, co-authored `wyse50.el', support for Wyse 50 terminals.

Richard L. Pieri wrote `pop3.el', a Post Office Protocol (RFC 1460) interface for Emacs.

Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit widgets.

Christian Plaunt wrote `soundex.el', an implementation of the Soundex algorithm for comparing English words by their pronunciation.

David Ponce wrote `recentf.el', a package that puts a menu of recently visited files in the Emacs menu bar.

Francesco A. Potorti wrote `cmacexp.el', providing a command which runs the C preprocessor on a region of a file and displays the results. He also expanded and redesigned the etags program.

Michael D. Prange and Steven A. Wood wrote `fortran.el', a mode for editing FORTRAN code.

Mukesh Prasad contributed `vmsproc.el', a facility for running asynchronous subprocesses on VMS.

Marko Rahamaa wrote `latin-3.el', code which sets up case-conversion and syntax tables for the ISO Latin-3 charact set.

Ashwin Ram wrote `refer.el', commands to look up references in bibliography files by keyword.

Eric S. Raymond wrote:

`vc.el', an interface to the RCS and SCCS source code version control systems, with Paul Eggert,
`gud.el', a package for running source-level debuggers like GDB and SDB in Emacs,
`asm-mode.el', a mode for editing assembly language code,
`AT386.el', terminal support package for IBM's AT keyboards,
`cookie1.el', support for "fortune-cookie" programs like `yow.el' and `spook.el',
`finder.el', a package for finding Emacs Lisp packages by keyword and topic,
`keyswap.el', code to swap the BS and DEL keys,
`loadhist.el', functions for loading and unloading Emacs features,
`lisp-mnt.el', functions for working with the special headers used in Emacs Lisp library files, and
code to set and make use of the load-history lisp variable, which records the source file from which each lisp function loaded into Emacs came.

Edward M. Reingold wrote the extensive calendar and diary support (try M-x calendar), with contributions from Stewart Clamen, Nachum Dershowitz, Paul Eggert, Steve Fisk, Michael Kifer, and Lara Rios. Andy Oram contributed to its documentation. Reingold has also contributed to `tex-mode.el', a mode for editing TeX files, as have William F. Schelter, Dick King, Stephen Gildea, Michael Prange, and Jacob Gore.

Alex Rezinsky contributed `which-func.el', a mode that shows the name of the current function in the mode line.

Rob Riepel contributed `tpu-edt.el' and its associated files, providing an emulation of the VMS TPU text editor emulating the VMS EDT editor, and `vt-control.el', providing some control functions for the DEC VT line of terminals.

Roland B. Roberts contributed much of the VMS support distributed with Emacs 19, along with Joseph M. Kelsey, and `vms-pmail.el', support for using Emacs within VMS MAIL.

John Robinson wrote `bg-mouse.el', support for the mouse on the BBN Bitgraph terminal.

Danny Roozendaal implemented `handwrite.el', which converts text into "handwriting."

William Rosenblatt wrote `float.el', implementing a floating-point numeric type using Lisp cons cells and integers.

Guillermo J. Rozas wrote `scheme.el', a mode for editing Scheme and DSSSL code, and `fakemail.c', an interface to the System V mailer.

Ivar Rummelhoff provided `winner.el', which records recent window configurations so you can move back to them.

Jason Rumney has ported the Emacs 21 display engine to MS-Windows, and contributed extensively to the MS-Windows port of Emacs.

Wolfgang Rupprecht contributed Emacs 19's floating-point support (including `float-sup.el' and `floatfns.c'), and `sup-mouse.el', support for the Supdup mouse on lisp machines.

James B. Salem and Brewster Kahle wrote `completion.el', providing dynamic word completion.

Masahiko Sato wrote `vip.el', an emulation of the VI editor.

Holger Schauer wrote `fortune.el', a package for using fortune in message signatures.

William Schelter wrote `telnet.el', support for telnet sessions within Emacs.

Ralph Schleicher contributed `battery.el', a package for displaying laptop computer battery status, and `info-look.el', a package for looking up Info documentation for symbols in the buffer.

Michael Schmidt and Tom Perrine wrote `modula2.el', a mode for editing Modula-2 code, based on work by Mick Jordan and Peter Robinson.

Ronald S. Schnell wrote `dunnet.el', a text adventure game.

Philippe Schnoebelen wrote `gomoku.el', a Go Moku game played against Emacs, and `mpuz.el', a multiplication puzzle.

Jan Schormann wrote `solitaire.el', an Emacs Lisp implementation of the Solitaire game.

Alex Schroeder wrote `ansi-color.el', a package for translating ANSI color escape sequences to Emacs faces, and `sql.el', a package for interactively running an SQL interpreter in an Emacs buffer.

Randal Schwartz wrote `pp.el', a pretty-printer for lisp objects.

Oliver Seidel wrote `todo-mode.el', a package for maintaining `TODO' list files.

Manuel Serrano contributed the Flyspell package that does spell checking as you type.

Hovav Shacham wrote `windmove.el', a set of commands for selecting windows based on their geometrical position on the frame.

Stanislav Shalunov wrote `uce.el', for responding to unsolicited commercial email.

Richard Sharman contributed `hilit-chg.el', which uses colors to show recent editing changes.

Olin Shivers wrote:

`comint.el', a library for modes running interactive command-line- oriented subprocesses,
`cmuscheme.el', for running inferior Scheme processes,
`inf-lisp.el', for running inferior Lisp process, and
`shell.el', for running inferior shells.

Espen Skoglund wrote `pascal.el', a mode for editing Pascal code.

Rick Sladkey wrote `backquote.el', a lisp macro for creating mostly-constant data.

Lynn Slater wrote `help-macro.el', a macro for writing interactive help for key bindings.

Chris Smith wrote `icon.el', a mode for editing Icon code.

David Smith wrote `ielm.el', a mode for interacting with the Emacs Lisp interpreter as a subprocess.

Paul D. Smith wrote `snmp-mode.el'.

William Sommerfeld wrote `scribe.el', a mode for editing Scribe files, and `server.el', a package allowing programs to send files to an extant Emacs job to be edited.

Andre Spiegel made many contributions to the Emacs Version Control package, and in particular made it support multiple back ends.

Michael Staats wrote `pc-select.el', which rebinds keys for selecting regions to follow many other systems.

Richard Stallman invented Emacs, and then wrote:

`easymeny.el', a facility for defining Emacs menus,
`menu-bar.el', the Emacs menu bar support code,
`paren.el', a package to make matching parentheses stand out in color, and
most of the rest of Emacs code.

Sam Steingold wrote `gulp.el', a facility for asking package maintainers for updated versions of their packages via e-mail, and `midnight.el', a package for running a command every midnight.

Ake Stenhoff and Lars Lindberg wrote `imenu.el', a framework for browsing indices made from buffer contents.

Peter Stephenson contributed `vcursor.el', which implements a "virtual cursor" that you can move with the keyboard and use for copying text.

Ken Stevens wrote the initial version of `ispell.el' and maintains that package since Ispell 3.1 release.

Jonathan Stigelman wrote `hilit19.el', a package providing automatic highlighting in source code buffers, mail readers, and other contexts.

Martin Stjernholm co-authored CC Mode, a major editing mode for C, C++, Objective-C, and Java code.

Steve Strassman did not write `spook.el', and even if he did, he really didn't mean for you to use it in an anarchistic way.

Olaf Sylvester wrote `bs.el', a package for manipulating Emacs buffers.

Tibor S<imko and Milan Zamazal wrote `slovak.el', support for editing text in Slovak language.

Naoto Takahashi wrote `utf-8.el', support for encoding and decoding UTF-8 data.

Taichi Kawabata wrote support for Devanagari script and the Indian languages.

Jens T. Berger Thielemann wrote `word-help.el', which is part of the basis for `info-look.el'.

Spencer Thomas wrote the original `dabbrev.el', providing a command which completes the partial word before point, based on other nearby words for which it is a prefix. He also wrote the original dumping support.

Jim Thompson wrote `ps-print.el', which converts Emacs text to Postscript.

Tom Tromey and Chris Lindblad wrote `tcl.el', a major mode for editing Tcl/Tk source files and running a Tcl interpeter as an Emacs subprocess.

Daiki Ueno wrote `starttls.el', support for Transport Layer Security protocol.

Masanobu Umeda wrote:

GNUS, a feature-full reader for Usenet news,
`prolog.el', a mode for editing Prolog code,
`rmailsort.el', a package for sorting messages in RMAIL folders,
`metamail.el', an interface to the Metamail program,
`gnus-kill.el', the Kill File mode for Gnus,
`gnus-mh.el', an mh-e interface for Gnus,
`gnus-msg.el', a mail and post interface for Gnus,
`tcp.el', emulation of the open-network-stream function for some Emacs configurations which lack it, and
`timezone.el', providing functions for dealing with time zones.

Rajesh Vaidheeswarran wrote `whitespace.el', a package that detects and cleans up excess whitespace in a file.

Neil W. Van Dyke wrote `webjump.el', a "hot links" package.

Didier Verna contributed `rect.el', a package of functions for operations on rectangle regions of text.

Ulrik Vieth implemented `meta-mode.el', for editing MetaFont code.

Geoffrey Voelker wrote the Windows NT support. He also wrote `dos-w32.el', functions shared by the MS-DOS and MS-Windows ports of Emacs, and `w32-fns.el', MS-Windows specific support functions.

Johan Vromans wrote `forms.el' and its associated files, defining a mode for filling in forms, and `iso-acc.el', a minor mode providing electric accent keys for text using the ISO-8859 character set.

Barry Warsaw wrote:

`assoc.el', a set of utility functions for working with association lists,
`cc-mode.el', a major mode for editing C, C++, and Java code, based on earlier work by Dave Detlefs, Stewart Clamen, and Richard Stallman,
`elp.el', a new profiler for Emacs Lisp programs.
`man.el', a mode for reading UNIX manual pages,
`regi.el', providing an AWK-like functionality for use in lisp programs,
`reporter.el', providing customizable bug reporting for lisp packages, and
`supercite.el', a minor mode for quoting sections of mail messages and news articles.

Morten Welinder introduced face support into the MS-DOS port of Emacs, and also wrote:

`desktop.el', facilities for saving some of Emacs's state between sessions,
`timer.el', the Emacs facility to run commands at a given time or frequency, or when Emacs is idle, and its C-level support code,
`pc-win.el', the MS-DOS "window-system" support,
`internal.el', an "internal terminal" emulator for the MS-DOS port of Emacs,
`arc-mode.el', the mode for editing compressed archives,
`s-region.el', commands for setting the region using the shift key and motion commands, and
`dos-fns.el', functions for use under MS-DOS.

He also helped port Emacs to MS-DOS.

Joseph Brian Wells wrote:

`apropos.el', a command to find commands, functions, and variables whose names contain matches for a regular expression,
`resume.el', support for processing command-line arguments after resuming a suspended Emacs job, and
`mail-extr.el', a package for extracting names and addresses from mail headers, with contributions from Jamie Zawinski.

Rodney Whitby and Reto Zimmermann wrote `vhdl-mode.el', a major mode for editing VHDL source code.

John Wiegley wrote `align.el', a set of commands for aligning text according to regular-expression based rules; `timeclock.el', a package for keeping track of time spent on projects; `pcomplete.el', a programmable completion facility; and eshell, a command shell implemented entirely in Emacs Lisp.

Ed Wilkinson wrote `b2m.c', a program to convert mail files from RMAIL format to Unix mbox format.

Mike Williams wrote `mouse-sel.el', providing enhanced mouse selection, and `thingatpt.el', a library of functions for finding the "thing" (word, line, s-expression) containing point.

Bill Wohler wrote the Emacs interface to the MH mail system.

Dale R. Worley wrote `emerge.el', a package for interactively merging two versions of a file.

Francis J. Wright wrote WoMan, a package for browsing manual pages without the man command.

Tom Wurgler wrote `emacs-lock.el', which makes it harder to exit with valuable buffers unsaved.

Ilya Zakharevich and Bob Olson contributed `cperl-mode.el', a major mode for editing Perl code. Ilya Zakharevich also wrote `tmm.el', a mode for accessing the Emacs menu bar on a text-mode terminal.

Milan Zamazal wrote `czech.el', support for editing Czech text, `glasses.el', a package for easier reading of source code which uses illegible identifier names such as cantReadThisVariable, and `tildify.el', commands for adding hard spaces to text, TeX, and SGML/HTML files.

Victor Zandy contributed `zone.el', a package for people who like to zone out in front of Emacs.

Eli Zaretskii made many standard Emacs features work on MS-DOS. He also wrote `tty-colors.el', which implements transparent mapping of X colors to tty colors, and (together with Kenichi Handa) `codepage.el', a package for editing text encoded in DOS/Windows code pages.

Jamie Zawinski wrote:

Emacs 19's optimizing byte compiler, with Hallvard Furuseth,
much of the support for faces and X selections,
`mailabbrev.el', a package providing automatic expansion of mail aliases, and
`tar-mode.el', providing simple viewing and editing commands for tar files.

Shenghuo Zhu wrote:

`binhex.el', a package for reading and writing binhex files,
`mm-partial.el', message/partial support for MIME messages,
`rfc1843.el', an HZ decoding package,
`uudecode.el', an Emacs Lisp decoder for uuencoded data,
`webmail.el', an interface to Web mail.

Ian T. Zimmerman wrote `gametree.el'.

Neal Ziring and Felix S. T. Wu wrote `vi.el', an emulation of the VI text editor.

Detlev Zundel wrote `re-builder.el', a package for building regexps with visual feedback.

Others too numerous to mention have reported and fixed bugs, and added features to many parts of Emacs. (Many are mentioned in the `ChangeLog' files which are summarized in the file `AUTHORS' in the distribution.) We thank them for their generosity as well.

This list intended to mention every contributor of a major package or feature we currently distribute; if you know of someone we have omitted, please report that as a manual bug.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Key (Character) Index

Jump to:

! " # $ % & * + . < = > ^ ~
A B C D E F G H I J K L M N O P Q R S T U V W X Z

Index Entry

Section

!

! (Dired)

AB.8 Shell Commands in Dired

"

" (TeX mode)

T.9.1 TeX Editing Commands

#

# (Dired)

AB.4 Flagging Many Files at Once

$

$ (Dired)

AB.13 Hiding Subdirectories

%

% C (Dired)

AB.9 Transforming File Names in Dired

% d (Dired)

AB.4 Flagging Many Files at Once

% g (Dired)

AB.6 Dired Marks vs. Flags

% H (Dired)

AB.9 Transforming File Names in Dired

% l (Dired)

AB.9 Transforming File Names in Dired

% m (Dired)

AB.6 Dired Marks vs. Flags

% R (Dired)

AB.9 Transforming File Names in Dired

% S (Dired)

AB.9 Transforming File Names in Dired

% u (Dired)

AB.9 Transforming File Names in Dired

&

& (Dired)

AB.4 Flagging Many Files at Once

*

* ! (Dired)

AB.6 Dired Marks vs. Flags

* % (Dired)

AB.6 Dired Marks vs. Flags

* * (Dired)

AB.6 Dired Marks vs. Flags

* / (Dired)

AB.6 Dired Marks vs. Flags

* ? (Dired)

AB.6 Dired Marks vs. Flags

* @ (Dired)

AB.6 Dired Marks vs. Flags

* c (Dired)

AB.6 Dired Marks vs. Flags

* C-n (Dired)

AB.6 Dired Marks vs. Flags

* C-p (Dired)

AB.6 Dired Marks vs. Flags

* DEL (Dired)

AB.6 Dired Marks vs. Flags

* m (Dired)

AB.6 Dired Marks vs. Flags

* s (Dired)

AB.6 Dired Marks vs. Flags

* t (Dired)

AB.6 Dired Marks vs. Flags

* u (Dired)

AB.6 Dired Marks vs. Flags

+

+ (Dired)

AB.7 Operating on Files

.

. (Calendar mode)

AC.1.3 Specified Dates

. (Dired)

AB.4 Flagging Many Files at Once

. (Rmail)

AA.2 Scrolling Within a Message

<

< (Dired)

AB.12 Moving Over Subdirectories

< (Rmail)

AA.3 Moving Among Messages

=

= (Dired)

AB.10 File Comparison with Dired

>

> (Dired)

AB.12 Moving Over Subdirectories

> (Rmail)

AA.3 Moving Among Messages

^

^ (Dired)

AB.5 Visiting Files in Dired

~

~ (Dired)

AB.4 Flagging Many Files at Once

A

a (Calendar mode)

AC.6 Holidays

a (Dired)

AB.5 Visiting Files in Dired

A (Dired)

AB.7 Operating on Files

a (Rmail)

AA.8 Labels

B

B (Dired)

AB.7 Operating on Files

b (Rmail)

AA.1 Basic Concepts of Rmail

BACKSPACE

H.7.1 Deletion

BS

H.7.1 Deletion

BS (MS-DOS)

AH.1 Keyboard and Mouse on MS-DOS

C

C (Dired)

AB.7 Operating on Files

c (Rmail)

AA.10 Sending Replies

C-@

H.1 Setting the Mark

C-\

Q.5 Selecting an Input Method

C-]

AD.8 Quitting and Aborting

C-_

D.4 Undoing Changes

C-_ (Dired)

AB.6 Dired Marks vs. Flags

C-a

D.2 Changing the Location of Point

C-a (Calendar mode)

AC.1.2 Beginning or End of Week, Month or Year

C-b

D.2 Changing the Location of Point

C-b (Calendar mode)

AC.1.1 Motion by Standard Lengths of Time

C-BREAK (MS-DOS)

AH.1 Keyboard and Mouse on MS-DOS

C-c ' (Picture mode)

Y.2 Controlling Motion after Insert

C-c . (Picture mode)

Y.2 Controlling Motion after Insert

C-c / (Picture mode)

Y.2 Controlling Motion after Insert

C-c ; (Fortran mode)

U.12.3 Fortran Comments

C-c < (GUD)

V.5.3 Commands of GUD

C-c < (Picture mode)

Y.2 Controlling Motion after Insert

C-c > (GUD)

V.5.3 Commands of GUD

C-c > (Picture mode)

Y.2 Controlling Motion after Insert

C-c @ (Outline minor mode)

T.8 Outline Mode

C-c @ C-h

U.7 Hideshow minor mode

C-c @ C-l

U.7 Hideshow minor mode

C-c @ C-M-h

U.7 Hideshow minor mode

C-c @ C-M-s

U.7 Hideshow minor mode

C-c @ C-r

U.7 Hideshow minor mode

C-c @ C-s

U.7 Hideshow minor mode

C-c \ (Picture mode)

Y.2 Controlling Motion after Insert

C-c ^ (Picture mode)

Y.2 Controlling Motion after Insert

C-c ` (Picture mode)

Y.2 Controlling Motion after Insert

C-c C-\ (C mode)

U.11.4 Other Commands for C Mode

C-c C-\ (Shell mode)

AC.15.3 Shell Mode

C-c C-a (C mode)

U.11.2 Electric C Characters

C-c C-a (Mail mode)

Z.3 Mail Aliases

C-c C-a (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-a (Shell mode)

AC.15.3 Shell Mode

C-c C-b (Outline mode)

T.8.2 Outline Motion Commands

C-c C-b (Picture mode)

Y.2 Controlling Motion after Insert

C-c C-b (Shell mode)

AC.15.3 Shell Mode

C-c C-b (TeX mode)

T.9.3 TeX Printing Commands

C-c C-c (Edit Abbrevs)

X.4 Examining and Editing Abbrevs

C-c C-c (Edit Tab Stops)

S.2 Tab Stops

C-c C-c (Mail mode)

Z.4.1 Mail Sending

C-c C-c (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-c (Shell mode)

AC.15.3 Shell Mode

C-c C-d (C mode)

U.11.3 Hungry Delete Feature in C

C-c C-d (Fortran mode)

U.12.2.1 Fortran Indentation and Filling Commands

C-c C-d (GUD)

V.5.3 Commands of GUD

C-c C-d (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-d (Picture mode)

Y.1 Basic Editing in Picture Mode

C-c C-e (C mode)

U.11.4 Other Commands for C Mode

C-c C-e (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-e (Shell mode)

AC.15.3 Shell Mode

C-c C-e (LaTeX mode)

T.9.2 LaTeX Editing Commands

C-c C-f (GUD)

V.5.3 Commands of GUD

C-c C-f (Outline mode)

T.8.2 Outline Motion Commands

C-c C-f (Picture mode)

Y.2 Controlling Motion after Insert

C-c C-f (Shell mode)

AC.15.3 Shell Mode

C-c C-f (TeX mode)

T.9.3 TeX Printing Commands

C-c C-f C-b (Mail mode)

Z.4.2 Mail Header Editing

C-c C-f C-c (Mail mode)

Z.4.2 Mail Header Editing

C-c C-f C-f (Mail mode)

Z.4.2 Mail Header Editing

C-c C-f C-s (Mail mode)

Z.4.2 Mail Header Editing

C-c C-f C-t (Mail mode)

Z.4.2 Mail Header Editing

C-c C-i (GUD)

V.5.3 Commands of GUD

C-c C-i (Mail mode)

Z.4.4 Mail Mode Miscellany

C-c C-i (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-j (Term mode)

AC.15.8 Term Mode

C-c C-k (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-k (Picture mode)

Y.4 Picture Mode Rectangle Commands

C-c C-k (Term mode)

AC.15.8 Term Mode

C-c C-k (TeX mode)

T.9.3 TeX Printing Commands

C-c C-l (Calendar mode)

AC.4 Miscellaneous Calendar Commands

C-c C-l (GUD)

V.5.3 Commands of GUD

C-c C-l (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-l (Shell mode)

AC.15.3 Shell Mode

C-c C-l (TeX mode)

T.9.3 TeX Printing Commands

C-c C-n (C mode)

U.11.1 C Mode Motion Commands

C-c C-n (Fortran mode)

U.12.1 Motion Commands

C-c C-n (GUD)

V.5.3 Commands of GUD

C-c C-n (Outline mode)

T.8.2 Outline Motion Commands

C-c C-n (Shell mode)

AC.15.4.2 Shell History Copying

C-c C-o (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-o (Shell mode)

AC.15.3 Shell Mode

C-c C-o (LaTeX mode)

T.9.2 LaTeX Editing Commands

C-c C-p (C mode)

U.11.1 C Mode Motion Commands

C-c C-p (Fortran mode)

U.12.1 Motion Commands

C-c C-p (Outline mode)

T.8.2 Outline Motion Commands

C-c C-p (Shell mode)

AC.15.4.2 Shell History Copying

C-c C-p (TeX mode)

T.9.3 TeX Printing Commands

C-c C-q (C mode)

U.3.4 Commands for C Indentation

C-c C-q (Mail mode)

Z.4.3 Citing Mail

C-c C-q (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-q (Term mode)

AC.15.9 Page-At-A-Time Output

C-c C-q (TeX mode)

T.9.3 TeX Printing Commands

C-c C-r (Fortran mode)

U.12.5 Checking Columns in Fortran

C-c C-r (GUD)

V.5.3 Commands of GUD

C-c C-r (Mail mode)

Z.4.3 Citing Mail

C-c C-r (Shell mode)

AC.15.3 Shell Mode

C-c C-r (TeX mode)

T.9.3 TeX Printing Commands

C-c C-s (C mode)

U.11.4 Other Commands for C Mode

C-c C-s (GUD)

V.5.3 Commands of GUD

C-c C-s (Mail mode)

Z.4.1 Mail Sending

C-c C-s (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-s (Shell mode)

AC.15.3 Shell Mode

C-c C-t (C mode)

U.11.3 Hungry Delete Feature in C

C-c C-t (GUD)

V.5.3 Commands of GUD

C-c C-t (Mail mode)

Z.4.4 Mail Mode Miscellany

C-c C-t (Outline mode)

T.8.3 Outline Visibility Commands

C-c C-u (C mode)

U.11.1 C Mode Motion Commands

C-c C-u (Outline mode)

T.8.2 Outline Motion Commands

C-c C-u (Shell mode)

AC.15.3 Shell Mode

C-c C-v (TeX mode)

T.9.3 TeX Printing Commands

C-c C-w (Fortran mode)

U.12.5 Checking Columns in Fortran

C-c C-w (Mail mode)

Z.4.4 Mail Mode Miscellany

C-c C-w (Picture mode)

Y.4 Picture Mode Rectangle Commands

C-c C-w (Shell mode)

AC.15.3 Shell Mode

C-c C-x

T.8.5 Folding Editing

C-c C-x (Picture mode)

Y.4 Picture Mode Rectangle Commands

C-c C-y (Mail mode)

Z.4.3 Citing Mail

C-c C-y (Picture mode)

Y.4 Picture Mode Rectangle Commands

C-c C-z

T.8.5 Folding Editing

C-c C-z (Shell mode)

AC.15.3 Shell Mode

C-c colon (C mode)

U.11.2 Electric C Characters

C-c RET (Shell mode)

AC.15.4.2 Shell History Copying

C-c TAB (Picture mode)

Y.3 Picture Mode Tabs

C-c TAB (TeX mode)

T.9.3 TeX Printing Commands

C-c { (TeX mode)

T.9.1 TeX Editing Commands

C-c } (TeX mode)

T.9.1 TeX Editing Commands

C-d

H.7.1 Deletion

C-d (Rmail)

AA.4 Deleting Messages

C-d (Shell mode)

AC.15.3 Shell Mode

C-Down-Mouse-1

N.7.3 Customizing Buffer Menus

C-e

D.2 Changing the Location of Point

C-e (Calendar mode)

AC.1.2 Beginning or End of Week, Month or Year

C-f

D.2 Changing the Location of Point

C-f (Calendar mode)

AC.1.1 Motion by Standard Lengths of Time

C-g

AD.8 Quitting and Aborting

C-g (MS-DOS)

AH.1 Keyboard and Mouse on MS-DOS

C-h

G. Help

C-h a

G.4 Apropos

C-h b

G.8 Other Help Commands

C-h C

Q.7 Coding Systems

C-h c

G.2 Documentation for a Key

C-h C-\

Q.5 Selecting an Input Method

C-h C-c

G.8 Other Help Commands

C-h C-d

G.8 Other Help Commands

C-h C-f

G.8 Other Help Commands

C-h C-h

G. Help

C-h C-i

U.6.1 Info Documentation Lookup

C-h C-k

G.8 Other Help Commands

C-h C-p

G.8 Other Help Commands

C-h C-w

G.8 Other Help Commands

C-h F

G.8 Other Help Commands

C-h f

G.3 Help by Command or Variable Name

C-h h

Q.1 Introduction to International Character Sets

C-h I

Q.5 Selecting an Input Method

C-h i

G.8 Other Help Commands

C-h k

G.2 Documentation for a Key

C-h L

Q.3 Language Environments

C-h l

G.8 Other Help Commands

C-h m

G.8 Other Help Commands

C-h n

G.8 Other Help Commands

C-h P

G.8 Other Help Commands

C-h p

G.5 Keyword Search for Lisp Libraries

C-h s

AD.6 The Syntax Table

C-h t

D. Basic Editing Commands

C-h w

G.3 Help by Command or Variable Name

C-j

U.3.1 Basic Program Indentation Commands

C-j (and major modes)

R. Major Modes

C-j (MS-DOS)

AH.1 Keyboard and Mouse on MS-DOS

C-j (TeX mode)

T.9.1 TeX Editing Commands

C-k

H.7.2 Killing by Lines

C-k (Gnus)

AC.14.3 Summary of Gnus Commands

C-l

J.6 Scrolling

C-M-%

K.7.4 Query Replace

C-M-.

W.2.5 Finding a Tag

C-M-/

X.6 Dynamic Abbrev Expansion

C-M-@

U.4.1 Expressions with Balanced Parentheses

C-M-\

S.1 Indentation Commands and Techniques

C-M-a

U.2.2 Moving by Defuns

C-M-b

U.4.1 Expressions with Balanced Parentheses

C-M-c

AC.26 Recursive Editing Levels

C-M-d

U.4.2 Moving in the Parenthesis Structure

C-M-d (Dired)

AB.12 Moving Over Subdirectories

C-M-DEL

U.4.1 Expressions with Balanced Parentheses

C-M-e

U.2.2 Moving by Defuns

C-M-f

U.4.1 Expressions with Balanced Parentheses

C-M-h

U.2.2 Moving by Defuns

C-M-h (C mode)

U.2.2 Moving by Defuns

C-M-j

U.5.2 Multiple Lines of Comments

C-M-j (Fortran mode)

U.12.2.1 Fortran Indentation and Filling Commands

C-M-k

U.4.1 Expressions with Balanced Parentheses

C-M-l

J.6 Scrolling

C-M-l (Rmail)

AA.11.1 Making Summaries

C-M-l (Shell mode)

AC.15.3 Shell Mode

C-M-n

U.4.2 Moving in the Parenthesis Structure

C-M-n (Dired)

AB.12 Moving Over Subdirectories

C-M-n (Rmail)

AA.8 Labels

C-M-o

S.1 Indentation Commands and Techniques

C-M-p

U.4.2 Moving in the Parenthesis Structure

C-M-p (Dired)

AB.12 Moving Over Subdirectories

C-M-p (Rmail)

AA.8 Labels

C-M-q

U.3.2 Indenting Several Lines

C-M-q (C mode)

U.3.4 Commands for C Indentation

C-M-q (Fortran mode)

U.12.2.1 Fortran Indentation and Filling Commands

C-M-r

K.4 Regular Expression Search

C-M-r (Rmail)

AA.11.1 Making Summaries

C-M-s

K.4 Regular Expression Search

C-M-s (Rmail)

AA.11.1 Making Summaries

C-M-t

U.4.1 Expressions with Balanced Parentheses

C-M-t (Rmail)

AA.11.1 Making Summaries

C-M-u

U.4.2 Moving in the Parenthesis Structure

C-M-u (Dired)

AB.12 Moving Over Subdirectories

C-M-v

O.3 Using Other Windows

C-M-w

H.8.2 Appending Kills

C-M-x (Emacs-Lisp mode)

V.8 Evaluating Emacs-Lisp Expressions

C-M-x (Lisp mode)

V.10 Running an External Lisp

C-Mouse-1

P.5 Mouse Clicks for Menus

C-Mouse-2

P.5 Mouse Clicks for Menus

C-mouse-2 (mode line)

P.6 Mode Line Mouse Commands

C-Mouse-2 (scroll bar)

O.2 Splitting Windows

C-Mouse-2 (scroll bar)

P.6 Mode Line Mouse Commands

C-Mouse-3

P.5 Mouse Clicks for Menus

C-Mouse-3 (when menu bar is disabled)

P.15 Menu Bars

C-n

D.2 Changing the Location of Point

C-n (Calendar mode)

AC.1.1 Motion by Standard Lengths of Time

C-n (Dired)

AB.2 Navigation in the Dired Buffer

C-n (Gnus Group mode)

AC.14.3 Summary of Gnus Commands

C-n (Gnus Summary mode)

AC.14.3 Summary of Gnus Commands

C-o

D.7 Blank Lines

C-o (Dired)

AB.5 Visiting Files in Dired

C-o (Rmail)

AA.7 Copying Messages Out to Files

C-p

D.2 Changing the Location of Point

C-p (Calendar mode)

AC.1.1 Motion by Standard Lengths of Time

C-p (Dired)

AB.2 Navigation in the Dired Buffer

C-p (Gnus Group mode)

AC.14.3 Summary of Gnus Commands

C-p (Gnus Summary mode)

AC.14.3 Summary of Gnus Commands

C-q

D.1 Inserting Text

C-r

K.1 Incremental Search

C-s

K.1 Incremental Search

C-S-Mouse-3 (FFAP)

AC.28.3 Finding Files and URLs at Point

C-SPC

H.1 Setting the Mark

C-t

L.2 Transposing Text

C-TAB

M.15 File Name Cache

C-u

D.10 Numeric Arguments

C-u C-@

H.5 The Mark Ring

C-u C-c C-w (Fortran mode)

U.12.5 Checking Columns in Fortran

C-u C-SPC

H.5 The Mark Ring

C-u C-x u

D.4 Undoing Changes

C-u M-;

U.5.1 Comment Commands

C-u TAB

U.3.2 Indenting Several Lines

C-v

J.6 Scrolling

C-v (Calendar mode)

AC.2 Scrolling in the Calendar

C-w

H.7.3 Other Kill Commands

C-x #

AC.16 Using Emacs as a Server

C-x $

J.9 Selective Display

C-x (

AD.3.1 Basic Use

C-x )

AD.3.1 Basic Use

C-x +

O.6 Deleting and Rearranging Windows

C-x -

O.6 Deleting and Rearranging Windows

C-x .

T.5.4 The Fill Prefix

C-x 0

O.6 Deleting and Rearranging Windows

C-x 1

O.6 Deleting and Rearranging Windows

C-x 2

O.2 Splitting Windows

C-x 3

O.2 Splitting Windows

C-x 4

O.4 Displaying in Another Window

C-x 4 .

W.2.5 Finding a Tag

C-x 4 0

O.6 Deleting and Rearranging Windows

C-x 4 a

W.1 Change Logs

C-x 4 b

N.1 Creating and Selecting Buffers

C-x 4 b (Iswitchb mode)

N.7.2 Switching Between Buffers using Substrings

C-x 4 c

N.6 Indirect Buffers

C-x 4 C-o (Iswitchb mode)

N.7.2 Switching Between Buffers using Substrings

C-x 4 d

AB.1 Entering Dired

C-x 4 f

M.2 Visiting Files

C-x 4 f (FFAP)

AC.28.3 Finding Files and URLs at Point

C-x 4 m

Z. Sending Mail

C-x 5

P.7 Creating Frames

C-x 5 .

W.2.5 Finding a Tag

C-x 5 0

P.8 Frame Commands

C-x 5 1

P.8 Frame Commands

C-x 5 2

P.7 Creating Frames

C-x 5 b

N.1 Creating and Selecting Buffers

C-x 5 b (Iswitchb mode)

N.7.2 Switching Between Buffers using Substrings

C-x 5 d

AB.1 Entering Dired

C-x 5 f

M.2 Visiting Files

C-x 5 f (FFAP)

AC.28.3 Finding Files and URLs at Point

C-x 5 m

Z. Sending Mail

C-x 5 o

P.8 Frame Commands

C-x 5 r

P.7 Creating Frames

C-x 6 1

AC.23 Two-Column Editing

C-x 6 2

AC.23 Two-Column Editing

C-x 6 b

AC.23 Two-Column Editing

C-x 6 d

AC.23 Two-Column Editing

C-x 6 RET

AC.23 Two-Column Editing

C-x 6 s

AC.23 Two-Column Editing

C-x 8

Q.13 Single-byte Character Set Support

C-x ;

U.5.3 Options Controlling Comments

C-x <

J.7 Horizontal Scrolling

C-x < (Calendar mode)

AC.2 Scrolling in the Calendar

C-x =

D.9 Cursor Position Information

C-x >

J.7 Horizontal Scrolling

C-x > (Calendar mode)

AC.2 Scrolling in the Calendar

C-x [

T.4 Pages

C-x [ (Calendar mode)

AC.1.1 Motion by Standard Lengths of Time

C-x ]

T.4 Pages

C-x ] (Calendar mode)

AC.1.1 Motion by Standard Lengths of Time

C-x ^

O.6 Deleting and Rearranging Windows

C-x `

V.3 Compilation Mode

C-x a g

X.2 Defining Abbrevs

C-x a i g

X.2 Defining Abbrevs

C-x a i l

X.2 Defining Abbrevs

C-x a l

X.2 Defining Abbrevs

C-x b

N.1 Creating and Selecting Buffers

C-x b (Iswitchb mode)

N.7.2 Switching Between Buffers using Substrings

C-x C-a (GUD)

V.5.3 Commands of GUD

C-x C-b

N.2 Listing Existing Buffers

C-x C-c

C.1 Exiting Emacs

C-x C-d

M.8 File Directories

C-x C-e

V.8 Evaluating Emacs-Lisp Expressions

C-x C-f

M.2 Visiting Files

C-x C-f (FFAP)

AC.28.3 Finding Files and URLs at Point

C-x C-k

AD.3.1 Basic Use

C-x C-l

T.6 Case Conversion Commands

C-x C-n

D.2 Changing the Location of Point

C-x C-o

D.7 Blank Lines

C-x C-p

T.4 Pages

C-x C-q

N.3 Miscellaneous Buffer Operations

C-x C-q (Version Control)

M.7.3 Basic Editing under Version Control

C-x C-r

M.2 Visiting Files

C-x C-s

M.3 Saving Files

C-x C-SPC

H.6 The Global Mark Ring

C-x C-t

L.2 Transposing Text

C-x C-u

T.6 Case Conversion Commands

C-x C-v

M.2 Visiting Files

C-x C-w

M.3 Saving Files

C-x C-x

H.1 Setting the Mark

C-x C-z

V.10 Running an External Lisp

C-x d

AB.1 Entering Dired

C-x d (FFAP)

AC.28.3 Finding Files and URLs at Point

C-x DEL

T.2 Sentences

C-x e

AD.3.1 Basic Use

C-x ESC ESC

E.5 Repeating Minibuffer Commands

C-x f

T.5.3 Explicit Fill Commands

C-x h

H.4 Commands to Mark Textual Objects

C-x i

M.10 Miscellaneous File Operations

C-x k

N.4 Killing Buffers

C-x l

T.4 Pages

C-x m

Z. Sending Mail

C-x n d

AC.22 Narrowing

C-x n n

AC.22 Narrowing

C-x n p

AC.22 Narrowing

C-x n w

AC.22 Narrowing

C-x o

O.3 Using Other Windows

C-x q

AD.3.3 Executing Macros with Variations

C-x r +

I.5 Keeping Numbers in Registers

C-x r b

I.7 Bookmarks

C-x r d

H.10 Rectangles

C-x r f

I.4 Saving Window Configurations in Registers

C-x r i

I.2 Saving Text in Registers

C-x r j

I.1 Saving Positions in Registers

C-x r k

H.10 Rectangles

C-x r l

I.7 Bookmarks

C-x r m

I.7 Bookmarks

C-x r n

I.5 Keeping Numbers in Registers

C-x r o

H.10 Rectangles

C-x r r

I.3 Saving Rectangles in Registers

C-x r s

I.2 Saving Text in Registers

C-x r SPC

I.1 Saving Positions in Registers

C-x r t

H.10 Rectangles

C-x r w

I.4 Saving Window Configurations in Registers

C-x r y

H.10 Rectangles

C-x RET

Q.1 Introduction to International Character Sets

C-x RET c

Q.9 Specifying a Coding System

C-x RET C-\

Q.5 Selecting an Input Method

C-x RET f

Q.9 Specifying a Coding System

C-x RET k

Q.9 Specifying a Coding System

C-x RET p

Q.9 Specifying a Coding System

C-x RET t

Q.9 Specifying a Coding System

C-x RET x

Q.9 Specifying a Coding System

C-x RET X

Q.9 Specifying a Coding System

C-x s

M.3 Saving Files

C-x SPC

V.5.3 Commands of GUD

C-x TAB

S.1 Indentation Commands and Techniques

C-x TAB (Enriched mode)

T.11.6 Indentation in Formatted Text

C-x u

D.4 Undoing Changes

C-x v =

M.7.4 Examining And Comparing Old Versions

C-x v a

M.7.9.1 Change Logs and VC

C-x v b

M.7.7.2 Local Version Control

C-x v c

M.7.5.3 Undoing Version Control Actions

C-x v d

M.7.5.4 Dired under VC

C-x v g

M.7.4 Examining And Comparing Old Versions

C-x v h

M.7.9.3 Inserting Version Control Headers

C-x v i

M.7.5.1 Registering a File for Version Control

C-x v l

M.7.5.2 VC Status Commands

C-x v m

M.7.6.3 Merging Branches

C-x v r

M.7.8.1 Making and Using Snapshots

C-x v s

M.7.8.1 Making and Using Snapshots

C-x v u

M.7.5.3 Undoing Version Control Actions

C-x v v

M.7.3 Basic Editing under Version Control

C-x v ~

M.7.4 Examining And Comparing Old Versions

C-x w b

J.4 Interactive Highlighting by Matching

C-x w h

J.4 Interactive Highlighting by Matching

C-x w i

J.4 Interactive Highlighting by Matching

C-x w l

J.4 Interactive Highlighting by Matching

C-x w r

J.4 Interactive Highlighting by Matching

C-x z

D.11 Repeating a Command

C-x }

O.6 Deleting and Rearranging Windows

C-y

H.8.1 The Kill Ring

C-z

C.1 Exiting Emacs

C-z (X windows)

P.8 Frame Commands

D

d (Calendar mode)

AC.10.1 Commands Displaying Diary Entries

d (Dired)

AB.3 Deleting Files with Dired

D (Dired)

AB.7 Operating on Files

d (Rmail)

AA.4 Deleting Messages

DEL

H.7.1 Deletion

DEL (and major modes)

R. Major Modes

DEL (Dired)

AB.3 Deleting Files with Dired

DEL (Gnus)

AC.14.3 Summary of Gnus Commands

DEL (MS-DOS)

AH.1 Keyboard and Mouse on MS-DOS

DEL (programming modes)

U.1 Major Modes for Programming Languages

DEL (Rmail)

AA.2 Scrolling Within a Message

DELETE

H.7.1 Deletion

DELETE (and mouse selection)

P.1 Mouse Commands for Editing

DOWN

D.2 Changing the Location of Point

E

e (Dired)

AB.5 Visiting Files in Dired

e (Rmail)

AA.15 Editing Within a Message

ESC a

U.11.1 C Mode Motion Commands

ESC e

U.11.1 C Mode Motion Commands

ESC ESC ESC

AD.8 Quitting and Aborting

F

f (Dired)

AB.5 Visiting Files in Dired

f (Rmail)

AA.10 Sending Replies

F1

G. Help

F10

B.4 The Menu Bar

F2 1

AC.23 Two-Column Editing

F2 2

AC.23 Two-Column Editing

F2 b

AC.23 Two-Column Editing

F2 d

AC.23 Two-Column Editing

F2 RET

AC.23 Two-Column Editing

F2 s

AC.23 Two-Column Editing

G

G (Dired)

AB.7 Operating on Files

g (Dired)

AB.14 Updating the Dired Buffer

g (Rmail)

AA.6 Multiple Rmail Files

g char (Calendar mode)

AC.9.3 Converting From Other Calendars

g d (Calendar mode)

AC.1.3 Specified Dates

g m (Calendar mode)

AC.9.4 Converting from the Mayan Calendar

H

h (Calendar mode)

AC.6 Holidays

H (Dired)

AB.7 Operating on Files

h (Rmail)

AA.11.1 Making Summaries

Help

G. Help

I

i (Dired)

AB.11 Subdirectories in Dired

i (Rmail)

AA.6 Multiple Rmail Files

i a (Calendar mode)

AC.10.5 Special Diary Entries

i b (Calendar mode)

AC.10.5 Special Diary Entries

i c (Calendar mode)

AC.10.5 Special Diary Entries

i d (Calendar mode)

AC.10.4 Commands to Add to the Diary

i m (Calendar mode)

AC.10.4 Commands to Add to the Diary

i w (Calendar mode)

AC.10.4 Commands to Add to the Diary

i y (Calendar mode)

AC.10.4 Commands to Add to the Diary

INSERT

AD.1 Minor Modes

J

j (Rmail)

AA.3 Moving Among Messages

K

k (Dired)

AB.14 Updating the Dired Buffer

k (Rmail)

AA.8 Labels

L

l (Dired)

AB.14 Updating the Dired Buffer

L (Dired)

AB.7 Operating on Files

L (Gnus Group mode)

AC.14.3 Summary of Gnus Commands

l (Gnus Group mode)

AC.14.3 Summary of Gnus Commands

l (Rmail)

AA.11.1 Making Summaries

LEFT

D.2 Changing the Location of Point

M

m (Calendar mode)

AC.10.1 Commands Displaying Diary Entries

M (Calendar mode)

AC.8 Phases of the Moon

m (Dired)

AB.6 Dired Marks vs. Flags

M (Dired)

AB.7 Operating on Files

m (Rmail)

AA.10 Sending Replies

M-!

AC.15.1 Single Shell Commands

M-$

L.4 Checking and Correcting Spelling

M-$ (Dired)

AB.13 Hiding Subdirectories

M-%

K.7.4 Query Replace

M-'

X.3 Controlling Abbrev Expansion

M-*

W.2.5 Finding a Tag

M-,

W.2.6 Searching and Replacing with Tags Tables

M--

D.10 Numeric Arguments

M-- M-c

L.3 Case Conversion

M-- M-l

L.3 Case Conversion

M-- M-u

L.3 Case Conversion

M-.

W.2.5 Finding a Tag

M-/

X.6 Dynamic Abbrev Expansion

M-1

D.10 Numeric Arguments

M-;

U.5.1 Comment Commands

M-<

D.2 Changing the Location of Point

M-< (Calendar mode)

AC.1.2 Beginning or End of Week, Month or Year

M-=

D.9 Cursor Position Information

M-= (Calendar mode)

AC.3 Counting Days

M-= (Dired)

AB.10 File Comparison with Dired

M->

D.2 Changing the Location of Point

M-> (Calendar mode)

AC.1.2 Beginning or End of Week, Month or Year

M-? (Nroff mode)

T.10 Nroff Mode

M-? (Shell mode)

AC.15.3 Shell Mode

M-@

T.1 Words

M-\

H.7.1 Deletion

M-^

S.1 Indentation Commands and Techniques

M-^ (Fortran mode)

U.12.2.1 Fortran Indentation and Filling Commands

M-`

B.4 The Menu Bar

M-a

T.2 Sentences

M-a (Calendar mode)

AC.1.2 Beginning or End of Week, Month or Year

M-b

T.1 Words

M-c

T.6 Case Conversion Commands

M-colon

V.8 Evaluating Emacs-Lisp Expressions

M-d

T.1 Words

M-DEL

T.1 Words

M-Drag-Mouse-1

P.2 Secondary Selection

M-e

T.2 Sentences

M-e (Calendar mode)

AC.1.2 Beginning or End of Week, Month or Year

M-f

T.1 Words

M-g b (Enriched mode)

T.11.4 Faces in Formatted Text

M-g d (Enriched mode)

T.11.4 Faces in Formatted Text

M-g i (Enriched mode)

T.11.4 Faces in Formatted Text

M-g l (Enriched mode)

T.11.4 Faces in Formatted Text

M-g o (Enriched mode)

T.11.4 Faces in Formatted Text

M-g u (Enriched mode)

T.11.4 Faces in Formatted Text

M-h

T.3 Paragraphs

M-i

S.2 Tab Stops

M-j c (Enriched mode)

T.11.7 Justification in Formatted Text

M-j f (Enriched mode)

T.11.7 Justification in Formatted Text

M-j l (Enriched mode)

T.11.7 Justification in Formatted Text

M-j r (Enriched mode)

T.11.7 Justification in Formatted Text

M-j u (Enriched mode)

T.11.7 Justification in Formatted Text

M-k

T.2 Sentences

M-l

T.6 Case Conversion Commands

M-m

S.1 Indentation Commands and Techniques

M-m (Rmail)

AA.10 Sending Replies

M-Mouse-1

P.2 Secondary Selection

M-Mouse-2

P.2 Secondary Selection

M-Mouse-3

P.2 Secondary Selection

M-n (minibuffer history)

E.4 Minibuffer History

M-n (Nroff mode)

T.10 Nroff Mode

M-n (Rmail)

AA.3 Moving Among Messages

M-n (Shell mode)

AC.15.4.1 Shell History Ring

M-p (minibuffer history)

E.4 Minibuffer History

M-p (Nroff mode)

T.10 Nroff Mode

M-p (Rmail)

AA.3 Moving Among Messages

M-p (Shell mode)

AC.15.4.1 Shell History Ring

M-q

T.5.3 Explicit Fill Commands

M-q (C mode)

U.11.4 Other Commands for C Mode

M-q (Fortran mode)

U.12.2.1 Fortran Indentation and Filling Commands

M-r

D.2 Changing the Location of Point

M-r (minibuffer history)

E.4 Minibuffer History

M-r (Shell mode)

AC.15.4.1 Shell History Ring

M-S (Enriched mode)

T.11.7 Justification in Formatted Text

M-s (Gnus Summary mode)

AC.14.3 Summary of Gnus Commands

M-s (minibuffer history)

E.4 Minibuffer History

M-s (Rmail)

AA.3 Moving Among Messages

M-s (Shell mode)

AC.15.4.1 Shell History Ring

M-s (Text mode)

T.5.3 Explicit Fill Commands

M-SPC

H.7.1 Deletion

M-t

L.2 Transposing Text

M-TAB

U.8 Completion for Symbol Names

M-TAB (customization buffer)

AD.2.2.2 Changing an Option

M-TAB (Mail mode)

Z.4.2 Mail Header Editing

M-TAB (Picture mode)

Y.3 Picture Mode Tabs

M-TAB (Text mode)

T.7 Text Mode

M-u

T.6 Case Conversion Commands

M-v

J.6 Scrolling

M-v (Calendar mode)

AC.2 Scrolling in the Calendar

M-w

H.8.1 The Kill Ring

M-x

F. Running Commands by Name

M-y

H.8.3 Yanking Earlier Kills

M-z

H.7.3 Other Kill Commands

M-{

T.3 Paragraphs

M-{ (Calendar mode)

AC.1.1 Motion by Standard Lengths of Time

M-|

AC.15.1 Single Shell Commands

M-}

T.3 Paragraphs

M-} (Calendar mode)

AC.1.1 Motion by Standard Lengths of Time

M-~

M.3 Saving Files

Mouse-1

P.1 Mouse Commands for Editing

Mouse-1 (mode line)

P.6 Mode Line Mouse Commands

Mouse-2

P.1 Mouse Commands for Editing

Mouse-2 (mode line)

P.6 Mode Line Mouse Commands

Mouse-2 (selection)

P.4 Following References with the Mouse

Mouse-3

P.1 Mouse Commands for Editing

Mouse-3 (mode line)

P.6 Mode Line Mouse Commands

N

n (Gnus)

AC.14.3 Summary of Gnus Commands

n (Rmail)

AA.3 Moving Among Messages

NEXT

J.6 Scrolling

O

o (Calendar mode)

AC.1.3 Specified Dates

O (Dired)

AB.7 Operating on Files

o (Dired)

AB.5 Visiting Files in Dired

o (Rmail)

AA.7 Copying Messages Out to Files

P

p (Calendar mode)

AC.9.2 Converting To Other Calendars

P (Dired)

AB.7 Operating on Files

p (Gnus)

AC.14.3 Summary of Gnus Commands

p (Rmail)

AA.3 Moving Among Messages

p d (Calendar mode)

AC.4 Miscellaneous Calendar Commands

PAGEDOWN

J.6 Scrolling

PAGEUP

J.6 Scrolling

PRIOR

J.6 Scrolling

Q

q (Calendar mode)

AC.4 Miscellaneous Calendar Commands

Q (Dired)

AB.7 Operating on Files

q (Gnus Group mode)

AC.14.3 Summary of Gnus Commands

Q (Rmail summary)

AA.11.2 Editing in Summaries

q (Rmail summary)

AA.11.2 Editing in Summaries

q (Rmail)

AA.1 Basic Concepts of Rmail

R

R (Dired)

AB.7 Operating on Files

r (Rmail)

AA.10 Sending Replies

RET

D.1 Inserting Text

RET (Dired)

AB.5 Visiting Files in Dired

RET (Occur mode)

K.8 Other Search-and-Loop Commands

RET (Shell mode)

AC.15.3 Shell Mode

RIGHT

D.2 Changing the Location of Point

S

S (Calendar mode)

AC.7 Times of Sunrise and Sunset

s (Calendar mode)

AC.10.1 Commands Displaying Diary Entries

S (Dired)

AB.7 Operating on Files

s (Dired)

AB.14 Updating the Dired Buffer

s (Gnus Summary mode)

AC.14.3 Summary of Gnus Commands

s (Rmail)

AA.1 Basic Concepts of Rmail

S-Mouse-1

P.12 Setting Frame Parameters

S-Mouse-2

U.7 Hideshow minor mode

S-Mouse-3 (FFAP)

AC.28.3 Finding Files and URLs at Point

S-TAB (customization buffer)

AD.2.2.2 Changing an Option

S-TAB (Help mode)

G.7 Help Mode Commands

SPC

E.3.2 Completion Commands

SPC (Calendar mode)

AC.4 Miscellaneous Calendar Commands

SPC (Dired)

AB.2 Navigation in the Dired Buffer

SPC (Gnus)

AC.14.3 Summary of Gnus Commands

SPC (Rmail)

AA.2 Scrolling Within a Message

T

t (Calendar mode)

AC.5 LaTeX Calendar

t (Rmail)

AA.13 Display of Messages

TAB

S. Indentation

TAB (and major modes)

R. Major Modes

TAB (completion)

E.3.1 Completion Example

TAB (customization buffer)

AD.2.2.2 Changing an Option

TAB (GUD)

V.5.3 Commands of GUD

TAB (Help mode)

G.7 Help Mode Commands

TAB (programming modes)

U.3.1 Basic Program Indentation Commands

TAB (Shell mode)

AC.15.3 Shell Mode

TAB (Text mode)

T.7 Text Mode

U

u (Calendar mode)

AC.6 Holidays

u (Dired deletion)

AB.3 Deleting Files with Dired

u (Dired)

AB.6 Dired Marks vs. Flags

u (Gnus Group mode)

AC.14.3 Summary of Gnus Commands

u (Rmail)

AA.4 Deleting Messages

UP

D.2 Changing the Location of Point

V

v (Dired)

AB.5 Visiting Files in Dired

W

w (Rmail)

AA.7 Copying Messages Out to Files

X

x (Calendar mode)

AC.6 Holidays

X (Dired)

AB.8 Shell Commands in Dired

x (Dired)

AB.3 Deleting Files with Dired

x (Rmail)

AA.4 Deleting Messages

Z

Z (Dired)

AB.7 Operating on Files

Jump to:

! " # $ % & * + . < = > ^ ~
A B C D E F G H I J K L M N O P Q R S T U V W X Z

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Command-Line Options Index

Jump to:

+ -

Index Entry

Section

+

+linenum

AE.1 Action Arguments

-

--background-color

AE.8 Window Color Options

--batch

AE.2 Initial Options

--border-color

AE.8 Window Color Options

--border-width

AE.10 Internal and External Borders

--cursor-color

AE.8 Window Color Options

--debug-init

AE.2 Initial Options

--display

AE.2 Initial Options

--eval

AE.1 Action Arguments

--execute

AE.1 Action Arguments

--file

AE.1 Action Arguments

--font

AE.7 Font Specification Options

--foreground-color

AE.8 Window Color Options

--funcall

AE.1 Action Arguments

--geometry

AE.9 Options for Window Geometry

--icon-type

AE.12 Icons

--iconic

AE.12 Icons

--insert

AE.1 Action Arguments

--internal-border

AE.10 Internal and External Borders

--kill

AE.1 Action Arguments

--load

AE.1 Action Arguments

--mouse-color

AE.8 Window Color Options

--multibyte

AE.2 Initial Options

--name

AE.13 X Resources

--no-init-file

AE.2 Initial Options

--no-site-file

AE.2 Initial Options

--no-windows

AE.2 Initial Options

--reverse-video

AE.8 Window Color Options

--terminal

AE.2 Initial Options

--title

AE.11 Frame Titles

--unibyte

AE.2 Initial Options

--user

AE.2 Initial Options

--visit

AE.1 Action Arguments

--xrm

AE.13 X Resources

-bd

AE.8 Window Color Options

-bg

AE.8 Window Color Options

-bw

AE.10 Internal and External Borders

-cr

AE.8 Window Color Options

-d

AE.2 Initial Options

-f

AE.1 Action Arguments

-fg

AE.8 Window Color Options

-fn

AE.7 Font Specification Options

-g

AE.9 Options for Window Geometry

-i

AE.12 Icons

-ib

AE.10 Internal and External Borders

-l

AE.1 Action Arguments

-ms

AE.8 Window Color Options

-nw

AE.2 Initial Options

-q

AE.2 Initial Options

-r

AE.8 Window Color Options

-rv

AE.8 Window Color Options

-t

AE.2 Initial Options

-T

AE.11 Frame Titles

-u

AE.2 Initial Options

Jump to:

+ -

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Command and Function Index

Jump to:

2 5
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

Index Entry

Section

2

2C-associate-buffer

AC.23 Two-Column Editing

2C-dissociate

AC.23 Two-Column Editing

2C-merge

AC.23 Two-Column Editing

2C-newline

AC.23 Two-Column Editing

2C-split

AC.23 Two-Column Editing

2C-two-columns

AC.23 Two-Column Editing

5

5x5

AC.30 Other Amusements

A

abbrev-mode

X.1 Abbrev Concepts

abbrev-prefix-mark

X.3 Controlling Abbrev Expansion

abort-recursive-edit

AD.8 Quitting and Aborting

add-change-log-entry-other-window

W.1 Change Logs

add-global-abbrev

X.2 Defining Abbrevs

add-mode-abbrev

X.2 Defining Abbrevs

add-name-to-file

M.10 Miscellaneous File Operations

add-untranslated-filesystem

AH.4 Text Files and Binary Files

american-calendar

AC.10.3 Date Formats

append-next-kill

H.8.2 Appending Kills

append-to-buffer

H.9 Accumulating Text

append-to-file

H.9 Accumulating Text

append-to-register

I.2 Saving Text in Registers

apply-macro-to-region-lines

AD.3.1 Basic Use

appt-add

AC.11 Appointments

appt-delete

AC.11 Appointments

appt-make-list

AC.11 Appointments

apropos

G.4 Apropos

apropos-command

G.4 Apropos

apropos-documentation

G.4 Apropos

apropos-value

G.4 Apropos

apropos-variable

G.4 Apropos

ask-user-about-lock

M.3.2 Protection against Simultaneous Editing

auto-compression-mode

M.11 Accessing Compressed Files

auto-fill-mode

T.5.1 Auto Fill Mode

auto-image-file-mode

M.16 Convenience Features for Finding Files

auto-lower-mode

P.12 Setting Frame Parameters

auto-raise-mode

P.12 Setting Frame Parameters

auto-revert-mode

M.4 Reverting a Buffer

auto-save-mode

M.5.2 Controlling Auto-Saving

B

back-to-indentation

S.1 Indentation Commands and Techniques

backward-char

D.2 Changing the Location of Point

backward-kill-sentence

T.2 Sentences

backward-kill-sexp

U.4.1 Expressions with Balanced Parentheses

backward-kill-word

T.1 Words

backward-list

U.4.2 Moving in the Parenthesis Structure

backward-page

T.4 Pages

backward-paragraph

T.3 Paragraphs

backward-sentence

T.2 Sentences

backward-sexp

U.4.1 Expressions with Balanced Parentheses

backward-text-line

T.10 Nroff Mode

backward-up-list

U.4.2 Moving in the Parenthesis Structure

backward-word

T.1 Words

balance-windows

O.6 Deleting and Rearranging Windows

beginning-of-buffer

D.2 Changing the Location of Point

beginning-of-defun

U.2.2 Moving by Defuns

beginning-of-line

D.2 Changing the Location of Point

binary-overwrite-mode

AD.1 Minor Modes

blackbox

AC.30 Other Amusements

blink-cursor-mode

J.13 Displaying the Cursor

bookmark-delete

I.7 Bookmarks

bookmark-insert

I.7 Bookmarks

bookmark-insert-location

I.7 Bookmarks

bookmark-jump

I.7 Bookmarks

bookmark-jump

I.7 Bookmarks

bookmark-load

I.7 Bookmarks

bookmark-save

I.7 Bookmarks

bookmark-set

I.7 Bookmarks

bookmark-set

I.7 Bookmarks

bookmark-write

I.7 Bookmarks

browse-url

AC.28.1 Following URLs

browse-url-at-mouse

AC.28.1 Following URLs

browse-url-at-point

AC.28.1 Following URLs

bs-show

N.7.3 Customizing Buffer Menus

buffer-menu

N.5 Operating on Several Buffers

C

c-backslash-region

U.11.4 Other Commands for C Mode

c-backward-conditional

U.11.1 C Mode Motion Commands

c-backward-into-nomenclature

U.11.1 C Mode Motion Commands

c-beginning-of-statement

U.11.1 C Mode Motion Commands

c-electric-backspace

U.1 Major Modes for Programming Languages

c-end-of-statement

U.11.1 C Mode Motion Commands

c-fill-paragraph

U.11.4 Other Commands for C Mode

c-forward-conditional

U.11.1 C Mode Motion Commands

c-forward-into-nomenclature

U.11.1 C Mode Motion Commands

c-indent-command

U.3.1 Basic Program Indentation Commands

c-indent-command

U.3.4 Commands for C Indentation

c-indent-defun

U.3.4 Commands for C Indentation

c-indent-exp

U.3.4 Commands for C Indentation

c-macro-expand

U.11.4 Other Commands for C Mode

c-mark-function

U.2.2 Moving by Defuns

c-scope-operator

U.11.2 Electric C Characters

c-set-style

U.3.5 Customizing C Indentation

c-show-syntactic-information

U.11.4 Other Commands for C Mode

c-toggle-auto-hungry-state

U.11.3 Hungry Delete Feature in C

c-toggle-auto-state

U.11.2 Electric C Characters

c-toggle-hungry-state

U.11.3 Hungry Delete Feature in C

c-up-conditional

U.11.1 C Mode Motion Commands

calendar

AC. The Calendar and the Diary

calendar-backward-day

AC.1.1 Motion by Standard Lengths of Time

calendar-backward-month

AC.1.1 Motion by Standard Lengths of Time

calendar-backward-week

AC.1.1 Motion by Standard Lengths of Time

calendar-beginning-of-month

AC.1.2 Beginning or End of Week, Month or Year

calendar-beginning-of-week

AC.1.2 Beginning or End of Week, Month or Year

calendar-beginning-of-year

AC.1.2 Beginning or End of Week, Month or Year

calendar-count-days-region

AC.3 Counting Days

calendar-cursor-holidays

AC.6 Holidays

calendar-end-of-month

AC.1.2 Beginning or End of Week, Month or Year

calendar-end-of-week

AC.1.2 Beginning or End of Week, Month or Year

calendar-end-of-year

AC.1.2 Beginning or End of Week, Month or Year

calendar-forward-day

AC.1.1 Motion by Standard Lengths of Time

calendar-forward-month

AC.1.1 Motion by Standard Lengths of Time

calendar-forward-week

AC.1.1 Motion by Standard Lengths of Time

calendar-forward-year

AC.1.1 Motion by Standard Lengths of Time

calendar-forward-year

AC.1.1 Motion by Standard Lengths of Time

calendar-goto-astro-day-number

AC.9.3 Converting From Other Calendars

calendar-goto-chinese-date

AC.9.3 Converting From Other Calendars

calendar-goto-coptic-date

AC.9.3 Converting From Other Calendars

calendar-goto-date

AC.1.3 Specified Dates

calendar-goto-ethiopic-date

AC.9.3 Converting From Other Calendars

calendar-goto-french-date

AC.9.3 Converting From Other Calendars

calendar-goto-hebrew-date

AC.9.3 Converting From Other Calendars

calendar-goto-islamic-date

AC.9.3 Converting From Other Calendars

calendar-goto-iso-date

AC.9.3 Converting From Other Calendars

calendar-goto-julian-date

AC.9.3 Converting From Other Calendars

calendar-goto-mayan-long-count-date

AC.9.4 Converting from the Mayan Calendar

calendar-goto-persian-date

AC.9.3 Converting From Other Calendars

calendar-goto-today

AC.1.3 Specified Dates

calendar-next-calendar-round-date

AC.9.4 Converting from the Mayan Calendar

calendar-next-haab-date

AC.9.4 Converting from the Mayan Calendar

calendar-next-tzolkin-date

AC.9.4 Converting from the Mayan Calendar

calendar-other-month

AC.1.3 Specified Dates

calendar-phases-of-moon

AC.8 Phases of the Moon

calendar-previous-haab-date

AC.9.4 Converting from the Mayan Calendar

calendar-previous-tzolkin-date

AC.9.4 Converting from the Mayan Calendar

calendar-print-astro-day-number

AC.9.2 Converting To Other Calendars

calendar-print-chinese-date

AC.9.2 Converting To Other Calendars

calendar-print-coptic-date

AC.9.2 Converting To Other Calendars

calendar-print-day-of-year

AC.4 Miscellaneous Calendar Commands

calendar-print-ethiopic-date

AC.9.2 Converting To Other Calendars

calendar-print-french-date

AC.9.2 Converting To Other Calendars

calendar-print-hebrew-date

AC.9.2 Converting To Other Calendars

calendar-print-islamic-date

AC.9.2 Converting To Other Calendars

calendar-print-iso-date

AC.9.2 Converting To Other Calendars

calendar-print-julian-date

AC.9.2 Converting To Other Calendars

calendar-print-mayan-date

AC.9.2 Converting To Other Calendars

calendar-print-persian-date

AC.9.2 Converting To Other Calendars

calendar-sunrise-sunset

AC.7 Times of Sunrise and Sunset

calendar-unmark

AC.6 Holidays

call-last-kbd-macro

AD.3.1 Basic Use

capitalize-word

T.6 Case Conversion Commands

cd

M.1 File Names

center-line

T.5.3 Explicit Fill Commands

change-log-merge

W.1 Change Logs

change-log-mode

W.1 Change Logs

change-log-redate

W.1 Change Logs

check-parens

U.4 Commands for Editing with Parentheses

choose-completion

E.3.2 Completion Commands

clean-buffer-list

N.4 Killing Buffers

clear-rectangle

H.10 Rectangles

clone-indirect-buffer

N.6 Indirect Buffers

clone-indirect-buffer-other-window

N.6 Indirect Buffers

codepage-setup

AH.6 International Support on MS-DOS

column-number-mode

J.10 Optional Mode Line Features

comint-bol-or-process-mark

AC.15.3 Shell Mode

comint-continue-subjob

AC.15.3 Shell Mode

comint-copy-old-input

AC.15.4.2 Shell History Copying

comint-delchar-or-maybe-eof

AC.15.3 Shell Mode

comint-delete-output

AC.15.3 Shell Mode

comint-dynamic-complete

AC.15.3 Shell Mode

comint-dynamic-list-filename...

AC.15.3 Shell Mode

comint-dynamic-list-input-ring

AC.15.3 Shell Mode

comint-get-next-from-history

AC.15.4.1 Shell History Ring

comint-interrupt-subjob

AC.15.3 Shell Mode

comint-kill-input

AC.15.3 Shell Mode

comint-magic-space

AC.15.4.3 Shell History References

comint-next-input

AC.15.4.1 Shell History Ring

comint-next-matching-input

AC.15.4.1 Shell History Ring

comint-next-prompt

AC.15.4.2 Shell History Copying

comint-previous-input

AC.15.4.1 Shell History Ring

comint-previous-matching-input

AC.15.4.1 Shell History Ring

comint-previous-prompt

AC.15.4.2 Shell History Copying

comint-quit-subjob

AC.15.3 Shell Mode

comint-run

AC.15.3 Shell Mode

comint-send-input

AC.15.3 Shell Mode

comint-show-maximum-output

AC.15.3 Shell Mode

comint-show-output

AC.15.3 Shell Mode

comint-stop-subjob

AC.15.3 Shell Mode

comint-strip-ctrl-m

AC.15.3 Shell Mode

comint-truncate-buffer

AC.15.3 Shell Mode

comint-write-output

AC.15.3 Shell Mode

comment-dwim

U.5.1 Comment Commands

comment-indent-new-line

U.5.2 Multiple Lines of Comments

comment-kill

U.5.1 Comment Commands

comment-region

U.5.2 Multiple Lines of Comments

comment-set-column

U.5.3 Options Controlling Comments

compare-windows

M.9 Comparing Files

compile

V.1 Running Compilations under Emacs

compile (MS-DOS)

AH.7 Subprocesses on MS-DOS

compile-goto-error

V.3 Compilation Mode

complete-symbol

U.8 Completion for Symbol Names

compose-mail

Z. Sending Mail

compose-mail-other-frame

Z. Sending Mail

compose-mail-other-window

Z. Sending Mail

copy-file

M.10 Miscellaneous File Operations

copy-rectangle-to-register

I.3 Saving Rectangles in Registers

copy-to-buffer

H.9 Accumulating Text

copy-to-register

I.2 Saving Text in Registers

count-lines-page

T.4 Pages

count-lines-region

D.9 Cursor Position Information

count-text-lines

T.10 Nroff Mode

cpp-highlight-buffer

U.11.4 Other Commands for C Mode

create-fontset-from-fontset-spec

Q.11 Defining fontsets

crisp-mode

AC.27 Emulation

customize

AD.2.2 Easy Customization Interface

customize-apropos

AD.2.2.4 Customizing Specific Items

customize-browse

AD.2.2.1 Customization Groups

customize-changed-options

AD.2.2.4 Customizing Specific Items

customize-customized

AD.2.2.4 Customizing Specific Items

customize-face

AD.2.2.4 Customizing Specific Items

customize-group

AD.2.2.4 Customizing Specific Items

customize-option

AD.2.2.4 Customizing Specific Items

customize-saved

AD.2.2.4 Customizing Specific Items

cwarn-mode

U.11.4 Other Commands for C Mode

D

dabbrev-completion

X.6 Dynamic Abbrev Expansion

dabbrev-expand

X.6 Dynamic Abbrev Expansion

dbx

V.5.1 Starting GUD

debug_print

AD.10.3 Checklist for Bug Reports

decipher

AC.30 Other Amusements

default-value

AD.2.4 Local Variables

define-abbrevs

X.5 Saving Abbrevs

define-key

AD.4.3 Local Keymaps

define-mail-abbrev

Z.3 Mail Aliases

define-mail-alias

Z.3 Mail Aliases

delete-backward-char

H.7.1 Deletion

delete-blank-lines

D.7 Blank Lines

delete-char

H.7.1 Deletion

delete-file

M.10 Miscellaneous File Operations

delete-frame

P.8 Frame Commands

delete-horizontal-space

H.7.1 Deletion

delete-indentation

S.1 Indentation Commands and Techniques

delete-matching-lines

K.8 Other Search-and-Loop Commands

delete-non-matching-lines

K.8 Other Search-and-Loop Commands

delete-other-frames

P.8 Frame Commands

delete-other-windows

O.6 Deleting and Rearranging Windows

delete-rectangle

H.10 Rectangles

delete-selection-mode

H.7 Deletion and Killing

delete-trailing-whitespace

J.5 Trailing Whitespace

delete-whitespace-rectangle

H.10 Rectangles

delete-window

O.6 Deleting and Rearranging Windows

describe-bindings

G.8 Other Help Commands

describe-categories

K.5 Syntax of Regular Expressions

describe-coding-system

Q.7 Coding Systems

describe-copying

G.8 Other Help Commands

describe-distribution

G.8 Other Help Commands

describe-function

G.3 Help by Command or Variable Name

describe-input-method

Q.5 Selecting an Input Method

describe-key

G.2 Documentation for a Key

describe-key-briefly

G.2 Documentation for a Key

describe-language-environment

Q.3 Language Environments

describe-mode

G.8 Other Help Commands

describe-no-warranty

G.8 Other Help Commands

describe-project

G.8 Other Help Commands

describe-syntax

AD.6 The Syntax Table

desktop-save

AC.25 Saving Emacs Sessions

diary

AC.10.1 Commands Displaying Diary Entries

diary-anniversary

AC.10.5 Special Diary Entries

diary-block

AC.10.5 Special Diary Entries

diary-cyclic

AC.10.5 Special Diary Entries

diary-float

AC.10.5 Special Diary Entries

diary-mail-entries

AC.10.1 Commands Displaying Diary Entries

diff

M.9 Comparing Files

diff-backup

M.9 Comparing Files

diff-mode

M.9 Comparing Files

digit-argument

D.10 Numeric Arguments

dired

AB.1 Entering Dired

dired-backup-diff

AB.10 File Comparison with Dired

dired-change-marks

AB.6 Dired Marks vs. Flags

dired-clean-directory

AB.4 Flagging Many Files at Once

dired-create-directory

AB.7 Operating on Files

dired-diff

AB.10 File Comparison with Dired

dired-display-file

AB.5 Visiting Files in Dired

dired-do-byte-compile

AB.7 Operating on Files

dired-do-chgrp

AB.7 Operating on Files

dired-do-chmod

AB.7 Operating on Files

dired-do-chown

AB.7 Operating on Files

dired-do-compress

AB.7 Operating on Files

dired-do-copy

AB.7 Operating on Files

dired-do-copy-regexp

AB.9 Transforming File Names in Dired

dired-do-delete

AB.7 Operating on Files

dired-do-flagged-delete

AB.3 Deleting Files with Dired

dired-do-hardlink

AB.7 Operating on Files

dired-do-hardlink-regexp

AB.9 Transforming File Names in Dired

dired-do-kill-lines

AB.14 Updating the Dired Buffer

dired-do-load

AB.7 Operating on Files

dired-do-print

AB.7 Operating on Files

dired-do-query-replace-regexp

AB.7 Operating on Files

dired-do-redisplay

AB.14 Updating the Dired Buffer

dired-do-rename

AB.7 Operating on Files

dired-do-rename-regexp

AB.9 Transforming File Names in Dired

dired-do-search

AB.7 Operating on Files

dired-do-shell-command

AB.8 Shell Commands in Dired

dired-do-symlink

AB.7 Operating on Files

dired-do-symlink-regexp

AB.9 Transforming File Names in Dired

dired-do-toggle

AB.6 Dired Marks vs. Flags

dired-downcase

AB.9 Transforming File Names in Dired

dired-find-alternate-file

AB.5 Visiting Files in Dired

dired-find-file

AB.5 Visiting Files in Dired

dired-find-file-other-window

AB.5 Visiting Files in Dired

dired-flag-auto-save-files

AB.4 Flagging Many Files at Once

dired-flag-backup-files

AB.4 Flagging Many Files at Once

dired-flag-file-deletion

AB.3 Deleting Files with Dired

dired-flag-files-regexp

AB.4 Flagging Many Files at Once

dired-flag-garbage-files

AB.4 Flagging Many Files at Once

dired-hide-all

AB.13 Hiding Subdirectories

dired-hide-subdir

AB.13 Hiding Subdirectories

dired-mark

AB.6 Dired Marks vs. Flags

dired-mark-directories

AB.6 Dired Marks vs. Flags

dired-mark-executables

AB.6 Dired Marks vs. Flags

dired-mark-files-containing-regexp

AB.6 Dired Marks vs. Flags

dired-mark-files-regexp

AB.6 Dired Marks vs. Flags

dired-mark-subdir-files

AB.6 Dired Marks vs. Flags

dired-mark-symlinks

AB.6 Dired Marks vs. Flags

dired-maybe-insert-subdir

AB.11 Subdirectories in Dired

dired-mouse-find-file-other-window

AB.5 Visiting Files in Dired

dired-next-dirline

AB.12 Moving Over Subdirectories

dired-next-marked-file

AB.6 Dired Marks vs. Flags

dired-next-subdir

AB.12 Moving Over Subdirectories

dired-other-frame

AB.1 Entering Dired

dired-other-window

AB.1 Entering Dired

dired-prev-dirline

AB.12 Moving Over Subdirectories

dired-prev-marked-file

AB.6 Dired Marks vs. Flags

dired-prev-subdir

AB.12 Moving Over Subdirectories

dired-sort-toggle-or-edit

AB.14 Updating the Dired Buffer

dired-tree-down

AB.12 Moving Over Subdirectories

dired-tree-up

AB.12 Moving Over Subdirectories

dired-undo

AB.6 Dired Marks vs. Flags

dired-unmark

AB.6 Dired Marks vs. Flags

dired-unmark-all-files

AB.6 Dired Marks vs. Flags

dired-unmark-all-marks

AB.6 Dired Marks vs. Flags

dired-unmark-backward

AB.6 Dired Marks vs. Flags

dired-up-directory

AB.5 Visiting Files in Dired

dired-upcase

AB.9 Transforming File Names in Dired

dired-view-file

AB.5 Visiting Files in Dired

dirs

AC.15.5 Directory Tracking

dirtrack-mode

AC.15.5 Directory Tracking

disable-command

AD.4.11 Disabling Commands

display-time

J.10 Optional Mode Line Features

dissociated-press

AC.29 Dissociated Press

do-applescript

AG.6 Mac-Specific Lisp Functions

do-auto-save

M.5.2 Controlling Auto-Saving

doctor

AD.9.9 Help for Total Frustration

down-list

U.4.2 Moving in the Parenthesis Structure

downcase-region

T.6 Case Conversion Commands

downcase-word

T.6 Case Conversion Commands

dunnet

AC.30 Other Amusements

E

edit-abbrevs

X.4 Examining and Editing Abbrevs

edit-kbd-macro

AD.3.1 Basic Use

edit-picture

Y. Editing Pictures

edit-tab-stops

S.2 Tab Stops

edit-tab-stops-note-changes

S.2 Tab Stops

edt-emulation-off

AC.27 Emulation

edt-emulation-on

AC.27 Emulation

eldoc-mode

U.6.3 Emacs Lisp Documentation Lookup

electric-nroff-mode

T.10 Nroff Mode

emacs-lisp-mode

V.8 Evaluating Emacs-Lisp Expressions

emacs-version

AD.10.2 Understanding Bug Reporting

emerge-auto-advance-mode

W.3.2 Submodes of Emerge

emerge-buffers

W.3.1 Overview of Emerge

emerge-buffers-with-ancestor

W.3.1 Overview of Emerge

emerge-files

W.3.1 Overview of Emerge

emerge-files-with-ancestor

W.3.1 Overview of Emerge

emerge-skip-prefers-mode

W.3.2 Submodes of Emerge

enable-command

AD.4.11 Disabling Commands

enable-flow-control

AD.9.5 Spontaneous Entry to Incremental Search

enable-flow-control-on

AD.9.5 Spontaneous Entry to Incremental Search

enable-local-eval

AD.2.5 Local Variables in Files

enable-local-variables

AD.2.5 Local Variables in Files

end-kbd-macro

AD.3.1 Basic Use

end-of-buffer

D.2 Changing the Location of Point

end-of-defun

U.2.2 Moving by Defuns

end-of-line

D.2 Changing the Location of Point

enlarge-window

O.6 Deleting and Rearranging Windows

enlarge-window-horizontally

O.6 Deleting and Rearranging Windows

enriched-mode

T.11.1 Requesting to Edit Formatted Text

eshell

AC.15 Running Shell Commands from Emacs

european-calendar

AC.10.3 Date Formats

eval-current-buffer

V.8 Evaluating Emacs-Lisp Expressions

eval-defun

V.8 Evaluating Emacs-Lisp Expressions

eval-expression

V.8 Evaluating Emacs-Lisp Expressions

eval-last-sexp

V.8 Evaluating Emacs-Lisp Expressions

eval-region

V.8 Evaluating Emacs-Lisp Expressions

exchange-point-and-mark

H.1 Setting the Mark

execute-extended-command

F. Running Commands by Name

exit-calendar

AC.4 Miscellaneous Calendar Commands

exit-recursive-edit

AC.26 Recursive Editing Levels

expand-abbrev

X.3 Controlling Abbrev Expansion

expand-mail-aliases

Z.3 Mail Aliases

expand-region-abbrevs

X.3 Controlling Abbrev Expansion

F

f90-mode

U.12 Fortran Mode

facemenu-remove-all

T.11.3 Editing Format Information

facemenu-remove-face-props

T.11.3 Editing Format Information

facemenu-set-background

T.11.5 Colors in Formatted Text

facemenu-set-bold

T.11.4 Faces in Formatted Text

facemenu-set-bold-italic

T.11.4 Faces in Formatted Text

facemenu-set-default

T.11.4 Faces in Formatted Text

facemenu-set-face

T.11.4 Faces in Formatted Text

facemenu-set-foreground

T.11.5 Colors in Formatted Text

facemenu-set-italic

T.11.4 Faces in Formatted Text

facemenu-set-underline

T.11.4 Faces in Formatted Text

ff-find-related-file

U.11.4 Other Commands for C Mode

ffap

AC.28.3 Finding Files and URLs at Point

ffap-dired-at-point

AC.28.3 Finding Files and URLs at Point

ffap-menu

AC.28.3 Finding Files and URLs at Point

ffap-mode

AC.28.3 Finding Files and URLs at Point

ffap-next

AC.28.3 Finding Files and URLs at Point

file-cache-add-directory

M.15 File Name Cache

file-cache-minibuffer-complete

M.15 File Name Cache

fill-individual-paragraphs

T.5.4 The Fill Prefix

fill-nonuniform-paragraphs

T.5.4 The Fill Prefix

fill-paragraph

T.5.3 Explicit Fill Commands

fill-region

T.5.3 Explicit Fill Commands

fill-region-as-paragraph

T.5.3 Explicit Fill Commands

find-alternate-file

M.2 Visiting Files

find-dired

AB.15 Dired and find

find-file

M.2 Visiting Files

find-file-at-point

AC.28.3 Finding Files and URLs at Point

find-file-literally

M.2 Visiting Files

find-file-other-frame

M.2 Visiting Files

find-file-other-window

M.2 Visiting Files

find-file-read-only

M.2 Visiting Files

find-file-read-only-other-frame

P.7 Creating Frames

find-function

AC.28.4 Finding Function and Variable Definitions

find-function-on-key

AC.28.4 Finding Function and Variable Definitions

find-grep-dired

AB.15 Dired and find

find-name-dired

AB.15 Dired and find

find-tag

W.2.5 Finding a Tag

find-tag-other-frame

W.2.5 Finding a Tag

find-tag-other-window

W.2.5 Finding a Tag

find-tag-regexp

W.2.5 Finding a Tag

find-variable

AC.28.4 Finding Function and Variable Definitions

finder-by-keyword

G.5 Keyword Search for Lisp Libraries

flush-lines

K.8 Other Search-and-Loop Commands

flyspell-mode

L.4 Checking and Correcting Spelling

foldout-exit-fold

T.8.5 Folding Editing

foldout-zoom-subtree

T.8.5 Folding Editing

follow-mode

J.8 Follow Mode

font-lock-add-keywords

J.2 Font Lock mode

font-lock-mode

J.2 Font Lock mode

font-lock-remove-keywords

J.2 Font Lock mode

format-find-file

T.11.9 Forcing Enriched Mode

fortran-auto-fill-mode

U.12.4 Fortran Auto Fill Mode

fortran-column-ruler

U.12.5 Checking Columns in Fortran

fortran-comment-region

U.12.3 Fortran Comments

fortran-indent-subprogram

U.12.2.1 Fortran Indentation and Filling Commands

fortran-join-line

U.12.2.1 Fortran Indentation and Filling Commands

fortran-mode

U.12 Fortran Mode

fortran-next-statement

U.12.1 Motion Commands

fortran-previous-statement

U.12.1 Motion Commands

fortran-split-line

U.12.2.1 Fortran Indentation and Filling Commands

fortran-strip-sequence-nos

U.12.5 Checking Columns in Fortran

fortran-window-create

U.12.5 Checking Columns in Fortran

fortran-window-create-momentarily

U.12.5 Checking Columns in Fortran

fortune-to-signature

Z.5 Mail Amusements

forward-char

D.2 Changing the Location of Point

forward-list

U.4.2 Moving in the Parenthesis Structure

forward-page

T.4 Pages

forward-paragraph

T.3 Paragraphs

forward-sentence

T.2 Sentences

forward-sexp

U.4.1 Expressions with Balanced Parentheses

forward-text-line

T.10 Nroff Mode

forward-word

T.1 Words

frame-configuration-to-register

I.4 Saving Window Configurations in Registers

G

gdb

V.5.1 Starting GUD

getenv

AE.5 Environment Variables

glasses-mode

U.9 Glasses minor mode

global-auto-revert-mode

M.4 Reverting a Buffer

global-cwarn-mode

U.11.4 Other Commands for C Mode

global-font-lock-mode

J.2 Font Lock mode

global-set-key

AD.4.5 Changing Key Bindings Interactively

global-unset-key

AD.4.5 Changing Key Bindings Interactively

gnus

AC.14 Gnus

gnus-group-exit

AC.14.3 Summary of Gnus Commands

gnus-group-kill-group

AC.14.3 Summary of Gnus Commands

gnus-group-list-all-groups

AC.14.3 Summary of Gnus Commands

gnus-group-list-groups

AC.14.3 Summary of Gnus Commands

gnus-group-next-group

AC.14.3 Summary of Gnus Commands

gnus-group-next-unread-group

AC.14.3 Summary of Gnus Commands

gnus-group-prev-group

AC.14.3 Summary of Gnus Commands

gnus-group-prev-unread-group

AC.14.3 Summary of Gnus Commands

gnus-group-read-group

AC.14.3 Summary of Gnus Commands

gnus-group-unsubscribe-current-group

AC.14.3 Summary of Gnus Commands

gnus-summary-isearch-article

AC.14.3 Summary of Gnus Commands

gnus-summary-next-subject

AC.14.3 Summary of Gnus Commands

gnus-summary-next-unread-article

AC.14.3 Summary of Gnus Commands

gnus-summary-prev-page

AC.14.3 Summary of Gnus Commands

gnus-summary-prev-subject

AC.14.3 Summary of Gnus Commands

gnus-summary-prev-unread-article

AC.14.3 Summary of Gnus Commands

gnus-summary-search-article-forward

AC.14.3 Summary of Gnus Commands

gomoku

AC.30 Other Amusements

goto-address

AC.28.2 Activating URLs

goto-char

D.2 Changing the Location of Point

goto-line

D.2 Changing the Location of Point

grep

V.2 Searching with Grep under Emacs

grep (MS-DOS)

AH.7 Subprocesses on MS-DOS

grep-find

V.2 Searching with Grep under Emacs

gud-cont

V.5.3 Commands of GUD

gud-def

V.5.4 GUD Customization

gud-down

V.5.3 Commands of GUD

gud-finish

V.5.3 Commands of GUD

gud-gdb-complete-command

V.5.3 Commands of GUD

gud-next

V.5.3 Commands of GUD

gud-refresh

V.5.3 Commands of GUD

gud-remove

V.5.3 Commands of GUD

gud-step

V.5.3 Commands of GUD

gud-stepi

V.5.3 Commands of GUD

gud-tbreak

V.5.3 Commands of GUD

gud-up

V.5.3 Commands of GUD

H

handwrite

AC.19 PostScript Hardcopy

hanoi

AC.30 Other Amusements

help-command

G. Help

help-for-help

G. Help

help-next-ref

G.7 Help Mode Commands

help-previous-ref

G.7 Help Mode Commands

help-with-tutorial

D. Basic Editing Commands

hi-lock-find-patterns

J.4 Interactive Highlighting by Matching

hi-lock-mode

J.4 Interactive Highlighting by Matching

hi-lock-write-interactive-patterns

J.4 Interactive Highlighting by Matching

hide-body

T.8.3 Outline Visibility Commands

hide-entry

T.8.3 Outline Visibility Commands

hide-ifdef-mode

U.11.4 Other Commands for C Mode

hide-leaves

T.8.3 Outline Visibility Commands

hide-other

T.8.3 Outline Visibility Commands

hide-sublevels

T.8.3 Outline Visibility Commands

hide-subtree

T.8.3 Outline Visibility Commands

highlight-changes-mode

J.3 Highlight Changes Mode

highlight-lines-matching-regexp

J.4 Interactive Highlighting by Matching

highlight-regexp

J.4 Interactive Highlighting by Matching

hl-line-mode

J.13 Displaying the Cursor

holidays

AC.6 Holidays

how-many

K.8 Other Search-and-Loop Commands

hs-hide-all

U.7 Hideshow minor mode

hs-hide-block

U.7 Hideshow minor mode

hs-hide-level

U.7 Hideshow minor mode

hs-minor-mode

U.7 Hideshow minor mode

hs-minor-mode

U.7 Hideshow minor mode

hs-show-all

U.7 Hideshow minor mode

hs-show-block

U.7 Hideshow minor mode

hs-show-region

U.7 Hideshow minor mode

I

icomplete-mode

E.3.4 Completion Options

iconify-or-deiconify-frame

P.8 Frame Commands

ielm

V.9 Lisp Interaction Buffers

imenu

U.2.3 Imenu

imenu-add-menubar-index

U.2.3 Imenu

increase-left-margin

T.11.6 Indentation in Formatted Text

increment-register

I.5 Keeping Numbers in Registers

indent-code-rigidly

U.3.2 Indenting Several Lines

indent-for-tab-command

U.3.1 Basic Program Indentation Commands

indent-line-function

U.3.1 Basic Program Indentation Commands

indent-region

S.1 Indentation Commands and Techniques

indent-relative

S.1 Indentation Commands and Techniques

indent-rigidly

S.1 Indentation Commands and Techniques

indent-sexp

U.3.2 Indenting Several Lines

info

G.8 Other Help Commands

Info-goto-emacs-command-node

G.8 Other Help Commands

Info-goto-emacs-key-command-node

G.8 Other Help Commands

info-lookup-file

U.6.1 Info Documentation Lookup

info-lookup-symbol

U.6.1 Info Documentation Lookup

insert-abbrevs

X.5 Saving Abbrevs

insert-anniversary-diary-entry

AC.10.5 Special Diary Entries

insert-block-diary-entry

AC.10.5 Special Diary Entries

insert-cyclic-diary-entry

AC.10.5 Special Diary Entries

insert-diary-entry

AC.10.4 Commands to Add to the Diary

insert-file

M.10 Miscellaneous File Operations

insert-kbd-macro

AD.3.2 Naming and Saving Keyboard Macros

insert-monthly-diary-entry

AC.10.4 Commands to Add to the Diary

insert-register

I.2 Saving Text in Registers

insert-weekly-diary-entry

AC.10.4 Commands to Add to the Diary

insert-yearly-diary-entry

AC.10.4 Commands to Add to the Diary

inverse-add-global-abbrev

X.2 Defining Abbrevs

inverse-add-mode-abbrev

X.2 Defining Abbrevs

isearch-backward

K.1 Incremental Search

isearch-backward-regexp

K.4 Regular Expression Search

isearch-forward

K.1 Incremental Search

isearch-forward-regexp

K.4 Regular Expression Search

isearch-toggle-input-method

K.1 Incremental Search

isearch-toggle-specified-input-method

K.1 Incremental Search

iso-accents-mode

Q.13 Single-byte Character Set Support

iso-gtex2iso

T.9.4 TeX Mode Miscellany

iso-iso2gtex

T.9.4 TeX Mode Miscellany

iso-iso2tex

T.9.4 TeX Mode Miscellany

iso-tex2iso

T.9.4 TeX Mode Miscellany

ispell

L.4 Checking and Correcting Spelling

ispell-buffer

L.4 Checking and Correcting Spelling

ispell-complete-word

L.4 Checking and Correcting Spelling

ispell-kill-ispell

L.4 Checking and Correcting Spelling

ispell-message

Z.4.4 Mail Mode Miscellany

ispell-region

L.4 Checking and Correcting Spelling

ispell-word

L.4 Checking and Correcting Spelling

iswitchb-mode

N.7.2 Switching Between Buffers using Substrings

J

jdb

V.5.1 Starting GUD

jump-to-register

I.1 Saving Positions in Registers

just-one-space

H.7.1 Deletion

K

kbd-macro-query

AD.3.3 Executing Macros with Variations

keep-lines

K.8 Other Search-and-Loop Commands

keyboard-escape-quit

AD.8 Quitting and Aborting

keyboard-quit

AD.8 Quitting and Aborting

keyboard-translate

AD.5 Keyboard Translations

kill-all-abbrevs

X.2 Defining Abbrevs

kill-buffer

N.4 Killing Buffers

kill-buffer-and-window

O.6 Deleting and Rearranging Windows

kill-compilation

V.1 Running Compilations under Emacs

kill-line

H.7.2 Killing by Lines

kill-local-variable

AD.2.4 Local Variables

kill-rectangle

H.10 Rectangles

kill-region

H.7.3 Other Kill Commands

kill-ring-save

H.8.1 The Kill Ring

kill-sentence

T.2 Sentences

kill-sexp

U.4.1 Expressions with Balanced Parentheses

kill-some-buffers

N.4 Killing Buffers

kill-word

T.1 Words

L

latex-mode

T.9 TeX Mode

life

AC.30 Other Amusements

line-number-mode

J.10 Optional Mode Line Features

lisp-complete-symbol

U.8 Completion for Symbol Names

lisp-eval-defun

V.10 Running an External Lisp

lisp-interaction-mode

V.9 Lisp Interaction Buffers

lisp-mode

V.10 Running an External Lisp

list-abbrevs

X.4 Examining and Editing Abbrevs

list-bookmarks

I.7 Bookmarks

list-buffers

N.2 Listing Existing Buffers

list-calendar-holidays

AC.6 Holidays

list-coding-systems

Q.7 Coding Systems

list-colors-display

AE.8 Window Color Options

list-command-history

E.5 Repeating Minibuffer Commands

list-directory

M.8 File Directories

list-faces-display

J.1 Using Multiple Typefaces

list-holidays

AC.6 Holidays

list-input-methods

Q.5 Selecting an Input Method

list-matching-lines

K.8 Other Search-and-Loop Commands

list-tags

W.2.7 Tags Table Inquiries

list-text-properties-at

T.11.3 Editing Format Information

list-yahrzeit-dates

AC.9.3 Converting From Other Calendars

lm

AC.30 Other Amusements

load

V.7 Libraries of Lisp Code for Emacs

load-file

V.7 Libraries of Lisp Code for Emacs

load-library

V.7 Libraries of Lisp Code for Emacs

local-set-key

AD.4.5 Changing Key Bindings Interactively

local-unset-key

AD.4.5 Changing Key Bindings Interactively

locate

AB.15 Dired and find

locate-with-filter

AB.15 Dired and find

lpr-buffer

AC.18 Hardcopy Output

lpr-region

AC.18 Hardcopy Output

M

mac-file-name-to-posix

AG.6 Mac-Specific Lisp Functions

mail-attach-file

Z.4.4 Mail Mode Miscellany

mail-bcc

Z.4.2 Mail Header Editing

mail-cc

Z.4.2 Mail Header Editing

mail-complete

Z.4.2 Mail Header Editing

mail-fcc

Z.4.2 Mail Header Editing

mail-fill-yanked-message

Z.4.3 Citing Mail

mail-interactive-insert-alias

Z.3 Mail Aliases

mail-send

Z.4.1 Mail Sending

mail-send-and-exit

Z.4.1 Mail Sending

mail-signature

Z.4.4 Mail Mode Miscellany

mail-subject

Z.4.2 Mail Header Editing

mail-text

Z.4.4 Mail Mode Miscellany

mail-to

Z.4.2 Mail Header Editing

mail-yank-original

Z.4.3 Citing Mail

mail-yank-region

Z.4.3 Citing Mail

make-frame-command

P.7 Creating Frames

make-frame-on-display

P.10 Multiple Displays

make-indirect-buffer

N.6 Indirect Buffers

make-local-variable

AD.2.4 Local Variables

make-symbolic-link

M.10 Miscellaneous File Operations

make-variable-buffer-local

AD.2.4 Local Variables

Man-fontify-manpage

U.6.2 Man Page Lookup

manual-entry

U.6.2 Man Page Lookup

mark-calendar-holidays

AC.6 Holidays

mark-defun

U.2.2 Moving by Defuns

mark-diary-entries

AC.10.1 Commands Displaying Diary Entries

mark-page

T.4 Pages

mark-paragraph

T.3 Paragraphs

mark-sexp

U.4.1 Expressions with Balanced Parentheses

mark-whole-buffer

H.4 Commands to Mark Textual Objects

mark-word

T.1 Words

menu-bar-enable-clipboard

P.3 Using the Clipboard

minibuffer-complete

E.3.1 Completion Example

minibuffer-complete-word

E.3.2 Completion Commands

mode, auto-image-file

M.16 Convenience Features for Finding Files

mode25

AH.2 Display on MS-DOS

mode4350

AH.2 Display on MS-DOS

modify-face

AD.2.2.3 Customizing Faces

morse-region

AC.30 Other Amusements

mouse-avoidance-mode

P.19 Mouse Avoidance

mouse-buffer-menu

N.7.3 Customizing Buffer Menus

mouse-choose-completion

E.3.2 Completion Commands

mouse-save-then-click

P.1 Mouse Commands for Editing

mouse-secondary-save-then-kill

P.2 Secondary Selection

mouse-set-point

P.1 Mouse Commands for Editing

mouse-set-region

P.1 Mouse Commands for Editing

mouse-set-secondary

P.2 Secondary Selection

mouse-start-secondary

P.2 Secondary Selection

mouse-wheel-mode

P.14 Scrolling With "Wheeled" Mice

mouse-yank-at-click

P.1 Mouse Commands for Editing

mouse-yank-secondary

P.2 Secondary Selection

move-to-window-line

D.2 Changing the Location of Point

mpuz

AC.30 Other Amusements

msb-mode

N.7.3 Customizing Buffer Menus

msdos-set-mouse-buttons

AH.1 Keyboard and Mouse on MS-DOS

N

name-last-kbd-macro

AD.3.2 Naming and Saving Keyboard Macros

narrow-to-defun

AC.22 Narrowing

narrow-to-page

AC.22 Narrowing

narrow-to-region

AC.22 Narrowing

negative-argument

D.10 Numeric Arguments

newline

D.1 Inserting Text

newline-and-indent

U.3.1 Basic Program Indentation Commands

next-completion

E.3.2 Completion Commands

next-error

V.3 Compilation Mode

next-history-element

E.4 Minibuffer History

next-line

D.2 Changing the Location of Point

next-matching-history-element

E.4 Minibuffer History

normal-erase-is-backspace-mode

H.7.1 Deletion

normal-erase-is-backspace-mode

AD.9.1 If DEL Fails to Delete

normal-mode

R.1 How Major Modes are Chosen

not-modified

M.3 Saving Files

nroff-mode

T.10 Nroff Mode

number-to-register

I.5 Keeping Numbers in Registers

O

occur

K.8 Other Search-and-Loop Commands

open-dribble-file

AD.10.3 Checklist for Bug Reports

open-line

D.7 Blank Lines

open-rectangle

H.10 Rectangles

open-termscript

AD.10.3 Checklist for Bug Reports

other-frame

P.8 Frame Commands

other-window

O.3 Using Other Windows

outline-backward-same-level

T.8.2 Outline Motion Commands

outline-forward-same-level

T.8.2 Outline Motion Commands

outline-minor-mode

T.8 Outline Mode

outline-mode

T.8 Outline Mode

outline-next-visible-heading

T.8.2 Outline Motion Commands

outline-previous-visible-heading

T.8.2 Outline Motion Commands

outline-up-heading

T.8.2 Outline Motion Commands

overwrite-mode

AD.1 Minor Modes

P

paragraph-indent-minor-mode

T.7 Text Mode

paragraph-indent-text-mode

T.7 Text Mode

partial-completion-mode

E.3.4 Completion Options

pc-bindings-mode

AC.27 Emulation

pc-selection-mode

AC.27 Emulation

pdb

V.5.1 Starting GUD

perldb

V.5.1 Starting GUD

phases-of-moon

AC.8 Phases of the Moon

picture-backward-clear-column

Y.1 Basic Editing in Picture Mode

picture-backward-column

Y.1 Basic Editing in Picture Mode

picture-clear-column

Y.1 Basic Editing in Picture Mode

picture-clear-line

Y.1 Basic Editing in Picture Mode

picture-clear-rectangle

Y.4 Picture Mode Rectangle Commands

picture-clear-rectangle-to-register

Y.4 Picture Mode Rectangle Commands

picture-forward-column

Y.1 Basic Editing in Picture Mode

picture-motion

Y.2 Controlling Motion after Insert

picture-motion-reverse

Y.2 Controlling Motion after Insert

picture-move-down

Y.1 Basic Editing in Picture Mode

picture-move-up

Y.1 Basic Editing in Picture Mode

picture-movement-down

Y.2 Controlling Motion after Insert

picture-movement-left

Y.2 Controlling Motion after Insert

picture-movement-ne

Y.2 Controlling Motion after Insert

picture-movement-nw

Y.2 Controlling Motion after Insert

picture-movement-right

Y.2 Controlling Motion after Insert

picture-movement-se

Y.2 Controlling Motion after Insert

picture-movement-sw

Y.2 Controlling Motion after Insert

picture-movement-up

Y.2 Controlling Motion after Insert

picture-newline

Y.1 Basic Editing in Picture Mode

picture-open-line

Y.1 Basic Editing in Picture Mode

picture-set-tab-stops

Y.3 Picture Mode Tabs

picture-tab

Y.3 Picture Mode Tabs

picture-tab-search

Y.3 Picture Mode Tabs

picture-yank-rectangle

Y.4 Picture Mode Rectangle Commands

picture-yank-rectangle-from-register

Y.4 Picture Mode Rectangle Commands

plain-tex-mode

T.9 TeX Mode

point-to-register

I.1 Saving Positions in Registers

pong

AC.30 Other Amusements

pop-global-mark

H.6 The Global Mark Ring

pop-tag-mark

W.2.5 Finding a Tag

posix-file-name-to-mac

AG.6 Mac-Specific Lisp Functions

prefer-coding-system

Q.8 Recognizing Coding Systems

prepend-to-buffer

H.9 Accumulating Text

prepend-to-register

I.2 Saving Text in Registers

previous-completion

E.3.2 Completion Commands

previous-history-element

E.4 Minibuffer History

previous-line

D.2 Changing the Location of Point

previous-matching-history-element

E.4 Minibuffer History

print-buffer

AC.18 Hardcopy Output

print-buffer (MS-DOS)

AH.5 Printing and MS-DOS

print-region

AC.18 Hardcopy Output

print-region (MS-DOS)

AH.5 Printing and MS-DOS

ps-print-buffer

AC.19 PostScript Hardcopy

ps-print-buffer (MS-DOS)

AH.5 Printing and MS-DOS

ps-print-buffer-with-faces

AC.19 PostScript Hardcopy

ps-print-region

AC.19 PostScript Hardcopy

ps-print-region-with-faces

AC.19 PostScript Hardcopy

ps-spool-buffer

AC.19 PostScript Hardcopy

ps-spool-buffer (MS-DOS)

AH.5 Printing and MS-DOS

ps-spool-buffer-with-faces

AC.19 PostScript Hardcopy

ps-spool-region

AC.19 PostScript Hardcopy

ps-spool-region-with-faces

AC.19 PostScript Hardcopy

pwd

M.1 File Names

Q

quail-set-keyboard-layout

Q.5 Selecting an Input Method

query-replace

K.7.4 Query Replace

query-replace-regexp

K.7.4 Query Replace

quietly-read-abbrev-file

X.5 Saving Abbrevs

quoted-insert

D.1 Inserting Text

R

re-search-backward

K.4 Regular Expression Search

re-search-forward

K.4 Regular Expression Search

read-abbrev-file

X.5 Saving Abbrevs

recenter

J.6 Scrolling

recentf-edit-list

M.16 Convenience Features for Finding Files

recentf-mode

M.16 Convenience Features for Finding Files

recentf-save-list

M.16 Convenience Features for Finding Files

recompile

V.1 Running Compilations under Emacs

recover-file

M.5.3 Recovering Data from Auto-Saves

recover-session

M.5.3 Recovering Data from Auto-Saves

redraw-calendar

AC.4 Miscellaneous Calendar Commands

remove-untranslated-filesystem

AH.4 Text Files and Binary Files

rename-buffer

N.3 Miscellaneous Buffer Operations

rename-file

M.10 Miscellaneous File Operations

repeat

D.11 Repeating a Command

repeat-complex-command

E.5 Repeating Minibuffer Commands

replace-regexp

K.7.1 Unconditional Replacement

replace-string

K.7.1 Unconditional Replacement

report-emacs-bug

AD.10.3 Checklist for Bug Reports

reposition-window

J.6 Scrolling

revert-buffer

M.4 Reverting a Buffer

revert-buffer (Dired)

AB.14 Updating the Dired Buffer

rmail

AA. Reading Mail with Rmail

rmail-add-label

AA.8 Labels

rmail-beginning-of-message

AA.2 Scrolling Within a Message

rmail-bury

AA.1 Basic Concepts of Rmail

rmail-continue

AA.10 Sending Replies

rmail-delete-backward

AA.4 Deleting Messages

rmail-delete-forward

AA.4 Deleting Messages

rmail-edit-current-message

AA.15 Editing Within a Message

rmail-expunge

AA.4 Deleting Messages

rmail-expunge-and-save

AA.1 Basic Concepts of Rmail

rmail-first-message

AA.3 Moving Among Messages

rmail-forward

AA.10 Sending Replies

rmail-get-new-mail

AA.6 Multiple Rmail Files

rmail-input

AA.6 Multiple Rmail Files

rmail-kill-label

AA.8 Labels

rmail-last-message

AA.3 Moving Among Messages

rmail-mail

AA.10 Sending Replies

rmail-mode

AA. Reading Mail with Rmail

rmail-next-labeled-message

AA.8 Labels

rmail-next-message

AA.3 Moving Among Messages

rmail-next-undeleted-message

AA.3 Moving Among Messages

rmail-output

AA.7 Copying Messages Out to Files

rmail-output-body-to-file

AA.7 Copying Messages Out to Files

rmail-output-to-rmail-file

AA.7 Copying Messages Out to Files

rmail-previous-labeled-message

AA.8 Labels

rmail-previous-message

AA.3 Moving Among Messages

rmail-previous-undeleted-message

AA.3 Moving Among Messages

rmail-quit

AA.1 Basic Concepts of Rmail

rmail-redecode-body

AA.14 Rmail and Coding Systems

rmail-reply

AA.10 Sending Replies

rmail-resend

AA.10 Sending Replies

rmail-retry-failure

AA.10 Sending Replies

rmail-search

AA.3 Moving Among Messages

rmail-show-message

AA.3 Moving Among Messages

rmail-summary

AA.11.1 Making Summaries

rmail-summary-by-labels

AA.11.1 Making Summaries

rmail-summary-by-recipients

AA.11.1 Making Summaries

rmail-summary-by-regexp

AA.11.1 Making Summaries

rmail-summary-by-topic

AA.11.1 Making Summaries

rmail-summary-quit

AA.11.2 Editing in Summaries

rmail-summary-wipe

AA.11.2 Editing in Summaries

rmail-toggle-header

AA.13 Display of Messages

rmail-undelete-previous-message

AA.4 Deleting Messages

rot13-other-window

AA.18 Reading Rot13 Messages

run-lisp

V.10 Running an External Lisp

S

save-buffer

M.3 Saving Files

save-buffers-kill-emacs

C.1 Exiting Emacs

save-some-buffers

M.3 Saving Files

scroll-all-mode

AC.27 Emulation

scroll-bar-mode

P.13 Scroll Bars

scroll-calendar-left

AC.2 Scrolling in the Calendar

scroll-calendar-left-three-months

AC.2 Scrolling in the Calendar

scroll-calendar-right

AC.2 Scrolling in the Calendar

scroll-calendar-right-three-months

AC.2 Scrolling in the Calendar

scroll-down

J.6 Scrolling

scroll-left

J.7 Horizontal Scrolling

scroll-other-window

O.3 Using Other Windows

scroll-right

J.7 Horizontal Scrolling

scroll-up

J.6 Scrolling

sdb

V.5.1 Starting GUD

search-backward

K.2 Nonincremental Search

search-forward

K.2 Nonincremental Search

select-frame-by-name

P.20 Non-Window Terminals

self-insert

D.1 Inserting Text

send-invisible

AC.15.3 Shell Mode

server-edit

AC.16 Using Emacs as a Server

set-background-color

P.12 Setting Frame Parameters

set-border-color

P.12 Setting Frame Parameters

set-buffer-file-coding-system

Q.9 Specifying a Coding System

set-buffer-process-coding-system

Q.9 Specifying a Coding System

set-cursor-color

P.12 Setting Frame Parameters

set-face-background

J.1 Using Multiple Typefaces

set-face-foreground

J.1 Using Multiple Typefaces

set-fill-column

T.5.3 Explicit Fill Commands

set-fill-prefix

T.5.4 The Fill Prefix

set-foreground-color

P.12 Setting Frame Parameters

set-frame-font

P.12 Setting Frame Parameters

set-frame-name

P.20 Non-Window Terminals

set-goal-column

D.2 Changing the Location of Point

set-input-method

Q.5 Selecting an Input Method

set-justification-center

T.11.7 Justification in Formatted Text

set-justification-full

T.11.7 Justification in Formatted Text

set-justification-left

T.11.7 Justification in Formatted Text

set-justification-none

T.11.7 Justification in Formatted Text

set-justification-right

T.11.7 Justification in Formatted Text

set-keyboard-coding-system

Q.9 Specifying a Coding System

set-language-environment

Q.3 Language Environments

set-locale-environment

Q.3 Language Environments

set-mark-command

H.1 Setting the Mark

set-mouse-color

P.12 Setting Frame Parameters

set-next-selection-coding-system

Q.9 Specifying a Coding System

set-rmail-inbox-list

AA.6 Multiple Rmail Files

set-selection-coding-system

Q.9 Specifying a Coding System

set-selective-display

J.9 Selective Display

set-terminal-coding-system

Q.9 Specifying a Coding System

set-variable

AD.2.1 Examining and Setting Variables

set-visited-file-name

M.3 Saving Files

setenv

AE.5 Environment Variables

setq-default

AD.2.4 Local Variables

shell

AC.15.2 Interactive Inferior Shell

shell-backward-command

AC.15.3 Shell Mode

shell-command

AC.15.1 Single Shell Commands

shell-command-on-region

AC.15.1 Single Shell Commands

shell-forward-command

AC.15.3 Shell Mode

shell-pushd-dextract

AC.15.6 Shell Mode Options

shell-pushd-dunique

AC.15.6 Shell Mode Options

shell-pushd-tohome

AC.15.6 Shell Mode Options

show-all

T.8.3 Outline Visibility Commands

show-all-diary-entries

AC.10.1 Commands Displaying Diary Entries

show-branches

T.8.3 Outline Visibility Commands

show-children

T.8.3 Outline Visibility Commands

show-entry

T.8.3 Outline Visibility Commands

show-paren-mode

U.4.3 Automatic Display Of Matching Parentheses

show-subtree

T.8.3 Outline Visibility Commands

shrink-window-if-larger-than-buffer

O.6 Deleting and Rearranging Windows

slitex-mode

T.9 TeX Mode

smerge-mode

M.9 Comparing Files

snake

AC.30 Other Amusements

solitaire

AC.30 Other Amusements

sort-columns

AC.21 Sorting Text

sort-fields

AC.21 Sorting Text

sort-lines

AC.21 Sorting Text

sort-numeric-fields

AC.21 Sorting Text

sort-pages

AC.21 Sorting Text

sort-paragraphs

AC.21 Sorting Text

split-line

S.1 Indentation Commands and Techniques

split-window-horizontally

O.2 Splitting Windows

split-window-vertically

O.2 Splitting Windows

spook

Z.5 Mail Amusements

standard-display-8bit

Q.13 Single-byte Character Set Support

start-kbd-macro

AD.3.1 Basic Use

string-insert-rectangle

H.10 Rectangles

string-rectangle

H.10 Rectangles

studlify-region

AC.30 Other Amusements

substitute-in-file-name

M.1 File Names

substitute-key-definition

AD.7.2 Init File Examples

sunrise-sunset

AC.7 Times of Sunrise and Sunset

suspend-emacs

C.1 Exiting Emacs

switch-to-buffer

N.1 Creating and Selecting Buffers

switch-to-buffer-other-frame

N.1 Creating and Selecting Buffers

switch-to-buffer-other-window

N.1 Creating and Selecting Buffers

switch-to-completions

E.3.2 Completion Commands

T

tab-to-tab-stop

S.2 Tab Stops

tabify

S.3 Tabs vs. Spaces

tags-apropos

W.2.7 Tags Table Inquiries

tags-loop-continue

W.2.6 Searching and Replacing with Tags Tables

tags-query-replace

W.2.6 Searching and Replacing with Tags Tables

tags-search

W.2.6 Searching and Replacing with Tags Tables

term

AC.15.7 Emacs Terminal Emulator

term-char-mode

AC.15.8 Term Mode

term-line-mode

AC.15.8 Term Mode

term-pager-toggle

AC.15.9 Page-At-A-Time Output

tetris

AC.30 Other Amusements

tex-bibtex-file

T.9.3 TeX Printing Commands

tex-buffer

T.9.3 TeX Printing Commands

tex-close-latex-block

T.9.2 LaTeX Editing Commands

tex-file

T.9.3 TeX Printing Commands

tex-insert-braces

T.9.1 TeX Editing Commands

tex-insert-quote

T.9.1 TeX Editing Commands

tex-kill-job

T.9.3 TeX Printing Commands

tex-latex-block

T.9.2 LaTeX Editing Commands

tex-mode

T.9 TeX Mode

tex-print

T.9.3 TeX Printing Commands

tex-recenter-output-buffer

T.9.3 TeX Printing Commands

tex-region

T.9.3 TeX Printing Commands

tex-show-print-queue

T.9.3 TeX Printing Commands

tex-terminate-paragraph

T.9.1 TeX Editing Commands

tex-validate-region

T.9.1 TeX Editing Commands

tex-view

T.9.3 TeX Printing Commands

text-mode

T.7 Text Mode

time-stamp

M.3.4 Updating Time Stamps Automatically

timeclock-in

AC.13 Summing Time Intervals

timeclock-modeline-display

AC.13 Summing Time Intervals

timeclock-out

AC.13 Summing Time Intervals

timeclock-reread-log

AC.13 Summing Time Intervals

timeclock-when-to-leave

AC.13 Summing Time Intervals

timeclock-workday-remaining

AC.13 Summing Time Intervals

tmm-menubar

B.4 The Menu Bar

toggle-debug-on-error

AD.10.3 Checklist for Bug Reports

toggle-enable-multibyte-characters

Q.2 Enabling Multibyte Characters

toggle-input-method

Q.5 Selecting an Input Method

toggle-save-place

AC.25 Saving Emacs Sessions

toggle-scroll-bar

P.13 Scroll Bars

toggle-truncate-lines

D.8 Continuation Lines

tooltip-mode

P.18 Tooltips (or "Balloon Help")

top-level

AD.8 Quitting and Aborting

tpu-edt-on

AC.27 Emulation

transient-mark-mode

H.2 Transient Mark Mode

transpose-chars

L.2 Transposing Text

transpose-lines

L.2 Transposing Text

transpose-sexps

U.4.1 Expressions with Balanced Parentheses

transpose-words

L.2 Transposing Text

tty-suppress-bold-inverse-default-colors

J.12 Customization of Display

turn-on-font-lock

J.2 Font Lock mode

U

undigestify-rmail-message

AA.16 Digest Messages

undo

D.4 Undoing Changes

unexpand-abbrev

X.3 Controlling Abbrev Expansion

unforward-rmail-message

AA.10 Sending Replies

unhighlight-regexp

J.4 Interactive Highlighting by Matching

universal-argument

D.10 Numeric Arguments

universal-coding-system-argument

Q.9 Specifying a Coding System

unmorse-region

AC.30 Other Amusements

unrmail

AA.17 Converting an Rmail File to Inbox Format

untabify

S.3 Tabs vs. Spaces

up-list

T.9.1 TeX Editing Commands

upcase-region

T.6 Case Conversion Commands

upcase-word

T.6 Case Conversion Commands

V

vc-annotate

M.7.4 Examining And Comparing Old Versions

vc-cancel-version

M.7.5.3 Undoing Version Control Actions

vc-create-snapshot

M.7.8.1 Making and Using Snapshots

vc-diff

M.7.4 Examining And Comparing Old Versions

vc-directory

M.7.5.4 Dired under VC

vc-dired-mark-locked

M.7.5.5 VC Dired Commands

vc-dired-toggle-terse-mode

M.7.5.5 VC Dired Commands

vc-insert-headers

M.7.9.3 Inserting Version Control Headers

vc-merge

M.7.6.3 Merging Branches

vc-next-action

M.7.3 Basic Editing under Version Control

vc-print-log

M.7.5.2 VC Status Commands

vc-register

M.7.5.1 Registering a File for Version Control

vc-rename-file

M.7.9.2 Renaming VC Work Files and Master Files

vc-retrieve-snapshot

M.7.8.1 Making and Using Snapshots

vc-revert-buffer

M.7.5.3 Undoing Version Control Actions

vc-switch-backend

M.7.7.2 Local Version Control

vc-toggle-read-only

M.7.3 Basic Editing under Version Control

vc-update-change-log

M.7.9.1 Change Logs and VC

vc-version-other-window

M.7.4 Examining And Comparing Old Versions

vi-mode

AC.27 Emulation

view-buffer

N.3 Miscellaneous Buffer Operations

view-diary-entries

AC.10.1 Commands Displaying Diary Entries

view-emacs-FAQ

G.8 Other Help Commands

view-emacs-news

G.8 Other Help Commands

view-emacs-problems

G.8 Other Help Commands

view-file

M.10 Miscellaneous File Operations

view-hello-file

Q.1 Introduction to International Character Sets

view-lossage

G.8 Other Help Commands

view-register

I. Registers

vip-mode

AC.27 Emulation

viper-mode

AC.27 Emulation

visit-tags-table

W.2.4 Selecting a Tags Table

W

what-cursor-position

D.9 Cursor Position Information

what-line

D.9 Cursor Position Information

what-page

D.9 Cursor Position Information

where-is

G.3 Help by Command or Variable Name

which-function-mode

U.2.4 Which Function Mode

widen

AC.22 Narrowing

widget-backward

AD.2.2.2 Changing an Option

widget-complete

AD.2.2.2 Changing an Option

widget-forward

AD.2.2.2 Changing an Option

windmove-default-keybindings

O.7 Window Handling Convenience Features and Customization

windmove-right

O.7 Window Handling Convenience Features and Customization

window-configuration-to-register

I.4 Saving Window Configurations in Registers

winner-mode

O.7 Window Handling Convenience Features and Customization

woman

U.6.2 Man Page Lookup

woman-find-file

U.6.2 Man Page Lookup

word-search-backward

K.3 Word Search

word-search-forward

K.3 Word Search

wordstar-mode

AC.27 Emulation

write-abbrev-file

X.5 Saving Abbrevs

write-file

M.3 Saving Files

write-region

M.10 Miscellaneous File Operations

X

xdb

V.5.1 Starting GUD

Y

yank

H.8.1 The Kill Ring

yank-pop

H.8.3 Yanking Earlier Kills

yank-rectangle

H.10 Rectangles

yow

AC.30 Other Amusements

Z

zap-to-char

H.7.3 Other Kill Commands

zone

AC.30 Other Amusements

Jump to:

2 5
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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Variable Index

Jump to:

A B C D E F G H I J K L M N O P R S T U V W X

Index Entry

Section

A

abbrev-all-caps

X.3 Controlling Abbrev Expansion

abbrev-file-name

X.5 Saving Abbrevs

abbrev-mode

X.1 Abbrev Concepts

adaptive-fill-first-line-regexp

T.5.5 Adaptive Filling

adaptive-fill-function

T.5.5 Adaptive Filling

adaptive-fill-mode

T.5.5 Adaptive Filling

adaptive-fill-regexp

T.5.5 Adaptive Filling

add-log-keep-changes-together

W.1 Change Logs

ange-ftp-default-user

M.13 Remote Files

ange-ftp-gateway-host

M.13 Remote Files

ange-ftp-generate-anonymous-password

M.13 Remote Files

ange-ftp-make-backup-files

M.13 Remote Files

ange-ftp-smart-gateway

M.13 Remote Files

appt-display-diary

AC.11 Appointments

appt-issue-message

AC.11 Appointments

apropos-do-all

G.4 Apropos

auto-coding-alist

Q.8 Recognizing Coding Systems

auto-coding-regexp-alist

Q.8 Recognizing Coding Systems

auto-compression-mode

M.11 Accessing Compressed Files

auto-mode-alist

R.1 How Major Modes are Chosen

auto-revert-interval

M.4 Reverting a Buffer

auto-save-default

M.5.2 Controlling Auto-Saving

auto-save-interval

M.5.2 Controlling Auto-Saving

auto-save-list-file-prefix

M.5.3 Recovering Data from Auto-Saves

auto-save-timeout

M.5.2 Controlling Auto-Saving

auto-save-visited-file-name

M.5.1 Auto-Save Files

automatic-hscrolling

J.7 Horizontal Scrolling

B

backup-by-copying

M.3.1.3 Copying vs. Renaming

backup-by-copying-when-linked

M.3.1.3 Copying vs. Renaming

backup-by-copying-when-mismatch

M.3.1.3 Copying vs. Renaming

backup-by-copying-when-privileged-mismatch

M.3.1.3 Copying vs. Renaming

backup-directory-alist

M.3.1.1 Single or Numbered Backups

backup-enable-predicate

M.3.1 Backup Files

baud-rate

J.12 Customization of Display

bdf-directory-list

AC.20 Variables for PostScript Hardcopy

blink-matching-delay

U.4.3 Automatic Display Of Matching Parentheses

blink-matching-paren

U.4.3 Automatic Display Of Matching Parentheses

blink-matching-paren-distance

U.4.3 Automatic Display Of Matching Parentheses

bookmark-save-flag

I.7 Bookmarks

bookmark-search-size

I.7 Bookmarks

browse-url-browser-function

AC.28.1 Following URLs

buffer-file-coding-system

Q.8 Recognizing Coding Systems

buffer-read-only

N.3 Miscellaneous Buffer Operations

C

c-comment-only-line-offset

U.11.5 Comments in C Modes

c-comment-start-regexp

U.11.5 Comments in C Modes

c-default-style

U.3.5 Customizing C Indentation

c-hanging-comment-ender-p

U.11.5 Comments in C Modes

c-hanging-comment-starter-p

U.11.5 Comments in C Modes

c-hungry-delete-key

U.11.3 Hungry Delete Feature in C

c-mode-hook

U.1 Major Modes for Programming Languages

c-mode-map

AD.4.3 Local Keymaps

calendar-daylight-savings-ends

AC.12 Daylight Savings Time

calendar-daylight-savings-ends-time

AC.12 Daylight Savings Time

calendar-daylight-savings-starts

AC.12 Daylight Savings Time

calendar-daylight-time-offset

AC.12 Daylight Savings Time

calendar-daylight-time-zone-name

AC.7 Times of Sunrise and Sunset

calendar-latitude

AC.7 Times of Sunrise and Sunset

calendar-location-name

AC.7 Times of Sunrise and Sunset

calendar-longitude

AC.7 Times of Sunrise and Sunset

calendar-standard-time-zone-name

AC.7 Times of Sunrise and Sunset

calendar-time-zone

AC.7 Times of Sunrise and Sunset

calendar-week-start-day

AC.1.2 Beginning or End of Week, Month or Year

case-fold-search

K.6 Searching and Case

case-replace

K.7.3 Replace Commands and Case

change-log-version-info-enabled

W.1 Change Logs

change-log-version-number-regexp-list

W.1 Change Logs

change-major-mode-with-file-name

R.1 How Major Modes are Chosen

coding

Q.8 Recognizing Coding Systems

colon-double-space

T.5.3 Explicit Fill Commands

comint-completion-addsuffix

AC.15.6 Shell Mode Options

comint-completion-autolist

AC.15.6 Shell Mode Options

comint-completion-fignore

AC.15.3 Shell Mode

comint-completion-recexact

AC.15.6 Shell Mode Options

comint-input-autoexpand

AC.15.4.3 Shell History References

comint-input-ignoredups

AC.15.6 Shell Mode Options

comint-prompt-regexp

AC.15.4.3 Shell History References

comint-scroll-show-maximum-output

AC.15.6 Shell Mode Options

comint-scroll-to-bottom-on-input

AC.15.6 Shell Mode Options

comint-scroll-to-bottom-on-output

AC.15.6 Shell Mode Options

comint-use-prompt-regexp-instead-of-fields

AC.15.4.3 Shell History References

command-history

E.5 Repeating Minibuffer Commands

command-line-args

AE.1 Action Arguments

comment-column

U.5.3 Options Controlling Comments

comment-end

U.5.3 Options Controlling Comments

comment-indent-function

U.5.3 Options Controlling Comments

comment-line-start

U.12.3 Fortran Comments

comment-line-start-skip

U.12.3 Fortran Comments

comment-multi-line

U.5.3 Options Controlling Comments

comment-padding

U.5.3 Options Controlling Comments

comment-start

U.5.3 Options Controlling Comments

comment-start-skip

U.5.3 Options Controlling Comments

compare-ignore-case

M.9 Comparing Files

compilation-error-regexp-alist

V.3 Compilation Mode

compilation-scroll-output

V.1 Running Compilations under Emacs

compile-command

V.1 Running Compilations under Emacs

completion-auto-help

E.3.4 Completion Options

completion-ignored-extensions

E.3.4 Completion Options

confirm-kill-emacs

C.1 Exiting Emacs

crisp-override-meta-x

AC.27 Emulation

ctl-arrow

J.12 Customization of Display

ctl-x-4-map

AD.4.2 Prefix Keymaps

ctl-x-map

AD.4.2 Prefix Keymaps

current-input-method

Q.5 Selecting an Input Method

current-language-environment

Q.3 Language Environments

cursor-in-non-selected-windows

J.13 Displaying the Cursor

custom-buffer-done-function

AD.2.2.2 Changing an Option

D

dabbrev-abbrev-char-regexp

X.7 Customizing Dynamic Abbreviation

dabbrev-abbrev-skip-leading-regexp

X.7 Customizing Dynamic Abbreviation

dabbrev-case-fold-search

X.7 Customizing Dynamic Abbreviation

dabbrev-case-fold-search

X.7 Customizing Dynamic Abbreviation

dabbrev-case-replace

X.7 Customizing Dynamic Abbreviation

dabbrev-check-all-buffers

X.6 Dynamic Abbrev Expansion

dabbrev-ignored-buffer-regexps

X.6 Dynamic Abbrev Expansion

dabbrev-limit

X.6 Dynamic Abbrev Expansion

dbx-mode-hook

V.5.4 GUD Customization

default-buffer-file-coding-system

Q.9 Specifying a Coding System

default-directory

M.1 File Names

default-enable-multibyte-characters

Q.2 Enabling Multibyte Characters

default-indicate-empty-lines

J.5 Trailing Whitespace

default-input-method

Q.5 Selecting an Input Method

default-justification

T.11.7 Justification in Formatted Text

default-major-mode

R.1 How Major Modes are Chosen

delete-auto-save-files

M.5.1 Auto-Save Files

delete-old-versions

M.3.1.2 Automatic Deletion of Backups

desktop-enable

AC.25 Saving Emacs Sessions

desktop-files-not-to-save

AC.25 Saving Emacs Sessions

diary-file

AC.10.2 The Diary File

diary-hook

AC.11 Appointments

diary-mail-days

AC.10.1 Commands Displaying Diary Entries

diff-switches

M.9 Comparing Files

dired-chown-program

AB.7 Operating on Files

dired-copy-preserve-time

AB.7 Operating on Files

dired-dwim-target

AB.7 Operating on Files

dired-garbage-files-regexp

AB.4 Flagging Many Files at Once

dired-kept-versions

AB.4 Flagging Many Files at Once

dired-listing-switches

AB.1 Entering Dired

dired-listing-switches (MS-DOS)

AH.7 Subprocesses on MS-DOS

dired-recursive-copies

AB.7 Operating on Files

dired-recursive-deletes

AB.3 Deleting Files with Dired

display-buffer-reuse-frames

N.1 Creating and Selecting Buffers

display-time-24hr-format

J.10 Optional Mode Line Features

display-time-mail-face

J.10 Optional Mode Line Features

display-time-use-mail-icon

J.10 Optional Mode Line Features

dos-codepage

AH.6 International Support on MS-DOS

dos-display-scancodes

AH.1 Keyboard and Mouse on MS-DOS

dos-hyper-key

AH.1 Keyboard and Mouse on MS-DOS

dos-keypad-mode

AH.1 Keyboard and Mouse on MS-DOS

dos-printer

AH.5 Printing and MS-DOS

dos-ps-printer

AH.5 Printing and MS-DOS

dos-super-key

AH.1 Keyboard and Mouse on MS-DOS

dos-unsupported-character-glyph

AH.6 International Support on MS-DOS

double-click-fuzz

AD.4.10 Rebinding Mouse Buttons

double-click-time

AD.4.10 Rebinding Mouse Buttons

E

echo-keystrokes

J.12 Customization of Display

emacs-lisp-mode-hook

U.1 Major Modes for Programming Languages

emerge-combine-versions-template

W.3.6 Combining the Two Versions

emerge-startup-hook

W.3.7 Fine Points of Emerge

enable-multibyte-characters

Q.2 Enabling Multibyte Characters

enable-recursive-minibuffers

E.2 Editing in the Minibuffer

enriched-fill-after-visiting

T.11.1 Requesting to Edit Formatted Text

enriched-translations

T.11.1 Requesting to Edit Formatted Text

eol-mnemonic-dos

B.3 The Mode Line

eol-mnemonic-mac

B.3 The Mode Line

eol-mnemonic-undecided

B.3 The Mode Line

eol-mnemonic-unix

B.3 The Mode Line

esc-map

AD.4.2 Prefix Keymaps

european-calendar-style

AC.10.3 Date Formats

eval-expression-debug-on-error

V.8 Evaluating Emacs-Lisp Expressions

eval-expression-print-length

V.8 Evaluating Emacs-Lisp Expressions

eval-expression-print-level

V.8 Evaluating Emacs-Lisp Expressions

even-window-heights

N.1 Creating and Selecting Buffers

exit-language-environment-hook

Q.3 Language Environments

explicit-shell-file-name

AC.15.2 Interactive Inferior Shell

F

ff-related-file-alist

U.11.4 Other Commands for C Mode

file-coding-system-alist

Q.8 Recognizing Coding Systems

file-name-buffer-file-type-alist

AH.4 Text Files and Binary Files

file-name-coding-system

Q.9 Specifying a Coding System

file-name-handler-alist

M.13 Remote Files

fill-column

T.5.3 Explicit Fill Commands

fill-prefix

T.5.4 The Fill Prefix

find-file-existing-other-name

M.6 File Name Aliases

find-file-hooks

M.2 Visiting Files

find-file-not-found-hooks

M.2 Visiting Files

find-file-run-dired

M.2 Visiting Files

find-file-suppress-same-file-warnings

M.6 File Name Aliases

find-file-visit-truename

M.6 File Name Aliases

find-file-wildcards

M.2 Visiting Files

find-ls-option

AB.15 Dired and find

find-tag-marker-ring-length

W.2.5 Finding a Tag

foldout-mouse-modifiers

T.8.5 Folding Editing

font-lock-beginning-of-syntax-function

J.2 Font Lock mode

font-lock-maximum-decoration

J.2 Font Lock mode

font-lock-maximum-size

J.2 Font Lock mode

fortran-analyze-depth

U.12.2.2 Continuation Lines

fortran-break-before-delimiters

U.12.4 Fortran Auto Fill Mode

fortran-check-all-num...

U.12.2.5 Variables for Fortran Indentation

fortran-column-ruler-fixed

U.12.5 Checking Columns in Fortran

fortran-column-ruler-tabs

U.12.5 Checking Columns in Fortran

fortran-comment-indent-char

U.12.3 Fortran Comments

fortran-comment-indent-style

U.12.3 Fortran Comments

fortran-comment-line-extra-indent

U.12.3 Fortran Comments

fortran-comment-region

U.12.3 Fortran Comments

fortran-continuation-indent

U.12.2.5 Variables for Fortran Indentation

fortran-continuation-string

U.12.2.2 Continuation Lines

fortran-do-indent

U.12.2.5 Variables for Fortran Indentation

fortran-electric-line-number

U.12.2.3 Line Numbers

fortran-if-indent

U.12.2.5 Variables for Fortran Indentation

fortran-line-number-indent

U.12.2.3 Line Numbers

fortran-minimum-statement-indent...

U.12.2.5 Variables for Fortran Indentation

fortran-structure-indent

U.12.2.5 Variables for Fortran Indentation

fortran-tab-mode-default

U.12.2.2 Continuation Lines

G

gdb-mode-hook

V.5.4 GUD Customization

global-font-lock-mode

J.2 Font Lock mode

grep-regexp-alist

V.3 Compilation Mode

gud-xdb-directories

V.5.1 Starting GUD

H

help-map

AD.4.2 Prefix Keymaps

hi-lock-exclude-modes

J.4 Interactive Highlighting by Matching

highlight-nonselected-windows

H.2 Transient Mark Mode

highlight-wrong-size-font

Q.10 Fontsets

history-length

E.4 Minibuffer History

hourglass-delay

J.12 Customization of Display

hs-hide-comments-when-hiding-all

U.7 Hideshow minor mode

hs-isearch-open

U.7 Hideshow minor mode

hs-special-modes-alist

U.7 Hideshow minor mode

I

image-file-name-extensions

M.16 Convenience Features for Finding Files

image-file-name-regexps

M.16 Convenience Features for Finding Files

imenu-auto-rescan

U.2.3 Imenu

imenu-sort-function

U.2.3 Imenu

indent-tabs-mode

S.3 Tabs vs. Spaces

indent-tabs-mode (Fortran mode)

U.12.2.2 Continuation Lines

indicate-empty-lines

J.5 Trailing Whitespace

inferior-lisp-program

V.10 Running an External Lisp

inhibit-eol-conversion

Q.8 Recognizing Coding Systems

inhibit-iso-escape-detection

Q.8 Recognizing Coding Systems

initial-major-mode

C. Entering and Exiting Emacs

input-method-highlight-flag

Q.4 Input Methods

input-method-verbose-flag

Q.4 Input Methods

insert-default-directory

M.1 File Names

interpreter-mode-alist

R.1 How Major Modes are Chosen

inverse-video

J.12 Customization of Display

isearch-lazy-highlight

K.1 Incremental Search

isearch-lazy-highlight-face

K.1 Incremental Search

isearch-mode-map

K.1 Incremental Search

ispell-dictionary

L.4 Checking and Correcting Spelling

J

jdb-mode-hook

V.5.4 GUD Customization

K

kept-new-versions

M.3.1.2 Automatic Deletion of Backups

kept-old-versions

M.3.1.2 Automatic Deletion of Backups

keyboard-coding-system

Q.9 Specifying a Coding System

kill-buffer-hook

N.4 Killing Buffers

kill-read-only-ok

H.7 Deletion and Killing

kill-ring

H.8.3 Yanking Earlier Kills

kill-ring-max

H.8.3 Yanking Earlier Kills

kill-whole-line

H.7.2 Killing by Lines

L

latex-block-names

T.9.2 LaTeX Editing Commands

latex-mode-hook

T.9.4 TeX Mode Miscellany

latex-run-command

T.9.3 TeX Printing Commands

latin1-display

Q.12 Undisplayable Characters

line-number-display-limit

J.10 Optional Mode Line Features

line-number-display-limit-width

J.10 Optional Mode Line Features

lisp-body-indent

U.3.3 Customizing Lisp Indentation

lisp-indent-offset

U.3.3 Customizing Lisp Indentation

lisp-interaction-mode-hook

U.1 Major Modes for Programming Languages

lisp-mode-hook

U.1 Major Modes for Programming Languages

lisp-mode-map

AD.4.3 Local Keymaps

list-directory-brief-switches

M.8 File Directories

list-directory-verbose-switches

M.8 File Directories

load-dangerous-libraries

V.7 Libraries of Lisp Code for Emacs

load-path

V.7 Libraries of Lisp Code for Emacs

locale-charset-language-names

Q.3 Language Environments

locale-coding-system

Q.9 Specifying a Coding System

locale-language-names

Q.3 Language Environments

locale-preferred-coding-systems

Q.3 Language Environments

locate-command

AB.15 Dired and find

lpr-add-switches

AC.18 Hardcopy Output

lpr-command (MS-DOS)

AH.5 Printing and MS-DOS

lpr-commands

AC.18 Hardcopy Output

lpr-headers-switches

AC.18 Hardcopy Output

lpr-headers-switches (MS-DOS)

AH.5 Printing and MS-DOS

lpr-switches

AC.18 Hardcopy Output

lpr-switches (MS-DOS)

AH.5 Printing and MS-DOS

M

mac-command-key-is-meta

AG.1 Keyboard Input on the Mac

mac-keyboard-text-encoding

AG.1 Keyboard Input on the Mac

mail-abbrevs

Z.3 Mail Aliases

mail-aliases

Z.3 Mail Aliases

mail-archive-file-name

Z.2 Mail Header Fields

mail-default-headers

Z.2 Mail Header Fields

mail-default-reply-to

Z.2 Mail Header Fields

mail-from-style

Z.2 Mail Header Fields

mail-mode-hook

Z.4.4 Mail Mode Miscellany

mail-personal-alias-file

Z.3 Mail Aliases

mail-self-blind

Z.2 Mail Header Fields

mail-setup-hook

Z.4.4 Mail Mode Miscellany

mail-signature

Z.4.4 Mail Mode Miscellany

mail-user-agent

Z.6 Mail-Composition Methods

mail-yank-prefix

Z.4.3 Citing Mail

make-backup-file-name-function

M.3.1.1 Single or Numbered Backups

make-backup-files

M.3.1 Backup Files

Man-fontify-manpage-flag

U.6.2 Man Page Lookup

Man-switches

U.6.2 Man Page Lookup

mark-even-if-inactive

H.2 Transient Mark Mode

mark-ring

H.5 The Mark Ring

mark-ring-max

H.5 The Mark Ring

max-mini-window-height

E.2 Editing in the Minibuffer

message-log-max

B.2 The Echo Area

midnight-hook

N.4 Killing Buffers

midnight-mode

N.4 Killing Buffers

minibuffer-local-completion-map

AD.4.4 Minibuffer Keymaps

minibuffer-local-map

AD.4.4 Minibuffer Keymaps

minibuffer-local-must-match-map

AD.4.4 Minibuffer Keymaps

minibuffer-local-ns-map

AD.4.4 Minibuffer Keymaps

mode-line-inverse-video

J.12 Customization of Display

mode-specific-map

AD.4.2 Prefix Keymaps

mouse-avoidance-mode

P.19 Mouse Avoidance

mouse-scroll-min-lines

P.1 Mouse Commands for Editing

mouse-wheel-follow-mouse

P.14 Scrolling With "Wheeled" Mice

mouse-wheel-scroll-amount

P.14 Scrolling With "Wheeled" Mice

mouse-yank-at-point

P.1 Mouse Commands for Editing

N

next-line-add-newlines

D.2 Changing the Location of Point

next-screen-context-lines

J.6 Scrolling

no-redraw-on-reenter

J.12 Customization of Display

normal-erase-is-backspace

AD.9.1 If DEL Fails to Delete

nroff-mode-hook

T.10 Nroff Mode

O

outline-level

T.8.1 Format of Outlines

outline-minor-mode-prefix

T.8 Outline Mode

outline-mode-hook

T.8 Outline Mode

outline-regexp

T.8.1 Format of Outlines

P

page-delimiter

T.4 Pages

paragraph-separate

T.3 Paragraphs

paragraph-start

T.3 Paragraphs

partial-completion-mode

E.3.4 Completion Options

PC-disable-includes

E.3.4 Completion Options

PC-include-file-path

E.3.4 Completion Options

pdb-mode-hook

V.5.4 GUD Customization

perldb-mode-hook

V.5.4 GUD Customization

picture-mode-hook

Y. Editing Pictures

picture-tab-chars

Y.3 Picture Mode Tabs

plain-tex-mode-hook

T.9.4 TeX Mode Miscellany

print-region-function (MS-DOS)

AH.5 Printing and MS-DOS

printer-name

AC.18 Hardcopy Output

printer-name (MS-DOS)

AH.5 Printing and MS-DOS

ps-font-family

AC.20 Variables for PostScript Hardcopy

ps-font-info-database

AC.20 Variables for PostScript Hardcopy

ps-font-size

AC.20 Variables for PostScript Hardcopy

ps-landscape-mode

AC.20 Variables for PostScript Hardcopy

ps-lpr-command

AC.20 Variables for PostScript Hardcopy

ps-lpr-command (MS-DOS)

AH.5 Printing and MS-DOS

ps-lpr-switches

AC.20 Variables for PostScript Hardcopy

ps-lpr-switches (MS-DOS)

AH.5 Printing and MS-DOS

ps-multibyte-buffer

AC.20 Variables for PostScript Hardcopy

ps-number-of-columns

AC.20 Variables for PostScript Hardcopy

ps-page-dimensions-database

AC.20 Variables for PostScript Hardcopy

ps-paper-type

AC.20 Variables for PostScript Hardcopy

ps-print-color-p

AC.20 Variables for PostScript Hardcopy

ps-print-header

AC.20 Variables for PostScript Hardcopy

ps-printer-name

AC.20 Variables for PostScript Hardcopy

ps-printer-name (MS-DOS)

AH.5 Printing and MS-DOS

ps-use-face-background

AC.20 Variables for PostScript Hardcopy

R

read-quoted-char-radix

D.1 Inserting Text

recentf-mode

M.16 Convenience Features for Finding Files

require-final-newline

M.3 Saving Files

resize-mini-windows

E.2 Editing in the Minibuffer

revert-without-query

M.4 Reverting a Buffer

rmail-decode-mime-charset

Q.8 Recognizing Coding Systems

rmail-delete-after-output

AA.7 Copying Messages Out to Files

rmail-delete-message-hook

AA.4 Deleting Messages

rmail-dont-reply-to-names

AA.10 Sending Replies

rmail-edit-mode-hook

AA.15 Editing Within a Message

rmail-file-coding-system

Q.8 Recognizing Coding Systems

rmail-file-name

AA.1 Basic Concepts of Rmail

rmail-highlighted-headers

AA.13 Display of Messages

rmail-ignored-headers

AA.13 Display of Messages

rmail-mail-new-frame

AA.10 Sending Replies

rmail-mode-hook

AA. Reading Mail with Rmail

rmail-movemail-flags

AA.19 movemail and POP

rmail-output-file-alist

AA.7 Copying Messages Out to Files

rmail-pop-password

AA.19 movemail and POP

rmail-pop-password-required

AA.19 movemail and POP

rmail-preserve-inbox

AA.19 movemail and POP

rmail-primary-inbox-list

AA.5 Rmail Files and Inboxes

rmail-redisplay-summary

AA.11.2 Editing in Summaries

rmail-retry-ignored-headers

AA.10 Sending Replies

rmail-secondary-file-directory

AA.6 Multiple Rmail Files

rmail-secondary-file-regexp

AA.6 Multiple Rmail Files

rmail-summary-line-count-flag

AA.11.1 Making Summaries

rmail-summary-window-size

AA.11.1 Making Summaries

S

same-window-buffer-names

O.5 Forcing Display in the Same Window

same-window-regexps

O.5 Forcing Display in the Same Window

save-abbrevs

X.5 Saving Abbrevs

save-place

AC.25 Saving Emacs Sessions

scheme-mode-hook

U.1 Major Modes for Programming Languages

scroll-all-mode

O.7 Window Handling Convenience Features and Customization

scroll-bar-mode

P.13 Scroll Bars

scroll-bar-width

P.13 Scroll Bars

scroll-conservatively

J.6 Scrolling

scroll-down-aggressively

J.6 Scrolling

scroll-margin

J.6 Scrolling

scroll-preserve-screen-position

J.6 Scrolling

scroll-up-aggressively

J.6 Scrolling

sdb-mode-hook

V.5.4 GUD Customization

search-slow-speed

K.1.1 Slow Terminal Incremental Search

search-slow-window-lines

K.1.1 Slow Terminal Incremental Search

selective-display-ellipses

J.9 Selective Display

sendmail-coding-system

Q.8 Recognizing Coding Systems

sentence-end

T.2 Sentences

sentence-end-double-space

T.5.3 Explicit Fill Commands

sentence-end-without-period

T.5.3 Explicit Fill Commands

server-kill-new-buffers

AC.16 Using Emacs as a Server

server-temp-file-regexp

AC.16 Using Emacs as a Server

server-window

AC.16 Using Emacs as a Server

set-language-environment-hook

Q.3 Language Environments

shell-cd-regexp

AC.15.5 Directory Tracking

shell-command-default-error-buffer

AC.15.1 Single Shell Commands

shell-command-regexp

AC.15.3 Shell Mode

shell-completion-execonly

AC.15.6 Shell Mode Options

shell-completion-fignore

AC.15.3 Shell Mode

shell-file-name

AC.15.1 Single Shell Commands

shell-input-ring-file-name

AC.15.4.1 Shell History Ring

shell-popd-regexp

AC.15.5 Directory Tracking

shell-prompt-pattern

AC.15.4.3 Shell History References

shell-pushd-regexp

AC.15.5 Directory Tracking

show-trailing-whitespace

J.5 Trailing Whitespace

slitex-mode-hook

T.9.4 TeX Mode Miscellany

slitex-run-command

T.9.3 TeX Printing Commands

small-temporary-file-directory

M.3.1 Backup Files

sort-fold-case

AC.21 Sorting Text

sort-numeric-base

AC.21 Sorting Text

special-display-buffer-names

P.11 Special Buffer Frames

special-display-frame-alist

P.11 Special Buffer Frames

special-display-regexps

P.11 Special Buffer Frames

split-window-keep-point

O.2 Splitting Windows

standard-fontset-spec

Q.11 Defining fontsets

standard-indent

T.11.6 Indentation in Formatted Text

suggest-key-bindings

F. Running Commands by Name

T

tab-stop-list

S.2 Tab Stops

tab-width

J.12 Customization of Display

tags-apropos-additional-actions

W.2.7 Tags Table Inquiries

tags-apropos-verbose

W.2.7 Tags Table Inquiries

tags-case-fold-search

W.2.6 Searching and Replacing with Tags Tables

tags-file-name

W.2.4 Selecting a Tags Table

tags-table-list

W.2.4 Selecting a Tags Table

tags-tag-face

W.2.7 Tags Table Inquiries

temporary-file-directory

M.3.1 Backup Files

term-file-prefix

AD.7.3 Terminal-specific Initialization

term-setup-hook

AD.7.3 Terminal-specific Initialization

tex-bibtex-command

T.9.3 TeX Printing Commands

tex-default-mode

T.9 TeX Mode

tex-directory

T.9.3 TeX Printing Commands

tex-dvi-print-command

T.9.3 TeX Printing Commands

tex-dvi-view-command

T.9.3 TeX Printing Commands

tex-main-file

T.9.3 TeX Printing Commands

tex-mode-hook

T.9.4 TeX Mode Miscellany

tex-run-command

T.9.3 TeX Printing Commands

tex-shell-hook

T.9.4 TeX Mode Miscellany

tex-show-queue-command

T.9.3 TeX Printing Commands

tex-start-options-string

T.9.3 TeX Printing Commands

text-mode-hook

T.7 Text Mode

timeclock-ask-before-exiting

AC.13 Summing Time Intervals

timeclock-file

AC.13 Summing Time Intervals

timeclock-modeline-display

AC.13 Summing Time Intervals

track-eol

D.2 Changing the Location of Point

truncate-lines

D.8 Continuation Lines

truncate-partial-width-windows

O.2 Splitting Windows

U

undo-limit

D.4 Undoing Changes

undo-strong-limit

D.4 Undoing Changes

unibyte-display-via-language-environment

Q.13 Single-byte Character Set Support

uniquify-buffer-name-style

N.7.1 Making Buffer Names Unique

use-dialog-box

P.17 Using Dialog Boxes

user-mail-address

AD.7.2 Init File Examples

V

vc-command-messages

M.7.10.1 General Options

vc-comment-alist

M.7.9.3 Inserting Version Control Headers

vc-consult-headers

M.7.10.2 Options for RCS and SCCS

vc-cvs-stay-local

M.7.10.3 Options specific for CVS

vc-default-init-version

M.7.5.1 Registering a File for Version Control

vc-diff-switches

M.7.4 Examining And Comparing Old Versions

vc-directory-exclusion-list

M.7.5.4 Dired under VC

vc-dired-recurse

M.7.5.4 Dired under VC

vc-dired-terse-display

M.7.5.4 Dired under VC

vc-follow-symlinks

M.7.10.1 General Options

vc-handled-backends

M.7.10 Customizing VC

vc-header-alist

M.7.9.3 Inserting Version Control Headers

vc-initial-comment

M.7.5.1 Registering a File for Version Control

vc-keep-workfiles

M.7.10.1 General Options

vc-log-mode-hook

M.7.3.4 Features of the Log Entry Buffer

vc-make-backup-files

M.3.1 Backup Files

vc-make-backup-files

M.7.10.1 General Options

vc-mistrust-permissions

M.7.10.2 Options for RCS and SCCS

vc-path

M.7.10.1 General Options

vc-rcs-diff-switches

M.7.4 Examining And Comparing Old Versions

vc-static-header-alist

M.7.9.3 Inserting Version Control Headers

vc-suppress-confirm

M.7.10.1 General Options

version-control

M.3.1.1 Single or Numbered Backups

visible-bell

J.12 Customization of Display

W

w32-pass-alt-to-system

AH.9 Using the System Menu on Windows

which-func-modes

U.2.4 Which Function Mode

window-min-height

O.6 Deleting and Rearranging Windows

window-min-width

O.6 Deleting and Rearranging Windows

woman-dired-keys

U.6.2 Man Page Lookup

woman-manpath

U.6.2 Man Page Lookup

woman-path

U.6.2 Man Page Lookup

X

x-cut-buffer-max

P.1 Mouse Commands for Editing

x-select-enable-clipboard

P.3 Using the Clipboard

x-stretch-cursor

J.13 Displaying the Cursor

xdb-mode-hook

V.5.4 GUD Customization

Jump to:

A B C D E F G H I J K L M N O P R S T U V W X

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Concept Index

Jump to:

" ( * - . / 8 ?
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

Index Entry

Section

"

"PC" key bindings

AC.27 Emulation

(

( in leftmost column

U.2.1 Left Margin Convention

*

`*Messages*' buffer

B.2 The Echo Area

-

--/---/.-./.../.

AC.30 Other Amusements

.

`.mailrc' file

Z.3 Mail Aliases

`.timelog' file

AC.13 Summing Time Intervals

`.Xdefaults' file, and MS-Windows

AE.13 X Resources

/

// in file name

E.1 Minibuffers for File Names

8

8-bit character codes

D.1 Inserting Text

8-bit display

Q.13 Single-byte Character Set Support

8-bit input

Q.13 Single-byte Character Set Support

?

`?' in display

Q.1 Introduction to International Character Sets

A

A and B buffers (Emerge)

W.3.1 Overview of Emerge

Abbrev mode

X.1 Abbrev Concepts

abbrevs

X. Abbrevs

abnormal hook

AD.2.3 Hooks

aborting recursive edit

AD.8 Quitting and Aborting

accented characters

Q.13 Single-byte Character Set Support

accessible portion

AC.22 Narrowing

accumulating scattered text

H.9 Accumulating Text

action options (command line)

AE. Command Line Arguments

active fields (customization buffer)

AD.2.2.1 Customization Groups

adaptive filling

T.5.5 Adaptive Filling

againformation

AC.29 Dissociated Press

aggressive scrolling

J.6 Scrolling

alarm clock

AC.11 Appointments

ange-ftp

M.13 Remote Files

anonymous FTP

M.13 Remote Files

appending kills in the ring

H.8.2 Appending Kills

appointment notification

AC.11 Appointments

apropos

G.4 Apropos

arc

M.12 File Archives

Archive mode

M.12 File Archives

arguments (command line)

AE. Command Line Arguments

arguments to commands

D.10 Numeric Arguments

arrow keys

D.2 Changing the Location of Point

ASCII

B.5 Kinds of User Input

Asm mode

U.13 Asm Mode

assembler mode

U.13 Asm Mode

astronomical day numbers

AC.9.1 Supported Calendar Systems

attribute (Rmail)

AA.8 Labels

attributes of mode line, changing

J.10 Optional Mode Line Features

Auto Compression mode

M.11 Accessing Compressed Files

Auto Fill mode

T.5.1 Auto Fill Mode

Auto Save mode

M.5 Auto-Saving: Protection Against Disasters

Auto-Lower mode

P.12 Setting Frame Parameters

Auto-Raise mode

P.12 Setting Frame Parameters

Auto-Revert mode

M.4 Reverting a Buffer

autoload

V.7 Libraries of Lisp Code for Emacs

autoload Lisp libraries

AD.7.2 Init File Examples

automatic version backups

M.7.7.1 Version Backups

available colors

AE.8 Window Color Options

avoiding mouse in the way of your typing

P.19 Mouse Avoidance

Awk mode

U.1 Major Modes for Programming Languages

B

b2m

AA.17 Converting an Rmail File to Inbox Format

Babyl format to Inbox format

AA.17 Converting an Rmail File to Inbox Format

back end (version control)

M.7.1.1 Supported Version Control Systems

background color, command-line argument

AE.8 Window Color Options

background mode, on xterm

AE.5.1 General Variables

BACKSPACE vs DEL

AD.9.1 If DEL Fails to Delete

backtrace for bug reports

AD.10.3 Checklist for Bug Reports

backup file

M.3.1 Backup Files

backup file names on MS-DOS

AH.3 File Names on MS-DOS

backup, and user-id

M.3.1.3 Copying vs. Renaming

backups for remote files

M.13 Remote Files

balanced expression

U.4.1 Expressions with Balanced Parentheses

balloon help

G.9 Help on Active Text and Tooltips

balloon help

P.18 Tooltips (or "Balloon Help")

base buffer

N.6 Indirect Buffers

batch mode

AE.2 Initial Options

binary files, on MS-DOS/MS-Windows

AH.4 Text Files and Binary Files

binding

B.7 Keys and Commands

blank lines

D.7 Blank Lines

blank lines in programs

U.5.2 Multiple Lines of Comments

body lines (Outline mode)

T.8.1 Format of Outlines

bold font

AD.2.2.3 Customizing Faces

bookmarks

I.7 Bookmarks

border color, command-line argument

AE.8 Window Color Options

border width, command-line argument

AE.10 Internal and External Borders

borders (X Window System)

AE.10 Internal and External Borders

boredom

AC.30 Other Amusements

box-drawing characters (MS-DOS)

AH.6 International Support on MS-DOS

brace in column zero and fontification

J.2 Font Lock mode

braces, moving across

U.4.2 Moving in the Parenthesis Structure

branch (version control)

M.7.6 Multiple Branches of a File

Brief emulation

AC.27 Emulation

Browse-URL

AC.28.1 Following URLs

buffer definitions index

U.2.3 Imenu

buffer list, customizable

N.7.3 Customizing Buffer Menus

buffer menu

N.5 Operating on Several Buffers

buffer menu

N.7.3 Customizing Buffer Menus

buffer size, maximum

N. Using Multiple Buffers

buffers

N. Using Multiple Buffers

buggestion

AC.29 Dissociated Press

bugs

AD.10 Reporting Bugs

building programs

V. Compiling and Testing Programs

button down events

AD.4.10 Rebinding Mouse Buttons

bypassing init and site-start file

AE.2 Initial Options

byte code

V.7 Libraries of Lisp Code for Emacs

byte-compiling several files (in Dired)

AB.7 Operating on Files

C

C editing

U. Editing Programs

C editing

W. Maintaining Programs

C mode

U.11 C and Related Modes

C++ class browser, tags

W.2 Tags Tables

C++ mode

U.11 C and Related Modes

C-

B.5 Kinds of User Input

cache of file names

M.15 File Name Cache

calendar

AC. The Calendar and the Diary

calendar and LaTeX

AC.5 LaTeX Calendar

calendar, first day of week

AC.1.2 Beginning or End of Week, Month or Year

call Lisp functions, command-line argument

AE.1 Action Arguments

capitalizing words

T.6 Case Conversion Commands

case conversion

T.6 Case Conversion Commands

case-sensitivity and tags search

W.2.6 Searching and Replacing with Tags Tables

categories of characters

K.5 Syntax of Regular Expressions

Celtic

Q. International Character Set Support

centering

T.5.3 Explicit Fill Commands

change buffers

N.1 Creating and Selecting Buffers

change log

W.1 Change Logs

Change Log mode

W.1 Change Logs

changes, undoing

D.4 Undoing Changes

changing file group (in Dired)

AB.7 Operating on Files

changing file owner (in Dired)

AB.7 Operating on Files

changing file permissions (in Dired)

AB.7 Operating on Files

character set (keyboard)

B.5 Kinds of User Input

characters (in text)

B.8 Character Set for Text

characters (in text)

J.11 How Text Is Displayed

characters which belong to a specific language

K.5 Syntax of Regular Expressions

checking out files

M.7.1.2 Concepts of Version Control

checking spelling

L.4 Checking and Correcting Spelling

Chinese

Q. International Character Set Support

Chinese calendar

AC.9.1 Supported Calendar Systems

choosing a major mode

R.1 How Major Modes are Chosen

ciphers

AC.30 Other Amusements

citing mail

Z.4.3 Citing Mail

class browser, C++

W.2 Tags Tables

click events

AD.4.10 Rebinding Mouse Buttons

clipboard

P.3 Using the Clipboard

clipboard support (Mac OS)

AG.2 International Character Set Support on the Mac

codepage, MS-DOS

AH.6 International Support on MS-DOS

coding systems

Q.7 Coding Systems

collision

M.3.2 Protection against Simultaneous Editing

color emulation on black-and-white printers

AC.20 Variables for PostScript Hardcopy

color of window

AE.8 Window Color Options

colors

P.12 Setting Frame Parameters

Column Number mode

J.10 Optional Mode Line Features

columns (and rectangles)

H.10 Rectangles

columns (indentation)

S. Indentation

columns, splitting

AC.23 Two-Column Editing

Comint mode

AC.15.3 Shell Mode

comint-highlight-input face

AC.15.2 Interactive Inferior Shell

comint-highlight-prompt face

AC.15.2 Interactive Inferior Shell

command

B.7 Keys and Commands

command history

E.5 Repeating Minibuffer Commands

command line arguments

AE. Command Line Arguments

comments

U.5 Manipulating Comments

comments on customized options

AD.2.2.2 Changing an Option

compare files (in Dired)

AB.10 File Comparison with Dired

comparing 3 files (diff3)

M.9 Comparing Files

comparing files

M.9 Comparing Files

compilation buffer, keeping current position at the end

V.1 Running Compilations under Emacs

compilation errors

V.1 Running Compilations under Emacs

Compilation mode

V.3 Compilation Mode

compilation under MS-DOS

AH.7 Subprocesses on MS-DOS

complete key

B.6 Keys

completion

E.3 Completion

completion (Lisp symbols)

U.8 Completion for Symbol Names

completion (symbol names)

U.8 Completion for Symbol Names

compose character

Q.13 Single-byte Character Set Support

compressing files (in Dired)

AB.7 Operating on Files

compression

M.11 Accessing Compressed Files

conflicts

M.7.6.3 Merging Branches

connecting to remote host

AC.15.10 Remote Host Shell

continuation line

D.8 Continuation Lines

Control

B.5 Kinds of User Input

control characters

B.5 Kinds of User Input

Control-Meta

U.4.1 Expressions with Balanced Parentheses

converting change log date style

W.1 Change Logs

converting Rmail file to mailbox format

AA.17 Converting an Rmail File to Inbox Format

converting text to upper or lower case

T.6 Case Conversion Commands

Coptic calendar

AC.9.1 Supported Calendar Systems

copy of every outgoing message

Z.2 Mail Header Fields

copying files

M.10 Miscellaneous File Operations

copying files (in Dired)

AB.7 Operating on Files

copying text

H.8 Yanking

CORBA IDL mode

U.11 C and Related Modes

correcting spelling

L.4 Checking and Correcting Spelling

CPerl mode

U.1 Major Modes for Programming Languages

crashes

M.5 Auto-Saving: Protection Against Disasters

creating files

M.2 Visiting Files

creating frames

P.7 Creating Frames

CRiSP mode

AC.27 Emulation

cryptanalysis

AC.30 Other Amusements

current buffer

N. Using Multiple Buffers

current function name in mode line

U.2.4 Which Function Mode

cursor

B.1 Point

cursor color, command-line argument

AE.8 Window Color Options

cursor in non-selected windows

J.13 Displaying the Cursor

cursor location

D.9 Cursor Position Information

cursor location, on MS-DOS

AH.4 Text Files and Binary Files

cursor motion

D.2 Changing the Location of Point

cursor shape on MS-DOS

AH.2 Display on MS-DOS

cursor, blinking

J.13 Displaying the Cursor

cursor, locating visually

J.13 Displaying the Cursor

customization

AD. Customization

customization buffer

AD.2.2 Easy Customization Interface

customization groups

AD.2.2.1 Customization Groups

customized options, saving

AD.2.2.2 Changing an Option

customizing faces

AD.2.2.3 Customizing Faces

customizing Lisp indentation

U.3.3 Customizing Lisp Indentation

cut and paste

Glossary

cut buffer

P.1 Mouse Commands for Editing

cutting and X

P.1 Mouse Commands for Editing

cutting text

H.7 Deletion and Killing

CVS

M.7.1.1 Supported Version Control Systems

cvs

M.7.5.4 Dired under VC

CVS Dired Mode

M.7.5.4 Dired under VC

cvs watch feature

M.7.10.3 Options specific for CVS

CVSREAD environment variable (CVS)

M.7.10.3 Options specific for CVS

CWarn mode

U.11.4 Other Commands for C Mode

Cyrillic

Q. International Character Set Support

Czech

Q. International Character Set Support

D

day of year

AC.4 Miscellaneous Calendar Commands

daylight savings time

AC.12 Daylight Savings Time

DBX

V.5 Running Debuggers Under Emacs

dead character

Q.13 Single-byte Character Set Support

debuggers

V.5 Running Debuggers Under Emacs

debugging Emacs, tricks and techniques

AD.10.3 Checklist for Bug Reports

debugging X problems

AE.13 X Resources

decoding mail messages (Rmail)

AA.14 Rmail and Coding Systems

decoding non-ASCII keyboard input on X

Q.9 Specifying a Coding System

default argument

E. The Minibuffer

default-frame-alist

P.7 Creating Frames

`default.el' file, not loading

AE.2 Initial Options

`default.el', the default init file

AD.7 The Init File, `~/.emacs'

defining keyboard macros

AD.3 Keyboard Macros

definitions, finding in Lisp sources

AC.28.4 Finding Function and Variable Definitions

defuns

U.2.2 Moving by Defuns

DEL vs BACKSPACE

AD.9.1 If DEL Fails to Delete

Delete Selection mode

H.7 Deletion and Killing

deleting auto-save files

AB.4 Flagging Many Files at Once

deleting blank lines

D.7 Blank Lines

deleting characters and lines

D.3 Erasing Text

deleting files (in Dired)

AB.3 Deleting Files with Dired

deleting some backup files

AB.4 Flagging Many Files at Once

deletion

H.7 Deletion and Killing

deletion (of files)

M.10 Miscellaneous File Operations

deletion (Rmail)

AA.4 Deleting Messages

Delphi mode

U.1 Major Modes for Programming Languages

desktop

AC.25 Saving Emacs Sessions

Devanagari

Q. International Character Set Support

developediment

AC.29 Dissociated Press

device for Emacs terminal I/O

AE.2 Initial Options

dialog boxes

P.17 Using Dialog Boxes

diary

AC.10 The Diary

diary file

AC.10.2 The Diary File

Diff mode

M.9 Comparing Files

diffs

M.9 Comparing Files

digest message

AA.16 Digest Messages

directional window selection

O.7 Window Handling Convenience Features and Customization

directories in buffer names

N.7.1 Making Buffer Names Unique

directory header lines

AB.12 Moving Over Subdirectories

directory listing

M.8 File Directories

directory listing on MS-DOS

AH.7 Subprocesses on MS-DOS

directory tracking

AC.15.5 Directory Tracking

Dired

AB. Dired, the Directory Editor

Dired sorting

AB.14 Updating the Dired Buffer

disable window system

AE.2 Initial Options

disabled command

AD.4.11 Disabling Commands

disabling remote files

M.13 Remote Files

DISPLAY environment variable

AE.6 Specifying the Display Name

display for Emacs frame

AE.2 Initial Options

display name (X Window System)

AE.6 Specifying the Display Name

display of line number

J.10 Optional Mode Line Features

doctor

AD.9.9 Help for Total Frustration

DOS codepages

AH.6 International Support on MS-DOS

DOS-style end-of-line display

Q.8 Recognizing Coding Systems

DOS-to-Unix conversion of files

AH.4 Text Files and Binary Files

double clicks

AD.4.10 Rebinding Mouse Buttons

double slash in file name

E.1 Minibuffers for File Names

down events

AD.4.10 Rebinding Mouse Buttons

downcase file names

AB.9 Transforming File Names in Dired

drag events

AD.4.10 Rebinding Mouse Buttons

drastic changes

M.4 Reverting a Buffer

dribble file

AD.10.3 Checklist for Bug Reports

DSSSL mode

U.1 Major Modes for Programming Languages

Dutch

Q. International Character Set Support

E

Ebrowse

W.2 Tags Tables

echo area

B.2 The Echo Area

Edebug

AD.10.3 Checklist for Bug Reports

editable fields (customization buffer)

AD.2.2.1 Customization Groups

editing binary files

AC.24 Editing Binary Files

editing in Picture mode

Y.1 Basic Editing in Picture Mode

editing level, recursive

AC.26 Recursive Editing Levels

EDITOR environment variable

AC.16 Using Emacs as a Server

EDT

AC.27 Emulation

Eldoc mode

U.6.3 Emacs Lisp Documentation Lookup

Eliza

AD.9.9 Help for Total Frustration

Emacs as a server

AC.16 Using Emacs as a Server

EMACS environment variable

AC.15.2 Interactive Inferior Shell

Emacs icon, a gnu

AE.12 Icons

Emacs initialization file

AD.7 The Init File, `~/.emacs'

Emacs-Lisp mode

V.8 Evaluating Emacs-Lisp Expressions

emacs.bash

AC.17 Invoking emacsclient

emacsclient

AC.16 Using Emacs as a Server

Emerge

W.3 Merging Files with Emerge

empty lines

J.5 Trailing Whitespace

emulating other editors

AC.27 Emulation

emulation of Brief

AC.27 Emulation

encoding of characters

Q. International Character Set Support

end-of-line conversion

Q.7 Coding Systems

end-of-line conversion on MS-DOS/MS-Windows

AH.4 Text Files and Binary Files

end-of-line conversion, mode-line indication

B.3 The Mode Line

Enriched mode

T.11 Editing Formatted Text

entering Emacs

C. Entering and Exiting Emacs

environment variables

AE.5 Environment Variables

environment variables (Mac OS)

AG.3 Environment Variables and Command Line Arguments.

environment variables for subshells

AC.15.2 Interactive Inferior Shell

environment variables in file names

M.1 File Names

environment variables, and non-ASCII characters

Q.2 Enabling Multibyte Characters

erasing characters and lines

D.3 Erasing Text

error log

V.1 Running Compilations under Emacs

error message in the echo area

B.2 The Echo Area

errors in init file

AE.2 Initial Options

ESC replacing META key

B.5 Kinds of User Input

escape sequences in files

Q.8 Recognizing Coding Systems

ESHELL environment variable

AC.15.2 Interactive Inferior Shell

etags program

W.2.2 Creating Tags Tables

Ethiopic

Q. International Character Set Support

Ethiopic calendar

AC.9.1 Supported Calendar Systems

Euro sign

Q.3 Language Environments

European character sets

Q.13 Single-byte Character Set Support

evaluate expression, command-line argument

AE.1 Action Arguments

exiting

C.1 Exiting Emacs

exiting recursive edit

AC.26 Recursive Editing Levels

expanding subdirectories in Dired

AB.11 Subdirectories in Dired

expansion (of abbrevs)

X. Abbrevs

expansion of C macros

U.11.4 Other Commands for C Mode

expansion of environment variables

M.1 File Names

expression

U.4.1 Expressions with Balanced Parentheses

expunging (Dired)

AB.3 Deleting Files with Dired

expunging (Rmail)

AA.4 Deleting Messages

F

face colors, setting

J.1 Using Multiple Typefaces

faces

J.1 Using Multiple Typefaces

faces for highlighting search matches

K.1 Incremental Search

faces under MS-DOS

AH.2 Display on MS-DOS

failed merges

M.9 Comparing Files

FFAP minor mode

AC.28.3 Finding Files and URLs at Point

file archives

M.12 File Archives

file comparison (in Dired)

AB.10 File Comparison with Dired

file database (locate)

AB.15 Dired and find

file dates

M.3.2 Protection against Simultaneous Editing

file directory

M.8 File Directories

file local variables

AD.2.5 Local Variables in Files

file management

AB. Dired, the Directory Editor

file name caching

M.15 File Name Cache

file names

M.1 File Names

file names (Mac OS)

AG.4 Volumes and Directories on the Mac

file names under MS-DOS

AH.3 File Names on MS-DOS

file names under Windows 95/NT

AH.3 File Names on MS-DOS

file names with non-ASCII characters

Q.9 Specifying a Coding System

file ownership, and backup

M.3.1.3 Copying vs. Renaming

file selection dialog

M.2 Visiting Files

file shadows

M.3.3 Shadowing Files

file truenames

M.6 File Name Aliases

file version in change log entries

W.1 Change Logs

files

M. File Handling

files, visiting and saving

M.2 Visiting Files

fill prefix

T.5.4 The Fill Prefix

filling text

T.5 Filling Text

find

M.15 File Name Cache

find and Dired

AB.15 Dired and find

finding file at point

AC.28.3 Finding Files and URLs at Point

finding files containing regexp matches (in Dired)

AB.6 Dired Marks vs. Flags

finding strings within text

K. Searching and Replacement

firewall, and accessing remote files

M.13 Remote Files

fixing incorrectly decoded mail messages

AA.14 Rmail and Coding Systems

flagging files (in Dired)

AB.3 Deleting Files with Dired

flagging many files for deletion (in Dired)

AB.4 Flagging Many Files at Once

flow control

AD.9.5 Spontaneous Entry to Incremental Search

Flyspell mode

L.4 Checking and Correcting Spelling

folding editing

T.8.5 Folding Editing

Follow mode

J.8 Follow Mode

font (default)

P.7 Creating Frames

font (principal)

P.12 Setting Frame Parameters

font for menus

AE.13 X Resources

Font Lock mode

J.2 Font Lock mode

font name (X Window System)

AE.7 Font Specification Options

font names (Mac OS)

AG.5 Specifying Fonts on the Mac

fonts and faces

AD.2.2.3 Customizing Faces

fonts for PostScript printing

AC.20 Variables for PostScript Hardcopy

fonts for various scripts

Q.3 Language Environments

fonts, emulating under MS-DOS

AH.2 Display on MS-DOS

fontsets

Q.10 Fontsets

foreground color, command-line argument

AE.8 Window Color Options

formatted text

T.11 Editing Formatted Text

formfeed

T.4 Pages

Fortran continuation lines

U.12.2.2 Continuation Lines

Fortran mode

U.12 Fortran Mode

Fortran77 and Fortran90

U.12 Fortran Mode

fortune cookies

Z.5 Mail Amusements

forwarding a message

AA.10 Sending Replies

frame size under MS-DOS

AH.2 Display on MS-DOS

frame title, command-line argument

AE.11 Frame Titles

frames

P. Frames and X Windows

frames on MS-DOS

AH.2 Display on MS-DOS

French Revolutionary calendar

AC.9.1 Supported Calendar Systems

fringe

J.1 Using Multiple Typefaces

FTP

M.13 Remote Files

function definition

B.7 Keys and Commands

function key

AD.4.1 Keymaps

function, move to beginning or end

U.2.2 Moving by Defuns

G

gamma correction

AE.13 X Resources

gateway, and remote file access with ange-ftp

M.13 Remote Files

GDB

V.5 Running Debuggers Under Emacs

geometry of Emacs window

AE.9 Options for Window Geometry

German

Q. International Character Set Support

getting help with keys

D.6 Help

Glasses mode

U.9 Glasses minor mode

Global Auto-Revert mode

M.4 Reverting a Buffer

global keymap

AD.4.1 Keymaps

global mark ring

H.6 The Global Mark Ring

global substitution

K.7 Replacement Commands

Gnome

P.3 Using the Clipboard

Gnus

AC.14 Gnus

Go Moku

AC.30 Other Amusements

Goto-address

AC.28.2 Activating URLs

graphic characters

D.1 Inserting Text

Greek

Q. International Character Set Support

Gregorian calendar

AC.9 Conversion To and From Other Calendars

growing minibuffer

E.2 Editing in the Minibuffer

GUD library

V.5 Running Debuggers Under Emacs

gzip

M.11 Accessing Compressed Files

H

handwriting

AC.19 PostScript Hardcopy

hard links (creation)

M.10 Miscellaneous File Operations

hard links (in Dired)

AB.7 Operating on Files

hard newline

T.11.2 Hard and Soft Newlines

hardcopy

AC.18 Hardcopy Output

head version

M.7.6 Multiple Branches of a File

header (TeX mode)

T.9.3 TeX Printing Commands

header line (Dired)

AB.12 Moving Over Subdirectories

headers (of mail message)

Z.2 Mail Header Fields

heading lines (Outline mode)

T.8.1 Format of Outlines

Hebrew

Q. International Character Set Support

Hebrew calendar

AC.9.1 Supported Calendar Systems

height of minibuffer

E.2 Editing in the Minibuffer

help

G. Help

hex editing

AC.24 Editing Binary Files

Hexl mode

AC.24 Editing Binary Files

Hide-ifdef mode

U.11.4 Other Commands for C Mode

hiding in Dired (Dired)

AB.13 Hiding Subdirectories

highlight current line

J.13 Displaying the Cursor

highlighting by matching

J.4 Interactive Highlighting by Matching

highlighting lines of text

J.4 Interactive Highlighting by Matching

highlighting matching parentheses

U.4.3 Automatic Display Of Matching Parentheses

highlighting region

H.2 Transient Mark Mode

Hindi

Q. International Character Set Support

history of commands

E.5 Repeating Minibuffer Commands

history of minibuffer input

E.4 Minibuffer History

history reference

AC.15.4.3 Shell History References

holidays

AC.6 Holidays

home directory shorthand

M.1 File Names

HOME directory under MS-DOS

AH.3 File Names on MS-DOS

hook

AD.2.3 Hooks

horizontal scrolling

J.7 Horizontal Scrolling

hourglass pointer display

J.12 Customization of Display

Hyper (under MS-DOS)

AH.1 Keyboard and Mouse on MS-DOS

hyperlinking

AC.28 Hyperlinking and Navigation Features

I

IBM graphics characters (MS-DOS)

AH.6 International Support on MS-DOS

Icomplete mode

E.3.4 Completion Options

Icon mode

U.1 Major Modes for Programming Languages

icons (X Window System)

AE.12 Icons

icons, tool bar

P.16 Tool Bars

identifiers, making long ones readable

U.9 Glasses minor mode

IDL mode

U.11 C and Related Modes

ignored file names, in completion

E.3.4 Completion Options

ignoriginal

AC.29 Dissociated Press

images, visiting

M.16 Convenience Features for Finding Files

in-situ subdirectory (Dired)

AB.11 Subdirectories in Dired

inbox file

AA.5 Rmail Files and Inboxes

incorrect fontification

J.2 Font Lock mode

incremental search

K.1 Incremental Search

incremental search, input method interference

Q.4 Input Methods

indentation

S. Indentation

indentation for comments

U.5.1 Comment Commands

indentation for programs

U.3 Indentation for Programs

index of buffer definitions

U.2.3 Imenu

indirect buffer

N.6 Indirect Buffers

indirect buffers and outlines

T.8.4 Viewing One Outline in Multiple Views

inferior process

V.1 Running Compilations under Emacs

inferior processes under MS-DOS

AH.7 Subprocesses on MS-DOS

Info

G.8 Other Help Commands

Info index completion

U.8 Completion for Symbol Names

init file

AD.7 The Init File, `~/.emacs'

init file, and non-ASCII characters

Q.2 Enabling Multibyte Characters

init file, default name under MS-DOS

AH.3 File Names on MS-DOS

init file, not loading

AE.2 Initial Options

initial options (command line)

AE. Command Line Arguments

initial-frame-alist

P.7 Creating Frames

input event

B.5 Kinds of User Input

input method, during incremental search

K.1 Incremental Search

input methods

Q.4 Input Methods

input with the keyboard

B.5 Kinds of User Input

insert file contents, command-line argument

AE.1 Action Arguments

inserted subdirectory (Dired)

AB.11 Subdirectories in Dired

inserting blank lines

D.7 Blank Lines

insertion

D.1 Inserting Text

interactive highlighting

J.4 Interactive Highlighting by Matching

international characters in `.emacs'

AD.7.1 Init File Syntax

international files from DOS/Windows systems

Q.7 Coding Systems

international scripts

Q. International Character Set Support

international support (MS-DOS)

AH.6 International Support on MS-DOS

interval operator (in regexps)

W.2.3 Etags Regexps

Intlfonts for PostScript printing

AC.20 Variables for PostScript Hardcopy

Intlfonts package, installation

Q.3 Language Environments

invisible lines

T.8 Outline Mode

IPA

Q. International Character Set Support

Islamic calendar

AC.9.1 Supported Calendar Systems

ISO Accents mode

Q.13 Single-byte Character Set Support

ISO commercial calendar

AC.9.1 Supported Calendar Systems

ISO Latin character sets

Q.13 Single-byte Character Set Support

iso-acc library

Q.13 Single-byte Character Set Support

iso-ascii library

Q.13 Single-byte Character Set Support

iso-transl library

Q.13 Single-byte Character Set Support

ispell program

L.4 Checking and Correcting Spelling

Iswitchb mode

N.7.2 Switching Between Buffers using Substrings

italic font

AD.2.2.3 Customizing Faces

J

Japanese

Q. International Character Set Support

jar

M.12 File Archives

Java class archives

M.12 File Archives

Java mode

U.11 C and Related Modes

JDB

V.5 Running Debuggers Under Emacs

Julian calendar

AC.9.1 Supported Calendar Systems

Julian day numbers

AC.9.1 Supported Calendar Systems

justification

T.5.3 Explicit Fill Commands

K

Kerberos POP authentication

AA.19 movemail and POP

key

B.6 Keys

key bindings

AD.4 Customizing Key Bindings

key rebinding, permanent

AD.7 The Init File, `~/.emacs'

key rebinding, this session

AD.4.5 Changing Key Bindings Interactively

key sequence

B.6 Keys

keyboard coding (Mac OS)

AG.1 Keyboard Input on the Mac

keyboard input

B.5 Kinds of User Input

keyboard macro

AD.3 Keyboard Macros

keyboard shortcuts

Glossary

keyboard translations

AD.5 Keyboard Translations

keymap

AD.4.1 Keymaps

kill ring

H.8 Yanking

killing buffers

N.4 Killing Buffers

killing characters and lines

D.3 Erasing Text

killing Emacs

C.1 Exiting Emacs

killing expressions

U.4.1 Expressions with Balanced Parentheses

killing rectangular areas of text

H.10 Rectangles

killing text

H.7 Deletion and Killing

Korean

Q. International Character Set Support

L

label (Rmail)

AA.8 Labels

landmark game

AC.30 Other Amusements

language environment, automatic selection on MS-DOS

AH.6 International Support on MS-DOS

language environments

Q.3 Language Environments

Lao

Q. International Character Set Support

LaTeX mode

T.9 TeX Mode

LaTeX references

T.9.4 TeX Mode Miscellany

Latin

Q. International Character Set Support

Latin-1 TeX encoding

T.9.4 TeX Mode Miscellany

Latin-1, Latin-2 and Latin-3 input mode

Q.13 Single-byte Character Set Support

lazy search highlighting

K.1 Incremental Search

leading

AE.13 X Resources

leaving Emacs

C.1 Exiting Emacs

Leim package

Q.4 Input Methods

LessTif Widget X Resources

AE.15 LessTif Menu X Resources

libraries

V.7 Libraries of Lisp Code for Emacs

Life

AC.30 Other Amusements

line number commands

D.9 Cursor Position Information

line number display

J.10 Optional Mode Line Features

line spacing

AE.13 X Resources

line wrapping

D.8 Continuation Lines

line-drawing characters (MS-DOS)

AH.6 International Support on MS-DOS

lines, highlighting

J.4 Interactive Highlighting by Matching

Lisp definitions, finding in sources

AC.28.4 Finding Function and Variable Definitions

Lisp editing

U. Editing Programs

Lisp editing

W. Maintaining Programs

Lisp files byte-compiled by XEmacs

V.7 Libraries of Lisp Code for Emacs

Lisp files, and multibyte operation

Q.2 Enabling Multibyte Characters

Lisp functions specific to Mac OS

AG.6 Mac-Specific Lisp Functions

Lisp string syntax

AD.7.1 Init File Syntax

Lisp symbol completion

U.8 Completion for Symbol Names

list commands

U.4.2 Moving in the Parenthesis Structure

listing current buffers

N.2 Listing Existing Buffers

listing system fonts

AE.7 Font Specification Options

load init file of another user

AE.2 Initial Options

loading Lisp code

V.7 Libraries of Lisp Code for Emacs

loading Lisp libraries automatically

AD.7.2 Init File Examples

loading Lisp libraries, command-line argument

AE.1 Action Arguments

loading several files (in Dired)

AB.7 Operating on Files

local back end (version control)

M.7.7.2 Local Version Control

local keymap

AD.4.3 Local Keymaps

local variables

AD.2.4 Local Variables

local variables in files

AD.2.5 Local Variables in Files

local version control

M.7.7.2 Local Version Control

locale, date format

M.3.4 Updating Time Stamps Automatically

locales

Q.3 Language Environments

location of point

D.9 Cursor Position Information

locking (CVS)

M.7.10.3 Options specific for CVS

locking and version control

M.7.1.2 Concepts of Version Control

locking files

M.3.2 Protection against Simultaneous Editing

locking, non-strict (RCS)

M.7.10.2 Options for RCS and SCCS

logging keystrokes

AD.10.3 Checklist for Bug Reports

long file names in DOS box under Windows 95/NT

AH.3 File Names on MS-DOS

looking for a subject in documentation

G. Help

lpr usage under MS-DOS

AH.5 Printing and MS-DOS

Lucid Widget X Resources

AE.14 Lucid Menu X Resources

lzh

M.12 File Archives

M

M-

B.5 Kinds of User Input

M4 mode

U.1 Major Modes for Programming Languages

Mac OS

AG. Emacs and the Mac OS

Mac Roman coding system

AG.2 International Character Set Support on the Mac

Macintosh

AG. Emacs and the Mac OS

Macintosh end-of-line conversion

Q.7 Coding Systems

Macintosh key bindings

AC.27 Emulation

macro expansion in C

U.11.4 Other Commands for C Mode

mail

Z. Sending Mail

mail (on mode line)

J.10 Optional Mode Line Features

mail aliases

Z.3 Mail Aliases

MAIL environment variable

AA.5 Rmail Files and Inboxes

Mail mode

Z.4 Mail Mode

mail-composition methods

Z.6 Mail-Composition Methods

MAILHOST environment variable

AA.19 movemail and POP

mailrc file

Z.3 Mail Aliases

major modes

R. Major Modes

make

V.1 Running Compilations under Emacs

Makefile mode

U.1 Major Modes for Programming Languages

making pictures out of text characters

Y. Editing Pictures

manipulating paragraphs

T.3 Paragraphs

manipulating sentences

T.2 Sentences

manipulating text

T. Commands for Human Languages

manual page

U.6.2 Man Page Lookup

manual pages, on MS-DOS/MS-Windows

U.6.2 Man Page Lookup

manual version backups

M.7.7.1 Version Backups

manuals, on-line

G.8 Other Help Commands

Marathi

Q. International Character Set Support

mark

H. The Mark and the Region

mark ring

H.5 The Mark Ring

marking executable files (in Dired)

AB.6 Dired Marks vs. Flags

marking many files (in Dired)

AB.6 Dired Marks vs. Flags

marking sections of text

H.4 Commands to Mark Textual Objects

marking subdirectories (in Dired)

AB.6 Dired Marks vs. Flags

marking symlinks (in Dired)

AB.6 Dired Marks vs. Flags

Markov chain

AC.29 Dissociated Press

master file

M.7.1.2 Concepts of Version Control

matching parentheses

U.4.3 Automatic Display Of Matching Parentheses

matching parenthesis and braces, moving to

U.4.2 Moving in the Parenthesis Structure

maximum buffer size exceeded, error message

M.2 Visiting Files

Mayan calendar

AC.9.1 Supported Calendar Systems

Mayan calendar round

AC.9.4 Converting from the Mayan Calendar

Mayan haab calendar

AC.9.4 Converting from the Mayan Calendar

Mayan long count

AC.9.4 Converting from the Mayan Calendar

Mayan tzolkin calendar

AC.9.4 Converting from the Mayan Calendar

memory full

AD.9.6 Running out of Memory

menu bar

B.4 The Menu Bar

Menu Bar mode

P.15 Menu Bars

Menu X Resources (LessTif widgets)

AE.15 LessTif Menu X Resources

Menu X Resources (Lucid widgets)

AE.14 Lucid Menu X Resources

merge buffer (Emerge)

W.3.1 Overview of Emerge

merges, failed

M.9 Comparing Files

merging changes

M.7.6.3 Merging Branches

merging files

W.3 Merging Files with Emerge

message

Z. Sending Mail

Message mode for sending mail

Z.6 Mail-Composition Methods

message number

AA.1 Basic Concepts of Rmail

messages saved from echo area

B.2 The Echo Area

Meta

B.5 Kinds of User Input

Meta (Mac OS)

AG.1 Keyboard Input on the Mac

Meta (under MS-DOS)

AH.1 Keyboard and Mouse on MS-DOS

Meta commands and words

T.1 Words

Metafont mode

U.1 Major Modes for Programming Languages

MH mail interface

Z.6 Mail-Composition Methods

Midnight mode

N.4 Killing Buffers

minibuffer

E. The Minibuffer

minibuffer history

E.4 Minibuffer History

minibuffer keymaps

AD.4.4 Minibuffer Keymaps

minor mode keymap

AD.4.3 Local Keymaps

minor modes

AD.1 Minor Modes

mistakes, correcting

L. Commands for Fixing Typos

mode hook

U.1 Major Modes for Programming Languages

mode line

B.3 The Mode Line

mode line (MS-DOS)

AH.6 International Support on MS-DOS

mode line, 3D appearance

J.10 Optional Mode Line Features

mode line, mouse

P.6 Mode Line Mouse Commands

mode, Abbrev

X.1 Abbrev Concepts

mode, archive

M.12 File Archives

mode, Auto Compression

M.11 Accessing Compressed Files

mode, Auto Fill

T.5.1 Auto Fill Mode

mode, Auto Save

M.5 Auto-Saving: Protection Against Disasters

mode, Auto-Revert

M.4 Reverting a Buffer

mode, C

U.11 C and Related Modes

mode, Column Number

J.10 Optional Mode Line Features

mode, Comint

AC.15.3 Shell Mode

mode, Compilation

V.3 Compilation Mode

mode, CORBA IDL

U.11 C and Related Modes

mode, CRiSP

AC.27 Emulation

mode, Delete Selection

H.7 Deletion and Killing

mode, Emacs-Lisp

V.8 Evaluating Emacs-Lisp Expressions

mode, Enriched

T.11 Editing Formatted Text

mode, Follow

J.8 Follow Mode

mode, Font Lock

J.2 Font Lock mode

mode, Fortran

U.12 Fortran Mode

mode, Global Auto-Revert

M.4 Reverting a Buffer

mode, Hexl

AC.24 Editing Binary Files

mode, Iswitchb

N.7.2 Switching Between Buffers using Substrings

mode, Java

U.11 C and Related Modes

mode, LaTeX

T.9 TeX Mode

mode, Mail

Z.4 Mail Mode

mode, major

R. Major Modes

mode, Menu Bar

P.15 Menu Bars

mode, minor

AD.1 Minor Modes

mode, Mouse Wheel

P.14 Scrolling With "Wheeled" Mice

mode, MSB

N.7.3 Customizing Buffer Menus

mode, Objective C

U.11 C and Related Modes

mode, Outline

T.8 Outline Mode

mode, Overwrite

AD.1 Minor Modes

mode, Paragraph-Indent Text

T.7 Text Mode

mode, PC selection

AC.27 Emulation

mode, Pike

U.11 C and Related Modes

mode, Scroll Bar

P.13 Scroll Bars

mode, Scroll-all

O.7 Window Handling Convenience Features and Customization

mode, Shell

AC.15.3 Shell Mode

mode, SliTeX

T.9 TeX Mode

mode, tar

M.12 File Archives

mode, Term

AC.15.8 Term Mode

mode, TeX

T.9 TeX Mode

mode, Text

T.7 Text Mode

mode, Tool Bar

P.16 Tool Bars

mode, Transient Mark

H.2 Transient Mark Mode

mode, View

M.10 Miscellaneous File Operations

mode, Winner

O.7 Window Handling Convenience Features and Customization

modes for programming languages

U.1 Major Modes for Programming Languages

modes, Refill

T.5.2 Refill Mode

modification dates

M.3.4 Updating Time Stamps Automatically

modified (buffer)

M.2 Visiting Files

Modula2 mode

U.1 Major Modes for Programming Languages

moon, phases of

AC.8 Phases of the Moon

Morse code

AC.30 Other Amusements

Motif key bindings

AC.27 Emulation

mouse

AD.4.1 Keymaps

mouse avoidance

P.19 Mouse Avoidance

mouse button events

AD.4.10 Rebinding Mouse Buttons

mouse buttons (what they do)

P.1 Mouse Commands for Editing

mouse on mode line

P.6 Mode Line Mouse Commands

mouse pointer color, command-line argument

AE.8 Window Color Options

mouse support under MS-DOS

AH.1 Keyboard and Mouse on MS-DOS

mouse wheel

P.14 Scrolling With "Wheeled" Mice

Mouse Wheel minor mode

P.14 Scrolling With "Wheeled" Mice

mouse, set number of buttons

AH.1 Keyboard and Mouse on MS-DOS

move to beginning or end of function

U.2.2 Moving by Defuns

movemail

AA.19 movemail and POP

movemail program

AA.19 movemail and POP

movement

D.2 Changing the Location of Point

moving inside the calendar

AC.1 Movement in the Calendar

moving point

D.2 Changing the Location of Point

moving text

H.8 Yanking

moving the cursor

D.2 Changing the Location of Point

MS Windows

P. Frames and X Windows

MS-DOG

AH. Emacs and MS-DOS

MS-DOS end-of-line conversion

Q.7 Coding Systems

MS-DOS peculiarities

AH. Emacs and MS-DOS

MS-Windows codepages

AH.6 International Support on MS-DOS

MSB mode

N.7.3 Customizing Buffer Menus

MULE

Q. International Character Set Support

multibyte characters

Q. International Character Set Support

multibyte operation, and Lisp files

Q.2 Enabling Multibyte Characters

multiple `*info*' and `*Help*' buffers

N.6 Indirect Buffers

multiple displays

P.10 Multiple Displays

multiple views of outline

T.8.4 Viewing One Outline in Multiple Views

multiple windows in Emacs

O. Multiple Windows

multiple-file search and replace

W.2.6 Searching and Replacing with Tags Tables

mustatement

AC.29 Dissociated Press

N

named configurations (RCS)

M.7.8.2 Snapshot Caveats

narrowing

AC.22 Narrowing

narrowing, and line number display

J.10 Optional Mode Line Features

navigation

AC.28 Hyperlinking and Navigation Features

`net use', and printing on MS-Windows

AH.5 Printing and MS-DOS

networked printers (MS-Windows)

AH.5 Printing and MS-DOS

newline

D.1 Inserting Text

newlines, hard and soft

T.11.2 Hard and Soft Newlines

NFS and quitting

AD.8 Quitting and Aborting

nil

Glossary

non-ASCII characters in `.emacs'

AD.7.1 Init File Syntax

non-ASCII keys, binding

AD.4.9 Non-ASCII Characters on the Keyboard

non-greedy regexp matching

K.5 Syntax of Regular Expressions

non-integral number of lines in a window

J.10 Optional Mode Line Features

non-strict locking (RCS)

M.7.10.2 Options for RCS and SCCS

non-window terminals

P.20 Non-Window Terminals

nonincremental search

K.2 Nonincremental Search

normal hook

AD.2.3 Hooks

nroff

T.10 Nroff Mode

NSA

Z.5 Mail Amusements

numeric arguments

D.10 Numeric Arguments

O

Objective C mode

U.11 C and Related Modes

Octave mode

U.1 Major Modes for Programming Languages

on-line manuals

G.8 Other Help Commands

open-parenthesis in leftmost column

U.2.1 Left Margin Convention

OpenWindows

P.3 Using the Clipboard

operating on files in Dired

AB.7 Operating on Files

operations on a marked region

H.3 Operating on the Region

option, user

AD.2 Variables

options (command line)

AE. Command Line Arguments

other editors

AC.27 Emulation

out of memory

AD.9.6 Running out of Memory

Outline mode

T.8 Outline Mode

outline with multiple views

T.8.4 Viewing One Outline in Multiple Views

outragedy

AC.29 Dissociated Press

Overwrite mode

AD.1 Minor Modes

P

page-at-a-time

AC.15.9 Page-At-A-Time Output

pages

T.4 Pages

Paragraph-Indent Text mode

T.7 Text Mode

paragraphs

T.3 Paragraphs

parentheses, displaying matches

U.4.3 Automatic Display Of Matching Parentheses

parentheses, moving across

U.4.2 Moving in the Parenthesis Structure

parenthesis in column zero and fontification

J.2 Font Lock mode

parenthetical groupings

U.4.2 Moving in the Parenthesis Structure

Partial Completion mode

E.3.4 Completion Options

parts of the screen

B. The Organization of the Screen

pasting

H.8 Yanking

pasting and X

P.1 Mouse Commands for Editing

patches

M.9 Comparing Files

patches, sending

AD.10.4 Sending Patches for GNU Emacs

PC key bindings

AC.27 Emulation

PC selection

AC.27 Emulation

PC Selection minor mode

AC.27 Emulation

PCL-CVS

M.7.5.4 Dired under VC

PDB

V.5 Running Debuggers Under Emacs

per-buffer variables

AD.2.4 Local Variables

Perl mode

U.1 Major Modes for Programming Languages

Perldb

V.5 Running Debuggers Under Emacs

Persian calendar

AC.9.1 Supported Calendar Systems

phases of the moon

AC.8 Phases of the Moon

Picture mode and rectangles

Y.4 Picture Mode Rectangle Commands

pictures

Y. Editing Pictures

Pike mode

U.11 C and Related Modes

point

B.1 Point

point location

D.9 Cursor Position Information

point location, on MS-DOS

AH.4 Text Files and Binary Files

Polish

Q. International Character Set Support

Pong game

AC.30 Other Amusements

POP inboxes

AA.19 movemail and POP

position and size of Emacs frame

AE.9 Options for Window Geometry

PostScript mode

U.1 Major Modes for Programming Languages

prefix arguments

D.10 Numeric Arguments

prefix key

B.6 Keys

preprocessor highlighting

U.11.4 Other Commands for C Mode

presidentagon

AC.29 Dissociated Press

pretty-printer

U.3 Indentation for Programs

primary Rmail file

AA.1 Basic Concepts of Rmail

primary selection

P.1 Mouse Commands for Editing

printing files (in Dired)

AB.7 Operating on Files

printing under MS-DOS

AH.7 Subprocesses on MS-DOS

program building

V. Compiling and Testing Programs

program editing

U. Editing Programs

program editing

W. Maintaining Programs

Prolog mode

U.1 Major Modes for Programming Languages

prompt

E. The Minibuffer

prompt, shell

AC.15.4.3 Shell History References

properbose

AC.29 Dissociated Press

puzzles

AC.30 Other Amusements

Q

query replace

K.7.4 Query Replace

quitting

AD.8 Quitting and Aborting

quitting

AD.8 Quitting and Aborting

quitting (in search)

K.1 Incremental Search

quitting Emacs

C.1 Exiting Emacs

quitting on MS-DOS

AH.1 Keyboard and Mouse on MS-DOS

quoting

D.1 Inserting Text

quoting file names

M.14 Quoted File Names

R

RCS

M.7.1.1 Supported Version Control Systems

read-only buffer

N.3 Miscellaneous Buffer Operations

read-only text, killing

H.7 Deletion and Killing

reading mail

AA. Reading Mail with Rmail

reading netnews

AC.14 Gnus

rebinding keys, permanently

AD.7 The Init File, `~/.emacs'

rebinding major mode keys

AD.4.3 Local Keymaps

rebinding mouse buttons

AD.4.10 Rebinding Mouse Buttons

rebinding non-ASCII keys

AD.4.9 Non-ASCII Characters on the Keyboard

rectangle

H.10 Rectangles

rectangles and Picture mode

Y.4 Picture Mode Rectangle Commands

recursive copying

AB.7 Operating on Files

recursive deletion

AB.3 Deleting Files with Dired

recursive editing level

AC.26 Recursive Editing Levels

redefining keys, this session

AD.4.5 Changing Key Bindings Interactively

references, LaTeX

T.9.4 TeX Mode Miscellany

Refill minor mode

T.5.2 Refill Mode

refilling text, word processor style

T.5.2 Refill Mode

refreshing displayed files

AB.14 Updating the Dired Buffer

RefTeX package

T.9.4 TeX Mode Miscellany

regexp

K.4 Regular Expression Search

region

H. The Mark and the Region

region face

J.1 Using Multiple Typefaces

region highlighting

H.2 Transient Mark Mode

registered file

M.7.1.2 Concepts of Version Control

registers

I. Registers

Registry (MS-Windows)

AE.13 X Resources

regular expression

K.4 Regular Expression Search

related files

U.11.4 Other Commands for C Mode

reload files

AC.25 Saving Emacs Sessions

remember editing session

AC.25 Saving Emacs Sessions

remote file access

M.13 Remote Files

remote host

AC.15.10 Remote Host Shell

remote repositories (CVS)

M.7.7 Remote Repositories

remote repositories (CVS)

M.7.10.3 Options specific for CVS

renaming files (in Dired)

AB.7 Operating on Files

repeating a command

D.11 Repeating a Command

replacement

K.7 Replacement Commands

reply to a message

AA.10 Sending Replies

REPLYTO environment variable

Z.2 Mail Header Fields

reporting bugs

AD.10.3 Checklist for Bug Reports

reread a file

M.4 Reverting a Buffer

resizing minibuffer

E.2 Editing in the Minibuffer

resolving conflicts

M.7.6.3 Merging Branches

resource name, command-line argument

AE.13 X Resources

resource values, command-line argument

AE.13 X Resources

resources

AE.13 X Resources

restore session

AC.25 Saving Emacs Sessions

restriction

AC.22 Narrowing

retrying a failed message

AA.10 Sending Replies

reverse order in POP inboxes

AA.19 movemail and POP

reverse video, command-line argument

AE.8 Window Color Options

Rlogin

AC.15.10 Remote Host Shell

Rmail

AA. Reading Mail with Rmail

Romanian

Q. International Character Set Support

rot13 code

AA.18 Reading Rot13 Messages

running a hook

AD.2.3 Hooks

running Lisp functions

V. Compiling and Testing Programs

S

s-region package

AC.27 Emulation

saved echo area messages

B.2 The Echo Area

Saveplace

AC.25 Saving Emacs Sessions

saving files

M.2 Visiting Files

saving fuile name in a register

I.6 Keeping File Names in Registers

saving keyboard macros

AD.3.2 Naming and Saving Keyboard Macros

saving number in a register

I.5 Keeping Numbers in Registers

saving option value

AD.2.2.2 Changing an Option

saving position in a register

I.1 Saving Positions in Registers

saving rectangle in a register

I.3 Saving Rectangles in Registers

saving sessions

AC.25 Saving Emacs Sessions

saving text in a register

I.2 Saving Text in Registers

saving window configuration in a register

I.4 Saving Window Configurations in Registers

SCCS

M.7.1.1 Supported Version Control Systems

screen

B. The Organization of the Screen

Scroll Bar mode

P.13 Scroll Bars

Scroll-all mode

O.7 Window Handling Convenience Features and Customization

scrolling

J.6 Scrolling

scrolling all windows

AC.27 Emulation

scrolling in the calendar

AC.2 Scrolling in the Calendar

scrolling windows together

O.7 Window Handling Convenience Features and Customization

SDB

V.5 Running Debuggers Under Emacs

search and replace in multiple files

W.2.6 Searching and Replacing with Tags Tables

search and replace in multiple files (in Dired)

AB.7 Operating on Files

search multiple files (in Dired)

AB.7 Operating on Files

search-and-replace commands

K.7 Replacement Commands

searching

K. Searching and Replacement

searching documentation efficiently

G. Help

searching for non-ASCII characters

K.1 Incremental Search

searching in Rmail

AA.3 Moving Among Messages

secondary selection

P.2 Secondary Selection

sections of manual pages

U.6.2 Man Page Lookup

selected buffer

N. Using Multiple Buffers

selected window

O.1 Concepts of Emacs Windows

selecting buffers in other windows

O.4 Displaying in Another Window

selection, PC

AC.27 Emulation

selection, primary

P.1 Mouse Commands for Editing

selective display

J.9 Selective Display

selective undo

D.4 Undoing Changes

self-documentation

G. Help

sending mail

Z. Sending Mail

sending patches for GNU Emacs

AD.10.4 Sending Patches for GNU Emacs

sentences

T.2 Sentences

server, using Emacs as

AC.16 Using Emacs as a Server

setting a mark

H. The Mark and the Region

setting option value

AD.2.2.2 Changing an Option

setting variables

AD.2.1 Examining and Setting Variables

sexp

U.4.1 Expressions with Balanced Parentheses

shadow files

M.3.3 Shadowing Files

shell commands

AC.15 Running Shell Commands from Emacs

shell commands, Dired

AB.8 Shell Commands in Dired

SHELL environment variable

AC.15.2 Interactive Inferior Shell

Shell mode

AC.15.3 Shell Mode

shell scripts, and local file variables

AD.2.5 Local Variables in Files

Shell-script mode

U.1 Major Modes for Programming Languages

Show Paren mode

U.4.3 Automatic Display Of Matching Parentheses

shy group, in regexp

K.5 Syntax of Regular Expressions

Simula mode

U.1 Major Modes for Programming Languages

simultaneous editing

M.3.2 Protection against Simultaneous Editing

single-frame terminals

P.20 Non-Window Terminals

site init file

AD.7 The Init File, `~/.emacs'

`site-start.el' file, not loading

AE.2 Initial Options

`site-start.el', the site startup file

AD.7 The Init File, `~/.emacs'

size of minibuffer

E.2 Editing in the Minibuffer

slashes repeated in file name

E.1 Minibuffers for File Names

SliTeX mode

T.9 TeX Mode

Slovak

Q. International Character Set Support

Slovenian

Q. International Character Set Support

slow display during scrolling

J.2 Font Lock mode

Smerge mode

M.9 Comparing Files

Snake

AC.30 Other Amusements

snapshots and version control

M.7.8 Snapshots

soft newline

T.11.2 Hard and Soft Newlines

solitaire

AC.30 Other Amusements

sorting

AC.21 Sorting Text

sorting Dired buffer

AB.14 Updating the Dired Buffer

Spanish

Q. International Character Set Support

specify default font from the command line

AE.7 Font Specification Options

speedbar

P.9 Making and Using a Speedbar Frame

spell-checking the active region

L.4 Checking and Correcting Spelling

spelling, checking and correcting

L.4 Checking and Correcting Spelling

splitting columns

AC.23 Two-Column Editing

standard fontset

Q.11 Defining fontsets

start iconified, command-line argument

AE.12 Icons

starting Emacs

C. Entering and Exiting Emacs

startup (command line arguments)

AE. Command Line Arguments

startup (init file)

AD.7 The Init File, `~/.emacs'

startup fontset

Q.11 Defining fontsets

string substitution

K.7 Replacement Commands

string syntax

AD.7.1 Init File Syntax

StudlyCaps

AC.30 Other Amusements

StudlyCaps, making them readable

U.9 Glasses minor mode

style (for indentation)

U.3.5 Customizing C Indentation

subdirectories in Dired

AB.11 Subdirectories in Dired

subscribe groups

AC.14.3 Summary of Gnus Commands

subshell

AC.15 Running Shell Commands from Emacs

subtree (Outline mode)

T.8.3 Outline Visibility Commands

summary (Rmail)

AA.11 Summaries

summing time intervals

AC.13 Summing Time Intervals

sunrise and sunset

AC.7 Times of Sunrise and Sunset

Super (under MS-DOS)

AH.1 Keyboard and Mouse on MS-DOS

suspending

C.1 Exiting Emacs

suspicious constructions in C, C++

U.11.4 Other Commands for C Mode

switch buffers

N.1 Creating and Selecting Buffers

switches (command line)

AE. Command Line Arguments

symlinks (in Dired)

AB.7 Operating on Files

synchronizing windows

J.8 Follow Mode

synchronous X mode

AE.13 X Resources

syntax highlighting and coloring

J.2 Font Lock mode

syntax of regexps

K.5 Syntax of Regular Expressions

syntax table

AD.6 The Syntax Table

T

t

Glossary

tab stops

S.2 Tab Stops

tables, indentation for

S.2 Tab Stops

tags

U.2.3 Imenu

tags table

W.2 Tags Tables

tags, C++

W.2 Tags Tables

tags-based completion

U.8 Completion for Symbol Names

Tar mode

M.12 File Archives

Tcl mode

U.1 Major Modes for Programming Languages

techniquitous

AC.29 Dissociated Press

television

H.8.2 Appending Kills

Telnet

AC.15.10 Remote Host Shell

TERM environment variable

AD.10.3 Checklist for Bug Reports

Term mode

AC.15.8 Term Mode

terminal emulators, mouse support

P.21 Using a Mouse in Terminal Emulators

termscript file

AD.10.3 Checklist for Bug Reports

Tetris

AC.30 Other Amusements

TeX mode

T.9 TeX Mode

TEXEDIT environment variable

AC.16 Using Emacs as a Server

TEXINPUTS environment variable

T.9.3 TeX Printing Commands

text

T. Commands for Human Languages

text and binary files on MS-DOS/MS-Windows

AH.4 Text Files and Binary Files

text colors, from command line

AE.8 Window Color Options

Text mode

T.7 Text Mode

text/enriched MIME format

T.11 Editing Formatted Text

Thai

Q. International Character Set Support

Tibetan

Q. International Character Set Support

time (on mode line)

J.10 Optional Mode Line Features

time intervals, summing

AC.13 Summing Time Intervals

time stamps

M.3.4 Updating Time Stamps Automatically

timeclock

AC.13 Summing Time Intervals

toggling marks (in Dired)

AB.6 Dired Marks vs. Flags

Tool Bar mode

P.16 Tool Bars

tooltips

G.9 Help on Active Text and Tooltips

tooltips with GUD

V.5.5 GUD Tooltips

top level

B.3 The Mode Line

tower of Hanoi

AC.30 Other Amusements

TPU

AC.27 Emulation

trailing whitespace

J.5 Trailing Whitespace

Transient Mark mode

H.2 Transient Mark Mode

transposition of expressions

U.4.1 Expressions with Balanced Parentheses

triple clicks

AD.4.10 Rebinding Mouse Buttons

truenames of files

M.6 File Name Aliases

truncation

D.8 Continuation Lines

trunk (version control)

M.7.6 Multiple Branches of a File

Turkish

Q. International Character Set Support

turn multibyte support on or off

Q.2 Enabling Multibyte Characters

two directories (in Dired)

AB.7 Operating on Files

two-column editing

AC.23 Two-Column Editing

typos, fixing

L. Commands for Fixing Typos

U

unbalanced parentheses and quotes

U.4 Commands for Editing with Parentheses

uncompression

M.11 Accessing Compressed Files

undeletion (Rmail)

AA.4 Deleting Messages

undigestify

AA.16 Digest Messages

undisplayable characters

Q.1 Introduction to International Character Sets

undo

D.4 Undoing Changes

undo limit

D.4 Undoing Changes

undoing window configuration changes

O.7 Window Handling Convenience Features and Customization

Unibyte operation

Q.13 Single-byte Character Set Support

unibyte operation (MS-DOS)

AH.6 International Support on MS-DOS

unibyte operation, and Lisp files

Q.2 Enabling Multibyte Characters

unibyte operation, command-line argument

AE.2 Initial Options

unibyte operation, environment variable

AE.5.1 General Variables

unique buffer names

N.7.1 Making Buffer Names Unique

unmarking files (in Dired)

AB.6 Dired Marks vs. Flags

unsubscribe groups

AC.14.3 Summary of Gnus Commands

untranslated file system

AH.4 Text Files and Binary Files

unzip archives

M.12 File Archives

upcase file names

AB.9 Transforming File Names in Dired

updating Dired buffer

AB.14 Updating the Dired Buffer

URLs

AC.28.1 Following URLs

URLs, activating

AC.28.2 Activating URLs

user name for remote file access

M.13 Remote Files

user option

AD.2 Variables

userenced

AC.29 Dissociated Press

using tab stops in making tables

S.2 Tab Stops

usual erasure key

AD.9.1 If DEL Fails to Delete

V

variable

AD.2 Variables

vc-resolve-conflicts

M.7.6.3 Merging Branches

version backups

M.7.7.1 Version Backups

version control

M.7 Version Control

VERSION_CONTROL environment variable

M.3.1.1 Single or Numbered Backups

VHDL mode

U.1 Major Modes for Programming Languages

vi

AC.27 Emulation

Vietnamese

Q. International Character Set Support

View mode

M.10 Miscellaneous File Operations

viewing

M.10 Miscellaneous File Operations

views of an outline

T.8.4 Viewing One Outline in Multiple Views

visiting files

M.2 Visiting Files

visiting files, command-line argument

AE.1 Action Arguments

visiting image files

M.16 Convenience Features for Finding Files

W

watching files (CVS)

M.7.10.3 Options specific for CVS

Web

AC.28.1 Following URLs

weeks, which day they start on

AC.1.2 Beginning or End of Week, Month or Year

wheel, mouse

P.14 Scrolling With "Wheeled" Mice

whitespace, trailing

J.5 Trailing Whitespace

wide block cursor

J.13 Displaying the Cursor

widening

AC.22 Narrowing

width and height of Emacs frame

AE.9 Options for Window Geometry

width of the scroll bar

P.13 Scroll Bars

wildcard characters in file names

M.2 Visiting Files

Windmove package

O.7 Window Handling Convenience Features and Customization

window configuration changes, undoing

O.7 Window Handling Convenience Features and Customization

Windows clipboard support

AH.1 Keyboard and Mouse on MS-DOS

windows in Emacs

O. Multiple Windows

windows, synchronizing

J.8 Follow Mode

Winner mode

O.7 Window Handling Convenience Features and Customization

word processing

T.11 Editing Formatted Text

word search

K.3 Word Search

word wrap

T.5.1 Auto Fill Mode

words

T.1 Words

words, case conversion

T.6 Case Conversion Commands

WordStar

AC.27 Emulation

work file

M.7.1.2 Concepts of Version Control

World Wide Web

AC.28.1 Following URLs

wrapping

D.8 Continuation Lines

WYSIWYG

T.11 Editing Formatted Text

X

X clipboard

P.3 Using the Clipboard

X cutting and pasting

P.1 Mouse Commands for Editing

X resources, `~/.Xdefaults' file

AE.13 X Resources

XDB

V.5 Running Debuggers Under Emacs

xon-xoff

AD.9.5 Spontaneous Entry to Incremental Search

xterm, mouse support

P.21 Using a Mouse in Terminal Emulators

Y

yahrzeits

AC.9.3 Converting From Other Calendars

yanking

H.8 Yanking

yanking previous kills

H.8.3 Yanking Earlier Kills

Z

zip

M.12 File Archives

Zippy

AC.30 Other Amusements

Zmacs mode

H.2 Transient Mark Mode

zoo

M.12 File Archives

Jump to:

" ( * - . / 8 ?
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

[Top]

[Contents]

[Index]

[ ? ]

Footnotes

(1)

On terminals that support Latin-1 characters, the character shown after `Char:' is displayed as the actual glyph of A with grave accent.
(2)

Some systems use Mouse-3 for a mode-specific menu. We took a survey of users, and found they preferred to keep Mouse-3 for selecting and killing regions. Hence the decision to use C-Mouse-3 for this menu.
(3)

Placing it at the left is usually more useful with overlapping frames with text starting at the left margin.
(4)

If you run Emacs on X, you need to inform the X server about the location of the newly installed fonts with the following commands:
 xset fp+ /usr/local/share/emacs/fonts
 xset fp rehash
(5)

If more than one of these is set, the first one that is nonempty specifies your locale for this purpose.
(6)

It is also specified for MIME `text/*' bodies and in other network transport contexts. It is different from the SGML reference syntax record-start/record-end format which Emacs doesn't support directly.
(7)

The Emacs installation instructions have information on additional font support.
(8)

SliTeX is obsoleted by the `slides' document class in recent LaTeX versions.
(9)

The word "sexp" is used to refer to an expression in Lisp.
(10)

On some systems, the man program accepts a `-a' command-line option which tells it to display all the man pages for the specified topic. If you want this behavior, you can add this option to the value of the variable Man-switches.
(11)

The name of the command, woman, is an acronym for "w/o (without) man," since it doesn't use the man program.
(12)

Under a window system the arrow is displayed in the marginal area of the Emacs window.
(13)

The US National Security Agency.
(14)

You should not suspend the shell process. Suspending a subjob of the shell is a completely different matter--that is normal practice, but you must use the shell to continue the subjob; this command won't do it.
(15)

This dissociword actually appeared during the Vietnam War, when it was very appropriate.
(16)

Note that you should avoid the string syntax for binding 8-bit characters, since they will be interpreted as meta keys. See section `Strings of Events' in The Emacs Lisp Reference Manual.
(17)

Here and below, whenever we say "colon-separated list of directories", it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, the directories are separated by semi-colons instead, since DOS/Windows file names might include a colon after a drive letter.
(18)

Note that the `net use' command requires the UNC share name to be typed with the Windows-style backslashes, while the value of printer-name can be set with either forward- or backslashes.
(19)

Normally, one particular codepage is burnt into the display memory, while other codepages can be installed by modifying system configuration files, such as `CONFIG.SYS', and rebooting. While third-party software is known to exist that allows to change the codepage without rebooting, we describe here how a stock MS-DOS system behaves.
(20)

The standard Emacs coding systems for ISO 8859 are not quite right for the purpose, because typically the DOS codepage does not match the standard ISO character codes. For example, the letter `ç' (`c' with cedilla) has code 231 in the standard Latin-1 character set, but the corresponding DOS codepage 850 uses code 135 for this glyph.
(21)

The wording here was careless. The intention was that nobody would have to pay for permission to use the GNU system. But the words don't make this clear, and people often interpret them as saying that copies of GNU should always be distributed at little or no charge. That was never the intent; later on, the manifesto mentions the possibility of companies providing the service of distribution for a profit. Subsequently I have learned to distinguish carefully between "free" in the sense of freedom and "free" in the sense of price. Free software is software that users have the freedom to distribute and change. Some users may obtain copies at no charge, while others pay to obtain copies--and if the funds help support improving the software, so much the better. The important thing is that everyone who has a copy has the freedom to cooperate with others in using it.
(22)

This is another place I failed to distinguish carefully between the two different meanings of "free." The statement as it stands is not false--you can get copies of GNU software at no charge, from your friends or over the net. But it does suggest the wrong idea.
(23)

Several such companies now exist.
(24)

The Free Software Foundation raises most of its funds from a distribution service, although it is a charity rather than a company. If no one chooses to obtain copies by ordering from the FSF, it will be unable to do its work. But this does not mean that proprietary restrictions are justified to force every user to pay. If a small fraction of all the users order copies from the FSF, that is sufficient to keep the FSF afloat. So we ask users to choose to support us in this way. Have you done your part?
(25)

A group of computer companies recently pooled funds to support maintenance of the GNU C Compiler.

[Top]

[Contents]

[Index]

[ ? ]

Table of Contents

Distribution
GNU GENERAL PUBLIC LICENSE

Preamble
How to Apply These Terms to Your New Programs

A. GNU Free Documentation License

ADDENDUM: How to use this License for your documents

Introduction
B. The Organization of the Screen

B.1 Point
B.2 The Echo Area
B.3 The Mode Line
B.4 The Menu Bar
B.5 Kinds of User Input
B.6 Keys
B.7 Keys and Commands
B.8 Character Set for Text

C. Entering and Exiting Emacs

C.1 Exiting Emacs

D. Basic Editing Commands

D.1 Inserting Text
D.2 Changing the Location of Point
D.3 Erasing Text
D.4 Undoing Changes
D.5 Files
D.6 Help
D.7 Blank Lines
D.8 Continuation Lines
D.9 Cursor Position Information
D.10 Numeric Arguments
D.11 Repeating a Command

E. The Minibuffer

E.1 Minibuffers for File Names
E.2 Editing in the Minibuffer
E.3 Completion

E.3.1 Completion Example
E.3.2 Completion Commands
E.3.3 Strict Completion
E.3.4 Completion Options

E.4 Minibuffer History
E.5 Repeating Minibuffer Commands

F. Running Commands by Name
G. Help

G.1 Help Summary
G.2 Documentation for a Key
G.3 Help by Command or Variable Name
G.4 Apropos
G.5 Keyword Search for Lisp Libraries
G.6 Help for International Language Support
G.7 Help Mode Commands
G.8 Other Help Commands
G.9 Help on Active Text and Tooltips

H. The Mark and the Region

H.1 Setting the Mark
H.2 Transient Mark Mode
H.3 Operating on the Region
H.4 Commands to Mark Textual Objects
H.5 The Mark Ring
H.6 The Global Mark Ring
H.7 Deletion and Killing

H.7.1 Deletion
H.7.2 Killing by Lines
H.7.3 Other Kill Commands

H.8 Yanking

H.8.1 The Kill Ring
H.8.2 Appending Kills
H.8.3 Yanking Earlier Kills

H.9 Accumulating Text
H.10 Rectangles

I. Registers

I.1 Saving Positions in Registers
I.2 Saving Text in Registers
I.3 Saving Rectangles in Registers
I.4 Saving Window Configurations in Registers
I.5 Keeping Numbers in Registers
I.6 Keeping File Names in Registers
I.7 Bookmarks

J. Controlling the Display

J.1 Using Multiple Typefaces
J.2 Font Lock mode
J.3 Highlight Changes Mode
J.4 Interactive Highlighting by Matching
J.5 Trailing Whitespace
J.6 Scrolling
J.7 Horizontal Scrolling
J.8 Follow Mode
J.9 Selective Display
J.10 Optional Mode Line Features
J.11 How Text Is Displayed
J.12 Customization of Display
J.13 Displaying the Cursor

K. Searching and Replacement

K.1 Incremental Search

K.1.1 Slow Terminal Incremental Search

K.2 Nonincremental Search
K.3 Word Search
K.4 Regular Expression Search
K.5 Syntax of Regular Expressions
K.6 Searching and Case
K.7 Replacement Commands

K.7.1 Unconditional Replacement
K.7.2 Regexp Replacement
K.7.3 Replace Commands and Case
K.7.4 Query Replace

K.8 Other Search-and-Loop Commands

L. Commands for Fixing Typos

L.1 Killing Your Mistakes
L.2 Transposing Text
L.3 Case Conversion
L.4 Checking and Correcting Spelling

M. File Handling

M.1 File Names
M.2 Visiting Files
M.3 Saving Files

M.3.1 Backup Files

M.3.1.1 Single or Numbered Backups
M.3.1.2 Automatic Deletion of Backups
M.3.1.3 Copying vs. Renaming

M.3.2 Protection against Simultaneous Editing
M.3.3 Shadowing Files
M.3.4 Updating Time Stamps Automatically

M.4 Reverting a Buffer
M.5 Auto-Saving: Protection Against Disasters

M.5.1 Auto-Save Files
M.5.2 Controlling Auto-Saving
M.5.3 Recovering Data from Auto-Saves

M.6 File Name Aliases
M.7 Version Control

M.7.1 Introduction to Version Control

M.7.1.1 Supported Version Control Systems
M.7.1.2 Concepts of Version Control

M.7.2 Version Control and the Mode Line
M.7.3 Basic Editing under Version Control

M.7.3.1 Basic Version Control with Locking
M.7.3.2 Basic Version Control without Locking
M.7.3.3 Advanced Control in C-x C-q
M.7.3.4 Features of the Log Entry Buffer

M.7.4 Examining And Comparing Old Versions
M.7.5 The Secondary Commands of VC

M.7.5.1 Registering a File for Version Control
M.7.5.2 VC Status Commands
M.7.5.3 Undoing Version Control Actions
M.7.5.4 Dired under VC
M.7.5.5 VC Dired Commands

M.7.6 Multiple Branches of a File

M.7.6.1 Switching between Branches
M.7.6.2 Creating New Branches
M.7.6.3 Merging Branches
M.7.6.4 Multi-User Branching

M.7.7 Remote Repositories

M.7.7.1 Version Backups
M.7.7.2 Local Version Control

M.7.8 Snapshots

M.7.8.1 Making and Using Snapshots
M.7.8.2 Snapshot Caveats

M.7.9 Miscellaneous Commands and Features of VC

M.7.9.1 Change Logs and VC
M.7.9.2 Renaming VC Work Files and Master Files
M.7.9.3 Inserting Version Control Headers

M.7.10 Customizing VC

M.7.10.1 General Options
M.7.10.2 Options for RCS and SCCS
M.7.10.3 Options specific for CVS

M.8 File Directories
M.9 Comparing Files
M.10 Miscellaneous File Operations
M.11 Accessing Compressed Files
M.12 File Archives
M.13 Remote Files
M.14 Quoted File Names
M.15 File Name Cache
M.16 Convenience Features for Finding Files

N. Using Multiple Buffers

N.1 Creating and Selecting Buffers
N.2 Listing Existing Buffers
N.3 Miscellaneous Buffer Operations
N.4 Killing Buffers
N.5 Operating on Several Buffers
N.6 Indirect Buffers
N.7 Convenience Features and Customization of Buffer Handling

N.7.1 Making Buffer Names Unique
N.7.2 Switching Between Buffers using Substrings
N.7.3 Customizing Buffer Menus

O. Multiple Windows

O.1 Concepts of Emacs Windows
O.2 Splitting Windows
O.3 Using Other Windows
O.4 Displaying in Another Window
O.5 Forcing Display in the Same Window
O.6 Deleting and Rearranging Windows
O.7 Window Handling Convenience Features and Customization

P. Frames and X Windows

P.1 Mouse Commands for Editing
P.2 Secondary Selection
P.3 Using the Clipboard
P.4 Following References with the Mouse
P.5 Mouse Clicks for Menus
P.6 Mode Line Mouse Commands
P.7 Creating Frames
P.8 Frame Commands
P.9 Making and Using a Speedbar Frame
P.10 Multiple Displays
P.11 Special Buffer Frames
P.12 Setting Frame Parameters
P.13 Scroll Bars
P.14 Scrolling With "Wheeled" Mice
P.15 Menu Bars
P.16 Tool Bars
P.17 Using Dialog Boxes
P.18 Tooltips (or "Balloon Help")
P.19 Mouse Avoidance
P.20 Non-Window Terminals
P.21 Using a Mouse in Terminal Emulators

Q. International Character Set Support

Q.1 Introduction to International Character Sets
Q.2 Enabling Multibyte Characters
Q.3 Language Environments
Q.4 Input Methods
Q.5 Selecting an Input Method
Q.6 Unibyte and Multibyte Non-ASCII characters
Q.7 Coding Systems
Q.8 Recognizing Coding Systems
Q.9 Specifying a Coding System
Q.10 Fontsets
Q.11 Defining fontsets
Q.12 Undisplayable Characters
Q.13 Single-byte Character Set Support

R. Major Modes

R.1 How Major Modes are Chosen

S. Indentation

S.1 Indentation Commands and Techniques
S.2 Tab Stops
S.3 Tabs vs. Spaces

T. Commands for Human Languages

T.1 Words
T.2 Sentences
T.3 Paragraphs
T.4 Pages
T.5 Filling Text

T.5.1 Auto Fill Mode
T.5.2 Refill Mode
T.5.3 Explicit Fill Commands
T.5.4 The Fill Prefix
T.5.5 Adaptive Filling

T.6 Case Conversion Commands
T.7 Text Mode
T.8 Outline Mode

T.8.1 Format of Outlines
T.8.2 Outline Motion Commands
T.8.3 Outline Visibility Commands
T.8.4 Viewing One Outline in Multiple Views
T.8.5 Folding Editing

T.9 TeX Mode

T.9.1 TeX Editing Commands
T.9.2 LaTeX Editing Commands
T.9.3 TeX Printing Commands
T.9.4 TeX Mode Miscellany

T.10 Nroff Mode
T.11 Editing Formatted Text

T.11.1 Requesting to Edit Formatted Text
T.11.2 Hard and Soft Newlines
T.11.3 Editing Format Information
T.11.4 Faces in Formatted Text
T.11.5 Colors in Formatted Text
T.11.6 Indentation in Formatted Text
T.11.7 Justification in Formatted Text
T.11.8 Setting Other Text Properties
T.11.9 Forcing Enriched Mode

U. Editing Programs

U.1 Major Modes for Programming Languages
U.2 Top-Level Definitions, or Defuns

U.2.1 Left Margin Convention
U.2.2 Moving by Defuns
U.2.3 Imenu
U.2.4 Which Function Mode

U.3 Indentation for Programs

U.3.1 Basic Program Indentation Commands
U.3.2 Indenting Several Lines
U.3.3 Customizing Lisp Indentation
U.3.4 Commands for C Indentation
U.3.5 Customizing C Indentation

U.4 Commands for Editing with Parentheses

U.4.1 Expressions with Balanced Parentheses
U.4.2 Moving in the Parenthesis Structure
U.4.3 Automatic Display Of Matching Parentheses

U.5 Manipulating Comments

U.5.1 Comment Commands
U.5.2 Multiple Lines of Comments
U.5.3 Options Controlling Comments

U.6 Documentation Lookup

U.6.1 Info Documentation Lookup
U.6.2 Man Page Lookup
U.6.3 Emacs Lisp Documentation Lookup

U.7 Hideshow minor mode
U.8 Completion for Symbol Names
U.9 Glasses minor mode
U.10 Other Features Useful for Editing Programs
U.11 C and Related Modes

U.11.1 C Mode Motion Commands
U.11.2 Electric C Characters
U.11.3 Hungry Delete Feature in C
U.11.4 Other Commands for C Mode
U.11.5 Comments in C Modes

U.12 Fortran Mode

U.12.1 Motion Commands
U.12.2 Fortran Indentation

U.12.2.1 Fortran Indentation and Filling Commands
U.12.2.2 Continuation Lines
U.12.2.3 Line Numbers
U.12.2.4 Syntactic Conventions
U.12.2.5 Variables for Fortran Indentation

U.12.3 Fortran Comments
U.12.4 Fortran Auto Fill Mode
U.12.5 Checking Columns in Fortran
U.12.6 Fortran Keyword Abbrevs

U.13 Asm Mode

V. Compiling and Testing Programs

V.1 Running Compilations under Emacs
V.2 Searching with Grep under Emacs
V.3 Compilation Mode
V.4 Subshells for Compilation
V.5 Running Debuggers Under Emacs

V.5.1 Starting GUD
V.5.2 Debugger Operation
V.5.3 Commands of GUD
V.5.4 GUD Customization
V.5.5 GUD Tooltips

V.6 Executing Lisp Expressions
V.7 Libraries of Lisp Code for Emacs
V.8 Evaluating Emacs-Lisp Expressions
V.9 Lisp Interaction Buffers
V.10 Running an External Lisp

W. Maintaining Programs

W.1 Change Logs
W.2 Tags Tables

W.2.1 Source File Tag Syntax
W.2.2 Creating Tags Tables
W.2.3 Etags Regexps
W.2.4 Selecting a Tags Table
W.2.5 Finding a Tag
W.2.6 Searching and Replacing with Tags Tables
W.2.7 Tags Table Inquiries

W.3 Merging Files with Emerge

W.3.1 Overview of Emerge
W.3.2 Submodes of Emerge
W.3.3 State of a Difference
W.3.4 Merge Commands
W.3.5 Exiting Emerge
W.3.6 Combining the Two Versions
W.3.7 Fine Points of Emerge

X. Abbrevs

X.1 Abbrev Concepts
X.2 Defining Abbrevs
X.3 Controlling Abbrev Expansion
X.4 Examining and Editing Abbrevs
X.5 Saving Abbrevs
X.6 Dynamic Abbrev Expansion
X.7 Customizing Dynamic Abbreviation

Y. Editing Pictures

Y.1 Basic Editing in Picture Mode
Y.2 Controlling Motion after Insert
Y.3 Picture Mode Tabs
Y.4 Picture Mode Rectangle Commands

Z. Sending Mail

Z.1 The Format of the Mail Buffer
Z.2 Mail Header Fields
Z.3 Mail Aliases
Z.4 Mail Mode

Z.4.1 Mail Sending
Z.4.2 Mail Header Editing
Z.4.3 Citing Mail
Z.4.4 Mail Mode Miscellany

Z.5 Mail Amusements
Z.6 Mail-Composition Methods

AA. Reading Mail with Rmail

AA.1 Basic Concepts of Rmail
AA.2 Scrolling Within a Message
AA.3 Moving Among Messages
AA.4 Deleting Messages
AA.5 Rmail Files and Inboxes
AA.6 Multiple Rmail Files
AA.7 Copying Messages Out to Files
AA.8 Labels
AA.9 Rmail Attributes
AA.10 Sending Replies
AA.11 Summaries

AA.11.1 Making Summaries
AA.11.2 Editing in Summaries

AA.12 Sorting the Rmail File
AA.13 Display of Messages
AA.14 Rmail and Coding Systems
AA.15 Editing Within a Message
AA.16 Digest Messages
AA.17 Converting an Rmail File to Inbox Format
AA.18 Reading Rot13 Messages
AA.19 movemail and POP

AB. Dired, the Directory Editor

AB.1 Entering Dired
AB.2 Navigation in the Dired Buffer
AB.3 Deleting Files with Dired
AB.4 Flagging Many Files at Once
AB.5 Visiting Files in Dired
AB.6 Dired Marks vs. Flags
AB.7 Operating on Files
AB.8 Shell Commands in Dired
AB.9 Transforming File Names in Dired
AB.10 File Comparison with Dired
AB.11 Subdirectories in Dired
AB.12 Moving Over Subdirectories
AB.13 Hiding Subdirectories
AB.14 Updating the Dired Buffer
AB.15 Dired and find

AC. The Calendar and the Diary

AC.1 Movement in the Calendar

AC.1.1 Motion by Standard Lengths of Time
AC.1.2 Beginning or End of Week, Month or Year
AC.1.3 Specified Dates

AC.2 Scrolling in the Calendar
AC.3 Counting Days
AC.4 Miscellaneous Calendar Commands
AC.5 LaTeX Calendar
AC.6 Holidays
AC.7 Times of Sunrise and Sunset
AC.8 Phases of the Moon
AC.9 Conversion To and From Other Calendars

AC.9.1 Supported Calendar Systems
AC.9.2 Converting To Other Calendars
AC.9.3 Converting From Other Calendars
AC.9.4 Converting from the Mayan Calendar

AC.10 The Diary

AC.10.1 Commands Displaying Diary Entries
AC.10.2 The Diary File
AC.10.3 Date Formats
AC.10.4 Commands to Add to the Diary
AC.10.5 Special Diary Entries

AC.11 Appointments
AC.12 Daylight Savings Time
AC.13 Summing Time Intervals
AC.14 Gnus

AC.14.1 Gnus Buffers
AC.14.2 When Gnus Starts Up
AC.14.3 Summary of Gnus Commands

AC.15 Running Shell Commands from Emacs

AC.15.1 Single Shell Commands
AC.15.2 Interactive Inferior Shell
AC.15.3 Shell Mode
AC.15.4 Shell Command History

AC.15.4.1 Shell History Ring
AC.15.4.2 Shell History Copying
AC.15.4.3 Shell History References

AC.15.5 Directory Tracking
AC.15.6 Shell Mode Options
AC.15.7 Emacs Terminal Emulator
AC.15.8 Term Mode
AC.15.9 Page-At-A-Time Output
AC.15.10 Remote Host Shell

AC.16 Using Emacs as a Server
AC.17 Invoking emacsclient
AC.18 Hardcopy Output
AC.19 PostScript Hardcopy
AC.20 Variables for PostScript Hardcopy
AC.21 Sorting Text
AC.22 Narrowing
AC.23 Two-Column Editing
AC.24 Editing Binary Files
AC.25 Saving Emacs Sessions
AC.26 Recursive Editing Levels
AC.27 Emulation
AC.28 Hyperlinking and Navigation Features

AC.28.1 Following URLs
AC.28.2 Activating URLs
AC.28.3 Finding Files and URLs at Point
AC.28.4 Finding Function and Variable Definitions

AC.29 Dissociated Press
AC.30 Other Amusements

AD. Customization

AD.1 Minor Modes
AD.2 Variables

AD.2.1 Examining and Setting Variables
AD.2.2 Easy Customization Interface

AD.2.2.1 Customization Groups
AD.2.2.2 Changing an Option
AD.2.2.3 Customizing Faces
AD.2.2.4 Customizing Specific Items

AD.2.3 Hooks
AD.2.4 Local Variables
AD.2.5 Local Variables in Files

AD.3 Keyboard Macros

AD.3.1 Basic Use
AD.3.2 Naming and Saving Keyboard Macros
AD.3.3 Executing Macros with Variations

AD.4 Customizing Key Bindings

AD.4.1 Keymaps
AD.4.2 Prefix Keymaps
AD.4.3 Local Keymaps
AD.4.4 Minibuffer Keymaps
AD.4.5 Changing Key Bindings Interactively
AD.4.6 Rebinding Keys in Your Init File
AD.4.7 Rebinding Function Keys
AD.4.8 Named ASCII Control Characters
AD.4.9 Non-ASCII Characters on the Keyboard
AD.4.10 Rebinding Mouse Buttons
AD.4.11 Disabling Commands

AD.5 Keyboard Translations
AD.6 The Syntax Table
AD.7 The Init File, `~/.emacs'

AD.7.1 Init File Syntax
AD.7.2 Init File Examples
AD.7.3 Terminal-specific Initialization
AD.7.4 How Emacs Finds Your Init File

AD.8 Quitting and Aborting
AD.9 Dealing with Emacs Trouble

AD.9.1 If DEL Fails to Delete
AD.9.2 Recursive Editing Levels
AD.9.3 Garbage on the Screen
AD.9.4 Garbage in the Text
AD.9.5 Spontaneous Entry to Incremental Search
AD.9.6 Running out of Memory
AD.9.7 Recovery After a Crash
AD.9.8 Emergency Escape
AD.9.9 Help for Total Frustration

AD.10 Reporting Bugs

AD.10.1 When Is There a Bug
AD.10.2 Understanding Bug Reporting
AD.10.3 Checklist for Bug Reports
AD.10.4 Sending Patches for GNU Emacs

AD.11 Contributing to Emacs Development
AD.12 How To Get Help with GNU Emacs

AE. Command Line Arguments

AE.1 Action Arguments
AE.2 Initial Options
AE.3 Command Argument Example
AE.4 Resuming Emacs with Arguments
AE.5 Environment Variables

AE.5.1 General Variables
AE.5.2 Miscellaneous Variables

AE.6 Specifying the Display Name
AE.7 Font Specification Options
AE.8 Window Color Options
AE.9 Options for Window Geometry
AE.10 Internal and External Borders
AE.11 Frame Titles
AE.12 Icons
AE.13 X Resources
AE.14 Lucid Menu X Resources
AE.15 LessTif Menu X Resources

AF. Emacs 20 Antinews
AG. Emacs and the Mac OS

AG.1 Keyboard Input on the Mac
AG.2 International Character Set Support on the Mac
AG.3 Environment Variables and Command Line Arguments.
AG.4 Volumes and Directories on the Mac
AG.5 Specifying Fonts on the Mac
AG.6 Mac-Specific Lisp Functions

AH. Emacs and MS-DOS

AH.1 Keyboard and Mouse on MS-DOS
AH.2 Display on MS-DOS
AH.3 File Names on MS-DOS
AH.4 Text Files and Binary Files
AH.5 Printing and MS-DOS
AH.6 International Support on MS-DOS
AH.7 Subprocesses on MS-DOS
AH.8 Subprocesses on Windows 9X/ME and Windows NT/2K
AH.9 Using the System Menu on Windows

The GNU Manifesto

What's GNU? Gnu's Not Unix!
Why I Must Write GNU
Why GNU Will Be Compatible with Unix
How GNU Will Be Available
Why Many Other Programmers Want to Help
How You Can Contribute
Why All Computer Users Will Benefit
Some Easily Rebutted Objections to GNU's Goals

Glossary
AI. Acknowledgments
Key (Character) Index
Command-Line Options Index
Command and Function Index
Variable Index
Concept Index

[Top]

[Contents]

[Index]

[ ? ]

Short Table of Contents

Distribution
GNU GENERAL PUBLIC LICENSE
A. GNU Free Documentation License
Introduction
B. The Organization of the Screen
C. Entering and Exiting Emacs
D. Basic Editing Commands
E. The Minibuffer
F. Running Commands by Name
G. Help
H. The Mark and the Region
I. Registers
J. Controlling the Display
K. Searching and Replacement
L. Commands for Fixing Typos
M. File Handling
N. Using Multiple Buffers
O. Multiple Windows
P. Frames and X Windows
Q. International Character Set Support
R. Major Modes
S. Indentation
T. Commands for Human Languages
U. Editing Programs
V. Compiling and Testing Programs
W. Maintaining Programs
X. Abbrevs
Y. Editing Pictures
Z. Sending Mail
AA. Reading Mail with Rmail
AB. Dired, the Directory Editor
AC. The Calendar and the Diary
AD. Customization
AE. Command Line Arguments
AF. Emacs 20 Antinews
AG. Emacs and the Mac OS
AH. Emacs and MS-DOS
The GNU Manifesto
Glossary
AI. Acknowledgments
Key (Character) Index
Command-Line Options Index
Command and Function Index
Variable Index
Concept Index

[Top]

[Contents]

[Index]

[ ? ]

About this document
This document was generated on April 2, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button

Name

Go to

From 1.2.3 go to

[ < ]

Back

previous section in reading order

1.2.2

[ > ]

Forward

next section in reading order

1.2.4

[ << ]

FastBack

previous or up-and-previous section

1.1

[ Up ]

Up

up section

1.2

[ >> ]

FastForward

next or up-and-next section

1.3

[Top]

Top

cover (top) of document

[Contents]

Contents

table of contents

[Index]

Index

concept index

[ ? ]

About

this page

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

1. Section One

1.1 Subsection One-One

...

1.2 Subsection One-Two

1.2.1 Subsubsection One-Two-One

1.2.2 Subsubsection One-Two-Two

1.2.3 Subsubsection One-Two-Three <== Current Position

1.2.4 Subsubsection One-Two-Four

1.3 Subsection One-Three

...

1.4 Subsection One-Four

This document was generated on April 2, 2002 using texi2html


GNU Emacs Manual

Table of Contents

  • Preface
  • Distribution
  • GNU GENERAL PUBLIC LICENSE
    • Preamble
    • TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
    • How to Apply These Terms to Your New Programs
  • Introduction
  • The Organization of the Screen
    • Point
    • The Echo Area
    • The Mode Line
    • The Menu Bar
  • Characters, Keys and Commands
    • Kinds of User Input
    • Keys
    • Keys and Commands
    • Character Set for Text
  • Entering and Exiting Emacs
    • Exiting Emacs
  • Basic Editing Commands
    • Inserting Text
    • Changing the Location of Point
    • Erasing Text
    • Undoing Changes
    • Files
    • Help
    • Blank Lines
    • Continuation Lines
    • Cursor Position Information
    • Numeric Arguments
    • Repeating a Command
  • The Minibuffer
    • Minibuffers for File Names
    • Editing in the Minibuffer
    • Completion
      • Completion Example
      • Completion Commands
      • Strict Completion
      • Completion Options
    • Minibuffer History
    • Repeating Minibuffer Commands
  • Running Commands by Name
  • Help
    • Documentation for a Key
    • Help by Command or Variable Name
    • Apropos
    • Keyword Search for Lisp Libraries
    • Help for International Language Support
    • Help Mode Commands
    • Other Help Commands
  • The Mark and the Region
    • Setting the Mark
    • Transient Mark Mode
    • Operating on the Region
    • Commands to Mark Textual Objects
    • The Mark Ring
    • The Global Mark Ring
  • Killing and Moving Text
    • Deletion and Killing
      • Deletion
      • Killing by Lines
      • Other Kill Commands
    • Yanking
      • The Kill Ring
      • Appending Kills
      • Yanking Earlier Kills
    • Accumulating Text
    • Rectangles
  • Registers
    • Saving Positions in Registers
    • Saving Text in Registers
    • Saving Rectangles in Registers
    • Saving Window Configurations in Registers
    • Keeping Numbers in Registers
    • Keeping File Names in Registers
    • Bookmarks
  • Controlling the Display
    • Scrolling
    • Horizontal Scrolling
    • Follow Mode
    • Selective Display
    • Optional Mode Line Features
    • How Text Is Displayed
    • Variables Controlling Display
  • Searching and Replacement
    • Incremental Search
      • Slow Terminal Incremental Search
    • Nonincremental Search
    • Word Search
    • Regular Expression Search
    • Syntax of Regular Expressions
    • Searching and Case
    • Replacement Commands
      • Unconditional Replacement
      • Regexp Replacement
      • Replace Commands and Case
      • Query Replace
    • Other Search-and-Loop Commands
  • Commands for Fixing Typos
    • Killing Your Mistakes
    • Transposing Text
    • Case Conversion
    • Checking and Correcting Spelling
  • File Handling
    • File Names
    • Visiting Files
    • Saving Files
      • Backup Files
        • Single or Numbered Backups
        • Automatic Deletion of Backups
        • Copying vs. Renaming
      • Protection against Simultaneous Editing
    • Reverting a Buffer
    • Auto-Saving: Protection Against Disasters
      • Auto-Save Files
      • Controlling Auto-Saving
      • Recovering Data from Auto-Saves
    • File Name Aliases
    • Version Control
      • Introduction to Version Control
        • Supported Version Control Systems
        • Concepts of Version Control
      • Version Control and the Mode Line
      • Basic Editing under Version Control
        • Basic Version Control with Locking
        • Basic Version Control without Locking
        • Features of the Log Entry Buffer
      • Examining And Comparing Old Versions
      • The Secondary Commands of VC
        • Registering a File for Version Control
        • VC Status Commands
        • Undoing Version Control Actions
        • Dired under VC
        • VC Dired Commands
      • Multiple Branches of a File
        • Switching between Branches
        • Creating New Branches
        • Merging Branches
        • Multi-User Branching
      • Snapshots
        • Making and Using Snapshots
        • Snapshot Caveats
      • Miscellaneous Commands and Features of VC
        • Change Logs and VC
        • Renaming VC Work Files and Master Files
        • Inserting Version Control Headers
      • Customizing VC
        • Options for VC Backends
        • VC Workfile Handling
        • VC Status Retrieval
        • VC Command Execution
    • File Directories
    • Comparing Files
    • Miscellaneous File Operations
    • Accessing Compressed Files
    • Remote Files
    • Quoted File Names
  • Using Multiple Buffers
    • Creating and Selecting Buffers
    • Listing Existing Buffers
    • Miscellaneous Buffer Operations
    • Killing Buffers
    • Operating on Several Buffers
    • Indirect Buffers
  • Multiple Windows
    • Concepts of Emacs Windows
    • Splitting Windows
    • Using Other Windows
    • Displaying in Another Window
    • Forcing Display in the Same Window
    • Deleting and Rearranging Windows
  • Frames and X Windows
    • Mouse Commands for Editing
    • Secondary Selection
    • Following References with the Mouse
    • Mouse Clicks for Menus
    • Mode Line Mouse Commands
    • Creating Frames
    • Making and Using a Speedbar Frame
    • Multiple Displays
    • Special Buffer Frames
    • Setting Frame Parameters
    • Scroll Bars
    • Menu Bars
    • Using Multiple Typefaces
    • Font Lock mode
    • Font Lock Support Modes
      • Fast Lock Mode
      • Lazy Lock Mode
      • Fast Lock or Lazy Lock?
    • Highlight Changes Mode
    • Miscellaneous X Window Features
    • Non-Window Terminals
  • International Character Set Support
    • Introduction to International Character Sets
    • Enabling Multibyte Characters
    • Language Environments
    • Input Methods
    • Selecting an Input Method
    • Unibyte and Multibyte Non-ASCII characters
    • Coding Systems
    • Recognizing Coding Systems
    • Specifying a Coding System
    • Fontsets
    • Defining fontsets
    • Single-byte European Character Support
  • Major Modes
    • How Major Modes are Chosen
  • Indentation
    • Indentation Commands and Techniques
    • Tab Stops
    • Tabs vs. Spaces
  • Commands for Human Languages
    • Words
    • Sentences
    • Paragraphs
    • Pages
    • Filling Text
      • Auto Fill Mode
      • Explicit Fill Commands
      • The Fill Prefix
      • Adaptive Filling
    • Case Conversion Commands
    • Text Mode
    • Outline Mode
      • Format of Outlines
      • Outline Motion Commands
      • Outline Visibility Commands
      • Viewing One Outline in Multiple Views
    • TeX Mode
      • TeX Editing Commands
      • LaTeX Editing Commands
      • TeX Printing Commands
    • Nroff Mode
    • Editing Formatted Text
      • Requesting to Edit Formatted Text
      • Hard and Soft Newlines
      • Editing Format Information
      • Faces in Formatted Text
      • Colors in Formatted Text
      • Indentation in Formatted Text
      • Justification in Formatted Text
      • Setting Other Text Properties
      • Forcing Enriched Mode
  • Editing Programs
    • Major Modes for Programming Languages
    • Lists and Sexps
    • List And Sexp Commands
    • Defuns
    • Indentation for Programs
      • Basic Program Indentation Commands
      • Indenting Several Lines
      • Customizing Lisp Indentation
      • Commands for C Indentation
      • Customizing C Indentation
        • Step 1--Syntactic Analysis
        • Step 2--Indentation Calculation
        • Changing Indentation Style
        • Syntactic Symbols
        • Variables for C Indentation
        • C Indentation Styles
    • Automatic Display Of Matching Parentheses
    • Manipulating Comments
      • Comment Commands
      • Multiple Lines of Comments
      • Options Controlling Comments
    • Editing Without Unbalanced Parentheses
    • Completion for Symbol Names
    • Which Function Mode
    • Documentation Commands
    • Change Logs
    • Tags Tables
      • Source File Tag Syntax
      • Creating Tags Tables
      • Selecting a Tags Table
      • Finding a Tag
      • Searching and Replacing with Tags Tables
      • Tags Table Inquiries
    • Merging Files with Emerge
      • Overview of Emerge
      • Submodes of Emerge
      • State of a Difference
      • Merge Commands
      • Exiting Emerge
      • Combining the Two Versions
      • Fine Points of Emerge
    • C and Related Modes
      • C Mode Motion Commands
      • Electric C Characters
      • Hungry Delete Feature in C
      • Other Commands for C Mode
      • Comments in C Modes
    • Fortran Mode
      • Motion Commands
      • Fortran Indentation
        • Fortran Indentation Commands
        • Continuation Lines
        • Line Numbers
        • Syntactic Conventions
        • Variables for Fortran Indentation
      • Fortran Comments
      • Fortran Auto Fill Mode
      • Checking Columns in Fortran
      • Fortran Keyword Abbrevs
      • Other Fortran Mode Commands
    • Asm Mode
  • Compiling and Testing Programs
    • Running Compilations under Emacs
    • Searching with Grep under Emacs
    • Compilation Mode
    • Subshells for Compilation
    • Running Debuggers Under Emacs
      • Starting GUD
      • Debugger Operation
      • Commands of GUD
      • GUD Customization
    • Executing Lisp Expressions
    • Libraries of Lisp Code for Emacs
    • Evaluating Emacs-Lisp Expressions
    • Lisp Interaction Buffers
    • Running an External Lisp
  • Abbrevs
    • Abbrev Concepts
    • Defining Abbrevs
    • Controlling Abbrev Expansion
    • Examining and Editing Abbrevs
    • Saving Abbrevs
    • Dynamic Abbrev Expansion
    • Customizing Dynamic Abbreviation
  • Editing Pictures
    • Basic Editing in Picture Mode
    • Controlling Motion after Insert
    • Picture Mode Tabs
    • Picture Mode Rectangle Commands
  • Sending Mail
    • The Format of the Mail Buffer
    • Mail Header Fields
    • Mail Aliases
    • Mail Mode
      • Mail Sending
      • Mail Header Editing
      • Citing Mail
      • Mail Mode Miscellany
    • Distracting the NSA
    • Mail-Composition Methods
  • Reading Mail with Rmail
    • Basic Concepts of Rmail
    • Scrolling Within a Message
    • Moving Among Messages
    • Deleting Messages
    • Rmail Files and Inboxes
    • Multiple Rmail Files
    • Copying Messages Out to Files
    • Labels
    • Rmail Attributes
    • Sending Replies
    • Summaries
      • Making Summaries
      • Editing in Summaries
    • Sorting the Rmail File
    • Display of Messages
    • Editing Within a Message
    • Digest Messages
    • Converting an Rmail File to Inbox Format
    • Reading Rot13 Messages
    • movemail and POP
  • Dired, the Directory Editor
    • Entering Dired
    • Commands in the Dired Buffer
    • Deleting Files with Dired
    • Flagging Many Files at Once
    • Visiting Files in Dired
    • Dired Marks vs. Flags
    • Operating on Files
    • Shell Commands in Dired
    • Transforming File Names in Dired
    • File Comparison with Dired
    • Subdirectories in Dired
    • Moving Over Subdirectories
    • Hiding Subdirectories
    • Updating the Dired Buffer
    • Dired and find
  • The Calendar and the Diary
    • Movement in the Calendar
      • Motion by Standard Lengths of Time
      • Beginning or End of Week, Month or Year
      • Specified Dates
    • Scrolling in the Calendar
    • Counting Days
    • Miscellaneous Calendar Commands
    • LaTeX Calendar
    • Holidays
    • Times of Sunrise and Sunset
    • Phases of the Moon
    • Conversion To and From Other Calendars
      • Supported Calendar Systems
      • Converting To Other Calendars
      • Converting From Other Calendars
      • Converting from the Mayan Calendar
    • The Diary
      • Commands Displaying Diary Entries
      • The Diary File
      • Date Formats
      • Commands to Add to the Diary
      • Special Diary Entries
    • Appointments
    • Daylight Savings Time
  • Miscellaneous Commands
    • Gnus
      • Gnus Buffers
      • When Gnus Starts Up
      • Summary of Gnus Commands
    • Running Shell Commands from Emacs
      • Single Shell Commands
      • Interactive Inferior Shell
      • Shell Mode
      • Shell Command History
        • Shell History Ring
        • Shell History Copying
        • Shell History References
      • Shell Mode Options
      • Remote Host Shell
    • Using Emacs as a Server
    • Hardcopy Output
    • Postscript Hardcopy
    • Variables for Postscript Hardcopy
    • Sorting Text
    • Narrowing
    • Two-Column Editing
    • Editing Binary Files
    • Saving Emacs Sessions
    • Recursive Editing Levels
    • Emulation
    • Dissociated Press
    • Other Amusements
  • Customization
    • Minor Modes
    • Variables
      • Examining and Setting Variables
      • Easy Customization Interface
        • Customization Groups
        • Changing an Option
        • Customizing Faces
        • Customizing Specific Items
      • Hooks
      • Local Variables
      • Local Variables in Files
    • Keyboard Macros
      • Basic Use
      • Naming and Saving Keyboard Macros
      • Executing Macros with Variations
    • Customizing Key Bindings
      • Keymaps
      • Prefix Keymaps
      • Local Keymaps
      • Minibuffer Keymaps
      • Changing Key Bindings Interactively
      • Rebinding Keys in Your Init File
      • Rebinding Function Keys
      • Named ASCII Control Characters
      • Non-ASCII Characters on the Keyboard
      • Rebinding Mouse Buttons
      • Disabling Commands
    • Keyboard Translations
    • The Syntax Table
    • The Init File, `~/.emacs'
      • Init File Syntax
      • Init File Examples
      • Terminal-specific Initialization
      • How Emacs Finds Your Init File
  • Dealing with Common Problems
    • Quitting and Aborting
    • Dealing with Emacs Trouble
      • If DEL Fails to Delete
      • Recursive Editing Levels
      • Garbage on the Screen
      • Garbage in the Text
      • Spontaneous Entry to Incremental Search
      • Running out of Memory
      • Recovery After a Crash
      • Emergency Escape
      • Help for Total Frustration
    • Reporting Bugs
      • When Is There a Bug
      • Understanding Bug Reporting
      • Checklist for Bug Reports
      • Sending Patches for GNU Emacs
    • Contributing to Emacs Development
    • How To Get Help with GNU Emacs
  • Command Line Arguments
    • Action Arguments
    • Initial Options
    • Command Argument Example
    • Resuming Emacs with Arguments
    • Environment Variables
      • General Variables
      • Miscellaneous Variables
    • Specifying the Display Name
    • Font Specification Options
    • Window Color Options
    • Options for Window Geometry
    • Internal and External Borders
    • Frame Titles
    • Icons
    • X Resources
    • Lucid Menu X Resources
    • Motif Menu X Resources
  • Emacs 19 Antinews
  • Emacs and MS-DOS
    • Keyboard and Mouse on MS-DOS
    • Display on MS-DOS
    • File Names on MS-DOS
    • Text Files and Binary Files
    • Printing and MS-DOS
    • International Support on MS-DOS
    • Subprocesses on MS-DOS
    • Subprocesses on Windows 95 and NT
    • Using the System Menu on Windows
  • The GNU Manifesto
    • What's GNU? Gnu's Not Unix!
    • Why I Must Write GNU
    • Why GNU Will Be Compatible with Unix
    • How GNU Will Be Available
    • Why Many Other Programmers Want to Help
    • How You Can Contribute
    • Why All Computer Users Will Benefit
    • Some Easily Rebutted Objections to GNU's Goals
  • Glossary
  • Key (Character) Index
  • Command and Function Index
  • Variable Index
  • Concept Index

Distribution

GNU Emacs is free software; this means that everyone is free to use it and free to redistribute it on certain conditions. GNU Emacs is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of GNU Emacs that they might get from you. The precise conditions are found in the GNU General Public License that comes with Emacs and also appears following this section.

One way to get a copy of GNU Emacs is from someone else who has it. You need not ask for our permission to do so, or tell any one else; just copy it. If you have access to the Internet, you can get the latest distribution version of GNU Emacs by anonymous FTP; see the file `etc/FTP' in the Emacs distribution for more information.

You may also receive GNU Emacs when you buy a computer. Computer manufacturers are free to distribute copies on the same terms that apply to everyone else. These terms require them to give you the full sources, including whatever changes they may have made, and to permit you to redistribute the GNU Emacs received from them under the usual terms of the General Public License. In other words, the program must be free for you when you get it, not just free for the manufacturer.

You can also order copies of GNU Emacs from the Free Software Foundation on CD-ROM. This is a convenient and reliable way to get a copy; it is also a good way to help fund our work. (The Foundation has always received most of its funds in this way.) An order form is included in the file `etc/ORDERS' in the Emacs distribution, and on our web site in http://www.gnu.org/order/order.html. For further information, write to

Free Software Foundation
59 Temple Place, Suite 330
Boston, MA  02111-1307 USA
USA

The income from distribution fees goes to support the foundation's purpose: the development of new free software, and improvements to our existing programs including GNU Emacs.

If you find GNU Emacs useful, please send a donation to the Free Software Foundation to support our work. Donations to the Free Software Foundation are tax deductible in the US. If you use GNU Emacs at your workplace, please suggest that the company make a donation. If company policy is unsympathetic to the idea of donating to charity, you might instead suggest ordering a CD-ROM from the Foundation occasionally, or subscribing to periodic updates.

Contributors to GNU Emacs include Per Abrahamsen, Jay K. Adams, Joe Arceneaux, Boaz Ben-Zvi, Jim Blandy, Terrence Brannon, Frank Bresz, Peter Breton, Kevin Broadey, Vincent Broman, David M. Brown, Bill Carpenter, Hans Chalupsky, Bob Chassell, James Clark, Mike Clarkson, Glynn Clements, Andrew Csillag, Doug Cutting, Michael DeCorte, Gary Delp, Matthieu Devin, Eri Ding, Carsten Dominik, Scott Draves, Viktor Dukhovni, John Eaton, Rolf Ebert, Stephen Eglen, Torbj@"orn Einarsson, Tsugumoto Enami, Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick Farnback, Fred Fish, Karl Fogel, Gary Foster, Noah Friedman, Keith Gabryelski, Kevin Gallagher, Kevin Gallo, Howard Gayle, Stephen Gildea, David Gillespie, Bob Glickstein, Boris Goldowsky, Michelangelo Grigni, Michael Gschwind, Henry Guillaume, Doug Gwyn, Ken'ichi Handa, Chris Hanson, K. Shane Hartman, John Heidemann, Markus Heritsch, Karl Heuer, Manabu Higashida, Anders Holst, Kurt Hornik, Tom Houlder, Lars Ingebrigtsen, Andrew Innes, Michael K. Johnson, Kyle Jones, Tomoji Kagatani, Brewster Kahle, David Kaufman, Henry Kautz, Howard Kaye, Michael Kifer, Richard King, Larry K. Kolodney, Robert Krawitz, Sebastian Kremer, Geoff Kuenning, David K@aa gedal, Daniel LaLiberte, Aaron Larson, James R. Larus, Frederic Lepied, Lars Lindberg, Eric Ludlam, Neil M. Mager, Ken Manheimer, Bill Mann, Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin, Thomas May, Roland McGrath, David Megginson, Wayne Mesard, Richard Mlynarik, Keith Moore, Erik Naggum, Thomas Neumann, Mike Newton, Jurgen Nickelsen, Jeff Norden, Andrew Norman, Jeff Peck, Damon Anton Permezel, Tom Perrine, Jens Petersen, Daniel Pfeiffer, Fred Pierresteguy, Christian Plaunt, Francesco A. Potorti, Michael D. Prange, Ashwin Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold, Rob Riepel, Roland B. Roberts, John Robinson, Danny Roozendaal, William Rosenblatt, Guillermo J. Rozas, Ivar Rummelhoff, Wolfgang Rupprecht, James B. Salem, Masahiko Sato, William Schelter, Ralph Schleicher, Gregor Schmid, Michael Schmidt, Ronald S. Schnell, Philippe Schnoebelen, Stephen Schoef, Randal Schwartz, Manuel Serrano, Stanislav Shalunov, Mark Shapiro, Richard Sharman, Olin Shivers, Espen Skoglund, Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul D. Smith, William Sommerfeld, Michael Staats, Sam Steingold, Ake Stenhoff, Peter Stephenson, Jonathan Stigelman, Steve Strassman, Jens T. Berger Thielemann, Spencer Thomas, Jim Thompson, Masanobu Umeda, Neil W. Van Dyke, Ulrik Vieth, Geoffrey Voelker, Johan Vromans, Barry Warsaw, Morten Welinder, Joseph Brian Wells, Rodney Whitby, Ed Wilkinson, Mike Williams, Steven A. Wood, Dale R. Worley, Felix S. T. Wu, Tom Wurgler, Eli Zaretskii, Jamie Zawinski, Ian T. Zimmermann, Reto Zimmermann, and Neal Ziring.

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and an idea of what it does.
Copyright (C) 19yy  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

Introduction

You are reading about GNU Emacs, the GNU incarnation of the advanced, self-documenting, customizable, extensible real-time display editor Emacs. (The `G' in `GNU' is not silent.)

We say that Emacs is a display editor because normally the text being edited is visible on the screen and is updated automatically as you type your commands. See section The Organization of the Screen.

We call it a real-time editor because the display is updated very frequently, usually after each character or pair of characters you type. This minimizes the amount of information you must keep in your head as you edit. See section Basic Editing Commands.

We call Emacs advanced because it provides facilities that go beyond simple insertion and deletion: controlling subprocesses; automatic indentation of programs; viewing two or more files at once; editing formatted text; and dealing in terms of characters, words, lines, sentences, paragraphs, and pages, as well as expressions and comments in several different programming languages.

Self-documenting means that at any time you can type a special character, Control-h, to find out what your options are. You can also use it to find out what any command does, or to find all the commands that pertain to a topic. See section Help.

Customizable means that you can change the definitions of Emacs commands in little ways. For example, if you use a programming language in which comments start with `<**' and end with `**>', you can tell the Emacs comment manipulation commands to use those strings (see section Manipulating Comments). Another sort of customization is rearrangement of the command set. For example, if you prefer the four basic cursor motion commands (up, down, left and right) on keys in a diamond pattern on the keyboard, you can rebind the keys that way. See section Customization.

Extensible means that you can go beyond simple customization and write entirely new commands, programs in the Lisp language to be run by Emacs's own Lisp interpreter. Emacs is an "on-line extensible" system, which means that it is divided into many functions that call each other, any of which can be redefined in the middle of an editing session. Almost any part of Emacs can be replaced without making a separate copy of all of Emacs. Most of the editing commands of Emacs are written in Lisp already; the few exceptions could have been written in Lisp but are written in C for efficiency. Although only a programmer can write an extension, anybody can use it afterward. If you want to learn Emacs Lisp programming, we recommend the Introduction to Emacs Lisp by Robert J. Chassell, also published by the Free Software Foundation.

When run under the X Window System, Emacs provides its own menus and convenient bindings to mouse buttons. But Emacs can provide many of the benefits of a window system on a text-only terminal. For instance, you can look at or edit several files at once, move text between files, and edit files while running shell commands.

The Organization of the Screen

On a text-only terminal, the Emacs display occupies the whole screen. On the X Window System, Emacs creates its own X windows to use. We use the term frame to mean an entire text-only screen or an entire X window used by Emacs. Emacs uses both kinds of frames in the same way to display your editing. Emacs normally starts out with just one frame, but you can create additional frames if you wish. See section Frames and X Windows.

When you start Emacs, the entire frame except for the first and last lines is devoted to the text you are editing. This area is called the window. The first line is a menu bar, and the last line is a special echo area or minibuffer window where prompts appear and where you can enter responses. See below for more information about these special lines.

You can subdivide the large text window horizontally or vertically into multiple text windows, each of which can be used for a different file (see section Multiple Windows). In this manual, the word "window" always refers to the subdivisions of a frame within Emacs.

The window that the cursor is in is the selected window, in which editing takes place. Most Emacs commands implicitly apply to the text in the selected window (though mouse commands generally operate on whatever window you click them in, whether selected or not). The other windows display text for reference only, unless/until you select them. If you use multiple frames under the X Window System, then giving the input focus to a particular frame selects a window in that frame.

Each window's last line is a mode line, which describes what is going on in that window. It appears in inverse video, if the terminal supports that, and its contents begin with `--:--  *scratch*' when Emacs starts. The mode line displays status information such as what buffer is being displayed above it in the window, what major and minor modes are in use, and whether the buffer contains unsaved changes.

Point

Within Emacs, the terminal's cursor shows the location at which editing commands will take effect. This location is called point. Many Emacs commands move point through the text, so that you can edit at different places in it. You can also place point by clicking mouse button 1.

While the cursor appears to point at a character, you should think of point as between two characters; it points before the character that appears under the cursor. For example, if your text looks like `frob' with the cursor over the `b', then point is between the `o' and the `b'. If you insert the character `!' at that position, the result is `fro!b', with point between the `!' and the `b'. Thus, the cursor remains over the `b', as before.

Sometimes people speak of "the cursor" when they mean "point," or speak of commands that move point as "cursor motion" commands.

Terminals have only one cursor, and when output is in progress it must appear where the typing is being done. This does not mean that point is moving. It is only that Emacs has no way to show you the location of point except when the terminal is idle.

If you are editing several files in Emacs, each in its own buffer, each buffer has its own point location. A buffer that is not currently displayed remembers where point is in case you display it again later.

When there are multiple windows in a frame, each window has its own point location. The cursor shows the location of point in the selected window. This also is how you can tell which window is selected. If the same buffer appears in more than one window, each window has its own position for point in that buffer.

When there are multiple frames, each frame can display one cursor. The cursor in the selected frame is solid; the cursor in other frames is a hollow box, and appears in the window that would be selected if you give the input focus to that frame.

The term `point' comes from the character `.', which was the command in TECO (the language in which the original Emacs was written) for accessing the value now called `point'.

The Echo Area

The line at the bottom of the frame (below the mode line) is the echo area. It is used to display small amounts of text for several purposes.

Echoing means displaying the characters that you type. Outside Emacs, the operating system normally echoes all your input. Emacs handles echoing differently.

Single-character commands do not echo in Emacs, and multi-character commands echo only if you pause while typing them. As soon as you pause for more than a second in the middle of a command, Emacs echoes all the characters of the command so far. This is to prompt you for the rest of the command. Once echoing has started, the rest of the command echoes immediately as you type it. This behavior is designed to give confident users fast response, while giving hesitant users maximum feedback. You can change this behavior by setting a variable (see section Variables Controlling Display).

If a command cannot be executed, it may print an error message in the echo area. Error messages are accompanied by a beep or by flashing the screen. Also, any input you have typed ahead is thrown away when an error happens.

Some commands print informative messages in the echo area. These messages look much like error messages, but they are not announced with a beep and do not throw away input. Sometimes the message tells you what the command has done, when this is not obvious from looking at the text being edited. Sometimes the sole purpose of a command is to print a message giving you specific information--for example, C-x = prints a message describing the character position of point in the text and its current column in the window. Commands that take a long time often display messages ending in `...' while they are working, and add `done' at the end when they are finished.

Echo-area informative messages are saved in an editor buffer named `*Messages*'. (We have not explained buffers yet; see section Using Multiple Buffers, for more information about them.) If you miss a message that appears briefly on the screen, you can switch to the `*Messages*' buffer to see it again. (Successive progress messages are often collapsed into one in that buffer.)

The size of `*Messages*' is limited to a certain number of lines. The variable message-log-max specifies how many lines. Once the buffer has that many lines, each line added at the end deletes one line from the beginning. See section Variables, for how to set variables such as message-log-max.

The echo area is also used to display the minibuffer, a window that is used for reading arguments to commands, such as the name of a file to be edited. When the minibuffer is in use, the echo area begins with a prompt string that usually ends with a colon; also, the cursor appears in that line because it is the selected window. You can always get out of the minibuffer by typing C-g. See section The Minibuffer.

The Mode Line

Each text window's last line is a mode line, which describes what is going on in that window. When there is only one text window, the mode line appears right above the echo area; it is the next-to-last line on the frame. The mode line is in inverse video if the terminal supports that, and it starts and ends with dashes.

Normally, the mode line looks like this:

-cs:ch  buf      (major minor)--line--pos------

This gives information about the buffer being displayed in the window: the buffer's name, what major and minor modes are in use, whether the buffer's text has been changed, and how far down the buffer you are currently looking.

ch contains two stars `**' if the text in the buffer has been edited (the buffer is "modified"), or `--' if the buffer has not been edited. For a read-only buffer, it is `%*' if the buffer is modified, and `%%' otherwise.

buf is the name of the window's buffer. In most cases this is the same as the name of a file you are editing. See section Using Multiple Buffers.

The buffer displayed in the selected window (the window that the cursor is in) is also Emacs's selected buffer, the one that editing takes place in. When we speak of what some command does to "the buffer," we are talking about the currently selected buffer.

line is `L' followed by the current line number of point. This is present when Line Number mode is enabled (which it normally is). You can optionally display the current column number too, by turning on Column Number mode (which is not enabled by default because it is somewhat slower). See section Optional Mode Line Features.

pos tells you whether there is additional text above the top of the window, or below the bottom. If your buffer is small and it is all visible in the window, pos is `All'. Otherwise, it is `Top' if you are looking at the beginning of the buffer, `Bot' if you are looking at the end of the buffer, or `nn%', where nn is the percentage of the buffer above the top of the window.

major is the name of the major mode in effect in the buffer. At any time, each buffer is in one and only one of the possible major modes. The major modes available include Fundamental mode (the least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many others. See section Major Modes, for details of how the modes differ and how to select one.

Some major modes display additional information after the major mode name. For example, Rmail buffers display the current message number and the total number of messages. Compilation buffers and Shell buffers display the status of the subprocess.

minor is a list of some of the minor modes that are turned on at the moment in the window's chosen buffer. For example, `Fill' means that Auto Fill mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means that Overwrite mode is on. See section Minor Modes, for more information. `Narrow' means that the buffer being displayed has editing restricted to only a portion of its text. This is not really a minor mode, but is like one. See section Narrowing. `Def' means that a keyboard macro is being defined. See section Keyboard Macros.

In addition, if Emacs is currently inside a recursive editing level, square brackets (`[...]') appear around the parentheses that surround the modes. If Emacs is in one recursive editing level within another, double square brackets appear, and so on. Since recursive editing levels affect Emacs globally, not just one buffer, the square brackets appear in every window's mode line or not in any of them. See section Recursive Editing Levels.

Non-windowing terminals can only show a single Emacs frame at a time (see section Frames and X Windows). On such terminals, the mode line displays the name of the selected frame, after ch. The initial frame's name is `F1'.

cs states the coding system used for the file you are editing. A dash indicates the default state of affairs: no code conversion, except for end-of-line translation if the file contents call for that. `=' means no conversion whatsoever. Nontrivial code conversions are represented by various letters--for example, `1' refers to ISO Latin-1. See section Coding Systems, for more information. If you are using an input method, a string of the form `i>' is added to the beginning of cs; i identifies the input method. (Some input methods show `+' or `@' instead of `>'.) See section Input Methods.

When you are using a character-only terminal (not a window system), cs uses three characters to describe, respectively, the coding system for keyboard input, the coding system for terminal output, and the coding system used for the file you are editing.

When multibyte characters are not enabled, cs does not appear at all. See section Enabling Multibyte Characters.

The colon after cs can change to another string in certain circumstances. Emacs uses newline to separate lines in the buffer. Some files use different conventions for separating lines: either carriage-return linefeed (the MS-DOS convention) or just carriage-return (the Macintosh convention). If the buffer's file uses carriage-return linefeed, the colon changes to either a backslash (`\') or `(DOS)', depending on the operating system. If the file uses just carriage-return, the colon indicator changes to either a forward slash (`/') or `(Mac)'. On some systems, Emacs displays `(Unix)' instead of the colon even for files that use newline to separate lines.

You can customize the mode line display for each of the end-of-line formats by setting each of the variables eol-mnemonic-unix, eol-mnemonic-dos, eol-mnemonic-mac, and eol-mnemonic-undecided to any string you find appropriate. See section Variables, for an explanation how to set variables.

See section Optional Mode Line Features, for features that add other handy information to the mode line, such as the current column number of point, the current time, and whether new mail for you has arrived.

The Menu Bar

Each Emacs frame normally has a menu bar at the top which you can use to perform certain common operations. There's no need to list them here, as you can more easily see for yourself.

When you are using a window system, you can use the mouse to choose a command from the menu bar. An arrow pointing right, after the menu item, indicates that the item leads to a subsidiary menu; `...' at the end means that the command will read arguments from the keyboard before it actually does anything.

To view the full command name and documentation for a menu item, type C-h k, and then select the menu bar with the mouse in the usual way (see section Documentation for a Key).

On text-only terminals with no mouse, you can use the menu bar by typing M-` or F10 (these run the command tmm-menubar). This command enters a mode in which you can select a menu item from the keyboard. A provisional choice appears in the echo area. You can use the left and right arrow keys to move through the menu to different choices. When you have found the choice you want, type RET to select it.

Each menu item also has an assigned letter or digit which designates that item; it is usually the initial of some word in the item's name. This letter or digit is separated from the item name by `=>'. You can type the item's letter or digit to select the item.

Some of the commands in the menu bar have ordinary key bindings as well; if so, the menu lists one equivalent key binding in parentheses after the item itself.

Characters, Keys and Commands

This chapter explains the character sets used by Emacs for input commands and for the contents of files, and also explains the concepts of keys and commands, which are fundamental for understanding how Emacs interprets your keyboard and mouse input.

Kinds of User Input

GNU Emacs uses an extension of the ASCII character set for keyboard input; it also accepts non-character input events including function keys and mouse button actions.

ASCII consists of 128 character codes. Some of these codes are assigned graphic symbols such as `a' and `='; the rest are control characters, such as Control-a (usually written C-a for short). C-a gets its name from the fact that you type it by holding down the CTRL key while pressing a.

Some ASCII control characters have special names, and most terminals have special keys you can type them with: for example, RET, TAB, DEL and ESC. The space character is usually referred to below as SPC, even though strictly speaking it is a graphic character whose graphic happens to be blank. Some keyboards have a key labeled "linefeed" which is an alias for C-j.

Emacs extends the ASCII character set with thousands more printing characters (see section International Character Set Support), additional control characters, and a few more modifiers that can be combined with any character.

On ASCII terminals, there are only 32 possible control characters. These are the control variants of letters and `@[]\^_'. In addition, the shift key is meaningless with control characters: C-a and C-A are the same character, and Emacs cannot distinguish them.

But the Emacs character set has room for control variants of all printing characters, and for distinguishing between C-a and C-A. X Windows makes it possible to enter all these characters. For example, C-- (that's Control-Minus) and C-5 are meaningful Emacs commands under X.

Another Emacs character-set extension is additional modifier bits. Only one modifier bit is commonly used; it is called Meta. Every character has a Meta variant; examples include Meta-a (normally written M-a, for short), M-A (not the same character as M-a, but those two characters normally have the same meaning in Emacs), M-RET, and M-C-a. For reasons of tradition, we usually write C-M-a rather than M-C-a; logically speaking, the order in which the modifier keys CTRL and META are mentioned does not matter.

Some terminals have a META key, and allow you to type Meta characters by holding this key down. Thus, Meta-a is typed by holding down META and pressing a. The META key works much like the SHIFT key. Such a key is not always labeled META, however, as this function is often a special option for a key with some other primary purpose.

If there is no META key, you can still type Meta characters using two-character sequences starting with ESC. Thus, to enter M-a, you could type ESC a. To enter C-M-a, you would type ESC C-a. ESC is allowed on terminals with META keys, too, in case you have formed a habit of using it. X Windows provides several other modifier keys that can be applied to any input character. These are called SUPER, HYPER and ALT. We write `s-', `H-' and `A-' to say that a character uses these modifiers. Thus, s-H-C-x is short for Super-Hyper-Control-x. Not all X terminals actually provide keys for these modifier flags--in fact, many terminals have a key labeled ALT which is really a META key. The standard key bindings of Emacs do not include any characters with these modifiers. But you can assign them meanings of your own by customizing Emacs.

Keyboard input includes keyboard keys that are not characters at all: for example function keys and arrow keys. Mouse buttons are also outside the gamut of characters. You can modify these events with the modifier keys CTRL, META, SUPER, HYPER and ALT, just like keyboard characters.

Input characters and non-character inputs are collectively called input events. See section `Input Events' in The Emacs Lisp Reference Manual, for more information. If you are not doing Lisp programming, but simply want to redefine the meaning of some characters or non-character events, see section Customization.

ASCII terminals cannot really send anything to the computer except ASCII characters. These terminals use a sequence of characters to represent each function key. But that is invisible to the Emacs user, because the keyboard input routines recognize these special sequences and convert them to function key events before any other part of Emacs gets to see them.

Keys

A key sequence (key, for short) is a sequence of input events that are meaningful as a unit--as "a single command." Some Emacs command sequences are just one character or one event; for example, just C-f is enough to move forward one character. But Emacs also has commands that take two or more events to invoke.

If a sequence of events is enough to invoke a command, it is a complete key. Examples of complete keys include C-a, X, RET, NEXT (a function key), DOWN (an arrow key), C-x C-f, and C-x 4 C-f. If it isn't long enough to be complete, we call it a prefix key. The above examples show that C-x and C-x 4 are prefix keys. Every key sequence is either a complete key or a prefix key.

Most single characters constitute complete keys in the standard Emacs command bindings. A few of them are prefix keys. A prefix key combines with the following input event to make a longer key sequence, which may itself be complete or a prefix. For example, C-x is a prefix key, so C-x and the next input event combine to make a two-character key sequence. Most of these key sequences are complete keys, including C-x C-f and C-x b. A few, such as C-x 4 and C-x r, are themselves prefix keys that lead to three-character key sequences. There's no limit to the length of a key sequence, but in practice people rarely use sequences longer than four events.

By contrast, you can't add more events onto a complete key. For example, the two-character sequence C-f C-k is not a key, because the C-f is a complete key in itself. It's impossible to give C-f C-k an independent meaning as a command. C-f C-k is two key sequences, not one.

All told, the prefix keys in Emacs are C-c, C-h, C-x, C-x RET, C-x @, C-x a, C-x n, C-x r, C-x v, C-x 4, C-x 5, C-x 6, ESC, M-g and M-j. But this list is not cast in concrete; it is just a matter of Emacs's standard key bindings. If you customize Emacs, you can make new prefix keys, or eliminate these. See section Customizing Key Bindings.

If you do make or eliminate prefix keys, that changes the set of possible key sequences. For example, if you redefine C-f as a prefix, C-f C-k automatically becomes a key (complete, unless you define it too as a prefix). Conversely, if you remove the prefix definition of C-x 4, then C-x 4 f (or C-x 4 anything) is no longer a key.

Typing the help character (C-h or F1) after a prefix character displays a list of the commands starting with that prefix. There are a few prefix characters for which C-h does not work--for historical reasons, they have other meanings for C-h which are not easy to change. But F1 should work for all prefix characters.

Keys and Commands

This manual is full of passages that tell you what particular keys do. But Emacs does not assign meanings to keys directly. Instead, Emacs assigns meanings to named commands, and then gives keys their meanings by binding them to commands.

Every command has a name chosen by a programmer. The name is usually made of a few English words separated by dashes; for example, next-line or forward-word. A command also has a function definition which is a Lisp program; this is what makes the command do what it does. In Emacs Lisp, a command is actually a special kind of Lisp function; one which specifies how to read arguments for it and call it interactively. For more information on commands and functions, see section `What Is a Function' in The Emacs Lisp Reference Manual. (The definition we use in this manual is simplified slightly.)

The bindings between keys and commands are recorded in various tables called keymaps. See section Keymaps.

When we say that "C-n moves down vertically one line" we are glossing over a distinction that is irrelevant in ordinary use but is vital in understanding how to customize Emacs. It is the command next-line that is programmed to move down vertically. C-n has this effect because it is bound to that command. If you rebind C-n to the command forward-word then C-n will move forward by words instead. Rebinding keys is a common method of customization.

In the rest of this manual, we usually ignore this subtlety to keep things simple. To give the information needed for customization, we state the name of the command which really does the work in parentheses after mentioning the key that runs it. For example, we will say that "The command C-n (next-line) moves point vertically down," meaning that next-line is a command that moves vertically down and C-n is a key that is standardly bound to it.

While we are on the subject of information for customization only, it's a good time to tell you about variables. Often the description of a command will say, "To change this, set the variable mumble-foo." A variable is a name used to remember a value. Most of the variables documented in this manual exist just to facilitate customization: some command or other part of Emacs examines the variable and behaves differently according to the value that you set. Until you are interested in customizing, you can ignore the information about variables. When you are ready to be interested, read the basic information on variables, and then the information on individual variables will make sense. See section Variables.

Character Set for Text

Text in Emacs buffers is a sequence of 8-bit bytes. Each byte can hold a single ASCII character. Both ASCII control characters (octal codes 000 through 037, and 0177) and ASCII printing characters (codes 040 through 0176) are allowed; however, non-ASCII control characters cannot appear in a buffer. The other modifier flags used in keyboard input, such as Meta, are not allowed in buffers either.

Some ASCII control characters serve special purposes in text, and have special names. For example, the newline character (octal code 012) is used in the buffer to end a line, and the tab character (octal code 011) is used for indenting to the next tab stop column (normally every 8 columns). See section How Text Is Displayed.

Non-ASCII printing characters can also appear in buffers. When multibyte characters are enabled, you can use any of the non-ASCII printing characters that Emacs supports. They have character codes starting at 256, octal 0400, and each one is represented as a sequence of two or more bytes. See section International Character Set Support.

If you disable multibyte characters, then you can use only one alphabet of non-ASCII characters, but they all fit in one byte. They use codes 0200 through 0377. See section Single-byte European Character Support.

Entering and Exiting Emacs

The usual way to invoke Emacs is with the shell command `emacs'. Emacs clears the screen and then displays an initial help message and copyright notice. Some operating systems discard all type-ahead when Emacs starts up; they give Emacs no way to prevent this. Therefore, it is advisable to wait until Emacs clears the screen before typing your first editing command.

If you run Emacs from a shell window under the X Window System, run it in the background with `emacs&'. This way, Emacs does not tie up the shell window, so you can use that to run other shell commands while Emacs operates its own X windows. You can begin typing Emacs commands as soon as you direct your keyboard input to the Emacs frame.

When Emacs starts up, it makes a buffer named `*scratch*'. That's the buffer you start out in. The `*scratch*' buffer uses Lisp Interaction mode; you can use it to type Lisp expressions and evaluate them, or you can ignore that capability and simply doodle. (You can specify a different major mode for this buffer by setting the variable initial-major-mode in your init file. See section The Init File, `~/.emacs'.)

It is possible to specify files to be visited, Lisp files to be loaded, and functions to be called, by giving Emacs arguments in the shell command line. See section Command Line Arguments. But we don't recommend doing this. The feature exists mainly for compatibility with other editors.

Many other editors are designed to be started afresh each time you want to edit. You edit one file and then exit the editor. The next time you want to edit either another file or the same one, you must run the editor again. With these editors, it makes sense to use a command-line argument to say which file to edit.

But starting a new Emacs each time you want to edit a different file does not make sense. For one thing, this would be annoyingly slow. For another, this would fail to take advantage of Emacs's ability to visit more than one file in a single editing session. And it would lose the other accumulated context, such as registers, undo history, and the mark ring.

The recommended way to use GNU Emacs is to start it only once, just after you log in, and do all your editing in the same Emacs session. Each time you want to edit a different file, you visit it with the existing Emacs, which eventually comes to have many files in it ready for editing. Usually you do not kill the Emacs until you are about to log out. See section File Handling, for more information on visiting more than one file.

Exiting Emacs

There are two commands for exiting Emacs because there are two kinds of exiting: suspending Emacs and killing Emacs.

Suspending means stopping Emacs temporarily and returning control to its parent process (usually a shell), allowing you to resume editing later in the same Emacs job, with the same buffers, same kill ring, same undo history, and so on. This is the usual way to exit.

Killing Emacs means destroying the Emacs job. You can run Emacs again later, but you will get a fresh Emacs; there is no way to resume the same editing session after it has been killed.

C-z
Suspend Emacs (suspend-emacs) or iconify a frame (iconify-or-deiconify-frame).
C-x C-c
Kill Emacs (save-buffers-kill-emacs).

To suspend Emacs, type C-z (suspend-emacs). This takes you back to the shell from which you invoked Emacs. You can resume Emacs with the shell command `%emacs' in most common shells.

On systems that do not support suspending programs, C-z starts an inferior shell that communicates directly with the terminal. Emacs waits until you exit the subshell. (The way to do that is probably with C-d or `exit', but it depends on which shell you use.) The only way on these systems to get back to the shell from which Emacs was run (to log out, for example) is to kill Emacs.

Suspending also fails if you run Emacs under a shell that doesn't support suspending programs, even if the system itself does support it. In such a case, you can set the variable cannot-suspend to a non-nil value to force C-z to start an inferior shell. (One might also describe Emacs's parent shell as "inferior" for failing to support job control properly, but that is a matter of taste.)

When Emacs communicates directly with an X server and creates its own dedicated X windows, C-z has a different meaning. Suspending an applications that uses its own X windows is not meaningful or useful. Instead, C-z runs the command iconify-or-deiconify-frame, which temporarily closes up the selected Emacs frame (see section Frames and X Windows). The way to get back to a shell window is with the window manager.

To kill Emacs, type C-x C-c (save-buffers-kill-emacs). A two-character key is used for this to make it harder to type. This command first offers to save any modified file-visiting buffers. If you do not save them all, it asks for reconfirmation with yes before killing Emacs, since any changes not saved will be lost forever. Also, if any subprocesses are still running, C-x C-c asks for confirmation about them, since killing Emacs will kill the subprocesses immediately.

There is no way to restart an Emacs session once you have killed it. You can, however, arrange for Emacs to record certain session information, such as which files are visited, when you kill it, so that the next time you restart Emacs it will try to visit the same files and so on. See section Saving Emacs Sessions.

The operating system usually listens for certain special characters whose meaning is to kill or suspend the program you are running. This operating system feature is turned off while you are in Emacs. The meanings of C-z and C-x C-c as keys in Emacs were inspired by the use of C-z and C-c on several operating systems as the characters for stopping or killing a program, but that is their only relationship with the operating system. You can customize these keys to run any commands of your choice (see section Keymaps).

Basic Editing Commands

We now give the basics of how to enter text, make corrections, and save the text in a file. If this material is new to you, you might learn it more easily by running the Emacs learn-by-doing tutorial. To use the tutorial, run Emacs and type Control-h t (help-with-tutorial).

To clear the screen and redisplay, type C-l (recenter).

Inserting Text

To insert printing characters into the text you are editing, just type them. This inserts the characters you type into the buffer at the cursor (that is, at point; see section Point). The cursor moves forward, and any text after the cursor moves forward too. If the text in the buffer is `FOOBAR', with the cursor before the `B', then if you type XX, you get `FOOXXBAR', with the cursor still before the `B'.

To delete text you have just inserted, use DEL. DEL deletes the character before the cursor (not the one that the cursor is on top of or under; that is the character after the cursor). The cursor and all characters after it move backwards. Therefore, if you type a printing character and then type DEL, they cancel out.

To end a line and start typing a new one, type RET. This inserts a newline character in the buffer. If point is in the middle of a line, RET splits the line. Typing DEL when the cursor is at the beginning of a line deletes the preceding newline, thus joining the line with the preceding line.

Emacs can split lines automatically when they become too long, if you turn on a special minor mode called Auto Fill mode. See section Filling Text, for how to use Auto Fill mode.

If you prefer to have text characters replace (overwrite) existing text rather than shove it to the right, you can enable Overwrite mode, a minor mode. See section Minor Modes.

Direct insertion works for printing characters and SPC, but other characters act as editing commands and do not insert themselves. If you need to insert a control character or a character whose code is above 200 octal, you must quote it by typing the character Control-q (quoted-insert) first. (This character's name is normally written C-q for short.) There are two ways to use C-q:

  • C-q followed by any non-graphic character (even C-g) inserts that character.
  • C-q followed by a sequence of octal digits inserts the character with the specified octal character code. You can use any number of octal digits; any non-digit terminates the sequence. If the terminating character is RET, it serves only to terminate the sequence; any other non-digit is itself used as input after terminating the sequence. (The use of octal sequences is disabled in ordinary non-binary Overwrite mode, to give you a convenient way to insert a digit instead of overwriting with it.)

When multibyte characters are enabled, octal codes 0200 through 0377 are not valid as characters; if you specify a code in this range, C-q assumes that you intend to use some ISO Latin-n character set, and converts the specified code to the corresponding Emacs character code. See section Enabling Multibyte Characters. You select which ISO Latin character set though your choice of language environment (see section Language Environments).

To use decimal or hexadecimal instead of octal, set the variable read-quoted-char-radix to 10 or 16. If the radix is greater than 10, some letters starting with a serve as part of a character code, just like digits.

A numeric argument to C-q specifies how many copies of the quoted character should be inserted (see section Numeric Arguments).

Customization information: DEL in most modes runs the command delete-backward-char; RET runs the command newline, and self-inserting printing characters run the command self-insert, which inserts whatever character was typed to invoke it. Some major modes rebind DEL to other commands.

Changing the Location of Point

To do more than insert characters, you have to know how to move point (see section Point). The simplest way to do this is with arrow keys, or by clicking the left mouse button where you want to move to.

There are also control and meta characters for cursor motion. Some are equivalent to the arrow keys (these date back to the days before terminals had arrow keys, and are usable on terminals which don't have them). Others do more sophisticated things.

C-a
Move to the beginning of the line (beginning-of-line).
C-e
Move to the end of the line (end-of-line).
C-f
Move forward one character (forward-char).
C-b
Move backward one character (backward-char).
M-f
Move forward one word (forward-word).
M-b
Move backward one word (backward-word).
C-n
Move down one line, vertically (next-line). This command attempts to keep the horizontal position unchanged, so if you start in the middle of one line, you end in the middle of the next. When on the last line of text, C-n creates a new line and moves onto it.
C-p
Move up one line, vertically (previous-line).
M-r
Move point to left margin, vertically centered in the window (move-to-window-line). Text does not move on the screen. A numeric argument says which screen line to place point on. It counts screen lines down from the top of the window (zero for the top line). A negative argument counts lines from the bottom (-1 for the bottom line).
M-<
Move to the top of the buffer (beginning-of-buffer). With numeric argument n, move to n/10 of the way from the top. See section Numeric Arguments, for more information on numeric arguments.
M->
Move to the end of the buffer (end-of-buffer).
M-x goto-char
Read a number n and move point to buffer position n. Position 1 is the beginning of the buffer.
M-x goto-line
Read a number n and move point to line number n. Line 1 is the beginning of the buffer.
C-x C-n
Use the current column of point as the semipermanent goal column for C-n and C-p (set-goal-column). Henceforth, those commands always move to this column in each line moved into, or as close as possible given the contents of the line. This goal column remains in effect until canceled.
C-u C-x C-n
Cancel the goal column. Henceforth, C-n and C-p once again try to stick to a fixed horizontal position, as usual.

If you set the variable track-eol to a non-nil value, then C-n and C-p when at the end of the starting line move to the end of another line. Normally, track-eol is nil. See section Variables, for how to set variables such as track-eol.

Normally, C-n on the last line of a buffer appends a newline to it. If the variable next-line-add-newlines is nil, then C-n gets an error instead (like C-p on the first line).

Erasing Text

DEL
Delete the character before point (delete-backward-char).
C-d
Delete the character after point (delete-char).
C-k
Kill to the end of the line (kill-line).
M-d
Kill forward to the end of the next word (kill-word).
M-DEL
Kill back to the beginning of the previous word (backward-kill-word).

You already know about the DEL key which deletes the character before point (that is, before the cursor). Another key, Control-d (C-d for short), deletes the character after point (that is, the character that the cursor is on). This shifts the rest of the text on the line to the left. If you type C-d at the end of a line, it joins together that line and the next line.

To erase a larger amount of text, use the C-k key, which kills a line at a time. If you type C-k at the beginning or middle of a line, it kills all the text up to the end of the line. If you type C-k at the end of a line, it joins that line and the next line.

See section Deletion and Killing, for more flexible ways of killing text.

Undoing Changes

You can undo all the recent changes in the buffer text, up to a certain point. Each buffer records changes individually, and the undo command always applies to the current buffer. Usually each editing command makes a separate entry in the undo records, but some commands such as query-replace make many entries, and very simple commands such as self-inserting characters are often grouped to make undoing less tedious.

C-x u
Undo one batch of changes--usually, one command worth (undo).
C-_
The same.
C-u C-x u
Undo one batch of changes in the region.

The command C-x u or C-_ is how you undo. The first time you give this command, it undoes the last change. Point moves back to where it was before the command that made the change.

Consecutive repetitions of C-_ or C-x u undo earlier and earlier changes, back to the limit of the undo information available. If all recorded changes have already been undone, the undo command prints an error message and does nothing.

Any command other than an undo command breaks the sequence of undo commands. Starting from that moment, the previous undo commands become ordinary changes that you can undo. Thus, to redo changes you have undone, type C-f or any other command that will harmlessly break the sequence of undoing, then type more undo commands.

Ordinary undo applies to all changes made in the current buffer. You can also perform selective undo, limited to the current region. To do this, specify the region you want, then run the undo command with a prefix argument (the value does not matter): C-u C-x u or C-u C-_. This undoes the most recent change in the region. To undo further changes in the same region, repeat the undo command (no prefix argument is needed). In Transient Mark mode, any use of undo when there is an active region performs selective undo; you do not need a prefix argument.

If you notice that a buffer has been modified accidentally, the easiest way to recover is to type C-_ repeatedly until the stars disappear from the front of the mode line. At this time, all the modifications you made have been canceled. Whenever an undo command makes the stars disappear from the mode line, it means that the buffer contents are the same as they were when the file was last read in or saved.

If you do not remember whether you changed the buffer deliberately, type C-_ once. When you see the last change you made undone, you will see whether it was an intentional change. If it was an accident, leave it undone. If it was deliberate, redo the change as described above.

Not all buffers record undo information. Buffers whose names start with spaces don't; these buffers are used internally by Emacs and its extensions to hold text that users don't normally look at or edit.

You cannot undo mere cursor motion; only changes in the buffer contents save undo information. However, some cursor motion commands set the mark, so if you use these commands from time to time, you can move back to the neighborhoods you have moved through by popping the mark ring (see section The Mark Ring).

When the undo information for a buffer becomes too large, Emacs discards the oldest undo information from time to time (during garbage collection). You can specify how much undo information to keep by setting two variables: undo-limit and undo-strong-limit. Their values are expressed in units of bytes of space.

The variable undo-limit sets a soft limit: Emacs keeps undo data for enough commands to reach this size, and perhaps exceed it, but does not keep data for any earlier commands beyond that. Its default value is 20000. The variable undo-strong-limit sets a stricter limit: the command which pushes the size past this amount is itself forgotten. Its default value is 30000.

Regardless of the values of those variables, the most recent change is never discarded, so there is no danger that garbage collection occurring right after an unintentional large change might prevent you from undoing it.

The reason the undo command has two keys, C-x u and C-_, set up to run it is that it is worthy of a single-character key, but on some keyboards it is not obvious how to type C-_. C-x u is an alternative you can type straightforwardly on any terminal.

Files

The commands described above are sufficient for creating and altering text in an Emacs buffer; the more advanced Emacs commands just make things easier. But to keep any text permanently you must put it in a file. Files are named units of text which are stored by the operating system for you to retrieve later by name. To look at or use the contents of a file in any way, including editing the file with Emacs, you must specify the file name.

Consider a file named `/usr/rms/foo.c'. In Emacs, to begin editing this file, type

C-x C-f /usr/rms/foo.c RET

Here the file name is given as an argument to the command C-x C-f (find-file). That command uses the minibuffer to read the argument, and you type RET to terminate the argument (see section The Minibuffer).

Emacs obeys the command by visiting the file: creating a buffer, copying the contents of the file into the buffer, and then displaying the buffer for you to edit. If you alter the text, you can save the new text in the file by typing C-x C-s (save-buffer). This makes the changes permanent by copying the altered buffer contents back into the file `/usr/rms/foo.c'. Until you save, the changes exist only inside Emacs, and the file `foo.c' is unaltered.

To create a file, just visit the file with C-x C-f as if it already existed. This creates an empty buffer in which you can insert the text you want to put in the file. The file is actually created when you save this buffer with C-x C-s.

Of course, there is a lot more to learn about using files. See section File Handling.

Help

If you forget what a key does, you can find out with the Help character, which is C-h (or F1, which is an alias for C-h). Type C-h k followed by the key you want to know about; for example, C-h k C-n tells you all about what C-n does. C-h is a prefix key; C-h k is just one of its subcommands (the command describe-key). The other subcommands of C-h provide different kinds of help. Type C-h twice to get a description of all the help facilities. See section Help.

Blank Lines

Here are special commands and techniques for putting in and taking out blank lines.

C-o
Insert one or more blank lines after the cursor (open-line).
C-x C-o
Delete all but one of many consecutive blank lines (delete-blank-lines).

When you want to insert a new line of text before an existing line, you can do it by typing the new line of text, followed by RET. However, it may be easier to see what you are doing if you first make a blank line and then insert the desired text into it. This is easy to do using the key C-o (open-line), which inserts a newline after point but leaves point in front of the newline. After C-o, type the text for the new line. C-o F O O has the same effect as F O O RET, except for the final location of point.

You can make several blank lines by typing C-o several times, or by giving it a numeric argument to tell it how many blank lines to make. See section Numeric Arguments, for how. If you have a fill prefix, then C-o command inserts the fill prefix on the new line, when you use it at the beginning of a line. See section The Fill Prefix.

The easy way to get rid of extra blank lines is with the command C-x C-o (delete-blank-lines). C-x C-o in a run of several blank lines deletes all but one of them. C-x C-o on a solitary blank line deletes that blank line. When point is on a nonblank line, C-x C-o deletes any blank lines following that nonblank line.

Continuation Lines

If you add too many characters to one line without breaking it with RET, the line will grow to occupy two (or more) lines on the screen, with a `\' at the extreme right margin of all but the last of them. The `\' says that the following screen line is not really a distinct line in the text, but just the continuation of a line too long to fit the screen. Continuation is also called line wrapping.

Sometimes it is nice to have Emacs insert newlines automatically when a line gets too long. Continuation on the screen does not do that. Use Auto Fill mode (see section Filling Text) if that's what you want.

As an alternative to continuation, Emacs can display long lines by truncation. This means that all the characters that do not fit in the width of the screen or window do not appear at all. They remain in the buffer, temporarily invisible. `$' is used in the last column instead of `\' to inform you that truncation is in effect.

Truncation instead of continuation happens whenever horizontal scrolling is in use, and optionally in all side-by-side windows (see section Multiple Windows). You can enable truncation for a particular buffer by setting the variable truncate-lines to non-nil in that buffer. (See section Variables.) Altering the value of truncate-lines makes it local to the current buffer; until that time, the default value is in effect. The default is initially nil. See section Local Variables.

See section Variables Controlling Display, for additional variables that affect how text is displayed.

Cursor Position Information

Here are commands to get information about the size and position of parts of the buffer, and to count lines.

M-x what-page
Print page number of point, and line number within page.
M-x what-line
Print line number of point in the buffer.
M-x line-number-mode
Toggle automatic display of current line number.
M-=
Print number of lines in the current region (count-lines-region). See section The Mark and the Region, for information about the region.
C-x =
Print character code of character after point, character position of point, and column of point (what-cursor-position).

There are two commands for working with line numbers. M-x what-line computes the current line number and displays it in the echo area. To go to a given line by number, use M-x goto-line; it prompts you for the number. These line numbers count from one at the beginning of the buffer.

You can also see the current line number in the mode line; See section The Mode Line. If you narrow the buffer, then the line number in the mode line is relative to the accessible portion (see section Narrowing). By contrast, what-line shows both the line number relative to the narrowed region and the line number relative to the whole buffer.

By contrast, M-x what-page counts pages from the beginning of the file, and counts lines within the page, printing both numbers. See section Pages.

While on this subject, we might as well mention M-= (count-lines-region), which prints the number of lines in the region (see section The Mark and the Region). See section Pages, for the command C-x l which counts the lines in the current page.

The command C-x = (what-cursor-position) can be used to find out the column that the cursor is in, and other miscellaneous information about point. It prints a line in the echo area that looks like this:

Char: c (0143, 99, 0x63)  point=21044 of 26883(78%)  column 53

(In fact, this is the output produced when point is before the `column' in the example.)

The four values after `Char:' describe the character that follows point, first by showing it and then by giving its character code in octal, decimal and hex. For a non-ASCII multibyte character, these are followed by `ext' and the character's representation, in hex, in the buffer's coding system, if that coding system encodes the character safely and with a single byte (see section Coding Systems). If the character's encoding is longer than one byte, Emacs shows `ext ...'.

`point=' is followed by the position of point expressed as a character count. The front of the buffer counts as position 1, one character later as 2, and so on. The next, larger, number is the total number of characters in the buffer. Afterward in parentheses comes the position expressed as a percentage of the total size.

`column' is followed by the horizontal position of point, in columns from the left edge of the window.

If the buffer has been narrowed, making some of the text at the beginning and the end temporarily inaccessible, C-x = prints additional text describing the currently accessible range. For example, it might display this:

Char: C (0103, 67, 0x43)  point=252 of 889(28%) <231 - 599>  column 0

where the two extra numbers give the smallest and largest character position that point is allowed to assume. The characters between those two positions are the accessible ones. See section Narrowing.

If point is at the end of the buffer (or the end of the accessible part), the C-x = output does not describe a character after point. The output might look like this:

point=26957 of 26956(100%)  column 0

C-u C-x = displays additional information about a character, in place of the buffer coordinates and column: the character set name and the codes that identify the character within that character set; ASCII characters are identified as belonging to the ASCII character set. In addition, the full character encoding, even if it takes more than a single byte, is shown after `ext'. Here's an example for a Latin-1 character A with a grave accent in a buffer whose coding system is iso-2022-7bit(1):

Char: `A (04300, 2240, 0x8c0, ext ESC , A @) (latin-iso8859-1 64)

Numeric Arguments

In mathematics and computer usage, the word argument means "data provided to a function or operation." You can give any Emacs command a numeric argument (also called a prefix argument). Some commands interpret the argument as a repetition count. For example, C-f with an argument of ten moves forward ten characters instead of one. With these commands, no argument is equivalent to an argument of one. Negative arguments tell most such commands to move or act in the opposite direction.

If your terminal keyboard has a META key, the easiest way to specify a numeric argument is to type digits and/or a minus sign while holding down the META key. For example,

M-5 C-n

would move down five lines. The characters Meta-1, Meta-2, and so on, as well as Meta--, do this because they are keys bound to commands (digit-argument and negative-argument) that are defined to contribute to an argument for the next command. Digits and - modified with Control, or Control and Meta, also specify numeric arguments.

Another way of specifying an argument is to use the C-u (universal-argument) command followed by the digits of the argument. With C-u, you can type the argument digits without holding down modifier keys; C-u works on all terminals. To type a negative argument, type a minus sign after C-u. Just a minus sign without digits normally means -1.

C-u followed by a character which is neither a digit nor a minus sign has the special meaning of "multiply by four." It multiplies the argument for the next command by four. C-u twice multiplies it by sixteen. Thus, C-u C-u C-f moves forward sixteen characters. This is a good way to move forward "fast," since it moves about 1/5 of a line in the usual size screen. Other useful combinations are C-u C-n, C-u C-u C-n (move down a good fraction of a screen), C-u C-u C-o (make "a lot" of blank lines), and C-u C-k (kill four lines).

Some commands care only about whether there is an argument, and not about its value. For example, the command M-q (fill-paragraph) with no argument fills text; with an argument, it justifies the text as well. (See section Filling Text, for more information on M-q.) Plain C-u is a handy way of providing an argument for such commands.

Some commands use the value of the argument as a repeat count, but do something peculiar when there is no argument. For example, the command C-k (kill-line) with argument n kills n lines, including their terminating newlines. But C-k with no argument is special: it kills the text up to the next newline, or, if point is right at the end of the line, it kills the newline itself. Thus, two C-k commands with no arguments can kill a nonblank line, just like C-k with an argument of one. (See section Deletion and Killing, for more information on C-k.)

A few commands treat a plain C-u differently from an ordinary argument. A few others may treat an argument of just a minus sign differently from an argument of -1. These unusual cases are described when they come up; they are always for reasons of convenience of use of the individual command.

You can use a numeric argument to insert multiple copies of a character. This is straightforward unless the character is a digit; for example, C-u 6 4 a inserts 64 copies of the character `a'. But this does not work for inserting digits; C-u 6 4 1 specifies an argument of 641, rather than inserting anything. To separate the digit to insert from the argument, type another C-u; for example, C-u 6 4 C-u 1 does insert 64 copies of the character `1'.

We use the term "prefix argument" as well as "numeric argument" to emphasize that you type the argument before the command, and to distinguish these arguments from minibuffer arguments that come after the command.

Repeating a Command

The command C-x z (repeat) provides another way to repeat an Emacs command many times. This command repeats the previous Emacs command, whatever that was. Repeating a command uses the same arguments that were used before; it does not read new arguments each time.

To repeat the command more than once, type additional z's: each z repeats the command one more time. Repetition ends when you type a character other than z, or press a mouse button.

For example, suppose you type C-u 2 0 C-d to delete 20 characters. You can repeat that command (including its argument) three additional times, to delete a total of 80 characters, by typing C-x z z z. The first C-x z repeats the command once, and each subsequent z repeats it once again.

The Minibuffer

The minibuffer is the facility used by Emacs commands to read arguments more complicated than a single number. Minibuffer arguments can be file names, buffer names, Lisp function names, Emacs command names, Lisp expressions, and many other things, depending on the command reading the argument. You can use the usual Emacs editing commands in the minibuffer to edit the argument text.

When the minibuffer is in use, it appears in the echo area, and the terminal's cursor moves there. The beginning of the minibuffer line displays a prompt which says what kind of input you should supply and how it will be used. Often this prompt is derived from the name of the command that the argument is for. The prompt normally ends with a colon.

Sometimes a default argument appears in parentheses after the colon; it too is part of the prompt. The default will be used as the argument value if you enter an empty argument (for example, just type RET). For example, commands that read buffer names always show a default, which is the name of the buffer that will be used if you type just RET.

The simplest way to enter a minibuffer argument is to type the text you want, terminated by RET which exits the minibuffer. You can cancel the command that wants the argument, and get out of the minibuffer, by typing C-g.

Since the minibuffer uses the screen space of the echo area, it can conflict with other ways Emacs customarily uses the echo area. Here is how Emacs handles such conflicts:

  • If a command gets an error while you are in the minibuffer, this does not cancel the minibuffer. However, the echo area is needed for the error message and therefore the minibuffer itself is hidden for a while. It comes back after a few seconds, or as soon as you type anything.
  • If in the minibuffer you use a command whose purpose is to print a message in the echo area, such as C-x =, the message is printed normally, and the minibuffer is hidden for a while. It comes back after a few seconds, or as soon as you type anything.
  • Echoing of keystrokes does not take place while the minibuffer is in use.

Minibuffers for File Names

Sometimes the minibuffer starts out with text in it. For example, when you are supposed to give a file name, the minibuffer starts out containing the default directory, which ends with a slash. This is to inform you which directory the file will be found in if you do not specify a directory.

For example, the minibuffer might start out with these contents:

Find File: /u2/emacs/src/

where `Find File: ' is the prompt. Typing buffer.c specifies the file `/u2/emacs/src/buffer.c'. To find files in nearby directories, use ..; thus, if you type ../lisp/simple.el, you will get the file named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with M-DEL the directory names you don't want (see section Words).

If you don't want any of the default, you can kill it with C-a C-k. But you don't need to kill the default; you can simply ignore it. Insert an absolute file name, one starting with a slash or a tilde, after the default directory. For example, to specify the file `/etc/termcap', just insert that name, giving these minibuffer contents:

Find File: /u2/emacs/src//etc/termcap

GNU Emacs gives a special meaning to a double slash (which is not normally a useful thing to write): it means, "ignore everything before the second slash in the pair." Thus, `/u2/emacs/src/' is ignored in the example above, and you get the file `/etc/termcap'.

If you set insert-default-directory to nil, the default directory is not inserted in the minibuffer. This way, the minibuffer starts out empty. But the name you type, if relative, is still interpreted with respect to the same default directory.

Editing in the Minibuffer

The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual Emacs commands are available for editing the text of an argument you are entering.

Since RET in the minibuffer is defined to exit the minibuffer, you can't use it to insert a newline in the minibuffer. To do that, type C-o or C-q C-j. (Recall that a newline is really the character control-J.)

The minibuffer has its own window which always has space on the screen but acts as if it were not there when the minibuffer is not in use. When the minibuffer is in use, its window is just like the others; you can switch to another window with C-x o, edit text in other windows and perhaps even visit more files, before returning to the minibuffer to submit the argument. You can kill text in another window, return to the minibuffer window, and then yank the text to use it in the argument. See section Multiple Windows.

There are some restrictions on the use of the minibuffer window, however. You cannot switch buffers in it--the minibuffer and its window are permanently attached. Also, you cannot split or kill the minibuffer window. But you can make it taller in the normal fashion with C-x ^. If you enable Resize-Minibuffer mode, then the minibuffer window expands vertically as necessary to hold the text that you put in the minibuffer. Use M-x resize-minibuffer-mode to enable or disable this minor mode (see section Minor Modes).

Scrolling works specially in the minibuffer window. When the minibuffer is just one line high, and it contains a long line of text that won't fit on the screen, scrolling automatically maintains an overlap of a certain number of characters from one continuation line to the next. The variable minibuffer-scroll-overlap specifies how many characters of overlap; the default is 20.

If while in the minibuffer you issue a command that displays help text of any sort in another window, you can use the C-M-v command while in the minibuffer to scroll the help text. This lasts until you exit the minibuffer. This feature is especially useful if a completing minibuffer gives you a list of possible completions. See section Using Other Windows.

Emacs normally disallows most commands that use the minibuffer while the minibuffer is active. This rule is to prevent recursive minibuffers from confusing novice users. If you want to be able to use such commands in the minibuffer, set the variable enable-recursive-minibuffers to a non-nil value.

Completion

For certain kinds of arguments, you can use completion to enter the argument value. Completion means that you type part of the argument, then Emacs visibly fills in the rest, or as much as can be determined from the part you have typed.

When completion is available, certain keys---TAB, RET, and SPC---are rebound to complete the text present in the minibuffer into a longer string that it stands for, by matching it against a set of completion alternatives provided by the command reading the argument. ? is defined to display a list of possible completions of what you have inserted.

For example, when M-x uses the minibuffer to read the name of a command, it provides a list of all available Emacs command names to complete against. The completion keys match the text in the minibuffer against all the command names, find any additional name characters implied by the ones already present in the minibuffer, and add those characters to the ones you have given. This is what makes it possible to type M-x ins SPC b RET instead of M-x insert-buffer RET (for example).

Case is normally significant in completion, because it is significant in most of the names that you can complete (buffer names, file names and command names). Thus, `fo' does not complete to `Foo'. Completion does ignore case distinctions for certain arguments in which case does not matter.

Completion Example

A concrete example may help here. If you type M-x au TAB, the TAB looks for alternatives (in this case, command names) that start with `au'. There are several, including auto-fill-mode and auto-save-mode---but they are all the same as far as auto-, so the `au' in the minibuffer changes to `auto-'.

If you type TAB again immediately, there are multiple possibilities for the very next character--it could be any of `cfilrs'---so no more characters are added; instead, TAB displays a list of all possible completions in another window.

If you go on to type f TAB, this TAB sees `auto-f'. The only command name starting this way is auto-fill-mode, so completion fills in the rest of that. You now have `auto-fill-mode' in the minibuffer after typing just au TAB f TAB. Note that TAB has this effect because in the minibuffer it is bound to the command minibuffer-complete when completion is available.

Completion Commands

Here is a list of the completion commands defined in the minibuffer when completion is available.

TAB
Complete the text in the minibuffer as much as possible (minibuffer-complete).
SPC
Complete the minibuffer text, but don't go beyond one word (minibuffer-complete-word).
RET
Submit the text in the minibuffer as the argument, possibly completing first as described below (minibuffer-complete-and-exit).
?
Print a list of all possible completions of the text in the minibuffer (minibuffer-list-completions).

SPC completes much like TAB, but never goes beyond the next hyphen or space. If you have `auto-f' in the minibuffer and type SPC, it finds that the completion is `auto-fill-mode', but it stops completing after `fill-'. This gives `auto-fill-'. Another SPC at this point completes all the way to `auto-fill-mode'. SPC in the minibuffer when completion is available runs the command minibuffer-complete-word.

Here are some commands you can use to choose a completion from a window that displays a list of completions:

Mouse-2
Clicking mouse button 2 on a completion in the list of possible completions chooses that completion (mouse-choose-completion). You normally use this command while point is in the minibuffer; but you must click in the list of completions, not in the minibuffer itself.
PRIOR
M-v
Typing PRIOR or PAGE-UP, or M-v, while in the minibuffer, selects the window showing the completion list buffer (switch-to-completions). This paves the way for using the commands below. (Selecting that window in the usual ways has the same effect, but this way is more convenient.)
RET
Typing RET in the completion list buffer chooses the completion that point is in or next to (choose-completion). To use this command, you must first switch windows to the window that shows the list of completions.
RIGHT
Typing the right-arrow key RIGHT in the completion list buffer moves point to the following completion (next-completion).
LEFT
Typing the left-arrow key LEFT in the completion list buffer moves point toward the beginning of the buffer, to the previous completion (previous-completion).

Strict Completion

There are three different ways that RET can work in completing minibuffers, depending on how the argument will be used.

  • Strict completion is used when it is meaningless to give any argument except one of the known alternatives. For example, when C-x k reads the name of a buffer to kill, it is meaningless to give anything but the name of an existing buffer. In strict completion, RET refuses to exit if the text in the minibuffer does not complete to an exact match.
  • Cautious completion is similar to strict completion, except that RET exits only if the text was an exact match already, not needing completion. If the text is not an exact match, RET does not exit, but it does complete the text. If it completes to an exact match, a second RET will exit. Cautious completion is used for reading file names for files that must already exist.
  • Permissive completion is used when any string whatever is meaningful, and the list of completion alternatives is just a guide. For example, when C-x C-f reads the name of a file to visit, any file name is allowed, in case you want to create a file. In permissive completion, RET takes the text in the minibuffer exactly as given, without completing it.

The completion commands display a list of all possible completions in a window whenever there is more than one possibility for the very next character. Also, typing ? explicitly requests such a list. If the list of completions is long, you can scroll it with C-M-v (see section Using Other Windows).

Completion Options

When completion is done on file names, certain file names are usually ignored. The variable completion-ignored-extensions contains a list of strings; a file whose name ends in any of those strings is ignored as a possible completion. The standard value of this variable has several elements including ".o", ".elc", ".dvi" and "~". The effect is that, for example, `foo' can complete to `foo.c' even though `foo.o' exists as well. However, if all the possible completions end in "ignored" strings, then they are not ignored. Ignored extensions do not apply to lists of completions--those always mention all possible completions.

Normally, a completion command that finds the next character is undetermined automatically displays a list of all possible completions. If the variable completion-auto-help is set to nil, this does not happen, and you must type ? to display the possible completions.

The complete library implements a more powerful kind of completion that can complete multiple words at a time. For example, it can complete the command name abbreviation p-b into print-buffer, because no other command starts with two words whose initials are `p' and `b'. To use this library, put (load "complete") in your `~/.emacs' file (see section The Init File, `~/.emacs').

Icomplete mode presents a constantly-updated display that tells you what completions are available for the text you've entered so far. The command to enable or disable this minor mode is M-x icomplete-mode.

Minibuffer History

Every argument that you enter with the minibuffer is saved on a minibuffer history list so that you can use it again later in another argument. Special commands load the text of an earlier argument in the minibuffer. They discard the old minibuffer contents, so you can think of them as moving through the history of previous arguments.

UP
M-p
Move to the next earlier argument string saved in the minibuffer history (previous-history-element).
DOWN
M-n
Move to the next later argument string saved in the minibuffer history (next-history-element).
M-r regexp RET
Move to an earlier saved argument in the minibuffer history that has a match for regexp (previous-matching-history-element).
M-s regexp RET
Move to a later saved argument in the minibuffer history that has a match for regexp (next-matching-history-element).

The simplest way to reuse the saved arguments in the history list is to move through the history list one element at a time. While in the minibuffer, use M-p or up-arrow (previous-history-element) to "move to" the next earlier minibuffer input, and use M-n or down-arrow (next-history-element) to "move to" the next later input.

The previous input that you fetch from the history entirely replaces the contents of the minibuffer. To use it as the argument, exit the minibuffer as usual with RET. You can also edit the text before you reuse it; this does not change the history element that you "moved" to, but your new argument does go at the end of the history list in its own right.

For many minibuffer arguments there is a "default" value. In some cases, the minibuffer history commands know the default value. Then you can insert the default value into the minibuffer as text by using M-n to move "into the future" in the history. Eventually we hope to make this feature available whenever the minibuffer has a default value.

There are also commands to search forward or backward through the history; they search for history elements that match a regular expression that you specify with the minibuffer. M-r (previous-matching-history-element) searches older elements in the history, while M-s (next-matching-history-element) searches newer elements. By special dispensation, these commands can use the minibuffer to read their arguments even though you are already in the minibuffer when you issue them. As with incremental searching, an uppercase letter in the regular expression makes the search case-sensitive (see section Searching and Case).

All uses of the minibuffer record your input on a history list, but there are separate history lists for different kinds of arguments. For example, there is a list for file names, used by all the commands that read file names. (As a special feature, this history list records the absolute file name, no more and no less, even if that is not how you entered the file name.)

There are several other very specific history lists, including one for command names read by M-x, one for buffer names, one for arguments of commands like query-replace, and one for compilation commands read by compile. Finally, there is one "miscellaneous" history list that most minibuffer arguments use.

The variable history-length specifies the maximum length of a minibuffer history list; once a list gets that long, the oldest element is deleted each time an element is added. If the value of history-length is t, though, there is no maximum length and elements are never deleted.

Repeating Minibuffer Commands

Every command that uses the minibuffer at least once is recorded on a special history list, together with the values of its arguments, so that you can repeat the entire command. In particular, every use of M-x is recorded there, since M-x uses the minibuffer to read the command name.

C-x ESC ESC
Re-execute a recent minibuffer command (repeat-complex-command).
M-x list-command-history
Display the entire command history, showing all the commands C-x ESC ESC can repeat, most recent first.

C-x ESC ESC is used to re-execute a recent minibuffer-using command. With no argument, it repeats the last such command. A numeric argument specifies which command to repeat; one means the last one, and larger numbers specify earlier ones.

C-x ESC ESC works by turning the previous command into a Lisp expression and then entering a minibuffer initialized with the text for that expression. If you type just RET, the command is repeated as before. You can also change the command by editing the Lisp expression. Whatever expression you finally submit is what will be executed. The repeated command is added to the front of the command history unless it is identical to the most recently executed command already there.

Even if you don't understand Lisp syntax, it will probably be obvious which command is displayed for repetition. If you do not change the text, it will repeat exactly as before.

Once inside the minibuffer for C-x ESC ESC, you can use the minibuffer history commands (M-p, M-n, M-r, M-s; see section Minibuffer History) to move through the history list of saved entire commands. After finding the desired previous command, you can edit its expression as usual and then resubmit it by typing RET as usual.

The list of previous minibuffer-using commands is stored as a Lisp list in the variable command-history. Each element is a Lisp expression which describes one command and its arguments. Lisp programs can re-execute a command by calling eval with the command-history element.

Running Commands by Name

The Emacs commands that are used often or that must be quick to type are bound to keys--short sequences of characters--for convenient use. Other Emacs commands that do not need to be brief are not bound to keys; to run them, you must refer to them by name.

A command name is, by convention, made up of one or more words, separated by hyphens; for example, auto-fill-mode or manual-entry. The use of English words makes the command name easier to remember than a key made up of obscure characters, even though it is more characters to type.

The way to run a command by name is to start with M-x, type the command name, and finish it with RET. M-x uses the minibuffer to read the command name. RET exits the minibuffer and runs the command. The string `M-x' appears at the beginning of the minibuffer as a prompt to remind you to enter the name of a command to be run. See section The Minibuffer, for full information on the features of the minibuffer.

You can use completion to enter the command name. For example, the command forward-char can be invoked by name by typing

M-x forward-char RET

or

M-x forw TAB c RET

Note that forward-char is the same command that you invoke with the key C-f. You can run any Emacs command by name using M-x, whether or not any keys are bound to it.

If you type C-g while the command name is being read, you cancel the M-x command and get out of the minibuffer, ending up at top level.

To pass a numeric argument to the command you are invoking with M-x, specify the numeric argument before the M-x. M-x passes the argument along to the command it runs. The argument value appears in the prompt while the command name is being read.

If the command you type has a key binding of its own, Emacs mentions this in the echo area, two seconds after the command finishes (if you don't type anything else first). For example, if you type M-x forward-word, the message says that you can run the same command more easily by typing M-f. You can turn off these messages by setting suggest-key-bindings to nil.

Normally, when describing in this manual a command that is run by name, we omit the RET that is needed to terminate the name. Thus we might speak of M-x auto-fill-mode rather than M-x auto-fill-mode RET. We mention the RET only when there is a need to emphasize its presence, such as when we show the command together with following arguments.

M-x works by running the command execute-extended-command, which is responsible for reading the name of another command and invoking it.

Help

Emacs provides extensive help features accessible through a single character, C-h. C-h is a prefix key that is used only for documentation-printing commands. The characters that you can type after C-h are called help options. One help option is C-h; that is how you ask for help about using C-h. To cancel, type C-g. The function key F1 is equivalent to C-h.

C-h C-h (help-for-help) displays a list of the possible help options, each with a brief description. Before you type a help option, you can use SPC or DEL to scroll through the list.

C-h or F1 means "help" in various other contexts as well. For example, in the middle of query-replace, it describes the options available for how to operate on the current match. After a prefix key, it displays a list of the alternatives that can follow the prefix key. (A few prefix keys don't support C-h, because they define other meanings for it, but they all support F1.)

Most help buffers use a special major mode, Help mode, which lets you scroll conveniently with SPC and DEL.

Here is a summary of the defined help commands.

C-h a regexp RET
Display a list of commands whose names match regexp (apropos-command).
C-h b
Display a table of all key bindings in effect now, in this order: minor mode bindings, major mode bindings, and global bindings (describe-bindings).
C-h c key
Print the name of the command that key runs (describe-key-briefly). Here c stands for `character'. For more extensive information on key, use C-h k.
C-h f function RET
Display documentation on the Lisp function named function (describe-function). Since commands are Lisp functions, a command name may be used.
C-h h
Display the `hello' file, which shows examples of various character sets.
C-h i
Run Info, the program for browsing documentation files (info). The complete Emacs manual is available on-line in Info.
C-h k key
Display the name and documentation of the command that key runs (describe-key).
C-h l
Display a description of the last 100 characters you typed (view-lossage).
C-h m
Display documentation of the current major mode (describe-mode).
C-h n
Display documentation of Emacs changes, most recent first (view-emacs-news).
C-h p
Find packages by topic keyword (finder-by-keyword).
C-h s
Display current contents of the syntax table, plus an explanation of what they mean (describe-syntax). See section The Syntax Table.
C-h t
Enter the Emacs interactive tutorial (help-with-tutorial).
C-h v var RET
Display the documentation of the Lisp variable var (describe-variable).
C-h w command RET
Print which keys run the command named command (where-is).
C-h C coding RET
Describe coding system coding (describe-coding-system).
C-h C RET
Describe the coding systems currently in use.
C-h I method RET
Describe an input method (describe-input-method).
C-h L language-env RET
Describe information on the character sets, coding systems and input methods used for language environment language-env (describe-language-environment).
C-h C-c
Display the copying conditions for GNU Emacs.
C-h C-d
Display information about getting new versions of GNU Emacs.
C-h C-f function RET
Enter Info and go to the node documenting the Emacs function function (Info-goto-emacs-command-node).
C-h C-k key
Enter Info and go to the node where the key sequence key is documented (Info-goto-emacs-key-command-node).
C-h C-p
Display information about the GNU Project.
C-h TAB symbol RET
Display the Info documentation on symbol symbol according to the programming language you are editing (info-lookup-symbol).

Documentation for a Key

The most basic C-h options are C-h c (describe-key-briefly) and C-h k (describe-key). C-h c key prints in the echo area the name of the command that key is bound to. For example, C-h c C-f prints `forward-char'. Since command names are chosen to describe what the commands do, this is a good way to get a very brief description of what key does.

C-h k key is similar but gives more information: it displays the documentation string of the command as well as its name. This is too big for the echo area, so a window is used for the display.

C-h c and C-h k work for any sort of key sequences, including function keys and mouse events.

Help by Command or Variable Name

C-h f (describe-function) reads the name of a Lisp function using the minibuffer, then displays that function's documentation string in a window. Since commands are Lisp functions, you can use this to get the documentation of a command that you know by name. For example,

C-h f auto-fill-mode RET

displays the documentation of auto-fill-mode. This is the only way to get the documentation of a command that is not bound to any key (one which you would normally run using M-x).

C-h f is also useful for Lisp functions that you are planning to use in a Lisp program. For example, if you have just written the expression (make-vector len) and want to check that you are using make-vector properly, type C-h f make-vector RET. Because C-h f allows all function names, not just command names, you may find that some of your favorite abbreviations that work in M-x don't work in C-h f. An abbreviation may be unique among command names yet fail to be unique when other function names are allowed.

The function name for C-h f to describe has a default which is used if you type RET leaving the minibuffer empty. The default is the function called by the innermost Lisp expression in the buffer around point, provided that is a valid, defined Lisp function name. For example, if point is located following the text `(make-vector (car x)', the innermost list containing point is the one that starts with `(make-vector', so the default is to describe the function make-vector.

C-h f is often useful just to verify that you have the right spelling for the function name. If C-h f mentions a name from the buffer as the default, that name must be defined as a Lisp function. If that is all you want to know, just type C-g to cancel the C-h f command, then go on editing.

C-h w command RET tells you what keys are bound to command. It prints a list of the keys in the echo area. If it says the command is not on any key, you must use M-x to run it. C-h w runs the command where-is.

C-h v (describe-variable) is like C-h f but describes Lisp variables instead of Lisp functions. Its default is the Lisp symbol around or before point, but only if that is the name of a known Lisp variable. See section Variables.

Apropos

A more sophisticated sort of question to ask is, "What are the commands for working with files?" To ask this question, type C-h a file RET, which displays a list of all command names that contain `file', including copy-file, find-file, and so on. With each command name appears a brief description of how to use the command, and what keys you can currently invoke it with. For example, it would say that you can invoke find-file by typing C-x C-f. The a in C-h a stands for `Apropos'; C-h a runs the command apropos-command. This command normally checks only commands (interactive functions); if you specify a prefix argument, it checks noninteractive functions as well.

Because C-h a looks only for functions whose names contain the string you specify, you must use ingenuity in choosing the string. If you are looking for commands for killing backwards and C-h a kill-backwards RET doesn't reveal any, don't give up. Try just kill, or just backwards, or just back. Be persistent. Also note that you can use a regular expression as the argument, for more flexibility (see section Syntax of Regular Expressions).

Here is a set of arguments to give to C-h a that covers many classes of Emacs commands, since there are strong conventions for naming the standard Emacs commands. By giving you a feel for the naming conventions, this set should also serve to aid you in developing a technique for picking apropos strings.

char, line, word, sentence, paragraph, region, page, sexp, list, defun, rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, forward, backward, next, previous, up, down, search, goto, kill, delete, mark, insert, yank, fill, indent, case, change, set, what, list, find, view, describe, default.

To list all user variables that match a regexp, use the command M-x apropos-variable. This command shows only user variables and customization options by default; if you specify a prefix argument, it checks all variables.

To list all Lisp symbols that contain a match for a regexp, not just the ones that are defined as commands, use the command M-x apropos instead of C-h a. This command does not check key bindings by default; specify a numeric argument if you want it to check them.

The apropos-documentation command is like apropos except that it searches documentation strings as well as symbol names for matches for the specified regular expression.

The apropos-value command is like apropos except that it searches symbols' values for matches for the specified regular expression. This command does not check function definitions or property lists by default; specify a numeric argument if you want it to check them.

If the variable apropos-do-all is non-nil, the commands above all behave as if they had been given a prefix argument.

If you want more information about a function definition, variable or symbol property listed in the Apropos buffer, you can click on it with Mouse-2 or move there and type RET.

Keyword Search for Lisp Libraries

The C-h p command lets you search the standard Emacs Lisp libraries by topic keywords. Here is a partial list of keywords you can use:

abbrev -- abbreviation handling, typing shortcuts, macros.
bib -- support for the bibliography processor bib.
c -- C and C++ language support.
calendar -- calendar and time management support.
comm -- communications, networking, remote access to files.
data -- support for editing files of data.
docs -- support for Emacs documentation.
emulations -- emulations of other editors.
extensions -- Emacs Lisp language extensions.
faces -- support for using faces (fonts and colors; see section Using Multiple Typefaces).
frames -- support for Emacs frames and window systems.
games -- games, jokes and amusements.
hardware -- support for interfacing with exotic hardware.
help -- support for on-line help systems.
hypermedia -- support for links within text, or other media types.
i18n -- internationalization and alternate character-set support.
internal -- code for Emacs internals, build process, defaults.
languages -- specialized modes for editing programming languages.
lisp -- support for using Lisp (including Emacs Lisp).
local -- libraries local to your site.
maint -- maintenance aids for the Emacs development group.
mail -- modes for electronic-mail handling.
matching -- searching and matching.
news -- support for netnews reading and posting.
non-text -- support for editing files that are not ordinary text.
oop -- support for object-oriented programming.
outlines -- hierarchical outlining.
processes -- process, subshell, compilation, and job control support.
terminals -- support for terminal types.
tex -- support for the TeX formatter.
tools -- programming tools.
unix -- front-ends/assistants for, or emulators of, Unix features.
vms -- support code for VMS.
wp -- word processing.

Help for International Language Support

You can use the command C-h L (describe-language-environment) to find out the support for a specific language environment. See section Language Environments. This tells you which languages this language environment is useful for, and lists the character sets, coding systems, and input methods that go with it. It also shows some sample text to illustrate scripts.

The command C-h h (view-hello-file) displays the file `etc/HELLO', which shows how to say "hello" in many languages.

The command C-h I (describe-input-method) describes information about input methods--either a specified input method, or by default the input method in use. See section Input Methods.

The command C-h C (describe-coding-system) describes information about coding systems--either a specified coding system, or the ones currently in use. See section Coding Systems.

Help Mode Commands

Help buffers provide the commands of View mode (see section Miscellaneous File Operations), plus a few special commands of their own.

SPC
Scroll forward.
DEL
Scroll backward.
RET
Follow a cross reference at point.
TAB
Move point forward to the next cross reference.
S-TAB
Move point back to the previous cross reference.
Mouse-2
Follow a cross reference that you click on.

When a command name (see section Running Commands by Name) or variable name (see section Variables) appears in the documentation, it normally appears inside paired single-quotes. You can click on the name with Mouse-2, or move point there and type RET, to view the documentation of that command or variable. Use C-c C-b to retrace your steps.

There are convenient commands for moving point to cross references in the help text. TAB (help-next-ref) moves point down to the next cross reference. Use S-TAB to move point up to the previous cross reference (help-previous-ref).

Other Help Commands

C-h i (info) runs the Info program, which is used for browsing through structured documentation files. The entire Emacs manual is available within Info. Eventually all the documentation of the GNU system will be available. Type h after entering Info to run a tutorial on using Info.

If you specify a numeric argument, C-h i prompts for the name of a documentation file. This way, you can browse a file which doesn't have an entry in the top-level Info menu. It is also handy when you need to get to the documentation quickly, and you know the exact name of the file.

There are two special help commands for accessing Emacs documentation through Info. C-h C-f function RET enters Info and goes straight to the documentation of the Emacs function function. C-h C-k key enters Info and goes straight to the documentation of the key key. These two keys run the commands Info-goto-emacs-command-node and Info-goto-emacs-key-command-node.

When editing a program, if you have an Info version of the manual for the programming language, you can use the command C-h C-i to refer to the manual documentation for a symbol (keyword, function or variable). The details of how this command works depend on the major mode.

If something surprising happens, and you are not sure what commands you typed, use C-h l (view-lossage). C-h l prints the last 100 command characters you typed in. If you see commands that you don't know, you can use C-h c to find out what they do.

Emacs has numerous major modes, each of which redefines a few keys and makes a few other changes in how editing works. C-h m (describe-mode) prints documentation on the current major mode, which normally describes all the commands that are changed in this mode.

C-h b (describe-bindings) and C-h s (describe-syntax) present other information about the current Emacs mode. C-h b displays a list of all the key bindings now in effect; the local bindings defined by the current minor modes first, then the local bindings defined by the current major mode, and finally the global bindings (see section Customizing Key Bindings). C-h s displays the contents of the syntax table, with explanations of each character's syntax (see section The Syntax Table).

You can get a similar list for a particular prefix key by typing C-h after the prefix key. (There are a few prefix keys for which this does not work--those that provide their own bindings for C-h. One of these is ESC, because ESC C-h is actually C-M-h, which marks a defun.)

The other C-h options display various files of useful information. C-h C-w displays the full details on the complete absence of warranty for GNU Emacs. C-h n (view-emacs-news) displays the file `emacs/etc/NEWS', which contains documentation on Emacs changes arranged chronologically. C-h F (view-emacs-FAQ) displays the Emacs frequently-answered-questions list. C-h t (help-with-tutorial) displays the learn-by-doing Emacs tutorial. C-h C-c (describe-copying) displays the file `emacs/etc/COPYING', which tells you the conditions you must obey in distributing copies of Emacs. C-h C-d (describe-distribution) displays the file `emacs/etc/DISTRIB', which tells you how you can order a copy of the latest version of Emacs. C-h C-p (describe-project) displays general information about the GNU Project.

The Mark and the Region

Many Emacs commands operate on an arbitrary contiguous part of the current buffer. To specify the text for such a command to operate on, you set the mark at one end of it, and move point to the other end. The text between point and the mark is called the region. Emacs highlights the region whenever there is one, if you enable Transient Mark mode (see section Transient Mark Mode).

You can move point or the mark to adjust the boundaries of the region. It doesn't matter which one is set first chronologically, or which one comes earlier in the text. Once the mark has been set, it remains where you put it until you set it again at another place. Each Emacs buffer has its own mark, so that when you return to a buffer that had been selected previously, it has the same mark it had before.

Many commands that insert text, such as C-y (yank) and M-x insert-buffer, position point and the mark at opposite ends of the inserted text, so that the region contains the text just inserted.

Aside from delimiting the region, the mark is also useful for remembering a spot that you may want to go back to. To make this feature more useful, each buffer remembers 16 previous locations of the mark in the mark ring.

Setting the Mark

Here are some commands for setting the mark:

C-SPC
Set the mark where point is (set-mark-command).
C-@
The same.
C-x C-x
Interchange mark and point (exchange-point-and-mark).
Drag-Mouse-1
Set point and the mark around the text you drag across.
Mouse-3
Set the mark where point is, then move point to where you click (mouse-save-then-kill).

For example, suppose you wish to convert part of the buffer to upper case, using the C-x C-u (upcase-region) command, which operates on the text in the region. You can first go to the beginning of the text to be capitalized, type C-SPC to put the mark there, move to the end, and then type C-x C-u. Or, you can set the mark at the end of the text, move to the beginning, and then type C-x C-u.

The most common way to set the mark is with the C-SPC command (set-mark-command). This sets the mark where point is. Then you can move point away, leaving the mark behind.

There are two ways to set the mark with the mouse. You can drag mouse button one across a range of text; that puts point where you release the mouse button, and sets the mark at the other end of that range. Or you can click mouse button three, which sets the mark at point (like C-SPC) and then moves point (like Mouse-1). Both of these methods copy the region into the kill ring in addition to setting the mark; that gives behavior consistent with other window-driven applications, but if you don't want to modify the kill ring, you must use keyboard commands to set the mark. See section Mouse Commands for Editing.

Ordinary terminals have only one cursor, so there is no way for Emacs to show you where the mark is located. You have to remember. The usual solution to this problem is to set the mark and then use it soon, before you forget where it is. Alternatively, you can see where the mark is with the command C-x C-x (exchange-point-and-mark) which puts the mark where point was and point where the mark was. The extent of the region is unchanged, but the cursor and point are now at the previous position of the mark. In Transient Mark mode, this command reactivates the mark.

C-x C-x is also useful when you are satisfied with the position of point but want to move the other end of the region (where the mark is); do C-x C-x to put point at that end of the region, and then move it. A second use of C-x C-x, if necessary, puts the mark at the new position with point back at its original position.

There is no such character as C-SPC in ASCII; when you type SPC while holding down CTRL, what you get on most ordinary terminals is the character C-@. This key is actually bound to set-mark-command. But unless you are unlucky enough to have a terminal where typing C-SPC does not produce C-@, you might as well think of this character as C-SPC. Under X, C-SPC is actually a distinct character, but its binding is still set-mark-command.

Transient Mark Mode

Emacs can highlight the current region, using X Windows. But normally it does not. Why not?

Highlighting the region doesn't work well ordinarily in Emacs, because once you have set a mark, there is always a region (in that buffer). And highlighting the region all the time would be a nuisance.

You can turn on region highlighting by enabling Transient Mark mode. This is a more rigid mode of operation in which the region "lasts" only temporarily, so you must set up a region for each command that uses one. In Transient Mark mode, most of the time there is no region; therefore, highlighting the region when it exists is convenient.

To enable Transient Mark mode, type M-x transient-mark-mode. This command toggles the mode, so you can repeat the command to turn off the mode.

Here are the details of Transient Mark mode:

  • To set the mark, type C-SPC (set-mark-command). This makes the mark active; as you move point, you will see the region highlighting grow and shrink.
  • The mouse commands for specifying the mark also make it active. So do keyboard commands whose purpose is to specify a region, including M-@, C-M-@, M-h, C-M-h, C-x C-p, and C-x h.
  • When the mark is active, you can execute commands that operate on the region, such as killing, indenting, or writing to a file.
  • Any change to the buffer, such as inserting or deleting a character, deactivates the mark. This means any subsequent command that operates on a region will get an error and refuse to operate. You can make the region active again by typing C-x C-x.
  • Commands like M-> and C-s that "leave the mark behind" in addition to some other primary purpose do not activate the new mark. You can activate the new region by executing C-x C-x (exchange-point-and-mark).
  • C-s when the mark is active does not alter the mark.
  • Quitting with C-g deactivates the mark.

Highlighting of the region uses the region face; you can customize how the region is highlighted by changing this face. See section Customizing Faces.

When multiple windows show the same buffer, they can have different regions, because they can have different values of point (though they all share one common mark position). Ordinarily, only the selected window highlights its region (see section Multiple Windows). However, if the variable highlight-nonselected-windows is non-nil, then each window highlights its own region (provided that Transient Mark mode is enabled and the window's buffer's mark is active).

When Transient Mark mode is not enabled, every command that sets the mark also activates it, and nothing ever deactivates it.

If the variable mark-even-if-inactive is non-nil in Transient Mark mode, then commands can use the mark and the region even when it is inactive. Region highlighting appears and disappears just as it normally does in Transient Mark mode, but the mark doesn't really go away when the highlighting disappears.

Transient Mark mode is also sometimes known as "Zmacs mode" because the Zmacs editor on the MIT Lisp Machine handled the mark in a similar way.

Operating on the Region

Once you have a region and the mark is active, here are some of the ways you can operate on the region:

  • Kill it with C-w (see section Deletion and Killing).
  • Save it in a register with C-x r s (see section Registers).
  • Save it in a buffer or a file (see section Accumulating Text).
  • Convert case with C-x C-l or C-x C-u (see section Case Conversion Commands).
  • Indent it with C-x TAB or C-M-\ (see section Indentation).
  • Fill it as text with M-x fill-region (see section Filling Text).
  • Print hardcopy with M-x print-region (see section Hardcopy Output).
  • Evaluate it as Lisp code with M-x eval-region (see section Evaluating Emacs-Lisp Expressions).

Most commands that operate on the text in the region have the word region in their names.

Commands to Mark Textual Objects

Here are the commands for placing point and the mark around a textual object such as a word, list, paragraph or page.

M-@
Set mark after end of next word (mark-word). This command and the following one do not move point.
C-M-@
Set mark after end of next Lisp expression (mark-sexp).
M-h
Put region around current paragraph (mark-paragraph).
C-M-h
Put region around current Lisp defun (mark-defun).
C-x h
Put region around entire buffer (mark-whole-buffer).
C-x C-p
Put region around current page (mark-page).

M-@ (mark-word) puts the mark at the end of the next word, while C-M-@ (mark-sexp) puts it at the end of the next Lisp expression. These commands handle arguments just like M-f and C-M-f.

Other commands set both point and mark, to delimit an object in the buffer. For example, M-h (mark-paragraph) moves point to the beginning of the paragraph that surrounds or follows point, and puts the mark at the end of that paragraph (see section Paragraphs). It prepares the region so you can indent, case-convert, or kill a whole paragraph.

C-M-h (mark-defun) similarly puts point before and the mark after the current or following defun (see section Defuns). C-x C-p (mark-page) puts point before the current page, and mark at the end (see section Pages). The mark goes after the terminating page delimiter (to include it), while point goes after the preceding page delimiter (to exclude it). A numeric argument specifies a later page (if positive) or an earlier page (if negative) instead of the current page.

Finally, C-x h (mark-whole-buffer) sets up the entire buffer as the region, by putting point at the beginning and the mark at the end.

In Transient Mark mode, all of these commands activate the mark.

The Mark Ring

Aside from delimiting the region, the mark is also useful for remembering a spot that you may want to go back to. To make this feature more useful, each buffer remembers 16 previous locations of the mark, in the mark ring. Commands that set the mark also push the old mark onto this ring. To return to a marked location, use C-u C-SPC (or C-u C-@); this is the command set-mark-command given a numeric argument. It moves point to where the mark was, and restores the mark from the ring of former marks. Thus, repeated use of this command moves point to all of the old marks on the ring, one by one. The mark positions you move through in this way are not lost; they go to the end of the ring.

Each buffer has its own mark ring. All editing commands use the current buffer's mark ring. In particular, C-u C-SPC always stays in the same buffer.

Many commands that can move long distances, such as M-< (beginning-of-buffer), start by setting the mark and saving the old mark on the mark ring. This is to make it easier for you to move back later. Searches set the mark if they move point. You can tell when a command sets the mark because it displays `Mark Set' in the echo area.

If you want to move back to the same place over and over, the mark ring may not be convenient enough. If so, you can record the position in a register for later retrieval (see section Saving Positions in Registers).

The variable mark-ring-max specifies the maximum number of entries to keep in the mark ring. If that many entries exist and another one is pushed, the last one in the list is discarded. Repeating C-u C-SPC cycles through the positions currently in the ring.

The variable mark-ring holds the mark ring itself, as a list of marker objects, with the most recent first. This variable is local in every buffer.

The Global Mark Ring

In addition to the ordinary mark ring that belongs to each buffer, Emacs has a single global mark ring. It records a sequence of buffers in which you have recently set the mark, so you can go back to those buffers.

Setting the mark always makes an entry on the current buffer's mark ring. If you have switched buffers since the previous mark setting, the new mark position makes an entry on the global mark ring also. The result is that the global mark ring records a sequence of buffers that you have been in, and, for each buffer, a place where you set the mark.

The command C-x C-SPC (pop-global-mark) jumps to the buffer and position of the latest entry in the global ring. It also rotates the ring, so that successive uses of C-x C-SPC take you to earlier and earlier buffers.

Killing and Moving Text

Killing means erasing text and copying it into the kill ring, from which it can be retrieved by yanking it. Some systems use the terms "cutting" and "pasting" for these operations.

The commonest way of moving or copying text within Emacs is to kill it and later yank it elsewhere in one or more places. This is very safe because Emacs remembers several recent kills, not just the last one. It is versatile, because the many commands for killing syntactic units can also be used for moving those units. But there are other ways of copying text for special purposes.

Emacs has only one kill ring for all buffers, so you can kill text in one buffer and yank it in another buffer.

Deletion and Killing

Most commands which erase text from the buffer save it in the kill ring so that you can move or copy it to other parts of the buffer. These commands are known as kill commands. The rest of the commands that erase text do not save it in the kill ring; they are known as delete commands. (This distinction is made only for erasure of text in the buffer.) If you do a kill or delete command by mistake, you can use the C-x u (undo) command to undo it (see section Undoing Changes).

The delete commands include C-d (delete-char) and DEL (delete-backward-char), which delete only one character at a time, and those commands that delete only spaces or newlines. Commands that can destroy significant amounts of nontrivial data generally kill. The commands' names and individual descriptions use the words `kill' and `delete' to say which they do.

Deletion

C-d
Delete next character (delete-char).
DEL
Delete previous character (delete-backward-char).
M-\
Delete spaces and tabs around point (delete-horizontal-space).
M-SPC
Delete spaces and tabs around point, leaving one space (just-one-space).
C-x C-o
Delete blank lines around the current line (delete-blank-lines).
M-^
Join two lines by deleting the intervening newline, along with any indentation following it (delete-indentation).

The most basic delete commands are C-d (delete-char) and DEL (delete-backward-char). C-d deletes the character after point, the one the cursor is "on top of." This doesn't move point. DEL deletes the character before the cursor, and moves point back. You can delete newlines like any other characters in the buffer; deleting a newline joins two lines. Actually, C-d and DEL aren't always delete commands; when given arguments, they kill instead, since they can erase more than one character this way.

The other delete commands are those which delete only whitespace characters: spaces, tabs and newlines. M-\ (delete-horizontal-space) deletes all the spaces and tab characters before and after point. M-SPC (just-one-space) does likewise but leaves a single space after point, regardless of the number of spaces that existed previously (even zero).

C-x C-o (delete-blank-lines) deletes all blank lines after the current line. If the current line is blank, it deletes all blank lines preceding the current line as well (leaving one blank line, the current line).

M-^ (delete-indentation) joins the current line and the previous line, by deleting a newline and all surrounding spaces, usually leaving a single space. See section Indentation.

Killing by Lines

C-k
Kill rest of line or one or more lines (kill-line).

The simplest kill command is C-k. If given at the beginning of a line, it kills all the text on the line, leaving it blank. When used on a blank line, it kills the whole line including its newline. To kill an entire non-blank line, go to the beginning and type C-k twice.

More generally, C-k kills from point up to the end of the line, unless it is at the end of a line. In that case it kills the newline following point, thus merging the next line into the current one. Spaces and tabs that you can't see at the end of the line are ignored when deciding which case applies, so if point appears to be at the end of the line, you can be sure C-k will kill the newline.

When C-k is given a positive argument, it kills that many lines and the newlines that follow them (however, text on the current line before point is spared). With a negative argument -n, it kills n lines preceding the current line (together with the text on the current line before point). Thus, C-u - 2 C-k at the front of a line kills the two previous lines.

C-k with an argument of zero kills the text before point on the current line.

If the variable kill-whole-line is non-nil, C-k at the very beginning of a line kills the entire line including the following newline. This variable is normally nil.

Other Kill Commands

C-w
Kill region (from point to the mark) (kill-region).
M-d
Kill word (kill-word). See section Words.
M-DEL
Kill word backwards (backward-kill-word).
C-x DEL
Kill back to beginning of sentence (backward-kill-sentence). See section Sentences.
M-k
Kill to end of sentence (kill-sentence).
C-M-k
Kill sexp (kill-sexp). See section Lists and Sexps.
M-z char
Kill through the next occurrence of char (zap-to-char).

A kill command which is very general is C-w (kill-region), which kills everything between point and the mark. With this command, you can kill any contiguous sequence of characters, if you first set the region around them.

A convenient way of killing is combined with searching: M-z (zap-to-char) reads a character and kills from point up to (and including) the next occurrence of that character in the buffer. A numeric argument acts as a repeat count. A negative argument means to search backward and kill text before point.

Other syntactic units can be killed: words, with M-DEL and M-d (see section Words); sexps, with C-M-k (see section Lists and Sexps); and sentences, with C-x DEL and M-k (see section Sentences).

You can use kill commands in read-only buffers. They don't actually change the buffer, and they beep to warn you of that, but they do copy the text you tried to kill into the kill ring, so you can yank it into other buffers. Most of the kill commands move point across the text they copy in this way, so that successive kill commands build up a single kill ring entry as usual.

Yanking

Yanking means reinserting text previously killed. This is what some systems call "pasting." The usual way to move or copy text is to kill it and then yank it elsewhere one or more times.

C-y
Yank last killed text (yank).
M-y
Replace text just yanked with an earlier batch of killed text (yank-pop).
M-w
Save region as last killed text without actually killing it (kill-ring-save).
C-M-w
Append next kill to last batch of killed text (append-next-kill).

The Kill Ring

All killed text is recorded in the kill ring, a list of blocks of text that have been killed. There is only one kill ring, shared by all buffers, so you can kill text in one buffer and yank it in another buffer. This is the usual way to move text from one file to another. (See section Accumulating Text, for some other ways.)

The command C-y (yank) reinserts the text of the most recent kill. It leaves the cursor at the end of the text. It sets the mark at the beginning of the text. See section The Mark and the Region.

C-u C-y leaves the cursor in front of the text, and sets the mark after it. This happens only if the argument is specified with just a C-u, precisely. Any other sort of argument, including C-u and digits, specifies an earlier kill to yank (see section Yanking Earlier Kills).

To copy a block of text, you can use M-w (kill-ring-save), which copies the region into the kill ring without removing it from the buffer. This is approximately equivalent to C-w followed by C-x u, except that M-w does not alter the undo history and does not temporarily change the screen.

Appending Kills

Normally, each kill command pushes a new entry onto the kill ring. However, two or more kill commands in a row combine their text into a single entry, so that a single C-y yanks all the text as a unit, just as it was before it was killed.

Thus, if you want to yank text as a unit, you need not kill all of it with one command; you can keep killing line after line, or word after word, until you have killed it all, and you can still get it all back at once.

Commands that kill forward from point add onto the end of the previous killed text. Commands that kill backward from point add text onto the beginning. This way, any sequence of mixed forward and backward kill commands puts all the killed text into one entry without rearrangement. Numeric arguments do not break the sequence of appending kills. For example, suppose the buffer contains this text:

This is a line -!-of sample text.

with point shown by -!-. If you type M-d M-DEL M-d M-DEL, killing alternately forward and backward, you end up with `a line of sample' as one entry in the kill ring, and `This is  text.' in the buffer. (Note the double space, which you can clean up with M-SPC or M-q.)

Another way to kill the same text is to move back two words with M-b M-b, then kill all four words forward with C-u M-d. This produces exactly the same results in the buffer and in the kill ring. M-f M-f C-u M-DEL kills the same text, all going backward; once again, the result is the same. The text in the kill ring entry always has the same order that it had in the buffer before you killed it.

If a kill command is separated from the last kill command by other commands (not just numeric arguments), it starts a new entry on the kill ring. But you can force it to append by first typing the command C-M-w (append-next-kill) right before it. The C-M-w tells the following command, if it is a kill command, to append the text it kills to the last killed text, instead of starting a new entry. With C-M-w, you can kill several separated pieces of text and accumulate them to be yanked back in one place.

A kill command following M-w does not append to the text that M-w copied into the kill ring.

Yanking Earlier Kills

To recover killed text that is no longer the most recent kill, use the M-y command (yank-pop). It takes the text previously yanked and replaces it with the text from an earlier kill. So, to recover the text of the next-to-the-last kill, first use C-y to yank the last kill, and then use M-y to replace it with the previous kill. M-y is allowed only after a C-y or another M-y.

You can understand M-y in terms of a "last yank" pointer which points at an entry in the kill ring. Each time you kill, the "last yank" pointer moves to the newly made entry at the front of the ring. C-y yanks the entry which the "last yank" pointer points to. M-y moves the "last yank" pointer to a different entry, and the text in the buffer changes to match. Enough M-y commands can move the pointer to any entry in the ring, so you can get any entry into the buffer. Eventually the pointer reaches the end of the ring; the next M-y moves it to the first entry again.

M-y moves the "last yank" pointer around the ring, but it does not change the order of the entries in the ring, which always runs from the most recent kill at the front to the oldest one still remembered.

M-y can take a numeric argument, which tells it how many entries to advance the "last yank" pointer by. A negative argument moves the pointer toward the front of the ring; from the front of the ring, it moves "around" to the last entry and continues forward from there.

Once the text you are looking for is brought into the buffer, you can stop doing M-y commands and it will stay there. It's just a copy of the kill ring entry, so editing it in the buffer does not change what's in the ring. As long as no new killing is done, the "last yank" pointer remains at the same place in the kill ring, so repeating C-y will yank another copy of the same previous kill.

If you know how many M-y commands it would take to find the text you want, you can yank that text in one step using C-y with a numeric argument. C-y with an argument restores the text the specified number of entries back in the kill ring. Thus, C-u 2 C-y gets the next-to-the-last block of killed text. It is equivalent to C-y M-y. C-y with a numeric argument starts counting from the "last yank" pointer, and sets the "last yank" pointer to the entry that it yanks.

The length of the kill ring is controlled by the variable kill-ring-max; no more than that many blocks of killed text are saved.

The actual contents of the kill ring are stored in a variable named kill-ring; you can view the entire contents of the kill ring with the command C-h v kill-ring.

Accumulating Text

Usually we copy or move text by killing it and yanking it, but there are other methods convenient for copying one block of text in many places, or for copying many scattered blocks of text into one place. To copy one block to many places, store it in a register (see section Registers). Here we describe the commands to accumulate scattered pieces of text into a buffer or into a file.

M-x append-to-buffer
Append region to contents of specified buffer.
M-x prepend-to-buffer
Prepend region to contents of specified buffer.
M-x copy-to-buffer
Copy region into specified buffer, deleting that buffer's old contents.
M-x insert-buffer
Insert contents of specified buffer into current buffer at point.
M-x append-to-file
Append region to contents of specified file, at the end.

To accumulate text into a buffer, use M-x append-to-buffer. This reads a buffer name, then inserts a copy of the region into the buffer specified. If you specify a nonexistent buffer, append-to-buffer creates the buffer. The text is inserted wherever point is in that buffer. If you have been using the buffer for editing, the copied text goes into the middle of the text of the buffer, wherever point happens to be in it.

Point in that buffer is left at the end of the copied text, so successive uses of append-to-buffer accumulate the text in the specified buffer in the same order as they were copied. Strictly speaking, append-to-buffer does not always append to the text already in the buffer--it appends only if point in that buffer is at the end. However, if append-to-buffer is the only command you use to alter a buffer, then point is always at the end.

M-x prepend-to-buffer is just like append-to-buffer except that point in the other buffer is left before the copied text, so successive prependings add text in reverse order. M-x copy-to-buffer is similar except that any existing text in the other buffer is deleted, so the buffer is left containing just the text newly copied into it.

To retrieve the accumulated text from another buffer, use the command M-x insert-buffer; this too takes buffername as an argument. It inserts a copy of the text in buffer buffername into the selected buffer. You can alternatively select the other buffer for editing, then optionally move text from it by killing. See section Using Multiple Buffers, for background information on buffers.

Instead of accumulating text within Emacs, in a buffer, you can append text directly into a file with M-x append-to-file, which takes filename as an argument. It adds the text of the region to the end of the specified file. The file is changed immediately on disk.

You should use append-to-file only with files that are not being visited in Emacs. Using it on a file that you are editing in Emacs would change the file behind Emacs's back, which can lead to losing some of your editing.

Rectangles

The rectangle commands operate on rectangular areas of the text: all the characters between a certain pair of columns, in a certain range of lines. Commands are provided to kill rectangles, yank killed rectangles, clear them out, fill them with blanks or text, or delete them. Rectangle commands are useful with text in multicolumn formats, and for changing text into or out of such formats.

When you must specify a rectangle for a command to work on, you do it by putting the mark at one corner and point at the opposite corner. The rectangle thus specified is called the region-rectangle because you control it in about the same way the region is controlled. But remember that a given combination of point and mark values can be interpreted either as a region or as a rectangle, depending on the command that uses them.

If point and the mark are in the same column, the rectangle they delimit is empty. If they are in the same line, the rectangle is one line high. This asymmetry between lines and columns comes about because point (and likewise the mark) is between two columns, but within a line.

C-x r k
Kill the text of the region-rectangle, saving its contents as the "last killed rectangle" (kill-rectangle).
C-x r d
Delete the text of the region-rectangle (delete-rectangle).
C-x r y
Yank the last killed rectangle with its upper left corner at point (yank-rectangle).
C-x r o
Insert blank space to fill the space of the region-rectangle (open-rectangle). This pushes the previous contents of the region-rectangle rightward.
M-x clear-rectangle
Clear the region-rectangle by replacing its contents with spaces.
M-x delete-whitespace-rectangle
Delete whitespace in each of the lines on the specified rectangle, starting from the left edge column of the rectangle.
C-x r t string RET
Insert string on each line of the region-rectangle (string-rectangle).

The rectangle operations fall into two classes: commands deleting and inserting rectangles, and commands for blank rectangles.

There are two ways to get rid of the text in a rectangle: you can discard the text (delete it) or save it as the "last killed" rectangle. The commands for these two ways are C-x r d (delete-rectangle) and C-x r k (kill-rectangle). In either case, the portion of each line that falls inside the rectangle's boundaries is deleted, causing following text (if any) on the line to move left into the gap.

Note that "killing" a rectangle is not killing in the usual sense; the rectangle is not stored in the kill ring, but in a special place that can only record the most recent rectangle killed. This is because yanking a rectangle is so different from yanking linear text that different yank commands have to be used and yank-popping is hard to make sense of.

To yank the last killed rectangle, type C-x r y (yank-rectangle). Yanking a rectangle is the opposite of killing one. Point specifies where to put the rectangle's upper left corner. The rectangle's first line is inserted there, the rectangle's second line is inserted at a position one line vertically down, and so on. The number of lines affected is determined by the height of the saved rectangle.

You can convert single-column lists into double-column lists using rectangle killing and yanking; kill the second half of the list as a rectangle and then yank it beside the first line of the list. See section Two-Column Editing, for another way to edit multi-column text.

You can also copy rectangles into and out of registers with C-x r r r and C-x r i r. See section Saving Rectangles in Registers.

There are two commands you can use for making blank rectangles: M-x clear-rectangle which blanks out existing text, and C-x r o (open-rectangle) which inserts a blank rectangle. Clearing a rectangle is equivalent to deleting it and then inserting a blank rectangle of the same size.

The command M-x delete-whitespace-rectangle deletes horizontal whitespace starting from a particular column. This applies to each of the lines in the rectangle, and the column is specified by the left edge of the rectangle. The right edge of the rectangle does not make any difference to this command.

The command C-x r t (M-x string-rectangle) replaces the rectangle with a specified string (inserted once on each line). The string's width need not be the same as the width of the rectangle. If the string's width is less, the text after the rectangle shifts left; if the string is wider than the rectangle, the text after the rectangle shifts right.

Registers

Emacs registers are places you can save text or positions for later use. Once you save text or a rectangle in a register, you can copy it into the buffer once or many times; you can move point to a position saved in a register once or many times.

Each register has a name which is a single character. A register can store a piece of text, a rectangle, a position, a window configuration, or a file name, but only one thing at any given time. Whatever you store in a register remains there until you store something else in that register. To see what a register r contains, use M-x view-register.

M-x view-register RET r
Display a description of what register r contains.

Saving Positions in Registers

Saving a position records a place in a buffer so that you can move back there later. Moving to a saved position switches to that buffer and moves point to that place in it.

C-x r SPC r
Save position of point in register r (point-to-register).
C-x r j r
Jump to the position saved in register r (jump-to-register).

To save the current position of point in a register, choose a name r and type C-x r SPC r. The register r retains the position thus saved until you store something else in that register.

The command C-x r j r moves point to the position recorded in register r. The register is not affected; it continues to record the same position. You can jump to the saved position any number of times.

If you use C-x r j to go to a saved position, but the buffer it was saved from has been killed, C-x r j tries to create the buffer again by visiting the same file. Of course, this works only for buffers that were visiting files.

Saving Text in Registers

When you want to insert a copy of the same piece of text several times, it may be inconvenient to yank it from the kill ring, since each subsequent kill moves that entry further down the ring. An alternative is to store the text in a register and later retrieve it.

C-x r s r
Copy region into register r (copy-to-register).
C-x r i r
Insert text from register r (insert-register).

C-x r s r stores a copy of the text of the region into the register named r. Given a numeric argument, C-x r s r deletes the text from the buffer as well.

C-x r i r inserts in the buffer the text from register r. Normally it leaves point before the text and places the mark after, but with a numeric argument (C-u) it puts point after the text and the mark before.

Saving Rectangles in Registers

A register can contain a rectangle instead of linear text. The rectangle is represented as a list of strings. See section Rectangles, for basic information on how to specify a rectangle in the buffer.

C-x r r r
Copy the region-rectangle into register r (copy-rectangle-to-register). With numeric argument, delete it as well.
C-x r i r
Insert the rectangle stored in register r (if it contains a rectangle) (insert-register).

The C-x r i r command inserts a text string if the register contains one, and inserts a rectangle if the register contains one.

See also the command sort-columns, which you can think of as sorting a rectangle. See section Sorting Text.

Saving Window Configurations in Registers

You can save the window configuration of the selected frame in a register, or even the configuration of all windows in all frames, and restore the configuration later.

C-x r w r
Save the state of the selected frame's windows in register r (window-configuration-to-register).
C-x r f r
Save the state of all frames, including all their windows, in register r (frame-configuration-to-register).

Use C-x r j r to restore a window or frame configuration. This is the same command used to restore a cursor position. When you restore a frame configuration, any existing frames not included in the configuration become invisible. If you wish to delete these frames instead, use C-u C-x r j r.

Keeping Numbers in Registers

There are commands to store a number in a register, to insert the number in the buffer in decimal, and to increment it. These commands can be useful in keyboard macros (see section Keyboard Macros).

C-u number C-x r n reg
Store number into register reg (number-to-register).
C-u number C-x r + reg
Increment the number in register reg by number (increment-register).
C-x r g reg
Insert the number from register reg into the buffer.

C-x r g is the same command used to insert any other sort of register contents into the buffer.

Keeping File Names in Registers

If you visit certain file names frequently, you can visit them more conveniently if you put their names in registers. Here's the Lisp code used to put a file name in a register:

(set-register ?r '(file . name))

For example,

(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog"))

puts the file name shown in register `z'.

To visit the file whose name is in register r, type C-x r j r. (This is the same command used to jump to a position or restore a frame configuration.)

Bookmarks

Bookmarks are somewhat like registers in that they record positions you can jump to. Unlike registers, they have long names, and they persist automatically from one Emacs session to the next. The prototypical use of bookmarks is to record "where you were reading" in various files.

C-x r m RET
Set the bookmark for the visited file, at point.
C-x r m bookmark RET
Set the bookmark named bookmark at point (bookmark-set).
C-x r b bookmark RET
Jump to the bookmark named bookmark (bookmark-jump).
C-x r l
List all bookmarks (list-bookmarks).
M-x bookmark-save
Save all the current bookmark values in the default bookmark file.

The prototypical use for bookmarks is to record one current position in each of several files. So the command C-x r m, which sets a bookmark, uses the visited file name as the default for the bookmark name. If you name each bookmark after the file it points to, then you can conveniently revisit any of those files with C-x r b, and move to the position of the bookmark at the same time.

To display a list of all your bookmarks in a separate buffer, type C-x r l (list-bookmarks). If you switch to that buffer, you can use it to edit your bookmark definitions or annotate the bookmarks. Type C-h m in that buffer for more information about its special editing commands.

When you kill Emacs, Emacs offers to save your bookmark values in your default bookmark file, `~/.emacs.bmk', if you have changed any bookmark values. You can also save the bookmarks at any time with the M-x bookmark-save command. The bookmark commands load your default bookmark file automatically. This saving and loading is how bookmarks persist from one Emacs session to the next.

If you set the variable bookmark-save-flag to 1, then each command that sets a bookmark will also save your bookmarks; this way, you don't lose any bookmark values even if Emacs crashes. (The value, if a number, says how many bookmark modifications should go by between saving.)

Bookmark position values are saved with surrounding context, so that bookmark-jump can find the proper position even if the file is modified slightly. The variable bookmark-search-size says how many characters of context to record, on each side of the bookmark's position.

Here are some additional commands for working with bookmarks:

M-x bookmark-load RET filename RET
Load a file named filename that contains a list of bookmark values. You can use this command, as well as bookmark-write, to work with other files of bookmark values in addition to your default bookmark file.
M-x bookmark-write RET filename RET
Save all the current bookmark values in the file filename.
M-x bookmark-delete RET bookmark RET
Delete the bookmark named bookmark.
M-x bookmark-insert-location RET bookmark RET
Insert in the buffer the name of the file that bookmark bookmark points to.
M-x bookmark-insert RET bookmark RET
Insert in the buffer the contents of the file that bookmark bookmark points to.

Controlling the Display

Since only part of a large buffer fits in the window, Emacs tries to show a part that is likely to be interesting. Display-control commands allow you to specify which part of the text you want to see, and how to display it.

Scrolling

If a buffer contains text that is too large to fit entirely within a window that is displaying the buffer, Emacs shows a contiguous portion of the text. The portion shown always contains point.

Scrolling means moving text up or down in the window so that different parts of the text are visible. Scrolling forward means that text moves up, and new text appears at the bottom. Scrolling backward moves text down and new text appears at the top.

Scrolling happens automatically if you move point past the bottom or top of the window. You can also explicitly request scrolling with the commands in this section.

C-l
Clear screen and redisplay, scrolling the selected window to center point vertically within it (recenter).
C-v
Scroll forward (a windowful or a specified number of lines) (scroll-up).
NEXT
Likewise, scroll forward.
M-v
Scroll backward (scroll-down).
PRIOR
Likewise, scroll backward.
arg C-l
Scroll so point is on line arg (recenter).
C-M-l
Scroll heuristically to bring useful information onto the screen (reposition-window).

The most basic scrolling command is C-l (recenter) with no argument. It clears the entire screen and redisplays all windows. In addition, it scrolls the selected window so that point is halfway down from the top of the window.

The scrolling commands C-v and M-v let you move all the text in the window up or down a few lines. C-v (scroll-up) with an argument shows you that many more lines at the bottom of the window, moving the text and point up together as C-l might. C-v with a negative argument shows you more lines at the top of the window. M-v (scroll-down) is like C-v, but moves in the opposite direction. The function keys NEXT and PRIOR are equivalent to C-v and M-v.

The names of scroll commands are based on the direction that the text moves in the window. Thus, the command to scroll forward is called scroll-up because it moves the text upward on the screen.

To read the buffer a windowful at a time, use C-v with no argument. It takes the last two lines at the bottom of the window and puts them at the top, followed by nearly a whole windowful of lines not previously visible. If point was in the text scrolled off the top, it moves to the new top of the window. M-v with no argument moves backward with overlap similarly. The number of lines of overlap across a C-v or M-v is controlled by the variable next-screen-context-lines; by default, it is 2.

Some users like the full-screen scroll commands to keep point at the same screen line. To enable this behavior, set the variable scroll-preserve-screen-position to a non-nil value. This mode is convenient for browsing through a file by scrolling by screenfuls; if you come back to the screen where you started, point goes back to the line where it started. However, this mode is inconvenient when you move to the next screen in order to move point to the text there.

Another way to do scrolling is with C-l with a numeric argument. C-l does not clear the screen when given an argument; it only scrolls the selected window. With a positive argument n, it repositions text to put point n lines down from the top. An argument of zero puts point on the very top line. Point does not move with respect to the text; rather, the text and point move rigidly on the screen. C-l with a negative argument puts point that many lines from the bottom of the window. For example, C-u - 1 C-l puts point on the bottom line, and C-u - 5 C-l puts it five lines from the bottom. Just C-u as argument, as in C-u C-l, scrolls point to the center of the selected window.

The C-M-l command (reposition-window) scrolls the current window heuristically in a way designed to get useful information onto the screen. For example, in a Lisp file, this command tries to get the entire current defun onto the screen if possible.

Scrolling happens automatically if point has moved out of the visible portion of the text when it is time to display. Normally, automatic scrolling centers point vertically within the window. However, if you set scroll-conservatively to a small number n, then if you move point just a little off the screen--less than n lines--then Emacs scrolls the text just far enough to bring point back on screen. By default, scroll-conservatively is 0.

The variable scroll-margin restricts how close point can come to the top or bottom of a window. Its value is a number of screen lines; if point comes within that many lines of the top or bottom of the window, Emacs recenters the window. By default, scroll-margin is 0.

Horizontal Scrolling

Horizontal scrolling means shifting all the lines sideways within a window--so that some of the text near the left margin is not displayed at all.

C-x <
Scroll text in current window to the left (scroll-left).
C-x >
Scroll to the right (scroll-right).

When a window has been scrolled horizontally, text lines are truncated rather than continued (see section Continuation Lines), with a `$' appearing in the first column when there is text truncated to the left, and in the last column when there is text truncated to the right.

The command C-x < (scroll-left) scrolls the selected window to the left by n columns with argument n. This moves part of the beginning of each line off the left edge of the window. With no argument, it scrolls by almost the full width of the window (two columns less, to be precise).

C-x > (scroll-right) scrolls similarly to the right. The window cannot be scrolled any farther to the right once it is displayed normally (with each line starting at the window's left margin); attempting to do so has no effect. This means that you don't have to calculate the argument precisely for C-x >; any sufficiently large argument will restore the normal display.

You can request automatic horizontal scrolling by enabling Hscroll mode. When this mode is enabled, Emacs scrolls a window horizontally whenever that is necessary to keep point visible and not too far from the left or right edge. The command to enable or disable this mode is M-x hscroll-mode.

Follow Mode

Follow mode is a minor mode that makes two windows showing the same buffer scroll as one tall "virtual window." To use Follow mode, go to a frame with just one window, split it into two side-by-side windows using C-x 3, and then type M-x follow-mode. From then on, you can edit the buffer in either of the two windows, or scroll either one; the other window follows it.

To turn off Follow mode, type M-x follow-mode a second time.

Selective Display

Emacs has the ability to hide lines indented more than a certain number of columns (you specify how many columns). You can use this to get an overview of a part of a program.

To hide lines, type C-x $ (set-selective-display) with a numeric argument n. Then lines with at least n columns of indentation disappear from the screen. The only indication of their presence is that three dots (`...') appear at the end of each visible line that is followed by one or more hidden ones.

The commands C-n and C-p move across the hidden lines as if they were not there.

The hidden lines are still present in the buffer, and most editing commands see them as usual, so you may find point in the middle of the hidden text. When this happens, the cursor appears at the end of the previous line, after the three dots. If point is at the end of the visible line, before the newline that ends it, the cursor appears before the three dots.

To make all lines visible again, type C-x $ with no argument.

If you set the variable selective-display-ellipses to nil, the three dots do not appear at the end of a line that precedes hidden lines. Then there is no visible indication of the hidden lines. This variable becomes local automatically when set.

Optional Mode Line Features

The current line number of point appears in the mode line when Line Number mode is enabled. Use the command M-x line-number-mode to turn this mode on and off; normally it is on. The line number appears before the buffer percentage pos, with the letter `L' to indicate what it is. See section Minor Modes, for more information about minor modes and about how to use this command.

If the buffer is very large (larger than the value of line-number-display-limit), then the line number doesn't appear. Emacs doesn't compute the line number when the buffer is large, because that would be too slow. If you have narrowed the buffer (see section Narrowing), the displayed line number is relative to the accessible portion of the buffer.

You can also display the current column number by turning on Column Number mode. It displays the current column number preceded by the letter `C'. Type M-x column-number-mode to toggle this mode.

Emacs can optionally display the time and system load in all mode lines. To enable this feature, type M-x display-time. The information added to the mode line usually appears after the buffer name, before the mode names and their parentheses. It looks like this:

hh:mmpm l.ll

Here hh and mm are the hour and minute, followed always by `am' or `pm'. l.ll is the average number of running processes in the whole system recently. (Some fields may be missing if your operating system cannot support them.) If you prefer time display in 24-hour format, set the variable display-time-24hr-format to t.

The word `Mail' appears after the load level if there is mail for you that you have not read yet.

How Text Is Displayed

ASCII printing characters (octal codes 040 through 0176) in Emacs buffers are displayed with their graphics. So are non-ASCII multibyte printing characters (octal codes above 0400).

Some ASCII control characters are displayed in special ways. The newline character (octal code 012) is displayed by starting a new line. The tab character (octal code 011) is displayed by moving to the next tab stop column (normally every 8 columns).

Other ASCII control characters are normally displayed as a caret (`^') followed by the non-control version of the character; thus, control-A is displayed as `^A'.

Non-ASCII characters 0200 through 0377 are displayed with octal escape sequences; thus, character code 0243 (octal) is displayed as `\243'. However, if you enable European display, most of these characters become non-ASCII printing characters, and are displayed using their graphics (assuming your terminal supports them). See section Single-byte European Character Support.

Variables Controlling Display

This section contains information for customization only. Beginning users should skip it.

The variable mode-line-inverse-video controls whether the mode line is displayed in inverse video (assuming the terminal supports it); nil means don't do so. See section The Mode Line. If you specify the foreground color for the modeline face, and mode-line-inverse-video is non-nil, then the default background color for that face is the usual foreground color. See section Using Multiple Typefaces.

If the variable inverse-video is non-nil, Emacs attempts to invert all the lines of the display from what they normally are.

If the variable visible-bell is non-nil, Emacs attempts to make the whole screen blink when it would normally make an audible bell sound. This variable has no effect if your terminal does not have a way to make the screen blink.

When you reenter Emacs after suspending, Emacs normally clears the screen and redraws the entire display. On some terminals with more than one page of memory, it is possible to arrange the termcap entry so that the `ti' and `te' strings (output to the terminal when Emacs is entered and exited, respectively) switch between pages of memory so as to use one page for Emacs and another page for other output. Then you might want to set the variable no-redraw-on-reenter non-nil; this tells Emacs to assume, when resumed, that the screen page it is using still contains what Emacs last wrote there.

The variable echo-keystrokes controls the echoing of multi-character keys; its value is the number of seconds of pause required to cause echoing to start, or zero meaning don't echo at all. See section The Echo Area.

If the variable ctl-arrow is nil, control characters in the buffer are displayed with octal escape sequences, except for newline and tab. Altering the value of ctl-arrow makes it local to the current buffer; until that time, the default value is in effect. The default is initially t. See section `Display Tables' in The Emacs Lisp Reference Manual.

Normally, a tab character in the buffer is displayed as whitespace which extends to the next display tab stop position, and display tab stops come at intervals equal to eight spaces. The number of spaces per tab is controlled by the variable tab-width, which is made local by changing it, just like ctl-arrow. Note that how the tab character in the buffer is displayed has nothing to do with the definition of TAB as a command. The variable tab-width must have an integer value between 1 and 1000, inclusive.

If the variable truncate-lines is non-nil, then each line of text gets just one screen line for display; if the text line is too long, display shows only the part that fits. If truncate-lines is nil, then long text lines display as more than one screen line, enough to show the whole text of the line. See section Continuation Lines. Altering the value of truncate-lines makes it local to the current buffer; until that time, the default value is in effect. The default is initially nil.

If the variable truncate-partial-width-windows is non-nil, it forces truncation rather than continuation in any window less than the full width of the screen or frame, regardless of the value of truncate-lines. For information about side-by-side windows, see section Splitting Windows. See also section `Display' in The Emacs Lisp Reference Manual.

The variable baud-rate holds the output speed of the terminal, as far as Emacs knows. Setting this variable does not change the speed of actual data transmission, but the value is used for calculations such as padding. It also affects decisions about whether to scroll part of the screen or redraw it instead--even when using a window system. (We designed it this way, despite the fact that a window system has no true "output speed," to give you a way to tune these decisions.)

You can customize the way any particular character code is displayed by means of a display table. See section `Display Tables' in The Emacs Lisp Reference Manual.

Searching and Replacement

Like other editors, Emacs has commands for searching for occurrences of a string. The principal search command is unusual in that it is incremental; it begins to search before you have finished typing the search string. There are also nonincremental search commands more like those of other editors.

Besides the usual replace-string command that finds all occurrences of one string and replaces them with another, Emacs has a fancy replacement command called query-replace which asks interactively which occurrences to replace.

Incremental Search

An incremental search begins searching as soon as you type the first character of the search string. As you type in the search string, Emacs shows you where the string (as you have typed it so far) would be found. When you have typed enough characters to identify the place you want, you can stop. Depending on what you plan to do next, you may or may not need to terminate the search explicitly with RET.

C-s
Incremental search forward (isearch-forward).
C-r
Incremental search backward (isearch-backward).

C-s starts an incremental search. C-s reads characters from the keyboard and positions the cursor at the first occurrence of the characters that you have typed. If you type C-s and then F, the cursor moves right after the first `F'. Type an O, and see the cursor move to after the first `FO'. After another O, the cursor is after the first `FOO' after the place where you started the search. At each step, the buffer text that matches the search string is highlighted, if the terminal can do that; at each step, the current search string is updated in the echo area.

If you make a mistake in typing the search string, you can cancel characters with DEL. Each DEL cancels the last character of search string. This does not happen until Emacs is ready to read another input character; first it must either find, or fail to find, the character you want to erase. If you do not want to wait for this to happen, use C-g as described below.

When you are satisfied with the place you have reached, you can type RET, which stops searching, leaving the cursor where the search brought it. Also, any command not specially meaningful in searches stops the searching and is then executed. Thus, typing C-a would exit the search and then move to the beginning of the line. RET is necessary only if the next command you want to type is a printing character, DEL, RET, or another control character that is special within searches (C-q, C-w, C-r, C-s, C-y, M-y, M-r, or M-s).

Sometimes you search for `FOO' and find it, but not the one you expected to find. There was a second `FOO' that you forgot about, before the one you were aiming for. In this event, type another C-s to move to the next occurrence of the search string. This can be done any number of times. If you overshoot, you can cancel some C-s characters with DEL.

After you exit a search, you can search for the same string again by typing just C-s C-s: the first C-s is the key that invokes incremental search, and the second C-s means "search again."

To reuse earlier search strings, use the search ring. The commands M-p and M-n move through the ring to pick a search string to reuse. These commands leave the selected search ring element in the minibuffer, where you can edit it. Type C-s or C-r to terminate editing the string and search for it.

If your string is not found at all, the echo area says `Failing I-Search'. The cursor is after the place where Emacs found as much of your string as it could. Thus, if you search for `FOOT', and there is no `FOOT', you might see the cursor after the `FOO' in `FOOL'. At this point there are several things you can do. If your string was mistyped, you can rub some of it out and correct it. If you like the place you have found, you can type RET or some other Emacs command to "accept what the search offered." Or you can type C-g, which removes from the search string the characters that could not be found (the `T' in `FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second C-g at that point cancels the search entirely, returning point to where it was when the search started.

An upper-case letter in the search string makes the search case-sensitive. If you delete the upper-case character from the search string, it ceases to have this effect. See section Searching and Case.

If a search is failing and you ask to repeat it by typing another C-s, it starts again from the beginning of the buffer. Repeating a failing reverse search with C-r starts again from the end. This is called wrapping around. `Wrapped' appears in the search prompt once this has happened. If you keep on going past the original starting point of the search, it changes to `Overwrapped', which means that you are revisiting matches that you have already seen.

The C-g "quit" character does special things during searches; just what it does depends on the status of the search. If the search has found what you specified and is waiting for input, C-g cancels the entire search. The cursor moves back to where you started the search. If C-g is typed when there are characters in the search string that have not been found--because Emacs is still searching for them, or because it has failed to find them--then the search string characters which have not been found are discarded from the search string. With them gone, the search is now successful and waiting for more input, so a second C-g will cancel the entire search.

To search for a newline, type C-j. To search for another control character, such as control-S or carriage return, you must quote it by typing C-q first. This function of C-q is analogous to its use for insertion (see section Inserting Text): it causes the following character to be treated the way any "ordinary" character is treated in the same context. You can also specify a character by its octal code: enter C-q followed by a sequence of octal digits.

You can change to searching backwards with C-r. If a search fails because the place you started was too late in the file, you should do this. Repeated C-r keeps looking for more occurrences backwards. A C-s starts going forwards again. C-r in a search can be canceled with DEL.

If you know initially that you want to search backwards, you can use C-r instead of C-s to start the search, because C-r as a key runs a command (isearch-backward) to search backward. A backward search finds matches that are entirely before the starting point, just as a forward search finds matches that begin after it.

The characters C-y and C-w can be used in incremental search to grab text from the buffer into the search string. This makes it convenient to search for another occurrence of text at point. C-w copies the word after point as part of the search string, advancing point over that word. Another C-s to repeat the search will then search for a string including that word. C-y is similar to C-w but copies all the rest of the current line into the search string. Both C-y and C-w convert the text they copy to lower case if the search is currently not case-sensitive; this is so the search remains case-insensitive.

The character M-y copies text from the kill ring into the search string. It uses the same text that C-y as a command would yank. See section Yanking.

When you exit the incremental search, it sets the mark to where point was, before the search. That is convenient for moving back there. In Transient Mark mode, incremental search sets the mark without activating it, and does so only if the mark is not already active.

To customize the special characters that incremental search understands, alter their bindings in the keymap isearch-mode-map. For a list of bindings, look at the documentation of isearch-mode with C-h f isearch-mode RET.

Slow Terminal Incremental Search

Incremental search on a slow terminal uses a modified style of display that is designed to take less time. Instead of redisplaying the buffer at each place the search gets to, it creates a new single-line window and uses that to display the line that the search has found. The single-line window comes into play as soon as point gets outside of the text that is already on the screen.

When you terminate the search, the single-line window is removed. Then Emacs redisplays the window in which the search was done, to show its new position of point.

The slow terminal style of display is used when the terminal baud rate is less than or equal to the value of the variable search-slow-speed, initially 1200.

The number of lines to use in slow terminal search display is controlled by the variable search-slow-window-lines. Its normal value is 1.

Nonincremental Search

Emacs also has conventional nonincremental search commands, which require you to type the entire search string before searching begins.

C-s RET string RET
Search for string.
C-r RET string RET
Search backward for string.

To do a nonincremental search, first type C-s RET. This enters the minibuffer to read the search string; terminate the string with RET, and then the search takes place. If the string is not found, the search command gets an error.

The way C-s RET works is that the C-s invokes incremental search, which is specially programmed to invoke nonincremental search if the argument you give it is empty. (Such an empty argument would otherwise be useless.) C-r RET also works this way.

However, nonincremental searches performed using C-s RET do not call search-forward right away. The first thing done is to see if the next character is C-w, which requests a word search.

Forward and backward nonincremental searches are implemented by the commands search-forward and search-backward. These commands may be bound to keys in the usual manner. The feature that you can get to them via the incremental search commands exists for historical reasons, and to avoid the need to find suitable key sequences for them.

Word Search

Word search searches for a sequence of words without regard to how the words are separated. More precisely, you type a string of many words, using single spaces to separate them, and the string can be found even if there are multiple spaces, newlines or other punctuation between the words.

Word search is useful for editing a printed document made with a text formatter. If you edit while looking at the printed, formatted version, you can't tell where the line breaks are in the source file. With word search, you can search without having to know them.

C-s RET C-w words RET
Search for words, ignoring details of punctuation.
C-r RET C-w words RET
Search backward for words, ignoring details of punctuation.

Word search is a special case of nonincremental search and is invoked with C-s RET C-w. This is followed by the search string, which must always be terminated with RET. Being nonincremental, this search does not start until the argument is terminated. It works by constructing a regular expression and searching for that; see section Regular Expression Search.

Use C-r RET C-w to do backward word search.

Forward and backward word searches are implemented by the commands word-search-forward and word-search-backward. These commands may be bound to keys in the usual manner. The feature that you can get to them via the incremental search commands exists for historical reasons, and to avoid the need to find suitable key sequences for them.

Regular Expression Search

A regular expression (regexp, for short) is a pattern that denotes a class of alternative strings to match, possibly infinitely many. In GNU Emacs, you can search for the next match for a regexp either incrementally or not.

Incremental search for a regexp is done by typing C-M-s (isearch-forward-regexp). This command reads a search string incrementally just like C-s, but it treats the search string as a regexp rather than looking for an exact match against the text in the buffer. Each time you add text to the search string, you make the regexp longer, and the new regexp is searched for. Invoking C-s with a prefix argument (its value does not matter) is another way to do a forward incremental regexp search. To search backward for a regexp, use C-M-r (isearch-backward-regexp), or C-r with a prefix argument.

All of the control characters that do special things within an ordinary incremental search have the same function in incremental regexp search. Typing C-s or C-r immediately after starting the search retrieves the last incremental search regexp used; that is to say, incremental regexp and non-regexp searches have independent defaults. They also have separate search rings that you can access with M-p and M-n.

If you type SPC in incremental regexp search, it matches any sequence of whitespace characters, including newlines. If you want to match just a space, type C-q SPC.

Note that adding characters to the regexp in an incremental regexp search can make the cursor move back and start again. For example, if you have searched for `foo' and you add `\|bar', the cursor backs up in case the first `bar' precedes the first `foo'.

Nonincremental search for a regexp is done by the functions re-search-forward and re-search-backward. You can invoke these with M-x, or bind them to keys, or invoke them by way of incremental regexp search with C-M-s RET and C-M-r RET.

If you use the incremental regexp search commands with a prefix argument, they perform ordinary string search, like isearch-forward and isearch-backward. See section Incremental Search.

Syntax of Regular Expressions

Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character is a simple regular expression which matches that same character and nothing else. The special characters are `$', `^', `.', `*', `+', `?', `[', `]' and `\'. Any other character appearing in a regular expression is ordinary, unless a `\' precedes it.

For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does not match the string `ff'.) Likewise, `o' is a regular expression that matches only `o'. (When case distinctions are being ignored, these regexps also match `F' and `O', but we consider this a generalization of "the same string," rather than an exception.)

Any two regular expressions a and b can be concatenated. The result is a regular expression which matches a string if a matches some amount of the beginning of that string and b matches the rest of the string.

As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial. To do something nontrivial, you need to use one of the special characters. Here is a list of them.

. (Period)
is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like `a.b', which matches any three-character string that begins with `a' and ends with `b'.
*
is not a construct by itself; it is a postfix operator that means to match the preceding regular expression repetitively as many times as possible. Thus, `o*' matches any number of `o's (including no `o's). `*' always applies to the smallest possible preceding expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. It matches `f', `fo', `foo', and so on. The matcher processes a `*' construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the `*'-modified construct in case that makes it possible to match the rest of the pattern. For example, in matching `ca*ar' against the string `caaar', the `a*' first tries to match all three `a's; but the rest of the pattern is `ar' and there is only `r' left to match, so this try fails. The next alternative is for `a*' to match only two `a's. With this choice, the rest of the regexp matches successfully.
+
is a postfix operator, similar to `*' except that it must match the preceding expression at least once. So, for example, `ca+r' matches the strings `car' and `caaaar' but not the string `cr', whereas `ca*r' matches all three strings.
?
is a postfix operator, similar to `*' except that it can match the preceding expression either once or not at all. For example, `ca?r' matches `car' or `cr'; nothing else.
[ ... ]
is a character set, which begins with `[' and is terminated by `]'. In the simplest case, the characters between the two brackets are what this set can match. Thus, `[ad]' matches either one `a' or one `d', and `[ad]*' matches any string composed of just `a's and `d's (including the empty string), from which it follows that `c[ad]*r' matches `cr', `car', `cdr', `caddaar', etc. You can also include character ranges in a character set, by writing the starting and ending characters with a `-' between them. Thus, `[a-z]' matches any lower-case ASCII letter. Ranges may be intermixed freely with individual characters, as in `[a-z$%.]', which matches any lower-case ASCII letter or `$', `%' or period. Note that the usual regexp special characters are not special inside a character set. A completely different set of special characters exists inside character sets: `]', `-' and `^'. To include a `]' in a character set, you must make it the first character. For example, `[]a]' matches `]' or `a'. To include a `-', write `-' as the first or last character of the set, or put it after a range. Thus, `[]-]' matches both `]' and `-'. To include `^' in a set, put it anywhere but at the beginning of the set. When you use a range in case-insensitive search, you should write both ends of the range in upper case, or both in lower case, or both should be non-letters. The behavior of a mixed-case range such as `A-z' is somewhat ill-defined, and it may change in future Emacs versions.
[^ ... ]
`[^' begins a complemented character set, which matches any character except the ones specified. Thus, `[^a-z0-9A-Z]' matches all characters except letters and digits. `^' is not special in a character set unless it is the first character. The character following the `^' is treated as if it were first (in other words, `-' and `]' are not special there). A complemented character set can match a newline, unless newline is mentioned as one of the characters not to match. This is in contrast to the handling of regexps in programs such as grep.
^
is a special character that matches the empty string, but only at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, `^foo' matches a `foo' that occurs at the beginning of a line.
$
is similar to `^' but matches only at the end of a line. Thus, `x+$' matches a string of one `x' or more at the end of a line.
\
has two functions: it quotes the special characters (including `\'), and it introduces additional special constructs. Because `\' quotes special characters, `\$' is a regular expression that matches only `$', and `\[' is a regular expression that matches only `[', and so on.

Note: for historical compatibility, special characters are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, `*foo' treats `*' as ordinary since there is no preceding expression on which the `*' can act. It is poor practice to depend on this behavior; it is better to quote the special character anyway, regardless of where it appears.

For the most part, `\' followed by any character matches only that character. However, there are several exceptions: two-character sequences starting with `\' that have special meanings. The second character in the sequence is always an ordinary character when used on its own. Here is a table of `\' constructs.

\|
specifies an alternative. Two regular expressions a and b with `\|' in between form an expression that matches some text if either a matches it or b matches it. It works by trying to match a, and if that fails, by trying to match b. Thus, `foo\|bar' matches either `foo' or `bar' but no other string. `\|' applies to the largest possible surrounding expressions. Only a surrounding `\( ... \)' grouping can limit the grouping power of `\|'. Full backtracking capability exists to handle multiple uses of `\|'.
\( ... \)
is a grouping construct that serves three purposes:
  1. To enclose a set of `\|' alternatives for other operations. Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
  2. To enclose a complicated expression for the postfix operators `*', `+' and `?' to operate on. Thus, `ba\(na\)*' matches `bananana', etc., with any (zero or more) number of `na' strings.
  3. To record a matched substring for future reference.
This last application is not a consequence of the idea of a parenthetical grouping; it is a separate feature that is assigned as a second meaning to the same `\( ... \)' construct. In practice there is no conflict between the two meanings.
\d
matches the same text that matched the dth occurrence of a `\( ... \)' construct. After the end of a `\( ... \)' construct, the matcher remembers the beginning and end of the text matched by that construct. Then, later on in the regular expression, you can use `\' followed by the digit d to mean "match the same text matched the dth time by the `\( ... \)' construct." The strings matching the first nine `\( ... \)' constructs appearing in a regular expression are assigned numbers 1 through 9 in the order that the open-parentheses appear in the regular expression. So you can use `\1' through `\9' to refer to the text matched by the corresponding `\( ... \)' constructs. For example, `\(.*\)\1' matches any newline-free string that is composed of two identical halves. The `\(.*\)' matches the first half, which may be anything, but the `\1' that follows must match the same exact text. If a particular `\( ... \)' construct matches more than once (which can easily happen if it is followed by `*'), only the last match is recorded.
\`
matches the empty string, but only at the beginning of the buffer or string being matched against.
\'
matches the empty string, but only at the end of the buffer or string being matched against.
\=
matches the empty string, but only at point.
\b
matches the empty string, but only at the beginning or end of a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a separate word. `\bballs?\b' matches `ball' or `balls' as a separate word. `\b' matches at the beginning or end of the buffer regardless of what text appears next to it.
\B
matches the empty string, but not at the beginning or end of a word.
\<
matches the empty string, but only at the beginning of a word. `\<' matches at the beginning of the buffer only if a word-constituent character follows.
\>
matches the empty string, but only at the end of a word. `\>' matches at the end of the buffer only if the contents end with a word-constituent character.
\w
matches any word-constituent character. The syntax table determines which characters these are. See section The Syntax Table.
\W
matches any character that is not a word-constituent.
\sc
matches any character whose syntax is c. Here c is a character that represents a syntax code: thus, `w' for word constituent, `-' for whitespace, `(' for open parenthesis, etc. Represent a character of whitespace (which can be a newline) by either `-' or a space character.
\Sc
matches any character whose syntax is not c.

The constructs that pertain to words and syntax are controlled by the setting of the syntax table (see section The Syntax Table).

Here is a complicated regexp, used by Emacs to recognize the end of a sentence together with any whitespace that follows. It is given in Lisp syntax to enable you to distinguish the spaces from the tab characters. In Lisp syntax, the string constant begins and ends with a double-quote. `\"' stands for a double-quote as part of the regexp, `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for a newline.

"[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"

This contains four parts in succession: a character set matching period, `?', or `!'; a character set matching close-brackets, quotes, or parentheses, repeated any number of times; an alternative in backslash-parentheses that matches end-of-line, a tab, or two spaces; and a character set matching whitespace characters, repeated any number of times.

To enter the same regexp interactively, you would type TAB to enter a tab, and C-j to enter a newline. You would also type single backslashes as themselves, instead of doubling them for Lisp syntax.

Searching and Case

Incremental searches in Emacs normally ignore the case of the text they are searching through, if you specify the text in lower case. Thus, if you specify searching for `foo', then `Foo' and `foo' are also considered a match. Regexps, and in particular character sets, are included: `[ab]' would match `a' or `A' or `b' or `B'.

An upper-case letter anywhere in the incremental search string makes the search case-sensitive. Thus, searching for `Foo' does not find `foo' or `FOO'. This applies to regular expression search as well as to string search. The effect ceases if you delete the upper-case letter from the search string.

If you set the variable case-fold-search to nil, then all letters must match exactly, including case. This is a per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. See section Local Variables. This variable applies to nonincremental searches also, including those performed by the replace commands (see section Replacement Commands) and the minibuffer history matching commands (see section Minibuffer History).

Replacement Commands

Global search-and-replace operations are not needed as often in Emacs as they are in other editors(2), but they are available. In addition to the simple M-x replace-string command which is like that found in most editors, there is a M-x query-replace command which asks you, for each occurrence of the pattern, whether to replace it.

The replace commands normally operate on the text from point to the end of the buffer; however, in Transient Mark mode, when the mark is active, they operate on the region. The replace commands all replace one string (or regexp) with one replacement string. It is possible to perform several replacements in parallel using the command expand-region-abbrevs (see section Controlling Abbrev Expansion).

Unconditional Replacement

M-x replace-string RET string RET newstring RET
Replace every occurrence of string with newstring.
M-x replace-regexp RET regexp RET newstring RET
Replace every match for regexp with newstring.

To replace every instance of `foo' after point with `bar', use the command M-x replace-string with the two arguments `foo' and `bar'. Replacement happens only in the text after point, so if you want to cover the whole buffer you must go to the beginning first. All occurrences up to the end of the buffer are replaced; to limit replacement to part of the buffer, narrow to that part of the buffer before doing the replacement (see section Narrowing). In Transient Mark mode, when the region is active, replacement is limited to the region (see section Transient Mark Mode).

When replace-string exits, it leaves point at the last occurrence replaced. It sets the mark to the prior position of point (where the replace-string command was issued); use C-u C-SPC to move back there.

A numeric argument restricts replacement to matches that are surrounded by word boundaries. The argument's value doesn't matter.

Regexp Replacement

The M-x replace-string command replaces exact matches for a single string. The similar command M-x replace-regexp replaces any match for a specified pattern.

In replace-regexp, the newstring need not be constant: it can refer to all or part of what is matched by the regexp. `\&' in newstring stands for the entire match being replaced. `\d' in newstring, where d is a digit, stands for whatever matched the dth parenthesized grouping in regexp. To include a `\' in the text to replace with, you must enter `\\'. For example,

M-x replace-regexp RET c[ad]+r RET \&-safe RET

replaces (for example) `cadr' with `cadr-safe' and `cddr' with `cddr-safe'.

M-x replace-regexp RET \(c[ad]+r\)-safe RET \1 RET

performs the inverse transformation.

Replace Commands and Case

If the first argument of a replace command is all lower case, the commands ignores case while searching for occurrences to replace--provided case-fold-search is non-nil. If case-fold-search is set to nil, case is always significant in all searches.

In addition, when the newstring argument is all or partly lower case, replacement commands try to preserve the case pattern of each occurrence. Thus, the command

M-x replace-string RET foo RET bar RET

replaces a lower case `foo' with a lower case `bar', an all-caps `FOO' with `BAR', and a capitalized `Foo' with `Bar'. (These three alternatives--lower case, all caps, and capitalized, are the only ones that replace-string can distinguish.)

If upper-case letters are used in the replacement string, they remain upper case every time that text is inserted. If upper-case letters are used in the first argument, the second argument is always substituted exactly as given, with no case conversion. Likewise, if either case-replace or case-fold-search is set to nil, replacement is done without case conversion.

Query Replace

M-% string RET newstring RET
M-x query-replace RET string RET newstring RET
Replace some occurrences of string with newstring.
C-M-% regexp RET newstring RET
M-x query-replace-regexp RET regexp RET newstring RET
Replace some matches for regexp with newstring.

If you want to change only some of the occurrences of `foo' to `bar', not all of them, then you cannot use an ordinary replace-string. Instead, use M-% (query-replace). This command finds occurrences of `foo' one by one, displays each occurrence and asks you whether to replace it. A numeric argument to query-replace tells it to consider only occurrences that are bounded by word-delimiter characters. This preserves case, just like replace-string, provided case-replace is non-nil, as it normally is.

Aside from querying, query-replace works just like replace-string, and query-replace-regexp works just like replace-regexp. This command is run by C-M-%.

The things you can type when you are shown an occurrence of string or a match for regexp are:

SPC
to replace the occurrence with newstring.
DEL
to skip to the next occurrence without replacing this one.
, (Comma)
to replace this occurrence and display the result. You are then asked for another input character to say what to do next. Since the replacement has already been made, DEL and SPC are equivalent in this situation; both move to the next occurrence. You can type C-r at this point (see below) to alter the replaced text. You can also type C-x u to undo the replacement; this exits the query-replace, so if you want to do further replacement you must use C-x ESC ESC RET to restart (see section Repeating Minibuffer Commands).
RET
to exit without doing any more replacements.
. (Period)
to replace this occurrence and then exit without searching for more occurrences.
!
to replace all remaining occurrences without asking again.
^
to go back to the position of the previous occurrence (or what used to be an occurrence), in case you changed it by mistake. This works by popping the mark ring. Only one ^ in a row is meaningful, because only one previous replacement position is kept during query-replace.
C-r
to enter a recursive editing level, in case the occurrence needs to be edited rather than just replaced with newstring. When you are done, exit the recursive editing level with C-M-c to proceed to the next occurrence. See section Recursive Editing Levels.
C-w
to delete the occurrence, and then enter a recursive editing level as in C-r. Use the recursive edit to insert text to replace the deleted occurrence of string. When done, exit the recursive editing level with C-M-c to proceed to the next occurrence.
C-l
to redisplay the screen. Then you must type another character to specify what to do with this occurrence.
C-h
to display a message summarizing these options. Then you must type another character to specify what to do with this occurrence.

Some other characters are aliases for the ones listed above: y, n and q are equivalent to SPC, DEL and RET.

Aside from this, any other character exits the query-replace, and is then reread as part of a key sequence. Thus, if you type C-k, it exits the query-replace and then kills to end of line.

To restart a query-replace once it is exited, use C-x ESC ESC, which repeats the query-replace because it used the minibuffer to read its arguments. See section Repeating Minibuffer Commands.

See also section Transforming File Names in Dired, for Dired commands to rename, copy, or link files by replacing regexp matches in file names.

Other Search-and-Loop Commands

Here are some other commands that find matches for a regular expression. They all operate from point to the end of the buffer, and all ignore case in matching, if the pattern contains no upper-case letters and case-fold-search is non-nil.

M-x occur RET regexp RET
Display a list showing each line in the buffer that contains a match for regexp. A numeric argument specifies the number of context lines to print before and after each matching line; the default is none. To limit the search to part of the buffer, narrow to that part (see section Narrowing). The buffer `*Occur*' containing the output serves as a menu for finding the occurrences in their original context. Click Mouse-2 on an occurrence listed in `*Occur*', or position point there and type RET; this switches to the buffer that was searched and moves point to the original of the chosen occurrence.
M-x list-matching-lines
Synonym for M-x occur.
M-x count-matches RET regexp RET
Print the number of matches for regexp after point.
M-x flush-lines RET regexp RET
Delete each line that follows point and contains a match for regexp.
M-x keep-lines RET regexp RET
Delete each line that follows point and does not contain a match for regexp.

In addition, you can use grep from Emacs to search a collection of files for matches for a regular expression, then visit the matches either sequentially or in arbitrary order. See section Searching with Grep under Emacs.

Commands for Fixing Typos

In this chapter we describe the commands that are especially useful for the times when you catch a mistake in your text just after you have made it, or change your mind while composing text on the fly.

The most fundamental command for correcting erroneous editing is the undo command, C-x u or C-_. This command undoes a single command (usually), a part of a command (in the case of query-replace), or several consecutive self-inserting characters. Consecutive repetitions of C-_ or C-x u undo earlier and earlier changes, back to the limit of the undo information available. See section Undoing Changes, for for more information.

Killing Your Mistakes

DEL
Delete last character (delete-backward-char).
M-DEL
Kill last word (backward-kill-word).
C-x DEL
Kill to beginning of sentence (backward-kill-sentence).

The DEL character (delete-backward-char) is the most important correction command. It deletes the character before point. When DEL follows a self-inserting character command, you can think of it as canceling that command. However, avoid the mistake of thinking of DEL as a general way to cancel a command!

When your mistake is longer than a couple of characters, it might be more convenient to use M-DEL or C-x DEL. M-DEL kills back to the start of the last word, and C-x DEL kills back to the start of the last sentence. C-x DEL is particularly useful when you change your mind about the phrasing of the text you are writing. M-DEL and C-x DEL save the killed text for C-y and M-y to retrieve. See section Yanking.

M-DEL is often useful even when you have typed only a few characters wrong, if you know you are confused in your typing and aren't sure exactly what you typed. At such a time, you cannot correct with DEL except by looking at the screen to see what you did. Often it requires less thought to kill the whole word and start again.

Transposing Text

C-t
Transpose two characters (transpose-chars).
M-t
Transpose two words (transpose-words).
C-M-t
Transpose two balanced expressions (transpose-sexps).
C-x C-t
Transpose two lines (transpose-lines).

The common error of transposing two characters can be fixed, when they are adjacent, with the C-t command (transpose-chars). Normally, C-t transposes the two characters on either side of point. When given at the end of a line, rather than transposing the last character of the line with the newline, which would be useless, C-t transposes the last two characters on the line. So, if you catch your transposition error right away, you can fix it with just a C-t. If you don't catch it so fast, you must move the cursor back to between the two transposed characters. If you transposed a space with the last character of the word before it, the word motion commands are a good way of getting there. Otherwise, a reverse search (C-r) is often the best way. See section Searching and Replacement.

M-t (transpose-words) transposes the word before point with the word after point. It moves point forward over a word, dragging the word preceding or containing point forward as well. The punctuation characters between the words do not move. For example, `FOO, BAR' transposes into `BAR, FOO' rather than `BAR FOO,'.

C-M-t (transpose-sexps) is a similar command for transposing two expressions (see section Lists and Sexps), and C-x C-t (transpose-lines) exchanges lines. They work like M-t except in determining the division of the text into syntactic units.

A numeric argument to a transpose command serves as a repeat count: it tells the transpose command to move the character (word, sexp, line) before or containing point across several other characters (words, sexps, lines). For example, C-u 3 C-t moves the character before point forward across three other characters. It would change `f-!-oobar' into `oobf-!-ar'. This is equivalent to repeating C-t three times. C-u - 4 M-t moves the word before point backward across four words. C-u - C-M-t would cancel the effect of plain C-M-t.

A numeric argument of zero is assigned a special meaning (because otherwise a command with a repeat count of zero would do nothing): to transpose the character (word, sexp, line) ending after point with the one ending after the mark.

Case Conversion

M-- M-l
Convert last word to lower case. Note Meta-- is Meta-minus.
M-- M-u
Convert last word to all upper case.
M-- M-c
Convert last word to lower case with capital initial.

A very common error is to type words in the wrong case. Because of this, the word case-conversion commands M-l, M-u and M-c have a special feature when used with a negative argument: they do not move the cursor. As soon as you see you have mistyped the last word, you can simply case-convert it and go on typing. See section Case Conversion Commands.

Checking and Correcting Spelling

This section describes the commands to check the spelling of a single word or of a portion of a buffer. These commands work with the spelling checker program Ispell, which is not part of Emacs.

M-x flyspell-mode
Enable Flyspell mode, which highlights all misspelled words.
M-$
Check and correct spelling of the word at point (ispell-word).
M-TAB
Complete the word before point based on the spelling dictionary (ispell-complete-word).
M-x ispell-buffer
Check and correct spelling of each word in the buffer.
M-x ispell-region
Check and correct spelling of each word in the region.
M-x ispell-message
Check and correct spelling of each word in a draft mail message, excluding cited material.
M-x ispell-change-dictionary RET dict RET
Restart the Ispell process, using dict as the dictionary.
M-x ispell-kill-ispell
Kill the Ispell subprocess.

Flyspell mode is a fully-automatic way to check spelling as you edit in Emacs. It operates by checking words as you change or insert them. When it finds a word that it does not recognize, it highlights that word. This does not interfere with your editing, but when you see the highlighted word, you can move to it and fix it. Type M-x flyspell-mode to enable or disable this mode in the current buffer.

When Flyspell mode highlights a word as misspelled, you can click on it with Mouse-2 to display a menu of possible corrections and actions. You can also correct the word by editing it manually in any way you like.

The other Emacs spell-checking features check or look up words when you give an explicit command to do so. Checking all or part of the buffer is useful when you have text that was written outside of this Emacs session and might contain any number of misspellings.

To check the spelling of the word around or next to point, and optionally correct it as well, use the command M-$ (ispell-word). If the word is not correct, the command offers you various alternatives for what to do about it.

To check the entire current buffer, use M-x ispell-buffer. Use M-x ispell-region to check just the current region. To check spelling in an email message you are writing, use M-x ispell-message; that checks the whole buffer, but does not check material that is indented or appears to be cited from other messages.

Each time these commands encounter an incorrect word, they ask you what to do. They display a list of alternatives, usually including several "near-misses"---words that are close to the word being checked. Then you must type a character. Here are the valid responses:

SPC
Skip this word--continue to consider it incorrect, but don't change it here.
r new RET
Replace the word (just this time) with new.
R new RET
Replace the word with new, and do a query-replace so you can replace it elsewhere in the buffer if you wish.
digit
Replace the word (just this time) with one of the displayed near-misses. Each near-miss is listed with a digit; type that digit to select it.
a
Accept the incorrect word--treat it as correct, but only in this editing session.
A
Accept the incorrect word--treat it as correct, but only in this editing session and for this buffer.
i
Insert this word in your private dictionary file so that Ispell will consider it correct it from now on, even in future sessions.
u
Insert the lower-case version of this word in your private dictionary file.
m
Like i, but you can also specify dictionary completion information.
l word RET
Look in the dictionary for words that match word. These words become the new list of "near-misses"; you can select one of them to replace with by typing a digit. You can use `*' in word as a wildcard.
C-g
Quit interactive spell checking. You can restart it again afterward with C-u M-$.
X
Same as C-g.
x
Quit interactive spell checking and move point back to where it was when you started spell checking.
q
Quit interactive spell checking and kill the Ispell subprocess.
C-l
Refresh the screen.
C-z
This key has its normal command meaning (suspend Emacs or iconify this frame).

The command ispell-complete-word, which is bound to the key M-TAB in Text mode and related modes, shows a list of completions based on spelling correction. Insert the beginning of a word, and then type M-TAB; the command displays a completion list window. To choose one of the completions listed, click Mouse-2 on it, or move the cursor there in the completions window and type RET. See section Text Mode.

Once started, the Ispell subprocess continues to run (waiting for something to do), so that subsequent spell checking commands complete more quickly. If you want to get rid of the Ispell process, use M-x ispell-kill-ispell. This is not usually necessary, since the process uses no time except when you do spelling correction.

Ispell uses two dictionaries: the standard dictionary and your private dictionary. The variable ispell-dictionary specifies the file name of the standard dictionary to use. A value of nil says to use the default dictionary. The command M-x ispell-change-dictionary sets this variable and then restarts the Ispell subprocess, so that it will use a different dictionary.

File Handling

The operating system stores data permanently in named files. So most of the text you edit with Emacs comes from a file and is ultimately stored in a file.

To edit a file, you must tell Emacs to read the file and prepare a buffer containing a copy of the file's text. This is called visiting the file. Editing commands apply directly to text in the buffer; that is, to the copy inside Emacs. Your changes appear in the file itself only when you save the buffer back into the file.

In addition to visiting and saving files, Emacs can delete, copy, rename, and append to files, keep multiple versions of them, and operate on file directories.

File Names

Most Emacs commands that operate on a file require you to specify the file name. (Saving and reverting are exceptions; the buffer knows which file name to use for them.) You enter the file name using the minibuffer (see section The Minibuffer). Completion is available, to make it easier to specify long file names. See section Completion.

For most operations, there is a default file name which is used if you type just RET to enter an empty argument. Normally the default file name is the name of the file visited in the current buffer; this makes it easy to operate on that file with any of the Emacs file commands.

Each buffer has a default directory, normally the same as the directory of the file visited in that buffer. When you enter a file name without a directory, the default directory is used. If you specify a directory in a relative fashion, with a name that does not start with a slash, it is interpreted with respect to the default directory. The default directory is kept in the variable default-directory, which has a separate value in every buffer.

For example, if the default file name is `/u/rms/gnu/gnu.tasks' then the default directory is `/u/rms/gnu/'. If you type just `foo', which does not specify a directory, it is short for `/u/rms/gnu/foo'. `../.login' would stand for `/u/rms/.login'. `new/foo' would stand for the file name `/u/rms/gnu/new/foo'.

The command M-x pwd prints the current buffer's default directory, and the command M-x cd sets it (to a value read using the minibuffer). A buffer's default directory changes only when the cd command is used. A file-visiting buffer's default directory is initialized to the directory of the file that is visited there. If you create a buffer with C-x b, its default directory is copied from that of the buffer that was current at the time.

The default directory actually appears in the minibuffer when the minibuffer becomes active to read a file name. This serves two purposes: it shows you what the default is, so that you can type a relative file name and know with certainty what it will mean, and it allows you to edit the default to specify a different directory. This insertion of the default directory is inhibited if the variable insert-default-directory is set to nil.

Note that it is legitimate to type an absolute file name after you enter the minibuffer, ignoring the presence of the default directory name as part of the text. The final minibuffer contents may look invalid, but that is not so. For example, if the minibuffer starts out with `/usr/tmp/' and you add `/x1/rms/foo', you get `/usr/tmp//x1/rms/foo'; but Emacs ignores everything through the first slash in the double slash; the result is `/x1/rms/foo'. See section Minibuffers for File Names.

`$' in a file name is used to substitute environment variables. For example, if you have used the shell command `export FOO=rms/hacks' to set up an environment variable named FOO, then you can use `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for `/u/rms/hacks/test.c'. The environment variable name consists of all the alphanumeric characters after the `$'; alternatively, it may be enclosed in braces after the `$'. Note that shell commands to set environment variables affect Emacs only if done before Emacs is started.

To access a file with `$' in its name, type `$$'. This pair is converted to a single `$' at the same time as variable substitution is performed for single `$'. Alternatively, quote the whole file name with `/:' (see section Quoted File Names).

The Lisp function that performs the substitution is called substitute-in-file-name. The substitution is performed only on file names read as such using the minibuffer.

You can include non-ASCII characters in file names if you set the variable file-name-coding-system to a non-nil value. See section Specifying a Coding System.

Visiting Files

C-x C-f
Visit a file (find-file).
C-x C-r
Visit a file for viewing, without allowing changes to it (find-file-read-only).
C-x C-v
Visit a different file instead of the one visited last (find-alternate-file).
C-x 4 f
Visit a file, in another window (find-file-other-window). Don't alter what is displayed in the selected window.
C-x 5 f
Visit a file, in a new frame (find-file-other-frame). Don't alter what is displayed in the selected frame.
M-x find-file-literally
Visit a file with no conversion of the contents.

Visiting a file means copying its contents into an Emacs buffer so you can edit them. Emacs makes a new buffer for each file that you visit. We say that this buffer is visiting the file that it was created to hold. Emacs constructs the buffer name from the file name by throwing away the directory, keeping just the name proper. For example, a file named `/usr/rms/emacs.tex' would get a buffer named `emacs.tex'. If there is already a buffer with that name, a unique name is constructed by appending `<2>', `<3>', or so on, using the lowest number that makes a name that is not already in use.

Each window's mode line shows the name of the buffer that is being displayed in that window, so you can always tell what buffer you are editing.

The changes you make with editing commands are made in the Emacs buffer. They do not take effect in the file that you visited, or any place permanent, until you save the buffer. Saving the buffer means that Emacs writes the current contents of the buffer into its visited file. See section Saving Files.

If a buffer contains changes that have not been saved, we say the buffer is modified. This is important because it implies that some changes will be lost if the buffer is not saved. The mode line displays two stars near the left margin to indicate that the buffer is modified.

To visit a file, use the command C-x C-f (find-file). Follow the command with the name of the file you wish to visit, terminated by a RET.

The file name is read using the minibuffer (see section The Minibuffer), with defaulting and completion in the standard manner (see section File Names). While in the minibuffer, you can abort C-x C-f by typing C-g.

Your confirmation that C-x C-f has completed successfully is the appearance of new text on the screen and a new buffer name in the mode line. If the specified file does not exist and could not be created, or cannot be read, then you get an error, with an error message displayed in the echo area.

If you visit a file that is already in Emacs, C-x C-f does not make another copy. It selects the existing buffer containing that file. However, before doing so, it checks that the file itself has not changed since you visited or saved it last. If the file has changed, a warning message is printed. See section Protection against Simultaneous Editing.

What if you want to create a new file? Just visit it. Emacs prints `(New File)' in the echo area, but in other respects behaves as if you had visited an existing empty file. If you make any changes and save them, the file is created.

Emacs recognizes from the contents of a file which convention it uses to separate lines--newline (used on GNU/Linux and on Unix), carriage-return linefeed (used on Microsoft systems), or just carriage-return (used on the Macintosh)---and automatically converts the contents to the normal Emacs convention, which is that the newline character separates lines. This is a part of the general feature of coding system conversion (see section Coding Systems), and makes it possible to edit files imported from various different operating systems with equal convenience. If you change the text and save the file, Emacs performs the inverse conversion, changing newlines back into carriage-return linefeed or just carriage-return if appropriate.

If the file you specify is actually a directory, C-x C-f invokes Dired, the Emacs directory browser, so that you can "edit" the contents of the directory (see section Dired, the Directory Editor). Dired is a convenient way to delete, look at, or operate on the files in the directory. However, if the variable find-file-run-dired is nil, then it is an error to try to visit a directory.

If the file name you specify contains wildcard characters, Emacs visits all the files that match it. See section Quoted File Names, if you want to visit a file whose name actually contains wildcard characters.

If you visit a file that the operating system won't let you modify, Emacs makes the buffer read-only, so that you won't go ahead and make changes that you'll have trouble saving afterward. You can make the buffer writable with C-x C-q (vc-toggle-read-only). See section Miscellaneous Buffer Operations.

Occasionally you might want to visit a file as read-only in order to protect yourself from entering changes accidentally; do so by visiting the file with the command C-x C-r (find-file-read-only).

If you visit a nonexistent file unintentionally (because you typed the wrong file name), use the C-x C-v command (find-alternate-file) to visit the file you really wanted. C-x C-v is similar to C-x C-f, but it kills the current buffer (after first offering to save it if it is modified). When it reads the file name to visit, it inserts the entire default file name in the buffer, with point just after the directory part; this is convenient if you made a slight error in typing the name.

If you find a file which exists but cannot be read, C-x C-f signals an error.

C-x 4 f (find-file-other-window) is like C-x C-f except that the buffer containing the specified file is selected in another window. The window that was selected before C-x 4 f continues to show the same buffer it was already showing. If this command is used when only one window is being displayed, that window is split in two, with one window showing the same buffer as before, and the other one showing the newly requested file. See section Multiple Windows.

C-x 5 f (find-file-other-frame) is similar, but opens a new frame, or makes visible any existing frame showing the file you seek. This feature is available only when you are using a window system. See section Frames and X Windows.

If you wish to edit a file as a sequence of characters with no special encoding or conversion, use the M-x find-file-literally command. It visits a file, like C-x C-f, but does not do format conversion (see section Editing Formatted Text), character code conversion (see section Coding Systems), or automatic uncompression (see section Accessing Compressed Files). If you already have visited the same file in the usual (non-literal) manner, this command asks you whether to visit it literally instead.

Two special hook variables allow extensions to modify the operation of visiting files. Visiting a file that does not exist runs the functions in the list find-file-not-found-hooks; this variable holds a list of functions, and the functions are called one by one until one of them returns non-nil. Any visiting of a file, whether extant or not, expects find-file-hooks to contain a list of functions and calls them all, one by one. In both cases the functions receive no arguments. Of these two variables, find-file-not-found-hooks takes effect first. These variables are not normal hooks, and their names end in `-hooks' rather than `-hook' to indicate that fact. See section Hooks.

There are several ways to specify automatically the major mode for editing the file (see section How Major Modes are Chosen), and to specify local variables defined for that file (see section Local Variables in Files).

Saving Files

Saving a buffer in Emacs means writing its contents back into the file that was visited in the buffer.

C-x C-s
Save the current buffer in its visited file (save-buffer).
C-x s
Save any or all buffers in their visited files (save-some-buffers).
M-~
Forget that the current buffer has been changed (not-modified).
C-x C-w
Save the current buffer in a specified file (write-file).
M-x set-visited-file-name
Change file the name under which the current buffer will be saved.

When you wish to save the file and make your changes permanent, type C-x C-s (save-buffer). After saving is finished, C-x C-s displays a message like this:

Wrote /u/rms/gnu/gnu.tasks

If the selected buffer is not modified (no changes have been made in it since the buffer was created or last saved), saving is not really done, because it would have no effect. Instead, C-x C-s displays a message like this in the echo area:

(No changes need to be saved)

The command C-x s (save-some-buffers) offers to save any or all modified buffers. It asks you what to do with each buffer. The possible responses are analogous to those of query-replace:

y
Save this buffer and ask about the rest of the buffers.
n
Don't save this buffer, but ask about the rest of the buffers.
!
Save this buffer and all the rest with no more questions.
RET
Terminate save-some-buffers without any more saving.
.
Save this buffer, then exit save-some-buffers without even asking about other buffers.
C-r
View the buffer that you are currently being asked about. When you exit View mode, you get back to save-some-buffers, which asks the question again.
C-h
Display a help message about these options.

C-x C-c, the key sequence to exit Emacs, invokes save-some-buffers and therefore asks the same questions.

If you have changed a buffer but you do not want to save the changes, you should take some action to prevent it. Otherwise, each time you use C-x s or C-x C-c, you are liable to save this buffer by mistake. One thing you can do is type M-~ (not-modified), which clears out the indication that the buffer is modified. If you do this, none of the save commands will believe that the buffer needs to be saved. (`~' is often used as a mathematical symbol for `not'; thus M-~ is `not', metafied.) You could also use set-visited-file-name (see below) to mark the buffer as visiting a different file name, one which is not in use for anything important. Alternatively, you can cancel all the changes made since the file was visited or saved, by reading the text from the file again. This is called reverting. See section Reverting a Buffer. You could also undo all the changes by repeating the undo command C-x u until you have undone all the changes; but reverting is easier.

M-x set-visited-file-name alters the name of the file that the current buffer is visiting. It reads the new file name using the minibuffer. Then it specifies the visited file name and changes the buffer name correspondingly (as long as the new name is not in use). set-visited-file-name does not save the buffer in the newly visited file; it just alters the records inside Emacs in case you do save later. It also marks the buffer as "modified" so that C-x C-s in that buffer will save.

If you wish to mark the buffer as visiting a different file and save it right away, use C-x C-w (write-file). It is precisely equivalent to set-visited-file-name followed by C-x C-s. C-x C-s used on a buffer that is not visiting a file has the same effect as C-x C-w; that is, it reads a file name, marks the buffer as visiting that file, and saves it there. The default file name in a buffer that is not visiting a file is made by combining the buffer name with the buffer's default directory.

If the new file name implies a major mode, then C-x C-w switches to that major mode, in most cases. The command set-visited-file-name also does this. See section How Major Modes are Chosen.

If Emacs is about to save a file and sees that the date of the latest version on disk does not match what Emacs last read or wrote, Emacs notifies you of this fact, because it probably indicates a problem caused by simultaneous editing and requires your immediate attention. See section Protection against Simultaneous Editing.

If the variable require-final-newline is non-nil, Emacs puts a newline at the end of any file that doesn't already end in one, every time a file is saved or written. The default is nil.

Backup Files

On most operating systems, rewriting a file automatically destroys all record of what the file used to contain. Thus, saving a file from Emacs throws away the old contents of the file--or it would, except that Emacs carefully copies the old contents to another file, called the backup file, before actually saving.

For most files, the variable make-backup-files determines whether to make backup files. On most operating systems, its default value is t, so that Emacs does write backup files.

For files managed by a version control system (see section Version Control), the variable vc-make-backup-files determines whether to make backup files. By default, it is nil, since backup files are redundant when you store all the previous versions in a version control system. See section VC Workfile Handling.

The default value of the backup-enable-predicate variable prevents backup files being written for files in `/tmp'.

At your option, Emacs can keep either a single backup file or a series of numbered backup files for each file that you edit.

Emacs makes a backup for a file only the first time the file is saved from one buffer. No matter how many times you save a file, its backup file continues to contain the contents from before the file was visited. Normally this means that the backup file contains the contents from before the current editing session; however, if you kill the buffer and then visit the file again, a new backup file will be made by the next save.

You can also explicitly request making another backup file from a buffer even though it has already been saved at least once. If you save the buffer with C-u C-x C-s, the version thus saved will be made into a backup file if you save the buffer again. C-u C-u C-x C-s saves the buffer, but first makes the previous file contents into a new backup file. C-u C-u C-u C-x C-s does both things: it makes a backup from the previous contents, and arranges to make another from the newly saved contents, if you save again.

Single or Numbered Backups

If you choose to have a single backup file (this is the default), the backup file's name is constructed by appending `~' to the file name being edited; thus, the backup file for `eval.c' would be `eval.c~'.

If you choose to have a series of numbered backup files, backup file names are made by appending `.~', the number, and another `~' to the original file name. Thus, the backup files of `eval.c' would be called `eval.c.~1~', `eval.c.~2~', and so on, through names like `eval.c.~259~' and beyond.

If protection stops you from writing backup files under the usual names, the backup file is written as `%backup%~' in your home directory. Only one such file can exist, so only the most recently made such backup is available.

The choice of single backup or numbered backups is controlled by the variable version-control. Its possible values are

t
Make numbered backups.
nil
Make numbered backups for files that have numbered backups already. Otherwise, make single backups.
never
Do not in any case make numbered backups; always make single backups.

You can set version-control locally in an individual buffer to control the making of backups for that buffer's file. For example, Rmail mode locally sets version-control to never to make sure that there is only one backup for an Rmail file. See section Local Variables.

If you set the environment variable VERSION_CONTROL, to tell various GNU utilities what to do with backup files, Emacs also obeys the environment variable by setting the Lisp variable version-control accordingly at startup. If the environment variable's value is `t' or `numbered', then version-control becomes t; if the value is `nil' or `existing', then version-control becomes nil; if it is `never' or `simple', then version-control becomes never.

Automatic Deletion of Backups

To prevent unlimited consumption of disk space, Emacs can delete numbered backup versions automatically. Generally Emacs keeps the first few backups and the latest few backups, deleting any in between. This happens every time a new backup is made.

The two variables kept-old-versions and kept-new-versions control this deletion. Their values are, respectively the number of oldest (lowest-numbered) backups to keep and the number of newest (highest-numbered) ones to keep, each time a new backup is made. Recall that these values are used just after a new backup version is made; that newly made backup is included in the count in kept-new-versions. By default, both variables are 2.

If delete-old-versions is non-nil, the excess middle versions are deleted without a murmur. If it is nil, the default, then you are asked whether the excess middle versions should really be deleted.

Dired's . (Period) command can also be used to delete old versions. See section Deleting Files with Dired.

Copying vs. Renaming

Backup files can be made by copying the old file or by renaming it. This makes a difference when the old file has multiple names. If the old file is renamed into the backup file, then the alternate names become names for the backup file. If the old file is copied instead, then the alternate names remain names for the file that you are editing, and the contents accessed by those names will be the new contents.

The method of making a backup file may also affect the file's owner and group. If copying is used, these do not change. If renaming is used, you become the file's owner, and the file's group becomes the default (different operating systems have different defaults for the group).

Having the owner change is usually a good idea, because then the owner always shows who last edited the file. Also, the owners of the backups show who produced those versions. Occasionally there is a file whose owner should not change; it is a good idea for such files to contain local variable lists to set backup-by-copying-when-mismatch locally (see section Local Variables in Files).

The choice of renaming or copying is controlled by three variables. Renaming is the default choice. If the variable backup-by-copying is non-nil, copying is used. Otherwise, if the variable backup-by-copying-when-linked is non-nil, then copying is used for files that have multiple names, but renaming may still be used when the file being edited has only one name. If the variable backup-by-copying-when-mismatch is non-nil, then copying is used if renaming would cause the file's owner or group to change. backup-by-copying-when-mismatch is t by default if you start Emacs as the superuser.

When a file is managed with a version control system (see section Version Control), Emacs does not normally make backups in the usual way for that file. But check-in and check-out are similar in some ways to making backups. One unfortunate similarity is that these operations typically break hard links, disconnecting the file name you visited from any alternate names for the same file. This has nothing to do with Emacs--the version control system does it.

Protection against Simultaneous Editing

Simultaneous editing occurs when two users visit the same file, both make changes, and then both save them. If nobody were informed that this was happening, whichever user saved first would later find that his changes were lost.

On some systems, Emacs notices immediately when the second user starts to change the file, and issues an immediate warning. On all systems, Emacs checks when you save the file, and warns if you are about to overwrite another user's changes. You can prevent loss of the other user's work by taking the proper corrective action instead of saving the file.

When you make the first modification in an Emacs buffer that is visiting a file, Emacs records that the file is locked by you. (It does this by creating a symbolic link in the same directory with a different name.) Emacs removes the lock when you save the changes. The idea is that the file is locked whenever an Emacs buffer visiting it has unsaved changes.

If you begin to modify the buffer while the visited file is locked by someone else, this constitutes a collision. When Emacs detects a collision, it asks you what to do, by calling the Lisp function ask-user-about-lock. You can redefine this function for the sake of customization. The standard definition of this function asks you a question and accepts three possible answers:

s
Steal the lock. Whoever was already changing the file loses the lock, and you gain the lock.
p
Proceed. Go ahead and edit the file despite its being locked by someone else.
q
Quit. This causes an error (file-locked) and the modification you were trying to make in the buffer does not actually take place.

Note that locking works on the basis of a file name; if a file has multiple names, Emacs does not realize that the two names are the same file and cannot prevent two users from editing it simultaneously under different names. However, basing locking on names means that Emacs can interlock the editing of new files that will not really exist until they are saved.

Some systems are not configured to allow Emacs to make locks, and there are cases where lock files cannot be written. In these cases, Emacs cannot detect trouble in advance, but it still can detect the collision when you try to save a file and overwrite someone else's changes.

If Emacs or the operating system crashes, this may leave behind lock files which are stale. So you may occasionally get warnings about spurious collisions. When you determine that the collision is spurious, just use p to tell Emacs to go ahead anyway.

Every time Emacs saves a buffer, it first checks the last-modification date of the existing file on disk to verify that it has not changed since the file was last visited or saved. If the date does not match, it implies that changes were made in the file in some other way, and these changes are about to be lost if Emacs actually does save. To prevent this, Emacs prints a warning message and asks for confirmation before saving. Occasionally you will know why the file was changed and know that it does not matter; then you can answer yes and proceed. Otherwise, you should cancel the save with C-g and investigate the situation.

The first thing you should do when notified that simultaneous editing has already taken place is to list the directory with C-u C-x C-d (see section File Directories). This shows the file's current author. You should attempt to contact him to warn him not to continue editing. Often the next step is to save the contents of your Emacs buffer under a different name, and use diff to compare the two files.

Reverting a Buffer

If you have made extensive changes to a file and then change your mind about them, you can get rid of them by reading in the previous version of the file. To do this, use M-x revert-buffer, which operates on the current buffer. Since reverting a buffer unintentionally could lose a lot of work, you must confirm this command with yes.

revert-buffer keeps point at the same distance (measured in characters) from the beginning of the file. If the file was edited only slightly, you will be at approximately the same piece of text after reverting as before. If you have made drastic changes, the same value of point in the old file may address a totally different piece of text.

Reverting marks the buffer as "not modified" until another change is made.

Some kinds of buffers whose contents reflect data bases other than files, such as Dired buffers, can also be reverted. For them, reverting means recalculating their contents from the appropriate data base. Buffers created explicitly with C-x b cannot be reverted; revert-buffer reports an error when asked to do so.

When you edit a file that changes automatically and frequently--for example, a log of output from a process that continues to run--it may be useful for Emacs to revert the file without querying you, whenever you visit the file again with C-x C-f.

To request this behavior, set the variable revert-without-query to a list of regular expressions. When a file name matches one of these regular expressions, find-file and revert-buffer will revert it automatically if it has changed--provided the buffer itself is not modified. (If you have edited the text, it would be wrong to discard your changes.)

Auto-Saving: Protection Against Disasters

Emacs saves all the visited files from time to time (based on counting your keystrokes) without being asked. This is called auto-saving. It prevents you from losing more than a limited amount of work if the system crashes.

When Emacs determines that it is time for auto-saving, each buffer is considered, and is auto-saved if auto-saving is turned on for it and it has been changed since the last time it was auto-saved. The message `Auto-saving...' is displayed in the echo area during auto-saving, if any files are actually auto-saved. Errors occurring during auto-saving are caught so that they do not interfere with the execution of commands you have been typing.

Auto-Save Files

Auto-saving does not normally save in the files that you visited, because it can be very undesirable to save a program that is in an inconsistent state when you have made half of a planned change. Instead, auto-saving is done in a different file called the auto-save file, and the visited file is changed only when you request saving explicitly (such as with C-x C-s).

Normally, the auto-save file name is made by appending `#' to the front and rear of the visited file name. Thus, a buffer visiting file `foo.c' is auto-saved in a file `#foo.c#'. Most buffers that are not visiting files are auto-saved only if you request it explicitly; when they are auto-saved, the auto-save file name is made by appending `#%' to the front and `#' to the rear of buffer name. For example, the `*mail*' buffer in which you compose messages to be sent is auto-saved in a file named `#%*mail*#'. Auto-save file names are made this way unless you reprogram parts of Emacs to do something different (the functions make-auto-save-file-name and auto-save-file-name-p). The file name to be used for auto-saving in a buffer is calculated when auto-saving is turned on in that buffer.

When you delete a substantial part of the text in a large buffer, auto save turns off temporarily in that buffer. This is because if you deleted the text unintentionally, you might find the auto-save file more useful if it contains the deleted text. To reenable auto-saving after this happens, save the buffer with C-x C-s, or use C-u 1 M-x auto-save.

If you want auto-saving to be done in the visited file, set the variable auto-save-visited-file-name to be non-nil. In this mode, there is really no difference between auto-saving and explicit saving.

A buffer's auto-save file is deleted when you save the buffer in its visited file. To inhibit this, set the variable delete-auto-save-files to nil. Changing the visited file name with C-x C-w or set-visited-file-name renames any auto-save file to go with the new visited name.

Controlling Auto-Saving

Each time you visit a file, auto-saving is turned on for that file's buffer if the variable auto-save-default is non-nil (but not in batch mode; see section Entering and Exiting Emacs). The default for this variable is t, so auto-saving is the usual practice for file-visiting buffers. Auto-saving can be turned on or off for any existing buffer with the command M-x auto-save-mode. Like other minor mode commands, M-x auto-save-mode turns auto-saving on with a positive argument, off with a zero or negative argument; with no argument, it toggles.

Emacs does auto-saving periodically based on counting how many characters you have typed since the last time auto-saving was done. The variable auto-save-interval specifies how many characters there are between auto-saves. By default, it is 300.

Auto-saving also takes place when you stop typing for a while. The variable auto-save-timeout says how many seconds Emacs should wait before it does an auto save (and perhaps also a garbage collection). (The actual time period is longer if the current buffer is long; this is a heuristic which aims to keep out of your way when you are editing long buffers, in which auto-save takes an appreciable amount of time.) Auto-saving during idle periods accomplishes two things: first, it makes sure all your work is saved if you go away from the terminal for a while; second, it may avoid some auto-saving while you are actually typing.

Emacs also does auto-saving whenever it gets a fatal error. This includes killing the Emacs job with a shell command such as `kill %emacs', or disconnecting a phone line or network connection.

You can request an auto-save explicitly with the command M-x do-auto-save.

Recovering Data from Auto-Saves

You can use the contents of an auto-save file to recover from a loss of data with the command M-x recover-file RET file RET. This visits file and then (after your confirmation) restores the contents from its auto-save file `#file#'. You can then save with C-x C-s to put the recovered text into file itself. For example, to recover file `foo.c' from its auto-save file `#foo.c#', do:

M-x recover-file RET foo.c RET
yes RET
C-x C-s

Before asking for confirmation, M-x recover-file displays a directory listing describing the specified file and the auto-save file, so you can compare their sizes and dates. If the auto-save file is older, M-x recover-file does not offer to read it.

If Emacs or the computer crashes, you can recover all the files you were editing from their auto save files with the command M-x recover-session. This first shows you a list of recorded interrupted sessions. Move point to the one you choose, and type C-c C-c.

Then recover-session asks about each of the files that were being edited during that session, asking whether to recover that file. If you answer y, it calls recover-file, which works in its normal fashion. It shows the dates of the original file and its auto-save file, and asks once again whether to recover that file.

When recover-session is done, the files you've chosen to recover are present in Emacs buffers. You should then save them. Only this--saving them--updates the files themselves.

Interrupted sessions are recorded for later recovery in files named `~/.saves-pid-hostname'. The `~/.saves' portion of these names comes from the value of auto-save-list-file-prefix. You can arrange to record sessions in a different place by setting that variable in your `.emacs' file, but you'll have to redefine recover-session as well to make it look in the new place. If you set auto-save-list-file-prefix to nil in your `.emacs' file, sessions are not recorded for recovery.

File Name Aliases

Symbolic links and hard links both make it possible for several file names to refer to the same file. Hard links are alternate names that refer directly to the file; all the names are equally valid, and no one of them is preferred. By contrast, a symbolic link is a kind of defined alias: when `foo' is a symbolic link to `bar', you can use either name to refer to the file, but `bar' is the real name, while `foo' is just an alias. More complex cases occur when symbolic links point to directories.

If you visit two names for the same file, normally Emacs makes two different buffers, but it warns you about the situation.

If you wish to avoid visiting the same file in two buffers under different names, set the variable find-file-existing-other-name to a non-nil value. Then find-file uses the existing buffer visiting the file, no matter which of the file's names you specify.

If the variable find-file-visit-truename is non-nil, then the file name recorded for a buffer is the file's truename (made by replacing all symbolic links with their target names), rather than the name you specify. Setting find-file-visit-truename also implies the effect of find-file-existing-other-name.

Version Control

Version control systems are packages that can record multiple versions of a source file, usually storing the unchanged parts of the file just once. Version control systems also record history information such as the creation time of each version, who created it, and a description of what was changed in that version.

The Emacs version control interface is called VC. Its commands work with three version control systems--RCS, CVS and SCCS. The GNU project recommends RCS and CVS, which are free software and available from the Free Software Foundation.

Introduction to Version Control

VC allows you to use a version control system from within Emacs, integrating the version control operations smoothly with editing. VC provides a uniform interface to version control, so that regardless of which version control system is in use, you can use it the same way.

This section provides a general overview of version control, and describes the version control systems that VC supports. You can skip this section if you are already familiar with the version control system you want to use.

Supported Version Control Systems

VC currently works with three different version control systems or "back ends": RCS, CVS, and SCCS.

RCS is a free version control system that is available from the Free Software Foundation. It is perhaps the most mature of the supported back ends, and the VC commands are conceptually closest to RCS. Almost everything you can do with RCS can be done through VC.

CVS is built on top of RCS, and extends the features of RCS, allowing for more sophisticated release management, and concurrent multi-user development. VC supports basic editing operations under CVS, but for some less common tasks you still need to call CVS from the command line. Note also that before using CVS you must set up a repository, which is a subject too complex to treat here.

SCCS is a proprietary but widely used version control system. In terms of capabilities, it is the weakest of the three that VC supports. VC compensates for certain features missing in SCCS (snapshots, for example) by implementing them itself, but some other VC features, such as multiple branches, are not available with SCCS. You should use SCCS only if for some reason you cannot use RCS.

Concepts of Version Control

When a file is under version control, we also say that it is registered in the version control system. Each registered file has a corresponding master file which represents the file's present state plus its change history--enough to reconstruct the current version or any earlier version. Usually the master file also records a log entry for each version, describing in words what was changed in that version.

The file that is maintained under version control is sometimes called the work file corresponding to its master file. You edit the work file and make changes in it, as you would with an ordinary file. (With SCCS and RCS, you must lock the file before you start to edit it.) After you are done with a set of changes, you check the file in, which records the changes in the master file, along with a log entry for them.

With CVS, there are usually multiple work files corresponding to a single master file--often each user has his own copy. It is also possible to use RCS in this way, but this is not the usual way to use RCS.

A version control system typically has some mechanism to coordinate between users who want to change the same file. One method is locking (analogous to the locking that Emacs uses to detect simultaneous editing of a file, but distinct from it). The other method is to merge your changes with other people's changes when you check them in.

With version control locking, work files are normally read-only so that you cannot change them. You ask the version control system to make a work file writable for you by locking it; only one user can do this at any given time. When you check in your changes, that unlocks the file, making the work file read-only again. This allows other users to lock the file to make further changes. SCCS always uses locking, and RCS normally does.

The other alternative for RCS is to let each user modify the work file at any time. In this mode, locking is not required, but it is permitted; check-in is still the way to record a new version.

CVS normally allows each user to modify his own copy of the work file at any time, but requires merging with changes from other users at check-in time. However, CVS can also be set up to require locking. (see section Options for VC Backends).

Version Control and the Mode Line

When you visit a file that is under version control, Emacs indicates this on the mode line. For example, `RCS-1.3' says that RCS is used for that file, and the current version is 1.3.

The character between the back-end name and the version number indicates the version control status of the file. `-' means that the work file is not locked (if locking is in use), or not modified (if locking is not in use). `:' indicates that the file is locked, or that it is modified. If the file is locked by some other user (for instance, `jim'), that is displayed as `RCS:jim:1.3'.

Basic Editing under Version Control

The principal VC command is an all-purpose command that performs either locking or check-in, depending on the situation.

C-x C-q
C-x v v
Perform the next logical version control operation on this file.

Strictly speaking, the command for this job is vc-next-action, bound to C-x v v. However, the normal meaning of C-x C-q is to make a read-only buffer writable, or vice versa; we have extended it to do the same job properly for files managed by version control, by performing the appropriate version control operations. When you type C-x C-q on a registered file, it acts like C-x v v.

The precise action of this command depends on the state of the file, and whether the version control system uses locking or not. SCCS and RCS normally use locking; CVS normally does not use locking.

Basic Version Control with Locking

If locking is used for the file (as with SCCS, and RCS in its default mode), C-x C-q can either lock a file or check it in:

  • If the file is not locked, C-x C-q locks it, and makes it writable so that you can change it.
  • If the file is locked by you, and contains changes, C-x C-q checks in the changes. In order to do this, it first reads the log entry for the new version. See section Features of the Log Entry Buffer.
  • If the file is locked by you, but you have not changed it since you locked it, C-x C-q releases the lock and makes the file read-only again.
  • If the file is locked by some other user, C-x C-q asks you whether you want to "steal the lock" from that user. If you say yes, the file becomes locked by you, but a message is sent to the person who had formerly locked the file, to inform him of what has happened.

These rules also apply when you use CVS in locking mode, except that there is no such thing as stealing a lock.

Basic Version Control without Locking

When there is no locking--the default for CVS--work files are always writable; you do not need to do anything before you begin to edit a file. The status indicator on the mode line is `-' if the file is unmodified; it flips to `:' as soon as you save any changes in the work file.

Here is what C-x C-q does when using CVS:

  • If some other user has checked in changes into the master file, Emacs asks you whether you want to merge those changes into your own work file (see section Merging Branches). You must do this before you can check in your own changes.
  • If there are no new changes in the master file, but you have made modifications in your work file, C-x C-q checks in your changes. In order to do this, it first reads the log entry for the new version. See section Features of the Log Entry Buffer.
  • If the file is not modified, the C-x C-q does nothing.

These rules also apply when you use RCS in the mode that does not require locking, except that automatic merging of changes from the master file is not implemented. Unfortunately, this means that nothing informs you if another user has checked in changes in the same file since you began editing it, and when this happens, his changes will be effectively removed when you check in your version (though they will remain in the master file, so they will not be entirely lost). You must therefore verify the current version is unchanged, before you check in your changes. We hope to eliminate this risk and provide automatic merging with RCS in a future Emacs version.

In addition, locking is possible with RCS even in this mode, although it is not required; C-x C-q with an unmodified file locks the file, just as it does with RCS in its normal (locking) mode.

Features of the Log Entry Buffer

When you check in changes, C-x C-q first reads a log entry. It pops up a buffer called `*VC-Log*' for you to enter the log entry. When you are finished, type C-c C-c in the `*VC-Log*' buffer. That is when check-in really happens.

To abort check-in, just don't type C-c C-c in that buffer. You can switch buffers and do other editing. As long as you don't try to check in another file, the entry you were editing remains in the `*VC-Log*' buffer, and you can go back to that buffer at any time to complete the check-in.

If you change several source files for the same reason, it is often convenient to specify the same log entry for many of the files. To do this, use the history of previous log entries. The commands M-n, M-p, M-s and M-r for doing this work just like the minibuffer history commands (except that these versions are used outside the minibuffer).

Each time you check in a file, the log entry buffer is put into VC Log mode, which involves running two hooks: text-mode-hook and vc-log-mode-hook. See section Hooks.

Examining And Comparing Old Versions

One of the convenient features of version control is the ability to examine any version of a file, or compare two versions.

C-x v ~ version RET
Examine version version of the visited file, in a buffer of its own.
C-x v =
Compare the current buffer contents with the latest checked-in version of the file.
C-u C-x v = file RET oldvers RET newvers RET
Compare the specified two versions of file.
C-x v g
Display the result of the CVS annotate command using colors.

To examine an old version in toto, visit the file and then type C-x v ~ version RET (vc-version-other-window). This puts the text of version version in a file named `filename.~version~', and visits it in its own buffer in a separate window. (In RCS, you can also select an old version and create a branch from it. See section Multiple Branches of a File.)

But usually it is more convenient to compare two versions of the file, with the command C-x v = (vc-diff). Plain C-x v = compares the current buffer contents (saving them in the file if necessary) with the last checked-in version of the file. C-u C-x v =, with a numeric argument, reads a file name and two version numbers, then compares those versions of the specified file.

If you supply a directory name instead of the name of a registered file, this command compares the two specified versions of all registered files in that directory and its subdirectories.

You can specify a checked-in version by its number; an empty input specifies the current contents of the work file (which may be different from all the checked-in versions). You can also specify a snapshot name (see section Snapshots) instead of one or both version numbers.

This command works by running the diff utility, getting the options from the variable diff-switches. It displays the output in a special buffer in another window. Unlike the M-x diff command, C-x v = does not try to locate the changes in the old and new versions. This is because normally one or both versions do not exist as files when you compare them; they exist only in the records of the master file. See section Comparing Files, for more information about M-x diff.

For CVS-controlled files, you can display the result of the CVS annotate command, using colors to enhance the visual appearance. Use the command M-x vc-annotate to do this. Red means new, blue means old, and intermediate colors indicate intermediate ages. A prefix argument n specifies a stretch factor for the time scale; it makes each color cover a period n times as long.

The Secondary Commands of VC

This section explains the secondary commands of VC; those that you might use once a day.

Registering a File for Version Control

You can put any file under version control by simply visiting it, and then typing C-x v i (vc-register).

C-x v i
Register the visited file for version control.

To register the file, Emacs must choose which version control system to use for it. You can specify your choice explicitly by setting vc-default-back-end to RCS, CVS or SCCS. Otherwise, if there is a subdirectory named `RCS', `SCCS', or `CVS', Emacs uses the corresponding version control system. In the absence of any specification, the default choice is RCS if RCS is installed, otherwise SCCS.

If locking is in use, C-x v i leaves the file unlocked and read-only. Type C-x C-q if you wish to start editing it. After registering a file with CVS, you must subsequently commit the initial version by typing C-x C-q.

The initial version number for a newly registered file is 1.1, by default. You can specify a different default by setting the variable vc-default-init-version, or you can give C-x v i a numeric argument; then it reads the initial version number for this particular file using the minibuffer.

If vc-initial-comment is non-nil, C-x v i reads an initial comment to describe the purpose of this source file. Reading the initial comment works like reading a log entry (see section Features of the Log Entry Buffer).

VC Status Commands

C-x v l
Display version control state and change history.

To view the detailed version control status and history of a file, type C-x v l (vc-print-log). It displays the history of changes to the current file, including the text of the log entries. The output appears in a separate window.

Undoing Version Control Actions

C-x v u
Revert the buffer and the file to the last checked-in version.
C-x v c
Remove the last-entered change from the master for the visited file. This undoes your last check-in.

If you want to discard your current set of changes and revert to the last version checked in, use C-x v u (vc-revert-buffer). This leaves the file unlocked; if locking is in use, you must first lock the file again before you change it again. C-x v u requires confirmation, unless it sees that you haven't made any changes since the last checked-in version.

C-x v u is also the command to unlock a file if you lock it and then decide not to change it.

To cancel a change that you already checked in, use C-x v c (vc-cancel-version). This command discards all record of the most recent checked-in version. C-x v c also offers to revert your work file and buffer to the previous version (the one that precedes the version that is deleted).

If you answer no, VC keeps your changes in the buffer, and locks the file. The no-revert option is useful when you have checked in a change and then discover a trivial error in it; you can cancel the erroneous check-in, fix the error, and check the file in again.

When C-x v c does not revert the buffer, it unexpands all version control headers in the buffer instead (see section Inserting Version Control Headers). This is because the buffer no longer corresponds to any existing version. If you check it in again, the check-in process will expand the headers properly for the new version number.

However, it is impossible to unexpand the RCS `$Log$' header automatically. If you use that header feature, you have to unexpand it by hand--by deleting the entry for the version that you just canceled.

Be careful when invoking C-x v c, as it is easy to lose a lot of work with it. To help you be careful, this command always requires confirmation with yes. Note also that this command is disabled under CVS, because canceling versions is very dangerous and discouraged with CVS.

Dired under VC

When you are working on a large program, it is often useful to find out which files have changed within an entire directory tree, or to view the status of all files under version control at once, and to perform version control operations on collections of files. You can use the command C-x v d (vc-directory) to make a directory listing that includes only files relevant for version control.

C-x v d creates a buffer which uses VC Dired Mode. This looks much like an ordinary Dired buffer (see section Dired, the Directory Editor); however, normally it shows only the noteworthy files (those locked or not up-to-date). This is called terse display. If you set the variable vc-dired-terse-display to nil, then VC Dired shows all relevant files--those managed under version control, plus all subdirectories (full display). The command v t in a VC Dired buffer toggles between terse display and full display (see section VC Dired Commands).

By default, VC Dired produces a recursive listing of noteworthy or relevant files at or below the given directory. You can change this by setting the variable vc-dired-recurse to nil; then VC Dired shows only the files in the given directory.

The line for an individual file shows the version control state in the place of the hard link count, owner, group, and size of the file. If the file is unmodified, in sync with the master file, the version control state shown is blank. Otherwise it consists of text in parentheses. Under RCS and SCCS, the name of the user locking the file is shown; under CVS, an abbreviated version of the `cvs status' output is used. Here is an example using RCS:

  /home/jim/project:

  -rw-r--r-- (jim)      Apr  2 23:39 file1
  -r--r--r--            Apr  5 20:21 file2

The files `file1' and `file2' are under version control, `file1' is locked by user jim, and `file2' is unlocked.

Here is an example using CVS:

  /home/joe/develop:

  -rw-r--r-- (modified) Aug  2  1997 file1.c
  -rw-r--r--            Apr  4 20:09 file2.c
  -rw-r--r-- (merge)    Sep 13  1996 file3.c

Here `file1.c' is modified with respect to the repository, and `file2.c' is not. `file3.c' is modified, but other changes have also been checked in to the repository--you need to merge them with the work file before you can check it in.

When VC Dired displays subdirectories (in the "full" display mode), it omits some that should never contain any files under version control. By default, this includes Version Control subdirectories such as `RCS' and `CVS'; you can customize this by setting the variable vc-directory-exclusion-list.

You can fine-tune VC Dired's format by typing C-u C-x v d---as in ordinary Dired, that allows you to specify additional switches for the `ls' command.

VC Dired Commands

All the usual Dired commands work normally in VC Dired mode, except for v, which is redefined as the version control prefix. You can invoke VC commands such as vc-diff and vc-print-log by typing v =, or v l, and so on. Most of these commands apply to the file name on the current line.

The command v v (vc-next-action) operates on all the marked files, so that you can lock or check in several files at once. If it operates on more than one file, it handles each file according to its current state; thus, it might lock one file, but check in another file. This could be confusing; it is up to you to avoid confusing behavior by marking a set of files that are in a similar state.

If any files call for check-in, v v reads a single log entry, then uses it for all the files being checked in. This is convenient for registering or checking in several files at once, as part of the same change.

You can toggle between terse display (only locked files, or files not up-to-date) and full display at any time by typing v t vc-dired-toggle-terse-mode. There is also a special command * l (vc-dired-mark-locked), which marks all files currently locked (or, with CVS, all files not up-to-date). Thus, typing * l t k is another way to delete from the buffer all files except those currently locked.

Multiple Branches of a File

One use of version control is to maintain multiple "current" versions of a file. For example, you might have different versions of a program in which you are gradually adding various unfinished new features. Each such independent line of development is called a branch. VC allows you to create branches, switch between different branches, and merge changes from one branch to another. Please note, however, that branches are only supported for RCS at the moment.

A file's main line of development is usually called the trunk. The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At any such version, you can start an independent branch. A branch starting at version 1.2 would have version number 1.2.1.1, and consecutive versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is a second branch also starting at version 1.2, it would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.

If you omit the final component of a version number, that is called a branch number. It refers to the highest existing version on that branch--the head version of that branch. The branches in the example above have branch numbers 1.2.1 and 1.2.2.

Switching between Branches

To switch between branches, type C-u C-x C-q and specify the version number you want to select. This version is then visited unlocked (write-protected), so you can examine it before locking it. Switching branches in this way is allowed only when the file is not locked.

You can omit the minor version number, thus giving only the branch number; this takes you to the head version on the chosen branch. If you only type RET, Emacs goes to the highest version on the trunk.

After you have switched to any branch (including the main branch), you stay on it for subsequent VC commands, until you explicitly select some other branch.

Creating New Branches

To create a new branch from a head version (one that is the latest in the branch that contains it), first select that version if necessary, lock it with C-x C-q, and make whatever changes you want. Then, when you check in the changes, use C-u C-x C-q. This lets you specify the version number for the new version. You should specify a suitable branch number for a branch starting at the current version. For example, if the current version is 2.5, the branch number should be 2.5.1, 2.5.2, and so on, depending on the number of existing branches at that point.

To create a new branch at an older version (one that is no longer the head of a branch), first select that version (see section Switching between Branches), then lock it with C-x C-q. You'll be asked to confirm, when you lock the old version, that you really mean to create a new branch--if you say no, you'll be offered a chance to lock the latest version instead.

Then make your changes and type C-x C-q again to check in a new version. This automatically creates a new branch starting from the selected version. You need not specially request a new branch, because that's the only way to add a new version at a point that is not the head of a branch.

After the branch is created, you "stay" on it. That means that subsequent check-ins create new versions on that branch. To leave the branch, you must explicitly select a different version with C-u C-x C-q. To transfer changes from one branch to another, use the merge command, described in the next section.

Merging Branches

When you have finished the changes on a certain branch, you will often want to incorporate them into the file's main line of development (the trunk). This is not a trivial operation, because development might also have proceeded on the trunk, so that you must merge the changes into a file that has already been changed otherwise. VC allows you to do this (and other things) with the vc-merge command.

C-x v m (vc-merge)
Merge changes into the work file.

C-x v m (vc-merge) takes a set of changes and merges it into the current version of the work file. It first asks you for a branch number or a pair of version numbers in the minibuffer. Then it finds the changes from that branch, or between the two versions you specified, and merges them into the current version of the current file.

As an example, suppose that you have finished a certain feature on branch 1.3.1. In the meantime, development on the trunk has proceeded to version 1.5. To merge the changes from the branch to the trunk, first go to the head version of the trunk, by typing C-u C-x C-q RET. Version 1.5 is now current. If locking is used for the file, type C-x C-q to lock version 1.5 so that you can change it. Next, type C-x v m 1.3.1 RET. This takes the entire set of changes on branch 1.3.1 (relative to version 1.3, where the branch started, up to the last version on the branch) and merges it into the current version of the work file. You can now check in the changed file, thus creating version 1.6 containing the changes from the branch.

It is possible to do further editing after merging the branch, before the next check-in. But it is usually wiser to check in the merged version, then lock it and make the further changes. This will keep a better record of the history of changes.

When you merge changes into a file that has itself been modified, the changes might overlap. We call this situation a conflict, and reconciling the conflicting changes is called resolving a conflict.

Whenever conflicts occur during merging, VC detects them, tells you about them in the echo area, and asks whether you want help in merging. If you say yes, it starts an Ediff session (see section `Ediff' in The Ediff Manual).

If you say no, the conflicting changes are both inserted into the file, surrounded by conflict markers. The example below shows how a conflict region looks; the file is called `name' and the current master file version with user B's changes in it is 1.11.

<<<<<<< name
  User A's version
=======
  User B's version
>>>>>>> 1.11

Then you can resolve the conflicts by editing the file manually. Or you can type M-x vc-resolve-conflicts after visiting the file. This starts an Ediff session, as described above.

Multi-User Branching

It is often useful for multiple developers to work simultaneously on different branches of a file. CVS allows this by default; for RCS, it is possible if you create multiple source directories. Each source directory should have a link named `RCS' which points to a common directory of RCS master files. Then each source directory can have its own choice of selected versions, but all share the same common RCS records.

This technique works reliably and automatically, provided that the source files contain RCS version headers (see section Inserting Version Control Headers). The headers enable Emacs to be sure, at all times, which version number is present in the work file.

If the files do not have version headers, you must instead tell Emacs explicitly in each session which branch you are working on. To do this, first find the file, then type C-u C-x C-q and specify the correct branch number. This ensures that Emacs knows which branch it is using during this particular editing session.

Snapshots

A snapshot is a named set of file versions (one for each registered file) that you can treat as a unit. One important kind of snapshot is a release, a (theoretically) stable version of the system that is ready for distribution to users.

Making and Using Snapshots

There are two basic commands for snapshots; one makes a snapshot with a given name, the other retrieves a named snapshot.

C-x v s name RET
Define the last saved versions of every registered file in or under the current directory as a snapshot named name (vc-create-snapshot).
C-x v r name RET
For all registered files at or below the current directory level, select whatever versions correspond to the snapshot name (vc-retrieve-snapshot). This command reports an error if any files are locked at or below the current directory, without changing anything; this is to avoid overwriting work in progress.

A snapshot uses a very small amount of resources--just enough to record the list of file names and which version belongs to the snapshot. Thus, you need not hesitate to create snapshots whenever they are useful.

You can give a snapshot name as an argument to C-x v = or C-x v ~ (see section Examining And Comparing Old Versions). Thus, you can use it to compare a snapshot against the current files, or two snapshots against each other, or a snapshot against a named version.

Snapshot Caveats

VC's snapshot facilities are modeled on RCS's named-configuration support. They use RCS's native facilities for this, so under VC snapshots made using RCS are visible even when you bypass VC.

For SCCS, VC implements snapshots itself. The files it uses contain name/file/version-number triples. These snapshots are visible only through VC.

A snapshot is a set of checked-in versions. So make sure that all the files are checked in and not locked when you make a snapshot.

File renaming and deletion can create some difficulties with snapshots. This is not a VC-specific problem, but a general design issue in version control systems that no one has solved very well yet.

If you rename a registered file, you need to rename its master along with it (the command vc-rename-file does this automatically). If you are using SCCS, you must also update the records of the snapshot, to mention the file by its new name (vc-rename-file does this, too). An old snapshot that refers to a master file that no longer exists under the recorded name is invalid; VC can no longer retrieve it. It would be beyond the scope of this manual to explain enough about RCS and SCCS to explain how to update the snapshots by hand.

Using vc-rename-file makes the snapshot remain valid for retrieval, but it does not solve all problems. For example, some of the files in the program probably refer to others by name. At the very least, the makefile probably mentions the file that you renamed. If you retrieve an old snapshot, the renamed file is retrieved under its new name, which is not the name that the makefile expects. So the program won't really work as retrieved.

Miscellaneous Commands and Features of VC

This section explains the less-frequently-used features of VC.

Change Logs and VC

If you use RCS or CVS for a program and also maintain a change log file for it (see section Change Logs), you can generate change log entries automatically from the version control log entries:

C-x v a
Visit the current directory's change log file and, for registered files in that directory, create new entries for versions checked in since the most recent entry in the change log file. (vc-update-change-log). This command works with RCS or CVS only, not with SCCS.
C-u C-x v a
As above, but only find entries for the current buffer's file.
M-1 C-x v a
As above, but find entries for all the currently visited files that are maintained with version control. This works only with RCS, and it puts all entries in the log for the default directory, which may not be appropriate.

For example, suppose the first line of `ChangeLog' is dated 1999-04-10, and that the only check-in since then was by Nathaniel Bowditch to `rcs2log' on 1999-05-22 with log text `Ignore log messages that start with `#'.'. Then C-x v a visits `ChangeLog' and inserts text like this:

@medbreak

1999-05-22  Nathaniel Bowditch  <nat@apn.org>

        * rcs2log: Ignore log messages that start with `#'.

@medbreak

You can then edit the new change log entry further as you wish.

Unfortunately, timestamps in ChangeLog files are only dates, so some of the new change log entry may duplicate what's already in ChangeLog. You will have to remove these duplicates by hand.

Normally, the log entry for file `foo' is displayed as `* foo: text of log entry'. The `:' after `foo' is omitted if the text of the log entry starts with `(functionname): '. For example, if the log entry for `vc.el' is `(vc-do-command): Check call-process status.', then the text in `ChangeLog' looks like this:

@medbreak

1999-05-06  Nathaniel Bowditch  <nat@apn.org>

        * vc.el (vc-do-command): Check call-process status.

@medbreak

When C-x v a adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time. If the log entries for several such files all have the same text, it coalesces them into a single entry. For example, suppose the most recent check-ins have the following log entries:

* For `vc.texinfo': `Fix expansion typos.'
* For `vc.el': `Don't call expand-file-name.'
* For `vc-hooks.el': `Don't call expand-file-name.'

They appear like this in `ChangeLog':

@medbreak

1999-04-01  Nathaniel Bowditch  <nat@apn.org>

        * vc.texinfo: Fix expansion typos.

        * vc.el, vc-hooks.el: Don't call expand-file-name.

@medbreak

Normally, C-x v a separates log entries by a blank line, but you can mark several related log entries to be clumped together (without an intervening blank line) by starting the text of each related log entry with a label of the form `{clumpname} '. The label itself is not copied to `ChangeLog'. For example, suppose the log entries are:

* For `vc.texinfo': `{expand} Fix expansion typos.'
* For `vc.el': `{expand} Don't call expand-file-name.'
* For `vc-hooks.el': `{expand} Don't call expand-file-name.'

Then the text in `ChangeLog' looks like this:

@medbreak

1999-04-01  Nathaniel Bowditch  <nat@apn.org>

        * vc.texinfo: Fix expansion typos.
        * vc.el, vc-hooks.el: Don't call expand-file-name.

@medbreak

A log entry whose text begins with `#' is not copied to `ChangeLog'. For example, if you merely fix some misspellings in comments, you can log the change with an entry beginning with `#' to avoid putting such trivia into `ChangeLog'.

Renaming VC Work Files and Master Files

When you rename a registered file, you must also rename its master file correspondingly to get proper results. Use vc-rename-file to rename the source file as you specify, and rename its master file accordingly. It also updates any snapshots (see section Snapshots) that mention the file, so that they use the new name; despite this, the snapshot thus modified may not completely work (see section Snapshot Caveats).

You cannot use vc-rename-file on a file that is locked by someone else.

Inserting Version Control Headers

Sometimes it is convenient to put version identification strings directly into working files. Certain special strings called version headers are replaced in each successive version by the number of that version.

If you are using RCS, and version headers are present in your working files, Emacs can use them to determine the current version and the locking state of the files. This is more reliable than referring to the master files, which is done when there are no version headers. Note that in a multi-branch environment, version headers are necessary to make VC behave correctly (see section Multi-User Branching).

Searching for version headers is controlled by the variable vc-consult-headers. If it is non-nil, Emacs searches for headers to determine the version number you are editing. Setting it to nil disables this feature.

You can use the C-x v h command (vc-insert-headers) to insert a suitable header string.

C-x v h
Insert headers in a file for use with your version-control system.

The default header string is `$Id$' for RCS and `%W%' for SCCS. You can specify other headers to insert by setting the variable vc-header-alist. Its value is a list of elements of the form (program . string) where program is RCS or SCCS and string is the string to use.

Instead of a single string, you can specify a list of strings; then each string in the list is inserted as a separate header on a line of its own.

It is often necessary to use "superfluous" backslashes when writing the strings that you put in this variable. This is to prevent the string in the constant from being interpreted as a header itself if the Emacs Lisp file containing it is maintained with version control.

Each header is inserted surrounded by tabs, inside comment delimiters, on a new line at point. Normally the ordinary comment start and comment end strings of the current mode are used, but for certain modes, there are special comment delimiters for this purpose; the variable vc-comment-alist specifies them. Each element of this list has the form (mode starter ender).

The variable vc-static-header-alist specifies further strings to add based on the name of the buffer. Its value should be a list of elements of the form (regexp . format). Whenever regexp matches the buffer name, format is inserted as part of the header. A header line is inserted for each element that matches the buffer name, and for each string specified by vc-header-alist. The header line is made by processing the string from vc-header-alist with the format taken from the element. The default value for vc-static-header-alist is as follows:

(("\\.c$" .
  "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
#endif /* lint */\n"))

It specifies insertion of text of this form:

#ifndef lint
static char vcid[] = "string";
#endif /* lint */

Note that the text above starts with a blank line.

If you use more than one version header in a file, put them close together in the file. The mechanism in revert-buffer that preserves markers may not handle markers positioned between two version headers.

Customizing VC

There are many ways of customizing VC. The options you can set fall into four categories, described in the following sections.

Options for VC Backends

You can tell RCS and CVS whether to use locking for a file or not (see section Concepts of Version Control, for a description of locking). VC automatically recognizes what you have chosen, and behaves accordingly.

For RCS, the default is to use locking, but there is a mode called non-strict locking in which you can check-in changes without locking the file first. Use `rcs -U' to switch to non-strict locking for a particular file, see the `rcs' manpage for details.

Under CVS, the default is not to use locking; anyone can change a work file at any time. However, there are ways to restrict this, resulting in behavior that resembles locking.

For one thing, you can set the CVSREAD environment variable to an arbitrary value. If this variable is defined, CVS makes your work files read-only by default. In Emacs, you must type C-x C-q to make the file writeable, so that editing works in fact similar as if locking was used. Note however, that no actual locking is performed, so several users can make their files writeable at the same time. When setting CVSREAD for the first time, make sure to check out all your modules anew, so that the file protections are set correctly.

Another way to achieve something similar to locking is to use the watch feature of CVS. If a file is being watched, CVS makes it read-only by default, and you must also use C-x C-q in Emacs to make it writable. VC calls cvs edit to make the file writeable, and CVS takes care to notify other developers of the fact that you intend to change the file. See the CVS documentation for details on using the watch feature.

You can turn off use of VC for CVS-managed files by setting the variable vc-handle-cvs to nil. If you do this, Emacs treats these files as if they were not registered, and the VC commands are not available for them. You must do all CVS operations manually.

VC Workfile Handling

Emacs normally does not save backup files for source files that are maintained with version control. If you want to make backup files even for files that use version control, set the variable vc-make-backup-files to a non-nil value.

Normally the work file exists all the time, whether it is locked or not. If you set vc-keep-workfiles to nil, then checking in a new version with C-x C-q deletes the work file; but any attempt to visit the file with Emacs creates it again. (With CVS, work files are always kept.)

Editing a version-controlled file through a symbolic link can be dangerous. It bypasses the version control system--you can edit the file without locking it, and fail to check your changes in. Also, your changes might overwrite those of another user. To protect against this, VC checks each symbolic link that you visit, to see if it points to a file under version control.

The variable vc-follow-symlinks controls what to do when a symbolic link points to a version-controlled file. If it is nil, VC only displays a warning message. If it is t, VC automatically follows the link, and visits the real file instead, telling you about this in the echo area. If the value is ask (the default), VC asks you each time whether to follow the link.

VC Status Retrieval

When deducing the locked/unlocked state of a file, VC first looks for an RCS version header string in the file (see section Inserting Version Control Headers). If there is no header string, or if you are using SCCS, VC normally looks at the file permissions of the work file; this is fast. But there might be situations when the file permissions cannot be trusted. In this case the master file has to be consulted, which is rather expensive. Also the master file can only tell you if there's any lock on the file, but not whether your work file really contains that locked version.

You can tell VC not to use version headers to determine lock status by setting vc-consult-headers to nil. VC then always uses the file permissions (if it can trust them), or else checks the master file.

You can specify the criterion for whether to trust the file permissions by setting the variable vc-mistrust-permissions. Its value can be t (always mistrust the file permissions and check the master file), nil (always trust the file permissions), or a function of one argument which makes the decision. The argument is the directory name of the `RCS', `CVS' or `SCCS' subdirectory. A non-nil value from the function says to mistrust the file permissions. If you find that the file permissions of work files are changed erroneously, set vc-mistrust-permissions to t. Then VC always checks the master file to determine the file's status.

VC Command Execution

If vc-suppress-confirm is non-nil, then C-x C-q and C-x v i can save the current buffer without asking, and C-x v u also operates without asking for confirmation. (This variable does not affect C-x v c; that operation is so drastic that it should always ask for confirmation.)

VC mode does much of its work by running the shell commands for RCS, CVS and SCCS. If vc-command-messages is non-nil, VC displays messages to indicate which shell commands it runs, and additional messages when the commands finish.

You can specify additional directories to search for version control programs by setting the variable vc-path. These directories are searched before the usual search path. But the proper files are usually found automatically.

File Directories

The file system groups files into directories. A directory listing is a list of all the files in a directory. Emacs provides commands to create and delete directories, and to make directory listings in brief format (file names only) and verbose format (sizes, dates, and authors included). There is also a directory browser called Dired; see section Dired, the Directory Editor.

C-x C-d dir-or-pattern RET
Display a brief directory listing (list-directory).
C-u C-x C-d dir-or-pattern RET
Display a verbose directory listing.
M-x make-directory RET dirname RET
Create a new directory named dirname.
M-x delete-directory RET dirname RET
Delete the directory named dirname. It must be empty, or you get an error.

The command to display a directory listing is C-x C-d (list-directory). It reads using the minibuffer a file name which is either a directory to be listed or a wildcard-containing pattern for the files to be listed. For example,

C-x C-d /u2/emacs/etc RET

lists all the files in directory `/u2/emacs/etc'. Here is an example of specifying a file name pattern:

C-x C-d /u2/emacs/src/*.c RET

Normally, C-x C-d prints a brief directory listing containing just file names. A numeric argument (regardless of value) tells it to make a verbose listing including sizes, dates, and authors (like `ls -l').

The text of a directory listing is obtained by running ls in an inferior process. Two Emacs variables control the switches passed to ls: list-directory-brief-switches is a string giving the switches to use in brief listings ("-CF" by default), and list-directory-verbose-switches is a string giving the switches to use in a verbose listing ("-l" by default).

Comparing Files

The command M-x diff compares two files, displaying the differences in an Emacs buffer named `*Diff*'. It works by running the diff program, using options taken from the variable diff-switches, whose value should be a string.

The buffer `*Diff*' has Compilation mode as its major mode, so you can use C-x ` to visit successive changed locations in the two source files. You can also move to a particular hunk of changes and type RET or C-c C-c, or click Mouse-2 on it, to move to the corresponding source location. You can also use the other special commands of Compilation mode: SPC and DEL for scrolling, and M-p and M-n for cursor motion. See section Running Compilations under Emacs.

The command M-x diff-backup compares a specified file with its most recent backup. If you specify the name of a backup file, diff-backup compares it with the source file that it is a backup of.

The command M-x compare-windows compares the text in the current window with that in the next window. Comparison starts at point in each window, and each starting position is pushed on the mark ring in its respective buffer. Then point moves forward in each window, a character at a time, until a mismatch between the two windows is reached. Then the command is finished. For more information about windows in Emacs, section Multiple Windows.

With a numeric argument, compare-windows ignores changes in whitespace. If the variable compare-ignore-case is non-nil, it ignores differences in case as well.

See also section Merging Files with Emerge, for convenient facilities for merging two similar files.

Miscellaneous File Operations

Emacs has commands for performing many other operations on files. All operate on one file; they do not accept wildcard file names.

M-x view-file allows you to scan or read a file by sequential screenfuls. It reads a file name argument using the minibuffer. After reading the file into an Emacs buffer, view-file displays the beginning. You can then type SPC to scroll forward one windowful, or DEL to scroll backward. Various other commands are provided for moving around in the file, but none for changing it; type ? while viewing for a list of them. They are mostly the same as normal Emacs cursor motion commands. To exit from viewing, type q. The commands for viewing are defined by a special major mode called View mode.

A related command, M-x view-buffer, views a buffer already present in Emacs. See section Miscellaneous Buffer Operations.

M-x insert-file inserts a copy of the contents of the specified file into the current buffer at point, leaving point unchanged before the contents and the mark after them.

M-x write-region is the inverse of M-x insert-file; it copies the contents of the region into the specified file. M-x append-to-file adds the text of the region to the end of the specified file. See section Accumulating Text.

M-x delete-file deletes the specified file, like the rm command in the shell. If you are deleting many files in one directory, it may be more convenient to use Dired (see section Dired, the Directory Editor).

M-x rename-file reads two file names old and new using the minibuffer, then renames file old as new. If a file named new already exists, you must confirm with yes or renaming is not done; this is because renaming causes the old meaning of the name new to be lost. If old and new are on different file systems, the file old is copied and deleted.

The similar command M-x add-name-to-file is used to add an additional name to an existing file without removing its old name. The new name must belong on the same file system that the file is on.

M-x copy-file reads the file old and writes a new file named new with the same contents. Confirmation is required if a file named new already exists, because copying has the consequence of overwriting the old contents of the file new.

M-x make-symbolic-link reads two file names target and linkname, then creates a symbolic link named linkname and pointing at target. The effect is that future attempts to open file linkname will refer to whatever file is named target at the time the opening is done, or will get an error if the name target is not in use at that time. This command does not expand the argument target, so that it allows you to specify a relative name as the target of the link.

Confirmation is required when creating the link if linkname is in use. Note that not all systems support symbolic links.

Accessing Compressed Files

Emacs comes with a library that can automatically uncompress compressed files when you visit them, and automatically recompress them if you alter them and save them. To enable this feature, type the command M-x auto-compression-mode.

When automatic compression (which implies automatic uncompression as well) is enabled, Emacs recognizes compressed files by their file names. File names ending in `.gz' indicate a file compressed with gzip. Other endings indicate other compression programs.

Automatic uncompression and compression apply to all the operations in which Emacs uses the contents of a file. This includes visiting it, saving it, inserting its contents into a buffer, loading it, and byte compiling it.

Remote Files

You can refer to files on other machines using a special file name syntax:

/host:filename
/user@host:filename

When you do this, Emacs uses the FTP program to read and write files on the specified host. It logs in through FTP using your user name or the name user. It may ask you for a password from time to time; this is used for logging in on host.

Normally, if you do not specify a user name in a remote file name, that means to use your own user name. But if you set the variable ange-ftp-default-user to a string, that string is used instead. (The Emacs package that implements FTP file access is called ange-ftp.)

You can entirely turn off the FTP file name feature by setting the variable file-name-handler-alist to nil.

Quoted File Names

You can quote an absolute file name to prevent special characters and syntax in it from having their special effects. The way to do this is to add `/:' at the beginning.

For example, you can quote a local file name which appears remote, to prevent it from being treated as a remote file name. Thus, if you have a directory named `/foo:' and a file named `bar' in it, you can refer to that file in Emacs as `/:/foo:/bar'.

`/:' can also prevent `~' from being treated as a special character for a user's home directory. For example, `/:/tmp/~hack' refers to a file whose name is `~hack' in directory `/tmp'.

Likewise, quoting with `/:' is one way to enter in the minibuffer a file name that contains `$'. However, the `/:' must be at the beginning of the buffer in order to quote `$'.

You can also quote wildcard characters with `/:', for visiting. For example, `/:/tmp/foo*bar' visits the file `/tmp/foo*bar'. However, in most cases you can simply type the wildcard characters for themselves. For example, if the only file name in `/tmp' that starts with `foo' and ends with `bar' is `foo*bar', then specifying `/tmp/foo*bar' will visit just `/tmp/foo*bar'.

Using Multiple Buffers

The text you are editing in Emacs resides in an object called a buffer. Each time you visit a file, a buffer is created to hold the file's text. Each time you invoke Dired, a buffer is created to hold the directory listing. If you send a message with C-x m, a buffer named `*mail*' is used to hold the text of the message. When you ask for a command's documentation, that appears in a buffer called `*Help*'.

At any time, one and only one buffer is selected. It is also called the current buffer. Often we say that a command operates on "the buffer" as if there were only one; but really this means that the command operates on the selected buffer (most commands do).

When Emacs has multiple windows, each window has a chosen buffer which is displayed there, but at any time only one of the windows is selected and its chosen buffer is the selected buffer. Each window's mode line displays the name of the buffer that the window is displaying (see section Multiple Windows).

Each buffer has a name, which can be of any length, and you can select any buffer by giving its name. Most buffers are made by visiting files, and their names are derived from the files' names. But you can also create an empty buffer with any name you want. A newly started Emacs has a buffer named `*scratch*' which can be used for evaluating Lisp expressions in Emacs. The distinction between upper and lower case matters in buffer names.

Each buffer records individually what file it is visiting, whether it is modified, and what major mode and minor modes are in effect in it (see section Major Modes). Any Emacs variable can be made local to a particular buffer, meaning its value in that buffer can be different from the value in other buffers. See section Local Variables.

Creating and Selecting Buffers

C-x b buffer RET
Select or create a buffer named buffer (switch-to-buffer).
C-x 4 b buffer RET
Similar, but select buffer in another window (switch-to-buffer-other-window).
C-x 5 b buffer RET
Similar, but select buffer in a separate frame (switch-to-buffer-other-frame).

To select the buffer named bufname, type C-x b bufname RET. This runs the command switch-to-buffer with argument bufname. You can use completion on an abbreviation for the buffer name you want (see section Completion). An empty argument to C-x b specifies the most recently selected buffer that is not displayed in any window.

Most buffers are created by visiting files, or by Emacs commands that want to display some text, but you can also create a buffer explicitly by typing C-x b bufname RET. This makes a new, empty buffer that is not visiting any file, and selects it for editing. Such buffers are used for making notes to yourself. If you try to save one, you are asked for the file name to use. The new buffer's major mode is determined by the value of default-major-mode (see section Major Modes).

Note that C-x C-f, and any other command for visiting a file, can also be used to switch to an existing file-visiting buffer. See section Visiting Files.

Emacs uses buffer names that start with a space for internal purposes. It treats these buffers specially in minor ways--for example, by default they do not record undo information. It is best to avoid using such buffer names yourself.

Listing Existing Buffers

C-x C-b
List the existing buffers (list-buffers).

To display a list of all the buffers that exist, type C-x C-b. Each line in the list shows one buffer's name, major mode and visited file. The buffers are listed in the order that they were current; the buffers that were current most recently come first.

`*' at the beginning of a line indicates the buffer is "modified." If several buffers are modified, it may be time to save some with C-x s (see section Saving Files). `%' indicates a read-only buffer. `.' marks the selected buffer. Here is an example of a buffer list:

 MR Buffer         Size  Mode           File
 -- ------         ----  ----           ----
.*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
    *Help*         1287  Fundamental
    files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
  % RMAIL          64042 RMAIL          /u/rms/RMAIL
 *% man            747   Dired          /u2/emacs/man/
    net.emacs      343885 Fundamental   /u/rms/net.emacs
    fileio.c       27691 C              /u2/emacs/src/fileio.c
    NEWS           67340 Text           /u2/emacs/etc/NEWS
    *scratch*	   0	 Lisp Interaction

Note that the buffer `*Help*' was made by a help request; it is not visiting any file. The buffer man was made by Dired on the directory `/u2/emacs/man/'.

Miscellaneous Buffer Operations

C-x C-q
Toggle read-only status of buffer (vc-toggle-read-only).
M-x rename-buffer RET name RET
Change the name of the current buffer.
M-x rename-uniquely
Rename the current buffer by adding `<number>' to the end.
M-x view-buffer RET buffer RET
Scroll through buffer buffer.

A buffer can be read-only, which means that commands to change its contents are not allowed. The mode line indicates read-only buffers with `%%' or `%*' near the left margin. Read-only buffers are usually made by subsystems such as Dired and Rmail that have special commands to operate on the text; also by visiting a file whose access control says you cannot write it.

If you wish to make changes in a read-only buffer, use the command C-x C-q (vc-toggle-read-only). It makes a read-only buffer writable, and makes a writable buffer read-only. In most cases, this works by setting the variable buffer-read-only, which has a local value in each buffer and makes the buffer read-only if its value is non-nil. If the file is maintained with version control, C-x C-q works through the version control system to change the read-only status of the file as well as the buffer. See section Version Control.

M-x rename-buffer changes the name of the current buffer. Specify the new name as a minibuffer argument. There is no default. If you specify a name that is in use for some other buffer, an error happens and no renaming is done.

M-x rename-uniquely renames the current buffer to a similar name with a numeric suffix added to make it both different and unique. This command does not need an argument. It is useful for creating multiple shell buffers: if you rename the `*Shell*' buffer, then do M-x shell again, it makes a new shell buffer named `*Shell*'; meanwhile, the old shell buffer continues to exist under its new name. This method is also good for mail buffers, compilation buffers, and most Emacs features that create special buffers with particular names.

M-x view-buffer is much like M-x view-file (see section Miscellaneous File Operations) except that it examines an already existing Emacs buffer. View mode provides commands for scrolling through the buffer conveniently but not for changing it. When you exit View mode with q, that switches back to the buffer (and the position) which was previously displayed in the window. Alternatively, if you exit View mode with e, the buffer and the value of point that resulted from your perusal remain in effect.

The commands M-x append-to-buffer and M-x insert-buffer can be used to copy text from one buffer to another. See section Accumulating Text.

Killing Buffers

If you continue an Emacs session for a while, you may accumulate a large number of buffers. You may then find it convenient to kill the buffers you no longer need. On most operating systems, killing a buffer releases its space back to the operating system so that other programs can use it. Here are some commands for killing buffers:

C-x k bufname RET
Kill buffer bufname (kill-buffer).
M-x kill-some-buffers
Offer to kill each buffer, one by one.

C-x k (kill-buffer) kills one buffer, whose name you specify in the minibuffer. The default, used if you type just RET in the minibuffer, is to kill the current buffer. If you kill the current buffer, another buffer is selected; one that has been selected recently but does not appear in any window now. If you ask to kill a file-visiting buffer that is modified (has unsaved editing), then you must confirm with yes before the buffer is killed.

The command M-x kill-some-buffers asks about each buffer, one by one. An answer of y means to kill the buffer. Killing the current buffer or a buffer containing unsaved changes selects a new buffer or asks for confirmation just like kill-buffer.

The buffer menu feature (see section Operating on Several Buffers) is also convenient for killing various buffers.

If you want to do something special every time a buffer is killed, you can add hook functions to the hook kill-buffer-hook (see section Hooks).

If you run one Emacs session for a period of days, as many people do, it can fill up with buffers that you used several days ago. The command M-x clean-buffer-list is a convenient way to purge them; it kills all the unmodified buffers that you have not used for a long time. An ordinary buffer is killed if it has not been displayed for three days; however, you can specify certain buffers that should never be killed automatically, and others that should be killed if they have been unused for a mere hour.

You can also have this buffer purging done for you, every day at midnight, by enabling Midnight mode. Midnight mode operates each day at midnight; at that time, it runs clean-buffer-list, or whichever functions you have placed in the normal hook midnight-hook (see section Hooks).

To enable Midnight mode, use the Customization buffer to set the variable midnight-mode to t. See section Easy Customization Interface.

Operating on Several Buffers

The buffer-menu facility is like a "Dired for buffers"; it allows you to request operations on various Emacs buffers by editing an Emacs buffer containing a list of them. You can save buffers, kill them (here called deleting them, for consistency with Dired), or display them.

M-x buffer-menu
Begin editing a buffer listing all Emacs buffers.

The command buffer-menu writes a list of all Emacs buffers into the buffer `*Buffer List*', and selects that buffer in Buffer Menu mode. The buffer is read-only, and can be changed only through the special commands described in this section. The usual Emacs cursor motion commands can be used in the `*Buffer List*' buffer. The following commands apply to the buffer described on the current line.

d
Request to delete (kill) the buffer, then move down. The request shows as a `D' on the line, before the buffer name. Requested deletions take place when you type the x command.
C-d
Like d but move up afterwards instead of down.
s
Request to save the buffer. The request shows as an `S' on the line. Requested saves take place when you type the x command. You may request both saving and deletion for the same buffer.
x
Perform previously requested deletions and saves.
u
Remove any request made for the current line, and move down.
DEL
Move to previous line and remove any request made for that line.

The d, C-d, s and u commands to add or remove flags also move down (or up) one line. They accept a numeric argument as a repeat count.

These commands operate immediately on the buffer listed on the current line:

~
Mark the buffer "unmodified." The command ~ does this immediately when you type it.
%
Toggle the buffer's read-only flag. The command % does this immediately when you type it.
t
Visit the buffer as a tags table. See section Selecting a Tags Table.

There are also commands to select another buffer or buffers:

q
Quit the buffer menu--immediately display the most recent formerly visible buffer in its place.
RET
f
Immediately select this line's buffer in place of the `*Buffer List*' buffer.
o
Immediately select this line's buffer in another window as if by C-x 4 b, leaving `*Buffer List*' visible.
C-o
Immediately display this line's buffer in another window, but don't select the window.
1
Immediately select this line's buffer in a full-screen window.
2
Immediately set up two windows, with this line's buffer in one, and the previously selected buffer (aside from the buffer `*Buffer List*') in the other.
b
Bury the buffer listed on this line.
m
Mark this line's buffer to be displayed in another window if you exit with the v command. The request shows as a `>' at the beginning of the line. (A single buffer may not have both a delete request and a display request.)
v
Immediately select this line's buffer, and also display in other windows any buffers previously marked with the m command. If you have not marked any buffers, this command is equivalent to 1.

All that buffer-menu does directly is create and switch to a suitable buffer, and turn on Buffer Menu mode. Everything else described above is implemented by the special commands provided in Buffer Menu mode. One consequence of this is that you can switch from the `*Buffer List*' buffer to another Emacs buffer, and edit there. You can reselect the `*Buffer List*' buffer later, to perform the operations already requested, or you can kill it, or pay no further attention to it.

The only difference between buffer-menu and list-buffers is that buffer-menu switches to the `*Buffer List*' buffer in the selected window; list-buffers displays it in another window. If you run list-buffers (that is, type C-x C-b) and select the buffer list manually, you can use all of the commands described here.

The buffer `*Buffer List*' is not updated automatically when buffers are created and killed; its contents are just text. If you have created, deleted or renamed buffers, the way to update `*Buffer List*' to show what you have done is to type g (revert-buffer) or repeat the buffer-menu command.

Indirect Buffers

An indirect buffer shares the text of some other buffer, which is called the base buffer of the indirect buffer. In some ways it is the analogue, for buffers, of a symbolic link between files.

M-x make-indirect-buffer base-buffer RET indirect-name RET
Create an indirect buffer named indirect-name whose base buffer is base-buffer.

The text of the indirect buffer is always identical to the text of its base buffer; changes made by editing either one are visible immediately in the other. But in all other respects, the indirect buffer and its base buffer are completely separate. They have different names, different values of point, different narrowing, different markers, different major modes, and different local variables.

An indirect buffer cannot visit a file, but its base buffer can. If you try to save the indirect buffer, that actually works by saving the base buffer. Killing the base buffer effectively kills the indirect buffer, but killing an indirect buffer has no effect on its base buffer.

One way to use indirect buffers is to display multiple views of an outline. See section Viewing One Outline in Multiple Views.

Multiple Windows

Emacs can split a frame into two or many windows. Multiple windows can display parts of different buffers, or different parts of one buffer. Multiple frames always imply multiple windows, because each frame has its own set of windows. Each window belongs to one and only one frame.

Concepts of Emacs Windows

Each Emacs window displays one Emacs buffer at any time. A single buffer may appear in more than one window; if it does, any changes in its text are displayed in all the windows where it appears. But the windows showing the same buffer can show different parts of it, because each window has its own value of point.

At any time, one of the windows is the selected window; the buffer this window is displaying is the current buffer. The terminal's cursor shows the location of point in this window. Each other window has a location of point as well, but since the terminal has only one cursor there is no way to show where those locations are. When multiple frames are visible in X Windows, each frame has a cursor which appears in the frame's selected window. The cursor in the selected frame is solid; the cursor in other frames is a hollow box.

Commands to move point affect the value of point for the selected Emacs window only. They do not change the value of point in any other Emacs window, even one showing the same buffer. The same is true for commands such as C-x b to change the selected buffer in the selected window; they do not affect other windows at all. However, there are other commands such as C-x 4 b that select a different window and switch buffers in it. Also, all commands that display information in a window, including (for example) C-h f (describe-function) and C-x C-b (list-buffers), work by switching buffers in a nonselected window without affecting the selected window.

When multiple windows show the same buffer, they can have different regions, because they can have different values of point. However, they all have the same value for the mark, because each buffer has only one mark position.

Each window has its own mode line, which displays the buffer name, modification status and major and minor modes of the buffer that is displayed in the window. See section The Mode Line, for full details on the mode line.

@break

Splitting Windows

C-x 2
Split the selected window into two windows, one above the other (split-window-vertically).
C-x 3
Split the selected window into two windows positioned side by side (split-window-horizontally).
C-Mouse-2
In the mode line or scroll bar of a window, split that window.

The command C-x 2 (split-window-vertically) breaks the selected window into two windows, one above the other. Both windows start out displaying the same buffer, with the same value of point. By default the two windows each get half the height of the window that was split; a numeric argument specifies how many lines to give to the top window.

C-x 3 (split-window-horizontally) breaks the selected window into two side-by-side windows. A numeric argument specifies how many columns to give the one on the left. A line of vertical bars separates the two windows. Windows that are not the full width of the screen have mode lines, but they are truncated. On terminals where Emacs does not support highlighting, truncated mode lines sometimes do not appear in inverse video.

You can split a window horizontally or vertically by clicking C-Mouse-2 in the mode line or the scroll bar. The line of splitting goes through the place where you click: if you click on the mode line, the new scroll bar goes above the spot; if you click in the scroll bar, the mode line of the split window is side by side with your click.

When a window is less than the full width, text lines too long to fit are frequent. Continuing all those lines might be confusing. The variable truncate-partial-width-windows can be set non-nil to force truncation in all windows less than the full width of the screen, independent of the buffer being displayed and its value for truncate-lines. See section Continuation Lines.

Horizontal scrolling is often used in side-by-side windows. See section Controlling the Display.

If split-window-keep-point is non-nil, the default, both of the windows resulting from C-x 2 inherit the value of point from the window that was split. This means that scrolling is inevitable. If this variable is nil, then C-x 2 tries to avoid shifting any text the screen, by putting point in each window at a position already visible in the window. It also selects whichever window contain the screen line that the cursor was previously on. Some users prefer the latter mode on slow terminals.

Using Other Windows

C-x o
Select another window (other-window). That is o, not zero.
C-M-v
Scroll the next window (scroll-other-window).
M-x compare-windows
Find next place where the text in the selected window does not match the text in the next window.
Mouse-1
Mouse-1, in a window's mode line, selects that window but does not move point in it (mouse-select-window).

To select a different window, click with Mouse-1 on its mode line. With the keyboard, you can switch windows by typing C-x o (other-window). That is an o, for `other', not a zero. When there are more than two windows, this command moves through all the windows in a cyclic order, generally top to bottom and left to right. After the rightmost and bottommost window, it goes back to the one at the upper left corner. A numeric argument means to move several steps in the cyclic order of windows. A negative argument moves around the cycle in the opposite order. When the minibuffer is active, the minibuffer is the last window in the cycle; you can switch from the minibuffer window to one of the other windows, and later switch back and finish supplying the minibuffer argument that is requested. See section Editing in the Minibuffer.

The usual scrolling commands (see section Controlling the Display) apply to the selected window only, but there is one command to scroll the next window. C-M-v (scroll-other-window) scrolls the window that C-x o would select. It takes arguments, positive and negative, like C-v. (In the minibuffer, C-M-v scrolls the window that contains the minibuffer help display, if any, rather than the next window in the standard cyclic order.)

The command M-x compare-windows lets you compare two files or buffers visible in two windows, by moving through them to the next mismatch. See section Comparing Files, for details.

Displaying in Another Window

C-x 4 is a prefix key for commands that select another window (splitting the window if there is only one) and select a buffer in that window. Different C-x 4 commands have different ways of finding the buffer to select.

C-x 4 b bufname RET
Select buffer bufname in another window. This runs switch-to-buffer-other-window.
C-x 4 C-o bufname RET
Display buffer bufname in another window, but don't select that buffer or that window. This runs display-buffer.
C-x 4 f filename RET
Visit file filename and select its buffer in another window. This runs find-file-other-window. See section Visiting Files.
C-x 4 d directory RET
Select a Dired buffer for directory directory in another window. This runs dired-other-window. See section Dired, the Directory Editor.
C-x 4 m
Start composing a mail message in another window. This runs mail-other-window; its same-window analogue is C-x m (see section Sending Mail).
C-x 4 .
Find a tag in the current tags table, in another window. This runs find-tag-other-window, the multiple-window variant of M-. (see section Tags Tables).
C-x 4 r filename RET
Visit file filename read-only, and select its buffer in another window. This runs find-file-read-only-other-window. See section Visiting Files.

Forcing Display in the Same Window

Certain Emacs commands switch to a specific buffer with special contents. For example, M-x shell switches to a buffer named `*Shell*'. By convention, all these commands are written to pop up the buffer in a separate window. But you can specify that certain of these buffers should appear in the selected window.

If you add a buffer name to the list same-window-buffer-names, the effect is that such commands display that particular buffer by switching to it in the selected window. For example, if you add the element "*grep*" to the list, the grep command will display its output buffer in the selected window.

The default value of same-window-buffer-names is not nil: it specifies buffer names `*info*', `*mail*' and `*shell*' (as well as others used by more obscure Emacs packages). This is why M-x shell normally switches to the `*shell*' buffer in the selected window. If you delete this element from the value of same-window-buffer-names, the behavior of M-x shell will change--it will pop up the buffer in another window instead.

You can specify these buffers more generally with the variable same-window-regexps. Set it to a list of regular expressions; then any buffer whose name matches one of those regular expressions is displayed by switching to it in the selected window. (Once again, this applies only to buffers that normally get displayed for you in a separate window.) The default value of this variable specifies Telnet and rlogin buffers.

An analogous feature lets you specify buffers which should be displayed in their own individual frames. See section Special Buffer Frames.

Deleting and Rearranging Windows

C-x 0
Delete the selected window (delete-window). The last character in this key sequence is a zero.
C-x 1
Delete all windows in the selected frame except the selected window (delete-other-windows).
C-x 4 0
Delete the selected window and kill the buffer that was showing in it (kill-buffer-and-window). The last character in this key sequence is a zero.
C-x ^
Make selected window taller (enlarge-window).
C-x }
Make selected window wider (enlarge-window-horizontally).
C-x {
Make selected window narrower (shrink-window-horizontally).
C-x -
Shrink this window if its buffer doesn't need so many lines (shrink-window-if-larger-than-buffer).
C-x +
Make all windows the same height (balance-windows).
Drag-Mouse-1
Dragging a window's mode line up or down with Mouse-1 changes window heights.
Mouse-2
Mouse-2 in a window's mode line deletes all other windows in the frame (mouse-delete-other-windows).
Mouse-3
Mouse-3 in a window's mode line deletes that window (mouse-delete-window).

To delete a window, type C-x 0 (delete-window). (That is a zero.) The space occupied by the deleted window is given to an adjacent window (but not the minibuffer window, even if that is active at the time). Once a window is deleted, its attributes are forgotten; only restoring a window configuration can bring it back. Deleting the window has no effect on the buffer it used to display; the buffer continues to exist, and you can select it in any window with C-x b.

C-x 4 0 (kill-buffer-and-window) is a stronger command than C-x 0; it kills the current buffer and then deletes the selected window.

C-x 1 (delete-other-windows) is more powerful in a different way; it deletes all the windows except the selected one (and the minibuffer); the selected window expands to use the whole frame except for the echo area.

You can also delete a window by clicking on its mode line with Mouse-2, and delete all the windows in a frame except one window by clicking on that window's mode line with Mouse-3.

The easiest way to adjust window heights is with a mouse. If you press Mouse-1 on a mode line, you can drag that mode line up or down, changing the heights of the windows above and below it.

To readjust the division of space among vertically adjacent windows, use C-x ^ (enlarge-window). It makes the currently selected window get one line bigger, or as many lines as is specified with a numeric argument. With a negative argument, it makes the selected window smaller. C-x } (enlarge-window-horizontally) makes the selected window wider by the specified number of columns. C-x { (shrink-window-horizontally) makes the selected window narrower by the specified number of columns.

When you make a window bigger, the space comes from one of its neighbors. If this makes any window too small, it is deleted and its space is given to an adjacent window. The minimum size is specified by the variables window-min-height and window-min-width.

The command C-x - (shrink-window-if-larger-than-buffer) reduces the height of the selected window, if it is taller than necessary to show the whole text of the buffer it is displaying. It gives the extra lines to other windows in the frame.

You can also use C-x + (balance-windows) to even out the heights of all the windows in the selected frame.

See section Editing in the Minibuffer, for information about the Resize-Minibuffer mode, which automatically changes the size of the minibuffer window to fit the text in the minibuffer.

Frames and X Windows

When using the X Window System, you can create multiple windows at the X level in a single Emacs session. Each X window that belongs to Emacs displays a frame which can contain one or several Emacs windows. A frame initially contains a single general-purpose Emacs window which you can subdivide vertically or horizontally into smaller windows. A frame normally contains its own echo area and minibuffer, but you can make frames that don't have these--they use the echo area and minibuffer of another frame.

Editing you do in one frame also affects the other frames. For instance, if you put text in the kill ring in one frame, you can yank it in another frame. If you exit Emacs through C-x C-c in one frame, it terminates all the frames. To delete just one frame, use C-x 5 0.

To avoid confusion, we reserve the word "window" for the subdivisions that Emacs implements, and never use it to refer to a frame.

Emacs compiled for MS-DOS emulates some aspects of the window system so that you can use many of the features described in this chapter. See section Keyboard and Mouse on MS-DOS, for more information.

Mouse Commands for Editing

The mouse commands for selecting and copying a region are mostly compatible with the xterm program. You can use the same mouse commands for copying between Emacs and other X client programs.

If you select a region with any of these mouse commands, and then immediately afterward type the DELETE function key, it deletes the region that you selected. The BACKSPACE function key and the ASCII character DEL do not do this; if you type any other key in between the mouse command and DELETE, it does not do this.

Mouse-1
Move point to where you click (mouse-set-point). This is normally the left button.
Drag-Mouse-1
Set the region to the text you select by dragging, and copy it to the kill ring (mouse-set-region). You can specify both ends of the region with this single command. If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse back into the window. This way, you can select regions that don't fit entirely on the screen. The number of lines scrolled per step depends on how far away from the window edge the mouse has gone; the variable mouse-scroll-min-lines specifies a minimum step size.
Mouse-2
Yank the last killed text, where you click (mouse-yank-at-click). This is normally the middle button.
Mouse-3
This command, mouse-save-then-kill, has several functions depending on where you click and the status of the region. The most basic case is when you click Mouse-1 in one place and then Mouse-3 in another. This selects the text between those two positions as the region. It also copies the new region to the kill ring, so that you can copy it to someplace else. If you click Mouse-1 in the text, scroll with the scroll bar, and then click Mouse-3, it remembers where point was before scrolling (where you put it with Mouse-1), and uses that position as the other end of the region. This is so that you can select a region that doesn't fit entirely on the screen. More generally, if you do not have a highlighted region, Mouse-3 selects the text between point and the click position as the region. It does this by setting the mark where point was, and moving point to where you click. If you have a highlighted region, or if the region was set just before by dragging button 1, Mouse-3 adjusts the nearer end of the region by moving it to where you click. The adjusted region's text also replaces the old region's text in the kill ring. If you originally specified the region using a double or triple Mouse-1, so that the region is defined to consist of entire words or lines, then adjusting the region with Mouse-3 also proceeds by entire words or lines. If you use Mouse-3 a second time consecutively, at the same place, that kills the region already selected.
Double-Mouse-1
This key sets the region around the word which you click on. If you click on a character with "symbol" syntax (such as underscore, in C mode), it sets the region around the symbol surrounding that character. If you click on a character with open-parenthesis or close-parenthesis syntax, it sets the region around the parenthetical grouping (sexp) which that character starts or ends. If you click on a character with string-delimiter syntax (such as a singlequote or doublequote in C), it sets the region around the string constant (using heuristics to figure out whether that character is the beginning or the end of it).
Double-Drag-Mouse-1
This key selects a region made up of the words you drag across.
Triple-Mouse-1
This key sets the region around the line you click on.
Triple-Drag-Mouse-1
This key selects a region made up of the lines you drag across.

The simplest way to kill text with the mouse is to press Mouse-1 at one end, then press Mouse-3 twice at the other end. See section Deletion and Killing. To copy the text into the kill ring without deleting it from the buffer, press Mouse-3 just once--or just drag across the text with Mouse-1. Then you can copy it elsewhere by yanking it.

To yank the killed or copied text somewhere else, move the mouse there and press Mouse-2. See section Yanking. However, if mouse-yank-at-point is non-nil, Mouse-2 yanks at point. Then it does not matter where you click, or even which of the frame's windows you click on. The default value is nil. This variable also affects yanking the secondary selection.

To copy text to another X window, kill it or save it in the kill ring. Under X, this also sets the primary selection. Then use the "paste" or "yank" command of the program operating the other window to insert the text from the selection.

To copy text from another X window, use the "cut" or "copy" command of the program operating the other window, to select the text you want. Then yank it in Emacs with C-y or Mouse-2.

These cutting and pasting commands also work on MS-Windows.

When Emacs puts text into the kill ring, or rotates text to the front of the kill ring, it sets the primary selection in the X server. This is how other X clients can access the text. Emacs also stores the text in the cut buffer, but only if the text is short enough (x-cut-buffer-max specifies the maximum number of characters); putting long strings in the cut buffer can be slow.

The commands to yank the first entry in the kill ring actually check first for a primary selection in another program; after that, they check for text in the cut buffer. If neither of those sources provides text to yank, the kill ring contents are used.

Secondary Selection

The secondary selection is another way of selecting text using X. It does not use point or the mark, so you can use it to kill text without setting point or the mark.

M-Drag-Mouse-1
Set the secondary selection, with one end at the place where you press down the button, and the other end at the place where you release it (mouse-set-secondary). The highlighting appears and changes as you drag. If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse back into the window. This way, you can mark regions that don't fit entirely on the screen.
M-Mouse-1
Set one endpoint for the secondary selection (mouse-start-secondary).
M-Mouse-3
Make a secondary selection, using the place specified with M-Mouse-1 as the other end (mouse-secondary-save-then-kill). A second click at the same place kills the secondary selection just made.
M-Mouse-2
Insert the secondary selection where you click (mouse-yank-secondary). This places point at the end of the yanked text.

Double or triple clicking of M-Mouse-1 operates on words and lines, much like Mouse-1.

If mouse-yank-at-point is non-nil, M-Mouse-2 yanks at point. Then it does not matter precisely where you click; all that matters is which window you click on. See section Mouse Commands for Editing.

Following References with the Mouse

Some Emacs buffers display lists of various sorts. These include lists of files, of buffers, of possible completions, of matches for a pattern, and so on.

Since yanking text into these buffers is not very useful, most of them define Mouse-2 specially, as a command to use or view the item you click on.

For example, if you click Mouse-2 on a file name in a Dired buffer, you visit that file. If you click Mouse-2 on an error message in the `*Compilation*' buffer, you go to the source code for that error message. If you click Mouse-2 on a completion in the `*Completions*' buffer, you choose that completion.

You can usually tell when Mouse-2 has this special sort of meaning because the sensitive text highlights when you move the mouse over it.

Mouse Clicks for Menus

Mouse clicks modified with the CTRL and SHIFT keys bring up menus.

C-Mouse-1
This menu is for selecting a buffer.
C-Mouse-2
This menu is for specifying faces and other text properties for editing formatted text. See section Editing Formatted Text.
C-Mouse-3
This menu is mode-specific. For most modes, this menu has the same items as all the mode-specific menu-bar menus put together. Some modes may specify a different menu for this button.(3)
S-mouse-1
This menu is for specifying the frame's principal font.

Mode Line Mouse Commands

You can use mouse clicks on window mode lines to select and manipulate windows.

Mouse-1
Mouse-1 on a mode line selects the window above. By dragging Mouse-1 on the mode line, you can move it, thus changing the height of the windows above and below.
Mouse-2
Mouse-2 on a mode line expands that window to fill its frame.
Mouse-3
Mouse-3 on a mode line deletes the window above.
C-Mouse-2
C-Mouse-2 on a mode line splits the window above horizontally, above the place in the mode line where you click.

C-Mouse-2 on a scroll bar splits the corresponding window vertically. See section Splitting Windows.

Creating Frames

The prefix key C-x 5 is analogous to C-x 4, with parallel subcommands. The difference is that C-x 5 commands create a new frame rather than just a new window in the selected frame (see section Displaying in Another Window). If an existing visible or iconified frame already displays the requested material, these commands use the existing frame, after raising or deiconifying as necessary.

The various C-x 5 commands differ in how they find or create the buffer to select:

C-x 5 2
Create a new frame (make-frame-command).
C-x 5 b bufname RET
Select buffer bufname in another frame. This runs switch-to-buffer-other-frame.
C-x 5 f filename RET
Visit file filename and select its buffer in another frame. This runs find-file-other-frame. See section Visiting Files.
C-x 5 d directory RET
Select a Dired buffer for directory directory in another frame. This runs dired-other-frame. See section Dired, the Directory Editor.
C-x 5 m
Start composing a mail message in another frame. This runs mail-other-frame. It is the other-frame variant of C-x m. See section Sending Mail.
C-x 5 .
Find a tag in the current tag table in another frame. This runs find-tag-other-frame, the multiple-frame variant of M-.. See section Tags Tables.
C-x 5 r filename RET
Visit file filename read-only, and select its buffer in another frame. This runs find-file-read-only-other-frame. See section Visiting Files.

You can control the appearance of new frames you create by setting the frame parameters in default-frame-alist. You can use the variable initial-frame-alist to specify parameters that affect only the initial frame. See section `Initial Parameters' in The Emacs Lisp Reference Manual, for more information.

The easiest way to specify the principal font for all your Emacs frames is with an X resource (see section Font Specification Options), but you can also do it by modifying default-frame-alist to specify the font parameter, as shown here:

(add-to-list 'default-frame-alist '(font . "10x20"))

Making and Using a Speedbar Frame

An Emacs frame can have a speedbar, which is a vertical window that serves as a scrollable menu of files you could visit and tags within those files. To create a speedbar, type M-x speedbar; this creates a speedbar window for the selected frame. From then on, you can click on a file name in the speedbar to visit that file in the corresponding Emacs frame, or click on a tag name to jump to that tag in the Emacs frame.

Initially the speedbar lists the immediate contents of the current directory, one file per line. Each line also has a box, `[+]' or `<+>', that you can click on with Mouse-2 to "open up" the contents of that item. If the line names a directory, opening it adds the contents of that directory to the speedbar display, underneath the directory's own line. If the line lists an ordinary file, opening it up adds a list of the tags in that file to the speedbar display. When a file is opened up, the `[+]' changes to `[-]'; you can click on that box to "close up" that file (hide its contents).

Some major modes, including Rmail mode, Info, and GUD, have specialized ways of putting useful items into the speedbar for you to select. For example, in Rmail mode, the speedbar shows a list of Rmail files, and lets you move the current message to another Rmail file by clicking on its `<M>' box.

A speedbar belongs to one Emacs frame, and always operates on that frame. If you use multiple frames, you can make a speedbar for some or all of the frames; type M-x speedbar in any given frame to make a speedbar for it.

Multiple Displays

A single Emacs can talk to more than one X Windows display. Initially, Emacs uses just one display--the one specified with the DISPLAY environment variable or with the `--display' option (see section Initial Options). To connect to another display, use the command make-frame-on-display:

M-x make-frame-on-display RET display RET
Create a new frame on display display.

A single X server can handle more than one screen. When you open frames on two screens belonging to one server, Emacs knows they share a single keyboard, and it treats all the commands arriving from these screens as a single stream of input.

When you open frames on different X servers, Emacs makes a separate input stream for each server. This way, two users can type simultaneously on the two displays, and Emacs will not garble their input. Each server also has its own selected frame. The commands you enter with a particular X server apply to that server's selected frame.

Despite these features, people using the same Emacs job from different displays can still interfere with each other if they are not careful. For example, if any one types C-x C-c, that exits the Emacs job for all of them!

Special Buffer Frames

You can make certain chosen buffers, for which Emacs normally creates a second window when you have just one window, appear in special frames of their own. To do this, set the variable special-display-buffer-names to a list of buffer names; any buffer whose name is in that list automatically gets a special frame, when an Emacs command wants to display it "in another window."

For example, if you set the variable this way,

(setq special-display-buffer-names
      '("*Completions*" "*grep*" "*tex-shell*"))

then completion lists, grep output and the TeX mode shell buffer get individual frames of their own. These frames, and the windows in them, are never automatically split or reused for any other buffers. They continue to show the buffers they were created for, unless you alter them by hand. Killing the special buffer deletes its frame automatically.

More generally, you can set special-display-regexps to a list of regular expressions; then a buffer gets its own frame if its name matches any of those regular expressions. (Once again, this applies only to buffers that normally get displayed for you in a separate window.)

The variable special-display-frame-alist specifies the frame parameters for these frames. It has a default value, so you don't need to set it.

For those who know Lisp, an element of special-display-buffer-names or special-display-regexps can also be a list. Then the first element is the buffer name or regular expression; the rest of the list specifies how to create the frame. It can be an association list specifying frame parameter values; these values take precedence over parameter values specified in special-display-frame-alist. Alternatively, it can have this form:

(function args...)

where function is a symbol. Then the frame is constructed by calling function; its first argument is the buffer, and its remaining arguments are args.

An analogous feature lets you specify buffers which should be displayed in the selected window. See section Forcing Display in the Same Window. The same-window feature takes precedence over the special-frame feature; therefore, if you add a buffer name to special-display-buffer-names and it has no effect, check to see whether that feature is also in use for the same buffer name.

Setting Frame Parameters

This section describes commands for altering the display style and window management behavior of the selected frame.

M-x set-foreground-color RET color RET
Specify color color for the foreground of the selected frame.
M-x set-background-color RET color RET
Specify color color for the background of the selected frame. This changes the foreground color of the modeline face also, so that it remains in inverse video compared with the default.
M-x set-cursor-color RET color RET
Specify color color for the cursor of the selected frame.
M-x set-mouse-color RET color RET
Specify color color for the mouse cursor when it is over the selected frame.
M-x set-border-color RET color RET
Specify color color for the border of the selected frame.
M-x list-colors-display
Display the defined color names and show what the colors look like. This command is somewhat slow.
M-x auto-raise-mode
Toggle whether or not the selected frame should auto-raise. Auto-raise means that every time you move the mouse onto the frame, it raises the frame. Note that this auto-raise feature is implemented by Emacs itself. Some window managers also implement auto-raise. If you enable auto-raise for Emacs frames in your X window manager, it should work, but it is beyond Emacs's control and therefore auto-raise-mode has no effect on it.
M-x auto-lower-mode
Toggle whether or not the selected frame should auto-lower. Auto-lower means that every time you move the mouse off the frame, the frame moves to the bottom of the stack of X windows. The command auto-lower-mode has no effect on auto-lower implemented by the X window manager. To control that, you must use the appropriate window manager features.
M-x set-frame-font RET font RET
Specify font font as the principal font for the selected frame. The principal font is used for all text displayed in the frame, except when a face (see section Using Multiple Typefaces) specifies a different font to use for certain text. See section Font Specification Options, for ways to list the available fonts on your system. You can also set a frame's principal font through a pop-up menu. Press S-Mouse-1 to activate this menu.

In Emacs versions that use an X toolkit, the color-setting and font-setting functions don't affect menus and the menu bar, since they are displayed by their own widget classes. To change the appearance of the menus and menu bar, you must use X resources (see section X Resources). See section Window Color Options, regarding colors. See section Font Specification Options, regarding choice of font.

For information on frame parameters and customization, see section `Frame Parameters' in The Emacs Lisp Reference Manual.

Scroll Bars

When using X, Emacs normally makes a scroll bar at the left of each Emacs window. The scroll bar runs the height of the window, and shows a moving rectangular inner box which represents the portion of the buffer currently displayed. The entire height of the scroll bar represents the entire length of the buffer.

You can use Mouse-2 (normally, the middle button) in the scroll bar to move or drag the inner box up and down. If you move it to the top of the scroll bar, you see the top of the buffer. If you move it to the bottom of the scroll bar, you see the bottom of the buffer.

The left and right buttons in the scroll bar scroll by controlled increments. Mouse-1 (normally, the left button) moves the line at the level where you click up to the top of the window. Mouse-3 (normally, the right button) moves the line at the top of the window down to the level where you click. By clicking repeatedly in the same place, you can scroll by the same distance over and over.

Aside from scrolling, you can also click C-Mouse-2 in the scroll bar to split a window vertically. The split occurs on the line where you click.

You can enable or disable Scroll Bar mode with the command M-x scroll-bar-mode. With no argument, it toggles the use of scroll bars. With an argument, it turns use of scroll bars on if and only if the argument is positive. This command applies to all frames, including frames yet to be created. You can use the X resource `verticalScrollBars' to control the initial setting of Scroll Bar mode. See section X Resources.

To enable or disable scroll bars for just the selected frame, use the M-x toggle-scroll-bar command.

Menu Bars

You can turn display of menu bars on or off with M-x menu-bar-mode. With no argument, this command toggles Menu Bar mode, a minor mode. With an argument, the command turns Menu Bar mode on if the argument is positive, off if the argument is not positive. You can use the X resource `menuBarLines' to control the initial setting of Menu Bar mode. See section X Resources. Expert users often turn off the menu bar, especially on text-only terminals, where this makes one additional line available for text.

See section The Menu Bar, for information on how to invoke commands with the menu bar.

Using Multiple Typefaces

When using Emacs with X, you can set up multiple styles of displaying characters. The aspects of style that you can control are the type font, the foreground color, the background color, and whether to underline. Emacs on MS-DOS supports faces partially by letting you control the foreground and background colors of each face (see section Emacs and MS-DOS).

The way you control display style is by defining named faces. Each face can specify a type font, a foreground color, a background color, and an underline flag; but it does not have to specify all of them. Then by specifying the face or faces to use for a given part of the text in the buffer, you control how that text appears.

The style of display used for a given character in the text is determined by combining several faces. Any aspect of the display style that isn't specified by overlays or text properties comes from the frame itself.

Enriched mode, the mode for editing formatted text, includes several commands and menus for specifying faces. See section Faces in Formatted Text, for how to specify the font for text in the buffer. See section Colors in Formatted Text, for how to specify the foreground and background color.

To alter the appearance of a face, use the customization buffer. See section Customizing Faces. You can also use X resources to specify attributes of particular faces (see section X Resources).

To see what faces are currently defined, and what they look like, type M-x list-faces-display. It's possible for a given face to look different in different frames; this command shows the appearance in the frame in which you type it. Here's a list of the standardly defined faces:

default
This face is used for ordinary text that doesn't specify any other face.
modeline
This face is used for mode lines. By default, it's set up as the inverse of the default face. See section Variables Controlling Display.
highlight
This face is used for highlighting portions of text, in various modes.
region
This face is used for displaying a selected region (when Transient Mark mode is enabled--see below).
secondary-selection
This face is used for displaying a secondary selection (see section Secondary Selection).
bold
This face uses a bold variant of the default font, if it has one.
italic
This face uses an italic variant of the default font, if it has one.
bold-italic
This face uses a bold italic variant of the default font, if it has one.
underline
This face underlines text.

When Transient Mark mode is enabled, the text of the region is highlighted when the mark is active. This uses the face named region; you can control the style of highlighting by changing the style of this face (see section Customizing Faces). See section Transient Mark Mode, for more information about Transient Mark mode and activation and deactivation of the mark.

One easy way to use faces is to turn on Font Lock mode. This minor mode, which is always local to a particular buffer, arranges to choose faces according to the syntax of the text you are editing. It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs. See section Font Lock mode, for more information about Font Lock mode and syntactic highlighting.

You can print out the buffer with the highlighting that appears on your screen using the command ps-print-buffer-with-faces. See section Postscript Hardcopy.

Font Lock mode

Font Lock mode is a minor mode, always local to a particular buffer, which highlights (or "fontifies") using various faces according to the syntax of the text you are editing. It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs--for example, names of functions being defined or reserved keywords.

The command M-x font-lock-mode turns Font Lock mode on or off according to the argument, and toggles the mode when it has no argument. The function turn-on-font-lock unconditionally enables Font Lock mode. This is useful in mode-hook functions. For example, to enable Font Lock mode whenever you edit a C file, you can do this:

(add-hook 'c-mode-hook 'turn-on-font-lock)

To turn on Font Lock mode automatically in all modes which support it, use the function global-font-lock-mode, like this:

(global-font-lock-mode 1)

In Font Lock mode, when you edit the text, the highlighting updates automatically in the line that you changed. Most changes don't affect the highlighting of subsequent lines, but occasionally they do. To rehighlight a range of lines, use the command M-g M-g (font-lock-fontify-block).

In certain major modes, M-g M-g refontifies the entire current function. (The variable font-lock-mark-block-function controls how to find the current function.) In other major modes, M-g M-g refontifies 16 lines above and below point.

With a prefix argument n, M-g M-g refontifies n lines above and below point, regardless of the mode.

To get the full benefit of Font Lock mode, you need to choose a default font which has bold, italic, and bold-italic variants; or else you need to have a color or gray-scale screen.

The variable font-lock-maximum-decoration specifies the preferred level of fontification, for modes that provide multiple levels. Level 1 is the least amount of fontification; some modes support levels as high as 3. The normal default is "as high as possible." You can specify an integer, which applies to all modes, or you can specify different numbers for particular major modes; for example, to use level 1 for C/C++ modes, and the default level otherwise, use this:

(setq font-lock-maximum-decoration
      '((c-mode . 1) (c++-mode . 1)))

Fontification can be too slow for large buffers, so you can suppress it. The variable font-lock-maximum-size specifies a buffer size, beyond which buffer fontification is suppressed.

Comment and string fontification (or "syntactic" fontification) relies on analysis of the syntactic structure of the buffer text. For the purposes of speed, some modes including C mode and Lisp mode rely on a special convention: an open-parenthesis in the leftmost column always defines the beginning of a defun, and is thus always outside any string or comment. (See section Defuns.) If you don't follow this convention, then Font Lock mode can misfontify the text after an open-parenthesis in the leftmost column that is inside a string or comment.

The variable font-lock-beginning-of-syntax-function (always buffer-local) specifies how Font Lock mode can find a position guaranteed to be outside any comment or string. In modes which use the leftmost column parenthesis convention, the default value of the variable is beginning-of-defun---that tells Font Lock mode to use the convention. If you set this variable to nil, Font Lock no longer relies on the convention. This avoids incorrect results, but the price is that, in some cases, fontification for a changed text must rescan buffer text from the beginning of the buffer.

Font Lock highlighting patterns already exist for many modes, but you may want to fontify additional patterns. You can use the function font-lock-add-keywords, to add your own highlighting patterns for a particular mode. For example, to highlight `FIXME:' words in C comments, use this:

(font-lock-add-keywords
 'c-mode
 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))

Font Lock Support Modes

Font Lock support modes make Font Lock mode faster for large buffers. There are two support modes: Fast Lock mode and Lazy Lock mode. They use two different methods of speeding up Font Lock mode.

Fast Lock Mode

To make Font Lock mode faster for buffers visiting large files, you can use Fast Lock mode. Fast Lock mode saves the font information for each file in a separate cache file; each time you visit the file, it rereads the font information from the cache file instead of refontifying the text from scratch.

The command M-x fast-lock-mode turns Fast Lock mode on or off, according to the argument (with no argument, it toggles). You can also arrange to enable Fast Lock mode whenever you use Font Lock mode, like this:

(setq font-lock-support-mode 'fast-lock-mode)

It is not worth writing a cache file for small buffers. Therefore, the variable fast-lock-minimum-size specifies a minimum file size for caching font information.

The variable fast-lock-cache-directories specifies where to put the cache files. Its value is a list of directories to try; "." means the same directory as the file being edited. The default value is ("." "~/.emacs-flc"), which means to use the same directory if possible, and otherwise the directory `~/.emacs-flc'.

The variable fast-lock-save-others specifies whether Fast Lock mode should save cache files for files that you do not own. A non-nil value means yes (and that is the default).

Lazy Lock Mode

To make Font Lock mode faster for large buffers, you can use Lazy Lock mode to reduce the amount of text that is fontified. In Lazy Lock mode, buffer fontification is demand-driven; it happens to portions of the buffer that are about to be displayed. And fontification of your changes is deferred; it happens only when Emacs has been idle for a certain short period of time.

The command M-x lazy-lock-mode turns Lazy Lock mode on or off, according to the argument (with no argument, it toggles). You can also arrange to enable Lazy Lock mode whenever you use Font Lock mode, like this:

(setq font-lock-support-mode 'lazy-lock-mode)

It is not worth avoiding buffer fontification for small buffers. Therefore, the variable lazy-lock-minimum-size specifies a minimum buffer size for demand-driven buffer fontification. Buffers smaller than that are fontified all at once, as in plain Font Lock mode.

When you alter the buffer, Lazy Lock mode defers fontification of the text you changed. The variable lazy-lock-defer-time specifies how many seconds Emacs must be idle before it starts fontifying your changes. If the value is 0, then changes are fontified immediately, as in plain Font Lock mode.

Lazy Lock mode normally fontifies newly visible portions of the buffer before they are first displayed. However, if the value of lazy-lock-defer-on-scrolling is non-nil, newly visible text is fontified only when Emacs is idle for lazy-lock-defer-time seconds.

In some modes, including C mode and Emacs Lisp mode, changes in one line's contents can alter the context for subsequent lines, and thus change how they ought to be fontified. Ordinarily, you must type M-g M-g to refontify the subsequent lines. However, if you set the variable lazy-lock-defer-contextually to non-nil, Lazy Lock mode does this automatically, after lazy-lock-defer-time seconds.

When Emacs is idle for a long time, Lazy Lock fontifies additional portions of the buffer, not yet displayed, in case you will display them later. This is called stealth fontification.

The variable lazy-lock-stealth-time specifies how many seconds Emacs has to be idle before stealth fontification starts. A value of nil means no stealth fontification. The variables lazy-lock-stealth-lines and lazy-lock-stealth-verbose specify the granularity and verbosity of stealth fontification.

Fast Lock or Lazy Lock?

Here is a simple guide to help you choose one of the Font Lock support modes.

  • Fast Lock mode intervenes only during file visiting and buffer killing (and related events); therefore buffer editing and window scrolling are no faster or slower than in plain Font Lock mode.
  • Fast Lock mode is slower at reading a cache file than Lazy Lock mode is at fontifying a window; therefore Fast Lock mode is slower at visiting a file than Lazy Lock mode.
  • Lazy Lock mode intervenes during window scrolling to fontify text that scrolls onto the screen; therefore, scrolling is slower than in plain Font Lock mode.
  • Lazy Lock mode doesn't fontify during buffer editing (it defers fontification of changes); therefore, editing is faster than in plain Font Lock mode.
  • Fast Lock mode can be fooled by a file that is kept under version control software; therefore buffer fontification may occur even when a cache file exists for the file.
  • Fast Lock mode only works with a buffer visiting a file; Lazy Lock mode works with any buffer.
  • Fast Lock mode generates cache files; Lazy Lock mode does not.

The variable font-lock-support-mode specifies which of these support modes to use; for example, to specify that Fast Lock mode is used for C/C++ modes, and Lazy Lock mode otherwise, set the variable like this:

(setq font-lock-support-mode
      '((c-mode . fast-lock-mode) (c++-mode . fast-lock-mode)
        (t . lazy-lock-mode)))

Highlight Changes Mode

Use M-x highlight-changes-mode to enable a minor mode that uses faces (colors, typically) to indicate which parts of the buffer were changed most recently.

Miscellaneous X Window Features

The following commands let you create, delete and operate on frames:

C-z
Iconify the selected Emacs frame (iconify-or-deiconify-frame). The normal meaning of C-z, to suspend Emacs, is not useful under a window system, so it has a different binding in that case. If you type this command on an Emacs frame's icon, it deiconifies the frame.
C-x 5 0
Delete the selected frame (delete-frame). This is not allowed if there is only one frame.
C-x 5 o
Select another frame, raise it, and warp the mouse to it so that it stays selected. If you repeat this command, it cycles through all the frames on your terminal.

Non-Window Terminals

If your terminal does not have a window system that Emacs supports, then it can display only one Emacs frame at a time. However, you can still create multiple Emacs frames, and switch between them. Switching frames on these terminals is much like switching between different window configurations.

Use C-x 5 2 to create a new frame and switch to it; use C-x 5 o to cycle through the existing frames; use C-x 5 0 to delete the current frame.

Each frame has a number to distinguish it. If your terminal can display only one frame at a time, the selected frame's number n appears near the beginning of the mode line, in the form `Fn'.

`Fn' is actually the frame's name. You can also specify a different name if you wish, and you can select a frame by its name. Use the command M-x set-frame-name RET name RET to specify a new name for the selected frame, and use M-x select-frame-by-name RET name RET to select a frame according to its name. The name you specify appears in the mode line when the frame is selected.

International Character Set Support

Emacs supports a wide variety of international character sets, including European variants of the Latin alphabet, as well as Chinese, Devanagari (Hindi and Marathi), Ethiopian, Greek, IPA, Japanese, Korean, Lao, Russian, Thai, Tibetan, and Vietnamese scripts. These features have been merged from the modified version of Emacs known as MULE (for "MULti-lingual Enhancement to GNU Emacs")

Introduction to International Character Sets

The users of these scripts have established many more-or-less standard coding systems for storing files. Emacs internally uses a single multibyte character encoding, so that it can intermix characters from all these scripts in a single buffer or string. This encoding represents each non-ASCII character as a sequence of bytes in the range 0200 through 0377. Emacs translates between the multibyte character encoding and various other coding systems when reading and writing files, when exchanging data with subprocesses, and (in some cases) in the C-q command (see section Unibyte and Multibyte Non-ASCII characters).

The command C-h h (view-hello-file) displays the file `etc/HELLO', which shows how to say "hello" in many languages. This illustrates various scripts.

Keyboards, even in the countries where these character sets are used, generally don't have keys for all the characters in them. So Emacs supports various input methods, typically one for each script or language, to make it convenient to type them.

The prefix key C-x RET is used for commands that pertain to multibyte characters, coding systems, and input methods.

Enabling Multibyte Characters

You can enable or disable multibyte character support, either for Emacs as a whole, or for a single buffer. When multibyte characters are disabled in a buffer, then each byte in that buffer represents a character, even codes 0200 through 0377. The old features for supporting the European character sets, ISO Latin-1 and ISO Latin-2, work as they did in Emacs 19 and also work for the other ISO 8859 character sets.

However, there is no need to turn off multibyte character support to use ISO Latin; the Emacs multibyte character set includes all the characters in these character sets, and Emacs can translate automatically to and from the ISO codes.

To edit a particular file in unibyte representation, visit it using find-file-literally. See section Visiting Files. To convert a buffer in multibyte representation into a single-byte representation of the same characters, the easiest way is to save the contents in a file, kill the buffer, and find the file again with find-file-literally. You can also use C-x RET c (universal-coding-system-argument) and specify `raw-text' as the coding system with which to find or save a file. See section Specifying a Coding System. Finding a file as `raw-text' doesn't disable format conversion, uncompression and auto mode selection as find-file-literally does.

To turn off multibyte character support by default, start Emacs with the `--unibyte' option (see section Initial Options), or set the environment variable `EMACS_UNIBYTE'. You can also customize enable-multibyte-characters or, equivalently, directly set the variable default-enable-multibyte-characters in your init file to have basically the same effect as `--unibyte'.

Multibyte strings are not created during initialization from the values of environment variables, `/etc/passwd' entries etc. that contain non-ASCII 8-bit characters. However, the initialization file is normally read as multibyte--like Lisp files in general--even with `--unibyte'. To avoid multibyte strings being generated by non-ASCII characters in it, put `-*-unibyte: t;-*-' in a comment on the first line. Do the same for initialization files for packages like Gnus.

The mode line indicates whether multibyte character support is enabled in the current buffer. If it is, there are two or more characters (most often two dashes) before the colon near the beginning of the mode line. When multibyte characters are not enabled, just one dash precedes the colon.

Language Environments

All supported character sets are supported in Emacs buffers whenever multibyte characters are enabled; there is no need to select a particular language in order to display its characters in an Emacs buffer. However, it is important to select a language environment in order to set various defaults. The language environment really represents a choice of preferred script (more or less) rather than a choice of language.

The language environment controls which coding systems to recognize when reading text (see section Recognizing Coding Systems). This applies to files, incoming mail, netnews, and any other text you read into Emacs. It may also specify the default coding system to use when you create a file. Each language environment also specifies a default input method.

The way to select a language environment is with the command M-x set-language-environment. It makes no difference which buffer is current when you use this command, because the effects apply globally to the Emacs session. The supported language environments include:

Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-Alternativnyj, Cyrillic-ISO, Cyrillic-KOI8, Devanagari, English, Ethiopic, Greek, Hebrew, Japanese, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Thai, Tibetan, and Vietnamese.

Some operating systems let you specify the language you are using by setting locale environment variables. Emacs handles one common special case of this: if your locale name for character types contains the string `8859-n', Emacs automatically selects the corresponding language environment.

To display information about the effects of a certain language environment lang-env, use the command C-h L lang-env RET (describe-language-environment). This tells you which languages this language environment is useful for, and lists the character sets, coding systems, and input methods that go with it. It also shows some sample text to illustrate scripts used in this language environment. By default, this command describes the chosen language environment.

You can customize any language environment with the normal hook set-language-environment-hook. The command set-language-environment runs that hook after setting up the new language environment. The hook functions can test for a specific language environment by checking the variable current-language-environment.

Before it starts to set up the new language environment, set-language-environment first runs the hook exit-language-environment-hook. This hook is useful for undoing customizations that were made with set-language-environment-hook. For instance, if you set up a special key binding in a specific language environment using set-language-environment-hook, you should set up exit-language-environment-hook to restore the normal binding for that key.

Input Methods

An input method is a kind of character conversion designed specifically for interactive input. In Emacs, typically each language has its own input method; sometimes several languages which use the same characters can share one input method. A few languages support several input methods.

The simplest kind of input method works by mapping ASCII letters into another alphabet. This is how the Greek and Russian input methods work.

A more powerful technique is composition: converting sequences of characters into one letter. Many European input methods use composition to produce a single non-ASCII letter from a sequence that consists of a letter followed by accent characters (or vice versa). For example, some methods convert the sequence a' into a single accented letter. These input methods have no special commands of their own; all they do is compose sequences of printing characters.

The input methods for syllabic scripts typically use mapping followed by composition. The input methods for Thai and Korean work this way. First, letters are mapped into symbols for particular sounds or tone marks; then, sequences of these which make up a whole syllable are mapped into one syllable sign.

Chinese and Japanese require more complex methods. In Chinese input methods, first you enter the phonetic spelling of a Chinese word (in input method chinese-py, among others), or a sequence of portions of the character (input methods chinese-4corner and chinese-sw, and others). Since one phonetic spelling typically corresponds to many different Chinese characters, you must select one of the alternatives using special Emacs commands. Keys such as C-f, C-b, C-n, C-p, and digits have special definitions in this situation, used for selecting among the alternatives. TAB displays a buffer showing all the possibilities.

In Japanese input methods, first you input a whole word using phonetic spelling; then, after the word is in the buffer, Emacs converts it into one or more characters using a large dictionary. One phonetic spelling corresponds to many differently written Japanese words, so you must select one of them; use C-n and C-p to cycle through the alternatives.

Sometimes it is useful to cut off input method processing so that the characters you have just entered will not combine with subsequent characters. For example, in input method latin-1-postfix, the sequence e ' combines to form an `e' with an accent. What if you want to enter them as separate characters?

One way is to type the accent twice; that is a special feature for entering the separate letter and accent. For example, e ' ' gives you the two characters `e''. Another way is to type another letter after the e---something that won't combine with that--and immediately delete it. For example, you could type e e DEL ' to get separate `e' and `''.

Another method, more general but not quite as easy to type, is to use C-\ C-\ between two characters to stop them from combining. This is the command C-\ (toggle-input-method) used twice.

C-\ C-\ is especially useful inside an incremental search, because it stops waiting for more characters to combine, and starts searching for what you have already entered.

The variables input-method-highlight-flag and input-method-verbose-flag control how input methods explain what is happening. If input-method-highlight-flag is non-nil, the partial sequence is highlighted in the buffer. If input-method-verbose-flag is non-nil, the list of possible characters to type next is displayed in the echo area (but not when you are in the minibuffer).

Selecting an Input Method

C-\
Enable or disable use of the selected input method.
C-x RET C-\ method RET
Select a new input method for the current buffer.
C-h I method RET
C-h C-\ method RET
Describe the input method method (describe-input-method). By default, it describes the current input method (if any). This description should give you the full details of how to use any particular input method.
M-x list-input-methods
Display a list of all the supported input methods.

To choose an input method for the current buffer, use C-x RET C-\ (set-input-method). This command reads the input method name with the minibuffer; the name normally starts with the language environment that it is meant to be used with. The variable current-input-method records which input method is selected. Input methods use various sequences of ASCII characters to stand for non-ASCII characters. Sometimes it is useful to turn off the input method temporarily. To do this, type C-\ (toggle-input-method). To reenable the input method, type C-\ again.

If you type C-\ and you have not yet selected an input method, it prompts for you to specify one. This has the same effect as using C-x RET C-\ to specify an input method.

Selecting a language environment specifies a default input method for use in various buffers. When you have a default input method, you can select it in the current buffer by typing C-\. The variable default-input-method specifies the default input method (nil means there is none).

Some input methods for alphabetic scripts work by (in effect) remapping the keyboard to emulate various keyboard layouts commonly used for those scripts. How to do this remapping properly depends on your actual keyboard layout. To specify which layout your keyboard has, use the command M-x quail-set-keyboard-layout.

To display a list of all the supported input methods, type M-x list-input-methods. The list gives information about each input method, including the string that stands for it in the mode line.

Unibyte and Multibyte Non-ASCII characters

When multibyte characters are enabled, character codes 0240 (octal) through 0377 (octal) are not really legitimate in the buffer. The valid non-ASCII printing characters have codes that start from 0400.

If you type a self-inserting character in the invalid range 0240 through 0377, Emacs assumes you intended to use one of the ISO Latin-n character sets, and converts it to the Emacs code representing that Latin-n character. You select which ISO Latin character set to use through your choice of language environment (see above). If you do not specify a choice, the default is Latin-1.

The same thing happens when you use C-q to enter an octal code in this range.

Coding Systems

Users of various languages have established many more-or-less standard coding systems for representing them. Emacs does not use these coding systems internally; instead, it converts from various coding systems to its own system when reading data, and converts the internal coding system to other coding systems when writing data. Conversion is possible in reading or writing files, in sending or receiving from the terminal, and in exchanging data with subprocesses.

Emacs assigns a name to each coding system. Most coding systems are used for one language, and the name of the coding system starts with the language name. Some coding systems are used for several languages; their names usually start with `iso'. There are also special coding systems no-conversion, raw-text and emacs-mule which do not convert printing characters at all.

In addition to converting various representations of non-ASCII characters, a coding system can perform end-of-line conversion. Emacs handles three different conventions for how to separate lines in a file: newline, carriage-return linefeed, and just carriage-return.

C-h C coding RET
Describe coding system coding.
C-h C RET
Describe the coding systems currently in use.
M-x list-coding-systems
Display a list of all the supported coding systems.

The command C-h C (describe-coding-system) displays information about particular coding systems. You can specify a coding system name as argument; alternatively, with an empty argument, it describes the coding systems currently selected for various purposes, both in the current buffer and as the defaults, and the priority list for recognizing coding systems (see section Recognizing Coding Systems).

To display a list of all the supported coding systems, type M-x list-coding-systems. The list gives information about each coding system, including the letter that stands for it in the mode line (see section The Mode Line).

Each of the coding systems that appear in this list--except for no-conversion, which means no conversion of any kind--specifies how and whether to convert printing characters, but leaves the choice of end-of-line conversion to be decided based on the contents of each file. For example, if the file appears to use the sequence carriage-return linefeed to separate lines, DOS end-of-line conversion will be used.

Each of the listed coding systems has three variants which specify exactly what to do for end-of-line conversion:

...-unix
Don't do any end-of-line conversion; assume the file uses newline to separate lines. (This is the convention normally used on Unix and GNU systems.)
...-dos
Assume the file uses carriage-return linefeed to separate lines, and do the appropriate conversion. (This is the convention normally used on Microsoft systems.(4))
...-mac
Assume the file uses carriage-return to separate lines, and do the appropriate conversion. (This is the convention normally used on the Macintosh system.)

These variant coding systems are omitted from the list-coding-systems display for brevity, since they are entirely predictable. For example, the coding system iso-latin-1 has variants iso-latin-1-unix, iso-latin-1-dos and iso-latin-1-mac.

The coding system raw-text is good for a file which is mainly ASCII text, but may contain byte values above 127 which are not meant to encode non-ASCII characters. With raw-text, Emacs copies those byte values unchanged, and sets enable-multibyte-characters to nil in the current buffer so that they will be interpreted properly. raw-text handles end-of-line conversion in the usual way, based on the data encountered, and has the usual three variants to specify the kind of end-of-line conversion to use.

In contrast, the coding system no-conversion specifies no character code conversion at all--none for non-ASCII byte values and none for end of line. This is useful for reading or writing binary files, tar files, and other files that must be examined verbatim. It, too, sets enable-multibyte-characters to nil.

The easiest way to edit a file with no conversion of any kind is with the M-x find-file-literally command. This uses no-conversion, and also suppresses other Emacs features that might convert the file contents before you see them. See section Visiting Files.

The coding system emacs-mule means that the file contains non-ASCII characters stored with the internal Emacs encoding. It handles end-of-line conversion based on the data encountered, and has the usual three variants to specify the kind of end-of-line conversion.

Recognizing Coding Systems

Most of the time, Emacs can recognize which coding system to use for any given file--once you have specified your preferences.

Some coding systems can be recognized or distinguished by which byte sequences appear in the data. However, there are coding systems that cannot be distinguished, not even potentially. For example, there is no way to distinguish between Latin-1 and Latin-2; they use the same byte values with different meanings.

Emacs handles this situation by means of a priority list of coding systems. Whenever Emacs reads a file, if you do not specify the coding system to use, Emacs checks the data against each coding system, starting with the first in priority and working down the list, until it finds a coding system that fits the data. Then it converts the file contents assuming that they are represented in this coding system.

The priority list of coding systems depends on the selected language environment (see section Language Environments). For example, if you use French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use Czech, you probably want Latin-2 to be preferred. This is one of the reasons to specify a language environment.

However, you can alter the priority list in detail with the command M-x prefer-coding-system. This command reads the name of a coding system from the minibuffer, and adds it to the front of the priority list, so that it is preferred to all others. If you use this command several times, each use adds one element to the front of the priority list.

If you use a coding system that specifies the end-of-line conversion type, such as iso-8859-1-dos, what that means is that Emacs should attempt to recognize iso-8859-1 with priority, and should use DOS end-of-line conversion in case it recognizes iso-8859-1.

Sometimes a file name indicates which coding system to use for the file. The variable file-coding-system-alist specifies this correspondence. There is a special function modify-coding-system-alist for adding elements to this list. For example, to read and write all `.txt' files using the coding system china-iso-8bit, you can execute this Lisp expression:

(modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)

The first argument should be file, the second argument should be a regular expression that determines which files this applies to, and the third argument says which coding system to use for these files.

Emacs recognizes which kind of end-of-line conversion to use based on the contents of the file: if it sees only carriage-returns, or only carriage-return linefeed sequences, then it chooses the end-of-line conversion accordingly. You can inhibit the automatic use of end-of-line conversion by setting the variable inhibit-eol-conversion to non-nil.

You can specify the coding system for a particular file using the `-*-...-*-' construct at the beginning of a file, or a local variables list at the end (see section Local Variables in Files). You do this by defining a value for the "variable" named coding. Emacs does not really have a variable coding; instead of setting a variable, it uses the specified coding system for the file. For example, `-*-mode: C; coding: latin-1;-*-' specifies use of the Latin-1 coding system, as well as C mode. If you specify the coding explicitly in the file, that overrides file-coding-system-alist.

The variable auto-coding-alist is the strongest way to specify the coding system for certain patterns of file names; this variable even overrides `-*-coding:-*-' tags in the file itself. Emacs uses this feature for tar and archive files, to prevent Emacs from being confused by a `-*-coding:-*-' tag in a member of the archive and thinking it applies to the archive file as a whole.

Once Emacs has chosen a coding system for a buffer, it stores that coding system in buffer-file-coding-system and uses that coding system, by default, for operations that write from this buffer into a file. This includes the commands save-buffer and write-region. If you want to write files from this buffer using a different coding system, you can specify a different coding system for the buffer using set-buffer-file-coding-system (see section Specifying a Coding System).

When you send a message with Mail mode (see section Sending Mail), Emacs has four different ways to determine the coding system to use for encoding the message text. It tries the buffer's own value of buffer-file-coding-system, if that is non-nil. Otherwise, it uses the value of sendmail-coding-system, if that is non-nil. The third way is to use the default coding system for new files, which is controlled by your choice of language environment, if that is non-nil. If all of these three values are nil, Emacs encodes outgoing mail using the Latin-1 coding system.

When you get new mail in Rmail, each message is translated automatically from the coding system it is written in--as if it were a separate file. This uses the priority list of coding systems that you have specified. If a MIME message specifies a character set, Rmail obeys that specification, unless rmail-decode-mime-charset is nil.

For reading and saving Rmail files themselves, Emacs uses the coding system specified by the variable rmail-file-coding-system. The default value is nil, which means that Rmail files are not translated (they are read and written in the Emacs internal character code).

Specifying a Coding System

In cases where Emacs does not automatically choose the right coding system, you can use these commands to specify one:

C-x RET f coding RET
Use coding system coding for the visited file in the current buffer.
C-x RET c coding RET
Specify coding system coding for the immediately following command.
C-x RET k coding RET
Use coding system coding for keyboard input.
C-x RET t coding RET
Use coding system coding for terminal output.
C-x RET p input-coding RET output-coding RET
Use coding systems input-coding and output-coding for subprocess input and output in the current buffer.
C-x RET x coding RET
Use coding system coding for transferring selections to and from other programs through the window system.
C-x RET X coding RET
Use coding system coding for transferring one selection--the next one--to or from the window system.

The command C-x RET f (set-buffer-file-coding-system) specifies the file coding system for the current buffer--in other words, which coding system to use when saving or rereading the visited file. You specify which coding system using the minibuffer. Since this command applies to a file you have already visited, it affects only the way the file is saved.

Another way to specify the coding system for a file is when you visit the file. First use the command C-x RET c (universal-coding-system-argument); this command uses the minibuffer to read a coding system name. After you exit the minibuffer, the specified coding system is used for the immediately following command.

So if the immediately following command is C-x C-f, for example, it reads the file using that coding system (and records the coding system for when the file is saved). Or if the immediately following command is C-x C-w, it writes the file using that coding system. Other file commands affected by a specified coding system include C-x C-i and C-x C-v, as well as the other-window variants of C-x C-f.

C-x RET c also affects commands that start subprocesses, including M-x shell (see section Running Shell Commands from Emacs).

However, if the immediately following command does not use the coding system, then C-x RET c ultimately has no effect.

An easy way to visit a file with no conversion is with the M-x find-file-literally command. See section Visiting Files.

The variable default-buffer-file-coding-system specifies the choice of coding system to use when you create a new file. It applies when you find a new file, and when you create a buffer and then save it in a file. Selecting a language environment typically sets this variable to a good choice of default coding system for that language environment.

The command C-x RET t (set-terminal-coding-system) specifies the coding system for terminal output. If you specify a character code for terminal output, all characters output to the terminal are translated into that coding system.

This feature is useful for certain character-only terminals built to support specific languages or character sets--for example, European terminals that support one of the ISO Latin character sets. You need to specify the terminal coding system when using multibyte text, so that Emacs knows which characters the terminal can actually handle.

By default, output to the terminal is not translated at all, unless Emacs can deduce the proper coding system from your terminal type.

The command C-x RET k (set-keyboard-coding-system) specifies the coding system for keyboard input. Character-code translation of keyboard input is useful for terminals with keys that send non-ASCII graphic characters--for example, some terminals designed for ISO Latin-1 or subsets of it.

By default, keyboard input is not translated at all.

There is a similarity between using a coding system translation for keyboard input, and using an input method: both define sequences of keyboard input that translate into single characters. However, input methods are designed to be convenient for interactive use by humans, and the sequences that are translated are typically sequences of ASCII printing characters. Coding systems typically translate sequences of non-graphic characters.

The command C-x RET x (set-selection-coding-system) specifies the coding system for sending selected text to the window system, and for receiving the text of selections made in other applications. This command applies to all subsequent selections, until you override it by using the command again. The command C-x RET X (set-next-selection-coding-system) specifies the coding system for the next selection made in Emacs or read by Emacs.

The command C-x RET p (set-buffer-process-coding-system) specifies the coding system for input and output to a subprocess. This command applies to the current buffer; normally, each subprocess has its own buffer, and thus you can use this command to specify translation to and from a particular subprocess by giving the command in the corresponding buffer.

By default, process input and output are not translated at all.

The variable file-name-coding-system specifies a coding system to use for encoding file names. If you set the variable to a coding system name (as a Lisp symbol or a string), Emacs encodes file names using that coding system for all file operations. This makes it possible to use non-ASCII characters in file names--or, at least, those non-ASCII characters which the specified coding system can encode.

If file-name-coding-system is nil, Emacs uses a default coding system determined by the selected language environment. In the default language environment, any non-ASCII characters in file names are not encoded specially; they appear in the file system using the internal Emacs representation.

Warning: if you change file-name-coding-system (or the language environment) in the middle of an Emacs session, problems can result if you have already visited files whose names were encoded using the earlier coding system and cannot be encoded (or are encoded differently) under the new coding system. If you try to save one of these buffers under the visited file name, saving may use the wrong file name, or it may get an error. If such a problem happens, use C-x C-w to specify a new file name for that buffer.

Fontsets

A font for X Windows typically defines shapes for one alphabet or script. Therefore, displaying the entire range of scripts that Emacs supports requires a collection of many fonts. In Emacs, such a collection is called a fontset. A fontset is defined by a list of fonts, each assigned to handle a range of character codes.

Each fontset has a name, like a font. The available X fonts are defined by the X server; fontsets, however, are defined within Emacs itself. Once you have defined a fontset, you can use it within Emacs by specifying its name, anywhere that you could use a single font. Of course, Emacs fontsets can use only the fonts that the X server supports; if certain characters appear on the screen as hollow boxes, this means that the fontset in use for them has no font for those characters.

Emacs creates two fontsets automatically: the standard fontset and the startup fontset. The standard fontset is most likely to have fonts for a wide variety of non-ASCII characters; however, this is not the default for Emacs to use. (By default, Emacs tries to find a font which has bold and italic variants.) You can specify use of the standard fontset with the `-fn' option, or with the `Font' X resource (see section Font Specification Options). For example,

emacs -fn fontset-standard

A fontset does not necessarily specify a font for every character code. If a fontset specifies no font for a certain character, or if it specifies a font that does not exist on your system, then it cannot display that character properly. It will display that character as an empty box instead.

The fontset height and width are determined by the ASCII characters (that is, by the font used for ASCII characters in that fontset). If another font in the fontset has a different height, or a different width, then characters assigned to that font are clipped to the fontset's size. If highlight-wrong-size-font is non-nil, a box is displayed around these wrong-size characters as well.

Defining fontsets

Emacs creates a standard fontset automatically according to the value of standard-fontset-spec. This fontset's name is

-*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard

or just `fontset-standard' for short.

Bold, italic, and bold-italic variants of the standard fontset are created automatically. Their names have `bold' instead of `medium', or `i' instead of `r', or both.

If you specify a default ASCII font with the `Font' resource or the `-fn' argument, Emacs generates a fontset from it automatically. This is the startup fontset and its name is fontset-startup. It does this by replacing the foundry, family, add_style, and average_width fields of the font name with `*', replacing charset_registry field with `fontset', and replacing charset_encoding field with `startup', then using the resulting string to specify a fontset.

For instance, if you start Emacs this way,

emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"

Emacs generates the following fontset and uses it for the initial X window frame:

-*-*-medium-r-normal-*-14-140-*-*-*-*-fontset-startup

With the X resource `Emacs.Font', you can specify a fontset name just like an actual font name. But be careful not to specify a fontset name in a wildcard resource like `Emacs*Font'---that wildcard specification applies to various other purposes, such as menus, and menus cannot handle fontsets.

You can specify additional fontsets using X resources named `Fontset-n', where n is an integer starting from 0. The resource value should have this form:

fontpattern, [charsetname:fontname]...

fontpattern should have the form of a standard X font name, except for the last two fields. They should have the form `fontset-alias'.

The fontset has two names, one long and one short. The long name is fontpattern. The short name is `fontset-alias'. You can refer to the fontset by either name.

The construct `charset:font' specifies which font to use (in this fontset) for one particular character set. Here, charset is the name of a character set, and font is the font to use for that character set. You can use this construct any number of times in defining one fontset.

For the other character sets, Emacs chooses a font based on fontpattern. It replaces `fontset-alias' with values that describe the character set. For the ASCII character font, `fontset-alias' is replaced with `ISO8859-1'.

In addition, when several consecutive fields are wildcards, Emacs collapses them into a single wildcard. This is to prevent use of auto-scaled fonts. Fonts made by scaling larger fonts are not usable for editing, and scaling a smaller font is not useful because it is better to use the smaller font in its own size, which Emacs does.

Thus if fontpattern is this,

-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

the font specification for ASCII characters would be this:

-*-fixed-medium-r-normal-*-24-*-ISO8859-1

and the font specification for Chinese GB2312 characters would be this:

-*-fixed-medium-r-normal-*-24-*-gb2312*-*

You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that have `song ti' or `fangsong ti' in family field. In such a case, `Fontset-n' can be specified as below:

Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

Then, the font specifications for all but Chinese GB2312 characters have `fixed' in the family field, and the font specification for Chinese GB2312 characters has a wild card `*' in the family field.

The function that processes the fontset resource value to create the fontset is called create-fontset-from-fontset-spec. You can also call this function explicitly to create a fontset.

See section Font Specification Options, for more information about font naming in X.

Single-byte European Character Support

The ISO 8859 Latin-n character sets define character codes in the range 160 to 255 to handle the accented letters and punctuation needed by various European languages. If you disable multibyte characters, Emacs can still handle one of these character codes at a time. To specify which of these codes to use, invoke M-x set-language-environment and specify a suitable language environment such as `Latin-n'.

For more information about unibyte operation, see section Enabling Multibyte Characters. Note particularly that you probably want to ensure that your initialization files are read as unibyte if they contain non-ASCII characters.

Emacs can also display those characters, provided the terminal or font in use supports them. This works automatically. Alternatively, if you are using a window system, Emacs can also display single-byte characters through fontsets, in effect by displaying the equivalent multibyte characters according to the current language environment. To request this, set the variable unibyte-display-via-language-environment to a non-nil value.

If your terminal does not support display of the Latin-1 character set, Emacs can display these characters as ASCII sequences which at least give you a clear idea of what the characters are. To do this, load the library iso-ascii. Similar libraries for other Latin-n character sets could be implemented, but we don't have them yet.

Normally non-ISO-8859 characters (between characters 128 and 159 inclusive) are displayed as octal escapes. You can change this for non-standard `extended' versions of ISO-8859 character sets by using the function standard-display-8bit in the disp-table library.

There are three different ways you can input single-byte non-ASCII characters:

  • If your keyboard can generate character codes 128 and up, representing non-ASCII characters, execute the following expression to enable Emacs to understand them:
    (set-input-mode (car (current-input-mode))
                (nth 1 (current-input-mode))
                0)
  • You can use an input method for the selected language environment. See section Input Methods. When you use an input method in a unibyte buffer, the non-ASCII character you specify with it is converted to unibyte.
  • For Latin-1 only, you can use the key C-x 8 as a "compose character" prefix for entry of non-ASCII Latin-1 printing characters. C-x 8 is good for insertion (in the minibuffer as well as other buffers), for searching, and in any other context where a key sequence is allowed. C-x 8 works by loading the iso-transl library. Once that library is loaded, the ALT modifier key, if you have one, serves the same purpose as C-x 8; use ALT together with an accent character to modify the following letter. In addition, if you have keys for the Latin-1 "dead accent characters", they too are defined to compose with the following character, once iso-transl is loaded.

Major Modes

Emacs provides many alternative major modes, each of which customizes Emacs for editing text of a particular sort. The major modes are mutually exclusive, and each buffer has one major mode at any time. The mode line normally shows the name of the current major mode, in parentheses (see section The Mode Line).

The least specialized major mode is called Fundamental mode. This mode has no mode-specific redefinitions or variable settings, so that each Emacs command behaves in its most general manner, and each option is in its default state. For editing text of a specific type that Emacs knows about, such as Lisp code or English text, you should switch to the appropriate major mode, such as Lisp mode or Text mode.

Selecting a major mode changes the meanings of a few keys to become more specifically adapted to the language being edited. The ones that are changed frequently are TAB, DEL, and C-j. The prefix key C-c normally contains mode-specific commands. In addition, the commands which handle comments use the mode to determine how comments are to be delimited. Many major modes redefine the syntactical properties of characters appearing in the buffer. See section The Syntax Table.

The major modes fall into three major groups. Lisp mode (which has several variants), C mode, Fortran mode and others are for specific programming languages. Text mode, Nroff mode, TeX mode and Outline mode are for editing English text. The remaining major modes are not intended for use on users' files; they are used in buffers created for specific purposes by Emacs, such as Dired mode for buffers made by Dired (see section Dired, the Directory Editor), Mail mode for buffers made by C-x m (see section Sending Mail), and Shell mode for buffers used for communicating with an inferior shell process (see section Interactive Inferior Shell).

Most programming-language major modes specify that only blank lines separate paragraphs. This is to make the paragraph commands useful. (See section Paragraphs.) They also cause Auto Fill mode to use the definition of TAB to indent the new lines it creates. This is because most lines in a program are usually indented. (See section Indentation.)

How Major Modes are Chosen

You can select a major mode explicitly for the current buffer, but most of the time Emacs determines which mode to use based on the file name or on special text in the file.

Explicit selection of a new major mode is done with a M-x command. From the name of a major mode, add -mode to get the name of a command to select that mode. Thus, you can enter Lisp mode by executing M-x lisp-mode.

When you visit a file, Emacs usually chooses the right major mode based on the file's name. For example, files whose names end in `.c' are edited in C mode. The correspondence between file names and major modes is controlled by the variable auto-mode-alist. Its value is a list in which each element has this form,

(regexp . mode-function)

or this form,

(regexp mode-function flag)

For example, one element normally found in the list has the form ("\\.c\\'" . c-mode), and it is responsible for selecting C mode for files whose names end in `.c'. (Note that `\\' is needed in Lisp syntax to include a `\' in the string, which is needed to suppress the special meaning of `.' in regexps.) If the element has the form (regexp mode-function flag) and flag is non-nil, then after calling function, the suffix that matched regexp is discarded and the list is searched again for another match.

You can specify which major mode should be used for editing a certain file by a special sort of text in the first nonblank line of the file. The mode name should appear in this line both preceded and followed by `-*-'. Other text may appear on the line as well. For example,

;-*-Lisp-*-

tells Emacs to use Lisp mode. Such an explicit specification overrides any defaulting based on the file name. Note how the semicolon is used to make Lisp treat this line as a comment.

Another format of mode specification is

-*- mode: modename;-*-

which allows you to specify local variables as well, like this:

-*- mode: modename; var: value; ... -*-

See section Local Variables in Files, for more information about this.

When a file's contents begin with `#!', it can serve as an executable shell command, which works by running an interpreter named on the file's first line. The rest of the file is used as input to the interpreter.

When you visit such a file in Emacs, if the file's name does not specify a major mode, Emacs uses the interpreter name on the first line to choose a mode. If the first line is the name of a recognized interpreter program, such as `perl' or `tcl', Emacs uses a mode appropriate for programs for that interpreter. The variable interpreter-mode-alist specifies the correspondence between interpreter program names and major modes.

When the first line starts with `#!', you cannot (on many systems) use the `-*-' feature on the first line, because the system would get confused when running the interpreter. So Emacs looks for `-*-' on the second line in such files as well as on the first line.

When you visit a file that does not specify a major mode to use, or when you create a new buffer with C-x b, the variable default-major-mode specifies which major mode to use. Normally its value is the symbol fundamental-mode, which specifies Fundamental mode. If default-major-mode is nil, the major mode is taken from the previously selected buffer.

If you change the major mode of a buffer, you can go back to the major mode Emacs would choose automatically: use the command M-x normal-mode to do this. This is the same function that find-file calls to choose the major mode. It also processes the file's local variables list if any.

The commands C-x C-w and set-visited-file-name change to a new major mode if the new file name implies a mode (see section Saving Files). However, this does not happen if the buffer contents specify a major mode, and certain "special" major modes do not allow the mode to change. You can turn off this mode-changing feature by setting change-major-mode-with-file-name to nil.

Indentation

This chapter describes the Emacs commands that add, remove, or adjust indentation.

TAB
Indent current line "appropriately" in a mode-dependent fashion.
C-j
Perform RET followed by TAB (newline-and-indent).
M-^
Merge two lines (delete-indentation). This would cancel out the effect of C-j.
C-M-o
Split line at point; text on the line after point becomes a new line indented to the same column that it now starts in (split-line).
M-m
Move (forward or back) to the first nonblank character on the current line (back-to-indentation).
C-M-\
Indent several lines to same column (indent-region).
C-x TAB
Shift block of lines rigidly right or left (indent-rigidly).
M-i
Indent from point to the next prespecified tab stop column (tab-to-tab-stop).
M-x indent-relative
Indent from point to under an indentation point in the previous line.

Most programming languages have some indentation convention. For Lisp code, lines are indented according to their nesting in parentheses. The same general idea is used for C code, though many details are different.

Whatever the language, to indent a line, use the TAB command. Each major mode defines this command to perform the sort of indentation appropriate for the particular language. In Lisp mode, TAB aligns the line according to its depth in parentheses. No matter where in the line you are when you type TAB, it aligns the line as a whole. In C mode, TAB implements a subtle and sophisticated indentation style that knows about many aspects of C syntax.

In Text mode, TAB runs the command tab-to-tab-stop, which indents to the next tab stop column. You can set the tab stops with M-x edit-tab-stops.

Indentation Commands and Techniques

To move over the indentation on a line, do M-m (back-to-indentation). This command, given anywhere on a line, positions point at the first nonblank character on the line.

To insert an indented line before the current line, do C-a C-o TAB. To make an indented line after the current line, use C-e C-j.

If you just want to insert a tab character in the buffer, you can type C-q TAB.

C-M-o (split-line) moves the text from point to the end of the line vertically down, so that the current line becomes two lines. C-M-o first moves point forward over any spaces and tabs. Then it inserts after point a newline and enough indentation to reach the same column point is on. Point remains before the inserted newline; in this regard, C-M-o resembles C-o.

To join two lines cleanly, use the M-^ (delete-indentation) command. It deletes the indentation at the front of the current line, and the line boundary as well, replacing them with a single space. As a special case (useful for Lisp code) the single space is omitted if the characters to be joined are consecutive open parentheses or closing parentheses, or if the junction follows another newline. To delete just the indentation of a line, go to the beginning of the line and use M-\ (delete-horizontal-space), which deletes all spaces and tabs around the cursor.

If you have a fill prefix, M-^ deletes the fill prefix if it appears after the newline that is deleted. See section The Fill Prefix.

There are also commands for changing the indentation of several lines at once. C-M-\ (indent-region) applies to all the lines that begin in the region; it indents each line in the "usual" way, as if you had typed TAB at the beginning of the line. A numeric argument specifies the column to indent to, and each line is shifted left or right so that its first nonblank character appears in that column. C-x TAB (indent-rigidly) moves all of the lines in the region right by its argument (left, for negative arguments). The whole group of lines moves rigidly sideways, which is how the command gets its name.

M-x indent-relative indents at point based on the previous line (actually, the last nonempty line). It inserts whitespace at point, moving point, until it is underneath an indentation point in the previous line. An indentation point is the end of a sequence of whitespace or the end of the line. If point is farther right than any indentation point in the previous line, the whitespace before point is deleted and the first indentation point then applicable is used. If no indentation point is applicable even then, indent-relative runs tab-to-tab-stop (see next section).

indent-relative is the definition of TAB in Indented Text mode. See section Commands for Human Languages.

See section Indentation in Formatted Text, for another way of specifying the indentation for part of your text.

Tab Stops

For typing in tables, you can use Text mode's definition of TAB, tab-to-tab-stop. This command inserts indentation before point, enough to reach the next tab stop column. If you are not in Text mode, this command can be found on the key M-i.

You can specify the tab stops used by M-i. They are stored in a variable called tab-stop-list, as a list of column-numbers in increasing order.

The convenient way to set the tab stops is with M-x edit-tab-stops, which creates and selects a buffer containing a description of the tab stop settings. You can edit this buffer to specify different tab stops, and then type C-c C-c to make those new tab stops take effect. edit-tab-stops records which buffer was current when you invoked it, and stores the tab stops back in that buffer; normally all buffers share the same tab stops and changing them in one buffer affects all, but if you happen to make tab-stop-list local in one buffer then edit-tab-stops in that buffer will edit the local settings.

Here is what the text representing the tab stops looks like for ordinary tab stops every eight columns.

        :       :       :       :       :       :
0         1         2         3         4
0123456789012345678901234567890123456789012345678
To install changes, type C-c C-c

The first line contains a colon at each tab stop. The remaining lines are present just to help you see where the colons are and know what to do.

Note that the tab stops that control tab-to-tab-stop have nothing to do with displaying tab characters in the buffer. See section Variables Controlling Display, for more information on that.

Tabs vs. Spaces

Emacs normally uses both tabs and spaces to indent lines. If you prefer, all indentation can be made from spaces only. To request this, set indent-tabs-mode to nil. This is a per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. See section Local Variables.

There are also commands to convert tabs to spaces or vice versa, always preserving the columns of all nonblank text. M-x tabify scans the region for sequences of spaces, and converts sequences of at least three spaces to tabs if that can be done without changing indentation. M-x untabify changes all tabs in the region to appropriate numbers of spaces.

Commands for Human Languages

The term text has two widespread meanings in our area of the computer field. One is data that is a sequence of characters. Any file that you edit with Emacs is text, in this sense of the word. The other meaning is more restrictive: a sequence of characters in a human language for humans to read (possibly after processing by a text formatter), as opposed to a program or commands for a program.

Human languages have syntactic/stylistic conventions that can be supported or used to advantage by editor commands: conventions involving words, sentences, paragraphs, and capital letters. This chapter describes Emacs commands for all of these things. There are also commands for filling, which means rearranging the lines of a paragraph to be approximately equal in length. The commands for moving over and killing words, sentences and paragraphs, while intended primarily for editing text, are also often useful for editing programs.

Emacs has several major modes for editing human-language text. If the file contains text pure and simple, use Text mode, which customizes Emacs in small ways for the syntactic conventions of text. Outline mode provides special commands for operating on text with an outline structure. See section Outline Mode.

For text which contains embedded commands for text formatters, Emacs has other major modes, each for a particular text formatter. Thus, for input to TeX, you would use TeX mode (see section TeX Mode). For input to nroff, use Nroff mode.

Instead of using a text formatter, you can edit formatted text in WYSIWYG style ("what you see is what you get"), with Enriched mode. Then the formatting appears on the screen in Emacs while you edit. See section Editing Formatted Text.

Words

Emacs has commands for moving over or operating on words. By convention, the keys for them are all Meta characters.

M-f
Move forward over a word (forward-word).
M-b
Move backward over a word (backward-word).
M-d
Kill up to the end of a word (kill-word).
M-DEL
Kill back to the beginning of a word (backward-kill-word).
M-@
Mark the end of the next word (mark-word).
M-t
Transpose two words or drag a word across other words (transpose-words).

Notice how these keys form a series that parallels the character-based C-f, C-b, C-d, DEL and C-t. M-@ is cognate to C-@, which is an alias for C-SPC.

The commands M-f (forward-word) and M-b (backward-word) move forward and backward over words. These Meta characters are thus analogous to the corresponding control characters, C-f and C-b, which move over single characters in the text. The analogy extends to numeric arguments, which serve as repeat counts. M-f with a negative argument moves backward, and M-b with a negative argument moves forward. Forward motion stops right after the last letter of the word, while backward motion stops right before the first letter.

M-d (kill-word) kills the word after point. To be precise, it kills everything from point to the place M-f would move to. Thus, if point is in the middle of a word, M-d kills just the part after point. If some punctuation comes between point and the next word, it is killed along with the word. (If you wish to kill only the next word but not the punctuation before it, simply do M-f to get the end, and kill the word backwards with M-DEL.) M-d takes arguments just like M-f.

M-DEL (backward-kill-word) kills the word before point. It kills everything from point back to where M-b would move to. If point is after the space in `FOO, BAR', then `FOO, ' is killed. (If you wish to kill just `FOO', and not the comma and the space, use M-b M-d instead of M-DEL.)

M-t (transpose-words) exchanges the word before or containing point with the following word. The delimiter characters between the words do not move. For example, `FOO, BAR' transposes into `BAR, FOO' rather than `BAR FOO,'. See section Transposing Text, for more on transposition and on arguments to transposition commands.

To operate on the next n words with an operation which applies between point and mark, you can either set the mark at point and then move over the words, or you can use the command M-@ (mark-word) which does not move point, but sets the mark where M-f would move to. M-@ accepts a numeric argument that says how many words to scan for the place to put the mark. In Transient Mark mode, this command activates the mark.

The word commands' understanding of syntax is completely controlled by the syntax table. Any character can, for example, be declared to be a word delimiter. See section The Syntax Table.

Sentences

The Emacs commands for manipulating sentences and paragraphs are mostly on Meta keys, so as to be like the word-handling commands.

M-a
Move back to the beginning of the sentence (backward-sentence).
M-e
Move forward to the end of the sentence (forward-sentence).
M-k
Kill forward to the end of the sentence (kill-sentence).
C-x DEL
Kill back to the beginning of the sentence (backward-kill-sentence).

The commands M-a and M-e (backward-sentence and forward-sentence) move to the beginning and end of the current sentence, respectively. They were chosen to resemble C-a and C-e, which move to the beginning and end of a line. Unlike them, M-a and M-e if repeated or given numeric arguments move over successive sentences.

Moving backward over a sentence places point just before the first character of the sentence; moving forward places point right after the punctuation that ends the sentence. Neither one moves over the whitespace at the sentence boundary.

Just as C-a and C-e have a kill command, C-k, to go with them, so M-a and M-e have a corresponding kill command M-k (kill-sentence) which kills from point to the end of the sentence. With minus one as an argument it kills back to the beginning of the sentence. Larger arguments serve as a repeat count. There is also a command, C-x DEL (backward-kill-sentence), for killing back to the beginning of a sentence. This command is useful when you change your mind in the middle of composing text.

The sentence commands assume that you follow the American typist's convention of putting two spaces at the end of a sentence; they consider a sentence to end wherever there is a `.', `?' or `!' followed by the end of a line or two spaces, with any number of `)', `]', `'', or `"' characters allowed in between. A sentence also begins or ends wherever a paragraph begins or ends.

The variable sentence-end controls recognition of the end of a sentence. It is a regexp that matches the last few characters of a sentence, together with the whitespace following the sentence. Its normal value is

"[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"

This example is explained in the section on regexps. See section Syntax of Regular Expressions.

If you want to use just one space between sentences, you should set sentence-end to this value:

"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"

You should also set the variable sentence-end-double-space to nil so that the fill commands expect and leave just one space at the end of a sentence. Note that this makes it impossible to distinguish between periods that end sentences and those that indicate abbreviations.

Paragraphs

The Emacs commands for manipulating paragraphs are also Meta keys.

M-{
Move back to previous paragraph beginning (backward-paragraph).
M-}
Move forward to next paragraph end (forward-paragraph).
M-h
Put point and mark around this or next paragraph (mark-paragraph).

M-{ moves to the beginning of the current or previous paragraph, while M-} moves to the end of the current or next paragraph. Blank lines and text-formatter command lines separate paragraphs and are not considered part of any paragraph. In Fundamental mode, but not in Text mode, an indented line also starts a new paragraph. (If a paragraph is preceded by a blank line, these commands treat that blank line as the beginning of the paragraph.)

In major modes for programs, paragraphs begin and end only at blank lines. This makes the paragraph commands continue to be useful even though there are no paragraphs per se.

When there is a fill prefix, then paragraphs are delimited by all lines which don't start with the fill prefix. See section Filling Text.

When you wish to operate on a paragraph, you can use the command M-h (mark-paragraph) to set the region around it. Thus, for example, M-h C-w kills the paragraph around or after point. The M-h command puts point at the beginning and mark at the end of the paragraph point was in. In Transient Mark mode, it activates the mark. If point is between paragraphs (in a run of blank lines, or at a boundary), the paragraph following point is surrounded by point and mark. If there are blank lines preceding the first line of the paragraph, one of these blank lines is included in the region.

The precise definition of a paragraph boundary is controlled by the variables paragraph-separate and paragraph-start. The value of paragraph-start is a regexp that should match any line that either starts or separates paragraphs. The value of paragraph-separate is another regexp that should match only lines that separate paragraphs without being part of any paragraph (for example, blank lines). Lines that start a new paragraph and are contained in it must match only paragraph-start, not paragraph-separate. For example, in Fundamental mode, paragraph-start is "[ \t\n\f]" and paragraph-separate is "[ \t\f]*$".

Normally it is desirable for page boundaries to separate paragraphs. The default values of these variables recognize the usual separator for pages.

Pages

Files are often thought of as divided into pages by the formfeed character (ASCII control-L, octal code 014). When you print hardcopy for a file, this character forces a page break; thus, each page of the file goes on a separate page on paper. Most Emacs commands treat the page-separator character just like any other character: you can insert it with C-q C-l, and delete it with DEL. Thus, you are free to paginate your file or not. However, since pages are often meaningful divisions of the file, Emacs provides commands to move over them and operate on them.

C-x [
Move point to previous page boundary (backward-page).
C-x ]
Move point to next page boundary (forward-page).
C-x C-p
Put point and mark around this page (or another page) (mark-page).
C-x l
Count the lines in this page (count-lines-page).

The C-x [ (backward-page) command moves point to immediately after the previous page delimiter. If point is already right after a page delimiter, it skips that one and stops at the previous one. A numeric argument serves as a repeat count. The C-x ] (forward-page) command moves forward past the next page delimiter.

The C-x C-p command (mark-page) puts point at the beginning of the current page and the mark at the end. The page delimiter at the end is included (the mark follows it). The page delimiter at the front is excluded (point follows it). C-x C-p C-w is a handy way to kill a page to move it elsewhere. If you move to another page delimiter with C-x [ and C-x ], then yank the killed page, all the pages will be properly delimited once again. The reason C-x C-p includes only the following page delimiter in the region is to ensure that.

A numeric argument to C-x C-p is used to specify which page to go to, relative to the current one. Zero means the current page. One means the next page, and -1 means the previous one.

The C-x l command (count-lines-page) is good for deciding where to break a page in two. It prints in the echo area the total number of lines in the current page, and then divides it up into those preceding the current line and those following, as in

Page has 96 (72+25) lines

Notice that the sum is off by one; this is correct if point is not at the beginning of a line.

The variable page-delimiter controls where pages begin. Its value is a regexp that matches the beginning of a line that separates pages. The normal value of this variable is "^\f", which matches a formfeed character at the beginning of a line.

Filling Text

Filling text means breaking it up into lines that fit a specified width. Emacs does filling in two ways. In Auto Fill mode, inserting text with self-inserting characters also automatically fills it. There are also explicit fill commands that you can use when editing text leaves it unfilled. When you edit formatted text, you can specify a style of filling for each portion of the text (see section Editing Formatted Text).

Auto Fill Mode

Auto Fill mode is a minor mode in which lines are broken automatically when they become too wide. Breaking happens only when you type a SPC or RET.

M-x auto-fill-mode
Enable or disable Auto Fill mode.
SPC
RET
In Auto Fill mode, break lines when appropriate.

M-x auto-fill-mode turns Auto Fill mode on if it was off, or off if it was on. With a positive numeric argument it always turns Auto Fill mode on, and with a negative argument always turns it off. You can see when Auto Fill mode is in effect by the presence of the word `Fill' in the mode line, inside the parentheses. Auto Fill mode is a minor mode which is enabled or disabled for each buffer individually. See section Minor Modes.

In Auto Fill mode, lines are broken automatically at spaces when they get longer than the desired width. Line breaking and rearrangement takes place only when you type SPC or RET. If you wish to insert a space or newline without permitting line-breaking, type C-q SPC or C-q C-j (recall that a newline is really a control-J). Also, C-o inserts a newline without line breaking.

Auto Fill mode works well with programming-language modes, because it indents new lines with TAB. If a line ending in a comment gets too long, the text of the comment is split into two comment lines. Optionally, new comment delimiters are inserted at the end of the first line and the beginning of the second so that each line is a separate comment; the variable comment-multi-line controls the choice (see section Manipulating Comments).

Adaptive filling (see the following section) works for Auto Filling as well as for explicit fill commands. It takes a fill prefix automatically from the second or first line of a paragraph.

Auto Fill mode does not refill entire paragraphs; it can break lines but cannot merge lines. So editing in the middle of a paragraph can result in a paragraph that is not correctly filled. The easiest way to make the paragraph properly filled again is usually with the explicit fill commands.

Many users like Auto Fill mode and want to use it in all text files. The section on init files says how to arrange this permanently for yourself. See section The Init File, `~/.emacs'.

Explicit Fill Commands

M-q
Fill current paragraph (fill-paragraph).
C-x f
Set the fill column (set-fill-column).
M-x fill-region
Fill each paragraph in the region (fill-region).
M-x fill-region-as-paragraph
Fill the region, considering it as one paragraph.
M-s
Center a line.

To refill a paragraph, use the command M-q (fill-paragraph). This operates on the paragraph that point is inside, or the one after point if point is between paragraphs. Refilling works by removing all the line-breaks, then inserting new ones where necessary.

To refill many paragraphs, use M-x fill-region, which divides the region into paragraphs and fills each of them.

M-q and fill-region use the same criteria as M-h for finding paragraph boundaries (see section Paragraphs). For more control, you can use M-x fill-region-as-paragraph, which refills everything between point and mark. This command deletes any blank lines within the region, so separate blocks of text end up combined into one block.

A numeric argument to M-q causes it to justify the text as well as filling it. This means that extra spaces are inserted to make the right margin line up exactly at the fill column. To remove the extra spaces, use M-q with no argument. (Likewise for fill-region.) Another way to control justification, and choose other styles of filling, is with the justification text property; see section Justification in Formatted Text.

The command M-s (center-line) centers the current line within the current fill column. With an argument n, it centers n lines individually and moves past them.

The maximum line width for filling is in the variable fill-column. Altering the value of fill-column makes it local to the current buffer; until that time, the default value is in effect. The default is initially 70. See section Local Variables. The easiest way to set fill-column is to use the command C-x f (set-fill-column). With a numeric argument, it uses that as the new fill column. With just C-u as argument, it sets fill-column to the current horizontal position of point.

Emacs commands normally consider a period followed by two spaces or by a newline as the end of a sentence; a period followed by just one space indicates an abbreviation and not the end of a sentence. To preserve the distinction between these two ways of using a period, the fill commands do not break a line after a period followed by just one space.

If the variable sentence-end-double-space is nil, the fill commands expect and leave just one space at the end of a sentence. Ordinarily this variable is t, so the fill commands insist on two spaces for the end of a sentence, as explained above. See section Sentences.

If the variable colon-double-space is non-nil, the fill commands put two spaces after a colon.

The Fill Prefix

To fill a paragraph in which each line starts with a special marker (which might be a few spaces, giving an indented paragraph), you can use the fill prefix feature. The fill prefix is a string that Emacs expects every line to start with, and which is not included in filling. You can specify a fill prefix explicitly; Emacs can also deduce the fill prefix automatically (see section Adaptive Filling).

C-x .
Set the fill prefix (set-fill-prefix).
M-q
Fill a paragraph using current fill prefix (fill-paragraph).
M-x fill-individual-paragraphs
Fill the region, considering each change of indentation as starting a new paragraph.
M-x fill-nonuniform-paragraphs
Fill the region, considering only paragraph-separator lines as starting a new paragraph.

To specify a fill prefix, move to a line that starts with the desired prefix, put point at the end of the prefix, and give the command C-x . (set-fill-prefix). That's a period after the C-x. To turn off the fill prefix, specify an empty prefix: type C-x . with point at the beginning of a line.

When a fill prefix is in effect, the fill commands remove the fill prefix from each line before filling and insert it on each line after filling. Auto Fill mode also inserts the fill prefix automatically when it makes a new line. The C-o command inserts the fill prefix on new lines it creates, when you use it at the beginning of a line (see section Blank Lines). Conversely, the command M-^ deletes the prefix (if it occurs) after the newline that it deletes (see section Indentation).

For example, if fill-column is 40 and you set the fill prefix to `;; ', then M-q in the following text

;; This is an
;; example of a paragraph
;; inside a Lisp-style comment.

produces this:

;; This is an example of a paragraph
;; inside a Lisp-style comment.

Lines that do not start with the fill prefix are considered to start paragraphs, both in M-q and the paragraph commands; this gives good results for paragraphs with hanging indentation (every line indented except the first one). Lines which are blank or indented once the prefix is removed also separate or start paragraphs; this is what you want if you are writing multi-paragraph comments with a comment delimiter on each line.

You can use M-x fill-individual-paragraphs to set the fill prefix for each paragraph automatically. This command divides the region into paragraphs, treating every change in the amount of indentation as the start of a new paragraph, and fills each of these paragraphs. Thus, all the lines in one "paragraph" have the same amount of indentation. That indentation serves as the fill prefix for that paragraph.

M-x fill-nonuniform-paragraphs is a similar command that divides the region into paragraphs in a different way. It considers only paragraph-separating lines (as defined by paragraph-separate) as starting a new paragraph. Since this means that the lines of one paragraph may have different amounts of indentation, the fill prefix used is the smallest amount of indentation of any of the lines of the paragraph. This gives good results with styles that indent a paragraph's first line more or less that the rest of the paragraph.

The fill prefix is stored in the variable fill-prefix. Its value is a string, or nil when there is no fill prefix. This is a per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. See section Local Variables.

The indentation text property provides another way to control the amount of indentation paragraphs receive. See section Indentation in Formatted Text.

Adaptive Filling

The fill commands can deduce the proper fill prefix for a paragraph automatically in certain cases: either whitespace or certain punctuation characters at the beginning of a line are propagated to all lines of the paragraph.

If the paragraph has two or more lines, the fill prefix is taken from the paragraph's second line, but only if it appears on the first line as well.

If a paragraph has just one line, fill commands may take a prefix from that line. The decision is complicated because there are three reasonable things to do in such a case:

  • Use the first line's prefix on all the lines of the paragraph.
  • Indent subsequent lines with whitespace, so that they line up under the text that follows the prefix on the first line, but don't actually copy the prefix from the first line.
  • Don't do anything special with the second and following lines.

All three of these styles of formatting are commonly used. So the fill commands try to determine what you would like, based on the prefix that appears and on the major mode. Here is how.

If the prefix found on the first line matches adaptive-fill-first-line-regexp, or if it appears to be a comment-starting sequence (this depends on the major mode), then the prefix found is used for filling the paragraph, provided it would not act as a paragraph starter on subsequent lines.

Otherwise, the prefix found is converted to an equivalent number of spaces, and those spaces are used as the fill prefix for the rest of the lines, provided they would not act as a paragraph starter on subsequent lines.

In Text mode, and other modes where only blank lines and page delimiters separate paragraphs, the prefix chosen by adaptive filling never acts as a paragraph starter, so it can always be used for filling.

The variable adaptive-fill-regexp determines what kinds of line beginnings can serve as a fill prefix: any characters at the start of the line that match this regular expression are used. If you set the variable adaptive-fill-mode to nil, the fill prefix is never chosen automatically.

You can specify more complex ways of choosing a fill prefix automatically by setting the variable adaptive-fill-function to a function. This function is called with point after the left margin of a line, and it should return the appropriate fill prefix based on that line. If it returns nil, that means it sees no fill prefix in that line.

Case Conversion Commands

Emacs has commands for converting either a single word or any arbitrary range of text to upper case or to lower case.

M-l
Convert following word to lower case (downcase-word).
M-u
Convert following word to upper case (upcase-word).
M-c
Capitalize the following word (capitalize-word).
C-x C-l
Convert region to lower case (downcase-region).
C-x C-u
Convert region to upper case (upcase-region).

The word conversion commands are the most useful. M-l (downcase-word) converts the word after point to lower case, moving past it. Thus, repeating M-l converts successive words. M-u (upcase-word) converts to all capitals instead, while M-c (capitalize-word) puts the first letter of the word into upper case and the rest into lower case. All these commands convert several words at once if given an argument. They are especially convenient for converting a large amount of text from all upper case to mixed case, because you can move through the text using M-l, M-u or M-c on each word as appropriate, occasionally using M-f instead to skip a word.

When given a negative argument, the word case conversion commands apply to the appropriate number of words before point, but do not move point. This is convenient when you have just typed a word in the wrong case: you can give the case conversion command and continue typing.

If a word case conversion command is given in the middle of a word, it applies only to the part of the word which follows point. This is just like what M-d (kill-word) does. With a negative argument, case conversion applies only to the part of the word before point.

The other case conversion commands are C-x C-u (upcase-region) and C-x C-l (downcase-region), which convert everything between point and mark to the specified case. Point and mark do not move.

The region case conversion commands upcase-region and downcase-region are normally disabled. This means that they ask for confirmation if you try to use them. When you confirm, you may enable the command, which means it will not ask for confirmation again. See section Disabling Commands.

Text Mode

When you edit files of text in a human language, it's more convenient to use Text mode rather than Fundamental mode. To enter Text mode, type M-x text-mode.

In Text mode, only blank lines and page delimiters separate paragraphs. As a result, paragraphs can be indented, and adaptive filling determines what indentation to use when filling a paragraph. See section Adaptive Filling.

Text mode defines TAB to run indent-relative (see section Indentation), so that you can conveniently indent a line like the previous line. When the previous line is not indented, indent-relative runs tab-to-tab-stop, which uses Emacs tab stops that you can set (see section Tab Stops).

Text mode turns off the features concerned with comments except when you explicitly invoke them. It changes the syntax table so that periods are not considered part of a word, while apostrophes, backspaces and underlines are considered part of words.

If you indent the first lines of paragraphs, then you should use Paragraph-Indent Text mode rather than Text mode. In this mode, you do not need to have blank lines between paragraphs, because the first-line indentation is sufficient to start a paragraph; however paragraphs in which every line is indented are not supported. Use M-x paragraph-indent-text-mode to enter this mode.

Text mode, and all the modes based on it, define M-TAB as the command ispell-complete-word, which performs completion of the partial word in the buffer before point, using the spelling dictionary as the space of possible words. See section Checking and Correcting Spelling.

Entering Text mode runs the hook text-mode-hook. Other major modes related to Text mode also run this hook, followed by hooks of their own; this includes Paragraph-Indent Text mode, Nroff mode, TeX mode, Outline mode, and Mail mode. Hook functions on text-mode-hook can look at the value of major-mode to see which of these modes is actually being entered. See section Hooks.

Outline Mode

Outline mode is a major mode much like Text mode but intended for editing outlines. It allows you to make parts of the text temporarily invisible so that you can see the outline structure. Type M-x outline-mode to switch to Outline mode as the major mode of the current buffer.

When Outline mode makes a line invisible, the line does not appear on the screen. The screen appears exactly as if the invisible line were deleted, except that an ellipsis (three periods in a row) appears at the end of the previous visible line (only one ellipsis no matter how many invisible lines follow).

Editing commands that operate on lines, such as C-n and C-p, treat the text of the invisible line as part of the previous visible line. Killing an entire visible line, including its terminating newline, really kills all the following invisible lines along with it.

Outline minor mode provides the same commands as the major mode, Outline mode, but you can use it in conjunction with other major modes. Type M-x outline-minor-mode to enable the Outline minor mode in the current buffer. You can also specify this in the text of a file, with a file local variable of the form `mode: outline-minor' (see section Local Variables in Files).

The major mode, Outline mode, provides special key bindings on the C-c prefix. Outline minor mode provides similar bindings with C-c @ as the prefix; this is to reduce the conflicts with the major mode's special commands. (The variable outline-minor-mode-prefix controls the prefix used.)

Entering Outline mode runs the hook text-mode-hook followed by the hook outline-mode-hook (see section Hooks).

Format of Outlines

Outline mode assumes that the lines in the buffer are of two types: heading lines and body lines. A heading line represents a topic in the outline. Heading lines start with one or more stars; the number of stars determines the depth of the heading in the outline structure. Thus, a heading line with one star is a major topic; all the heading lines with two stars between it and the next one-star heading are its subtopics; and so on. Any line that is not a heading line is a body line. Body lines belong with the preceding heading line. Here is an example:

* Food
This is the body,
which says something about the topic of food.

** Delicious Food
This is the body of the second-level header.

** Distasteful Food
This could have
a body too, with
several lines.

*** Dormitory Food

* Shelter
Another first-level topic with its header line.

A heading line together with all following body lines is called collectively an entry. A heading line together with all following deeper heading lines and their body lines is called a subtree.

You can customize the criterion for distinguishing heading lines by setting the variable outline-regexp. Any line whose beginning has a match for this regexp is considered a heading line. Matches that start within a line (not at the left margin) do not count. The length of the matching text determines the level of the heading; longer matches make a more deeply nested level. Thus, for example, if a text formatter has commands `@chapter', `@section' and `@subsection' to divide the document into chapters and sections, you could make those lines count as heading lines by setting outline-regexp to `"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words `chapter' and `section' are equally long, but by defining the regexp to match only `chap' we ensure that the length of the text matched on a chapter heading is shorter, so that Outline mode will know that sections are contained in chapters. This works as long as no other command starts with `@chap'.

It is possible to change the rule for calculating the level of a heading line by setting the variable outline-level. The value of outline-level should be a function that takes no arguments and returns the level of the current heading. Some major modes such as C, Nroff, and Emacs Lisp mode set this variable in order to work with Outline minor mode.

Outline Motion Commands

Outline mode provides special motion commands that move backward and forward to heading lines.

C-c C-n
Move point to the next visible heading line (outline-next-visible-heading).
C-c C-p
Move point to the previous visible heading line (outline-previous-visible-heading).
C-c C-f
Move point to the next visible heading line at the same level as the one point is on (outline-forward-same-level).
C-c C-b
Move point to the previous visible heading line at the same level (outline-backward-same-level).
C-c C-u
Move point up to a lower-level (more inclusive) visible heading line (outline-up-heading).

C-c C-n (outline-next-visible-heading) moves down to the next heading line. C-c C-p (outline-previous-visible-heading) moves similarly backward. Both accept numeric arguments as repeat counts. The names emphasize that invisible headings are skipped, but this is not really a special feature. All editing commands that look for lines ignore the invisible lines automatically.

More powerful motion commands understand the level structure of headings. C-c C-f (outline-forward-same-level) and C-c C-b (outline-backward-same-level) move from one heading line to another visible heading at the same depth in the outline. C-c C-u (outline-up-heading) moves backward to another heading that is less deeply nested.

Outline Visibility Commands

The other special commands of outline mode are used to make lines visible or invisible. Their names all start with hide or show. Most of them fall into pairs of opposites. They are not undoable; instead, you can undo right past them. Making lines visible or invisible is simply not recorded by the undo mechanism.

C-c C-t
Make all body lines in the buffer invisible (hide-body).
C-c C-a
Make all lines in the buffer visible (show-all).
C-c C-d
Make everything under this heading invisible, not including this heading itself (hide-subtree).
C-c C-s
Make everything under this heading visible, including body, subheadings, and their bodies (show-subtree).
C-c C-l
Make the body of this heading line, and of all its subheadings, invisible (hide-leaves).
C-c C-k
Make all subheadings of this heading line, at all levels, visible (show-branches).
C-c C-i
Make immediate subheadings (one level down) of this heading line visible (show-children).
C-c C-c
Make this heading line's body invisible (hide-entry).
C-c C-e
Make this heading line's body visible (show-entry).
C-c C-q
Hide everything except the top n levels of heading lines (hide-sublevels).
C-c C-o
Hide everything except for the heading or body that point is in, plus the headings leading up from there to the top level of the outline (hide-other).

Two commands that are exact opposites are C-c C-c (hide-entry) and C-c C-e (show-entry). They are used with point on a heading line, and apply only to the body lines of that heading. Subheadings and their bodies are not affected.

Two more powerful opposites are C-c C-d (hide-subtree) and C-c C-s (show-subtree). Both expect to be used when point is on a heading line, and both apply to all the lines of that heading's subtree: its body, all its subheadings, both direct and indirect, and all of their bodies. In other words, the subtree contains everything following this heading line, up to and not including the next heading of the same or higher rank.

Intermediate between a visible subtree and an invisible one is having all the subheadings visible but none of the body. There are two commands for doing this, depending on whether you want to hide the bodies or make the subheadings visible. They are C-c C-l (hide-leaves) and C-c C-k (show-branches).

A little weaker than show-branches is C-c C-i (show-children). It makes just the direct subheadings visible--those one level down. Deeper subheadings remain invisible, if they were invisible.

Two commands have a blanket effect on the whole file. C-c C-t (hide-body) makes all body lines invisible, so that you see just the outline structure. C-c C-a (show-all) makes all lines visible. These commands can be thought of as a pair of opposites even though C-c C-a applies to more than just body lines.

The command C-c C-q (hide-sublevels) hides all but the top level headings. With a numeric argument n, it hides everything except the top n levels of heading lines.

The command C-c C-o (hide-other) hides everything except the heading or body text that point is in, plus its parents (the headers leading up from there to top level in the outline).

You can turn off the use of ellipses at the ends of visible lines by setting selective-display-ellipses to nil. Then there is no visible indication of the presence of invisible lines.

When incremental search finds text that is hidden by Outline mode, it makes that part of the buffer visible. If you exit the search at that position, the text remains visible.

Viewing One Outline in Multiple Views

You can display two views of a single outline at the same time, in different windows. To do this, you must create an indirect buffer using M-x make-indirect-buffer. The first argument of this command is the existing outline buffer name, and its second argument is the name to use for the new indirect buffer. See section Indirect Buffers.

Once the indirect buffer exists, you can display it in a window in the normal fashion, with C-x 4 b or other Emacs commands. The Outline mode commands to show and hide parts of the text operate on each buffer independently; as a result, each buffer can have its own view. If you want more than two views on the same outline, create additional indirect buffers.

TeX Mode

TeX is a powerful text formatter written by Donald Knuth; it is also free, like GNU Emacs. LaTeX is a simplified input format for TeX, implemented by TeX macros; it comes with TeX. SliTeX is a special form of LaTeX.

Emacs has a special TeX mode for editing TeX input files. It provides facilities for checking the balance of delimiters and for invoking TeX on all or part of the file.

TeX mode has three variants, Plain TeX mode, LaTeX mode, and SliTeX mode (these three distinct major modes differ only slightly). They are designed for editing the three different formats. The command M-x tex-mode looks at the contents of the buffer to determine whether the contents appear to be either LaTeX input or SliTeX input; if so, it selects the appropriate mode. If the file contents do not appear to be LaTeX or SliTeX, it selects Plain TeX mode. If the contents are insufficient to determine this, the variable tex-default-mode controls which mode is used.

When M-x tex-mode does not guess right, you can use the commands M-x plain-tex-mode, M-x latex-mode, and M-x slitex-mode to select explicitly the particular variants of TeX mode.

TeX Editing Commands

Here are the special commands provided in TeX mode for editing the text of the file.

"
Insert, according to context, either `"' or `"' or `"' (tex-insert-quote).
C-j
Insert a paragraph break (two newlines) and check the previous paragraph for unbalanced braces or dollar signs (tex-terminate-paragraph).
M-x tex-validate-region
Check each paragraph in the region for unbalanced braces or dollar signs.
C-c {
Insert `{}' and position point between them (tex-insert-braces).
C-c }
Move forward past the next unmatched close brace (up-list).

In TeX, the character `"' is not normally used; we use `"' to start a quotation and `"' to end one. To make editing easier under this formatting convention, TeX mode overrides the normal meaning of the key " with a command that inserts a pair of single-quotes or backquotes (tex-insert-quote). To be precise, this command inserts `"' after whitespace or an open brace, `"' after a backslash, and `"' after any other character.

If you need the character `"' itself in unusual contexts, use C-q to insert it. Also, " with a numeric argument always inserts that number of `"' characters. You can turn off the feature of " expansion by eliminating that binding in the local map (see section Customizing Key Bindings).

In TeX mode, `$' has a special syntax code which attempts to understand the way TeX math mode delimiters match. When you insert a `$' that is meant to exit math mode, the position of the matching `$' that entered math mode is displayed for a second. This is the same feature that displays the open brace that matches a close brace that is inserted. However, there is no way to tell whether a `$' enters math mode or leaves it; so when you insert a `$' that enters math mode, the previous `$' position is shown as if it were a match, even though they are actually unrelated.

TeX uses braces as delimiters that must match. Some users prefer to keep braces balanced at all times, rather than inserting them singly. Use C-c { (tex-insert-braces) to insert a pair of braces. It leaves point between the two braces so you can insert the text that belongs inside. Afterward, use the command C-c } (up-list) to move forward past the close brace.

There are two commands for checking the matching of braces. C-j (tex-terminate-paragraph) checks the paragraph before point, and inserts two newlines to start a new paragraph. It prints a message in the echo area if any mismatch is found. M-x tex-validate-region checks a region, paragraph by paragraph. The errors are listed in the `*Occur*' buffer, and you can use C-c C-c or Mouse-2 in that buffer to go to a particular mismatch.

Note that Emacs commands count square brackets and parentheses in TeX mode, not just braces. This is not strictly correct for the purpose of checking TeX syntax. However, parentheses and square brackets are likely to be used in text as matching delimiters and it is useful for the various motion commands and automatic match display to work with them.

LaTeX Editing Commands

LaTeX mode, and its variant, SliTeX mode, provide a few extra features not applicable to plain TeX.

C-c C-o
Insert `\begin' and `\end' for LaTeX block and position point on a line between them (tex-latex-block).
C-c C-e
Close the innermost LaTeX block not yet closed (tex-close-latex-block).

In LaTeX input, `\begin' and `\end' commands are used to group blocks of text. To insert a `\begin' and a matching `\end' (on a new line following the `\begin'), use C-c C-o (tex-latex-block). A blank line is inserted between the two, and point is left there. You can use completion when you enter the block type; to specify additional block type names beyond the standard list, set the variable latex-block-names. For example, here's how to add `theorem', `corollary', and `proof':

(setq latex-block-names '("theorem" "corollary" "proof"))

In LaTeX input, `\begin' and `\end' commands must balance. You can use C-c C-e (tex-close-latex-block) to insert automatically a matching `\end' to match the last unmatched `\begin'. It indents the `\end' to match the corresponding `\begin'. It inserts a newline after `\end' if point is at the beginning of a line.

TeX Printing Commands

You can invoke TeX as an inferior of Emacs on either the entire contents of the buffer or just a region at a time. Running TeX in this way on just one chapter is a good way to see what your changes look like without taking the time to format the entire file.

C-c C-r
Invoke TeX on the current region, together with the buffer's header (tex-region).
C-c C-b
Invoke TeX on the entire current buffer (tex-buffer).
C-c TAB
Invoke BibTeX on the current file (tex-bibtex-file).
C-c C-f
Invoke TeX on the current file (tex-file).
C-c C-l
Recenter the window showing output from the inferior TeX so that the last line can be seen (tex-recenter-output-buffer).
C-c C-k
Kill the TeX subprocess (tex-kill-job).
C-c C-p
Print the output from the last C-c C-r, C-c C-b, or C-c C-f command (tex-print).
C-c C-v
Preview the output from the last C-c C-r, C-c C-b, or C-c C-f command (tex-view).
C-c C-q
Show the printer queue (tex-show-print-queue).

You can pass the current buffer through an inferior TeX by means of C-c C-b (tex-buffer). The formatted output appears in a temporary file; to print it, type C-c C-p (tex-print). Afterward, you can use C-c C-q (tex-show-print-queue) to view the progress of your output towards being printed. If your terminal has the ability to display TeX output files, you can preview the output on the terminal with C-c C-v (tex-view).

You can specify the directory to use for running TeX by setting the variable tex-directory. "." is the default value. If your environment variable TEXINPUTS contains relative directory names, or if your files contains `\input' commands with relative file names, then tex-directory must be "." or you will get the wrong results. Otherwise, it is safe to specify some other directory, such as "/tmp".

If you want to specify which shell commands are used in the inferior TeX, you can do so by setting the values of the variables tex-run-command, latex-run-command, slitex-run-command, tex-dvi-print-command, tex-dvi-view-command, and tex-show-queue-command. You must set the value of tex-dvi-view-command for your particular terminal; this variable has no default value. The other variables have default values that may (or may not) be appropriate for your system.

Normally, the file name given to these commands comes at the end of the command string; for example, `latex filename'. In some cases, however, the file name needs to be embedded in the command; an example is when you need to provide the file name as an argument to one command whose output is piped to another. You can specify where to put the file name with `*' in the command string. For example,

(setq tex-dvi-print-command "dvips -f * | lpr")

The terminal output from TeX, including any error messages, appears in a buffer called `*tex-shell*'. If TeX gets an error, you can switch to this buffer and feed it input (this works as in Shell mode; see section Interactive Inferior Shell). Without switching to this buffer you can scroll it so that its last line is visible by typing C-c C-l.

Type C-c C-k (tex-kill-job) to kill the TeX process if you see that its output is no longer useful. Using C-c C-b or C-c C-r also kills any TeX process still running.

You can also pass an arbitrary region through an inferior TeX by typing C-c C-r (tex-region). This is tricky, however, because most files of TeX input contain commands at the beginning to set parameters and define macros, without which no later part of the file will format correctly. To solve this problem, C-c C-r allows you to designate a part of the file as containing essential commands; it is included before the specified region as part of the input to TeX. The designated part of the file is called the header.

To indicate the bounds of the header in Plain TeX mode, you insert two special strings in the file. Insert `%**start of header' before the header, and `%**end of header' after it. Each string must appear entirely on one line, but there may be other text on the line before or after. The lines containing the two strings are included in the header. If `%**start of header' does not appear within the first 100 lines of the buffer, C-c C-r assumes that there is no header.

In LaTeX mode, the header begins with `\documentstyle' and ends with `\begin{document}'. These are commands that LaTeX requires you to use in any case, so nothing special needs to be done to identify the header.

The commands (tex-buffer) and (tex-region) do all of their work in a temporary directory, and do not have available any of the auxiliary files needed by TeX for cross-references; these commands are generally not suitable for running the final copy in which all of the cross-references need to be correct.

When you want the auxiliary files for cross references, use C-c C-f (tex-file) which runs TeX on the current buffer's file, in that file's directory. Before running TeX, it offers to save any modified buffers. Generally, you need to use (tex-file) twice to get the cross-references right.

The value of the variable tex-start-options-string specifies options for the TeX run. The default value causes TeX to run in nonstopmode. To run TeX interactively, set the variable to "".

Large TeX documents are often split into several files--one main file, plus subfiles. Running TeX on a subfile typically does not work; you have to run it on the main file. In order to make tex-file useful when you are editing a subfile, you can set the variable tex-main-file to the name of the main file. Then tex-file runs TeX on that file.

The most convenient way to use tex-main-file is to specify it in a local variable list in each of the subfiles. See section Local Variables in Files.

For LaTeX files, you can use BibTeX to process the auxiliary file for the current buffer's file. BibTeX looks up bibliographic citations in a data base and prepares the cited references for the bibliography section. The command C-c TAB (tex-bibtex-file) runs the shell command (tex-bibtex-command) to produce a `.bbl' file for the current buffer's file. Generally, you need to do C-c C-f (tex-file) once to generate the `.aux' file, then do C-c TAB (tex-bibtex-file), and then repeat C-c C-f (tex-file) twice more to get the cross-references correct.

Entering any kind of TeX mode runs the hooks text-mode-hook and tex-mode-hook. Then it runs either plain-tex-mode-hook or latex-mode-hook, whichever is appropriate. For SliTeX files, it calls slitex-mode-hook. Starting the TeX shell runs the hook tex-shell-hook. See section Hooks.

Nroff Mode

Nroff mode is a mode like Text mode but modified to handle nroff commands present in the text. Invoke M-x nroff-mode to enter this mode. It differs from Text mode in only a few ways. All nroff command lines are considered paragraph separators, so that filling will never garble the nroff commands. Pages are separated by `.bp' commands. Comments start with backslash-doublequote. Also, three special commands are provided that are not in Text mode:

M-n
Move to the beginning of the next line that isn't an nroff command (forward-text-line). An argument is a repeat count.
M-p
Like M-n but move up (backward-text-line).
M-?
Prints in the echo area the number of text lines (lines that are not nroff commands) in the region (count-text-lines).

The other feature of Nroff mode is that you can turn on Electric Nroff mode. This is a minor mode that you can turn on or off with M-x electric-nroff-mode (see section Minor Modes). When the mode is on, each time you use RET to end a line that contains an nroff command that opens a kind of grouping, the matching nroff command to close that grouping is automatically inserted on the following line. For example, if you are at the beginning of a line and type . ( b RET, this inserts the matching command `.)b' on a new line following point.

If you use Outline minor mode with Nroff mode (see section Outline Mode), heading lines are lines of the form `.H' followed by a number (the header level).

Entering Nroff mode runs the hook text-mode-hook, followed by the hook nroff-mode-hook (see section Hooks).

Editing Formatted Text

Enriched mode is a minor mode for editing files that contain formatted text in WYSIWYG fashion, as in a word processor. Currently, formatted text in Enriched mode can specify fonts, colors, underlining, margins, and types of filling and justification. In the future, we plan to implement other formatting features as well.

Enriched mode is a minor mode (see section Minor Modes). Typically it is used in conjunction with Text mode (see section Text Mode). However, you can also use it with other major modes such as Outline mode and Paragraph-Indent Text mode.

Potentially, Emacs can store formatted text files in various file formats. Currently, only one format is implemented: text/enriched format, which is defined by the MIME protocol. See section `Format Conversion' in the Emacs Lisp Reference Manual, for details of how Emacs recognizes and converts file formats.

The Emacs distribution contains a formatted text file that can serve as an example. Its name is `etc/enriched.doc'. It contains samples illustrating all the features described in this section. It also contains a list of ideas for future enhancements.

Requesting to Edit Formatted Text

Whenever you visit a file that Emacs saved in the text/enriched format, Emacs automatically converts the formatting information in the file into Emacs's own internal format (text properties), and turns on Enriched mode.

To create a new file of formatted text, first visit the nonexistent file, then type M-x enriched-mode before you start inserting text. This command turns on Enriched mode. Do this before you begin inserting text, to ensure that the text you insert is handled properly.

More generally, the command enriched-mode turns Enriched mode on if it was off, and off if it was on. With a prefix argument, this command turns Enriched mode on if the argument is positive, and turns the mode off otherwise.

When you save a buffer while Enriched mode is enabled in it, Emacs automatically converts the text to text/enriched format while writing it into the file. When you visit the file again, Emacs will automatically recognize the format, reconvert the text, and turn on Enriched mode again.

Normally, after visiting a file in text/enriched format, Emacs refills each paragraph to fit the specified right margin. You can turn off this refilling, to save time, by setting the variable enriched-fill-after-visiting to nil or to ask.

However, when visiting a file that was saved from Enriched mode, there is no need for refilling, because Emacs saves the right margin settings along with the text.

You can add annotations for saving additional text properties, which Emacs normally does not save, by adding to enriched-translations. Note that the text/enriched standard requires any non-standard annotations to have names starting with `x-', as in `x-read-only'. This ensures that they will not conflict with standard annotations that may be added later.

Hard and Soft Newlines

In formatted text, Emacs distinguishes between two different kinds of newlines, hard newlines and soft newlines.

Hard newlines are used to separate paragraphs, or items in a list, or anywhere that there should always be a line break regardless of the margins. The RET command (newline) and C-o (open-line) insert hard newlines.

Soft newlines are used to make text fit between the margins. All the fill commands, including Auto Fill, insert soft newlines--and they delete only soft newlines.

Although hard and soft newlines look the same, it is important to bear the difference in mind. Do not use RET to break lines in the middle of filled paragraphs, or else you will get hard newlines that are barriers to further filling. Instead, let Auto Fill mode break lines, so that if the text or the margins change, Emacs can refill the lines properly. See section Auto Fill Mode.

On the other hand, in tables and lists, where the lines should always remain as you type them, you can use RET to end lines. For these lines, you may also want to set the justification style to unfilled. See section Justification in Formatted Text.

Editing Format Information

There are two ways to alter the formatting information for a formatted text file: with keyboard commands, and with the mouse.

The easiest way to add properties to your document is by using the Text Properties menu. You can get to this menu in two ways: from the Edit menu in the menu bar, or with C-mouse-2 (hold the CTRL key and press the middle mouse button).

Most of the items in the Text Properties menu lead to other submenus. These are described in the sections that follow. Some items run commands directly:

Remove Properties
Delete from the region all the text properties that the Text Properties menu works with (facemenu-remove-props).
Remove All
Delete all text properties from the region (facemenu-remove-all).
List Properties
List all the text properties of the character following point (list-text-properties-at).
Display Faces
Display a list of all the defined faces.
Display Colors
Display a list of all the defined colors.

Faces in Formatted Text

The Faces submenu lists various Emacs faces including bold, italic, and underline. Selecting one of these adds the chosen face to the region. See section Using Multiple Typefaces. You can also specify a face with these keyboard commands:

M-g d
Set the region, or the next inserted character, to the default face (facemenu-set-default).
M-g b
Set the region, or the next inserted character, to the bold face (facemenu-set-bold).
M-g i
Set the region, or the next inserted character, to the italic face (facemenu-set-italic).
M-g l
Set the region, or the next inserted character, to the bold-italic face (facemenu-set-bold-italic).
M-g u
Set the region, or the next inserted character, to the underline face (facemenu-set-underline).
M-g o face RET
Set the region, or the next inserted character, to the face face (facemenu-set-face).

If you use these commands with a prefix argument--or, in Transient Mark mode, if the region is not active--then these commands specify a face to use for your next self-inserting input. See section Transient Mark Mode. This applies to both the keyboard commands and the menu commands.

Enriched mode defines two additional faces: excerpt and fixed. These correspond to codes used in the text/enriched file format.

The excerpt face is intended for quotations. This face is the same as italic unless you customize it (see section Customizing Faces).

The fixed face is meant to say, "Use a fixed-width font for this part of the text." Emacs currently supports only fixed-width fonts; therefore, the fixed annotation is not necessary now. However, we plan to support variable width fonts in future Emacs versions, and other systems that display text/enriched format may not use a fixed-width font as the default. So if you specifically want a certain part of the text to use a fixed-width font, you should specify the fixed face for that part.

The fixed face is normally defined to use a different font from the default. However, different systems have different fonts installed, so you may need to customize this.

If your terminal cannot display different faces, you will not be able to see them, but you can still edit documents containing faces. You can even add faces and colors to documents. They will be visible when the file is viewed on a terminal that can display them.

Colors in Formatted Text

You can specify foreground and background colors for portions of the text. There is a menu for specifying the foreground color and a menu for specifying the background color. Each color menu lists all the colors that you have used in Enriched mode in the current Emacs session.

If you specify a color with a prefix argument--or, in Transient Mark mode, if the region is not active--then it applies to your next self-inserting input. See section Transient Mark Mode. Otherwise, the command applies to the region.

Each color menu contains one additional item: `Other'. You can use this item to specify a color that is not listed in the menu; it reads the color name with the minibuffer. To display list of available colors and their names, use the `Display Colors' menu item in the Text Properties menu (see section Editing Format Information).

Any color that you specify in this way, or that is mentioned in a formatted text file that you read in, is added to both color menus for the duration of the Emacs session.

There are no key bindings for specifying colors, but you can do so with the extended commands M-x facemenu-set-foreground and M-x facemenu-set-background. Both of these commands read the name of the color with the minibuffer.

Indentation in Formatted Text

When editing formatted text, you can specify different amounts of indentation for the right or left margin of an entire paragraph or a part of a paragraph. The margins you specify automatically affect the Emacs fill commands (see section Filling Text) and line-breaking commands.

The Indentation submenu provides a convenient interface for specifying these properties. The submenu contains four items:

Indent More
Indent the region by 4 columns (increase-left-margin). In Enriched mode, this command is also available on C-x TAB; if you supply a numeric argument, that says how many columns to add to the margin (a negative argument reduces the number of columns).
Indent Less
Remove 4 columns of indentation from the region.
Indent Right More
Make the text narrower by indenting 4 columns at the right margin.
Indent Right Less
Remove 4 columns of indentation from the right margin.

You can use these commands repeatedly to increase or decrease the indentation.

The most common way to use these commands is to change the indentation of an entire paragraph. However, that is not the only use. You can change the margins at any point; the new values take effect at the end of the line (for right margins) or the beginning of the next line (for left margins).

This makes it possible to format paragraphs with hanging indents, which means that the first line is indented less than subsequent lines. To set up a hanging indent, increase the indentation of the region starting after the first word of the paragraph and running until the end of the paragraph.

Indenting the first line of a paragraph is easier. Set the margin for the whole paragraph where you want it to be for the body of the paragraph, then indent the first line by inserting extra spaces or tabs.

Sometimes, as a result of editing, the filling of a paragraph becomes messed up--parts of the paragraph may extend past the left or right margins. When this happens, use M-q (fill-paragraph) to refill the paragraph.

The variable standard-indent specifies how many columns these commands should add to or subtract from the indentation. The default value is 4. The overall default right margin for Enriched mode is controlled by the variable fill-column, as usual.

The fill prefix, if any, works in addition to the specified paragraph indentation: C-x . does not include the specified indentation's whitespace in the new value for the fill prefix, and the fill commands look for the fill prefix after the indentation on each line. See section The Fill Prefix.

Justification in Formatted Text

When editing formatted text, you can specify various styles of justification for a paragraph. The style you specify automatically affects the Emacs fill commands.

The Justification submenu provides a convenient interface for specifying the style. The submenu contains five items:

Flush Left
This is the most common style of justification (at least for English). Lines are aligned at the left margin but left uneven at the right.
Flush Right
This aligns each line with the right margin. Spaces and tabs are added on the left, if necessary, to make lines line up on the right.
Full
This justifies the text, aligning both edges of each line. Justified text looks very nice in a printed book, where the spaces can all be adjusted equally, but it does not look as nice with a fixed-width font on the screen. Perhaps a future version of Emacs will be able to adjust the width of spaces in a line to achieve elegant justification.
Center
This centers every line between the current margins.
None
This turns off filling entirely. Each line will remain as you wrote it; the fill and auto-fill functions will have no effect on text which has this setting. You can, however, still indent the left margin. In unfilled regions, all newlines are treated as hard newlines (see section Hard and Soft Newlines) .

In Enriched mode, you can also specify justification from the keyboard using the M-j prefix character:

M-j l
Make the region left-filled (set-justification-left).
M-j r
Make the region right-filled (set-justification-right).
M-j f
Make the region fully-justified (set-justification-full).
M-j c
M-S
Make the region centered (set-justification-center).
M-j u
Make the region unfilled (set-justification-none).

Justification styles apply to entire paragraphs. All the justification-changing commands operate on the paragraph containing point, or, if the region is active, on all paragraphs which overlap the region.

The default justification style is specified by the variable default-justification. Its value should be one of the symbols left, right, full, center, or none.

Setting Other Text Properties

The Other Properties menu lets you add or remove three other useful text properties: read-only, invisible and intangible. The intangible property disallows moving point within the text, the invisible text property hides text from display, and the read-only property disallows alteration of the text.

Each of these special properties has a menu item to add it to the region. The last menu item, `Remove Special', removes all of these special properties from the text in the region.

Currently, the invisible and intangible properties are not saved in the text/enriched format. The read-only property is saved, but it is not a standard part of the text/enriched format, so other editors may not respect it.

Forcing Enriched Mode

Normally, Emacs knows when you are editing formatted text because it recognizes the special annotations used in the file that you visited. However, there are situations in which you must take special actions to convert file contents or turn on Enriched mode:

  • When you visit a file that was created with some other editor, Emacs may not recognize the file as being in the text/enriched format. In this case, when you visit the file you will see the formatting commands rather than the formatted text. Type M-x format-decode-buffer to translate it.
  • When you insert a file into a buffer, rather than visiting it. Emacs does the necessary conversions on the text which you insert, but it does not enable Enriched mode. If you wish to do that, type M-x enriched-mode.

The command format-decode-buffer translates text in various formats into Emacs's internal format. It asks you to specify the format to translate from; however, normally you can type just RET, which tells Emacs to guess the format.

If you wish to look at text/enriched file in its raw form, as a sequence of characters rather than as formatted text, use the M-x find-file-literally command. This visits a file, like find-file, but does not do format conversion. It also inhibits character code conversion (see section Coding Systems) and automatic uncompression (see section Accessing Compressed Files). To disable format conversion but allow character code conversion and/or automatic uncompression if appropriate, use format-find-file with suitable arguments.

Editing Programs

Emacs has many commands designed to understand the syntax of programming languages such as Lisp and C. These commands can

  • Move over or kill balanced expressions or sexps (see section Lists and Sexps).
  • Move over or mark top-level expressions---defuns, in Lisp; functions, in C (see section Defuns).
  • Show how parentheses balance (see section Automatic Display Of Matching Parentheses).
  • Insert, kill or align comments (see section Manipulating Comments).
  • Follow the usual indentation conventions of the language (see section Indentation for Programs).

The commands for words, sentences and paragraphs are very useful in editing code even though their canonical application is for editing human language text. Most symbols contain words (see section Words); sentences can be found in strings and comments (see section Sentences). Paragraphs per se don't exist in code, but the paragraph commands are useful anyway, because programming language major modes define paragraphs to begin and end at blank lines (see section Paragraphs). Judicious use of blank lines to make the program clearer will also provide useful chunks of text for the paragraph commands to work on.

The selective display feature is useful for looking at the overall structure of a function (see section Selective Display). This feature causes only the lines that are indented less than a specified amount to appear on the screen.

Major Modes for Programming Languages

Emacs also has major modes for the programming languages Lisp, Scheme (a variant of Lisp), Awk, C, C++, Fortran, Icon, Java, Objective-C, Pascal, Perl, Pike, CORBA IDL, and Tcl. There is also a major mode for makefiles, called Makefile mode. An second alternative mode for Perl is called CPerl mode.

Ideally, a major mode should be implemented for each programming language that you might want to edit with Emacs; but often the mode for one language can serve for other syntactically similar languages. The language modes that exist are those that someone decided to take the trouble to write.

There are several forms of Lisp mode, which differ in the way they interface to Lisp execution. See section Executing Lisp Expressions.

Each of the programming language major modes defines the TAB key to run an indentation function that knows the indentation conventions of that language and updates the current line's indentation accordingly. For example, in C mode TAB is bound to c-indent-line. C-j is normally defined to do RET followed by TAB; thus, it too indents in a mode-specific fashion.

In most programming languages, indentation is likely to vary from line to line. So the major modes for those languages rebind DEL to treat a tab as if it were the equivalent number of spaces (using the command backward-delete-char-untabify). This makes it possible to rub out indentation one column at a time without worrying whether it is made up of spaces or tabs. Use C-b C-d to delete a tab character before point, in these modes.

Programming language modes define paragraphs to be separated only by blank lines, so that the paragraph commands remain useful. Auto Fill mode, if enabled in a programming language major mode, indents the new lines which it creates.

Turning on a major mode runs a normal hook called the mode hook, which is the value of a Lisp variable. Each major mode has a mode hook, and the hook's name is always made from the mode command's name by adding `-hook'. For example, turning on C mode runs the hook c-mode-hook, while turning on Lisp mode runs the hook lisp-mode-hook. See section Hooks.

Lists and Sexps

By convention, Emacs keys for dealing with balanced expressions are usually Control-Meta characters. They tend to be analogous in function to their Control and Meta equivalents. These commands are usually thought of as pertaining to expressions in programming languages, but can be useful with any language in which some sort of parentheses exist (including human languages).

These commands fall into two classes. Some deal only with lists (parenthetical groupings). They see nothing except parentheses, brackets, braces (whichever ones must balance in the language you are working with), and escape characters that might be used to quote those.

The other commands deal with expressions or sexps. The word `sexp' is derived from s-expression, the ancient term for an expression in Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It refers to an expression in whatever language your program is written in. Each programming language has its own major mode, which customizes the syntax tables so that expressions in that language count as sexps.

Sexps typically include symbols, numbers, and string constants, as well as anything contained in parentheses, brackets or braces.

In languages that use prefix and infix operators, such as C, it is not possible for all expressions to be sexps. For example, C mode does not recognize `foo + bar' as a sexp, even though it is a C expression; it recognizes `foo' as one sexp and `bar' as another, with the `+' as punctuation between them. This is a fundamental ambiguity: both `foo + bar' and `foo' are legitimate choices for the sexp to move over if point is at the `f'. Note that `(foo + bar)' is a single sexp in C mode.

Some languages have obscure forms of expression syntax that nobody has bothered to make Emacs understand properly.

List And Sexp Commands

C-M-f
Move forward over a sexp (forward-sexp).
C-M-b
Move backward over a sexp (backward-sexp).
C-M-k
Kill sexp forward (kill-sexp).
C-M-DEL
Kill sexp backward (backward-kill-sexp).
C-M-u
Move up and backward in list structure (backward-up-list).
C-M-d
Move down and forward in list structure (down-list).
C-M-n
Move forward over a list (forward-list).
C-M-p
Move backward over a list (backward-list).
C-M-t
Transpose expressions (transpose-sexps).
C-M-@
Put mark after following expression (mark-sexp).

To move forward over a sexp, use C-M-f (forward-sexp). If the first significant character after point is an opening delimiter (`(' in Lisp; `(', `[' or `{' in C), C-M-f moves past the matching closing delimiter. If the character begins a symbol, string, or number, C-M-f moves over that.

The command C-M-b (backward-sexp) moves backward over a sexp. The detailed rules are like those above for C-M-f, but with directions reversed. If there are any prefix characters (single-quote, backquote and comma, in Lisp) preceding the sexp, C-M-b moves back over them as well. The sexp commands move across comments as if they were whitespace in most modes.

C-M-f or C-M-b with an argument repeats that operation the specified number of times; with a negative argument, it moves in the opposite direction.

Killing a whole sexp can be done with C-M-k (kill-sexp) or C-M-DEL (backward-kill-sexp). C-M-k kills the characters that C-M-f would move over, and C-M-DEL kills the characters that C-M-b would move over.

The list commands move over lists, as the sexp commands do, but skip blithely over any number of other kinds of sexps (symbols, strings, etc.). They are C-M-n (forward-list) and C-M-p (backward-list). The main reason they are useful is that they usually ignore comments (since the comments usually do not contain any lists).

C-M-n and C-M-p stay at the same level in parentheses, when that's possible. To move up one (or n) levels, use C-M-u (backward-up-list). C-M-u moves backward up past one unmatched opening delimiter. A positive argument serves as a repeat count; a negative argument reverses direction of motion and also requests repetition, so it moves forward and up one or more levels.

To move down in list structure, use C-M-d (down-list). In Lisp mode, where `(' is the only opening delimiter, this is nearly the same as searching for a `('. An argument specifies the number of levels of parentheses to go down.

A somewhat random-sounding command which is nevertheless handy is C-M-t (transpose-sexps), which drags the previous sexp across the next one. An argument serves as a repeat count, and a negative argument drags backwards (thus canceling out the effect of C-M-t with a positive argument). An argument of zero, rather than doing nothing, transposes the sexps ending after point and the mark.

To set the region around the next sexp in the buffer, use C-M-@ (mark-sexp), which sets mark at the same place that C-M-f would move to. C-M-@ takes arguments like C-M-f. In particular, a negative argument is useful for putting the mark at the beginning of the previous sexp.

The list and sexp commands' understanding of syntax is completely controlled by the syntax table. Any character can, for example, be declared to be an opening delimiter and act like an open parenthesis. See section The Syntax Table.

Defuns

In Emacs, a parenthetical grouping at the top level in the buffer is called a defun. The name derives from the fact that most top-level lists in a Lisp file are instances of the special form defun, but any top-level parenthetical grouping counts as a defun in Emacs parlance regardless of what its contents are, and regardless of the programming language in use. For example, in C, the body of a function definition is a defun.

C-M-a
Move to beginning of current or preceding defun (beginning-of-defun).
C-M-e
Move to end of current or following defun (end-of-defun).
C-M-h
Put region around whole current or following defun (mark-defun).

The commands to move to the beginning and end of the current defun are C-M-a (beginning-of-defun) and C-M-e (end-of-defun).

If you wish to operate on the current defun, use C-M-h (mark-defun) which puts point at the beginning and mark at the end of the current or next defun. For example, this is the easiest way to get ready to move the defun to a different place in the text. In C mode, C-M-h runs the function c-mark-function, which is almost the same as mark-defun; the difference is that it backs up over the argument declarations, function name and returned data type so that the entire C function is inside the region. See section Commands to Mark Textual Objects.

Emacs assumes that any open-parenthesis found in the leftmost column is the start of a defun. Therefore, never put an open-parenthesis at the left margin in a Lisp file unless it is the start of a top-level list. Never put an open-brace or other opening delimiter at the beginning of a line of C code unless it starts the body of a function. The most likely problem case is when you want an opening delimiter at the start of a line inside a string. To avoid trouble, put an escape character (`\', in C and Emacs Lisp, `/' in some other Lisp dialects) before the opening delimiter. It will not affect the contents of the string.

In the remotest past, the original Emacs found defuns by moving upward a level of parentheses until there were no more levels to go up. This always required scanning all the way back to the beginning of the buffer, even for a small function. To speed up the operation, Emacs was changed to assume that any `(' (or other character assigned the syntactic class of opening-delimiter) at the left margin is the start of a defun. This heuristic is nearly always right and avoids the costly scan; however, it mandates the convention described above.

Indentation for Programs

The best way to keep a program properly indented is to use Emacs to reindent it as you change it. Emacs has commands to indent properly either a single line, a specified number of lines, or all of the lines inside a single parenthetical grouping.

Emacs also provides a Lisp pretty-printer in the library pp. This program reformats a Lisp object with indentation chosen to look nice.

Basic Program Indentation Commands

TAB
Adjust indentation of current line.
C-j
Equivalent to RET followed by TAB (newline-and-indent).

The basic indentation command is TAB, which gives the current line the correct indentation as determined from the previous lines. The function that TAB runs depends on the major mode; it is lisp-indent-line in Lisp mode, c-indent-line in C mode, etc. These functions understand different syntaxes for different languages, but they all do about the same thing. TAB in any programming-language major mode inserts or deletes whitespace at the beginning of the current line, independent of where point is in the line. If point is inside the whitespace at the beginning of the line, TAB leaves it at the end of that whitespace; otherwise, TAB leaves point fixed with respect to the characters around it.

Use C-q TAB to insert a tab at point.

When entering lines of new code, use C-j (newline-and-indent), which is equivalent to a RET followed by a TAB. C-j creates a blank line and then gives it the appropriate indentation.

TAB indents the second and following lines of the body of a parenthetical grouping each under the preceding one; therefore, if you alter one line's indentation to be nonstandard, the lines below will tend to follow it. This behavior is convenient in cases where you have overridden the standard result of TAB because you find it unaesthetic for a particular line.

Remember that an open-parenthesis, open-brace or other opening delimiter at the left margin is assumed by Emacs (including the indentation routines) to be the start of a function. Therefore, you must never have an opening delimiter in column zero that is not the beginning of a function, not even inside a string. This restriction is vital for making the indentation commands fast; you must simply accept it. See section Defuns, for more information on this.

Indenting Several Lines

When you wish to reindent several lines of code which have been altered or moved to a different level in the list structure, you have several commands available.

C-M-q
Reindent all the lines within one list (indent-sexp).
C-u TAB
Shift an entire list rigidly sideways so that its first line is properly indented.
C-M-\
Reindent all lines in the region (indent-region).

You can reindent the contents of a single list by positioning point before the beginning of it and typing C-M-q (indent-sexp in Lisp mode, c-indent-exp in C mode; also bound to other suitable commands in other modes). The indentation of the line the sexp starts on is not changed; therefore, only the relative indentation within the list, and not its position, is changed. To correct the position as well, type a TAB before the C-M-q.

If the relative indentation within a list is correct but the indentation of its first line is not, go to that line and type C-u TAB. TAB with a numeric argument reindents the current line as usual, then reindents by the same amount all the lines in the grouping starting on the current line. In other words, it reindents the whole grouping rigidly as a unit. It is clever, though, and does not alter lines that start inside strings, or C preprocessor lines when in C mode.

Another way to specify the range to be reindented is with the region. The command C-M-\ (indent-region) applies TAB to every line whose first character is between point and mark.

Customizing Lisp Indentation

The indentation pattern for a Lisp expression can depend on the function called by the expression. For each Lisp function, you can choose among several predefined patterns of indentation, or define an arbitrary one with a Lisp program.

The standard pattern of indentation is as follows: the second line of the expression is indented under the first argument, if that is on the same line as the beginning of the expression; otherwise, the second line is indented underneath the function name. Each following line is indented under the previous line whose nesting depth is the same.

If the variable lisp-indent-offset is non-nil, it overrides the usual indentation pattern for the second line of an expression, so that such lines are always indented lisp-indent-offset more columns than the containing list.

The standard pattern is overridden for certain functions. Functions whose names start with def always indent the second line by lisp-body-indent extra columns beyond the open-parenthesis starting the expression.

The standard pattern can be overridden in various ways for individual functions, according to the lisp-indent-function property of the function name. There are four possibilities for this property:

nil
This is the same as no property; the standard indentation pattern is used.
defun
The pattern used for function names that start with def is used for this function also.
a number, number
The first number arguments of the function are distinguished arguments; the rest are considered the body of the expression. A line in the expression is indented according to whether the first argument on it is distinguished or not. If the argument is part of the body, the line is indented lisp-body-indent more columns than the open-parenthesis starting the containing expression. If the argument is distinguished and is either the first or second argument, it is indented twice that many extra columns. If the argument is distinguished and not the first or second argument, the standard pattern is followed for that line.
a symbol, symbol
symbol should be a function name; that function is called to calculate the indentation of a line within this expression. The function receives two arguments:
state
The value returned by parse-partial-sexp (a Lisp primitive for indentation and nesting computation) when it parses up to the beginning of this line.
pos
The position at which the line being indented begins.
It should return either a number, which is the number of columns of indentation for that line, or a list whose car is such a number. The difference between returning a number and returning a list is that a number says that all following lines at the same nesting level should be indented just like this one; a list says that following lines might call for different indentations. This makes a difference when the indentation is being computed by C-M-q; if the value is a number, C-M-q need not recalculate indentation for the following lines until the end of the list.

Commands for C Indentation

Here are the commands for indentation in C mode and related modes:

C-c C-q
Reindent the current top-level function definition or aggregate type declaration (c-indent-defun).
C-M-q
Reindent each line in the balanced expression that follows point (c-indent-exp). A prefix argument inhibits error checking and warning messages about invalid syntax.
TAB
Reindent the current line, and/or in some cases insert a tab character (c-indent-command). If c-tab-always-indent is t, this command always reindents the current line and does nothing else. This is the default. If that variable is nil, this command reindents the current line only if point is at the left margin or in the line's indentation; otherwise, it inserts a tab (or the equivalent number of spaces, if indent-tabs-mode is nil). Any other value (not nil or t) means always reindent the line, and also insert a tab if within a comment, a string, or a preprocessor directive.
C-u TAB
Reindent the current line according to its syntax; also rigidly reindent any other lines of the expression that starts on the current line. See section Indenting Several Lines.

To reindent the whole current buffer, type C-x h C-M-\. This first selects the whole buffer as the region, then reindents that region.

To reindent the current block, use C-M-u C-M-q. This moves to the front of the block and then reindents it all.

Customizing C Indentation

C mode and related modes use a simple yet flexible mechanism for customizing indentation. The mechanism works in two steps: first it classifies the line syntactically according to its contents and context; second, it associates each kind of syntactic construct with an indentation offset which you can customize.

Step 1--Syntactic Analysis

In the first step, the C indentation mechanism looks at the line before the one you are currently indenting and determines the syntactic components of the construct on that line. It builds a list of these syntactic components, each of which contains a syntactic symbol and sometimes also a buffer position. Some syntactic symbols describe grammatical elements, for example statement and substatement; others describe locations amidst grammatical elements, for example class-open and knr-argdecl.

Conceptually, a line of C code is always indented relative to the indentation of some line higher up in the buffer. This is represented by the buffer positions in the syntactic component list.

Here is an example. Suppose we have the following code in a C++ mode buffer (the line numbers don't actually appear in the buffer):

1: void swap (int& a, int& b)
2: {
3:   int tmp = a;
4:   a = b;
5:   b = tmp;
6: }

If you type C-c C-s (which runs the command c-show-syntactic-information) on line 4, it shows the result of the indentation mechanism for that line:

((statement . 32))

This indicates that the line is a statement and it is indented relative to buffer position 32, which happens to be the `i' in int on line 3. If you move the cursor to line 3 and type C-c C-s, it displays this:

((defun-block-intro . 28))

This indicates that the int line is the first statement in a block, and is indented relative to buffer position 28, which is the brace just after the function header.

Here is another example:

1: int add (int val, int incr, int doit)
2: {
3:   if (doit)
4:     {
5:       return (val + incr);
6:     }
7:   return (val);
8: }

Typing C-c C-s on line 4 displays this:

((substatement-open . 43))

This says that the brace opens a substatement block. By the way, a substatement indicates the line after an if, else, while, do, switch, for, try, catch, finally, or synchronized statement.

Within the C indentation commands, after a line has been analyzed syntactically for indentation, the variable c-syntactic-context contains a list that describes the results. Each element in this list is a syntactic component: a cons cell containing a syntactic symbol and (optionally) its corresponding buffer position. There may be several elements in a component list; typically only one element has a buffer position.

Step 2--Indentation Calculation

The C indentation mechanism calculates the indentation for the current line using the list of syntactic components, c-syntactic-context, derived from syntactic analysis. Each component is a cons cell that contains a syntactic symbol and may also contain a buffer position.

Each component contributes to the final total indentation of the line in two ways. First, the syntactic symbol identifies an element of c-offsets-alist, which is an association list mapping syntactic symbols into indentation offsets. Each syntactic symbol's offset adds to the total indentation. Second, if the component includes a buffer position, the column number of that position adds to the indentation. All these offsets and column numbers, added together, give the total indentation.

The following examples demonstrate the workings of the C indentation mechanism:

1: void swap (int& a, int& b)
2: {
3:   int tmp = a;
4:   a = b;
5:   b = tmp;
6: }

Suppose that point is on line 3 and you type TAB to reindent the line. As explained above (see section Step 1--Syntactic Analysis), the syntactic component list for that line is:

((defun-block-intro . 28))

In this case, the indentation calculation first looks up defun-block-intro in the c-offsets-alist alist. Suppose that it finds the integer 2; it adds this to the running total (initialized to zero), yielding a updated total indentation of 2 spaces.

The next step is to find the column number of buffer position 28. Since the brace at buffer position 28 is in column zero, this adds 0 to the running total. Since this line has only one syntactic component, the total indentation for the line is 2 spaces.

1: int add (int val, int incr, int doit)
2: {
3:   if (doit)
4:     {
5:       return(val + incr);
6:     }
7:   return(val);
8: }

If you type TAB on line 4, the same process is performed, but with different data. The syntactic component list for this line is:

((substatement-open . 43))

Here, the indentation calculation's first job is to look up the symbol substatement-open in c-offsets-alist. Let's assume that the offset for this symbol is 2. At this point the running total is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43, which is the `i' in if on line 3. This character is in column 2 on that line. Adding this yields a total indentation of 4 spaces.

If a syntactic symbol in the analysis of a line does not appear in c-offsets-alist, it is ignored; if in addition the variable c-strict-syntax-p is non-nil, it is an error.

Changing Indentation Style

There are two ways to customize the indentation style for the C-like modes. First, you can select one of several predefined styles, each of which specifies offsets for all the syntactic symbols. For more flexibility, you can customize the handling of individual syntactic symbols. See section Syntactic Symbols, for a list of all defined syntactic symbols.

M-x c-set-style RET style RET
Select predefined indentation style style. Type ? when entering style to see a list of supported styles; to find out what a style looks like, select it and reindent some C code.
C-c C-o symbol RET offset RET
Set the indentation offset for syntactic symbol symbol (c-set-offset). The second argument offset specifies the new indentation offset.

The c-offsets-alist variable controls the amount of indentation to give to each syntactic symbol. Its value is an association list, and each element of the list has the form (syntactic-symbol . offset). By changing the offsets for various syntactic symbols, you can customize indentation in fine detail. To change this alist, use c-set-offset (see below).

Each offset value in c-offsets-alist can be an integer, a function or variable name, a list, or one of the following symbols: +, -, ++, --, *, or /, indicating positive or negative multiples of the variable c-basic-offset. Thus, if you want to change the levels of indentation to be 3 spaces instead of 2 spaces, set c-basic-offset to 3.

Using a function as the offset value provides the ultimate flexibility in customizing indentation. The function is called with a single argument containing the cons of the syntactic symbol and the buffer position, if any. The function should return an integer offset. If the offset value is a list, its elements are processed according to the rules above until a non-nil value is found. That value is then added to the total indentation in the normal manner. The primary use for this is to combine the results of several functions.

The command C-c C-o (c-set-offset) is the easiest way to set offsets, both interactively or in your `~/.emacs' file. First specify the syntactic symbol, then the offset you want. See section Syntactic Symbols, for a list of valid syntactic symbols and their meanings.

Syntactic Symbols

Here is a table of valid syntactic symbols for indentation in C and related modes, with their syntactic meanings. Normally, most of these symbols are assigned offsets in c-offsets-alist.

string
Inside a multi-line string.
c
Inside a multi-line C style block comment.
defun-open
On a brace that opens a function definition.
defun-close
On a brace that closes a function definition.
defun-block-intro
In the first line in a top-level defun.
class-open
On a brace that opens a class definition.
class-close
On a brace that closes a class definition.
inline-open
On a brace that opens an in-class inline method.
inline-close
On a brace that closes an in-class inline method.
extern-lang-open
On a brace that opens an external language block.
extern-lang-close
On a brace that closes an external language block.
func-decl-cont
The region between a function definition's argument list and the defun opening brace (excluding K&R function definitions). In C, you cannot put anything but whitespace and comments between them; in C++ and Java, throws declarations and other things can appear in this context.
knr-argdecl-intro
On the first line of a K&R C argument declaration.
knr-argdecl
In one of the subsequent lines in a K&R C argument declaration.
topmost-intro
On the first line in a topmost construct definition.
topmost-intro-cont
On the topmost definition continuation lines.
member-init-intro
On the first line in a member initialization list.
member-init-cont
On one of the subsequent member initialization list lines.
inher-intro
On the first line of a multiple inheritance list.
inher-cont
On one of the subsequent multiple inheritance lines.
block-open
On a statement block open brace.
block-close
On a statement block close brace.
brace-list-open
On the opening brace of an enum or static array list.
brace-list-close
On the closing brace of an enum or static array list.
brace-list-intro
On the first line in an enum or static array list.
brace-list-entry
On one of the subsequent lines in an enum or static array list.
brace-entry-open
On one of the subsequent lines in an enum or static array list, when the line begins with an open brace.
statement
On an ordinary statement.
statement-cont
On a continuation line of a statement.
statement-block-intro
On the first line in a new statement block.
statement-case-intro
On the first line in a case "block."
statement-case-open
On the first line in a case block starting with brace.
inexpr-statement
On a statement block inside an expression. This is used for a GNU extension to the C language, and for Pike special functions that take a statement block as an argument.
inexpr-class
On a class definition inside an expression. This is used for anonymous classes and anonymous array initializers in Java.
substatement
On the first line after an if, while, for, do, or else.
substatement-open
On the brace that opens a substatement block.
case-label
On a case or default label.
access-label
On a C++ private, protected, or public access label.
label
On any ordinary label.
do-while-closure
On the while that ends a do-while construct.
else-clause
On the else of an if-else construct.
catch-clause
On the catch and finally lines in try...catch constructs in C++ and Java.
comment-intro
On a line containing only a comment introduction.
arglist-intro
On the first line in an argument list.
arglist-cont
On one of the subsequent argument list lines when no arguments follow on the same line as the arglist opening parenthesis.
arglist-cont-nonempty
On one of the subsequent argument list lines when at least one argument follows on the same line as the arglist opening parenthesis.
arglist-close
On the closing parenthesis of an argument list.
stream-op
On one of the lines continuing a stream operator construct.
inclass
On a construct that is nested inside a class definition. The indentation is relative to the open brace of the class definition.
inextern-lang
On a construct that is nested inside an external language block.
inexpr-statement
On the first line of statement block inside an expression. This is used for the GCC extension to C that uses the syntax ({ ... }). It is also used for the special functions that takes a statement block as an argument in Pike.
inexpr-class
On the first line of a class definition inside an expression. This is used for anonymous classes and anonymous array initializers in Java.
cpp-macro
On the start of a cpp macro.
friend
On a C++ friend declaration.
objc-method-intro
On the first line of an Objective-C method definition.
objc-method-args-cont
On one of the lines continuing an Objective-C method definition.
objc-method-call-cont
On one of the lines continuing an Objective-C method call.
inlambda
Like inclass, but used inside lambda (i.e. anonymous) functions. Only used in Pike.
lambda-intro-cont
On a line continuing the header of a lambda function, between the lambda keyword and the function body. Only used in Pike.

Variables for C Indentation

This section describes additional variables which control the indentation behavior of C mode and related mode.

c-offsets-alist
Association list of syntactic symbols and their indentation offsets. You should not set this directly, only with c-set-offset. See section Changing Indentation Style, for details.
c-style-alist
Variable for defining indentation styles; see below.
c-basic-offset
Amount of basic offset used by + and - symbols in c-offsets-alist.
c-special-indent-hook
Hook for user-defined special indentation adjustments. This hook is called after a line is indented by C mode and related modes.

The variable c-style-alist specifies the predefined indentation styles. Each element has form (name variable-setting...), where name is the name of the style. Each variable-setting has the form (variable . value); variable is one of the customization variables used by C mode, and value is the value for that variable when using the selected style.

When variable is c-offsets-alist, that is a special case: value is appended to the front of the value of c-offsets-alist instead of replacing that value outright. Therefore, it is not necessary for value to specify each and every syntactic symbol--only those for which the style differs from the default.

The indentation of lines containing only comments is also affected by the variable c-comment-only-line-offset (see section Comments in C Modes).

C Indentation Styles

A C style is a collection of indentation style customizations. Emacs comes with several predefined indentation styles for C and related modes, including gnu, k&r, bsd, stroustrup, linux, python, java, whitesmith, ellemtel, and cc-mode. The default style is gnu.

To choose the style you want, use the command M-x c-set-style. Specify a style name as an argument (case is not significant in C style names). The chosen style only affects newly visited buffers, not those you are already editing. You can also set the variable c-default-style to specify the style for various major modes. Its value should be an alist, in which each element specifies one major mode and which indentation style to use for it. For example,

(setq c-default-style
      '((java-mode . "java") (other . "gnu")))

specifies an explicit choice for Java mode, and the default `gnu' style for the other C-like modes.

To define a new C indentation style, call the function c-add-style:

(c-add-style name values use-now)

Here name is the name of the new style (a string), and values is an alist whose elements have the form (variable . value). The variables you specify should be among those documented in section Variables for C Indentation.

If use-now is non-nil, c-add-style switches to the new style after defining it.

Automatic Display Of Matching Parentheses

The Emacs parenthesis-matching feature is designed to show automatically how parentheses match in the text. Whenever you type a self-inserting character that is a closing delimiter, the cursor moves momentarily to the location of the matching opening delimiter, provided that is on the screen. If it is not on the screen, some text near it is displayed in the echo area. Either way, you can tell what grouping is being closed off.

In Lisp, automatic matching applies only to parentheses. In C, it applies to braces and brackets too. Emacs knows which characters to regard as matching delimiters based on the syntax table, which is set by the major mode. See section The Syntax Table.

If the opening delimiter and closing delimiter are mismatched--such as in `[x)'---a warning message is displayed in the echo area. The correct matches are specified in the syntax table.

Three variables control parenthesis match display. blink-matching-paren turns the feature on or off; nil turns it off, but the default is t to turn match display on. blink-matching-delay says how many seconds to wait; the default is 1, but on some systems it is useful to specify a fraction of a second. blink-matching-paren-distance specifies how many characters back to search to find the matching opening delimiter. If the match is not found in that far, scanning stops, and nothing is displayed. This is to prevent scanning for the matching delimiter from wasting lots of time when there is no match. The default is 12,000.

When using X Windows, you can request a more powerful alternative kind of automatic parenthesis matching by enabling Show Paren mode. This mode turns off the usual kind of matching parenthesis display and instead uses highlighting to show what matches. Whenever point is after a close parenthesis, the close parenthesis and its matching open parenthesis are both highlighted; otherwise, if point is before an open parenthesis, the matching close parenthesis is highlighted. (There is no need to highlight the open parenthesis after point because the cursor appears on top of that character.) Use the command M-x show-paren-mode to enable or disable this mode.

Manipulating Comments

Because comments are such an important part of programming, Emacs provides special commands for editing and inserting comments.

Comment Commands

The comment commands insert, kill and align comments.

M-;
Insert or align comment (indent-for-comment).
C-x ;
Set comment column (set-comment-column).
C-u - C-x ;
Kill comment on current line (kill-comment).
C-M-j
Like RET followed by inserting and aligning a comment (indent-new-comment-line).
M-x comment-region
Add or remove comment delimiters on all the lines in the region.

The command that creates a comment is M-; (indent-for-comment). If there is no comment already on the line, a new comment is created, aligned at a specific column called the comment column. The comment is created by inserting the string Emacs thinks comments should start with (the value of comment-start; see below). Point is left after that string. If the text of the line extends past the comment column, then the indentation is done to a suitable boundary (usually, at least one space is inserted). If the major mode has specified a string to terminate comments, that is inserted after point, to keep the syntax valid.

M-; can also be used to align an existing comment. If a line already contains the string that starts comments, then M-; just moves point after it and reindents it to the conventional place. Exception: comments starting in column 0 are not moved.

Some major modes have special rules for indenting certain kinds of comments in certain contexts. For example, in Lisp code, comments which start with two semicolons are indented as if they were lines of code, instead of at the comment column. Comments which start with three semicolons are supposed to start at the left margin. Emacs understands these conventions by indenting a double-semicolon comment using TAB, and by not changing the indentation of a triple-semicolon comment at all.

;; This function is just an example
;;; Here either two or three semicolons are appropriate.
(defun foo (x)
;;; And now, the first part of the function:
  ;; The following line adds one.
  (1+ x))           ; This line adds one.

In C code, a comment preceded on its line by nothing but whitespace is indented like a line of code.

Even when an existing comment is properly aligned, M-; is still useful for moving directly to the start of the comment.

C-u - C-x ; (kill-comment) kills the comment on the current line, if there is one. The indentation before the start of the comment is killed as well. If there does not appear to be a comment in the line, nothing is done. To reinsert the comment on another line, move to the end of that line, do C-y, and then do M-; to realign it. Note that C-u - C-x ; is not a distinct key; it is C-x ; (set-comment-column) with a negative argument. That command is programmed so that when it receives a negative argument it calls kill-comment. However, kill-comment is a valid command which you could bind directly to a key if you wanted to.

Multiple Lines of Comments

If you are typing a comment and wish to continue it on another line, you can use the command C-M-j (indent-new-comment-line). This terminates the comment you are typing, creates a new blank line afterward, and begins a new comment indented under the old one. When Auto Fill mode is on, going past the fill column while typing a comment causes the comment to be continued in just this fashion. If point is not at the end of the line when C-M-j is typed, the text on the rest of the line becomes part of the new comment line.

To turn existing lines into comment lines, use the M-x comment-region command. It adds comment delimiters to the lines that start in the region, thus commenting them out. With a negative argument, it does the opposite--it deletes comment delimiters from the lines in the region.

With a positive argument, comment-region duplicates the last character of the comment start sequence it adds; the argument specifies how many copies of the character to insert. Thus, in Lisp mode, C-u 2 M-x comment-region adds `;;' to each line. Duplicating the comment delimiter is a way of calling attention to the comment. It can also affect how the comment is indented. In Lisp, for proper indentation, you should use an argument of two, if between defuns, and three, if within a defun.

The variable comment-padding specifies how many spaces comment-region should insert on each line between the comment delimiter and the line's original text. The default is 1.

Options Controlling Comments

The comment column is stored in the variable comment-column. You can set it to a number explicitly. Alternatively, the command C-x ; (set-comment-column) sets the comment column to the column point is at. C-u C-x ; sets the comment column to match the last comment before point in the buffer, and then does a M-; to align the current line's comment under the previous one. Note that C-u - C-x ; runs the function kill-comment as described above.

The variable comment-column is per-buffer: setting the variable in the normal fashion affects only the current buffer, but there is a default value which you can change with setq-default. See section Local Variables. Many major modes initialize this variable for the current buffer.

The comment commands recognize comments based on the regular expression that is the value of the variable comment-start-skip. Make sure this regexp does not match the null string. It may match more than the comment starting delimiter in the strictest sense of the word; for example, in C mode the value of the variable is "/\\*+ *", which matches extra stars and spaces after the `/*' itself. (Note that `\\' is needed in Lisp syntax to include a `\' in the string, which is needed to deny the first star its special meaning in regexp syntax. See section Syntax of Regular Expressions.)

When a comment command makes a new comment, it inserts the value of comment-start to begin it. The value of comment-end is inserted after point, so that it will follow the text that you will insert into the comment. In C mode, comment-start has the value "/* " and comment-end has the value " */".

The variable comment-multi-line controls how C-M-j (indent-new-comment-line) behaves when used inside a comment. If comment-multi-line is nil, as it normally is, then the comment on the starting line is terminated and a new comment is started on the new following line. If comment-multi-line is not nil, then the new following line is set up as part of the same comment that was found on the starting line. This is done by not inserting a terminator on the old line, and not inserting a starter on the new line. In languages where multi-line comments work, the choice of value for this variable is a matter of taste.

The variable comment-indent-function should contain a function that will be called to compute the indentation for a newly inserted comment or for aligning an existing comment. It is set differently by various major modes. The function is called with no arguments, but with point at the beginning of the comment, or at the end of a line if a new comment is to be inserted. It should return the column in which the comment ought to start. For example, in Lisp mode, the indent hook function bases its decision on how many semicolons begin an existing comment, and on the code in the preceding lines.

Editing Without Unbalanced Parentheses

M-(
Put parentheses around next sexp(s) (insert-parentheses).
M-)
Move past next close parenthesis and reindent (move-past-close-and-reindent).

The commands M-( (insert-parentheses) and M-) (move-past-close-and-reindent) are designed to facilitate a style of editing which keeps parentheses balanced at all times. M-( inserts a pair of parentheses, either together as in `()', or, if given an argument, around the next several sexps. It leaves point after the open parenthesis. The command M-) moves past the close parenthesis, deleting any indentation preceding it, and indenting with C-j after it.

For example, instead of typing ( F O O ), you can type M-( F O O, which has the same effect except for leaving the cursor before the close parenthesis.

M-( may insert a space before the open parenthesis, depending on the syntax class of the preceding character. Set parens-require-spaces to nil value if you wish to inhibit this.

Completion for Symbol Names

Usually completion happens in the minibuffer. But one kind of completion is available in all buffers: completion for symbol names.

The character M-TAB runs a command to complete the partial symbol before point against the set of meaningful symbol names. Any additional characters determined by the partial name are inserted at point.

If the partial name in the buffer has more than one possible completion and they have no additional characters in common, a list of all possible completions is displayed in another window.

In most programming language major modes, M-TAB runs the command complete-symbol, which provides two kinds of completion. Normally it does completion based on a tags table (see section Tags Tables); with a numeric argument (regardless of the value), it does completion based on the names listed in the Info file indexes for your language. Thus, to complete the name of a symbol defined in your own program, use M-TAB with no argument; to complete the name of a standard library function, use C-u M-TAB. Of course, Info-based completion works only if there is an Info file for the standard library functions of your language, and only if it is installed at your site.

In Emacs-Lisp mode, the name space for completion normally consists of nontrivial symbols present in Emacs--those that have function definitions, values or properties. However, if there is an open-parenthesis immediately before the beginning of the partial symbol, only symbols with function definitions are considered as completions. The command which implements this is lisp-complete-symbol.

In Text mode and related modes, M-TAB completes words based on the spell-checker's dictionary. See section Checking and Correcting Spelling.

Which Function Mode

Which Function mode is a minor mode that displays the current function name in the mode line, as you move around in a buffer.

To enable (or disable) Which Function mode, use the command M-x which-function-mode. This command is global; it applies to all buffers, both existing ones and those yet to be created. However, this only affects certain major modes, those listed in the value of which-func-modes. (If the value is t, then Which Function mode applies to all major modes that know how to support it--which are the major modes that support Imenu.)

Documentation Commands

As you edit Lisp code to be run in Emacs, the commands C-h f (describe-function) and C-h v (describe-variable) can be used to print documentation of functions and variables that you want to call. These commands use the minibuffer to read the name of a function or variable to document, and display the documentation in a window.

For extra convenience, these commands provide default arguments based on the code in the neighborhood of point. C-h f sets the default to the function called in the innermost list containing point. C-h v uses the symbol name around or adjacent to point as its default.

For Emacs Lisp code, you can also use Eldoc mode. This minor mode constantly displays in the echo area the argument list for the function being called at point. (In other words, it finds the function call that point is contained in, and displays the argument list of that function.) Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use the command M-x eldoc-mode to enable or disable this feature.

For C, Lisp, and other languages, you can use C-h C-i (info-lookup-symbol) to view the Info documentation for a symbol. You specify the symbol with the minibuffer; by default, it uses the symbol that appears in the buffer at point. The major mode determines where to look for documentation for the symbol--which Info files and which indices. You can also use M-x info-lookup-file to look for documentation for a file name.

You can read the "man page" for an operating system command, library function, or system call, with the M-x manual-entry command. It runs the man program to format the man page, and runs it asynchronously if your system permits, so that you can keep on editing while the page is being formatted. (MS-DOS and MS-Windows 3 do not permit asynchronous subprocesses, so on these systems you cannot edit while Emacs waits for man to exit.) The result goes in a buffer named `*Man topic*'. These buffers use a special major mode, Man mode, that facilitates scrolling and examining other manual pages. For details, type C-h m while in a man page buffer.

For a long man page, setting the faces properly can take substantial time. By default, Emacs uses faces in man pages if Emacs can display different fonts or colors. You can turn off use of faces in man pages by setting the variable Man-fontify-manpage-flag to nil.

If you insert the text of a man page into an Emacs buffer in some other fashion, you can use the command M-x Man-fontify-manpage to perform the same conversions that M-x manual-entry does.

Eventually the GNU project hopes to replace most man pages with better-organized manuals that you can browse with Info. See section Other Help Commands. Since this process is only partially completed, it is still useful to read manual pages.

Change Logs

The Emacs command C-x 4 a adds a new entry to the change log file for the file you are editing (add-change-log-entry-other-window).

A change log file contains a chronological record of when and why you have changed a program, consisting of a sequence of entries describing individual changes. Normally it is kept in a file called `ChangeLog' in the same directory as the file you are editing, or one of its parent directories. A single `ChangeLog' file can record changes for all the files in its directory and all its subdirectories.

A change log entry starts with a header line that contains your name, your email address (taken from the variable user-mail-address), and the current date and time. Aside from these header lines, every line in the change log starts with a space or a tab. The bulk of the entry consists of items, each of which starts with a line starting with whitespace and a star. Here are two entries, both dated in May 1993, each with two items:

@medbreak

1993-05-25  Richard Stallman  <rms@gnu.org>

        * man.el: Rename symbols `man-*' to `Man-*'.
        (manual-entry): Make prompt string clearer.

        * simple.el (blink-matching-paren-distance):
        Change default to 12,000.

1993-05-24  Richard Stallman  <rms@gnu.org>

        * vc.el (minor-mode-map-alist): Don't use it if it's void.
        (vc-cancel-version): Doc fix.

(Previous Emacs versions used a different format for the date.)

One entry can describe several changes; each change should have its own item. Normally there should be a blank line between items. When items are related (parts of the same change, in different places), group them by leaving no blank line between them. The second entry above contains two items grouped in this way.

C-x 4 a visits the change log file and creates a new entry unless the most recent entry is for today's date and your name. It also creates a new item for the current file. For many languages, it can even guess the name of the function or other object that was changed.

The change log file is visited in Change Log mode. In this major mode, each bunch of grouped items counts as one paragraph, and each entry is considered a page. This facilitates editing the entries. C-j and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry.

Version control systems are another way to keep track of changes in your program and keep a change log. See section Features of the Log Entry Buffer.

Tags Tables

A tags table is a description of how a multi-file program is broken up into files. It lists the names of the component files and the names and positions of the functions (or other named subunits) in each file. Grouping the related files makes it possible to search or replace through all the files with one command. Recording the function names and positions makes possible the M-. command which finds the definition of a function by looking up which of the files it is in.

Tags tables are stored in files called tags table files. The conventional name for a tags table file is `TAGS'.

Each entry in the tags table records the name of one tag, the name of the file that the tag is defined in (implicitly), and the position in that file of the tag's definition.

Just what names from the described files are recorded in the tags table depends on the programming language of the described file. They normally include all functions and subroutines, and may also include global variables, data types, and anything else convenient. Each name recorded is called a tag.

Source File Tag Syntax

Here is how tag syntax is defined for the most popular languages:

  • In C code, any C function or typedef is a tag, and so are definitions of struct, union and enum. #define macro definitions and enum constants are also tags, unless you specify `--no-defines' when making the tags table. Similarly, global variables are tags, unless you specify `--no-globals'. Use of `--no-globals' and `--no-defines' can make the tags table file much smaller.
  • In C++ code, in addition to all the tag constructs of C code, member functions are also recognized, and optionally member variables if you use the `--members' option. Tags for variables and functions in classes are named `class::variable' and `class::function'.
  • In Java code, tags include all the constructs recognized in C++, plus the extends and implements constructs. Tags for variables and functions in classes are named `class.variable' and `class.function'.
  • In LaTeX text, the argument of any of the commands \chapter, \section, \subsection, \subsubsection, \eqno, \label, \ref, \cite, \bibitem, \part, \appendix, \entry, or \index, is a tag. Other commands can make tags as well, if you specify them in the environment variable TEXTAGS before invoking etags. The value of this environment variable should be a colon-separated list of command names. For example,
    TEXTAGS="def:newcommand:newenvironment"
export TEXTAGS
    specifies (using Bourne shell syntax) that the commands `\def', `\newcommand' and `\newenvironment' also define tags.
  • In Lisp code, any function defined with defun, any variable defined with defvar or defconst, and in general the first argument of any expression that starts with `(def' in column zero, is a tag.
  • In Scheme code, tags include anything defined with def or with a construct whose name starts with `def'. They also include variables set with set! at top level in the file.

Several other languages are also supported:

  • In assembler code, labels appearing at the beginning of a line, followed by a colon, are tags.
  • In Bison or Yacc input files, each rule defines as a tag the nonterminal it constructs. The portions of the file that contain C code are parsed as C code.
  • In Cobol code, tags are paragraph names; that is, any word starting in column 8 and followed by a period.
  • In Erlang code, the tags are the functions, records, and macros defined in the file.
  • In Fortran code, functions, subroutines and blockdata are tags.
  • In Objective C code, tags include Objective C definitions for classes, class categories, methods, and protocols.
  • In Pascal code, the tags are the functions and procedures defined in the file.
  • In Perl code, the tags are the procedures defined by the sub keyword.
  • In Postscript code, the tags are the functions.
  • In Prolog code, a tag name appears at the left margin.

You can also generate tags based on regexp matching (see section Creating Tags Tables) to handle other formats and languages.

Creating Tags Tables

The etags program is used to create a tags table file. It knows the syntax of several languages, as described in the previous section. Here is how to run etags:

etags inputfiles...

The etags program reads the specified files, and writes a tags table named `TAGS' in the current working directory. etags recognizes the language used in an input file based on its file name and contents. You can specify the language with the `--language=name' option, described below.

If the tags table data become outdated due to changes in the files described in the table, the way to update the tags table is the same way it was made in the first place. It is not necessary to do this often.

If the tags table fails to record a tag, or records it for the wrong file, then Emacs cannot possibly find its definition. However, if the position recorded in the tags table becomes a little bit wrong (due to some editing in the file that the tag definition is in), the only consequence is a slight delay in finding the tag. Even if the stored position is very wrong, Emacs will still find the tag, but it must search the entire file for it.

So you should update a tags table when you define new tags that you want to have listed, or when you move tag definitions from one file to another, or when changes become substantial. Normally there is no need to update the tags table after each edit, or even every day.

One tags table can effectively include another. Specify the included tags file name with the `--include=file' option when creating the file that is to include it. The latter file then acts as if it contained all the files specified in the included file, as well as the files it directly contains.

If you specify the source files with relative file names when you run etags, the tags file will contain file names relative to the directory where the tags file was initially written. This way, you can move an entire directory tree containing both the tags file and the source files, and the tags file will still refer correctly to the source files.

If you specify absolute file names as arguments to etags, then the tags file will contain absolute file names. This way, the tags file will still refer to the same files even if you move it, as long as the source files remain in the same place. Absolute file names start with `/', or with `device:/' on MS-DOS and MS-Windows.

When you want to make a tags table from a great number of files, you may have problems listing them on the command line, because some systems have a limit on its length. The simplest way to circumvent this limit is to tell etags to read the file names from its standard input, by typing a dash in place of the file names, like this:

find . -name "*.[chCH]" -print | etags -

Use the option `--language=name' to specify the language explicitly. You can intermix these options with file names; each one applies to the file names that follow it. Specify `--language=auto' to tell etags to resume guessing the language from the file names and file contents. Specify `--language=none' to turn off language-specific processing entirely; then etags recognizes tags by regexp matching alone. `etags --help' prints the list of the languages etags knows, and the file name rules for guessing the language.

The `--regex' option provides a general way of recognizing tags based on regexp matching. You can freely intermix it with file names. Each `--regex' option adds to the preceding ones, and applies only to the following files. The syntax is:

--regex=/tagregexp[/nameregexp]/

where tagregexp is used to match the lines to tag. It is always anchored, that is, it behaves as if preceded by `^'. If you want to account for indentation, just match any initial number of blanks by beginning your regular expression with `[ \t]*'. In the regular expressions, `\' quotes the next character, and `\t' stands for the tab character. Note that etags does not handle the other C escape sequences for special characters.

The syntax of regular expressions in etags is the same as in Emacs, augmented with the interval operator, which works as in grep and ed. The syntax of an interval operator is `\{m,n\}', and its meaning is to match the preceding expression at least m times and up to n times.

You should not match more characters with tagregexp than that needed to recognize what you want to tag. If the match is such that more characters than needed are unavoidably matched by tagregexp, you may find useful to add a nameregexp, in order to narrow the tag scope. You can find some examples below.

The `-R' option deletes all the regexps defined with `--regex' options. It applies to the file names following it, as you can see from the following example:

etags --regex=/reg1/ voo.doo --regex=/reg2/ \
    bar.ber -R --lang=lisp los.er

Here etags chooses the parsing language for `voo.doo' and `bar.ber' according to their contents. etags also uses reg1 to recognize additional tags in `voo.doo', and both reg1 and reg2 to recognize additional tags in `bar.ber'. etags uses the Lisp tags rules, and no regexp matching, to recognize tags in `los.er'.

Here are some more examples. The regexps are quoted to protect them from shell interpretation.

  • Tag the DEFVAR macros in the emacs source files:
    --regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
  • Tag VHDL files (this example is a single long line, broken here for formatting reasons):
    --language=none
--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
  • Tag Tcl files (this last example shows the usage of a nameregexp):
    --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'

For a list of the other available etags options, execute etags --help.

Selecting a Tags Table

Emacs has at any time one selected tags table, and all the commands for working with tags tables use the selected one. To select a tags table, type M-x visit-tags-table, which reads the tags table file name as an argument. The name `TAGS' in the default directory is used as the default file name.

All this command does is store the file name in the variable tags-file-name. Emacs does not actually read in the tags table contents until you try to use them. Setting this variable yourself is just as good as using visit-tags-table. The variable's initial value is nil; that value tells all the commands for working with tags tables that they must ask for a tags table file name to use.

Using visit-tags-table when a tags table is already loaded gives you a choice: you can add the new tags table to the current list of tags tables, or start a new list. The tags commands use all the tags tables in the current list. If you start a new list, the new tags table is used instead of others. If you add the new table to the current list, it is used as well as the others. When the tags commands scan the list of tags tables, they don't always start at the beginning of the list; they start with the first tags table (if any) that describes the current file, proceed from there to the end of the list, and then scan from the beginning of the list until they have covered all the tables in the list.

You can specify a precise list of tags tables by setting the variable tags-table-list to a list of strings, like this:

(setq tags-table-list
      '("~/emacs" "/usr/local/lib/emacs/src"))

This tells the tags commands to look at the `TAGS' files in your `~/emacs' directory and in the `/usr/local/lib/emacs/src' directory. The order depends on which file you are in and which tags table mentions that file, as explained above.

Do not set both tags-file-name and tags-table-list.

Finding a Tag

The most important thing that a tags table enables you to do is to find the definition of a specific tag.

M-. tag RET
Find first definition of tag (find-tag).
C-u M-.
Find next alternate definition of last tag specified.
C-u - M-.
Go back to previous tag found.
C-M-. pattern RET
Find a tag whose name matches pattern (find-tag-regexp).
C-u C-M-.
Find the next tag whose name matches the last pattern used.
C-x 4 . tag RET
Find first definition of tag, but display it in another window (find-tag-other-window).
C-x 5 . tag RET
Find first definition of tag, and create a new frame to select the buffer (find-tag-other-frame).
M-*
Pop back to where you previously invoked M-. and friends.

M-. (find-tag) is the command to find the definition of a specified tag. It searches through the tags table for that tag, as a string, and then uses the tags table info to determine the file that the definition is in and the approximate character position in the file of the definition. Then find-tag visits that file, moves point to the approximate character position, and searches ever-increasing distances away to find the tag definition.

If an empty argument is given (just type RET), the sexp in the buffer before or around point is used as the tag argument. See section Lists and Sexps, for info on sexps.

You don't need to give M-. the full name of the tag; a part will do. This is because M-. finds tags in the table which contain tag as a substring. However, it prefers an exact match to a substring match. To find other tags that match the same substring, give find-tag a numeric argument, as in C-u M-.; this does not read a tag name, but continues searching the tags table's text for another tag containing the same substring last used. If you have a real META key, M-0 M-. is an easier alternative to C-u M-..

Like most commands that can switch buffers, find-tag has a variant that displays the new buffer in another window, and one that makes a new frame for it. The former is C-x 4 ., which invokes the command find-tag-other-window. The latter is C-x 5 ., which invokes find-tag-other-frame.

To move back to places you've found tags recently, use C-u - M-.; more generally, M-. with a negative numeric argument. This command can take you to another buffer. C-x 4 . with a negative argument finds the previous tag location in another window.

As well as going back to places you've found tags recently, you can go back to places from where you found them. Use M-*, which invokes the command pop-tag-mark, for this. Typically you would find and study the definition of something with M-. and then return to where you were with M-*.

Both C-u - M-. and M-* allow you to retrace your steps to a depth determined by the variable find-tag-marker-ring-length.

The command C-M-. (find-tag-regexp) visits the tags that match a specified regular expression. It is just like M-. except that it does regexp matching instead of substring matching.

Searching and Replacing with Tags Tables

The commands in this section visit and search all the files listed in the selected tags table, one by one. For these commands, the tags table serves only to specify a sequence of files to search.

M-x tags-search RET regexp RET
Search for regexp through the files in the selected tags table.
M-x tags-query-replace RET regexp RET replacement RET
Perform a query-replace-regexp on each file in the selected tags table.
M-,
Restart one of the commands above, from the current location of point (tags-loop-continue).

M-x tags-search reads a regexp using the minibuffer, then searches for matches in all the files in the selected tags table, one file at a time. It displays the name of the file being searched so you can follow its progress. As soon as it finds an occurrence, tags-search returns.

Having found one match, you probably want to find all the rest. To find one more match, type M-, (tags-loop-continue) to resume the tags-search. This searches the rest of the current buffer, followed by the remaining files of the tags table.

M-x tags-query-replace performs a single query-replace-regexp through all the files in the tags table. It reads a regexp to search for and a string to replace with, just like ordinary M-x query-replace-regexp. It searches much like M-x tags-search, but repeatedly, processing matches according to your input. See section Replacement Commands, for more information on query replace.

It is possible to get through all the files in the tags table with a single invocation of M-x tags-query-replace. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query replace subsequently by typing M-,; this command resumes the last tags search or replace command that you did.

The commands in this section carry out much broader searches than the find-tag family. The find-tag commands search only for definitions of tags that match your substring or regexp. The commands tags-search and tags-query-replace find every occurrence of the regexp, as ordinary search commands and replace commands do in the current buffer.

These commands create buffers only temporarily for the files that they have to search (those which are not already visited in Emacs buffers). Buffers in which no match is found are quickly killed; the others continue to exist.

It may have struck you that tags-search is a lot like grep. You can also run grep itself as an inferior of Emacs and have Emacs show you the matching lines one by one. This works much like running a compilation; finding the source locations of the grep matches works like finding the compilation errors. See section Running Compilations under Emacs.

Tags Table Inquiries

M-x list-tags RET file RET
Display a list of the tags defined in the program file file.
M-x tags-apropos RET regexp RET
Display a list of all tags matching regexp.

M-x list-tags reads the name of one of the files described by the selected tags table, and displays a list of all the tags defined in that file. The "file name" argument is really just a string to compare against the file names recorded in the tags table; it is read as a string rather than as a file name. Therefore, completion and defaulting are not available, and you must enter the file name the same way it appears in the tags table. Do not include a directory as part of the file name unless the file name recorded in the tags table includes a directory.

M-x tags-apropos is like apropos for tags (see section Apropos). It reads a regexp, then finds all the tags in the selected tags table whose entries match that regexp, and displays the tag names found.

You can also perform completion in the buffer on the name space of tag names in the current tags tables. See section Completion for Symbol Names.

Merging Files with Emerge

It's not unusual for programmers to get their signals crossed and modify the same program in two different directions. To recover from this confusion, you need to merge the two versions. Emerge makes this easier. See also section Comparing Files, for commands to compare in a more manual fashion, and section `Emerge' in The Ediff Manual.

Overview of Emerge

To start Emerge, run one of these four commands:

M-x emerge-files
Merge two specified files.
M-x emerge-files-with-ancestor
Merge two specified files, with reference to a common ancestor.
M-x emerge-buffers
Merge two buffers.
M-x emerge-buffers-with-ancestor
Merge two buffers with reference to a common ancestor in a third buffer.

The Emerge commands compare two files or buffers, and display the comparison in three buffers: one for each input text (the A buffer and the B buffer), and one (the merge buffer) where merging takes place. The merge buffer shows the full merged text, not just the differences. Wherever the two input texts differ, you can choose which one of them to include in the merge buffer.

The Emerge commands that take input from existing buffers use only the accessible portions of those buffers, if they are narrowed (see section Narrowing).

If a common ancestor version is available, from which the two texts to be merged were both derived, Emerge can use it to guess which alternative is right. Wherever one current version agrees with the ancestor, Emerge presumes that the other current version is a deliberate change which should be kept in the merged version. Use the `with-ancestor' commands if you want to specify a common ancestor text. These commands read three file or buffer names--variant A, variant B, and the common ancestor.

After the comparison is done and the buffers are prepared, the interactive merging starts. You control the merging by typing special merge commands in the merge buffer. The merge buffer shows you a full merged text, not just differences. For each run of differences between the input texts, you can choose which one of them to keep, or edit them both together.

The merge buffer uses a special major mode, Emerge mode, with commands for making these choices. But you can also edit the buffer with ordinary Emacs commands.

At any given time, the attention of Emerge is focused on one particular difference, called the selected difference. This difference is marked off in the three buffers like this:

vvvvvvvvvvvvvvvvvvvv
text that differs
^^^^^^^^^^^^^^^^^^^^

Emerge numbers all the differences sequentially and the mode line always shows the number of the selected difference.

Normally, the merge buffer starts out with the A version of the text. But when the A version of a difference agrees with the common ancestor, then the B version is initially preferred for that difference.

Emerge leaves the merged text in the merge buffer when you exit. At that point, you can save it in a file with C-x C-w. If you give a numeric argument to emerge-files or emerge-files-with-ancestor, it reads the name of the output file using the minibuffer. (This is the last file name those commands read.) Then exiting from Emerge saves the merged text in the output file.

Normally, Emerge commands save the output buffer in its file when you exit. If you abort Emerge with C-], the Emerge command does not save the output buffer, but you can save it yourself if you wish.

Submodes of Emerge

You can choose between two modes for giving merge commands: Fast mode and Edit mode. In Fast mode, basic merge commands are single characters, but ordinary Emacs commands are disabled. This is convenient if you use only merge commands. In Edit mode, all merge commands start with the prefix key C-c C-c, and the normal Emacs commands are also available. This allows editing the merge buffer, but slows down Emerge operations.

Use e to switch to Edit mode, and C-c C-c f to switch to Fast mode. The mode line indicates Edit and Fast modes with `E' and `F'.

Emerge has two additional submodes that affect how particular merge commands work: Auto Advance mode and Skip Prefers mode.

If Auto Advance mode is in effect, the a and b commands advance to the next difference. This lets you go through the merge faster as long as you simply choose one of the alternatives from the input. The mode line indicates Auto Advance mode with `A'.

If Skip Prefers mode is in effect, the n and p commands skip over differences in states prefer-A and prefer-B (see section State of a Difference). Thus you see only differences for which neither version is presumed "correct." The mode line indicates Skip Prefers mode with `S'.

Use the command s a (emerge-auto-advance-mode) to set or clear Auto Advance mode. Use s s (emerge-skip-prefers-mode) to set or clear Skip Prefers mode. These commands turn on the mode with a positive argument, turns it off with a negative or zero argument, and toggle the mode with no argument.

State of a Difference

In the merge buffer, a difference is marked with lines of `v' and `^' characters. Each difference has one of these seven states:

A
The difference is showing the A version. The a command always produces this state; the mode line indicates it with `A'.
B
The difference is showing the B version. The b command always produces this state; the mode line indicates it with `B'.
default-A
default-B
The difference is showing the A or the B state by default, because you haven't made a choice. All differences start in the default-A state (and thus the merge buffer is a copy of the A buffer), except those for which one alternative is "preferred" (see below). When you select a difference, its state changes from default-A or default-B to plain A or B. Thus, the selected difference never has state default-A or default-B, and these states are never displayed in the mode line. The command d a chooses default-A as the default state, and d b chooses default-B. This chosen default applies to all differences which you haven't ever selected and for which no alternative is preferred. If you are moving through the merge sequentially, the differences you haven't selected are those following the selected one. Thus, while moving sequentially, you can effectively make the A version the default for some sections of the merge buffer and the B version the default for others by using d a and d b between sections.
prefer-A
prefer-B
The difference is showing the A or B state because it is preferred. This means that you haven't made an explicit choice, but one alternative seems likely to be right because the other alternative agrees with the common ancestor. Thus, where the A buffer agrees with the common ancestor, the B version is preferred, because chances are it is the one that was actually changed. These two states are displayed in the mode line as `A*' and `B*'.
combined
The difference is showing a combination of the A and B states, as a result of the x c or x C commands. Once a difference is in this state, the a and b commands don't do anything to it unless you give them a numeric argument. The mode line displays this state as `comb'.

Merge Commands

Here are the Merge commands for Fast mode; in Edit mode, precede them with C-c C-c:

p
Select the previous difference.
n
Select the next difference.
a
Choose the A version of this difference.
b
Choose the B version of this difference.
C-u n j
Select difference number n.
.
Select the difference containing point. You can use this command in the merge buffer or in the A or B buffer.
q
Quit--finish the merge.
C-]
Abort--exit merging and do not save the output.
f
Go into Fast mode. (In Edit mode, this is actually C-c C-c f.)
e
Go into Edit mode.
l
Recenter (like C-l) all three windows.
-
Specify part of a prefix numeric argument.
digit
Also specify part of a prefix numeric argument.
d a
Choose the A version as the default from here down in the merge buffer.
d b
Choose the B version as the default from here down in the merge buffer.
c a
Copy the A version of this difference into the kill ring.
c b
Copy the B version of this difference into the kill ring.
i a
Insert the A version of this difference at point.
i b
Insert the B version of this difference at point.
m
Put point and mark around the difference.
^
Scroll all three windows down (like M-v).
v
Scroll all three windows up (like C-v).
<
Scroll all three windows left (like C-x <).
>
Scroll all three windows right (like C-x >).
|
Reset horizontal scroll on all three windows.
x 1
Shrink the merge window to one line. (Use C-u l to restore it to full size.)
x c
Combine the two versions of this difference (see section Combining the Two Versions).
x f
Show the names of the files/buffers Emerge is operating on, in a Help window. (Use C-u l to restore windows.)
x j
Join this difference with the following one. (C-u x j joins this difference with the previous one.)
x s
Split this difference into two differences. Before you use this command, position point in each of the three buffers at the place where you want to split the difference.
x t
Trim identical lines off the top and bottom of the difference. Such lines occur when the A and B versions are identical but differ from the ancestor version.

Exiting Emerge

The q command (emerge-quit) finishes the merge, storing the results into the output file if you specified one. It restores the A and B buffers to their proper contents, or kills them if they were created by Emerge and you haven't changed them. It also disables the Emerge commands in the merge buffer, since executing them later could damage the contents of the various buffers.

C-] aborts the merge. This means exiting without writing the output file. If you didn't specify an output file, then there is no real difference between aborting and finishing the merge.

If the Emerge command was called from another Lisp program, then its return value is t for successful completion, or nil if you abort.

Combining the Two Versions

Sometimes you want to keep both alternatives for a particular difference. To do this, use x c, which edits the merge buffer like this:

#ifdef NEW
version from A buffer
#else /* not NEW */
version from B buffer
#endif /* not NEW */

While this example shows C preprocessor conditionals delimiting the two alternative versions, you can specify the strings to use by setting the variable emerge-combine-versions-template to a string of your choice. In the string, `%a' says where to put version A, and `%b' says where to put version B. The default setting, which produces the results shown above, looks like this:

"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"

Fine Points of Emerge

During the merge, you mustn't try to edit the A and B buffers yourself. Emerge modifies them temporarily, but ultimately puts them back the way they were.

You can have any number of merges going at once--just don't use any one buffer as input to more than one merge at once, since the temporary changes made in these buffers would get in each other's way.

Starting Emerge can take a long time because it needs to compare the files fully. Emacs can't do anything else until diff finishes. Perhaps in the future someone will change Emerge to do the comparison in the background when the input files are large--then you could keep on doing other things with Emacs until Emerge is ready to accept commands.

After setting up the merge, Emerge runs the hook emerge-startup-hook (see section Hooks).

C and Related Modes

This section describes special features available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes. When we say "C mode and related modes," those are the modes we mean.

C Mode Motion Commands

This section describes commands for moving point, in C mode and related modes.

C-c C-u
Move point back to the containing preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move point forward to the end of the containing preprocessor conditional. When going backwards, #elif is treated like #else followed by #if. When going forwards, #elif is ignored.
C-c C-p
Move point back over a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move forward.
C-c C-n
Move point forward across a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move backward.
M-a
Move point to the beginning of the innermost C statement (c-beginning-of-statement). If point is already at the beginning of a statement, move to the beginning of the preceding statement. With prefix argument n, move back n - 1 statements. If point is within a string or comment, or next to a comment (only whitespace between them), this command moves by sentences instead of statements. When called from a program, this function takes three optional arguments: the numeric prefix argument, a buffer position limit (don't move back before that place), and a flag that controls whether to do sentence motion when inside of a comment.
M-e
Move point to the end of the innermost C statement; like M-a except that it moves in the other direction (c-end-of-statement).
M-x c-backward-into-nomenclature
Move point backward to beginning of a C++ nomenclature section or word. With prefix argument n, move n times. If n is negative, move forward. C++ nomenclature means a symbol name in the style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter begins a section or word. In the GNU project, we recommend using underscores to separate words within an identifier in C or C++, rather than using case distinctions.
M-x c-forward-into-nomenclature
Move point forward to end of a C++ nomenclature section or word. With prefix argument n, move n times.

Electric C Characters

In C mode and related modes, certain printing characters are "electric"---in addition to inserting themselves, they also reindent the current line and may insert newlines. This feature is controlled by the variable c-auto-newline. The "electric" characters are {, }, :, #, ;, ,, <, >, /, *, (, and ).

Electric characters insert newlines only when the auto-newline feature is enabled (indicated by `/a' in the mode line after the mode name). This feature is controlled by the variable c-auto-newline. You can turn this feature on or off with the command C-c C-a:

C-c C-a
Toggle the auto-newline feature (c-toggle-auto-state). With a prefix argument, this command turns the auto-newline feature on if the argument is positive, and off if it is negative.

The colon character is electric because that is appropriate for a single colon. But when you want to insert a double colon in C++, the electric behavior of colon is inconvenient. You can insert a double colon with no reindentation or newlines by typing C-c ::

C-c :
Insert a double colon scope operator at point, without reindenting the line or adding any newlines (c-scope-operator).

The electric # key reindents the line if it appears to be the beginning of a preprocessor directive. This happens when the value of c-electric-pound-behavior is (alignleft). You can turn this feature off by setting c-electric-pound-behavior to nil.

The variable c-hanging-braces-alist controls the insertion of newlines before and after inserted braces. It is an association list with elements of the following form: (syntactic-symbol . nl-list). Most of the syntactic symbols that appear in c-offsets-alist are meaningful here as well.

The list nl-list may contain either of the symbols before or after, or both; or it may be nil. When a brace is inserted, the syntactic context it defines is looked up in c-hanging-braces-alist; if it is found, the nl-list is used to determine where newlines are inserted: either before the brace, after, or both. If not found, the default is to insert a newline both before and after braces.

The variable c-hanging-colons-alist controls the insertion of newlines before and after inserted colons. It is an association list with elements of the following form: (syntactic-symbol . nl-list). The list nl-list may contain either of the symbols before or after, or both; or it may be nil.

When a colon is inserted, the syntactic symbol it defines is looked up in this list, and if found, the nl-list is used to determine where newlines are inserted: either before the brace, after, or both. If the syntactic symbol is not found in this list, no newlines are inserted.

Electric characters can also delete newlines automatically when the auto-newline feature is enabled. This feature makes auto-newline more acceptable, by deleting the newlines in the most common cases where you do not want them. Emacs can recognize several cases in which deleting a newline might be desirable; by setting the variable c-cleanup-list, you can specify which of these cases that should happen. The variable's value is a list of symbols, each describing one case for possible deletion of a newline. Here are the meaningful symbols, and their meanings:

brace-catch-brace
Clean up `} catch (condition) {' constructs by placing the entire construct on a single line. The clean-up occurs when you type the `{', if there is nothing between the braces aside from catch and condition.
brace-else-brace
Clean up `} else {' constructs by placing the entire construct on a single line. The clean-up occurs when you type the `{' after the else, but only if there is nothing but white space between the braces and the else.
brace-elseif-brace
Clean up `} else if (...) {' constructs by placing the entire construct on a single line. The clean-up occurs when you type the `{', if there is nothing but white space between the `}' and `{' aside from the keywords and the if-condition.
empty-defun-braces
Clean up empty defun braces by placing the braces on the same line. Clean-up occurs when you type the closing brace.
defun-close-semi
Clean up the semicolon after a struct or similar type declaration, by placing the semicolon on the same line as the closing brace. Clean-up occurs when you type the semicolon.
list-close-comma
Clean up commas following braces in array and aggregate initializers. Clean-up occurs when you type the comma.
scope-operator
Clean up double colons which may designate a C++ scope operator, by placing the colons together. Clean-up occurs when you type the second colon, but only when the two colons are separated by nothing but whitespace.

Hungry Delete Feature in C

When the hungry-delete feature is enabled (indicated by `/h' or `/ah' in the mode line after the mode name), a single DEL command deletes all preceding whitespace, not just one space. To turn this feature on or off, use C-c C-d:

C-c C-d
Toggle the hungry-delete feature (c-toggle-hungry-state). With a prefix argument, this command turns the hungry-delete feature on if the argument is positive, and off if it is negative.
C-c C-t
Toggle the auto-newline and hungry-delete features, both at once (c-toggle-auto-hungry-state).

The variable c-hungry-delete-key controls whether the hungry-delete feature is enabled.

Other Commands for C Mode

C-M-h
Put mark at the end of a function definition, and put point at the beginning (c-mark-function).
M-q
Fill a paragraph, handling C and C++ comments (c-fill-paragraph). If any part of the current line is a comment or within a comment, this command fills the comment or the paragraph of it that point is in, preserving the comment indentation and comment delimiters.
C-c C-e
Run the C preprocessor on the text in the region, and show the result, which includes the expansion of all the macro calls (c-macro-expand). The buffer text before the region is also included in preprocessing, for the sake of macros defined there, but the output from this part isn't shown. When you are debugging C code that uses macros, sometimes it is hard to figure out precisely how the macros expand. With this command, you don't have to figure it out; you can see the expansions.
C-c C-\
Insert or align `\' characters at the ends of the lines of the region (c-backslash-region). This is useful after writing or editing a C macro definition. If a line already ends in `\', this command adjusts the amount of whitespace before it. Otherwise, it inserts a new `\'. However, the last line in the region is treated specially; no `\' is inserted on that line, and any `\' there is deleted.
M-x cpp-highlight-buffer
Highlight parts of the text according to its preprocessor conditionals. This command displays another buffer named `*CPP Edit*', which serves as a graphic menu for selecting how to display particular kinds of conditionals and their contents. After changing various settings, click on `[A]pply these settings' (or go to that buffer and type a) to rehighlight the C mode buffer accordingly.
C-c C-s
Display the syntactic information about the current source line (c-show-syntactic-information). This is the information that directs how the line is indented.

Comments in C Modes

C mode and related modes use a number of variables for controlling comment format.

c-comment-only-line-offset
Extra offset for line which contains only the start of a comment. It can be either an integer or a cons cell of the form (non-anchored-offset . anchored-offset), where non-anchored-offset is the amount of offset given to non-column-zero anchored comment-only lines, and anchored-offset is the amount of offset to give column-zero anchored comment-only lines. Just an integer as value is equivalent to (val . 0).
c-comment-start-regexp
This buffer-local variable specifies how to recognize the start of a comment.
c-hanging-comment-ender-p
If this variable is nil, c-fill-paragraph leaves the comment terminator of a block comment on a line by itself. The default value is t, which puts the comment-end delimiter `*/' at the end of the last line of the comment text.
c-hanging-comment-starter-p
If this variable is nil, c-fill-paragraph leaves the starting delimiter of a block comment on a line by itself. The default value is t, which puts the comment-start delimiter `/*' at the beginning of the first line of the comment text.

Fortran Mode

Fortran mode provides special motion commands for Fortran statements and subprograms, and indentation commands that understand Fortran conventions of nesting, line numbers and continuation statements. Fortran mode has its own Auto Fill mode that breaks long lines into proper Fortran continuation lines.

Special commands for comments are provided because Fortran comments are unlike those of other languages. Built-in abbrevs optionally save typing when you insert Fortran keywords.

Use M-x fortran-mode to switch to this major mode. This command runs the hook fortran-mode-hook (see section Hooks).

Motion Commands

Fortran mode provides special commands to move by subprograms (functions and subroutines) and by statements. There is also a command to put the region around one subprogram, convenient for killing it or moving it.

C-M-a
Move to beginning of subprogram (beginning-of-fortran-subprogram).
C-M-e
Move to end of subprogram (end-of-fortran-subprogram).
C-M-h
Put point at beginning of subprogram and mark at end (mark-fortran-subprogram).
C-c C-n
Move to beginning of current or next statement (fortran-next-statement).
C-c C-p
Move to beginning of current or previous statement (fortran-previous-statement).

Fortran Indentation

Special commands and features are needed for indenting Fortran code in order to make sure various syntactic entities (line numbers, comment line indicators and continuation line flags) appear in the columns that are required for standard Fortran.

Fortran Indentation Commands

TAB
Indent the current line (fortran-indent-line).
C-j
Indent the current and start a new indented line (fortran-indent-new-line).
C-M-j
Break the current line and set up a continuation line.
M-^
Join this line to the previous line.
C-M-q
Indent all the lines of the subprogram point is in (fortran-indent-subprogram).

Fortran mode redefines TAB to reindent the current line for Fortran (fortran-indent-line). This command indents line numbers and continuation markers to their required columns, and independently indents the body of the statement based on its nesting in the program.

The key C-j runs the command fortran-indent-new-line, which reindents the current line then makes and indents a new line. This command is useful to reindent the closing statement of `do' loops and other blocks before starting a new line.

The key C-M-q runs fortran-indent-subprogram, a command to reindent all the lines of the Fortran subprogram (function or subroutine) containing point.

The key C-M-j runs fortran-split-line, which splits a line in the appropriate fashion for Fortran. In a non-comment line, the second half becomes a continuation line and is indented accordingly. In a comment line, both halves become separate comment lines.

M-^ runs the command fortran-join-line, which is more or less the inverse of fortran-split-line. It joins the current line to the previous line in a suitable way for Fortran code.

Continuation Lines

Most modern Fortran compilers allow two ways of writing continuation lines. If the first non-space character on a line is in column 5, then that line is a continuation of the previous line. We call this fixed format. (In GNU Emacs we always count columns from 0.) The variable fortran-continuation-string specifies what character to put on column 5. A line that starts with a tab character followed by any digit except `0' is also a continuation line. We call this style of continuation tab format.

Fortran mode can make either style of continuation line, but you must specify which one you prefer. The value of the variable indent-tabs-mode controls the choice: nil for fixed format, and non-nil for tab format. You can tell which style is presently in effect by the presence or absence of the string `Tab' in the mode line.

If the text on a line starts with the conventional Fortran continuation marker `$', or if it begins with any non-whitespace character in column 5, Fortran mode treats it as a continuation line. When you indent a continuation line with TAB, it converts the line to the current continuation style. When you split a Fortran statement with C-M-j, the continuation marker on the newline is created according to the continuation style.

The setting of continuation style affects several other aspects of editing in Fortran mode. In fixed format mode, the minimum column number for the body of a statement is 6. Lines inside of Fortran blocks that are indented to larger column numbers always use only the space character for whitespace. In tab format mode, the minimum column number for the statement body is 8, and the whitespace before column 8 must always consist of one tab character.

When you enter Fortran mode for an existing file, it tries to deduce the proper continuation style automatically from the file contents. The first line that begins with either a tab character or six spaces determines the choice. The variable fortran-analyze-depth specifies how many lines to consider (at the beginning of the file); if none of those lines indicates a style, then the variable fortran-tab-mode-default specifies the style. If it is nil, that specifies fixed format, and non-nil specifies tab format.

Line Numbers

If a number is the first non-whitespace in the line, Fortran indentation assumes it is a line number and moves it to columns 0 through 4. (Columns always count from 0 in GNU Emacs.)

Line numbers of four digits or less are normally indented one space. The variable fortran-line-number-indent controls this; it specifies the maximum indentation a line number can have. Line numbers are indented to right-justify them to end in column 4 unless that would require more than this maximum indentation. The default value of the variable is 1.

Simply inserting a line number is enough to indent it according to these rules. As each digit is inserted, the indentation is recomputed. To turn off this feature, set the variable fortran-electric-line-number to nil. Then inserting line numbers is like inserting anything else.

Syntactic Conventions

Fortran mode assumes that you follow certain conventions that simplify the task of understanding a Fortran program well enough to indent it properly:

  • Two nested `do' loops never share a `continue' statement.
  • Fortran keywords such as `if', `else', `then', `do' and others are written without embedded whitespace or line breaks. Fortran compilers generally ignore whitespace outside of string constants, but Fortran mode does not recognize these keywords if they are not contiguous. Constructs such as `else if' or `end do' are acceptable, but the second word should be on the same line as the first and not on a continuation line.

If you fail to follow these conventions, the indentation commands may indent some lines unaesthetically. However, a correct Fortran program retains its meaning when reindented even if the conventions are not followed.

Variables for Fortran Indentation

Several additional variables control how Fortran indentation works:

fortran-do-indent
Extra indentation within each level of `do' statement (default 3).
fortran-if-indent
Extra indentation within each level of `if' statement (default 3). This value is also used for extra indentation within each level of the Fortran 90 `where' statement.
fortran-structure-indent
Extra indentation within each level of `structure', `union', or `map' statements (default 3).
fortran-continuation-indent
Extra indentation for bodies of continuation lines (default 5).
fortran-check-all-num-for-matching-do
If this is nil, indentation assumes that each `do' statement ends on a `continue' statement. Therefore, when computing indentation for a statement other than `continue', it can save time by not checking for a `do' statement ending there. If this is non-nil, indenting any numbered statement must check for a `do' that ends there. The default is nil.
fortran-blink-matching-if
If this is t, indenting an `endif' statement moves the cursor momentarily to the matching `if' statement to show where it is. The default is nil.
fortran-minimum-statement-indent-fixed
Minimum indentation for fortran statements when using fixed format continuation line style. Statement bodies are never indented less than this much. The default is 6.
fortran-minimum-statement-indent-tab
Minimum indentation for fortran statements for tab format continuation line style. Statement bodies are never indented less than this much. The default is 8.

Fortran Comments

The usual Emacs comment commands assume that a comment can follow a line of code. In Fortran, the standard comment syntax requires an entire line to be just a comment. Therefore, Fortran mode replaces the standard Emacs comment commands and defines some new variables.

Fortran mode can also handle a nonstandard comment syntax where comments start with `!' and can follow other text. Because only some Fortran compilers accept this syntax, Fortran mode will not insert such comments unless you have said in advance to do so. To do this, set the variable comment-start to `"!"' (see section Variables).

M-;
Align comment or insert new comment (fortran-comment-indent).
C-x ;
Applies to nonstandard `!' comments only.
C-c ;
Turn all lines of the region into comments, or (with argument) turn them back into real code (fortran-comment-region).

M-; in Fortran mode is redefined as the command fortran-comment-indent. Like the usual M-; command, this recognizes any kind of existing comment and aligns its text appropriately; if there is no existing comment, a comment is inserted and aligned. But inserting and aligning comments are not the same in Fortran mode as in other modes.

When a new comment must be inserted, if the current line is blank, a full-line comment is inserted. On a non-blank line, a nonstandard `!' comment is inserted if you have said you want to use them. Otherwise a full-line comment is inserted on a new line before the current line.

Nonstandard `!' comments are aligned like comments in other languages, but full-line comments are different. In a standard full-line comment, the comment delimiter itself must always appear in column zero. What can be aligned is the text within the comment. You can choose from three styles of alignment by setting the variable fortran-comment-indent-style to one of these values:

fixed
Align the text at a fixed column, which is the sum of fortran-comment-line-extra-indent and the minimum statement indentation. This is the default. The minimum statement indentation is fortran-minimum-statement-indent-fixed for fixed format continuation line style and fortran-minimum-statement-indent-tab for tab format style.
relative
Align the text as if it were a line of code, but with an additional fortran-comment-line-extra-indent columns of indentation.
nil
Don't move text in full-line comments automatically at all.

In addition, you can specify the character to be used to indent within full-line comments by setting the variable fortran-comment-indent-char to the single-character string you want to use.

Fortran mode introduces two variables comment-line-start and comment-line-start-skip, which play for full-line comments the same roles played by comment-start and comment-start-skip for ordinary text-following comments. Normally these are set properly by Fortran mode, so you do not need to change them.

The normal Emacs comment command C-x ; has not been redefined. If you use `!' comments, this command can be used with them. Otherwise it is useless in Fortran mode.

The command C-c ; (fortran-comment-region) turns all the lines of the region into comments by inserting the string `C$$$' at the front of each one. With a numeric argument, it turns the region back into live code by deleting `C$$$' from the front of each line in it. The string used for these comments can be controlled by setting the variable fortran-comment-region. Note that here we have an example of a command and a variable with the same name; these two uses of the name never conflict because in Lisp and in Emacs it is always clear from the context which one is meant.

Fortran Auto Fill Mode

Fortran Auto Fill mode is a minor mode which automatically splits Fortran statements as you insert them when they become too wide. Splitting a statement involves making continuation lines using fortran-continuation-string (see section Continuation Lines). This splitting happens when you type SPC, RET, or TAB, and also in the Fortran indentation commands.

M-x fortran-auto-fill-mode turns Fortran Auto Fill mode on if it was off, or off if it was on. This command works the same as M-x auto-fill-mode does for normal Auto Fill mode (see section Filling Text). A positive numeric argument turns Fortran Auto Fill mode on, and a negative argument turns it off. You can see when Fortran Auto Fill mode is in effect by the presence of the word `Fill' in the mode line, inside the parentheses. Fortran Auto Fill mode is a minor mode, turned on or off for each buffer individually. See section Minor Modes.

Fortran Auto Fill mode breaks lines at spaces or delimiters when the lines get longer than the desired width (the value of fill-column). The delimiters that Fortran Auto Fill mode may break at are `,', `'', `+', `-', `/', `*', `=', and `)'. The line break comes after the delimiter if the variable fortran-break-before-delimiters is nil. Otherwise (and by default), the break comes before the delimiter.

By default, Fortran Auto Fill mode is not enabled. If you want this feature turned on permanently, add a hook function to fortran-mode-hook to execute (fortran-auto-fill-mode 1). See section Hooks.

Checking Columns in Fortran

C-c C-r
Display a "column ruler" momentarily above the current line (fortran-column-ruler).
C-c C-w
Split the current window horizontally temporarily so that it is 72 columns wide. This may help you avoid making lines longer than the 72-character limit that some Fortran compilers impose (fortran-window-create-momentarily).

The command C-c C-r (fortran-column-ruler) shows a column ruler momentarily above the current line. The comment ruler is two lines of text that show you the locations of columns with special significance in Fortran programs. Square brackets show the limits of the columns for line numbers, and curly brackets show the limits of the columns for the statement body. Column numbers appear above them.

Note that the column numbers count from zero, as always in GNU Emacs. As a result, the numbers may be one less than those you are familiar with; but the positions they indicate in the line are standard for Fortran.

The text used to display the column ruler depends on the value of the variable indent-tabs-mode. If indent-tabs-mode is nil, then the value of the variable fortran-column-ruler-fixed is used as the column ruler. Otherwise, the variable fortran-column-ruler-tab is displayed. By changing these variables, you can change the column ruler display.

For even more help, use C-c C-w (fortran-window-create), a command which splits the current window horizontally, making a window 72 columns wide. By editing in this window you can immediately see when you make a line too wide to be correct Fortran.

Fortran Keyword Abbrevs

Fortran mode provides many built-in abbrevs for common keywords and declarations. These are the same sort of abbrev that you can define yourself. To use them, you must turn on Abbrev mode. See section Abbrevs.

The built-in abbrevs are unusual in one way: they all start with a semicolon. You cannot normally use semicolon in an abbrev, but Fortran mode makes this possible by changing the syntax of semicolon to "word constituent."

For example, one built-in Fortran abbrev is `;c' for `continue'. If you insert `;c' and then insert a punctuation character such as a space or a newline, the `;c' expands automatically to `continue', provided Abbrev mode is enabled.

Type `;?' or `;C-h' to display a list of all the built-in Fortran abbrevs and what they stand for.

Other Fortran Mode Commands

C-x n d
Narrow to the current Fortran subprogram.

Fortran mode redefines the key C-x n d to run the command fortran-narrow-to-subprogram, which is the Fortran analogue of the key's usual definition. It narrows the buffer to the subprogram containing point.

Asm Mode

Asm mode is a major mode for editing files of assembler code. It defines these commands:

TAB
tab-to-tab-stop.
C-j
Insert a newline and then indent using tab-to-tab-stop.
:
Insert a colon and then remove the indentation from before the label preceding colon. Then do tab-to-tab-stop.
;
Insert or align a comment.

The variable asm-comment-char specifies which character starts comments in assembler syntax.

Compiling and Testing Programs

The previous chapter discusses the Emacs commands that are useful for making changes in programs. This chapter deals with commands that assist in the larger process of developing and maintaining programs.

Running Compilations under Emacs

Emacs can run compilers for noninteractive languages such as C and Fortran as inferior processes, feeding the error log into an Emacs buffer. It can also parse the error messages and show you the source lines where compilation errors occurred.

M-x compile
Run a compiler asynchronously under Emacs, with error messages to `*compilation*' buffer.
M-x grep
Run grep asynchronously under Emacs, with matching lines listed in the buffer named `*grep*'.
M-x grep-find
Run grep via find, with user-specified arguments, and collect output in the buffer named `*grep*'.
M-x kill-compilation
M-x kill-grep
Kill the running compilation or grep subprocess.

To run make or another compilation command, do M-x compile. This command reads a shell command line using the minibuffer, and then executes the command in an inferior shell, putting output in the buffer named `*compilation*'. The current buffer's default directory is used as the working directory for the execution of the command; normally, therefore, the compilation happens in this directory.

When the shell command line is read, the minibuffer appears containing a default command line, which is the command you used the last time you did M-x compile. If you type just RET, the same command line is used again. For the first M-x compile, the default is `make -k'. The default compilation command comes from the variable compile-command; if the appropriate compilation command for a file is something other than `make -k', it can be useful for the file to specify a local value for compile-command (see section Local Variables in Files).

Starting a compilation displays the buffer `*compilation*' in another window but does not select it. The buffer's mode line tells you whether compilation is finished, with the word `run' or `exit' inside the parentheses. You do not have to keep this buffer visible; compilation continues in any case. While a compilation is going on, the string `Compiling' appears in the mode lines of all windows. When this string disappears, the compilation is finished.

If you want to watch the compilation transcript as it appears, switch to the `*compilation*' buffer and move point to the end of the buffer. When point is at the end, new compilation output is inserted above point, which remains at the end. If point is not at the end of the buffer, it remains fixed while more compilation output is added at the end of the buffer.

If you set the variable compilation-scroll-output to a non-nil value, then the compilation buffer always scrolls to follow output as it comes in.

To kill the compilation process, do M-x kill-compilation. When the compiler process terminates, the mode line of the `*compilation*' buffer changes to say `signal' instead of `run'. Starting a new compilation also kills any running compilation, as only one can exist at any time. However, M-x compile asks for confirmation before actually killing a compilation that is running.

Searching with Grep under Emacs

Just as you can run a compiler from Emacs and then visit the lines where there were compilation errors, you can also run grep and then visit the lines on which matches were found. This works by treating the matches reported by grep as if they were "errors."

To do this, type M-x grep, then enter a command line that specifies how to run grep. Use the same arguments you would give grep when running it normally: a grep-style regexp (usually in single-quotes to quote the shell's special characters) followed by file names, which may use wildcards. The output from grep goes in the `*grep*' buffer. You can find the corresponding lines in the original files using C-x ` and RET, as with compilation errors.

If you specify a prefix argument for M-x grep, it figures out the tag (see section Tags Tables) around point, and puts that into the default grep command.

The command M-x grep-find is similar to M-x grep, but it supplies a different initial default for the command--one that runs both find and grep, so as to search every file in a directory tree. See also the find-grep-dired command, in section Dired and find.

Compilation Mode

The `*compilation*' buffer uses a special major mode, Compilation mode, whose main feature is to provide a convenient way to look at the source line where the error happened.

C-x `
Visit the locus of the next compiler error message or grep match.
RET
Visit the locus of the error message that point is on. This command is used in the compilation buffer.
Mouse-2
Visit the locus of the error message that you click on.

You can visit the source for any particular error message by moving point in `*compilation*' to that error message and typing RET (compile-goto-error). Or click Mouse-2 on the error message; you need not switch to the `*compilation*' buffer first.

To parse the compiler error messages sequentially, type C-x ` (next-error). The character following the C-x is the backquote or "grave accent," not the single-quote. This command is available in all buffers, not just in `*compilation*'; it displays the next error message at the top of one window and source location of the error in another window.

The first time C-x ` is used after the start of a compilation, it moves to the first error's location. Subsequent uses of C-x ` advance down to subsequent errors. If you visit a specific error message with RET or Mouse-2, subsequent C-x ` commands advance from there. When C-x ` gets to the end of the buffer and finds no more error messages to visit, it fails and signals an Emacs error.

C-u C-x ` starts scanning from the beginning of the compilation buffer. This is one way to process the same set of errors again.

Compilation mode also redefines the keys SPC and DEL to scroll by screenfuls, and M-n and M-p to move to the next or previous error message. You can also use M-{ and M-} to move up or down to an error message for a different source file.

The features of Compilation mode are also available in a minor mode called Compilation Minor mode. This lets you parse error messages in any buffer, not just a normal compilation output buffer. Type M-x compilation-minor-mode to enable the minor mode. This defines the keys RET and Mouse-2, as in the Compilation major mode.

Compilation minor mode works in any buffer, as long as the contents are in a format that it understands. In an Rlogin buffer (see section Remote Host Shell), Compilation minor mode automatically accesses remote source files by FTP (see section File Names).

Subshells for Compilation

Emacs uses a shell to run the compilation command, but specifies the option for a noninteractive shell. This means, in particular, that the shell should start with no prompt. If you find your usual shell prompt making an unsightly appearance in the `*compilation*' buffer, it means you have made a mistake in your shell's init file by setting the prompt unconditionally. (This init file's name may be `.bashrc', `.profile', `.cshrc', `.shrc', or various other things, depending on the shell you use.) The shell init file should set the prompt only if there already is a prompt. In csh, here is how to do it:

if ($?prompt) set prompt = ...

And here's how to do it in bash:

if [ "${PS1+set}" = set ]
then PS1=...
fi

There may well be other things that your shell's init file ought to do only for an interactive shell. You can use the same method to conditionalize them.

The MS-DOS "operating system" does not support asynchronous subprocesses; to work around this lack, M-x compile runs the compilation command synchronously on MS-DOS. As a consequence, you must wait until the command finishes before you can do anything else in Emacs. See section Emacs and MS-DOS.

Running Debuggers Under Emacs

The GUD (Grand Unified Debugger) library provides an interface to various symbolic debuggers from within Emacs. We recommend the debugger GDB, which is free software, but you can also run DBX, SDB or XDB if you have them. GUD can also serve as an interface to the Perl's debugging mode, the Python debugger PDB, and to JDB, the Java Debugger.

Starting GUD

There are several commands for starting a debugger, each corresponding to a particular debugger program.

M-x gdb RET file RET
Run GDB as a subprocess of Emacs. This command creates a buffer for input and output to GDB, and switches to it. If a GDB buffer already exists, it just switches to that buffer.
M-x dbx RET file RET
Similar, but run DBX instead of GDB.
M-x xdb RET file RET
Similar, but run XDB instead of GDB. Use the variable gud-xdb-directories to specify directories to search for source files.
M-x sdb RET file RET
Similar, but run SDB instead of GDB. Some versions of SDB do not mention source file names in their messages. When you use them, you need to have a valid tags table (see section Tags Tables) in order for GUD to find functions in the source code. If you have not visited a tags table or the tags table doesn't list one of the functions, you get a message saying `The sdb support requires a valid tags table to work'. If this happens, generate a valid tags table in the working directory and try again.
M-x perldb RET file RET
Run the Perl interpreter in debug mode to debug file, a Perl program.
M-x jdb RET file RET
Run the Java debugger to debug file.
M-x pdb RET file RET
Run the Python debugger to debug file.

Each of these commands takes one argument: a command line to invoke the debugger. In the simplest case, specify just the name of the executable file you want to debug. You may also use options that the debugger supports. However, shell wildcards and variables are not allowed. GUD assumes that the first argument not starting with a `-' is the executable file name.

Emacs can only run one debugger process at a time.

Debugger Operation

When you run a debugger with GUD, the debugger uses an Emacs buffer for its ordinary input and output. This is called the GUD buffer. The debugger displays the source files of the program by visiting them in Emacs buffers. An arrow (`=>') in one of these buffers indicates the current execution line. Moving point in this buffer does not move the arrow.

You can start editing these source files at any time in the buffers that were made to display them. The arrow is not part of the file's text; it appears only on the screen. If you do modify a source file, keep in mind that inserting or deleting lines will throw off the arrow's positioning; GUD has no way of figuring out which line corresponded before your changes to the line number in a debugger message. Also, you'll typically have to recompile and restart the program for your changes to be reflected in the debugger's tables.

If you wish, you can control your debugger process entirely through the debugger buffer, which uses a variant of Shell mode. All the usual commands for your debugger are available, and you can use the Shell mode history commands to repeat them. See section Shell Mode.

Commands of GUD

The GUD interaction buffer uses a variant of Shell mode, so the commands of Shell mode are available (see section Shell Mode). GUD mode also provides commands for setting and clearing breakpoints, for selecting stack frames, and for stepping through the program. These commands are available both in the GUD buffer and globally, but with different key bindings.

The breakpoint commands are usually used in source file buffers, because that is the way to specify where to set or clear the breakpoint. Here's the global command to set a breakpoint:

C-x SPC
Set a breakpoint on the source line that point is on.

Here are the other special commands provided by GUD. The keys starting with C-c are available only in the GUD interaction buffer. The key bindings that start with C-x C-a are available in the GUD interaction buffer and also in source files.

C-c C-l
C-x C-a C-l
Display in another window the last line referred to in the GUD buffer (that is, the line indicated in the last location message). This runs the command gud-refresh.
C-c C-s
C-x C-a C-s
Execute a single line of code (gud-step). If the line contains a function call, execution stops after entering the called function.
C-c C-n
C-x C-a C-n
Execute a single line of code, stepping across entire function calls at full speed (gud-next).
C-c C-i
C-x C-a C-i
Execute a single machine instruction (gud-stepi).
C-c C-r
C-x C-a C-r
Continue execution without specifying any stopping point. The program will run until it hits a breakpoint, terminates, or gets a signal that the debugger is checking for (gud-cont).
C-c C-d
C-x C-a C-d
Delete the breakpoint(s) on the current source line, if any (gud-remove). If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped.
C-c C-t
C-x C-a C-t
Set a temporary breakpoint on the current source line, if any. If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped.

The above commands are common to all supported debuggers. If you are using GDB or (some versions of) DBX, these additional commands are available:

C-c <
C-x C-a <
Select the next enclosing stack frame (gud-up). This is equivalent to the `up' command.
C-c >
C-x C-a >
Select the next inner stack frame (gud-down). This is equivalent to the `down' command.

If you are using GDB, these additional key bindings are available:

TAB
With GDB, complete a symbol name (gud-gdb-complete-command). This key is available only in the GUD interaction buffer, and requires GDB versions 4.13 and later.
C-c C-f
C-x C-a C-f
Run the program until the selected stack frame returns (or until it stops for some other reason).

These commands interpret a numeric argument as a repeat count, when that makes sense.

Because TAB serves as a completion command, you can't use it to enter a tab as input to the program you are debugging with GDB. Instead, type C-q TAB to enter a tab.

GUD Customization

On startup, GUD runs one of the following hooks: gdb-mode-hook, if you are using GDB; dbx-mode-hook, if you are using DBX; sdb-mode-hook, if you are using SDB; xdb-mode-hook, if you are using XDB; perldb-mode-hook, for Perl debugging mode; jdb-mode-hook, for PDB; jdb-mode-hook, for JDB. You can use these hooks to define custom key bindings for the debugger interaction buffer. See section Hooks.

Here is a convenient way to define a command that sends a particular command string to the debugger, and set up a key binding for it in the debugger interaction buffer:

(gud-def function cmdstring binding docstring)

This defines a command named function which sends cmdstring to the debugger process, and gives it the documentation string docstring. You can use the command thus defined in any buffer. If binding is non-nil, gud-def also binds the command to C-c binding in the GUD buffer's mode and to C-x C-a binding generally.

The command string cmdstring may contain certain `%'-sequences that stand for data to be filled in at the time function is called:

`%f'
The name of the current source file. If the current buffer is the GUD buffer, then the "current source file" is the file that the program stopped in.
`%l'
The number of the current source line. If the current buffer is the GUD buffer, then the "current source line" is the line that the program stopped in.
`%e'
The text of the C lvalue or function-call expression at or adjacent to point.
`%a'
The text of the hexadecimal address at or adjacent to point.
`%p'
The numeric argument of the called function, as a decimal number. If the command is used without a numeric argument, `%p' stands for the empty string. If you don't use `%p' in the command string, the command you define ignores any numeric argument.

Executing Lisp Expressions

Emacs has several different major modes for Lisp and Scheme. They are the same in terms of editing commands, but differ in the commands for executing Lisp expressions. Each mode has its own purpose.

Emacs-Lisp mode
The mode for editing source files of programs to run in Emacs Lisp. This mode defines C-M-x to evaluate the current defun. See section Libraries of Lisp Code for Emacs.
Lisp Interaction mode
The mode for an interactive session with Emacs Lisp. It defines C-j to evaluate the sexp before point and insert its value in the buffer. See section Lisp Interaction Buffers.
Lisp mode
The mode for editing source files of programs that run in Lisps other than Emacs Lisp. This mode defines C-M-x to send the current defun to an inferior Lisp process. See section Running an External Lisp.
Inferior Lisp mode
The mode for an interactive session with an inferior Lisp process. This mode combines the special features of Lisp mode and Shell mode (see section Shell Mode).
Scheme mode
Like Lisp mode but for Scheme programs.
Inferior Scheme mode
The mode for an interactive session with an inferior Scheme process.

Most editing commands for working with Lisp programs are in fact available globally. See section Editing Programs.

Libraries of Lisp Code for Emacs

Lisp code for Emacs editing commands is stored in files whose names conventionally end in `.el'. This ending tells Emacs to edit them in Emacs-Lisp mode (see section Executing Lisp Expressions).

To execute a file of Emacs Lisp code, use M-x load-file. This command reads a file name using the minibuffer and then executes the contents of that file as Lisp code. It is not necessary to visit the file first; in any case, this command reads the file as found on disk, not text in an Emacs buffer.

Once a file of Lisp code is installed in the Emacs Lisp library directories, users can load it using M-x load-library. Programs can load it by calling load-library, or with load, a more primitive function that is similar but accepts some additional arguments.

M-x load-library differs from M-x load-file in that it searches a sequence of directories and tries three file names in each directory. Suppose your argument is lib; the three names are `lib.elc', `lib.el', and lastly just `lib'. If `lib.elc' exists, it is by convention the result of compiling `lib.el'; it is better to load the compiled file, since it will load and run faster.

If load-library finds that `lib.el' is newer than `lib.elc' file, it prints a warning, because it's likely that somebody made changes to the `.el' file and forgot to recompile it.

Because the argument to load-library is usually not in itself a valid file name, file name completion is not available. Indeed, when using this command, you usually do not know exactly what file name will be used.

The sequence of directories searched by M-x load-library is specified by the variable load-path, a list of strings that are directory names. The default value of the list contains the directory where the Lisp code for Emacs itself is stored. If you have libraries of your own, put them in a single directory and add that directory to load-path. nil in this list stands for the current default directory, but it is probably not a good idea to put nil in the list. If you find yourself wishing that nil were in the list, most likely what you really want to do is use M-x load-file this once.

Often you do not have to give any command to load a library, because the commands defined in the library are set up to autoload that library. Trying to run any of those commands calls load to load the library; this replaces the autoload definitions with the real ones from the library.

Emacs Lisp code can be compiled into byte-code which loads faster, takes up less space when loaded, and executes faster. See section `Byte Compilation' in the Emacs Lisp Reference Manual. By convention, the compiled code for a library goes in a separate file whose name consists of the library source file with `c' appended. Thus, the compiled code for `foo.el' goes in `foo.elc'. That's why load-library searches for `.elc' files first.

Evaluating Emacs-Lisp Expressions

Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp mode; this happens automatically for file names ending in `.el'. By contrast, Lisp mode itself is used for editing Lisp programs intended for other Lisp systems. To switch to Emacs-Lisp mode explicitly, use the command M-x emacs-lisp-mode.

For testing of Lisp programs to run in Emacs, it is often useful to evaluate part of the program as it is found in the Emacs buffer. For example, after changing the text of a Lisp function definition, evaluating the definition installs the change for future calls to the function. Evaluation of Lisp expressions is also useful in any kind of editing, for invoking noninteractive functions (functions that are not commands).

M-:
Read a single Lisp expression in the minibuffer, evaluate it, and print the value in the echo area (eval-expression).
C-x C-e
Evaluate the Lisp expression before point, and print the value in the echo area (eval-last-sexp).
C-M-x
Evaluate the defun containing or after point, and print the value in the echo area (eval-defun).
M-x eval-region
Evaluate all the Lisp expressions in the region.
M-x eval-current-buffer
Evaluate all the Lisp expressions in the buffer.

M-: (eval-expression) is the most basic command for evaluating a Lisp expression interactively. It reads the expression using the minibuffer, so you can execute any expression on a buffer regardless of what the buffer contains. When the expression is evaluated, the current buffer is once again the buffer that was current when M-: was typed.

In Emacs-Lisp mode, the key C-M-x is bound to the command eval-defun, which parses the defun containing or following point as a Lisp expression and evaluates it. The value is printed in the echo area. This command is convenient for installing in the Lisp environment changes that you have just made in the text of a function definition.

C-M-x treats defvar expressions specially. Normally, evaluating a defvar expression does nothing if the variable it defines already has a value. But C-M-x unconditionally resets the variable to the initial value specified in the defvar expression. This special feature is convenient for debugging Lisp programs.

The command C-x C-e (eval-last-sexp) evaluates the Lisp expression preceding point in the buffer, and displays the value in the echo area. It is available in all major modes, not just Emacs-Lisp mode. It does not treat defvar specially.

If C-M-x, C-x C-e, or M-: is given a numeric argument, it inserts the value into the current buffer at point, rather than displaying it in the echo area. The argument's value does not matter.

The most general command for evaluating Lisp expressions from a buffer is eval-region. M-x eval-region parses the text of the region as one or more Lisp expressions, evaluating them one by one. M-x eval-current-buffer is similar but evaluates the entire buffer. This is a reasonable way to install the contents of a file of Lisp code that you are just ready to test. Later, as you find bugs and change individual functions, use C-M-x on each function that you change. This keeps the Lisp world in step with the source file.

Lisp Interaction Buffers

The buffer `*scratch*' which is selected when Emacs starts up is provided for evaluating Lisp expressions interactively inside Emacs.

The simplest way to use the `*scratch*' buffer is to insert Lisp expressions and type C-j after each expression. This command reads the Lisp expression before point, evaluates it, and inserts the value in printed representation before point. The result is a complete typescript of the expressions you have evaluated and their values.

The `*scratch*' buffer's major mode is Lisp Interaction mode, which is the same as Emacs-Lisp mode except for the binding of C-j.

The rationale for this feature is that Emacs must have a buffer when it starts up, but that buffer is not useful for editing files since a new buffer is made for every file that you visit. The Lisp interpreter typescript is the most useful thing I can think of for the initial buffer to do. Type M-x lisp-interaction-mode to put the current buffer in Lisp Interaction mode.

An alternative way of evaluating Emacs Lisp expressions interactively is to use Inferior Emacs-Lisp mode, which provides an interface rather like Shell mode (see section Shell Mode) for evaluating Emacs Lisp expressions. Type M-x ielm to create an `*ielm*' buffer which uses this mode.

Running an External Lisp

Emacs has facilities for running programs in other Lisp systems. You can run a Lisp process as an inferior of Emacs, and pass expressions to it to be evaluated. You can also pass changed function definitions directly from the Emacs buffers in which you edit the Lisp programs to the inferior Lisp process.

To run an inferior Lisp process, type M-x run-lisp. This runs the program named lisp, the same program you would run by typing lisp as a shell command, with both input and output going through an Emacs buffer named `*lisp*'. That is to say, any "terminal output" from Lisp will go into the buffer, advancing point, and any "terminal input" for Lisp comes from text in the buffer. (You can change the name of the Lisp executable file by setting the variable inferior-lisp-program.)

To give input to Lisp, go to the end of the buffer and type the input, terminated by RET. The `*lisp*' buffer is in Inferior Lisp mode, which combines the special characteristics of Lisp mode with most of the features of Shell mode (see section Shell Mode). The definition of RET to send a line to a subprocess is one of the features of Shell mode.

For the source files of programs to run in external Lisps, use Lisp mode. This mode can be selected with M-x lisp-mode, and is used automatically for files whose names end in `.l', `.lsp', or `.lisp', as most Lisp systems usually expect.

When you edit a function in a Lisp program you are running, the easiest way to send the changed definition to the inferior Lisp process is the key C-M-x. In Lisp mode, this runs the function lisp-eval-defun, which finds the defun around or following point and sends it as input to the Lisp process. (Emacs can send input to any inferior process regardless of what buffer is current.)

Contrast the meanings of C-M-x in Lisp mode (for editing programs to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp programs to be run in Emacs): in both modes it has the effect of installing the function definition that point is in, but the way of doing so is different according to where the relevant Lisp environment is found. See section Executing Lisp Expressions.

Abbrevs

A defined abbrev is a word which expands, if you insert it, into some different text. Abbrevs are defined by the user to expand in specific ways. For example, you might define `foo' as an abbrev expanding to `find outer otter'. Then you would be able to insert `find outer otter ' into the buffer by typing f o o SPC.

A second kind of abbreviation facility is called dynamic abbrev expansion. You use dynamic abbrev expansion with an explicit command to expand the letters in the buffer before point by looking for other words in the buffer that start with those letters. See section Dynamic Abbrev Expansion.

Abbrev Concepts

An abbrev is a word which has been defined to expand into a specified expansion. When you insert a word-separator character following the abbrev, that expands the abbrev--replacing the abbrev with its expansion. For example, if `foo' is defined as an abbrev expanding to `find outer otter', then you can insert `find outer otter.' into the buffer by typing f o o ..

Abbrevs expand only when Abbrev mode (a minor mode) is enabled. Disabling Abbrev mode does not cause abbrev definitions to be forgotten, but they do not expand until Abbrev mode is enabled again. The command M-x abbrev-mode toggles Abbrev mode; with a numeric argument, it turns Abbrev mode on if the argument is positive, off otherwise. See section Minor Modes. abbrev-mode is also a variable; Abbrev mode is on when the variable is non-nil. The variable abbrev-mode automatically becomes local to the current buffer when it is set.

Abbrev definitions can be mode-specific---active only in one major mode. Abbrevs can also have global definitions that are active in all major modes. The same abbrev can have a global definition and various mode-specific definitions for different major modes. A mode-specific definition for the current major mode overrides a global definition.

Abbrevs can be defined interactively during the editing session. Lists of abbrev definitions can also be saved in files and reloaded in later sessions. Some users keep extensive lists of abbrevs that they load in every session.

Defining Abbrevs

C-x a g
Define an abbrev, using one or more words before point as its expansion (add-global-abbrev).
C-x a l
Similar, but define an abbrev specific to the current major mode (add-mode-abbrev).
C-x a i g
Define a word in the buffer as an abbrev (inverse-add-global-abbrev).
C-x a i l
Define a word in the buffer as a mode-specific abbrev (inverse-add-mode-abbrev).
M-x kill-all-abbrevs
This command discards all abbrev definitions currently in effect, leaving a blank slate.

The usual way to define an abbrev is to enter the text you want the abbrev to expand to, position point after it, and type C-x a g (add-global-abbrev). This reads the abbrev itself using the minibuffer, and then defines it as an abbrev for one or more words before point. Use a numeric argument to say how many words before point should be taken as the expansion. For example, to define the abbrev `foo' as mentioned above, insert the text `find outer otter' and then type C-u 3 C-x a g f o o RET.

An argument of zero to C-x a g means to use the contents of the region as the expansion of the abbrev being defined.

The command C-x a l (add-mode-abbrev) is similar, but defines a mode-specific abbrev. Mode-specific abbrevs are active only in a particular major mode. C-x a l defines an abbrev for the major mode in effect at the time C-x a l is typed. The arguments work the same as for C-x a g.

If the text already in the buffer is the abbrev, rather than its expansion, use command C-x a i g (inverse-add-global-abbrev) instead of C-x a g, or use C-x a i l (inverse-add-mode-abbrev) instead of C-x a l. These commands are called "inverse" because they invert the meaning of the two text strings they use (one from the buffer and one read with the minibuffer).

To change the definition of an abbrev, just define a new definition. When the abbrev has a prior definition, the abbrev definition commands ask for confirmation for replacing it.

To remove an abbrev definition, give a negative argument to the abbrev definition command: C-u - C-x a g or C-u - C-x a l. The former removes a global definition, while the latter removes a mode-specific definition.

M-x kill-all-abbrevs removes all the abbrev definitions there are, both global and local.

Controlling Abbrev Expansion

An abbrev expands whenever it is present in the buffer just before point and you type a self-inserting whitespace or punctuation character (SPC, comma, etc.). More precisely, any character that is not a word constituent expands an abbrev, and any word-constituent character can be part of an abbrev. The most common way to use an abbrev is to insert it and then insert a punctuation character to expand it.

Abbrev expansion preserves case; thus, `foo' expands into `find outer otter'; `Foo' into `Find outer otter', and `FOO' into `FIND OUTER OTTER' or `Find Outer Otter' according to the variable abbrev-all-caps (a non-nil value chooses the first of the two expansions).

These commands are used to control abbrev expansion:

M-'
Separate a prefix from a following abbrev to be expanded (abbrev-prefix-mark).
C-x a e
Expand the abbrev before point (expand-abbrev). This is effective even when Abbrev mode is not enabled.
M-x expand-region-abbrevs
Expand some or all abbrevs found in the region.

You may wish to expand an abbrev with a prefix attached; for example, if `cnst' expands into `construction', you might want to use it to enter `reconstruction'. It does not work to type recnst, because that is not necessarily a defined abbrev. What you can do is use the command M-' (abbrev-prefix-mark) in between the prefix `re' and the abbrev `cnst'. First, insert `re'. Then type M-'; this inserts a hyphen in the buffer to indicate that it has done its work. Then insert the abbrev `cnst'; the buffer now contains `re-cnst'. Now insert a non-word character to expand the abbrev `cnst' into `construction'. This expansion step also deletes the hyphen that indicated M-' had been used. The result is the desired `reconstruction'.

If you actually want the text of the abbrev in the buffer, rather than its expansion, you can accomplish this by inserting the following punctuation with C-q. Thus, foo C-q , leaves `foo,' in the buffer.

If you expand an abbrev by mistake, you can undo the expansion and bring back the abbrev itself by typing C-_ to undo (see section Undoing Changes). This also undoes the insertion of the non-word character that expanded the abbrev. If the result you want is the terminating non-word character plus the unexpanded abbrev, you must reinsert the terminating character, quoting it with C-q. You can also use the command M-x unexpand-abbrev to cancel the last expansion without deleting the terminating character.

M-x expand-region-abbrevs searches through the region for defined abbrevs, and for each one found offers to replace it with its expansion. This command is useful if you have typed in text using abbrevs but forgot to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. This command is effective even if Abbrev mode is not enabled.

Expanding an abbrev runs the hook pre-abbrev-expand-hook (see section Hooks).

Examining and Editing Abbrevs

M-x list-abbrevs
Display a list of all abbrev definitions.
M-x edit-abbrevs
Edit a list of abbrevs; you can add, alter or remove definitions.

The output from M-x list-abbrevs looks like this:

(lisp-mode-abbrev-table)
"dk"	       0    "define-key"
(global-abbrev-table)
"dfn"	       0    "definition"

(Some blank lines of no semantic significance, and some other abbrev tables, have been omitted.)

A line containing a name in parentheses is the header for abbrevs in a particular abbrev table; global-abbrev-table contains all the global abbrevs, and the other abbrev tables that are named after major modes contain the mode-specific abbrevs.

Within each abbrev table, each nonblank line defines one abbrev. The word at the beginning of the line is the abbrev. The number that follows is the number of times the abbrev has been expanded. Emacs keeps track of this to help you see which abbrevs you actually use, so that you can eliminate those that you don't use often. The string at the end of the line is the expansion.

M-x edit-abbrevs allows you to add, change or kill abbrev definitions by editing a list of them in an Emacs buffer. The list has the same format described above. The buffer of abbrevs is called `*Abbrevs*', and is in Edit-Abbrevs mode. Type C-c C-c in this buffer to install the abbrev definitions as specified in the buffer--and delete any abbrev definitions not listed.

The command edit-abbrevs is actually the same as list-abbrevs except that it selects the buffer `*Abbrevs*' whereas list-abbrevs merely displays it in another window.

Saving Abbrevs

These commands allow you to keep abbrev definitions between editing sessions.

M-x write-abbrev-file RET file RET
Write a file file describing all defined abbrevs.
M-x read-abbrev-file RET file RET
Read the file file and define abbrevs as specified therein.
M-x quietly-read-abbrev-file RET file RET
Similar but do not display a message about what is going on.
M-x define-abbrevs
Define abbrevs from definitions in current buffer.
M-x insert-abbrevs
Insert all abbrevs and their expansions into current buffer.

M-x write-abbrev-file reads a file name using the minibuffer and then writes a description of all current abbrev definitions into that file. This is used to save abbrev definitions for use in a later session. The text stored in the file is a series of Lisp expressions that, when executed, define the same abbrevs that you currently have.

M-x read-abbrev-file reads a file name using the minibuffer and then reads the file, defining abbrevs according to the contents of the file. M-x quietly-read-abbrev-file is the same except that it does not display a message in the echo area saying that it is doing its work; it is actually useful primarily in the `.emacs' file. If an empty argument is given to either of these functions, they use the file name specified in the variable abbrev-file-name, which is by default "~/.abbrev_defs".

Emacs will offer to save abbrevs automatically if you have changed any of them, whenever it offers to save all files (for C-x s or C-x C-c). This feature can be inhibited by setting the variable save-abbrevs to nil.

The commands M-x insert-abbrevs and M-x define-abbrevs are similar to the previous commands but work on text in an Emacs buffer. M-x insert-abbrevs inserts text into the current buffer before point, describing all current abbrev definitions; M-x define-abbrevs parses the entire current buffer and defines abbrevs accordingly.

Dynamic Abbrev Expansion

The abbrev facility described above operates automatically as you insert text, but all abbrevs must be defined explicitly. By contrast, dynamic abbrevs allow the meanings of abbrevs to be determined automatically from the contents of the buffer, but dynamic abbrev expansion happens only when you request it explicitly.

M-/
Expand the word in the buffer before point as a dynamic abbrev, by searching in the buffer for words starting with that abbreviation (dabbrev-expand).
C-M-/
Complete the word before point as a dynamic abbrev (dabbrev-completion).

For example, if the buffer contains `does this follow ' and you type f o M-/, the effect is to insert `follow' because that is the last word in the buffer that starts with `fo'. A numeric argument to M-/ says to take the second, third, etc. distinct expansion found looking backward from point. Repeating M-/ searches for an alternative expansion by looking farther back. After scanning all the text before point, it searches the text after point. The variable dabbrev-limit, if non-nil, specifies how far in the buffer to search for an expansion.

After scanning the current buffer, M-/ normally searches other buffers, unless you have set dabbrev-check-all-buffers to nil.

A negative argument to M-/, as in C-u - M-/, says to search first for expansions after point, and second for expansions before point. If you repeat the M-/ to look for another expansion, do not specify an argument. This tries all the expansions after point and then the expansions before point.

After you have expanded a dynamic abbrev, you can copy additional words that follow the expansion in its original context. Simply type SPC M-/ for each word you want to copy. The spacing and punctuation between words is copied along with the words.

The command C-M-/ (dabbrev-completion) performs completion of a dynamic abbreviation. Instead of trying the possible expansions one by one, it finds all of them, then inserts the text that they have in common. If they have nothing in common, C-M-/ displays a list of completions, from which you can select a choice in the usual manner. See section Completion.

Dynamic abbrev expansion is completely independent of Abbrev mode; the expansion of a word with M-/ is completely independent of whether it has a definition as an ordinary abbrev.

Customizing Dynamic Abbreviation

Normally, dynamic abbrev expansion ignores case when searching for expansions. That is, the expansion need not agree in case with the word you are expanding.

This feature is controlled by the variable dabbrev-case-fold-search. If it is t, case is ignored in this search; if nil, the word and the expansion must match in case. If the value of dabbrev-case-fold-search is case-fold-search, which is true by default, then the variable case-fold-search controls whether to ignore case while searching for expansions.

Normally, dynamic abbrev expansion preserves the case pattern of the abbrev you have typed, by converting the expansion to that case pattern.

The variable dabbrev-case-replace controls whether to preserve the case pattern of the abbrev. If it is t, the abbrev's case pattern is preserved in most cases; if nil, the expansion is always copied verbatim. If the value of dabbrev-case-replace is case-replace, which is true by default, then the variable case-replace controls whether to copy the expansion verbatim.

However, if the expansion contains a complex mixed case pattern, and the abbrev matches this pattern as far as it goes, then the expansion is always copied verbatim, regardless of those variables. Thus, for example, if the buffer contains variableWithSillyCasePattern, and you type v a M-/, it copies the expansion verbatim including its case pattern.

The variable dabbrev-abbrev-char-regexp, if non-nil, controls which characters are considered part of a word, for dynamic expansion purposes. The regular expression must match just one character, never two or more. The same regular expression also determines which characters are part of an expansion. The value nil has a special meaning: abbreviations are made of word characters, but expansions are made of word and symbol characters.

In shell scripts and makefiles, a variable name is sometimes prefixed with `$' and sometimes not. Major modes for this kind of text can customize dynamic abbreviation to handle optional prefixes by setting the variable dabbrev-abbrev-skip-leading-regexp. Its value should be a regular expression that matches the optional prefix that dynamic abbreviation should ignore.

Editing Pictures

To edit a picture made out of text characters (for example, a picture of the division of a register into fields, as a comment in a program), use the command M-x edit-picture to enter Picture mode.

In Picture mode, editing is based on the quarter-plane model of text, according to which the text characters lie studded on an area that stretches infinitely far to the right and downward. The concept of the end of a line does not exist in this model; the most you can say is where the last nonblank character on the line is found.

Of course, Emacs really always considers text as a sequence of characters, and lines really do have ends. But Picture mode replaces the most frequently-used commands with variants that simulate the quarter-plane model of text. They do this by inserting spaces or by converting tabs to spaces.

Most of the basic editing commands of Emacs are redefined by Picture mode to do essentially the same thing but in a quarter-plane way. In addition, Picture mode defines various keys starting with the C-c prefix to run special picture editing commands.

One of these keys, C-c C-c, is pretty important. Often a picture is part of a larger file that is usually edited in some other major mode. M-x edit-picture records the name of the previous major mode so you can use the C-c C-c command (picture-mode-exit) later to go back to that mode. C-c C-c also deletes spaces from the ends of lines, unless given a numeric argument.

The special commands of Picture mode all work in other modes (provided the `picture' library is loaded), but are not bound to keys except in Picture mode. The descriptions below talk of moving "one column" and so on, but all the picture mode commands handle numeric arguments as their normal equivalents do.

Turning on Picture mode runs the hook picture-mode-hook (see section Hooks).

Basic Editing in Picture Mode

Most keys do the same thing in Picture mode that they usually do, but do it in a quarter-plane style. For example, C-f is rebound to run picture-forward-column, a command which moves point one column to the right, inserting a space if necessary so that the actual end of the line makes no difference. C-b is rebound to run picture-backward-column, which always moves point left one column, converting a tab to multiple spaces if necessary. C-n and C-p are rebound to run picture-move-down and picture-move-up, which can either insert spaces or convert tabs as necessary to make sure that point stays in exactly the same column. C-e runs picture-end-of-line, which moves to after the last nonblank character on the line. There is no need to change C-a, as the choice of screen model does not affect beginnings of lines.

Insertion of text is adapted to the quarter-plane screen model through the use of Overwrite mode (see section Minor Modes). Self-inserting characters replace existing text, column by column, rather than pushing existing text to the right. RET runs picture-newline, which just moves to the beginning of the following line so that new text will replace that line.

Picture mode provides erasure instead of deletion and killing of text. DEL (picture-backward-clear-column) replaces the preceding character with a space rather than removing it; this moves point backwards. C-d (picture-clear-column) replaces the next character or characters with spaces, but does not move point. (If you want to clear characters to spaces and move forward over them, use SPC.) C-k (picture-clear-line) really kills the contents of lines, but does not delete the newlines from the buffer.

To do actual insertion, you must use special commands. C-o (picture-open-line) creates a blank line after the current line; it never splits a line. C-M-o (split-line) makes sense in Picture mode, so it is not changed. C-j (picture-duplicate-line) inserts below the current line another line with the same contents.

To do actual deletion in Picture mode, use C-w, C-c C-d (which is defined as delete-char, as C-d is in other modes), or one of the picture rectangle commands (see section Picture Mode Rectangle Commands).

Controlling Motion after Insert

Since "self-inserting" characters in Picture mode overwrite and move point, there is no essential restriction on how point should be moved. Normally point moves right, but you can specify any of the eight orthogonal or diagonal directions for motion after a "self-inserting" character. This is useful for drawing lines in the buffer.

C-c <
Move left after insertion (picture-movement-left).
C-c >
Move right after insertion (picture-movement-right).
C-c ^
Move up after insertion (picture-movement-up).
C-c .
Move down after insertion (picture-movement-down).
C-c `
Move up and left ("northwest") after insertion (picture-movement-nw).
C-c '
Move up and right ("northeast") after insertion (picture-movement-ne).
C-c /
Move down and left ("southwest") after insertion
(picture-movement-sw).
C-c \
Move down and right ("southeast") after insertion
(picture-movement-se).

Two motion commands move based on the current Picture insertion direction. The command C-c C-f (picture-motion) moves in the same direction as motion after "insertion" currently does, while C-c C-b (picture-motion-reverse) moves in the opposite direction.

Picture Mode Tabs

Two kinds of tab-like action are provided in Picture mode. Use M-TAB (picture-tab-search) for context-based tabbing. With no argument, it moves to a point underneath the next "interesting" character that follows whitespace in the previous nonblank line. "Next" here means "appearing at a horizontal position greater than the one point starts out at." With an argument, as in C-u M-TAB, this command moves to the next such interesting character in the current line. M-TAB does not change the text; it only moves point. "Interesting" characters are defined by the variable picture-tab-chars, which should define a set of characters. The syntax for this variable is like the syntax used inside of `[...]' in a regular expression--but without the `[' and the `]'. Its default value is "!-~".

TAB itself runs picture-tab, which operates based on the current tab stop settings; it is the Picture mode equivalent of tab-to-tab-stop. Normally it just moves point, but with a numeric argument it clears the text that it moves over.

The context-based and tab-stop-based forms of tabbing are brought together by the command C-c TAB (picture-set-tab-stops). This command sets the tab stops to the positions which M-TAB would consider significant in the current line. The use of this command, together with TAB, can get the effect of context-based tabbing. But M-TAB is more convenient in the cases where it is sufficient.

It may be convenient to prevent use of actual tab characters in pictures. For example, this prevents C-x TAB from messing up the picture. You can do this by setting the variable indent-tabs-mode to nil. See section Tabs vs. Spaces.

Picture Mode Rectangle Commands

Picture mode defines commands for working on rectangular pieces of the text in ways that fit with the quarter-plane model. The standard rectangle commands may also be useful (see section Rectangles).

C-c C-k
Clear out the region-rectangle with spaces (picture-clear-rectangle). With argument, delete the text.
C-c C-w r
Similar but save rectangle contents in register r first (picture-clear-rectangle-to-register).
C-c C-y
Copy last killed rectangle into the buffer by overwriting, with upper left corner at point (picture-yank-rectangle). With argument, insert instead.
C-c C-x r
Similar, but use the rectangle in register r (picture-yank-rectangle-from-register).

The picture rectangle commands C-c C-k (picture-clear-rectangle) and C-c C-w (picture-clear-rectangle-to-register) differ from the standard rectangle commands in that they normally clear the rectangle instead of deleting it; this is analogous with the way C-d is changed in Picture mode.

However, deletion of rectangles can be useful in Picture mode, so these commands delete the rectangle if given a numeric argument. C-c C-k either with or without a numeric argument saves the rectangle for C-c C-y.

The Picture mode commands for yanking rectangles differ from the standard ones in overwriting instead of inserting. This is the same way that Picture mode insertion of other text differs from other modes. C-c C-y (picture-yank-rectangle) inserts (by overwriting) the rectangle that was most recently killed, while C-c C-x (picture-yank-rectangle-from-register) does likewise for the rectangle found in a specified register.

Sending Mail

To send a message in Emacs, you start by typing a command (C-x m) to select and initialize the `*mail*' buffer. Then you edit the text and headers of the message in this buffer, and type another command (C-c C-s or C-c C-c) to send the message.

C-x m
Begin composing a message to send (compose-mail).
C-x 4 m
Likewise, but display the message in another window (compose-mail-other-window).
C-x 5 m
Likewise, but make a new frame (compose-mail-other-frame).
C-c C-s
In Mail mode, send the message (mail-send).
C-c C-c
Send the message and bury the mail buffer (mail-send-and-exit).

The command C-x m (compose-mail) selects a buffer named `*mail*' and initializes it with the skeleton of an outgoing message. C-x 4 m (compose-mail-other-window) selects the `*mail*' buffer in a different window, leaving the previous current buffer visible. C-x 5 m (compose-mail-other-frame) creates a new frame to select the `*mail*' buffer.

Because the mail-composition buffer is an ordinary Emacs buffer, you can switch to other buffers while in the middle of composing mail, and switch back later (or never). If you use the C-x m command again when you have been composing another message but have not sent it, you are asked to confirm before the old message is erased. If you answer n, the `*mail*' buffer is left selected with its old contents, so you can finish the old message and send it. C-u C-x m is another way to do this. Sending the message marks the `*mail*' buffer "unmodified," which avoids the need for confirmation when C-x m is next used.

If you are composing a message in the `*mail*' buffer and want to send another message before finishing the first, rename the `*mail*' buffer using M-x rename-uniquely (see section Miscellaneous Buffer Operations). Then you can use C-x m or its variants described above to make a new `*mail*' buffer. Once you've done that, you can work with each mail buffer independently.

The Format of the Mail Buffer

In addition to the text or body, a message has header fields which say who sent it, when, to whom, why, and so on. Some header fields, such as `Date' and `Sender', are created automatically when you send the message. Others, such as the recipient names, must be specified by you in order to send the message properly.

Mail mode provides a few commands to help you edit some header fields, and some are preinitialized in the buffer automatically at times. You can insert and edit header fields using ordinary editing commands.

The line in the buffer that says

--text follows this line--

is a special delimiter that separates the headers you have specified from the text. Whatever follows this line is the text of the message; the headers precede it. The delimiter line itself does not appear in the message actually sent. The text used for the delimiter line is controlled by the variable mail-header-separator.

Here is an example of what the headers and text in the mail buffer might look like.

To: gnu@gnu.org
CC: lungfish@spam.org, byob@spam.org
Subject: The Emacs Manual
--Text follows this line--
Please ignore this message.

Mail Header Fields

A header field in the mail buffer starts with a field name at the beginning of a line, terminated by a colon. Upper and lower case are equivalent in field names (and in mailing addresses also). After the colon and optional whitespace comes the contents of the field.

You can use any name you like for a header field, but normally people use only standard field names with accepted meanings. Here is a table of fields commonly used in outgoing messages.

`To'
This field contains the mailing addresses to which the message is addressed. If you list more than one address, use commas, not spaces, to separate them.
`Subject'
The contents of the `Subject' field should be a piece of text that says what the message is about. The reason `Subject' fields are useful is that most mail-reading programs can provide a summary of messages, listing the subject of each message but not its text.
`CC'
This field contains additional mailing addresses to send the message to, like `To' except that these readers should not regard the message as directed at them.
`BCC'
This field contains additional mailing addresses to send the message to, which should not appear in the header of the message actually sent. Copies sent this way are called blind carbon copies. To send a blind carbon copy of every outgoing message to yourself, set the variable mail-self-blind to t.
`FCC'
This field contains the name of one file and directs Emacs to append a copy of the message to that file when you send the message. If the file is in Rmail format, Emacs writes the message in Rmail format; otherwise, Emacs writes the message in system mail file format. To put a fixed file name in the `FCC' field each time you start editing an outgoing message, set the variable mail-archive-file-name to that file name. Unless you remove the `FCC' field before sending, the message will be written into that file when it is sent.
`From'
Use the `From' field to say who you are, when the account you are using to send the mail is not your own. The contents of the `From' field should be a valid mailing address, since replies will normally go there. If you don't specify the `From' field yourself, Emacs uses the value of user-mail-address as the default.
`Reply-to'
Use this field to direct replies to a different address. Most mail-reading programs (including Rmail) automatically send replies to the `Reply-to' address in preference to the `From' address. By adding a `Reply-to' field to your header, you can work around any problems your `From' address may cause for replies. To put a fixed `Reply-to' address into every outgoing message, set the variable mail-default-reply-to to that address (as a string). Then mail initializes the message with a `Reply-to' field as specified. You can delete or alter that header field before you send the message, if you wish. When Emacs starts up, if the environment variable REPLYTO is set, mail-default-reply-to is initialized from that environment variable.
`In-reply-to'
This field contains a piece of text describing a message you are replying to. Some mail systems can use this information to correlate related pieces of mail. Normally this field is filled in by Rmail when you reply to a message in Rmail, and you never need to think about it (see section Reading Mail with Rmail).
`References'
This field lists the message IDs of related previous messages. Rmail sets up this field automatically when you reply to a message.

The `To', `CC', `BCC' and `FCC' header fields can appear any number of times, and each such header field can contain multiple addresses, separated by commas. This way, you can specify any number of places to send the message. A `To', `CC', or `BCC' field can also have continuation lines: one or more lines starting with whitespace, following the starting line of the field, are considered part of the field. Here's an example of a `To' field with a continuation line:

To: foo@here.net, this@there.net,
  me@gnu.cambridge.mass.usa.earth.spiral3281

When you send the message, if you didn't write a `From' field yourself, Emacs puts in one for you. The variable mail-from-style controls the format:

nil
Use just the email address, as in `king@grassland.com'.
parens
Use both email address and full name, as in `king@grassland.com (Elvis Parsley)'.
angles
Use both email address and full name, as in `Elvis Parsley <king@grassland.com>'.
system-default
Allow the system to insert the `From' field.

Mail Aliases

You can define mail aliases in a file named `~/.mailrc'. These are short mnemonic names which stand for mail addresses or groups of mail addresses. Like many other mail programs, Emacs expands aliases when they occur in the `To', `From', `CC', `BCC', and `Reply-to' fields, plus their `Resent-' variants.

To define an alias in `~/.mailrc', write a line in the following format:

alias shortaddress fulladdresses

Here fulladdresses stands for one or more mail addresses for shortaddress to expand into. Separate multiple addresses with spaces; if an address contains a space, quote the whole address with a pair of double-quotes.

For instance, to make maingnu stand for gnu@gnu.org plus a local address of your own, put in this line:

alias maingnu gnu@gnu.org local-gnu

Emacs also recognizes include commands in `.mailrc' files. They look like this:

source filename

The file `~/.mailrc' is used primarily by other mail-reading programs; it can contain various other commands. Emacs ignores everything in it except for alias definitions and include commands.

Another way to define a mail alias, within Emacs alone, is with the define-mail-alias command. It prompts for the alias and then the full address. You can use it to define aliases in your `.emacs' file, like this:

(define-mail-alias "maingnu" "gnu@gnu.org")

define-mail-alias records aliases by adding them to a variable named mail-aliases. If you are comfortable with manipulating Lisp lists, you can set mail-aliases directly. The initial value of mail-aliases is t, which means that Emacs should read `.mailrc' to get the proper value.

You can specify a different file name to use instead of `~/.mailrc' by setting the variable mail-personal-alias-file.

Normally, Emacs expands aliases when you send the message. You do not need to expand mail aliases before sending the message, but you can expand them if you want to see where the mail will actually go. To do this, use the command M-x expand-mail-aliases; it expands all mail aliases currently present in the mail headers that hold addresses.

If you like, you can have mail aliases expand as abbrevs, as soon as you type them in (see section Abbrevs). To enable this feature, execute the following:

(add-hook 'mail-setup-hook 'mail-abbrevs-setup)

This can go in your `.emacs' file. See section Hooks. If you use this feature, you must use define-mail-abbrev instead of define-mail-alias; the latter does not work with this package. Note that the mail abbreviation package uses the variable mail-abbrevs instead of mail-aliases, and that all alias names are converted to lower case.

The mail abbreviation package also provides the C-c C-a (mail-interactive-insert-alias) command, which reads an alias name (with completion) and inserts its definition at point. This is useful when editing the message text itself or a header field such as `Subject' in which Emacs does not normally expand aliases.

Note that abbrevs expand only if you insert a word-separator character afterward. However, you can rebind C-n and M-> to cause expansion as well. Here's how to do that:

(add-hook 'mail-setup-hook
          '(lambda ()
             (substitute-key-definition
               'next-line 'mail-abbrev-next-line
               mail-mode-map global-map)
             (substitute-key-definition
               'end-of-buffer 'mail-abbrev-end-of-buffer
               mail-mode-map global-map)))

Mail Mode

The major mode used in the mail buffer is Mail mode, which is much like Text mode except that various special commands are provided on the C-c prefix. These commands all have to do specifically with editing or sending the message. In addition, Mail mode defines the character `%' as a word separator; this is helpful for using the word commands to edit mail addresses.

Mail mode is normally used in buffers set up automatically by the mail command and related commands. However, you can also switch to Mail mode in a file-visiting buffer. That is a useful thing to do if you have saved draft message text in a file.

Mail Sending

Mail mode has two commands for sending the message you have been editing:

C-c C-s
Send the message, and leave the mail buffer selected (mail-send).
C-c C-c
Send the message, and select some other buffer (mail-send-and-exit).

C-c C-s (mail-send) sends the message and marks the mail buffer unmodified, but leaves that buffer selected so that you can modify the message (perhaps with new recipients) and send it again. C-c C-c (mail-send-and-exit) sends and then deletes the window or switches to another buffer. It puts the mail buffer at the lowest priority for reselection by default, since you are finished with using it. This is the usual way to send the message.

In a file-visiting buffer, sending the message does not clear the modified flag, because only saving the file should do that. As a result, you don't get a warning if you try to send the same message twice.

When you send a message that contains non-ASCII characters, they need to be encoded with a coding system (see section Coding Systems). Usually the coding system is specified automatically by your chosen language environment (see section Language Environments). You can explicitly specify the coding system for outgoing mail by setting the variable sendmail-coding-system.

If the coding system thus determined does not handle the characters in a particular message, Emacs asks you to select the coding system to use, showing a list of possible coding systems.

Mail Header Editing

Mail mode provides special commands to move to particular header fields and to complete addresses in headers.

C-c C-f C-t
Move to the `To' header field, creating one if there is none (mail-to).
C-c C-f C-s
Move to the `Subject' header field, creating one if there is none (mail-subject).
C-c C-f C-c
Move to the `CC' header field, creating one if there is none (mail-cc).
C-c C-f C-b
Move to the `BCC' header field, creating one if there is none (mail-bcc).
C-c C-f C-f
Move to the `FCC' header field, creating one if there is none (mail-fcc).
M-TAB
Complete a mailing address (mail-complete).

There are five commands to move point to particular header fields, all based on the prefix C-c C-f (`C-f' is for "field"). They are listed in the table above. If the field in question does not exist, these commands create one. We provide special motion commands for these particular fields because they are the fields users most often want to edit.

While editing a header field that contains mailing addresses, such as `To:', `CC:' and `BCC:', you can complete a mailing address by typing M-TAB (mail-complete). It inserts the full name corresponding to the address, if it can determine the full name. The variable mail-complete-style controls whether to insert the full name, and what style to use, as in mail-from-style (see section Mail Header Fields).

For completion purposes, the valid mailing addresses are taken to be the local users' names plus your personal mail aliases. You can specify additional sources of valid addresses; use the customization buffer to see the options for this.

If you type M-TAB in the body of the message, it invokes ispell-complete-word, as in Text mode.

Citing Mail

Mail mode also has commands for yanking or citing all or part of a message that you are replying to. These commands are active only when you started sending a message using an Rmail command.

C-c C-y
Yank the selected message from Rmail (mail-yank-original).
C-c C-r
Yank the region from the Rmail buffer (mail-yank-region).
C-c C-q
Fill each paragraph cited from another message (mail-fill-yanked-message).

When mail sending is invoked from the Rmail mail reader using an Rmail command, C-c C-y can be used inside the mail buffer to insert the text of the message you are replying to. Normally it indents each line of that message three spaces and eliminates most header fields. A numeric argument specifies the number of spaces to indent. An argument of just C-u says not to indent at all and not to eliminate anything. C-c C-y always uses the current message from the Rmail buffer, so you can insert several old messages by selecting one in Rmail, switching to `*mail*' and yanking it, then switching back to Rmail to select another.

You can specify the text for C-c C-y to insert at the beginning of each line: set mail-yank-prefix to the desired string. (A value of nil means to use indentation; this is the default.) However, C-u C-c C-y never adds anything at the beginning of the inserted lines, regardless of the value of mail-yank-prefix.

To yank just a part of an incoming message, set the region in Rmail to the part you want; then go to the `*Mail*' message and type C-c C-r (mail-yank-region). Each line that is copied is indented or prefixed according to mail-yank-prefix.

After using C-c C-y or C-c C-r, you can type C-c C-q (mail-fill-yanked-message) to fill the paragraphs of the yanked old message or messages. One use of C-c C-q fills all such paragraphs, each one individually. To fill a single paragraph of the quoted message, use M-q. If filling does not automatically handle the type of citation prefix you use, try setting the fill prefix explicitly. See section Filling Text.

Mail Mode Miscellany

C-c C-t
Move to the beginning of the message body text (mail-text).
C-c C-w
Insert the file `~/.signature' at the end of the message text (mail-signature).
C-c C-i file RET
Insert the contents of file at the end of the outgoing message (mail-attach-file).
M-x ispell-message
Do spelling correction on the message text, but not on citations from other messages.

C-c C-t (mail-text) moves point to just after the header separator line--that is, to the beginning of the message body text.

C-c C-w (mail-signature) adds a standard piece of text at the end of the message to say more about who you are. The text comes from the file `~/.signature' in your home directory. To insert your signature automatically, set the variable mail-signature to t; then starting a mail message automatically inserts the contents of your `~/.signature' file. If you want to omit your signature from a particular message, delete it from the buffer before you send the message.

You can also set mail-signature to a string; then that string is inserted automatically as your signature when you start editing a message to send. If you set it to some other Lisp expression, the expression is evaluated each time, and its value (which should be a string) specifies the signature.

You can do spelling correction on the message text you have written with the command M-x ispell-message. If you have yanked an incoming message into the outgoing draft, this command skips what was yanked, but it checks the text that you yourself inserted. (It looks for indentation or mail-yank-prefix to distinguish the cited lines from your input.) See section Checking and Correcting Spelling.

To include a file in the outgoing message, you can use C-x i, the usual command to insert a file in the current buffer. But it is often more convenient to use a special command, C-c C-i (mail-attach-file). This command inserts the file contents at the end of the buffer, after your signature if any, with a delimiter line that includes the file name.

Turning on Mail mode (which C-x m does automatically) runs the normal hooks text-mode-hook and mail-mode-hook. Initializing a new outgoing message runs the normal hook mail-setup-hook; if you want to add special fields to your mail header or make other changes to the appearance of the mail buffer, use that hook. See section Hooks.

The main difference between these hooks is just when they are invoked. Whenever you type M-x mail, mail-mode-hook runs as soon as the `*mail*' buffer is created. Then the mail-setup function puts in the default contents of the buffer. After these default contents are inserted, mail-setup-hook runs.

Distracting the NSA

M-x spook adds a line of randomly chosen keywords to an outgoing mail message. The keywords are chosen from a list of words that suggest you are discussing something subversive.

The idea behind this feature is the suspicion that the NSA snoops on all electronic mail messages that contain keywords suggesting they might find them interesting. (The NSA says they don't, but that's what they would say.) The idea is that if lots of people add suspicious words to their messages, the NSA will get so busy with spurious input that they will have to give up reading it all.

Here's how to insert spook keywords automatically whenever you start entering an outgoing message:

(add-hook 'mail-setup-hook 'spook)

Whether or not this confuses the NSA, it at least amuses people.

Mail-Composition Methods

This chapter describes the usual Emacs mode for editing and sending mail--Mail mode. Emacs has alternative facilities for editing and sending mail, including MH-E and Message mode, not documented in this manual. You can choose any of them as your preferred method. The commands C-x m, C-x 4 m and C-x 5 m use whichever agent you have specified. So do various other Emacs commands and facilities that send mail.

To specify your mail-composition method, set the variable mail-user-agent. Currently legitimate values include sendmail-user-agent, mh-e-user-agent, and message-user-agent.

If you select a different mail-composition method, the information in this chapter about the `*mail*' buffer and Mail mode does not apply; other methods may use completely different commands with a different format in a differently named buffer.

Reading Mail with Rmail

Rmail is an Emacs subsystem for reading and disposing of mail that you receive. Rmail stores mail messages in files called Rmail files. Reading the message in an Rmail file is done in a special major mode, Rmail mode, which redefines most letters to run commands for managing mail. The command rmail-mode is used to switch into Rmail mode, and it runs the hook rmail-mode-hook as usual, but don't run this command by hand; it can't do a reasonable job unless the buffer is visiting a proper Rmail file.

Basic Concepts of Rmail

Using Rmail in the simplest fashion, you have one Rmail file `~/RMAIL' in which all of your mail is saved. It is called your primary Rmail file. The command M-x rmail reads your primary Rmail file, merges new mail in from your inboxes, displays the first message you haven't read yet, and lets you begin reading. The variable rmail-file-name specifies the name of the primary Rmail file.

Rmail uses narrowing to hide all but one message in the Rmail file. The message that is shown is called the current message. Rmail mode's special commands can do such things as delete the current message, copy it into another file, send a reply, or move to another message. You can also create multiple Rmail files and use Rmail to move messages between them.

Within the Rmail file, messages are normally arranged sequentially in order of receipt; you can specify other ways to sort them. Messages are assigned consecutive integers as their message numbers. The number of the current message is displayed in Rmail's mode line, followed by the total number of messages in the file. You can move to a message by specifying its message number with the j key (see section Moving Among Messages).

Following the usual conventions of Emacs, changes in an Rmail file become permanent only when the file is saved. You can save it with s (rmail-save), which also expunges deleted messages from the file first (see section Deleting Messages). To save the file without expunging, use C-x C-s. Rmail also saves the Rmail file after merging new mail from an inbox file (see section Rmail Files and Inboxes).

You can exit Rmail with q (rmail-quit); this expunges and saves the Rmail file and then switches to another buffer. But there is no need to `exit' formally. If you switch from Rmail to editing in other buffers, and never happen to switch back, you have exited. (The Rmail command b, rmail-bury, does this for you.) Just make sure to save the Rmail file eventually (like any other file you have changed). C-x s is a good enough way to do this (see section Saving Files).

Scrolling Within a Message

When Rmail displays a message that does not fit on the screen, you must scroll through it to read the rest. You could do this with C-v, M-v and M-<, but in Rmail scrolling is so frequent that it deserves to be easier to type.

SPC
Scroll forward (scroll-up).
DEL
Scroll backward (scroll-down).
.
Scroll to start of message (rmail-beginning-of-message).

Since the most common thing to do while reading a message is to scroll through it by screenfuls, Rmail makes SPC and DEL synonyms of C-v (scroll-up) and M-v (scroll-down)

The command . (rmail-beginning-of-message) scrolls back to the beginning of the selected message. This is not quite the same as M-<: for one thing, it does not set the mark; for another, it resets the buffer boundaries to the current message if you have changed them.

Moving Among Messages

The most basic thing to do with a message is to read it. The way to do this in Rmail is to make the message current. The usual practice is to move sequentially through the file, since this is the order of receipt of messages. When you enter Rmail, you are positioned at the first message that you have not yet made current (that is, the first one that has the `unseen' attribute; see section Rmail Attributes). Move forward to see the other new messages; move backward to reexamine old messages.

n
Move to the next nondeleted message, skipping any intervening deleted messages (rmail-next-undeleted-message).
p
Move to the previous nondeleted message (rmail-previous-undeleted-message).
M-n
Move to the next message, including deleted messages (rmail-next-message).
M-p
Move to the previous message, including deleted messages (rmail-previous-message).
j
Move to the first message. With argument n, move to message number n (rmail-show-message).
>
Move to the last message (rmail-last-message).
<
Move to the first message (rmail-first-message).
M-s regexp RET
Move to the next message containing a match for regexp (rmail-search).
- M-s regexp RET
Move to the previous message containing a match for regexp.

n and p are the usual way of moving among messages in Rmail. They move through the messages sequentially, but skip over deleted messages, which is usually what you want to do. Their command definitions are named rmail-next-undeleted-message and rmail-previous-undeleted-message. If you do not want to skip deleted messages--for example, if you want to move to a message to undelete it--use the variants M-n and M-p (rmail-next-message and rmail-previous-message). A numeric argument to any of these commands serves as a repeat count.

In Rmail, you can specify a numeric argument by typing just the digits. You don't need to type C-u first.

The M-s (rmail-search) command is Rmail's version of search. The usual incremental search command C-s works in Rmail, but it searches only within the current message. The purpose of M-s is to search for another message. It reads a regular expression (see section Syntax of Regular Expressions) nonincrementally, then searches starting at the beginning of the following message for a match. It then selects that message. If regexp is empty, M-s reuses the regexp used the previous time.

To search backward in the file for another message, give M-s a negative argument. In Rmail you can do this with - M-s.

It is also possible to search for a message based on labels. See section Labels.

To move to a message specified by absolute message number, use j (rmail-show-message) with the message number as argument. With no argument, j selects the first message. < (rmail-first-message) also selects the first message. > (rmail-last-message) selects the last message.

Deleting Messages

When you no longer need to keep a message, you can delete it. This flags it as ignorable, and some Rmail commands pretend it is no longer present; but it still has its place in the Rmail file, and still has its message number.

Expunging the Rmail file actually removes the deleted messages. The remaining messages are renumbered consecutively. Expunging is the only action that changes the message number of any message, except for undigestifying (see section Digest Messages).

d
Delete the current message, and move to the next nondeleted message (rmail-delete-forward).
C-d
Delete the current message, and move to the previous nondeleted message (rmail-delete-backward).
u
Undelete the current message, or move back to a deleted message and undelete it (rmail-undelete-previous-message).
x
Expunge the Rmail file (rmail-expunge).

There are two Rmail commands for deleting messages. Both delete the current message and select another message. d (rmail-delete-forward) moves to the following message, skipping messages already deleted, while C-d (rmail-delete-backward) moves to the previous nondeleted message. If there is no nondeleted message to move to in the specified direction, the message that was just deleted remains current. A numeric argument to either command reverses the direction of motion after deletion.

Whenever Rmail deletes a message, it invokes the function(s) listed in rmail-delete-message-hook. When the hook functions are invoked, the message has been marked deleted, but it is still the current message in the Rmail buffer.

To make all the deleted messages finally vanish from the Rmail file, type x (rmail-expunge). Until you do this, you can still undelete the deleted messages. The undeletion command, u (rmail-undelete-previous-message), is designed to cancel the effect of a d command in most cases. It undeletes the current message if the current message is deleted. Otherwise it moves backward to previous messages until a deleted message is found, and undeletes that message.

You can usually undo a d with a u because the u moves back to and undeletes the message that the d deleted. But this does not work when the d skips a few already-deleted messages that follow the message being deleted; then the u command undeletes the last of the messages that were skipped. There is no clean way to avoid this problem. However, by repeating the u command, you can eventually get back to the message that you intend to undelete. You can also select a particular deleted message with the M-p command, then type u to undelete it.

A deleted message has the `deleted' attribute, and as a result `deleted' appears in the mode line when the current message is deleted. In fact, deleting or undeleting a message is nothing more than adding or removing this attribute. See section Rmail Attributes.

Rmail Files and Inboxes

The operating system places incoming mail for you in a file that we call your inbox. When you start up Rmail, it runs a C program called movemail to copy the new messages from your inbox into your primary Rmail file, which also contains other messages saved from previous Rmail sessions. It is in this file that you actually read the mail with Rmail. This operation is called getting new mail. You can get new mail at any time in Rmail by typing g.

The variable rmail-primary-inbox-list contains a list of the files which are inboxes for your primary Rmail file. If you don't set this variable explicitly, it is initialized from the MAIL environment variable, or, as a last resort, set to nil, which means to use the default inbox. The default inbox is `/var/mail/username', `/usr/spool/mail/username', or `/usr/mail/username', depending on your operating system.

To see what the default is on your system, use C-h v rmail-primary-inbox RET. You can specify the inbox file(s) for any Rmail file with the command set-rmail-inbox-list; see section Multiple Rmail Files.

There are two reasons for having separate Rmail files and inboxes.

  1. The inbox file format varies between operating systems and according to the other mail software in use. Only one part of Rmail needs to know about the alternatives, and it need only understand how to convert all of them to Rmail's own format.
  2. It is very cumbersome to access an inbox file without danger of losing mail, because it is necessary to interlock with mail delivery. Moreover, different operating systems use different interlocking techniques. The strategy of moving mail out of the inbox once and for all into a separate Rmail file avoids the need for interlocking in all the rest of Rmail, since only Rmail operates on the Rmail file.

Rmail was written to use Babyl format as its internal format. Since then, we have recognized that the usual inbox format on Unix and GNU systems is adequate for the job, and we plan to change Rmail to use that as its internal format. However, the Rmail file will still be separate from the inbox file, even on systems where their format is the same.

Multiple Rmail Files

Rmail operates by default on your primary Rmail file, which is named `~/RMAIL' and receives your incoming mail from your system inbox file. But you can also have other Rmail files and edit them with Rmail. These files can receive mail through their own inboxes, or you can move messages into them with explicit Rmail commands (see section Copying Messages Out to Files).

i file RET
Read file into Emacs and run Rmail on it (rmail-input).
M-x set-rmail-inbox-list RET files RET
Specify inbox file names for current Rmail file to get mail from.
g
Merge new mail from current Rmail file's inboxes (rmail-get-new-mail).
C-u g file RET
Merge new mail from inbox file file.

To run Rmail on a file other than your primary Rmail file, you may use the i (rmail-input) command in Rmail. This visits the file in Rmail mode. You can use M-x rmail-input even when not in Rmail.

The file you read with i should normally be a valid Rmail file. If it is not, Rmail tries to decompose it into a stream of messages in various known formats. If it succeeds, it converts the whole file to an Rmail file. If you specify a file name that doesn't exist, i initializes a new buffer for creating a new Rmail file.

You can also select an Rmail file from a menu. Choose first the menu bar Classify item, then from the Classify menu choose the Input Rmail File item; then choose the Rmail file you want. The variables rmail-secondary-file-directory and rmail-secondary-file-regexp specify which files to offer in the menu: the first variable says which directory to find them in; the second says which files in that directory to offer (all those that match the regular expression). These variables also apply to choosing a file for output (see section Copying Messages Out to Files).

Each Rmail file can contain a list of inbox file names; you can specify this list with M-x set-rmail-inbox-list RET files RET. The argument can contain any number of file names, separated by commas. It can also be empty, which specifies that this file should have no inboxes. Once a list of inboxes is specified, the Rmail file remembers it permanently until you specify a different list.

As a special exception, if your primary Rmail file does not specify any inbox files, it uses your standard system inbox.

The g command (rmail-get-new-mail) merges mail into the current Rmail file from its specified inboxes. If the Rmail file has no inboxes, g does nothing. The command M-x rmail also merges new mail into your primary Rmail file.

To merge mail from a file that is not the usual inbox, give the g key a numeric argument, as in C-u g. Then it reads a file name and merges mail from that file. The inbox file is not deleted or changed in any way when g with an argument is used. This is, therefore, a general way of merging one file of messages into another.

Copying Messages Out to Files

These commands copy messages from an Rmail file into another file.

o file RET
Append a copy of the current message to the file file, using Rmail file format by default (rmail-output-to-rmail-file).
C-o file RET
Append a copy of the current message to the file file, using system inbox file format by default (rmail-output).
w file RET
Output just the message body to the file file, taking the default file name from the message `Subject' header.

The commands o and C-o copy the current message into a specified file. This file may be an Rmail file or it may be in system inbox format; the output commands ascertain the file's format and write the copied message in that format.

When copying a message to a file in Unix mail file format, these commands include whichever header fields are currently visible. Use the t command first, if you wish, to specify which headers to show (and copy).

The o and C-o commands differ in two ways: each has its own separate default file name, and each specifies a choice of format to use when the file does not already exist. The o command uses Rmail format when it creates a new file, while C-o uses system inbox format for a new file. The default file name for o is the file name used last with o, and the default file name for C-o is the file name used last with C-o.

If the output file is an Rmail file currently visited in an Emacs buffer, the output commands copy the message into that buffer. It is up to you to save the buffer eventually in its file.

Sometimes you may receive a message whose body holds the contents of a file. You can save the body to a file (excluding the message header) with the w command (rmail-output-body-to-file). Often these messages contain the intended file name in the `Subject' field, so the w command uses the `Subject' field as the default for the output file name. However, the file name is read using the minibuffer, so you can specify a different name if you wish.

You can also output a message to an Rmail file chosen with a menu. Choose first the menu bar Classify item, then from the Classify menu choose the Output Rmail File menu item; then choose the Rmail file you want. This outputs the current message to that file, like the o command. The variables rmail-secondary-file-directory and rmail-secondary-file-regexp specify which files to offer in the menu: the first variable says which directory to find them in; the second says which files in that directory to offer (all those that match the regular expression).

Copying a message gives the original copy of the message the `filed' attribute, so that `filed' appears in the mode line when such a message is current. If you like to keep just a single copy of every mail message, set the variable rmail-delete-after-output to t; then the o and C-o commands delete the original message after copying it. (You can undelete the original afterward if you wish.)

Copying messages into files in system inbox format uses the header fields that are displayed in Rmail at the time. Thus, if you use the t command to view the entire header and then copy the message, the entire header is copied. See section Display of Messages.

The variable rmail-output-file-alist lets you specify intelligent defaults for the output file, based on the contents of the current message. The value should be a list whose elements have this form:

(regexp . name-exp)

If there's a match for regexp in the current message, then the default file name for output is name-exp. If multiple elements match the message, the first matching element decides the default file name. The subexpression name-exp may be a string constant giving the file name to use, or more generally it may be any Lisp expression that returns a file name as a string. rmail-output-file-alist applies to both o and C-o.

Labels

Each message can have various labels assigned to it as a means of classification. Each label has a name; different names are different labels. Any given label is either present or absent on a particular message. A few label names have standard meanings and are given to messages automatically by Rmail when appropriate; these special labels are called attributes. All other labels are assigned only by users.

a label RET
Assign the label label to the current message (rmail-add-label).
k label RET
Remove the label label from the current message (rmail-kill-label).
C-M-n labels RET
Move to the next message that has one of the labels labels (rmail-next-labeled-message).
C-M-p labels RET
Move to the previous message that has one of the labels labels (rmail-previous-labeled-message).
C-M-l labels RET
Make a summary of all messages containing any of the labels labels (rmail-summary-by-labels).

The a (rmail-add-label) and k (rmail-kill-label) commands allow you to assign or remove any label on the current message. If the label argument is empty, it means to assign or remove the same label most recently assigned or removed.

Once you have given messages labels to classify them as you wish, there are two ways to use the labels: in moving and in summaries.

The command C-M-n labels RET (rmail-next-labeled-message) moves to the next message that has one of the labels labels. The argument labels specifies one or more label names, separated by commas. C-M-p (rmail-previous-labeled-message) is similar, but moves backwards to previous messages. A numeric argument to either command serves as a repeat count.

The command C-M-l labels RET (rmail-summary-by-labels) displays a summary containing only the messages that have at least one of a specified set of labels. The argument labels is one or more label names, separated by commas. See section Summaries, for information on summaries.

If the labels argument to C-M-n, C-M-p or C-M-l is empty, it means to use the last set of labels specified for any of these commands.

Rmail Attributes

Some labels such as `deleted' and `filed' have built-in meanings and are assigned to or removed from messages automatically at appropriate times; these labels are called attributes. Here is a list of Rmail attributes:

`unseen'
Means the message has never been current. Assigned to messages when they come from an inbox file, and removed when a message is made current. When you start Rmail, it initially shows the first message that has this attribute.
`deleted'
Means the message is deleted. Assigned by deletion commands and removed by undeletion commands (see section Deleting Messages).
`filed'
Means the message has been copied to some other file. Assigned by the file output commands (see section Multiple Rmail Files).
`answered'
Means you have mailed an answer to the message. Assigned by the r command (rmail-reply). See section Sending Replies.
`forwarded'
Means you have forwarded the message. Assigned by the f command (rmail-forward). See section Sending Replies.
`edited'
Means you have edited the text of the message within Rmail. See section Editing Within a Message.
`resent'
Means you have resent the message. Assigned by the command M-x rmail-resend. See section Sending Replies.

All other labels are assigned or removed only by the user, and have no standard meaning.

Sending Replies

Rmail has several commands that use Mail mode to send outgoing mail. See section Sending Mail, for information on using Mail mode, including certain features meant to work with Rmail. What this section documents are the special commands of Rmail for entering Mail mode. Note that the usual keys for sending mail---C-x m, C-x 4 m, and C-x 5 m---are available in Rmail mode and work just as they usually do.

m
Send a message (rmail-mail).
c
Continue editing the already started outgoing message (rmail-continue).
r
Send a reply to the current Rmail message (rmail-reply).
f
Forward the current message to other users (rmail-forward).
C-u f
Resend the current message to other users (rmail-resend).
M-m
Try sending a bounced message a second time (rmail-retry-failure).

The most common reason to send a message while in Rmail is to reply to the message you are reading. To do this, type r (rmail-reply). This displays the `*mail*' buffer in another window, much like C-x 4 m, but preinitializes the `Subject', `To', `CC' and `In-reply-to' header fields based on the message you are replying to. The `To' field starts out as the address of the person who sent the message you received, and the `CC' field starts out with all the other recipients of that message.

You can exclude certain recipients from being placed automatically in the `CC', using the variable rmail-dont-reply-to-names. Its value should be a regular expression (as a string); any recipient that the regular expression matches, is excluded from the `CC' field. The default value matches your own name, and any name starting with `info-'. (Those names are excluded because there is a convention of using them for large mailing lists to broadcast announcements.)

To omit the `CC' field completely for a particular reply, enter the reply command with a numeric argument: C-u r or 1 r.

Once the `*mail*' buffer has been initialized, editing and sending the mail goes as usual (see section Sending Mail). You can edit the presupplied header fields if they are not right for you. You can also use the commands of Mail mode (see section Mail Mode), including C-c C-y which yanks in the message that you are replying to. You can switch to the Rmail buffer, select a different message there, switch back, and yank the new current message.

Sometimes a message does not reach its destination. Mailers usually send the failed message back to you, enclosed in a failure message. The Rmail command M-m (rmail-retry-failure) prepares to send the same message a second time: it sets up a `*mail*' buffer with the same text and header fields as before. If you type C-c C-c right away, you send the message again exactly the same as the first time. Alternatively, you can edit the text or headers and then send it. The variable rmail-retry-ignored-headers, in the same format as rmail-ignored-headers (see section Display of Messages), controls which headers are stripped from the failed message when retrying it; it defaults to nil.

Another frequent reason to send mail in Rmail is to forward the current message to other users. f (rmail-forward) makes this easy by preinitializing the `*mail*' buffer with the current message as the text, and a subject designating a forwarded message. All you have to do is fill in the recipients and send. When you forward a message, recipients get a message which is "from" you, and which has the original message in its contents.

Forwarding a message encloses it between two delimiter lines. It also modifies every line that starts with a dash, by inserting `- ' at the start of the line. When you receive a forwarded message, if it contains something besides ordinary text--for example, program source code--you might find it useful to undo that transformation. You can do this by selecting the forwarded message and typing M-x unforward-rmail-message. This command extracts the original forwarded message, deleting the inserted `- ' strings, and inserts it into the Rmail file as a separate message immediately following the current one.

Resending is an alternative similar to forwarding; the difference is that resending sends a message that is "from" the original sender, just as it reached you--with a few added header fields `Resent-from' and `Resent-to' to indicate that it came via you. To resend a message in Rmail, use C-u f. (f runs rmail-forward, which is programmed to invoke rmail-resend if you provide a numeric argument.)

The m (rmail-mail) command is used to start editing an outgoing message that is not a reply. It leaves the header fields empty. Its only difference from C-x 4 m is that it makes the Rmail buffer accessible for C-c C-y, just as r does. Thus, m can be used to reply to or forward a message; it can do anything r or f can do.

The c (rmail-continue) command resumes editing the `*mail*' buffer, to finish editing an outgoing message you were already composing, or to alter a message you have sent.

If you set the variable rmail-mail-new-frame to a non-nil value, then all the Rmail commands to start sending a message create a new frame to edit it in. This frame is deleted when you send the message, or when you use the `Don't Send' item in the `Mail' menu.

All the Rmail commands to send a message use the mail-composition method that you have chosen (see section Mail-Composition Methods).

Summaries

A summary is a buffer containing one line per message to give you an overview of the mail in an Rmail file. Each line shows the message number, the sender, the labels, and the subject. Almost all Rmail commands are valid in the summary buffer also; these apply to the message described by the current line of the summary. Moving point in the summary buffer selects messages as you move to their summary lines.

A summary buffer applies to a single Rmail file only; if you are editing multiple Rmail files, each one can have its own summary buffer. The summary buffer name is made by appending `-summary' to the Rmail buffer's name. Normally only one summary buffer is displayed at a time.

Making Summaries

Here are the commands to create a summary for the current Rmail file. Once the Rmail file has a summary buffer, changes in the Rmail file (such as deleting or expunging messages, and getting new mail) automatically update the summary.

h
C-M-h
Summarize all messages (rmail-summary).
l labels RET
C-M-l labels RET
Summarize messages that have one or more of the specified labels (rmail-summary-by-labels).
C-M-r rcpts RET
Summarize messages that have one or more of the specified recipients (rmail-summary-by-recipients).
C-M-t topic RET
Summarize messages that have a match for the specified regexp topic in their subjects (rmail-summary-by-topic).

The h or C-M-h (rmail-summary) command fills the summary buffer for the current Rmail file with a summary of all the messages in the file. It then displays and selects the summary buffer in another window.

C-M-l labels RET (rmail-summary-by-labels) makes a partial summary mentioning only the messages that have one or more of the labels labels. labels should contain label names separated by commas.

C-M-r rcpts RET (rmail-summary-by-recipients) makes a partial summary mentioning only the messages that have one or more of the recipients rcpts. rcpts should contain mailing addresses separated by commas.

C-M-t topic RET (rmail-summary-by-topic) makes a partial summary mentioning only the messages whose subjects have a match for the regular expression topic.

Note that there is only one summary buffer for any Rmail file; making one kind of summary discards any previously made summary.

The variable rmail-summary-window-size says how many lines to use for the summary window. The variable rmail-summary-line-count-flag controls whether the summary line for a message should include the line count of the message.

Editing in Summaries

You can use the Rmail summary buffer to do almost anything you can do in the Rmail buffer itself. In fact, once you have a summary buffer, there's no need to switch back to the Rmail buffer.

You can select and display various messages in the Rmail buffer, from the summary buffer, just by moving point in the summary buffer to different lines. It doesn't matter what Emacs command you use to move point; whichever line point is on at the end of the command, that message is selected in the Rmail buffer.

Almost all Rmail commands work in the summary buffer as well as in the Rmail buffer. Thus, d in the summary buffer deletes the current message, u undeletes, and x expunges. o and C-o output the current message to a file; r starts a reply to it. You can scroll the current message while remaining in the summary buffer using SPC and DEL.

The Rmail commands to move between messages also work in the summary buffer, but with a twist: they move through the set of messages included in the summary. They also ensure the Rmail buffer appears on the screen (unlike cursor motion commands, which update the contents of the Rmail buffer but don't display it in a window unless it already appears). Here is a list of these commands:

n
Move to next line, skipping lines saying `deleted', and select its message.
p
Move to previous line, skipping lines saying `deleted', and select its message.
M-n
Move to next line and select its message.
M-p
Move to previous line and select its message.
>
Move to the last line, and select its message.
<
Move to the first line, and select its message.
M-s pattern RET
Search through messages for pattern starting with the current message; select the message found, and move point in the summary buffer to that message's line.

Deletion, undeletion, and getting new mail, and even selection of a different message all update the summary buffer when you do them in the Rmail buffer. If the variable rmail-redisplay-summary is non-nil, these actions also bring the summary buffer back onto the screen.

When you are finished using the summary, type Q (rmail-summary-wipe) to delete the summary buffer's window. You can also exit Rmail while in the summary: q (rmail-summary-quit) deletes the summary window, then exits from Rmail by saving the Rmail file and switching to another buffer.

Sorting the Rmail File

M-x rmail-sort-by-date
Sort messages of current Rmail file by date.
M-x rmail-sort-by-subject
Sort messages of current Rmail file by subject.
M-x rmail-sort-by-author
Sort messages of current Rmail file by author's name.
M-x rmail-sort-by-recipient
Sort messages of current Rmail file by recipient's names.
M-x rmail-sort-by-correspondent
Sort messages of current Rmail file by the name of the other correspondent.
M-x rmail-sort-by-lines
Sort messages of current Rmail file by size (number of lines).
M-x rmail-sort-by-keywords RET labels RET
Sort messages of current Rmail file by labels. The argument labels should be a comma-separated list of labels. The order of these labels specifies the order of messages; messages with the first label come first, messages with the second label come second, and so on. Messages which have none of these labels come last.

The Rmail sort commands perform a stable sort: if there is no reason to prefer either one of two messages, their order remains unchanged. You can use this to sort by more than one criterion. For example, if you use rmail-sort-by-date and then rmail-sort-by-author, messages from the same author appear in order by date.

With a numeric argument, all these commands reverse the order of comparison. This means they sort messages from newest to oldest, from biggest to smallest, or in reverse alphabetical order.

Display of Messages

Rmail reformats the header of each message before displaying it for the first time. Reformatting hides uninteresting header fields to reduce clutter. You can use the t command to show the entire header or to repeat the header reformatting operation.

t
Toggle display of complete header (rmail-toggle-header).

Reformatting the header involves deleting most header fields, on the grounds that they are not interesting. The variable rmail-ignored-headers holds a regular expression that specifies which header fields to hide in this way--if it matches the beginning of a header field, that whole field is hidden.

Rmail saves the complete original header before reformatting; to see it, use the t command (rmail-toggle-header). This discards the reformatted headers of the current message and displays it with the original header. Repeating t reformats the message again. Selecting the message again also reformats.

One consequence of this is that if you edit the reformatted header (using e; see section Editing Within a Message), subsequent use of t will discard your edits. On the other hand, if you use e after t, to edit the original (unreformatted) header, those changes are permanent.

When the t command has a prefix argument, a positive argument means to show the reformatted header, and a zero or negative argument means to show the full header.

When used with a window system that supports multiple fonts, Rmail highlights certain header fields that are especially interesting--by default, the `From' and `Subject' fields. The variable rmail-highlighted-headers holds a regular expression that specifies the header fields to highlight; if it matches the beginning of a header field, that whole field is highlighted.

If you specify unusual colors for your text foreground and background, the colors used for highlighting may not go well with them. If so, specify different colors for the highlight face. That is worth doing because the highlight face is used for other kinds of highlighting as well. See section Using Multiple Typefaces, for how to do this.

To turn off highlighting entirely in Rmail, set rmail-highlighted-headers to nil.

Editing Within a Message

Most of the usual Emacs commands are available in Rmail mode, though a few, such as C-M-n and C-M-h, are redefined by Rmail for other purposes. However, the Rmail buffer is normally read only, and most of the letters are redefined as Rmail commands. If you want to edit the text of a message, you must use the Rmail command e.

e
Edit the current message as ordinary text.

The e command (rmail-edit-current-message) switches from Rmail mode into Rmail Edit mode, another major mode which is nearly the same as Text mode. The mode line indicates this change.

In Rmail Edit mode, letters insert themselves as usual and the Rmail commands are not available. When you are finished editing the message and are ready to go back to Rmail, type C-c C-c, which switches back to Rmail mode. Alternatively, you can return to Rmail mode but cancel all the editing that you have done, by typing C-c C-].

Entering Rmail Edit mode runs the hook text-mode-hook; then it runs the hook rmail-edit-mode-hook (see section Hooks). It adds the attribute `edited' to the message. It also displays the full headers of the message, so that you can edit the headers as well as the body of the message, and your changes in the the headers will be permanent.

Digest Messages

A digest message is a message which exists to contain and carry several other messages. Digests are used on some moderated mailing lists; all the messages that arrive for the list during a period of time such as one day are put inside a single digest which is then sent to the subscribers. Transmitting the single digest uses much less computer time than transmitting the individual messages even though the total size is the same, because the per-message overhead in network mail transmission is considerable.

When you receive a digest message, the most convenient way to read it is to undigestify it: to turn it back into many individual messages. Then you can read and delete the individual messages as it suits you.

To do this, select the digest message and type the command M-x undigestify-rmail-message. This extracts the submessages as separate Rmail messages, and inserts them following the digest. The digest message itself is flagged as deleted.

Converting an Rmail File to Inbox Format

The command M-x unrmail converts a file in Rmail format to inbox format (also known as the system mailbox format), so that you can use it with other mail-editing tools. You must specify two arguments, the name of the Rmail file and the name to use for the converted file. M-x unrmail does not alter the Rmail file itself.

Reading Rot13 Messages

Mailing list messages that might offend some readers are sometimes encoded in a simple code called rot13---so named because it rotates the alphabet by 13 letters. This code is not for secrecy, as it provides none; rather, it enables those who might be offended to avoid ever seeing the real text of the message.

To view a buffer using the rot13 code, use the command M-x rot13-other-window. This displays the current buffer in another window which applies the code when displaying the text.

movemail and POP

When getting new mail, Rmail first copies the new mail from the inbox file to the Rmail file; then it saves the Rmail file; then it truncates the inbox file. This way, a system crash may cause duplication of mail between the inbox and the Rmail file, but cannot lose mail. If rmail-preserve-inbox is non-nil, then Rmail will copy new mail from the inbox file to the Rmail file without truncating the inbox file. You may wish to set this, for example, on a portable computer you use to check your mail via POP while traveling, so that your mail will remain on the server and you can save it later on your workstation.

In some cases, Rmail copies the new mail from the inbox file indirectly. First it runs the movemail program to move the mail from the inbox to an intermediate file called `~/.newmail-inboxname'. Then Rmail merges the new mail from that file, saves the Rmail file, and only then deletes the intermediate file. If there is a crash at the wrong time, this file continues to exist, and Rmail will use it again the next time it gets new mail from that inbox.

If Rmail is unable to convert the data in `~/.newmail-inboxname' into Babyl format, it renames the file to `~/RMAILOSE.n' (n is an integer chosen to make the name unique) so that Rmail will not have trouble with the data again. You should look at the file, find whatever message confuses Rmail (probably one that includes the control-underscore character, octal code 037), and delete it. Then you can use 1 g to get new mail from the corrected file.

Some sites use a method called POP for accessing users' inbox data instead of storing the data in inbox files. movemail can work with POP if you compile it with the macro MAIL_USE_POP defined. (You can achieve that by specifying `--with-pop' when you run configure during the installation of Emacs.) movemail only works with POP3, not with older versions of POP.

Assuming you have compiled and installed movemail appropriately, you can specify a POP inbox by using a "file name" of the form `po:username', in the inbox list of an Rmail file. movemail handles such a name by opening a connection to the POP server. The MAILHOST environment variable specifies the machine to look for the server on.

Accessing mail via POP may require a password. If the variable rmail-pop-password is non-nil, it specifies the password to use for POP. Alternatively, if rmail-pop-password-required is non-nil, then Rmail asks you for the password to use.

If you need to pass additional command-line flags to movemail, set the variable rmail-movemail-flags a list of the flags you wish to use. Do not use this variable to pass the `-p' flag to preserve your inbox contents; use rmail-preserve-inbox instead.

The movemail program installed at your site may support Kerberos authentication. If it is supported, it is used by default whenever you attempt to retrieve POP mail when rmail-pop-password and rmail-pop-password-required are unset.

Some POP servers store messages in reverse order. If your server does this, and you would rather read your mail in the order in which it was received, you can tell movemail to reverse the order of downloaded messages by adding the `-r' flag to rmail-movemail-flags.

Dired, the Directory Editor

Dired makes an Emacs buffer containing a listing of a directory, and optionally some of its subdirectories as well. You can use the normal Emacs commands to move around in this buffer, and special Dired commands to operate on the files listed.

Entering Dired

To invoke Dired, do C-x d or M-x dired. The command reads a directory name or wildcard file name pattern as a minibuffer argument to specify which files to list. Where dired differs from list-directory is in putting the buffer into Dired mode so that the special commands of Dired are available.

The variable dired-listing-switches specifies the options to give to ls for listing directory; this string must contain `-l'. If you use a numeric prefix argument with the dired command, you can specify the ls switches with the minibuffer before you enter the directory specification.

To display the Dired buffer in another window rather than in the selected window, use C-x 4 d (dired-other-window) instead of C-x d. C-x 5 d (dired-other-frame) uses a separate frame to display the Dired buffer.

Commands in the Dired Buffer

The Dired buffer is "read-only," and inserting text in it is not useful, so ordinary printing characters such as d and x are used for special Dired commands. Some Dired commands mark or flag the current file (that is, the file on the current line); other commands operate on the marked files or on the flagged files.

All the usual Emacs cursor motion commands are available in Dired buffers. Some special-purpose cursor motion commands are also provided. The keys C-n and C-p are redefined to put the cursor at the beginning of the file name on the line, rather than at the beginning of the line.

For extra convenience, SPC and n in Dired are equivalent to C-n. p is equivalent to C-p. (Moving by lines is so common in Dired that it deserves to be easy to type.) DEL (move up and unflag) is often useful simply for moving up.

Deleting Files with Dired

The primary use of Dired is to flag files for deletion and then delete the files previously flagged.

d
Flag this file for deletion.
u
Remove deletion flag on this line.
DEL
Move point to previous line and remove the deletion flag on that line.
x
Delete the files that are flagged for deletion.

You can flag a file for deletion by moving to the line describing the file and typing d (dired-flag-file-deletion). The deletion flag is visible as a `D' at the beginning of the line. This command moves point to the next line, so that repeated d commands flag successive files. A numeric argument serves as a repeat count.

The files are flagged for deletion rather than deleted immediately to reduce the danger of deleting a file accidentally. Until you direct Dired to expunge the flagged files, you can remove deletion flags using the commands u and DEL. u (dired-unmark) works just like d, but removes flags rather than making flags. DEL (dired-unmark-backward) moves upward, removing flags; it is like u with argument -1.

To delete the flagged files, type x (dired-expunge). This command first displays a list of all the file names flagged for deletion, and requests confirmation with yes. If you confirm, Dired deletes the flagged files, then deletes their lines from the text of the Dired buffer. The shortened Dired buffer remains selected.

If you answer no or quit with C-g when asked to confirm, you return immediately to Dired, with the deletion flags still present in the buffer, and no files actually deleted.

Flagging Many Files at Once

#
Flag all auto-save files (files whose names start and end with `#') for deletion (see section Auto-Saving: Protection Against Disasters).
~
Flag all backup files (files whose names end with `~') for deletion (see section Backup Files).
&
Flag for deletion all files with certain kinds of names, names that suggest you could easily create the files again.
. (Period)
Flag excess numeric backup files for deletion. The oldest and newest few backup files of any one file are exempt; the middle ones are flagged.
% d regexp RET
Flag for deletion all files whose names match the regular expression regexp.

The #, ~, &, and . commands flag many files for deletion, based on their file names. These commands are useful precisely because they do not themselves delete any files; you can remove the deletion flags from any flagged files that you really wish to keep.

& (dired-flag-garbage-files) flags files whose names match the regular expression specified by the variable dired-garbage-files-regexp. By default, this matches certain files produced by TeX, and the `.orig' and `.rej' files produced by patch.

# (dired-flag-auto-save-files) flags for deletion all files whose names look like auto-save files (see section Auto-Saving: Protection Against Disasters)---that is, files whose names begin and end with `#'. ~ (dired-flag-backup-files) flags for deletion all files whose names say they are backup files (see section Backup Files)---that is, whose names end in `~'.

. (period, dired-clean-directory) flags just some of the backup files for deletion: all but the oldest few and newest few backups of any one file. Normally dired-kept-versions (not kept-new-versions; that applies only when saving) specifies the number of newest versions of each file to keep, and kept-old-versions specifies the number of oldest versions to keep.

Period with a positive numeric argument, as in C-u 3 ., specifies the number of newest versions to keep, overriding dired-kept-versions. A negative numeric argument overrides kept-old-versions, using minus the value of the argument to specify the number of oldest versions of each file to keep.

The % d command flags all files whose names match a specified regular expression (dired-flag-files-regexp). Only the non-directory part of the file name is used in matching. You can use `^' and `$' to anchor matches. You can exclude subdirectories by hiding them (see section Hiding Subdirectories).

Visiting Files in Dired

There are several Dired commands for visiting or examining the files listed in the Dired buffer. All of them apply to the current line's file; if that file is really a directory, these commands invoke Dired on that subdirectory (making a separate Dired buffer).

f
Visit the file described on the current line, like typing C-x C-f and supplying that file name (dired-find-file). See section Visiting Files.
RET
Equivalent to f.
o
Like f, but uses another window to display the file's buffer (dired-find-file-other-window). The Dired buffer remains visible in the first window. This is like using C-x 4 C-f to visit the file. See section Multiple Windows.
C-o
Visit the file described on the current line, and display the buffer in another window, but do not select that window (dired-display-file).
Mouse-2
Visit the file named by the line you click on (dired-mouse-find-file-other-window). This uses another window to display the file, like the o command.
v
View the file described on the current line, using M-x view-file (dired-view-file). Viewing a file is like visiting it, but is slanted toward moving around in the file conveniently and does not allow changing the file. See section Miscellaneous File Operations.

Dired Marks vs. Flags

Instead of flagging a file with `D', you can mark the file with some other character (usually `*'). Most Dired commands to operate on files, aside from "expunge" (x), look for files marked with `*'.

Here are some commands for marking with `*', or for unmarking or operating on marks. (See section Deleting Files with Dired, for commands to flag and unflag files.)

m
* m
Mark the current file with `*' (dired-mark). With a numeric argument n, mark the next n files starting with the current file. (If n is negative, mark the previous -n files.)
* *
Mark all executable files with `*' (dired-mark-executables). With a numeric argument, unmark all those files.
* @
Mark all symbolic links with `*' (dired-mark-symlinks). With a numeric argument, unmark all those files.
* /
Mark with `*' all files which are actually directories, except for `.' and `..' (dired-mark-directories). With a numeric argument, unmark all those files.
* s
Mark all the files in the current subdirectory, aside from `.' and `..' (dired-mark-subdir-files).
u
* u
Remove any mark on this line (dired-unmark).
DEL
* DEL
Move point to previous line and remove any mark on that line (dired-unmark-backward).
* !
Remove all marks from all the files in this Dired buffer (dired-unmark-all-files-no-query).
* ? markchar
Remove all marks that use the character markchar (dired-unmark-all-files). The argument is a single character--do not use RET to terminate it. With a numeric argument, this command queries about each marked file, asking whether to remove its mark. You can answer y meaning yes, n meaning no, or ! to remove the marks from the remaining files without asking about them.
* C-n
Move down to the next marked file (dired-next-marked-file) A file is "marked" if it has any kind of mark.
* C-p
Move up to the previous marked file (dired-prev-marked-file)
* t
Toggle all marks (dired-do-toggle): files marked with `*' become unmarked, and unmarked files are marked with `*'. Files marked in any other way are not affected.
* c old new
Replace all marks that use the character old with marks that use the character new (dired-change-marks). This command is the primary way to create or use marks other than `*' or `D'. The arguments are single characters--do not use RET to terminate them. You can use almost any character as a mark character by means of this command, to distinguish various classes of files. If old is a space (` '), then the command operates on all unmarked files; if new is a space, then the command unmarks the files it acts on. To illustrate the power of this command, here is how to put `D' flags on all the files that have no marks, while unflagging all those that already have `D' flags:
* c D t  * c SPC D  * c t SPC
This assumes that no files are marked with `t'.
% m regexp RET
* % regexp RET
Mark (with `*') all files whose names match the regular expression regexp (dired-mark-files-regexp). This command is like % d, except that it marks files with `*' instead of flagging with `D'. See section Flagging Many Files at Once. Only the non-directory part of the file name is used in matching. Use `^' and `$' to anchor matches. Exclude subdirectories by hiding them (see section Hiding Subdirectories).
% g regexp RET
Mark (with `*') all files whose contents contain a match for the regular expression regexp (dired-mark-files-containing-regexp). This command is like % m, except that it searches the file contents instead of the file name.
C-_
Undo changes in the Dired buffer, such as adding or removing marks (dired-undo).

Operating on Files

This section describes the basic Dired commands to operate on one file or several files. All of these commands are capital letters; all of them use the minibuffer, either to read an argument or to ask for confirmation, before they act. All of them give you several ways to specify which files to manipulate:

  • If you give the command a numeric prefix argument n, it operates on the next n files, starting with the current file. (If n is negative, the command operates on the -n files preceding the current line.)
  • Otherwise, if some files are marked with `*', the command operates on all those files.
  • Otherwise, the command operates on the current file only.

Here are the file-manipulating commands that operate on files in this way. (Some other Dired commands, such as ! and the `%' commands, also use these conventions to decide which files to work on.)

C new RET
Copy the specified files (dired-do-copy). The argument new is the directory to copy into, or (if copying a single file) the new name. If dired-copy-preserve-time is non-nil, then copying with this command sets the modification time of the new file to be the same as that of the old file.
D
Delete the specified files (dired-do-delete). Like the other commands in this section, this command operates on the marked files, or the next n files. By contrast, x (dired-expunge) deletes all flagged files.
R new RET
Rename the specified files (dired-do-rename). The argument new is the directory to rename into, or (if renaming a single file) the new name. Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names.
H new RET
Make hard links to the specified files (dired-do-hardlink). The argument new is the directory to make the links in, or (if making just one link) the name to give the link.
S new RET
Make symbolic links to the specified files (dired-do-symlink). The argument new is the directory to make the links in, or (if making just one link) the name to give the link.
M modespec RET
Change the mode (also called "permission bits") of the specified files (dired-do-chmod). This uses the chmod program, so modespec can be any argument that chmod can handle.
G newgroup RET
Change the group of the specified files to newgroup (dired-do-chgrp).
O newowner RET
Change the owner of the specified files to newowner (dired-do-chown). (On most systems, only the superuser can do this.) The variable dired-chown-program specifies the name of the program to use to do the work (different systems put chown in different places).
P command RET
Print the specified files (dired-do-print). You must specify the command to print them with, but the minibuffer starts out with a suitable guess made using the variables lpr-command and lpr-switches (the same variables that lpr-buffer uses; see section Hardcopy Output).
Z
Compress the specified files (dired-do-compress). If the file appears to be a compressed file already, it is uncompressed instead.
L
Load the specified Emacs Lisp files (dired-do-load). See section Libraries of Lisp Code for Emacs.
B
Byte compile the specified Emacs Lisp files (dired-do-byte-compile). See section `Byte Compilation' in The Emacs Lisp Reference Manual.
A regexp RET
Search all the specified files for the regular expression regexp (dired-do-search). This command is a variant of tags-search. The search stops at the first match it finds; use M-, to resume the search and find the next match. See section Searching and Replacing with Tags Tables.
Q from RET to RET
Perform query-replace-regexp on each of the specified files, replacing matches for from (a regular expression) with the string to (dired-do-query-replace). This command is a variant of tags-query-replace. If you exit the query replace loop, you can use M-, to resume the scan and replace more matches. See section Searching and Replacing with Tags Tables.

One special file-operation command is + (dired-create-directory). This command reads a directory name and creates the directory if it does not already exist.

Shell Commands in Dired

The dired command ! (dired-do-shell-command) reads a shell command string in the minibuffer and runs that shell command on all the specified files. You can specify the files to operate on in the usual ways for Dired commands (see section Operating on Files). There are two ways of applying a shell command to multiple files:

  • If you use `*' in the shell command, then it runs just once, with the list of file names substituted for the `*'. The order of file names is the order of appearance in the Dired buffer. Thus, ! tar cf foo.tar * RET runs tar on the entire list of file names, putting them into one tar file `foo.tar'.
  • If the command string doesn't contain `*', then it runs once for each file, with the file name added at the end. For example, ! uudecode RET runs uudecode on each file.

What if you want to run the shell command once for each file but with the file name inserted in the middle? Or if you want to use the file names in a more complicated fashion? Use a shell loop. For example, this shell command would run uuencode on each of the specified files, writing the output into a corresponding `.uu' file:

for file in *; do uuencode $file $file >$file.uu; done

The working directory for the shell command is the top-level directory of the Dired buffer.

The ! command does not attempt to update the Dired buffer to show new or modified files, because it doesn't really understand shell commands, and does not know what files the shell command changed. Use the g command to update the Dired buffer (see section Updating the Dired Buffer).

Transforming File Names in Dired

Here are commands that alter file names in a systematic way:

% u
Rename each of the selected files to an upper-case name (dired-upcase). If the old file names are `Foo' and `bar', the new names are `FOO' and `BAR'.
% l
Rename each of the selected files to a lower-case name (dired-downcase). If the old file names are `Foo' and `bar', the new names are `foo' and `bar'.
% R from RET to RET
% C from RET to RET
% H from RET to RET
% S from RET to RET
These four commands rename, copy, make hard links and make soft links, in each case computing the new name by regular-expression substitution from the name of the old file.

The four regular-expression substitution commands effectively perform a search-and-replace on the selected file names in the Dired buffer. They read two arguments: a regular expression from, and a substitution pattern to.

The commands match each "old" file name against the regular expression from, and then replace the matching part with to. You can use `\&' and `\digit' in to to refer to all or part of what the pattern matched in the old file name, as in replace-regexp (see section Regexp Replacement). If the regular expression matches more than once in a file name, only the first match is replaced.

For example, % R ^.*$ RET x-\& RET renames each selected file by prepending `x-' to its name. The inverse of this, removing `x-' from the front of each file name, is also possible: one method is % R ^x-\(.*\)$ RET \1 RET; another is % R ^x- RET RET. (Use `^' and `$' to anchor matches that should span the whole filename.)

Normally, the replacement process does not consider the files' directory names; it operates on the file name within the directory. If you specify a numeric argument of zero, then replacement affects the entire absolute file name including directory name.

Often you will want to select the set of files to operate on using the same regexp that you will use to operate on them. To do this, mark those files with % m regexp RET, then use the same regular expression in the command to operate on the files. To make this easier, the % commands to operate on files use the last regular expression specified in any % command as a default.

File Comparison with Dired

Here are two Dired commands that compare specified files using diff.

=
Compare the current file (the file at point) with another file (the file at the mark) using the diff program (dired-diff). The file at the mark is the first argument of diff, and the file at point is the second argument.
M-=
Compare the current file with its latest backup file (dired-backup-diff). If the current file is itself a backup, compare it with the file it is a backup of; this way, you can compare a file with any backup version of your choice. The backup file is the first file given to diff.

Subdirectories in Dired

A Dired buffer displays just one directory in the normal case; but you can optionally include its subdirectories as well.

The simplest way to include multiple directories in one Dired buffer is to specify the options `-lR' for running ls. (If you give a numeric argument when you run Dired, then you can specify these options in the minibuffer.) That produces a recursive directory listing showing all subdirectories at all levels.

But usually all the subdirectories are too many; usually you will prefer to include specific subdirectories only. You can do this with the i command:

i
Insert the contents of a subdirectory later in the buffer.

Use the i (dired-maybe-insert-subdir) command on a line that describes a file which is a directory. It inserts the contents of that directory into the same Dired buffer, and moves there. Inserted subdirectory contents follow the top-level directory of the Dired buffer, just as they do in `ls -lR' output.

If the subdirectory's contents are already present in the buffer, the i command just moves to it.

In either case, i sets the Emacs mark before moving, so C-u C-SPC takes you back to the old position in the buffer (the line describing that subdirectory).

Use the l command (dired-do-redisplay) to update the subdirectory's contents. Use k to delete the subdirectory. See section Updating the Dired Buffer.

Moving Over Subdirectories

When a Dired buffer lists subdirectories, you can use the page motion commands C-x [ and C-x ] to move by entire directories.

The following commands move across, up and down in the tree of directories within one Dired buffer. They move to directory header lines, which are the lines that give a directory's name, at the beginning of the directory's contents.

C-M-n
Go to next subdirectory header line, regardless of level (dired-next-subdir).
C-M-p
Go to previous subdirectory header line, regardless of level (dired-prev-subdir).
C-M-u
Go up to the parent directory's header line (dired-tree-up).
C-M-d
Go down in the directory tree, to the first subdirectory's header line (dired-tree-down).
<
Move up to the previous directory-file line (dired-prev-dirline). These lines are the ones that describe a directory as a file in its parent directory.
>
Move down to the next directory-file line (dired-prev-dirline).

Hiding Subdirectories

Hiding a subdirectory means to make it invisible, except for its header line, via selective display (see section Selective Display).

$
Hide or reveal the subdirectory that point is in, and move point to the next subdirectory (dired-hide-subdir). A numeric argument serves as a repeat count.
M-$
Hide all subdirectories in this Dired buffer, leaving only their header lines (dired-hide-all). Or, if any subdirectory is currently hidden, make all subdirectories visible again. You can use this command to get an overview in very deep directory trees or to move quickly to subdirectories far away.

Ordinary Dired commands never consider files inside a hidden subdirectory. For example, the commands to operate on marked files ignore files in hidden directories even if they are marked. Thus you can use hiding to temporarily exclude subdirectories from operations without having to remove the markers.

The subdirectory hiding commands toggle; that is, they hide what was visible, and show what was hidden.

Updating the Dired Buffer

This section describes commands to update the Dired buffer to reflect outside (non-Dired) changes in the directories and files, and to delete part of the Dired buffer.

g
Update the entire contents of the Dired buffer (revert-buffer).
l
Update the specified files (dired-do-redisplay).
k
Delete the specified file lines---not the files, just the lines (dired-do-kill-lines).
s
Toggle between alphabetical order and date/time order (dired-sort-toggle-or-edit).
C-u s switches RET
Refresh the Dired buffer using switches as dired-listing-switches.

Type g (revert-buffer) to update the contents of the Dired buffer, based on changes in the files and directories listed. This preserves all marks except for those on files that have vanished. Hidden subdirectories are updated but remain hidden.

To update only some of the files, type l (dired-do-redisplay). This command applies to the next n files, or to the marked files if any, or to the current file. Updating them means reading their current status from the file system and changing the buffer to reflect it properly.

If you use l on a subdirectory header line, it updates the contents of the corresponding subdirectory.

To delete the specified file lines---not the files, just the lines--type k (dired-do-kill-lines). With a numeric argument n, this command applies to the next n files; otherwise, it applies to the marked files.

If you kill the line for a file that is a directory, the directory's contents are also deleted from the buffer. Typing C-u k on the header line for a subdirectory is another way to delete a subdirectory from the Dired buffer.

The g command brings back any individual lines that you have killed in this way, but not subdirectories--you must use i to reinsert each subdirectory.

The files in a Dired buffers are normally listed in alphabetical order by file names. Alternatively Dired can sort them by date/time. The Dired command s (dired-sort-toggle-or-edit) switches between these two sorting modes. The mode line in a Dired buffer indicates which way it is currently sorted--by name, or by date.

C-u s switches RET lets you specify a new value for dired-listing-switches.

Dired and find

You can select a set of files for display in a Dired buffer more flexibly by using the find utility to choose the files.

To search for files with names matching a wildcard pattern use M-x find-name-dired. It reads arguments directory and pattern, and chooses all the files in directory or its subdirectories whose individual names match pattern.

The files thus chosen are displayed in a Dired buffer in which the ordinary Dired commands are available.

If you want to test the contents of files, rather than their names, use M-x find-grep-dired. This command reads two minibuffer arguments, directory and regexp; it chooses all the files in directory or its subdirectories that contain a match for regexp. It works by running the programs find and grep. See also M-x grep-find, in section Running Compilations under Emacs. Remember to write the regular expression for grep, not for Emacs.

The most general command in this series is M-x find-dired, which lets you specify any condition that find can test. It takes two minibuffer arguments, directory and find-args; it runs find in directory, passing find-args to tell find what condition to test. To use this command, you need to know how to use find.

The format of listing produced by these commands is controlled by the variable find-ls-option, whose default value specifies using options `-ld' for ls. If your listings are corrupted, you may need to change the value of this variable.

The Calendar and the Diary

Emacs provides the functions of a desk calendar, with a diary of planned or past events. To enter the calendar, type M-x calendar; this displays a three-month calendar centered on the current month, with point on the current date. With a numeric argument, as in C-u M-x calendar, it prompts you for the month and year to be the center of the three-month calendar. The calendar uses its own buffer, whose major mode is Calendar mode.

Mouse-2 in the calendar brings up a menu of operations on a particular date; C-Mouse-3 brings up a menu of commonly used calendar features that are independent of any particular date. To exit the calendar, type q. See section `Calendar' in The Emacs Lisp Reference Manual, for customization information about the calendar and diary.

Movement in the Calendar

Calendar mode lets you move through the calendar in logical units of time such as days, weeks, months, and years. If you move outside the three months originally displayed, the calendar display "scrolls" automatically through time to make the selected date visible. Moving to a date lets you view its holidays or diary entries, or convert it to other calendars; moving longer time periods is also useful simply to scroll the calendar.

Motion by Standard Lengths of Time

The commands for movement in the calendar buffer parallel the commands for movement in text. You can move forward and backward by days, weeks, months, and years.

C-f
Move point one day forward (calendar-forward-day).
C-b
Move point one day backward (calendar-backward-day).
C-n
Move point one week forward (calendar-forward-week).
C-p
Move point one week backward (calendar-backward-week).
M-}
Move point one month forward (calendar-forward-month).
M-{
Move point one month backward (calendar-backward-month).
C-x ]
Move point one year forward (calendar-forward-year).
C-x [
Move point one year backward (calendar-backward-year).

The day and week commands are natural analogues of the usual Emacs commands for moving by characters and by lines. Just as C-n usually moves to the same column in the following line, in Calendar mode it moves to the same day in the following week. And C-p moves to the same day in the previous week.

The arrow keys are equivalent to C-f, C-b, C-n and C-p, just as they normally are in other modes.

The commands for motion by months and years work like those for weeks, but move a larger distance. The month commands M-} and M-{ move forward or backward by an entire month's time. The year commands C-x ] and C-x [ move forward or backward a whole year.

The easiest way to remember these commands is to consider months and years analogous to paragraphs and pages of text, respectively. But the commands themselves are not quite analogous. The ordinary Emacs paragraph commands move to the beginning or end of a paragraph, whereas these month and year commands move by an entire month or an entire year, which usually involves skipping across the end of a month or year.

All these commands accept a numeric argument as a repeat count. For convenience, the digit keys and the minus sign specify numeric arguments in Calendar mode even without the Meta modifier. For example, 100 C-f moves point 100 days forward from its present location.

Beginning or End of Week, Month or Year

A week (or month, or year) is not just a quantity of days; we think of weeks (months, years) as starting on particular dates. So Calendar mode provides commands to move to the beginning or end of a week, month or year:

C-a
Move point to start of week (calendar-beginning-of-week).
C-e
Move point to end of week (calendar-end-of-week).
M-a
Move point to start of month (calendar-beginning-of-month).
M-e
Move point to end of month (calendar-end-of-month).
M-<
Move point to start of year (calendar-beginning-of-year).
M->
Move point to end of year (calendar-end-of-year).

These commands also take numeric arguments as repeat counts, with the repeat count indicating how many weeks, months, or years to move backward or forward.

By default, weeks begin on Sunday. To make them begin on Monday instead, set the variable calendar-week-start-day to 1.

Specified Dates

Calendar mode provides commands for moving to a particular date specified in various ways.

g d
Move point to specified date (calendar-goto-date).
o
Center calendar around specified month (calendar-other-month).
.
Move point to today's date (calendar-goto-today).

g d (calendar-goto-date) prompts for a year, a month, and a day of the month, and then moves to that date. Because the calendar includes all dates from the beginning of the current era, you must type the year in its entirety; that is, type `1990', not `90'.

o (calendar-other-month) prompts for a month and year, then centers the three-month calendar around that month.

You can return to today's date with . (calendar-goto-today).

Scrolling in the Calendar

The calendar display scrolls automatically through time when you move out of the visible portion. You can also scroll it manually. Imagine that the calendar window contains a long strip of paper with the months on it. Scrolling it means moving the strip so that new months become visible in the window.

C-x <
Scroll calendar one month forward (scroll-calendar-left).
C-x >
Scroll calendar one month backward (scroll-calendar-right).
C-v
NEXT
Scroll calendar three months forward (scroll-calendar-left-three-months).
M-v
PRIOR
Scroll calendar three months backward (scroll-calendar-right-three-months).

The most basic calendar scroll commands scroll by one month at a time. This means that there are two months of overlap between the display before the command and the display after. C-x < scrolls the calendar contents one month to the left; that is, it moves the display forward in time. C-x > scrolls the contents to the right, which moves backwards in time.

The commands C-v and M-v scroll the calendar by an entire "screenful"---three months--in analogy with the usual meaning of these commands. C-v makes later dates visible and M-v makes earlier dates visible. These commands take a numeric argument as a repeat count; in particular, since C-u multiplies the next command by four, typing C-u C-v scrolls the calendar forward by a year and typing C-u M-v scrolls the calendar backward by a year.

The function keys NEXT and PRIOR are equivalent to C-v and M-v, just as they are in other modes.

Counting Days

M-=
Display the number of days in the current region (calendar-count-days-region).

To determine the number of days in the region, type M-= (calendar-count-days-region). The numbers of days printed is inclusive; that is, it includes the days specified by mark and point.

Miscellaneous Calendar Commands

p d
Display day-in-year (calendar-print-day-of-year).
C-c C-l
Regenerate the calendar window (redraw-calendar).
SPC
Scroll the next window (scroll-other-window).
q
Exit from calendar (exit-calendar).

To print the number of days elapsed since the start of the year, or the number of days remaining in the year, type the p d command (calendar-print-day-of-year). This displays both of those numbers in the echo area. The number of days elapsed includes the selected date. The number of days remaining does not include that date.

If the calendar window text gets corrupted, type C-c C-l (redraw-calendar) to redraw it. (This can only happen if you use non-Calendar-mode editing commands.)

In Calendar mode, you can use SPC (scroll-other-window) to scroll the other window. This is handy when you display a list of holidays or diary entries in another window.

To exit from the calendar, type q (exit-calendar). This buries all buffers related to the calendar, selecting other buffers. (If a frame contains a dedicated calendar window, exiting from the calendar iconifies that frame.)

LaTeX Calendar

The Calendar LaTeX commands produce a buffer of LaTeX code that prints as a calendar. Depending on the command you use, the printed calendar covers the day, week, month or year that point is in.

t m
Generate a one-month calendar (cal-tex-cursor-month).
t M
Generate a sideways-printing one-month calendar (cal-tex-cursor-month-landscape).
t d
Generate a one-day calendar (cal-tex-cursor-day).
t w 1
Generate a one-page calendar for one week (cal-tex-cursor-week).
t w 2
Generate a two-page calendar for one week (cal-tex-cursor-week2).
t w 3
Generate an ISO-style calendar for one week (cal-tex-cursor-week-iso).
t w 4
Generate a calendar for one Monday-starting week (cal-tex-cursor-week-monday).
t f w
Generate a Filofax-style two-weeks-at-a-glance calendar (cal-tex-cursor-filofax-2week).
t f W
Generate a Filofax-style one-week-at-a-glance calendar (cal-tex-cursor-filofax-week).
t y
Generate a calendar for one year (cal-tex-cursor-year).
t Y
Generate a sideways-printing calendar for one year (cal-tex-cursor-year-landscape).
t f y
Generate a Filofax-style calendar for one year (cal-tex-cursor-filofax-year).

Some of these commands print the calendar sideways (in "landscape mode"), so it can be wider than it is long. Some of them use Filofax paper size (3.75in x 6.75in). All of these commands accept a prefix argument which specifies how many days, weeks, months or years to print (starting always with the selected one).

If the variable cal-tex-holidays is non-nil (the default), then the printed calendars show the holidays in calendar-holidays. If the variable cal-tex-diary is non-nil (the default is nil), diary entries are included also (in weekly and monthly calendars only).

Holidays

The Emacs calendar knows about all major and many minor holidays, and can display them.

h
Display holidays for the selected date (calendar-cursor-holidays).
Mouse-2 Holidays
Display any holidays for the date you click on.
x
Mark holidays in the calendar window (mark-calendar-holidays).
u
Unmark calendar window (calendar-unmark).
a
List all holidays for the displayed three months in another window (list-calendar-holidays).
M-x holidays
List all holidays for three months around today's date in another window.
M-x list-holidays
List holidays in another window for a specified range of years.

To see if any holidays fall on a given date, position point on that date in the calendar window and use the h command. Alternatively, click on that date with Mouse-2 and then choose Holidays from the menu that appears. Either way, this displays the holidays for that date, in the echo area if they fit there, otherwise in a separate window.

To view the distribution of holidays for all the dates shown in the calendar, use the x command. This displays the dates that are holidays in a different face (or places a `*' after these dates, if display with multiple faces is not available). The command applies both to the currently visible months and to other months that subsequently become visible by scrolling. To turn marking off and erase the current marks, type u, which also erases any diary marks (see section The Diary).

To get even more detailed information, use the a command, which displays a separate buffer containing a list of all holidays in the current three-month range. You can use SPC in the calendar window to scroll that list.

The command M-x holidays displays the list of holidays for the current month and the preceding and succeeding months; this works even if you don't have a calendar window. If you want the list of holidays centered around a different month, use C-u M-x holidays, which prompts for the month and year.

The holidays known to Emacs include United States holidays and the major Christian, Jewish, and Islamic holidays; also the solstices and equinoxes.

The command M-x list-holidays displays the list of holidays for a range of years. This function asks you for the starting and stopping years, and allows you to choose all the holidays or one of several categories of holidays. You can use this command even if you don't have a calendar window.

The dates used by Emacs for holidays are based on current practice, not historical fact. Historically, for instance, the start of daylight savings time and even its existence have varied from year to year, but present United States law mandates that daylight savings time begins on the first Sunday in April. When the daylight savings rules are set up for the United States, Emacs always uses the present definition, even though it is wrong for some prior years.

Times of Sunrise and Sunset

Special calendar commands can tell you, to within a minute or two, the times of sunrise and sunset for any date.

S
Display times of sunrise and sunset for the selected date (calendar-sunrise-sunset).
Mouse-2 Sunrise/Sunset
Display times of sunrise and sunset for the date you click on.
M-x sunrise-sunset
Display times of sunrise and sunset for today's date.
C-u M-x sunrise-sunset
Display times of sunrise and sunset for a specified date.

Within the calendar, to display the local times of sunrise and sunset in the echo area, move point to the date you want, and type S. Alternatively, click Mouse-2 on the date, then choose Sunrise/Sunset from the menu that appears. The command M-x sunrise-sunset is available outside the calendar to display this information for today's date or a specified date. To specify a date other than today, use C-u M-x sunrise-sunset, which prompts for the year, month, and day.

You can display the times of sunrise and sunset for any location and any date with C-u C-u M-x sunrise-sunset. This asks you for a longitude, latitude, number of minutes difference from Coordinated Universal Time, and date, and then tells you the times of sunrise and sunset for that location on that date.

Because the times of sunrise and sunset depend on the location on earth, you need to tell Emacs your latitude, longitude, and location name before using these commands. Here is an example of what to set:

(setq calendar-latitude 40.1)
(setq calendar-longitude -88.2)
(setq calendar-location-name "Urbana, IL")

Use one decimal place in the values of calendar-latitude and calendar-longitude.

Your time zone also affects the local time of sunrise and sunset. Emacs usually gets time zone information from the operating system, but if these values are not what you want (or if the operating system does not supply them), you must set them yourself. Here is an example:

(setq calendar-time-zone -360)
(setq calendar-standard-time-zone-name "CST")
(setq calendar-daylight-time-zone-name "CDT")

The value of calendar-time-zone is the number of minutes difference between your local standard time and Coordinated Universal Time (Greenwich time). The values of calendar-standard-time-zone-name and calendar-daylight-time-zone-name are the abbreviations used in your time zone. Emacs displays the times of sunrise and sunset corrected for daylight savings time. See section Daylight Savings Time, for how daylight savings time is determined.

As a user, you might find it convenient to set the calendar location variables for your usual physical location in your `.emacs' file. And when you install Emacs on a machine, you can create a `default.el' file which sets them properly for the typical location of most users of that machine. See section The Init File, `~/.emacs'.

Phases of the Moon

These calendar commands display the dates and times of the phases of the moon (new moon, first quarter, full moon, last quarter). This feature is useful for debugging problems that "depend on the phase of the moon."

M
Display the dates and times for all the quarters of the moon for the three-month period shown (calendar-phases-of-moon).
M-x phases-of-moon
Display dates and times of the quarters of the moon for three months around today's date.

Within the calendar, use the M command to display a separate buffer of the phases of the moon for the current three-month range. The dates and times listed are accurate to within a few minutes.

Outside the calendar, use the command M-x phases-of-moon to display the list of the phases of the moon for the current month and the preceding and succeeding months. For information about a different month, use C-u M-x phases-of-moon, which prompts for the month and year.

The dates and times given for the phases of the moon are given in local time (corrected for daylight savings, when appropriate); but if the variable calendar-time-zone is void, Coordinated Universal Time (the Greenwich time zone) is used. See section Daylight Savings Time.

Conversion To and From Other Calendars

The Emacs calendar displayed is always the Gregorian calendar, sometimes called the "new style" calendar, which is used in most of the world today. However, this calendar did not exist before the sixteenth century and was not widely used before the eighteenth century; it did not fully displace the Julian calendar and gain universal acceptance until the early twentieth century. The Emacs calendar can display any month since January, year 1 of the current era, but the calendar displayed is the Gregorian, even for a date at which the Gregorian calendar did not exist.

While Emacs cannot display other calendars, it can convert dates to and from several other calendars.

Supported Calendar Systems

The ISO commercial calendar is used largely in Europe.

The Julian calendar, named after Julius Caesar, was the one used in Europe throughout medieval times, and in many countries up until the nineteenth century.

Astronomers use a simple counting of days elapsed since noon, Monday, January 1, 4713 B.C. on the Julian calendar. The number of days elapsed is called the Julian day number or the Astronomical day number.

The Hebrew calendar is used by tradition in the Jewish religion. The Emacs calendar program uses the Hebrew calendar to determine the dates of Jewish holidays. Hebrew calendar dates begin and end at sunset.

The Islamic calendar is used in many predominantly Islamic countries. Emacs uses it to determine the dates of Islamic holidays. There is no universal agreement in the Islamic world about the calendar; Emacs uses a widely accepted version, but the precise dates of Islamic holidays often depend on proclamation by religious authorities, not on calculations. As a consequence, the actual dates of observance can vary slightly from the dates computed by Emacs. Islamic calendar dates begin and end at sunset.

The French Revolutionary calendar was created by the Jacobins after the 1789 revolution, to represent a more secular and nature-based view of the annual cycle, and to install a 10-day week in a rationalization measure similar to the metric system. The French government officially abandoned this calendar at the end of 1805.

The Maya of Central America used three separate, overlapping calendar systems, the long count, the tzolkin, and the haab. Emacs knows about all three of these calendars. Experts dispute the exact correlation between the Mayan calendar and our calendar; Emacs uses the Goodman-Martinez-Thompson correlation in its calculations.

The Copts use a calendar based on the ancient Egyptian solar calendar. Their calendar consists of twelve 30-day months followed by an extra five-day period. Once every fourth year they add a leap day to this extra period to make it six days. The Ethiopic calendar is identical in structure, but has different year numbers and month names.

The Persians use a solar calendar based on a design of Omar Khayyam. Their calendar consists of twelve months of which the first six have 31 days, the next five have 30 days, and the last has 29 in ordinary years and 30 in leap years. Leap years occur in a complicated pattern every four or five years.

The Chinese calendar is a complicated system of lunar months arranged into solar years. The years go in cycles of sixty, each year containing either twelve months in an ordinary year or thirteen months in a leap year; each month has either 29 or 30 days. Years, ordinary months, and days are named by combining one of ten "celestial stems" with one of twelve "terrestrial branches" for a total of sixty names that are repeated in a cycle of sixty.

Converting To Other Calendars

The following commands describe the selected date (the date at point) in various other calendar systems:

Mouse-2 Other Calendars
Display the date that you click on, expressed in various other calendars.
p c
Display ISO commercial calendar equivalent for selected day (calendar-print-iso-date).
p j
Display Julian date for selected day (calendar-print-julian-date).
p a
Display astronomical (Julian) day number for selected day (calendar-print-astro-day-number).
p h
Display Hebrew date for selected day (calendar-print-hebrew-date).
p i
Display Islamic date for selected day (calendar-print-islamic-date).
p f
Display French Revolutionary date for selected day (calendar-print-french-date).
p C
Display Chinese date for selected day (calendar-print-chinese-date).
p k
Display Coptic date for selected day (calendar-print-coptic-date).
p e
Display Ethiopic date for selected day (calendar-print-ethiopic-date).
p p
Display Persian date for selected day (calendar-print-persian-date).
p m
Display Mayan date for selected day (calendar-print-mayan-date).

If you are using X, the easiest way to translate a date into other calendars is to click on it with Mouse-2, then choose Other Calendars from the menu that appears. This displays the equivalent forms of the date in all the calendars Emacs understands, in the form of a menu. (Choosing an alternative from this menu doesn't actually do anything--the menu is used only for display.)

Put point on the desired date of the Gregorian calendar, then type the appropriate keys. The p is a mnemonic for "print" since Emacs "prints" the equivalent date in the echo area.

Converting From Other Calendars

You can use the other supported calendars to specify a date to move to. This section describes the commands for doing this using calendars other than Mayan; for the Mayan calendar, see the following section.

g c
Move to a date specified in the ISO commercial calendar (calendar-goto-iso-date).
g j
Move to a date specified in the Julian calendar (calendar-goto-julian-date).
g a
Move to a date specified in astronomical (Julian) day number (calendar-goto-astro-day-number).
g h
Move to a date specified in the Hebrew calendar (calendar-goto-hebrew-date).
g i
Move to a date specified in the Islamic calendar (calendar-goto-islamic-date).
g f
Move to a date specified in the French Revolutionary calendar (calendar-goto-french-date).
g C
Move to a date specified in the Chinese calendar (calendar-goto-chinese-date).
g p
Move to a date specified in the Persian calendar (calendar-goto-persian-date).
g k
Move to a date specified in the Coptic calendar (calendar-goto-coptic-date).
g e
Move to a date specified in the Ethiopic calendar (calendar-goto-ethiopic-date).

These commands ask you for a date on the other calendar, move point to the Gregorian calendar date equivalent to that date, and display the other calendar's date in the echo area. Emacs uses strict completion (see section Completion) whenever it asks you to type a month name, so you don't have to worry about the spelling of Hebrew, Islamic, or French names.

One common question concerning the Hebrew calendar is the computation of the anniversary of a date of death, called a "yahrzeit." The Emacs calendar includes a facility for such calculations. If you are in the calendar, the command M-x list-yahrzeit-dates asks you for a range of years and then displays a list of the yahrzeit dates for those years for the date given by point. If you are not in the calendar, this command first asks you for the date of death and the range of years, and then displays the list of yahrzeit dates.

Converting from the Mayan Calendar

Here are the commands to select dates based on the Mayan calendar:

g m l
Move to a date specified by the long count calendar (calendar-goto-mayan-long-count-date).
g m n t
Move to the next occurrence of a place in the tzolkin calendar (calendar-next-tzolkin-date).
g m p t
Move to the previous occurrence of a place in the tzolkin calendar (calendar-previous-tzolkin-date).
g m n h
Move to the next occurrence of a place in the haab calendar (calendar-next-haab-date).
g m p h
Move to the previous occurrence of a place in the haab calendar (calendar-previous-haab-date).
g m n c
Move to the next occurrence of a place in the calendar round (calendar-next-calendar-round-date).
g m p c
Move to the previous occurrence of a place in the calendar round (calendar-previous-calendar-round-date).

To understand these commands, you need to understand the Mayan calendars. The long count is a counting of days with these units:

1 kin = 1 day   1 uinal = 20 kin   1 tun = 18 uinal
1 katun = 20 tun   1 baktun = 20 katun

Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long count dates as early as 7.17.18.13.1, but no earlier. When you use the g m l command, type the Mayan long count date with the baktun, katun, tun, uinal, and kin separated by periods.

The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of independent cycles of 13 and 20 days. Since this cycle repeats endlessly, Emacs provides commands to move backward and forward to the previous or next point in the cycle. Type g m p t to go to the previous tzolkin date; Emacs asks you for a tzolkin date and moves point to the previous occurrence of that date. Similarly, type g m n t to go to the next occurrence of a tzolkin date.

The Mayan haab calendar is a cycle of 365 days arranged as 18 months of 20 days each, followed a 5-day monthless period. Like the tzolkin cycle, this cycle repeats endlessly, and there are commands to move backward and forward to the previous or next point in the cycle. Type g m p h to go to the previous haab date; Emacs asks you for a haab date and moves point to the previous occurrence of that date. Similarly, type g m n h to go to the next occurrence of a haab date.

The Maya also used the combination of the tzolkin date and the haab date. This combination is a cycle of about 52 years called a calendar round. If you type g m p c, Emacs asks you for both a haab and a tzolkin date and then moves point to the previous occurrence of that combination. Use g m n c to move point to the next occurrence of a combination. These commands signal an error if the haab/tzolkin date combination you have typed is impossible.

Emacs uses strict completion (see section Strict Completion) whenever it asks you to type a Mayan name, so you don't have to worry about spelling.

The Diary

The Emacs diary keeps track of appointments or other events on a daily basis, in conjunction with the calendar. To use the diary feature, you must first create a diary file containing a list of events and their dates. Then Emacs can automatically pick out and display the events for today, for the immediate future, or for any specified date.

By default, Emacs uses `~/diary' as the diary file. This is the same file that the calendar utility uses. A sample `~/diary' file is:

12/22/1988  Twentieth wedding anniversary!!
&1/1.       Happy New Year!
10/22       Ruth's birthday.
* 21, *:    Payday
Tuesday--weekly meeting with grad students at 10am
         Supowit, Shen, Bitner, and Kapoor to attend.
1/13/89     Friday the thirteenth!!
&thu 4pm    squash game with Lloyd.
mar 16      Dad's birthday
April 15, 1989 Income tax due.
&* 15       time cards due.

This example uses extra spaces to align the event descriptions of most of the entries. Such formatting is purely a matter of taste.

Although you probably will start by creating a diary manually, Emacs provides a number of commands to let you view, add, and change diary entries.

Commands Displaying Diary Entries

Once you have created a `~/diary' file, you can use the calendar to view it. You can also view today's events outside of Calendar mode.

d
Display all diary entries for the selected date (view-diary-entries).
Mouse-2 Diary
Display all diary entries for the date you click on.
s
Display the entire diary file (show-all-diary-entries).
m
Mark all visible dates that have diary entries (mark-diary-entries).
u
Unmark the calendar window (calendar-unmark).
M-x print-diary-entries
Print hard copy of the diary display as it appears.
M-x diary
Display all diary entries for today's date.
M-x diary-mail-entries
Mail yourself email reminders about upcoming diary entries.

Displaying the diary entries with d shows in a separate window the diary entries for the selected date in the calendar. The mode line of the new window shows the date of the diary entries and any holidays that fall on that date. If you specify a numeric argument with d, it shows all the diary entries for that many successive days. Thus, 2 d displays all the entries for the selected date and for the following day.

Another way to display the diary entries for a date is to click Mouse-2 on the date, and then choose Diary from the menu that appears.

To get a broader view of which days are mentioned in the diary, use the m command. This displays the dates that have diary entries in a different face (or places a `+' after these dates, if display with multiple faces is not available). The command applies both to the currently visible months and to other months that subsequently become visible by scrolling. To turn marking off and erase the current marks, type u, which also turns off holiday marks (see section Holidays).

To see the full diary file, rather than just some of the entries, use the s command.

Display of selected diary entries uses the selective display feature to hide entries that don't apply.

The diary buffer as you see it is an illusion, so simply printing the buffer does not print what you see on your screen. There is a special command to print hard copy of the diary buffer as it appears; this command is M-x print-diary-entries. It sends the data directly to the printer. You can customize it like lpr-region (see section Hardcopy Output).

The command M-x diary displays the diary entries for the current date, independently of the calendar display, and optionally for the next few days as well; the variable number-of-diary-entries specifies how many days to include. See section `Calendar' in The Emacs Lisp Reference Manual.

If you put (diary) in your `.emacs' file, this automatically displays a window with the day's diary entries, when you enter Emacs. The mode line of the displayed window shows the date and any holidays that fall on that date.

Many users like to receive notice of events in their diary as email. To send such mail to yourself, use the command M-x diary-mail-entries. A prefix argument specifies how many days (starting with today) to check; otherwise, the variable diary-mail-days says how many days.

The Diary File

Your diary file is a file that records events associated with particular dates. The name of the diary file is specified by the variable diary-file; `~/diary' is the default. The calendar utility program supports a subset of the format allowed by the Emacs diary facilities, so you can use that utility to view the diary file, with reasonable results aside from the entries it cannot understand.

Each entry in the diary file describes one event and consists of one or more lines. An entry always begins with a date specification at the left margin. The rest of the entry is simply text to describe the event. If the entry has more than one line, then the lines after the first must begin with whitespace to indicate they continue a previous entry. Lines that do not begin with valid dates and do not continue a preceding entry are ignored.

You can inhibit the marking of certain diary entries in the calendar window; to do this, insert an ampersand (`&') at the beginning of the entry, before the date. This has no effect on display of the entry in the diary window; it affects only marks on dates in the calendar window. Nonmarking entries are especially useful for generic entries that would otherwise mark many different dates.

If the first line of a diary entry consists only of the date or day name with no following blanks or punctuation, then the diary window display doesn't include that line; only the continuation lines appear. For example, this entry:

02/11/1989
      Bill B. visits Princeton today
      2pm Cognitive Studies Committee meeting
      2:30-5:30 Liz at Lawrenceville
      4:00pm Dentist appt
      7:30pm Dinner at George's
      8:00-10:00pm concert

appears in the diary window without the date line at the beginning. This style of entry looks neater when you display just a single day's entries, but can cause confusion if you ask for more than one day's entries.

You can edit the diary entries as they appear in the window, but it is important to remember that the buffer displayed contains the entire diary file, with portions of it concealed from view. This means, for instance, that the C-f (forward-char) command can put point at what appears to be the end of the line, but what is in reality the middle of some concealed line.

Be careful when editing the diary entries! Inserting additional lines or adding/deleting characters in the middle of a visible line cannot cause problems, but editing at the end of a line may not do what you expect. Deleting a line may delete other invisible entries that follow it. Before editing the diary, it is best to display the entire file with s (show-all-diary-entries).

Date Formats

Here are some sample diary entries, illustrating different ways of formatting a date. The examples all show dates in American order (month, day, year), but Calendar mode supports European order (day, month, year) as an option.

4/20/93  Switch-over to new tabulation system
apr. 25  Start tabulating annual results
4/30  Results for April are due
*/25  Monthly cycle finishes
Friday  Don't leave without backing up files

The first entry appears only once, on April 20, 1993. The second and third appear every year on the specified dates, and the fourth uses a wildcard (asterisk) for the month, so it appears on the 25th of every month. The final entry appears every week on Friday.

You can use just numbers to express a date, as in `month/day' or `month/day/year'. This must be followed by a nondigit. In the date itself, month and day are numbers of one or two digits. The optional year is also a number, and may be abbreviated to the last two digits; that is, you can use `11/12/1989' or `11/12/89'.

Dates can also have the form `monthname day' or `monthname day, year', where the month's name can be spelled in full or abbreviated to three characters (with or without a period). Case is not significant.

A date may be generic; that is, partially unspecified. Then the entry applies to all dates that match the specification. If the date does not contain a year, it is generic and applies to any year. Alternatively, month, day, or year can be a `*'; this matches any month, day, or year, respectively. Thus, a diary entry `3/*/*' matches any day in March of any year; so does `march *'.

If you prefer the European style of writing dates--in which the day comes before the month--type M-x european-calendar while in the calendar, or set the variable european-calendar-style to t before using any calendar or diary command. This mode interprets all dates in the diary in the European manner, and also uses European style for displaying diary dates. (Note that there is no comma after the monthname in the European style.) To go back to the (default) American style of writing dates, type M-x american-calendar.

You can use the name of a day of the week as a generic date which applies to any date falling on that day of the week. You can abbreviate the day of the week to three letters (with or without a period) or spell it in full; case is not significant.

Commands to Add to the Diary

While in the calendar, there are several commands to create diary entries:

i d
Add a diary entry for the selected date (insert-diary-entry).
i w
Add a diary entry for the selected day of the week (insert-weekly-diary-entry).
i m
Add a diary entry for the selected day of the month (insert-monthly-diary-entry).
i y
Add a diary entry for the selected day of the year (insert-yearly-diary-entry).

You can make a diary entry for a specific date by selecting that date in the calendar window and typing the i d command. This command displays the end of your diary file in another window and inserts the date; you can then type the rest of the diary entry.

If you want to make a diary entry that applies to a specific day of the week, select that day of the week (any occurrence will do) and type i w. This inserts the day-of-week as a generic date; you can then type the rest of the diary entry. You can make a monthly diary entry in the same fashion. Select the day of the month, use the i m command, and type rest of the entry. Similarly, you can insert a yearly diary entry with the i y command.

All of the above commands make marking diary entries by default. To make a nonmarking diary entry, give a numeric argument to the command. For example, C-u i w makes a nonmarking weekly diary entry.

When you modify the diary file, be sure to save the file before exiting Emacs.

Special Diary Entries

In addition to entries based on calendar dates, the diary file can contain sexp entries for regular events such as anniversaries. These entries are based on Lisp expressions (sexps) that Emacs evaluates as it scans the diary file. Instead of a date, a sexp entry contains `%%' followed by a Lisp expression which must begin and end with parentheses. The Lisp expression determines which dates the entry applies to.

Calendar mode provides commands to insert certain commonly used sexp entries:

i a
Add an anniversary diary entry for the selected date (insert-anniversary-diary-entry).
i b
Add a block diary entry for the current region (insert-block-diary-entry).
i c
Add a cyclic diary entry starting at the date (insert-cyclic-diary-entry).

If you want to make a diary entry that applies to the anniversary of a specific date, move point to that date and use the i a command. This displays the end of your diary file in another window and inserts the anniversary description; you can then type the rest of the diary entry. The entry looks like this:

%%(diary-anniversary 10 31 1948) Arthur's birthday

This entry applies to October 31 in any year after 1948; `10 31 1948' specifies the date. (If you are using the European calendar style, the month and day are interchanged.) The reason this expression requires a beginning year is that advanced diary functions can use it to calculate the number of elapsed years.

A block diary entry applies to a specified range of consecutive dates. Here is a block diary entry that applies to all dates from June 24, 1990 through July 10, 1990:

%%(diary-block 6 24 1990 7 10 1990) Vacation

The `6 24 1990' indicates the starting date and the `7 10 1990' indicates the stopping date. (Again, if you are using the European calendar style, the month and day are interchanged.)

To insert a block entry, place point and the mark on the two dates that begin and end the range, and type i b. This command displays the end of your diary file in another window and inserts the block description; you can then type the diary entry.

Cyclic diary entries repeat after a fixed interval of days. To create one, select the starting date and use the i c command. The command prompts for the length of interval, then inserts the entry, which looks like this:

%%(diary-cyclic 50 3 1 1990) Renew medication

This entry applies to March 1, 1990 and every 50th day following; `3 1 1990' specifies the starting date. (If you are using the European calendar style, the month and day are interchanged.)

All three of these commands make marking diary entries. To insert a nonmarking entry, give a numeric argument to the command. For example, C-u i a makes a nonmarking anniversary diary entry.

Marking sexp diary entries in the calendar is extremely time-consuming, since every date visible in the calendar window must be individually checked. So it's a good idea to make sexp diary entries nonmarking (with `&') when possible.

Another sophisticated kind of sexp entry, a floating diary entry, specifies a regularly occurring event by offsets specified in days, weeks, and months. It is comparable to a crontab entry interpreted by the cron utility. Here is a nonmarking, floating diary entry that applies to the last Thursday in November:

&%%(diary-float 11 4 -1) American Thanksgiving

The 11 specifies November (the eleventh month), the 4 specifies Thursday (the fourth day of the week, where Sunday is numbered zero), and the -1 specifies "last" (1 would mean "first," 2 would mean "second," -2 would mean "second-to-last," and so on). The month can be a single month or a list of months. Thus you could change the 11 above to `'(1 2 3)' and have the entry apply to the last Thursday of January, February, and March. If the month is t, the entry applies to all months of the year.

Most generally, sexp diary entries can perform arbitrary computations to determine when they apply. See section `Sexp Diary Entries' in The Emacs Lisp Reference Manual.

Appointments

If you have a diary entry for an appointment, and that diary entry begins with a recognizable time of day, Emacs can warn you, several minutes beforehand, that that appointment is pending. Emacs alerts you to the appointment by displaying a message in the mode line.

To enable appointment notification, you must enable the time display feature of Emacs, M-x display-time (see section The Mode Line). You must also add the function appt-make-list to the diary-hook, like this:

(add-hook 'diary-hook 'appt-make-list)

Adding this text to your `.emacs' file does the whole job:

(display-time)
(add-hook 'diary-hook 'appt-make-list)
(diary 0)

With these preparations done, when you display the diary (either with the d command in the calendar window or with the M-x diary command), it sets up an appointment list of all the diary entries found with recognizable times of day, and reminds you just before each of them.

For example, suppose the diary file contains these lines:

Monday
  9:30am Coffee break
 12:00pm Lunch

Then on Mondays, after you have displayed the diary, you will be reminded at 9:20am about your coffee break and at 11:50am about lunch.

You can write times in am/pm style (with `12:00am' standing for midnight and `12:00pm' standing for noon), or 24-hour European/military style. You need not be consistent; your diary file can have a mixture of the two styles.

Emacs updates the appointments list automatically just after midnight. This also displays the next day's diary entries in the diary buffer, unless you set appt-display-diary to nil.

You can also use the appointment notification facility like an alarm clock. The command M-x appt-add adds entries to the appointment list without affecting your diary file. You delete entries from the appointment list with M-x appt-delete.

You can turn off the appointment notification feature at any time by setting appt-issue-message to nil.

Daylight Savings Time

Emacs understands the difference between standard time and daylight savings time--the times given for sunrise, sunset, solstices, equinoxes, and the phases of the moon take that into account. The rules for daylight savings time vary from place to place and have also varied historically from year to year. To do the job properly, Emacs needs to know which rules to use.

Some operating systems keep track of the rules that apply to the place where you are; on these systems, Emacs gets the information it needs from the system automatically. If some or all of this information is missing, Emacs fills in the gaps with the rules currently used in Cambridge, Massachusetts. If the resulting rules are not what you want, you can tell Emacs the rules to use by setting certain variables: calendar-daylight-savings-starts and calendar-daylight-savings-ends.

These values should be Lisp expressions that refer to the variable year, and evaluate to the Gregorian date on which daylight savings time starts or (respectively) ends, in the form of a list (month day year). The values should be nil if your area does not use daylight savings time.

Emacs uses these expressions to determine the starting date of daylight savings time for the holiday list and for correcting times of day in the solar and lunar calculations.

The values for Cambridge, Massachusetts are as follows:

(calendar-nth-named-day 1 0 4 year)
(calendar-nth-named-day -1 0 10 year)

That is, the first 0th day (Sunday) of the fourth month (April) in the year specified by year, and the last Sunday of the tenth month (October) of that year. If daylight savings time were changed to start on October 1, you would set calendar-daylight-savings-starts to this:

(list 10 1 year)

If there is no daylight savings time at your location, or if you want all times in standard time, set calendar-daylight-savings-starts and calendar-daylight-savings-ends to nil.

The variable calendar-daylight-time-offset specifies the difference between daylight savings time and standard time, measured in minutes. The value for Cambridge, Massachusetts is 60.

The two variables calendar-daylight-savings-starts-time and calendar-daylight-savings-ends-time specify the number of minutes after midnight local time when the transition to and from daylight savings time should occur. For Cambridge, Massachusetts both variables' values are 120.

Miscellaneous Commands

This chapter contains several brief topics that do not fit anywhere else: reading netnews, running shell commands and shell subprocesses, using a single shared Emacs for utilities that expect to run an editor as a subprocess, printing hardcopy, sorting text, narrowing display to part of the buffer, editing double-column files and binary files, saving an Emacs session for later resumption, emulating other editors, and various diversions and amusements.

Gnus

Gnus is an Emacs package primarily designed for reading and posting Usenet news. It can also be used to read and respond to messages from a number of other sources--mail, remote directories, digests, and so on.

Here we introduce Gnus and describe several basic features. For full details on Gnus, type M-x info and then select the Gnus manual.

To start Gnus, type M-x gnus RET.

Gnus Buffers

As opposed to most normal Emacs packages, Gnus uses a number of different buffers to display information and to receive commands. The three buffers users spend most of their time in are the group buffer, the summary buffer and the article buffer.

The group buffer contains a list of groups. This is the first buffer Gnus displays when it starts up. It normally displays only the groups to which you subscribe and that contain unread articles. Use this buffer to select a specific group.

The summary buffer lists one line for each article in a single group. By default, the author, the subject and the line number are displayed for each article, but this is customizable, like most aspects of Gnus display. The summary buffer is created when you select a group in the group buffer, and is killed when you exit the group. Use this buffer to select an article.

The article buffer displays the article. In normal Gnus usage, you don't select this buffer--all useful article-oriented commands work in the summary buffer. But you can select the article buffer, and execute all Gnus commands from that buffer, if you want to.

When Gnus Starts Up

At startup, Gnus reads your `.newsrc' news initialization file and attempts to communicate with the local news server, which is a repository of news articles. The news server need not be the same computer you are logged in on.

If you start Gnus and connect to the server, but do not see any newsgroups listed in the group buffer, type L or A k to get a listing of all the groups. Then type u to toggle subscription to groups.

The first time you start Gnus, Gnus subscribes you to a few selected groups. All other groups start out as killed groups for you; you can list them with A k. All new groups that subsequently come to exist at the news server become zombie groups for you; type A z to list them. You can subscribe to a group shown in these lists using the u command.

When you quit Gnus with q, it automatically records in your `.newsrc' and `.newsrc.eld' initialization files the subscribed or unsubscribed status of all groups. You should normally not edit these files manually, but you may if you know how.

Summary of Gnus Commands

Reading news is a two step process:

  1. Choose a group in the group buffer.
  2. Select articles from the summary buffer. Each article selected is displayed in the article buffer in a large window, below the summary buffer in its small window.

Each Gnus buffer has its own special commands; however, the meanings of any given key in the various Gnus buffers are usually analogous, even if not identical. Here are commands for the group and summary buffers:

q
In the group buffer, update your `.newsrc' initialization file and quit Gnus. In the summary buffer, exit the current group and return to the group buffer. Thus, typing q twice quits Gnus.
L
In the group buffer, list all the groups available on your news server (except those you have killed). This may be a long list!
l
In the group buffer, list only the groups to which you subscribe and which contain unread articles.
u
In the group buffer, unsubscribe from (or subscribe to) the group listed in the line that point is on. When you quit Gnus by typing q, Gnus lists in your `.newsrc' file which groups you have subscribed to. The next time you start Gnus, you won't see this group, because Gnus normally displays only subscribed-to groups.
C-k
In the group buffer, "kill" the current line's group--don't even list it in `.newsrc' from now on. This affects future Gnus sessions as well as the present session. When you quit Gnus by typing q, Gnus writes information in the file `.newsrc' describing all newsgroups except those you have "killed."
SPC
In the group buffer, select the group on the line under the cursor and display the first unread article in that group. In the summary buffer,
  • Select the article on the line under the cursor if none is selected.
  • Scroll the text of the selected article (if there is one).
  • Select the next unread article if at the end of the current article.
Thus, you can move through all the articles by repeatedly typing SPC.
DEL
In the group buffer, move point to the previous group containing unread articles. In the summary buffer, scroll the text of the article backwards.
n
Move point to the next unread group, or select the next unread article.
p
Move point to the previous unread group, or select the previous unread article.
C-n
C-p
Move point to the next or previous item, even if it is marked as read. This does not select the article or group on that line.
s
In the summary buffer, do an incremental search of the current text in the article buffer, just as if you switched to the article buffer and typed C-s.
M-s regexp RET
In the summary buffer, search forward for articles containing a match for regexp.

Running Shell Commands from Emacs

Emacs has commands for passing single command lines to inferior shell processes; it can also run a shell interactively with input and output to an Emacs buffer named `*shell*'.

M-! cmd RET
Run the shell command line cmd and display the output (shell-command).
M-| cmd RET
Run the shell command line cmd with region contents as input; optionally replace the region with the output (shell-command-on-region).
M-x shell
Run a subshell with input and output through an Emacs buffer. You can then give commands interactively.

Single Shell Commands

M-! (shell-command) reads a line of text using the minibuffer and executes it as a shell command in a subshell made just for that command. Standard input for the command comes from the null device. If the shell command produces any output, the output goes into an Emacs buffer named `*Shell Command Output*', which is displayed in another window but not selected. A numeric argument, as in M-1 M-!, directs this command to insert any output into the current buffer. In that case, point is left before the output and the mark is set after the output.

If the shell command line ends in `&', it runs asynchronously. For a synchronous shell command, shell-command returns the command's exit status (0 means success), when it is called from a Lisp program.

M-| (shell-command-on-region) is like M-! but passes the contents of the region as the standard input to the shell command, instead of no input. If a numeric argument is used, meaning insert the output in the current buffer, then the old region is deleted first and the output replaces it as the contents of the region. It returns the command's exit status when it is called from a Lisp program.

Both M-! and M-| use shell-file-name to specify the shell to use. This variable is initialized based on your SHELL environment variable when Emacs is started. If the file name does not specify a directory, the directories in the list exec-path are searched; this list is initialized based on the environment variable PATH when Emacs is started. Your `.emacs' file can override either or both of these default initializations.

Both M-! and M-| wait for the shell command to complete. To stop waiting, type C-g to quit; that terminates the shell command with the signal SIGINT---the same signal that C-c normally generates in the shell. Emacs waits until the command actually terminates. If the shell command doesn't stop (because it ignores the SIGINT signal), type C-g again; this sends the command a SIGKILL signal which is impossible to ignore.

To specify a coding system for M-! or M-|, use the command C-x RET c immediately beforehand. See section Specifying a Coding System.

Error output from the command is normally intermixed with the regular output. If you set the variable shell-command-default-error-buffer to a string, which is a buffer name, error output is inserted before point in the buffer of that name.

Interactive Inferior Shell

To run a subshell interactively, putting its typescript in an Emacs buffer, use M-x shell. This creates (or reuses) a buffer named `*shell*' and runs a subshell with input coming from and output going to that buffer. That is to say, any "terminal output" from the subshell goes into the buffer, advancing point, and any "terminal input" for the subshell comes from text in the buffer. To give input to the subshell, go to the end of the buffer and type the input, terminated by RET.

Emacs does not wait for the subshell to do anything. You can switch windows or buffers and edit them while the shell is waiting, or while it is running a command. Output from the subshell waits until Emacs has time to process it; this happens whenever Emacs is waiting for keyboard input or for time to elapse.

To make multiple subshells, rename the buffer `*shell*' to something different using M-x rename-uniquely. Then type M-x shell again to create a new buffer `*shell*' with its own subshell. If you rename this buffer as well, you can create a third one, and so on. All the subshells run independently and in parallel.

The file name used to load the subshell is the value of the variable explicit-shell-file-name, if that is non-nil. Otherwise, the environment variable ESHELL is used, or the environment variable SHELL if there is no ESHELL. If the file name specified is relative, the directories in the list exec-path are searched; this list is initialized based on the environment variable PATH when Emacs is started. Your `.emacs' file can override either or both of these default initializations.

To specify a coding system for the shell, you can use the command C-x RET c immediately before M-x shell. You can also specify a coding system after starting the shell by using C-x RET p in the shell buffer. See section Specifying a Coding System.

As soon as the subshell is started, it is sent as input the contents of the file `~/.emacs_shellname', if that file exists, where shellname is the name of the file that the shell was loaded from. For example, if you use bash, the file sent to it is `~/.emacs_bash'.

cd, pushd and popd commands given to the inferior shell are watched by Emacs so it can keep the `*shell*' buffer's default directory the same as the shell's working directory. These commands are recognized syntactically by examining lines of input that are sent. If you use aliases for these commands, you can tell Emacs to recognize them also. For example, if the value of the variable shell-pushd-regexp matches the beginning of a shell command line, that line is regarded as a pushd command. Change this variable when you add aliases for `pushd'. Likewise, shell-popd-regexp and shell-cd-regexp are used to recognize commands with the meaning of `popd' and `cd'. These commands are recognized only at the beginning of a shell command line.

If Emacs gets an error while trying to handle what it believes is a `cd', `pushd' or `popd' command, it runs the hook shell-set-directory-error-hook (see section Hooks).

If Emacs does not properly track changes in the current directory of the subshell, use the command M-x dirs to ask the shell what its current directory is. This command works for shells that support the most common command syntax; it may not work for unusual shells.

You can also use M-x dirtrack-mode to enable (or disable) an alternative and more aggressive method of tracking changes in the current directory.

Emacs defines the environment variable EMACS in the subshell, with value t. A shell script can check this variable to determine whether it has been run from an Emacs subshell.

Shell Mode

Shell buffers use Shell mode, which defines several special keys attached to the C-c prefix. They are chosen to resemble the usual editing and job control characters present in shells that are not under Emacs, except that you must type C-c first. Here is a complete list of the special key bindings of Shell mode:

RET
At end of buffer send line as input; otherwise, copy current line to end of buffer and send it (comint-send-input). When a line is copied, any text at the beginning of the line that matches the variable shell-prompt-pattern is left out; this variable's value should be a regexp string that matches the prompts that your shell uses.
TAB
Complete the command name or file name before point in the shell buffer (comint-dynamic-complete). TAB also completes history references (see section Shell History References) and environment variable names. The variable shell-completion-fignore specifies a list of file name extensions to ignore in Shell mode completion. The default setting ignores file names ending in `~', `#' or `%'. Other related Comint modes use the variable comint-completion-fignore instead.
M-?
Display temporarily a list of the possible completions of the file name before point in the shell buffer (comint-dynamic-list-filename-completions).
C-d
Either delete a character or send EOF (comint-delchar-or-maybe-eof). Typed at the end of the shell buffer, C-d sends EOF to the subshell. Typed at any other position in the buffer, C-d deletes a character as usual.
C-c C-a
Move to the beginning of the line, but after the prompt if any (comint-bol). If you repeat this command twice in a row, the second time it moves back to the process mark, which is the beginning of the input that you have not yet sent to the subshell. (Normally that is the same place--the end of the prompt on this line--but after C-c SPC the process mark may be in a previous line.)
C-c SPC
Accumulate multiple lines of input, then send them together. This command inserts a newline before point, but does not send the preceding text as input to the subshell--at least, not yet. Both lines, the one before this newline and the one after, will be sent together (along with the newline that separates them), when you type RET.
C-c C-u
Kill all text pending at end of buffer to be sent as input (comint-kill-input).
C-c C-w
Kill a word before point (backward-kill-word).
C-c C-c
Interrupt the shell or its current subjob if any (comint-interrupt-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.
C-c C-z
Stop the shell or its current subjob if any (comint-stop-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.
C-c C-\
Send quit signal to the shell or its current subjob if any (comint-quit-subjob). This command also kills any shell input pending in the shell buffer and not yet sent.
C-c C-o
Kill the last batch of output from a shell command (comint-kill-output). This is useful if a shell command spews out lots of output that just gets in the way.
C-c C-r
C-M-l
Scroll to display the beginning of the last batch of output at the top of the window; also move the cursor there (comint-show-output).
C-c C-e
Scroll to put the end of the buffer at the bottom of the window (comint-show-maximum-output).
C-c C-f
Move forward across one shell command, but not beyond the current line (shell-forward-command). The variable shell-command-regexp specifies how to recognize the end of a command.
C-c C-b
Move backward across one shell command, but not beyond the current line (shell-backward-command).
C-c C-l
Display the buffer's history of shell commands in another window (comint-dynamic-list-input-ring).
M-x dirs
Ask the shell what its current directory is, so that Emacs can agree with the shell.
M-x send-invisible RET text RET
Send text as input to the shell, after reading it without echoing. This is useful when a shell command runs a program that asks for a password. Alternatively, you can arrange for Emacs to notice password prompts and turn off echoing for them, as follows:
(add-hook 'comint-output-filter-functions
          'comint-watch-for-password-prompt)
M-x comint-continue-subjob
Continue the shell process. This is useful if you accidentally suspend the shell process.(5)
M-x comint-strip-ctrl-m
Discard all control-M characters from the current group of shell output. The most convenient way to use this command is to make it run automatically when you get output from the subshell. To do that, evaluate this Lisp expression:
(add-hook 'comint-output-filter-functions
          'comint-strip-ctrl-m)
M-x comint-truncate-buffer
This command truncates the shell buffer to a certain maximum number of lines, specified by the variable comint-buffer-maximum-size. Here's how to do this automatically each time you get output from the subshell:
(add-hook 'comint-output-filter-functions
          'comint-truncate-buffer)

Shell mode also customizes the paragraph commands so that only shell prompts start new paragraphs. Thus, a paragraph consists of an input command plus the output that follows it in the buffer.

Shell mode is a derivative of Comint mode, a general-purpose mode for communicating with interactive subprocesses. Most of the features of Shell mode actually come from Comint mode, as you can see from the command names listed above. The special features of Shell mode in particular include the choice of regular expression for detecting prompts, the directory tracking feature, and a few user commands.

Other Emacs features that use variants of Comint mode include GUD (see section Running Debuggers Under Emacs) and M-x run-lisp (see section Running an External Lisp).

You can use M-x comint-run to execute any program of your choice in a subprocess using unmodified Comint mode--without the specializations of Shell mode.

Shell Command History

Shell buffers support three ways of repeating earlier commands. You can use the same keys used in the minibuffer; these work much as they do in the minibuffer, inserting text from prior commands while point remains always at the end of the buffer. You can move through the buffer to previous inputs in their original place, then resubmit them or copy them to the end. Or you can use a `!'-style history reference.

Shell History Ring

M-p
Fetch the next earlier old shell command.
M-n
Fetch the next later old shell command.
M-r regexp RET
M-s regexp RET
Search backwards or forwards for old shell commands that match regexp.
C-c C-x (Shell mode)
Fetch the next subsequent command from the history.

Shell buffers provide a history of previously entered shell commands. To reuse shell commands from the history, use the editing commands M-p, M-n, M-r and M-s. These work just like the minibuffer history commands except that they operate on the text at the end of the shell buffer, where you would normally insert text to send to the shell.

M-p fetches an earlier shell command to the end of the shell buffer. Successive use of M-p fetches successively earlier shell commands, each replacing any text that was already present as potential shell input. M-n does likewise except that it finds successively more recent shell commands from the buffer.

The history search commands M-r and M-s read a regular expression and search through the history for a matching command. Aside from the choice of which command to fetch, they work just like M-p and M-r. If you enter an empty regexp, these commands reuse the same regexp used last time.

When you find the previous input you want, you can resubmit it by typing RET, or you can edit it first and then resubmit it if you wish.

Often it is useful to reexecute several successive shell commands that were previously executed in sequence. To do this, first find and reexecute the first command of the sequence. Then type C-c C-x; that will fetch the following command--the one that follows the command you just repeated. Then type RET to reexecute this command. You can reexecute several successive commands by typing C-c C-x RET over and over.

These commands get the text of previous shell commands from a special history list, not from the shell buffer itself. Thus, editing the shell buffer, or even killing large parts of it, does not affect the history that these commands access.

Some shells store their command histories in files so that you can refer to previous commands from previous shell sessions. Emacs reads the command history file for your chosen shell, to initialize its own command history. The file name is `~/.bash_history' for bash, `~/.sh_history' for ksh, and `~/.history' for other shells.

Shell History Copying

C-c C-p
Move point to the previous prompt (comint-previous-prompt).
C-c C-n
Move point to the following prompt (comint-next-prompt).
C-c RET
Copy the input command which point is in, inserting the copy at the end of the buffer (comint-copy-old-input). This is useful if you move point back to a previous command. After you copy the command, you can submit the copy as input with RET. If you wish, you can edit the copy before resubmitting it.

Moving to a previous input and then copying it with C-c RET produces the same results--the same buffer contents--that you would get by using M-p enough times to fetch that previous input from the history list. However, C-c RET copies the text from the buffer, which can be different from what is in the history list if you edit the input text in the buffer after it has been sent.

Shell History References

Various shells including csh and bash support history references that begin with `!' and `^'. Shell mode can understand these constructs and perform the history substitution for you. If you insert a history reference and type TAB, this searches the input history for a matching command, performs substitution if necessary, and places the result in the buffer in place of the history reference. For example, you can fetch the most recent command beginning with `mv' with ! m v TAB. You can edit the command if you wish, and then resubmit the command to the shell by typing RET.

History references take effect only following a shell prompt. The variable shell-prompt-pattern specifies how to recognize a shell prompt. Comint modes in general use the variable comint-prompt-regexp to specify how to find a prompt; Shell mode uses shell-prompt-pattern to set up the local value of comint-prompt-regexp.

Shell mode can optionally expand history references in the buffer when you send them to the shell. To request this, set the variable comint-input-autoexpand to input.

You can make SPC perform history expansion by binding SPC to the command comint-magic-space.

Shell Mode Options

If the variable comint-scroll-to-bottom-on-input is non-nil, insertion and yank commands scroll the selected window to the bottom before inserting.

If comint-scroll-show-maximum-output is non-nil, then scrolling due to arrival of output tries to place the last line of text at the bottom line of the window, so as to show as much useful text as possible. (This mimics the scrolling behavior of many terminals.) The default is nil.

By setting comint-scroll-to-bottom-on-output, you can opt for having point jump to the end of the buffer whenever output arrives--no matter where in the buffer point was before. If the value is this, point jumps in the selected window. If the value is all, point jumps in each window that shows the comint buffer. If the value is other, point jumps in all nonselected windows that show the current buffer. The default value is nil, which means point does not jump to the end.

The variable comint-input-ignoredups controls whether successive identical inputs are stored in the input history. A non-nil value means to omit an input that is the same as the previous input. The default is nil, which means to store each input even if it is equal to the previous input.

Three variables customize file name completion. The variable comint-completion-addsuffix controls whether completion inserts a space or a slash to indicate a fully completed file or directory name (non-nil means do insert a space or slash). comint-completion-recexact, if non-nil, directs TAB to choose the shortest possible completion if the usual Emacs completion algorithm cannot add even a single character. comint-completion-autolist, if non-nil, says to list all the possible completions whenever completion is not exact.

The command comint-dynamic-complete-variable does variable-name completion using the environment variables as set within Emacs. The variables controlling file name completion apply to variable-name completion too. This command is normally available through the menu bar.

Command completion normally considers only executable files. If you set shell-command-execonly to nil, it considers nonexecutable files as well.

You can configure the behavior of `pushd'. Variables control whether `pushd' behaves like `cd' if no argument is given (shell-pushd-tohome), pop rather than rotate with a numeric argument (shell-pushd-dextract), and only add directories to the directory stack if they are not already on it (shell-pushd-dunique). The values you choose should match the underlying shell, of course.

Remote Host Shell

Emacs provides two commands for logging in to another computer and communicating with it through an Emacs buffer.

M-x telnet RET hostname RET
Set up a Telnet connection to the computer named hostname.
M-x rlogin RET hostname RET
Set up an Rlogin connection to the computer named hostname.

Use M-x telnet to set up a Telnet connection to another computer. (Telnet is the standard Internet protocol for remote login.) It reads the host name of the other computer as an argument with the minibuffer. Once the connection is established, talking to the other computer works like talking to a subshell: you can edit input with the usual Emacs commands, and send it a line at a time by typing RET. The output is inserted in the Telnet buffer interspersed with the input.

Use M-x rlogin to set up an Rlogin connection. Rlogin is another remote login communication protocol, essentially much like the Telnet protocol but incompatible with it, and supported only by certain systems. Rlogin's advantages are that you can arrange not to have to give your user name and password when communicating between two machines you frequently use, and that you can make an 8-bit-clean connection. (To do that in Emacs, set rlogin-explicit-args to ("-8") before you run Rlogin.)

M-x rlogin sets up the default file directory of the Emacs buffer to access the remote host via FTP (see section File Names), and it tracks the shell commands that change the current directory, just like Shell mode.

There are two ways of doing directory tracking in an Rlogin buffer--either with remote directory names `/host:dir/' or with local names (that works if the "remote" machine shares file systems with your machine of origin). You can use the command rlogin-directory-tracking-mode to switch modes. No argument means use remote directory names, a positive argument means use local names, and a negative argument means turn off directory tracking.

Using Emacs as a Server

Various programs such as mail can invoke your choice of editor to edit a particular piece of text, such as a message that you are sending. By convention, most of these programs use the environment variable EDITOR to specify which editor to run. If you set EDITOR to `emacs', they invoke Emacs--but in an inconvenient fashion, by starting a new, separate Emacs process. This is inconvenient because it takes time and because the new Emacs process doesn't share the buffers in the existing Emacs process.

You can arrange to use your existing Emacs process as the editor for programs like mail by using the Emacs client and Emacs server programs. Here is how.

First, the preparation. Within Emacs, call the function server-start. (Your `.emacs' file can do this automatically if you add the expression (server-start) to it.) Then, outside Emacs, set the EDITOR environment variable to `emacsclient'. (Note that some programs use a different environment variable; for example, to make TeX use `emacsclient', you should set the TEXEDIT environment variable to `emacsclient +%d %s'.)

Then, whenever any program invokes your specified EDITOR program, the effect is to send a message to your principal Emacs telling it to visit a file. (That's what the program emacsclient does.) Emacs displays the buffer immediately and you can immediately begin editing it.

When you've finished editing that buffer, type C-x # (server-edit). This saves the file and sends a message back to the emacsclient program telling it to exit. The programs that use EDITOR wait for the "editor" (actually, emacsclient) to exit. C-x # also checks for other pending external requests to edit various files, and selects the next such file.

You can switch to a server buffer manually if you wish; you don't have to arrive at it with C-x #. But C-x # is the only way to say that you are "finished" with one.

If you set the variable server-window to a window or a frame, C-x # displays the server buffer in that window or in that frame.

While mail or another application is waiting for emacsclient to finish, emacsclient does not read terminal input. So the terminal that mail was using is effectively blocked for the duration. In order to edit with your principal Emacs, you need to be able to use it without using that terminal. There are two ways to do this:

  • Using a window system, run mail and the principal Emacs in two separate windows. While mail is waiting for emacsclient, the window where it was running is blocked, but you can use Emacs by switching windows.
  • Use Shell mode in Emacs to run the other program such as mail; then, emacsclient blocks only the subshell under Emacs, and you can still use Emacs to edit the file.

Some programs write temporary files for you to edit. After you edit the temporary file, the program reads it back and deletes it. If the Emacs server is later asked to edit the same file name, it should assume this has nothing to do with the previous occasion for that file name. The server accomplishes this by killing the temporary file's buffer when you finish with the file. Use the variable server-temp-file-regexp to specify which files are temporary in this sense; its value should be a regular expression that matches file names that are temporary.

If you run emacsclient with the option `--no-wait', it returns immediately without waiting for you to "finish" the buffer in Emacs.

Hardcopy Output

The Emacs commands for making hardcopy let you print either an entire buffer or just part of one, either with or without page headers. See also the hardcopy commands of Dired (see section Miscellaneous File Operations) and the diary (see section Commands Displaying Diary Entries).

M-x print-buffer
Print hardcopy of current buffer with page headings containing the file name and page number.
M-x lpr-buffer
Print hardcopy of current buffer without page headings.
M-x print-region
Like print-buffer but print only the current region.
M-x lpr-region
Like lpr-buffer but print only the current region.

The hardcopy commands (aside from the Postscript commands) pass extra switches to the lpr program based on the value of the variable lpr-switches. Its value should be a list of strings, each string an option starting with `-'. For example, to specify a line width of 80 columns for all the printing you do in Emacs, set lpr-switches like this:

(setq lpr-switches '("-w80"))

You can specify the printer to use by setting the variable printer-name.

The variable lpr-command specifies the name of the printer program to run; the default value depends on your operating system type. On most systems, the default is "lpr". The variable lpr-headers-switches similarly specifies the extra switches to use to make page headers. The variable lpr-add-switches controls whether to supply `-T' and `-J' options (suitable for lpr) to the printer program: nil means don't add them. lpr-add-switches should be nil if your printer program is not compatible with lpr.

Postscript Hardcopy

These commands convert buffer contents to Postscript, either printing it or leaving it in another Emacs buffer.

M-x ps-print-buffer
Print hardcopy of the current buffer in Postscript form.
M-x ps-print-region
Print hardcopy of the current region in Postscript form.
M-x ps-print-buffer-with-faces
Print hardcopy of the current buffer in Postscript form, showing the faces used in the text by means of Postscript features.
M-x ps-print-region-with-faces
Print hardcopy of the current region in Postscript form, showing the faces used in the text.
M-x ps-spool-buffer
Generate Postscript for the current buffer text.
M-x ps-spool-region
Generate Postscript for the current region.
M-x ps-spool-buffer-with-faces
Generate Postscript for the current buffer, showing the faces used.
M-x ps-spool-region-with-faces
Generate Postscript for the current region, showing the faces used.

The Postscript commands, ps-print-buffer and ps-print-region, print buffer contents in Postscript form. One command prints the entire buffer; the other, just the region. The corresponding `-with-faces' commands, ps-print-buffer-with-faces and ps-print-region-with-faces, use Postscript features to show the faces (fonts and colors) in the text properties of the text being printed.

If you are using a color display, you can print a buffer of program code with color highlighting by turning on Font-Lock mode in that buffer, and using ps-print-buffer-with-faces.

The commands whose names have `spool' instead of `print' generate the Postscript output in an Emacs buffer instead of sending it to the printer.

Variables for Postscript Hardcopy

All the Postscript hardcopy commands use the variables ps-lpr-command and ps-lpr-switches to specify how to print the output. ps-lpr-command specifies the command name to run, ps-lpr-switches specifies command line options to use, and ps-printer-name specifies the printer. If you don't set the first two variables yourself, they take their initial values from lpr-command and lpr-switches. If ps-printer-name is nil, printer-name is used.

The variable ps-print-header controls whether these commands add header lines to each page--set it to nil to turn headers off. You can turn off color processing by setting ps-print-color-p to nil.

The variable ps-paper-type specifies which size of paper to format for; legitimate values include a4, a3, a4small, b4, b5, executive, ledger, legal, letter, letter-small, statement, tabloid. The default is letter. You can define additional paper sizes by changing the variable ps-page-dimensions-database.

The variable ps-landscape-mode specifies the orientation of printing on the page. The default is nil, which stands for "portrait" mode. Any non-nil value specifies "landscape" mode.

The variable ps-number-of-columns specifies the number of columns; it takes effect in both landscape and portrait mode. The default is 1.

The variable ps-font-family specifies which font family to use for printing ordinary text. Legitimate values include Courier, Helvetica, NewCenturySchlbk, Palatino and Times. The variable ps-font-size specifies the size of the font for ordinary text. It defaults to 8.5 points.

Many other customization variables for these commands are defined and described in the Lisp file `ps-print.el'.

Sorting Text

Emacs provides several commands for sorting text in the buffer. All operate on the contents of the region (the text between point and the mark). They divide the text of the region into many sort records, identify a sort key for each record, and then reorder the records into the order determined by the sort keys. The records are ordered so that their keys are in alphabetical order, or, for numeric sorting, in numeric order. In alphabetic sorting, all upper-case letters `A' through `Z' come before lower-case `a', in accord with the ASCII character sequence.

The various sort commands differ in how they divide the text into sort records and in which part of each record is used as the sort key. Most of the commands make each line a separate sort record, but some commands use paragraphs or pages as sort records. Most of the sort commands use each entire sort record as its own sort key, but some use only a portion of the record as the sort key.

M-x sort-lines
Divide the region into lines, and sort by comparing the entire text of a line. A numeric argument means sort into descending order.
M-x sort-paragraphs
Divide the region into paragraphs, and sort by comparing the entire text of a paragraph (except for leading blank lines). A numeric argument means sort into descending order.
M-x sort-pages
Divide the region into pages, and sort by comparing the entire text of a page (except for leading blank lines). A numeric argument means sort into descending order.
M-x sort-fields
Divide the region into lines, and sort by comparing the contents of one field in each line. Fields are defined as separated by whitespace, so the first run of consecutive non-whitespace characters in a line constitutes field 1, the second such run constitutes field 2, etc. Specify which field to sort by with a numeric argument: 1 to sort by field 1, etc. A negative argument means count fields from the right instead of from the left; thus, minus 1 means sort by the last field. If several lines have identical contents in the field being sorted, they keep same relative order that they had in the original buffer.
M-x sort-numeric-fields
Like M-x sort-fields except the specified field is converted to an integer for each line, and the numbers are compared. `10' comes before `2' when considered as text, but after it when considered as a number.
M-x sort-columns
Like M-x sort-fields except that the text within each line used for comparison comes from a fixed range of columns. See below for an explanation.
M-x reverse-region
Reverse the order of the lines in the region. This is useful for sorting into descending order by fields or columns, since those sort commands do not have a feature for doing that.

For example, if the buffer contains this:

On systems where clash detection (locking of files being edited) is
implemented, Emacs also checks the first time you modify a buffer
whether the file has changed on disk since it was last visited or
saved.  If it has, you are asked to confirm that you want to change
the buffer.

applying M-x sort-lines to the entire buffer produces this:

On systems where clash detection (locking of files being edited) is
implemented, Emacs also checks the first time you modify a buffer
saved.  If it has, you are asked to confirm that you want to change
the buffer.
whether the file has changed on disk since it was last visited or

where the upper-case `O' sorts before all lower-case letters. If you use C-u 2 M-x sort-fields instead, you get this:

implemented, Emacs also checks the first time you modify a buffer
saved.  If it has, you are asked to confirm that you want to change
the buffer.
On systems where clash detection (locking of files being edited) is
whether the file has changed on disk since it was last visited or

where the sort keys were `Emacs', `If', `buffer', `systems' and `the'.

M-x sort-columns requires more explanation. You specify the columns by putting point at one of the columns and the mark at the other column. Because this means you cannot put point or the mark at the beginning of the first line of the text you want to sort, this command uses an unusual definition of `region': all of the line point is in is considered part of the region, and so is all of the line the mark is in, as well as all the lines in between.

For example, to sort a table by information found in columns 10 to 15, you could put the mark on column 10 in the first line of the table, and point on column 15 in the last line of the table, and then run sort-columns. Equivalently, you could run it with the mark on column 15 in the first line and point on column 10 in the last line.

This can be thought of as sorting the rectangle specified by point and the mark, except that the text on each line to the left or right of the rectangle moves along with the text inside the rectangle. See section Rectangles.

Many of the sort commands ignore case differences when comparing, if sort-fold-case is non-nil.

Narrowing

Narrowing means focusing in on some portion of the buffer, making the rest temporarily inaccessible. The portion which you can still get to is called the accessible portion. Canceling the narrowing, which makes the entire buffer once again accessible, is called widening. The amount of narrowing in effect in a buffer at any time is called the buffer's restriction.

Narrowing can make it easier to concentrate on a single subroutine or paragraph by eliminating clutter. It can also be used to restrict the range of operation of a replace command or repeating keyboard macro.

C-x n n
Narrow down to between point and mark (narrow-to-region).
C-x n w
Widen to make the entire buffer accessible again (widen).
C-x n p
Narrow down to the current page (narrow-to-page).
C-x n d
Narrow down to the current defun (narrow-to-defun).

When you have narrowed down to a part of the buffer, that part appears to be all there is. You can't see the rest, you can't move into it (motion commands won't go outside the accessible part), you can't change it in any way. However, it is not gone, and if you save the file all the inaccessible text will be saved. The word `Narrow' appears in the mode line whenever narrowing is in effect.

The primary narrowing command is C-x n n (narrow-to-region). It sets the current buffer's restrictions so that the text in the current region remains accessible but all text before the region or after the region is inaccessible. Point and mark do not change.

Alternatively, use C-x n p (narrow-to-page) to narrow down to the current page. See section Pages, for the definition of a page. C-x n d (narrow-to-defun) narrows down to the defun containing point (see section Defuns).

The way to cancel narrowing is to widen with C-x n w (widen). This makes all text in the buffer accessible again.

You can get information on what part of the buffer you are narrowed down to using the C-x = command. See section Cursor Position Information.

Because narrowing can easily confuse users who do not understand it, narrow-to-region is normally a disabled command. Attempting to use this command asks for confirmation and gives you the option of enabling it; if you enable the command, confirmation will no longer be required for it. See section Disabling Commands.

Two-Column Editing

Two-column mode lets you conveniently edit two side-by-side columns of text. It uses two side-by-side windows, each showing its own buffer.

There are three ways to enter two-column mode:

F2 2 or C-x 6 2
Enter two-column mode with the current buffer on the left, and on the right, a buffer whose name is based on the current buffer's name (2C-two-columns). If the right-hand buffer doesn't already exist, it starts out empty; the current buffer's contents are not changed. This command is appropriate when the current buffer is empty or contains just one column and you want to add another column.
F2 s or C-x 6 s
Split the current buffer, which contains two-column text, into two buffers, and display them side by side (2C-split). The current buffer becomes the left-hand buffer, but the text in the right-hand column is moved into the right-hand buffer. The current column specifies the split point. Splitting starts with the current line and continues to the end of the buffer. This command is appropriate when you have a buffer that already contains two-column text, and you wish to separate the columns temporarily.
F2 b buffer RET
C-x 6 b buffer RET
Enter two-column mode using the current buffer as the left-hand buffer, and using buffer buffer as the right-hand buffer (2C-associate-buffer).

F2 s or C-x 6 s looks for a column separator, which is a string that appears on each line between the two columns. You can specify the width of the separator with a numeric argument to F2 s; that many characters, before point, constitute the separator string. By default, the width is 1, so the column separator is the character before point.

When a line has the separator at the proper place, F2 s puts the text after the separator into the right-hand buffer, and deletes the separator. Lines that don't have the column separator at the proper place remain unsplit; they stay in the left-hand buffer, and the right-hand buffer gets an empty line to correspond. (This is the way to write a line that "spans both columns while in two-column mode": write it in the left-hand buffer, and put an empty line in the right-hand buffer.)

The command C-x 6 RET or F2 RET (2C-newline) inserts a newline in each of the two buffers at corresponding positions. This is the easiest way to add a new line to the two-column text while editing it in split buffers.

When you have edited both buffers as you wish, merge them with F2 1 or C-x 6 1 (2C-merge). This copies the text from the right-hand buffer as a second column in the other buffer. To go back to two-column editing, use F2 s.

Use F2 d or C-x 6 d to dissociate the two buffers, leaving each as it stands (2C-dissociate). If the other buffer, the one not current when you type F2 d, is empty, F2 d kills it.

Editing Binary Files

There is a special major mode for editing binary files: Hexl mode. To use it, use M-x hexl-find-file instead of C-x C-f to visit the file. This command converts the file's contents to hexadecimal and lets you edit the translation. When you save the file, it is converted automatically back to binary.

You can also use M-x hexl-mode to translate an existing buffer into hex. This is useful if you visit a file normally and then discover it is a binary file.

Ordinary text characters overwrite in Hexl mode. This is to reduce the risk of accidentally spoiling the alignment of data in the file. There are special commands for insertion. Here is a list of the commands of Hexl mode:

C-M-d
Insert a byte with a code typed in decimal.
C-M-o
Insert a byte with a code typed in octal.
C-M-x
Insert a byte with a code typed in hex.
C-x [
Move to the beginning of a 1k-byte "page."
C-x ]
Move to the end of a 1k-byte "page."
M-g
Move to an address specified in hex.
M-j
Move to an address specified in decimal.
C-c C-c
Leave Hexl mode, going back to the major mode this buffer had before you invoked hexl-mode.

Saving Emacs Sessions

You can use the Desktop library to save the state of Emacs from one session to another. Saving the state means that Emacs starts up with the same set of buffers, major modes, buffer positions, and so on that the previous Emacs session had.

To use Desktop, you should use the Customization buffer (see section Easy Customization Interface) to set desktop-enable to a non-nil value, or add these lines at the end of your `.emacs' file:

(desktop-load-default)
(desktop-read)

The first time you save the state of the Emacs session, you must do it manually, with the command M-x desktop-save. Once you have done that, exiting Emacs will save the state again--not only the present Emacs session, but also subsequent sessions. You can also save the state at any time, without exiting Emacs, by typing M-x desktop-save again.

In order for Emacs to recover the state from a previous session, you must start it with the same current directory as you used when you started the previous session. This is because desktop-read looks in the current directory for the file to read. This means that you can have separate saved sessions in different directories; the directory in which you start Emacs will control which saved session to use.

The variable desktop-files-not-to-save controls which files are excluded from state saving. Its value is a regular expression that matches the files to exclude. By default, remote (ftp-accessed) files are excluded; this is because visiting them again in the subsequent session would be slow. If you want to include these files in state saving, set desktop-files-not-to-save to "^$". See section Remote Files.

Recursive Editing Levels

A recursive edit is a situation in which you are using Emacs commands to perform arbitrary editing while in the middle of another Emacs command. For example, when you type C-r inside of a query-replace, you enter a recursive edit in which you can change the current buffer. On exiting from the recursive edit, you go back to the query-replace.

Exiting the recursive edit means returning to the unfinished command, which continues execution. The command to exit is C-M-c (exit-recursive-edit).

You can also abort the recursive edit. This is like exiting, but also quits the unfinished command immediately. Use the command C-] (abort-recursive-edit) to do this. See section Quitting and Aborting.

The mode line shows you when you are in a recursive edit by displaying square brackets around the parentheses that always surround the major and minor mode names. Every window's mode line shows this, in the same way, since being in a recursive edit is true of Emacs as a whole rather than any particular window or buffer.

It is possible to be in recursive edits within recursive edits. For example, after typing C-r in a query-replace, you may type a command that enters the debugger. This begins a recursive editing level for the debugger, within the recursive editing level for C-r. Mode lines display a pair of square brackets for each recursive editing level currently in progress.

Exiting the inner recursive edit (such as, with the debugger c command) resumes the command running in the next level up. When that command finishes, you can then use C-M-c to exit another recursive editing level, and so on. Exiting applies to the innermost level only. Aborting also gets out of only one level of recursive edit; it returns immediately to the command level of the previous recursive edit. If you wish, you can then abort the next recursive editing level.

Alternatively, the command M-x top-level aborts all levels of recursive edits, returning immediately to the top-level command reader.

The text being edited inside the recursive edit need not be the same text that you were editing at top level. It depends on what the recursive edit is for. If the command that invokes the recursive edit selects a different buffer first, that is the buffer you will edit recursively. In any case, you can switch buffers within the recursive edit in the normal manner (as long as the buffer-switching keys have not been rebound). You could probably do all the rest of your editing inside the recursive edit, visiting files and all. But this could have surprising effects (such as stack overflow) from time to time. So remember to exit or abort the recursive edit when you no longer need it.

In general, we try to minimize the use of recursive editing levels in GNU Emacs. This is because they constrain you to "go back" in a particular order--from the innermost level toward the top level. When possible, we present different activities in separate buffers so that you can switch between them as you please. Some commands switch to a new major mode which provides a command to switch back. These approaches give you more flexibility to go back to unfinished tasks in the order you choose.

Emulation

GNU Emacs can be programmed to emulate (more or less) most other editors. Standard facilities can emulate these:

EDT (DEC VMS editor)
Turn on EDT emulation with M-x edt-emulation-on. M-x edt-emulation-off restores normal Emacs command bindings. Most of the EDT emulation commands are keypad keys, and most standard Emacs key bindings are still available. The EDT emulation rebindings are done in the global keymap, so there is no problem switching buffers or major modes while in EDT emulation.
vi (Berkeley editor)
Viper is the newest emulator for vi. It implements several levels of emulation; level 1 is closest to vi itself, while level 5 departs somewhat from strict emulation to take advantage of the capabilities of Emacs. To invoke Viper, type M-x viper-mode; it will guide you the rest of the way and ask for the emulation level. See Info file `viper', node `Top'.
vi (another emulator)
M-x vi-mode enters a major mode that replaces the previously established major mode. All of the vi commands that, in real vi, enter "input" mode are programmed instead to return to the previous major mode. Thus, ordinary Emacs serves as vi's "input" mode. Because vi emulation works through major modes, it does not work to switch buffers during emulation. Return to normal Emacs first. If you plan to use vi emulation much, you probably want to bind a key to the vi-mode command.
vi (alternate emulator)
M-x vip-mode invokes another vi emulator, said to resemble real vi more thoroughly than M-x vi-mode. "Input" mode in this emulator is changed from ordinary Emacs so you can use ESC to go back to emulated vi command mode. To get from emulated vi command mode back to ordinary Emacs, type C-z. This emulation does not work through major modes, and it is possible to switch buffers in various ways within the emulator. It is not so necessary to assign a key to the command vip-mode as it is with vi-mode because terminating insert mode does not use it. See Info file `vip', node `Top', for full information.

Dissociated Press

M-x dissociated-press is a command for scrambling a file of text either word by word or character by character. Starting from a buffer of straight English, it produces extremely amusing output. The input comes from the current Emacs buffer. Dissociated Press writes its output in a buffer named `*Dissociation*', and redisplays that buffer after every couple of lines (approximately) so you can read the output as it comes out.

Dissociated Press asks every so often whether to continue generating output. Answer n to stop it. You can also stop at any time by typing C-g. The dissociation output remains in the `*Dissociation*' buffer for you to copy elsewhere if you wish.

Dissociated Press operates by jumping at random from one point in the buffer to another. In order to produce plausible output rather than gibberish, it insists on a certain amount of overlap between the end of one run of consecutive words or characters and the start of the next. That is, if it has just printed out `president' and then decides to jump to a different point in the file, it might spot the `ent' in `pentagon' and continue from there, producing `presidentagon'.(6) Long sample texts produce the best results.

A positive argument to M-x dissociated-press tells it to operate character by character, and specifies the number of overlap characters. A negative argument tells it to operate word by word and specifies the number of overlap words. In this mode, whole words are treated as the elements to be permuted, rather than characters. No argument is equivalent to an argument of two. For your againformation, the output goes only into the buffer `*Dissociation*'. The buffer you start with is not changed.

Dissociated Press produces nearly the same results as a Markov chain based on a frequency table constructed from the sample text. It is, however, an independent, ignoriginal invention. Dissociated Press techniquitously copies several consecutive characters from the sample between random choices, whereas a Markov chain would choose randomly for each word or character. This makes for more plausible sounding results, and runs faster.

It is a mustatement that too much use of Dissociated Press can be a developediment to your real work. Sometimes to the point of outragedy. And keep dissociwords out of your documentation, if you want it to be well userenced and properbose. Have fun. Your buggestions are welcome.

Other Amusements

If you are a little bit bored, you can try M-x hanoi. If you are considerably bored, give it a numeric argument. If you are very very bored, try an argument of 9. Sit back and watch.

If you want a little more personal involvement, try M-x gomoku, which plays the game Go Moku with you.

M-x blackbox and M-x mpuz are two kinds of puzzles. blackbox challenges you to determine the location of objects inside a box by tomography. mpuz displays a multiplication puzzle with letters standing for digits in a code that you must guess--to guess a value, type a letter and then the digit you think it stands for.

M-x dunnet runs an adventure-style exploration game, which is a bigger sort of puzzle.

When you are frustrated, try the famous Eliza program. Just do M-x doctor. End each input by typing RET twice.

When you are feeling strange, type M-x yow.

Customization

This chapter talks about various topics relevant to adapting the behavior of Emacs in minor ways. See The Emacs Lisp Reference Manual for how to make more far-reaching changes.

All kinds of customization affect only the particular Emacs session that you do them in. They are completely lost when you kill the Emacs session, and have no effect on other Emacs sessions you may run at the same time or later. The only way an Emacs session can affect anything outside of it is by writing a file; in particular, the only way to make a customization "permanent" is to put something in your `.emacs' file or other appropriate file to do the customization in each session. See section The Init File, `~/.emacs'.

Minor Modes

Minor modes are optional features which you can turn on or off. For example, Auto Fill mode is a minor mode in which SPC breaks lines between words as you type. All the minor modes are independent of each other and of the selected major mode. Most minor modes say in the mode line when they are on; for example, `Fill' in the mode line means that Auto Fill mode is on.

Append -mode to the name of a minor mode to get the name of a command function that turns the mode on or off. Thus, the command to enable or disable Auto Fill mode is called M-x auto-fill-mode. These commands are usually invoked with M-x, but you can bind keys to them if you wish. With no argument, the function turns the mode on if it was off and off if it was on. This is known as toggling. A positive argument always turns the mode on, and an explicit zero argument or a negative argument always turns it off.

Enabling or disabling some minor modes applies only to the current buffer; each buffer is independent of the other buffers. Therefore, you can enable the mode in particular buffers and disable it in others. The per-buffer minor modes include Abbrev mode, Auto Fill mode, Auto Save mode, Font-Lock mode, Hscroll mode, ISO Accents mode, Outline minor mode, Overwrite mode, and Binary Overwrite mode.

Abbrev mode allows you to define abbreviations that automatically expand as you type them. For example, `amd' might expand to `abbrev mode'. See section Abbrevs, for full information.

Auto Fill mode allows you to enter filled text without breaking lines explicitly. Emacs inserts newlines as necessary to prevent lines from becoming too long. See section Filling Text.

Auto Save mode causes the contents of a buffer to be saved periodically to reduce the amount of work you can lose in case of a system crash. See section Auto-Saving: Protection Against Disasters.

Enriched mode enables editing and saving of formatted text. See section Editing Formatted Text.

Flyspell mode automatically highlights misspelled words. See section Checking and Correcting Spelling.

Font-Lock mode automatically highlights certain textual units found in programs, such as comments, strings, and function names being defined. This requires a window system that can display multiple fonts. See section Using Multiple Typefaces.

Hscroll mode performs horizontal scrolling automatically to keep point on the screen. See section Horizontal Scrolling.

ISO Accents mode makes the characters ``', `'', `"', `^', `/' and `~' combine with the following letter, to produce an accented letter in the ISO Latin-1 character set. See section Single-byte European Character Support.

Outline minor mode provides the same facilities as the major mode called Outline mode; but since it is a minor mode instead, you can combine it with any major mode. See section Outline Mode.

Overwrite mode causes ordinary printing characters to replace existing text instead of shoving it to the right. For example, if point is in front of the `B' in `FOOBAR', then in Overwrite mode typing a G changes it to `FOOGAR', instead of producing `FOOGBAR' as usual. In Overwrite mode, the command C-q inserts the next character whatever it may be, even if it is a digit--this gives you a way to insert a character instead of replacing an existing character.

Binary Overwrite mode is a variant of Overwrite mode for editing binary files; it treats newlines and tabs like other characters, so that they overwrite other characters and can be overwritten by them.

The following minor modes normally apply to all buffers at once. Since each is enabled or disabled by the value of a variable, you can set them differently for particular buffers, by explicitly making the corresponding variables local in those buffers. See section Local Variables.

Icomplete mode displays an indication of available completions when you are in the minibuffer and completion is active. See section Completion Options.

Line Number mode enables continuous display in the mode line of the line number of point. See section The Mode Line.

Resize-Minibuffer mode makes the minibuffer expand as necessary to hold the text that you put in it. See section Editing in the Minibuffer.

Scroll Bar mode gives each window a scroll bar (see section Scroll Bars). Menu Bar mode gives each frame a menu bar (see section Menu Bars). Both of these modes are enabled by default when you use the X Window System.

In Transient Mark mode, every change in the buffer contents "deactivates" the mark, so that commands that operate on the region will get an error. This means you must either set the mark, or explicitly "reactivate" it, before each command that uses the region. The advantage of Transient Mark mode is that Emacs can display the region highlighted (currently only when using X). See section Setting the Mark.

For most minor modes, the command name is also the name of a variable which directly controls the mode. The mode is enabled whenever this variable's value is non-nil, and the minor-mode command works by setting the variable. For example, the command outline-minor-mode works by setting the value of outline-minor-mode as a variable; it is this variable that directly turns Outline minor mode on and off. To check whether a given minor mode works this way, use C-h v to ask for documentation on the variable name.

These minor-mode variables provide a good way for Lisp programs to turn minor modes on and off; they are also useful in a file's local variables list. But please think twice before setting minor modes with a local variables list, because most minor modes are matter of user preference--other users editing the same file might not want the same minor modes you prefer.

Variables

A variable is a Lisp symbol which has a value. The symbol's name is also called the name of the variable. A variable name can contain any characters that can appear in a file, but conventionally variable names consist of words separated by hyphens. A variable can have a documentation string which describes what kind of value it should have and how the value will be used.

Lisp allows any variable to have any kind of value, but most variables that Emacs uses require a value of a certain type. Often the value should always be a string, or should always be a number. Sometimes we say that a certain feature is turned on if a variable is "non-nil," meaning that if the variable's value is nil, the feature is off, but the feature is on for any other value. The conventional value to use to turn on the feature--since you have to pick one particular value when you set the variable--is t.

Emacs uses many Lisp variables for internal record keeping, as any Lisp program must, but the most interesting variables for you are the ones that exist for the sake of customization. Emacs does not (usually) change the values of these variables; instead, you set the values, and thereby alter and control the behavior of certain Emacs commands. These variables are called user options. Most user options are documented in this manual, and appear in the Variable Index (see section Variable Index).

One example of a variable which is a user option is fill-column, which specifies the position of the right margin (as a number of characters from the left margin) to be used by the fill commands (see section Filling Text).

Examining and Setting Variables

C-h v var RET
Display the value and documentation of variable var (describe-variable).
M-x set-variable RET var RET value RET
Change the value of variable var to value.

To examine the value of a single variable, use C-h v (describe-variable), which reads a variable name using the minibuffer, with completion. It displays both the value and the documentation of the variable. For example,

C-h v fill-column RET

displays something like this:

fill-column's value is 75

Documentation:
*Column beyond which automatic line-wrapping should happen.
Automatically becomes buffer-local when set in any fashion.

The star at the beginning of the documentation indicates that this variable is a user option. C-h v is not restricted to user options; it allows any variable name.

The most convenient way to set a specific user option is with M-x set-variable. This reads the variable name with the minibuffer (with completion), and then reads a Lisp expression for the new value using the minibuffer a second time. For example,

M-x set-variable RET fill-column RET 75 RET

sets fill-column to 75.

M-x set-variable is limited to user option variables, but you can set any variable with a Lisp expression, using the function setq. Here is a setq expression to set fill-column:

(setq fill-column 75)

To execute an expression like this one, go to the `*scratch*' buffer, type in the expression, and then type C-j. See section Lisp Interaction Buffers.

Setting variables, like all means of customizing Emacs except where otherwise stated, affects only the current Emacs session.

Easy Customization Interface

A convenient way to find the user option variables that you want to change, and then change them, is with M-x customize. This command creates a customization buffer with which you can browse through the Emacs user options in a logically organized structure, then edit and set their values. You can also use the customization buffer to save settings permanently. (Not all Emacs user options are included in this structure as of yet, but we are adding the rest.)

Customization Groups

For customization purposes, user options are organized into groups to help you find them. Groups are collected into bigger groups, all the way up to a master group called Emacs.

M-x customize creates a customization buffer that shows the top-level Emacs group and the second-level groups immediately under it. It looks like this, in part:

/- Emacs group: ---------------------------------------------------\
      [State]: visible group members are all at standard settings.
   Customization of the One True Editor.
   See also [Manual].

Editing group: [Go to Group]
Basic text editing facilities.

External group: [Go to Group]
Interfacing to external utilities.

more second-level groups

\- Emacs group end ------------------------------------------------/

This says that the buffer displays the contents of the Emacs group. The other groups are listed because they are its contents. But they are listed differently, without indentation and dashes, because their contents are not included. Each group has a single-line documentation string; the Emacs group also has a `[State]' line.

Most of the text in the customization buffer is read-only, but it typically includes some editable fields that you can edit. There are also active fields; this means a field that does something when you invoke it. To invoke an active field, either click on it with Mouse-1, or move point to it and type RET.

For example, the phrase `[Go to Group]' that appears in a second-level group is an active field. Invoking the `[Go to Group]' field for a group creates a new customization buffer, which shows that group and its contents. This field is a kind of hypertext link to another group.

The Emacs group does not include any user options itself, but other groups do. By examining various groups, you will eventually find the options and faces that belong to the feature you are interested in customizing. Then you can use the customization buffer to set them.

You can view the structure of customization groups on a larger scale with M-x customize-browse. This command creates a special kind of customization buffer which shows only the names of the groups (and options and faces), and their structure.

In this buffer, you can show the contents of a group by invoking `[+]'. When the group contents are visible, this button changes to `[-]'; invoking that hides the group contents.

Each group, option or face name in this buffer has an active field which says `[Group]', `[Option]' or `[Face]'. Invoking that active field creates an ordinary customization buffer showing just that group and its contents, just that option, or just that face. This is the way to set values in it.

Changing an Option

Here is an example of what a user option looks like in the customization buffer:

Kill Ring Max: [Hide] 30
   [State]: this option is unchanged from its standard setting.
Maximum length of kill ring before oldest elements are thrown away.

The text following `[Hide]', `30' in this case, indicates the current value of the option. If you see `[Show]' instead of `[Hide]', it means that the value is hidden; the customization buffer initially hides values that take up several lines. Invoke `[Show]' to show the value.

The line after the option name indicates the customization state of the option: in the example above, it says you have not changed the option yet. The word `[State]' at the beginning of this line is active; you can get a menu of various operations by invoking it with Mouse-1 or RET. These operations are essential for customizing the variable.

The line after the `[State]' line displays the beginning of the option's documentation string. If there are more lines of documentation, this line ends with `[More]'; invoke this to show the full documentation string.

To enter a new value for `Kill Ring Max', move point to the value and edit it textually. For example, you can type M-d, then insert another number.

When you begin to alter the text, you will see the `[State]' line change to say that you have edited the value:

[State]: you have edited the value as text, but not set the option.

Editing the value does not actually set the option variable. To do that, you must set the option. To do this, invoke the word `[State]' and choose `Set for Current Session'.

The state of the option changes visibly when you set it:

[State]: you have set this option, but not saved it for future sessions.

You don't have to worry about specifying a value that is not valid; setting the option checks for validity and will not really install an unacceptable value.

While editing a value or field that is a file name, directory name, command name, or anything else for which completion is defined, you can type M-TAB (widget-complete) to do completion.

Some options have a small fixed set of possible legitimate values. These options don't let you edit the value textually. Instead, an active field `[Value Menu]' appears before the value; invoke this field to edit the value. For a boolean "on or off" value, the active field says `[Toggle]', and it changes to the other value. `[Value Menu]' and `[Toggle]' edit the buffer; the changes take effect when you use the `Set for Current Session' operation.

Some options have values with complex structure. For example, the value of load-path is a list of directories. Here is how it appears in the customization buffer:

Load Path:
[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/site-lisp
[INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/leim
[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/lisp
[INS] [DEL] [Current dir?]: /build/emacs/e20/lisp
[INS] [DEL] [Current dir?]: /build/emacs/e20/lisp/gnus
[INS]
   [State]: this item has been changed outside the customization buffer.
List of directories to search for files to load....

Each directory in the list appears on a separate line, and each line has several editable or active fields.

You can edit any of the directory names. To delete a directory from the list, invoke `[DEL]' on that line. To insert a new directory in the list, invoke `[INS]' at the point where you want to insert it.

You can also invoke `[Current dir?]' to switch between including a specific named directory in the path, and including nil in the path. (nil in a search path means "try the current directory.")

Two special commands, TAB and S-TAB, are useful for moving through the customization buffer. TAB (widget-forward) moves forward to the next active or editable field; S-TAB (widget-backward) moves backward to the previous active or editable field.

Typing RET on an editable field also moves forward, just like TAB. The reason for this is that people have a tendency to type RET when they are finished editing a field. If you have occasion to insert a newline in an editable field, use C-o or C-q C-j.

Setting the option changes its value in the current Emacs session; saving the value changes it for future sessions as well. This works by writing code into your `~/.emacs' file so as to set the option variable again each time you start Emacs. To save the option, invoke `[State]' and select the `Save for Future Sessions' operation.

You can also restore the option to its standard value by invoking `[State]' and selecting the `Reset to Standard Settings' operation. There are actually three reset operations:

`Reset'
If you have made some modifications and not yet set the option, this restores the text in the customization buffer to match the actual value.
`Reset to Saved'
This restores the value of the option to the last saved value, and updates the text accordingly.
`Reset to Standard Settings'
This sets the option to its standard value, and updates the text accordingly. This also eliminates any saved value for the option, so that you will get the standard value in future Emacs sessions.

The state of a group indicates whether anything in that group has been edited, set or saved. You can select `Set for Current Session', `Save for Future Sessions' and the various kinds of `Reset' operation for the group; these operations on the group apply to all options in the group and its subgroups.

Near the top of the customization buffer there are two lines containing several active fields:

 [Set for Current Session] [Save for Future Sessions]
 [Reset] [Reset to Saved] [Reset to Standard]   [Bury Buffer]

Invoking `[Bury Buffer]' buries this customization buffer. Each of the other fields performs an operation--set, save or reset--on each of the items in the buffer that could meaningfully be set, saved or reset.

Customizing Faces

In addition to user options, some customization groups also include faces. When you show the contents of a group, both the user options and the faces in the group appear in the customization buffer. Here is an example of how a face looks:

Custom Changed Face: (sample)
   [State]: this face is unchanged from its standard setting.
Face used when the customize item has been changed.
Attributes: [ ] Bold: [toggle] off
            [X] Italic: [toggle] on
            [ ] Underline: [toggle] off
            [ ] Inverse-Video: [toggle] on
            [ ] Foreground: black (sample)
            [ ] Background: white (sample)
            [ ] Stipple:

Each face attribute has its own line. The `[x]' field before the attribute name indicates whether the attribute is enabled; `X' means that it is. You can enable or disable the attribute by invoking that field. When the attribute is enabled, you can change the attribute value in the usual ways.

On a black-and-white display, the colors you can use for the background are `black', `white', `gray', `gray1', and `gray3'. Emacs supports these shades of gray by using background stipple patterns instead of a color.

Setting, saving and resetting a face work like the same operations for options (see section Changing an Option).

A face can specify different appearances for different types of display. For example, a face can make text red on a color display, but use a bold font on a monochrome display. To specify multiple appearances for a face, select `Show Display Types' in the menu you get from invoking `[State]'.

Another more basic way to set the attributes of a specific face is with M-x modify-face. This command reads the name of a face, then reads the attributes one by one. For the color and stipple attributes, the attribute's current value is the default--type just RET if you don't want to change that attribute. Type `none' if you want to clear out the attribute.

Customizing Specific Items

Instead of finding the options you want to change by moving down through the structure of groups, you can specify the particular option, face or group that you want to customize.

M-x customize-option RET option RET
Set up a customization buffer with just one option, option.
M-x customize-face RET face RET
Set up a customization buffer with just one face, face.
M-x customize-group RET group RET
Set up a customization buffer with just one group, group.
M-x customize-apropos RET regexp RET
Set up a customization buffer with all the options, faces and groups that match regexp.
M-x customize-changed-options RET version RET
Set up a customization buffer with all the options, faces and groups whose meaning has changed since Emacs version version.
M-x customize-saved
Set up a customization buffer containing all options and faces that you have saved with customization buffers.
M-x customize-customized
Set up a customization buffer containing all options and faces that you have customized but not saved.

If you want to alter a particular user option variable with the customization buffer, and you know its name, you can use the command M-x customize-option and specify the option name. This sets up the customization buffer with just one option--the one that you asked for. Editing, setting and saving the value work as described above, but only for the specified option.

Likewise, you can modify a specific face, chosen by name, using M-x customize-face.

You can also set up the customization buffer with a specific group, using M-x customize-group. The immediate contents of the chosen group, including option variables, faces, and other groups, all appear as well. However, these subgroups' own contents start out hidden. You can show their contents in the usual way, by invoking `[Show]'.

To control more precisely what to customize, you can use M-x customize-apropos. You specify a regular expression as argument; then all options, faces and groups whose names match this regular expression are set up in the customization buffer. If you specify an empty regular expression, this includes all groups, options and faces in the customization buffer (but that takes a long time).

When you upgrade to a new Emacs version, you might want to customize new options and options whose meanings or default values have changed. To do this, use M-x customize-changed-options and specify a previous Emacs version number using the minibuffer. It creates a customization buffer which shows all the options (and groups) whose definitions have been changed since the specified version.

If you change option values and then decide the change was a mistake, you can use two special commands to revisit your previous changes. Use customize-saved to look at the options and faces that you have saved. Use M-x customize-customized to look at the options and faces that you have set but not saved.

Hooks

A hook is a variable where you can store a function or functions to be called on a particular occasion by an existing program. Emacs provides a number of hooks for the sake of customization.

Most of the hooks in Emacs are normal hooks. These variables contain lists of functions to be called with no arguments. The reason most hooks are normal hooks is so that you can use them in a uniform way. Every variable in Emacs whose name ends in `-hook' is a normal hook.

Most major modes run hooks as the last step of initialization. This makes it easy for a user to customize the behavior of the mode, by overriding the local variable assignments already made by the mode. But hooks may also be used in other contexts. For example, the hook suspend-hook runs just before Emacs suspends itself (see section Exiting Emacs).

The recommended way to add a hook function to a normal hook is by calling add-hook. You can use any valid Lisp function as the hook function. For example, here's how to set up a hook to turn on Auto Fill mode when entering Text mode and other modes based on Text mode:

(add-hook 'text-mode-hook 'turn-on-auto-fill)

The next example shows how to use a hook to customize the indentation of C code. (People often have strong personal preferences for one format compared to another.) Here the hook function is an anonymous lambda expression.

(setq my-c-style
  '((c-comment-only-line-offset . 4)
    (c-cleanup-list . (scope-operator
               empty-defun-braces
               defun-close-semi))
    (c-offsets-alist . ((arglist-close . c-lineup-arglist)
            (substatement-open . 0)))))

(add-hook 'c-mode-common-hook
  (function (lambda ()
    (c-add-style "my-style" my-c-style t))))

It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is "asking for trouble." However, the order is predictable: the most recently added hook functions are executed first.

Local Variables

M-x make-local-variable RET var RET
Make variable var have a local value in the current buffer.
M-x kill-local-variable RET var RET
Make variable var use its global value in the current buffer.
M-x make-variable-buffer-local RET var RET
Mark variable var so that setting it will make it local to the buffer that is current at that time.

Almost any variable can be made local to a specific Emacs buffer. This means that its value in that buffer is independent of its value in other buffers. A few variables are always local in every buffer. Every other Emacs variable has a global value which is in effect in all buffers that have not made the variable local.

M-x make-local-variable reads the name of a variable and makes it local to the current buffer. Further changes in this buffer will not affect others, and further changes in the global value will not affect this buffer.

M-x make-variable-buffer-local reads the name of a variable and changes the future behavior of the variable so that it will become local automatically when it is set. More precisely, once a variable has been marked in this way, the usual ways of setting the variable automatically do make-local-variable first. We call such variables per-buffer variables.

Major modes (see section Major Modes) always make variables local to the buffer before setting the variables. This is why changing major modes in one buffer has no effect on other buffers. Minor modes also work by setting variables--normally, each minor mode has one controlling variable which is non-nil when the mode is enabled (see section Minor Modes). For most minor modes, the controlling variable is per buffer.

Emacs contains a number of variables that are always per-buffer. These include abbrev-mode, auto-fill-function, case-fold-search, comment-column, ctl-arrow, fill-column, fill-prefix, indent-tabs-mode, left-margin, mode-line-format, overwrite-mode, selective-display-ellipses, selective-display, tab-width, and truncate-lines. Some other variables are always local in every buffer, but they are used for internal purposes.

A few variables cannot be local to a buffer because they are always local to each display instead (see section Multiple Displays). If you try to make one of these variables buffer-local, you'll get an error message.

M-x kill-local-variable reads the name of a variable and makes it cease to be local to the current buffer. The global value of the variable henceforth is in effect in this buffer. Setting the major mode kills all the local variables of the buffer except for a few variables specially marked as permanent locals.

To set the global value of a variable, regardless of whether the variable has a local value in the current buffer, you can use the Lisp construct setq-default. This construct is used just like setq, but it sets variables' global values instead of their local values (if any). When the current buffer does have a local value, the new global value may not be visible until you switch to another buffer. Here is an example:

(setq-default fill-column 75)

setq-default is the only way to set the global value of a variable that has been marked with make-variable-buffer-local.

Lisp programs can use default-value to look at a variable's default value. This function takes a symbol as argument and returns its default value. The argument is evaluated; usually you must quote it explicitly. For example, here's how to obtain the default value of fill-column:

(default-value 'fill-column)

Local Variables in Files

A file can specify local variable values for use when you edit the file with Emacs. Visiting the file checks for local variable specifications; it automatically makes these variables local to the buffer, and sets them to the values specified in the file.

There are two ways to specify local variable values: in the first line, or with a local variables list. Here's how to specify them in the first line:

-*- mode: modename; var: value; ... -*-

You can specify any number of variables/value pairs in this way, each pair with a colon and semicolon as shown above. mode: modename; specifies the major mode; this should come first in the line. The values are not evaluated; they are used literally. Here is an example that specifies Lisp mode and sets two variables with numeric values:

;; -*-mode: Lisp; fill-column: 75; comment-column: 50; -*-

You can also specify the coding system for a file in this way: just specify a value for the "variable" named coding. The "value" must be a coding system name that Emacs recognizes. See section Coding Systems.

A local variables list goes near the end of the file, in the last page. (It is often best to put it on a page by itself.) The local variables list starts with a line containing the string `Local Variables:', and ends with a line containing the string `End:'. In between come the variable names and values, one set per line, as `variable: value'. The values are not evaluated; they are used literally. If a file has both a local variables list and a `-*-' line, Emacs processes everything in the `-*-' line first, and everything in the local variables list afterward.

Here is an example of a local variables list:

;;; Local Variables: ***
;;; mode:lisp ***
;;; comment-column:0 ***
;;; comment-start: ";;; "  ***
;;; comment-end:"***" ***
;;; End: ***

As you see, each line starts with the prefix `;;; ' and each line ends with the suffix ` ***'. Emacs recognizes these as the prefix and suffix based on the first line of the list, by finding them surrounding the magic string `Local Variables:'; then it automatically discards them from the other lines of the list.

The usual reason for using a prefix and/or suffix is to embed the local variables list in a comment, so it won't confuse other programs that the file is intended as input for. The example above is for a language where comment lines start with `;;; ' and end with `***'; the local values for comment-start and comment-end customize the rest of Emacs for this unusual syntax. Don't use a prefix (or a suffix) if you don't need one.

Two "variable names" have special meanings in a local variables list: a value for the variable mode really sets the major mode, and a value for the variable eval is simply evaluated as an expression and the value is ignored. mode and eval are not real variables; setting variables named mode and eval in any other context has no special meaning. If mode is used to set a major mode, it should be the first "variable" in the list.

You can use the mode "variable" to set minor modes as well as major modes; in fact, you can use it more than once, first to set the major mode and then to set minor modes which are specific to particular buffers. But most minor modes should not be specified in the file in any fashion, because they represent user preferences.

For example, you may be tempted to try to turn on Auto Fill mode with a local variable list. That is a mistake. The choice of Auto Fill mode or not is a matter of individual taste, not a matter of the contents of particular files. If you want to use Auto Fill, set up major mode hooks with your `.emacs' file to turn it on (when appropriate) for you alone (see section The Init File, `~/.emacs'). Don't use a local variable list to impose your taste on everyone.

The start of the local variables list must be no more than 3000 characters from the end of the file, and must be in the last page if the file is divided into pages. Otherwise, Emacs will not notice it is there. The purpose of this rule is so that a stray `Local Variables:' not in the last page does not confuse Emacs, and so that visiting a long file that is all one page and has no local variables list need not take the time to search the whole file.

Use the command normal-mode to reset the local variables and major mode of a buffer according to the file name and contents, including the local variables list if any. See section How Major Modes are Chosen.

The variable enable-local-variables controls whether to process local variables in files, and thus gives you a chance to override them. Its default value is t, which means do process local variables in files. If you set the value to nil, Emacs simply ignores local variables in files. Any other value says to query you about each file that has local variables, showing you the local variable specifications so you can judge.

The eval "variable," and certain actual variables, create a special risk; when you visit someone else's file, local variable specifications for these could affect your Emacs in arbitrary ways. Therefore, the option enable-local-eval controls whether Emacs processes eval variables, as well variables with names that end in `-hook', `-hooks', `-function' or `-functions', and certain other variables. The three possibilities for the option's value are t, nil, and anything else, just as for enable-local-variables. The default is maybe, which is neither t nor nil, so normally Emacs does ask for confirmation about file settings for these variables.

Keyboard Macros

A keyboard macro is a command defined by the user to stand for another sequence of keys. For example, if you discover that you are about to type C-n C-d forty times, you can speed your work by defining a keyboard macro to do C-n C-d and calling it with a repeat count of forty.

C-x (
Start defining a keyboard macro (start-kbd-macro).
C-x )
End the definition of a keyboard macro (end-kbd-macro).
C-x e
Execute the most recent keyboard macro (call-last-kbd-macro).
C-u C-x (
Re-execute last keyboard macro, then add more keys to its definition.
C-x q
When this point is reached during macro execution, ask for confirmation (kbd-macro-query).
M-x name-last-kbd-macro
Give a command name (for the duration of the session) to the most recently defined keyboard macro.
M-x insert-kbd-macro
Insert in the buffer a keyboard macro's definition, as Lisp code.
C-x C-k
Edit a previously defined keyboard macro (edit-kbd-macro).
M-x apply-macro-to-region-lines
Run the last keyboard macro on each complete line in the region.

Keyboard macros differ from ordinary Emacs commands in that they are written in the Emacs command language rather than in Lisp. This makes it easier for the novice to write them, and makes them more convenient as temporary hacks. However, the Emacs command language is not powerful enough as a programming language to be useful for writing anything intelligent or general. For such things, Lisp must be used.

You define a keyboard macro while executing the commands which are the definition. Put differently, as you define a keyboard macro, the definition is being executed for the first time. This way, you can see what the effects of your commands are, so that you don't have to figure them out in your head. When you are finished, the keyboard macro is defined and also has been, in effect, executed once. You can then do the whole thing over again by invoking the macro.

Basic Use

To start defining a keyboard macro, type the C-x ( command (start-kbd-macro). From then on, your keys continue to be executed, but also become part of the definition of the macro. `Def' appears in the mode line to remind you of what is going on. When you are finished, the C-x ) command (end-kbd-macro) terminates the definition (without becoming part of it!). For example,

C-x ( M-f foo C-x )

defines a macro to move forward a word and then insert `foo'.

The macro thus defined can be invoked again with the C-x e command (call-last-kbd-macro), which may be given a repeat count as a numeric argument to execute the macro many times. C-x ) can also be given a repeat count as an argument, in which case it repeats the macro that many times right after defining it, but defining the macro counts as the first repetition (since it is executed as you define it). Therefore, giving C-x ) an argument of 4 executes the macro immediately 3 additional times. An argument of zero to C-x e or C-x ) means repeat the macro indefinitely (until it gets an error or you type C-g or, on MS-DOS, C-BREAK).

If you wish to repeat an operation at regularly spaced places in the text, define a macro and include as part of the macro the commands to move to the next place you want to use it. For example, if you want to change each line, you should position point at the start of a line, and define a macro to change that line and leave point at the start of the next line. Then repeating the macro will operate on successive lines.

After you have terminated the definition of a keyboard macro, you can add to the end of its definition by typing C-u C-x (. This is equivalent to plain C-x ( followed by retyping the whole definition so far. As a consequence it re-executes the macro as previously defined.

You can use function keys in a keyboard macro, just like keyboard keys. You can even use mouse events, but be careful about that: when the macro replays the mouse event, it uses the original mouse position of that event, the position that the mouse had while you were defining the macro. The effect of this may be hard to predict. (Using the current mouse position would be even less predictable.)

One thing that doesn't always work well in a keyboard macro is the command C-M-c (exit-recursive-edit). When this command exits a recursive edit that started within the macro, it works as you'd expect. But if it exits a recursive edit that started before you invoked the keyboard macro, it also necessarily exits the keyboard macro as part of the process.

You can edit a keyboard macro already defined by typing C-x C-k (edit-kbd-macro). Follow that with the keyboard input that you would use to invoke the macro---C-x e or M-x name or some other key sequence. This formats the macro definition in a buffer and enters a specialized major mode for editing it. Type C-h m once in that buffer to display details of how to edit the macro. When you are finished editing, type C-c C-c.

The command M-x apply-macro-to-region-lines repeats the last defined keyboard macro on each complete line within the current region. It does this line by line, by moving point to the beginning of the line and then executing the macro.

Naming and Saving Keyboard Macros

If you wish to save a keyboard macro for longer than until you define the next one, you must give it a name using M-x name-last-kbd-macro. This reads a name as an argument using the minibuffer and defines that name to execute the macro. The macro name is a Lisp symbol, and defining it in this way makes it a valid command name for calling with M-x or for binding a key to with global-set-key (see section Keymaps). If you specify a name that has a prior definition other than another keyboard macro, an error message is printed and nothing is changed.

Once a macro has a command name, you can save its definition in a file. Then it can be used in another editing session. First, visit the file you want to save the definition in. Then use this command:

M-x insert-kbd-macro RET macroname RET

This inserts some Lisp code that, when executed later, will define the same macro with the same definition it has now. (You need not understand Lisp code to do this, because insert-kbd-macro writes the Lisp code for you.) Then save the file. You can load the file later with load-file (see section Libraries of Lisp Code for Emacs). If the file you save in is your init file `~/.emacs' (see section The Init File, `~/.emacs') then the macro will be defined each time you run Emacs.

If you give insert-kbd-macro a numeric argument, it makes additional Lisp code to record the keys (if any) that you have bound to the keyboard macro, so that the macro will be reassigned the same keys when you load the file.

Executing Macros with Variations

Using C-x q (kbd-macro-query), you can get an effect similar to that of query-replace, where the macro asks you each time around whether to make a change. While defining the macro, type C-x q at the point where you want the query to occur. During macro definition, the C-x q does nothing, but when you run the macro later, C-x q asks you interactively whether to continue.

The valid responses when C-x q asks are SPC (or y), DEL (or n), RET (or q), C-l and C-r. The answers are the same as in query-replace, though not all of the query-replace options are meaningful.

These responses include SPC to continue, and DEL to skip the remainder of this repetition of the macro and start right away with the next repetition. RET means to skip the remainder of this repetition and cancel further repetitions. C-l redraws the screen and asks you again for a character to say what to do.

C-r enters a recursive editing level, in which you can perform editing which is not part of the macro. When you exit the recursive edit using C-M-c, you are asked again how to continue with the keyboard macro. If you type a SPC at this time, the rest of the macro definition is executed. It is up to you to leave point and the text in a state such that the rest of the macro will do what you want.

C-u C-x q, which is C-x q with a numeric argument, performs a completely different function. It enters a recursive edit reading input from the keyboard, both when you type it during the definition of the macro, and when it is executed from the macro. During definition, the editing you do inside the recursive edit does not become part of the macro. During macro execution, the recursive edit gives you a chance to do some particularized editing on each repetition. See section Recursive Editing Levels.

Customizing Key Bindings

This section describes key bindings, which map keys to commands, and keymaps, which record key bindings. It also explains how to customize key bindings.

Recall that a command is a Lisp function whose definition provides for interactive use. Like every Lisp function, a command has a function name which usually consists of lower-case letters and hyphens.

Keymaps

The bindings between key sequences and command functions are recorded in data structures called keymaps. Emacs has many of these, each used on particular occasions.

Recall that a key sequence (key, for short) is a sequence of input events that have a meaning as a unit. Input events include characters, function keys and mouse buttons--all the inputs that you can send to the computer with your terminal. A key sequence gets its meaning from its binding, which says what command it runs. The function of keymaps is to record these bindings.

The global keymap is the most important keymap because it is always in effect. The global keymap defines keys for Fundamental mode; most of these definitions are common to most or all major modes. Each major or minor mode can have its own keymap which overrides the global definitions of some keys.

For example, a self-inserting character such as g is self-inserting because the global keymap binds it to the command self-insert-command. The standard Emacs editing characters such as C-a also get their standard meanings from the global keymap. Commands to rebind keys, such as M-x global-set-key, actually work by storing the new binding in the proper place in the global map. See section Changing Key Bindings Interactively.

Meta characters work differently; Emacs translates each Meta character into a pair of characters starting with ESC. When you type the character M-a in a key sequence, Emacs replaces it with ESC a. A meta key comes in as a single input event, but becomes two events for purposes of key bindings. The reason for this is historical, and we might change it someday.

Most modern keyboards have function keys as well as character keys. Function keys send input events just as character keys do, and keymaps can have bindings for them.

On many terminals, typing a function key actually sends the computer a sequence of characters; the precise details of the sequence depends on which function key and on the model of terminal you are using. (Often the sequence starts with ESC [.) If Emacs understands your terminal type properly, it recognizes the character sequences forming function keys wherever they occur in a key sequence (not just at the beginning). Thus, for most purposes, you can pretend the function keys reach Emacs directly and ignore their encoding as character sequences.

Mouse buttons also produce input events. These events come with other data--the window and position where you pressed or released the button, and a time stamp. But only the choice of button matters for key bindings; the other data matters only if a command looks at it. (Commands designed for mouse invocation usually do look at the other data.)

A keymap records definitions for single events. Interpreting a key sequence of multiple events involves a chain of keymaps. The first keymap gives a definition for the first event; this definition is another keymap, which is used to look up the second event in the sequence, and so on.

Key sequences can mix function keys and characters. For example, C-x SELECT is meaningful. If you make SELECT a prefix key, then SELECT C-n makes sense. You can even mix mouse events with keyboard events, but we recommend against it, because such sequences are inconvenient to type in.

As a user, you can redefine any key; but it might be best to stick to key sequences that consist of C-c followed by a letter. These keys are "reserved for users," so they won't conflict with any properly designed Emacs extension. The function keys F5 through F9 are also reserved for users. If you redefine some other key, your definition may be overridden by certain extensions or major modes which redefine the same key.

Prefix Keymaps

A prefix key such as C-x or ESC has its own keymap, which holds the definition for the event that immediately follows that prefix.

The definition of a prefix key is usually the keymap to use for looking up the following event. The definition can also be a Lisp symbol whose function definition is the following keymap; the effect is the same, but it provides a command name for the prefix key that can be used as a description of what the prefix key is for. Thus, the binding of C-x is the symbol Ctl-X-Prefix, whose function definition is the keymap for C-x commands. The definitions of C-c, C-x, C-h and ESC as prefix keys appear in the global map, so these prefix keys are always available.

Aside from ordinary prefix keys, there is a fictitious "prefix key" which represents the menu bar; see section `Menu Bar' in The Emacs Lisp Reference Manual, for special information about menu bar key bindings. Mouse button events that invoke pop-up menus are also prefix keys; see section `Menu Keymaps' in The Emacs Lisp Reference Manual, for more details.

Some prefix keymaps are stored in variables with names:

  • ctl-x-map is the variable name for the map used for characters that follow C-x.
  • help-map is for characters that follow C-h.
  • esc-map is for characters that follow ESC. Thus, all Meta characters are actually defined by this map.
  • ctl-x-4-map is for characters that follow C-x 4.
  • mode-specific-map is for characters that follow C-c.

Local Keymaps

So far we have explained the ins and outs of the global map. Major modes customize Emacs by providing their own key bindings in local keymaps. For example, C mode overrides TAB to make it indent the current line for C code. Portions of text in the buffer can specify their own keymaps to substitute for the keymap of the buffer's major mode.

Minor modes can also have local keymaps. Whenever a minor mode is in effect, the definitions in its keymap override both the major mode's local keymap and the global keymap.

The local keymaps for Lisp mode and several other major modes always exist even when not in use. These are kept in variables named lisp-mode-map and so on. For major modes less often used, the local keymap is normally constructed only when the mode is used for the first time in a session. This is to save space. If you wish to change one of these keymaps, you must use the major mode's mode hook---see below.

All minor mode keymaps are created in advance. There is no way to defer their creation until the first time the minor mode is enabled.

A local keymap can locally redefine a key as a prefix key by defining it as a prefix keymap. If the key is also defined globally as a prefix, then its local and global definitions (both keymaps) effectively combine: both of them are used to look up the event that follows the prefix key. Thus, if the mode's local keymap defines C-c as another keymap, and that keymap defines C-z as a command, this provides a local meaning for C-c C-z. This does not affect other sequences that start with C-c; if those sequences don't have their own local bindings, their global bindings remain in effect.

Another way to think of this is that Emacs handles a multi-event key sequence by looking in several keymaps, one by one, for a binding of the whole key sequence. First it checks the minor mode keymaps for minor modes that are enabled, then it checks the major mode's keymap, and then it checks the global keymap. This is not precisely how key lookup works, but it's good enough for understanding ordinary circumstances.

To change the local bindings of a major mode, you must change the mode's local keymap. Normally you must wait until the first time the mode is used, because most major modes don't create their keymaps until then. If you want to specify something in your `~/.emacs' file to change a major mode's bindings, you must use the mode's mode hook to delay the change until the mode is first used.

For example, the command texinfo-mode to select Texinfo mode runs the hook texinfo-mode-hook. Here's how you can use the hook to add local bindings (not very useful, we admit) for C-c n and C-c p in Texinfo mode:

(add-hook 'texinfo-mode-hook
          '(lambda ()
             (define-key texinfo-mode-map
                         "\C-cp"
                         'backward-paragraph)
             (define-key texinfo-mode-map
                         "\C-cn"
                         'forward-paragraph)
             ))

See section Hooks.

Minibuffer Keymaps

The minibuffer has its own set of local keymaps; they contain various completion and exit commands.

  • minibuffer-local-map is used for ordinary input (no completion).
  • minibuffer-local-ns-map is similar, except that SPC exits just like RET. This is used mainly for Mocklisp compatibility.
  • minibuffer-local-completion-map is for permissive completion.
  • minibuffer-local-must-match-map is for strict completion and for cautious completion.

Changing Key Bindings Interactively

The way to redefine an Emacs key is to change its entry in a keymap. You can change the global keymap, in which case the change is effective in all major modes (except those that have their own overriding local definitions for the same key). Or you can change the current buffer's local map, which affects all buffers using the same major mode.

M-x global-set-key RET key cmd RET
Define key globally to run cmd.
M-x local-set-key RET key cmd RET
Define key locally (in the major mode now in effect) to run cmd.
M-x global-unset-key RET key
Make key undefined in the global map.
M-x local-unset-key RET key
Make key undefined locally (in the major mode now in effect).

For example, suppose you like to execute commands in a subshell within an Emacs buffer, instead of suspending Emacs and executing commands in your login shell. Normally, C-z is bound to the function suspend-emacs (when not using the X Window System), but you can change C-z to invoke an interactive subshell within Emacs, by binding it to shell as follows:

M-x global-set-key RET C-z shell RET

global-set-key reads the command name after the key. After you press the key, a message like this appears so that you can confirm that you are binding the key you want:

Set key C-z to command:

You can redefine function keys and mouse events in the same way; just type the function key or click the mouse when it's time to specify the key to rebind.

You can rebind a key that contains more than one event in the same way. Emacs keeps reading the key to rebind until it is a complete key (that is, not a prefix key). Thus, if you type C-f for key, that's the end; the minibuffer is entered immediately to read cmd. But if you type C-x, another character is read; if that is 4, another character is read, and so on. For example,

M-x global-set-key RET C-x 4 $ spell-other-window RET

redefines C-x 4 $ to run the (fictitious) command spell-other-window.

The two-character keys consisting of C-c followed by a letter are reserved for user customizations. Lisp programs are not supposed to define these keys, so the bindings you make for them will be available in all major modes and will never get in the way of anything.

You can remove the global definition of a key with global-unset-key. This makes the key undefined; if you type it, Emacs will just beep. Similarly, local-unset-key makes a key undefined in the current major mode keymap, which makes the global definition (or lack of one) come back into effect in that major mode.

If you have redefined (or undefined) a key and you subsequently wish to retract the change, undefining the key will not do the job--you need to redefine the key with its standard definition. To find the name of the standard definition of a key, go to a Fundamental mode buffer and use C-h c. The documentation of keys in this manual also lists their command names.

If you want to prevent yourself from invoking a command by mistake, it is better to disable the command than to undefine the key. A disabled command is less work to invoke when you really want to. See section Disabling Commands.

Rebinding Keys in Your Init File

If you have a set of key bindings that you like to use all the time, you can specify them in your `.emacs' file by using their Lisp syntax.

The simplest method for doing this works for ASCII characters and Meta-modified ASCII characters only. This method uses a string to represent the key sequence you want to rebind. For example, here's how to bind C-z to shell:

(global-set-key "\C-z" 'shell)

This example uses a string constant containing one character, C-z. The single-quote before the command name, shell, marks it as a constant symbol rather than a variable. If you omit the quote, Emacs would try to evaluate shell immediately as a variable. This probably causes an error; it certainly isn't what you want.

Here is another example that binds a key sequence two characters long:

(global-set-key "\C-xl" 'make-symbolic-link)

When the key sequence includes function keys or mouse button events, or non-ASCII characters such as C-= or H-a, you must use the more general method of rebinding, which uses a vector to specify the key sequence.

The way to write a vector in Emacs Lisp is with square brackets around the vector elements. Use spaces to separate the elements. If an element is a symbol, simply write the symbol's name--no other delimiters or punctuation are needed. If a vector element is a character, write it as a Lisp character constant: `?' followed by the character as it would appear in a string.

Here are examples of using vectors to rebind C-= (a control character outside of ASCII), H-a (a Hyper character; ASCII doesn't have Hyper at all), F7 (a function key), and C-Mouse-1 (a keyboard-modified mouse button):

(global-set-key [?\C-=] 'make-symbolic-link)
(global-set-key [?\H-a] 'make-symbolic-link)
(global-set-key [f7] 'make-symbolic-link)
(global-set-key [C-mouse-1] 'make-symbolic-link)

You can use a vector for the simple cases too. Here's how to rewrite the first two examples, above, to use vectors:

(global-set-key [?\C-z] 'shell)

(global-set-key [?\C-x ?l] 'make-symbolic-link)

Rebinding Function Keys

Key sequences can contain function keys as well as ordinary characters. Just as Lisp characters (actually integers) represent keyboard characters, Lisp symbols represent function keys. If the function key has a word as its label, then that word is also the name of the corresponding Lisp symbol. Here are the conventional Lisp names for common function keys:

left, up, right, down
Cursor arrow keys.
begin, end, home, next, prior
Other cursor repositioning keys.
select, print, execute, backtab
insert, undo, redo, clearline
insertline, deleteline, insertchar, deletechar,
Miscellaneous function keys.
f1, f2, ... f35
Numbered function keys (across the top of the keyboard).
kp-add, kp-subtract, kp-multiply, kp-divide
kp-backtab, kp-space, kp-tab, kp-enter
kp-separator, kp-decimal, kp-equal
Keypad keys (to the right of the regular keyboard), with names or punctuation.
kp-0, kp-1, ... kp-9
Keypad keys with digits.
kp-f1, kp-f2, kp-f3, kp-f4
Keypad PF keys.

These names are conventional, but some systems (especially when using X windows) may use different names. To make certain what symbol is used for a given function key on your terminal, type C-h c followed by that key.

A key sequence which contains function key symbols (or anything but ASCII characters) must be a vector rather than a string. The vector syntax uses spaces between the elements, and square brackets around the whole vector. Thus, to bind function key `f1' to the command rmail, write the following:

(global-set-key [f1] 'rmail)

To bind the right-arrow key to the command forward-char, you can use this expression:

(global-set-key [right] 'forward-char)

This uses the Lisp syntax for a vector containing the symbol right. (This binding is present in Emacs by default.)

See section Rebinding Keys in Your Init File, for more information about using vectors for rebinding.

You can mix function keys and characters in a key sequence. This example binds C-x NEXT to the command forward-page.

(global-set-key [?\C-x next] 'forward-page)

where ?\C-x is the Lisp character constant for the character C-x. The vector element next is a symbol and therefore does not take a question mark.

You can use the modifier keys CTRL, META, HYPER, SUPER, ALT and SHIFT with function keys. To represent these modifiers, add the strings `C-', `M-', `H-', `s-', `A-' and `S-' at the front of the symbol name. Thus, here is how to make Hyper-Meta-RIGHT move forward a word:

(global-set-key [H-M-right] 'forward-word)

Named ASCII Control Characters

TAB, RET, BS, LFD, ESC and DEL started out as names for certain ASCII control characters, used so often that they have special keys of their own. Later, users found it convenient to distinguish in Emacs between these keys and the "same" control characters typed with the CTRL key.

Emacs distinguishes these two kinds of input, when used with the X Window System. It treats the "special" keys as function keys named tab, return, backspace, linefeed, escape, and delete. These function keys translate automatically into the corresponding ASCII characters if they have no bindings of their own. As a result, neither users nor Lisp programs need to pay attention to the distinction unless they care to.

If you do not want to distinguish between (for example) TAB and C-i, make just one binding, for the ASCII character TAB (octal code 011). If you do want to distinguish, make one binding for this ASCII character, and another for the "function key" tab.

With an ordinary ASCII terminal, there is no way to distinguish between TAB and C-i (and likewise for other such pairs), because the terminal sends the same character in both cases.

Non-ASCII Characters on the Keyboard

If your keyboard has keys that send non-ASCII characters, such as accented letters, rebinding these keys is a bit tricky. There are two solutions you can use. One is to specify a keyboard coding system, using set-keyboard-coding-system (see section Specifying a Coding System). Then you can bind these keys in the usual way, but writing

(global-set-key [?char] 'some-function)

and typing the key you want to bind to insert char.

If you don't specify the keyboard coding system, that approach won't work. Instead, you need to find out the actual code that the terminal sends. The easiest way to do this in Emacs is to create an empty buffer with C-x b temp RET, make it unibyte with M-x toggle-enable-multibyte-characters RET, then type the key to insert the character into this buffer.

Move point before the character, then type C-b C-x =. This displays a message in the minibuffer, showing the character code in three ways, octal, decimal and hexadecimal, all within a set of parentheses. Use the second of the three numbers, the decimal one, inside the vector to bind:

(global-set-key [decimal-code] 'some-function)

Rebinding Mouse Buttons

Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary mouse events in Emacs are click events; these happen when you press a button and release it without moving the mouse. You can also get drag events, when you move the mouse while holding the button down. Drag events happen when you finally let go of the button.

The symbols for basic click events are mouse-1 for the leftmost button, mouse-2 for the next, and so on. Here is how you can redefine the second mouse button to split the current window:

(global-set-key [mouse-2] 'split-window-vertically)

The symbols for drag events are similar, but have the prefix `drag-' before the word `mouse'. For example, dragging the first button generates a drag-mouse-1 event.

You can also define bindings for events that occur when a mouse button is pressed down. These events start with `down-' instead of `drag-'. Such events are generated only if they have key bindings. When you get a button-down event, a corresponding click or drag event will always follow.

If you wish, you can distinguish single, double, and triple clicks. A double click means clicking a mouse button twice in approximately the same place. The first click generates an ordinary click event. The second click, if it comes soon enough, generates a double-click event instead. The event type for a double-click event starts with `double-': for example, double-mouse-3.

This means that you can give a special meaning to the second click at the same place, but it must act on the assumption that the ordinary single click definition has run when the first click was received.

This constrains what you can do with double clicks, but user interface designers say that this constraint ought to be followed in any case. A double click should do something similar to the single click, only "more so." The command for the double-click event should perform the extra work for the double click.

If a double-click event has no binding, it changes to the corresponding single-click event. Thus, if you don't define a particular double click specially, it executes the single-click command twice.

Emacs also supports triple-click events whose names start with `triple-'. Emacs does not distinguish quadruple clicks as event types; clicks beyond the third generate additional triple-click events. However, the full number of clicks is recorded in the event list, so you can distinguish if you really want to. We don't recommend distinct meanings for more than three clicks, but sometimes it is useful for subsequent clicks to cycle through the same set of three meanings, so that four clicks are equivalent to one click, five are equivalent to two, and six are equivalent to three.

Emacs also records multiple presses in drag and button-down events. For example, when you press a button twice, then move the mouse while holding the button, Emacs gets a `double-drag-' event. And at the moment when you press it down for the second time, Emacs gets a `double-down-' event (which is ignored, like all button-down events, if it has no binding).

The variable double-click-time specifies how long may elapse between clicks that are recognized as a pair. Its value is measured in milliseconds. If the value is nil, double clicks are not detected at all. If the value is t, then there is no time limit.

The symbols for mouse events also indicate the status of the modifier keys, with the usual prefixes `C-', `M-', `H-', `s-', `A-' and `S-'. These always precede `double-' or `triple-', which always precede `drag-' or `down-'.

A frame includes areas that don't show text from the buffer, such as the mode line and the scroll bar. You can tell whether a mouse button comes from a special area of the screen by means of dummy "prefix keys." For example, if you click the mouse in the mode line, you get the prefix key mode-line before the ordinary mouse-button symbol. Thus, here is how to define the command for clicking the first button in a mode line to run scroll-up:

(global-set-key [mode-line mouse-1] 'scroll-up)

Here is the complete list of these dummy prefix keys and their meanings:

mode-line
The mouse was in the mode line of a window.
vertical-line
The mouse was in the vertical line separating side-by-side windows. (If you use scroll bars, they appear in place of these vertical lines.)
vertical-scroll-bar
The mouse was in a vertical scroll bar. (This is the only kind of scroll bar Emacs currently supports.)

You can put more than one mouse button in a key sequence, but it isn't usual to do so.

Disabling Commands

Disabling a command marks the command as requiring confirmation before it can be executed. The purpose of disabling a command is to prevent beginning users from executing it by accident and being confused.

An attempt to invoke a disabled command interactively in Emacs displays a window containing the command's name, its documentation, and some instructions on what to do immediately; then Emacs asks for input saying whether to execute the command as requested, enable it and execute it, or cancel. If you decide to enable the command, you are asked whether to do this permanently or just for the current session. Enabling permanently works by automatically editing your `.emacs' file.

The direct mechanism for disabling a command is to put a non-nil disabled property on the Lisp symbol for the command. Here is the Lisp program to do this:

(put 'delete-region 'disabled t)

If the value of the disabled property is a string, that string is included in the message printed when the command is used:

(put 'delete-region 'disabled
     "It's better to use `kill-region' instead.\n")

You can make a command disabled either by editing the `.emacs' file directly or with the command M-x disable-command, which edits the `.emacs' file for you. Likewise, M-x enable-command edits `.emacs' to enable a command permanently. See section The Init File, `~/.emacs'.

Whether a command is disabled is independent of what key is used to invoke it; disabling also applies if the command is invoked using M-x. Disabling a command has no effect on calling it as a function from Lisp programs.

Keyboard Translations

Some keyboards do not make it convenient to send all the special characters that Emacs uses. The most common problem case is the DEL character. Some keyboards provide no convenient way to type this very important character--usually because they were designed to expect the character C-h to be used for deletion. On these keyboards, if you press the key normally used for deletion, Emacs handles the C-h as a prefix character and offers you a list of help options, which is not what you want.

You can work around this problem within Emacs by setting up keyboard translations to turn C-h into DEL and DEL into C-h, as follows:

;; Translate C-h to DEL.
(keyboard-translate ?\C-h ?\C-?)

;; Translate DEL to C-h.
(keyboard-translate ?\C-? ?\C-h)

Keyboard translations are not the same as key bindings in keymaps (see section Keymaps). Emacs contains numerous keymaps that apply in different situations, but there is only one set of keyboard translations, and it applies to every character that Emacs reads from the terminal. Keyboard translations take place at the lowest level of input processing; the keys that are looked up in keymaps contain the characters that result from keyboard translation.

Under X, the keyboard key named DELETE is a function key and is distinct from the ASCII character named DEL. See section Named ASCII Control Characters. Keyboard translations affect only ASCII character input, not function keys; thus, the above example used under X does not affect the DELETE key. However, the translation above isn't necessary under X, because Emacs can also distinguish between the BACKSPACE key and C-h; and it normally treats BACKSPACE as DEL.

For full information about how to use keyboard translations, see section `Translating Input' in The Emacs Lisp Reference Manual.

The Syntax Table

All the Emacs commands which parse words or balance parentheses are controlled by the syntax table. The syntax table says which characters are opening delimiters, which are parts of words, which are string quotes, and so on. Each major mode has its own syntax table (though sometimes related major modes use the same one) which it installs in each buffer that uses that major mode. The syntax table installed in the current buffer is the one that all commands use, so we call it "the" syntax table. A syntax table is a Lisp object, a char-table, whose elements are numbers.

To display a description of the contents of the current syntax table, type C-h s (describe-syntax). The description of each character includes both the string you would have to give to modify-syntax-entry to set up that character's current syntax, and some English to explain that string if necessary.

For full information on the syntax table, see section `Syntax Tables' in The Emacs Lisp Reference Manual.

The Init File, `~/.emacs'

When Emacs is started, it normally loads a Lisp program from the file `.emacs' or `.emacs.el' in your home directory. We call this file your init file because it specifies how to initialize Emacs for you. You can use the command line switch `-q' to prevent loading your init file, and `-u' (or `--user') to specify a different user's init file (see section Entering and Exiting Emacs).

There can also be a default init file, which is the library named `default.el', found via the standard search path for libraries. The Emacs distribution contains no such library; your site may create one for local customizations. If this library exists, it is loaded whenever you start Emacs (except when you specify `-q'). But your init file, if any, is loaded first; if it sets inhibit-default-init non-nil, then `default' is not loaded.

Your site may also have a site startup file; this is named `site-start.el', if it exists. Emacs loads this library before it loads your init file. To inhibit loading of this library, use the option `-no-site-file'.

If you have a large amount of code in your `.emacs' file, you should rename it to `~/.emacs.el', and byte-compile it. See section `Byte Compilation' in the Emacs Lisp Reference Manual, for more information about compiling Emacs Lisp programs.

If you are going to write actual Emacs Lisp programs that go beyond minor customization, you should read the Emacs Lisp Reference Manual.

Init File Syntax

The `.emacs' file contains one or more Lisp function call expressions. Each of these consists of a function name followed by arguments, all surrounded by parentheses. For example, (setq fill-column 60) calls the function setq to set the variable fill-column (see section Filling Text) to 60.

The second argument to setq is an expression for the new value of the variable. This can be a constant, a variable, or a function call expression. In `.emacs', constants are used most of the time. They can be:

Numbers:
Numbers are written in decimal, with an optional initial minus sign.
Strings:
Lisp string syntax is the same as C string syntax with a few extra features. Use a double-quote character to begin and end a string constant. In a string, you can include newlines and special characters literally. But often it is cleaner to use backslash sequences for them: `\n' for newline, `\b' for backspace, `\r' for carriage return, `\t' for tab, `\f' for formfeed (control-L), `\e' for escape, `\\' for a backslash, `\"' for a double-quote, or `\ooo' for the character whose octal code is ooo. Backslash and double-quote are the only characters for which backslash sequences are mandatory. `\C-' can be used as a prefix for a control character, as in `\C-s' for ASCII control-S, and `\M-' can be used as a prefix for a Meta character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A.
Characters:
Lisp character constant syntax consists of a `?' followed by either a character or an escape sequence starting with `\'. Examples: ?x, ?\n, ?\", ?\). Note that strings and characters are not interchangeable in Lisp; some contexts require one and some contexts require the other.
True:
t stands for `true'.
False:
nil stands for `false'.
Other Lisp objects:
Write a single-quote (') followed by the Lisp object you want.

Init File Examples

Here are some examples of doing certain commonly desired things with Lisp expressions:

  • Make TAB in C mode just insert a tab if point is in the middle of a line.
    (setq c-tab-always-indent nil)
    Here we have a variable whose value is normally t for `true' and the alternative is nil for `false'.
  • Make searches case sensitive by default (in all buffers that do not override this).
    (setq-default case-fold-search nil)
    This sets the default value, which is effective in all buffers that do not have local values for the variable. Setting case-fold-search with setq affects only the current buffer's local value, which is not what you probably want to do in an init file.
  • Specify your own email address, if Emacs can't figure it out correctly.
    (setq user-mail-address "coon@yoyodyne.com")
    Various Emacs packages that need your own email address use the value of user-mail-address.
  • Make Text mode the default mode for new buffers.
    (setq default-major-mode 'text-mode)
    Note that text-mode is used because it is the command for entering Text mode. The single-quote before it makes the symbol a constant; otherwise, text-mode would be treated as a variable name.
  • Set up defaults for the Latin-1 character set which supports most of the languages of Western Europe.
    (set-language-environment "Latin-1")
  • Turn on Auto Fill mode automatically in Text mode and related modes.
    (add-hook 'text-mode-hook
  '(lambda () (auto-fill-mode 1)))
    This shows how to add a hook function to a normal hook variable (see section Hooks). The function we supply is a list starting with lambda, with a single-quote in front of it to make it a list constant rather than an expression. It's beyond the scope of this manual to explain Lisp functions, but for this example it is enough to know that the effect is to execute (auto-fill-mode 1) when Text mode is entered. You can replace that with any other expression that you like, or with several expressions in a row. Emacs comes with a function named turn-on-auto-fill whose definition is (lambda () (auto-fill-mode 1)). Thus, a simpler way to write the above example is as follows:
    (add-hook 'text-mode-hook 'turn-on-auto-fill)
  • Load the installed Lisp library named `foo' (actually a file `foo.elc' or `foo.el' in a standard Emacs directory).
    (load "foo")
    When the argument to load is a relative file name, not starting with `/' or `~', load searches the directories in load-path (see section Libraries of Lisp Code for Emacs).
  • Load the compiled Lisp file `foo.elc' from your home directory.
    (load "~/foo.elc")
    Here an absolute file name is used, so no searching is done.
  • Rebind the key C-x l to run the function make-symbolic-link.
    (global-set-key "\C-xl" 'make-symbolic-link)
    or
    (define-key global-map "\C-xl" 'make-symbolic-link)
    Note once again the single-quote used to refer to the symbol make-symbolic-link instead of its value as a variable.
  • Do the same thing for Lisp mode only.
    (define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
  • Redefine all keys which now run next-line in Fundamental mode so that they run forward-line instead.
    (substitute-key-definition 'next-line 'forward-line
                           global-map)
  • Make C-x C-v undefined.
    (global-unset-key "\C-x\C-v")
    One reason to undefine a key is so that you can make it a prefix. Simply defining C-x C-v anything will make C-x C-v a prefix, but C-x C-v must first be freed of its usual non-prefix definition.
  • Make `$' have the syntax of punctuation in Text mode. Note the use of a character constant for `$'.
    (modify-syntax-entry ?\$ "." text-mode-syntax-table)
  • Enable the use of the command narrow-to-region without confirmation.
    (put 'narrow-to-region 'disabled nil)

Terminal-specific Initialization

Each terminal type can have a Lisp library to be loaded into Emacs when it is run on that type of terminal. For a terminal type named termtype, the library is called `term/termtype' and it is found by searching the directories load-path as usual and trying the suffixes `.elc' and `.el'. Normally it appears in the subdirectory `term' of the directory where most Emacs libraries are kept.

The usual purpose of the terminal-specific library is to map the escape sequences used by the terminal's function keys onto more meaningful names, using function-key-map. See the file `term/lk201.el' for an example of how this is done. Many function keys are mapped automatically according to the information in the Termcap data base; the terminal-specific library needs to map only the function keys that Termcap does not specify.

When the terminal type contains a hyphen, only the part of the name before the first hyphen is significant in choosing the library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library `term/aaa'. The code in the library can use (getenv "TERM") to find the full terminal type name.

The library's name is constructed by concatenating the value of the variable term-file-prefix and the terminal type. Your `.emacs' file can prevent the loading of the terminal-specific library by setting term-file-prefix to nil.

Emacs runs the hook term-setup-hook at the end of initialization, after both your `.emacs' file and any terminal-specific library have been read in. Add hook functions to this hook if you wish to override part of any of the terminal-specific libraries and to define initializations for terminals that do not have a library. See section Hooks.

How Emacs Finds Your Init File

Normally Emacs uses the environment variable HOME to find `.emacs'; that's what `~' means in a file name. But if you have done su, Emacs tries to find your own `.emacs', not that of the user you are currently pretending to be. The idea is that you should get your own editor customizations even if you are running as the super user.

More precisely, Emacs first determines which user's init file to use. It gets the user name from the environment variables LOGNAME and USER; if neither of those exists, it uses effective user-ID. If that user name matches the real user-ID, then Emacs uses HOME; otherwise, it looks up the home directory corresponding to that user name in the system's data base of users.

Dealing with Common Problems

If you type an Emacs command you did not intend, the results are often mysterious. This chapter tells what you can do to cancel your mistake or recover from a mysterious situation. Emacs bugs and system crashes are also considered.

Quitting and Aborting

C-g
C-BREAK (MS-DOS)
Quit. Cancel running or partially typed command.
C-]
Abort innermost recursive editing level and cancel the command which invoked it (abort-recursive-edit).
ESC ESC ESC
Either quit or abort, whichever makes sense (keyboard-escape-quit).
M-x top-level
Abort all recursive editing levels that are currently executing.
C-x u
Cancel a previously made change in the buffer contents (undo).

There are two ways of canceling commands which are not finished executing: quitting with C-g, and aborting with C-] or M-x top-level. Quitting cancels a partially typed command or one which is already running. Aborting exits a recursive editing level and cancels the command that invoked the recursive edit. (See section Recursive Editing Levels.)

Quitting with C-g is used for getting rid of a partially typed command, or a numeric argument that you don't want. It also stops a running command in the middle in a relatively safe way, so you can use it if you accidentally give a command which takes a long time. In particular, it is safe to quit out of killing; either your text will all still be in the buffer, or it will all be in the kill ring (or maybe both). Quitting an incremental search does special things documented under searching; in general, it may take two successive C-g characters to get out of a search (see section Incremental Search).

On MS-DOS, the character C-BREAK serves as a quit character like C-g. The reason is that it is not feasible, on MS-DOS, to recognize C-g while a command is running, between interactions with the user. By contrast, it is feasible to recognize C-BREAK at all times. See section Keyboard and Mouse on MS-DOS.

C-g works by setting the variable quit-flag to t the instant C-g is typed; Emacs Lisp checks this variable frequently and quits if it is non-nil. C-g is only actually executed as a command if you type it while Emacs is waiting for input.

If you quit with C-g a second time before the first C-g is recognized, you activate the "emergency escape" feature and return to the shell. See section Emergency Escape.

There may be times when you cannot quit. When Emacs is waiting for the operating system to do something, quitting is impossible unless special pains are taken for the particular system call within Emacs where the waiting occurs. We have done this for the system calls that users are likely to want to quit from, but it's possible you will find another. In one very common case--waiting for file input or output using NFS--Emacs itself knows how to quit, but most NFS implementations simply do not allow user programs to stop waiting for NFS when the NFS server is hung.

Aborting with C-] (abort-recursive-edit) is used to get out of a recursive editing level and cancel the command which invoked it. Quitting with C-g does not do this, and could not do this, because it is used to cancel a partially typed command within the recursive editing level. Both operations are useful. For example, if you are in a recursive edit and type C-u 8 to enter a numeric argument, you can cancel that argument with C-g and remain in the recursive edit.

The command ESC ESC ESC (keyboard-escape-quit) can either quit or abort. This key was defined because ESC is used to "get out" in many PC programs. It can cancel a prefix argument, clear a selected region, or get out of a Query Replace, like C-g. It can get out of the minibuffer or a recursive edit, like C-]. It can also get out of splitting the frame into multiple windows, like C-x 1. One thing it cannot do, however, is stop a command that is running. That's because it executes as an ordinary command, and Emacs doesn't notice it until it is ready for a command.

The command M-x top-level is equivalent to "enough" C-] commands to get you out of all the levels of recursive edits that you are in. C-] gets you out one level at a time, but M-x top-level goes out all levels at once. Both C-] and M-x top-level are like all other commands, and unlike C-g, in that they take effect only when Emacs is ready for a command. C-] is an ordinary key and has its meaning only because of its binding in the keymap. See section Recursive Editing Levels.

C-x u (undo) is not strictly speaking a way of canceling a command, but you can think of it as canceling a command that already finished executing. See section Undoing Changes.

Dealing with Emacs Trouble

This section describes various conditions in which Emacs fails to work normally, and how to recognize them and correct them.

If DEL Fails to Delete

If you find that DEL enters Help like Control-h instead of deleting a character, your terminal is sending the wrong code for DEL. You can work around this problem by changing the keyboard translation table (see section Keyboard Translations).

Recursive Editing Levels

Recursive editing levels are important and useful features of Emacs, but they can seem like malfunctions to the user who does not understand them.

If the mode line has square brackets `[...]' around the parentheses that contain the names of the major and minor modes, you have entered a recursive editing level. If you did not do this on purpose, or if you don't understand what that means, you should just get out of the recursive editing level. To do so, type M-x top-level. This is called getting back to top level. See section Recursive Editing Levels.

Garbage on the Screen

If the data on the screen looks wrong, the first thing to do is see whether the text is really wrong. Type C-l, to redisplay the entire screen. If the screen appears correct after this, the problem was entirely in the previous screen update. (Otherwise, see section Garbage in the Text.)

Display updating problems often result from an incorrect termcap entry for the terminal you are using. The file `etc/TERMS' in the Emacs distribution gives the fixes for known problems of this sort. `INSTALL' contains general advice for these problems in one of its sections. Very likely there is simply insufficient padding for certain display operations. To investigate the possibility that you have this sort of problem, try Emacs on another terminal made by a different manufacturer. If problems happen frequently on one kind of terminal but not another kind, it is likely to be a bad termcap entry, though it could also be due to a bug in Emacs that appears for terminals that have or that lack specific features.

Garbage in the Text

If C-l shows that the text is wrong, try undoing the changes to it using C-x u until it gets back to a state you consider correct. Also try C-h l to find out what command you typed to produce the observed results.

If a large portion of text appears to be missing at the beginning or end of the buffer, check for the word `Narrow' in the mode line. If it appears, the text you don't see is probably still present, but temporarily off-limits. To make it accessible again, type C-x n w. See section Narrowing.

Spontaneous Entry to Incremental Search

If Emacs spontaneously displays `I-search:' at the bottom of the screen, it means that the terminal is sending C-s and C-q according to the poorly designed xon/xoff "flow control" protocol.

If this happens to you, your best recourse is to put the terminal in a mode where it will not use flow control, or give it so much padding that it will never send a C-s. (One way to increase the amount of padding is to set the variable baud-rate to a larger value. Its value is the terminal output speed, measured in the conventional units of baud.)

If you don't succeed in turning off flow control, the next best thing is to tell Emacs to cope with it. To do this, call the function enable-flow-control.

Typically there are particular terminal types with which you must use flow control. You can conveniently ask for flow control on those terminal types only, using enable-flow-control-on. For example, if you find you must use flow control on VT-100 and H19 terminals, put the following in your `.emacs' file:

(enable-flow-control-on "vt100" "h19")

When flow control is enabled, you must type C-\ to get the effect of a C-s, and type C-^ to get the effect of a C-q. (These aliases work by means of keyboard translations; see section Keyboard Translations.)

Running out of Memory

If you get the error message `Virtual memory exceeded', save your modified buffers with C-x s. This method of saving them has the smallest need for additional memory. Emacs keeps a reserve of memory which it makes available when this error happens; that should be enough to enable C-x s to complete its work.

Once you have saved your modified buffers, you can exit this Emacs job and start another, or you can use M-x kill-some-buffers to free space in the current Emacs job. If you kill buffers containing a substantial amount of text, you can safely go on editing. Emacs refills its memory reserve automatically when it sees sufficient free space available, in case you run out of memory another time.

Do not use M-x buffer-menu to save or kill buffers when you run out of memory, because the buffer menu needs a fair amount memory itself, and the reserve supply may not be enough.

Recovery After a Crash

If Emacs or the computer crashes, you can recover the files you were editing at the time of the crash from their auto-save files. To do this, start Emacs again and type the command M-x recover-session.

This command initially displays a buffer which lists interrupted session files, each with its date. You must choose which session to recover from. Typically the one you want is the most recent one. Move point to the one you choose, and type C-c C-c.

Then recover-session asks about each of the files that you were editing during that session; it asks whether to recover that file. If you answer y for a file, it shows the dates of that file and its auto-save file, then asks once again whether to recover that file. For the second question, you must confirm with yes. If you do, Emacs visits the file but gets the text from the auto-save file.

When recover-session is done, the files you've chosen to recover are present in Emacs buffers. You should then save them. Only this--saving them--updates the files themselves.

Emergency Escape

Because at times there have been bugs causing Emacs to loop without checking quit-flag, a special feature causes Emacs to be suspended immediately if you type a second C-g while the flag is already set, so you can always get out of GNU Emacs. Normally Emacs recognizes and clears quit-flag (and quits!) quickly enough to prevent this from happening. (On MS-DOS and compatible systems, type C-BREAK twice.)

When you resume Emacs after a suspension caused by multiple C-g, it asks two questions before going back to what it had been doing:

Auto-save? (y or n)
Abort (and dump core)? (y or n)

Answer each one with y or n followed by RET.

Saying y to `Auto-save?' causes immediate auto-saving of all modified buffers in which auto-saving is enabled.

Saying y to `Abort (and dump core)?' causes an illegal instruction to be executed, dumping core. This is to enable a wizard to figure out why Emacs was failing to quit in the first place. Execution does not continue after a core dump. If you answer n, execution does continue. With luck, GNU Emacs will ultimately check quit-flag and quit normally. If not, and you type another C-g, it is suspended again.

If Emacs is not really hung, just slow, you may invoke the double C-g feature without really meaning to. Then just resume and answer n to both questions, and you will arrive at your former state. Presumably the quit you requested will happen soon.

The double-C-g feature is turned off when Emacs is running under the X Window System, since you can use the window manager to kill Emacs or to create another window and run another program.

On MS-DOS and compatible systems, the emergency escape feature is sometimes unavailable, even if you press C-BREAK twice, when some system call (MS-DOS or BIOS) hangs, or when Emacs is stuck in a very tight endless loop (in C code, not in Lisp code).

Help for Total Frustration

If using Emacs (or something else) becomes terribly frustrating and none of the techniques described above solve the problem, Emacs can still help you.

First, if the Emacs you are using is not responding to commands, type C-g C-g to get out of it and then start a new one.

Second, type M-x doctor RET.

The doctor will help you feel better. Each time you say something to the doctor, you must end it by typing RET RET. This lets the doctor know you are finished.

Reporting Bugs

Sometimes you will encounter a bug in Emacs. Although we cannot promise we can or will fix the bug, and we might not even agree that it is a bug, we want to hear about problems you encounter. Often we agree they are bugs and want to fix them.

To make it possible for us to fix a bug, you must report it. In order to do so effectively, you must know when and how to do it.

When Is There a Bug

If Emacs executes an illegal instruction, or dies with an operating system error message that indicates a problem in the program (as opposed to something like "disk full"), then it is certainly a bug.

If Emacs updates the display in a way that does not correspond to what is in the buffer, then it is certainly a bug. If a command seems to do the wrong thing but the problem corrects itself if you type C-l, it is a case of incorrect display updating.

Taking forever to complete a command can be a bug, but you must make certain that it was really Emacs's fault. Some commands simply take a long time. Type C-g (C-BREAK on MS-DOS) and then C-h l to see whether the input Emacs received was what you intended to type; if the input was such that you know it should have been processed quickly, report a bug. If you don't know whether the command should take a long time, find out by looking in the manual or by asking for assistance.

If a command you are familiar with causes an Emacs error message in a case where its usual definition ought to be reasonable, it is probably a bug.

If a command does the wrong thing, that is a bug. But be sure you know for certain what it ought to have done. If you aren't familiar with the command, or don't know for certain how the command is supposed to work, then it might actually be working right. Rather than jumping to conclusions, show the problem to someone who knows for certain.

Finally, a command's intended definition may not be best for editing with. This is a very important sort of problem, but it is also a matter of judgment. Also, it is easy to come to such a conclusion out of ignorance of some of the existing features. It is probably best not to complain about such a problem until you have checked the documentation in the usual ways, feel confident that you understand it, and know for certain that what you want is not available. If you are not sure what the command is supposed to do after a careful reading of the manual, check the index and glossary for any terms that may be unclear.

If after careful rereading of the manual you still do not understand what the command should do, that indicates a bug in the manual, which you should report. The manual's job is to make everything clear to people who are not Emacs experts--including you. It is just as important to report documentation bugs as program bugs.

If the on-line documentation string of a function or variable disagrees with the manual, one of them must be wrong; that is a bug.

Understanding Bug Reporting

When you decide that there is a bug, it is important to report it and to report it in a way which is useful. What is most useful is an exact description of what commands you type, starting with the shell command to run Emacs, until the problem happens.

The most important principle in reporting a bug is to report facts. Hypotheses and verbal descriptions are no substitute for the detailed raw data. Reporting the facts is straightforward, but many people strain to posit explanations and report them instead of the facts. If the explanations are based on guesses about how Emacs is implemented, they will be useless; meanwhile, lacking the facts, we will have no real information about the bug.

For example, suppose that you type C-x C-f /glorp/baz.ugh RET, visiting a file which (you know) happens to be rather large, and Emacs displayed `I feel pretty today'. The best way to report the bug is with a sentence like the preceding one, because it gives all the facts.

A bad way would be to assume that the problem is due to the size of the file and say, "I visited a large file, and Emacs displayed `I feel pretty today'." This is what we mean by "guessing explanations." The problem is just as likely to be due to the fact that there is a `z' in the file name. If this is so, then when we got your report, we would try out the problem with some "large file," probably with no `z' in its name, and not see any problem. There is no way in the world that we could guess that we should try visiting a file with a `z' in its name.

Alternatively, the problem might be due to the fact that the file starts with exactly 25 spaces. For this reason, you should make sure that you inform us of the exact contents of any file that is needed to reproduce the bug. What if the problem only occurs when you have typed the C-x C-a command previously? This is why we ask you to give the exact sequence of characters you typed since starting the Emacs session.

You should not even say "visit a file" instead of C-x C-f unless you know that it makes no difference which visiting command is used. Similarly, rather than saying "if I have three characters on the line," say "after I type RET A B C RET C-p," if that is the way you entered the text.

So please don't guess any explanations when you report a bug. If you want to actually debug the problem, and report explanations that are more than guesses, that is useful--but please include the facts as well.

Checklist for Bug Reports

The best way to send a bug report is to mail it electronically to the Emacs maintainers at `bug-gnu-emacs@gnu.org'. (If you want to suggest a change as an improvement, use the same address.)

If you'd like to read the bug reports, you can find them on the newsgroup `gnu.emacs.bug'; keep in mind, however, that as a spectator you should not criticize anything about what you see there. The purpose of bug reports is to give information to the Emacs maintainers. Spectators are welcome only as long as they do not interfere with this. In particular, some bug reports contain large amounts of data; spectators should not complain about this.

Please do not post bug reports using netnews; mail is more reliable than netnews about reporting your correct address, which we may need in order to ask you for more information.

If you can't send electronic mail, then mail the bug report on paper or machine-readable media to this address:

GNU Emacs Bugs
Free Software Foundation
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA

We do not promise to fix the bug; but if the bug is serious, or ugly, or easy to fix, chances are we will want to.

A convenient way to send a bug report for Emacs is to use the command M-x report-emacs-bug. This sets up a mail buffer (see section Sending Mail) and automatically inserts some of the essential information. However, it cannot supply all the necessary information; you should still read and follow the guidelines below, so you can enter the other crucial information by hand before you send the message.

To enable maintainers to investigate a bug, your report should include all these things:

  • The version number of Emacs. Without this, we won't know whether there is any point in looking for the bug in the current version of GNU Emacs. You can get the version number by typing M-x emacs-version RET. If that command does not work, you probably have something other than GNU Emacs, so you will have to report the bug somewhere else.
  • The type of machine you are using, and the operating system name and version number. M-x emacs-version RET provides this information too. Copy its output from the `*Messages*' buffer, so that you get it all and get it accurately.
  • The operands given to the configure command when Emacs was installed.
  • A complete list of any modifications you have made to the Emacs source. (We may not have time to investigate the bug unless it happens in an unmodified Emacs. But if you've made modifications and you don't tell us, you are sending us on a wild goose chase.) Be precise about these changes. A description in English is not enough--send a context diff for them. Adding files of your own, or porting to another machine, is a modification of the source.
  • Details of any other deviations from the standard procedure for installing GNU Emacs.
  • The complete text of any files needed to reproduce the bug. If you can tell us a way to cause the problem without visiting any files, please do so. This makes it much easier to debug. If you do need files, make sure you arrange for us to see their exact contents. For example, it can often matter whether there are spaces at the ends of lines, or a newline after the last line in the buffer (nothing ought to care whether the last line is terminated, but try telling the bugs that).
  • The precise commands we need to type to reproduce the bug. The easy way to record the input to Emacs precisely is to write a dribble file. To start the file, execute the Lisp expression
    (open-dribble-file "~/dribble")
    using M-: or from the `*scratch*' buffer just after starting Emacs. From then on, Emacs copies all your input to the specified dribble file until the Emacs process is killed.
  • For possible display bugs, the terminal type (the value of environment variable TERM), the complete termcap entry for the terminal from `/etc/termcap' (since that file is not identical on all machines), and the output that Emacs actually sent to the terminal. The way to collect the terminal output is to execute the Lisp expression
    (open-termscript "~/termscript")
    using M-: or from the `*scratch*' buffer just after starting Emacs. From then on, Emacs copies all terminal output to the specified termscript file as well, until the Emacs process is killed. If the problem happens when Emacs starts up, put this expression into your `.emacs' file so that the termscript file will be open when Emacs displays the screen for the first time. Be warned: it is often difficult, and sometimes impossible, to fix a terminal-dependent bug without access to a terminal of the type that stimulates the bug.
  • A description of what behavior you observe that you believe is incorrect. For example, "The Emacs process gets a fatal signal," or, "The resulting text is as follows, which I think is wrong." Of course, if the bug is that Emacs gets a fatal signal, then one can't miss it. But if the bug is incorrect text, the maintainer might fail to notice what is wrong. Why leave it to chance? Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of the source is out of sync, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and the copy here might not. If you said to expect a crash, then when Emacs here fails to crash, we would know that the bug was not happening. If you don't say to expect a crash, then we would not know whether the bug was happening--we would not be able to draw any conclusion from our observations.
  • If the manifestation of the bug is an Emacs error message, it is important to report the precise text of the error message, and a backtrace showing how the Lisp program in Emacs arrived at the error. To get the error message text accurately, copy it from the `*Messages*' buffer into the bug report. Copy all of it, not just part. To make a backtrace for the error, evaluate the Lisp expression (setq debug-on-error t) before the error happens (that is to say, you must execute that expression and then make the bug happen). This causes the error to run the Lisp debugger, which shows you a backtrace. Copy the text of the debugger's backtrace into the bug report. This use of the debugger is possible only if you know how to make the bug happen again. If you can't make it happen again, at least copy the whole error message.
  • Check whether any programs you have loaded into the Lisp world, including your `.emacs' file, set any variables that may affect the functioning of Emacs. Also, see whether the problem happens in a freshly started Emacs without loading your `.emacs' file (start Emacs with the -q switch to prevent loading the init file). If the problem does not occur then, you must report the precise contents of any programs that you must load into the Lisp world in order to cause the problem to occur.
  • If the problem does depend on an init file or other Lisp programs that are not part of the standard Emacs system, then you should make sure it is not a bug in those programs by complaining to their maintainers first. After they verify that they are using Emacs in a way that is supposed to work, they should report the bug.
  • If you wish to mention something in the GNU Emacs source, show the line of code with a few lines of context. Don't just give a line number. The line numbers in the development sources don't match those in your sources. It would take extra work for the maintainers to determine what code is in your version at a given line number, and we could not be certain.
  • Additional information from a C debugger such as GDB might enable someone to find a problem on a machine which he does not have available. If you don't know how to use GDB, please read the GDB manual--it is not very long, and using GDB is easy. You can find the GDB distribution, including the GDB manual in online form, in most of the same places you can find the Emacs distribution. To run Emacs under GDB, you should switch to the `src' subdirectory in which Emacs was compiled, then do `gdb emacs'. It is important for the directory `src' to be current so that GDB will read the `.gdbinit' file in this directory. However, you need to think when you collect the additional information if you want it to show what causes the bug. For example, many people send just a backtrace, but that is not very useful by itself. A simple backtrace with arguments often conveys little about what is happening inside GNU Emacs, because most of the arguments listed in the backtrace are pointers to Lisp objects. The numeric values of these pointers have no significance whatever; all that matters is the contents of the objects they point to (and most of the contents are themselves pointers). To provide useful information, you need to show the values of Lisp objects in Lisp notation. Do this for each variable which is a Lisp object, in several stack frames near the bottom of the stack. Look at the source to see which variables are Lisp objects, because the debugger thinks of them as integers. To show a variable's value in Lisp syntax, first print its value, then use the user-defined GDB command pr to print the Lisp object in Lisp syntax. (If you must use another debugger, call the function debug_print with the object as an argument.) The pr command is defined by the file `.gdbinit', and it works only if you are debugging a running process (not with a core dump). To make Lisp errors stop Emacs and return to GDB, put a breakpoint at Fsignal. For a short listing of Lisp functions running, type the GDB command xbacktrace. If you want to examine Lisp function arguments, move up the stack, and each time you get to a frame for the function Ffuncall, type these GDB commands:
    p *args
pr
    To print the first argument that the function received, use these commands:
    p args[1]
pr
    You can print the other arguments likewise. The argument nargs of Ffuncall says how many arguments Ffuncall received; these include the Lisp function itself and the arguments for that function. The file `.gdbinit' defines several other commands that are useful for examining the data types and contents of Lisp objects. Their names begin with `x'. These commands work at a lower level than pr, and are less convenient, but they may work even when pr does not, such as when debugging a core dump or when Emacs has had a fatal signal.
  • If the symptom of the bug is that Emacs fails to respond, don't assume Emacs is "hung"---it may instead be in an infinite loop. To find out which, make the problem happen under GDB and stop Emacs once it is not responding. (If Emacs is using X Windows directly, you can stop Emacs by typing C-z at the GDB job.) Then try stepping with `step'. If Emacs is hung, the `step' command won't return. If it is looping, `step' will return. If this shows Emacs is hung in a system call, stop it again and examine the arguments of the call. In your bug report, state exactly where in the source the system call is, and what the arguments are. If Emacs is in an infinite loop, please determine where the loop starts and ends. The easiest way to do this is to use the GDB command `finish'. Each time you use it, Emacs resumes execution until it exits one stack frame. Keep typing `finish' until it doesn't return--that means the infinite loop is in the stack frame which you just tried to finish. Stop Emacs again, and use `finish' repeatedly again until you get back to that frame. Then use `next' to step through that frame. By stepping, you will see where the loop starts and ends. Also please examine the data being used in the loop and try to determine why the loop does not exit when it should. Include all of this information in your bug report.

Here are some things that are not necessary in a bug report:

  • A description of the envelope of the bug--this is not necessary for a reproducible bug. Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it. This is often time-consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. You might as well save time by not searching for additional examples. Of course, if you can find a simpler example to report instead of the original one, that is a convenience. Errors in the output will be easier to spot, running under the debugger will take less time, etc. However, simplification is not vital; if you can't do this or don't have time to try, please report the bug with your original test case.
  • A system-call trace of Emacs execution. System-call traces are very useful for certain special kinds of debugging, but in most cases they give little useful information. It is therefore strange that many people seem to think that the way to report information about a crash is to send a system-call trace. Perhaps this is a habit formed from experience debugging programs that don't have source code or debugging symbols. In most programs, a backtrace is normally far, far more informative than a system-call trace. Even in Emacs, a simple backtrace is generally more informative, though to give full information you should supplement the backtrace by displaying variable values and printing them as Lisp objects with pr (see above).
  • A patch for the bug. A patch for the bug is useful if it is a good one. But don't omit the other information that a bug report needs, such as the test case, on the assumption that a patch is sufficient. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. And if we can't understand what bug you are trying to fix, or why your patch should be an improvement, we mustn't install it.
  • A guess about what the bug is or what it depends on. Such guesses are usually wrong. Even experts can't guess right about such things without first using the debugger to find the facts.

Sending Patches for GNU Emacs

If you would like to write bug fixes or improvements for GNU Emacs, that is very helpful. When you send your changes, please follow these guidelines to make it easy for the maintainers to use them. If you don't follow these guidelines, your information might still be useful, but using it will take extra work. Maintaining GNU Emacs is a lot of work in the best of circumstances, and we can't keep up unless you do your best to help.

  • Send an explanation with your changes of what problem they fix or what improvement they bring about. For a bug fix, just include a copy of the bug report, and explain why the change fixes the bug. (Referring to a bug report is not as good as including it, because then we will have to look it up, and we have probably already deleted it if we've already fixed the bug.)
  • Always include a proper bug report for the problem you think you have fixed. We need to convince ourselves that the change is right before installing it. Even if it is correct, we might have trouble understanding it if we don't have a way to reproduce the problem.
  • Include all the comments that are appropriate to help people reading the source in the future understand why this change was needed.
  • Don't mix together changes made for different reasons. Send them individually. If you make two changes for separate reasons, then we might not want to install them both. We might want to install just one. If you send them all jumbled together in a single set of diffs, we have to do extra work to disentangle them--to figure out which parts of the change serve which purpose. If we don't have time for this, we might have to ignore your changes entirely. If you send each change as soon as you have written it, with its own explanation, then two changes never get tangled up, and we can consider each one properly without any extra work to disentangle them.
  • Send each change as soon as that change is finished. Sometimes people think they are helping us by accumulating many changes to send them all together. As explained above, this is absolutely the worst thing you could do. Since you should send each change separately, you might as well send it right away. That gives us the option of installing it immediately if it is important.
  • Use `diff -c' to make your diffs. Diffs without context are hard to install reliably. More than that, they are hard to study; we must always study a patch to decide whether we want to install it. Unidiff format is better than contextless diffs, but not as easy to read as `-c' format. If you have GNU diff, use `diff -c -F'^[_a-zA-Z0-9$]+ *('' when making diffs of C code. This shows the name of the function that each change occurs in.
  • Avoid any ambiguity as to which is the old version and which is the new. Please make the old version the first argument to diff, and the new version the second argument. And please give one version or the other a name that indicates whether it is the old version or your new changed one.
  • Write the change log entries for your changes. This is both to save us the extra work of writing them, and to help explain your changes so we can understand them. The purpose of the change log is to show people where to find what was changed. So you need to be specific about what functions you changed; in large functions, it's often helpful to indicate where within the function the change was. On the other hand, once you have shown people where to find the change, you need not explain its purpose in the change log. Thus, if you add a new function, all you need to say about it is that it is new. If you feel that the purpose needs explaining, it probably does--but put the explanation in comments in the code. It will be more useful there. Please read the `ChangeLog' files in the `src' and `lisp' directories to see what sorts of information to put in, and to learn the style that we use. If you would like your name to appear in the header line, showing who made the change, send us the header line. See section Change Logs.
  • When you write the fix, keep in mind that we can't install a change that would break other systems. Please think about what effect your change will have if compiled on another type of system. Sometimes people send fixes that might be an improvement in general--but it is hard to be sure of this. It's hard to install such changes because we have to study them very carefully. Of course, a good explanation of the reasoning by which you concluded the change was correct can help convince us. The safest changes are changes to the configuration files for a particular machine. These are safe because they can't create new bugs on other machines. Please help us keep up with the workload by designing the patch in a form that is clearly safe to install.

Contributing to Emacs Development

If you would like to help pretest Emacs releases to assure they work well, or if you would like to work on improving Emacs, please contact the maintainers at bug-gnu-emacs@gnu.org. A pretester should be prepared to investigate bugs as well as report them. If you'd like to work on improving Emacs, please ask for suggested projects or suggest your own ideas.

If you have already written an improvement, please tell us about it. If you have not yet started work, it is useful to contact bug-gnu-emacs@gnu.org before you start; it might be possible to suggest ways to make your extension fit in better with the rest of Emacs.

How To Get Help with GNU Emacs

If you need help installing, using or changing GNU Emacs, there are two ways to find it:

  • Send a message to the mailing list help-gnu-emacs@gnu.org, or post your request on newsgroup gnu.emacs.help. (This mailing list and newsgroup interconnect, so it does not matter which one you use.)
  • Look in the service directory for someone who might help you for a fee. The service directory is found in the file named `etc/SERVICE' in the Emacs distribution.

Command Line Arguments

GNU Emacs supports command line arguments to request various actions when invoking Emacs. These are for compatibility with other editors and for sophisticated activities. We don't recommend using them for ordinary editing.

Arguments starting with `-' are options. Other arguments specify files to visit. Emacs visits the specified files while it starts up. The last file name on your command line becomes the current buffer; the other files are also present in other buffers. As usual, the special argument `--' says that all subsequent arguments are file names, not options, even if they start with `-'.

Emacs command options can specify many things, such as the size and position of the X window Emacs uses, its colors, and so on. A few options support advanced usage, such as running Lisp functions on files in batch mode. The sections of this chapter describe the available options, arranged according to their purpose.

There are two ways of writing options: the short forms that start with a single `-', and the long forms that start with `--'. For example, `-d' is a short form and `--display' is the corresponding long form.

The long forms with `--' are easier to remember, but longer to type. However, you don't have to spell out the whole option name; any unambiguous abbreviation is enough. When a long option takes an argument, you can use either a space or an equal sign to separate the option name and the argument. Thus, you can write either `--display sugar-bombs:0.0' or `--display=sugar-bombs:0.0'. We recommend an equal sign because it makes the relationship clearer, and the tables below always show an equal sign.

Most options specify how to initialize Emacs, or set parameters for the Emacs session. We call them initial options. A few options specify things to do: for example, load libraries, call functions, or exit Emacs. These are called action options. These and file names together are called action arguments. Emacs processes all the action arguments in the order they are written.

Action Arguments

Here is a table of the action arguments and options:

`file'
Visit file using find-file. See section Visiting Files.
`+linenum file'
Visit file using find-file, then go to line number linenum in it.
`-l file'
`--load=file'
Load a Lisp library named file with the function load. See section Libraries of Lisp Code for Emacs. The library can be found either in the current directory, or in the Emacs library search path as specified with EMACSLOADPATH (see section General Variables).
`-f function'
`--funcall=function'
Call Lisp function function with no arguments.
`--eval expression'
Evaluate Lisp expression expression.
`--insert=file'
Insert the contents of file into the current buffer. This is like what M-x insert-file does. See section Miscellaneous File Operations.
`--kill'
Exit from Emacs without asking for confirmation.

The init file can access the values of the action arguments as the elements of a list in the variable command-line-args. The init file can override the normal processing of the action arguments, or define new ones, by reading and setting this variable.

Initial Options

The initial options specify parameters for the Emacs session. This section describes the more general initial options; some other options specifically related to X Windows appear in the following sections.

Some initial options affect the loading of init files. The normal actions of Emacs are to first load `site-start.el' if it exists, then your own init file `~/.emacs' if it exists, and finally `default.el' if it exists; certain options prevent loading of some of these files or substitute other files for them.

`-t device'
`--terminal=device'
Use device as the device for terminal input and output.
`-d display'
`--display=display'
Use the X Window System and use the display named display to open the initial Emacs frame.
`-nw'
`--no-windows'
Don't communicate directly with X, disregarding the DISPLAY environment variable even if it is set.
`-batch'
`--batch'
Run Emacs in batch mode, which means that the text being edited is not displayed and the standard terminal interrupt characters such as C-z and C-c continue to have their normal effect. Emacs in batch mode outputs to stderr only what would normally be printed in the echo area under program control. Batch mode is used for running programs written in Emacs Lisp from shell scripts, makefiles, and so on. Normally the `-l' option or `-f' option will be used as well, to invoke a Lisp program to do the batch processing. `-batch' implies `-q' (do not load an init file). It also causes Emacs to kill itself after all command options have been processed. In addition, auto-saving is not done except in buffers for which it has been explicitly requested.
`-q'
`--no-init-file'
Do not load your Emacs init file `~/.emacs', or `default.el' either.
`--no-site-file'
Do not load `site-start.el'. The options `-q', `-u' and `-batch' have no effect on the loading of this file--this is the only option that blocks it.
`-u user'
`--user=user'
Load user's Emacs init file `~user/.emacs' instead of your own.
`--debug-init'
Enable the Emacs Lisp debugger for errors in the init file.
`--unibyte'
Set up to do almost everything with single-byte buffers and strings. All buffers and strings are unibyte unless you (or a Lisp program) explicitly ask for a multibyte buffer or string. Setting the environment variable EMACS_UNIBYTE has the same effect.
`--multibyte'
Inhibit the effect of EMACS_UNIBYTE, so that Emacs uses multibyte characters by default, as usual.

Command Argument Example

Here is an example of using Emacs with arguments and options. It assumes you have a Lisp program file called `hack-c.el' which, when loaded, performs some useful operation on the current buffer, expected to be a C program.

emacs -batch foo.c -l hack-c -f save-buffer >& log

This says to visit `foo.c', load `hack-c.el' (which makes changes in the visited file), save `foo.c' (note that save-buffer is the function that C-x C-s is bound to), and then exit back to the shell (because of `-batch'). `-batch' also guarantees there will be no problem redirecting output to `log', because Emacs will not assume that it has a display terminal to work with.

Resuming Emacs with Arguments

You can specify action arguments for Emacs when you resume it after a suspension. To prepare for this, put the following code in your `.emacs' file (see section Hooks):

(add-hook 'suspend-hook 'resume-suspend-hook)
(add-hook 'suspend-resume-hook 'resume-process-args)

As further preparation, you must execute the shell script `emacs.csh' (if you use csh as your shell) or `emacs.bash' (if you use bash as your shell). These scripts define an alias named edit, which will resume Emacs giving it new command line arguments such as files to visit.

Only action arguments work properly when you resume Emacs. Initial arguments are not recognized--it's too late to execute them anyway.

Note that resuming Emacs (with or without arguments) must be done from within the shell that is the parent of the Emacs job. This is why edit is an alias rather than a program or a shell script. It is not possible to implement a resumption command that could be run from other subjobs of the shell; no way to define a command that could be made the value of EDITOR, for example. Therefore, this feature does not take the place of the Emacs Server feature (see section Using Emacs as a Server).

The aliases use the Emacs Server feature if you appear to have a server Emacs running. However, they cannot determine this with complete accuracy. They may think that a server is still running when in actuality you have killed that Emacs, because the file `/tmp/.esrv...' still exists. If this happens, find that file and delete it.

Environment Variables

This appendix describes how Emacs uses environment variables. An environment variable is a string passed from the operating system to Emacs, and the collection of environment variables is known as the environment. Environment variable names are case sensitive and it is conventional to use upper case letters only.

Because environment variables come from the operating system there is no general way to set them; it depends on the operating system and especially the shell that you are using. For example, here's how to set the environment variable ORGANIZATION to `not very much' using bash:

export ORGANIZATION="not very much"

and here's how to do it in csh or tcsh:

setenv ORGANIZATION "not very much"

When Emacs is set-up to use the X windowing system, it inherits the use of a large number of environment variables from the X library. See the X documentation for more information.

General Variables

AUTHORCOPY
The name of a file used to archive news articles posted with the GNUS package.
CDPATH
Used by the cd command to search for the directory you specify, when you specify a relative directory name.
DOMAINNAME
The name of the Internet domain that the machine running Emacs is located in. Used by the GNUS package.
EMACS_UNIBYTE
Defining this environment variable directs Emacs to do almost everything with single-byte buffers and strings. It is equivalent to using the `--unibyte' command-line option on each invocation. See section Initial Options.
EMACSDATA
Used to initialize the variable data-directory used to locate the architecture-independent files that come with Emacs. Setting this variable overrides the setting in `paths.h' when Emacs was built.
EMACSLOADPATH
A colon-separated list of directories from which to load Emacs Lisp files. Setting this variable overrides the setting in `paths.h' when Emacs was built.
EMACSLOCKDIR
The directory that Emacs places lock files--files used to protect users from editing the same files simultaneously. Setting this variable overrides the setting in `paths.h' when Emacs was built.
EMACSPATH
The location of Emacs-specific binaries. Setting this variable overrides the setting in `paths.h' when Emacs was built.
ESHELL
Used for shell-mode to override the SHELL environment variable.
HISTFILE
The name of the file that shell commands are saved in between logins. This variable defaults to `~/.history' if you use (t)csh as shell, to `~/.bash_history' if you use bash, to `~/.sh_history' if you use ksh, and to `~/.history' otherwise.
HOME
The location of the user's files in the directory tree; used for expansion of file names starting with a tilde (`~'). On MS-DOS, it defaults to the directory from which Emacs was started, with `/bin' removed from the end if it was present.
HOSTNAME
The name of the machine that Emacs is running on.
INCPATH
A colon-separated list of directories. Used by the complete package to search for files.
INFOPATH
A colon-separated list of directories holding info files. Setting this variable overrides the setting in `paths.el' when Emacs was built.
LANG
LC_ALL
LC_CTYPE
The user's preferred locale. A locale name which contains `8859-n', `8859_n' or `8859n', where n is between 1 and 4, automatically specifies the `Latin-n' language environment when Emacs starts up. If n is 9, that specifies `Latin-5'.
LOGNAME
The user's login name. See also USER.
MAIL
The name of the user's system mail inbox.
MAILRC
Name of file containing mail aliases. This defaults to `~/.mailrc'.
MH
Name of setup file for the mh system. This defaults to `~/.mh_profile'.
NAME
The real-world name of the user.
NNTPSERVER
The name of the news server. Used by the mh and GNUS packages.
ORGANIZATION
The name of the organization to which you belong. Used for setting the `Organization:' header in your posts from the GNUS package.
PATH
A colon-separated list of directories in which executables reside. (On MS-DOS, it is semicolon-separated instead.) This variable is used to set the Emacs Lisp variable exec-path which you should consider to use instead.
PWD
If set, this should be the default directory when Emacs was started.
REPLYTO
If set, this specifies an initial value for the variable mail-default-reply-to. See section Mail Header Fields.
SAVEDIR
The name of a directory in which news articles are saved by default. Used by the GNUS package.
SHELL
The name of an interpreter used to parse and execute programs run from inside Emacs.
TERM
The name of the terminal that Emacs is running on. The variable must be set unless Emacs is run in batch mode. On MS-DOS, it defaults to `internal', which specifies a built-in terminal emulation that handles the machine's own display.
TERMCAP
The name of the termcap library file describing how to program the terminal specified by the TERM variable. This defaults to `/etc/termcap'.
TMPDIR
Used by the Emerge package as a prefix for temporary files.
TZ
This specifies the current time zone and possibly also daylight savings information. On MS-DOS, the default is based on country code; see the file `msdos.c' for details.
USER
The user's login name. See also LOGNAME. On MS-DOS, this defaults to `root'.
VERSION_CONTROL
Used to initialize the version-control variable (see section Single or Numbered Backups).

Miscellaneous Variables

These variables are used only on particular configurations:

COMSPEC
On MS-DOS, the name of the command interpreter to use. This is used to make a default value for the SHELL environment variable.
NAME
On MS-DOS, this variable defaults to the value of the USER variable.
TEMP
TMP
On MS-DOS, these specify the name of the directory for storing temporary files in.
EMACSTEST
On MS-DOS, this specifies a file to use to log the operation of the internal terminal emulator. This feature is useful for submitting bug reports.
EMACSCOLORS
Used on MS-DOS systems to set screen colors early, so that the screen won't momentarily flash the default colors when Emacs starts up. The value of this variable should be two-character encoding of the foreground (the first character) and the background (the second character) colors of the default face. Each character should be the hexadecimal code for the desired color on a standard PC text-mode display. The PC display usually supports only eight background colors. However, Emacs switches the DOS display to a mode where all 16 colors can be used for the background, so all four bits of the background color are actually used.
WINDOW_GFX
Used when initializing the Sun windows system.

Specifying the Display Name

The environment variable DISPLAY tells all X clients, including Emacs, where to display their windows. Its value is set up by default in ordinary circumstances, when you start an X server and run jobs locally. Occasionally you may need to specify the display yourself; for example, if you do a remote login and want to run a client program remotely, displaying on your local screen.

With Emacs, the main reason people change the default display is to let them log into another system, run Emacs on that system, but have the window displayed at their local terminal. You might need to use login to another system because the files you want to edit are there, or because the Emacs executable file you want to run is there.

The syntax of the DISPLAY environment variable is `host:display.screen', where host is the host name of the X Window System server machine, display is an arbitrarily-assigned number that distinguishes your server (X terminal) from other servers on the same machine, and screen is a rarely-used field that allows an X server to control multiple terminal screens. The period and the screen field are optional. If included, screen is usually zero.

For example, if your host is named `glasperle' and your server is the first (or perhaps the only) server listed in the configuration, your DISPLAY is `glasperle:0.0'.

You can specify the display name explicitly when you run Emacs, either by changing the DISPLAY variable, or with the option `-d display' or `--display=display'. Here is an example:

emacs --display=glasperle:0 &

You can inhibit the direct use of X with the `-nw' option. This is also an initial option. It tells Emacs to display using ordinary ASCII on its controlling terminal.

Sometimes, security arrangements prevent a program on a remote system from displaying on your local system. In this case, trying to run Emacs produces messages like this:

Xlib:  connection to "glasperle:0.0" refused by server

You might be able to overcome this problem by using the xhost command on the local system to give permission for access from your remote machine.

Font Specification Options

By default, Emacs displays text in the font named `9x15', which makes each character nine pixels wide and fifteen pixels high. You can specify a different font on your command line through the option `-fn name'.

`-fn name'
Use font name as the default font.
`--font=name'
`--font' is an alias for `-fn'.

Under X, each font has a long name which consists of eleven words or numbers, separated by dashes. Some fonts also have shorter nicknames---`9x15' is such a nickname. You can use either kind of name. You can use wildcard patterns for the font name; then Emacs lets X choose one of the fonts that match the pattern. Here is an example, which happens to specify the font whose nickname is `6x13':

emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &

You can also specify the font in your `.Xdefaults' file:

emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1

A long font name has the following form:

-maker-family-weight-slant-widthtype-style...
...-pixels-height-horiz-vert-spacing-width-charset
family
This is the name of the font family--for example, `courier'.
weight
This is normally `bold', `medium' or `light'. Other words may appear here in some font names.
slant
This is `r' (roman), `i' (italic), `o' (oblique), `ri' (reverse italic), or `ot' (other).
widthtype
This is normally `condensed', `extended', `semicondensed' or `normal'. Other words may appear here in some font names.
style
This is an optional additional style name. Usually it is empty--most long font names have two hyphens in a row at this point.
pixels
This is the font height, in pixels.
height
This is the font height on the screen, measured in tenths of a printer's point--approximately 1/720 of an inch. In other words, it is the point size of the font, times ten. For a given vertical resolution, height and pixels are proportional; therefore, it is common to specify just one of them and use `*' for the other.
horiz
This is the horizontal resolution, in pixels per inch, of the screen for which the font is intended.
vert
This is the vertical resolution, in dots per inch, of the screen for which the font is intended. Normally the resolution of the fonts on your system is the right value for your screen; therefore, you normally specify `*' for this and horiz.
spacing
This is `m' (monospace), `p' (proportional) or `c' (character cell). Emacs can use `m' and `c' fonts.
width
This is the average character width, in pixels, multiplied by ten.
charset
This is the character set that the font depicts. Normally you should use `iso8859-1'.

Use only fixed-width fonts--that is, fonts in which all characters have the same width; Emacs cannot yet handle display properly for variable-width fonts. Any font with `m' or `c' in the spacing field of the long name is a fixed-width font. Here's how to use the xlsfonts program to list all the fixed-width fonts available on your system:

xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'

To see what a particular font looks like, use the xfd command. For example:

xfd -fn 6x13

displays the entire font `6x13'.

While running Emacs, you can set the font of the current frame (see section Setting Frame Parameters) or for a specific kind of text (see section Using Multiple Typefaces).

Window Color Options

On a color display, you can specify which color to use for various parts of the Emacs display. To find out what colors are available on your system, look at the `/usr/lib/X11/rgb.txt' file. If you do not specify colors, the default for the background is white and the default for all other colors is black. On a monochrome display, the foreground is black, the background is white, and the border is gray if the display supports that.

Here is a list of the options for specifying colors:

`-fg color'
`--foreground-color=color'
Specify the foreground color.
`-bg color'
`--background-color=color'
Specify the background color.
`-bd color'
`--border-color=color'
Specify the color of the border of the X window.
`-cr color'
`--cursor-color=color'
Specify the color of the Emacs cursor which indicates where point is.
`-ms color'
`--mouse-color=color'
Specify the color for the mouse cursor when the mouse is in the Emacs window.
`-r'
`--reverse-video'
Reverse video--swap the foreground and background colors.

For example, to use a coral mouse cursor and a slate blue text cursor, enter:

emacs -ms coral -cr 'slate blue' &

You can reverse the foreground and background colors through the `-r' option or with the X resource `reverseVideo'.

Options for Window Geometry

The `-geometry' option controls the size and position of the initial Emacs frame. Here is the format for specifying the window geometry:

`-g widthxheight{+-}xoffset{+-}yoffset'
Specify window size width and height (measured in character columns and lines), and positions xoffset and yoffset (measured in pixels).
`--geometry=widthxheight{+-}xoffset{+-}yoffset'
This is another way of writing the same thing.

{+-} means either a plus sign or a minus sign. A plus sign before xoffset means it is the distance from the left side of the screen; a minus sign means it counts from the right side. A plus sign before yoffset means it is the distance from the top of the screen, and a minus sign there indicates the distance from the bottom. The values xoffset and yoffset may themselves be positive or negative, but that doesn't change their meaning, only their direction.

Emacs uses the same units as xterm does to interpret the geometry. The width and height are measured in characters, so a large font creates a larger frame than a small font. The xoffset and yoffset are measured in pixels.

Since the mode line and the echo area occupy the last 2 lines of the frame, the height of the initial text window is 2 less than the height specified in your geometry. In non-X-toolkit versions of Emacs, the menu bar also takes one line of the specified number.

You do not have to specify all of the fields in the geometry specification.

If you omit both xoffset and yoffset, the window manager decides where to put the Emacs frame, possibly by letting you place it with the mouse. For example, `164x55' specifies a window 164 columns wide, enough for two ordinary width windows side by side, and 55 lines tall.

The default width for Emacs is 80 characters and the default height is 40 lines. You can omit either the width or the height or both. If you start the geometry with an integer, Emacs interprets it as the width. If you start with an `x' followed by an integer, Emacs interprets it as the height. Thus, `81' specifies just the width; `x45' specifies just the height.

If you start with `+' or `-', that introduces an offset, which means both sizes are omitted. Thus, `-3' specifies the xoffset only. (If you give just one offset, it is always xoffset.) `+3-3' specifies both the xoffset and the yoffset, placing the frame near the bottom left of the screen.

You can specify a default for any or all of the fields in `.Xdefaults' file, and then override selected fields with a `--geometry' option.

Internal and External Borders

An Emacs frame has an internal border and an external border. The internal border is an extra strip of the background color around all four edges of the frame. Emacs itself adds the internal border. The external border is added by the window manager outside the internal border; it may contain various boxes you can click on to move or iconify the window.

`-ib width'
`--internal-border=width'
Specify width as the width of the internal border.
`-bw width'
`--border-width=width'
Specify width as the width of the main border.

When you specify the size of the frame, that does not count the borders. The frame's position is measured from the outside edge of the external border.

Use the `-ib n' option to specify an internal border n pixels wide. The default is 1. Use `-bw n' to specify the width of the external border (though the window manager may not pay attention to what you specify). The default width of the external border is 2.

Frame Titles

An Emacs frame may or may not have a specified title. The frame title, if specified, appears in window decorations and icons as the name of the frame. If an Emacs frame has no specified title, the default title is the name of the executable program (if there is only one frame) or the selected window's buffer name (if there is more than one frame).

You can specify a title for the initial Emacs frame with a command line option:

`-title title'
`--title=title'
`-T title'
Specify title as the title for the initial Emacs frame.

The `--name' option (see section X Resources) also specifies the title for the initial Emacs frame.

Icons

Most window managers allow the user to "iconify" a frame, removing it from sight, and leaving a small, distinctive "icon" window in its place. Clicking on the icon window makes the frame itself appear again. If you have many clients running at once, you can avoid cluttering up the screen by iconifying most of the clients.

`-i'
`--icon-type'
Use a picture of a gnu as the Emacs icon.
`-iconic'
`--iconic'
Start Emacs in iconified state.

The `-i' or `--icon-type' option tells Emacs to use an icon window containing a picture of the GNU gnu. If omitted, Emacs lets the window manager choose what sort of icon to use--usually just a small rectangle containing the frame's title.

The `-iconic' option tells Emacs to begin running as an icon, rather than opening a frame right away. In this situation, the icon window provides only indication that Emacs has started; the usual text frame doesn't appear until you deiconify it.

X Resources

Programs running under the X Window System organize their user options under a hierarchy of classes and resources. You can specify default values for these options in your X resources file, usually named `~/.Xdefaults'.

Each line in the file specifies a value for one option or for a collection of related options, for one program or for several programs (optionally even for all programs).

Programs define named resources with particular meanings. They also define how to group resources into named classes. For instance, in Emacs, the `internalBorder' resource controls the width of the internal border, and the `borderWidth' resource controls the width of the external border. Both of these resources are part of the `BorderWidth' class. Case distinctions are significant in these names.

In `~/.Xdefaults', you can specify a value for a single resource on one line, like this:

emacs.borderWidth: 2

Or you can use a class name to specify the same value for all resources in that class. Here's an example:

emacs.BorderWidth: 2

If you specify a value for a class, it becomes the default for all resources in that class. You can specify values for individual resources as well; these override the class value, for those particular resources. Thus, this example specifies 2 as the default width for all borders, but overrides this value with 4 for the external border:

emacs.Borderwidth: 2
emacs.borderwidth: 4

The order in which the lines appear in the file does not matter. Also, command-line options always override the X resources file.

The string `emacs' in the examples above is also a resource name. It actually represents the name of the executable file that you invoke to run Emacs. If Emacs is installed under a different name, it looks for resources under that name instead of `emacs'.

`-name name'
`--name=name'
Use name as the resource name (and the title) for the initial Emacs frame. This option does not affect subsequent frames, but Lisp programs can specify frame names when they create frames. If you don't specify this option, the default is to use the Emacs executable's name as the resource name.
`-xrm resource-values'
`--xrm=resource-values'
Specify X resource values for this Emacs job (see below).

For consistency, `-name' also specifies the name to use for other resource values that do not belong to any particular frame.

The resources that name Emacs invocations also belong to a class; its name is `Emacs'. If you write `Emacs' instead of `emacs', the resource applies to all frames in all Emacs jobs, regardless of frame titles and regardless of the name of the executable file. Here is an example:

Emacs.BorderWidth: 2
Emacs.borderWidth: 4

You can specify a string of additional resource values for Emacs to use with the command line option `-xrm resources'. The text resources should have the same format that you would use inside a file of X resources. To include multiple resource specifications in data, put a newline between them, just as you would in a file. You can also use `#include "filename"' to include a file full of resource specifications. Resource values specified with `-xrm' take precedence over all other resource specifications.

The following table lists the resource names that designate options for Emacs, each with the class that it belongs to:

background (class Background)
Background color name.
bitmapIcon (class BitmapIcon)
Use a bitmap icon (a picture of a gnu) if `on', let the window manager choose an icon if `off'.
borderColor (class BorderColor)
Color name for the external border.
borderWidth (class BorderWidth)
Width in pixels of the external border.
cursorColor (class Foreground)
Color name for text cursor (point).
font (class Font)
Font name for text (or fontset name, see section Fontsets).
foreground (class Foreground)
Color name for text.
geometry (class Geometry)
Window size and position. Be careful not to specify this resource as `emacs*geometry', because that may affect individual menus as well as the Emacs frame itself. If this resource specifies a position, that position applies only to the initial Emacs frame (or, in the case of a resource for a specific frame name, only that frame). However, the size if specified here applies to all frames.
iconName (class Title)
Name to display in the icon.
internalBorder (class BorderWidth)
Width in pixels of the internal border.
menuBar (class MenuBar)
Give frames menu bars if `on'; don't have menu bars if `off'.
minibuffer (class Minibuffer)
If `none', don't make a minibuffer in this frame. It will use a separate minibuffer frame instead.
paneFont (class Font)
Font name for menu pane titles, in non-toolkit versions of Emacs.
pointerColor (class Foreground)
Color of the mouse cursor.
reverseVideo (class ReverseVideo)
Switch foreground and background default colors if `on', use colors as specified if `off'.
verticalScrollBars (class ScrollBars)
Give frames scroll bars if `on'; don't have scroll bars if `off'.
selectionFont (class Font)
Font name for pop-up menu items, in non-toolkit versions of Emacs. (For toolkit versions, see section Lucid Menu X Resources, also see section Motif Menu X Resources.)
title (class Title)
Name to display in the title bar of the initial Emacs frame.

Here are resources for controlling the appearance of particular faces (see section Using Multiple Typefaces):

face.attributeFont
Font for face face.
face.attributeForeground
Foreground color for face face.
face.attributeBackground
Background color for face face.
face.attributeUnderline
Underline flag for face face. Use `on' or `true' for yes.

Lucid Menu X Resources

If the Emacs installed at your site was built to use the X toolkit with the Lucid menu widgets, then the menu bar is a separate widget and has its own resources. The resource names contain `pane.menubar' (following, as always, the name of the Emacs invocation or `Emacs' which stands for all Emacs invocations). Specify them like this:

Emacs.pane.menubar.resource:  value

For example, to specify the font `8x16' for the menu-bar items, write this:

Emacs.pane.menubar.font:  8x16

Resources for non-menubar toolkit pop-up menus have `menu*', in like fashion. For example, to specify the font `8x16' for the pop-up menu items, write this:

Emacs.menu*.font:	8x16

For dialog boxes, use `dialog' instead of `menu':

Emacs.dialog*.font:	8x16

Experience shows that on some systems you may need to add `shell.' before the `pane.menubar' or `menu*'. On some other systems, you must not add `shell.'.

Here is a list of the specific resources for menu bars and pop-up menus:

font
Font for menu item text.
foreground
Color of the foreground.
background
Color of the background.
buttonForeground
In the menu bar, the color of the foreground for a selected item.
horizontalSpacing
Horizontal spacing in pixels between items. Default is 3.
verticalSpacing
Vertical spacing in pixels between items. Default is 1.
arrowSpacing
Horizontal spacing between the arrow (which indicates a submenu) and the associated text. Default is 10.
shadowThickness
Thickness of shadow line around the widget.

Motif Menu X Resources

If the Emacs installed at your site was built to use the X toolkit with the Motif widgets, then the menu bar is a separate widget and has its own resources. The resource names contain `pane.menubar' (following, as always, the name of the Emacs invocation or `Emacs' which stands for all Emacs invocations). Specify them like this:

Emacs.pane.menubar.subwidget.resource:  value

Each individual string in the menu bar is a subwidget; the subwidget's name is the same as the menu item string. For example, the word `Files' in the menu bar is part of a subwidget named `emacs.pane.menubar.Files'. Most likely, you want to specify the same resources for the whole menu bar. To do this, use `*' instead of a specific subwidget name. For example, to specify the font `8x16' for the menu-bar items, write this:

Emacs.pane.menubar.*.fontList:  8x16

This also specifies the resource value for submenus.

Each item in a submenu in the menu bar also has its own name for X resources; for example, the `Files' submenu has an item named `Save Buffer'. A resource specification for a submenu item looks like this:

Emacs.pane.menubar.popup_*.menu.item.resource: value

For example, here's how to specify the font for the `Save Buffer' item:

Emacs.pane.menubar.popup_*.Files.Save Buffer.fontList: 8x16

For an item in a second-level submenu, such as `Check Message' under `Spell' under `Edit', the resource fits this template:

Emacs.pane.menubar.popup_*.popup_*.menu.resource: value

For example,

Emacs.pane.menubar.popup_*.popup_*.Spell.Check Message: value

It's impossible to specify a resource for all the menu-bar items without also specifying it for the submenus as well. So if you want the submenu items to look different from the menu bar itself, you must ask for that in two steps. First, specify the resource for all of them; then, override the value for submenus alone. Here is an example:

Emacs.pane.menubar.*.fontList:  8x16
Emacs.pane.menubar.popup_*.fontList: 8x16

For toolkit pop-up menus, use `menu*' instead of `pane.menubar'. For example, to specify the font `8x16' for the pop-up menu items, write this:

Emacs.menu*.fontList:  8x16

@medbreak Here is a list of the specific resources for menu bars and pop-up menus:

armColor
The color to show in an armed button.
fontList
The font to use.
marginBottom
marginHeight
marginLeft
marginRight
marginTop
marginWidth
Amount of space to leave around the item, within the border.
borderWidth
The width of border around the menu item, on all sides.
shadowThickness
The width of the border shadow.
bottomShadowColor
The color for the border shadow, on the bottom and the right.
topShadowColor
The color for the border shadow, on the top and the left.

Emacs 19 Antinews

For those users who live backwards in time, here is information about downgrading to Emacs version 19. We hope you will enjoy the greater simplicity that results from the absence of certain Emacs 20 features.

  • The multibyte character and end-of-line conversion support have been eliminated entirely. (Some users consider this a tremendous improvement.) Character codes are limited to the range 0 through 255 and files imported onto Unix-like systems may have a ^M at the end of each line to remind you to control MS-DOG type files.
  • Fontsets, coding systems and input methods have been eliminated as well.
  • The mode line normally displays the string `Emacs', in case you forget what editor you are using.
  • Scroll bars always appear on the right-hand side of the window. This clearly separates them from the text in the window.
  • The M-x customize feature has been replaced with a very simple feature, M-x edit-options. This shows you all the user options right from the start, so you don't have to hunt for the ones you want. It also provides a few commands, such as s and x, to set a user option.
  • The DELETE key does nothing special in Emacs 19 when you use it after selecting a region with the mouse. It does exactly the same thing in that situation as it does at all other times: delete one character backwards.
  • C-x C-w no longer changes the major mode according to the new file name. If you want to change the mode, use M-x normal-mode.
  • In Transient Mark mode, each window displays highlighting for the region as it exists in that window.
  • Outline mode doesn't use overlay properties; instead, it hides a line by converting the preceding newline into code 015. Magically, however, if you save the file, the 015 character appears in the file as a newline.
  • There is now a clever way you can activate the minibuffer recursively even if enable-recursive-minibuffers is nil. All you have to do is switch windows to a non-minibuffer window, and then use a minibuffer command. You can pile up any number of minibuffer levels this way, but M-x top-level will get you out of all of them.
  • We have removed the limit on the length of minibuffer history lists; they now contain all the minibuffer arguments you have used since the beginning of the session.
  • Dynamic abbrev expansion now handles case conversion in a very simple and straightforward way. If you have requested preserving case, it always converts the entire expansion to the case pattern of the abbrev that you have typed in.
  • The compose-mail command does not exist; C-x m now runs mail directly.
  • There is no way to quote a file name with special characters in it. What you see is what you get: if the name looks remote, it is remote.
  • M-x grep-find has been eliminated, because grep has never been lost.
  • Some Dired commands have been rearranged: two-character sequences have been replaced with quick single-character commands:
    • For dired-mark-executables, type *.
    • For dired-mark-directories, type /.
    • For dired-mark-symlinks, type @.
    • For dired-change-marks, type c.
    • For dired-unmark-all-files, type C-M-?.
    • For dired-unmark-all-marks, type C-M-? RET.
    But if you want to use dired-flag-garbage-files, &, you'll just have to stop living in the past.
  • In C mode, you can now specify your preferred style for block comments. If you want to use the style
    /*
blah
blah
*/
    then you should set the variable c-block-comments-indent-p to t.
  • To customize faces used by Font Lock mode, use the variable font-lock-face-attributes. See its documentation string for details.
  • For efficiency, Font Lock mode now uses by default the minimum supported level of decoration for the selected major mode.
  • If you kill a buffer, any registers holding saved positions in that buffer are changed to point into limbo.
  • The function set-frame-font has been renamed to set-default-font.
  • The variable tex-main-file doesn't exist. Of course, you can create the variable by setting it, but that won't do anything special.
  • The scroll-preserve-screen-position variable has been eliminated; and so has the feature that it controls.
  • We have eliminated the functions add-untranslated-filesystem and remove-untranslated-filesystem, and replaced them with a simpler function, using-unix-filesystems.
  • To keep up with decreasing computer memory capacity, many other functions and files have been eliminated in Emacs 19. There's no need to mention them all here. If you try to use one of them, you'll get an error message to tell you that it is undefined or unbound.

Emacs and MS-DOS

This section briefly describes the peculiarities of using Emacs under the MS-DOS "operating system" (also known as "MS-DOG"). If you build Emacs for MS-DOS, the binary will also run on Windows 3.X, Windows NT, Windows 9X, or OS/2 as a DOS application; the information in this chapter applies for all of those systems, if you use an Emacs that was built for MS-DOS.

Note that it is possible to build Emacs specifically for Windows NT or Windows 9X. If you do that, most of this chapter does not apply; instead, you get behavior much closer to what is documented in the rest of the manual, including support for long file names, multiple frames, scroll bars, mouse menus, and subprocesses. However, the section on text files and binary files does still apply. There are also two sections at the end of this chapter which apply specifically for Windows NT and 9X.

Keyboard and Mouse on MS-DOS

The PC keyboard maps use the left ALT key as the META key. You have two choices for emulating the SUPER and HYPER keys: choose either the right CTRL key or the right ALT key by setting the variables dos-hyper-key and dos-super-key to 1 or 2 respectively. If neither dos-super-key nor dos-hyper-key is 1, then by default the right ALT key is also mapped to the META key. However, if the MS-DOS international keyboard support program `KEYB.COM' is installed, Emacs will not map the right ALT to META, since it is used for accessing characters like ~ and @ on non-US keyboard layouts; in this case, you may only use the left ALT as META key.

The variable dos-keypad-mode is a flag variable that controls what key codes are returned by keys in the numeric keypad. You can also define the keypad ENTER key to act like C-j, by putting the following line into your `_emacs' file:

;; Make the Enter key from the Numeric keypad act as C-j.
(define-key function-key-map [kp-enter] [?\C-j])

The key that is called DEL in Emacs (because that's how it is designated on most workstations) is known as BS (backspace) on a PC. That is why the PC-specific terminal initialization remaps the BS key to act as DEL; the DEL key is remapped to act as C-d for the same reasons.

Emacs built for MS-DOS recognizes C-BREAK as a quit character, just like C-g. This is because Emacs cannot detect that you have typed C-g until it is ready for more input. As a consequence, you cannot use C-g to stop a running command (see section Quitting and Aborting). By contrast, C-BREAK is detected as soon as you type it (as C-g is on other systems), so it can be used to stop a running command and for emergency escape (see section Emergency Escape).

Emacs on MS-DOS supports a mouse (on the default terminal only). The mouse commands work as documented, including those that use menus and the menu bar (see section The Menu Bar). Scroll bars don't work in MS-DOS Emacs. PC mice usually have only two buttons; these act as Mouse-1 and Mouse-2, but if you press both of them together, that has the effect of Mouse-3.

Emacs built for MS-DOS supports clipboard operations when it runs on Windows. Commands that put text on the kill ring, or yank text from the ring, check the Windows clipboard first, just as Emacs does on X Windows (see section Mouse Commands for Editing). Only the primary selection and the cut buffer are supported by MS-DOS Emacs on Windows; the secondary selection always appears as empty.

Due to the way clipboard access is implemented by Windows, the length of text you can put into the clipboard is limited by the amount of free DOS memory that is available to Emacs. Usually, up to 620KB of text can be put into the clipboard, but this limit depends on the system configuration and is lower if you run Emacs as a subprocess of another program. If the killed text does not fit, Emacs prints a message saying so, and does not put the text into the clipboard.

Null characters also cannot be put into the Windows clipboard. If the killed text includes null characters, Emacs does not put such text into the clipboard, and prints in the echo area a message to that effect.

The variable dos-display-scancodes, when non-nil, directs Emacs to display the ASCII value and the keyboard scan code of each keystroke; this feature serves as a complement to the view-lossage command, for debugging.

Display on MS-DOS

Display on MS-DOS cannot use font variants, like bold or italic, but it does support multiple faces, each of which can specify a foreground and a background color. Therefore, you can get the full functionality of Emacs packages that use fonts (such as font-lock, Enriched Text mode, and others) by defining the relevant faces to use different colors. Use the list-colors-display command (see section Setting Frame Parameters) and the list-faces-display command (see section Using Multiple Typefaces) to see what colors and faces are available and what they look like.

The section section International Support on MS-DOS, later in this chapter, describes how Emacs displays glyphs and characters which aren't supported by the native font built into the DOS display.

Multiple frames (see section Frames and X Windows) are supported on MS-DOS, but they all overlap, so you only see a single frame at any given moment. That single visible frame occupies the entire screen. When you run Emacs from MS-Windows DOS box, you can make the visible frame smaller than the full screen, but Emacs still cannot display more than a single frame at a time.

The mode4350 command switches the display to 43 or 50 lines, depending on your hardware; the mode25 command switches to the default 80x25 screen size.

By default, Emacs only knows how to set screen sizes of 80 columns by 25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has special video modes that will switch the display to other sizes, you can have Emacs support those too. When you ask Emacs to switch the frame to n rows by m columns dimensions, it checks if there is a variable called screen-dimensions-nxm, and if so, uses its value (which must be an integer) as the video mode to switch to. (Emacs switches to that video mode by calling the BIOS Set Video Mode function with the value of screen-dimensions-nxm in the AL register.) For example, suppose your adapter will switch to 66x80 dimensions when put into video mode 85. Then you can make Emacs support this screen size by putting the following into your `_emacs' file:

(setq screen-dimensions-66x80 85)

Since Emacs on MS-DOS can only set the frame size to specific supported dimensions, it cannot honor every possible frame resizing request. When an unsupported size is requested, Emacs chooses the next larger supported size beyond the specified size. For example, if you ask for 36x80 frame, you will get 40x80 instead.

The variables screen-dimensions-nxm are used only when they exactly match the specified size; the search for the next larger supported size ignores them. In the above example, even if your VGA supports 38x80 dimensions and you define a variable screen-dimensions-38x80 with a suitable value, you will still get 40x80 screen when you ask for a 36x80 frame. If you want to get the 38x80 size in this case, you can do it by setting the variable named screen-dimensions-36x80 with the same video mode value as screen-dimensions-38x80.

Changing frame dimensions on MS-DOS has the effect of changing all the other frames to the new dimensions.

File Names on MS-DOS

MS-DOS normally uses a backslash, `\', to separate name units within a file name, instead of the slash used on other systems. Emacs on MS-DOS permits use of either slash or backslash, and also knows about drive letters in file names.

On MS-DOS, file names are case-insensitive and limited to eight characters, plus optionally a period and three more characters. Emacs knows enough about these limitations to handle file names that were meant for other operating systems. For instance, leading dots `.' in file names are invalid in MS-DOS, so Emacs transparently converts them to underscores `_'; thus your default init file (see section The Init File, `~/.emacs') is called `_emacs' on MS-DOS. Excess characters before or after the period are generally ignored by MS-DOS itself; thus, if you visit the file `LongFileName.EvenLongerExtension', you will silently get `longfile.eve', but Emacs will still display the long file name on the mode line. Other than that, it's up to you to specify file names which are valid under MS-DOS; the transparent conversion as described above only works on file names built into Emacs.

The above restrictions on the file names on MS-DOS make it almost impossible to construct the name of a backup file (see section Single or Numbered Backups) without losing some of the original file name characters. For example, the name of a backup file for `docs.txt' is `docs.tx~' even if single backup is used.

If you run Emacs as a DOS application under Windows 9X, you can turn on support for long file names. If you do that, Emacs doesn't truncate file names or convert them to lower case; instead, it uses the file names that you specify, verbatim. To enable long file name support, set the environment variable LFN to `y' before starting Emacs. Unfortunately, Windows NT doesn't allow DOS programs to access long file names, so Emacs built for MS-DOS will only see their short 8+3 aliases.

MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends that the directory where it is installed is the value of HOME environment variable. That is, if your Emacs binary, `emacs.exe', is in the directory `c:/utils/emacs/bin', then Emacs acts as if HOME were set to `c:/utils/emacs'. In particular, that is where Emacs looks for the init file `_emacs'. With this in mind, you can use `~' in file names as an alias for the home directory, as you would in Unix. You can also set HOME variable in the environment before starting Emacs; its value will then override the above default behavior.

Emacs on MS-DOS handles the directory name `/dev' specially, because of a feature in the emulator libraries of DJGPP that pretends I/O devices have names in that directory. We recommend that you avoid using an actual directory named `/dev' on any disk.

Text Files and Binary Files

GNU Emacs uses newline characters to separate text lines. This is the convention used on Unix, on which GNU Emacs was developed, and on GNU systems since they are modeled on Unix.

MS-DOS and MS-Windows normally use carriage-return linefeed, a two-character sequence, to separate text lines. (Linefeed is the same character as newline.) Therefore, convenient editing of typical files with Emacs requires conversion of these end-of-line (EOL) sequences. And that is what Emacs normally does: it converts carriage-return linefeed into newline when reading files, and converts newline into carriage-return linefeed when writing files. The same mechanism that handles conversion of international character codes does this conversion also (see section Coding Systems).

One consequence of this special format-conversion of most files is that character positions as reported by Emacs (see section Cursor Position Information) do not agree with the file size information known to the operating system.

Some kinds of files should not be converted, because their contents are not really text. Therefore, Emacs on MS-DOS distinguishes certain files as binary files, and reads and writes them verbatim. (This distinction is not part of MS-DOS; it is made by Emacs only.) These include executable programs, compressed archives, etc. Emacs uses the file name to decide whether to treat a file as binary: the variable file-name-buffer-file-type-alist defines the file-name patterns that indicate binary files. Note that if a file name matches one of the patterns for binary files in file-name-buffer-file-type-alist, Emacs uses the no-conversion coding system (see section Coding Systems) which turns off all coding-system conversions, not only the EOL conversion.

In addition, if Emacs recognizes from a file's contents that it uses newline rather than carriage-return linefeed as its line separator, it does not perform conversion when reading or writing that file. Thus, you can read and edit files from Unix or GNU systems on MS-DOS with no special effort, and they will be left with their Unix-style EOLs.

You can visit a file and specify whether to treat a file as text or binary using the commands find-file-text and find-file-binary. End-of-line conversion is part of the general coding system conversion mechanism, so another way to control whether to treat a file as text or binary is with the commands for specifying a coding system (see section Specifying a Coding System). For example, C-x RET c undecided-unix RET C-x C-f foobar.txt visits the file `foobar.txt' without converting the EOLs.

The mode line indicates whether end-of-line translation was used for the current buffer. Normally a colon appears after the coding system letter near the beginning of the mode line. If MS-DOS end-of-line translation is in use for the buffer, this character changes to a backslash.

When you use NFS or Samba to access file systems that reside on computers using Unix or GNU systems, Emacs should not perform end-of-line translation on any files in these file systems--not even when you create a new file. To request this, designate these file systems as untranslated file systems by calling the function add-untranslated-filesystem. It takes one argument: the file system name, including a drive letter and optionally a directory. For example,

(add-untranslated-filesystem "Z:")

designates drive Z as an untranslated file system, and

(add-untranslated-filesystem "Z:\\foo")

designates directory `\foo' on drive Z as an untranslated file system.

Most often you would use add-untranslated-filesystem in your `_emacs' file, or in `site-start.el' so that all the users at your site get the benefit of it.

To countermand the effect of add-untranslated-filesystem, use the function remove-untranslated-filesystem. This function takes one argument, which should be a string just like the one that was used previously with add-untranslated-filesystem.

Printing and MS-DOS

Printing commands, such as lpr-buffer (see section Hardcopy Output) and ps-print-buffer (see section Postscript Hardcopy) can work in MS-DOS and MS-Windows by sending the output to one of the printer ports, if a Unix-style lpr program is unavailable. This behaviour is controlled by the same variables that control printing with lpr on Unix (see section Hardcopy Output, see section Variables for Postscript Hardcopy), but the defaults for these variables on MS-DOS and MS-Windows are not the same as the defaults on Unix.

If you want to use your local printer, printing on it in the usual DOS manner, then set the Lisp variable lpr-command to "" (its default value) and printer-name to the name of the printer port--for example, "PRN", the usual local printer port (that's the default), or "LPT2", or "COM1" for a serial printer. You can also set printer-name to a file name, in which case "printed" output is actually appended to that file. If you set printer-name to "NUL", printed output is silently discarded (sent to the system null device).

On MS-Windows, when the Windows network software is installed, you can also use a printer shared by another machine by setting printer-name to the UNC share name for that printer--for example, "//joes_pc/hp4si". (It doesn't matter whether you use forward slashes or backslashes here.) To find out the names of shared printers, run the command `net view' at a DOS command prompt to obtain a list of servers, and `net view server-name' to see the names of printers (and directories) shared by that server.

If you set printer-name to a file name, it's best to use an absolute file name. Emacs changes the working directory according to the default directory of the current buffer, so if the file name in printer-name is relative, you will end up with several such files, each one in the directory of the buffer from which the printing was done.

The commands print-buffer and print-region call the pr program, or use special switches to the lpr program, to produce headers on each printed page. MS-DOS and MS-Windows don't normally have these programs, so by default, the variable lpr-headers-switches is set so that the requests to print page headers are silently ignored. Thus, print-buffer and print-region produce the same output as lpr-buffer and lpr-region, respectively. If you do have a suitable pr program (for example, from GNU Textutils), set lpr-headers-switches to nil; Emacs will then call pr to produce the page headers, and print the resulting output as specified by printer-name.

Finally, if you do have an lpr work-alike, you can set the variable lpr-command to "lpr". Then Emacs will use lpr for printing, as on other systems. (If the name of the program isn't lpr, set lpr-command to specify where to find it.) The variable lpr-switches has its standard meaning when lpr-command is not "". If the variable printer-name has a string value, it is used as the value for the -P option to lpr, as on Unix.

A parallel set of variables, ps-lpr-command, ps-lpr-switches, and ps-printer-name (see section Variables for Postscript Hardcopy), defines how PostScript files should be printed. These variables are used in the same way as the corresponding variables described above for non-PostScript printing. Thus, the value of ps-printer-name is used as the name of the device (or file) to which PostScript output is sent, just as printer-name is used for non-PostScript printing. (There are two distinct sets of variables in case you have two printers attached to two different ports, and only one of them is a PostScript printer.)

The default value of the variable ps-lpr-command is "", which causes PostScript output to be sent to the printer port specified by ps-printer-name, but ps-lpr-command can also be set to the name of a program which will accept PostScript files. Thus, if you have a non-PostScript printer, you can set this variable to the name of a PostScript interpreter program (such as Ghostscript). Any switches that need to be passed to the interpreter program are specified using ps-lpr-switches. (If the value of ps-printer-name is a string, it will be added to the list of switches as the value for the -P option. This is probably only useful if you are using lpr, so when using an interpreter typically you would set ps-printer-name to something other than a string so it is ignored.)

For example, to use Ghostscript for printing on an Epson printer connected to the `LPT2' port, put this in your `_emacs' file:

(setq ps-printer-name t)  ; Ghostscript doesn't understand -P
(setq ps-lpr-command "c:/gs/gs386")
(setq ps-lpr-switches '("-q" "-dNOPAUSE"
            "-sDEVICE=epson"
            "-r240x72"
            "-sOutputFile=LPT2"
            "-Ic:/gs"))

(This assumes that Ghostscript is installed in the `"c:/gs"' directory.)

For backwards compatibility, the value of dos-printer (dos-ps-printer), if it has a value, overrides the value of printer-name (ps-printer-name), on MS-DOS and MS-Windows only.

International Support on MS-DOS

Emacs on MS-DOS supports the same international character sets as it does on Unix and other platforms (see section International Character Set Support), including coding systems for converting between the different character sets. However, due to incompatibilities between MS-DOS/MS-Windows and Unix, there are several DOS-specific aspects of this support that users should be aware of. This section describes these aspects.

M-x dos-codepage-setup
Set up Emacs display and coding systems as appropriate for the current DOS codepage.
M-x codepage-setup
Create a coding system for a certain DOS codepage.

MS-DOS is designed to support one character set of 256 characters at any given time, but gives you a variety of character sets to choose from. The alternative character sets are known as DOS codepages. Each codepage includes all 128 ASCII characters, but the other 128 characters (codes 128 through 255) vary from one codepage to another. Each DOS codepage is identified by a 3-digit number, such as 850, 862, etc.

In contrast to X Windows, which lets you use several fonts at the same time, MS-DOS doesn't allow use of several codepages in a single session. Instead, MS-DOS loads a single codepage at system startup, and you must reboot MS-DOS to change it(7). Much the same limitation applies when you run DOS executables on other systems such as MS-Windows.

If you invoke Emacs on MS-DOS with the `--unibyte' option (see section Initial Options), Emacs does not perform any conversion of non-ASCII characters. Instead, it reads and writes any non-ASCII characters verbatim, and sends their 8-bit codes to the display verbatim. Thus, unibyte Emacs on MS-DOS supports the current codepage, whatever it may be, but cannot even represent any other characters.

For multibyte operation on MS-DOS, Emacs needs to know which characters the chosen DOS codepage can display. So it queries the system shortly after startup to get the chosen codepage number, and stores the number in the variable dos-codepage. Some systems return the default value 437 for the current codepage, even though the actual codepage is different. (This typically happens when you use the codepage built into the display hardware.) You can specify a different codepage for Emacs to use by setting the variable dos-codepage in your init file.

Multibyte Emacs supports only certain DOS codepages: those which can display Far-Eastern scripts, like the Japanese codepage 932, and those that encode a single ISO 8859 character set.

The Far-Eastern codepages can directly display one of the MULE character sets for these countries, so Emacs simply sets up to use the appropriate terminal coding system that is supported by the codepage. The special features described in the rest of this section mostly pertain to codepages that encode ISO 8859 character sets.

For the codepages which correspond to one of the ISO character sets, Emacs knows the character set name based on the codepage number. Emacs automatically creates a coding system to support reading and writing files that use the current codepage, and uses this coding system by default. The name of this coding system is cpnnn, where nnn is the codepage number.(8) (`c' with cedilla) has code 231 in the standard Latin-1 character set, but the corresponding DOS codepage 850 uses code 135 for this glyph.}

All the cpnnn coding systems use the letter `D' (for "DOS") as their mode-line mnemonic. Since both the terminal coding system and the default coding system for file I/O are set to the proper cpnnn coding system at startup, it is normal for the mode line on MS-DOS to begin with `-DD\-'. See section The Mode Line. Far-Eastern DOS terminals do not use the cpnnn coding systems, and thus their initial mode line looks like on Unix.

Since the codepage number also indicates which script you are using, Emacs automatically runs set-language-environment to select the language environment for that script (see section Language Environments).

If a buffer contains a character belonging to some other ISO 8859 character set, not the one that the chosen DOS codepage supports, Emacs displays it using a sequence of ASCII characters. For example, if the current codepage doesn't have a glyph for the letter ``o' (small `o' with a grave accent), it is displayed as `{`o}', where the braces serve as a visual indication that this is a single character. (This may look awkward for some non-Latin characters, such as those from Greek or Hebrew alphabets, but it is still readable by a person who knows the language.) Even though the character may occupy several columns on the screen, it is really still just a single character, and all Emacs commands treat it as one.

Not all characters in DOS codepages correspond to ISO 8859 characters--some are used for other purposes, such as box-drawing characters and other graphics. Emacs cannot represent these characters internally, so when you read a file that uses these characters, they are converted into a particular character code, specified by the variable dos-unsupported-character-glyph.

Emacs supports many other characters sets aside from ISO 8859, but it cannot display them on MS-DOS. So if one of these multibyte characters appears in a buffer, Emacs on MS-DOS displays them as specified by the dos-unsupported-character-glyph variable; by default, this glyph is an empty triangle. Use the C-u C-x = command to display the actual code and character set of such characters. See section Cursor Position Information.

By default, Emacs defines a coding system to support the current codepage. To define a coding system for some other codepage (e.g., to visit a file written on a DOS machine in another country), use the M-x codepage-setup command. It prompts for the 3-digit code of the codepage, with completion, then creates the coding system for the specified codepage. You can then use the new coding system to read and write files, but you must specify it explicitly for the file command when you want to use it (see section Specifying a Coding System).

These coding systems are also useful for visiting a file encoded using a DOS codepage, using Emacs running on some other operating system.

Subprocesses on MS-DOS

Because MS-DOS is a single-process "operating system," asynchronous subprocesses are not available. In particular, Shell mode and its variants do not work. Most Emacs features that use asynchronous subprocesses also don't work on MS-DOS, including spelling correction and GUD. When in doubt, try and see; commands that don't work print an error message saying that asynchronous processes aren't supported.

Compilation under Emacs with M-x compile, searching files with M-x grep and displaying differences between files with M-x diff do work, by running the inferior processes synchronously. This means you cannot do any more editing until the inferior process finishes.

By contrast, Emacs compiled as native Windows application does support asynchronous subprocesses. See section Subprocesses on Windows 95 and NT.

Printing commands, such as lpr-buffer (see section Hardcopy Output) and ps-print-buffer (see section Postscript Hardcopy), work in MS-DOS by sending the output to one of the printer ports. See section Printing and MS-DOS.

When you run a subprocess synchronously on MS-DOS, make sure the program terminates and does not try to read keyboard input. If the program does not terminate on its own, you will be unable to terminate it, because MS-DOS provides no general way to terminate a process. Pressing C-c or C-BREAK might sometimes help in these cases.

Accessing files on other machines is not supported on MS-DOS. Other network-oriented commands such as sending mail, Web browsing, remote login, etc., don't work either, unless network access is built into MS-DOS with some network redirector.

Dired on MS-DOS uses the ls-lisp package where other platforms use the system ls command. Therefore, Dired on MS-DOS supports only some of the possible options you can mention in the dired-listing-switches variable. The options that work are `-A', `-a', `-c', `-i', `-r', `-S', `-s', `-t', and `-u'.

Subprocesses on Windows 95 and NT

Emacs compiled as a native Windows application (as opposed to the DOS version) includes full support for asynchronous subprocesses. In the Windows version, synchronous and asynchronous subprocesses work fine on both Windows 95 and Windows NT as long as you run only 32-bit Windows applications. However, when you run a DOS application in a subprocess, you may encounter problems or be unable to run the application at all; and if you run two DOS applications at the same time in two subprocesses, you may have to reboot your system.

Since the standard command interpreter (and most command line utilities) on Windows 95 are DOS applications, these problems are significant when using that system. But there's nothing we can do about them; only Microsoft can fix them.

If you run just one DOS application subprocess, the subprocess should work as expected as long as it is "well-behaved" and does not perform direct screen access or other unusual actions. If you have a CPU monitor application, your machine will appear to be 100% busy even when the DOS application is idle, but this is only an artifact of the way CPU monitors measure processor load.

You must terminate the DOS application before you start any other DOS application in a different subprocess. Emacs is unable to interrupt or terminate a DOS subprocess. The only way you can terminate such a subprocess is by giving it a command that tells its program to exit.

If you attempt to run two DOS applications at the same time in separate subprocesses, the second one that is started will be suspended until the first one finishes, even if either or both of them are asynchronous.

If you can go to the first subprocess, and tell it to exit, the second subprocess should continue normally. However, if the second subprocess is synchronous, Emacs itself will be hung until the first subprocess finishes. If it will not finish without user input, then you have no choice but to reboot if you are running on Windows 95. If you are running on Windows NT, you can use a process viewer application to kill the appropriate instance of ntvdm instead (this will terminate both DOS subprocesses).

If you have to reboot Windows 95 in this situation, do not use the Shutdown command on the Start menu; that usually hangs the system. Instead, type CTL-ALT-DEL and then choose Shutdown. That usually works, although it may take a few minutes to do its job.

Using the System Menu on Windows

Emacs compiled as a native Windows application normally turns off the Windows feature that tapping the ALT key invokes the Windows menu. The reason is that the ALT also serves as META in Emacs. When using Emacs, users often press the META key temporarily and then change their minds; if this has the effect of bringing up the Windows menu, it alters the meaning of subsequent commands. Many users find this frustrating.

You can reenable Windows's default handling of tapping the ALT key by setting w32-pass-alt-to-system to a non-nil value.

The GNU Manifesto

The GNU Manifesto which appears below was written by Richard Stallman at the beginning of the GNU project, to ask for participation and support. For the first few years, it was updated in minor ways to account for developments, but now it seems best to leave it unchanged as most people have seen it.

Since that time, we have learned about certain common misunderstandings that different wording could help avoid. Footnotes added in 1993 help clarify these points.

For up-to-date information about the available GNU software, please see the latest issue of the GNU's Bulletin. The list is much too long to include here.

What's GNU? Gnu's Not Unix!

GNU, which stands for Gnu's Not Unix, is the name for the complete Unix-compatible software system which I am writing so that I can give it away free to everyone who can use it.(9) Several other volunteers are helping me. Contributions of time, money, programs and equipment are greatly needed.

So far we have an Emacs text editor with Lisp for writing editor commands, a source level debugger, a yacc-compatible parser generator, a linker, and around 35 utilities. A shell (command interpreter) is nearly completed. A new portable optimizing C compiler has compiled itself and may be released this year. An initial kernel exists but many more features are needed to emulate Unix. When the kernel and compiler are finished, it will be possible to distribute a GNU system suitable for program development. We will use TeX as our text formatter, but an nroff is being worked on. We will use the free, portable X window system as well. After this we will add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of other things, plus on-line documentation. We hope to supply, eventually, everything useful that normally comes with a Unix system, and more.

GNU will be able to run Unix programs, but will not be identical to Unix. We will make all improvements that are convenient, based on our experience with other operating systems. In particular, we plan to have longer file names, file version numbers, a crashproof file system, file name completion perhaps, terminal-independent display support, and perhaps eventually a Lisp-based window system through which several Lisp programs and ordinary Unix programs can share a screen. Both C and Lisp will be available as system programming languages. We will try to support UUCP, MIT Chaosnet, and Internet protocols for communication.

GNU is aimed initially at machines in the 68000/16000 class with virtual memory, because they are the easiest machines to make it run on. The extra effort to make it run on smaller machines will be left to someone who wants to use it on them.

To avoid horrible confusion, please pronounce the `G' in the word `GNU' when it is the name of this project.

Why I Must Write GNU

I consider that the golden rule requires that if I like a program I must share it with other people who like it. Software sellers want to divide the users and conquer them, making each user agree not to share with others. I refuse to break solidarity with other users in this way. I cannot in good conscience sign a nondisclosure agreement or a software license agreement. For years I worked within the Artificial Intelligence Lab to resist such tendencies and other inhospitalities, but eventually they had gone too far: I could not remain in an institution where such things are done for me against my will.

So that I can continue to use computers without dishonor, I have decided to put together a sufficient body of free software so that I will be able to get along without any software that is not free. I have resigned from the AI lab to deny MIT any legal excuse to prevent me from giving GNU away.

Why GNU Will Be Compatible with Unix

Unix is not my ideal system, but it is not too bad. The essential features of Unix seem to be good ones, and I think I can fill in what Unix lacks without spoiling them. And a system compatible with Unix would be convenient for many other people to adopt.

How GNU Will Be Available

GNU is not in the public domain. Everyone will be permitted to modify and redistribute GNU, but no distributor will be allowed to restrict its further redistribution. That is to say, proprietary modifications will not be allowed. I want to make sure that all versions of GNU remain free.

Why Many Other Programmers Want to Help

I have found many other programmers who are excited about GNU and want to help.

Many programmers are unhappy about the commercialization of system software. It may enable them to make more money, but it requires them to feel in conflict with other programmers in general rather than feel as comrades. The fundamental act of friendship among programmers is the sharing of programs; marketing arrangements now typically used essentially forbid programmers to treat others as friends. The purchaser of software must choose between friendship and obeying the law. Naturally, many decide that friendship is more important. But those who believe in law often do not feel at ease with either choice. They become cynical and think that programming is just a way of making money.

By working on and using GNU rather than proprietary programs, we can be hospitable to everyone and obey the law. In addition, GNU serves as an example to inspire and a banner to rally others to join us in sharing. This can give us a feeling of harmony which is impossible if we use software that is not free. For about half the programmers I talk to, this is an important happiness that money cannot replace.

How You Can Contribute

I am asking computer manufacturers for donations of machines and money. I'm asking individuals for donations of programs and work.

One consequence you can expect if you donate machines is that GNU will run on them at an early date. The machines should be complete, ready to use systems, approved for use in a residential area, and not in need of sophisticated cooling or power.

I have found very many programmers eager to contribute part-time work for GNU. For most projects, such part-time distributed work would be very hard to coordinate; the independently-written parts would not work together. But for the particular task of replacing Unix, this problem is absent. A complete Unix system contains hundreds of utility programs, each of which is documented separately. Most interface specifications are fixed by Unix compatibility. If each contributor can write a compatible replacement for a single Unix utility, and make it work properly in place of the original on a Unix system, then these utilities will work right when put together. Even allowing for Murphy to create a few unexpected problems, assembling these components will be a feasible task. (The kernel will require closer communication and will be worked on by a small, tight group.)

If I get donations of money, I may be able to hire a few people full or part time. The salary won't be high by programmers' standards, but I'm looking for people for whom building community spirit is as important as making money. I view this as a way of enabling dedicated people to devote their full energies to working on GNU by sparing them the need to make a living in another way.

Why All Computer Users Will Benefit

Once GNU is written, everyone will be able to obtain good system software free, just like air.(10)

This means much more than just saving everyone the price of a Unix license. It means that much wasteful duplication of system programming effort will be avoided. This effort can go instead into advancing the state of the art.

Complete system sources will be available to everyone. As a result, a user who needs changes in the system will always be free to make them himself, or hire any available programmer or company to make them for him. Users will no longer be at the mercy of one programmer or company which owns the sources and is in sole position to make changes.

Schools will be able to provide a much more educational environment by encouraging all students to study and improve the system code. Harvard's computer lab used to have the policy that no program could be installed on the system if its sources were not on public display, and upheld it by actually refusing to install certain programs. I was very much inspired by this.

Finally, the overhead of considering who owns the system software and what one is or is not entitled to do with it will be lifted.

Arrangements to make people pay for using a program, including licensing of copies, always incur a tremendous cost to society through the cumbersome mechanisms necessary to figure out how much (that is, which programs) a person must pay for. And only a police state can force everyone to obey them. Consider a space station where air must be manufactured at great cost: charging each breather per liter of air may be fair, but wearing the metered gas mask all day and all night is intolerable even if everyone can afford to pay the air bill. And the TV cameras everywhere to see if you ever take the mask off are outrageous. It's better to support the air plant with a head tax and chuck the masks.

Copying all or parts of a program is as natural to a programmer as breathing, and as productive. It ought to be as free.

Some Easily Rebutted Objections to GNU's Goals

"Nobody will use it if it is free, because that means they can't rely on any support."

"You have to charge for the program to pay for providing the support."

If people would rather pay for GNU plus service than get GNU free without service, a company to provide just service to people who have obtained GNU free ought to be profitable.(11)

We must distinguish between support in the form of real programming work and mere handholding. The former is something one cannot rely on from a software vendor. If your problem is not shared by enough people, the vendor will tell you to get lost.

If your business needs to be able to rely on support, the only way is to have all the necessary sources and tools. Then you can hire any available person to fix your problem; you are not at the mercy of any individual. With Unix, the price of sources puts this out of consideration for most businesses. With GNU this will be easy. It is still possible for there to be no available competent person, but this problem cannot be blamed on distribution arrangements. GNU does not eliminate all the world's problems, only some of them.

Meanwhile, the users who know nothing about computers need handholding: doing things for them which they could easily do themselves but don't know how.

Such services could be provided by companies that sell just hand-holding and repair service. If it is true that users would rather spend money and get a product with service, they will also be willing to buy the service having got the product free. The service companies will compete in quality and price; users will not be tied to any particular one. Meanwhile, those of us who don't need the service should be able to use the program without paying for the service.

"You cannot reach many people without advertising, and you must charge for the program to support that."

"It's no use advertising a program people can get free."

There are various forms of free or very cheap publicity that can be used to inform numbers of computer users about something like GNU. But it may be true that one can reach more microcomputer users with advertising. If this is really so, a business which advertises the service of copying and mailing GNU for a fee ought to be successful enough to pay for its advertising and more. This way, only the users who benefit from the advertising pay for it.

On the other hand, if many people get GNU from their friends, and such companies don't succeed, this will show that advertising was not really necessary to spread GNU. Why is it that free market advocates don't want to let the free market decide this?(12)

"My company needs a proprietary operating system to get a competitive edge."

GNU will remove operating system software from the realm of competition. You will not be able to get an edge in this area, but neither will your competitors be able to get an edge over you. You and they will compete in other areas, while benefiting mutually in this one. If your business is selling an operating system, you will not like GNU, but that's tough on you. If your business is something else, GNU can save you from being pushed into the expensive business of selling operating systems.

I would like to see GNU development supported by gifts from many manufacturers and users, reducing the cost to each.(13)

"Don't programmers deserve a reward for their creativity?"

If anything deserves a reward, it is social contribution. Creativity can be a social contribution, but only in so far as society is free to use the results. If programmers deserve to be rewarded for creating innovative programs, by the same token they deserve to be punished if they restrict the use of these programs.

"Shouldn't a programmer be able to ask for a reward for his creativity?"

There is nothing wrong with wanting pay for work, or seeking to maximize one's income, as long as one does not use means that are destructive. But the means customary in the field of software today are based on destruction.

Extracting money from users of a program by restricting their use of it is destructive because the restrictions reduce the amount and the ways that the program can be used. This reduces the amount of wealth that humanity derives from the program. When there is a deliberate choice to restrict, the harmful consequences are deliberate destruction.

The reason a good citizen does not use such destructive means to become wealthier is that, if everyone did so, we would all become poorer from the mutual destructiveness. This is Kantian ethics; or, the Golden Rule. Since I do not like the consequences that result if everyone hoards information, I am required to consider it wrong for one to do so. Specifically, the desire to be rewarded for one's creativity does not justify depriving the world in general of all or part of that creativity.

"Won't programmers starve?"

I could answer that nobody is forced to be a programmer. Most of us cannot manage to get any money for standing on the street and making faces. But we are not, as a result, condemned to spend our lives standing on the street making faces, and starving. We do something else.

But that is the wrong answer because it accepts the questioner's implicit assumption: that without ownership of software, programmers cannot possibly be paid a cent. Supposedly it is all or nothing.

The real reason programmers will not starve is that it will still be possible for them to get paid for programming; just not paid as much as now.

Restricting copying is not the only basis for business in software. It is the most common basis because it brings in the most money. If it were prohibited, or rejected by the customer, software business would move to other bases of organization which are now used less often. There are always numerous ways to organize any kind of business.

Probably programming will not be as lucrative on the new basis as it is now. But that is not an argument against the change. It is not considered an injustice that sales clerks make the salaries that they now do. If programmers made the same, that would not be an injustice either. (In practice they would still make considerably more than that.)

"Don't people have a right to control how their creativity is used?"

"Control over the use of one's ideas" really constitutes control over other people's lives; and it is usually used to make their lives more difficult.

People who have studied the issue of intellectual property rights carefully (such as lawyers) say that there is no intrinsic right to intellectual property. The kinds of supposed intellectual property rights that the government recognizes were created by specific acts of legislation for specific purposes.

For example, the patent system was established to encourage inventors to disclose the details of their inventions. Its purpose was to help society rather than to help inventors. At the time, the life span of 17 years for a patent was short compared with the rate of advance of the state of the art. Since patents are an issue only among manufacturers, for whom the cost and effort of a license agreement are small compared with setting up production, the patents often do not do much harm. They do not obstruct most individuals who use patented products.

The idea of copyright did not exist in ancient times, when authors frequently copied other authors at length in works of non-fiction. This practice was useful, and is the only way many authors' works have survived even in part. The copyright system was created expressly for the purpose of encouraging authorship. In the domain for which it was invented--books, which could be copied economically only on a printing press--it did little harm, and did not obstruct most of the individuals who read the books.

All intellectual property rights are just licenses granted by society because it was thought, rightly or wrongly, that society as a whole would benefit by granting them. But in any particular situation, we have to ask: are we really better off granting such license? What kind of act are we licensing a person to do?

The case of programs today is very different from that of books a hundred years ago. The fact that the easiest way to copy a program is from one neighbor to another, the fact that a program has both source code and object code which are distinct, and the fact that a program is used rather than read and enjoyed, combine to create a situation in which a person who enforces a copyright is harming society as a whole both materially and spiritually; in which a person should not do so regardless of whether the law enables him to.

"Competition makes things get done better."

The paradigm of competition is a race: by rewarding the winner, we encourage everyone to run faster. When capitalism really works this way, it does a good job; but its defenders are wrong in assuming it always works this way. If the runners forget why the reward is offered and become intent on winning, no matter how, they may find other strategies--such as, attacking other runners. If the runners get into a fist fight, they will all finish late.

Proprietary and secret software is the moral equivalent of runners in a fist fight. Sad to say, the only referee we've got does not seem to object to fights; he just regulates them ("For every ten yards you run, you can fire one shot"). He really ought to break them up, and penalize runners for even trying to fight.

"Won't everyone stop programming without a monetary incentive?"

Actually, many people will program with absolutely no monetary incentive. Programming has an irresistible fascination for some people, usually the people who are best at it. There is no shortage of professional musicians who keep at it even though they have no hope of making a living that way.

But really this question, though commonly asked, is not appropriate to the situation. Pay for programmers will not disappear, only become less. So the right question is, will anyone program with a reduced monetary incentive? My experience shows that they will.

For more than ten years, many of the world's best programmers worked at the Artificial Intelligence Lab for far less money than they could have had anywhere else. They got many kinds of non-monetary rewards: fame and appreciation, for example. And creativity is also fun, a reward in itself.

Then most of them left when offered a chance to do the same interesting work for a lot of money.

What the facts show is that people will program for reasons other than riches; but if given a chance to make a lot of money as well, they will come to expect and demand it. Low-paying organizations do poorly in competition with high-paying ones, but they do not have to do badly if the high-paying ones are banned.

"We need the programmers desperately. If they demand that we stop helping our neighbors, we have to obey."

You're never so desperate that you have to obey this sort of demand. Remember: millions for defense, but not a cent for tribute!

"Programmers need to make a living somehow."

In the short run, this is true. However, there are plenty of ways that programmers could make a living without selling the right to use a program. This way is customary now because it brings programmers and businessmen the most money, not because it is the only way to make a living. It is easy to find other ways if you want to find them. Here are a number of examples.

A manufacturer introducing a new computer will pay for the porting of operating systems onto the new hardware.

The sale of teaching, hand-holding and maintenance services could also employ programmers.

People with new ideas could distribute programs as freeware, asking for donations from satisfied users, or selling hand-holding services. I have met people who are already working this way successfully.

Users with related needs can form users' groups, and pay dues. A group would contract with programming companies to write programs that the group's members would like to use.

All sorts of development can be funded with a Software Tax:

Suppose everyone who buys a computer has to pay x percent of the price as a software tax. The government gives this to an agency like the NSF to spend on software development.

But if the computer buyer makes a donation to software development himself, he can take a credit against the tax. He can donate to the project of his own choosing--often, chosen because he hopes to use the results when it is done. He can take a credit for any amount of donation up to the total tax he had to pay.

The total tax rate could be decided by a vote of the payers of the tax, weighted according to the amount they will be taxed on.

The consequences:

  • The computer-using community supports software development.
  • This community decides what level of support is needed.
  • Users who care which projects their share is spent on can choose this for themselves.

In the long run, making programs free is a step toward the post-scarcity world, where nobody will have to work very hard just to make a living. People will be free to devote themselves to activities that are fun, such as programming, after spending the necessary ten hours a week on required tasks such as legislation, family counseling, robot repair and asteroid prospecting. There will be no need to be able to make a living from programming.

We have already greatly reduced the amount of work that the whole society must do for its actual productivity, but only a little of this has translated itself into leisure for workers because much nonproductive activity is required to accompany productive activity. The main causes of this are bureaucracy and isometric struggles against competition. Free software will greatly reduce these drains in the area of software production. We must do this, in order for technical gains in productivity to translate into less work for us.

Glossary

Abbrev
An abbrev is a text string which expands into a different text string when present in the buffer. For example, you might define a few letters as an abbrev for a long phrase that you want to insert frequently. See section Abbrevs.
Aborting
Aborting means getting out of a recursive edit (q.v.). The commands C-] and M-x top-level are used for this. See section Quitting and Aborting.
Alt
Alt is the name of a modifier bit which a keyboard input character may have. To make a character Alt, type it while holding down the ALT key. Such characters are given names that start with Alt- (usually written A- for short). (Note that many terminals have a key labeled ALT which is really a META key.) See section Kinds of User Input.
ASCII character
An ASCII character is either an ASCII control character or an ASCII printing character. See section Kinds of User Input.
ASCII control character
An ASCII control character is the Control version of an upper-case letter, or the Control version of one of the characters `@[\]^_?'.
ASCII printing character
ASCII printing characters include letters, digits, space, and these punctuation characters: `!@#$%^& *()_-+=|\~` {}[]:;"' <>,.?/'.
Auto Fill Mode
Auto Fill mode is a minor mode in which text that you insert is automatically broken into lines of fixed width. See section Filling Text.
Auto Saving
Auto saving is the practice of saving the contents of an Emacs buffer in a specially-named file, so that the information will not be lost if the buffer is lost due to a system error or user error. See section Auto-Saving: Protection Against Disasters.
Backup File
A backup file records the contents that a file had before the current editing session. Emacs makes backup files automatically to help you track down or cancel changes you later regret making. See section Backup Files.
Balance Parentheses
Emacs can balance parentheses manually or automatically. Manual balancing is done by the commands to move over balanced expressions (see section Lists and Sexps). Automatic balancing is done by blinking or highlighting the parenthesis that matches one just inserted (see section Automatic Display Of Matching Parentheses).
Bind
To bind a key sequence means to give it a binding (q.v.). See section Changing Key Bindings Interactively.
Binding
A key sequence gets its meaning in Emacs by having a binding, which is a command (q.v.), a Lisp function that is run when the user types that sequence. See section Keys and Commands. Customization often involves rebinding a character to a different command function. The bindings of all key sequences are recorded in the keymaps (q.v.). See section Keymaps.
Blank Lines
Blank lines are lines that contain only whitespace. Emacs has several commands for operating on the blank lines in the buffer.
Buffer
The buffer is the basic editing unit; one buffer corresponds to one text being edited. You can have several buffers, but at any time you are editing only one, the `selected' buffer, though several can be visible when you are using multiple windows (q.v.). Most buffers are visiting (q.v.) some file. See section Using Multiple Buffers.
Buffer Selection History
Emacs keeps a buffer selection history which records how recently each Emacs buffer has been selected. This is used for choosing a buffer to select. See section Using Multiple Buffers.
Button Down Event
A button down event is the kind of input event generated right away when you press a mouse button. See section Rebinding Mouse Buttons.
C-
C- in the name of a character is an abbreviation for Control. See section Kinds of User Input.
C-M-
C-M- in the name of a character is an abbreviation for Control-Meta. See section Kinds of User Input.
Case Conversion
Case conversion means changing text from upper case to lower case or vice versa. See section Case Conversion Commands, for the commands for case conversion.
Character
Characters form the contents of an Emacs buffer; see section Character Set for Text. Also, key sequences (q.v.) are usually made up of characters (though they may include other input events as well). See section Kinds of User Input.
Character Set
Emacs supports a number of character sets, each of which represents a particular alphabet or script. See section International Character Set Support.
Click Event
A click event is the kind of input event generated when you press a mouse button and release it without moving the mouse. See section Rebinding Mouse Buttons.
Coding System
A coding system is an encoding for representing text characters in a file or in a stream of information. Emacs has the ability to convert text to or from a variety of coding systems when reading or writing it. See section Coding Systems.
Command
A command is a Lisp function specially defined to be able to serve as a key binding in Emacs. When you type a key sequence (q.v.), its binding (q.v.) is looked up in the relevant keymaps (q.v.) to find the command to run. See section Keys and Commands.
Command Name
A command name is the name of a Lisp symbol which is a command (see section Keys and Commands). You can invoke any command by its name using M-x (see section Running Commands by Name).
Comment
A comment is text in a program which is intended only for humans reading the program, and which is marked specially so that it will be ignored when the program is loaded or compiled. Emacs offers special commands for creating, aligning and killing comments. See section Manipulating Comments.
Compilation
Compilation is the process of creating an executable program from source code. Emacs has commands for compiling files of Emacs Lisp code (see section `Byte Compilation' in the Emacs Lisp Reference Manual) and programs in C and other languages (see section Running Compilations under Emacs).
Complete Key
A complete key is a key sequence which fully specifies one action to be performed by Emacs. For example, X and C-f and C-x m are complete keys. Complete keys derive their meanings from being bound (q.v.) to commands (q.v.). Thus, X is conventionally bound to a command to insert `X' in the buffer; C-x m is conventionally bound to a command to begin composing a mail message. See section Keys.
Completion
Completion is what Emacs does when it automatically fills out an abbreviation for a name into the entire name. Completion is done for minibuffer (q.v.) arguments when the set of possible valid inputs is known; for example, on command names, buffer names, and file names. Completion occurs when TAB, SPC or RET is typed. See section Completion.
Continuation Line
When a line of text is longer than the width of the window, it takes up more than one screen line when displayed. We say that the text line is continued, and all screen lines used for it after the first are called continuation lines. See section Basic Editing Commands.
Control Character
A control character is a character that you type by holding down the CTRL key. Some control characters also have their own keys, so that you can type them without using CTRL. For example, RET, TAB, ESC and DEL are all control characters. See section Kinds of User Input.
Copyleft
A copyleft is a notice giving the public legal permission to redistribute a program or other work of art. Copylefts are used by left-wing programmers to promote freedom and cooperation, just as copyrights are used by right-wing programmers to gain power over other people. The particular form of copyleft used by the GNU project is called the GNU General Public License. See section GNU GENERAL PUBLIC LICENSE.
Current Buffer
The current buffer in Emacs is the Emacs buffer on which most editing commands operate. You can select any Emacs buffer as the current one. See section Using Multiple Buffers.
Current Line
The line point is on (see section Point).
Current Paragraph
The paragraph that point is in. If point is between paragraphs, the current paragraph is the one that follows point. See section Paragraphs.
Current Defun
The defun (q.v.) that point is in. If point is between defuns, the current defun is the one that follows point. See section Defuns.
Cursor
The cursor is the rectangle on the screen which indicates the position called point (q.v.) at which insertion and deletion takes place. The cursor is on or under the character that follows point. Often people speak of `the cursor' when, strictly speaking, they mean `point'. See section Basic Editing Commands.
Customization
Customization is making minor changes in the way Emacs works. It is often done by setting variables (see section Variables) or by rebinding key sequences (see section Keymaps).
Default Argument
The default for an argument is the value that will be assumed if you do not specify one. When the minibuffer is used to read an argument, the default argument is used if you just type RET. See section The Minibuffer.
Default Directory
When you specify a file name that does not start with `/' or `~', it is interpreted relative to the current buffer's default directory. See section Minibuffers for File Names.
Defun
A defun is a list at the top level of parenthesis or bracket structure in a program. It is so named because most such lists in Lisp programs are calls to the Lisp function defun. See section Defuns.
DEL
DEL is a character that runs the command to delete one character of text. See section Basic Editing Commands.
Deletion
Deletion means erasing text without copying it into the kill ring (q.v.). The alternative is killing (q.v.). See section Deletion and Killing.
Deletion of Files
Deleting a file means erasing it from the file system. See section Miscellaneous File Operations.
Deletion of Messages
Deleting a message means flagging it to be eliminated from your mail file. Until you expunge (q.v.) the Rmail file, you can still undelete the messages you have deleted. See section Deleting Messages.
Deletion of Windows
Deleting a window means eliminating it from the screen. Other windows expand to use up the space. The deleted window can never come back, but no actual text is thereby lost. See section Multiple Windows.
Directory
File directories are named collections in the file system, within which you can place individual files or subdirectories. See section File Directories.
Dired
Dired is the Emacs facility that displays the contents of a file directory and allows you to "edit the directory," performing operations on the files in the directory. See section Dired, the Directory Editor.
Disabled Command
A disabled command is one that you may not run without special confirmation. The usual reason for disabling a command is that it is confusing for beginning users. See section Disabling Commands.
Down Event
Short for `button down event'.
Drag Event
A drag event is the kind of input event generated when you press a mouse button, move the mouse, and then release the button. See section Rebinding Mouse Buttons.
Dribble File
A file into which Emacs writes all the characters that the user types on the keyboard. Dribble files are used to make a record for debugging Emacs bugs. Emacs does not make a dribble file unless you tell it to. See section Reporting Bugs.
Echo Area
The echo area is the bottom line of the screen, used for echoing the arguments to commands, for asking questions, and printing brief messages (including error messages). The messages are stored in the buffer `*Messages*' so you can review them later. See section The Echo Area.
Echoing
Echoing is acknowledging the receipt of commands by displaying them (in the echo area). Emacs never echoes single-character key sequences; longer key sequences echo only if you pause while typing them.
Electric
We say that a character is electric if it is normally self-inserting (q.v.), but the current major mode (q.v.) redefines it to do something else as well. For example, some programming language major modes define particular delimiter characters to reindent the line or insert one or more newlines in addition to self-insertion.
Error
An error occurs when an Emacs command cannot execute in the current circumstances. When an error occurs, execution of the command stops (unless the command has been programmed to do otherwise) and Emacs reports the error by printing an error message (q.v.). Type-ahead is discarded. Then Emacs is ready to read another editing command.
Error Message
An error message is a single line of output displayed by Emacs when the user asks for something impossible to do (such as, killing text forward when point is at the end of the buffer). They appear in the echo area, accompanied by a beep.
ESC
ESC is a character used as a prefix for typing Meta characters on keyboards lacking a META key. Unlike the META key (which, like the SHIFT key, is held down while another character is typed), you press the ESC key as you would press a letter key, and it applies to the next character you type.
Expunging
Expunging an Rmail file or Dired buffer is an operation that truly discards the messages or files you have previously flagged for deletion.
File Locking
Emacs used file locking to notice when two different users start to edit one file at the same time. See section Protection against Simultaneous Editing.
File Name
A file name is a name that refers to a file. File names may be relative or absolute; the meaning of a relative file name depends on the current directory, but an absolute file name refers to the same file regardless of which directory is current. On GNU and Unix systems, an absolute file name starts with a slash (the root directory) or with `~/' or `~user/' (a home directory). Some people use the term "pathname" for file names, but we do not; we use the word "path" only in the term "search path" (q.v.).
File-Name Component
A file-name component names a file directly within a particular directory. On GNU and Unix systems, a file name is a sequence of file-name components, separated by slashes. For example, `foo/bar' is a file name containing two components, `foo' and `bar'; it refers to the file named `bar' in the directory named `foo' in the current directory.
Fill Prefix
The fill prefix is a string that should be expected at the beginning of each line when filling is done. It is not regarded as part of the text to be filled. See section Filling Text.
Filling
Filling text means shifting text between consecutive lines so that all the lines are approximately the same length. See section Filling Text.
Formatted Text
Formatted text is text that displays with formatting information while you edit. Formatting information includes fonts, colors, and specified margins. See section Editing Formatted Text.
Frame
A frame is a rectangular cluster of Emacs windows. Emacs starts out with one frame, but you can create more. You can subdivide each frame into Emacs windows (q.v.). When you are using X windows, all the frames can be visible at the same time. See section Frames and X Windows.
Function Key
A function key is a key on the keyboard that sends input but does not correspond to any character. See section Rebinding Function Keys.
Global
Global means `independent of the current environment; in effect throughout Emacs'. It is the opposite of local (q.v.). Particular examples of the use of `global' appear below.
Global Abbrev
A global definition of an abbrev (q.v.) is effective in all major modes that do not have local (q.v.) definitions for the same abbrev. See section Abbrevs.
Global Keymap
The global keymap (q.v.) contains key bindings that are in effect except when overridden by local key bindings in a major mode's local keymap (q.v.). See section Keymaps.
Global Mark Ring
The global mark ring records the series of buffers you have recently set a mark in. In many cases you can use this to backtrack through buffers you have been editing in, or in which you have found tags. See section The Global Mark Ring.
Global Substitution
Global substitution means replacing each occurrence of one string by another string through a large amount of text. See section Replacement Commands.
Global Variable
The global value of a variable (q.v.) takes effect in all buffers that do not have their own local (q.v.) values for the variable. See section Variables.
Graphic Character
Graphic characters are those assigned pictorial images rather than just names. All the non-Meta (q.v.) characters except for the Control (q.v.) characters are graphic characters. These include letters, digits, punctuation, and spaces; they do not include RET or ESC. In Emacs, typing a graphic character inserts that character (in ordinary editing modes). See section Basic Editing Commands.
Highlighting
Highlighting text means displaying it with a different foreground and/or background color to make it stand out from the rest of the text in the buffer.
Hardcopy
Hardcopy means printed output. Emacs has commands for making printed listings of text in Emacs buffers. See section Hardcopy Output.
HELP
HELP is the Emacs name for C-h or F1. You can type HELP at any time to ask what options you have, or to ask what any command does. See section Help.
Hyper
Hyper is the name of a modifier bit which a keyboard input character may have. To make a character Hyper, type it while holding down the HYPER key. Such characters are given names that start with Hyper- (usually written H- for short). See section Kinds of User Input.
Inbox
An inbox is a file in which mail is delivered by the operating system. Rmail transfers mail from inboxes to Rmail files (q.v.) in which the mail is then stored permanently or until explicitly deleted. See section Rmail Files and Inboxes.
Indentation
Indentation means blank space at the beginning of a line. Most programming languages have conventions for using indentation to illuminate the structure of the program, and Emacs has special commands to adjust indentation. See section Indentation.
Indirect Buffer
An indirect buffer is a buffer that shares the text of another buffer, called its base buffer. See section Indirect Buffers.
Input Event
An input event represents, within Emacs, one action taken by the user on the terminal. Input events include typing characters, typing function keys, pressing or releasing mouse buttons, and switching between Emacs frames. See section Kinds of User Input.
Input Method
An input method is a system for entering non-ASCII text characters by typing sequences of ASCII characters (q.v.). See section Input Methods.
Insertion
Insertion means copying text into the buffer, either from the keyboard or from some other place in Emacs.
Interlocking
Interlocking is a feature for warning when you start to alter a file that someone else is already editing. See section Protection against Simultaneous Editing.
Justification
Justification means adding extra spaces to lines of text to make them come exactly to a specified width. See section Filling Text.
Keyboard Macro
Keyboard macros are a way of defining new Emacs commands from sequences of existing ones, with no need to write a Lisp program. See section Keyboard Macros.
Key Sequence
A key sequence (key, for short) is a sequence of input events (q.v.) that are meaningful as a single unit. If the key sequence is enough to specify one action, it is a complete key (q.v.); if it is not enough, it is a prefix key (q.v.). See section Keys.
Keymap
The keymap is the data structure that records the bindings (q.v.) of key sequences to the commands that they run. For example, the global keymap binds the character C-n to the command function next-line. See section Keymaps.
Keyboard Translation Table
The keyboard translation table is an array that translates the character codes that come from the terminal into the character codes that make up key sequences. See section Keyboard Translations.
Kill Ring
The kill ring is where all text you have killed recently is saved. You can reinsert any of the killed text still in the ring; this is called yanking (q.v.). See section Yanking.
Killing
Killing means erasing text and saving it on the kill ring so it can be yanked (q.v.) later. Some other systems call this "cutting." Most Emacs commands to erase text do killing, as opposed to deletion (q.v.). See section Deletion and Killing.
Killing Jobs
Killing a job (such as, an invocation of Emacs) means making it cease to exist. Any data within it, if not saved in a file, is lost. See section Exiting Emacs.
Language Environment
Your choice of language environment specifies defaults for the input method (q.v.) and coding system (q.v.). See section Language Environments. These defaults are relevant if you edit non-ASCII text (see section International Character Set Support).
List
A list is, approximately, a text string beginning with an open parenthesis and ending with the matching close parenthesis. In C mode and other non-Lisp modes, groupings surrounded by other kinds of matched delimiters appropriate to the language, such as braces, are also considered lists. Emacs has special commands for many operations on lists. See section Lists and Sexps.
Local
Local means `in effect only in a particular context'; the relevant kind of context is a particular function execution, a particular buffer, or a particular major mode. It is the opposite of `global' (q.v.). Specific uses of `local' in Emacs terminology appear below.
Local Abbrev
A local abbrev definition is effective only if a particular major mode is selected. In that major mode, it overrides any global definition for the same abbrev. See section Abbrevs.
Local Keymap
A local keymap is used in a particular major mode; the key bindings (q.v.) in the current local keymap override global bindings of the same key sequences. See section Keymaps.
Local Variable
A local value of a variable (q.v.) applies to only one buffer. See section Local Variables.
M-
M- in the name of a character is an abbreviation for META, one of the modifier keys that can accompany any character. See section Kinds of User Input.
M-C-
M-C- in the name of a character is an abbreviation for Control-Meta; it means the same thing as C-M-. If your terminal lacks a real META key, you type a Control-Meta character by typing ESC and then typing the corresponding Control character. See section Kinds of User Input.
M-x
M-x is the key sequence which is used to call an Emacs command by name. This is how you run commands that are not bound to key sequences. See section Running Commands by Name.
Mail
Mail means messages sent from one user to another through the computer system, to be read at the recipient's convenience. Emacs has commands for composing and sending mail, and for reading and editing the mail you have received. See section Sending Mail. See section Reading Mail with Rmail, for how to read mail.
Mail Composition Method
A mail composition method is a program runnable within Emacs for editing and sending a mail message. Emacs lets you select from several alternative mail composition methods. See section Mail-Composition Methods.
Major Mode
The Emacs major modes are a mutually exclusive set of options, each of which configures Emacs for editing a certain sort of text. Ideally, each programming language has its own major mode. See section Major Modes.
Mark
The mark points to a position in the text. It specifies one end of the region (q.v.), point being the other end. Many commands operate on all the text from point to the mark. Each buffer has its own mark. See section The Mark and the Region.
Mark Ring
The mark ring is used to hold several recent previous locations of the mark, just in case you want to move back to them. Each buffer has its own mark ring; in addition, there is a single global mark ring (q.v.). See section The Mark Ring.
Menu Bar
The menu bar is the line at the top of an Emacs frame. It contains words you can click on with the mouse to bring up menus. The menu bar feature is supported only with X. See section Menu Bars.
Message
See `mail'.
Meta
Meta is the name of a modifier bit which a command character may have. It is present in a character if the character is typed with the META key held down. Such characters are given names that start with Meta- (usually written M- for short). For example, M-< is typed by holding down META and at the same time typing < (which itself is done, on most terminals, by holding down SHIFT and typing ,). See section Kinds of User Input.
Meta Character
A Meta character is one whose character code includes the Meta bit.
Minibuffer
The minibuffer is the window that appears when necessary inside the echo area (q.v.), used for reading arguments to commands. See section The Minibuffer.
Minibuffer History
The minibuffer history records the text you have specified in the past for minibuffer arguments, so you can conveniently use the same text again. See section Minibuffer History.
Minor Mode
A minor mode is an optional feature of Emacs which can be switched on or off independently of all other features. Each minor mode has a command to turn it on or off. See section Minor Modes.
Minor Mode Keymap
A keymap that belongs to a minor mode and is active when that mode is enabled. Minor mode keymaps take precedence over the buffer's local keymap, just as the local keymap takes precedence over the global keymap. See section Keymaps.
Mode Line
The mode line is the line at the bottom of each window (q.v.), giving status information on the buffer displayed in that window. See section The Mode Line.
Modified Buffer
A buffer (q.v.) is modified if its text has been changed since the last time the buffer was saved (or since when it was created, if it has never been saved). See section Saving Files.
Moving Text
Moving text means erasing it from one place and inserting it in another. The usual way to move text by killing (q.v.) and then yanking (q.v.). See section Deletion and Killing.
MULE
MULE refers to the Emacs features for editing non-ASCII text using multibyte characters (q.v.). See section International Character Set Support.
Multibyte Character
A multibyte character is a character that takes up several buffer positions. Emacs uses multibyte characters to represent non-ASCII text, since the number of non-ASCII characters is much more than 256. See section Introduction to International Character Sets.
Named Mark
A named mark is a register (q.v.) in its role of recording a location in text so that you can move point to that location. See section Registers.
Narrowing
Narrowing means creating a restriction (q.v.) that limits editing in the current buffer to only a part of the text in the buffer. Text outside that part is inaccessible to the user until the boundaries are widened again, but it is still there, and saving the file saves it all. See section Narrowing.
Newline
Control-J characters in the buffer terminate lines of text and are therefore also called newlines. See section Character Set for Text.
Numeric Argument
A numeric argument is a number, specified before a command, to change the effect of the command. Often the numeric argument serves as a repeat count. See section Numeric Arguments.
Overwrite Mode
Overwrite mode is a minor mode. When it is enabled, ordinary text characters replace the existing text after point rather than pushing it to the right. See section Minor Modes.
Page
A page is a unit of text, delimited by formfeed characters (ASCII control-L, code 014) coming at the beginning of a line. Some Emacs commands are provided for moving over and operating on pages. See section Pages.
Paragraph
Paragraphs are the medium-size unit of English text. There are special Emacs commands for moving over and operating on paragraphs. See section Paragraphs.
Parsing
We say that certain Emacs commands parse words or expressions in the text being edited. Really, all they know how to do is find the other end of a word or expression. See section The Syntax Table.
Point
Point is the place in the buffer at which insertion and deletion occur. Point is considered to be between two characters, not at one character. The terminal's cursor (q.v.) indicates the location of point. See section Basic Editing Commands.
Prefix Argument
See `numeric argument'.
Prefix Key
A prefix key is a key sequence (q.v.) whose sole function is to introduce a set of longer key sequences. C-x is an example of prefix key; any two-character sequence starting with C-x is therefore a legitimate key sequence. See section Keys.
Primary Rmail File
Your primary Rmail file is the file named `RMAIL' in your home directory. That's where Rmail stores your incoming mail, unless you specify a different file name. See section Reading Mail with Rmail.
Primary Selection
The primary selection is one particular X selection (q.v.); it is the selection that most X applications use for transferring text to and from other applications. The Emacs kill commands set the primary selection and the yank command uses the primary selection when appropriate. See section Deletion and Killing.
Prompt
A prompt is text printed to ask the user for input. Displaying a prompt is called prompting. Emacs prompts always appear in the echo area (q.v.). One kind of prompting happens when the minibuffer is used to read an argument (see section The Minibuffer); the echoing which happens when you pause in the middle of typing a multi-character key sequence is also a kind of prompting (see section The Echo Area).
Quitting
Quitting means canceling a partially typed command or a running command, using C-g (or C-BREAK on MS-DOS). See section Quitting and Aborting.
Quoting
Quoting means depriving a character of its usual special significance. The most common kind of quoting in Emacs is with C-q. What constitutes special significance depends on the context and on convention. For example, an "ordinary" character as an Emacs command inserts itself; so in this context, a special character is any character that does not normally insert itself (such as DEL, for example), and quoting it makes it insert itself as if it were not special. Not all contexts allow quoting. See section Basic Editing Commands.
Quoting File Names
Quoting a file name turns off the special significance of constructs such as `$', `~' and `:'. See section Quoted File Names.
Read-Only Buffer
A read-only buffer is one whose text you are not allowed to change. Normally Emacs makes buffers read-only when they contain text which has a special significance to Emacs; for example, Dired buffers. Visiting a file that is write-protected also makes a read-only buffer. See section Using Multiple Buffers.
Rectangle
A rectangle consists of the text in a given range of columns on a given range of lines. Normally you specify a rectangle by putting point at one corner and putting the mark at the opposite corner. See section Rectangles.
Recursive Editing Level
A recursive editing level is a state in which part of the execution of a command involves asking the user to edit some text. This text may or may not be the same as the text to which the command was applied. The mode line indicates recursive editing levels with square brackets (`[' and `]'). See section Recursive Editing Levels.
Redisplay
Redisplay is the process of correcting the image on the screen to correspond to changes that have been made in the text being edited. See section The Organization of the Screen.
Regexp
See `regular expression'.
Region
The region is the text between point (q.v.) and the mark (q.v.). Many commands operate on the text of the region. See section The Mark and the Region.
Registers
Registers are named slots in which text or buffer positions or rectangles can be saved for later use. See section Registers.
Regular Expression
A regular expression is a pattern that can match various text strings; for example, `l[0-9]+' matches `l' followed by one or more digits. See section Syntax of Regular Expressions.
Repeat Count
See `numeric argument'.
Replacement
See `global substitution'.
Restriction
A buffer's restriction is the amount of text, at the beginning or the end of the buffer, that is temporarily inaccessible. Giving a buffer a nonzero amount of restriction is called narrowing (q.v.). See section Narrowing.
RET
RET is a character that in Emacs runs the command to insert a newline into the text. It is also used to terminate most arguments read in the minibuffer (q.v.). See section Kinds of User Input.
Rmail File
An Rmail file is a file containing text in a special format used by Rmail for storing mail. See section Reading Mail with Rmail.
Saving
Saving a buffer means copying its text into the file that was visited (q.v.) in that buffer. This is the way text in files actually gets changed by your Emacs editing. See section Saving Files.
Scroll Bar
A scroll bar is a tall thin hollow box that appears at the side of a window. You can use mouse commands in the scroll bar to scroll the window. The scroll bar feature is supported only with X. See section Scroll Bars.
Scrolling
Scrolling means shifting the text in the Emacs window so as to see a different part of the buffer. See section Controlling the Display.
Searching
Searching means moving point to the next occurrence of a specified string or the next match for a specified regular expression. See section Searching and Replacement.
Search Path
A search path is a list of directory names, to be used for searching for files for certain purposes. For example, the variable load-path holds a search path for finding Lisp library files. See section Libraries of Lisp Code for Emacs.
Secondary Selection
The secondary selection is one particular X selection; some X applications can use it for transferring text to and from other applications. Emacs has special mouse commands for transferring text using the secondary selection. See section Secondary Selection.
Selecting
Selecting a buffer means making it the current (q.v.) buffer. See section Using Multiple Buffers.
Selection
The X window system allows an application program to specify named selections whose values are text. A program can also read the selections that other programs have set up. This is the principal way of transferring text between window applications. Emacs has commands to work with the primary (q.v.) selection and the secondary (q.v.) selection.
Self-Documentation
Self-documentation is the feature of Emacs which can tell you what any command does, or give you a list of all commands related to a topic you specify. You ask for self-documentation with the help character, C-h. See section Help.
Self-Inserting Character
A character is self-inserting if typing that character inserts that character in the buffer. Ordinary printing and whitespace characters are self-inserting in Emacs, except in certain special major modes.
Sentences
Emacs has commands for moving by or killing by sentences. See section Sentences.
Sexp
A sexp (short for `s-expression') is the basic syntactic unit of Lisp in its textual form: either a list, or Lisp atom. Many Emacs commands operate on sexps. The term `sexp' is generalized to languages other than Lisp, to mean a syntactically recognizable expression. See section Lists and Sexps.
Simultaneous Editing
Simultaneous editing means two users modifying the same file at once. Simultaneous editing if not detected can cause one user to lose his work. Emacs detects all cases of simultaneous editing and warns one of the users to investigate. See section Protection against Simultaneous Editing.
String
A string is a kind of Lisp data object which contains a sequence of characters. Many Emacs variables are intended to have strings as values. The Lisp syntax for a string consists of the characters in the string with a `"' before and another `"' after. A `"' that is part of the string must be written as `\"' and a `\' that is part of the string must be written as `\\'. All other characters, including newline, can be included just by writing them inside the string; however, backslash sequences as in C, such as `\n' for newline or `\241' using an octal character code, are allowed as well.
String Substitution
See `global substitution'.
Syntax Table
The syntax table tells Emacs which characters are part of a word, which characters balance each other like parentheses, etc. See section The Syntax Table.
Super
Super is the name of a modifier bit which a keyboard input character may have. To make a character Super, type it while holding down the SUPER key. Such characters are given names that start with Super- (usually written s- for short). See section Kinds of User Input.
Tags Table
A tags table is a file that serves as an index to the function definitions in one or more other files. See section Tags Tables.
Termscript File
A termscript file contains a record of all characters sent by Emacs to the terminal. It is used for tracking down bugs in Emacs redisplay. Emacs does not make a termscript file unless you tell it to. See section Reporting Bugs.
Text
Two meanings (see section Commands for Human Languages):
  • Data consisting of a sequence of characters, as opposed to binary numbers, images, graphics commands, executable programs, and the like. The contents of an Emacs buffer are always text in this sense.
  • Data consisting of written human language, as opposed to programs, or following the stylistic conventions of human language.
Top Level
Top level is the normal state of Emacs, in which you are editing the text of the file you have visited. You are at top level whenever you are not in a recursive editing level (q.v.) or the minibuffer (q.v.), and not in the middle of a command. You can get back to top level by aborting (q.v.) and quitting (q.v.). See section Quitting and Aborting.
Transposition
Transposing two units of text means putting each one into the place formerly occupied by the other. There are Emacs commands to transpose two adjacent characters, words, sexps (q.v.) or lines (see section Transposing Text).
Truncation
Truncating text lines in the display means leaving out any text on a line that does not fit within the right margin of the window displaying it. See also `continuation line'. See section Basic Editing Commands.
Undoing
Undoing means making your previous editing go in reverse, bringing back the text that existed earlier in the editing session. See section Undoing Changes.
User Option
A user option is a variable (q.v.) that exists so that you can customize Emacs by setting it to a new value. See section Variables.
Variable
A variable is an object in Lisp that can store an arbitrary value. Emacs uses some variables for internal purposes, and has others (known as `user options' (q.v.)) just so that you can set their values to control the behavior of Emacs. The variables used in Emacs that you are likely to be interested in are listed in the Variables Index in this manual. See section Variables, for information on variables.
Version Control
Version control systems keep track of multiple versions of a source file. They provide a more powerful alternative to keeping backup files (q.v.). See section Version Control.
Visiting
Visiting a file means loading its contents into a buffer (q.v.) where they can be edited. See section Visiting Files.
Whitespace
Whitespace is any run of consecutive formatting characters (space, tab, newline, and backspace).
Widening
Widening is removing any restriction (q.v.) on the current buffer; it is the opposite of narrowing (q.v.). See section Narrowing.
Window
Emacs divides a frame (q.v.) into one or more windows, each of which can display the contents of one buffer (q.v.) at any time. See section The Organization of the Screen, for basic information on how Emacs uses the screen. See section Multiple Windows, for commands to control the use of windows.
Word Abbrev
Synonymous with `abbrev'.
Word Search
Word search is searching for a sequence of words, considering the punctuation between them as insignificant. See section Word Search.
WYSIWYG
WYSIWYG stands for `What you see is what you get.' Emacs generally provides WYSIWYG editing for files of characters; in Enriched mode (see section Editing Formatted Text), it provides WYSIWYG editing for files that include text formatting information.
Yanking
Yanking means reinserting text previously killed. It can be used to undo a mistaken kill, or for copying or moving text. Some other systems call this "pasting." See section Yanking.

Key (Character) Index

!

  • ! (Dired)

    • "

  • " (TeX mode)

    • #

  • # (Dired)

    • $

  • $ (Dired)

    • %

  • % C (Dired)
  • % d (Dired)
  • % H (Dired)
  • % l (Dired)
  • % m (Dired), % m (Dired)
  • % R (Dired)
  • % S (Dired)
  • % u (Dired)

    • &

  • & (Dired)

    • *

  • * ! (Dired)
  • * % (Dired)
  • * * (Dired)
  • * / (Dired)
  • * ? (Dired)
  • * @ (Dired)
  • * c (Dired)
  • * C-n (Dired)
  • * C-p (Dired)
  • * DEL (Dired)
  • * m (Dired)
  • * s (Dired)
  • * t (Dired)
  • * u (Dired)

    • +

  • + (Dired)

    • .

  • . (Calendar mode)
  • . (Dired)
  • . (Rmail)

    • <

  • < (Dired)
  • < (Rmail)

    • =

  • = (Dired)

    • >

  • > (Dired)
  • > (Rmail)

    • a

  • a (Calendar mode)
  • A (Dired)
  • a (Rmail)

    • b

  • B (Dired)
  • b (Rmail)
  • BS (MS-DOS)

    • c

  • C (Dired)
  • c (Rmail)
  • C-@
  • C-\
  • C-]
  • C-_
  • C-_ (Dired)
  • C-a
  • C-a (Calendar mode)
  • C-b
  • C-b (Calendar mode)
  • C-BREAK (MS-DOS)
  • C-c ' (Picture mode)
  • C-c . (Picture mode)
  • C-c / (Picture mode)
  • C-c : (C mode)
  • C-c ; (Fortran mode)
  • C-c < (GUD)
  • C-c < (Picture mode)
  • C-c > (GUD)
  • C-c > (Picture mode)
  • C-c @ (Outline minor mode)
  • C-c \ (Picture mode)
  • C-c ^ (Picture mode)
  • C-c ` (Picture mode)
  • C-c C-\ (C mode)
  • C-c C-\ (Shell mode)
  • C-c C-a (C mode)
  • C-c C-a (Mail mode)
  • C-c C-a (Outline mode)
  • C-c C-a (Shell mode)
  • C-c C-b (Outline mode)
  • C-c C-b (Picture mode)
  • C-c C-b (Shell mode)
  • C-c C-b (TeX mode)
  • C-c C-c (Edit Abbrevs)
  • C-c C-c (Edit Tab Stops)
  • C-c C-c (Mail mode)
  • C-c C-c (Outline mode)
  • C-c C-c (Shell mode)
  • C-c C-d (C mode)
  • C-c C-d (GUD)
  • C-c C-d (Outline mode)
  • C-c C-d (Picture mode)
  • C-c C-e (C mode)
  • C-c C-e (LaTeX mode)
  • C-c C-e (Outline mode)
  • C-c C-e (Shell mode)
  • C-c C-f (GUD)
  • C-c C-f (Outline mode)
  • C-c C-f (Picture mode)
  • C-c C-f (Shell mode)
  • C-c C-f (TeX mode)
  • C-c C-f C-b (Mail mode)
  • C-c C-f C-c (Mail mode)
  • C-c C-f C-f (Mail mode)
  • C-c C-f C-s (Mail mode)
  • C-c C-f C-t (Mail mode)
  • C-c C-i (GUD)
  • C-c C-i (Mail mode)
  • C-c C-i (Outline mode)
  • C-c C-k (Outline mode)
  • C-c C-k (Picture mode)
  • C-c C-k (TeX mode)
  • C-c C-l (Calendar mode)
  • C-c C-l (GUD)
  • C-c C-l (Outline mode)
  • C-c C-l (Shell mode)
  • C-c C-l (TeX mode)
  • C-c C-n (C mode)
  • C-c C-n (Fortran mode)
  • C-c C-n (GUD)
  • C-c C-n (Outline mode)
  • C-c C-n (Shell mode)
  • C-c C-o (C mode)
  • C-c C-o (LaTeX mode)
  • C-c C-o (Outline mode)
  • C-c C-o (Shell mode)
  • C-c C-p (C mode)
  • C-c C-p (Fortran mode)
  • C-c C-p (Outline mode)
  • C-c C-p (Shell mode)
  • C-c C-p (TeX mode)
  • C-c C-q (C mode)
  • C-c C-q (Mail mode)
  • C-c C-q (Outline mode)
  • C-c C-q (TeX mode)
  • C-c C-r (Fortran mode)
  • C-c C-r (GUD)
  • C-c C-r (Mail mode)
  • C-c C-r (Shell mode)
  • C-c C-r (TeX mode)
  • C-c C-s (C mode)
  • C-c C-s (GUD)
  • C-c C-s (Mail mode)
  • C-c C-s (Outline mode)
  • C-c C-t (C mode)
  • C-c C-t (GUD)
  • C-c C-t (Mail mode)
  • C-c C-t (Outline mode)
  • C-c C-u (C mode)
  • C-c C-u (Outline mode)
  • C-c C-u (Shell mode)
  • C-c C-v (TeX mode)
  • C-c C-w (Fortran mode)
  • C-c C-w (Mail mode)
  • C-c C-w (Picture mode)
  • C-c C-w (Shell mode)
  • C-c C-x (Picture mode)
  • C-c C-y (Mail mode)
  • C-c C-y (Picture mode)
  • C-c C-z (Shell mode)
  • C-c RET (Shell mode)
  • C-c TAB (Picture mode)
  • C-c TAB (TeX mode)
  • C-c { (TeX mode)
  • C-c } (TeX mode)
  • C-d
  • C-d (Rmail)
  • C-d (Shell mode)
  • C-e
  • C-e (Calendar mode)
  • C-f
  • C-f (Calendar mode)
  • C-g
  • C-g (MS-DOS)
  • C-h
  • C-h a
  • C-h b
  • C-h C
  • C-h c
  • C-h C-\
  • C-h C-c
  • C-h C-d
  • C-h C-f
  • C-h C-h
  • C-h C-i
  • C-h C-k
  • C-h C-p
  • C-h C-w
  • C-h F
  • C-h f
  • C-h h
  • C-h I
  • C-h i
  • C-h k
  • C-h L
  • C-h l
  • C-h m
  • C-h n
  • C-h p
  • C-h s
  • C-h t
  • C-h w
  • C-j
  • C-j (and major modes)
  • C-j (Fortran mode)
  • C-j (MS-DOS)
  • C-j (TeX mode)
  • C-k
  • C-k (Gnus)
  • C-l
  • C-M-%
  • C-M-.
  • C-M-/
  • C-M-@
  • C-M-\
  • C-M-a
  • C-M-a (Fortran mode)
  • C-M-b
  • C-M-c
  • C-M-d
  • C-M-d (Dired)
  • C-M-DEL
  • C-M-e
  • C-M-e (Fortran mode)
  • C-M-f
  • C-M-h
  • C-M-h (C mode)
  • C-M-h (Fortran mode)
  • C-M-j
  • C-M-j (Fortran mode)
  • C-M-k
  • C-M-l
  • C-M-l (Rmail)
  • C-M-l (Shell mode)
  • C-M-n
  • C-M-n (Dired)
  • C-M-n (Rmail)
  • C-M-o
  • C-M-p
  • C-M-p (Dired)
  • C-M-p (Rmail)
  • C-M-q
  • C-M-q (C mode)
  • C-M-q (Fortran mode)
  • C-M-r
  • C-M-r (Rmail)
  • C-M-s
  • C-M-t, C-M-t
  • C-M-t (Rmail)
  • C-M-u
  • C-M-u (Dired)
  • C-M-v
  • C-M-w
  • C-M-x (Emacs-Lisp mode)
  • C-M-x (Lisp mode)
  • C-Mouse-2 (scroll bar)
  • C-Mouse-3
  • C-n
  • C-n (Calendar mode)
  • C-n (Dired)
  • C-n (Gnus Group mode)
  • C-n (Gnus Summary mode)
  • C-o
  • C-o (Dired)
  • C-o (Rmail)
  • C-p
  • C-p (Calendar mode)
  • C-p (Dired)
  • C-p (Gnus Group mode)
  • C-p (Gnus Summary mode)
  • C-q
  • C-r
  • C-s
  • C-SPC
  • C-t
  • C-u
  • C-u - C-x ;
  • C-u C-@
  • C-u C-SPC
  • C-u C-x u
  • C-u TAB
  • C-v
  • C-v (Calendar mode)
  • C-w
  • C-x #
  • C-x $
  • C-x (
  • C-x )
  • C-x +
  • C-x -
  • C-x .
  • C-x 0
  • C-x 1
  • C-x 2
  • C-x 3
  • C-x 4
  • C-x 4 .
  • C-x 4 0
  • C-x 4 a
  • C-x 4 b
  • C-x 4 d
  • C-x 4 f
  • C-x 4 m
  • C-x 5
  • C-x 5 .
  • C-x 5 0
  • C-x 5 2
  • C-x 5 b
  • C-x 5 d
  • C-x 5 f
  • C-x 5 m
  • C-x 5 o
  • C-x 5 r
  • C-x 6 1
  • C-x 6 2
  • C-x 6 b
  • C-x 6 d
  • C-x 6 RET
  • C-x 6 s
  • C-x 8
  • C-x ;
  • C-x <
  • C-x < (Calendar mode)
  • C-x =
  • C-x >
  • C-x > (Calendar mode)
  • C-x [
  • C-x [ (Calendar mode)
  • C-x ]
  • C-x ] (Calendar mode)
  • C-x ^
  • C-x `
  • C-x a g
  • C-x a i g
  • C-x a i l
  • C-x a l
  • C-x b
  • C-x C-a (GUD)
  • C-x C-b
  • C-x C-c
  • C-x C-d
  • C-x C-e
  • C-x C-f
  • C-x C-k
  • C-x C-l
  • C-x C-n
  • C-x C-o
  • C-x C-p
  • C-x C-q
  • C-x C-q (Version Control)
  • C-x C-r
  • C-x C-s
  • C-x C-SPC
  • C-x C-t
  • C-x C-u
  • C-x C-v
  • C-x C-w
  • C-x C-x
  • C-x C-z
  • C-x d
  • C-x DEL
  • C-x e
  • C-x ESC ESC
  • C-x f
  • C-x h
  • C-x k
  • C-x l
  • C-x m
  • C-x n d
  • C-x n d (Fortran mode)
  • C-x n n
  • C-x n p
  • C-x n w
  • C-x o
  • C-x q
  • C-x r +
  • C-x r b
  • C-x r d
  • C-x r f
  • C-x r i
  • C-x r j
  • C-x r k
  • C-x r l
  • C-x r m
  • C-x r n
  • C-x r o
  • C-x r r
  • C-x r s
  • C-x r SPC
  • C-x r t
  • C-x r w
  • C-x r y
  • C-x RET
  • C-x RET c
  • C-x RET C-\
  • C-x RET f
  • C-x RET k
  • C-x RET p
  • C-x RET t
  • C-x RET X
  • C-x RET x
  • C-x s
  • C-x SPC
  • C-x TAB
  • C-x TAB (Enriched mode)
  • C-x u
  • C-x v =
  • C-x v a
  • C-x v c
  • C-x v d
  • C-x v g
  • C-x v h
  • C-x v i
  • C-x v l
  • C-x v m
  • C-x v r
  • C-x v s
  • C-x v u
  • C-x v v
  • C-x v ~
  • C-x z
  • C-x }
  • C-y
  • C-z
  • C-z (X windows)

    • d

  • d (Calendar mode)
  • D (Dired)
  • d (Dired)
  • d (Rmail)
  • DEL
  • DEL (and major modes)
  • DEL (Dired)
  • DEL (Gnus)
  • DEL (MS-DOS)
  • DEL (programming modes)
  • DEL (Rmail)
  • DELETE
  • DOWN

    • e

  • e (Rmail)
  • ESC a
  • ESC e
  • ESC ESC ESC

    • f

  • f (Dired)
  • f (Rmail)
  • F1
  • F10
  • F2 1
  • F2 2
  • F2 b
  • F2 d
  • F2 RET
  • F2 s

    • g

  • G (Dired)
  • g (Dired)
  • g (Rmail)
  • g char (Calendar mode)
  • g d (Calendar mode)
  • g m (Calendar mode)

    • h

  • h (Calendar mode)
  • H (Dired)
  • h (Rmail)
  • Help

    • i

  • i (Dired)
  • i (Rmail)
  • i a (Calendar mode)
  • i b (Calendar mode)
  • i c (Calendar mode)
  • i d (Calendar mode)
  • i m (Calendar mode)
  • i w (Calendar mode)
  • i y (Calendar mode)

    • j

  • j (Rmail)

    • k

  • k (Dired)
  • k (Rmail)

    • l

  • L (Dired)
  • l (Dired)
  • L (Gnus Group mode)
  • l (Gnus Group mode)
  • l (Rmail)
  • LEFT

    • m

  • M (Calendar mode)
  • m (Calendar mode)
  • M (Dired)
  • m (Dired)
  • m (Rmail)
  • M-!
  • M-$
  • M-$ (Dired)
  • M-%
  • M-'
  • M-(
  • M-)
  • M-*
  • M-,
  • M--
  • M-- M-c
  • M-- M-l
  • M-- M-u
  • M-.
  • M-/
  • M-1
  • M-:
  • M-;
  • M-<
  • M-< (Calendar mode)
  • M-=
  • M-= (Calendar mode)
  • M-= (Dired)
  • M->
  • M-> (Calendar mode)
  • M-? (Nroff mode)
  • M-? (Shell mode)
  • M-@
  • M-\
  • M-^
  • M-^ (Fortran mode)
  • M-`
  • M-a
  • M-a (Calendar mode)
  • M-b
  • M-c
  • M-d
  • M-DEL
  • M-Drag-Mouse-1
  • M-e
  • M-e (Calendar mode)
  • M-f
  • M-g b (Enriched mode)
  • M-g d (Enriched mode)
  • M-g i (Enriched mode)
  • M-g l (Enriched mode)
  • M-g M-g
  • M-g o (Enriched mode)
  • M-g u (Enriched mode)
  • M-h
  • M-i
  • M-j c (Enriched mode)
  • M-j f (Enriched mode)
  • M-j l (Enriched mode)
  • M-j r (Enriched mode)
  • M-j u (Enriched mode)
  • M-k
  • M-l
  • M-m
  • M-m (Rmail)
  • M-Mouse-1
  • M-Mouse-2
  • M-Mouse-3
  • M-n (minibuffer history)
  • M-n (Nroff mode)
  • M-n (Rmail)
  • M-n (Shell mode)
  • M-p (minibuffer history)
  • M-p (Nroff mode)
  • M-p (Rmail)
  • M-p (Shell mode)
  • M-q
  • M-q (C mode)
  • M-r
  • M-r (minibuffer history)
  • M-r (Shell mode)
  • M-S (Enriched mode)
  • M-s (Gnus Summary mode)
  • M-s (minibuffer history)
  • M-s (Rmail)
  • M-s (Shell mode)
  • M-s (Text mode)
  • M-SPC
  • M-t, M-t
  • M-TAB
  • M-TAB (customization buffer)
  • M-TAB (Mail mode)
  • M-TAB (Picture mode)
  • M-TAB (Text mode)
  • M-u
  • M-v
  • M-v (Calendar mode)
  • M-w
  • M-x
  • M-y
  • M-z
  • M-{
  • M-{ (Calendar mode)
  • M-|
  • M-}
  • M-} (Calendar mode)
  • M-~
  • Mouse-1
  • Mouse-2
  • Mouse-2 (selection)
  • Mouse-3

    • n

  • n (Gnus)
  • n (Rmail)
  • NEXT

    • o

  • o (Calendar mode)
  • O (Dired)
  • o (Dired)
  • o (Rmail)

    • p

  • p (Calendar mode)
  • P (Dired)
  • p (Gnus)
  • p (Rmail)
  • p d (Calendar mode)
  • PRIOR

    • q

  • q (Calendar mode)
  • Q (Dired)
  • q (Gnus Group mode)
  • Q (Rmail summary)
  • q (Rmail summary)
  • q (Rmail)

    • r

  • R (Dired)
  • r (Rmail)
  • RET
  • RET (Dired)
  • RET (Occur mode)
  • RET (Shell mode)
  • RIGHT

    • s

  • S (Calendar mode)
  • s (Calendar mode)
  • S (Dired)
  • s (Dired)
  • s (Gnus Summary mode)
  • s (Rmail)
  • S-Mouse-1
  • S-TAB (customization buffer)
  • S-TAB (Help mode)
  • SPC
  • SPC (Calendar mode)
  • SPC (Dired)
  • SPC (Gnus)
  • SPC (Rmail)

    • t

  • t (Calendar mode)
  • t (Rmail)
  • TAB
  • TAB (and major modes)
  • TAB (completion)
  • TAB (customization buffer)
  • TAB (GUD)
  • TAB (Help mode)
  • TAB (programming modes)
  • TAB (Shell mode)
  • TAB (Text mode)

    • u

  • u (Calendar mode)
  • u (Dired deletion)
  • u (Dired)
  • u (Gnus Group mode)
  • u (Rmail)
  • UP

    • v

  • v (Dired)

    • w

  • w (Rmail)

    • x

  • x (Calendar mode)
  • x (Dired)
  • x (Rmail)

    • z

  • Z (Dired)

    • ~

  • ~ (Dired)

    • Command and Function Index

    2

  • 2C-associate-buffer
  • 2C-dissociate
  • 2C-merge
  • 2C-newline
  • 2C-split
  • 2C-two-columns

    • a

  • abbrev-mode
  • abbrev-prefix-mark
  • abort-recursive-edit
  • add-change-log-entry-other-window
  • add-global-abbrev
  • add-mode-abbrev
  • add-name-to-file
  • add-untranslated-filesystem
  • american-calendar
  • append-next-kill
  • append-to-buffer
  • append-to-file
  • apply-macro-to-region-lines
  • appt-add
  • appt-delete
  • appt-make-list
  • apropos
  • apropos-command
  • apropos-documentation
  • apropos-value
  • apropos-variable
  • ask-user-about-lock
  • auto-compression-mode
  • auto-fill-mode
  • auto-lower-mode
  • auto-raise-mode
  • auto-save-mode

    • b

  • back-to-indentation
  • backward-char
  • backward-delete-char-untabify
  • backward-kill-sentence
  • backward-kill-sexp
  • backward-kill-word
  • backward-list
  • backward-page
  • backward-paragraph
  • backward-sentence
  • backward-sexp
  • backward-text-line
  • backward-up-list
  • backward-word
  • balance-windows
  • beginning-of-buffer
  • beginning-of-defun
  • beginning-of-fortran-subprogram
  • beginning-of-line
  • binary-overwrite-mode
  • blackbox
  • bookmark-delete
  • bookmark-insert
  • bookmark-insert-location
  • bookmark-jump, bookmark-jump
  • bookmark-load
  • bookmark-save
  • bookmark-set, bookmark-set
  • bookmark-write
  • buffer-menu

    • c

  • c-add-style
  • c-backslash-region
  • c-backward-conditional
  • c-backward-into-nomenclature
  • c-beginning-of-statement
  • c-end-of-statement
  • c-fill-paragraph
  • c-forward-conditional
  • c-forward-into-nomenclature
  • c-indent-command
  • c-indent-defun
  • c-indent-exp
  • c-indent-line
  • c-macro-expand
  • c-mark-function, c-mark-function
  • c-scope-operator
  • c-set-offset
  • c-set-style
  • c-show-syntactic-information
  • c-toggle-auto-hungry-state
  • c-toggle-auto-state
  • c-toggle-hungry-state
  • c-up-conditional
  • calendar
  • calendar-backward-day
  • calendar-backward-month
  • calendar-backward-week
  • calendar-beginning-of-month
  • calendar-beginning-of-week
  • calendar-beginning-of-year
  • calendar-count-days-region
  • calendar-cursor-holidays
  • calendar-end-of-month
  • calendar-end-of-week
  • calendar-end-of-year
  • calendar-forward-day
  • calendar-forward-month
  • calendar-forward-week
  • calendar-forward-year, calendar-forward-year
  • calendar-goto-astro-day-number
  • calendar-goto-chinese-date
  • calendar-goto-coptic-date
  • calendar-goto-date
  • calendar-goto-ethiopic-date
  • calendar-goto-french-date
  • calendar-goto-hebrew-date
  • calendar-goto-islamic-date
  • calendar-goto-iso-date
  • calendar-goto-julian-date
  • calendar-goto-mayan-long-count-date
  • calendar-goto-persian-date
  • calendar-goto-today
  • calendar-next-calendar-round-date
  • calendar-next-haab-date
  • calendar-next-tzolkin-date
  • calendar-other-month
  • calendar-phases-of-moon
  • calendar-previous-haab-date
  • calendar-previous-tzolkin-date
  • calendar-print-astro-day-number
  • calendar-print-chinese-date
  • calendar-print-coptic-date
  • calendar-print-day-of-year
  • calendar-print-ethiopic-date
  • calendar-print-french-date
  • calendar-print-hebrew-date
  • calendar-print-islamic-date
  • calendar-print-iso-date
  • calendar-print-julian-date
  • calendar-print-mayan-date
  • calendar-print-persian-date
  • calendar-sunrise-sunset
  • calendar-unmark
  • call-last-kbd-macro
  • capitalize-word
  • cd
  • center-line
  • change-log-mode
  • choose-completion
  • clean-buffer-list
  • clear-rectangle
  • codepage-setup
  • column-number-mode
  • comint-bol
  • comint-continue-subjob
  • comint-copy-old-input
  • comint-delchar-or-maybe-eof
  • comint-dynamic-complete
  • comint-dynamic-complete-variable
  • comint-dynamic-list-filename...
  • comint-dynamic-list-input-ring
  • comint-get-next-from-history
  • comint-interrupt-subjob
  • comint-kill-input
  • comint-kill-output
  • comint-magic-space
  • comint-next-input
  • comint-next-matching-input
  • comint-next-prompt
  • comint-previous-input
  • comint-previous-matching-input
  • comint-previous-prompt
  • comint-quit-subjob
  • comint-run
  • comint-send-input
  • comint-show-maximum-output
  • comint-show-output
  • comint-stop-subjob
  • comint-strip-ctrl-m
  • comint-truncate-buffer
  • comment-region
  • compare-windows
  • compile
  • compile (MS-DOS)
  • compile-goto-error
  • complete-symbol
  • compose-mail
  • compose-mail-other-frame
  • compose-mail-other-window
  • copy-file
  • copy-rectangle-to-register
  • copy-to-buffer
  • copy-to-register
  • count-lines-page
  • count-lines-region
  • count-matches
  • count-text-lines
  • cpp-highlight-buffer
  • create-fontset-from-fontset-spec
  • customize
  • customize-apropos
  • customize-browse
  • customize-changed-options
  • customize-customized
  • customize-face
  • customize-group
  • customize-option
  • customize-saved

    • d

  • dabbrev-completion
  • dabbrev-expand
  • dbx
  • debug_print
  • default-value
  • define-abbrevs
  • define-key
  • define-mail-abbrev
  • define-mail-alias
  • delete-backward-char
  • delete-blank-lines
  • delete-char
  • delete-file
  • delete-frame
  • delete-horizontal-space
  • delete-indentation
  • delete-matching-lines
  • delete-non-matching-lines
  • delete-other-windows
  • delete-rectangle
  • delete-whitespace-rectangle
  • delete-window
  • describe-bindings
  • describe-coding-system
  • describe-copying
  • describe-distribution
  • describe-function
  • describe-input-method
  • describe-key
  • describe-key-briefly
  • describe-language-environment
  • describe-mode
  • describe-no-warranty
  • describe-project
  • describe-syntax
  • desktop-save
  • diary
  • diary-anniversary
  • diary-block
  • diary-cyclic
  • diary-float
  • diary-mail-entries
  • diff
  • diff-backup
  • digit-argument
  • dired
  • dired-backup-diff
  • dired-change-marks
  • dired-clean-directory
  • dired-create-directory
  • dired-diff
  • dired-display-file
  • dired-do-byte-compile
  • dired-do-chgrp
  • dired-do-chmod
  • dired-do-chown
  • dired-do-compress
  • dired-do-copy
  • dired-do-copy-regexp
  • dired-do-delete
  • dired-do-hardlink
  • dired-do-hardlink-regexp
  • dired-do-kill-lines
  • dired-do-load
  • dired-do-print
  • dired-do-query-replace
  • dired-do-redisplay
  • dired-do-rename
  • dired-do-rename-regexp
  • dired-do-search
  • dired-do-shell-command
  • dired-do-symlink
  • dired-do-symlink-regexp
  • dired-do-toggle
  • dired-downcase
  • dired-expunge
  • dired-find-file
  • dired-find-file-other-window
  • dired-flag-auto-save-files
  • dired-flag-backup-files
  • dired-flag-file-deletion
  • dired-flag-files-regexp
  • dired-flag-garbage-files
  • dired-hide-all
  • dired-hide-subdir
  • dired-mark
  • dired-mark-directories
  • dired-mark-executables
  • dired-mark-files-containing-regexp
  • dired-mark-files-regexp
  • dired-mark-subdir-files
  • dired-mark-symlinks
  • dired-maybe-insert-subdir
  • dired-mouse-find-file-other-window
  • dired-next-dirline
  • dired-next-marked-file
  • dired-next-subdir
  • dired-other-frame
  • dired-other-window
  • dired-prev-dirline
  • dired-prev-marked-file
  • dired-prev-subdir
  • dired-sort-toggle-or-edit
  • dired-tree-down
  • dired-tree-up
  • dired-undo
  • dired-unmark
  • dired-unmark-all-files
  • dired-unmark-all-files-no-query
  • dired-unmark-backward
  • dired-upcase
  • dired-view-file
  • dirs
  • dirtrack-mode
  • disable-command
  • display-time
  • dissociated-press
  • do-auto-save
  • doctor
  • down-list
  • downcase-region
  • downcase-word
  • dunnet

    • e

  • edit-abbrevs
  • edit-kbd-macro
  • edit-picture
  • edit-tab-stops
  • edit-tab-stops-note-changes
  • edt-emulation-off
  • edt-emulation-on
  • eldoc-mode
  • electric-nroff-mode
  • emacs-lisp-mode
  • emacs-version
  • emerge-auto-advance-mode
  • emerge-buffers
  • emerge-buffers-with-ancestor
  • emerge-files
  • emerge-files-with-ancestor
  • emerge-skip-prefers-mode
  • enable-command
  • enable-flow-control
  • enable-flow-control-on
  • enable-local-eval
  • enable-local-variables
  • end-kbd-macro
  • end-of-buffer
  • end-of-defun
  • end-of-fortran-subprogram
  • end-of-line
  • enlarge-window
  • enlarge-window-horizontally
  • enriched-mode
  • european-calendar
  • eval-current-buffer
  • eval-defun
  • eval-expression
  • eval-last-sexp
  • eval-region
  • exchange-point-and-mark
  • execute-extended-command
  • exit-calendar
  • exit-recursive-edit
  • expand-abbrev
  • expand-mail-aliases
  • expand-region-abbrevs

    • f

  • facemenu-remove-all
  • facemenu-remove-props
  • facemenu-set-background
  • facemenu-set-bold
  • facemenu-set-bold-italic
  • facemenu-set-default
  • facemenu-set-face
  • facemenu-set-foreground
  • facemenu-set-italic
  • facemenu-set-underline
  • fast-lock-mode
  • fill-individual-paragraphs
  • fill-nonuniform-paragraphs
  • fill-paragraph
  • fill-region
  • fill-region-as-paragraph
  • find-alternate-file
  • find-dired
  • find-file
  • find-file-binary
  • find-file-literally
  • find-file-other-frame
  • find-file-other-window
  • find-file-read-only
  • find-file-read-only-other-frame
  • find-file-text
  • find-grep-dired
  • find-name-dired
  • find-tag
  • find-tag-other-frame
  • find-tag-other-window
  • find-tag-regexp
  • finder-by-keyword
  • flush-lines
  • flyspell-mode
  • font-lock-add-keywords
  • font-lock-fontify-block
  • font-lock-mode
  • format-find-file
  • fortran-auto-fill-mode
  • fortran-column-ruler
  • fortran-comment-region
  • fortran-indent-line
  • fortran-indent-new-line
  • fortran-indent-subprogram
  • fortran-join-line
  • fortran-mode
  • fortran-narrow-to-subprogram
  • fortran-next-statement
  • fortran-previous-statement
  • fortran-split-line
  • fortran-window-create
  • forward-char
  • forward-list
  • forward-page
  • forward-paragraph
  • forward-sentence
  • forward-sexp
  • forward-text-line
  • forward-word
  • frame-configuration-to-register

    • g

  • gdb
  • global-font-lock-mode
  • global-set-key
  • global-unset-key
  • gnus
  • gnus-group-exit
  • gnus-group-kill-group
  • gnus-group-list-all-groups
  • gnus-group-list-groups
  • gnus-group-next-group
  • gnus-group-next-unread-group
  • gnus-group-prev-group
  • gnus-group-prev-unread-group
  • gnus-group-read-group
  • gnus-group-unsubscribe-current-group
  • gnus-summary-isearch-article
  • gnus-summary-next-subject
  • gnus-summary-next-unread-article
  • gnus-summary-prev-page
  • gnus-summary-prev-subject
  • gnus-summary-prev-unread-article
  • gnus-summary-search-article-forward
  • gomoku
  • goto-char
  • goto-line
  • grep
  • grep (MS-DOS)
  • grep-find
  • gud-cont
  • gud-def
  • gud-down
  • gud-finish
  • gud-gdb-complete-command
  • gud-next
  • gud-refresh
  • gud-remove
  • gud-step
  • gud-stepi
  • gud-tbreak
  • gud-up

    • h

  • hanoi
  • help-command
  • help-for-help
  • help-next-ref
  • help-previous-ref
  • help-with-tutorial
  • hide-body
  • hide-entry
  • hide-leaves
  • hide-other
  • hide-sublevels
  • hide-subtree
  • highlight-changes-mode
  • holidays
  • hscroll-mode

    • i

  • iconify-or-deiconify-frame
  • ielm
  • increase-left-margin
  • increment-register
  • indent-for-comment
  • indent-new-comment-line
  • indent-region
  • indent-relative
  • indent-rigidly
  • indent-sexp
  • info
  • Info-goto-emacs-command-node
  • Info-goto-emacs-key-command-node
  • info-lookup-file
  • info-lookup-symbol
  • insert-abbrevs
  • insert-anniversary-diary-entry
  • insert-block-diary-entry
  • insert-cyclic-diary-entry
  • insert-diary-entry
  • insert-file
  • insert-kbd-macro
  • insert-monthly-diary-entry
  • insert-parentheses
  • insert-register
  • insert-weekly-diary-entry
  • insert-yearly-diary-entry
  • inverse-add-global-abbrev
  • inverse-add-mode-abbrev
  • isearch-backward
  • isearch-backward-regexp
  • isearch-forward
  • isearch-forward-regexp
  • ispell-buffer
  • ispell-complete-word
  • ispell-kill-ispell
  • ispell-message
  • ispell-region
  • ispell-word

    • j

  • jdb
  • jump-to-register
  • just-one-space

    • k

  • kbd-macro-query
  • keep-lines
  • keyboard-escape-quit
  • keyboard-translate
  • kill-all-abbrevs
  • kill-buffer
  • kill-buffer-and-window
  • kill-comment
  • kill-compilation
  • kill-line
  • kill-local-variable
  • kill-rectangle
  • kill-region
  • kill-ring-save
  • kill-sentence
  • kill-sexp
  • kill-some-buffers
  • kill-word

    • l

  • latex-mode
  • lazy-lock-mode
  • line-number-mode
  • lisp-complete-symbol
  • lisp-eval-defun
  • lisp-indent-line
  • lisp-interaction-mode
  • lisp-mode
  • list-abbrevs
  • list-bookmarks
  • list-buffers
  • list-calendar-holidays
  • list-coding-systems
  • list-command-history
  • list-directory
  • list-faces-display
  • list-holidays
  • list-input-methods
  • list-matching-lines
  • list-tags
  • list-text-properties-at
  • list-yahrzeit-dates
  • load
  • load-file
  • load-library
  • local-set-key
  • local-unset-key
  • lpr-buffer
  • lpr-region

    • m

  • mail-attach-file
  • mail-bcc
  • mail-cc
  • mail-complete
  • mail-fcc
  • mail-fill-yanked-message
  • mail-interactive-insert-alias
  • mail-send
  • mail-send-and-exit
  • mail-signature
  • mail-subject
  • mail-text
  • mail-to
  • mail-yank-original
  • mail-yank-region
  • make-frame-command
  • make-frame-on-display
  • make-indirect-buffer
  • make-local-variable
  • make-symbolic-link
  • make-variable-buffer-local
  • Man-fontify-manpage
  • manual-entry
  • mark-calendar-holidays
  • mark-defun
  • mark-diary-entries
  • mark-fortran-subprogram
  • mark-page
  • mark-paragraph
  • mark-sexp
  • mark-whole-buffer
  • mark-word
  • minibuffer-complete
  • minibuffer-complete-word
  • mode25
  • mode4350
  • modify-face
  • mouse-choose-completion
  • mouse-save-then-click
  • mouse-secondary-save-then-kill
  • mouse-set-point
  • mouse-set-region
  • mouse-set-secondary
  • mouse-start-secondary
  • mouse-yank-at-click
  • mouse-yank-secondary
  • move-past-close-and-reindent
  • move-to-window-line
  • mpuz, mpuz

    • n

  • name-last-kbd-macro
  • narrow-to-defun
  • narrow-to-page
  • narrow-to-region
  • negative-argument
  • newline
  • newline-and-indent
  • next-completion
  • next-error
  • next-history-element
  • next-line
  • next-matching-history-element
  • normal-mode
  • not-modified
  • nroff-mode
  • number-to-register

    • o

  • occur
  • open-dribble-file
  • open-line
  • open-rectangle
  • open-termscript
  • other-frame
  • other-window
  • outline-backward-same-level
  • outline-forward-same-level
  • outline-minor-mode
  • outline-mode
  • outline-next-visible-heading
  • outline-previous-visible-heading
  • outline-up-heading
  • overwrite-mode

    • p

  • paragraph-indent-text-mode
  • pdb
  • perldb
  • phases-of-moon
  • picture-backward-clear-column
  • picture-backward-column
  • picture-clear-column
  • picture-clear-line
  • picture-clear-rectangle
  • picture-clear-rectangle-to-register
  • picture-forward-column
  • picture-motion
  • picture-motion-reverse
  • picture-move-down
  • picture-move-up
  • picture-movement-down
  • picture-movement-left
  • picture-movement-ne
  • picture-movement-nw
  • picture-movement-right
  • picture-movement-se
  • picture-movement-sw
  • picture-movement-up
  • picture-newline
  • picture-open-line
  • picture-set-tab-stops
  • picture-tab
  • picture-tab-search
  • picture-yank-rectangle
  • picture-yank-rectangle-from-register
  • plain-tex-mode
  • point-to-register
  • pop-global-mark
  • pop-tag-mark
  • prefer-coding-system
  • prepend-to-buffer
  • previous-completion
  • previous-history-element
  • previous-line
  • previous-matching-history-element
  • print-buffer
  • print-buffer (MS-DOS)
  • print-region
  • print-region (MS-DOS)
  • ps-print-buffer
  • ps-print-buffer (MS-DOS)
  • ps-print-buffer-with-faces
  • ps-print-region
  • ps-print-region-with-faces
  • ps-spool-buffer
  • ps-spool-buffer (MS-DOS)
  • ps-spool-buffer-with-faces
  • ps-spool-region
  • ps-spool-region-with-faces
  • pwd

    • q

  • quail-set-keyboard-layout
  • query-replace
  • query-replace-regexp
  • quietly-read-abbrev-file
  • quoted-insert

    • r

  • re-search-backward
  • re-search-forward
  • read-abbrev-file
  • recenter
  • recover-file
  • recover-session
  • redraw-calendar
  • remove-untranslated-filesystem
  • rename-buffer
  • rename-file
  • repeat
  • repeat-complex-command
  • replace-regexp
  • replace-string
  • report-emacs-bug
  • reposition-window
  • resize-minibuffer-mode
  • revert-buffer
  • revert-buffer (Dired)
  • rlogin
  • rlogin-directory-tracking-mode
  • rmail
  • rmail-add-label
  • rmail-beginning-of-message
  • rmail-bury
  • rmail-continue
  • rmail-delete-backward
  • rmail-delete-forward
  • rmail-edit-current-message
  • rmail-expunge
  • rmail-first-message
  • rmail-forward
  • rmail-get-new-mail
  • rmail-input
  • rmail-kill-label
  • rmail-last-message
  • rmail-mail
  • rmail-mode
  • rmail-next-labeled-message
  • rmail-next-message
  • rmail-next-undeleted-message
  • rmail-output
  • rmail-output-body-to-file
  • rmail-output-to-rmail-file
  • rmail-previous-labeled-message
  • rmail-previous-message
  • rmail-previous-undeleted-message
  • rmail-quit
  • rmail-reply
  • rmail-resend
  • rmail-retry-failure
  • rmail-save
  • rmail-search
  • rmail-show-message
  • rmail-summary
  • rmail-summary-by-labels
  • rmail-summary-by-recipients
  • rmail-summary-by-topic
  • rmail-summary-quit
  • rmail-summary-wipe
  • rmail-toggle-header
  • rmail-undelete-previous-message
  • rot13-other-window
  • run-lisp

    • s

  • save-buffer
  • save-buffers-kill-emacs
  • save-some-buffers
  • scroll-bar-mode
  • scroll-calendar-left
  • scroll-calendar-left-three-months
  • scroll-calendar-right
  • scroll-calendar-right-three-months
  • scroll-down
  • scroll-left
  • scroll-other-window
  • scroll-right
  • scroll-up
  • sdb
  • search-backward
  • search-forward
  • select-frame-by-name
  • self-insert
  • send-invisible
  • server-edit
  • set-background-color
  • set-border-color
  • set-buffer-file-coding-system
  • set-buffer-process-coding-system
  • set-comment-column
  • set-cursor-color
  • set-fill-column
  • set-fill-prefix
  • set-foreground-color
  • set-frame-font
  • set-frame-name
  • set-goal-column
  • set-input-method
  • set-justification-center
  • set-justification-full
  • set-justification-left
  • set-justification-none
  • set-justification-right
  • set-keyboard-coding-system
  • set-language-environment
  • set-mark-command
  • set-mouse-color
  • set-next-selection-coding-system
  • set-rmail-inbox-list
  • set-selection-coding-system
  • set-selective-display
  • set-terminal-coding-system
  • set-variable
  • set-visited-file-name
  • setq-default
  • shell
  • shell-backward-command
  • shell-command
  • shell-command-on-region
  • shell-forward-command
  • shell-pushd-dextract
  • shell-pushd-dunique
  • shell-pushd-tohome
  • show-all
  • show-all-diary-entries
  • show-branches
  • show-children
  • show-entry
  • show-paren-mode
  • show-subtree
  • shrink-window-if-larger-than-buffer
  • slitex-mode
  • sort-columns
  • sort-fields
  • sort-lines
  • sort-numeric-fields
  • sort-pages
  • sort-paragraphs
  • split-line
  • split-window-horizontally
  • split-window-vertically
  • spook
  • standard-display-8bit
  • start-kbd-macro
  • string-rectangle
  • substitute-in-file-name
  • substitute-key-definition
  • sunrise-sunset
  • suspend-emacs
  • switch-to-buffer
  • switch-to-buffer-other-frame
  • switch-to-buffer-other-window
  • switch-to-completions

    • t

  • tab-to-tab-stop
  • tabify
  • tags-apropos
  • tags-loop-continue
  • tags-query-replace
  • tags-search
  • telnet
  • tex-bibtex-file
  • tex-buffer
  • tex-close-latex-block
  • tex-file
  • tex-insert-braces
  • tex-insert-quote
  • tex-kill-job
  • tex-latex-block
  • tex-mode
  • tex-print
  • tex-recenter-output-buffer
  • tex-region
  • tex-show-print-queue
  • tex-terminate-paragraph
  • tex-validate-region
  • tex-view
  • text-mode
  • tmm-menubar
  • toggle-input-method
  • toggle-scroll-bar
  • top-level
  • transient-mark-mode
  • transpose-chars
  • transpose-lines
  • transpose-sexps, transpose-sexps
  • transpose-words, transpose-words
  • turn-on-font-lock

    • u

  • undigestify-rmail-message
  • undo
  • unexpand-abbrev
  • unforward-rmail-message
  • universal-argument
  • universal-coding-system-argument
  • unrmail
  • untabify
  • up-list
  • upcase-region
  • upcase-word

    • v

  • vc-annotate
  • vc-cancel-version
  • vc-create-snapshot
  • vc-diff
  • vc-directory
  • vc-dired-mark-locked
  • vc-dired-toggle-terse-mode
  • vc-insert-headers
  • vc-merge
  • vc-next-action
  • vc-print-log
  • vc-register
  • vc-rename-file
  • vc-retrieve-snapshot
  • vc-revert-buffer
  • vc-toggle-read-only, vc-toggle-read-only
  • vc-update-change-log
  • vc-version-other-window
  • vi-mode
  • view-buffer
  • view-diary-entries
  • view-emacs-FAQ
  • view-emacs-news
  • view-file
  • view-hello-file
  • view-lossage
  • view-register
  • vip-mode
  • viper-mode
  • visit-tags-table

    • w

  • what-cursor-position
  • what-line
  • what-page
  • where-is
  • which-function-mode
  • widen
  • widget-backward
  • widget-complete
  • widget-forward
  • window-configuration-to-register
  • word-search-backward
  • word-search-forward
  • write-abbrev-file
  • write-file
  • write-region

    • x

  • xdb

    • y

  • yank
  • yank-pop
  • yank-rectangle
  • yow

    • z

  • zap-to-char

    • Variable Index

    a

  • abbrev-all-caps
  • abbrev-file-name
  • abbrev-mode
  • adaptive-fill-first-line-regexp
  • adaptive-fill-function
  • adaptive-fill-mode
  • adaptive-fill-regexp
  • ange-ftp-default-user
  • appt-display-diary
  • appt-issue-message
  • apropos-do-all
  • auto-coding-alist
  • auto-mode-alist
  • auto-save-default
  • auto-save-interval
  • auto-save-list-file-prefix
  • auto-save-timeout
  • auto-save-visited-file-name

    • b

  • backup-by-copying
  • backup-by-copying-when-linked
  • backup-by-copying-when-mismatch
  • backup-enable-predicate
  • baud-rate
  • blink-matching-delay
  • blink-matching-paren
  • blink-matching-paren-distance
  • bookmark-save-flag
  • bookmark-search-size
  • buffer-file-coding-system
  • buffer-read-only

    • c

  • c-basic-offset
  • c-comment-only-line-offset
  • c-comment-start-regexp
  • c-default-style
  • c-hanging-comment-ender-p
  • c-hanging-comment-starter-p
  • c-hungry-delete-key
  • c-mode-hook
  • c-mode-map
  • c-offsets-alist
  • c-special-indent-hook
  • c-strict-syntax-p
  • c-style-alist
  • c-syntactic-context
  • calendar-daylight-savings-ends
  • calendar-daylight-savings-ends-time
  • calendar-daylight-savings-starts
  • calendar-daylight-time-offset
  • calendar-daylight-time-zone-name
  • calendar-latitude
  • calendar-location-name
  • calendar-longitude
  • calendar-standard-time-zone-name
  • calendar-time-zone
  • calendar-week-start-day
  • case-fold-search
  • case-replace
  • change-major-mode-with-file-name
  • coding
  • colon-double-space
  • comint-completion-addsuffix
  • comint-completion-autolist
  • comint-completion-fignore
  • comint-completion-recexact
  • comint-input-autoexpand
  • comint-input-ignoredups
  • comint-prompt-regexp
  • comint-scroll-show-maximum-output
  • comint-scroll-to-bottom-on-input
  • comint-scroll-to-bottom-on-output
  • command-history
  • command-line-args
  • comment-column
  • comment-end
  • comment-indent-function
  • comment-line-start
  • comment-line-start-skip
  • comment-multi-line
  • comment-padding
  • comment-start
  • comment-start-skip
  • compare-ignore-case
  • compilation-scroll-output
  • compile-command
  • completion-auto-help
  • completion-ignored-extensions
  • ctl-arrow
  • ctl-x-4-map
  • ctl-x-map
  • current-input-method

    • d

  • dabbrev-abbrev-char-regexp
  • dabbrev-abbrev-skip-leading-regexp
  • dabbrev-case-fold-search, dabbrev-case-fold-search
  • dabbrev-case-replace
  • dabbrev-check-all-buffers
  • dabbrev-limit
  • dbx-mode-hook
  • default-buffer-file-coding-system
  • default-directory
  • default-enable-multibyte-characters
  • default-input-method
  • default-justification
  • default-major-mode
  • delete-auto-save-files
  • delete-old-versions
  • desktop-enable
  • desktop-files-not-to-save
  • diary-file
  • diary-hook
  • diary-mail-days
  • diff-switches
  • dired-chown-program
  • dired-copy-preserve-time
  • dired-garbage-files-regexp
  • dired-kept-versions
  • dired-listing-switches
  • dired-listing-switches (MS-DOS)
  • display-time-24hr-format
  • dos-codepage
  • dos-display-scancodes
  • dos-hyper-key
  • dos-keypad-mode
  • dos-printer
  • dos-ps-printer
  • dos-super-key
  • dos-unsupported-character-glyph
  • double-click-time

    • e

  • echo-keystrokes
  • emacs-lisp-mode-hook
  • emerge-combine-versions-template
  • emerge-startup-hook
  • enable-multibyte-characters, enable-multibyte-characters
  • enable-recursive-minibuffers
  • enriched-fill-after-visiting
  • enriched-translations
  • eol-mnemonic-dos
  • eol-mnemonic-mac
  • eol-mnemonic-undecided
  • eol-mnemonic-unix
  • esc-map
  • european-calendar-style
  • exit-language-environment-hook
  • explicit-shell-file-name

    • f

  • fast-lock-cache-directories
  • fast-lock-minimum-size
  • fast-lock-save-others
  • file-coding-system-alist
  • file-name-buffer-file-type-alist
  • file-name-coding-system
  • file-name-handler-alist
  • fill-column
  • fill-prefix
  • find-file-existing-other-name
  • find-file-hooks
  • find-file-not-found-hooks
  • find-file-run-dired
  • find-file-visit-truename
  • find-ls-option
  • find-tag-marker-ring-length
  • font-lock-beginning-of-syntax-function
  • font-lock-mark-block-function
  • font-lock-maximum-decoration
  • font-lock-maximum-size
  • font-lock-support-mode
  • fortran-analyze-depth
  • fortran-break-before-delimiters
  • fortran-check-all-num...
  • fortran-column-ruler
  • fortran-comment-indent-char
  • fortran-comment-indent-style
  • fortran-comment-line-extra-indent
  • fortran-comment-region
  • fortran-continuation-indent
  • fortran-continuation-string
  • fortran-do-indent
  • fortran-electric-line-number
  • fortran-if-indent
  • fortran-line-number-indent
  • fortran-minimum-statement-indent...
  • fortran-structure-indent
  • fortran-tab-mode-default

    • g

  • gdb-mode-hook
  • gud-xdb-directories

    • h

  • help-map
  • highlight-nonselected-windows
  • highlight-wrong-size-font
  • history-length

    • i

  • indent-tabs-mode
  • indent-tabs-mode (Fortran mode)
  • inferior-lisp-program
  • inhibit-eol-conversion
  • initial-major-mode
  • input-method-highlight-flag
  • input-method-verbose-flag
  • insert-default-directory
  • interpreter-mode-alist
  • inverse-video
  • isearch-mode-map
  • ispell-dictionary

    • j

  • jdb-mode-hook

    • k

  • kept-new-versions
  • kept-old-versions
  • kill-buffer-hook
  • kill-ring
  • kill-ring-max
  • kill-whole-line

    • l

  • latex-block-names
  • latex-mode-hook
  • latex-run-command
  • lazy-lock-defer-contextually
  • lazy-lock-defer-on-scrolling
  • lazy-lock-defer-time
  • lazy-lock-minimum-size
  • lazy-lock-stealth-lines
  • lazy-lock-stealth-time
  • lazy-lock-stealth-verbose
  • line-number-display-limit
  • lisp-body-indent
  • lisp-indent-offset
  • lisp-interaction-mode-hook
  • lisp-mode-hook
  • lisp-mode-map
  • list-directory-brief-switches
  • list-directory-verbose-switches
  • load-path
  • lpr-add-switches
  • lpr-command (MS-DOS)
  • lpr-commands
  • lpr-headers-switches
  • lpr-headers-switches (MS-DOS)
  • lpr-switches
  • lpr-switches (MS-DOS)

    • m

  • mail-abbrevs
  • mail-aliases
  • mail-archive-file-name
  • mail-default-reply-to
  • mail-from-style
  • mail-mode-hook
  • mail-personal-alias-file
  • mail-self-blind
  • mail-setup-hook
  • mail-signature
  • mail-user-agent
  • mail-yank-prefix
  • make-backup-files
  • Man-fontify-manpage-flag
  • mark-even-if-inactive
  • mark-ring
  • mark-ring-max
  • message-log-max
  • midnight-hook
  • midnight-mode
  • minibuffer-local-completion-map
  • minibuffer-local-map
  • minibuffer-local-must-match-map
  • minibuffer-local-ns-map
  • minibuffer-scroll-overlap
  • mode-line-inverse-video
  • mode-specific-map
  • mouse-scroll-min-lines
  • mouse-yank-at-point
  • muddle-mode-hook

    • n

  • next-line-add-newlines
  • next-screen-context-lines
  • no-redraw-on-reenter
  • nroff-mode-hook

    • o

  • outline-level
  • outline-minor-mode-prefix
  • outline-mode-hook
  • outline-regexp

    • p

  • page-delimiter
  • paragraph-separate
  • paragraph-start
  • parens-require-spaces
  • pdb-mode-hook
  • perldb-mode-hook
  • picture-mode-hook
  • picture-tab-chars
  • plain-tex-mode-hook
  • print-region-function (MS-DOS)
  • printer-name
  • printer-name (MS-DOS)
  • ps-font-family
  • ps-font-info-database
  • ps-font-size
  • ps-landscape-mode
  • ps-lpr-command
  • ps-lpr-command (MS-DOS)
  • ps-lpr-switches
  • ps-lpr-switches (MS-DOS)
  • ps-number-of-columns
  • ps-page-dimensions-database
  • ps-paper-type
  • ps-print-color-p
  • ps-print-header
  • ps-printer-name
  • ps-printer-name (MS-DOS)

    • r

  • read-quoted-char-radix
  • require-final-newline
  • revert-without-query
  • rlogin-explicit-args
  • rmail-decode-mime-charset
  • rmail-delete-after-output
  • rmail-delete-message-hook
  • rmail-dont-reply-to-names
  • rmail-edit-mode-hook
  • rmail-file-coding-system
  • rmail-file-name
  • rmail-highlighted-headers
  • rmail-ignored-headers
  • rmail-mail-new-frame
  • rmail-mode-hook
  • rmail-movemail-flags
  • rmail-output-file-alist
  • rmail-pop-password
  • rmail-pop-password-required
  • rmail-preserve-inbox
  • rmail-primary-inbox-list
  • rmail-redisplay-summary
  • rmail-retry-ignored-headers
  • rmail-secondary-file-directory
  • rmail-secondary-file-regexp
  • rmail-summary-line-count-flag
  • rmail-summary-window-size

    • s

  • same-window-buffer-names
  • same-window-regexps
  • save-abbrevs
  • scheme-mode-hook
  • scroll-conservatively
  • scroll-margin
  • scroll-preserve-screen-position
  • sdb-mode-hook
  • search-slow-speed
  • search-slow-window-lines
  • selective-display-ellipses
  • sendmail-coding-system, sendmail-coding-system
  • sentence-end
  • sentence-end-double-space
  • server-temp-file-regexp
  • server-window
  • set-language-environment-hook
  • shell-cd-regexp
  • shell-command-default-error-buffer
  • shell-command-execonly
  • shell-command-regexp
  • shell-completion-fignore
  • shell-file-name
  • shell-input-ring-file-name
  • shell-popd-regexp
  • shell-prompt-pattern
  • shell-pushd-regexp
  • shell-set-directory-error-hook
  • slitex-mode-hook
  • slitex-run-command
  • sort-fold-case
  • special-display-buffer-names
  • special-display-frame-alist
  • special-display-regexps
  • split-window-keep-point
  • standard-fontset-spec
  • standard-indent
  • suggest-key-bindings

    • t

  • tab-stop-list
  • tab-width
  • tags-file-name
  • tags-table-list
  • term-file-prefix
  • term-setup-hook
  • tex-bibtex-command
  • tex-default-mode
  • tex-directory
  • tex-dvi-print-command
  • tex-dvi-view-command
  • tex-main-file
  • tex-mode-hook
  • tex-run-command
  • tex-shell-hook
  • tex-show-queue-command
  • tex-start-options-string
  • text-mode-hook
  • track-eol
  • truncate-lines
  • truncate-partial-width-windows

    • u

  • undo-limit
  • undo-strong-limit
  • unibyte-display-via-language-environment
  • user-mail-address

    • v

  • vc-command-messages
  • vc-comment-alist
  • vc-consult-headers
  • vc-default-back-end
  • vc-default-init-version
  • vc-directory-exclusion-list
  • vc-dired-recurse
  • vc-dired-terse-display
  • vc-follow-symlinks
  • vc-handle-cvs
  • vc-header-alist
  • vc-initial-comment
  • vc-keep-workfiles
  • vc-log-mode-hook
  • vc-make-backup-files, vc-make-backup-files
  • vc-mistrust-permissions
  • vc-path
  • vc-static-header-alist
  • vc-suppress-confirm
  • version-control
  • visible-bell

    • w

  • w32-pass-alt-to-system
  • which-func-modes
  • window-min-height
  • window-min-width

    • x

  • x-cut-buffer-max
  • xdb-mode-hook

    • Concept Index

    *

  • `*Messages*' buffer

    • .

  • `.mailrc' file

    • /

  • // in file name

    • 8

  • 8-bit display

    • a

  • A and B buffers (Emerge)
  • Abbrev mode
  • abbrevs
  • aborting recursive edit
  • accented characters
  • accessible portion
  • accumulating scattered text
  • action options (command line)
  • active fields (customization buffer)
  • adaptive filling
  • againformation
  • alarm clock
  • ange-ftp
  • appending kills in the ring
  • appointment notification
  • apropos
  • arguments (command line)
  • arguments, numeric
  • arguments, prefix
  • arrow keys
  • ASCII
  • Asm mode
  • astronomical day numbers
  • attribute (Rmail)
  • Auto Compression mode
  • Auto Fill mode
  • Auto Save mode
  • Auto-Lower mode
  • Auto-Raise mode
  • autoload
  • Awk mode

    • b

  • back end (version control)
  • backend options (VC)
  • backtrace for bug reports
  • backup file
  • backup file names on MS-DOS
  • base buffer
  • batch mode
  • binding
  • blank lines
  • blank lines in programs
  • body lines (Outline mode)
  • bold font
  • bookmarks
  • borders (X Windows)
  • boredom
  • branch (version control)
  • buffer menu
  • buffers
  • buggestion
  • bugs
  • building programs
  • button down events
  • byte code

    • c

  • C editing
  • c indentation styles
  • C mode
  • C++ mode
  • C-
  • calendar
  • calendar and LaTeX
  • calendar, first day of week
  • capitalizing words
  • case conversion
  • centering
  • change buffers
  • change log
  • Change Log mode
  • changes, undoing
  • character set (keyboard)
  • characters (in text), characters (in text)
  • checking out files
  • checking spelling
  • Chinese
  • Chinese calendar
  • choosing a major mode
  • citing mail
  • click events
  • codepage, MS-DOS
  • coding systems
  • collision
  • color of window (X Windows)
  • colors
  • Column Number mode
  • columns (and rectangles)
  • columns (indentation)
  • columns, splitting
  • Comint mode
  • command
  • command history
  • command line arguments
  • comments
  • comparing files
  • compilation errors
  • Compilation mode
  • compilation under MS-DOS
  • complete
  • complete key
  • completion
  • completion (symbol names)
  • completion in Lisp
  • completion using tags
  • compression
  • conflicts
  • connecting to remote host
  • continuation line
  • Control
  • control characters
  • Control-Meta
  • converting text to upper or lower case
  • Coptic calendar
  • copying files
  • copying text
  • CORBA IDL mode
  • correcting spelling
  • CPerl mode
  • crashes
  • creating files
  • creating frames
  • current buffer
  • cursor
  • cursor location
  • cursor location, under MS-DOS
  • cursor motion
  • customization
  • customization buffer
  • customization groups
  • customizing faces
  • customizing Lisp indentation
  • cut buffer
  • cutting and X
  • cutting text
  • CVS
  • cvs watch feature
  • CVSREAD environment variable (CVS)

    • d

  • day of year
  • daylight savings time
  • DBX
  • debuggers
  • default argument
  • default-frame-alist
  • defining keyboard macros
  • defuns
  • deleting blank lines
  • deleting characters and lines
  • deleting files (in Dired)
  • deletion
  • deletion (of files)
  • deletion (Rmail)
  • desktop
  • Devanagari
  • developediment
  • diary
  • diary file
  • digest message
  • directory header lines
  • directory listing
  • directory listing on MS-DOS
  • Dired
  • Dired sorting
  • disabled command
  • DISPLAY environment variable
  • display name (X Windows)
  • doctor
  • DOS codepages
  • double clicks
  • double slash in file name
  • down events
  • drag events
  • drastic changes
  • dribble file

    • e

  • echo area
  • editable fields (customization buffer)
  • editing binary files
  • editing in Picture mode
  • editing level, recursive
  • EDITOR environment variable
  • EDT
  • Eldoc mode
  • Eliza
  • Emacs as a server
  • Emacs initialization file
  • Emacs-Lisp mode
  • emacsclient
  • Emerge
  • emulating other editors
  • encoding of characters
  • end-of-line conversion, end-of-line conversion
  • end-of-line conversion on MS-DOS/MS-Windows
  • end-of-line conversion, mode-line indication
  • Enriched mode
  • entering Emacs
  • environment
  • environment variables
  • erasing characters and lines
  • error log
  • error message in the echo area
  • ESC replacing META key
  • ESHELL environment variable
  • etags program
  • Ethiopian
  • Ethiopic calendar
  • European character sets
  • exiting
  • exiting recursive edit
  • expanding subdirectories in Dired
  • expansion (of abbrevs)
  • expansion of C macros
  • expression
  • expunging (Dired)
  • expunging (Rmail)

    • f

  • faces
  • faces under MS-DOS
  • Fast Lock mode
  • file dates
  • file directory
  • file local variables
  • file names
  • file names under MS-DOS
  • file names under Windows 95/NT
  • file truenames
  • files
  • files, visiting and saving
  • fill prefix
  • filling text
  • find and Dired
  • finding strings within text
  • flagging files (in Dired)
  • flow control
  • Flyspell mode
  • Follow mode
  • font (default)
  • font (principal)
  • Font Lock mode
  • font name (X Windows)
  • fonts and faces
  • fonts, emulating under MS-DOS
  • fontsets
  • formatted text
  • formfeed
  • Fortran continuation lines
  • Fortran mode
  • forwarding a message
  • frame size under MS-DOS
  • frames
  • frames on MS-DOS
  • French Revolutionary calendar
  • FTP
  • function
  • function definition
  • function key

    • g

  • GDB
  • geometry (X Windows)
  • getting help with keys
  • global keymap
  • global mark ring
  • global substitution
  • Gnus
  • Go Moku
  • graphic characters
  • Greek
  • Gregorian calendar
  • growing minibuffer
  • GUD library
  • gzip

    • h

  • hard newline
  • hardcopy
  • head version
  • header (TeX mode)
  • header line (Dired)
  • headers (of mail message)
  • heading lines (Outline mode)
  • Hebrew calendar
  • height of minibuffer
  • help
  • Hexl mode
  • hiding in Dired (Dired)
  • highlighting region
  • Hindi
  • history of commands
  • history of minibuffer input
  • history reference
  • holidays
  • HOME directory under MS-DOS
  • hook
  • horizontal scrolling
  • Hscroll mode
  • Hyper (under MS-DOS)

    • i

  • Icomplete mode
  • Icon mode
  • icons (X Windows)
  • IDL mode
  • ignoriginal
  • in-situ subdirectory (Dired)
  • inbox file
  • incremental search
  • indentation
  • Indentation Calculation
  • indentation for comments
  • indentation for programs
  • indirect buffer
  • indirect buffers and outlines
  • inferior process
  • inferior processes under MS-DOS
  • Info
  • Info index completion
  • init file
  • init file, default name under MS-DOS
  • initial options (command line)
  • initial-frame-alist
  • input event
  • input methods
  • input with the keyboard
  • inserted subdirectory (Dired)
  • inserting blank lines
  • insertion
  • international scripts
  • international support (MS-DOS)
  • interval operator (in regexps)
  • invisible lines
  • IPA
  • Islamic calendar
  • ISO commercial calendar
  • ISO Latin character sets
  • iso-ascii library
  • iso-transl library
  • ispell program
  • italic font

    • j

  • Japanese
  • Java mode
  • JDB
  • Julian calendar
  • Julian day numbers
  • justification

    • k

  • Kerberos POP authentication
  • key
  • key bindings
  • key rebinding, permanent
  • key rebinding, this session
  • key sequence
  • keyboard input
  • keyboard macro
  • keyboard translations
  • keymap
  • kill ring
  • killing buffers
  • killing characters and lines
  • killing Emacs
  • killing rectangular areas of text
  • killing text
  • Korean

    • l

  • label (Rmail)
  • language environment, automatic selection on MS-DOS
  • language environments
  • Lao
  • LaTeX mode
  • Lazy Lock mode
  • leaving Emacs
  • libraries
  • line number commands
  • Line Number mode
  • line wrapping
  • Lisp editing
  • Lisp string syntax
  • Lisp symbol completion
  • list
  • listing current buffers
  • loading Lisp code
  • local keymap
  • local variables
  • local variables in files
  • location of point
  • locking (CVS)
  • locking and version control
  • locking files
  • locking under version control
  • locking, non-strict (RCS)
  • long file names in DOS box under Windows 95/NT
  • lpr usage under MS-DOS
  • Lucid Widget X Resources

    • m

  • M-
  • Macintosh end-of-line conversion
  • macro expansion in C
  • mail
  • mail (on mode line)
  • mail aliases
  • MAIL environment variable
  • Mail mode
  • mail-composition methods
  • MAILHOST environment variable
  • mailrc file
  • major modes
  • make
  • Makefile mode
  • making pictures out of text characters
  • manipulating paragraphs
  • manipulating sentences
  • manipulating text
  • manuals, on-line
  • Marathi
  • mark
  • mark ring
  • marking in Dired
  • marking sections of text
  • Markov chain
  • master file
  • matching parentheses
  • Mayan calendar
  • Mayan calendar round
  • Mayan haab calendar
  • Mayan long count
  • Mayan tzolkin calendar
  • memory full
  • menu bar
  • Menu Bar mode
  • Menu X Resources (Lucid widgets)
  • Menu X Resources (Motif widgets)
  • merge buffer (Emerge)
  • merging changes
  • merging files
  • message
  • message number
  • messages saved from echo area
  • Meta
  • Meta (under MS-DOS)
  • Meta commands and words
  • Midnight mode
  • minibuffer
  • minibuffer history
  • minibuffer keymaps
  • minor mode keymap
  • minor modes
  • mistakes, correcting
  • mode hook
  • mode line
  • mode line (MS-DOS)
  • mode, Abbrev
  • mode, Auto Compression
  • mode, Auto Fill
  • mode, Auto Save
  • mode, C
  • mode, Column Number
  • mode, Comint
  • mode, Compilation
  • mode, CORBA IDL
  • mode, Emacs-Lisp
  • mode, Enriched
  • mode, Fast Lock
  • mode, Follow
  • mode, Font Lock
  • mode, Fortran
  • mode, Hexl
  • mode, Hscroll
  • mode, Java
  • mode, LaTeX
  • mode, Lazy Lock
  • mode, Line Number
  • mode, Mail
  • mode, major
  • mode, Menu Bar
  • mode, minor
  • mode, Objective C
  • mode, Outline
  • mode, Overwrite
  • mode, Paragraph-Indent Text
  • mode, Pike
  • mode, Resize-Minibuffer
  • mode, Scroll Bar
  • mode, Shell
  • mode, SliTeX
  • mode, TeX
  • mode, Text
  • mode, Transient Mark
  • mode, View
  • modes for programming languages
  • modified (buffer)
  • moon, phases of
  • Motif Widget X Resources
  • mouse
  • mouse button events
  • mouse buttons (what they do)
  • mouse support under MS-DOS
  • movemail
  • movemail program
  • movement
  • moving inside the calendar
  • moving point
  • moving text
  • moving the cursor
  • MS-DOG
  • MS-DOS end-of-line conversion
  • MS-DOS peculiarities
  • MULE
  • multibyte characters
  • multiple displays
  • multiple views of outline
  • multiple windows in Emacs
  • mustatement

    • n

  • named configurations (RCS)
  • narrowing
  • newline
  • newlines, hard and soft
  • NFS and quitting
  • non-strict locking (RCS)
  • non-window terminals
  • nonincremental search
  • nroff
  • NSA
  • numeric arguments

    • o

  • Objective C mode
  • on-line manuals
  • operating on files in Dired
  • operations on a marked region
  • option, user
  • options (command line)
  • other editors
  • out of memory
  • Outline mode
  • outline with multiple views
  • outragedy
  • Overwrite mode

    • p

  • pages
  • Paragraph-Indent Text mode
  • paragraphs
  • parentheses
  • parts of the screen
  • pasting
  • pasting and X
  • patches, sending
  • PDB
  • per-buffer variables
  • Perl mode
  • Perldb
  • Persian calendar
  • phases of the moon
  • Picture mode and rectangles
  • pictures
  • Pike mode
  • point
  • point location
  • point location, under MS-DOS
  • POP inboxes
  • POP inboxes in reverse order
  • prefix arguments
  • prefix key
  • preprocessor highlighting
  • presidentagon
  • primary Rmail file
  • primary selection
  • printing under MS-DOS
  • program building
  • program editing
  • prompt
  • properbose
  • puzzles

    • q

  • query replace
  • quitting, quitting
  • quitting (in search)
  • quitting Emacs
  • quitting on MS-DOS
  • quoting
  • quoting file names

    • r

  • RCS
  • read-only buffer
  • reading mail
  • reading netnews
  • rebinding keys, permanently
  • rebinding keys, this session
  • rebinding major mode keys
  • rebinding mouse buttons
  • rectangle
  • rectangles and Picture mode
  • recursive editing level
  • regexp
  • regexp syntax
  • region
  • region face
  • region highlighting
  • registered file
  • registers
  • regular expression
  • remote file access
  • remote host
  • repeating a command
  • replacement
  • reply to a message
  • REPLYTO environment variable
  • reporting bugs
  • Resize-Minibuffer mode
  • resolving conflicts
  • resources
  • restriction
  • retrying a failed message
  • Rlogin
  • Rmail
  • rot13 code
  • running Lisp functions
  • Russian

    • s

  • saved echo area messages
  • saving files
  • saving keyboard macros
  • saving option value
  • saving sessions
  • SCCS
  • screen
  • Scroll Bar mode
  • scrolling
  • scrolling in the calendar
  • SDB
  • search-and-replace commands
  • searching
  • searching in Rmail
  • secondary selection
  • selected buffer
  • selected window
  • selecting buffers in other windows
  • selection, primary
  • selective display
  • selective undo
  • self-documentation
  • sending mail
  • sending patches for GNU Emacs
  • sentences
  • server, using Emacs as
  • setting a mark
  • setting option value
  • setting variables
  • sexp
  • shell commands
  • shell commands, Dired
  • SHELL environment variable
  • Shell mode
  • Show Paren mode
  • simultaneous editing
  • single-frame terminals
  • size of minibuffer
  • slashes repeated in file name
  • SliTeX mode
  • snapshots and version control
  • soft newline
  • sorting
  • sorting Dired buffer
  • speedbar
  • spelling, checking and correcting
  • splitting columns
  • standard fontset
  • starting Emacs
  • startup (command line arguments)
  • startup (init file)
  • startup fontset
  • stealth fontification
  • string substitution
  • string syntax
  • subdirectories in Dired
  • subscribe groups
  • subshell
  • subtree (Outline mode)
  • summary (Rmail)
  • sunrise and sunset
  • Super (under MS-DOS)
  • suspending
  • switch buffers
  • switches (command line)
  • syntactic analysis
  • syntactic component
  • syntactic symbol
  • syntax highlighting
  • syntax table

    • t

  • tab stops
  • tables, indentation for
  • tags completion
  • tags table
  • Tcl mode
  • techniquitous
  • television
  • Telnet
  • TERM environment variable
  • termscript file
  • TeX mode
  • TEXEDIT environment variable
  • TEXINPUTS environment variable
  • text
  • text and binary files on MS-DOS/MS-Windows
  • Text mode
  • Thai
  • Tibetan
  • time (on mode line)
  • top level
  • tower of Hanoi
  • Transient Mark mode
  • transposition
  • triple clicks
  • truenames of files
  • truncation
  • trunk (version control)
  • two-column editing
  • typos, fixing

    • u

  • uncompression
  • undeletion (Rmail)
  • undigestify
  • undo
  • undo limit
  • Unibyte operation
  • unibyte operation, unibyte operation
  • unibyte operation (MS-DOS)
  • unsubscribe groups
  • untranslated file system
  • user option
  • userenced
  • using tab stops in making tables

    • v

  • variable
  • vc-resolve-conflicts
  • version control
  • VERSION_CONTROL environment variable
  • vi
  • Vietnamese
  • View mode
  • viewing
  • views of an outline
  • visiting files, visiting files

    • w

  • watching files (CVS)
  • weeks, which day they start on
  • widening
  • Windows clipboard support
  • windows in Emacs
  • word processing
  • word search
  • word wrap
  • words
  • words, case conversion
  • work file
  • wrapping
  • WYSIWYG

    • x

  • X cutting and pasting
  • XDB
  • xon-xoff

    • y

  • yahrzeits
  • yanking
  • yanking previous kills

    • z

  • Zippy
  • Zmacs mode

    • Footnotes

    (1)

    On terminals that support Latin-1 characters, the character shown after `Char:' is displayed as the actual glyph of A with grave accent.

    (2)

    In some editors, search-and-replace operations are the only convenient way to make a single change in the text.

    (3)

    Some systems use Mouse-3 for a mode-specific menu. We took a survey of users, and found they preferred to keep Mouse-3 for selecting and killing regions. Hence the decision to use C-Mouse-3 for this menu.

    (4)

    It is also specified for MIME `text/*' bodies and in other network transport contexts. It is different from the SGML reference syntax record-start/record-end format which Emacs doesn't support directly.

    (5)

    You should not suspend the shell process. Suspending a subjob of the shell is a completely different matter--that is normal practice, but you must use the shell to continue the subjob; this command won't do it.

    (6)

    This dissociword actually appeared during the Vietnam War, when it was very appropriate.

    (7)

    Normally, one particular codepage is burnt into the display memory, while other codepages can be installed by modifying system configuration files, such as `CONFIG.SYS', and rebooting.

    (8)

    The standard Emacs coding systems for ISO 8859 are not quite right for the purpose, because typically the DOS codepage does not match the standard ISO character codes. For example, the letter `@,{c'

    (9)

    The wording here was careless. The intention was that nobody would have to pay for permission to use the GNU system. But the words don't make this clear, and people often interpret them as saying that copies of GNU should always be distributed at little or no charge. That was never the intent; later on, the manifesto mentions the possibility of companies providing the service of distribution for a profit. Subsequently I have learned to distinguish carefully between "free" in the sense of freedom and "free" in the sense of price. Free software is software that users have the freedom to distribute and change. Some users may obtain copies at no charge, while others pay to obtain copies--and if the funds help support improving the software, so much the better. The important thing is that everyone who has a copy has the freedom to cooperate with others in using it.

    (10)

    This is another place I failed to distinguish carefully between the two different meanings of "free". The statement as it stands is not false--you can get copies of GNU software at no charge, from your friends or over the net. But it does suggest the wrong idea.

    (11)

    Several such companies now exist.

    (12)

    The Free Software Foundation raises most of its funds from a distribution service, although it is a charity rather than a company. If no one chooses to obtain copies by ordering from the FSF, it will be unable to do its work. But this does not mean that proprietary restrictions are justified to force every user to pay. If a small fraction of all the users order copies from the FSF, that is sufficient to keep the FSF afloat. So we ask users to choose to support us in this way. Have you done your part?

    (13)

    A group of computer companies recently pooled funds to support maintenance of the GNU C Compiler.

    This document was generated on 1 October 2001 using the texi2html translator version 1.54.


GNU file utilities

This manual documents version 4.1 of the GNU file utilities.

1. Introduction | Caveats, overview, and authors.
2. Common options
3. File permissions | Access modes.
4. Date input formats | Specifying date strings.
5. Directory listing | ls dir vdir d v dircolors
6. Basic operations | cp dd install mv rm shred
7. Special file types | ln mkdir rmdir mkfifo mknod
8. Changing file attributes | chgrp chmod chown touch
9. Disk usage | df du sync
Index | General index.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Introduction

This manual is incomplete: No attempt is made to explain basic file concepts in a way suitable for novices. Thus, if you are interested, please get involved in improving this manual. The entire GNU community will benefit.

The GNU file utilities are mostly compatible with the POSIX.2 standard.

Please report bugs to bug-fileutils@gnu.org. Remember to include the version number, machine architecture, input files, and any other information needed to reproduce the bug: your input, what you expected, what you got, and why it is wrong. Diffs are welcome, but please include a description of the problem as well, since this is sometimes difficult to infer. See section `Bugs' in GNU CC.

This manual was originally derived from the Unix man pages in the distribution, which were written by David MacKenzie and updated by Jim Meyering. What you are reading now is the authoritative documentation for these utilities; the man pages are no longer being maintained. François Pinard did the initial conversion to Texinfo format. Karl Berry did the indexing, some reorganization, and editing of the results. Richard Stallman contributed his usual invaluable insights to the overall process.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. Common options

Certain options are available in all of these programs (in fact, every GNU program should accept them). Rather than writing identical descriptions for each of the programs, they are described here.

`--help'
Print a usage message listing all available options, then exit successfully.

`--version'
Print the version number, then exit successfully.

2.1 Backup options | -b -S -V, in some programs.
2.2 Block size | BLOCK_SIZE and --block-size, in some programs.
2.3 Target directory | --target-directory, in some programs.
2.4 Trailing slashes | --strip-trailing-slashes, in some programs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 Backup options

Some GNU programs (at least cp, install, ln, and mv) optionally make backups of files before writing new versions. These options control the details of these backups. The options are also briefly mentioned in the descriptions of the particular programs.

`-b'
`--backup[=method]'
Make a backup of each file that would otherwise be overwritten or removed. Without this option, the original versions are destroyed. Use method to determine the type of backups to make. When this option is used but method is not specified, then the value of the VERSION_CONTROL environment variable is used. And if VERSION_CONTROL is not set, the default backup type is `existing'.

Note that the short form of this option, `-b' does not accept any argument. Using `-b' is equivalent to using `--backup=existing'.

This option corresponds to the Emacs variable `version-control'; the values for method are the same as those used in Emacs. This option also accepts more descriptive names. The valid methods are (unique abbreviations are accepted):

`none'
`off'
Never make backups.

`numbered'
`t'
Always make numbered backups.

`existing'
`nil'
Make numbered backups of files that already have them, simple backups of the others.

`simple'
`never'
Always make simple backups. Please note `never' is not to be confused with `none'.

`-S suffix'
`--suffix=suffix'
Append suffix to each backup file made with `-b'. If this option is not specified, the value of the SIMPLE_BACKUP_SUFFIX environment variable is used. And if SIMPLE_BACKUP_SUFFIX is not set, the default is `~', just as in Emacs.

`--version-control=method'
This option is obsolete and will be removed in a future release. It has been replaced with --backup.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 Block size

Some GNU programs (at least df, du, and ls) display file sizes in "blocks". You can adjust the block size to make file sizes easier to read. The block size used for display is independent of any filesystem block size.

Normally, disk usage sizes are rounded up, disk free space sizes are rounded down, and other sizes are rounded to the nearest value with ties rounding to an even value.

The default block size is chosen by examining the following environment variables in turn; the first one that is set determines the block size.

DF_BLOCK_SIZE
This specifies the default block size for the df command. Similarly, DU_BLOCK_SIZE specifies the default for du and LS_BLOCK_SIZE for ls.

BLOCK_SIZE
This specifies the default block size for all three commands, if the above command-specific environment variables are not set.

POSIXLY_CORRECT
If neither the command_BLOCK_SIZE nor the BLOCK_SIZE variables are set, but this variable is set, the block size defaults to 512.

If none of the above environment variables are set, the block size currently defaults to 1024 bytes, but this number may change in the future.

A block size specification can be a positive integer specifying the number of bytes per block, or it can be human-readable or si to select a human-readable format.

With human-readable formats, output sizes are followed by a size letter such as `M' for megabytes. BLOCK_SIZE=human-readable uses powers of 1024; `M' stands for 1,048,576 bytes. BLOCK_SIZE=si is similar, but uses powers of 1000; `M' stands for 1,000,000 bytes. (SI, the International System of Units, defines these power-of-1000 prefixes.)

An integer block size can be followed by a size letter to specify a multiple of that size. When this notation is used, the size letters normally stand for powers of 1024, and can be followed by an optional `B' for "byte"; but if followed by `D' (for "decimal byte"), they stand for powers of 1000. For example, BLOCK_SIZE=4MB is equivalent to BLOCK_SIZE=4194304, and BLOCK_SIZE=4MD is equivalent to BLOCK_SIZE=4000000.

The following size letters are defined. Large sizes like 1Y may be rejected by your computer due to limitations of its arithmetic.

`k'
kilo: 2^10 = 1024 for human-readable, or 10^3 = 1000 for si.
`M'
Mega: 2^20 = 1,048,576 or 10^6 = 1,000,000.
`G'
Giga: 2^30 = 1,073,741,824 or 10^9 = 1,000,000,000.
`T'
Tera: 2^40 = 1,099,511,627,776 or 10^12 = 1,000,000,000,000.
`P'
Peta: 2^50 = 1,125,899,906,842,624 or 10^15 = 1,000,000,000,000,000.
`E'
Exa: 2^60 = 1,152,921,504,606,846,976 or 10^18 = 1,000,000,000,000,000,000.
`Z'
Zetta: 2^70 = 1,180,591,620,717,411,303,424 or 10^21 = 1,000,000,000,000,000,000,000.
`Y'
Yotta: 2^80 = 1,208,925,819,614,629,174,706,176 or 10^24 = 1,000,000,000,000,000,000,000,000.

Block size defaults can be overridden by an explicit `--block-size=size' option. The `-k' or `--kilobytes' option is equivalent to `--block-size=1k', which is the default unless the POSIXLY_CORRECT environment variable is set. The `-h' or `--human-readable' option is equivalent to `--block-size=human-readable'. The `--si' option is equivalent to `--block-size=si'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.3 Target directory

Some GNU programs (at least cp, install, ln, and mv) allow you to specify the target directory via this option:

`--target-directory=directory'
Specify the destination directory.

The interface for most programs is that after processing options and a finite (possibly zero) number of fixed-position arguments, the remaining argument list is either expected to be empty, or is a list of items (usually files) that will all be handled identically. The xargs program is designed to work well with this convention.

The commands in the mv-family are unusual in that they take a variable number of arguments with a special case at the end (namely, the target directory). This makes it nontrivial to perform some operations, e.g., "move all files from here to ../d/", because mv * ../d/ might exhaust the argument space, and ls | xargs ... doesn't have a clean way to specify an extra final argument for each invocation of the subject command. (It can be done by going through a shell command, but that requires more human labor and brain power than it should.)

The --target-directory option allows the cp, install, ln, and mv programs to be used conveniently with xargs. For example, you can move the files from the current directory to a sibling directory, d like this: (However, this doesn't move files whose names begin with `.'.)

ls |xargs mv --target-directory=../d

If you use the GNU find program, you can move all files with this command:
find . -mindepth 1 -maxdepth 1 \
  | xargs mv --target-directory=../d

But that will fail if there are no files in the current directory or if any file has a name containing a newline character. The following example removes those limitations and requires both GNU find and GNU xargs:
find . -mindepth 1 -maxdepth 1 -print0 \
  | xargs --null --no-run-if-empty \
      mv --target-directory=../d

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.4 Trailing slashes

Some GNU programs (at least cp and mv) allow you to remove any trailing slashes from each source argument before operating on it. The --strip-trailing-slashes option enables this behavior.

This is useful when a source argument may have a trailing slash and specify a symbolic link to a directory. This scenario is in fact rather common because some shells can automatically append a trailing slash when performing file name completion on such symbolic links. Without this option, mv, for example, (via the system's rename function) must interpret a trailing slash as a request to dereference the symbolic link and so must rename the indirectly referenced directory and not the symbolic link. Although it may seem surprising that such behavior be the default, it is required by POSIX.2 and is consistent with other parts of that standard.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. File permissions

Each file has a set of permissions that control the kinds of access that users have to that file. The permissions for a file are also called its access mode. They can be represented either in symbolic form or as an octal number.

3.1 Structure of File Permissions | Structure of file permissions.
3.2 Symbolic Modes | Mnemonic permissions representation.
3.3 Numeric Modes | Permissions as octal numbers.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 Structure of File Permissions

There are three kinds of permissions that a user can have for a file:

  1. permission to read the file. For directories, this means permission to list the contents of the directory.
  2. permission to write to (change) the file. For directories, this means permission to create and remove files in the directory.
  3. permission to execute the file (run it as a program). For directories, this means permission to access files in the directory.

There are three categories of users who may have different permissions to perform any of the above operations on a file:

  1. the file's owner;
  2. other users who are in the file's group;
  3. everyone else.

Files are given an owner and group when they are created. Usually the owner is the current user and the group is the group of the directory the file is in, but this varies with the operating system, the filesystem the file is created on, and the way the file is created. You can change the owner and group of a file by using the chown and chgrp commands.

In addition to the three sets of three permissions listed above, a file's permissions have three special components, which affect only executable files (programs) and, on some systems, directories:

  1. set the process's effective user ID to that of the file upon execution (called the setuid bit). No effect on directories.
  2. set the process's effective group ID to that of the file upon execution (called the setgid bit). For directories on some systems, put files created in the directory into the same group as the directory, no matter what group the user who creates them is in.
  3. save the program's text image on the swap device so it will load more quickly when run (called the sticky bit). For directories on some systems, prevent users from removing or renaming a file in a directory unless they own the file or the directory; this is called the restriction deletion flag for the directory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 Symbolic Modes

Symbolic modes represent changes to files' permissions as operations on single-character symbols. They allow you to modify either all or selected parts of files' permissions, optionally based on their previous values, and perhaps on the current umask as well (see section 3.2.6 The Umask and Protection).

The format of symbolic modes is:

[ugoa...][[+-=][rwxXstugo...]...][,...]

The following sections describe the operators and other details of symbolic modes.

3.2.1 Setting Permissions | Basic operations on permissions.
3.2.2 Copying Existing Permissions | Copying existing permissions.
3.2.3 Changing Special Permissions | Special permissions.
3.2.4 Conditional Executability | Conditionally affecting executability.
3.2.5 Making Multiple Changes | Making multiple changes.
3.2.6 The Umask and Protection | The effect of the umask.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.1 Setting Permissions

The basic symbolic operations on a file's permissions are adding, removing, and setting the permission that certain users have to read, write, and execute the file. These operations have the following format:

users operation permissions

The spaces between the three parts above are shown for readability only; symbolic modes cannot contain spaces.

The users part tells which users' access to the file is changed. It consists of one or more of the following letters (or it can be empty; see section 3.2.6 The Umask and Protection, for a description of what happens then). When more than one of these letters is given, the order that they are in does not matter.

u
the user who owns the file;
g
other users who are in the file's group;
o
all other users;
a
all users; the same as `ugo'.

The operation part tells how to change the affected users' access to the file, and is one of the following symbols:

+
to add the permissions to whatever permissions the users already have for the file;
-
to remove the permissions from whatever permissions the users already have for the file;
=
to make the permissions the only permissions that the users have for the file.

The permissions part tells what kind of access to the file should be changed; it is zero or more of the following letters. As with the users part, the order does not matter when more than one letter is given. Omitting the permissions part is useful only with the `=' operation, where it gives the specified users no access at all to the file.

r
the permission the users have to read the file;
w
the permission the users have to write to the file;
x
the permission the users have to execute the file.

For example, to give everyone permission to read and write a file, but not to execute it, use:

a=rw

To remove write permission for from all users other than the file's owner, use:

go-w

The above command does not affect the access that the owner of the file has to it, nor does it affect whether other users can read or execute the file.

To give everyone except a file's owner no permission to do anything with that file, use the mode below. Other users could still remove the file, if they have write permission on the directory it is in.

go=

Another way to specify the same thing is:

og-rxw

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.2 Copying Existing Permissions

You can base a file's permissions on its existing permissions. To do this, instead of using `r', `w', or `x' after the operator, you use the letter `u', `g', or `o'. For example, the mode
o+g
adds the permissions for users who are in a file's group to the permissions that other users have for the file. Thus, if the file started out as mode 664 (`rw-rw-r--'), the above mode would change it to mode 666 (`rw-rw-rw-'). If the file had started out as mode 741 (`rwxr----x'), the above mode would change it to mode 745 (`rwxr--r-x'). The `-' and `=' operations work analogously.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.3 Changing Special Permissions

In addition to changing a file's read, write, and execute permissions, you can change its special permissions. See section 3.1 Structure of File Permissions, for a summary of these permissions.

To change a file's permission to set the user ID on execution, use `u' in the users part of the symbolic mode and `s' in the permissions part.

To change a file's permission to set the group ID on execution, use `g' in the users part of the symbolic mode and `s' in the permissions part.

To change a file's permission to stay permanently on the swap device, use `o' in the users part of the symbolic mode and `t' in the permissions part.

For example, to add set user ID permission to a program, you can use the mode:

u+s

To remove both set user ID and set group ID permission from it, you can use the mode:

ug-s

To cause a program to be saved on the swap device, you can use the mode:

o+t

Remember that the special permissions only affect files that are executable, plus, on some systems, directories (on which they have different meanings; see section 3.1 Structure of File Permissions). Also, the combinations `u+t', `g+t', and `o+s' have no effect.

The `=' operator is not very useful with special permissions; for example, the mode:

o=t

does cause the file to be saved on the swap device, but it also removes all read, write, and execute permissions that users not in the file's group might have had for it.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.4 Conditional Executability

There is one more special type of symbolic permission: if you use `X' instead of `x', execute permission is affected only if the file already had execute permission or is a directory. It affects directories' execute permission even if they did not initially have any execute permissions set.

For example, this mode:

a+X

gives all users permission to execute files (or search directories) if anyone could before.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.5 Making Multiple Changes

The format of symbolic modes is actually more complex than described above (see section 3.2.1 Setting Permissions). It provides two ways to make multiple changes to files' permissions.

The first way is to specify multiple operation and permissions parts after a users part in the symbolic mode.

For example, the mode:

og+rX-w

gives users other than the owner of the file read permission and, if it is a directory or if someone already had execute permission to it, gives them execute permission; and it also denies them write permission to the file. It does not affect the permission that the owner of the file has for it. The above mode is equivalent to the two modes:

og+rX
og-w

The second way to make multiple changes is to specify more than one simple symbolic mode, separated by commas. For example, the mode:

a+r,go-w

gives everyone permission to read the file and removes write permission on it for all users except its owner. Another example:

u=rwx,g=rx,o=

sets all of the non-special permissions for the file explicitly. (It gives users who are not in the file's group no permission at all for it.)

The two methods can be combined. The mode:

a+r,g+x-w

gives all users permission to read the file, and gives users who are in the file's group permission to execute it, as well, but not permission to write to it. The above mode could be written in several different ways; another is:

u+r,g+rx,o+r,g-w

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.6 The Umask and Protection

If the users part of a symbolic mode is omitted, it defaults to `a' (affect all users), except that any permissions that are set in the system variable umask are not affected. The value of umask can be set using the umask command. Its default value varies from system to system.

Omitting the users part of a symbolic mode is generally not useful with operations other than `+'. It is useful with `+' because it allows you to use umask as an easily customizable protection against giving away more permission to files than you intended to.

As an example, if umask has the value 2, which removes write permission for users who are not in the file's group, then the mode:

+w

adds permission to write to the file to its owner and to other users who are in the file's group, but not to other users. In contrast, the mode:

a+w

ignores umask, and does give write permission for the file to all users.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 Numeric Modes

File permissions are stored internally as integers. As an alternative to giving a symbolic mode, you can give an octal (base 8) number that corresponds to the internal representation of the new mode. This number is always interpreted in octal; you do not have to add a leading 0, as you do in C. Mode 0055 is the same as mode 55.

A numeric mode is usually shorter than the corresponding symbolic mode, but it is limited in that it cannot take into account a file's previous permissions; it can only set them absolutely.

On most systems, the permissions granted to the user, to other users in the file's group, and to other users not in the file's group are each stored as three bits, which are represented as one octal digit. The three special permissions are also each stored as one bit, and they are as a group represented as another octal digit. Here is how the bits are arranged, starting with the lowest valued bit:

Value in  Corresponding
Mode      Permission

          Other users not in the file's group:
   1      Execute
   2      Write
   4      Read

          Other users in the file's group:
  10      Execute
  20      Write
  40      Read

          The file's owner:
 100      Execute
 200      Write
 400      Read

          Special permissions:
1000      Save text image on swap device
2000      Set group ID on execution
4000      Set user ID on execution

For example, numeric mode 4755 corresponds to symbolic mode `u=rwxs,go=rx', and numeric mode 664 corresponds to symbolic mode `ug=rw,o=r'. Numeric mode 0 corresponds to symbolic mode `ugo='.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Date input formats

First, a quote:

Our units of temporal measurement, from seconds on up to months, are so complicated, asymmetrical and disjunctive so as to make coherent mental reckoning in time all but impossible. Indeed, had some tyrannical god contrived to enslave our minds to time, to make it all but impossible for us to escape subjection to sodden routines and unpleasant surprises, he could hardly have done better than handing down our present system. It is like a set of trapezoidal building blocks, with no vertical or horizontal surfaces, like a language in which the simplest thought demands ornate constructions, useless particles and lengthy circumlocutions. Unlike the more successful patterns of language and science, which enable us to face experience boldly or at least level-headedly, our system of temporal calculation silently and persistently encourages our terror of time.

... It is as though architects had to measure length in feet, width in meters and height in ells; as though basic instruction manuals demanded a knowledge of five different languages. It is no wonder then that we often look into our own immediate past or future, last Tuesday or a week from Sunday, with feelings of helpless confusion. ...

--- Robert Grudin, Time and the Art of Living.

This section describes the textual date representations that GNU programs accept. These are the strings you, as a user, can supply as arguments to the various programs. The C interface (via the getdate function) is not described here.

Although the date syntax here can represent any possible time since the year zero, computer integers often cannot represent such a wide range of time. On POSIX systems, the clock starts at 1970-01-01 00:00:00 UTC: POSIX does not require support for times before the POSIX Epoch and times far in the future. Traditional Unix systems have 32-bit signed time_t and can represent times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 UTC. Systems with 64-bit signed time_t can represent all the times in the known lifetime of the universe.

4.1 General date syntax | Common rules.
4.2 Calendar date items | 19 Dec 1994.
4.3 Time of day items | 9:20pm.
4.4 Time zone items | EST, PDT, GMT, ...
4.5 Day of week items | Monday and others.
4.6 Relative items in date strings | next tuesday, 2 years ago.
4.7 Pure numbers in date strings | 19931219, 1440.
4.8 Authors of getdate | Bellovin, Eggert, Salz, Berets, et al.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 General date syntax

A date is a string, possibly empty, containing many items separated by whitespace. The whitespace may be omitted when no ambiguity arises. The empty string means the beginning of today (i.e., midnight). Order of the items is immaterial. A date string may contain many flavors of items:

  • calendar date items
  • time of the day items
  • time zone items
  • day of the week items
  • relative items
  • pure numbers.

We describe each of these item types in turn, below.

A few numbers may be written out in words in most contexts. This is most useful for specifying day of the week items or relative items (see below). Here is the list: `first' for 1, `next' for 2, `third' for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6, `seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10, `eleventh' for 11 and `twelfth' for 12. Also, `last' means exactly -1.

When a month is written this way, it is still considered to be written numerically, instead of being "spelled in full"; this changes the allowed strings.

In the current implementation, only English is supported for words and abbreviations like `AM', `DST', `EST', `first', `January', `Sunday', `tomorrow', and `year'.

The output of date is not always acceptable as a date string, not only because of the language problem, but also because there is no standard meaning for time zone items like `IST'. When using date to generate a date string intended to be parsed later, specify a date format that is independent of language and that does not use time zone items other than `UTC' and `Z'. Here are some ways to do this:

$ LC_ALL=C TZ=UTC0 date
Fri Dec 15 19:48:05 UTC 2000
$ TZ=UTC0 date +"%Y-%m-%d %H:%M:%SZ"
2000-12-15 19:48:05Z
$ date --iso-8601=seconds  # a GNU extension
2000-12-15T11:48:05-0800
$ date --rfc-822  # a GNU extension
Fri, 15 Dec 2000 11:48:05 -0800
$ date +"%Y-%m-%d %H:%M:%S %z"  # %z is a GNU extension.
2000-12-15 11:48:05 -0800

Alphabetic case is completely ignored in dates. Comments may be introduced between round parentheses, as long as included parentheses are properly nested. Hyphens not followed by a digit are currently ignored. Leading zeros on numbers are ignored.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2 Calendar date items

A calendar date item specifies a day of the year. It is specified differently, depending on whether the month is specified numerically or literally. All these strings specify the same calendar date:

1972-09-24     # ISO 8601.
72-9-24        # Assume 19xx for 69 through 99,
               # 20xx for 00 through 68.
72-09-24       # Leading zeros are ignored.
9/24/72        # Common U.S. writing.
24 September 1972
24 Sept 72     # September has a special abbreviation.
24 Sep 72      # Three-letter abbreviations always allowed.
Sep 24, 1972
24-sep-72
24sep72

The year can also be omitted. In this case, the last specified year is used, or the current year if none. For example:

9/24
sep 24

Here are the rules.

For numeric months, the ISO 8601 format `year-month-day' is allowed, where year is any positive number, month is a number between 01 and 12, and day is a number between 01 and 31. A leading zero must be present if a number is less than ten. If year is 68 or smaller, then 2000 is added to it; otherwise, if year is less than 100, then 1900 is added to it. The construct `month/day/year', popular in the United States, is accepted. Also `month/day', omitting the year.

Literal months may be spelled out in full: `January', `February', `March', `April', `May', `June', `July', `August', `September', `October', `November' or `December'. Literal months may be abbreviated to their first three letters, possibly followed by an abbreviating dot. It is also permitted to write `Sept' instead of `September'.

When months are written literally, the calendar date may be given as any of the following:

day month year
day month
month day year
day-month-year

Or, omitting the year:

month day

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3 Time of day items

A time of day item in date strings specifies the time on a given day. Here are some examples, all of which represent the same time:

20:02:0
20:02
8:02pm
20:02-0500      # In EST (U.S. Eastern Standard Time).

More generally, the time of the day may be given as `hour:minute:second', where hour is a number between 0 and 23, minute is a number between 0 and 59, and second is a number between 0 and 59. Alternatively, `:second' can be omitted, in which case it is taken to be zero.

If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), hour is restricted to run from 1 to 12, and `:minute' may be omitted (taken to be zero). `am' indicates the first half of the day, `pm' indicates the second half of the day. In this notation, 12 is the predecessor of 1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented interpretation of `12am' and `12pm', as opposed to the old tradition derived from Latin which uses `12m' for noon and `12pm' for midnight.)

The time may alternatively be followed by a time zone correction, expressed as `shhmm', where s is `+' or `-', hh is a number of zone hours and mm is a number of zone minutes. When a time zone correction is given this way, it forces interpretation of the time relative to Coordinated Universal Time (UTC), overriding any previous specification for the time zone or the local time zone. The minute part of the time of the day may not be elided when a time zone correction is used. This is the best way to specify a time zone correction by fractional parts of an hour.

Either `am'/`pm' or a time zone correction may be specified, but not both.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4 Time zone items

A time zone item specifies an international time zone, indicated by a small set of letters, e.g., `UTC' or `Z' for Coordinated Universal Time. Any included periods are ignored. By following a non-daylight-saving time zone by the string `DST' in a separate word (that is, separated by some white space), the corresponding daylight saving time zone may be specified.

Time zone items other than `UTC' and `Z' are obsolescent and are not recommended, because they are ambiguous; for example, `EST' has a different meaning in Australia than in the United States. Instead, it's better to use unambiguous numeric time zone corrections like `-0500', as described in the previous section.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5 Day of week items

The explicit mention of a day of the week will forward the date (only if necessary) to reach that day of the week in the future.

Days of the week may be spelled out in full: `Sunday', `Monday', `Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may be abbreviated to their first three letters, optionally followed by a period. The special abbreviations `Tues' for `Tuesday', `Wednes' for `Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.

A number may precede a day of the week item to move forward supplementary weeks. It is best used in expression like `third monday'. In this context, `last day' or `next day' is also acceptable; they move one week before or after the day that day by itself would represent.

A comma following a day of the week item is ignored.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6 Relative items in date strings

Relative items adjust a date (or the current date if none) forward or backward. The effects of relative items accumulate. Here are some examples:

1 year
1 year ago
3 years
2 days

The unit of time displacement may be selected by the string `year' or `month' for moving by whole years or months. These are fuzzy units, as years and months are not all of equal duration. More precise units are `fortnight' which is worth 14 days, `week' worth 7 days, `day' worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60 seconds, and `second' or `sec' worth one second. An `s' suffix on these units is accepted and ignored.

The unit of time may be preceded by a multiplier, given as an optionally signed number. Unsigned numbers are taken as positively signed. No number at all implies 1 for a multiplier. Following a relative item by the string `ago' is equivalent to preceding the unit by a multiplier with value -1.

The string `tomorrow' is worth one day in the future (equivalent to `day'), the string `yesterday' is worth one day in the past (equivalent to `day ago').

The strings `now' or `today' are relative items corresponding to zero-valued time displacement, these strings come from the fact a zero-valued time displacement represents the current time when not otherwise changed by previous items. They may be used to stress other items, like in `12:00 today'. The string `this' also has the meaning of a zero-valued time displacement, but is preferred in date strings like `this thursday'.

When a relative item causes the resulting date to cross a boundary where the clocks were adjusted, typically for daylight-saving time, the resulting date and time are adjusted accordingly.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.7 Pure numbers in date strings

The precise interpretation of a pure decimal number depends on the context in the date string.

If the decimal number is of the form yyyymmdd and no other calendar date item (see section 4.2 Calendar date items) appears before it in the date string, then yyyy is read as the year, mm as the month number and dd as the day of the month, for the specified calendar date.

If the decimal number is of the form hhmm and no other time of day item appears before it in the date string, then hh is read as the hour of the day and mm as the minute of the hour, for the specified time of the day. mm can also be omitted.

If both a calendar date and a time of day appear to the left of a number in the date string, but no relative item, then the number overrides the year.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.8 Authors of getdate

getdate was originally implemented by Steven M. Bellovin (smb@research.att.com) while at the University of North Carolina at Chapel Hill. The code was later tweaked by a couple of people on Usenet, then completely overhauled by Rich $alz (rsalz@bbn.com) and Jim Berets (jberets@bbn.com) in August, 1990. Various revisions for the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert and others.

This chapter was originally produced by François Pinard (pinard@iro.umontreal.ca) from the `getdate.y' source code, and then edited by K. Berry (kb@cs.umb.edu).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Directory listing

This chapter describes the ls command and its variants dir and vdir, which list information about files.

5.1 ls: List directory contents | List directory contents.
5.2 dir: Briefly list directory contents | Briefly ls.
5.3 vdir: Verbosely list directory contents | Verbosely ls.
5.4 dircolors: Color setup for ls | Color setup for ls, etc.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 ls: List directory contents

The ls program lists information about files (of any type, including directories). Options and file arguments can be intermixed arbitrarily, as usual.

For non-option command-line arguments that are directories, by default ls lists the contents of directories, not recursively, and omitting files with names beginning with `.'. For other non-option arguments, by default ls lists just the file name. If no non-option arguments are specified, ls lists the contents of the current directory.

By default, the output is sorted alphabetically. If standard output is a terminal, the output is in columns (sorted vertically) and control characters are output as question marks; otherwise, the output is listed one per line and control characters are output as-is.

Because ls is such a fundamental program, it has accumulated many options over the years. They are described in the subsections below; within each section, options are listed alphabetically (ignoring case). The division of options into the subsections is not absolute, since some options affect more than one aspect of ls's operation.

The `-g' option is accepted but ignored, for compatibility with Unix. Also see 2. Common options.

5.1.1 Which files are listed
5.1.2 What information is listed
5.1.3 Sorting the output
5.1.4 More details about version sort
5.1.5 General output formatting
5.1.6 Formatting the file names

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.1 Which files are listed

These options determine which files ls lists information for. By default, any files and the contents of any directories on the command line are shown.

`-a'
`--all'
List all files in directories, including files that start with `.'.

`-A'
`--almost-all'
List all files in directories except for `.' and `..'.

`-B'
`--ignore-backups'
Do not list files that end with `~', unless they are given on the command line.

`-d'
`--directory'
List just the names of directories, as with other types of files, rather than listing their contents.

`-I PATTERN'
`--ignore=PATTERN'
Do not list files whose names match the shell pattern (not regular expression) pattern unless they are given on the command line. As in the shell, an initial `.' in a file name does not match a wildcard at the start of pattern. Sometimes it is useful to give this option several times. For example,

$ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'

The first option ignores names of length 3 or more that start with `.', the second ignores all two-character names that start with `.' except `..', and the third ignores names that start with `#'.

`-L'
`--dereference'
In a long listing, show file information (e.g., times and permissions) for the referents of symbolic links rather than for the symbolic links themselves.

`-R'
`--recursive'
List the contents of all directories recursively.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.2 What information is listed

These options affect the information that ls displays. By default, only file names are shown.

`-D'
`--dired'
With the long listing (`-l') format, print an additional line after the main output:

//DIRED// beg1 end1 beg2 end2 ...

The begN and endN are unsigned integers that record the byte position of the beginning and end of each file name in the output. This makes it easy for Emacs to find the names, even when they contain unusual characters such as space or newline, without fancy searching.

If directories are being listed recursively (-R), output a similar line after each subdirectory:
//SUBDIRED// format beg1 end1 ...

Finally, output a line of the form:
//DIRED-OPTIONS// --quoting-style=word
where word is the quoting style (see section 5.1.6 Formatting the file names).

`-G'
`--no-group'
Inhibit display of group information in a long format directory listing. (This is the default in some non-GNU versions of ls, so we provide this option for compatibility.)

`-h'
`--human-readable'
Append a size letter such as `M' for megabytes to each size. Powers of 1024 are used, not 1000; `M' stands for 1,048,576 bytes. Use the `--si' option if you prefer powers of 1000.

`-H'
`--si'
Append a size letter such as `M' for megabytes to each size. (SI is the International System of Units, which defines these letters as prefixes.) Powers of 1000 are used, not 1024; `M' stands for 1,000,000 bytes. Use the `-h' or `--human-readable' option if you prefer powers of 1024.

Warning: the meaning of `-H' will change in the future to conform to POSIX. Use `--si' for the old meaning.

`-i'
`--inode'
Print the inode number (also called the file serial number and index number) of each file to the left of the file name. (This number uniquely identifies each file within a particular filesystem.)

`-l'
`--format=long'
`--format=verbose'
In addition to the name of each file, print the file type, permissions, number of hard links, owner name, group name, size in bytes, and timestamp (by default, the modification time). For files with a time more than six months old or in the future, the timestamp contains the year instead of the time of day. If the timestamp contains today's date with the year rather than a time of day, the file's time is in the future, which means you probably have clock skew problems which may break programs like make that rely on file times.

For each directory that is listed, preface the files with a line `total blocks', where blocks is the total disk allocation for all files in that directory. The block size currently defaults to 1024 bytes, but this can be overridden (see section 2.2 Block size). The blocks computed counts each hard link separately; this is arguably a deficiency.

The permissions listed are similar to symbolic mode specifications (see section 3.2 Symbolic Modes). But ls combines multiple bits into the third character of each set of permissions as follows:

`s'
If the setuid or setgid bit and the corresponding executable bit are both set.

`S'
If the setuid or setgid bit is set but the corresponding executable bit is not set.

`t'
If the sticky bit and the other-executable bit are both set.

`T'
If the sticky bit is set but the other-executable bit is not set.

`x'
If the executable bit is set and none of the above apply.

`-'
Otherwise.

Following the permission bits is a single character that specifies whether an alternate access method applies to the file. When that character is a space, there is no alternate access method. When it is a printing character (e.g., `+'), then there is such a method.

`-o'
Produce long format directory listings, but don't display group information. It is equivalent to using `--format=long' with `--no-group' . This option is provided for compatibility with other versions of ls.

`-s'
`--size'
Print the disk allocation of each file to the left of the file name. This is the amount of disk space used by the file, which is usually a bit more than the file's size, but it can be less if the file has holes.

Normally the disk allocation is printed in units of 1024 bytes, but this can be overridden (see section 2.2 Block size).

For files that are NFS-mounted from an HP-UX system to a BSD system, this option reports sizes that are half the correct values. On HP-UX systems, it reports sizes that are twice the correct values for files that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX; it also affects the HP-UX ls program.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.3 Sorting the output

These options change the order in which ls sorts the information it outputs. By default, sorting is done by character code (e.g., ASCII order).

`-c'
`--time=ctime'
`--time=status'
`--time=use'
If the long listing format (e.g., `-l', `-o') is being used, print the status change time (the `ctime' in the inode) instead of the modification time. When explicitly sorting by time (`--sort=time' or `-t') or when not using a long listing format, sort according to the status change time.

`-f'
Primarily, like `-U'---do not sort; list the files in whatever order they are stored in the directory. But also enable `-a' (list all files) and disable `-l', `--color', and `-s' (if they were specified before the `-f').

`-r'
`--reverse'
Reverse whatever the sorting method is--e.g., list files in reverse alphabetical order, youngest first, smallest first, or whatever.

`-S'
`--sort=size'
Sort by file size, largest first.

`-t'
`--sort=time'
Sort by modification time (the `mtime' in the inode), newest first.

`-u'
`--time=atime'
`--time=access'
If the long listing format (e.g., `--format=long') is being used, print the last access time (the `atime' in the inode). When explicitly sorting by time (`--sort=time' or `-t') or when not using a long listing format, sort according to the access time.

`-U'
`--sort=none'
Do not sort; list the files in whatever order they are stored in the directory. (Do not do any of the other unrelated things that `-f' does.) This is especially useful when listing very large directories, since not doing any sorting can be noticeably faster.

`-v'
`--sort=version'
Sort by version name and number, lowest first. It behaves like a default sort, except that each sequence of decimal digits is treated numerically as an index/version number. (See section 5.1.4 More details about version sort.)

`-X'
`--sort=extension'
Sort directory contents alphabetically by file extension (characters after the last `.'); files with no extension are sorted first.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.4 More details about version sort

The version sort takes into account the fact that file names frequently include indices or version numbers. Standard sorting functions usually do not produce the ordering that people expect because comparisons are made on a character-by-character basis. The version sort addresses this problem, and is especially useful when browsing directories that contain many files with indices/version numbers in their names:

      > ls -1            > ls -1v
      foo.zml-1.gz       foo.zml-1.gz
      foo.zml-100.gz     foo.zml-2.gz
      foo.zml-12.gz      foo.zml-6.gz
      foo.zml-13.gz      foo.zml-12.gz
      foo.zml-2.gz       foo.zml-13.gz
      foo.zml-25.gz      foo.zml-25.gz
      foo.zml-6.gz       foo.zml-100.gz

Note also that numeric parts with leading zeroes are considered as fractional one:

      > ls -1            > ls -1v
      abc-1.007.tgz      abc-1.007.tgz
      abc-1.012b.tgz     abc-1.01a.tgz
      abc-1.01a.tgz      abc-1.012b.tgz

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.5 General output formatting

These options affect the appearance of the overall output.

`-1'
`--format=single-column'
List one file per line. This is the default for ls when standard output is not a terminal.

`-C'
`--format=vertical'
List files in columns, sorted vertically. This is the default for ls if standard output is a terminal. It is always the default for the dir and d programs. GNU ls uses variable width columns to display as many files as possible in the fewest lines.

`--color [=when]'
Specify whether to use color for distinguishing file types. when may be omitted, or one of:
  • none - Do not use color at all. This is the default.
  • auto - Only use color if standard output is a terminal.
  • always - Always use color.
Specifying `--color' and no when is equivalent to `--color=always'. Piping a colorized listing through a pager like more or less usually produces unreadable results. However, using more -f does seem to work.

`-F'
`--classify'
`--indicator-style=classify'
Append a character to each file name indicating the file type. Also, for regular files that are executable, append `*'. The file type indicators are `/' for directories, `@' for symbolic links, `|' for FIFOs, `=' for sockets, and nothing for regular files.

`--full-time'
List times in full, rather than using the standard abbreviation heuristics. The format is currently similar to that of date, but this is planned to change in a future release, partly because modern file time stamps have more precision. It's not possible to change the format, but you can extract out the date string with cut and then pass the result to date -d. See section `date invocation' in Shell utilities.

This is most useful because the time output includes the seconds. (Unix filesystems store file timestamps only to the nearest second, so this option shows all the information there is.) For example, this can help when you have a Makefile that is not regenerating files properly.

`--indicator-style=word'
Append a character indicator with style word to entry names, as follows:
`none'
Do not append any character indicator; this is the default.
`file-type'
Append `/' for directories, `@' for symbolic links, `|' for FIFOs, `=' for sockets, and nothing for regular files. This is the same as the `-p' or `--file-type' option.
`classify'
Append `*' for executable regular files, otherwise behave as for `file-type'. This is the same as the `-F' or `--classify' option.

`-k'
`--kilobytes'
Print file sizes in 1024-byte blocks, overriding the default block size (see section 2.2 Block size).

`-m'
`--format=commas'
List files horizontally, with as many as will fit on each line, separated by `, ' (a comma and a space).

`-n'
`--numeric-uid-gid'
List the numeric UID and GID instead of the names.

`-p'
`--file-type'
`--indicator-style=file-type'
Append a character to each file name indicating the file type. This is like `-F', except that executables are not marked.

`-x format'
`--format=across'
`--format=horizontal'
List the files in columns, sorted horizontally.

`-T cols'
`--tabsize=cols'
Assume that each tabstop is cols columns wide. The default is 8. ls uses tabs where possible in the output, for efficiency. If cols is zero, do not use tabs at all.

`-w'
`--width=cols'
Assume the screen is cols columns wide. The default is taken from the terminal settings if possible; otherwise the environment variable COLUMNS is used if it is set; otherwise the default is 80.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.6 Formatting the file names

These options change how file names themselves are printed.

`-b'
`--escape'
`--quoting-style=escape'
Quote nongraphic characters in file names using alphabetic and octal backslash sequences like those used in C.

`-N'
`--literal'
Do not quote file names.

`-q'
`--hide-control-chars'
Print question marks instead of nongraphic characters in file names. This is the default if the output is a terminal and the program is ls.

`-Q'
`--quote-name'
`--quoting-style=c'
Enclose file names in double quotes and quote nongraphic characters as in C.

`--quoting-style=word'
Use style word to quote output names. The word should be one of the following:
`literal'
Output names as-is.
`shell'
Quote names for the shell if they contain shell metacharacters or would cause ambiguous output.
`shell-always'
Quote names for the shell, even if they would normally not require quoting.
`c'
Quote names as for a C language string; this is the same as the `-Q' or `--quote-name' option.
`escape'
Quote as with `c' except omit the surrounding double-quote characters; this is the same as the `-b' or `--escape' option.
`clocale'
Quote as with `c' except use quotation marks appropriate for the locale.
`locale'
Like `clocale', but quote `like this' instead of "like this" in the default C locale. This looks nicer on many displays.

You can specify the default value of the `--quoting-style' option with the environment variable QUOTING_STYLE. If that environment variable is not set, the default value is `literal', but this default may change to `shell' in a future version of this package.

`--show-control-chars'
Print nongraphic characters as-is in file names. This is the default unless the output is a terminal and the program is ls.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 dir: Briefly list directory contents

dir (also installed as d) is equivalent to ls -C -b; that is, by default files are listed in columns, sorted vertically, and special characters are represented by backslash escape sequences.

See section ls.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.3 vdir: Verbosely list directory contents

vdir (also installed as v) is equivalent to ls -l -b; that is, by default files are listed in long format and special characters are represented by backslash escape sequences.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4 dircolors: Color setup for ls

dircolors outputs a sequence of shell commands to set up the terminal for color output from ls (and dir, etc.). Typical usage:

eval `dircolors [option]... [file]`

If file is specified, dircolors reads it to determine which colors to use for which file types and extensions. Otherwise, a precompiled database is used. For details on the format of these files, run `dircolors --print-database'.

The output is a shell command to set the LS_COLORS environment variable. You can specify the shell syntax to use on the command line, or dircolors will guess it from the value of the SHELL environment variable.

The program accepts the following options. Also see 2. Common options.

`-b'
`--sh'
`--bourne-shell'
Output Bourne shell commands. This is the default if the SHELL environment variable is set and does not end with `csh' or `tcsh'.

`-c'
`--csh'
`--c-shell'
Output C shell commands. This is the default if SHELL ends with csh or tcsh.

`-p'
`--print-database'
Print the (compiled-in) default color configuration database. This output is itself a valid configuration file, and is fairly descriptive of the possibilities.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Basic operations

This chapter describes the commands for basic file manipulation: copying, moving (renaming), and deleting (removing).

6.1 cp: Copy files and directories | Copy files.
6.2 dd: Convert and copy a file | Convert and copy a file.
6.3 install: Copy files and set attributes | Copy files and set attributes.
6.4 mv: Move (rename) files | Move (rename) files.
6.5 rm: Remove files or directories | Remove files or directories.
6.6 shred: Remove files more securely | Remove files more securely.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1 cp: Copy files and directories

cp copies files (or, optionally, directories). The copy is completely independent of the original. You can either copy one file to another, or copy arbitrarily many files to a destination directory. Synopsis:

cp [option]... source dest
cp [option]... source... directory

If the last argument names an existing directory, cp copies each source file into that directory (retaining the same name). Otherwise, if only two files are given, it copies the first onto the second. It is an error if the last argument is not a directory and more than two non-option arguments are given.

Generally, files are written just as they are read. For exceptions, see the `--sparse' option below.

By default, cp does not copy directories. However, the `-R', `-a', and `-r' options cause cp to copy recursively by descending into source directories and copying files to corresponding destination directories.

By default, cp follows symbolic links only when not copying recursively. This default can be overridden with the `--no-dereference' (`-d'), `--dereference' (`-L'), and `-H' options. If more than one of these options is specified, the last one silently overrides the others.

cp generally refuses to copy a file onto itself, with the following exception: if `--force --backup' is specified with source and dest identical, and referring to a regular file, cp will make a backup file, either regular or numbered, as specified in the usual ways (see section 2.1 Backup options). This is useful when you simply want to make a backup of an existing file before changing it.

The program accepts the following options. Also see 2. Common options.

`-a'
`--archive'
Preserve as much as possible of the structure and attributes of the original files in the copy (but do not attempt to preserve internal directory structure; i.e., `ls -U' may list the entries in a copied directory in a different order). Equivalent to `-dpR'.

`-b'
`--backup[=method]'
See section 2.1 Backup options. Make a backup of each file that would otherwise be overwritten or removed. As a special case, cp makes a backup of source when the force and backup options are given and source and dest are the same name for an existing, regular file. One useful application of this combination of options is this tiny Bourne shell script:

#!/bin/sh
# Usage: backup FILE...
# Create a GNU-style backup of each listed FILE.
for i in "$@"; do
  cp --backup --force "$i" "$i"
done

`-d'
`--no-dereference'
Copy symbolic links as symbolic links rather than copying the files that they point to, and preserve hard links between source files in the copies.

`-f'
`--force'
When copying without this option and an existing destination file cannot be opened for writing, the copy fails. However, with `--force'), when a destination file cannot be opened, cp then unlinks it and tries to open it again. Contrast this behavior with that enabled by `--link' and `--symbolic-link', whereby the destination file is never opened but rather is unlinked unconditionally. Also see the description of `--remove-destination'.

`-H'
If a command line argument specifies a symbolic link, then copy the file it points to rather than the symbolic link itself. However, copy (preserving its nature) any symbolic link that is encountered via recursive traversal.

`-i'
`--interactive'
Prompt whether to overwrite existing regular destination files.

`-l'
`--link'
Make hard links instead of copies of non-directories.

`-L'
`--dereference'
Always follow symbolic links.

`-p'
`--preserve'
Preserve the original files' owner, group, permissions, and timestamps. In the absence of this option, each destination file is created with the permissions of the corresponding source file, minus the bits set in the umask. See section 3. File permissions.

`-P'
`--parents'
Form the name of each destination file by appending to the target directory a slash and the specified name of the source file. The last argument given to cp must be the name of an existing directory. For example, the command:

cp --parents a/b/c existing_dir

copies the file `a/b/c' to `existing_dir/a/b/c', creating any missing intermediate directories.

Warning: the meaning of `-P' will change in the future to conform to POSIX. Use `--parents' for the old meaning, and `--no-dereference' for the new.

`-r'
Copy directories recursively, copying any non-directories and special files (e.g., symbolic links, FIFOs and device files) as if they were regular files. This means trying to read the data in each source file and writing it to the destination. It is usually a mistake to apply cp -r to special files like FIFOs and the ones typically found in the `/dev' directory. In most cases, cp -r will hang indefinitely trying to read from FIFOs and special files like `/dev/console', and it will fill up your destination disk if you use it to copy `/dev/zero'. Use the `--recursive' (`-R') option instead if you want to copy special files, preserving their special nature rather than reading from them to copy their contents.

`-R'
`--recursive'
Copy directories recursively, preserving non-directories (contrast with `-r' just above).

`--remove-destination'
Remove each existing destination file before attempting to open it (contrast with `-f' above).

`--sparse=when'
A sparse file contains holes---a sequence of zero bytes that does not occupy any physical disk blocks; the `read' system call reads these as zeroes. This can both save considerable disk space and increase speed, since many binary files contain lots of consecutive zero bytes. By default, cp detects holes in input source files via a crude heuristic and makes the corresponding output file sparse as well.

The when value can be one of the following:

`auto'
The default behavior: the output file is sparse if the input file is sparse.

`always'
Always make the output file sparse. This is useful when the input file resides on a filesystem that does not support sparse files (the most notable example is `efs' filesystems in SGI IRIX 5.3 and earlier), but the output file is on another type of filesystem.

`never'
Never make the output file sparse. This is useful in creating a file for use with the mkswap command, since such a file must not have any holes.

`--strip-trailing-slashes'
Remove any trailing slashes from each source argument. See section 2.4 Trailing slashes.

`-s'
`--symbolic-link'
Make symbolic links instead of copies of non-directories. All source file names must be absolute (starting with `/') unless the destination files are in the current directory. This option merely results in an error message on systems that do not support symbolic links.

`-S suffix'
`--suffix=suffix'
Append suffix to each backup file made with `-b'. See section 2.1 Backup options.

`--target-directory=directory'
Specify the destination directory. See section 2.3 Target directory.

`-v'
`--verbose'
Print the name of each file before copying it.

`-V method'
`--version-control=method'
Change the type of backups made with `-b'. The method argument can be `none' (or `off'), `numbered' (or `t'), `existing' (or `nil'), or `never' (or `simple'). See section 2.1 Backup options.

`-x'
`--one-file-system'
Skip subdirectories that are on different filesystems from the one that the copy started on. However, mount point directories are copied.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.2 dd: Convert and copy a file

dd copies a file (from standard input to standard output, by default) with a changeable I/O block size, while optionally performing conversions on it. Synopsis:

dd [option]...

The program accepts the following options. Also see 2. Common options.

The numeric-valued options below (bytes and blocks) can be followed by a multiplier: `b'=512, `c'=1, `w'=2, `xm'=m, or any of the standard block size suffixes like `k'=1024 (see section 2.2 Block size).

Use different dd invocations to use different block sizes for skipping and I/O. For example, the following shell commands copy data in 512 kB blocks between a disk and a tape, but do not save or restore a 4 kB label at the start of the disk:

disk=/dev/rdsk/c0t1d0s2
tape=/dev/rmt/0

# Copy all but the label from disk to tape.
(dd bs=4k skip=1 count=0 && dd bs=512k) <$disk >$tape

# Copy from tape back to disk, but leave the disk label alone.
(dd bs=4k seek=1 count=0 && dd bs=512k) <$tape >$disk

`if=file'
Read from file instead of standard input.

`of=file'
Write to file instead of standard output. Unless `conv=notrunc' is given, dd truncates file to zero bytes (or the size specified with `seek=').

`ibs=bytes'
Read bytes bytes at a time.

`obs=bytes'
Write bytes bytes at a time.

`bs=bytes'
Both read and write bytes bytes at a time. This overrides `ibs' and `obs'.

`cbs=bytes'
Convert bytes bytes at a time.

`skip=blocks'
Skip blocks `ibs'-byte blocks in the input file before copying.

`seek=blocks'
Skip blocks `obs'-byte blocks in the output file before copying.

`count=blocks'
Copy blocks `ibs'-byte blocks from the input file, instead of everything until the end of the file.

`conv=conversion[,conversion]...'
Convert the file as specified by the conversion argument(s). (No spaces around any comma(s).)

Conversions:

`ascii'
Convert EBCDIC to ASCII.

`ebcdic'
Convert ASCII to EBCDIC.

`ibm'
Convert ASCII to alternate EBCDIC.

`block'
For each line in the input, output `cbs' bytes, replacing the input newline with a space and padding with spaces as necessary.

`unblock'
Replace trailing spaces in each `cbs'-sized input block with a newline.

`lcase'
Change uppercase letters to lowercase.

`ucase'
Change lowercase letters to uppercase.

`swab'
Swap every pair of input bytes. GNU dd, unlike others, works when an odd number of bytes are read--the last byte is simply copied (since there is nothing to swap it with).

`noerror'
Continue after read errors.

`notrunc'
Do not truncate the output file.

`sync'
Pad every input block to size of `ibs' with trailing zero bytes. When use with `block' or `unblock', pad with spaces instead of zero bytes.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3 install: Copy files and set attributes

install copies files while setting their permission modes and, if possible, their owner and group. Synopses:

install [option]... source dest
install [option]... source... directory
install -d [option]... directory...

In the first of these, the source file is copied to the dest target file. In the second, each of the source files are copied to the destination directory. In the last, each directory (and any missing parent directories) is created.

install is similar to cp, but allows you to control the attributes of destination files. It is typically used in Makefiles to copy programs into their destination directories. It refuses to copy files onto themselves.

The program accepts the following options. Also see 2. Common options.

`-b'
`--backup[=method]'
See section 2.1 Backup options. Make a backup of each file that would otherwise be overwritten or removed.

`-c'
Ignored; for compatibility with old Unix versions of install.

`-d'
`--directory'
Create each given directory and any missing parent directories, setting the owner, group and mode as given on the command line or to the defaults. It also gives any parent directories it creates those attributes. (This is different from the SunOS 4.x install, which gives directories that it creates the default attributes.)

`-g group'
`--group=group'
Set the group ownership of installed files or directories to group. The default is the process' current group. group may be either a group name or a numeric group id.

`-m mode'
`--mode=mode'
Set the permissions for the installed file or directory to mode, which can be either an octal number, or a symbolic mode as in chmod, with 0 as the point of departure (see section 3. File permissions). The default mode is `u=rwx,go=rx'---read, write, and execute for the owner, and read and execute for group and other.

`-o owner'
`--owner=owner'
If install has appropriate privileges (is run as root), set the ownership of installed files or directories to owner. The default is root. owner may be either a user name or a numeric user ID.

`-p'
`--preserve-timestamps'
Set the time of last access and the time of last modification of each installed file to match those of each corresponding original file. When a file is installed without this option, its last access and last modification times are both set to the time of installation. This option is useful if you want to use the last modification times of installed files to keep track of when they were last built as opposed to when they were last installed.

`-s'
`--strip'
Strip the symbol tables from installed binary executables.

`-S suffix'
`--suffix=suffix'
Append suffix to each backup file made with `-b'. See section 2.1 Backup options.

`--target-directory=directory'
Specify the destination directory. See section 2.3 Target directory.

`-v'
`--verbose'
Print the name of each file before copying it.

`-V method'
`--version-control=method'
Change the type of backups made with `-b'. The method argument can be `none' (or `off'), `numbered' (or `t'), `existing' (or `nil'), or `never' (or `simple'). See section 2.1 Backup options.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4 mv: Move (rename) files

mv moves or renames files (or directories). Synopsis:

mv [option]... source dest
mv [option]... source... directory

If the last argument names an existing directory, mv moves each other given file into a file with the same name in that directory. Otherwise, if only two files are given, it renames the first as the second. It is an error if the last argument is not a directory and more than two files are given.

mv can move any type of file from one filesystem to another. Prior to version 4.0 of the fileutils, mv could move only regular files between filesystems. For example, now mv can move an entire directory hierarchy including special device files from one partition to another. It first uses some of the same code that's used by cp -a to copy the requested directories and files, then (assuming the copy succeeded) it removes the originals. If the copy fails, then the part that was copied to the destination partition is removed. If you were to copy three directories from one partition to another and the copy of the first directory succeeded, but the second didn't, the first would be left on the destination partion and the second and third would be left on the original partition.

If a destination file exists but is normally unwritable, standard input is a terminal, and the `-f' or `--force' option is not given, mv prompts the user for whether to replace the file. (You might own the file, or have write permission on its directory.) If the response does not begin with `y' or `Y', the file is skipped.

Warning: If you try to move a symlink that points to a directory, and you specify the symlink with a trailing slash, then mv doesn't move the symlink but instead moves the directory referenced by the symlink. See section 2.4 Trailing slashes.

The program accepts the following options. Also see 2. Common options.

`-b'
`--backup[=method]'
See section 2.1 Backup options. Make a backup of each file that would otherwise be overwritten or removed.

`-f'
`--force'
Do not prompt the user before removing an unwritable destination file.

`-i'
`--interactive'
Prompt whether to overwrite each existing destination file, regardless of its permissions. If the response does not begin with `y' or `Y', the file is skipped.

`-u'
`--update'
Do not move a nondirectory that has an existing destination with the same or newer modification time.

`-v'
`--verbose'
Print the name of each file before moving it.

`--strip-trailing-slashes'
Remove any trailing slashes from each source argument. See section 2.4 Trailing slashes.

`-S suffix'
`--suffix=suffix'
Append suffix to each backup file made with `-b'. See section 2.1 Backup options.

`--target-directory=directory'
Specify the destination directory. See section 2.3 Target directory.

`-V method'
`--version-control=method'
Change the type of backups made with `-b'. The method argument can be `none' (or `off'), `numbered' (or `t'), `existing' (or `nil'), or `never' (or `simple'). See section 2.1 Backup options.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.5 rm: Remove files or directories

rm removes each given file. By default, it does not remove directories. Synopsis:

rm [option]... [file]...

If a file is unwritable, standard input is a terminal, and the `-f' or `--force' option is not given, or the `-i' or `--interactive' option is given, rm prompts the user for whether to remove the file. If the response does not begin with `y' or `Y', the file is skipped.

The program accepts the following options. Also see 2. Common options.

`-d'
`--directory'
Attempt to remove directories with unlink instead of rmdir, and don't require a directory to be empty before trying to unlink it. This works only if you have appropriate privileges and if your operating system supports unlink for directories. Because unlinking a directory causes any files in the deleted directory to become unreferenced, it is wise to fsck the filesystem after doing this.

`-f'
`--force'
Ignore nonexistent files and never prompt the user. Ignore any previous `--interactive' (`-i') option.

`-i'
`--interactive'
Prompt whether to remove each file. If the response does not begin with `y' or `Y', the file is skipped. Ignore any previous `--force' (`-f') option.

`-r'
`-R'
`--recursive'
Remove the contents of directories recursively.

`-v'
`--verbose'
Print the name of each file before removing it.

One common question is how to remove files whose names begin with a `-'. GNU rm, like every program that uses the getopt function to parse its arguments, lets you use the `--' option to indicate that all following arguments are non-options. To remove a file called `-f' in the current directory, you could type either:

rm -- -f

or:

rm ./-f

The Unix rm program's use of a single `-' for this purpose predates the development of the getopt standard syntax.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.6 shred: Remove files more securely

shred overwrites devices or files, to help prevent even very expensive hardware from recovering the data.

Ordinarily when you remove a file (see section 6.5 rm: Remove files or directories), the data is not actually destroyed. Only the index listing where the file is stored is destroyed, and the storage is made available for reuse. There are undelete utilities that will attempt to reconstruct the index and can bring the file back if the parts were not reused.

On a busy system with a nearly-full drive, space can get reused in a few seconds. But there is no way to know for sure. If you have sensitive data, you may want to be sure that recovery is not possible by actually overwriting the file with non-sensitive data.

However, even after doing that, it is possible to take the disk back to a laboratory and use a lot of sensitive (and expensive) equipment to look for the faint "echoes" of the original data underneath the overwritten data. If the data has only been overwritten once, it's not even that hard.

The best way to remove something irretrievably is to destroy the media it's on with acid, melt it down, or the like. For cheap removable media like floppy disks, this is the preferred method. However, hard drives are expensive and hard to melt, so the shred utility tries to achieve a similar effect non-destructively.

This uses many overwrite passes, with the data patterns chosen to maximize the damage they do to the old data. While this will work on floppies, the patterns are designed for best effect on hard drives. For more details, see the source code and Peter Gutmann's paper Secure Deletion of Data from Magnetic and Solid-State Memory, from the proceedings of the Sixth USENIX Security Symposium (San Jose, California, 22--25 July, 1996). The paper is also available online http://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html.

Please note that shred relies on a very important assumption: that the filesystem overwrites data in place. This is the traditional way to do things, but many modern filesystem designs do not satisfy this assumption. Exceptions include:

  • Log-structured or journaled filesystems, such as those supplied with AIX and Solaris.

  • Filesystems that write redundant data and carry on even if some writes fail, such as RAID-based filesystems.

  • Filesystems that make snapshots, such as Network Appliance's NFS server.

  • Filesystems that cache in temporary locations, such as NFS version 3 clients.

  • Compressed filesystems.

If you are not sure how your filesystem operates, then you should assume that it does not overwrite data in place, which means that shred cannot reliably operate on regular files in your filesystem.

Generally speaking, it is more reliable to shred a device than a file, since this bypasses the problem of filesystem design mentioned above. However, even shredding devices is not always completely reliable. For example, most disks map out bad sectors invisibly to the application; if the bad sectors contain sensitive data, shred won't be able to destroy it.

shred makes no attempt to detect or report these problem, just as it makes no attempt to do anything about backups. However, since it is more reliable to shred devices than files, shred by default does not truncate or remove the output file. This default is more suitable for devices, which typically cannot be truncated and should not be removed.

shred [option]... file[...]

The program accepts the following options. Also see 2. Common options.

`-f'
`--force'
Override file permissions if necessary to allow overwriting.

`-NUMBER'
`-n NUMBER'
`--iterations=NUMBER'
By default, shred uses 25 passes of overwrite. This is enough for all of the useful overwrite patterns to be used at least once. You can reduce this to save time, or increase it if you have a lot of time to waste.

`-s BYTES'
`--size=BYTES'
Shred the first BYTES bytes of the file. The default is to shred the whole file. BYTES can be followed by a size specification like `k', `M', or `G' to specify a multiple. See section 2.2 Block size.

`-u'
`--remove'
After shredding a file, truncate it (if possible) and then remove it. If a file has multiple links, only the named links will be removed.

`-v'
`--verbose'
Display status updates as sterilization proceeds.

`-x'
`--exact'
Normally, shred rounds the file size up to the next multiple of the filesystem block size to fully erase the last block of the file. This option suppresses that behavior. Thus, by default if you shred a 10-byte file on a system with 512-byte blocks, the resulting file will be 512 bytes long. With this option, shred does not increase the size of the file.

`-z'
`--zero'
Normally, the last pass that shred writes is made up of random data. If this would be conspicuous on your hard drive (for example, because it looks like encrypted data), or you just think it's tidier, the `--zero' option adds an additional overwrite pass with all zero bits. This is in addition to the number of passes specified by the `--iterations' option.

`-'
Shred standard output.

This argument is considered an option. If the common `--' option has been used to indicate the end of options on the command line, then `-' will be interpreted as an ordinary file name.

The intended use of this is to shred a removed temporary file. For example

i=`tempfile -m 0600`
exec 3<>"$i"
rm -- "$i"
echo "Hello, world" >&3
shred - >&3
exec 3>-

Note that the shell command `shred - >file' does not shred the contents of file, since it truncates file before invoking shred. Use the command `shred file' or (if using a Bourne-compatible shell) the command `shred - 1<>file' instead.

You might use the following command to erase all trace of the file system you'd created on the floppy disk in your first drive. That command takes about 20 minutes to erase a 1.44MB floppy.

shred --verbose /dev/fd0

Similarly, to erase all data on a selected partition of your hard disk, you could give a command like this:

shred --verbose /dev/sda5

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. Special file types

This chapter describes commands which create special types of files (and rmdir, which removes directories, one special file type).

Although Unix-like operating systems have markedly fewer special file types than others, not everything can be treated only as the undifferentiated byte stream of normal files. For example, when a file is created or removed, the system must record this information, which it does in a directory---a special type of file. Although you can read directories as normal files, if you're curious, in order for the system to do its job it must impose a structure, a certain order, on the bytes of the file. Thus it is a "special" type of file.

Besides directories, other special file types include named pipes (FIFOs), symbolic links, sockets, and so-called special files.

7.1 ln: Make links between files | Make links between files.
7.2 mkdir: Make directories | Make directories.
7.3 mkfifo: Make FIFOs (named pipes) | Make FIFOs (named pipes).
7.4 mknod: Make block or character special files | Make block or character special files.
7.5 rmdir: Remove empty directories | Remove empty directories.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1 ln: Make links between files

ln makes links between files. By default, it makes hard links; with the `-s' option, it makes symbolic (or soft) links. Synopses:

ln [option]... target [linkname]
ln [option]... target... directory

  • If the last argument names an existing directory, ln creates a link to each target file in that directory, using the targets' names. (But see the description of the `--no-dereference' option below.)

  • If two filenames are given, ln creates a link from the second to the first.

  • If one target is given, ln creates a link to that file in the current directory.

  • It is an error if the last argument is not a directory and more than two files are given. Without `-f' or `-i' (see below), ln will not remove an existing file. Use the `--backup' option to make ln rename existing files.

A hard link is another name for an existing file; the link and the original are indistinguishable. Technically speaking, they share the same inode, and the inode contains all the information about a file--indeed, it is not incorrect to say that the inode is the file. On all existing implementations, you cannot make a hard link to a directory, and hard links cannot cross filesystem boundaries. (These restrictions are not mandated by POSIX, however.)

Symbolic links (symlinks for short), on the other hand, are a special file type (which not all kernels support: System V release 3 (and older) systems lack symlinks) in which the link file actually refers to a different file, by name. When most operations (opening, reading, writing, and so on) are passed the symbolic link file, the kernel automatically dereferences the link and operates on the target of the link. But some operations (e.g., removing) work on the link file itself, rather than on its target. See section `Symbolic Links' in The GNU C Library Reference Manual.

The program accepts the following options. Also see 2. Common options.

`-b'
`--backup[=method]'
See section 2.1 Backup options. Make a backup of each file that would otherwise be overwritten or removed.

`-d'
`-F'
`--directory'
Allow the super-user to make hard links to directories.

`-f'
`--force'
Remove existing destination files.

`-i'
`--interactive'
Prompt whether to remove existing destination files.

`-n'
`--no-dereference'
When given an explicit destination that is a symlink to a directory, treat that destination as if it were a normal file.

When the destination is an actual directory (not a symlink to one), there is no ambiguity. The link is created in that directory. But when the specified destination is a symlink to a directory, there are two ways to treat the user's request. ln can treat the destination just as it would a normal directory and create the link in it. On the other hand, the destination can be viewed as a non-directory--as the symlink itself. In that case, ln must delete or backup that symlink before creating the new link. The default is to treat a destination that is a symlink to a directory just like a directory.

`-s'
`--symbolic'
Make symbolic links instead of hard links. This option merely produces an error message on systems that do not support symbolic links.

`-S suffix'
`--suffix=suffix'
Append suffix to each backup file made with `-b'. See section 2.1 Backup options.

`--target-directory=directory'
Specify the destination directory. See section 2.3 Target directory.

`-v'
`--verbose'
Print the name of each file before linking it.

`-V method'
`--version-control=method'
Change the type of backups made with `-b'. The method argument can be `none' (or `off'), `numbered' (or `t'), `existing' (or `nil'), or `never' (or `simple'). See section 2.1 Backup options.

Examples:

ln -s /some/name  # creates link ./name pointing to /some/name
ln -s /some/name myname  # creates link ./myname pointing to /some/name
ln -s a b ..      # creates links ../a and ../b pointing to ./a and ./b

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2 mkdir: Make directories

mkdir creates directories with the specified names. Synopsis:

mkdir [option]... name...

If a name is an existing file but not a directory, mkdir prints a warning message on stderr and will exit with a status of 1 after processing any remaining names. The same is done when a name is an existing directory and the -p option is not given. If a name is an existing directory and the -p option is given, mkdir will ignore it. That is, mkdir will not print a warning, raise an error, or change the mode of the directory (even if the -m option is given), and will move on to processing any remaining names.

The program accepts the following options. Also see 2. Common options.

`-m mode'
`--mode=mode'
Set the mode of created directories to mode, which is symbolic as in chmod and uses `a=rwx' (read, write and execute allowed for everyone) minus the bits set in the umask for the point of the departure. See section 3. File permissions.

`-p'
`--parents'
Make any missing parent directories for each argument. The mode for parent directories is set to the umask modified by `u+wx'. Ignore arguments corresponding to existing directories.

`-v'
`--verbose'
Print a message for each created directory. This is most useful with `--parents'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3 mkfifo: Make FIFOs (named pipes)

mkfifo creates FIFOs (also called named pipes) with the specified names. Synopsis:

mkfifo [option] name...

A FIFO is a special file type that permits independent processes to communicate. One process opens the FIFO file for writing, and another for reading, after which data can flow as with the usual anonymous pipe in shells or elsewhere.

The program accepts the following option. Also see 2. Common options.

`-m mode'
`--mode=mode'
Set the mode of created FIFOs to mode, which is symbolic as in chmod and uses `a=rw' (read and write allowed for everyone) minus the bits set in the umask for the point of departure. See section 3. File permissions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4 mknod: Make block or character special files

mknod creates a FIFO, character special file, or block special file with the specified name. Synopsis:

mknod [option]... name type [major minor]

Unlike the phrase "special file type" above, the term special file has a technical meaning on Unix: something that can generate or receive data. Usually this corresponds to a physical piece of hardware, e.g., a printer or a disk. (These files are typically created at system-configuration time.) The mknod command is what creates files of this type. Such devices can be read either a character at a time or a "block" (many characters) at a time, hence we say there are block special files and character special files.

The arguments after name specify the type of file to make:

`p'
for a FIFO

`b'
for a block special file

`c'
for a character special file

When making a block or character special file, the major and minor device numbers must be given after the file type.

The program accepts the following option. Also see 2. Common options.

`-m mode'
`--mode=mode'
Set the mode of created files to mode, which is symbolic as in chmod and uses `a=rw' minus the bits set in the umask as the point of departure. See section 3. File permissions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5 rmdir: Remove empty directories

rmdir removes empty directories. Synopsis:

rmdir [option]... directory...

If any directory argument does not refer to an existing empty directory, it is an error.

The program accepts the following option. Also see 2. Common options.

`--ignore-fail-on-non-empty'
Ignore each failure to remove a directory that is solely because the directory is non-empty.

`-p'
`--parents'
Remove directory, then try to remove each component of directory. So, for example, `rmdir -p a/b/c' is similar to `rmdir a/b/c a/b a'. As such, it fails if any of those directories turns out not to be empty. Use the `--ignore-fail-on-non-empty' option to make it so such a failure does not evoke a diagnostic and does not cause rmdir to exit unsuccessfully.

`-v'
`--verbose'
Give a diagnostic for each successful removal. directory is removed.

See section 6.5 rm: Remove files or directories, for how to remove non-empty directories (recursively).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. Changing file attributes

A file is not merely its contents, a name, and a file type (see section 7. Special file types). A file also has an owner (a userid), a group (a group id), permissions (what the owner can do with the file, what people in the group can do, and what everyone else can do), various timestamps, and other information. Collectively, we call these a file's attributes.

These commands change file attributes.

8.1 chown: Change file owner and group | Change file owners and groups.
8.2 chgrp: Change group ownership | Change file groups.
8.3 chmod: Change access permissions | Change access permissions.
8.4 touch: Change file timestamps | Change file timestamps.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1 chown: Change file owner and group

chown changes the user and/or group ownership of each given file to new-owner or to the user and group of an existing reference file. Synopsis:

chown [option]... {new-owner | --reference=ref_file} file...

If used, new-owner specifies the new owner and/or group as follows (with no embedded white space):

[owner] [ [:] [group] ]

Specifically:

owner
If only an owner (a user name or numeric user id) is given, that user is made the owner of each given file, and the files' group is not changed.

owner`:'group
If the owner is followed by a colon and a group (a group name or numeric group id), with no spaces between them, the group ownership of the files is changed as well (to group).

owner`:'
If a colon but no group name follows owner, that user is made the owner of the files and the group of the files is changed to owner's login group.

`:'group
If the colon and following group are given, but the owner is omitted, only the group of the files is changed; in this case, chown performs the same function as chgrp.

You may use `.' in place of the `:' separator. This is a GNU extension for compatibility with older scripts. New scripts should avoid the use of `.' because GNU chown may fail if owner contains `.' characters.

The program accepts the following options. Also see 2. Common options.

`-c'
`--changes'
Verbosely describe the action for each file whose ownership actually changes.

`-f'
`--silent'
`--quiet'
Do not print error messages about files whose ownership cannot be changed.

`--from=old-owner'
Change a file's ownership only if it has current attributes specified by old-owner. old-owner has the same form as new-owner described above. This option is useful primarily from a security standpoint in that it narrows considerably the window of potential abuse. For example, to reflect a UID numbering change for one user's files without an option like this, root might run

find / -owner OLDUSER -print0 | xargs -0 chown NEWUSER

But that is dangerous because the interval between when the find tests the existing file's owner and when the chown is actually run may be quite large. One way to narrow the gap would be to invoke chown for each file as it is found:

find / -owner OLDUSER -exec chown NEWUSER {} \;

But that is very slow if there are many affected files. With this option, it is safer (the gap is narrower still) though still not perfect:

chown -R --from=OLDUSER NEWUSER /

`--dereference'
Do not act on symbolic links themselves but rather on what they point to.

`-h'
`--no-dereference'
Act on symbolic links themselves instead of what they point to. This is the default. This mode relies on the lchown system call. On systems that do not provide the lchown system call, chown fails when a file specified on the command line is a symbolic link. By default, no diagnostic is issued for symbolic links encountered during a recursive traversal, but see `--verbose'.

`--reference=ref_file'
Change the user and group of each file to be the same as those of ref_file. If ref_file is a symbolic link, do not use the user and group of the symbolic link, but rather those of the file it refers to.

`-v'
`--verbose'
Output a diagnostic for every file processed. If a symbolic link is encountered during a recursive traversal on a system without the lchown system call, and `--no-dereference' is in effect, then issue a diagnostic saying neither the symbolic link nor its referent is being changed.

`-R'
`--recursive'
Recursively change ownership of directories and their contents.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2 chgrp: Change group ownership

chgrp changes the group ownership of each given file to group (which can be either a group name or a numeric group id) or to the group of an existing reference file. Synopsis:

chgrp [option]... {group | --reference=ref_file} file...

The program accepts the following options. Also see 2. Common options.

`-c'
`--changes'
Verbosely describe the action for each file whose group actually changes.

`-f'
`--silent'
`--quiet'
Do not print error messages about files whose group cannot be changed.

`--dereference'
Do not act on symbolic links themselves but rather on what they point to.

`-h'
`--no-dereference'
Act on symbolic links themselves instead of what they point to. This is the default. This mode relies on the lchown system call. On systems that do not provide the lchown system call, chgrp fails when a file specified on the command line is a symbolic link. By default, no diagnostic is issued for symbolic links encountered during a recursive traversal, but see `--verbose'.

`--reference=ref_file'
Change the group of each file to be the same as that of ref_file. If ref_file is a symbolic link, do not use the group of the symbolic link, but rather that of the file it refers to.

`-v'
`--verbose'
Output a diagnostic for every file processed. If a symbolic link is encountered during a recursive traversal on a system without the lchown system call, and `--no-dereference' is in effect, then issue a diagnostic saying neither the symbolic link nor its referent is being changed.

`-R'
`--recursive'
Recursively change the group ownership of directories and their contents.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.3 chmod: Change access permissions

chmod changes the access permissions of the named files. Synopsis:

chmod [option]... {mode | --reference=ref_file} file...

chmod never changes the permissions of symbolic links, since the chmod system call cannot change their permissions. This is not a problem since the permissions of symbolic links are never used. However, for each symbolic link listed on the command line, chmod changes the permissions of the pointed-to file. In contrast, chmod ignores symbolic links encountered during recursive directory traversals.

If used, mode specifies the new permissions. For details, see the section on 3. File permissions.

The program accepts the following options. Also see 2. Common options.

`-c'
`--changes'
Verbosely describe the action for each file whose permissions actually changes.

`-f'
`--silent'
`--quiet'
Do not print error messages about files whose permissions cannot be changed.

`-v'
`--verbose'
Verbosely describe the action or non-action taken for every file.

`--reference=ref_file'
Change the mode of each file to be the same as that of ref_file. See section 3. File permissions. If ref_file is a symbolic link, do not use the mode of the symbolic link, but rather that of the file it refers to.

`-R'
`--recursive'
Recursively change permissions of directories and their contents.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.4 touch: Change file timestamps

touch changes the access and/or modification times of the specified files. Synopsis:

touch [option]... file...

If the first file would be a valid argument to the `-t' option and no timestamp is given with any of the `-d', `-r', or `-t' options and the `--' argument is not given, that argument is interpreted as the time for the other files instead of as a file name. Warning: this usage is obsolescent, and future versions of POSIX will require that support for it be withdrawn. Use `-t' instead.

Any file that does not exist is created empty.

If changing both the access and modification times to the current time, touch can change the timestamps for files that the user running it does not own but has write permission for. Otherwise, the user must own the files.

Although touch provides options for changing two of the times -- the times of last access and modification -- of a file, there is actually a third one as well: the inode change time. This is often referred to as a file's ctime. The inode change time represents the time when the file's meta-information last changed. One common example of this is when the permissions of a file change. Changing the permissions doesn't access the file, so the atime doesn't change, nor does it modify the file, so the mtime doesn't change. Yet, something about the file itself has changed, and this must be noted somewhere. This is the job of the ctime field. This is necessary, so that, for example, a backup program can make a fresh copy of the file, including the new permissions value. Another operation that modifies a file's ctime without affecting the others is renaming. In any case, it is not possible, in normal operations, for a user to change the ctime field to a user-specified value.

The program accepts the following options. Also see 2. Common options.

`-a'
`--time=atime'
`--time=access'
`--time=use'
Change the access time only.

`-c'
`--no-create'
Do not create files that do not exist.

`-d'
`--date=time'
Use time instead of the current time. It can contain month names, timezones, `am' and `pm', etc. See section 4. Date input formats.

`-f'
Ignored; for compatibility with BSD versions of touch.

`-m'
`--time=mtime'
`--time=modify'
Change the modification time only.

`-r file'
`--reference=file'
Use the times of the reference file instead of the current time.

`-t [[CC]YY]MMDDhhmm[.ss]'
Use the argument (optional four-digit or two-digit years, months, days, hours, minutes, optional seconds) instead of the current time. If the year is specified with only two digits, then CC is 20 for years in the range 0 ... 68, and 19 for years in 69 ... 99. If no digits of the year are specified, the argument is interpreted as a date in the current year.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. Disk usage

No disk can hold an infinite amount of data. These commands report on how much disk storage is in use or available. (This has nothing much to do with how much main memory, i.e., RAM, a program is using when it runs; for that, you want ps or pstat or swap or some such command.)

9.1 df: Report filesystem disk space usage | Report filesystem disk space usage.
9.2 du: Estimate file space usage | Estimate file space usage.
9.3 sync: Synchronize data on disk with memory | Synchronize memory and disk.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1 df: Report filesystem disk space usage

df reports the amount of disk space used and available on filesystems. Synopsis:

df [option]... [file]...

With no arguments, df reports the space used and available on all currently mounted filesystems (of all types). Otherwise, df reports on the filesystem containing each argument file.

Normally the disk space is printed in units of 1024 bytes, but this can be overridden (see section 2.2 Block size).

If an argument file is a disk device file containing a mounted filesystem, df shows the space available on that filesystem rather than on the filesystem containing the device node (i.e., the root filesystem). GNU df does not attempt to determine the disk usage on unmounted filesystems, because on most kinds of systems doing so requires extremely nonportable intimate knowledge of filesystem structures.

The program accepts the following options. Also see 2. Common options.

`-a'
`--all'
Include in the listing filesystems that have a size of 0 blocks, which are omitted by default. Such filesystems are typically special-purpose pseudo-filesystems, such as automounter entries. Also, filesystems of type "ignore" or "auto", supported by some operating systems, are only included if this option is specified.

`-h'
`--human-readable'
Append a size letter such as `M' for megabytes to each size. Powers of 1024 are used, not 1000; `M' stands for 1,048,576 bytes. Use the `-H' or `--si' option if you prefer powers of 1000.

`-H'
`--si'
Append a size letter such as `M' for megabytes to each size. (SI is the International System of Units, which defines these letters as prefixes.) Powers of 1000 are used, not 1024; `M' stands for 1,000,000 bytes. Use the `-h' or `--human-readable' option if you prefer powers of 1024.

`-i'
`--inodes'
List inode usage information instead of block usage. An inode (short for index node) contains information about a file such as its owner, permissions, timestamps, and location on the disk.

`-k'
`--kilobytes'
Print sizes in 1024-byte blocks, overriding the default block size (see section 2.2 Block size).

`-l'
`--local'
Limit the listing to local filesystems. By default, remote filesystems are also listed.

`-m'
`--megabytes'
Print sizes in megabyte (that is, 1,048,576-byte) blocks.

`--no-sync'
Do not invoke the sync system call before getting any usage data. This may make df run significantly faster on systems with many disks, but on some systems (notably SunOS) the results may be slightly out of date. This is the default.

`-P'
`--portability'
Use the POSIX output format. This is like the default format except for the following:

  1. The information about each filesystem is always printed on exactly one line; a mount device is never put on a line by itself. This means that if the mount device name is more than 20 characters long (e.g., for some network mounts), the columns are misaligned.

  2. Non-integer values are rounded up, instead of being rounded down or rounded to the nearest integer.

  3. The labels in the header output line are changed to conform to POSIX.

`--sync'
Invoke the sync system call before getting any usage data. On some systems (notably SunOS), doing this yields more up to date results, but in general this option makes df much slower, especially when there are many or very busy filesystems.

`-t fstype'
`--type=fstype'
Limit the listing to filesystems of type fstype. Multiple filesystem types can be specified by giving multiple `-t' options. By default, nothing is omitted.

`-T'
`--print-type'
Print each filesystem's type. The types printed here are the same ones you can include or exclude with `-t' and `-x'. The particular types printed are whatever is supported by the system. Here are some of the common names (this list is certainly not exhaustive):

`nfs'
An NFS filesystem, i.e., one mounted over a network from another machine. This is the one type name which seems to be used uniformly by all systems.

`4.2, ufs, efs...'
A filesystem on a locally-mounted hard disk. (The system might even support more than one type here; Linux does.)

`hsfs, cdfs'
A filesystem on a CD-ROM drive. HP-UX uses `cdfs', most other systems use `hsfs' (`hs' for "High Sierra").

`pcfs'
An MS-DOS filesystem, usually on a diskette.

`-x fstype'
`--exclude-type=fstype'
Limit the listing to filesystems not of type fstype. Multiple filesystem types can be eliminated by giving multiple `-x' options. By default, no filesystem types are omitted.

`-v'
Ignored; for compatibility with System V versions of df.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.2 du: Estimate file space usage

du reports the amount of disk space used by the specified files and for each subdirectory (of directory arguments). Synopsis:

du [option]... [file]...

With no arguments, du reports the disk space for the current directory. Normally the disk space is printed in units of 1024 bytes, but this can be overridden (see section 2.2 Block size).

The program accepts the following options. Also see 2. Common options.

`-a'
`--all'
Show counts for all files, not just directories.

`-b'
`--bytes'
Print sizes in bytes, overriding the default block size (see section 2.2 Block size).

`-c'
`--total'
Print a grand total of all arguments after all arguments have been processed. This can be used to find out the total disk usage of a given set of files or directories.

`-D'
`--dereference-args'
Dereference symbolic links that are command line arguments. Does not affect other symbolic links. This is helpful for finding out the disk usage of directories, such as `/usr/tmp', which are often symbolic links.

`-h'
`--human-readable'
Append a size letter such as `M' for megabytes to each size. Powers of 1024 are used, not 1000; `M' stands for 1,048,576 bytes. Use the `-H' or `--si' option if you prefer powers of 1000.

`-H'
`--si'
Append a size letter such as `M' for megabytes to each size. (SI is the International System of Units, which defines these letters as prefixes.) Powers of 1000 are used, not 1024; `M' stands for 1,000,000 bytes. Use the `-h' or `--human-readable' option if you prefer powers of 1024.

`-k'
`--kilobytes'
Print sizes in 1024-byte blocks, overriding the default block size (see section 2.2 Block size).

`-l'
`--count-links'
Count the size of all files, even if they have appeared already (as a hard link).

`-L'
`--dereference'
Dereference symbolic links (show the disk space used by the file or directory that the link points to instead of the space used by the link).

`--max-depth=DEPTH'
Show the total for each directory (and file if --all) that is at most MAX_DEPTH levels down from the root of the hierarchy. The root is at level 0, so du --max-depth=0 is equivalent to du -s.

`-m'
`--megabytes'
Print sizes in megabyte (that is, 1,048,576-byte) blocks.

`-s'
`--summarize'
Display only a total for each argument.

`-S'
`--separate-dirs'
Report the size of each directory separately, not including the sizes of subdirectories.

`-x'
`--one-file-system'
Skip directories that are on different filesystems from the one that the argument being processed is on.

`--exclude=PAT'
When recursing, skip subdirectories or files matching PAT. For example, du --exclude='*.o' excludes files whose names end in `.o'.

`-X FILE'
`--exclude-from=FILE'
Like `--exclude', except take the patterns to exclude from FILE, one per line. If FILE is `-', take the patterns from standard input.

On BSD systems, du reports sizes that are half the correct values for files that are NFS-mounted from HP-UX systems. On HP-UX systems, it reports sizes that are twice the correct values for files that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX; it also affects the HP-UX du program.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3 sync: Synchronize data on disk with memory

sync writes any data buffered in memory out to disk. This can include (but is not limited to) modified superblocks, modified inodes, and delayed reads and writes. This must be implemented by the kernel; The sync program does nothing but exercise the sync system call.

The kernel keeps data in memory to avoid doing (relatively slow) disk reads and writes. This improves performance, but if the computer crashes, data may be lost or the filesystem corrupted as a result. sync ensures everything in memory is written to disk.

Any arguments are ignored, except for a lone `--help' or `--version' (see section 2. Common options).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Index

Jump to: - 4
A B C D E F G H I K L M N O P Q R S T U V W Y

 | Index Entry | Section
- |  |
 | - | 6.6 shred: Remove files more securely
 | - and Unix rm | 6.5 rm: Remove files or directories
 | `-', removing files beginning with | 6.5 rm: Remove files or directories
 | --all | 5.1.1 Which files are listed
 | --all | 9.1 df: Report filesystem disk space usage
 | --all | 9.2 du: Estimate file space usage
 | --almost-all | 5.1.1 Which files are listed
 | --archive | 6.1 cp: Copy files and directories
 | --backup | 2.1 Backup options
 | --backup | 6.1 cp: Copy files and directories
 | --backup | 6.3 install: Copy files and set attributes
 | --backup | 6.4 mv: Move (rename) files
 | --backup | 7.1 ln: Make links between files
 | --block-size=size | 2.2 Block size
 | --bourne-shell | 5.4 dircolors: Color setup for ls
 | --bytes | 9.2 du: Estimate file space usage
 | --c-shell | 5.4 dircolors: Color setup for ls
 | --changes | 8.1 chown: Change file owner and group
 | --changes | 8.2 chgrp: Change group ownership
 | --changes | 8.3 chmod: Change access permissions
 | --classify | 5.1.5 General output formatting
 | --color | 5.1.5 General output formatting
 | --count-links | 9.2 du: Estimate file space usage
 | --csh | 5.4 dircolors: Color setup for ls
 | --date | 8.4 touch: Change file timestamps
 | --dereference | 5.1.1 Which files are listed
 | --dereference | 6.1 cp: Copy files and directories
 | --dereference | 8.1 chown: Change file owner and group
 | --dereference | 8.2 chgrp: Change group ownership
 | --dereference | 9.2 du: Estimate file space usage
 | --dereference-args | 9.2 du: Estimate file space usage
 | --directory | 5.1.1 Which files are listed
 | --directory | 6.3 install: Copy files and set attributes
 | --directory | 6.5 rm: Remove files or directories
 | --directory | 7.1 ln: Make links between files
 | --dired | 5.1.2 What information is listed
 | --escape | 5.1.6 Formatting the file names
 | --exact | 6.6 shred: Remove files more securely
 | --exclude-from=FILE | 9.2 du: Estimate file space usage
 | --exclude-type | 9.1 df: Report filesystem disk space usage
 | --exclude=PAT | 9.2 du: Estimate file space usage
 | --file-type | 5.1.5 General output formatting
 | --force | 6.1 cp: Copy files and directories
 | --force | 6.4 mv: Move (rename) files
 | --force | 6.5 rm: Remove files or directories
 | --force | 6.6 shred: Remove files more securely
 | --force | 7.1 ln: Make links between files
 | --format | 5.1.2 What information is listed
 | --format | 5.1.5 General output formatting
 | --format | 5.1.5 General output formatting
 | --format | 5.1.5 General output formatting
 | --format | 5.1.5 General output formatting
 | --from | 8.1 chown: Change file owner and group
 | --full-time | 5.1.5 General output formatting
 | --group | 6.3 install: Copy files and set attributes
 | --help | 2. Common options
 | --hide-control-chars | 5.1.6 Formatting the file names
 | --human-readable | 2.2 Block size
 | --human-readable | 5.1.2 What information is listed
 | --human-readable | 9.1 df: Report filesystem disk space usage
 | --human-readable | 9.2 du: Estimate file space usage
 | --ignore-backups | 5.1.1 Which files are listed
 | --ignore-fail-on-non-empty | 7.5 rmdir: Remove empty directories
 | --ignore=pattern | 5.1.1 Which files are listed
 | --indicator-style | 5.1.5 General output formatting
 | --indicator-style | 5.1.5 General output formatting
 | --indicator-style | 5.1.5 General output formatting
 | --inode | 5.1.2 What information is listed
 | --inodes | 9.1 df: Report filesystem disk space usage
 | --interactive | 6.1 cp: Copy files and directories
 | --interactive | 6.4 mv: Move (rename) files
 | --interactive | 6.5 rm: Remove files or directories
 | --interactive | 7.1 ln: Make links between files
 | --iterations=NUMBER | 6.6 shred: Remove files more securely
 | --kilobytes | 2.2 Block size
 | --kilobytes | 5.1.5 General output formatting
 | --kilobytes | 9.1 df: Report filesystem disk space usage
 | --kilobytes | 9.2 du: Estimate file space usage
 | --link | 6.1 cp: Copy files and directories
 | --literal | 5.1.6 Formatting the file names
 | --local | 9.1 df: Report filesystem disk space usage
 | --max-depth=DEPTH | 9.2 du: Estimate file space usage
 | --megabytes | 9.1 df: Report filesystem disk space usage
 | --megabytes | 9.2 du: Estimate file space usage
 | --mode | 6.3 install: Copy files and set attributes
 | --mode | 7.2 mkdir: Make directories
 | --mode | 7.3 mkfifo: Make FIFOs (named pipes)
 | --mode | 7.4 mknod: Make block or character special files
 | --no-create | 8.4 touch: Change file timestamps
 | --no-dereference | 6.1 cp: Copy files and directories
 | --no-dereference | 7.1 ln: Make links between files
 | --no-dereference | 8.1 chown: Change file owner and group
 | --no-dereference | 8.2 chgrp: Change group ownership
 | --no-group | 5.1.2 What information is listed
 | --no-sync | 9.1 df: Report filesystem disk space usage
 | --numeric-uid-gid | 5.1.5 General output formatting
 | --one-file-system | 6.1 cp: Copy files and directories
 | --one-file-system | 9.2 du: Estimate file space usage
 | --owner | 6.3 install: Copy files and set attributes
 | --parents | 6.1 cp: Copy files and directories
 | --parents | 7.2 mkdir: Make directories
 | --parents | 7.5 rmdir: Remove empty directories
 | --portability | 9.1 df: Report filesystem disk space usage
 | --preserve | 6.1 cp: Copy files and directories
 | --preserve-timestamps | 6.3 install: Copy files and set attributes
 | --print-database | 5.4 dircolors: Color setup for ls
 | --print-type | 9.1 df: Report filesystem disk space usage
 | --quiet | 8.1 chown: Change file owner and group
 | --quiet | 8.2 chgrp: Change group ownership
 | --quiet | 8.3 chmod: Change access permissions
 | --quote-name | 5.1.6 Formatting the file names
 | --quoting-style | 5.1.6 Formatting the file names
 | --quoting-style | 5.1.6 Formatting the file names
 | --quoting-style | 5.1.6 Formatting the file names
 | --recursive | 5.1.1 Which files are listed
 | --recursive | 6.1 cp: Copy files and directories
 | --recursive | 6.5 rm: Remove files or directories
 | --recursive | 8.1 chown: Change file owner and group
 | --recursive | 8.2 chgrp: Change group ownership
 | --recursive | 8.3 chmod: Change access permissions
 | --reference | 8.1 chown: Change file owner and group
 | --reference | 8.2 chgrp: Change group ownership
 | --reference | 8.3 chmod: Change access permissions
 | --reference | 8.4 touch: Change file timestamps
 | --remove | 6.6 shred: Remove files more securely
 | --remove-destination | 6.1 cp: Copy files and directories
 | --reverse | 5.1.3 Sorting the output
 | --separate-dirs | 9.2 du: Estimate file space usage
 | --sh | 5.4 dircolors: Color setup for ls
 | --show-control-chars | 5.1.6 Formatting the file names
 | --si | 2.2 Block size
 | --si | 5.1.2 What information is listed
 | --si | 9.1 df: Report filesystem disk space usage
 | --si | 9.2 du: Estimate file space usage
 | --silent | 8.1 chown: Change file owner and group
 | --silent | 8.2 chgrp: Change group ownership
 | --silent | 8.3 chmod: Change access permissions
 | --size | 5.1.2 What information is listed
 | --size=BYTES | 6.6 shred: Remove files more securely
 | --sort | 5.1.3 Sorting the output
 | --sort | 5.1.3 Sorting the output
 | --sort | 5.1.3 Sorting the output
 | --sort | 5.1.3 Sorting the output
 | --sort | 5.1.3 Sorting the output
 | --sparse=when | 6.1 cp: Copy files and directories
 | --strip | 6.3 install: Copy files and set attributes
 | --strip-trailing-slashes | 6.1 cp: Copy files and directories
 | --strip-trailing-slashes | 6.4 mv: Move (rename) files
 | --suffix | 2.1 Backup options
 | --suffix | 6.1 cp: Copy files and directories
 | --suffix | 6.3 install: Copy files and set attributes
 | --suffix | 6.4 mv: Move (rename) files
 | --suffix | 7.1 ln: Make links between files
 | --summarize | 9.2 du: Estimate file space usage
 | --symbolic | 7.1 ln: Make links between files
 | --symbolic-link | 6.1 cp: Copy files and directories
 | --sync | 9.1 df: Report filesystem disk space usage
 | --tabsize | 5.1.5 General output formatting
 | --target-directory | 2.3 Target directory
 | --target-directory | 6.1 cp: Copy files and directories
 | --target-directory | 6.3 install: Copy files and set attributes
 | --target-directory | 6.4 mv: Move (rename) files
 | --target-directory | 7.1 ln: Make links between files
 | --time | 5.1.3 Sorting the output
 | --time | 5.1.3 Sorting the output
 | --time | 8.4 touch: Change file timestamps
 | --time | 8.4 touch: Change file timestamps
 | --total | 9.2 du: Estimate file space usage
 | --type | 9.1 df: Report filesystem disk space usage
 | --update | 6.4 mv: Move (rename) files
 | --verbose | 6.1 cp: Copy files and directories
 | --verbose | 6.3 install: Copy files and set attributes
 | --verbose | 6.4 mv: Move (rename) files
 | --verbose | 6.5 rm: Remove files or directories
 | --verbose | 6.6 shred: Remove files more securely
 | --verbose | 7.1 ln: Make links between files
 | --verbose | 7.2 mkdir: Make directories
 | --verbose | 7.5 rmdir: Remove empty directories
 | --verbose | 8.1 chown: Change file owner and group
 | --verbose | 8.2 chgrp: Change group ownership
 | --verbose | 8.3 chmod: Change access permissions
 | --version | 2. Common options
 | --version-control | 2.1 Backup options
 | --version-control | 6.1 cp: Copy files and directories
 | --version-control | 6.3 install: Copy files and set attributes
 | --version-control | 6.4 mv: Move (rename) files
 | --version-control | 7.1 ln: Make links between files
 | --width | 5.1.5 General output formatting
 | --zero | 6.6 shred: Remove files more securely
 | -1 | 5.1.5 General output formatting
 | -a | 5.1.1 Which files are listed
 | -A | 5.1.1 Which files are listed
 | -a | 6.1 cp: Copy files and directories
 | -a | 8.4 touch: Change file timestamps
 | -a | 9.1 df: Report filesystem disk space usage
 | -a | 9.2 du: Estimate file space usage
 | -B | 5.1.1 Which files are listed
 | -b | 2.1 Backup options
 | -b | 5.1.6 Formatting the file names
 | -b | 5.4 dircolors: Color setup for ls
 | -b | 6.1 cp: Copy files and directories
 | -b | 6.3 install: Copy files and set attributes
 | -b | 6.4 mv: Move (rename) files
 | -b | 7.1 ln: Make links between files
 | -b | 9.2 du: Estimate file space usage
 | -C | 5.1.5 General output formatting
 | -c | 5.1.3 Sorting the output
 | -c | 5.4 dircolors: Color setup for ls
 | -c | 6.3 install: Copy files and set attributes
 | -c | 8.1 chown: Change file owner and group
 | -c | 8.2 chgrp: Change group ownership
 | -c | 8.3 chmod: Change access permissions
 | -c | 8.4 touch: Change file timestamps
 | -c | 9.2 du: Estimate file space usage
 | -d | 5.1.1 Which files are listed
 | -D | 5.1.2 What information is listed
 | -D | 9.2 du: Estimate file space usage
 | -d | 6.1 cp: Copy files and directories
 | -d | 6.3 install: Copy files and set attributes
 | -d | 6.5 rm: Remove files or directories
 | -d | 7.1 ln: Make links between files
 | -d | 8.4 touch: Change file timestamps
 | -f | 5.1.3 Sorting the output
 | -F | 5.1.5 General output formatting
 | -F | 7.1 ln: Make links between files
 | -f | 6.1 cp: Copy files and directories
 | -f | 6.4 mv: Move (rename) files
 | -f | 6.5 rm: Remove files or directories
 | -f | 6.6 shred: Remove files more securely
 | -f | 7.1 ln: Make links between files
 | -f | 8.1 chown: Change file owner and group
 | -f | 8.2 chgrp: Change group ownership
 | -f | 8.3 chmod: Change access permissions
 | -f | 8.4 touch: Change file timestamps
 | -G | 5.1.2 What information is listed
 | -g | 6.3 install: Copy files and set attributes
 | -g (ignored) | 5.1 ls: List directory contents
 | -H | 5.1.2 What information is listed
 | -h | 2.2 Block size
 | -h | 5.1.2 What information is listed
 | -H | 6.1 cp: Copy files and directories
 | -h | 8.1 chown: Change file owner and group
 | -H | 9.1 df: Report filesystem disk space usage
 | -h | 8.2 chgrp: Change group ownership
 | -H | 9.2 du: Estimate file space usage
 | -h | 9.1 df: Report filesystem disk space usage
 | -h | 9.2 du: Estimate file space usage
 | -I | 5.1.1 Which files are listed
 | -i | 5.1.2 What information is listed
 | -i | 6.1 cp: Copy files and directories
 | -i | 6.4 mv: Move (rename) files
 | -i | 6.5 rm: Remove files or directories
 | -i | 7.1 ln: Make links between files
 | -i | 9.1 df: Report filesystem disk space usage
 | -k | 2.2 Block size
 | -k | 5.1.5 General output formatting
 | -k | 9.1 df: Report filesystem disk space usage
 | -k | 9.2 du: Estimate file space usage
 | -L | 5.1.1 Which files are listed
 | -l | 5.1.2 What information is listed
 | -L | 6.1 cp: Copy files and directories
 | -l | 6.1 cp: Copy files and directories
 | -L | 9.2 du: Estimate file space usage
 | -l | 9.1 df: Report filesystem disk space usage
 | -l | 9.2 du: Estimate file space usage
 | -m | 5.1.5 General output formatting
 | -m | 6.3 install: Copy files and set attributes
 | -m | 7.2 mkdir: Make directories
 | -m | 7.3 mkfifo: Make FIFOs (named pipes)
 | -m | 7.4 mknod: Make block or character special files
 | -m | 8.4 touch: Change file timestamps
 | -m | 9.1 df: Report filesystem disk space usage
 | -m | 9.2 du: Estimate file space usage
 | -n | 5.1.5 General output formatting
 | -N | 5.1.6 Formatting the file names
 | -n | 7.1 ln: Make links between files
 | -n NUMBER | 6.6 shred: Remove files more securely
 | -o | 5.1.2 What information is listed
 | -o | 6.3 install: Copy files and set attributes
 | -P | 6.1 cp: Copy files and directories
 | -p | 5.4 dircolors: Color setup for ls
 | -p | 6.1 cp: Copy files and directories
 | -P | 9.1 df: Report filesystem disk space usage
 | -p | 6.3 install: Copy files and set attributes
 | -p | 7.2 mkdir: Make directories
 | -p | 7.5 rmdir: Remove empty directories
 | -Q | 5.1.6 Formatting the file names
 | -q | 5.1.6 Formatting the file names
 | -r | 5.1.3 Sorting the output
 | -R | 5.1.1 Which files are listed
 | -r | 6.5 rm: Remove files or directories
 | -R | 6.1 cp: Copy files and directories
 | -R | 6.5 rm: Remove files or directories
 | -r | 8.4 touch: Change file timestamps
 | -R | 8.1 chown: Change file owner and group
 | -R | 8.2 chgrp: Change group ownership
 | -R | 8.3 chmod: Change access permissions
 | -s | 5.1.2 What information is listed
 | -S | 2.1 Backup options
 | -S | 5.1.3 Sorting the output
 | -s | 6.1 cp: Copy files and directories
 | -S | 6.1 cp: Copy files and directories
 | -s | 6.3 install: Copy files and set attributes
 | -S | 6.3 install: Copy files and set attributes
 | -s | 7.1 ln: Make links between files
 | -S | 6.4 mv: Move (rename) files
 | -s | 9.2 du: Estimate file space usage
 | -S | 7.1 ln: Make links between files
 | -S | 9.2 du: Estimate file space usage
 | -s BYTES | 6.6 shred: Remove files more securely
 | -t | 5.1.3 Sorting the output
 | -T | 5.1.5 General output formatting
 | -t | 9.1 df: Report filesystem disk space usage
 | -T | 9.1 df: Report filesystem disk space usage
 | -u | 5.1.3 Sorting the output
 | -U | 5.1.3 Sorting the output
 | -u | 6.4 mv: Move (rename) files
 | -u | 6.6 shred: Remove files more securely
 | -v | 5.1.3 Sorting the output
 | -V | 6.1 cp: Copy files and directories
 | -V | 6.3 install: Copy files and set attributes
 | -v | 6.1 cp: Copy files and directories
 | -V | 6.4 mv: Move (rename) files
 | -v | 6.3 install: Copy files and set attributes
 | -v | 6.4 mv: Move (rename) files
 | -V | 7.1 ln: Make links between files
 | -v | 6.5 rm: Remove files or directories
 | -v | 6.6 shred: Remove files more securely
 | -v | 7.1 ln: Make links between files
 | -v | 7.2 mkdir: Make directories
 | -v | 7.5 rmdir: Remove empty directories
 | -v | 8.1 chown: Change file owner and group
 | -v | 8.2 chgrp: Change group ownership
 | -v | 8.3 chmod: Change access permissions
 | -w | 5.1.5 General output formatting
 | -x | 5.1.5 General output formatting
 | -X | 5.1.3 Sorting the output
 | -x | 6.1 cp: Copy files and directories
 | -x | 6.6 shred: Remove files more securely
 | -x | 9.1 df: Report filesystem disk space usage
 | -x | 9.2 du: Estimate file space usage
 | -X FILE | 9.2 du: Estimate file space usage
 | -z | 6.6 shred: Remove files more securely
4 |  |
 | 4.2 filesystem type | 9.1 df: Report filesystem disk space usage
A |  |
 | abbreviations for months | 4.2 Calendar date items
 | access permissions, changing | 8.3 chmod: Change access permissions
 | access time, changing | 8.4 touch: Change file timestamps
 | access time, printing or sorting files by | 5.1.3 Sorting the output
 | across, listing files | 5.1.5 General output formatting
 | adding permissions | 3.2.1 Setting Permissions
 | ago in date strings | 4.6 Relative items in date strings
 | alternate ebcdic, converting to | 6.2 dd: Convert and copy a file
 | always color option | 5.1.5 General output formatting
 | am in date strings | 4.3 Time of day items
 | appropriate privileges | 6.3 install: Copy files and set attributes
 | ascii, converting to | 6.2 dd: Convert and copy a file
 | atime, changing | 8.4 touch: Change file timestamps
 | atime, printing or sorting files by | 5.1.3 Sorting the output
 | attributes, file | 8. Changing file attributes
 | authors of getdate | 4.8 Authors of getdate
 | auto color option | 5.1.5 General output formatting
 | automounter filesystems | 9.1 df: Report filesystem disk space usage
B |  |
 | b for block special file | 7.4 mknod: Make block or character special files
 | backslash sequences for file names | 5.1.6 Formatting the file names
 | backup files, ignoring | 5.1.1 Which files are listed
 | backup options | 2.1 Backup options
 | backup suffix | 2.1 Backup options
 | backups, making | 2.1 Backup options
 | backups, making | 6.1 cp: Copy files and directories
 | backups, making | 6.3 install: Copy files and set attributes
 | backups, making | 6.4 mv: Move (rename) files
 | backups, making | 7.1 ln: Make links between files
 | backups, making only | 6.1 cp: Copy files and directories
 | beginning of time, for POSIX | 4. Date input formats
 | Bellovin, Steven M. | 4.8 Authors of getdate
 | Berets, Jim | 4.8 Authors of getdate
 | Berry, K. | 4.8 Authors of getdate
 | block (space-padding) | 6.2 dd: Convert and copy a file
 | block size | 2.2 Block size
 | block size | 6.2 dd: Convert and copy a file
 | block size of conversion | 6.2 dd: Convert and copy a file
 | block size of input | 6.2 dd: Convert and copy a file
 | block size of output | 6.2 dd: Convert and copy a file
 | block special files | 7.4 mknod: Make block or character special files
 | block special files, creating | 7.4 mknod: Make block or character special files
 | BLOCK_SIZE | 2.2 Block size
 | Bourne shell syntax for color setup | 5.4 dircolors: Color setup for ls
 | bs | 6.2 dd: Convert and copy a file
 | BSD touch compatibility | 8.4 touch: Change file timestamps
 | bugs, reporting | 1. Introduction
 | byte-swapping | 6.2 dd: Convert and copy a file
C |  |
 | c for character special file | 7.4 mknod: Make block or character special files
 | C shell syntax for color setup | 5.4 dircolors: Color setup for ls
 | calendar date item | 4.2 Calendar date items
 | case, ignored in dates | 4.1 General date syntax
 | cbs | 6.2 dd: Convert and copy a file
 | CD-ROM filesystem type | 9.1 df: Report filesystem disk space usage
 | cdfs filesystem type | 9.1 df: Report filesystem disk space usage
 | changed files, verbosely describing | 8.2 chgrp: Change group ownership
 | changed owners, verbosely describing | 8.1 chown: Change file owner and group
 | changing access permissions | 8.3 chmod: Change access permissions
 | changing file attributes | 8. Changing file attributes
 | changing file ownership | 8.1 chown: Change file owner and group
 | changing file timestamps | 8.4 touch: Change file timestamps
 | changing group ownership | 8.1 chown: Change file owner and group
 | changing group ownership | 8.2 chgrp: Change group ownership
 | changing special permissions | 3.2.3 Changing Special Permissions
 | character special files | 7.4 mknod: Make block or character special files
 | character special files, creating | 7.4 mknod: Make block or character special files
 | chgrp | 8.2 chgrp: Change group ownership
 | chmod | 8.3 chmod: Change access permissions
 | chown | 8.1 chown: Change file owner and group
 | color database, printing | 5.4 dircolors: Color setup for ls
 | color setup | 5.4 dircolors: Color setup for ls
 | color, distinguishing file types with | 5.1.5 General output formatting
 | COLUMNS | 5.1.5 General output formatting
 | commas, outputting between files | 5.1.5 General output formatting
 | comments, in dates | 4.1 General date syntax
 | common options | 2. Common options
 | conditional executability | 3.2.4 Conditional Executability
 | conv | 6.2 dd: Convert and copy a file
 | conversion block size | 6.2 dd: Convert and copy a file
 | converting while copying a file | 6.2 dd: Convert and copy a file
 | copying directories recursively | 6.1 cp: Copy files and directories
 | copying existing permissions | 3.2.2 Copying Existing Permissions
 | copying files and directories | 6.1 cp: Copy files and directories
 | copying files and setting attributes | 6.3 install: Copy files and set attributes
 | count | 6.2 dd: Convert and copy a file
 | cp | 6.1 cp: Copy files and directories
 | crashes and corruption | 9.3 sync: Synchronize data on disk with memory
 | creating directories | 7.2 mkdir: Make directories
 | creating FIFOs (named pipes) | 7.3 mkfifo: Make FIFOs (named pipes)
 | creating links (hard or soft) | 7.1 ln: Make links between files
 | csh syntax for color setup | 5.4 dircolors: Color setup for ls
 | ctime, printing or sorting by | 5.1.3 Sorting the output
D |  |
 | data, erasing | 6.6 shred: Remove files more securely
 | database for color setup, printing | 5.4 dircolors: Color setup for ls
 | date format, ISO 8601 | 4.2 Calendar date items
 | date input formats | 4. Date input formats
 | day in date strings | 4.6 Relative items in date strings
 | day in date strings | 4.6 Relative items in date strings
 | day of week item | 4.5 Day of week items
 | dd | 6.2 dd: Convert and copy a file
 | dereferencing symbolic links | 7.1 ln: Make links between files
 | destination directory | 2.3 Target directory
 | destination directory | 6.1 cp: Copy files and directories
 | destination directory | 6.3 install: Copy files and set attributes
 | destination directory | 6.4 mv: Move (rename) files
 | destination directory | 7.1 ln: Make links between files
 | device file, disk | 9.1 df: Report filesystem disk space usage
 | df | 9.1 df: Report filesystem disk space usage
 | DF_BLOCK_SIZE | 2.2 Block size
 | dir | 5.2 dir: Briefly list directory contents
 | dircolors | 5.4 dircolors: Color setup for ls
 | directories, copying | 6.1 cp: Copy files and directories
 | directories, copying recursively | 6.1 cp: Copy files and directories
 | directories, creating | 7.2 mkdir: Make directories
 | directories, creating with given attributes | 6.3 install: Copy files and set attributes
 | directories, removing (recursively) | 6.5 rm: Remove files or directories
 | directories, removing empty | 7.5 rmdir: Remove empty directories
 | directories, removing with unlink | 6.5 rm: Remove files or directories
 | directory deletion, ignoring failures | 7.5 rmdir: Remove empty directories
 | directory deletion, reporting | 7.5 rmdir: Remove empty directories
 | directory listing | 5.1 ls: List directory contents
 | directory listing, brief | 5.2 dir: Briefly list directory contents
 | directory listing, recursive | 5.1.1 Which files are listed
 | directory listing, verbose | 5.3 vdir: Verbosely list directory contents
 | directory order, listing by | 5.1.3 Sorting the output
 | dired Emacs mode support | 5.1.2 What information is listed
 | disk allocation | 5.1.2 What information is listed
 | disk device file | 9.1 df: Report filesystem disk space usage
 | disk usage | 9. Disk usage
 | disk usage by filesystem | 9.1 df: Report filesystem disk space usage
 | disk usage for files | 9.2 du: Estimate file space usage
 | diskette filesystem | 9.1 df: Report filesystem disk space usage
 | displacement of dates | 4.6 Relative items in date strings
 | DOS filesystem | 9.1 df: Report filesystem disk space usage
 | du | 9.2 du: Estimate file space usage
 | DU_BLOCK_SIZE | 2.2 Block size
E |  |
 | ebcdic, converting to | 6.2 dd: Convert and copy a file
 | efs filesystem type | 9.1 df: Report filesystem disk space usage
 | Eggert, Paul | 4.8 Authors of getdate
 | empty files, creating | 8.4 touch: Change file timestamps
 | epoch, for POSIX | 4. Date input formats
 | erasing data | 6.6 shred: Remove files more securely
 | error messages, omitting | 8.1 chown: Change file owner and group
 | error messages, omitting | 8.2 chgrp: Change group ownership
 | error messages, omitting | 8.3 chmod: Change access permissions
 | excluding files from du | 9.2 du: Estimate file space usage
 | excluding files from du | 9.2 du: Estimate file space usage
 | executables and file type, marking | 5.1.5 General output formatting
 | execute permission | 3.1 Structure of File Permissions
 | execute permission, symbolic | 3.2.1 Setting Permissions
 | existing backup method | 2.1 Backup options
 | extension, sorting files by | 5.1.3 Sorting the output
F |  |
 | FIFOs, creating | 7.3 mkfifo: Make FIFOs (named pipes)
 | file attributes, changing | 8. Changing file attributes
 | file information, preserving | 6.1 cp: Copy files and directories
 | file ownership, changing | 8.1 chown: Change file owner and group
 | file permissions | 3. File permissions
 | file permissions, numeric | 3.3 Numeric Modes
 | file space usage | 9.2 du: Estimate file space usage
 | file timestamps, changing | 8.4 touch: Change file timestamps
 | file type and executables, marking | 5.1.5 General output formatting
 | file type, marking | 5.1.5 General output formatting
 | file types | 7. Special file types
 | file types, special | 7. Special file types
 | file utilities |
 | files beginning with `-', removing | 6.5 rm: Remove files or directories
 | files, copying | 6.1 cp: Copy files and directories
 | filesystem disk usage | 9.1 df: Report filesystem disk space usage
 | filesystem space, retrieving current data more slowly | 9.1 df: Report filesystem disk space usage
 | filesystem space, retrieving old data more quickly | 9.1 df: Report filesystem disk space usage
 | filesystem types, limiting output to certain | 9.1 df: Report filesystem disk space usage
 | filesystem types, limiting output to certain | 9.1 df: Report filesystem disk space usage
 | filesystem types, printing | 9.1 df: Report filesystem disk space usage
 | filesystems and hard links | 7.1 ln: Make links between files
 | filesystems, omitting copying to different | 6.1 cp: Copy files and directories
 | first in date strings | 4.1 General date syntax
 | force deletion | 6.6 shred: Remove files more securely
 | fortnight in date strings | 4.6 Relative items in date strings
 | fsck | 6.5 rm: Remove files or directories
G |  |
 | general date syntax | 4.1 General date syntax
 | getdate | 4. Date input formats
 | giving away permissions | 3.2.6 The Umask and Protection
 | grand total of disk space | 9.2 du: Estimate file space usage
 | group owner, default | 3.1 Structure of File Permissions
 | group ownership of installed files, setting | 6.3 install: Copy files and set attributes
 | group ownership, changing | 8.1 chown: Change file owner and group
 | group ownership, changing | 8.2 chgrp: Change group ownership
 | group, permissions for | 3.2.1 Setting Permissions
H |  |
 | hard link, defined | 7.1 ln: Make links between files
 | hard links to directories | 7.1 ln: Make links between files
 | hard links, counting in du | 9.2 du: Estimate file space usage
 | hard links, creating | 7.1 ln: Make links between files
 | hard links, preserving | 6.1 cp: Copy files and directories
 | help, online | 2. Common options
 | High Sierra filesystem | 9.1 df: Report filesystem disk space usage
 | history | 1. Introduction
 | holes, copying files with | 6.1 cp: Copy files and directories
 | horizontal, listing files | 5.1.5 General output formatting
 | hour in date strings | 4.6 Relative items in date strings
 | hsfs filesystem type | 9.1 df: Report filesystem disk space usage
 | human-readable output | 2.2 Block size
 | human-readable output | 5.1.2 What information is listed
 | human-readable output | 9.1 df: Report filesystem disk space usage
 | human-readable output | 9.2 du: Estimate file space usage
I |  |
 | ibs | 6.2 dd: Convert and copy a file
 | if | 6.2 dd: Convert and copy a file
 | ignore filesystems | 9.1 df: Report filesystem disk space usage
 | inode number, printing | 5.1.2 What information is listed
 | inode usage | 9.1 df: Report filesystem disk space usage
 | inode, and hard links | 7.1 ln: Make links between files
 | inodes, written buffered | 9.3 sync: Synchronize data on disk with memory
 | input block size | 6.2 dd: Convert and copy a file
 | install | 6.3 install: Copy files and set attributes
 | introduction | 1. Introduction
 | ISO 8601 date format | 4.2 Calendar date items
 | items in date strings | 4.1 General date syntax
 | iterations, selecting the number of | 6.6 shred: Remove files more securely
K |  |
 | kilobytes for filesystem sizes | 9.1 df: Report filesystem disk space usage
L |  |
 | language, in dates | 4.1 General date syntax
 | language, in dates | 4.1 General date syntax
 | last day | 4.5 Day of week items
 | last in date strings | 4.1 General date syntax
 | lcase, converting to | 6.2 dd: Convert and copy a file
 | lchown | 8.1 chown: Change file owner and group
 | lchown | 8.1 chown: Change file owner and group
 | lchown | 8.2 chgrp: Change group ownership
 | lchown | 8.2 chgrp: Change group ownership
 | leading directories, creating missing | 6.3 install: Copy files and set attributes
 | limiting output of du | 9.2 du: Estimate file space usage
 | links, creating | 7.1 ln: Make links between files
 | Linux filesystem types | 9.1 df: Report filesystem disk space usage
 | ln | 7.1 ln: Make links between files
 | local filesystem types | 9.1 df: Report filesystem disk space usage
 | long ls format | 5.1.2 What information is listed
 | ls | 5.1 ls: List directory contents
 | LS_BLOCK_SIZE | 2.2 Block size
 | LS_COLORS | 5.4 dircolors: Color setup for ls
M |  |
 | MacKenzie, David | 4.8 Authors of getdate
 | Makefiles, installing programs in | 6.3 install: Copy files and set attributes
 | manipulating files | 6. Basic operations
 | megabytes for filesystem sizes | 9.1 df: Report filesystem disk space usage
 | megabytes for filesystem sizes | 9.2 du: Estimate file space usage
 | Meyering, Jim | 4.8 Authors of getdate
 | midnight in date strings | 4.3 Time of day items
 | minute in date strings | 4.6 Relative items in date strings
 | minutes, time zone correction by | 4.3 Time of day items
 | mkdir | 7.2 mkdir: Make directories
 | mkfifo | 7.3 mkfifo: Make FIFOs (named pipes)
 | mknod | 7.4 mknod: Make block or character special files
 | modes and umask | 3.2.6 The Umask and Protection
 | modes of created directories, setting | 7.2 mkdir: Make directories
 | modes of created FIFOs, setting | 7.3 mkfifo: Make FIFOs (named pipes)
 | modification time, sorting files by | 5.1.3 Sorting the output
 | modify time, changing | 8.4 touch: Change file timestamps
 | month in date strings | 4.6 Relative items in date strings
 | month names in date strings | 4.2 Calendar date items
 | months, written-out | 4.1 General date syntax
 | MS-DOS filesystem | 9.1 df: Report filesystem disk space usage
 | mtime, changing | 8.4 touch: Change file timestamps
 | multiple changes to permissions | 3.2.5 Making Multiple Changes
 | multipliers after numbers | 6.2 dd: Convert and copy a file
 | mv | 6.4 mv: Move (rename) files
N |  |
 | named pipes, creating | 7.3 mkfifo: Make FIFOs (named pipes)
 | newer files, moving only | 6.4 mv: Move (rename) files
 | next day | 4.5 Day of week items
 | next in date strings | 4.1 General date syntax
 | NFS filesystem type | 9.1 df: Report filesystem disk space usage
 | NFS mounts from BSD to HP-UX | 5.1.2 What information is listed
 | NFS mounts from BSD to HP-UX | 9.2 du: Estimate file space usage
 | noerror | 6.2 dd: Convert and copy a file
 | non-directories, copying as special files | 6.1 cp: Copy files and directories
 | none backup method | 2.1 Backup options
 | none color option | 5.1.5 General output formatting
 | none, sorting option for ls | 5.1.3 Sorting the output
 | noon in date strings | 4.3 Time of day items
 | notrunc | 6.2 dd: Convert and copy a file
 | now in date strings | 4.6 Relative items in date strings
 | numbered backup method | 2.1 Backup options
 | numbers, written-out | 4.1 General date syntax
 | numeric modes | 3.3 Numeric Modes
 | numeric uid and gid | 5.1.5 General output formatting
O |  |
 | obs | 6.2 dd: Convert and copy a file
 | octal numbers for file modes | 3.3 Numeric Modes
 | of | 6.2 dd: Convert and copy a file
 | one filesystem, restricting du to | 9.2 du: Estimate file space usage
 | one-line output format | 9.1 df: Report filesystem disk space usage
 | ordinal numbers | 4.1 General date syntax
 | other permissions | 3.2.1 Setting Permissions
 | output block size | 6.2 dd: Convert and copy a file
 | output format, portable | 9.1 df: Report filesystem disk space usage
 | owner of file, permissions for | 3.2.1 Setting Permissions
 | owner, default | 3.1 Structure of File Permissions
 | ownership of installed files, setting | 6.3 install: Copy files and set attributes
P |  |
 | p for FIFO file | 7.4 mknod: Make block or character special files
 | parent directories and cp | 6.1 cp: Copy files and directories
 | parent directories, creating | 7.2 mkdir: Make directories
 | parent directories, creating missing | 6.3 install: Copy files and set attributes
 | parent directories, removing | 7.5 rmdir: Remove empty directories
 | PC filesystem | 9.1 df: Report filesystem disk space usage
 | pcfs | 9.1 df: Report filesystem disk space usage
 | permissions of files | 3. File permissions
 | permissions of installed files, setting | 6.3 install: Copy files and set attributes
 | permissions, changing access | 8.3 chmod: Change access permissions
 | permissions, copying existing | 3.2.2 Copying Existing Permissions
 | permissions, for changing file timestamps | 8.4 touch: Change file timestamps
 | permissions, output by ls | 5.1.2 What information is listed
 | Pinard, F. | 4.8 Authors of getdate
 | pm in date strings | 4.3 Time of day items
 | portable output format | 9.1 df: Report filesystem disk space usage
 | POSIX output format | 9.1 df: Report filesystem disk space usage
 | POSIX.2 | 1. Introduction
 | POSIXLY_CORRECT, and block size | 2.2 Block size
 | printing color database | 5.4 dircolors: Color setup for ls
 | prompting, and ln | 7.1 ln: Make links between files
 | prompting, and mv | 6.4 mv: Move (rename) files
 | prompting, and rm | 6.5 rm: Remove files or directories
 | prompts, forcing | 6.4 mv: Move (rename) files
 | prompts, omitting | 6.4 mv: Move (rename) files
 | pure numbers in date strings | 4.7 Pure numbers in date strings
Q |  |
 | quoting style | 5.1.6 Formatting the file names
R |  |
 | read errors, ignoring | 6.2 dd: Convert and copy a file
 | read permission | 3.1 Structure of File Permissions
 | read permission, symbolic | 3.2.1 Setting Permissions
 | read system call, and holes | 6.1 cp: Copy files and directories
 | recursive directory listing | 5.1.1 Which files are listed
 | recursively changing access permissions | 8.3 chmod: Change access permissions
 | recursively changing file ownership | 8.1 chown: Change file owner and group
 | recursively changing group ownership | 8.2 chgrp: Change group ownership
 | recursively copying directories | 6.1 cp: Copy files and directories
 | relative items in date strings | 4.6 Relative items in date strings
 | removing empty directories | 7.5 rmdir: Remove empty directories
 | removing files after shredding | 6.6 shred: Remove files more securely
 | removing files or directories | 6.5 rm: Remove files or directories
 | removing permissions | 3.2.1 Setting Permissions
 | restricted deletion flag | 3.1 Structure of File Permissions
 | reverse sorting | 5.1.3 Sorting the output
 | rm | 6.5 rm: Remove files or directories
 | rmdir | 7.5 rmdir: Remove empty directories
 | root as default owner | 6.3 install: Copy files and set attributes
S |  |
 | Salz, Rich | 4.8 Authors of getdate
 | seek | 6.2 dd: Convert and copy a file
 | self-backups | 6.1 cp: Copy files and directories
 | setgid | 3.1 Structure of File Permissions
 | setting permissions | 3.2.1 Setting Permissions
 | setuid | 3.1 Structure of File Permissions
 | setup for color | 5.4 dircolors: Color setup for ls
 | sh syntax for color setup | 5.4 dircolors: Color setup for ls
 | SHELL environment variable, and color | 5.4 dircolors: Color setup for ls
 | shred | 6.6 shred: Remove files more securely
 | SI output | 2.2 Block size
 | SI output | 5.1.2 What information is listed
 | SI output | 9.1 df: Report filesystem disk space usage
 | SI output | 9.2 du: Estimate file space usage
 | simple backup method | 2.1 Backup options
 | SIMPLE_BACKUP_SUFFIX | 2.1 Backup options
 | single-column output of files | 5.1.5 General output formatting
 | size of file to shred | 6.6 shred: Remove files more securely
 | size of files, reporting | 5.1.2 What information is listed
 | size of files, sorting files by | 5.1.3 Sorting the output
 | skip | 6.2 dd: Convert and copy a file
 | sorting ls output | 5.1.3 Sorting the output
 | sparse files, copying | 6.1 cp: Copy files and directories
 | special file types | 7. Special file types
 | special file types | 7. Special file types
 | special files | 7.4 mknod: Make block or character special files
 | status time, printing or sorting by | 5.1.3 Sorting the output
 | sticky | 3.1 Structure of File Permissions
 | stripping symbol table information | 6.3 install: Copy files and set attributes
 | stripping trailing slashes | 6.1 cp: Copy files and directories
 | stripping trailing slashes | 6.4 mv: Move (rename) files
 | subtracting permissions | 3.2.1 Setting Permissions
 | superblock, writing | 9.3 sync: Synchronize data on disk with memory
 | swab (byte-swapping) | 6.2 dd: Convert and copy a file
 | swap space, saving text image in | 3.1 Structure of File Permissions
 | symbol table information, stripping | 6.3 install: Copy files and set attributes
 | symbolic (soft) links, creating | 7.1 ln: Make links between files
 | symbolic link, defined | 7.1 ln: Make links between files
 | symbolic links, changing group | 8.2 chgrp: Change group ownership
 | symbolic links, changing owner | 8.1 chown: Change file owner and group
 | symbolic links, changing owner | 8.1 chown: Change file owner and group
 | symbolic links, changing owner | 8.1 chown: Change file owner and group
 | symbolic links, changing owner | 8.2 chgrp: Change group ownership
 | symbolic links, copying | 6.1 cp: Copy files and directories
 | symbolic links, copying with | 6.1 cp: Copy files and directories
 | symbolic links, dereferencing | 5.1.1 Which files are listed
 | symbolic links, dereferencing in du | 9.2 du: Estimate file space usage
 | symbolic links, permissions of | 8.3 chmod: Change access permissions
 | symbolic modes | 3.2 Symbolic Modes
 | sync | 9.3 sync: Synchronize data on disk with memory
 | sync (padding with nulls) | 6.2 dd: Convert and copy a file
 | synchronize disk and memory | 9.3 sync: Synchronize data on disk with memory
T |  |
 | target directory | 2.3 Target directory
 | target directory | 2.3 Target directory
 | target directory | 6.1 cp: Copy files and directories
 | target directory | 6.3 install: Copy files and set attributes
 | target directory | 6.4 mv: Move (rename) files
 | target directory | 7.1 ln: Make links between files
 | terminal, using color iff | 5.1.5 General output formatting
 | text image, saving in swap space | 3.1 Structure of File Permissions
 | this in date strings | 4.6 Relative items in date strings
 | time | 8.4 touch: Change file timestamps
 | time of day item | 4.3 Time of day items
 | time zone correction | 4.3 Time of day items
 | time zone item | 4.1 General date syntax
 | time zone item | 4.4 Time zone items
 | timestamps of installed files, preserving | 6.3 install: Copy files and set attributes
 | timestamps, changing file | 8.4 touch: Change file timestamps
 | today in date strings | 4.6 Relative items in date strings
 | tomorrow in date strings | 4.6 Relative items in date strings
 | touch | 8.4 touch: Change file timestamps
 | trailing slashes | 2.4 Trailing slashes
 | truncating output file, avoiding | 6.2 dd: Convert and copy a file
U |  |
 | ucase, converting to | 6.2 dd: Convert and copy a file
 | ufs filesystem type | 9.1 df: Report filesystem disk space usage
 | umask and modes | 3.2.6 The Umask and Protection
 | unblock | 6.2 dd: Convert and copy a file
 | unlink | 6.5 rm: Remove files or directories
 | unsorted directory listing | 5.1.3 Sorting the output
 | use time, changing | 8.4 touch: Change file timestamps
 | use time, printing or sorting files by | 5.1.3 Sorting the output
 | use time, printing or sorting files by | 5.1.3 Sorting the output
 | utilities for file handling |
V |  |
 | vdir | 5.3 vdir: Verbosely list directory contents
 | verbose ls format | 5.1.2 What information is listed
 | version number, finding | 2. Common options
 | version, sorting option for ls | 5.1.3 Sorting the output
 | version-control Emacs variable | 2.1 Backup options
 | VERSION_CONTROL | 2.1 Backup options
 | VERSION_CONTROL | 6.1 cp: Copy files and directories
 | VERSION_CONTROL | 6.3 install: Copy files and set attributes
 | VERSION_CONTROL | 6.4 mv: Move (rename) files
 | VERSION_CONTROL | 7.1 ln: Make links between files
 | vertical sorted files in columns | 5.1.5 General output formatting
W |  |
 | week in date strings | 4.6 Relative items in date strings
 | write permission | 3.1 Structure of File Permissions
 | write permission, symbolic | 3.2.1 Setting Permissions
Y |  |
 | year in date strings | 4.6 Relative items in date strings
 | yesterday in date strings | 4.6 Relative items in date strings

Jump to: - 4
A B C D E F G H I K L M N O P Q R S T U V W Y

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Introduction
    2. Common options
      2.1 Backup options
      2.2 Block size
      2.3 Target directory
      2.4 Trailing slashes
    3. File permissions
      3.1 Structure of File Permissions
      3.2 Symbolic Modes
        3.2.1 Setting Permissions
        3.2.2 Copying Existing Permissions
        3.2.3 Changing Special Permissions
        3.2.4 Conditional Executability
        3.2.5 Making Multiple Changes
        3.2.6 The Umask and Protection
      3.3 Numeric Modes
    4. Date input formats
      4.1 General date syntax
      4.2 Calendar date items
      4.3 Time of day items
      4.4 Time zone items
      4.5 Day of week items
      4.6 Relative items in date strings
      4.7 Pure numbers in date strings
      4.8 Authors of getdate
    5. Directory listing
      5.1 ls: List directory contents
        5.1.1 Which files are listed
        5.1.2 What information is listed
        5.1.3 Sorting the output
        5.1.4 More details about version sort
        5.1.5 General output formatting
        5.1.6 Formatting the file names
      5.2 dir: Briefly list directory contents
      5.3 vdir: Verbosely list directory contents
      5.4 dircolors: Color setup for ls
    6. Basic operations
      6.1 cp: Copy files and directories
      6.2 dd: Convert and copy a file
      6.3 install: Copy files and set attributes
      6.4 mv: Move (rename) files
      6.5 rm: Remove files or directories
      6.6 shred: Remove files more securely
    7. Special file types
      7.1 ln: Make links between files
      7.2 mkdir: Make directories
      7.3 mkfifo: Make FIFOs (named pipes)
      7.4 mknod: Make block or character special files
      7.5 rmdir: Remove empty directories
    8. Changing file attributes
      8.1 chown: Change file owner and group
      8.2 chgrp: Change group ownership
      8.3 chmod: Change access permissions
      8.4 touch: Change file timestamps
    9. Disk usage
      9.1 df: Report filesystem disk space usage
      9.2 du: Estimate file space usage
      9.3 sync: Synchronize data on disk with memory
    Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Introduction
2. Common options
3. File permissions
4. Date input formats
5. Directory listing
6. Basic operations
7. Special file types
8. Changing file attributes
9. Disk usage
Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on May 3, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on May 3, 2002 using texi2html


Finding Files

Edition 1.1, for GNU find version 4.1

November 1994

by David MacKenzie

Table of Contents

  • Introduction
    • Scope
    • Overview
    • find Expressions
  • Finding Files
    • Name
      • Base Name Patterns
      • Full Name Patterns
      • Fast Full Name Search
      • Shell Pattern Matching
    • Links
      • Symbolic Links
      • Hard Links
    • Time
      • Age Ranges
      • Comparing Timestamps
    • Size
    • Type
    • Owner
    • Permissions
    • Contents
    • Directories
    • Filesystems
    • Combining Primaries With Operators
  • Actions
    • Print File Name
    • Print File Information
      • Escapes
      • Format Directives
        • Name Directives
        • Ownership Directives
        • Size Directives
        • Location Directives
        • Time Directives
      • Time Formats
        • Time Components
        • Date Components
        • Combined Time Formats
    • Run Commands
      • Single File
      • Multiple Files
        • Unsafe File Name Handling
        • Safe File Name Handling
        • Limiting Command Size
        • Interspersing File Names
      • Querying
    • Adding Tests
  • Common Tasks
    • Viewing And Editing
    • Archiving
    • Cleaning Up
    • Strange File Names
    • Fixing Permissions
    • Classifying Files
  • File Name Databases
    • Database Locations
    • Database Formats
      • New Database Format
      • Sample Database
      • Old Database Format
  • File Permissions
    • Structure of File Permissions
    • Symbolic Modes
      • Setting Permissions
      • Copying Existing Permissions
      • Changing Special Permissions
      • Conditional Executability
      • Making Multiple Changes
      • The Umask and Protection
    • Numeric Modes
  • Reference
    • Invoking find
    • Invoking locate
    • Invoking updatedb
    • Invoking xargs
  • find Primary Index

Introduction

This manual shows how to find files that meet criteria you specify, and how to perform various actions on the files that you find. The principal programs that you use to perform these tasks are find, locate, and xargs. Some of the examples in this manual use capabilities specific to the GNU versions of those programs.

GNU find was originally written by Eric Decker, with enhancements by David MacKenzie, Jay Plett, and Tim Wood. GNU xargs was originally written by Mike Rendell, with enhancements by David MacKenzie. GNU locate and its associated utilities were originally written by James Woods, with enhancements by David MacKenzie. The idea for `find -print0' and `xargs -0' came from Dan Bernstein. Many other people have contributed bug fixes, small improvements, and helpful suggestions. Thanks!

Mail suggestions and bug reports for these programs to bug-gnu-utils@prep.ai.mit.edu. Please include the version number, which you can get by running `find --version'.

Scope

For brevity, the word file in this manual means a regular file, a directory, a symbolic link, or any other kind of node that has a directory entry. A directory entry is also called a file name. A file name may contain some, all, or none of the directories in a path that leads to the file. These are all examples of what this manual calls "file names":

parser.c
README
./budget/may-94.sc
fred/.cshrc
/usr/local/include/termcap.h

A directory tree is a directory and the files it contains, all of its subdirectories and the files they contain, etc. It can also be a single non-directory file.

These programs enable you to find the files in one or more directory trees that:

  • have names that contain certain text or match a certain pattern;
  • are links to certain files;
  • were last used during a certain period of time;
  • are within a certain size range;
  • are of a certain type (regular file, directory, symbolic link, etc.);
  • are owned by a certain user or group;
  • have certain access permissions;
  • contain text that matches a certain pattern;
  • are within a certain depth in the directory tree;
  • or some combination of the above.

Once you have found the files you're looking for (or files that are potentially the ones you're looking for), you can do more to them than simply list their names. You can get any combination of the files' attributes, or process the files in many ways, either individually or in groups of various sizes. Actions that you might want to perform on the files you have found include, but are not limited to:

  • view or edit
  • store in an archive
  • remove or rename
  • change access permissions
  • classify into groups

This manual describes how to perform each of those tasks, and more.

Overview

The principal programs used for making lists of files that match given criteria and running commands on them are find, locate, and xargs. An additional command, updatedb, is used by system administrators to create databases for locate to use.

find searches for files in a directory hierarchy and prints information about the files it found. It is run like this:

find [file...] [expression]

Here is a typical use of find. This example prints the names of all files in the directory tree rooted in `/usr/src' whose name ends with `.c' and that are larger than 100 Kilobytes.

find /usr/src -name '*.c' -size +100k -print

locate searches special file name databases for file names that match patterns. The system administrator runs the updatedb program to create the databases. locate is run like this:

locate [option...] pattern...

This example prints the names of all files in the default file name database whose name ends with `Makefile' or `makefile'. Which file names are stored in the database depends on how the system administrator ran updatedb.

locate '*[Mm]akefile'

The name xargs, pronounced EX-args, means "combine arguments." xargs builds and executes command lines by gathering together arguments it reads on the standard input. Most often, these arguments are lists of file names generated by find. xargs is run like this:

xargs [option...] [command [initial-arguments]]

The following command searches the files listed in the file `file-list' and prints all of the lines in them that contain the word `typedef'.

xargs grep typedef < file-list

find Expressions

The expression that find uses to select files consists of one or more primaries, each of which is a separate command line argument to find. find evaluates the expression each time it processes a file. An expression can contain any of the following types of primaries:

options
affect overall operation rather than the processing of a specific file;
tests
return a true or false value, depending on the file's attributes;
actions
have side effects and return a true or false value; and
operators
connect the other arguments and affect when and whether they are evaluated.

You can omit the operator between two primaries; it defaults to `-and'. See section Combining Primaries With Operators, for ways to connect primaries into more complex expressions. If the expression contains no actions other than `-prune', `-print' is performed on all files for which the entire expression is true (see section Print File Name).

Options take effect immediately, rather than being evaluated for each file when their place in the expression is reached. Therefore, for clarity, it is best to place them at the beginning of the expression.

Many of the primaries take arguments, which immediately follow them in the next command line argument to find. Some arguments are file names, patterns, or other strings; others are numbers. Numeric arguments can be specified as

+n
for greater than n,
-n
for less than n,
n
for exactly n.

Finding Files

By default, find prints to the standard output the names of the files that match the given criteria. See section Actions, for how to get more information about the matching files.

Name

Here are ways to search for files whose name matches a certain pattern. See section Shell Pattern Matching, for a description of the pattern arguments to these tests.

Each of these tests has a case-sensitive version and a case-insensitive version, whose name begins with `i'. In a case-insensitive comparison, the patterns `fo*' and `F??' match the file names `Foo', `FOO', `foo', `fOo', etc.

Base Name Patterns

Test: -name pattern
Test: -iname pattern
True if the base of the file name (the path with the leading directories removed) matches shell pattern pattern. For `-iname', the match is case-insensitive. To ignore a whole directory tree, use `-prune' (see section Directories). As an example, to find Texinfo source files in `/usr/local/doc':

find /usr/local/doc -name '*.texi'

Full Name Patterns

Test: -path pattern
Test: -ipath pattern
True if the entire file name, starting with the command line argument under which the file was found, matches shell pattern pattern. For `-ipath', the match is case-insensitive. To ignore a whole directory tree, use `-prune' rather than checking every file in the tree (see section Directories).

Test: -regex expr
Test: -iregex expr
True if the entire file name matches regular expression expr. This is a match on the whole path, not a search. For example, to match a file named `./fubar3', you can use the regular expression `.*bar.' or `.*b.*3', but not `b.*r3'. See section `Syntax of Regular Expressions' in The GNU Emacs Manual, for a description of the syntax of regular expressions. For `-iregex', the match is case-insensitive.

Fast Full Name Search

To search for files by name without having to actually scan the directories on the disk (which can be slow), you can use the locate program. For each shell pattern you give it, locate searches one or more databases of file names and displays the file names that contain the pattern. See section Shell Pattern Matching, for details about shell patterns.

If a pattern is a plain string--it contains no metacharacters---locate displays all file names in the database that contain that string. If a pattern contains metacharacters, locate only displays file names that match the pattern exactly. As a result, patterns that contain metacharacters should usually begin with a `*', and will most often end with one as well. The exceptions are patterns that are intended to explicitly match the beginning or end of a file name.

The command

locate pattern

is almost equivalent to

find directories -name pattern

where directories are the directories for which the file name databases contain information. The differences are that the locate information might be out of date, and that locate handles wildcards in the pattern slightly differently than find (see section Shell Pattern Matching).

The file name databases contain lists of files that were on the system when the databases were last updated. The system administrator can choose the file name of the default database, the frequency with which the databases are updated, and the directories for which they contain entries.

Here is how to select which file name databases locate searches. The default is system-dependent.

--database=path
-d path
Instead of searching the default file name database, search the file name databases in path, which is a colon-separated list of database file names. You can also use the environment variable LOCATE_PATH to set the list of database files to search. The option overrides the environment variable if both are used.

Shell Pattern Matching

find and locate can compare file names, or parts of file names, to shell patterns. A shell pattern is a string that may contain the following special characters, which are known as wildcards or metacharacters.

You must quote patterns that contain metacharacters to prevent the shell from expanding them itself. Double and single quotes both work; so does escaping with a backslash.

*
Matches any zero or more characters.
?
Matches any one character.
[string]
Matches exactly one character that is a member of the string string. This is called a character class. As a shorthand, string may contain ranges, which consist of two characters with a dash between them. For example, the class `[a-z0-9_]' matches a lowercase letter, a number, or an underscore. You can negate a class by placing a `!' or `^' immediately after the opening bracket. Thus, `[^A-Z@]' matches any character except an uppercase letter or an at sign.
\
Removes the special meaning of the character that follows it. This works even in character classes.

In the find tests that do shell pattern matching (`-name', `-path', etc.), wildcards in the pattern do not match a `.' at the beginning of a file name. This is not the case for locate. Thus, `find -name '*macs'' does not match a file named `.emacs', but `locate '*macs'' does.

Slash characters have no special significance in the shell pattern matching that find and locate do, unlike in the shell, in which wildcards do not match them. Therefore, a pattern `foo*bar' can match a file name `foo3/bar', and a pattern `./sr*sc' can match a file name `./src/misc'.

Links

There are two ways that files can be linked together. Symbolic links are a special type of file whose contents are a portion of the name of another file. Hard links are multiple directory entries for one file; the file names all have the same index node (inode) number on the disk.

Symbolic Links

Test: -lname pattern
Test: -ilname pattern
True if the file is a symbolic link whose contents match shell pattern pattern. For `-ilname', the match is case-insensitive. See section Shell Pattern Matching, for details about the pattern argument. So, to list any symbolic links to `sysdep.c' in the current directory and its subdirectories, you can do:

find . -lname '*sysdep.c'

Option: -follow
Dereference symbolic links. The following differences in behavior occur when this option is given:

  • find follows symbolic links to directories when searching directory trees.
  • `-lname' and `-ilname' always return false.
  • `-type' reports the types of the files that symbolic links point to.
  • Implies `-noleaf' (see section Directories).

Hard Links

To find hard links, first get the inode number of the file whose links you want to find. You can learn a file's inode number and the number of links to it by running `ls -i' or `find -ls'. If the file has more than one link, you can search for the other links by passing that inode number to `-inum'. Add the `-xdev' option if you are starting the search at a directory that has other filesystems mounted on it, such as `/usr' on many systems. Doing this saves needless searching, since hard links to a file must be on the same filesystem. See section Filesystems.

Test: -inum n
File has inode number n.

You can also search for files that have a certain number of links, with `-links'. Directories normally have at least two hard links; their `.' entry is the second one. If they have subdirectories, each of those also has a hard link called `..' to its parent directory.

Test: -links n
File has n hard links.

Time

Each file has three time stamps, which record the last time that certain operations were performed on the file:

  1. access (read the file's contents)
  2. change the status (modify the file or its attributes)
  3. modify (change the file's contents)

You can search for files whose time stamps are within a certain age range, or compare them to other time stamps.

Age Ranges

These tests are mainly useful with ranges (`+n' and `-n').

Test: -atime n
Test: -ctime n
Test: -mtime n
True if the file was last accessed (or its status changed, or it was modified) n*24 hours ago.

Test: -amin n
Test: -cmin n
Test: -mmin n
True if the file was last accessed (or its status changed, or it was modified) n minutes ago. These tests provide finer granularity of measurement than `-atime' et al. For example, to list files in `/u/bill' that were last read from 2 to 6 hours ago:

find /u/bill -amin +2 -amin -6

Option: -daystart
Measure times from the beginning of today rather than from 24 hours ago. So, to list the regular files in your home directory that were modified yesterday, do

find ~ -daystart -type f -mtime 1

Comparing Timestamps

As an alternative to comparing timestamps to the current time, you can compare them to another file's timestamp. That file's timestamp could be updated by another program when some event occurs. Or you could set it to a particular fixed date using the touch command. For example, to list files in `/usr' modified after February 1 of the current year:

touch -t 02010000 /tmp/stamp$$
find /usr -newer /tmp/stamp$$
rm -f /tmp/stamp$$

Test: -anewer file
Test: -cnewer file
Test: -newer file
True if the file was last accessed (or its status changed, or it was modified) more recently than file was modified. These tests are affected by `-follow' only if `-follow' comes before them on the command line. See section Symbolic Links, for more information on `-follow'. As an example, to list any files modified since `/bin/sh' was last modified:

find . -newer /bin/sh

Test: -used n
True if the file was last accessed n days after its status was last changed. Useful for finding files that are not being used, and could perhaps be archived or removed to save disk space.

Size

Test: -size n[bckw]
True if the file uses n units of space, rounding up. The units are 512-byte blocks by default, but they can be changed by adding a one-character suffix to n:

b
512-byte blocks
c
bytes
k
kilobytes (1024 bytes)
w
2-byte words

The size does not count indirect blocks, but it does count blocks in sparse files that are not actually allocated.

Test: -empty
True if the file is empty and is either a regular file or a directory. This might make it a good candidate for deletion. This test is useful with `-depth' (see section Directories) and `-exec rm -rf '{}' ';'' (see section Single File).

Type

Test: -type c
True if the file is of type c:

b
block (buffered) special
c
character (unbuffered) special
d
directory
p
named pipe (FIFO)
f
regular file
l
symbolic link
s
socket

Test: -xtype c
The same as `-type' unless the file is a symbolic link. For symbolic links: if `-follow' has not been given, true if the file is a link to a file of type c; if `-follow' has been given, true if c is `l'. In other words, for symbolic links, `-xtype' checks the type of the file that `-type' does not check. See section Symbolic Links, for more information on `-follow'.

Owner

Test: -user uname
Test: -group gname
True if the file is owned by user uname (belongs to group gname). A numeric ID is allowed.

Test: -uid n
Test: -gid n
True if the file's numeric user ID (group ID) is n. These tests support ranges (`+n' and `-n'), unlike `-user' and `-group'.

Test: -nouser
Test: -nogroup
True if no user corresponds to the file's numeric user ID (no group corresponds to the numeric group ID). These cases usually mean that the files belonged to users who have since been removed from the system. You probably should change the ownership of such files to an existing user or group, using the chown or chgrp program.

Permissions

See section File Permissions, for information on how file permissions are structured and how to specify them.

Test: -perm mode
True if the file's permissions are exactly mode (which can be numeric or symbolic). Symbolic modes use mode 0 as a point of departure. If mode starts with `-', true if all of the permissions set in mode are set for the file; permissions not set in mode are ignored. If mode starts with `+', true if any of the permissions set in mode are set for the file; permissions not set in mode are ignored.

Contents

To search for files based on their contents, you can use the grep program. For example, to find out which C source files in the current directory contain the string `thing', you can do:

grep -l thing *.[ch]

If you also want to search for the string in files in subdirectories, you can combine grep with find and xargs, like this:

find . -name '*.[ch]' | xargs grep -l thing

The `-l' option causes grep to print only the names of files that contain the string, rather than the lines that contain it. The string argument (`thing') is actually a regular expression, so it can contain metacharacters. This method can be refined a little by using the `-r' option to make xargs not run grep if find produces no output, and using the find action `-print0' and the xargs option `-0' to avoid misinterpreting files whose names contain spaces:

find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing

For a fuller treatment of finding files whose contents match a pattern, see the manual page for grep.

Directories

Here is how to control which directories find searches, and how it searches them. These two options allow you to process a horizontal slice of a directory tree.

Option: -maxdepth levels
Descend at most levels (a non-negative integer) levels of directories below the command line arguments. `-maxdepth 0' means only apply the tests and actions to the command line arguments.

Option: -mindepth levels
Do not apply any tests or actions at levels less than levels (a non-negative integer). `-mindepth 1' means process all files except the command line arguments.

Option: -depth
Process each directory's contents before the directory itself. Doing this is a good idea when producing lists of files to archive with cpio or tar. If a directory does not have write permission for its owner, its contents can still be restored from the archive since the directory's permissions are restored after its contents.

Action: -prune
If `-depth' is not given, true; do not descend the current directory. If `-depth' is given, false; no effect. `-prune' only affects tests and actions that come after it in the expression, not those that come before.

For example, to skip the directory `src/emacs' and all files and directories under it, and print the names of the other files found:

find . -path './src/emacs' -prune -o -print

Option: -noleaf
Do not optimize by assuming that directories contain 2 fewer subdirectories than their hard link count. This option is needed when searching filesystems that do not follow the Unix directory-link convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount points. Each directory on a normal Unix filesystem has at least 2 hard links: its name and its `.' entry. Additionally, its subdirectories (if any) each have a `..' entry linked to that directory. When find is examining a directory, after it has statted 2 fewer subdirectories than the directory's link count, it knows that the rest of the entries in the directory are non-directories (leaf files in the directory tree). If only the files' names need to be examined, there is no need to stat them; this gives a significant increase in search speed.

Filesystems

A filesystem is a section of a disk, either on the local host or mounted from a remote host over a network. Searching network filesystems can be slow, so it is common to make find avoid them.

There are two ways to avoid searching certain filesystems. One way is to tell find to only search one filesystem:

Option: -xdev
Option: -mount
Don't descend directories on other filesystems. These options are synonyms.

The other way is to check the type of filesystem each file is on, and not descend directories that are on undesirable filesystem types:

Test: -fstype type
True if the file is on a filesystem of type type. The valid filesystem types vary among different versions of Unix; an incomplete list of filesystem types that are accepted on some version of Unix or another is:
ufs 4.2 4.3 nfs tmp mfs S51K S52K

You can use `-printf' with the `%F' directive to see the types of your filesystems. See section Print File Information. `-fstype' is usually used with `-prune' to avoid searching remote filesystems (see section Directories).

Combining Primaries With Operators

Operators build a complex expression from tests and actions. The operators are, in order of decreasing precedence:

( expr )
Force precedence. True if expr is true.
! expr
-not expr
True if expr is false.
expr1 expr2
expr1 -a expr2
expr1 -and expr2
And; expr2 is not evaluated if expr1 is false.
expr1 -o expr2
expr1 -or expr2
Or; expr2 is not evaluated if expr1 is true.
expr1 , expr2
List; both expr1 and expr2 are always evaluated. True if expr2 is true. The value of expr1 is discarded. This operator lets you do multiple independent operations on one traversal, without depending on whether other operations succeeded.

find searches the directory tree rooted at each file name by evaluating the expression from left to right, according to the rules of precedence, until the outcome is known (the left hand side is false for `-and', true for `-or'), at which point find moves on to the next file name.

There are two other tests that can be useful in complex expressions:

Test: -true
Always true.

Test: -false
Always false.

Actions

There are several ways you can print information about the files that match the criteria you gave in the find expression. You can print the information either to the standard output or to a file that you name. You can also execute commands that have the file names as arguments. You can use those commands as further filters to select files.

Print File Name

Action: -print
True; print the full file name on the standard output, followed by a newline.

Action: -fprint file
True; print the full file name into file file, followed by a newline. If file does not exist when find is run, it is created; if it does exist, it is truncated to 0 bytes. The file names `/dev/stdout' and `/dev/stderr' are handled specially; they refer to the standard output and standard error output, respectively.

Print File Information

Action: -ls
True; list the current file in `ls -dils' format on the standard output. The output looks like this:

204744   17 -rw-r--r--   1 djm      staff       17337 Nov  2  1992 ./lwall-quotes

The fields are:

  1. The inode number of the file. See section Hard Links, for how to find files based on their inode number.
  2. the number of blocks in the file. The block counts are of 1K blocks, unless the environment variable POSIXLY_CORRECT is set, in which case 512-byte blocks are used. See section Size, for how to find files based on their size.
  3. The file's type and permissions. The type is shown as a dash for a regular file; for other file types, a letter like for `-type' is used (see section Type). The permissions are read, write, and execute for the file's owner, its group, and other users, respectively; a dash means the permission is not granted. See section File Permissions, for more details about file permissions. See section Permissions, for how to find files based on their permissions.
  4. The number of hard links to the file.
  5. The user who owns the file.
  6. The file's group.
  7. The file's size in bytes.
  8. The date the file was last modified.
  9. The file's name. `-ls' quotes non-printable characters in the file names using C-like backslash escapes.

Action: -fls file
True; like `-ls' but write to file like `-fprint' (see section Print File Name).

Action: -printf format
True; print format on the standard output, interpreting `\' escapes and `%' directives. Field widths and precisions can be specified as with the printf C function. Unlike `-print', `-printf' does not add a newline at the end of the string.

Action: -fprintf file format
True; like `-printf' but write to file like `-fprint' (see section Print File Name).

Escapes

The escapes that `-printf' and `-fprintf' recognize are:

\a
Alarm bell.
\b
Backspace.
\c
Stop printing from this format immediately and flush the output.
\f
Form feed.
\n
Newline.
\r
Carriage return.
\t
Horizontal tab.
\v
Vertical tab.
\\
A literal backslash (`\').

A `\' character followed by any other character is treated as an ordinary character, so they both are printed, and a warning message is printed to the standard error output (because it was probably a typo).

Format Directives

`-printf' and `-fprintf' support the following format directives to print information about the file being processed. Unlike the C printf function, they do not support field width specifiers.

`%%' is a literal percent sign. A `%' character followed by any other character is discarded (but the other character is printed), and a warning message is printed to the standard error output (because it was probably a typo).

Name Directives

%p
File's name.
%f
File's name with any leading directories removed (only the last element).
%h
Leading directories of file's name (all but the last element and the slash before it).
%P
File's name with the name of the command line argument under which it was found removed from the beginning.
%H
Command line argument under which file was found.

Ownership Directives

%g
File's group name, or numeric group ID if the group has no name.
%G
File's numeric group ID.
%u
File's user name, or numeric user ID if the user has no name.
%U
File's numeric user ID.
%m
File's permissions (in octal).

Size Directives

%k
File's size in 1K blocks (rounded up).
%b
File's size in 512-byte blocks (rounded up).
%s
File's size in bytes.

Location Directives

%d
File's depth in the directory tree; files named on the command line have a depth of 0.
%F
Type of the filesystem the file is on; this value can be used for `-fstype' (see section Directories).
%l
Object of symbolic link (empty string if file is not a symbolic link).
%i
File's inode number (in decimal).
%n
Number of hard links to file.

Time Directives

Some of these directives use the C ctime function. Its output depends on the current locale, but it typically looks like

Wed Nov  2 00:42:36 1994
%a
File's last access time in the format returned by the C ctime function.
%Ak
File's last access time in the format specified by k (see section Time Formats).
%c
File's last status change time in the format returned by the C ctime function.
%Ck
File's last status change time in the format specified by k (see section Time Formats).
%t
File's last modification time in the format returned by the C ctime function.
%Tk
File's last modification time in the format specified by k (see section Time Formats).

Time Formats

Below are the formats for the directives `%A', `%C', and `%T', which print the file's timestamps. Some of these formats might not be available on all systems, due to differences in the C strftime function between systems.

Time Components

The following format directives print single components of the time.

H
hour (00..23)
I
hour (01..12)
k
hour ( 0..23)
l
hour ( 1..12)
p
locale's AM or PM
Z
time zone (e.g., EDT), or nothing if no time zone is determinable
M
minute (00..59)
S
second (00..61)
@
seconds since Jan. 1, 1970, 00:00 GMT.

Date Components

The following format directives print single components of the date.

a
locale's abbreviated weekday name (Sun..Sat)
A
locale's full weekday name, variable length (Sunday..Saturday)
b
h
locale's abbreviated month name (Jan..Dec)
B
locale's full month name, variable length (January..December)
m
month (01..12)
d
day of month (01..31)
w
day of week (0..6)
j
day of year (001..366)
U
week number of year with Sunday as first day of week (00..53)
W
week number of year with Monday as first day of week (00..53)
Y
year (1970...)
y
last two digits of year (00..99)

Combined Time Formats

The following format directives print combinations of time and date components.

r
time, 12-hour (hh:mm:ss [AP]M)
T
time, 24-hour (hh:mm:ss)
X
locale's time representation (H:M:S)
c
locale's date and time (Sat Nov 04 12:02:33 EST 1989)
D
date (mm/dd/yy)
x
locale's date representation (mm/dd/yy)

Run Commands

You can use the list of file names created by find or locate as arguments to other commands. In this way you can perform arbitrary actions on the files.

Single File

Here is how to run a command on one file at a time.

Action: -exec command ;
Execute command; true if 0 status is returned. find takes all arguments after `-exec' to be part of the command until an argument consisting of `;' is reached. It replaces the string `{}' by the current file name being processed everywhere it occurs in the command. Both of these constructions need to be escaped (with a `\') or quoted to protect them from expansion by the shell. The command is executed in the directory in which find was run.

For example, to compare each C header file in the current directory with the file `/tmp/master':

find . -name '*.h' -exec diff -u '{}' /tmp/master ';'

Multiple Files

Sometimes you need to process files alone. But when you don't, it is faster to run a command on as many files as possible at a time, rather than once per file. Doing this saves on the time it takes to start up the command each time.

To run a command on more than one file at once, use the xargs command, which is invoked like this:

xargs [option...] [command [initial-arguments]]

xargs reads arguments from the standard input, delimited by blanks (which can be protected with double or single quotes or a backslash) or newlines. It executes the command (default is `/bin/echo') one or more times with any initial-arguments followed by arguments read from standard input. Blank lines on the standard input are ignored.

Instead of blank-delimited names, it is safer to use `find -print0' or `find -fprint0' and process the output by giving the `-0' or `--null' option to GNU xargs, GNU tar, GNU cpio, or perl.

You can use shell command substitution (backquotes) to process a list of arguments, like this:

grep -l sprintf `find $HOME -name '*.c' -print`

However, that method produces an error if the length of the `.c' file names exceeds the operating system's command-line length limit. xargs avoids that problem by running the command as many times as necessary without exceeding the limit:

find $HOME -name '*.c' -print | grep -l sprintf

However, if the command needs to have its standard input be a terminal (less, for example), you have to use the shell command substitution method.

Unsafe File Name Handling

Because file names can contain quotes, backslashes, blank characters, and even newlines, it is not safe to process them using xargs in its default mode of operation. But since most files' names do not contain blanks, this problem occurs only infrequently. If you are only searching through files that you know have safe names, then you need not be concerned about it.

In many applications, if xargs botches processing a file because its name contains special characters, some data might be lost. The importance of this problem depends on the importance of the data and whether anyone notices the loss soon enough to correct it. However, here is an extreme example of the problems that using blank-delimited names can cause. If the following command is run daily from cron, then any user can remove any file on the system:

find / -name '#*' -atime +7 -print | xargs rm

For example, you could do something like this:

eg$ echo > '#
vmunix'

and then cron would delete `/vmunix', if it ran xargs with `/' as its current directory.

To delete other files, for example `/u/joeuser/.plan', you could do this:

eg$ mkdir '#
'
eg$ cd '#
'
eg$ mkdir u u/joeuser u/joeuser/.plan'
'
eg$ echo > u/joeuser/.plan'
/#foo'
eg$ cd ..
eg$ find . -name '#*' -print | xargs echo
./# ./# /u/joeuser/.plan /#foo

Safe File Name Handling

Here is how to make find output file names so that they can be used by other programs without being mangled or misinterpreted. You can process file names generated this way by giving the `-0' or `--null' option to GNU xargs, GNU tar, GNU cpio, or perl.

Action: -print0
True; print the full file name on the standard output, followed by a null character.

Action: -fprint0 file
True; like `-print0' but write to file like `-fprint' (see section Print File Name).

Limiting Command Size

xargs gives you control over how many arguments it passes to the command each time it executes it. By default, it uses up to ARG_MAX - 2k, or 20k, whichever is smaller, characters per command. It uses as many lines and arguments as fit within that limit. The following options modify those values.

--no-run-if-empty
-r
If the standard input does not contain any nonblanks, do not run the command. By default, the command is run once even if there is no input.
--max-lines[=max-lines]
-l[max-lines]
Use at most max-lines nonblank input lines per command line; max-lines defaults to 1 if omitted. Trailing blanks cause an input line to be logically continued on the next input line, for the purpose of counting the lines. Implies `-x'.
--max-args=max-args
-n max-args
Use at most max-args arguments per command line. Fewer than max-args arguments will be used if the size (see the `-s' option) is exceeded, unless the `-x' option is given, in which case xargs will exit.
--max-chars=max-chars
-s max-chars
Use at most max-chars characters per command line, including the command and initial arguments and the terminating nulls at the ends of the argument strings.
--max-procs=max-procs
-P max-procs
Run up to max-procs processes at a time; the default is 1. If max-procs is 0, xargs will run as many processes as possible at a time. Use the `-n', `-s', or `-l' option with `-P'; otherwise chances are that the command will be run only once.

Interspersing File Names

xargs can insert the name of the file it is processing between arguments you give for the command. Unless you also give options to limit the command size (see section Limiting Command Size), this mode of operation is equivalent to `find -exec' (see section Single File).

--replace[=replace-str]
-i[replace-str]
Replace occurences of replace-str in the initial arguments with names read from standard input. Also, unquoted blanks do not terminate arguments. If replace-str is omitted, it defaults to `{}' (like for `find -exec'). Implies `-x' and `-l 1'. As an example, to sort each file the `bills' directory, leaving the output in that file name with `.sorted' appended, you could do:
find bills -type f | xargs -iXX sort -o XX.sorted XX
The equivalent command using `find -exec' is:
find bills -type f -exec sort -o '{}.sorted' '{}' ';'

Querying

To ask the user whether to execute a command on a single file, you can use the find primary `-ok' instead of `-exec':

Action: -ok command ;
Like `-exec' (see section Single File), but ask the user first (on the standard input); if the response does not start with `y' or `Y', do not run the command, and return false.

When processing multiple files with a single command, to query the user you give xargs the following option. When using this option, you might find it useful to control the number of files processed per invocation of the command (see section Limiting Command Size).

--interactive
-p
Prompt the user about whether to run each command line and read a line from the terminal. Only run the command line if the response starts with `y' or `Y'. Implies `-t'.

Adding Tests

You can test for file attributes that none of the find builtin tests check. To do this, use xargs to run a program that filters a list of files printed by find. If possible, use find builtin tests to pare down the list, so the program run by xargs has less work to do. The tests builtin to find will likely run faster than tests that other programs perform.

For example, here is a way to print the names of all of the unstripped binaries in the `/usr/local' directory tree. Builtin tests avoid running file on files that are not regular files or are not executable.

find /usr/local -type f -perm +a=x | xargs file |
  grep 'not stripped' | cut -d: -f1

The cut program removes everything after the file name from the output of file.

If you want to place a special test somewhere in the middle of a find expression, you can use `-exec' to run a program that performs the test. Because `-exec' evaluates to the exit status of the executed program, you can write a program (which can be a shell script) that tests for a special attribute and make it exit with a true (zero) or false (non-zero) status. It is a good idea to place such a special test after the builtin tests, because it starts a new process which could be avoided if a builtin test evaluates to false. Use this method only when xargs is not flexible enough, because starting one or more new processes to test each file is slower than using xargs to start one process that tests many files.

Here is a shell script called unstripped that checks whether its argument is an unstripped binary file:

#!/bin/sh
file $1 | grep 'not stripped' > /dev/null

This script relies on the fact that the shell exits with the status of the last program it executed, in this case grep. grep exits with a true status if it found any matches, false if not. Here is an example of using the script (assuming it is in your search path). It lists the stripped executables in the file `sbins' and the unstripped ones in `ubins'.

find /usr/local -type f -perm +a=x \
  \( -exec unstripped '{}' \; -fprint ubins -o -fprint sbins \)

Common Tasks

The sections that follow contain some extended examples that both give a good idea of the power of these programs, and show you how to solve common real-world problems.

Viewing And Editing

To view a list of files that meet certain criteria, simply run your file viewing program with the file names as arguments. Shells substitute a command enclosed in backquotes with its output, so the whole command looks like this:

less `find /usr/include -name '*.h' | xargs grep -l mode_t`

You can edit those files by giving an editor name instead of a file viewing program.

Archiving

You can pass a list of files produced by find to a file archiving program. GNU tar and cpio can both read lists of file names from the standard input--either delimited by nulls (the safe way) or by blanks (the lazy, risky default way). To use null-delimited names, give them the `--null' option. You can store a file archive in a file, write it on a tape, or send it over a network to extract on another machine.

One common use of find to archive files is to send a list of the files in a directory tree to cpio. Use `-depth' so if a directory does not have write permission for its owner, its contents can still be restored from the archive since the directory's permissions are restored after its contents. Here is an example of doing this using cpio; you could use a more complex find expression to archive only certain files.

find . -depth -print0 |
  cpio --create --null --format=crc --file=/dev/nrst0

You could restore that archive using this command:

cpio --extract --null --make-dir --unconditional \
  --preserve --file=/dev/nrst0

Here are the commands to do the same things using tar:

find . -depth -print0 |
  tar --create --null --files-from=- --file=/dev/nrst0

tar --extract --null --preserve-perm --same-owner \
  --file=/dev/nrst0

Here is an example of copying a directory from one machine to another:

find . -depth -print0 | cpio -0o -Hnewc |
  rsh other-machine "cd `pwd` && cpio -i0dum"

Cleaning Up

This section gives examples of removing unwanted files in various situations. Here is a command to remove the CVS backup files created when an update requires a merge:

find . -name '.#*' -print0 | xargs -0r rm -f

You can run this command to clean out your clutter in `/tmp'. You might place it in the file your shell runs when you log out (`.bash_logout', `.logout', or `.zlogout', depending on which shell you use).

find /tmp -user $LOGNAME -type f -print0 | xargs -0 -r rm -f

To remove old Emacs backup and auto-save files, you can use a command like the following. It is especially important in this case to use null-terminated file names because Emacs packages like the VM mailer often create temporary file names with spaces in them, like `#reply to David J. MacKenzie<1>#'.

find ~ \( -name '*~' -o -name '#*#' \) -print0 |
  xargs --no-run-if-empty --null rm -vf

Removing old files from `/tmp' is commonly done from cron:

find /tmp /var/tmp -not -type d -mtime +3 -print0 |
  xargs --null --no-run-if-empty rm -f

find /tmp /var/tmp -depth -mindepth 1 -type d -empty -print0 |
  xargs --null --no-run-if-empty rmdir

The second find command above uses `-depth' so it cleans out empty directories depth-first, hoping that the parents become empty and can be removed too. It uses `-mindepth' to avoid removing `/tmp' itself if it becomes totally empty.

Strange File Names

find can help you remove or rename a file with strange characters in its name. People are sometimes stymied by files whose names contain characters such as spaces, tabs, control characters, or characters with the high bit set. The simplest way to remove such files is:

rm -i some*pattern*that*matches*the*problem*file

rm asks you whether to remove each file matching the given pattern. If you are using an old shell, this approach might not work if the file name contains a character with the high bit set; the shell may strip it off. A more reliable way is:

find . -maxdepth 1 tests -ok rm '{}' \;

where tests uniquely identify the file. The `-maxdepth 1' option prevents find from wasting time searching for the file in any subdirectories; if there are no subdirectories, you may omit it. A good way to uniquely identify the problem file is to figure out its inode number; use

ls -i

Suppose you have a file whose name contains control characters, and you have found that its inode number is 12345. This command prompts you for whether to remove it:

find . -maxdepth 1 -inum 12345 -ok rm -f '{}' \;

If you don't want to be asked, perhaps because the file name may contain a strange character sequence that will mess up your screen when printed, then use `-exec' instead of `-ok'.

If you want to rename the file instead, you can use mv instead of rm:

find . -maxdepth 1 -inum 12345 -ok mv '{}' new-file-name \;

Fixing Permissions

Suppose you want to make sure that everyone can write to the directories in a certain directory tree. Here is a way to find directories lacking either user or group write permission (or both), and fix their permissions:

find . -type d -not -perm -ug=w | xargs chmod ug+w

You could also reverse the operations, if you want to make sure that directories do not have world write permission.

Classifying Files

If you want to classify a set of files into several groups based on different criteria, you can use the comma operator to perform multiple independent tests on the files. Here is an example:

find / -type d \( -perm -o=w -fprint allwrite , \
  -perm -o=x -fprint allexec \)

echo "Directories that can be written to by everyone:"
cat allwrite
echo ""
echo "Directories with search permissions for everyone:"
cat allexec

find has only to make one scan through the directory tree (which is one of the most time consuming parts of its work).

File Name Databases

The file name databases used by locate contain lists of files that were in particular directory trees when the databases were last updated. The file name of the default database is determined when locate and updatedb are configured and installed. The frequency with which the databases are updated and the directories for which they contain entries depend on how often updatedb is run, and with which arguments.

Database Locations

There can be multiple file name databases. Users can select which databases locate searches using an environment variable or a command line option. The system administrator can choose the file name of the default database, the frequency with which the databases are updated, and the directories for which they contain entries. File name databases are updated by running the updatedb program, typically nightly.

In networked environments, it often makes sense to build a database at the root of each filesystem, containing the entries for that filesystem. updatedb is then run for each filesystem on the fileserver where that filesystem is on a local disk, to prevent thrashing the network. Here are the options to updatedb to select which directories each database contains entries for:

--localpaths='path...'
Non-network directories to put in the database. Default is `/'.
--netpaths='path...'
Network (NFS, AFS, RFS, etc.) directories to put in the database. Default is none.
--prunepaths='path...'
Directories to not put in the database, which would otherwise be. Default is `/tmp /usr/tmp /var/tmp /afs'.
--output=dbfile
The database file to build. Default is system-dependent, but typically `/usr/local/var/locatedb'.
--netuser=user
The user to search network directories as, using su. Default is daemon.

Database Formats

The file name databases contain lists of files that were in particular directory trees when the databases were last updated. The file name database format changed starting with GNU locate version 4.0 to allow machines with diffent byte orderings to share the databases. The new GNU locate can read both the old and new database formats. However, old versions of locate and find produce incorrect results if given a new-format database.

New Database Format

updatedb runs a program called frcode to front-compress the list of file names, which reduces the database size by a factor of 4 to 5. Front-compression (also known as incremental encoding) works as follows.

The database entries are a sorted list (case-insensitively, for users' convenience). Since the list is sorted, each entry is likely to share a prefix (initial string) with the previous entry. Each database entry begins with an offset-differential count byte, which is the additional number of characters of prefix of the preceding entry to use beyond the number that the preceding entry is using of its predecessor. (The counts can be negative.) Following the count is a null-terminated ASCII remainder--the part of the name that follows the shared prefix.

If the offset-differential count is larger than can be stored in a byte (+/-127), the byte has the value 0x80 and the count follows in a 2-byte word, with the high byte first (network byte order).

Every database begins with a dummy entry for a file called `LOCATE02', which locate checks for to ensure that the database file has the correct format; it ignores the entry in doing the search.

Databases can not be concatenated together, even if the first (dummy) entry is trimmed from all but the first database. This is because the offset-differential count in the first entry of the second and following databases will be wrong.

Sample Database

Sample input to frcode:

/usr/src
/usr/src/cmd/aardvark.c
/usr/src/cmd/armadillo.c
/usr/tmp/zoo

Length of the longest prefix of the preceding entry to share:

0 /usr/src
8 /cmd/aardvark.c
14 rmadillo.c
5 tmp/zoo

Output from frcode, with trailing nulls changed to newlines and count bytes made printable:

0 LOCATE02
0 /usr/src
8 /cmd/aardvark.c
6 rmadillo.c
-9 tmp/zoo

(6 = 14 - 8, and -9 = 5 - 14)

Old Database Format

The old database format is used by Unix locate and find programs and earlier releases of the GNU ones. updatedb produces this format if given the `--old-format' option.

updatedb runs programs called bigram and code to produce old-format databases. The old format differs from the new one in the following ways. Instead of each entry starting with an offset-differential count byte and ending with a null, byte values from 0 through 28 indicate offset-differential counts from -14 through 14. The byte value indicating that a long offset-differential count follows is 0x1e (30), not 0x80. The long counts are stored in host byte order, which is not necessarily network byte order, and host integer word size, which is usually 4 bytes. They also represent a count 14 less than their value. The database lines have no termination byte; the start of the next line is indicated by its first byte having a value <= 30.

In addition, instead of starting with a dummy entry, the old database format starts with a 256 byte table containing the 128 most common bigrams in the file list. A bigram is a pair of adjacent bytes. Bytes in the database that have the high bit set are indexes (with the high bit cleared) into the bigram table. The bigram and offset-differential count coding makes these databases 20-25% smaller than the new format, but makes them not 8-bit clean. Any byte in a file name that is in the ranges used for the special codes is replaced in the database by a question mark, which not coincidentally is the shell wildcard to match a single character.

File Permissions

Each file has a set of permissions that control the kinds of access that users have to that file. The permissions for a file are also called its access mode. They can be represented either in symbolic form or as an octal number.

Structure of File Permissions

There are three kinds of permissions that a user can have for a file:

  1. permission to read the file. For directories, this means permission to list the contents of the directory.
  2. permission to write to (change) the file. For directories, this means permission to create and remove files in the directory.
  3. permission to execute the file (run it as a program). For directories, this means permission to access files in the directory.

There are three categories of users who may have different permissions to perform any of the above operations on a file:

  1. the file's owner;
  2. other users who are in the file's group;
  3. everyone else.

Files are given an owner and group when they are created. Usually the owner is the current user and the group is the group of the directory the file is in, but this varies with the operating system, the filesystem the file is created on, and the way the file is created. You can change the owner and group of a file by using the chown and chgrp commands.

In addition to the three sets of three permissions listed above, a file's permissions have three special components, which affect only executable files (programs) and, on some systems, directories:

  1. set the process's effective user ID to that of the file upon execution (called the setuid bit). No effect on directories.
  2. set the process's effective group ID to that of the file upon execution (called the setgid bit). For directories on some systems, put files created in the directory into the same group as the directory, no matter what group the user who creates them is in.
  3. save the program's text image on the swap device so it will load more quickly when run (called the sticky bit). For directories on some systems, prevent users from removing files that they do not own in the directory; this is called making the directory append-only.

Symbolic Modes

Symbolic modes represent changes to files' permissions as operations on single-character symbols. They allow you to modify either all or selected parts of files' permissions, optionally based on their previous values, and perhaps on the current umask as well (see section The Umask and Protection).

The format of symbolic modes is:

[ugoa...][[+-=][rwxXstugo...]...][,...]

The following sections describe the operators and other details of symbolic modes.

Setting Permissions

The basic symbolic operations on a file's permissions are adding, removing, and setting the permission that certain users have to read, write, and execute the file. These operations have the following format:

users operation permissions

The spaces between the three parts above are shown for readability only; symbolic modes can not contain spaces.

The users part tells which users' access to the file is changed. It consists of one or more of the following letters (or it can be empty; see section The Umask and Protection, for a description of what happens then). When more than one of these letters is given, the order that they are in does not matter.

u
the user who owns the file;
g
other users who are in the file's group;
o
all other users;
a
all users; the same as `ugo'.

The operation part tells how to change the affected users' access to the file, and is one of the following symbols:

+
to add the permissions to whatever permissions the users already have for the file;
-
to remove the permissions from whatever permissions the users already have for the file;
=
to make the permissions the only permissions that the users have for the file.

The permissions part tells what kind of access to the file should be changed; it is zero or more of the following letters. As with the users part, the order does not matter when more than one letter is given. Omitting the permissions part is useful only with the `=' operation, where it gives the specified users no access at all to the file.

r
the permission the users have to read the file;
w
the permission the users have to write to the file;
x
the permission the users have to execute the file.

For example, to give everyone permission to read and write a file, but not to execute it, use:

a=rw

To remove write permission for from all users other than the file's owner, use:

go-w

The above command does not affect the access that the owner of the file has to it, nor does it affect whether other users can read or execute the file.

To give everyone except a file's owner no permission to do anything with that file, use the mode below. Other users could still remove the file, if they have write permission on the directory it is in.

go=

Another way to specify the same thing is:

og-rxw

Copying Existing Permissions

You can base part of a file's permissions on part of its existing permissions. To do this, instead of using `r', `w', or `x' after the operator, you use the letter `u', `g', or `o'. For example, the mode

o+g

adds the permissions for users who are in a file's group to the permissions that other users have for the file. Thus, if the file started out as mode 664 (`rw-rw-r--'), the above mode would change it to mode 666 (`rw-rw-rw-'). If the file had started out as mode 741 (`rwxr----x'), the above mode would change it to mode 745 (`rwxr--r-x'). The `-' and `=' operations work analogously.

Changing Special Permissions

In addition to changing a file's read, write, and execute permissions, you can change its special permissions. See section Structure of File Permissions, for a summary of these permissions.

To change a file's permission to set the user ID on execution, use `u' in the users part of the symbolic mode and `s' in the permissions part.

To change a file's permission to set the group ID on execution, use `g' in the users part of the symbolic mode and `s' in the permissions part.

To change a file's permission to stay permanently on the swap device, use `o' in the users part of the symbolic mode and `t' in the permissions part.

For example, to add set user ID permission to a program, you can use the mode:

u+s

To remove both set user ID and set group ID permission from it, you can use the mode:

ug-s

To cause a program to be saved on the swap device, you can use the mode:

o+t

Remember that the special permissions only affect files that are executable, plus, on some systems, directories (on which they have different meanings; see section Structure of File Permissions). Using `a' in the users part of a symbolic mode does not cause the special permissions to be affected; thus,

a+s

has no effect. You must use `u', `g', and `o' explicitly to affect the special permissions. Also, the combinations `u+t', `g+t', and `o+s' have no effect.

The `=' operator is not very useful with special permissions; for example, the mode:

o=t

does cause the file to be saved on the swap device, but it also removes all read, write, and execute permissions that users not in the file's group might have had for it.

Conditional Executability

There is one more special type of symbolic permission: if you use `X' instead of `x', execute permission is affected only if the file already had execute permission or is a directory. It affects directories' execute permission even if they did not initially have any execute permissions set.

For example, this mode:

a+X

gives all users permission to execute files (or search directories) if anyone could before.

Making Multiple Changes

The format of symbolic modes is actually more complex than described above (see section Setting Permissions). It provides two ways to make multiple changes to files' permissions.

The first way is to specify multiple operation and permissions parts after a users part in the symbolic mode.

For example, the mode:

og+rX-w

gives users other than the owner of the file read permission and, if it is a directory or if someone already had execute permission to it, gives them execute permission; and it also denies them write permission to it file. It does not affect the permission that the owner of the file has for it. The above mode is equivalent to the two modes:

og+rX
og-w

The second way to make multiple changes is to specify more than one simple symbolic mode, separated by commas. For example, the mode:

a+r,go-w

gives everyone permission to read the file and removes write permission on it for all users except its owner. Another example:

u=rwx,g=rx,o=

sets all of the non-special permissions for the file explicitly. (It gives users who are not in the file's group no permission at all for it.)

The two methods can be combined. The mode:

a+r,g+x-w

gives all users permission to read the file, and gives users who are in the file's group permission to execute it, as well, but not permission to write to it. The above mode could be written in several different ways; another is:

u+r,g+rx,o+r,g-w

The Umask and Protection

If the users part of a symbolic mode is omitted, it defaults to `a' (affect all users), except that any permissions that are set in the system variable umask are not affected. The value of umask can be set using the umask command. Its default value varies from system to system.

Omitting the users part of a symbolic mode is generally not useful with operations other than `+'. It is useful with `+' because it allows you to use umask as an easily customizable protection against giving away more permission to files than you intended to.

As an example, if umask has the value 2, which removes write permission for users who are not in the file's group, then the mode:

+w

adds permission to write to the file to its owner and to other users who are in the file's group, but not to other users. In contrast, the mode:

a+w

ignores umask, and does give write permission for the file to all users.

Numeric Modes

File permissions are stored internally as 16 bit integers. As an alternative to giving a symbolic mode, you can give an octal (base 8) number that corresponds to the internal representation of the new mode. This number is always interpreted in octal; you do not have to add a leading 0, as you do in C. Mode 0055 is the same as mode 55.

A numeric mode is usually shorter than the corresponding symbolic mode, but it is limited in that it can not take into account a file's previous permissions; it can only set them absolutely.

The permissions granted to the user, to other users in the file's group, and to other users not in the file's group are each stored as three bits, which are represented as one octal digit. The three special permissions are also each stored as one bit, and they are as a group represented as another octal digit. Here is how the bits are arranged in the 16 bit integer, starting with the lowest valued bit:

Value in  Corresponding
Mode      Permission

          Other users not in the file's group:
   1      Execute
   2      Write
   4      Read

          Other users in the file's group:
  10      Execute
  20      Write
  40      Read

          The file's owner:
 100      Execute
 200      Write
 400      Read

          Special permissions:
1000      Save text image on swap device
2000      Set group ID on execution
4000      Set user ID on execution

For example, numeric mode 4755 corresponds to symbolic mode `u=rwxs,go=rx', and numeric mode 664 corresponds to symbolic mode `ug=rw,o=r'. Numeric mode 0 corresponds to symbolic mode `ugo='.

Reference

Below are summaries of the command line syntax for the programs discussed in this manual.

Invoking find

find [file...] [expression]

find searches the directory tree rooted at each file name file by evaluating the expression on each file it finds in the tree.

find considers the first argument that begins with `-', `(', `)', `,', or `!' to be the beginning of the expression; any arguments before it are paths to search, and any arguments after it are the rest of the expression. If no paths are given, the current directory is used. If no expression is given, the expression `-print' is used.

find exits with status 0 if all files are processed successfully, greater than 0 if errors occur.

See section find Primary Index, for a summary of all of the tests, actions, and options that the expression can contain.

find also recognizes two options for administrative use:

--help
Print a summary of the command-line argument format and exit.
--version
Print the version number of find and exit.

Invoking locate

locate [option...] pattern...
--database=path
-d path
Instead of searching the default file name database, search the file name databases in path, which is a colon-separated list of database file names. You can also use the environment variable LOCATE_PATH to set the list of database files to search. The option overrides the environment variable if both are used.
--help
Print a summary of the options to locate and exit.
--version
Print the version number of locate and exit.

Invoking updatedb

updatedb [option...]
--localpaths='path...'
Non-network directories to put in the database. Default is `/'.
--netpaths='path...'
Network (NFS, AFS, RFS, etc.) directories to put in the database. Default is none.
--prunepaths='path...'
Directories to not put in the database, which would otherwise be. Default is `/tmp /usr/tmp /var/tmp /afs'.
--output=dbfile
The database file to build. Default is system-dependent, but typically `/usr/local/var/locatedb'.
--netuser=user
The user to search network directories as, using su(1). Default is daemon.

Invoking xargs

xargs [option...] [command [initial-arguments]]

xargs exits with the following status:

0
if it succeeds
123
if any invocation of the command exited with status 1-125
124
if the command exited with status 255
125
if the command is killed by a signal
126
if the command cannot be run
127
if the command is not found
1
if some other error occurred.
--null
-0
Input filenames are terminated by a null character instead of by whitespace, and the quotes and backslash are not special (every character is taken literally). Disables the end of file string, which is treated like any other argument.
--eof[=eof-str]
-e[eof-str]
Set the end of file string to eof-str. If the end of file string occurs as a line of input, the rest of the input is ignored. If eof-str is omitted, there is no end of file string. If this option is not given, the end of file string defaults to `_'.
--help
Print a summary of the options to xargs and exit.
--replace[=replace-str]
-i[replace-str]
Replace occurences of replace-str in the initial arguments with names read from standard input. Also, unquoted blanks do not terminate arguments. If replace-str is omitted, it defaults to `{}' (like for `find -exec'). Implies `-x' and `-l 1'.
--max-lines[=max-lines]
-l[max-lines]
Use at most max-lines nonblank input lines per command line; max-lines defaults to 1 if omitted. Trailing blanks cause an input line to be logically continued on the next input line, for the purpose of counting the lines. Implies `-x'.
--max-args=max-args
-n max-args
Use at most max-args arguments per command line. Fewer than max-args arguments will be used if the size (see the `-s' option) is exceeded, unless the `-x' option is given, in which case xargs will exit.
--interactive
-p
Prompt the user about whether to run each command line and read a line from the terminal. Only run the command line if the response starts with `y' or `Y'. Implies `-t'.
--no-run-if-empty
-r
If the standard input does not contain any nonblanks, do not run the command. By default, the command is run once even if there is no input.
--max-chars=max-chars
-s max-chars
Use at most max-chars characters per command line, including the command and initial arguments and the terminating nulls at the ends of the argument strings.
--verbose
-t
Print the command line on the standard error output before executing it.
--version
Print the version number of xargs and exit.
--exit
-x
Exit if the size (see the -s option) is exceeded.
--max-procs=max-procs
-P max-procs
Run up to max-procs processes at a time; the default is 1. If max-procs is 0, xargs will run as many processes as possible at a time.

find Primary Index

This is a list of all of the primaries (tests, actions, and options) that make up find expressions for selecting files. See section find Expressions, for more information on expressions.

Jump to: -

-

  • -amin
  • -anewer
  • -atime
  • -cmin
  • -cnewer
  • -ctime
  • -daystart
  • -depth
  • -empty
  • -exec
  • -false
  • -fls
  • -follow
  • -fprint
  • -fprint0
  • -fprintf
  • -fstype
  • -gid
  • -group
  • -ilname
  • -iname
  • -inum
  • -ipath
  • -iregex
  • -links
  • -lname
  • -ls
  • -maxdepth
  • -mindepth
  • -mmin
  • -mount
  • -mtime
  • -name
  • -newer
  • -nogroup
  • -noleaf
  • -nouser
  • -ok
  • -path
  • -perm
  • -print
  • -print0
  • -printf
  • -prune
  • -regex
  • -size
  • -true
  • -type
  • -uid
  • -used
  • -user
  • -xdev
  • -xtype

    • This document was generated on 7 November 1998 using the texi2html translator version 1.52.


GNU Finger

Edition 1.3, for GNU Finger version 1.37

October 1992

by Jan Brittenson and Brian Fox

Table of Contents

  • Introduction
    • Why Another Finger?
  • Using Finger
    • Arguments to GNU Finger
    • Command Line Options
    • Special User Names
  • Advanced Use
    • How Finger Works
    • The `~/.fingerrc' Script
    • User-defined Targets
    • How Finger Picks a Port
  • Security Issues
  • Bug Reports
  • Installation
    • Basic Installation
    • Configuration Files
      • The `clients' file
      • The `serverhost' file
      • The `mailhost' file
      • The `forwardhost' file
      • The `ttylocs' file
    • Site Specific Functions
    • Configuration Options
  • GNU Finger Quick Reference

Introduction

GNU Finger is a utility program designed to allow users of Unix hosts on the Internet network to get information about each other. It is a direct replacement for the Berkeley 4.3 finger code, although it produces different looking output and is designed to run on a wide variety of systems.

Why Another Finger?

Originally, each host on the Internet network consisted of a single, reasonably powerful computer, capable of handling many users at the same time. Typically, a site (physical location of computer users) would have only one or two computers, even if they had 20 or more people who used them. If a user at site A wanted to know about users logged on at site B, a simple program could be invoked to query the host at site B about the users which were logged on.

With the onset of more-power-per-person computing, the mainframe has been set aside. A modern computing facility usually consists of one user per host, and many hosts per site. This makes it a trial to find out about logged on users at another site, since you must query each host to find out about the single user who is logged on. If the site had 20 hosts, you would have to invoke a finger program 20 times just to find out who was logged on!

GNU Finger is a simple and effective way around this problem. For sites with many hosts, a single host may be designated as the finger server host. This host collects information about who is logged on to other hosts at that site. If a user at site A wants to know about users logged on at site B, only the server host need be queried, instead of each host at that site. This is very convenient.

GNU Finger is a direct replacement for existing finger programs. Since the finger protocol (rules for communication) is very simple, GNU Finger follows that protocol in responding to simple requests. But GNU Finger also implements another protocol which allows two finger programs to exchange information in a predetermined way, which allows faster and wider bandwidth communication.

Finger delivers information about users in varying formats, depending on how it is invoked. finger invoked without any options performs a site wide finger request, no matter which machine it has been invoked from. Switch arguments exist for getting the "long" form of finger information and for getting information only about the local machine.

If a user on host A wants to know about a user on host B, finger must make a network connection to host B. If host B is running a finger program, that program is asked to relay information about the user in question through the connection back to host A, where finger can display it.

GNU Finger also runs a server daemon process on the server host, whose job is to keep track of which users are logged in to local machines.

An optional and currently unsupported feature is passing of graphic images. This is built on the new protocol. A user at site A (e.g. MIT) may see the picture of a user at site B (e.g. UCSB), by typing a finger request. The conversion of graphic data from one format to another is done through GNU Finger; no site need know where or how such images are stored on any other site to be able to display those images. You should ask your system administrator to find out whether he has chose to include this functionality on your network.

Using Finger

Arguments to GNU Finger

The basic argument to Finger is a user@host pair. The user portion is the name of the user about whom you would like information. The host is a machine that the user has an account on. When invoked in this manner, GNU Finger displays the list of hosts that this user is currently logged in on, or, if the user is not logged in, the last time and location that he or she was. host may be expressed as any valid Internet address (i.e. dot-notation, host.domain, etc).

If host is non-existent, the local host is assumed. If user is blank or unspecified, it is assumed that you want information about all users.

The content and format of the output of GNU finger depends on what is being fingered:

User
Displays login information about user. If `--info' or `--l' is also specified, finger will display the full name, home directory, shell, mail forwarding, and `.plan' and/or `.project' file. This is what the output will look like:
bash$ finger --info bson@gnu.ai.mit.edu
[apple-gunkies.gnu.ai.mit.edu]

Jan Brittenson (bson)
Home: /home/fsf/bson
Shell: /usr/local/bin/bash
Mail forwarded to bson@ai.mit.edu.
No mail.
  User     Real Name         What    Idle  TTY  Host      Console Location
bson     Jan Brittenson     fgrep          *p0 apple-gu (nutrimat.gnu.ai.)
bson     Jan Brittenson              1:57  *sb nutrimat

Plan:
    To hack GNU Finger
The following is output, in the order listed, when asking for long information (`-l' or `--info') about a particular user:
  • Real and login names.
  • Home directory.
  • Login shell.
  • Mail forwarding.
  • Whether the user has any unread mail, and if so, when it was last read.
  • Current login information, in the same format as produced by a short finger (see below for an explanation). If the user isn't currently logged on, then the last login time and remote host (if known) is reported.
  • A `~/.plan' file. If the file isn't readable by everyone, then a message is printed to this effect.
  • A `~/.projects' file. This file, like `~/.plan', should be readable by everyone.

bash$ finger bson@gnu.ai.mit.edu
[apple-gunkies.gnu.ai.mit.edu]
  User     Real Name         What    Idle  TTY  Host      Console Location
bson     Jan Brittenson     fgrep          *p0 apple-gu (nutrimat.gnu.ai.)
bson     Jan Brittenson              1:57  *sb nutrimat
Here is an explanation of what each column contains in the short example:
User
The user login name.
Real Name
The real name of the user.
What
The current or last program run by the user, depending on the system in use. On System V Release 4, for instance, the current program is shown, but on BSD it will be the last terminated program.
Idle
The time the user has been idle, as hours:minutes, or the first 7 characters of a string such as "14 days".
TTY
The significant portion of the user's terminal connection. Exactly what portion this is is system dependent. For example, on System V Release 4, it might be `*40' for `/dev/pty/40', while on BSD it might be `*p0' for `/dev/ttyp0'. If preceded by an asterisk ("*"), then the user allows anyone to send messages to this particular terminal.
Host
The host the user is logged onto.
Console Location
Where the user's console is located. If logged in over the network, then this will be the most significant portion of the remote host name if known. A host name is always parenthesized.
In the general short output (i.e. not for a particular host), GNU Finger lists the least idle login for a particular user on each host. A single user often has several logins, since on some systems each window opened creates its own login record. In addition to the least idle login, the console login is also always listed, regardless of how long it has been idle. To list all login records for a particular, host, use the special target `.local'. For example, while the following may be part of the general short finger listing for the host `mole.gnu.ai.mit.edu':
brendan  Brendan Kehoe               5:09  *p8 mole     (lisa.cygnus.com)
info     InfoMaster                 12:12  *p4 mole     (hal)
law      Jeffrey A. Law              3:52  *p7 mole     (128.110.4.17:0.0)
rms      Richard Stallman   sendmai  1:34  *p1 mole     (unix:0.0)
rms      Richard Stallman           6 days *co mole
The last line is the console. The following might be listed by the command `finger .local@mole.gnu.ai.mit.edu':
[mole.gnu.ai.mit.edu]
  User     Real Name         What    Idle  TTY  Host      Console Location
brendan  Brendan Kehoe               5:18  *p8 mole     (lisa.cygnus.com)
info     InfoMaster                 12:22  *p4 mole     (hal)
law      Jeffrey A. Law              4:01  *p7 mole     (128.110.4.17:0.0)
rms      Richard Stallman   sendmai  1:44  *p1 mole     (unix:0.0)
rms      Richard Stallman           23:08  *p0 mole     (unix:0.0)
rms      Richard Stallman           1 day, *p2 mole     (unix:0.0)
rms      Richard Stallman           6 days *co mole
Mailing List or Alias
Expands the mailing list or alias and displays the recipients. You always have to use `--info' or (or `-l') when fingering a mailing list or mail alias, otherwise mail aliases won't be looked up due to the extra processing involved. This is what the output will look like:
% finger --info postmaster@gnu.ai.mit.edu
postmaster is an alias for the following:
    Roland McGrath <roland>,
    <tower@prep.ai.mit.edu>,
    Noah Friedman <friedman>,
    Michael I Bushnell <mib>
User-defined Target
Allows the remote host to display specific information, such as price lists, literature, or weather forecasts. For example:
% finger .site@gnu.ai.mit.edu

This is the FSF GNU Project. For more information, please contact
"postmaster". For information about guest accounts, please contact
"request".

Command Line Options

There are a number of command line options that you can give to GNU Finger:

`--face'
`-f'
Ask Finger for the face of all users information has been requested about. An explicit user list has to be provided.
`--info'
`-l'
`-i'
Display the "long" form of information for the users fingered. The exact information returned depends on what finger software is run on the remote host -- GNU Finger, for instance, returns specific information. `-l' is supplied for backwards compatibility; finger as distributed from Berkeley has this option.
`--brief'
`-b'
Display the "short" form of information for the users fingered. This is the opposite of `--info'.
`--port port'
`-P port'
Make a connection to port, which can be either a numerical port number or a service name from `/etc/services'.
`--help'
`-h'
Print a description of all options.

Special User Names

You can give GNU Finger one of several "special" user names. These user names all begin with a period (`.') and instruct the receiving finger daemon to do something that only a GNU Finger daemon can do. Currently, the "special" names are:

`.free'
Return a list of free machines. `Free' machines are those that have no users logged in, or have been idle for a long time. The information returned makes it clear which one is true.
`.all'
Return the information about every machine that the Finger server knows about. `.all' is equivalent to issuing the finger command without specifying the user name.
`.site'
Returns information about the site, such as company and location.
`.clients'
Returns a list of the clients that the GNU Finger server knows about. Also lists who is logged onto the console.
`.faces'
Return a list of the faces that this server has available. The last line output tells you how many lines were listed previously.
`.local'
Finger only at the specific machine. This allows finger to continue to be useful even in the event that the server is down. It also allows you to examine all the login records of a user. Normally, the server only keeps track of the most recently active login record for each user.
`.help'
Describe services provided by the finger server.

Advanced Use

How Finger Works

GNU Finger is the collective name for a set of programs:

`finger'
Parses the command line and connects to the finger server, `in.fingerd', on the finger server. Returns the output from the server. finger connects to in.fingerd on the host specified in the command line. This is the only program you need to know anything about if you're a regular user. You should refer to this program as the finger client to avoid possible confusion.
`fingerd'
Regularly connects to in.cfingerd on the clients specified in the `fingerdir/clients' file, to obtain finger data. This client data is saved in the file `fingerdir/userdata'. fingerd should run on the host specified in the `fingerdir/serverhost' file. fingerd should be started at boot time.
`in.fingerd'
Responds to finger connections through inetd. Should be attached to the `finger' service via `/etc/inetd.conf'. in.fingerd behaves somewhat differently depending on what host it runs on: on the server host it reads the `fingerdir/userdata' database, on all other hosts it forwards all requests (unless `.local' is the target) to in.fingerd on the host specified in `fingerdir/serverhost'. in.fingerd reads the `fingerdir/userdata' database, various system files, and makes SMTP connections to the host specified in the `fingerdir/mailhost' file.
`in.cfingerd'
This is the program that responds to call-ins from fingerd by sampling the status on the client and forwarding it to fingerd. It should be configured to respond to the `cfinger' service specified in the `clients' configuration file, or port 2003 if nothing else is specified.

The `~/.fingerrc' Script

When the GNU Finger server receives a request for information about a user it looks to see if the user has a `.fingerrc' file in the home directory. If such a file exists, and is executable, then this file is executed, and the normal finger output is passed to it as input. Its output becomes what is returned for the request. Thus, it can be used to:

  • Disable fingering a specific user by linking `~user/.fingerrc' to `/bin/true'.
  • Entirely replace the output of finger by ignoring its input. Below is a sample script which could be put in `~price-info/.fingerrc'.
    #! /bin/sh
#
# This sample script replaces the output of GNU Finger
#
echo Hack-O-Matic Consulting Services, Inc. "   " `date`

cat <<ETX

Hi, thanks for asking us about prices on our newly introduced support
services for Free Software. Below is a list of new services; for a list
of our previous services, please send mail to this address and someone
will contact you. Please don't forget to tell us how to reach you.

ETX
cat ~/info/new-stuff
  • Filter the output to make changes. If the script below is put in `~bson/.fingerrc' on the finger server host for the domain `gnu.ai.mit.edu':
    #! /bin/sh
#
# This sample filter replaces the "Project:" tag with
# "Working on:"
#
sed -e 's/^Project:$/Working on:/g'
    Then when `finger -l bson@gnu.ai.mit.edu' is run, the output could look something like:
    Jan Brittenson (bson)
Home: /home/fsf/bson
Shell: /usr/local/bin/bash
No mail.

Jan Brittenson (bson) is not presently logged in.
Last seen at wombat.gnu.ai.mit.edu on Tue Sep  1 15:08:12 1992

No plan.

Working on:
        1. Hacking GNU Finger
        2. Making friends

User-defined Targets

Various special targets can be added as executable files in the directory `fingerdir/targets'. Each file name in this directory starts with a letter describing when to execute it, followed by a hyphen and the target name. The three letters are:

`l'
In response to a "long" finger; usually by typing `finger -l'.
`s'
In response to a "short" finger; usually the default if no options are given.
`x'
In response to either a "long" or "short" request.

For instance, the special-target file `x-.help' is run for either `finger .help' or `finger -l .help', whereas the special- target file `l-prices' is run only for `finger -l prices'.

The special-target file is run as super-user, and is given no input. By convention, all GNU Finger sites should support at least:

`.help'
Display message describing what features and special targets exist on this site.
`.site'
Display message describing the site. This may include such things as the company name, its address, and how to contact the system manager.

How Finger Picks a Port

When invoked, the GNU Finger client looks to see if a `--port' option was specified on the command line. If so, then this becomes the port number or service used. Otherwise, the client looks to see what name it was started under, removes any leading directory path, and any trailing suffixes. A suffix is the part of a filename that follows a dot, including the dot itself. This is the service name used. For instance, if GNU Finger is installed as `/usr/local/bin/finger.new', then the service `finger' is used. If it's installed as `/usr/local/bin/gfinger', then the service `gfinger' is used. This behavior can be changed by the system administrator during installation.

Security Issues

One question that often arises when installing networking software which adds new functionality is whether it can be considered sufficiently secure. The most significant new function in GNU Finger with regard to security is the ability for a user to have a `.fingerrc' in the home directory. The following are the precautions take by GNU Finger:

  • Check whether `.fingerrc' is writable to anyone except the owner. Notice that check is not enabled by default, since FSF users like anyone to be able to write any file -- enable this check during installation by editing `config.h'.
  • Check whether `.fingerrc' is owned by the user in whose home directory it's found. This, like the previous check, is disabled by default. It really only makes sense on systems where ordinary users can't give away their files.
  • Execute the script through the user's login shell, using the command "shell -c script". This means that a user who has had his account disabled (i.e. shell set to a program that prints a notice or just dies) can't run a `.fingerrc' script. This behavior can be changed by hard-coding the shell in `config.h'.

Bug Reports

You are strongly encouraged to submit a bug report to bug-gnu-utils@gnu.ai.mit.edu if you have problems with this beta release of GNU Finger. Here are some things that are generally helpful to mention, when relevant:

  • The GNU Finger version and where you obtained the distribution.
  • Your hardware.
  • Operating system.
  • C Compiler used.
  • The arguments you gave to `./configure'.
  • Changes you made to the GNU Finger configuration files.
  • Any changes you have made to the source code or installation procedures.
  • Your network configuration; don't forget to mention what hardware, operating systems, and C compilers are used on each node where the bug manifests itself.
  • Any problems you had during installation.

If you're having problems compiling or installing GNU Finger, then the following is particularly helpful to mention:

  • The command line used to invoke configure.
  • The current directory.
  • The command line used to invoke make and make version (particularly if you're using GNU Make).
  • A capture of the compiler output.

Please feel free to include any patches, as well.

Installation

Basic Installation

Here are the steps that you will need to take in order to install GNU Finger.

  1. Pick a machine which will be the local finger server for your network. Create a `clients' file, and install it in `/usr/local/etc/fingerdir' (or the EtcDir as specified in `config.h'). Put the names of all hosts that should report to the finger server in this file. Don't forget to include the finger server itself.
  2. For each client (the designated server is also a client), do the following,
  3. Change your working directory to be the top of the GNU Finger sources. For instance, if you have placed the source in `/src/gnu/finger' you would type `cd /src/gnu/finger'.
  4. In the source directory, type `make clean' and `./configure' if this host is different from the previous one. If you're using csh on an old version of System V, you might need to type `sh ./configure' instead to prevent csh from trying to execute configure itself. The configure shell script attempts to guess correct values for various system-dependent variables used during compilation, and creates the Makefile(s) (one in each subdirectory of the source directory). In some packages it creates a C header file containing system-dependent definitions. It also creates a file `config.status' that you can run in the future to recreate the current configuration. Running configure takes a minute or two. While it is running, it prints some messages that tell what it is doing. If you don't want to see the messages, run configure with its standard output redirected to `/dev/null'; for example, `./configure >/dev/null'. To compile the package in a different directory from the one containing the source code, you must use a version of make that supports the VPATH variable, such as GNU make. `cd' to the directory where you want the object files and executables to go and run configure. configure automatically checks for the source code in the directory that configure is in and in `..'. If for some reason configure is not in the source code directory that you are configuring, then it will report that it can't find the source code. In that case, run configure with the option `--srcdir=DIR', where DIR is the directory that contains the source code. You can tell `configure' to figure out the configuration for your system, and record it in `config.status', without actually configuring the package (creating `Makefile' and perhaps a configuration header file). To do this, give configure the `--no-create' option. Later, you can run ./config.status to actually configure the package for a particular host. This option is useful mainly in `Makefile' rules for updating `config.status' and `Makefile'. You can also give `config.status' the `--recheck' option, which makes it re-run configure with the same arguments you used before. This is useful if you change configure. `configure' ignores any other arguments that you give it. If you want to install the GNU Finger configuration files somewhere other than `/usr/local/etc/fingerdir', then you should edit the files `./config.h' and `include/fingerpaths.h' now. You need to specify the alternate locations of where the configuration files will be kept. If you want to include the unsupported code for mugshots, then you should now also choose one of the face formats, as well as edit `lib/Makefile.in', `lib/site/Makefile.in', and `src/Makefile.in' to compile and link in the files necessary. If your system requires unusual options for compilation or linking that configure doesn't know about, you can give configure initial values for some variables by setting them in the environment. In Bourne-compatible shells, you can do that on the command line like this:
    CC='gcc -traditional' DEFS=-D_POSIX_SOURCE ./configure
    The `make' variables that you might want to override with environment variables when running configure are: (For these variables, any value given in the environment overrides the value that `configure' would choose:)
    CC
    C compiler program. Default is `cc', or `gcc' if `gcc' is in your search path.
    INSTALL
    Program to use to install files. Default is `install' if you have it, `cp' otherwise.
    (For these variables, any value given in the environment is added to the value that `configure' chooses:)
    DEFS
    Configuration options, in the form `-Dfoo -Dbar ...'
    LIBS
    Libraries to link with, in the form `-lfoo -lbar ...'
  5. To build and/or install the GNU Finger executables and standard targets, issue one of the following commands:
    `make server'
    To build and install all executables, plus install the finger-specific server configuration files. Use this if the host is the designated finger server.
    `make client'
    To build all executables, but install only those used by the non-server clients. Use this unless the host is the designated finger server.
    `make all'
    To build all executables, but perform no installation.
    The above commands build `lib/libfinger.a' and the main programs in `src': finger, in.fingerd, and in.cfingerd, as well as fingerd on the server. If you want to, you can override the `make' variables CFLAGS and LDFLAGS like this:
    make CFLAGS=-O2 LDFLAGS=-s
  6. Modify the system configuration so that the client has (refer to the system documentation for details on how to do this on a particular system):
    • Entries in the system `services' file, or equivalent, which mentions the correct TCP port for in.cfingerd (port 2003) and in.fingerd (port 79). If port 2003 is already used by something else, then read the section on Configuration Files for details on how to specify a port other than 2003 in the `/usr/local/etc/fingerdir/clients' file. A good name for the service is `cfinger'.
    • Entries in the system `inetd.conf' file, or equivalent, which contains references to in.cfingerd and in.fingerd. in.fingerd needs to be run with UID root. Consult your system documentation for details on how to do this. in.cfingerd should be run with UID root on System V derivatives.
    • a `/usr/local/etc/fingerdir/serverhost' file which contains the name of the GNU Finger server host,
    • a `/usr/local/etc/fingerdir/mailhost' file which contains the name of the mail server to ask for user mail forwarding information and mailing list expansion, and
    • the inetd daemon restarted, so that server and user requests can be answered.
  7. When you have performed the above steps for each client, log onto the designated GNU Finger server.
  8. Start the server daemon, fingerd. You should arrange to have fingerd started every time the server host is rebooted. For exact details on how to do this, please refer to the server host's system documentation.
  9. If you chose to include the mugshots option, now might be a good time to install the mugshots. But first, try getting a face from another site running GNU Finger! For example, you might try
    finger --face bfox@aurel.cns.caltech.edu
  10. Modify the files `x-.help' and `x-.site' in `/usr/local/etc/fingerdir/targets' for your site.

Now you're all set! You might like to read through the section on Configuration Files.

Configuration Files

This section describes the format of the GNU Finger configuration files.

The `clients' file

The `/usr/local/etc/fingerdir/clients' file contains a list of clients that the GNU Finger server fingerd is supposed to poll. You can edit this file and then send the finger server a SIGHUP to tell it that the configuration has changed. Each line in the file should be either the name of a host or a comment. The name can be preceded by @port, to tell the finger server to poll the particular host by using a port other than 2003. A comment is any line that starts with a hash sign (#). Below is a sample `clients' file:

# This file contains all GNU Finger clients on the gnu.ai.mit.edu
# network. Apple-gunkies is the GNU Finger server (see ``serverhost'').
apple-gunkies.gnu.ai.mit.edu

# Albert is the mail exchanger (see ``mailhost'').
albert.gnu.ai.mit.edu

# Spiff is a Sony, so port 2003 is already used for `mbanks'.
# Use port 2010 instead.
@2010 spiff.gnu.ai.mit.edu

churchy.gnu.ai.mit.edu
mole.gnu.ai.mit.edu
geech.gnu.ai.mit.edu
wookumz.gnu.ai.mit.edu
nutrimat.gnu.ai.mit.edu
kropotkin.gnu.ai.mit.edu
goldman.gnu.ai.mit.edu
hal.gnu.ai.mit.edu
wombat.gnu.ai.mit.edu

Although this sample `clients' file contains the fully qualified domain names of the hosts, it's usually enough to specify only the host name portion. Explicit IP addresses can be used too, but this is a practise strongly discouraged. Notice that the server is also in the clients file and has a in.cfingerd; this is necessary in order for the server to correctly poll itself.

The `serverhost' file

The `/usr/local/etc/fingerdir/serverhost' file holds the name of the GNU Finger server host; this is as the name implies, the host that the GNU Finger server fingerd runs on. Lines starting with a hash sign (#) are treated as comments. Below is a sample `serverhost' file:

# A-g does all the finger stuff
apple-gunkies.gnu.ai.mit.edu

The `mailhost' file

The `/usr/local/etc/fingerdir/mailhost' file holds the name of the mail exchanger host for the network. This host should know how to talk SMTP; this file should never hold the name of a host that can't. It's contacted to obtain mail forwarding information and to expand mailing lists if a `.forward' file can't be found in the user's home directory. GNU Finger always looks and reports on user `.forward' files regardless of whether `mailhost' exists or not. Any lines in this file that start with a hash sign (#) are treated as comments.

The `forwardhost' file

The `/usr/local/etc/fingerdir/forwardhost' file holds the name of the host to forward finger requests to when the current finger server can't find a matching user name or mail alias. No forwarding takes place if this file doesn't exist. Any lines that start with a hash sign (#) are treated as comments. This is a sample output of what it can look like when a request is forwarded:

% finger -l nosuchuser@gnu.ai.mit.edu
[No user nosuchuser@apple-gunkies.gnu.ai.mit.edu, forwarding
 request to life.ai.mit.edu]
Login name: nosuchuser			In real life: ???

The `ttylocs' file

The `/usr/local/etc/fingerdir/ttylocs' file holds explanations for the hosts or terminal lines that users have logged in from or through. Each client host has its own copy of this file. Each line consists of a host name followed by a description. The name and description are separated by one or more blanks or TABs.

spiff.gnu.ai.mit.edu            NE43 Hall
susie.gnu.ai.mit.edu            NE43 Sony 427 x8568
spike.gnu.ai.mit.edu            NE43 Sony 427 x8568
apple-gunkies.gnu.ai.mit.edu    NE43 427
sugar-bombs.gnu.ai.mit.edu      Elsewhere
pogo.gnu.ai.mit.edu             NE43 447
albert.gnu.ai.mit.edu           Noisy Machine Room
128.52.46.42                    The salt mines
churchy.gnu.ai.mit.edu          NE43 426
mole.gnu.ai.mit.edu             NE43 430
geech.gnu.ai.mit.edu            NE43 426
wookumz.gnu.ai.mit.edu          NE43 427
calvin.gnu.ai.mit.edu           NE43
gnu.gnu.ai.mit.edu              NE43
kropotkin.gnu.ai.mit.edu        Total anarchy

Site Specific Functions

If you are interested in customizing GNU Finger's output, then the `lib/site' directory is the right place to start. If you would like to add new code for displaying faces, or have a particularly interesting "long" information output format, I would be glad to include it as unsupported code in the next release of GNU Finger. (I will direct correspondence regarding your code to you.) You can find other contributed code in `lib/site', most notably different user info formats and code to handle different bit map file formats. The only file supported in `lib/site' is `userinfo.c'.

Configuration Options

The following definitions in `config.h' control the behavior of GNU Finger:

SUPPORT_FINGERRC
Undefine to prevent users from writing `.fingerrc' scripts. Defined by default.
CHECK_OWNER_FINGERRC
Define to make sure `.fingerrc' is owned by the user in whose directory it's found.
CHECK_RDONLY_FINGERRC
Define to make sure `.fingerrc' isn't writable by anyone other than its owner.
FINGERRC_SHELL
The shell to use to execute `.fingerrc'. Undefine to use user's login shell.
DEFAULT_POLL_INTERVAL
Define to be the delay between polls, in seconds, unless an interval is explicitly given to fingerd with the `--interval' option.
BASENAME_IS_SERVICE
Undefine if you always want the finger client to use the `finger' service. Otherwise the service is deduced from the basename of the client. Defined by default.
INFO_IS_DEFAULT
Define if you prefer `finger --info' to be the default, undefine if you prefer `finger --brief' to be the default.

GNU Finger Quick Reference

finger options user@host

Finger obtains information about user on the remote system host. It can also be used to obtain information about mailing lists and special site-specific services.

Options can be one or more of:

`--info'
`-i'
`-l'
Return as much information as possible about user.
`--brief'
`-b'
`-s'
Only display current login info.
`--face'
`-f'
Display a mugshot of user. Not supported.
`--port port#'
`-P port#'
Connect to the finger server using port or service port#.

This document was generated on 7 November 1998 using the texi2html translator version 1.52.


Flex - a scanner generator

Flex, version 2.5

A fast scanner generator

Edition 2.5, March 1995

Vern Paxson

Table of Contents

    • Name
    • Synopsis
    • Overview
    • Description
    • Some simple examples
    • Format of the input file
    • Patterns
    • How the input is matched
    • Actions
    • The generated scanner
    • Start conditions
    • Multiple input buffers
    • End-of-file rules
    • Miscellaneous macros
    • Values available to the user
    • Interfacing with yacc
    • Options
    • Performance considerations
    • Generating C++ scanners
    • Incompatibilities with lex and POSIX
    • Diagnostics
    • Files
    • Deficiencies / Bugs
    • See also
    • Author

Copyright (C) 1990 The Regents of the University of California. All rights reserved.

This code is derived from software contributed to Berkeley by Vern Paxson.

The United States Government has rights in this work pursuant to contract no. DE-AC03-76SF00098 between the United States Department of Energy and the University of California.

Redistribution and use in source and binary forms with or without modification are permitted provided that: (1) source distributions retain this entire copyright notice and comment, and (2) distributions including binaries display the following acknowledgement: "This product includes software developed by the University of California, Berkeley and its contributors" in the documentation or other materials provided with the distribution and in all advertising materials mentioning features or use of this software. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Name

flex - fast lexical analyzer generator

Synopsis

flex [-bcdfhilnpstvwBFILTV78+? -C[aefFmr] -ooutput -Pprefix -Sskeleton]
[--help --version] [filename ...]

Overview

This manual describes flex, a tool for generating programs that perform pattern-matching on text. The manual includes both tutorial and reference sections:

Description
a brief overview of the tool
Some Simple Examples
Format Of The Input File
Patterns
the extended regular expressions used by flex
How The Input Is Matched
the rules for determining what has been matched
Actions
how to specify what to do when a pattern is matched
The Generated Scanner
details regarding the scanner that flex produces; how to control the input source
Start Conditions
introducing context into your scanners, and managing "mini-scanners"
Multiple Input Buffers
how to manipulate multiple input sources; how to scan from strings instead of files
End-of-file Rules
special rules for matching the end of the input
Miscellaneous Macros
a summary of macros available to the actions
Values Available To The User
a summary of values available to the actions
Interfacing With Yacc
connecting flex scanners together with yacc parsers
Options
flex command-line options, and the "%option" directive
Performance Considerations
how to make your scanner go as fast as possible
Generating C++ Scanners
the (experimental) facility for generating C++ scanner classes
Incompatibilities With Lex And POSIX
how flex differs from AT&T lex and the POSIX lex standard
Diagnostics
those error messages produced by flex (or scanners it generates) whose meanings might not be apparent
Files
files used by flex
Deficiencies / Bugs
known problems with flex
See Also
other documentation, related tools
Author
includes contact information

Description

flex is a tool for generating scanners: programs which recognized lexical patterns in text. flex reads the given input files, or its standard input if no file names are given, for a description of a scanner to generate. The description is in the form of pairs of regular expressions and C code, called rules. flex generates as output a C source file, `lex.yy.c', which defines a routine `yylex()'. This file is compiled and linked with the `-lfl' library to produce an executable. When the executable is run, it analyzes its input for occurrences of the regular expressions. Whenever it finds one, it executes the corresponding C code.

Some simple examples

First some simple examples to get the flavor of how one uses flex. The following flex input specifies a scanner which whenever it encounters the string "username" will replace it with the user's login name:

%%
username    printf( "%s", getlogin() );

By default, any text not matched by a flex scanner is copied to the output, so the net effect of this scanner is to copy its input file to its output with each occurrence of "username" expanded. In this input, there is just one rule. "username" is the pattern and the "printf" is the action. The "%%" marks the beginning of the rules.

Here's another simple example:

        int num_lines = 0, num_chars = 0;

%%
\n      ++num_lines; ++num_chars;
.       ++num_chars;

%%
main()
        {
        yylex();
        printf( "# of lines = %d, # of chars = %d\n",
                num_lines, num_chars );
        }

This scanner counts the number of characters and the number of lines in its input (it produces no output other than the final report on the counts). The first line declares two globals, "num_lines" and "num_chars", which are accessible both inside `yylex()' and in the `main()' routine declared after the second "%%". There are two rules, one which matches a newline ("\n") and increments both the line count and the character count, and one which matches any character other than a newline (indicated by the "." regular expression).

A somewhat more complicated example:

/* scanner for a toy Pascal-like language */

%{
/* need this for the call to atof() below */
#include <math.h>
%}

DIGIT    [0-9]
ID       [a-z][a-z0-9]*

%%

{DIGIT}+    {
            printf( "An integer: %s (%d)\n", yytext,
                    atoi( yytext ) );
            }

{DIGIT}+"."{DIGIT}*        {
            printf( "A float: %s (%g)\n", yytext,
                    atof( yytext ) );
            }

if|then|begin|end|procedure|function        {
            printf( "A keyword: %s\n", yytext );
            }

{ID}        printf( "An identifier: %s\n", yytext );

"+"|"-"|"*"|"/"   printf( "An operator: %s\n", yytext );

"{"[^}\n]*"}"     /* eat up one-line comments */

[ \t\n]+          /* eat up whitespace */

.           printf( "Unrecognized character: %s\n", yytext );

%%

main( argc, argv )
int argc;
char **argv;
    {
    ++argv, --argc;  /* skip over program name */
    if ( argc > 0 )
            yyin = fopen( argv[0], "r" );
    else
            yyin = stdin;

    yylex();
    }

This is the beginnings of a simple scanner for a language like Pascal. It identifies different types of tokens and reports on what it has seen.

The details of this example will be explained in the following sections.

Format of the input file

The flex input file consists of three sections, separated by a line with just `%%' in it:

definitions
%%
rules
%%
user code

The definitions section contains declarations of simple name definitions to simplify the scanner specification, and declarations of start conditions, which are explained in a later section. Name definitions have the form:

name definition

The "name" is a word beginning with a letter or an underscore ('_') followed by zero or more letters, digits, '_', or '-' (dash). The definition is taken to begin at the first non-white-space character following the name and continuing to the end of the line. The definition can subsequently be referred to using "{name}", which will expand to "(definition)". For example,

DIGIT    [0-9]
ID       [a-z][a-z0-9]*

defines "DIGIT" to be a regular expression which matches a single digit, and "ID" to be a regular expression which matches a letter followed by zero-or-more letters-or-digits. A subsequent reference to

{DIGIT}+"."{DIGIT}*

is identical to

([0-9])+"."([0-9])*

and matches one-or-more digits followed by a '.' followed by zero-or-more digits.

The rules section of the flex input contains a series of rules of the form:

pattern   action

where the pattern must be unindented and the action must begin on the same line.

See below for a further description of patterns and actions.

Finally, the user code section is simply copied to `lex.yy.c' verbatim. It is used for companion routines which call or are called by the scanner. The presence of this section is optional; if it is missing, the second `%%' in the input file may be skipped, too.

In the definitions and rules sections, any indented text or text enclosed in `%{' and `%}' is copied verbatim to the output (with the `%{}''s removed). The `%{}''s must appear unindented on lines by themselves.

In the rules section, any indented or %{} text appearing before the first rule may be used to declare variables which are local to the scanning routine and (after the declarations) code which is to be executed whenever the scanning routine is entered. Other indented or %{} text in the rule section is still copied to the output, but its meaning is not well-defined and it may well cause compile-time errors (this feature is present for POSIX compliance; see below for other such features).

In the definitions section (but not in the rules section), an unindented comment (i.e., a line beginning with "/*") is also copied verbatim to the output up to the next "*/".

Patterns

The patterns in the input are written using an extended set of regular expressions. These are:

`x'
match the character `x'
`.'
any character (byte) except newline
`[xyz]'
a "character class"; in this case, the pattern matches either an `x', a `y', or a `z'
`[abj-oZ]'
a "character class" with a range in it; matches an `a', a `b', any letter from `j' through `o', or a `Z'
`[^A-Z]'
a "negated character class", i.e., any character but those in the class. In this case, any character EXCEPT an uppercase letter.
`[^A-Z\n]'
any character EXCEPT an uppercase letter or a newline
`r*'
zero or more r's, where r is any regular expression
`r+'
one or more r's
`r?'
zero or one r's (that is, "an optional r")
`r{2,5}'
anywhere from two to five r's
`r{2,}'
two or more r's
`r{4}'
exactly 4 r's
`{name}'
the expansion of the "name" definition (see above)
`"[xyz]\"foo"'
the literal string: `[xyz]"foo'
`\x'
if x is an `a', `b', `f', `n', `r', `t', or `v', then the ANSI-C interpretation of \x. Otherwise, a literal `x' (used to escape operators such as `*')
`\0'
a NUL character (ASCII code 0)
`\123'
the character with octal value 123
`\x2a'
the character with hexadecimal value 2a
`(r)'
match an r; parentheses are used to override precedence (see below)
`rs'
the regular expression r followed by the regular expression s; called "concatenation"
`r|s'
either an r or an s
`r/s'
an r but only if it is followed by an s. The text matched by s is included when determining whether this rule is the longest match, but is then returned to the input before the action is executed. So the action only sees the text matched by r. This type of pattern is called trailing context. (There are some combinations of `r/s' that flex cannot match correctly; see notes in the Deficiencies / Bugs section below regarding "dangerous trailing context".)
`^r'
an r, but only at the beginning of a line (i.e., which just starting to scan, or right after a newline has been scanned).
`r$'
an r, but only at the end of a line (i.e., just before a newline). Equivalent to "r/\n". Note that flex's notion of "newline" is exactly whatever the C compiler used to compile flex interprets '\n' as; in particular, on some DOS systems you must either filter out \r's in the input yourself, or explicitly use r/\r\n for "r$".
`<s>r'
an r, but only in start condition s (see below for discussion of start conditions) <s1,s2,s3>r same, but in any of start conditions s1, s2, or s3
`<*>r'
an r in any start condition, even an exclusive one.
`<<EOF>>'
an end-of-file
`<s1,s2><<EOF>>'
an end-of-file when in start condition s1 or s2

Note that inside of a character class, all regular expression operators lose their special meaning except escape ('\') and the character class operators, '-', ']', and, at the beginning of the class, '^'.

The regular expressions listed above are grouped according to precedence, from highest precedence at the top to lowest at the bottom. Those grouped together have equal precedence. For example,

foo|bar*

is the same as

(foo)|(ba(r*))

since the '*' operator has higher precedence than concatenation, and concatenation higher than alternation ('|'). This pattern therefore matches either the string "foo" or the string "ba" followed by zero-or-more r's. To match "foo" or zero-or-more "bar"'s, use:

foo|(bar)*

and to match zero-or-more "foo"'s-or-"bar"'s:

(foo|bar)*

In addition to characters and ranges of characters, character classes can also contain character class expressions. These are expressions enclosed inside `[': and `:'] delimiters (which themselves must appear between the '[' and ']' of the character class; other elements may occur inside the character class, too). The valid expressions are:

[:alnum:] [:alpha:] [:blank:]
[:cntrl:] [:digit:] [:graph:]
[:lower:] [:print:] [:punct:]
[:space:] [:upper:] [:xdigit:]

These expressions all designate a set of characters equivalent to the corresponding standard C `isXXX' function. For example, `[:alnum:]' designates those characters for which `isalnum()' returns true - i.e., any alphabetic or numeric. Some systems don't provide `isblank()', so flex defines `[:blank:]' as a blank or a tab.

For example, the following character classes are all equivalent:

[[:alnum:]]
[[:alpha:][:digit:]
[[:alpha:]0-9]
[a-zA-Z0-9]

If your scanner is case-insensitive (the `-i' flag), then `[:upper:]' and `[:lower:]' are equivalent to `[:alpha:]'.

Some notes on patterns:

  • A negated character class such as the example "[^A-Z]" above will match a newline unless "\n" (or an equivalent escape sequence) is one of the characters explicitly present in the negated character class (e.g., "[^A-Z\n]"). This is unlike how many other regular expression tools treat negated character classes, but unfortunately the inconsistency is historically entrenched. Matching newlines means that a pattern like [^"]* can match the entire input unless there's another quote in the input.
  • A rule can have at most one instance of trailing context (the '/' operator or the '$' operator). The start condition, '^', and "<<EOF>>" patterns can only occur at the beginning of a pattern, and, as well as with '/' and '$', cannot be grouped inside parentheses. A '^' which does not occur at the beginning of a rule or a '$' which does not occur at the end of a rule loses its special properties and is treated as a normal character. The following are illegal:
    foo/bar$
<sc1>foo<sc2>bar
    Note that the first of these, can be written "foo/bar\n". The following will result in '$' or '^' being treated as a normal character:
    foo|(bar$)
foo|^bar
    If what's wanted is a "foo" or a bar-followed-by-a-newline, the following could be used (the special '|' action is explained below):
    foo      |
bar$     /* action goes here */
    A similar trick will work for matching a foo or a bar-at-the-beginning-of-a-line.

How the input is matched

When the generated scanner is run, it analyzes its input looking for strings which match any of its patterns. If it finds more than one match, it takes the one matching the most text (for trailing context rules, this includes the length of the trailing part, even though it will then be returned to the input). If it finds two or more matches of the same length, the rule listed first in the flex input file is chosen.

Once the match is determined, the text corresponding to the match (called the token) is made available in the global character pointer yytext, and its length in the global integer yyleng. The action corresponding to the matched pattern is then executed (a more detailed description of actions follows), and then the remaining input is scanned for another match.

If no match is found, then the default rule is executed: the next character in the input is considered matched and copied to the standard output. Thus, the simplest legal flex input is:

%%

which generates a scanner that simply copies its input (one character at a time) to its output.

Note that yytext can be defined in two different ways: either as a character pointer or as a character array. You can control which definition flex uses by including one of the special directives `%pointer' or `%array' in the first (definitions) section of your flex input. The default is `%pointer', unless you use the `-l' lex compatibility option, in which case yytext will be an array. The advantage of using `%pointer' is substantially faster scanning and no buffer overflow when matching very large tokens (unless you run out of dynamic memory). The disadvantage is that you are restricted in how your actions can modify yytext (see the next section), and calls to the `unput()' function destroys the present contents of yytext, which can be a considerable porting headache when moving between different lex versions.

The advantage of `%array' is that you can then modify yytext to your heart's content, and calls to `unput()' do not destroy yytext (see below). Furthermore, existing lex programs sometimes access yytext externally using declarations of the form:

extern char yytext[];

This definition is erroneous when used with `%pointer', but correct for `%array'.

`%array' defines yytext to be an array of YYLMAX characters, which defaults to a fairly large value. You can change the size by simply #define'ing YYLMAX to a different value in the first section of your flex input. As mentioned above, with `%pointer' yytext grows dynamically to accommodate large tokens. While this means your `%pointer' scanner can accommodate very large tokens (such as matching entire blocks of comments), bear in mind that each time the scanner must resize yytext it also must rescan the entire token from the beginning, so matching such tokens can prove slow. yytext presently does not dynamically grow if a call to `unput()' results in too much text being pushed back; instead, a run-time error results.

Also note that you cannot use `%array' with C++ scanner classes (the c++ option; see below).

Actions

Each pattern in a rule has a corresponding action, which can be any arbitrary C statement. The pattern ends at the first non-escaped whitespace character; the remainder of the line is its action. If the action is empty, then when the pattern is matched the input token is simply discarded. For example, here is the specification for a program which deletes all occurrences of "zap me" from its input:

%%
"zap me"

(It will copy all other characters in the input to the output since they will be matched by the default rule.)

Here is a program which compresses multiple blanks and tabs down to a single blank, and throws away whitespace found at the end of a line:

%%
[ \t]+        putchar( ' ' );
[ \t]+$       /* ignore this token */

If the action contains a '{', then the action spans till the balancing '}' is found, and the action may cross multiple lines. flex knows about C strings and comments and won't be fooled by braces found within them, but also allows actions to begin with `%{' and will consider the action to be all the text up to the next `%}' (regardless of ordinary braces inside the action).

An action consisting solely of a vertical bar ('|') means "same as the action for the next rule." See below for an illustration.

Actions can include arbitrary C code, including return statements to return a value to whatever routine called `yylex()'. Each time `yylex()' is called it continues processing tokens from where it last left off until it either reaches the end of the file or executes a return.

Actions are free to modify yytext except for lengthening it (adding characters to its end--these will overwrite later characters in the input stream). This however does not apply when using `%array' (see above); in that case, yytext may be freely modified in any way.

Actions are free to modify yyleng except they should not do so if the action also includes use of `yymore()' (see below).

There are a number of special directives which can be included within an action:

  • `ECHO' copies yytext to the scanner's output.
  • BEGIN followed by the name of a start condition places the scanner in the corresponding start condition (see below).
  • REJECT directs the scanner to proceed on to the "second best" rule which matched the input (or a prefix of the input). The rule is chosen as described above in "How the Input is Matched", and yytext and yyleng set up appropriately. It may either be one which matched as much text as the originally chosen rule but came later in the flex input file, or one which matched less text. For example, the following will both count the words in the input and call the routine special() whenever "frob" is seen:
            int word_count = 0;
%%

frob        special(); REJECT;
[^ \t\n]+   ++word_count;
    Without the REJECT, any "frob"'s in the input would not be counted as words, since the scanner normally executes only one action per token. Multiple REJECT's are allowed, each one finding the next best choice to the currently active rule. For example, when the following scanner scans the token "abcd", it will write "abcdabcaba" to the output:
    %%
a        |
ab       |
abc      |
abcd     ECHO; REJECT;
.|\n     /* eat up any unmatched character */
    (The first three rules share the fourth's action since they use the special '|' action.) REJECT is a particularly expensive feature in terms of scanner performance; if it is used in any of the scanner's actions it will slow down all of the scanner's matching. Furthermore, REJECT cannot be used with the `-Cf' or `-CF' options (see below). Note also that unlike the other special actions, REJECT is a branch; code immediately following it in the action will not be executed.
  • `yymore()' tells the scanner that the next time it matches a rule, the corresponding token should be appended onto the current value of yytext rather than replacing it. For example, given the input "mega-kludge" the following will write "mega-mega-kludge" to the output:
    %%
mega-    ECHO; yymore();
kludge   ECHO;
    First "mega-" is matched and echoed to the output. Then "kludge" is matched, but the previous "mega-" is still hanging around at the beginning of yytext so the `ECHO' for the "kludge" rule will actually write "mega-kludge".

Two notes regarding use of `yymore()'. First, `yymore()' depends on the value of yyleng correctly reflecting the size of the current token, so you must not modify yyleng if you are using `yymore()'. Second, the presence of `yymore()' in the scanner's action entails a minor performance penalty in the scanner's matching speed.

  • `yyless(n)' returns all but the first n characters of the current token back to the input stream, where they will be rescanned when the scanner looks for the next match. yytext and yyleng are adjusted appropriately (e.g., yyleng will now be equal to n ). For example, on the input "foobar" the following will write out "foobarbar":
    %%
foobar    ECHO; yyless(3);
[a-z]+    ECHO;
    An argument of 0 to yyless will cause the entire current input string to be scanned again. Unless you've changed how the scanner will subsequently process its input (using BEGIN, for example), this will result in an endless loop. Note that yyless is a macro and can only be used in the flex input file, not from other source files.
  • `unput(c)' puts the character c back onto the input stream. It will be the next character scanned. The following action will take the current token and cause it to be rescanned enclosed in parentheses.
    {
int i;
/* Copy yytext because unput() trashes yytext */
char *yycopy = strdup( yytext );
unput( ')' );
for ( i = yyleng - 1; i >= 0; --i )
    unput( yycopy[i] );
unput( '(' );
free( yycopy );
}
    Note that since each `unput()' puts the given character back at the beginning of the input stream, pushing back strings must be done back-to-front. An important potential problem when using `unput()' is that if you are using `%pointer' (the default), a call to `unput()' destroys the contents of yytext, starting with its rightmost character and devouring one character to the left with each call. If you need the value of yytext preserved after a call to `unput()' (as in the above example), you must either first copy it elsewhere, or build your scanner using `%array' instead (see How The Input Is Matched). Finally, note that you cannot put back EOF to attempt to mark the input stream with an end-of-file.
  • `input()' reads the next character from the input stream. For example, the following is one way to eat up C comments:
    %%
"/*"        {
            register int c;

            for ( ; ; )
                {
                while ( (c = input()) != '*' &&
                        c != EOF )
                    ;    /* eat up text of comment */

                if ( c == '*' )
                    {
                    while ( (c = input()) == '*' )
                        ;
                    if ( c == '/' )
                        break;    /* found the end */
                    }

                if ( c == EOF )
                    {
                    error( "EOF in comment" );
                    break;
                    }
                }
            }
    (Note that if the scanner is compiled using `C++', then `input()' is instead referred to as `yyinput()', in order to avoid a name clash with the `C++' stream by the name of input.)
  • YY_FLUSH_BUFFER flushes the scanner's internal buffer so that the next time the scanner attempts to match a token, it will first refill the buffer using YY_INPUT (see The Generated Scanner, below). This action is a special case of the more general `yy_flush_buffer()' function, described below in the section Multiple Input Buffers.
  • `yyterminate()' can be used in lieu of a return statement in an action. It terminates the scanner and returns a 0 to the scanner's caller, indicating "all done". By default, `yyterminate()' is also called when an end-of-file is encountered. It is a macro and may be redefined.

The generated scanner

The output of flex is the file `lex.yy.c', which contains the scanning routine `yylex()', a number of tables used by it for matching tokens, and a number of auxiliary routines and macros. By default, `yylex()' is declared as follows:

int yylex()
    {
    ... various definitions and the actions in here ...
    }

(If your environment supports function prototypes, then it will be "int yylex( void )".) This definition may be changed by defining the "YY_DECL" macro. For example, you could use:

#define YY_DECL float lexscan( a, b ) float a, b;

to give the scanning routine the name lexscan, returning a float, and taking two floats as arguments. Note that if you give arguments to the scanning routine using a K&R-style/non-prototyped function declaration, you must terminate the definition with a semi-colon (`;').

Whenever `yylex()' is called, it scans tokens from the global input file yyin (which defaults to stdin). It continues until it either reaches an end-of-file (at which point it returns the value 0) or one of its actions executes a return statement.

If the scanner reaches an end-of-file, subsequent calls are undefined unless either yyin is pointed at a new input file (in which case scanning continues from that file), or `yyrestart()' is called. `yyrestart()' takes one argument, a `FILE *' pointer (which can be nil, if you've set up YY_INPUT to scan from a source other than yyin), and initializes yyin for scanning from that file. Essentially there is no difference between just assigning yyin to a new input file or using `yyrestart()' to do so; the latter is available for compatibility with previous versions of flex, and because it can be used to switch input files in the middle of scanning. It can also be used to throw away the current input buffer, by calling it with an argument of yyin; but better is to use YY_FLUSH_BUFFER (see above). Note that `yyrestart()' does not reset the start condition to INITIAL (see Start Conditions, below).

If `yylex()' stops scanning due to executing a return statement in one of the actions, the scanner may then be called again and it will resume scanning where it left off.

By default (and for purposes of efficiency), the scanner uses block-reads rather than simple `getc()' calls to read characters from yyin. The nature of how it gets its input can be controlled by defining the YY_INPUT macro. YY_INPUT's calling sequence is "YY_INPUT(buf,result,max_size)". Its action is to place up to max_size characters in the character array buf and return in the integer variable result either the number of characters read or the constant YY_NULL (0 on Unix systems) to indicate EOF. The default YY_INPUT reads from the global file-pointer "yyin".

A sample definition of YY_INPUT (in the definitions section of the input file):

%{
#define YY_INPUT(buf,result,max_size) \
    { \
    int c = getchar(); \
    result = (c == EOF) ? YY_NULL : (buf[0] = c, 1); \
    }
%}

This definition will change the input processing to occur one character at a time.

When the scanner receives an end-of-file indication from YY_INPUT, it then checks the `yywrap()' function. If `yywrap()' returns false (zero), then it is assumed that the function has gone ahead and set up yyin to point to another input file, and scanning continues. If it returns true (non-zero), then the scanner terminates, returning 0 to its caller. Note that in either case, the start condition remains unchanged; it does not revert to INITIAL.

If you do not supply your own version of `yywrap()', then you must either use `%option noyywrap' (in which case the scanner behaves as though `yywrap()' returned 1), or you must link with `-lfl' to obtain the default version of the routine, which always returns 1.

Three routines are available for scanning from in-memory buffers rather than files: `yy_scan_string()', `yy_scan_bytes()', and `yy_scan_buffer()'. See the discussion of them below in the section Multiple Input Buffers.

The scanner writes its `ECHO' output to the yyout global (default, stdout), which may be redefined by the user simply by assigning it to some other FILE pointer.

Start conditions

flex provides a mechanism for conditionally activating rules. Any rule whose pattern is prefixed with "<sc>" will only be active when the scanner is in the start condition named "sc". For example,

<STRING>[^"]*        { /* eat up the string body ... */
            ...
            }

will be active only when the scanner is in the "STRING" start condition, and

<INITIAL,STRING,QUOTE>\.        { /* handle an escape ... */
            ...
            }

will be active only when the current start condition is either "INITIAL", "STRING", or "QUOTE".

Start conditions are declared in the definitions (first) section of the input using unindented lines beginning with either `%s' or `%x' followed by a list of names. The former declares inclusive start conditions, the latter exclusive start conditions. A start condition is activated using the BEGIN action. Until the next BEGIN action is executed, rules with the given start condition will be active and rules with other start conditions will be inactive. If the start condition is inclusive, then rules with no start conditions at all will also be active. If it is exclusive, then only rules qualified with the start condition will be active. A set of rules contingent on the same exclusive start condition describe a scanner which is independent of any of the other rules in the flex input. Because of this, exclusive start conditions make it easy to specify "mini-scanners" which scan portions of the input that are syntactically different from the rest (e.g., comments).

If the distinction between inclusive and exclusive start conditions is still a little vague, here's a simple example illustrating the connection between the two. The set of rules:

%s example
%%

<example>foo   do_something();

bar            something_else();

is equivalent to

%x example
%%

<example>foo   do_something();

<INITIAL,example>bar    something_else();

Without the `<INITIAL,example>' qualifier, the `bar' pattern in the second example wouldn't be active (i.e., couldn't match) when in start condition `example'. If we just used `<example>' to qualify `bar', though, then it would only be active in `example' and not in INITIAL, while in the first example it's active in both, because in the first example the `example' starting condition is an inclusive (`%s') start condition.

Also note that the special start-condition specifier `<*>' matches every start condition. Thus, the above example could also have been written;

%x example
%%

<example>foo   do_something();

<*>bar    something_else();

The default rule (to `ECHO' any unmatched character) remains active in start conditions. It is equivalent to:

<*>.|\\n     ECHO;

`BEGIN(0)' returns to the original state where only the rules with no start conditions are active. This state can also be referred to as the start-condition "INITIAL", so `BEGIN(INITIAL)' is equivalent to `BEGIN(0)'. (The parentheses around the start condition name are not required but are considered good style.)

BEGIN actions can also be given as indented code at the beginning of the rules section. For example, the following will cause the scanner to enter the "SPECIAL" start condition whenever `yylex()' is called and the global variable enter_special is true:

        int enter_special;

%x SPECIAL
%%
        if ( enter_special )
            BEGIN(SPECIAL);

<SPECIAL>blahblahblah
...more rules follow...

To illustrate the uses of start conditions, here is a scanner which provides two different interpretations of a string like "123.456". By default it will treat it as as three tokens, the integer "123", a dot ('.'), and the integer "456". But if the string is preceded earlier in the line by the string "expect-floats" it will treat it as a single token, the floating-point number 123.456:

%{
#include <math.h>
%}
%s expect

%%
expect-floats        BEGIN(expect);

<expect>[0-9]+"."[0-9]+      {
            printf( "found a float, = %f\n",
                    atof( yytext ) );
            }
<expect>\n           {
            /* that's the end of the line, so
             * we need another "expect-number"
             * before we'll recognize any more
             * numbers
             */
            BEGIN(INITIAL);
            }

[0-9]+      {

Version 2.5               December 1994                        18

            printf( "found an integer, = %d\n",
                    atoi( yytext ) );
            }

"."         printf( "found a dot\n" );

Here is a scanner which recognizes (and discards) C comments while maintaining a count of the current input line.

%x comment
%%
        int line_num = 1;

"/*"         BEGIN(comment);

<comment>[^*\n]*        /* eat anything that's not a '*' */
<comment>"*"+[^*/\n]*   /* eat up '*'s not followed by '/'s */
<comment>\n             ++line_num;
<comment>"*"+"/"        BEGIN(INITIAL);

This scanner goes to a bit of trouble to match as much text as possible with each rule. In general, when attempting to write a high-speed scanner try to match as much possible in each rule, as it's a big win.

Note that start-conditions names are really integer values and can be stored as such. Thus, the above could be extended in the following fashion:

%x comment foo
%%
        int line_num = 1;
        int comment_caller;

"/*"         {
             comment_caller = INITIAL;
             BEGIN(comment);
             }

...

<foo>"/*"    {
             comment_caller = foo;
             BEGIN(comment);
             }

<comment>[^*\n]*        /* eat anything that's not a '*' */
<comment>"*"+[^*/\n]*   /* eat up '*'s not followed by '/'s */
<comment>\n             ++line_num;
<comment>"*"+"/"        BEGIN(comment_caller);

Furthermore, you can access the current start condition using the integer-valued YY_START macro. For example, the above assignments to comment_caller could instead be written

comment_caller = YY_START;

Flex provides YYSTATE as an alias for YY_START (since that is what's used by AT&T lex).

Note that start conditions do not have their own name-space; %s's and %x's declare names in the same fashion as #define's.

Finally, here's an example of how to match C-style quoted strings using exclusive start conditions, including expanded escape sequences (but not including checking for a string that's too long):

%x str

%%
        char string_buf[MAX_STR_CONST];
        char *string_buf_ptr;

\"      string_buf_ptr = string_buf; BEGIN(str);

<str>\"        { /* saw closing quote - all done */
        BEGIN(INITIAL);
        *string_buf_ptr = '\0';
        /* return string constant token type and
         * value to parser
         */
        }

<str>\n        {
        /* error - unterminated string constant */
        /* generate error message */
        }

<str>\\[0-7]{1,3} {
        /* octal escape sequence */
        int result;

        (void) sscanf( yytext + 1, "%o", &result );

        if ( result > 0xff )
                /* error, constant is out-of-bounds */

        *string_buf_ptr++ = result;
        }

<str>\\[0-9]+ {
        /* generate error - bad escape sequence; something
         * like '\48' or '\0777777'
         */
        }

<str>\\n  *string_buf_ptr++ = '\n';
<str>\\t  *string_buf_ptr++ = '\t';
<str>\\r  *string_buf_ptr++ = '\r';
<str>\\b  *string_buf_ptr++ = '\b';
<str>\\f  *string_buf_ptr++ = '\f';

<str>\\(.|\n)  *string_buf_ptr++ = yytext[1];

<str>[^\\\n\"]+        {
        char *yptr = yytext;

        while ( *yptr )
                *string_buf_ptr++ = *yptr++;
        }

Often, such as in some of the examples above, you wind up writing a whole bunch of rules all preceded by the same start condition(s). Flex makes this a little easier and cleaner by introducing a notion of start condition scope. A start condition scope is begun with:

<SCs>{

where SCs is a list of one or more start conditions. Inside the start condition scope, every rule automatically has the prefix `<SCs>' applied to it, until a `}' which matches the initial `{'. So, for example,

<ESC>{
    "\\n"   return '\n';
    "\\r"   return '\r';
    "\\f"   return '\f';
    "\\0"   return '\0';
}

is equivalent to:

<ESC>"\\n"  return '\n';
<ESC>"\\r"  return '\r';
<ESC>"\\f"  return '\f';
<ESC>"\\0"  return '\0';

Start condition scopes may be nested.

Three routines are available for manipulating stacks of start conditions:

`void yy_push_state(int new_state)'
pushes the current start condition onto the top of the start condition stack and switches to new_state as though you had used `BEGIN new_state' (recall that start condition names are also integers).
`void yy_pop_state()'
pops the top of the stack and switches to it via BEGIN.
`int yy_top_state()'
returns the top of the stack without altering the stack's contents.

The start condition stack grows dynamically and so has no built-in size limitation. If memory is exhausted, program execution aborts.

To use start condition stacks, your scanner must include a `%option stack' directive (see Options below).

Multiple input buffers

Some scanners (such as those which support "include" files) require reading from several input streams. As flex scanners do a large amount of buffering, one cannot control where the next input will be read from by simply writing a YY_INPUT which is sensitive to the scanning context. YY_INPUT is only called when the scanner reaches the end of its buffer, which may be a long time after scanning a statement such as an "include" which requires switching the input source.

To negotiate these sorts of problems, flex provides a mechanism for creating and switching between multiple input buffers. An input buffer is created by using:

YY_BUFFER_STATE yy_create_buffer( FILE *file, int size )

which takes a FILE pointer and a size and creates a buffer associated with the given file and large enough to hold size characters (when in doubt, use YY_BUF_SIZE for the size). It returns a YY_BUFFER_STATE handle, which may then be passed to other routines (see below). The YY_BUFFER_STATE type is a pointer to an opaque struct yy_buffer_state structure, so you may safely initialize YY_BUFFER_STATE variables to `((YY_BUFFER_STATE) 0)' if you wish, and also refer to the opaque structure in order to correctly declare input buffers in source files other than that of your scanner. Note that the FILE pointer in the call to yy_create_buffer is only used as the value of yyin seen by YY_INPUT; if you redefine YY_INPUT so it no longer uses yyin, then you can safely pass a nil FILE pointer to yy_create_buffer. You select a particular buffer to scan from using:

void yy_switch_to_buffer( YY_BUFFER_STATE new_buffer )

switches the scanner's input buffer so subsequent tokens will come from new_buffer. Note that `yy_switch_to_buffer()' may be used by `yywrap()' to set things up for continued scanning, instead of opening a new file and pointing yyin at it. Note also that switching input sources via either `yy_switch_to_buffer()' or `yywrap()' does not change the start condition.

void yy_delete_buffer( YY_BUFFER_STATE buffer )

is used to reclaim the storage associated with a buffer. You can also clear the current contents of a buffer using:

void yy_flush_buffer( YY_BUFFER_STATE buffer )

This function discards the buffer's contents, so the next time the scanner attempts to match a token from the buffer, it will first fill the buffer anew using YY_INPUT.

`yy_new_buffer()' is an alias for `yy_create_buffer()', provided for compatibility with the C++ use of new and delete for creating and destroying dynamic objects.

Finally, the YY_CURRENT_BUFFER macro returns a YY_BUFFER_STATE handle to the current buffer.

Here is an example of using these features for writing a scanner which expands include files (the `<<EOF>>' feature is discussed below):

/* the "incl" state is used for picking up the name
 * of an include file
 */
%x incl

%{
#define MAX_INCLUDE_DEPTH 10
YY_BUFFER_STATE include_stack[MAX_INCLUDE_DEPTH];
int include_stack_ptr = 0;
%}

%%
include             BEGIN(incl);

[a-z]+              ECHO;
[^a-z\n]*\n?        ECHO;

<incl>[ \t]*      /* eat the whitespace */
<incl>[^ \t\n]+   { /* got the include file name */
        if ( include_stack_ptr >= MAX_INCLUDE_DEPTH )
            {
            fprintf( stderr, "Includes nested too deeply" );
            exit( 1 );
            }

        include_stack[include_stack_ptr++] =
            YY_CURRENT_BUFFER;

        yyin = fopen( yytext, "r" );

        if ( ! yyin )
            error( ... );

        yy_switch_to_buffer(
            yy_create_buffer( yyin, YY_BUF_SIZE ) );

        BEGIN(INITIAL);
        }

<<EOF>> {
        if ( --include_stack_ptr < 0 )
            {
            yyterminate();
            }

        else
            {
            yy_delete_buffer( YY_CURRENT_BUFFER );
            yy_switch_to_buffer(
                 include_stack[include_stack_ptr] );
            }
        }

Three routines are available for setting up input buffers for scanning in-memory strings instead of files. All of them create a new input buffer for scanning the string, and return a corresponding YY_BUFFER_STATE handle (which you should delete with `yy_delete_buffer()' when done with it). They also switch to the new buffer using `yy_switch_to_buffer()', so the next call to `yylex()' will start scanning the string.

`yy_scan_string(const char *str)'
scans a NUL-terminated string.
`yy_scan_bytes(const char *bytes, int len)'
scans len bytes (including possibly NUL's) starting at location bytes.

Note that both of these functions create and scan a copy of the string or bytes. (This may be desirable, since `yylex()' modifies the contents of the buffer it is scanning.) You can avoid the copy by using:

`yy_scan_buffer(char *base, yy_size_t size)'
which scans in place the buffer starting at base, consisting of size bytes, the last two bytes of which must be YY_END_OF_BUFFER_CHAR (ASCII NUL). These last two bytes are not scanned; thus, scanning consists of `base[0]' through `base[size-2]', inclusive. If you fail to set up base in this manner (i.e., forget the final two YY_END_OF_BUFFER_CHAR bytes), then `yy_scan_buffer()' returns a nil pointer instead of creating a new input buffer. The type yy_size_t is an integral type to which you can cast an integer expression reflecting the size of the buffer.

End-of-file rules

The special rule "<<EOF>>" indicates actions which are to be taken when an end-of-file is encountered and yywrap() returns non-zero (i.e., indicates no further files to process). The action must finish by doing one of four things:

  • assigning yyin to a new input file (in previous versions of flex, after doing the assignment you had to call the special action YY_NEW_FILE; this is no longer necessary);
  • executing a return statement;
  • executing the special `yyterminate()' action;
  • or, switching to a new buffer using `yy_switch_to_buffer()' as shown in the example above.

<<EOF>> rules may not be used with other patterns; they may only be qualified with a list of start conditions. If an unqualified <<EOF>> rule is given, it applies to all start conditions which do not already have <<EOF>> actions. To specify an <<EOF>> rule for only the initial start condition, use

<INITIAL><<EOF>>

These rules are useful for catching things like unclosed comments. An example:

%x quote
%%

...other rules for dealing with quotes...

<quote><<EOF>>   {
         error( "unterminated quote" );
         yyterminate();
         }
<<EOF>>  {
         if ( *++filelist )
             yyin = fopen( *filelist, "r" );
         else
            yyterminate();
         }

Miscellaneous macros

The macro YY_USER_ACTION can be defined to provide an action which is always executed prior to the matched rule's action. For example, it could be #define'd to call a routine to convert yytext to lower-case. When YY_USER_ACTION is invoked, the variable yy_act gives the number of the matched rule (rules are numbered starting with 1). Suppose you want to profile how often each of your rules is matched. The following would do the trick:

#define YY_USER_ACTION ++ctr[yy_act]

where ctr is an array to hold the counts for the different rules. Note that the macro YY_NUM_RULES gives the total number of rules (including the default rule, even if you use `-s', so a correct declaration for ctr is:

int ctr[YY_NUM_RULES];

The macro YY_USER_INIT may be defined to provide an action which is always executed before the first scan (and before the scanner's internal initializations are done). For example, it could be used to call a routine to read in a data table or open a logging file.

The macro `yy_set_interactive(is_interactive)' can be used to control whether the current buffer is considered interactive. An interactive buffer is processed more slowly, but must be used when the scanner's input source is indeed interactive to avoid problems due to waiting to fill buffers (see the discussion of the `-I' flag below). A non-zero value in the macro invocation marks the buffer as interactive, a zero value as non-interactive. Note that use of this macro overrides `%option always-interactive' or `%option never-interactive' (see Options below). `yy_set_interactive()' must be invoked prior to beginning to scan the buffer that is (or is not) to be considered interactive.

The macro `yy_set_bol(at_bol)' can be used to control whether the current buffer's scanning context for the next token match is done as though at the beginning of a line. A non-zero macro argument makes rules anchored with

The macro `YY_AT_BOL()' returns true if the next token scanned from the current buffer will have '^' rules active, false otherwise.

In the generated scanner, the actions are all gathered in one large switch statement and separated using YY_BREAK, which may be redefined. By default, it is simply a "break", to separate each rule's action from the following rule's. Redefining YY_BREAK allows, for example, C++ users to #define YY_BREAK to do nothing (while being very careful that every rule ends with a "break" or a "return"!) to avoid suffering from unreachable statement warnings where because a rule's action ends with "return", the YY_BREAK is inaccessible.

Values available to the user

This section summarizes the various values available to the user in the rule actions.

  • `char *yytext' holds the text of the current token. It may be modified but not lengthened (you cannot append characters to the end). If the special directive `%array' appears in the first section of the scanner description, then yytext is instead declared `char yytext[YYLMAX]', where YYLMAX is a macro definition that you can redefine in the first section if you don't like the default value (generally 8KB). Using `%array' results in somewhat slower scanners, but the value of yytext becomes immune to calls to `input()' and `unput()', which potentially destroy its value when yytext is a character pointer. The opposite of `%array' is `%pointer', which is the default. You cannot use `%array' when generating C++ scanner classes (the `-+' flag).
  • `int yyleng' holds the length of the current token.
  • `FILE *yyin' is the file which by default flex reads from. It may be redefined but doing so only makes sense before scanning begins or after an EOF has been encountered. Changing it in the midst of scanning will have unexpected results since flex buffers its input; use `yyrestart()' instead. Once scanning terminates because an end-of-file has been seen, you can assign yyin at the new input file and then call the scanner again to continue scanning.
  • `void yyrestart( FILE *new_file )' may be called to point yyin at the new input file. The switch-over to the new file is immediate (any previously buffered-up input is lost). Note that calling `yyrestart()' with yyin as an argument thus throws away the current input buffer and continues scanning the same input file.
  • `FILE *yyout' is the file to which `ECHO' actions are done. It can be reassigned by the user.
  • YY_CURRENT_BUFFER returns a YY_BUFFER_STATE handle to the current buffer.
  • YY_START returns an integer value corresponding to the current start condition. You can subsequently use this value with BEGIN to return to that start condition.

Interfacing with yacc

One of the main uses of flex is as a companion to the yacc parser-generator. yacc parsers expect to call a routine named `yylex()' to find the next input token. The routine is supposed to return the type of the next token as well as putting any associated value in the global yylval. To use flex with yacc, one specifies the `-d' option to yacc to instruct it to generate the file `y.tab.h' containing definitions of all the `%tokens' appearing in the yacc input. This file is then included in the flex scanner. For example, if one of the tokens is "TOK_NUMBER", part of the scanner might look like:

%{
#include "y.tab.h"
%}

%%

[0-9]+        yylval = atoi( yytext ); return TOK_NUMBER;

Options

flex has the following options:

`-b'
Generate backing-up information to `lex.backup'. This is a list of scanner states which require backing up and the input characters on which they do so. By adding rules one can remove backing-up states. If all backing-up states are eliminated and `-Cf' or `-CF' is used, the generated scanner will run faster (see the `-p' flag). Only users who wish to squeeze every last cycle out of their scanners need worry about this option. (See the section on Performance Considerations below.)
`-c'
is a do-nothing, deprecated option included for POSIX compliance.
`-d'
makes the generated scanner run in debug mode. Whenever a pattern is recognized and the global yy_flex_debug is non-zero (which is the default), the scanner will write to stderr a line of the form:
--accepting rule at line 53 ("the matched text")
The line number refers to the location of the rule in the file defining the scanner (i.e., the file that was fed to flex). Messages are also generated when the scanner backs up, accepts the default rule, reaches the end of its input buffer (or encounters a NUL; at this point, the two look the same as far as the scanner's concerned), or reaches an end-of-file.
`-f'
specifies fast scanner. No table compression is done and stdio is bypassed. The result is large but fast. This option is equivalent to `-Cfr' (see below).
`-h'
generates a "help" summary of flex's options to stdout and then exits. `-?' and `--help' are synonyms for `-h'.
`-i'
instructs flex to generate a case-insensitive scanner. The case of letters given in the flex input patterns will be ignored, and tokens in the input will be matched regardless of case. The matched text given in yytext will have the preserved case (i.e., it will not be folded).
`-l'
turns on maximum compatibility with the original AT&T lex implementation. Note that this does not mean full compatibility. Use of this option costs a considerable amount of performance, and it cannot be used with the `-+, -f, -F, -Cf', or `-CF' options. For details on the compatibilities it provides, see the section "Incompatibilities With Lex And POSIX" below. This option also results in the name YY_FLEX_LEX_COMPAT being #define'd in the generated scanner.
`-n'
is another do-nothing, deprecated option included only for POSIX compliance.
`-p'
generates a performance report to stderr. The report consists of comments regarding features of the flex input file which will cause a serious loss of performance in the resulting scanner. If you give the flag twice, you will also get comments regarding features that lead to minor performance losses. Note that the use of REJECT, `%option yylineno' and variable trailing context (see the Deficiencies / Bugs section below) entails a substantial performance penalty; use of `yymore()', the `^' operator, and the `-I' flag entail minor performance penalties.
`-s'
causes the default rule (that unmatched scanner input is echoed to stdout) to be suppressed. If the scanner encounters input that does not match any of its rules, it aborts with an error. This option is useful for finding holes in a scanner's rule set.
`-t'
instructs flex to write the scanner it generates to standard output instead of `lex.yy.c'.
`-v'
specifies that flex should write to stderr a summary of statistics regarding the scanner it generates. Most of the statistics are meaningless to the casual flex user, but the first line identifies the version of flex (same as reported by `-V'), and the next line the flags used when generating the scanner, including those that are on by default.
`-w'
suppresses warning messages.
`-B'
instructs flex to generate a batch scanner, the opposite of interactive scanners generated by `-I' (see below). In general, you use `-B' when you are certain that your scanner will never be used interactively, and you want to squeeze a little more performance out of it. If your goal is instead to squeeze out a lot more performance, you should be using the `-Cf' or `-CF' options (discussed below), which turn on `-B' automatically anyway.
`-F'
specifies that the fast scanner table representation should be used (and stdio bypassed). This representation is about as fast as the full table representation `(-f)', and for some sets of patterns will be considerably smaller (and for others, larger). In general, if the pattern set contains both "keywords" and a catch-all, "identifier" rule, such as in the set:
"case"    return TOK_CASE;
"switch"  return TOK_SWITCH;
...
"default" return TOK_DEFAULT;
[a-z]+    return TOK_ID;
then you're better off using the full table representation. If only the "identifier" rule is present and you then use a hash table or some such to detect the keywords, you're better off using `-F'. This option is equivalent to `-CFr' (see below). It cannot be used with `-+'.
`-I'
instructs flex to generate an interactive scanner. An interactive scanner is one that only looks ahead to decide what token has been matched if it absolutely must. It turns out that always looking one extra character ahead, even if the scanner has already seen enough text to disambiguate the current token, is a bit faster than only looking ahead when necessary. But scanners that always look ahead give dreadful interactive performance; for example, when a user types a newline, it is not recognized as a newline token until they enter another token, which often means typing in another whole line. Flex scanners default to interactive unless you use the `-Cf' or `-CF' table-compression options (see below). That's because if you're looking for high-performance you should be using one of these options, so if you didn't, flex assumes you'd rather trade off a bit of run-time performance for intuitive interactive behavior. Note also that you cannot use `-I' in conjunction with `-Cf' or `-CF'. Thus, this option is not really needed; it is on by default for all those cases in which it is allowed. You can force a scanner to not be interactive by using `-B' (see above).
`-L'
instructs flex not to generate `#line' directives. Without this option, flex peppers the generated scanner with #line directives so error messages in the actions will be correctly located with respect to either the original flex input file (if the errors are due to code in the input file), or `lex.yy.c' (if the errors are flex's fault -- you should report these sorts of errors to the email address given below).
`-T'
makes flex run in trace mode. It will generate a lot of messages to stderr concerning the form of the input and the resultant non-deterministic and deterministic finite automata. This option is mostly for use in maintaining flex.
`-V'
prints the version number to stdout and exits. `--version' is a synonym for `-V'.
`-7'
instructs flex to generate a 7-bit scanner, i.e., one which can only recognized 7-bit characters in its input. The advantage of using `-7' is that the scanner's tables can be up to half the size of those generated using the `-8' option (see below). The disadvantage is that such scanners often hang or crash if their input contains an 8-bit character. Note, however, that unless you generate your scanner using the `-Cf' or `-CF' table compression options, use of `-7' will save only a small amount of table space, and make your scanner considerably less portable. Flex's default behavior is to generate an 8-bit scanner unless you use the `-Cf' or `-CF', in which case flex defaults to generating 7-bit scanners unless your site was always configured to generate 8-bit scanners (as will often be the case with non-USA sites). You can tell whether flex generated a 7-bit or an 8-bit scanner by inspecting the flag summary in the `-v' output as described above. Note that if you use `-Cfe' or `-CFe' (those table compression options, but also using equivalence classes as discussed see below), flex still defaults to generating an 8-bit scanner, since usually with these compression options full 8-bit tables are not much more expensive than 7-bit tables.
`-8'
instructs flex to generate an 8-bit scanner, i.e., one which can recognize 8-bit characters. This flag is only needed for scanners generated using `-Cf' or `-CF', as otherwise flex defaults to generating an 8-bit scanner anyway. See the discussion of `-7' above for flex's default behavior and the tradeoffs between 7-bit and 8-bit scanners.
`-+'
specifies that you want flex to generate a C++ scanner class. See the section on Generating C++ Scanners below for details.
`-C[aefFmr]'
controls the degree of table compression and, more generally, trade-offs between small scanners and fast scanners. `-Ca' ("align") instructs flex to trade off larger tables in the generated scanner for faster performance because the elements of the tables are better aligned for memory access and computation. On some RISC architectures, fetching and manipulating long-words is more efficient than with smaller-sized units such as shortwords. This option can double the size of the tables used by your scanner. `-Ce' directs flex to construct equivalence classes, i.e., sets of characters which have identical lexical properties (for example, if the only appearance of digits in the flex input is in the character class "[0-9]" then the digits '0', '1', ..., '9' will all be put in the same equivalence class). Equivalence classes usually give dramatic reductions in the final table/object file sizes (typically a factor of 2-5) and are pretty cheap performance-wise (one array look-up per character scanned). `-Cf' specifies that the full scanner tables should be generated - flex should not compress the tables by taking advantages of similar transition functions for different states. `-CF' specifies that the alternate fast scanner representation (described above under the `-F' flag) should be used. This option cannot be used with `-+'. `-Cm' directs flex to construct meta-equivalence classes, which are sets of equivalence classes (or characters, if equivalence classes are not being used) that are commonly used together. Meta-equivalence classes are often a big win when using compressed tables, but they have a moderate performance impact (one or two "if" tests and one array look-up per character scanned). `-Cr' causes the generated scanner to bypass use of the standard I/O library (stdio) for input. Instead of calling `fread()' or `getc()', the scanner will use the `read()' system call, resulting in a performance gain which varies from system to system, but in general is probably negligible unless you are also using `-Cf' or `-CF'. Using `-Cr' can cause strange behavior if, for example, you read from yyin using stdio prior to calling the scanner (because the scanner will miss whatever text your previous reads left in the stdio input buffer). `-Cr' has no effect if you define YY_INPUT (see The Generated Scanner above). A lone `-C' specifies that the scanner tables should be compressed but neither equivalence classes nor meta-equivalence classes should be used. The options `-Cf' or `-CF' and `-Cm' do not make sense together - there is no opportunity for meta-equivalence classes if the table is not being compressed. Otherwise the options may be freely mixed, and are cumulative. The default setting is `-Cem', which specifies that flex should generate equivalence classes and meta-equivalence classes. This setting provides the highest degree of table compression. You can trade off faster-executing scanners at the cost of larger tables with the following generally being true:
slowest & smallest
      -Cem
      -Cm
      -Ce
      -C
      -C{f,F}e
      -C{f,F}
      -C{f,F}a
fastest & largest
Note that scanners with the smallest tables are usually generated and compiled the quickest, so during development you will usually want to use the default, maximal compression. `-Cfe' is often a good compromise between speed and size for production scanners.
`-ooutput'
directs flex to write the scanner to the file `out-' put instead of `lex.yy.c'. If you combine `-o' with the `-t' option, then the scanner is written to stdout but its `#line' directives (see the `-L' option above) refer to the file output.
`-Pprefix'
changes the default `yy' prefix used by flex for all globally-visible variable and function names to instead be prefix. For example, `-Pfoo' changes the name of yytext to `footext'. It also changes the name of the default output file from `lex.yy.c' to `lex.foo.c'. Here are all of the names affected:
yy_create_buffer
yy_delete_buffer
yy_flex_debug
yy_init_buffer
yy_flush_buffer
yy_load_buffer_state
yy_switch_to_buffer
yyin
yyleng
yylex
yylineno
yyout
yyrestart
yytext
yywrap
(If you are using a C++ scanner, then only yywrap and yyFlexLexer are affected.) Within your scanner itself, you can still refer to the global variables and functions using either version of their name; but externally, they have the modified name. This option lets you easily link together multiple flex programs into the same executable. Note, though, that using this option also renames `yywrap()', so you now must either provide your own (appropriately-named) version of the routine for your scanner, or use `%option noyywrap', as linking with `-lfl' no longer provides one for you by default.
`-Sskeleton_file'
overrides the default skeleton file from which flex constructs its scanners. You'll never need this option unless you are doing flex maintenance or development.

flex also provides a mechanism for controlling options within the scanner specification itself, rather than from the flex command-line. This is done by including `%option' directives in the first section of the scanner specification. You can specify multiple options with a single `%option' directive, and multiple directives in the first section of your flex input file. Most options are given simply as names, optionally preceded by the word "no" (with no intervening whitespace) to negate their meaning. A number are equivalent to flex flags or their negation:

7bit            -7 option
8bit            -8 option
align           -Ca option
backup          -b option
batch           -B option
c++             -+ option

caseful or
case-sensitive  opposite of -i (default)

case-insensitive or
caseless        -i option

debug           -d option
default         opposite of -s option
ecs             -Ce option
fast            -F option
full            -f option
interactive     -I option
lex-compat      -l option
meta-ecs        -Cm option
perf-report     -p option
read            -Cr option
stdout          -t option
verbose         -v option
warn            opposite of -w option
                (use "%option nowarn" for -w)

array           equivalent to "%array"
pointer         equivalent to "%pointer" (default)

Some `%option's' provide features otherwise not available:

`always-interactive'
instructs flex to generate a scanner which always considers its input "interactive". Normally, on each new input file the scanner calls `isatty()' in an attempt to determine whether the scanner's input source is interactive and thus should be read a character at a time. When this option is used, however, then no such call is made.
`main'
directs flex to provide a default `main()' program for the scanner, which simply calls `yylex()'. This option implies noyywrap (see below).
`never-interactive'
instructs flex to generate a scanner which never considers its input "interactive" (again, no call made to `isatty())'. This is the opposite of `always-' interactive.
`stack'
enables the use of start condition stacks (see Start Conditions above).
`stdinit'
if unset (i.e., `%option nostdinit') initializes yyin and yyout to nil FILE pointers, instead of stdin and stdout.
`yylineno'
directs flex to generate a scanner that maintains the number of the current line read from its input in the global variable yylineno. This option is implied by `%option lex-compat'.
`yywrap'
if unset (i.e., `%option noyywrap'), makes the scanner not call `yywrap()' upon an end-of-file, but simply assume that there are no more files to scan (until the user points yyin at a new file and calls `yylex()' again).

flex scans your rule actions to determine whether you use the REJECT or `yymore()' features. The reject and yymore options are available to override its decision as to whether you use the options, either by setting them (e.g., `%option reject') to indicate the feature is indeed used, or unsetting them to indicate it actually is not used (e.g., `%option noyymore').

Three options take string-delimited values, offset with '=':

%option outfile="ABC"

is equivalent to `-oABC', and

%option prefix="XYZ"

is equivalent to `-PXYZ'.

Finally,

%option yyclass="foo"

only applies when generating a C++ scanner (`-+' option). It informs flex that you have derived `foo' as a subclass of yyFlexLexer so flex will place your actions in the member function `foo::yylex()' instead of `yyFlexLexer::yylex()'. It also generates a `yyFlexLexer::yylex()' member function that emits a run-time error (by invoking `yyFlexLexer::LexerError()') if called. See Generating C++ Scanners, below, for additional information.

A number of options are available for lint purists who want to suppress the appearance of unneeded routines in the generated scanner. Each of the following, if unset, results in the corresponding routine not appearing in the generated scanner:

input, unput
yy_push_state, yy_pop_state, yy_top_state
yy_scan_buffer, yy_scan_bytes, yy_scan_string

(though `yy_push_state()' and friends won't appear anyway unless you use `%option stack').

Performance considerations

The main design goal of flex is that it generate high-performance scanners. It has been optimized for dealing well with large sets of rules. Aside from the effects on scanner speed of the table compression `-C' options outlined above, there are a number of options/actions which degrade performance. These are, from most expensive to least:

REJECT
%option yylineno
arbitrary trailing context

pattern sets that require backing up
%array
%option interactive
%option always-interactive

'^' beginning-of-line operator
yymore()

with the first three all being quite expensive and the last two being quite cheap. Note also that `unput()' is implemented as a routine call that potentially does quite a bit of work, while `yyless()' is a quite-cheap macro; so if just putting back some excess text you scanned, use `yyless()'.

REJECT should be avoided at all costs when performance is important. It is a particularly expensive option.

Getting rid of backing up is messy and often may be an enormous amount of work for a complicated scanner. In principal, one begins by using the `-b' flag to generate a `lex.backup' file. For example, on the input

%%
foo        return TOK_KEYWORD;
foobar     return TOK_KEYWORD;

the file looks like:

State #6 is non-accepting -
 associated rule line numbers:
       2       3
 out-transitions: [ o ]
 jam-transitions: EOF [ \001-n  p-\177 ]

State #8 is non-accepting -
 associated rule line numbers:
       3
 out-transitions: [ a ]
 jam-transitions: EOF [ \001-`  b-\177 ]

State #9 is non-accepting -
 associated rule line numbers:
       3
 out-transitions: [ r ]
 jam-transitions: EOF [ \001-q  s-\177 ]

Compressed tables always back up.

The first few lines tell us that there's a scanner state in which it can make a transition on an 'o' but not on any other character, and that in that state the currently scanned text does not match any rule. The state occurs when trying to match the rules found at lines 2 and 3 in the input file. If the scanner is in that state and then reads something other than an 'o', it will have to back up to find a rule which is matched. With a bit of head-scratching one can see that this must be the state it's in when it has seen "fo". When this has happened, if anything other than another 'o' is seen, the scanner will have to back up to simply match the 'f' (by the default rule).

The comment regarding State #8 indicates there's a problem when "foob" has been scanned. Indeed, on any character other than an 'a', the scanner will have to back up to accept "foo". Similarly, the comment for State #9 concerns when "fooba" has been scanned and an 'r' does not follow.

The final comment reminds us that there's no point going to all the trouble of removing backing up from the rules unless we're using `-Cf' or `-CF', since there's no performance gain doing so with compressed scanners.

The way to remove the backing up is to add "error" rules:

%%
foo         return TOK_KEYWORD;
foobar      return TOK_KEYWORD;

fooba       |
foob        |
fo          {
            /* false alarm, not really a keyword */
            return TOK_ID;
            }

Eliminating backing up among a list of keywords can also be done using a "catch-all" rule:

%%
foo         return TOK_KEYWORD;
foobar      return TOK_KEYWORD;

[a-z]+      return TOK_ID;

This is usually the best solution when appropriate.

Backing up messages tend to cascade. With a complicated set of rules it's not uncommon to get hundreds of messages. If one can decipher them, though, it often only takes a dozen or so rules to eliminate the backing up (though it's easy to make a mistake and have an error rule accidentally match a valid token. A possible future flex feature will be to automatically add rules to eliminate backing up).

It's important to keep in mind that you gain the benefits of eliminating backing up only if you eliminate every instance of backing up. Leaving just one means you gain nothing.

Variable trailing context (where both the leading and trailing parts do not have a fixed length) entails almost the same performance loss as REJECT (i.e., substantial). So when possible a rule like:

%%
mouse|rat/(cat|dog)   run();

is better written:

%%
mouse/cat|dog         run();
rat/cat|dog           run();

or as

%%
mouse|rat/cat         run();
mouse|rat/dog         run();

Note that here the special '|' action does not provide any savings, and can even make things worse (see Deficiencies / Bugs below).

Another area where the user can increase a scanner's performance (and one that's easier to implement) arises from the fact that the longer the tokens matched, the faster the scanner will run. This is because with long tokens the processing of most input characters takes place in the (short) inner scanning loop, and does not often have to go through the additional work of setting up the scanning environment (e.g., yytext) for the action. Recall the scanner for C comments:

%x comment
%%
        int line_num = 1;

"/*"         BEGIN(comment);

<comment>[^*\n]*
<comment>"*"+[^*/\n]*
<comment>\n             ++line_num;
<comment>"*"+"/"        BEGIN(INITIAL);

This could be sped up by writing it as:

%x comment
%%
        int line_num = 1;

"/*"         BEGIN(comment);

<comment>[^*\n]*
<comment>[^*\n]*\n      ++line_num;
<comment>"*"+[^*/\n]*
<comment>"*"+[^*/\n]*\n ++line_num;
<comment>"*"+"/"        BEGIN(INITIAL);

Now instead of each newline requiring the processing of another action, recognizing the newlines is "distributed" over the other rules to keep the matched text as long as possible. Note that adding rules does not slow down the scanner! The speed of the scanner is independent of the number of rules or (modulo the considerations given at the beginning of this section) how complicated the rules are with regard to operators such as '*' and '|'.

A final example in speeding up a scanner: suppose you want to scan through a file containing identifiers and keywords, one per line and with no other extraneous characters, and recognize all the keywords. A natural first approach is:

%%
asm      |
auto     |
break    |
... etc ...
volatile |
while    /* it's a keyword */

.|\n     /* it's not a keyword */

To eliminate the back-tracking, introduce a catch-all rule:

%%
asm      |
auto     |
break    |
... etc ...
volatile |
while    /* it's a keyword */

[a-z]+   |
.|\n     /* it's not a keyword */

Now, if it's guaranteed that there's exactly one word per line, then we can reduce the total number of matches by a half by merging in the recognition of newlines with that of the other tokens:

%%
asm\n    |
auto\n   |
break\n  |
... etc ...
volatile\n |
while\n  /* it's a keyword */

[a-z]+\n |
.|\n     /* it's not a keyword */

One has to be careful here, as we have now reintroduced backing up into the scanner. In particular, while we know that there will never be any characters in the input stream other than letters or newlines, flex can't figure this out, and it will plan for possibly needing to back up when it has scanned a token like "auto" and then the next character is something other than a newline or a letter. Previously it would then just match the "auto" rule and be done, but now it has no "auto" rule, only a "auto\n" rule. To eliminate the possibility of backing up, we could either duplicate all rules but without final newlines, or, since we never expect to encounter such an input and therefore don't how it's classified, we can introduce one more catch-all rule, this one which doesn't include a newline:

%%
asm\n    |
auto\n   |
break\n  |
... etc ...
volatile\n |
while\n  /* it's a keyword */

[a-z]+\n |
[a-z]+   |
.|\n     /* it's not a keyword */

Compiled with `-Cf', this is about as fast as one can get a flex scanner to go for this particular problem.

A final note: flex is slow when matching NUL's, particularly when a token contains multiple NUL's. It's best to write rules which match short amounts of text if it's anticipated that the text will often include NUL's.

Another final note regarding performance: as mentioned above in the section How the Input is Matched, dynamically resizing yytext to accommodate huge tokens is a slow process because it presently requires that the (huge) token be rescanned from the beginning. Thus if performance is vital, you should attempt to match "large" quantities of text but not "huge" quantities, where the cutoff between the two is at about 8K characters/token.

Generating C++ scanners

flex provides two different ways to generate scanners for use with C++. The first way is to simply compile a scanner generated by flex using a C++ compiler instead of a C compiler. You should not encounter any compilations errors (please report any you find to the email address given in the Author section below). You can then use C++ code in your rule actions instead of C code. Note that the default input source for your scanner remains yyin, and default echoing is still done to yyout. Both of these remain `FILE *' variables and not C++ streams.

You can also use flex to generate a C++ scanner class, using the `-+' option, (or, equivalently, `%option c++'), which is automatically specified if the name of the flex executable ends in a `+', such as flex++. When using this option, flex defaults to generating the scanner to the file `lex.yy.cc' instead of `lex.yy.c'. The generated scanner includes the header file `FlexLexer.h', which defines the interface to two C++ classes.

The first class, FlexLexer, provides an abstract base class defining the general scanner class interface. It provides the following member functions:

`const char* YYText()'
returns the text of the most recently matched token, the equivalent of yytext.
`int YYLeng()'
returns the length of the most recently matched token, the equivalent of yyleng.
`int lineno() const'
returns the current input line number (see `%option yylineno'), or 1 if `%option yylineno' was not used.
`void set_debug( int flag )'
sets the debugging flag for the scanner, equivalent to assigning to yy_flex_debug (see the Options section above). Note that you must build the scanner using `%option debug' to include debugging information in it.
`int debug() const'
returns the current setting of the debugging flag.

Also provided are member functions equivalent to `yy_switch_to_buffer(), yy_create_buffer()' (though the first argument is an `istream*' object pointer and not a `FILE*', `yy_flush_buffer()', `yy_delete_buffer()', and `yyrestart()' (again, the first argument is a `istream*' object pointer).

The second class defined in `FlexLexer.h' is yyFlexLexer, which is derived from FlexLexer. It defines the following additional member functions:

`yyFlexLexer( istream* arg_yyin = 0, ostream* arg_yyout = 0 )'
constructs a yyFlexLexer object using the given streams for input and output. If not specified, the streams default to cin and cout, respectively.
`virtual int yylex()'
performs the same role is `yylex()' does for ordinary flex scanners: it scans the input stream, consuming tokens, until a rule's action returns a value. If you derive a subclass S from yyFlexLexer and want to access the member functions and variables of S inside `yylex()', then you need to use `%option yyclass="S"' to inform flex that you will be using that subclass instead of yyFlexLexer. In this case, rather than generating `yyFlexLexer::yylex()', flex generates `S::yylex()' (and also generates a dummy `yyFlexLexer::yylex()' that calls `yyFlexLexer::LexerError()' if called).
`virtual void switch_streams(istream* new_in = 0, ostream* new_out = 0)'
reassigns yyin to new_in (if non-nil) and yyout to new_out (ditto), deleting the previous input buffer if yyin is reassigned.
`int yylex( istream* new_in = 0, ostream* new_out = 0 )'
first switches the input streams via `switch_streams( new_in, new_out )' and then returns the value of `yylex()'.

In addition, yyFlexLexer defines the following protected virtual functions which you can redefine in derived classes to tailor the scanner:

`virtual int LexerInput( char* buf, int max_size )'
reads up to `max_size' characters into buf and returns the number of characters read. To indicate end-of-input, return 0 characters. Note that "interactive" scanners (see the `-B' and `-I' flags) define the macro YY_INTERACTIVE. If you redefine LexerInput() and need to take different actions depending on whether or not the scanner might be scanning an interactive input source, you can test for the presence of this name via `#ifdef'.
`virtual void LexerOutput( const char* buf, int size )'
writes out size characters from the buffer buf, which, while NUL-terminated, may also contain "internal" NUL's if the scanner's rules can match text with NUL's in them.
`virtual void LexerError( const char* msg )'
reports a fatal error message. The default version of this function writes the message to the stream cerr and exits.

Note that a yyFlexLexer object contains its entire scanning state. Thus you can use such objects to create reentrant scanners. You can instantiate multiple instances of the same yyFlexLexer class, and you can also combine multiple C++ scanner classes together in the same program using the `-P' option discussed above. Finally, note that the `%array' feature is not available to C++ scanner classes; you must use `%pointer' (the default).

Here is an example of a simple C++ scanner:

    // An example of using the flex C++ scanner class.

%{
int mylineno = 0;
%}

string  \"[^\n"]+\"

ws      [ \t]+

alpha   [A-Za-z]
dig     [0-9]
name    ({alpha}|{dig}|\$)({alpha}|{dig}|[_.\-/$])*
num1    [-+]?{dig}+\.?([eE][-+]?{dig}+)?
num2    [-+]?{dig}*\.{dig}+([eE][-+]?{dig}+)?
number  {num1}|{num2}

%%

{ws}    /* skip blanks and tabs */

"/*"    {
        int c;

        while((c = yyinput()) != 0)
            {
            if(c == '\n')
                ++mylineno;

            else if(c == '*')
                {
                if((c = yyinput()) == '/')
                    break;
                else
                    unput(c);
                }
            }
        }

{number}  cout << "number " << YYText() << '\n';

\n        mylineno++;

{name}    cout << "name " << YYText() << '\n';

{string}  cout << "string " << YYText() << '\n';

%%

Version 2.5               December 1994                        44

int main( int /* argc */, char** /* argv */ )
    {
    FlexLexer* lexer = new yyFlexLexer;
    while(lexer->yylex() != 0)
        ;
    return 0;
    }

If you want to create multiple (different) lexer classes, you use the `-P' flag (or the `prefix=' option) to rename each yyFlexLexer to some other xxFlexLexer. You then can include `<FlexLexer.h>' in your other sources once per lexer class, first renaming yyFlexLexer as follows:

#undef yyFlexLexer
#define yyFlexLexer xxFlexLexer
#include <FlexLexer.h>

#undef yyFlexLexer
#define yyFlexLexer zzFlexLexer
#include <FlexLexer.h>

if, for example, you used `%option prefix="xx"' for one of your scanners and `%option prefix="zz"' for the other.

IMPORTANT: the present form of the scanning class is experimental and may change considerably between major releases.

Incompatibilities with lex and POSIX

flex is a rewrite of the AT&T Unix lex tool (the two implementations do not share any code, though), with some extensions and incompatibilities, both of which are of concern to those who wish to write scanners acceptable to either implementation. Flex is fully compliant with the POSIX lex specification, except that when using `%pointer' (the default), a call to `unput()' destroys the contents of yytext, which is counter to the POSIX specification.

In this section we discuss all of the known areas of incompatibility between flex, AT&T lex, and the POSIX specification.

flex's `-l' option turns on maximum compatibility with the original AT&T lex implementation, at the cost of a major loss in the generated scanner's performance. We note below which incompatibilities can be overcome using the `-l' option.

flex is fully compatible with lex with the following exceptions:

  • The undocumented lex scanner internal variable yylineno is not supported unless `-l' or `%option yylineno' is used. yylineno should be maintained on a per-buffer basis, rather than a per-scanner (single global variable) basis. yylineno is not part of the POSIX specification.
  • The `input()' routine is not redefinable, though it may be called to read characters following whatever has been matched by a rule. If `input()' encounters an end-of-file the normal `yywrap()' processing is done. A "real" end-of-file is returned by `input()' as EOF. Input is instead controlled by defining the YY_INPUT macro. The flex restriction that `input()' cannot be redefined is in accordance with the POSIX specification, which simply does not specify any way of controlling the scanner's input other than by making an initial assignment to yyin.
  • The `unput()' routine is not redefinable. This restriction is in accordance with POSIX.
  • flex scanners are not as reentrant as lex scanners. In particular, if you have an interactive scanner and an interrupt handler which long-jumps out of the scanner, and the scanner is subsequently called again, you may get the following message:
    fatal flex scanner internal error--end of buffer missed
    To reenter the scanner, first use
    yyrestart( yyin );
    Note that this call will throw away any buffered input; usually this isn't a problem with an interactive scanner. Also note that flex C++ scanner classes are reentrant, so if using C++ is an option for you, you should use them instead. See "Generating C++ Scanners" above for details.
  • `output()' is not supported. Output from the `ECHO' macro is done to the file-pointer yyout (default stdout). `output()' is not part of the POSIX specification.
  • lex does not support exclusive start conditions (%x), though they are in the POSIX specification.
  • When definitions are expanded, flex encloses them in parentheses. With lex, the following:
    NAME    [A-Z][A-Z0-9]*
%%
foo{NAME}?      printf( "Found it\n" );
%%
    will not match the string "foo" because when the macro is expanded the rule is equivalent to "foo[A-Z][A-Z0-9]*?" and the precedence is such that the '?' is associated with "[A-Z0-9]*". With flex, the rule will be expanded to "foo([A-Z][A-Z0-9]*)?" and so the string "foo" will match. Note that if the definition begins with `^' or ends with `$' then it is not expanded with parentheses, to allow these operators to appear in definitions without losing their special meanings. But the `<s>, /', and `<<EOF>>' operators cannot be used in a flex definition. Using `-l' results in the lex behavior of no parentheses around the definition. The POSIX specification is that the definition be enclosed in parentheses.
  • Some implementations of lex allow a rule's action to begin on a separate line, if the rule's pattern has trailing whitespace:
    %%
foo|bar<space here>
  { foobar_action(); }
    flex does not support this feature.
  • The lex `%r' (generate a Ratfor scanner) option is not supported. It is not part of the POSIX specification.
  • After a call to `unput()', yytext is undefined until the next token is matched, unless the scanner was built using `%array'. This is not the case with lex or the POSIX specification. The `-l' option does away with this incompatibility.
  • The precedence of the `{}' (numeric range) operator is different. lex interprets "abc{1,3}" as "match one, two, or three occurrences of 'abc'", whereas flex interprets it as "match 'ab' followed by one, two, or three occurrences of 'c'". The latter is in agreement with the POSIX specification.
  • The precedence of the `^' operator is different. lex interprets "^foo|bar" as "match either 'foo' at the beginning of a line, or 'bar' anywhere", whereas flex interprets it as "match either 'foo' or 'bar' if they come at the beginning of a line". The latter is in agreement with the POSIX specification.
  • The special table-size declarations such as `%a' supported by lex are not required by flex scanners; flex ignores them.
  • The name FLEX_SCANNER is #define'd so scanners may be written for use with either flex or lex. Scanners also include YY_FLEX_MAJOR_VERSION and YY_FLEX_MINOR_VERSION indicating which version of flex generated the scanner (for example, for the 2.5 release, these defines would be 2 and 5 respectively).

The following flex features are not included in lex or the POSIX specification:

C++ scanners
%option
start condition scopes
start condition stacks
interactive/non-interactive scanners
yy_scan_string() and friends
yyterminate()
yy_set_interactive()
yy_set_bol()
YY_AT_BOL()
<<EOF>>
<*>
YY_DECL
YY_START
YY_USER_ACTION
YY_USER_INIT
#line directives
%{}'s around actions
multiple actions on a line

plus almost all of the flex flags. The last feature in the list refers to the fact that with flex you can put multiple actions on the same line, separated with semicolons, while with lex, the following

foo    handle_foo(); ++num_foos_seen;

is (rather surprisingly) truncated to

foo    handle_foo();

flex does not truncate the action. Actions that are not enclosed in braces are simply terminated at the end of the line.

Diagnostics

`warning, rule cannot be matched'
indicates that the given rule cannot be matched because it follows other rules that will always match the same text as it. For example, in the following "foo" cannot be matched because it comes after an identifier "catch-all" rule:
[a-z]+    got_identifier();
foo       got_foo();
Using REJECT in a scanner suppresses this warning.
`warning, -s option given but default rule can be matched'
means that it is possible (perhaps only in a particular start condition) that the default rule (match any single character) is the only one that will match a particular input. Since `-s' was given, presumably this is not intended.
`reject_used_but_not_detected undefined'
`yymore_used_but_not_detected undefined'
These errors can occur at compile time. They indicate that the scanner uses REJECT or `yymore()' but that flex failed to notice the fact, meaning that flex scanned the first two sections looking for occurrences of these actions and failed to find any, but somehow you snuck some in (via a #include file, for example). Use `%option reject' or `%option yymore' to indicate to flex that you really do use these features.
`flex scanner jammed'
a scanner compiled with `-s' has encountered an input string which wasn't matched by any of its rules. This error can also occur due to internal problems.
`token too large, exceeds YYLMAX'
your scanner uses `%array' and one of its rules matched a string longer than the `YYL-' MAX constant (8K bytes by default). You can increase the value by #define'ing YYLMAX in the definitions section of your flex input.
`scanner requires -8 flag to use the character 'x''
Your scanner specification includes recognizing the 8-bit character x and you did not specify the -8 flag, and your scanner defaulted to 7-bit because you used the `-Cf' or `-CF' table compression options. See the discussion of the `-7' flag for details.
`flex scanner push-back overflow'
you used `unput()' to push back so much text that the scanner's buffer could not hold both the pushed-back text and the current token in yytext. Ideally the scanner should dynamically resize the buffer in this case, but at present it does not.
`input buffer overflow, can't enlarge buffer because scanner uses REJECT'
the scanner was working on matching an extremely large token and needed to expand the input buffer. This doesn't work with scanners that use REJECT.
`fatal flex scanner internal error--end of buffer missed'
This can occur in an scanner which is reentered after a long-jump has jumped out (or over) the scanner's activation frame. Before reentering the scanner, use:
yyrestart( yyin );
or, as noted above, switch to using the C++ scanner class.
`too many start conditions in <> construct!'
you listed more start conditions in a <> construct than exist (so you must have listed at least one of them twice).

Files

`-lfl'
library with which scanners must be linked.
`lex.yy.c'
generated scanner (called `lexyy.c' on some systems).
`lex.yy.cc'
generated C++ scanner class, when using `-+'.
`<FlexLexer.h>'
header file defining the C++ scanner base class, FlexLexer, and its derived class, yyFlexLexer.
`flex.skl'
skeleton scanner. This file is only used when building flex, not when flex executes.
`lex.backup'
backing-up information for `-b' flag (called `lex.bck' on some systems).

Deficiencies / Bugs

Some trailing context patterns cannot be properly matched and generate warning messages ("dangerous trailing context"). These are patterns where the ending of the first part of the rule matches the beginning of the second part, such as "zx*/xy*", where the 'x*' matches the 'x' at the beginning of the trailing context. (Note that the POSIX draft states that the text matched by such patterns is undefined.)

For some trailing context rules, parts which are actually fixed-length are not recognized as such, leading to the abovementioned performance loss. In particular, parts using '|' or {n} (such as "foo{3}") are always considered variable-length.

Combining trailing context with the special '|' action can result in fixed trailing context being turned into the more expensive variable trailing context. For example, in the following:

%%
abc      |
xyz/def

Use of `unput()' invalidates yytext and yyleng, unless the `%array' directive or the `-l' option has been used.

Pattern-matching of NUL's is substantially slower than matching other characters.

Dynamic resizing of the input buffer is slow, as it entails rescanning all the text matched so far by the current (generally huge) token.

Due to both buffering of input and read-ahead, you cannot intermix calls to <stdio.h> routines, such as, for example, `getchar()', with flex rules and expect it to work. Call `input()' instead.

The total table entries listed by the `-v' flag excludes the number of table entries needed to determine what rule has been matched. The number of entries is equal to the number of DFA states if the scanner does not use REJECT, and somewhat greater than the number of states if it does.

REJECT cannot be used with the `-f' or `-F' options.

The flex internal algorithms need documentation.

See also

lex(1), yacc(1), sed(1), awk(1).

John Levine, Tony Mason, and Doug Brown: Lex & Yacc; O'Reilly and Associates. Be sure to get the 2nd edition.

M. E. Lesk and E. Schmidt, LEX - Lexical Analyzer Generator.

Alfred Aho, Ravi Sethi and Jeffrey Ullman: Compilers: Principles, Techniques and Tools; Addison-Wesley (1986). Describes the pattern-matching techniques used by flex (deterministic finite automata).

Author

Vern Paxson, with the help of many ideas and much inspiration from Van Jacobson. Original version by Jef Poskanzer. The fast table representation is a partial implementation of a design done by Van Jacobson. The implementation was done by Kevin Gong and Vern Paxson.

Thanks to the many flex beta-testers, feedbackers, and contributors, especially Francois Pinard, Casey Leedom, Stan Adermann, Terry Allen, David Barker-Plummer, John Basrai, Nelson H.F. Beebe, `benson@odi.com', Karl Berry, Peter A. Bigot, Simon Blanchard, Keith Bostic, Frederic Brehm, Ian Brockbank, Kin Cho, Nick Christopher, Brian Clapper, J.T. Conklin, Jason Coughlin, Bill Cox, Nick Cropper, Dave Curtis, Scott David Daniels, Chris G. Demetriou, Theo Deraadt, Mike Donahue, Chuck Doucette, Tom Epperly, Leo Eskin, Chris Faylor, Chris Flatters, Jon Forrest, Joe Gayda, Kaveh R. Ghazi, Eric Goldman, Christopher M. Gould, Ulrich Grepel, Peer Griebel, Jan Hajic, Charles Hemphill, NORO Hideo, Jarkko Hietaniemi, Scott Hofmann, Jeff Honig, Dana Hudes, Eric Hughes, John Interrante, Ceriel Jacobs, Michal Jaegermann, Sakari Jalovaara, Jeffrey R. Jones, Henry Juengst, Klaus Kaempf, Jonathan I. Kamens, Terrence O Kane, Amir Katz, `ken@ken.hilco.com', Kevin B. Kenny, Steve Kirsch, Winfried Koenig, Marq Kole, Ronald Lamprecht, Greg Lee, Rohan Lenard, Craig Leres, John Levine, Steve Liddle, Mike Long, Mohamed el Lozy, Brian Madsen, Malte, Joe Marshall, Bengt Martensson, Chris Metcalf, Luke Mewburn, Jim Meyering, R. Alexander Milowski, Erik Naggum, G.T. Nicol, Landon Noll, James Nordby, Marc Nozell, Richard Ohnemus, Karsten Pahnke, Sven Panne, Roland Pesch, Walter Pelissero, Gaumond Pierre, Esmond Pitt, Jef Poskanzer, Joe Rahmeh, Jarmo Raiha, Frederic Raimbault, Pat Rankin, Rick Richardson, Kevin Rodgers, Kai Uwe Rommel, Jim Roskind, Alberto Santini, Andreas Scherer, Darrell Schiebel, Raf Schietekat, Doug Schmidt, Philippe Schnoebelen, Andreas Schwab, Alex Siegel, Eckehard Stolz, Jan-Erik Strvmquist, Mike Stump, Paul Stuart, Dave Tallman, Ian Lance Taylor, Chris Thewalt, Richard M. Timoney, Jodi Tsai, Paul Tuinenga, Gary Weik, Frank Whaley, Gerhard Wilhelms, Kent Williams, Ken Yap, Ron Zellar, Nathan Zelle, David Zuhn, and those whose names have slipped my marginal mail-archiving skills but whose contributions are appreciated all the same.

Thanks to Keith Bostic, Jon Forrest, Noah Friedman, John Gilmore, Craig Leres, John Levine, Bob Mulcahy, G.T. Nicol, Francois Pinard, Rich Salz, and Richard Stallman for help with various distribution headaches.

Thanks to Esmond Pitt and Earle Horton for 8-bit character support; to Benson Margulies and Fred Burke for C++ support; to Kent Williams and Tom Epperly for C++ class support; to Ove Ewerlid for support of NUL's; and to Eric Hughes for support of multiple buffers.

This work was primarily done when I was with the Real Time Systems Group at the Lawrence Berkeley Laboratory in Berkeley, CA. Many thanks to all there for the support I received.

Send comments to `vern@ee.lbl.gov'.

This document was generated on 23 February 2001 using texi2html 1.56k.


The GNU Awk User's Guide

Node:Top, Next:Foreword, Previous:(dir), Up:(dir)

General Introduction

This file documents awk, a program that you can use to select particular records in a file and perform operations upon them. Copyright © 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.

This is Edition 3 of GAWK: Effective AWK Programming: A User's Guide for GNU Awk, for the 3.1.1 (or later) version of the GNU implementation of AWK.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the section entitled "GNU Free Documentation License".

  1. "A GNU Manual"
  2. "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."
  • Foreword: Some nice words about this Web page.
  • Preface: What this Web page is about; brief history and acknowledgments.
  • Getting Started: A basic introduction to using awk. How to run an awk program. Command-line syntax.
  • Regexp: All about matching things using regular expressions.
  • Reading Files: How to read files and manipulate fields.
  • Printing: How to print using awk. Describes the print and printf statements. Also describes redirection of output.
  • Expressions: Expressions are the basic building blocks of statements.
  • Patterns and Actions: Overviews of patterns and actions.
  • Arrays: The description and use of arrays. Also includes array-oriented control statements.
  • Functions: Built-in and user-defined functions.
  • Internationalization: Getting gawk to speak your language.
  • Advanced Features: Stuff for advanced users, specific to gawk.
  • Invoking Gawk: How to run gawk.
  • Library Functions: A Library of awk Functions.
  • Sample Programs: Many awk programs with complete explanations.
  • Language History: The evolution of the awk language.
  • Installation: Installing gawk under various operating systems.
  • Notes: Notes about gawk extensions and possible future work.
  • Basic Concepts: A very quick intoduction to programming concepts.
  • Glossary: An explanation of some unfamiliar terms.
  • Copying: Your right to copy and distribute gawk.
  • GNU Free Documentation License: The license for this Web page.
  • Index: Concept and Variable Index.

  • History: The history of gawk and awk.
  • Names: What name to use to find awk.
  • This Manual: Using this Web page. Includes sample input files that you can use.
  • Conventions: Typographical Conventions.
  • Manual History: Brief history of the GNU project and this Web page.
  • How To Contribute: Helping to save the world.
  • Acknowledgments: Acknowledgments.
  • Running gawk: How to run gawk programs; includes command-line syntax.
  • One-shot: Running a short throwaway awk program.
  • Read Terminal: Using no input files (input from terminal instead).
  • Long: Putting permanent awk programs in files.
  • Executable Scripts: Making self-contained awk programs.
  • Comments: Adding documentation to gawk programs.
  • Quoting: More discussion of shell quoting issues.
  • Sample Data Files: Sample data files for use in the awk programs illustrated in this Web page.
  • Very Simple: A very simple example.
  • Two Rules: A less simple one-line example using two rules.
  • More Complex: A more complex example.
  • Statements/Lines: Subdividing or combining statements into lines.
  • Other Features: Other Features of awk.
  • When: When to use gawk and when to use other things.
  • Regexp Usage: How to Use Regular Expressions.
  • Escape Sequences: How to write nonprinting characters.
  • Regexp Operators: Regular Expression Operators.
  • Character Lists: What can go between [...].
  • GNU Regexp Operators: Operators specific to GNU software.
  • Case-sensitivity: How to do case-insensitive matching.
  • Leftmost Longest: How much text matches.
  • Computed Regexps: Using Dynamic Regexps.
  • Records: Controlling how data is split into records.
  • Fields: An introduction to fields.
  • Nonconstant Fields: Nonconstant Field Numbers.
  • Changing Fields: Changing the Contents of a Field.
  • Field Separators: The field separator and how to change it.
  • Regexp Field Splitting: Using regexps as the field separator.
  • Single Character Fields: Making each character a separate field.
  • Command Line Field Separator: Setting FS from the command-line.
  • Field Splitting Summary: Some final points and a summary table.
  • Constant Size: Reading constant width data.
  • Multiple Line: Reading multi-line records.
  • Getline: Reading files under explicit program control using the getline function.
  • Plain Getline: Using getline with no arguments.
  • Getline/Variable: Using getline into a variable.
  • Getline/File: Using getline from a file.
  • Getline/Variable/File: Using getline into a variable from a file.
  • Getline/Pipe: Using getline from a pipe.
  • Getline/Variable/Pipe: Using getline into a variable from a pipe.
  • Getline/Coprocess: Using getline from a coprocess.
  • Getline/Variable/Coprocess: Using getline into a variable from a coprocess.
  • Getline Notes: Important things to know about getline.
  • Getline Summary: Summary of getline Variants.
  • Print: The print statement.
  • Print Examples: Simple examples of print statements.
  • Output Separators: The output separators and how to change them.
  • OFMT: Controlling Numeric Output With print.
  • Printf: The printf statement.
  • Basic Printf: Syntax of the printf statement.
  • Control Letters: Format-control letters.
  • Format Modifiers: Format-specification modifiers.
  • Printf Examples: Several examples.
  • Redirection: How to redirect output to multiple files and pipes.
  • Special Files: File name interpretation in gawk. gawk allows access to inherited file descriptors.
  • Special FD: Special files for I/O.
  • Special Process: Special files for process information.
  • Special Network: Special files for network communications.
  • Special Caveats: Things to watch out for.
  • Close Files And Pipes: Closing Input and Output Files and Pipes.
  • Constants: String, numeric and regexp constants.
  • Scalar Constants: Numeric and string constants.
  • Nondecimal-numbers: What are octal and hex numbers.
  • Regexp Constants: Regular Expression constants.
  • Using Constant Regexps: When and how to use a regexp constant.
  • Variables: Variables give names to values for later use.
  • Using Variables: Using variables in your programs.
  • Assignment Options: Setting variables on the command-line and a summary of command-line syntax. This is an advanced method of input.
  • Conversion: The conversion of strings to numbers and vice versa.
  • Arithmetic Ops: Arithmetic operations (+, -, etc.)
  • Concatenation: Concatenating strings.
  • Assignment Ops: Changing the value of a variable or a field.
  • Increment Ops: Incrementing the numeric value of a variable.
  • Truth Values: What is ``true'' and what is ``false''.
  • Typing and Comparison: How variables acquire types and how this affects comparison of numbers and strings with <, etc.
  • Boolean Ops: Combining comparison expressions using boolean operators || (``or''), && (``and'') and ! (``not'').
  • Conditional Exp: Conditional expressions select between two subexpressions under control of a third subexpression.
  • Function Calls: A function call is an expression.
  • Precedence: How various operators nest.
  • Pattern Overview: What goes into a pattern.
  • Regexp Patterns: Using regexps as patterns.
  • Expression Patterns: Any expression can be used as a pattern.
  • Ranges: Pairs of patterns specify record ranges.
  • BEGIN/END: Specifying initialization and cleanup rules.
  • Using BEGIN/END: How and why to use BEGIN/END rules.
  • I/O And BEGIN/END: I/O issues in BEGIN/END rules.
  • Empty: The empty pattern, which matches every record.
  • Using Shell Variables: How to use shell variables with awk.
  • Action Overview: What goes into an action.
  • Statements: Describes the various control statements in detail.
  • If Statement: Conditionally execute some awk statements.
  • While Statement: Loop until some condition is satisfied.
  • Do Statement: Do specified action while looping until some condition is satisfied.
  • For Statement: Another looping statement, that provides initialization and increment clauses.
  • Break Statement: Immediately exit the innermost enclosing loop.
  • Continue Statement: Skip to the end of the innermost enclosing loop.
  • Next Statement: Stop processing the current input record.
  • Nextfile Statement: Stop processing the current file.
  • Exit Statement: Stop execution of awk.
  • Built-in Variables: Summarizes the built-in variables.
  • User-modified: Built-in variables that you change to control awk.
  • Auto-set: Built-in variables where awk gives you information.
  • ARGC and ARGV: Ways to use ARGC and ARGV.
  • Array Intro: Introduction to Arrays
  • Reference to Elements: How to examine one element of an array.
  • Assigning Elements: How to change an element of an array.
  • Array Example: Basic Example of an Array
  • Scanning an Array: A variation of the for statement. It loops through the indices of an array's existing elements.
  • Delete: The delete statement removes an element from an array.
  • Numeric Array Subscripts: How to use numbers as subscripts in awk.
  • Uninitialized Subscripts: Using Uninitialized variables as subscripts.
  • Multi-dimensional: Emulating multidimensional arrays in awk.
  • Multi-scanning: Scanning multidimensional arrays.
  • Array Sorting: Sorting array values and indices.
  • Built-in: Summarizes the built-in functions.
  • Calling Built-in: How to call built-in functions.
  • Numeric Functions: Functions that work with numbers, including int, sin and rand.
  • String Functions: Functions for string manipulation, such as split, match and sprintf.
  • Gory Details: More than you want to know about \ and & with sub, gsub, and gensub.
  • I/O Functions: Functions for files and shell commands.
  • Time Functions: Functions for dealing with timestamps.
  • Bitwise Functions: Functions for bitwise operations.
  • I18N Functions: Functions for string translation.
  • User-defined: Describes User-defined functions in detail.
  • Definition Syntax: How to write definitions and what they mean.
  • Function Example: An example function definition and what it does.
  • Function Caveats: Things to watch out for.
  • Return Statement: Specifying the value a function returns.
  • Dynamic Typing: How variable types can change at runtime.
  • I18N and L10N: Internationalization and Localization.
  • Explaining gettext: How GNU gettext works.
  • Programmer i18n: Features for the programmer.
  • Translator i18n: Features for the translator.
  • String Extraction: Extracting marked strings.
  • Printf Ordering: Rearranging printf arguments.
  • I18N Portability: awk-level portability issues.
  • I18N Example: A simple i18n example.
  • Gawk I18N: gawk is also internationalized.
  • Nondecimal Data: Allowing nondecimal input data.
  • Two-way I/O: Two-way communications with another process.
  • TCP/IP Networking: Using gawk for network programming.
  • Portal Files: Using gawk with BSD portals.
  • Profiling: Profiling your awk programs.
  • Command Line: How to run awk.
  • Options: Command-line options and their meanings.
  • Other Arguments: Input file names and variable assignments.
  • AWKPATH Variable: Searching directories for awk programs.
  • Obsolete: Obsolete Options and/or features.
  • Undocumented: Undocumented Options and Features.
  • Known Bugs: Known Bugs in gawk.
  • Library Names: How to best name private global variables in library functions.
  • General Functions: Functions that are of general use.
  • Nextfile Function: Two implementations of a nextfile function.
  • Assert Function: A function for assertions in awk programs.
  • Round Function: A function for rounding if sprintf does not do it correctly.
  • Cliff Random Function: The Cliff Random Number Generator.
  • Ordinal Functions: Functions for using characters as numbers and vice versa.
  • Join Function: A function to join an array into a string.
  • Gettimeofday Function: A function to get formatted times.
  • Data File Management: Functions for managing command-line data files.
  • Filetrans Function: A function for handling data file transitions.
  • Rewind Function: A function for rereading the current file.
  • File Checking: Checking that data files are readable.
  • Ignoring Assigns: Treating assignments as file names.
  • Getopt Function: A function for processing command-line arguments.
  • Passwd Functions: Functions for getting user information.
  • Group Functions: Functions for getting group information.
  • Running Examples: How to run these examples.
  • Clones: Clones of common utilities.
  • Cut Program: The cut utility.
  • Egrep Program: The egrep utility.
  • Id Program: The id utility.
  • Split Program: The split utility.
  • Tee Program: The tee utility.
  • Uniq Program: The uniq utility.
  • Wc Program: The wc utility.
  • Miscellaneous Programs: Some interesting awk programs.
  • Dupword Program: Finding duplicated words in a document.
  • Alarm Program: An alarm clock.
  • Translate Program: A program similar to the tr utility.
  • Labels Program: Printing mailing labels.
  • Word Sorting: A program to produce a word usage count.
  • History Sorting: Eliminating duplicate entries from a history file.
  • Extract Program: Pulling out programs from Texinfo source files.
  • Simple Sed: A Simple Stream Editor.
  • Igawk Program: A wrapper for awk that includes files.
  • V7/SVR3.1: The major changes between V7 and System V Release 3.1.
  • SVR4: Minor changes between System V Releases 3.1 and 4.
  • POSIX: New features from the POSIX standard.
  • BTL: New features from the Bell Laboratories version of awk.
  • POSIX/GNU: The extensions in gawk not in POSIX awk.
  • Contributors: The major contributors to gawk.
  • Gawk Distribution: What is in the gawk distribution.
  • Getting: How to get the distribution.
  • Extracting: How to extract the distribution.
  • Distribution contents: What is in the distribution.
  • Unix Installation: Installing gawk under various versions of Unix.
  • Quick Installation: Compiling gawk under Unix.
  • Additional Configuration Options: Other compile-time options.
  • Configuration Philosophy: How it's all supposed to work.
  • Non-Unix Installation: Installation on Other Operating Systems.
  • Amiga Installation: Installing gawk on an Amiga.
  • BeOS Installation: Installing gawk on BeOS.
  • PC Installation: Installing and Compiling gawk on MS-DOS and OS/2.
  • PC Binary Installation: Installing a prepared distribution.
  • PC Compiling: Compiling gawk for MS-DOS, Win32, and OS/2.
  • PC Using: Running gawk on MS-DOS, Win32 and OS/2.
  • Cygwin: Building and running gawk for Cygwin.
  • VMS Installation: Installing gawk on VMS.
  • VMS Compilation: How to compile gawk under VMS.
  • VMS Installation Details: How to install gawk under VMS.
  • VMS Running: How to run gawk under VMS.
  • VMS POSIX: Alternate instructions for VMS POSIX.
  • Unsupported: Systems whose ports are no longer supported.
  • Atari Installation: Installing gawk on the Atari ST.
  • Atari Compiling: Compiling gawk on Atari.
  • Atari Using: Running gawk on Atari.
  • Tandem Installation: Installing gawk on a Tandem.
  • Bugs: Reporting Problems and Bugs.
  • Other Versions: Other freely available awk implementations.
  • Compatibility Mode: How to disable certain gawk extensions.
  • Additions: Making Additions To gawk.
  • Adding Code: Adding code to the main body of gawk.
  • New Ports: Porting gawk to a new operating system.
  • Dynamic Extensions: Adding new built-in functions to gawk.
  • Internals: A brief look at some gawk internals.
  • Sample Library: A example of new functions.
  • Internal File Description: What the new functions will do.
  • Internal File Ops: The code for internal file operations.
  • Using Internal File Ops: How to use an external extension.
  • Future Extensions: New features that may be implemented one day.
  • Basic High Level: The high level view.
  • Basic Data Typing: A very quick intro to data types.
  • Floating Point Issues: Stuff to know about floating-point numbers.

Short Contents

  • General Introduction
  • Foreword
  • Preface
  • Getting Started with awk
  • Regular Expressions
  • Reading Input Files
  • Printing Output
  • Expressions
  • Patterns, Actions, and Variables
  • Arrays in awk
  • Functions
  • Internationalization with gawk
  • Advanced Features of gawk
  • Running awk and gawk
  • A Library of awk Functions
  • Practical awk Programs
  • The Evolution of the awk Language
  • Installing gawk
  • Implementation Notes
  • Basic Programming Concepts
  • Glossary
  • GNU General Public License
  • GNU Free Documentation License
  • Index

Table of Contents

  • General Introduction
  • Foreword
  • Preface
    • History of awk and gawk
    • A Rose by Any Other Name
    • Using This Book
    • Typographical Conventions
    • The GNU Project and This Book
    • How to Contribute
    • Acknowledgments
  • Getting Started with awk
    • How to Run awk Programs
      • One-Shot Throwaway awk Programs
      • Running awk Without Input Files
      • Running Long Programs
      • Executable awk Programs
      • Comments in awk Programs
      • Shell-Quoting Issues
    • Data Files for the Examples
    • Some Simple Examples
    • An Example with Two Rules
    • A More Complex Example
    • awk Statements Versus Lines
    • Other Features of awk
    • When to Use awk
  • Regular Expressions
    • How to Use Regular Expressions
    • Escape Sequences
    • Regular Expression Operators
    • Using Character Lists
    • gawk-Specific Regexp Operators
    • Case Sensitivity in Matching
    • How Much Text Matches?
    • Using Dynamic Regexps
  • Reading Input Files
    • How Input Is Split into Records
    • Examining Fields
    • Nonconstant Field Numbers
    • Changing the Contents of a Field
    • Specifying How Fields Are Separated
      • Using Regular Expressions to Separate Fields
      • Making Each Character a Separate Field
      • Setting FS from the Command Line
      • Field-Splitting Summary
    • Reading Fixed-Width Data
    • Multiple-Line Records
    • Explicit Input with getline
      • Using getline with No Arguments
      • Using getline into a Variable
      • Using getline from a File
      • Using getline into a Variable from a File
      • Using getline from a Pipe
      • Using getline into a Variable from a Pipe
      • Using getline from a Coprocess
      • Using getline into a Variable from a Coprocess
      • Points to Remember About getline
      • Summary of getline Variants
  • Printing Output
    • The print Statement
    • Examples of print Statements
    • Output Separators
    • Controlling Numeric Output with print
    • Using printf Statements for Fancier Printing
      • Introduction to the printf Statement
      • Format-Control Letters
      • Modifiers for printf Formats
      • Examples Using printf
    • Redirecting Output of print and printf
    • Special File Names in gawk
      • Special Files for Standard Descriptors
      • Special Files for Process-Related Information
      • Special Files for Network Communications
      • Special File Name Caveats
    • Closing Input and Output Redirections
  • Expressions
    • Constant Expressions
      • Numeric and String Constants
      • Octal and Hexadecimal Numbers
      • Regular Expression Constants
    • Using Regular Expression Constants
    • Variables
      • Using Variables in a Program
      • Assigning Variables on the Command Line
    • Conversion of Strings and Numbers
    • Arithmetic Operators
    • String Concatenation
    • Assignment Expressions
    • Increment and Decrement Operators
    • True and False in awk
    • Variable Typing and Comparison Expressions
    • Boolean Expressions
    • Conditional Expressions
    • Function Calls
    • Operator Precedence (How Operators Nest)
  • Patterns, Actions, and Variables
    • Pattern Elements
      • Regular Expressions as Patterns
      • Expressions as Patterns
      • Specifying Record Ranges with Patterns
      • The BEGIN and END Special Patterns
        • Startup and Cleanup Actions
        • Input/Output from BEGIN and END Rules
      • The Empty Pattern
    • Using Shell Variables in Programs
    • Actions
    • Control Statements in Actions
      • The if-else Statement
      • The while Statement
      • The do-while Statement
      • The for Statement
      • The break Statement
      • The continue Statement
      • The next Statement
      • Using gawk's nextfile Statement
      • The exit Statement
    • Built-in Variables
      • Built-in Variables That Control awk
      • Built-in Variables That Convey Information
      • Using ARGC and ARGV
  • Arrays in awk
    • Introduction to Arrays
    • Referring to an Array Element
    • Assigning Array Elements
    • Basic Array Example
    • Scanning All Elements of an Array
    • The delete Statement
    • Using Numbers to Subscript Arrays
    • Using Uninitialized Variables as Subscripts
    • Multidimensional Arrays
    • Scanning Multidimensional Arrays
    • Sorting Array Values and Indices with gawk
  • Functions
    • Built-in Functions
      • Calling Built-in Functions
      • Numeric Functions
      • String-Manipulation Functions
        • More About \ and & with sub, gsub, and gensub
      • Input/Output Functions
      • Using gawk's Timestamp Functions
      • Bit-Manipulation Functions of gawk
      • Using gawk's String-Translation Functions
    • User-Defined Functions
      • Function Definition Syntax
      • Function Definition Examples
      • Calling User-Defined Functions
      • The return Statement
      • Functions and Their Effects on Variable Typing
  • Internationalization with gawk
    • Internationalization and Localization
    • GNU gettext
    • Internationalizing awk Programs
    • Translating awk Programs
      • Extracting Marked Strings
      • Rearranging printf Arguments
      • awk Portability Issues
    • A Simple Internationalization Example
    • gawk Can Speak Your Language
  • Advanced Features of gawk
    • Allowing Nondecimal Input Data
    • Two-Way Communications with Another Process
    • Using gawk for Network Programming
    • Using gawk with BSD Portals
    • Profiling Your awk Programs
  • Running awk and gawk
    • Invoking awk
    • Command-Line Options
    • Other Command-Line Arguments
    • The AWKPATH Environment Variable
    • Obsolete Options and/or Features
    • Undocumented Options and Features
    • Known Bugs in gawk
  • A Library of awk Functions
    • Naming Library Function Global Variables
    • General Programming
      • Implementing nextfile as a Function
      • Assertions
      • Rounding Numbers
      • The Cliff Random Number Generator
      • Translating Between Characters and Numbers
      • Merging an Array into a String
      • Managing the Time of Day
    • Data File Management
      • Noting Data File Boundaries
      • Rereading the Current File
      • Checking for Readable Data Files
      • Treating Assignments as File Names
    • Processing Command-Line Options
    • Reading the User Database
    • Reading the Group Database
  • Practical awk Programs
    • Running the Example Programs
    • Reinventing Wheels for Fun and Profit
      • Cutting out Fields and Columns
      • Searching for Regular Expressions in Files
      • Printing out User Information
      • Splitting a Large File into Pieces
      • Duplicating Output into Multiple Files
      • Printing Nonduplicated Lines of Text
      • Counting Things
    • A Grab Bag of awk Programs
      • Finding Duplicated Words in a Document
      • An Alarm Clock Program
      • Transliterating Characters
      • Printing Mailing Labels
      • Generating Word-Usage Counts
      • Removing Duplicates from Unsorted Text
      • Extracting Programs from Texinfo Source Files
      • A Simple Stream Editor
      • An Easy Way to Use Library Functions
  • The Evolution of the awk Language
    • Major Changes Between V7 and SVR3.1
    • Changes Between SVR3.1 and SVR4
    • Changes Between SVR4 and POSIX awk
    • Extensions in the Bell Laboratories awk
    • Extensions in gawk Not in POSIX awk
    • Major Contributors to gawk
  • Installing gawk
    • The gawk Distribution
      • Getting the gawk Distribution
      • Extracting the Distribution
      • Contents of the gawk Distribution
    • Compiling and Installing gawk on Unix
      • Compiling gawk for Unix
      • Additional Configuration Options
      • The Configuration Process
    • Installation on Other Operating Systems
      • Installing gawk on an Amiga
      • Installing gawk on BeOS
      • Installation on PC Operating Systems
        • Installing a Prepared Distribution for PC Systems
        • Compiling gawk for PC Operating Systems
        • Using gawk on PC Operating Systems
        • Using gawk In The Cygwin Environment
      • How to Compile and Install gawk on VMS
        • Compiling gawk on VMS
        • Installing gawk on VMS
        • Running gawk on VMS
        • Building and Using gawk on VMS POSIX
    • Unsupported Operating System Ports
      • Installing gawk on the Atari ST
        • Compiling gawk on the Atari ST
        • Running gawk on the Atari ST
      • Installing gawk on a Tandem
    • Reporting Problems and Bugs
    • Other Freely Available awk Implementations
  • Implementation Notes
    • Downward Compatibility and Debugging
    • Making Additions to gawk
      • Adding New Features
      • Porting gawk to a New Operating System
    • Adding New Built-in Functions to gawk
      • A Minimal Introduction to gawk Internals
      • Directory and File Operation Built-ins
        • Using chdir and stat
        • C Code for chdir and stat
        • Integrating the Extensions
    • Probable Future Extensions
  • Basic Programming Concepts
    • What a Program Does
    • Data Values in a Computer
    • Floating-Point Number Caveats
  • Glossary
  • GNU General Public License
    • Preamble
    • Terms and Conditions for Copying, Distribution and Modification
    • How to Apply These Terms to Your New Programs
  • GNU Free Documentation License
    • ADDENDUM: How to use this License for your documents
  • Index

Node:Foreword, Next:Preface, Previous:Top, Up:Top

Foreword

Arnold Robbins and I are good friends. We were introduced 11 years ago by circumstances--and our favorite programming language, AWK. The circumstances started a couple of years earlier. I was working at a new job and noticed an unplugged Unix computer sitting in the corner. No one knew how to use it, and neither did I. However, a couple of days later it was running, and I was root and the one-and-only user. That day, I began the transition from statistician to Unix programmer.

On one of many trips to the library or bookstore in search of books on Unix, I found the gray AWK book, a.k.a. Aho, Kernighan and Weinberger, The AWK Programming Language, Addison-Wesley, 1988. AWK's simple programming paradigm--find a pattern in the input and then perform an action--often reduced complex or tedious data manipulations to few lines of code. I was excited to try my hand at programming in AWK.

Alas, the awk on my computer was a limited version of the language described in the AWK book. I discovered that my computer had "old awk" and the AWK book described "new awk." I learned that this was typical; the old version refused to step aside or relinquish its name. If a system had a new awk, it was invariably called nawk, and few systems had it. The best way to get a new awk was to ftp the source code for gawk from prep.ai.mit.edu. gawk was a version of new awk written by David Trueman and Arnold, and available under the GNU General Public License.

(Incidentally, it's no longer difficult to find a new awk. gawk ships with Linux, and you can download binaries or source code for almost any system; my wife uses gawk on her VMS box.)

My Unix system started out unplugged from the wall; it certainly was not plugged into a network. So, oblivious to the existence of gawk and the Unix community in general, and desiring a new awk, I wrote my own, called mawk. Before I was finished I knew about gawk, but it was too late to stop, so I eventually posted to a comp.sources newsgroup.

A few days after my posting, I got a friendly email from Arnold introducing himself. He suggested we share design and algorithms and attached a draft of the POSIX standard so that I could update mawk to support language extensions added after publication of the AWK book.

Frankly, if our roles had been reversed, I would not have been so open and we probably would have never met. I'm glad we did meet. He is an AWK expert's AWK expert and a genuinely nice person. Arnold contributes significant amounts of his expertise and time to the Free Software Foundation.

This book is the gawk reference manual, but at its core it is a book about AWK programming that will appeal to a wide audience. It is a definitive reference to the AWK language as defined by the 1987 Bell Labs release and codified in the 1992 POSIX Utilities standard.

On the other hand, the novice AWK programmer can study a wealth of practical programs that emphasize the power of AWK's basic idioms: data driven control-flow, pattern matching with regular expressions, and associative arrays. Those looking for something new can try out gawk's interface to network protocols via special /inet files.

The programs in this book make clear that an AWK program is typically much smaller and faster to develop than a counterpart written in C. Consequently, there is often a payoff to prototype an algorithm or design in AWK to get it running quickly and expose problems early. Often, the interpreted performance is adequate and the AWK prototype becomes the product.

The new pgawk (profiling gawk), produces program execution counts. I recently experimented with an algorithm that for n lines of input, exhibited ~ C n^2 performance, while theory predicted ~ C n log n behavior. A few minutes poring over the awkprof.out profile pinpointed the problem to a single line of code. pgawk is a welcome addition to my programmer's toolbox.

Arnold has distilled over a decade of experience writing and using AWK programs, and developing gawk, into this book. If you use AWK or want to learn how, then read this book.

Michael Brennan
Author of mawk

Node:Preface, Next:Getting Started, Previous:Foreword, Up:Top

Preface

Several kinds of tasks occur repeatedly when working with text files. You might want to extract certain lines and discard the rest. Or you may need to make changes wherever certain patterns appear, but leave the rest of the file alone. Writing single-use programs for these tasks in languages such as C, C++, or Pascal is time-consuming and inconvenient. Such jobs are often easier with awk. The awk utility interprets a special-purpose programming language that makes it easy to handle simple data-reformatting jobs.

The GNU implementation of awk is called gawk; it is fully compatible with the System V Release 4 version of awk. gawk is also compatible with the POSIX specification of the awk language. This means that all properly written awk programs should work with gawk. Thus, we usually don't distinguish between gawk and other awk implementations.

Using awk allows you to:

  • Manage small, personal databases
  • Generate reports
  • Validate data
  • Produce indexes and perform other document preparation tasks
  • Experiment with algorithms that you can adapt later to other computer languages

In addition, gawk provides facilities that make it easy to:

  • Extract bits and pieces of data for processing
  • Sort data
  • Perform simple network communications

This Web page teaches you about the awk language and how you can use it effectively. You should already be familiar with basic system commands, such as cat and ls,1 as well as basic shell facilities, such as input/output (I/O) redirection and pipes.

Implementations of the awk language are available for many different computing environments. This Web page, while describing the awk language in general, also describes the particular implementation of awk called gawk (which stands for "GNU awk"). gawk runs on a broad range of Unix systems, ranging from 80386 PC-based computers up through large-scale systems, such as Crays. gawk has also been ported to Mac OS X, MS-DOS, Microsoft Windows (all versions) and OS/2 PCs, Atari and Amiga microcomputers, BeOS, Tandem D20, and VMS.

  • History: The history of gawk and awk.
  • Names: What name to use to find awk.
  • This Manual: Using this Web page. Includes sample input files that you can use.
  • Conventions: Typographical Conventions.
  • Manual History: Brief history of the GNU project and this Web page.
  • How To Contribute: Helping to save the world.
  • Acknowledgments: Acknowledgments.

Node:History, Next:Names, Previous:Preface, Up:Preface

History of awk and gawk

Recipe For A Programming Language

1 part egrep | 1 part snobol
2 parts ed | 3 parts C

Blend all parts well using lex and yacc. Document minimally and release.

After eight years, add another part egrep and two more parts C. Document very well and release.

The name awk comes from the initials of its designers: Alfred V. Aho, Peter J. Weinberger and Brian W. Kernighan. The original version of awk was written in 1977 at AT&T Bell Laboratories. In 1985, a new version made the programming language more powerful, introducing user-defined functions, multiple input streams, and computed regular expressions. This new version became widely available with Unix System V Release 3.1 (SVR3.1). The version in SVR4 added some new features and cleaned up the behavior in some of the "dark corners" of the language. The specification for awk in the POSIX Command Language and Utilities standard further clarified the language. Both the gawk designers and the original Bell Laboratories awk designers provided feedback for the POSIX specification.

Paul Rubin wrote the GNU implementation, gawk, in 1986. Jay Fenlason completed it, with advice from Richard Stallman. John Woods contributed parts of the code as well. In 1988 and 1989, David Trueman, with help from me, thoroughly reworked gawk for compatibility with the newer awk. Circa 1995, I became the primary maintainer. Current development focuses on bug fixes, performance improvements, standards compliance, and occasionally, new features.

In May of 1997, Jürgen Kahrs felt the need for network access from awk, and with a little help from me, set about adding features to do this for gawk. At that time, he also wrote the bulk of TCP/IP Internetworking with gawk (a separate document, available as part of the gawk distribution). His code finally became part of the main gawk distribution with gawk version 3.1.

See Major Contributors to gawk, for a complete list of those who made important contributions to gawk.

Node:Names, Next:This Manual, Previous:History, Up:Preface

A Rose by Any Other Name

The awk language has evolved over the years. Full details are provided in The Evolution of the awk Language. The language described in this Web page is often referred to as "new awk" (nawk).

Because of this, many systems have multiple versions of awk. Some systems have an awk utility that implements the original version of the awk language and a nawk utility for the new version. Others have an oawk version for the "old awk" language and plain awk for the new one. Still others only have one version, which is usually the new one.2

All in all, this makes it difficult for you to know which version of awk you should run when writing your programs. The best advice I can give here is to check your local documentation. Look for awk, oawk, and nawk, as well as for gawk. It is likely that you already have some version of new awk on your system, which is what you should use when running your programs. (Of course, if you're reading this Web page, chances are good that you have gawk!)

Throughout this Web page, whenever we refer to a language feature that should be available in any complete implementation of POSIX awk, we simply use the term awk. When referring to a feature that is specific to the GNU implementation, we use the term gawk.

Node:This Manual, Next:Conventions, Previous:Names, Up:Preface

Using This Book

The term awk refers to a particular program as well as to the language you use to tell this program what to do. When we need to be careful, we call the language "the awk language," and the program "the awk utility." This Web page explains both the awk language and how to run the awk utility. The term awk program refers to a program written by you in the awk programming language.

Primarily, this Web page explains the features of awk, as defined in the POSIX standard. It does so in the context of the gawk implementation. While doing so, it also attempts to describe important differences between gawk and other awk implementations.3 Finally, any gawk features that are not in the POSIX standard for awk are noted.

This Web page has the difficult task of being both a tutorial and a reference. If you are a novice, feel free to skip over details that seem too complex. You should also ignore the many cross-references; they are for the expert user and for the online Info version of the document.

There are subsections labelled as Advanced Notes scattered throughout the Web page. They add a more complete explanation of points that are relevant, but not likely to be of interest on first reading. All appear in the index, under the heading "advanced features."

Most of the time, the examples use complete awk programs. In some of the more advanced sections, only the part of the awk program that illustrates the concept currently being described is shown.

While this Web page is aimed principally at people who have not been exposed to awk, there is a lot of information here that even the awk expert should find useful. In particular, the description of POSIX awk and the example programs in A Library of awk Functions, and in Practical awk Programs, should be of interest. Getting Started with awk, provides the essentials you need to know to begin using awk. Regular Expressions, introduces regular expressions in general, and in particular the flavors supported by POSIX awk and gawk. Reading Input Files, describes how awk reads your data. It introduces the concepts of records and fields, as well as the getline command. I/O redirection is first described here. Printing Output, describes how awk programs can produce output with print and printf. Expressions, describes expressions, which are the basic building blocks for getting most things done in a program. Patterns Actions and Variables, describes how to write patterns for matching records, actions for doing something when a record is matched, and the built-in variables awk and gawk use. Arrays in awk, covers awk's one-and-only data structure: associative arrays. Deleting array elements and whole arrays is also described, as well as sorting arrays in gawk. Functions, describes the built-in functions awk and gawk provide, as well as how to define your own functions. Internationalization with gawk, describes special features in gawk for translating program messages into different languages at runtime. Advanced Features of gawk, describes a number of gawk-specific advanced features. Of particular note are the abilities to have two-way communications with another process, perform TCP/IP networking, and profile your awk programs. Running awk and gawk, describes how to run gawk, the meaning of its command-line options, and how it finds awk program source files. A Library of awk Functions, and Practical awk Programs, provide many sample awk programs. Reading them allows you to see awk solving real problems. The Evolution of the awk Language, describes how the awk language has evolved since first release to present. It also describes how gawk has acquired features over time. Installing gawk, describes how to get gawk, how to compile it under Unix, and how to compile and use it on different non-Unix systems. It also describes how to report bugs in gawk and where to get three other freely available implementations of awk. Implementation Notes, describes how to disable gawk's extensions, as well as how to contribute new code to gawk, how to write extension libraries, and some possible future directions for gawk development. Basic Programming Concepts, provides some very cursory background material for those who are completely unfamiliar with computer programming. Also centralized there is a discussion of some of the issues surrounding floating-point numbers.

The Glossary, defines most, if not all, the significant terms used throughout the book. If you find terms that you aren't familiar with, try looking them up here. GNU General Public License, and GNU Free Documentation License, present the licenses that cover the gawk source code and this Web page, respectively.

Node:Conventions, Next:Manual History, Previous:This Manual, Up:Preface

Typographical Conventions

This Web page is written using Texinfo, the GNU documentation formatting language. A single Texinfo source file is used to produce both the printed and online versions of the documentation. This section briefly documents the typographical conventions used in Texinfo.

Examples you would type at the command-line are preceded by the common shell primary and secondary prompts, $ and >. Output from the command is preceded by the glyph "-|". This typically represents the command's standard output. Error messages, and other output on the command's standard error, are preceded by the glyph "error-->". For example:

$ echo hi on stdout
-| hi on stdout
$ echo hello on stderr 1>&2
error--> hello on stderr

Characters that you type at the keyboard look like this. In particular, there are special characters called "control characters." These are characters that you type by holding down both the CONTROL key and another key, at the same time. For example, a Ctrl-d is typed by first pressing and holding the CONTROL key, next pressing the d key and finally releasing both keys.

Dark Corners
Dark corners are basically fractal -- no matter how much you illuminate, there's always a smaller but darker one.
Brian Kernighan

Until the POSIX standard (and The Gawk Manual), many features of awk were either poorly documented or not documented at all. Descriptions of such features (often called "dark corners") are noted in this Web page with "(d.c.)". They also appear in the index under the heading "dark corner."

As noted by the opening quote, though, any coverage of dark corners is, by definition, something that is incomplete.

Node:Manual History, Next:How To Contribute, Previous:Conventions, Up:Preface

The GNU Project and This Book

The Free Software Foundation (FSF) is a nonprofit organization dedicated to the production and distribution of freely distributable software. It was founded by Richard M. Stallman, the author of the original Emacs editor. GNU Emacs is the most widely used version of Emacs today.

The GNU4 Project is an ongoing effort on the part of the Free Software Foundation to create a complete, freely distributable, POSIX-compliant computing environment. The FSF uses the "GNU General Public License" (GPL) to ensure that their software's source code is always available to the end user. A copy of the GPL is included in this Web page for your reference (see GNU General Public License). The GPL applies to the C language source code for gawk. To find out more about the FSF and the GNU Project online, see the GNU Project's home page. This Web page may also be read from their web site.

A shell, an editor (Emacs), highly portable optimizing C, C++, and Objective-C compilers, a symbolic debugger and dozens of large and small utilities (such as gawk), have all been completed and are freely available. The GNU operating system kernel (the HURD), has been released but is still in an early stage of development.

Until the GNU operating system is more fully developed, you should consider using GNU/Linux, a freely distributable, Unix-like operating system for Intel 80386, DEC Alpha, Sun SPARC, IBM S/390, and other systems.5 There are many books on GNU/Linux. One that is freely available is Linux Installation and Getting Started, by Matt Welsh. Many GNU/Linux distributions are often available in computer stores or bundled on CD-ROMs with books about Linux. (There are three other freely available, Unix-like operating systems for 80386 and other systems: NetBSD, FreeBSD, and OpenBSD. All are based on the 4.4-Lite Berkeley Software Distribution, and they use recent versions of gawk for their versions of awk.)

The Web page you are reading is actually free--at least, the information in it is free to anyone. The machine-readable source code for the Web page comes with gawk; anyone may take this Web page to a copying machine and make as many copies as they like. (Take a moment to check the Free Documentation License in GNU Free Documentation License.)

Although you could just print it out yourself, bound books are much easier to read and use. Furthermore, the proceeds from sales of this book go back to the FSF to help fund development of more free software.

The Web page itself has gone through a number of previous editions. Paul Rubin wrote the very first draft of The GAWK Manual; it was around 40 pages in size. Diane Close and Richard Stallman improved it, yielding a version that was around 90 pages long and barely described the original, "old" version of awk.

I started working with that version in the fall of 1988. As work on it progressed, the FSF published several preliminary versions (numbered 0.x). In 1996, Edition 1.0 was released with gawk 3.0.0. The FSF published the first two editions under the title The GNU Awk User's Guide.

This edition maintains the basic structure of Edition 1.0, but with significant additional material, reflecting the host of new features in gawk version 3.1. Of particular note is Sorting Array Values and Indices with gawk, as well as Using gawk's Bit Manipulation Functions, Internationalization with gawk, and also Advanced Features of gawk, and Adding New Built-in Functions to gawk.

GAWK: Effective AWK Programming will undoubtedly continue to evolve. An electronic version comes with the gawk distribution from the FSF. If you find an error in this Web page, please report it! See Reporting Problems and Bugs, for information on submitting problem reports electronically, or write to me in care of the publisher.

Node:How To Contribute, Next:Acknowledgments, Previous:Manual History, Up:Preface

How to Contribute

As the maintainer of GNU awk, I am starting a collection of publicly available awk programs. For more information, see ftp://ftp.freefriends.org/arnold/Awkstuff. If you have written an interesting awk program, or have written a gawk extension that you would like to share with the rest of the world, please contact me (arnold@gnu.org). Making things available on the Internet helps keep the gawk distribution down to manageable size.

Node:Acknowledgments, Previous:How To Contribute, Up:Preface

Acknowledgments

The initial draft of The GAWK Manual had the following acknowledgments:

Many people need to be thanked for their assistance in producing this manual. Jay Fenlason contributed many ideas and sample programs. Richard Mlynarik and Robert Chassell gave helpful comments on drafts of this manual. The paper A Supplemental Document for awk by John W. Pierce of the Chemistry Department at UC San Diego, pinpointed several issues relevant both to awk implementation and to this manual, that would otherwise have escaped us.

I would like to acknowledge Richard M. Stallman, for his vision of a better world and for his courage in founding the FSF and starting the GNU Project.

The following people (in alphabetical order) provided helpful comments on various versions of this book, up to and including this edition. Rick Adams, Nelson H.F. Beebe, Karl Berry, Dr. Michael Brennan, Rich Burridge, Claire Cloutier, Diane Close, Scott Deifik, Christopher ("Topher") Eliot, Jeffrey Friedl, Dr. Darrel Hankerson, Michal Jaegermann, Dr. Richard J. LeBlanc, Michael Lijewski, Pat Rankin, Miriam Robbins, Mary Sheehan, and Chuck Toporek.

Robert J. Chassell provided much valuable advice on the use of Texinfo. He also deserves special thanks for convincing me not to title this Web page How To Gawk Politely. Karl Berry helped significantly with the TeX part of Texinfo.

I would like to thank Marshall and Elaine Hartholz of Seattle and Dr. Bert and Rita Schreiber of Detroit for large amounts of quiet vacation time in their homes, which allowed me to make significant progress on this Web page and on gawk itself.

Phil Hughes of SSC contributed in a very important way by loaning me his laptop GNU/Linux system, not once, but twice, which allowed me to do a lot of work while away from home.

David Trueman deserves special credit; he has done a yeoman job of evolving gawk so that it performs well and without bugs. Although he is no longer involved with gawk, working with him on this project was a significant pleasure.

The intrepid members of the GNITS mailing list, and most notably Ulrich Drepper, provided invaluable help and feedback for the design of the internationalization features.

Nelson Beebe, Martin Brown, Andreas Buening, Scott Deifik, Darrel Hankerson, Isamu Hasegawa, Michal Jaegermann, Jürgen Kahrs, Pat Rankin, Kai Uwe Rommel, and Eli Zaretskii (in alphabetical order) make up the gawk "crack portability team." Without their hard work and help, gawk would not be nearly the fine program it is today. It has been and continues to be a pleasure working with this team of fine people.

David and I would like to thank Brian Kernighan of Bell Laboratories for invaluable assistance during the testing and debugging of gawk, and for help in clarifying numerous points about the language. We could not have done nearly as good a job on either gawk or its documentation without his help.

Chuck Toporek, Mary Sheehan, and Claire Coutier of O'Reilly & Associates contributed significant editorial help for this Web page for the 3.1 release of gawk.

I must thank my wonderful wife, Miriam, for her patience through the many versions of this project, for her proofreading, and for sharing me with the computer. I would like to thank my parents for their love, and for the grace with which they raised and educated me. Finally, I also must acknowledge my gratitude to G-d, for the many opportunities He has sent my way, as well as for the gifts He has given me with which to take advantage of those opportunities.

Arnold Robbins
Nof Ayalon
ISRAEL
March, 2001

Node:Getting Started, Next:Regexp, Previous:Preface, Up:Top

Getting Started with awk

The basic function of awk is to search files for lines (or other units of text) that contain certain patterns. When a line matches one of the patterns, awk performs specified actions on that line. awk keeps processing input lines in this way until it reaches the end of the input files.

Programs in awk are different from programs in most other languages, because awk programs are data-driven; that is, you describe the data you want to work with and then what to do when you find it. Most other languages are procedural; you have to describe, in great detail, every step the program is to take. When working with procedural languages, it is usually much harder to clearly describe the data your program will process. For this reason, awk programs are often refreshingly easy to read and write.

When you run awk, you specify an awk program that tells awk what to do. The program consists of a series of rules. (It may also contain function definitions, an advanced feature that we will ignore for now. See User-Defined Functions.) Each rule specifies one pattern to search for and one action to perform upon finding the pattern.

Syntactically, a rule consists of a pattern followed by an action. The action is enclosed in curly braces to separate it from the pattern. Newlines usually separate rules. Therefore, an awk program looks like this:

pattern { action }
pattern { action }
...
  • Running gawk: How to run gawk programs; includes command-line syntax.
  • Sample Data Files: Sample data files for use in the awk programs illustrated in this Web page.
  • Very Simple: A very simple example.
  • Two Rules: A less simple one-line example using two rules.
  • More Complex: A more complex example.
  • Statements/Lines: Subdividing or combining statements into lines.
  • Other Features: Other Features of awk.
  • When: When to use gawk and when to use other things.

Node:Running gawk, Next:Sample Data Files, Previous:Getting Started, Up:Getting Started

How to Run awk Programs

There are several ways to run an awk program. If the program is short, it is easiest to include it in the command that runs awk, like this:

awk 'program' input-file1 input-file2 ...

When the program is long, it is usually more convenient to put it in a file and run it with a command like this:

awk -f program-file input-file1 input-file2 ...

This section discusses both mechanisms, along with several variations of each.

  • One-shot: Running a short throwaway awk program.
  • Read Terminal: Using no input files (input from terminal instead).
  • Long: Putting permanent awk programs in files.
  • Executable Scripts: Making self-contained awk programs.
  • Comments: Adding documentation to gawk programs.
  • Quoting: More discussion of shell quoting issues.

Node:One-shot, Next:Read Terminal, Previous:Running gawk, Up:Running gawk

One-Shot Throwaway awk Programs

Once you are familiar with awk, you will often type in simple programs the moment you want to use them. Then you can write the program as the first argument of the awk command, like this:

awk 'program' input-file1 input-file2 ...

where program consists of a series of patterns and actions, as described earlier.

This command format instructs the shell, or command interpreter, to start awk and use the program to process records in the input file(s). There are single quotes around program so the shell won't interpret any awk characters as special shell characters. The quotes also cause the shell to treat all of program as a single argument for awk, and allow program to be more than one line long.

This format is also useful for running short or medium-sized awk programs from shell scripts, because it avoids the need for a separate file for the awk program. A self-contained shell script is more reliable because there are no other files to misplace. Some Simple Examples, later in this chapter, presents several short, self-contained programs.

Node:Read Terminal, Next:Long, Previous:One-shot, Up:Running gawk

Running awk Without Input Files

You can also run awk without any input files. If you type the following command line:

awk 'program'

awk applies the program to the standard input, which usually means whatever you type on the terminal. This continues until you indicate end-of-file by typing Ctrl-d. (On other operating systems, the end-of-file character may be different. For example, on OS/2 and MS-DOS, it is Ctrl-z.)

As an example, the following program prints a friendly piece of advice (from Douglas Adams's The Hitchhiker's Guide to the Galaxy), to keep you from worrying about the complexities of computer programming (BEGIN is a feature we haven't discussed yet):

$ awk "BEGIN { print \"Don't Panic!\" }"
-| Don't Panic!

This program does not read any input. The \ before each of the inner double quotes is necessary because of the shell's quoting rules--in particular because it mixes both single quotes and double quotes.6

This next simple awk program emulates the cat utility; it copies whatever you type on the keyboard to its standard output (why this works is explained shortly).

$ awk '{ print }'
Now is the time for all good men
-| Now is the time for all good men
to come to the aid of their country.
-| to come to the aid of their country.
Four score and seven years ago, ...
-| Four score and seven years ago, ...
What, me worry?
-| What, me worry?
Ctrl-d

Node:Long, Next:Executable Scripts, Previous:Read Terminal, Up:Running gawk

Running Long Programs

Sometimes your awk programs can be very long. In this case, it is more convenient to put the program into a separate file. In order to tell awk to use that file for its program, you type:

awk -f source-file input-file1 input-file2 ...

The -f instructs the awk utility to get the awk program from the file source-file. Any file name can be used for source-file. For example, you could put the program:

BEGIN { print "Don't Panic!" }

into the file advice. Then this command:

awk -f advice

does the same thing as this one:

awk "BEGIN { print \"Don't Panic!\" }"

This was explained earlier (see Running awk Without Input Files). Note that you don't usually need single quotes around the file name that you specify with -f, because most file names don't contain any of the shell's special characters. Notice that in advice, the awk program did not have single quotes around it. The quotes are only needed for programs that are provided on the awk command line.

If you want to identify your awk program files clearly as such, you can add the extension .awk to the file name. This doesn't affect the execution of the awk program but it does make "housekeeping" easier.

Node:Executable Scripts, Next:Comments, Previous:Long, Up:Running gawk

Executable awk Programs

Once you have learned awk, you may want to write self-contained awk scripts, using the #! script mechanism. You can do this on many Unix systems7 as well as on the GNU system. For example, you could update the file advice to look like this:

#! /bin/awk -f

BEGIN { print "Don't Panic!" }

After making this file executable (with the chmod utility), simply type advice at the shell and the system arranges to run awk 8 as if you had typed awk -f advice:

$ chmod +x advice
$ advice
-| Don't Panic!

Self-contained awk scripts are useful when you want to write a program that users can invoke without their having to know that the program is written in awk.

Advanced Notes: Portability Issues with #!

Some systems limit the length of the interpreter name to 32 characters. Often, this can be dealt with by using a symbolic link.

You should not put more than one argument on the #! line after the path to awk. It does not work. The operating system treats the rest of the line as a single argument and passes it to awk. Doing this leads to confusing behavior--most likely a usage diagnostic of some sort from awk.

Finally, the value of ARGV[0] (see Built-in Variables) varies depending upon your operating system. Some systems put awk there, some put the full pathname of awk (such as /bin/awk), and some put the name of your script (advice). Don't rely on the value of ARGV[0] to provide your script name.

Node:Comments, Next:Quoting, Previous:Executable Scripts, Up:Running gawk

Comments in awk Programs

A comment is some text that is included in a program for the sake of human readers; it is not really an executable part of the program. Comments can explain what the program does and how it works. Nearly all programming languages have provisions for comments, as programs are typically hard to understand without them.

In the awk language, a comment starts with the sharp sign character (#) and continues to the end of the line. The # does not have to be the first character on the line. The awk language ignores the rest of a line following a sharp sign. For example, we could have put the following into advice:

# This program prints a nice friendly message.  It helps
# keep novice users from being afraid of the computer.
BEGIN    { print "Don't Panic!" }

You can put comment lines into keyboard-composed throwaway awk programs, but this usually isn't very useful; the purpose of a comment is to help you or another person understand the program when reading it at a later time.

Caution: As mentioned in One-Shot Throwaway awk Programs, you can enclose small to medium programs in single quotes, in order to keep your shell scripts self-contained. When doing so, don't put an apostrophe (i.e., a single quote) into a comment (or anywhere else in your program). The shell interprets the quote as the closing quote for the entire program. As a result, usually the shell prints a message about mismatched quotes, and if awk actually runs, it will probably print strange messages about syntax errors. For example, look at the following:

$ awk '{ print "hello" } # let's be cute'
>

The shell sees that the first two quotes match, and that a new quoted object begins at the end of the command line. It therefore prompts with the secondary prompt, waiting for more input. With Unix awk, closing the quoted string produces this result:

$ awk '{ print "hello" } # let's be cute'
> '
error--> awk: can't open file be
error-->  source line number 1

Putting a backslash before the single quote in let's wouldn't help, since backslashes are not special inside single quotes. The next subsection describes the shell's quoting rules.

Node:Quoting, Previous:Comments, Up:Running gawk

Shell-Quoting Issues

For short to medium length awk programs, it is most convenient to enter the program on the awk command line. This is best done by enclosing the entire program in single quotes. This is true whether you are entering the program interactively at the shell prompt, or writing it as part of a larger shell script:

awk 'program text' input-file1 input-file2 ...

Once you are working with the shell, it is helpful to have a basic knowledge of shell quoting rules. The following rules apply only to POSIX-compliant, Bourne-style shells (such as bash, the GNU Bourne-Again Shell). If you use csh, you're on your own.

  • Quoted items can be concatenated with nonquoted items as well as with other quoted items. The shell turns everything into one argument for the command.
  • Preceding any single character with a backslash (\) quotes that character. The shell removes the backslash and passes the quoted character on to the command.
  • Single quotes protect everything between the opening and closing quotes. The shell does no interpretation of the quoted text, passing it on verbatim to the command. It is impossible to embed a single quote inside single-quoted text. Refer back to Comments in awk Programs, for an example of what happens if you try.
  • Double quotes protect most things between the opening and closing quotes. The shell does at least variable and command substitution on the quoted text. Different shells may do additional kinds of processing on double-quoted text.

    Since certain characters within double-quoted text are processed by the shell, they must be escaped within the text. Of note are the characters $, `, \, and ", all of which must be preceded by a backslash within double-quoted text if they are to be passed on literally to the program. (The leading backslash is stripped first.) Thus, the example seen previously in Running awk Without Input Files, is applicable:

    $ awk "BEGIN { print \"Don't Panic!\" }"
-| Don't Panic!

    Note that the single quote is not special within double quotes.

  • Null strings are removed when they occur as part of a non-null command-line argument, while explicit non-null objects are kept. For example, to specify that the field separator FS should be set to the null string, use:
    awk -F "" 'program' files # correct

    Don't use this:

    awk -F"" 'program' files  # wrong!

    In the second case, awk will attempt to use the text of the program as the value of FS, and the first file name as the text of the program! This results in syntax errors at best, and confusing behavior at worst.

Mixing single and double quotes is difficult. You have to resort to shell quoting tricks, like this:

$ awk 'BEGIN { print "Here is a single quote <'"'"'>" }'
-| Here is a single quote <'>

This program consists of three concatenated quoted strings. The first and the third are single-quoted, the second is double-quoted.

This can be "simplified" to:

$ awk 'BEGIN { print "Here is a single quote <'\''>" }'
-| Here is a single quote <'>

Judge for yourself which of these two is the more readable.

Another option is to use double quotes, escaping the embedded, awk-level double quotes:

$ awk "BEGIN { print \"Here is a single quote <'>\" }"
-| Here is a single quote <'>

This option is also painful, because double quotes, backslashes, and dollar signs are very common in awk programs.

If you really need both single and double quotes in your awk program, it is probably best to move it into a separate file, where the shell won't be part of the picture, and you can say what you mean.

Node:Sample Data Files, Next:Very Simple, Previous:Running gawk, Up:Getting Started

Data Files for the Examples

Many of the examples in this Web page take their input from two sample data files. The first, BBS-list, represents a list of computer bulletin board systems together with information about those systems. The second data file, called inventory-shipped, contains information about monthly shipments. In both files, each line is considered to be one record.

In the data file BBS-list, each record contains the name of a computer bulletin board, its phone number, the board's baud rate(s), and a code for the number of hours it is operational. An A in the last column means the board operates 24 hours a day. A B in the last column means the board only operates on evening and weekend hours. A C means the board operates only on weekends:

aardvark     555-5553     1200/300          B
alpo-net     555-3412     2400/1200/300     A
barfly       555-7685     1200/300          A
bites        555-1675     2400/1200/300     A
camelot      555-0542     300               C
core         555-2912     1200/300          C
fooey        555-1234     2400/1200/300     B
foot         555-6699     1200/300          B
macfoo       555-6480     1200/300          A
sdace        555-3430     2400/1200/300     A
sabafoo      555-2127     1200/300          C

The data file inventory-shipped represents information about shipments during the year. Each record contains the month, the number of green crates shipped, the number of red boxes shipped, the number of orange bags shipped, and the number of blue packages shipped, respectively. There are 16 entries, covering the 12 months of last year and the first four months of the current year.

Jan  13  25  15 115
Feb  15  32  24 226
Mar  15  24  34 228
Apr  31  52  63 420
May  16  34  29 208
Jun  31  42  75 492
Jul  24  34  67 436
Aug  15  34  47 316
Sep  13  55  37 277
Oct  29  54  68 525
Nov  20  87  82 577
Dec  17  35  61 401

Jan  21  36  64 620
Feb  26  58  80 652
Mar  24  75  70 495
Apr  21  70  74 514

Node:Very Simple, Next:Two Rules, Previous:Sample Data Files, Up:Getting Started

Some Simple Examples

The following command runs a simple awk program that searches the input file BBS-list for the character string foo (a grouping of characters is usually called a string; the term string is based on similar usage in English, such as "a string of pearls," or "a string of cars in a train"):

awk '/foo/ { print $0 }' BBS-list

When lines containing foo are found, they are printed because print $0 means print the current line. (Just print by itself means the same thing, so we could have written that instead.)

You will notice that slashes (/) surround the string foo in the awk program. The slashes indicate that foo is the pattern to search for. This type of pattern is called a regular expression, which is covered in more detail later (see Regular Expressions). The pattern is allowed to match parts of words. There are single quotes around the awk program so that the shell won't interpret any of it as special shell characters.

Here is what this program prints:

$ awk '/foo/ { print $0 }' BBS-list
-| fooey        555-1234     2400/1200/300     B
-| foot         555-6699     1200/300          B
-| macfoo       555-6480     1200/300          A
-| sabafoo      555-2127     1200/300          C

In an awk rule, either the pattern or the action can be omitted, but not both. If the pattern is omitted, then the action is performed for every input line. If the action is omitted, the default action is to print all lines that match the pattern.

Thus, we could leave out the action (the print statement and the curly braces) in the previous example and the result would be the same: all lines matching the pattern foo are printed. By comparison, omitting the print statement but retaining the curly braces makes an empty action that does nothing (i.e., no lines are printed).

Many practical awk programs are just a line or two. Following is a collection of useful, short programs to get you started. Some of these programs contain constructs that haven't been covered yet. (The description of the program will give you a good idea of what is going on, but please read the rest of the Web page to become an awk expert!) Most of the examples use a data file named data. This is just a placeholder; if you use these programs yourself, substitute your own file names for data. For future reference, note that there is often more than one way to do things in awk. At some point, you may want to look back at these examples and see if you can come up with different ways to do the same things shown here:

  • Print the length of the longest input line:
    awk '{ if (length($0) > max) max = length($0) }
     END { print max }' data
  • Print every line that is longer than 80 characters:
    awk 'length($0) > 80' data

    The sole rule has a relational expression as its pattern and it has no action--so the default action, printing the record, is used.

  • Print the length of the longest line in data:
    expand data | awk '{ if (x < length()) x = length() }
              END { print "maximum line length is " x }'

    The input is processed by the expand utility to change tabs into spaces, so the widths compared are actually the right-margin columns.

  • Print every line that has at least one field:
    awk 'NF > 0' data

    This is an easy way to delete blank lines from a file (or rather, to create a new file similar to the old file but from which the blank lines have been removed).

  • Print seven random numbers from 0 to 100, inclusive:
    awk 'BEGIN { for (i = 1; i <= 7; i++)
                 print int(101 * rand()) }'
  • Print the total number of bytes used by files:
    ls -l files | awk '{ x += $5 }
                  END { print "total bytes: " x }'
  • Print the total number of kilobytes used by files:
    ls -l files | awk '{ x += $5 }
   END { print "total K-bytes: " (x + 1023)/1024 }'
  • Print a sorted list of the login names of all users:
    awk -F: '{ print $1 }' /etc/passwd | sort
  • Count the lines in a file:
    awk 'END { print NR }' data
  • Print the even-numbered lines in the data file:
    awk 'NR % 2 == 0' data

    If you use the expression NR % 2 == 1 instead, the program would print the odd-numbered lines.

Node:Two Rules, Next:More Complex, Previous:Very Simple, Up:Getting Started

An Example with Two Rules

The awk utility reads the input files one line at a time. For each line, awk tries the patterns of each of the rules. If several patterns match, then several actions are run in the order in which they appear in the awk program. If no patterns match, then no actions are run.

After processing all the rules that match the line (and perhaps there are none), awk reads the next line. (However, see The next Statement, and also see Using gawk's nextfile Statement). This continues until the program reaches the end of the file. For example, the following awk program contains two rules:

/12/  { print $0 }
/21/  { print $0 }

The first rule has the string 12 as the pattern and print $0 as the action. The second rule has the string 21 as the pattern and also has print $0 as the action. Each rule's action is enclosed in its own pair of braces.

This program prints every line that contains the string 12 or the string 21. If a line contains both strings, it is printed twice, once by each rule.

This is what happens if we run this program on our two sample data files, BBS-list and inventory-shipped:

$ awk '/12/ { print $0 }
>      /21/ { print $0 }' BBS-list inventory-shipped
-| aardvark     555-5553     1200/300          B
-| alpo-net     555-3412     2400/1200/300     A
-| barfly       555-7685     1200/300          A
-| bites        555-1675     2400/1200/300     A
-| core         555-2912     1200/300          C
-| fooey        555-1234     2400/1200/300     B
-| foot         555-6699     1200/300          B
-| macfoo       555-6480     1200/300          A
-| sdace        555-3430     2400/1200/300     A
-| sabafoo      555-2127     1200/300          C
-| sabafoo      555-2127     1200/300          C
-| Jan  21  36  64 620
-| Apr  21  70  74 514

Note how the line beginning with sabafoo in BBS-list was printed twice, once for each rule.

Node:More Complex, Next:Statements/Lines, Previous:Two Rules, Up:Getting Started

A More Complex Example

Now that we've mastered some simple tasks, let's look at what typical awk programs do. This example shows how awk can be used to summarize, select, and rearrange the output of another utility. It uses features that haven't been covered yet, so don't worry if you don't understand all the details:

ls -l | awk '$6 == "Nov" { sum += $5 }
             END { print sum }'

This command prints the total number of bytes in all the files in the current directory that were last modified in November (of any year). 9 The ls -l part of this example is a system command that gives you a listing of the files in a directory, including each file's size and the date the file was last modified. Its output looks like this:

-rw-r--r--  1 arnold   user   1933 Nov  7 13:05 Makefile
-rw-r--r--  1 arnold   user  10809 Nov  7 13:03 awk.h
-rw-r--r--  1 arnold   user    983 Apr 13 12:14 awk.tab.h
-rw-r--r--  1 arnold   user  31869 Jun 15 12:20 awk.y
-rw-r--r--  1 arnold   user  22414 Nov  7 13:03 awk1.c
-rw-r--r--  1 arnold   user  37455 Nov  7 13:03 awk2.c
-rw-r--r--  1 arnold   user  27511 Dec  9 13:07 awk3.c
-rw-r--r--  1 arnold   user   7989 Nov  7 13:03 awk4.c

The first field contains read-write permissions, the second field contains the number of links to the file, and the third field identifies the owner of the file. The fourth field identifies the group of the file. The fifth field contains the size of the file in bytes. The sixth, seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field contains the name of the file.10

The $6 == "Nov" in our awk program is an expression that tests whether the sixth field of the output from ls -l matches the string Nov. Each time a line has the string Nov for its sixth field, the action sum += $5 is performed. This adds the fifth field (the file's size) to the variable sum. As a result, when awk has finished reading all the input lines, sum is the total of the sizes of the files whose lines matched the pattern. (This works because awk variables are automatically initialized to zero.)

After the last line of output from ls has been processed, the END rule executes and prints the value of sum. In this example, the value of sum is 140963.

These more advanced awk techniques are covered in later sections (see Actions). Before you can move on to more advanced awk programming, you have to know how awk interprets your input and displays your output. By manipulating fields and using print statements, you can produce some very useful and impressive-looking reports.

Node:Statements/Lines, Next:Other Features, Previous:More Complex, Up:Getting Started

awk Statements Versus Lines

Most often, each line in an awk program is a separate statement or separate rule, like this:

awk '/12/  { print $0 }
     /21/  { print $0 }' BBS-list inventory-shipped

However, gawk ignores newlines after any of the following symbols and keywords:

,    {    ?    :    ||    &&    do    else

A newline at any other point is considered the end of the statement.11

If you would like to split a single statement into two lines at a point where a newline would terminate it, you can continue it by ending the first line with a backslash character (\). The backslash must be the final character on the line in order to be recognized as a continuation character. A backslash is allowed anywhere in the statement, even in the middle of a string or regular expression. For example:

awk '/This regular expression is too long, so continue it\
 on the next line/ { print $1 }'

We have generally not used backslash continuation in the sample programs in this Web page. In gawk, there is no limit on the length of a line, so backslash continuation is never strictly necessary; it just makes programs more readable. For this same reason, as well as for clarity, we have kept most statements short in the sample programs presented throughout the Web page. Backslash continuation is most useful when your awk program is in a separate source file instead of entered from the command line. You should also note that many awk implementations are more particular about where you may use backslash continuation. For example, they may not allow you to split a string constant using backslash continuation. Thus, for maximum portability of your awk programs, it is best not to split your lines in the middle of a regular expression or a string.

Caution: Backslash continuation does not work as described with the C shell. It works for awk programs in files and for one-shot programs, provided you are using a POSIX-compliant shell, such as the Unix Bourne shell or bash. But the C shell behaves differently! There, you must use two backslashes in a row, followed by a newline. Note also that when using the C shell, every newline in your awk program must be escaped with a backslash. To illustrate:

% awk 'BEGIN { \
?   print \\
?       "hello, world" \
? }'
-| hello, world

Here, the % and ? are the C shell's primary and secondary prompts, analogous to the standard shell's $ and >.

Compare the previous example to how it is done with a POSIX-compliant shell:

$ awk 'BEGIN {
>   print \
>       "hello, world"
> }'
-| hello, world

awk is a line-oriented language. Each rule's action has to begin on the same line as the pattern. To have the pattern and action on separate lines, you must use backslash continuation; there is no other option.

Another thing to keep in mind is that backslash continuation and comments do not mix. As soon as awk sees the # that starts a comment, it ignores everything on the rest of the line. For example:

$ gawk 'BEGIN { print "dont panic" # a friendly \
>                                    BEGIN rule
> }'
error--> gawk: cmd. line:2:                BEGIN rule
error--> gawk: cmd. line:2:                ^ parse error

In this case, it looks like the backslash would continue the comment onto the next line. However, the backslash-newline combination is never even noticed because it is "hidden" inside the comment. Thus, the BEGIN is noted as a syntax error.

When awk statements within one rule are short, you might want to put more than one of them on a line. This is accomplished by separating the statements with a semicolon (;). This also applies to the rules themselves. Thus, the program shown at the start of this section could also be written this way:

/12/ { print $0 } ; /21/ { print $0 }

Note: The requirement that states that rules on the same line must be separated with a semicolon was not in the original awk language; it was added for consistency with the treatment of statements within an action.

Node:Other Features, Next:When, Previous:Statements/Lines, Up:Getting Started

Other Features of awk

The awk language provides a number of predefined, or built-in, variables that your programs can use to get information from awk. There are other variables your program can set as well to control how awk processes your data.

In addition, awk provides a number of built-in functions for doing common computational and string-related operations. gawk provides built-in functions for working with timestamps, performing bit manipulation, and for runtime string translation.

As we develop our presentation of the awk language, we introduce most of the variables and many of the functions. They are defined systematically in Built-in Variables, and Built-in Functions.

Node:When, Previous:Other Features, Up:Getting Started

When to Use awk

Now that you've seen some of what awk can do, you might wonder how awk could be useful for you. By using utility programs, advanced patterns, field separators, arithmetic statements, and other selection criteria, you can produce much more complex output. The awk language is very useful for producing reports from large amounts of raw data, such as summarizing information from the output of other utility programs like ls. (See A More Complex Example.)

Programs written with awk are usually much smaller than they would be in other languages. This makes awk programs easy to compose and use. Often, awk programs can be quickly composed at your terminal, used once, and thrown away. Because awk programs are interpreted, you can avoid the (usually lengthy) compilation part of the typical edit-compile-test-debug cycle of software development.

Complex programs have been written in awk, including a complete retargetable assembler for eight-bit microprocessors (see Glossary, for more information), and a microcode assembler for a special-purpose Prolog computer. However, awk's capabilities are strained by tasks of such complexity.

If you find yourself writing awk scripts of more than, say, a few hundred lines, you might consider using a different programming language. Emacs Lisp is a good choice if you need sophisticated string or pattern matching capabilities. The shell is also good at string and pattern matching; in addition, it allows powerful use of the system utilities. More conventional languages, such as C, C++, and Java, offer better facilities for system programming and for managing the complexity of large programs. Programs in these languages may require more lines of source code than the equivalent awk programs, but they are easier to maintain and usually run more efficiently.

Node:Regexp, Next:Reading Files, Previous:Getting Started, Up:Top

Regular Expressions

A regular expression, or regexp, is a way of describing a set of strings. Because regular expressions are such a fundamental part of awk programming, their format and use deserve a separate chapter.

A regular expression enclosed in slashes (/) is an awk pattern that matches every input record whose text belongs to that set. The simplest regular expression is a sequence of letters, numbers, or both. Such a regexp matches any string that contains that sequence. Thus, the regexp foo matches any string containing foo. Therefore, the pattern /foo/ matches any input record containing the three characters foo anywhere in the record. Other kinds of regexps let you specify more complicated classes of strings.

Initially, the examples in this chapter are simple. As we explain more about how regular expressions work, we will present more complicated instances.

  • Regexp Usage: How to Use Regular Expressions.
  • Escape Sequences: How to write nonprinting characters.
  • Regexp Operators: Regular Expression Operators.
  • Character Lists: What can go between [...].
  • GNU Regexp Operators: Operators specific to GNU software.
  • Case-sensitivity: How to do case-insensitive matching.
  • Leftmost Longest: How much text matches.
  • Computed Regexps: Using Dynamic Regexps.

Node:Regexp Usage, Next:Escape Sequences, Previous:Regexp, Up:Regexp

How to Use Regular Expressions

A regular expression can be used as a pattern by enclosing it in slashes. Then the regular expression is tested against the entire text of each record. (Normally, it only needs to match some part of the text in order to succeed.) For example, the following prints the second field of each record that contains the string foo anywhere in it:

$ awk '/foo/ { print $2 }' BBS-list
-| 555-1234
-| 555-6699
-| 555-6480
-| 555-2127

~ (tilde), ~ operator Regular expressions can also be used in matching expressions. These expressions allow you to specify the string to match against; it need not be the entire current input record. The two operators ~ and !~ perform regular expression comparisons. Expressions using these operators can be used as patterns, or in if, while, for, and do statements. (See Control Statements in Actions.) For example:

exp ~ /regexp/

is true if the expression exp (taken as a string) matches regexp. The following example matches, or selects, all input records with the uppercase letter J somewhere in the first field:

$ awk '$1 ~ /J/' inventory-shipped
-| Jan  13  25  15 115
-| Jun  31  42  75 492
-| Jul  24  34  67 436
-| Jan  21  36  64 620

So does this:

awk '{ if ($1 ~ /J/) print }' inventory-shipped

This next example is true if the expression exp (taken as a character string) does not match regexp:

exp !~ /regexp/

The following example matches, or selects, all input records whose first field does not contain the uppercase letter J:

$ awk '$1 !~ /J/' inventory-shipped
-| Feb  15  32  24 226
-| Mar  15  24  34 228
-| Apr  31  52  63 420
-| May  16  34  29 208
...

When a regexp is enclosed in slashes, such as /foo/, we call it a regexp constant, much like 5.27 is a numeric constant and "foo" is a string constant.

Node:Escape Sequences, Next:Regexp Operators, Previous:Regexp Usage, Up:Regexp

Escape Sequences

Some characters cannot be included literally in string constants ("foo") or regexp constants (/foo/). Instead, they should be represented with escape sequences, which are character sequences beginning with a backslash (\). One use of an escape sequence is to include a double-quote character in a string constant. Because a plain double quote ends the string, you must use \" to represent an actual double-quote character as a part of the string. For example:

$ awk 'BEGIN { print "He said \"hi!\" to her." }'
-| He said "hi!" to her.

The backslash character itself is another character that cannot be included normally; you must write \\ to put one backslash in the string or regexp. Thus, the string whose contents are the two characters " and \ must be written "\"\\".

Backslash also represents unprintable characters such as TAB or newline. While there is nothing to stop you from entering most unprintable characters directly in a string constant or regexp constant, they may look ugly.

The following table lists all the escape sequences used in awk and what they represent. Unless noted otherwise, all these escape sequences apply to both string constants and regexp constants:

\\
A literal backslash, \.
\a
The "alert" character, Ctrl-g, ASCII code 7 (BEL). (This usually makes some sort of audible noise.)
\b
Backspace, Ctrl-h, ASCII code 8 (BS).
\f
Formfeed, Ctrl-l, ASCII code 12 (FF).
\n
Newline, Ctrl-j, ASCII code 10 (LF).
\r
Carriage return, Ctrl-m, ASCII code 13 (CR).
\t
Horizontal TAB, Ctrl-i, ASCII code 9 (HT).
\v
Vertical tab, Ctrl-k, ASCII code 11 (VT).
\nnn
The octal value nnn, where nnn stands for 1 to 3 digits between 0 and 7. For example, the code for the ASCII ESC (escape) character is \033.
\xhh...
The hexadecimal value hh, where hh stands for a sequence of hexadecimal digits (0-9, and either A-F or a-f). Like the same construct in ISO C, the escape sequence continues until the first nonhexadecimal digit is seen. However, using more than two hexadecimal digits produces undefined results. (The \x escape sequence is not allowed in POSIX awk.)
\/
A literal slash (necessary for regexp constants only). This expression is used when you want to write a regexp constant that contains a slash. Because the regexp is delimited by slashes, you need to escape the slash that is part of the pattern, in order to tell awk to keep processing the rest of the regexp.
\"
A literal double quote (necessary for string constants only). This expression is used when you want to write a string constant that contains a double quote. Because the string is delimited by double quotes, you need to escape the quote that is part of the string, in order to tell awk to keep processing the rest of the string.

In gawk, a number of additional two-character sequences that begin with a backslash have special meaning in regexps. See gawk-Specific Regexp Operators.

In a regexp, a backslash before any character that is not in the previous list and not listed in gawk-Specific Regexp Operators, means that the next character should be taken literally, even if it would normally be a regexp operator. For example, /a\+b/ matches the three characters a+b.

For complete portability, do not use a backslash before any character not shown in the previous list.

To summarize:

  • The escape sequences in the table above are always processed first, for both string constants and regexp constants. This happens very early, as soon as awk reads your program.
  • gawk processes both regexp constants and dynamic regexps (see Using Dynamic Regexps), for the special operators listed in gawk-Specific Regexp Operators.
  • A backslash before any other character means to treat that character literally.

Advanced Notes: Backslash Before Regular Characters

If you place a backslash in a string constant before something that is not one of the characters previously listed, POSIX awk purposely leaves what happens as undefined. There are two choices:

Strip the backslash out
This is what Unix awk and gawk both do. For example, "a\qc" is the same as "aqc". (Because this is such an easy bug both to introduce and to miss, gawk warns you about it.) Consider FS = "[ \t]+\|[ \t]+" to use vertical bars surrounded by whitespace as the field separator. There should be two backslashes in the string FS = "[ \t]+\\|[ \t]+".)
Leave the backslash alone
Some other awk implementations do this. In such implementations, typing "a\qc" is the same as typing "a\\qc".

Advanced Notes: Escape Sequences for Metacharacters

Suppose you use an octal or hexadecimal escape to represent a regexp metacharacter. (See Regular Expression Operators.) Does awk treat the character as a literal character or as a regexp operator?

Historically, such characters were taken literally. (d.c.) However, the POSIX standard indicates that they should be treated as real metacharacters, which is what gawk does. In compatibility mode (see Command-Line Options), gawk treats the characters represented by octal and hexadecimal escape sequences literally when used in regexp constants. Thus, /a\52b/ is equivalent to /a\*b/.

Node:Regexp Operators, Next:Character Lists, Previous:Escape Sequences, Up:Regexp

Regular Expression Operators

You can combine regular expressions with special characters, called regular expression operators or metacharacters, to increase the power and versatility of regular expressions.

The escape sequences described earlier in Escape Sequences, are valid inside a regexp. They are introduced by a \ and are recognized and converted into corresponding real characters as the very first step in processing regexps.

Here is a list of metacharacters. All characters that are not escape sequences and that are not listed in the table stand for themselves:

\
This is used to suppress the special meaning of a character when matching. For example, \$ matches the character $.
^
This matches the beginning of a string. For example, ^@chapter matches @chapter at the beginning of a string and can be used to identify chapter beginnings in Texinfo source files. The ^ is known as an anchor, because it anchors the pattern to match only at the beginning of the string.

It is important to realize that ^ does not match the beginning of a line embedded in a string. The condition is not true in the following example:

if ("line1\nLINE 2" ~ /^L/) ...

$
This is similar to ^, but it matches only at the end of a string. For example, p$ matches a record that ends with a p. The $ is an anchor and does not match the end of a line embedded in a string. The condition in the following example is not true:
if ("line1\nLINE 2" ~ /1$/) ...

.
This matches any single character, including the newline character. For example, .P matches any single character followed by a P in a string. Using concatenation, we can make a regular expression such as U.A, which matches any three-character sequence that begins with U and ends with A.

In strict POSIX mode (see Command-Line Options), . does not match the NUL character, which is a character with all bits equal to zero. Otherwise, NUL is just another character. Other versions of awk may not be able to match the NUL character.

[...]
This is called a character list.12 It matches any one of the characters that are enclosed in the square brackets. For example, [MVX] matches any one of the characters M, V, or X in a string. A full discussion of what can be inside the square brackets of a character list is given in Using Character Lists.
[^ ...]
This is a complemented character list. The first character after the [ must be a ^. It matches any characters except those in the square brackets. For example, [^awk] matches any character that is not an a, w, or k.
|
This is the alternation operator and it is used to specify alternatives. The | has the lowest precedence of all the regular expression operators. For example, ^P|[[:digit:]] matches any string that matches either ^P or [[:digit:]]. This means it matches any string that starts with P or contains a digit.

The alternation applies to the largest possible regexps on either side.

(...)
Parentheses are used for grouping in regular expressions, as in arithmetic. They can be used to concatenate regular expressions containing the alternation operator, |. For example, @(samp|code)\{[^}]+\} matches both @code{foo} and @samp{bar}. (These are Texinfo formatting control sequences.)
*
This symbol means that the preceding regular expression should be repeated as many times as necessary to find a match. For example, ph* applies the * symbol to the preceding h and looks for matches of one p followed by any number of hs. This also matches just p if no hs are present.

The * repeats the smallest possible preceding expression. (Use parentheses if you want to repeat a larger expression.) It finds as many repetitions as possible. For example, awk '/\(c[ad][ad]*r x\)/ { print }' sample prints every record in sample containing a string of the form (car x), (cdr x), (cadr x), and so on. Notice the escaping of the parentheses by preceding them with backslashes.

+
This symbol is similar to *, except that the preceding expression must be matched at least once. This means that wh+y would match why and whhy, but not wy, whereas wh*y would match all three of these strings. The following is a simpler way of writing the last * example:
awk '/\(c[ad]+r x\)/ { print }' sample

?
This symbol is similar to *, except that the preceding expression can be matched either once or not at all. For example, fe?d matches fed and fd, but nothing else.
{n}
{n,}
{n,m}
One or two numbers inside braces denote an interval expression. If there is one number in the braces, the preceding regexp is repeated n times. If there are two numbers separated by a comma, the preceding regexp is repeated n to m times. If there is one number followed by a comma, then the preceding regexp is repeated at least n times:
wh{3}y
Matches whhhy, but not why or whhhhy.
wh{3,5}y
Matches whhhy, whhhhy, or whhhhhy, only.
wh{2,}y
Matches whhy or whhhy, and so on.

Interval expressions were not traditionally available in awk. They were added as part of the POSIX standard to make awk and egrep consistent with each other.

However, because old programs may use { and } in regexp constants, by default gawk does not match interval expressions in regexps. If either --posix or --re-interval are specified (see Command-Line Options), then interval expressions are allowed in regexps.

For new programs that use { and } in regexp constants, it is good practice to always escape them with a backslash. Then the regexp constants are valid and work the way you want them to, using any version of awk.13

In regular expressions, the *, +, and ? operators, as well as the braces { and }, have the highest precedence, followed by concatenation, and finally by |. As in arithmetic, parentheses can change how operators are grouped.

In POSIX awk and gawk, the *, +, and ? operators stand for themselves when there is nothing in the regexp that precedes them. For example, /+/ matches a literal plus sign. However, many other versions of awk treat such a usage as a syntax error.

If gawk is in compatibility mode (see Command-Line Options), POSIX character classes and interval expressions are not available in regular expressions.

Node:Character Lists, Next:GNU Regexp Operators, Previous:Regexp Operators, Up:Regexp

Using Character Lists

Within a character list, a range expression consists of two characters separated by a hyphen. It matches any single character that sorts between the two characters, using the locale's collating sequence and character set. For example, in the default C locale, [a-dx-z] is equivalent to [abcdxyz]. Many locales sort characters in dictionary order, and in these locales, [a-dx-z] is typically not equivalent to [abcdxyz]; instead it might be equivalent to [aBbCcDdxXyYz], for example. To obtain the traditional interpretation of bracket expressions, you can use the C locale by setting the LC_ALL environment variable to the value C.

To include one of the characters \, ], -, or ^ in a character list, put a \ in front of it. For example:

[d\]]

matches either d or ].

This treatment of \ in character lists is compatible with other awk implementations and is also mandated by POSIX. The regular expressions in awk are a superset of the POSIX specification for Extended Regular Expressions (EREs). POSIX EREs are based on the regular expressions accepted by the traditional egrep utility.

Character classes are a new feature introduced in the POSIX standard. A character class is a special notation for describing lists of characters that have a specific attribute, but the actual characters can vary from country to country and/or from character set to character set. For example, the notion of what is an alphabetic character differs between the United States and France.

A character class is only valid in a regexp inside the brackets of a character list. Character classes consist of [:, a keyword denoting the class, and :]. Here are the character classes defined by the POSIX standard.

[:alnum:] | Alphanumeric characters.
[:alpha:] | Alphabetic characters.
[:blank:] | Space and TAB characters.
[:cntrl:] | Control characters.
[:digit:] | Numeric characters.
[:graph:] | Characters that are both printable and visible. (A space is printable but not visible, whereas an a is both.)
[:lower:] | Lowercase alphabetic characters.
[:print:] | Printable characters (characters that are not control characters).
[:punct:] | Punctuation characters (characters that are not letters, digits, control characters, or space characters).
[:space:] | Space characters (such as space, TAB, and formfeed, to name a few).
[:upper:] | Uppercase alphabetic characters.
[:xdigit:] | Characters that are hexadecimal digits.

For example, before the POSIX standard, you had to write /[A-Za-z0-9]/ to match alphanumeric characters. If your character set had other alphabetic characters in it, this would not match them, and if your character set collated differently from ASCII, this might not even match the ASCII alphanumeric characters. With the POSIX character classes, you can write /[[:alnum:]]/ to match the alphabetic and numeric characters in your character set.

Two additional special sequences can appear in character lists. These apply to non-ASCII character sets, which can have single symbols (called collating elements) that are represented with more than one character. They can also have several characters that are equivalent for collating, or sorting, purposes. (For example, in French, a plain "e" and a grave-accented "è" are equivalent.) These sequences are:

Collating symbols
Multicharacter collating elements enclosed between [. and .]. For example, if ch is a collating element, then [[.ch.]] is a regexp that matches this collating element, whereas [ch] is a regexp that matches either c or h.
Equivalence classes
Locale-specific names for a list of characters that are equal. The name is enclosed between [= and =]. For example, the name e might be used to represent all of "e," "è," and "é." In this case, [[=e=]] is a regexp that matches any of e, é, or è.

These features are very valuable in non-English-speaking locales.

Caution: The library functions that gawk uses for regular expression matching currently recognize only POSIX character classes; they do not recognize collating symbols or equivalence classes.

Node:GNU Regexp Operators, Next:Case-sensitivity, Previous:Character Lists, Up:Regexp

gawk-Specific Regexp Operators

GNU software that deals with regular expressions provides a number of additional regexp operators. These operators are described in this section and are specific to gawk; they are not available in other awk implementations. Most of the additional operators deal with word matching. For our purposes, a word is a sequence of one or more letters, digits, or underscores (_):

\w
Matches any word-constituent character--that is, it matches any letter, digit, or underscore. Think of it as shorthand for [[:alnum:]_].
\W
Matches any character that is not word-constituent. Think of it as shorthand for [^[:alnum:]_].
\<
Matches the empty string at the beginning of a word. For example, /\<away/ matches away but not stowaway.
\>
Matches the empty string at the end of a word. For example, /stow\>/ matches stow but not stowaway.
\y
Matches the empty string at either the beginning or the end of a word (i.e., the word boundary). For example, \yballs?\y matches either ball or balls, as a separate word.
\B
Matches the empty string that occurs between two word-constituent characters. For example, /\Brat\B/ matches crate but it does not match dirty rat. \B is essentially the opposite of \y.

There are two other operators that work on buffers. In Emacs, a buffer is, naturally, an Emacs buffer. For other programs, gawk's regexp library routines consider the entire string to match as the buffer. The operators are:

\`
Matches the empty string at the beginning of a buffer (string).
\'
Matches the empty string at the end of a buffer (string).

Because ^ and $ always work in terms of the beginning and end of strings, these operators don't add any new capabilities for awk. They are provided for compatibility with other GNU software.

In other GNU software, the word-boundary operator is \b. However, that conflicts with the awk language's definition of \b as backspace, so gawk uses a different letter. An alternative method would have been to require two backslashes in the GNU operators, but this was deemed too confusing. The current method of using \y for the GNU \b appears to be the lesser of two evils.

The various command-line options (see Command-Line Options) control how gawk interprets characters in regexps:

No options
In the default case, gawk provides all the facilities of POSIX regexps and the previously described GNU regexp operators. GNU regexp operators described in Regular Expression Operators. However, interval expressions are not supported.
--posix
Only POSIX regexps are supported; the GNU operators are not special (e.g., \w matches a literal w). Interval expressions are allowed.
--traditional
Traditional Unix awk regexps are matched. The GNU operators are not special, interval expressions are not available, nor are the POSIX character classes ([[:alnum:]], etc.). Characters described by octal and hexadecimal escape sequences are treated literally, even if they represent regexp metacharacters.
--re-interval
Allow interval expressions in regexps, even if --traditional has been provided.

Node:Case-sensitivity, Next:Leftmost Longest, Previous:GNU Regexp Operators, Up:Regexp

Case Sensitivity in Matching

Case is normally significant in regular expressions, both when matching ordinary characters (i.e., not metacharacters) and inside character sets. Thus, a w in a regular expression matches only a lowercase w and not an uppercase W.

The simplest way to do a case-independent match is to use a character list--for example, [Ww]. However, this can be cumbersome if you need to use it often, and it can make the regular expressions harder to read. There are two alternatives that you might prefer.

One way to perform a case-insensitive match at a particular point in the program is to convert the data to a single case, using the tolower or toupper built-in string functions (which we haven't discussed yet; see String Manipulation Functions). For example:

tolower($1) ~ /foo/  { ... }

converts the first field to lowercase before matching against it. This works in any POSIX-compliant awk.

Another method, specific to gawk, is to set the variable IGNORECASE to a nonzero value (see Built-in Variables). When IGNORECASE is not zero, all regexp and string operations ignore case. Changing the value of IGNORECASE dynamically controls the case-sensitivity of the program as it runs. Case is significant by default because IGNORECASE (like most variables) is initialized to zero:

x = "aB"
if (x ~ /ab/) ...   # this test will fail

IGNORECASE = 1
if (x ~ /ab/) ...   # now it will succeed

In general, you cannot use IGNORECASE to make certain rules case-insensitive and other rules case-sensitive, because there is no straightforward way to set IGNORECASE just for the pattern of a particular rule.14 To do this, use either character lists or tolower. However, one thing you can do with IGNORECASE only is dynamically turn case-sensitivity on or off for all the rules at once.

IGNORECASE can be set on the command line or in a BEGIN rule (see Other Command-Line Arguments; also see Startup and Cleanup Actions). Setting IGNORECASE from the command line is a way to make a program case-insensitive without having to edit it.

Prior to gawk 3.0, the value of IGNORECASE affected regexp operations only. It did not affect string comparison with ==, !=, and so on. Beginning with version 3.0, both regexp and string comparison operations are also affected by IGNORECASE.

Beginning with gawk 3.0, the equivalences between upper- and lowercase characters are based on the ISO-8859-1 (ISO Latin-1) character set. This character set is a superset of the traditional 128 ASCII characters, which also provides a number of characters suitable for use with European languages.

The value of IGNORECASE has no effect if gawk is in compatibility mode (see Command-Line Options). Case is always significant in compatibility mode.

Node:Leftmost Longest, Next:Computed Regexps, Previous:Case-sensitivity, Up:Regexp

How Much Text Matches?

Consider the following:

echo aaaabcd | awk '{ sub(/a+/, "<A>"); print }'

This example uses the sub function (which we haven't discussed yet; see String Manipulation Functions) to make a change to the input record. Here, the regexp /a+/ indicates "one or more a characters," and the replacement text is <A>.

The input contains four a characters. awk (and POSIX) regular expressions always match the leftmost, longest sequence of input characters that can match. Thus, all four a characters are replaced with <A> in this example:

$ echo aaaabcd | awk '{ sub(/a+/, "<A>"); print }'
-| <A>bcd

For simple match/no-match tests, this is not so important. But when doing text matching and substitutions with the match, sub, gsub, and gensub functions, it is very important. Understanding this principle is also important for regexp-based record and field splitting (see How Input Is Split into Records, and also see Specifying How Fields Are Separated).

Node:Computed Regexps, Previous:Leftmost Longest, Up:Regexp

Using Dynamic Regexps

The righthand side of a ~ or !~ operator need not be a regexp constant (i.e., a string of characters between slashes). It may be any expression. The expression is evaluated and converted to a string if necessary; the contents of the string are used as the regexp. A regexp that is computed in this way is called a dynamic regexp:

BEGIN { digits_regexp = "[[:digit:]]+" }
$0 ~ digits_regexp    { print }

This sets digits_regexp to a regexp that describes one or more digits, and tests whether the input record matches this regexp.

When using the ~ and !~ Caution: When using the ~ and !~ operators, there is a difference between a regexp constant enclosed in slashes and a string constant enclosed in double quotes. If you are going to use a string constant, you have to understand that the string is, in essence, scanned twice: the first time when awk reads your program, and the second time when it goes to match the string on the lefthand side of the operator with the pattern on the right. This is true of any string-valued expression (such as digits_regexp, shown previously), not just string constants.

What difference does it make if the string is scanned twice? The answer has to do with escape sequences, and particularly with backslashes. To get a backslash into a regular expression inside a string, you have to type two backslashes.

For example, /\*/ is a regexp constant for a literal *. Only one backslash is needed. To do the same thing with a string, you have to type "\\*". The first backslash escapes the second one so that the string actually contains the two characters \ and *.

Given that you can use both regexp and string constants to describe regular expressions, which should you use? The answer is "regexp constants," for several reasons:

  • String constants are more complicated to write and more difficult to read. Using regexp constants makes your programs less error-prone. Not understanding the difference between the two kinds of constants is a common source of errors.
  • It is more efficient to use regexp constants. awk can note that you have supplied a regexp and store it internally in a form that makes pattern matching more efficient. When using a string constant, awk must first convert the string into this internal form and then perform the pattern matching.
  • Using regexp constants is better form; it shows clearly that you intend a regexp match.

Advanced Notes: Using \n in Character Lists of Dynamic Regexps

Some commercial versions of awk do not allow the newline character to be used inside a character list for a dynamic regexp:

$ awk '$0 ~ "[ \t\n]"'
error--> awk: newline in character class [
error--> ]...
error-->  source line number 1
error-->  context is
error-->          >>>  <<<

But a newline in a regexp constant works with no problem:

$ awk '$0 ~ /[ \t\n]/'
here is a sample line
-| here is a sample line
Ctrl-d

gawk does not have this problem, and it isn't likely to occur often in practice, but it's worth noting for future reference.

Node:Reading Files, Next:Printing, Previous:Regexp, Up:Top

Reading Input Files

In the typical awk program, all input is read either from the standard input (by default, this is the keyboard, but often it is a pipe from another command) or from files whose names you specify on the awk command line. If you specify input files, awk reads them in order, processing all the data from one before going on to the next. The name of the current input file can be found in the built-in variable FILENAME (see Built-in Variables).

The input is read in units called records, and is processed by the rules of your program one record at a time. By default, each record is one line. Each record is automatically split into chunks called fields. This makes it more convenient for programs to work on the parts of a record.

On rare occasions, you may need to use the getline command. The getline command is valuable, both because it can do explicit input from any number of files, and because the files used with it do not have to be named on the awk command line (see Explicit Input with getline).

  • Records: Controlling how data is split into records.
  • Fields: An introduction to fields.
  • Nonconstant Fields: Nonconstant Field Numbers.
  • Changing Fields: Changing the Contents of a Field.
  • Field Separators: The field separator and how to change it.
  • Constant Size: Reading constant width data.
  • Multiple Line: Reading multi-line records.
  • Getline: Reading files under explicit program control using the getline function.

Node:Records, Next:Fields, Previous:Reading Files, Up:Reading Files

How Input Is Split into Records

The awk utility divides the input for your awk program into records and fields. awk keeps track of the number of records that have been read so far from the current input file. This value is stored in a built-in variable called FNR. It is reset to zero when a new file is started. Another built-in variable, NR, is the total number of input records read so far from all data files. It starts at zero, but is never automatically reset to zero.

Records are separated by a character called the record separator. By default, the record separator is the newline character. This is why records are, by default, single lines. A different character can be used for the record separator by assigning the character to the built-in variable RS.

Like any other variable, the value of RS can be changed in the awk program with the assignment operator, = (see Assignment Expressions). The new record-separator character should be enclosed in quotation marks, which indicate a string constant. Often the right time to do this is at the beginning of execution, before any input is processed, so that the very first record is read with the proper separator. To do this, use the special BEGIN pattern (see The BEGIN and END Special Patterns). For example:

awk 'BEGIN { RS = "/" }
     { print $0 }' BBS-list

changes the value of RS to "/", before reading any input. This is a string whose first character is a slash; as a result, records are separated by slashes. Then the input file is read, and the second rule in the awk program (the action with no pattern) prints each record. Because each print statement adds a newline at the end of its output, this awk program copies the input with each slash changed to a newline. Here are the results of running the program on BBS-list:

$ awk 'BEGIN { RS = "/" }
>      { print $0 }' BBS-list
-| aardvark     555-5553     1200
-| 300          B
-| alpo-net     555-3412     2400
-| 1200
-| 300     A
-| barfly       555-7685     1200
-| 300          A
-| bites        555-1675     2400
-| 1200
-| 300     A
-| camelot      555-0542     300               C
-| core         555-2912     1200
-| 300          C
-| fooey        555-1234     2400
-| 1200
-| 300     B
-| foot         555-6699     1200
-| 300          B
-| macfoo       555-6480     1200
-| 300          A
-| sdace        555-3430     2400
-| 1200
-| 300     A
-| sabafoo      555-2127     1200
-| 300          C
-|

Note that the entry for the camelot BBS is not split. In the original data file (see Data Files for the Examples), the line looks like this:

camelot      555-0542     300               C

It has one baud rate only, so there are no slashes in the record, unlike the others which have two or more baud rates. In fact, this record is treated as part of the record for the core BBS; the newline separating them in the output is the original newline in the data file, not the one added by awk when it printed the record!

Another way to change the record separator is on the command line, using the variable-assignment feature (see Other Command-Line Arguments):

awk '{ print $0 }' RS="/" BBS-list

This sets RS to / before processing BBS-list.

Using an unusual character such as / for the record separator produces correct behavior in the vast majority of cases. However, the following (extreme) pipeline prints a surprising 1:

$ echo | awk 'BEGIN { RS = "a" } ; { print NF }'
-| 1

There is one field, consisting of a newline. The value of the built-in variable NF is the number of fields in the current record.

Reaching the end of an input file terminates the current input record, even if the last character in the file is not the character in RS. (d.c.)

The empty string "" (a string without any characters) has a special meaning as the value of RS. It means that records are separated by one or more blank lines and nothing else. See Multiple-Line Records, for more details.

If you change the value of RS in the middle of an awk run, the new value is used to delimit subsequent records, but the record currently being processed, as well as records already processed, are not affected.

After the end of the record has been determined, gawk sets the variable RT to the text in the input that matched RS. When using gawk, the value of RS is not limited to a one-character string. It can be any regular expression (see Regular Expressions). In general, each record ends at the next string that matches the regular expression; the next record starts at the end of the matching string. This general rule is actually at work in the usual case, where RS contains just a newline: a record ends at the beginning of the next matching string (the next newline in the input), and the following record starts just after the end of this string (at the first character of the following line). The newline, because it matches RS, is not part of either record.

When RS is a single character, RT contains the same single character. However, when RS is a regular expression, RT contains the actual input text that matched the regular expression.

The following example illustrates both of these features. It sets RS equal to a regular expression that matches either a newline or a series of one or more uppercase letters with optional leading and/or trailing whitespace:

$ echo record 1 AAAA record 2 BBBB record 3 |
> gawk 'BEGIN { RS = "\n|( *[[:upper:]]+ *)" }
>             { print "Record =", $0, "and RT =", RT }'
-| Record = record 1 and RT =  AAAA
-| Record = record 2 and RT =  BBBB
-| Record = record 3 and RT =
-|

The final line of output has an extra blank line. This is because the value of RT is a newline, and the print statement supplies its own terminating newline. See A Simple Stream Editor, for a more useful example of RS as a regexp and RT.

The use of RS as a regular expression and the RT variable are gawk extensions; they are not available in compatibility mode (see Command-Line Options). In compatibility mode, only the first character of the value of RS is used to determine the end of the record.

Advanced Notes: RS = "\0" Is Not Portable

There are times when you might want to treat an entire data file as a single record. The only way to make this happen is to give RS a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary input files.

You might think that for text files, the NUL character, which consists of a character with all bits equal to zero, is a good value to use for RS in this case:

BEGIN { RS = "\0" }  # whole file becomes one record?

gawk in fact accepts this, and uses the NUL character for the record separator. However, this usage is not portable to other awk implementations.

All other awk implementations15 store strings internally as C-style strings. C strings use the NUL character as the string terminator. In effect, this means that RS = "\0" is the same as RS = "". (d.c.)

The best way to treat a whole file as a single record is to simply read the file in, one record at a time, concatenating each record onto the end of the previous ones.

Node:Fields, Next:Nonconstant Fields, Previous:Records, Up:Reading Files

Examining Fields

When awk reads an input record, the record is automatically parsed or separated by the interpreter into chunks called fields. By default, fields are separated by whitespace, like words in a line. Whitespace in awk means any string of one or more spaces, tabs, or newlines;16 other characters, such as formfeed, vertical tab, etc. that are considered whitespace by other languages, are not considered whitespace by awk.

The purpose of fields is to make it more convenient for you to refer to these pieces of the record. You don't have to use them--you can operate on the whole record if you want--but fields are what make simple awk programs so powerful.

A dollar-sign ($) is used to refer to a field in an awk program, followed by the number of the field you want. Thus, $1 refers to the first field, $2 to the second, and so on. (Unlike the Unix shells, the field numbers are not limited to single digits. $127 is the one hundred twenty-seventh field in the record.) For example, suppose the following is a line of input:

This seems like a pretty nice example.

Here the first field, or $1, is This, the second field, or $2, is seems, and so on. Note that the last field, $7, is example.. Because there is no space between the e and the ., the period is considered part of the seventh field.

NF is a built-in variable whose value is the number of fields in the current record. awk automatically updates the value of NF each time it reads a record. No matter how many fields there are, the last field in a record can be represented by $NF. So, $NF is the same as $7, which is example.. If you try to reference a field beyond the last one (such as $8 when the record has only seven fields), you get the empty string. (If used in a numeric operation, you get zero.)

The use of $0, which looks like a reference to the "zero-th" field, is a special case: it represents the whole input record when you are not interested in specific fields. Here are some more examples:

$ awk '$1 ~ /foo/ { print $0 }' BBS-list
-| fooey        555-1234     2400/1200/300     B
-| foot         555-6699     1200/300          B
-| macfoo       555-6480     1200/300          A
-| sabafoo      555-2127     1200/300          C

This example prints each record in the file BBS-list whose first field contains the string foo. The operator ~ is called a matching operator (see How to Use Regular Expressions); it tests whether a string (here, the field $1) matches a given regular expression.

By contrast, the following example looks for foo in the entire record and prints the first field and the last field for each matching input record:

$ awk '/foo/ { print $1, $NF }' BBS-list
-| fooey B
-| foot B
-| macfoo A
-| sabafoo C

Node:Nonconstant Fields, Next:Changing Fields, Previous:Fields, Up:Reading Files

Nonconstant Field Numbers

The number of a field does not need to be a constant. Any expression in the awk language can be used after a $ to refer to a field. The value of the expression specifies the field number. If the value is a string, rather than a number, it is converted to a number. Consider this example:

awk '{ print $NR }'

Recall that NR is the number of records read so far: one in the first record, two in the second, etc. So this example prints the first field of the first record, the second field of the second record, and so on. For the twentieth record, field number 20 is printed; most likely, the record has fewer than 20 fields, so this prints a blank line. Here is another example of using expressions as field numbers:

awk '{ print $(2*2) }' BBS-list

awk evaluates the expression (2*2) and uses its value as the number of the field to print. The * sign represents multiplication, so the expression 2*2 evaluates to four. The parentheses are used so that the multiplication is done before the $ operation; they are necessary whenever there is a binary operator in the field-number expression. This example, then, prints the hours of operation (the fourth field) for every line of the file BBS-list. (All of the awk operators are listed, in order of decreasing precedence, in Operator Precedence (How Operators Nest).)

If the field number you compute is zero, you get the entire record. Thus, $(2-2) has the same value as $0. Negative field numbers are not allowed; trying to reference one usually terminates the program. (The POSIX standard does not define what happens when you reference a negative field number. gawk notices this and terminates your program. Other awk implementations may behave differently.)

As mentioned in Examining Fields, awk stores the current record's number of fields in the built-in variable NF (also see Built-in Variables). The expression $NF is not a special feature--it is the direct consequence of evaluating NF and using its value as a field number.

Node:Changing Fields, Next:Field Separators, Previous:Nonconstant Fields, Up:Reading Files

Changing the Contents of a Field

The contents of a field, as seen by awk, can be changed within an awk program; this changes what awk perceives as the current input record. (The actual input is untouched; awk never modifies the input file.) Consider the following example and its output:

$ awk '{ nboxes = $3 ; $3 = $3 - 10
>        print nboxes, $3 }' inventory-shipped
-| 13 3
-| 15 5
-| 15 5
...

The program first saves the original value of field three in the variable nboxes. The - sign represents subtraction, so this program reassigns field three, $3, as the original value of field three minus ten: $3 - 10. (See Arithmetic Operators.) Then it prints the original and new values for field three. (Someone in the warehouse made a consistent mistake while inventorying the red boxes.)

For this to work, the text in field $2 must make sense as a number; the string of characters must be converted to a number for the computer to do arithmetic on it. The number resulting from the subtraction is converted back to a string of characters that then becomes field three. See Conversion of Strings and Numbers.

When the value of a field is changed (as perceived by awk), the text of the input record is recalculated to contain the new field where the old one was. In other words, $0 changes to reflect the altered field. Thus, this program prints a copy of the input file, with 10 subtracted from the second field of each line:

$ awk '{ $2 = $2 - 10; print $0 }' inventory-shipped
-| Jan 3 25 15 115
-| Feb 5 32 24 226
-| Mar 5 24 34 228
...

It is also possible to also assign contents to fields that are out of range. For example:

$ awk '{ $6 = ($5 + $4 + $3 + $2)
>        print $6 }' inventory-shipped
-| 168
-| 297
-| 301
...

We've just created $6, whose value is the sum of fields $2, $3, $4, and $5. The + sign represents addition. For the file inventory-shipped, $6 represents the total number of parcels shipped for a particular month.

Creating a new field changes awk's internal copy of the current input record, which is the value of $0. Thus, if you do print $0 after adding a field, the record printed includes the new field, with the appropriate number of field separators between it and the previously existing fields.

This recomputation affects and is affected by NF (the number of fields; see Examining Fields). It is also affected by a feature that has not been discussed yet: the output field separator, OFS, used to separate the fields (see Output Separators). For example, the value of NF is set to the number of the highest field you create.

Note, however, that merely referencing an out-of-range field does not change the value of either $0 or NF. Referencing an out-of-range field only produces an empty string. For example:

if ($(NF+1) != "")
    print "can't happen"
else
    print "everything is normal"

should print everything is normal, because NF+1 is certain to be out of range. (See The if-else Statement, for more information about awk's if-else statements. See Variable Typing and Comparison Expressions, for more information about the != operator.)

It is important to note that making an assignment to an existing field changes the value of $0 but does not change the value of NF, even when you assign the empty string to a field. For example:

$ echo a b c d | awk '{ OFS = ":"; $2 = ""
>                       print $0; print NF }'
-| a::c:d
-| 4

The field is still there; it just has an empty value, denoted by the two colons between a and c. This example shows what happens if you create a new field:

$ echo a b c d | awk '{ OFS = ":"; $2 = ""; $6 = "new"
>                       print $0; print NF }'
-| a::c:d::new
-| 6

The intervening field, $5, is created with an empty value (indicated by the second pair of adjacent colons), and NF is updated with the value six.

Decrementing NF throws away the values of the fields after the new value of NF and recomputes $0. (d.c.) Here is an example:

$ echo a b c d e f | awk '{ print "NF =", NF;
>                            NF = 3; print $0 }'
-| NF = 6
-| a b c

Caution: Some versions of awk don't rebuild $0 when NF is decremented. Caveat emptor.

Node:Field Separators, Next:Constant Size, Previous:Changing Fields, Up:Reading Files

Specifying How Fields Are Separated

  • Regexp Field Splitting: Using regexps as the field separator.
  • Single Character Fields: Making each character a separate field.
  • Command Line Field Separator: Setting FS from the command-line.
  • Field Splitting Summary: Some final points and a summary table.

The field separator, which is either a single character or a regular expression, controls the way awk splits an input record into fields. awk scans the input record for character sequences that match the separator; the fields themselves are the text between the matches.

In the examples that follow, we use the bullet symbol (•) to represent spaces in the output. If the field separator is oo, then the following line:

moo goo gai pan

is split into three fields: m, •g, and •gai•pan. Note the leading spaces in the values of the second and third fields.

The field separator is represented by the built-in variable FS. Shell programmers take note: awk does not use the name IFS that is used by the POSIX-compliant shells (such as the Unix Bourne shell, sh, or bash).

The value of FS can be changed in the awk program with the assignment operator, = (see Assignment Expressions). Often the right time to do this is at the beginning of execution before any input has been processed, so that the very first record is read with the proper separator. To do this, use the special BEGIN pattern (see The BEGIN and END Special Patterns). For example, here we set the value of FS to the string ",":

awk 'BEGIN { FS = "," } ; { print $2 }'

Given the input line:

John Q. Smith, 29 Oak St., Walamazoo, MI 42139

this awk program extracts and prints the string •29•Oak•St..

Sometimes the input data contains separator characters that don't separate fields the way you thought they would. For instance, the person's name in the example we just used might have a title or suffix attached, such as:

John Q. Smith, LXIX, 29 Oak St., Walamazoo, MI 42139

The same program would extract •LXIX, instead of •29•Oak•St.. If you were expecting the program to print the address, you would be surprised. The moral is to choose your data layout and separator characters carefully to prevent such problems. (If the data is not in a form that is easy to process, perhaps you can massage it first with a separate awk program.)

Fields are normally separated by whitespace sequences (spaces, tabs, and newlines), not by single spaces. Two spaces in a row do not delimit an empty field. The default value of the field separator FS is a string containing a single space, " ". If awk interpreted this value in the usual way, each space character would separate fields, so two spaces in a row would make an empty field between them. The reason this does not happen is that a single space as the value of FS is a special case--it is taken to specify the default manner of delimiting fields.

If FS is any other single character, such as ",", then each occurrence of that character separates two fields. Two consecutive occurrences delimit an empty field. If the character occurs at the beginning or the end of the line, that too delimits an empty field. The space character is the only single character that does not follow these rules.

Node:Regexp Field Splitting, Next:Single Character Fields, Previous:Field Separators, Up:Field Separators

Using Regular Expressions to Separate Fields

The previous subsection discussed the use of single characters or simple strings as the value of FS. More generally, the value of FS may be a string containing any regular expression. In this case, each match in the record for the regular expression separates fields. For example, the assignment:

FS = ", \t"

makes every area of an input line that consists of a comma followed by a space and a TAB into a field separator.

For a less trivial example of a regular expression, try using single spaces to separate fields the way single commas are used. FS can be set to "[ ]" (left bracket, space, right bracket). This regular expression matches a single space and nothing else (see Regular Expressions).

There is an important difference between the two cases of FS = " " (a single space) and FS = "[ \t\n]+" (a regular expression matching one or more spaces, tabs, or newlines). For both values of FS, fields are separated by runs (multiple adjacent occurrences) of spaces, tabs, and/or newlines. However, when the value of FS is " ", awk first strips leading and trailing whitespace from the record and then decides where the fields are. For example, the following pipeline prints b:

$ echo ' a b c d ' | awk '{ print $2 }'
-| b

However, this pipeline prints a (note the extra spaces around each letter):

$ echo ' a  b  c  d ' | awk 'BEGIN { FS = "[ \t\n]+" }
>                                  { print $2 }'
-| a

In this case, the first field is null or empty.

The stripping of leading and trailing whitespace also comes into play whenever $0 is recomputed. For instance, study this pipeline:

$ echo '   a b c d' | awk '{ print; $2 = $2; print }'
-|    a b c d
-| a b c d

The first print statement prints the record as it was read, with leading whitespace intact. The assignment to $2 rebuilds $0 by concatenating $1 through $NF together, separated by the value of OFS. Because the leading whitespace was ignored when finding $1, it is not part of the new $0. Finally, the last print statement prints the new $0.

Node:Single Character Fields, Next:Command Line Field Separator, Previous:Regexp Field Splitting, Up:Field Separators

Making Each Character a Separate Field

There are times when you may want to examine each character of a record separately. This can be done in gawk by simply assigning the null string ("") to FS. In this case, each individual character in the record becomes a separate field. For example:

$ echo a b | gawk 'BEGIN { FS = "" }
>                  {
>                      for (i = 1; i <= NF; i = i + 1)
>                          print "Field", i, "is", $i
>                  }'
-| Field 1 is a
-| Field 2 is
-| Field 3 is b

Traditionally, the behavior of FS equal to "" was not defined. In this case, most versions of Unix awk simply treat the entire record as only having one field. (d.c.) In compatibility mode (see Command-Line Options), if FS is the null string, then gawk also behaves this way.

Node:Command Line Field Separator, Next:Field Splitting Summary, Previous:Single Character Fields, Up:Field Separators

Setting FS from the Command Line

FS can be set on the command line. Use the -F option to do so. For example:

awk -F, 'program' input-files

sets FS to the , character. Notice that the option uses an uppercase F instead of a lowercase f. The latter option (-f) specifies a file containing an awk program. Case is significant in command-line options: the -F and -f options have nothing to do with each other. You can use both options at the same time to set the FS variable and get an awk program from a file.

The value used for the argument to -F is processed in exactly the same way as assignments to the built-in variable FS. Any special characters in the field separator must be escaped appropriately. For example, to use a \ as the field separator on the command line, you would have to type:

# same as FS = "\\"
awk -F\\\\ '...' files ...

Because \ is used for quoting in the shell, awk sees -F\\. Then awk processes the \\ for escape characters (see Escape Sequences), finally yielding a single \ to use for the field separator.

As a special case, in compatibility mode (see Command-Line Options), if the argument to -F is t, then FS is set to the TAB character. If you type -F\t at the shell, without any quotes, the \ gets deleted, so awk figures that you really want your fields to be separated with tabs and not ts. Use -v FS="t" or -F"[t]" on the command line if you really do want to separate your fields with ts.

For example, let's use an awk program file called baud.awk that contains the pattern /300/ and the action print $1:

/300/   { print $1 }

Let's also set FS to be the - character and run the program on the file BBS-list. The following command prints a list of the names of the bulletin boards that operate at 300 baud and the first three digits of their phone numbers:

$ awk -F- -f baud.awk BBS-list
-| aardvark     555
-| alpo
-| barfly       555
-| bites        555
-| camelot      555
-| core         555
-| fooey        555
-| foot         555
-| macfoo       555
-| sdace        555
-| sabafoo      555

Note the second line of output. The second line in the original file looked like this:

alpo-net     555-3412     2400/1200/300     A

The - as part of the system's name was used as the field separator, instead of the - in the phone number that was originally intended. This demonstrates why you have to be careful in choosing your field and record separators.

Perhaps the most common use of a single character as the field separator occurs when processing the Unix system password file. On many Unix systems, each user has a separate entry in the system password file, one line per user. The information in these lines is separated by colons. The first field is the user's logon name and the second is the user's (encrypted or shadow) password. A password file entry might look like this:

arnold:xyzzy:2076:10:Arnold Robbins:/home/arnold:/bin/bash

The following program searches the system password file and prints the entries for users who have no password:

awk -F: '$2 == ""' /etc/passwd

Node:Field Splitting Summary, Previous:Command Line Field Separator, Up:Field Separators

Field-Splitting Summary

The following table summarizes how fields are split, based on the value of FS (== means "is equal to"):

FS == " "
Fields are separated by runs of whitespace. Leading and trailing whitespace are ignored. This is the default.
FS == any other single character
Fields are separated by each occurrence of the character. Multiple successive occurrences delimit empty fields, as do leading and trailing occurrences. The character can even be a regexp metacharacter; it does not need to be escaped.
FS == regexp
Fields are separated by occurrences of characters that match regexp. Leading and trailing matches of regexp delimit empty fields.
FS == ""
Each individual character in the record becomes a separate field. (This is a gawk extension; it is not specified by the POSIX standard.)

Advanced Notes: Changing FS Does Not Affect the Fields

According to the POSIX standard, awk is supposed to behave as if each record is split into fields at the time it is read. In particular, this means that if you change the value of FS after a record is read, the value of the fields (i.e., how they were split) should reflect the old value of FS, not the new one.

However, many implementations of awk do not work this way. Instead, they defer splitting the fields until a field is actually referenced. The fields are split using the current value of FS! (d.c.) This behavior can be difficult to diagnose. The following example illustrates the difference between the two methods. (The sed 17 command prints just the first line of /etc/passwd.)

sed 1q /etc/passwd | awk '{ FS = ":" ; print $1 }'

which usually prints:

root

on an incorrect implementation of awk, while gawk prints something like:

root:nSijPlPhZZwgE:0:0:Root:/:

Node:Constant Size, Next:Multiple Line, Previous:Field Separators, Up:Reading Files

Reading Fixed-Width Data

Note: This section discusses an advanced feature of gawk. If you are a novice awk user, you might want to skip it on the first reading.

gawk version 2.13 introduced a facility for dealing with fixed-width fields with no distinctive field separator. For example, data of this nature arises in the input for old Fortran programs where numbers are run together, or in the output of programs that did not anticipate the use of their output as input for other programs.

An example of the latter is a table where all the columns are lined up by the use of a variable number of spaces and empty fields are just spaces. Clearly, awk's normal field splitting based on FS does not work well in this case. Although a portable awk program can use a series of substr calls on $0 (see String Manipulation Functions), this is awkward and inefficient for a large number of fields.

The splitting of an input record into fixed-width fields is specified by assigning a string containing space-separated numbers to the built-in variable FIELDWIDTHS. Each number specifies the width of the field, including columns between fields. If you want to ignore the columns between fields, you can specify the width as a separate field that is subsequently ignored. It is a fatal error to supply a field width that is not a positive number. The following data is the output of the Unix w utility. It is useful to illustrate the use of FIELDWIDTHS:

 10:06pm  up 21 days, 14:04,  23 users
User     tty       login  idle   JCPU   PCPU  what
hzuo     ttyV0     8:58pm            9      5  vi p24.tex
hzang    ttyV3     6:37pm    50                -csh
eklye    ttyV5     9:53pm            7      1  em thes.tex
dportein ttyV6     8:17pm  1:47                -csh
gierd    ttyD3    10:00pm     1                elm
dave     ttyD4     9:47pm            4      4  w
brent    ttyp0    26Jun91  4:46  26:46   4:41  bash
dave     ttyq4    26Jun9115days     46     46  wnewmail

The following program takes the above input, converts the idle time to number of seconds, and prints out the first two fields and the calculated idle time:

Note: This program uses a number of awk features that haven't been introduced yet.

BEGIN  { FIELDWIDTHS = "9 6 10 6 7 7 35" }
NR > 2 {
    idle = $4
    sub(/^  */, "", idle)   # strip leading spaces
    if (idle == "")
        idle = 0
    if (idle ~ /:/) {
        split(idle, t, ":")
        idle = t[1] * 60 + t[2]
    }
    if (idle ~ /days/)
        idle *= 24 * 60 * 60

    print $1, $2, idle
}

Running the program on the data produces the following results:

hzuo      ttyV0  0
hzang     ttyV3  50
eklye     ttyV5  0
dportein  ttyV6  107
gierd     ttyD3  1
dave      ttyD4  0
brent     ttyp0  286
dave      ttyq4  1296000

Another (possibly more practical) example of fixed-width input data is the input from a deck of balloting cards. In some parts of the United States, voters mark their choices by punching holes in computer cards. These cards are then processed to count the votes for any particular candidate or on any particular issue. Because a voter may choose not to vote on some issue, any column on the card may be empty. An awk program for processing such data could use the FIELDWIDTHS feature to simplify reading the data. (Of course, getting gawk to run on a system with card readers is another story!)

Assigning a value to FS causes gawk to use FS for field splitting again. Use FS = FS to make this happen, without having to know the current value of FS. In order to tell which kind of field splitting is in effect, use PROCINFO["FS"] (see Built-in Variables That Convey Information). The value is "FS" if regular field splitting is being used, or it is "FIELDWIDTHS" if fixed-width field splitting is being used:

if (PROCINFO["FS"] == "FS")
    regular field splitting ...
else
    fixed-width field splitting ...

This information is useful when writing a function that needs to temporarily change FS or FIELDWIDTHS, read some records, and then restore the original settings (see Reading the User Database, for an example of such a function).

Node:Multiple Line, Next:Getline, Previous:Constant Size, Up:Reading Files

Multiple-Line Records

In some databases, a single line cannot conveniently hold all the information in one entry. In such cases, you can use multiline records. The first step in doing this is to choose your data format.

One technique is to use an unusual character or string to separate records. For example, you could use the formfeed character (written \f in awk, as in C) to separate them, making each record a page of the file. To do this, just set the variable RS to "\f" (a string containing the formfeed character). Any other character could equally well be used, as long as it won't be part of the data in a record.

Another technique is to have blank lines separate records. By a special dispensation, an empty string as the value of RS indicates that records are separated by one or more blank lines. When RS is set to the empty string, each record always ends at the first blank line encountered. The next record doesn't start until the first nonblank line that follows. No matter how many blank lines appear in a row, they all act as one record separator. (Blank lines must be completely empty; lines that contain only whitespace do not count.)

You can achieve the same effect as RS = "" by assigning the string "\n\n+" to RS. This regexp matches the newline at the end of the record and one or more blank lines after the record. In addition, a regular expression always matches the longest possible sequence when there is a choice (see How Much Text Matches?). So the next record doesn't start until the first nonblank line that follows--no matter how many blank lines appear in a row, they are considered one record separator.

There is an important difference between RS = "" and RS = "\n\n+". In the first case, leading newlines in the input data file are ignored, and if a file ends without extra blank lines after the last record, the final newline is removed from the record. In the second case, this special processing is not done. (d.c.)

Now that the input is separated into records, the second step is to separate the fields in the record. One way to do this is to divide each of the lines into fields in the normal manner. This happens by default as the result of a special feature. When RS is set to the empty string, the newline character always acts as a field separator. This is in addition to whatever field separations result from FS.

The original motivation for this special exception was probably to provide useful behavior in the default case (i.e., FS is equal to " "). This feature can be a problem if you really don't want the newline character to separate fields, because there is no way to prevent it. However, you can work around this by using the split function to break up the record manually (see String Manipulation Functions).

Another way to separate fields is to put each field on a separate line: to do this, just set the variable FS to the string "\n". (This simple regular expression matches a single newline.) A practical example of a data file organized this way might be a mailing list, where each entry is separated by blank lines. Consider a mailing list in a file named addresses, which looks like this:

Jane Doe
123 Main Street
Anywhere, SE 12345-6789

John Smith
456 Tree-lined Avenue
Smallville, MW 98765-4321
...

A simple program to process this file is as follows:

# addrs.awk --- simple mailing list program

# Records are separated by blank lines.
# Each line is one field.
BEGIN { RS = "" ; FS = "\n" }

{
      print "Name is:", $1
      print "Address is:", $2
      print "City and State are:", $3
      print ""
}

Running the program produces the following output:

$ awk -f addrs.awk addresses
-| Name is: Jane Doe
-| Address is: 123 Main Street
-| City and State are: Anywhere, SE 12345-6789
-|
-| Name is: John Smith
-| Address is: 456 Tree-lined Avenue
-| City and State are: Smallville, MW 98765-4321
-|
...

See Printing Mailing Labels, for a more realistic program that deals with address lists. The following table summarizes how records are split, based on the value of RS:

RS == "\n"
Records are separated by the newline character (\n). In effect, every line in the data file is a separate record, including blank lines. This is the default.
RS == any single character
Records are separated by each occurrence of the character. Multiple successive occurrences delimit empty records.
RS == ""
Records are separated by runs of blank lines. The newline character always serves as a field separator, in addition to whatever value FS may have. Leading and trailing newlines in a file are ignored.
RS == regexp
Records are separated by occurrences of characters that match regexp. Leading and trailing matches of regexp delimit empty records. (This is a gawk extension; it is not specified by the POSIX standard.)

In all cases, gawk sets RT to the input text that matched the value specified by RS.

Node:Getline, Previous:Multiple Line, Up:Reading Files

Explicit Input with getline

So far we have been getting our input data from awk's main input stream--either the standard input (usually your terminal, sometimes the output from another program) or from the files specified on the command line. The awk language has a special built-in command called getline that can be used to read input under your explicit control.

The getline command is used in several different ways and should not be used by beginners. The examples that follow the explanation of the getline command include material that has not been covered yet. Therefore, come back and study the getline command after you have reviewed the rest of this Web page and have a good knowledge of how awk works.

The getline command returns one if it finds a record and zero if it encounters the end of the file. If there is some error in getting a record, such as a file that cannot be opened, then getline returns -1. In this case, gawk sets the variable ERRNO to a string describing the error that occurred.

In the following examples, command stands for a string value that represents a shell command.

  • Plain Getline: Using getline with no arguments.
  • Getline/Variable: Using getline into a variable.
  • Getline/File: Using getline from a file.
  • Getline/Variable/File: Using getline into a variable from a file.
  • Getline/Pipe: Using getline from a pipe.
  • Getline/Variable/Pipe: Using getline into a variable from a pipe.
  • Getline/Coprocess: Using getline from a coprocess.
  • Getline/Variable/Coprocess: Using getline into a variable from a coprocess.
  • Getline Notes: Important things to know about getline.
  • Getline Summary: Summary of getline Variants.

Node:Plain Getline, Next:Getline/Variable, Previous:Getline, Up:Getline

Using getline with No Arguments

The getline command can be used without arguments to read input from the current input file. All it does in this case is read the next input record and split it up into fields. This is useful if you've finished processing the current record, but want to do some special processing on the next record right now. For example:

{
     if ((t = index($0, "/*")) != 0) {
          # value of `tmp' will be "" if t is 1
          tmp = substr($0, 1, t - 1)
          u = index(substr($0, t + 2), "*/")
          while (u == 0) {
               if (getline <= 0) {
                    m = "unexpected EOF or error"
                    m = (m ": " ERRNO)
                    print m > "/dev/stderr"
                    exit
               }
               t = -1
               u = index($0, "*/")
          }
          # substr expression will be "" if */
          # occurred at end of line
          $0 = tmp substr($0, u + 2)
     }
     print $0
}

This awk program deletes all C-style comments (/* ... */) from the input. By replacing the print $0 with other statements, you could perform more complicated processing on the decommented input, such as searching for matches of a regular expression. (This program has a subtle problem--it does not work if one comment ends and another begins on the same line.)

This form of the getline command sets NF, NR, FNR, and the value of $0.

Note: The new value of $0 is used to test the patterns of any subsequent rules. The original value of $0 that triggered the rule that executed getline is lost. By contrast, the next statement reads a new record but immediately begins processing it normally, starting with the first rule in the program. See The next Statement.

Node:Getline/Variable, Next:Getline/File, Previous:Plain Getline, Up:Getline

Using getline into a Variable

You can use getline var to read the next record from awk's input into the variable var. No other processing is done. For example, suppose the next line is a comment or a special string, and you want to read it without triggering any rules. This form of getline allows you to read that line and store it in a variable so that the main read-a-line-and-check-each-rule loop of awk never sees it. The following example swaps every two lines of input:

{
     if ((getline tmp) > 0) {
          print tmp
          print $0
     } else
          print $0
}

It takes the following list:

wan
tew
free
phore

and produces these results:

tew
wan
phore
free

The getline command used in this way sets only the variables NR and FNR (and of course, var). The record is not split into fields, so the values of the fields (including $0) and the value of NF do not change.

Node:Getline/File, Next:Getline/Variable/File, Previous:Getline/Variable, Up:Getline

Using getline from a File

Use getline < file to read the next record from file. Here file is a string-valued expression that specifies the file name. < file is called a redirection because it directs input to come from a different place. For example, the following program reads its input record from the file secondary.input when it encounters a first field with a value equal to 10 in the current input file:

{
    if ($1 == 10) {
         getline < "secondary.input"
         print
    } else
         print
}

Because the main input stream is not used, the values of NR and FNR are not changed. However, the record it reads is split into fields in the normal manner, so the values of $0 and the other fields are changed, resulting in a new value of NF.

According to POSIX, getline < expression is ambiguous if expression contains unparenthesized operators other than $; for example, getline < dir "/" file is ambiguous because the concatenation operator is not parenthesized. You should write it as getline < (dir "/" file) if you want your program to be portable to other awk implementations. (It happens that gawk gets it right, but you should not rely on this. Parentheses make it easier to read.)

Node:Getline/Variable/File, Next:Getline/Pipe, Previous:Getline/File, Up:Getline

Using getline into a Variable from a File

Use getline var < file to read input from the file file, and put it in the variable var. As above, file is a string-valued expression that specifies the file from which to read.

In this version of getline, none of the built-in variables are changed and the record is not split into fields. The only variable changed is var. For example, the following program copies all the input files to the output, except for records that say @include filename. Such a record is replaced by the contents of the file filename:

{
     if (NF == 2 && $1 == "@include") {
          while ((getline line < $2) > 0)
               print line
          close($2)
     } else
          print
}

Note here how the name of the extra input file is not built into the program; it is taken directly from the data, specifically from the second field on the @include line.

The close function is called to ensure that if two identical @include lines appear in the input, the entire specified file is included twice. See Closing Input and Output Redirections.

One deficiency of this program is that it does not process nested @include statements (i.e., @include statements in included files) the way a true macro preprocessor would. See An Easy Way to Use Library Functions, for a program that does handle nested @include statements.

Node:Getline/Pipe, Next:Getline/Variable/Pipe, Previous:Getline/Variable/File, Up:Getline

Using getline from a Pipe

The output of a command can also be piped into getline, using command | getline. In this case, the string command is run as a shell command and its output is piped into awk to be used as input. This form of getline reads one record at a time from the pipe. For example, the following program copies its input to its output, except for lines that begin with @execute, which are replaced by the output produced by running the rest of the line as a shell command:

{
     if ($1 == "@execute") {
          tmp = substr($0, 10)
          while ((tmp | getline) > 0)
               print
          close(tmp)
     } else
          print
}

The close function is called to ensure that if two identical @execute lines appear in the input, the command is run for each one. See Closing Input and Output Redirections. Given the input:

foo
bar
baz
@execute who
bletch

the program might produce:

foo
bar
baz
arnold     ttyv0   Jul 13 14:22
miriam     ttyp0   Jul 13 14:23     (murphy:0)
bill       ttyp1   Jul 13 14:23     (murphy:0)
bletch

Notice that this program ran the command who and printed the previous result. (If you try this program yourself, you will of course get different results, depending upon who is logged in on your system.)

This variation of getline splits the record into fields, sets the value of NF, and recomputes the value of $0. The values of NR and FNR are not changed.

According to POSIX, expression | getline is ambiguous if expression contains unparenthesized operators other than $--for example, "echo " "date" | getline is ambiguous because the concatenation operator is not parenthesized. You should write it as ("echo " "date") | getline if you want your program to be portable to other awk implementations.

Node:Getline/Variable/Pipe, Next:Getline/Coprocess, Previous:Getline/Pipe, Up:Getline

Using getline into a Variable from a Pipe

When you use command | getline var, the output of command is sent through a pipe to getline and into the variable var. For example, the following program reads the current date and time into the variable current_time, using the date utility, and then prints it:

BEGIN {
     "date" | getline current_time
     close("date")
     print "Report printed on " current_time
}

In this version of getline, none of the built-in variables are changed and the record is not split into fields.

Node:Getline/Coprocess, Next:Getline/Variable/Coprocess, Previous:Getline/Variable/Pipe, Up:Getline

Using getline from a Coprocess

Input into getline from a pipe is a one-way operation. The command that is started with command | getline only sends data to your awk program.

On occasion, you might want to send data to another program for processing and then read the results back. gawk allows you start a coprocess, with which two-way communications are possible. This is done with the |& operator. Typically, you write data to the coprocess first and then read results back, as shown in the following:

print "some query" |& "db_server"
"db_server" |& getline

which sends a query to db_server and then reads the results.

The values of NR and FNR are not changed, because the main input stream is not used. However, the record is split into fields in the normal manner, thus changing the values of $0, of the other fields, and of NF.

Coprocesses are an advanced feature. They are discussed here only because this is the section on getline. See Two-Way Communications with Another Process, where coprocesses are discussed in more detail.

Node:Getline/Variable/Coprocess, Next:Getline Notes, Previous:Getline/Coprocess, Up:Getline

Using getline into a Variable from a Coprocess

When you use command |& getline var, the output from the coprocess command is sent through a two-way pipe to getline and into the variable var.

In this version of getline, none of the built-in variables are changed and the record is not split into fields. The only variable changed is var.

Node:Getline Notes, Next:Getline Summary, Previous:Getline/Variable/Coprocess, Up:Getline

Points to Remember About getline

Here are some miscellaneous points about getline that you should bear in mind:

  • When getline changes the value of $0 and NF, awk does not automatically jump to the start of the program and start testing the new record against every pattern. However, the new record is tested against any subsequent rules.
  • Many awk implementations limit the number of pipelines that an awk program may have open to just one. In gawk, there is no such limit. You can open as many pipelines (and coprocesses) as the underlying operating system permits.
  • An interesting side effect occurs if you use getline without a redirection inside a BEGIN rule. Because an unredirected getline reads from the command-line data files, the first getline command causes awk to set the value of FILENAME. Normally, FILENAME does not have a value inside BEGIN rules, because you have not yet started to process the command-line data files. (d.c.) (See The BEGIN and END Special Patterns, also see Built-in Variables That Convey Information.)

Node:Getline Summary, Previous:Getline Notes, Up:Getline

Summary of getline Variants

The following table summarizes the eight variants of getline, listing which built-in variables are set by each one.

getline | Sets $0, NF, FNR, and NR
getline var | Sets var, FNR, and NR
getline < file | Sets $0 and NF
getline var < file | Sets var
command | getline | Sets $0 and NF
command | getline var | Sets var
command |& getline | Sets $0 and NF. This is a gawk extension
command |& getline var | Sets var. This is a gawk extension

Node:Printing, Next:Expressions, Previous:Reading Files, Up:Top

Printing Output

One of the most common programming actions is to print, or output, some or all of the input. Use the print statement for simple output, and the printf statement for fancier formatting. The print statement is not limited when computing which values to print. However, with two exceptions, you cannot specify how to print them--how many columns, whether to use exponential notation or not, and so on. (For the exceptions, see Output Separators, and Controlling Numeric Output with print.) For printing with specifications, you need the printf statement (see Using printf Statements for Fancier Printing).

Besides basic and formatted printing, this chapter also covers I/O redirections to files and pipes, introduces the special file names that gawk processes internally, and discusses the close built-in function.

  • Print: The print statement.
  • Print Examples: Simple examples of print statements.
  • Output Separators: The output separators and how to change them.
  • OFMT: Controlling Numeric Output With print.
  • Printf: The printf statement.
  • Redirection: How to redirect output to multiple files and pipes.
  • Special Files: File name interpretation in gawk. gawk allows access to inherited file descriptors.
  • Close Files And Pipes: Closing Input and Output Files and Pipes.

Node:Print, Next:Print Examples, Previous:Printing, Up:Printing

The print Statement

The print statement is used to produce output with simple, standardized formatting. Specify only the strings or numbers to print, in a list separated by commas. They are output, separated by single spaces, followed by a newline. The statement looks like this:

print item1, item2, ...

The entire list of items may be optionally enclosed in parentheses. The parentheses are necessary if any of the item expressions uses the > relational operator; otherwise it could be confused with a redirection (see Redirecting Output of print and printf).

The items to print can be constant strings or numbers, fields of the current record (such as $1), variables, or any awk expression. Numeric values are converted to strings and then printed.

The simple statement print with no items is equivalent to print $0: it prints the entire current record. To print a blank line, use print "", where "" is the empty string. To print a fixed piece of text, use a string constant, such as "Don't Panic", as one item. If you forget to use the double-quote characters, your text is taken as an awk expression, and you will probably get an error. Keep in mind that a space is printed between any two items.

Node:Print Examples, Next:Output Separators, Previous:Print, Up:Printing

Examples of print Statements

Each print statement makes at least one line of output. However, it isn't limited to only one line. If an item value is a string that contains a newline, the newline is output along with the rest of the string. A single print statement can make any number of lines this way.

The following is an example of printing a string that contains embedded newlines (the \n is an escape sequence, used to represent the newline character; see Escape Sequences):

$ awk 'BEGIN { print "line one\nline two\nline three" }'
-| line one
-| line two
-| line three

The next example, which is run on the inventory-shipped file, prints the first two fields of each input record, with a space between them:

$ awk '{ print $1, $2 }' inventory-shipped
-| Jan 13
-| Feb 15
-| Mar 15
...

A common mistake in using the print statement is to omit the comma between two items. This often has the effect of making the items run together in the output, with no space. The reason for this is that juxtaposing two string expressions in awk means to concatenate them. Here is the same program, without the comma:

$ awk '{ print $1 $2 }' inventory-shipped
-| Jan13
-| Feb15
-| Mar15
...

To someone unfamiliar with the inventory-shipped file, neither example's output makes much sense. A heading line at the beginning would make it clearer. Let's add some headings to our table of months ($1) and green crates shipped ($2). We do this using the BEGIN pattern (see The BEGIN and END Special Patterns) so that the headings are only printed once:

awk 'BEGIN {  print "Month Crates"
              print "----- ------" }
           {  print $1, $2 }' inventory-shipped

When run, the program prints the following:

Month Crates
----- ------
Jan 13
Feb 15
Mar 15
...

The only problem, however, is that the headings and the table data don't line up! We can fix this by printing some spaces between the two fields:

awk 'BEGIN { print "Month Crates"
             print "----- ------" }
           { print $1, "     ", $2 }' inventory-shipped

Lining up columns this way can get pretty complicated when there are many columns to fix. Counting spaces for two or three columns is simple, but any more than this can take up a lot of time. This is why the printf statement was created (see Using printf Statements for Fancier Printing); one of its specialties is lining up columns of data.

Note: You can continue either a print or printf statement simply by putting a newline after any comma (see awk Statements Versus Lines).

Node:Output Separators, Next:OFMT, Previous:Print Examples, Up:Printing

Output Separators

As mentioned previously, a print statement contains a list of items separated by commas. In the output, the items are normally separated by single spaces. However, this doesn't need to be the case; a single space is only the default. Any string of characters may be used as the output field separator by setting the built-in variable OFS. The initial value of this variable is the string " "--that is, a single space.

The output from an entire print statement is called an output record. Each print statement outputs one output record, and then outputs a string called the output record separator (or ORS). The initial value of ORS is the string "\n"; i.e., a newline character. Thus, each print statement normally makes a separate line.

In order to change how output fields and records are separated, assign new values to the variables OFS and ORS. The usual place to do this is in the BEGIN rule (see The BEGIN and END Special Patterns), so that it happens before any input is processed. It can also be done with assignments on the command line, before the names of the input files, or using the -v command-line option (see Command-Line Options). The following example prints the first and second fields of each input record, separated by a semicolon, with a blank line added after each newline:

$ awk 'BEGIN { OFS = ";"; ORS = "\n\n" }
>            { print $1, $2 }' BBS-list
-| aardvark;555-5553
-|
-| alpo-net;555-3412
-|
-| barfly;555-7685
...

If the value of ORS does not contain a newline, the program's output is run together on a single line.

Node:OFMT, Next:Printf, Previous:Output Separators, Up:Printing

Controlling Numeric Output with print

When the print statement is used to print numeric values, awk internally converts the number to a string of characters and prints that string. awk uses the sprintf function to do this conversion (see String Manipulation Functions). For now, it suffices to say that the sprintf function accepts a format specification that tells it how to format numbers (or strings), and that there are a number of different ways in which numbers can be formatted. The different format specifications are discussed more fully in Format-Control Letters.

The built-in variable OFMT contains the default format specification that print uses with sprintf when it wants to convert a number to a string for printing. The default value of OFMT is "%.6g". The way print prints numbers can be changed by supplying different format specifications as the value of OFMT, as shown in the following example:

$ awk 'BEGIN {
>   OFMT = "%.0f"  # print numbers as integers (rounds)
>   print 17.23, 17.54 }'
-| 17 18

According to the POSIX standard, awk's behavior is undefined if OFMT contains anything but a floating-point conversion specification. (d.c.)

Node:Printf, Next:Redirection, Previous:OFMT, Up:Printing

Using printf Statements for Fancier Printing

For more precise control over the output format than what is normally provided by print, use printf. printf can be used to specify the width to use for each item, as well as various formatting choices for numbers (such as what output base to use, whether to print an exponent, whether to print a sign, and how many digits to print after the decimal point). This is done by supplying a string, called the format string, that controls how and where to print the other arguments.

  • Basic Printf: Syntax of the printf statement.
  • Control Letters: Format-control letters.
  • Format Modifiers: Format-specification modifiers.
  • Printf Examples: Several examples.

Node:Basic Printf, Next:Control Letters, Previous:Printf, Up:Printf

Introduction to the printf Statement

A simple printf statement looks like this:

printf format, item1, item2, ...

The entire list of arguments may optionally be enclosed in parentheses. The parentheses are necessary if any of the item expressions use the > relational operator; otherwise, it can be confused with a redirection (see Redirecting Output of print and printf).

The difference between printf and print is the format argument. This is an expression whose value is taken as a string; it specifies how to output each of the other arguments. It is called the format string.

The format string is very similar to that in the ISO C library function printf. Most of format is text to output verbatim. Scattered among this text are format specifiers--one per item. Each format specifier says to output the next item in the argument list at that place in the format.

The printf statement does not automatically append a newline to its output. It outputs only what the format string specifies. So if a newline is needed, you must include one in the format string. The output separator variables OFS and ORS have no effect on printf statements. For example:

$ awk 'BEGIN {
>    ORS = "\nOUCH!\n"; OFS = "+"
>    msg = "Dont Panic!"
>    printf "%s\n", msg
> }'
-| Dont Panic!

Here, neither the + nor the OUCH appear when the message is printed.

Node:Control Letters, Next:Format Modifiers, Previous:Basic Printf, Up:Printf

Format-Control Letters

A format specifier starts with the character % and ends with a format-control letter--it tells the printf statement how to output one item. The format-control letter specifies what kind of value to print. The rest of the format specifier is made up of optional modifiers that control how to print the value, such as the field width. Here is a list of the format-control letters:

%c
This prints a number as an ASCII character; thus, printf "%c", 65 outputs the letter A. (The output for a string value is the first character of the string.)
%d, %i
These are equivalent; they both print a decimal integer. (The %i specification is for compatibility with ISO C.)
%e, %E
These print a number in scientific (exponential) notation; for example:
printf "%4.3e\n", 1950

prints 1.950e+03, with a total of four significant figures, three of which follow the decimal point. (The 4.3 represents two modifiers, discussed in the next subsection.) %E uses E instead of e in the output.

%f
This prints a number in floating-point notation. For example:
printf "%4.3f", 1950

prints 1950.000, with a total of four significant figures, three of which follow the decimal point. (The 4.3 represents two modifiers, discussed in the next subsection.)

%g, %G
These print a number in either scientific notation or in floating-point notation, whichever uses fewer characters; if the result is printed in scientific notation, %G uses E instead of e.
%o
This prints an unsigned octal integer.
%s
This prints a string.
%u
This prints an unsigned decimal integer. (This format is of marginal use, because all numbers in awk are floating-point; it is provided primarily for compatibility with C.)
%x, %X
These print an unsigned hexadecimal integer; %X uses the letters A through F instead of a through f.
%%
This isn't a format-control letter, but it does have meaning--the sequence %% outputs one %; it does not consume an argument and it ignores any modifiers.

Note: When using the integer format-control letters for values that are outside the range of a C long integer, gawk switches to the %g format specifier. Other versions of awk may print invalid values or do something else entirely. (d.c.)

Node:Format Modifiers, Next:Printf Examples, Previous:Control Letters, Up:Printf

Modifiers for printf Formats

A format specification can also include modifiers that can control how much of the item's value is printed, as well as how much space it gets. The modifiers come between the % and the format-control letter. We will use the bullet symbol "•" in the following examples to represent spaces in the output. Here are the possible modifiers, in the order in which they may appear:

N$
An integer constant followed by a $ is a positional specifier. Normally, format specifications are applied to arguments in the order given in the format string. With a positional specifier, the format specification is applied to a specific argument, instead of what would be the next argument in the list. Positional specifiers begin counting with one. Thus:
printf "%s %s\n", "don't", "panic"
printf "%2$s %1$s\n", "panic", "don't"

prints the famous friendly message twice.

At first glance, this feature doesn't seem to be of much use. It is in fact a gawk extension, intended for use in translating messages at runtime. See Rearranging printf Arguments, which describes how and why to use positional specifiers. For now, we will not use them.

-
The minus sign, used before the width modifier (see later on in this table), says to left-justify the argument within its specified width. Normally, the argument is printed right-justified in the specified width. Thus:
printf "%-4s", "foo"

prints foo•.

space
For numeric conversions, prefix positive values with a space and negative values with a minus sign.
+
The plus sign, used before the width modifier (see later on in this table), says to always supply a sign for numeric conversions, even if the data to format is positive. The + overrides the space modifier.
#
Use an "alternate form" for certain control letters. For %o, supply a leading zero. For %x and %X, supply a leading 0x or 0X for a nonzero result. For %e, %E, and %f, the result always contains a decimal point. For %g and %G, trailing zeros are not removed from the result.
0
A leading 0 (zero) acts as a flag that indicates that output should be padded with zeros instead of spaces. This applies even to non-numeric output formats. (d.c.) This flag only has an effect when the field width is wider than the value to print.
width
This is a number specifying the desired minimum width of a field. Inserting any number between the % sign and the format-control character forces the field to expand to this width. The default way to do this is to pad with spaces on the left. For example:
printf "%4s", "foo"

prints •foo.

The value of width is a minimum width, not a maximum. If the item value requires more than width characters, it can be as wide as necessary. Thus, the following:

printf "%4s", "foobar"

prints foobar.

Preceding the width with a minus sign causes the output to be padded with spaces on the right, instead of on the left.

.prec
A period followed by an integer constant specifies the precision to use when printing. The meaning of the precision varies by control letter:
%e, %E, %f
Number of digits to the right of the decimal point.
%g, %G
Maximum number of significant digits.
%d, %i, %o, %u, %x, %X
Minimum number of digits to print.
%s
Maximum number of characters from the string that should print.

Thus, the following:

printf "%.4s", "foobar"

prints foob.

The C library printf's dynamic width and prec capability (for example, "%*.*s") is supported. Instead of supplying explicit width and/or prec values in the format string, they are passed in the argument list. For example:

w = 5
p = 3
s = "abcdefg"
printf "%*.*s\n", w, p, s

is exactly equivalent to:

s = "abcdefg"
printf "%5.3s\n", s

Both programs output ••abc. Earlier versions of awk did not support this capability. If you must use such a version, you may simulate this feature by using concatenation to build up the format string, like so:

w = 5
p = 3
s = "abcdefg"
printf "%" w "." p "s\n", s

This is not particularly easy to read but it does work.

C programmers may be used to supplying additional l, L, and h modifiers in printf format strings. These are not valid in awk. Most awk implementations silently ignore these modifiers. If --lint is provided on the command line (see Command-Line Options), gawk warns about their use. If --posix is supplied, their use is a fatal error.

Node:Printf Examples, Previous:Format Modifiers, Up:Printf

Examples Using printf

The following is a simple example of how to use printf to make an aligned table:

awk '{ printf "%-10s %s\n", $1, $2 }' BBS-list

This command prints the names of the bulletin boards ($1) in the file BBS-list as a string of 10 characters that are left-justified. It also prints the phone numbers ($2) next on the line. This produces an aligned two-column table of names and phone numbers, as shown here:

$ awk '{ printf "%-10s %s\n", $1, $2 }' BBS-list
-| aardvark   555-5553
-| alpo-net   555-3412
-| barfly     555-7685
-| bites      555-1675
-| camelot    555-0542
-| core       555-2912
-| fooey      555-1234
-| foot       555-6699
-| macfoo     555-6480
-| sdace      555-3430
-| sabafoo    555-2127

In this case, the phone numbers had to be printed as strings because the numbers are separated by a dash. Printing the phone numbers as numbers would have produced just the first three digits: 555. This would have been pretty confusing.

It wasn't necessary to specify a width for the phone numbers because they are last on their lines. They don't need to have spaces after them.

The table could be made to look even nicer by adding headings to the tops of the columns. This is done using the BEGIN pattern (see The BEGIN and END Special Patterns) so that the headers are only printed once, at the beginning of the awk program:

awk 'BEGIN { print "Name      Number"
             print "----      ------" }
     { printf "%-10s %s\n", $1, $2 }' BBS-list

The above example mixed print and printf statements in the same program. Using just printf statements can produce the same results:

awk 'BEGIN { printf "%-10s %s\n", "Name", "Number"
             printf "%-10s %s\n", "----", "------" }
     { printf "%-10s %s\n", $1, $2 }' BBS-list

Printing each column heading with the same format specification used for the column elements ensures that the headings are aligned just like the columns.

The fact that the same format specification is used three times can be emphasized by storing it in a variable, like this:

awk 'BEGIN { format = "%-10s %s\n"
             printf format, "Name", "Number"
             printf format, "----", "------" }
     { printf format, $1, $2 }' BBS-list

At this point, it would be a worthwhile exercise to use the printf statement to line up the headings and table data for the inventory-shipped example that was covered earlier in the section on the print statement (see The print Statement).

Node:Redirection, Next:Special Files, Previous:Printf, Up:Printing

Redirecting Output of print and printf

So far, the output from print and printf has gone to the standard output, usually the terminal. Both print and printf can also send their output to other places. This is called redirection.

A redirection appears after the print or printf statement. Redirections in awk are written just like redirections in shell commands, except that they are written inside the awk program.

There are four forms of output redirection: output to a file, output appended to a file, output through a pipe to another command, and output to a coprocess. They are all shown for the print statement, but they work identically for printf:

print items > output-file
This type of redirection prints the items into the output file named output-file. The file name output-file can be any expression. Its value is changed to a string and then used as a file name (see Expressions).

When this type of redirection is used, the output-file is erased before the first output is written to it. Subsequent writes to the same output-file do not erase output-file, but append to it. (This is different from how you use redirections in shell scripts.) If output-file does not exist, it is created. For example, here is how an awk program can write a list of BBS names to one file named name-list, and a list of phone numbers to another file named phone-list:

$ awk '{ print $2 > "phone-list"
>        print $1 > "name-list" }' BBS-list
$ cat phone-list
-| 555-5553
-| 555-3412
...
$ cat name-list
-| aardvark
-| alpo-net
...

Each output file contains one name or number per line.

print items >> output-file
This type of redirection prints the items into the pre-existing output file named output-file. The difference between this and the single-> redirection is that the old contents (if any) of output-file are not erased. Instead, the awk output is appended to the file. If output-file does not exist, then it is created.
print items | command
It is also possible to send output to another program through a pipe instead of into a file. This type of redirection opens a pipe to command, and writes the values of items through this pipe to another process created to execute command.

The redirection argument command is actually an awk expression. Its value is converted to a string whose contents give the shell command to be run. For example, the following produces two files, one unsorted list of BBS names, and one list sorted in reverse alphabetical order:

awk '{ print $1 > "names.unsorted"
       command = "sort -r > names.sorted"
       print $1 | command }' BBS-list

The unsorted list is written with an ordinary redirection, while the sorted list is written by piping through the sort utility.

The next example uses redirection to mail a message to the mailing list bug-system. This might be useful when trouble is encountered in an awk script run periodically for system maintenance:

report = "mail bug-system"
print "Awk script failed:", $0 | report
m = ("at record number " FNR " of " FILENAME)
print m | report
close(report)

The message is built using string concatenation and saved in the variable m. It's then sent down the pipeline to the mail program. (The parentheses group the items to concatenate--see String Concatenation.)

The close function is called here because it's a good idea to close the pipe as soon as all the intended output has been sent to it. See Closing Input and Output Redirections, for more information.

This example also illustrates the use of a variable to represent a file or command--it is not necessary to always use a string constant. Using a variable is generally a good idea, because awk requires that the string value be spelled identically every time.

print items |& command
This type of redirection prints the items to the input of command. The difference between this and the single-| redirection is that the output from command can be read with getline. Thus command is a coprocess, which works together with, but subsidiary to, the awk program.

This feature is a gawk extension, and is not available in POSIX awk. See Two-Way Communications with Another Process, for a more complete discussion.

Redirecting output using >, >>, |, or |& asks the system to open a file, pipe, or coprocess only if the particular file or command you specify has not already been written to by your program or if it has been closed since it was last written to.

It is a common error to use > redirection for the first print to a file, and then to use >> for subsequent output:

# clear the file
print "Don't panic" > "guide.txt"
...
# append
print "Avoid improbability generators" >> "guide.txt"

This is indeed how redirections must be used from the shell. But in awk, it isn't necessary. In this kind of case, a program should use > for all the print statements, since the output file is only opened once.

As mentioned earlier (see Points About getline to Remember), many Many awk implementations limit the number of pipelines that an awk program may have open to just one! In gawk, there is no such limit. gawk allows a program to open as many pipelines as the underlying operating system permits.

Advanced Notes: Piping into sh

A particularly powerful way to use redirection is to build command lines and pipe them into the shell, sh. For example, suppose you have a list of files brought over from a system where all the file names are stored in uppercase, and you wish to rename them to have names in all lowercase. The following program is both simple and efficient:

{ printf("mv %s %s\n", $0, tolower($0)) | "sh" }

END { close("sh") }

The tolower function returns its argument string with all uppercase characters converted to lowercase (see String Manipulation Functions). The program builds up a list of command lines, using the mv utility to rename the files. It then sends the list to the shell for execution.

Node:Special Files, Next:Close Files And Pipes, Previous:Redirection, Up:Printing

Special File Names in gawk

gawk provides a number of special file names that it interprets internally. These file names provide access to standard file descriptors, process-related information, and TCP/IP networking.

  • Special FD: Special files for I/O.
  • Special Process: Special files for process information.
  • Special Network: Special files for network communications.
  • Special Caveats: Things to watch out for.

Node:Special FD, Next:Special Process, Previous:Special Files, Up:Special Files

Special Files for Standard Descriptors

Running programs conventionally have three input and output streams already available to them for reading and writing. These are known as the standard input, standard output, and standard error output. These streams are, by default, connected to your terminal, but they are often redirected with the shell, via the <, <<, >, >>, >&, and | operators. Standard error is typically used for writing error messages; the reason there are two separate streams, standard output and standard error, is so that they can be redirected separately.

In other implementations of awk, the only way to write an error message to standard error in an awk program is as follows:

print "Serious error detected!" | "cat 1>&2"

This works by opening a pipeline to a shell command that can access the standard error stream that it inherits from the awk process. This is far from elegant, and it is also inefficient, because it requires a separate process. So people writing awk programs often don't do this. Instead, they send the error messages to the terminal, like this:

print "Serious error detected!" > "/dev/tty"

This usually has the same effect but not always: although the standard error stream is usually the terminal, it can be redirected; when that happens, writing to the terminal is not correct. In fact, if awk is run from a background job, it may not have a terminal at all. Then opening /dev/tty fails.

gawk provides special file names for accessing the three standard streams, as well as any other inherited open files. If the file name matches one of these special names when gawk redirects input or output, then it directly uses the stream that the file name stands for. These special file names work for all operating systems that gawk has been ported to, not just those that are POSIX-compliant:

/dev/stdin
The standard input (file descriptor 0).
/dev/stdout
The standard output (file descriptor 1).
/dev/stderr
The standard error output (file descriptor 2).
/dev/fd/N
The file associated with file descriptor N. Such a file must be opened by the program initiating the awk execution (typically the shell). Unless special pains are taken in the shell from which gawk is invoked, only descriptors 0, 1, and 2 are available.

The file names /dev/stdin, /dev/stdout, and /dev/stderr are aliases for /dev/fd/0, /dev/fd/1, and /dev/fd/2, respectively. However, they are more self-explanatory. The proper way to write an error message in a gawk program is to use /dev/stderr, like this:

print "Serious error detected!" > "/dev/stderr"

Note the use of quotes around the file name. Like any other redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results.

Node:Special Process, Next:Special Network, Previous:Special FD, Up:Special Files

Special Files for Process-Related Information

gawk also provides special file names that give access to information about the running gawk process. Each of these "files" provides a single record of information. To read them more than once, they must first be closed with the close function (see Closing Input and Output Redirections). The file names are:

/dev/pid
Reading this file returns the process ID of the current process, in decimal form, terminated with a newline.
/dev/ppid
Reading this file returns the parent process ID of the current process, in decimal form, terminated with a newline.
/dev/pgrpid
Reading this file returns the process group ID of the current process, in decimal form, terminated with a newline.
/dev/user
Reading this file returns a single record terminated with a newline. The fields are separated with spaces. The fields represent the following information:
$1
The return value of the getuid system call (the real user ID number).
$2
The return value of the geteuid system call (the effective user ID number).
$3
The return value of the getgid system call (the real group ID number).
$4
The return value of the getegid system call (the effective group ID number).

If there are any additional fields, they are the group IDs returned by the getgroups system call. (Multiple groups may not be supported on all systems.)

These special file names may be used on the command line as data files, as well as for I/O redirections within an awk program. They may not be used as source files with the -f option.

Note: The special files that provide process-related information are now considered obsolete and will disappear entirely in the next release of gawk. gawk prints a warning message every time you use one of these files. To obtain process-related information, use the PROCINFO array. See Built-in Variables That Convey Information.

Node:Special Network, Next:Special Caveats, Previous:Special Process, Up:Special Files

Special Files for Network Communications

Starting with version 3.1 of gawk, awk programs can open a two-way TCP/IP connection, acting as either a client or a server. This is done using a special file name of the form:

/inet/protocol/local-port/remote-host/remote-port

The protocol is one of tcp, udp, or raw, and the other fields represent the other essential pieces of information for making a networking connection. These file names are used with the |& operator for communicating with a coprocess (see Two-Way Communications with Another Process). This is an advanced feature, mentioned here only for completeness. Full discussion is delayed until Using gawk for Network Programming.

Node:Special Caveats, Previous:Special Network, Up:Special Files

Special File Name Caveats

Here is a list of things to bear in mind when using the special file names that gawk provides:

  • Recognition of these special file names is disabled if gawk is in compatibility mode (see Command-Line Options).
  • The As mentioned earlier, the special files that provide process-related information are now considered obsolete and will disappear entirely in the next release of gawk. gawk prints a warning message every time you use one of these files. To obtain process-related information, use the PROCINFO array. See Built-in Variables.
  • Starting with version 3.1, gawk always interprets these special file names.18 For example, using /dev/fd/4 for output actually writes on file descriptor 4, and not on a new file descriptor that is dup'ed from file descriptor 4. Most of the time this does not matter; however, it is important to not close any of the files related to file descriptors 0, 1, and 2. Doing so results in unpredictable behavior.

Node:Close Files And Pipes, Previous:Special Files, Up:Printing

Closing Input and Output Redirections

If the same file name or the same shell command is used with getline more than once during the execution of an awk program (see Explicit Input with getline), the file is opened (or the command is executed) the first time only. At that time, the first record of input is read from that file or command. The next time the same file or command is used with getline, another record is read from it, and so on.

Similarly, when a file or pipe is opened for output, the file name or command associated with it is remembered by awk, and subsequent writes to the same file or command are appended to the previous writes. The file or pipe stays open until awk exits.

This implies that special steps are necessary in order to read the same file again from the beginning, or to rerun a shell command (rather than reading more output from the same command). The close function makes these things possible:

close(filename)

or:

close(command)

The argument filename or command can be any expression. Its value must exactly match the string that was used to open the file or start the command (spaces and other "irrelevant" characters included). For example, if you open a pipe with this:

"sort -r names" | getline foo

then you must close it with this:

close("sort -r names")

Once this function call is executed, the next getline from that file or command, or the next print or printf to that file or command, reopens the file or reruns the command. Because the expression that you use to close a file or pipeline must exactly match the expression used to open the file or run the command, it is good practice to use a variable to store the file name or command. The previous example becomes the following:

sortcom = "sort -r names"
sortcom | getline foo
...
close(sortcom)

This helps avoid hard-to-find typographical errors in your awk programs. Here are some of the reasons for closing an output file:

  • To write a file and read it back later on in the same awk program. Close the file after writing it, then begin reading it with getline.
  • To write numerous files, successively, in the same awk program. If the files aren't closed, eventually awk may exceed a system limit on the number of open files in one process. It is best to close each one when the program has finished writing it.
  • To make a command finish. When output is redirected through a pipe, the command reading the pipe normally continues to try to read input as long as the pipe is open. Often this means the command cannot really do its work until the pipe is closed. For example, if output is redirected to the mail program, the message is not actually sent until the pipe is closed.
  • To run the same program a second time, with the same arguments. This is not the same thing as giving more input to the first run!

    For example, suppose a program pipes output to the mail program. If it outputs several lines redirected to this pipe without closing it, they make a single message of several lines. By contrast, if the program closes the pipe after each line of output, then each line makes a separate message.

If you use more files than the system allows you to have open, gawk attempts to multiplex the available open files among your data files. gawk's ability to do this depends upon the facilities of your operating system, so it may not always work. It is therefore both good practice and good portability advice to always use close on your files when you are done with them. In fact, if you are using a lot of pipes, it is essential that you close commands when done. For example, consider something like this:

{
    ...
    command = ("grep " $1 " /some/file | my_prog -q " $3)
    while ((command | getline) > 0) {
        process output of command
    }
    # need close(command) here
}

This example creates a new pipeline based on data in each record. Without the call to close indicated in the comment, awk creates child processes to run the commands, until it eventually runs out of file descriptors for more pipelines.

Even though each command has finished (as indicated by the end-of-file return status from getline), the child process is not terminated;19 more importantly, the file descriptor for the pipe is not closed and released until close is called or awk exits.

close will silently do nothing if given an argument that does not represent a file, pipe or coprocess that was opened with a redirection.

When using the |& operator to communicate with a coprocess, it is occasionally useful to be able to close one end of the two-way pipe without closing the other. This is done by supplying a second argument to close. As in any other call to close, the first argument is the name of the command or special file used to start the coprocess. The second argument should be a string, with either of the values "to" or "from". Case does not matter. As this is an advanced feature, a more complete discussion is delayed until Two-Way Communications with Another Process, which discusses it in more detail and gives an example.

Advanced Notes: Using close's Return Value

In many versions of Unix awk, the close function is actually a statement. It is a syntax error to try and use the return value from close: (d.c.)

command = "..."
command | getline info
retval = close(command)  # syntax error in most Unix awks

gawk treats close as a function. The return value is -1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. In these cases, gawk sets the built-in variable ERRNO to a string describing the problem.

In gawk, when closing a pipe or coprocess, the return value is the exit status of the command. Otherwise, it is the return value from the system's close or fclose C functions when closing input or output files, respectively. This value is zero if the close succeeds, or -1 if it fails.

The return value for closing a pipeline is particularly useful. It allows you to get the output from a command as well as its exit status.

For POSIX-compliant systems, if the exit status is a number above 128, then the program was terminated by a signal. Subtract 128 to get the signal number:

exit_val = close(command)
if (exit_val > 128)
    print command, "died with signal", exit_val - 128
else
    print command, "exited with code", exit_val

Currently, in gawk, this only works for commands piping into getline. For commands piped into from print or printf, the return value from close is that of the library's pclose function.

Node:Expressions, Next:Patterns and Actions, Previous:Printing, Up:Top

Expressions

Expressions are the basic building blocks of awk patterns and actions. An expression evaluates to a value that you can print, test, or pass to a function. Additionally, an expression can assign a new value to a variable or a field by using an assignment operator.

An expression can serve as a pattern or action statement on its own. Most other kinds of statements contain one or more expressions that specify the data on which to operate. As in other languages, expressions in awk include variables, array references, constants, and function calls, as well as combinations of these with various operators.

  • Constants: String, numeric and regexp constants.
  • Using Constant Regexps: When and how to use a regexp constant.
  • Variables: Variables give names to values for later use.
  • Conversion: The conversion of strings to numbers and vice versa.
  • Arithmetic Ops: Arithmetic operations (+, -, etc.)
  • Concatenation: Concatenating strings.
  • Assignment Ops: Changing the value of a variable or a field.
  • Increment Ops: Incrementing the numeric value of a variable.
  • Truth Values: What is ``true'' and what is ``false''.
  • Typing and Comparison: How variables acquire types and how this affects comparison of numbers and strings with <, etc.
  • Boolean Ops: Combining comparison expressions using boolean operators || (``or''), && (``and'') and ! (``not'').
  • Conditional Exp: Conditional expressions select between two subexpressions under control of a third subexpression.
  • Function Calls: A function call is an expression.
  • Precedence: How various operators nest.

Node:Constants, Next:Using Constant Regexps, Previous:Expressions, Up:Expressions

Constant Expressions

The simplest type of expression is the constant, which always has the same value. There are three types of constants: numeric, string, and regular expression.

Each is used in the appropriate context when you need a data value that isn't going to change. Numeric constants can have different forms, but are stored identically internally.

  • Scalar Constants: Numeric and string constants.
  • Nondecimal-numbers: What are octal and hex numbers.
  • Regexp Constants: Regular Expression constants.

Node:Scalar Constants, Next:Nondecimal-numbers, Previous:Constants, Up:Constants

Numeric and String Constants

A numeric constant stands for a number. This number can be an integer, a decimal fraction, or a number in scientific (exponential) notation.20 Here are some examples of numeric constants that all have the same value:

105
1.05e+2
1050e-1

A string constant consists of a sequence of characters enclosed in double-quotation marks. For example:

"parrot"

represents the string whose contents are parrot. Strings in gawk can be of any length, and they can contain any of the possible eight-bit ASCII characters including ASCII NUL (character code zero). Other awk implementations may have difficulty with some character codes.

Node:Nondecimal-numbers, Next:Regexp Constants, Previous:Scalar Constants, Up:Constants

Octal and Hexadecimal Numbers

In awk, all numbers are in decimal; i.e., base 10. Many other programming languages allow you to specify numbers in other bases, often octal (base 8) and hexadecimal (base 16). In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc. Just as 11, in decimal, is 1 times 10 plus 1, so 11, in octal, is 1 times 8, plus 1. This equals 9 in decimal. In hexadecimal, there are 16 digits. Since the everyday decimal number system only has ten digits (0-9), the letters a through f are used to represent the rest. (Case in the letters is usually irrelevant; hexadecimal a and A have the same value.) Thus, 11, in hexadecimal, is 1 times 16 plus 1, which equals 17 in decimal.

Just by looking at plain 11, you can't tell what base it's in. So, in C, C++, and other languages derived from C, there is a special notation to help signify the base. Octal numbers start with a leading 0, and hexadecimal numbers start with a leading 0x or 0X:

11
Decimal value 11.
011
Octal 11, decimal value 9.
0x11
Hexadecimal 11, decimal value 17.

This example shows the difference:

$ gawk 'BEGIN { printf "%d, %d, %d\n", 011, 11, 0x11 }'
-| 9, 11, 17

Being able to use octal and hexadecimal constants in your programs is most useful when working with data that cannot be represented conveniently as characters or as regular numbers, such as binary data of various sorts.

gawk allows the use of octal and hexadecimal constants in your program text. However, such numbers in the input data are not treated differently; doing so by default would break old programs. (If you really need to do this, use the --non-decimal-data command-line option; see Allowing Nondecimal Input Data.) If you have octal or hexadecimal data, you can use the strtonum function (see String Manipulation Functions) to convert the data into a number. Most of the time, you will want to use octal or hexadecimal constants when working with the built-in bit manipulation functions; see Using gawk's Bit Manipulation Functions, for more information.

Unlike some early C implementations, 8 and 9 are not valid in octal constants; e.g., gawk treats 018 as decimal 18:

$ gawk 'BEGIN { print "021 is", 021 ; print 018 }'
-| 021 is 17
-| 18

Octal and hexadecimal source code constants are a gawk extension. If gawk is in compatibility mode (see Command-Line Options), they are not available.

Advanced Notes: A Constant's Base Does Not Affect Its Value

Once a numeric constant has been converted internally into a number, gawk no longer remembers what the original form of the constant was; the internal value is always used. This has particular consequences for conversion of numbers to strings:

$ gawk 'BEGIN { printf "0x11 is <%s>\n", 0x11 }'
-| 0x11 is <17>

Node:Regexp Constants, Previous:Nondecimal-numbers, Up:Constants

Regular Expression Constants

A regexp constant is a regular expression description enclosed in slashes, such as /^beginning and end$/. Most regexps used in awk programs are constant, but the ~ and !~ matching operators can also match computed or "dynamic" regexps (which are just ordinary strings or variables that contain a regexp).

Node:Using Constant Regexps, Next:Variables, Previous:Constants, Up:Expressions

Using Regular Expression Constants

When used on the righthand side of the ~ or !~ operators, a regexp constant merely stands for the regexp that is to be matched. However, regexp constants (such as /foo/) may be used like simple expressions. When a regexp constant appears by itself, it has the same meaning as if it appeared in a pattern, i.e., ($0 ~ /foo/) (d.c.) See Expressions as Patterns. This means that the following two code segments:

if ($0 ~ /barfly/ || $0 ~ /camelot/)
    print "found"

and:

if (/barfly/ || /camelot/)
    print "found"

are exactly equivalent. One rather bizarre consequence of this rule is that the following Boolean expression is valid, but does not do what the user probably intended:

# note that /foo/ is on the left of the ~
if (/foo/ ~ $1) print "found foo"

This code is "obviously" testing $1 for a match against the regexp /foo/. But in fact, the expression /foo/ ~ $1 actually means ($0 ~ /foo/) ~ $1. In other words, first match the input record against the regexp /foo/. The result is either zero or one, depending upon the success or failure of the match. That result is then matched against the first field in the record. Because it is unlikely that you would ever really want to make this kind of test, gawk issues a warning when it sees this construct in a program. Another consequence of this rule is that the assignment statement:

matches = /foo/

assigns either zero or one to the variable matches, depending upon the contents of the current input record. This feature of the language has never been well documented until the POSIX specification.

Constant regular expressions are also used as the first argument for the gensub, sub, and gsub functions, and as the second argument of the match function (see String Manipulation Functions). Modern implementations of awk, including gawk, allow the third argument of split to be a regexp constant, but some older implementations do not. (d.c.) This can lead to confusion when attempting to use regexp constants as arguments to user-defined functions (see User-Defined Functions). For example:

function mysub(pat, repl, str, global)
{
    if (global)
        gsub(pat, repl, str)
    else
        sub(pat, repl, str)
    return str
}

{
    ...
    text = "hi! hi yourself!"
    mysub(/hi/, "howdy", text, 1)
    ...
}

In this example, the programmer wants to pass a regexp constant to the user-defined function mysub, which in turn passes it on to either sub or gsub. However, what really happens is that the pat parameter is either one or zero, depending upon whether or not $0 matches /hi/. gawk issues a warning when it sees a regexp constant used as a parameter to a user-defined function, since passing a truth value in this way is probably not what was intended.

Node:Variables, Next:Conversion, Previous:Using Constant Regexps, Up:Expressions

Variables

Variables are ways of storing values at one point in your program for use later in another part of your program. They can be manipulated entirely within the program text, and they can also be assigned values on the awk command line.

  • Using Variables: Using variables in your programs.
  • Assignment Options: Setting variables on the command-line and a summary of command-line syntax. This is an advanced method of input.

Node:Using Variables, Next:Assignment Options, Previous:Variables, Up:Variables

Using Variables in a Program

Variables let you give names to values and refer to them later. Variables have already been used in many of the examples. The name of a variable must be a sequence of letters, digits, or underscores, and it may not begin with a digit. Case is significant in variable names; a and A are distinct variables.

A variable name is a valid expression by itself; it represents the variable's current value. Variables are given new values with assignment operators, increment operators, and decrement operators. See Assignment Expressions.

A few variables have special built-in meanings, such as FS (the field separator), and NF (the number of fields in the current input record). See Built-in Variables, for a list of the built-in variables. These built-in variables can be used and assigned just like all other variables, but their values are also used or changed automatically by awk. All built-in variables' names are entirely uppercase.

Variables in awk can be assigned either numeric or string values. The kind of value a variable holds can change over the life of a program. By default, variables are initialized to the empty string, which is zero if converted to a number. There is no need to "initialize" each variable explicitly in awk, which is what you would do in C and in most other traditional languages.

Node:Assignment Options, Previous:Using Variables, Up:Variables

Assigning Variables on the Command Line

Any awk variable can be set by including a variable assignment among the arguments on the command line when awk is invoked (see Other Command-Line Arguments). Such an assignment has the following form:

variable=text

With it, a variable is set either at the beginning of the awk run or in between input files. When the assignment is preceded with the -v option, as in the following:

-v variable=text

the variable is set at the very beginning, even before the BEGIN rules are run. The -v option and its assignment must precede all the file name arguments, as well as the program text. (See Command-Line Options, for more information about the -v option.) Otherwise, the variable assignment is performed at a time determined by its position among the input file arguments--after the processing of the preceding input file argument. For example:

awk '{ print $n }' n=4 inventory-shipped n=2 BBS-list

prints the value of field number n for all input records. Before the first file is read, the command line sets the variable n equal to four. This causes the fourth field to be printed in lines from the file inventory-shipped. After the first file has finished, but before the second file is started, n is set to two, so that the second field is printed in lines from BBS-list:

$ awk '{ print $n }' n=4 inventory-shipped n=2 BBS-list
-| 15
-| 24
...
-| 555-5553
-| 555-3412
...

Command-line arguments are made available for explicit examination by the awk program in the ARGV array (see Using ARGC and ARGV). awk processes the values of command-line assignments for escape sequences (see Escape Sequences). (d.c.)

Node:Conversion, Next:Arithmetic Ops, Previous:Variables, Up:Expressions

Conversion of Strings and Numbers

Strings are converted to numbers and numbers are converted to strings, if the context of the awk program demands it. For example, if the value of either foo or bar in the expression foo + bar happens to be a string, it is converted to a number before the addition is performed. If numeric values appear in string concatenation, they are converted to strings. Consider the following:

two = 2; three = 3
print (two three) + 4

This prints the (numeric) value 27. The numeric values of the variables two and three are converted to strings and concatenated together. The resulting string is converted back to the number 23, to which 4 is then added.

If, for some reason, you need to force a number to be converted to a string, concatenate the empty string, "", with that number. To force a string to be converted to a number, add zero to that string. A string is converted to a number by interpreting any numeric prefix of the string as numerals: "2.5" converts to 2.5, "1e3" converts to 1000, and "25fix" has a numeric value of 25. Strings that can't be interpreted as valid numbers convert to zero.

The exact manner in which numbers are converted into strings is controlled by the awk built-in variable CONVFMT (see Built-in Variables). Numbers are converted using the sprintf function with CONVFMT as the format specifier (see String Manipulation Functions).

CONVFMT's default value is "%.6g", which prints a value with at least six significant digits. For some applications, you might want to change it to specify more precision. On most modern machines, 17 digits is enough to capture a floating-point number's value exactly, most of the time.21

Strange results can occur if you set CONVFMT to a string that doesn't tell sprintf how to format floating-point numbers in a useful way. For example, if you forget the % in the format, awk converts all numbers to the same constant string. As a special case, if a number is an integer, then the result of converting it to a string is always an integer, no matter what the value of CONVFMT may be. Given the following code fragment:

CONVFMT = "%2.2f"
a = 12
b = a ""

b has the value "12", not "12.00". (d.c.)

Prior to the POSIX standard, awk used the value of OFMT for converting numbers to strings. OFMT specifies the output format to use when printing numbers with print. CONVFMT was introduced in order to separate the semantics of conversion from the semantics of printing. Both CONVFMT and OFMT have the same default value: "%.6g". In the vast majority of cases, old awk programs do not change their behavior. However, these semantics for OFMT are something to keep in mind if you must port your new style program to older implementations of awk. We recommend that instead of changing your programs, just port gawk itself. See The print Statement, for more information on the print statement.

Node:Arithmetic Ops, Next:Concatenation, Previous:Conversion, Up:Expressions

Arithmetic Operators

The awk language uses the common arithmetic operators when evaluating expressions. All of these arithmetic operators follow normal precedence rules and work as you would expect them to.

The following example uses a file named grades, which contains a list of student names as well as three test scores per student (it's a small class):

Pat   100 97 58
Sandy  84 72 93
Chris  72 92 89

This programs takes the file grades and prints the average of the scores:

$ awk '{ sum = $2 + $3 + $4 ; avg = sum / 3
>        print $1, avg }' grades
-| Pat 85
-| Sandy 83
-| Chris 84.3333

The following list provides the arithmetic operators in awk, in order from the highest precedence to the lowest:

- x
Negation.
+ x
Unary plus; the expression is converted to a number.
x ^ y
x ** y
Exponentiation; x raised to the y power. 2 ^ 3 has the value eight; the character sequence ** is equivalent to ^.
x * y
Multiplication.
x / y
Division; because all numbers in awk are floating-point numbers, the result is not rounded to an integer--3 / 4 has the value 0.75. (It is a common mistake, especially for C programmers, to forget that all numbers in awk are floating-point, and that division of integer-looking constants produces a real number, not an integer.)
x % y
Remainder; further discussion is provided in the text, just after this list.
x + y
Addition.
x - y
Subtraction.

Unary plus and minus have the same precedence, the multiplication operators all have the same precedence, and addition and subtraction have the same precedence.

When computing the remainder of x % y, the quotient is rounded toward zero to an integer and multiplied by y. This result is subtracted from x; this operation is sometimes known as "trunc-mod." The following relation always holds:

b * int(a / b) + (a % b) == a

One possibly undesirable effect of this definition of remainder is that x % y is negative if x is negative. Thus:

-17 % 8 = -1

In other awk implementations, the signedness of the remainder may be machine-dependent.

Note: The POSIX standard only specifies the use of ^ for exponentiation. For maximum portability, do not use the ** operator.

Node:Concatenation, Next:Assignment Ops, Previous:Arithmetic Ops, Up:Expressions

String Concatenation

It seemed like a good idea at the time.
Brian Kernighan

There is only one string operation: concatenation. It does not have a specific operator to represent it. Instead, concatenation is performed by writing expressions next to one another, with no operator. For example:

$ awk '{ print "Field number one: " $1 }' BBS-list
-| Field number one: aardvark
-| Field number one: alpo-net
...

Without the space in the string constant after the :, the line runs together. For example:

$ awk '{ print "Field number one:" $1 }' BBS-list
-| Field number one:aardvark
-| Field number one:alpo-net
...

Because string concatenation does not have an explicit operator, it is often necessary to insure that it happens at the right time by using parentheses to enclose the items to concatenate. For example, the following code fragment does not concatenate file and name as you might expect:

file = "file"
name = "name"
print "something meaningful" > file name

It is necessary to use the following:

print "something meaningful" > (file name)

Parentheses should be used around concatenation in all but the most common contexts, such as on the righthand side of =. Be careful about the kinds of expressions used in string concatenation. In particular, the order of evaluation of expressions used for concatenation is undefined in the awk language. Consider this example:

BEGIN {
    a = "don't"
    print (a " " (a = "panic"))
}

It is not defined whether the assignment to a happens before or after the value of a is retrieved for producing the concatenated value. The result could be either don't panic, or panic panic. The precedence of concatenation, when mixed with other operators, is often counter-intuitive. Consider this example:

$ awk 'BEGIN { print -12 " " -24 }'
-| -12-24

This "obviously" is concatenating -12, a space, and -24. But where did the space disappear to? The answer lies in the combination of operator precedences and awk's automatic conversion rules. To get the desired result, write the program in the following manner:

$ awk 'BEGIN { print -12 " " (-24) }'
-| -12 -24

This forces awk to treat the - on the -24 as unary. Otherwise, it's parsed as follows:

    -12 (" " - 24)
=> -12 (0 - 24)
=> -12 (-24)
=> -12-24

As mentioned earlier, when doing concatenation, parenthesize. Otherwise, you're never quite sure what you'll get.

Node:Assignment Ops, Next:Increment Ops, Previous:Concatenation, Up:Expressions

Assignment Expressions

An assignment is an expression that stores a (usually different) value into a variable. For example, let's assign the value one to the variable z:

z = 1

After this expression is executed, the variable z has the value one. Whatever old value z had before the assignment is forgotten.

Assignments can also store string values. For example, the following stores the value "this food is good" in the variable message:

thing = "food"
predicate = "good"
message = "this " thing " is " predicate

This also illustrates string concatenation. The = sign is called an assignment operator. It is the simplest assignment operator because the value of the righthand operand is stored unchanged. Most operators (addition, concatenation, and so on) have no effect except to compute a value. If the value isn't used, there's no reason to use the operator. An assignment operator is different; it does produce a value, but even if you ignore it, the assignment still makes itself felt through the alteration of the variable. We call this a side effect.

The lefthand operand of an assignment need not be a variable (see Variables); it can also be a field (see Changing the Contents of a Field) or an array element (see Arrays in awk). These are all called lvalues, which means they can appear on the lefthand side of an assignment operator. The righthand operand may be any expression; it produces the new value that the assignment stores in the specified variable, field, or array element. (Such values are called rvalues.)

It is important to note that variables do not have permanent types. A variable's type is simply the type of whatever value it happens to hold at the moment. In the following program fragment, the variable foo has a numeric value at first, and a string value later on:

foo = 1
print foo
foo = "bar"
print foo

When the second assignment gives foo a string value, the fact that it previously had a numeric value is forgotten.

String values that do not begin with a digit have a numeric value of zero. After executing the following code, the value of foo is five:

foo = "a string"
foo = foo + 5

Note: Using a variable as a number and then later as a string can be confusing and is poor programming style. The previous two examples illustrate how awk works, not how you should write your programs!

An assignment is an expression, so it has a value--the same value that is assigned. Thus, z = 1 is an expression with the value one. One consequence of this is that you can write multiple assignments together, such as:

x = y = z = 5

This example stores the value five in all three variables (x, y, and z). It does so because the value of z = 5, which is five, is stored into y and then the value of y = z = 5, which is five, is stored into x.

Assignments may be used anywhere an expression is called for. For example, it is valid to write x != (y = 1) to set y to one, and then test whether x equals one. But this style tends to make programs hard to read; such nesting of assignments should be avoided, except perhaps in a one-shot program.

Aside from =, there are several other assignment operators that do arithmetic with the old value of the variable. For example, the operator += computes a new value by adding the righthand value to the old value of the variable. Thus, the following assignment adds five to the value of foo:

foo += 5

This is equivalent to the following:

foo = foo + 5

Use whichever makes the meaning of your program clearer.

There are situations where using += (or any assignment operator) is not the same as simply repeating the lefthand operand in the righthand expression. For example:

# Thanks to Pat Rankin for this example
BEGIN  {
    foo[rand()] += 5
    for (x in foo)
       print x, foo[x]

    bar[rand()] = bar[rand()] + 5
    for (x in bar)
       print x, bar[x]
}

The indices of bar are practically guaranteed to be different, because rand returns different values each time it is called. (Arrays and the rand function haven't been covered yet. See Arrays in awk, and see Numeric Functions, for more information). This example illustrates an important fact about assignment operators: the lefthand expression is only evaluated once. It is up to the implementation as to which expression is evaluated first, the lefthand or the righthand. Consider this example:

i = 1
a[i += 2] = i + 1

The value of a[3] could be either two or four.

Here is a table of the arithmetic assignment operators. In each case, the righthand operand is an expression whose value is converted to a number.

lvalue += increment | Adds increment to the value of lvalue.
lvalue -= decrement | Subtracts decrement from the value of lvalue.
lvalue *= coefficient | Multiplies the value of lvalue by coefficient.
lvalue /= divisor | Divides the value of lvalue by divisor.
lvalue %= modulus | Sets lvalue to its remainder by modulus.
lvalue ^= power |
lvalue **= power | Raises lvalue to the power power.

Note: Only the ^= operator is specified by POSIX. For maximum portability, do not use the **= operator.

Advanced Notes: Syntactic Ambiguities Between /= and Regular Expressions

There is a syntactic ambiguity between the /= assignment operator and regexp constants whose first character is an =. (d.c.) This is most notable in commercial awk versions. For example:

$ awk /==/ /dev/null
error--> awk: syntax error at source line 1
error-->  context is
error-->         >>> /= <<<
error--> awk: bailing out at source line 1

A workaround is:

awk '/[=]=/' /dev/null

gawk does not have this problem, nor do the other freely available versions described in Other Freely Available awk Implementations.

Node:Increment Ops, Next:Truth Values, Previous:Assignment Ops, Up:Expressions

Increment and Decrement Operators

Increment and decrement operators increase or decrease the value of a variable by one. An assignment operator can do the same thing, so the increment operators add no power to the awk language; however, they are convenient abbreviations for very common operations.

The operator used for adding one is written ++. It can be used to increment a variable either before or after taking its value. To pre-increment a variable v, write ++v. This adds one to the value of v--that new value is also the value of the expression. (The assignment expression v += 1 is completely equivalent.) Writing the ++ after the variable specifies post-increment. This increments the variable value just the same; the difference is that the value of the increment expression itself is the variable's old value. Thus, if foo has the value four, then the expression foo++ has the value four, but it changes the value of foo to five. In other words, the operator returns the old value of the variable, but with the side effect of incrementing it.

The post-increment foo++ is nearly the same as writing (foo += 1) - 1. It is not perfectly equivalent because all numbers in awk are floating-point--in floating-point, foo + 1 - 1 does not necessarily equal foo. But the difference is minute as long as you stick to numbers that are fairly small (less than 10e12).

Fields and array elements are incremented just like variables. (Use $(i++) when you want to do a field reference and a variable increment at the same time. The parentheses are necessary because of the precedence of the field reference operator $.)

The decrement operator -- works just like ++, except that it subtracts one instead of adding it. As with ++, it can be used before the lvalue to pre-decrement or after it to post-decrement. Following is a summary of increment and decrement expressions:

++lvalue
This expression increments lvalue, and the new value becomes the value of the expression.
lvalue++
This expression increments lvalue, but the value of the expression is the old value of lvalue.
--lvalue
This expression is like ++lvalue, but instead of adding, it subtracts. It decrements lvalue and delivers the value that is the result.
lvalue--
This expression is like lvalue++, but instead of adding, it subtracts. It decrements lvalue. The value of the expression is the old value of lvalue.

Advanced Notes: Operator Evaluation Order

Doctor, doctor! It hurts when I do this!
So don't do that!
Groucho Marx

What happens for something like the following?

b = 6
print b += b++

Or something even stranger?

b = 6
b += ++b + b++
print b

In other words, when do the various side effects prescribed by the postfix operators (b++) take effect? When side effects happen is implementation defined. In other words, it is up to the particular version of awk. The result for the first example may be 12 or 13, and for the second, it may be 22 or 23.

In short, doing things like this is not recommended and definitely not anything that you can rely upon for portability. You should avoid such things in your own programs.

Node:Truth Values, Next:Typing and Comparison, Previous:Increment Ops, Up:Expressions

True and False in awk

Many programming languages have a special representation for the concepts of "true" and "false." Such languages usually use the special constants true and false, or perhaps their uppercase equivalents. However, awk is different. It borrows a very simple concept of true and false from C. In awk, any nonzero numeric value or any nonempty string value is true. Any other value (zero or the null string "") is false. The following program prints A strange truth value three times:

BEGIN {
   if (3.1415927)
       print "A strange truth value"
   if ("Four Score And Seven Years Ago")
       print "A strange truth value"
   if (j = 57)
       print "A strange truth value"
}

There is a surprising consequence of the "nonzero or non-null" rule: the string constant "0" is actually true, because it is non-null. (d.c.)

Node:Typing and Comparison, Next:Boolean Ops, Previous:Truth Values, Up:Expressions

Variable Typing and Comparison Expressions

The Guide is definitive. Reality is frequently inaccurate.
The Hitchhiker's Guide to the Galaxy

Unlike other programming languages, awk variables do not have a fixed type. Instead, they can be either a number or a string, depending upon the value that is assigned to them.

The 1992 POSIX standard introduced the concept of a numeric string, which is simply a string that looks like a number--for example, " +2". This concept is used for determining the type of a variable. The type of the variable is important because the types of two variables determine how they are compared. In gawk, variable typing follows these rules:

  • A numeric constant or the result of a numeric operation has the numeric attribute.
  • A string constant or the result of a string operation has the string attribute.
  • Fields, getline input, FILENAME, ARGV elements, ENVIRON elements, and the elements of an array created by split that are numeric strings have the strnum attribute. Otherwise, they have the string attribute. Uninitialized variables also have the strnum attribute.
  • Attributes propagate across assignments but are not changed by any use.

The last rule is particularly important. In the following program, a has numeric type, even though it is later used in a string operation:

BEGIN {
         a = 12.345
         b = a " is a cute number"
         print b
}

When two operands are compared, either string comparison or numeric comparison may be used. This depends upon the attributes of the operands, according to the following symmetric matrix:

        +----------------------------------------------
        |       STRING          NUMERIC         STRNUM
--------+----------------------------------------------
        |
STRING  |       string          string          string
        |
NUMERIC |       string          numeric         numeric
        |
STRNUM  |       string          numeric         numeric
--------+----------------------------------------------

The basic idea is that user input that looks numeric--and only user input--should be treated as numeric, even though it is actually made of characters and is therefore also a string. Thus, for example, the string constant " +3.14" is a string, even though it looks numeric, and is never treated as number for comparison purposes.

In short, when one operand is a "pure" string, such as a string constant, then a string comparison is performed. Otherwise, a numeric comparison is performed.22

Comparison expressions compare strings or numbers for relationships such as equality. They are written using relational operators, which are a superset of those in C. Here is a table of them:

x < y
True if x is less than y.
x <= y
True if x is less than or equal to y.
x > y
True if x is greater than y.
x >= y
True if x is greater than or equal to y.
x == y
True if x is equal to y.
x != y
True if x is not equal to y.
x ~ y
True if the string x matches the regexp denoted by y.
x !~ y
True if the string x does not match the regexp denoted by y.
subscript in array
True if the array array has an element with the subscript subscript.

Comparison expressions have the value one if true and zero if false. When comparing operands of mixed types, numeric operands are converted to strings using the value of CONVFMT (see Conversion of Strings and Numbers).

Strings are compared by comparing the first character of each, then the second character of each, and so on. Thus, "10" is less than "9". If there are two strings where one is a prefix of the other, the shorter string is less than the longer one. Thus, "abc" is less than "abcd".

It is very easy to accidentally mistype the == operator and leave off one of the = characters. The result is still valid awk code, but the program does not do what is intended:

if (a = b)   # oops! should be a == b
   ...
else
   ...

Unless b happens to be zero or the null string, the if part of the test always succeeds. Because the operators are so similar, this kind of error is very difficult to spot when scanning the source code.

The following table of expressions illustrates the kind of comparison gawk performs, as well as what the result of the comparison is:

1.5 <= 2.0
numeric comparison (true)
"abc" >= "xyz"
string comparison (false)
1.5 != " +2"
string comparison (true)
"1e2" < "3"
string comparison (true)
a = 2; b = "2"
a == b
string comparison (true)
a = 2; b = " +2"
a == b
string comparison (false)

In the next example:

$ echo 1e2 3 | awk '{ print ($1 < $2) ? "true" : "false" }'
-| false

the result is false because both $1 and $2 are user input. They are numeric strings--therefore both have the strnum attribute, dictating a numeric comparison. The purpose of the comparison rules and the use of numeric strings is to attempt to produce the behavior that is "least surprising," while still "doing the right thing." String comparisons and regular expression comparisons are very different. For example:

x == "foo"

has the value one, or is true if the variable x is precisely foo. By contrast:

x ~ /foo/

has the value one if x contains foo, such as "Oh, what a fool am I!".

The righthand operand of the ~ and !~ operators may be either a regexp constant (/.../) or an ordinary expression. In the latter case, the value of the expression as a string is used as a dynamic regexp (see How to Use Regular Expressions; also see Using Dynamic Regexps).

In modern implementations of awk, a constant regular expression in slashes by itself is also an expression. The regexp /regexp/ is an abbreviation for the following comparison expression:

$0 ~ /regexp/

One special place where /foo/ is not an abbreviation for $0 ~ /foo/ is when it is the righthand operand of ~ or !~. See Using Regular Expression Constants, where this is discussed in more detail.

Node:Boolean Ops, Next:Conditional Exp, Previous:Typing and Comparison, Up:Expressions

Boolean Expressions

A Boolean expression is a combination of comparison expressions or matching expressions, using the Boolean operators "or" (||), "and" (&&), and "not" (!), along with parentheses to control nesting. The truth value of the Boolean expression is computed by combining the truth values of the component expressions. Boolean expressions are also referred to as logical expressions. The terms are equivalent.

Boolean expressions can be used wherever comparison and matching expressions can be used. They can be used in if, while, do, and for statements (see Control Statements in Actions). They have numeric values (one if true, zero if false) that come into play if the result of the Boolean expression is stored in a variable or used in arithmetic.

In addition, every Boolean expression is also a valid pattern, so you can use one as a pattern to control the execution of rules. The Boolean operators are:

boolean1 && boolean2
True if both boolean1 and boolean2 are true. For example, the following statement prints the current input record if it contains both 2400 and foo:
if ($0 ~ /2400/ && $0 ~ /foo/) print

The subexpression boolean2 is evaluated only if boolean1 is true. This can make a difference when boolean2 contains expressions that have side effects. In the case of $0 ~ /foo/ && ($2 == bar++), the variable bar is not incremented if there is no substring foo in the record.

boolean1 || boolean2
True if at least one of boolean1 or boolean2 is true. For example, the following statement prints all records in the input that contain either 2400 or foo or both:
if ($0 ~ /2400/ || $0 ~ /foo/) print

The subexpression boolean2 is evaluated only if boolean1 is false. This can make a difference when boolean2 contains expressions that have side effects.

! boolean
True if boolean is false. For example, the following program prints no home! in the unusual event that the HOME environment variable is not defined:
BEGIN { if (! ("HOME" in ENVIRON))
               print "no home!" }

(The in operator is described in Referring to an Array Element.)

The && and || operators are called short-circuit operators because of the way they work. Evaluation of the full expression is "short-circuited" if the result can be determined part way through its evaluation.

Statements that use && or || can be continued simply by putting a newline after them. But you cannot put a newline in front of either of these operators without using backslash continuation (see awk Statements Versus Lines).

The actual value of an expression using the ! operator is either one or zero, depending upon the truth value of the expression it is applied to. The ! operator is often useful for changing the sense of a flag variable from false to true and back again. For example, the following program is one way to print lines in between special bracketing lines:

$1 == "START"   { interested = ! interested; next }
interested == 1 { print }
$1 == "END"     { interested = ! interested; next }

The variable interested, as with all awk variables, starts out initialized to zero, which is also false. When a line is seen whose first field is START, the value of interested is toggled to true, using !. The next rule prints lines as long as interested is true. When a line is seen whose first field is END, interested is toggled back to false.

Note: The next statement is discussed in The next Statement. next tells awk to skip the rest of the rules, get the next record, and start processing the rules over again at the top. The reason it's there is to avoid printing the bracketing START and END lines.

Node:Conditional Exp, Next:Function Calls, Previous:Boolean Ops, Up:Expressions

Conditional Expressions

A conditional expression is a special kind of expression that has three operands. It allows you to use one expression's value to select one of two other expressions. The conditional expression is the same as in the C language, as shown here:

selector ? if-true-exp : if-false-exp

There are three subexpressions. The first, selector, is always computed first. If it is "true" (not zero or not null), then if-true-exp is computed next and its value becomes the value of the whole expression. Otherwise, if-false-exp is computed next and its value becomes the value of the whole expression. For example, the following expression produces the absolute value of x:

x >= 0 ? x : -x

Each time the conditional expression is computed, only one of if-true-exp and if-false-exp is used; the other is ignored. This is important when the expressions have side effects. For example, this conditional expression examines element i of either array a or array b, and increments i:

x == y ? a[i++] : b[i++]

This is guaranteed to increment i exactly once, because each time only one of the two increment expressions is executed and the other is not. See Arrays in awk, for more information about arrays.

As a minor gawk extension, a statement that uses ?: can be continued simply by putting a newline after either character. However, putting a newline in front of either character does not work without using backslash continuation (see awk Statements Versus Lines). If --posix is specified (see Command-Line Options), then this extension is disabled.

Node:Function Calls, Next:Precedence, Previous:Conditional Exp, Up:Expressions

Function Calls

A function is a name for a particular calculation. This enables you to ask for it by name at any point in the program. For example, the function sqrt computes the square root of a number.

A fixed set of functions are built-in, which means they are available in every awk program. The sqrt function is one of these. See Built-in Functions, for a list of built-in functions and their descriptions. In addition, you can define functions for use in your program. See User-Defined Functions, for instructions on how to do this.

The way to use a function is with a function call expression, which consists of the function name followed immediately by a list of arguments in parentheses. The arguments are expressions that provide the raw materials for the function's calculations. When there is more than one argument, they are separated by commas. If there are no arguments, just write () after the function name. The following examples show function calls with and without arguments:

sqrt(x^2 + y^2)        one argument
atan2(y, x)            two arguments
rand()                 no arguments

Caution: Do not put any space between the function name and the open-parenthesis! A user-defined function name looks just like the name of a variable--a space would make the expression look like concatenation of a variable with an expression inside parentheses.

With built-in functions, space before the parenthesis is harmless, but it is best not to get into the habit of using space to avoid mistakes with user-defined functions. Each function expects a particular number of arguments. For example, the sqrt function must be called with a single argument, the number of which to take the square root:

sqrt(argument)

Some of the built-in functions have one or more optional arguments. If those arguments are not supplied, the functions use a reasonable default value. See Built-in Functions, for full details. If arguments are omitted in calls to user-defined functions, then those arguments are treated as local variables and initialized to the empty string (see User-Defined Functions).

Like every other expression, the function call has a value, which is computed by the function based on the arguments you give it. In this example, the value of sqrt(argument) is the square root of argument. A function can also have side effects, such as assigning values to certain variables or doing I/O. The following program reads numbers, one number per line, and prints the square root of each one:

$ awk '{ print "The square root of", $1, "is", sqrt($1) }'
1
-| The square root of 1 is 1
3
-| The square root of 3 is 1.73205
5
-| The square root of 5 is 2.23607
Ctrl-d

Node:Precedence, Previous:Function Calls, Up:Expressions

Operator Precedence (How Operators Nest)

Operator precedence determines how operators are grouped when different operators appear close by in one expression. For example, * has higher precedence than +; thus, a + b * c means to multiply b and c, and then add a to the product (i.e., a + (b * c)).

The normal precedence of the operators can be overruled by using parentheses. Think of the precedence rules as saying where the parentheses are assumed to be. In fact, it is wise to always use parentheses whenever there is an unusual combination of operators, because other people who read the program may not remember what the precedence is in this case. Even experienced programmers occasionally forget the exact rules, which leads to mistakes. Explicit parentheses help prevent any such mistakes.

When operators of equal precedence are used together, the leftmost operator groups first, except for the assignment, conditional, and exponentiation operators, which group in the opposite order. Thus, a - b + c groups as (a - b) + c and a = b = c groups as a = (b = c).

The precedence of prefix unary operators does not matter as long as only unary operators are involved, because there is only one way to interpret them: innermost first. Thus, $++i means $(++i) and ++$x means ++($x). However, when another operator follows the operand, then the precedence of the unary operators can matter. $x^2 means ($x)^2, but -x^2 means -(x^2), because - has lower precedence than ^, whereas $ has higher precedence. This table presents awk's operators, in order of highest to lowest precedence:

(...)
Grouping.
$
Field.
++ --
Increment, decrement.
^ **
Exponentiation. These operators group right-to-left.
+ - !
Unary plus, minus, logical "not."
* / %
Multiplication, division, modulus.
+ -
Addition, subtraction.
String Concatenation
No special symbol is used to indicate concatenation. The operands are simply written side by side (see String Concatenation).
< <= == !=
> >= >> | |&
Relational and redirection. The relational operators and the redirections have the same precedence level. Characters such as > serve both as relationals and as redirections; the context distinguishes between the two meanings.

Note that the I/O redirection operators in print and printf statements belong to the statement level, not to expressions. The redirection does not produce an expression that could be the operand of another operator. As a result, it does not make sense to use a redirection operator near another operator of lower precedence without parentheses. Such combinations (for example, print foo > a ? b : c), result in syntax errors. The correct way to write this statement is print foo > (a ? b : c).

~ !~
Matching, nonmatching.
in
Array membership.
&&
Logical "and".
||
Logical "or".
?:
Conditional. This operator groups right-to-left.
= += -= *=
/= %= ^= **=
Assignment. These operators group right to left.

Note: The |&, **, and **= operators are not specified by POSIX. For maximum portability, do not use them.

Node:Patterns and Actions, Next:Arrays, Previous:Expressions, Up:Top

Patterns, Actions, and Variables

As you have already seen, each awk statement consists of a pattern with an associated action. This chapter describes how you build patterns and actions, what kinds of things you can do within actions, and awk's built-in variables.

The pattern-action rules and the statements available for use within actions form the core of awk programming. In a sense, everything covered up to here has been the foundation that programs are built on top of. Now it's time to start building something useful.

  • Pattern Overview: What goes into a pattern.
  • Using Shell Variables: How to use shell variables with awk.
  • Action Overview: What goes into an action.
  • Statements: Describes the various control statements in detail.
  • Built-in Variables: Summarizes the built-in variables.

Node:Pattern Overview, Next:Using Shell Variables, Previous:Patterns and Actions, Up:Patterns and Actions

Pattern Elements

  • Regexp Patterns: Using regexps as patterns.
  • Expression Patterns: Any expression can be used as a pattern.
  • Ranges: Pairs of patterns specify record ranges.
  • BEGIN/END: Specifying initialization and cleanup rules.
  • Empty: The empty pattern, which matches every record.

Patterns in awk control the execution of rules--a rule is executed when its pattern matches the current input record. The following is a summary of the types of awk patterns:

/regular expression/
A regular expression. It matches when the text of the input record fits the regular expression. (See Regular Expressions.)
expression
A single expression. It matches when its value is nonzero (if a number) or non-null (if a string). (See Expressions as Patterns.)
pat1, pat2
A pair of patterns separated by a comma, specifying a range of records. The range includes both the initial record that matches pat1 and the final record that matches pat2. (See Specifying Record Ranges with Patterns.)
BEGIN
END
Special patterns for you to supply startup or cleanup actions for your awk program. (See The BEGIN and END Special Patterns.)
empty
The empty pattern matches every input record. (See The Empty Pattern.)

Node:Regexp Patterns, Next:Expression Patterns, Previous:Pattern Overview, Up:Pattern Overview

Regular Expressions as Patterns

Regular expressions are one of the first kinds of patterns presented in this book. This kind of pattern is simply a regexp constant in the pattern part of a rule. Its meaning is $0 ~ /pattern/. The pattern matches when the input record matches the regexp. For example:

/foo|bar|baz/  { buzzwords++ }
END            { print buzzwords, "buzzwords seen" }

Node:Expression Patterns, Next:Ranges, Previous:Regexp Patterns, Up:Pattern Overview

Expressions as Patterns

Any awk expression is valid as an awk pattern. The pattern matches if the expression's value is nonzero (if a number) or non-null (if a string). The expression is reevaluated each time the rule is tested against a new input record. If the expression uses fields such as $1, the value depends directly on the new input record's text; otherwise, it depends on only what has happened so far in the execution of the awk program.

Comparison expressions, using the comparison operators described in Variable Typing and Comparison Expressions, are a very common kind of pattern. Regexp matching and nonmatching are also very common expressions. The left operand of the ~ and !~ operators is a string. The right operand is either a constant regular expression enclosed in slashes (/regexp/), or any expression whose string value is used as a dynamic regular expression (see Using Dynamic Regexps). The following example prints the second field of each input record whose first field is precisely foo:

$ awk '$1 == "foo" { print $2 }' BBS-list

(There is no output, because there is no BBS site with the exact name foo.) Contrast this with the following regular expression match, which accepts any record with a first field that contains foo:

$ awk '$1 ~ /foo/ { print $2 }' BBS-list
-| 555-1234
-| 555-6699
-| 555-6480
-| 555-2127

A regexp constant as a pattern is also a special case of an expression pattern. The expression /foo/ has the value one if foo appears in the current input record. Thus, as a pattern, /foo/ matches any record containing foo.

Boolean expressions are also commonly used as patterns. Whether the pattern matches an input record depends on whether its subexpressions match. For example, the following command prints all the records in BBS-list that contain both 2400 and foo:

$ awk '/2400/ && /foo/' BBS-list
-| fooey        555-1234     2400/1200/300     B

The following command prints all records in BBS-list that contain either 2400 or foo (or both, of course):

$ awk '/2400/ || /foo/' BBS-list
-| alpo-net     555-3412     2400/1200/300     A
-| bites        555-1675     2400/1200/300     A
-| fooey        555-1234     2400/1200/300     B
-| foot         555-6699     1200/300          B
-| macfoo       555-6480     1200/300          A
-| sdace        555-3430     2400/1200/300     A
-| sabafoo      555-2127     1200/300          C

The following command prints all records in BBS-list that do not contain the string foo:

$ awk '! /foo/' BBS-list
-| aardvark     555-5553     1200/300          B
-| alpo-net     555-3412     2400/1200/300     A
-| barfly       555-7685     1200/300          A
-| bites        555-1675     2400/1200/300     A
-| camelot      555-0542     300               C
-| core         555-2912     1200/300          C
-| sdace        555-3430     2400/1200/300     A

The subexpressions of a Boolean operator in a pattern can be constant regular expressions, comparisons, or any other awk expressions. Range patterns are not expressions, so they cannot appear inside Boolean patterns. Likewise, the special patterns BEGIN and END, which never match any input record, are not expressions and cannot appear inside Boolean patterns.

Node:Ranges, Next:BEGIN/END, Previous:Expression Patterns, Up:Pattern Overview

Specifying Record Ranges with Patterns

A range pattern is made of two patterns separated by a comma, in the form begpat, endpat. It is used to match ranges of consecutive input records. The first pattern, begpat, controls where the range begins, while endpat controls where the pattern ends. For example, the following:

awk '$1 == "on", $1 == "off"' myfile

prints every record in myfile between on/off pairs, inclusive.

A range pattern starts out by matching begpat against every input record. When a record matches begpat, the range pattern is turned on and the range pattern matches this record as well. As long as the range pattern stays turned on, it automatically matches every input record read. The range pattern also matches endpat against every input record; when this succeeds, the range pattern is turned off again for the following record. Then the range pattern goes back to checking begpat against each record.

The record that turns on the range pattern and the one that turns it off both match the range pattern. If you don't want to operate on these records, you can write if statements in the rule's action to distinguish them from the records you are interested in.

It is possible for a pattern to be turned on and off by the same record. If the record satisfies both conditions, then the action is executed for just that record. For example, suppose there is text between two identical markers (e.g., the % symbol), each on its own line, that should be ignored. A first attempt would be to combine a range pattern that describes the delimited text with the next statement (not discussed yet, see The next Statement). This causes awk to skip any further processing of the current record and start over again with the next input record. Such a program looks like this:

/^%$/,/^%$/    { next }
               { print }

This program fails because the range pattern is both turned on and turned off by the first line, which just has a % on it. To accomplish this task, write the program in the following manner, using a flag:

/^%$/     { skip = ! skip; next }
skip == 1 { next } # skip lines with `skip' set

In a range pattern, the comma (,) has the lowest precedence of all the operators (i.e., it is evaluated last). Thus, the following program attempts to combine a range pattern with another, simpler test:

echo Yes | awk '/1/,/2/ || /Yes/'

The intent of this program is (/1/,/2/) || /Yes/. However, awk interprets this as /1/, (/2/ || /Yes/). This cannot be changed or worked around; range patterns do not combine with other patterns:

$ echo yes | gawk '(/1/,/2/) || /Yes/'
error--> gawk: cmd. line:1: (/1/,/2/) || /Yes/
error--> gawk: cmd. line:1:           ^ parse error
error--> gawk: cmd. line:2: (/1/,/2/) || /Yes/
error--> gawk: cmd. line:2:                   ^ unexpected newline

Node:BEGIN/END, Next:Empty, Previous:Ranges, Up:Pattern Overview

The BEGIN and END Special Patterns

All the patterns described so far are for matching input records. The BEGIN and END special patterns are different. They supply startup and cleanup actions for awk programs. BEGIN and END rules must have actions; there is no default action for these rules because there is no current record when they run. BEGIN and END rules are often referred to as "BEGIN and END blocks" by long-time awk programmers.

  • Using BEGIN/END: How and why to use BEGIN/END rules.
  • I/O And BEGIN/END: I/O issues in BEGIN/END rules.

Node:Using BEGIN/END, Next:I/O And BEGIN/END, Previous:BEGIN/END, Up:BEGIN/END
Startup and Cleanup Actions

A BEGIN rule is executed once only, before the first input record is read. Likewise, an END rule is executed once only, after all the input is read. For example:

$ awk '
> BEGIN { print "Analysis of \"foo\"" }
> /foo/ { ++n }
> END   { print "\"foo\" appears", n, "times." }' BBS-list
-| Analysis of "foo"
-| "foo" appears 4 times.

This program finds the number of records in the input file BBS-list that contain the string foo. The BEGIN rule prints a title for the report. There is no need to use the BEGIN rule to initialize the counter n to zero, since awk does this automatically (see Variables). The second rule increments the variable n every time a record containing the pattern foo is read. The END rule prints the value of n at the end of the run.

The special patterns BEGIN and END cannot be used in ranges or with Boolean operators (indeed, they cannot be used with any operators). An awk program may have multiple BEGIN and/or END rules. They are executed in the order in which they appear: all the BEGIN rules at startup and all the END rules at termination. BEGIN and END rules may be intermixed with other rules. This feature was added in the 1987 version of awk and is included in the POSIX standard. The original (1978) version of awk required the BEGIN rule to be placed at the beginning of the program, the END rule to be placed at the end, and only allowed one of each. This is no longer required, but it is a good idea to follow this template in terms of program organization and readability.

Multiple BEGIN and END rules are useful for writing library functions, because each library file can have its own BEGIN and/or END rule to do its own initialization and/or cleanup. The order in which library functions are named on the command line controls the order in which their BEGIN and END rules are executed. Therefore, you have to be careful when writing such rules in library files so that the order in which they are executed doesn't matter. See Command-Line Options, for more information on using library functions. See A Library of awk Functions, for a number of useful library functions.

If an awk program has only a BEGIN rule and no other rules, then the program exits after the BEGIN rule is run.23 However, if an END rule exists, then the input is read, even if there are no other rules in the program. This is necessary in case the END rule checks the FNR and NR variables.

Node:I/O And BEGIN/END, Previous:Using BEGIN/END, Up:BEGIN/END
Input/Output from BEGIN and END Rules

There are several (sometimes subtle) points to remember when doing I/O from a BEGIN or END rule. The first has to do with the value of $0 in a BEGIN rule. Because BEGIN rules are executed before any input is read, there simply is no input record, and therefore no fields, when executing BEGIN rules. References to $0 and the fields yield a null string or zero, depending upon the context. One way to give $0 a real value is to execute a getline command without a variable (see Explicit Input with getline). Another way is simply to assign a value to $0.

The second point is similar to the first but from the other direction. Traditionally, due largely to implementation issues, $0 and NF were undefined inside an END rule. The POSIX standard specifies that NF is available in an END rule. It contains the number of fields from the last input record. Most probably due to an oversight, the standard does not say that $0 is also preserved, although logically one would think that it should be. In fact, gawk does preserve the value of $0 for use in END rules. Be aware, however, that Unix awk, and possibly other implementations, do not.

The third point follows from the first two. The meaning of print inside a BEGIN or END rule is the same as always: print $0. If $0 is the null string, then this prints an empty line. Many long time awk programmers use an unadorned print in BEGIN and END rules, to mean print "", relying on $0 being null. Although one might generally get away with this in BEGIN rules, it is a very bad idea in END rules, at least in gawk. It is also poor style, since if an empty line is needed in the output, the program should print one explicitly.

Finally, the next and nextfile statements are not allowed in a BEGIN rule, because the implicit read-a-record-and-match-against-the-rules loop has not started yet. Similarly, those statements are not valid in an END rule, since all the input has been read. (See The next Statement, and see Using gawk's nextfile Statement.)

Node:Empty, Previous:BEGIN/END, Up:Pattern Overview

The Empty Pattern

An empty (i.e., nonexistent) pattern is considered to match every input record. For example, the program:

awk '{ print $1 }' BBS-list

prints the first field of every record.

Node:Using Shell Variables, Next:Action Overview, Previous:Pattern Overview, Up:Patterns and Actions

Using Shell Variables in Programs

awk programs are often used as components in larger programs written in shell. For example, it is very common to use a shell variable to hold a pattern that the awk program searches for. There are two ways to get the value of the shell variable into the body of the awk program.

The most common method is to use shell quoting to substitute the variable's value into the program inside the script. For example, in the following program:

echo -n "Enter search pattern: "
read pattern
awk "/$pattern/ "'{ nmatches++ }
     END { print nmatches, "found" }' /path/to/data

the awk program consists of two pieces of quoted text that are concatenated together to form the program. The first part is double-quoted, which allows substitution of the pattern variable inside the quotes. The second part is single-quoted.

Variable substitution via quoting works, but can be potentially messy. It requires a good understanding of the shell's quoting rules (see Shell Quoting Issues), and it's often difficult to correctly match up the quotes when reading the program.

A better method is to use awk's variable assignment feature (see Assigning Variables on the Command Line) to assign the shell variable's value to an awk variable's value. Then use dynamic regexps to match the pattern (see Using Dynamic Regexps). The following shows how to redo the previous example using this technique:

echo -n "Enter search pattern: "
read pattern
awk -v pat="$pattern" '$0 ~ pat { nmatches++ }
       END { print nmatches, "found" }' /path/to/data

Now, the awk program is just one single-quoted string. The assignment -v pat="$pattern" still requires double quotes, in case there is whitespace in the value of $pattern. The awk variable pat could be named pattern too, but that would be more confusing. Using a variable also provides more flexibility, since the variable can be used anywhere inside the program--for printing, as an array subscript, or for any other use--without requiring the quoting tricks at every point in the program.

Node:Action Overview, Next:Statements, Previous:Using Shell Variables, Up:Patterns and Actions

Actions

An awk program or script consists of a series of rules and function definitions interspersed. (Functions are described later. See User-Defined Functions.) A rule contains a pattern and an action, either of which (but not both) may be omitted. The purpose of the action is to tell awk what to do once a match for the pattern is found. Thus, in outline, an awk program generally looks like this:

[pattern] [{ action }]
[pattern] [{ action }]
...
function name(args) { ... }
...

An action consists of one or more awk statements, enclosed in curly braces ({...}). Each statement specifies one thing to do. The statements are separated by newlines or semicolons. The curly braces around an action must be used even if the action contains only one statement, or if it contains no statements at all. However, if you omit the action entirely, omit the curly braces as well. An omitted action is equivalent to { print $0 }:

/foo/  { }     match foo, do nothing --- empty action
/foo/          match foo, print the record --- omitted action

The following types of statements are supported in awk:

Expressions
Call functions or assign values to variables (see Expressions). Executing this kind of statement simply computes the value of the expression. This is useful when the expression has side effects (see Assignment Expressions).
Control statements
Specify the control flow of awk programs. The awk language gives you C-like constructs (if, for, while, and do) as well as a few special ones (see Control Statements in Actions).
Compound statements
Consist of one or more statements enclosed in curly braces. A compound statement is used in order to put several statements together in the body of an if, while, do, or for statement.
Input statements
Use the getline command (see Explicit Input with getline). Also supplied in awk are the next statement (see The next Statement), and the nextfile statement (see Using gawk's nextfile Statement).
Output statements
Such as print and printf. See Printing Output.
Deletion statements
For deleting array elements. See The delete Statement.

Node:Statements, Next:Built-in Variables, Previous:Action Overview, Up:Patterns and Actions

Control Statements in Actions

Control statements, such as if, while, and so on, control the flow of execution in awk programs. Most of the control statements in awk are patterned on similar statements in C.

All the control statements start with special keywords, such as if and while, to distinguish them from simple expressions. Many control statements contain other statements. For example, the if statement contains another statement that may or may not be executed. The contained statement is called the body. To include more than one statement in the body, group them into a single compound statement with curly braces, separating them with newlines or semicolons.

  • If Statement: Conditionally execute some awk statements.
  • While Statement: Loop until some condition is satisfied.
  • Do Statement: Do specified action while looping until some condition is satisfied.
  • For Statement: Another looping statement, that provides initialization and increment clauses.
  • Break Statement: Immediately exit the innermost enclosing loop.
  • Continue Statement: Skip to the end of the innermost enclosing loop.
  • Next Statement: Stop processing the current input record.
  • Nextfile Statement: Stop processing the current file.
  • Exit Statement: Stop execution of awk.

Node:If Statement, Next:While Statement, Previous:Statements, Up:Statements

The if-else Statement

The if-else statement is awk's decision-making statement. It looks like this:

if (condition) then-body [else else-body]

The condition is an expression that controls what the rest of the statement does. If the condition is true, then-body is executed; otherwise, else-body is executed. The else part of the statement is optional. The condition is considered false if its value is zero or the null string; otherwise, the condition is true. Refer to the following:

if (x % 2 == 0)
    print "x is even"
else
    print "x is odd"

In this example, if the expression x % 2 == 0 is true (that is, if the value of x is evenly divisible by two), then the first print statement is executed; otherwise, the second print statement is executed. If the else keyword appears on the same line as then-body and then-body is not a compound statement (i.e., not surrounded by curly braces), then a semicolon must separate then-body from the else. To illustrate this, the previous example can be rewritten as:

if (x % 2 == 0) print "x is even"; else
        print "x is odd"

If the ; is left out, awk can't interpret the statement and it produces a syntax error. Don't actually write programs this way, because a human reader might fail to see the else if it is not the first thing on its line.

Node:While Statement, Next:Do Statement, Previous:If Statement, Up:Statements

The while Statement

In programming, a loop is a part of a program that can be executed two or more times in succession. The while statement is the simplest looping statement in awk. It repeatedly executes a statement as long as a condition is true. For example:

while (condition)
  body

body is a statement called the body of the loop, and condition is an expression that controls how long the loop keeps running. The first thing the while statement does is test the condition. If the condition is true, it executes the statement body. After body has been executed, condition is tested again, and if it is still true, body is executed again. This process repeats until the condition is no longer true. If the condition is initially false, the body of the loop is never executed and awk continues with the statement following the loop. This example prints the first three fields of each record, one per line:

awk '{ i = 1
       while (i <= 3) {
           print $i
           i++
       }
}' inventory-shipped

The body of this loop is a compound statement enclosed in braces, containing two statements. The loop works in the following manner: first, the value of i is set to one. Then, the while statement tests whether i is less than or equal to three. This is true when i equals one, so the i-th field is printed. Then the i++ increments the value of i and the loop repeats. The loop terminates when i reaches four.

A newline is not required between the condition and the body; however using one makes the program clearer unless the body is a compound statement or else is very simple. The newline after the open-brace that begins the compound statement is not required either, but the program is harder to read without it.

Node:Do Statement, Next:For Statement, Previous:While Statement, Up:Statements

The do-while Statement

The do loop is a variation of the while looping statement. The do loop executes the body once and then repeats the body as long as the condition is true. It looks like this:

do
  body
while (condition)

Even if the condition is false at the start, the body is executed at least once (and only once, unless executing body makes condition true). Contrast this with the corresponding while statement:

while (condition)
  body

This statement does not execute body even once if the condition is false to begin with. The following is an example of a do statement:

{      i = 1
       do {
          print $0
          i++
       } while (i <= 10)
}

This program prints each input record 10 times. However, it isn't a very realistic example, since in this case an ordinary while would do just as well. This situation reflects actual experience; only occasionally is there a real use for a do statement.

Node:For Statement, Next:Break Statement, Previous:Do Statement, Up:Statements

The for Statement

The for statement makes it more convenient to count iterations of a loop. The general form of the for statement looks like this:

for (initialization; condition; increment)
  body

The initialization, condition, and increment parts are arbitrary awk expressions, and body stands for any awk statement.

The for statement starts by executing initialization. Then, as long as the condition is true, it repeatedly executes body and then increment. Typically, initialization sets a variable to either zero or one, increment adds one to it, and condition compares it against the desired number of iterations. For example:

awk '{ for (i = 1; i <= 3; i++)
          print $i
}' inventory-shipped

This prints the first three fields of each input record, with one field per line.

It isn't possible to set more than one variable in the initialization part without using a multiple assignment statement such as x = y = 0. This makes sense only if all the initial values are equal. (But it is possible to initialize additional variables by writing their assignments as separate statements preceding the for loop.)

The same is true of the increment part. Incrementing additional variables requires separate statements at the end of the loop. The C compound expression, using C's comma operator, is useful in this context but it is not supported in awk.

Most often, increment is an increment expression, as in the previous example. But this is not required; it can be any expression whatsoever. For example, the following statement prints all the powers of two between 1 and 100:

for (i = 1; i <= 100; i *= 2)
  print i

If there is nothing to be done, any of the three expressions in the parentheses following the for keyword may be omitted. Thus, for (; x > 0;) is equivalent to while (x > 0). If the condition is omitted, it is treated as true, effectively yielding an infinite loop (i.e., a loop that never terminates).

In most cases, a for loop is an abbreviation for a while loop, as shown here:

initialization
while (condition) {
  body
  increment
}

The only exception is when the continue statement (see The continue Statement) is used inside the loop. Changing a for statement to a while statement in this way can change the effect of the continue statement inside the loop.

The awk language has a for statement in addition to a while statement because a for loop is often both less work to type and more natural to think of. Counting the number of iterations is very common in loops. It can be easier to think of this counting as part of looping rather than as something to do inside the loop.

Node:Break Statement, Next:Continue Statement, Previous:For Statement, Up:Statements

The break Statement

The break statement jumps out of the innermost for, while, or do loop that encloses it. The following example finds the smallest divisor of any integer, and also identifies prime numbers:

# find smallest divisor of num
{
   num = $1
   for (div = 2; div*div <= num; div++)
     if (num % div == 0)
       break
   if (num % div == 0)
     printf "Smallest divisor of %d is %d\n", num, div
   else
     printf "%d is prime\n", num
}

When the remainder is zero in the first if statement, awk immediately breaks out of the containing for loop. This means that awk proceeds immediately to the statement following the loop and continues processing. (This is very different from the exit statement, which stops the entire awk program. See The exit Statement.)

Th following program illustrates how the condition of a for or while statement could be replaced with a break inside an if:

# find smallest divisor of num
{
  num = $1
  for (div = 2; ; div++) {
    if (num % div == 0) {
      printf "Smallest divisor of %d is %d\n", num, div
      break
    }
    if (div*div > num) {
      printf "%d is prime\n", num
      break
    }
  }
}

The break statement has no meaning when used outside the body of a loop. However, although it was never documented, historical implementations of awk treated the break statement outside of a loop as if it were a next statement (see The next Statement). Recent versions of Unix awk no longer allow this usage. gawk supports this use of break only if --traditional has been specified on the command line (see Command-Line Options). Otherwise, it is treated as an error, since the POSIX standard specifies that break should only be used inside the body of a loop. (d.c.)

Node:Continue Statement, Next:Next Statement, Previous:Break Statement, Up:Statements

The continue Statement

As with break, the continue statement is used only inside for, while, and do loops. It skips over the rest of the loop body, causing the next cycle around the loop to begin immediately. Contrast this with break, which jumps out of the loop altogether.

The continue statement in a for loop directs awk to skip the rest of the body of the loop and resume execution with the increment-expression of the for statement. The following program illustrates this fact:

BEGIN {
     for (x = 0; x <= 20; x++) {
         if (x == 5)
             continue
         printf "%d ", x
     }
     print ""
}

This program prints all the numbers from 0 to 20--except for 5, for which the printf is skipped. Because the increment x++ is not skipped, x does not remain stuck at 5. Contrast the for loop from the previous example with the following while loop:

BEGIN {
     x = 0
     while (x <= 20) {
         if (x == 5)
             continue
         printf "%d ", x
         x++
     }
     print ""
}

This program loops forever once x reaches 5.

The continue statement has no meaning when used outside the body of a loop. Historical versions of awk treated a continue statement outside a loop the same way they treated a break statement outside a loop: as if it were a next statement (see The next Statement). Recent versions of Unix awk no longer work this way, and gawk allows it only if --traditional is specified on the command line (see Command-Line Options). Just like the break statement, the POSIX standard specifies that continue should only be used inside the body of a loop. (d.c.)

Node:Next Statement, Next:Nextfile Statement, Previous:Continue Statement, Up:Statements

The next Statement

The next statement forces awk to immediately stop processing the current record and go on to the next record. This means that no further rules are executed for the current record, and the rest of the current rule's action isn't executed.

Contrast this with the effect of the getline function (see Explicit Input with getline). That also causes awk to read the next record immediately, but it does not alter the flow of control in any way (i.e., the rest of the current action executes with a new input record).

At the highest level, awk program execution is a loop that reads an input record and then tests each rule's pattern against it. If you think of this loop as a for statement whose body contains the rules, then the next statement is analogous to a continue statement. It skips to the end of the body of this implicit loop and executes the increment (which reads another record).

For example, suppose an awk program works only on records with four fields, and it shouldn't fail when given bad input. To avoid complicating the rest of the program, write a "weed out" rule near the beginning, in the following manner:

NF != 4 {
  err = sprintf("%s:%d: skipped: NF != 4\n", FILENAME, FNR)
  print err > "/dev/stderr"
  next
}

Because of the next statement, the program's subsequent rules won't see the bad record. The error message is redirected to the standard error output stream, as error messages should be. For more detail see Special File Names in gawk.

According to the POSIX standard, the behavior is undefined if the next statement is used in a BEGIN or END rule. gawk treats it as a syntax error. Although POSIX permits it, some other awk implementations don't allow the next statement inside function bodies (see User-Defined Functions). Just as with any other next statement, a next statement inside a function body reads the next record and starts processing it with the first rule in the program. If the next statement causes the end of the input to be reached, then the code in any END rules is executed. See The BEGIN and END Special Patterns.

Node:Nextfile Statement, Next:Exit Statement, Previous:Next Statement, Up:Statements

Using gawk's nextfile Statement

gawk provides the nextfile statement, which is similar to the next statement. However, instead of abandoning processing of the current record, the nextfile statement instructs gawk to stop processing the current data file.

The nextfile statement is a gawk extension. In most other awk implementations, or if gawk is in compatibility mode (see Command-Line Options), nextfile is not special.

Upon execution of the nextfile statement, FILENAME is updated to the name of the next data file listed on the command line, FNR is reset to one, ARGIND is incremented, and processing starts over with the first rule in the program. (ARGIND hasn't been introduced yet. See Built-in Variables.) If the nextfile statement causes the end of the input to be reached, then the code in any END rules is executed. See The BEGIN and END Special Patterns.

The nextfile statement is useful when there are many data files to process but it isn't necessary to process every record in every file. Normally, in order to move on to the next data file, a program has to continue scanning the unwanted records. The nextfile statement accomplishes this much more efficiently.

While one might think that close(FILENAME) would accomplish the same as nextfile, this isn't true. close is reserved for closing files, pipes, and coprocesses that are opened with redirections. It is not related to the main processing that awk does with the files listed in ARGV.

If it's necessary to use an awk version that doesn't support nextfile, see Implementing nextfile as a Function, for a user-defined function that simulates the nextfile statement.

The current version of the Bell Laboratories awk (see Other Freely Available awk Implementations) also supports nextfile. However, it doesn't allow the nextfile statement inside function bodies (see User-Defined Functions). gawk does; a nextfile inside a function body reads the next record and starts processing it with the first rule in the program, just as any other nextfile statement.

Caution: Versions of gawk prior to 3.0 used two words (next file) for the nextfile statement. In version 3.0, this was changed to one word, because the treatment of file was inconsistent. When it appeared after next, file was a keyword; otherwise, it was a regular identifier. The old usage is no longer accepted; next file generates a syntax error.

Node:Exit Statement, Previous:Nextfile Statement, Up:Statements

The exit Statement

The exit statement causes awk to immediately stop executing the current rule and to stop processing input; any remaining input is ignored. The exit statement is written as follows:

exit [return code]

When an exit statement is executed from a BEGIN rule, the program stops processing everything immediately. No input records are read. However, if an END rule is present, as part of executing the exit statement, the END rule is executed (see The BEGIN and END Special Patterns). If exit is used as part of an END rule, it causes the program to stop immediately.

An exit statement that is not part of a BEGIN or END rule stops the execution of any further automatic rules for the current record, skips reading any remaining input records, and executes the END rule if there is one.

In such a case, if you don't want the END rule to do its job, set a variable to nonzero before the exit statement and check that variable in the END rule. See Assertions, for an example that does this.

If an argument is supplied to exit, its value is used as the exit status code for the awk process. If no argument is supplied, exit returns status zero (success). In the case where an argument is supplied to a first exit statement, and then exit is called a second time from an END rule with no argument, awk uses the previously supplied exit value. (d.c.)

For example, suppose an error condition occurs that is difficult or impossible to handle. Conventionally, programs report this by exiting with a nonzero status. An awk program can do this using an exit statement with a nonzero argument, as shown in the following example:

BEGIN {
       if (("date" | getline date_now) <= 0) {
         print "Can't get system date" > "/dev/stderr"
         exit 1
       }
       print "current date is", date_now
       close("date")
}

Node:Built-in Variables, Previous:Statements, Up:Patterns and Actions

Built-in Variables

Most awk variables are available to use for your own purposes; they never change unless your program assigns values to them, and they never affect anything unless your program examines them. However, a few variables in awk have special built-in meanings. awk examines some of these automatically, so that they enable you to tell awk how to do certain things. Others are set automatically by awk, so that they carry information from the internal workings of awk to your program.

This section documents all the built-in variables of gawk, most of which are also documented in the chapters describing their areas of activity.

  • User-modified: Built-in variables that you change to control awk.
  • Auto-set: Built-in variables where awk gives you information.
  • ARGC and ARGV: Ways to use ARGC and ARGV.

Node:User-modified, Next:Auto-set, Previous:Built-in Variables, Up:Built-in Variables

Built-in Variables That Control awk

The following is an alphabetical list of variables that you can change to control how awk does certain things. The variables that are specific to gawk are marked with a pound sign (#).

BINMODE #
On non-POSIX systems, this variable specifies use of binary mode for all I/O. Numeric values of one, two, or three specify that input files, output files, or all files, respectively, should use binary I/O. Alternatively, string values of "r" or "w" specify that input files and output files, respectively, should use binary I/O. A string value of "rw" or "wr" indicates that all files should use binary I/O. Any other string value is equivalent to "rw", but gawk generates a warning message. BINMODE is described in more detail in Using gawk on PC Operating Systems.

This variable is a gawk extension. In other awk implementations (except mawk, see Other Freely Available awk Implementations), or if gawk is in compatibility mode (see Command-Line Options), it is not special.

CONVFMT
This string controls conversion of numbers to strings (see Conversion of Strings and Numbers). It works by being passed, in effect, as the first argument to the sprintf function (see String Manipulation Functions). Its default value is "%.6g". CONVFMT was introduced by the POSIX standard.
FIELDWIDTHS #
This is a space-separated list of columns that tells gawk how to split input with fixed columnar boundaries. Assigning a value to FIELDWIDTHS overrides the use of FS for field splitting. See Reading Fixed-Width Data, for more information.

If gawk is in compatibility mode (see Command-Line Options), then FIELDWIDTHS has no special meaning, and field-splitting operations occur based exclusively on the value of FS.

FS
This is the input field separator (see Specifying How Fields Are Separated). The value is a single-character string or a multi-character regular expression that matches the separations between fields in an input record. If the value is the null string (""), then each character in the record becomes a separate field. (This behavior is a gawk extension. POSIX awk does not specify the behavior when FS is the null string.)

The default value is " ", a string consisting of a single space. As a special exception, this value means that any sequence of spaces, tabs, and/or newlines is a single separator.24 It also causes spaces, tabs, and newlines at the beginning and end of a record to be ignored.

You can set the value of FS on the command line using the -F option:

awk -F, 'program' input-files

If gawk is using FIELDWIDTHS for field splitting, assigning a value to FS causes gawk to return to the normal, FS-based field splitting. An easy way to do this is to simply say FS = FS, perhaps with an explanatory comment.

IGNORECASE #
If IGNORECASE is nonzero or non-null, then all string comparisons and all regular expression matching are case independent. Thus, regexp matching with ~ and !~, as well as the gensub, gsub, index, match, split, and sub functions, record termination with RS, and field splitting with FS, all ignore case when doing their particular regexp operations. However, the value of IGNORECASE does not affect array subscripting. See Case Sensitivity in Matching.

If gawk is in compatibility mode (see Command-Line Options), then IGNORECASE has no special meaning. Thus, string and regexp operations are always case-sensitive.

LINT #
When this variable is true (nonzero or non-null), gawk behaves as if the --lint command-line option is in effect. (see Command-Line Options). With a value of "fatal", lint warnings become fatal errors. Any other true value prints nonfatal warnings. Assigning a false value to LINT turns off the lint warnings.

This variable is a gawk extension. It is not special in other awk implementations. Unlike the other special variables, changing LINT does affect the production of lint warnings, even if gawk is in compatibility mode. Much as the --lint and --traditional options independently control different aspects of gawk's behavior, the control of lint warnings during program execution is independent of the flavor of awk being executed.

OFMT
This string controls conversion of numbers to strings (see Conversion of Strings and Numbers) for printing with the print statement. It works by being passed as the first argument to the sprintf function (see String Manipulation Functions). Its default value is "%.6g". Earlier versions of awk also used OFMT to specify the format for converting numbers to strings in general expressions; this is now done by CONVFMT.
OFS
This is the output field separator (see Output Separators). It is output between the fields printed by a print statement. Its default value is " ", a string consisting of a single space.
ORS
This is the output record separator. It is output at the end of every print statement. Its default value is "\n", the newline character. (See Output Separators.)
RS
This is awk's input record separator. Its default value is a string containing a single newline character, which means that an input record consists of a single line of text. It can also be the null string, in which case records are separated by runs of blank lines. If it is a regexp, records are separated by matches of the regexp in the input text. (See How Input Is Split into Records.)

The ability for RS to be a regular expression is a gawk extension. In most other awk implementations, or if gawk is in compatibility mode (see Command-Line Options), just the first character of RS's value is used.

SUBSEP
This is the subscript separator. It has the default value of "\034" and is used to separate the parts of the indices of a multidimensional array. Thus, the expression foo["A", "B"] really accesses foo["A\034B"] (see Multidimensional Arrays).
TEXTDOMAIN #
This variable is used for internationalization of programs at the awk level. It sets the default text domain for specially marked string constants in the source text, as well as for the dcgettext, dcngettext and bindtextdomain functions (see Internationalization with gawk). The default value of TEXTDOMAIN is "messages".

This variable is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see Command-Line Options), it is not special.

Node:Auto-set, Next:ARGC and ARGV, Previous:User-modified, Up:Built-in Variables

Built-in Variables That Convey Information

The following is an alphabetical list of variables that awk sets automatically on certain occasions in order to provide information to your program. The variables that are specific to gawk are marked with an asterisk (*).

ARGC, ARGV
The command-line arguments available to awk programs are stored in an array called ARGV. ARGC is the number of command-line arguments present. See Other Command-Line Arguments. Unlike most awk arrays, ARGV is indexed from 0 to ARGC - 1. In the following example:
$ awk 'BEGIN {
>         for (i = 0; i < ARGC; i++)
>             print ARGV[i]
>      }' inventory-shipped BBS-list
-| awk
-| inventory-shipped
-| BBS-list

ARGV[0] contains "awk", ARGV[1] contains "inventory-shipped", and ARGV[2] contains "BBS-list". The value of ARGC is three, one more than the index of the last element in ARGV, because the elements are numbered from zero.

The names ARGC and ARGV, as well as the convention of indexing the array from 0 to ARGC - 1, are derived from the C language's method of accessing command-line arguments.

The value of ARGV[0] can vary from system to system. Also, you should note that the program text is not included in ARGV, nor are any of awk's command-line options. See Using ARGC and ARGV, for information about how awk uses these variables.

ARGIND #
The index in ARGV of the current file being processed. Every time gawk opens a new data file for processing, it sets ARGIND to the index in ARGV of the file name. When gawk is processing the input files, FILENAME == ARGV[ARGIND] is always true.

This variable is useful in file processing; it allows you to tell how far along you are in the list of data files as well as to distinguish between successive instances of the same file name on the command line.

While you can change the value of ARGIND within your awk program, gawk automatically sets it to a new value when the next file is opened.

This variable is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see Command-Line Options), it is not special.

ENVIRON
An associative array that contains the values of the environment. The array indices are the environment variable names; the elements are the values of the particular environment variables. For example, ENVIRON["HOME"] might be /home/arnold. Changing this array does not affect the environment passed on to any programs that awk may spawn via redirection or the system function.

Some operating systems may not have environment variables. On such systems, the ENVIRON array is empty (except for ENVIRON["AWKPATH"], see The AWKPATH Environment Variable).

ERRNO #
If a system error occurs during a redirection for getline, during a read for getline, or during a close operation, then ERRNO contains a string describing the error.

This variable is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see Command-Line Options), it is not special.

FILENAME
The name of the file that awk is currently reading. When no data files are listed on the command line, awk reads from the standard input and FILENAME is set to "-". FILENAME is changed each time a new file is read (see Reading Input Files). Inside a BEGIN rule, the value of FILENAME is "", since there are no input files being processed yet.25 (d.c.) Note, though, that using getline (see Explicit Input with getline) inside a BEGIN rule can give FILENAME a value.
FNR
The current record number in the current file. FNR is incremented each time a new record is read (see Explicit Input with getline). It is reinitialized to zero each time a new input file is started.
NF
The number of fields in the current input record. NF is set each time a new record is read, when a new field is created or when $0 changes (see Examining Fields).
NR
The number of input records awk has processed since the beginning of the program's execution (see How Input Is Split into Records). NR is incremented each time a new record is read.
PROCINFO #
The elements of this array provide access to information about the running awk program. The following elements (listed alphabetically) are guaranteed to be available:
PROCINFO["egid"]
The value of the getegid system call.
PROCINFO["euid"]
The value of the geteuid system call.
PROCINFO["FS"]
This is "FS" if field splitting with FS is in effect, or it is "FIELDWIDTHS" if field splitting with FIELDWIDTHS is in effect.
PROCINFO["gid"]
The value of the getgid system call.
PROCINFO["pgrpid"]
The process group ID of the current process.
PROCINFO["pid"]
The process ID of the current process.
PROCINFO["ppid"]
The parent process ID of the current process.
PROCINFO["uid"]
The value of the getuid system call.

On some systems, there may be elements in the array, "group1" through "groupN" for some N. N is the number of supplementary groups that the process has. Use the in operator to test for these elements (see Referring to an Array Element).

This array is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see Command-Line Options), it is not special.

RLENGTH
The length of the substring matched by the match function (see String Manipulation Functions). RLENGTH is set by invoking the match function. Its value is the length of the matched string, or -1 if no match is found.
RSTART
The start-index in characters of the substring that is matched by the match function (see String Manipulation Functions). RSTART is set by invoking the match function. Its value is the position of the string where the matched substring starts, or zero if no match was found.
RT #
This is set each time a record is read. It contains the input text that matched the text denoted by RS, the record separator.

This variable is a gawk extension. In other awk implementations, or if gawk is in compatibility mode (see Command-Line Options), it is not special.

Advanced Notes: Changing NR and FNR

awk increments NR and FNR each time it reads a record, instead of setting them to the absolute value of the number of records read. This means that a program can change these variables and their new values are incremented for each record. (d.c.) This is demonstrated in the following example:

$ echo '1
> 2
> 3
> 4' | awk 'NR == 2 { NR = 17 }
> { print NR }'
-| 1
-| 17
-| 18
-| 19

Before FNR was added to the awk language (see Major Changes Between V7 and SVR3.1), many awk programs used this feature to track the number of records in a file by resetting NR to zero when FILENAME changed.

Node:ARGC and ARGV, Previous:Auto-set, Up:Built-in Variables

Using ARGC and ARGV

Built-in Variables That Convey Information, presented the following program describing the information contained in ARGC and ARGV:
$ awk 'BEGIN {
>        for (i = 0; i < ARGC; i++)
>            print ARGV[i]
>      }' inventory-shipped BBS-list
-| awk
-| inventory-shipped
-| BBS-list

In this example, ARGV[0] contains awk, ARGV[1] contains inventory-shipped, and ARGV[2] contains BBS-list. Notice that the awk program is not entered in ARGV. The other special command-line options, with their arguments, are also not entered. This includes variable assignments done with the -v option (see Command-Line Options). Normal variable assignments on the command line are treated as arguments and do show up in the ARGV array:

$ cat showargs.awk
-| BEGIN {
-|     printf "A=%d, B=%d\n", A, B
-|     for (i = 0; i < ARGC; i++)
-|         printf "\tARGV[%d] = %s\n", i, ARGV[i]
-| }
-| END   { printf "A=%d, B=%d\n", A, B }
$ awk -v A=1 -f showargs.awk B=2 /dev/null
-| A=1, B=0
-|        ARGV[0] = awk
-|        ARGV[1] = B=2
-|        ARGV[2] = /dev/null
-| A=1, B=2

A program can alter ARGC and the elements of ARGV. Each time awk reaches the end of an input file, it uses the next element of ARGV as the name of the next input file. By storing a different string there, a program can change which files are read. Use "-" to represent the standard input. Storing additional elements and incrementing ARGC causes additional files to be read.

If the value of ARGC is decreased, that eliminates input files from the end of the list. By recording the old value of ARGC elsewhere, a program can treat the eliminated arguments as something other than file names.

To eliminate a file from the middle of the list, store the null string ("") into ARGV in place of the file's name. As a special feature, awk ignores file names that have been replaced with the null string. Another option is to use the delete statement to remove elements from ARGV (see The delete Statement).

All of these actions are typically done in the BEGIN rule, before actual processing of the input begins. See Splitting a Large File into Pieces, and see Duplicating Output into Multiple Files, for examples of each way of removing elements from ARGV. The following fragment processes ARGV in order to examine, and then remove, command-line options:

BEGIN {
    for (i = 1; i < ARGC; i++) {
        if (ARGV[i] == "-v")
            verbose = 1
        else if (ARGV[i] == "-d")
            debug = 1
        else if (ARGV[i] ~ /^-?/) {
            e = sprintf("%s: unrecognized option -- %c",
                    ARGV[0], substr(ARGV[i], 1, ,1))
            print e > "/dev/stderr"
        } else
            break
        delete ARGV[i]
    }
}

To actually get the options into the awk program, end the awk options with -- and then supply the awk program's options, in the following manner:

awk -f myprog -- -v -d file1 file2 ...

This is not necessary in gawk. Unless --posix has been specified, gawk silently puts any unrecognized options into ARGV for the awk program to deal with. As soon as it sees an unknown option, gawk stops looking for other options that it might otherwise recognize. The previous example with gawk would be:

gawk -f myprog -d -v file1 file2 ...

Because -d is not a valid gawk option, it and the following -v are passed on to the awk program.

Node:Arrays, Next:Functions, Previous:Patterns and Actions, Up:Top

Arrays in awk

An array is a table of values called elements. The elements of an array are distinguished by their indices. Indices may be either numbers or strings.

This chapter describes how arrays work in awk, how to use array elements, how to scan through every element in an array, and how to remove array elements. It also describes how awk simulates multidimensional arrays, as well as some of the less obvious points about array usage. The chapter finishes with a discussion of gawk's facility for sorting an array based on its indices.

awk maintains a single set of names that may be used for naming variables, arrays, and functions (see User-Defined Functions). Thus, you cannot have a variable and an array with the same name in the same awk program.

  • Array Intro: Introduction to Arrays
  • Reference to Elements: How to examine one element of an array.
  • Assigning Elements: How to change an element of an array.
  • Array Example: Basic Example of an Array
  • Scanning an Array: A variation of the for statement. It loops through the indices of an array's existing elements.
  • Delete: The delete statement removes an element from an array.
  • Numeric Array Subscripts: How to use numbers as subscripts in awk.
  • Uninitialized Subscripts: Using Uninitialized variables as subscripts.
  • Multi-dimensional: Emulating multidimensional arrays in awk.
  • Multi-scanning: Scanning multidimensional arrays.
  • Array Sorting: Sorting array values and indices.

Node:Array Intro, Next:Reference to Elements, Previous:Arrays, Up:Arrays

Introduction to Arrays

The awk language provides one-dimensional arrays for storing groups of related strings or numbers. Every awk array must have a name. Array names have the same syntax as variable names; any valid variable name would also be a valid array name. But one name cannot be used in both ways (as an array and as a variable) in the same awk program.

Arrays in awk superficially resemble arrays in other programming languages, but there are fundamental differences. In awk, it isn't necessary to specify the size of an array before starting to use it. Additionally, any number or string in awk, not just consecutive integers, may be used as an array index.

In most other languages, arrays must be declared before use, including a specification of how many elements or components they contain. In such languages, the declaration causes a contiguous block of memory to be allocated for that many elements. Usually, an index in the array must be a positive integer. For example, the index zero specifies the first element in the array, which is actually stored at the beginning of the block of memory. Index one specifies the second element, which is stored in memory right after the first element, and so on. It is impossible to add more elements to the array, because it has room only for as many elements as given in the declaration. (Some languages allow arbitrary starting and ending indices--e.g., 15 .. 27--but the size of the array is still fixed when the array is declared.)

A contiguous array of four elements might look like the following example, conceptually, if the element values are 8, "foo", "", and 30:

Only the values are stored; the indices are implicit from the order of the values. Here, 8 is the value at index zero, because 8 appears in the position with zero elements before it.

Arrays in awk are different--they are associative. This means that each array is a collection of pairs: an index and its corresponding array element value:

Element 3     Value 30
Element 1     Value "foo"
Element 0     Value 8
Element 2     Value ""

The pairs are shown in jumbled order because their order is irrelevant.

One advantage of associative arrays is that new pairs can be added at any time. For example, suppose a tenth element is added to the array whose value is "number ten". The result is:

Element 10    Value "number ten"
Element 3     Value 30
Element 1     Value "foo"
Element 0     Value 8
Element 2     Value ""

Now the array is sparse, which just means some indices are missing. It has elements 0-3 and 10, but doesn't have elements 4, 5, 6, 7, 8, or 9.

Another consequence of associative arrays is that the indices don't have to be positive integers. Any number, or even a string, can be an index. For example, the following is an array that translates words from English to French:

Element "dog" Value "chien"
Element "cat" Value "chat"
Element "one" Value "un"
Element 1     Value "un"

Here we decided to translate the number one in both spelled-out and numeric form--thus illustrating that a single array can have both numbers and strings as indices. In fact, array subscripts are always strings; this is discussed in more detail in Using Numbers to Subscript Arrays. Here, the number 1 isn't double-quoted, since awk automatically converts it to a string.

The value of IGNORECASE has no effect upon array subscripting. The identical string value used to store an array element must be used to retrieve it. When awk creates an array (e.g., with the split built-in function), that array's indices are consecutive integers starting at one. (See String Manipulation Functions.)

awk's arrays are efficient--the time to access an element is independent of the number of elements in the array.

Node:Reference to Elements, Next:Assigning Elements, Previous:Array Intro, Up:Arrays

Referring to an Array Element

The principal way to use an array is to refer to one of its elements. An array reference is an expression as follows:

array[index]

Here, array is the name of an array. The expression index is the index of the desired element of the array.

The value of the array reference is the current value of that array element. For example, foo[4.3] is an expression for the element of array foo at index 4.3.

A reference to an array element that has no recorded value yields a value of "", the null string. This includes elements that have not been assigned any value as well as elements that have been deleted (see The delete Statement). Such a reference automatically creates that array element, with the null string as its value. (In some cases, this is unfortunate, because it might waste memory inside awk.)

To determine whether an element exists in an array at a certain index, use the following expression:

index in array

This expression tests whether the particular index exists, without the side effect of creating that element if it is not present. The expression has the value one (true) if array[index] exists and zero (false) if it does not exist. For example, this statement tests whether the array frequencies contains the index 2:

if (2 in frequencies)
    print "Subscript 2 is present."

Note that this is not a test of whether the array frequencies contains an element whose value is two. There is no way to do that except to scan all the elements. Also, this does not create frequencies[2], while the following (incorrect) alternative does:

if (frequencies[2] != "")
    print "Subscript 2 is present."

Node:Assigning Elements, Next:Array Example, Previous:Reference to Elements, Up:Arrays

Assigning Array Elements

Array elements can be assigned values just like awk variables:

array[subscript] = value

array is the name of an array. The expression subscript is the index of the element of the array that is assigned a value. The expression value is the value to assign to that element of the array.

Node:Array Example, Next:Scanning an Array, Previous:Assigning Elements, Up:Arrays

Basic Array Example

The following program takes a list of lines, each beginning with a line number, and prints them out in order of line number. The line numbers are not in order when they are first read--instead they are scrambled. This program sorts the lines by making an array using the line numbers as subscripts. The program then prints out the lines in sorted order of their numbers. It is a very simple program and gets confused upon encountering repeated numbers, gaps, or lines that don't begin with a number:

{
  if ($1 > max)
    max = $1
  arr[$1] = $0
}

END {
  for (x = 1; x <= max; x++)
    print arr[x]
}

The first rule keeps track of the largest line number seen so far; it also stores each line into the array arr, at an index that is the line's number. The second rule runs after all the input has been read, to print out all the lines. When this program is run with the following input:

5  I am the Five man
2  Who are you?  The new number two!
4  . . . And four on the floor
1  Who is number one?
3  I three you.

Its output is:

1  Who is number one?
2  Who are you?  The new number two!
3  I three you.
4  . . . And four on the floor
5  I am the Five man

If a line number is repeated, the last line with a given number overrides the others. Gaps in the line numbers can be handled with an easy improvement to the program's END rule, as follows:

END {
  for (x = 1; x <= max; x++)
    if (x in arr)
      print arr[x]
}

Node:Scanning an Array, Next:Delete, Previous:Array Example, Up:Arrays

Scanning All Elements of an Array

In programs that use arrays, it is often necessary to use a loop that executes once for each element of an array. In other languages, where arrays are contiguous and indices are limited to positive integers, this is easy: all the valid indices can be found by counting from the lowest index up to the highest. This technique won't do the job in awk, because any number or string can be an array index. So awk has a special kind of for statement for scanning an array:

for (var in array)
  body

This loop executes body once for each index in array that the program has previously used, with the variable var set to that index.

The following program uses this form of the for statement. The first rule scans the input records and notes which words appear (at least once) in the input, by storing a one into the array used with the word as index. The second rule scans the elements of used to find all the distinct words that appear in the input. It prints each word that is more than 10 characters long and also prints the number of such words. See String Manipulation Functions, for more information on the built-in function length.

# Record a 1 for each word that is used at least once
{
    for (i = 1; i <= NF; i++)
        used[$i] = 1
}

# Find number of distinct words more than 10 characters long
END {
    for (x in used)
        if (length(x) > 10) {
            ++num_long_words
            print x
        }
    print num_long_words, "words longer than 10 characters"
}

See Generating Word Usage Counts, for a more detailed example of this type.

The order in which elements of the array are accessed by this statement is determined by the internal arrangement of the array elements within awk and cannot be controlled or changed. This can lead to problems if new elements are added to array by statements in the loop body; it is not predictable whether the for loop will reach them. Similarly, changing var inside the loop may produce strange results. It is best to avoid such things.

Node:Delete, Next:Numeric Array Subscripts, Previous:Scanning an Array, Up:Arrays

The delete Statement

To remove an individual element of an array, use the delete statement:

delete array[index]

Once an array element has been deleted, any value the element once had is no longer available. It is as if the element had never been referred to or had been given a value. The following is an example of deleting elements in an array:

for (i in frequencies)
  delete frequencies[i]

This example removes all the elements from the array frequencies. Once an element is deleted, a subsequent for statement to scan the array does not report that element and the in operator to check for the presence of that element returns zero (i.e., false):

delete foo[4]
if (4 in foo)
    print "This will never be printed"

It is important to note that deleting an element is not the same as assigning it a null value (the empty string, ""). For example:

foo[4] = ""
if (4 in foo)
  print "This is printed, even though foo[4] is empty"

It is not an error to delete an element that does not exist. If --lint is provided on the command line (see Command-Line Options), gawk issues a warning message when an element that is not in the array is deleted.

All the elements of an array may be deleted with a single statement by leaving off the subscript in the delete statement, as follows:

delete array

This ability is a gawk extension; it is not available in compatibility mode (see Command-Line Options).

Using this version of the delete statement is about three times more efficient than the equivalent loop that deletes each element one at a time.

The following statement provides a portable but nonobvious way to clear out an array:26

split("", array)

The split function (see String Manipulation Functions) clears out the target array first. This call asks it to split apart the null string. Because there is no data to split out, the function simply clears the array and then returns.

Caution: Deleting an array does not change its type; you cannot delete an array and then use the array's name as a scalar (i.e., a regular variable). For example, the following does not work:

a[1] = 3; delete a; a = 3

Node:Numeric Array Subscripts, Next:Uninitialized Subscripts, Previous:Delete, Up:Arrays

Using Numbers to Subscript Arrays

An important aspect about arrays to remember is that array subscripts are always strings. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting (see Conversion of Strings and Numbers). This means that the value of the built-in variable CONVFMT can affect how your program accesses elements of an array. For example:

xyz = 12.153
data[xyz] = 1
CONVFMT = "%2.2f"
if (xyz in data)
    printf "%s is in data\n", xyz
else
    printf "%s is not in data\n", xyz

This prints 12.15 is not in data. The first statement gives xyz a numeric value. Assigning to data[xyz] subscripts data with the string value "12.153" (using the default conversion value of CONVFMT, "%.6g"). Thus, the array element data["12.153"] is assigned the value one. The program then changes the value of CONVFMT. The test (xyz in data) generates a new string value from xyz--this time "12.15"--because the value of CONVFMT only allows two significant digits. This test fails, since "12.15" is a different string from "12.153".

According to the rules for conversions (see Conversion of Strings and Numbers), integer values are always converted to strings as integers, no matter what the value of CONVFMT may happen to be. So the usual case of the following works:

for (i = 1; i <= maxsub; i++)
    do something with array[i]

The "integer values always convert to strings as integers" rule has an additional consequence for array indexing. Octal and hexadecimal constants (see Octal and Hexadecimal Numbers) are converted internally into numbers, and their original form is forgotten. This means, for example, that array[17], array[021], and array[0x11] all refer to the same element!

As with many things in awk, the majority of the time things work as one would expect them to. But it is useful to have a precise knowledge of the actual rules which sometimes can have a subtle effect on your programs.

Node:Uninitialized Subscripts, Next:Multi-dimensional, Previous:Numeric Array Subscripts, Up:Arrays

Using Uninitialized Variables as Subscripts

Suppose it's necessary to write a program to print the input data in reverse order. A reasonable attempt to do so (with some test data) might look like this:

$ echo 'line 1
> line 2
> line 3' | awk '{ l[lines] = $0; ++lines }
> END {
>     for (i = lines-1; i >= 0; --i)
>        print l[i]
> }'
-| line 3
-| line 2

Unfortunately, the very first line of input data did not come out in the output!

At first glance, this program should have worked. The variable lines is uninitialized, and uninitialized variables have the numeric value zero. So, awk should have printed the value of l[0].

The issue here is that subscripts for awk arrays are always strings. Uninitialized variables, when used as strings, have the value "", not zero. Thus, line 1 ends up stored in l[""]. The following version of the program works correctly:

{ l[lines++] = $0 }
END {
    for (i = lines - 1; i >= 0; --i)
       print l[i]
}

Here, the ++ forces lines to be numeric, thus making the "old value" numeric zero. This is then converted to "0" as the array subscript.

Even though it is somewhat unusual, the null string ("") is a valid array subscript. (d.c.) gawk warns about the use of the null string as a subscript if --lint is provided on the command line (see Command-Line Options).

Node:Multi-dimensional, Next:Multi-scanning, Previous:Uninitialized Subscripts, Up:Arrays

Multidimensional Arrays

A multidimensional array is an array in which an element is identified by a sequence of indices instead of a single index. For example, a two-dimensional array requires two indices. The usual way (in most languages, including awk) to refer to an element of a two-dimensional array named grid is with grid[x,y].

Multidimensional arrays are supported in awk through concatenation of indices into one string. awk converts the indices into strings (see Conversion of Strings and Numbers) and concatenates them together, with a separator between them. This creates a single string that describes the values of the separate indices. The combined string is used as a single index into an ordinary, one-dimensional array. The separator used is the value of the built-in variable SUBSEP.

For example, suppose we evaluate the expression foo[5,12] = "value" when the value of SUBSEP is "@". The numbers 5 and 12 are converted to strings and concatenated with an @ between them, yielding "5@12"; thus, the array element foo["5@12"] is set to "value".

Once the element's value is stored, awk has no record of whether it was stored with a single index or a sequence of indices. The two expressions foo[5,12] and foo[5 SUBSEP 12] are always equivalent.

The default value of SUBSEP is the string "\034", which contains a nonprinting character that is unlikely to appear in an awk program or in most input data. The usefulness of choosing an unlikely character comes from the fact that index values that contain a string matching SUBSEP can lead to combined strings that are ambiguous. Suppose that SUBSEP is "@"; then foo["a@b", "c"] and foo["a", "b@c"] are indistinguishable because both are actually stored as foo["a@b@c"].

To test whether a particular index sequence exists in a multidimensional array, use the same operator (in) that is used for single dimensional arrays. Write the whole sequence of indices in parentheses, separated by commas, as the left operand:

(subscript1, subscript2, ...) in array

The following example treats its input as a two-dimensional array of fields; it rotates this array 90 degrees clockwise and prints the result. It assumes that all lines have the same number of elements:

{
     if (max_nf < NF)
          max_nf = NF
     max_nr = NR
     for (x = 1; x <= NF; x++)
          vector[x, NR] = $x
}

END {
     for (x = 1; x <= max_nf; x++) {
          for (y = max_nr; y >= 1; --y)
               printf("%s ", vector[x, y])
          printf("\n")
     }
}

When given the input:

1 2 3 4 5 6
2 3 4 5 6 1
3 4 5 6 1 2
4 5 6 1 2 3

the program produces the following output:

4 3 2 1
5 4 3 2
6 5 4 3
1 6 5 4
2 1 6 5
3 2 1 6

Node:Multi-scanning, Next:Array Sorting, Previous:Multi-dimensional, Up:Arrays

Scanning Multidimensional Arrays

There is no special for statement for scanning a "multidimensional" array. There cannot be one, because, in truth, there are no multidimensional arrays or elements--there is only a multidimensional way of accessing an array.

However, if your program has an array that is always accessed as multidimensional, you can get the effect of scanning it by combining the scanning for statement (see Scanning All Elements of an Array) with the built-in split function (see String Manipulation Functions). It works in the following manner:

for (combined in array) {
    split(combined, separate, SUBSEP)
    ...
}

This sets the variable combined to each concatenated combined index in the array, and splits it into the individual indices by breaking it apart where the value of SUBSEP appears. The individual indices then become the elements of the array separate.

Thus, if a value is previously stored in array[1, "foo"]; then an element with index "1\034foo" exists in array. (Recall that the default value of SUBSEP is the character with code 034.) Sooner or later, the for statement finds that index and does an iteration with the variable combined set to "1\034foo". Then the split function is called as follows:

split("1\034foo", separate, "\034")

The result is to set separate[1] to "1" and separate[2] to "foo". Presto! The original sequence of separate indices is recovered.

Node:Array Sorting, Previous:Multi-scanning, Up:Arrays

Sorting Array Values and Indices with gawk

The order in which an array is scanned with a for (i in array) loop is essentially arbitrary. In most awk implementations, sorting an array requires writing a sort function. While this can be educational for exploring different sorting algorithms, usually that's not the point of the program. gawk provides the built-in asort function (see String Manipulation Functions) that sorts an array. For example:

populate the array data
n = asort(data)
for (i = 1; i <= n; i++)
    do something with data[i]

After the call to asort, the array data is indexed from 1 to some number n, the total number of elements in data. (This count is asort's return value.) data[1] <= data[2] <= data[3], and so on. The comparison of array elements is done using gawk's usual comparison rules (see Variable Typing and Comparison Expressions).

An important side effect of calling asort is that the array's original indices are irrevocably lost. As this isn't always desirable, asort accepts a second argument:

populate the array source
n = asort(source, dest)
for (i = 1; i <= n; i++)
    do something with dest[i]

In this case, gawk copies the source array into the dest array and then sorts dest, destroying its indices. However, the source array is not affected.

Often, what's needed is to sort on the values of the indices instead of the values of the elements. To do this, use a helper array to hold the sorted index values, and then access the original array's elements. It works in the following way:

populate the array data
# copy indices
j = 1
for (i in data) {
    ind[j] = i    # index value becomes element value
    j++
}
n = asort(ind)    # index values are now sorted
for (i = 1; i <= n; i++)
    do something with data[ind[i]]

Sorting the array by replacing the indices provides maximal flexibility. To traverse the elements in decreasing order, use a loop that goes from n down to 1, either over the elements or over the indices.

Copying array indices and elements isn't expensive in terms of memory. Internally, gawk maintains reference counts to data. For example, when asort copies the first array to the second one, there is only one copy of the original array elements' data, even though both arrays use the values. Similarly, when copying the indices from data to ind, there is only one copy of the actual index strings.

As with array subscripts, the value of IGNORECASE does not affect array sorting.

Node:Functions, Next:Internationalization, Previous:Arrays, Up:Top

Functions

This chapter describes awk's built-in functions, which fall into three categories: numeric, string, and I/O. gawk provides additional groups of functions to work with values that represent time, do bit manipulation, and internationalize and localize programs.

Besides the built-in functions, awk has provisions for writing new functions that the rest of a program can use. The second half of this chapter describes these user-defined functions.

  • Built-in: Summarizes the built-in functions.
  • User-defined: Describes User-defined functions in detail.

Node:Built-in, Next:User-defined, Previous:Functions, Up:Functions

Built-in Functions

Built-in functions are always available for your awk program to call. This section defines all the built-in functions in awk; some of these are mentioned in other sections but are summarized here for your convenience.

  • Calling Built-in: How to call built-in functions.
  • Numeric Functions: Functions that work with numbers, including int, sin and rand.
  • String Functions: Functions for string manipulation, such as split, match and sprintf.
  • I/O Functions: Functions for files and shell commands.
  • Time Functions: Functions for dealing with timestamps.
  • Bitwise Functions: Functions for bitwise operations.
  • I18N Functions: Functions for string translation.

Node:Calling Built-in, Next:Numeric Functions, Previous:Built-in, Up:Built-in

Calling Built-in Functions

To call one of awk's built-in functions, write the name of the function followed by arguments in parentheses. For example, atan2(y + z, 1) is a call to the function atan2 and has two arguments.

Whitespace is ignored between the built-in function name and the open parenthesis, and it is good practice to avoid using whitespace there. User-defined functions do not permit whitespace in this way, and it is easier to avoid mistakes by following a simple convention that always works--no whitespace after a function name.

Each built-in function accepts a certain number of arguments. In some cases, arguments can be omitted. The defaults for omitted arguments vary from function to function and are described under the individual functions. In some awk implementations, extra arguments given to built-in functions are ignored. However, in gawk, it is a fatal error to give extra arguments to a built-in function.

When a function is called, expressions that create the function's actual parameters are evaluated completely before the call is performed. For example, in the following code fragment:

i = 4
j = sqrt(i++)

the variable i is incremented to the value five before sqrt is called with a value of four for its actual parameter. The order of evaluation of the expressions used for the function's parameters is undefined. Thus, avoid writing programs that assume that parameters are evaluated from left to right or from right to left. For example:

i = 5
j = atan2(i++, i *= 2)

If the order of evaluation is left to right, then i first becomes 6, and then 12, and atan2 is called with the two arguments 6 and 12. But if the order of evaluation is right to left, i first becomes 10, then 11, and atan2 is called with the two arguments 11 and 10.

Node:Numeric Functions, Next:String Functions, Previous:Calling Built-in, Up:Built-in

Numeric Functions

The following list describes all of the built-in functions that work with numbers. Optional parameters are enclosed in square brackets ([ ]):

int(x)
This returns the nearest integer to x, located between x and zero and truncated toward zero.

For example, int(3) is 3, int(3.9) is 3, int(-3.9) is -3, and int(-3) is -3 as well.

sqrt(x)
This returns the positive square root of x. gawk reports an error if x is negative. Thus, sqrt(4) is 2.
exp(x)
This returns the exponential of x (e ^ x) or reports an error if x is out of range. The range of values x can have depends on your machine's floating-point representation.
log(x)
This returns the natural logarithm of x, if x is positive; otherwise, it reports an error.
sin(x)
This returns the sine of x, with x in radians.
cos(x)
This returns the cosine of x, with x in radians.
atan2(y, x)
This returns the arctangent of y / x in radians.
rand()
This returns a random number. The values of rand are uniformly distributed between zero and one. The value is never zero and never one.27

Often random integers are needed instead. Following is a user-defined function that can be used to obtain a random non-negative integer less than n:

function randint(n) {
     return int(n * rand())
}

The multiplication produces a random number greater than zero and less than n. Using int, this result is made into an integer between zero and n - 1, inclusive.

The following example uses a similar function to produce random integers between one and n. This program prints a new random number for each input record:

# Function to roll a simulated die.
function roll(n) { return 1 + int(rand() * n) }

# Roll 3 six-sided dice and
# print total number of points.
{
      printf("%d points\n",
             roll(6)+roll(6)+roll(6))
}

Caution: In most awk implementations, including gawk, rand starts generating numbers from the same starting number, or seed, each time you run awk. Thus, a program generates the same results each time you run it. The numbers are random within one awk run but predictable from run to run. This is convenient for debugging, but if you want a program to do different things each time it is used, you must change the seed to a value that is different in each run. To do this, use srand.

srand([x])
The function srand sets the starting point, or seed, for generating random numbers to the value x.

Each seed value leads to a particular sequence of random numbers.28 Thus, if the seed is set to the same value a second time, the same sequence of random numbers is produced again.

Different awk implementations use different random-number generators internally. Don't expect the same awk program to produce the same series of random numbers when executed by different versions of awk.

If the argument x is omitted, as in srand(), then the current date and time of day are used for a seed. This is the way to get random numbers that are truly unpredictable.

The return value of srand is the previous seed. This makes it easy to keep track of the seeds in case you need to consistently reproduce sequences of random numbers.

Node:String Functions, Next:I/O Functions, Previous:Numeric Functions, Up:Built-in

String-Manipulation Functions

The functions in this section look at or change the text of one or more strings. Optional parameters are enclosed in square brackets ([ ]). Those functions that are specific to gawk are marked with a pound sign (#):

  • Gory Details: More than you want to know about \ and & with sub, gsub, and gensub.
asort(source [, dest]) #
asort is a gawk-specific extension, returning the number of elements in the array source. The contents of source are sorted using gawk's normal rules for comparing values, and the indices of the sorted values of source are replaced with sequential integers starting with one. If the optional array dest is specified, then source is duplicated into dest. dest is then sorted, leaving the indices of source unchanged. For example, if the contents of a are as follows:
a["last"] = "de"
a["first"] = "sac"
a["middle"] = "cul"

A call to asort:

asort(a)

results in the following contents of a:

a[1] = "cul"
a[2] = "de"
a[3] = "sac"

The asort function is described in more detail in Sorting Array Values and Indices with gawk. asort is a gawk extension; it is not available in compatibility mode (see Command-Line Options).

index(in, find)
This searches the string in for the first occurrence of the string find, and returns the position in characters where that occurrence begins in the string in. Consider the following example:
$ awk 'BEGIN { print index("peanut", "an") }'
-| 3

If find is not found, index returns zero. (Remember that string indices in awk start at one.)

length([string])
This returns the number of characters in string. If string is a number, the length of the digit string representing that number is returned. For example, length("abcde") is 5. By contrast, length(15 * 35) works out to 3. In this example, 15 * 35 = 525, and 525 is then converted to the string "525", which has three characters.

If no argument is supplied, length returns the length of $0.

Note: In older versions of awk, the length function could be called without any parentheses. Doing so is marked as "deprecated" in the POSIX standard. This means that while a program can do this, it is a feature that can eventually be removed from a future version of the standard. Therefore, for programs to be maximally portable, always supply the parentheses.

match(string, regexp [, array])
The match function searches string for the longest, leftmost substring matched by the regular expression, regexp. It returns the character position, or index, at which that substring begins (one, if it starts at the beginning of string). If no match is found, it returns zero.

The order of the first two arguments is backwards from most other string functions that work with regular expressions, such as sub and gsub. It might help to remember that for match, the order is the same as for the ~ operator: string ~ regexp.

The match function sets the built-in variable RSTART to the index. It also sets the built-in variable RLENGTH to the length in characters of the matched substring. If no match is found, RSTART is set to zero, and RLENGTH to -1.

For example:

{
       if ($1 == "FIND")
         regex = $2
       else {
         where = match($0, regex)
         if (where != 0)
           print "Match of", regex, "found at",
                     where, "in", $0
       }
}

This program looks for lines that match the regular expression stored in the variable regex. This regular expression can be changed. If the first word on a line is FIND, regex is changed to be the second word on that line. Therefore, if given:

FIND ru+n
My program runs
but not very quickly
FIND Melvin
JF+KM
This line is property of Reality Engineering Co.
Melvin was here.

awk prints:

Match of ru+n found at 12 in My program runs
Match of Melvin found at 1 in Melvin was here.

If array is present, it is cleared, and then the 0th element of array is set to the entire portion of string matched by regexp. If regexp contains parentheses, the integer-indexed elements of array are set to contain the portion of string matching the corresponding parenthesized subexpression. For example:

$ echo foooobazbarrrrr |
> gawk '{ match($0, /(fo+).+(bar*)/, arr)
>           print arr[1], arr[2] }'
-| foooo barrrrr

The array argument to match is a gawk extension. In compatibility mode (see Command-Line Options), using a third argument is a fatal error.

split(string, array [, fieldsep])
This function divides string into pieces separated by fieldsep and stores the pieces in array. The first piece is stored in array[1], the second piece in array[2], and so forth. The string value of the third argument, fieldsep, is a regexp describing where to split string (much as FS can be a regexp describing where to split input records). If fieldsep is omitted, the value of FS is used. split returns the number of elements created.

The split function splits strings into pieces in a manner similar to the way input lines are split into fields. For example:

split("cul-de-sac", a, "-")

splits the string cul-de-sac into three fields using - as the separator. It sets the contents of the array a as follows:

a[1] = "cul"
a[2] = "de"
a[3] = "sac"

The value returned by this call to split is three.

As with input field-splitting, when the value of fieldsep is " ", leading and trailing whitespace is ignored, and the elements are separated by runs of whitespace. Also as with input field-splitting, if fieldsep is the null string, each individual character in the string is split into its own array element. (This is a gawk-specific extension.)

Modern implementations of awk, including gawk, allow the third argument to be a regexp constant (/abc/) as well as a string. (d.c.) The POSIX standard allows this as well.

Before splitting the string, split deletes any previously existing elements in the array array. If string does not match fieldsep at all, array has one element only. The value of that element is the original string.

sprintf(format, expression1, ...)
This returns (without printing) the string that printf would have printed out with the same arguments (see Using printf Statements for Fancier Printing). For example:
pival = sprintf("pi = %.2f (approx.)", 22/7)

assigns the string "pi = 3.14 (approx.)" to the variable pival.

strtonum(str) #
Examines str and returns its numeric value. If str begins with a leading 0, strtonum assumes that str is an octal number. If str begins with a leading 0x or 0X, strtonum assumes that str is a hexadecimal number. For example:
$ echo 0x11 |
> gawk '{ printf "%d\n", strtonum($1) }'
-| 17

Using the strtonum function is not the same as adding zero to a string value; the automatic coercion of strings to numbers works only for decimal data, not for octal or hexadecimal.29

strtonum is a gawk extension; it is not available in compatibility mode (see Command-Line Options).

sub(regexp, replacement [, target])
The sub function alters the value of target. It searches this value, which is treated as a string, for the leftmost, longest substring matched by the regular expression regexp. Then the entire string is changed by replacing the matched text with replacement. The modified string becomes the new value of target.

This function is peculiar because target is not simply used to compute a value, and not just any expression will do--it must be a variable, field, or array element so that sub can store a modified value there. If this argument is omitted, then the default is to use and alter $0. For example:

str = "water, water, everywhere"
sub(/at/, "ith", str)

sets str to "wither, water, everywhere", by replacing the leftmost longest occurrence of at with ith.

The sub function returns the number of substitutions made (either one or zero).

If the special character & appears in replacement, it stands for the precise substring that was matched by regexp. (If the regexp can match more than one string, then this precise substring may vary.) For example:

{ sub(/candidate/, "& and his wife"); print }

changes the first occurrence of candidate to candidate and his wife on each input line. Here is another example:

$ awk 'BEGIN {
>         str = "daabaaa"
>         sub(/a+/, "C&C", str)
>         print str
> }'
-| dCaaCbaaa

This shows how & can represent a nonconstant string and also illustrates the "leftmost, longest" rule in regexp matching (see How Much Text Matches?).

The effect of this special character (&) can be turned off by putting a backslash before it in the string. As usual, to insert one backslash in the string, you must write two backslashes. Therefore, write \\& in a string constant to include a literal & in the replacement. For example, the following shows how to replace the first | on each line with an &:

{ sub(/\|/, "\\&"); print }

As mentioned, the third argument to sub must be a variable, field or array reference. Some versions of awk allow the third argument to be an expression that is not an lvalue. In such a case, sub still searches for the pattern and returns zero or one, but the result of the substitution (if any) is thrown away because there is no place to put it. Such versions of awk accept expressions such as the following:

sub(/USA/, "United States", "the USA and Canada")

For historical compatibility, gawk accepts erroneous code, such as in the previous example. However, using any other nonchangeable object as the third parameter causes a fatal error and your program will not run.

Finally, if the regexp is not a regexp constant, it is converted into a string, and then the value of that string is treated as the regexp to match.

gsub(regexp, replacement [, target])
This is similar to the sub function, except gsub replaces all of the longest, leftmost, nonoverlapping matching substrings it can find. The g in gsub stands for "global," which means replace everywhere. For example:
{ gsub(/Britain/, "United Kingdom"); print }

replaces all occurrences of the string Britain with United Kingdom for all input records.

The gsub function returns the number of substitutions made. If the variable to search and alter (target) is omitted, then the entire input record ($0) is used. As in sub, the characters & and \ are special, and the third argument must be assignable.

gensub(regexp, replacement, how [, target]) #
gensub is a general substitution function. Like sub and gsub, it searches the target string target for matches of the regular expression regexp. Unlike sub and gsub, the modified string is returned as the result of the function and the original target string is not changed. If how is a string beginning with g or G, then it replaces all matches of regexp with replacement. Otherwise, how is treated as a number that indicates which match of regexp to replace. If no target is supplied, $0 is used.

gensub provides an additional feature that is not available in sub or gsub: the ability to specify components of a regexp in the replacement text. This is done by using parentheses in the regexp to mark the components and then specifying \N in the replacement text, where N is a digit from 1 to 9. For example:

$ gawk '
> BEGIN {
>      a = "abc def"
>      b = gensub(/(.+) (.+)/, "\\2 \\1", "g", a)
>      print b
> }'
-| def abc

As with sub, you must type two backslashes in order to get one into the string. In the replacement text, the sequence \0 represents the entire matched text, as does the character &.

The following example shows how you can use the third argument to control which match of the regexp should be changed:

$ echo a b c a b c |
> gawk '{ print gensub(/a/, "AA", 2) }'
-| a b c AA b c

In this case, $0 is used as the default target string. gensub returns the new string as its result, which is passed directly to print for printing.

If the how argument is a string that does not begin with g or G, or if it is a number that is less than or equal to zero, only one substitution is performed. If how is zero, gawk issues a warning message.

If regexp does not match target, gensub's return value is the original unchanged value of target.

gensub is a gawk extension; it is not available in compatibility mode (see Command-Line Options).

substr(string, start [, length])
This returns a length-character-long substring of string, starting at character number start. The first character of a string is character number one.30 For example, substr("washington", 5, 3) returns "ing".

If length is not present, this function returns the whole suffix of string that begins at character number start. For example, substr("washington", 5) returns "ington". The whole suffix is also returned if length is greater than the number of characters remaining in the string, counting from character start.

If start is less than one or greater than the number of characters in the string, substr returns the null string. Similarly, if length is present but less than or equal to zero, the null string is returned.

The string returned by substr cannot be assigned. Thus, it is a mistake to attempt to change a portion of a string, as shown in the following example:

string = "abcdef"
# try to get "abCDEf", won't work
substr(string, 3, 3) = "CDE"

It is also a mistake to use substr as the third argument of sub or gsub:

gsub(/xyz/, "pdq", substr($0, 5, 20))  # WRONG

(Some commercial versions of awk do in fact let you use substr this way, but doing so is not portable.)

If you need to replace bits and pieces of a string, combine substr with string concatenation, in the following manner:

string = "abcdef"
...
string = substr(string, 1, 2) "CDE" substr(string, 6)

tolower(string)
This returns a copy of string, with each uppercase character in the string replaced with its corresponding lowercase character. Nonalphabetic characters are left unchanged. For example, tolower("MiXeD cAsE 123") returns "mixed case 123".
toupper(string)
This returns a copy of string, with each lowercase character in the string replaced with its corresponding uppercase character. Nonalphabetic characters are left unchanged. For example, toupper("MiXeD cAsE 123") returns "MIXED CASE 123".

Node:Gory Details, Previous:String Functions, Up:String Functions
More About \ and & with sub, gsub, and gensub

When using sub, gsub, or gensub, and trying to get literal backslashes and ampersands into the replacement text, you need to remember that there are several levels of escape processing going on.

First, there is the lexical level, which is when awk reads your program and builds an internal copy of it that can be executed. Then there is the runtime level, which is when awk actually scans the replacement string to determine what to generate.

At both levels, awk looks for a defined set of characters that can come after a backslash. At the lexical level, it looks for the escape sequences listed in Escape Sequences. Thus, for every \ that awk processes at the runtime level, type two backslashes at the lexical level. When a character that is not valid for an escape sequence follows the \, Unix awk and gawk both simply remove the initial \ and put the next character into the string. Thus, for example, "a\qb" is treated as "aqb".

At the runtime level, the various functions handle sequences of \ and & differently. The situation is (sadly) somewhat complex. Historically, the sub and gsub functions treated the two character sequence \& specially; this sequence was replaced in the generated text with a single &. Any other \ within the replacement string that did not precede an & was passed through unchanged. To illustrate with a table:

 You type         sub sees          sub generates
 --------         ----------          ---------------
     \&              &            the matched text
    \\&             \&            a literal &
   \\\&             \&            a literal &
  \\\\&            \\&            a literal \&
 \\\\\&            \\&            a literal \&
\\\\\\&           \\\&            a literal \\&
    \\q             \q            a literal \q

This table shows both the lexical-level processing, where an odd number of backslashes becomes an even number at the runtime level, as well as the runtime processing done by sub. (For the sake of simplicity, the rest of the following tables only show the case of even numbers of backslashes entered at the lexical level.)

The problem with the historical approach is that there is no way to get a literal \ followed by the matched text.

The 1992 POSIX standard attempted to fix this problem. The standard says that sub and gsub look for either a \ or an & after the \. If either one follows a \, that character is output literally. The interpretation of \ and & then becomes:

 You type         sub sees          sub generates
 --------         ----------          ---------------
      &              &            the matched text
    \\&             \&            a literal &
  \\\\&            \\&            a literal \, then the matched text
\\\\\\&           \\\&            a literal \&

This appears to solve the problem. Unfortunately, the phrasing of the standard is unusual. It says, in effect, that \ turns off the special meaning of any following character, but for anything other than \ and &, such special meaning is undefined. This wording leads to two problems:

  • Backslashes must now be doubled in the replacement string, breaking historical awk programs.
  • To make sure that an awk program is portable, every character in the replacement string must be preceded with a backslash.31

The POSIX standard is under revision. Because of the problems just listed, proposed text for the revised standard reverts to rules that correspond more closely to the original existing practice. The proposed rules have special cases that make it possible to produce a \ preceding the matched text:

In a nutshell, at the runtime level, there are now three special sequences of characters (\\\&, \\& and \&) whereas historically there was only one. However, as in the historical case, any \ that is not part of one of these three sequences is not special and appears in the output literally.

gawk 3.0 and 3.1 follow these proposed POSIX rules for sub and gsub. Whether these proposed rules will actually become codified into the standard is unknown at this point. Subsequent gawk releases will track the standard and implement whatever the final version specifies; this Web page will be updated as well.32

The rules for gensub are considerably simpler. At the runtime level, whenever gawk sees a \, if the following character is a digit, then the text that matched the corresponding parenthesized subexpression is placed in the generated output. Otherwise, no matter what character follows the \, it appears in the generated text and the \ does not:

  You type          gensub sees         gensub generates
  --------          -------------         ------------------
      &                    &            the matched text
    \\&                   \&            a literal &
   \\\\                   \\            a literal \
  \\\\&                  \\&            a literal \, then the matched text
\\\\\\&                 \\\&            a literal \&
    \\q                   \q            a literal q

Because of the complexity of the lexical and runtime level processing and the special cases for sub and gsub, we recommend the use of gawk and gensub when you have to do substitutions.

Advanced Notes: Matching the Null String

In awk, the * operator can match the null string. This is particularly important for the sub, gsub, and gensub functions. For example:

$ echo abc | awk '{ gsub(/m*/, "X"); print }'
-| XaXbXcX

Although this makes a certain amount of sense, it can be surprising.

Node:I/O Functions, Next:Time Functions, Previous:String Functions, Up:Built-in

Input/Output Functions

The following functions relate to input/output (I/O). Optional parameters are enclosed in square brackets ([ ]):

close(filename [, how])
Close the file filename for input or output. Alternatively, the argument may be a shell command that was used for creating a coprocess, or for redirecting to or from a pipe; then the coprocess or pipe is closed. See Closing Input and Output Redirections, for more information.

When closing a coprocess, it is occasionally useful to first close one end of the two-way pipe and then to close the other. This is done by providing a second argument to close. This second argument should be one of the two string values "to" or "from", indicating which end of the pipe to close. Case in the string does not matter. See Two-Way Communications with Another Process, which discusses this feature in more detail and gives an example.

fflush([filename])
Flush any buffered output associated with filename, which is either a file opened for writing or a shell command for redirecting output to a pipe or coprocess.

Many utility programs buffer their output; i.e., they save information to write to a disk file or terminal in memory until there is enough for it to be worthwhile to send the data to the output device. This is often more efficient than writing every little bit of information as soon as it is ready. However, sometimes it is necessary to force a program to flush its buffers; that is, write the information to its destination, even if a buffer is not full. This is the purpose of the fflush function--gawk also buffers its output and the fflush function forces gawk to flush its buffers.

fflush was added to the Bell Laboratories research version of awk in 1994; it is not part of the POSIX standard and is not available if --posix has been specified on the command line (see Command-Line Options).

gawk extends the fflush function in two ways. The first is to allow no argument at all. In this case, the buffer for the standard output is flushed. The second is to allow the null string ("") as the argument. In this case, the buffers for all open output files and pipes are flushed.

fflush returns zero if the buffer is successfully flushed; otherwise, it returns -1. In the case where all buffers are flushed, the return value is zero only if all buffers were flushed successfully. Otherwise, it is -1, and gawk warns about the problem filename.

gawk also issues a warning message if you attempt to flush a file or pipe that was opened for reading (such as with getline), or if filename is not an open file, pipe, or coprocess. In such a case, fflush returns -1, as well.

system(command)
Executes operating-system commands and then returns to the awk program. The system function executes the command given by the string command. It returns the status returned by the command that was executed as its value.

For example, if the following fragment of code is put in your awk program:

END {
     system("date | mail -s 'awk run done' root")
}

the system administrator is sent mail when the awk program finishes processing input and begins its end-of-input processing.

Note that redirecting print or printf into a pipe is often enough to accomplish your task. If you need to run many commands, it is more efficient to simply print them down a pipeline to the shell:

while (more stuff to do)
    print command | "/bin/sh"
close("/bin/sh")

However, if your awk program is interactive, system is useful for cranking up large self-contained programs, such as a shell or an editor. Some operating systems cannot implement the system function. system causes a fatal error if it is not supported.

Advanced Notes: Interactive Versus Noninteractive Buffering

As a side point, buffering issues can be even more confusing, depending upon whether your program is interactive, i.e., communicating with a user sitting at a keyboard.33

Interactive programs generally line buffer their output; i.e., they write out every line. Noninteractive programs wait until they have a full buffer, which may be many lines of output. Here is an example of the difference:

$ awk '{ print $1 + $2 }'
1 1
-| 2
2 3
-| 5
Ctrl-d

Each line of output is printed immediately. Compare that behavior with this example:

$ awk '{ print $1 + $2 }' | cat
1 1
2 3
Ctrl-d
-| 2
-| 5

Here, no output is printed until after the Ctrl-d is typed, because it is all buffered and sent down the pipe to cat in one shot.

Advanced Notes: Controlling Output Buffering with system

The fflush function provides explicit control over output buffering for individual files and pipes. However, its use is not portable to many other awk implementations. An alternative method to flush output buffers is to call system with a null string as its argument:

system("")   # flush output

gawk treats this use of the system function as a special case and is smart enough not to run a shell (or other command interpreter) with the empty command. Therefore, with gawk, this idiom is not only useful, it is also efficient. While this method should work with other awk implementations, it does not necessarily avoid starting an unnecessary shell. (Other implementations may only flush the buffer associated with the standard output and not necessarily all buffered output.)

If you think about what a programmer expects, it makes sense that system should flush any pending output. The following program:

BEGIN {
     print "first print"
     system("echo system echo")
     print "second print"
}

must print:

first print
system echo
second print

and not:

system echo
first print
second print

If awk did not flush its buffers before calling system, you would see the latter (undesirable) output.

Node:Time Functions, Next:Bitwise Functions, Previous:I/O Functions, Up:Built-in

Using gawk's Timestamp Functions

awk programs are commonly used to process log files containing timestamp information, indicating when a particular log record was written. Many programs log their timestamp in the form returned by the time system call, which is the number of seconds since a particular epoch. On POSIX-compliant systems, it is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds.34 All known POSIX-compliant systems support timestamps from 0 through 2^31 - 1, which is sufficient to represent times through 2038-01-19 03:14:07 UTC. Many systems support a wider range of timestamps, including negative timestamps that represent times before the epoch.

In order to make it easier to process such log files and to produce useful reports, gawk provides the following functions for working with timestamps. They are gawk extensions; they are not specified in the POSIX standard, nor are they in any other known version of awk.35 Optional parameters are enclosed in square brackets ([ ]):

systime()
This function returns the current time as the number of seconds since the system epoch. On POSIX systems, this is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds. It may be a different number on other systems.
mktime(datespec)
This function turns datespec into a timestamp in the same form as is returned by systime. It is similar to the function of the same name in ISO C. The argument, datespec, is a string of the form "YYYY MM DD HH MM SS [DST]". The string consists of six or seven numbers representing, respectively, the full year including century, the month from 1 to 12, the day of the month from 1 to 31, the hour of the day from 0 to 23, the minute from 0 to 59, the second from 0 to 60,36 and an optional daylight-savings flag.

The values of these numbers need not be within the ranges specified; for example, an hour of -1 means 1 hour before midnight. The origin-zero Gregorian calendar is assumed, with year 0 preceding year 1 and year -1 preceding year 0. The time is assumed to be in the local timezone. If the daylight-savings flag is positive, the time is assumed to be daylight savings time; if zero, the time is assumed to be standard time; and if negative (the default), mktime attempts to determine whether daylight savings time is in effect for the specified time.

If datespec does not contain enough elements or if the resulting time is out of range, mktime returns -1.

strftime([format [, timestamp]])
This function returns a string. It is similar to the function of the same name in ISO C. The time specified by timestamp is used to produce a string, based on the contents of the format string. The timestamp is in the same format as the value returned by the systime function. If no timestamp argument is supplied, gawk uses the current time of day as the timestamp. If no format argument is supplied, strftime uses "%a %b %d %H:%M:%S %Z %Y". This format string produces output that is (almost) equivalent to that of the date utility. (Versions of gawk prior to 3.0 require the format argument.)

The systime function allows you to compare a timestamp from a log file with the current time of day. In particular, it is easy to determine how long ago a particular record was logged. It also allows you to produce log records using the "seconds since the epoch" format.

The mktime function allows you to convert a textual representation of a date and time into a timestamp. This makes it easy to do before/after comparisons of dates and times, particularly when dealing with date and time data coming from an external source, such as a log file.

The strftime function allows you to easily turn a timestamp into human-readable information. It is similar in nature to the sprintf function (see String Manipulation Functions), in that it copies nonformat specification characters verbatim to the returned string, while substituting date and time values for format specifications in the format string.

strftime is guaranteed by the 1999 ISO C standard37 to support the following date format specifications:

%a
The locale's abbreviated weekday name.
%A
The locale's full weekday name.
%b
The locale's abbreviated month name.
%B
The locale's full month name.
%c
The locale's "appropriate" date and time representation. (This is %A %B %d %T %Y in the "C" locale.)
%C
The century. This is the year divided by 100 and truncated to the next lower integer.
%d
The day of the month as a decimal number (01-31).
%D
Equivalent to specifying %m/%d/%y.
%e
The day of the month, padded with a space if it is only one digit.
%F
Equivalent to specifying %Y-%m-%d. This is the ISO 8601 date format.
%g
The year modulo 100 of the ISO week number, as a decimal number (00-99). For example, January 1, 1993 is in week 53 of 1992. Thus, the year of its ISO week number is 1992, even though its year is 1993. Similarly, December 31, 1973 is in week 1 of 1974. Thus, the year of its ISO week number is 1974, even though its year is 1973.
%G
The full year of the ISO week number, as a decimal number.
%h
Equivalent to %b.
%H
The hour (24-hour clock) as a decimal number (00-23).
%I
The hour (12-hour clock) as a decimal number (01-12).
%j
The day of the year as a decimal number (001-366).
%m
The month as a decimal number (01-12).
%M
The minute as a decimal number (00-59).
%n
A newline character (ASCII LF).
%p
The locale's equivalent of the AM/PM designations associated with a 12-hour clock.
%r
The locale's 12-hour clock time. (This is %I:%M:%S %p in the "C" locale.)
%R
Equivalent to specifying %H:%M.
%S
The second as a decimal number (00-60).
%t
A TAB character.
%T
Equivalent to specifying %H:%M:%S.
%u
The weekday as a decimal number (1-7). Monday is day one.
%U
The week number of the year (the first Sunday as the first day of week one) as a decimal number (00-53).
%V
The week number of the year (the first Monday as the first day of week one) as a decimal number (01-53). The method for determining the week number is as specified by ISO 8601. (To wit: if the week containing January 1 has four or more days in the new year, then it is week one; otherwise it is week 53 of the previous year and the next week is week one.)
%w
The weekday as a decimal number (0-6). Sunday is day zero.
%W
The week number of the year (the first Monday as the first day of week one) as a decimal number (00-53).
%x
The locale's "appropriate" date representation. (This is %A %B %d %Y in the "C" locale.)
%X
The locale's "appropriate" time representation. (This is %T in the "C" locale.)
%y
The year modulo 100 as a decimal number (00-99).
%Y
The full year as a decimal number (e.g., 1995).
%z
The timezone offset in a +HHMM format (e.g., the format necessary to produce RFC 822/RFC 1036 date headers).
%Z
The time zone name or abbreviation; no characters if no time zone is determinable.
%Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH
%OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy
"Alternate representations" for the specifications that use only the second letter (%c, %C, and so on).38 (These facilitate compliance with the POSIX date utility.)
%%
A literal %.

If a conversion specifier is not one of the above, the behavior is undefined.39

Informally, a locale is the geographic place in which a program is meant to run. For example, a common way to abbreviate the date September 4, 1991 in the United States is "9/4/91." In many countries in Europe, however, it is abbreviated "4.9.91." Thus, the %x specification in a "US" locale might produce 9/4/91, while in a "EUROPE" locale, it might produce 4.9.91. The ISO C standard defines a default "C" locale, which is an environment that is typical of what most C programmers are used to.

A public-domain C version of strftime is supplied with gawk for systems that are not yet fully standards-compliant. It supports all of the just listed format specifications. If that version is used to compile gawk (see Installing gawk), then the following additional format specifications are available:

%k
The hour (24-hour clock) as a decimal number (0-23). Single-digit numbers are padded with a space.
%l
The hour (12-hour clock) as a decimal number (1-12). Single-digit numbers are padded with a space.
%N
The "Emperor/Era" name. Equivalent to %C.
%o
The "Emperor/Era" year. Equivalent to %y.
%s
The time as a decimal timestamp in seconds since the epoch.
%v
The date in VMS format (e.g., 20-JUN-1991).

Additionally, the alternate representations are recognized but their normal representations are used.

This example is an awk implementation of the POSIX date utility. Normally, the date utility prints the current date and time of day in a well-known format. However, if you provide an argument to it that begins with a +, date copies nonformat specifier characters to the standard output and interprets the current time according to the format specifiers in the string. For example:

$ date '+Today is %A, %B %d, %Y.'
-| Today is Thursday, September 14, 2000.

Here is the gawk version of the date utility. It has a shell "wrapper" to handle the -u option, which requires that date run as if the time zone is set to UTC:

#! /bin/sh
#
# date --- approximate the P1003.2 'date' command

case $1 in
-u)  TZ=UTC0     # use UTC
     export TZ
     shift ;;
esac

gawk 'BEGIN  {
    format = "%a %b %d %H:%M:%S %Z %Y"
    exitval = 0

    if (ARGC > 2)
        exitval = 1
    else if (ARGC == 2) {
        format = ARGV[1]
        if (format ~ /^\+/)
            format = substr(format, 2)   # remove leading +
    }
    print strftime(format)
    exit exitval
}' "$@"

Node:Bitwise Functions, Next:I18N Functions, Previous:Time Functions, Up:Built-in

Bit-Manipulation Functions of gawk

I can explain it for you, but I can't understand it for you.
Anonymous

Many languages provide the ability to perform bitwise operations on two integer numbers. In other words, the operation is performed on each successive pair of bits in the operands. Three common operations are bitwise AND, OR, and XOR. The operations are described by the following table:

                Bit Operator
          |  AND  |   OR  |  XOR
          |---+---+---+---+---+---
Operands  | 0 | 1 | 0 | 1 | 0 | 1
----------+---+---+---+---+---+---
    0     | 0   0 | 0   1 | 0   1
    1     | 0   1 | 1   1 | 1   0

As you can see, the result of an AND operation is 1 only when both bits are 1. The result of an OR operation is 1 if either bit is 1. The result of an XOR operation is 1 if either bit is 1, but not both. The next operation is the complement; the complement of 1 is 0 and the complement of 0 is 1. Thus, this operation "flips" all the bits of a given value.

Finally, two other common operations are to shift the bits left or right. For example, if you have a bit string 10111001 and you shift it right by three bits, you end up with 00010111.40 If you start over again with 10111001 and shift it left by three bits, you end up with 11001000. gawk provides built-in functions that implement the bitwise operations just described. They are:

and(v1, v2) | Returns the bitwise AND of the values provided by v1 and v2.
or(v1, v2) | Returns the bitwise OR of the values provided by v1 and v2.
xor(v1, v2) | Returns the bitwise XOR of the values provided by v1 and v2.
compl(val) | Returns the bitwise complement of val.
lshift(val, count) | Returns the value of val, shifted left by count bits.
rshift(val, count) | Returns the value of val, shifted right by count bits.

For all of these functions, first the double-precision floating-point value is converted to a C unsigned long, then the bitwise operation is performed and then the result is converted back into a C double. (If you don't understand this paragraph, don't worry about it.)

Here is a user-defined function (see User-Defined Functions) that illustrates the use of these functions:

# bits2str --- turn a byte into readable 1's and 0's

function bits2str(bits,        data, mask)
{
    if (bits == 0)
        return "0"

    mask = 1
    for (; bits != 0; bits = rshift(bits, 1))
        data = (and(bits, mask) ? "1" : "0") data

    while ((length(data) % 8) != 0)
        data = "0" data

    return data
}

BEGIN {
    printf "123 = %s\n", bits2str(123)
    printf "0123 = %s\n", bits2str(0123)
    printf "0x99 = %s\n", bits2str(0x99)
    comp = compl(0x99)
    printf "compl(0x99) = %#x = %s\n", comp, bits2str(comp)
    shift = lshift(0x99, 2)
    printf "lshift(0x99, 2) = %#x = %s\n", shift, bits2str(shift)
    shift = rshift(0x99, 2)
    printf "rshift(0x99, 2) = %#x = %s\n", shift, bits2str(shift)
}

This program produces the following output when run:

$ gawk -f testbits.awk
-| 123 = 01111011
-| 0123 = 01010011
-| 0x99 = 10011001
-| compl(0x99) = 0xffffff66 = 11111111111111111111111101100110
-| lshift(0x99, 2) = 0x264 = 0000001001100100
-| rshift(0x99, 2) = 0x26 = 00100110

The bits2str function turns a binary number into a string. The number 1 represents a binary value where the rightmost bit is set to 1. Using this mask, the function repeatedly checks the rightmost bit. ANDing the mask with the value indicates whether the rightmost bit is 1 or not. If so, a "1" is concatenated onto the front of the string. Otherwise, a "0" is added. The value is then shifted right by one bit and the loop continues until there are no more 1 bits.

If the initial value is zero it returns a simple "0". Otherwise, at the end, it pads the value with zeros to represent multiples of 8-bit quantities. This is typical in modern computers.

The main code in the BEGIN rule shows the difference between the decimal and octal values for the same numbers (see Octal and Hexadecimal Numbers), and then demonstrates the results of the compl, lshift, and rshift functions.

Node:I18N Functions, Previous:Bitwise Functions, Up:Built-in

Using gawk's String-Translation Functions

gawk provides facilities for internationalizing awk programs. These include the functions described in the following list. The descriptions here are purposely brief. See Internationalization with gawk, for the full story. Optional parameters are enclosed in square brackets ([ ]):

dcgettext(string [, domain [, category]])
This function returns the translation of string in text domain domain for locale category category. The default value for domain is the current value of TEXTDOMAIN. The default value for category is "LC_MESSAGES".
dcngettext(string1, string2, number [, domain [, category]])
This function returns the plural form used for number of the translation of string1 and string2 in text domain domain for locale category category. string1 is the English singular variant of a message, and string2 the English plural variant of the same message. The default value for domain is the current value of TEXTDOMAIN. The default value for category is "LC_MESSAGES".
bindtextdomain(directory [, domain])
This function allows you to specify the directory in which gawk will look for message translation files, in case they will not or cannot be placed in the "standard" locations (e.g., during testing). It returns the directory in which domain is "bound."

The default domain is the value of TEXTDOMAIN. If directory is the null string (""), then bindtextdomain returns the current binding for the given domain.

Node:User-defined, Previous:Built-in, Up:Functions

User-Defined Functions

Complicated awk programs can often be simplified by defining your own functions. User-defined functions can be called just like built-in ones (see Function Calls), but it is up to you to define them, i.e., to tell awk what they should do.

  • Definition Syntax: How to write definitions and what they mean.
  • Function Example: An example function definition and what it does.
  • Function Caveats: Things to watch out for.
  • Return Statement: Specifying the value a function returns.
  • Dynamic Typing: How variable types can change at runtime.

Node:Definition Syntax, Next:Function Example, Previous:User-defined, Up:User-defined

Function Definition Syntax

Definitions of functions can appear anywhere between the rules of an awk program. Thus, the general form of an awk program is extended to include sequences of rules and user-defined function definitions. There is no need to put the definition of a function before all uses of the function. This is because awk reads the entire program before starting to execute any of it.

The definition of a function named name looks like this:

function name(parameter-list)
{
     body-of-function
}

name is the name of the function to define. A valid function name is like a valid variable name: a sequence of letters, digits, and underscores that doesn't start with a digit. Within a single awk program, any particular name can only be used as a variable, array, or function.

parameter-list is a list of the function's arguments and local variable names, separated by commas. When the function is called, the argument names are used to hold the argument values given in the call. The local variables are initialized to the empty string. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself.

The body-of-function consists of awk statements. It is the most important part of the definition, because it says what the function should actually do. The argument names exist to give the body a way to talk about the arguments; local variables exist to give the body places to keep temporary values.

Argument names are not distinguished syntactically from local variable names. Instead, the number of arguments supplied when the function is called determines how many argument variables there are. Thus, if three argument values are given, the first three names in parameter-list are arguments and the rest are local variables.

It follows that if the number of arguments is not the same in all calls to the function, some of the names in parameter-list may be arguments on some occasions and local variables on others. Another way to think of this is that omitted arguments default to the null string.

Usually when you write a function, you know how many names you intend to use for arguments and how many you intend to use as local variables. It is conventional to place some extra space between the arguments and the local variables, in order to document how your function is supposed to be used.

During execution of the function body, the arguments and local variable values hide, or shadow, any variables of the same names used in the rest of the program. The shadowed variables are not accessible in the function definition, because there is no way to name them while their names have been taken away for the local variables. All other variables used in the awk program can be referenced or set normally in the function's body.

The arguments and local variables last only as long as the function body is executing. Once the body finishes, you can once again access the variables that were shadowed while the function was running.

The function body can contain expressions that call functions. They can even call this function, either directly or by way of another function. When this happens, we say the function is recursive. The act of a function calling itself is called recursion.

In many awk implementations, including gawk, the keyword function may be abbreviated func. However, POSIX only specifies the use of the keyword function. This actually has some practical implications. If gawk is in POSIX-compatibility mode (see Command-Line Options), then the following statement does not define a function:

func foo() { a = sqrt($1) ; print a }

Instead it defines a rule that, for each record, concatenates the value of the variable func with the return value of the function foo. If the resulting string is non-null, the action is executed. This is probably not what is desired. (awk accepts this input as syntactically valid, because functions may be used before they are defined in awk programs.)

To ensure that your awk programs are portable, always use the keyword function when defining a function.

Node:Function Example, Next:Function Caveats, Previous:Definition Syntax, Up:User-defined

Function Definition Examples

Here is an example of a user-defined function, called myprint, that takes a number and prints it in a specific format:

function myprint(num)
{
     printf "%6.3g\n", num
}

To illustrate, here is an awk rule that uses our myprint function:

$3 > 0     { myprint($3) }

This program prints, in our special format, all the third fields that contain a positive number in our input. Therefore, when given the following:

 1.2   3.4    5.6   7.8
 9.10 11.12 -13.14 15.16
17.18 19.20  21.22 23.24

this program, using our function to format the results, prints:

   5.6
  21.2

This function deletes all the elements in an array:

function delarray(a,    i)
{
    for (i in a)
       delete a[i]
}

When working with arrays, it is often necessary to delete all the elements in an array and start over with a new list of elements (see The delete Statement). Instead of having to repeat this loop everywhere that you need to clear out an array, your program can just call delarray. (This guarantees portability. The use of delete array to delete the contents of an entire array is a nonstandard extension.)

The following is an example of a recursive function. It takes a string as an input parameter and returns the string in backwards order. Recursive functions must always have a test that stops the recursion. In this case, the recursion terminates when the starting position is zero, i.e., when there are no more characters left in the string.

function rev(str, start)
{
    if (start == 0)
        return ""

    return (substr(str, start, 1) rev(str, start - 1))
}

If this function is in a file named rev.awk, it can be tested this way:

$ echo "Don't Panic!" |
> gawk --source '{ print rev($0, length($0)) }' -f rev.awk
-| !cinaP t'noD

The C ctime function takes a timestamp and returns it in a string, formatted in a well-known fashion. The following example uses the built-in strftime function (see Using gawk's Timestamp Functions) to create an awk version of ctime:

# ctime.awk
#
# awk version of C ctime(3) function

function ctime(ts,    format)
{
    format = "%a %b %d %H:%M:%S %Z %Y"
    if (ts == 0)
        ts = systime()       # use current time as default
    return strftime(format, ts)
}

Node:Function Caveats, Next:Return Statement, Previous:Function Example, Up:User-defined

Calling User-Defined Functions

Calling a function means causing the function to run and do its job. A function call is an expression and its value is the value returned by the function.

A function call consists of the function name followed by the arguments in parentheses. awk expressions are what you write in the call for the arguments. Each time the call is executed, these expressions are evaluated, and the values are the actual arguments. For example, here is a call to foo with three arguments (the first being a string concatenation):

foo(x y, "lose", 4 * z)

Caution: Whitespace characters (spaces and tabs) are not allowed between the function name and the open-parenthesis of the argument list. If you write whitespace by mistake, awk might think that you mean to concatenate a variable with an expression in parentheses. However, it notices that you used a function name and not a variable name, and reports an error.

When a function is called, it is given a copy of the values of its arguments. This is known as call by value. The caller may use a variable as the expression for the argument, but the called function does not know this--it only knows what value the argument had. For example, if you write the following code:

foo = "bar"
z = myfunc(foo)

then you should not think of the argument to myfunc as being "the variable foo." Instead, think of the argument as the string value "bar". If the function myfunc alters the values of its local variables, this has no effect on any other variables. Thus, if myfunc does this:

function myfunc(str)
{
  print str
  str = "zzz"
  print str
}

to change its first argument variable str, it does not change the value of foo in the caller. The role of foo in calling myfunc ended when its value ("bar") was computed. If str also exists outside of myfunc, the function body cannot alter this outer value, because it is shadowed during the execution of myfunc and cannot be seen or changed from there.

However, when arrays are the parameters to functions, they are not copied. Instead, the array itself is made available for direct manipulation by the function. This is usually called call by reference. Changes made to an array parameter inside the body of a function are visible outside that function.

Note: Changing an array parameter inside a function can be very dangerous if you do not watch what you are doing. For example:

function changeit(array, ind, nvalue)
{
     array[ind] = nvalue
}

BEGIN {
    a[1] = 1; a[2] = 2; a[3] = 3
    changeit(a, 2, "two")
    printf "a[1] = %s, a[2] = %s, a[3] = %s\n",
            a[1], a[2], a[3]
}

prints a[1] = 1, a[2] = two, a[3] = 3, because changeit stores "two" in the second element of a.

Some awk implementations allow you to call a function that has not been defined. They only report a problem at runtime when the program actually tries to call the function. For example:

BEGIN {
    if (0)
        foo()
    else
        bar()
}
function bar() { ... }
# note that `foo' is not defined

Because the if statement will never be true, it is not really a problem that foo has not been defined. Usually, though, it is a problem if a program calls an undefined function.

If --lint is specified (see Command-Line Options), gawk reports calls to undefined functions.

Some awk implementations generate a runtime error if you use the next statement (see The next Statement) inside a user-defined function. gawk does not have this limitation.

Node:Return Statement, Next:Dynamic Typing, Previous:Function Caveats, Up:User-defined

The return Statement

The body of a user-defined function can contain a return statement. This statement returns control to the calling part of the awk program. It can also be used to return a value for use in the rest of the awk program. It looks like this:

return [expression]

The expression part is optional. If it is omitted, then the returned value is undefined, and therefore, unpredictable.

A return statement with no value expression is assumed at the end of every function definition. So if control reaches the end of the function body, then the function returns an unpredictable value. awk does not warn you if you use the return value of such a function.

Sometimes, you want to write a function for what it does, not for what it returns. Such a function corresponds to a void function in C or to a procedure in Pascal. Thus, it may be appropriate to not return any value; simply bear in mind that if you use the return value of such a function, you do so at your own risk.

The following is an example of a user-defined function that returns a value for the largest number among the elements of an array:

function maxelt(vec,   i, ret)
{
     for (i in vec) {
          if (ret == "" || vec[i] > ret)
               ret = vec[i]
     }
     return ret
}

You call maxelt with one argument, which is an array name. The local variables i and ret are not intended to be arguments; while there is nothing to stop you from passing more than one argument to maxelt, the results would be strange. The extra space before i in the function parameter list indicates that i and ret are not supposed to be arguments. You should follow this convention when defining functions.

The following program uses the maxelt function. It loads an array, calls maxelt, and then reports the maximum number in that array:

function maxelt(vec,   i, ret)
{
     for (i in vec) {
          if (ret == "" || vec[i] > ret)
               ret = vec[i]
     }
     return ret
}

# Load all fields of each record into nums.
{
     for(i = 1; i <= NF; i++)
          nums[NR, i] = $i
}

END {
     print maxelt(nums)
}

Given the following input:

 1 5 23 8 16
44 3 5 2 8 26
256 291 1396 2962 100
-6 467 998 1101
99385 11 0 225

the program reports (predictably) that 99385 is the largest number in the array.

Node:Dynamic Typing, Previous:Return Statement, Up:User-defined

Functions and Their Effects on Variable Typing

awk is a very fluid language. It is possible that awk can't tell if an identifier represents a regular variable or an array until runtime. Here is an annotated sample program:

function foo(a)
{
    a[1] = 1   # parameter is an array
}

BEGIN {
    b = 1
    foo(b)  # invalid: fatal type mismatch

    foo(x)  # x uninitialized, becomes an array dynamically
    x = 1   # now not allowed, runtime error
}

Usually, such things aren't a big issue, but it's worth being aware of them.

Node:Internationalization, Next:Advanced Features, Previous:Functions, Up:Top

Internationalization with gawk

Once upon a time, computer makers wrote software that worked only in English. Eventually, hardware and software vendors noticed that if their systems worked in the native languages of non-English-speaking countries, they were able to sell more systems. As a result, internationalization and localization of programs and software systems became a common practice.

Until recently, the ability to provide internationalization was largely restricted to programs written in C and C++. This chapter describes the underlying library gawk uses for internationalization, as well as how gawk makes internationalization features available at the awk program level. Having internationalization available at the awk level gives software developers additional flexibility--they are no longer required to write in C when internationalization is a requirement.

  • I18N and L10N: Internationalization and Localization.
  • Explaining gettext: How GNU gettext works.
  • Programmer i18n: Features for the programmer.
  • Translator i18n: Features for the translator.
  • I18N Example: A simple i18n example.
  • Gawk I18N: gawk is also internationalized.

Node:I18N and L10N, Next:Explaining gettext, Previous:Internationalization, Up:Internationalization

Internationalization and Localization

Internationalization means writing (or modifying) a program once, in such a way that it can use multiple languages without requiring further source-code changes. Localization means providing the data necessary for an internationalized program to work in a particular language. Most typically, these terms refer to features such as the language used for printing error messages, the language used to read responses, and information related to how numerical and monetary values are printed and read.

Node:Explaining gettext, Next:Programmer i18n, Previous:I18N and L10N, Up:Internationalization

GNU gettext

The facilities in GNU gettext focus on messages; strings printed by a program, either directly or via formatting with printf or sprintf.41

When using GNU gettext, each application has its own text domain. This is a unique name, such as kpilot or gawk, that identifies the application. A complete application may have multiple components--programs written in C or C++, as well as scripts written in sh or awk. All of the components use the same text domain.

To make the discussion concrete, assume we're writing an application named guide. Internationalization consists of the following steps, in this order:

  1. The programmer goes through the source for all of guide's components and marks each string that is a candidate for translation. For example, "`-F': option required" is a good candidate for translation. A table with strings of option names is not (e.g., gawk's --profile option should remain the same, no matter what the local language).
  2. The programmer indicates the application's text domain ("guide") to the gettext library, by calling the textdomain function.
  3. Messages from the application are extracted from the source code and collected into a portable object file (guide.po), which lists the strings and their translations. The translations are initially empty. The original (usually English) messages serve as the key for lookup of the translations.
  4. For each language with a translator, guide.po is copied and translations are created and shipped with the application.
  5. Each language's .po file is converted into a binary message object (.mo) file. A message object file contains the original messages and their translations in a binary format that allows fast lookup of translations at runtime.
  6. When guide is built and installed, the binary translation files are installed in a standard place.
  7. For testing and development, it is possible to tell gettext to use .mo files in a different directory than the standard one by using the bindtextdomain function.
  8. At runtime, guide looks up each string via a call to gettext. The returned string is the translated string if available, or the original string if not.
  9. If necessary, it is possible to access messages from a different text domain than the one belonging to the application, without having to switch the application's default text domain back and forth.

In C (or C++), the string marking and dynamic translation lookup are accomplished by wrapping each string in a call to gettext:

printf(gettext("Don't Panic!\n"));

The tools that extract messages from source code pull out all strings enclosed in calls to gettext.

The GNU gettext developers, recognizing that typing gettext over and over again is both painful and ugly to look at, use the macro _ (an underscore) to make things easier:

/* In the standard header file: */
#define _(str) gettext(str)

/* In the program text: */
printf(_("Don't Panic!\n"));

This reduces the typing overhead to just three extra characters per string and is considerably easier to read as well. There are locale categories for different types of locale-related information. The defined locale categories that gettext knows about are:

LC_MESSAGES
Text messages. This is the default category for gettext operations, but it is possible to supply a different one explicitly, if necessary. (It is almost never necessary to supply a different category.)
LC_COLLATE
Text-collation information; i.e., how different characters and/or groups of characters sort in a given language.
LC_CTYPE
Character-type information (alphabetic, digit, upper- or lowercase, and so on). This information is accessed via the POSIX character classes in regular expressions, such as /[[:alnum:]]/ (see Regular Expression Operators).
LC_MONETARY
Monetary information, such as the currency symbol, and whether the symbol goes before or after a number.
LC_NUMERIC
Numeric information, such as which characters to use for the decimal point and the thousands separator.42
LC_RESPONSE
Response information, such as how "yes" and "no" appear in the local language, and possibly other information as well.
LC_TIME
Time- and date-related information, such as 12- or 24-hour clock, month printed before or after day in a date, local month abbreviations, and so on.
LC_ALL
All of the above. (Not too useful in the context of gettext.)

Node:Programmer i18n, Next:Translator i18n, Previous:Explaining gettext, Up:Internationalization

Internationalizing awk Programs

gawk provides the following variables and functions for internationalization:

TEXTDOMAIN
This variable indicates the application's text domain. For compatibility with GNU gettext, the default value is "messages".
_"your message here"
String constants marked with a leading underscore are candidates for translation at runtime. String constants without a leading underscore are not translated.
dcgettext(string [, domain [, category]])
This built-in function returns the translation of string in text domain domain for locale category category. The default value for domain is the current value of TEXTDOMAIN. The default value for category is "LC_MESSAGES".

If you supply a value for category, it must be a string equal to one of the known locale categories described in the previous section. You must also supply a text domain. Use TEXTDOMAIN if you want to use the current domain.

Caution: The order of arguments to the awk version of the dcgettext function is purposely different from the order for the C version. The awk version's order was chosen to be simple and to allow for reasonable awk-style default arguments.

dcngettext(string1, string2, number [, domain [, category]])
This built-in function returns the plural form used for number of the translation of string1 and string2 in text domain domain for locale category category. string1 is the English singular variant of a message, and string2 the English plural variant of the same message. The default value for domain is the current value of TEXTDOMAIN. The default value for category is "LC_MESSAGES".

The same remarks as for the dcgettext function apply.

bindtextdomain(directory [, domain])
This built-in function allows you to specify the directory in which gettext looks for .mo files, in case they will not or cannot be placed in the standard locations (e.g., during testing). It returns the directory in which domain is "bound."

The default domain is the value of TEXTDOMAIN. If directory is the null string (""), then bindtextdomain returns the current binding for the given domain.

To use these facilities in your awk program, follow the steps outlined in the previous section, like so:

  1. Set the variable TEXTDOMAIN to the text domain of your program. This is best done in a BEGIN rule (see The BEGIN and END Special Patterns), or it can also be done via the -v command-line option (see Command-Line Options):
    BEGIN {
    TEXTDOMAIN = "guide"
    ...
}
  2. Mark all translatable strings with a leading underscore (_) character. It must be adjacent to the opening quote of the string. For example:
    print _"hello, world"
x = _"you goofed"
printf(_"Number of users is %d\n", nusers)
  3. If you are creating strings dynamically, you can still translate them, using the dcgettext built-in function:
    message = nusers " users logged in"
message = dcgettext(message, "adminprog")
print message

    Here, the call to dcgettext supplies a different text domain ("adminprog") in which to find the message, but it uses the default "LC_MESSAGES" category.

  4. During development, you might want to put the .mo file in a private directory for testing. This is done with the bindtextdomain built-in function:
    BEGIN {
   TEXTDOMAIN = "guide"   # our text domain
   if (Testing) {
       # where to find our files
       bindtextdomain("testdir")
       # joe is in charge of adminprog
       bindtextdomain("../joe/testdir", "adminprog")
   }
   ...
}

See A Simple Internationalization Example, for an example program showing the steps to create and use translations from awk.

Node:Translator i18n, Next:I18N Example, Previous:Programmer i18n, Up:Internationalization

Translating awk Programs

Once a program's translatable strings have been marked, they must be extracted to create the initial .po file. As part of translation, it is often helpful to rearrange the order in which arguments to printf are output.

gawk's --gen-po command-line option extracts the messages and is discussed next. After that, printf's ability to rearrange the order for printf arguments at runtime is covered.

  • String Extraction: Extracting marked strings.
  • Printf Ordering: Rearranging printf arguments.
  • I18N Portability: awk-level portability issues.

Node:String Extraction, Next:Printf Ordering, Previous:Translator i18n, Up:Translator i18n

Extracting Marked Strings

Once your awk program is working, and all the strings have been marked and you've set (and perhaps bound) the text domain, it is time to produce translations. First, use the --gen-po command-line option to create the initial .po file:

$ gawk --gen-po -f guide.awk > guide.po

When run with --gen-po, gawk does not execute your program. Instead, it parses it as usual and prints all marked strings to standard output in the format of a GNU gettext Portable Object file. Also included in the output are any constant strings that appear as the first argument to dcgettext or as the first and second argument to dcngettext.43 See A Simple Internationalization Example, for the full list of steps to go through to create and test translations for guide.

Node:Printf Ordering, Next:I18N Portability, Previous:String Extraction, Up:Translator i18n

Rearranging printf Arguments

Format strings for printf and sprintf (see Using printf Statements for Fancier Printing) present a special problem for translation. Consider the following:44

printf(_"String `%s' has %d characters\n",
          string, length(string)))

A possible German translation for this might be:

"%d Zeichen lang ist die Zeichenkette `%s'\n"

The problem should be obvious: the order of the format specifications is different from the original! Even though gettext can return the translated string at runtime, it cannot change the argument order in the call to printf.

To solve this problem, printf format specificiers may have an additional optional element, which we call a positional specifier. For example:

"%2$d Zeichen lang ist die Zeichenkette `%1$s'\n"

Here, the positional specifier consists of an integer count, which indicates which argument to use, and a $. Counts are one-based, and the format string itself is not included. Thus, in the following example, string is the first argument and length(string) is the second:

$ gawk 'BEGIN {
>     string = "Dont Panic"
>     printf _"%2$d characters live in \"%1$s\"\n",
>                         string, length(string)
> }'
-| 10 characters live in "Dont Panic"

If present, positional specifiers come first in the format specification, before the flags, the field width, and/or the precision.

Positional specifiers can be used with the dynamic field width and precision capability:

$ gawk 'BEGIN {
>    printf("%*.*s\n", 10, 20, "hello")
>    printf("%3$*2$.*1$s\n", 20, 10, "hello")
> }'
-|      hello
-|      hello

Note: When using * with a positional specifier, the * comes first, then the integer position, and then the $. This is somewhat counterintutive.

gawk does not allow you to mix regular format specifiers and those with positional specifiers in the same string:

$ gawk 'BEGIN { printf _"%d %3$s\n", 1, 2, "hi" }'
error--> gawk: cmd. line:1: fatal: must use `count$' on all formats or none

Note: There are some pathological cases that gawk may fail to diagnose. In such cases, the output may not be what you expect. It's still a bad idea to try mixing them, even if gawk doesn't detect it.

Although positional specifiers can be used directly in awk programs, their primary purpose is to help in producing correct translations of format strings into languages different from the one in which the program is first written.

Node:I18N Portability, Previous:Printf Ordering, Up:Translator i18n

awk Portability Issues

gawk's internationalization features were purposely chosen to have as little impact as possible on the portability of awk programs that use them to other versions of awk. Consider this program:

BEGIN {
    TEXTDOMAIN = "guide"
    if (Test_Guide)   # set with -v
        bindtextdomain("/test/guide/messages")
    print _"don't panic!"
}

As written, it won't work on other versions of awk. However, it is actually almost portable, requiring very little change:

  • Assignments to TEXTDOMAIN won't have any effect, since TEXTDOMAIN is not special in other awk implementations.
  • Non-GNU versions of awk treat marked strings as the concatenation of a variable named _ with the string following it.45 Typically, the variable _ has the null string ("") as its value, leaving the original string constant as the result.
  • By defining "dummy" functions to replace dcgettext, dcngettext and bindtextdomain, the awk program can be made to run, but all the messages are output in the original language. For example:
    function bindtextdomain(dir, domain)
{
    return dir
}

function dcgettext(string, domain, category)
{
    return string
}

function dcngettext(string1, string2, number, domain, category)
{
    return (number == 1 ? string1 : string2)
}
  • The use of positional specifications in printf or sprintf is not portable. To support gettext at the C level, many systems' C versions of sprintf do support positional specifiers. But it works only if enough arguments are supplied in the function call. Many versions of awk pass printf formats and arguments unchanged to the underlying C library version of sprintf, but only one format and argument at a time. What happens if a positional specification is used is anybody's guess. However, since the positional specifications are primarily for use in translated format strings, and since non-GNU awks never retrieve the translated string, this should not be a problem in practice.

Node:I18N Example, Next:Gawk I18N, Previous:Translator i18n, Up:Internationalization

A Simple Internationalization Example

Now let's look at a step-by-step example of how to internationalize and localize a simple awk program, using guide.awk as our original source:

BEGIN {
    TEXTDOMAIN = "guide"
    bindtextdomain(".")  # for testing
    print _"Don't Panic"
    print _"The Answer Is", 42
    print "Pardon me, Zaphod who?"
}

Run gawk --gen-po to create the .po file:

$ gawk --gen-po -f guide.awk > guide.po

This produces:

#: guide.awk:4
msgid "Don't Panic"
msgstr ""

#: guide.awk:5
msgid "The Answer Is"
msgstr ""

This original portable object file is saved and reused for each language into which the application is translated. The msgid is the original string and the msgstr is the translation.

Note: Strings not marked with a leading underscore do not appear in the guide.po file.

Next, the messages must be translated. Here is a translation to a hypothetical dialect of English, called "Mellow":46

$ cp guide.po guide-mellow.po
Add translations to guide-mellow.po ...

Following are the translations:

#: guide.awk:4
msgid "Don't Panic"
msgstr "Hey man, relax!"

#: guide.awk:5
msgid "The Answer Is"
msgstr "Like, the scoop is"

The next step is to make the directory to hold the binary message object file and then to create the guide.mo file. The directory layout shown here is standard for GNU gettext on GNU/Linux systems. Other versions of gettext may use a different layout:

$ mkdir en_US en_US/LC_MESSAGES

The msgfmt utility does the conversion from human-readable .po file to machine-readable .mo file. By default, msgfmt creates a file named messages. This file must be renamed and placed in the proper directory so that gawk can find it:

$ msgfmt guide-mellow.po
$ mv messages en_US/LC_MESSAGES/guide.mo

Finally, we run the program to test it:

$ gawk -f guide.awk
-| Hey man, relax!
-| Like, the scoop is 42
-| Pardon me, Zaphod who?

If the three replacement functions for dcgettext, dcngettext and bindtextdomain (see awk Portability Issues) are in a file named libintl.awk, then we can run guide.awk unchanged as follows:

$ gawk --posix -f guide.awk -f libintl.awk
-| Don't Panic
-| The Answer Is 42
-| Pardon me, Zaphod who?

Node:Gawk I18N, Previous:I18N Example, Up:Internationalization

gawk Can Speak Your Language

As of version 3.1, gawk itself has been internationalized using the GNU gettext package. (GNU gettext is described in complete detail in GNU gettext tools.) As of this writing, the latest version of GNU gettext is version 0.11.1.

If a translation of gawk's messages exists, then gawk produces usage messages, warnings, and fatal errors in the local language.

On systems that do not use version 2 (or later) of the GNU C library, you should configure gawk with the --with-included-gettext option before compiling and installing it. See Additional Configuration Options, for more information.

Node:Advanced Features, Next:Invoking Gawk, Previous:Internationalization, Up:Top

Advanced Features of gawk

Write documentation as if whoever reads it is a violent psychopath who knows where you live.
Steve English, as quoted by Peter Langston

This chapter discusses advanced features in gawk. It's a bit of a "grab bag" of items that are otherwise unrelated to each other. First, a command-line option allows gawk to recognize nondecimal numbers in input data, not just in awk programs. Next, two-way I/O, discussed briefly in earlier parts of this Web page, is described in full detail, along with the basics of TCP/IP networking and BSD portal files. Finally, gawk can profile an awk program, making it possible to tune it for performance. Adding New Built-in Functions to gawk, discusses the ability to dynamically add new built-in functions to gawk. As this feature is still immature and likely to change, its description is relegated to an appendix.

  • Nondecimal Data: Allowing nondecimal input data.
  • Two-way I/O: Two-way communications with another process.
  • TCP/IP Networking: Using gawk for network programming.
  • Portal Files: Using gawk with BSD portals.
  • Profiling: Profiling your awk programs.

Node:Nondecimal Data, Next:Two-way I/O, Previous:Advanced Features, Up:Advanced Features

Allowing Nondecimal Input Data

If you run gawk with the --non-decimal-data option, you can have nondecimal constants in your input data:

$ echo 0123 123 0x123 |
> gawk --non-decimal-data '{ printf "%d, %d, %d\n",
>                                         $1, $2, $3 }'
-| 83, 123, 291

For this feature to work, write your program so that gawk treats your data as numeric:

$ echo 0123 123 0x123 | gawk '{ print $1, $2, $3 }'
-| 0123 123 0x123

The print statement treats its expressions as strings. Although the fields can act as numbers when necessary, they are still strings, so print does not try to treat them numerically. You may need to add zero to a field to force it to be treated as a number. For example:

$ echo 0123 123 0x123 | gawk --non-decimal-data '
> { print $1, $2, $3
>   print $1 + 0, $2 + 0, $3 + 0 }'
-| 0123 123 0x123
-| 83 123 291

Because it is common to have decimal data with leading zeros, and because using it could lead to surprising results, the default is to leave this facility disabled. If you want it, you must explicitly request it.

Caution: Use of this option is not recommended. It can break old programs very badly. Instead, use the strtonum function to convert your data (see Octal and Hexadecimal Numbers). This makes your programs easier to write and easier to read, and leads to less surprising results.

Node:Two-way I/O, Next:TCP/IP Networking, Previous:Nondecimal Data, Up:Advanced Features

Two-Way Communications with Another Process

From: brennan@whidbey.com (Mike Brennan)
Newsgroups: comp.lang.awk
Subject: Re: Learn the SECRET to Attract Women Easily
Date: 4 Aug 1997 17:34:46 GMT
Message-ID: <5s53rm$eca@news.whidbey.com>

On 3 Aug 1997 13:17:43 GMT, Want More Dates???
<tracy78@kilgrona.com> wrote:
>Learn the SECRET to Attract Women Easily
>
>The SCENT(tm)  Pheromone Sex Attractant For Men to Attract Women

The scent of awk programmers is a lot more attractive to women than
the scent of perl programmers.
--
Mike Brennan

It is often useful to be able to send data to a separate program for processing and then read the result. This can always be done with temporary files:

# write the data for processing
tempfile = ("/tmp/mydata." PROCINFO["pid"])
while (not done with data)
    print data | ("subprogram > " tempfile)
close("subprogram > " tempfile)

# read the results, remove tempfile when done
while ((getline newdata < tempfile) > 0)
    process newdata appropriately
close(tempfile)
system("rm " tempfile)

This works, but not elegantly.

Starting with version 3.1 of gawk, it is possible to open a two-way pipe to another process. The second process is termed a coprocess, since it runs in parallel with gawk. The two-way connection is created using the new |& operator (borrowed from the Korn shell, ksh):47

do {
    print data |& "subprogram"
    "subprogram" |& getline results
} while (data left to process)
close("subprogram")

The first time an I/O operation is executed using the |& operator, gawk creates a two-way pipeline to a child process that runs the other program. Output created with print or printf is written to the program's standard input, and output from the program's standard output can be read by the gawk program using getline. As is the case with processes started by |, the subprogram can be any program, or pipeline of programs, that can be started by the shell.

There are some cautionary items to be aware of:

  • As the code inside gawk currently stands, the coprocess's standard error goes to the same place that the parent gawk's standard error goes. It is not possible to read the child's standard error separately.

    </itemizedlist>

  • I/O buffering may be a problem. gawk automatically flushes all output down the pipe to the child process. However, if the coprocess does not flush its output, gawk may hang when doing a getline in order to read the coprocess's results. This could lead to a situation known as deadlock, where each process is waiting for the other one to do something.

It is possible to close just one end of the two-way pipe to a coprocess, by supplying a second argument to the close function of either "to" or "from" (see Closing Input and Output Redirections). These strings tell gawk to close the end of the pipe that sends data to the process or the end that reads from it, respectively.

This is particularly necessary in order to use the system sort utility as part of a coprocess; sort must read all of its input data before it can produce any output. The sort program does not receive an end-of-file indication until gawk closes the write end of the pipe.

When you have finished writing data to the sort utility, you can close the "to" end of the pipe, and then start reading sorted data via getline. For example:

BEGIN {
    command = "LC_ALL=C sort"
    n = split("abcdefghijklmnopqrstuvwxyz", a, "")

    for (i = n; i > 0; i--)
        print a[i] |& command
    close(command, "to")

    while ((command |& getline line) > 0)
        print "got", line
    close(command)
}

This program writes the letters of the alphabet in reverse order, one per line, down the two-way pipe to sort. It then closes the write end of the pipe, so that sort receives an end-of-file indication. This causes sort to sort the data and write the sorted data back to the gawk program. Once all of the data has been read, gawk terminates the coprocess and exits.

As a side note, the assignment LC_ALL=C in the sort command ensures traditional Unix (ASCII) sorting from sort.

Node:TCP/IP Networking, Next:Portal Files, Previous:Two-way I/O, Up:Advanced Features

Using gawk for Network Programming

EMISTERED: A host is a host from coast to coast,
and no-one can talk to host that's close,
unless the host that isn't close
is busy hung or dead.

In addition to being able to open a two-way pipeline to a coprocess on the same system (see Two-Way Communications with Another Process), it is possible to make a two-way connection to another process on another system across an IP networking connection.

You can think of this as just a very long two-way pipeline to a coprocess. The way gawk decides that you want to use TCP/IP networking is by recognizing special file names that begin with /inet/.

The full syntax of the special file name is /inet/protocol/local-port/remote-host/remote-port. The components are:

protocol
The protocol to use over IP. This must be either tcp, udp, or raw, for a TCP, UDP, or raw IP connection, respectively. The use of TCP is recommended for most applications.

Caution: The use of raw sockets is not currently supported in version 3.1 of gawk.

local-port
The local TCP or UDP port number to use. Use a port number of 0 when you want the system to pick a port. This is what you should do when writing a TCP or UDP client. You may also use a well-known service name, such as smtp or http, in which case gawk attempts to determine the predefined port number using the C getservbyname function.
remote-host
The IP address or fully-qualified domain name of the Internet host to which you want to connect.
remote-port
The TCP or UDP port number to use on the given remote-host. Again, use 0 if you don't care, or else a well-known service name.

Consider the following very simple example:

BEGIN {
  Service = "/inet/tcp/0/localhost/daytime"
  Service |& getline
  print $0
  close(Service)
}

This program reads the current date and time from the local system's TCP daytime server. It then prints the results and closes the connection.

Because this topic is extensive, the use of gawk for TCP/IP programming is documented separately. See TCP/IP Internetworking with gawk, which comes as part of the gawk distribution, for a much more complete introduction and discussion, as well as extensive examples.

Node:Portal Files, Next:Profiling, Previous:TCP/IP Networking, Up:Advanced Features

Using gawk with BSD Portals

Similar to the /inet special files, if gawk is configured with the --enable-portals option (see Compiling gawk for Unix), then gawk treats files whose pathnames begin with /p as 4.4 BSD-style portals.

When used with the |& operator, gawk opens the file for two-way communications. The operating system's portal mechanism then manages creating the process associated with the portal and the corresponding communications with the portal's process.

Node:Profiling, Previous:Portal Files, Up:Advanced Features

Profiling Your awk Programs

Beginning with version 3.1 of gawk, you may produce execution traces of your awk programs. This is done with a specially compiled version of gawk, called pgawk ("profiling gawk").

pgawk is identical in every way to gawk, except that when it has finished running, it creates a profile of your program in a file named awkprof.out. Because it is profiling, it also executes up to 45% slower than gawk normally does.

As shown in the following example, the --profile option can be used to change the name of the file where pgawk will write the profile:

$ pgawk --profile=myprog.prof -f myprog.awk data1 data2

In the above example, pgawk places the profile in myprog.prof instead of in awkprof.out.

Regular gawk also accepts this option. When called with just --profile, gawk "pretty prints" the program into awkprof.out, without any execution counts. You may supply an option to --profile to change the file name. Here is a sample session showing a simple awk program, its input data, and the results from running pgawk. First, the awk program:

BEGIN { print "First BEGIN rule" }

END { print "First END rule" }

/foo/ {
    print "matched /foo/, gosh"
    for (i = 1; i <= 3; i++)
        sing()
}

{
    if (/foo/)
        print "if is true"
    else
        print "else is true"
}

BEGIN { print "Second BEGIN rule" }

END { print "Second END rule" }

function sing(    dummy)
{
    print "I gotta be me!"
}

Following is the input data:

foo
bar
baz
foo
junk

Here is the awkprof.out that results from running pgawk on this program and data (this example also illustrates that awk programmers sometimes have to work late):

        # gawk profile, created Sun Aug 13 00:00:15 2000

        # BEGIN block(s)

        BEGIN {
     1          print "First BEGIN rule"
     1          print "Second BEGIN rule"
        }

        # Rule(s)

     5  /foo/   { # 2
     2          print "matched /foo/, gosh"
     6          for (i = 1; i <= 3; i++) {
     6                  sing()
                }
        }

     5  {
     5          if (/foo/) { # 2
     2                  print "if is true"
     3          } else {
     3                  print "else is true"
                }
        }

        # END block(s)

        END {
     1          print "First END rule"
     1          print "Second END rule"
        }

        # Functions, listed alphabetically

     6  function sing(dummy)
        {
     6          print "I gotta be me!"
        }

This example illustrates many of the basic rules for profiling output. The rules are as follows:

  • The program is printed in the order BEGIN rule, pattern/action rules, END rule and functions, listed alphabetically. Multiple BEGIN and END rules are merged together.
  • Pattern-action rules have two counts. The first count, to the left of the rule, shows how many times the rule's pattern was tested. The second count, to the right of the rule's opening left brace in a comment, shows how many times the rule's action was executed. The difference between the two indicates how many times the rule's pattern evaluated to false.
  • Similarly, the count for an if-else statement shows how many times the condition was tested. To the right of the opening left brace for the if's body is a count showing how many times the condition was true. The count for the else indicates how many times the test failed.
  • The count for a loop header (such as for or while) shows how many times the loop test was executed. (Because of this, you can't just look at the count on the first statement in a rule to determine how many times the rule was executed. If the first statement is a loop, the count is misleading.)
  • For user-defined functions, the count next to the function keyword indicates how many times the function was called. The counts next to the statements in the body show how many times those statements were executed.
  • The layout uses "K&R" style with tabs. Braces are used everywhere, even when the body of an if, else, or loop is only a single statement.
  • Parentheses are used only where needed, as indicated by the structure of the program and the precedence rules. For example, (3 + 5) * 4 means add three plus five, then multiply the total by four. However, 3 + 5 * 4 has no parentheses, and means 3 + (5 * 4).
  • All string concatenations are parenthesized too. (This could be made a bit smarter.)
  • Parentheses are used around the arguments to print and printf only when the print or printf statement is followed by a redirection. Similarly, if the target of a redirection isn't a scalar, it gets parenthesized.
  • pgawk supplies leading comments in front of the BEGIN and END rules, the pattern/action rules, and the functions.

The profiled version of your program may not look exactly like what you typed when you wrote it. This is because pgawk creates the profiled version by "pretty printing" its internal representation of the program. The advantage to this is that pgawk can produce a standard representation. The disadvantage is that all source-code comments are lost, as are the distinctions among multiple BEGIN and END rules. Also, things such as:

/foo/

come out as:

/foo/   {
    print $0
}

which is correct, but possibly surprising.

Besides creating profiles when a program has completed, pgawk can produce a profile while it is running. This is useful if your awk program goes into an infinite loop and you want to see what has been executed. To use this feature, run pgawk in the background:

$ pgawk -f myprog &
[1] 13992

The shell prints a job number and process ID number; in this case, 13992. Use the kill command to send the USR1 signal to pgawk:

$ kill -USR1 13992

As usual, the profiled version of the program is written to awkprof.out, or to a different file if you use the --profile option.

Along with the regular profile, as shown earlier, the profile includes a trace of any active functions:

# Function Call Stack:

#   3. baz
#   2. bar
#   1. foo
# -- main --

You may send pgawk the USR1 signal as many times as you like. Each time, the profile and function call trace are appended to the output profile file.

If you use the HUP signal instead of the USR1 signal, pgawk produces the profile and the function call trace and then exits.

When pgawk runs on MS-DOS or MS-Windows, it uses the INT and QUIT signals for producing the profile and, in the case of the INT signal, pgawk exits. This is because these systems don't support the kill command, so the only signals you can deliver to a program are those generated by the keyboard. The INT signal is generated by the Ctrl-<C> or Ctrl-<BREAK> key, while the QUIT signal is generated by the Ctrl-<\> key.

Node:Invoking Gawk, Next:Library Functions, Previous:Advanced Features, Up:Top

Running awk and gawk

This chapter covers how to run awk, both POSIX-standard and gawk-specific command-line options, and what awk and gawk do with non-option arguments. It then proceeds to cover how gawk searches for source files, obsolete options and/or features, and known bugs in gawk. This chapter rounds out the discussion of awk as a program and as a language.

While a number of the options and features described here were discussed in passing earlier in the book, this chapter provides the full details.

  • Command Line: How to run awk.
  • Options: Command-line options and their meanings.
  • Other Arguments: Input file names and variable assignments.
  • AWKPATH Variable: Searching directories for awk programs.
  • Obsolete: Obsolete Options and/or features.
  • Undocumented: Undocumented Options and Features.
  • Known Bugs: Known Bugs in gawk.

Node:Command Line, Next:Options, Previous:Invoking Gawk, Up:Invoking Gawk

Invoking awk

There are two ways to run awk--with an explicit program or with one or more program files. Here are templates for both of them; items enclosed in [...] in these templates are optional:

awk [options] -f progfile [--] file ...
awk [options] [--] 'program' file ...

Besides traditional one-letter POSIX-style options, gawk also supports GNU long options.

It is possible to invoke awk with an empty program:

awk '' datafile1 datafile2

Doing so makes little sense, though; awk exits silently when given an empty program. (d.c.) If --lint has been specified on the command line, gawk issues a warning that the program is empty.

Node:Options, Next:Other Arguments, Previous:Command Line, Up:Invoking Gawk

Command-Line Options

Options begin with a dash and consist of a single character. GNU-style long options consist of two dashes and a keyword. The keyword can be abbreviated, as long as the abbreviation allows the option to be uniquely identified. If the option takes an argument, then the keyword is either immediately followed by an equals sign (=) and the argument's value, or the keyword and the argument's value are separated by whitespace. If a particular option with a value is given more than once, it is the last value that counts.

Each long option for gawk has a corresponding POSIX-style option. The long and short options are interchangeable in all contexts. The options and their meanings are as follows:

-F fs
--field-separator fs
Sets the FS variable to fs (see Specifying How Fields Are Separated).
-f source-file
--file source-file
Indicates that the awk program is to be found in source-file instead of in the first non-option argument.
-v var=val
--assign var=val
Sets the variable var to the value val before execution of the program begins. Such variable values are available inside the BEGIN rule (see Other Command-Line Arguments).

The -v option can only set one variable, but it can be used more than once, setting another variable each time, like this: awk -v foo=1 -v bar=2 ....

Caution: Using -v to set the values of the built-in variables may lead to surprising results. awk will reset the values of those variables as it needs to, possibly ignoring any predefined value you may have given.

-mf N
-mr N
Sets various memory limits to the value N. The f flag sets the maximum number of fields and the r flag sets the maximum record size. These two flags and the -m option are from the Bell Laboratories research version of Unix awk. They are provided for compatibility but otherwise ignored by gawk, since gawk has no predefined limits. (The Bell Laboratories awk no longer needs these options; it continues to accept them to avoid breaking old programs.)
-W gawk-opt
Following the POSIX standard, implementation-specific options are supplied as arguments to the -W option. These options also have corresponding GNU-style long options. Note that the long options may be abbreviated, as long as the abbreviations remain unique. The full list of gawk-specific options is provided next.
--
Signals the end of the command-line options. The following arguments are not treated as options even if they begin with -. This interpretation of -- follows the POSIX argument parsing conventions.

This is useful if you have file names that start with -, or in shell scripts, if you have file names that will be specified by the user that could start with -.

The previous list described options mandated by the POSIX standard, as well as options available in the Bell Laboratories version of awk. The following list describes gawk-specific options:

-W compat
-W traditional
--compat
--traditional
Specifies compatibility mode, in which the GNU extensions to the awk language are disabled, so that gawk behaves just like the Bell Laboratories research version of Unix awk. --traditional is the preferred form of this option. See Extensions in gawk Not in POSIX awk, which summarizes the extensions. Also see Downward Compatibility and Debugging.
-W copyright
--copyright
Print the short version of the General Public License and then exit.
-W copyleft
--copyleft
Just like --copyright. This option may disappear in a future version of gawk.
-W dump-variables[=file]
--dump-variables[=file]
Prints a sorted list of global variables, their types, and final values to file. If no file is provided, gawk prints this list to the file named awkvars.out in the current directory.

Having a list of all global variables is a good way to look for typographical errors in your programs. You would also use this option if you have a large program with a lot of functions, and you want to be sure that your functions don't inadvertently use global variables that you meant to be local. (This is a particularly easy mistake to make with simple variable names like i, j, etc.)

-W gen-po
--gen-po
Analyzes the source program and generates a GNU gettext Portable Object file on standard output for all string constants that have been marked for translation. See Internationalization with gawk, for information about this option.
-W help
-W usage
--help
--usage
Prints a "usage" message summarizing the short and long style options that gawk accepts and then exit.
-W lint[=fatal]
--lint[=fatal]
Warns about constructs that are dubious or nonportable to other awk implementations. Some warnings are issued when gawk first reads your program. Others are issued at runtime, as your program executes. With an optional argument of fatal, lint warnings become fatal errors. This may be drastic, but its use will certainly encourage the development of cleaner awk programs.
-W lint-old
--lint-old
Warns about constructs that are not available in the original version of awk from Version 7 Unix (see Major Changes Between V7 and SVR3.1).
-W non-decimal-data
--non-decimal-data
Enable automatic interpretation of octal and hexadecimal values in input data (see Allowing Nondecimal Input Data).

Caution: This option can severely break old programs. Use with care.

-W posix
--posix
Operates in strict POSIX mode. This disables all gawk extensions (just like --traditional) and adds the following additional restrictions:
  • \x escape sequences are not recognized (see Escape Sequences).
  • Newlines do not act as whitespace to separate fields when FS is equal to a single space (see Examining Fields).
  • Newlines are not allowed after ? or : (see Conditional Expressions).
  • The synonym func for the keyword function is not recognized (see Function Definition Syntax).
  • The ** and **= operators cannot be used in place of ^ and ^= (see Arithmetic Operators, and also see Assignment Expressions).
  • Specifying -Ft on the command-line does not set the value of FS to be a single TAB character (see Specifying How Fields Are Separated).
  • The fflush built-in function is not supported (see Input/Output Functions).

If you supply both --traditional and --posix on the command line, --posix takes precedence. gawk also issues a warning if both options are supplied.

-W profile[=file]
--profile[=file]
Enable profiling of awk programs (see Profiling Your awk Programs). By default, profiles are created in a file named awkprof.out. The optional file argument allows you to specify a different file name for the profile file.

When run with gawk, the profile is just a "pretty printed" version of the program. When run with pgawk, the profile contains execution counts for each statement in the program in the left margin, and function call counts for each function.

-W re-interval
--re-interval
Allows interval expressions (see Regular Expression Operators) in regexps. Because interval expressions were traditionally not available in awk, gawk does not provide them by default. This prevents old awk programs from breaking.
-W source program-text
--source program-text
Allows you to mix source code in files with source code that you enter on the command line. Program source code is taken from the program-text. This is particularly useful when you have library functions that you want to use from your command-line programs (see The AWKPATH Environment Variable).
-W version
--version
Prints version information for this particular copy of gawk. This allows you to determine if your copy of gawk is up to date with respect to whatever the Free Software Foundation is currently distributing. It is also useful for bug reports (see Reporting Problems and Bugs).

As long as program text has been supplied, any other options are flagged as invalid with a warning message but are otherwise ignored.

In compatibility mode, as a special case, if the value of fs supplied to the -F option is t, then FS is set to the TAB character ("\t"). This is true only for --traditional and not for --posix (see Specifying How Fields Are Separated).

The -f option may be used more than once on the command line. If it is, awk reads its program source from all of the named files, as if they had been concatenated together into one big file. This is useful for creating libraries of awk functions. These functions can be written once and then retrieved from a standard place, instead of having to be included into each individual program. (As mentioned in Function Definition Syntax, function names must be unique.)

Library functions can still be used, even if the program is entered at the terminal, by specifying -f /dev/tty. After typing your program, type Ctrl-d (the end-of-file character) to terminate it. (You may also use -f - to read program source from the standard input but then you will not be able to also use the standard input as a source of data.)

Because it is clumsy using the standard awk mechanisms to mix source file and command-line awk programs, gawk provides the --source option. This does not require you to pre-empt the standard input for your source code; it allows you to easily mix command-line and library source code (see The AWKPATH Environment Variable).

If no -f or --source option is specified, then gawk uses the first non-option command-line argument as the text of the program source code.

If the environment variable POSIXLY_CORRECT exists, then gawk behaves in strict POSIX mode, exactly as if you had supplied the --posix command-line option. Many GNU programs look for this environment variable to turn on strict POSIX mode. If --lint is supplied on the command line and gawk turns on POSIX mode because of POSIXLY_CORRECT, then it issues a warning message indicating that POSIX mode is in effect. You would typically set this variable in your shell's startup file. For a Bourne-compatible shell (such as bash), you would add these lines to the .profile file in your home directory:

POSIXLY_CORRECT=true
export POSIXLY_CORRECT

For a csh-compatible shell,48 you would add this line to the .login file in your home directory:

setenv POSIXLY_CORRECT true

Having POSIXLY_CORRECT set is not recommended for daily use, but it is good for testing the portability of your programs to other environments.

Node:Other Arguments, Next:AWKPATH Variable, Previous:Options, Up:Invoking Gawk

Other Command-Line Arguments

Any additional arguments on the command line are normally treated as input files to be processed in the order specified. However, an argument that has the form var=value, assigns the value value to the variable var--it does not specify a file at all. (This was discussed earlier in Assigning Variables on the Command Line.)

All these arguments are made available to your awk program in the ARGV array (see Built-in Variables). Command-line options and the program text (if present) are omitted from ARGV. All other arguments, including variable assignments, are included. As each element of ARGV is processed, gawk sets the variable ARGIND to the index in ARGV of the current element.

The distinction between file name arguments and variable-assignment arguments is made when awk is about to open the next input file. At that point in execution, it checks the file name to see whether it is really a variable assignment; if so, awk sets the variable instead of reading a file.

Therefore, the variables actually receive the given values after all previously specified files have been read. In particular, the values of variables assigned in this fashion are not available inside a BEGIN rule (see The BEGIN and END Special Patterns), because such rules are run before awk begins scanning the argument list.

The variable values given on the command line are processed for escape sequences (see Escape Sequences). (d.c.)

In some earlier implementations of awk, when a variable assignment occurred before any file names, the assignment would happen before the BEGIN rule was executed. awk's behavior was thus inconsistent; some command-line assignments were available inside the BEGIN rule, while others were not. Unfortunately, some applications came to depend upon this "feature." When awk was changed to be more consistent, the -v option was added to accommodate applications that depended upon the old behavior.

The variable assignment feature is most useful for assigning to variables such as RS, OFS, and ORS, which control input and output formats before scanning the data files. It is also useful for controlling state if multiple passes are needed over a data file. For example:

awk 'pass == 1  { pass 1 stuff }
     pass == 2  { pass 2 stuff }' pass=1 mydata pass=2 mydata

Given the variable assignment feature, the -F option for setting the value of FS is not strictly necessary. It remains for historical compatibility.

Node:AWKPATH Variable, Next:Obsolete, Previous:Other Arguments, Up:Invoking Gawk

The AWKPATH Environment Variable

In most awk implementations, you must supply a precise path name for each program file, unless the file is in the current directory. But in gawk, if the file name supplied to the -f option does not contain a /, then gawk searches a list of directories (called the search path), one by one, looking for a file with the specified name.

The search path is a string consisting of directory names separated by colons. gawk gets its search path from the AWKPATH environment variable. If that variable does not exist, gawk uses a default path, .:/usr/local/share/awk.49 (Programs written for use by system administrators should use an AWKPATH variable that does not include the current directory, ..)

The search path feature is particularly useful for building libraries of useful awk functions. The library files can be placed in a standard directory in the default path and then specified on the command line with a short file name. Otherwise, the full file name would have to be typed for each file.

By using both the --source and -f options, your command-line awk programs can use facilities in awk library files (see A Library of awk Functions). Path searching is not done if gawk is in compatibility mode. This is true for both --traditional and --posix. See Command-Line Options.

Note: If you want files in the current directory to be found, you must include the current directory in the path, either by including . explicitly in the path or by writing a null entry in the path. (A null entry is indicated by starting or ending the path with a colon or by placing two colons next to each other (::).) If the current directory is not included in the path, then files cannot be found in the current directory. This path search mechanism is identical to the shell's.

Starting with version 3.0, if AWKPATH is not defined in the environment, gawk places its default search path into ENVIRON["AWKPATH"]. This makes it easy to determine the actual search path that gawk will use from within an awk program.

While you can change ENVIRON["AWKPATH"] within your awk program, this has no effect on the running program's behavior. This makes sense: the AWKPATH environment variable is used to find the program source files. Once your program is running, all the files have been found, and gawk no longer needs to use AWKPATH.

Node:Obsolete, Next:Undocumented, Previous:AWKPATH Variable, Up:Invoking Gawk

Obsolete Options and/or Features

This section describes features and/or command-line options from previous releases of gawk that are either not available in the current version or that are still supported but deprecated (meaning that they will not be in the next release).

For version 3.1 of gawk, there are no deprecated command-line options from the previous version of gawk. The use of next file (two words) for nextfile was deprecated in gawk 3.0 but still worked. Starting with version 3.1, the two-word usage is no longer accepted.

The process-related special files described in Special Files for Process-Related Information, work as described, but are now considered deprecated. gawk prints a warning message every time they are used. (Use PROCINFO instead; see Built-in Variables That Convey Information.) They will be removed from the next release of gawk.

Node:Undocumented, Next:Known Bugs, Previous:Obsolete, Up:Invoking Gawk

Undocumented Options and Features

Use the Source, Luke!
Obi-Wan

This section intentionally left blank.

Node:Known Bugs, Previous:Undocumented, Up:Invoking Gawk

Known Bugs in gawk

  • The -F option for changing the value of FS (see Command-Line Options) is not necessary given the command-line variable assignment feature; it remains only for backward compatibility.
  • Syntactically invalid single-character programs tend to overflow the parse stack, generating a rather unhelpful message. Such programs are surprisingly difficult to diagnose in the completely general case, and the effort to do so really is not worth it.

Node:Library Functions, Next:Sample Programs, Previous:Invoking Gawk, Up:Top

A Library of awk Functions

User-Defined Functions, describes how to write your own awk functions. Writing functions is important, because it allows you to encapsulate algorithms and program tasks in a single place. It simplifies programming, making program development more manageable, and making programs more readable.

One valuable way to learn a new programming language is to read programs in that language. To that end, this chapter and Practical awk Programs, provide a good-sized body of code for you to read, and hopefully, to learn from.

This chapter presents a library of useful awk functions. Many of the sample programs presented later in this Web page use these functions. The functions are presented here in a progression from simple to complex. Extracting Programs from Texinfo Source Files, presents a program that you can use to extract the source code for these example library functions and programs from the Texinfo source for this Web page. (This has already been done as part of the gawk distribution.)

If you have written one or more useful, general-purpose awk functions and would like to contribute them to the author's collection of awk programs, see How to Contribute, for more information.

The programs in this chapter and in Practical awk Programs, freely use features that are gawk-specific. Rewriting these programs for different implementations of awk is pretty straightforward.

Diagnostic error messages are sent to /dev/stderr. Use | "cat 1>&2" instead of > "/dev/stderr" if your system does not have a /dev/stderr, or if you cannot use gawk.

A number of programs use nextfile (see Using gawk's nextfile Statement) to skip any remaining input in the input file. Implementing nextfile as a Function, shows you how to write a function that does the same thing.

Finally, some of the programs choose to ignore upper- and lowercase distinctions in their input. They do so by assigning one to IGNORECASE. You can achieve almost the same effect50 by adding the following rule to the beginning of the program:

# ignore case
{ $0 = tolower($0) }

Also, verify that all regexp and string constants used in comparisons use only lowercase letters.

  • Library Names: How to best name private global variables in library functions.
  • General Functions: Functions that are of general use.
  • Data File Management: Functions for managing command-line data files.
  • Getopt Function: A function for processing command-line arguments.
  • Passwd Functions: Functions for getting user information.
  • Group Functions: Functions for getting group information.

Node:Library Names, Next:General Functions, Previous:Library Functions, Up:Library Functions

Naming Library Function Global Variables

Due to the way the awk language evolved, variables are either global (usable by the entire program) or local (usable just by a specific function). There is no intermediate state analogous to static variables in C.

Library functions often need to have global variables that they can use to preserve state information between calls to the function--for example, getopt's variable _opti (see Processing Command-Line Options). Such variables are called private, since the only functions that need to use them are the ones in the library.

When writing a library function, you should try to choose names for your private variables that will not conflict with any variables used by either another library function or a user's main program. For example, a name like i or j is not a good choice, because user programs often use variable names like these for their own purposes.

The example programs shown in this chapter all start the names of their private variables with an underscore (_). Users generally don't use leading underscores in their variable names, so this convention immediately decreases the chances that the variable name will be accidentally shared with the user's program.

In addition, several of the library functions use a prefix that helps indicate what function or set of functions use the variables--for example, _pw_byname in the user database routines (see Reading the User Database). This convention is recommended, since it even further decreases the chance of inadvertent conflict among variable names. Note that this convention is used equally well for variable names and for private function names as well.51

As a final note on variable naming, if a function makes global variables available for use by a main program, it is a good convention to start that variable's name with a capital letter--for example, getopt's Opterr and Optind variables (see Processing Command-Line Options). The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the variable is not one of awk's built-in variables, such as FS.

It is also important that all variables in library functions that do not need to save state are, in fact, declared local.52 If this is not done, the variable could accidentally be used in the user's program, leading to bugs that are very difficult to track down:

function lib_func(x, y,    l1, l2)
{
    ...
    use variable some_var   # some_var should be local
    ...                   # but is not by oversight
}

A different convention, common in the Tcl community, is to use a single associative array to hold the values needed by the library function(s), or "package." This significantly decreases the number of actual global names in use. For example, the functions described in Reading the User Database, might have used array elements PW_data["inited"], PW_data["total"], PW_data["count"], and PW_data["awklib"], instead of _pw_inited, _pw_awklib, _pw_total, and _pw_count.

The conventions presented in this section are exactly that: conventions. You are not required to write your programs this way--we merely recommend that you do so.

Node:General Functions, Next:Data File Management, Previous:Library Names, Up:Library Functions

General Programming

This section presents a number of functions that are of general programming use.

  • Nextfile Function: Two implementations of a nextfile function.
  • Assert Function: A function for assertions in awk programs.
  • Round Function: A function for rounding if sprintf does not do it correctly.
  • Cliff Random Function: The Cliff Random Number Generator.
  • Ordinal Functions: Functions for using characters as numbers and vice versa.
  • Join Function: A function to join an array into a string.
  • Gettimeofday Function: A function to get formatted times.

Node:Nextfile Function, Next:Assert Function, Previous:General Functions, Up:General Functions

Implementing nextfile as a Function

The nextfile statement, presented in Using gawk's nextfile Statement, is a gawk-specific extension--it is not available in most other implementations of awk. This section shows two versions of a nextfile function that you can use to simulate gawk's nextfile statement if you cannot use gawk.

A first attempt at writing a nextfile function is as follows:

# nextfile --- skip remaining records in current file
# this should be read in before the "main" awk program

function nextfile()    { _abandon_ = FILENAME; next }
_abandon_ == FILENAME  { next }

Because it supplies a rule that must be executed first, this file should be included before the main program. This rule compares the current data file's name (which is always in the FILENAME variable) to a private variable named _abandon_. If the file name matches, then the action part of the rule executes a next statement to go on to the next record. (The use of _ in the variable name is a convention. It is discussed more fully in Naming Library Function Global Variables.)

The use of the next statement effectively creates a loop that reads all the records from the current data file. The end of the file is eventually reached and a new data file is opened, changing the value of FILENAME. Once this happens, the comparison of _abandon_ to FILENAME fails, and execution continues with the first rule of the "real" program.

The nextfile function itself simply sets the value of _abandon_ and then executes a next statement to start the loop.

This initial version has a subtle problem. If the same data file is listed twice on the commandline, one right after the other or even with just a variable assignment between them, this code skips right through the file a second time, even though it should stop when it gets to the end of the first occurrence. A second version of nextfile that remedies this problem is shown here:

# nextfile --- skip remaining records in current file
# correctly handle successive occurrences of the same file
# this should be read in before the "main" awk program

function nextfile()   { _abandon_ = FILENAME; next }

_abandon_ == FILENAME {
      if (FNR == 1)
          _abandon_ = ""
      else
          next
}

The nextfile function has not changed. It makes _abandon_ equal to the current file name and then executes a next statement. The next statement reads the next record and increments FNR so that FNR is guaranteed to have a value of at least two. However, if nextfile is called for the last record in the file, then awk closes the current data file and moves on to the next one. Upon doing so, FILENAME is set to the name of the new file and FNR is reset to one. If this next file is the same as the previous one, _abandon_ is still equal to FILENAME. However, FNR is equal to one, telling us that this is a new occurrence of the file and not the one we were reading when the nextfile function was executed. In that case, _abandon_ is reset to the empty string, so that further executions of this rule fail (until the next time that nextfile is called).

If FNR is not one, then we are still in the original data file and the program executes a next statement to skip through it.

An important question to ask at this point is: given that the functionality of nextfile can be provided with a library file, why is it built into gawk? Adding features for little reason leads to larger, slower programs that are harder to maintain. The answer is that building nextfile into gawk provides significant gains in efficiency. If the nextfile function is executed at the beginning of a large data file, awk still has to scan the entire file, splitting it up into records, just to skip over it. The built-in nextfile can simply close the file immediately and proceed to the next one, which saves a lot of time. This is particularly important in awk, because awk programs are generally I/O-bound (i.e., they spend most of their time doing input and output, instead of performing computations).

Node:Assert Function, Next:Round Function, Previous:Nextfile Function, Up:General Functions

Assertions

When writing large programs, it is often useful to know that a condition or set of conditions is true. Before proceeding with a particular computation, you make a statement about what you believe to be the case. Such a statement is known as an assertion. The C language provides an <assert.h> header file and corresponding assert macro that the programmer can use to make assertions. If an assertion fails, the assert macro arranges to print a diagnostic message describing the condition that should have been true but was not, and then it kills the program. In C, using assert looks this:

#include <assert.h>

int myfunc(int a, double b)
{
     assert(a <= 5 && b >= 17.1);
     ...
}

If the assertion fails, the program prints a message similar to this:

prog.c:5: assertion failed: a <= 5 && b >= 17.1

The C language makes it possible to turn the condition into a string for use in printing the diagnostic message. This is not possible in awk, so this assert function also requires a string version of the condition that is being tested. Following is the function:

# assert --- assert that a condition is true. Otherwise exit.
function assert(condition, string)
{
    if (! condition) {
        printf("%s:%d: assertion failed: %s\n",
            FILENAME, FNR, string) > "/dev/stderr"
        _assert_exit = 1
        exit 1
    }
}

END {
    if (_assert_exit)
        exit 1
}

The assert function tests the condition parameter. If it is false, it prints a message to standard error, using the string parameter to describe the failed condition. It then sets the variable _assert_exit to one and executes the exit statement. The exit statement jumps to the END rule. If the END rules finds _assert_exit to be true, it exits immediately.

The purpose of the test in the END rule is to keep any other END rules from running. When an assertion fails, the program should exit immediately. If no assertions fail, then _assert_exit is still false when the END rule is run normally, and the rest of the program's END rules execute. For all of this to work correctly, assert.awk must be the first source file read by awk. The function can be used in a program in the following way:

function myfunc(a, b)
{
     assert(a <= 5 && b >= 17.1, "a <= 5 && b >= 17.1")
     ...
}

If the assertion fails, you see a message similar to the following:

mydata:1357: assertion failed: a <= 5 && b >= 17.1

There is a small problem with this version of assert. An END rule is automatically added to the program calling assert. Normally, if a program consists of just a BEGIN rule, the input files and/or standard input are not read. However, now that the program has an END rule, awk attempts to read the input data files or standard input (see Startup and Cleanup Actions), most likely causing the program to hang as it waits for input.

There is a simple workaround to this: make sure the BEGIN rule always ends with an exit statement.

Node:Round Function, Next:Cliff Random Function, Previous:Assert Function, Up:General Functions

Rounding Numbers

The way printf and sprintf (see Using printf Statements for Fancier Printing) perform rounding often depends upon the system's C sprintf subroutine. On many machines, sprintf rounding is "unbiased," which means it doesn't always round a trailing .5 up, contrary to naive expectations. In unbiased rounding, .5 rounds to even, rather than always up, so 1.5 rounds to 2 but 4.5 rounds to 4. This means that if you are using a format that does rounding (e.g., "%.0f"), you should check what your system does. The following function does traditional rounding; it might be useful if your awk's printf does unbiased rounding:

# round.awk --- do normal rounding
function round(x,   ival, aval, fraction)
{
   ival = int(x)    # integer part, int() truncates

   # see if fractional part
   if (ival == x)   # no fraction
      return x

   if (x < 0) {
      aval = -x     # absolute value
      ival = int(aval)
      fraction = aval - ival
      if (fraction >= .5)
         return int(x) - 1   # -2.5 --> -3
      else
         return int(x)       # -2.3 --> -2
   } else {
      fraction = x - ival
      if (fraction >= .5)
         return ival + 1
      else
         return ival
   }
}

# test harness
{ print $0, round($0) }

Node:Cliff Random Function, Next:Ordinal Functions, Previous:Round Function, Up:General Functions

The Cliff Random Number Generator

The Cliff random number generator53 is a very simple random number generator that "passes the noise sphere test for randomness by showing no structure." It is easily programmed, in less than 10 lines of awk code:

# cliff_rand.awk --- generate Cliff random numbers
BEGIN { _cliff_seed = 0.1 }

function cliff_rand()
{
    _cliff_seed = (100 * log(_cliff_seed)) % 1
    if (_cliff_seed < 0)
        _cliff_seed = - _cliff_seed
    return _cliff_seed
}

This algorithm requires an initial "seed" of 0.1. Each new value uses the current seed as input for the calculation. If the built-in rand function (see Numeric Functions) isn't random enough, you might try using this function instead.

Node:Ordinal Functions, Next:Join Function, Previous:Cliff Random Function, Up:General Functions

Translating Between Characters and Numbers

One commercial implementation of awk supplies a built-in function, ord, which takes a character and returns the numeric value for that character in the machine's character set. If the string passed to ord has more than one character, only the first one is used.

The inverse of this function is chr (from the function of the same name in Pascal), which takes a number and returns the corresponding character. Both functions are written very nicely in awk; there is no real reason to build them into the awk interpreter:

# ord.awk --- do ord and chr

# Global identifiers:
#    _ord_:        numerical values indexed by characters
#    _ord_init:    function to initialize _ord_
BEGIN    { _ord_init() }

function _ord_init(    low, high, i, t)
{
    low = sprintf("%c", 7) # BEL is ascii 7
    if (low == "\a") {    # regular ascii
        low = 0
        high = 127
    } else if (sprintf("%c", 128 + 7) == "\a") {
        # ascii, mark parity
        low = 128
        high = 255
    } else {        # ebcdic(!)
        low = 0
        high = 255
    }

    for (i = low; i <= high; i++) {
        t = sprintf("%c", i)
        _ord_[t] = i
    }
}

Some explanation of the numbers used by chr is worthwhile. The most prominent character set in use today is ASCII. Although an 8-bit byte can hold 256 distinct values (from 0 to 255), ASCII only defines characters that use the values from 0 to 127.54 In the now distant past, at least one minicomputer manufacturer used ASCII, but with mark parity, meaning that the leftmost bit in the byte is always 1. This means that on those systems, characters have numeric values from 128 to 255. Finally, large mainframe systems use the EBCDIC character set, which uses all 256 values. While there are other character sets in use on some older systems, they are not really worth worrying about:

function ord(str,    c)
{
    # only first character is of interest
    c = substr(str, 1, 1)
    return _ord_[c]
}

function chr(c)
{
    # force c to be numeric by adding 0
    return sprintf("%c", c + 0)
}

#### test code ####
# BEGIN    \
# {
#    for (;;) {
#        printf("enter a character: ")
#        if (getline var <= 0)
#            break
#        printf("ord(%s) = %d\n", var, ord(var))
#    }
# }

An obvious improvement to these functions is to move the code for the _ord_init function into the body of the BEGIN rule. It was written this way initially for ease of development. There is a "test program" in a BEGIN rule, to test the function. It is commented out for production use.

Node:Join Function, Next:Gettimeofday Function, Previous:Ordinal Functions, Up:General Functions

Merging an Array into a String

When doing string processing, it is often useful to be able to join all the strings in an array into one long string. The following function, join, accomplishes this task. It is used later in several of the application programs (see Practical awk Programs).

Good function design is important; this function needs to be general but it should also have a reasonable default behavior. It is called with an array as well as the beginning and ending indices of the elements in the array to be merged. This assumes that the array indices are numeric--a reasonable assumption since the array was likely created with split (see String Manipulation Functions):

# join.awk --- join an array into a string
function join(array, start, end, sep,    result, i)
{
    if (sep == "")
       sep = " "
    else if (sep == SUBSEP) # magic value
       sep = ""
    result = array[start]
    for (i = start + 1; i <= end; i++)
        result = result sep array[i]
    return result
}

An optional additional argument is the separator to use when joining the strings back together. If the caller supplies a nonempty value, join uses it; if it is not supplied, it has a null value. In this case, join uses a single blank as a default separator for the strings. If the value is equal to SUBSEP, then join joins the strings with no separator between them. SUBSEP serves as a "magic" value to indicate that there should be no separation between the component strings.55

Node:Gettimeofday Function, Previous:Join Function, Up:General Functions

Managing the Time of Day

The systime and strftime functions described in Using gawk's Timestamp Functions, provide the minimum functionality necessary for dealing with the time of day in human readable form. While strftime is extensive, the control formats are not necessarily easy to remember or intuitively obvious when reading a program.

The following function, gettimeofday, populates a user-supplied array with preformatted time information. It returns a string with the current time formatted in the same way as the date utility:

# gettimeofday.awk --- get the time of day in a usable format

# Returns a string in the format of output of date(1)
# Populates the array argument time with individual values:
#    time["second"]       -- seconds (0 - 59)
#    time["minute"]       -- minutes (0 - 59)
#    time["hour"]         -- hours (0 - 23)
#    time["althour"]      -- hours (0 - 12)
#    time["monthday"]     -- day of month (1 - 31)
#    time["month"]        -- month of year (1 - 12)
#    time["monthname"]    -- name of the month
#    time["shortmonth"]   -- short name of the month
#    time["year"]         -- year modulo 100 (0 - 99)
#    time["fullyear"]     -- full year
#    time["weekday"]      -- day of week (Sunday = 0)
#    time["altweekday"]   -- day of week (Monday = 0)
#    time["dayname"]      -- name of weekday
#    time["shortdayname"] -- short name of weekday
#    time["yearday"]      -- day of year (0 - 365)
#    time["timezone"]     -- abbreviation of timezone name
#    time["ampm"]         -- AM or PM designation
#    time["weeknum"]      -- week number, Sunday first day
#    time["altweeknum"]   -- week number, Monday first day

function gettimeofday(time,    ret, now, i)
{
    # get time once, avoids unnecessary system calls
    now = systime()

    # return date(1)-style output
    ret = strftime("%a %b %d %H:%M:%S %Z %Y", now)

    # clear out target array
    delete time

    # fill in values, force numeric values to be
    # numeric by adding 0
    time["second"]       = strftime("%S", now) + 0
    time["minute"]       = strftime("%M", now) + 0
    time["hour"]         = strftime("%H", now) + 0
    time["althour"]      = strftime("%I", now) + 0
    time["monthday"]     = strftime("%d", now) + 0
    time["month"]        = strftime("%m", now) + 0
    time["monthname"]    = strftime("%B", now)
    time["shortmonth"]   = strftime("%b", now)
    time["year"]         = strftime("%y", now) + 0
    time["fullyear"]     = strftime("%Y", now) + 0
    time["weekday"]      = strftime("%w", now) + 0
    time["altweekday"]   = strftime("%u", now) + 0
    time["dayname"]      = strftime("%A", now)
    time["shortdayname"] = strftime("%a", now)
    time["yearday"]      = strftime("%j", now) + 0
    time["timezone"]     = strftime("%Z", now)
    time["ampm"]         = strftime("%p", now)
    time["weeknum"]      = strftime("%U", now) + 0
    time["altweeknum"]   = strftime("%W", now) + 0

    return ret
}

The string indices are easier to use and read than the various formats required by strftime. The alarm program presented in An Alarm Clock Program, uses this function. A more general design for the gettimeofday function would have allowed the user to supply an optional timestamp value to use instead of the current time.

Node:Data File Management, Next:Getopt Function, Previous:General Functions, Up:Library Functions

Data File Management

This section presents functions that are useful for managing command-line data files.

  • Filetrans Function: A function for handling data file transitions.
  • Rewind Function: A function for rereading the current file.
  • File Checking: Checking that data files are readable.
  • Ignoring Assigns: Treating assignments as file names.

Node:Filetrans Function, Next:Rewind Function, Previous:Data File Management, Up:Data File Management

Noting Data File Boundaries

The BEGIN and END rules are each executed exactly once at the beginning and end of your awk program, respectively (see The BEGIN and END Special Patterns). We (the gawk authors) once had a user who mistakenly thought that the BEGIN rule is executed at the beginning of each data file and the END rule is executed at the end of each data file. When informed that this was not the case, the user requested that we add new special patterns to gawk, named BEGIN_FILE and END_FILE, that would have the desired behavior. He even supplied us the code to do so.

Adding these special patterns to gawk wasn't necessary; the job can be done cleanly in awk itself, as illustrated by the following library program. It arranges to call two user-supplied functions, beginfile and endfile, at the beginning and end of each data file. Besides solving the problem in only nine(!) lines of code, it does so portably; this works with any implementation of awk:

# transfile.awk
#
# Give the user a hook for filename transitions
#
# The user must supply functions beginfile() and endfile()
# that each take the name of the file being started or
# finished, respectively.

FILENAME != _oldfilename \
{
    if (_oldfilename != "")
        endfile(_oldfilename)
    _oldfilename = FILENAME
    beginfile(FILENAME)
}

END   { endfile(FILENAME) }

This file must be loaded before the user's "main" program, so that the rule it supplies is executed first.

This rule relies on awk's FILENAME variable that automatically changes for each new data file. The current file name is saved in a private variable, _oldfilename. If FILENAME does not equal _oldfilename, then a new data file is being processed and it is necessary to call endfile for the old file. Because endfile should only be called if a file has been processed, the program first checks to make sure that _oldfilename is not the null string. The program then assigns the current file name to _oldfilename and calls beginfile for the file. Because, like all awk variables, _oldfilename is initialized to the null string, this rule executes correctly even for the first data file.

The program also supplies an END rule to do the final processing for the last file. Because this END rule comes before any END rules supplied in the "main" program, endfile is called first. Once again the value of multiple BEGIN and END rules should be clear.

This version has same problem as the first version of nextfile (see Implementing nextfile as a Function). If the same data file occurs twice in a row on the command line, then endfile and beginfile are not executed at the end of the first pass and at the beginning of the second pass. The following version solves the problem:

# ftrans.awk --- handle data file transitions
#
# user supplies beginfile() and endfile() functions
FNR == 1 {
    if (_filename_ != "")
        endfile(_filename_)
    _filename_ = FILENAME
    beginfile(FILENAME)
}

END  { endfile(_filename_) }
Counting Things, shows how this library function can be used and how it simplifies writing the main program.

Node:Rewind Function, Next:File Checking, Previous:Filetrans Function, Up:Data File Management

Rereading the Current File

Another request for a new built-in function was for a rewind function that would make it possible to reread the current file. The requesting user didn't want to have to use getline (see Explicit Input with getline) inside a loop.

However, as long as you are not in the END rule, it is quite easy to arrange to immediately close the current input file and then start over with it from the top. For lack of a better name, we'll call it rewind:

# rewind.awk --- rewind the current file and start over
function rewind(    i)
{
    # shift remaining arguments up
    for (i = ARGC; i > ARGIND; i--)
        ARGV[i] = ARGV[i-1]

    # make sure gawk knows to keep going
    ARGC++

    # make current file next to get done
    ARGV[ARGIND+1] = FILENAME

    # do it
    nextfile
}

This code relies on the ARGIND variable (see Built-in Variables That Convey Information), which is specific to gawk. If you are not using gawk, you can use ideas presented in Noting Data File Boundaries, to either update ARGIND on your own or modify this code as appropriate.

The rewind function also relies on the nextfile keyword (see Using gawk's nextfile Statement). See Implementing nextfile as a Function, for a function version of nextfile.

Node:File Checking, Next:Ignoring Assigns, Previous:Rewind Function, Up:Data File Management

Checking for Readable Data Files

Normally, if you give awk a data file that isn't readable, it stops with a fatal error. There are times when you might want to just ignore such files and keep going. You can do this by prepending the following program to your awk program:

# readable.awk --- library file to skip over unreadable files
BEGIN {
    for (i = 1; i < ARGC; i++) {
        if (ARGV[i] ~ /^[A-Za-z_][A-Za-z0-9_]*=.*/ \
            || ARGV[i] == "-")
            continue    # assignment or standard input
        else if ((getline junk < ARGV[i]) < 0) # unreadable
            delete ARGV[i]
        else
            close(ARGV[i])
    }
}

In gawk, the getline won't be fatal (unless --posix is in force). Removing the element from ARGV with delete skips the file (since it's no longer in the list).

Node:Ignoring Assigns, Previous:File Checking, Up:Data File Management

Treating Assignments as File Names

Occasionally, you might not want awk to process command-line variable assignments (see Assigning Variables on the Command Line). In particular, if you have file names that contain an = character, awk treats the file name as an assignment, and does not process it.

Some users have suggested an additional command-line option for gawk to disable command-line assignments. However, some simple programming with a library file does the trick:

# noassign.awk --- library file to avoid the need for a
# special option that disables command-line assignments
function disable_assigns(argc, argv,    i)
{
    for (i = 1; i < argc; i++)
        if (argv[i] ~ /^[A-Za-z_][A-Za-z_0-9]*=.*/)
            argv[i] = ("./" argv[i])
}

BEGIN {
    if (No_command_assign)
        disable_assigns(ARGC, ARGV)
}

You then run your program this way:

awk -v No_command_assign=1 -f noassign.awk -f yourprog.awk *

The function works by looping through the arguments. It prepends ./ to any argument that matches the form of a variable assignment, turning that argument into a file name.

The use of No_command_assign allows you to disable command-line assignments at invocation time, by giving the variable a true value. When not set, it is initially zero (i.e., false), so the command-line arguments are left alone.

Node:Getopt Function, Next:Passwd Functions, Previous:Data File Management, Up:Library Functions

Processing Command-Line Options

Most utilities on POSIX compatible systems take options, or "switches," on the command line that can be used to change the way a program behaves. awk is an example of such a program (see Command-Line Options). Often, options take arguments; i.e., data that the program needs to correctly obey the command-line option. For example, awk's -F option requires a string to use as the field separator. The first occurrence on the command line of either -- or a string that does not begin with - ends the options.

Modern Unix systems provide a C function named getopt for processing command-line arguments. The programmer provides a string describing the one-letter options. If an option requires an argument, it is followed in the string with a colon. getopt is also passed the count and values of the command-line arguments and is called in a loop. getopt processes the command-line arguments for option letters. Each time around the loop, it returns a single character representing the next option letter that it finds, or ? if it finds an invalid option. When it returns -1, there are no options left on the command line.

When using getopt, options that do not take arguments can be grouped together. Furthermore, options that take arguments require that the argument is present. The argument can immediately follow the option letter, or it can be a separate command-line argument.

Given a hypothetical program that takes three command-line options, -a, -b, and -c, where -b requires an argument, all of the following are valid ways of invoking the program:

prog -a -b foo -c data1 data2 data3
prog -ac -bfoo -- data1 data2 data3
prog -acbfoo data1 data2 data3

Notice that when the argument is grouped with its option, the rest of the argument is considered to be the option's argument. In this example, -acbfoo indicates that all of the -a, -b, and -c options were supplied, and that foo is the argument to the -b option.

getopt provides four external variables that the programmer can use:

optind
The index in the argument value array (argv) where the first nonoption command-line argument can be found.
optarg
The string value of the argument to an option.
opterr
Usually getopt prints an error message when it finds an invalid option. Setting opterr to zero disables this feature. (An application might want to print its own error message.)
optopt
The letter representing the command-line option.

The following C fragment shows how getopt might process command-line arguments for awk:

int
main(int argc, char *argv[])
{
    ...
    /* print our own message */
    opterr = 0;
    while ((c = getopt(argc, argv, "v:f:F:W:")) != -1) {
        switch (c) {
        case 'f':    /* file */
            ...
            break;
        case 'F':    /* field separator */
            ...
            break;
        case 'v':    /* variable assignment */
            ...
            break;
        case 'W':    /* extension */
            ...
            break;
        case '?':
        default:
            usage();
            break;
        }
    }
    ...
}

As a side point, gawk actually uses the GNU getopt_long function to process both normal and GNU-style long options (see Command-Line Options).

The abstraction provided by getopt is very useful and is quite handy in awk programs as well. Following is an awk version of getopt. This function highlights one of the greatest weaknesses in awk, which is that it is very poor at manipulating single characters. Repeated calls to substr are necessary for accessing individual characters (see String Manipulation Functions).56

The discussion that follows walks through the code a bit at a time:

# getopt.awk --- do C library getopt(3) function in awk
# External variables:
#    Optind -- index in ARGV of first nonoption argument
#    Optarg -- string value of argument to current option
#    Opterr -- if nonzero, print our own diagnostic
#    Optopt -- current option letter

# Returns:
#    -1     at end of options
#    ?      for unrecognized option
#    <c>    a character representing the current option

# Private Data:
#    _opti  -- index in multi-flag option, e.g., -abc

The function starts out with a list of the global variables it uses, what the return values are, what they mean, and any global variables that are "private" to this library function. Such documentation is essential for any program, and particularly for library functions.

The getopt function first checks that it was indeed called with a string of options (the options parameter). If options has a zero length, getopt immediately returns -1:

function getopt(argc, argv, options,    thisopt, i)
{
    if (length(options) == 0)    # no options given
        return -1

    if (argv[Optind] == "--") {  # all done
        Optind++
        _opti = 0
        return -1
    } else if (argv[Optind] !~ /^-[^: \t\n\f\r\v\b]/) {
        _opti = 0
        return -1
    }

The next thing to check for is the end of the options. A -- ends the command-line options, as does any command-line argument that does not begin with a -. Optind is used to step through the array of command-line arguments; it retains its value across calls to getopt, because it is a global variable.

The regular expression that is used, /^-[^: \t\n\f\r\v\b]/, is perhaps a bit of overkill; it checks for a - followed by anything that is not whitespace and not a colon. If the current command-line argument does not match this pattern, it is not an option, and it ends option processing:

    if (_opti == 0)
        _opti = 2
    thisopt = substr(argv[Optind], _opti, 1)
    Optopt = thisopt
    i = index(options, thisopt)
    if (i == 0) {
        if (Opterr)
            printf("%c -- invalid option\n",
                                  thisopt) > "/dev/stderr"
        if (_opti >= length(argv[Optind])) {
            Optind++
            _opti = 0
        } else
            _opti++
        return "?"
    }

The _opti variable tracks the position in the current command-line argument (argv[Optind]). If multiple options are grouped together with one - (e.g., -abx), it is necessary to return them to the user one at a time.

If _opti is equal to zero, it is set to two, which is the index in the string of the next character to look at (we skip the -, which is at position one). The variable thisopt holds the character, obtained with substr. It is saved in Optopt for the main program to use.

If thisopt is not in the options string, then it is an invalid option. If Opterr is nonzero, getopt prints an error message on the standard error that is similar to the message from the C version of getopt.

Because the option is invalid, it is necessary to skip it and move on to the next option character. If _opti is greater than or equal to the length of the current command-line argument, it is necessary to move on to the next argument, so Optind is incremented and _opti is reset to zero. Otherwise, Optind is left alone and _opti is merely incremented.

In any case, because the option is invalid, getopt returns ?. The main program can examine Optopt if it needs to know what the invalid option letter actually is. Continuing on:

    if (substr(options, i + 1, 1) == ":") {
        # get option argument
        if (length(substr(argv[Optind], _opti + 1)) > 0)
            Optarg = substr(argv[Optind], _opti + 1)
        else
            Optarg = argv[++Optind]
        _opti = 0
    } else
        Optarg = ""

If the option requires an argument, the option letter is followed by a colon in the options string. If there are remaining characters in the current command-line argument (argv[Optind]), then the rest of that string is assigned to Optarg. Otherwise, the next command-line argument is used (-xFOO versus -x FOO). In either case, _opti is reset to zero, because there are no more characters left to examine in the current command-line argument. Continuing:

    if (_opti == 0 || _opti >= length(argv[Optind])) {
        Optind++
        _opti = 0
    } else
        _opti++
    return thisopt
}

Finally, if _opti is either zero or greater than the length of the current command-line argument, it means this element in argv is through being processed, so Optind is incremented to point to the next element in argv. If neither condition is true, then only _opti is incremented, so that the next option letter can be processed on the next call to getopt.

The BEGIN rule initializes both Opterr and Optind to one. Opterr is set to one, since the default behavior is for getopt to print a diagnostic message upon seeing an invalid option. Optind is set to one, since there's no reason to look at the program name, which is in ARGV[0]:

BEGIN {
    Opterr = 1    # default is to diagnose
    Optind = 1    # skip ARGV[0]

    # test program
    if (_getopt_test) {
        while ((_go_c = getopt(ARGC, ARGV, "ab:cd")) != -1)
            printf("c = <%c>, optarg = <%s>\n",
                                       _go_c, Optarg)
        printf("non-option arguments:\n")
        for (; Optind < ARGC; Optind++)
            printf("\tARGV[%d] = <%s>\n",
                                    Optind, ARGV[Optind])
    }
}

The rest of the BEGIN rule is a simple test program. Here is the result of two sample runs of the test program:

$ awk -f getopt.awk -v _getopt_test=1 -- -a -cbARG bax -x
-| c = <a>, optarg = <>
-| c = <c>, optarg = <>
-| c = <b>, optarg = <ARG>
-| non-option arguments:
-|         ARGV[3] = <bax>
-|         ARGV[4] = <-x>

$ awk -f getopt.awk -v _getopt_test=1 -- -a -x -- xyz abc
-| c = <a>, optarg = <>
error--> x -- invalid option
-| c = <?>, optarg = <>
-| non-option arguments:
-|         ARGV[4] = <xyz>
-|         ARGV[5] = <abc>

In both runs, the first -- terminates the arguments to awk, so that it does not try to interpret the -a, etc., as its own options. Several of the sample programs presented in Practical awk Programs, use getopt to process their arguments.

Node:Passwd Functions, Next:Group Functions, Previous:Getopt Function, Up:Library Functions

Reading the User Database

The PROCINFO array (see Built-in Variables) provides access to the current user's real and effective user and group ID numbers, and if available, the user's supplementary group set. However, because these are numbers, they do not provide very useful information to the average user. There needs to be some way to find the user information associated with the user and group ID numbers. This section presents a suite of functions for retrieving information from the user database. See Reading the Group Database, for a similar suite that retrieves information from the group database.

The POSIX standard does not define the file where user information is kept. Instead, it provides the <pwd.h> header file and several C language subroutines for obtaining user information. The primary function is getpwent, for "get password entry." The "password" comes from the original user database file, /etc/passwd, which stores user information, along with the encrypted passwords (hence the name).

While an awk program could simply read /etc/passwd directly, this file may not contain complete information about the system's set of users.57 To be sure you are able to produce a readable and complete version of the user database, it is necessary to write a small C program that calls getpwent. getpwent is defined as returning a pointer to a struct passwd. Each time it is called, it returns the next entry in the database. When there are no more entries, it returns NULL, the null pointer. When this happens, the C program should call endpwent to close the database. Following is pwcat, a C program that "cats" the password database:

/*
 * pwcat.c
 *
 * Generate a printable version of the password database
 */
#include <stdio.h>
#include <pwd.h>

int
main(argc, argv)
int argc;
char **argv;
{
    struct passwd *p;

    while ((p = getpwent()) != NULL)
        printf("%s:%s:%d:%d:%s:%s:%s\n",
            p->pw_name, p->pw_passwd, p->pw_uid,
            p->pw_gid, p->pw_gecos, p->pw_dir, p->pw_shell);

    endpwent();
    exit(0);
}

If you don't understand C, don't worry about it. The output from pwcat is the user database, in the traditional /etc/passwd format of colon-separated fields. The fields are:

Login name | The user's login name.
Encrypted password | The user's encrypted password. This may not be available on some systems.
User-ID | The user's numeric user ID number.
Group-ID | The user's numeric group ID number.
Full name | The user's full name, and perhaps other information associated with the user.
Home directory | The user's login (or "home") directory (familiar to shell programmers as $HOME).
Login shell | The program that is run when the user logs in. This is usually a shell, such as bash.

A few lines representative of pwcat's output are as follows:

$ pwcat
-| root:3Ov02d5VaUPB6:0:1:Operator:/:/bin/sh
-| nobody:*:65534:65534::/:
-| daemon:*:1:1::/:
-| sys:*:2:2::/:/bin/csh
-| bin:*:3:3::/bin:
-| arnold:xyzzy:2076:10:Arnold Robbins:/home/arnold:/bin/sh
-| miriam:yxaay:112:10:Miriam Robbins:/home/miriam:/bin/sh
-| andy:abcca2:113:10:Andy Jacobs:/home/andy:/bin/sh
...

With that introduction, following is a group of functions for getting user information. There are several functions here, corresponding to the C functions of the same names:

# passwd.awk --- access password file information
BEGIN {
    # tailor this to suit your system
    _pw_awklib = "/usr/local/libexec/awk/"
}

function _pw_init(    oldfs, oldrs, olddol0, pwcat, using_fw)
{
    if (_pw_inited)
        return

    oldfs = FS
    oldrs = RS
    olddol0 = $0
    using_fw = (PROCINFO["FS"] == "FIELDWIDTHS")
    FS = ":"
    RS = "\n"

    pwcat = _pw_awklib "pwcat"
    while ((pwcat | getline) > 0) {
        _pw_byname[$1] = $0
        _pw_byuid[$3] = $0
        _pw_bycount[++_pw_total] = $0
    }
    close(pwcat)
    _pw_count = 0
    _pw_inited = 1
    FS = oldfs
    if (using_fw)
        FIELDWIDTHS = FIELDWIDTHS
    RS = oldrs
    $0 = olddol0
}

The BEGIN rule sets a private variable to the directory where pwcat is stored. Because it is used to help out an awk library routine, we have chosen to put it in /usr/local/libexec/awk; however, you might want it to be in a different directory on your system.

The function _pw_init keeps three copies of the user information in three associative arrays. The arrays are indexed by username (_pw_byname), by user ID number (_pw_byuid), and by order of occurrence (_pw_bycount). The variable _pw_inited is used for efficiency; _pw_init needs only to be called once.

Because this function uses getline to read information from pwcat, it first saves the values of FS, RS, and $0. It notes in the variable using_fw whether field splitting with FIELDWIDTHS is in effect or not. Doing so is necessary, since these functions could be called from anywhere within a user's program, and the user may have his or her own way of splitting records and fields.

The using_fw variable checks PROCINFO["FS"], which is "FIELDWIDTHS" if field splitting is being done with FIELDWIDTHS. This makes it possible to restore the correct field-splitting mechanism later. The test can only be true for gawk. It is false if using FS or on some other awk implementation.

The main part of the function uses a loop to read database lines, split the line into fields, and then store the line into each array as necessary. When the loop is done, _pw_init cleans up by closing the pipeline, setting _pw_inited to one, and restoring FS (and FIELDWIDTHS if necessary), RS, and $0. The use of _pw_count is explained shortly.

The getpwnam function takes a username as a string argument. If that user is in the database, it returns the appropriate line. Otherwise, it returns the null string:

function getpwnam(name)
{
    _pw_init()
    if (name in _pw_byname)
        return _pw_byname[name]
    return ""
}

Similarly, the getpwuid function takes a user ID number argument. If that user number is in the database, it returns the appropriate line. Otherwise, it returns the null string:

function getpwuid(uid)
{
    _pw_init()
    if (uid in _pw_byuid)
        return _pw_byuid[uid]
    return ""
}

The getpwent function simply steps through the database, one entry at a time. It uses _pw_count to track its current position in the _pw_bycount array:

function getpwent()
{
    _pw_init()
    if (_pw_count < _pw_total)
        return _pw_bycount[++_pw_count]
    return ""
}

The endpwent function resets _pw_count to zero, so that subsequent calls to getpwent start over again:

function endpwent()
{
    _pw_count = 0
}

A conscious design decision in this suite was made that each subroutine calls _pw_init to initialize the database arrays. The overhead of running a separate process to generate the user database, and the I/O to scan it, are only incurred if the user's main program actually calls one of these functions. If this library file is loaded along with a user's program, but none of the routines are ever called, then there is no extra runtime overhead. (The alternative is move the body of _pw_init into a BEGIN rule, which always runs pwcat. This simplifies the code but runs an extra process that may never be needed.)

In turn, calling _pw_init is not too expensive, because the _pw_inited variable keeps the program from reading the data more than once. If you are worried about squeezing every last cycle out of your awk program, the check of _pw_inited could be moved out of _pw_init and duplicated in all the other functions. In practice, this is not necessary, since most awk programs are I/O-bound, and it clutters up the code.

The id program in Printing out User Information, uses these functions.

Node:Group Functions, Previous:Passwd Functions, Up:Library Functions

Reading the Group Database

Much of the discussion presented in Reading the User Database, applies to the group database as well. Although there has traditionally been a well-known file (/etc/group) in a well-known format, the POSIX standard only provides a set of C library routines (<grp.h> and getgrent) for accessing the information. Even though this file may exist, it likely does not have complete information. Therefore, as with the user database, it is necessary to have a small C program that generates the group database as its output.

grcat, a C program that "cats" the group database, is as follows:

/*
 * grcat.c
 *
 * Generate a printable version of the group database
 */
#include <stdio.h>
#include <grp.h>

int
main(argc, argv)
int argc;
char **argv;
{
    struct group *g;
    int i;

    while ((g = getgrent()) != NULL) {
        printf("%s:%s:%d:", g->gr_name, g->gr_passwd,
                                            g->gr_gid);
        for (i = 0; g->gr_mem[i] != NULL; i++) {
            printf("%s", g->gr_mem[i]);
            if (g->gr_mem[i+1] != NULL)
                putchar(',');
        }
        putchar('\n');
    }
    endgrent();
    exit(0);
}

Each line in the group database represents one group. The fields are separated with colons and represent the following information:

Group name | The group's name.
Group password | The group's encrypted password. In practice, this field is never used; it is usually empty or set to *.
Group-ID | The group's numeric group ID number; this number should be unique within the file.
Group member list | A comma-separated list of usernames. These users are members of the group. Modern Unix systems allow users to be members of several groups simultaneously. If your system does, then there are elements "group1" through "groupN" in PROCINFO for those group ID numbers. (Note that PROCINFO is a gawk extension; see Built-in Variables.)

Here is what running grcat might produce:

$ grcat
-| wheel:*:0:arnold
-| nogroup:*:65534:
-| daemon:*:1:
-| kmem:*:2:
-| staff:*:10:arnold,miriam,andy
-| other:*:20:
...

Here are the functions for obtaining information from the group database. There are several, modeled after the C library functions of the same names:

# group.awk --- functions for dealing with the group file
BEGIN    \
{
    # Change to suit your system
    _gr_awklib = "/usr/local/libexec/awk/"
}

function _gr_init(    oldfs, oldrs, olddol0, grcat,
                             using_fw, n, a, i)
{
    if (_gr_inited)
        return

    oldfs = FS
    oldrs = RS
    olddol0 = $0
    using_fw = (PROCINFO["FS"] == "FIELDWIDTHS")
    FS = ":"
    RS = "\n"

    grcat = _gr_awklib "grcat"
    while ((grcat | getline) > 0) {
        if ($1 in _gr_byname)
            _gr_byname[$1] = _gr_byname[$1] "," $4
        else
            _gr_byname[$1] = $0
        if ($3 in _gr_bygid)
            _gr_bygid[$3] = _gr_bygid[$3] "," $4
        else
            _gr_bygid[$3] = $0

        n = split($4, a, "[ \t]*,[ \t]*")
        for (i = 1; i <= n; i++)
            if (a[i] in _gr_groupsbyuser)
                _gr_groupsbyuser[a[i]] = \
                    _gr_groupsbyuser[a[i]] " " $1
            else
                _gr_groupsbyuser[a[i]] = $1

        _gr_bycount[++_gr_count] = $0
    }
    close(grcat)
    _gr_count = 0
    _gr_inited++
    FS = oldfs
    if (using_fw)
        FIELDWIDTHS = FIELDWIDTHS
    RS = oldrs
    $0 = olddol0
}

The BEGIN rule sets a private variable to the directory where grcat is stored. Because it is used to help out an awk library routine, we have chosen to put it in /usr/local/libexec/awk. You might want it to be in a different directory on your system.

These routines follow the same general outline as the user database routines (see Reading the User Database). The _gr_inited variable is used to ensure that the database is scanned no more than once. The _gr_init function first saves FS, FIELDWIDTHS, RS, and $0, and then sets FS and RS to the correct values for scanning the group information.

The group information is stored is several associative arrays. The arrays are indexed by group name (_gr_byname), by group ID number (_gr_bygid), and by position in the database (_gr_bycount). There is an additional array indexed by username (_gr_groupsbyuser), which is a space-separated list of groups to which each user belongs.

Unlike the user database, it is possible to have multiple records in the database for the same group. This is common when a group has a large number of members. A pair of such entries might look like the following:

tvpeople:*:101:johnny,jay,arsenio
tvpeople:*:101:david,conan,tom,joan

For this reason, _gr_init looks to see if a group name or group ID number is already seen. If it is, then the usernames are simply concatenated onto the previous list of users. (There is actually a subtle problem with the code just presented. Suppose that the first time there were no names. This code adds the names with a leading comma. It also doesn't check that there is a $4.)

Finally, _gr_init closes the pipeline to grcat, restores FS (and FIELDWIDTHS if necessary), RS, and $0, initializes _gr_count to zero (it is used later), and makes _gr_inited nonzero.

The getgrnam function takes a group name as its argument, and if that group exists, it is returned. Otherwise, getgrnam returns the null string:

function getgrnam(group)
{
    _gr_init()
    if (group in _gr_byname)
        return _gr_byname[group]
    return ""
}

The getgrgid function is similar, it takes a numeric group ID and looks up the information associated with that group ID:

function getgrgid(gid)
{
    _gr_init()
    if (gid in _gr_bygid)
        return _gr_bygid[gid]
    return ""
}

The getgruser function does not have a C counterpart. It takes a username and returns the list of groups that have the user as a member:

function getgruser(user)
{
    _gr_init()
    if (user in _gr_groupsbyuser)
        return _gr_groupsbyuser[user]
    return ""
}

The getgrent function steps through the database one entry at a time. It uses _gr_count to track its position in the list:

function getgrent()
{
    _gr_init()
    if (++_gr_count in _gr_bycount)
        return _gr_bycount[_gr_count]
    return ""
}

The endgrent function resets _gr_count to zero so that getgrent can start over again:

function endgrent()
{
    _gr_count = 0
}

As with the user database routines, each function calls _gr_init to initialize the arrays. Doing so only incurs the extra overhead of running grcat if these functions are used (as opposed to moving the body of _gr_init into a BEGIN rule).

Most of the work is in scanning the database and building the various associative arrays. The functions that the user calls are themselves very simple, relying on awk's associative arrays to do work.

The id program in Printing out User Information, uses these functions.

Node:Sample Programs, Next:Language History, Previous:Library Functions, Up:Top

Practical awk Programs

A Library of awk Functions, presents the idea that reading programs in a language contributes to learning that language. This chapter continues that theme, presenting a potpourri of awk programs for your reading enjoyment. There are three sections. The first describes how to run the programs presented in this chapter.

The second presents awk versions of several common POSIX utilities. These are programs that you are hopefully already familiar with, and therefore, whose problems are understood. By reimplementing these programs in awk, you can focus on the awk-related aspects of solving the programming problem.

The third is a grab bag of interesting programs. These solve a number of different data-manipulation and management problems. Many of the programs are short, which emphasizes awk's ability to do a lot in just a few lines of code.

Many of these programs use the library functions presented in A Library of awk Functions.

  • Running Examples: How to run these examples.
  • Clones: Clones of common utilities.
  • Miscellaneous Programs: Some interesting awk programs.

Node:Running Examples, Next:Clones, Previous:Sample Programs, Up:Sample Programs

Running the Example Programs

To run a given program, you would typically do something like this:

awk -f program -- options files

Here, program is the name of the awk program (such as cut.awk), options are any command-line options for the program that start with a -, and files are the actual data files.

If your system supports the #! executable interpreter mechanism (see Executable awk Programs), you can instead run your program directly:

cut.awk -c1-8 myfiles > results

If your awk is not gawk, you may instead need to use this:

cut.awk -- -c1-8 myfiles > results

Node:Clones, Next:Miscellaneous Programs, Previous:Running Examples, Up:Sample Programs

Reinventing Wheels for Fun and Profit

This section presents a number of POSIX utilities that are implemented in awk. Reinventing these programs in awk is often enjoyable, because the algorithms can be very clearly expressed, and the code is usually very concise and simple. This is true because awk does so much for you.

It should be noted that these programs are not necessarily intended to replace the installed versions on your system. Instead, their purpose is to illustrate awk language programming for "real world" tasks.

The programs are presented in alphabetical order.

  • Cut Program: The cut utility.
  • Egrep Program: The egrep utility.
  • Id Program: The id utility.
  • Split Program: The split utility.
  • Tee Program: The tee utility.
  • Uniq Program: The uniq utility.
  • Wc Program: The wc utility.

Node:Cut Program, Next:Egrep Program, Previous:Clones, Up:Clones

Cutting out Fields and Columns

The cut utility selects, or "cuts," characters or fields from its standard input and sends them to its standard output. Fields are separated by tabs by default, but you may supply a command-line option to change the field delimiter (i.e., the field-separator character). cut's definition of fields is less general than awk's.

A common use of cut might be to pull out just the login name of logged-on users from the output of who. For example, the following pipeline generates a sorted, unique list of the logged-on users:

who | cut -c1-8 | sort | uniq

The options for cut are:

-c list
Use list as the list of characters to cut out. Items within the list may be separated by commas, and ranges of characters can be separated with dashes. The list 1-8,15,22-35 specifies characters 1 through 8, 15, and 22 through 35.
-f list
Use list as the list of fields to cut out.
-d delim
Use delim as the field-separator character instead of the tab character.
-s
Suppress printing of lines that do not contain the field delimiter.

The awk implementation of cut uses the getopt library function (see Processing Command-Line Options) and the join library function (see Merging an Array into a String).

The program begins with a comment describing the options, the library functions needed, and a usage function that prints out a usage message and exits. usage is called if invalid arguments are supplied:

# cut.awk --- implement cut in awk
# Options:
#    -f list     Cut fields
#    -d c        Field delimiter character
#    -c list     Cut characters
#
#    -s          Suppress lines without the delimiter
#
# Requires getopt and join library functions

function usage(    e1, e2)
{
    e1 = "usage: cut [-f list] [-d c] [-s] [files...]"
    e2 = "usage: cut [-c list] [files...]"
    print e1 > "/dev/stderr"
    print e2 > "/dev/stderr"
    exit 1
}

The variables e1 and e2 are used so that the function fits nicely on the page. screen.

Next comes a BEGIN rule that parses the command-line options. It sets FS to a single TAB character, because that is cut's default field separator. The output field separator is also set to be the same as the input field separator. Then getopt is used to step through the command-line options. Exactly one of the variables by_fields or by_chars is set to true, to indicate that processing should be done by fields or by characters, respectively. When cutting by characters, the output field separator is set to the null string:

BEGIN    \
{
    FS = "\t"    # default
    OFS = FS
    while ((c = getopt(ARGC, ARGV, "sf:c:d:")) != -1) {
        if (c == "f") {
            by_fields = 1
            fieldlist = Optarg
        } else if (c == "c") {
            by_chars = 1
            fieldlist = Optarg
            OFS = ""
        } else if (c == "d") {
            if (length(Optarg) > 1) {
                printf("Using first character of %s" \
                " for delimiter\n", Optarg) > "/dev/stderr"
                Optarg = substr(Optarg, 1, 1)
            }
            FS = Optarg
            OFS = FS
            if (FS == " ")    # defeat awk semantics
                FS = "[ ]"
        } else if (c == "s")
            suppress++
        else
            usage()
    }

    for (i = 1; i < Optind; i++)
        ARGV[i] = ""

Special care is taken when the field delimiter is a space. Using a single space (" ") for the value of FS is incorrect--awk would separate fields with runs of spaces, tabs, and/or newlines, and we want them to be separated with individual spaces. Also, note that after getopt is through, we have to clear out all the elements of ARGV from 1 to Optind, so that awk does not try to process the command-line options as file names.

After dealing with the command-line options, the program verifies that the options make sense. Only one or the other of -c and -f should be used, and both require a field list. Then the program calls either set_fieldlist or set_charlist to pull apart the list of fields or characters:

    if (by_fields && by_chars)
        usage()

    if (by_fields == 0 && by_chars == 0)
        by_fields = 1    # default

    if (fieldlist == "") {
        print "cut: needs list for -c or -f" > "/dev/stderr"
        exit 1
    }

    if (by_fields)
        set_fieldlist()
    else
        set_charlist()
}

set_fieldlist is used to split the field list apart at the commas and into an array. Then, for each element of the array, it looks to see if it is actually a range, and if so, splits it apart. The range is verified to make sure the first number is smaller than the second. Each number in the list is added to the flist array, which simply lists the fields that will be printed. Normal field splitting is used. The program lets awk handle the job of doing the field splitting:

function set_fieldlist(        n, m, i, j, k, f, g)
{
    n = split(fieldlist, f, ",")
    j = 1    # index in flist
    for (i = 1; i <= n; i++) {
        if (index(f[i], "-") != 0) { # a range
            m = split(f[i], g, "-")
            if (m != 2 || g[1] >= g[2]) {
                printf("bad field list: %s\n",
                                  f[i]) > "/dev/stderr"
                exit 1
            }
            for (k = g[1]; k <= g[2]; k++)
                flist[j++] = k
        } else
            flist[j++] = f[i]
    }
    nfields = j - 1
}

The set_charlist function is more complicated than set_fieldlist. The idea here is to use gawk's FIELDWIDTHS variable (see Reading Fixed-Width Data), which describes constant-width input. When using a character list, that is exactly what we have.

Setting up FIELDWIDTHS is more complicated than simply listing the fields that need to be printed. We have to keep track of the fields to print and also the intervening characters that have to be skipped. For example, suppose you wanted characters 1 through 8, 15, and 22 through 35. You would use -c 1-8,15,22-35. The necessary value for FIELDWIDTHS is "8 6 1 6 14". This yields five fields, and the fields to print are $1, $3, and $5. The intermediate fields are filler, which is stuff in between the desired data. flist lists the fields to print, and t tracks the complete field list, including filler fields:

function set_charlist(    field, i, j, f, g, t,
                          filler, last, len)
{
    field = 1   # count total fields
    n = split(fieldlist, f, ",")
    j = 1       # index in flist
    for (i = 1; i <= n; i++) {
        if (index(f[i], "-") != 0) { # range
            m = split(f[i], g, "-")
            if (m != 2 || g[1] >= g[2]) {
                printf("bad character list: %s\n",
                               f[i]) > "/dev/stderr"
                exit 1
            }
            len = g[2] - g[1] + 1
            if (g[1] > 1)  # compute length of filler
                filler = g[1] - last - 1
            else
                filler = 0
            if (filler)
                t[field++] = filler
            t[field++] = len  # length of field
            last = g[2]
            flist[j++] = field - 1
        } else {
            if (f[i] > 1)
                filler = f[i] - last - 1
            else
                filler = 0
            if (filler)
                t[field++] = filler
            t[field++] = 1
            last = f[i]
            flist[j++] = field - 1
        }
    }
    FIELDWIDTHS = join(t, 1, field - 1)
    nfields = j - 1
}

Next is the rule that actually processes the data. If the -s option is given, then suppress is true. The first if statement makes sure that the input record does have the field separator. If cut is processing fields, suppress is true, and the field separator character is not in the record, then the record is skipped.

If the record is valid, then gawk has split the data into fields, either using the character in FS or using fixed-length fields and FIELDWIDTHS. The loop goes through the list of fields that should be printed. The corresponding field is printed if it contains data. If the next field also has data, then the separator character is written out between the fields:

{
    if (by_fields && suppress && index($0, FS) != 0)
        next

    for (i = 1; i <= nfields; i++) {
        if ($flist[i] != "") {
            printf "%s", $flist[i]
            if (i < nfields && $flist[i+1] != "")
                printf "%s", OFS
        }
    }
    print ""
}

This version of cut relies on gawk's FIELDWIDTHS variable to do the character-based cutting. While it is possible in other awk implementations to use substr (see String Manipulation Functions), it is also extremely painful. The FIELDWIDTHS variable supplies an elegant solution to the problem of picking the input line apart by characters.

Node:Egrep Program, Next:Id Program, Previous:Cut Program, Up:Clones

Searching for Regular Expressions in Files

The egrep utility searches files for patterns. It uses regular expressions that are almost identical to those available in awk (see Regular Expressions). It is used in the following manner:

egrep [ options ] 'pattern' files ...

The pattern is a regular expression. In typical usage, the regular expression is quoted to prevent the shell from expanding any of the special characters as file name wildcards. Normally, egrep prints the lines that matched. If multiple file names are provided on the command line, each output line is preceded by the name of the file and a colon.

The options to egrep are as follows:

-c
Print out a count of the lines that matched the pattern, instead of the lines themselves.
-s
Be silent. No output is produced and the exit value indicates whether the pattern was matched.
-v
Invert the sense of the test. egrep prints the lines that do not match the pattern and exits successfully if the pattern is not matched.
-i
Ignore case distinctions in both the pattern and the input data.
-l
Only print (list) the names of the files that matched, not the lines that matched.
-e pattern
Use pattern as the regexp to match. The purpose of the -e option is to allow patterns that start with a -.

This version uses the getopt library function (see Processing Command-Line Options) and the file transition library program (see Noting Data File Boundaries).

The program begins with a descriptive comment and then a BEGIN rule that processes the command-line arguments with getopt. The -i (ignore case) option is particularly easy with gawk; we just use the IGNORECASE built-in variable (see Built-in Variables):

# egrep.awk --- simulate egrep in awk
# Options:
#    -c    count of lines
#    -s    silent - use exit value
#    -v    invert test, success if no match
#    -i    ignore case
#    -l    print filenames only
#    -e    argument is pattern
#
# Requires getopt and file transition library functions

BEGIN {
    while ((c = getopt(ARGC, ARGV, "ce:svil")) != -1) {
        if (c == "c")
            count_only++
        else if (c == "s")
            no_print++
        else if (c == "v")
            invert++
        else if (c == "i")
            IGNORECASE = 1
        else if (c == "l")
            filenames_only++
        else if (c == "e")
            pattern = Optarg
        else
            usage()
    }

Next comes the code that handles the egrep-specific behavior. If no pattern is supplied with -e, the first nonoption on the command line is used. The awk command-line arguments up to ARGV[Optind] are cleared, so that awk won't try to process them as files. If no files are specified, the standard input is used, and if multiple files are specified, we make sure to note this so that the file names can precede the matched lines in the output:

    if (pattern == "")
        pattern = ARGV[Optind++]

    for (i = 1; i < Optind; i++)
        ARGV[i] = ""
    if (Optind >= ARGC) {
        ARGV[1] = "-"
        ARGC = 2
    } else if (ARGC - Optind > 1)
        do_filenames++

#    if (IGNORECASE)
#        pattern = tolower(pattern)
}

The last two lines are commented out, since they are not needed in gawk. They should be uncommented if you have to use another version of awk.

The next set of lines should be uncommented if you are not using gawk. This rule translates all the characters in the input line into lowercase if the -i option is specified.58 The rule is commented out since it is not necessary with gawk:

#{
#    if (IGNORECASE)
#        $0 = tolower($0)
#}

The beginfile function is called by the rule in ftrans.awk when each new file is processed. In this case, it is very simple; all it does is initialize a variable fcount to zero. fcount tracks how many lines in the current file matched the pattern (naming the parameter junk shows we know that beginfile is called with a parameter, but that we're not interested in its value):

function beginfile(junk)
{
    fcount = 0
}

The endfile function is called after each file has been processed. It affects the output only when the user wants a count of the number of lines that matched. no_print is true only if the exit status is desired. count_only is true if line counts are desired. egrep therefore only prints line counts if printing and counting are enabled. The output format must be adjusted depending upon the number of files to process. Finally, fcount is added to total, so that we know the total number of lines that matched the pattern:

function endfile(file)
{
    if (! no_print && count_only)
        if (do_filenames)
            print file ":" fcount
        else
            print fcount

    total += fcount
}

The following rule does most of the work of matching lines. The variable matches is true if the line matched the pattern. If the user wants lines that did not match, the sense of matches is inverted using the ! operator. fcount is incremented with the value of matches, which is either one or zero, depending upon a successful or unsuccessful match. If the line does not match, the next statement just moves on to the next record.

A number of additional tests are made, but they are only done if we are not counting lines. First, if the user only wants exit status (no_print is true), then it is enough to know that one line in this file matched, and we can skip on to the next file with nextfile. Similarly, if we are only printing file names, we can print the file name, and then skip to the next file with nextfile. Finally, each line is printed, with a leading file name and colon if necessary:

{
    matches = ($0 ~ pattern)
    if (invert)
        matches = ! matches

    fcount += matches    # 1 or 0

    if (! matches)
        next

    if (! count_only) {
        if (no_print)
            nextfile

        if (filenames_only) {
            print FILENAME
            nextfile
        }

        if (do_filenames)
            print FILENAME ":" $0
        else
            print
    }
}

The END rule takes care of producing the correct exit status. If there are no matches, the exit status is one; otherwise it is zero:

END    \
{
    if (total == 0)
        exit 1
    exit 0
}

The usage function prints a usage message in case of invalid options, and then exits:

function usage(    e)
{
    e = "Usage: egrep [-csvil] [-e pat] [files ...]"
    e = e "\n\tegrep [-csvil] pat [files ...]"
    print e > "/dev/stderr"
    exit 1
}

The variable e is used so that the function fits nicely on the printed page.

Just a note on programming style: you may have noticed that the END rule uses backslash continuation, with the open brace on a line by itself. This is so that it more closely resembles the way functions are written. Many of the examples in this chapter use this style. You can decide for yourself if you like writing your BEGIN and END rules this way or not.

Node:Id Program, Next:Split Program, Previous:Egrep Program, Up:Clones

Printing out User Information

The id utility lists a user's real and effective user ID numbers, real and effective group ID numbers, and the user's group set, if any. id only prints the effective user ID and group ID if they are different from the real ones. If possible, id also supplies the corresponding user and group names. The output might look like this:

$ id
-| uid=2076(arnold) gid=10(staff) groups=10(staff),4(tty)

This information is part of what is provided by gawk's PROCINFO array (see Built-in Variables). However, the id utility provides a more palatable output than just individual numbers.

Here is a simple version of id written in awk. It uses the user database library functions (see Reading the User Database) and the group database library functions (see Reading the Group Database):

The program is fairly straightforward. All the work is done in the BEGIN rule. The user and group ID numbers are obtained from PROCINFO. The code is repetitive. The entry in the user database for the real user ID number is split into parts at the :. The name is the first field. Similar code is used for the effective user ID number and the group numbers:

# id.awk --- implement id in awk
#
# Requires user and group library functions
# output is:
# uid=12(foo) euid=34(bar) gid=3(baz) \
#             egid=5(blat) groups=9(nine),2(two),1(one)

BEGIN    \
{
    uid = PROCINFO["uid"]
    euid = PROCINFO["euid"]
    gid = PROCINFO["gid"]
    egid = PROCINFO["egid"]

    printf("uid=%d", uid)
    pw = getpwuid(uid)
    if (pw != "") {
        split(pw, a, ":")
        printf("(%s)", a[1])
    }

    if (euid != uid) {
        printf(" euid=%d", euid)
        pw = getpwuid(euid)
        if (pw != "") {
            split(pw, a, ":")
            printf("(%s)", a[1])
        }
    }

    printf(" gid=%d", gid)
    pw = getgrgid(gid)
    if (pw != "") {
        split(pw, a, ":")
        printf("(%s)", a[1])
    }

    if (egid != gid) {
        printf(" egid=%d", egid)
        pw = getgrgid(egid)
        if (pw != "") {
            split(pw, a, ":")
            printf("(%s)", a[1])
        }
    }

    for (i = 1; ("group" i) in PROCINFO; i++) {
        if (i == 1)
            printf(" groups=")
        group = PROCINFO["group" i]
        printf("%d", group)
        pw = getgrgid(group)
        if (pw != "") {
            split(pw, a, ":")
            printf("(%s)", a[1])
        }
        if (("group" (i+1)) in PROCINFO)
            printf(",")
    }

    print ""
}

The test in the for loop is worth noting. Any supplementary groups in the PROCINFO array have the indices "group1" through "groupN" for some N, i.e., the total number of supplementary groups. However, we don't know in advance how many of these groups there are.

This loop works by starting at one, concatenating the value with "group", and then using in to see if that value is in the array. Eventually, i is incremented past the last group in the array and the loop exits.

The loop is also correct if there are no supplementary groups; then the condition is false the first time it's tested, and the loop body never executes.

Node:Split Program, Next:Tee Program, Previous:Id Program, Up:Clones

Splitting a Large File into Pieces

The split program splits large text files into smaller pieces. Usage is as follows:

split [-count] file [ prefix ]

By default, the output files are named xaa, xab, and so on. Each file has 1000 lines in it, with the likely exception of the last file. To change the number of lines in each file, supply a number on the command line preceded with a minus; e.g., -500 for files with 500 lines in them instead of 1000. To change the name of the output files to something like myfileaa, myfileab, and so on, supply an additional argument that specifies the file name prefix.

Here is a version of split in awk. It uses the ord and chr functions presented in Translating Between Characters and Numbers.

The program first sets its defaults, and then tests to make sure there are not too many arguments. It then looks at each argument in turn. The first argument could be a minus sign followed by a number. If it is, this happens to look like a negative number, so it is made positive, and that is the count of lines. The data file name is skipped over and the final argument is used as the prefix for the output file names:

# split.awk --- do split in awk
#
# Requires ord and chr library functions
# usage: split [-num] [file] [outname]

BEGIN {
    outfile = "x"    # default
    count = 1000
    if (ARGC > 4)
        usage()

    i = 1
    if (ARGV[i] ~ /^-[0-9]+$/) {
        count = -ARGV[i]
        ARGV[i] = ""
        i++
    }
    # test argv in case reading from stdin instead of file
    if (i in ARGV)
        i++    # skip data file name
    if (i in ARGV) {
        outfile = ARGV[i]
        ARGV[i] = ""
    }

    s1 = s2 = "a"
    out = (outfile s1 s2)
}

The next rule does most of the work. tcount (temporary count) tracks how many lines have been printed to the output file so far. If it is greater than count, it is time to close the current file and start a new one. s1 and s2 track the current suffixes for the file name. If they are both z, the file is just too big. Otherwise, s1 moves to the next letter in the alphabet and s2 starts over again at a:

{
    if (++tcount > count) {
        close(out)
        if (s2 == "z") {
            if (s1 == "z") {
                printf("split: %s is too large to split\n",
                       FILENAME) > "/dev/stderr"
                exit 1
            }
            s1 = chr(ord(s1) + 1)
            s2 = "a"
        }
        else
            s2 = chr(ord(s2) + 1)
        out = (outfile s1 s2)
        tcount = 1
    }
    print > out
}

The usage function simply prints an error message and exits:

function usage(   e)
{
    e = "usage: split [-num] [file] [outname]"
    print e > "/dev/stderr"
    exit 1
}

The variable e is used so that the function fits nicely on the page.

This program is a bit sloppy; it relies on awk to automatically close the last file instead of doing it in an END rule. It also assumes that letters are contiguous in the character set, which isn't true for EBCDIC systems.

Node:Tee Program, Next:Uniq Program, Previous:Split Program, Up:Clones

Duplicating Output into Multiple Files

The tee program is known as a "pipe fitting." tee copies its standard input to its standard output and also duplicates it to the files named on the command line. Its usage is as follows:

tee [-a] file ...

The -a option tells tee to append to the named files, instead of truncating them and starting over.

The BEGIN rule first makes a copy of all the command-line arguments into an array named copy. ARGV[0] is not copied, since it is not needed. tee cannot use ARGV directly, since awk attempts to process each file name in ARGV as input data.

If the first argument is -a, then the flag variable append is set to true, and both ARGV[1] and copy[1] are deleted. If ARGC is less than two, then no file names were supplied and tee prints a usage message and exits. Finally, awk is forced to read the standard input by setting ARGV[1] to "-" and ARGC to two:

# tee.awk --- tee in awk
BEGIN    \
{
    for (i = 1; i < ARGC; i++)
        copy[i] = ARGV[i]

    if (ARGV[1] == "-a") {
        append = 1
        delete ARGV[1]
        delete copy[1]
        ARGC--
    }
    if (ARGC < 2) {
        print "usage: tee [-a] file ..." > "/dev/stderr"
        exit 1
    }
    ARGV[1] = "-"
    ARGC = 2
}

The single rule does all the work. Since there is no pattern, it is executed for each line of input. The body of the rule simply prints the line into each file on the command line, and then to the standard output:

{
    # moving the if outside the loop makes it run faster
    if (append)
        for (i in copy)
            print >> copy[i]
    else
        for (i in copy)
            print > copy[i]
    print
}

It is also possible to write the loop this way:

for (i in copy)
    if (append)
        print >> copy[i]
    else
        print > copy[i]

This is more concise but it is also less efficient. The if is tested for each record and for each output file. By duplicating the loop body, the if is only tested once for each input record. If there are N input records and M output files, the first method only executes N if statements, while the second executes N*M if statements.

Finally, the END rule cleans up by closing all the output files:

END    \
{
    for (i in copy)
        close(copy[i])
}

Node:Uniq Program, Next:Wc Program, Previous:Tee Program, Up:Clones

Printing Nonduplicated Lines of Text

The uniq utility reads sorted lines of data on its standard input, and by default removes duplicate lines. In other words, it only prints unique lines--hence the name. uniq has a number of options. The usage is as follows:

uniq [-udc [-n]] [+n] [ input file [ output file ]]

The options for uniq are:

-d
Pnly print only repeated lines.
-u
Print only nonrepeated lines.
-c
Count lines. This option overrides -d and -u. Both repeated and nonrepeated lines are counted.
-n
Skip n fields before comparing lines. The definition of fields is similar to awk's default: nonwhitespace characters separated by runs of spaces and/or tabs.
+n
Skip n characters before comparing lines. Any fields specified with -n are skipped first.
input file
Data is read from the input file named on the command line, instead of from the standard input.
output file
The generated output is sent to the named output file, instead of to the standard output.

Normally uniq behaves as if both the -d and -u options are provided.

uniq uses the getopt library function (see Processing Command-Line Options) and the join library function (see Merging an Array into a String).

The program begins with a usage function and then a brief outline of the options and their meanings in a comment. The BEGIN rule deals with the command-line arguments and options. It uses a trick to get getopt to handle options of the form -25, treating such an option as the option letter 2 with an argument of 5. If indeed two or more digits are supplied (Optarg looks like a number), Optarg is concatenated with the option digit and then the result is added to zero to make it into a number. If there is only one digit in the option, then Optarg is not needed. In this case, Optind must be decremented so that getopt processes it next time. This code is admittedly a bit tricky.

If no options are supplied, then the default is taken, to print both repeated and nonrepeated lines. The output file, if provided, is assigned to outputfile. Early on, outputfile is initialized to the standard output, /dev/stdout:

# uniq.awk --- do uniq in awk
#
# Requires getopt and join library functions
function usage(    e)
{
    e = "Usage: uniq [-udc [-n]] [+n] [ in [ out ]]"
    print e > "/dev/stderr"
    exit 1
}

# -c    count lines. overrides -d and -u
# -d    only repeated lines
# -u    only non-repeated lines
# -n    skip n fields
# +n    skip n characters, skip fields first

BEGIN   \
{
    count = 1
    outputfile = "/dev/stdout"
    opts = "udc0:1:2:3:4:5:6:7:8:9:"
    while ((c = getopt(ARGC, ARGV, opts)) != -1) {
        if (c == "u")
            non_repeated_only++
        else if (c == "d")
            repeated_only++
        else if (c == "c")
            do_count++
        else if (index("0123456789", c) != 0) {
            # getopt requires args to options
            # this messes us up for things like -5
            if (Optarg ~ /^[0-9]+$/)
                fcount = (c Optarg) + 0
            else {
                fcount = c + 0
                Optind--
            }
        } else
            usage()
    }

    if (ARGV[Optind] ~ /^\+[0-9]+$/) {
        charcount = substr(ARGV[Optind], 2) + 0
        Optind++
    }

    for (i = 1; i < Optind; i++)
        ARGV[i] = ""

    if (repeated_only == 0 && non_repeated_only == 0)
        repeated_only = non_repeated_only = 1

    if (ARGC - Optind == 2) {
        outputfile = ARGV[ARGC - 1]
        ARGV[ARGC - 1] = ""
    }
}

The following function, are_equal, compares the current line, $0, to the previous line, last. It handles skipping fields and characters. If no field count and no character count are specified, are_equal simply returns one or zero depending upon the result of a simple string comparison of last and $0. Otherwise, things get more complicated. If fields have to be skipped, each line is broken into an array using split (see String Manipulation Functions); the desired fields are then joined back into a line using join. The joined lines are stored in clast and cline. If no fields are skipped, clast and cline are set to last and $0, respectively. Finally, if characters are skipped, substr is used to strip off the leading charcount characters in clast and cline. The two strings are then compared and are_equal returns the result:

function are_equal(    n, m, clast, cline, alast, aline)
{
    if (fcount == 0 && charcount == 0)
        return (last == $0)

    if (fcount > 0) {
        n = split(last, alast)
        m = split($0, aline)
        clast = join(alast, fcount+1, n)
        cline = join(aline, fcount+1, m)
    } else {
        clast = last
        cline = $0
    }
    if (charcount) {
        clast = substr(clast, charcount + 1)
        cline = substr(cline, charcount + 1)
    }

    return (clast == cline)
}

The following two rules are the body of the program. The first one is executed only for the very first line of data. It sets last equal to $0, so that subsequent lines of text have something to be compared to.

The second rule does the work. The variable equal is one or zero, depending upon the results of are_equal's comparison. If uniq is counting repeated lines, and the lines are equal, then it increments the count variable. Otherwise, it prints the line and resets count, since the two lines are not equal.

If uniq is not counting, and if the lines are equal, count is incremented. Nothing is printed, since the point is to remove duplicates. Otherwise, if uniq is counting repeated lines and more than one line is seen, or if uniq is counting nonrepeated lines and only one line is seen, then the line is printed, and count is reset.

Finally, similar logic is used in the END rule to print the final line of input data:

NR == 1 {
    last = $0
    next
}

{
    equal = are_equal()

    if (do_count) {    # overrides -d and -u
        if (equal)
            count++
        else {
            printf("%4d %s\n", count, last) > outputfile
            last = $0
            count = 1    # reset
        }
        next
    }

    if (equal)
        count++
    else {
        if ((repeated_only && count > 1) ||
            (non_repeated_only && count == 1))
                print last > outputfile
        last = $0
        count = 1
    }
}

END {
    if (do_count)
        printf("%4d %s\n", count, last) > outputfile
    else if ((repeated_only && count > 1) ||
            (non_repeated_only && count == 1))
        print last > outputfile
}

Node:Wc Program, Previous:Uniq Program, Up:Clones

Counting Things

The wc (word count) utility counts lines, words, and characters in one or more input files. Its usage is as follows:

wc [-lwc] [ files ... ]

If no files are specified on the command line, wc reads its standard input. If there are multiple files, it also prints total counts for all the files. The options and their meanings are shown in the following list:

-l
Count only lines.
-w
Count only words. A "word" is a contiguous sequence of nonwhitespace characters, separated by spaces and/or tabs. Luckily, this is the normal way awk separates fields in its input data.
-c
Count only characters.

Implementing wc in awk is particularly elegant, since awk does a lot of the work for us; it splits lines into words (i.e., fields) and counts them, it counts lines (i.e., records), and it can easily tell us how long a line is.

This uses the getopt library function (see Processing Command-Line Options) and the file-transition functions (see Noting Data File Boundaries).

This version has one notable difference from traditional versions of wc: it always prints the counts in the order lines, words, and characters. Traditional versions note the order of the -l, -w, and -c options on the command line, and print the counts in that order.

The BEGIN rule does the argument processing. The variable print_total is true if more than one file is named on the command line:

# wc.awk --- count lines, words, characters

# Options:
#    -l    only count lines
#    -w    only count words
#    -c    only count characters
#
# Default is to count lines, words, characters
#
# Requires getopt and file transition library functions

BEGIN {
    # let getopt print a message about
    # invalid options. we ignore them
    while ((c = getopt(ARGC, ARGV, "lwc")) != -1) {
        if (c == "l")
            do_lines = 1
        else if (c == "w")
            do_words = 1
        else if (c == "c")
            do_chars = 1
    }
    for (i = 1; i < Optind; i++)
        ARGV[i] = ""

    # if no options, do all
    if (! do_lines && ! do_words && ! do_chars)
        do_lines = do_words = do_chars = 1

    print_total = (ARGC - i > 2)
}

The beginfile function is simple; it just resets the counts of lines, words, and characters to zero, and saves the current file name in fname:

function beginfile(file)
{
    chars = lines = words = 0
    fname = FILENAME
}

The endfile function adds the current file's numbers to the running totals of lines, words, and characters.59 It then prints out those numbers for the file that was just read. It relies on beginfile to reset the numbers for the following data file:

function endfile(file)
{
    tchars += chars
    tlines += lines
    twords += words
    if (do_lines)
        printf "\t%d", lines
    if (do_words)
        printf "\t%d", words
    if (do_chars)
        printf "\t%d", chars
    printf "\t%s\n", fname
}

There is one rule that is executed for each line. It adds the length of the record, plus one, to chars. Adding one plus the record length is needed because the newline character separating records (the value of RS) is not part of the record itself, and thus not included in its length. Next, lines is incremented for each line read, and words is incremented by the value of NF, which is the number of "words" on this line:

# do per line
{
    chars += length($0) + 1    # get newline
    lines++
    words += NF
}

Finally, the END rule simply prints the totals for all the files:

END {
    if (print_total) {
        if (do_lines)
            printf "\t%d", tlines
        if (do_words)
            printf "\t%d", twords
        if (do_chars)
            printf "\t%d", tchars
        print "\ttotal"
    }
}

Node:Miscellaneous Programs, Previous:Clones, Up:Sample Programs

A Grab Bag of awk Programs

This section is a large "grab bag" of miscellaneous programs. We hope you find them both interesting and enjoyable.

  • Dupword Program: Finding duplicated words in a document.
  • Alarm Program: An alarm clock.
  • Translate Program: A program similar to the tr utility.
  • Labels Program: Printing mailing labels.
  • Word Sorting: A program to produce a word usage count.
  • History Sorting: Eliminating duplicate entries from a history file.
  • Extract Program: Pulling out programs from Texinfo source files.
  • Simple Sed: A Simple Stream Editor.
  • Igawk Program: A wrapper for awk that includes files.

Node:Dupword Program, Next:Alarm Program, Previous:Miscellaneous Programs, Up:Miscellaneous Programs

Finding Duplicated Words in a Document

A common error when writing large amounts of prose is to accidentally duplicate words. Typically you will see this in text as something like "the the program does the following..." When the text is online, often the duplicated words occur at the end of one line and the beginning of another, making them very difficult to spot.

This program, dupword.awk, scans through a file one line at a time and looks for adjacent occurrences of the same word. It also saves the last word on a line (in the variable prev) for comparison with the first word on the next line.

The first two statements make sure that the line is all lowercase, so that, for example, "The" and "the" compare equal to each other. The next statement replaces nonalphanumeric and nonwhitespace characters with spaces, so that punctuation does not affect the comparison either. The characters are replaced with spaces so that formatting controls don't create nonsense words (e.g., the Texinfo @code{NF} becomes codeNF if punctuation is simply deleted). The record is then resplit into fields, yielding just the actual words on the line, and ensuring that there are no empty fields.

If there are no fields left after removing all the punctuation, the current record is skipped. Otherwise, the program loops through each word, comparing it to the previous one:

# dupword.awk --- find duplicate words in text
{
    $0 = tolower($0)
    gsub(/[^[:alnum:][:blank:]]/, " ");
    $0 = $0         # re-split
    if (NF == 0)
        next
    if ($1 == prev)
        printf("%s:%d: duplicate %s\n",
            FILENAME, FNR, $1)
    for (i = 2; i <= NF; i++)
        if ($i == $(i-1))
            printf("%s:%d: duplicate %s\n",
                FILENAME, FNR, $i)
    prev = $NF
}

Node:Alarm Program, Next:Translate Program, Previous:Dupword Program, Up:Miscellaneous Programs

An Alarm Clock Program

Nothing cures insomnia like a ringing alarm clock.
Arnold Robbins

The following program is a simple "alarm clock" program. You give it a time of day and an optional message. At the specified time, it prints the message on the standard output. In addition, you can give it the number of times to repeat the message as well as a delay between repetitions.

This program uses the gettimeofday function from Managing the Time of Day.

All the work is done in the BEGIN rule. The first part is argument checking and setting of defaults: the delay, the count, and the message to print. If the user supplied a message without the ASCII BEL character (known as the "alert" character, "\a"), then it is added to the message. (On many systems, printing the ASCII BEL generates an audible alert. Thus when the alarm goes off, the system calls attention to itself in case the user is not looking at the computer or terminal.) Here is the program:

# alarm.awk --- set an alarm
#
# Requires gettimeofday library function
# usage: alarm time [ "message" [ count [ delay ] ] ]

BEGIN    \
{
    # Initial argument sanity checking
    usage1 = "usage: alarm time ['message' [count [delay]]]"
    usage2 = sprintf("\t(%s) time ::= hh:mm", ARGV[1])

    if (ARGC < 2) {
        print usage1 > "/dev/stderr"
        print usage2 > "/dev/stderr"
        exit 1
    } else if (ARGC == 5) {
        delay = ARGV[4] + 0
        count = ARGV[3] + 0
        message = ARGV[2]
    } else if (ARGC == 4) {
        count = ARGV[3] + 0
        message = ARGV[2]
    } else if (ARGC == 3) {
        message = ARGV[2]
    } else if (ARGV[1] !~ /[0-9]?[0-9]:[0-9][0-9]/) {
        print usage1 > "/dev/stderr"
        print usage2 > "/dev/stderr"
        exit 1
    }

    # set defaults for once we reach the desired time
    if (delay == 0)
        delay = 180    # 3 minutes
    if (count == 0)
        count = 5
    if (message == "")
        message = sprintf("\aIt is now %s!\a", ARGV[1])
    else if (index(message, "\a") == 0)
        message = "\a" message "\a"

The next section of code turns the alarm time into hours and minutes, converts it (if necessary) to a 24-hour clock, and then turns that time into a count of the seconds since midnight. Next it turns the current time into a count of seconds since midnight. The difference between the two is how long to wait before setting off the alarm:

    # split up alarm time
    split(ARGV[1], atime, ":")
    hour = atime[1] + 0    # force numeric
    minute = atime[2] + 0  # force numeric

    # get current broken down time
    gettimeofday(now)

    # if time given is 12-hour hours and it's after that
    # hour, e.g., `alarm 5:30' at 9 a.m. means 5:30 p.m.,
    # then add 12 to real hour
    if (hour < 12 && now["hour"] > hour)
        hour += 12

    # set target time in seconds since midnight
    target = (hour * 60 * 60) + (minute * 60)

    # get current time in seconds since midnight
    current = (now["hour"] * 60 * 60) + \
               (now["minute"] * 60) + now["second"]

    # how long to sleep for
    naptime = target - current
    if (naptime <= 0) {
        print "time is in the past!" > "/dev/stderr"
        exit 1
    }

Finally, the program uses the system function (see Input/Output Functions) to call the sleep utility. The sleep utility simply pauses for the given number of seconds. If the exit status is not zero, the program assumes that sleep was interrupted and exits. If sleep exited with an OK status (zero), then the program prints the message in a loop, again using sleep to delay for however many seconds are necessary:

    # zzzzzz..... go away if interrupted
    if (system(sprintf("sleep %d", naptime)) != 0)
        exit 1

    # time to notify!
    command = sprintf("sleep %d", delay)
    for (i = 1; i <= count; i++) {
        print message
        # if sleep command interrupted, go away
        if (system(command) != 0)
            break
    }

    exit 0
}

Node:Translate Program, Next:Labels Program, Previous:Alarm Program, Up:Miscellaneous Programs

Transliterating Characters

The system tr utility transliterates characters. For example, it is often used to map uppercase letters into lowercase for further processing:

generate data | tr 'A-Z' 'a-z' | process data ...

tr requires two lists of characters.60 When processing the input, the first character in the first list is replaced with the first character in the second list, the second character in the first list is replaced with the second character in the second list, and so on. If there are more characters in the "from" list than in the "to" list, the last character of the "to" list is used for the remaining characters in the "from" list.

Some time ago, a user proposed that a transliteration function should be added to gawk. The following program was written to prove that character transliteration could be done with a user-level function. This program is not as complete as the system tr utility but it does most of the job.

The translate program demonstrates one of the few weaknesses of standard awk: dealing with individual characters is very painful, requiring repeated use of the substr, index, and gsub built-in functions (see String Manipulation Functions).61 There are two functions. The first, stranslate, takes three arguments:

from
A list of characters from which to translate.
to
A list of characters to which to translate.
target
The string on which to do the translation.

Associative arrays make the translation part fairly easy. t_ar holds the "to" characters, indexed by the "from" characters. Then a simple loop goes through from, one character at a time. For each character in from, if the character appears in target, gsub is used to change it to the corresponding to character.

The translate function simply calls stranslate using $0 as the target. The main program sets two global variables, FROM and TO, from the command line, and then changes ARGV so that awk reads from the standard input.

Finally, the processing rule simply calls translate for each record:

# translate.awk --- do tr-like stuff
# Bugs: does not handle things like: tr A-Z a-z, it has
# to be spelled out. However, if `to' is shorter than `from',
# the last character in `to' is used for the rest of `from'.

function stranslate(from, to, target,     lf, lt, t_ar, i, c)
{
    lf = length(from)
    lt = length(to)
    for (i = 1; i <= lt; i++)
        t_ar[substr(from, i, 1)] = substr(to, i, 1)
    if (lt < lf)
        for (; i <= lf; i++)
            t_ar[substr(from, i, 1)] = substr(to, lt, 1)
    for (i = 1; i <= lf; i++) {
        c = substr(from, i, 1)
        if (index(target, c) > 0)
            gsub(c, t_ar[c], target)
    }
    return target
}

function translate(from, to)
{
    return $0 = stranslate(from, to, $0)
}

# main program
BEGIN {
    if (ARGC < 3) {
        print "usage: translate from to" > "/dev/stderr"
        exit
    }
    FROM = ARGV[1]
    TO = ARGV[2]
    ARGC = 2
    ARGV[1] = "-"
}

{
    translate(FROM, TO)
    print
}

While it is possible to do character transliteration in a user-level function, it is not necessarily efficient, and we (the gawk authors) started to consider adding a built-in function. However, shortly after writing this program, we learned that the System V Release 4 awk had added the toupper and tolower functions (see String Manipulation Functions). These functions handle the vast majority of the cases where character transliteration is necessary, and so we chose to simply add those functions to gawk as well and then leave well enough alone.

An obvious improvement to this program would be to set up the t_ar array only once, in a BEGIN rule. However, this assumes that the "from" and "to" lists will never change throughout the lifetime of the program.

Node:Labels Program, Next:Word Sorting, Previous:Translate Program, Up:Miscellaneous Programs

Printing Mailing Labels

Here is a "real world"62 program. This script reads lists of names and addresses and generates mailing labels. Each page of labels has 20 labels on it, 2 across and 10 down. The addresses are guaranteed to be no more than 5 lines of data. Each address is separated from the next by a blank line.

The basic idea is to read 20 labels worth of data. Each line of each label is stored in the line array. The single rule takes care of filling the line array and printing the page when 20 labels have been read.

The BEGIN rule simply sets RS to the empty string, so that awk splits records at blank lines (see How Input Is Split into Records). It sets MAXLINES to 100, since 100 is the maximum number of lines on the page (20 * 5 = 100).

Most of the work is done in the printpage function. The label lines are stored sequentially in the line array. But they have to print horizontally; line[1] next to line[6], line[2] next to line[7], and so on. Two loops are used to accomplish this. The outer loop, controlled by i, steps through every 10 lines of data; this is each row of labels. The inner loop, controlled by j, goes through the lines within the row. As j goes from 0 to 4, i+j is the j-th line in the row, and i+j+5 is the entry next to it. The output ends up looking something like this:

line 1          line 6
line 2          line 7
line 3          line 8
line 4          line 9
line 5          line 10
...

As a final note, an extra blank line is printed at lines 21 and 61, to keep the output lined up on the labels. This is dependent on the particular brand of labels in use when the program was written. You will also note that there are 2 blank lines at the top and 2 blank lines at the bottom.

The END rule arranges to flush the final page of labels; there may not have been an even multiple of 20 labels in the data:

# labels.awk --- print mailing labels

# Each label is 5 lines of data that may have blank lines.
# The label sheets have 2 blank lines at the top and 2 at
# the bottom.

BEGIN    { RS = "" ; MAXLINES = 100 }

function printpage(    i, j)
{
    if (Nlines <= 0)
        return

    printf "\n\n"        # header

    for (i = 1; i <= Nlines; i += 10) {
        if (i == 21 || i == 61)
            print ""
        for (j = 0; j < 5; j++) {
            if (i + j > MAXLINES)
                break
            printf "   %-41s %s\n", line[i+j], line[i+j+5]
        }
        print ""
    }

    printf "\n\n"        # footer

    for (i in line)
        line[i] = ""
}

# main rule
{
    if (Count >= 20) {
        printpage()
        Count = 0
        Nlines = 0
    }
    n = split($0, a, "\n")
    for (i = 1; i <= n; i++)
        line[++Nlines] = a[i]
    for (; i <= 5; i++)
        line[++Nlines] = ""
    Count++
}

END    \
{
    printpage()
}

Node:Word Sorting, Next:History Sorting, Previous:Labels Program, Up:Miscellaneous Programs

Generating Word-Usage Counts

The following awk program prints the number of occurrences of each word in its input. It illustrates the associative nature of awk arrays by using strings as subscripts. It also demonstrates the for index in array mechanism. Finally, it shows how awk is used in conjunction with other utility programs to do a useful task of some complexity with a minimum of effort. Some explanations follow the program listing:

# Print list of word frequencies
{
    for (i = 1; i <= NF; i++)
        freq[$i]++
}

END {
    for (word in freq)
        printf "%s\t%d\n", word, freq[word]
}

This program has two rules. The first rule, because it has an empty pattern, is executed for every input line. It uses awk's field-accessing mechanism (see Examining Fields) to pick out the individual words from the line, and the built-in variable NF (see Built-in Variables) to know how many fields are available. For each input word, it increments an element of the array freq to reflect that the word has been seen an additional time.

The second rule, because it has the pattern END, is not executed until the input has been exhausted. It prints out the contents of the freq table that has been built up inside the first action. This program has several problems that would prevent it from being useful by itself on real text files:

  • Words are detected using the awk convention that fields are separated just by whitespace. Other characters in the input (except newlines) don't have any special meaning to awk. This means that punctuation characters count as part of words.
  • The awk language considers upper- and lowercase characters to be distinct. Therefore, "bartender" and "Bartender" are not treated as the same word. This is undesirable, since in normal text, words are capitalized if they begin sentences, and a frequency analyzer should not be sensitive to capitalization.
  • The output does not come out in any useful order. You're more likely to be interested in which words occur most frequently or in having an alphabetized table of how frequently each word occurs.

The way to solve these problems is to use some of awk's more advanced features. First, we use tolower to remove case distinctions. Next, we use gsub to remove punctuation characters. Finally, we use the system sort utility to process the output of the awk script. Here is the new version of the program:

# wordfreq.awk --- print list of word frequencies

{
    $0 = tolower($0)    # remove case distinctions
    # remove punctuation
    gsub(/[^[:alnum:]_[:blank:]]/, "", $0)
    for (i = 1; i <= NF; i++)
        freq[$i]++
}

END {
    for (word in freq)
        printf "%s\t%d\n", word, freq[word]
}

Assuming we have saved this program in a file named wordfreq.awk, and that the data is in file1, the following pipeline:

awk -f wordfreq.awk file1 | sort -k 2nr

produces a table of the words appearing in file1 in order of decreasing frequency. The awk program suitably massages the data and produces a word frequency table, which is not ordered.

The awk script's output is then sorted by the sort utility and printed on the terminal. The options given to sort specify a sort that uses the second field of each input line (skipping one field), that the sort keys should be treated as numeric quantities (otherwise 15 would come before 5), and that the sorting should be done in descending (reverse) order.

The sort could even be done from within the program, by changing the END action to:

END {
    sort = "sort -k 2nr"
    for (word in freq)
        printf "%s\t%d\n", word, freq[word] | sort
    close(sort)
}

This way of sorting must be used on systems that do not have true pipes at the command-line (or batch-file) level. See the general operating system documentation for more information on how to use the sort program.

Node:History Sorting, Next:Extract Program, Previous:Word Sorting, Up:Miscellaneous Programs

Removing Duplicates from Unsorted Text

The uniq program (see Printing Nonduplicated Lines of Text), removes duplicate lines from sorted data.

Suppose, however, you need to remove duplicate lines from a data file but that you want to preserve the order the lines are in. A good example of this might be a shell history file. The history file keeps a copy of all the commands you have entered, and it is not unusual to repeat a command several times in a row. Occasionally you might want to compact the history by removing duplicate entries. Yet it is desirable to maintain the order of the original commands.

This simple program does the job. It uses two arrays. The data array is indexed by the text of each line. For each line, data[$0] is incremented. If a particular line has not been seen before, then data[$0] is zero. In this case, the text of the line is stored in lines[count]. Each element of lines is a unique command, and the indices of lines indicate the order in which those lines are encountered. The END rule simply prints out the lines, in order:

# histsort.awk --- compact a shell history file
# Thanks to Byron Rakitzis for the general idea
{
    if (data[$0]++ == 0)
        lines[++count] = $0
}

END {
    for (i = 1; i <= count; i++)
        print lines[i]
}

This program also provides a foundation for generating other useful information. For example, using the following print statement in the END rule indicates how often a particular command is used:

print data[lines[i]], lines[i]

This works because data[$0] is incremented each time a line is seen.

Node:Extract Program, Next:Simple Sed, Previous:History Sorting, Up:Miscellaneous Programs

Extracting Programs from Texinfo Source Files

Both this chapter and the previous chapter (A Library of awk Functions) present a large number of awk programs. If you want to experiment with these programs, it is tedious to have to type them in by hand. Here we present a program that can extract parts of a Texinfo input file into separate files.

This Web page is written in Texinfo, the GNU project's document formatting language. A single Texinfo source file can be used to produce both printed and online documentation. Texinfo is fully documented in the book Texinfo--The GNU Documentation Format, available from the Free Software Foundation.

For our purposes, it is enough to know three things about Texinfo input files:

  • The "at" symbol (@) is special in Texinfo, much as the backslash (\) is in C or awk. Literal @ symbols are represented in Texinfo source files as @@.
  • Comments start with either @c or @comment. The file-extraction program works by using special comments that start at the beginning of a line.
  • Lines containing @group and @end group commands bracket example text that should not be split across a page boundary. (Unfortunately, TeX isn't always smart enough to do things exactly right, and we have to give it some help.)

The following program, extract.awk, reads through a Texinfo source file and does two things, based on the special comments. Upon seeing @c system ..., it runs a command, by extracting the command text from the control line and passing it on to the system function (see Input/Output Functions). Upon seeing @c file filename, each subsequent line is sent to the file filename, until @c endfile is encountered. The rules in extract.awk match either @c or @comment by letting the omment part be optional. Lines containing @group and @end group are simply removed. extract.awk uses the join library function (see Merging an Array into a String).

The example programs in the online Texinfo source for GAWK: Effective AWK Programming (gawk.texi) have all been bracketed inside file and endfile lines. The gawk distribution uses a copy of extract.awk to extract the sample programs and install many of them in a standard directory where gawk can find them. The Texinfo file looks something like this:

...
This program has a @code{BEGIN} rule,
that prints a nice message:

@example
@c file examples/messages.awk
BEGIN @{ print "Don't panic!" @}
@c end file
@end example

It also prints some final advice:

@example
@c file examples/messages.awk
END @{ print "Always avoid bored archeologists!" @}
@c end file
@end example
...

extract.awk begins by setting IGNORECASE to one, so that mixed upper- and lowercase letters in the directives won't matter.

The first rule handles calling system, checking that a command is given (NF is at least three) and also checking that the command exits with a zero exit status, signifying OK:

# extract.awk --- extract files and run programs
#                 from texinfo files
BEGIN    { IGNORECASE = 1 }

/^@c(omment)?[ \t]+system/    \
{
    if (NF < 3) {
        e = (FILENAME ":" FNR)
        e = (e  ": badly formed `system' line")
        print e > "/dev/stderr"
        next
    }
    $1 = ""
    $2 = ""
    stat = system($0)
    if (stat != 0) {
        e = (FILENAME ":" FNR)
        e = (e ": warning: system returned " stat)
        print e > "/dev/stderr"
    }
}

The variable e is used so that the function fits nicely on the page. screen.

The second rule handles moving data into files. It verifies that a file name is given in the directive. If the file named is not the current file, then the current file is closed. Keeping the current file open until a new file is encountered allows the use of the > redirection for printing the contents, keeping open file management simple.

The for loop does the work. It reads lines using getline (see Explicit Input with getline). For an unexpected end of file, it calls the unexpected_eof function. If the line is an "endfile" line, then it breaks out of the loop. If the line is an @group or @end group line, then it ignores it and goes on to the next line. Similarly, comments within examples are also ignored.

Most of the work is in the following few lines. If the line has no @ symbols, the program can print it directly. Otherwise, each leading @ must be stripped off. To remove the @ symbols, the line is split into separate elements of the array a, using the split function (see String Manipulation Functions). The @ symbol is used as the separator character. Each element of a that is empty indicates two successive @ symbols in the original line. For each two empty elements (@@ in the original file), we have to add a single @ symbol back in.

When the processing of the array is finished, join is called with the value of SUBSEP, to rejoin the pieces back into a single line. That line is then printed to the output file:

/^@c(omment)?[ \t]+file/    \
{
    if (NF != 3) {
        e = (FILENAME ":" FNR ": badly formed `file' line")
        print e > "/dev/stderr"
        next
    }
    if ($3 != curfile) {
        if (curfile != "")
            close(curfile)
        curfile = $3
    }

    for (;;) {
        if ((getline line) <= 0)
            unexpected_eof()
        if (line ~ /^@c(omment)?[ \t]+endfile/)
            break
        else if (line ~ /^@(end[ \t]+)?group/)
            continue
        else if (line ~ /^@c(omment+)?[ \t]+/)
            continue
        if (index(line, "@") == 0) {
            print line > curfile
            continue
        }
        n = split(line, a, "@")
        # if a[1] == "", means leading @,
        # don't add one back in.
        for (i = 2; i <= n; i++) {
            if (a[i] == "") { # was an @@
                a[i] = "@"
                if (a[i+1] == "")
                    i++
            }
        }
        print join(a, 1, n, SUBSEP) > curfile
    }
}

An important thing to note is the use of the > redirection. Output done with > only opens the file once; it stays open and subsequent output is appended to the file (see Redirecting Output of print and printf). This makes it easy to mix program text and explanatory prose for the same sample source file (as has been done here!) without any hassle. The file is only closed when a new data file name is encountered or at the end of the input file.

Finally, the function unexpected_eof prints an appropriate error message and then exits. The END rule handles the final cleanup, closing the open file:

function unexpected_eof() {
    printf("%s:%d: unexpected EOF or error\n",
        FILENAME, FNR) > "/dev/stderr"
    exit 1
}

END {
    if (curfile)
        close(curfile)
}

Node:Simple Sed, Next:Igawk Program, Previous:Extract Program, Up:Miscellaneous Programs

A Simple Stream Editor

The sed utility is a stream editor, a program that reads a stream of data, makes changes to it, and passes it on. It is often used to make global changes to a large file or to a stream of data generated by a pipeline of commands. While sed is a complicated program in its own right, its most common use is to perform global substitutions in the middle of a pipeline:

command1 < orig.data | sed 's/old/new/g' | command2 > result

Here, s/old/new/g tells sed to look for the regexp old on each input line and globally replace it with the text new, i.e., all the occurrences on a line. This is similar to awk's gsub function (see String Manipulation Functions).

The following program, awksed.awk, accepts at least two command-line arguments: the pattern to look for and the text to replace it with. Any additional arguments are treated as data file names to process. If none are provided, the standard input is used:

# awksed.awk --- do s/foo/bar/g using just print
#    Thanks to Michael Brennan for the idea
function usage()
{
    print "usage: awksed pat repl [files...]" > "/dev/stderr"
    exit 1
}

BEGIN {
    # validate arguments
    if (ARGC < 3)
        usage()

    RS = ARGV[1]
    ORS = ARGV[2]

    # don't use arguments as files
    ARGV[1] = ARGV[2] = ""
}

# look ma, no hands!
{
    if (RT == "")
        printf "%s", $0
    else
        print
}

The program relies on gawk's ability to have RS be a regexp, as well as on the setting of RT to the actual text that terminates the record (see How Input Is Split into Records).

The idea is to have RS be the pattern to look for. gawk automatically sets $0 to the text between matches of the pattern. This is text that we want to keep, unmodified. Then, by setting ORS to the replacement text, a simple print statement outputs the text we want to keep, followed by the replacement text.

There is one wrinkle to this scheme, which is what to do if the last record doesn't end with text that matches RS. Using a print statement unconditionally prints the replacement text, which is not correct. However, if the file did not end in text that matches RS, RT is set to the null string. In this case, we can print $0 using printf (see Using printf Statements for Fancier Printing).

The BEGIN rule handles the setup, checking for the right number of arguments and calling usage if there is a problem. Then it sets RS and ORS from the command-line arguments and sets ARGV[1] and ARGV[2] to the null string, so that they are not treated as file names (see Using ARGC and ARGV).

The usage function prints an error message and exits. Finally, the single rule handles the printing scheme outlined above, using print or printf as appropriate, depending upon the value of RT.

Node:Igawk Program, Previous:Simple Sed, Up:Miscellaneous Programs

An Easy Way to Use Library Functions

Using library functions in awk can be very beneficial. It encourages code reuse and the writing of general functions. Programs are smaller and therefore clearer. However, using library functions is only easy when writing awk programs; it is painful when running them, requiring multiple -f options. If gawk is unavailable, then so too is the AWKPATH environment variable and the ability to put awk functions into a library directory (see Command-Line Options). It would be nice to be able to write programs in the following manner:

# library functions
@include getopt.awk
@include join.awk
...

# main program
BEGIN {
    while ((c = getopt(ARGC, ARGV, "a:b:cde")) != -1)
        ...
    ...
}

The following program, igawk.sh, provides this service. It simulates gawk's searching of the AWKPATH variable and also allows nested includes; i.e., a file that is included with @include can contain further @include statements. igawk makes an effort to only include files once, so that nested includes don't accidentally include a library function twice.

igawk should behave just like gawk externally. This means it should accept all of gawk's command-line arguments, including the ability to have multiple source files specified via -f, and the ability to mix command-line and library source files.

The program is written using the POSIX Shell (sh) command language. It works as follows:

  1. Loop through the arguments, saving anything that doesn't represent awk source code for later, when the expanded program is run.
  2. For any arguments that do represent awk text, put the arguments into a temporary file that will be expanded. There are two cases:
    1. Literal text, provided with --source or --source=. This text is just echoed directly. The echo program automatically supplies a trailing newline.
    2. Source file names, provided with -f. We use a neat trick and echo @include filename into the temporary file. Since the file-inclusion program works the way gawk does, this gets the text of the file included into the program at the correct point.
  3. Run an awk program (naturally) over the temporary file to expand @include statements. The expanded program is placed in a second temporary file.
  4. Run the expanded program with gawk and any other original command-line arguments that the user supplied (such as the data file names).

The initial part of the program turns on shell tracing if the first argument is debug. Otherwise, a shell trap statement arranges to clean up any temporary files on program exit or upon an interrupt.

The next part loops through all the command-line arguments. There are several cases of interest:

--
This ends the arguments to igawk. Anything else should be passed on to the user's awk program without being evaluated.
-W
This indicates that the next option is specific to gawk. To make argument processing easier, the -W is appended to the front of the remaining arguments and the loop continues. (This is an sh programming trick. Don't worry about it if you are not familiar with sh.)
-v, -F
These are saved and passed on to gawk.
-f, --file, --file=, -Wfile=
The file name is saved to the temporary file /tmp/ig.s.$$ with an @include statement. The sed utility is used to remove the leading option part of the argument (e.g., --file=).
--source, --source=, -Wsource=
The source text is echoed into /tmp/ig.s.$$.
--version, -Wversion
igawk prints its version number, runs gawk --version to get the gawk version information, and then exits.

If none of the -f, --file, -Wfile, --source, or -Wsource arguments are supplied, then the first nonoption argument should be the awk program. If there are no command-line arguments left, igawk prints an error message and exits. Otherwise, the first argument is echoed into /tmp/ig.s.$$. In any case, after the arguments have been processed, /tmp/ig.s.$$ contains the complete text of the original awk program.

The $$ in sh represents the current process ID number. It is often used in shell programs to generate unique temporary file names. This allows multiple users to run igawk without worrying that the temporary file names will clash. The program is as follows:

#! /bin/sh
# igawk --- like gawk but do @include processing
if [ "$1" = debug ]
then
    set -x
    shift
else
    # cleanup on exit, hangup, interrupt, quit, termination
    trap 'rm -f /tmp/ig.[se].$$' 0 1 2 3 15
fi

while [ $# -ne 0 ] # loop over arguments
do
    case $1 in
    --)     shift; break;;

    -W)     shift
            set -- -W"$@"
            continue;;

    -[vF])  opts="$opts $1 '$2'"
            shift;;

    -[vF]*) opts="$opts '$1'" ;;

    -f)     echo @include "$2" >> /tmp/ig.s.$$
            shift;;

    -f*)    f=`echo "$1" | sed 's/-f//'`
            echo @include "$f" >> /tmp/ig.s.$$ ;;

    -?file=*)    # -Wfile or --file
            f=`echo "$1" | sed 's/-.file=//'`
            echo @include "$f" >> /tmp/ig.s.$$ ;;

    -?file)      # get arg, $2
            echo @include "$2" >> /tmp/ig.s.$$
            shift;;

    -?source=*)  # -Wsource or --source
            t=`echo "$1" | sed 's/-.source=//'`
            echo "$t" >> /tmp/ig.s.$$ ;;

    -?source)    # get arg, $2
            echo "$2" >> /tmp/ig.s.$$
            shift;;

    -?version)
            echo igawk: version 1.0 1>&2
            gawk --version
            exit 0 ;;

    -[W-]*) opts="$opts '$1'" ;;

    *)      break;;
    esac
    shift
done

if [ ! -s /tmp/ig.s.$$ ]
then
    if [ -z "$1" ]
    then
         echo igawk: no program! 1>&2
         exit 1
    else
        echo "$1" > /tmp/ig.s.$$
        shift
    fi
fi

# at this point, /tmp/ig.s.$$ has the program

The awk program to process @include directives reads through the program, one line at a time, using getline (see Explicit Input with getline). The input file names and @include statements are managed using a stack. As each @include is encountered, the current file name is "pushed" onto the stack and the file named in the @include directive becomes the current file name. As each file is finished, the stack is "popped," and the previous input file becomes the current input file again. The process is started by making the original file the first one on the stack.

The pathto function does the work of finding the full path to a file. It simulates gawk's behavior when searching the AWKPATH environment variable (see The AWKPATH Environment Variable). If a file name has a / in it, no path search is done. Otherwise, the file name is concatenated with the name of each directory in the path, and an attempt is made to open the generated file name. The only way to test if a file can be read in awk is to go ahead and try to read it with getline; this is what pathto does.63 If the file can be read, it is closed and the file name is returned:

gawk -- '
# process @include directives

function pathto(file,    i, t, junk)
{
    if (index(file, "/") != 0)
        return file

    for (i = 1; i <= ndirs; i++) {
        t = (pathlist[i] "/" file)
        if ((getline junk < t) > 0) {
            # found it
            close(t)
            return t
        }
    }
    return ""
}

The main program is contained inside one BEGIN rule. The first thing it does is set up the pathlist array that pathto uses. After splitting the path on :, null elements are replaced with ".", which represents the current directory:

BEGIN {
    path = ENVIRON["AWKPATH"]
    ndirs = split(path, pathlist, ":")
    for (i = 1; i <= ndirs; i++) {
        if (pathlist[i] == "")
            pathlist[i] = "."
    }

The stack is initialized with ARGV[1], which will be /tmp/ig.s.$$. The main loop comes next. Input lines are read in succession. Lines that do not start with @include are printed verbatim. If the line does start with @include, the file name is in $2. pathto is called to generate the full path. If it cannot, then we print an error message and continue.

The next thing to check is if the file is included already. The processed array is indexed by the full file name of each included file and it tracks this information for us. If the file is seen again, a warning message is printed. Otherwise, the new file name is pushed onto the stack and processing continues.

Finally, when getline encounters the end of the input file, the file is closed and the stack is popped. When stackptr is less than zero, the program is done:

    stackptr = 0
    input[stackptr] = ARGV[1] # ARGV[1] is first file

    for (; stackptr >= 0; stackptr--) {
        while ((getline < input[stackptr]) > 0) {
            if (tolower($1) != "@include") {
                print
                continue
            }
            fpath = pathto($2)
            if (fpath == "") {
                printf("igawk:%s:%d: cannot find %s\n",
                    input[stackptr], FNR, $2) > "/dev/stderr"
                continue
            }
            if (! (fpath in processed)) {
                processed[fpath] = input[stackptr]
                input[++stackptr] = fpath  # push onto stack
            } else
                print $2, "included in", input[stackptr],
                    "already included in",
                    processed[fpath] > "/dev/stderr"
        }
        close(input[stackptr])
    }
}' /tmp/ig.s.$$ > /tmp/ig.e.$$

The last step is to call gawk with the expanded program, along with the original options and command-line arguments that the user supplied. gawk's exit status is passed back on to igawk's calling program:

eval gawk -f /tmp/ig.e.$$ $opts -- "$@"

exit $?

This version of igawk represents my third attempt at this program. There are three key simplifications that make the program work better:

  • Using @include even for the files named with -f makes building the initial collected awk program much simpler; all the @include processing can be done once.
  • Not trying to save the line read with getline in the pathto function when testing for the file's accessibility for use with the main program simplifies things considerably.
  • Using a getline loop in the BEGIN rule does it all in one place. It is not necessary to call out to a separate loop for processing nested @include statements.

Also, this program illustrates that it is often worthwhile to combine sh and awk programming together. You can usually accomplish quite a lot, without having to resort to low-level programming in C or C++, and it is frequently easier to do certain kinds of string and argument manipulation using the shell than it is in awk.

Finally, igawk shows that it is not always necessary to add new features to a program; they can often be layered on top. With igawk, there is no real reason to build @include processing into gawk itself.

As an additional example of this, consider the idea of having two files in a directory in the search path:

default.awk
This file contains a set of default library functions, such as getopt and assert.
site.awk
This file contains library functions that are specific to a site or installation; i.e., locally developed functions. Having a separate file allows default.awk to change with new gawk releases, without requiring the system administrator to update it each time by adding the local functions.

One user suggested that gawk be modified to automatically read these files upon startup. Instead, it would be very simple to modify igawk to do this. Since igawk can process nested @include directives, default.awk could simply contain @include statements for the desired library functions.

Node:Language History, Next:Installation, Previous:Sample Programs, Up:Top

The Evolution of the awk Language

This Web page describes the GNU implementation of awk, which follows the POSIX specification. Many long-time awk users learned awk programming with the original awk implementation in Version 7 Unix. (This implementation was the basis for awk in Berkeley Unix, through 4.3-Reno. Subsequent versions of Berkeley Unix, and systems derived from 4.4BSD-Lite, use various versions of gawk for their awk.) This chapter briefly describes the evolution of the awk language, with cross-references to other parts of the Web page where you can find more information.

  • V7/SVR3.1: The major changes between V7 and System V Release 3.1.
  • SVR4: Minor changes between System V Releases 3.1 and 4.
  • POSIX: New features from the POSIX standard.
  • BTL: New features from the Bell Laboratories version of awk.
  • POSIX/GNU: The extensions in gawk not in POSIX awk.
  • Contributors: The major contributors to gawk.

Node:V7/SVR3.1, Next:SVR4, Previous:Language History, Up:Language History

Major Changes Between V7 and SVR3.1

The awk language evolved considerably between the release of Version 7 Unix (1978) and the new version that was first made generally available in System V Release 3.1 (1987). This section summarizes the changes, with cross-references to further details:

  • The requirement for ; to separate rules on a line (see awk Statements Versus Lines).
  • User-defined functions and the return statement (see User-Defined Functions).
  • The delete statement (see The delete Statement).
  • The do-while statement (see The do-while Statement).
  • The built-in functions atan2, cos, sin, rand, and srand (see Numeric Functions).
  • The built-in functions gsub, sub, and match (see String Manipulation Functions).
  • The built-in functions close and system (see Input/Output Functions).
  • The ARGC, ARGV, FNR, RLENGTH, RSTART, and SUBSEP built-in variables (see Built-in Variables).
  • The conditional expression using the ternary operator ?: (see Conditional Expressions).
  • The exponentiation operator ^ (see Arithmetic Operators) and its assignment operator form ^= (see Assignment Expressions).
  • C-compatible operator precedence, which breaks some old awk programs (see Operator Precedence (How Operators Nest)).
  • Regexps as the value of FS (see Specifying How Fields Are Separated) and as the third argument to the split function (see String Manipulation Functions).
  • Dynamic regexps as operands of the ~ and !~ operators (see How to Use Regular Expressions).
  • The escape sequences \b, \f, and \r (see Escape Sequences). (Some vendors have updated their old versions of awk to recognize \b, \f, and \r, but this is not something you can rely on.)
  • Redirection of input for the getline function (see Explicit Input with getline).
  • Multiple BEGIN and END rules (see The BEGIN and END Special Patterns).
  • Multidimensional arrays (see Multidimensional Arrays).

Node:SVR4, Next:POSIX, Previous:V7/SVR3.1, Up:Language History

Changes Between SVR3.1 and SVR4

The System V Release 4 (1989) version of Unix awk added these features (some of which originated in gawk):

  • The ENVIRON variable (see Built-in Variables).
  • Multiple -f options on the command line (see Command-Line Options).
  • The -v option for assigning variables before program execution begins (see Command-Line Options).
  • The -- option for terminating command-line options.
  • The \a, \v, and \x escape sequences (see Escape Sequences).
  • A defined return value for the srand built-in function (see Numeric Functions).
  • The toupper and tolower built-in string functions for case translation (see String Manipulation Functions).
  • A cleaner specification for the %c format-control letter in the printf function (see Format-Control Letters).
  • The ability to dynamically pass the field width and precision ("%*.*d") in the argument list of the printf function (see Format-Control Letters).
  • The use of regexp constants, such as /foo/, as expressions, where they are equivalent to using the matching operator, as in $0 ~ /foo/ (see Using Regular Expression Constants).
  • Processing of escape sequences inside command-line variable assignments (see Assigning Variables on the Command Line).

Node:POSIX, Next:BTL, Previous:SVR4, Up:Language History

Changes Between SVR4 and POSIX awk

The POSIX Command Language and Utilities standard for awk (1992) introduced the following changes into the language:

  • The use of -W for implementation-specific options (see Command-Line Options).
  • The use of CONVFMT for controlling the conversion of numbers to strings (see Conversion of Strings and Numbers).
  • The concept of a numeric string and tighter comparison rules to go with it (see Variable Typing and Comparison Expressions).
  • More complete documentation of many of the previously undocumented features of the language.

The following common extensions are not permitted by the POSIX standard:

  • \x escape sequences are not recognized (see Escape Sequences).
  • Newlines do not act as whitespace to separate fields when FS is equal to a single space (see Examining Fields).
  • Newlines are not allowed after ? or : (see Conditional Expressions).
  • The synonym func for the keyword function is not recognized (see Function Definition Syntax).
  • The operators ** and **= cannot be used in place of ^ and ^= (see Arithmetic Operators, and Assignment Expressions).
  • Specifying -Ft on the command line does not set the value of FS to be a single TAB character (see Specifying How Fields Are Separated).
  • The fflush built-in function is not supported (see Input/Output Functions).

Node:BTL, Next:POSIX/GNU, Previous:POSIX, Up:Language History

Extensions in the Bell Laboratories awk

Brian Kernighan, one of the original designers of Unix awk, has made his version available via his home page (see Other Freely Available awk Implementations). This section describes extensions in his version of awk that are not in POSIX awk:

  • The -mf N and -mr N command-line options to set the maximum number of fields and the maximum record size, respectively (see Command-Line Options). As a side note, his awk no longer needs these options; it continues to accept them to avoid breaking old programs.
  • The fflush built-in function for flushing buffered output (see Input/Output Functions).
  • The ** and **= operators (see Arithmetic Operators and Assignment Expressions).
  • The use of func as an abbreviation for function (see Function Definition Syntax).

The Bell Laboratories awk also incorporates the following extensions, originally developed for gawk:

  • The \x escape sequence (see Escape Sequences).
  • The /dev/stdin, /dev/stdout, and /dev/stderr special files (see Special File Names in gawk).
  • The ability for FS and for the third argument to split to be null strings (see Making Each Character a Separate Field).
  • The nextfile statement (see Using gawk's nextfile Statement).
  • The ability to delete all of an array at once with delete array (see The delete Statement).

Node:POSIX/GNU, Next:Contributors, Previous:BTL, Up:Language History

Extensions in gawk Not in POSIX awk

The GNU implementation, gawk, adds a large number of features. This section lists them in the order they were added to gawk. They can all be disabled with either the --traditional or --posix options (see Command-Line Options).

Version 2.10 of gawk introduced the following features:

  • The AWKPATH environment variable for specifying a path search for the -f command-line option (see Command-Line Options).
  • The IGNORECASE variable and its effects (see Case Sensitivity in Matching).
  • The /dev/stdin, /dev/stdout, /dev/stderr and /dev/fd/N special file names (see Special File Names in gawk).

Version 2.13 of gawk introduced the following features:

  • The FIELDWIDTHS variable and its effects (see Reading Fixed-Width Data).
  • The systime and strftime built-in functions for obtaining and printing timestamps (see Using gawk's Timestamp Functions).
  • The -W lint option to provide error and portability checking for both the source code and at runtime (see Command-Line Options).
  • The -W compat option to turn off the GNU extensions (see Command-Line Options).
  • The -W posix option for full POSIX compliance (see Command-Line Options).

Version 2.14 of gawk introduced the following feature:

  • The next file statement for skipping to the next data file (see Using gawk's nextfile Statement).

Version 2.15 of gawk introduced the following features:

  • The ARGIND variable, which tracks the movement of FILENAME through ARGV (see Built-in Variables).
  • The ERRNO variable, which contains the system error message when getline returns -1 or close fails (see Built-in Variables).
  • The /dev/pid, /dev/ppid, /dev/pgrpid, and /dev/user file name interpretation (see Special File Names in gawk).
  • The ability to delete all of an array at once with delete array (see The delete Statement).
  • The ability to use GNU-style long-named options that start with -- (see Command-Line Options).
  • The --source option for mixing command-line and library-file source code (see Command-Line Options).

Version 3.0 of gawk introduced the following features:

  • IGNORECASE changed, now applying to string comparison as well as regexp operations (see Case Sensitivity in Matching).
  • The RT variable that contains the input text that matched RS (see How Input Is Split into Records).
  • Full support for both POSIX and GNU regexps (see Regular Expressions).
  • The gensub function for more powerful text manipulation (see String Manipulation Functions).
  • The strftime function acquired a default time format, allowing it to be called with no arguments (see Using gawk's Timestamp Functions).
  • The ability for FS and for the third argument to split to be null strings (see Making Each Character a Separate Field).
  • The ability for RS to be a regexp (see How Input Is Split into Records).
  • The next file statement became nextfile (see Using gawk's nextfile Statement).
  • The --lint-old option to warn about constructs that are not available in the original Version 7 Unix version of awk (see Major Changes Between V7 and SVR3.1).
  • The -m option and the fflush function from the Bell Laboratories research version of awk (see Command-Line Options; also see Input/Output Functions).
  • The --re-interval option to provide interval expressions in regexps (see Regular Expression Operators).
  • The --traditional option was added as a better name for --compat (see Command-Line Options).
  • The use of GNU Autoconf to control the configuration process (see Compiling gawk for Unix).
  • Amiga support (see Installing gawk on an Amiga).

Version 3.1 of gawk introduced the following features:

  • The BINMODE special variable for non-POSIX systems, which allows binary I/O for input and/or output files (see Using gawk on PC Operating Systems).
  • The LINT special variable, which dynamically controls lint warnings (see Built-in Variables).
  • The PROCINFO array for providing process-related information (see Built-in Variables).
  • The TEXTDOMAIN special variable for setting an application's internationalization text domain (see Built-in Variables, and Internationalization with gawk).
  • The ability to use octal and hexadecimal constants in awk program source code (see Octal and Hexadecimal Numbers).
  • The |& operator for two-way I/O to a coprocess (see Two-Way Communications with Another Process).
  • The /inet special files for TCP/IP networking using |& (see Using gawk for Network Programming).
  • The optional second argument to close that allows closing one end of a two-way pipe to a coprocess (see Two-Way Communications with Another Process).
  • The optional third argument to the match function for capturing text-matching subexpressions within a regexp (see String Manipulation Functions).
  • Positional specifiers in printf formats for making translations easier (see Rearranging printf Arguments).
  • The asort function for sorting arrays (see Sorting Array Values and Indices with gawk).
  • The bindtextdomain and dcgettext functions for internationalization (see Internationalizing awk Programs).
  • The extension built-in function and the ability to add new built-in functions dynamically (see Adding New Built-in Functions to gawk).
  • The mktime built-in function for creating timestamps (see Using gawk's Timestamp Functions).
  • The and, or, xor, compl, lshift, rshift, and strtonum built-in functions (see Using gawk's Bit Manipulation Functions).
  • The support for next file as two words was removed completely (see Using gawk's nextfile Statement).
  • The --dump-variables option to print a list of all global variables (see Command-Line Options).
  • The --gen-po command-line option and the use of a leading underscore to mark strings that should be translated (see Extracting Marked Strings).
  • The --non-decimal-data option to allow non-decimal input data (see Allowing Nondecimal Input Data).
  • The --profile option and pgawk, the profiling version of gawk, for producing execution profiles of awk programs (see Profiling Your awk Programs).
  • The --enable-portals configuration option to enable special treatment of pathnames that begin with /p as BSD portals (see Using gawk with BSD Portals).
  • The use of GNU Automake to help in standardizing the configuration process (see Compiling gawk for Unix).
  • The use of GNU gettext for gawk's own message output (see gawk Can Speak Your Language).
  • BeOS support (see Installing gawk on BeOS).
  • Tandem support (see Installing gawk on a Tandem).
  • The Atari port became officially unsupported (see Installing gawk on the Atari ST).
  • The source code now uses new-style function definitions, with ansi2knr to convert the code on systems with old compilers.

Node:Contributors, Previous:POSIX/GNU, Up:Language History

Major Contributors to gawk

Always give credit where credit is due.
Anonymous

This section names the major contributors to gawk and/or this Web page, in approximate chronological order:

  • Dr. Alfred V. Aho, Dr. Peter J. Weinberger, and Dr. Brian W. Kernighan, all of Bell Laboratories, designed and implemented Unix awk, from which gawk gets the majority of its feature set.
  • Paul Rubin did the initial design and implementation in 1986, and wrote the first draft (around 40 pages) of this Web page.
  • Jay Fenlason finished the initial implementation.
  • Diane Close revised the first draft of this Web page, bringing it to around 90 pages.
  • Richard Stallman helped finish the implementation and the initial draft of this Web page. He is also the founder of the FSF and the GNU project.
  • John Woods contributed parts of the code (mostly fixes) in the initial version of gawk.
  • In 1988, David Trueman took over primary maintenance of gawk, making it compatible with "new" awk, and greatly improving its performance.
  • Pat Rankin provided the VMS port and its documentation.
  • Conrad Kwok, Scott Garfinkle, and Kent Williams did the initial ports to MS-DOS with various versions of MSC.
  • Hal Peterson provided help in porting gawk to Cray systems.
  • Kai Uwe Rommel provided the initial port to OS/2 and its documentation.
  • Michal Jaegermann provided the port to Atari systems and its documentation. He continues to provide portability checking with DEC Alpha systems, and has done a lot of work to make sure gawk works on non-32-bit systems.
  • Fred Fish provided the port to Amiga systems and its documentation.
  • Scott Deifik currently maintains the MS-DOS port.
  • Juan Grigera maintains the port to Win32 systems.
  • Dr. Darrel Hankerson acts as coordinator for the various ports to different PC platforms and creates binary distributions for various PC operating systems. He is also instrumental in keeping the documentation up to date for the various PC platforms.
  • Christos Zoulas provided the extension built-in function for dynamically adding new modules.
  • Jürgen Kahrs contributed the initial version of the TCP/IP networking code and documentation, and motivated the inclusion of the |& operator.
  • Stephen Davies provided the port to Tandem systems and its documentation.
  • Martin Brown provided the port to BeOS and its documentation.
  • Arno Peters did the initial work to convert gawk to use GNU Automake and gettext.
  • Alan J. Broder provided the initial version of the asort function as well as the code for the new optional third argument to the match function.
  • Andreas Buening updated the gawk port for OS/2.

    Isamu Hasegawa, of IBM in Japan, contributed support for multibyte characters.

  • Arnold Robbins has been working on gawk since 1988, at first helping David Trueman, and as the primary maintainer since around 1994.

Node:Installation, Next:Notes, Previous:Language History, Up:Top

Installing gawk

This appendix provides instructions for installing gawk on the various platforms that are supported by the developers. The primary developer supports GNU/Linux (and Unix), whereas the other ports are contributed. See Reporting Problems and Bugs, for the electronic mail addresses of the people who did the respective ports.

  • Gawk Distribution: What is in the gawk distribution.
  • Unix Installation: Installing gawk under various versions of Unix.
  • Non-Unix Installation: Installation on Other Operating Systems.
  • Unsupported: Systems whose ports are no longer supported.
  • Bugs: Reporting Problems and Bugs.
  • Other Versions: Other freely available awk implementations.

Node:Gawk Distribution, Next:Unix Installation, Previous:Installation, Up:Installation

The gawk Distribution

This section describes how to get the gawk distribution, how to extract it, and then what is in the various files and subdirectories.

  • Getting: How to get the distribution.
  • Extracting: How to extract the distribution.
  • Distribution contents: What is in the distribution.

Node:Getting, Next:Extracting, Previous:Gawk Distribution, Up:Gawk Distribution

Getting the gawk Distribution

There are three ways to get GNU software:

  • Copy it from someone else who already has it.
  • Order gawk directly from the Free Software Foundation. Software distributions are available for Gnu/Linux, Unix, and MS-Windows, in several CD packages. Their address is:
    Free Software Foundation
59 Temple Place, Suite 330
Boston, MA  02111-1307 USA
Phone: +1-617-542-5942
Fax (including Japan): +1-617-542-2652
Email: gnu@gnu.org
URL: http://www.gnu.org

    Ordering from the FSF directly contributes to the support of the foundation and to the production of more free software.

  • Retrieve gawk by using anonymous ftp to the Internet host ftp.gnu.org, in the directory /gnu/gawk.

The GNU software archive is mirrored around the world. The up-to-date list of mirror sites is available from the main FSF web site. Try to use one of the mirrors; they will be less busy, and you can usually find one closer to your site.

Node:Extracting, Next:Distribution contents, Previous:Getting, Up:Gawk Distribution

Extracting the Distribution

gawk is distributed as a tar file compressed with the GNU Zip program, gzip.

Once you have the distribution (for example, gawk-3.1.1.tar.gz), use gzip to expand the file and then use tar to extract it. You can use the following pipeline to produce the gawk distribution:

# Under System V, add 'o' to the tar options
gzip -d -c gawk-3.1.1.tar.gz | tar -xvpf -

This creates a directory named gawk-3.1.1 in the current directory.

The distribution file name is of the form gawk-V.R.P.tar.gz. The V represents the major version of gawk, the R represents the current release of version V, and the P represents a patch level, meaning that minor bugs have been fixed in the release. The current patch level is 1, but when retrieving distributions, you should get the version with the highest version, release, and patch level. (Note, however, that patch levels greater than or equal to 80 denote "beta" or nonproduction software; you might not want to retrieve such a version unless you don't mind experimenting.) If you are not on a Unix system, you need to make other arrangements for getting and extracting the gawk distribution. You should consult a local expert.

Node:Distribution contents, Previous:Extracting, Up:Gawk Distribution

Contents of the gawk Distribution

The gawk distribution has a number of C source files, documentation files, subdirectories, and files related to the configuration process (see Compiling and Installing gawk on Unix), as well as several subdirectories related to different non-Unix operating systems:

Various .c, .y, and .h files
The actual gawk source code.
README
README_d/README.*
Descriptive files: README for gawk under Unix and the rest for the various hardware and software combinations.
INSTALL
A file providing an overview of the configuration and installation process.
ChangeLog
A detailed list of source code changes as bugs are fixed or improvements made.
NEWS
A list of changes to gawk since the last release or patch.
COPYING
The GNU General Public License.
FUTURES
A brief list of features and changes being contemplated for future releases, with some indication of the time frame for the feature, based on its difficulty.
LIMITATIONS
A list of those factors that limit gawk's performance. Most of these depend on the hardware or operating system software and are not limits in gawk itself.
POSIX.STD
A description of one area in which the POSIX standard for awk is incorrect as well as how gawk handles the problem.
doc/awkforai.txt
A short article describing why gawk is a good language for AI (Artificial Intelligence) programming.
doc/README.card
doc/ad.block
doc/awkcard.in
doc/cardfonts
doc/colors
doc/macros
doc/no.colors
doc/setter.outline
The troff source for a five-color awk reference card. A modern version of troff such as GNU troff (groff) is needed to produce the color version. See the file README.card for instructions if you have an older troff.
doc/gawk.1
The troff source for a manual page describing gawk. This is distributed for the convenience of Unix users.
doc/gawk.texi
The Texinfo source file for this Web page. It should be processed with TeX to produce a printed document, and with makeinfo to produce an Info or HTML file.
doc/gawk.info
The generated Info file for this Web page.
doc/gawkinet.texi
The Texinfo source file for TCP/IP Internetworking with gawk. It should be processed with TeX to produce a printed document and with makeinfo to produce an Info or HTML file.
doc/gawkinet.info
The generated Info file for TCP/IP Internetworking with gawk.
doc/igawk.1
The troff source for a manual page describing the igawk program presented in An Easy Way to Use Library Functions.
doc/Makefile.in
The input file used during the configuration process to generate the actual Makefile for creating the documentation.
Makefile.am
*/Makefile.am
Files used by the GNU automake software for generating the Makefile.in files used by autoconf and configure.
Makefile.in
acconfig.h
acinclude.m4
aclocal.m4
configh.in
configure.in
configure
custom.h
missing_d/*
m4/*
These files and subdirectories are used when configuring gawk for various Unix systems. They are explained in Compiling and Installing gawk on Unix.
intl/*
po/*
The intl directory provides the GNU gettext library, which implements gawk's internationalization features, while the po library contains message translations.
awklib/extract.awk
awklib/Makefile.am
awklib/Makefile.in
awklib/eg/*
The awklib directory contains a copy of extract.awk (see Extracting Programs from Texinfo Source Files), which can be used to extract the sample programs from the Texinfo source file for this Web page. It also contains a Makefile.in file, which configure uses to generate a Makefile. Makefile.am is used by GNU Automake to create Makefile.in. The library functions from A Library of awk Functions, and the igawk program from An Easy Way to Use Library Functions, are included as ready-to-use files in the gawk distribution. They are installed as part of the installation process. The rest of the programs in this Web page are available in appropriate subdirectories of awklib/eg.
unsupported/atari/*
Files needed for building gawk on an Atari ST (see Installing gawk on the Atari ST, for details).
unsupported/tandem/*
Files needed for building gawk on a Tandem (see Installing gawk on a Tandem, for details).
posix/*
Files needed for building gawk on POSIX-compliant systems.
pc/*
Files needed for building gawk under MS-DOS, MS Windows and OS/2 (see Installation on PC Operating Systems, for details).
vms/*
Files needed for building gawk under VMS (see How to Compile and Install gawk on VMS, for details).
test/*
A test suite for gawk. You can use make check from the top-level gawk directory to run your version of gawk against the test suite. If gawk successfully passes make check, then you can be confident of a successful port.

Node:Unix Installation, Next:Non-Unix Installation, Previous:Gawk Distribution, Up:Installation

Compiling and Installing gawk on Unix

Usually, you can compile and install gawk by typing only two commands. However, if you use an unusual system, you may need to configure gawk for your system yourself.

  • Quick Installation: Compiling gawk under Unix.
  • Additional Configuration Options: Other compile-time options.
  • Configuration Philosophy: How it's all supposed to work.

Node:Quick Installation, Next:Additional Configuration Options, Previous:Unix Installation, Up:Unix Installation

Compiling gawk for Unix

After you have extracted the gawk distribution, cd to gawk-3.1.1. Like most GNU software, gawk is configured automatically for your Unix system by running the configure program. This program is a Bourne shell script that is generated automatically using GNU autoconf. (The autoconf software is described fully in Autoconf--Generating Automatic Configuration Scripts, which is available from the Free Software Foundation.)

To configure gawk, simply run configure:

sh ./configure

This produces a Makefile and config.h tailored to your system. The config.h file describes various facts about your system. You might want to edit the Makefile to change the CFLAGS variable, which controls the command-line options that are passed to the C compiler (such as optimization levels or compiling for debugging).

Alternatively, you can add your own values for most make variables on the command line, such as CC and CFLAGS, when running configure:

CC=cc CFLAGS=-g sh ./configure

See the file INSTALL in the gawk distribution for all the details.

After you have run configure and possibly edited the Makefile, type:

make

Shortly thereafter, you should have an executable version of gawk. That's all there is to it! To verify that gawk is working properly, run make check. All of the tests should succeed. If these steps do not work, or if any of the tests fail, check the files in the README_d directory to see if you've found a known problem. If the failure is not described there, please send in a bug report (see Reporting Problems and Bugs.)

Node:Additional Configuration Options, Next:Configuration Philosophy, Previous:Quick Installation, Up:Unix Installation

Additional Configuration Options

There are several additional options you may use on the configure command line when compiling gawk from scratch, including:

--enable-portals
Treat pathnames that begin with /p as BSD portal files when doing two-way I/O with the |& operator (see Using gawk with BSD Portals).
--with-included-gettext
Use the version of the gettext library that comes with gawk. This option should be used on systems that do not use version 2 (or later) of the GNU C library. All known modern GNU/Linux systems use Glibc 2. Use this option on any other system.
--disable-nls
Disable all message-translation facilities. This is usually not desirable, but it may bring you some slight performance improvement. You should also use this option if --with-included-gettext doesn't work on your system.

Node:Configuration Philosophy, Previous:Additional Configuration Options, Up:Unix Installation

The Configuration Process

This section is of interest only if you know something about using the C language and the Unix operating system.

The source code for gawk generally attempts to adhere to formal standards wherever possible. This means that gawk uses library routines that are specified by the ISO C standard and by the POSIX operating system interface standard. When using an ISO C compiler, function prototypes are used to help improve the compile-time checking.

Many Unix systems do not support all of either the ISO or the POSIX standards. The missing_d subdirectory in the gawk distribution contains replacement versions of those functions that are most likely to be missing.

The config.h file that configure creates contains definitions that describe features of the particular operating system where you are attempting to compile gawk. The three things described by this file are: what header files are available, so that they can be correctly included, what (supposedly) standard functions are actually available in your C libraries, and various miscellaneous facts about your variant of Unix. For example, there may not be an st_blksize element in the stat structure. In this case, HAVE_ST_BLKSIZE is undefined.

It is possible for your C compiler to lie to configure. It may do so by not exiting with an error when a library function is not available. To get around this, edit the file custom.h. Use an #ifdef that is appropriate for your system, and either #define any constants that configure should have defined but didn't, or #undef any constants that configure defined and should not have. custom.h is automatically included by config.h.

It is also possible that the configure program generated by autoconf will not work on your system in some other fashion. If you do have a problem, the file configure.in is the input for autoconf. You may be able to change this file and generate a new version of configure that works on your system (see Reporting Problems and Bugs, for information on how to report problems in configuring gawk). The same mechanism may be used to send in updates to configure.in and/or custom.h.

Node:Non-Unix Installation, Next:Unsupported, Previous:Unix Installation, Up:Installation

Installation on Other Operating Systems

This section describes how to install gawk on various non-Unix systems.

  • Amiga Installation: Installing gawk on an Amiga.
  • BeOS Installation: Installing gawk on BeOS.
  • PC Installation: Installing and Compiling gawk on MS-DOS and OS/2.
  • VMS Installation: Installing gawk on VMS.

Node:Amiga Installation, Next:BeOS Installation, Previous:Non-Unix Installation, Up:Non-Unix Installation

Installing gawk on an Amiga

You can install gawk on an Amiga system using a Unix emulation environment, available via anonymous ftp from ftp.ninemoons.com in the directory pub/ade/current. This includes a shell based on pdksh. The primary component of this environment is a Unix emulation library, ixemul.lib.

A more complete distribution for the Amiga is available on the Geek Gadgets CD-ROM, available from:

CRONUS
1840 E. Warner Road #105-265
Tempe, AZ 85284  USA
US Toll Free: (800) 804-0833
Phone: +1-602-491-0442
FAX: +1-602-491-0048
Email: info@ninemoons.com
WWW: http://www.ninemoons.com
Anonymous ftp site: ftp.ninemoons.com

Once you have the distribution, you can configure gawk simply by running configure:

configure -v m68k-amigaos

Then run make and you should be all set! If these steps do not work, please send in a bug report (see Reporting Problems and Bugs).

Node:BeOS Installation, Next:PC Installation, Previous:Amiga Installation, Up:Non-Unix Installation

Installing gawk on BeOS

Since BeOS DR9, all the tools that you should need to build gawk are included with BeOS. The process is basically identical to the Unix process of running configure and then make. Full instructions are given below.

You can compile gawk under BeOS by extracting the standard sources and running configure. You must specify the location prefix for the installation directory. For BeOS DR9 and beyond, the best directory to use is /boot/home/config, so the configure command is:

configure --prefix=/boot/home/config

This installs the compiled application into /boot/home/config/bin, which is already specified in the standard PATH.

Once the configuration process is completed, you can run make, and then make install:

$ make
...
$ make install

BeOS uses bash as its shell; thus, you use gawk the same way you would under Unix. If these steps do not work, please send in a bug report (see Reporting Problems and Bugs).

Node:PC Installation, Next:VMS Installation, Previous:BeOS Installation, Up:Non-Unix Installation

Installation on PC Operating Systems

This section covers installation and usage of gawk on x86 machines running DOS, any version of Windows, or OS/2. In this section, the term "Win32" refers to any of Windows-95/98/ME/NT/2000.

The limitations of DOS (and DOS shells under Windows or OS/2) has meant that various "DOS extenders" are often used with programs such as gawk. The varying capabilities of Microsoft Windows 3.1 and Win32 can add to the confusion. For an overview of the considerations, please refer to README_d/README.pc in the distribution.

  • PC Binary Installation: Installing a prepared distribution.
  • PC Compiling: Compiling gawk for MS-DOS, Win32, and OS/2.
  • PC Using: Running gawk on MS-DOS, Win32 and OS/2.
  • Cygwin: Building and running gawk for Cygwin.

Node:PC Binary Installation, Next:PC Compiling, Previous:PC Installation, Up:PC Installation
Installing a Prepared Distribution for PC Systems

If you have received a binary distribution prepared by the DOS maintainers, then gawk and the necessary support files appear under the gnu directory, with executables in gnu/bin, libraries in gnu/lib/awk, and manual pages under gnu/man. This is designed for easy installation to a /gnu directory on your drive--however, the files can be installed anywhere provided AWKPATH is set properly. Regardless of the installation directory, the first line of igawk.cmd and igawk.bat (in gnu/bin) may need to be edited.

The binary distribution contains a separate file describing the contents. In particular, it may include more than one version of the gawk executable.

OS/2 (32 bit, EMX) binary distributions are prepared for the /usr directory of your preferred drive. Set UNIXROOT to your installation drive (e.g., e:) if you want to install gawk onto another drive than the hardcoded default c:. Executables appear in /usr/bin, libraries under /usr/share/awk, manual pages under /usr/man, Texinfo documentation under /usr/info and NLS files under /usr/share/locale. If you already have a file /usr/info/dir from another package do not overwrite it! Instead enter the following commands at your prompt (replace x: by your installation drive):

install-info --info-dir=x:/usr/info x:/usr/info/gawk.info
install-info --info-dir=x:/usr/info x:/usr/info/gawkinet.info

However, the files can be installed anywhere provided AWKPATH is set properly.

The binary distribution may contain a separate file containing additional or more detailed installation instructions.

Node:PC Compiling, Next:PC Using, Previous:PC Binary Installation, Up:PC Installation
Compiling gawk for PC Operating Systems

gawk can be compiled for MS-DOS, Win32, and OS/2 using the GNU development tools from DJ Delorie (DJGPP; MS-DOS only) or Eberhard Mattes (EMX; MS-DOS, Win32 and OS/2). Microsoft Visual C/C++ can be used to build a Win32 version, and Microsoft C/C++ can be used to build 16-bit versions for MS-DOS and OS/2. The file README_d/README.pc in the gawk distribution contains additional notes, and pc/Makefile contains important information on compilation options.

To build gawk for MS-DOS, Win32, and OS/2 (16 bit; for 32 bit (EMX) see below), copy the files in the pc directory (except for ChangeLog) to the directory with the rest of the gawk sources. The Makefile contains a configuration section with comments and may need to be edited in order to work with your make utility.

The Makefile contains a number of targets for building various MS-DOS, Win32, and OS/2 versions. A list of targets is printed if the make command is given without a target. As an example, to build gawk using the DJGPP tools, enter make djgpp.

Using make to run the standard tests and to install gawk requires additional Unix-like tools, including sh, sed, and cp. In order to run the tests, the test/*.ok files may need to be converted so that they have the usual DOS-style end-of-line markers. Most of the tests work properly with Stewartson's shell along with the companion utilities or appropriate GNU utilities. However, some editing of test/Makefile is required. It is recommended that you copy the file pc/Makefile.tst over the file test/Makefile as a replacement. Details can be found in README_d/README.pc and in the file pc/Makefile.tst.

To build gawk for OS/2 (32 bit, EMX), there are three possibilities:

  1. Using the configure script included in the official gawk distribution. configure need not be recreated but a number of restrictions exist when using this choice:
    • An external gettext library cannot be used. I.e. the configure option --without-included-gettext does not work. Unfortunately, the internal gettext library is seriuosly broken for OS/2. Therefore you have to use --disable-nls.
    • Executables must be linked statically (a.out format only). make install does not work.

      These restrictions are due to restrictions in Autoconf 2.13 and cannot be avoided. They will vanish as soon as gawk moves on to Autoconf 2.5x. Now enter the following commands at your sh prompt:

      $ CC="gcc"; export CC
$ CFLAGS="-O2"; export CFLAGS
$ AWK="awk"; export AWK
$ LD="ld"; export LD
$ LDFLAGS="-Zexe"; export LDFLAGS
$ RANLIB="ranlib"; export RANLIB
$ ac_cv_header_sys_socket_h="yes"
$ export ac_cv_header_sys_socket_h
$ ./configure --prefix=c:/usr --disable-nls
$ make

  2. Using a special version of Autoconf 2.13 for OS/2 to recreate configure. Not tested. In principle this should work but the same restrictions apply as in 1, but the environment variables CC, AWK, LDFLAGS and RANLIB are not necessary.
  3. Using Autoconf 2.5x to recreate configure (2.52f or higher recommended). Some patches must be applied to Makefile.am and test/Makefile.am and po/Makefile.in.in. Currently not supported.

Note: Even if the compiled gawk.exe executable contains a DOS header (a.out format), it does not work under DOS. To compile an executable that runs under DOS, CPPFLAGS must be set to "-DPIPES_SIMULATED". But then some nonstandard extensions of gawk (e.g., |&) do not work!

After compilation the internal tests can be performed. Enter make check CMP="diff -a" at your command prompt. All tests but the pid test are expected to work properly. The pid test might or might not work, no idea why.

Note: Most OS/2 ports of GNU make are not able to handle the Makefiles of this package. If you encounter any problems with make try GNU make 3.79.1. You should find the latest version on ftp://ftp.unixos2.org.

Node:PC Using, Next:Cygwin, Previous:PC Compiling, Up:PC Installation
Using gawk on PC Operating Systems

With the exception of the Cygwin environment, the |& operator and TCP/IP networking (see Using gawk for Network Programming) are not supported for MS-DOS or MS-Windows. EMX (OS/2 only) does support at least the |& operator.

The OS/2 and MS-DOS versions of gawk search for program files as described in The AWKPATH Environment Variable. However, semicolons (rather than colons) separate elements in the AWKPATH variable. If AWKPATH is not set or is empty, then the default search path for OS/2 (16 bit) and MS-DOS versions is ".;c:/lib/awk;c:/gnu/lib/awk".

The search path for OS/2 (32 bit, EMX) is determined by the prefix directory (most likely /usr or c:/usr) that has been specified as an option of the configure script like it is the case for the Unix versions. If c:/usr is the prefix directory then the default search path contains . and c:/usr/share/awk. Additionally, to support binary distributions of gawk for OS/2 systems whose drive c: might not support long file names or might not exist at all, there is a special environment variable. If UNIXROOT specifies a drive then this specific drive is also searched for program files. E.g., if UNIXROOT is set to e: the complete default search path is ".;c:/usr/share/awk;e:/usr/share/awk".

An sh-like shell (as opposed to command.com under MS-DOS or cmd.exe under OS/2) may be useful for awk programming. Ian Stewartson has written an excellent shell for MS-DOS and OS/2, Daisuke Aoyama has ported GNU bash to MS-DOS using the DJGPP tools, and several shells are available for OS/2, including ksh. The file README_d/README.pc in the gawk distribution contains information on these shells. Users of Stewartson's shell on DOS should examine its documentation for handling command lines; in particular, the setting for gawk in the shell configuration may need to be changed and the ignoretype option may also be of interest.

Under OS/2 and DOS, gawk (and many other text programs) silently translate end-of-line "\r\n" to "\n" on input and "\n" to "\r\n" on output. A special BINMODE variable allows control over these translations and is interpreted as follows:

  • If BINMODE is "r", or (BINMODE & 1) is nonzero, then binary mode is set on read (i.e., no translations on reads).
  • If BINMODE is "w", or (BINMODE & 2) is nonzero, then binary mode is set on write (i.e., no translations on writes).
  • If BINMODE is "rw" or "wr", binary mode is set for both read and write (same as (BINMODE & 3)).
  • BINMODE=non-null-string is the same as BINMODE=3 (i.e., no translations on reads or writes). However, gawk issues a warning message if the string is not one of "rw" or "wr".

The modes for standard input and standard output are set one time only (after the command line is read, but before processing any of the awk program). Setting BINMODE for standard input or standard output is accomplished by using an appropriate -v BINMODE=N option on the command line. BINMODE is set at the time a file or pipe is opened and cannot be changed mid-stream.

The name BINMODE was chosen to match mawk (see Other Freely Available awk Implementations). Both mawk and gawk handle BINMODE similarly; however, mawk adds a -W BINMODE=N option and an environment variable that can set BINMODE, RS, and ORS. The files binmode[1-3].awk (under gnu/lib/awk in some of the prepared distributions) have been chosen to match mawk's -W BINMODE=N option. These can be changed or discarded; in particular, the setting of RS giving the fewest "surprises" is open to debate. mawk uses RS = "\r\n" if binary mode is set on read, which is appropriate for files with the DOS-style end-of-line.

To illustrate, the following examples set binary mode on writes for standard output and other files, and set ORS as the "usual" DOS-style end-of-line:

gawk -v BINMODE=2 -v ORS="\r\n" ...

or:

gawk -v BINMODE=w -f binmode2.awk ...

These give the same result as the -W BINMODE=2 option in mawk. The following changes the record separator to "\r\n" and sets binary mode on reads, but does not affect the mode on standard input:

gawk -v RS="\r\n" --source "BEGIN { BINMODE = 1 }" ...

or:

gawk -f binmode1.awk ...

With proper quoting, in the first example the setting of RS can be moved into the BEGIN rule.

Node:Cygwin, Previous:PC Using, Up:PC Installation
Using gawk In The Cygwin Environment

gawk can be used "out of the box" under Windows if you are using the Cygwin environment.64 This environment provides an excellent simulation of Unix, using the GNU tools, such as bash, the GNU Compiler Collection (GCC), GNU Make, and other GNU tools. Compilation and installation for Cygwin is the same as for a Unix system:

tar -xvpzf gawk-3.1.1.tar.gz
cd gawk-3.1.1
./configure
make

When compared to GNU/Linux on the same system, the configure step on Cygwin takes considerably longer. However, it does finish, and then the make proceeds as usual.

Note: The |& operator and TCP/IP networking (see Using gawk for Network Programming) are fully supported in the Cygwin environment. This is not true for any other environment for MS-DOS or MS-Windows.

Node:VMS Installation, Previous:PC Installation, Up:Non-Unix Installation

How to Compile and Install gawk on VMS

This subsection describes how to compile and install gawk under VMS.

  • VMS Compilation: How to compile gawk under VMS.
  • VMS Installation Details: How to install gawk under VMS.
  • VMS Running: How to run gawk under VMS.
  • VMS POSIX: Alternate instructions for VMS POSIX.

Node:VMS Compilation, Next:VMS Installation Details, Previous:VMS Installation, Up:VMS Installation
Compiling gawk on VMS

To compile gawk under VMS, there is a DCL command procedure that issues all the necessary CC and LINK commands. There is also a Makefile for use with the MMS utility. From the source directory, use either:

$ @[.VMS]VMSBUILD.COM

or:

$ MMS/DESCRIPTION=[.VMS]DESCRIP.MMS GAWK

Depending upon which C compiler you are using, follow one of the sets of instructions in this table:

VAX C V3.x
Use either vmsbuild.com or descrip.mms as is. These use CC/OPTIMIZE=NOLINE, which is essential for Version 3.0.
VAX C V2.x
You must have Version 2.3 or 2.4; older ones won't work. Edit either vmsbuild.com or descrip.mms according to the comments in them. For vmsbuild.com, this just entails removing two ! delimiters. Also edit config.h (which is a copy of file [.config]vms-conf.h) and comment out or delete the two lines #define __STDC__ 0 and #define VAXC_BUILTINS near the end.
GNU C
Edit vmsbuild.com or descrip.mms; the changes are different from those for VAX C V2.x but equally straightforward. No changes to config.h are needed.
DEC C
Edit vmsbuild.com or descrip.mms according to their comments. No changes to config.h are needed.

gawk has been tested under VAX/VMS 5.5-1 using VAX C V3.2, and GNU C 1.40 and 2.3. It should work without modifications for VMS V4.6 and up.

Node:VMS Installation Details, Next:VMS Running, Previous:VMS Compilation, Up:VMS Installation
Installing gawk on VMS

To install gawk, all you need is a "foreign" command, which is a DCL symbol whose value begins with a dollar sign. For example:

$ GAWK :== $disk1:[gnubin]GAWK

Substitute the actual location of gawk.exe for $disk1:[gnubin]. The symbol should be placed in the login.com of any user who wants to run gawk, so that it is defined every time the user logs on. Alternatively, the symbol may be placed in the system-wide sylogin.com procedure, which allows all users to run gawk.

Optionally, the help entry can be loaded into a VMS help library:

$ LIBRARY/HELP SYS$HELP:HELPLIB [.VMS]GAWK.HLP

(You may want to substitute a site-specific help library rather than the standard VMS library HELPLIB.) After loading the help text, the command:

$ HELP GAWK

provides information about both the gawk implementation and the awk programming language.

The logical name AWK_LIBRARY can designate a default location for awk program files. For the -f option, if the specified file name has no device or directory path information in it, gawk looks in the current directory first, then in the directory specified by the translation of AWK_LIBRARY if the file is not found. If, after searching in both directories, the file still is not found, gawk appends the suffix .awk to the filename and retries the file search. If AWK_LIBRARY is not defined, that portion of the file search fails benignly.

Node:VMS Running, Next:VMS POSIX, Previous:VMS Installation Details, Up:VMS Installation
Running gawk on VMS

Command-line parsing and quoting conventions are significantly different on VMS, so examples in this Web page or from other sources often need minor changes. They are minor though, and all awk programs should run correctly.

Here are a couple of trivial tests:

$ gawk -- "BEGIN {print ""Hello, World!""}"
$ gawk -"W" version
! could also be -"W version" or "-W version"

Note that uppercase and mixed-case text must be quoted.

The VMS port of gawk includes a DCL-style interface in addition to the original shell-style interface (see the help entry for details). One side effect of dual command-line parsing is that if there is only a single parameter (as in the quoted string program above), the command becomes ambiguous. To work around this, the normally optional -- flag is required to force Unix style rather than DCL parsing. If any other dash-type options (or multiple parameters such as data files to process) are present, there is no ambiguity and -- can be omitted.

The default search path, when looking for awk program files specified by the -f option, is "SYS$DISK:[],AWK_LIBRARY:". The logical name AWKPATH can be used to override this default. The format of AWKPATH is a comma-separated list of directory specifications. When defining it, the value should be quoted so that it retains a single translation and not a multitranslation RMS searchlist.

Node:VMS POSIX, Previous:VMS Running, Up:VMS Installation
Building and Using gawk on VMS POSIX

Ignore the instructions above, although vms/gawk.hlp should still be made available in a help library. The source tree should be unpacked into a container file subsystem rather than into the ordinary VMS filesystem. Make sure that the two scripts, configure and vms/posix-cc.sh, are executable; use chmod +x on them if necessary. Then execute the following two commands:

psx> CC=vms/posix-cc.sh configure
psx> make CC=c89 gawk

The first command constructs files config.h and Makefile out of templates, using a script to make the C compiler fit configure's expectations. The second command compiles and links gawk using the C compiler directly; ignore any warnings from make about being unable to redefine CC. configure takes a very long time to execute, but at least it provides incremental feedback as it runs.

This has been tested with VAX/VMS V6.2, VMS POSIX V2.0, and DEC C V5.2.

Once built, gawk works like any other shell utility. Unlike the normal VMS port of gawk, no special command-line manipulation is needed in the VMS POSIX environment.

Node:Unsupported, Next:Bugs, Previous:Non-Unix Installation, Up:Installation

Unsupported Operating System Ports

This sections describes systems for which the gawk port is no longer supported.

  • Atari Installation: Installing gawk on the Atari ST.
  • Tandem Installation: Installing gawk on a Tandem.

Node:Atari Installation, Next:Tandem Installation, Previous:Unsupported, Up:Unsupported

Installing gawk on the Atari ST

The Atari port is no longer supported. It is included for those who might want to use it but it is no longer being actively maintained.

There are no substantial differences when installing gawk on various Atari models. Compiled gawk executables do not require a large amount of memory with most awk programs, and should run on all Motorola processor-based models (called further ST, even if that is not exactly right).

In order to use gawk, you need to have a shell, either text or graphics, that does not map all the characters of a command line to uppercase. Maintaining case distinction in option flags is very important (see Command-Line Options). These days this is the default and it may only be a problem for some very old machines. If your system does not preserve the case of option flags, you need to upgrade your tools. Support for I/O redirection is necessary to make it easy to import awk programs from other environments. Pipes are nice to have but not vital.

  • Atari Compiling: Compiling gawk on Atari.
  • Atari Using: Running gawk on Atari.

Node:Atari Compiling, Next:Atari Using, Previous:Atari Installation, Up:Atari Installation
Compiling gawk on the Atari ST

A proper compilation of gawk sources when sizeof(int) differs from sizeof(void *) requires an ISO C compiler. An initial port was done with gcc. You may actually prefer executables where ints are four bytes wide but the other variant works as well.

You may need quite a bit of memory when trying to recompile the gawk sources, as some source files (regex.c in particular) are quite big. If you run out of memory compiling such a file, try reducing the optimization level for this particular file, which may help.

With a reasonable shell (bash will do), you have a pretty good chance that the configure utility will succeed, and in particular if you run GNU/Linux, MiNT or a similar operating system. Otherwise sample versions of config.h and Makefile.st are given in the atari subdirectory and can be edited and copied to the corresponding files in the main source directory. Even if configure produces something, it might be advisable to compare its results with the sample versions and possibly make adjustments.

Some gawk source code fragments depend on a preprocessor define atarist. This basically assumes the TOS environment with gcc. Modify these sections as appropriate if they are not right for your environment. Also see the remarks about AWKPATH and envsep in Running gawk on the Atari ST.

As shipped, the sample config.h claims that the system function is missing from the libraries, which is not true, and an alternative implementation of this function is provided in unsupported/atari/system.c. Depending upon your particular combination of shell and operating system, you might want to change the file to indicate that system is available.

Node:Atari Using, Previous:Atari Compiling, Up:Atari Installation
Running gawk on the Atari ST

An executable version of gawk should be placed, as usual, anywhere in your PATH where your shell can find it.

While executing, the Atari version of gawk creates a number of temporary files. When using gcc libraries for TOS, gawk looks for either of the environment variables, TEMP or TMPDIR, in that order. If either one is found, its value is assumed to be a directory for temporary files. This directory must exist, and if you can spare the memory, it is a good idea to put it on a RAM drive. If neither TEMP nor TMPDIR are found, then gawk uses the current directory for its temporary files.

The ST version of gawk searches for its program files, as described in The AWKPATH Environment Variable. The default value for the AWKPATH variable is taken from DEFPATH defined in Makefile. The sample gcc/TOS Makefile for the ST in the distribution sets DEFPATH to ".,c:\lib\awk,c:\gnu\lib\awk". The search path can be modified by explicitly setting AWKPATH to whatever you want. Note that colons cannot be used on the ST to separate elements in the AWKPATH variable, since they have another reserved meaning. Instead, you must use a comma to separate elements in the path. When recompiling, the separating character can be modified by initializing the envsep variable in unsupported/atari/gawkmisc.atr to another value.

Although awk allows great flexibility in doing I/O redirections from within a program, this facility should be used with care on the ST running under TOS. In some circumstances, the OS routines for file-handle pool processing lose track of certain events, causing the computer to crash and requiring a reboot. Often a warm reboot is sufficient. Fortunately, this happens infrequently and in rather esoteric situations. In particular, avoid having one part of an awk program using print statements explicitly redirected to /dev/stdout, while other print statements use the default standard output, and a calling shell has redirected standard output to a file.

When gawk is compiled with the ST version of gcc and its usual libraries, it accepts both / and \ as path separators. While this is convenient, it should be remembered that this removes one technically valid character (/) from your file name. It may also create problems for external programs called via the system function, which may not support this convention. Whenever it is possible that a file created by gawk will be used by some other program, use only backslashes. Also remember that in awk, backslashes in strings have to be doubled in order to get literal backslashes (see Escape Sequences).

Node:Tandem Installation, Previous:Atari Installation, Up:Unsupported

Installing gawk on a Tandem

The Tandem port is only minimally supported. The port's contributor no longer has access to a Tandem system.

The Tandem port was done on a Cyclone machine running D20. The port is pretty clean and all facilities seem to work except for the I/O piping facilities (see Using getline from a Pipe, Using getline into a Variable from a Pipe, and Redirecting Output of print and printf), which is just too foreign a concept for Tandem.

To build a Tandem executable from source, download all of the files so that the file names on the Tandem box conform to the restrictions of D20. For example, array.c becomes ARRAYC, and awk.h becomes AWKH. The totally Tandem-specific files are in the tandem "subvolume" (unsupported/tandem in the gawk distribution) and should be copied to the main source directory before building gawk.

The file compit can then be used to compile and bind an executable. Alas, there is no configure or make.

Usage is the same as for Unix, except that D20 requires all { and } characters to be escaped with ~ on the command line (but not in script files). Also, the standard Tandem syntax for /in filename,out filename/ must be used instead of the usual Unix < and > for file redirection. (Redirection options on getline, print etc., are supported.)

The -mr val option (see Command-Line Options) has been "stolen" to enable Tandem users to process fixed-length records with no "end-of-line" character. That is, -mr 74 tells gawk to read the input file as fixed 74-byte records.

Node:Bugs, Next:Other Versions, Previous:Unsupported, Up:Installation

Reporting Problems and Bugs

There is nothing more dangerous than a bored archeologist.
The Hitchhiker's Guide to the Galaxy

If you have problems with gawk or think that you have found a bug, please report it to the developers; we cannot promise to do anything but we might well want to fix it.

Before reporting a bug, make sure you have actually found a real bug. Carefully reread the documentation and see if it really says you can do what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation!

Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possible awk program and input data file that reproduces the problem. Then send us the program and data file, some idea of what kind of Unix system you're using, the compiler you used to compile gawk, and the exact results gawk gave you. Also say what you expected to occur; this helps us decide whether the problem is really in the documentation.

Once you have a precise problem, send email to bug-gawk@gnu.org.

Please include the version number of gawk you are using. You can get this information with the command gawk --version. Using this address automatically sends a carbon copy of your mail to me. If necessary, I can be reached directly at arnold@gnu.org. The bug reporting address is preferred since the email list is archived at the GNU Project. All email should be in English, since that is my native language.

Caution: Do not try to report bugs in gawk by posting to the Usenet/Internet newsgroup comp.lang.awk. While the gawk developers do occasionally read this newsgroup, there is no guarantee that we will see your posting. The steps described above are the official recognized ways for reporting bugs.

Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation or are just obscure features, ask me; I will try to help you out, although I may not have the time to fix the problem. You can send me electronic mail at the Internet address noted previously.

If you find bugs in one of the non-Unix ports of gawk, please send an electronic mail message to the person who maintains that port. They are named in the following list, as well as in the README file in the gawk distribution. Information in the README file should be considered authoritative if it conflicts with this Web page.

The people maintaining the non-Unix ports of gawk are as follows:

Amiga | Fred Fish, fnf@ninemoons.com.
BeOS | Martin Brown, mc@whoever.com.
MS-DOS | Scott Deifik, scottd@amgen.com and Darrel Hankerson, hankedr@mail.auburn.edu.
MS-Windows | Juan Grigera, juan@biophnet.unlp.edu.ar.
OS/2 | The Unix for OS/2 team, gawk-maintainer@unixos2.org.
Tandem | Stephen Davies, scldad@sdc.com.au.
VMS | Pat Rankin, rankin@eql.caltech.edu.

If your bug is also reproducible under Unix, please send a copy of your report to the bug-gawk@gnu.org email list as well.

Node:Other Versions, Previous:Bugs, Up:Installation

Other Freely Available awk Implementations

It's kind of fun to put comments like this in your awk code.
// Do C++ comments work? answer: yes! of course
Michael Brennan

There are three other freely available awk implementations. This section briefly describes where to get them:

Unix awk
Brian Kernighan has made his implementation of awk freely available. You can retrieve this version via the World Wide Web from his home page.65 It is available in several archive formats:
Shell archive
http://cm.bell-labs.com/who/bwk/awk.shar
Compressed tar file
http://cm.bell-labs.com/who/bwk/awk.tar.gz
Zip file
http://cm.bell-labs.com/who/bwk/awk.zip

This version requires an ISO C (1990 standard) compiler; the C compiler from GCC (the GNU Compiler Collection) works quite nicely.

See Extensions in the Bell Laboratories awk, for a list of extensions in this awk that are not in POSIX awk.

mawk
Michael Brennan has written an independent implementation of awk, called mawk. It is available under the GPL (see GNU General Public License), just as gawk is.

You can get it via anonymous ftp to the host ftp.whidbey.net. Change directory to /pub/brennan. Use "binary" or "image" mode, and retrieve mawk1.3.3.tar.gz (or the latest version that is there).

gunzip may be used to decompress this file. Installation is similar to gawk's (see Compiling and Installing gawk on Unix).

mawk has the following extensions that are not in POSIX awk:

  • The fflush built-in function for flushing buffered output (see Input/Output Functions).
  • The ** and **= operators (see Arithmetic Operators and also see Assignment Expressions).
  • The use of func as an abbreviation for function (see Function Definition Syntax).
  • The \x escape sequence (see Escape Sequences).
  • The /dev/stdout, and /dev/stderr special files (see Special File Names in gawk). Use "-" instead of "/dev/stdin" with mawk.
  • The ability for FS and for the third argument to split to be null strings (see Making Each Character a Separate Field).
  • The ability to delete all of an array at once with delete array (see The delete Statement).
  • The ability for RS to be a regexp (see How Input Is Split into Records).
  • The BINMODE special variable for non-Unix operating systems (see Using gawk on PC Operating Systems).

The next version of mawk will support nextfile.

awka
Written by Andrew Sumner, awka translates awk programs into C, compiles them, and links them with a library of functions that provides the core awk functionality. It also has a number of extensions.

The awk translator is released under the GPL, and the library is under the LGPL.

To get awka, go to http://awka.sourceforge.net. You can reach Andrew Sumner at andrew_sumner@bigfoot.com.

Node:Notes, Next:Basic Concepts, Previous:Installation, Up:Top

Implementation Notes

This appendix contains information mainly of interest to implementors and maintainers of gawk. Everything in it applies specifically to gawk and not to other implementations.

  • Compatibility Mode: How to disable certain gawk extensions.
  • Additions: Making Additions To gawk.
  • Dynamic Extensions: Adding new built-in functions to gawk.
  • Future Extensions: New features that may be implemented one day.

Node:Compatibility Mode, Next:Additions, Previous:Notes, Up:Notes

Downward Compatibility and Debugging

See Extensions in gawk Not in POSIX awk, for a summary of the GNU extensions to the awk language and program. All of these features can be turned off by invoking gawk with the --traditional option or with the --posix option.

If gawk is compiled for debugging with -DDEBUG, then there is one more option available on the command line:

-W parsedebug
--parsedebug
Prints out the parse stack information as the program is being parsed.

This option is intended only for serious gawk developers and not for the casual user. It probably has not even been compiled into your version of gawk, since it slows down execution.

Node:Additions, Next:Dynamic Extensions, Previous:Compatibility Mode, Up:Notes

Making Additions to gawk

If you find that you want to enhance gawk in a significant fashion, you are perfectly free to do so. That is the point of having free software; the source code is available and you are free to change it as you want (see GNU General Public License).

This section discusses the ways you might want to change gawk as well as any considerations you should bear in mind.

  • Adding Code: Adding code to the main body of gawk.
  • New Ports: Porting gawk to a new operating system.

Node:Adding Code, Next:New Ports, Previous:Additions, Up:Additions

Adding New Features

You are free to add any new features you like to gawk. However, if you want your changes to be incorporated into the gawk distribution, there are several steps that you need to take in order to make it possible for me to include your changes:

  1. Before building the new feature into gawk itself, consider writing it as an extension module (see Adding New Built-in Functions to gawk). If that's not possible, continue with the rest of the steps in this list.
  2. Get the latest version. It is much easier for me to integrate changes if they are relative to the most recent distributed version of gawk. If your version of gawk is very old, I may not be able to integrate them at all. (See Getting the gawk Distribution, for information on getting the latest version of gawk.)
  3. Follow the GNU Coding Standards. This document describes how GNU software should be written. If you haven't read it, please do so, preferably before starting to modify gawk. (The GNU Coding Standards are available from the GNU Project's ftp site, at ftp://ftp.gnu.org/gnu/GNUInfo/standards.text. Texinfo, Info, and DVI versions are also available.)
  4. Use the gawk coding style. The C code for gawk follows the instructions in the GNU Coding Standards, with minor exceptions. The code is formatted using the traditional "K&R" style, particularly as regards to the placement of braces and the use of tabs. In brief, the coding rules for gawk are as follows:
    • Use ANSI/ISO style (prototype) function headers when defining functions.
    • Put the name of the function at the beginning of its own line.
    • Put the return type of the function, even if it is int, on the line above the line with the name and arguments of the function.
    • Put spaces around parentheses used in control structures (if, while, for, do, switch, and return).
    • Do not put spaces in front of parentheses used in function calls.
    • Put spaces around all C operators and after commas in function calls.
    • Do not use the comma operator to produce multiple side effects, except in for loop initialization and increment parts, and in macro bodies.
    • Use real tabs for indenting, not spaces.
    • Use the "K&R" brace layout style.
    • Use comparisons against NULL and '\0' in the conditions of if, while, and for statements, as well as in the cases of switch statements, instead of just the plain pointer or character value.
    • Use the TRUE, FALSE and NULL symbolic constants and the character constant '\0' where appropriate, instead of 1 and 0.
    • Use the ISALPHA, ISDIGIT, etc. macros, instead of the traditional lowercase versions; these macros are better behaved for non-ASCII character sets.
    • Provide one-line descriptive comments for each function.
    • Do not use #elif. Many older Unix C compilers cannot handle it.
    • Do not use the alloca function for allocating memory off the stack. Its use causes more portability trouble than is worth the minor benefit of not having to free the storage. Instead, use malloc and free.

    Note: If I have to reformat your code to follow the coding style used in gawk, I may not bother to integrate your changes at all.

  5. Be prepared to sign the appropriate paperwork. In order for the FSF to distribute your changes, you must either place those changes in the public domain and submit a signed statement to that effect, or assign the copyright in your changes to the FSF. Both of these actions are easy to do and many people have done so already. If you have questions, please contact me (see Reporting Problems and Bugs), or gnu@gnu.org.
  6. Update the documentation. Along with your new code, please supply new sections and/or chapters for this Web page. If at all possible, please use real Texinfo, instead of just supplying unformatted ASCII text (although even that is better than no documentation at all). Conventions to be followed in GAWK: Effective AWK Programming are provided after the @bye at the end of the Texinfo source file. If possible, please update the man page as well.

    You will also have to sign paperwork for your documentation changes.

  7. Submit changes as context diffs or unified diffs. Use diff -c -r -N or diff -u -r -N to compare the original gawk source tree with your version. (I find context diffs to be more readable but unified diffs are more compact.) I recommend using the GNU version of diff. Send the output produced by either run of diff to me when you submit your changes. (See Reporting Problems and Bugs, for the electronic mail information.)

    Using this format makes it easy for me to apply your changes to the master version of the gawk source code (using patch). If I have to apply the changes manually, using a text editor, I may not do so, particularly if there are lots of changes.

  8. Include an entry for the ChangeLog file with your submission. This helps further minimize the amount of work I have to do, making it easier for me to accept patches.

Although this sounds like a lot of work, please remember that while you may write the new code, I have to maintain it and support it. If it isn't possible for me to do that with a minimum of extra work, then I probably will not.

Node:New Ports, Previous:Adding Code, Up:Additions

Porting gawk to a New Operating System

If you want to port gawk to a new operating system, there are several steps:

  1. Follow the guidelines in the previous section concerning coding style, submission of diffs, and so on.
  2. When doing a port, bear in mind that your code must coexist peacefully with the rest of gawk and the other ports. Avoid gratuitous changes to the system-independent parts of the code. If at all possible, avoid sprinkling #ifdefs just for your port throughout the code.

    If the changes needed for a particular system affect too much of the code, I probably will not accept them. In such a case, you can, of course, distribute your changes on your own, as long as you comply with the GPL (see GNU General Public License).

  3. A number of the files that come with gawk are maintained by other people at the Free Software Foundation. Thus, you should not change them unless it is for a very good reason; i.e., changes are not out of the question, but changes to these files are scrutinized extra carefully. The files are getopt.h, getopt.c, getopt1.c, regex.h, regex.c, dfa.h, dfa.c, install-sh, and mkinstalldirs.
  4. Be willing to continue to maintain the port. Non-Unix operating systems are supported by volunteers who maintain the code needed to compile and run gawk on their systems. If noone volunteers to maintain a port, it becomes unsupported and it may be necessary to remove it from the distribution.
  5. Supply an appropriate gawkmisc.??? file. Each port has its own gawkmisc.??? that implements certain operating system specific functions. This is cleaner than a plethora of #ifdefs scattered throughout the code. The gawkmisc.c in the main source directory includes the appropriate gawkmisc.??? file from each subdirectory. Be sure to update it as well.

    Each port's gawkmisc.??? file has a suffix reminiscent of the machine or operating system for the port--for example, pc/gawkmisc.pc and vms/gawkmisc.vms. The use of separate suffixes, instead of plain gawkmisc.c, makes it possible to move files from a port's subdirectory into the main subdirectory, without accidentally destroying the real gawkmisc.c file. (Currently, this is only an issue for the PC operating system ports.)

  6. Supply a Makefile as well as any other C source and header files that are necessary for your operating system. All your code should be in a separate subdirectory, with a name that is the same as, or reminiscent of, either your operating system or the computer system. If possible, try to structure things so that it is not necessary to move files out of the subdirectory into the main source directory. If that is not possible, then be sure to avoid using names for your files that duplicate the names of files in the main source directory.
  7. Update the documentation. Please write a section (or sections) for this Web page describing the installation and compilation steps needed to compile and/or install gawk for your system.
  8. Be prepared to sign the appropriate paperwork. In order for the FSF to distribute your code, you must either place your code in the public domain and submit a signed statement to that effect, or assign the copyright in your code to the FSF.

Following these steps makes it much easier to integrate your changes into gawk and have them coexist happily with other operating systems' code that is already there.

In the code that you supply and maintain, feel free to use a coding style and brace layout that suits your taste.

Node:Dynamic Extensions, Next:Future Extensions, Previous:Additions, Up:Notes

Adding New Built-in Functions to gawk

Danger Will Robinson! Danger!!
Warning! Warning!
The Robot

Beginning with gawk 3.1, it is possible to add new built-in functions to gawk using dynamically loaded libraries. This facility is available on systems (such as GNU/Linux) that support the dlopen and dlsym functions. This section describes how to write and use dynamically loaded extentions for gawk. Experience with programming in C or C++ is necessary when reading this section.

Caution: The facilities described in this section are very much subject to change in the next gawk release. Be aware that you may have to re-do everything, perhaps from scratch, upon the next release.

  • Internals: A brief look at some gawk internals.
  • Sample Library: A example of new functions.

Node:Internals, Next:Sample Library, Previous:Dynamic Extensions, Up:Dynamic Extensions

A Minimal Introduction to gawk Internals

The truth is that gawk was not designed for simple extensibility. The facilities for adding functions using shared libraries work, but are something of a "bag on the side." Thus, this tour is brief and simplistic; would-be gawk hackers are encouraged to spend some time reading the source code before trying to write extensions based on the material presented here. Of particular note are the files awk.h, builtin.c, and eval.c. Reading awk.y in order to see how the parse tree is built would also be of use.

With the disclaimers out of the way, the following types, structure members, functions, and macros are declared in awk.h and are of use when writing extensions. The next section shows how they are used:

AWKNUM
An AWKNUM is the internal type of awk floating-point numbers. Typically, it is a C double.
NODE
Just about everything is done using objects of type NODE. These contain both strings and numbers, as well as variables and arrays.
AWKNUM force_number(NODE *n)
This macro forces a value to be numeric. It returns the actual numeric value contained in the node. It may end up calling an internal gawk function.
void force_string(NODE *n)
This macro guarantees that a NODE's string value is current. It may end up calling an internal gawk function. It also guarantees that the string is zero-terminated.
n->param_cnt
The number of parameters actually passed in a function call at runtime.
n->stptr
n->stlen
The data and length of a NODE's string value, respectively. The string is not guaranteed to be zero-terminated. If you need to pass the string value to a C library function, save the value in n->stptr[n->stlen], assign '\0' to it, call the routine, and then restore the value.
n->type
The type of the NODE. This is a C enum. Values should be either Node_var or Node_var_array for function parameters.
n->vname
The "variable name" of a node. This is not of much use inside externally written extensions.
void assoc_clear(NODE *n)
Clears the associative array pointed to by n. Make sure that n->type == Node_var_array first.
NODE **assoc_lookup(NODE *symbol, NODE *subs, int reference)
Finds, and installs if necessary, array elements. symbol is the array, subs is the subscript. This is usually a value created with tmp_string (see below). reference should be TRUE if it is an error to use the value before it is created. Typically, FALSE is the correct value to use from extension functions.
NODE *make_string(char *s, size_t len)
Take a C string and turn it into a pointer to a NODE that can be stored appropriately. This is permanent storage; understanding of gawk memory management is helpful.
NODE *make_number(AWKNUM val)
Take an AWKNUM and turn it into a pointer to a NODE that can be stored appropriately. This is permanent storage; understanding of gawk memory management is helpful.
NODE *tmp_string(char *s, size_t len);
Take a C string and turn it into a pointer to a NODE that can be stored appropriately. This is temporary storage; understanding of gawk memory management is helpful.
NODE *tmp_number(AWKNUM val)
Take an AWKNUM and turn it into a pointer to a NODE that can be stored appropriately. This is temporary storage; understanding of gawk memory management is helpful.
NODE *dupnode(NODE *n)
Duplicate a node. In most cases, this increments an internal reference count instead of actually duplicating the entire NODE; understanding of gawk memory management is helpful.
void free_temp(NODE *n)
This macro releases the memory associated with a NODE allocated with tmp_string or tmp_number. Understanding of gawk memory management is helpful.
void make_builtin(char *name, NODE *(*func)(NODE *), int count)
Register a C function pointed to by func as new built-in function name. name is a regular C string. count is the maximum number of arguments that the function takes. The function should be written in the following manner:
/* do_xxx --- do xxx function for gawk */

NODE *
do_xxx(NODE *tree)
{
    ...
}

NODE *get_argument(NODE *tree, int i)
This function is called from within a C extension function to get the i-th argument from the function call. The first argument is argument zero.
void set_value(NODE *tree)
This function is called from within a C extension function to set the return value from the extension function. This value is what the awk program sees as the return value from the new awk function.
void update_ERRNO(void)
This function is called from within a C extension function to set the value of gawk's ERRNO variable, based on the current value of the C errno variable. It is provided as a convenience.

An argument that is supposed to be an array needs to be handled with some extra code, in case the array being passed in is actually from a function parameter. The following boilerplate code shows how to do this:

NODE *the_arg;

the_arg = get_argument(tree, 2); /* assume need 3rd arg, 0-based */

/* if a parameter, get it off the stack */
if (the_arg->type == Node_param_list)
    the_arg = stack_ptr[the_arg->param_cnt];

/* parameter referenced an array, get it */
if (the_arg->type == Node_array_ref)
    the_arg = the_arg->orig_array;

/* check type */
if (the_arg->type != Node_var && the_arg->type != Node_var_array)
    fatal("newfunc: third argument is not an array");

/* force it to be an array, if necessary, clear it */
the_arg->type = Node_var_array;
assoc_clear(the_arg);

Again, you should spend time studying the gawk internals; don't just blindly copy this code.

Node:Sample Library, Previous:Internals, Up:Dynamic Extensions

Directory and File Operation Built-ins

Two useful functions that are not in awk are chdir (so that an awk program can change its directory) and stat (so that an awk program can gather information about a file). This section implements these functions for gawk in an external extension library.

  • Internal File Description: What the new functions will do.
  • Internal File Ops: The code for internal file operations.
  • Using Internal File Ops: How to use an external extension.

Node:Internal File Description, Next:Internal File Ops, Previous:Sample Library, Up:Sample Library
Using chdir and stat

This section shows how to use the new functions at the awk level once they've been integrated into the running gawk interpreter. Using chdir is very straightforward. It takes one argument, the new directory to change to:

...
newdir = "/home/arnold/funstuff"
ret = chdir(newdir)
if (ret < 0) {
    printf("could not change to %s: %s\n",
                   newdir, ERRNO) > "/dev/stderr"
    exit 1
}
...

The return value is negative if the chdir failed, and ERRNO (see Built-in Variables) is set to a string indicating the error.

Using stat is a bit more complicated. The C stat function fills in a structure that has a fair amount of information. The right way to model this in awk is to fill in an associative array with the appropriate information:

file = "/home/arnold/.profile"
fdata[1] = "x"    # force `fdata' to be an array
ret = stat(file, fdata)
if (ret < 0) {
    printf("could not stat %s: %s\n",
             file, ERRNO) > "/dev/stderr"
    exit 1
}
printf("size of %s is %d bytes\n", file, fdata["size"])

The stat function always clears the data array, even if the stat fails. It fills in the following elements:

"name"
The name of the file that was stat'ed.
"dev"
"ino"
The file's device and inode numbers, respectively.
"mode"
The file's mode, as a numeric value. This includes both the file's type and its permissions.
"nlink"
The number of hard links (directory entries) the file has.
"uid"
"gid"
The numeric user and group ID numbers of the file's owner.
"size"
The size in bytes of the file.
"blocks"
The number of disk blocks the file actually occupies. This may not be a function of the file's size if the file has holes.
"atime"
"mtime"
"ctime"
The file's last access, modification, and inode update times, respectively. These are numeric timestamps, suitable for formatting with strftime (see Built-in Functions).
"pmode"
The file's "printable mode." This is a string representation of the file's type and permissions, such as what is produced by ls -l--for example, "drwxr-xr-x".
"type"
A printable string representation of the file's type. The value is one of the following:
"blockdev"
"chardev"
The file is a block or character device ("special file").
"directory"
The file is a directory.
"fifo"
The file is a named-pipe (also known as a FIFO).
"file"
The file is just a regular file.
"socket"
The file is an AF_UNIX ("Unix domain") socket in the filesystem.
"symlink"
The file is a symbolic link.

Several additional elements may be present depending upon the operating system and the type of the file. You can test for them in your awk program by using the in operator (see Referring to an Array Element):

"blksize"
The preferred block size for I/O to the file. This field is not present on all POSIX-like systems in the C stat structure.
"linkval"
If the file is a symbolic link, this element is the name of the file the link points to (i.e., the value of the link).
"rdev"
"major"
"minor"
If the file is a block or character device file, then these values represent the numeric device number and the major and minor components of that number, respectively.

Node:Internal File Ops, Next:Using Internal File Ops, Previous:Internal File Description, Up:Sample Library
C Code for chdir and stat

Here is the C code for these extensions. They were written for GNU/Linux. The code needs some more work for complete portability to other POSIX-compliant systems:66

#include "awk.h"

#include <sys/sysmacros.h>

/*  do_chdir --- provide dynamically loaded
                 chdir() builtin for gawk */

static NODE *
do_chdir(tree)
NODE *tree;
{
    NODE *newdir;
    int ret = -1;

    newdir = get_argument(tree, 0);

The file includes the "awk.h" header file for definitions for the gawk internals. It includes <sys/sysmacros.h> for access to the major and minor macros.

By convention, for an awk function foo, the function that implements it is called do_foo. The function should take a NODE * argument, usually called tree, that represents the argument list to the function. The newdir variable represents the new directory to change to, retrieved with get_argument. Note that the first argument is numbered zero.

This code actually accomplishes the chdir. It first forces the argument to be a string and passes the string value to the chdir system call. If the chdir fails, ERRNO is updated. The result of force_string has to be freed with free_temp:

    if (newdir != NULL) {
        (void) force_string(newdir);
        ret = chdir(newdir->stptr);
        if (ret < 0)
            update_ERRNO();

        free_temp(newdir);
    }

Finally, the function returns the return value to the awk level, using set_value. Then it must return a value from the call to the new built-in (this value ignored by the interpreter):

    /* Set the return value */
    set_value(tmp_number((AWKNUM) ret));

    /* Just to make the interpreter happy */
    return tmp_number((AWKNUM) 0);
}

The stat built-in is more involved. First comes a function that turns a numeric mode into a printable representation (e.g., 644 becomes -rw-r--r--). This is omitted here for brevity:

/* format_mode --- turn a stat mode field
                   into something readable */

static char *
format_mode(fmode)
unsigned long fmode;
{
    ...
}

Next comes the actual do_stat function itself. First come the variable declarations and argument checking:

/* do_stat --- provide a stat() function for gawk */

static NODE *
do_stat(tree)
NODE *tree;
{
    NODE *file, *array;
    struct stat sbuf;
    int ret;
    char *msg;
    NODE **aptr;
    char *pmode;    /* printable mode */
    char *type = "unknown";

    /* check arg count */
    if (tree->param_cnt != 2)
        fatal(
    "stat: called with %d arguments, should be 2",
            tree->param_cnt);

Then comes the actual work. First, we get the arguments. Then, we always clear the array. To get the file information, we use lstat, in case the file is a symbolic link. If there's an error, we set ERRNO and return:

    /*
     * directory is first arg,
     * array to hold results is second
     */
    file = get_argument(tree, 0);
    array = get_argument(tree, 1);

    /* empty out the array */
    assoc_clear(array);

    /* lstat the file, if error, set ERRNO and return */
    (void) force_string(file);
    ret = lstat(file->stptr, & sbuf);
    if (ret < 0) {
        update_ERRNO();

        set_value(tmp_number((AWKNUM) ret));

        free_temp(file);
        return tmp_number((AWKNUM) 0);
    }

Now comes the tedious part: filling in the array. Only a few of the calls are shown here, since they all follow the same pattern:

    /* fill in the array */
    aptr = assoc_lookup(array, tmp_string("name", 4), FALSE);
    *aptr = dupnode(file);

    aptr = assoc_lookup(array, tmp_string("mode", 4), FALSE);
    *aptr = make_number((AWKNUM) sbuf.st_mode);

    aptr = assoc_lookup(array, tmp_string("pmode", 5), FALSE);
    pmode = format_mode(sbuf.st_mode);
    *aptr = make_string(pmode, strlen(pmode));

When done, we free the temporary value containing the file name, set the return value, and return:

    free_temp(file);

    /* Set the return value */
    set_value(tmp_number((AWKNUM) ret));

    /* Just to make the interpreter happy */
    return tmp_number((AWKNUM) 0);
}

Finally, it's necessary to provide the "glue" that loads the new function(s) into gawk. By convention, each library has a routine named dlload that does the job:

/* dlload --- load new builtins in this library */

NODE *
dlload(tree, dl)
NODE *tree;
void *dl;
{
    make_builtin("chdir", do_chdir, 1);
    make_builtin("stat", do_stat, 2);
    return tmp_number((AWKNUM) 0);
}

And that's it! As an exercise, consider adding functions to implement system calls such as chown, chmod, and umask.

Node:Using Internal File Ops, Previous:Internal File Ops, Up:Sample Library
Integrating the Extensions

Now that the code is written, it must be possible to add it at runtime to the running gawk interpreter. First, the code must be compiled. Assuming that the functions are in a file named filefuncs.c, and idir is the location of the gawk include files, the following steps create a GNU/Linux shared library:

$ gcc -shared -DHAVE_CONFIG_H -c -O -g -Iidir filefuncs.c
$ ld -o filefuncs.so -shared filefuncs.o

Once the library exists, it is loaded by calling the extension built-in function. This function takes two arguments: the name of the library to load and the name of a function to call when the library is first loaded. This function adds the new functions to gawk. It returns the value returned by the initialization function within the shared library:

# file testff.awk
BEGIN {
    extension("./filefuncs.so", "dlload")

    chdir(".")  # no-op

    data[1] = 1 # force `data' to be an array
    print "Info for testff.awk"
    ret = stat("testff.awk", data)
    print "ret =", ret
    for (i in data)
        printf "data[\"%s\"] = %s\n", i, data[i]
    print "testff.awk modified:",
        strftime("%m %d %y %H:%M:%S", data["mtime"])
}

Here are the results of running the program:

$ gawk -f testff.awk
-| Info for testff.awk
-| ret = 0
-| data["blksize"] = 4096
-| data["mtime"] = 932361936
-| data["mode"] = 33188
-| data["type"] = file
-| data["dev"] = 2065
-| data["gid"] = 10
-| data["ino"] = 878597
-| data["ctime"] = 971431797
-| data["blocks"] = 2
-| data["nlink"] = 1
-| data["name"] = testff.awk
-| data["atime"] = 971608519
-| data["pmode"] = -rw-r--r--
-| data["size"] = 607
-| data["uid"] = 2076
-| testff.awk modified: 07 19 99 08:25:36

Node:Future Extensions, Previous:Dynamic Extensions, Up:Notes

Probable Future Extensions

AWK is a language similar to PERL, only considerably more elegant.
Arnold Robbins

Hey!
Larry Wall

This section briefly lists extensions and possible improvements that indicate the directions we are currently considering for gawk. The file FUTURES in the gawk distribution lists these extensions as well.

Following is a list of probable future changes visible at the awk language level:

Loadable module interface
It is not clear that the awk-level interface to the modules facility is as good as it should be. The interface needs to be redesigned, particularly taking namespace issues into account, as well as possibly including issues such as library search path order and versioning.
RECLEN variable for fixed-length records
Along with FIELDWIDTHS, this would speed up the processing of fixed-length records. PROCINFO["RS"] would be "RS" or "RECLEN", depending upon which kind of record processing is in effect.
Additional printf specifiers
The 1999 ISO C standard added a number of additional printf format specifiers. These should be evaluated for possible inclusion in gawk.
Databases
It may be possible to map a GDBM/NDBM/SDBM file into an awk array.
Large character sets
It would be nice if gawk could handle UTF-8 and other character sets that are larger than eight bits.
More lint warnings
There are more things that could be checked for portability.

Following is a list of probable improvements that will make gawk's source code easier to work with:

Loadable module mechanics
The current extension mechanism works (see Adding New Built-in Functions to gawk), but is rather primitive. It requires a fair amount of manual work to create and integrate a loadable module. Nor is the current mechanism as portable as might be desired. The GNU libtool package provides a number of features that would make using loadable modules much easier. gawk should be changed to use libtool.
Loadable module internals
The API to its internals that gawk "exports" should be revised. Too many things are needlessly exposed. A new API should be designed and implemented to make module writing easier.
Better array subscript management
gawk's management of array subscript storage could use revamping, so that using the same value to index multiple arrays only stores one copy of the index value.
Integrating the DBUG library
Integrating Fred Fish's DBUG library would be helpful during development, but it's a lot of work to do.

Following is a list of probable improvements that will make gawk perform better:

An improved version of dfa
The dfa pattern matcher from GNU grep has some problems. Either a new version or a fixed one will deal with some important regexp matching issues.
Compilation of awk programs
gawk uses a Bison (YACC-like) parser to convert the script given it into a syntax tree; the syntax tree is then executed by a simple recursive evaluator. This method incurs a lot of overhead, since the recursive evaluator performs many procedure calls to do even the simplest things.

It should be possible for gawk to convert the script's parse tree into a C program which the user would then compile, using the normal C compiler and a special gawk library to provide all the needed functions (regexps, fields, associative arrays, type coercion, and so on).

An easier possibility might be for an intermediate phase of gawk to convert the parse tree into a linear byte code form like the one used in GNU Emacs Lisp. The recursive evaluator would then be replaced by a straight line byte code interpreter that would be intermediate in speed between running a compiled program and doing what gawk does now.

Finally, the programs in the test suite could use documenting in this Web page.

See Making Additions to gawk, if you are interested in tackling any of these projects.

Node:Basic Concepts, Next:Glossary, Previous:Notes, Up:Top

Basic Programming Concepts

This appendix attempts to define some of the basic concepts and terms that are used throughout the rest of this Web page. As this Web page is specifically about awk, and not about computer programming in general, the coverage here is by necessity fairly cursory and simplistic. (If you need more background, there are many other introductory texts that you should refer to instead.)

  • Basic High Level: The high level view.
  • Basic Data Typing: A very quick intro to data types.
  • Floating Point Issues: Stuff to know about floating-point numbers.

Node:Basic High Level, Next:Basic Data Typing, Previous:Basic Concepts, Up:Basic Concepts

What a Program Does

At the most basic level, the job of a program is to process some input data and produce results.

                  _______
+------+         /       \         +---------+
| Data | -----> < Program > -----> | Results |
+------+         \_______/         +---------+

The "program" in the figure can be either a compiled program67 (such as ls), or it may be interpreted. In the latter case, a machine-executable program such as awk reads your program, and then uses the instructions in your program to process the data.

When you write a program, it usually consists of the following, very basic set of steps:

                              ______
+----------------+           / More \  No       +----------+
| Initialization | -------> <  Data  > -------> | Clean Up |
+----------------+    ^      \   ?  /           +----------+
                      |       +--+-+
                      |          | Yes
                      |          |
                      |          V
                      |     +---------+
                      +-----+ Process |
                            +---------+
Initialization
These are the things you do before actually starting to process data, such as checking arguments, initializing any data you need to work with, and so on. This step corresponds to awk's BEGIN rule (see The BEGIN and END Special Patterns).

If you were baking a cake, this might consist of laying out all the mixing bowls and the baking pan, and making sure you have all the ingredients that you need.

Processing
This is where the actual work is done. Your program reads data, one logical chunk at a time, and processes it as appropriate.

In most programming languages, you have to manually manage the reading of data, checking to see if there is more each time you read a chunk. awk's pattern-action paradigm (see Getting Started with awk) handles the mechanics of this for you.

In baking a cake, the processing corresponds to the actual labor: breaking eggs, mixing the flour, water, and other ingredients, and then putting the cake into the oven.

Clean Up
Once you've processed all the data, you may have things you need to do before exiting. This step corresponds to awk's END rule (see The BEGIN and END Special Patterns).

After the cake comes out of the oven, you still have to wrap it in plastic wrap to keep anyone from tasting it, as well as wash the mixing bowls and utensils.

An algorithm is a detailed set of instructions necessary to accomplish a task, or process data. It is much the same as a recipe for baking a cake. Programs implement algorithms. Often, it is up to you to design the algorithm and implement it, simultaneously.

The "logical chunks" we talked about previously are called records, similar to the records a company keeps on employees, a school keeps for students, or a doctor keeps for patients. Each record has many component parts, such as first and last names, date of birth, address, and so on. The component parts are referred to as the fields of the record.

The act of reading data is termed input, and that of generating results, not too surprisingly, is termed output. They are often referred to together as "input/output," and even more often, as "I/O" for short. (You will also see "input" and "output" used as verbs.)

awk manages the reading of data for you, as well as the breaking it up into records and fields. Your program's job is to tell awk what to with the data. You do this by describing patterns in the data to look for, and actions to execute when those patterns are seen. This data-driven nature of awk programs usually makes them both easier to write and easier to read.

Node:Basic Data Typing, Next:Floating Point Issues, Previous:Basic High Level, Up:Basic Concepts

Data Values in a Computer

In a program, you keep track of information and values in things called variables. A variable is just a name for a given value, such as first_name, last_name, address, and so on. awk has several predefined variables, and it has special names to refer to the current input record and the fields of the record. You may also group multiple associated values under one name, as an array.

Data, particularly in awk, consists of either numeric values, such as 42 or 3.1415927, or string values. String values are essentially anything that's not a number, such as a name. Strings are sometimes referred to as character data, since they store the individual characters that comprise them. Individual variables, as well as numeric and string variables, are referred to as scalar values. Groups of values, such as arrays, are not scalars.

Within computers, there are two kinds of numeric values: integers and floating-point. In school, integer values were referred to as "whole" numbers--that is, numbers without any fractional part, such as 1, 42, or -17. The advantage to integer numbers is that they represent values exactly. The disadvantage is that their range is limited. On most modern systems, this range is -2,147,483,648 to 2,147,483,647.

Integer values come in two flavors: signed and unsigned. Signed values may be negative or positive, with the range of values just described. Unsigned values are always positive. On most modern systems, the range is from 0 to 4,294,967,295.

Floating-point numbers represent what are called "real" numbers; i.e., those that do have a fractional part, such as 3.1415927. The advantage to floating-point numbers is that they can represent a much larger range of values. The disadvantage is that there are numbers that they cannot represent exactly. awk uses double-precision floating-point numbers, which can hold more digits than single-precision floating-point numbers. Floating-point issues are discussed more fully in Floating-Point Number Caveats.

At the very lowest level, computers store values as groups of binary digits, or bits. Modern computers group bits into groups of eight, called bytes. Advanced applications sometimes have to manipulate bits directly, and gawk provides functions for doing so.

While you are probably used to the idea of a number without a value (i.e., zero), it takes a bit more getting used to the idea of zero-length character data. Nevertheless, such a thing exists. It is called the null string. The null string is character data that has no value. In other words, it is empty. It is written in awk programs like this: "".

Humans are used to working in decimal; i.e., base 10. In base 10, numbers go from 0 to 9, and then "roll over" into the next column. (Remember grade school? 42 is 4 times 10 plus 2.)

There are other number bases though. Computers commonly use base 2 or binary, base 8 or octal, and base 16 or hexadecimal. In binary, each column represents two times the value in the column to its right. Each column may contain either a 0 or a 1. Thus, binary 1010 represents 1 times 8, plus 0 times 4, plus 1 times 2, plus 0 times 1, or decimal 10. Octal and hexadecimal are discussed more in Octal and Hexadecimal Numbers.

Programs are written in programming languages. Hundreds, if not thousands, of programming languages exist. One of the most popular is the C programming language. The C language had a very strong influence on the design of the awk language.

There have been several versions of C. The first is often referred to as "K&R" C, after the initials of Brian Kernighan and Dennis Ritchie, the authors of the first book on C. (Dennis Ritchie created the language, and Brian Kernighan was one of the creators of awk.)

In the mid-1980s, an effort began to produce an international standard for C. This work culminated in 1989, with the production of the ANSI standard for C. This standard became an ISO standard in 1990. Where it makes sense, POSIX awk is compatible with 1990 ISO C.

In 1999, a revised ISO C standard was approved and released. Future versions of gawk will be as compatible as possible with this standard.

Node:Floating Point Issues, Previous:Basic Data Typing, Up:Basic Concepts

Floating-Point Number Caveats

As mentioned earlier, floating-point numbers represent what are called "real" numbers, i.e., those that have a fractional part. awk uses double-precision floating-point numbers to represent all numeric values. This section describes some of the issues involved in using floating-point numbers.

There is a very nice paper on floating-point arithmetic by David Goldberg, "What Every Computer Scientist Should Know About Floating-point Arithmetic," ACM Computing Surveys 23, 1 (1991-03), 5-48.68 This is worth reading if you are interested in the details, but it does require a background in computer science.

Internally, awk keeps both the numeric value (double-precision floating-point) and the string value for a variable. Separately, awk keeps track of what type the variable has (see Variable Typing and Comparison Expressions), which plays a role in how variables are used in comparisons.

It is important to note that the string value for a number may not reflect the full value (all the digits) that the numeric value actually contains. The following program (values.awk) illustrates this:

{
   $1 = $2 + $3
   # see it for what it is
   printf("$1 = %.12g\n", $1)
   # use CONVFMT
   a = "<" $1 ">"
   print "a =", a
   # use OFMT
   print "$1 =", $1
}

This program shows the full value of the sum of $2 and $3 using printf, and then prints the string values obtained from both automatic conversion (via CONVFMT) and from printing (via OFMT).

Here is what happens when the program is run:

$ echo 2 3.654321 1.2345678 | awk -f values.awk
-| $1 = 4.8888888
-| a = <4.88889>
-| $1 = 4.88889

This makes it clear that the full numeric value is different from what the default string representations show.

CONVFMT's default value is "%.6g", which yields a value with at least six significant digits. For some applications, you might want to change it to specify more precision. On most modern machines, most of the time, 17 digits is enough to capture a floating-point number's value exactly.69

Unlike numbers in the abstract sense (such as what you studied in high school or college math), numbers stored in computers are limited in certain ways. They cannot represent an infinite number of digits, nor can they always represent things exactly. In particular, floating-point numbers cannot always represent values exactly. Here is an example:

$ awk '{ printf("%010d\n", $1 * 100) }'
515.79
-| 0000051579
515.80
-| 0000051579
515.81
-| 0000051580
515.82
-| 0000051582
Ctrl-d

This shows that some values can be represented exactly, whereas others are only approximated. This is not a "bug" in awk, but simply an artifact of how computers represent numbers.

Another peculiarity of floating-point numbers on modern systems is that they often have more than one representation for the number zero! In particular, it is possible to represent "minus zero" as well as regular, or "positive" zero.

This example shows that negative and positive zero are distinct values when stored internally, but that they are in fact equal to each other, as well as to "regular" zero:

$ gawk 'BEGIN { mz = -0 ; pz = 0
> printf "-0 = %g, +0 = %g, (-0 == +0) -> %d\n", mz, pz, mz == pz
> printf "mz == 0 -> %d, pz == 0 -> %d\n", mz == 0, pz == 0
> }'
-| -0 = -0, +0 = 0, (-0 == +0) -> 1
-| mz == 0 -> 1, pz == 0 -> 1

It helps to keep this in mind should you process numeric data that contains negative zero values; the fact that the zero is negative is noted and can affect comparisons.

Node:Glossary, Next:Copying, Previous:Basic Concepts, Up:Top

Glossary

Action
A series of awk statements attached to a rule. If the rule's pattern matches an input record, awk executes the rule's action. Actions are always enclosed in curly braces. (See Actions.)
Amazing awk Assembler
Henry Spencer at the University of Toronto wrote a retargetable assembler completely as sed and awk scripts. It is thousands of lines long, including machine descriptions for several eight-bit microcomputers. It is a good example of a program that would have been better written in another language. You can get it from ftp://ftp.freefriends.org/arnold/Awkstuff/aaa.tgz.
Amazingly Workable Formatter (awf)
Henry Spencer at the University of Toronto wrote a formatter that accepts a large subset of the nroff -ms and nroff -man formatting commands, using awk and sh. It is available over the Internet from ftp://ftp.freefriends.org/arnold/Awkstuff/awf.tgz.
Anchor
The regexp metacharacters ^ and $, which force the match to the beginning or end of the string, respectively.
ANSI
The American National Standards Institute. This organization produces many standards, among them the standards for the C and C++ programming languages. These standards often become international standards as well. See also "ISO."
Array
A grouping of multiple values under the same name. Most languages just provide sequential arrays. awk provides associative arrays.
Assertion
A statement in a program that a condition is true at this point in the program. Useful for reasoning about how a program is supposed to behave.
Assignment
An awk expression that changes the value of some awk variable or data object. An object that you can assign to is called an lvalue. The assigned values are called rvalues. See Assignment Expressions.
Associative Array
Arrays in which the indices may be numbers or strings, not just sequential integers in a fixed range.
awk Language
The language in which awk programs are written.
awk Program
An awk program consists of a series of patterns and actions, collectively known as rules. For each input record given to the program, the program's rules are all processed in turn. awk programs may also contain function definitions.
awk Script
Another name for an awk program.
Bash
The GNU version of the standard shell (the Bourne-Again SHell). See also "Bourne Shell."
BBS
See "Bulletin Board System."
Bit
Short for "Binary Digit." All values in computer memory ultimately reduce to binary digits: values that are either zero or one. Groups of bits may be interpreted differently--as integers, floating-point numbers, character data, addresses of other memory objects, or other data. awk lets you work with floating-point numbers and strings. gawk lets you manipulate bit values with the built-in functions described in Using gawk's Bit Manipulation Functions.

Computers are often defined by how many bits they use to represent integer values. Typical systems are 32-bit systems, but 64-bit systems are becoming increasingly popular, and 16-bit systems are waning in popularity.

Boolean Expression
Named after the English mathematician Boole. See also "Logical Expression."
Bourne Shell
The standard shell (/bin/sh) on Unix and Unix-like systems, originally written by Steven R. Bourne. Many shells (bash, ksh, pdksh, zsh) are generally upwardly compatible with the Bourne shell.
Built-in Function
The awk language provides built-in functions that perform various numerical, I/O-related, and string computations. Examples are sqrt (for the square root of a number) and substr (for a substring of a string). gawk provides functions for timestamp management, bit manipulation, and runtime string translation. (See Built-in Functions.)
Built-in Variable
ARGC, ARGV, CONVFMT, ENVIRON, FILENAME, FNR, FS, NF, NR, OFMT, OFS, ORS, RLENGTH, RSTART, RS, and SUBSEP are the variables that have special meaning to awk. In addition, ARGIND, BINMODE, ERRNO, FIELDWIDTHS, IGNORECASE, LINT, PROCINFO, RT, and TEXTDOMAIN are the variables that have special meaning to gawk. Changing some of them affects awk's running environment. (See Built-in Variables.)
Braces
See "Curly Braces."
Bulletin Board System
A computer system allowing users to log in and read and/or leave messages for other users of the system, much like leaving paper notes on a bulletin board.
C
The system programming language that most GNU software is written in. The awk programming language has C-like syntax, and this Web page points out similarities between awk and C when appropriate.

In general, gawk attempts to be as similar to the 1990 version of ISO C as makes sense. Future versions of gawk may adopt features from the newer 1999 standard, as appropriate.

C++
A popular object-oriented programming language derived from C.
Character Set
The set of numeric codes used by a computer system to represent the characters (letters, numbers, punctuation, etc.) of a particular country or place. The most common character set in use today is ASCII (American Standard Code for Information Interchange). Many European countries use an extension of ASCII known as ISO-8859-1 (ISO Latin-1).
CHEM
A preprocessor for pic that reads descriptions of molecules and produces pic input for drawing them. It was written in awk by Brian Kernighan and Jon Bentley, and is available from http://cm.bell-labs.com/netlib/typesetting/chem.gz.
Coprocess
A subordinate program with which two-way communications is possible.
Compiler
A program that translates human-readable source code into machine-executable object code. The object code is then executed directly by the computer. See also "Interpreter."
Compound Statement
A series of awk statements, enclosed in curly braces. Compound statements may be nested. (See Control Statements in Actions.)
Concatenation
Concatenating two strings means sticking them together, one after another, producing a new string. For example, the string foo concatenated with the string bar gives the string foobar. (See String Concatenation.)
Conditional Expression
An expression using the ?: ternary operator, such as expr1 ? expr2 : expr3. The expression expr1 is evaluated; if the result is true, the value of the whole expression is the value of expr2; otherwise the value is expr3. In either case, only one of expr2 and expr3 is evaluated. (See Conditional Expressions.)
Comparison Expression
A relation that is either true or false, such as (a < b). Comparison expressions are used in if, while, do, and for statements, and in patterns to select which input records to process. (See Variable Typing and Comparison Expressions.)
Curly Braces
The characters { and }. Curly braces are used in awk for delimiting actions, compound statements, and function bodies.
Dark Corner
An area in the language where specifications often were (or still are) not clear, leading to unexpected or undesirable behavior. Such areas are marked in this Web page with "(d.c.)" in the text and are indexed under the heading "dark corner."
Data Driven
A description of awk programs, where you specify the data you are interested in processing, and what to do when that data is seen.
Data Objects
These are numbers and strings of characters. Numbers are converted into strings and vice versa, as needed. (See Conversion of Strings and Numbers.)
Deadlock
The situation in which two communicating processes are each waiting for the other to perform an action.
Double-Precision
An internal representation of numbers that can have fractional parts. Double-precision numbers keep track of more digits than do single-precision numbers, but operations on them are sometimes more expensive. This is the way awk stores numeric values. It is the C type double.
Dynamic Regular Expression
A dynamic regular expression is a regular expression written as an ordinary expression. It could be a string constant, such as "foo", but it may also be an expression whose value can vary. (See Using Dynamic Regexps.)
Environment
A collection of strings, of the form name=val, that each program has available to it. Users generally place values into the environment in order to provide information to various programs. Typical examples are the environment variables HOME and PATH.
Empty String
See "Null String."
Epoch
The date used as the "beginning of time" for timestamps. Time values in Unix systems are represented as seconds since the epoch, with library functions available for converting these values into standard date and time formats.

The epoch on Unix and POSIX systems is 1970-01-01 00:00:00 UTC. See also "GMT" and "UTC."

Escape Sequences
A special sequence of characters used for describing nonprinting characters, such as \n for newline or \033 for the ASCII ESC (Escape) character. (See Escape Sequences.)
FDL
See "Free Documentation License."
Field
When awk reads an input record, it splits the record into pieces separated by whitespace (or by a separator regexp that you can change by setting the built-in variable FS). Such pieces are called fields. If the pieces are of fixed length, you can use the built-in variable FIELDWIDTHS to describe their lengths. (See Specifying How Fields Are Separated, and Reading Fixed-Width Data.)
Flag
A variable whose truth value indicates the existence or nonexistence of some condition.
Floating-Point Number
Often referred to in mathematical terms as a "rational" or real number, this is just a number that can have a fractional part. See also "Double-Precision" and "Single-Precision."
Format
Format strings are used to control the appearance of output in the strftime and sprintf functions, and are used in the printf statement as well. Also, data conversions from numbers to strings are controlled by the format string contained in the built-in variable CONVFMT. (See Format-Control Letters.)
Free Documentation License
This document describes the terms under which this Web page is published and may be copied. (See GNU Free Documentation License.)
Function
A specialized group of statements used to encapsulate general or program-specific tasks. awk has a number of built-in functions, and also allows you to define your own. (See Functions.)
FSF
See "Free Software Foundation."
Free Software Foundation
A nonprofit organization dedicated to the production and distribution of freely distributable software. It was founded by Richard M. Stallman, the author of the original Emacs editor. GNU Emacs is the most widely used version of Emacs today.
gawk
The GNU implementation of awk.
General Public License
This document describes the terms under which gawk and its source code may be distributed. (See GNU General Public License.)
GMT
"Greenwich Mean Time." This is the old term for UTC. It is the time of day used as the epoch for Unix and POSIX systems. See also "Epoch" and "UTC."
GNU
"GNU's not Unix". An on-going project of the Free Software Foundation to create a complete, freely distributable, POSIX-compliant computing environment.
GNU/Linux
A variant of the GNU system using the Linux kernel, instead of the Free Software Foundation's Hurd kernel. Linux is a stable, efficient, full-featured clone of Unix that has been ported to a variety of architectures. It is most popular on PC-class systems, but runs well on a variety of other systems too. The Linux kernel source code is available under the terms of the GNU General Public License, which is perhaps its most important aspect.
GPL
See "General Public License."
Hexadecimal
Base 16 notation, where the digits are 0-9 and A-F, with A representing 10, B representing 11, and so on, up to F for 15. Hexadecimal numbers are written in C using a leading 0x, to indicate their base. Thus, 0x12 is 18 (1 times 16 plus 2).
I/O
Abbreviation for "Input/Output," the act of moving data into and/or out of a running program.
Input Record
A single chunk of data that is read in by awk. Usually, an awk input record consists of one line of text. (See How Input Is Split into Records.)
Integer
A whole number, i.e., a number that does not have a fractional part.
Internationalization
The process of writing or modifying a program so that it can use multiple languages without requiring further source code changes.
Interpreter
A program that reads human-readable source code directly, and uses the instructions in it to process data and produce results. awk is typically (but not always) implemented as an interpreter. See also "Compiler."
Interval Expression
A component of a regular expression that lets you specify repeated matches of some part of the regexp. Interval expressions were not traditionally available in awk programs.
ISO
The International Standards Organization. This organization produces international standards for many things, including programming languages, such as C and C++. In the computer arena, important standards like those for C, C++, and POSIX become both American national and ISO international standards simultaneously. This Web page refers to Standard C as "ISO C" throughout.
Keyword
In the awk language, a keyword is a word that has special meaning. Keywords are reserved and may not be used as variable names.

gawk's keywords are: BEGIN, END, if, else, while, do...while, for, for...in, break, continue, delete, next, nextfile, function, func, and exit.

Lesser General Public License
This document describes the terms under which binary library archives or shared objects, and their source code may be distributed.
Linux
See "GNU/Linux."
LGPL
See "Lesser General Public License."
Localization
The process of providing the data necessary for an internationalized program to work in a particular language.
Logical Expression
An expression using the operators for logic, AND, OR, and NOT, written &&, ||, and ! in awk. Often called Boolean expressions, after the mathematician who pioneered this kind of mathematical logic.
Lvalue
An expression that can appear on the left side of an assignment operator. In most languages, lvalues can be variables or array elements. In awk, a field designator can also be used as an lvalue.
Matching
The act of testing a string against a regular expression. If the regexp describes the contents of the string, it is said to match it.
Metacharacters
Characters used within a regexp that do not stand for themselves. Instead, they denote regular expression operations, such as repetition, grouping, or alternation.
Null String
A string with no characters in it. It is represented explicitly in awk programs by placing two double quote characters next to each other (""). It can appear in input data by having two successive occurrences of the field separator appear next to each other.
Number
A numeric-valued data object. Modern awk implementations use double-precision floating-point to represent numbers. Very old awk implementations use single-precision floating-point.
Octal
Base-eight notation, where the digits are 0-7. Octal numbers are written in C using a leading 0, to indicate their base. Thus, 013 is 11 (one times 8 plus 3).
P1003.2
See "POSIX."
Pattern
Patterns tell awk which input records are interesting to which rules.

A pattern is an arbitrary conditional expression against which input is tested. If the condition is satisfied, the pattern is said to match the input record. A typical pattern might compare the input record against a regular expression. (See Pattern Elements.)

POSIX
The name for a series of standards that specify a Portable Operating System interface. The "IX" denotes the Unix heritage of these standards. The main standard of interest for awk users is IEEE Standard for Information Technology, Standard 1003.2-1992, Portable Operating System Interface (POSIX) Part 2: Shell and Utilities. Informally, this standard is often referred to as simply "P1003.2."
Precedence
The order in which operations are performed when operators are used without explicit parentheses.
Private
Variables and/or functions that are meant for use exclusively by library functions and not for the main awk program. Special care must be taken when naming such variables and functions. (See Naming Library Function Global Variables.)
Range (of input lines)
A sequence of consecutive lines from the input file(s). A pattern can specify ranges of input lines for awk to process or it can specify single lines. (See Pattern Elements.)
Recursion
When a function calls itself, either directly or indirectly. If this isn't clear, refer to the entry for "recursion."
Redirection
Redirection means performing input from something other than the standard input stream, or performing output to something other than the standard output stream.

You can redirect the output of the print and printf statements to a file or a system command, using the >, >>, |, and |& operators. You can redirect input to the getline statement using the <, |, and |& operators. (See Redirecting Output of print and printf, and Explicit Input with getline.)

Regexp
Short for regular expression. A regexp is a pattern that denotes a set of strings, possibly an infinite set. For example, the regexp R.*xp matches any string starting with the letter R and ending with the letters xp. In awk, regexps are used in patterns and in conditional expressions. Regexps may contain escape sequences. (See Regular Expressions.)
Regular Expression
See "regexp."
Regular Expression Constant
A regular expression constant is a regular expression written within slashes, such as /foo/. This regular expression is chosen when you write the awk program and cannot be changed during its execution. (See How to Use Regular Expressions.)
Rule
A segment of an awk program that specifies how to process single input records. A rule consists of a pattern and an action. awk reads an input record; then, for each rule, if the input record satisfies the rule's pattern, awk executes the rule's action. Otherwise, the rule does nothing for that input record.
Rvalue
A value that can appear on the right side of an assignment operator. In awk, essentially every expression has a value. These values are rvalues.
Scalar
A single value, be it a number or a string. Regular variables are scalars; arrays and functions are not.
Search Path
In gawk, a list of directories to search for awk program source files. In the shell, a list of directories to search for executable programs.
Seed
The initial value, or starting point, for a sequence of random numbers.
sed
See "Stream Editor."
Shell
The command interpreter for Unix and POSIX-compliant systems. The shell works both interactively, and as a programming language for batch files, or shell scripts.
Short-Circuit
The nature of the awk logical operators && and ||. If the value of the entire expression is determinable from evaluating just the lefthand side of these operators, the righthand side is not evaluated. (See Boolean Expressions.)
Side Effect
A side effect occurs when an expression has an effect aside from merely producing a value. Assignment expressions, increment and decrement expressions, and function calls have side effects. (See Assignment Expressions.)
Single-Precision
An internal representation of numbers that can have fractional parts. Single-precision numbers keep track of fewer digits than do double-precision numbers, but operations on them are sometimes less expensive in terms of CPU time. This is the type used by some very old versions of awk to store numeric values. It is the C type float.
Space
The character generated by hitting the space bar on the keyboard.
Special File
A file name interpreted internally by gawk, instead of being handed directly to the underlying operating system--for example, /dev/stderr. (See Special File Names in gawk.)
Stream Editor
A program that reads records from an input stream and processes them one or more at a time. This is in contrast with batch programs, which may expect to read their input files in entirety before starting to do anything, as well as with interactive programs which require input from the user.
String
A datum consisting of a sequence of characters, such as I am a string. Constant strings are written with double quotes in the awk language and may contain escape sequences. (See Escape Sequences.)
Tab
The character generated by hitting the TAB key on the keyboard. It usually expands to up to eight spaces upon output.
Text Domain
A unique name that identifies an application. Used for grouping messages that are translated at runtime into the local language.
Timestamp
A value in the "seconds since the epoch" format used by Unix and POSIX systems. Used for the gawk functions mktime, strftime, and systime. See also "Epoch" and "UTC."
Unix
A computer operating system originally developed in the early 1970's at AT&T Bell Laboratories. It initially became popular in universities around the world and later moved into commercial environments as a software development system and network server system. There are many commercial versions of Unix, as well as several work-alike systems whose source code is freely available (such as GNU/Linux, NetBSD, FreeBSD, and OpenBSD).
UTC
The accepted abbreviation for "Universal Coordinated Time." This is standard time in Greenwich, England, which is used as a reference time for day and date calculations. See also "Epoch" and "GMT."
Whitespace
A sequence of space, TAB, or newline characters occurring inside an input record or a string.

Node:Copying, Next:GNU Free Documentation License, Previous:Glossary, Up:Top

GNU General Public License

Version 2, June 1991

Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

Terms and Conditions for Copying, Distribution and Modification

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and an idea of what it does.
Copyright (C) year  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License.

Node:GNU Free Documentation License, Next:Index, Previous:Copying, Up:Top

GNU Free Documentation License

Version 1.1, March 2000

Copyright (C) 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties-for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.
If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Node:Index, Previous:GNU Free Documentation License, Up:Top

Index

  • ! (exclamation point), ! operator: Boolean Ops
  • ! (exclamation point), ! operator: Egrep Program, Precedence
  • ! (exclamation point), != operator: Precedence, Typing and Comparison
  • ! (exclamation point), !~ operator: Expression Patterns, Precedence, Typing and Comparison, Regexp Constants, Computed Regexps, Case-sensitivity, Regexp Usage
  • ! operator: Egrep Program, Ranges
  • " (double quote): Quoting, Read Terminal
  • " (double quote), regexp constants: Computed Regexps
  • # (number sign), #! (executable scripts): Executable Scripts
  • # (number sign), #! (executable scripts), portability issues with: Executable Scripts
  • # (number sign), commenting: Comments
  • $ (dollar sign): Regexp Operators
  • $ (dollar sign), $ field operator: Precedence, Fields
  • $ (dollar sign), incrementing fields and arrays: Increment Ops
  • $ field operator: Fields
  • % (percent sign), % operator: Precedence
  • % (percent sign), %= operator: Precedence, Assignment Ops
  • & (ampersand), && operator: Precedence, Boolean Ops
  • & (ampersand), gsub/gensub/sub functions and: Gory Details
  • ' (single quote): Quoting, Long, One-shot
  • ' (single quote), vs. apostrophe: Comments
  • ' (single quote), with double quotes: Quoting
  • () (parentheses): Regexp Operators
  • () (parentheses), pgawk program: Profiling
  • * (asterisk), * operator, as multiplication operator: Precedence
  • * (asterisk), * operator, as regexp operator: Regexp Operators
  • * (asterisk), * operator, null strings, matching: Gory Details
  • * (asterisk), ** operator: Options, Precedence, Arithmetic Ops
  • * (asterisk), **= operator: Options, Precedence, Assignment Ops
  • * (asterisk), *= operator: Precedence, Assignment Ops
  • + (plus sign): Regexp Operators
  • + (plus sign), + operator: Precedence
  • + (plus sign), ++ operator: Precedence, Increment Ops
  • + (plus sign), += operator: Precedence, Assignment Ops
  • + (plus sign), decrement/increment operators: Increment Ops
  • , (comma), in range patterns: Ranges
  • - (hyphen), - operator: Precedence
  • - (hyphen), -- (decrement/increment) operator: Precedence
  • - (hyphen), -- operator: Increment Ops
  • - (hyphen), -= operator: Precedence, Assignment Ops
  • - (hyphen), filenames beginning with: Options
  • - (hyphen), in character lists: Character Lists
  • --assign option: Options
  • --compat option: Options
  • --copyleft option: Options
  • --copyright option: Options
  • --disable-nls configuration option: Additional Configuration Options
  • --dump-variables option: Library Names, Options
  • --enable-portals configuration option: Additional Configuration Options, Portal Files
  • --field-separator option: Options
  • --file option: Options
  • --gen-po option: Options, String Extraction
  • --help option: Options
  • --lint option: Options, Command Line
  • --lint-old option: Options
  • --non-decimal-data option: Options, Nondecimal Data
  • --non-decimal-data option, strtonum function and: Nondecimal Data
  • --posix option: Options
  • --posix option, --traditional option and: Options
  • --profile option: Options, Profiling
  • --re-interval option: Options
  • --source option: Options
  • --traditional option: Options
  • --traditional option, --posix option and: Options
  • --usage option: Options
  • --version option: Options
  • --with-included-gettext configuration option: Additional Configuration Options, Gawk I18N
  • --with-included-gettext configuration option, configuring gawk with: Additional Configuration Options
  • -f option: Options
  • -F option: Options, Command Line Field Separator
  • -f option: Long
  • -F option, -Ft sets FS to TAB: Options
  • -f option, on command line: Options
  • -F option, troubleshooting: Known Bugs
  • -mf/-mr options: Options
  • -v option: Options
  • -v option, variables, assigning: Assignment Options
  • -W option: Options
  • . (period): Regexp Operators
  • .mo files: Explaining gettext
  • .mo files, converting from .po: I18N Example
  • .mo files, specifying directory of: Programmer i18n, Explaining gettext
  • .po files: Translator i18n, Explaining gettext
  • .po files, converting to .mo: I18N Example
  • / (forward slash): Regexp
  • / (forward slash), / operator: Precedence
  • / (forward slash), /= operator: Precedence, Assignment Ops
  • / (forward slash), /= operator, vs. /=.../ regexp constant: Assignment Ops
  • / (forward slash), patterns and: Expression Patterns
  • /= operator vs. /=.../ regexp constant: Assignment Ops
  • /dev/... special files (gawk): Special FD
  • /inet/ files (gawk): TCP/IP Networking
  • /p files (gawk): Portal Files
  • ; (semicolon): Statements/Lines
  • ; (semicolon), AWKPATH variable and: PC Using
  • ; (semicolon), separating statements in actions: Statements, Action Overview
  • < (left angle bracket), < operator: Precedence, Typing and Comparison
  • < (left angle bracket), < operator (I/O): Getline/File
  • < (left angle bracket), <= operator: Precedence, Typing and Comparison
  • = (equals sign), = operator: Assignment Ops
  • = (equals sign), == operator: Precedence, Typing and Comparison
  • > (right angle bracket), > operator: Precedence, Typing and Comparison
  • > (right angle bracket), > operator (I/O): Redirection
  • > (right angle bracket), >= operator: Precedence, Typing and Comparison
  • > (right angle bracket), >> operator (I/O): Precedence, Redirection
  • ? (question mark): GNU Regexp Operators, Regexp Operators
  • ? (question mark), ?: operator: Precedence
  • [] (square brackets): Regexp Operators
  • \ (backslash): Regexp Operators, Quoting, Comments, Read Terminal
  • \ (backslash), \" escape sequence: Escape Sequences
  • \ (backslash), \' operator (gawk): GNU Regexp Operators
  • \ (backslash), \/ escape sequence: Escape Sequences
  • \ (backslash), \< operator (gawk): GNU Regexp Operators
  • \ (backslash), \> operator (gawk): GNU Regexp Operators
  • \ (backslash), \` operator (gawk): GNU Regexp Operators
  • \ (backslash), \a escape sequence: Escape Sequences
  • \ (backslash), \b escape sequence: Escape Sequences
  • \ (backslash), \B operator (gawk): GNU Regexp Operators
  • \ (backslash), \f escape sequence: Escape Sequences
  • \ (backslash), \n escape sequence: Escape Sequences
  • \ (backslash), \nnn escape sequence: Escape Sequences
  • \ (backslash), \r escape sequence: Escape Sequences
  • \ (backslash), \t escape sequence: Escape Sequences
  • \ (backslash), \v escape sequence: Escape Sequences
  • \ (backslash), \W operator (gawk): GNU Regexp Operators
  • \ (backslash), \w operator (gawk): GNU Regexp Operators
  • \ (backslash), \x escape sequence: Escape Sequences
  • \ (backslash), \y operator (gawk): GNU Regexp Operators
  • \ (backslash), as field separators: Command Line Field Separator
  • \ (backslash), continuing lines and: Egrep Program, Statements/Lines
  • \ (backslash), continuing lines and, comments and: Statements/Lines
  • \ (backslash), continuing lines and, in csh: Statements/Lines, More Complex
  • \ (backslash), gsub/gensub/sub functions and: Gory Details
  • \ (backslash), in character lists: Character Lists
  • \ (backslash), in escape sequences: Escape Sequences
  • \ (backslash), in escape sequences, POSIX and: Escape Sequences
  • \ (backslash), regexp constants: Computed Regexps
  • ^ (caret): GNU Regexp Operators, Regexp Operators
  • ^ (caret), ^ operator: Options, Precedence
  • ^ (caret), ^= operator: Options, Precedence, Assignment Ops
  • ^ (caret), in character lists: Character Lists
  • _ (underscore), _ C macro: Explaining gettext
  • _ (underscore), in names of private variables: Library Names
  • _ (underscore), translatable string: Programmer i18n
  • _gr_init user-defined function: Group Functions
  • _pw_init user-defined function: Passwd Functions
  • accessing fields: Fields
  • account information: Group Functions, Passwd Functions
  • actions: Action Overview
  • actions, control statements in: Statements
  • actions, default: Very Simple
  • actions, empty: Very Simple
  • adding, features to gawk: Adding Code
  • adding, fields: Changing Fields
  • adding, functions to gawk: Dynamic Extensions
  • advanced features, buffering: I/O Functions
  • advanced features, close function: Close Files And Pipes
  • advanced features, constants, values of: Nondecimal-numbers
  • advanced features, data files as single record: Records
  • advanced features, fixed-width data: Constant Size
  • advanced features, FNR/NR variables: Auto-set
  • advanced features, gawk: Advanced Features
  • advanced features, gawk, BSD portals: Portal Files
  • advanced features, gawk, network programming: TCP/IP Networking
  • advanced features, gawk, nondecimal input data: Nondecimal Data
  • advanced features, gawk, processes, communicating with: Two-way I/O
  • advanced features, network connections, See Also networks, connections: Advanced Features
  • advanced features, null strings, matching: Gory Details
  • advanced features, operators, precedence: Increment Ops
  • advanced features, piping into sh: Redirection
  • advanced features, regexp constants: Assignment Ops
  • Aho, Alfred: Contributors, History
  • alarm clock example program: Alarm Program
  • alarm.awk program: Alarm Program
  • algorithms: Basic High Level
  • Alpha (DEC): Manual History
  • amazing awk assembler (aaa): Glossary
  • amazingly workable formatter (awf): Glossary
  • ambiguity, syntactic: /= operator vs. /=.../ regexp constant: Assignment Ops
  • amiga: Amiga Installation
  • ampersand (&), && operator: Boolean Ops
  • ampersand (&), &&operator: Precedence
  • ampersand (&), gsub/gensub/sub functions and: Gory Details
  • AND bitwise operation: Bitwise Functions
  • and Boolean-logic operator: Boolean Ops
  • and function (gawk): Bitwise Functions
  • ANSI: Glossary
  • archeologists: Bugs
  • ARGC/ARGV variables: ARGC and ARGV, Auto-set
  • ARGC/ARGV variables, command-line arguments: Other Arguments
  • ARGC/ARGV variables, portability and: Executable Scripts
  • ARGIND variable: Auto-set
  • ARGIND variable, command-line arguments: Other Arguments
  • arguments, command-line: Other Arguments, ARGC and ARGV, Auto-set
  • arguments, command-line, invoking awk: Command Line
  • arguments, in function calls: Function Calls
  • arguments, processing: Getopt Function
  • arguments, retrieving: Internals
  • arithmetic operators: Arithmetic Ops
  • arrays: Arrays
  • arrays, as parameters to functions: Function Caveats
  • arrays, associative: Array Intro
  • arrays, associative, clearing: Internals
  • arrays, associative, library functions and: Library Names
  • arrays, deleting entire contents: Delete
  • arrays, elements, assigning: Assigning Elements
  • arrays, elements, deleting: Delete
  • arrays, elements, installing: Internals
  • arrays, elements, order of: Scanning an Array
  • arrays, elements, referencing: Reference to Elements
  • arrays, elements, retrieving number of: String Functions
  • arrays, for statement and: Scanning an Array
  • arrays, IGNORECASE variable and: Array Intro
  • arrays, indexing: Array Intro
  • arrays, merging into strings: Join Function
  • arrays, multidimensional: Multi-dimensional
  • arrays, multidimensional, scanning: Multi-scanning
  • arrays, names of: Arrays
  • arrays, scanning: Scanning an Array
  • arrays, sorting: Array Sorting
  • arrays, sorting, IGNORECASE variable and: Array Sorting
  • arrays, sparse: Array Intro
  • arrays, subscripts: Numeric Array Subscripts
  • arrays, subscripts, uninitialized variables as: Uninitialized Subscripts
  • artificial intelligence, gawk and: Distribution contents
  • ASCII: Ordinal Functions
  • asort function (gawk): String Functions, Array Sorting
  • asort function (gawk), arrays, sorting: Array Sorting
  • assert function (C library): Assert Function
  • assert user-defined function: Assert Function
  • assertions: Assert Function
  • assignment operators: Assignment Ops
  • assignment operators, evaluation order: Assignment Ops
  • assignment operators, lvalues/rvalues: Assignment Ops
  • assignments as filenames: Ignoring Assigns
  • assoc_clear internal function: Internals
  • assoc_lookup internal function: Internals
  • associative arrays: Array Intro
  • asterisk (*), * operator, as multiplication operator: Precedence
  • asterisk (*), * operator, as regexp operator: Regexp Operators
  • asterisk (*), * operator, null strings, matching: Gory Details
  • asterisk (*), ** operator: Options, Precedence, Arithmetic Ops
  • asterisk (*), **= operator: Options, Precedence, Assignment Ops
  • asterisk (*), *= operator: Precedence, Assignment Ops
  • atan2 function: Numeric Functions
  • atari: Atari Installation
  • awf (amazingly workable formatter) program: Glossary
  • awk language, POSIX version: Assignment Ops
  • awk programs: Two Rules, Executable Scripts, Getting Started
  • awk programs, complex: When
  • awk programs, documenting: Library Names, Comments
  • awk programs, examples of: Sample Programs
  • awk programs, execution of: Next Statement
  • awk programs, internationalizing: Programmer i18n, I18N Functions
  • awk programs, lengthy: Long
  • awk programs, lengthy, assertions: Assert Function
  • awk programs, location of: Options
  • awk programs, one-line examples: Very Simple
  • awk programs, profiling: Profiling
  • awk programs, profiling, enabling: Options
  • awk programs, running: Long, Running gawk
  • awk programs, running, from shell scripts: One-shot
  • awk programs, running, without input files: Read Terminal
  • awk programs, shell variables in: Using Shell Variables
  • awk, function of: Getting Started
  • awk, gawk and: This Manual, Preface
  • awk, history of: History
  • awk, implementation issues, pipes: Redirection
  • awk, implementations: Other Versions
  • awk, implementations, limits: Getline Notes
  • awk, invoking: Command Line
  • awk, new vs. old: Names
  • awk, new vs. old, OFMT variable: Conversion
  • awk, POSIX and: Preface
  • awk, POSIX and, See Also POSIX awk: Preface
  • awk, regexp constants and: Typing and Comparison
  • awk, See Also gawk: Preface
  • awk, terms describing: This Manual
  • awk, uses for: When, Getting Started, Preface
  • awk, versions of: V7/SVR3.1, Names
  • awk, versions of, changes between SVR3.1 and SVR4: SVR4
  • awk, versions of, changes between SVR4 and POSIX awk: POSIX
  • awk, versions of, changes between V7 and SVR3.1: V7/SVR3.1
  • awk, versions of, See Also Bell Laboratories awk: BTL
  • awk.h file (internal): Internals
  • awka compiler for awk: Other Versions
  • AWKNUM internal type: Internals
  • AWKPATH environment variable: PC Using
  • AWKPATH environment variable: AWKPATH Variable
  • awkprof.out file: Profiling
  • awksed.awk program: Simple Sed
  • awkvars.out file: Options
  • backslash (\): Regexp Operators, Quoting, Comments, Read Terminal
  • backslash (\), \" escape sequence: Escape Sequences
  • backslash (\), \' operator (gawk): GNU Regexp Operators
  • backslash (\), \/ escape sequence: Escape Sequences
  • backslash (\), \< operator (gawk): GNU Regexp Operators
  • backslash (\), \> operator (gawk): GNU Regexp Operators
  • backslash (\), \` operator (gawk): GNU Regexp Operators
  • backslash (\), \a escape sequence: Escape Sequences
  • backslash (\), \b escape sequence: Escape Sequences
  • backslash (\), \B operator (gawk): GNU Regexp Operators
  • backslash (\), \f escape sequence: Escape Sequences
  • backslash (\), \n escape sequence: Escape Sequences
  • backslash (\), \nnn escape sequence: Escape Sequences
  • backslash (\), \r escape sequence: Escape Sequences
  • backslash (\), \t escape sequence: Escape Sequences
  • backslash (\), \v escape sequence: Escape Sequences
  • backslash (\), \W operator (gawk): GNU Regexp Operators
  • backslash (\), \w operator (gawk): GNU Regexp Operators
  • backslash (\), \x escape sequence: Escape Sequences
  • backslash (\), \y operator (gawk): GNU Regexp Operators
  • backslash (\), as field separators: Command Line Field Separator
  • backslash (\), continuing lines and: Egrep Program, Statements/Lines
  • backslash (\), continuing lines and, comments and: Statements/Lines
  • backslash (\), continuing lines and, in csh: Statements/Lines, More Complex
  • backslash (\), gsub/gensub/sub functions and: Gory Details
  • backslash (\), in character lists: Character Lists
  • backslash (\), in escape sequences: Escape Sequences
  • backslash (\), in escape sequences, POSIX and: Escape Sequences
  • backslash (\), regexp constants: Computed Regexps
  • BBS-list file: Sample Data Files
  • Beebe, Nelson: Acknowledgments
  • BEGIN pattern: BEGIN/END, Field Separators, Records
  • BEGIN pattern, assert user-defined function and: Assert Function
  • BEGIN pattern, Boolean patterns and: Expression Patterns
  • BEGIN pattern, exit statement and: Exit Statement
  • BEGIN pattern, getline and: Getline Notes
  • BEGIN pattern, headings, adding: Print Examples
  • BEGIN pattern, next/nextfile statements and: Next Statement, I/O And BEGIN/END
  • BEGIN pattern, OFS/ORS variables, assigning values to: Output Separators
  • BEGIN pattern, operators and: Using BEGIN/END
  • BEGIN pattern, pgawk program: Profiling
  • BEGIN pattern, print statement and: I/O And BEGIN/END
  • BEGIN pattern, pwcat program: Passwd Functions
  • BEGIN pattern, running awk programs and: Cut Program
  • BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n
  • beginfile user-defined function: Filetrans Function
  • Bell Laboratories awk extensions: BTL
  • BeOS: BeOS Installation
  • Berry, Karl: Acknowledgments
  • binary input/output: User-modified
  • bindtextdomain function (C library): Explaining gettext
  • bindtextdomain function (gawk): Programmer i18n, I18N Functions
  • bindtextdomain function (gawk), portability and: I18N Portability
  • BINMODE variable: PC Using, User-modified
  • bits2str user-defined function: Bitwise Functions
  • bitwise, complement: Bitwise Functions
  • bitwise, operations: Bitwise Functions
  • bitwise, shift: Bitwise Functions
  • body, in actions: Statements
  • body, in loops: While Statement
  • Boolean expressions: Boolean Ops
  • Boolean expressions, as patterns: Expression Patterns
  • Boolean operators, See Boolean expressions: Boolean Ops
  • Bourne shell, quoting rules for: Quoting
  • braces ({}), actions and: Action Overview
  • braces ({}), pgawk program: Profiling
  • braces ({}), statements, grouping: Statements
  • bracket expressions, See character lists: Regexp Operators
  • break statement: Break Statement
  • Brennan, Michael: Other Versions, Simple Sed, Two-way I/O, Delete
  • Broder, Alan J.: Contributors
  • Brown, Martin: Bugs, Contributors, Acknowledgments
  • BSD portals: Portal Files
  • BSD-based operating systems: Glossary
  • Buening, Andreas: Contributors, Acknowledgments
  • buffering, input/output: Two-way I/O, I/O Functions
  • buffering, interactive vs. noninteractive: I/O Functions
  • buffers, flushing: I/O Functions
  • buffers, operators for: GNU Regexp Operators
  • bug reports, email address, bug-gawk@gnu.org: Bugs
  • bug-gawk@gnu.org bug reporting address: Bugs
  • built-in functions: Functions
  • built-in functions, evaluation order: Calling Built-in
  • built-in variables: Built-in Variables
  • built-in variables, -v option, setting with: Options
  • built-in variables, conveying information: Auto-set
  • built-in variables, user-modifiable: User-modified
  • call by reference: Function Caveats
  • call by value: Function Caveats
  • caret (^): GNU Regexp Operators, Regexp Operators
  • caret (^), ^ operator: Options, Precedence
  • caret (^), ^= operator: Options, Precedence, Assignment Ops
  • caret (^), in character lists: Character Lists
  • case sensitivity, array indices and: Array Intro
  • case sensitivity, converting case: String Functions
  • case sensitivity, example programs: Library Functions
  • case sensitivity, gawk: Case-sensitivity
  • case sensitivity, regexps and: User-modified, Case-sensitivity
  • case sensitivity, string comparisons and: User-modified
  • character encodings: Ordinal Functions
  • character lists: Character Lists, Regexp Operators
  • character lists, character classes: Character Lists
  • character lists, collating elements: Character Lists
  • character lists, collating symbols: Character Lists
  • character lists, complemented: Regexp Operators
  • character lists, equivalence classes: Character Lists
  • character lists, non-ASCII: Character Lists
  • character lists, range expressions: Character Lists
  • character sets: Ordinal Functions
  • character sets (machine character encodings): Glossary
  • character sets, See Also character lists: Regexp Operators
  • characters, counting: Wc Program
  • characters, transliterating: Translate Program
  • characters, values of as numbers: Ordinal Functions
  • Chassell, Robert J.: Acknowledgments
  • chdir function, implementing in gawk: Sample Library
  • chem utility: Glossary
  • chr user-defined function: Ordinal Functions
  • Cliff random numbers: Cliff Random Function
  • cliff_rand user-defined function: Cliff Random Function
  • close function: I/O Functions, Close Files And Pipes, Getline/Pipe, Getline/Variable/File
  • close function, return values: Close Files And Pipes
  • close function, two-way pipes and: Two-way I/O
  • Close, Diane: Contributors, Manual History
  • collating elements: Character Lists
  • collating symbols: Character Lists
  • columns, aligning: Print Examples
  • columns, cutting: Cut Program
  • comma (,), in range patterns: Ranges
  • command line, arguments: Other Arguments, ARGC and ARGV, Auto-set
  • command line, formats: Running gawk
  • command line, FS on, setting: Command Line Field Separator
  • command line, invoking awk from: Command Line
  • command line, options: Options, Command Line Field Separator, Long
  • command line, options, end of: Options
  • command line, variables, assigning on: Assignment Options
  • command-line options, processing: Getopt Function
  • command-line options, string extraction: String Extraction
  • commenting: Comments
  • commenting, backslash continuation and: Statements/Lines
  • comp.lang.awk newsgroup: Bugs
  • comparison expressions: Typing and Comparison
  • comparison expressions, as patterns: Expression Patterns
  • comparison expressions, string vs. regexp: Typing and Comparison
  • compatibility mode (gawk), extensions: POSIX/GNU
  • compatibility mode (gawk), file names: Special Caveats
  • compatibility mode (gawk), hexadecimal numbers: Nondecimal-numbers
  • compatibility mode (gawk), octal numbers: Nondecimal-numbers
  • compatibility mode (gawk), specifying: Options
  • compiled programs: Glossary, Basic High Level
  • compl function (gawk): Bitwise Functions
  • complement, bitwise: Bitwise Functions
  • compound statements, control statements and: Statements
  • concatenating: Concatenation
  • conditional expressions: Conditional Exp
  • configuration option, --disable-nls: Additional Configuration Options
  • configuration option, --enable-portals: Additional Configuration Options
  • configuration option, --with-included-gettext: Additional Configuration Options, Gawk I18N
  • configuration options, gawk: Additional Configuration Options
  • constants, nondecimal: Nondecimal Data
  • constants, types of: Constants
  • continue statement: Continue Statement
  • control statements: Statements
  • converting, case: String Functions
  • converting, dates to timestamps: Time Functions
  • converting, during subscripting: Numeric Array Subscripts
  • converting, numbers: Conversion
  • converting, numbers, to strings: Bitwise Functions
  • converting, strings to numbers: Conversion
  • CONVFMT variable: User-modified, Conversion
  • CONVFMT variable, array subscripts and: Numeric Array Subscripts
  • coprocesses: Two-way I/O, Redirection
  • coprocesses, closing: Close Files And Pipes
  • coprocesses, getline from: Getline/Coprocess
  • cos function: Numeric Functions
  • counting: Wc Program
  • csh utility: Statements/Lines
  • csh utility, backslash continuation and: More Complex
  • csh utility, POSIXLY_CORRECT environment variable: Options
  • csh utility, |& operator, comparison with: Two-way I/O
  • ctime user-defined function: Function Example
  • currency symbols, localization: Explaining gettext
  • custom.h file: Configuration Philosophy
  • cut utility: Cut Program
  • cut.awk program: Cut Program
  • d.c., See dark corner: Conventions
  • dark corner: Glossary, Truth Values, Assignment Ops, Format Modifiers, Conventions
  • dark corner, array subscripts: Uninitialized Subscripts
  • dark corner, break statement: Break Statement
  • dark corner, close function: Close Files And Pipes
  • dark corner, command-line arguments: Assignment Options
  • dark corner, continue statement: Continue Statement
  • dark corner, CONVFMT variable: Conversion
  • dark corner, escape sequences: Other Arguments
  • dark corner, escape sequences, for metacharacters: Escape Sequences
  • dark corner, exit statement: Exit Statement
  • dark corner, field separators: Field Splitting Summary
  • dark corner, FILENAME variable: Auto-set, Getline Notes
  • dark corner, FNR/NR variables: Auto-set
  • dark corner, format-control characters: Control Letters
  • dark corner, FS as null string: Single Character Fields
  • dark corner, input files: Records
  • dark corner, invoking awk: Command Line
  • dark corner, multiline records: Multiple Line
  • dark corner, NF variable, decrementing: Changing Fields
  • dark corner, OFMT variable: OFMT
  • dark corner, regexp constants: Using Constant Regexps
  • dark corner, regexp constants, /= operator and: Assignment Ops
  • dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps
  • dark corner, split function: String Functions
  • dark corner, strings, storing: Records
  • data, fixed-width: Constant Size
  • data-driven languages: Basic High Level
  • database, group, reading: Group Functions
  • database, users, reading: Passwd Functions
  • date utility, GNU: Time Functions
  • date utility, POSIX: Time Functions
  • dates, converting to timestamps: Time Functions
  • dates, information related to, localization: Explaining gettext
  • Davies, Stephen: Bugs, Contributors
  • dcgettext function (gawk): Programmer i18n, I18N Functions
  • dcgettext function (gawk), portability and: I18N Portability
  • dcngettext function (gawk): Programmer i18n, I18N Functions
  • dcngettext function (gawk), portability and: I18N Portability
  • deadlocks: Two-way I/O
  • debugging gawk: Known Bugs
  • debugging gawk, bug reports: Bugs
  • decrement operators: Increment Ops
  • Deifik, Scott: Bugs, Contributors, Acknowledgments
  • delete statement: Delete
  • deleting elements in arrays: Delete
  • deleting entire arrays: Delete
  • differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV
  • differences in awk and gawk, ARGIND variable: Auto-set
  • differences in awk and gawk, array elements, deleting: Delete
  • differences in awk and gawk, AWKPATH environment variable: AWKPATH Variable
  • differences in awk and gawk, BEGIN/END patterns: I/O And BEGIN/END
  • differences in awk and gawk, BINMODE variable: PC Using, User-modified
  • differences in awk and gawk, close function: Close Files And Pipes
  • differences in awk and gawk, ERRNO variable: Auto-set
  • differences in awk and gawk, error messages: Special FD
  • differences in awk and gawk, FIELDWIDTHS variable: User-modified
  • differences in awk and gawk, function arguments (gawk): Calling Built-in
  • differences in awk and gawk, getline command: Getline
  • differences in awk and gawk, IGNORECASE variable: User-modified
  • differences in awk and gawk, implementation limitations: Redirection, Getline Notes
  • differences in awk and gawk, input/output operators: Redirection, Getline/Coprocess
  • differences in awk and gawk, line continuations: Conditional Exp
  • differences in awk and gawk, LINT variable: User-modified
  • differences in awk and gawk, match function: String Functions
  • differences in awk and gawk, next/nextfile statements: Nextfile Statement
  • differences in awk and gawk, print/printf statements: Format Modifiers
  • differences in awk and gawk, PROCINFO array: Auto-set
  • differences in awk and gawk, record separators: Records
  • differences in awk and gawk, regexp constants: Using Constant Regexps
  • differences in awk and gawk, regular expressions: Case-sensitivity
  • differences in awk and gawk, RS/RT variables: Records
  • differences in awk and gawk, RT variable: Auto-set
  • differences in awk and gawk, single-character fields: Single Character Fields
  • differences in awk and gawk, split function: String Functions
  • differences in awk and gawk, strings: Scalar Constants
  • differences in awk and gawk, strings, storing: Records
  • differences in awk and gawk, strtonum function (gawk): String Functions
  • differences in awk and gawk, TEXTDOMAIN variable: User-modified
  • differences in awk and gawk, trunc-mod operation: Arithmetic Ops
  • directories, changing: Sample Library
  • directories, searching: Igawk Program, AWKPATH Variable
  • division: Arithmetic Ops
  • do-while statement: Do Statement, Regexp Usage
  • documentation, of awk programs: Library Names
  • documentation, online: Manual History
  • documents, searching: Dupword Program
  • dollar sign ($): Regexp Operators
  • dollar sign ($), $ field operator: Precedence, Fields
  • dollar sign ($), incrementing fields and arrays: Increment Ops
  • double quote ("): Quoting, Read Terminal
  • double quote ("), regexp constants: Computed Regexps
  • double-precision floating-point: Basic Data Typing
  • Drepper, Ulrich: Acknowledgments
  • dupnode internal function: Internals
  • dupword.awk program: Dupword Program
  • EBCDIC: Ordinal Functions
  • egrep utility: Egrep Program, Character Lists
  • egrep.awk program: Egrep Program
  • elements in arrays: Reference to Elements
  • elements in arrays, assigning: Assigning Elements
  • elements in arrays, deleting: Delete
  • elements in arrays, order of: Scanning an Array
  • elements in arrays, scanning: Scanning an Array
  • email address for bug reports, bug-gawk@gnu.org: Bugs
  • EMISTERED: TCP/IP Networking
  • empty pattern: Empty
  • empty strings, See null strings: Regexp Field Splitting
  • END pattern: BEGIN/END
  • END pattern, assert user-defined function and: Assert Function
  • END pattern, backslash continuation and: Egrep Program
  • END pattern, Boolean patterns and: Expression Patterns
  • END pattern, exit statement and: Exit Statement
  • END pattern, next/nextfile statements and: Next Statement, I/O And BEGIN/END
  • END pattern, operators and: Using BEGIN/END
  • END pattern, pgawk program: Profiling
  • END pattern, print statement and: I/O And BEGIN/END
  • endfile user-defined function: Filetrans Function
  • endgrent function (C library): Group Functions
  • endgrent user-defined function: Group Functions
  • endpwent function (C library): Passwd Functions
  • endpwent user-defined function: Passwd Functions
  • ENVIRON variable: Auto-set
  • environment variables: Auto-set
  • epoch, definition of: Glossary
  • equals sign (=), = operator: Assignment Ops
  • equals sign (=), == operator: Precedence, Typing and Comparison
  • EREs (Extended Regular Expressions): Character Lists
  • ERRNO variable: Internals, Auto-set, Getline
  • error handling: Special FD
  • error handling, ERRNO variable and: Auto-set
  • error output: Special FD
  • escape processing, gsub/gensub/sub functions: Gory Details
  • escape sequences: Escape Sequences
  • escape sequences, unrecognized: Options
  • evaluation order: Increment Ops
  • evaluation order, concatenation: Concatenation
  • evaluation order, functions: Calling Built-in
  • examining fields: Fields
  • exclamation point (!), ! operator: Egrep Program, Precedence, Boolean Ops
  • exclamation point (!), != operator: Precedence, Typing and Comparison
  • exclamation point (!), !~ operator: Expression Patterns, Precedence, Typing and Comparison, Regexp Constants, Computed Regexps, Case-sensitivity, Regexp Usage
  • exit statement: Exit Statement
  • exp function: Numeric Functions
  • expand utility: Very Simple
  • expressions: Expressions
  • expressions, as patterns: Expression Patterns
  • expressions, assignment: Assignment Ops
  • expressions, Boolean: Boolean Ops
  • expressions, comparison: Typing and Comparison
  • expressions, conditional: Conditional Exp
  • expressions, matching, See comparison expressions: Typing and Comparison
  • expressions, selecting: Conditional Exp
  • Extended Regular Expressions (EREs): Character Lists
  • extension function (gawk): Using Internal File Ops
  • extensions, Bell Laboratories awk: BTL
  • extensions, in gawk, not in POSIX awk: POSIX/GNU
  • extensions, mawk: Other Versions
  • extract.awk program: Extract Program
  • extraction, of marked strings (internationalization): String Extraction
  • false, logical: Truth Values
  • FDL (Free Documentation License): GNU Free Documentation License
  • features, adding to gawk: Adding Code
  • features, advanced, See advanced features: Obsolete
  • features, deprecated: Obsolete
  • features, undocumented: Undocumented
  • Fenlason, Jay: Contributors, History
  • fflush function: I/O Functions
  • fflush function, unsupported: Options
  • field numbers: Nonconstant Fields
  • field operator $: Fields
  • field operators, dollar sign as: Fields
  • field separators: User-modified, Field Separators
  • field separators, choice of: Field Separators
  • field separators, FIELDWIDTHS variable and: User-modified
  • field separators, in multiline records: Multiple Line
  • field separators, on command line: Command Line Field Separator
  • field separators, POSIX and: Field Splitting Summary, Fields
  • field separators, regular expressions as: Regexp Field Splitting, Field Separators
  • field separators, See Also OFS: Changing Fields
  • field separators, spaces as: Cut Program
  • fields: Basic High Level, Fields, Reading Files
  • fields, adding: Changing Fields
  • fields, changing contents of: Changing Fields
  • fields, cutting: Cut Program
  • fields, examining: Fields
  • fields, number of: Fields
  • fields, numbers: Nonconstant Fields
  • fields, printing: Print Examples
  • fields, separating: Field Separators
  • fields, single-character: Single Character Fields
  • FIELDWIDTHS variable: User-modified, Constant Size
  • file descriptors: Special FD
  • file names, distinguishing: Auto-set
  • file names, in compatibility mode: Special Caveats
  • file names, standard streams in gawk: Special FD
  • FILENAME variable: Auto-set, Reading Files
  • FILENAME variable, getline, setting with: Getline Notes
  • filenames, assignments as: Ignoring Assigns
  • files, .mo: Explaining gettext
  • files, .mo, converting from .po: I18N Example
  • files, .mo, specifying directory of: Programmer i18n, Explaining gettext
  • files, .po: Translator i18n, Explaining gettext
  • files, .po, converting to .mo: I18N Example
  • files, /dev/... special files: Special FD
  • files, /inet/ (gawk): TCP/IP Networking
  • files, /p (gawk): Portal Files
  • files, as single records: Records
  • files, awk programs in: Long
  • files, awkprof.out: Profiling
  • files, awkvars.out: Options
  • files, closing: I/O Functions
  • files, descriptors, See file descriptors: Special FD
  • files, for process information: Special Process
  • files, group: Group Functions
  • files, information about, retrieving: Sample Library
  • files, initialization and cleanup: Filetrans Function
  • files, input, See input files: Read Terminal
  • files, log, timestamps in: Time Functions
  • files, managing: Data File Management
  • files, managing, data file boundaries: Filetrans Function
  • files, message object: Explaining gettext
  • files, message object, converting from portable object files: I18N Example
  • files, message object, specifying directory of: Programmer i18n, Explaining gettext
  • files, multiple passes over: Other Arguments
  • files, multiple, duplicating output into: Tee Program
  • files, output, See output files: Close Files And Pipes
  • files, password: Passwd Functions
  • files, portable object: Translator i18n, Explaining gettext
  • files, portable object, converting to message object files: I18N Example
  • files, portable object, generating: Options
  • files, portal: Portal Files
  • files, processing, ARGIND variable and: Auto-set
  • files, reading: Rewind Function
  • files, reading, multiline records: Multiple Line
  • files, searching for regular expressions: Egrep Program
  • files, skipping: File Checking
  • files, source, search path for: Igawk Program
  • files, splitting: Split Program
  • files, Texinfo, extracting programs from: Extract Program
  • Fish, Fred: Bugs, Contributors
  • fixed-width data: Constant Size
  • flag variables: Tee Program, Boolean Ops
  • floating-point: Floating Point Issues
  • floating-point, numbers: Basic Data Typing
  • floating-point, numbers, AWKNUM internal type: Internals
  • FNR variable: Auto-set, Records
  • FNR variable, changing: Auto-set
  • for statement: For Statement
  • for statement, in arrays: Scanning an Array
  • force_number internal function: Internals
  • force_string internal function: Internals
  • format specifiers, mixing regular with positional specifiers: Printf Ordering
  • format specifiers, printf statement: Control Letters
  • format specifiers, strftime function (gawk): Time Functions
  • format strings: Basic Printf
  • formats, numeric output: OFMT
  • formatting output: Printf
  • forward slash (/): Regexp
  • forward slash (/), / operator: Precedence
  • forward slash (/), /= operator: Precedence, Assignment Ops
  • forward slash (/), /= operator, vs. /=.../ regexp constant: Assignment Ops
  • forward slash (/), patterns and: Expression Patterns
  • Free Documentation License (FDL): GNU Free Documentation License
  • Free Software Foundation (FSF): Glossary, Getting, Manual History
  • free_temp internal macro: Internals
  • FreeBSD: Glossary
  • FS variable: User-modified, Field Separators
  • FS variable, --field-separator option and: Options
  • FS variable, as null string: Single Character Fields
  • FS variable, as TAB character: Options
  • FS variable, changing value of: Known Bugs, Field Separators
  • FS variable, running awk programs and: Cut Program
  • FS variable, setting from command line: Command Line Field Separator
  • FSF (Free Software Foundation): Glossary, Getting, Manual History
  • function calls: Function Calls
  • functions, arrays as parameters to: Function Caveats
  • functions, built-in: Functions, Function Calls
  • functions, built-in, adding to gawk: Dynamic Extensions
  • functions, built-in, evaluation order: Calling Built-in
  • functions, defining: Definition Syntax
  • functions, library: Library Functions
  • functions, library, assertions: Assert Function
  • functions, library, associative arrays and: Library Names
  • functions, library, C library: Getopt Function
  • functions, library, character values as numbers: Ordinal Functions
  • functions, library, Cliff random numbers: Cliff Random Function
  • functions, library, command-line options: Getopt Function
  • functions, library, example program for using: Igawk Program
  • functions, library, group database, reading: Group Functions
  • functions, library, managing data files: Data File Management
  • functions, library, managing time: Gettimeofday Function
  • functions, library, merging arrays into strings: Join Function
  • functions, library, nextfile statement: Nextfile Function
  • functions, library, rounding numbers: Round Function
  • functions, library, user database, reading: Passwd Functions
  • functions, names of: Definition Syntax, Arrays
  • functions, recursive: Definition Syntax
  • functions, return values, setting: Internals
  • functions, string-translation: I18N Functions
  • functions, undefined: Function Caveats
  • functions, user-defined: User-defined
  • functions, user-defined, calling: Function Caveats
  • functions, user-defined, counts: Profiling
  • functions, user-defined, library of: Library Functions
  • functions, user-defined, next/nextfile statements and: Nextfile Statement, Next Statement
  • G-d: Acknowledgments
  • Garfinkle, Scott: Contributors
  • gawk, awk and: This Manual, Preface
  • gawk, bitwise operations in: Bitwise Functions
  • gawk, break statement in: Break Statement
  • gawk, built-in variables and: Built-in Variables
  • gawk, character classes and: Character Lists
  • gawk, coding style in: Adding Code
  • gawk, command-line options: GNU Regexp Operators
  • gawk, comparison operators and: Typing and Comparison
  • gawk, configuring: Configuration Philosophy
  • gawk, configuring, options: Additional Configuration Options
  • gawk, continue statement in: Continue Statement
  • gawk, debugging: Known Bugs
  • gawk, distribution: Distribution contents
  • gawk, escape sequences: Escape Sequences
  • gawk, extensions, disabling: Options
  • gawk, features, adding: Adding Code
  • gawk, features, advanced: Advanced Features
  • gawk, fflush function in: I/O Functions
  • gawk, field separators and: User-modified
  • gawk, FIELDWIDTHS variable in: User-modified
  • gawk, file names in: Special Files
  • gawk, format-control characters: Control Letters
  • gawk, function arguments and: Calling Built-in
  • gawk, functions, adding: Dynamic Extensions
  • gawk, hexadecimal numbers and: Nondecimal-numbers
  • gawk, IGNORECASE variable in: User-modified
  • gawk, implementation issues: Notes
  • gawk, implementation issues, debugging: Compatibility Mode
  • gawk, implementation issues, downward compatibility: Compatibility Mode
  • gawk, implementation issues, limits: Getline Notes
  • gawk, implementation issues, pipes: Redirection
  • gawk, installing: Installation
  • gawk, internals: Internals
  • gawk, internationalization and, See internationalization: Internationalization
  • gawk, interpreter, adding code to: Future Extensions, Using Internal File Ops
  • gawk, interval expressions and: Regexp Operators
  • gawk, line continuation in: Conditional Exp
  • gawk, LINT variable in: User-modified
  • gawk, list of contributors to: Contributors
  • gawk, MS-DOS version of: PC Using
  • gawk, newlines in: Statements/Lines
  • gawk, next file statement in: Nextfile Statement
  • gawk, nextfile statement in: Nextfile Function, Nextfile Statement
  • gawk, octal numbers and: Nondecimal-numbers
  • gawk, OS/2 version of: PC Using
  • gawk, regexp constants and: Using Constant Regexps
  • gawk, regular expressions, case sensitivity: Case-sensitivity
  • gawk, regular expressions, operators: GNU Regexp Operators
  • gawk, regular expressions, precedence: Regexp Operators
  • gawk, See Also awk: Preface
  • gawk, source code, obtaining: Getting
  • gawk, splitting fields and: Constant Size
  • gawk, string-translation functions: I18N Functions
  • gawk, timestamps: Time Functions
  • gawk, uses for: Preface
  • gawk, versions of, information about, printing: Options
  • gawk, word-boundary operator: GNU Regexp Operators
  • General Public License (GPL): Glossary
  • General Public License, See GPL: Manual History
  • gensub function (gawk): String Functions, Using Constant Regexps
  • gensub function (gawk), escape processing: Gory Details
  • get_argument internal function: Internals
  • getgrent function (C library): Group Functions
  • getgrent user-defined function: Group Functions
  • getgrgid function (C library): Group Functions
  • getgrgid user-defined function: Group Functions
  • getgrnam function (C library): Group Functions
  • getgrnam user-defined function: Group Functions
  • getgruser function (C library): Group Functions
  • getgruser function, user-defined: Group Functions
  • getline command: Reading Files
  • getline command, _gr_init user-defined function: Group Functions
  • getline command, _pw_init function: Passwd Functions
  • getline command, coprocesses, using from: Close Files And Pipes, Getline/Coprocess
  • getline command, deadlock and: Two-way I/O
  • getline command, explicit input with: Getline
  • getline command, FILENAME variable and: Getline Notes
  • getline command, return values: Getline
  • getline command, variants: Getline Summary
  • getopt function (C library): Getopt Function
  • getopt user-defined function: Getopt Function
  • getpwent function (C library): Passwd Functions
  • getpwent user-defined function: Passwd Functions
  • getpwnam function (C library): Passwd Functions
  • getpwnam user-defined function: Passwd Functions
  • getpwuid function (C library): Passwd Functions
  • getpwuid user-defined function: Passwd Functions
  • getservbyname function (C library): TCP/IP Networking
  • gettext function (C library): Explaining gettext
  • gettext library: Explaining gettext
  • gettext library, locale categories: Explaining gettext
  • gettimeofday user-defined function: Gettimeofday Function
  • GNITS mailing list: Acknowledgments
  • GNU awk, See gawk: Preface
  • GNU Free Documentation License: GNU Free Documentation License
  • GNU General Public License: Glossary
  • GNU Lesser General Public License: Glossary
  • GNU long options: Options, Command Line
  • GNU long options, printing list of: Options
  • GNU Project: Glossary, Manual History
  • GNU/Linux: Glossary, Atari Compiling, Additional Configuration Options, I18N Example, Manual History
  • GPL (General Public License): Glossary, Manual History
  • GPL (General Public License), printing: Options
  • grcat program: Group Functions
  • Grigera, Juan: Bugs, Contributors
  • group database, reading: Group Functions
  • group file: Group Functions
  • groups, information about: Group Functions
  • gsub function: String Functions, Using Constant Regexps
  • gsub function, arguments of: String Functions
  • gsub function, escape processing: Gory Details
  • Hankerson, Darrel: Bugs, Contributors, Acknowledgments
  • Hartholz, Elaine: Acknowledgments
  • Hartholz, Marshall: Acknowledgments
  • Hasegawa, Isamu: Contributors, Acknowledgments
  • hexadecimal numbers: Nondecimal-numbers
  • hexadecimal, values, enabling interpretation of: Options
  • histsort.awk program: History Sorting
  • Hughes, Phil: Acknowledgments
  • HUP signal: Profiling
  • hyphen (-), - operator: Precedence
  • hyphen (-), -- (decrement/increment) operators: Precedence
  • hyphen (-), -- operator: Increment Ops
  • hyphen (-), -= operator: Precedence, Assignment Ops
  • hyphen (-), filenames beginning with: Options
  • hyphen (-), in character lists: Character Lists
  • id utility: Id Program
  • id.awk program: Id Program
  • if statement: If Statement, Regexp Usage
  • if statement, actions, changing: Ranges
  • igawk.sh program: Igawk Program
  • IGNORECASE variable: User-modified, Case-sensitivity
  • IGNORECASE variable, array sorting and: Array Sorting
  • IGNORECASE variable, array subscripts and: Array Intro
  • IGNORECASE variable, in example programs: Library Functions
  • implementation issues, gawk: Notes
  • implementation issues, gawk, debugging: Compatibility Mode
  • implementation issues, gawk, limits: Redirection, Getline Notes
  • in operator: Id Program, Precedence, Typing and Comparison
  • in operator, arrays and: Scanning an Array, Reference to Elements
  • increment operators: Increment Ops
  • index function: String Functions
  • indexing arrays: Array Intro
  • initialization, automatic: More Complex
  • input files: Reading Files
  • input files, closing: Close Files And Pipes
  • input files, counting elements in: Wc Program
  • input files, examples: Sample Data Files
  • input files, reading: Reading Files
  • input files, running awk without: Read Terminal
  • input files, skipping: Nextfile Function
  • input files, variable assignments and: Other Arguments
  • input pipeline: Getline/Pipe
  • input redirection: Getline/File
  • input, data, nondecimal: Nondecimal Data
  • input, explicit: Getline
  • input, files, See input files: Multiple Line
  • input, multiline records: Multiple Line
  • input, splitting into records: Records
  • input, standard: Special FD, Read Terminal
  • input/output, binary: User-modified
  • input/output, from BEGIN and END: I/O And BEGIN/END
  • input/output, two-way: Two-way I/O
  • insomnia, cure for: Alarm Program
  • installation, amiga: Amiga Installation
  • installation, atari: Atari Installation
  • installation, beos: BeOS Installation
  • installation, tandem: Tandem Installation
  • installation, vms: VMS Installation
  • installing gawk: Installation
  • int function: Numeric Functions
  • INT signal (MS-DOS): Profiling
  • integers: Basic Data Typing
  • integers, unsigned: Basic Data Typing
  • interacting with other programs: I/O Functions
  • internationalization: I18N and L10N, I18N Functions
  • internationalization, localization: Internationalization, User-modified
  • internationalization, localization, character classes: Character Lists
  • internationalization, localization, gawk and: Internationalization
  • internationalization, localization, locale categories: Explaining gettext
  • internationalization, localization, marked strings: Programmer i18n
  • internationalization, localization, portability and: I18N Portability
  • internationalizing a program: Explaining gettext
  • interpreted programs: Glossary, Basic High Level
  • interval expressions: Regexp Operators
  • inventory-shipped file: Sample Data Files
  • ISO: Glossary
  • ISO 8859-1: Glossary
  • ISO Latin-1: Glossary
  • Jacobs, Andrew: Passwd Functions
  • Jaegermann, Michal: Contributors, Acknowledgments
  • Jedi knights: Undocumented
  • join user-defined function: Join Function
  • Kahrs, Jürgen: Contributors, Acknowledgments
  • Kenobi, Obi-Wan: Undocumented
  • Kernighan, Brian: Basic Data Typing, Other Versions, Contributors, BTL, Concatenation, Acknowledgments, Conventions, History
  • kill command, dynamic profiling: Profiling
  • Knights, jedi: Undocumented
  • Kwok, Conrad: Contributors
  • labels.awk program: Labels Program
  • languages, data-driven: Basic High Level
  • LC_ALL locale category: Explaining gettext
  • LC_COLLATE locale category: Explaining gettext
  • LC_CTYPE locale category: Explaining gettext
  • LC_MESSAGES locale category: Explaining gettext
  • LC_MESSAGES locale category, bindtextdomain function (gawk): Programmer i18n
  • LC_MONETARY locale category: Explaining gettext
  • LC_NUMERIC locale category: Explaining gettext
  • LC_RESPONSE locale category: Explaining gettext
  • LC_TIME locale category: Explaining gettext
  • left angle bracket (<), < operator: Precedence, Typing and Comparison
  • left angle bracket (<), < operator (I/O): Getline/File
  • left angle bracket (<), <= operator: Precedence, Typing and Comparison
  • left shift, bitwise: Bitwise Functions
  • leftmost longest match: Multiple Line
  • length function: String Functions
  • Lesser General Public License (LGPL): Glossary
  • LGPL (Lesser General Public License): Glossary
  • libraries of awk functions: Library Functions
  • libraries of awk functions, assertions: Assert Function
  • libraries of awk functions, associative arrays and: Library Names
  • libraries of awk functions, character values as numbers: Ordinal Functions
  • libraries of awk functions, command-line options: Getopt Function
  • libraries of awk functions, example program for using: Igawk Program
  • libraries of awk functions, group database, reading: Group Functions
  • libraries of awk functions, managing, data files: Data File Management
  • libraries of awk functions, managing, time: Gettimeofday Function
  • libraries of awk functions, merging arrays into strings: Join Function
  • libraries of awk functions, nextfile statement: Nextfile Function
  • libraries of awk functions, rounding numbers: Round Function
  • libraries of awk functions, user database, reading: Passwd Functions
  • line breaks: Statements/Lines
  • line continuations: Boolean Ops
  • line continuations, gawk: Conditional Exp
  • line continuations, in print statement: Print Examples
  • line continuations, with C shell: More Complex
  • lines, blank, printing: Print
  • lines, counting: Wc Program
  • lines, duplicate, removing: History Sorting
  • lines, matching ranges of: Ranges
  • lines, skipping between markers: Ranges
  • lint checking: User-modified
  • lint checking, array elements: Delete
  • lint checking, array subscripts: Uninitialized Subscripts
  • lint checking, empty programs: Command Line
  • lint checking, issuing warnings: Options
  • lint checking, POSIXLY_CORRECT environment variable: Options
  • lint checking, undefined functions: Function Caveats
  • LINT variable: User-modified
  • Linux: Glossary, Atari Compiling, Additional Configuration Options, I18N Example, Manual History
  • locale categories: Explaining gettext
  • localization: I18N and L10N
  • localization, See internationalization, localization: I18N and L10N
  • log files, timestamps in: Time Functions
  • log function: Numeric Functions
  • logical false/true: Truth Values
  • logical operators, See Boolean expressions: Boolean Ops
  • login information: Passwd Functions
  • long options: Command Line
  • loops: While Statement
  • loops, continue statements and: For Statement
  • loops, count for header: Profiling
  • loops, exiting: Break Statement
  • loops, See Also while statement: While Statement
  • Lost In Space: Dynamic Extensions
  • ls utility: More Complex
  • lshift function (gawk): Bitwise Functions
  • lvalues/rvalues: Assignment Ops
  • mailing labels, printing: Labels Program
  • mailing list, GNITS: Acknowledgments
  • make_builtin internal function: Internals
  • make_number internal function: Internals
  • make_string internal function: Internals
  • mark parity: Ordinal Functions
  • marked string extraction (internationalization): String Extraction
  • marked strings, extracting: String Extraction
  • Marx, Groucho: Increment Ops
  • match function: String Functions
  • match function, RSTART/RLENGTH variables: String Functions
  • matching, expressions, See comparison expressions: Typing and Comparison
  • matching, leftmost longest: Multiple Line
  • matching, null strings: Gory Details
  • mawk program: Other Versions
  • memory, releasing: Internals
  • memory, setting limits: Options
  • message object files: Explaining gettext
  • message object files, converting from portable object files: I18N Example
  • message object files, specifying directory of: Programmer i18n, Explaining gettext
  • metacharacters, escape sequences for: Escape Sequences
  • mktime function (gawk): Time Functions
  • modifiers, in format specifiers: Format Modifiers
  • monetary information, localization: Explaining gettext
  • msgfmt utility: I18N Example
  • names, arrays/variables: Library Names, Arrays
  • names, functions: Library Names, Definition Syntax
  • namespace issues: Library Names, Arrays
  • namespace issues, functions: Definition Syntax
  • nawk utility: Names
  • negative zero: Floating Point Issues
  • NetBSD: Glossary
  • networks, programming: TCP/IP Networking
  • networks, support for: Special Network
  • newlines: Options, Boolean Ops, Statements/Lines
  • newlines, as field separators: Field Separators
  • newlines, as record separators: Records
  • newlines, in dynamic regexps: Computed Regexps
  • newlines, in regexp constants: Computed Regexps
  • newlines, printing: Print Examples
  • newlines, separating statements in actions: Statements, Action Overview
  • next file statement: POSIX/GNU
  • next file statement, deprecated: Obsolete
  • next file statement, in gawk: Nextfile Statement
  • next statement: Next Statement, Boolean Ops
  • next statement, BEGIN/END patterns and: I/O And BEGIN/END
  • next statement, user-defined functions and: Next Statement
  • nextfile statement: Nextfile Statement
  • nextfile statement, BEGIN/END patterns and: I/O And BEGIN/END
  • nextfile statement, implementing: Nextfile Function
  • nextfile statement, in gawk: Nextfile Statement
  • nextfile statement, next file statement and: Obsolete
  • nextfile statement, user-defined functions and: Nextfile Statement
  • nextfile user-defined function: Nextfile Function
  • NF variable: Auto-set, Fields
  • NF variable, decrementing: Changing Fields
  • noassign.awk program: Ignoring Assigns
  • NODE internal type: Internals
  • nodes, duplicating: Internals
  • not Boolean-logic operator: Boolean Ops
  • NR variable: Auto-set, Records
  • NR variable, changing: Auto-set
  • null strings: Basic Data Typing, Truth Values, Regexp Field Splitting, Records
  • null strings, array elements and: Delete
  • null strings, as array subscripts: Uninitialized Subscripts
  • null strings, converting numbers to strings: Conversion
  • null strings, matching: Gory Details
  • null strings, quoting and: Quoting
  • number sign (#), #! (executable scripts): Executable Scripts
  • number sign (#), #! (executable scripts), portability issues with: Executable Scripts
  • number sign (#), commenting: Comments
  • numbers: Internals
  • numbers, as array subscripts: Numeric Array Subscripts
  • numbers, as values of characters: Ordinal Functions
  • numbers, Cliff random: Cliff Random Function
  • numbers, converting: Conversion
  • numbers, converting, to strings: Bitwise Functions, User-modified
  • numbers, floating-point: Basic Data Typing
  • numbers, floating-point, AWKNUM internal type: Internals
  • numbers, hexadecimal: Nondecimal-numbers
  • numbers, NODE internal type: Internals
  • numbers, octal: Nondecimal-numbers
  • numbers, random: Numeric Functions
  • numbers, rounding: Round Function
  • numeric, constants: Scalar Constants
  • numeric, output format: OFMT
  • numeric, strings: Typing and Comparison
  • numeric, values: Internals
  • oawk utility: Names
  • obsolete features: Obsolete
  • octal numbers: Nondecimal-numbers
  • octal values, enabling interpretation of: Options
  • OFMT variable: User-modified, Conversion, OFMT
  • OFMT variable, POSIX awk and: OFMT
  • OFS variable: User-modified, Output Separators, Changing Fields
  • OpenBSD: Glossary
  • operating systems, BSD-based: Portal Files, Manual History
  • operating systems, PC, gawk on: PC Using
  • operating systems, PC, gawk on, installing: PC Installation
  • operating systems, porting gawk to: New Ports
  • operating systems, See Also GNU/Linux, PC operating systems, Unix: Installation
  • operations, bitwise: Bitwise Functions
  • operators, arithmetic: Arithmetic Ops
  • operators, assignment: Assignment Ops
  • operators, assignment, evaluation order: Assignment Ops
  • operators, Boolean, See Boolean expressions: Boolean Ops
  • operators, decrement/increment: Increment Ops
  • operators, GNU-specific: GNU Regexp Operators
  • operators, input/output: Precedence, Redirection, Getline/Coprocess, Getline/Pipe, Getline/File
  • operators, logical, See Boolean expressions: Boolean Ops
  • operators, precedence: Precedence, Increment Ops
  • operators, relational, See operators, comparison: Typing and Comparison
  • operators, short-circuit: Boolean Ops
  • operators, string: Concatenation
  • operators, string-matching: Regexp Usage
  • operators, string-matching, for buffers: GNU Regexp Operators
  • operators, word-boundary (gawk): GNU Regexp Operators
  • options, command-line: Options, Command Line Field Separator, Long
  • options, command-line, end of: Options
  • options, command-line, invoking awk: Command Line
  • options, command-line, processing: Getopt Function
  • options, deprecated: Obsolete
  • options, long: Options, Command Line
  • options, printing list of: Options
  • OR bitwise operation: Bitwise Functions
  • or Boolean-logic operator: Boolean Ops
  • or function (gawk): Bitwise Functions
  • ord user-defined function: Ordinal Functions
  • order of evaluation, concatenation: Concatenation
  • ORS variable: User-modified, Output Separators
  • output field separator, See OFS variable: Changing Fields
  • output record separator, See ORS variable: Output Separators
  • output redirection: Redirection
  • output, buffering: I/O Functions
  • output, duplicating into files: Tee Program
  • output, files, closing: Close Files And Pipes
  • output, format specifier, OFMT: OFMT
  • output, formatted: Printf
  • output, pipes: Redirection
  • output, printing, See printing: Printing
  • output, records: Output Separators
  • output, standard: Special FD
  • P1003.2 POSIX standard: Glossary
  • param_cnt internal variable: Internals
  • parameters, number of: Internals
  • parentheses (): Regexp Operators
  • parentheses (), pgawk program: Profiling
  • password file: Passwd Functions
  • patterns: Patterns and Actions
  • patterns, comparison expressions as: Expression Patterns
  • patterns, counts: Profiling
  • patterns, default: Very Simple
  • patterns, empty: Empty
  • patterns, expressions as: Regexp Patterns
  • patterns, ranges in: Ranges
  • patterns, regexp constants as: Expression Patterns
  • patterns, types of: Pattern Overview
  • PC operating systems, gawk on: PC Using
  • PC operating systems, gawk on, installing: PC Installation
  • percent sign (%), % operator: Precedence
  • percent sign (%), %= operator: Precedence, Assignment Ops
  • period (.): Regexp Operators
  • PERL: Future Extensions
  • Peters, Arno: Contributors
  • Peterson, Hal: Contributors
  • pgawk program: Profiling
  • pgawk program, awkprof.out file: Profiling
  • pgawk program, dynamic profiling: Profiling
  • pipes, closing: Close Files And Pipes
  • pipes, input: Getline/Pipe
  • pipes, output: Redirection
  • plus sign (+): Regexp Operators
  • plus sign (+), + operator: Precedence
  • plus sign (+), ++ operator: Precedence, Increment Ops
  • plus sign (+), += operator: Precedence, Assignment Ops
  • plus sign (+), decrement/increment operators: Increment Ops
  • portability: Escape Sequences
  • portability, #! (executable scripts): Executable Scripts
  • portability, ** operator and: Arithmetic Ops
  • portability, **= operator and: Assignment Ops
  • portability, ARGV variable: Executable Scripts
  • portability, backslash continuation and: Statements/Lines
  • portability, backslash in escape sequences: Escape Sequences
  • portability, close function and: Close Files And Pipes
  • portability, data files as single record: Records
  • portability, deleting array elements: Delete
  • portability, example programs: Library Functions
  • portability, fflush function and: I/O Functions
  • portability, functions, defining: Definition Syntax
  • portability, gawk: New Ports
  • portability, gettext library and: Explaining gettext
  • portability, internationalization and: I18N Portability
  • portability, length function: String Functions
  • portability, new awk vs. old awk: Conversion
  • portability, next statement in user-defined functions: Function Caveats
  • portability, NF variable, decrementing: Changing Fields
  • portability, operators: Increment Ops
  • portability, operators, not in POSIX awk: Precedence
  • portability, POSIXLY_CORRECT environment variable: Options
  • portability, substr function: String Functions
  • portable object files: Translator i18n, Explaining gettext
  • portable object files, converting to message object files: I18N Example
  • portable object files, generating: Options
  • portal files: Portal Files
  • porting gawk: New Ports
  • positional specifiers, printf statement: Printf Ordering, Format Modifiers
  • positional specifiers, printf statement, mixing with regular formats: Printf Ordering
  • positive zero: Floating Point Issues
  • POSIX awk: Assignment Ops, This Manual
  • POSIX awk, **= operator and: Assignment Ops
  • POSIX awk, < operator and: Getline/File
  • POSIX awk, arithmetic operators and: Arithmetic Ops
  • POSIX awk, backslashes in string constants: Escape Sequences
  • POSIX awk, BEGIN/END patterns: I/O And BEGIN/END
  • POSIX awk, break statement and: Break Statement
  • POSIX awk, changes in awk versions: POSIX
  • POSIX awk, character lists and: Character Lists
  • POSIX awk, character lists and, character classes: Character Lists
  • POSIX awk, continue statement and: Continue Statement
  • POSIX awk, CONVFMT variable and: User-modified
  • POSIX awk, date utility and: Time Functions
  • POSIX awk, field separators and: Field Splitting Summary, Fields
  • POSIX awk, FS variable and: User-modified
  • POSIX awk, function keyword in: Definition Syntax
  • POSIX awk, functions and, gsub/sub: Gory Details
  • POSIX awk, functions and, length: String Functions
  • POSIX awk, GNU long options and: Options
  • POSIX awk, interval expressions in: Regexp Operators
  • POSIX awk, next/nextfile statements and: Next Statement
  • POSIX awk, numeric strings and: Typing and Comparison
  • POSIX awk, OFMT variable and: Conversion, OFMT
  • POSIX awk, period (.), using: Regexp Operators
  • POSIX awk, pipes, closing: Close Files And Pipes
  • POSIX awk, printf format strings and: Format Modifiers
  • POSIX awk, regular expressions and: Regexp Operators
  • POSIX awk, timestamps and: Time Functions
  • POSIX awk, | I/O operator and: Getline/Pipe
  • POSIX mode: Options
  • POSIX, awk and: Preface
  • POSIX, gawk extensions not included in: POSIX/GNU
  • POSIX, programs, implementing in awk: Clones
  • POSIXLY_CORRECT environment variable: Options
  • precedence: Precedence, Increment Ops
  • precedence, regexp operators: Regexp Operators
  • print statement: Printing
  • print statement, BEGIN/END patterns and: I/O And BEGIN/END
  • print statement, commas, omitting: Print Examples
  • print statement, I/O operators in: Precedence
  • print statement, line continuations and: Print Examples
  • print statement, OFMT variable and: User-modified
  • print statement, See Also redirection, of output: Redirection
  • print statement, sprintf function and: Round Function
  • printf statement: Printf, Printing
  • printf statement, columns, aligning: Print Examples
  • printf statement, format-control characters: Control Letters
  • printf statement, I/O operators in: Precedence
  • printf statement, modifiers: Format Modifiers
  • printf statement, positional specifiers: Printf Ordering, Format Modifiers
  • printf statement, positional specifiers, mixing with regular formats: Printf Ordering
  • printf statement, See Also redirection, of output: Redirection
  • printf statement, sprintf function and: Round Function
  • printf statement, syntax of: Basic Printf
  • printing: Printing
  • printing, list of options: Options
  • printing, mailing labels: Labels Program
  • printing, unduplicated lines of text: Uniq Program
  • printing, user information: Id Program
  • private variables: Library Names
  • process information, files for: Special Process
  • processes, two-way communications with: Two-way I/O
  • processing data: Basic High Level
  • PROCINFO array: Group Functions, Passwd Functions, Auto-set, Special Caveats
  • profiling awk programs: Profiling
  • profiling awk programs, dynamically: Profiling
  • profiling gawk, See pgawk program: Profiling
  • program, definition of: Getting Started
  • programmers, attractiveness of: Two-way I/O
  • programming conventions, --non-decimal-data option: Nondecimal Data
  • programming conventions, ARGC/ARGV variables: Auto-set
  • programming conventions, exit statement: Exit Statement
  • programming conventions, function parameters: Return Statement
  • programming conventions, functions, calling: Calling Built-in
  • programming conventions, functions, writing: Definition Syntax
  • programming conventions, gawk internals: Internal File Ops
  • programming conventions, nextfile statement: Nextfile Function
  • programming conventions, private variable names: Library Names
  • programming language, recipe for: History
  • programming languages, data-driven vs. procedural: Getting Started
  • programming, basic steps: Basic High Level
  • programming, concepts: Basic Concepts
  • pwcat program: Passwd Functions
  • question mark (?): GNU Regexp Operators, Regexp Operators
  • question mark (?), ?: operator: Precedence
  • QUIT signal (MS-DOS): Profiling
  • quoting: Comments, Long, Read Terminal
  • quoting, rules for: Quoting
  • quoting, tricks for: Quoting
  • Rakitzis, Byron: History Sorting
  • rand function: Numeric Functions
  • random numbers, Cliff: Cliff Random Function
  • random numbers, rand/srand functions: Numeric Functions
  • random numbers, seed of: Numeric Functions
  • range expressions: Character Lists
  • range patterns: Ranges
  • Rankin, Pat: Bugs, Contributors, Assignment Ops, Acknowledgments
  • raw sockets: TCP/IP Networking
  • readable data files, checking: File Checking
  • readable.awk program: File Checking
  • recipe for a programming language: History
  • record separators: User-modified, Records
  • record separators, changing: Records
  • record separators, regular expressions as: Records
  • record separators, with multiline records: Multiple Line
  • records: Basic High Level, Reading Files
  • records, multiline: Multiple Line
  • records, printing: Print
  • records, splitting input into: Records
  • records, terminating: Records
  • records, treating files as: Records
  • recursive functions: Definition Syntax
  • redirection of input: Getline/File
  • redirection of output: Redirection
  • reference counting, sorting arrays: Array Sorting
  • regexp constants: Typing and Comparison, Regexp Constants, Regexp Usage
  • regexp constants, /=.../, /= operator and: Assignment Ops
  • regexp constants, as patterns: Expression Patterns
  • regexp constants, in gawk: Using Constant Regexps
  • regexp constants, slashes vs. quotes: Computed Regexps
  • regexp constants, vs. string constants: Computed Regexps
  • regexp, See regular expressions: Regexp
  • regular expressions: Regexp
  • regular expressions as field separators: Field Separators
  • regular expressions, anchors in: Regexp Operators
  • regular expressions, as field separators: Regexp Field Splitting
  • regular expressions, as patterns: Regexp Patterns, Regexp Usage
  • regular expressions, as record separators: Records
  • regular expressions, case sensitivity: User-modified, Case-sensitivity
  • regular expressions, computed: Computed Regexps
  • regular expressions, constants, See regexp constants: Regexp Usage
  • regular expressions, dynamic: Computed Regexps
  • regular expressions, dynamic, with embedded newlines: Computed Regexps
  • regular expressions, gawk, command-line options: GNU Regexp Operators
  • regular expressions, interval expressions and: Options
  • regular expressions, leftmost longest match: Leftmost Longest
  • regular expressions, operators: Regexp Operators, Regexp Usage
  • regular expressions, operators, for buffers: GNU Regexp Operators
  • regular expressions, operators, for words: GNU Regexp Operators
  • regular expressions, operators, gawk: GNU Regexp Operators
  • regular expressions, operators, precedence of: Regexp Operators
  • regular expressions, searching for: Egrep Program
  • relational operators, See comparison operators: Typing and Comparison
  • return statement, user-defined functions: Return Statement
  • return values, close function: Close Files And Pipes
  • rev user-defined function: Function Example
  • rewind user-defined function: Rewind Function
  • right angle bracket (>), > operator: Precedence, Typing and Comparison
  • right angle bracket (>), > operator (I/O): Redirection
  • right angle bracket (>), >= operator: Precedence, Typing and Comparison
  • right angle bracket (>), >> operator (I/O): Precedence, Redirection
  • right shift, bitwise: Bitwise Functions
  • Ritchie, Dennis: Basic Data Typing
  • RLENGTH variable: Auto-set
  • RLENGTH variable, match function and: String Functions
  • Robbins, Arnold: Future Extensions, Bugs, Contributors, Alarm Program, Passwd Functions, Getline/Pipe, Command Line Field Separator
  • Robbins, Bill: Getline/Pipe
  • Robbins, Harry: Acknowledgments
  • Robbins, Jean: Acknowledgments
  • Robbins, Miriam: Passwd Functions, Getline/Pipe, Acknowledgments
  • Robinson, Will: Dynamic Extensions
  • robot, the: Dynamic Extensions
  • Rommel, Kai Uwe: Contributors, Acknowledgments
  • round user-defined function: Round Function
  • rounding: Round Function
  • rounding numbers: Round Function
  • RS variable: User-modified, Records
  • RS variable, multiline records and: Multiple Line
  • rshift function (gawk): Bitwise Functions
  • RSTART variable: Auto-set
  • RSTART variable, match function and: String Functions
  • RT variable: Auto-set, Multiple Line, Records
  • Rubin, Paul: Contributors, History
  • rule, definition of: Getting Started
  • rvalues/lvalues: Assignment Ops
  • scalar values: Basic Data Typing
  • Schreiber, Bert: Acknowledgments
  • Schreiber, Rita: Acknowledgments
  • search paths: VMS Running, PC Using
  • search paths, for source files: VMS Running, Igawk Program, AWKPATH Variable
  • searching: String Functions
  • searching, files for regular expressions: Egrep Program
  • searching, for words: Dupword Program
  • sed utility: Glossary, Igawk Program, Simple Sed, Field Splitting Summary
  • semicolon (;): Statements/Lines
  • semicolon (;), AWKPATH variable and: PC Using
  • semicolon (;), separating statements in actions: Statements, Action Overview
  • separators, field: User-modified
  • separators, field, FIELDWIDTHS variable and: User-modified
  • separators, field, POSIX and: Fields
  • separators, for records: Records
  • separators, for records, regular expressions as: Records
  • separators, for statements in actions: Action Overview
  • separators, record: User-modified
  • separators, subscript: User-modified
  • set_value internal function: Internals
  • shells, piping commands into: Redirection
  • shells, quoting: Using Shell Variables
  • shells, quoting, rules for: Quoting
  • shells, scripts: One-shot
  • shells, variables: Using Shell Variables
  • shift, bitwise: Bitwise Functions
  • short-circuit operators: Boolean Ops
  • side effects: Increment Ops, Concatenation
  • side effects, array indexing: Reference to Elements
  • side effects, asort function: Array Sorting
  • side effects, assignment expressions: Assignment Ops
  • side effects, Boolean operators: Boolean Ops
  • side effects, conditional expressions: Conditional Exp
  • side effects, decrement/increment operators: Increment Ops
  • side effects, FILENAME variable: Getline Notes
  • side effects, function calls: Function Calls
  • side effects, statements: Action Overview
  • signals, HUP/SIGHUP: Profiling
  • signals, INT/SIGINT (MS-DOS): Profiling
  • signals, QUIT/SIGQUIT (MS-DOS): Profiling
  • signals, USR1/SIGUSR1: Profiling
  • sin function: Numeric Functions
  • single quote ('): Quoting, Long, One-shot
  • single quote ('), vs. apostrophe: Comments
  • single quote ('), with double quotes: Quoting
  • single-character fields: Single Character Fields
  • single-precision floating-point: Basic Data Typing
  • Skywalker, Luke: Undocumented
  • sleep utility: Alarm Program
  • sockets: TCP/IP Networking
  • sort function, arrays, sorting: Array Sorting
  • sort utility: Word Sorting
  • sort utility, coprocesses and: Two-way I/O
  • sorting characters in different languages: Explaining gettext
  • source code, awka: Other Versions
  • source code, Bell Laboratories awk: Other Versions
  • source code, gawk: Gawk Distribution
  • source code, mawk: Other Versions
  • source code, mixing: Options
  • source files, search path for: Igawk Program
  • sparse arrays: Array Intro
  • Spencer, Henry: Glossary
  • split function: String Functions
  • split function, array elements, deleting: Delete
  • split utility: Split Program
  • split.awk program: Split Program
  • sprintf function: String Functions, OFMT
  • sprintf function, OFMT variable and: User-modified
  • sprintf function, print/printf statements and: Round Function
  • sqrt function: Numeric Functions
  • square brackets ([]): Regexp Operators
  • srand function: Numeric Functions
  • Stallman, Richard: Glossary, Contributors, Acknowledgments, Manual History
  • standard input: Special FD, Read Terminal
  • standard output: Special FD
  • stat function, implementing in gawk: Sample Library
  • statements, compound, control statements and: Statements
  • statements, control, in actions: Statements
  • statements, multiple: Statements/Lines
  • stlen internal variable: Internals
  • stptr internal variable: Internals
  • stream editors: Igawk Program, Simple Sed, Field Splitting Summary
  • strftime function (gawk): Time Functions
  • string constants: Scalar Constants
  • string constants, vs. regexp constants: Computed Regexps
  • string extraction (internationalization): String Extraction
  • string operators: Concatenation
  • string-matching operators: Regexp Usage
  • strings: Internals
  • strings, converting: Conversion
  • strings, converting, numbers to: Bitwise Functions, User-modified
  • strings, empty, See null strings: Records
  • strings, extracting: String Extraction
  • strings, for localization: Programmer i18n
  • strings, length of: Scalar Constants
  • strings, merging arrays into: Join Function
  • strings, NODE internal type: Internals
  • strings, null: Regexp Field Splitting
  • strings, numeric: Typing and Comparison
  • strings, splitting: String Functions
  • strtonum function (gawk): String Functions
  • strtonum function (gawk), --non-decimal-data option and: Nondecimal Data
  • sub function: String Functions, Using Constant Regexps
  • sub function, arguments of: String Functions
  • sub function, escape processing: Gory Details
  • subscript separators: User-modified
  • subscripts in arrays, multidimensional: Multi-dimensional
  • subscripts in arrays, multidimensional, scanning: Multi-scanning
  • subscripts in arrays, numbers as: Numeric Array Subscripts
  • subscripts in arrays, uninitialized variables as: Uninitialized Subscripts
  • SUBSEP variable: User-modified
  • SUBSEP variable, multidimensional arrays: Multi-dimensional
  • substr function: String Functions
  • Sumner, Andrew: Other Versions
  • syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops
  • system function: I/O Functions
  • systime function (gawk): Time Functions
  • tandem: Tandem Installation
  • Tcl: Library Names
  • TCP/IP: TCP/IP Networking
  • TCP/IP, support for: Special Network
  • tee utility: Tee Program
  • tee.awk program: Tee Program
  • terminating records: Records
  • testbits.awk program: Bitwise Functions
  • Texinfo: Adding Code, Distribution contents, Extract Program, Dupword Program, Library Functions, Conventions
  • Texinfo, chapter beginnings in files: Regexp Operators
  • Texinfo, extracting programs from source files: Extract Program
  • text, printing: Print
  • text, printing, unduplicated lines of: Uniq Program
  • textdomain function (C library): Explaining gettext
  • TEXTDOMAIN variable: Programmer i18n, User-modified
  • TEXTDOMAIN variable, BEGIN pattern and: Programmer i18n
  • TEXTDOMAIN variable, portability and: I18N Portability
  • tilde (~), ~ operator: Expression Patterns, Precedence, Typing and Comparison, Regexp Constants, Computed Regexps, Case-sensitivity, Regexp Usage
  • time, alarm clock example program: Alarm Program
  • time, localization and: Explaining gettext
  • time, managing: Gettimeofday Function
  • time, retrieving: Time Functions
  • timestamps: Time Functions
  • timestamps, converting dates to: Time Functions
  • timestamps, formatted: Gettimeofday Function
  • tmp_number internal function: Internals
  • tmp_string internal function: Internals
  • tolower function: String Functions
  • toupper function: String Functions
  • tr utility: Translate Program
  • translate.awk program: Translate Program
  • troubleshooting, --non-decimal-data option: Options
  • troubleshooting, -F option: Known Bugs
  • troubleshooting, == operator: Typing and Comparison
  • troubleshooting, awk uses FS not IFS: Field Separators
  • troubleshooting, backslash before nonspecial character: Escape Sequences
  • troubleshooting, division: Arithmetic Ops
  • troubleshooting, fatal errors, field widths, specifying: Constant Size
  • troubleshooting, fatal errors, printf format strings: Format Modifiers
  • troubleshooting, fflush function: I/O Functions
  • troubleshooting, function call syntax: Function Calls
  • troubleshooting, gawk: Compatibility Mode, Known Bugs
  • troubleshooting, gawk, bug reports: Bugs
  • troubleshooting, gawk, fatal errors, function arguments: Calling Built-in
  • troubleshooting, getline function: File Checking
  • troubleshooting, gsub/sub functions: String Functions
  • troubleshooting, match function: String Functions
  • troubleshooting, print statement, omitting commas: Print Examples
  • troubleshooting, printing: Redirection
  • troubleshooting, quotes with file names: Special FD
  • troubleshooting, readable data files: File Checking
  • troubleshooting, regexp constants vs. string constants: Computed Regexps
  • troubleshooting, string concatenation: Concatenation
  • troubleshooting, substr function: String Functions
  • troubleshooting, system function: I/O Functions
  • troubleshooting, typographical errors, global variables: Options
  • true, logical: Truth Values
  • Trueman, David: Contributors, Acknowledgments, History
  • trunc-mod operation: Arithmetic Ops
  • truth values: Truth Values
  • type conversion: Conversion
  • type internal variable: Internals
  • undefined functions: Function Caveats
  • underscore (_), _ C macro: Explaining gettext
  • underscore (_), in names of private variables: Library Names
  • underscore (_), translatable string: Programmer i18n
  • undocumented features: Undocumented
  • uninitialized variables, as array subscripts: Uninitialized Subscripts
  • uniq utility: Uniq Program
  • uniq.awk program: Uniq Program
  • Unix: Glossary
  • Unix awk, backslashes in escape sequences: Escape Sequences
  • Unix awk, close function and: Close Files And Pipes
  • Unix awk, password files, field separators and: Command Line Field Separator
  • Unix, awk scripts and: Executable Scripts
  • unsigned integers: Basic Data Typing
  • update_ERRNO internal function: Internals
  • user database, reading: Passwd Functions
  • user-defined, functions: User-defined
  • user-defined, functions, counts: Profiling
  • user-defined, variables: Variables
  • user-modifiable variables: User-modified
  • users, information about, printing: Id Program
  • users, information about, retrieving: Passwd Functions
  • USR1 signal: Profiling
  • values, numeric: Basic Data Typing
  • values, string: Basic Data Typing
  • variable typing: Typing and Comparison
  • variables: Basic Data Typing, Other Features
  • variables, assigning on command line: Assignment Options
  • variables, built-in: Built-in Variables, Using Variables
  • variables, built-in, -v option, setting with: Options
  • variables, built-in, conveying information: Auto-set
  • variables, flag: Boolean Ops
  • variables, getline command into, using: Getline/Variable/Coprocess, Getline/Variable/Pipe, Getline/Variable/File, Getline/Variable
  • variables, global, for library functions: Library Names
  • variables, global, printing list of: Options
  • variables, initializing: Using Variables
  • variables, names of: Arrays
  • variables, private: Library Names
  • variables, setting: Options
  • variables, shadowing: Definition Syntax
  • variables, types of: Assignment Ops
  • variables, types of, comparison expressions and: Typing and Comparison
  • variables, uninitialized, as array subscripts: Uninitialized Subscripts
  • variables, user-defined: Variables
  • vertical bar (|): Regexp Operators
  • vertical bar (|), | operator (I/O): Precedence, Getline/Pipe
  • vertical bar (|), |& I/O operator (I/O): Two-way I/O
  • vertical bar (|), |& operator (I/O): Precedence, Getline/Coprocess
  • vertical bar (|), |& operator (I/O), two-way communications: Portal Files
  • vertical bar (|), || operator: Precedence, Boolean Ops
  • vname internal variable: Internals
  • w utility: Constant Size
  • Wall, Larry: Future Extensions
  • warnings, issuing: Options
  • wc utility: Wc Program
  • wc.awk program: Wc Program
  • Weinberger, Peter: Contributors, History
  • while statement: While Statement, Regexp Usage
  • whitespace, as field separators: Field Separators
  • whitespace, functions, calling: Calling Built-in
  • whitespace, newlines as: Options
  • Williams, Kent: Contributors
  • Woods, John: Contributors
  • word boundaries, matching: GNU Regexp Operators
  • word, regexp definition of: GNU Regexp Operators
  • word-boundary operator (gawk): GNU Regexp Operators
  • wordfreq.awk program: Word Sorting
  • words, counting: Wc Program
  • words, duplicate, searching for: Dupword Program
  • words, usage counts, generating: Word Sorting
  • xgettext utility: String Extraction
  • XOR bitwise operation: Bitwise Functions
  • xor function (gawk): Bitwise Functions
  • Zaretskii, Eli: Acknowledgments
  • zero, negative vs. positive: Floating Point Issues
  • Zoulas, Christos: Contributors
  • {} (braces), actions and: Action Overview
  • {} (braces), pgawk program: Profiling
  • {} (braces), statements, grouping: Statements
  • | (vertical bar): Regexp Operators
  • | (vertical bar), | operator (I/O): Precedence, Redirection, Getline/Pipe
  • | (vertical bar), |& operator (I/O): Two-way I/O, Precedence, Redirection, Getline/Coprocess
  • | (vertical bar), |& operator (I/O), pipes, closing: Close Files And Pipes
  • | (vertical bar), |& operator (I/O), two-way communications: Portal Files
  • | (vertical bar), || operator: Precedence, Boolean Ops
  • ~ (tilde), ~ operator: Expression Patterns, Precedence, Typing and Comparison, Regexp Constants, Computed Regexps, Case-sensitivity

Footnotes

  1. These commands are available on POSIX-compliant systems, as well as on traditional Unix-based systems. If you are using some other operating system, you still need to be familiar with the ideas of I/O redirection and pipes.

  2. Often, these systems use gawk for their awk implementation!

  3. All such differences appear in the index under the entry "differences in awk and gawk."

  4. GNU stands for "GNU's not Unix."

  5. The terminology "GNU/Linux" is explained in the Glossary.

  6. Although we generally recommend the use of single quotes around the program text, double quotes are needed here in order to put the single quote into the message.

  7. The #! mechanism works on Linux systems, systems derived from the 4.4-Lite Berkeley Software Distribution, and most commercial Unix systems.

  8. The line beginning with #! lists the full file name of an interpreter to run and an optional initial command-line argument to pass to that interpreter. The operating system then runs the interpreter with the given argument and the full argument list of the executed program. The first argument in the list is the full file name of the awk program. The rest of the argument list contains either options to awk, or data files, or both.

  9. In the C shell (csh), you need to type a semicolon and then a backslash at the end of the first line; see awk Statements Versus Lines, for an explanation. In a POSIX-compliant shell, such as the Bourne shell or bash, you can type the example as shown. If the command echo $path produces an empty output line, you are most likely using a POSIX-compliant shell. Otherwise, you are probably using the C shell or a shell derived from it.

  10. On some very old systems, you may need to use ls -lg to get this output.

  11. The ? and : referred to here is the three-operand conditional expression described in Conditional Expressions. Splitting lines after ? and : is a minor gawk extension; if --posix is specified (see Command-Line Options), then this extension is disabled.

  12. In other literature, you may see a character list referred to as either a character set, a character class, or a bracket expression.

  13. Use two backslashes if you're using a string constant with a regexp operator or function.

  14. Experienced C and C++ programmers will note that it is possible, using something like IGNORECASE = 1 && /foObAr/ { ... } and IGNORECASE = 0 || /foobar/ { ... }. However, this is somewhat obscure and we don't recommend it.

  15. At least that we know about.

  16. In POSIX awk, newlines are not considered whitespace for separating fields.

  17. The sed utility is a "stream editor." Its behavior is also defined by the POSIX standard.

  18. Older versions of gawk would interpret these names internally only if the system did not actually have a /dev/fd directory or any of the other special files listed earlier. Usually this didn't make a difference, but sometimes it did; thus, it was decided to make gawk's behavior consistent on all systems and to have it always interpret the special file names itself.

  19. The technical terminology is rather morbid. The finished child is called a "zombie," and cleaning up after it is referred to as "reaping."

  20. The internal representation of all numbers, including integers, uses double-precision floating-point numbers. On most modern systems, these are in IEEE 754 standard format.

  21. Pathological cases can require up to 752 digits (!), but we doubt that you need to worry about this.

  22. The POSIX standard is under revision. The revised standard's rules for typing and comparison are the same as just described for gawk.

  23. The original version of awk used to keep reading and ignoring input until the end of the file was seen.

  24. In POSIX awk, newline does not count as whitespace.

  25. Some early implementations of Unix awk initialized FILENAME to "-", even if there were data files to be processed. This behavior was incorrect and should not be relied upon in your programs.

  26. Thanks to Michael Brennan for pointing this out.

  27. The C version of rand is known to produce fairly poor sequences of random numbers. However, nothing requires that an awk implementation use the C rand to implement the awk version of rand. In fact, gawk uses the BSD random function, which is considerably better than rand, to produce random numbers.

  28. Computer-generated random numbers really are not truly random. They are technically known as "pseudorandom." This means that while the numbers in a sequence appear to be random, you can in fact generate the same sequence of random numbers over and over again.

  29. Unless you use the --non-decimal-data option, which isn't recommended. See Allowing Nondecimal Input Data, for more information.

  30. This is different from C and C++, in which the first character is number zero.

  31. This consequence was certainly unintended.

  32. As this Web page was being finalized, we learned that the POSIX standard will not use these rules. However, it was too late to change gawk for the 3.1 release. gawk behaves as described here.

  33. A program is interactive if the standard output is connected to a terminal device.

  34. See Glossary, especially the entries "Epoch" and "UTC."

  35. The GNU date utility can also do many of the things described here. Its use may be preferable for simple time-related operations in shell scripts.

  36. Occasionally there are minutes in a year with a leap second, which is why the seconds can go up to 60.

  37. As this is a recent standard, not every system's strftime necessarily supports all of the conversions listed here.

  38. If you don't understand any of this, don't worry about it; these facilities are meant to make it easier to "internationalize" programs. Other internationalization features are described in Internationalization with gawk.

  39. This is because ISO C leaves the behavior of the C version of strftime undefined and gawk uses the system's version of strftime if it's there. Typically, the conversion specifier either does not appear in the returned string or appears literally.

  40. This example shows that 0's come in on the left side. For gawk, this is always true, but in some languages, it's possible to have the left side fill with 1's. Caveat emptor.

  41. For some operating systems, the gawk port doesn't support GNU gettext. This applies most notably to the PC operating systems. As such, these features are not available if you are using one of those operating systems. Sorry.

  42. Americans use a comma every three decimal places and a period for the decimal point, while many Europeans do exactly the opposite: 1,234.56 versus 1.234,56.

  43. Starting with gettext version 0.11.1, the xgettext utility that comes with GNU gettext can handle .awk files.

  44. This example is borrowed from the GNU gettext manual.

  45. This is good fodder for an "Obfuscated awk" contest.

  46. Perhaps it would be better if it were called "Hippy." Ah, well.

  47. This is very different from the same operator in the C shell, csh.

  48. Not recommended.

  49. Your version of gawk may use a different directory; it will depend upon how gawk was built and installed. The actual directory is the value of $(datadir) generated when gawk was configured. You probably don't need to worry about this, though.

  50. The effects are not identical. Output of the transformed record will be in all lowercase, while IGNORECASE preserves the original contents of the input record.

  51. While all the library routines could have been rewritten to use this convention, this was not done, in order to show how my own awk programming style has evolved and to provide some basis for this discussion.

  52. gawk's --dump-variables command-line option is useful for verifying this.

  53. http://mathworld.wolfram.com/CliffRandomNumberGenerator.hmtl

  54. ASCII has been extended in many countries to use the values from 128 to 255 for country-specific characters. If your system uses these extensions, you can simplify _ord_init to simply loop from 0 to 255.

  55. It would be nice if awk had an assignment operator for concatenation. The lack of an explicit operator for concatenation makes string operations more difficult than they really need to be.

  56. This function was written before gawk acquired the ability to split strings into single characters using "" as the separator. We have left it alone, since using substr is more portable.

  57. It is often the case that password information is stored in a network database.

  58. It also introduces a subtle bug; if a match happens, we output the translated line, not the original.

  59. wc can't just use the value of FNR in endfile. If you examine the code in Noting Data File Boundaries you will see that FNR has already been reset by the time endfile is called.

  60. On some older System V systems, tr may require that the lists be written as range expressions enclosed in square brackets ([a-z]) and quoted, to prevent the shell from attempting a file name expansion. This is not a feature.

  61. This program was written before gawk acquired the ability to split each character in a string into separate array elements.

  62. "Real world" is defined as "a program actually used to get something done."

  63. On some very old versions of awk, the test getline junk < t can loop forever if the file exists but is empty. Caveat emptor.

  64. http://www.cygwin.com

  65. http://cm.bell-labs.com/who/bwk

  66. This version is edited slightly for presentation. The complete version can be found in extension/filefuncs.c in the gawk distribution.

  67. Compiled programs are typically written in lower-level languages such as C, C++, Fortran, or Ada, and then translated, or compiled, into a form that the computer can execute directly.

  68. http://www.validgh.com/goldberg/paper.ps.

  69. Pathological cases can require up to 752 digits (!), but we doubt that you need to worry about this.


Using the GNU Compiler Collection (GCC)

This file documents the use of the GNU compilers.

Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

Copyright © 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License" and "Funding Free Software", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the section entitled "GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.

Short Contents

  • Introduction
  • Compile C, C++, Objective-C, Ada, Fortran, or Java
  • Language Standards Supported by GCC
  • GCC Command Options
  • C Implementation-defined behavior
  • Extensions to the C Language Family
  • Extensions to the C++ Language
  • GNU Objective-C runtime features
  • gcov: a Test Coverage Program
  • Known Causes of Trouble with GCC
  • Reporting Bugs
  • How To Get Help with GCC
  • Contributing to GCC Development
  • Using GCC on VMS
  • Funding Free Software
  • The GNU Project and GNU/Linux
  • GNU GENERAL PUBLIC LICENSE
  • GNU Free Documentation License
  • Contributors to GCC
  • Option Index
  • Index

Table of Contents

  • Introduction
  • Compile C, C++, Objective-C, Ada, Fortran, or Java
  • Language Standards Supported by GCC
  • GCC Command Options
    • Option Summary
    • Options Controlling the Kind of Output
    • Compiling C++ Programs
    • Options Controlling C Dialect
    • Options Controlling C++ Dialect
    • Options Controlling Objective-C Dialect
    • Options to Control Diagnostic Messages Formatting
    • Options to Request or Suppress Warnings
    • Options for Debugging Your Program or GCC
    • Options That Control Optimization
    • Options Controlling the Preprocessor
    • Passing Options to the Assembler
    • Options for Linking
    • Options for Directory Search
    • Specifying subprocesses and the switches to pass to them
    • Specifying Target Machine and Compiler Version
    • Hardware Models and Configurations
      • M680x0 Options
      • M68hc1x Options
      • VAX Options
      • SPARC Options
      • Convex Options
      • AMD29K Options
      • ARM Options
      • MN10200 Options
      • MN10300 Options
      • M32R/D Options
      • M88K Options
      • IBM RS/6000 and PowerPC Options
      • IBM RT Options
      • MIPS Options
      • Intel 386 and AMD x86-64 Options
      • HPPA Options
      • Intel 960 Options
      • DEC Alpha Options
      • DEC Alpha/VMS Options
      • Clipper Options
      • H8/300 Options
      • SH Options
      • Options for System V
      • TMS320C3x/C4x Options
      • V850 Options
      • ARC Options
      • NS32K Options
      • AVR Options
      • MCore Options
      • IA-64 Options
      • D30V Options
      • S/390 and zSeries Options
      • CRIS Options
      • MMIX Options
      • PDP-11 Options
      • Xstormy16 Options
      • Xtensa Options
    • Options for Code Generation Conventions
    • Environment Variables Affecting GCC
    • Running Protoize
  • C Implementation-defined behavior
    • Translation
    • Environment
    • Identifiers
    • Characters
    • Integers
    • Floating point
    • Arrays and pointers
    • Hints
    • Structures, unions, enumerations, and bit-fields
    • Qualifiers
    • Preprocessing directives
    • Library functions
    • Architecture
    • Locale-specific behavior
  • Extensions to the C Language Family
    • Statements and Declarations in Expressions
    • Locally Declared Labels
    • Labels as Values
    • Nested Functions
    • Constructing Function Calls
    • Naming an Expression's Type
    • Referring to a Type with typeof
    • Generalized Lvalues
    • Conditionals with Omitted Operands
    • Double-Word Integers
    • Complex Numbers
    • Hex Floats
    • Arrays of Length Zero
    • Arrays of Variable Length
    • Macros with a Variable Number of Arguments.
    • Slightly Looser Rules for Escaped Newlines
    • String Literals with Embedded Newlines
    • Non-Lvalue Arrays May Have Subscripts
    • Arithmetic on void- and Function-Pointers
    • Non-Constant Initializers
    • Compound Literals
    • Designated Initializers
    • Case Ranges
    • Cast to a Union Type
    • Mixed Declarations and Code
    • Declaring Attributes of Functions
    • Attribute Syntax
    • Prototypes and Old-Style Function Definitions
    • C++ Style Comments
    • Dollar Signs in Identifier Names
    • The Character <ESC> in Constants
    • Inquiring on Alignment of Types or Variables
    • Specifying Attributes of Variables
    • Specifying Attributes of Types
    • An Inline Function is As Fast As a Macro
    • Assembler Instructions with C Expression Operands
      • i386 floating point asm operands
    • Constraints for asm Operands
      • Simple Constraints
      • Multiple Alternative Constraints
      • Constraint Modifier Characters
      • Constraints for Particular Machines
    • Controlling Names Used in Assembler Code
    • Variables in Specified Registers
      • Defining Global Register Variables
      • Specifying Registers for Local Variables
    • Alternate Keywords
    • Incomplete enum Types
    • Function Names as Strings
    • Getting the Return or Frame Address of a Function
    • Using vector instructions through built-in functions
    • Other built-in functions provided by GCC
    • Built-in Functions Specific to Particular Target Machines
      • X86 Built-in Functions
      • PowerPC AltiVec Built-in Functions
    • Pragmas Accepted by GCC
      • ARM Pragmas
      • Darwin Pragmas
      • Solaris Pragmas
      • Tru64 Pragmas
    • Unnamed struct/union fields within structs/unions.
  • Extensions to the C++ Language
    • Minimum and Maximum Operators in C++
    • When is a Volatile Object Accessed?
    • Restricting Pointer Aliasing
    • Vague Linkage
    • Declarations and Definitions in One Header
    • Where's the Template?
    • Extracting the function pointer from a bound pointer to member function
    • C++-Specific Variable, Function, and Type Attributes
    • Java Exceptions
    • Deprecated Features
    • Backwards Compatibility
  • GNU Objective-C runtime features
    • +load: Executing code before main
      • What you can and what you cannot do in +load
    • Type encoding
    • Garbage Collection
    • Constant string objects
    • compatibility_alias
  • gcov: a Test Coverage Program
    • Introduction to gcov
    • Invoking gcov
    • Using gcov with GCC Optimization
    • Brief description of gcov data files
  • Known Causes of Trouble with GCC
    • Actual Bugs We Haven't Fixed Yet
    • Cross-Compiler Problems
    • Interoperation
    • Problems Compiling Certain Programs
    • Incompatibilities of GCC
    • Fixed Header Files
    • Standard Libraries
    • Disappointments and Misunderstandings
    • Common Misunderstandings with GNU C++
      • Declare and Define Static Members
      • Temporaries May Vanish Before You Expect
      • Implicit Copy-Assignment for Virtual Bases
    • Caveats of using protoize
    • Certain Changes We Don't Want to Make
    • Warning Messages and Error Messages
  • Reporting Bugs
    • Have You Found a Bug?
    • Where to Report Bugs
    • How to Report Bugs
    • The gccbug script
  • How To Get Help with GCC
  • Contributing to GCC Development
  • Using GCC on VMS
    • Include Files and VMS
    • Global Declarations and VMS
    • Other VMS Issues
  • Funding Free Software
  • The GNU Project and GNU/Linux
  • GNU GENERAL PUBLIC LICENSE
    • Preamble
    • How to Apply These Terms to Your New Programs
  • GNU Free Documentation License
    • ADDENDUM: How to use this License for your documents
  • Contributors to GCC
  • Option Index
  • Index

Node:Top, Next:G++ and GCC, Up:(DIR)

Introduction

This manual documents how to use the GNU compilers, as well as their features and incompatibilities, and how to report bugs. It corresponds to GCC version 3.1. The internals of the GNU compilers, including how to port them to new targets and some information about how to write front ends for new languages, are documented in a separate manual. See Introduction.

  • G++ and GCC: You can compile C or C++ programs.
  • Standards: Language standards supported by GCC.
  • Invoking GCC: Command options supported by gcc.
  • C Implementation: How GCC implements the ISO C specification.
  • C Extensions: GNU extensions to the C language family.
  • C++ Extensions: GNU extensions to the C++ language.
  • Objective-C: GNU Objective-C runtime features.
  • Gcov: gcov: a GCC test coverage program.
  • Trouble: If you have trouble using GCC.
  • Bugs: How, why and where to report bugs.
  • Service: How to find suppliers of support for GCC.
  • Contributing: How to contribute to testing and developing GCC.
  • VMS: Using GCC on VMS.

  • Funding: How to help assure funding for free software.
  • GNU Project: The GNU Project and GNU/Linux.

  • Copying: GNU General Public License says how you can copy and share GCC.
  • GNU Free Documentation License: How you can copy and share this manual.
  • Contributors: People who have contributed to GCC.

  • Option Index: Index to command line options.
  • Index: Index of concepts and symbol names.


Using the GNU Compiler Collection (GCC)

Node:Actual Bugs, Next:Cross-Compiler Problems, Up:Trouble

Actual Bugs We Haven't Fixed Yet

  • The fixincludes script interacts badly with automounters; if the directory of system header files is automounted, it tends to be unmounted while fixincludes is running. This would seem to be a bug in the automounter. We don't know any good way to work around it.
  • The fixproto script will sometimes add prototypes for the sigsetjmp and siglongjmp functions that reference the jmp_buf type before that type is defined. To work around this, edit the offending file and place the typedef in front of the prototypes.
  • When -pedantic-errors is specified, GCC will incorrectly give an error message when a function name is specified in an expression involving the comma operator.


Using the GNU Compiler Collection (GCC)

Node:Alignment, Next:Inline, Previous:Type Attributes, Up:C Extensions

Inquiring on Alignment of Types or Variables

The keyword __alignof__ allows you to inquire about how an object is aligned, or the minimum alignment usually required by a type. Its syntax is just like sizeof.

For example, if the target machine requires a double value to be aligned on an 8-byte boundary, then __alignof__ (double) is 8. This is true on many RISC machines. On more traditional machine designs, __alignof__ (double) is 4 or even 2.

Some machines never actually require alignment; they allow reference to any data type even at an odd addresses. For these machines, __alignof__ reports the recommended alignment of a type.

If the operand of __alignof__ is an lvalue rather than a type, its value is the required alignment for its type, taking into account any minimum alignment specified with GCC's __attribute__ extension (see Variable Attributes). For example, after this declaration:

struct foo { int x; char y; } foo1;

the value of __alignof__ (foo1.y) is 1, even though its actual alignment is probably 2 or 4, the same as __alignof__ (int).

It is an error to ask for the alignment of an incomplete type.


Using the GNU Compiler Collection (GCC)

Node:Alternate Keywords, Next:Incomplete Enums, Previous:Explicit Reg Vars, Up:C Extensions

Alternate Keywords

The option -traditional disables certain keywords; -ansi and the various -std options disable certain others. This causes trouble when you want to use GNU C extensions, or ISO C features, in a general-purpose header file that should be usable by all programs, including ISO C programs and traditional ones. The keywords asm, typeof and inline cannot be used since they won't work in a program compiled with -ansi (although inline can be used in a program compiled with -std=c99), while the keywords const, volatile, signed, typeof and inline won't work in a program compiled with -traditional. The ISO C99 keyword restrict is only available when -std=gnu99 (which will eventually be the default) or -std=c99 (or the equivalent -std=iso9899:1999) is used.

The way to solve these problems is to put __ at the beginning and end of each problematical keyword. For example, use __asm__ instead of asm, __const__ instead of const, and __inline__ instead of inline.

Other C compilers won't accept these alternative keywords; if you want to compile with another compiler, you can define the alternate keywords as macros to replace them with the customary keywords. It looks like this:

#ifndef __GNUC__
#define __asm__ asm
#endif

-pedantic and other options cause warnings for many GNU C extensions. You can prevent such warnings within one expression by writing __extension__ before the expression. __extension__ has no effect aside from this.


Using the GNU Compiler Collection (GCC)

Node:AMD29K Options, Next:ARM Options, Previous:Convex Options, Up:Submodel Options

AMD29K Options

These -m options are defined for the AMD Am29000:

-mdw
Generate code that assumes the DW bit is set, i.e., that byte and halfword operations are directly supported by the hardware. This is the default.
-mndw
Generate code that assumes the DW bit is not set.
-mbw
Generate code that assumes the system supports byte and halfword write operations. This is the default.
-mnbw
Generate code that assumes the systems does not support byte and halfword write operations. -mnbw implies -mndw.
-msmall
Use a small memory model that assumes that all function addresses are either within a single 256 KB segment or at an absolute address of less than 256k. This allows the call instruction to be used instead of a const, consth, calli sequence.
-mnormal
Use the normal memory model: Generate call instructions only when calling functions in the same file and calli instructions otherwise. This works if each file occupies less than 256 KB but allows the entire executable to be larger than 256 KB. This is the default.
-mlarge
Always use calli instructions. Specify this option if you expect a single file to compile into more than 256 KB of code.
-m29050
Generate code for the Am29050.
-m29000
Generate code for the Am29000. This is the default.
-mkernel-registers
Generate references to registers gr64-gr95 instead of to registers gr96-gr127. This option can be used when compiling kernel code that wants a set of global registers disjoint from that used by user-mode code.

Note that when this option is used, register names in -f flags must use the normal, user-mode, names.

-muser-registers
Use the normal set of global registers, gr96-gr127. This is the default.
-mstack-check
-mno-stack-check
Insert (or do not insert) a call to __msp_check after each stack adjustment. This is often used for kernel code.
-mstorem-bug
-mno-storem-bug
-mstorem-bug handles 29k processors which cannot handle the separation of a mtsrim insn and a storem instruction (most 29000 chips to date, but not the 29050).
-mno-reuse-arg-regs
-mreuse-arg-regs
-mno-reuse-arg-regs tells the compiler to only use incoming argument registers for copying out arguments. This helps detect calling a function with fewer arguments than it was declared with.
-mno-impure-text
-mimpure-text
-mimpure-text, used in addition to -shared, tells the compiler to not pass -assert pure-text to the linker when linking a shared object.
-msoft-float
Generate output containing library calls for floating point. Warning: the requisite libraries are not part of GCC. Normally the facilities of the machine's usual C compiler are used, but this can't be done directly in cross-compilation. You must make your own arrangements to provide suitable library functions for cross-compilation.
-mno-multm
Do not generate multm or multmu instructions. This is useful for some embedded systems which do not have trap handlers for these instructions.


Using the GNU Compiler Collection (GCC)

Node:ARC Options, Next:NS32K Options, Previous:V850 Options, Up:Submodel Options

ARC Options

These options are defined for ARC implementations:

-EL
Compile code for little endian mode. This is the default.
-EB
Compile code for big endian mode.
-mmangle-cpu
Prepend the name of the cpu to all public symbol names. In multiple-processor systems, there are many ARC variants with different instruction and register set characteristics. This flag prevents code compiled for one cpu to be linked with code compiled for another. No facility exists for handling variants that are "almost identical". This is an all or nothing option.
-mcpu=cpu
Compile code for ARC variant cpu. Which variants are supported depend on the configuration. All variants support -mcpu=base, this is the default.
-mtext=text-section
-mdata=data-section
-mrodata=readonly-data-section
Put functions, data, and readonly data in text-section, data-section, and readonly-data-section respectively by default. This can be overridden with the section attribute. See Variable Attributes.


Using the GNU Compiler Collection (GCC)

Node:Architecture implementation, Next:Locale-specific behavior implementation, Previous:Library functions implementation, Up:C Implementation

Architecture

  • The values or expressions assigned to the macros specified in the headers <float.h>, <limits.h>, and <stdint.h> (5.2.4.2, 7.18.2, 7.18.3).
  • The number, order, and encoding of bytes in any object (when not explicitly specified in this International Standard) (6.2.6.1).
  • The value of the result of the sizeof operator (6.5.3.4).


Using the GNU Compiler Collection (GCC)

Node:ARM Options, Next:MN10200 Options, Previous:AMD29K Options, Up:Submodel Options

ARM Options

These -m options are defined for Advanced RISC Machines (ARM) architectures:

-mapcs-frame
Generate a stack frame that is compliant with the ARM Procedure Call Standard for all functions, even if this is not strictly necessary for correct execution of the code. Specifying -fomit-frame-pointer with this option will cause the stack frames not to be generated for leaf functions. The default is -mno-apcs-frame.
-mapcs
This is a synonym for -mapcs-frame.
-mapcs-26
Generate code for a processor running with a 26-bit program counter, and conforming to the function calling standards for the APCS 26-bit option. This option replaces the -m2 and -m3 options of previous releases of the compiler.
-mapcs-32
Generate code for a processor running with a 32-bit program counter, and conforming to the function calling standards for the APCS 32-bit option. This option replaces the -m6 option of previous releases of the compiler.
-mthumb-interwork
Generate code which supports calling between the ARM and Thumb instruction sets. Without this option the two instruction sets cannot be reliably used inside one program. The default is -mno-thumb-interwork, since slightly larger code is generated when -mthumb-interwork is specified.
-mno-sched-prolog
Prevent the reordering of instructions in the function prolog, or the merging of those instruction with the instructions in the function's body. This means that all functions will start with a recognizable set of instructions (or in fact one of a choice from a small set of different function prologues), and this information can be used to locate the start if functions inside an executable piece of code. The default is -msched-prolog.
-mhard-float
Generate output containing floating point instructions. This is the default.
-msoft-float
Generate output containing library calls for floating point. Warning: the requisite libraries are not available for all ARM targets. Normally the facilities of the machine's usual C compiler are used, but this cannot be done directly in cross-compilation. You must make your own arrangements to provide suitable library functions for cross-compilation.

-msoft-float changes the calling convention in the output file; therefore, it is only useful if you compile all of a program with this option. In particular, you need to compile libgcc.a, the library that comes with GCC, with -msoft-float in order for this to work.

-mlittle-endian
Generate code for a processor running in little-endian mode. This is the default for all standard configurations.
-mbig-endian
Generate code for a processor running in big-endian mode; the default is to compile code for a little-endian processor.
-mwords-little-endian
This option only applies when generating code for big-endian processors. Generate code for a little-endian word order but a big-endian byte order. That is, a byte order of the form 32107654. Note: this option should only be used if you require compatibility with code for big-endian ARM processors generated by versions of the compiler prior to 2.8.
-malignment-traps
Generate code that will not trap if the MMU has alignment traps enabled. On ARM architectures prior to ARMv4, there were no instructions to access half-word objects stored in memory. However, when reading from memory a feature of the ARM architecture allows a word load to be used, even if the address is unaligned, and the processor core will rotate the data as it is being loaded. This option tells the compiler that such misaligned accesses will cause a MMU trap and that it should instead synthesise the access as a series of byte accesses. The compiler can still use word accesses to load half-word data if it knows that the address is aligned to a word boundary.

This option is ignored when compiling for ARM architecture 4 or later, since these processors have instructions to directly access half-word objects in memory.

-mno-alignment-traps
Generate code that assumes that the MMU will not trap unaligned accesses. This produces better code when the target instruction set does not have half-word memory operations (i.e. implementations prior to ARMv4).

Note that you cannot use this option to access unaligned word objects, since the processor will only fetch one 32-bit aligned object from memory.

The default setting for most targets is -mno-alignment-traps, since this produces better code when there are no half-word memory instructions available.

-mshort-load-bytes
-mno-short-load-words
These are deprecated aliases for -malignment-traps.
-mno-short-load-bytes
-mshort-load-words
This are deprecated aliases for -mno-alignment-traps.
-mbsd
This option only applies to RISC iX. Emulate the native BSD-mode compiler. This is the default if -ansi is not specified.
-mxopen
This option only applies to RISC iX. Emulate the native X/Open-mode compiler.
-mno-symrename
This option only applies to RISC iX. Do not run the assembler post-processor, symrename, after code has been assembled. Normally it is necessary to modify some of the standard symbols in preparation for linking with the RISC iX C library; this option suppresses this pass. The post-processor is never run when the compiler is built for cross-compilation.
-mcpu=name
This specifies the name of the target ARM processor. GCC uses this name to determine what kind of instructions it can emit when generating assembly code. Permissible names are: arm2, arm250, arm3, arm6, arm60, arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi, arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe, arm7tdmi, arm8, strongarm, strongarm110, strongarm1100, arm8, arm810, arm9, arm9e, arm920, arm920t, arm940t, arm9tdmi, arm10tdmi, arm1020t, xscale.
-mtune=name
This option is very similar to the -mcpu= option, except that instead of specifying the actual target processor type, and hence restricting which instructions can be used, it specifies that GCC should tune the performance of the code as if the target were of the type specified in this option, but still choosing the instructions that it will generate based on the cpu specified by a -mcpu= option. For some ARM implementations better performance can be obtained by using this option.
-march=name
This specifies the name of the target ARM architecture. GCC uses this name to determine what kind of instructions it can emit when generating assembly code. This option can be used in conjunction with or instead of the -mcpu= option. Permissible names are: armv2, armv2a, armv3, armv3m, armv4, armv4t, armv5, armv5t, armv5te.
-mfpe=number
-mfp=number
This specifies the version of the floating point emulation available on the target. Permissible values are 2 and 3. -mfp= is a synonym for -mfpe=, for compatibility with older versions of GCC.
-mstructure-size-boundary=n
The size of all structures and unions will be rounded up to a multiple of the number of bits set by this option. Permissible values are 8 and 32. The default value varies for different toolchains. For the COFF targeted toolchain the default value is 8. Specifying the larger number can produce faster, more efficient code, but can also increase the size of the program. The two values are potentially incompatible. Code compiled with one value cannot necessarily expect to work with code or libraries compiled with the other value, if they exchange information using structures or unions.
-mabort-on-noreturn
Generate a call to the function abort at the end of a noreturn function. It will be executed if the function tries to return.
-mlong-calls
-mno-long-calls
Tells the compiler to perform function calls by first loading the address of the function into a register and then performing a subroutine call on this register. This switch is needed if the target function will lie outside of the 64 megabyte addressing range of the offset based version of subroutine call instruction.

Even if this switch is enabled, not all function calls will be turned into long calls. The heuristic is that static functions, functions which have the short-call attribute, functions that are inside the scope of a #pragma no_long_calls directive and functions whose definitions have already been compiled within the current compilation unit, will not be turned into long calls. The exception to this rule is that weak function definitions, functions with the long-call attribute or the section attribute, and functions that are within the scope of a #pragma long_calls directive, will always be turned into long calls.

This feature is not enabled by default. Specifying -mno-long-calls will restore the default behavior, as will placing the function calls within the scope of a #pragma long_calls_off directive. Note these switches have no effect on how the compiler generates code to handle function calls via function pointers.

-mnop-fun-dllimport
Disable support for the dllimport attribute.
-msingle-pic-base
Treat the register used for PIC addressing as read-only, rather than loading it in the prologue for each function. The run-time system is responsible for initializing this register with an appropriate value before execution begins.
-mpic-register=reg
Specify the register to be used for PIC addressing. The default is R10 unless stack-checking is enabled, when R9 is used.
-mpoke-function-name
Write the name of each function into the text section, directly preceding the function prologue. The generated code is similar to this:
     t0
         .ascii "arm_poke_function_name", 0
         .align
     t1
         .word 0xff000000 + (t1 - t0)
     arm_poke_function_name
         mov     ip, sp
         stmfd   sp!, {fp, ip, lr, pc}
         sub     fp, ip, #4

When performing a stack backtrace, code can inspect the value of pc stored at fp + 0. If the trace function then looks at location pc - 12 and the top 8 bits are set, then we know that there is a function name embedded immediately preceding this location and has length ((pc[-3]) & 0xff000000).

-mthumb
Generate code for the 16-bit Thumb instruction set. The default is to use the 32-bit ARM instruction set.
-mtpcs-frame
Generate a stack frame that is compliant with the Thumb Procedure Call Standard for all non-leaf functions. (A leaf function is one that does not call any other functions.) The default is -mno-tpcs-frame.
-mtpcs-leaf-frame
Generate a stack frame that is compliant with the Thumb Procedure Call Standard for all leaf functions. (A leaf function is one that does not call any other functions.) The default is -mno-apcs-leaf-frame.
-mcallee-super-interworking
Gives all externally visible functions in the file being compiled an ARM instruction set header which switches to Thumb mode before executing the rest of the function. This allows these functions to be called from non-interworking code.
-mcaller-super-interworking
Allows calls via function pointers (including virtual functions) to execute correctly regardless of whether the target code has been compiled for interworking or not. There is a small overhead in the cost of executing a function pointer if this option is enabled.


Using the GNU Compiler Collection (GCC)

Node:ARM Pragmas, Next:Darwin Pragmas, Up:Pragmas

ARM Pragmas

The ARM target defines pragmas for controlling the default addition of long_call and short_call attributes to functions. See Function Attributes, for information about the effects of these attributes.

long_calls
Set all subsequent functions to have the long_call attribute.
no_long_calls
Set all subsequent functions to have the short_call attribute.
long_calls_off
Do not affect the long_call or short_call attributes of subsequent functions.


Using the GNU Compiler Collection (GCC)

Node:Arrays and pointers implementation, Next:Hints implementation, Previous:Floating point implementation, Up:C Implementation

Arrays and pointers

  • The result of converting a pointer to an integer or vice versa (6.3.2.3).

    A cast from pointer to integer discards most-significant bits if the pointer representation is larger than the integer type, sign-extends1 if the pointer representation is smaller than the integer type, otherwise the bits are unchanged.

    A cast from integer to pointer discards most-significant bits if the pointer representation is smaller than the integer type, extends according to the signedness of the integer type if the pointer representation is larger than the integer type, otherwise the bits are unchanged.

    When casting from pointer to integer and back again, the resulting pointer must reference the same object as the original pointer, otherwise the behavior is undefined. That is, one may not use integer arithmetic to avoid the undefined behavior of pointer arithmetic as proscribed in 6.5.6/8.

  • The size of the result of subtracting two pointers to elements of the same array (6.5.6).

Footnotes

  1. Future versions of GCC may zero-extend, or use a target-defined ptr_extend pattern. Do not rely on sign extension.


Using the GNU Compiler Collection (GCC)

Node:Asm Labels, Next:Explicit Reg Vars, Previous:Constraints, Up:C Extensions

Controlling Names Used in Assembler Code

You can specify the name to be used in the assembler code for a C function or variable by writing the asm (or __asm__) keyword after the declarator as follows:

int foo asm ("myfoo") = 2;

This specifies that the name to be used for the variable foo in the assembler code should be myfoo rather than the usual _foo.

On systems where an underscore is normally prepended to the name of a C function or variable, this feature allows you to define names for the linker that do not start with an underscore.

It does not make sense to use this feature with a non-static local variable since such variables do not have assembler names. If you are trying to put the variable in a particular register, see Explicit Reg Vars. GCC presently accepts such code with a warning, but will probably be changed to issue an error, rather than a warning, in the future.

You cannot use asm in this way in a function definition; but you can get the same effect by writing a declaration for the function before its definition and putting asm there, like this:

extern func () asm ("FUNC");

func (x, y)
     int x, y;
...

It is up to you to make sure that the assembler names you choose do not conflict with any other assembler symbols. Also, you must not use a register name; that would produce completely invalid assembler code. GCC does not as yet have the ability to store static variables in registers. Perhaps that will be added.


Using the GNU Compiler Collection (GCC)

Node:Assembler Options, Next:Link Options, Previous:Preprocessor Options, Up:Invoking GCC

Passing Options to the Assembler

You can pass options to the assembler.

-Wa,option
Pass option as an option to the assembler. If option contains commas, it is split into multiple options at the commas.


Using the GNU Compiler Collection (GCC)

Node:Attribute Syntax, Next:Function Prototypes, Previous:Function Attributes, Up:C Extensions

Attribute Syntax

This section describes the syntax with which __attribute__ may be used, and the constructs to which attribute specifiers bind, for the C language. Some details may vary for C++ and Objective-C. Because of infelicities in the grammar for attributes, some forms described here may not be successfully parsed in all cases.

There are some problems with the semantics of attributes in C++. For example, there are no manglings for attributes, although they may affect code generation, so problems may arise when attributed types are used in conjunction with templates or overloading. Similarly, typeid does not distinguish between types with different attributes. Support for attributes in C++ may be restricted in future to attributes on declarations only, but not on nested declarators.

See Function Attributes, for details of the semantics of attributes applying to functions. See Variable Attributes, for details of the semantics of attributes applying to variables. See Type Attributes, for details of the semantics of attributes applying to structure, union and enumerated types.

An attribute specifier is of the form __attribute__ ((attribute-list)). An attribute list is a possibly empty comma-separated sequence of attributes, where each attribute is one of the following:

  • Empty. Empty attributes are ignored.
  • A word (which may be an identifier such as unused, or a reserved word such as const).
  • A word, followed by, in parentheses, parameters for the attribute. These parameters take one of the following forms:
    • An identifier. For example, mode attributes use this form.
    • An identifier followed by a comma and a non-empty comma-separated list of expressions. For example, format attributes use this form.
    • A possibly empty comma-separated list of expressions. For example, format_arg attributes use this form with the list being a single integer constant expression, and alias attributes use this form with the list being a single string constant.

An attribute specifier list is a sequence of one or more attribute specifiers, not separated by any other tokens.

An attribute specifier list may appear after the colon following a label, other than a case or default label. The only attribute it makes sense to use after a label is unused. This feature is intended for code generated by programs which contains labels that may be unused but which is compiled with -Wall. It would not normally be appropriate to use in it human-written code, though it could be useful in cases where the code that jumps to the label is contained within an #ifdef conditional.

An attribute specifier list may appear as part of a struct, union or enum specifier. It may go either immediately after the struct, union or enum keyword, or after the closing brace. It is ignored if the content of the structure, union or enumerated type is not defined in the specifier in which the attribute specifier list is used--that is, in usages such as struct __attribute__((foo)) bar with no following opening brace. Where attribute specifiers follow the closing brace, they are considered to relate to the structure, union or enumerated type defined, not to any enclosing declaration the type specifier appears in, and the type defined is not complete until after the attribute specifiers.

Otherwise, an attribute specifier appears as part of a declaration, counting declarations of unnamed parameters and type names, and relates to that declaration (which may be nested in another declaration, for example in the case of a parameter declaration), or to a particular declarator within a declaration. Where an attribute specifier is applied to a parameter declared as a function or an array, it should apply to the function or array rather than the pointer to which the parameter is implicitly converted, but this is not yet correctly implemented.

Any list of specifiers and qualifiers at the start of a declaration may contain attribute specifiers, whether or not such a list may in that context contain storage class specifiers. (Some attributes, however, are essentially in the nature of storage class specifiers, and only make sense where storage class specifiers may be used; for example, section.) There is one necessary limitation to this syntax: the first old-style parameter declaration in a function definition cannot begin with an attribute specifier, because such an attribute applies to the function instead by syntax described below (which, however, is not yet implemented in this case). In some other cases, attribute specifiers are permitted by this grammar but not yet supported by the compiler. All attribute specifiers in this place relate to the declaration as a whole. In the obsolescent usage where a type of int is implied by the absence of type specifiers, such a list of specifiers and qualifiers may be an attribute specifier list with no other specifiers or qualifiers.

An attribute specifier list may appear immediately before a declarator (other than the first) in a comma-separated list of declarators in a declaration of more than one identifier using a single list of specifiers and qualifiers. Such attribute specifiers apply only to the identifier before whose declarator they appear. For example, in

__attribute__((noreturn)) void d0 (void),
    __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
     d2 (void)

the noreturn attribute applies to all the functions declared; the format attribute only applies to d1.

An attribute specifier list may appear immediately before the comma, = or semicolon terminating the declaration of an identifier other than a function definition. At present, such attribute specifiers apply to the declared object or function, but in future they may attach to the outermost adjacent declarator. In simple cases there is no difference, but, for example, in

void (****f)(void) __attribute__((noreturn));

at present the noreturn attribute applies to f, which causes a warning since f is not a function, but in future it may apply to the function ****f. The precise semantics of what attributes in such cases will apply to are not yet specified. Where an assembler name for an object or function is specified (see Asm Labels), at present the attribute must follow the asm specification; in future, attributes before the asm specification may apply to the adjacent declarator, and those after it to the declared object or function.

An attribute specifier list may, in future, be permitted to appear after the declarator in a function definition (before any old-style parameter declarations or the function body).

Attribute specifiers may be mixed with type qualifiers appearing inside the [] of a parameter array declarator, in the C99 construct by which such qualifiers are applied to the pointer to which the array is implicitly converted. Such attribute specifiers apply to the pointer, not to the array, but at present this is not implemented and they are ignored.

An attribute specifier list may appear at the start of a nested declarator. At present, there are some limitations in this usage: the attributes correctly apply to the declarator, but for most individual attributes the semantics this implies are not implemented. When attribute specifiers follow the * of a pointer declarator, they may be mixed with any type qualifiers present. The following describes the formal semantics of this syntax. It will make the most sense if you are familiar with the formal specification of declarators in the ISO C standard.

Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration T D1, where T contains declaration specifiers that specify a type Type (such as int) and D1 is a declarator that contains an identifier ident. The type specified for ident for derived declarators whose type does not include an attribute specifier is as in the ISO C standard.

If D1 has the form ( attribute-specifier-list D ), and the declaration T D specifies the type "derived-declarator-type-list Type" for ident, then T D1 specifies the type "derived-declarator-type-list attribute-specifier-list Type" for ident.

If D1 has the form * type-qualifier-and-attribute-specifier-list D, and the declaration T D specifies the type "derived-declarator-type-list Type" for ident, then T D1 specifies the type "derived-declarator-type-list type-qualifier-and-attribute-specifier-list Type" for ident.

For example,

void (__attribute__((noreturn)) ****f) (void);

specifies the type "pointer to pointer to pointer to pointer to non-returning function returning void". As another example,

char *__attribute__((aligned(8))) *f;

specifies the type "pointer to 8-byte-aligned pointer to char". Note again that this does not work with most attributes; for example, the usage of aligned and noreturn attributes given above is not yet supported.

For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes. If an attribute that only applies to types is applied to a declaration, it will be treated as applying to the type of that declaration. If an attribute that only applies to declarations is applied to the type of a declaration, it will be treated as applying to that declaration; and, for compatibility with code placing the attributes immediately before the identifier declared, such an attribute applied to a function return type will be treated as applying to the function type, and such an attribute applied to an array element type will be treated as applying to the array type. If an attribute that only applies to function types is applied to a pointer-to-function type, it will be treated as applying to the pointer target type; if such an attribute is applied to a function return type that is not a pointer-to-function type, it will be treated as applying to the function type.


Using the GNU Compiler Collection (GCC)

Node:AVR Options, Next:MCore Options, Previous:NS32K Options, Up:Submodel Options

AVR Options

These options are defined for AVR implementations:

-mmcu=mcu
Specify ATMEL AVR instruction set or MCU type.

Instruction set avr1 is for the minimal AVR core, not supported by the C compiler, only for assembler programs (MCU types: at90s1200, attiny10, attiny11, attiny12, attiny15, attiny28).

Instruction set avr2 (default) is for the classic AVR core with up to 8K program memory space (MCU types: at90s2313, at90s2323, attiny22, at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515, at90c8534, at90s8535).

Instruction set avr3 is for the classic AVR core with up to 128K program memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).

Instruction set avr4 is for the enhanced AVR core with up to 8K program memory space (MCU types: atmega8, atmega83, atmega85).

Instruction set avr5 is for the enhanced AVR core with up to 128K program memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323, atmega64, atmega128, at43usb355, at94k).

-msize
Output instruction sizes to the asm file.
-minit-stack=N
Specify the initial stack address, which may be a symbol or numeric value, __stack is the default.
-mno-interrupts
Generated code is not compatible with hardware interrupts. Code size will be smaller.
-mcall-prologues
Functions prologues/epilogues expanded as call to appropriate subroutines. Code size will be smaller.
-mno-tablejump
Do not generate tablejump insns which sometimes increase code size.
-mtiny-stack
Change only the low 8 bits of the stack pointer.


Using the GNU Compiler Collection (GCC)

Node:Backwards Compatibility, Previous:Deprecated Features, Up:C++ Extensions

Backwards Compatibility

Now that there is a definitive ISO standard C++, G++ has a specification to adhere to. The C++ language evolved over time, and features that used to be acceptable in previous drafts of the standard, such as the ARM [Annotated C++ Reference Manual], are no longer accepted. In order to allow compilation of C++ written to such drafts, G++ contains some backwards compatibilities. All such backwards compatibility features are liable to disappear in future versions of G++. They should be considered deprecated See Deprecated Features.

For scope
If a variable is declared at for scope, it used to remain in scope until the end of the scope which contained the for statement (rather than just within the for scope). G++ retains this, but issues a warning, if such a variable is accessed outside the for scope.
Implicit C language
Old C system header files did not contain an extern "C" {...} scope to set the language. On such systems, all header files are implicitly scoped inside a C language scope. Also, an empty prototype () will be treated as an unspecified number of arguments, rather than no arguments, as C++ demands.


Using the GNU Compiler Collection (GCC)

Node:Bound member functions, Next:C++ Attributes, Previous:Template Instantiation, Up:C++ Extensions

Extracting the function pointer from a bound pointer to member function

In C++, pointer to member functions (PMFs) are implemented using a wide pointer of sorts to handle all the possible call mechanisms; the PMF needs to store information about how to adjust the this pointer, and if the function pointed to is virtual, where to find the vtable, and where in the vtable to look for the member function. If you are using PMFs in an inner loop, you should really reconsider that decision. If that is not an option, you can extract the pointer to the function that would be called for a given object/PMF pair and call it directly inside the inner loop, to save a bit of time.

Note that you will still be paying the penalty for the call through a function pointer; on most modern architectures, such a call defeats the branch prediction features of the CPU. This is also true of normal virtual function calls.

The syntax for this extension is

extern A a;
extern int (A::*fp)();
typedef int (*fptr)(A *);

fptr p = (fptr)(a.*fp);

For PMF constants (i.e. expressions of the form &Klasse::Member), no object is needed to obtain the address of the function. They can be converted to function pointers directly:

fptr p1 = (fptr)(&A::foo);

You must specify -Wno-pmf-conversions to use this extension.


Using the GNU Compiler Collection (GCC)

Node:Bug Criteria, Next:Bug Lists, Up:Bugs

Have You Found a Bug?

If you are not sure whether you have found a bug, here are some guidelines:

  • If the compiler gets a fatal signal, for any input whatever, that is a compiler bug. Reliable compilers never crash.
  • If the compiler produces invalid assembly code, for any input whatever (except an asm statement), that is a compiler bug, unless the compiler reports errors (not just warnings) which would ordinarily prevent the assembler from being run.
  • If the compiler produces valid assembly code that does not correctly execute the input source code, that is a compiler bug.

    However, you must double-check to make sure, because you may have run into an incompatibility between GNU C and traditional C (see Incompatibilities). These incompatibilities might be considered bugs, but they are inescapable consequences of valuable features.

    Or you may have a program whose behavior is undefined, which happened by chance to give the desired results with another C or C++ compiler.

    For example, in many nonoptimizing compilers, you can write x; at the end of a function instead of return x;, with the same results. But the value of the function is undefined if return is omitted; it is not a bug when GCC produces different results.

    Problems often result from expressions with two increment operators, as in f (*p++, *p++). Your previous compiler might have interpreted that expression the way you intended; GCC might interpret it another way. Neither compiler is wrong. The bug is in your code.

    After you have localized the error to a single source line, it should be easy to check for these things. If your program is correct and well defined, you have found a compiler bug.

  • If the compiler produces an error message for valid input, that is a compiler bug.
  • If the compiler does not produce an error message for invalid input, that is a compiler bug. However, you should note that your idea of "invalid input" might be my idea of "an extension" or "support for traditional practice".
  • If you are an experienced user of one of the languages GCC supports, your suggestions for improvement of GCC are welcome in any case.


Using the GNU Compiler Collection (GCC)

Node:Bug Lists, Next:Bug Reporting, Previous:Bug Criteria, Up:Bugs

Where to Report Bugs

Send bug reports for the GNU Compiler Collection to gcc-bugs@gcc.gnu.org. In accordance with the GNU-wide convention, in which bug reports for tool "foo" are sent to bug-foo@gnu.org, the address bug-gcc@gnu.org may also be used; it will forward to the address given above.

Please read http://gcc.gnu.org/bugs.html for additional and/or more up-to-date bug reporting instructions before you post a bug report.


Using the GNU Compiler Collection (GCC)

Node:Bug Reporting, Next:gccbug, Previous:Bug Lists, Up:Bugs

How to Report Bugs

The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!

Often people omit facts because they think they know what causes the problem and they conclude that some details don't matter. Thus, you might assume that the name of the variable you use in an example does not matter. Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that name is stored in memory; perhaps, if the name were different, the contents of that location would fool the compiler into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable someone to fix the bug if it is not known. It isn't very important what happens if the bug is already known. Therefore, always write your bug reports on the assumption that the bug is not known.

Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" This cannot help us fix a bug, so it is basically useless. We respond by asking for enough details to enable us to investigate. You might as well expedite matters by sending them to begin with.

Try to make your bug report self-contained. If we have to ask you for more information, it is best if you include all the previous information in your response, as well as the information that was missing.

Please report each bug in a separate message. This makes it easier for us to track which bugs have been fixed and to forward your bugs reports to the appropriate maintainer.

To enable someone to investigate the bug, you should include all these things:

  • The version of GCC. You can get this by running it with the -v option.

    Without this, we won't know whether there is any point in looking for the bug in the current version of GCC.

  • A complete input file that will reproduce the bug. If the bug is in the C preprocessor, send a source file and any header files that it requires. If the bug is in the compiler proper (cc1), send the preprocessor output generated by adding -save-temps to the compilation command (see Debugging Options). When you do this, use the same -I, -D or -U options that you used in actual compilation. Then send the input.i or input.ii files generated.

    A single statement is not enough of an example. In order to compile it, it must be embedded in a complete file of compiler input; and the bug might depend on the details of how this is done.

    Without a real example one can compile, all anyone can do about your bug report is wish you luck. It would be futile to try to guess how to provoke the bug. For example, bugs in register allocation and reloading frequently depend on every little detail of the function they happen in.

    Even if the input file that fails comes from a GNU program, you should still send the complete test case. Don't ask the GCC maintainers to do the extra work of obtaining the program in question--they are all overworked as it is. Also, the problem may depend on what is in the header files on your system; it is unreliable for the GCC maintainers to try the problem with the header files available to them. By sending CPP output, you can eliminate this source of uncertainty and save us a certain percentage of wild goose chases.

  • The command arguments you gave GCC to compile that example and observe the bug. For example, did you use -O? To guarantee you won't omit something important, list all the options.

    If we were to try to guess the arguments, we would probably guess wrong and then we would not encounter the bug.

  • The type of machine you are using, and the operating system name and version number.
  • The operands you gave to the configure command when you installed the compiler.
  • A complete list of any modifications you have made to the compiler source. (We don't promise to investigate the bug unless it happens in an unmodified compiler. But if you've made modifications and don't tell us, then you are sending us on a wild goose chase.)

    Be precise about these changes. A description in English is not enough--send a context diff for them.

    Adding files of your own (such as a machine description for a machine we don't support) is a modification of the compiler source.

  • Details of any other deviations from the standard procedure for installing GCC.
  • A description of what behavior you observe that you believe is incorrect. For example, "The compiler gets a fatal signal," or, "The assembler instruction at line 208 in the output is incorrect."

    Of course, if the bug is that the compiler gets a fatal signal, then one can't miss it. But if the bug is incorrect output, the maintainer might not notice unless it is glaringly wrong. None of us has time to study all the assembler code from a 50-line C program just on the chance that one instruction might be wrong. We need you to do this part!

    Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of the compiler is out of synch, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and the copy here would not. If you said to expect a crash, then when the compiler here fails to crash, we would know that the bug was not happening. If you don't say to expect a crash, then we would not know whether the bug was happening. We would not be able to draw any conclusion from our observations.

    If the problem is a diagnostic when compiling GCC with some other compiler, say whether it is a warning or an error.

    Often the observed symptom is incorrect output when your program is run. Sad to say, this is not enough information unless the program is short and simple. None of us has time to study a large program to figure out how it would work if compiled correctly, much less which line of it was compiled wrong. So you will have to do that. Tell us which source line it is, and what incorrect result happens when that line is executed. A person who understands the program can find this as easily as finding a bug in the program itself.

  • If you send examples of assembler code output from GCC, please use -g when you make them. The debugging information includes source line numbers which are essential for correlating the output with the input.
  • If you wish to mention something in the GCC source, refer to it by context, not by line number.

    The line numbers in the development sources don't match those in your sources. Your line numbers would convey no useful information to the maintainers.

  • Additional information from a debugger might enable someone to find a problem on a machine which he does not have available. However, you need to think when you collect this information if you want it to have any chance of being useful.

    For example, many people send just a backtrace, but that is never useful by itself. A simple backtrace with arguments conveys little about GCC because the compiler is largely data-driven; the same functions are called over and over for different RTL insns, doing different things depending on the details of the insn.

    Most of the arguments listed in the backtrace are useless because they are pointers to RTL list structure. The numeric values of the pointers, which the debugger prints in the backtrace, have no significance whatever; all that matters is the contents of the objects they point to (and most of the contents are other such pointers).

    In addition, most compiler passes consist of one or more loops that scan the RTL insn sequence. The most vital piece of information about such a loop--which insn it has reached--is usually in a local variable, not in an argument.

    What you need to provide in addition to a backtrace are the values of the local variables for several stack frames up. When a local variable or an argument is an RTX, first print its value and then use the GDB command pr to print the RTL expression that it points to. (If GDB doesn't run on your machine, use your debugger to call the function debug_rtx with the RTX as an argument.) In general, whenever a variable is a pointer, its value is no use without the data it points to.

Here are some things that are not necessary:

  • A description of the envelope of the bug.

    Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it.

    This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. You might as well save your time for something else.

    Of course, if you can find a simpler example to report instead of the original one, that is a convenience. Errors in the output will be easier to spot, running under the debugger will take less time, etc. Most GCC bugs involve just one function, so the most straightforward way to simplify an example is to delete all the function definitions except the one where the bug occurs. Those earlier in the file may be replaced by external declarations if the crucial function depends on them. (Exception: inline functions may affect compilation of functions defined later in the file.)

    However, simplification is not vital; if you don't want to do this, report the bug anyway and send the entire test case you used.

  • In particular, some people insert conditionals #ifdef BUG around a statement which, if removed, makes the bug not happen. These are just clutter; we won't pay any attention to them anyway. Besides, you should send us cpp output, and that can't have conditionals.
  • A patch for the bug.

    A patch for the bug is useful if it is a good one. But don't omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all.

    Sometimes with a program as complicated as GCC it is very hard to construct an example that will make the program follow a certain path through the code. If you don't send the example, we won't be able to construct one, so we won't be able to verify that the bug is fixed.

    And if we can't understand what bug you are trying to fix, or why your patch should be an improvement, we won't install it. A test case will help us to understand.

    See http://gcc.gnu.org/contribute.html for guidelines on how to make it easy for us to understand and install your patches.

  • A guess about what the bug is or what it depends on.

    Such guesses are usually wrong. Even I can't guess right about such things without first using the debugger to find the facts.

  • A core dump file.

    We have no way of examining a core dump for your type of machine unless we have an identical system--and if we do have one, we should be able to reproduce the crash ourselves.


Using the GNU Compiler Collection (GCC)

Node:Bugs, Next:Service, Previous:Trouble, Up:Top

Reporting Bugs

Your bug reports play an essential role in making GCC reliable.

When you encounter a problem, the first thing to do is to see if it is already known. See Trouble. If it isn't known, then you should report the problem.

Reporting a bug may help you by bringing a solution to your problem, or it may not. (If it does not, look in the service directory; see Service.) In any case, the principal function of a bug report is to help the entire community by making the next version of GCC work better. Bug reports are your contribution to the maintenance of GCC.

Since the maintainers are very overloaded, we cannot respond to every bug report. However, if the bug has not been fixed, we are likely to send you a patch and ask you to tell us whether it works.

In order for a bug report to serve its purpose, you must include the information that makes for fixing the bug.

  • Criteria: Have you really found a bug?
  • Where: Where to send your bug report.
  • Reporting: How to report a bug effectively.
  • GNATS: You can use a bug reporting tool.
  • Known: Known problems.
  • Help: Where to ask for help.


Using the GNU Compiler Collection (GCC)

Node:C++ Attributes, Next:Java Exceptions, Previous:Bound member functions, Up:C++ Extensions

C++-Specific Variable, Function, and Type Attributes

Some attributes only make sense for C++ programs.

init_priority (priority)

In Standard C++, objects defined at namespace scope are guaranteed to be initialized in an order in strict accordance with that of their definitions in a given translation unit. No guarantee is made for initializations across translation units. However, GNU C++ allows users to control the order of initialization of objects defined at namespace scope with the init_priority attribute by specifying a relative priority, a constant integral expression currently bounded between 101 and 65535 inclusive. Lower numbers indicate a higher priority.

In the following example, A would normally be created before B, but the init_priority attribute has reversed that order:

Some_Class  A  __attribute__ ((init_priority (2000)));
Some_Class  B  __attribute__ ((init_priority (543)));

Note that the particular values of priority do not matter; only their relative ordering.

java_interface

This type attribute informs C++ that the class is a Java interface. It may only be applied to classes declared within an extern "Java" block. Calls to methods declared in this interface will be dispatched using GCJ's interface table mechanism, instead of regular virtual table dispatch.


Using the GNU Compiler Collection (GCC)

Node:C++ Comments, Next:Dollar Signs, Previous:Function Prototypes, Up:C Extensions

C++ Style Comments

In GNU C, you may use C++ style comments, which start with // and continue until the end of the line. Many other C implementations allow such comments, and they are likely to be in a future C standard. However, C++ style comments are not recognized if you specify -ansi, a -std option specifying a version of ISO C before C99, or -traditional, since they are incompatible with traditional constructs like dividend//*comment*/divisor.


Using the GNU Compiler Collection (GCC)

Node:C++ Dialect Options, Next:Objective-C Dialect Options, Previous:C Dialect Options, Up:Invoking GCC

Options Controlling C++ Dialect

This section describes the command-line options that are only meaningful for C++ programs; but you can also use most of the GNU compiler options regardless of what language your program is in. For example, you might compile a file firstClass.C like this:

g++ -g -frepo -O -c firstClass.C

In this example, only -frepo is an option meant only for C++ programs; you can use the other options with any language supported by GCC.

Here is a list of options that are only for compiling C++ programs:

-fno-access-control
Turn off all access checking. This switch is mainly useful for working around bugs in the access control code.
-fcheck-new
Check that the pointer returned by operator new is non-null before attempting to modify the storage allocated. The current Working Paper requires that operator new never return a null pointer, so this check is normally unnecessary.

An alternative to using this option is to specify that your operator new does not throw any exceptions; if you declare it throw(), G++ will check the return value. See also new (nothrow).

-fconserve-space
Put uninitialized or runtime-initialized global variables into the common segment, as C does. This saves space in the executable at the cost of not diagnosing duplicate definitions. If you compile with this flag and your program mysteriously crashes after main() has completed, you may have an object that is being destroyed twice because two definitions were merged.

This option is no longer useful on most targets, now that support has been added for putting variables into BSS without making them common.

-fno-const-strings
Give string constants type char * instead of type const char *. By default, G++ uses type const char * as required by the standard. Even if you use -fno-const-strings, you cannot actually modify the value of a string constant, unless you also use -fwritable-strings.

This option might be removed in a future release of G++. For maximum portability, you should structure your code so that it works with string constants that have type const char *.

-fdollars-in-identifiers
Accept $ in identifiers. You can also explicitly prohibit use of $ with the option -fno-dollars-in-identifiers. (GNU C allows $ by default on most target systems, but there are a few exceptions.) Traditional C allowed the character $ to form part of identifiers. However, ISO C and C++ forbid $ in identifiers.
-fno-elide-constructors
The C++ standard allows an implementation to omit creating a temporary which is only used to initialize another object of the same type. Specifying this option disables that optimization, and forces G++ to call the copy constructor in all cases.
-fno-enforce-eh-specs
Don't check for violation of exception specifications at runtime. This option violates the C++ standard, but may be useful for reducing code size in production builds, much like defining NDEBUG. The compiler will still optimize based on the exception specifications.
-fexternal-templates

Cause #pragma interface and implementation to apply to template instantiation; template instances are emitted or not according to the location of the template definition. See Template Instantiation, for more information.

This option is deprecated.

-falt-external-templates
Similar to -fexternal-templates, but template instances are emitted or not according to the place where they are first instantiated. See Template Instantiation, for more information.

This option is deprecated.

-ffor-scope
-fno-for-scope
If -ffor-scope is specified, the scope of variables declared in a for-init-statement is limited to the for loop itself, as specified by the C++ standard. If -fno-for-scope is specified, the scope of variables declared in a for-init-statement extends to the end of the enclosing scope, as was the case in old versions of G++, and other (traditional) implementations of C++.

The default if neither flag is given to follow the standard, but to allow and give a warning for old-style code that would otherwise be invalid, or have different behavior.

-fno-gnu-keywords
Do not recognize typeof as a keyword, so that code can use this word as an identifier. You can use the keyword __typeof__ instead. -ansi implies -fno-gnu-keywords.
-fno-implicit-templates
Never emit code for non-inline templates which are instantiated implicitly (i.e. by use); only emit code for explicit instantiations. See Template Instantiation, for more information.
-fno-implicit-inline-templates
Don't emit code for implicit instantiations of inline templates, either. The default is to handle inlines differently so that compiles with and without optimization will need the same set of explicit instantiations.
-fno-implement-inlines
To save space, do not emit out-of-line copies of inline functions controlled by #pragma implementation. This will cause linker errors if these functions are not inlined everywhere they are called.
-fms-extensions
Disable pedantic warnings about constructs used in MFC, such as implicit int and getting a pointer to member function via non-standard syntax.
-fno-nonansi-builtins
Disable built-in declarations of functions that are not mandated by ANSI/ISO C. These include ffs, alloca, _exit, index, bzero, conjf, and other related functions.
-fno-operator-names
Do not treat the operator name keywords and, bitand, bitor, compl, not, or and xor as synonyms as keywords.
-fno-optional-diags
Disable diagnostics that the standard says a compiler does not need to issue. Currently, the only such diagnostic issued by G++ is the one for a name having multiple meanings within a class.
-fpermissive
Downgrade messages about nonconformant code from errors to warnings. By default, G++ effectively sets -pedantic-errors without -pedantic; this option reverses that. This behavior and this option are superseded by -pedantic, which works as it does for GNU C.
-frepo
Enable automatic template instantiation at link time. This option also implies -fno-implicit-templates. See Template Instantiation, for more information.
-fno-rtti
Disable generation of information about every class with virtual functions for use by the C++ runtime type identification features (dynamic_cast and typeid). If you don't use those parts of the language, you can save some space by using this flag. Note that exception handling uses the same information, but it will generate it as needed.
-fstats
Emit statistics about front-end processing at the end of the compilation. This information is generally only useful to the G++ development team.
-ftemplate-depth-n
Set the maximum instantiation depth for template classes to n. A limit on the template instantiation depth is needed to detect endless recursions during template class instantiation. ANSI/ISO C++ conforming programs must not rely on a maximum depth greater than 17.
-fuse-cxa-atexit
Register destructors for objects with static storage duration with the __cxa_atexit function rather than the atexit function. This option is required for fully standards-compliant handling of static destructors, but will only work if your C library supports __cxa_atexit.
-fvtable-gc
Emit special relocations for vtables and virtual function references so that the linker can identify unused virtual functions and zero out vtable slots that refer to them. This is most useful with -ffunction-sections and -Wl,--gc-sections, in order to also discard the functions themselves.

This optimization requires GNU as and GNU ld. Not all systems support this option. -Wl,--gc-sections is ignored without -static.

-fno-weak
Do not use weak symbol support, even if it is provided by the linker. By default, G++ will use weak symbols if they are available. This option exists only for testing, and should not be used by end-users; it will result in inferior code and has no benefits. This option may be removed in a future release of G++.
-nostdinc++
Do not search for header files in the standard directories specific to C++, but do still search the other standard directories. (This option is used when building the C++ library.)

In addition, these optimization, warning, and code generation options have meanings only for C++ programs:

-fno-default-inline
Do not assume inline for functions defined inside a class scope. See Options That Control Optimization. Note that these functions will have linkage like inline functions; they just won't be inlined by default.
-Wctor-dtor-privacy (C++ only)
Warn when a class seems unusable, because all the constructors or destructors in a class are private and the class has no friends or public static member functions.
-Wnon-virtual-dtor (C++ only)
Warn when a class declares a non-virtual destructor that should probably be virtual, because it looks like the class will be used polymorphically.
-Wreorder (C++ only)
Warn when the order of member initializers given in the code does not match the order in which they must be executed. For instance:
struct A {
  int i;
  int j;
  A(): j (0), i (1) { }
};

Here the compiler will warn that the member initializers for i and j will be rearranged to match the declaration order of the members.

The following -W... options are not affected by -Wall.

-Weffc++ (C++ only)
Warn about violations of the following style guidelines from Scott Meyers' Effective C++ book:
  • Item 11: Define a copy constructor and an assignment operator for classes with dynamically allocated memory.
  • Item 12: Prefer initialization to assignment in constructors.
  • Item 14: Make destructors virtual in base classes.
  • Item 15: Have operator= return a reference to *this.
  • Item 23: Don't try to return a reference when you must return an object.

and about violations of the following style guidelines from Scott Meyers' More Effective C++ book:

  • Item 6: Distinguish between prefix and postfix forms of increment and decrement operators.
  • Item 7: Never overload &&, ||, or ,.

If you use this option, you should be aware that the standard library headers do not obey all of these guidelines; you can use grep -v to filter out those warnings.

-Wno-deprecated (C++ only)
Do not warn about usage of deprecated features. See Deprecated Features.
-Wno-non-template-friend (C++ only)
Disable warnings when non-templatized friend functions are declared within a template. With the advent of explicit template specification support in G++, if the name of the friend is an unqualified-id (i.e., friend foo(int)), the C++ language specification demands that the friend declare or define an ordinary, nontemplate function. (Section 14.5.3). Before G++ implemented explicit specification, unqualified-ids could be interpreted as a particular specialization of a templatized function. Because this non-conforming behavior is no longer the default behavior for G++, -Wnon-template-friend allows the compiler to check existing code for potential trouble spots, and is on by default. This new compiler behavior can be turned off with -Wno-non-template-friend which keeps the conformant compiler code but disables the helpful warning.
-Wold-style-cast (C++ only)
Warn if an old-style (C-style) cast to a non-void type is used within a C++ program. The new-style casts (static_cast, reinterpret_cast, and const_cast) are less vulnerable to unintended effects, and much easier to grep for.
-Woverloaded-virtual (C++ only)
Warn when a function declaration hides virtual functions from a base class. For example, in:
struct A {
  virtual void f();
};

struct B: public A {
  void f(int);
};

the A class version of f is hidden in B, and code like this:

B* b;
b->f();

will fail to compile.

-Wno-pmf-conversions (C++ only)
Disable the diagnostic for converting a bound pointer to member function to a plain pointer.
-Wsign-promo (C++ only)
Warn when overload resolution chooses a promotion from unsigned or enumeral type to a signed type over a conversion to an unsigned type of the same size. Previous versions of G++ would try to preserve unsignedness, but the standard mandates the current behavior.
-Wsynth (C++ only)
Warn when G++'s synthesis behavior does not match that of cfront. For instance:
struct A {
  operator int ();
  A& operator = (int);
};

main ()
{
  A a,b;
  a = b;
}

In this example, G++ will synthesize a default A& operator = (const A&);, while cfront will use the user-defined operator =.


Using the GNU Compiler Collection (GCC)

Node:C++ Extensions, Next:Objective-C, Previous:C Extensions, Up:Top

Extensions to the C++ Language

The GNU compiler provides these extensions to the C++ language (and you can also use most of the C language extensions in your C++ programs). If you want to write code that checks whether these features are available, you can test for the GNU compiler the same way as for C programs: check for a predefined macro __GNUC__. You can also use __GNUG__ to test specifically for GNU C++ (see Standard Predefined Macros).

  • Min and Max: C++ Minimum and maximum operators.
  • Volatiles: What constitutes an access to a volatile object.
  • Restricted Pointers: C99 restricted pointers and references.
  • Vague Linkage: Where G++ puts inlines, vtables and such.
  • C++ Interface: You can use a single C++ header file for both declarations and definitions.
  • Template Instantiation: Methods for ensuring that exactly one copy of each needed template instantiation is emitted.
  • Bound member functions: You can extract a function pointer to the method denoted by a ->* or .* expression.
  • C++ Attributes: Variable, function, and type attributes for C++ only.
  • Java Exceptions: Tweaking exception handling to work with Java.
  • Deprecated Features: Things might disappear from g++.
  • Backwards Compatibility: Compatibilities with earlier definitions of C++.


Using the GNU Compiler Collection (GCC)

Node:C++ Interface, Next:Template Instantiation, Previous:Vague Linkage, Up:C++ Extensions

Declarations and Definitions in One Header

C++ object definitions can be quite complex. In principle, your source code will need two kinds of things for each object that you use across more than one source file. First, you need an interface specification, describing its structure with type declarations and function prototypes. Second, you need the implementation itself. It can be tedious to maintain a separate interface description in a header file, in parallel to the actual implementation. It is also dangerous, since separate interface and implementation definitions may not remain parallel.

With GNU C++, you can use a single header file for both purposes.

Warning: The mechanism to specify this is in transition. For the nonce, you must use one of two #pragma commands; in a future release of GNU C++, an alternative mechanism will make these #pragma commands unnecessary.

The header file contains the full definitions, but is marked with #pragma interface in the source code. This allows the compiler to use the header file only as an interface specification when ordinary source files incorporate it with #include. In the single source file where the full implementation belongs, you can use either a naming convention or #pragma implementation to indicate this alternate use of the header file.

#pragma interface
#pragma interface "subdir/objects.h"
Use this directive in header files that define object classes, to save space in most of the object files that use those classes. Normally, local copies of certain information (backup copies of inline member functions, debugging information, and the internal tables that implement virtual functions) must be kept in each object file that includes class definitions. You can use this pragma to avoid such duplication. When a header file containing #pragma interface is included in a compilation, this auxiliary information will not be generated (unless the main input source file itself uses #pragma implementation). Instead, the object files will contain references to be resolved at link time.

The second form of this directive is useful for the case where you have multiple headers with the same name in different directories. If you use this form, you must specify the same string to #pragma implementation.

#pragma implementation
#pragma implementation "objects.h"
Use this pragma in a main input file, when you want full output from included header files to be generated (and made globally visible). The included header file, in turn, should use #pragma interface. Backup copies of inline member functions, debugging information, and the internal tables used to implement virtual functions are all generated in implementation files.

If you use #pragma implementation with no argument, it applies to an include file with the same basename1 as your source file. For example, in allclass.cc, giving just #pragma implementation by itself is equivalent to #pragma implementation "allclass.h".

In versions of GNU C++ prior to 2.6.0 allclass.h was treated as an implementation file whenever you would include it from allclass.cc even if you never specified #pragma implementation. This was deemed to be more trouble than it was worth, however, and disabled.

If you use an explicit #pragma implementation, it must appear in your source file before you include the affected header files.

Use the string argument if you want a single implementation file to include code from multiple header files. (You must also use #include to include the header file; #pragma implementation only specifies how to use the file--it doesn't actually include it.)

There is no way to split up the contents of a single header file into multiple implementation files.

#pragma implementation and #pragma interface also have an effect on function inlining.

If you define a class in a header file marked with #pragma interface, the effect on a function defined in that class is similar to an explicit extern declaration--the compiler emits no code at all to define an independent version of the function. Its definition is used only for inlining with its callers.

Conversely, when you include the same header file in a main source file that declares it as #pragma implementation, the compiler emits code for the function itself; this defines a version of the function that can be found via pointers (or by callers compiled without inlining). If all calls to the function can be inlined, you can avoid emitting the function by compiling with -fno-implement-inlines. If any calls were not inlined, you will get linker errors.

Footnotes

  1. A file's basename was the name stripped of all leading path information and of trailing suffixes, such as .h or .C or .cc.


Using the GNU Compiler Collection (GCC)

Node:C++ Misunderstandings, Next:Protoize Caveats, Previous:Disappointments, Up:Trouble

Common Misunderstandings with GNU C++

C++ is a complex language and an evolving one, and its standard definition (the ISO C++ standard) was only recently completed. As a result, your C++ compiler may occasionally surprise you, even when its behavior is correct. This section discusses some areas that frequently give rise to questions of this sort.

  • Static Definitions: Static member declarations are not definitions
  • Temporaries: Temporaries may vanish before you expect
  • Copy Assignment: Copy Assignment operators copy virtual bases twice


Using the GNU Compiler Collection (GCC)

Node:C Dialect Options, Next:C++ Dialect Options, Previous:Invoking G++, Up:Invoking GCC

Options Controlling C Dialect

The following options control the dialect of C (or languages derived from C, such as C++ and Objective-C) that the compiler accepts:

-ansi
In C mode, support all ISO C89 programs. In C++ mode, remove GNU extensions that conflict with ISO C++.

This turns off certain features of GCC that are incompatible with ISO C89 (when compiling C code), or of standard C++ (when compiling C++ code), such as the asm and typeof keywords, and predefined macros such as unix and vax that identify the type of system you are using. It also enables the undesirable and rarely used ISO trigraph feature. For the C compiler, it disables recognition of C++ style // comments as well as the inline keyword.

The alternate keywords __asm__, __extension__, __inline__ and __typeof__ continue to work despite -ansi. You would not want to use them in an ISO C program, of course, but it is useful to put them in header files that might be included in compilations done with -ansi. Alternate predefined macros such as __unix__ and __vax__ are also available, with or without -ansi.

The -ansi option does not cause non-ISO programs to be rejected gratuitously. For that, -pedantic is required in addition to -ansi. See Warning Options.

The macro __STRICT_ANSI__ is predefined when the -ansi option is used. Some header files may notice this macro and refrain from declaring certain functions or defining certain macros that the ISO standard doesn't call for; this is to avoid interfering with any programs that might use these names for other things.

Functions which would normally be built in but do not have semantics defined by ISO C (such as alloca and ffs) are not built-in functions with -ansi is used. See Other built-in functions provided by GCC, for details of the functions affected.

-std=
Determine the language standard. This option is currently only supported when compiling C. A value for this option must be provided; possible values are
c89
iso9899:1990
ISO C89 (same as -ansi).
iso9899:199409
ISO C89 as modified in amendment 1.
c99
c9x
iso9899:1999
iso9899:199x
ISO C99. Note that this standard is not yet fully supported; see http://gcc.gnu.org/gcc-3.1/c99status.html for more information. The names c9x and iso9899:199x are deprecated.
gnu89
Default, ISO C89 plus GNU extensions (including some C99 features).
gnu99
gnu9x
ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC, this will become the default. The name gnu9x is deprecated.

Even when this option is not specified, you can still use some of the features of newer standards in so far as they do not conflict with previous C standards. For example, you may use __restrict__ even when -std=c99 is not specified.

The -std options specifying some version of ISO C have the same effects as -ansi, except that features that were not in ISO C89 but are in the specified version (for example, // comments and the inline keyword in ISO C99) are not disabled.

See Language Standards Supported by GCC, for details of these standard versions.

-aux-info filename
Output to the given filename prototyped declarations for all functions declared and/or defined in a translation unit, including those in header files. This option is silently ignored in any language other than C.

Besides declarations, the file indicates, in comments, the origin of each declaration (source file and line), whether the declaration was implicit, prototyped or unprototyped (I, N for new or O for old, respectively, in the first character after the line number and the colon), and whether it came from a declaration or a definition (C or F, respectively, in the following character). In the case of function definitions, a K&R-style list of arguments followed by their declarations is also provided, inside comments, after the declaration.

-fno-asm
Do not recognize asm, inline or typeof as a keyword, so that code can use these words as identifiers. You can use the keywords __asm__, __inline__ and __typeof__ instead. -ansi implies -fno-asm.

In C++, this switch only affects the typeof keyword, since asm and inline are standard keywords. You may want to use the -fno-gnu-keywords flag instead, which has the same effect. In C99 mode (-std=c99 or -std=gnu99), this switch only affects the asm and typeof keywords, since inline is a standard keyword in ISO C99.

-fno-builtin
-fno-builtin-function (C and Objective-C only)
Don't recognize built-in functions that do not begin with __builtin_ as prefix. See Other built-in functions provided by GCC, for details of the functions affected, including those which are not built-in functions when -ansi or -std options for strict ISO C conformance are used because they do not have an ISO standard meaning.

GCC normally generates special code to handle certain built-in functions more efficiently; for instance, calls to alloca may become single instructions that adjust the stack directly, and calls to memcpy may become inline copy loops. The resulting code is often both smaller and faster, but since the function calls no longer appear as such, you cannot set a breakpoint on those calls, nor can you change the behavior of the functions by linking with a different library.

In C++, -fno-builtin is always in effect. The -fbuiltin option has no effect. Therefore, in C++, the only way to get the optimization benefits of built-in functions is to call the function using the __builtin_ prefix. The GNU C++ Standard Library uses built-in functions to implement many functions (like std::strchr), so that you automatically get efficient code.

With the -fno-builtin-function option, not available when compiling C++, only the built-in function function is disabled. function must not begin with __builtin_. If a function is named this is not built-in in this version of GCC, this option is ignored. There is no corresponding -fbuiltin-function option; if you wish to enable built-in functions selectively when using -fno-builtin or -ffreestanding, you may define macros such as:

#define abs(n)          __builtin_abs ((n))
#define strcpy(d, s)    __builtin_strcpy ((d), (s))

-fhosted

Assert that compilation takes place in a hosted environment. This implies -fbuiltin. A hosted environment is one in which the entire standard library is available, and in which main has a return type of int. Examples are nearly everything except a kernel. This is equivalent to -fno-freestanding.

-ffreestanding

Assert that compilation takes place in a freestanding environment. This implies -fno-builtin. A freestanding environment is one in which the standard library may not exist, and program startup may not necessarily be at main. The most obvious example is an OS kernel. This is equivalent to -fno-hosted.

See Language Standards Supported by GCC, for details of freestanding and hosted environments.

-trigraphs
Support ISO C trigraphs. The -ansi option (and -std options for strict ISO C conformance) implies -trigraphs.
-no-integrated-cpp
Invoke the external cpp during compilation. The default is to use the integrated cpp (internal cpp). This option also allows a user-supplied cpp via the -B option. This flag is applicable in both C and C++ modes.

We do not guarantee to retain this option in future, and we may change its semantics.

-traditional
Attempt to support some aspects of traditional C compilers. Specifically:
  • All extern declarations take effect globally even if they are written inside of a function definition. This includes implicit declarations of functions.
  • The newer keywords typeof, inline, signed, const and volatile are not recognized. (You can still use the alternative keywords such as __typeof__, __inline__, and so on.)
  • Comparisons between pointers and integers are always allowed.
  • Integer types unsigned short and unsigned char promote to unsigned int.
  • Out-of-range floating point literals are not an error.
  • Certain constructs which ISO regards as a single invalid preprocessing number, such as 0xe-0xd, are treated as expressions instead.
  • String "constants" are not necessarily constant; they are stored in writable space, and identical looking constants are allocated separately. (This is the same as the effect of -fwritable-strings.)
  • All automatic variables not declared register are preserved by longjmp. Ordinarily, GNU C follows ISO C: automatic variables not declared volatile may be clobbered.
  • The character escape sequences \x and \a evaluate as the literal characters x and a respectively. Without -traditional, \x is a prefix for the hexadecimal representation of a character, and \a produces a bell.

This option is deprecated and may be removed.

You may wish to use -fno-builtin as well as -traditional if your program uses names that are normally GNU C built-in functions for other purposes of its own.

You cannot use -traditional if you include any header files that rely on ISO C features. Some vendors are starting to ship systems with ISO C header files and you cannot use -traditional on such systems to compile files that include any system headers.

The -traditional option also enables -traditional-cpp.

-traditional-cpp
Attempt to support some aspects of traditional C preprocessors. See the GNU CPP manual for details.
-fcond-mismatch
Allow conditional expressions with mismatched types in the second and third arguments. The value of such an expression is void. This option is not supported for C++.
-funsigned-char
Let the type char be unsigned, like unsigned char.

Each kind of machine has a default for what char should be. It is either like unsigned char by default or like signed char by default.

Ideally, a portable program should always use signed char or unsigned char when it depends on the signedness of an object. But many programs have been written to use plain char and expect it to be signed, or expect it to be unsigned, depending on the machines they were written for. This option, and its inverse, let you make such a program work with the opposite default.

The type char is always a distinct type from each of signed char or unsigned char, even though its behavior is always just like one of those two.

-fsigned-char
Let the type char be signed, like signed char.

Note that this is equivalent to -fno-unsigned-char, which is the negative form of -funsigned-char. Likewise, the option -fno-signed-char is equivalent to -funsigned-char.

-fsigned-bitfields
-funsigned-bitfields
-fno-signed-bitfields
-fno-unsigned-bitfields
These options control whether a bit-field is signed or unsigned, when the declaration does not use either signed or unsigned. By default, such a bit-field is signed, because this is consistent: the basic integer types such as int are signed types.

However, when -traditional is used, bit-fields are all unsigned no matter what.

-fwritable-strings
Store string constants in the writable data segment and don't uniquize them. This is for compatibility with old programs which assume they can write into string constants. The option -traditional also has this effect.

Writing into string constants is a very bad idea; "constants" should be constant.

-fallow-single-precision
Do not promote single precision math operations to double precision, even when compiling with -traditional.

Traditional K&R C promotes all floating point operations to double precision, regardless of the sizes of the operands. On the architecture for which you are compiling, single precision may be faster than double precision. If you must use -traditional, but want to use single precision operations when the operands are single precision, use this option. This option has no effect when compiling with ISO or GNU C conventions (the default).

-fshort-wchar
Override the underlying type for wchar_t to be short unsigned int instead of the default for the target. This option is useful for building programs to run under WINE.


Using the GNU Compiler Collection (GCC)

Node:C Extensions, Next:C++ Extensions, Previous:C Implementation, Up:Top

Extensions to the C Language Family

GNU C provides several language features not found in ISO standard C. (The -pedantic option directs GCC to print a warning message if any of these features is used.) To test for the availability of these features in conditional compilation, check for a predefined macro __GNUC__, which is always defined under GCC.

These extensions are available in C and Objective-C. Most of them are also available in C++. See Extensions to the C++ Language, for extensions that apply only to C++.

Some features that are in ISO C99 but not C89 or C++ are also, as extensions, accepted by GCC in C89 mode and in C++.

  • Statement Exprs: Putting statements and declarations inside expressions.
  • Local Labels: Labels local to a statement-expression.
  • Labels as Values: Getting pointers to labels, and computed gotos.
  • Nested Functions: As in Algol and Pascal, lexical scoping of functions.
  • Constructing Calls: Dispatching a call to another function.
  • Naming Types: Giving a name to the type of some expression.
  • Typeof: typeof: referring to the type of an expression.
  • Lvalues: Using ?:, , and casts in lvalues.
  • Conditionals: Omitting the middle operand of a ?: expression.
  • Long Long: Double-word integers---long long int.
  • Complex: Data types for complex numbers.
  • Hex Floats: Hexadecimal floating-point constants.
  • Zero Length: Zero-length arrays.
  • Variable Length: Arrays whose length is computed at run time.
  • Variadic Macros: Macros with a variable number of arguments.
  • Escaped Newlines: Slightly looser rules for escaped newlines.
  • Multi-line Strings: String literals with embedded newlines.
  • Subscripting: Any array can be subscripted, even if not an lvalue.
  • Pointer Arith: Arithmetic on void-pointers and function pointers.
  • Initializers: Non-constant initializers.
  • Compound Literals: Compound literals give structures, unions or arrays as values.
  • Designated Inits: Labeling elements of initializers.
  • Cast to Union: Casting to union type from any member of the union.
  • Case Ranges: `case 1 ... 9' and such.
  • Mixed Declarations: Mixing declarations and code.
  • Function Attributes: Declaring that functions have no side effects, or that they can never return.
  • Attribute Syntax: Formal syntax for attributes.
  • Function Prototypes: Prototype declarations and old-style definitions.
  • C++ Comments: C++ comments are recognized.
  • Dollar Signs: Dollar sign is allowed in identifiers.
  • Character Escapes: \e stands for the character <ESC>.
  • Variable Attributes: Specifying attributes of variables.
  • Type Attributes: Specifying attributes of types.
  • Alignment: Inquiring about the alignment of a type or variable.
  • Inline: Defining inline functions (as fast as macros).
  • Extended Asm: Assembler instructions with C expressions as operands. (With them you can define ``built-in'' functions.)
  • Constraints: Constraints for asm operands
  • Asm Labels: Specifying the assembler name to use for a C symbol.
  • Explicit Reg Vars: Defining variables residing in specified registers.
  • Alternate Keywords: __const__, __asm__, etc., for header files.
  • Incomplete Enums: enum foo;, with details to follow.
  • Function Names: Printable strings which are the name of the current function.
  • Return Address: Getting the return or frame address of a function.
  • Vector Extensions: Using vector instructions through built-in functions.
  • Other Builtins: Other built-in functions.
  • Target Builtins: Built-in functions specific to particular targets.
  • Pragmas: Pragmas accepted by GCC.
  • Unnamed Fields: Unnamed struct/union fields within structs/unions.


Using the GNU Compiler Collection (GCC)

Node:C Implementation, Next:C Extensions, Previous:Invoking GCC, Up:Top

C Implementation-defined behavior

A conforming implementation of ISO C is required to document its choice of behavior in each of the areas that are designated "implementation defined." The following lists all such areas, along with the section number from the ISO/IEC 9899:1999 standard.

  • Translation implementation:
  • Environment implementation:
  • Identifiers implementation:
  • Characters implementation:
  • Integers implementation:
  • Floating point implementation:
  • Arrays and pointers implementation:
  • Hints implementation:
  • Structures unions enumerations and bit-fields implementation:
  • Qualifiers implementation:
  • Preprocessing directives implementation:
  • Library functions implementation:
  • Architecture implementation:
  • Locale-specific behavior implementation:


Using the GNU Compiler Collection (GCC)

Node:Case Ranges, Next:Mixed Declarations, Previous:Cast to Union, Up:C Extensions

Case Ranges

You can specify a range of consecutive values in a single case label, like this:

case low ... high:

This has the same effect as the proper number of individual case labels, one for each integer value from low to high, inclusive.

This feature is especially useful for ranges of ASCII character codes:

case 'A' ... 'Z':

Be careful: Write spaces around the ..., for otherwise it may be parsed wrong when you use it with integer values. For example, write this:

case 1 ... 5:

rather than this:

case 1...5:


Using the GNU Compiler Collection (GCC)

Node:Cast to Union, Next:Case Ranges, Previous:Designated Inits, Up:C Extensions

Cast to a Union Type

A cast to union type is similar to other casts, except that the type specified is a union type. You can specify the type either with union tag or with a typedef name. A cast to union is actually a constructor though, not a cast, and hence does not yield an lvalue like normal casts. (See Compound Literals.)

The types that may be cast to the union type are those of the members of the union. Thus, given the following union and variables:

union foo { int i; double d; };
int x;
double y;

both x and y can be cast to type union foo.

Using the cast as the right-hand side of an assignment to a variable of union type is equivalent to storing in a member of the union:

union foo u;
...
u = (union foo) x  ==  u.i = x
u = (union foo) y  ==  u.d = y

You can also use the union cast as a function argument:

void hack (union foo);
...
hack ((union foo) x);


Using the GNU Compiler Collection (GCC)

Node:Character Escapes, Next:Variable Attributes, Previous:Dollar Signs, Up:C Extensions

The Character <ESC> in Constants

You can use the sequence \e in a string or character constant to stand for the ASCII character <ESC>.


Using the GNU Compiler Collection (GCC)

Node:Characters implementation, Next:Integers implementation, Previous:Identifiers implementation, Up:C Implementation

Characters

  • The number of bits in a byte (3.6).
  • The values of the members of the execution character set (5.2.1).
  • The unique value of the member of the execution character set produced for each of the standard alphabetic escape sequences (5.2.2).
  • The value of a char object into which has been stored any character other than a member of the basic execution character set (6.2.5).
  • Which of signed char or unsigned char has the same range, representation, and behavior as "plain" char (6.2.5, 6.3.1.1).
  • The mapping of members of the source character set (in character constants and string literals) to members of the execution character set (6.4.4.4, 5.1.1.2).
  • The value of an integer character constant containing more than one character or containing a character or escape sequence that does not map to a single-byte execution character (6.4.4.4).
  • The value of a wide character constant containing more than one multibyte character, or containing a multibyte character or escape sequence not represented in the extended execution character set (6.4.4.4).
  • The current locale used to convert a wide character constant consisting of a single multibyte character that maps to a member of the extended execution character set into a corresponding wide character code (6.4.4.4).
  • The current locale used to convert a wide string literal into corresponding wide character codes (6.4.5).
  • The value of a string literal containing a multibyte character or escape sequence not represented in the execution character set (6.4.5).


Using the GNU Compiler Collection (GCC)

Node:Clipper Options, Next:H8/300 Options, Previous:DEC Alpha/VMS Options, Up:Submodel Options

Clipper Options

These -m options are defined for the Clipper implementations:

-mc300
Produce code for a C300 Clipper processor. This is the default.
-mc400
Produce code for a C400 Clipper processor, i.e. use floating point registers f8-f15.


Using the GNU Compiler Collection (GCC)

Node:Code Gen Options, Next:Environment Variables, Previous:Submodel Options, Up:Invoking GCC

Options for Code Generation Conventions

These machine-independent options control the interface conventions used in code generation.

Most of them have both positive and negative forms; the negative form of -ffoo would be -fno-foo. In the table below, only one of the forms is listed--the one which is not the default. You can figure out the other form by either removing no- or adding it.

-fexceptions
Enable exception handling. Generates extra code needed to propagate exceptions. For some targets, this implies GCC will generate frame unwind information for all functions, which can produce significant data size overhead, although it does not affect execution. If you do not specify this option, GCC will enable it by default for languages like C++ which normally require exception handling, and disable it for languages like C that do not normally require it. However, you may need to enable this option when compiling C code that needs to interoperate properly with exception handlers written in C++. You may also wish to disable this option if you are compiling older C++ programs that don't use exception handling.
-fnon-call-exceptions
Generate code that allows trapping instructions to throw exceptions. Note that this requires platform-specific runtime support that does not exist everywhere. Moreover, it only allows trapping instructions to throw exceptions, i.e. memory references or floating point instructions. It does not allow exceptions to be thrown from arbitrary signal handlers such as SIGALRM.
-funwind-tables
Similar to -fexceptions, except that it will just generate any needed static data, but will not affect the generated code in any other way. You will normally not enable this option; instead, a language processor that needs this handling would enable it on your behalf.
-fasynchronous-unwind-tables
Generate unwind table in dwarf2 format, if supported by target machine. The table is exact at each instruction boundary, so it can be used for stack unwinding from asynchronous events (such as debugger or garbage collector).
-fpcc-struct-return
Return "short" struct and union values in memory like longer ones, rather than in registers. This convention is less efficient, but it has the advantage of allowing intercallability between GCC-compiled files and files compiled with other compilers.

The precise convention for returning structures in memory depends on the target configuration macros.

Short structures and unions are those whose size and alignment match that of some integer type.

-freg-struct-return
Return struct and union values in registers when possible. This is more efficient for small structures than -fpcc-struct-return.

If you specify neither -fpcc-struct-return nor -freg-struct-return, GCC defaults to whichever convention is standard for the target. If there is no standard convention, GCC defaults to -fpcc-struct-return, except on targets where GCC is the principal compiler. In those cases, we can choose the standard, and we chose the more efficient register return alternative.

-fshort-enums
Allocate to an enum type only as many bytes as it needs for the declared range of possible values. Specifically, the enum type will be equivalent to the smallest integer type which has enough room.
-fshort-double
Use the same size for double as for float.
-fshared-data
Requests that the data and non-const variables of this compilation be shared data rather than private data. The distinction makes sense only on certain operating systems, where shared data is shared between processes running the same program, while private data exists in one copy per process.
-fno-common
In C, allocate even uninitialized global variables in the data section of the object file, rather than generating them as common blocks. This has the effect that if the same variable is declared (without extern) in two different compilations, you will get an error when you link them. The only reason this might be useful is if you wish to verify that the program will work on other systems which always work this way.
-fno-ident
Ignore the #ident directive.
-fno-gnu-linker
Do not output global initializations (such as C++ constructors and destructors) in the form used by the GNU linker (on systems where the GNU linker is the standard method of handling them). Use this option when you want to use a non-GNU linker, which also requires using the collect2 program to make sure the system linker includes constructors and destructors. (collect2 is included in the GCC distribution.) For systems which must use collect2, the compiler driver gcc is configured to do this automatically.
-finhibit-size-directive
Don't output a .size assembler directive, or anything else that would cause trouble if the function is split in the middle, and the two halves are placed at locations far apart in memory. This option is used when compiling crtstuff.c; you should not need to use it for anything else.
-fverbose-asm
Put extra commentary information in the generated assembly code to make it more readable. This option is generally only of use to those who actually need to read the generated assembly code (perhaps while debugging the compiler itself).

-fno-verbose-asm, the default, causes the extra information to be omitted and is useful when comparing two assembler files.

-fvolatile
Consider all memory references through pointers to be volatile.
-fvolatile-global
Consider all memory references to extern and global data items to be volatile. GCC does not consider static data items to be volatile because of this switch.
-fvolatile-static
Consider all memory references to static data to be volatile.
-fpic
Generate position-independent code (PIC) suitable for use in a shared library, if supported for the target machine. Such code accesses all constant addresses through a global offset table (GOT). The dynamic loader resolves the GOT entries when the program starts (the dynamic loader is not part of GCC; it is part of the operating system). If the GOT size for the linked executable exceeds a machine-specific maximum size, you get an error message from the linker indicating that -fpic does not work; in that case, recompile with -fPIC instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k on the m68k and RS/6000. The 386 has no such limit.)

Position-independent code requires special support, and therefore works only on certain machines. For the 386, GCC supports PIC for System V but not for the Sun 386i. Code generated for the IBM RS/6000 is always position-independent.

-fPIC
If supported for the target machine, emit position-independent code, suitable for dynamic linking and avoiding any limit on the size of the global offset table. This option makes a difference on the m68k, m88k, and the Sparc.

Position-independent code requires special support, and therefore works only on certain machines.

-ffixed-reg
Treat the register named reg as a fixed register; generated code should never refer to it (except perhaps as a stack pointer, frame pointer or in some other fixed role).

reg must be the name of a register. The register names accepted are machine-specific and are defined in the REGISTER_NAMES macro in the machine description macro file.

This flag does not have a negative form, because it specifies a three-way choice.

-fcall-used-reg
Treat the register named reg as an allocable register that is clobbered by function calls. It may be allocated for temporaries or variables that do not live across a call. Functions compiled this way will not save and restore the register reg.

It is an error to used this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in the machine's execution model will produce disastrous results.

This flag does not have a negative form, because it specifies a three-way choice.

-fcall-saved-reg
Treat the register named reg as an allocable register saved by functions. It may be allocated even for temporaries or variables that live across a call. Functions compiled this way will save and restore the register reg if they use it.

It is an error to used this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in the machine's execution model will produce disastrous results.

A different sort of disaster will result from the use of this flag for a register in which function values may be returned.

This flag does not have a negative form, because it specifies a three-way choice.

-fpack-struct
Pack all structure members together without holes. Usually you would not want to use this option, since it makes the code suboptimal, and the offsets of structure members won't agree with system libraries.
-finstrument-functions
Generate instrumentation calls for entry and exit to functions. Just after function entry and just before function exit, the following profiling functions will be called with the address of the current function and its call site. (On some platforms, __builtin_return_address does not work beyond the current function, so the call site information may not be available to the profiling functions otherwise.)
void __cyg_profile_func_enter (void *this_fn,
                               void *call_site);
void __cyg_profile_func_exit  (void *this_fn,
                               void *call_site);

The first argument is the address of the start of the current function, which may be looked up exactly in the symbol table.

This instrumentation is also done for functions expanded inline in other functions. The profiling calls will indicate where, conceptually, the inline function is entered and exited. This means that addressable versions of such functions must be available. If all your uses of a function are expanded inline, this may mean an additional expansion of code size. If you use extern inline in your C code, an addressable version of such functions must be provided. (This is normally the case anyways, but if you get lucky and the optimizer always expands the functions inline, you might have gotten away without providing static copies.)

A function may be given the attribute no_instrument_function, in which case this instrumentation will not be done. This can be used, for example, for the profiling functions listed above, high-priority interrupt routines, and any functions from which the profiling functions cannot safely be called (perhaps signal handlers, if the profiling routines generate output or allocate memory).

-fstack-check
Generate code to verify that you do not go beyond the boundary of the stack. You should specify this flag if you are running in an environment with multiple threads, but only rarely need to specify it in a single-threaded environment since stack overflow is automatically detected on nearly all systems if there is only one stack.

Note that this switch does not actually cause checking to be done; the operating system must do that. The switch causes generation of code to ensure that the operating system sees the stack being extended.

-fstack-limit-register=reg
-fstack-limit-symbol=sym
-fno-stack-limit
Generate code to ensure that the stack does not grow beyond a certain value, either the value of a register or the address of a symbol. If the stack would grow beyond the value, a signal is raised. For most targets, the signal is raised before the stack overruns the boundary, so it is possible to catch the signal without taking special precautions.

For instance, if the stack starts at absolute address 0x80000000 and grows downwards, you can use the flags -fstack-limit-symbol=__stack_limit and -Wl,--defsym,__stack_limit=0x7ffe0000 to enforce a stack limit of 128KB. Note that this may only work with the GNU linker.

-fargument-alias
-fargument-noalias
-fargument-noalias-global
Specify the possible relationships among parameters and between parameters and global data.

-fargument-alias specifies that arguments (parameters) may alias each other and may alias global storage.
-fargument-noalias specifies that arguments do not alias each other, but may alias global storage.
-fargument-noalias-global specifies that arguments do not alias each other and do not alias global storage.

Each language will automatically use whatever option is required by the language standard. You should not need to use these options yourself.

-fleading-underscore
This option and its counterpart, -fno-leading-underscore, forcibly change the way C symbols are represented in the object file. One use is to help link with legacy assembly code.

Be warned that you should know what you are doing when invoking this option, and that not all targets provide complete support for it.


Using the GNU Compiler Collection (GCC)

Node:compatibility_alias, Previous:Constant string objects, Up:Objective-C

compatibility_alias

This is a feature of the Objective-C compiler rather than of the runtime, anyway since it is documented nowhere and its existence was forgotten, we are documenting it here.

The keyword @compatibility_alias allows you to define a class name as equivalent to another class name. For example:

@compatibility_alias WOApplication GSWApplication;

tells the compiler that each time it encounters WOApplication as a class name, it should replace it with GSWApplication (that is, WOApplication is just an alias for GSWApplication).

There are some constraints on how this can be used--

  • WOApplication (the alias) must not be an existing class;
  • GSWApplication (the real class) must be an existing class.


Using the GNU Compiler Collection (GCC)

Node:Complex, Next:Hex Floats, Previous:Long Long, Up:C Extensions

Complex Numbers

ISO C99 supports complex floating data types, and as an extension GCC supports them in C89 mode and in C++, and supports complex integer data types which are not part of ISO C99. You can declare complex types using the keyword _Complex. As an extension, the older GNU keyword __complex__ is also supported.

For example, _Complex double x; declares x as a variable whose real part and imaginary part are both of type double. _Complex short int y; declares y to have real and imaginary parts of type short int; this is not likely to be useful, but it shows that the set of complex types is complete.

To write a constant with a complex data type, use the suffix i or j (either one; they are equivalent). For example, 2.5fi has type _Complex float and 3i has type _Complex int. Such a constant always has a pure imaginary value, but you can form any complex value you like by adding one to a real constant. This is a GNU extension; if you have an ISO C99 conforming C library (such as GNU libc), and want to construct complex constants of floating type, you should include <complex.h> and use the macros I or _Complex_I instead.

To extract the real part of a complex-valued expression exp, write __real__ exp. Likewise, use __imag__ to extract the imaginary part. This is a GNU extension; for values of floating type, you should use the ISO C99 functions crealf, creal, creall, cimagf, cimag and cimagl, declared in <complex.h> and also provided as built-in functions by GCC.

The operator ~ performs complex conjugation when used on a value with a complex type. This is a GNU extension; for values of floating type, you should use the ISO C99 functions conjf, conj and conjl, declared in <complex.h> and also provided as built-in functions by GCC.

GCC can allocate complex automatic variables in a noncontiguous fashion; it's even possible for the real part to be in a register while the imaginary part is on the stack (or vice-versa). None of the supported debugging info formats has a way to represent noncontiguous allocation like this, so GCC describes a noncontiguous complex variable as if it were two separate variables of noncomplex type. If the variable's actual name is foo, the two fictitious variables are named foo$real and foo$imag. You can examine and set these two fictitious variables with your debugger.

A future version of GDB will know how to recognize such pairs and treat them as a single variable with a complex type.


Using the GNU Compiler Collection (GCC)

Node:Compound Literals, Next:Designated Inits, Previous:Initializers, Up:C Extensions

Compound Literals

ISO C99 supports compound literals. A compound literal looks like a cast containing an initializer. Its value is an object of the type specified in the cast, containing the elements specified in the initializer; it is an lvalue. As an extension, GCC supports compound literals in C89 mode and in C++.

Usually, the specified type is a structure. Assume that struct foo and structure are declared as shown:

struct foo {int a; char b[2];} structure;

Here is an example of constructing a struct foo with a compound literal:

structure = ((struct foo) {x + y, 'a', 0});

This is equivalent to writing the following:

{
  struct foo temp = {x + y, 'a', 0};
  structure = temp;
}

You can also construct an array. If all the elements of the compound literal are (made up of) simple constant expressions, suitable for use in initializers of objects of static storage duration, then the compound literal can be coerced to a pointer to its first element and used in such an initializer, as shown here:

char **foo = (char *[]) { "x", "y", "z" };

Compound literals for scalar types and union types are is also allowed, but then the compound literal is equivalent to a cast.

As a GNU extension, GCC allows initialization of objects with static storage duration by compound literals (which is not possible in ISO C99, because the initializer is not a constant). It is handled as if the object was initialized only with the bracket enclosed list if compound literal's and object types match. The initializer list of the compound literal must be constant. If the object being initialized has array type of unknown size, the size is determined by compound literal size.

static struct foo x = (struct foo) {1, 'a', 'b'};
static int y[] = (int []) {1, 2, 3};
static int z[] = (int [3]) {1};

The above lines are equivalent to the following:

static struct foo x = {1, 'a', 'b'};
static int y[] = {1, 2, 3};
static int z[] = {1, 0, 0};


Using the GNU Compiler Collection (GCC)

Node:Conditionals, Next:Long Long, Previous:Lvalues, Up:C Extensions

Conditionals with Omitted Operands

The middle operand in a conditional expression may be omitted. Then if the first operand is nonzero, its value is the value of the conditional expression.

Therefore, the expression

x ? : y

has the value of x if that is nonzero; otherwise, the value of y.

This example is perfectly equivalent to

x ? x : y

In this simple case, the ability to omit the middle operand is not especially useful. When it becomes useful is when the first operand does, or may (if it is a macro argument), contain a side effect. Then repeating the operand in the middle would perform the side effect twice. Omitting the middle operand uses the value already computed without the undesirable effects of recomputing it.


Using the GNU Compiler Collection (GCC)

Node:Constant string objects, Next:compatibility_alias, Previous:Garbage Collection, Up:Objective-C

Constant string objects

GNU Objective-C provides constant string objects that are generated directly by the compiler. You declare a constant string object by prefixing a C constant string with the character @:

  id myString = @"this is a constant string object";

The constant string objects are usually instances of the NXConstantString class which is provided by the GNU Objective-C runtime. To get the definition of this class you must include the objc/NXConstStr.h header file.

User defined libraries may want to implement their own constant string class. To be able to support them, the GNU Objective-C compiler provides a new command line options -fconstant-string-class=class-name. The provided class should adhere to a strict structure, the same as NXConstantString's structure:

@interface NXConstantString : Object
{
  char *c_string;
  unsigned int len;
}
@end

User class libraries may choose to inherit the customized constant string class from a different class than Object. There is no requirement in the methods the constant string class has to implement.

When a file is compiled with the -fconstant-string-class option, all the constant string objects will be instances of the class specified as argument to this option. It is possible to have multiple compilation units referring to different constant string classes, neither the compiler nor the linker impose any restrictions in doing this.


Using the GNU Compiler Collection (GCC)

Node:Constraints, Next:Asm Labels, Previous:Extended Asm, Up:C Extensions

Constraints for asm Operands

Here are specific details on what constraint letters you can use with asm operands. Constraints can say whether an operand may be in a register, and which kinds of register; whether the operand can be a memory reference, and which kinds of address; whether the operand may be an immediate constant, and which possible values it may have. Constraints can also require two operands to match.

  • Simple Constraints: Basic use of constraints.
  • Multi-Alternative: When an insn has two alternative constraint-patterns.
  • Modifiers: More precise control over effects of constraints.
  • Machine Constraints: Special constraints for some particular machines.


Using the GNU Compiler Collection (GCC)

Node:Constructing Calls, Next:Naming Types, Previous:Nested Functions, Up:C Extensions

Constructing Function Calls

Using the built-in functions described below, you can record the arguments a function received, and call another function with the same arguments, without knowing the number or types of the arguments.

You can also record the return value of that function call, and later return that value, without knowing what data type the function tried to return (as long as your caller expects that data type).

void * __builtin_apply_args () Built-in Function
This built-in function returns a pointer to data describing how to perform a call with the same arguments as were passed to the current function.

The function saves the arg pointer register, structure value address, and all registers that might be used to pass arguments to a function into a block of memory allocated on the stack. Then it returns the address of that block.

void * __builtin_apply (void (*function)(), void *arguments, size_t size) Built-in Function
This built-in function invokes function with a copy of the parameters described by arguments and size.

The value of arguments should be the value returned by __builtin_apply_args. The argument size specifies the size of the stack argument data, in bytes.

This function returns a pointer to data describing how to return whatever value was returned by function. The data is saved in a block of memory allocated on the stack.

It is not always simple to compute the proper value for size. The value is used by __builtin_apply to compute the amount of data that should be pushed on the stack and copied from the incoming argument area.

void __builtin_return (void *result) Built-in Function
This built-in function returns the value described by result from the containing function. You should specify, for result, a value returned by __builtin_apply.


Using the GNU Compiler Collection (GCC)

Node:Contributing, Next:VMS, Previous:Service, Up:Top

Contributing to GCC Development

If you would like to help pretest GCC releases to assure they work well, our current development sources are available by CVS (see http://gcc.gnu.org/cvs.html). Source and binary snapshots are also available for FTP; see http://gcc.gnu.org/snapshots.html.

If you would like to work on improvements to GCC, please read the advice at these URLs:

http://gcc.gnu.org/contribute.html
http://gcc.gnu.org/contributewhy.html

for information on how to make useful contributions and avoid duplication of effort. Suggested projects are listed at http://gcc.gnu.org/projects/.


Using the GNU Compiler Collection (GCC)

Node:Contributors, Next:Option Index, Previous:GNU Free Documentation License, Up:Top

Contributors to GCC

The GCC project would like to thank its many contributors. Without them the project would not have been nearly as successful as it has been. Any omissions in this list are accidental. Feel free to contact law@redhat.com if you have been left out or some of your contributions are not listed. Please keep this list in alphabetical order.

Some projects operating under the GCC project maintain their own list of contributors, such as the C++ library.

  • Analog Devices helped implement the support for complex data types and iterators.
  • John David Anglin for improvements to libstdc++-v3 and the HP-UX port.
  • James van Artsdalen wrote the code that makes efficient use of the Intel 80387 register stack.
  • Alasdair Baird for various bugfixes.
  • Gerald Baumgartner added the signature extension to the C++ front end.
  • Neil Booth for various work on cpplib.
  • Per Bothner for his direction via the steering committee and various improvements to our infrastructure for supporting new languages. Chill and Java front end implementations. Initial implementations of cpplib, fix-header, config.guess, libio, and past C++ library (libg++) maintainer.
  • Devon Bowen helped port GCC to the Tahoe.
  • Don Bowman for mips-vxworks contributions.
  • Dave Brolley for work on cpplib and Chill.
  • Robert Brown implemented the support for Encore 32000 systems.
  • Christian Bruel for improvements to local store elimination.
  • Herman A.J. ten Brugge for various fixes.
  • Joe Buck for his direction via the steering committee.
  • Craig Burley for leadership of the Fortran effort.
  • Paolo Carlini for his work on libstdc++-v3.
  • John Carr for his alias work, SPARC hacking, infrastructure improvements, previous contributions to the steering committee, loop optimizations, etc.
  • Steve Chamberlain wrote the support for the Hitachi SH and H8 processors and the PicoJava processor.
  • Scott Christley for his Objective-C contributions.
  • Branko Cibej for more warning contributions.
  • Nick Clifton for arm, mcore, fr30, v850, m32r work, --help, and other random hacking.
  • Ralf Corsepius for SH testing and minor bugfixing.
  • Stan Cox for care and feeding of the x86 port and lots of behind the scenes hacking.
  • Alex Crain provided changes for the 3b1.
  • Ian Dall for major improvements to the NS32k port.
  • Dario Dariol contributed the four varieties of sample programs that print a copy of their source.
  • Ulrich Drepper for his work on the C++ runtime libraries, glibc, testing of GCC using glibc, ISO C99 support, CFG dumping support, etc.
  • Richard Earnshaw for his ongoing work with the ARM.
  • David Edelsohn for his direction via the steering committee, ongoing work with the RS6000/PowerPC port, and help cleaning up Haifa loop changes.
  • Paul Eggert for random hacking all over GCC.
  • Mark Elbrecht for various DJGPP improvements.
  • Ben Elliston for his work to move the Objective-C runtime into its own subdirectory and for his work on autoconf.
  • Marc Espie for OpenBSD support.
  • Doug Evans for much of the global optimization framework, arc, m32r, and SPARC work.
  • Fred Fish for BeOS support and Ada fixes.
  • Peter Gerwinski for various bugfixes and the Pascal front end.
  • Kaveh Ghazi for his direction via the steering committee and amazing work to make -W -Wall useful.
  • Judy Goldberg for c++ contributions.
  • Torbjorn Granlund for various fixes and the c-torture testsuite, multiply- and divide-by-constant optimization, improved long long support, improved leaf function register allocation, and his direction via the steering committee.
  • Anthony Green for his -Os contributions and Java front end work.
  • Michael K. Gschwind contributed the port to the PDP-11.
  • Ron Guilmette implemented the protoize and unprotoize tools, the support for Dwarf symbolic debugging information, and much of the support for System V Release 4. He has also worked heavily on the Intel 386 and 860 support.
  • Bruno Haible for improvements in the runtime overhead for EH, new warnings and assorted bugfixes.
  • Andrew Haley for his Java work.
  • Chris Hanson assisted in making GCC work on HP-UX for the 9000 series 300.
  • Michael Hayes for various thankless work he's done trying to get the c30/c40 ports functional. Lots of loop and unroll improvements and fixes.
  • Kate Hedstrom for staking the g77 folks with an initial testsuite.
  • Richard Henderson for his ongoing SPARC, alpha, and ia32 work, loop opts, and generally fixing lots of old problems we've ignored for years, flow rewrite and lots of further stuff, including reviewing tons of patches.
  • Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed the support for the Sony NEWS machine.
  • Manfred Hollstein for his ongoing work to keep the m88k alive, lots of testing an bugfixing, particularly of our configury code.
  • Steve Holmgren for MachTen patches.
  • Jan Hubicka for his x86 port improvements.
  • Christian Iseli for various bugfixes.
  • Kamil Iskra for general m68k hacking.
  • Lee Iverson for random fixes and MIPS testing.
  • Andreas Jaeger for various fixes to the MIPS port
  • Jakub Jelinek for his SPARC work and sibling call optimizations as well as lots of bug fixes and test cases.
  • Janis Johnson for ia64 testing and fixes and for her quality improvement sidetracks.
  • J. Kean Johnston for OpenServer support.
  • Klaus Kaempf for his ongoing work to make alpha-vms a viable target.
  • David Kashtan of SRI adapted GCC to VMS.
  • Geoffrey Keating for his ongoing work to make the PPC work for GNU/Linux and his automatic regression tester.
  • Brendan Kehoe for his ongoing work with g++.
  • Oliver M. Kellogg of Deutsche Aerospace contributed the port to the MIL-STD-1750A.
  • Richard Kenner of the New York University Ultracomputer Research Laboratory wrote the machine descriptions for the AMD 29000, the DEC Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for instruction attributes. He also made changes to better support RISC processors including changes to common subexpression elimination, strength reduction, function calling sequence handling, and condition code support, in addition to generalizing the code for frame pointer elimination and delay slot scheduling. Richard Kenner was also the head maintainer of GCC for several years.
  • Mumit Khan for various contributions to the cygwin and mingw32 ports and maintaining binary releases for Windows hosts.
  • Robin Kirkham for cpu32 support.
  • Mark Klein for PA improvements.
  • Thomas Koenig for various bugfixes.
  • Bruce Korb for the new and improved fixincludes code.
  • Benjamin Kosnik for his g++ work and for leading the libstdc++-v3 effort.
  • Charles LaBrec contributed the support for the Integrated Solutions 68020 system.
  • Jeff Law for his direction via the steering committee, coordinating the entire egcs project and GCC 2.95, rolling out snapshots and releases, handling merges from GCC2, reviewing tons of patches that might have fallen through the cracks else, and random but extensive hacking.
  • Marc Lehmann for his direction via the steering committee and helping with analysis and improvements of x86 performance.
  • Ted Lemon wrote parts of the RTL reader and printer.
  • Kriang Lerdsuwanakij for improvements to demangler and various c++ fixes.
  • Warren Levy major work on libgcj (Java Runtime Library) and random work on the Java front end.
  • Alain Lichnewsky ported GCC to the MIPS CPU.
  • Robert Lipe for OpenServer support, new testsuites, testing, etc.
  • Weiwen Liu for testing and various bugfixes.
  • Dave Love for his ongoing work with the Fortran front end and runtime libraries.
  • Martin von Löwis for internal consistency checking infrastructure, and various C++ improvements including namespace support.
  • H.J. Lu for his previous contributions to the steering committee, many x86 bug reports, prototype patches, and keeping the GNU/Linux ports working.
  • Greg McGary for random fixes and (someday) bounded pointers.
  • Andrew MacLeod for his ongoing work in building a real EH system, various code generation improvements, work on the global optimizer, etc.
  • Vladimir Makarov for hacking some ugly i960 problems, PowerPC hacking improvements to compile-time performance and overall knowledge and direction in the area of instruction scheduling.
  • Bob Manson for his behind the scenes work on dejagnu.
  • Michael Meissner for LRS framework, ia32, m32r, v850, m88k, MIPS, powerpc, haifa, ECOFF debug support, and other assorted hacking.
  • Jason Merrill for his direction via the steering committee and leading the g++ effort.
  • David Miller for his direction via the steering committee, lots of SPARC work, improvements in jump.c and interfacing with the Linux kernel developers.
  • Gary Miller ported GCC to Charles River Data Systems machines.
  • Mark Mitchell for his direction via the steering committee, mountains of C++ work, load/store hoisting out of loops, alias analysis improvements, ISO C restrict support, and serving as release manager for GCC 3.x.
  • Alan Modra for various GNU/Linux bits and testing.
  • Toon Moene for his direction via the steering committee, Fortran maintenance, and his ongoing work to make us make Fortran run fast.
  • Jason Molenda for major help in the care and feeding of all the services on the gcc.gnu.org (formerly egcs.cygnus.com) machine--mail, web services, ftp services, etc etc.
  • Catherine Moore for fixing various ugly problems we have sent her way, including the haifa bug which was killing the Alpha & PowerPC Linux kernels.
  • David Mosberger-Tang for various Alpha improvements.
  • Stephen Moshier contributed the floating point emulator that assists in cross-compilation and permits support for floating point numbers wider than 64 bits and for ISO C99 support.
  • Bill Moyer for his behind the scenes work on various issues.
  • Philippe De Muyter for his work on the m68k port.
  • Joseph S. Myers for his work on the PDP-11 port, format checking and ISO C99 support, and continuous emphasis on (and contributions to) documentation.
  • Nathan Myers for his work on libstdc++-v3.
  • NeXT, Inc. donated the front end that supports the Objective-C language.
  • Hans-Peter Nilsson for the CRIS and MMIX ports, improvements to the search engine setup, various documentation fixes and other small fixes.
  • Geoff Noer for this work on getting cygwin native builds working.
  • David O'Brien for the FreeBSD/alpha, FreeBSD/AMD x86-64, FreeBSD/ARM, FreeBSD/PowerPC, and FreeBSD/SPARC64 ports and related infrastructure improvements.
  • Alexandre Oliva for various build infrastructure improvements, scripts and amazing testing work.
  • Melissa O'Neill for various NeXT fixes.
  • Rainer Orth for random MIPS work, including improvements to our o32 ABI support, improvements to dejagnu's MIPS support, etc.
  • Paul Petersen wrote the machine description for the Alliant FX/8.
  • Alexandre Petit-Bianco for his Java work.
  • Matthias Pfaller for major improvements to the NS32k port.
  • Gerald Pfeifer for his direction via the steering committee, pointing out lots of problems we need to solve, maintenance of the web pages, and taking care of documentation maintenance in general.
  • Ovidiu Predescu for his work on the Objective-C front end and runtime libraries.
  • Ken Raeburn for various improvements to checker, MIPS ports and various cleanups in the compiler.
  • David Reese of Sun Microsystems contributed to the Solaris on PowerPC port.
  • Gabriel Dos Reis for contributions and maintenance of libstdc++-v3, including valarray implementation and limits support.
  • Joern Rennecke for maintaining the sh port, loop, regmove & reload hacking.
  • Loren J. Rittle for improvements to libstdc++-v3 and the FreeBSD port.
  • Craig Rodrigues for processing tons of bug reports.
  • Gavin Romig-Koch for lots of behind the scenes MIPS work.
  • Ken Rose for fixes to our delay slot filling code.
  • Paul Rubin wrote most of the preprocessor.
  • Juha Sarlin for improvements to the H8 code generator.
  • Greg Satz assisted in making GCC work on HP-UX for the 9000 series 300.
  • Peter Schauer wrote the code to allow debugging to work on the Alpha.
  • William Schelter did most of the work on the Intel 80386 support.
  • Bernd Schmidt for various code generation improvements and major work in the reload pass as well a serving as release manager for GCC 2.95.3.
  • Andreas Schwab for his work on the m68k port.
  • Joel Sherrill for his direction via the steering committee, RTEMS contributions and RTEMS testing.
  • Nathan Sidwell for many C++ fixes/improvements.
  • Jeffrey Siegal for helping RMS with the original design of GCC, some code which handles the parse tree and RTL data structures, constant folding and help with the original VAX & m68k ports.
  • Franz Sirl for his ongoing work with making the PPC port stable for linux.
  • Andrey Slepuhin for assorted AIX hacking.
  • Christopher Smith did the port for Convex machines.
  • Randy Smith finished the Sun FPA support.
  • Scott Snyder for various fixes.
  • Richard Stallman, for writing the original gcc and launching the GNU project.
  • Jan Stein of the Chalmers Computer Society provided support for Genix, as well as part of the 32000 machine description.
  • Nigel Stephens for various mips16 related fixes/improvements.
  • Jonathan Stone wrote the machine description for the Pyramid computer.
  • Graham Stott for various infrastructure improvements.
  • Mike Stump for his Elxsi port, g++ contributions over the years and more recently his vxworks contributions
  • Shigeya Suzuki for this fixes for the bsdi platforms.
  • Ian Lance Taylor for his mips16 work, general configury hacking, fixincludes, etc.
  • Holger Teutsch provided the support for the Clipper CPU.
  • Gary Thomas for his ongoing work to make the PPC work for GNU/Linux.
  • Philipp Thomas for random bugfixes throughout the compiler
  • Kresten Krab Thorup wrote the run time support for the Objective-C language.
  • Michael Tiemann for random bugfixes, the first instruction scheduler, initial C++ support, function integration, NS32k, SPARC and M88k machine description work, delay slot scheduling.
  • Teemu Torma for thread safe exception handling support.
  • Leonard Tower wrote parts of the parser, RTL generator, and RTL definitions, and of the VAX machine description.
  • Tom Tromey for internationalization support and his Java work.
  • Lassi Tuura for improvements to config.guess to determine HP processor types.
  • Todd Vierling for contributions for NetBSD ports.
  • Dean Wakerley for converting the install documentation from HTML to texinfo in time for GCC 3.0.
  • Krister Walfridsson for random bugfixes.
  • John Wehle for various improvements for the x86 code generator, related infrastructure improvements to help x86 code generation, value range propagation and other work, WE32k port.
  • Zack Weinberg for major work on cpplib and various other bugfixes.
  • Dale Wiles helped port GCC to the Tahoe.
  • Bob Wilson from Tensilica, Inc. for the Xtensa port.
  • Jim Wilson for his direction via the steering committee, tackling hard problems in various places that nobody else wanted to work on, strength reduction and other loop optimizations.
  • Carlo Wood for various fixes.
  • Tom Wood for work on the m88k port.
  • Masanobu Yuhara of Fujitsu Laboratories implemented the machine description for the Tron architecture (specifically, the Gmicro).
  • Kevin Zachmann helped ported GCC to the Tahoe.

We'd also like to thank the folks who have contributed time and energy in testing GCC:

  • David Billinghurst
  • Horst von Brand
  • Rodney Brown
  • Joe Buck
  • Craig Burley
  • Ulrich Drepper
  • David Edelsohn
  • Yung Shing Gene
  • Kaveh Ghazi
  • Kate Hedstrom
  • Richard Henderson
  • Manfred Hollstein
  • Kamil Iskra
  • Christian Joensson
  • Jeff Law
  • Robert Lipe
  • Damon Love
  • Dave Love
  • H.J. Lu
  • Brad Lucier
  • Mumit Khan
  • Matthias Klose
  • Martin Knoblauch
  • David Miller
  • Toon Moene
  • Matthias Mueller
  • Alexandre Oliva
  • Richard Polton
  • David Rees
  • Loren J. Rittle
  • Peter Schmid
  • David Schuler
  • Vin Shelton
  • Franz Sirl
  • Mike Stump
  • Carlo Wood
  • And many others

And finally we'd like to thank everyone who uses the compiler, submits bug reports and generally reminds us why we're doing this work in the first place.


Using the GNU Compiler Collection (GCC)

Node:Convex Options, Next:AMD29K Options, Previous:SPARC Options, Up:Submodel Options

Convex Options

These -m options are defined for Convex:

-mc1
Generate output for C1. The code will run on any Convex machine. The preprocessor symbol __convex__c1__ is defined.
-mc2
Generate output for C2. Uses instructions not available on C1. Scheduling and other optimizations are chosen for max performance on C2. The preprocessor symbol __convex_c2__ is defined.
-mc32
Generate output for C32xx. Uses instructions not available on C1. Scheduling and other optimizations are chosen for max performance on C32. The preprocessor symbol __convex_c32__ is defined.
-mc34
Generate output for C34xx. Uses instructions not available on C1. Scheduling and other optimizations are chosen for max performance on C34. The preprocessor symbol __convex_c34__ is defined.
-mc38
Generate output for C38xx. Uses instructions not available on C1. Scheduling and other optimizations are chosen for max performance on C38. The preprocessor symbol __convex_c38__ is defined.
-margcount
Generate code which puts an argument count in the word preceding each argument list. This is compatible with regular CC, and a few programs may need the argument count word. GDB and other source-level debuggers do not need it; this info is in the symbol table.
-mnoargcount
Omit the argument count word. This is the default.
-mvolatile-cache
Allow volatile references to be cached. This is the default.
-mvolatile-nocache
Volatile references bypass the data cache, going all the way to memory. This is only needed for multi-processor code that does not use standard synchronization instructions. Making non-volatile references to volatile locations will not necessarily work.
-mlong32
Type long is 32 bits, the same as type int. This is the default.
-mlong64
Type long is 64 bits, the same as type long long. This option is useless, because no library support exists for it.


Using the GNU Compiler Collection (GCC)

Node:Copy Assignment, Previous:Temporaries, Up:C++ Misunderstandings

Implicit Copy-Assignment for Virtual Bases

When a base class is virtual, only one subobject of the base class belongs to each full object. Also, the constructors and destructors are invoked only once, and called from the most-derived class. However, such objects behave unspecified when being assigned. For example:

struct Base{
  char *name;
  Base(char *n) : name(strdup(n)){}
  Base& operator= (const Base& other){
   free (name);
   name = strdup (other.name);
  }
};

struct A:virtual Base{
  int val;
  A():Base("A"){}
};

struct B:virtual Base{
  int bval;
  B():Base("B"){}
};

struct Derived:public A, public B{
  Derived():Base("Derived"){}
};

void func(Derived &d1, Derived &d2)
{
  d1 = d2;
}

The C++ standard specifies that Base::Base is only called once when constructing or copy-constructing a Derived object. It is unspecified whether Base::operator= is called more than once when the implicit copy-assignment for Derived objects is invoked (as it is inside func in the example).

g++ implements the "intuitive" algorithm for copy-assignment: assign all direct bases, then assign all members. In that algorithm, the virtual base subobject can be encountered many times. In the example, copying proceeds in the following order: val, name (via strdup), bval, and name again.

If application code relies on copy-assignment, a user-defined copy-assignment operator removes any uncertainties. With such an operator, the application can define whether and how the virtual base subobject is assigned.


Using the GNU Compiler Collection (GCC)

Node:Copying, Next:GNU Free Documentation License, Previous:GNU Project, Up:Top

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
    NO WARRANTY
  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) year  name of author

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.


Using the GNU Compiler Collection (GCC)

Node:CRIS Options, Next:MMIX Options, Previous:S/390 and zSeries Options, Up:Submodel Options

CRIS Options

These options are defined specifically for the CRIS ports.

-march=architecture-type
-mcpu=architecture-type
Generate code for the specified architecture. The choices for architecture-type are v3, v8 and v10 for respectively ETRAX 4, ETRAX 100, and ETRAX 100 LX. Default is v0 except for cris-axis-linux-gnu, where the default is v10.
-mtune=architecture-type
Tune to architecture-type everything applicable about the generated code, except for the ABI and the set of available instructions. The choices for architecture-type are the same as for -march=architecture-type.
-mmax-stack-frame=n
Warn when the stack frame of a function exceeds n bytes.
-melinux-stacksize=n
Only available with the cris-axis-aout target. Arranges for indications in the program to the kernel loader that the stack of the program should be set to n bytes.
-metrax4
-metrax100
The options -metrax4 and -metrax100 are synonyms for -march=v3 and -march=v8 respectively.
-mpdebug
Enable CRIS-specific verbose debug-related information in the assembly code. This option also has the effect to turn off the #NO_APP formatted-code indicator to the assembler at the beginning of the assembly file.
-mcc-init
Do not use condition-code results from previous instruction; always emit compare and test instructions before use of condition codes.
-mno-side-effects
Do not emit instructions with side-effects in addressing modes other than post-increment.
-mstack-align
-mno-stack-align
-mdata-align
-mno-data-align
-mconst-align
-mno-const-align
These options (no-options) arranges (eliminate arrangements) for the stack-frame, individual data and constants to be aligned for the maximum single data access size for the chosen CPU model. The default is to arrange for 32-bit alignment. ABI details such as structure layout are not affected by these options.
-m32-bit
-m16-bit
-m8-bit
Similar to the stack- data- and const-align options above, these options arrange for stack-frame, writable data and constants to all be 32-bit, 16-bit or 8-bit aligned. The default is 32-bit alignment.
-mno-prologue-epilogue
-mprologue-epilogue
With -mno-prologue-epilogue, the normal function prologue and epilogue that sets up the stack-frame are omitted and no return instructions or return sequences are generated in the code. Use this option only together with visual inspection of the compiled code: no warnings or errors are generated when call-saved registers must be saved, or storage for local variable needs to be allocated.
-mno-gotplt
-mgotplt
With -fpic and -fPIC, don't generate (do generate) instruction sequences that load addresses for functions from the PLT part of the GOT rather than (traditional on other architectures) calls to the PLT. The default is -mgotplt.
-maout
Legacy no-op option only recognized with the cris-axis-aout target.
-melf
Legacy no-op option only recognized with the cris-axis-elf and cris-axis-linux-gnu targets.
-melinux
Only recognized with the cris-axis-aout target, where it selects a GNU/linux-like multilib, include files and instruction set for -march=v8.
-mlinux
Legacy no-op option only recognized with the cris-axis-linux-gnu target.
-sim
This option, recognized for the cris-axis-aout and cris-axis-elf arranges to link with input-output functions from a simulator library. Code, initialized data and zero-initialized data are allocated consecutively.
-sim2
Like -sim, but pass linker options to locate initialized data at 0x40000000 and zero-initialized data at 0x80000000.


Using the GNU Compiler Collection (GCC)

Node:Cross-Compiler Problems, Next:Interoperation, Previous:Actual Bugs, Up:Trouble

Cross-Compiler Problems

You may run into problems with cross compilation on certain machines, for several reasons.

  • Cross compilation can run into trouble for certain machines because some target machines' assemblers require floating point numbers to be written as integer constants in certain contexts.

    The compiler writes these integer constants by examining the floating point value as an integer and printing that integer, because this is simple to write and independent of the details of the floating point representation. But this does not work if the compiler is running on a different machine with an incompatible floating point format, or even a different byte-ordering.

    In addition, correct constant folding of floating point values requires representing them in the target machine's format. (The C standard does not quite require this, but in practice it is the only way to win.)

    It is now possible to overcome these problems by defining macros such as REAL_VALUE_TYPE. But doing so is a substantial amount of work for each target machine. See Cross Compilation and Floating Point.

  • At present, the program mips-tfile which adds debug support to object files on MIPS systems does not work in a cross compile environment.


Using the GNU Compiler Collection (GCC)

Node:D30V Options, Next:S/390 and zSeries Options, Previous:IA-64 Options, Up:Submodel Options

D30V Options

These -m options are defined for D30V implementations:

-mextmem
Link the .text, .data, .bss, .strings, .rodata, .rodata1, .data1 sections into external memory, which starts at location 0x80000000.
-mextmemory
Same as the -mextmem switch.
-monchip
Link the .text section into onchip text memory, which starts at location 0x0. Also link .data, .bss, .strings, .rodata, .rodata1, .data1 sections into onchip data memory, which starts at location 0x20000000.
-mno-asm-optimize
-masm-optimize
Disable (enable) passing -O to the assembler when optimizing. The assembler uses the -O option to automatically parallelize adjacent short instructions where possible.
-mbranch-cost=n
Increase the internal costs of branches to n. Higher costs means that the compiler will issue more instructions to avoid doing a branch. The default is 2.
-mcond-exec=n
Specify the maximum number of conditionally executed instructions that replace a branch. The default is 4.


Using the GNU Compiler Collection (GCC)

Node:Darwin Pragmas, Next:Solaris Pragmas, Previous:ARM Pragmas, Up:Pragmas

Darwin Pragmas

The following pragmas are available for all architectures running the Darwin operating system. These are useful for compatibility with other MacOS compilers.

mark tokens...
This pragma is accepted, but has no effect.
options align=alignment
This pragma sets the alignment of fields in structures. The values of alignment may be mac68k, to emulate m68k alignment, or power, to emulate PowerPC alignment. Uses of this pragma nest properly; to restore the previous setting, use reset for the alignment.
segment tokens...
This pragma is accepted, but has no effect.
unused (var [, var]...)
This pragma declares variables to be possibly unused. GCC will not produce warnings for the listed variables. The effect is similar to that of the unused attribute, except that this pragma may appear anywhere within the variables' scopes.


Using the GNU Compiler Collection (GCC)

Node:Debugging Options, Next:Optimize Options, Previous:Warning Options, Up:Invoking GCC

Options for Debugging Your Program or GCC

GCC has various special options that are used for debugging either your program or GCC:

-g
Produce debugging information in the operating system's native format (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging information.

On most systems that use stabs format, -g enables use of extra debugging information that only GDB can use; this extra information makes debugging work better in GDB but will probably make other debuggers crash or refuse to read the program. If you want to control for certain whether to generate the extra information, use -gstabs+, -gstabs, -gxcoff+, -gxcoff, -gdwarf-1+, -gdwarf-1, or -gvms (see below).

Unlike most other C compilers, GCC allows you to use -g with -O. The shortcuts taken by optimized code may occasionally produce surprising results: some variables you declared may not exist at all; flow of control may briefly move where you did not expect it; some statements may not be executed because they compute constant results or their values were already at hand; some statements may execute in different places because they were moved out of loops.

Nevertheless it proves possible to debug optimized output. This makes it reasonable to use the optimizer for programs that might have bugs.

The following options are useful when GCC is generated with the capability for more than one debugging format.

-ggdb
Produce debugging information for use by GDB. This means to use the most expressive format available (DWARF 2, stabs, or the native format if neither of those are supported), including GDB extensions if at all possible.
-gstabs
Produce debugging information in stabs format (if that is supported), without GDB extensions. This is the format used by DBX on most BSD systems. On MIPS, Alpha and System V Release 4 systems this option produces stabs debugging output which is not understood by DBX or SDB. On System V Release 4 systems this option requires the GNU assembler.
-gstabs+
Produce debugging information in stabs format (if that is supported), using GNU extensions understood only by the GNU debugger (GDB). The use of these extensions is likely to make other debuggers crash or refuse to read the program.
-gcoff
Produce debugging information in COFF format (if that is supported). This is the format used by SDB on most System V systems prior to System V Release 4.
-gxcoff
Produce debugging information in XCOFF format (if that is supported). This is the format used by the DBX debugger on IBM RS/6000 systems.
-gxcoff+
Produce debugging information in XCOFF format (if that is supported), using GNU extensions understood only by the GNU debugger (GDB). The use of these extensions is likely to make other debuggers crash or refuse to read the program, and may cause assemblers other than the GNU assembler (GAS) to fail with an error.
-gdwarf
Produce debugging information in DWARF version 1 format (if that is supported). This is the format used by SDB on most System V Release 4 systems.
-gdwarf+
Produce debugging information in DWARF version 1 format (if that is supported), using GNU extensions understood only by the GNU debugger (GDB). The use of these extensions is likely to make other debuggers crash or refuse to read the program.
-gdwarf-2
Produce debugging information in DWARF version 2 format (if that is supported). This is the format used by DBX on IRIX 6.
-gvms
Produce debugging information in VMS debug format (if that is supported). This is the format used by DEBUG on VMS systems.
-glevel
-ggdblevel
-gstabslevel
-gcofflevel
-gxcofflevel
-gvmslevel
Request debugging information and also use level to specify how much information. The default level is 2.

Level 1 produces minimal information, enough for making backtraces in parts of the program that you don't plan to debug. This includes descriptions of functions and external variables, but no information about local variables and no line numbers.

Level 3 includes extra information, such as all the macro definitions present in the program. Some debuggers support macro expansion when you use -g3.

Note that in order to avoid confusion between DWARF1 debug level 2, and DWARF2, neither -gdwarf nor -gdwarf-2 accept a concatenated debug level. Instead use an additional -glevel option to change the debug level for DWARF1 or DWARF2.

-p
Generate extra code to write profile information suitable for the analysis program prof. You must use this option when compiling the source files you want data about, and you must also use it when linking.
-pg
Generate extra code to write profile information suitable for the analysis program gprof. You must use this option when compiling the source files you want data about, and you must also use it when linking.
-a
Generate extra code to write profile information for basic blocks, which will record the number of times each basic block is executed, the basic block start address, and the function name containing the basic block. If -g is used, the line number and filename of the start of the basic block will also be recorded. If not overridden by the machine description, the default action is to append to the text file bb.out.

This data could be analyzed by a program like tcov. Note, however, that the format of the data is not what tcov expects. Eventually GNU gprof should be extended to process this data.

-Q
Makes the compiler print out each function name as it is compiled, and print some statistics about each pass when it finishes.
-ftime-report
Makes the compiler print some statistics about the time consumed by each pass when it finishes.
-fmem-report
Makes the compiler print some statistics about permanent memory allocation when it finishes.
-fprofile-arcs
Instrument arcs during compilation to generate coverage data or for profile-directed block ordering. During execution the program records how many times each branch is executed and how many times it is taken. When the compiled program exits it saves this data to a file called sourcename.da for each source file.

For profile-directed block ordering, compile the program with -fprofile-arcs plus optimization and code generation options, generate the arc profile information by running the program on a selected workload, and then compile the program again with the same optimization and code generation options plus -fbranch-probabilities (see Options that Control Optimization).

The other use of -fprofile-arcs is for use with gcov, when it is used with the -ftest-coverage option. GCC supports two methods of determining code coverage: the options that support gcov, and options -a and -ax, which write information to text files. The options that support gcov do not need to instrument every arc in the program, so a program compiled with them runs faster than a program compiled with -a, which adds instrumentation code to every basic block in the program. The tradeoff: since gcov does not have execution counts for all branches, it must start with the execution counts for the instrumented branches, and then iterate over the program flow graph until the entire graph has been solved. Hence, gcov runs a little more slowly than a program which uses information from -a and -ax.

With -fprofile-arcs, for each function of your program GCC creates a program flow graph, then finds a spanning tree for the graph. Only arcs that are not on the spanning tree have to be instrumented: the compiler adds code to count the number of times that these arcs are executed. When an arc is the only exit or only entrance to a block, the instrumentation code can be added to the block; otherwise, a new basic block must be created to hold the instrumentation code.

This option makes it possible to estimate branch probabilities and to calculate basic block execution counts. In general, basic block execution counts as provided by -a do not give enough information to estimate all branch probabilities.

-ftest-coverage
Create data files for the gcov code-coverage utility (see gcov: a GCC Test Coverage Program). The data file names begin with the name of your source file:
sourcename.bb
A mapping from basic blocks to line numbers, which gcov uses to associate basic block execution counts with line numbers.
sourcename.bbg
A list of all arcs in the program flow graph. This allows gcov to reconstruct the program flow graph, so that it can compute all basic block and arc execution counts from the information in the sourcename.da file.

Use -ftest-coverage with -fprofile-arcs; the latter option adds instrumentation to the program, which then writes execution counts to another data file:

sourcename.da
Runtime arc execution counts, used in conjunction with the arc information in the file sourcename.bbg.

Coverage data will map better to the source files if -ftest-coverage is used without optimization.

-dletters
Says to make debugging dumps during compilation at times specified by letters. This is used for debugging the compiler. The file names for most of the dumps are made by appending a pass number and a word to the source file name (e.g. foo.c.00.rtl or foo.c.01.sibling). Here are the possible letters for use in letters, and their meanings:
A
Annotate the assembler output with miscellaneous debugging information.
b
Dump after computing branch probabilities, to file.14.bp.
B
Dump after block reordering, to file.29.bbro.
c
Dump after instruction combination, to the file file.16.combine.
C
Dump after the first if conversion, to the file file.17.ce.
d
Dump after delayed branch scheduling, to file.31.dbr.
D
Dump all macro definitions, at the end of preprocessing, in addition to normal output.
e
Dump after SSA optimizations, to file.04.ssa and file.07.ussa.
E
Dump after the second if conversion, to file.26.ce2.
f
Dump after life analysis, to file.15.life.
F
Dump after purging ADDRESSOF codes, to file.09.addressof.
g
Dump after global register allocation, to file.21.greg.
h
Dump after finalization of EH handling code, to file.02.eh.
k
Dump after reg-to-stack conversion, to file.28.stack.
o
Dump after post-reload optimizations, to file.22.postreload.
G
Dump after GCSE, to file.10.gcse.
i
Dump after sibling call optimizations, to file.01.sibling.
j
Dump after the first jump optimization, to file.03.jump.
k
Dump after conversion from registers to stack, to file.32.stack.
l
Dump after local register allocation, to file.20.lreg.
L
Dump after loop optimization, to file.11.loop.
M
Dump after performing the machine dependent reorganisation pass, to file.30.mach.
n
Dump after register renumbering, to file.25.rnreg.
N
Dump after the register move pass, to file.18.regmove.
r
Dump after RTL generation, to file.00.rtl.
R
Dump after the second scheduling pass, to file.27.sched2.
s
Dump after CSE (including the jump optimization that sometimes follows CSE), to file.08.cse.
S
Dump after the first scheduling pass, to file.19.sched.
t
Dump after the second CSE pass (including the jump optimization that sometimes follows CSE), to file.12.cse2.
w
Dump after the second flow pass, to file.23.flow2.
X
Dump after SSA dead code elimination, to file.06.ssadce.
z
Dump after the peephole pass, to file.24.peephole2.
a
Produce all the dumps listed above.
m
Print statistics on memory usage, at the end of the run, to standard error.
p
Annotate the assembler output with a comment indicating which pattern and alternative was used. The length of each instruction is also printed.
P
Dump the RTL in the assembler output as a comment before each instruction. Also turns on -dp annotation.
v
For each of the other indicated dump files (except for file.00.rtl), dump a representation of the control flow graph suitable for viewing with VCG to file.pass.vcg.
x
Just generate RTL for a function instead of compiling it. Usually used with r.
y
Dump debugging information during parsing, to standard error.

-fdump-unnumbered
When doing debugging dumps (see -d option above), suppress instruction numbers and line number note output. This makes it more feasible to use diff on debugging dumps for compiler invocations with different options, in particular with and without -g.
-fdump-translation-unit (C and C++ only)
-fdump-translation-unit-options (C and C++ only)
Dump a representation of the tree structure for the entire translation unit to a file. The file name is made by appending .tu to the source file name. If the -options form is used, options controls the details of the dump as described for the -fdump-tree options.
-fdump-class-hierarchy (C++ only)
-fdump-class-hierarchy-options (C++ only)
Dump a representation of each class's hierarchy and virtual function table layout to a file. The file name is made by appending .class to the source file name. If the -options form is used, options controls the details of the dump as described for the -fdump-tree options.
-fdump-tree-switch (C++ only)
-fdump-tree-switch-options (C++ only)
Control the dumping at various stages of processing the intermediate language tree to a file. The file name is generated by appending a switch specific suffix to the source file name. If the -options form is used, options is a list of - separated options that control the details of the dump. Not all options are applicable to all dumps, those which are not meaningful will be ignored. The following options are available
address
Print the address of each node. Usually this is not meaningful as it changes according to the environment and source file. Its primary use is for tying up a dump file with a debug environment.
slim
Inhibit dumping of members of a scope or body of a function merely because that scope has been reached. Only dump such items when they are directly reachable by some other path.
all
Turn on all options.

The following tree dumps are possible:

original
Dump before any tree based optimization, to file.original.
optimized
Dump after all tree based optimization, to file.optimized.
inlined
Dump after function inlining, to file.inlined.

-fpretend-float
When running a cross-compiler, pretend that the target machine uses the same floating point format as the host machine. This causes incorrect output of the actual floating constants, but the actual instruction sequence will probably be the same as GCC would make when running on the target machine.
-save-temps
Store the usual "temporary" intermediate files permanently; place them in the current directory and name them based on the source file. Thus, compiling foo.c with -c -save-temps would produce files foo.i and foo.s, as well as foo.o. This creates a preprocessed foo.i output file even though the compiler now normally uses an integrated preprocessor.
-time
Report the CPU time taken by each subprocess in the compilation sequence. For C source files, this is the compiler proper and assembler (plus the linker if linking is done). The output looks like this:
# cc1 0.12 0.01
# as 0.00 0.01

The first number on each line is the "user time," that is time spent executing the program itself. The second number is "system time," time spent executing operating system routines on behalf of the program. Both numbers are in seconds.

-print-file-name=library
Print the full absolute name of the library file library that would be used when linking--and don't do anything else. With this option, GCC does not compile or link anything; it just prints the file name.
-print-multi-directory
Print the directory name corresponding to the multilib selected by any other switches present in the command line. This directory is supposed to exist in GCC_EXEC_PREFIX.
-print-multi-lib
Print the mapping from multilib directory names to compiler switches that enable them. The directory name is separated from the switches by ;, and each switch starts with an @ instead of the -, without spaces between multiple switches. This is supposed to ease shell-processing.
-print-prog-name=program
Like -print-file-name, but searches for a program such as cpp.
-print-libgcc-file-name
Same as -print-file-name=libgcc.a.

This is useful when you use -nostdlib or -nodefaultlibs but you do want to link with libgcc.a. You can do

gcc -nostdlib files... `gcc -print-libgcc-file-name`

-print-search-dirs
Print the name of the configured installation directory and a list of program and library directories gcc will search--and don't do anything else.

This is useful when gcc prints the error message installation problem, cannot exec cpp0: No such file or directory. To resolve this you either need to put cpp0 and the other compiler components where gcc expects to find them, or you can set the environment variable GCC_EXEC_PREFIX to the directory where you installed them. Don't forget the trailing '/'. See Environment Variables.

-dumpmachine
Print the compiler's target machine (for example, i686-pc-linux-gnu)--and don't do anything else.
-dumpversion
Print the compiler version (for example, 3.0)--and don't do anything else.
-dumpspecs
Print the compiler's built-in specs--and don't do anything else. (This is used when GCC itself is being built.) See Spec Files.


Using the GNU Compiler Collection (GCC)

Node:DEC Alpha Options, Next:DEC Alpha/VMS Options, Previous:Intel 960 Options, Up:Submodel Options

DEC Alpha Options

These -m options are defined for the DEC Alpha implementations:

-mno-soft-float
-msoft-float
Use (do not use) the hardware floating-point instructions for floating-point operations. When -msoft-float is specified, functions in libgcc.a will be used to perform floating-point operations. Unless they are replaced by routines that emulate the floating-point operations, or compiled in such a way as to call such emulations routines, these routines will issue floating-point operations. If you are compiling for an Alpha without floating-point operations, you must ensure that the library is built so as not to call them.

Note that Alpha implementations without floating-point operations are required to have floating-point registers.

-mfp-reg
-mno-fp-regs
Generate code that uses (does not use) the floating-point register set. -mno-fp-regs implies -msoft-float. If the floating-point register set is not used, floating point operands are passed in integer registers as if they were integers and floating-point results are passed in $0 instead of $f0. This is a non-standard calling sequence, so any function with a floating-point argument or return value called by code compiled with -mno-fp-regs must also be compiled with that option.

A typical use of this option is building a kernel that does not use, and hence need not save and restore, any floating-point registers.

-mieee
The Alpha architecture implements floating-point hardware optimized for maximum performance. It is mostly compliant with the IEEE floating point standard. However, for full compliance, software assistance is required. This option generates code fully IEEE compliant code except that the inexact-flag is not maintained (see below). If this option is turned on, the preprocessor macro _IEEE_FP is defined during compilation. The resulting code is less efficient but is able to correctly support denormalized numbers and exceptional IEEE values such as not-a-number and plus/minus infinity. Other Alpha compilers call this option -ieee_with_no_inexact.
-mieee-with-inexact
This is like -mieee except the generated code also maintains the IEEE inexact-flag. Turning on this option causes the generated code to implement fully-compliant IEEE math. In addition to _IEEE_FP, _IEEE_FP_EXACT is defined as a preprocessor macro. On some Alpha implementations the resulting code may execute significantly slower than the code generated by default. Since there is very little code that depends on the inexact-flag, you should normally not specify this option. Other Alpha compilers call this option -ieee_with_inexact.
-mfp-trap-mode=trap-mode
This option controls what floating-point related traps are enabled. Other Alpha compilers call this option -fptm trap-mode. The trap mode can be set to one of four values:
n
This is the default (normal) setting. The only traps that are enabled are the ones that cannot be disabled in software (e.g., division by zero trap).
u
In addition to the traps enabled by n, underflow traps are enabled as well.
su
Like su, but the instructions are marked to be safe for software completion (see Alpha architecture manual for details).
sui
Like su, but inexact traps are enabled as well.

-mfp-rounding-mode=rounding-mode
Selects the IEEE rounding mode. Other Alpha compilers call this option -fprm rounding-mode. The rounding-mode can be one of:
n
Normal IEEE rounding mode. Floating point numbers are rounded towards the nearest machine number or towards the even machine number in case of a tie.
m
Round towards minus infinity.
c
Chopped rounding mode. Floating point numbers are rounded towards zero.
d
Dynamic rounding mode. A field in the floating point control register (fpcr, see Alpha architecture reference manual) controls the rounding mode in effect. The C library initializes this register for rounding towards plus infinity. Thus, unless your program modifies the fpcr, d corresponds to round towards plus infinity.

-mtrap-precision=trap-precision
In the Alpha architecture, floating point traps are imprecise. This means without software assistance it is impossible to recover from a floating trap and program execution normally needs to be terminated. GCC can generate code that can assist operating system trap handlers in determining the exact location that caused a floating point trap. Depending on the requirements of an application, different levels of precisions can be selected:
p
Program precision. This option is the default and means a trap handler can only identify which program caused a floating point exception.
f
Function precision. The trap handler can determine the function that caused a floating point exception.
i
Instruction precision. The trap handler can determine the exact instruction that caused a floating point exception.

Other Alpha compilers provide the equivalent options called -scope_safe and -resumption_safe.

-mieee-conformant
This option marks the generated code as IEEE conformant. You must not use this option unless you also specify -mtrap-precision=i and either -mfp-trap-mode=su or -mfp-trap-mode=sui. Its only effect is to emit the line .eflag 48 in the function prologue of the generated assembly file. Under DEC Unix, this has the effect that IEEE-conformant math library routines will be linked in.
-mbuild-constants
Normally GCC examines a 32- or 64-bit integer constant to see if it can construct it from smaller constants in two or three instructions. If it cannot, it will output the constant as a literal and generate code to load it from the data segment at runtime.

Use this option to require GCC to construct all integer constants using code, even if it takes more instructions (the maximum is six).

You would typically use this option to build a shared library dynamic loader. Itself a shared library, it must relocate itself in memory before it can find the variables and constants in its own data segment.

-malpha-as
-mgas
Select whether to generate code to be assembled by the vendor-supplied assembler (-malpha-as) or by the GNU assembler -mgas.
-mbwx
-mno-bwx
-mcix
-mno-cix
-mfix
-mno-fix
-mmax
-mno-max
Indicate whether GCC should generate code to use the optional BWX, CIX, FIX and MAX instruction sets. The default is to use the instruction sets supported by the CPU type specified via -mcpu= option or that of the CPU on which GCC was built if none was specified.
-mfloat-vax
-mfloat-ieee
Generate code that uses (does not use) VAX F and G floating point arithmetic instead of IEEE single and double precision.
-mexplicit-relocs
-mno-explicit-relocs
Older Alpha assemblers provided no way to generate symbol relocations except via assembler macros. Use of these macros does not allow optimial instruction scheduling. GNU binutils as of version 2.12 supports a new syntax that allows the compiler to explicitly mark which relocations should apply to which instructions. This option is mostly useful for debugging, as GCC detects the capabilities of the assembler when it is built and sets the default accordingly.
-msmall-data
-mlarge-data
When -mexplicit-relocs is in effect, static data is accessed via gp-relative relocations. When -msmall-data is used, objects 8 bytes long or smaller are placed in a small data area (the .sdata and .sbss sections) and are accessed via 16-bit relocations off of the $gp register. This limits the size of the small data area to 64KB, but allows the variables to be directly accessed via a single instruction.

The default is -mlarge-data. With this option the data area is limited to just below 2GB. Programs that require more than 2GB of data must use malloc or mmap to allocate the data in the heap instead of in the program's data segment.

When generating code for shared libraries, -fpic implies -msmall-data and -fPIC implies -mlarge-data.

-mcpu=cpu_type
Set the instruction set and instruction scheduling parameters for machine type cpu_type. You can specify either the EV style name or the corresponding chip number. GCC supports scheduling parameters for the EV4, EV5 and EV6 family of processors and will choose the default values for the instruction set from the processor you specify. If you do not specify a processor type, GCC will default to the processor on which the compiler was built.

Supported values for cpu_type are

ev4
ev45
21064
Schedules as an EV4 and has no instruction set extensions.
ev5
21164
Schedules as an EV5 and has no instruction set extensions.
ev56
21164a
Schedules as an EV5 and supports the BWX extension.
pca56
21164pc
21164PC
Schedules as an EV5 and supports the BWX and MAX extensions.
ev6
21264
Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
ev67
21264a
Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.

-mtune=cpu_type
Set only the instruction scheduling parameters for machine type cpu_type. The instruction set is not changed.
-mmemory-latency=time
Sets the latency the scheduler should assume for typical memory references as seen by the application. This number is highly dependent on the memory access patterns used by the application and the size of the external cache on the machine.

Valid options for time are

number
A decimal number representing clock cycles.
L1
L2
L3
main
The compiler contains estimates of the number of clock cycles for "typical" EV4 & EV5 hardware for the Level 1, 2 & 3 caches (also called Dcache, Scache, and Bcache), as well as to main memory. Note that L3 is only valid for EV5.


Using the GNU Compiler Collection (GCC)

Node:DEC Alpha/VMS Options, Next:Clipper Options, Previous:DEC Alpha Options, Up:Submodel Options

DEC Alpha/VMS Options

These -m options are defined for the DEC Alpha/VMS implementations:

-mvms-return-codes
Return VMS condition codes from main. The default is to return POSIX style condition (e.g. error) codes.


Using the GNU Compiler Collection (GCC)

Node:Deprecated Features, Next:Backwards Compatibility, Previous:Java Exceptions, Up:C++ Extensions

Deprecated Features

In the past, the GNU C++ compiler was extended to experiment with new features, at a time when the C++ language was still evolving. Now that the C++ standard is complete, some of those features are superseded by superior alternatives. Using the old features might cause a warning in some cases that the feature will be dropped in the future. In other cases, the feature might be gone already.

While the list below is not exhaustive, it documents some of the options that are now deprecated:

-fexternal-templates
-falt-external-templates
These are two of the many ways for g++ to implement template instantiation. See Template Instantiation. The C++ standard clearly defines how template definitions have to be organized across implementation units. g++ has an implicit instantiation mechanism that should work just fine for standard-conforming code.
-fstrict-prototype
-fno-strict-prototype
Previously it was possible to use an empty prototype parameter list to indicate an unspecified number of parameters (like C), rather than no parameters, as C++ demands. This feature has been removed, except where it is required for backwards compatibility See Backwards Compatibility.

The named return value extension has been deprecated, and is now removed from g++.

The use of initializer lists with new expressions has been deprecated, and is now removed from g++.

Floating and complex non-type template parameters have been deprecated, and are now removed from g++.

The implicit typename extension has been deprecated and will be removed from g++ at some point. In some cases g++ determines that a dependant type such as TPL<T>::X is a type without needing a typename keyword, contrary to the standard.


Using the GNU Compiler Collection (GCC)

Node:Designated Inits, Next:Cast to Union, Previous:Compound Literals, Up:C Extensions

Designated Initializers

Standard C89 requires the elements of an initializer to appear in a fixed order, the same as the order of the elements in the array or structure being initialized.

In ISO C99 you can give the elements in any order, specifying the array indices or structure field names they apply to, and GNU C allows this as an extension in C89 mode as well. This extension is not implemented in GNU C++.

To specify an array index, write [index] = before the element value. For example,

int a[6] = { [4] = 29, [2] = 15 };

is equivalent to

int a[6] = { 0, 0, 15, 0, 29, 0 };

The index values must be constant expressions, even if the array being initialized is automatic.

An alternative syntax for this which has been obsolete since GCC 2.5 but GCC still accepts is to write [index] before the element value, with no =.

To initialize a range of elements to the same value, write [first ... last] = value. This is a GNU extension. For example,

int widths[] = { [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 };

If the value in it has side-effects, the side-effects will happen only once, not for each initialized field by the range initializer.

Note that the length of the array is the highest value specified plus one.

In a structure initializer, specify the name of a field to initialize with .fieldname = before the element value. For example, given the following structure,

struct point { int x, y; };

the following initialization

struct point p = { .y = yvalue, .x = xvalue };

is equivalent to

struct point p = { xvalue, yvalue };

Another syntax which has the same meaning, obsolete since GCC 2.5, is fieldname:, as shown here:

struct point p = { y: yvalue, x: xvalue };

The [index] or .fieldname is known as a designator. You can also use a designator (or the obsolete colon syntax) when initializing a union, to specify which element of the union should be used. For example,

union foo { int i; double d; };

union foo f = { .d = 4 };

will convert 4 to a double to store it in the union using the second element. By contrast, casting 4 to type union foo would store it into the union as the integer i, since it is an integer. (See Cast to Union.)

You can combine this technique of naming elements with ordinary C initialization of successive elements. Each initializer element that does not have a designator applies to the next consecutive element of the array or structure. For example,

int a[6] = { [1] = v1, v2, [4] = v4 };

is equivalent to

int a[6] = { 0, v1, v2, 0, v4, 0 };

Labeling the elements of an array initializer is especially useful when the indices are characters or belong to an enum type. For example:

int whitespace[256]
  = { [' '] = 1, ['\t'] = 1, ['\h'] = 1,
      ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 };

You can also write a series of .fieldname and [index] designators before an = to specify a nested subobject to initialize; the list is taken relative to the subobject corresponding to the closest surrounding brace pair. For example, with the struct point declaration above:

struct point ptarray[10] = { [2].y = yv2, [2].x = xv2, [0].x = xv0 };

If the same field is initialized multiple times, it will have value from the last initialization. If any such overridden initialization has side-effect, it is unspecified whether the side-effect happens or not. Currently, gcc will discard them and issue a warning.


Using the GNU Compiler Collection (GCC)

Node:Directory Options, Next:Spec Files, Previous:Link Options, Up:Invoking GCC

Options for Directory Search

These options specify directories to search for header files, for libraries and for parts of the compiler:

-Idir
Add the directory dir to the head of the list of directories to be searched for header files. This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories. However, you should not use this option to add directories that contain vendor-supplied system header files (use -isystem for that). If you use more than one -I option, the directories are scanned in left-to-right order; the standard system directories come after.

If a standard system include directory, or a directory specified with -isystem, is also specified with -I, it will be searched only in the position requested by -I. Also, it will not be considered a system include directory. If that directory really does contain system headers, there is a good chance that they will break. For instance, if GCC's installation procedure edited the headers in /usr/include to fix bugs, -I/usr/include will cause the original, buggy headers to be found instead of the corrected ones. GCC will issue a warning when a system include directory is hidden in this way.

-I-
Any directories you specify with -I options before the -I- option are searched only for the case of #include "file"; they are not searched for #include <file>.

If additional directories are specified with -I options after the -I-, these directories are searched for all #include directives. (Ordinarily all -I directories are used this way.)

In addition, the -I- option inhibits the use of the current directory (where the current input file came from) as the first search directory for #include "file". There is no way to override this effect of -I-. With -I. you can specify searching the directory which was current when the compiler was invoked. That is not exactly the same as what the preprocessor does by default, but it is often satisfactory.

-I- does not inhibit the use of the standard system directories for header files. Thus, -I- and -nostdinc are independent.

-Ldir
Add directory dir to the list of directories to be searched for -l.
-Bprefix
This option specifies where to find the executables, libraries, include files, and data files of the compiler itself.

The compiler driver program runs one or more of the subprograms cpp, cc1, as and ld. It tries prefix as a prefix for each program it tries to run, both with and without machine/version/ (see Target Options).

For each subprogram to be run, the compiler driver first tries the -B prefix, if any. If that name is not found, or if -B was not specified, the driver tries two standard prefixes, which are /usr/lib/gcc/ and /usr/local/lib/gcc-lib/. If neither of those results in a file name that is found, the unmodified program name is searched for using the directories specified in your PATH environment variable.

The compiler will check to see if the path provided by the -B refers to a directory, and if necessary it will add a directory separator character at the end of the path.

-B prefixes that effectively specify directory names also apply to libraries in the linker, because the compiler translates these options into -L options for the linker. They also apply to includes files in the preprocessor, because the compiler translates these options into -isystem options for the preprocessor. In this case, the compiler appends include to the prefix.

The run-time support file libgcc.a can also be searched for using the -B prefix, if needed. If it is not found there, the two standard prefixes above are tried, and that is all. The file is left out of the link if it is not found by those means.

Another way to specify a prefix much like the -B prefix is to use the environment variable GCC_EXEC_PREFIX. See Environment Variables.

As a special kludge, if the path provided by -B is [dir/]stageN/, where N is a number in the range 0 to 9, then it will be replaced by [dir/]include. This is to help with boot-strapping the compiler.

-specs=file
Process file after the compiler reads in the standard specs file, in order to override the defaults that the gcc driver program uses when determining what switches to pass to cc1, cc1plus, as, ld, etc. More than one -specs=file can be specified on the command line, and they are processed in order, from left to right.


Using the GNU Compiler Collection (GCC)

Node:Disappointments, Next:C++ Misunderstandings, Previous:Standard Libraries, Up:Trouble

Disappointments and Misunderstandings

These problems are perhaps regrettable, but we don't know any practical way around them.

  • Certain local variables aren't recognized by debuggers when you compile with optimization.

    This occurs because sometimes GCC optimizes the variable out of existence. There is no way to tell the debugger how to compute the value such a variable "would have had", and it is not clear that would be desirable anyway. So GCC simply does not mention the eliminated variable when it writes debugging information.

    You have to expect a certain amount of disagreement between the executable and your source code, when you use optimization.

  • Users often think it is a bug when GCC reports an error for code like this:
    int foo (struct mumble *);

struct mumble { ... };

int foo (struct mumble *x)
{ ... }

    This code really is erroneous, because the scope of struct mumble in the prototype is limited to the argument list containing it. It does not refer to the struct mumble defined with file scope immediately below--they are two unrelated types with similar names in different scopes.

    But in the definition of foo, the file-scope type is used because that is available to be inherited. Thus, the definition and the prototype do not match, and you get an error.

    This behavior may seem silly, but it's what the ISO standard specifies. It is easy enough for you to make your code work by moving the definition of struct mumble above the prototype. It's not worth being incompatible with ISO C just to avoid an error for the example shown above.

  • Accesses to bit-fields even in volatile objects works by accessing larger objects, such as a byte or a word. You cannot rely on what size of object is accessed in order to read or write the bit-field; it may even vary for a given bit-field according to the precise usage.

    If you care about controlling the amount of memory that is accessed, use volatile but do not use bit-fields.

  • GCC comes with shell scripts to fix certain known problems in system header files. They install corrected copies of various header files in a special directory where only GCC will normally look for them. The scripts adapt to various systems by searching all the system header files for the problem cases that we know about.

    If new system header files are installed, nothing automatically arranges to update the corrected header files. You will have to reinstall GCC to fix the new header files. More specifically, go to the build directory and delete the files stmp-fixinc and stmp-headers, and the subdirectory include; then do make install again.

  • On 68000 and x86 systems, for instance, you can get paradoxical results if you test the precise values of floating point numbers. For example, you can find that a floating point value which is not a NaN is not equal to itself. This results from the fact that the floating point registers hold a few more bits of precision than fit in a double in memory. Compiled code moves values between memory and floating point registers at its convenience, and moving them into memory truncates them.

    You can partially avoid this problem by using the -ffloat-store option (see Optimize Options).

  • On the MIPS, variable argument functions using varargs.h cannot have a floating point value for the first argument. The reason for this is that in the absence of a prototype in scope, if the first argument is a floating point, it is passed in a floating point register, rather than an integer register.

    If the code is rewritten to use the ISO standard stdarg.h method of variable arguments, and the prototype is in scope at the time of the call, everything will work fine.

  • On the H8/300 and H8/300H, variable argument functions must be implemented using the ISO standard stdarg.h method of variable arguments. Furthermore, calls to functions using stdarg.h variable arguments must have a prototype for the called function in scope at the time of the call.
  • On AIX and other platforms without weak symbol support, templates need to be instantiated explicitly and symbols for static members of templates will not be generated.


Using the GNU Compiler Collection (GCC)

Node:Dollar Signs, Next:Character Escapes, Previous:C++ Comments, Up:C Extensions

Dollar Signs in Identifier Names

In GNU C, you may normally use dollar signs in identifier names. This is because many traditional C implementations allow such identifiers. However, dollar signs in identifiers are not supported on a few target machines, typically because the target assembler does not allow them.


Using the GNU Compiler Collection (GCC)

Node:Environment implementation, Next:Identifiers implementation, Previous:Translation implementation, Up:C Implementation

Environment

The behavior of these points are dependent on the implementation of the C library, and are not defined by GCC itself.


Using the GNU Compiler Collection (GCC)

Node:Environment Variables, Next:Running Protoize, Previous:Code Gen Options, Up:Invoking GCC

Environment Variables Affecting GCC

This section describes several environment variables that affect how GCC operates. Some of them work by specifying directories or prefixes to use when searching for various kinds of files. Some are used to specify other aspects of the compilation environment.

Note that you can also specify places to search using options such as -B, -I and -L (see Directory Options). These take precedence over places specified using environment variables, which in turn take precedence over those specified by the configuration of GCC. See Controlling the Compilation Driver gcc.

LANG
LC_CTYPE
LC_MESSAGES
LC_ALL
These environment variables control the way that GCC uses localization information that allow GCC to work with different national conventions. GCC inspects the locale categories LC_CTYPE and LC_MESSAGES if it has been configured to do so. These locale categories can be set to any value supported by your installation. A typical value is en_UK for English in the United Kingdom.

The LC_CTYPE environment variable specifies character classification. GCC uses it to determine the character boundaries in a string; this is needed for some multibyte encodings that contain quote and escape characters that would otherwise be interpreted as a string end or escape.

The LC_MESSAGES environment variable specifies the language to use in diagnostic messages.

If the LC_ALL environment variable is set, it overrides the value of LC_CTYPE and LC_MESSAGES; otherwise, LC_CTYPE and LC_MESSAGES default to the value of the LANG environment variable. If none of these variables are set, GCC defaults to traditional C English behavior.

TMPDIR
If TMPDIR is set, it specifies the directory to use for temporary files. GCC uses temporary files to hold the output of one stage of compilation which is to be used as input to the next stage: for example, the output of the preprocessor, which is the input to the compiler proper.
GCC_EXEC_PREFIX
If GCC_EXEC_PREFIX is set, it specifies a prefix to use in the names of the subprograms executed by the compiler. No slash is added when this prefix is combined with the name of a subprogram, but you can specify a prefix that ends with a slash if you wish.

If GCC_EXEC_PREFIX is not set, GCC will attempt to figure out an appropriate prefix to use based on the pathname it was invoked with.

If GCC cannot find the subprogram using the specified prefix, it tries looking in the usual places for the subprogram.

The default value of GCC_EXEC_PREFIX is prefix/lib/gcc-lib/ where prefix is the value of prefix when you ran the configure script.

Other prefixes specified with -B take precedence over this prefix.

This prefix is also used for finding files such as crt0.o that are used for linking.

In addition, the prefix is used in an unusual way in finding the directories to search for header files. For each of the standard directories whose name normally begins with /usr/local/lib/gcc-lib (more precisely, with the value of GCC_INCLUDE_DIR), GCC tries replacing that beginning with the specified prefix to produce an alternate directory name. Thus, with -Bfoo/, GCC will search foo/bar where it would normally search /usr/local/lib/bar. These alternate directories are searched first; the standard directories come next.

COMPILER_PATH
The value of COMPILER_PATH is a colon-separated list of directories, much like PATH. GCC tries the directories thus specified when searching for subprograms, if it can't find the subprograms using GCC_EXEC_PREFIX.
LIBRARY_PATH
The value of LIBRARY_PATH is a colon-separated list of directories, much like PATH. When configured as a native compiler, GCC tries the directories thus specified when searching for special linker files, if it can't find them using GCC_EXEC_PREFIX. Linking using GCC also uses these directories when searching for ordinary libraries for the -l option (but directories specified with -L come first).
LANG
This variable is used to pass locale information to the compiler. One way in which this information is used is to determine the character set to be used when character literals, string literals and comments are parsed in C and C++. When the compiler is configured to allow multibyte characters, the following values for LANG are recognized:
C-JIS
Recognize JIS characters.
C-SJIS
Recognize SJIS characters.
C-EUCJP
Recognize EUCJP characters.

If LANG is not defined, or if it has some other value, then the compiler will use mblen and mbtowc as defined by the default locale to recognize and translate multibyte characters.

Some additional environments variables affect the behavior of the preprocessor.

CPATH
C_INCLUDE_PATH
CPLUS_INCLUDE_PATH
OBJC_INCLUDE_PATH
Each variable's value is a list of directories separated by a special character, much like PATH, in which to look for header files. The special character, PATH_SEPARATOR, is target-dependent and determined at GCC build time. For Windows-based targets it is a semicolon, and for almost all other targets it is a colon.

CPATH specifies a list of directories to be searched as if specified with -I, but after any paths given with -I options on the command line. The environment variable is used regardless of which language is being preprocessed.

The remaining environment variables apply only when preprocessing the particular language indicated. Each specifies a list of directories to be searched as if specified with -isystem, but after any paths given with -isystem options on the command line.

DEPENDENCIES_OUTPUT
If this variable is set, its value specifies how to output dependencies for Make based on the non-system header files processed by the compiler. System header files are ignored in the dependency output.

The value of DEPENDENCIES_OUTPUT can be just a file name, in which case the Make rules are written to that file, guessing the target name from the source file name. Or the value can have the form file target, in which case the rules are written to file file using target as the target name.

In other words, this environment variable is equivalent to combining the options -MM and -MF (see Preprocessor Options), with an optional -MT switch too.

SUNPRO_DEPENDENCIES
This variable is the same as the environment variable DEPENDENCIES_OUTPUT (see DEPENDENCIES_OUTPUT), except that system header files are not ignored, so it implies -M rather than -MM. See Preprocessor Options.


Using the GNU Compiler Collection (GCC)

Node:Escaped Newlines, Next:Multi-line Strings, Previous:Variadic Macros, Up:C Extensions

Slightly Looser Rules for Escaped Newlines

Recently, the non-traditional preprocessor has relaxed its treatment of escaped newlines. Previously, the newline had to immediately follow a backslash. The current implementation allows whitespace in the form of spaces, horizontal and vertical tabs, and form feeds between the backslash and the subsequent newline. The preprocessor issues a warning, but treats it as a valid escaped newline and combines the two lines to form a single logical line. This works within comments and tokens, including multi-line strings, as well as between tokens. Comments are not treated as whitespace for the purposes of this relaxation, since they have not yet been replaced with spaces.


Using the GNU Compiler Collection (GCC)

Node:Executing code before main, Next:Type encoding, Previous:Objective-C, Up:Objective-C

+load: Executing code before main

The GNU Objective-C runtime provides a way that allows you to execute code before the execution of the program enters the main function. The code is executed on a per-class and a per-category basis, through a special class method +load.

This facility is very useful if you want to initialize global variables which can be accessed by the program directly, without sending a message to the class first. The usual way to initialize global variables, in the +initialize method, might not be useful because +initialize is only called when the first message is sent to a class object, which in some cases could be too late.

Suppose for example you have a FileStream class that declares Stdin, Stdout and Stderr as global variables, like below:

FileStream *Stdin = nil;
FileStream *Stdout = nil;
FileStream *Stderr = nil;

@implementation FileStream

+ (void)initialize
{
    Stdin = [[FileStream new] initWithFd:0];
    Stdout = [[FileStream new] initWithFd:1];
    Stderr = [[FileStream new] initWithFd:2];
}

/* Other methods here */
@end

In this example, the initialization of Stdin, Stdout and Stderr in +initialize occurs too late. The programmer can send a message to one of these objects before the variables are actually initialized, thus sending messages to the nil object. The +initialize method which actually initializes the global variables is not invoked until the first message is sent to the class object. The solution would require these variables to be initialized just before entering main.

The correct solution of the above problem is to use the +load method instead of +initialize:

@implementation FileStream

+ (void)load
{
    Stdin = [[FileStream new] initWithFd:0];
    Stdout = [[FileStream new] initWithFd:1];
    Stderr = [[FileStream new] initWithFd:2];
}

/* Other methods here */
@end

The +load is a method that is not overridden by categories. If a class and a category of it both implement +load, both methods are invoked. This allows some additional initializations to be performed in a category.

This mechanism is not intended to be a replacement for +initialize. You should be aware of its limitations when you decide to use it instead of +initialize.

  • What you can and what you cannot do in +load:


Using the GNU Compiler Collection (GCC)

Node:Explicit Reg Vars, Next:Alternate Keywords, Previous:Asm Labels, Up:C Extensions

Variables in Specified Registers

GNU C allows you to put a few global variables into specified hardware registers. You can also specify the register in which an ordinary register variable should be allocated.

  • Global register variables reserve registers throughout the program. This may be useful in programs such as programming language interpreters which have a couple of global variables that are accessed very often.
  • Local register variables in specific registers do not reserve the registers. The compiler's data flow analysis is capable of determining where the specified registers contain live values, and where they are available for other uses. Stores into local register variables may be deleted when they appear to be dead according to dataflow analysis. References to local register variables may be deleted or moved or simplified.

    These local variables are sometimes convenient for use with the extended asm feature (see Extended Asm), if you want to write one output of the assembler instruction directly into a particular register. (This will work provided the register you specify fits the constraints specified for that operand in the asm.)

  • Global Reg Vars:
  • Local Reg Vars:


Using the GNU Compiler Collection (GCC)

Node:Extended Asm, Next:Constraints, Previous:Inline, Up:C Extensions

Assembler Instructions with C Expression Operands

In an assembler instruction using asm, you can specify the operands of the instruction using C expressions. This means you need not guess which registers or memory locations will contain the data you want to use.

You must specify an assembler instruction template much like what appears in a machine description, plus an operand constraint string for each operand.

For example, here is how to use the 68881's fsinx instruction:

asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));

Here angle is the C expression for the input operand while result is that of the output operand. Each has "f" as its operand constraint, saying that a floating point register is required. The = in =f indicates that the operand is an output; all output operands' constraints must use =. The constraints use the same language used in the machine description (see Constraints).

Each operand is described by an operand-constraint string followed by the C expression in parentheses. A colon separates the assembler template from the first output operand and another separates the last output operand from the first input, if any. Commas separate the operands within each group. The total number of operands is currently limited to 30; this limitation may be lifted in some future version of GCC.

If there are no output operands but there are input operands, you must place two consecutive colons surrounding the place where the output operands would go.

As of GCC version 3.1, it is also possible to specify input and output operands using symbolic names which can be referenced within the assembler code. These names are specified inside square brackets preceding the constraint string, and can be referenced inside the assembler code using %[name] instead of a percentage sign followed by the operand number. Using named operands the above example could look like:

asm ("fsinx %[angle],%[output]"
     : [output] "=f" (result)
     : [angle] "f" (angle));

Note that the symbolic operand names have no relation whatsoever to other C identifiers. You may use any name you like, even those of existing C symbols, but must ensure that no two operands within the same assembler construct use the same symbolic name.

Output operand expressions must be lvalues; the compiler can check this. The input operands need not be lvalues. The compiler cannot check whether the operands have data types that are reasonable for the instruction being executed. It does not parse the assembler instruction template and does not know what it means or even whether it is valid assembler input. The extended asm feature is most often used for machine instructions the compiler itself does not know exist. If the output expression cannot be directly addressed (for example, it is a bit-field), your constraint must allow a register. In that case, GCC will use the register as the output of the asm, and then store that register into the output.

The ordinary output operands must be write-only; GCC will assume that the values in these operands before the instruction are dead and need not be generated. Extended asm supports input-output or read-write operands. Use the constraint character + to indicate such an operand and list it with the output operands.

When the constraints for the read-write operand (or the operand in which only some of the bits are to be changed) allows a register, you may, as an alternative, logically split its function into two separate operands, one input operand and one write-only output operand. The connection between them is expressed by constraints which say they need to be in the same location when the instruction executes. You can use the same C expression for both operands, or different expressions. For example, here we write the (fictitious) combine instruction with bar as its read-only source operand and foo as its read-write destination:

asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));

The constraint "0" for operand 1 says that it must occupy the same location as operand 0. A number in constraint is allowed only in an input operand and it must refer to an output operand.

Only a number in the constraint can guarantee that one operand will be in the same place as another. The mere fact that foo is the value of both operands is not enough to guarantee that they will be in the same place in the generated assembler code. The following would not work reliably:

asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));

Various optimizations or reloading could cause operands 0 and 1 to be in different registers; GCC knows no reason not to do so. For example, the compiler might find a copy of the value of foo in one register and use it for operand 1, but generate the output operand 0 in a different register (copying it afterward to foo's own address). Of course, since the register for operand 1 is not even mentioned in the assembler code, the result will not work, but GCC can't tell that.

As of GCC version 3.1, one may write [name] instead of the operand number for a matching constraint. For example:

asm ("cmoveq %1,%2,%[result]"
     : [result] "=r"(result)
     : "r" (test), "r"(new), "[result]"(old));

Some instructions clobber specific hard registers. To describe this, write a third colon after the input operands, followed by the names of the clobbered hard registers (given as strings). Here is a realistic example for the VAX:

asm volatile ("movc3 %0,%1,%2"
              : /* no outputs */
              : "g" (from), "g" (to), "g" (count)
              : "r0", "r1", "r2", "r3", "r4", "r5");

You may not write a clobber description in a way that overlaps with an input or output operand. For example, you may not have an operand describing a register class with one member if you mention that register in the clobber list. There is no way for you to specify that an input operand is modified without also specifying it as an output operand. Note that if all the output operands you specify are for this purpose (and hence unused), you will then also need to specify volatile for the asm construct, as described below, to prevent GCC from deleting the asm statement as unused.

If you refer to a particular hardware register from the assembler code, you will probably have to list the register after the third colon to tell the compiler the register's value is modified. In some assemblers, the register names begin with %; to produce one % in the assembler code, you must write %% in the input.

If your assembler instruction can alter the condition code register, add cc to the list of clobbered registers. GCC on some machines represents the condition codes as a specific hardware register; cc serves to name this register. On other machines, the condition code is handled differently, and specifying cc has no effect. But it is valid no matter what the machine.

If your assembler instruction modifies memory in an unpredictable fashion, add memory to the list of clobbered registers. This will cause GCC to not keep memory values cached in registers across the assembler instruction. You will also want to add the volatile keyword if the memory affected is not listed in the inputs or outputs of the asm, as the memory clobber does not count as a side-effect of the asm.

You can put multiple assembler instructions together in a single asm template, separated by the characters normally used in assembly code for the system. A combination that works in most places is a newline to break the line, plus a tab character to move to the instruction field (written as \n\t). Sometimes semicolons can be used, if the assembler allows semicolons as a line-breaking character. Note that some assembler dialects use semicolons to start a comment. The input operands are guaranteed not to use any of the clobbered registers, and neither will the output operands' addresses, so you can read and write the clobbered registers as many times as you like. Here is an example of multiple instructions in a template; it assumes the subroutine _foo accepts arguments in registers 9 and 10:

asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
     : /* no outputs */
     : "g" (from), "g" (to)
     : "r9", "r10");

Unless an output operand has the & constraint modifier, GCC may allocate it in the same register as an unrelated input operand, on the assumption the inputs are consumed before the outputs are produced. This assumption may be false if the assembler code actually consists of more than one instruction. In such a case, use & for each output operand that may not overlap an input. See Modifiers.

If you want to test the condition code produced by an assembler instruction, you must include a branch and a label in the asm construct, as follows:

asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
     : "g" (result)
     : "g" (input));

This assumes your assembler supports local labels, as the GNU assembler and most Unix assemblers do.

Speaking of labels, jumps from one asm to another are not supported. The compiler's optimizers do not know about these jumps, and therefore they cannot take account of them when deciding how to optimize.

Usually the most convenient way to use these asm instructions is to encapsulate them in macros that look like functions. For example,

#define sin(x)       \
({ double __value, __arg = (x);   \
   asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
   __value; })

Here the variable __arg is used to make sure that the instruction operates on a proper double value, and to accept only those arguments x which can convert automatically to a double.

Another way to make sure the instruction operates on the correct data type is to use a cast in the asm. This is different from using a variable __arg in that it converts more different types. For example, if the desired type were int, casting the argument to int would accept a pointer with no complaint, while assigning the argument to an int variable named __arg would warn about using a pointer unless the caller explicitly casts it.

If an asm has output operands, GCC assumes for optimization purposes the instruction has no side effects except to change the output operands. This does not mean instructions with a side effect cannot be used, but you must be careful, because the compiler may eliminate them if the output operands aren't used, or move them out of loops, or replace two with one if they constitute a common subexpression. Also, if your instruction does have a side effect on a variable that otherwise appears not to change, the old value of the variable may be reused later if it happens to be found in a register.

You can prevent an asm instruction from being deleted, moved significantly, or combined, by writing the keyword volatile after the asm. For example:

#define get_and_set_priority(new)              \
({ int __old;                                  \
   asm volatile ("get_and_set_priority %0, %1" \
                 : "=g" (__old) : "g" (new));  \
   __old; })

If you write an asm instruction with no outputs, GCC will know the instruction has side-effects and will not delete the instruction or move it outside of loops.

The volatile keyword indicates that the instruction has important side-effects. GCC will not delete a volatile asm if it is reachable. (The instruction can still be deleted if GCC can prove that control-flow will never reach the location of the instruction.) In addition, GCC will not reschedule instructions across a volatile asm instruction. For example:

*(volatile int *)addr = foo;
asm volatile ("eieio" : : );

Assume addr contains the address of a memory mapped device register. The PowerPC eieio instruction (Enforce In-order Execution of I/O) tells the CPU to make sure that the store to that device register happens before it issues any other I/O.

Note that even a volatile asm instruction can be moved in ways that appear insignificant to the compiler, such as across jump instructions. You can't expect a sequence of volatile asm instructions to remain perfectly consecutive. If you want consecutive output, use a single asm. Also, GCC will perform some optimizations across a volatile asm instruction; GCC does not "forget everything" when it encounters a volatile asm instruction the way some other compilers do.

An asm instruction without any operands or clobbers (an "old style" asm) will be treated identically to a volatile asm instruction.

It is a natural idea to look for a way to give access to the condition code left by the assembler instruction. However, when we attempted to implement this, we found no way to make it work reliably. The problem is that output operands might need reloading, which would result in additional following "store" instructions. On most machines, these instructions would alter the condition code before there was time to test it. This problem doesn't arise for ordinary "test" and "compare" instructions because they don't have any output operands.

For reasons similar to those described above, it is not possible to give an assembler instruction access to the condition code left by previous instructions.

If you are writing a header file that should be includable in ISO C programs, write __asm__ instead of asm. See Alternate Keywords.

i386 floating point asm operands

There are several rules on the usage of stack-like regs in asm_operands insns. These rules apply only to the operands that are stack-like regs:

  1. Given a set of input regs that die in an asm_operands, it is necessary to know which are implicitly popped by the asm, and which must be explicitly popped by gcc.

    An input reg that is implicitly popped by the asm must be explicitly clobbered, unless it is constrained to match an output operand.

  2. For any input reg that is implicitly popped by an asm, it is necessary to know how to adjust the stack to compensate for the pop. If any non-popped input is closer to the top of the reg-stack than the implicitly popped reg, it would not be possible to know what the stack looked like--it's not clear how the rest of the stack "slides up".

    All implicitly popped input regs must be closer to the top of the reg-stack than any input that is not implicitly popped.

    It is possible that if an input dies in an insn, reload might use the input reg for an output reload. Consider this example:

    asm ("foo" : "=t" (a) : "f" (b));

    This asm says that input B is not popped by the asm, and that the asm pushes a result onto the reg-stack, i.e., the stack is one deeper after the asm than it was before. But, it is possible that reload will think that it can use the same reg for both the input and the output, if input B dies in this insn.

    If any input operand uses the f constraint, all output reg constraints must use the & earlyclobber.

    The asm above would be written as

    asm ("foo" : "=&t" (a) : "f" (b));

  3. Some operands need to be in particular places on the stack. All output operands fall in this category--there is no other way to know which regs the outputs appear in unless the user indicates this in the constraints.

    Output operands must specifically indicate which reg an output appears in after an asm. =f is not allowed: the operand constraints must select a class with a single reg.

  4. Output operands may not be "inserted" between existing stack regs. Since no 387 opcode uses a read/write operand, all output operands are dead before the asm_operands, and are pushed by the asm_operands. It makes no sense to push anywhere but the top of the reg-stack.

    Output operands must start at the top of the reg-stack: output operands may not "skip" a reg.

  5. Some asm statements may need extra stack space for internal calculations. This can be guaranteed by clobbering stack registers unrelated to the inputs and outputs.

Here are a couple of reasonable asms to want to write. This asm takes one input, which is internally popped, and produces two outputs.

asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));

This asm takes two inputs, which are popped by the fyl2xp1 opcode, and replaces them with one output. The user must code the st(1) clobber for reg-stack.c to know that fyl2xp1 pops both inputs.

asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");


Using the GNU Compiler Collection (GCC)

Node:External Bugs, Next:Incompatibilities, Previous:Interoperation, Up:Trouble

Problems Compiling Certain Programs

Certain programs have problems compiling.

  • Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2 because of problems in DEC's versions of the X11 header files X11/Xlib.h and X11/Xutil.h. People recommend adding -I/usr/include/mit to use the MIT versions of the header files, using the -traditional switch to turn off ISO C, or fixing the header files by adding this:
    #ifdef __STDC__
#define NeedFunctionPrototypes 0
#endif
  • On various 386 Unix systems derived from System V, including SCO, ISC, and ESIX, you may get error messages about running out of virtual memory while compiling certain programs.

    You can prevent this problem by linking GCC with the GNU malloc (which thus replaces the malloc that comes with the system). GNU malloc is available as a separate package, and also in the file src/gmalloc.c in the GNU Emacs 19 distribution.

    If you have installed GNU malloc as a separate library package, use this option when you relink GCC:

    MALLOC=/usr/local/lib/libgmalloc.a

    Alternatively, if you have compiled gmalloc.c from Emacs 19, copy the object file to gmalloc.o and use this option when you relink GCC:

    MALLOC=gmalloc.o


Using the GNU Compiler Collection (GCC)

Node:Fixed Headers, Next:Standard Libraries, Previous:Incompatibilities, Up:Trouble

Fixed Header Files

GCC needs to install corrected versions of some system header files. This is because most target systems have some header files that won't work with GCC unless they are changed. Some have bugs, some are incompatible with ISO C, and some depend on special features of other compilers.

Installing GCC automatically creates and installs the fixed header files, by running a program called fixincludes (or for certain targets an alternative such as fixinc.svr4). Normally, you don't need to pay attention to this. But there are cases where it doesn't do the right thing automatically.

  • If you update the system's header files, such as by installing a new system version, the fixed header files of GCC are not automatically updated. The easiest way to update them is to reinstall GCC. (If you want to be clever, look in the makefile and you can find a shortcut.)
  • On some systems, in particular SunOS 4, header file directories contain machine-specific symbolic links in certain places. This makes it possible to share most of the header files among hosts running the same version of SunOS 4 on different machine models.

    The programs that fix the header files do not understand this special way of using symbolic links; therefore, the directory of fixed header files is good only for the machine model used to build it.

    In SunOS 4, only programs that look inside the kernel will notice the difference between machine models. Therefore, for most purposes, you need not be concerned about this.

    It is possible to make separate sets of fixed header files for the different machine models, and arrange a structure of symbolic links so as to use the proper set, but you'll have to do this by hand.

  • On Lynxos, GCC by default does not fix the header files. This is because bugs in the shell cause the fixincludes script to fail.

    This means you will encounter problems due to bugs in the system header files. It may be no comfort that they aren't GCC's fault, but it does mean that there's nothing for us to do about them.


Using the GNU Compiler Collection (GCC)

Node:Function Attributes, Next:Attribute Syntax, Previous:Mixed Declarations, Up:C Extensions

Declaring Attributes of Functions

In GNU C, you declare certain things about functions called in your program which help the compiler optimize function calls and check your code more carefully.

The keyword __attribute__ allows you to specify special attributes when making a declaration. This keyword is followed by an attribute specification inside double parentheses. The following attributes are currently defined for functions on all targets: noreturn, noinline, always_inline, pure, const, format, format_arg, no_instrument_function, section, constructor, destructor, used, unused, deprecated, weak, malloc, and alias. Several other attributes are defined for functions on particular target systems. Other attributes, including section are supported for variables declarations (see Variable Attributes) and for types (see Type Attributes).

You may also specify attributes with __ preceding and following each keyword. This allows you to use them in header files without being concerned about a possible macro of the same name. For example, you may use __noreturn__ instead of noreturn.

See Attribute Syntax, for details of the exact syntax for using attributes.

noreturn
A few standard library functions, such as abort and exit, cannot return. GCC knows this automatically. Some programs define their own functions that never return. You can declare them noreturn to tell the compiler this fact. For example,
void fatal () __attribute__ ((noreturn));

void
fatal (...)
{
  ... /* Print error message. */ ...
  exit (1);
}

The noreturn keyword tells the compiler to assume that fatal cannot return. It can then optimize without regard to what would happen if fatal ever did return. This makes slightly better code. More importantly, it helps avoid spurious warnings of uninitialized variables.

Do not assume that registers saved by the calling function are restored before calling the noreturn function.

It does not make sense for a noreturn function to have a return type other than void.

The attribute noreturn is not implemented in GCC versions earlier than 2.5. An alternative way to declare that a function does not return, which works in the current version and in some older versions, is as follows:

typedef void voidfn ();

volatile voidfn fatal;

noinline
This function attribute prevents a function from being considered for inlining.
always_inline
Generally, functions are not inlined unless optimization is specified. For functions declared inline, this attribute inlines the function even if no optimization level was specified.
pure
Many functions have no effects except the return value and their return value depends only on the parameters and/or global variables. Such a function can be subject to common subexpression elimination and loop optimization just as an arithmetic operator would be. These functions should be declared with the attribute pure. For example,
int square (int) __attribute__ ((pure));

says that the hypothetical function square is safe to call fewer times than the program says.

Some of common examples of pure functions are strlen or memcmp. Interesting non-pure functions are functions with infinite loops or those depending on volatile memory or other system resource, that may change between two consecutive calls (such as feof in a multithreading environment).

The attribute pure is not implemented in GCC versions earlier than 2.96.

const
Many functions do not examine any values except their arguments, and have no effects except the return value. Basically this is just slightly more strict class than the pure attribute above, since function is not allowed to read global memory.

Note that a function that has pointer arguments and examines the data pointed to must not be declared const. Likewise, a function that calls a non-const function usually must not be const. It does not make sense for a const function to return void.

The attribute const is not implemented in GCC versions earlier than 2.5. An alternative way to declare that a function has no side effects, which works in the current version and in some older versions, is as follows:

typedef int intfn ();

extern const intfn square;

This approach does not work in GNU C++ from 2.6.0 on, since the language specifies that the const must be attached to the return value.

format (archetype, string-index, first-to-check)
The format attribute specifies that a function takes printf, scanf, strftime or strfmon style arguments which should be type-checked against a format string. For example, the declaration:
extern int
my_printf (void *my_object, const char *my_format, ...)
      __attribute__ ((format (printf, 2, 3)));

causes the compiler to check the arguments in calls to my_printf for consistency with the printf style format string argument my_format.

The parameter archetype determines how the format string is interpreted, and should be printf, scanf, strftime or strfmon. (You can also use __printf__, __scanf__, __strftime__ or __strfmon__.) The parameter string-index specifies which argument is the format string argument (starting from 1), while first-to-check is the number of the first argument to check against the format string. For functions where the arguments are not available to be checked (such as vprintf), specify the third parameter as zero. In this case the compiler only checks the format string for consistency. For strftime formats, the third parameter is required to be zero.

In the example above, the format string (my_format) is the second argument of the function my_print, and the arguments to check start with the third argument, so the correct parameters for the format attribute are 2 and 3.

The format attribute allows you to identify your own functions which take format strings as arguments, so that GCC can check the calls to these functions for errors. The compiler always (unless -ffreestanding is used) checks formats for the standard library functions printf, fprintf, sprintf, scanf, fscanf, sscanf, strftime, vprintf, vfprintf and vsprintf whenever such warnings are requested (using -Wformat), so there is no need to modify the header file stdio.h. In C99 mode, the functions snprintf, vsnprintf, vscanf, vfscanf and vsscanf are also checked. Except in strictly conforming C standard modes, the X/Open function strfmon is also checked as are printf_unlocked and fprintf_unlocked. See Options Controlling C Dialect.

format_arg (string-index)
The format_arg attribute specifies that a function takes a format string for a printf, scanf, strftime or strfmon style function and modifies it (for example, to translate it into another language), so the result can be passed to a printf, scanf, strftime or strfmon style function (with the remaining arguments to the format function the same as they would have been for the unmodified string). For example, the declaration:
extern char *
my_dgettext (char *my_domain, const char *my_format)
      __attribute__ ((format_arg (2)));

causes the compiler to check the arguments in calls to a printf, scanf, strftime or strfmon type function, whose format string argument is a call to the my_dgettext function, for consistency with the format string argument my_format. If the format_arg attribute had not been specified, all the compiler could tell in such calls to format functions would be that the format string argument is not constant; this would generate a warning when -Wformat-nonliteral is used, but the calls could not be checked without the attribute.

The parameter string-index specifies which argument is the format string argument (starting from 1).

The format-arg attribute allows you to identify your own functions which modify format strings, so that GCC can check the calls to printf, scanf, strftime or strfmon type function whose operands are a call to one of your own function. The compiler always treats gettext, dgettext, and dcgettext in this manner except when strict ISO C support is requested by -ansi or an appropriate -std option, or -ffreestanding is used. See Options Controlling C Dialect.

no_instrument_function
If -finstrument-functions is given, profiling function calls will be generated at entry and exit of most user-compiled functions. Functions with this attribute will not be so instrumented.
section ("section-name")
Normally, the compiler places the code it generates in the text section. Sometimes, however, you need additional sections, or you need certain particular functions to appear in special sections. The section attribute specifies that a function lives in a particular section. For example, the declaration:
extern void foobar (void) __attribute__ ((section ("bar")));

puts the function foobar in the bar section.

Some file formats do not support arbitrary sections so the section attribute is not available on all platforms. If you need to map the entire contents of a module to a particular section, consider using the facilities of the linker instead.

constructor
destructor
The constructor attribute causes the function to be called automatically before execution enters main (). Similarly, the destructor attribute causes the function to be called automatically after main () has completed or exit () has been called. Functions with these attributes are useful for initializing data that will be used implicitly during the execution of the program.

These attributes are not currently implemented for Objective-C.

unused
This attribute, attached to a function, means that the function is meant to be possibly unused. GCC will not produce a warning for this function. GNU C++ does not currently support this attribute as definitions without parameters are valid in C++.
used
This attribute, attached to a function, means that code must be emitted for the function even if it appears that the function is not referenced. This is useful, for example, when the function is referenced only in inline assembly.
deprecated
The deprecated attribute results in a warning if the function is used anywhere in the source file. This is useful when identifying functions that are expected to be removed in a future version of a program. The warning also includes the location of the declaration of the deprecated function, to enable users to easily find further information about why the function is deprecated, or what they should do instead. Note that the warnings only occurs for uses:
int old_fn () __attribute__ ((deprecated));
int old_fn ();
int (*fn_ptr)() = old_fn;

results in a warning on line 3 but not line 2.

The deprecated attribute can also be used for variables and types (see Variable Attributes, see Type Attributes.)

weak
The weak attribute causes the declaration to be emitted as a weak symbol rather than a global. This is primarily useful in defining library functions which can be overridden in user code, though it can also be used with non-function declarations. Weak symbols are supported for ELF targets, and also for a.out targets when using the GNU assembler and linker.
malloc
The malloc attribute is used to tell the compiler that a function may be treated as if it were the malloc function. The compiler assumes that calls to malloc result in a pointers that cannot alias anything. This will often improve optimization.
alias ("target")
The alias attribute causes the declaration to be emitted as an alias for another symbol, which must be specified. For instance,
void __f () { /* do something */; }
void f () __attribute__ ((weak, alias ("__f")));

declares f to be a weak alias for __f. In C++, the mangled name for the target must be used.

Not all target machines support this attribute.

regparm (number)
On the Intel 386, the regparm attribute causes the compiler to pass up to number integer arguments in registers EAX, EDX, and ECX instead of on the stack. Functions that take a variable number of arguments will continue to be passed all of their arguments on the stack.
stdcall
On the Intel 386, the stdcall attribute causes the compiler to assume that the called function will pop off the stack space used to pass arguments, unless it takes a variable number of arguments.

The PowerPC compiler for Windows NT currently ignores the stdcall attribute.

cdecl
On the Intel 386, the cdecl attribute causes the compiler to assume that the calling function will pop off the stack space used to pass arguments. This is useful to override the effects of the -mrtd switch.

The PowerPC compiler for Windows NT currently ignores the cdecl attribute.

longcall
On the RS/6000 and PowerPC, the longcall attribute causes the compiler to always call the function via a pointer, so that functions which reside further than 64 megabytes (67,108,864 bytes) from the current location can be called.
long_call/short_call
This attribute allows to specify how to call a particular function on ARM. Both attributes override the -mlong-calls (see ARM Options) command line switch and #pragma long_calls settings. The long_call attribute causes the compiler to always call the function by first loading its address into a register and then using the contents of that register. The short_call attribute always places the offset to the function from the call site into the BL instruction directly.
dllimport
On the PowerPC running Windows NT, the dllimport attribute causes the compiler to call the function via a global pointer to the function pointer that is set up by the Windows NT dll library. The pointer name is formed by combining __imp_ and the function name.
dllexport
On the PowerPC running Windows NT, the dllexport attribute causes the compiler to provide a global pointer to the function pointer, so that it can be called with the dllimport attribute. The pointer name is formed by combining __imp_ and the function name.
exception (except-func [, except-arg])
On the PowerPC running Windows NT, the exception attribute causes the compiler to modify the structured exception table entry it emits for the declared function. The string or identifier except-func is placed in the third entry of the structured exception table. It represents a function, which is called by the exception handling mechanism if an exception occurs. If it was specified, the string or identifier except-arg is placed in the fourth entry of the structured exception table.
function_vector
Use this attribute on the H8/300 and H8/300H to indicate that the specified function should be called through the function vector. Calling a function through the function vector will reduce code size, however; the function vector has a limited size (maximum 128 entries on the H8/300 and 64 entries on the H8/300H) and shares space with the interrupt vector.

You must use GAS and GLD from GNU binutils version 2.7 or later for this attribute to work correctly.

interrupt
Use this attribute on the ARM, AVR, M32R/D and Xstormy16 ports to indicate that the specified function is an interrupt handler. The compiler will generate function entry and exit sequences suitable for use in an interrupt handler when this attribute is present.

Note, interrupt handlers for the H8/300, H8/300H and SH processors can be specified via the interrupt_handler attribute.

Note, on the AVR interrupts will be enabled inside the function.

Note, for the ARM you can specify the kind of interrupt to be handled by adding an optional parameter to the interrupt attribute like this:

void f () __attribute__ ((interrupt ("IRQ")));

Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF.

interrupt_handler
Use this attribute on the H8/300, H8/300H and SH to indicate that the specified function is an interrupt handler. The compiler will generate function entry and exit sequences suitable for use in an interrupt handler when this attribute is present.
sp_switch
Use this attribute on the SH to indicate an interrupt_handler function should switch to an alternate stack. It expects a string argument that names a global variable holding the address of the alternate stack.
void *alt_stack;
void f () __attribute__ ((interrupt_handler,
                          sp_switch ("alt_stack")));

trap_exit
Use this attribute on the SH for an interrupt_handle to return using trapa instead of rte. This attribute expects an integer argument specifying the trap number to be used.
eightbit_data
Use this attribute on the H8/300 and H8/300H to indicate that the specified variable should be placed into the eight bit data section. The compiler will generate more efficient code for certain operations on data in the eight bit data area. Note the eight bit data area is limited to 256 bytes of data.

You must use GAS and GLD from GNU binutils version 2.7 or later for this attribute to work correctly.

tiny_data
Use this attribute on the H8/300H to indicate that the specified variable should be placed into the tiny data section. The compiler will generate more efficient code for loads and stores on data in the tiny data section. Note the tiny data area is limited to slightly under 32kbytes of data.
signal
Use this attribute on the AVR to indicate that the specified function is an signal handler. The compiler will generate function entry and exit sequences suitable for use in an signal handler when this attribute is present. Interrupts will be disabled inside function.
naked
Use this attribute on the ARM or AVR ports to indicate that the specified function do not need prologue/epilogue sequences generated by the compiler. It is up to the programmer to provide these sequences.
model (model-name)
Use this attribute on the M32R/D to set the addressability of an object, and the code generated for a function. The identifier model-name is one of small, medium, or large, representing each of the code models.

Small model objects live in the lower 16MB of memory (so that their addresses can be loaded with the ld24 instruction), and are callable with the bl instruction.

Medium model objects may live anywhere in the 32-bit address space (the compiler will generate seth/add3 instructions to load their addresses), and are callable with the bl instruction.

Large model objects may live anywhere in the 32-bit address space (the compiler will generate seth/add3 instructions to load their addresses), and may not be reachable with the bl instruction (the compiler will generate the much slower seth/add3/jl instruction sequence).

You can specify multiple attributes in a declaration by separating them by commas within the double parentheses or by immediately following an attribute declaration with another attribute declaration.

Some people object to the __attribute__ feature, suggesting that ISO C's #pragma should be used instead. At the time __attribute__ was designed, there were two reasons for not doing this.

  1. It is impossible to generate #pragma commands from a macro.
  2. There is no telling what the same #pragma might mean in another compiler.

These two reasons applied to almost any application that might have been proposed for #pragma. It was basically a mistake to use #pragma for anything.

The ISO C99 standard includes _Pragma, which now allows pragmas to be generated from macros. In addition, a #pragma GCC namespace is now in use for GCC-specific pragmas. However, it has been found convenient to use __attribute__ to achieve a natural attachment of attributes to their corresponding declarations, whereas #pragma GCC is of use for constructs that do not naturally form part of the grammar. See Miscellaneous Preprocessing Directives.


Using the GNU Compiler Collection (GCC)

Node:Function Names, Next:Return Address, Previous:Incomplete Enums, Up:C Extensions

Function Names as Strings

GCC predefines two magic identifiers to hold the name of the current function. The identifier __FUNCTION__ holds the name of the function as it appears in the source. The identifier __PRETTY_FUNCTION__ holds the name of the function pretty printed in a language specific fashion.

These names are always the same in a C function, but in a C++ function they may be different. For example, this program:

extern "C" {
extern int printf (char *, ...);
}

class a {
 public:
  sub (int i)
    {
      printf ("__FUNCTION__ = %s\n", __FUNCTION__);
      printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
    }
};

int
main (void)
{
  a ax;
  ax.sub (0);
  return 0;
}

gives this output:

__FUNCTION__ = sub
__PRETTY_FUNCTION__ = int  a::sub (int)

The compiler automagically replaces the identifiers with a string literal containing the appropriate name. Thus, they are neither preprocessor macros, like __FILE__ and __LINE__, nor variables. This means that they catenate with other string literals, and that they can be used to initialize char arrays. For example

char here[] = "Function " __FUNCTION__ " in " __FILE__;

On the other hand, #ifdef __FUNCTION__ does not have any special meaning inside a function, since the preprocessor does not do anything special with the identifier __FUNCTION__.

Note that these semantics are deprecated, and that GCC 3.2 will handle __FUNCTION__ and __PRETTY_FUNCTION__ the same way as __func__. __func__ is defined by the ISO standard C99:

The identifier __func__ is implicitly declared by the translator
as if, immediately following the opening brace of each function
definition, the declaration

static const char __func__[] = "function-name";

appeared, where function-name is the name of the lexically-enclosing
function.  This name is the unadorned name of the function.

By this definition, __func__ is a variable, not a string literal. In particular, __func__ does not catenate with other string literals.

In C++, __FUNCTION__ and __PRETTY_FUNCTION__ are variables, declared in the same way as __func__.


Using the GNU Compiler Collection (GCC)

Node:Function Prototypes, Next:C++ Comments, Previous:Attribute Syntax, Up:C Extensions

Prototypes and Old-Style Function Definitions

GNU C extends ISO C to allow a function prototype to override a later old-style non-prototype definition. Consider the following example:

/* Use prototypes unless the compiler is old-fashioned.  */
#ifdef __STDC__
#define P(x) x
#else
#define P(x) ()
#endif

/* Prototype function declaration.  */
int isroot P((uid_t));

/* Old-style function definition.  */
int
isroot (x)   /* ??? lossage here ??? */
     uid_t x;
{
  return x == 0;
}

Suppose the type uid_t happens to be short. ISO C does not allow this example, because subword arguments in old-style non-prototype definitions are promoted. Therefore in this example the function definition's argument is really an int, which does not match the prototype argument type of short.

This restriction of ISO C makes it hard to write code that is portable to traditional C compilers, because the programmer does not know whether the uid_t type is short, int, or long. Therefore, in cases like these GNU C allows a prototype to override a later old-style definition. More precisely, in GNU C, a function prototype argument type overrides the argument type specified by a later old-style definition if the former type is the same as the latter type before promotion. Thus in GNU C the above example is equivalent to the following:

int isroot (uid_t);

int
isroot (uid_t x)
{
  return x == 0;
}

GNU C++ does not support old-style function definitions, so this extension is irrelevant.


Using the GNU Compiler Collection (GCC)

Node:Funding, Next:GNU Project, Previous:VMS, Up:Top

Funding Free Software

If you want to have more free software a few years from now, it makes sense for you to help encourage people to contribute funds for its development. The most effective approach known is to encourage commercial redistributors to donate.

Users of free software systems can boost the pace of development by encouraging for-a-fee distributors to donate part of their selling price to free software developers--the Free Software Foundation, and others.

The way to convince distributors to do this is to demand it and expect it from them. So when you compare distributors, judge them partly by how much they give to free software development. Show distributors they must compete to be the one who gives the most.

To make this approach work, you must insist on numbers that you can compare, such as, "We will donate ten dollars to the Frobnitz project for each disk sold." Don't be satisfied with a vague promise, such as "A portion of the profits are donated," since it doesn't give a basis for comparison.

Even a precise fraction "of the profits from this disk" is not very meaningful, since creative accounting and unrelated business decisions can greatly alter what fraction of the sales price counts as profit. If the price you pay is $50, ten percent of the profit is probably less than a dollar; it might be a few cents, or nothing at all.

Some redistributors do development work themselves. This is useful too; but to keep everyone honest, you need to inquire how much they do, and what kind. Some kinds of development make much more long-term difference than others. For example, maintaining a separate version of a program contributes very little; maintaining the standard version of a program for the whole community contributes much. Easy new ports contribute little, since someone else would surely do them; difficult ports such as adding a new CPU to the GNU Compiler Collection contribute more; major new features or packages contribute the most.

By establishing the idea that supporting further development is "the proper thing to do" when distributing free software for a fee, we can assure a steady flow of resources into making more free software.

Copyright © 1994 Free Software Foundation, Inc.
Verbatim copying and redistribution of this section is permitted
without royalty; alteration is not permitted.


Using the GNU Compiler Collection (GCC)

Node:G++ and GCC, Next:Standards, Previous:Top, Up:Top

Compile C, C++, Objective-C, Ada, Fortran, or Java

Several versions of the compiler (C, C++, Objective-C, Ada, Fortran, and Java) are integrated; this is why we use the name "GNU Compiler Collection". GCC can compile programs written in any of these languages. The Ada, Fortran, and Java compilers are described in separate manuals.

"GCC" is a common shorthand term for the GNU Compiler Collection. This is both the most general name for the compiler, and the name used when the emphasis is on compiling C programs (as the abbreviation formerly stood for "GNU C Compiler").

When referring to C++ compilation, it is usual to call the compiler "G++". Since there is only one compiler, it is also accurate to call it "GCC" no matter what the language context; however, the term "G++" is more useful when the emphasis is on compiling C++ programs.

Similarly, when we talk about Ada compilation, we usually call the compiler "GNAT", for the same reasons.

We use the name "GCC" to refer to the compilation system as a whole, and more specifically to the language-independent part of the compiler. For example, we refer to the optimization options as affecting the behavior of "GCC" or sometimes just "the compiler".

Front ends for other languages, such as Mercury and Pascal exist but have not yet been integrated into GCC. These front ends, like that for C++, are built in subdirectories of GCC and link to it. The result is an integrated compiler that can compile programs written in C, C++, Objective-C, or any of the languages for which you have installed front ends.

In this manual, we only discuss the options for the C, Objective-C, and C++ compilers and those of the GCC core. Consult the documentation of the other front ends for the options to use when compiling programs written in other languages.

G++ is a compiler, not merely a preprocessor. G++ builds object code directly from your C++ program source. There is no intermediate C version of the program. (By contrast, for example, some other implementations use a program that generates a C program from your C++ source.) Avoiding an intermediate C representation of the program means that you get better object code, and better debugging information. The GNU debugger, GDB, works with this information in the object code to give you comprehensive C++ source-level editing capabilities (see C and C++).


Using the GNU Compiler Collection (GCC)

Node:Garbage Collection, Next:Constant string objects, Previous:Type encoding, Up:Objective-C

Garbage Collection

Support for a new memory management policy has been added by using a powerful conservative garbage collector, known as the Boehm-Demers-Weiser conservative garbage collector. It is available from http://www.hpl.hp.com/personal/Hans_Boehm/gc/.

To enable the support for it you have to configure the compiler using an additional argument, --enable-objc-gc. You need to have garbage collector installed before building the compiler. This will build an additional runtime library which has several enhancements to support the garbage collector. The new library has a new name, libobjc_gc.a to not conflict with the non-garbage-collected library.

When the garbage collector is used, the objects are allocated using the so-called typed memory allocation mechanism available in the Boehm-Demers-Weiser collector. This mode requires precise information on where pointers are located inside objects. This information is computed once per class, immediately after the class has been initialized.

There is a new runtime function class_ivar_set_gcinvisible() which can be used to declare a so-called weak pointer reference. Such a pointer is basically hidden for the garbage collector; this can be useful in certain situations, especially when you want to keep track of the allocated objects, yet allow them to be collected. This kind of pointers can only be members of objects, you cannot declare a global pointer as a weak reference. Every type which is a pointer type can be declared a weak pointer, including id, Class and SEL.

Here is an example of how to use this feature. Suppose you want to implement a class whose instances hold a weak pointer reference; the following class does this:

@interface WeakPointer : Object
{
    const void* weakPointer;
}

- initWithPointer:(const void*)p;
- (const void*)weakPointer;
@end

@implementation WeakPointer

+ (void)initialize
{
  class_ivar_set_gcinvisible (self, "weakPointer", YES);
}

- initWithPointer:(const void*)p
{
  weakPointer = p;
  return self;
}

- (const void*)weakPointer
{
  return weakPointer;
}

@end

Weak pointers are supported through a new type character specifier represented by the ! character. The class_ivar_set_gcinvisible() function adds or removes this specifier to the string type description of the instance variable named as argument.


Using the GNU Compiler Collection (GCC)

Node:Gcov and Optimization, Next:Gcov Data Files, Previous:Invoking Gcov, Up:Gcov

Using gcov with GCC Optimization

If you plan to use gcov to help optimize your code, you must first compile your program with two special GCC options: -fprofile-arcs -ftest-coverage. Aside from that, you can use any other GCC options; but if you want to prove that every single line in your program was executed, you should not compile with optimization at the same time. On some machines the optimizer can eliminate some simple code lines by combining them with other lines. For example, code like this:

if (a != b)
  c = 1;
else
  c = 0;

can be compiled into one instruction on some machines. In this case, there is no way for gcov to calculate separate execution counts for each line because there isn't separate code for each line. Hence the gcov output looks like this if you compiled the program with optimization:

      100  if (a != b)
      100    c = 1;
      100  else
      100    c = 0;

The output shows that this block of code, combined by optimization, executed 100 times. In one sense this result is correct, because there was only one instruction representing all four of these lines. However, the output does not indicate how many times the result was 0 and how many times the result was 1.


Using the GNU Compiler Collection (GCC)

Node:Gcov Data Files, Previous:Gcov and Optimization, Up:Gcov

Brief description of gcov data files

gcov uses three files for doing profiling. The names of these files are derived from the original source file by substituting the file suffix with either .bb, .bbg, or .da. All of these files are placed in the same directory as the source file, and contain data stored in a platform-independent method.

The .bb and .bbg files are generated when the source file is compiled with the GCC -ftest-coverage option. The .bb file contains a list of source files (including headers), functions within those files, and line numbers corresponding to each basic block in the source file.

The .bb file format consists of several lists of 4-byte integers which correspond to the line numbers of each basic block in the file. Each list is terminated by a line number of 0. A line number of -1 is used to designate that the source file name (padded to a 4-byte boundary and followed by another -1) follows. In addition, a line number of -2 is used to designate that the name of a function (also padded to a 4-byte boundary and followed by a -2) follows.

The .bbg file is used to reconstruct the program flow graph for the source file. It contains a list of the program flow arcs (possible branches taken from one basic block to another) for each function which, in combination with the .bb file, enables gcov to reconstruct the program flow.

In the .bbg file, the format is:

        number of basic blocks for function #0 (4-byte number)
        total number of arcs for function #0 (4-byte number)
        count of arcs in basic block #0 (4-byte number)
        destination basic block of arc #0 (4-byte number)
        flag bits (4-byte number)
        destination basic block of arc #1 (4-byte number)
        flag bits (4-byte number)
        ...
        destination basic block of arc #N (4-byte number)
        flag bits (4-byte number)
        count of arcs in basic block #1 (4-byte number)
        destination basic block of arc #0 (4-byte number)
        flag bits (4-byte number)
        ...

A -1 (stored as a 4-byte number) is used to separate each function's list of basic blocks, and to verify that the file has been read correctly.

The .da file is generated when a program containing object files built with the GCC -fprofile-arcs option is executed. A separate .da file is created for each source file compiled with this option, and the name of the .da file is stored as an absolute pathname in the resulting object file. This path name is derived from the source file name by substituting a .da suffix.

The format of the .da file is fairly simple. The first 8-byte number is the number of counts in the file, followed by the counts (stored as 8-byte numbers). Each count corresponds to the number of times each arc in the program is executed. The counts are cumulative; each time the program is executed, it attempts to combine the existing .da files with the new counts for this invocation of the program. It ignores the contents of any .da files whose number of arcs doesn't correspond to the current program, and merely overwrites them instead.

All three of these files use the functions in gcov-io.h to store integers; the functions in this header provide a machine-independent mechanism for storing and retrieving data from a stream.


Using the GNU Compiler Collection (GCC)

Node:Gcov Intro, Next:Invoking Gcov, Up:Gcov

Introduction to gcov

gcov is a test coverage program. Use it in concert with GCC to analyze your programs to help create more efficient, faster running code. You can use gcov as a profiling tool to help discover where your optimization efforts will best affect your code. You can also use gcov along with the other profiling tool, gprof, to assess which parts of your code use the greatest amount of computing time.

Profiling tools help you analyze your code's performance. Using a profiler such as gcov or gprof, you can find out some basic performance statistics, such as:

  • how often each line of code executes
  • what lines of code are actually executed
  • how much computing time each section of code uses

Once you know these things about how your code works when compiled, you can look at each module to see which modules should be optimized. gcov helps you determine where to work on optimization.

Software developers also use coverage testing in concert with testsuites, to make sure software is actually good enough for a release. Testsuites can verify that a program works as expected; a coverage program tests to see how much of the program is exercised by the testsuite. Developers can then determine what kinds of test cases need to be added to the testsuites to create both better testing and a better final product.

You should compile your code without optimization if you plan to use gcov because the optimization, by combining some lines of code into one function, may not give you as much information as you need to look for `hot spots' where the code is using a great deal of computer time. Likewise, because gcov accumulates statistics by line (at the lowest resolution), it works best with a programming style that places only one statement on each line. If you use complicated macros that expand to loops or to other control structures, the statistics are less helpful--they only report on the line where the macro call appears. If your complex macros behave like functions, you can replace them with inline functions to solve this problem.

gcov creates a logfile called sourcefile.gcov which indicates how many times each line of a source file sourcefile.c has executed. You can use these logfiles along with gprof to aid in fine-tuning the performance of your programs. gprof gives timing information you can use along with the information you get from gcov.

gcov works only on code compiled with GCC. It is not compatible with any other profiling or test coverage mechanism.


Using the GNU Compiler Collection (GCC)

Node:Gcov, Next:Trouble, Previous:Objective-C, Up:Top

gcov: a Test Coverage Program

gcov is a tool you can use in conjunction with GCC to test code coverage in your programs.

  • Gcov Intro: Introduction to gcov.
  • Invoking Gcov: How to use gcov.
  • Gcov and Optimization: Using gcov with GCC optimization.
  • Gcov Data Files: The files used by gcov.


Using the GNU Compiler Collection (GCC)

Node:Global Declarations, Next:VMS Misc, Previous:Include Files and VMS, Up:VMS

Global Declarations and VMS

GCC does not provide the globalref, globaldef and globalvalue keywords of VAX-C. You can get the same effect with an obscure feature of GAS, the GNU assembler. (This requires GAS version 1.39 or later.) The following macros allow you to use this feature in a fairly natural way:

#ifdef __GNUC__
#define GLOBALREF(TYPE,NAME)                      \
  TYPE NAME                                       \
  asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
#define GLOBALDEF(TYPE,NAME,VALUE)                \
  TYPE NAME                                       \
  asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
    = VALUE
#define GLOBALVALUEREF(TYPE,NAME)                 \
  const TYPE NAME[1]                              \
  asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
#define GLOBALVALUEDEF(TYPE,NAME,VALUE)           \
  const TYPE NAME[1]                              \
  asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)  \
    = {VALUE}
#else
#define GLOBALREF(TYPE,NAME) \
  globalref TYPE NAME
#define GLOBALDEF(TYPE,NAME,VALUE) \
  globaldef TYPE NAME = VALUE
#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
  globalvalue TYPE NAME = VALUE
#define GLOBALVALUEREF(TYPE,NAME) \
  globalvalue TYPE NAME
#endif

(The _$$PsectAttributes_GLOBALSYMBOL prefix at the start of the name is removed by the assembler, after it has modified the attributes of the symbol). These macros are provided in the VMS binaries distribution in a header file GNU_HACKS.H. An example of the usage is:

GLOBALREF (int, ijk);
GLOBALDEF (int, jkl, 0);

The macros GLOBALREF and GLOBALDEF cannot be used straightforwardly for arrays, since there is no way to insert the array dimension into the declaration at the right place. However, you can declare an array with these macros if you first define a typedef for the array type, like this:

typedef int intvector[10];
GLOBALREF (intvector, foo);

Array and structure initializers will also break the macros; you can define the initializer to be a macro of its own, or you can expand the GLOBALDEF macro by hand. You may find a case where you wish to use the GLOBALDEF macro with a large array, but you are not interested in explicitly initializing each element of the array. In such cases you can use an initializer like: {0,}, which will initialize the entire array to 0.

A shortcoming of this implementation is that a variable declared with GLOBALVALUEREF or GLOBALVALUEDEF is always an array. For example, the declaration:

GLOBALVALUEREF(int, ijk);

declares the variable ijk as an array of type int [1]. This is done because a globalvalue is actually a constant; its "value" is what the linker would normally consider an address. That is not how an integer value works in C, but it is how an array works. So treating the symbol as an array name gives consistent results--with the exception that the value seems to have the wrong type. Don't try to access an element of the array. It doesn't have any elements. The array "address" may not be the address of actual storage.

The fact that the symbol is an array may lead to warnings where the variable is used. Insert type casts to avoid the warnings. Here is an example; it takes advantage of the ISO C feature allowing macros that expand to use the same name as the macro itself.

GLOBALVALUEREF (int, ss$_normal);
GLOBALVALUEDEF (int, xyzzy,123);
#ifdef __GNUC__
#define ss$_normal ((int) ss$_normal)
#define xyzzy ((int) xyzzy)
#endif

Don't use globaldef or globalref with a variable whose type is an enumeration type; this is not implemented. Instead, make the variable an integer, and use a globalvaluedef for each of the enumeration values. An example of this would be:

#ifdef __GNUC__
GLOBALDEF (int, color, 0);
GLOBALVALUEDEF (int, RED, 0);
GLOBALVALUEDEF (int, BLUE, 1);
GLOBALVALUEDEF (int, GREEN, 3);
#else
enum globaldef color {RED, BLUE, GREEN = 3};
#endif


Using the GNU Compiler Collection (GCC)

Node:Global Reg Vars, Next:Local Reg Vars, Up:Explicit Reg Vars

Defining Global Register Variables

You can define a global register variable in GNU C like this:

register int *foo asm ("a5");

Here a5 is the name of the register which should be used. Choose a register which is normally saved and restored by function calls on your machine, so that library routines will not clobber it.

Naturally the register name is cpu-dependent, so you would need to conditionalize your program according to cpu type. The register a5 would be a good choice on a 68000 for a variable of pointer type. On machines with register windows, be sure to choose a "global" register that is not affected magically by the function call mechanism.

In addition, operating systems on one type of cpu may differ in how they name the registers; then you would need additional conditionals. For example, some 68000 operating systems call this register %a5.

Eventually there may be a way of asking the compiler to choose a register automatically, but first we need to figure out how it should choose and how to enable you to guide the choice. No solution is evident.

Defining a global register variable in a certain register reserves that register entirely for this use, at least within the current compilation. The register will not be allocated for any other purpose in the functions in the current compilation. The register will not be saved and restored by these functions. Stores into this register are never deleted even if they would appear to be dead, but references may be deleted or moved or simplified.

It is not safe to access the global register variables from signal handlers, or from more than one thread of control, because the system library routines may temporarily use the register for other things (unless you recompile them specially for the task at hand).

It is not safe for one function that uses a global register variable to call another such function foo by way of a third function lose that was compiled without knowledge of this variable (i.e. in a different source file in which the variable wasn't declared). This is because lose might save the register and put some other value there. For example, you can't expect a global register variable to be available in the comparison-function that you pass to qsort, since qsort might have put something else in that register. (If you are prepared to recompile qsort with the same global register variable, you can solve this problem.)

If you want to recompile qsort or other source files which do not actually use your global register variable, so that they will not use that register for any other purpose, then it suffices to specify the compiler option -ffixed-reg. You need not actually add a global register declaration to their source code.

A function which can alter the value of a global register variable cannot safely be called from a function compiled without this variable, because it could clobber the value the caller expects to find there on return. Therefore, the function which is the entry point into the part of the program that uses the global register variable must explicitly save and restore the value which belongs to its caller.

On most machines, longjmp will restore to each global register variable the value it had at the time of the setjmp. On some machines, however, longjmp will not change the value of global register variables. To be portable, the function that called setjmp should make other arrangements to save the values of the global register variables, and to restore them in a longjmp. This way, the same thing will happen regardless of what longjmp does.

All global register variable declarations must precede all function definitions. If such a declaration could appear after function definitions, the declaration would be too late to prevent the register from being used for other purposes in the preceding functions.

Global register variables may not have initial values, because an executable file has no means to supply initial contents for a register.

On the Sparc, there are reports that g3 ... g7 are suitable registers, but certain library functions, such as getwd, as well as the subroutines for division and remainder, modify g3 and g4. g1 and g2 are local temporaries.

On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of course, it will not do to use more than a few of those.


Using the GNU Compiler Collection (GCC)

Node:GNU Free Documentation License, Next:Contributors, Previous:Copying, Up:Top

GNU Free Documentation License

Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.


Using the GNU Compiler Collection (GCC)

Node:H8/300 Options, Next:SH Options, Previous:Clipper Options, Up:Submodel Options

H8/300 Options

These -m options are defined for the H8/300 implementations:

-mrelax
Shorten some address references at link time, when possible; uses the linker option -relax. See ld and the H8/300, for a fuller description.
-mh
Generate code for the H8/300H.
-ms
Generate code for the H8/S.
-ms2600
Generate code for the H8/S2600. This switch must be used with -ms.
-mint32
Make int data 32 bits by default.
-malign-300
On the H8/300H and H8/S, use the same alignment rules as for the H8/300. The default for the H8/300H and H8/S is to align longs and floats on 4 byte boundaries. -malign-300 causes them to be aligned on 2 byte boundaries. This option has no effect on the H8/300.


Using the GNU Compiler Collection (GCC)

Node:Hex Floats, Next:Zero Length, Previous:Complex, Up:C Extensions

Hex Floats

ISO C99 supports floating-point numbers written not only in the usual decimal notation, such as 1.55e1, but also numbers such as 0x1.fp3 written in hexadecimal format. As a GNU extension, GCC supports this in C89 mode (except in some cases when strictly conforming) and in C++. In that format the 0x hex introducer and the p or P exponent field are mandatory. The exponent is a decimal number that indicates the power of 2 by which the significant part will be multiplied. Thus 0x1.f is 1 15/16, p3 multiplies it by 8, and the value of 0x1.fp3 is the same as 1.55e1.

Unlike for floating-point numbers in the decimal notation the exponent is always required in the hexadecimal notation. Otherwise the compiler would not be able to resolve the ambiguity of, e.g., 0x1.f. This could mean 1.0f or 1.9375 since f is also the extension for floating-point constants of type float.


Using the GNU Compiler Collection (GCC)

Node:Hints implementation, Next:Structures unions enumerations and bit-fields implementation, Previous:Arrays and pointers implementation, Up:C Implementation

Hints

  • The extent to which suggestions made by using the register storage-class specifier are effective (6.7.1).
  • The extent to which suggestions made by using the inline function specifier are effective (6.7.4).


Using the GNU Compiler Collection (GCC)

Node:HPPA Options, Next:Intel 960 Options, Previous:i386 and x86-64 Options, Up:Submodel Options

HPPA Options

These -m options are defined for the HPPA family of computers:

-march=architecture-type
Generate code for the specified architecture. The choices for architecture-type are 1.0 for PA 1.0, 1.1 for PA 1.1, and 2.0 for PA 2.0 processors. Refer to /usr/lib/sched.models on an HP-UX system to determine the proper architecture option for your machine. Code compiled for lower numbered architectures will run on higher numbered architectures, but not the other way around.

PA 2.0 support currently requires gas snapshot 19990413 or later. The next release of binutils (current is 2.9.1) will probably contain PA 2.0 support.

-mpa-risc-1-0
-mpa-risc-1-1
-mpa-risc-2-0
Synonyms for -march=1.0, -march=1.1, and -march=2.0 respectively.
-mbig-switch
Generate code suitable for big switch tables. Use this option only if the assembler/linker complain about out of range branches within a switch table.
-mjump-in-delay
Fill delay slots of function calls with unconditional jump instructions by modifying the return pointer for the function call to be the target of the conditional jump.
-mdisable-fpregs
Prevent floating point registers from being used in any manner. This is necessary for compiling kernels which perform lazy context switching of floating point registers. If you use this option and attempt to perform floating point operations, the compiler will abort.
-mdisable-indexing
Prevent the compiler from using indexing address modes. This avoids some rather obscure problems when compiling MIG generated code under MACH.
-mno-space-regs
Generate code that assumes the target has no space registers. This allows GCC to generate faster indirect calls and use unscaled index address modes.

Such code is suitable for level 0 PA systems and kernels.

-mfast-indirect-calls
Generate code that assumes calls never cross space boundaries. This allows GCC to emit code which performs faster indirect calls.

This option will not work in the presence of shared libraries or nested functions.

-mlong-load-store
Generate 3-instruction load and store sequences as sometimes required by the HP-UX 10 linker. This is equivalent to the +k option to the HP compilers.
-mportable-runtime
Use the portable calling conventions proposed by HP for ELF systems.
-mgas
Enable the use of assembler directives only GAS understands.
-mschedule=cpu-type
Schedule code according to the constraints for the machine type cpu-type. The choices for cpu-type are 700 7100, 7100LC, 7200, and 8000. Refer to /usr/lib/sched.models on an HP-UX system to determine the proper scheduling option for your machine.
-mlinker-opt
Enable the optimization pass in the HPUX linker. Note this makes symbolic debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers in which they give bogus error messages when linking some programs.
-msoft-float
Generate output containing library calls for floating point. Warning: the requisite libraries are not available for all HPPA targets. Normally the facilities of the machine's usual C compiler are used, but this cannot be done directly in cross-compilation. You must make your own arrangements to provide suitable library functions for cross-compilation. The embedded target hppa1.1-*-pro does provide software floating point support.

-msoft-float changes the calling convention in the output file; therefore, it is only useful if you compile all of a program with this option. In particular, you need to compile libgcc.a, the library that comes with GCC, with -msoft-float in order for this to work.


Using the GNU Compiler Collection (GCC)

Node:i386 and x86-64 Options, Next:HPPA Options, Previous:MIPS Options, Up:Submodel Options

Intel 386 and AMD x86-64 Options

These -m options are defined for the i386 and x86-64 family of computers:

-mcpu=cpu-type
Tune to cpu-type everything applicable about the generated code, except for the ABI and the set of available instructions. The choices for cpu-type are i386, i486, i586, i686, pentium, pentium-mmx, pentiumpro, pentium2, pentium3, pentium4, k6, k6-2, k6-3, athlon, athlon-tbird, athlon-4, athlon-xp and athlon-mp.

While picking a specific cpu-type will schedule things appropriately for that particular chip, the compiler will not generate any code that does not run on the i386 without the -march=cpu-type option being used. i586 is equivalent to pentium and i686 is equivalent to pentiumpro. k6 and athlon are the AMD chips as opposed to the Intel ones.

-march=cpu-type
Generate instructions for the machine type cpu-type. The choices for cpu-type are the same as for -mcpu. Moreover, specifying -march=cpu-type implies -mcpu=cpu-type.
-m386
-m486
-mpentium
-mpentiumpro
These options are synonyms for -mcpu=i386, -mcpu=i486, -mcpu=pentium, and -mcpu=pentiumpro respectively. These synonyms are deprecated.
-mfpmath=unit
generate floating point arithmetics for selected unit unit. the choices for unit are:
387
Use the standard 387 floating point coprocessor present majority of chips and emulated otherwise. Code compiled with this option will run almost everywhere. The temporary results are computed in 80bit precesion instead of precision specified by the type resulting in slightly different results compared to most of other chips. See -ffloat-store for more detailed description.

This is the default choice for i386 compiler.

sse
Use scalar floating point instructions present in the SSE instruction set. This instruction set is supported by Pentium3 and newer chips, in the AMD line by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE instruction set supports only single precision arithmetics, thus the double and extended precision arithmetics is still done using 387. Later version, present only in Pentium4 and the future AMD x86-64 chips supports double precision arithmetics too.

For i387 you need to use -march=cpu-type, -msse or -msse2 switches to enable SSE extensions and make this option effective. For x86-64 compiler, these extensions are enabled by default.

The resulting code should be considerably faster in majority of cases and avoid the numerical instability problems of 387 code, but may break some existing code that expects temporaries to be 80bit.

This is the default choice for x86-64 compiler.

sse,387
Attempt to utilize both instruction sets at once. This effectivly double the amount of available registers and on chips with separate execution units for 387 and SSE the execution resources too. Use this option with care, as it is still experimental, because gcc register allocator does not model separate functional units well resulting in instable performance.

-masm=dialect
Output asm instructions using selected dialect. Supported choices are intel or att (the default one).
-mieee-fp
-mno-ieee-fp
Control whether or not the compiler uses IEEE floating point comparisons. These handle correctly the case where the result of a comparison is unordered.
-msoft-float
Generate output containing library calls for floating point. Warning: the requisite libraries are not part of GCC. Normally the facilities of the machine's usual C compiler are used, but this can't be done directly in cross-compilation. You must make your own arrangements to provide suitable library functions for cross-compilation.

On machines where a function returns floating point results in the 80387 register stack, some floating point opcodes may be emitted even if -msoft-float is used.

-mno-fp-ret-in-387
Do not use the FPU registers for return values of functions.

The usual calling convention has functions return values of types float and double in an FPU register, even if there is no FPU. The idea is that the operating system should emulate an FPU.

The option -mno-fp-ret-in-387 causes such values to be returned in ordinary CPU registers instead.

-mno-fancy-math-387
Some 387 emulators do not support the sin, cos and sqrt instructions for the 387. Specify this option to avoid generating those instructions. This option is the default on FreeBSD, OpenBSD and NetBSD. This option is overridden when -march indicates that the target cpu will always have an FPU and so the instruction will not need emulation. As of revision 2.6.1, these instructions are not generated unless you also use the -funsafe-math-optimizations switch.
-malign-double
-mno-align-double
Control whether GCC aligns double, long double, and long long variables on a two word boundary or a one word boundary. Aligning double variables on a two word boundary will produce code that runs somewhat faster on a Pentium at the expense of more memory.
-m128bit-long-double
Control the size of long double type. i386 application binary interface specify the size to be 12 bytes, while modern architectures (Pentium and newer) prefer long double aligned to 8 or 16 byte boundary. This is impossible to reach with 12 byte long doubles in the array accesses.

Warning: if you use the -m128bit-long-double switch, the structures and arrays containing long double will change their size as well as function calling convention for function taking long double will be modified.

-m96bit-long-double
Set the size of long double to 96 bits as required by the i386 application binary interface. This is the default.
-msvr3-shlib
-mno-svr3-shlib
Control whether GCC places uninitialized local variables into the bss or data segments. -msvr3-shlib places them into bss. These options are meaningful only on System V Release 3.
-mrtd
Use a different function-calling convention, in which functions that take a fixed number of arguments return with the ret num instruction, which pops their arguments while returning. This saves one instruction in the caller since there is no need to pop the arguments there.

You can specify that an individual function is called with this calling sequence with the function attribute stdcall. You can also override the -mrtd option by using the function attribute cdecl. See Function Attributes.

Warning: this calling convention is incompatible with the one normally used on Unix, so you cannot use it if you need to call libraries compiled with the Unix compiler.

Also, you must provide function prototypes for all functions that take variable numbers of arguments (including printf); otherwise incorrect code will be generated for calls to those functions.

In addition, seriously incorrect code will result if you call a function with too many arguments. (Normally, extra arguments are harmlessly ignored.)

-mregparm=num
Control how many registers are used to pass integer arguments. By default, no registers are used to pass arguments, and at most 3 registers can be used. You can control this behavior for a specific function by using the function attribute regparm. See Function Attributes.

Warning: if you use this switch, and num is nonzero, then you must build all modules with the same value, including any libraries. This includes the system libraries and startup modules.

-mpreferred-stack-boundary=num
Attempt to keep the stack boundary aligned to a 2 raised to num byte boundary. If -mpreferred-stack-boundary is not specified, the default is 4 (16 bytes or 128 bits), except when optimizing for code size (-Os), in which case the default is the minimum correct alignment (4 bytes for x86, and 8 bytes for x86-64).

On Pentium and PentiumPro, double and long double values should be aligned to an 8 byte boundary (see -malign-double) or suffer significant run time performance penalties. On Pentium III, the Streaming SIMD Extension (SSE) data type __m128 suffers similar penalties if it is not 16 byte aligned.

To ensure proper alignment of this values on the stack, the stack boundary must be as aligned as that required by any value stored on the stack. Further, every function must be generated such that it keeps the stack aligned. Thus calling a function compiled with a higher preferred stack boundary from a function compiled with a lower preferred stack boundary will most likely misalign the stack. It is recommended that libraries that use callbacks always use the default setting.

This extra alignment does consume extra stack space, and generally increases code size. Code that is sensitive to stack space usage, such as embedded systems and operating system kernels, may want to reduce the preferred alignment to -mpreferred-stack-boundary=2.

-mmmx
-mno-mmx
-msse
-mno-sse
-msse2
-mno-sse2
-m3dnow
-mno-3dnow
These switches enable or disable the use of built-in functions that allow direct access to the MMX, SSE and 3Dnow extensions of the instruction set.

See X86 Built-in Functions, for details of the functions enabled and disabled by these switches.

-mpush-args
-mno-push-args
Use PUSH operations to store outgoing parameters. This method is shorter and usually equally fast as method using SUB/MOV operations and is enabled by default. In some cases disabling it may improve performance because of improved scheduling and reduced dependencies.
-maccumulate-outgoing-args
If enabled, the maximum amount of space required for outgoing arguments will be computed in the function prologue. This is faster on most modern CPUs because of reduced dependencies, improved scheduling and reduced stack usage when preferred stack boundary is not equal to 2. The drawback is a notable increase in code size. This switch implies -mno-push-args.
-mthreads
Support thread-safe exception handling on Mingw32. Code that relies on thread-safe exception handling must compile and link all code with the -mthreads option. When compiling, -mthreads defines -D_MT; when linking, it links in a special thread helper library -lmingwthrd which cleans up per thread exception handling data.
-mno-align-stringops
Do not align destination of inlined string operations. This switch reduces code size and improves performance in case the destination is already aligned, but gcc don't know about it.
-minline-all-stringops
By default GCC inlines string operations only when destination is known to be aligned at least to 4 byte boundary. This enables more inlining, increase code size, but may improve performance of code that depends on fast memcpy, strlen and memset for short lengths.
-momit-leaf-frame-pointer
Don't keep the frame pointer in a register for leaf functions. This avoids the instructions to save, set up and restore frame pointers and makes an extra register available in leaf functions. The option -fomit-frame-pointer removes the frame pointer for all functions which might make debugging harder.

These -m switches are supported in addition to the above on AMD x86-64 processors in 64-bit environments.

-m32
-m64
Generate code for a 32-bit or 64-bit environment. The 32-bit environment sets int, long and pointer to 32 bits and generates code that runs on any i386 system. The 64-bit environment sets int to 32 bits and long and pointer to 64 bits and generates code for AMD's x86-64 architecture.
-mno-red-zone
Do not use a so called red zone for x86-64 code. The red zone is mandated by the x86-64 ABI, it is a 128-byte area beyond the location of the stack pointer that will not be modified by signal or interrupt handlers and therefore can be used for temporary data without adjusting the stack pointer. The flag -mno-red-zone disables this red zone.


Using the GNU Compiler Collection (GCC)

Node:IA-64 Options, Next:D30V Options, Previous:MCore Options, Up:Submodel Options

IA-64 Options

These are the -m options defined for the Intel IA-64 architecture.

-mbig-endian
Generate code for a big endian target. This is the default for HPUX.
-mlittle-endian
Generate code for a little endian target. This is the default for AIX5 and Linux.
-mgnu-as
-mno-gnu-as
Generate (or don't) code for the GNU assembler. This is the default.
-mgnu-ld
-mno-gnu-ld
Generate (or don't) code for the GNU linker. This is the default.
-mno-pic
Generate code that does not use a global pointer register. The result is not position independent code, and violates the IA-64 ABI.
-mvolatile-asm-stop
-mno-volatile-asm-stop
Generate (or don't) a stop bit immediately before and after volatile asm statements.
-mb-step
Generate code that works around Itanium B step errata.
-mregister-names
-mno-register-names
Generate (or don't) in, loc, and out register names for the stacked registers. This may make assembler output more readable.
-mno-sdata
-msdata
Disable (or enable) optimizations that use the small data section. This may be useful for working around optimizer bugs.
-mconstant-gp
Generate code that uses a single constant global pointer value. This is useful when compiling kernel code.
-mauto-pic
Generate code that is self-relocatable. This implies -mconstant-gp. This is useful when compiling firmware code.
-minline-divide-min-latency
Generate code for inline divides using the minimum latency algorithm.
-minline-divide-max-throughput
Generate code for inline divides using the maximum throughput algorithm.
-mno-dwarf2-asm
-mdwarf2-asm
Don't (or do) generate assembler code for the DWARF2 line number debugging info. This may be useful when not using the GNU assembler.
-mfixed-range=register-range
Generate code treating the given register range as fixed registers. A fixed register is one that the register allocator can not use. This is useful when compiling kernel code. A register range is specified as two registers separated by a dash. Multiple register ranges can be specified separated by a comma.


Using the GNU Compiler Collection (GCC)

Node:Identifiers implementation, Next:Characters implementation, Previous:Environment implementation, Up:C Implementation

Identifiers

  • Which additional multibyte characters may appear in identifiers and their correspondence to universal character names (6.4.2).
  • The number of significant initial characters in an identifier (5.2.4.1, 6.4.2).


Using the GNU Compiler Collection (GCC)

Node:Include Files and VMS, Next:Global Declarations, Up:VMS

Include Files and VMS

Due to the differences between the filesystems of Unix and VMS, GCC attempts to translate file names in #include into names that VMS will understand. The basic strategy is to prepend a prefix to the specification of the include file, convert the whole filename to a VMS filename, and then try to open the file. GCC tries various prefixes one by one until one of them succeeds:

  1. The first prefix is the GNU_CC_INCLUDE: logical name: this is where GNU C header files are traditionally stored. If you wish to store header files in non-standard locations, then you can assign the logical GNU_CC_INCLUDE to be a search list, where each element of the list is suitable for use with a rooted logical.
  2. The next prefix tried is SYS$SYSROOT:[SYSLIB.]. This is where VAX-C header files are traditionally stored.
  3. If the include file specification by itself is a valid VMS filename, the preprocessor then uses this name with no prefix in an attempt to open the include file.
  4. If the file specification is not a valid VMS filename (i.e. does not contain a device or a directory specifier, and contains a / character), the preprocessor tries to convert it from Unix syntax to VMS syntax.

    Conversion works like this: the first directory name becomes a device, and the rest of the directories are converted into VMS-format directory names. For example, the name X11/foobar.h is translated to X11:[000000]foobar.h or X11:foobar.h, whichever one can be opened. This strategy allows you to assign a logical name to point to the actual location of the header files.

  5. If none of these strategies succeeds, the #include fails.

Include directives of the form:

#include foobar

are a common source of incompatibility between VAX-C and GCC. VAX-C treats this much like a standard #include <foobar.h> directive. That is incompatible with the ISO C behavior implemented by GCC: to expand the name foobar as a macro. Macro expansion should eventually yield one of the two standard formats for #include:

#include "file"
#include <file>

If you have this problem, the best solution is to modify the source to convert the #include directives to one of the two standard forms. That will work with either compiler. If you want a quick and dirty fix, define the file names as macros with the proper expansion, like this:

#define stdio <stdio.h>

This will work, as long as the name doesn't conflict with anything else in the program.

Another source of incompatibility is that VAX-C assumes that:

#include "foobar"

is actually asking for the file foobar.h. GCC does not make this assumption, and instead takes what you ask for literally; it tries to read the file foobar. The best way to avoid this problem is to always specify the desired file extension in your include directives.

GCC for VMS is distributed with a set of include files that is sufficient to compile most general purpose programs. Even though the GCC distribution does not contain header files to define constants and structures for some VMS system-specific functions, there is no reason why you cannot use GCC with any of these functions. You first may have to generate or create header files, either by using the public domain utility UNSDL (which can be found on a DECUS tape), or by extracting the relevant modules from one of the system macro libraries, and using an editor to construct a C header file.

A #include file name cannot contain a DECNET node name. The preprocessor reports an I/O error if you attempt to use a node name, whether explicitly, or implicitly via a logical name.


Using the GNU Compiler Collection (GCC)

Node:Incompatibilities, Next:Fixed Headers, Previous:External Bugs, Up:Trouble

Incompatibilities of GCC

There are several noteworthy incompatibilities between GNU C and K&R (non-ISO) versions of C. The -traditional option eliminates many of these incompatibilities, but not all, by telling GCC to behave like a K&R C compiler.

  • GCC normally makes string constants read-only. If several identical-looking string constants are used, GCC stores only one copy of the string.

    One consequence is that you cannot call mktemp with a string constant argument. The function mktemp always alters the string its argument points to.

    Another consequence is that sscanf does not work on some systems when passed a string constant as its format control string or input. This is because sscanf incorrectly tries to write into the string constant. Likewise fscanf and scanf.

    The best solution to these problems is to change the program to use char-array variables with initialization strings for these purposes instead of string constants. But if this is not possible, you can use the -fwritable-strings flag, which directs GCC to handle string constants the same way most C compilers do. -traditional also has this effect, among others.

  • -2147483648 is positive.

    This is because 2147483648 cannot fit in the type int, so (following the ISO C rules) its data type is unsigned long int. Negating this value yields 2147483648 again.

  • GCC does not substitute macro arguments when they appear inside of string constants. For example, the following macro in GCC
    #define foo(a) "a"

    will produce output "a" regardless of what the argument a is.

    The -traditional option directs GCC to handle such cases (among others) in the old-fashioned (non-ISO) fashion.

  • When you use setjmp and longjmp, the only automatic variables guaranteed to remain valid are those declared volatile. This is a consequence of automatic register allocation. Consider this function:
    jmp_buf j;

foo ()
{
  int a, b;

  a = fun1 ();
  if (setjmp (j))
    return a;

  a = fun2 ();
  /* longjmp (j) may occur in fun3. */
  return a + fun3 ();
}

    Here a may or may not be restored to its first value when the longjmp occurs. If a is allocated in a register, then its first value is restored; otherwise, it keeps the last value stored in it.

    If you use the -W option with the -O option, you will get a warning when GCC thinks such a problem might be possible.

    The -traditional option directs GCC to put variables in the stack by default, rather than in registers, in functions that call setjmp. This results in the behavior found in traditional C compilers.

  • Programs that use preprocessing directives in the middle of macro arguments do not work with GCC. For example, a program like this will not work:
    foobar (
#define luser
        hack)

    ISO C does not permit such a construct. It would make sense to support it when -traditional is used, but it is too much work to implement.

  • K&R compilers allow comments to cross over an inclusion boundary (i.e. started in an include file and ended in the including file). I think this would be quite ugly and can't imagine it could be needed.
  • Declarations of external variables and functions within a block apply only to the block containing the declaration. In other words, they have the same scope as any other declaration in the same place.

    In some other C compilers, a extern declaration affects all the rest of the file even if it happens within a block.

    The -traditional option directs GCC to treat all extern declarations as global, like traditional compilers.

  • In traditional C, you can combine long, etc., with a typedef name, as shown here:
    typedef int foo;
typedef long foo bar;

    In ISO C, this is not allowed: long and other type modifiers require an explicit int. Because this criterion is expressed by Bison grammar rules rather than C code, the -traditional flag cannot alter it.

  • PCC allows typedef names to be used as function parameters. The difficulty described immediately above applies here too.
  • When in -traditional mode, GCC allows the following erroneous pair of declarations to appear together in a given scope:
    typedef int foo;
typedef foo foo;
  • GCC treats all characters of identifiers as significant, even when in -traditional mode. According to K&R-1 (2.2), "No more than the first eight characters are significant, although more may be used.". Also according to K&R-1 (2.2), "An identifier is a sequence of letters and digits; the first character must be a letter. The underscore _ counts as a letter.", but GCC also allows dollar signs in identifiers.
  • PCC allows whitespace in the middle of compound assignment operators such as +=. GCC, following the ISO standard, does not allow this. The difficulty described immediately above applies here too.
  • GCC complains about unterminated character constants inside of preprocessing conditionals that fail. Some programs have English comments enclosed in conditionals that are guaranteed to fail; if these comments contain apostrophes, GCC will probably report an error. For example, this code would produce an error:
    #if 0
You can't expect this to work.
#endif

    The best solution to such a problem is to put the text into an actual C comment delimited by /*...*/. However, -traditional suppresses these error messages.

  • Many user programs contain the declaration long time ();. In the past, the system header files on many systems did not actually declare time, so it did not matter what type your program declared it to return. But in systems with ISO C headers, time is declared to return time_t, and if that is not the same as long, then long time (); is erroneous.

    The solution is to change your program to use appropriate system headers (<time.h> on systems with ISO C headers) and not to declare time if the system header files declare it, or failing that to use time_t as the return type of time.

  • When compiling functions that return float, PCC converts it to a double. GCC actually returns a float. If you are concerned with PCC compatibility, you should declare your functions to return double; you might as well say what you mean.
  • When compiling functions that return structures or unions, GCC output code normally uses a method different from that used on most versions of Unix. As a result, code compiled with GCC cannot call a structure-returning function compiled with PCC, and vice versa.

    The method used by GCC is as follows: a structure or union which is 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union with any other size is stored into an address supplied by the caller (usually in a special, fixed register, but on some machines it is passed on the stack). The machine-description macros STRUCT_VALUE and STRUCT_INCOMING_VALUE tell GCC where to pass this address.

    By contrast, PCC on most target machines returns structures and unions of any size by copying the data into an area of static storage, and then returning the address of that storage as if it were a pointer value. The caller must copy the data from that memory area to the place where the value is wanted. GCC does not use this method because it is slower and nonreentrant.

    On some newer machines, PCC uses a reentrant convention for all structure and union returning. GCC on most of these machines uses a compatible convention when returning structures and unions in memory, but still returns small structures and unions in registers.

    You can tell GCC to use a compatible convention for all structure and union returning with the option -fpcc-struct-return.

  • GCC complains about program fragments such as 0x74ae-0x4000 which appear to be two hexadecimal constants separated by the minus operator. Actually, this string is a single preprocessing token. Each such token must correspond to one token in C. Since this does not, GCC prints an error message. Although it may appear obvious that what is meant is an operator and two values, the ISO C standard specifically requires that this be treated as erroneous.

    A preprocessing token is a preprocessing number if it begins with a digit and is followed by letters, underscores, digits, periods and e+, e-, E+, E-, p+, p-, P+, or P- character sequences. (In strict C89 mode, the sequences p+, p-, P+ and P- cannot appear in preprocessing numbers.)

    To make the above program fragment valid, place whitespace in front of the minus sign. This whitespace will end the preprocessing number.


Using the GNU Compiler Collection (GCC)

Node:Incomplete Enums, Next:Function Names, Previous:Alternate Keywords, Up:C Extensions

Incomplete enum Types

You can define an enum tag without specifying its possible values. This results in an incomplete type, much like what you get if you write struct foo without describing the elements. A later declaration which does specify the possible values completes the type.

You can't allocate variables or storage using the type while it is incomplete. However, you can work with pointers to that type.

This extension may not be very useful, but it makes the handling of enum more consistent with the way struct and union are handled.

This extension is not supported by GNU C++.


Using the GNU Compiler Collection (GCC)

Node:Index, Previous:Option Index, Up:Top

Index

  • ! in constraint: Multi-Alternative
  • # in constraint: Modifiers
  • #pragma: Pragmas
  • #pragma implementation: C++ Interface
  • #pragma implementation, implied: C++ Interface
  • #pragma interface: C++ Interface
  • #pragma, reason for not using: Function Attributes
  • $: Dollar Signs
  • % in constraint: Modifiers
  • %include: Spec Files
  • %include_noerr: Spec Files
  • %rename: Spec Files
  • & in constraint: Modifiers
  • ': Incompatibilities
  • * in constraint: Modifiers
  • + in constraint: Modifiers
  • -lgcc, use with -nodefaultlibs: Link Options
  • -lgcc, use with -nostdlib: Link Options
  • -nodefaultlibs and unresolved references: Link Options
  • -nostdlib and unresolved references: Link Options
  • .sdata/.sdata2 references (PowerPC): RS/6000 and PowerPC Options
  • //: C++ Comments
  • 0 in constraint: Simple Constraints
  • < in constraint: Simple Constraints
  • <?: Min and Max
  • = in constraint: Modifiers
  • > in constraint: Simple Constraints
  • >?: Min and Max
  • ? in constraint: Multi-Alternative
  • ?: extensions: Conditionals, Lvalues
  • ?: side effect: Conditionals
  • \a: C Dialect Options
  • \x: C Dialect Options
  • _ in variables in macros: Naming Types
  • __builtin_apply: Constructing Calls
  • __builtin_apply_args: Constructing Calls
  • __builtin_choose_expr: Other Builtins
  • __builtin_constant_p: Other Builtins
  • __builtin_expect: Other Builtins
  • __builtin_frame_address: Return Address
  • __builtin_isgreater: Other Builtins
  • __builtin_isgreaterequal: Other Builtins
  • __builtin_isless: Other Builtins
  • __builtin_islessequal: Other Builtins
  • __builtin_islessgreater: Other Builtins
  • __builtin_isunordered: Other Builtins
  • __builtin_prefetch: Other Builtins
  • __builtin_return: Constructing Calls
  • __builtin_return_address: Return Address
  • __builtin_types_compatible_p: Other Builtins
  • __complex__ keyword: Complex
  • __extension__: Alternate Keywords
  • __func__ identifier: Function Names
  • __FUNCTION__ identifier: Function Names
  • __imag__ keyword: Complex
  • __PRETTY_FUNCTION__ identifier: Function Names
  • __real__ keyword: Complex
  • __STDC_HOSTED__: Standards
  • _Complex keyword: Complex
  • _Exit: Other Builtins
  • _exit: Other Builtins
  • abort: Other Builtins
  • abs: Other Builtins
  • accessing volatiles: Volatiles
  • Ada: G++ and GCC
  • address constraints: Simple Constraints
  • address of a label: Labels as Values
  • address_operand: Simple Constraints
  • alias attribute: Function Attributes
  • aliasing of parameters: Code Gen Options
  • aligned attribute: Type Attributes, Variable Attributes
  • alignment: Alignment
  • Alliant: Interoperation
  • alloca: Other Builtins
  • alloca vs variable-length arrays: Variable Length
  • alternate keywords: Alternate Keywords
  • always_inline function attribute: Function Attributes
  • AMD x86-64 Options: i386 and x86-64 Options
  • AMD1: Standards
  • AMD29K options: AMD29K Options
  • ANSI C: Standards
  • ANSI C standard: Standards
  • ANSI C89: Standards
  • ANSI support: C Dialect Options
  • ANSI X3.159-1989: Standards
  • apostrophes: Incompatibilities
  • ARC Options: ARC Options
  • arguments in frame (88k): M88K Options
  • ARM [Annotated C++ Reference Manual]: Backwards Compatibility
  • ARM options: ARM Options
  • arrays of length zero: Zero Length
  • arrays of variable length: Variable Length
  • arrays, non-lvalue: Subscripting
  • asm constraints: Constraints
  • asm expressions: Extended Asm
  • assembler instructions: Extended Asm
  • assembler names for identifiers: Asm Labels
  • assembler syntax, 88k: M88K Options
  • assembly code, invalid: Bug Criteria
  • attribute of types: Type Attributes
  • attribute of variables: Variable Attributes
  • attribute syntax: Attribute Syntax
  • autoincrement/decrement addressing: Simple Constraints
  • automatic inline for C++ member fns: Inline
  • AVR Options: AVR Options
  • backtrace for bug reports: Bug Reporting
  • Backwards Compatibility: Backwards Compatibility
  • bcmp: Other Builtins
  • bit shift overflow (88k): M88K Options
  • bound pointer to member function: Bound member functions
  • bug criteria: Bug Criteria
  • bug report mailing lists: Bug Lists
  • bugs: Bugs
  • bugs, known: Trouble
  • built-in functions: Other Builtins, C Dialect Options
  • byte writes (29k): AMD29K Options
  • bzero: Other Builtins
  • C compilation options: Invoking GCC
  • C intermediate output, nonexistent: G++ and GCC
  • C language extensions: C Extensions
  • C language, traditional: C Dialect Options
  • C standard: Standards
  • C standards: Standards
  • c++: Invoking G++
  • C++: G++ and GCC
  • C++ comments: C++ Comments
  • C++ compilation options: Invoking GCC
  • C++ interface and implementation headers: C++ Interface
  • C++ language extensions: C++ Extensions
  • C++ member fns, automatically inline: Inline
  • C++ misunderstandings: C++ Misunderstandings
  • C++ options, command line: C++ Dialect Options
  • C++ pragmas, effect on inlining: C++ Interface
  • C++ source file suffixes: Invoking G++
  • C++ static data, declaring and defining: Static Definitions
  • C89: Standards
  • C90: Standards
  • C94: Standards
  • C95: Standards
  • C99: Standards
  • C9X: Standards
  • C_INCLUDE_PATH: Environment Variables
  • calling functions through the function vector on the H8/300 processors: Function Attributes
  • case labels in initializers: Designated Inits
  • case ranges: Case Ranges
  • case sensitivity and VMS: VMS Misc
  • cast to a union: Cast to Union
  • casts as lvalues: Lvalues
  • cimag: Other Builtins
  • cimagf: Other Builtins
  • cimagl: Other Builtins
  • code generation conventions: Code Gen Options
  • code, mixed with declarations: Mixed Declarations
  • command options: Invoking GCC
  • comments, C++ style: C++ Comments
  • comparison of signed and unsigned values, warning: Warning Options
  • compiler bugs, reporting: Bug Reporting
  • compiler compared to C++ preprocessor: G++ and GCC
  • compiler options, C++: C++ Dialect Options
  • compiler options, Objective-C: Objective-C Dialect Options
  • compiler version, specifying: Target Options
  • COMPILER_PATH: Environment Variables
  • complex conjugation: Complex
  • complex numbers: Complex
  • compound expressions as lvalues: Lvalues
  • compound literals: Compound Literals
  • computed gotos: Labels as Values
  • conditional expressions as lvalues: Lvalues
  • conditional expressions, extensions: Conditionals
  • conflicting types: Disappointments
  • conj: Other Builtins
  • conjf: Other Builtins
  • conjl: Other Builtins
  • const applied to function: Function Attributes
  • const function attribute: Function Attributes
  • constants in constraints: Simple Constraints
  • constraint modifier characters: Modifiers
  • constraint, matching: Simple Constraints
  • constraints, asm: Constraints
  • constraints, machine specific: Machine Constraints
  • constructing calls: Constructing Calls
  • constructor expressions: Compound Literals
  • constructor function attribute: Function Attributes
  • contributors: Contributors
  • Convex options: Convex Options
  • core dump: Bug Criteria
  • cos: Other Builtins
  • cosf: Other Builtins
  • cosl: Other Builtins
  • CPATH: Environment Variables
  • CPLUS_INCLUDE_PATH: Environment Variables
  • creal: Other Builtins
  • crealf: Other Builtins
  • creall: Other Builtins
  • CRIS Options: CRIS Options
  • cross compiling: Target Options
  • D30V Options: D30V Options
  • DBX: Interoperation
  • deallocating variable length arrays: Variable Length
  • debug_rtx: Bug Reporting
  • debugging information options: Debugging Options
  • debugging, 88k OCS: M88K Options
  • declaration scope: Incompatibilities
  • declarations inside expressions: Statement Exprs
  • declarations, mixed with code: Mixed Declarations
  • declaring attributes of functions: Function Attributes
  • declaring static data in C++: Static Definitions
  • defining static data in C++: Static Definitions
  • dependencies for make as output: Environment Variables
  • dependencies, make: Preprocessor Options
  • DEPENDENCIES_OUTPUT: Environment Variables
  • deprecated attribute.: Function Attributes
  • designated initializers: Designated Inits
  • designator lists: Designated Inits
  • designators: Designated Inits
  • destructor function attribute: Function Attributes
  • diagnostic messages: Language Independent Options
  • dialect options: C Dialect Options
  • digits in constraint: Simple Constraints
  • directory options: Directory Options
  • divide instruction, 88k: M88K Options
  • dollar signs in identifier names: Dollar Signs
  • double-word arithmetic: Long Long
  • downward funargs: Nested Functions
  • DW bit (29k): AMD29K Options
  • E in constraint: Simple Constraints
  • earlyclobber operand: Modifiers
  • eight bit data on the H8/300 and H8/300H: Function Attributes
  • environment variables: Environment Variables
  • error messages: Warnings and Errors
  • escape sequences, traditional: C Dialect Options
  • escaped newlines: Escaped Newlines
  • exclamation point: Multi-Alternative
  • exit: Other Builtins
  • exit status and VMS: VMS Misc
  • explicit register variables: Explicit Reg Vars
  • expressions containing statements: Statement Exprs
  • expressions, compound, as lvalues: Lvalues
  • expressions, conditional, as lvalues: Lvalues
  • expressions, constructor: Compound Literals
  • extended asm: Extended Asm
  • extensible constraints: Simple Constraints
  • extensions, ?:: Conditionals, Lvalues
  • extensions, C language: C Extensions
  • extensions, C++ language: C++ Extensions
  • external declaration scope: Incompatibilities
  • F in constraint: Simple Constraints
  • fabs: Other Builtins
  • fabsf: Other Builtins
  • fabsl: Other Builtins
  • fatal signal: Bug Criteria
  • FDL, GNU Free Documentation License: GNU Free Documentation License
  • ffs: Other Builtins
  • file name suffix: Overall Options
  • file names: Link Options
  • flexible array members: Zero Length
  • float as function value type: Incompatibilities
  • floating point precision: Disappointments, Optimize Options
  • format function attribute: Function Attributes
  • format_arg function attribute: Function Attributes
  • Fortran: G++ and GCC
  • forwarding calls: Constructing Calls
  • fprintf: Other Builtins
  • fprintf_unlocked: Other Builtins
  • fputs: Other Builtins
  • fputs_unlocked: Other Builtins
  • freestanding environment: Standards
  • freestanding implementation: Standards
  • fscanf, and constant strings: Incompatibilities
  • function addressability on the M32R/D: Function Attributes
  • function attributes: Function Attributes
  • function pointers, arithmetic: Pointer Arith
  • function prototype declarations: Function Prototypes
  • function without a prologue/epilogue code: Function Attributes
  • function, size of pointer to: Pointer Arith
  • functions called via pointer on the RS/6000 and PowerPC: Function Attributes
  • functions in arbitrary sections: Function Attributes
  • functions that are passed arguments in registers on the 386: Function Attributes
  • functions that behave like malloc: Function Attributes
  • functions that do not pop the argument stack on the 386: Function Attributes
  • functions that do pop the argument stack on the 386: Function Attributes
  • functions that have no side effects: Function Attributes
  • functions that never return: Function Attributes
  • functions that pop the argument stack on the 386: Function Attributes
  • functions which are exported from a dll on PowerPC Windows NT: Function Attributes
  • functions which are imported from a dll on PowerPC Windows NT: Function Attributes
  • functions which specify exception handling on PowerPC Windows NT: Function Attributes
  • functions with printf, scanf, strftime or strfmon style arguments: Function Attributes
  • g in constraint: Simple Constraints
  • G in constraint: Simple Constraints
  • g++: Invoking G++
  • G++: G++ and GCC
  • GCC: G++ and GCC
  • GCC command options: Invoking GCC
  • gcc-bugs@gcc.gnu.org or bug-gcc@gnu.org: Bug Lists
  • GCC_EXEC_PREFIX: Environment Variables
  • gccbug script: gccbug
  • generalized lvalues: Lvalues
  • global offset table: Code Gen Options
  • global register after longjmp: Global Reg Vars
  • global register variables: Global Reg Vars
  • GLOBALDEF: Global Declarations
  • GLOBALREF: Global Declarations
  • GLOBALVALUEDEF: Global Declarations
  • GLOBALVALUEREF: Global Declarations
  • GNAT: G++ and GCC
  • goto with computed label: Labels as Values
  • gp-relative references (MIPS): MIPS Options
  • gprof: Debugging Options
  • grouping options: Invoking GCC
  • H in constraint: Simple Constraints
  • hardware models and configurations, specifying: Submodel Options
  • header files and VMS: Include Files and VMS
  • hex floats: Hex Floats
  • hosted environment: C Dialect Options, Standards
  • hosted implementation: Standards
  • HPPA Options: HPPA Options
  • I in constraint: Simple Constraints
  • i in constraint: Simple Constraints
  • i386 Options: i386 and x86-64 Options
  • IA-64 Options: IA-64 Options
  • IBM RS/6000 and PowerPC Options: RS/6000 and PowerPC Options
  • IBM RT options: RT Options
  • IBM RT PC: Interoperation
  • identifier names, dollar signs in: Dollar Signs
  • identifiers, names in assembler code: Asm Labels
  • identifying source, compiler (88k): M88K Options
  • imaxabs: Other Builtins
  • implementation-defined behavior, C language: C Implementation
  • implied #pragma implementation: C++ Interface
  • include files and VMS: Include Files and VMS
  • incompatibilities of GCC: Incompatibilities
  • increment operators: Bug Criteria
  • index: Other Builtins
  • indirect calls on ARM: Function Attributes
  • init_priority attribute: C++ Attributes
  • initializations in expressions: Compound Literals
  • initializers with labeled elements: Designated Inits
  • initializers, non-constant: Initializers
  • inline automatic for C++ member fns: Inline
  • inline functions: Inline
  • inline functions, omission of: Inline
  • inlining and C++ pragmas: C++ Interface
  • installation trouble: Trouble
  • integrating function code: Inline
  • Intel 386 Options: i386 and x86-64 Options
  • interface and implementation headers, C++: C++ Interface
  • intermediate C version, nonexistent: G++ and GCC
  • interrupt handler functions: Function Attributes
  • interrupt handler functions on the H8/300 and SH processors: Function Attributes
  • introduction: Top
  • invalid assembly code: Bug Criteria
  • invalid input: Bug Criteria
  • invoking g++: Invoking G++
  • ISO 9899: Standards
  • ISO C: Standards
  • ISO C standard: Standards
  • ISO C89: Standards
  • ISO C90: Standards
  • ISO C94: Standards
  • ISO C95: Standards
  • ISO C99: Standards
  • ISO C9X: Standards
  • ISO support: C Dialect Options
  • ISO/IEC 9899: Standards
  • Java: G++ and GCC
  • java_interface attribute: C++ Attributes
  • kernel and user registers (29k): AMD29K Options
  • keywords, alternate: Alternate Keywords
  • known causes of trouble: Trouble
  • labeled elements in initializers: Designated Inits
  • labels as values: Labels as Values
  • labs: Other Builtins
  • LANG: Environment Variables
  • language dialect options: C Dialect Options
  • large bit shifts (88k): M88K Options
  • LC_ALL: Environment Variables
  • LC_CTYPE: Environment Variables
  • LC_MESSAGES: Environment Variables
  • length-zero arrays: Zero Length
  • Libraries: Link Options
  • LIBRARY_PATH: Environment Variables
  • link options: Link Options
  • LL integer suffix: Long Long
  • llabs: Other Builtins
  • load address instruction: Simple Constraints
  • local labels: Local Labels
  • local variables in macros: Naming Types
  • local variables, specifying registers: Local Reg Vars
  • locale: Environment Variables
  • locale definition: Environment Variables
  • long long data types: Long Long
  • longjmp: Global Reg Vars
  • longjmp and automatic variables: C Dialect Options
  • longjmp incompatibilities: Incompatibilities
  • longjmp warnings: Warning Options
  • lvalues, generalized: Lvalues
  • m in constraint: Simple Constraints
  • M32R/D options: M32R/D Options
  • M680x0 options: M680x0 Options
  • M68hc1x options: M68hc1x Options
  • M88k options: M88K Options
  • machine dependent options: Submodel Options
  • machine specific constraints: Machine Constraints
  • macro with variable arguments: Variadic Macros
  • macros containing asm: Extended Asm
  • macros, inline alternative: Inline
  • macros, local labels: Local Labels
  • macros, local variables in: Naming Types
  • macros, statements in expressions: Statement Exprs
  • macros, types of arguments: Typeof
  • main and the exit status: VMS Misc
  • make: Preprocessor Options
  • malloc attribute: Function Attributes
  • matching constraint: Simple Constraints
  • maximum operator: Min and Max
  • MCore options: MCore Options
  • member fns, automatically inline: Inline
  • memcmp: Other Builtins
  • memcpy: Other Builtins
  • memory model (29k): AMD29K Options
  • memory references in constraints: Simple Constraints
  • memset: Other Builtins
  • message formatting: Language Independent Options
  • messages, warning: Warning Options
  • messages, warning and error: Warnings and Errors
  • middle-operands, omitted: Conditionals
  • minimum operator: Min and Max
  • MIPS options: MIPS Options
  • misunderstandings in C++: C++ Misunderstandings
  • mixed declarations and code: Mixed Declarations
  • mktemp, and constant strings: Incompatibilities
  • MMIX Options: MMIX Options
  • MN10200 options: MN10200 Options
  • MN10300 options: MN10300 Options
  • mode attribute: Variable Attributes
  • modifiers in constraints: Modifiers
  • multi-line string literals: Multi-line Strings
  • multiple alternative constraints: Multi-Alternative
  • multiprecision arithmetic: Long Long
  • n in constraint: Simple Constraints
  • name augmentation: VMS Misc
  • names used in assembler code: Asm Labels
  • naming convention, implementation headers: C++ Interface
  • naming types: Naming Types
  • nested functions: Nested Functions
  • newlines (escaped): Escaped Newlines
  • no_instrument_function function attribute: Function Attributes
  • nocommon attribute: Variable Attributes
  • noinline function attribute: Function Attributes
  • non-constant initializers: Initializers
  • non-static inline function: Inline
  • noreturn function attribute: Function Attributes
  • NS32K options: NS32K Options
  • o in constraint: Simple Constraints
  • OBJC_INCLUDE_PATH: Environment Variables
  • Objective-C: G++ and GCC
  • Objective-C options, command line: Objective-C Dialect Options
  • OCS (88k): M88K Options
  • offsettable address: Simple Constraints
  • old-style function definitions: Function Prototypes
  • omitted middle-operands: Conditionals
  • open coding: Inline
  • operand constraints, asm: Constraints
  • optimize options: Optimize Options
  • options to control diagnostics formatting: Language Independent Options
  • options to control warnings: Warning Options
  • options, C++: C++ Dialect Options
  • options, code generation: Code Gen Options
  • options, debugging: Debugging Options
  • options, dialect: C Dialect Options
  • options, directory search: Directory Options
  • options, GCC command: Invoking GCC
  • options, grouping: Invoking GCC
  • options, linking: Link Options
  • options, Objective-C: Objective-C Dialect Options
  • options, optimization: Optimize Options
  • options, order: Invoking GCC
  • options, preprocessor: Preprocessor Options
  • order of evaluation, side effects: Non-bugs
  • order of options: Invoking GCC
  • other register constraints: Simple Constraints
  • output file option: Overall Options
  • overloaded virtual fn, warning: C++ Dialect Options
  • p in constraint: Simple Constraints
  • packed attribute: Variable Attributes
  • parameter forward declaration: Variable Length
  • parameters, aliased: Code Gen Options
  • PDP-11 Options: PDP-11 Options
  • PIC: Code Gen Options
  • pmf: Bound member functions
  • pointer arguments: Function Attributes
  • pointer to member function: Bound member functions
  • portions of temporary objects, pointers to: Temporaries
  • pragma, extern_prefix: Tru64 Pragmas
  • pragma, long_calls: ARM Pragmas
  • pragma, long_calls_off: ARM Pragmas
  • pragma, mark: Darwin Pragmas
  • pragma, no_long_calls: ARM Pragmas
  • pragma, options align: Darwin Pragmas
  • pragma, reason for not using: Function Attributes
  • pragma, redefine_extname: Solaris Pragmas
  • pragma, segment: Darwin Pragmas
  • pragma, unused: Darwin Pragmas
  • pragmas: Pragmas
  • pragmas in C++, effect on inlining: C++ Interface
  • pragmas, interface and implementation: C++ Interface
  • pragmas, warning of unknown: Warning Options
  • preprocessing numbers: Incompatibilities
  • preprocessing tokens: Incompatibilities
  • preprocessor options: Preprocessor Options
  • printf: Other Builtins
  • printf_unlocked: Other Builtins
  • processor selection (29k): AMD29K Options
  • prof: Debugging Options
  • promotion of formal parameters: Function Prototypes
  • pure function attribute: Function Attributes
  • push address instruction: Simple Constraints
  • qsort, and global register variables: Global Reg Vars
  • question mark: Multi-Alternative
  • r in constraint: Simple Constraints
  • r0-relative references (88k): M88K Options
  • ranges in case statements: Case Ranges
  • read-only strings: Incompatibilities
  • register positions in frame (88k): M88K Options
  • register variable after longjmp: Global Reg Vars
  • registers: Extended Asm
  • registers for local variables: Local Reg Vars
  • registers in constraints: Simple Constraints
  • registers, global allocation: Explicit Reg Vars
  • registers, global variables in: Global Reg Vars
  • reordering, warning: Warning Options, C++ Dialect Options
  • reporting bugs: Bugs
  • rest argument (in macro): Variadic Macros
  • restricted pointers: Restricted Pointers
  • restricted references: Restricted Pointers
  • restricted this pointer: Restricted Pointers
  • return value of main: VMS Misc
  • rindex: Other Builtins
  • RS/6000 and PowerPC Options: RS/6000 and PowerPC Options
  • RT options: RT Options
  • RT PC: Interoperation
  • RTTI: Vague Linkage
  • run-time options: Code Gen Options
  • s in constraint: Simple Constraints
  • S/390 and zSeries Options: S/390 and zSeries Options
  • scanf, and constant strings: Incompatibilities
  • scope of a variable length array: Variable Length
  • scope of declaration: Disappointments
  • scope of external declarations: Incompatibilities
  • search path: Directory Options
  • section function attribute: Function Attributes
  • section variable attribute: Variable Attributes
  • sequential consistency on 88k: M88K Options
  • setjmp: Global Reg Vars
  • setjmp incompatibilities: Incompatibilities
  • shared strings: Incompatibilities
  • shared variable attribute: Variable Attributes
  • shared VMS run time system: VMS Misc
  • side effect in ?:: Conditionals
  • side effects, macro argument: Statement Exprs
  • side effects, order of evaluation: Non-bugs
  • signal handler functions on the AVR processors: Function Attributes
  • signed and unsigned values, comparison warning: Warning Options
  • simple constraints: Simple Constraints
  • sin: Other Builtins
  • sinf: Other Builtins
  • sinl: Other Builtins
  • sizeof: Typeof
  • smaller data references: M32R/D Options
  • smaller data references (88k): M88K Options
  • smaller data references (MIPS): MIPS Options
  • smaller data references (PowerPC): RS/6000 and PowerPC Options
  • SPARC options: SPARC Options
  • Spec Files: Spec Files
  • specified registers: Explicit Reg Vars
  • specifying compiler version and target machine: Target Options
  • specifying hardware config: Submodel Options
  • specifying machine version: Target Options
  • specifying registers for local variables: Local Reg Vars
  • sqrt: Other Builtins
  • sqrtf: Other Builtins
  • sqrtl: Other Builtins
  • sscanf, and constant strings: Incompatibilities
  • stack checks (29k): AMD29K Options
  • statements inside expressions: Statement Exprs
  • static data in C++, declaring and defining: Static Definitions
  • stdarg.h and RT PC: RT Options
  • storem bug (29k): AMD29K Options
  • strcat: Other Builtins
  • strchr: Other Builtins
  • strcmp: Other Builtins
  • strcpy: Other Builtins
  • strcspn: Other Builtins
  • string constants: Incompatibilities
  • strlen: Other Builtins
  • strncat: Other Builtins
  • strncmp: Other Builtins
  • strncpy: Other Builtins
  • strpbrk: Other Builtins
  • strrchr: Other Builtins
  • strspn: Other Builtins
  • strstr: Other Builtins
  • struct: Unnamed Fields
  • structure passing (88k): M88K Options
  • structures: Incompatibilities
  • structures, constructor expression: Compound Literals
  • submodel options: Submodel Options
  • subscripting: Subscripting
  • subscripting and function values: Subscripting
  • suffixes for C++ source: Invoking G++
  • SUNPRO_DEPENDENCIES: Environment Variables
  • suppressing warnings: Warning Options
  • surprises in C++: C++ Misunderstandings
  • SVr4: M88K Options
  • syntax checking: Warning Options
  • synthesized methods, warning: C++ Dialect Options
  • system headers, warnings from: Warning Options
  • target machine, specifying: Target Options
  • target options: Target Options
  • TC1: Standards
  • TC2: Standards
  • tcov: Debugging Options
  • Technical Corrigenda: Standards
  • Technical Corrigendum 1: Standards
  • Technical Corrigendum 2: Standards
  • template instantiation: Template Instantiation
  • temporaries, lifetime of: Temporaries
  • thunks: Nested Functions
  • tiny data section on the H8/300H: Function Attributes
  • TMPDIR: Environment Variables
  • TMS320C3x/C4x Options: TMS320C3x/C4x Options
  • traditional C language: C Dialect Options
  • type alignment: Alignment
  • type attributes: Type Attributes
  • type_info: Vague Linkage
  • typedef names as function parameters: Incompatibilities
  • typeof: Typeof
  • ULL integer suffix: Long Long
  • Ultrix calling convention: Interoperation
  • undefined behavior: Bug Criteria
  • undefined function value: Bug Criteria
  • underscores in variables in macros: Naming Types
  • underscores, avoiding (88k): M88K Options
  • union: Unnamed Fields
  • union, casting to a: Cast to Union
  • unions: Incompatibilities
  • unknown pragmas, warning: Warning Options
  • unresolved references and -nodefaultlibs: Link Options
  • unresolved references and -nostdlib: Link Options
  • unused attribute.: Function Attributes
  • used attribute.: Function Attributes
  • V in constraint: Simple Constraints
  • V850 Options: V850 Options
  • vague linkage: Vague Linkage
  • value after longjmp: Global Reg Vars
  • varargs.h and RT PC: RT Options
  • variable addressability on the M32R/D: Variable Attributes
  • variable alignment: Alignment
  • variable attributes: Variable Attributes
  • variable number of arguments: Variadic Macros
  • variable-length array scope: Variable Length
  • variable-length arrays: Variable Length
  • variables in specified registers: Explicit Reg Vars
  • variables, local, in macros: Naming Types
  • variadic macros: Variadic Macros
  • VAX calling convention: Interoperation
  • VAX options: VAX Options
  • VAXCRTL: VMS Misc
  • VLAs: Variable Length
  • VMS and case sensitivity: VMS Misc
  • VMS and include files: Include Files and VMS
  • void pointers, arithmetic: Pointer Arith
  • void, size of pointer to: Pointer Arith
  • volatile access: Volatiles
  • volatile applied to function: Function Attributes
  • volatile read: Volatiles
  • volatile write: Volatiles
  • vtable: Vague Linkage
  • warning for comparison of signed and unsigned values: Warning Options
  • warning for overloaded virtual fn: C++ Dialect Options
  • warning for reordering of member initializers: Warning Options, C++ Dialect Options
  • warning for synthesized methods: C++ Dialect Options
  • warning for unknown pragmas: Warning Options
  • warning messages: Warning Options
  • warnings from system headers: Warning Options
  • warnings vs errors: Warnings and Errors
  • weak attribute: Function Attributes
  • whitespace: Incompatibilities
  • X in constraint: Simple Constraints
  • X3.159-1989: Standards
  • x86-64 Options: i386 and x86-64 Options
  • Xstormy16 Options: Xstormy16 Options
  • Xtensa Options: Xtensa Options
  • zero division on 88k: M88K Options
  • zero-length arrays: Zero Length


Using the GNU Compiler Collection (GCC)

Node:Initializers, Next:Compound Literals, Previous:Pointer Arith, Up:C Extensions

Non-Constant Initializers

As in standard C++ and ISO C99, the elements of an aggregate initializer for an automatic variable are not required to be constant expressions in GNU C. Here is an example of an initializer with run-time varying elements:

foo (float f, float g)
{
  float beat_freqs[2] = { f-g, f+g };
  ...
}


Using the GNU Compiler Collection (GCC)

Node:Inline, Next:Extended Asm, Previous:Alignment, Up:C Extensions

An Inline Function is As Fast As a Macro

By declaring a function inline, you can direct GCC to integrate that function's code into the code for its callers. This makes execution faster by eliminating the function-call overhead; in addition, if any of the actual argument values are constant, their known values may permit simplifications at compile time so that not all of the inline function's code needs to be included. The effect on code size is less predictable; object code may be larger or smaller with function inlining, depending on the particular case. Inlining of functions is an optimization and it really "works" only in optimizing compilation. If you don't use -O, no function is really inline.

Inline functions are included in the ISO C99 standard, but there are currently substantial differences between what GCC implements and what the ISO C99 standard requires.

To declare a function inline, use the inline keyword in its declaration, like this:

inline int
inc (int *a)
{
  (*a)++;
}

(If you are writing a header file to be included in ISO C programs, write __inline__ instead of inline. See Alternate Keywords.) You can also make all "simple enough" functions inline with the option -finline-functions.

Note that certain usages in a function definition can make it unsuitable for inline substitution. Among these usages are: use of varargs, use of alloca, use of variable sized data types (see Variable Length), use of computed goto (see Labels as Values), use of nonlocal goto, and nested functions (see Nested Functions). Using -Winline will warn when a function marked inline could not be substituted, and will give the reason for the failure.

Note that in C and Objective-C, unlike C++, the inline keyword does not affect the linkage of the function.

GCC automatically inlines member functions defined within the class body of C++ programs even if they are not explicitly declared inline. (You can override this with -fno-default-inline; see Options Controlling C++ Dialect.)

When a function is both inline and static, if all calls to the function are integrated into the caller, and the function's address is never used, then the function's own assembler code is never referenced. In this case, GCC does not actually output assembler code for the function, unless you specify the option -fkeep-inline-functions. Some calls cannot be integrated for various reasons (in particular, calls that precede the function's definition cannot be integrated, and neither can recursive calls within the definition). If there is a nonintegrated call, then the function is compiled to assembler code as usual. The function must also be compiled as usual if the program refers to its address, because that can't be inlined.

When an inline function is not static, then the compiler must assume that there may be calls from other source files; since a global symbol can be defined only once in any program, the function must not be defined in the other source files, so the calls therein cannot be integrated. Therefore, a non-static inline function is always compiled on its own in the usual fashion.

If you specify both inline and extern in the function definition, then the definition is used only for inlining. In no case is the function compiled on its own, not even if you refer to its address explicitly. Such an address becomes an external reference, as if you had only declared the function, and had not defined it.

This combination of inline and extern has almost the effect of a macro. The way to use it is to put a function definition in a header file with these keywords, and put another copy of the definition (lacking inline and extern) in a library file. The definition in the header file will cause most calls to the function to be inlined. If any uses of the function remain, they will refer to the single copy in the library.

For future compatibility with when GCC implements ISO C99 semantics for inline functions, it is best to use static inline only. (The existing semantics will remain available when -std=gnu89 is specified, but eventually the default will be -std=gnu99 and that will implement the C99 semantics, though it does not do so yet.)

GCC does not inline any functions when not optimizing unless you specify the always_inline attribute for the function, like this:

/* Prototype.  */
inline void foo (const char) __attribute__((always_inline));


Using the GNU Compiler Collection (GCC)

Node:Integers implementation, Next:Floating point implementation, Previous:Characters implementation, Up:C Implementation

Integers

  • Any extended integer types that exist in the implementation (6.2.5).
  • Whether signed integer types are represented using sign and magnitude, two's complement, or one's complement, and whether the extraordinary value is a trap representation or an ordinary value (6.2.6.2).
  • The rank of any extended integer type relative to another extended integer type with the same precision (6.3.1.1).
  • The result of, or the signal raised by, converting an integer to a signed integer type when the value cannot be represented in an object of that type (6.3.1.3).
  • The results of some bitwise operations on signed integers (6.5).


Using the GNU Compiler Collection (GCC)

Node:Intel 960 Options, Next:DEC Alpha Options, Previous:HPPA Options, Up:Submodel Options

Intel 960 Options

These -m options are defined for the Intel 960 implementations:

-mcpu-type
Assume the defaults for the machine type cpu-type for some of the other options, including instruction scheduling, floating point support, and addressing modes. The choices for cpu-type are ka, kb, mc, ca, cf, sa, and sb. The default is kb.
-mnumerics
-msoft-float
The -mnumerics option indicates that the processor does support floating-point instructions. The -msoft-float option indicates that floating-point support should not be assumed.
-mleaf-procedures
-mno-leaf-procedures
Do (or do not) attempt to alter leaf procedures to be callable with the bal instruction as well as call. This will result in more efficient code for explicit calls when the bal instruction can be substituted by the assembler or linker, but less efficient code in other cases, such as calls via function pointers, or using a linker that doesn't support this optimization.
-mtail-call
-mno-tail-call
Do (or do not) make additional attempts (beyond those of the machine-independent portions of the compiler) to optimize tail-recursive calls into branches. You may not want to do this because the detection of cases where this is not valid is not totally complete. The default is -mno-tail-call.
-mcomplex-addr
-mno-complex-addr
Assume (or do not assume) that the use of a complex addressing mode is a win on this implementation of the i960. Complex addressing modes may not be worthwhile on the K-series, but they definitely are on the C-series. The default is currently -mcomplex-addr for all processors except the CB and CC.
-mcode-align
-mno-code-align
Align code to 8-byte boundaries for faster fetching (or don't bother). Currently turned on by default for C-series implementations only.
-mic-compat
-mic2.0-compat
-mic3.0-compat
Enable compatibility with iC960 v2.0 or v3.0.
-masm-compat
-mintel-asm
Enable compatibility with the iC960 assembler.
-mstrict-align
-mno-strict-align
Do not permit (do permit) unaligned accesses.
-mold-align
Enable structure-alignment compatibility with Intel's gcc release version 1.3 (based on gcc 1.37). This option implies -mstrict-align.
-mlong-double-64
Implement type long double as 64-bit floating point numbers. Without the option long double is implemented by 80-bit floating point numbers. The only reason we have it because there is no 128-bit long double support in fp-bit.c yet. So it is only useful for people using soft-float targets. Otherwise, we should recommend against use of it.


Using the GNU Compiler Collection (GCC)

Node:Interoperation, Next:External Bugs, Previous:Cross-Compiler Problems, Up:Trouble

Interoperation

This section lists various difficulties encountered in using GCC together with other compilers or with the assemblers, linkers, libraries and debuggers on certain systems.

  • G++ does not do name mangling in the same way as other C++ compilers. This means that object files compiled with one compiler cannot be used with another.

    This effect is intentional, to protect you from more subtle problems. Compilers differ as to many internal details of C++ implementation, including: how class instances are laid out, how multiple inheritance is implemented, and how virtual function calls are handled. If the name encoding were made the same, your programs would link against libraries provided from other compilers--but the programs would then crash when run. Incompatible libraries are then detected at link time, rather than at run time.

  • Older GDB versions sometimes fail to read the output of GCC version 2. If you have trouble, get GDB version 4.4 or later.
  • DBX rejects some files produced by GCC, though it accepts similar constructs in output from PCC. Until someone can supply a coherent description of what is valid DBX input and what is not, there is nothing I can do about these problems. You are on your own.
  • The GNU assembler (GAS) does not support PIC. To generate PIC code, you must use some other assembler, such as /bin/as.
  • On some BSD systems, including some versions of Ultrix, use of profiling causes static variable destructors (currently used only in C++) not to be run.
  • On some SGI systems, when you use -lgl_s as an option, it gets translated magically to -lgl_s -lX11_s -lc_s. Naturally, this does not happen when you use GCC. You must specify all three options explicitly.
  • On a Sparc, GCC aligns all values of type double on an 8-byte boundary, and it expects every double to be so aligned. The Sun compiler usually gives double values 8-byte alignment, with one exception: function arguments of type double may not be aligned.

    As a result, if a function compiled with Sun CC takes the address of an argument of type double and passes this pointer of type double * to a function compiled with GCC, dereferencing the pointer may cause a fatal signal.

    One way to solve this problem is to compile your entire program with GCC. Another solution is to modify the function that is compiled with Sun CC to copy the argument into a local variable; local variables are always properly aligned. A third solution is to modify the function that uses the pointer to dereference it via the following function access_double instead of directly with *:

    inline double
access_double (double *unaligned_ptr)
{
  union d2i { double d; int i[2]; };

  union d2i *p = (union d2i *) unaligned_ptr;
  union d2i u;

  u.i[0] = p->i[0];
  u.i[1] = p->i[1];

  return u.d;
}

    Storing into the pointer can be done likewise with the same union.

  • On Solaris, the malloc function in the libmalloc.a library may allocate memory that is only 4 byte aligned. Since GCC on the Sparc assumes that doubles are 8 byte aligned, this may result in a fatal signal if doubles are stored in memory allocated by the libmalloc.a library.

    The solution is to not use the libmalloc.a library. Use instead malloc and related functions from libc.a; they do not have this problem.

  • Sun forgot to include a static version of libdl.a with some versions of SunOS (mainly 4.1). This results in undefined symbols when linking static binaries (that is, if you use -static). If you see undefined symbols _dlclose, _dlsym or _dlopen when linking, compile and link against the file mit/util/misc/dlsym.c from the MIT version of X windows.
  • The 128-bit long double format that the Sparc port supports currently works by using the architecturally defined quad-word floating point instructions. Since there is no hardware that supports these instructions they must be emulated by the operating system. Long doubles do not work in Sun OS versions 4.0.3 and earlier, because the kernel emulator uses an obsolete and incompatible format. Long doubles do not work in Sun OS version 4.1.1 due to a problem in a Sun library. Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC does not enable them by default. Long doubles appear to work in Sun OS 5.x (Solaris 2.x).
  • On HP-UX version 9.01 on the HP PA, the HP compiler cc does not compile GCC correctly. We do not yet know why. However, GCC compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can compile itself properly on 9.01.
  • On the HP PA machine, ADB sometimes fails to work on functions compiled with GCC. Specifically, it fails to work on functions that use alloca or variable-size arrays. This is because GCC doesn't generate HP-UX unwind descriptors for such functions. It may even be impossible to generate them.
  • Debugging (-g) is not supported on the HP PA machine, unless you use the preliminary GNU tools.
  • Taking the address of a label may generate errors from the HP-UX PA assembler. GAS for the PA does not have this problem.
  • Using floating point parameters for indirect calls to static functions will not work when using the HP assembler. There simply is no way for GCC to specify what registers hold arguments for static functions when using the HP assembler. GAS for the PA does not have this problem.
  • In extremely rare cases involving some very large functions you may receive errors from the HP linker complaining about an out of bounds unconditional branch offset. This used to occur more often in previous versions of GCC, but is now exceptionally rare. If you should run into it, you can work around by making your function smaller.
  • GCC compiled code sometimes emits warnings from the HP-UX assembler of the form:
    (warning) Use of GR3 when
  frame >= 8192 may cause conflict.

    These warnings are harmless and can be safely ignored.

  • On the IBM RS/6000, compiling code of the form
    extern int foo;

... foo ...

static int foo;

    will cause the linker to report an undefined symbol foo. Although this behavior differs from most other systems, it is not a bug because redefining an extern variable as static is undefined in ISO C.

  • In extremely rare cases involving some very large functions you may receive errors from the AIX Assembler complaining about a displacement that is too large. If you should run into it, you can work around by making your function smaller.
  • The libstdc++.a library in GCC relies on the SVR4 dynamic linker semantics which merges global symbols between libraries and applications, especially necessary for C++ streams functionality. This is not the default behavior of AIX shared libraries and dynamic linking. libstdc++.a is built on AIX with "runtime-linking" enabled so that symbol merging can occur. To utilize this feature, the application linked with libstdc++.a must include the -Wl,-brtl flag on the link line. G++ cannot impose this because this option may interfere with the semantics of the user program and users may not always use g++ to link his or her application. Applications are not required to use the -Wl,-brtl flag on the link line--the rest of the libstdc++.a library which is not dependent on the symbol merging semantics will continue to function correctly.
  • An application can interpose its own definition of functions for functions invoked by libstdc++.a with "runtime-linking" enabled on AIX. To accomplish this the application must be linked with "runtime-linking" option and the functions explicitly must be exported by the application (-Wl,-brtl,-bE:exportfile).
  • AIX on the RS/6000 provides support (NLS) for environments outside of the United States. Compilers and assemblers use NLS to support locale-specific representations of various objects including floating-point numbers (. vs , for separating decimal fractions). There have been problems reported where the library linked with GCC does not produce the same floating-point formats that the assembler accepts. If you have this problem, set the LANG environment variable to C or En_US.
  • Even if you specify -fdollars-in-identifiers, you cannot successfully use $ in identifiers on the RS/6000 due to a restriction in the IBM assembler. GAS supports these identifiers.
  • There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that occurs when the fldcr instruction is used. GCC uses fldcr on the 88100 to serialize volatile memory references. Use the option -mno-serialize-volatile if your version of the assembler has this bug.
  • On VMS, GAS versions 1.38.1 and earlier may cause spurious warning messages from the linker. These warning messages complain of mismatched psect attributes. You can ignore them.
  • On NewsOS version 3, if you include both of the files stddef.h and sys/types.h, you get an error because there are two typedefs of size_t. You should change sys/types.h by adding these lines around the definition of size_t:
    #ifndef _SIZE_T
#define _SIZE_T
actual-typedef-here
#endif
  • On the Alliant, the system's own convention for returning structures and unions is unusual, and is not compatible with GCC no matter what options are used.
  • On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different convention for structure and union returning. Use the option -mhc-struct-return to tell GCC to use a convention compatible with it.
  • On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved by function calls. However, the C compiler uses conventions compatible with BSD Unix: registers 2 through 5 may be clobbered by function calls.

    GCC uses the same convention as the Ultrix C compiler. You can use these options to produce code compatible with the Fortran compiler:

    -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5

  • On the WE32k, you may find that programs compiled with GCC do not work with the standard shared C library. You may need to link with the ordinary C compiler. If you do so, you must specify the following options:
    -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s

    The first specifies where to find the library libgcc.a specified with the -lgcc option.

    GCC does linking by invoking ld, just as cc does, and there is no reason why it should matter which compilation program you use to invoke ld. If someone tracks this problem down, it can probably be fixed easily.

  • On the Alpha, you may get assembler errors about invalid syntax as a result of floating point constants. This is due to a bug in the C library functions ecvt, fcvt and gcvt. Given valid floating point numbers, they sometimes print NaN.
  • On Irix 4.0.5F (and perhaps in some other versions), an assembler bug sometimes reorders instructions incorrectly when optimization is turned on. If you think this may be happening to you, try using the GNU assembler; GAS version 2.1 supports ECOFF on Irix.

    Or use the -noasmopt option when you compile GCC with itself, and then again when you compile your program. (This is a temporary kludge to turn off assembler optimization on Irix.) If this proves to be what you need, edit the assembler spec in the file specs so that it unconditionally passes -O0 to the assembler, and never passes -O2 or -O3.


Using the GNU Compiler Collection (GCC)

Node:Invoking G++, Next:C Dialect Options, Previous:Overall Options, Up:Invoking GCC

Compiling C++ Programs

C++ source files conventionally use one of the suffixes .C, .cc, .cpp, .c++, .cp, or .cxx; preprocessed C++ files use the suffix .ii. GCC recognizes files with these names and compiles them as C++ programs even if you call the compiler the same way as for compiling C programs (usually with the name gcc).

However, C++ programs often require class libraries as well as a compiler that understands the C++ language--and under some circumstances, you might want to compile programs from standard input, or otherwise without a suffix that flags them as C++ programs. g++ is a program that calls GCC with the default language set to C++, and automatically specifies linking against the C++ library. On many systems, g++ is also installed with the name c++.

When you compile C++ programs, you may specify many of the same command-line options that you use for compiling programs in any language; or command-line options meaningful for C and related languages; or options that are meaningful only for C++ programs. See Options Controlling C Dialect, for explanations of options for languages related to C. See Options Controlling C++ Dialect, for explanations of options that are meaningful only for C++ programs.


Using the GNU Compiler Collection (GCC)

Node:Invoking GCC, Next:C Implementation, Previous:Standards, Up:Top

GCC Command Options

When you invoke GCC, it normally does preprocessing, compilation, assembly and linking. The "overall options" allow you to stop this process at an intermediate stage. For example, the -c option says not to run the linker. Then the output consists of object files output by the assembler.

Other options are passed on to one stage of processing. Some options control the preprocessor and others the compiler itself. Yet other options control the assembler and linker; most of these are not documented here, since you rarely need to use any of them.

Most of the command line options that you can use with GCC are useful for C programs; when an option is only useful with another language (usually C++), the explanation says so explicitly. If the description for a particular option does not mention a source language, you can use that option with all supported languages.

See Compiling C++ Programs, for a summary of special options for compiling C++ programs.

The gcc program accepts options and file names as operands. Many options have multi-letter names; therefore multiple single-letter options may not be grouped: -dr is very different from -d -r.

You can mix options and other arguments. For the most part, the order you use doesn't matter. Order does matter when you use several options of the same kind; for example, if you specify -L more than once, the directories are searched in the order specified.

Many options have long names starting with -f or with -W--for example, -fforce-mem, -fstrength-reduce, -Wformat and so on. Most of these have both positive and negative forms; the negative form of -ffoo would be -fno-foo. This manual documents only one of these two forms, whichever one is not the default.

See Option Index, for an index to GCC's options.

  • Option Summary: Brief list of all options, without explanations.
  • Overall Options: Controlling the kind of output: an executable, object files, assembler files, or preprocessed source.
  • Invoking G++: Compiling C++ programs.
  • C Dialect Options: Controlling the variant of C language compiled.
  • C++ Dialect Options: Variations on C++.
  • Objective-C Dialect Options: Variations on Objective-C.
  • Language Independent Options: Controlling how diagnostics should be formatted.
  • Warning Options: How picky should the compiler be?
  • Debugging Options: Symbol tables, measurements, and debugging dumps.
  • Optimize Options: How much optimization?
  • Preprocessor Options: Controlling header files and macro definitions. Also, getting dependency information for Make.
  • Assembler Options: Passing options to the assembler.
  • Link Options: Specifying libraries and so on.
  • Directory Options: Where to find header files and libraries. Where to find the compiler executable files.
  • Spec Files: How to pass switches to sub-processes.
  • Target Options: Running a cross-compiler, or an old version of GCC.
  • Submodel Options: Specifying minor hardware or convention variations, such as 68010 vs 68020.
  • Code Gen Options: Specifying conventions for function calls, data layout and register usage.
  • Environment Variables: Env vars that affect GCC.
  • Running Protoize: Automatically adding or removing function prototypes.


Using the GNU Compiler Collection (GCC)

Node:Invoking Gcov, Next:Gcov and Optimization, Previous:Gcov Intro, Up:Gcov

Invoking gcov

gcov [options] sourcefile

gcov accepts the following options:

-h
--help
Display help about using gcov (on the standard output), and exit without doing any further processing.
-v
--version
Display the gcov version number (on the standard output), and exit without doing any further processing.
-b
--branch-probabilities
Write branch frequencies to the output file, and write branch summary info to the standard output. This option allows you to see how often each branch in your program was taken.
-c
--branch-counts
Write branch frequencies as the number of branches taken, rather than the percentage of branches taken.
-n
--no-output
Do not create the gcov output file.
-l
--long-file-names
Create long file names for included source files. For example, if the header file x.h contains code, and was included in the file a.c, then running gcov on the file a.c will produce an output file called a.c.x.h.gcov instead of x.h.gcov. This can be useful if x.h is included in multiple source files.
-f
--function-summaries
Output summaries for each function in addition to the file level summary.
-o directory
--object-directory directory
The directory where the object files live. Gcov will search for .bb, .bbg, and .da files in this directory.

When using gcov, you must first compile your program with two special GCC options: -fprofile-arcs -ftest-coverage. This tells the compiler to generate additional information needed by gcov (basically a flow graph of the program) and also includes additional code in the object files for generating the extra profiling information needed by gcov. These additional files are placed in the directory where the source code is located.

Running the program will cause profile output to be generated. For each source file compiled with -fprofile-arcs, an accompanying .da file will be placed in the source directory.

Running gcov with your program's source file names as arguments will now produce a listing of the code along with frequency of execution for each line. For example, if your program is called tmp.c, this is what you see when you use the basic gcov facility:

$ gcc -fprofile-arcs -ftest-coverage tmp.c
$ a.out
$ gcov tmp.c
 87.50% of 8 source lines executed in file tmp.c
Creating tmp.c.gcov.

The file tmp.c.gcov contains output from gcov. Here is a sample:

                main()
                {
           1      int i, total;

           1      total = 0;

          11      for (i = 0; i < 10; i++)
          10        total += i;

           1      if (total != 45)
      ######        printf ("Failure\n");
                  else
           1        printf ("Success\n");
           1    }

When you use the -b option, your output looks like this:

$ gcov -b tmp.c
 87.50% of 8 source lines executed in file tmp.c
 80.00% of 5 branches executed in file tmp.c
 80.00% of 5 branches taken at least once in file tmp.c
 50.00% of 2 calls executed in file tmp.c
Creating tmp.c.gcov.

Here is a sample of a resulting tmp.c.gcov file:

                main()
                {
           1      int i, total;

           1      total = 0;

          11      for (i = 0; i < 10; i++)
branch 0 taken = 91%
branch 1 taken = 100%
branch 2 taken = 100%
          10        total += i;

           1      if (total != 45)
branch 0 taken = 100%
      ######        printf ("Failure\n");
call 0 never executed
branch 1 never executed
                  else
           1        printf ("Success\n");
call 0 returns = 100%
           1    }

For each basic block, a line is printed after the last line of the basic block describing the branch or call that ends the basic block. There can be multiple branches and calls listed for a single source line if there are multiple basic blocks that end on that line. In this case, the branches and calls are each given a number. There is no simple way to map these branches and calls back to source constructs. In general, though, the lowest numbered branch or call will correspond to the leftmost construct on the source line.

For a branch, if it was executed at least once, then a percentage indicating the number of times the branch was taken divided by the number of times the branch was executed will be printed. Otherwise, the message "never executed" is printed.

For a call, if it was executed at least once, then a percentage indicating the number of times the call returned divided by the number of times the call was executed will be printed. This will usually be 100%, but may be less for functions call exit or longjmp, and thus may not return every time they are called.

The execution counts are cumulative. If the example program were executed again without removing the .da file, the count for the number of times each line in the source was executed would be added to the results of the previous run(s). This is potentially useful in several ways. For example, it could be used to accumulate data over a number of program runs as part of a test verification suite, or to provide more accurate long-term information over a large number of program runs.

The data in the .da files is saved immediately before the program exits. For each source file compiled with -fprofile-arcs, the profiling code first attempts to read in an existing .da file; if the file doesn't match the executable (differing number of basic block counts) it will ignore the contents of the file. It then adds in the new execution counts and finally writes the data to the file.


Using the GNU Compiler Collection (GCC)

Node:Java Exceptions, Next:Deprecated Features, Previous:C++ Attributes, Up:C++ Extensions

Java Exceptions

The Java language uses a slightly different exception handling model from C++. Normally, GNU C++ will automatically detect when you are writing C++ code that uses Java exceptions, and handle them appropriately. However, if C++ code only needs to execute destructors when Java exceptions are thrown through it, GCC will guess incorrectly. Sample problematic code is:

  struct S { ~S(); };
  extern void bar();    // is written in Java, and may throw exceptions
  void foo()
  {
    S s;
    bar();
  }

The usual effect of an incorrect guess is a link failure, complaining of a missing routine called __gxx_personality_v0.

You can inform the compiler that Java exceptions are to be used in a translation unit, irrespective of what it might think, by writing #pragma GCC java_exceptions at the head of the file. This #pragma must appear before any functions that throw or catch exceptions, or run destructors when exceptions are thrown through them.

You cannot mix Java and C++ exceptions in the same translation unit. It is believed to be safe to throw a C++ exception from one file through another file compiled for the Java exception model, or vice versa, but there may be bugs in this area.


Using the GNU Compiler Collection (GCC)

Node:Labels as Values, Next:Nested Functions, Previous:Local Labels, Up:C Extensions

Labels as Values

You can get the address of a label defined in the current function (or a containing function) with the unary operator &&. The value has type void *. This value is a constant and can be used wherever a constant of that type is valid. For example:

void *ptr;
...
ptr = &&foo;

To use these values, you need to be able to jump to one. This is done with the computed goto statement1, goto *exp;. For example,

goto *ptr;

Any expression of type void * is allowed.

One way of using these constants is in initializing a static array that will serve as a jump table:

static void *array[] = { &&foo, &&bar, &&hack };

Then you can select a label with indexing, like this:

goto *array[i];

Note that this does not check whether the subscript is in bounds--array indexing in C never does that.

Such an array of label values serves a purpose much like that of the switch statement. The switch statement is cleaner, so use that rather than an array unless the problem does not fit a switch statement very well.

Another use of label values is in an interpreter for threaded code. The labels within the interpreter function can be stored in the threaded code for super-fast dispatching.

You may not use this mechanism to jump to code in a different function. If you do that, totally unpredictable things will happen. The best way to avoid this is to store the label address only in automatic variables and never pass it as an argument.

An alternate way to write the above example is

static const int array[] = { &&foo - &&foo, &&bar - &&foo,
                             &&hack - &&foo };
goto *(&&foo + array[i]);

This is more friendly to code living in shared libraries, as it reduces the number of dynamic relocations that are needed, and by consequence, allows the data to be read-only.

Footnotes

  1. The analogous feature in Fortran is called an assigned goto, but that name seems inappropriate in C, where one can do more than simply store label addresses in label variables.


Using the GNU Compiler Collection (GCC)

Node:Language Independent Options, Next:Warning Options, Previous:Objective-C Dialect Options, Up:Invoking GCC

Options to Control Diagnostic Messages Formatting

Traditionally, diagnostic messages have been formatted irrespective of the output device's aspect (e.g. its width, ...). The options described below can be used to control the diagnostic messages formatting algorithm, e.g. how many characters per line, how often source location information should be reported. Right now, only the C++ front end can honor these options. However it is expected, in the near future, that the remaining front ends would be able to digest them correctly.

-fmessage-length=n
Try to format error messages so that they fit on lines of about n characters. The default is 72 characters for g++ and 0 for the rest of the front ends supported by GCC. If n is zero, then no line-wrapping will be done; each error message will appear on a single line.
-fdiagnostics-show-location=once
Only meaningful in line-wrapping mode. Instructs the diagnostic messages reporter to emit once source location information; that is, in case the message is too long to fit on a single physical line and has to be wrapped, the source location won't be emitted (as prefix) again, over and over, in subsequent continuation lines. This is the default behavior.
-fdiagnostics-show-location=every-line
Only meaningful in line-wrapping mode. Instructs the diagnostic messages reporter to emit the same source location information (as prefix) for physical lines that result from the process of breaking a message which is too long to fit on a single line.


Using the GNU Compiler Collection (GCC)

Node:Library functions implementation, Next:Architecture implementation, Previous:Preprocessing directives implementation, Up:C Implementation

Library functions

The behavior of these points are dependent on the implementation of the C library, and are not defined by GCC itself.


Using the GNU Compiler Collection (GCC)

Node:Link Options, Next:Directory Options, Previous:Assembler Options, Up:Invoking GCC

Options for Linking

These options come into play when the compiler links object files into an executable output file. They are meaningless if the compiler is not doing a link step.

object-file-name
A file name that does not end in a special recognized suffix is considered to name an object file or library. (Object files are distinguished from libraries by the linker according to the file contents.) If linking is done, these object files are used as input to the linker.
-c
-S
-E
If any of these options is used, then the linker is not run, and object file names should not be used as arguments. See Overall Options.
-llibrary
-l library
Search the library named library when linking. (The second alternative with the library as a separate argument is only for POSIX compliance and is not recommended.)

It makes a difference where in the command you write this option; the linker searches and processes libraries and object files in the order they are specified. Thus, foo.o -lz bar.o searches library z after file foo.o but before bar.o. If bar.o refers to functions in z, those functions may not be loaded.

The linker searches a standard list of directories for the library, which is actually a file named liblibrary.a. The linker then uses this file as if it had been specified precisely by name.

The directories searched include several standard system directories plus any that you specify with -L.

Normally the files found this way are library files--archive files whose members are object files. The linker handles an archive file by scanning through it for members which define symbols that have so far been referenced but not defined. But if the file that is found is an ordinary object file, it is linked in the usual fashion. The only difference between using an -l option and specifying a file name is that -l surrounds library with lib and .a and searches several directories.

-lobjc
You need this special case of the -l option in order to link an Objective-C program.
-nostartfiles
Do not use the standard system startup files when linking. The standard system libraries are used normally, unless -nostdlib or -nodefaultlibs is used.
-nodefaultlibs
Do not use the standard system libraries when linking. Only the libraries you specify will be passed to the linker. The standard startup files are used normally, unless -nostartfiles is used. The compiler may generate calls to memcmp, memset, and memcpy for System V (and ISO C) environments or to bcopy and bzero for BSD environments. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified.
-nostdlib
Do not use the standard system startup files or libraries when linking. No startup files and only the libraries you specify will be passed to the linker. The compiler may generate calls to memcmp, memset, and memcpy for System V (and ISO C) environments or to bcopy and bzero for BSD environments. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified.

One of the standard libraries bypassed by -nostdlib and -nodefaultlibs is libgcc.a, a library of internal subroutines that GCC uses to overcome shortcomings of particular machines, or special needs for some languages. (See Interfacing to GCC Output, for more discussion of libgcc.a.) In most cases, you need libgcc.a even when you want to avoid other standard libraries. In other words, when you specify -nostdlib or -nodefaultlibs you should usually specify -lgcc as well. This ensures that you have no unresolved references to internal GCC library subroutines. (For example, __main, used to ensure C++ constructors will be called; see collect2.)

-s
Remove all symbol table and relocation information from the executable.
-static
On systems that support dynamic linking, this prevents linking with the shared libraries. On other systems, this option has no effect.
-shared
Produce a shared object which can then be linked with other objects to form an executable. Not all systems support this option. For predictable results, you must also specify the same set of options that were used to generate code (-fpic, -fPIC, or model suboptions) when you specify this option.1
-shared-libgcc
-static-libgcc
On systems that provide libgcc as a shared library, these options force the use of either the shared or static version respectively. If no shared version of libgcc was built when the compiler was configured, these options have no effect.

There are several situations in which an application should use the shared libgcc instead of the static version. The most common of these is when the application wishes to throw and catch exceptions across different shared libraries. In that case, each of the libraries as well as the application itself should use the shared libgcc.

Therefore, the G++ and GCJ drivers automatically add -shared-libgcc whenever you build a shared library or a main executable, because C++ and Java programs typically use exceptions, so this is the right thing to do.

If, instead, you use the GCC driver to create shared libraries, you may find that they will not always be linked with the shared libgcc. If GCC finds, at its configuration time, that you have a GNU linker that does not support option --eh-frame-hdr, it will link the shared version of libgcc into shared libraries by default. Otherwise, it will take advantage of the linker and optimize away the linking with the shared version of libgcc, linking with the static version of libgcc by default. This allows exceptions to propagate through such shared libraries, without incurring relocation costs at library load time.

However, if a library or main executable is supposed to throw or catch exceptions, you must link it using the G++ or GCJ driver, as appropriate for the languages used in the program, or using the option -shared-libgcc, such that it is linked with the shared libgcc.

-symbolic
Bind references to global symbols when building a shared object. Warn about any unresolved references (unless overridden by the link editor option -Xlinker -z -Xlinker defs). Only a few systems support this option.
-Xlinker option
Pass option as an option to the linker. You can use this to supply system-specific linker options which GCC does not know how to recognize.

If you want to pass an option that takes an argument, you must use -Xlinker twice, once for the option and once for the argument. For example, to pass -assert definitions, you must write -Xlinker -assert -Xlinker definitions. It does not work to write -Xlinker "-assert definitions", because this passes the entire string as a single argument, which is not what the linker expects.

-Wl,option
Pass option as an option to the linker. If option contains commas, it is split into multiple options at the commas.
-u symbol
Pretend the symbol symbol is undefined, to force linking of library modules to define it. You can use -u multiple times with different symbols to force loading of additional library modules.

Footnotes

  1. On some systems, gcc -shared needs to build supplementary stub code for constructors to work. On multi-libbed systems, gcc -shared must select the correct support libraries to link against. Failing to supply the correct flags may lead to subtle defects. Supplying them in cases where they are not necessary is innocuous.


Using the GNU Compiler Collection (GCC)

Node:Local Labels, Next:Labels as Values, Previous:Statement Exprs, Up:C Extensions

Locally Declared Labels

Each statement expression is a scope in which local labels can be declared. A local label is simply an identifier; you can jump to it with an ordinary goto statement, but only from within the statement expression it belongs to.

A local label declaration looks like this:

__label__ label;

or

__label__ label1, label2, ...;

Local label declarations must come at the beginning of the statement expression, right after the ({, before any ordinary declarations.

The label declaration defines the label name, but does not define the label itself. You must do this in the usual way, with label:, within the statements of the statement expression.

The local label feature is useful because statement expressions are often used in macros. If the macro contains nested loops, a goto can be useful for breaking out of them. However, an ordinary label whose scope is the whole function cannot be used: if the macro can be expanded several times in one function, the label will be multiply defined in that function. A local label avoids this problem. For example:

#define SEARCH(array, target)                     \
({                                                \
  __label__ found;                                \
  typeof (target) _SEARCH_target = (target);      \
  typeof (*(array)) *_SEARCH_array = (array);     \
  int i, j;                                       \
  int value;                                      \
  for (i = 0; i < max; i++)                       \
    for (j = 0; j < max; j++)                     \
      if (_SEARCH_array[i][j] == _SEARCH_target)  \
        { value = i; goto found; }                \
  value = -1;                                     \
 found:                                           \
  value;                                          \
})


Using the GNU Compiler Collection (GCC)

Node:Local Reg Vars, Previous:Global Reg Vars, Up:Explicit Reg Vars

Specifying Registers for Local Variables

You can define a local register variable with a specified register like this:

register int *foo asm ("a5");

Here a5 is the name of the register which should be used. Note that this is the same syntax used for defining global register variables, but for a local variable it would appear within a function.

Naturally the register name is cpu-dependent, but this is not a problem, since specific registers are most often useful with explicit assembler instructions (see Extended Asm). Both of these things generally require that you conditionalize your program according to cpu type.

In addition, operating systems on one type of cpu may differ in how they name the registers; then you would need additional conditionals. For example, some 68000 operating systems call this register %a5.

Defining such a register variable does not reserve the register; it remains available for other uses in places where flow control determines the variable's value is not live. However, these registers are made unavailable for use in the reload pass; excessive use of this feature leaves the compiler too few available registers to compile certain functions.

This option does not guarantee that GCC will generate code that has this variable in the register you specify at all times. You may not code an explicit reference to this register in an asm statement and assume it will always refer to this variable.

Stores into local register variables may be deleted when they appear to be dead according to dataflow analysis. References to local register variables may be deleted or moved or simplified.


Using the GNU Compiler Collection (GCC)

Node:Locale-specific behavior implementation, Previous:Architecture implementation, Up:C Implementation

Locale-specific behavior

The behavior of these points are dependent on the implementation of the C library, and are not defined by GCC itself.


Using the GNU Compiler Collection (GCC)

Node:Long Long, Next:Complex, Previous:Conditionals, Up:C Extensions

Double-Word Integers

ISO C99 supports data types for integers that are at least 64 bits wide, and as an extension GCC supports them in C89 mode and in C++. Simply write long long int for a signed integer, or unsigned long long int for an unsigned integer. To make an integer constant of type long long int, add the suffix LL to the integer. To make an integer constant of type unsigned long long int, add the suffix ULL to the integer.

You can use these types in arithmetic like any other integer types. Addition, subtraction, and bitwise boolean operations on these types are open-coded on all types of machines. Multiplication is open-coded if the machine supports fullword-to-doubleword a widening multiply instruction. Division and shifts are open-coded only on machines that provide special support. The operations that are not open-coded use special library routines that come with GCC.

There may be pitfalls when you use long long types for function arguments, unless you declare function prototypes. If a function expects type int for its argument, and you pass a value of type long long int, confusion will result because the caller and the subroutine will disagree about the number of bytes for the argument. Likewise, if the function expects long long int and you pass int. The best way to avoid such problems is to use prototypes.


Using the GNU Compiler Collection (GCC)

Node:Lvalues, Next:Conditionals, Previous:Typeof, Up:C Extensions

Generalized Lvalues

Compound expressions, conditional expressions and casts are allowed as lvalues provided their operands are lvalues. This means that you can take their addresses or store values into them.

Standard C++ allows compound expressions and conditional expressions as lvalues, and permits casts to reference type, so use of this extension is deprecated for C++ code.

For example, a compound expression can be assigned, provided the last expression in the sequence is an lvalue. These two expressions are equivalent:

(a, b) += 5
a, (b += 5)

Similarly, the address of the compound expression can be taken. These two expressions are equivalent:

&(a, b)
a, &b

A conditional expression is a valid lvalue if its type is not void and the true and false branches are both valid lvalues. For example, these two expressions are equivalent:

(a ? b : c) = 5
(a ? b = 5 : (c = 5))

A cast is a valid lvalue if its operand is an lvalue. A simple assignment whose left-hand side is a cast works by converting the right-hand side first to the specified type, then to the type of the inner left-hand side expression. After this is stored, the value is converted back to the specified type to become the value of the assignment. Thus, if a has type char *, the following two expressions are equivalent:

(int)a = 5
(int)(a = (char *)(int)5)

An assignment-with-arithmetic operation such as += applied to a cast performs the arithmetic using the type resulting from the cast, and then continues as in the previous case. Therefore, these two expressions are equivalent:

(int)a += 5
(int)(a = (char *)(int) ((int)a + 5))

You cannot take the address of an lvalue cast, because the use of its address would not work out coherently. Suppose that &(int)f were permitted, where f has type float. Then the following statement would try to store an integer bit-pattern where a floating point number belongs:

*&(int)f = 1;

This is quite different from what (int)f = 1 would do--that would convert 1 to floating point and store it. Rather than cause this inconsistency, we think it is better to prohibit use of & on a cast.

If you really do want an int * pointer with the address of f, you can simply write (int *)&f.


Using the GNU Compiler Collection (GCC)

Node:M32R/D Options, Next:M88K Options, Previous:MN10300 Options, Up:Submodel Options

M32R/D Options

These -m options are defined for Mitsubishi M32R/D architectures:

-m32rx
Generate code for the M32R/X.
-m32r
Generate code for the M32R. This is the default.
-mcode-model=small
Assume all objects live in the lower 16MB of memory (so that their addresses can be loaded with the ld24 instruction), and assume all subroutines are reachable with the bl instruction. This is the default.

The addressability of a particular object can be set with the model attribute.

-mcode-model=medium
Assume objects may be anywhere in the 32-bit address space (the compiler will generate seth/add3 instructions to load their addresses), and assume all subroutines are reachable with the bl instruction.
-mcode-model=large
Assume objects may be anywhere in the 32-bit address space (the compiler will generate seth/add3 instructions to load their addresses), and assume subroutines may not be reachable with the bl instruction (the compiler will generate the much slower seth/add3/jl instruction sequence).
-msdata=none
Disable use of the small data area. Variables will be put into one of .data, bss, or .rodata (unless the section attribute has been specified). This is the default.

The small data area consists of sections .sdata and .sbss. Objects may be explicitly put in the small data area with the section attribute using one of these sections.

-msdata=sdata
Put small global and static data in the small data area, but do not generate special code to reference them.
-msdata=use
Put small global and static data in the small data area, and generate special instructions to reference them.
-G num
Put global and static objects less than or equal to num bytes into the small data or bss sections instead of the normal data or bss sections. The default value of num is 8. The -msdata option must be set to one of sdata or use for this option to have any effect.

All modules should be compiled with the same -G num value. Compiling with different values of num may or may not work; if it doesn't the linker will give an error message--incorrect code will not be generated.


Using the GNU Compiler Collection (GCC)

Node:M680x0 Options, Next:M68hc1x Options, Up:Submodel Options

M680x0 Options

These are the -m options defined for the 68000 series. The default values for these options depends on which style of 68000 was selected when the compiler was configured; the defaults for the most common choices are given below.

-m68000
-mc68000
Generate output for a 68000. This is the default when the compiler is configured for 68000-based systems.

Use this option for microcontrollers with a 68000 or EC000 core, including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.

-m68020
-mc68020
Generate output for a 68020. This is the default when the compiler is configured for 68020-based systems.
-m68881
Generate output containing 68881 instructions for floating point. This is the default for most 68020 systems unless --nfp was specified when the compiler was configured.
-m68030
Generate output for a 68030. This is the default when the compiler is configured for 68030-based systems.
-m68040
Generate output for a 68040. This is the default when the compiler is configured for 68040-based systems.

This option inhibits the use of 68881/68882 instructions that have to be emulated by software on the 68040. Use this option if your 68040 does not have code to emulate those instructions.

-m68060
Generate output for a 68060. This is the default when the compiler is configured for 68060-based systems.

This option inhibits the use of 68020 and 68881/68882 instructions that have to be emulated by software on the 68060. Use this option if your 68060 does not have code to emulate those instructions.

-mcpu32
Generate output for a CPU32. This is the default when the compiler is configured for CPU32-based systems.

Use this option for microcontrollers with a CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334, 68336, 68340, 68341, 68349 and 68360.

-m5200
Generate output for a 520X "coldfire" family cpu. This is the default when the compiler is configured for 520X-based systems.

Use this option for microcontroller with a 5200 core, including the MCF5202, MCF5203, MCF5204 and MCF5202.

-m68020-40
Generate output for a 68040, without using any of the new instructions. This results in code which can run relatively efficiently on either a 68020/68881 or a 68030 or a 68040. The generated code does use the 68881 instructions that are emulated on the 68040.
-m68020-60
Generate output for a 68060, without using any of the new instructions. This results in code which can run relatively efficiently on either a 68020/68881 or a 68030 or a 68040. The generated code does use the 68881 instructions that are emulated on the 68060.
-mfpa
Generate output containing Sun FPA instructions for floating point.
-msoft-float
Generate output containing library calls for floating point. Warning: the requisite libraries are not available for all m68k targets. Normally the facilities of the machine's usual C compiler are used, but this can't be done directly in cross-compilation. You must make your own arrangements to provide suitable library functions for cross-compilation. The embedded targets m68k-*-aout and m68k-*-coff do provide software floating point support.
-mshort
Consider type int to be 16 bits wide, like short int.
-mnobitfield
Do not use the bit-field instructions. The -m68000, -mcpu32 and -m5200 options imply -mnobitfield.
-mbitfield
Do use the bit-field instructions. The -m68020 option implies -mbitfield. This is the default if you use a configuration designed for a 68020.
-mrtd
Use a different function-calling convention, in which functions that take a fixed number of arguments return with the rtd instruction, which pops their arguments while returning. This saves one instruction in the caller since there is no need to pop the arguments there.

This calling convention is incompatible with the one normally used on Unix, so you cannot use it if you need to call libraries compiled with the Unix compiler.

Also, you must provide function prototypes for all functions that take variable numbers of arguments (including printf); otherwise incorrect code will be generated for calls to those functions.

In addition, seriously incorrect code will result if you call a function with too many arguments. (Normally, extra arguments are harmlessly ignored.)

The rtd instruction is supported by the 68010, 68020, 68030, 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.

-malign-int
-mno-align-int
Control whether GCC aligns int, long, long long, float, double, and long double variables on a 32-bit boundary (-malign-int) or a 16-bit boundary (-mno-align-int). Aligning variables on 32-bit boundaries produces code that runs somewhat faster on processors with 32-bit busses at the expense of more memory.

Warning: if you use the -malign-int switch, GCC will align structures containing the above types differently than most published application binary interface specifications for the m68k.

-mpcrel
Use the pc-relative addressing mode of the 68000 directly, instead of using a global offset table. At present, this option implies -fpic, allowing at most a 16-bit offset for pc-relative addressing. -fPIC is not presently supported with -mpcrel, though this could be supported for 68020 and higher processors.
-mno-strict-align
-mstrict-align
Do not (do) assume that unaligned memory references will be handled by the system.


Using the GNU Compiler Collection (GCC)

Node:M68hc1x Options, Next:VAX Options, Previous:M680x0 Options, Up:Submodel Options

M68hc1x Options

These are the -m options defined for the 68hc11 and 68hc12 microcontrollers. The default values for these options depends on which style of microcontroller was selected when the compiler was configured; the defaults for the most common choices are given below.

-m6811
-m68hc11
Generate output for a 68HC11. This is the default when the compiler is configured for 68HC11-based systems.
-m6812
-m68hc12
Generate output for a 68HC12. This is the default when the compiler is configured for 68HC12-based systems.
-mauto-incdec
Enable the use of 68HC12 pre and post auto-increment and auto-decrement addressing modes.
-mshort
Consider type int to be 16 bits wide, like short int.
-msoft-reg-count=count
Specify the number of pseudo-soft registers which are used for the code generation. The maximum number is 32. Using more pseudo-soft register may or may not result in better code depending on the program. The default is 4 for 68HC11 and 2 for 68HC12.


Using the GNU Compiler Collection (GCC)

Node:M88K Options, Next:RS/6000 and PowerPC Options, Previous:M32R/D Options, Up:Submodel Options

M88K Options

These -m options are defined for Motorola 88k architectures:

-m88000
Generate code that works well on both the m88100 and the m88110.
-m88100
Generate code that works best for the m88100, but that also runs on the m88110.
-m88110
Generate code that works best for the m88110, and may not run on the m88100.
-mbig-pic
Obsolete option to be removed from the next revision. Use -fPIC.
-midentify-revision
Include an ident directive in the assembler output recording the source file name, compiler name and version, timestamp, and compilation flags used.
-mno-underscores
In assembler output, emit symbol names without adding an underscore character at the beginning of each name. The default is to use an underscore as prefix on each name.
-mocs-debug-info
-mno-ocs-debug-info
Include (or omit) additional debugging information (about registers used in each stack frame) as specified in the 88open Object Compatibility Standard, "OCS". This extra information allows debugging of code that has had the frame pointer eliminated. The default for DG/UX, SVr4, and Delta 88 SVr3.2 is to include this information; other 88k configurations omit this information by default.
-mocs-frame-position
When emitting COFF debugging information for automatic variables and parameters stored on the stack, use the offset from the canonical frame address, which is the stack pointer (register 31) on entry to the function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use -mocs-frame-position; other 88k configurations have the default -mno-ocs-frame-position.
-mno-ocs-frame-position
When emitting COFF debugging information for automatic variables and parameters stored on the stack, use the offset from the frame pointer register (register 30). When this option is in effect, the frame pointer is not eliminated when debugging information is selected by the -g switch.
-moptimize-arg-area
Save space by reorganizing the stack frame. This option generates code that does not agree with the 88open specifications, but uses less memory.
-mno-optimize-arg-area
Do not reorganize the stack frame to save space. This is the default. The generated conforms to the specification, but uses more memory.
-mshort-data-num
Generate smaller data references by making them relative to r0, which allows loading a value using a single instruction (rather than the usual two). You control which data references are affected by specifying num with this option. For example, if you specify -mshort-data-512, then the data references affected are those involving displacements of less than 512 bytes. -mshort-data-num is not effective for num greater than 64k.
-mserialize-volatile
-mno-serialize-volatile
Do, or don't, generate code to guarantee sequential consistency of volatile memory references. By default, consistency is guaranteed.

The order of memory references made by the MC88110 processor does not always match the order of the instructions requesting those references. In particular, a load instruction may execute before a preceding store instruction. Such reordering violates sequential consistency of volatile memory references, when there are multiple processors. When consistency must be guaranteed, GCC generates special instructions, as needed, to force execution in the proper order.

The MC88100 processor does not reorder memory references and so always provides sequential consistency. However, by default, GCC generates the special instructions to guarantee consistency even when you use -m88100, so that the code may be run on an MC88110 processor. If you intend to run your code only on the MC88100 processor, you may use -mno-serialize-volatile.

The extra code generated to guarantee consistency may affect the performance of your application. If you know that you can safely forgo this guarantee, you may use -mno-serialize-volatile.

-msvr4
-msvr3
Turn on (-msvr4) or off (-msvr3) compiler extensions related to System V release 4 (SVr4). This controls the following:

  1. Which variant of the assembler syntax to emit.
  2. -msvr4 makes the C preprocessor recognize #pragma weak that is used on System V release 4.
  3. -msvr4 makes GCC issue additional declaration directives used in SVr4.

-msvr4 is the default for the m88k-motorola-sysv4 and m88k-dg-dgux m88k configurations. -msvr3 is the default for all other m88k configurations.

-mversion-03.00
This option is obsolete, and is ignored.
-mno-check-zero-division
-mcheck-zero-division
Do, or don't, generate code to guarantee that integer division by zero will be detected. By default, detection is guaranteed.

Some models of the MC88100 processor fail to trap upon integer division by zero under certain conditions. By default, when compiling code that might be run on such a processor, GCC generates code that explicitly checks for zero-valued divisors and traps with exception number 503 when one is detected. Use of -mno-check-zero-division suppresses such checking for code generated to run on an MC88100 processor.

GCC assumes that the MC88110 processor correctly detects all instances of integer division by zero. When -m88110 is specified, no explicit checks for zero-valued divisors are generated, and both -mcheck-zero-division and -mno-check-zero-division are ignored.

-muse-div-instruction
Use the div instruction for signed integer division on the MC88100 processor. By default, the div instruction is not used.

On the MC88100 processor the signed integer division instruction div) traps to the operating system on a negative operand. The operating system transparently completes the operation, but at a large cost in execution time. By default, when compiling code that might be run on an MC88100 processor, GCC emulates signed integer division using the unsigned integer division instruction divu), thereby avoiding the large penalty of a trap to the operating system. Such emulation has its own, smaller, execution cost in both time and space. To the extent that your code's important signed integer division operations are performed on two nonnegative operands, it may be desirable to use the div instruction directly.

On the MC88110 processor the div instruction (also known as the divs instruction) processes negative operands without trapping to the operating system. When -m88110 is specified, -muse-div-instruction is ignored, and the div instruction is used for signed integer division.

Note that the result of dividing INT_MIN by -1 is undefined. In particular, the behavior of such a division with and without -muse-div-instruction may differ.

-mtrap-large-shift
-mhandle-large-shift
Include code to detect bit-shifts of more than 31 bits; respectively, trap such shifts or emit code to handle them properly. By default GCC makes no special provision for large bit shifts.
-mwarn-passed-structs
Warn when a function passes a struct as an argument or result. Structure-passing conventions have changed during the evolution of the C language, and are often the source of portability problems. By default, GCC issues no such warning.


Using the GNU Compiler Collection (GCC)

Node:Machine Constraints, Previous:Modifiers, Up:Constraints

Constraints for Particular Machines

Whenever possible, you should use the general-purpose constraint letters in asm arguments, since they will convey meaning more readily to people reading your code. Failing that, use the constraint letters that usually have very similar meanings across architectures. The most commonly used constraints are m and r (for memory and general-purpose registers respectively; see Simple Constraints), and I, usually the letter indicating the most common immediate-constant format.

For each machine architecture, the config/machine/machine.h file defines additional constraints. These constraints are used by the compiler itself for instruction generation, as well as for asm statements; therefore, some of the constraints are not particularly interesting for asm. The constraints are defined through these macros:

REG_CLASS_FROM_LETTER
Register class constraints (usually lower case).
CONST_OK_FOR_LETTER_P
Immediate constant constraints, for non-floating point constants of word size or smaller precision (usually upper case).
CONST_DOUBLE_OK_FOR_LETTER_P
Immediate constant constraints, for all floating point constants and for constants of greater than word size precision (usually upper case).
EXTRA_CONSTRAINT
Special cases of registers or memory. This macro is not required, and is only defined for some machines.

Inspecting these macro definitions in the compiler source for your machine is the best way to be certain you have the right constraints. However, here is a summary of the machine-dependent constraints available on some particular machines.

ARM family--arm.h
f
Floating-point register
F
One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0 or 10.0
G
Floating-point constant that would satisfy the constraint F if it were negated
I
Integer that is valid as an immediate operand in a data processing instruction. That is, an integer in the range 0 to 255 rotated by a multiple of 2
J
Integer in the range -4095 to 4095
K
Integer that satisfies constraint I when inverted (ones complement)
L
Integer that satisfies constraint I when negated (twos complement)
M
Integer in the range 0 to 32
Q
A memory reference where the exact address is in a single register (`m' is preferable for asm statements)
R
An item in the constant pool
S
A symbol in the text segment of the current file

AMD 29000 family--a29k.h
l
Local register 0
b
Byte Pointer (BP) register
q
Q register
h
Special purpose register
A
First accumulator register
a
Other accumulator register
f
Floating point register
I
Constant greater than 0, less than 0x100
J
Constant greater than 0, less than 0x10000
K
Constant whose high 24 bits are on (1)
L
16-bit constant whose high 8 bits are on (1)
M
32-bit constant whose high 16 bits are on (1)
N
32-bit negative constant that fits in 8 bits
O
The constant 0x80000000 or, on the 29050, any 32-bit constant whose low 16 bits are 0.
P
16-bit negative constant that fits in 8 bits
G
H
A floating point constant (in asm statements, use the machine independent E or F instead)

AVR family--avr.h
l
Registers from r0 to r15
a
Registers from r16 to r23
d
Registers from r16 to r31
w
Registers from r24 to r31. These registers can be used in adiw command
e
Pointer register (r26-r31)
b
Base pointer register (r28-r31)
q
Stack pointer register (SPH:SPL)
t
Temporary register r0
x
Register pair X (r27:r26)
y
Register pair Y (r29:r28)
z
Register pair Z (r31:r30)
I
Constant greater than -1, less than 64
J
Constant greater than -64, less than 1
K
Constant integer 2
L
Constant integer 0
M
Constant that fits in 8 bits
N
Constant integer -1
O
Constant integer 8, 16, or 24
P
Constant integer 1
G
A floating point constant 0.0

IBM RS6000--rs6000.h
b
Address base register
f
Floating point register
h
MQ, CTR, or LINK register
q
MQ register
c
CTR register
l
LINK register
x
CR register (condition register) number 0
y
CR register (condition register)
z
FPMEM stack memory for FPR-GPR transfers
I
Signed 16-bit constant
J
Unsigned 16-bit constant shifted left 16 bits (use L instead for SImode constants)
K
Unsigned 16-bit constant
L
Signed 16-bit constant shifted left 16 bits
M
Constant larger than 31
N
Exact power of 2
O
Zero
P
Constant whose negation is a signed 16-bit constant
G
Floating point constant that can be loaded into a register with one instruction per word
Q
Memory operand that is an offset from a register (m is preferable for asm statements)
R
AIX TOC entry
S
Constant suitable as a 64-bit mask operand
T
Constant suitable as a 32-bit mask operand
U
System V Release 4 small data area reference

Intel 386--i386.h
q
a, b, c, or d register for the i386. For x86-64 it is equivalent to r class. (for 8-bit instructions that do not use upper halves)
Q
a, b, c, or d register. (for 8-bit instructions, that do use upper halves)
R
Legacy register--equivalent to r class in i386 mode. (for non-8-bit registers used together with 8-bit upper halves in a single instruction)
A
Specifies the a or d registers. This is primarily useful for 64-bit integer values (when in 32-bit mode) intended to be returned with the d register holding the most significant bits and the a register holding the least significant bits.
f
Floating point register
t
First (top of stack) floating point register
u
Second floating point register
a
a register
b
b register
c
c register
d
d register
D
di register
S
si register
x
xmm SSE register
y
MMX register
I
Constant in range 0 to 31 (for 32-bit shifts)
J
Constant in range 0 to 63 (for 64-bit shifts)
K
0xff
L
0xffff
M
0, 1, 2, or 3 (shifts for lea instruction)
N
Constant in range 0 to 255 (for out instruction)
Z
Constant in range 0 to 0xffffffff or symbolic reference known to fit specified range. (for using immediates in zero extending 32-bit to 64-bit x86-64 instructions)
e
Constant in range -2147483648 to 2147483647 or symbolic reference known to fit specified range. (for using immediates in 64-bit x86-64 instructions)
G
Standard 80387 floating point constant

Intel 960--i960.h
f
Floating point register (fp0 to fp3)
l
Local register (r0 to r15)
b
Global register (g0 to g15)
d
Any local or global register
I
Integers from 0 to 31
J
0
K
Integers from -31 to 0
G
Floating point 0
H
Floating point 1

MIPS--mips.h
d
General-purpose integer register
f
Floating-point register (if available)
h
Hi register
l
Lo register
x
Hi or Lo register
y
General-purpose integer register
z
Floating-point status register
I
Signed 16-bit constant (for arithmetic instructions)
J
Zero
K
Zero-extended 16-bit constant (for logic instructions)
L
Constant with low 16 bits zero (can be loaded with lui)
M
32-bit constant which requires two instructions to load (a constant which is not I, K, or L)
N
Negative 16-bit constant
O
Exact power of two
P
Positive 16-bit constant
G
Floating point zero
Q
Memory reference that can be loaded with more than one instruction (m is preferable for asm statements)
R
Memory reference that can be loaded with one instruction (m is preferable for asm statements)
S
Memory reference in external OSF/rose PIC format (m is preferable for asm statements)

Motorola 680x0--m68k.h
a
Address register
d
Data register
f
68881 floating-point register, if available
x
Sun FPA (floating-point) register, if available
y
First 16 Sun FPA registers, if available
I
Integer in the range 1 to 8
J
16-bit signed number
K
Signed number whose magnitude is greater than 0x80
L
Integer in the range -8 to -1
M
Signed number whose magnitude is greater than 0x100
G
Floating point constant that is not a 68881 constant
H
Floating point constant that can be used by Sun FPA

Motorola 68HC11 & 68HC12 families--m68hc11.h
a
Register 'a'
b
Register 'b'
d
Register 'd'
q
An 8-bit register
t
Temporary soft register _.tmp
u
A soft register _.d1 to _.d31
w
Stack pointer register
x
Register 'x'
y
Register 'y'
z
Pseudo register 'z' (replaced by 'x' or 'y' at the end)
A
An address register: x, y or z
B
An address register: x or y
D
Register pair (x:d) to form a 32-bit value
L
Constants in the range -65536 to 65535
M
Constants whose 16-bit low part is zero
N
Constant integer 1 or -1
O
Constant integer 16
P
Constants in the range -8 to 2

SPARC--sparc.h
f
Floating-point register that can hold 32- or 64-bit values.
e
Floating-point register that can hold 64- or 128-bit values.
I
Signed 13-bit constant
J
Zero
K
32-bit constant with the low 12 bits clear (a constant that can be loaded with the sethi instruction)
L
A constant in the range supported by movcc instructions
M
A constant in the range supported by movrcc instructions
N
Same as K, except that it verifies that bits that are not in the lower 32-bits range are all zero. Must be used instead of K for modes wider than SImode
G
Floating-point zero
H
Signed 13-bit constant, sign-extended to 32 or 64 bits
Q
Floating-point constant whose integral representation can be moved into an integer register using a single sethi instruction
R
Floating-point constant whose integral representation can be moved into an integer register using a single mov instruction
S
Floating-point constant whose integral representation can be moved into an integer register using a high/lo_sum instruction sequence
T
Memory address aligned to an 8-byte boundary
U
Even register
W
Memory address for e constraint registers.

TMS320C3x/C4x--c4x.h
a
Auxiliary (address) register (ar0-ar7)
b
Stack pointer register (sp)
c
Standard (32-bit) precision integer register
f
Extended (40-bit) precision register (r0-r11)
k
Block count register (bk)
q
Extended (40-bit) precision low register (r0-r7)
t
Extended (40-bit) precision register (r0-r1)
u
Extended (40-bit) precision register (r2-r3)
v
Repeat count register (rc)
x
Index register (ir0-ir1)
y
Status (condition code) register (st)
z
Data page register (dp)
G
Floating-point zero
H
Immediate 16-bit floating-point constant
I
Signed 16-bit constant
J
Signed 8-bit constant
K
Signed 5-bit constant
L
Unsigned 16-bit constant
M
Unsigned 8-bit constant
N
Ones complement of unsigned 16-bit constant
O
High 16-bit constant (32-bit constant with 16 LSBs zero)
Q
Indirect memory reference with signed 8-bit or index register displacement
R
Indirect memory reference with unsigned 5-bit displacement
S
Indirect memory reference with 1 bit or index register displacement
T
Direct memory reference
U
Symbolic address

S/390 and zSeries--s390.h
a
Address register (general purpose register except r0)
d
Data register (arbitrary general purpose register)
f
Floating-point register
I
Unsigned 8-bit constant (0-255)
J
Unsigned 12-bit constant (0-4095)
K
Signed 16-bit constant (-32768-32767)
L
Unsigned 16-bit constant (0-65535)
Q
Memory reference without index register
S
Symbolic constant suitable for use with the larl instruction

Xstormy16--stormy16.h
a
Register r0.
b
Register r1.
c
Register r2.
d
Register r8.
e
Registers r0 through r7.
t
Registers r0 and r1.
y
The carry register.
z
Registers r8 and r9.
I
A constant between 0 and 3 inclusive.
J
A constant that has exactly one bit set.
K
A constant that has exactly one bit clear.
L
A constant between 0 and 255 inclusive.
M
A constant between -255 and 0 inclusive.
N
A constant between -3 and 0 inclusive.
O
A constant between 1 and 4 inclusive.
P
A constant between -4 and -1 inclusive.
Q
A memory reference that is a stack push.
R
A memory reference that is a stack pop.
S
A memory reference that refers to an constant address of known value.
T
The register indicated by Rx (not implemented yet).
U
A constant that is not between 2 and 15 inclusive.

Xtensa--xtensa.h
a
General-purpose 32-bit register
b
One-bit boolean register
A
MAC16 40-bit accumulator register
I
Signed 12-bit integer constant, for use in MOVI instructions
J
Signed 8-bit integer constant, for use in ADDI instructions
K
Integer constant valid for BccI instructions
L
Unsigned constant valid for BccUI instructions


Using the GNU Compiler Collection (GCC)

Node:MCore Options, Next:IA-64 Options, Previous:AVR Options, Up:Submodel Options

MCore Options

These are the -m options defined for the Motorola M*Core processors.

-mhardlit
-mhardlit
-mno-hardlit
Inline constants into the code stream if it can be done in two instructions or less.
-mdiv
-mdiv
-mno-div
Use the divide instruction. (Enabled by default).
-mrelax-immediate
-mrelax-immediate
-mno-relax-immediate
Allow arbitrary sized immediates in bit operations.
-mwide-bitfields
-mwide-bitfields
-mno-wide-bitfields
Always treat bit-fields as int-sized.
-m4byte-functions
-m4byte-functions
-mno-4byte-functions
Force all functions to be aligned to a four byte boundary.
-mcallgraph-data
-mcallgraph-data
-mno-callgraph-data
Emit callgraph information.
-mslow-bytes
-mslow-bytes
-mno-slow-bytes
Prefer word access when reading byte quantities.
-mlittle-endian
-mlittle-endian
-mbig-endian
Generate code for a little endian target.
-m210
-m210
-m340
Generate code for the 210 processor.


Using the GNU Compiler Collection (GCC)

Node:Min and Max, Next:Volatiles, Up:C++ Extensions

Minimum and Maximum Operators in C++

It is very convenient to have operators which return the "minimum" or the "maximum" of two arguments. In GNU C++ (but not in GNU C),

a <? b
is the minimum, returning the smaller of the numeric values a and b;
a >? b
is the maximum, returning the larger of the numeric values a and b.

These operations are not primitive in ordinary C++, since you can use a macro to return the minimum of two things in C++, as in the following example.

#define MIN(X,Y) ((X) < (Y) ? : (X) : (Y))

You might then use int min = MIN (i, j); to set min to the minimum value of variables i and j.

However, side effects in X or Y may cause unintended behavior. For example, MIN (i++, j++) will fail, incrementing the smaller counter twice. A GNU C extension allows you to write safe macros that avoid this kind of problem (see Naming an Expression's Type). However, writing MIN and MAX as macros also forces you to use function-call notation for a fundamental arithmetic operation. Using GNU C++ extensions, you can write int min = i <? j; instead.

Since <? and >? are built into the compiler, they properly handle expressions with side-effects; int min = i++ <? j++; works correctly.


Using the GNU Compiler Collection (GCC)

Node:MIPS Options, Next:i386 and x86-64 Options, Previous:RT Options, Up:Submodel Options

MIPS Options

These -m options are defined for the MIPS family of computers:

-march=cpu-type
Assume the defaults for the machine type cpu-type when generating instructions. The choices for cpu-type are r2000, r3000, r3900, r4000, r4100, r4300, r4400, r4600, r4650, r5000, r6000, r8000, and orion. Additionally, the r2000, r3000, r4000, r5000, and r6000 can be abbreviated as r2k (or r2K), r3k, etc.
-mtune=cpu-type
Assume the defaults for the machine type cpu-type when scheduling instructions. The choices for cpu-type are r2000, r3000, r3900, r4000, r4100, r4300, r4400, r4600, r4650, r5000, r6000, r8000, and orion. Additionally, the r2000, r3000, r4000, r5000, and r6000 can be abbreviated as r2k (or r2K), r3k, etc. While picking a specific cpu-type will schedule things appropriately for that particular chip, the compiler will not generate any code that does not meet level 1 of the MIPS ISA (instruction set architecture) without a -mipsX or -mabi switch being used.
-mcpu=cpu-type
This is identical to specifying both -march and -mtune.
-mips1
Issue instructions from level 1 of the MIPS ISA. This is the default. r3000 is the default cpu-type at this ISA level.
-mips2
Issue instructions from level 2 of the MIPS ISA (branch likely, square root instructions). r6000 is the default cpu-type at this ISA level.
-mips3
Issue instructions from level 3 of the MIPS ISA (64-bit instructions). r4000 is the default cpu-type at this ISA level.
-mips4
Issue instructions from level 4 of the MIPS ISA (conditional move, prefetch, enhanced FPU instructions). r8000 is the default cpu-type at this ISA level.
-mfp32
Assume that 32 32-bit floating point registers are available. This is the default.
-mfp64
Assume that 32 64-bit floating point registers are available. This is the default when the -mips3 option is used.
-mfused-madd
-mno-fused-madd
Generate code that uses (does not use) the floating point multiply and accumulate instructions, when they are available. These instructions are generated by default if they are available, but this may be undesirable if the extra precision causes problems or on certain chips in the mode where denormals are rounded to zero where denormals generated by multiply and accumulate instructions cause exceptions anyway.
-mgp32
Assume that 32 32-bit general purpose registers are available. This is the default.
-mgp64
Assume that 32 64-bit general purpose registers are available. This is the default when the -mips3 option is used.
-mint64
Force int and long types to be 64 bits wide. See -mlong32 for an explanation of the default, and the width of pointers.
-mlong64
Force long types to be 64 bits wide. See -mlong32 for an explanation of the default, and the width of pointers.
-mlong32
Force long, int, and pointer types to be 32 bits wide.

If none of -mlong32, -mlong64, or -mint64 are set, the size of ints, longs, and pointers depends on the ABI and ISA chosen. For -mabi=32, and -mabi=n32, ints and longs are 32 bits wide. For -mabi=64, ints are 32 bits, and longs are 64 bits wide. For -mabi=eabi and either -mips1 or -mips2, ints and longs are 32 bits wide. For -mabi=eabi and higher ISAs, ints are 32 bits, and longs are 64 bits wide. The width of pointer types is the smaller of the width of longs or the width of general purpose registers (which in turn depends on the ISA).

-mabi=32
-mabi=o64
-mabi=n32
-mabi=64
-mabi=eabi
Generate code for the indicated ABI. The default instruction level is -mips1 for 32, -mips3 for n32, and -mips4 otherwise. Conversely, with -mips1 or -mips2, the default ABI is 32; otherwise, the default ABI is 64.
-mmips-as
Generate code for the MIPS assembler, and invoke mips-tfile to add normal debug information. This is the default for all platforms except for the OSF/1 reference platform, using the OSF/rose object format. If the either of the -gstabs or -gstabs+ switches are used, the mips-tfile program will encapsulate the stabs within MIPS ECOFF.
-mgas
Generate code for the GNU assembler. This is the default on the OSF/1 reference platform, using the OSF/rose object format. Also, this is the default if the configure option --with-gnu-as is used.
-msplit-addresses
-mno-split-addresses
Generate code to load the high and low parts of address constants separately. This allows GCC to optimize away redundant loads of the high order bits of addresses. This optimization requires GNU as and GNU ld. This optimization is enabled by default for some embedded targets where GNU as and GNU ld are standard.
-mrnames
-mno-rnames
The -mrnames switch says to output code using the MIPS software names for the registers, instead of the hardware names (ie, a0 instead of $4). The only known assembler that supports this option is the Algorithmics assembler.
-mgpopt
-mno-gpopt
The -mgpopt switch says to write all of the data declarations before the instructions in the text section, this allows the MIPS assembler to generate one word memory references instead of using two words for short global or static data items. This is on by default if optimization is selected.
-mstats
-mno-stats
For each non-inline function processed, the -mstats switch causes the compiler to emit one line to the standard error file to print statistics about the program (number of registers saved, stack size, etc.).
-mmemcpy
-mno-memcpy
The -mmemcpy switch makes all block moves call the appropriate string function (memcpy or bcopy) instead of possibly generating inline code.
-mmips-tfile
-mno-mips-tfile
The -mno-mips-tfile switch causes the compiler not postprocess the object file with the mips-tfile program, after the MIPS assembler has generated it to add debug support. If mips-tfile is not run, then no local variables will be available to the debugger. In addition, stage2 and stage3 objects will have the temporary file names passed to the assembler embedded in the object file, which means the objects will not compare the same. The -mno-mips-tfile switch should only be used when there are bugs in the mips-tfile program that prevents compilation.
-msoft-float
Generate output containing library calls for floating point. Warning: the requisite libraries are not part of GCC. Normally the facilities of the machine's usual C compiler are used, but this can't be done directly in cross-compilation. You must make your own arrangements to provide suitable library functions for cross-compilation.
-mhard-float
Generate output containing floating point instructions. This is the default if you use the unmodified sources.
-mabicalls
-mno-abicalls
Emit (or do not emit) the pseudo operations .abicalls, .cpload, and .cprestore that some System V.4 ports use for position independent code.
-mlong-calls
-mno-long-calls
Do all calls with the JALR instruction, which requires loading up a function's address into a register before the call. You need to use this switch, if you call outside of the current 512 megabyte segment to functions that are not through pointers.
-mhalf-pic
-mno-half-pic
Put pointers to extern references into the data section and load them up, rather than put the references in the text section.
-membedded-pic
-mno-embedded-pic
Generate PIC code suitable for some embedded systems. All calls are made using PC relative address, and all data is addressed using the $gp register. No more than 65536 bytes of global data may be used. This requires GNU as and GNU ld which do most of the work. This currently only works on targets which use ECOFF; it does not work with ELF.
-membedded-data
-mno-embedded-data
Allocate variables to the read-only data section first if possible, then next in the small data section if possible, otherwise in data. This gives slightly slower code than the default, but reduces the amount of RAM required when executing, and thus may be preferred for some embedded systems.
-muninit-const-in-rodata
-mno-uninit-const-in-rodata
When used together with -membedded-data, it will always store uninitialized const variables in the read-only data section.
-msingle-float
-mdouble-float
The -msingle-float switch tells gcc to assume that the floating point coprocessor only supports single precision operations, as on the r4650 chip. The -mdouble-float switch permits gcc to use double precision operations. This is the default.
-mmad
-mno-mad
Permit use of the mad, madu and mul instructions, as on the r4650 chip.
-m4650
Turns on -msingle-float, -mmad, and, at least for now, -mcpu=r4650.
-mips16
-mno-mips16
Enable 16-bit instructions.
-mentry
Use the entry and exit pseudo ops. This option can only be used with -mips16.
-EL
Compile code for the processor in little endian mode. The requisite libraries are assumed to exist.
-EB
Compile code for the processor in big endian mode. The requisite libraries are assumed to exist.
-G num
Put global and static items less than or equal to num bytes into the small data or bss sections instead of the normal data or bss section. This allows the assembler to emit one word memory reference instructions based on the global pointer (gp or $28), instead of the normal two words used. By default, num is 8 when the MIPS assembler is used, and 0 when the GNU assembler is used. The -G num switch is also passed to the assembler and linker. All modules should be compiled with the same -G num value.
-nocpp
Tell the MIPS assembler to not run its preprocessor over user assembler files (with a .s suffix) when assembling them.
-mfix7000
Pass an option to gas which will cause nops to be inserted if the read of the destination register of an mfhi or mflo instruction occurs in the following two instructions.
-no-crt0
Do not include the default crt0.
-mflush-func=func
-mno-flush-func
Specifies the function to call to flush the I and D caches, or to not call any such function. If called, the function must take the same arguments as the common _flush_func(), that is, the address of the memory range for which the cache is being flushed, the size of the memory range, and the number 3 (to flush both caches). The default depends on the target gcc was configured for, but commonly is either _flush_func or __cpu_flush.

These options are defined by the macro TARGET_SWITCHES in the machine description. The default for the options is also defined by that macro, which enables you to change the defaults.


Using the GNU Compiler Collection (GCC)

Node:Mixed Declarations, Next:Function Attributes, Previous:Case Ranges, Up:C Extensions

Mixed Declarations and Code

ISO C99 and ISO C++ allow declarations and code to be freely mixed within compound statements. As an extension, GCC also allows this in C89 mode. For example, you could do:

int i;
...
i++;
int j = i + 2;

Each identifier is visible from where it is declared until the end of the enclosing block.


Using the GNU Compiler Collection (GCC)

Node:MMIX Options, Next:PDP-11 Options, Previous:CRIS Options, Up:Submodel Options

MMIX Options

These options are defined for the MMIX:

-mlibfuncs
-mno-libfuncs
Specify that intrinsic library functions are being compiled, passing all values in registers, no matter the size.
-mepsilon
-mno-epsilon
Generate floating-point comparison instructions that compare with respect to the rE epsilon register.
-mabi=mmixware
-mabi=gnu
Generate code that passes function parameters and return values that (in the called function) are seen as registers $0 and up, as opposed to the GNU ABI which uses global registers $231 and up.
-mzero-extend
-mno-zero-extend
When reading data from memory in sizes shorter than 64 bits, use (do not use) zero-extending load instructions by default, rather than sign-extending ones.
-mknuthdiv
-mno-knuthdiv
Make the result of a division yielding a remainder have the same sign as the divisor. With the default, -mno-knuthdiv, the sign of the remainder follows the sign of the dividend. Both methods are arithmetically valid, the latter being almost exclusively used.
-mtoplevel-symbols
-mno-toplevel-symbols
Prepend (do not prepend) a : to all global symbols, so the assembly code can be used with the PREFIX assembly directive.
-melf
Generate an executable in the ELF format, rather than the default mmo format used by the mmix simulator.
-mbranch-predict
-mno-branch-predict
Use (do not use) the probable-branch instructions, when static branch prediction indicates a probable branch.
-mbase-addresses
-mno-base-addresses
Generate (do not generate) code that uses base addresses. Using a base address automatically generates a request (handled by the assembler and the linker) for a constant to be set up in a global register. The register is used for one or more base address requests within the range 0 to 255 from the value held in the register. The generally leads to short and fast code, but the number of different data items that can be addressed is limited. This means that a program that uses lots of static data may require -mno-base-addresses.


Using the GNU Compiler Collection (GCC)

Node:MN10200 Options, Next:MN10300 Options, Previous:ARM Options, Up:Submodel Options

MN10200 Options

These -m options are defined for Matsushita MN10200 architectures:

-mrelax
Indicate to the linker that it should perform a relaxation optimization pass to shorten branches, calls and absolute memory addresses. This option only has an effect when used on the command line for the final link step.

This option makes symbolic debugging impossible.


Using the GNU Compiler Collection (GCC)

Node:MN10300 Options, Next:M32R/D Options, Previous:MN10200 Options, Up:Submodel Options

MN10300 Options

These -m options are defined for Matsushita MN10300 architectures:

-mmult-bug
Generate code to avoid bugs in the multiply instructions for the MN10300 processors. This is the default.
-mno-mult-bug
Do not generate code to avoid bugs in the multiply instructions for the MN10300 processors.
-mam33
Generate code which uses features specific to the AM33 processor.
-mno-am33
Do not generate code which uses features specific to the AM33 processor. This is the default.
-mno-crt0
Do not link in the C run-time initialization object file.
-mrelax
Indicate to the linker that it should perform a relaxation optimization pass to shorten branches, calls and absolute memory addresses. This option only has an effect when used on the command line for the final link step.

This option makes symbolic debugging impossible.


Using the GNU Compiler Collection (GCC)

Node:Modifiers, Next:Machine Constraints, Previous:Multi-Alternative, Up:Constraints

Constraint Modifier Characters

Here are constraint modifier characters.

=
Means that this operand is write-only for this instruction: the previous value is discarded and replaced by output data.
+
Means that this operand is both read and written by the instruction.

When the compiler fixes up the operands to satisfy the constraints, it needs to know which operands are inputs to the instruction and which are outputs from it. = identifies an output; + identifies an operand that is both input and output; all other operands are assumed to be input only.

If you specify = or + in a constraint, you put it in the first character of the constraint string.

&
Means (in a particular alternative) that this operand is an earlyclobber operand, which is modified before the instruction is finished using the input operands. Therefore, this operand may not lie in a register that is used as an input operand or as part of any memory address.

& applies only to the alternative in which it is written. In constraints with multiple alternatives, sometimes one alternative requires & while others do not. See, for example, the movdf insn of the 68000.

An input operand can be tied to an earlyclobber operand if its only use as an input occurs before the early result is written. Adding alternatives of this form often allows GCC to produce better code when only some of the inputs can be affected by the earlyclobber. See, for example, the mulsi3 insn of the ARM.

& does not obviate the need to write =.

%
Declares the instruction to be commutative for this operand and the following operand. This means that the compiler may interchange the two operands if that is the cheapest way to make all operands fit the constraints.
#
Says that all following characters, up to the next comma, are to be ignored as a constraint. They are significant only for choosing register preferences.
*
Says that the following character should be ignored when choosing register preferences. * has no effect on the meaning of the constraint as a constraint, and no effect on reloading.


Using the GNU Compiler Collection (GCC)

Node:Multi-Alternative, Next:Modifiers, Previous:Simple Constraints, Up:Constraints

Multiple Alternative Constraints

Sometimes a single instruction has multiple alternative sets of possible operands. For example, on the 68000, a logical-or instruction can combine register or an immediate value into memory, or it can combine any kind of operand into a register; but it cannot combine one memory location into another.

These constraints are represented as multiple alternatives. An alternative can be described by a series of letters for each operand. The overall constraint for an operand is made from the letters for this operand from the first alternative, a comma, the letters for this operand from the second alternative, a comma, and so on until the last alternative.

If all the operands fit any one alternative, the instruction is valid. Otherwise, for each alternative, the compiler counts how many instructions must be added to copy the operands so that that alternative applies. The alternative requiring the least copying is chosen. If two alternatives need the same amount of copying, the one that comes first is chosen. These choices can be altered with the ? and ! characters:

?
Disparage slightly the alternative that the ? appears in, as a choice when no alternative applies exactly. The compiler regards this alternative as one unit more costly for each ? that appears in it.
!
Disparage severely the alternative that the ! appears in. This alternative can still be used if it fits without reloading, but if reloading is needed, some other alternative will be used.


Using the GNU Compiler Collection (GCC)

Node:Multi-line Strings, Next:Subscripting, Previous:Escaped Newlines, Up:C Extensions

String Literals with Embedded Newlines

As an extension, GNU CPP permits string literals to cross multiple lines without escaping the embedded newlines. Each embedded newline is replaced with a single \n character in the resulting string literal, regardless of what form the newline took originally.

CPP currently allows such strings in directives as well (other than the #include family). This is deprecated and will eventually be removed.


Using the GNU Compiler Collection (GCC)

Node:Naming Types, Next:Typeof, Previous:Constructing Calls, Up:C Extensions

Naming an Expression's Type

You can give a name to the type of an expression using a typedef declaration with an initializer. Here is how to define name as a type name for the type of exp:

typedef name = exp;

This is useful in conjunction with the statements-within-expressions feature. Here is how the two together can be used to define a safe "maximum" macro that operates on any arithmetic type:

#define max(a,b) \
  ({typedef _ta = (a), _tb = (b);  \
    _ta _a = (a); _tb _b = (b);     \
    _a > _b ? _a : _b; })

The reason for using names that start with underscores for the local variables is to avoid conflicts with variable names that occur within the expressions that are substituted for a and b. Eventually we hope to design a new form of declaration syntax that allows you to declare variables whose scopes start only after their initializers; this will be a more reliable way to prevent such conflicts.


Using the GNU Compiler Collection (GCC)

Node:Nested Functions, Next:Constructing Calls, Previous:Labels as Values, Up:C Extensions

Nested Functions

A nested function is a function defined inside another function. (Nested functions are not supported for GNU C++.) The nested function's name is local to the block where it is defined. For example, here we define a nested function named square, and call it twice:

foo (double a, double b)
{
  double square (double z) { return z * z; }

  return square (a) + square (b);
}

The nested function can access all the variables of the containing function that are visible at the point of its definition. This is called lexical scoping. For example, here we show a nested function which uses an inherited variable named offset:

bar (int *array, int offset, int size)
{
  int access (int *array, int index)
    { return array[index + offset]; }
  int i;
  ...
  for (i = 0; i < size; i++)
    ... access (array, i) ...
}

Nested function definitions are permitted within functions in the places where variable definitions are allowed; that is, in any block, before the first statement in the block.

It is possible to call the nested function from outside the scope of its name by storing its address or passing the address to another function:

hack (int *array, int size)
{
  void store (int index, int value)
    { array[index] = value; }

  intermediate (store, size);
}

Here, the function intermediate receives the address of store as an argument. If intermediate calls store, the arguments given to store are used to store into array. But this technique works only so long as the containing function (hack, in this example) does not exit.

If you try to call the nested function through its address after the containing function has exited, all hell will break loose. If you try to call it after a containing scope level has exited, and if it refers to some of the variables that are no longer in scope, you may be lucky, but it's not wise to take the risk. If, however, the nested function does not refer to anything that has gone out of scope, you should be safe.

GCC implements taking the address of a nested function using a technique called trampolines. A paper describing them is available as http://people.debian.org/~karlheg/Usenix88-lexic.pdf.

A nested function can jump to a label inherited from a containing function, provided the label was explicitly declared in the containing function (see Local Labels). Such a jump returns instantly to the containing function, exiting the nested function which did the goto and any intermediate functions as well. Here is an example:

bar (int *array, int offset, int size)
{
  __label__ failure;
  int access (int *array, int index)
    {
      if (index > size)
        goto failure;
      return array[index + offset];
    }
  int i;
  ...
  for (i = 0; i < size; i++)
    ... access (array, i) ...
  ...
  return 0;

 /* Control comes here from access
    if it detects an error.  */
 failure:
  return -1;
}

A nested function always has internal linkage. Declaring one with extern is erroneous. If you need to declare the nested function before its definition, use auto (which is otherwise meaningless for function declarations).

bar (int *array, int offset, int size)
{
  __label__ failure;
  auto int access (int *, int);
  ...
  int access (int *array, int index)
    {
      if (index > size)
        goto failure;
      return array[index + offset];
    }
  ...
}


Using the GNU Compiler Collection (GCC)

Node:Non-bugs, Next:Warnings and Errors, Previous:Protoize Caveats, Up:Trouble

Certain Changes We Don't Want to Make

This section lists changes that people frequently request, but which we do not make because we think GCC is better without them.

  • Checking the number and type of arguments to a function which has an old-fashioned definition and no prototype.

    Such a feature would work only occasionally--only for calls that appear in the same file as the called function, following the definition. The only way to check all calls reliably is to add a prototype for the function. But adding a prototype eliminates the motivation for this feature. So the feature is not worthwhile.

  • Warning about using an expression whose type is signed as a shift count.

    Shift count operands are probably signed more often than unsigned. Warning about this would cause far more annoyance than good.

  • Warning about assigning a signed value to an unsigned variable.

    Such assignments must be very common; warning about them would cause more annoyance than good.

  • Warning when a non-void function value is ignored.

    Coming as I do from a Lisp background, I balk at the idea that there is something dangerous about discarding a value. There are functions that return values which some callers may find useful; it makes no sense to clutter the program with a cast to void whenever the value isn't useful.

  • Making -fshort-enums the default.

    This would cause storage layout to be incompatible with most other C compilers. And it doesn't seem very important, given that you can get the same result in other ways. The case where it matters most is when the enumeration-valued object is inside a structure, and in that case you can specify a field width explicitly.

  • Making bit-fields unsigned by default on particular machines where "the ABI standard" says to do so.

    The ISO C standard leaves it up to the implementation whether a bit-field declared plain int is signed or not. This in effect creates two alternative dialects of C.

    The GNU C compiler supports both dialects; you can specify the signed dialect with -fsigned-bitfields and the unsigned dialect with -funsigned-bitfields. However, this leaves open the question of which dialect to use by default.

    Currently, the preferred dialect makes plain bit-fields signed, because this is simplest. Since int is the same as signed int in every other context, it is cleanest for them to be the same in bit-fields as well.

    Some computer manufacturers have published Application Binary Interface standards which specify that plain bit-fields should be unsigned. It is a mistake, however, to say anything about this issue in an ABI. This is because the handling of plain bit-fields distinguishes two dialects of C. Both dialects are meaningful on every type of machine. Whether a particular object file was compiled using signed bit-fields or unsigned is of no concern to other object files, even if they access the same bit-fields in the same data structures.

    A given program is written in one or the other of these two dialects. The program stands a chance to work on most any machine if it is compiled with the proper dialect. It is unlikely to work at all if compiled with the wrong dialect.

    Many users appreciate the GNU C compiler because it provides an environment that is uniform across machines. These users would be inconvenienced if the compiler treated plain bit-fields differently on certain machines.

    Occasionally users write programs intended only for a particular machine type. On these occasions, the users would benefit if the GNU C compiler were to support by default the same dialect as the other compilers on that machine. But such applications are rare. And users writing a program to run on more than one type of machine cannot possibly benefit from this kind of compatibility.

    This is why GCC does and will treat plain bit-fields in the same fashion on all types of machines (by default).

    There are some arguments for making bit-fields unsigned by default on all machines. If, for example, this becomes a universal de facto standard, it would make sense for GCC to go along with it. This is something to be considered in the future.

    (Of course, users strongly concerned about portability should indicate explicitly in each bit-field whether it is signed or not. In this way, they write programs which have the same meaning in both C dialects.)

  • Undefining __STDC__ when -ansi is not used.

    Currently, GCC defines __STDC__ as long as you don't use -traditional. This provides good results in practice.

    Programmers normally use conditionals on __STDC__ to ask whether it is safe to use certain features of ISO C, such as function prototypes or ISO token concatenation. Since plain gcc supports all the features of ISO C, the correct answer to these questions is "yes".

    Some users try to use __STDC__ to check for the availability of certain library facilities. This is actually incorrect usage in an ISO C program, because the ISO C standard says that a conforming freestanding implementation should define __STDC__ even though it does not have the library facilities. gcc -ansi -pedantic is a conforming freestanding implementation, and it is therefore required to define __STDC__, even though it does not come with an ISO C library.

    Sometimes people say that defining __STDC__ in a compiler that does not completely conform to the ISO C standard somehow violates the standard. This is illogical. The standard is a standard for compilers that claim to support ISO C, such as gcc -ansi--not for other compilers such as plain gcc. Whatever the ISO C standard says is relevant to the design of plain gcc without -ansi only for pragmatic reasons, not as a requirement.

    GCC normally defines __STDC__ to be 1, and in addition defines __STRICT_ANSI__ if you specify the -ansi option, or a -std option for strict conformance to some version of ISO C. On some hosts, system include files use a different convention, where __STDC__ is normally 0, but is 1 if the user specifies strict conformance to the C Standard. GCC follows the host convention when processing system include files, but when processing user files it follows the usual GNU C convention.

  • Undefining __STDC__ in C++.

    Programs written to compile with C++-to-C translators get the value of __STDC__ that goes with the C compiler that is subsequently used. These programs must test __STDC__ to determine what kind of C preprocessor that compiler uses: whether they should concatenate tokens in the ISO C fashion or in the traditional fashion.

    These programs work properly with GNU C++ if __STDC__ is defined. They would not work otherwise.

    In addition, many header files are written to provide prototypes in ISO C but not in traditional C. Many of these header files can work without change in C++ provided __STDC__ is defined. If __STDC__ is not defined, they will all fail, and will all need to be changed to test explicitly for C++ as well.

  • Deleting "empty" loops.

    Historically, GCC has not deleted "empty" loops under the assumption that the most likely reason you would put one in a program is to have a delay, so deleting them will not make real programs run any faster.

    However, the rationale here is that optimization of a nonempty loop cannot produce an empty one, which holds for C but is not always the case for C++.

    Moreover, with -funroll-loops small "empty" loops are already removed, so the current behavior is both sub-optimal and inconsistent and will change in the future.

  • Making side effects happen in the same order as in some other compiler.

    It is never safe to depend on the order of evaluation of side effects. For example, a function call like this may very well behave differently from one compiler to another:

    void func (int, int);

int i = 2;
func (i++, i++);

    There is no guarantee (in either the C or the C++ standard language definitions) that the increments will be evaluated in any particular order. Either increment might happen first. func might get the arguments 2, 3, or it might get 3, 2, or even 2, 2.

  • Not allowing structures with volatile fields in registers.

    Strictly speaking, there is no prohibition in the ISO C standard against allowing structures with volatile fields in registers, but it does not seem to make any sense and is probably not what you wanted to do. So the compiler will give an error message in this case.

  • Making certain warnings into errors by default.

    Some ISO C testsuites report failure when the compiler does not produce an error message for a certain program.

    ISO C requires a "diagnostic" message for certain kinds of invalid programs, but a warning is defined by GCC to count as a diagnostic. If GCC produces a warning but not an error, that is correct ISO C support. If test suites call this "failure", they should be run with the GCC option -pedantic-errors, which will turn these warnings into errors.


Using the GNU Compiler Collection (GCC)

Node:NS32K Options, Next:AVR Options, Previous:ARC Options, Up:Submodel Options

NS32K Options

These are the -m options defined for the 32000 series. The default values for these options depends on which style of 32000 was selected when the compiler was configured; the defaults for the most common choices are given below.

-m32032
-m32032
Generate output for a 32032. This is the default when the compiler is configured for 32032 and 32016 based systems.
-m32332
-m32332
Generate output for a 32332. This is the default when the compiler is configured for 32332-based systems.
-m32532
-m32532
Generate output for a 32532. This is the default when the compiler is configured for 32532-based systems.
-m32081
Generate output containing 32081 instructions for floating point. This is the default for all systems.
-m32381
Generate output containing 32381 instructions for floating point. This also implies -m32081. The 32381 is only compatible with the 32332 and 32532 cpus. This is the default for the pc532-netbsd configuration.
-mmulti-add
Try and generate multiply-add floating point instructions polyF and dotF. This option is only available if the -m32381 option is in effect. Using these instructions requires changes to register allocation which generally has a negative impact on performance. This option should only be enabled when compiling code particularly likely to make heavy use of multiply-add instructions.
-mnomulti-add
Do not try and generate multiply-add floating point instructions polyF and dotF. This is the default on all platforms.
-msoft-float
Generate output containing library calls for floating point. Warning: the requisite libraries may not be available.
-mnobitfield
Do not use the bit-field instructions. On some machines it is faster to use shifting and masking operations. This is the default for the pc532.
-mbitfield
Do use the bit-field instructions. This is the default for all platforms except the pc532.
-mrtd
Use a different function-calling convention, in which functions that take a fixed number of arguments return pop their arguments on return with the ret instruction.

This calling convention is incompatible with the one normally used on Unix, so you cannot use it if you need to call libraries compiled with the Unix compiler.

Also, you must provide function prototypes for all functions that take variable numbers of arguments (including printf); otherwise incorrect code will be generated for calls to those functions.

In addition, seriously incorrect code will result if you call a function with too many arguments. (Normally, extra arguments are harmlessly ignored.)

This option takes its name from the 680x0 rtd instruction.

-mregparam
Use a different function-calling convention where the first two arguments are passed in registers.

This calling convention is incompatible with the one normally used on Unix, so you cannot use it if you need to call libraries compiled with the Unix compiler.

-mnoregparam
Do not pass any arguments in registers. This is the default for all targets.
-msb
It is OK to use the sb as an index register which is always loaded with zero. This is the default for the pc532-netbsd target.
-mnosb
The sb register is not available for use or has not been initialized to zero by the run time system. This is the default for all targets except the pc532-netbsd. It is also implied whenever -mhimem or -fpic is set.
-mhimem
Many ns32000 series addressing modes use displacements of up to 512MB. If an address is above 512MB then displacements from zero can not be used. This option causes code to be generated which can be loaded above 512MB. This may be useful for operating systems or ROM code.
-mnohimem
Assume code will be loaded in the first 512MB of virtual address space. This is the default for all platforms.


Using the GNU Compiler Collection (GCC)

Node:Objective-C Dialect Options, Next:Language Independent Options, Previous:C++ Dialect Options, Up:Invoking GCC

Options Controlling Objective-C Dialect

This section describes the command-line options that are only meaningful for Objective-C programs; but you can also use most of the GNU compiler options regardless of what language your program is in. For example, you might compile a file some_class.m like this:

gcc -g -fgnu-runtime -O -c some_class.m

In this example, only -fgnu-runtime is an option meant only for Objective-C programs; you can use the other options with any language supported by GCC.

Here is a list of options that are only for compiling Objective-C programs:

-fconstant-string-class=class-name
Use class-name as the name of the class to instantiate for each literal string specified with the syntax @"...". The default class name is NXConstantString.
-fgnu-runtime
Generate object code compatible with the standard GNU Objective-C runtime. This is the default for most types of systems.
-fnext-runtime
Generate output compatible with the NeXT runtime. This is the default for NeXT-based systems, including Darwin and Mac OS X.
-gen-decls
Dump interface declarations for all classes seen in the source file to a file named sourcename.decl.
-Wno-protocol
Do not warn if methods required by a protocol are not implemented in the class adopting it.
-Wselector
Warn if a selector has multiple methods of different types defined.


Using the GNU Compiler Collection (GCC)

Node:Objective-C, Next:Gcov, Previous:C++ Extensions, Up:Top

GNU Objective-C runtime features

This document is meant to describe some of the GNU Objective-C runtime features. It is not intended to teach you Objective-C, there are several resources on the Internet that present the language. Questions and comments about this document to Ovidiu Predescu ovidiu@cup.hp.com.

  • Executing code before main:
  • Type encoding:
  • Garbage Collection:
  • Constant string objects:
  • compatibility_alias:


Using the GNU Compiler Collection (GCC)

Node:Optimize Options, Next:Preprocessor Options, Previous:Debugging Options, Up:Invoking GCC

Options That Control Optimization

These options control various sorts of optimizations:

-O
-O1
Optimize. Optimizing compilation takes somewhat more time, and a lot more memory for a large function.

Without -O, the compiler's goal is to reduce the cost of compilation and to make debugging produce the expected results. Statements are independent: if you stop the program with a breakpoint between statements, you can then assign a new value to any variable or change the program counter to any other statement in the function and get exactly the results you would expect from the source code.

With -O, the compiler tries to reduce code size and execution time, without performing any optimizations that take a great deal of compilation time.

-O2
Optimize even more. GCC performs nearly all supported optimizations that do not involve a space-speed tradeoff. The compiler does not perform loop unrolling or function inlining when you specify -O2. As compared to -O, this option increases both compilation time and the performance of the generated code.

-O2 turns on all optional optimizations except for loop unrolling, function inlining, and register renaming. It also turns on the -fforce-mem option on all machines and frame pointer elimination on machines where doing so does not interfere with debugging.

Please note the warning under -fgcse about invoking -O2 on programs that use computed gotos.

-O3
Optimize yet more. -O3 turns on all optimizations specified by -O2 and also turns on the -finline-functions and -frename-registers options.
-O0
Do not optimize.
-Os
Optimize for size. -Os enables all -O2 optimizations that do not typically increase code size. It also performs further optimizations designed to reduce code size.

If you use multiple -O options, with or without level numbers, the last such option is the one that is effective.

Options of the form -fflag specify machine-independent flags. Most flags have both positive and negative forms; the negative form of -ffoo would be -fno-foo. In the table below, only one of the forms is listed--the one which is not the default. You can figure out the other form by either removing no- or adding it.

-ffloat-store
Do not store floating point variables in registers, and inhibit other options that might change whether a floating point value is taken from a register or memory.

This option prevents undesirable excess precision on machines such as the 68000 where the floating registers (of the 68881) keep more precision than a double is supposed to have. Similarly for the x86 architecture. For most programs, the excess precision does only good, but a few programs rely on the precise definition of IEEE floating point. Use -ffloat-store for such programs, after modifying them to store all pertinent intermediate computations into variables.

-fno-default-inline
Do not make member functions inline by default merely because they are defined inside the class scope (C++ only). Otherwise, when you specify -O, member functions defined inside class scope are compiled inline by default; i.e., you don't need to add inline in front of the member function name.
-fno-defer-pop
Always pop the arguments to each function call as soon as that function returns. For machines which must pop arguments after a function call, the compiler normally lets arguments accumulate on the stack for several function calls and pops them all at once.
-fforce-mem
Force memory operands to be copied into registers before doing arithmetic on them. This produces better code by making all memory references potential common subexpressions. When they are not common subexpressions, instruction combination should eliminate the separate register-load. The -O2 option turns on this option.
-fforce-addr
Force memory address constants to be copied into registers before doing arithmetic on them. This may produce better code just as -fforce-mem may.
-fomit-frame-pointer
Don't keep the frame pointer in a register for functions that don't need one. This avoids the instructions to save, set up and restore frame pointers; it also makes an extra register available in many functions. It also makes debugging impossible on some machines.

On some machines, such as the VAX, this flag has no effect, because the standard calling sequence automatically handles the frame pointer and nothing is saved by pretending it doesn't exist. The machine-description macro FRAME_POINTER_REQUIRED controls whether a target machine supports this flag. See Register Usage.

-foptimize-sibling-calls
Optimize sibling and tail recursive calls.
-ftrapv
This option generates traps for signed overflow on addition, subtraction, multiplication operations.
-fno-inline
Don't pay attention to the inline keyword. Normally this option is used to keep the compiler from expanding any functions inline. Note that if you are not optimizing, no functions can be expanded inline.
-finline-functions
Integrate all simple functions into their callers. The compiler heuristically decides which functions are simple enough to be worth integrating in this way.

If all calls to a given function are integrated, and the function is declared static, then the function is normally not output as assembler code in its own right.

-finline-limit=n
By default, gcc limits the size of functions that can be inlined. This flag allows the control of this limit for functions that are explicitly marked as inline (ie marked with the inline keyword or defined within the class definition in c++). n is the size of functions that can be inlined in number of pseudo instructions (not counting parameter handling). The default value of n is 600. Increasing this value can result in more inlined code at the cost of compilation time and memory consumption. Decreasing usually makes the compilation faster and less code will be inlined (which presumably means slower programs). This option is particularly useful for programs that use inlining heavily such as those based on recursive templates with C++.

Note: pseudo instruction represents, in this particular context, an abstract measurement of function's size. In no way, it represents a count of assembly instructions and as such its exact meaning might change from one release to an another.

-fkeep-inline-functions
Even if all calls to a given function are integrated, and the function is declared static, nevertheless output a separate run-time callable version of the function. This switch does not affect extern inline functions.
-fkeep-static-consts
Emit variables declared static const when optimization isn't turned on, even if the variables aren't referenced.

GCC enables this option by default. If you want to force the compiler to check if the variable was referenced, regardless of whether or not optimization is turned on, use the -fno-keep-static-consts option.

-fmerge-constants
Attempt to merge identical constants (string constants and floating point constants) accross compilation units.

This option is default for optimized compilation if assembler and linker support it. Use -fno-merge-constants to inhibit this behavior.

-fmerge-all-constants
Attempt to merge identical constants and identical variables.

This option implies -fmerge-constants. In addition to -fmerge-constants this considers e.g. even constant initialized arrays or initialized constant variables with integral or floating point types. Languages like C or C++ require each non-automatic variable to have distinct location, so using this option will result in non-conforming behavior.

-fno-function-cse
Do not put function addresses in registers; make each instruction that calls a constant function contain the function's address explicitly.

This option results in less efficient code, but some strange hacks that alter the assembler output may be confused by the optimizations performed when this option is not used.

-ffast-math
Sets -fno-math-errno, -funsafe-math-optimizations, and
-fno-trapping-math.

This option causes the preprocessor macro __FAST_MATH__ to be defined.

This option should never be turned on by any -O option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions.

-fno-math-errno
Do not set ERRNO after calling math functions that are executed with a single instruction, e.g., sqrt. A program that relies on IEEE exceptions for math error handling may want to use this flag for speed while maintaining IEEE arithmetic compatibility.

This option should never be turned on by any -O option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions.

The default is -fmath-errno.

-funsafe-math-optimizations
Allow optimizations for floating-point arithmetic that (a) assume that arguments and results are valid and (b) may violate IEEE or ANSI standards. When used at link-time, it may include libraries or startup files that change the default FPU control word or other similar optimizations.

This option should never be turned on by any -O option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions.

The default is -fno-unsafe-math-optimizations.

-fno-trapping-math
Compile code assuming that floating-point operations cannot generate user-visible traps. Setting this option may allow faster code if one relies on "non-stop" IEEE arithmetic, for example.

This option should never be turned on by any -O option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ISO rules/specifications for math functions.

The default is -ftrapping-math.

The following options control specific optimizations. The -O2 option turns on all of these optimizations except -funroll-loops and -funroll-all-loops. On most machines, the -O option turns on the -fthread-jumps and -fdelayed-branch options, but specific machines may handle it differently.

You can use the following flags in the rare cases when "fine-tuning" of optimizations to be performed is desired.

Not all of the optimizations performed by GCC have -f options to control them.

-fstrength-reduce
Perform the optimizations of loop strength reduction and elimination of iteration variables.
-fthread-jumps
Perform optimizations where we check to see if a jump branches to a location where another comparison subsumed by the first is found. If so, the first branch is redirected to either the destination of the second branch or a point immediately following it, depending on whether the condition is known to be true or false.
-fcse-follow-jumps
In common subexpression elimination, scan through jump instructions when the target of the jump is not reached by any other path. For example, when CSE encounters an if statement with an else clause, CSE will follow the jump when the condition tested is false.
-fcse-skip-blocks
This is similar to -fcse-follow-jumps, but causes CSE to follow jumps which conditionally skip over blocks. When CSE encounters a simple if statement with no else clause, -fcse-skip-blocks causes CSE to follow the jump around the body of the if.
-frerun-cse-after-loop
Re-run common subexpression elimination after loop optimizations has been performed.
-frerun-loop-opt
Run the loop optimizer twice.
-fgcse
Perform a global common subexpression elimination pass. This pass also performs global constant and copy propagation.

Note: When compiling a program using computed gotos, a GCC extension, you may get better runtime performance if you disable the global common subexpression elmination pass by adding -fno-gcse to the command line.

-fgcse-lm
When -fgcse-lm is enabled, global common subexpression elimination will attempt to move loads which are only killed by stores into themselves. This allows a loop containing a load/store sequence to be changed to a load outside the loop, and a copy/store within the loop.
-fgcse-sm
When -fgcse-sm is enabled, A store motion pass is run after global common subexpression elimination. This pass will attempt to move stores out of loops. When used in conjunction with -fgcse-lm, loops containing a load/store sequence can be changed to a load before the loop and a store after the loop.
-fdelete-null-pointer-checks
Use global dataflow analysis to identify and eliminate useless checks for null pointers. The compiler assumes that dereferencing a null pointer would have halted the program. If a pointer is checked after it has already been dereferenced, it cannot be null.

In some environments, this assumption is not true, and programs can safely dereference null pointers. Use -fno-delete-null-pointer-checks to disable this optimization for programs which depend on that behavior.

-fexpensive-optimizations
Perform a number of minor optimizations that are relatively expensive.
-foptimize-register-move
-fregmove
Attempt to reassign register numbers in move instructions and as operands of other simple instructions in order to maximize the amount of register tying. This is especially helpful on machines with two-operand instructions. GCC enables this optimization by default with -O2 or higher.

Note -fregmove and -foptimize-register-move are the same optimization.

-fdelayed-branch
If supported for the target machine, attempt to reorder instructions to exploit instruction slots available after delayed branch instructions.
-fschedule-insns
If supported for the target machine, attempt to reorder instructions to eliminate execution stalls due to required data being unavailable. This helps machines that have slow floating point or memory load instructions by allowing other instructions to be issued until the result of the load or floating point instruction is required.
-fschedule-insns2
Similar to -fschedule-insns, but requests an additional pass of instruction scheduling after register allocation has been done. This is especially useful on machines with a relatively small number of registers and where memory load instructions take more than one cycle.
-ffunction-sections
-fdata-sections
Place each function or data item into its own section in the output file if the target supports arbitrary sections. The name of the function or the name of the data item determines the section's name in the output file.

Use these options on systems where the linker can perform optimizations to improve locality of reference in the instruction space. HPPA processors running HP-UX and Sparc processors running Solaris 2 have linkers with such optimizations. Other systems using the ELF object format as well as AIX may have these optimizations in the future.

Only use these options when there are significant benefits from doing so. When you specify these options, the assembler and linker will create larger object and executable files and will also be slower. You will not be able to use gprof on all systems if you specify this option and you may have problems with debugging if you specify both this option and -g.

-fcaller-saves
Enable values to be allocated in registers that will be clobbered by function calls, by emitting extra instructions to save and restore the registers around such calls. Such allocation is done only when it seems to result in better code than would otherwise be produced.

This option is always enabled by default on certain machines, usually those which have no call-preserved registers to use instead.

For all machines, optimization level 2 and higher enables this flag by default.

-funroll-loops
Unroll loops whose number of iterations can be determined at compile time or upon entry to the loop. -funroll-loops implies both -fstrength-reduce and -frerun-cse-after-loop. This option makes code larger, and may or may not make it run faster.
-funroll-all-loops
Unroll all loops, even if their number of iterations is uncertain when the loop is entered. This usually makes programs run more slowly. -funroll-all-loops implies the same options as -funroll-loops,
-fprefetch-loop-arrays
If supported by the target machine, generate instructions to prefetch memory to improve the performance of loops that access large arrays.
-fmove-all-movables
Forces all invariant computations in loops to be moved outside the loop.
-freduce-all-givs
Forces all general-induction variables in loops to be strength-reduced.

Note: When compiling programs written in Fortran, -fmove-all-movables and -freduce-all-givs are enabled by default when you use the optimizer.

These options may generate better or worse code; results are highly dependent on the structure of loops within the source code.

These two options are intended to be removed someday, once they have helped determine the efficacy of various approaches to improving loop optimizations.

Please let us (gcc@gcc.gnu.org and fortran@gnu.org) know how use of these options affects the performance of your production code. We're very interested in code that runs slower when these options are enabled.

-fno-peephole
-fno-peephole2
Disable any machine-specific peephole optimizations. The difference between -fno-peephole and -fno-peephole2 is in how they are implemented in the compiler; some targets use one, some use the other, a few use both.
-fbranch-probabilities
After running a program compiled with -fprofile-arcs (see Options for Debugging Your Program or gcc), you can compile it a second time using -fbranch-probabilities, to improve optimizations based on the number of times each branch was taken. When the program compiled with -fprofile-arcs exits it saves arc execution counts to a file called sourcename.da for each source file The information in this data file is very dependent on the structure of the generated code, so you must use the same source code and the same optimization options for both compilations.

With -fbranch-probabilities, GCC puts a REG_EXEC_COUNT note on the first instruction of each basic block, and a REG_BR_PROB note on each JUMP_INSN and CALL_INSN. These can be used to improve optimization. Currently, they are only used in one place: in reorg.c, instead of guessing which path a branch is mostly to take, the REG_BR_PROB values are used to exactly determine which path is taken more often.

-fno-guess-branch-probability
Do not guess branch probabilities using a randomized model.

Sometimes gcc will opt to use a randomized model to guess branch probabilities, when none are available from either profiling feedback (-fprofile-arcs) or __builtin_expect. This means that different runs of the compiler on the same program may produce different object code.

In a hard real-time system, people don't want different runs of the compiler to produce code that has different behavior; minimizing non-determinism is of paramount import. This switch allows users to reduce non-determinism, possibly at the expense of inferior optimization.

-fstrict-aliasing
Allows the compiler to assume the strictest aliasing rules applicable to the language being compiled. For C (and C++), this activates optimizations based on the type of expressions. In particular, an object of one type is assumed never to reside at the same address as an object of a different type, unless the types are almost the same. For example, an unsigned int can alias an int, but not a void* or a double. A character type may alias any other type.

Pay special attention to code like this:

union a_union {
  int i;
  double d;
};

int f() {
  a_union t;
  t.d = 3.0;
  return t.i;
}
The practice of reading from a different union member than the one most recently written to (called "type-punning") is common. Even with -fstrict-aliasing, type-punning is allowed, provided the memory is accessed through the union type. So, the code above will work as expected. However, this code might not:
int f() {
  a_union t;
  int* ip;
  t.d = 3.0;
  ip = &t.i;
  return *ip;
}

Every language that wishes to perform language-specific alias analysis should define a function that computes, given an tree node, an alias set for the node. Nodes in different alias sets are not allowed to alias. For an example, see the C front-end function c_get_alias_set.

-falign-functions
-falign-functions=n
Align the start of functions to the next power-of-two greater than n, skipping up to n bytes. For instance, -falign-functions=32 aligns functions to the next 32-byte boundary, but -falign-functions=24 would align to the next 32-byte boundary only if this can be done by skipping 23 bytes or less.

-fno-align-functions and -falign-functions=1 are equivalent and mean that functions will not be aligned.

Some assemblers only support this flag when n is a power of two; in that case, it is rounded up.

If n is not specified, use a machine-dependent default.

-falign-labels
-falign-labels=n
Align all branch targets to a power-of-two boundary, skipping up to n bytes like -falign-functions. This option can easily make code slower, because it must insert dummy operations for when the branch target is reached in the usual flow of the code.

If -falign-loops or -falign-jumps are applicable and are greater than this value, then their values are used instead.

If n is not specified, use a machine-dependent default which is very likely to be 1, meaning no alignment.

-falign-loops
-falign-loops=n
Align loops to a power-of-two boundary, skipping up to n bytes like -falign-functions. The hope is that the loop will be executed many times, which will make up for any execution of the dummy operations.

If n is not specified, use a machine-dependent default.

-falign-jumps
-falign-jumps=n
Align branch targets to a power-of-two boundary, for branch targets where the targets can only be reached by jumping, skipping up to n bytes like -falign-functions. In this case, no dummy operations need be executed.

If n is not specified, use a machine-dependent default.

-fssa
Perform optimizations in static single assignment form. Each function's flow graph is translated into SSA form, optimizations are performed, and the flow graph is translated back from SSA form. Users should not specify this option, since it is not yet ready for production use.
-fssa-ccp
Perform Sparse Conditional Constant Propagation in SSA form. Requires -fssa. Like -fssa, this is an experimental feature.
-fssa-dce
Perform aggressive dead-code elimination in SSA form. Requires -fssa. Like -fssa, this is an experimental feature.
-fsingle-precision-constant
Treat floating point constant as single precision constant instead of implicitly converting it to double precision constant.
-frename-registers
Attempt to avoid false dependencies in scheduled code by making use of registers left over after register allocation. This optimization will most benefit processors with lots of registers. It can, however, make debugging impossible, since variables will no longer stay in a "home register".
-fno-cprop-registers
After register allocation and post-register allocation instruction splitting, we perform a copy-propagation pass to try to reduce scheduling dependencies and occasionally eliminate the copy.
--param name=value
In some places, GCC uses various constants to control the amount of optimization that is done. For example, GCC will not inline functions that contain more that a certain number of instructions. You can control some of these constants on the command-line using the --param option.

In each case, the value is an integer. The allowable choices for name are given in the following table:

max-delay-slot-insn-search
The maximum number of instructions to consider when looking for an instruction to fill a delay slot. If more than this arbitrary number of instructions is searched, the time savings from filling the delay slot will be minimal so stop searching. Increasing values mean more aggressive optimization, making the compile time increase with probably small improvement in executable run time.
max-delay-slot-live-search
When trying to fill delay slots, the maximum number of instructions to consider when searching for a block with valid live register information. Increasing this arbitrarily chosen value means more aggressive optimization, increasing the compile time. This parameter should be removed when the delay slot code is rewritten to maintain the control-flow graph.
max-gcse-memory
The approximate maximum amount of memory that will be allocated in order to perform the global common subexpression elimination optimization. If more memory than specified is required, the optimization will not be done.
max-gcse-passes
The maximum number of passes of GCSE to run.
max-pending-list-length
The maximum number of pending dependencies scheduling will allow before flushing the current state and starting over. Large functions with few branches or calls can create excessively large lists which needlessly consume memory and resources.
max-inline-insns
If an function contains more than this many instructions, it will not be inlined. This option is precisely equivalent to -finline-limit.


Using the GNU Compiler Collection (GCC)

Node:Option Index, Next:Index, Previous:Contributors, Up:Top

Option Index

GCC's command line options are indexed here without any initial - or --. Where an option has both positive and negative forms (such as -foption and -fno-option), relevant entries in the manual are indexed under the most appropriate form; it may sometimes be useful to look up both forms.

  • ###: Overall Options
  • $: Preprocessor Options
  • A: Preprocessor Options
  • a: Debugging Options
  • A-: Preprocessor Options
  • ansi: Non-bugs, Other Builtins, Preprocessor Options, C Dialect Options, Standards
  • aux-info: C Dialect Options
  • b: Target Options
  • B: Directory Options
  • bcopy-builtin: PDP-11 Options
  • c: Link Options
  • C: Preprocessor Options
  • c: Overall Options
  • D: Preprocessor Options
  • d: Debugging Options
  • da: Debugging Options
  • dA: Debugging Options
  • dB: Debugging Options
  • db: Debugging Options
  • dC: Debugging Options
  • dc: Debugging Options
  • dD: Preprocessor Options, Debugging Options
  • dd: Debugging Options
  • dE: Debugging Options
  • de: Debugging Options
  • dF: Debugging Options
  • df: Debugging Options
  • dG: Debugging Options
  • dg: Debugging Options
  • dh: Debugging Options
  • dI: Preprocessor Options
  • di: Debugging Options
  • dj: Debugging Options
  • dk: Debugging Options
  • dL: Debugging Options
  • dl: Debugging Options
  • dM: Preprocessor Options
  • dm: Debugging Options
  • dM: Debugging Options
  • dN: Preprocessor Options, Debugging Options
  • dn: Debugging Options
  • do: Debugging Options
  • dP: Debugging Options
  • dp: Debugging Options
  • dR: Debugging Options
  • dr: Debugging Options
  • dS: Debugging Options
  • ds: Debugging Options
  • dt: Debugging Options
  • dumpmachine: Debugging Options
  • dumpspecs: Debugging Options
  • dumpversion: Debugging Options
  • dv: Debugging Options
  • dw: Debugging Options
  • dx: Debugging Options
  • dX: Debugging Options
  • dy: Debugging Options
  • dz: Debugging Options
  • E: Link Options, Overall Options
  • EB: ARC Options, MIPS Options
  • EL: ARC Options, MIPS Options
  • falign-functions: Optimize Options
  • falign-jumps: Optimize Options
  • falign-labels: Optimize Options
  • falign-loops: Optimize Options
  • fallow-single-precision: C Dialect Options
  • falt-external-templates: Template Instantiation, C++ Dialect Options
  • fargument-alias: Code Gen Options
  • fargument-noalias: Code Gen Options
  • fargument-noalias-global: Code Gen Options
  • fbranch-probabilities: Optimize Options
  • fcall-saved: Interoperation, Code Gen Options
  • fcall-used: Code Gen Options
  • fcaller-saves: Optimize Options
  • fcheck-new: C++ Dialect Options
  • fcond-mismatch: C Dialect Options
  • fconserve-space: C++ Dialect Options
  • fconstant-string-class: Objective-C Dialect Options
  • fcse-follow-jumps: Optimize Options
  • fcse-skip-blocks: Optimize Options
  • fdata-sections: Optimize Options
  • fdelayed-branch: Optimize Options
  • fdelete-null-pointer-checks: Optimize Options
  • fdiagnostics-show-location: Language Independent Options
  • fdollars-in-identifiers: Interoperation, C++ Dialect Options
  • fdump-class-hierarchy: Debugging Options
  • fdump-translation-unit: Debugging Options
  • fdump-tree: Debugging Options
  • fdump-unnumbered: Debugging Options
  • fexceptions: Code Gen Options
  • fexpensive-optimizations: Optimize Options
  • fexternal-templates: Template Instantiation, C++ Dialect Options
  • ffast-math: Optimize Options
  • ffixed: Code Gen Options
  • ffloat-store: Disappointments, Optimize Options
  • ffor-scope: C++ Dialect Options
  • fforce-addr: Optimize Options
  • fforce-mem: Optimize Options
  • ffreestanding: Function Attributes, C Dialect Options, Standards
  • ffunction-sections: Optimize Options
  • fgcse: Optimize Options
  • fgcse-lm: Optimize Options
  • fgcse-sm: Optimize Options
  • fgnu-runtime: Objective-C Dialect Options
  • fhosted: C Dialect Options
  • finhibit-size-directive: Code Gen Options
  • finline-functions: Optimize Options
  • finline-limit: Optimize Options
  • finstrument-functions: Function Attributes, Code Gen Options
  • fkeep-inline-functions: Inline, Optimize Options
  • fkeep-static-consts: Optimize Options
  • fleading-underscore: Code Gen Options
  • fmem-report: Debugging Options
  • fmessage-length: Language Independent Options
  • fmove-all-movables: Optimize Options
  • fms-extensions: C++ Dialect Options
  • fnext-runtime: Objective-C Dialect Options
  • fno-access-control: C++ Dialect Options
  • fno-asm: C Dialect Options
  • fno-builtin: Other Builtins, C Dialect Options
  • fno-common: Variable Attributes, Code Gen Options
  • fno-const-strings: C++ Dialect Options
  • fno-cprop-registers: Optimize Options
  • fno-default-inline: Inline, Optimize Options, C++ Dialect Options
  • fno-defer-pop: Optimize Options
  • fno-elide-constructors: C++ Dialect Options
  • fno-enforce-eh-specs: C++ Dialect Options
  • fno-for-scope: C++ Dialect Options
  • fno-function-cse: Optimize Options
  • fno-gnu-keywords: C++ Dialect Options
  • fno-gnu-linker: Code Gen Options
  • fno-guess-branch-probability: Optimize Options
  • fno-ident: Code Gen Options
  • fno-implement-inlines: C++ Interface, C++ Dialect Options
  • fno-implicit-inline-templates: C++ Dialect Options
  • fno-implicit-templates: Template Instantiation, C++ Dialect Options
  • fno-inline: Optimize Options
  • fno-math-errno: Optimize Options
  • fno-nonansi-builtins: C++ Dialect Options
  • fno-operator-names: C++ Dialect Options
  • fno-optional-diags: C++ Dialect Options
  • fno-peephole: Optimize Options
  • fno-peephole2: Optimize Options
  • fno-rtti: C++ Dialect Options
  • fno-show-column: Preprocessor Options
  • fno-signed-bitfields: C Dialect Options
  • fno-stack-limit: Code Gen Options
  • fno-trapping-math: Optimize Options
  • fno-unsigned-bitfields: C Dialect Options
  • fno-weak: C++ Dialect Options
  • fnon-call-exceptions: Code Gen Options
  • fomit-frame-pointer: Optimize Options
  • foptimize-register-move: Optimize Options
  • foptimize-sibling-calls: Optimize Options
  • fpack-struct: Code Gen Options
  • fpcc-struct-return: Incompatibilities, Code Gen Options
  • fpermissive: C++ Dialect Options
  • fPIC: Code Gen Options
  • fpic: Code Gen Options
  • fprefetch-loop-arrays: Optimize Options
  • fpreprocessed: Preprocessor Options
  • fpretend-float: Debugging Options
  • fprofile-arcs: Other Builtins, Debugging Options
  • freduce-all-givs: Optimize Options
  • freg-struct-return: Code Gen Options
  • fregmove: Optimize Options
  • frename-registers: Optimize Options
  • frepo: Template Instantiation, C++ Dialect Options
  • frerun-cse-after-loop: Optimize Options
  • frerun-loop-opt: Optimize Options
  • fschedule-insns: Optimize Options
  • fschedule-insns2: Optimize Options
  • fshared-data: Code Gen Options
  • fshort-double: Code Gen Options
  • fshort-enums: Non-bugs, Type Attributes, Code Gen Options
  • fshort-wchar: C Dialect Options
  • fsigned-bitfields: Non-bugs, C Dialect Options
  • fsigned-char: C Dialect Options
  • fsingle-precision-constant: Optimize Options
  • fssa: Optimize Options
  • fssa-ccp: Optimize Options
  • fssa-dce: Optimize Options
  • fstack-check: Code Gen Options
  • fstack-limit-register: Code Gen Options
  • fstack-limit-symbol: Code Gen Options
  • fstats: C++ Dialect Options
  • fstrength-reduce: Optimize Options
  • fstrict-aliasing: Optimize Options
  • fsyntax-only: Warning Options
  • ftabstop: Preprocessor Options
  • ftemplate-depth: C++ Dialect Options
  • ftest-coverage: Debugging Options
  • fthread-jumps: Optimize Options
  • ftime-report: Debugging Options
  • ftrapv: Optimize Options
  • funroll-all-loops: Optimize Options
  • funroll-loops: Non-bugs, Optimize Options
  • funsafe-math-optimizations: Optimize Options
  • funsigned-bitfields: Non-bugs, C Dialect Options
  • funsigned-char: C Dialect Options
  • funwind-tables: Code Gen Options
  • fuse-cxa-atexit: C++ Dialect Options
  • fverbose-asm: Code Gen Options
  • fvolatile: Code Gen Options
  • fvolatile-global: Code Gen Options
  • fvolatile-static: Code Gen Options
  • fvtable-gc: C++ Dialect Options
  • fwritable-strings: Incompatibilities, C Dialect Options
  • G: System V Options, MIPS Options, RS/6000 and PowerPC Options, M32R/D Options
  • g: Debugging Options
  • gcc: Preprocessor Options
  • gcoff: Debugging Options
  • gdwarf: Debugging Options
  • gdwarf+: Debugging Options
  • gdwarf-2: Debugging Options
  • gen-decls: Objective-C Dialect Options
  • ggdb: Debugging Options
  • gstabs: Debugging Options
  • gstabs+: Debugging Options
  • gvms: Debugging Options
  • gxcoff: Debugging Options
  • gxcoff+: Debugging Options
  • H: Preprocessor Options
  • h: Preprocessor Options
  • help: Preprocessor Options, Overall Options
  • I: Directory Options, Preprocessor Options
  • I-: Directory Options, Preprocessor Options
  • idirafter: Preprocessor Options
  • imacros: Preprocessor Options
  • include: Preprocessor Options
  • iprefix: Preprocessor Options
  • isystem: Preprocessor Options
  • iwithprefix: Preprocessor Options
  • iwithprefixbefore: Preprocessor Options
  • L: Directory Options
  • l: Link Options
  • lobjc: Link Options
  • M: Preprocessor Options
  • m1: SH Options
  • m10: PDP-11 Options
  • m128bit-long-double: i386 and x86-64 Options
  • m16-bit: CRIS Options
  • m2: SH Options
  • m210: MCore Options
  • m29000: AMD29K Options
  • m29050: AMD29K Options
  • m3: SH Options
  • m31: S/390 and zSeries Options
  • m32: i386 and x86-64 Options, SPARC Options
  • m32-bit: CRIS Options
  • m32032: NS32K Options
  • m32081: NS32K Options
  • m32332: NS32K Options
  • m32381: NS32K Options
  • m32532: NS32K Options
  • m32r: M32R/D Options
  • m32rx: M32R/D Options
  • m340: MCore Options
  • m386: i386 and x86-64 Options
  • m3dnow: i386 and x86-64 Options
  • m3e: SH Options
  • m4: SH Options
  • m4-nofpu: SH Options
  • m4-single: SH Options
  • m4-single-only: SH Options
  • m40: PDP-11 Options
  • m45: PDP-11 Options
  • m4650: MIPS Options
  • m486: i386 and x86-64 Options
  • m4byte-functions: MCore Options
  • m5200: M680x0 Options
  • m64: S/390 and zSeries Options, i386 and x86-64 Options, SPARC Options
  • m68000: M680x0 Options
  • m68020: M680x0 Options
  • m68020-40: M680x0 Options
  • m68020-60: M680x0 Options
  • m68030: M680x0 Options
  • m68040: M680x0 Options
  • m68060: M680x0 Options
  • m6811: M68hc1x Options
  • m6812: M68hc1x Options
  • m68881: M680x0 Options
  • m68hc11: M68hc1x Options
  • m68hc12: M68hc1x Options
  • m8-bit: CRIS Options
  • m88000: M88K Options
  • m88100: M88K Options
  • m88110: M88K Options
  • m96bit-long-double: i386 and x86-64 Options
  • mabi-mmixware: MMIX Options
  • mabi=32: MIPS Options
  • mabi=64: MIPS Options
  • mabi=altivec: RS/6000 and PowerPC Options
  • mabi=eabi: MIPS Options
  • mabi=gnu: MMIX Options
  • mabi=n32: MIPS Options
  • mabi=no-altivec: RS/6000 and PowerPC Options
  • mabi=o64: MIPS Options
  • mabicalls: MIPS Options
  • mabort-on-noreturn: ARM Options
  • mabshi: PDP-11 Options
  • mac0: PDP-11 Options
  • maccumulate-outgoing-args: i386 and x86-64 Options
  • mads: RS/6000 and PowerPC Options
  • maix-struct-return: RS/6000 and PowerPC Options
  • maix32: RS/6000 and PowerPC Options
  • maix64: RS/6000 and PowerPC Options
  • malign-300: H8/300 Options
  • malign-double: i386 and x86-64 Options
  • malign-int: M680x0 Options
  • malignment-traps: ARM Options
  • malpha-as: DEC Alpha Options
  • maltivec: RS/6000 and PowerPC Options
  • mam33: MN10300 Options
  • maout: CRIS Options
  • mapcs: ARM Options
  • mapcs-26: ARM Options
  • mapcs-32: ARM Options
  • mapcs-frame: ARM Options
  • mapp-regs: SPARC Options
  • march: CRIS Options, HPPA Options, i386 and x86-64 Options, MIPS Options, ARM Options
  • margcount: Convex Options
  • masm-compat: Intel 960 Options
  • masm-optimize: D30V Options
  • masm=dialect: i386 and x86-64 Options
  • mauto-incdec: M68hc1x Options
  • mauto-pic: IA-64 Options
  • mb: SH Options
  • mb-step: IA-64 Options
  • mbackchain: S/390 and zSeries Options
  • mbase-addresses: MMIX Options
  • mbcopy: PDP-11 Options
  • mbig: TMS320C3x/C4x Options, RS/6000 and PowerPC Options
  • mbig-endian: Xtensa Options, IA-64 Options, MCore Options, RS/6000 and PowerPC Options, ARM Options
  • mbig-memory: TMS320C3x/C4x Options
  • mbig-pic: M88K Options
  • mbig-switch: V850 Options, HPPA Options
  • mbigtable: SH Options
  • mbit-align: RS/6000 and PowerPC Options
  • mbitfield: NS32K Options, M680x0 Options
  • mbk: TMS320C3x/C4x Options
  • mbooleans: Xtensa Options
  • mbranch-cheap: PDP-11 Options
  • mbranch-cost: D30V Options
  • mbranch-expensive: PDP-11 Options
  • mbranch-predict: MMIX Options
  • mbroken-saverestore: SPARC Options
  • mbsd: ARM Options
  • mbuild-constants: DEC Alpha Options
  • mbw: AMD29K Options
  • mbwx: DEC Alpha Options
  • mc1: Convex Options
  • mc2: Convex Options
  • mc300: Clipper Options
  • mc32: Convex Options
  • mc34: Convex Options
  • mc38: Convex Options
  • mc400: Clipper Options
  • mc68000: M680x0 Options
  • mc68020: M680x0 Options
  • mca: Intel 960 Options
  • mcall-aix: RS/6000 and PowerPC Options
  • mcall-gnu: RS/6000 and PowerPC Options
  • mcall-lib-mul: RT Options
  • mcall-linux: RS/6000 and PowerPC Options
  • mcall-netbsd: RS/6000 and PowerPC Options
  • mcall-prologues: AVR Options
  • mcall-solaris: RS/6000 and PowerPC Options
  • mcall-sysv: RS/6000 and PowerPC Options
  • mcall-sysv-eabi: RS/6000 and PowerPC Options
  • mcall-sysv-noeabi: RS/6000 and PowerPC Options
  • mcallee-super-interworking: ARM Options
  • mcaller-super-interworking: ARM Options
  • mcallgraph-data: MCore Options
  • mcc-init: CRIS Options
  • mcf: Intel 960 Options
  • mcheck-zero-division: M88K Options
  • mcix: DEC Alpha Options
  • mcmodel=embmedany: SPARC Options
  • mcmodel=medany: SPARC Options
  • mcmodel=medlow: SPARC Options
  • mcmodel=medmid: SPARC Options
  • mcode-align: Intel 960 Options
  • mcode-model=large: M32R/D Options
  • mcode-model=medium: M32R/D Options
  • mcode-model=small: M32R/D Options
  • mcomplex-addr: Intel 960 Options
  • mcond-exec: D30V Options
  • mconst-align: CRIS Options
  • mconstant-gp: IA-64 Options
  • mcpu: CRIS Options, ARC Options, TMS320C3x/C4x Options, DEC Alpha Options, i386 and x86-64 Options, MIPS Options, RS/6000 and PowerPC Options, ARM Options, SPARC Options
  • mcpu32: M680x0 Options
  • mcypress: SPARC Options
  • MD: Preprocessor Options
  • mdalign: SH Options
  • mdata: ARC Options
  • mdata-align: CRIS Options
  • mdb: TMS320C3x/C4x Options
  • mdebug: S/390 and zSeries Options
  • mdec-asm: PDP-11 Options
  • mdensity: Xtensa Options
  • mdisable-fpregs: HPPA Options
  • mdisable-indexing: HPPA Options
  • mdiv: MCore Options
  • mdouble-float: MIPS Options
  • mdp-isr-reload: TMS320C3x/C4x Options
  • mdw: AMD29K Options
  • mdwarf2-asm: IA-64 Options
  • meabi: RS/6000 and PowerPC Options
  • melf: MMIX Options, CRIS Options
  • melinux: CRIS Options
  • melinux-stacksize: CRIS Options
  • memb: RS/6000 and PowerPC Options
  • membedded-data: MIPS Options
  • membedded-pic: MIPS Options
  • mentry: MIPS Options
  • mep: V850 Options
  • mepsilon: MMIX Options
  • metrax100: CRIS Options
  • metrax4: CRIS Options
  • mexplicit-relocs: DEC Alpha Options
  • mextmem: D30V Options
  • mextmemory: D30V Options
  • MF: Preprocessor Options
  • mfast-fix: TMS320C3x/C4x Options
  • mfast-indirect-calls: HPPA Options
  • mfaster-structs: SPARC Options
  • mfix: DEC Alpha Options
  • mfix7000: MIPS Options
  • mfixed-range: IA-64 Options
  • mflat: SPARC Options
  • mfloat-ieee: DEC Alpha Options
  • mfloat-vax: DEC Alpha Options
  • mfloat32: PDP-11 Options
  • mfloat64: PDP-11 Options
  • mflush-func: MIPS Options
  • mfmovd: SH Options
  • mfp: ARM Options
  • mfp-arg-in-fpregs: RT Options
  • mfp-arg-in-gregs: RT Options
  • mfp-reg: DEC Alpha Options
  • mfp-rounding-mode: DEC Alpha Options
  • mfp-trap-mode: DEC Alpha Options
  • mfp32: MIPS Options
  • mfp64: MIPS Options
  • mfpa: M680x0 Options
  • mfpe: ARM Options
  • mfpu: PDP-11 Options, SPARC Options
  • mfull-fp-blocks: RT Options
  • mfull-toc: RS/6000 and PowerPC Options
  • mfused-madd: Xtensa Options, MIPS Options, RS/6000 and PowerPC Options
  • mg: VAX Options
  • MG: Preprocessor Options
  • mgas: DEC Alpha Options, HPPA Options, MIPS Options
  • mgnu: VAX Options
  • mgnu-as: IA-64 Options
  • mgnu-ld: IA-64 Options
  • mgotplt: CRIS Options
  • mgp32: MIPS Options
  • mgp64: MIPS Options
  • mgpopt: MIPS Options
  • mh: H8/300 Options
  • mhalf-pic: MIPS Options
  • mhandle-large-shift: M88K Options
  • mhard-float: Xtensa Options, S/390 and zSeries Options, MIPS Options, RS/6000 and PowerPC Options, ARM Options, SPARC Options
  • mhard-quad-float: SPARC Options
  • mhardlit: MCore Options
  • mhc-struct-return: Interoperation, RT Options
  • mhimem: NS32K Options
  • mhitachi: SH Options
  • mic-compat: Intel 960 Options
  • mic2.0-compat: Intel 960 Options
  • mic3.0-compat: Intel 960 Options
  • midentify-revision: M88K Options
  • mieee: SH Options, DEC Alpha Options
  • mieee-conformant: DEC Alpha Options
  • mieee-fp: i386 and x86-64 Options
  • mieee-with-inexact: DEC Alpha Options
  • mimpure-text: AMD29K Options
  • min-line-mul: RT Options
  • minit-stack: AVR Options
  • minline-all-stringops: i386 and x86-64 Options
  • minline-divide-max-throughput: IA-64 Options
  • minline-divide-min-latency: IA-64 Options
  • mint16: PDP-11 Options
  • mint32: PDP-11 Options, H8/300 Options
  • mint64: MIPS Options
  • mintel-asm: Intel 960 Options
  • mips1: MIPS Options
  • mips16: MIPS Options
  • mips2: MIPS Options
  • mips3: MIPS Options
  • mips4: MIPS Options
  • misize: SH Options
  • mjump-in-delay: HPPA Options
  • mka: Intel 960 Options
  • mkb: Intel 960 Options
  • mkernel-registers: AMD29K Options
  • mknuthdiv: MMIX Options
  • ml: SH Options
  • mlarge: AMD29K Options
  • mlarge-data: DEC Alpha Options
  • mleaf-procedures: Intel 960 Options
  • mlibfuncs: MMIX Options
  • mlinker-opt: HPPA Options
  • mlinux: CRIS Options
  • mlittle: RS/6000 and PowerPC Options
  • mlittle-endian: Xtensa Options, IA-64 Options, MCore Options, RS/6000 and PowerPC Options, ARM Options, SPARC Options
  • mlive-g0: SPARC Options
  • mlong-calls: V850 Options, MIPS Options, ARM Options
  • mlong-double-64: Intel 960 Options
  • mlong-load-store: HPPA Options
  • mlong32: MIPS Options, Convex Options
  • mlong64: MIPS Options, Convex Options
  • mlongcalls: Xtensa Options
  • mloop-unsigned: TMS320C3x/C4x Options
  • MM: Preprocessor Options
  • mmac16: Xtensa Options
  • mmad: MIPS Options
  • mmangle-cpu: ARC Options
  • mmax: DEC Alpha Options
  • mmax-stack-frame: CRIS Options
  • mmc: Intel 960 Options
  • mmcu: AVR Options
  • MMD: Preprocessor Options
  • mmemcpy: MIPS Options
  • mmemory-latency: DEC Alpha Options
  • mmemparm: TMS320C3x/C4x Options
  • mminimal-toc: RS/6000 and PowerPC Options
  • mminimum-fp-blocks: RT Options
  • mminmax: Xtensa Options
  • mmips-as: MIPS Options
  • mmips-tfile: MIPS Options
  • mmmx: i386 and x86-64 Options
  • mmpyi: TMS320C3x/C4x Options
  • mmul16: Xtensa Options
  • mmul32: Xtensa Options
  • mmult-bug: MN10300 Options
  • mmulti-add: NS32K Options
  • mmultiple: RS/6000 and PowerPC Options
  • mmvcle: S/390 and zSeries Options
  • mmvme: RS/6000 and PowerPC Options
  • mnbw: AMD29K Options
  • mndw: AMD29K Options
  • mnew-mnemonics: RS/6000 and PowerPC Options
  • mno-3dnow: i386 and x86-64 Options
  • mno-4byte-functions: MCore Options
  • mno-abicalls: MIPS Options
  • mno-abshi: PDP-11 Options
  • mno-ac0: PDP-11 Options
  • mno-align-double: i386 and x86-64 Options
  • mno-align-int: M680x0 Options
  • mno-align-stringops: i386 and x86-64 Options
  • mno-alignment-traps: ARM Options
  • mno-altivec: RS/6000 and PowerPC Options
  • mno-am33: MN10300 Options
  • mno-app-regs: SPARC Options
  • mno-asm-optimize: D30V Options
  • mno-backchain: S/390 and zSeries Options
  • mno-base-addresses: MMIX Options
  • mno-bit-align: RS/6000 and PowerPC Options
  • mno-bk: TMS320C3x/C4x Options
  • mno-booleans: Xtensa Options
  • mno-branch-predict: MMIX Options
  • mno-bwx: DEC Alpha Options
  • mno-callgraph-data: MCore Options
  • mno-check-zero-division: M88K Options
  • mno-cix: DEC Alpha Options
  • mno-code-align: Intel 960 Options
  • mno-complex-addr: Intel 960 Options
  • mno-const-align: CRIS Options
  • mno-crt0: MN10300 Options
  • mno-data-align: CRIS Options
  • mno-db: TMS320C3x/C4x Options
  • mno-debug: S/390 and zSeries Options
  • mno-density: Xtensa Options
  • mno-div: MCore Options
  • mno-dwarf2-asm: IA-64 Options
  • mno-eabi: RS/6000 and PowerPC Options
  • mno-embedded-data: MIPS Options
  • mno-embedded-pic: MIPS Options
  • mno-ep: V850 Options
  • mno-epsilon: MMIX Options
  • mno-explicit-relocs: DEC Alpha Options
  • mno-fancy-math-387: i386 and x86-64 Options
  • mno-fast-fix: TMS320C3x/C4x Options
  • mno-faster-structs: SPARC Options
  • mno-fix: DEC Alpha Options
  • mno-flat: SPARC Options
  • mno-float32: PDP-11 Options
  • mno-float64: PDP-11 Options
  • mno-fp-in-toc: RS/6000 and PowerPC Options
  • mno-fp-regs: DEC Alpha Options
  • mno-fp-ret-in-387: i386 and x86-64 Options
  • mno-fpu: SPARC Options
  • mno-fused-madd: Xtensa Options, MIPS Options, RS/6000 and PowerPC Options
  • mno-gnu-as: IA-64 Options
  • mno-gnu-ld: IA-64 Options
  • mno-gotplt: CRIS Options
  • mno-gpopt: MIPS Options
  • mno-half-pic: MIPS Options
  • mno-hardlit: MCore Options
  • mno-ieee-fp: i386 and x86-64 Options
  • mno-impure-text: AMD29K Options
  • mno-int16: PDP-11 Options
  • mno-int32: PDP-11 Options
  • mno-interrupts: AVR Options
  • mno-knuthdiv: MMIX Options
  • mno-leaf-procedures: Intel 960 Options
  • mno-libfuncs: MMIX Options
  • mno-long-calls: V850 Options, MIPS Options, ARM Options
  • mno-longcalls: Xtensa Options
  • mno-loop-unsigned: TMS320C3x/C4x Options
  • mno-mac16: Xtensa Options
  • mno-mad: MIPS Options
  • mno-max: DEC Alpha Options
  • mno-memcpy: MIPS Options
  • mno-minmax: Xtensa Options
  • mno-mips-tfile: MIPS Options
  • mno-mips16: MIPS Options
  • mno-mmx: i386 and x86-64 Options
  • mno-mpyi: TMS320C3x/C4x Options
  • mno-mul16: Xtensa Options
  • mno-mul32: Xtensa Options
  • mno-mult-bug: MN10300 Options
  • mno-multiple: RS/6000 and PowerPC Options
  • mno-multm: AMD29K Options
  • mno-mvcle: S/390 and zSeries Options
  • mno-nsa: Xtensa Options
  • mno-ocs-debug-info: M88K Options
  • mno-ocs-frame-position: M88K Options
  • mno-optimize-arg-area: M88K Options
  • mno-parallel-insns: TMS320C3x/C4x Options
  • mno-parallel-mpy: TMS320C3x/C4x Options
  • mno-pic: IA-64 Options
  • mno-power: RS/6000 and PowerPC Options
  • mno-power2: RS/6000 and PowerPC Options
  • mno-powerpc: RS/6000 and PowerPC Options
  • mno-powerpc-gfxopt: RS/6000 and PowerPC Options
  • mno-powerpc-gpopt: RS/6000 and PowerPC Options
  • mno-powerpc64: RS/6000 and PowerPC Options
  • mno-prolog-function: V850 Options
  • mno-prologue-epilogue: CRIS Options
  • mno-prototype: RS/6000 and PowerPC Options
  • mno-push-args: i386 and x86-64 Options
  • mno-register-names: IA-64 Options
  • mno-regnames: RS/6000 and PowerPC Options
  • mno-relax-immediate: MCore Options
  • mno-relocatable: RS/6000 and PowerPC Options
  • mno-relocatable-lib: RS/6000 and PowerPC Options
  • mno-reuse-arg-regs: AMD29K Options
  • mno-rnames: MIPS Options
  • mno-rptb: TMS320C3x/C4x Options
  • mno-rpts: TMS320C3x/C4x Options
  • mno-sched-prolog: ARM Options
  • mno-sdata: IA-64 Options, RS/6000 and PowerPC Options
  • mno-serialize-volatile: Interoperation, Xtensa Options, M88K Options
  • mno-sext: Xtensa Options
  • mno-short-load-bytes: ARM Options
  • mno-short-load-words: ARM Options
  • mno-side-effects: CRIS Options
  • mno-slow-bytes: MCore Options
  • mno-small-exec: S/390 and zSeries Options
  • mno-soft-float: DEC Alpha Options
  • mno-space-regs: HPPA Options
  • mno-split: PDP-11 Options
  • mno-split-addresses: MIPS Options
  • mno-sse: i386 and x86-64 Options
  • mno-stack-align: CRIS Options
  • mno-stack-bias: SPARC Options
  • mno-stack-check: AMD29K Options
  • mno-stats: MIPS Options
  • mno-storem-bug: AMD29K Options
  • mno-strict-align: Intel 960 Options, RS/6000 and PowerPC Options, M680x0 Options
  • mno-string: RS/6000 and PowerPC Options
  • mno-sum-in-toc: RS/6000 and PowerPC Options
  • mno-svr3-shlib: i386 and x86-64 Options
  • mno-symrename: ARM Options
  • mno-tablejump: AVR Options
  • mno-tail-call: Intel 960 Options
  • mno-target-align: Xtensa Options
  • mno-text-section-literals: Xtensa Options
  • mno-toc: RS/6000 and PowerPC Options
  • mno-toplevel-symbols: MMIX Options
  • mno-unaligned-doubles: SPARC Options
  • mno-underscores: M88K Options
  • mno-uninit-const-in-rodata: MIPS Options
  • mno-update: RS/6000 and PowerPC Options
  • mno-volatile-asm-stop: IA-64 Options
  • mno-wide-bitfields: MCore Options
  • mno-xl-call: RS/6000 and PowerPC Options
  • mno-zero-extend: MMIX Options
  • mnoargcount: Convex Options
  • mnobitfield: NS32K Options, M680x0 Options
  • mnohc-struct-return: RT Options
  • mnohimem: NS32K Options
  • mnomacsave: SH Options
  • mnomulti-add: NS32K Options
  • mnop-fun-dllimport: ARM Options
  • mnoregparam: NS32K Options
  • mnormal: AMD29K Options
  • mnosb: NS32K Options
  • mnsa: Xtensa Options
  • mnumerics: Intel 960 Options
  • mocs-debug-info: M88K Options
  • mocs-frame-position: M88K Options
  • mold-align: Intel 960 Options
  • mold-mnemonics: RS/6000 and PowerPC Options
  • momit-leaf-frame-pointer: i386 and x86-64 Options
  • monchip: D30V Options
  • moptimize-arg-area: M88K Options
  • MP: Preprocessor Options
  • mpa-risc-1-0: HPPA Options
  • mpa-risc-1-1: HPPA Options
  • mpa-risc-2-0: HPPA Options
  • mpadstruct: SH Options
  • mparallel-insns: TMS320C3x/C4x Options
  • mparallel-mpy: TMS320C3x/C4x Options
  • mparanoid: TMS320C3x/C4x Options
  • mpcrel: M680x0 Options
  • mpdebug: CRIS Options
  • mpe: RS/6000 and PowerPC Options
  • mpentium: i386 and x86-64 Options
  • mpentiumpro: i386 and x86-64 Options
  • mpic-register: ARM Options
  • mpoke-function-name: ARM Options
  • mportable-runtime: HPPA Options
  • mpower: RS/6000 and PowerPC Options
  • mpower2: RS/6000 and PowerPC Options
  • mpowerpc: RS/6000 and PowerPC Options
  • mpowerpc-gfxopt: RS/6000 and PowerPC Options
  • mpowerpc-gpopt: RS/6000 and PowerPC Options
  • mpowerpc64: RS/6000 and PowerPC Options
  • mprefergot: SH Options
  • mpreferred-stack-boundary: i386 and x86-64 Options
  • mprolog-function: V850 Options
  • mprologue-epilogue: CRIS Options
  • mprototype: RS/6000 and PowerPC Options
  • mpush-args: i386 and x86-64 Options
  • MQ: Preprocessor Options
  • mregister-names: IA-64 Options
  • mregnames: RS/6000 and PowerPC Options
  • mregparam: NS32K Options
  • mregparm: TMS320C3x/C4x Options, i386 and x86-64 Options
  • mrelax: SH Options, H8/300 Options, MN10300 Options, MN10200 Options
  • mrelax-immediate: MCore Options
  • mrelocatable: RS/6000 and PowerPC Options
  • mrelocatable-lib: RS/6000 and PowerPC Options
  • mreuse-arg-regs: AMD29K Options
  • mrnames: MIPS Options
  • mrodata: ARC Options
  • mrptb: TMS320C3x/C4x Options
  • mrpts: TMS320C3x/C4x Options
  • mrtd: Function Attributes, NS32K Options, i386 and x86-64 Options, M680x0 Options
  • ms: H8/300 Options
  • ms2600: H8/300 Options
  • msa: Intel 960 Options
  • msb: NS32K Options, Intel 960 Options
  • mschedule: HPPA Options
  • msda: V850 Options
  • msdata: IA-64 Options, RS/6000 and PowerPC Options
  • msdata-data: RS/6000 and PowerPC Options
  • msdata=default: RS/6000 and PowerPC Options
  • msdata=eabi: RS/6000 and PowerPC Options
  • msdata=none: RS/6000 and PowerPC Options, M32R/D Options
  • msdata=sdata: M32R/D Options
  • msdata=sysv: RS/6000 and PowerPC Options
  • msdata=use: M32R/D Options
  • mserialize-volatile: Xtensa Options, M88K Options
  • msext: Xtensa Options
  • mshort: M68hc1x Options, M680x0 Options
  • mshort-data: M88K Options
  • mshort-load-bytes: ARM Options
  • mshort-load-words: ARM Options
  • msim: Xstormy16 Options, RS/6000 and PowerPC Options
  • msingle-float: MIPS Options
  • msingle-pic-base: ARM Options
  • msize: AVR Options
  • mslow-bytes: MCore Options
  • msmall: TMS320C3x/C4x Options, AMD29K Options
  • msmall-data: DEC Alpha Options
  • msmall-exec: S/390 and zSeries Options
  • msmall-memory: TMS320C3x/C4x Options
  • msoft-float: Xtensa Options, PDP-11 Options, S/390 and zSeries Options, NS32K Options, DEC Alpha Options, Intel 960 Options, HPPA Options, i386 and x86-64 Options, MIPS Options, RS/6000 and PowerPC Options, ARM Options, AMD29K Options, SPARC Options, M680x0 Options
  • msoft-quad-float: SPARC Options
  • msoft-reg-count: M68hc1x Options
  • mspace: V850 Options, SH Options
  • msparclite: SPARC Options
  • msplit: PDP-11 Options
  • msplit-addresses: MIPS Options
  • msse: i386 and x86-64 Options
  • mstack-align: CRIS Options
  • mstack-bias: SPARC Options
  • mstack-check: AMD29K Options
  • mstats: MIPS Options
  • mstorem-bug: AMD29K Options
  • mstrict-align: Intel 960 Options, RS/6000 and PowerPC Options, M680x0 Options
  • mstring: RS/6000 and PowerPC Options
  • mstructure-size-boundary: ARM Options
  • msupersparc: SPARC Options
  • msvr3: M88K Options
  • msvr3-shlib: i386 and x86-64 Options
  • msvr4: M88K Options
  • msvr4-struct-return: RS/6000 and PowerPC Options
  • MT: Preprocessor Options
  • mtail-call: Intel 960 Options
  • mtarget-align: Xtensa Options
  • mtda: V850 Options
  • mtext: ARC Options
  • mtext-section-literals: Xtensa Options
  • mthreads: i386 and x86-64 Options
  • mthumb: ARM Options
  • mthumb-interwork: ARM Options
  • mti: TMS320C3x/C4x Options
  • mtiny-stack: AVR Options
  • mtoc: RS/6000 and PowerPC Options
  • mtoplevel-symbols: MMIX Options
  • mtpcs-frame: ARM Options
  • mtpcs-leaf-frame: ARM Options
  • mtrap-large-shift: M88K Options
  • mtrap-precision: DEC Alpha Options
  • mtune: CRIS Options, DEC Alpha Options, MIPS Options, RS/6000 and PowerPC Options, ARM Options, SPARC Options
  • munaligned-doubles: SPARC Options
  • muninit-const-in-rodata: MIPS Options
  • munix: VAX Options
  • munix-asm: PDP-11 Options
  • mupdate: RS/6000 and PowerPC Options
  • muse-div-instruction: M88K Options
  • muser-registers: AMD29K Options
  • musermode: SH Options
  • mv8: SPARC Options
  • mv850: V850 Options
  • mversion-03.00: M88K Options
  • mvms-return-codes: DEC Alpha/VMS Options
  • mvolatile-asm-stop: IA-64 Options
  • mvolatile-cache: Convex Options
  • mvolatile-nocache: Convex Options
  • mvxworks: RS/6000 and PowerPC Options
  • mwarn-passed-structs: M88K Options
  • mwide-bitfields: MCore Options
  • mwords-little-endian: ARM Options
  • mxl-call: RS/6000 and PowerPC Options
  • mxopen: ARM Options
  • myellowknife: RS/6000 and PowerPC Options
  • mzda: V850 Options
  • mzero-extend: MMIX Options
  • no-crt0: MIPS Options
  • no-integrated-cpp: C Dialect Options
  • no-red-zone: i386 and x86-64 Options
  • noasmopt: Interoperation
  • nocpp: MIPS Options
  • nodefaultlibs: Link Options
  • nostartfiles: Link Options
  • nostdinc: Preprocessor Options
  • nostdinc++: Preprocessor Options, C++ Dialect Options
  • nostdlib: Link Options
  • o: Preprocessor Options
  • O: Optimize Options
  • o: Overall Options
  • O0: Optimize Options
  • O1: Optimize Options
  • O2: Optimize Options
  • O3: Optimize Options
  • Os: Optimize Options
  • P: Preprocessor Options
  • p: Debugging Options
  • param: Optimize Options
  • pass-exit-codes: Overall Options
  • pedantic: Warnings and Errors, Alternate Keywords, C Extensions, Preprocessor Options, Warning Options, Standards
  • pedantic-errors: Warnings and Errors, Non-bugs, Actual Bugs, Preprocessor Options, Warning Options, Standards
  • pg: Debugging Options
  • pipe: Overall Options
  • print-file-name: Debugging Options
  • print-libgcc-file-name: Debugging Options
  • print-multi-directory: Debugging Options
  • print-multi-lib: Debugging Options
  • print-prog-name: Debugging Options
  • print-search-dirs: Debugging Options
  • pthread: RS/6000 and PowerPC Options
  • Q: Debugging Options
  • Qn: System V Options
  • Qy: System V Options
  • remap: Preprocessor Options
  • s: Link Options
  • S: Link Options, Overall Options
  • save-temps: Debugging Options
  • shared: Link Options
  • shared-libgcc: Link Options
  • sim: CRIS Options
  • sim2: CRIS Options
  • specs: Directory Options
  • static: Link Options
  • static-libgcc: Link Options
  • std: Non-bugs, Other Builtins, C Dialect Options, Standards
  • std=: Preprocessor Options
  • symbolic: Link Options
  • target-help: Preprocessor Options, Overall Options
  • time: Debugging Options
  • traditional: Non-bugs, Incompatibilities, Preprocessor Options, C Dialect Options, Standards
  • traditional-cpp: C Dialect Options
  • trigraphs: Preprocessor Options, C Dialect Options
  • u: Link Options
  • U: Preprocessor Options
  • undef: Preprocessor Options
  • V: Target Options
  • v: Preprocessor Options, Overall Options
  • version: Preprocessor Options
  • W: Incompatibilities
  • w: Preprocessor Options
  • W: Warning Options
  • w: Warning Options
  • Wa: Assembler Options
  • Waggregate-return: Warning Options
  • Wall: Standard Libraries, Preprocessor Options, Warning Options
  • Wbad-function-cast: Warning Options
  • Wcast-align: Warning Options
  • Wcast-qual: Warning Options
  • Wchar-subscripts: Warning Options
  • Wcomment: Preprocessor Options, Warning Options
  • Wcomments: Preprocessor Options
  • Wconversion: Protoize Caveats, Warning Options
  • Wctor-dtor-privacy: C++ Dialect Options
  • Wdisabled-optimization: Warning Options
  • Wdiv-by-zero: Warning Options
  • Weffc++: C++ Dialect Options
  • Werror: Preprocessor Options, Warning Options
  • Werror-implicit-function-declaration: Warning Options
  • Wfloat-equal: Warning Options
  • Wformat: Function Attributes, Warning Options
  • Wformat-nonliteral: Function Attributes, Warning Options
  • Wformat-security: Warning Options
  • Wformat=2: Warning Options
  • Wimplicit: Warning Options
  • Wimplicit-function-declaration: Warning Options
  • Wimplicit-int: Warning Options
  • Wimport: Preprocessor Options
  • Winline: Inline, Warning Options
  • Wl: Link Options
  • Wlarger-than: Warning Options
  • Wlong-long: Warning Options
  • Wmain: Warning Options
  • Wmissing-braces: Warning Options
  • Wmissing-declarations: Warning Options
  • Wmissing-format-attribute: Warning Options
  • Wmissing-noreturn: Warning Options
  • Wmissing-prototypes: Warning Options
  • Wmultichar: Warning Options
  • Wnested-externs: Warning Options
  • Wno-deprecated: C++ Dialect Options
  • Wno-deprecated-declarations: Warning Options
  • Wno-div-by-zero: Warning Options
  • Wno-format-extra-args: Warning Options
  • Wno-format-y2k: Warning Options
  • Wno-import: Warning Options
  • Wno-long-long: Warning Options
  • Wno-multichar: Warning Options
  • Wno-non-template-friend: C++ Dialect Options
  • Wno-pmf-conversions: Bound member functions, C++ Dialect Options
  • Wno-protocol: Objective-C Dialect Options
  • Wnon-virtual-dtor: C++ Dialect Options
  • Wold-style-cast: C++ Dialect Options
  • Woverloaded-virtual: C++ Dialect Options
  • Wp: Preprocessor Options
  • Wpacked: Warning Options
  • Wpadded: Warning Options
  • Wparentheses: Warning Options
  • Wpointer-arith: Pointer Arith, Warning Options
  • Wredundant-decls: Warning Options
  • Wreorder: Warning Options, C++ Dialect Options
  • Wreturn-type: Warning Options
  • Wselector: Objective-C Dialect Options
  • Wsequence-point: Warning Options
  • Wshadow: Warning Options
  • Wsign-compare: Warning Options
  • Wsign-promo: C++ Dialect Options
  • Wstrict-prototypes: Warning Options
  • Wswitch: Warning Options
  • Wsynth: C++ Dialect Options
  • Wsystem-headers: Preprocessor Options, Warning Options
  • Wtraditional: Preprocessor Options, Warning Options
  • Wtrigraphs: Preprocessor Options, Warning Options
  • Wundef: Preprocessor Options, Warning Options
  • Wuninitialized: Warning Options
  • Wunknown-pragmas: Warning Options
  • Wunreachable-code: Warning Options
  • Wunused: Warning Options
  • Wunused-function: Warning Options
  • Wunused-label: Warning Options
  • Wunused-parameter: Warning Options
  • Wunused-value: Warning Options
  • Wunused-variable: Warning Options
  • Wwrite-strings: Warning Options
  • x: Preprocessor Options, Overall Options
  • Xlinker: Link Options
  • Ym: System V Options
  • YP: System V Options


Using the GNU Compiler Collection (GCC)

Node:Option Summary, Next:Overall Options, Up:Invoking GCC

Option Summary

Here is a summary of all the options, grouped by type. Explanations are in the following sections.

Overall Options
See Options Controlling the Kind of Output.
-c  -S  -E  -o file  -pipe  -pass-exit-codes  -x language
-v  -###  --target-help  --help

C Language Options
See Options Controlling C Dialect.
-ansi  -std=standard  -aux-info filename
-fno-asm  -fno-builtin -fno-builtin-function
-fhosted  -ffreestanding
-trigraphs  -no-integrated-cpp  -traditional  -traditional-cpp
-fallow-single-precision  -fcond-mismatch
-fsigned-bitfields  -fsigned-char
-funsigned-bitfields  -funsigned-char
-fwritable-strings  -fshort-wchar

C++ Language Options
See Options Controlling C++ Dialect.
-fno-access-control  -fcheck-new  -fconserve-space
-fno-const-strings  -fdollars-in-identifiers
-fno-elide-constructors
-fno-enforce-eh-specs  -fexternal-templates
-falt-external-templates
-ffor-scope  -fno-for-scope  -fno-gnu-keywords
-fno-implicit-templates
-fno-implicit-inline-templates
-fno-implement-inlines  -fms-extensions
-fno-nonansi-builtins  -fno-operator-names
-fno-optional-diags  -fpermissive
-frepo  -fno-rtti  -fstats  -ftemplate-depth-n
-fuse-cxa-atexit  -fvtable-gc  -fno-weak  -nostdinc++
-fno-default-inline  -Wctor-dtor-privacy
-Wnon-virtual-dtor  -Wreorder
-Weffc++  -Wno-deprecated
-Wno-non-template-friend  -Wold-style-cast
-Woverloaded-virtual  -Wno-pmf-conversions
-Wsign-promo  -Wsynth

Objective-C Language Options
See Options Controlling Objective-C Dialect.
-fconstant-string-class=class-name
-fgnu-runtime  -fnext-runtime  -gen-decls
-Wno-protocol  -Wselector

Language Independent Options
See Options to Control Diagnostic Messages Formatting.
-fmessage-length=n
-fdiagnostics-show-location=[once|every-line]

Warning Options
See Options to Request or Suppress Warnings.
-fsyntax-only  -pedantic  -pedantic-errors
-w  -W  -Wall  -Waggregate-return
-Wcast-align  -Wcast-qual  -Wchar-subscripts  -Wcomment
-Wconversion  -Wno-deprecated-declarations
-Wdisabled-optimization  -Wdiv-by-zero  -Werror
-Wfloat-equal  -Wformat  -Wformat=2
-Wformat-nonliteral  -Wformat-security
-Wimplicit  -Wimplicit-int
-Wimplicit-function-declaration
-Werror-implicit-function-declaration
-Wimport  -Winline
-Wlarger-than-len  -Wlong-long
-Wmain  -Wmissing-braces  -Wmissing-declarations
-Wmissing-format-attribute  -Wmissing-noreturn
-Wmultichar  -Wno-format-extra-args  -Wno-format-y2k
-Wno-import  -Wpacked  -Wpadded
-Wparentheses  -Wpointer-arith  -Wredundant-decls
-Wreturn-type  -Wsequence-point  -Wshadow
-Wsign-compare  -Wswitch  -Wsystem-headers
-Wtrigraphs  -Wundef  -Wuninitialized
-Wunknown-pragmas  -Wunreachable-code
-Wunused  -Wunused-function  -Wunused-label  -Wunused-parameter
-Wunused-value  -Wunused-variable  -Wwrite-strings

C-only Warning Options

-Wbad-function-cast  -Wmissing-prototypes  -Wnested-externs
-Wstrict-prototypes  -Wtraditional

Debugging Options
See Options for Debugging Your Program or GCC.
-dletters  -dumpspecs  -dumpmachine  -dumpversion
-fdump-unnumbered -fdump-translation-unit[-n]
-fdump-class-hierarchy[-n]
-fdump-tree-original[-n] -fdump-tree-optimized[-n]
-fdump-tree-inlined[-n]
-fmem-report  -fpretend-float
-fprofile-arcs  -ftest-coverage  -ftime-report
-g  -glevel  -gcoff  -gdwarf  -gdwarf-1  -gdwarf-1+  -gdwarf-2
-ggdb  -gstabs  -gstabs+  -gvms  -gxcoff  -gxcoff+
-p  -pg  -print-file-name=library  -print-libgcc-file-name
-print-multi-directory  -print-multi-lib
-print-prog-name=program  -print-search-dirs  -Q
-save-temps  -time

Optimization Options
See Options that Control Optimization.
-falign-functions=n  -falign-jumps=n
-falign-labels=n  -falign-loops=n
-fbranch-probabilities  -fcaller-saves -fcprop-registers
-fcse-follow-jumps  -fcse-skip-blocks  -fdata-sections
-fdelayed-branch  -fdelete-null-pointer-checks
-fexpensive-optimizations  -ffast-math  -ffloat-store
-fforce-addr  -fforce-mem  -ffunction-sections
-fgcse  -fgcse-lm  -fgcse-sm
-finline-functions  -finline-limit=n  -fkeep-inline-functions
-fkeep-static-consts  -fmerge-constants  -fmerge-all-constants
-fmove-all-movables  -fno-default-inline  -fno-defer-pop
-fno-function-cse  -fno-guess-branch-probability
-fno-inline  -fno-math-errno  -fno-peephole  -fno-peephole2
-funsafe-math-optimizations -fno-trapping-math
-fomit-frame-pointer  -foptimize-register-move
-foptimize-sibling-calls  -fprefetch-loop-arrays
-freduce-all-givs -fregmove  -frename-registers
-frerun-cse-after-loop  -frerun-loop-opt
-fschedule-insns  -fschedule-insns2
-fsingle-precision-constant  -fssa -fssa-ccp -fssa-dce
-fstrength-reduce  -fstrict-aliasing  -fthread-jumps  -ftrapv
-funroll-all-loops  -funroll-loops
--param name=value
-O  -O0  -O1  -O2  -O3  -Os

Preprocessor Options
See Options Controlling the Preprocessor.
-$  -Aquestion=answer  -A-question[=answer]
-C  -dD  -dI  -dM  -dN
-Dmacro[=defn]  -E  -H
-idirafter dir
-include file  -imacros file
-iprefix file  -iwithprefix dir
-iwithprefixbefore dir  -isystem dir
-M  -MM  -MF  -MG  -MP  -MQ  -MT  -nostdinc  -P  -remap
-trigraphs  -undef  -Umacro  -Wp,option

Assembler Option
See Passing Options to the Assembler.
-Wa,option

Linker Options
See Options for Linking.
object-file-name  -llibrary
-nostartfiles  -nodefaultlibs  -nostdlib
-s  -static  -static-libgcc  -shared  -shared-libgcc  -symbolic
-Wl,option  -Xlinker option
-u symbol

Directory Options
See Options for Directory Search.
-Bprefix  -Idir  -I-  -Ldir  -specs=file

Target Options
See Target Options.
-b machine  -V version

Machine Dependent Options
See Hardware Models and Configurations.

M680x0 Options

-m68000  -m68020  -m68020-40  -m68020-60  -m68030  -m68040
-m68060  -mcpu32  -m5200  -m68881  -mbitfield  -mc68000  -mc68020
-mfpa  -mnobitfield  -mrtd  -mshort  -msoft-float  -mpcrel
-malign-int  -mstrict-align

M68hc1x Options

-m6811  -m6812  -m68hc11  -m68hc12
-mauto-incdec  -mshort  -msoft-reg-count=count

VAX Options

-mg  -mgnu  -munix

SPARC Options

-mcpu=cpu-type
-mtune=cpu-type
-mcmodel=code-model
-m32  -m64
-mapp-regs  -mbroken-saverestore  -mcypress
-mfaster-structs  -mflat
-mfpu  -mhard-float  -mhard-quad-float
-mimpure-text  -mlive-g0  -mno-app-regs
-mno-faster-structs  -mno-flat  -mno-fpu
-mno-impure-text  -mno-stack-bias  -mno-unaligned-doubles
-msoft-float  -msoft-quad-float  -msparclite  -mstack-bias
-msupersparc  -munaligned-doubles  -mv8

Convex Options

-mc1  -mc2  -mc32  -mc34  -mc38
-margcount  -mnoargcount
-mlong32  -mlong64
-mvolatile-cache  -mvolatile-nocache

AMD29K Options

-m29000  -m29050  -mbw  -mnbw  -mdw  -mndw
-mlarge  -mnormal  -msmall
-mkernel-registers  -mno-reuse-arg-regs
-mno-stack-check  -mno-storem-bug
-mreuse-arg-regs  -msoft-float  -mstack-check
-mstorem-bug  -muser-registers

ARM Options

-mapcs-frame  -mno-apcs-frame
-mapcs-26  -mapcs-32
-mapcs-stack-check  -mno-apcs-stack-check
-mapcs-float  -mno-apcs-float
-mapcs-reentrant  -mno-apcs-reentrant
-msched-prolog  -mno-sched-prolog
-mlittle-endian  -mbig-endian  -mwords-little-endian
-malignment-traps  -mno-alignment-traps
-msoft-float  -mhard-float  -mfpe
-mthumb-interwork  -mno-thumb-interwork
-mcpu=name  -march=name  -mfpe=name
-mstructure-size-boundary=n
-mbsd -mxopen  -mno-symrename
-mabort-on-noreturn
-mlong-calls  -mno-long-calls
-msingle-pic-base  -mno-single-pic-base
-mpic-register=reg
-mnop-fun-dllimport
-mpoke-function-name
-mthumb  -marm
-mtpcs-frame  -mtpcs-leaf-frame
-mcaller-super-interworking  -mcallee-super-interworking

MN10200 Options

-mrelax

MN10300 Options

-mmult-bug  -mno-mult-bug
-mam33  -mno-am33
-mno-crt0  -mrelax

M32R/D Options

-m32rx -m32r -mcode-model=model-type  -msdata=sdata-type
-G num

M88K Options

-m88000  -m88100  -m88110  -mbig-pic
-mcheck-zero-division  -mhandle-large-shift
-midentify-revision  -mno-check-zero-division
-mno-ocs-debug-info  -mno-ocs-frame-position
-mno-optimize-arg-area  -mno-serialize-volatile
-mno-underscores  -mocs-debug-info
-mocs-frame-position  -moptimize-arg-area
-mserialize-volatile  -mshort-data-num  -msvr3
-msvr4  -mtrap-large-shift  -muse-div-instruction
-mversion-03.00  -mwarn-passed-structs

RS/6000 and PowerPC Options

-mcpu=cpu-type
-mtune=cpu-type
-mpower  -mno-power  -mpower2  -mno-power2
-mpowerpc  -mpowerpc64  -mno-powerpc
-maltivec -mno-altivec
-mpowerpc-gpopt  -mno-powerpc-gpopt
-mpowerpc-gfxopt  -mno-powerpc-gfxopt
-mnew-mnemonics  -mold-mnemonics
-mfull-toc   -mminimal-toc  -mno-fp-in-toc  -mno-sum-in-toc
-m64  -m32  -mxl-call  -mno-xl-call  -mpe
-msoft-float  -mhard-float  -mmultiple  -mno-multiple
-mstring  -mno-string  -mupdate  -mno-update
-mfused-madd  -mno-fused-madd  -mbit-align  -mno-bit-align
-mstrict-align  -mno-strict-align  -mrelocatable
-mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib
-mtoc  -mno-toc -mlittle  -mlittle-endian  -mbig  -mbig-endian
-mcall-aix -mcall-sysv -mcall-netbsd
-maix-struct-return -msvr4-struct-return
-mabi=altivec -mabi=no-altivec
-mprototype  -mno-prototype
-msim  -mmvme  -mads  -myellowknife  -memb -msdata
-msdata=opt  -mvxworks -G num -pthread

RT Options

-mcall-lib-mul  -mfp-arg-in-fpregs  -mfp-arg-in-gregs
-mfull-fp-blocks  -mhc-struct-return  -min-line-mul
-mminimum-fp-blocks  -mnohc-struct-return

MIPS Options

-mabicalls -march=cpu-type -mtune=cpu=type
-mcpu=cpu-type -membedded-data  -muninit-const-in-rodata
-membedded-pic  -mfp32  -mfp64  -mfused-madd  -mno-fused-madd
-mgas  -mgp32  -mgp64
-mgpopt  -mhalf-pic  -mhard-float  -mint64  -mips1
-mips2  -mips3  -mips4  -mlong64  -mlong32  -mlong-calls  -mmemcpy
-mmips-as  -mmips-tfile  -mno-abicalls
-mno-embedded-data  -mno-uninit-const-in-rodata
-mno-embedded-pic  -mno-gpopt  -mno-long-calls
-mno-memcpy  -mno-mips-tfile  -mno-rnames  -mno-stats
-mrnames  -msoft-float
-m4650  -msingle-float  -mmad
-mstats  -EL  -EB  -G num  -nocpp
-mabi=32  -mabi=n32  -mabi=64  -mabi=eabi
-mfix7000  -mno-crt0 -mflush-func=func -mno-flush-func

i386 and x86-64 Options

-mcpu=cpu-type  -march=cpu-type -mfpmath=unit
-masm=dialect  -mno-fancy-math-387
-mno-fp-ret-in-387  -msoft-float  -msvr3-shlib
-mno-wide-multiply  -mrtd  -malign-double
-mpreferred-stack-boundary=num
-mmmx  -msse -msse2 -msse-math -m3dnow
-mthreads  -mno-align-stringops  -minline-all-stringops
-mpush-args  -maccumulate-outgoing-args  -m128bit-long-double
-m96bit-long-double  -mregparm=num  -momit-leaf-frame-pointer
-mno-red-zone
-m32 -m64

HPPA Options

-march=architecture-type
-mbig-switch  -mdisable-fpregs  -mdisable-indexing
-mfast-indirect-calls  -mgas  -mjump-in-delay
-mlong-load-store  -mno-big-switch  -mno-disable-fpregs
-mno-disable-indexing  -mno-fast-indirect-calls  -mno-gas
-mno-jump-in-delay  -mno-long-load-store
-mno-portable-runtime  -mno-soft-float
-mno-space-regs  -msoft-float  -mpa-risc-1-0
-mpa-risc-1-1  -mpa-risc-2-0  -mportable-runtime
-mschedule=cpu-type  -mspace-regs

Intel 960 Options

-mcpu-type  -masm-compat  -mclean-linkage
-mcode-align  -mcomplex-addr  -mleaf-procedures
-mic-compat  -mic2.0-compat  -mic3.0-compat
-mintel-asm  -mno-clean-linkage  -mno-code-align
-mno-complex-addr  -mno-leaf-procedures
-mno-old-align  -mno-strict-align  -mno-tail-call
-mnumerics  -mold-align  -msoft-float  -mstrict-align
-mtail-call

DEC Alpha Options

-mno-fp-regs  -msoft-float  -malpha-as  -mgas
-mieee  -mieee-with-inexact  -mieee-conformant
-mfp-trap-mode=mode  -mfp-rounding-mode=mode
-mtrap-precision=mode  -mbuild-constants
-mcpu=cpu-type  -mtune=cpu-type
-mbwx  -mmax  -mfix  -mcix
-mfloat-vax  -mfloat-ieee
-mexplicit-relocs  -msmall-data  -mlarge-data
-mmemory-latency=time

DEC Alpha/VMS Options

-mvms-return-codes

Clipper Options

-mc300  -mc400

H8/300 Options

-mrelax  -mh  -ms  -mint32  -malign-300

SH Options

-m1  -m2  -m3  -m3e
-m4-nofpu  -m4-single-only  -m4-single  -m4
-m5-64media -m5-64media-nofpu
-m5-32media -m5-32media-nofpu
-m5-compact -m5-compact-nofpu
-mb  -ml  -mdalign  -mrelax
-mbigtable  -mfmovd  -mhitachi  -mnomacsave
-mieee  -misize  -mpadstruct  -mspace
-mprefergot  -musermode

System V Options

-Qy  -Qn  -YP,paths  -Ym,dir

ARC Options

-EB  -EL
-mmangle-cpu  -mcpu=cpu  -mtext=text-section
-mdata=data-section  -mrodata=readonly-data-section

TMS320C3x/C4x Options

-mcpu=cpu  -mbig  -msmall  -mregparm  -mmemparm
-mfast-fix  -mmpyi  -mbk  -mti  -mdp-isr-reload
-mrpts=count  -mrptb  -mdb  -mloop-unsigned
-mparallel-insns  -mparallel-mpy  -mpreserve-float

V850 Options

-mlong-calls  -mno-long-calls  -mep  -mno-ep
-mprolog-function  -mno-prolog-function  -mspace
-mtda=n  -msda=n  -mzda=n
-mv850  -mbig-switch

NS32K Options

-m32032  -m32332  -m32532  -m32081  -m32381
-mmult-add  -mnomult-add  -msoft-float  -mrtd  -mnortd
-mregparam  -mnoregparam  -msb  -mnosb
-mbitfield  -mnobitfield  -mhimem  -mnohimem

AVR Options

-mmcu=mcu  -msize  -minit-stack=n  -mno-interrupts
-mcall-prologues  -mno-tablejump  -mtiny-stack

MCore Options

-mhardlit  -mno-hardlit  -mdiv  -mno-div  -mrelax-immediates
-mno-relax-immediates  -mwide-bitfields  -mno-wide-bitfields
-m4byte-functions  -mno-4byte-functions  -mcallgraph-data
-mno-callgraph-data  -mslow-bytes  -mno-slow-bytes  -mno-lsim
-mlittle-endian  -mbig-endian  -m210  -m340  -mstack-increment

MMIX Options

-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu
-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols
-melf -mbranch-predict -mno-branch-predict -mbase-addresses
-mno-base-addresses

IA-64 Options

-mbig-endian  -mlittle-endian  -mgnu-as  -mgnu-ld  -mno-pic
-mvolatile-asm-stop  -mb-step  -mregister-names  -mno-sdata
-mconstant-gp  -mauto-pic  -minline-divide-min-latency
-minline-divide-max-throughput  -mno-dwarf2-asm
-mfixed-range=register-range

D30V Options

-mextmem  -mextmemory  -monchip  -mno-asm-optimize  -masm-optimize
-mbranch-cost=n -mcond-exec=n

S/390 and zSeries Options

-mhard-float  -msoft-float  -mbackchain  -mno-backchain
-msmall-exec  -mno-small-exec  -mmvcle -mno-mvcle
-m64 -m31 -mdebug -mno-debug

CRIS Options

-mcpu=cpu -march=cpu -mtune=cpu
-mmax-stack-frame=n -melinux-stacksize=n
-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects
-mstack-align -mdata-align -mconst-align
-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt
-melf -maout -melinux -mlinux -sim -sim2

PDP-11 Options

-mfpu  -msoft-float  -mac0  -mno-ac0  -m40  -m45  -m10
-mbcopy  -mbcopy-builtin  -mint32  -mno-int16
-mint16  -mno-int32  -mfloat32  -mno-float64
-mfloat64  -mno-float32  -mabshi  -mno-abshi
-mbranch-expensive  -mbranch-cheap
-msplit  -mno-split  -munix-asm  -mdec-asm

Xstormy16 Options

-msim

Xtensa Options

-mbig-endian -mlittle-endian
-mdensity -mno-density
-mmac16 -mno-mac16
-mmul16 -mno-mul16
-mmul32 -mno-mul32
-mnsa -mno-nsa
-mminmax -mno-minmax
-msext -mno-sext
-mbooleans -mno-booleans
-mhard-float -msoft-float
-mfused-madd -mno-fused-madd
-mserialize-volatile -mno-serialize-volatile
-mtext-section-literals -mno-text-section-literals
-mtarget-align -mno-target-align
-mlongcalls -mno-longcalls

Code Generation Options
See Options for Code Generation Conventions.
-fcall-saved-reg  -fcall-used-reg
-ffixed-reg -fexceptions
-fnon-call-exceptions  -funwind-tables
-fasynchronous-unwind-tables
-finhibit-size-directive  -finstrument-functions
-fno-common  -fno-ident  -fno-gnu-linker
-fpcc-struct-return  -fpic  -fPIC
-freg-struct-return  -fshared-data  -fshort-enums
-fshort-double  -fvolatile
-fvolatile-global  -fvolatile-static
-fverbose-asm  -fpack-struct  -fstack-check
-fstack-limit-register=reg  -fstack-limit-symbol=sym
-fargument-alias  -fargument-noalias
-fargument-noalias-global  -fleading-underscore
  • Overall Options: Controlling the kind of output: an executable, object files, assembler files, or preprocessed source.
  • C Dialect Options: Controlling the variant of C language compiled.
  • C++ Dialect Options: Variations on C++.
  • Objective-C Dialect Options: Variations on Objective-C.
  • Language Independent Options: Controlling how diagnostics should be formatted.
  • Warning Options: How picky should the compiler be?
  • Debugging Options: Symbol tables, measurements, and debugging dumps.
  • Optimize Options: How much optimization?
  • Preprocessor Options: Controlling header files and macro definitions. Also, getting dependency information for Make.
  • Assembler Options: Passing options to the assembler.
  • Link Options: Specifying libraries and so on.
  • Directory Options: Where to find header files and libraries. Where to find the compiler executable files.
  • Spec Files: How to pass switches to sub-processes.
  • Target Options: Running a cross-compiler, or an old version of GCC.


Using the GNU Compiler Collection (GCC)

Node:Other Builtins, Next:Target Builtins, Previous:Vector Extensions, Up:C Extensions

Other built-in functions provided by GCC

GCC provides a large number of built-in functions other than the ones mentioned above. Some of these are for internal use in the processing of exceptions or variable-length argument lists and will not be documented here because they may change from time to time; we do not recommend general use of these functions.

The remaining functions are provided for optimization purposes.

GCC includes built-in versions of many of the functions in the standard C library. The versions prefixed with __builtin_ will always be treated as having the same meaning as the C library function even if you specify the -fno-builtin option. (see C Dialect Options) Many of these functions are only optimized in certain cases; if they are not optimized in a particular case, a call to the library function will be emitted.

The functions abort, exit, _Exit and _exit are recognized and presumed not to return, but otherwise are not built in. _exit is not recognized in strict ISO C mode (-ansi, -std=c89 or -std=c99). _Exit is not recognized in strict C89 mode (-ansi or -std=c89).

Outside strict ISO C mode, the functions alloca, bcmp, bzero, index, rindex, ffs, fputs_unlocked, printf_unlocked and fprintf_unlocked may be handled as built-in functions. All these functions have corresponding versions prefixed with __builtin_, which may be used even in strict C89 mode.

The ISO C99 functions conj, conjf, conjl, creal, crealf, creall, cimag, cimagf, cimagl, llabs and imaxabs are handled as built-in functions except in strict ISO C89 mode. There are also built-in versions of the ISO C99 functions cosf, cosl, fabsf, fabsl, sinf, sinl, sqrtf, and sqrtl, that are recognized in any mode since ISO C89 reserves these names for the purpose to which ISO C99 puts them. All these functions have corresponding versions prefixed with __builtin_.

The ISO C89 functions abs, cos, fabs, fprintf, fputs, labs, memcmp, memcpy, memset, printf, sin, sqrt, strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, and strstr are all recognized as built-in functions unless -fno-builtin is specified (or -fno-builtin-function is specified for an individual function). All of these functions have corresponding versions prefixed with __builtin_.

GCC provides built-in versions of the ISO C99 floating point comparison macros that avoid raising exceptions for unordered operands. They have the same names as the standard macros ( isgreater, isgreaterequal, isless, islessequal, islessgreater, and isunordered) , with __builtin_ prefixed. We intend for a library implementor to be able to simply #define each standard macro to its built-in equivalent.

int __builtin_types_compatible_p (type1, type2) Built-in Function

You can use the built-in function __builtin_types_compatible_p to determine whether two types are the same.

This built-in function returns 1 if the unqualified versions of the types type1 and type2 (which are types, not expressions) are compatible, 0 otherwise. The result of this built-in function can be used in integer constant expressions.

This built-in function ignores top level qualifiers (e.g., const, volatile). For example, int is equivalent to const int.

The type int[] and int[5] are compatible. On the other hand, int and char * are not compatible, even if the size of their types, on the particular architecture are the same. Also, the amount of pointer indirection is taken into account when determining similarity. Consequently, short * is not similar to short **. Furthermore, two types that are typedefed are considered compatible if their underlying types are compatible.

An enum type is considered to be compatible with another enum type. For example, enum {foo, bar} is similar to enum {hot, dog}.

You would typically use this function in code whose execution varies depending on the arguments' types. For example:

#define foo(x)                                                  \
  ({                                                           \
    typeof (x) tmp;                                             \
    if (__builtin_types_compatible_p (typeof (x), long double)) \
      tmp = foo_long_double (tmp);                              \
    else if (__builtin_types_compatible_p (typeof (x), double)) \
      tmp = foo_double (tmp);                                   \
    else if (__builtin_types_compatible_p (typeof (x), float))  \
      tmp = foo_float (tmp);                                    \
    else                                                        \
      abort ();                                                 \
    tmp;                                                        \
  })

Note: This construct is only available for C.

type __builtin_choose_expr (const_exp, exp1, exp2) Built-in Function

You can use the built-in function __builtin_choose_expr to evaluate code depending on the value of a constant expression. This built-in function returns exp1 if const_exp, which is a constant expression that must be able to be determined at compile time, is nonzero. Otherwise it returns 0.

This built-in function is analogous to the ? : operator in C, except that the expression returned has its type unaltered by promotion rules. Also, the built-in function does not evaluate the expression that was not chosen. For example, if const_exp evaluates to true, exp2 is not evaluated even if it has side-effects.

This built-in function can return an lvalue if the chosen argument is an lvalue.

If exp1 is returned, the return type is the same as exp1's type. Similarly, if exp2 is returned, its return type is the same as exp2.

Example:

#define foo(x)                                                               \
  __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), double),  \
    foo_double (x),                                                          \
    __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), float), \
      foo_float (x),                                                         \
      /* The void expression results in a compile-time error             \
         when assigning the result to something.  */                     \
      (void)0))

Note: This construct is only available for C. Furthermore, the unused expression (exp1 or exp2 depending on the value of const_exp) may still generate syntax errors. This may change in future revisions.

int __builtin_constant_p (exp) Built-in Function
You can use the built-in function __builtin_constant_p to determine if a value is known to be constant at compile-time and hence that GCC can perform constant-folding on expressions involving that value. The argument of the function is the value to test. The function returns the integer 1 if the argument is known to be a compile-time constant and 0 if it is not known to be a compile-time constant. A return of 0 does not indicate that the value is not a constant, but merely that GCC cannot prove it is a constant with the specified value of the -O option.

You would typically use this function in an embedded application where memory was a critical resource. If you have some complex calculation, you may want it to be folded if it involves constants, but need to call a function if it does not. For example:

#define Scale_Value(X)      \
  (__builtin_constant_p (X) \
  ? ((X) * SCALE + OFFSET) : Scale (X))

You may use this built-in function in either a macro or an inline function. However, if you use it in an inlined function and pass an argument of the function as the argument to the built-in, GCC will never return 1 when you call the inline function with a string constant or compound literal (see Compound Literals) and will not return 1 when you pass a constant numeric value to the inline function unless you specify the -O option.

You may also use __builtin_constant_p in initializers for static data. For instance, you can write

static const int table[] = {
   __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
   /* ... */
};

This is an acceptable initializer even if EXPRESSION is not a constant expression. GCC must be more conservative about evaluating the built-in in this case, because it has no opportunity to perform optimization.

Previous versions of GCC did not accept this built-in in data initializers. The earliest version where it is completely safe is 3.0.1.

long __builtin_expect (long exp, long c) Built-in Function
You may use __builtin_expect to provide the compiler with branch prediction information. In general, you should prefer to use actual profile feedback for this (-fprofile-arcs), as programmers are notoriously bad at predicting how their programs actually perform. However, there are applications in which this data is hard to collect.

The return value is the value of exp, which should be an integral expression. The value of c must be a compile-time constant. The semantics of the built-in are that it is expected that exp == c. For example:

if (__builtin_expect (x, 0))
  foo ();

would indicate that we do not expect to call foo, since we expect x to be zero. Since you are limited to integral expressions for exp, you should use constructions such as

if (__builtin_expect (ptr != NULL, 1))
  error ();

when testing pointer or floating-point values.

void __builtin_prefetch (const void *addr, ...) Built-in Function
This function is used to minimize cache-miss latency by moving data into a cache before it is accessed. You can insert calls to __builtin_prefetch into code for which you know addresses of data in memory that is likely to be accessed soon. If the target supports them, data prefetch instructions will be generated. If the prefetch is done early enough before the access then the data will be in the cache by the time it is accessed.

The value of addr is the address of the memory to prefetch. There are two optional arguments, rw and locality. The value of rw is a compile-time constant one or zero; one means that the prefetch is preparing for a write to the memory address and zero, the default, means that the prefetch is preparing for a read. The value locality must be a compile-time constant integer between zero and three. A value of zero means that the data has no temporal locality, so it need not be left in the cache after the access. A value of three means that the data has a high degree of temporal locality and should be left in all levels of cache possible. Values of one and two mean, respectively, a low or moderate degree of temporal locality. The default is three.

for (i = 0; i < n; i++)
  {
    a[i] = a[i] + b[i];
    __builtin_prefetch (&a[i+j], 1, 1);
    __builtin_prefetch (&b[i+j], 0, 1);
    /* ... */
  }

Data prefetch does not generate faults if addr is invalid, but the address expression itself must be valid. For example, a prefetch of p->next will not fault if p->next is not a valid address, but evaluation will fault if p is not a valid address.

If the target does not support data prefetch, the address expression is evaluated if it includes side effects but no other code is generated and GCC does not issue a warning.


Using the GNU Compiler Collection (GCC)

Node:Overall Options, Next:Invoking G++, Previous:Option Summary, Up:Invoking GCC

Options Controlling the Kind of Output

Compilation can involve up to four stages: preprocessing, compilation proper, assembly and linking, always in that order. The first three stages apply to an individual source file, and end by producing an object file; linking combines all the object files (those newly compiled, and those specified as input) into an executable file.

For any given input file, the file name suffix determines what kind of compilation is done:

file.c
C source code which must be preprocessed.
file.i
C source code which should not be preprocessed.
file.ii
C++ source code which should not be preprocessed.
file.m
Objective-C source code. Note that you must link with the library libobjc.a to make an Objective-C program work.
file.mi
Objective-C source code which should not be preprocessed.
file.h
C header file (not to be compiled or linked).
file.cc
file.cp
file.cxx
file.cpp
file.c++
file.C
C++ source code which must be preprocessed. Note that in .cxx, the last two letters must both be literally x. Likewise, .C refers to a literal capital C.
file.f
file.for
file.FOR
Fortran source code which should not be preprocessed.
file.F
file.fpp
file.FPP
Fortran source code which must be preprocessed (with the traditional preprocessor).
file.r
Fortran source code which must be preprocessed with a RATFOR preprocessor (not included with GCC).

See Options Controlling the Kind of Output, for more details of the handling of Fortran input files.

file.ads
Ada source code file which contains a library unit declaration (a declaration of a package, subprogram, or generic, or a generic instantiation), or a library unit renaming declaration (a package, generic, or subprogram renaming declaration). Such files are also called specs.
file.adb
Ada source code file containing a library unit body (a subprogram or package body). Such files are also called bodies.
file.s
Assembler code.
file.S
Assembler code which must be preprocessed.
other
An object file to be fed straight into linking. Any file name with no recognized suffix is treated this way.

You can specify the input language explicitly with the -x option:

-x language
Specify explicitly the language for the following input files (rather than letting the compiler choose a default based on the file name suffix). This option applies to all following input files until the next -x option. Possible values for language are:
c  c-header  cpp-output
c++  c++-cpp-output
objective-c  objc-cpp-output
assembler  assembler-with-cpp
ada
f77  f77-cpp-input  ratfor
java

-x none
Turn off any specification of a language, so that subsequent files are handled according to their file name suffixes (as they are if -x has not been used at all).
-pass-exit-codes
Normally the gcc program will exit with the code of 1 if any phase of the compiler returns a non-success return code. If you specify -pass-exit-codes, the gcc program will instead return with numerically highest error produced by any phase that returned an error indication.

If you only want some of the stages of compilation, you can use -x (or filename suffixes) to tell gcc where to start, and one of the options -c, -S, or -E to say where gcc is to stop. Note that some combinations (for example, -x cpp-output -E) instruct gcc to do nothing at all.

-c
Compile or assemble the source files, but do not link. The linking stage simply is not done. The ultimate output is in the form of an object file for each source file.

By default, the object file name for a source file is made by replacing the suffix .c, .i, .s, etc., with .o.

Unrecognized input files, not requiring compilation or assembly, are ignored.

-S
Stop after the stage of compilation proper; do not assemble. The output is in the form of an assembler code file for each non-assembler input file specified.

By default, the assembler file name for a source file is made by replacing the suffix .c, .i, etc., with .s.

Input files that don't require compilation are ignored.

-E
Stop after the preprocessing stage; do not run the compiler proper. The output is in the form of preprocessed source code, which is sent to the standard output.

Input files which don't require preprocessing are ignored.

-o file
Place output in file file. This applies regardless to whatever sort of output is being produced, whether it be an executable file, an object file, an assembler file or preprocessed C code.

Since only one output file can be specified, it does not make sense to use -o when compiling more than one input file, unless you are producing an executable file as output.

If -o is not specified, the default is to put an executable file in a.out, the object file for source.suffix in source.o, its assembler file in source.s, and all preprocessed C source on standard output.

-v
Print (on standard error output) the commands executed to run the stages of compilation. Also print the version number of the compiler driver program and of the preprocessor and the compiler proper.
-###
Like -v except the commands are not executed and all command arguments are quoted. This is useful for shell scripts to capture the driver-generated command lines.
-pipe
Use pipes rather than temporary files for communication between the various stages of compilation. This fails to work on some systems where the assembler is unable to read from a pipe; but the GNU assembler has no trouble.
--help
Print (on the standard output) a description of the command line options understood by gcc. If the -v option is also specified then --help will also be passed on to the various processes invoked by gcc, so that they can display the command line options they accept. If the -W option is also specified then command line options which have no documentation associated with them will also be displayed.
--target-help
Print (on the standard output) a description of target specific command line options for each tool.


Using the GNU Compiler Collection (GCC)

Node:PDP-11 Options, Next:Xstormy16 Options, Previous:MMIX Options, Up:Submodel Options

PDP-11 Options

These options are defined for the PDP-11:

-mfpu
Use hardware FPP floating point. This is the default. (FIS floating point on the PDP-11/40 is not supported.)
-msoft-float
Do not use hardware floating point.
-mac0
Return floating-point results in ac0 (fr0 in Unix assembler syntax).
-mno-ac0
Return floating-point results in memory. This is the default.
-m40
Generate code for a PDP-11/40.
-m45
Generate code for a PDP-11/45. This is the default.
-m10
Generate code for a PDP-11/10.
-mbcopy-builtin
Use inline movstrhi patterns for copying memory. This is the default.
-mbcopy
Do not use inline movstrhi patterns for copying memory.
-mint16
-mno-int32
Use 16-bit int. This is the default.
-mint32
-mno-int16
Use 32-bit int.
-mfloat64
-mno-float32
Use 64-bit float. This is the default.
-mfloat32
-mno-float64
Use 32-bit float.
-mabshi
Use abshi2 pattern. This is the default.
-mno-abshi
Do not use abshi2 pattern.
-mbranch-expensive
Pretend that branches are expensive. This is for experimenting with code generation only.
-mbranch-cheap
Do not pretend that branches are expensive. This is the default.
-msplit
Generate code for a system with split I&D.
-mno-split
Generate code for a system without split I&D. This is the default.
-munix-asm
Use Unix assembler syntax. This is the default when configured for pdp11-*-bsd.
-mdec-asm
Use DEC assembler syntax. This is the default when configured for any PDP-11 target other than pdp11-*-bsd.


Using the GNU Compiler Collection (GCC)

Node:Pointer Arith, Next:Initializers, Previous:Subscripting, Up:C Extensions

Arithmetic on void- and Function-Pointers

In GNU C, addition and subtraction operations are supported on pointers to void and on pointers to functions. This is done by treating the size of a void or of a function as 1.

A consequence of this is that sizeof is also allowed on void and on function types, and returns 1.

The option -Wpointer-arith requests a warning if these extensions are used.


Using the GNU Compiler Collection (GCC)

Node:PowerPC AltiVec Built-in Functions, Previous:X86 Built-in Functions, Up:Target Builtins

PowerPC AltiVec Built-in Functions

These built-in functions are available for the PowerPC family of computers, depending on the command-line switches used.

The following machine modes are available for use with AltiVec built-in functions (see Vector Extensions): V4SI for a vector of four 32-bit integers, V4SF for a vector of four 32-bit floating point numbers, V8HI for a vector of eight 16-bit integers, and V16QI for a vector of sixteen 8-bit integers.

The following functions are made available by including <altivec.h> and using -maltivec and -mabi=altivec. The functions implement the functionality described in Motorola's AltiVec Programming Interface Manual.

Note: Only the <altivec.h> interface is supported. Internally, GCC uses built-in functions to achieve the functionality in the aforementioned header file, but they are not supported and are subject to change without notice.

vector signed char vec_abs (vector signed char, vector signed char);
vector signed short vec_abs (vector signed short, vector signed short);
vector signed int vec_abs (vector signed int, vector signed int);
vector signed float vec_abs (vector signed float, vector signed float);

vector signed char vec_abss (vector signed char, vector signed char);
vector signed short vec_abss (vector signed short, vector signed short);

vector signed char vec_add (vector signed char, vector signed char);
vector unsigned char vec_add (vector signed char, vector unsigned char);

vector unsigned char vec_add (vector unsigned char, vector signed char);

vector unsigned char vec_add (vector unsigned char,
                              vector unsigned char);
vector signed short vec_add (vector signed short, vector signed short);
vector unsigned short vec_add (vector signed short,
                               vector unsigned short);
vector unsigned short vec_add (vector unsigned short,
                               vector signed short);
vector unsigned short vec_add (vector unsigned short,
                               vector unsigned short);
vector signed int vec_add (vector signed int, vector signed int);
vector unsigned int vec_add (vector signed int, vector unsigned int);
vector unsigned int vec_add (vector unsigned int, vector signed int);
vector unsigned int vec_add (vector unsigned int, vector unsigned int);
vector float vec_add (vector float, vector float);

vector unsigned int vec_addc (vector unsigned int, vector unsigned int);

vector unsigned char vec_adds (vector signed char,
                               vector unsigned char);
vector unsigned char vec_adds (vector unsigned char,
                               vector signed char);
vector unsigned char vec_adds (vector unsigned char,
                               vector unsigned char);
vector signed char vec_adds (vector signed char, vector signed char);
vector unsigned short vec_adds (vector signed short,
                                vector unsigned short);
vector unsigned short vec_adds (vector unsigned short,
                                vector signed short);
vector unsigned short vec_adds (vector unsigned short,
                                vector unsigned short);
vector signed short vec_adds (vector signed short, vector signed short);

vector unsigned int vec_adds (vector signed int, vector unsigned int);
vector unsigned int vec_adds (vector unsigned int, vector signed int);
vector unsigned int vec_adds (vector unsigned int, vector unsigned int);

vector signed int vec_adds (vector signed int, vector signed int);

vector float vec_and (vector float, vector float);
vector float vec_and (vector float, vector signed int);
vector float vec_and (vector signed int, vector float);
vector signed int vec_and (vector signed int, vector signed int);
vector unsigned int vec_and (vector signed int, vector unsigned int);
vector unsigned int vec_and (vector unsigned int, vector signed int);
vector unsigned int vec_and (vector unsigned int, vector unsigned int);
vector signed short vec_and (vector signed short, vector signed short);
vector unsigned short vec_and (vector signed short,
                               vector unsigned short);
vector unsigned short vec_and (vector unsigned short,
                               vector signed short);
vector unsigned short vec_and (vector unsigned short,
                               vector unsigned short);
vector signed char vec_and (vector signed char, vector signed char);
vector unsigned char vec_and (vector signed char, vector unsigned char);

vector unsigned char vec_and (vector unsigned char, vector signed char);

vector unsigned char vec_and (vector unsigned char,
                              vector unsigned char);

vector float vec_andc (vector float, vector float);
vector float vec_andc (vector float, vector signed int);
vector float vec_andc (vector signed int, vector float);
vector signed int vec_andc (vector signed int, vector signed int);
vector unsigned int vec_andc (vector signed int, vector unsigned int);
vector unsigned int vec_andc (vector unsigned int, vector signed int);
vector unsigned int vec_andc (vector unsigned int, vector unsigned int);

vector signed short vec_andc (vector signed short, vector signed short);

vector unsigned short vec_andc (vector signed short,
                                vector unsigned short);
vector unsigned short vec_andc (vector unsigned short,
                                vector signed short);
vector unsigned short vec_andc (vector unsigned short,
                                vector unsigned short);
vector signed char vec_andc (vector signed char, vector signed char);
vector unsigned char vec_andc (vector signed char,
                               vector unsigned char);
vector unsigned char vec_andc (vector unsigned char,
                               vector signed char);
vector unsigned char vec_andc (vector unsigned char,
                               vector unsigned char);

vector unsigned char vec_avg (vector unsigned char,
                              vector unsigned char);
vector signed char vec_avg (vector signed char, vector signed char);
vector unsigned short vec_avg (vector unsigned short,
                               vector unsigned short);
vector signed short vec_avg (vector signed short, vector signed short);
vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
vector signed int vec_avg (vector signed int, vector signed int);

vector float vec_ceil (vector float);

vector signed int vec_cmpb (vector float, vector float);

vector signed char vec_cmpeq (vector signed char, vector signed char);
vector signed char vec_cmpeq (vector unsigned char,
                              vector unsigned char);
vector signed short vec_cmpeq (vector signed short,
                               vector signed short);
vector signed short vec_cmpeq (vector unsigned short,
                               vector unsigned short);
vector signed int vec_cmpeq (vector signed int, vector signed int);
vector signed int vec_cmpeq (vector unsigned int, vector unsigned int);
vector signed int vec_cmpeq (vector float, vector float);

vector signed int vec_cmpge (vector float, vector float);

vector signed char vec_cmpgt (vector unsigned char,
                              vector unsigned char);
vector signed char vec_cmpgt (vector signed char, vector signed char);
vector signed short vec_cmpgt (vector unsigned short,
                               vector unsigned short);
vector signed short vec_cmpgt (vector signed short,
                               vector signed short);
vector signed int vec_cmpgt (vector unsigned int, vector unsigned int);
vector signed int vec_cmpgt (vector signed int, vector signed int);
vector signed int vec_cmpgt (vector float, vector float);

vector signed int vec_cmple (vector float, vector float);

vector signed char vec_cmplt (vector unsigned char,
                              vector unsigned char);
vector signed char vec_cmplt (vector signed char, vector signed char);
vector signed short vec_cmplt (vector unsigned short,
                               vector unsigned short);
vector signed short vec_cmplt (vector signed short,
                               vector signed short);
vector signed int vec_cmplt (vector unsigned int, vector unsigned int);
vector signed int vec_cmplt (vector signed int, vector signed int);
vector signed int vec_cmplt (vector float, vector float);

vector float vec_ctf (vector unsigned int, const char);
vector float vec_ctf (vector signed int, const char);

vector signed int vec_cts (vector float, const char);

vector unsigned int vec_ctu (vector float, const char);

void vec_dss (const char);

void vec_dssall (void);

void vec_dst (void *, int, const char);

void vec_dstst (void *, int, const char);

void vec_dststt (void *, int, const char);

void vec_dstt (void *, int, const char);

vector float vec_expte (vector float, vector float);

vector float vec_floor (vector float, vector float);

vector float vec_ld (int, vector float *);
vector float vec_ld (int, float *):
vector signed int vec_ld (int, int *);
vector signed int vec_ld (int, vector signed int *);
vector unsigned int vec_ld (int, vector unsigned int *);
vector unsigned int vec_ld (int, unsigned int *);
vector signed short vec_ld (int, short *, vector signed short *);
vector unsigned short vec_ld (int, unsigned short *,
                              vector unsigned short *);
vector signed char vec_ld (int, signed char *);
vector signed char vec_ld (int, vector signed char *);
vector unsigned char vec_ld (int, unsigned char *);
vector unsigned char vec_ld (int, vector unsigned char *);

vector signed char vec_lde (int, signed char *);
vector unsigned char vec_lde (int, unsigned char *);
vector signed short vec_lde (int, short *);
vector unsigned short vec_lde (int, unsigned short *);
vector float vec_lde (int, float *);
vector signed int vec_lde (int, int *);
vector unsigned int vec_lde (int, unsigned int *);

void float vec_ldl (int, float *);
void float vec_ldl (int, vector float *);
void signed int vec_ldl (int, vector signed int *);
void signed int vec_ldl (int, int *);
void unsigned int vec_ldl (int, unsigned int *);
void unsigned int vec_ldl (int, vector unsigned int *);
void signed short vec_ldl (int, vector signed short *);
void signed short vec_ldl (int, short *);
void unsigned short vec_ldl (int, vector unsigned short *);
void unsigned short vec_ldl (int, unsigned short *);
void signed char vec_ldl (int, vector signed char *);
void signed char vec_ldl (int, signed char *);
void unsigned char vec_ldl (int, vector unsigned char *);
void unsigned char vec_ldl (int, unsigned char *);

vector float vec_loge (vector float);

vector unsigned char vec_lvsl (int, void *, int *);

vector unsigned char vec_lvsr (int, void *, int *);

vector float vec_madd (vector float, vector float, vector float);

vector signed short vec_madds (vector signed short, vector signed short,
                               vector signed short);

vector unsigned char vec_max (vector signed char, vector unsigned char);

vector unsigned char vec_max (vector unsigned char, vector signed char);

vector unsigned char vec_max (vector unsigned char,
                              vector unsigned char);
vector signed char vec_max (vector signed char, vector signed char);
vector unsigned short vec_max (vector signed short,
                               vector unsigned short);
vector unsigned short vec_max (vector unsigned short,
                               vector signed short);
vector unsigned short vec_max (vector unsigned short,
                               vector unsigned short);
vector signed short vec_max (vector signed short, vector signed short);
vector unsigned int vec_max (vector signed int, vector unsigned int);
vector unsigned int vec_max (vector unsigned int, vector signed int);
vector unsigned int vec_max (vector unsigned int, vector unsigned int);
vector signed int vec_max (vector signed int, vector signed int);
vector float vec_max (vector float, vector float);

vector signed char vec_mergeh (vector signed char, vector signed char);
vector unsigned char vec_mergeh (vector unsigned char,
                                 vector unsigned char);
vector signed short vec_mergeh (vector signed short,
                                vector signed short);
vector unsigned short vec_mergeh (vector unsigned short,
                                  vector unsigned short);
vector float vec_mergeh (vector float, vector float);
vector signed int vec_mergeh (vector signed int, vector signed int);
vector unsigned int vec_mergeh (vector unsigned int,
                                vector unsigned int);

vector signed char vec_mergel (vector signed char, vector signed char);
vector unsigned char vec_mergel (vector unsigned char,
                                 vector unsigned char);
vector signed short vec_mergel (vector signed short,
                                vector signed short);
vector unsigned short vec_mergel (vector unsigned short,
                                  vector unsigned short);
vector float vec_mergel (vector float, vector float);
vector signed int vec_mergel (vector signed int, vector signed int);
vector unsigned int vec_mergel (vector unsigned int,
                                vector unsigned int);

vector unsigned short vec_mfvscr (void);

vector unsigned char vec_min (vector signed char, vector unsigned char);

vector unsigned char vec_min (vector unsigned char, vector signed char);

vector unsigned char vec_min (vector unsigned char,
                              vector unsigned char);
vector signed char vec_min (vector signed char, vector signed char);
vector unsigned short vec_min (vector signed short,
                               vector unsigned short);
vector unsigned short vec_min (vector unsigned short,
                               vector signed short);
vector unsigned short vec_min (vector unsigned short,
                               vector unsigned short);
vector signed short vec_min (vector signed short, vector signed short);
vector unsigned int vec_min (vector signed int, vector unsigned int);
vector unsigned int vec_min (vector unsigned int, vector signed int);
vector unsigned int vec_min (vector unsigned int, vector unsigned int);
vector signed int vec_min (vector signed int, vector signed int);
vector float vec_min (vector float, vector float);

vector signed short vec_mladd (vector signed short, vector signed short,
                               vector signed short);
vector signed short vec_mladd (vector signed short,
                               vector unsigned short,
                               vector unsigned short);
vector signed short vec_mladd (vector unsigned short,
                               vector signed short,
                               vector signed short);
vector unsigned short vec_mladd (vector unsigned short,
                                 vector unsigned short,
                                 vector unsigned short);

vector signed short vec_mradds (vector signed short,
                                vector signed short,
                                vector signed short);

vector unsigned int vec_msum (vector unsigned char,
                              vector unsigned char,
                              vector unsigned int);
vector signed int vec_msum (vector signed char, vector unsigned char,
                            vector signed int);
vector unsigned int vec_msum (vector unsigned short,
                              vector unsigned short,
                              vector unsigned int);
vector signed int vec_msum (vector signed short, vector signed short,
                            vector signed int);

vector unsigned int vec_msums (vector unsigned short,
                               vector unsigned short,
                               vector unsigned int);
vector signed int vec_msums (vector signed short, vector signed short,
                             vector signed int);

void vec_mtvscr (vector signed int);
void vec_mtvscr (vector unsigned int);
void vec_mtvscr (vector signed short);
void vec_mtvscr (vector unsigned short);
void vec_mtvscr (vector signed char);
void vec_mtvscr (vector unsigned char);

vector unsigned short vec_mule (vector unsigned char,
                                vector unsigned char);
vector signed short vec_mule (vector signed char, vector signed char);
vector unsigned int vec_mule (vector unsigned short,
                              vector unsigned short);
vector signed int vec_mule (vector signed short, vector signed short);

vector unsigned short vec_mulo (vector unsigned char,
                                vector unsigned char);
vector signed short vec_mulo (vector signed char, vector signed char);
vector unsigned int vec_mulo (vector unsigned short,
                              vector unsigned short);
vector signed int vec_mulo (vector signed short, vector signed short);

vector float vec_nmsub (vector float, vector float, vector float);

vector float vec_nor (vector float, vector float);
vector signed int vec_nor (vector signed int, vector signed int);
vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
vector signed short vec_nor (vector signed short, vector signed short);
vector unsigned short vec_nor (vector unsigned short,
                               vector unsigned short);
vector signed char vec_nor (vector signed char, vector signed char);
vector unsigned char vec_nor (vector unsigned char,
                              vector unsigned char);

vector float vec_or (vector float, vector float);
vector float vec_or (vector float, vector signed int);
vector float vec_or (vector signed int, vector float);
vector signed int vec_or (vector signed int, vector signed int);
vector unsigned int vec_or (vector signed int, vector unsigned int);
vector unsigned int vec_or (vector unsigned int, vector signed int);
vector unsigned int vec_or (vector unsigned int, vector unsigned int);
vector signed short vec_or (vector signed short, vector signed short);
vector unsigned short vec_or (vector signed short,
                              vector unsigned short);
vector unsigned short vec_or (vector unsigned short,
                              vector signed short);
vector unsigned short vec_or (vector unsigned short,
                              vector unsigned short);
vector signed char vec_or (vector signed char, vector signed char);
vector unsigned char vec_or (vector signed char, vector unsigned char);
vector unsigned char vec_or (vector unsigned char, vector signed char);
vector unsigned char vec_or (vector unsigned char,
                             vector unsigned char);

vector signed char vec_pack (vector signed short, vector signed short);
vector unsigned char vec_pack (vector unsigned short,
                               vector unsigned short);
vector signed short vec_pack (vector signed int, vector signed int);
vector unsigned short vec_pack (vector unsigned int,
                                vector unsigned int);

vector signed short vec_packpx (vector unsigned int,
                                vector unsigned int);

vector unsigned char vec_packs (vector unsigned short,
                                vector unsigned short);
vector signed char vec_packs (vector signed short, vector signed short);

vector unsigned short vec_packs (vector unsigned int,
                                 vector unsigned int);
vector signed short vec_packs (vector signed int, vector signed int);

vector unsigned char vec_packsu (vector unsigned short,
                                 vector unsigned short);
vector unsigned char vec_packsu (vector signed short,
                                 vector signed short);
vector unsigned short vec_packsu (vector unsigned int,
                                  vector unsigned int);
vector unsigned short vec_packsu (vector signed int, vector signed int);

vector float vec_perm (vector float, vector float,
                       vector unsigned char);
vector signed int vec_perm (vector signed int, vector signed int,
                            vector unsigned char);
vector unsigned int vec_perm (vector unsigned int, vector unsigned int,
                              vector unsigned char);
vector signed short vec_perm (vector signed short, vector signed short,
                              vector unsigned char);
vector unsigned short vec_perm (vector unsigned short,
                                vector unsigned short,
                                vector unsigned char);
vector signed char vec_perm (vector signed char, vector signed char,
                             vector unsigned char);
vector unsigned char vec_perm (vector unsigned char,
                               vector unsigned char,
                               vector unsigned char);

vector float vec_re (vector float);

vector signed char vec_rl (vector signed char, vector unsigned char);
vector unsigned char vec_rl (vector unsigned char,
                             vector unsigned char);
vector signed short vec_rl (vector signed short, vector unsigned short);

vector unsigned short vec_rl (vector unsigned short,
                              vector unsigned short);
vector signed int vec_rl (vector signed int, vector unsigned int);
vector unsigned int vec_rl (vector unsigned int, vector unsigned int);

vector float vec_round (vector float);

vector float vec_rsqrte (vector float);

vector float vec_sel (vector float, vector float, vector signed int);
vector float vec_sel (vector float, vector float, vector unsigned int);
vector signed int vec_sel (vector signed int, vector signed int,
                           vector signed int);
vector signed int vec_sel (vector signed int, vector signed int,
                           vector unsigned int);
vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
                             vector signed int);
vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
                             vector unsigned int);
vector signed short vec_sel (vector signed short, vector signed short,
                             vector signed short);
vector signed short vec_sel (vector signed short, vector signed short,
                             vector unsigned short);
vector unsigned short vec_sel (vector unsigned short,
                               vector unsigned short,
                               vector signed short);
vector unsigned short vec_sel (vector unsigned short,
                               vector unsigned short,
                               vector unsigned short);
vector signed char vec_sel (vector signed char, vector signed char,
                            vector signed char);
vector signed char vec_sel (vector signed char, vector signed char,
                            vector unsigned char);
vector unsigned char vec_sel (vector unsigned char,
                              vector unsigned char,
                              vector signed char);
vector unsigned char vec_sel (vector unsigned char,
                              vector unsigned char,
                              vector unsigned char);

vector signed char vec_sl (vector signed char, vector unsigned char);
vector unsigned char vec_sl (vector unsigned char,
                             vector unsigned char);
vector signed short vec_sl (vector signed short, vector unsigned short);

vector unsigned short vec_sl (vector unsigned short,
                              vector unsigned short);
vector signed int vec_sl (vector signed int, vector unsigned int);
vector unsigned int vec_sl (vector unsigned int, vector unsigned int);

vector float vec_sld (vector float, vector float, const char);
vector signed int vec_sld (vector signed int, vector signed int,
                           const char);
vector unsigned int vec_sld (vector unsigned int, vector unsigned int,
                             const char);
vector signed short vec_sld (vector signed short, vector signed short,
                             const char);
vector unsigned short vec_sld (vector unsigned short,
                               vector unsigned short, const char);
vector signed char vec_sld (vector signed char, vector signed char,
                            const char);
vector unsigned char vec_sld (vector unsigned char,
                              vector unsigned char,
                              const char);

vector signed int vec_sll (vector signed int, vector unsigned int);
vector signed int vec_sll (vector signed int, vector unsigned short);
vector signed int vec_sll (vector signed int, vector unsigned char);
vector unsigned int vec_sll (vector unsigned int, vector unsigned int);
vector unsigned int vec_sll (vector unsigned int,
                             vector unsigned short);
vector unsigned int vec_sll (vector unsigned int, vector unsigned char);

vector signed short vec_sll (vector signed short, vector unsigned int);
vector signed short vec_sll (vector signed short,
                             vector unsigned short);
vector signed short vec_sll (vector signed short, vector unsigned char);

vector unsigned short vec_sll (vector unsigned short,
                               vector unsigned int);
vector unsigned short vec_sll (vector unsigned short,
                               vector unsigned short);
vector unsigned short vec_sll (vector unsigned short,
                               vector unsigned char);
vector signed char vec_sll (vector signed char, vector unsigned int);
vector signed char vec_sll (vector signed char, vector unsigned short);
vector signed char vec_sll (vector signed char, vector unsigned char);
vector unsigned char vec_sll (vector unsigned char,
                              vector unsigned int);
vector unsigned char vec_sll (vector unsigned char,
                              vector unsigned short);
vector unsigned char vec_sll (vector unsigned char,
                              vector unsigned char);

vector float vec_slo (vector float, vector signed char);
vector float vec_slo (vector float, vector unsigned char);
vector signed int vec_slo (vector signed int, vector signed char);
vector signed int vec_slo (vector signed int, vector unsigned char);
vector unsigned int vec_slo (vector unsigned int, vector signed char);
vector unsigned int vec_slo (vector unsigned int, vector unsigned char);

vector signed short vec_slo (vector signed short, vector signed char);
vector signed short vec_slo (vector signed short, vector unsigned char);

vector unsigned short vec_slo (vector unsigned short,
                               vector signed char);
vector unsigned short vec_slo (vector unsigned short,
                               vector unsigned char);
vector signed char vec_slo (vector signed char, vector signed char);
vector signed char vec_slo (vector signed char, vector unsigned char);
vector unsigned char vec_slo (vector unsigned char, vector signed char);

vector unsigned char vec_slo (vector unsigned char,
                              vector unsigned char);

vector signed char vec_splat (vector signed char, const char);
vector unsigned char vec_splat (vector unsigned char, const char);
vector signed short vec_splat (vector signed short, const char);
vector unsigned short vec_splat (vector unsigned short, const char);
vector float vec_splat (vector float, const char);
vector signed int vec_splat (vector signed int, const char);
vector unsigned int vec_splat (vector unsigned int, const char);

vector signed char vec_splat_s8 (const char);

vector signed short vec_splat_s16 (const char);

vector signed int vec_splat_s32 (const char);

vector unsigned char vec_splat_u8 (const char);

vector unsigned short vec_splat_u16 (const char);

vector unsigned int vec_splat_u32 (const char);

vector signed char vec_sr (vector signed char, vector unsigned char);
vector unsigned char vec_sr (vector unsigned char,
                             vector unsigned char);
vector signed short vec_sr (vector signed short, vector unsigned short);

vector unsigned short vec_sr (vector unsigned short,
                              vector unsigned short);
vector signed int vec_sr (vector signed int, vector unsigned int);
vector unsigned int vec_sr (vector unsigned int, vector unsigned int);

vector signed char vec_sra (vector signed char, vector unsigned char);
vector unsigned char vec_sra (vector unsigned char,
                              vector unsigned char);
vector signed short vec_sra (vector signed short,
                             vector unsigned short);
vector unsigned short vec_sra (vector unsigned short,
                               vector unsigned short);
vector signed int vec_sra (vector signed int, vector unsigned int);
vector unsigned int vec_sra (vector unsigned int, vector unsigned int);

vector signed int vec_srl (vector signed int, vector unsigned int);
vector signed int vec_srl (vector signed int, vector unsigned short);
vector signed int vec_srl (vector signed int, vector unsigned char);
vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
vector unsigned int vec_srl (vector unsigned int,
                             vector unsigned short);
vector unsigned int vec_srl (vector unsigned int, vector unsigned char);

vector signed short vec_srl (vector signed short, vector unsigned int);
vector signed short vec_srl (vector signed short,
                             vector unsigned short);
vector signed short vec_srl (vector signed short, vector unsigned char);

vector unsigned short vec_srl (vector unsigned short,
                               vector unsigned int);
vector unsigned short vec_srl (vector unsigned short,
                               vector unsigned short);
vector unsigned short vec_srl (vector unsigned short,
                               vector unsigned char);
vector signed char vec_srl (vector signed char, vector unsigned int);
vector signed char vec_srl (vector signed char, vector unsigned short);
vector signed char vec_srl (vector signed char, vector unsigned char);
vector unsigned char vec_srl (vector unsigned char,
                              vector unsigned int);
vector unsigned char vec_srl (vector unsigned char,
                              vector unsigned short);
vector unsigned char vec_srl (vector unsigned char,
                              vector unsigned char);

vector float vec_sro (vector float, vector signed char);
vector float vec_sro (vector float, vector unsigned char);
vector signed int vec_sro (vector signed int, vector signed char);
vector signed int vec_sro (vector signed int, vector unsigned char);
vector unsigned int vec_sro (vector unsigned int, vector signed char);
vector unsigned int vec_sro (vector unsigned int, vector unsigned char);

vector signed short vec_sro (vector signed short, vector signed char);
vector signed short vec_sro (vector signed short, vector unsigned char);

vector unsigned short vec_sro (vector unsigned short,
                               vector signed char);
vector unsigned short vec_sro (vector unsigned short,
                               vector unsigned char);
vector signed char vec_sro (vector signed char, vector signed char);
vector signed char vec_sro (vector signed char, vector unsigned char);
vector unsigned char vec_sro (vector unsigned char, vector signed char);

vector unsigned char vec_sro (vector unsigned char,
                              vector unsigned char);

void vec_st (vector float, int, float *);
void vec_st (vector float, int, vector float *);
void vec_st (vector signed int, int, int *);
void vec_st (vector signed int, int, unsigned int *);
void vec_st (vector unsigned int, int, unsigned int *);
void vec_st (vector unsigned int, int, vector unsigned int *);
void vec_st (vector signed short, int, short *);
void vec_st (vector signed short, int, vector unsigned short *);
void vec_st (vector signed short, int, vector signed short *);
void vec_st (vector unsigned short, int, unsigned short *);
void vec_st (vector unsigned short, int, vector unsigned short *);
void vec_st (vector signed char, int, signed char *);
void vec_st (vector signed char, int, unsigned char *);
void vec_st (vector signed char, int, vector signed char *);
void vec_st (vector unsigned char, int, unsigned char *);
void vec_st (vector unsigned char, int, vector unsigned char *);

void vec_ste (vector signed char, int, unsigned char *);
void vec_ste (vector signed char, int, signed char *);
void vec_ste (vector unsigned char, int, unsigned char *);
void vec_ste (vector signed short, int, short *);
void vec_ste (vector signed short, int, unsigned short *);
void vec_ste (vector unsigned short, int, void *);
void vec_ste (vector signed int, int, unsigned int *);
void vec_ste (vector signed int, int, int *);
void vec_ste (vector unsigned int, int, unsigned int *);
void vec_ste (vector float, int, float *);

void vec_stl (vector float, int, vector float *);
void vec_stl (vector float, int, float *);
void vec_stl (vector signed int, int, vector signed int *);
void vec_stl (vector signed int, int, int *);
void vec_stl (vector signed int, int, unsigned int *);
void vec_stl (vector unsigned int, int, vector unsigned int *);
void vec_stl (vector unsigned int, int, unsigned int *);
void vec_stl (vector signed short, int, short *);
void vec_stl (vector signed short, int, unsigned short *);
void vec_stl (vector signed short, int, vector signed short *);
void vec_stl (vector unsigned short, int, unsigned short *);
void vec_stl (vector unsigned short, int, vector signed short *);
void vec_stl (vector signed char, int, signed char *);
void vec_stl (vector signed char, int, unsigned char *);
void vec_stl (vector signed char, int, vector signed char *);
void vec_stl (vector unsigned char, int, unsigned char *);
void vec_stl (vector unsigned char, int, vector unsigned char *);

vector signed char vec_sub (vector signed char, vector signed char);
vector unsigned char vec_sub (vector signed char, vector unsigned char);

vector unsigned char vec_sub (vector unsigned char, vector signed char);

vector unsigned char vec_sub (vector unsigned char,
                              vector unsigned char);
vector signed short vec_sub (vector signed short, vector signed short);
vector unsigned short vec_sub (vector signed short,
                               vector unsigned short);
vector unsigned short vec_sub (vector unsigned short,
                               vector signed short);
vector unsigned short vec_sub (vector unsigned short,
                               vector unsigned short);
vector signed int vec_sub (vector signed int, vector signed int);
vector unsigned int vec_sub (vector signed int, vector unsigned int);
vector unsigned int vec_sub (vector unsigned int, vector signed int);
vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
vector float vec_sub (vector float, vector float);

vector unsigned int vec_subc (vector unsigned int, vector unsigned int);

vector unsigned char vec_subs (vector signed char,
                               vector unsigned char);
vector unsigned char vec_subs (vector unsigned char,
                               vector signed char);
vector unsigned char vec_subs (vector unsigned char,
                               vector unsigned char);
vector signed char vec_subs (vector signed char, vector signed char);
vector unsigned short vec_subs (vector signed short,
                                vector unsigned short);
vector unsigned short vec_subs (vector unsigned short,
                                vector signed short);
vector unsigned short vec_subs (vector unsigned short,
                                vector unsigned short);
vector signed short vec_subs (vector signed short, vector signed short);

vector unsigned int vec_subs (vector signed int, vector unsigned int);
vector unsigned int vec_subs (vector unsigned int, vector signed int);
vector unsigned int vec_subs (vector unsigned int, vector unsigned int);

vector signed int vec_subs (vector signed int, vector signed int);

vector unsigned int vec_sum4s (vector unsigned char,
                               vector unsigned int);
vector signed int vec_sum4s (vector signed char, vector signed int);
vector signed int vec_sum4s (vector signed short, vector signed int);

vector signed int vec_sum2s (vector signed int, vector signed int);

vector signed int vec_sums (vector signed int, vector signed int);

vector float vec_trunc (vector float);

vector signed short vec_unpackh (vector signed char);
vector unsigned int vec_unpackh (vector signed short);
vector signed int vec_unpackh (vector signed short);

vector signed short vec_unpackl (vector signed char);
vector unsigned int vec_unpackl (vector signed short);
vector signed int vec_unpackl (vector signed short);

vector float vec_xor (vector float, vector float);
vector float vec_xor (vector float, vector signed int);
vector float vec_xor (vector signed int, vector float);
vector signed int vec_xor (vector signed int, vector signed int);
vector unsigned int vec_xor (vector signed int, vector unsigned int);
vector unsigned int vec_xor (vector unsigned int, vector signed int);
vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
vector signed short vec_xor (vector signed short, vector signed short);
vector unsigned short vec_xor (vector signed short,
                               vector unsigned short);
vector unsigned short vec_xor (vector unsigned short,
                               vector signed short);
vector unsigned short vec_xor (vector unsigned short,
                               vector unsigned short);
vector signed char vec_xor (vector signed char, vector signed char);
vector unsigned char vec_xor (vector signed char, vector unsigned char);

vector unsigned char vec_xor (vector unsigned char, vector signed char);

vector unsigned char vec_xor (vector unsigned char,
                              vector unsigned char);

vector signed int vec_all_eq (vector signed char, vector unsigned char);

vector signed int vec_all_eq (vector signed char, vector signed char);
vector signed int vec_all_eq (vector unsigned char, vector signed char);

vector signed int vec_all_eq (vector unsigned char,
                              vector unsigned char);
vector signed int vec_all_eq (vector signed short,
                              vector unsigned short);
vector signed int vec_all_eq (vector signed short, vector signed short);

vector signed int vec_all_eq (vector unsigned short,
                              vector signed short);
vector signed int vec_all_eq (vector unsigned short,
                              vector unsigned short);
vector signed int vec_all_eq (vector signed int, vector unsigned int);
vector signed int vec_all_eq (vector signed int, vector signed int);
vector signed int vec_all_eq (vector unsigned int, vector signed int);
vector signed int vec_all_eq (vector unsigned int, vector unsigned int);

vector signed int vec_all_eq (vector float, vector float);

vector signed int vec_all_ge (vector signed char, vector unsigned char);

vector signed int vec_all_ge (vector unsigned char, vector signed char);

vector signed int vec_all_ge (vector unsigned char,
                              vector unsigned char);
vector signed int vec_all_ge (vector signed char, vector signed char);
vector signed int vec_all_ge (vector signed short,
                              vector unsigned short);
vector signed int vec_all_ge (vector unsigned short,
                              vector signed short);
vector signed int vec_all_ge (vector unsigned short,
                              vector unsigned short);
vector signed int vec_all_ge (vector signed short, vector signed short);

vector signed int vec_all_ge (vector signed int, vector unsigned int);
vector signed int vec_all_ge (vector unsigned int, vector signed int);
vector signed int vec_all_ge (vector unsigned int, vector unsigned int);

vector signed int vec_all_ge (vector signed int, vector signed int);
vector signed int vec_all_ge (vector float, vector float);

vector signed int vec_all_gt (vector signed char, vector unsigned char);

vector signed int vec_all_gt (vector unsigned char, vector signed char);

vector signed int vec_all_gt (vector unsigned char,
                              vector unsigned char);
vector signed int vec_all_gt (vector signed char, vector signed char);
vector signed int vec_all_gt (vector signed short,
                              vector unsigned short);
vector signed int vec_all_gt (vector unsigned short,
                              vector signed short);
vector signed int vec_all_gt (vector unsigned short,
                              vector unsigned short);
vector signed int vec_all_gt (vector signed short, vector signed short);

vector signed int vec_all_gt (vector signed int, vector unsigned int);
vector signed int vec_all_gt (vector unsigned int, vector signed int);
vector signed int vec_all_gt (vector unsigned int, vector unsigned int);

vector signed int vec_all_gt (vector signed int, vector signed int);
vector signed int vec_all_gt (vector float, vector float);

vector signed int vec_all_in (vector float, vector float);

vector signed int vec_all_le (vector signed char, vector unsigned char);

vector signed int vec_all_le (vector unsigned char, vector signed char);

vector signed int vec_all_le (vector unsigned char,
                              vector unsigned char);
vector signed int vec_all_le (vector signed char, vector signed char);
vector signed int vec_all_le (vector signed short,
                              vector unsigned short);
vector signed int vec_all_le (vector unsigned short,
                              vector signed short);
vector signed int vec_all_le (vector unsigned short,
                              vector unsigned short);
vector signed int vec_all_le (vector signed short, vector signed short);

vector signed int vec_all_le (vector signed int, vector unsigned int);
vector signed int vec_all_le (vector unsigned int, vector signed int);
vector signed int vec_all_le (vector unsigned int, vector unsigned int);

vector signed int vec_all_le (vector signed int, vector signed int);
vector signed int vec_all_le (vector float, vector float);

vector signed int vec_all_lt (vector signed char, vector unsigned char);

vector signed int vec_all_lt (vector unsigned char, vector signed char);

vector signed int vec_all_lt (vector unsigned char,
                              vector unsigned char);
vector signed int vec_all_lt (vector signed char, vector signed char);
vector signed int vec_all_lt (vector signed short,
                              vector unsigned short);
vector signed int vec_all_lt (vector unsigned short,
                              vector signed short);
vector signed int vec_all_lt (vector unsigned short,
                              vector unsigned short);
vector signed int vec_all_lt (vector signed short, vector signed short);

vector signed int vec_all_lt (vector signed int, vector unsigned int);
vector signed int vec_all_lt (vector unsigned int, vector signed int);
vector signed int vec_all_lt (vector unsigned int, vector unsigned int);

vector signed int vec_all_lt (vector signed int, vector signed int);
vector signed int vec_all_lt (vector float, vector float);

vector signed int vec_all_nan (vector float);

vector signed int vec_all_ne (vector signed char, vector unsigned char);

vector signed int vec_all_ne (vector signed char, vector signed char);
vector signed int vec_all_ne (vector unsigned char, vector signed char);

vector signed int vec_all_ne (vector unsigned char,
                              vector unsigned char);
vector signed int vec_all_ne (vector signed short,
                              vector unsigned short);
vector signed int vec_all_ne (vector signed short, vector signed short);

vector signed int vec_all_ne (vector unsigned short,
                              vector signed short);
vector signed int vec_all_ne (vector unsigned short,
                              vector unsigned short);
vector signed int vec_all_ne (vector signed int, vector unsigned int);
vector signed int vec_all_ne (vector signed int, vector signed int);
vector signed int vec_all_ne (vector unsigned int, vector signed int);
vector signed int vec_all_ne (vector unsigned int, vector unsigned int);

vector signed int vec_all_ne (vector float, vector float);

vector signed int vec_all_nge (vector float, vector float);

vector signed int vec_all_ngt (vector float, vector float);

vector signed int vec_all_nle (vector float, vector float);

vector signed int vec_all_nlt (vector float, vector float);

vector signed int vec_all_numeric (vector float);

vector signed int vec_any_eq (vector signed char, vector unsigned char);

vector signed int vec_any_eq (vector signed char, vector signed char);
vector signed int vec_any_eq (vector unsigned char, vector signed char);

vector signed int vec_any_eq (vector unsigned char,
                              vector unsigned char);
vector signed int vec_any_eq (vector signed short,
                              vector unsigned short);
vector signed int vec_any_eq (vector signed short, vector signed short);

vector signed int vec_any_eq (vector unsigned short,
                              vector signed short);
vector signed int vec_any_eq (vector unsigned short,
                              vector unsigned short);
vector signed int vec_any_eq (vector signed int, vector unsigned int);
vector signed int vec_any_eq (vector signed int, vector signed int);
vector signed int vec_any_eq (vector unsigned int, vector signed int);
vector signed int vec_any_eq (vector unsigned int, vector unsigned int);

vector signed int vec_any_eq (vector float, vector float);

vector signed int vec_any_ge (vector signed char, vector unsigned char);

vector signed int vec_any_ge (vector unsigned char, vector signed char);

vector signed int vec_any_ge (vector unsigned char,
                              vector unsigned char);
vector signed int vec_any_ge (vector signed char, vector signed char);
vector signed int vec_any_ge (vector signed short,
                              vector unsigned short);
vector signed int vec_any_ge (vector unsigned short,
                              vector signed short);
vector signed int vec_any_ge (vector unsigned short,
                              vector unsigned short);
vector signed int vec_any_ge (vector signed short, vector signed short);

vector signed int vec_any_ge (vector signed int, vector unsigned int);
vector signed int vec_any_ge (vector unsigned int, vector signed int);
vector signed int vec_any_ge (vector unsigned int, vector unsigned int);

vector signed int vec_any_ge (vector signed int, vector signed int);
vector signed int vec_any_ge (vector float, vector float);

vector signed int vec_any_gt (vector signed char, vector unsigned char);

vector signed int vec_any_gt (vector unsigned char, vector signed char);

vector signed int vec_any_gt (vector unsigned char,
                              vector unsigned char);
vector signed int vec_any_gt (vector signed char, vector signed char);
vector signed int vec_any_gt (vector signed short,
                              vector unsigned short);
vector signed int vec_any_gt (vector unsigned short,
                              vector signed short);
vector signed int vec_any_gt (vector unsigned short,
                              vector unsigned short);
vector signed int vec_any_gt (vector signed short, vector signed short);

vector signed int vec_any_gt (vector signed int, vector unsigned int);
vector signed int vec_any_gt (vector unsigned int, vector signed int);
vector signed int vec_any_gt (vector unsigned int, vector unsigned int);

vector signed int vec_any_gt (vector signed int, vector signed int);
vector signed int vec_any_gt (vector float, vector float);

vector signed int vec_any_le (vector signed char, vector unsigned char);

vector signed int vec_any_le (vector unsigned char, vector signed char);

vector signed int vec_any_le (vector unsigned char,
                              vector unsigned char);
vector signed int vec_any_le (vector signed char, vector signed char);
vector signed int vec_any_le (vector signed short,
                              vector unsigned short);
vector signed int vec_any_le (vector unsigned short,
                              vector signed short);
vector signed int vec_any_le (vector unsigned short,
                              vector unsigned short);
vector signed int vec_any_le (vector signed short, vector signed short);

vector signed int vec_any_le (vector signed int, vector unsigned int);
vector signed int vec_any_le (vector unsigned int, vector signed int);
vector signed int vec_any_le (vector unsigned int, vector unsigned int);

vector signed int vec_any_le (vector signed int, vector signed int);
vector signed int vec_any_le (vector float, vector float);

vector signed int vec_any_lt (vector signed char, vector unsigned char);

vector signed int vec_any_lt (vector unsigned char, vector signed char);

vector signed int vec_any_lt (vector unsigned char,
                              vector unsigned char);
vector signed int vec_any_lt (vector signed char, vector signed char);
vector signed int vec_any_lt (vector signed short,
                              vector unsigned short);
vector signed int vec_any_lt (vector unsigned short,
                              vector signed short);
vector signed int vec_any_lt (vector unsigned short,
                              vector unsigned short);
vector signed int vec_any_lt (vector signed short, vector signed short);

vector signed int vec_any_lt (vector signed int, vector unsigned int);
vector signed int vec_any_lt (vector unsigned int, vector signed int);
vector signed int vec_any_lt (vector unsigned int, vector unsigned int);

vector signed int vec_any_lt (vector signed int, vector signed int);
vector signed int vec_any_lt (vector float, vector float);

vector signed int vec_any_nan (vector float);

vector signed int vec_any_ne (vector signed char, vector unsigned char);

vector signed int vec_any_ne (vector signed char, vector signed char);
vector signed int vec_any_ne (vector unsigned char, vector signed char);

vector signed int vec_any_ne (vector unsigned char,
                              vector unsigned char);
vector signed int vec_any_ne (vector signed short,
                              vector unsigned short);
vector signed int vec_any_ne (vector signed short, vector signed short);

vector signed int vec_any_ne (vector unsigned short,
                              vector signed short);
vector signed int vec_any_ne (vector unsigned short,
                              vector unsigned short);
vector signed int vec_any_ne (vector signed int, vector unsigned int);
vector signed int vec_any_ne (vector signed int, vector signed int);
vector signed int vec_any_ne (vector unsigned int, vector signed int);
vector signed int vec_any_ne (vector unsigned int, vector unsigned int);

vector signed int vec_any_ne (vector float, vector float);

vector signed int vec_any_nge (vector float, vector float);

vector signed int vec_any_ngt (vector float, vector float);

vector signed int vec_any_nle (vector float, vector float);

vector signed int vec_any_nlt (vector float, vector float);

vector signed int vec_any_numeric (vector float);

vector signed int vec_any_out (vector float, vector float);


Using the GNU Compiler Collection (GCC)

Node:Pragmas, Next:Unnamed Fields, Previous:Target Builtins, Up:C Extensions

Pragmas Accepted by GCC

GCC supports several types of pragmas, primarily in order to compile code originally written for other compilers. Note that in general we do not recommend the use of pragmas; See Function Attributes, for further explanation.

  • ARM Pragmas:
  • Darwin Pragmas:
  • Solaris Pragmas:
  • Tru64 Pragmas:


Using the GNU Compiler Collection (GCC)

Node:Preprocessing directives implementation, Next:Library functions implementation, Previous:Qualifiers implementation, Up:C Implementation

Preprocessing directives

  • How sequences in both forms of header names are mapped to headers or external source file names (6.4.7).
  • Whether the value of a character constant in a constant expression that controls conditional inclusion matches the value of the same character constant in the execution character set (6.10.1).
  • Whether the value of a single-character character constant in a constant expression that controls conditional inclusion may have a negative value (6.10.1).
  • The places that are searched for an included <> delimited header, and how the places are specified or the header is identified (6.10.2).
  • How the named source file is searched for in an included "" delimited header (6.10.2).
  • The method by which preprocessing tokens (possibly resulting from macro expansion) in a #include directive are combined into a header name (6.10.2).
  • The nesting limit for #include processing (6.10.2).
  • Whether the # operator inserts a \ character before the \ character that begins a universal character name in a character constant or string literal (6.10.3.2).
  • The behavior on each recognized non-STDC #pragma directive (6.10.6).
  • The definitions for __DATE__ and __TIME__ when respectively, the date and time of translation are not available (6.10.8).


Using the GNU Compiler Collection (GCC)

Node:Preprocessor Options, Next:Assembler Options, Previous:Optimize Options, Up:Invoking GCC

Options Controlling the Preprocessor

These options control the C preprocessor, which is run on each C source file before actual compilation.

If you use the -E option, nothing is done except preprocessing. Some of these options make sense only together with -E because they cause the preprocessor output to be unsuitable for actual compilation.

You can use -Wp,option to bypass the compiler driver and pass option directly through to the preprocessor. If option contains commas, it is split into multiple options at the commas. However, many options are modified, translated or interpreted by the compiler driver before being passed to the preprocessor, and -Wp forcibly bypasses this phase. The preprocessor's direct interface is undocumented and subject to change, so whenever possible you should avoid using -Wp and let the driver handle the options instead.

-D name
Predefine name as a macro, with definition 1.
-D name=definition
Predefine name as a macro, with definition definition. There are no restrictions on the contents of definition, but if you are invoking the preprocessor from a shell or shell-like program you may need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in the shell syntax.

If you wish to define a function-like macro on the command line, write its argument list with surrounding parentheses before the equals sign (if any). Parentheses are meaningful to most shells, so you will need to quote the option. With sh and csh, -D'name(args...)=definition' works.

-D and -U options are processed in the order they are given on the command line. All -imacros file and -include file options are processed after all -D and -U options.

-U name
Cancel any previous definition of name, either built in or provided with a -D option.
-undef
Do not predefine any system-specific macros. The common predefined macros remain defined.
-I dir
Add the directory dir to the list of directories to be searched for header files. Directories named by -I are searched before the standard system include directories.

It is dangerous to specify a standard system include directory in an -I option. This defeats the special treatment of system headers . It can also defeat the repairs to buggy system headers which GCC makes when it is installed.

-o file
Write output to file. This is the same as specifying file as the second non-option argument to cpp. gcc has a different interpretation of a second non-option argument, so you must use -o to specify the output file.
-Wall
Turns on all optional warnings which are desirable for normal code. At present this is -Wcomment and -Wtrigraphs. Note that many of the preprocessor's warnings are on by default and have no options to control them.
-Wcomment
-Wcomments
Warn whenever a comment-start sequence /* appears in a /* comment, or whenever a backslash-newline appears in a // comment. (Both forms have the same effect.)
-Wtrigraphs
Warn if any trigraphs are encountered. This option used to take effect only if -trigraphs was also specified, but now works independently. Warnings are not given for trigraphs within comments, as they do not affect the meaning of the program.
-Wtraditional
Warn about certain constructs that behave differently in traditional and ISO C. Also warn about ISO C constructs that have no traditional C equivalent, and problematic constructs which should be avoided.
-Wimport
Warn the first time #import is used.
-Wundef
Warn whenever an identifier which is not a macro is encountered in an #if directive, outside of defined. Such identifiers are replaced with zero.
-Werror
Make all warnings into hard errors. Source code which triggers warnings will be rejected.
-Wsystem-headers
Issue warnings for code in system headers. These are normally unhelpful in finding bugs in your own code, therefore suppressed. If you are responsible for the system library, you may want to see them.
-w
Suppress all warnings, including those which GNU CPP issues by default.
-pedantic
Issue all the mandatory diagnostics listed in the C standard. Some of them are left out by default, since they trigger frequently on harmless code.
-pedantic-errors
Issue all the mandatory diagnostics, and make all mandatory diagnostics into errors. This includes mandatory diagnostics that GCC issues without -pedantic but treats as warnings.
-M
Instead of outputting the result of preprocessing, output a rule suitable for make describing the dependencies of the main source file. The preprocessor outputs one make rule containing the object file name for that source file, a colon, and the names of all the included files, including those coming from -include or -imacros command line options.

Unless specified explicitly (with -MT or -MQ), the object file name consists of the basename of the source file with any suffix replaced with object file suffix. If there are many included files then the rule is split into several lines using \-newline. The rule has no commands.

This option does not suppress the preprocessor's debug output, such as -dM. To avoid mixing such debug output with the dependency rules you should explicitly specify the dependency output file with -MF, or use an environment variable like DEPENDENCIES_OUTPUT (see DEPENDENCIES_OUTPUT). Debug output will still be sent to the regular output stream as normal.

Passing -M to the driver implies -E.

-MM
Like -M but do not mention header files that are found in system header directories, nor header files that are included, directly or indirectly, from such a header.

This implies that the choice of angle brackets or double quotes in an #include directive does not in itself determine whether that header will appear in -MM dependency output. This is a slight change in semantics from GCC versions 3.0 and earlier.

-MF file
When used with -M or -MM, specifies a file to write the dependencies to. If no -MF switch is given the preprocessor sends the rules to the same place it would have sent preprocessed output.

When used with the driver options -MD or -MMD, -MF overrides the default dependency output file.

-MG
When used with -M or -MM, -MG says to treat missing header files as generated files and assume they live in the same directory as the source file. It suppresses preprocessed output, as a missing header file is ordinarily an error.

This feature is used in automatic updating of makefiles.

-MP
This option instructs CPP to add a phony target for each dependency other than the main file, causing each to depend on nothing. These dummy rules work around errors make gives if you remove header files without updating the Makefile to match.

This is typical output:

test.o: test.c test.h

test.h:

-MT target

Change the target of the rule emitted by dependency generation. By default CPP takes the name of the main input file, including any path, deletes any file suffix such as .c, and appends the platform's usual object suffix. The result is the target.

An -MT option will set the target to be exactly the string you specify. If you want multiple targets, you can specify them as a single argument to -MT, or use multiple -MT options.

For example, -MT '$(objpfx)foo.o' might give

$(objpfx)foo.o: foo.c

-MQ target

Same as -MT, but it quotes any characters which are special to Make. -MQ '$(objpfx)foo.o' gives

$$(objpfx)foo.o: foo.c

The default target is automatically quoted, as if it were given with -MQ.

-MD
-MD is equivalent to -M -MF file, except that -E is not implied. The driver determines file based on whether an -o option is given. If it is, the driver uses its argument but with a suffix of .d, otherwise it take the basename of the input file and applies a .d suffix.

If -MD is used in conjunction with -E, any -o switch is understood to specify the dependency output file (but see -MF), but if used without -E, each -o is understood to specify a target object file.

Since -E is not implied, -MD can be used to generate a dependency output file as a side-effect of the compilation process.

-MMD
Like -MD except mention only user header files, not system -header files.
-x c
-x c++
-x objective-c
-x assembler-with-cpp
Specify the source language: C, C++, Objective-C, or assembly. This has nothing to do with standards conformance or extensions; it merely selects which base syntax to expect. If you give none of these options, cpp will deduce the language from the extension of the source file: .c, .cc, .m, or .S. Some other common extensions for C++ and assembly are also recognized. If cpp does not recognize the extension, it will treat the file as C; this is the most generic mode.

Note: Previous versions of cpp accepted a -lang option which selected both the language and the standards conformance level. This option has been removed, because it conflicts with the -l option.

-std=standard
-ansi
Specify the standard to which the code should conform. Currently cpp only knows about the standards for C; other language standards will be added in the future.

standard may be one of:

iso9899:1990
c89
The ISO C standard from 1990. c89 is the customary shorthand for this version of the standard.

The -ansi option is equivalent to -std=c89.

iso9899:199409
The 1990 C standard, as amended in 1994.
iso9899:1999
c99
iso9899:199x
c9x
The revised ISO C standard, published in December 1999. Before publication, this was known as C9X.
gnu89
The 1990 C standard plus GNU extensions. This is the default.
gnu99
gnu9x
The 1999 C standard plus GNU extensions.

-I-
Split the include path. Any directories specified with -I options before -I- are searched only for headers requested with #include "file"; they are not searched for #include <file>. If additional directories are specified with -I options after the -I-, those directories are searched for all #include directives.

In addition, -I- inhibits the use of the directory of the current file directory as the first search directory for #include "file".

-nostdinc
Do not search the standard system directories for header files. Only the directories you have specified with -I options (and the directory of the current file, if appropriate) are searched.
-nostdinc++
Do not search for header files in the C++-specific standard directories, but do still search the other standard directories. (This option is used when building the C++ library.)
-include file
Process file as if #include "file" appeared as the first line of the primary source file. However, the first directory searched for file is the preprocessor's working directory instead of the directory containing the main source file. If not found there, it is searched for in the remainder of the #include "..." search chain as normal.

If multiple -include options are given, the files are included in the order they appear on the command line.

-imacros file
Exactly like -include, except that any output produced by scanning file is thrown away. Macros it defines remain defined. This allows you to acquire all the macros from a header without also processing its declarations.

All files specified by -imacros are processed before all files specified by -include.

-idirafter dir
Search dir for header files, but do it after all directories specified with -I and the standard system directories have been exhausted. dir is treated as a system include directory.
-iprefix prefix
Specify prefix as the prefix for subsequent -iwithprefix options. If the prefix represents a directory, you should include the final /.
-iwithprefix dir
-iwithprefixbefore dir
Append dir to the prefix specified previously with -iprefix, and add the resulting directory to the include search path. -iwithprefixbefore puts it in the same place -I would; -iwithprefix puts it where -idirafter would.

Use of these options is discouraged.

-isystem dir
Search dir for header files, after all directories specified by -I but before the standard system directories. Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories.
-fpreprocessed
Indicate to the preprocessor that the input file has already been preprocessed. This suppresses things like macro expansion, trigraph conversion, escaped newline splicing, and processing of most directives. The preprocessor still recognizes and removes comments, so that you can pass a file preprocessed with -C to the compiler without problems. In this mode the integrated preprocessor is little more than a tokenizer for the front ends.

-fpreprocessed is implicit if the input file has one of the extensions .i, .ii or .mi. These are the extensions that GCC uses for preprocessed files created by -save-temps.

-ftabstop=width
Set the distance between tab stops. This helps the preprocessor report correct column numbers in warnings or errors, even if tabs appear on the line. If the value is less than 1 or greater than 100, the option is ignored. The default is 8.
-fno-show-column
Do not print column numbers in diagnostics. This may be necessary if diagnostics are being scanned by a program that does not understand the column numbers, such as dejagnu.
-A predicate=answer
Make an assertion with the predicate predicate and answer answer. This form is preferred to the older form -A predicate(answer), which is still supported, because it does not use shell special characters.
-A -predicate=answer
Cancel an assertion with the predicate predicate and answer answer.
-A-
Cancel all predefined assertions and all assertions preceding it on the command line. Also, undefine all predefined macros and all macros preceding it on the command line. (This is a historical wart and may change in the future.)
-dCHARS
CHARS is a sequence of one or more of the following characters, and must not be preceded by a space. Other characters are interpreted by the compiler proper, or reserved for future versions of GCC, and so are silently ignored. If you specify characters whose behavior conflicts, the result is undefined.
M
Instead of the normal output, generate a list of #define directives for all the macros defined during the execution of the preprocessor, including predefined macros. This gives you a way of finding out what is predefined in your version of the preprocessor. Assuming you have no file foo.h, the command
touch foo.h; cpp -dM foo.h

will show all the predefined macros.

D
Like M except in two respects: it does not include the predefined macros, and it outputs both the #define directives and the result of preprocessing. Both kinds of output go to the standard output file.
N
Like D, but emit only the macro names, not their expansions.
I
Output #include directives in addition to the result of preprocessing.

-P
Inhibit generation of linemarkers in the output from the preprocessor. This might be useful when running the preprocessor on something that is not C code, and will be sent to a program which might be confused by the linemarkers.
-C
Do not discard comments. All comments are passed through to the output file, except for comments in processed directives, which are deleted along with the directive.

You should be prepared for side effects when using -C; it causes the preprocessor to treat comments as tokens in their own right. For example, comments appearing at the start of what would be a directive line have the effect of turning that line into an ordinary source line, since the first token on the line is no longer a #.

-gcc
Define the macros __GNUC__, __GNUC_MINOR__ and __GNUC_PATCHLEVEL__. These are defined automatically when you use gcc -E; you can turn them off in that case with -no-gcc.
-traditional
Try to imitate the behavior of old-fashioned C, as opposed to ISO C.
-trigraphs
Process trigraph sequences. These are three-character sequences, all starting with ??, that are defined by ISO C to stand for single characters. For example, ??/ stands for \, so '??/n' is a character constant for a newline. By default, GCC ignores trigraphs, but in standard-conforming modes it converts them. See the -std and -ansi options.

The nine trigraphs and their replacements are

Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
Replacement:      [    ]    {    }    #    \    ^    |    ~

-remap
Enable special code to work around file systems which only permit very short file names, such as MS-DOS.
-$
Forbid the use of $ in identifiers. The C standard allows implementations to define extra characters that can appear in identifiers. By default GNU CPP permits $, a common extension.
-h
--help
--target-help
Print text describing all the command line options instead of preprocessing anything.
-v
Verbose mode. Print out GNU CPP's version number at the beginning of execution, and report the final form of the include path.
-H
Print the name of each header file used, in addition to other normal activities. Each name is indented to show how deep in the #include stack it is.
-version
--version
Print out GNU CPP's version number. With one dash, proceed to preprocess as normal. With two dashes, exit immediately.


Using the GNU Compiler Collection (GCC)

Node:Protoize Caveats, Next:Non-bugs, Previous:C++ Misunderstandings, Up:Trouble

Caveats of using protoize

The conversion programs protoize and unprotoize can sometimes change a source file in a way that won't work unless you rearrange it.

  • protoize can insert references to a type name or type tag before the definition, or in a file where they are not defined.

    If this happens, compiler error messages should show you where the new references are, so fixing the file by hand is straightforward.

  • There are some C constructs which protoize cannot figure out. For example, it can't determine argument types for declaring a pointer-to-function variable; this you must do by hand. protoize inserts a comment containing ??? each time it finds such a variable; so you can find all such variables by searching for this string. ISO C does not require declaring the argument types of pointer-to-function types.
  • Using unprotoize can easily introduce bugs. If the program relied on prototypes to bring about conversion of arguments, these conversions will not take place in the program without prototypes. One case in which you can be sure unprotoize is safe is when you are removing prototypes that were made with protoize; if the program worked before without any prototypes, it will work again without them.

    You can find all the places where this problem might occur by compiling the program with the -Wconversion option. It prints a warning whenever an argument is converted.

  • Both conversion programs can be confused if there are macro calls in and around the text to be converted. In other words, the standard syntax for a declaration or definition must not result from expanding a macro. This problem is inherent in the design of C and cannot be fixed. If only a few functions have confusing macro calls, you can easily convert them manually.
  • protoize cannot get the argument types for a function whose definition was not actually compiled due to preprocessing conditionals. When this happens, protoize changes nothing in regard to such a function. protoize tries to detect such instances and warn about them.

    You can generally work around this problem by using protoize step by step, each time specifying a different set of -D options for compilation, until all of the functions have been converted. There is no automatic way to verify that you have got them all, however.

  • Confusion may result if there is an occasion to convert a function declaration or definition in a region of source code where there is more than one formal parameter list present. Thus, attempts to convert code containing multiple (conditionally compiled) versions of a single function header (in the same vicinity) may not produce the desired (or expected) results.

    If you plan on converting source files which contain such code, it is recommended that you first make sure that each conditionally compiled region of source code which contains an alternative function header also contains at least one additional follower token (past the final right parenthesis of the function header). This should circumvent the problem.

  • unprotoize can become confused when trying to convert a function definition or declaration which contains a declaration for a pointer-to-function formal argument which has the same name as the function being defined or declared. We recommend you avoid such choices of formal parameter names.
  • You might also want to correct some of the indentation by hand and break long lines. (The conversion programs don't write lines longer than eighty characters in any case.)


Using the GNU Compiler Collection (GCC)

Node:Qualifiers implementation, Next:Preprocessing directives implementation, Previous:Structures unions enumerations and bit-fields implementation, Up:C Implementation

Qualifiers

  • What constitutes an access to an object that has volatile-qualified type (6.7.3).


Using the GNU Compiler Collection (GCC)

Node:Restricted Pointers, Next:Vague Linkage, Previous:Volatiles, Up:C++ Extensions

Restricting Pointer Aliasing

As with gcc, g++ understands the C99 feature of restricted pointers, specified with the __restrict__, or __restrict type qualifier. Because you cannot compile C++ by specifying the -std=c99 language flag, restrict is not a keyword in C++.

In addition to allowing restricted pointers, you can specify restricted references, which indicate that the reference is not aliased in the local context.

void fn (int *__restrict__ rptr, int &__restrict__ rref)
{
  ...
}

In the body of fn, rptr points to an unaliased integer and rref refers to a (different) unaliased integer.

You may also specify whether a member function's this pointer is unaliased by using __restrict__ as a member function qualifier.

void T::fn () __restrict__
{
  ...
}

Within the body of T::fn, this will have the effective definition T *__restrict__ const this. Notice that the interpretation of a __restrict__ member function qualifier is different to that of const or volatile qualifier, in that it is applied to the pointer rather than the object. This is consistent with other compilers which implement restricted pointers.

As with all outermost parameter qualifiers, __restrict__ is ignored in function definition matching. This means you only need to specify __restrict__ in a function definition, rather than in a function prototype as well.


Using the GNU Compiler Collection (GCC)

Node:Return Address, Next:Vector Extensions, Previous:Function Names, Up:C Extensions

Getting the Return or Frame Address of a Function

These functions may be used to get information about the callers of a function.

void * __builtin_return_address (unsigned int level) Built-in Function
This function returns the return address of the current function, or of one of its callers. The level argument is number of frames to scan up the call stack. A value of 0 yields the return address of the current function, a value of 1 yields the return address of the caller of the current function, and so forth.

The level argument must be a constant integer.

On some machines it may be impossible to determine the return address of any function other than the current one; in such cases, or when the top of the stack has been reached, this function will return 0 or a random value. In addition, __builtin_frame_address may be used to determine if the top of the stack has been reached.

This function should only be used with a nonzero argument for debugging purposes.

void * __builtin_frame_address (unsigned int level) Built-in Function
This function is similar to __builtin_return_address, but it returns the address of the function frame rather than the return address of the function. Calling __builtin_frame_address with a value of 0 yields the frame address of the current function, a value of 1 yields the frame address of the caller of the current function, and so forth.

The frame is the area on the stack which holds local variables and saved registers. The frame address is normally the address of the first word pushed on to the stack by the function. However, the exact definition depends upon the processor and the calling convention. If the processor has a dedicated frame pointer register, and the function has a frame, then __builtin_frame_address will return the value of the frame pointer register.

On some machines it may be impossible to determine the frame address of any function other than the current one; in such cases, or when the top of the stack has been reached, this function will return 0 if the first frame pointer is properly initialized by the startup code.

This function should only be used with a nonzero argument for debugging purposes.


Using the GNU Compiler Collection (GCC)

Node:RS/6000 and PowerPC Options, Next:RT Options, Previous:M88K Options, Up:Submodel Options

IBM RS/6000 and PowerPC Options

These -m options are defined for the IBM RS/6000 and PowerPC:

-mpower
-mno-power
-mpower2
-mno-power2
-mpowerpc
-mno-powerpc
-mpowerpc-gpopt
-mno-powerpc-gpopt
-mpowerpc-gfxopt
-mno-powerpc-gfxopt
-mpowerpc64
-mno-powerpc64
GCC supports two related instruction set architectures for the RS/6000 and PowerPC. The POWER instruction set are those instructions supported by the rios chip set used in the original RS/6000 systems and the PowerPC instruction set is the architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and the IBM 4xx microprocessors.

Neither architecture is a subset of the other. However there is a large common subset of instructions supported by both. An MQ register is included in processors supporting the POWER architecture.

You use these options to specify which instructions are available on the processor you are using. The default value of these options is determined when configuring GCC. Specifying the -mcpu=cpu_type overrides the specification of these options. We recommend you use the -mcpu=cpu_type option rather than the options listed above.

The -mpower option allows GCC to generate instructions that are found only in the POWER architecture and to use the MQ register. Specifying -mpower2 implies -power and also allows GCC to generate instructions that are present in the POWER2 architecture but not the original POWER architecture.

The -mpowerpc option allows GCC to generate instructions that are found only in the 32-bit subset of the PowerPC architecture. Specifying -mpowerpc-gpopt implies -mpowerpc and also allows GCC to use the optional PowerPC architecture instructions in the General Purpose group, including floating-point square root. Specifying -mpowerpc-gfxopt implies -mpowerpc and also allows GCC to use the optional PowerPC architecture instructions in the Graphics group, including floating-point select.

The -mpowerpc64 option allows GCC to generate the additional 64-bit instructions that are found in the full PowerPC64 architecture and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to -mno-powerpc64.

If you specify both -mno-power and -mno-powerpc, GCC will use only the instructions in the common subset of both architectures plus some special AIX common-mode calls, and will not use the MQ register. Specifying both -mpower and -mpowerpc permits GCC to use any instruction from either architecture and to allow use of the MQ register; specify this for the Motorola MPC601.

-mnew-mnemonics
-mold-mnemonics
Select which mnemonics to use in the generated assembler code. With -mnew-mnemonics, GCC uses the assembler mnemonics defined for the PowerPC architecture. With -mold-mnemonics it uses the assembler mnemonics defined for the POWER architecture. Instructions defined in only one architecture have only one mnemonic; GCC uses that mnemonic irrespective of which of these options is specified.

GCC defaults to the mnemonics appropriate for the architecture in use. Specifying -mcpu=cpu_type sometimes overrides the value of these option. Unless you are building a cross-compiler, you should normally not specify either -mnew-mnemonics or -mold-mnemonics, but should instead accept the default.

-mcpu=cpu_type
Set architecture type, register usage, choice of mnemonics, and instruction scheduling parameters for machine type cpu_type. Supported values for cpu_type are rios, rios1, rsc, rios2, rs64a, 601, 602, 603, 603e, 604, 604e, 620, 630, 740, 7400, 7450, 750, power, power2, powerpc, 403, 505, 801, 821, 823, and 860 and common.

-mcpu=common selects a completely generic processor. Code generated under this option will run on any POWER or PowerPC processor. GCC will use only the instructions in the common subset of both architectures, and will not use the MQ register. GCC assumes a generic processor model for scheduling purposes.

-mcpu=power, -mcpu=power2, -mcpu=powerpc, and -mcpu=powerpc64 specify generic POWER, POWER2, pure 32-bit PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine types, with an appropriate, generic processor model assumed for scheduling purposes.

The other options specify a specific processor. Code generated under those options will run best on that processor, and may not run at all on others.

The -mcpu options automatically enable or disable other -m options as follows:

common
-mno-power, -mno-powerc
power
power2
rios1
rios2
rsc
-mpower, -mno-powerpc, -mno-new-mnemonics
powerpc
rs64a
602
603
603e
604
620
630
740
7400
7450
750
505
-mno-power, -mpowerpc, -mnew-mnemonics
601
-mpower, -mpowerpc, -mnew-mnemonics
403
821
860
-mno-power, -mpowerpc, -mnew-mnemonics, -msoft-float

-mtune=cpu_type
Set the instruction scheduling parameters for machine type cpu_type, but do not set the architecture type, register usage, or choice of mnemonics, as -mcpu=cpu_type would. The same values for cpu_type are used for -mtune as for -mcpu. If both are specified, the code generated will use the architecture, registers, and mnemonics set by -mcpu, but the scheduling parameters set by -mtune.
-maltivec
-mno-altivec
These switches enable or disable the use of built-in functions that allow access to the AltiVec instruction set. You may also need to set -mabi=altivec to adjust the current ABI with AltiVec ABI enhancements.
-mfull-toc
-mno-fp-in-toc
-mno-sum-in-toc
-mminimal-toc
Modify generation of the TOC (Table Of Contents), which is created for every executable file. The -mfull-toc option is selected by default. In that case, GCC will allocate at least one TOC entry for each unique non-automatic variable reference in your program. GCC will also place floating-point constants in the TOC. However, only 16,384 entries are available in the TOC.

If you receive a linker error message that saying you have overflowed the available TOC space, you can reduce the amount of TOC space used with the -mno-fp-in-toc and -mno-sum-in-toc options. -mno-fp-in-toc prevents GCC from putting floating-point constants in the TOC and -mno-sum-in-toc forces GCC to generate code to calculate the sum of an address and a constant at run-time instead of putting that sum into the TOC. You may specify one or both of these options. Each causes GCC to produce very slightly slower and larger code at the expense of conserving TOC space.

If you still run out of space in the TOC even when you specify both of these options, specify -mminimal-toc instead. This option causes GCC to make only one TOC entry for every file. When you specify this option, GCC will produce code that is slower and larger but which uses extremely little TOC space. You may wish to use this option only on files that contain less frequently executed code.

-maix64
-maix32
Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit long type, and the infrastructure needed to support them. Specifying -maix64 implies -mpowerpc64 and -mpowerpc, while -maix32 disables the 64-bit ABI and implies -mno-powerpc64. GCC defaults to -maix32.
-mxl-call
-mno-xl-call
On AIX, pass floating-point arguments to prototyped functions beyond the register save area (RSA) on the stack in addition to argument FPRs. The AIX calling convention was extended but not initially documented to handle an obscure K&R C case of calling a function that takes the address of its arguments with fewer arguments than declared. AIX XL compilers access floating point arguments which do not fit in the RSA from the stack when a subroutine is compiled without optimization. Because always storing floating-point arguments on the stack is inefficient and rarely needed, this option is not enabled by default and only is necessary when calling subroutines compiled by AIX XL compilers without optimization.
-mpe
Support IBM RS/6000 SP Parallel Environment (PE). Link an application written to use message passing with special startup code to enable the application to run. The system must have PE installed in the standard location (/usr/lpp/ppe.poe/), or the specs file must be overridden with the -specs= option to specify the appropriate directory location. The Parallel Environment does not support threads, so the -mpe option and the -pthread option are incompatible.
-msoft-float
-mhard-float
Generate code that does not use (uses) the floating-point register set. Software floating point emulation is provided if you use the -msoft-float option, and pass the option to GCC when linking.
-mmultiple
-mno-multiple
Generate code that uses (does not use) the load multiple word instructions and the store multiple word instructions. These instructions are generated by default on POWER systems, and not generated on PowerPC systems. Do not use -mmultiple on little endian PowerPC systems, since those instructions do not work when the processor is in little endian mode. The exceptions are PPC740 and PPC750 which permit the instructions usage in little endian mode.
-mstring
-mno-string
Generate code that uses (does not use) the load string instructions and the store string word instructions to save multiple registers and do small block moves. These instructions are generated by default on POWER systems, and not generated on PowerPC systems. Do not use -mstring on little endian PowerPC systems, since those instructions do not work when the processor is in little endian mode. The exceptions are PPC740 and PPC750 which permit the instructions usage in little endian mode.
-mupdate
-mno-update
Generate code that uses (does not use) the load or store instructions that update the base register to the address of the calculated memory location. These instructions are generated by default. If you use -mno-update, there is a small window between the time that the stack pointer is updated and the address of the previous frame is stored, which means code that walks the stack frame across interrupts or signals may get corrupted data.
-mfused-madd
-mno-fused-madd
Generate code that uses (does not use) the floating point multiply and accumulate instructions. These instructions are generated by default if hardware floating is used.
-mno-bit-align
-mbit-align
On System V.4 and embedded PowerPC systems do not (do) force structures and unions that contain bit-fields to be aligned to the base type of the bit-field.

For example, by default a structure containing nothing but 8 unsigned bit-fields of length 1 would be aligned to a 4 byte boundary and have a size of 4 bytes. By using -mno-bit-align, the structure would be aligned to a 1 byte boundary and be one byte in size.

-mno-strict-align
-mstrict-align
On System V.4 and embedded PowerPC systems do not (do) assume that unaligned memory references will be handled by the system.
-mrelocatable
-mno-relocatable
On embedded PowerPC systems generate code that allows (does not allow) the program to be relocated to a different address at runtime. If you use -mrelocatable on any module, all objects linked together must be compiled with -mrelocatable or -mrelocatable-lib.
-mrelocatable-lib
-mno-relocatable-lib
On embedded PowerPC systems generate code that allows (does not allow) the program to be relocated to a different address at runtime. Modules compiled with -mrelocatable-lib can be linked with either modules compiled without -mrelocatable and -mrelocatable-lib or with modules compiled with the -mrelocatable options.
-mno-toc
-mtoc
On System V.4 and embedded PowerPC systems do not (do) assume that register 2 contains a pointer to a global area pointing to the addresses used in the program.
-mlittle
-mlittle-endian
On System V.4 and embedded PowerPC systems compile code for the processor in little endian mode. The -mlittle-endian option is the same as -mlittle.
-mbig
-mbig-endian
On System V.4 and embedded PowerPC systems compile code for the processor in big endian mode. The -mbig-endian option is the same as -mbig.
-mcall-sysv
On System V.4 and embedded PowerPC systems compile code using calling conventions that adheres to the March 1995 draft of the System V Application Binary Interface, PowerPC processor supplement. This is the default unless you configured GCC using powerpc-*-eabiaix.
-mcall-sysv-eabi
Specify both -mcall-sysv and -meabi options.
-mcall-sysv-noeabi
Specify both -mcall-sysv and -mno-eabi options.
-mcall-aix
On System V.4 and embedded PowerPC systems compile code using calling conventions that are similar to those used on AIX. This is the default if you configured GCC using powerpc-*-eabiaix.
-mcall-solaris
On System V.4 and embedded PowerPC systems compile code for the Solaris operating system.
-mcall-linux
On System V.4 and embedded PowerPC systems compile code for the Linux-based GNU system.
-mcall-gnu
On System V.4 and embedded PowerPC systems compile code for the Hurd-based GNU system.
-mcall-netbsd
On System V.4 and embedded PowerPC systems compile code for the NetBSD operating system.
-maix-struct-return
Return all structures in memory (as specified by the AIX ABI).
-msvr4-struct-return
Return structures smaller than 8 bytes in registers (as specified by the SVR4 ABI).
-mabi=altivec
Extend the current ABI with AltiVec ABI extensions. This does not change the default ABI, instead it adds the AltiVec ABI extensions to the current ABI.
-mabi=no-altivec
Disable AltiVec ABI extensions for the current ABI.
-mprototype
-mno-prototype
On System V.4 and embedded PowerPC systems assume that all calls to variable argument functions are properly prototyped. Otherwise, the compiler must insert an instruction before every non prototyped call to set or clear bit 6 of the condition code register (CR) to indicate whether floating point values were passed in the floating point registers in case the function takes a variable arguments. With -mprototype, only calls to prototyped variable argument functions will set or clear the bit.
-msim
On embedded PowerPC systems, assume that the startup module is called sim-crt0.o and that the standard C libraries are libsim.a and libc.a. This is the default for powerpc-*-eabisim. configurations.
-mmvme
On embedded PowerPC systems, assume that the startup module is called crt0.o and the standard C libraries are libmvme.a and libc.a.
-mads
On embedded PowerPC systems, assume that the startup module is called crt0.o and the standard C libraries are libads.a and libc.a.
-myellowknife
On embedded PowerPC systems, assume that the startup module is called crt0.o and the standard C libraries are libyk.a and libc.a.
-mvxworks
On System V.4 and embedded PowerPC systems, specify that you are compiling for a VxWorks system.
-memb
On embedded PowerPC systems, set the PPC_EMB bit in the ELF flags header to indicate that eabi extended relocations are used.
-meabi
-mno-eabi
On System V.4 and embedded PowerPC systems do (do not) adhere to the Embedded Applications Binary Interface (eabi) which is a set of modifications to the System V.4 specifications. Selecting -meabi means that the stack is aligned to an 8 byte boundary, a function __eabi is called to from main to set up the eabi environment, and the -msdata option can use both r2 and r13 to point to two separate small data areas. Selecting -mno-eabi means that the stack is aligned to a 16 byte boundary, do not call an initialization function from main, and the -msdata option will only use r13 to point to a single small data area. The -meabi option is on by default if you configured GCC using one of the powerpc*-*-eabi* options.
-msdata=eabi
On System V.4 and embedded PowerPC systems, put small initialized const global and static data in the .sdata2 section, which is pointed to by register r2. Put small initialized non-const global and static data in the .sdata section, which is pointed to by register r13. Put small uninitialized global and static data in the .sbss section, which is adjacent to the .sdata section. The -msdata=eabi option is incompatible with the -mrelocatable option. The -msdata=eabi option also sets the -memb option.
-msdata=sysv
On System V.4 and embedded PowerPC systems, put small global and static data in the .sdata section, which is pointed to by register r13. Put small uninitialized global and static data in the .sbss section, which is adjacent to the .sdata section. The -msdata=sysv option is incompatible with the -mrelocatable option.
-msdata=default
-msdata
On System V.4 and embedded PowerPC systems, if -meabi is used, compile code the same as -msdata=eabi, otherwise compile code the same as -msdata=sysv.
-msdata-data
On System V.4 and embedded PowerPC systems, put small global and static data in the .sdata section. Put small uninitialized global and static data in the .sbss section. Do not use register r13 to address small data however. This is the default behavior unless other -msdata options are used.
-msdata=none
-mno-sdata
On embedded PowerPC systems, put all initialized global and static data in the .data section, and all uninitialized data in the .bss section.
-G num
On embedded PowerPC systems, put global and static items less than or equal to num bytes into the small data or bss sections instead of the normal data or bss section. By default, num is 8. The -G num switch is also passed to the linker. All modules should be compiled with the same -G num value.
-mregnames
-mno-regnames
On System V.4 and embedded PowerPC systems do (do not) emit register names in the assembly language output using symbolic forms.
-pthread
Adds support for multithreading with the pthreads library. This option sets flags for both the preprocessor and linker.


Using the GNU Compiler Collection (GCC)

Node:RT Options, Next:MIPS Options, Previous:RS/6000 and PowerPC Options, Up:Submodel Options

IBM RT Options

These -m options are defined for the IBM RT PC:

-min-line-mul
Use an in-line code sequence for integer multiplies. This is the default.
-mcall-lib-mul
Call lmul$$ for integer multiples.
-mfull-fp-blocks
Generate full-size floating point data blocks, including the minimum amount of scratch space recommended by IBM. This is the default.
-mminimum-fp-blocks
Do not include extra scratch space in floating point data blocks. This results in smaller code, but slower execution, since scratch space must be allocated dynamically.
-mfp-arg-in-fpregs
Use a calling sequence incompatible with the IBM calling convention in which floating point arguments are passed in floating point registers. Note that varargs.h and stdarg.h will not work with floating point operands if this option is specified.
-mfp-arg-in-gregs
Use the normal calling convention for floating point arguments. This is the default.
-mhc-struct-return
Return structures of more than one word in memory, rather than in a register. This provides compatibility with the MetaWare HighC (hc) compiler. Use the option -fpcc-struct-return for compatibility with the Portable C Compiler (pcc).
-mnohc-struct-return
Return some structures of more than one word in registers, when convenient. This is the default. For compatibility with the IBM-supplied compilers, use the option -fpcc-struct-return or the option -mhc-struct-return.


Using the GNU Compiler Collection (GCC)

Node:Running Protoize, Previous:Environment Variables, Up:Invoking GCC

Running Protoize

The program protoize is an optional part of GCC. You can use it to add prototypes to a program, thus converting the program to ISO C in one respect. The companion program unprotoize does the reverse: it removes argument types from any prototypes that are found.

When you run these programs, you must specify a set of source files as command line arguments. The conversion programs start out by compiling these files to see what functions they define. The information gathered about a file foo is saved in a file named foo.X.

After scanning comes actual conversion. The specified files are all eligible to be converted; any files they include (whether sources or just headers) are eligible as well.

But not all the eligible files are converted. By default, protoize and unprotoize convert only source and header files in the current directory. You can specify additional directories whose files should be converted with the -d directory option. You can also specify particular files to exclude with the -x file option. A file is converted if it is eligible, its directory name matches one of the specified directory names, and its name within the directory has not been excluded.

Basic conversion with protoize consists of rewriting most function definitions and function declarations to specify the types of the arguments. The only ones not rewritten are those for varargs functions.

protoize optionally inserts prototype declarations at the beginning of the source file, to make them available for any calls that precede the function's definition. Or it can insert prototype declarations with block scope in the blocks where undeclared functions are called.

Basic conversion with unprotoize consists of rewriting most function declarations to remove any argument types, and rewriting function definitions to the old-style pre-ISO form.

Both conversion programs print a warning for any function declaration or definition that they can't convert. You can suppress these warnings with -q.

The output from protoize or unprotoize replaces the original source file. The original file is renamed to a name ending with .save (for DOS, the saved filename ends in .sav without the original .c suffix). If the .save (.sav for DOS) file already exists, then the source file is simply discarded.

protoize and unprotoize both depend on GCC itself to scan the program and collect information about the functions it uses. So neither of these programs will work until GCC is installed.

Here is a table of the options you can use with protoize and unprotoize. Each option works with both programs unless otherwise stated.

-B directory
Look for the file SYSCALLS.c.X in directory, instead of the usual directory (normally /usr/local/lib). This file contains prototype information about standard system functions. This option applies only to protoize.
-c compilation-options
Use compilation-options as the options when running gcc to produce the .X files. The special option -aux-info is always passed in addition, to tell gcc to write a .X file.

Note that the compilation options must be given as a single argument to protoize or unprotoize. If you want to specify several gcc options, you must quote the entire set of compilation options to make them a single word in the shell.

There are certain gcc arguments that you cannot use, because they would produce the wrong kind of output. These include -g, -O, -c, -S, and -o If you include these in the compilation-options, they are ignored.

-C
Rename files to end in .C (.cc for DOS-based file systems) instead of .c. This is convenient if you are converting a C program to C++. This option applies only to protoize.
-g
Add explicit global declarations. This means inserting explicit declarations at the beginning of each source file for each function that is called in the file and was not declared. These declarations precede the first function definition that contains a call to an undeclared function. This option applies only to protoize.
-i string
Indent old-style parameter declarations with the string string. This option applies only to protoize.

unprotoize converts prototyped function definitions to old-style function definitions, where the arguments are declared between the argument list and the initial {. By default, unprotoize uses five spaces as the indentation. If you want to indent with just one space instead, use -i " ".

-k
Keep the .X files. Normally, they are deleted after conversion is finished.
-l
Add explicit local declarations. protoize with -l inserts a prototype declaration for each function in each block which calls the function without any declaration. This option applies only to protoize.
-n
Make no real changes. This mode just prints information about the conversions that would have been done without -n.
-N
Make no .save files. The original files are simply deleted. Use this option with caution.
-p program
Use the program program as the compiler. Normally, the name gcc is used.
-q
Work quietly. Most warnings are suppressed.
-v
Print the version number, just like -v for gcc.

If you need special compiler options to compile one of your program's source files, then you should generate that file's .X file specially, by running gcc on that source file with the appropriate options and the option -aux-info. Then run protoize on the entire set of files. protoize will use the existing .X file because it is newer than the source file. For example:

gcc -Dfoo=bar file1.c -aux-info file1.X
protoize *.c

You need to include the special files along with the rest in the protoize command, even though their .X files already exist, because otherwise they won't get converted.

See Protoize Caveats, for more information on how to use protoize successfully.


Using the GNU Compiler Collection (GCC)

Node:S/390 and zSeries Options, Next:CRIS Options, Previous:D30V Options, Up:Submodel Options

S/390 and zSeries Options

These are the -m options defined for the S/390 and zSeries architecture.

-mhard-float
-msoft-float
Use (do not use) the hardware floating-point instructions and registers for floating-point operations. When -msoft-float is specified, functions in libgcc.a will be used to perform floating-point operations. When -mhard-float is specified, the compiler generates IEEE floating-point instructions. This is the default.
-mbackchain
-mno-backchain
Generate (or do not generate) code which maintains an explicit backchain within the stack frame that points to the caller's frame. This is currently needed to allow debugging. The default is to generate the backchain.
-msmall-exec
-mno-small-exec
Generate (or do not generate) code using the bras instruction to do subroutine calls. This only works reliably if the total executable size does not exceed 64k. The default is to use the basr instruction instead, which does not have this limitation.
-m64
-m31
When -m31 is specified, generate code compliant to the Linux for S/390 ABI. When -m64 is specified, generate code compliant to the Linux for zSeries ABI. This allows GCC in particular to generate 64-bit instructions. For the s390 targets, the default is -m31, while the s390x targets default to -m64.
-mmvcle
-mno-mvcle
Generate (or do not generate) code using the mvcle instruction to perform block moves. When -mno-mvcle is specifed, use a mvc loop instead. This is the default.
-mdebug
-mno-debug
Print (or do not print) additional debug information when compiling. The default is to not print debug information.


Using the GNU Compiler Collection (GCC)

Node:Service, Next:Contributing, Previous:Bugs, Up:Top

How To Get Help with GCC

If you need help installing, using or changing GCC, there are two ways to find it:

  • Send a message to a suitable network mailing list. First try gcc-help@gcc.gnu.org (for help installing or using GCC), and if that brings no response, try gcc@gcc.gnu.org. For help changing GCC, ask gcc@gcc.gnu.org. If you think you have found a bug in GCC, please report it following the instructions at see Bug Reporting.
  • Look in the service directory for someone who might help you for a fee. The service directory is found at http://www.gnu.org/prep/service.html.


Using the GNU Compiler Collection (GCC)

Node:SH Options, Next:System V Options, Previous:H8/300 Options, Up:Submodel Options

SH Options

These -m options are defined for the SH implementations:

-m1
Generate code for the SH1.
-m2
Generate code for the SH2.
-m3
Generate code for the SH3.
-m3e
Generate code for the SH3e.
-m4-nofpu
Generate code for the SH4 without a floating-point unit.
-m4-single-only
Generate code for the SH4 with a floating-point unit that only supports single-precision arithmetic.
-m4-single
Generate code for the SH4 assuming the floating-point unit is in single-precision mode by default.
-m4
Generate code for the SH4.
-mb
Compile code for the processor in big endian mode.
-ml
Compile code for the processor in little endian mode.
-mdalign
Align doubles at 64-bit boundaries. Note that this changes the calling conventions, and thus some functions from the standard C library will not work unless you recompile it first with -mdalign.
-mrelax
Shorten some address references at link time, when possible; uses the linker option -relax.
-mbigtable
Use 32-bit offsets in switch tables. The default is to use 16-bit offsets.
-mfmovd
Enable the use of the instruction fmovd.
-mhitachi
Comply with the calling conventions defined by Hitachi.
-mnomacsave
Mark the MAC register as call-clobbered, even if -mhitachi is given.
-mieee
Increase IEEE-compliance of floating-point code.
-misize
Dump instruction size and location in the assembly code.
-mpadstruct
This option is deprecated. It pads structures to multiple of 4 bytes, which is incompatible with the SH ABI.
-mspace
Optimize for space instead of speed. Implied by -Os.
-mprefergot
When generating position-independent code, emit function calls using the Global Offset Table instead of the Procedure Linkage Table.
-musermode
Generate a library function call to invalidate instruction cache entries, after fixing up a trampoline. This library function call doesn't assume it can write to the whole memory address space. This is the default when the target is sh-*-linux*.


Using the GNU Compiler Collection (GCC)

Node:Simple Constraints, Next:Multi-Alternative, Up:Constraints

Simple Constraints

The simplest kind of constraint is a string full of letters, each of which describes one kind of operand that is permitted. Here are the letters that are allowed:

whitespace
Whitespace characters are ignored and can be inserted at any position except the first. This enables each alternative for different operands to be visually aligned in the machine description even if they have different number of constraints and modifiers.
m
A memory operand is allowed, with any kind of address that the machine supports in general.
o
A memory operand is allowed, but only if the address is offsettable. This means that adding a small integer (actually, the width in bytes of the operand, as determined by its machine mode) may be added to the address and the result is also a valid memory address.

For example, an address which is constant is offsettable; so is an address that is the sum of a register and a constant (as long as a slightly larger constant is also within the range of address-offsets supported by the machine); but an autoincrement or autodecrement address is not offsettable. More complicated indirect/indexed addresses may or may not be offsettable depending on the other addressing modes that the machine supports.

Note that in an output operand which can be matched by another operand, the constraint letter o is valid only when accompanied by both < (if the target machine has predecrement addressing) and > (if the target machine has preincrement addressing).

V
A memory operand that is not offsettable. In other words, anything that would fit the m constraint but not the o constraint.
<
A memory operand with autodecrement addressing (either predecrement or postdecrement) is allowed.
>
A memory operand with autoincrement addressing (either preincrement or postincrement) is allowed.
r
A register operand is allowed provided that it is in a general register.
i
An immediate integer operand (one with constant value) is allowed. This includes symbolic constants whose values will be known only at assembly time.
n
An immediate integer operand with a known numeric value is allowed. Many systems cannot support assembly-time constants for operands less than a word wide. Constraints for these operands should use n rather than i.
I, J, K, ... P
Other letters in the range I through P may be defined in a machine-dependent fashion to permit immediate integer operands with explicit integer values in specified ranges. For example, on the 68000, I is defined to stand for the range of values 1 to 8. This is the range permitted as a shift count in the shift instructions.
E
An immediate floating operand (expression code const_double) is allowed, but only if the target floating point format is the same as that of the host machine (on which the compiler is running).
F
An immediate floating operand (expression code const_double) is allowed.
G, H
G and H may be defined in a machine-dependent fashion to permit immediate floating operands in particular ranges of values.
s
An immediate integer operand whose value is not an explicit integer is allowed.

This might appear strange; if an insn allows a constant operand with a value not known at compile time, it certainly must allow any known value. So why use s instead of i? Sometimes it allows better code to be generated.

For example, on the 68000 in a fullword instruction it is possible to use an immediate operand; but if the immediate value is between -128 and 127, better code results from loading the value into a register and using the register. This is because the load into the register can be done with a moveq instruction. We arrange for this to happen by defining the letter K to mean "any integer outside the range -128 to 127", and then specifying Ks in the operand constraints.

g
Any register, memory or immediate integer operand is allowed, except for registers that are not general registers.
X
Any operand whatsoever is allowed.
0, 1, 2, ... 9
An operand that matches the specified operand number is allowed. If a digit is used together with letters within the same alternative, the digit should come last.

This number is allowed to be more than a single digit. If multiple digits are encountered consecutavely, they are interpreted as a single decimal integer. There is scant chance for ambiguity, since to-date it has never been desirable that 10 be interpreted as matching either operand 1 or operand 0. Should this be desired, one can use multiple alternatives instead.

This is called a matching constraint and what it really means is that the assembler has only a single operand that fills two roles which asm distinguishes. For example, an add instruction uses two input operands and an output operand, but on most CISC machines an add instruction really has only two operands, one of them an input-output operand:

addl #35,r12

Matching constraints are used in these circumstances. More precisely, the two operands that match must include one input-only operand and one output-only operand. Moreover, the digit must be a smaller number than the number of the operand that uses it in the constraint.

p
An operand that is a valid memory address is allowed. This is for "load address" and "push address" instructions.

p in the constraint must be accompanied by address_operand as the predicate in the match_operand. This predicate interprets the mode specified in the match_operand as the mode of the memory reference for which the address would be valid.

other-letters
Other letters can be defined in machine-dependent fashion to stand for particular classes of registers or other arbitrary operand types. d, a and f are defined on the 68000/68020 to stand for data, address and floating point registers.


Using the GNU Compiler Collection (GCC)

Node:Solaris Pragmas, Next:Tru64 Pragmas, Previous:Darwin Pragmas, Up:Pragmas

Solaris Pragmas

For compatibility with the SunPRO compiler, the following pragma is supported.

redefine_extname oldname newname

This pragma gives the C function oldname the assembler label newname. The pragma must appear before the function declaration. This pragma is equivalent to the asm labels extension (see Asm Labels). The preprocessor defines __PRAGMA_REDEFINE_EXTNAME if the pragma is available.


Using the GNU Compiler Collection (GCC)

Node:SPARC Options, Next:Convex Options, Previous:VAX Options, Up:Submodel Options

SPARC Options

These -m switches are supported on the SPARC:

-mno-app-regs
-mapp-regs
Specify -mapp-regs to generate output using the global registers 2 through 4, which the SPARC SVR4 ABI reserves for applications. This is the default.

To be fully SVR4 ABI compliant at the cost of some performance loss, specify -mno-app-regs. You should compile libraries and system software with this option.

-mfpu
-mhard-float
Generate output containing floating point instructions. This is the default.
-mno-fpu
-msoft-float
Generate output containing library calls for floating point. Warning: the requisite libraries are not available for all SPARC targets. Normally the facilities of the machine's usual C compiler are used, but this cannot be done directly in cross-compilation. You must make your own arrangements to provide suitable library functions for cross-compilation. The embedded targets sparc-*-aout and sparclite-*-* do provide software floating point support.

-msoft-float changes the calling convention in the output file; therefore, it is only useful if you compile all of a program with this option. In particular, you need to compile libgcc.a, the library that comes with GCC, with -msoft-float in order for this to work.

-mhard-quad-float
Generate output containing quad-word (long double) floating point instructions.
-msoft-quad-float
Generate output containing library calls for quad-word (long double) floating point instructions. The functions called are those specified in the SPARC ABI. This is the default.

As of this writing, there are no sparc implementations that have hardware support for the quad-word floating point instructions. They all invoke a trap handler for one of these instructions, and then the trap handler emulates the effect of the instruction. Because of the trap handler overhead, this is much slower than calling the ABI library routines. Thus the -msoft-quad-float option is the default.

-mno-flat
-mflat
With -mflat, the compiler does not generate save/restore instructions and will use a "flat" or single register window calling convention. This model uses %i7 as the frame pointer and is compatible with the normal register window model. Code from either may be intermixed. The local registers and the input registers (0-5) are still treated as "call saved" registers and will be saved on the stack as necessary.

With -mno-flat (the default), the compiler emits save/restore instructions (except for leaf functions) and is the normal mode of operation.

-mno-unaligned-doubles
-munaligned-doubles
Assume that doubles have 8 byte alignment. This is the default.

With -munaligned-doubles, GCC assumes that doubles have 8 byte alignment only if they are contained in another type, or if they have an absolute address. Otherwise, it assumes they have 4 byte alignment. Specifying this option avoids some rare compatibility problems with code generated by other compilers. It is not the default because it results in a performance loss, especially for floating point code.

-mno-faster-structs
-mfaster-structs
With -mfaster-structs, the compiler assumes that structures should have 8 byte alignment. This enables the use of pairs of ldd and std instructions for copies in structure assignment, in place of twice as many ld and st pairs. However, the use of this changed alignment directly violates the Sparc ABI. Thus, it's intended only for use on targets where the developer acknowledges that their resulting code will not be directly in line with the rules of the ABI.
-mv8
-msparclite
These two options select variations on the SPARC architecture.

By default (unless specifically configured for the Fujitsu SPARClite), GCC generates code for the v7 variant of the SPARC architecture.

-mv8 will give you SPARC v8 code. The only difference from v7 code is that the compiler emits the integer multiply and integer divide instructions which exist in SPARC v8 but not in SPARC v7.

-msparclite will give you SPARClite code. This adds the integer multiply, integer divide step and scan (ffs) instructions which exist in SPARClite but not in SPARC v7.

These options are deprecated and will be deleted in a future GCC release. They have been replaced with -mcpu=xxx.

-mcypress
-msupersparc
These two options select the processor for which the code is optimized.

With -mcypress (the default), the compiler optimizes code for the Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series. This is also appropriate for the older SparcStation 1, 2, IPX etc.

With -msupersparc the compiler optimizes code for the SuperSparc cpu, as used in the SparcStation 10, 1000 and 2000 series. This flag also enables use of the full SPARC v8 instruction set.

These options are deprecated and will be deleted in a future GCC release. They have been replaced with -mcpu=xxx.

-mcpu=cpu_type
Set the instruction set, register set, and instruction scheduling parameters for machine type cpu_type. Supported values for cpu_type are v7, cypress, v8, supersparc, sparclite, hypersparc, sparclite86x, f930, f934, sparclet, tsc701, v9, and ultrasparc.

Default instruction scheduling parameters are used for values that select an architecture and not an implementation. These are v7, v8, sparclite, sparclet, v9.

Here is a list of each supported architecture and their supported implementations.

    v7:             cypress
    v8:             supersparc, hypersparc
    sparclite:      f930, f934, sparclite86x
    sparclet:       tsc701
    v9:             ultrasparc

-mtune=cpu_type
Set the instruction scheduling parameters for machine type cpu_type, but do not set the instruction set or register set that the option -mcpu=cpu_type would.

The same values for -mcpu=cpu_type can be used for -mtune=cpu_type, but the only useful values are those that select a particular cpu implementation. Those are cypress, supersparc, hypersparc, f930, f934, sparclite86x, tsc701, and ultrasparc.

These -m switches are supported in addition to the above on the SPARCLET processor.

-mlittle-endian
Generate code for a processor running in little-endian mode.
-mlive-g0
Treat register %g0 as a normal register. GCC will continue to clobber it as necessary but will not assume it always reads as 0.
-mbroken-saverestore
Generate code that does not use non-trivial forms of the save and restore instructions. Early versions of the SPARCLET processor do not correctly handle save and restore instructions used with arguments. They correctly handle them used without arguments. A save instruction used without arguments increments the current window pointer but does not allocate a new stack frame. It is assumed that the window overflow trap handler will properly handle this case as will interrupt handlers.

These -m switches are supported in addition to the above on SPARC V9 processors in 64-bit environments.

-mlittle-endian
Generate code for a processor running in little-endian mode.
-m32
-m64
Generate code for a 32-bit or 64-bit environment. The 32-bit environment sets int, long and pointer to 32 bits. The 64-bit environment sets int to 32 bits and long and pointer to 64 bits.
-mcmodel=medlow
Generate code for the Medium/Low code model: the program must be linked in the low 32 bits of the address space. Pointers are 64 bits. Programs can be statically or dynamically linked.
-mcmodel=medmid
Generate code for the Medium/Middle code model: the program must be linked in the low 44 bits of the address space, the text segment must be less than 2G bytes, and data segment must be within 2G of the text segment. Pointers are 64 bits.
-mcmodel=medany
Generate code for the Medium/Anywhere code model: the program may be linked anywhere in the address space, the text segment must be less than 2G bytes, and data segment must be within 2G of the text segment. Pointers are 64 bits.
-mcmodel=embmedany
Generate code for the Medium/Anywhere code model for embedded systems: assume a 32-bit text and a 32-bit data segment, both starting anywhere (determined at link time). Register %g4 points to the base of the data segment. Pointers are still 64 bits. Programs are statically linked, PIC is not supported.
-mstack-bias
-mno-stack-bias
With -mstack-bias, GCC assumes that the stack pointer, and frame pointer if present, are offset by -2047 which must be added back when making stack frame references. Otherwise, assume no such offset is present.


Using the GNU Compiler Collection (GCC)

Node:Spec Files, Next:Target Options, Previous:Directory Options, Up:Invoking GCC

Specifying subprocesses and the switches to pass to them

gcc is a driver program. It performs its job by invoking a sequence of other programs to do the work of compiling, assembling and linking. GCC interprets its command-line parameters and uses these to deduce which programs it should invoke, and which command-line options it ought to place on their command lines. This behavior is controlled by spec strings. In most cases there is one spec string for each program that GCC can invoke, but a few programs have multiple spec strings to control their behavior. The spec strings built into GCC can be overridden by using the -specs= command-line switch to specify a spec file.

Spec files are plaintext files that are used to construct spec strings. They consist of a sequence of directives separated by blank lines. The type of directive is determined by the first non-whitespace character on the line and it can be one of the following:

%command
Issues a command to the spec file processor. The commands that can appear here are:
%include <file>
Search for file and insert its text at the current point in the specs file.
%include_noerr <file>
Just like %include, but do not generate an error message if the include file cannot be found.
%rename old_name new_name
Rename the spec string old_name to new_name.

*[spec_name]:
This tells the compiler to create, override or delete the named spec string. All lines after this directive up to the next directive or blank line are considered to be the text for the spec string. If this results in an empty string then the spec will be deleted. (Or, if the spec did not exist, then nothing will happened.) Otherwise, if the spec does not currently exist a new spec will be created. If the spec does exist then its contents will be overridden by the text of this directive, unless the first character of that text is the + character, in which case the text will be appended to the spec.
[suffix]:
Creates a new [suffix] spec pair. All lines after this directive and up to the next directive or blank line are considered to make up the spec string for the indicated suffix. When the compiler encounters an input file with the named suffix, it will processes the spec string in order to work out how to compile that file. For example:
.ZZ:
z-compile -input %i

This says that any input file whose name ends in .ZZ should be passed to the program z-compile, which should be invoked with the command-line switch -input and with the result of performing the %i substitution. (See below.)

As an alternative to providing a spec string, the text that follows a suffix directive can be one of the following:

@language
This says that the suffix is an alias for a known language. This is similar to using the -x command-line switch to GCC to specify a language explicitly. For example:
.ZZ:
@c++

Says that .ZZ files are, in fact, C++ source files.

#name
This causes an error messages saying:
name compiler not installed on this system.

GCC already has an extensive list of suffixes built into it. This directive will add an entry to the end of the list of suffixes, but since the list is searched from the end backwards, it is effectively possible to override earlier entries using this technique.

GCC has the following spec strings built into it. Spec files can override these strings or create their own. Note that individual targets can also add their own spec strings to this list.

asm          Options to pass to the assembler
asm_final    Options to pass to the assembler post-processor
cpp          Options to pass to the C preprocessor
cc1          Options to pass to the C compiler
cc1plus      Options to pass to the C++ compiler
endfile      Object files to include at the end of the link
link         Options to pass to the linker
lib          Libraries to include on the command line to the linker
libgcc       Decides which GCC support library to pass to the linker
linker       Sets the name of the linker
predefines   Defines to be passed to the C preprocessor
signed_char  Defines to pass to CPP to say whether char is signed
             by default
startfile    Object files to include at the start of the link

Here is a small example of a spec file:

%rename lib                 old_lib

*lib:
--start-group -lgcc -lc -leval1 --end-group %(old_lib)

This example renames the spec called lib to old_lib and then overrides the previous definition of lib with a new one. The new definition adds in some extra command-line options before including the text of the old definition.

Spec strings are a list of command-line options to be passed to their corresponding program. In addition, the spec strings can contain %-prefixed sequences to substitute variable text or to conditionally insert text into the command line. Using these constructs it is possible to generate quite complex command lines.

Here is a table of all defined %-sequences for spec strings. Note that spaces are not generated automatically around the results of expanding these sequences. Therefore you can concatenate them together or combine them with constant text in a single argument.

%%
Substitute one % into the program name or argument.
%i
Substitute the name of the input file being processed.
%b
Substitute the basename of the input file being processed. This is the substring up to (and not including) the last period and not including the directory.
%B
This is the same as %b, but include the file suffix (text after the last period).
%d
Marks the argument containing or following the %d as a temporary file name, so that that file will be deleted if GCC exits successfully. Unlike %g, this contributes no text to the argument.
%gsuffix
Substitute a file name that has suffix suffix and is chosen once per compilation, and mark the argument in the same way as %d. To reduce exposure to denial-of-service attacks, the file name is now chosen in a way that is hard to predict even when previously chosen file names are known. For example, %g.s ... %g.o ... %g.s might turn into ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s. suffix matches the regexp [.A-Za-z]* or the special string %O, which is treated exactly as if %O had been preprocessed. Previously, %g was simply substituted with a file name chosen once per compilation, without regard to any appended suffix (which was therefore treated just like ordinary text), making such attacks more likely to succeed.
%usuffix
Like %g, but generates a new temporary file name even if %usuffix was already seen.
%Usuffix
Substitutes the last file name generated with %usuffix, generating a new one if there is no such last file name. In the absence of any %usuffix, this is just like %gsuffix, except they don't share the same suffix space, so %g.s ... %U.s ... %g.s ... %U.s would involve the generation of two distinct file names, one for each %g.s and another for each %U.s. Previously, %U was simply substituted with a file name chosen for the previous %u, without regard to any appended suffix.
%jSUFFIX
Substitutes the name of the HOST_BIT_BUCKET, if any, and if it is writable, and if save-temps is off; otherwise, substitute the name of a temporary file, just like %u. This temporary file is not meant for communication between processes, but rather as a junk disposal mechanism.
%.SUFFIX
Substitutes .SUFFIX for the suffixes of a matched switch's args when it is subsequently output with %*. SUFFIX is terminated by the next space or %.
%w
Marks the argument containing or following the %w as the designated output file of this compilation. This puts the argument into the sequence of arguments that %o will substitute later.
%o
Substitutes the names of all the output files, with spaces automatically placed around them. You should write spaces around the %o as well or the results are undefined. %o is for use in the specs for running the linker. Input files whose names have no recognized suffix are not compiled at all, but they are included among the output files, so they will be linked.
%O
Substitutes the suffix for object files. Note that this is handled specially when it immediately follows %g, %u, or %U, because of the need for those to form complete file names. The handling is such that %O is treated exactly as if it had already been substituted, except that %g, %u, and %U do not currently support additional suffix characters following %O as they would following, for example, .o.
%p
Substitutes the standard macro predefinitions for the current target machine. Use this when running cpp.
%P
Like %p, but puts __ before and after the name of each predefined macro, except for macros that start with __ or with _L, where L is an uppercase letter. This is for ISO C.
%I
Substitute a -iprefix option made from GCC_EXEC_PREFIX.
%s
Current argument is the name of a library or startup file of some sort. Search for that file in a standard list of directories and substitute the full name found.
%estr
Print str as an error message. str is terminated by a newline. Use this when inconsistent options are detected.
%|
Output - if the input for the current command is coming from a pipe.
%(name)
Substitute the contents of spec string name at this point.
%[name]
Like %(...) but put __ around -D arguments.
%x{option}
Accumulate an option for %X.
%X
Output the accumulated linker options specified by -Wl or a %x spec string.
%Y
Output the accumulated assembler options specified by -Wa.
%Z
Output the accumulated preprocessor options specified by -Wp.
%v1
Substitute the major version number of GCC. (For version 2.9.5, this is 2.)
%v2
Substitute the minor version number of GCC. (For version 2.9.5, this is 9.)
%v3
Substitute the patch level number of GCC. (For version 2.9.5, this is 5.)
%a
Process the asm spec. This is used to compute the switches to be passed to the assembler.
%A
Process the asm_final spec. This is a spec string for passing switches to an assembler post-processor, if such a program is needed.
%l
Process the link spec. This is the spec for computing the command line passed to the linker. Typically it will make use of the %L %G %S %D and %E sequences.
%D
Dump out a -L option for each directory that GCC believes might contain startup files. If the target supports multilibs then the current multilib directory will be prepended to each of these paths.
%M
Output the multilib directory with directory separators replaced with _. If multilib directories are not set, or the multilib directory is . then this option emits nothing.
%L
Process the lib spec. This is a spec string for deciding which libraries should be included on the command line to the linker.
%G
Process the libgcc spec. This is a spec string for deciding which GCC support library should be included on the command line to the linker.
%S
Process the startfile spec. This is a spec for deciding which object files should be the first ones passed to the linker. Typically this might be a file named crt0.o.
%E
Process the endfile spec. This is a spec string that specifies the last object files that will be passed to the linker.
%C
Process the cpp spec. This is used to construct the arguments to be passed to the C preprocessor.
%c
Process the signed_char spec. This is intended to be used to tell cpp whether a char is signed. It typically has the definition:
%{funsigned-char:-D__CHAR_UNSIGNED__}

%1
Process the cc1 spec. This is used to construct the options to be passed to the actual C compiler (cc1).
%2
Process the cc1plus spec. This is used to construct the options to be passed to the actual C++ compiler (cc1plus).
%*
Substitute the variable part of a matched option. See below. Note that each comma in the substituted string is replaced by a single space.
%{S}
Substitutes the -S switch, if that switch was given to GCC. If that switch was not specified, this substitutes nothing. Note that the leading dash is omitted when specifying this option, and it is automatically inserted if the substitution is performed. Thus the spec string %{foo} would match the command-line option -foo and would output the command line option -foo.
%W{S}
Like %{S} but mark last argument supplied within as a file to be deleted on failure.
%{S*}
Substitutes all the switches specified to GCC whose names start with -S, but which also take an argument. This is used for switches like -o, -D, -I, etc. GCC considers -o foo as being one switch whose names starts with o. %{o*} would substitute this text, including the space. Thus two arguments would be generated.
%{^S*}
Like %{S*}, but don't put a blank between a switch and its argument. Thus %{^o*} would only generate one argument, not two.
%{S*&T*}
Like %{S*}, but preserve order of S and T options (the order of S and T in the spec is not significant). There can be any number of ampersand-separated variables; for each the wild card is optional. Useful for CPP as %{D*&U*&A*}.
%{<S}
Remove all occurrences of -S from the command line. Note--this command is position dependent. % commands in the spec string before this option will see -S, % commands in the spec string after this option will not.
%{S*:X}
Substitutes X if one or more switches whose names start with -S are specified to GCC. Note that the tail part of the -S option (i.e. the part matched by the *) will be substituted for each occurrence of %* within X.
%{S:X}
Substitutes X, but only if the -S switch was given to GCC.
%{!S:X}
Substitutes X, but only if the -S switch was not given to GCC.
%{|S:X}
Like %{S:X}, but if no S switch, substitute -.
%{|!S:X}
Like %{!S:X}, but if there is an S switch, substitute -.
%{.S:X}
Substitutes X, but only if processing a file with suffix S.
%{!.S:X}
Substitutes X, but only if not processing a file with suffix S.
%{S|P:X}
Substitutes X if either -S or -P was given to GCC. This may be combined with ! and . sequences as well, although they have a stronger binding than the |. For example a spec string like this:
%{.c:-foo} %{!.c:-bar} %{.c|d:-baz} %{!.c|d:-boggle}

will output the following command-line options from the following input command-line options:

fred.c        -foo -baz
jim.d         -bar -boggle
-d fred.c     -foo -baz -boggle
-d jim.d      -bar -baz -boggle

The conditional text X in a %{S:X} or %{!S:X} construct may contain other nested % constructs or spaces, or even newlines. They are processed as usual, as described above.

The -O, -f, -m, and -W switches are handled specifically in these constructs. If another value of -O or the negated form of a -f, -m, or -W switch is found later in the command line, the earlier switch value is ignored, except with {S*} where S is just one letter, which passes all matching options.

The character | at the beginning of the predicate text is used to indicate that a command should be piped to the following command, but only if -pipe is specified.

It is built into GCC which switches take arguments and which do not. (You might think it would be useful to generalize this to allow each compiler's spec to say which switches take arguments. But this cannot be done in a consistent fashion. GCC cannot even decide which input files have been specified without knowing which switches take arguments, and it must know which input files to compile in order to tell which compilers to run).

GCC also knows implicitly that arguments starting in -l are to be treated as compiler output files, and passed to the linker in their proper position among the other output files.


Using the GNU Compiler Collection (GCC)

Node:Standard Libraries, Next:Disappointments, Previous:Fixed Headers, Up:Trouble

Standard Libraries

GCC by itself attempts to be a conforming freestanding implementation. See Language Standards Supported by GCC, for details of what this means. Beyond the library facilities required of such an implementation, the rest of the C library is supplied by the vendor of the operating system. If that C library doesn't conform to the C standards, then your programs might get warnings (especially when using -Wall) that you don't expect.

For example, the sprintf function on SunOS 4.1.3 returns char * while the C standard says that sprintf returns an int. The fixincludes program could make the prototype for this function match the Standard, but that would be wrong, since the function will still return char *.

If you need a Standard compliant library, then you need to find one, as GCC does not provide one. The GNU C library (called glibc) provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for GNU/Linux and HURD-based GNU systems; no recent version of it supports other systems, though some very old versions did. Version 2.2 of the GNU C library includes nearly complete C99 support. You could also ask your operating system vendor if newer libraries are available.


Using the GNU Compiler Collection (GCC)

Node:Standards, Next:Invoking GCC, Previous:G++ and GCC, Up:Top

Language Standards Supported by GCC

For each language compiled by GCC for which there is a standard, GCC attempts to follow one or more versions of that standard, possibly with some exceptions, and possibly with some extensions.

GCC supports three versions of the C standard, although support for the most recent version is not yet complete.

The original ANSI C standard (X3.159-1989) was ratified in 1989 and published in 1990. This standard was ratified as an ISO standard (ISO/IEC 9899:1990) later in 1990. There were no technical differences between these publications, although the sections of the ANSI standard were renumbered and became clauses in the ISO standard. This standard, in both its forms, is commonly known as C89, or occasionally as C90, from the dates of ratification. The ANSI standard, but not the ISO standard, also came with a Rationale document. To select this standard in GCC, use one of the options -ansi, -std=c89 or -std=iso9899:1990; to obtain all the diagnostics required by the standard, you should also specify -pedantic (or -pedantic-errors if you want them to be errors rather than warnings). See Options Controlling C Dialect.

Errors in the 1990 ISO C standard were corrected in two Technical Corrigenda published in 1994 and 1996. GCC does not support the uncorrected version.

An amendment to the 1990 standard was published in 1995. This amendment added digraphs and __STDC_VERSION__ to the language, but otherwise concerned the library. This amendment is commonly known as AMD1; the amended standard is sometimes known as C94 or C95. To select this standard in GCC, use the option -std=iso9899:199409 (with, as for other standard versions, -pedantic to receive all required diagnostics).

A new edition of the ISO C standard was published in 1999 as ISO/IEC 9899:1999, and is commonly known as C99. GCC has incomplete support for this standard version; see http://gcc.gnu.org/gcc-3.1/c99status.html for details. To select this standard, use -std=c99 or -std=iso9899:1999. (While in development, drafts of this standard version were referred to as C9X.)

Errors in the 1999 ISO C standard were corrected in a Technical Corrigendum published in 2001. GCC does not support the uncorrected version.

GCC also has some limited support for traditional (pre-ISO) C with the -traditional option. This support may be of use for compiling some very old programs that have not been updated to ISO C, but should not be used for new programs. It will not work with some modern C libraries such as the GNU C library.

By default, GCC provides some extensions to the C language that on rare occasions conflict with the C standard. See Extensions to the C Language Family. Use of the -std options listed above will disable these extensions where they conflict with the C standard version selected. You may also select an extended version of the C language explicitly with -std=gnu89 (for C89 with GNU extensions) or -std=gnu99 (for C99 with GNU extensions). The default, if no C language dialect options are given, is -std=gnu89; this will change to -std=gnu99 in some future release when the C99 support is complete. Some features that are part of the C99 standard are accepted as extensions in C89 mode.

The ISO C standard defines (in clause 4) two classes of conforming implementation. A conforming hosted implementation supports the whole standard including all the library facilities; a conforming freestanding implementation is only required to provide certain library facilities: those in <float.h>, <limits.h>, <stdarg.h>, and <stddef.h>; since AMD1, also those in <iso646.h>; and in C99, also those in <stdbool.h> and <stdint.h>. In addition, complex types, added in C99, are not required for freestanding implementations. The standard also defines two environments for programs, a freestanding environment, required of all implementations and which may not have library facilities beyond those required of freestanding implementations, where the handling of program startup and termination are implementation-defined, and a hosted environment, which is not required, in which all the library facilities are provided and startup is through a function int main (void) or int main (int, char *[]). An OS kernel would be a freestanding environment; a program using the facilities of an operating system would normally be in a hosted implementation.

GCC aims towards being usable as a conforming freestanding implementation, or as the compiler for a conforming hosted implementation. By default, it will act as the compiler for a hosted implementation, defining __STDC_HOSTED__ as 1 and presuming that when the names of ISO C functions are used, they have the semantics defined in the standard. To make it act as a conforming freestanding implementation for a freestanding environment, use the option -ffreestanding; it will then define __STDC_HOSTED__ to 0 and not make assumptions about the meanings of function names from the standard library, with exceptions noted below. To build an OS kernel, you may well still need to make your own arrangements for linking and startup. See Options Controlling C Dialect.

GCC does not provide the library facilities required only of hosted implementations, nor yet all the facilities required by C99 of freestanding implementations; to use the facilities of a hosted environment, you will need to find them elsewhere (for example, in the GNU C library). See Standard Libraries.

Most of the compiler support routines used by GCC are present in libgcc, but there are a few exceptions. GCC requires the freestanding environment provide memcpy, memmove, memset and memcmp. Some older ports of GCC are configured to use the BSD bcopy, bzero and bcmp functions instead, but this is deprecated for new ports. Finally, if __builtin_trap is used, and the target does not implement the trap pattern, then GCC will emit a call to abort.

For references to Technical Corrigenda, Rationale documents and information concerning the history of C that is available online, see http://gcc.gnu.org/readings.html

There is no formal written standard for Objective-C. The most authoritative manual is "Object-Oriented Programming and the Objective-C Language", available at a number of web sites; http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/ has a recent version, while http://www.toodarkpark.org/computers/objc/ is an older example. http://www.gnustep.org includes useful information as well.

See GNAT Reference Manual, for information on standard conformance and compatibility of the Ada compiler.

See The GNU Fortran Language, for details of the Fortran language supported by GCC.

See Compatibility with the Java Platform, for details of compatibility between gcj and the Java Platform.


Using the GNU Compiler Collection (GCC)

Node:Statement Exprs, Next:Local Labels, Up:C Extensions

Statements and Declarations in Expressions

A compound statement enclosed in parentheses may appear as an expression in GNU C. This allows you to use loops, switches, and local variables within an expression.

Recall that a compound statement is a sequence of statements surrounded by braces; in this construct, parentheses go around the braces. For example:

({ int y = foo (); int z;
   if (y > 0) z = y;
   else z = - y;
   z; })

is a valid (though slightly more complex than necessary) expression for the absolute value of foo ().

The last thing in the compound statement should be an expression followed by a semicolon; the value of this subexpression serves as the value of the entire construct. (If you use some other kind of statement last within the braces, the construct has type void, and thus effectively no value.)

This feature is especially useful in making macro definitions "safe" (so that they evaluate each operand exactly once). For example, the "maximum" function is commonly defined as a macro in standard C as follows:

#define max(a,b) ((a) > (b) ? (a) : (b))

But this definition computes either a or b twice, with bad results if the operand has side effects. In GNU C, if you know the type of the operands (here let's assume int), you can define the macro safely as follows:

#define maxint(a,b) \
  ({int _a = (a), _b = (b); _a > _b ? _a : _b; })

Embedded statements are not allowed in constant expressions, such as the value of an enumeration constant, the width of a bit-field, or the initial value of a static variable.

If you don't know the type of the operand, you can still do this, but you must use typeof (see Typeof) or type naming (see Naming Types).

Statement expressions are not supported fully in G++, and their fate there is unclear. (It is possible that they will become fully supported at some point, or that they will be deprecated, or that the bugs that are present will continue to exist indefinitely.) Presently, statement expressions do not work well as default arguments.

In addition, there are semantic issues with statement-expressions in C++. If you try to use statement-expressions instead of inline functions in C++, you may be surprised at the way object destruction is handled. For example:

#define foo(a)  ({int b = (a); b + 3; })

does not work the same way as:

inline int foo(int a) { int b = a; return b + 3; }

In particular, if the expression passed into foo involves the creation of temporaries, the destructors for those temporaries will be run earlier in the case of the macro than in the case of the function.

These considerations mean that it is probably a bad idea to use statement-expressions of this form in header files that are designed to work with C++. (Note that some versions of the GNU C Library contained header files using statement-expression that lead to precisely this bug.)


Using the GNU Compiler Collection (GCC)

Node:Static Definitions, Next:Temporaries, Up:C++ Misunderstandings

Declare and Define Static Members

When a class has static data members, it is not enough to declare the static member; you must also define it. For example:

class Foo
{
  ...
  void method();
  static int bar;
};

This declaration only establishes that the class Foo has an int named Foo::bar, and a member function named Foo::method. But you still need to define both method and bar elsewhere. According to the ISO standard, you must supply an initializer in one (and only one) source file, such as:

int Foo::bar = 0;

Other C++ compilers may not correctly implement the standard behavior. As a result, when you switch to g++ from one of these compilers, you may discover that a program that appeared to work correctly in fact does not conform to the standard: g++ reports as undefined symbols any static data members that lack definitions.


Using the GNU Compiler Collection (GCC)

Node:Structures unions enumerations and bit-fields implementation, Next:Qualifiers implementation, Previous:Hints implementation, Up:C Implementation

Structures, unions, enumerations, and bit-fields

  • Whether a "plain" int bit-field is treated as a signed int bit-field or as an unsigned int bit-field (6.7.2, 6.7.2.1).
  • Allowable bit-field types other than _Bool, signed int, and unsigned int (6.7.2.1).
  • Whether a bit-field can straddle a storage-unit boundary (6.7.2.1).
  • The order of allocation of bit-fields within a unit (6.7.2.1).
  • The alignment of non-bit-field members of structures (6.7.2.1).
  • The integer type compatible with each enumerated type (6.7.2.2).


Using the GNU Compiler Collection (GCC)

Node:Submodel Options, Next:Code Gen Options, Previous:Target Options, Up:Invoking GCC

Hardware Models and Configurations

Earlier we discussed the standard option -b which chooses among different installed compilers for completely different target machines, such as VAX vs. 68000 vs. 80386.

In addition, each of these target machine types can have its own special options, starting with -m, to choose among various hardware models or configurations--for example, 68010 vs 68020, floating coprocessor or none. A single installed version of the compiler can compile for any model or configuration, according to the options specified.

Some configurations of the compiler also support additional special options, usually for compatibility with other compilers on the same platform.

These options are defined by the macro TARGET_SWITCHES in the machine description. The default for the options is also defined by that macro, which enables you to change the defaults.

  • M680x0 Options:
  • M68hc1x Options:
  • VAX Options:
  • SPARC Options:
  • Convex Options:
  • AMD29K Options:
  • ARM Options:
  • MN10200 Options:
  • MN10300 Options:
  • M32R/D Options:
  • M88K Options:
  • RS/6000 and PowerPC Options:
  • RT Options:
  • MIPS Options:
  • i386 and x86-64 Options:
  • HPPA Options:
  • Intel 960 Options:
  • DEC Alpha Options:
  • DEC Alpha/VMS Options:
  • Clipper Options:
  • H8/300 Options:
  • SH Options:
  • System V Options:
  • TMS320C3x/C4x Options:
  • V850 Options:
  • ARC Options:
  • NS32K Options:
  • AVR Options:
  • MCore Options:
  • IA-64 Options:
  • D30V Options:
  • S/390 and zSeries Options:
  • CRIS Options:
  • MMIX Options:
  • PDP-11 Options:
  • Xstormy16 Options:
  • Xtensa Options:


Using the GNU Compiler Collection (GCC)

Node:Subscripting, Next:Pointer Arith, Previous:Multi-line Strings, Up:C Extensions

Non-Lvalue Arrays May Have Subscripts

In ISO C99, arrays that are not lvalues still decay to pointers, and may be subscripted, although they may not be modified or used after the next sequence point and the unary & operator may not be applied to them. As an extension, GCC allows such arrays to be subscripted in C89 mode, though otherwise they do not decay to pointers outside C99 mode. For example, this is valid in GNU C though not valid in C89:

struct foo {int a[4];};

struct foo f();

bar (int index)
{
  return f().a[index];
}


Using the GNU Compiler Collection (GCC)

Node:System V Options, Next:TMS320C3x/C4x Options, Previous:SH Options, Up:Submodel Options

Options for System V

These additional options are available on System V Release 4 for compatibility with other compilers on those systems:

-G
Create a shared object. It is recommended that -symbolic or -shared be used instead.
-Qy
Identify the versions of each tool used by the compiler, in a .ident assembler directive in the output.
-Qn
Refrain from adding .ident directives to the output file (this is the default).
-YP,dirs
Search the directories dirs, and no others, for libraries specified with -l.
-Ym,dir
Look in the directory dir to find the M4 preprocessor. The assembler uses this option.


Using the GNU Compiler Collection (GCC)

Node:Target Builtins, Next:Pragmas, Previous:Other Builtins, Up:C Extensions

Built-in Functions Specific to Particular Target Machines

On some target machines, GCC supports many built-in functions specific to those machines. Generally these generate calls to specific machine instructions, but allow the compiler to schedule those calls.

  • X86 Built-in Functions:
  • PowerPC AltiVec Built-in Functions:


Using the GNU Compiler Collection (GCC)

Node:Target Options, Next:Submodel Options, Previous:Spec Files, Up:Invoking GCC

Specifying Target Machine and Compiler Version

By default, GCC compiles code for the same type of machine that you are using. However, it can also be installed as a cross-compiler, to compile for some other type of machine. In fact, several different configurations of GCC, for different target machines, can be installed side by side. Then you specify which one to use with the -b option.

In addition, older and newer versions of GCC can be installed side by side. One of them (probably the newest) will be the default, but you may sometimes wish to use another.

-b machine
The argument machine specifies the target machine for compilation. This is useful when you have installed GCC as a cross-compiler.

The value to use for machine is the same as was specified as the machine type when configuring GCC as a cross-compiler. For example, if a cross-compiler was configured with configure i386v, meaning to compile for an 80386 running System V, then you would specify -b i386v to run that cross compiler.

When you do not specify -b, it normally means to compile for the same type of machine that you are using.

-V version
The argument version specifies which version of GCC to run. This is useful when multiple versions are installed. For example, version might be 2.0, meaning to run GCC version 2.0.

The default version, when you do not specify -V, is the last version of GCC that you installed.

The -b and -V options actually work by controlling part of the file name used for the executable files and libraries used for compilation. A given version of GCC, for a given target machine, is normally kept in the directory /usr/local/lib/gcc-lib/machine/version.

Thus, sites can customize the effect of -b or -V either by changing the names of these directories or adding alternate names (or symbolic links). If in directory /usr/local/lib/gcc-lib/ the file 80386 is a link to the file i386v, then -b 80386 becomes an alias for -b i386v.

In one respect, the -b or -V do not completely change to a different compiler: the top-level driver program gcc that you originally invoked continues to run and invoke the other executables (preprocessor, compiler per se, assembler and linker) that do the real work. However, since no real work is done in the driver program, it usually does not matter that the driver program in use is not the one for the specified target. It is common for the interface to the other executables to change incompatibly between compiler versions, so unless the version specified is very close to that of the driver (for example, -V 3.0 with a driver program from GCC version 3.0.1), use of -V may not work; for example, using -V 2.95.2 will not work with a driver program from GCC 3.0.

The only way that the driver program depends on the target machine is in the parsing and handling of special machine-specific options. However, this is controlled by a file which is found, along with the other executables, in the directory for the specified version and target machine. As a result, a single installed driver program adapts to any specified target machine, and sufficiently similar compiler versions.

The driver program executable does control one significant thing, however: the default version and target machine. Therefore, you can install different instances of the driver program, compiled for different targets or versions, under different names.

For example, if the driver for version 2.0 is installed as ogcc and that for version 2.1 is installed as gcc, then the command gcc will use version 2.1 by default, while ogcc will use 2.0 by default. However, you can choose either version with either command with the -V option.


Using the GNU Compiler Collection (GCC)

Node:Template Instantiation, Next:Bound member functions, Previous:C++ Interface, Up:C++ Extensions

Where's the Template?

C++ templates are the first language feature to require more intelligence from the environment than one usually finds on a UNIX system. Somehow the compiler and linker have to make sure that each template instance occurs exactly once in the executable if it is needed, and not at all otherwise. There are two basic approaches to this problem, which I will refer to as the Borland model and the Cfront model.

Borland model
Borland C++ solved the template instantiation problem by adding the code equivalent of common blocks to their linker; the compiler emits template instances in each translation unit that uses them, and the linker collapses them together. The advantage of this model is that the linker only has to consider the object files themselves; there is no external complexity to worry about. This disadvantage is that compilation time is increased because the template code is being compiled repeatedly. Code written for this model tends to include definitions of all templates in the header file, since they must be seen to be instantiated.
Cfront model
The AT&T C++ translator, Cfront, solved the template instantiation problem by creating the notion of a template repository, an automatically maintained place where template instances are stored. A more modern version of the repository works as follows: As individual object files are built, the compiler places any template definitions and instantiations encountered in the repository. At link time, the link wrapper adds in the objects in the repository and compiles any needed instances that were not previously emitted. The advantages of this model are more optimal compilation speed and the ability to use the system linker; to implement the Borland model a compiler vendor also needs to replace the linker. The disadvantages are vastly increased complexity, and thus potential for error; for some code this can be just as transparent, but in practice it can been very difficult to build multiple programs in one directory and one program in multiple directories. Code written for this model tends to separate definitions of non-inline member templates into a separate file, which should be compiled separately.

When used with GNU ld version 2.8 or later on an ELF system such as Linux/GNU or Solaris 2, or on Microsoft Windows, g++ supports the Borland model. On other systems, g++ implements neither automatic model.

A future version of g++ will support a hybrid model whereby the compiler will emit any instantiations for which the template definition is included in the compile, and store template definitions and instantiation context information into the object file for the rest. The link wrapper will extract that information as necessary and invoke the compiler to produce the remaining instantiations. The linker will then combine duplicate instantiations.

In the mean time, you have the following options for dealing with template instantiations:

  1. Compile your template-using code with -frepo. The compiler will generate files with the extension .rpo listing all of the template instantiations used in the corresponding object files which could be instantiated there; the link wrapper, collect2, will then update the .rpo files to tell the compiler where to place those instantiations and rebuild any affected object files. The link-time overhead is negligible after the first pass, as the compiler will continue to place the instantiations in the same files.

    This is your best option for application code written for the Borland model, as it will just work. Code written for the Cfront model will need to be modified so that the template definitions are available at one or more points of instantiation; usually this is as simple as adding #include <tmethods.cc> to the end of each template header.

    For library code, if you want the library to provide all of the template instantiations it needs, just try to link all of its object files together; the link will fail, but cause the instantiations to be generated as a side effect. Be warned, however, that this may cause conflicts if multiple libraries try to provide the same instantiations. For greater control, use explicit instantiation as described in the next option.

  2. Compile your code with -fno-implicit-templates to disable the implicit generation of template instances, and explicitly instantiate all the ones you use. This approach requires more knowledge of exactly which instances you need than do the others, but it's less mysterious and allows greater control. You can scatter the explicit instantiations throughout your program, perhaps putting them in the translation units where the instances are used or the translation units that define the templates themselves; you can put all of the explicit instantiations you need into one big file; or you can create small files like
    #include "Foo.h"
#include "Foo.cc"

template class Foo<int>;
template ostream& operator <<
                (ostream&, const Foo<int>&);

    for each of the instances you need, and create a template instantiation library from those.

    If you are using Cfront-model code, you can probably get away with not using -fno-implicit-templates when compiling files that don't #include the member template definitions.

    If you use one big file to do the instantiations, you may want to compile it without -fno-implicit-templates so you get all of the instances required by your explicit instantiations (but not by any other files) without having to specify them as well.

    g++ has extended the template instantiation syntax outlined in the Working Paper to allow forward declaration of explicit instantiations (with extern), instantiation of the compiler support data for a template class (i.e. the vtable) without instantiating any of its members (with inline), and instantiation of only the static data members of a template class, without the support data or member functions (with (static):

    extern template int max (int, int);
inline template class Foo<int>;
static template class Foo<int>;

  3. Do nothing. Pretend g++ does implement automatic instantiation management. Code written for the Borland model will work fine, but each translation unit will contain instances of each of the templates it uses. In a large program, this can lead to an unacceptable amount of code duplication.
  4. Add #pragma interface to all files containing template definitions. For each of these files, add #pragma implementation "filename" to the top of some .C file which #includes it. Then compile everything with -fexternal-templates. The templates will then only be expanded in the translation unit which implements them (i.e. has a #pragma implementation line for the file where they live); all other files will use external references. If you're lucky, everything should work properly. If you get undefined symbol errors, you need to make sure that each template instance which is used in the program is used in the file which implements that template. If you don't have any use for a particular instance in that file, you can just instantiate it explicitly, using the syntax from the latest C++ working paper:
    template class A<int>;
template ostream& operator << (ostream&, const A<int>&);

    This strategy will work with code written for either model. If you are using code written for the Cfront model, the file containing a class template and the file containing its member templates should be implemented in the same translation unit.

  5. A slight variation on this approach is to use the flag -falt-external-templates instead. This flag causes template instances to be emitted in the translation unit that implements the header where they are first instantiated, rather than the one which implements the file where the templates are defined. This header must be the same in all translation units, or things are likely to break.

    See Declarations and Definitions in One Header, for more discussion of these pragmas.


Using the GNU Compiler Collection (GCC)

Node:Temporaries, Next:Copy Assignment, Previous:Static Definitions, Up:C++ Misunderstandings

Temporaries May Vanish Before You Expect

It is dangerous to use pointers or references to portions of a temporary object. The compiler may very well delete the object before you expect it to, leaving a pointer to garbage. The most common place where this problem crops up is in classes like string classes, especially ones that define a conversion function to type char * or const char *--which is one reason why the standard string class requires you to call the c_str member function. However, any class that returns a pointer to some internal structure is potentially subject to this problem.

For example, a program may use a function strfunc that returns string objects, and another function charfunc that operates on pointers to char:

string strfunc ();
void charfunc (const char *);

void
f ()
{
  const char *p = strfunc().c_str();
  ...
  charfunc (p);
  ...
  charfunc (p);
}

In this situation, it may seem reasonable to save a pointer to the C string returned by the c_str member function and use that rather than call c_str repeatedly. However, the temporary string created by the call to strfunc is destroyed after p is initialized, at which point p is left pointing to freed memory.

Code like this may run successfully under some other compilers, particularly obsolete cfront-based compilers that delete temporaries along with normal local variables. However, the GNU C++ behavior is standard-conforming, so if your program depends on late destruction of temporaries it is not portable.

The safe way to write such code is to give the temporary a name, which forces it to remain until the end of the scope of the name. For example:

string& tmp = strfunc ();
charfunc (tmp.c_str ());


Using the GNU Compiler Collection (GCC)

Node:TMS320C3x/C4x Options, Next:V850 Options, Previous:System V Options, Up:Submodel Options

TMS320C3x/C4x Options

These -m options are defined for TMS320C3x/C4x implementations:

-mcpu=cpu_type
Set the instruction set, register set, and instruction scheduling parameters for machine type cpu_type. Supported values for cpu_type are c30, c31, c32, c40, and c44. The default is c40 to generate code for the TMS320C40.
-mbig-memory
-mbig
-msmall-memory
-msmall
Generates code for the big or small memory model. The small memory model assumed that all data fits into one 64K word page. At run-time the data page (DP) register must be set to point to the 64K page containing the .bss and .data program sections. The big memory model is the default and requires reloading of the DP register for every direct memory access.
-mbk
-mno-bk
Allow (disallow) allocation of general integer operands into the block count register BK.
-mdb
-mno-db
Enable (disable) generation of code using decrement and branch, DBcond(D), instructions. This is enabled by default for the C4x. To be on the safe side, this is disabled for the C3x, since the maximum iteration count on the C3x is 2^23 + 1 (but who iterates loops more than 2^23 times on the C3x?). Note that GCC will try to reverse a loop so that it can utilise the decrement and branch instruction, but will give up if there is more than one memory reference in the loop. Thus a loop where the loop counter is decremented can generate slightly more efficient code, in cases where the RPTB instruction cannot be utilised.
-mdp-isr-reload
-mparanoid
Force the DP register to be saved on entry to an interrupt service routine (ISR), reloaded to point to the data section, and restored on exit from the ISR. This should not be required unless someone has violated the small memory model by modifying the DP register, say within an object library.
-mmpyi
-mno-mpyi
For the C3x use the 24-bit MPYI instruction for integer multiplies instead of a library call to guarantee 32-bit results. Note that if one of the operands is a constant, then the multiplication will be performed using shifts and adds. If the -mmpyi option is not specified for the C3x, then squaring operations are performed inline instead of a library call.
-mfast-fix
-mno-fast-fix
The C3x/C4x FIX instruction to convert a floating point value to an integer value chooses the nearest integer less than or equal to the floating point value rather than to the nearest integer. Thus if the floating point number is negative, the result will be incorrectly truncated an additional code is necessary to detect and correct this case. This option can be used to disable generation of the additional code required to correct the result.
-mrptb
-mno-rptb
Enable (disable) generation of repeat block sequences using the RPTB instruction for zero overhead looping. The RPTB construct is only used for innermost loops that do not call functions or jump across the loop boundaries. There is no advantage having nested RPTB loops due to the overhead required to save and restore the RC, RS, and RE registers. This is enabled by default with -O2.
-mrpts=count
-mno-rpts
Enable (disable) the use of the single instruction repeat instruction RPTS. If a repeat block contains a single instruction, and the loop count can be guaranteed to be less than the value count, GCC will emit a RPTS instruction instead of a RPTB. If no value is specified, then a RPTS will be emitted even if the loop count cannot be determined at compile time. Note that the repeated instruction following RPTS does not have to be reloaded from memory each iteration, thus freeing up the CPU buses for operands. However, since interrupts are blocked by this instruction, it is disabled by default.
-mloop-unsigned
-mno-loop-unsigned
The maximum iteration count when using RPTS and RPTB (and DB on the C40) is 2^31 + 1 since these instructions test if the iteration count is negative to terminate the loop. If the iteration count is unsigned there is a possibility than the 2^31 + 1 maximum iteration count may be exceeded. This switch allows an unsigned iteration count.
-mti
Try to emit an assembler syntax that the TI assembler (asm30) is happy with. This also enforces compatibility with the API employed by the TI C3x C compiler. For example, long doubles are passed as structures rather than in floating point registers.
-mregparm
-mmemparm
Generate code that uses registers (stack) for passing arguments to functions. By default, arguments are passed in registers where possible rather than by pushing arguments on to the stack.
-mparallel-insns
-mno-parallel-insns
Allow the generation of parallel instructions. This is enabled by default with -O2.
-mparallel-mpy
-mno-parallel-mpy
Allow the generation of MPY||ADD and MPY||SUB parallel instructions, provided -mparallel-insns is also specified. These instructions have tight register constraints which can pessimize the code generation of large functions.


Using the GNU Compiler Collection (GCC)

Node:Translation implementation, Next:Environment implementation, Up:C Implementation

Translation

  • How a diagnostic is identified (3.10, 5.1.1.3).
  • Whether each nonempty sequence of white-space characters other than new-line is retained or replaced by one space character in translation phase 3 (5.1.1.2).


Using the GNU Compiler Collection (GCC)

Node:Trouble, Next:Bugs, Previous:Gcov, Up:Top

Known Causes of Trouble with GCC

This section describes known problems that affect users of GCC. Most of these are not GCC bugs per se--if they were, we would fix them. But the result for a user may be like the result of a bug.

Some of these problems are due to bugs in other software, some are missing features that are too much work to add, and some are places where people's opinions differ as to what is best.

  • Actual Bugs: Bugs we will fix later.
  • Cross-Compiler Problems: Common problems of cross compiling with GCC.
  • Interoperation: Problems using GCC with other compilers, and with certain linkers, assemblers and debuggers.
  • External Bugs: Problems compiling certain programs.
  • Incompatibilities: GCC is incompatible with traditional C.
  • Fixed Headers: GCC uses corrected versions of system header files. This is necessary, but doesn't always work smoothly.
  • Standard Libraries: GCC uses the system C library, which might not be compliant with the ISO C standard.
  • Disappointments: Regrettable things we can't change, but not quite bugs.
  • C++ Misunderstandings: Common misunderstandings with GNU C++.
  • Protoize Caveats: Things to watch out for when using protoize.
  • Non-bugs: Things we think are right, but some others disagree.
  • Warnings and Errors: Which problems in your code get warnings, and which get errors.


Using the GNU Compiler Collection (GCC)

Node:Tru64 Pragmas, Previous:Solaris Pragmas, Up:Pragmas

Tru64 Pragmas

For compatibility with the Compaq C compiler, the following pragma is supported.

extern_prefix string

This pragma renames all subsequent function and variable declarations such that string is prepended to the name. This effect may be terminated by using another extern_prefix pragma with the empty string.

This pragma is similar in intent to to the asm labels extension (see Asm Labels) in that the system programmer wants to change the assembly-level ABI without changing the source-level API. The preprocessor defines __EXTERN_PREFIX if the pragma is available.


Using the GNU Compiler Collection (GCC)

Node:Type Attributes, Next:Alignment, Previous:Variable Attributes, Up:C Extensions

Specifying Attributes of Types

The keyword __attribute__ allows you to specify special attributes of struct and union types when you define such types. This keyword is followed by an attribute specification inside double parentheses. Five attributes are currently defined for types: aligned, packed, transparent_union, unused, and deprecated. Other attributes are defined for functions (see Function Attributes) and for variables (see Variable Attributes).

You may also specify any one of these attributes with __ preceding and following its keyword. This allows you to use these attributes in header files without being concerned about a possible macro of the same name. For example, you may use __aligned__ instead of aligned.

You may specify the aligned and transparent_union attributes either in a typedef declaration or just past the closing curly brace of a complete enum, struct or union type definition and the packed attribute only past the closing brace of a definition.

You may also specify attributes between the enum, struct or union tag and the name of the type rather than after the closing brace.

See Attribute Syntax, for details of the exact syntax for using attributes.

aligned (alignment)
This attribute specifies a minimum alignment (in bytes) for variables of the specified type. For example, the declarations:
struct S { short f[3]; } __attribute__ ((aligned (8)));
typedef int more_aligned_int __attribute__ ((aligned (8)));

force the compiler to insure (as far as it can) that each variable whose type is struct S or more_aligned_int will be allocated and aligned at least on a 8-byte boundary. On a Sparc, having all variables of type struct S aligned to 8-byte boundaries allows the compiler to use the ldd and std (doubleword load and store) instructions when copying one variable of type struct S to another, thus improving run-time efficiency.

Note that the alignment of any given struct or union type is required by the ISO C standard to be at least a perfect multiple of the lowest common multiple of the alignments of all of the members of the struct or union in question. This means that you can effectively adjust the alignment of a struct or union type by attaching an aligned attribute to any one of the members of such a type, but the notation illustrated in the example above is a more obvious, intuitive, and readable way to request the compiler to adjust the alignment of an entire struct or union type.

As in the preceding example, you can explicitly specify the alignment (in bytes) that you wish the compiler to use for a given struct or union type. Alternatively, you can leave out the alignment factor and just ask the compiler to align a type to the maximum useful alignment for the target machine you are compiling for. For example, you could write:

struct S { short f[3]; } __attribute__ ((aligned));

Whenever you leave out the alignment factor in an aligned attribute specification, the compiler automatically sets the alignment for the type to the largest alignment which is ever used for any data type on the target machine you are compiling for. Doing this can often make copy operations more efficient, because the compiler can use whatever instructions copy the biggest chunks of memory when performing copies to or from the variables which have types that you have aligned this way.

In the example above, if the size of each short is 2 bytes, then the size of the entire struct S type is 6 bytes. The smallest power of two which is greater than or equal to that is 8, so the compiler sets the alignment for the entire struct S type to 8 bytes.

Note that although you can ask the compiler to select a time-efficient alignment for a given type and then declare only individual stand-alone objects of that type, the compiler's ability to select a time-efficient alignment is primarily useful only when you plan to create arrays of variables having the relevant (efficiently aligned) type. If you declare or use arrays of variables of an efficiently-aligned type, then it is likely that your program will also be doing pointer arithmetic (or subscripting, which amounts to the same thing) on pointers to the relevant type, and the code that the compiler generates for these pointer arithmetic operations will often be more efficient for efficiently-aligned types than for other types.

The aligned attribute can only increase the alignment; but you can decrease it by specifying packed as well. See below.

Note that the effectiveness of aligned attributes may be limited by inherent limitations in your linker. On many systems, the linker is only able to arrange for variables to be aligned up to a certain maximum alignment. (For some linkers, the maximum supported alignment may be very very small.) If your linker is only able to align variables up to a maximum of 8 byte alignment, then specifying aligned(16) in an __attribute__ will still only provide you with 8 byte alignment. See your linker documentation for further information.

packed
This attribute, attached to an enum, struct, or union type definition, specified that the minimum required memory be used to represent the type.

Specifying this attribute for struct and union types is equivalent to specifying the packed attribute on each of the structure or union members. Specifying the -fshort-enums flag on the line is equivalent to specifying the packed attribute on all enum definitions.

You may only specify this attribute after a closing curly brace on an enum definition, not in a typedef declaration, unless that declaration also contains the definition of the enum.

transparent_union
This attribute, attached to a union type definition, indicates that any function parameter having that union type causes calls to that function to be treated in a special way.

First, the argument corresponding to a transparent union type can be of any type in the union; no cast is required. Also, if the union contains a pointer type, the corresponding argument can be a null pointer constant or a void pointer expression; and if the union contains a void pointer type, the corresponding argument can be any pointer expression. If the union member type is a pointer, qualifiers like const on the referenced type must be respected, just as with normal pointer conversions.

Second, the argument is passed to the function using the calling conventions of first member of the transparent union, not the calling conventions of the union itself. All members of the union must have the same machine representation; this is necessary for this argument passing to work properly.

Transparent unions are designed for library functions that have multiple interfaces for compatibility reasons. For example, suppose the wait function must accept either a value of type int * to comply with Posix, or a value of type union wait * to comply with the 4.1BSD interface. If wait's parameter were void *, wait would accept both kinds of arguments, but it would also accept any other pointer type and this would make argument type checking less useful. Instead, <sys/wait.h> might define the interface as follows:

typedef union
  {
    int *__ip;
    union wait *__up;
  } wait_status_ptr_t __attribute__ ((__transparent_union__));

pid_t wait (wait_status_ptr_t);

This interface allows either int * or union wait * arguments to be passed, using the int * calling convention. The program can call wait with arguments of either type:

int w1 () { int w; return wait (&w); }
int w2 () { union wait w; return wait (&w); }

With this interface, wait's implementation might look like this:

pid_t wait (wait_status_ptr_t p)
{
  return waitpid (-1, p.__ip, 0);
}

unused
When attached to a type (including a union or a struct), this attribute means that variables of that type are meant to appear possibly unused. GCC will not produce a warning for any variables of that type, even if the variable appears to do nothing. This is often the case with lock or thread classes, which are usually defined and then not referenced, but contain constructors and destructors that have nontrivial bookkeeping functions.
deprecated
The deprecated attribute results in a warning if the type is used anywhere in the source file. This is useful when identifying types that are expected to be removed in a future version of a program. If possible, the warning also includes the location of the declaration of the deprecated type, to enable users to easily find further information about why the type is deprecated, or what they should do instead. Note that the warnings only occur for uses and then only if the type is being applied to an identifier that itself is not being declared as deprecated.
typedef int T1 __attribute__ ((deprecated));
T1 x;
typedef T1 T2;
T2 y;
typedef T1 T3 __attribute__ ((deprecated));
T3 z __attribute__ ((deprecated));

results in a warning on line 2 and 3 but not lines 4, 5, or 6. No warning is issued for line 4 because T2 is not explicitly deprecated. Line 5 has no warning because T3 is explicitly deprecated. Similarly for line 6.

The deprecated attribute can also be used for functions and variables (see Function Attributes, see Variable Attributes.)

To specify multiple attributes, separate them by commas within the double parentheses: for example, __attribute__ ((aligned (16), packed)).


Using the GNU Compiler Collection (GCC)

Node:Type encoding, Next:Garbage Collection, Previous:Executing code before main, Up:Objective-C

Type encoding

The Objective-C compiler generates type encodings for all the types. These type encodings are used at runtime to find out information about selectors and methods and about objects and classes.

The types are encoded in the following way:

char | c
unsigned char | C
short | s
unsigned short | S
int | i
unsigned int | I
long | l
unsigned long | L
long long | q
unsigned long long | Q
float | f
double | d
void | v
id | @
Class | #
SEL | :
char* | *
unknown type | ?
bit-fields | b followed by the starting position of the bit-field, the type of the bit-field and the size of the bit-field (the bit-fields encoding was changed from the NeXT's compiler encoding, see below)

The encoding of bit-fields has changed to allow bit-fields to be properly handled by the runtime functions that compute sizes and alignments of types that contain bit-fields. The previous encoding contained only the size of the bit-field. Using only this information it is not possible to reliably compute the size occupied by the bit-field. This is very important in the presence of the Boehm's garbage collector because the objects are allocated using the typed memory facility available in this collector. The typed memory allocation requires information about where the pointers are located inside the object.

The position in the bit-field is the position, counting in bits, of the bit closest to the beginning of the structure.

The non-atomic types are encoded as follows:

pointers | ^ followed by the pointed type.
arrays | [ followed by the number of elements in the array followed by the type of the elements followed by ]
structures | { followed by the name of the structure (or ? if the structure is unnamed), the = sign, the type of the members and by }
unions | ( followed by the name of the structure (or ? if the union is unnamed), the = sign, the type of the members followed by )

Here are some types and their encodings, as they are generated by the compiler on an i386 machine:

Objective-C type Compiler encoding

int a[10];
[10i]

struct {
  int i;
  float f[3];
  int a:3;
  int b:2;
  char c;
}
{?=i[3f]b128i3b131i2c}

In addition to the types the compiler also encodes the type specifiers. The table below describes the encoding of the current Objective-C type specifiers:

Specifier | Encoding
const | r
in | n
inout | N
out | o
bycopy | O
oneway | V

The type specifiers are encoded just before the type. Unlike types however, the type specifiers are only encoded when they appear in method argument types.


Using the GNU Compiler Collection (GCC)

Node:Typeof, Next:Lvalues, Previous:Naming Types, Up:C Extensions

Referring to a Type with typeof

Another way to refer to the type of an expression is with typeof. The syntax of using of this keyword looks like sizeof, but the construct acts semantically like a type name defined with typedef.

There are two ways of writing the argument to typeof: with an expression or with a type. Here is an example with an expression:

typeof (x[0](1))

This assumes that x is an array of pointers to functions; the type described is that of the values of the functions.

Here is an example with a typename as the argument:

typeof (int *)

Here the type described is that of pointers to int.

If you are writing a header file that must work when included in ISO C programs, write __typeof__ instead of typeof. See Alternate Keywords.

A typeof-construct can be used anywhere a typedef name could be used. For example, you can use it in a declaration, in a cast, or inside of sizeof or typeof.

  • This declares y with the type of what x points to.
    typeof (*x) y;
  • This declares y as an array of such values.
    typeof (*x) y[4];
  • This declares y as an array of pointers to characters:
    typeof (typeof (char *)[4]) y;

    It is equivalent to the following traditional C declaration:

    char *y[4];

    To see the meaning of the declaration using typeof, and why it might be a useful way to write, let's rewrite it with these macros:

    #define pointer(T)  typeof(T *)
#define array(T, N) typeof(T [N])

    Now the declaration can be rewritten this way:

    array (pointer (char), 4) y;

    Thus, array (pointer (char), 4) is the type of arrays of 4 pointers to char.


Using the GNU Compiler Collection (GCC)

Node:Unnamed Fields, Previous:Pragmas, Up:C Extensions

Unnamed struct/union fields within structs/unions.

For compatibility with other compilers, GCC allows you to define a structure or union that contains, as fields, structures and unions without names. For example:

struct {
  int a;
  union {
    int b;
    float c;
  };
  int d;
} foo;

In this example, the user would be able to access members of the unnamed union with code like foo.b. Note that only unnamed structs and unions are allowed, you may not have, for example, an unnamed int.

You must never create such structures that cause ambiguous field definitions. For example, this structure:

struct {
  int a;
  struct {
    int a;
  };
} foo;

It is ambiguous which a is being referred to with foo.a. Such constructs are not supported and must be avoided. In the future, such constructs may be detected and treated as compilation errors.


Using the GNU Compiler Collection (GCC)

Node:V850 Options, Next:ARC Options, Previous:TMS320C3x/C4x Options, Up:Submodel Options

V850 Options

These -m options are defined for V850 implementations:

-mlong-calls
-mno-long-calls
Treat all calls as being far away (near). If calls are assumed to be far away, the compiler will always load the functions address up into a register, and call indirect through the pointer.
-mno-ep
-mep
Do not optimize (do optimize) basic blocks that use the same index pointer 4 or more times to copy pointer into the ep register, and use the shorter sld and sst instructions. The -mep option is on by default if you optimize.
-mno-prolog-function
-mprolog-function
Do not use (do use) external functions to save and restore registers at the prolog and epilog of a function. The external functions are slower, but use less code space if more than one function saves the same number of registers. The -mprolog-function option is on by default if you optimize.
-mspace
Try to make the code as small as possible. At present, this just turns on the -mep and -mprolog-function options.
-mtda=n
Put static or global variables whose size is n bytes or less into the tiny data area that register ep points to. The tiny data area can hold up to 256 bytes in total (128 bytes for byte references).
-msda=n
Put static or global variables whose size is n bytes or less into the small data area that register gp points to. The small data area can hold up to 64 kilobytes.
-mzda=n
Put static or global variables whose size is n bytes or less into the first 32 kilobytes of memory.
-mv850
Specify that the target processor is the V850.
-mbig-switch
Generate code suitable for big switch tables. Use this option only if the assembler/linker complain about out of range branches within a switch table.


Using the GNU Compiler Collection (GCC)

Node:Vague Linkage, Next:C++ Interface, Previous:Restricted Pointers, Up:C++ Extensions

Vague Linkage

There are several constructs in C++ which require space in the object file but are not clearly tied to a single translation unit. We say that these constructs have "vague linkage". Typically such constructs are emitted wherever they are needed, though sometimes we can be more clever.

Inline Functions
Inline functions are typically defined in a header file which can be included in many different compilations. Hopefully they can usually be inlined, but sometimes an out-of-line copy is necessary, if the address of the function is taken or if inlining fails. In general, we emit an out-of-line copy in all translation units where one is needed. As an exception, we only emit inline virtual functions with the vtable, since it will always require a copy.

Local static variables and string constants used in an inline function are also considered to have vague linkage, since they must be shared between all inlined and out-of-line instances of the function.

VTables
C++ virtual functions are implemented in most compilers using a lookup table, known as a vtable. The vtable contains pointers to the virtual functions provided by a class, and each object of the class contains a pointer to its vtable (or vtables, in some multiple-inheritance situations). If the class declares any non-inline, non-pure virtual functions, the first one is chosen as the "key method" for the class, and the vtable is only emitted in the translation unit where the key method is defined.

Note: If the chosen key method is later defined as inline, the vtable will still be emitted in every translation unit which defines it. Make sure that any inline virtuals are declared inline in the class body, even if they are not defined there.

type_info objects
C++ requires information about types to be written out in order to implement dynamic_cast, typeid and exception handling. For polymorphic classes (classes with virtual functions), the type_info object is written out along with the vtable so that dynamic_cast can determine the dynamic type of a class object at runtime. For all other types, we write out the type_info object when it is used: when applying typeid to an expression, throwing an object, or referring to a type in a catch clause or exception specification.
Template Instantiations
Most everything in this section also applies to template instantiations, but there are other options as well. See Where's the Template?.

When used with GNU ld version 2.8 or later on an ELF system such as Linux/GNU or Solaris 2, or on Microsoft Windows, duplicate copies of these constructs will be discarded at link time. This is known as COMDAT support.

On targets that don't support COMDAT, but do support weak symbols, GCC will use them. This way one copy will override all the others, but the unused copies will still take up space in the executable.

For targets which do not support either COMDAT or weak symbols, most entities with vague linkage will be emitted as local symbols to avoid duplicate definition errors from the linker. This will not happen for local statics in inlines, however, as having multiple copies will almost certainly break things.

See Declarations and Definitions in One Header, for another way to control placement of these constructs.


Using the GNU Compiler Collection (GCC)

Node:Variable Attributes, Next:Type Attributes, Previous:Character Escapes, Up:C Extensions

Specifying Attributes of Variables

The keyword __attribute__ allows you to specify special attributes of variables or structure fields. This keyword is followed by an attribute specification inside double parentheses. Ten attributes are currently defined for variables: aligned, mode, nocommon, packed, section, transparent_union, unused, deprecated, vector_size, and weak. Some other attributes are defined for variables on particular target systems. Other attributes are available for functions (see Function Attributes) and for types (see Type Attributes). Other front ends might define more attributes (see Extensions to the C++ Language).

You may also specify attributes with __ preceding and following each keyword. This allows you to use them in header files without being concerned about a possible macro of the same name. For example, you may use __aligned__ instead of aligned.

See Attribute Syntax, for details of the exact syntax for using attributes.

aligned (alignment)
This attribute specifies a minimum alignment for the variable or structure field, measured in bytes. For example, the declaration:
int x __attribute__ ((aligned (16))) = 0;

causes the compiler to allocate the global variable x on a 16-byte boundary. On a 68040, this could be used in conjunction with an asm expression to access the move16 instruction which requires 16-byte aligned operands.

You can also specify the alignment of structure fields. For example, to create a double-word aligned int pair, you could write:

struct foo { int x[2] __attribute__ ((aligned (8))); };

This is an alternative to creating a union with a double member that forces the union to be double-word aligned.

As in the preceding examples, you can explicitly specify the alignment (in bytes) that you wish the compiler to use for a given variable or structure field. Alternatively, you can leave out the alignment factor and just ask the compiler to align a variable or field to the maximum useful alignment for the target machine you are compiling for. For example, you could write:

short array[3] __attribute__ ((aligned));

Whenever you leave out the alignment factor in an aligned attribute specification, the compiler automatically sets the alignment for the declared variable or field to the largest alignment which is ever used for any data type on the target machine you are compiling for. Doing this can often make copy operations more efficient, because the compiler can use whatever instructions copy the biggest chunks of memory when performing copies to or from the variables or fields that you have aligned this way.

The aligned attribute can only increase the alignment; but you can decrease it by specifying packed as well. See below.

Note that the effectiveness of aligned attributes may be limited by inherent limitations in your linker. On many systems, the linker is only able to arrange for variables to be aligned up to a certain maximum alignment. (For some linkers, the maximum supported alignment may be very very small.) If your linker is only able to align variables up to a maximum of 8 byte alignment, then specifying aligned(16) in an __attribute__ will still only provide you with 8 byte alignment. See your linker documentation for further information.

mode (mode)
This attribute specifies the data type for the declaration--whichever type corresponds to the mode mode. This in effect lets you request an integer or floating point type according to its width.

You may also specify a mode of byte or __byte__ to indicate the mode corresponding to a one-byte integer, word or __word__ for the mode of a one-word integer, and pointer or __pointer__ for the mode used to represent pointers.

nocommon
This attribute specifies requests GCC not to place a variable "common" but instead to allocate space for it directly. If you specify the -fno-common flag, GCC will do this for all variables.

Specifying the nocommon attribute for a variable provides an initialization of zeros. A variable may only be initialized in one source file.

packed
The packed attribute specifies that a variable or structure field should have the smallest possible alignment--one byte for a variable, and one bit for a field, unless you specify a larger value with the aligned attribute.

Here is a structure in which the field x is packed, so that it immediately follows a:

struct foo
{
  char a;
  int x[2] __attribute__ ((packed));
};

section ("section-name")
Normally, the compiler places the objects it generates in sections like data and bss. Sometimes, however, you need additional sections, or you need certain particular variables to appear in special sections, for example to map to special hardware. The section attribute specifies that a variable (or function) lives in a particular section. For example, this small program uses several specific section names:
struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
int init_data __attribute__ ((section ("INITDATA"))) = 0;

main()
{
  /* Initialize stack pointer */
  init_sp (stack + sizeof (stack));

  /* Initialize initialized data */
  memcpy (&init_data, &data, &edata - &data);

  /* Turn on the serial ports */
  init_duart (&a);
  init_duart (&b);
}

Use the section attribute with an initialized definition of a global variable, as shown in the example. GCC issues a warning and otherwise ignores the section attribute in uninitialized variable declarations.

You may only use the section attribute with a fully initialized global definition because of the way linkers work. The linker requires each object be defined once, with the exception that uninitialized variables tentatively go in the common (or bss) section and can be multiply "defined". You can force a variable to be initialized with the -fno-common flag or the nocommon attribute.

Some file formats do not support arbitrary sections so the section attribute is not available on all platforms. If you need to map the entire contents of a module to a particular section, consider using the facilities of the linker instead.

shared
On Windows NT, in addition to putting variable definitions in a named section, the section can also be shared among all running copies of an executable or DLL. For example, this small program defines shared data by putting it in a named section shared and marking the section shareable:
int foo __attribute__((section ("shared"), shared)) = 0;

int
main()
{
  /* Read and write foo.  All running
     copies see the same value.  */
  return 0;
}

You may only use the shared attribute along with section attribute with a fully initialized global definition because of the way linkers work. See section attribute for more information.

The shared attribute is only available on Windows NT.

transparent_union
This attribute, attached to a function parameter which is a union, means that the corresponding argument may have the type of any union member, but the argument is passed as if its type were that of the first union member. For more details see See Type Attributes. You can also use this attribute on a typedef for a union data type; then it applies to all function parameters with that type.
unused
This attribute, attached to a variable, means that the variable is meant to be possibly unused. GCC will not produce a warning for this variable.
deprecated
The deprecated attribute results in a warning if the variable is used anywhere in the source file. This is useful when identifying variables that are expected to be removed in a future version of a program. The warning also includes the location of the declaration of the deprecated variable, to enable users to easily find further information about why the variable is deprecated, or what they should do instead. Note that the warnings only occurs for uses:
extern int old_var __attribute__ ((deprecated));
extern int old_var;
int new_fn () { return old_var; }

results in a warning on line 3 but not line 2.

The deprecated attribute can also be used for functions and types (see Function Attributes, see Type Attributes.)

vector_size (bytes)
This attribute specifies the vector size for the variable, measured in bytes. For example, the declaration:
int foo __attribute__ ((vector_size (16)));

causes the compiler to set the mode for foo, to be 16 bytes, divided into int sized units. Assuming a 32-bit int (a vector of 4 units of 4 bytes), the corresponding mode of foo will be V4SI.

This attribute is only applicable to integral and float scalars, although arrays, pointers, and function return values are allowed in conjunction with this construct.

Aggregates with this attribute are invalid, even if they are of the same size as a corresponding scalar. For example, the declaration:

struct S { int a; };
struct S  __attribute__ ((vector_size (16))) foo;

is invalid even if the size of the structure is the same as the size of the int.

weak
The weak attribute is described in See Function Attributes.
model (model-name)
Use this attribute on the M32R/D to set the addressability of an object. The identifier model-name is one of small, medium, or large, representing each of the code models.

Small model objects live in the lower 16MB of memory (so that their addresses can be loaded with the ld24 instruction).

Medium and large model objects may live anywhere in the 32-bit address space (the compiler will generate seth/add3 instructions to load their addresses).

To specify multiple attributes, separate them by commas within the double parentheses: for example, __attribute__ ((aligned (16), packed)).


Using the GNU Compiler Collection (GCC)

Node:Variable Length, Next:Variadic Macros, Previous:Zero Length, Up:C Extensions

Arrays of Variable Length

Variable-length automatic arrays are allowed in ISO C99, and as an extension GCC accepts them in C89 mode and in C++. (However, GCC's implementation of variable-length arrays does not yet conform in detail to the ISO C99 standard.) These arrays are declared like any other automatic arrays, but with a length that is not a constant expression. The storage is allocated at the point of declaration and deallocated when the brace-level is exited. For example:

FILE *
concat_fopen (char *s1, char *s2, char *mode)
{
  char str[strlen (s1) + strlen (s2) + 1];
  strcpy (str, s1);
  strcat (str, s2);
  return fopen (str, mode);
}

Jumping or breaking out of the scope of the array name deallocates the storage. Jumping into the scope is not allowed; you get an error message for it.

You can use the function alloca to get an effect much like variable-length arrays. The function alloca is available in many other C implementations (but not in all). On the other hand, variable-length arrays are more elegant.

There are other differences between these two methods. Space allocated with alloca exists until the containing function returns. The space for a variable-length array is deallocated as soon as the array name's scope ends. (If you use both variable-length arrays and alloca in the same function, deallocation of a variable-length array will also deallocate anything more recently allocated with alloca.)

You can also use variable-length arrays as arguments to functions:

struct entry
tester (int len, char data[len][len])
{
  ...
}

The length of an array is computed once when the storage is allocated and is remembered for the scope of the array in case you access it with sizeof.

If you want to pass the array first and the length afterward, you can use a forward declaration in the parameter list--another GNU extension.

struct entry
tester (int len; char data[len][len], int len)
{
  ...
}

The int len before the semicolon is a parameter forward declaration, and it serves the purpose of making the name len known when the declaration of data is parsed.

You can write any number of such parameter forward declarations in the parameter list. They can be separated by commas or semicolons, but the last one must end with a semicolon, which is followed by the "real" parameter declarations. Each forward declaration must match a "real" declaration in parameter name and data type. ISO C99 does not support parameter forward declarations.


Using the GNU Compiler Collection (GCC)

Node:Variadic Macros, Next:Escaped Newlines, Previous:Variable Length, Up:C Extensions

Macros with a Variable Number of Arguments.

In the ISO C standard of 1999, a macro can be declared to accept a variable number of arguments much as a function can. The syntax for defining the macro is similar to that of a function. Here is an example:

#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)

Here ... is a variable argument. In the invocation of such a macro, it represents the zero or more tokens until the closing parenthesis that ends the invocation, including any commas. This set of tokens replaces the identifier __VA_ARGS__ in the macro body wherever it appears. See the CPP manual for more information.

GCC has long supported variadic macros, and used a different syntax that allowed you to give a name to the variable arguments just like any other argument. Here is an example:

#define debug(format, args...) fprintf (stderr, format, args)

This is in all ways equivalent to the ISO C example above, but arguably more readable and descriptive.

GNU CPP has two further variadic macro extensions, and permits them to be used with either of the above forms of macro definition.

In standard C, you are not allowed to leave the variable argument out entirely; but you are allowed to pass an empty argument. For example, this invocation is invalid in ISO C, because there is no comma after the string:

debug ("A message")

GNU CPP permits you to completely omit the variable arguments in this way. In the above examples, the compiler would complain, though since the expansion of the macro still has the extra comma after the format string.

To help solve this problem, CPP behaves specially for variable arguments used with the token paste operator, ##. If instead you write

#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)

and if the variable arguments are omitted or empty, the ## operator causes the preprocessor to remove the comma before it. If you do provide some variable arguments in your macro invocation, GNU CPP does not complain about the paste operation and instead places the variable arguments after the comma. Just like any other pasted macro argument, these arguments are not macro expanded.


Using the GNU Compiler Collection (GCC)

Node:VAX Options, Next:SPARC Options, Previous:M68hc1x Options, Up:Submodel Options

VAX Options

These -m options are defined for the VAX:

-munix
Do not output certain jump instructions (aobleq and so on) that the Unix assembler for the VAX cannot handle across long ranges.
-mgnu
Do output those jump instructions, on the assumption that you will assemble with the GNU assembler.
-mg
Output code for g-format floating point numbers instead of d-format.


Using the GNU Compiler Collection (GCC)

Node:Vector Extensions, Next:Other Builtins, Previous:Return Address, Up:C Extensions

Using vector instructions through built-in functions

On some targets, the instruction set contains SIMD vector instructions that operate on multiple values contained in one large register at the same time. For example, on the i386 the MMX, 3Dnow! and SSE extensions can be used this way.

The first step in using these extensions is to provide the necessary data types. This should be done using an appropriate typedef:

typedef int v4si __attribute__ ((mode(V4SI)));

The base type int is effectively ignored by the compiler, the actual properties of the new type v4si are defined by the __attribute__. It defines the machine mode to be used; for vector types these have the form VnB; n should be the number of elements in the vector, and B should be the base mode of the individual elements. The following can be used as base modes:

QI
An integer that is as wide as the smallest addressable unit, usually 8 bits.
HI
An integer, twice as wide as a QI mode integer, usually 16 bits.
SI
An integer, four times as wide as a QI mode integer, usually 32 bits.
DI
An integer, eight times as wide as a QI mode integer, usually 64 bits.
SF
A floating point value, as wide as a SI mode integer, usually 32 bits.
DF
A floating point value, as wide as a DI mode integer, usually 64 bits.

Not all base types or combinations are always valid; which modes can be used is determined by the target machine. For example, if targetting the i386 MMX extensions, only V8QI, V4HI and V2SI are allowed modes.

There are no V1xx vector modes - they would be identical to the corresponding base mode.

There is no distinction between signed and unsigned vector modes. This distinction is made by the operations that perform on the vectors, not by the data type.

The types defined in this manner are somewhat special, they cannot be used with most normal C operations (i.e., a vector addition can not be represented by a normal addition of two vector type variables). You can declare only variables and use them in function calls and returns, as well as in assignments and some casts. It is possible to cast from one vector type to another, provided they are of the same size (in fact, you can also cast vectors to and from other datatypes of the same size).

A port that supports vector operations provides a set of built-in functions that can be used to operate on vectors. For example, a function to add two vectors and multiply the result by a third could look like this:

v4si f (v4si a, v4si b, v4si c)
{
  v4si tmp = __builtin_addv4si (a, b);
  return __builtin_mulv4si (tmp, c);
}


Using the GNU Compiler Collection (GCC)

Node:VMS Misc, Previous:Global Declarations, Up:VMS

Other VMS Issues

GCC automatically arranges for main to return 1 by default if you fail to specify an explicit return value. This will be interpreted by VMS as a status code indicating a normal successful completion. Version 1 of GCC did not provide this default.

GCC on VMS works only with the GNU assembler, GAS. You need version 1.37 or later of GAS in order to produce value debugging information for the VMS debugger. Use the ordinary VMS linker with the object files produced by GAS.

Under previous versions of GCC, the generated code would occasionally give strange results when linked to the sharable VAXCRTL library. Now this should work.

A caveat for use of const global variables: the const modifier must be specified in every external declaration of the variable in all of the source files that use that variable. Otherwise the linker will issue warnings about conflicting attributes for the variable. Your program will still work despite the warnings, but the variable will be placed in writable storage.

Although the VMS linker does distinguish between upper and lower case letters in global symbols, most VMS compilers convert all such symbols into upper case and most run-time library routines also have upper case names. To be able to reliably call such routines, GCC (by means of the assembler GAS) converts global symbols into upper case like other VMS compilers. However, since the usual practice in C is to distinguish case, GCC (via GAS) tries to preserve usual C behavior by augmenting each name that is not all lower case. This means truncating the name to at most 23 characters and then adding more characters at the end which encode the case pattern of those 23. Names which contain at least one dollar sign are an exception; they are converted directly into upper case without augmentation.

Name augmentation yields bad results for programs that use precompiled libraries (such as Xlib) which were generated by another compiler. You can use the compiler option /NOCASE_HACK to inhibit augmentation; it makes external C functions and variables case-independent as is usual on VMS. Alternatively, you could write all references to the functions and variables in such libraries using lower case; this will work on VMS, but is not portable to other systems. The compiler option /NAMES also provides control over global name handling.

Function and variable names are handled somewhat differently with G++. The GNU C++ compiler performs name mangling on function names, which means that it adds information to the function name to describe the data types of the arguments that the function takes. One result of this is that the name of a function can become very long. Since the VMS linker only recognizes the first 31 characters in a name, special action is taken to ensure that each function and variable has a unique name that can be represented in 31 characters.

If the name (plus a name augmentation, if required) is less than 32 characters in length, then no special action is performed. If the name is longer than 31 characters, the assembler (GAS) will generate a hash string based upon the function name, truncate the function name to 23 characters, and append the hash string to the truncated name. If the /VERBOSE compiler option is used, the assembler will print both the full and truncated names of each symbol that is truncated.

The /NOCASE_HACK compiler option should not be used when you are compiling programs that use libg++. libg++ has several instances of objects (i.e. Filebuf and filebuf) which become indistinguishable in a case-insensitive environment. This leads to cases where you need to inhibit augmentation selectively (if you were using libg++ and Xlib in the same program, for example). There is no special feature for doing this, but you can get the result by defining a macro for each mixed case symbol for which you wish to inhibit augmentation. The macro should expand into the lower case equivalent of itself. For example:

#define StuDlyCapS studlycaps

These macro definitions can be placed in a header file to minimize the number of changes to your source code.


Using the GNU Compiler Collection (GCC)

Node:VMS, Next:Funding, Previous:Contributing, Up:Top

Using GCC on VMS

Here is how to use GCC on VMS.

  • Include Files and VMS: Where the preprocessor looks for the include files.
  • Global Declarations: How to do globaldef, globalref and globalvalue with GCC.
  • VMS Misc: Misc information.


Using the GNU Compiler Collection (GCC)

Node:Volatiles, Next:Restricted Pointers, Previous:Min and Max, Up:C++ Extensions

When is a Volatile Object Accessed?

Both the C and C++ standard have the concept of volatile objects. These are normally accessed by pointers and used for accessing hardware. The standards encourage compilers to refrain from optimizations concerning accesses to volatile objects that it might perform on non-volatile objects. The C standard leaves it implementation defined as to what constitutes a volatile access. The C++ standard omits to specify this, except to say that C++ should behave in a similar manner to C with respect to volatiles, where possible. The minimum either standard specifies is that at a sequence point all previous accesses to volatile objects have stabilized and no subsequent accesses have occurred. Thus an implementation is free to reorder and combine volatile accesses which occur between sequence points, but cannot do so for accesses across a sequence point. The use of volatiles does not allow you to violate the restriction on updating objects multiple times within a sequence point.

In most expressions, it is intuitively obvious what is a read and what is a write. For instance

volatile int *dst = somevalue;
volatile int *src = someothervalue;
*dst = *src;

will cause a read of the volatile object pointed to by src and stores the value into the volatile object pointed to by dst. There is no guarantee that these reads and writes are atomic, especially for objects larger than int.

Less obvious expressions are where something which looks like an access is used in a void context. An example would be,

volatile int *src = somevalue;
*src;

With C, such expressions are rvalues, and as rvalues cause a read of the object, GCC interprets this as a read of the volatile being pointed to. The C++ standard specifies that such expressions do not undergo lvalue to rvalue conversion, and that the type of the dereferenced object may be incomplete. The C++ standard does not specify explicitly that it is this lvalue to rvalue conversion which is responsible for causing an access. However, there is reason to believe that it is, because otherwise certain simple expressions become undefined. However, because it would surprise most programmers, G++ treats dereferencing a pointer to volatile object of complete type in a void context as a read of the object. When the object has incomplete type, G++ issues a warning.

struct S;
struct T {int m;};
volatile S *ptr1 = somevalue;
volatile T *ptr2 = somevalue;
*ptr1;
*ptr2;

In this example, a warning is issued for *ptr1, and *ptr2 causes a read of the object pointed to. If you wish to force an error on the first case, you must force a conversion to rvalue with, for instance a static cast, static_cast<S>(*ptr1).

When using a reference to volatile, G++ does not treat equivalent expressions as accesses to volatiles, but instead issues a warning that no volatile is accessed. The rationale for this is that otherwise it becomes difficult to determine where volatile access occur, and not possible to ignore the return value from functions returning volatile references. Again, if you wish to force a read, cast the reference to an rvalue.


Using the GNU Compiler Collection (GCC)

Node:Warning Options, Next:Debugging Options, Previous:Language Independent Options, Up:Invoking GCC

Options to Request or Suppress Warnings

Warnings are diagnostic messages that report constructions which are not inherently erroneous but which are risky or suggest there may have been an error.

You can request many specific warnings with options beginning -W, for example -Wimplicit to request warnings on implicit declarations. Each of these specific warning options also has a negative form beginning -Wno- to turn off warnings; for example, -Wno-implicit. This manual lists only one of the two forms, whichever is not the default.

The following options control the amount and kinds of warnings produced by GCC; for further, language-specific options also refer to C++ Dialect Options and Objective-C Dialect Options.

-fsyntax-only
Check the code for syntax errors, but don't do anything beyond that.
-pedantic
Issue all the warnings demanded by strict ISO C and ISO C++; reject all programs that use forbidden extensions, and some other programs that do not follow ISO C and ISO C++. For ISO C, follows the version of the ISO C standard specified by any -std option used.

Valid ISO C and ISO C++ programs should compile properly with or without this option (though a rare few will require -ansi or a -std option specifying the required version of ISO C). However, without this option, certain GNU extensions and traditional C and C++ features are supported as well. With this option, they are rejected.

-pedantic does not cause warning messages for use of the alternate keywords whose names begin and end with __. Pedantic warnings are also disabled in the expression that follows __extension__. However, only system header files should use these escape routes; application programs should avoid them. See Alternate Keywords.

Some users try to use -pedantic to check programs for strict ISO C conformance. They soon find that it does not do quite what they want: it finds some non-ISO practices, but not all--only those for which ISO C requires a diagnostic, and some others for which diagnostics have been added.

A feature to report any failure to conform to ISO C might be useful in some instances, but would require considerable additional work and would be quite different from -pedantic. We don't have plans to support such a feature in the near future.

Where the standard specified with -std represents a GNU extended dialect of C, such as gnu89 or gnu99, there is a corresponding base standard, the version of ISO C on which the GNU extended dialect is based. Warnings from -pedantic are given where they are required by the base standard. (It would not make sense for such warnings to be given only for features not in the specified GNU C dialect, since by definition the GNU dialects of C include all features the compiler supports with the given option, and there would be nothing to warn about.)

-pedantic-errors
Like -pedantic, except that errors are produced rather than warnings.
-w
Inhibit all warning messages.
-Wno-import
Inhibit warning messages about the use of #import.
-Wchar-subscripts
Warn if an array subscript has type char. This is a common cause of error, as programmers often forget that this type is signed on some machines.
-Wcomment
Warn whenever a comment-start sequence /* appears in a /* comment, or whenever a Backslash-Newline appears in a // comment.
-Wformat
Check calls to printf and scanf, etc., to make sure that the arguments supplied have types appropriate to the format string specified, and that the conversions specified in the format string make sense. This includes standard functions, and others specified by format attributes (see Function Attributes), in the printf, scanf, strftime and strfmon (an X/Open extension, not in the C standard) families.

The formats are checked against the format features supported by GNU libc version 2.2. These include all ISO C89 and C99 features, as well as features from the Single Unix Specification and some BSD and GNU extensions. Other library implementations may not support all these features; GCC does not support warning about features that go beyond a particular library's limitations. However, if -pedantic is used with -Wformat, warnings will be given about format features not in the selected standard version (but not for strfmon formats, since those are not in any version of the C standard). See Options Controlling C Dialect.

-Wformat is included in -Wall. For more control over some aspects of format checking, the options -Wno-format-y2k, -Wno-format-extra-args, -Wformat-nonliteral, -Wformat-security and -Wformat=2 are available, but are not included in -Wall.

-Wno-format-y2k
If -Wformat is specified, do not warn about strftime formats which may yield only a two-digit year.
-Wno-format-extra-args
If -Wformat is specified, do not warn about excess arguments to a printf or scanf format function. The C standard specifies that such arguments are ignored.

Where the unused arguments lie between used arguments that are specified with $ operand number specifications, normally warnings are still given, since the implementation could not know what type to pass to va_arg to skip the unused arguments. However, in the case of scanf formats, this option will suppress the warning if the unused arguments are all pointers, since the Single Unix Specification says that such unused arguments are allowed.

-Wformat-nonliteral
If -Wformat is specified, also warn if the format string is not a string literal and so cannot be checked, unless the format function takes its format arguments as a va_list.
-Wformat-security
If -Wformat is specified, also warn about uses of format functions that represent possible security problems. At present, this warns about calls to printf and scanf functions where the format string is not a string literal and there are no format arguments, as in printf (foo);. This may be a security hole if the format string came from untrusted input and contains %n. (This is currently a subset of what -Wformat-nonliteral warns about, but in future warnings may be added to -Wformat-security that are not included in -Wformat-nonliteral.)
-Wformat=2
Enable -Wformat plus format checks not included in -Wformat. Currently equivalent to -Wformat -Wformat-nonliteral -Wformat-security.
-Wimplicit-int
Warn when a declaration does not specify a type.
-Wimplicit-function-declaration
-Werror-implicit-function-declaration
Give a warning (or error) whenever a function is used before being declared.
-Wimplicit
Same as -Wimplicit-int and -Wimplicit-function-declaration.
-Wmain
Warn if the type of main is suspicious. main should be a function with external linkage, returning int, taking either zero arguments, two, or three arguments of appropriate types.
-Wmissing-braces
Warn if an aggregate or union initializer is not fully bracketed. In the following example, the initializer for a is not fully bracketed, but that for b is fully bracketed.
int a[2][2] = { 0, 1, 2, 3 };
int b[2][2] = { { 0, 1 }, { 2, 3 } };

-Wparentheses
Warn if parentheses are omitted in certain contexts, such as when there is an assignment in a context where a truth value is expected, or when operators are nested whose precedence people often get confused about.

Also warn about constructions where there may be confusion to which if statement an else branch belongs. Here is an example of such a case:

{
  if (a)
    if (b)
      foo ();
  else
    bar ();
}

In C, every else branch belongs to the innermost possible if statement, which in this example is if (b). This is often not what the programmer expected, as illustrated in the above example by indentation the programmer chose. When there is the potential for this confusion, GCC will issue a warning when this flag is specified. To eliminate the warning, add explicit braces around the innermost if statement so there is no way the else could belong to the enclosing if. The resulting code would look like this:

{
  if (a)
    {
      if (b)
        foo ();
      else
        bar ();
    }
}

-Wsequence-point
Warn about code that may have undefined semantics because of violations of sequence point rules in the C standard.

The C standard defines the order in which expressions in a C program are evaluated in terms of sequence points, which represent a partial ordering between the execution of parts of the program: those executed before the sequence point, and those executed after it. These occur after the evaluation of a full expression (one which is not part of a larger expression), after the evaluation of the first operand of a &&, ||, ? : or , (comma) operator, before a function is called (but after the evaluation of its arguments and the expression denoting the called function), and in certain other places. Other than as expressed by the sequence point rules, the order of evaluation of subexpressions of an expression is not specified. All these rules describe only a partial order rather than a total order, since, for example, if two functions are called within one expression with no sequence point between them, the order in which the functions are called is not specified. However, the standards committee have ruled that function calls do not overlap.

It is not specified when between sequence points modifications to the values of objects take effect. Programs whose behavior depends on this have undefined behavior; the C standard specifies that "Between the previous and next sequence point an object shall have its stored value modified at most once by the evaluation of an expression. Furthermore, the prior value shall be read only to determine the value to be stored.". If a program breaks these rules, the results on any particular implementation are entirely unpredictable.

Examples of code with undefined behavior are a = a++;, a[n] = b[n++] and a[i++] = i;. Some more complicated cases are not diagnosed by this option, and it may give an occasional false positive result, but in general it has been found fairly effective at detecting this sort of problem in programs.

The present implementation of this option only works for C programs. A future implementation may also work for C++ programs.

The C standard is worded confusingly, therefore there is some debate over the precise meaning of the sequence point rules in subtle cases. Links to discussions of the problem, including proposed formal definitions, may be found on our readings page, at http://gcc.gnu.org/readings.html.

-Wreturn-type
Warn whenever a function is defined with a return-type that defaults to int. Also warn about any return statement with no return-value in a function whose return-type is not void.

For C++, a function without return type always produces a diagnostic message, even when -Wno-return-type is specified. The only exceptions are main and functions defined in system headers.

-Wswitch
Warn whenever a switch statement has an index of enumeral type and lacks a case for one or more of the named codes of that enumeration. (The presence of a default label prevents this warning.) case labels outside the enumeration range also provoke warnings when this option is used.
-Wtrigraphs
Warn if any trigraphs are encountered that might change the meaning of the program (trigraphs within comments are not warned about).
-Wunused-function
Warn whenever a static function is declared but not defined or a non\-inline static function is unused.
-Wunused-label
Warn whenever a label is declared but not used.

To suppress this warning use the unused attribute (see Variable Attributes).

-Wunused-parameter
Warn whenever a function parameter is unused aside from its declaration.

To suppress this warning use the unused attribute (see Variable Attributes).

-Wunused-variable
Warn whenever a local variable or non-constant static variable is unused aside from its declaration

To suppress this warning use the unused attribute (see Variable Attributes).

-Wunused-value
Warn whenever a statement computes a result that is explicitly not used.

To suppress this warning cast the expression to void.

-Wunused
All all the above -Wunused options combined.

In order to get a warning about an unused function parameter, you must either specify -W -Wunused or separately specify -Wunused-parameter.

-Wuninitialized
Warn if an automatic variable is used without first being initialized or if a variable may be clobbered by a setjmp call.

These warnings are possible only in optimizing compilation, because they require data flow information that is computed only when optimizing. If you don't specify -O, you simply won't get these warnings.

These warnings occur only for variables that are candidates for register allocation. Therefore, they do not occur for a variable that is declared volatile, or whose address is taken, or whose size is other than 1, 2, 4 or 8 bytes. Also, they do not occur for structures, unions or arrays, even when they are in registers.

Note that there may be no warning about a variable that is used only to compute a value that itself is never used, because such computations may be deleted by data flow analysis before the warnings are printed.

These warnings are made optional because GCC is not smart enough to see all the reasons why the code might be correct despite appearing to have an error. Here is one example of how this can happen:

{
  int x;
  switch (y)
    {
    case 1: x = 1;
      break;
    case 2: x = 4;
      break;
    case 3: x = 5;
    }
  foo (x);
}

If the value of y is always 1, 2 or 3, then x is always initialized, but GCC doesn't know this. Here is another common case:

{
  int save_y;
  if (change_y) save_y = y, y = new_y;
  ...
  if (change_y) y = save_y;
}

This has no bug because save_y is used only if it is set.

This option also warns when a non-volatile automatic variable might be changed by a call to longjmp. These warnings as well are possible only in optimizing compilation.

The compiler sees only the calls to setjmp. It cannot know where longjmp will be called; in fact, a signal handler could call it at any point in the code. As a result, you may get a warning even when there is in fact no problem because longjmp cannot in fact be called at the place which would cause a problem.

Some spurious warnings can be avoided if you declare all the functions you use that never return as noreturn. See Function Attributes.

-Wreorder (C++ only)
Warn when the order of member initializers given in the code does not match the order in which they must be executed. For instance:
-Wunknown-pragmas
Warn when a #pragma directive is encountered which is not understood by GCC. If this command line option is used, warnings will even be issued for unknown pragmas in system header files. This is not the case if the warnings were only enabled by the -Wall command line option.
-Wall
All of the above -W options combined. This enables all the warnings about constructions that some users consider questionable, and that are easy to avoid (or modify to prevent the warning), even in conjunction with macros.
-Wdiv-by-zero
Warn about compile-time integer division by zero. This is default. To inhibit the warning messages, use -Wno-div-by-zero. Floating point division by zero is not warned about, as it can be a legitimate way of obtaining infinities and NaNs.
-Wmultichar
Warn if a multicharacter constant ('FOOF') is used. This is default. To inhibit the warning messages, use -Wno-multichar. Usually they indicate a typo in the user's code, as they have implementation-defined values, and should not be used in portable code.
-Wsystem-headers
Print warning messages for constructs found in system header files. Warnings from system headers are normally suppressed, on the assumption that they usually do not indicate real problems and would only make the compiler output harder to read. Using this command line option tells GCC to emit warnings from system headers as if they occurred in user code. However, note that using -Wall in conjunction with this option will not warn about unknown pragmas in system headers--for that, -Wunknown-pragmas must also be used.

The following -W... options are not implied by -Wall. Some of them warn about constructions that users generally do not consider questionable, but which occasionally you might wish to check for; others warn about constructions that are necessary or hard to avoid in some cases, and there is no simple way to modify the code to suppress the warning.

-W
Print extra warning messages for these events:
  • A function can return either with or without a value. (Falling off the end of the function body is considered returning without a value.) For example, this function would evoke such a warning:
    foo (a)
{
  if (a > 0)
    return a;
}
  • An expression-statement or the left-hand side of a comma expression contains no side effects. To suppress the warning, cast the unused expression to void. For example, an expression such as x[i,j] will cause a warning, but x[(void)i,j] will not.
  • An unsigned value is compared against zero with < or <=.
  • A comparison like x<=y<=z appears; this is equivalent to (x<=y ? 1 : 0) <= z, which is a different interpretation from that of ordinary mathematical notation.
  • Storage-class specifiers like static are not the first things in a declaration. According to the C Standard, this usage is obsolescent.
  • The return type of a function has a type qualifier such as const. Such a type qualifier has no effect, since the value returned by a function is not an lvalue. (But don't warn about the GNU extension of volatile void return types. That extension will be warned about if -pedantic is specified.)
  • If -Wall or -Wunused is also specified, warn about unused arguments.
  • A comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned. (But don't warn if -Wno-sign-compare is also specified.)
  • An aggregate has a partly bracketed initializer. For example, the following code would evoke such a warning, because braces are missing around the initializer for x.h:
    struct s { int f, g; };
struct t { struct s h; int i; };
struct t x = { 1, 2, 3 };
  • An aggregate has an initializer which does not initialize all members. For example, the following code would cause such a warning, because x.h would be implicitly initialized to zero:
    struct s { int f, g, h; };
struct s x = { 3, 4 };

-Wfloat-equal
Warn if floating point values are used in equality comparisons.

The idea behind this is that sometimes it is convenient (for the programmer) to consider floating-point values as approximations to infinitely precise real numbers. If you are doing this, then you need to compute (by analysing the code, or in some other way) the maximum or likely maximum error that the computation introduces, and allow for it when performing comparisons (and when producing output, but that's a different problem). In particular, instead of testing for equality, you would check to see whether the two values have ranges that overlap; and this is done with the relational operators, so equality comparisons are probably mistaken.

-Wtraditional (C only)
Warn about certain constructs that behave differently in traditional and ISO C. Also warn about ISO C constructs that have no traditional C equivalent, and/or problematic constructs which should be avoided.
  • Macro parameters that appear within string literals in the macro body. In traditional C macro replacement takes place within string literals, but does not in ISO C.
  • In traditional C, some preprocessor directives did not exist. Traditional preprocessors would only consider a line to be a directive if the # appeared in column 1 on the line. Therefore -Wtraditional warns about directives that traditional C understands but would ignore because the # does not appear as the first character on the line. It also suggests you hide directives like #pragma not understood by traditional C by indenting them. Some traditional implementations would not recognize #elif, so it suggests avoiding it altogether.
  • A function-like macro that appears without arguments.
  • The unary plus operator.
  • The U integer constant suffix, or the F or L floating point constant suffixes. (Traditional C does support the L suffix on integer constants.) Note, these suffixes appear in macros defined in the system headers of most modern systems, e.g. the _MIN/_MAX macros in <limits.h>. Use of these macros in user code might normally lead to spurious warnings, however gcc's integrated preprocessor has enough context to avoid warning in these cases.
  • A function declared external in one block and then used after the end of the block.
  • A switch statement has an operand of type long.
  • A non-static function declaration follows a static one. This construct is not accepted by some traditional C compilers.
  • The ISO type of an integer constant has a different width or signedness from its traditional type. This warning is only issued if the base of the constant is ten. I.e. hexadecimal or octal values, which typically represent bit patterns, are not warned about.
  • Usage of ISO string concatenation is detected.
  • Initialization of automatic aggregates.
  • Identifier conflicts with labels. Traditional C lacks a separate namespace for labels.
  • Initialization of unions. If the initializer is zero, the warning is omitted. This is done under the assumption that the zero initializer in user code appears conditioned on e.g. __STDC__ to avoid missing initializer warnings and relies on default initialization to zero in the traditional C case.
  • Conversions by prototypes between fixed/floating point values and vice versa. The absence of these prototypes when compiling with traditional C would cause serious problems. This is a subset of the possible conversion warnings, for the full set use -Wconversion.

-Wundef
Warn if an undefined identifier is evaluated in an #if directive.
-Wshadow
Warn whenever a local variable shadows another local variable, parameter or global variable or whenever a built-in function is shadowed.
-Wlarger-than-len
Warn whenever an object of larger than len bytes is defined.
-Wpointer-arith
Warn about anything that depends on the "size of" a function type or of void. GNU C assigns these types a size of 1, for convenience in calculations with void * pointers and pointers to functions.
-Wbad-function-cast (C only)
Warn whenever a function call is cast to a non-matching type. For example, warn if int malloc() is cast to anything *.
-Wcast-qual
Warn whenever a pointer is cast so as to remove a type qualifier from the target type. For example, warn if a const char * is cast to an ordinary char *.
-Wcast-align
Warn whenever a pointer is cast such that the required alignment of the target is increased. For example, warn if a char * is cast to an int * on machines where integers can only be accessed at two- or four-byte boundaries.
-Wwrite-strings
When compiling C, give string constants the type const char[length] so that copying the address of one into a non-const char * pointer will get a warning; when compiling C++, warn about the deprecated conversion from string constants to char *. These warnings will help you find at compile time code that can try to write into a string constant, but only if you have been very careful about using const in declarations and prototypes. Otherwise, it will just be a nuisance; this is why we did not make -Wall request these warnings.
-Wconversion
Warn if a prototype causes a type conversion that is different from what would happen to the same argument in the absence of a prototype. This includes conversions of fixed point to floating and vice versa, and conversions changing the width or signedness of a fixed point argument except when the same as the default promotion.

Also, warn if a negative integer constant expression is implicitly converted to an unsigned type. For example, warn about the assignment x = -1 if x is unsigned. But do not warn about explicit casts like (unsigned) -1.

-Wsign-compare
Warn when a comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned. This warning is also enabled by -W; to get the other warnings of -W without this warning, use -W -Wno-sign-compare.
-Waggregate-return
Warn if any functions that return structures or unions are defined or called. (In languages where you can return an array, this also elicits a warning.)
-Wstrict-prototypes (C only)
Warn if a function is declared or defined without specifying the argument types. (An old-style function definition is permitted without a warning if preceded by a declaration which specifies the argument types.)
-Wmissing-prototypes (C only)
Warn if a global function is defined without a previous prototype declaration. This warning is issued even if the definition itself provides a prototype. The aim is to detect global functions that fail to be declared in header files.
-Wmissing-declarations
Warn if a global function is defined without a previous declaration. Do so even if the definition itself provides a prototype. Use this option to detect global functions that are not declared in header files.
-Wmissing-noreturn
Warn about functions which might be candidates for attribute noreturn. Note these are only possible candidates, not absolute ones. Care should be taken to manually verify functions actually do not ever return before adding the noreturn attribute, otherwise subtle code generation bugs could be introduced. You will not get a warning for main in hosted C environments.
-Wmissing-format-attribute
If -Wformat is enabled, also warn about functions which might be candidates for format attributes. Note these are only possible candidates, not absolute ones. GCC will guess that format attributes might be appropriate for any function that calls a function like vprintf or vscanf, but this might not always be the case, and some functions for which format attributes are appropriate may not be detected. This option has no effect unless -Wformat is enabled (possibly by -Wall).
-Wno-deprecated-declarations
Do not warn about uses of functions, variables, and types marked as deprecated by using the deprecated attribute. (see Function Attributes, see Variable Attributes, see Type Attributes.)
-Wpacked
Warn if a structure is given the packed attribute, but the packed attribute has no effect on the layout or size of the structure. Such structures may be mis-aligned for little benefit. For instance, in this code, the variable f.x in struct bar will be misaligned even though struct bar does not itself have the packed attribute:
struct foo {
  int x;
  char a, b, c, d;
} __attribute__((packed));
struct bar {
  char z;
  struct foo f;
};

-Wpadded
Warn if padding is included in a structure, either to align an element of the structure or to align the whole structure. Sometimes when this happens it is possible to rearrange the fields of the structure to reduce the padding and so make the structure smaller.
-Wredundant-decls
Warn if anything is declared more than once in the same scope, even in cases where multiple declaration is valid and changes nothing.
-Wnested-externs (C only)
Warn if an extern declaration is encountered within a function.
-Wunreachable-code
Warn if the compiler detects that code will never be executed.

This option is intended to warn when the compiler detects that at least a whole line of source code will never be executed, because some condition is never satisfied or because it is after a procedure that never returns.

It is possible for this option to produce a warning even though there are circumstances under which part of the affected line can be executed, so care should be taken when removing apparently-unreachable code.

For instance, when a function is inlined, a warning may mean that the line is unreachable in only one inlined copy of the function.

This option is not made part of -Wall because in a debugging version of a program there is often substantial code which checks correct functioning of the program and is, hopefully, unreachable because the program does work. Another common use of unreachable code is to provide behavior which is selectable at compile-time.

-Winline
Warn if a function can not be inlined and it was declared as inline.
-Wlong-long
Warn if long long type is used. This is default. To inhibit the warning messages, use -Wno-long-long. Flags -Wlong-long and -Wno-long-long are taken into account only when -pedantic flag is used.
-Wdisabled-optimization
Warn if a requested optimization pass is disabled. This warning does not generally indicate that there is anything wrong with your code; it merely indicates that GCC's optimizers were unable to handle the code effectively. Often, the problem is that your code is too big or too complex; GCC will refuse to optimize programs when the optimization itself is likely to take inordinate amounts of time.
-Werror
Make all warnings into errors.


Using the GNU Compiler Collection (GCC)

Node:Warnings and Errors, Previous:Non-bugs, Up:Trouble

Warning Messages and Error Messages

The GNU compiler can produce two kinds of diagnostics: errors and warnings. Each kind has a different purpose:

  • Errors report problems that make it impossible to compile your program. GCC reports errors with the source file name and line number where the problem is apparent.
  • Warnings report other unusual conditions in your code that may indicate a problem, although compilation can (and does) proceed. Warning messages also report the source file name and line number, but include the text warning: to distinguish them from error messages.

Warnings may indicate danger points where you should check to make sure that your program really does what you intend; or the use of obsolete features; or the use of nonstandard features of GNU C or C++. Many warnings are issued only if you ask for them, with one of the -W options (for instance, -Wall requests a variety of useful warnings).

GCC always tries to compile your program if possible; it never gratuitously rejects a program whose meaning is clear merely because (for instance) it fails to conform to a standard. In some cases, however, the C and C++ standards specify that certain extensions are forbidden, and a diagnostic must be issued by a conforming compiler. The -pedantic option tells GCC to issue warnings in such cases; -pedantic-errors says to make them errors instead. This does not mean that all non-ISO constructs get warnings or errors.

See Options to Request or Suppress Warnings, for more detail on these and related command-line options.


Using the GNU Compiler Collection (GCC)

Node:What you can and what you cannot do in +load, Previous:Executing code before main, Up:Executing code before main

What you can and what you cannot do in +load

The +load implementation in the GNU runtime guarantees you the following things:

  • you can write whatever C code you like;
  • you can send messages to Objective-C constant strings (@"this is a constant string");
  • you can allocate and send messages to objects whose class is implemented in the same file;
  • the +load implementation of all super classes of a class are executed before the +load of that class is executed;
  • the +load implementation of a class is executed before the +load implementation of any category.

In particular, the following things, even if they can work in a particular case, are not guaranteed:

  • allocation of or sending messages to arbitrary objects;
  • allocation of or sending messages to objects whose classes have a category implemented in the same file;

You should make no assumptions about receiving +load in sibling classes when you write +load of a class. The order in which sibling classes receive +load is not guaranteed.

The order in which +load and +initialize are called could be problematic if this matters. If you don't allocate objects inside +load, it is guaranteed that +load is called before +initialize. If you create an object inside +load the +initialize method of object's class is invoked even if +load was not invoked. Note if you explicitly call +load on a class, +initialize will be called first. To avoid possible problems try to implement only one of these methods.

The +load method is also invoked when a bundle is dynamically loaded into your running program. This happens automatically without any intervening operation from you. When you write bundles and you need to write +load you can safely create and send messages to objects whose classes already exist in the running program. The same restrictions as above apply to classes defined in bundle.


Using the GNU Compiler Collection (GCC)

Node:X86 Built-in Functions, Next:PowerPC AltiVec Built-in Functions, Up:Target Builtins

X86 Built-in Functions

These built-in functions are available for the i386 and x86-64 family of computers, depending on the command-line switches used.

The following machine modes are available for use with MMX built-in functions (see Vector Extensions): V2SI for a vector of two 32-bit integers, V4HI for a vector of four 16-bit integers, and V8QI for a vector of eight 8-bit integers. Some of the built-in functions operate on MMX registers as a whole 64-bit entity, these use DI as their mode.

If 3Dnow extensions are enabled, V2SF is used as a mode for a vector of two 32-bit floating point values.

If SSE extensions are enabled, V4SF is used for a vector of four 32-bit floating point values. Some instructions use a vector of four 32-bit integers, these use V4SI. Finally, some instructions operate on an entire vector register, interpreting it as a 128-bit integer, these use mode TI.

The following built-in functions are made available by -mmmx. All of them generate the machine instruction that is part of the name.

v8qi __builtin_ia32_paddb (v8qi, v8qi)
v4hi __builtin_ia32_paddw (v4hi, v4hi)
v2si __builtin_ia32_paddd (v2si, v2si)
v8qi __builtin_ia32_psubb (v8qi, v8qi)
v4hi __builtin_ia32_psubw (v4hi, v4hi)
v2si __builtin_ia32_psubd (v2si, v2si)
v8qi __builtin_ia32_paddsb (v8qi, v8qi)
v4hi __builtin_ia32_paddsw (v4hi, v4hi)
v8qi __builtin_ia32_psubsb (v8qi, v8qi)
v4hi __builtin_ia32_psubsw (v4hi, v4hi)
v8qi __builtin_ia32_paddusb (v8qi, v8qi)
v4hi __builtin_ia32_paddusw (v4hi, v4hi)
v8qi __builtin_ia32_psubusb (v8qi, v8qi)
v4hi __builtin_ia32_psubusw (v4hi, v4hi)
v4hi __builtin_ia32_pmullw (v4hi, v4hi)
v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
di __builtin_ia32_pand (di, di)
di __builtin_ia32_pandn (di,di)
di __builtin_ia32_por (di, di)
di __builtin_ia32_pxor (di, di)
v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
v2si __builtin_ia32_pcmpeqd (v2si, v2si)
v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
v2si __builtin_ia32_pcmpgtd (v2si, v2si)
v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
v2si __builtin_ia32_punpckhdq (v2si, v2si)
v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
v2si __builtin_ia32_punpckldq (v2si, v2si)
v8qi __builtin_ia32_packsswb (v4hi, v4hi)
v4hi __builtin_ia32_packssdw (v2si, v2si)
v8qi __builtin_ia32_packuswb (v4hi, v4hi)

The following built-in functions are made available either with -msse, or with a combination of -m3dnow and -march=athlon. All of them generate the machine instruction that is part of the name.

v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
v8qi __builtin_ia32_pavgb (v8qi, v8qi)
v4hi __builtin_ia32_pavgw (v4hi, v4hi)
v4hi __builtin_ia32_psadbw (v8qi, v8qi)
v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
v8qi __builtin_ia32_pminub (v8qi, v8qi)
v4hi __builtin_ia32_pminsw (v4hi, v4hi)
int __builtin_ia32_pextrw (v4hi, int)
v4hi __builtin_ia32_pinsrw (v4hi, int, int)
int __builtin_ia32_pmovmskb (v8qi)
void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
void __builtin_ia32_movntq (di *, di)
void __builtin_ia32_sfence (void)

The following built-in functions are available when -msse is used. All of them generate the machine instruction that is part of the name.

int __builtin_ia32_comieq (v4sf, v4sf)
int __builtin_ia32_comineq (v4sf, v4sf)
int __builtin_ia32_comilt (v4sf, v4sf)
int __builtin_ia32_comile (v4sf, v4sf)
int __builtin_ia32_comigt (v4sf, v4sf)
int __builtin_ia32_comige (v4sf, v4sf)
int __builtin_ia32_ucomieq (v4sf, v4sf)
int __builtin_ia32_ucomineq (v4sf, v4sf)
int __builtin_ia32_ucomilt (v4sf, v4sf)
int __builtin_ia32_ucomile (v4sf, v4sf)
int __builtin_ia32_ucomigt (v4sf, v4sf)
int __builtin_ia32_ucomige (v4sf, v4sf)
v4sf __builtin_ia32_addps (v4sf, v4sf)
v4sf __builtin_ia32_subps (v4sf, v4sf)
v4sf __builtin_ia32_mulps (v4sf, v4sf)
v4sf __builtin_ia32_divps (v4sf, v4sf)
v4sf __builtin_ia32_addss (v4sf, v4sf)
v4sf __builtin_ia32_subss (v4sf, v4sf)
v4sf __builtin_ia32_mulss (v4sf, v4sf)
v4sf __builtin_ia32_divss (v4sf, v4sf)
v4si __builtin_ia32_cmpeqps (v4sf, v4sf)
v4si __builtin_ia32_cmpltps (v4sf, v4sf)
v4si __builtin_ia32_cmpleps (v4sf, v4sf)
v4si __builtin_ia32_cmpgtps (v4sf, v4sf)
v4si __builtin_ia32_cmpgeps (v4sf, v4sf)
v4si __builtin_ia32_cmpunordps (v4sf, v4sf)
v4si __builtin_ia32_cmpneqps (v4sf, v4sf)
v4si __builtin_ia32_cmpnltps (v4sf, v4sf)
v4si __builtin_ia32_cmpnleps (v4sf, v4sf)
v4si __builtin_ia32_cmpngtps (v4sf, v4sf)
v4si __builtin_ia32_cmpngeps (v4sf, v4sf)
v4si __builtin_ia32_cmpordps (v4sf, v4sf)
v4si __builtin_ia32_cmpeqss (v4sf, v4sf)
v4si __builtin_ia32_cmpltss (v4sf, v4sf)
v4si __builtin_ia32_cmpless (v4sf, v4sf)
v4si __builtin_ia32_cmpgtss (v4sf, v4sf)
v4si __builtin_ia32_cmpgess (v4sf, v4sf)
v4si __builtin_ia32_cmpunordss (v4sf, v4sf)
v4si __builtin_ia32_cmpneqss (v4sf, v4sf)
v4si __builtin_ia32_cmpnlts (v4sf, v4sf)
v4si __builtin_ia32_cmpnless (v4sf, v4sf)
v4si __builtin_ia32_cmpngtss (v4sf, v4sf)
v4si __builtin_ia32_cmpngess (v4sf, v4sf)
v4si __builtin_ia32_cmpordss (v4sf, v4sf)
v4sf __builtin_ia32_maxps (v4sf, v4sf)
v4sf __builtin_ia32_maxss (v4sf, v4sf)
v4sf __builtin_ia32_minps (v4sf, v4sf)
v4sf __builtin_ia32_minss (v4sf, v4sf)
v4sf __builtin_ia32_andps (v4sf, v4sf)
v4sf __builtin_ia32_andnps (v4sf, v4sf)
v4sf __builtin_ia32_orps (v4sf, v4sf)
v4sf __builtin_ia32_xorps (v4sf, v4sf)
v4sf __builtin_ia32_movss (v4sf, v4sf)
v4sf __builtin_ia32_movhlps (v4sf, v4sf)
v4sf __builtin_ia32_movlhps (v4sf, v4sf)
v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
v2si __builtin_ia32_cvtps2pi (v4sf)
int __builtin_ia32_cvtss2si (v4sf)
v2si __builtin_ia32_cvttps2pi (v4sf)
int __builtin_ia32_cvttss2si (v4sf)
v4sf __builtin_ia32_rcpps (v4sf)
v4sf __builtin_ia32_rsqrtps (v4sf)
v4sf __builtin_ia32_sqrtps (v4sf)
v4sf __builtin_ia32_rcpss (v4sf)
v4sf __builtin_ia32_rsqrtss (v4sf)
v4sf __builtin_ia32_sqrtss (v4sf)
v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
void __builtin_ia32_movntps (float *, v4sf)
int __builtin_ia32_movmskps (v4sf)

The following built-in functions are available when -msse is used.

v4sf __builtin_ia32_loadaps (float *)
Generates the movaps machine instruction as a load from memory.
void __builtin_ia32_storeaps (float *, v4sf)
Generates the movaps machine instruction as a store to memory.
v4sf __builtin_ia32_loadups (float *)
Generates the movups machine instruction as a load from memory.
void __builtin_ia32_storeups (float *, v4sf)
Generates the movups machine instruction as a store to memory.
v4sf __builtin_ia32_loadsss (float *)
Generates the movss machine instruction as a load from memory.
void __builtin_ia32_storess (float *, v4sf)
Generates the movss machine instruction as a store to memory.
v4sf __builtin_ia32_loadhps (v4sf, v2si *)
Generates the movhps machine instruction as a load from memory.
v4sf __builtin_ia32_loadlps (v4sf, v2si *)
Generates the movlps machine instruction as a load from memory
void __builtin_ia32_storehps (v4sf, v2si *)
Generates the movhps machine instruction as a store to memory.
void __builtin_ia32_storelps (v4sf, v2si *)
Generates the movlps machine instruction as a store to memory.

The following built-in functions are available when -m3dnow is used. All of them generate the machine instruction that is part of the name.

void __builtin_ia32_femms (void)
v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
v2si __builtin_ia32_pf2id (v2sf)
v2sf __builtin_ia32_pfacc (v2sf, v2sf)
v2sf __builtin_ia32_pfadd (v2sf, v2sf)
v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
v2sf __builtin_ia32_pfmax (v2sf, v2sf)
v2sf __builtin_ia32_pfmin (v2sf, v2sf)
v2sf __builtin_ia32_pfmul (v2sf, v2sf)
v2sf __builtin_ia32_pfrcp (v2sf)
v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
v2sf __builtin_ia32_pfrsqrt (v2sf)
v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf)
v2sf __builtin_ia32_pfsub (v2sf, v2sf)
v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
v2sf __builtin_ia32_pi2fd (v2si)
v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)

The following built-in functions are available when both -m3dnow and -march=athlon are used. All of them generate the machine instruction that is part of the name.

v2si __builtin_ia32_pf2iw (v2sf)
v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
v2sf __builtin_ia32_pi2fw (v2si)
v2sf __builtin_ia32_pswapdsf (v2sf)
v2si __builtin_ia32_pswapdsi (v2si)


Using the GNU Compiler Collection (GCC)

Node:Xstormy16 Options, Next:Xtensa Options, Previous:PDP-11 Options, Up:Submodel Options

Xstormy16 Options

These options are defined for Xstormy16:

-msim
Choose startup files and linker script suitable for the simulator.


Using the GNU Compiler Collection (GCC)

Node:Xtensa Options, Previous:Xstormy16 Options, Up:Submodel Options

Xtensa Options

The Xtensa architecture is designed to support many different configurations. The compiler's default options can be set to match a particular Xtensa configuration by copying a configuration file into the GCC sources when building GCC. The options below may be used to override the default options.

-mbig-endian
-mlittle-endian
Specify big-endian or little-endian byte ordering for the target Xtensa processor.
-mdensity
-mno-density
Enable or disable use of the optional Xtensa code density instructions.
-mmac16
-mno-mac16
Enable or disable use of the Xtensa MAC16 option. When enabled, GCC will generate MAC16 instructions from standard C code, with the limitation that it will use neither the MR register file nor any instruction that operates on the MR registers. When this option is disabled, GCC will translate 16-bit multiply/accumulate operations to a combination of core instructions and library calls, depending on whether any other multiplier options are enabled.
-mmul16
-mno-mul16
Enable or disable use of the 16-bit integer multiplier option. When enabled, the compiler will generate 16-bit multiply instructions for multiplications of 16 bits or smaller in standard C code. When this option is disabled, the compiler will either use 32-bit multiply or MAC16 instructions if they are available or generate library calls to perform the multiply operations using shifts and adds.
-mmul32
-mno-mul32
Enable or disable use of the 32-bit integer multiplier option. When enabled, the compiler will generate 32-bit multiply instructions for multiplications of 32 bits or smaller in standard C code. When this option is disabled, the compiler will generate library calls to perform the multiply operations using either shifts and adds or 16-bit multiply instructions if they are available.
-mnsa
-mno-nsa
Enable or disable use of the optional normalization shift amount (NSA) instructions to implement the built-in ffs function.
-mminmax
-mno-minmax
Enable or disable use of the optional minimum and maximum value instructions.
-msext
-mno-sext
Enable or disable use of the optional sign extend (SEXT) instruction.
-mbooleans
-mno-booleans
Enable or disable support for the boolean register file used by Xtensa coprocessors. This is not typically useful by itself but may be required for other options that make use of the boolean registers (e.g., the floating-point option).
-mhard-float
-msoft-float
Enable or disable use of the floating-point option. When enabled, GCC generates floating-point instructions for 32-bit float operations. When this option is disabled, GCC generates library calls to emulate 32-bit floating-point operations using integer instructions. Regardless of this option, 64-bit double operations are always emulated with calls to library functions.
-mfused-madd
-mno-fused-madd
Enable or disable use of fused multiply/add and multiply/subtract instructions in the floating-point option. This has no effect if the floating-point option is not also enabled. Disabling fused multiply/add and multiply/subtract instructions forces the compiler to use separate instructions for the multiply and add/subtract operations. This may be desirable in some cases where strict IEEE 754-compliant results are required: the fused multiply add/subtract instructions do not round the intermediate result, thereby producing results with more bits of precision than specified by the IEEE standard. Disabling fused multiply add/subtract instructions also ensures that the program output is not sensitive to the compiler's ability to combine multiply and add/subtract operations.
-mserialize-volatile
-mno-serialize-volatile
When this option is enabled, GCC inserts MEMW instructions before volatile memory references to guarantee sequential consistency. The default is -mserialize-volatile. Use -mno-serialize-volatile to omit the MEMW instructions.
-mtext-section-literals
-mno-text-section-literals
Control the treatment of literal pools. The default is -mno-text-section-literals, which places literals in a separate section in the output file. This allows the literal pool to be placed in a data RAM/ROM, and it also allows the linker to combine literal pools from separate object files to remove redundant literals and improve code size. With -mtext-section-literals, the literals are interspersed in the text section in order to keep them as close as possible to their references. This may be necessary for large assembly files.
-mtarget-align
-mno-target-align
When this option is enabled, GCC instructs the assembler to automatically align instructions to reduce branch penalties at the expense of some code density. The assembler attempts to widen density instructions to align branch targets and the instructions following call instructions. If there are not enough preceding safe density instructions to align a target, no widening will be performed. The default is -mtarget-align. These options do not affect the treatment of auto-aligned instructions like LOOP, which the assembler will always align, either by widening density instructions or by inserting no-op instructions.
-mlongcalls
-mno-longcalls
When this option is enabled, GCC instructs the assembler to translate direct calls to indirect calls unless it can determine that the target of a direct call is in the range allowed by the call instruction. This translation typically occurs for calls to functions in other source files. Specifically, the assembler translates a direct CALL instruction into an L32R followed by a CALLX instruction. The default is -mno-longcalls. This option should be used in programs where the call target can potentially be out of range. This option is implemented in the assembler, not the compiler, so the assembly code generated by GCC will still show direct call instructions--look at the disassembled object code to see the actual instructions. Note that the assembler will use an indirect call for every cross-file call, not just those that really will be out of range.


Using the GNU Compiler Collection (GCC)

Node:Zero Length, Next:Variable Length, Previous:Hex Floats, Up:C Extensions

Arrays of Length Zero

Zero-length arrays are allowed in GNU C. They are very useful as the last element of a structure which is really a header for a variable-length object:

struct line {
  int length;
  char contents[0];
};

struct line *thisline = (struct line *)
  malloc (sizeof (struct line) + this_length);
thisline->length = this_length;

In ISO C89, you would have to give contents a length of 1, which means either you waste space or complicate the argument to malloc.

In ISO C99, you would use a flexible array member, which is slightly different in syntax and semantics:

  • Flexible array members are written as contents[] without the 0.
  • Flexible array members have incomplete type, and so the sizeof operator may not be applied. As a quirk of the original implementation of zero-length arrays, sizeof evaluates to zero.
  • Flexible array members may only appear as the last member of a struct that is otherwise non-empty.

GCC versions before 3.0 allowed zero-length arrays to be statically initialized, as if they were flexible arrays. In addition to those cases that were useful, it also allowed initializations in situations that would corrupt later data. Non-empty initialization of zero-length arrays is now treated like any case where there are more initializer elements than the array holds, in that a suitable warning about "excess elements in array" is given, and the excess elements (all of them, in this case) are ignored.

Instead GCC allows static initialization of flexible array members. This is equivalent to defining a new structure containing the original structure followed by an array of sufficient size to contain the data. I.e. in the following, f1 is constructed as if it were declared like f2.

struct f1 {
  int x; int y[];
} f1 = { 1, { 2, 3, 4 } };

struct f2 {
  struct f1 f1; int data[3];
} f2 = { { 1 }, { 2, 3, 4 } };

The convenience of this extension is that f1 has the desired type, eliminating the need to consistently refer to f2.f1.

This has symmetry with normal static arrays, in that an array of unknown size is also written with [].

Of course, this extension only makes sense if the extra data comes at the end of a top-level object, as otherwise we would be overwriting data at subsequent offsets. To avoid undue complication and confusion with initialization of deeply nested arrays, we simply disallow any non-empty initialization except when the structure is the top-level object. For example:

struct foo { int x; int y[]; };
struct bar { struct foo z; };

struct foo a = { 1, { 2, 3, 4 } };        // Valid.
struct bar b = { { 1, { 2, 3, 4 } } };    // Invalid.
struct bar c = { { 1, { } } };            // Valid.
struct foo d[1] = { { 1 { 2, 3, 4 } } };  // Invalid.


Using and Porting GNU Fortran

Contributed by James Craig Burley (craig@jcb-sc.com). Inspired by a first pass at translating g77-0.5.16/f/DOC that was contributed to Craig by David Ronis (ronis@onsager.chem.mcgill.ca).

Short Contents

  • Introduction
  • GNU GENERAL PUBLIC LICENSE
  • GNU Free Documentation License
  • Contributors to GNU Fortran
  • Funding Free Software
  • Funding GNU Fortran
  • Getting Started
  • What is GNU Fortran?
  • Compile Fortran, C, or Other Programs
  • GNU Fortran Command Options
  • News About GNU Fortran
  • User-visible Changes
  • The GNU Fortran Language
  • Other Dialects
  • The GNU Fortran Compiler
  • Other Compilers
  • Other Languages
  • Debugging and Interfacing
  • Collected Fortran Wisdom
  • Known Causes of Trouble with GNU Fortran
  • Open Questions
  • Reporting Bugs
  • How To Get Help with GNU Fortran
  • Adding Options
  • Projects
  • Front End
  • Diagnostics
  • Index

Table of Contents

  • Introduction
  • GNU GENERAL PUBLIC LICENSE
    • Preamble
    • How to Apply These Terms to Your New Programs
  • GNU Free Documentation License
    • ADDENDUM: How to use this License for your documents
  • Contributors to GNU Fortran
  • Funding Free Software
  • Funding GNU Fortran
  • Getting Started
  • What is GNU Fortran?
  • Compile Fortran, C, or Other Programs
  • GNU Fortran Command Options
    • Option Summary
    • Options Controlling the Kind of Output
    • Shorthand Options
    • Options Controlling Fortran Dialect
    • Options to Request or Suppress Warnings
    • Options for Debugging Your Program or GNU Fortran
    • Options That Control Optimization
    • Options Controlling the Preprocessor
    • Options for Directory Search
    • Options for Code Generation Conventions
    • Environment Variables Affecting GNU Fortran
  • News About GNU Fortran
  • User-visible Changes
  • The GNU Fortran Language
    • Direction of Language Development
    • ANSI FORTRAN 77 Standard Support
      • No Passing External Assumed-length
      • No Passing Dummy Assumed-length
      • No Pathological Implied-DO
      • No Useless Implied-DO
    • Conformance
    • Notation Used in This Chapter
    • Fortran Terms and Concepts
      • Syntactic Items
      • Statements, Comments, and Lines
      • Scope of Symbolic Names and Statement Labels
    • Characters, Lines, and Execution Sequence
      • GNU Fortran Character Set
      • Lines
      • Continuation Line
      • Statements
      • Statement Labels
      • Order of Statements and Lines
      • Including Source Text
      • Cpp-style directives
    • Data Types and Constants
      • Data Types
        • Double Notation
        • Star Notation
        • Kind Notation
      • Constants
      • Integer Type
      • Character Type
    • Expressions
      • The %LOC() Construct
    • Specification Statements
      • NAMELIST Statement
      • DOUBLE COMPLEX Statement
    • Control Statements
      • DO WHILE
      • END DO
      • Construct Names
      • The CYCLE and EXIT Statements
    • Functions and Subroutines
      • The %VAL() Construct
      • The %REF() Construct
      • The %DESCR() Construct
      • Generics and Specifics
      • REAL() and AIMAG() of Complex
      • CMPLX() of DOUBLE PRECISION
      • MIL-STD 1753 Support
      • f77/f2c Intrinsics
      • Table of Intrinsic Functions
        • Abort Intrinsic
        • Abs Intrinsic
        • Access Intrinsic
        • AChar Intrinsic
        • ACos Intrinsic
        • AdjustL Intrinsic
        • AdjustR Intrinsic
        • AImag Intrinsic
        • AInt Intrinsic
        • Alarm Intrinsic
        • All Intrinsic
        • Allocated Intrinsic
        • ALog Intrinsic
        • ALog10 Intrinsic
        • AMax0 Intrinsic
        • AMax1 Intrinsic
        • AMin0 Intrinsic
        • AMin1 Intrinsic
        • AMod Intrinsic
        • And Intrinsic
        • ANInt Intrinsic
        • Any Intrinsic
        • ASin Intrinsic
        • Associated Intrinsic
        • ATan Intrinsic
        • ATan2 Intrinsic
        • BesJ0 Intrinsic
        • BesJ1 Intrinsic
        • BesJN Intrinsic
        • BesY0 Intrinsic
        • BesY1 Intrinsic
        • BesYN Intrinsic
        • Bit_Size Intrinsic
        • BTest Intrinsic
        • CAbs Intrinsic
        • CCos Intrinsic
        • Ceiling Intrinsic
        • CExp Intrinsic
        • Char Intrinsic
        • ChDir Intrinsic (subroutine)
        • ChMod Intrinsic (subroutine)
        • CLog Intrinsic
        • Cmplx Intrinsic
        • Complex Intrinsic
        • Conjg Intrinsic
        • Cos Intrinsic
        • CosH Intrinsic
        • Count Intrinsic
        • CPU_Time Intrinsic
        • CShift Intrinsic
        • CSin Intrinsic
        • CSqRt Intrinsic
        • CTime Intrinsic (subroutine)
        • CTime Intrinsic (function)
        • DAbs Intrinsic
        • DACos Intrinsic
        • DASin Intrinsic
        • DATan Intrinsic
        • DATan2 Intrinsic
        • Date_and_Time Intrinsic
        • DbesJ0 Intrinsic
        • DbesJ1 Intrinsic
        • DbesJN Intrinsic
        • DbesY0 Intrinsic
        • DbesY1 Intrinsic
        • DbesYN Intrinsic
        • Dble Intrinsic
        • DCos Intrinsic
        • DCosH Intrinsic
        • DDiM Intrinsic
        • DErF Intrinsic
        • DErFC Intrinsic
        • DExp Intrinsic
        • Digits Intrinsic
        • DiM Intrinsic
        • DInt Intrinsic
        • DLog Intrinsic
        • DLog10 Intrinsic
        • DMax1 Intrinsic
        • DMin1 Intrinsic
        • DMod Intrinsic
        • DNInt Intrinsic
        • Dot_Product Intrinsic
        • DProd Intrinsic
        • DSign Intrinsic
        • DSin Intrinsic
        • DSinH Intrinsic
        • DSqRt Intrinsic
        • DTan Intrinsic
        • DTanH Intrinsic
        • DTime Intrinsic (subroutine)
        • EOShift Intrinsic
        • Epsilon Intrinsic
        • ErF Intrinsic
        • ErFC Intrinsic
        • ETime Intrinsic (subroutine)
        • ETime Intrinsic (function)
        • Exit Intrinsic
        • Exp Intrinsic
        • Exponent Intrinsic
        • FDate Intrinsic (subroutine)
        • FDate Intrinsic (function)
        • FGet Intrinsic (subroutine)
        • FGetC Intrinsic (subroutine)
        • Float Intrinsic
        • Floor Intrinsic
        • Flush Intrinsic
        • FNum Intrinsic
        • FPut Intrinsic (subroutine)
        • FPutC Intrinsic (subroutine)
        • Fraction Intrinsic
        • FSeek Intrinsic
        • FStat Intrinsic (subroutine)
        • FStat Intrinsic (function)
        • FTell Intrinsic (subroutine)
        • FTell Intrinsic (function)
        • GError Intrinsic
        • GetArg Intrinsic
        • GetCWD Intrinsic (subroutine)
        • GetCWD Intrinsic (function)
        • GetEnv Intrinsic
        • GetGId Intrinsic
        • GetLog Intrinsic
        • GetPId Intrinsic
        • GetUId Intrinsic
        • GMTime Intrinsic
        • HostNm Intrinsic (subroutine)
        • HostNm Intrinsic (function)
        • Huge Intrinsic
        • IAbs Intrinsic
        • IAChar Intrinsic
        • IAnd Intrinsic
        • IArgC Intrinsic
        • IBClr Intrinsic
        • IBits Intrinsic
        • IBSet Intrinsic
        • IChar Intrinsic
        • IDate Intrinsic (UNIX)
        • IDiM Intrinsic
        • IDInt Intrinsic
        • IDNInt Intrinsic
        • IEOr Intrinsic
        • IErrNo Intrinsic
        • IFix Intrinsic
        • Imag Intrinsic
        • ImagPart Intrinsic
        • Index Intrinsic
        • Int Intrinsic
        • Int2 Intrinsic
        • Int8 Intrinsic
        • IOr Intrinsic
        • IRand Intrinsic
        • IsaTty Intrinsic
        • IShft Intrinsic
        • IShftC Intrinsic
        • ISign Intrinsic
        • ITime Intrinsic
        • Kill Intrinsic (subroutine)
        • Kind Intrinsic
        • LBound Intrinsic
        • Len Intrinsic
        • Len_Trim Intrinsic
        • LGe Intrinsic
        • LGt Intrinsic
        • Link Intrinsic (subroutine)
        • LLe Intrinsic
        • LLt Intrinsic
        • LnBlnk Intrinsic
        • Loc Intrinsic
        • Log Intrinsic
        • Log10 Intrinsic
        • Logical Intrinsic
        • Long Intrinsic
        • LShift Intrinsic
        • LStat Intrinsic (subroutine)
        • LStat Intrinsic (function)
        • LTime Intrinsic
        • MatMul Intrinsic
        • Max Intrinsic
        • Max0 Intrinsic
        • Max1 Intrinsic
        • MaxExponent Intrinsic
        • MaxLoc Intrinsic
        • MaxVal Intrinsic
        • MClock Intrinsic
        • MClock8 Intrinsic
        • Merge Intrinsic
        • Min Intrinsic
        • Min0 Intrinsic
        • Min1 Intrinsic
        • MinExponent Intrinsic
        • MinLoc Intrinsic
        • MinVal Intrinsic
        • Mod Intrinsic
        • Modulo Intrinsic
        • MvBits Intrinsic
        • Nearest Intrinsic
        • NInt Intrinsic
        • Not Intrinsic
        • Or Intrinsic
        • Pack Intrinsic
        • PError Intrinsic
        • Precision Intrinsic
        • Present Intrinsic
        • Product Intrinsic
        • Radix Intrinsic
        • Rand Intrinsic
        • Random_Number Intrinsic
        • Random_Seed Intrinsic
        • Range Intrinsic
        • Real Intrinsic
        • RealPart Intrinsic
        • Rename Intrinsic (subroutine)
        • Repeat Intrinsic
        • Reshape Intrinsic
        • RRSpacing Intrinsic
        • RShift Intrinsic
        • Scale Intrinsic
        • Scan Intrinsic
        • Second Intrinsic (function)
        • Second Intrinsic (subroutine)
        • Selected_Int_Kind Intrinsic
        • Selected_Real_Kind Intrinsic
        • Set_Exponent Intrinsic
        • Shape Intrinsic
        • Short Intrinsic
        • Sign Intrinsic
        • Signal Intrinsic (subroutine)
        • Sin Intrinsic
        • SinH Intrinsic
        • Sleep Intrinsic
        • Sngl Intrinsic
        • Spacing Intrinsic
        • Spread Intrinsic
        • SqRt Intrinsic
        • SRand Intrinsic
        • Stat Intrinsic (subroutine)
        • Stat Intrinsic (function)
        • Sum Intrinsic
        • SymLnk Intrinsic (subroutine)
        • System Intrinsic (subroutine)
        • System_Clock Intrinsic
        • Tan Intrinsic
        • TanH Intrinsic
        • Time Intrinsic (UNIX)
        • Time8 Intrinsic
        • Tiny Intrinsic
        • Transfer Intrinsic
        • Transpose Intrinsic
        • Trim Intrinsic
        • TtyNam Intrinsic (subroutine)
        • TtyNam Intrinsic (function)
        • UBound Intrinsic
        • UMask Intrinsic (subroutine)
        • Unlink Intrinsic (subroutine)
        • Unpack Intrinsic
        • Verify Intrinsic
        • XOr Intrinsic
        • ZAbs Intrinsic
        • ZCos Intrinsic
        • ZExp Intrinsic
        • ZLog Intrinsic
        • ZSin Intrinsic
        • ZSqRt Intrinsic
    • Scope and Classes of Symbolic Names
      • Underscores in Symbol Names
    • I/O
    • Fortran 90 Features
  • Other Dialects
    • Source Form
      • Carriage Returns
      • Tabs
      • Short Lines
      • Long Lines
      • Ampersand Continuation Line
    • Trailing Comment
    • Debug Line
    • Dollar Signs in Symbol Names
    • Case Sensitivity
    • VXT Fortran
      • Meaning of Double Quote
      • Meaning of Exclamation Point in Column 6
    • Fortran 90
    • Pedantic Compilation
    • Distensions
      • Implicit Argument Conversion
      • Ugly Assumed-Size Arrays
      • Ugly Complex Part Extraction
      • Ugly Null Arguments
      • Ugly Conversion of Initializers
      • Ugly Integer Conversions
      • Ugly Assigned Labels
  • The GNU Fortran Compiler
    • Compiler Limits
    • Run-time Environment Limits
      • Timer Wraparounds
      • Year 2000 (Y2K) Problems
      • Array Size
      • Character-variable Length
      • Year 10000 (Y10K) Problems
    • Compiler Types
    • Compiler Constants
    • Compiler Intrinsics
      • Intrinsic Groups
      • Other Intrinsics
        • ACosD Intrinsic
        • AIMax0 Intrinsic
        • AIMin0 Intrinsic
        • AJMax0 Intrinsic
        • AJMin0 Intrinsic
        • ASinD Intrinsic
        • ATan2D Intrinsic
        • ATanD Intrinsic
        • BITest Intrinsic
        • BJTest Intrinsic
        • CDAbs Intrinsic
        • CDCos Intrinsic
        • CDExp Intrinsic
        • CDLog Intrinsic
        • CDSin Intrinsic
        • CDSqRt Intrinsic
        • ChDir Intrinsic (function)
        • ChMod Intrinsic (function)
        • CosD Intrinsic
        • DACosD Intrinsic
        • DASinD Intrinsic
        • DATan2D Intrinsic
        • DATanD Intrinsic
        • Date Intrinsic
        • DbleQ Intrinsic
        • DCmplx Intrinsic
        • DConjg Intrinsic
        • DCosD Intrinsic
        • DFloat Intrinsic
        • DFlotI Intrinsic
        • DFlotJ Intrinsic
        • DImag Intrinsic
        • DReal Intrinsic
        • DSinD Intrinsic
        • DTanD Intrinsic
        • DTime Intrinsic (function)
        • FGet Intrinsic (function)
        • FGetC Intrinsic (function)
        • FloatI Intrinsic
        • FloatJ Intrinsic
        • FPut Intrinsic (function)
        • FPutC Intrinsic (function)
        • IDate Intrinsic (VXT)
        • IIAbs Intrinsic
        • IIAnd Intrinsic
        • IIBClr Intrinsic
        • IIBits Intrinsic
        • IIBSet Intrinsic
        • IIDiM Intrinsic
        • IIDInt Intrinsic
        • IIDNnt Intrinsic
        • IIEOr Intrinsic
        • IIFix Intrinsic
        • IInt Intrinsic
        • IIOr Intrinsic
        • IIQint Intrinsic
        • IIQNnt Intrinsic
        • IIShftC Intrinsic
        • IISign Intrinsic
        • IMax0 Intrinsic
        • IMax1 Intrinsic
        • IMin0 Intrinsic
        • IMin1 Intrinsic
        • IMod Intrinsic
        • INInt Intrinsic
        • INot Intrinsic
        • IZExt Intrinsic
        • JIAbs Intrinsic
        • JIAnd Intrinsic
        • JIBClr Intrinsic
        • JIBits Intrinsic
        • JIBSet Intrinsic
        • JIDiM Intrinsic
        • JIDInt Intrinsic
        • JIDNnt Intrinsic
        • JIEOr Intrinsic
        • JIFix Intrinsic
        • JInt Intrinsic
        • JIOr Intrinsic
        • JIQint Intrinsic
        • JIQNnt Intrinsic
        • JIShft Intrinsic
        • JIShftC Intrinsic
        • JISign Intrinsic
        • JMax0 Intrinsic
        • JMax1 Intrinsic
        • JMin0 Intrinsic
        • JMin1 Intrinsic
        • JMod Intrinsic
        • JNInt Intrinsic
        • JNot Intrinsic
        • JZExt Intrinsic
        • Kill Intrinsic (function)
        • Link Intrinsic (function)
        • QAbs Intrinsic
        • QACos Intrinsic
        • QACosD Intrinsic
        • QASin Intrinsic
        • QASinD Intrinsic
        • QATan Intrinsic
        • QATan2 Intrinsic
        • QATan2D Intrinsic
        • QATanD Intrinsic
        • QCos Intrinsic
        • QCosD Intrinsic
        • QCosH Intrinsic
        • QDiM Intrinsic
        • QExp Intrinsic
        • QExt Intrinsic
        • QExtD Intrinsic
        • QFloat Intrinsic
        • QInt Intrinsic
        • QLog Intrinsic
        • QLog10 Intrinsic
        • QMax1 Intrinsic
        • QMin1 Intrinsic
        • QMod Intrinsic
        • QNInt Intrinsic
        • QSin Intrinsic
        • QSinD Intrinsic
        • QSinH Intrinsic
        • QSqRt Intrinsic
        • QTan Intrinsic
        • QTanD Intrinsic
        • QTanH Intrinsic
        • Rename Intrinsic (function)
        • Secnds Intrinsic
        • Signal Intrinsic (function)
        • SinD Intrinsic
        • SnglQ Intrinsic
        • SymLnk Intrinsic (function)
        • System Intrinsic (function)
        • TanD Intrinsic
        • Time Intrinsic (VXT)
        • UMask Intrinsic (function)
        • Unlink Intrinsic (function)
        • ZExt Intrinsic
  • Other Compilers
    • Dropping f2c Compatibility
    • Compilers Other Than f2c
  • Other Languages
    • Tools and advice for interoperating with C and C++
      • C Interfacing Tools
      • Accessing Type Information in C
      • Generating Skeletons and Prototypes with f2c
      • C++ Considerations
      • Startup Code
  • Debugging and Interfacing
    • Main Program Unit (PROGRAM)
    • Procedures (SUBROUTINE and FUNCTION)
    • Functions (FUNCTION and RETURN)
    • Names
    • Common Blocks (COMMON)
    • Local Equivalence Areas (EQUIVALENCE)
    • Complex Variables (COMPLEX)
    • Arrays (DIMENSION)
    • Adjustable Arrays (DIMENSION)
    • Alternate Entry Points (ENTRY)
    • Alternate Returns (SUBROUTINE and RETURN)
    • Assigned Statement Labels (ASSIGN and GOTO)
    • Run-time Library Errors
  • Collected Fortran Wisdom
    • Advantages Over f2c
      • Language Extensions
      • Diagnostic Abilities
      • Compiler Options
      • Compiler Speed
      • Program Speed
      • Ease of Debugging
      • Character and Hollerith Constants
    • Block Data and Libraries
    • Loops
    • Working Programs
      • Not My Type
      • Variables Assumed To Be Zero
      • Variables Assumed To Be Saved
      • Unwanted Variables
      • Unused Arguments
      • Surprising Interpretations of Code
      • Aliasing Assumed To Work
      • Output Assumed To Flush
      • Large File Unit Numbers
      • Floating-point precision
      • Inconsistent Calling Sequences
    • Overly Convenient Command-line Options
    • Faster Programs
      • Aligned Data
      • Prefer Automatic Uninitialized Variables
      • Avoid f2c Compatibility
      • Use Submodel Options
  • Known Causes of Trouble with GNU Fortran
    • Bugs Not In GNU Fortran
      • Signal 11 and Friends
      • Cannot Link Fortran Programs
      • Large Common Blocks
      • Debugger Problems
      • NeXTStep Problems
      • Stack Overflow
      • Nothing Happens
      • Strange Behavior at Run Time
      • Floating-point Errors
    • Known Bugs In GNU Fortran
    • Missing Features
      • Better Source Model
      • Fortran 90 Support
      • Intrinsics in PARAMETER Statements
      • Arbitrary Concatenation
      • SELECT CASE on CHARACTER Type
      • RECURSIVE Keyword
      • Increasing Precision/Range
      • Popular Non-standard Types
      • Full Support for Compiler Types
      • Array Bounds Expressions
      • POINTER Statements
      • Sensible Non-standard Constructs
      • READONLY Keyword
      • FLUSH Statement
      • Expressions in FORMAT Statements
      • Explicit Assembler Code
      • Q Edit Descriptor
      • Old-style PARAMETER Statements
      • TYPE and ACCEPT I/O Statements
      • STRUCTURE, UNION, RECORD, MAP
      • OPEN, CLOSE, and INQUIRE Keywords
      • ENCODE and DECODE
      • AUTOMATIC Statement
      • Suppressing Space Padding of Source Lines
      • Fortran Preprocessor
      • Bit Operations on Floating-point Data
      • Really Ugly Character Assignments
      • POSIX Standard
      • Floating-point Exception Handling
      • Nonportable Conversions
      • Large Automatic Arrays
      • Support for Threads
      • Enabling Debug Lines
      • Better Warnings
      • Gracefully Handle Sensible Bad Code
      • Non-standard Conversions
      • Non-standard Intrinsics
      • Modifying DO Variable
      • Better Pedantic Compilation
      • Warn About Implicit Conversions
      • Invalid Use of Hollerith Constant
      • Dummy Array Without Dimensioning Dummy
      • Invalid FORMAT Specifiers
      • Ambiguous Dialects
      • Unused Labels
      • Informational Messages
      • Uninitialized Variables at Run Time
      • Portable Unformatted Files
      • Better List-directed I/O
      • Default to Console I/O
      • Labels Visible to Debugger
    • Disappointments and Misunderstandings
      • Mangling of Names in Source Code
      • Multiple Definitions of External Names
      • Limitation on Implicit Declarations
    • Certain Changes We Don't Want to Make
      • Backslash in Constants
      • Initializing Before Specifying
      • Context-Sensitive Intrinsicness
      • Context-Sensitive Constants
      • Equivalence Versus Equality
      • Order of Side Effects
    • Warning Messages and Error Messages
  • Open Questions
  • Reporting Bugs
    • Have You Found a Bug?
    • Where to Report Bugs
    • How to Report Bugs
  • How To Get Help with GNU Fortran
  • Adding Options
  • Projects
    • Improve Efficiency
    • Better Optimization
    • Simplify Porting
    • More Extensions
    • Machine Model
    • Internals Documentation
    • Internals Improvements
    • Better Diagnostics
  • Front End
    • Overview of Sources
    • Overview of Translation Process
      • g77stripcard
      • lex.c
      • sta.c
      • sti.c
      • stq.c
      • stb.c
      • expr.c
      • stc.c
      • std.c
      • ste.c
      • Gotchas (Transforming)
        • Multi-character Lexemes
        • Space-padding Lexemes
        • Bizarre Free-form Hollerith Constants
        • Hollerith Constants
        • Confusing Function Keyword
        • Weird READ
      • TBD (Transforming)
    • Philosophy of Code Generation
    • Two-pass Design
      • Two-pass Code
      • Why Two Passes
    • Challenges Posed
    • Transforming Statements
      • Statements Needing Temporaries
      • Transforming DO WHILE
      • Transforming Iterative DO
      • Transforming Block IF
      • Transforming SELECT CASE
    • Transforming Expressions
    • Internal Naming Conventions
  • Diagnostics
    • CMPAMBIG
    • EXPIMP
    • INTGLOB
    • LEX
    • GLOBALS
    • LINKFAIL
    • Y2KBAD
  • Index

Node:Top, Next:Copying, Up:(DIR)

Introduction

This manual documents how to run, install and port g77, as well as its new features and incompatibilities, and how to report bugs. It corresponds to the GCC-3.1 version of g77.

  • Copying: GNU General Public License says how you can copy and share GNU Fortran.
  • GNU Free Documentation License: How you can copy and share this manual.
  • Contributors: People who have contributed to GNU Fortran.
  • Funding: How to help assure continued work for free software.
  • Funding GNU Fortran: How to help assure continued work on GNU Fortran.

  • Getting Started: Finding your way around this manual.
  • What is GNU Fortran?: How g77 fits into the universe.
  • G77 and GCC: You can compile Fortran, C, or other programs.
  • Invoking G77: Command options supported by g77.
  • News: News about recent releases of g77.
  • Changes: User-visible changes to recent releases of g77.
  • Language: The GNU Fortran language.
  • Compiler: The GNU Fortran compiler.
  • Other Dialects: Dialects of Fortran supported by g77.
  • Other Compilers: Fortran compilers other than g77.
  • Other Languages: Languages other than Fortran.
  • Debugging and Interfacing: How g77 generates code.
  • Collected Fortran Wisdom: How to avoid Trouble.
  • Trouble: If you have trouble with GNU Fortran.
  • Open Questions: Things we'd like to know.
  • Bugs: How, why, and where to report bugs.
  • Service: How to find suppliers of support for GNU Fortran.

  • Adding Options: Guidance on teaching g77 about new options.
  • Projects: Projects for g77 internals hackers.
  • Front End: Design and implementation of the g77 front end.

  • M: Diagnostics produced by g77.

  • Index: Index of concepts and symbol names.


Node:Advantages Over f2c, Next:Block Data and Libraries, Up:Collected Fortran Wisdom

Advantages Over f2c

Without f2c, g77 would have taken much longer to do and probably not been as good for quite a while. Sometimes people who notice how much g77 depends on, and documents encouragement to use, f2c ask why g77 was created if f2c already existed.

This section gives some basic answers to these questions, though it is not intended to be comprehensive.

  • Language Extensions: Features used by Fortran code.
  • Diagnostic Abilities: Abilities to spot problems early.
  • Compiler Options: Features helpful to accommodate legacy code, etc.
  • Compiler Speed: Speed of the compilation process.
  • Program Speed: Speed of the generated, optimized code.
  • Ease of Debugging: Debugging ease-of-use at the source level.
  • Character and Hollerith Constants: A byte saved is a byte earned.


Node:%DESCR(), Next:Generics and Specifics, Previous:%REF(), Up:Functions and Subroutines

The %DESCR() Construct

%DESCR(arg)

The %DESCR() construct specifies that an argument, arg, is to be passed by descriptor, instead of by value or reference.

%DESCR() is restricted to actual arguments in invocations of external procedures.

Use of %DESCR() is recommended only for code that is accessing facilities outside of GNU Fortran, such as operating system or windowing facilities. It is best to constrain such uses to isolated portions of a program--portions the deal specifically and exclusively with low-level, system-dependent facilities. Such portions might well provide a portable interface for use by the program as a whole, but are themselves not portable, and should be thoroughly tested each time they are rebuilt using a new compiler or version of a compiler.

Do not depend on %DESCR() supplying a pointer and/or a length passed by value to the procedure being invoked. While that is a likely implementation choice, other implementation choices are available that preserve the pass-by-reference semantics without passing a pointer to the argument, arg. (For example, a copy-in/copy-out implementation.) And, future versions of g77 might change the way descriptors are implemented, such as passing a single argument pointing to a record containing the pointer/length information instead of passing that same information via two arguments as it currently does.

Implementation Note: Currently, g77 passes all variables and arrays of type CHARACTER by descriptor. Future versions of, or dialects supported by, g77 might pass CHARACTER functions by descriptor as well.

Thus, use of %DESCR() tends to be restricted to cases where arg is not type CHARACTER but the called procedure accesses it via a means similar to the method used for Fortran CHARACTER arguments.

See Procedures (SUBROUTINE and FUNCTION), for detailed information on how this particular version of g77 passes arguments to procedures.


Node:%LOC(), Up:Expressions

The %LOC() Construct

%LOC(arg)

The %LOC() construct is an expression that yields the value of the location of its argument, arg, in memory. The size of the type of the expression depends on the system--typically, it is equivalent to either INTEGER(KIND=1) or INTEGER(KIND=2), though it is actually type INTEGER(KIND=7).

The argument to %LOC() must be suitable as the left-hand side of an assignment statement. That is, it may not be a general expression involving operators such as addition, subtraction, and so on, nor may it be a constant.

Use of %LOC() is recommended only for code that is accessing facilities outside of GNU Fortran, such as operating system or windowing facilities. It is best to constrain such uses to isolated portions of a program--portions that deal specifically and exclusively with low-level, system-dependent facilities. Such portions might well provide a portable interface for use by the program as a whole, but are themselves not portable, and should be thoroughly tested each time they are rebuilt using a new compiler or version of a compiler.

Do not depend on %LOC() returning a pointer that can be safely used to define (change) the argument. While this might work in some circumstances, it is hard to predict whether it will continue to work when a program (that works using this unsafe behavior) is recompiled using different command-line options or a different version of g77.

Generally, %LOC() is safe when used as an argument to a procedure that makes use of the value of the corresponding dummy argument only during its activation, and only when such use is restricted to referencing (reading) the value of the argument to %LOC().

Implementation Note: Currently, g77 passes arguments (those not passed using a construct such as %VAL()) by reference or descriptor, depending on the type of the actual argument. Thus, given INTEGER I, CALL FOO(I) would seem to mean the same thing as CALL FOO(%VAL(%LOC(I))), and in fact might compile to identical code.

However, CALL FOO(%VAL(%LOC(I))) emphatically means "pass, by value, the address of I in memory". While CALL FOO(I) might use that same approach in a particular version of g77, another version or compiler might choose a different implementation, such as copy-in/copy-out, to effect the desired behavior--and which will therefore not necessarily compile to the same code as would CALL FOO(%VAL(%LOC(I))) using the same version or compiler.

See Debugging and Interfacing, for detailed information on how this particular version of g77 implements various constructs.


Node:%REF(),
Next:%DESCR(),
Previous:%VAL(),
Up:Functions and Subroutines

The %REF() Construct

%REF(arg)

The %REF() construct specifies that an argument, arg, is to be passed by reference, instead of by value or descriptor.

%REF() is restricted to actual arguments in invocations of external procedures.

Use of %REF() is recommended only for code that is accessing facilities outside of GNU Fortran, such as operating system or windowing facilities. It is best to constrain such uses to isolated portions of a program--portions the deal specifically and exclusively with low-level, system-dependent facilities. Such portions might well provide a portable interface for use by the program as a whole, but are themselves not portable, and should be thoroughly tested each time they are rebuilt using a new compiler or version of a compiler.

Do not depend on %REF() supplying a pointer to the procedure being invoked. While that is a likely implementation choice, other implementation choices are available that preserve Fortran pass-by-reference semantics without passing a pointer to the argument, arg. (For example, a copy-in/copy-out implementation.)

Implementation Note: Currently, g77 passes all arguments (other than variables and arrays of type CHARACTER) by reference. Future versions of, or dialects supported by, g77 might not pass CHARACTER functions by reference.

Thus, use of %REF() tends to be restricted to cases where arg is type CHARACTER but the called procedure accesses it via a means other than the method used for Fortran CHARACTER arguments.

See Procedures (SUBROUTINE and FUNCTION), for detailed information on how this particular version of g77 passes arguments to procedures.


Node:%VAL(), Next:%REF(), Up:Functions and Subroutines

The %VAL() Construct

%VAL(arg)

The %VAL() construct specifies that an argument, arg, is to be passed by value, instead of by reference or descriptor.

%VAL() is restricted to actual arguments in invocations of external procedures.

Use of %VAL() is recommended only for code that is accessing facilities outside of GNU Fortran, such as operating system or windowing facilities. It is best to constrain such uses to isolated portions of a program--portions the deal specifically and exclusively with low-level, system-dependent facilities. Such portions might well provide a portable interface for use by the program as a whole, but are themselves not portable, and should be thoroughly tested each time they are rebuilt using a new compiler or version of a compiler.

Implementation Note: Currently, g77 passes all arguments either by reference or by descriptor.

Thus, use of %VAL() tends to be restricted to cases where the called procedure is written in a language other than Fortran that supports call-by-value semantics. (C is an example of such a language.)

See Procedures (SUBROUTINE and FUNCTION), for detailed information on how this particular version of g77 passes arguments to procedures.


Node:Abort Intrinsic, Next:Abs Intrinsic, Up:Table of Intrinsic Functions

Abort Intrinsic

CALL Abort()

Intrinsic groups: unix.

Description:

Prints a message and potentially causes a core dump via abort(3).


Node:Abs Intrinsic, Next:Access Intrinsic, Previous:Abort Intrinsic, Up:Table of Intrinsic Functions

Abs Intrinsic

Abs(A)

Abs: INTEGER or REAL function. The exact type depends on that of argument A--if A is COMPLEX, this function's type is REAL with the same KIND= value as the type of A. Otherwise, this function's type is the same as that of A.

A: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the absolute value of A.

If A is type COMPLEX, the absolute value is computed as:

SQRT(REALPART(A)**2+IMAGPART(A)**2)

Otherwise, it is computed by negating A if it is negative, or returning A.

See Sign Intrinsic, for how to explicitly compute the positive or negative form of the absolute value of an expression.


Node:Access Intrinsic, Next:AChar Intrinsic, Previous:Abs Intrinsic, Up:Table of Intrinsic Functions

Access Intrinsic

Access(Name, Mode)

Access: INTEGER(KIND=1) function.

Name: CHARACTER; scalar; INTENT(IN).

Mode: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Checks file Name for accessibility in the mode specified by Mode and returns 0 if the file is accessible in that mode, otherwise an error code if the file is inaccessible or Mode is invalid. See access(2). A null character (CHAR(0)) marks the end of the name in Name--otherwise, trailing blanks in Name are ignored. Mode may be a concatenation of any of the following characters:

r
Read permission
w
Write permission
x
Execute permission
SPC
Existence


Node:AChar Intrinsic, Next:ACos Intrinsic, Previous:Access Intrinsic, Up:Table of Intrinsic Functions

AChar Intrinsic

AChar(I)

AChar: CHARACTER*1 function.

I: INTEGER; scalar; INTENT(IN).

Intrinsic groups: f2c, f90.

Description:

Returns the ASCII character corresponding to the code specified by I.

See IAChar Intrinsic, for the inverse of this function.

See Char Intrinsic, for the function corresponding to the system's native character set.


Node:ACos Intrinsic, Next:AdjustL Intrinsic, Previous:AChar Intrinsic, Up:Table of Intrinsic Functions

ACos Intrinsic

ACos(X)

ACos: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the arc-cosine (inverse cosine) of X in radians.

See Cos Intrinsic, for the inverse of this function.


Node:ACosD Intrinsic, Next:AIMax0 Intrinsic, Up:Other Intrinsics

ACosD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL ACosD to use this name for an external procedure.


Node:Adding Options, Next:Projects, Previous:Service, Up:Top

Adding Options

To add a new command-line option to g77, first decide what kind of option you wish to add. Search the g77 and gcc documentation for one or more options that is most closely like the one you want to add (in terms of what kind of effect it has, and so on) to help clarify its nature.

  • Fortran options are options that apply only when compiling Fortran programs. They are accepted by g77 and gcc, but they apply only when compiling Fortran programs.
  • Compiler options are options that apply when compiling most any kind of program.

Fortran options are listed in the file gcc/gcc/f/lang-options.h, which is used during the build of gcc to build a list of all options that are accepted by at least one language's compiler. This list goes into the documented_lang_options array in gcc/toplev.c, which uses this array to determine whether a particular option should be offered to the linked-in front end for processing by calling lang_option_decode, which, for g77, is in gcc/gcc/f/com.c and just calls ffe_decode_option.

If the linked-in front end "rejects" a particular option passed to it, toplev.c just ignores the option, because some language's compiler is willing to accept it.

This allows commands like gcc -fno-asm foo.c bar.f to work, even though Fortran compilation does not currently support the -fno-asm option; even though the f771 version of lang_decode_option rejects -fno-asm, toplev.c doesn't produce a diagnostic because some other language (C) does accept it.

This also means that commands like g77 -fno-asm foo.f yield no diagnostics, despite the fact that no phase of the command was able to recognize and process -fno-asm--perhaps a warning about this would be helpful if it were possible.

Code that processes Fortran options is found in gcc/gcc/f/top.c, function ffe_decode_option. This code needs to check positive and negative forms of each option.

The defaults for Fortran options are set in their global definitions, also found in gcc/gcc/f/top.c. Many of these defaults are actually macros defined in gcc/gcc/f/target.h, since they might be machine-specific. However, since, in practice, GNU compilers should behave the same way on all configurations (especially when it comes to language constructs), the practice of setting defaults in target.h is likely to be deprecated and, ultimately, stopped in future versions of g77.

Accessor macros for Fortran options, used by code in the g77 FFE, are defined in gcc/gcc/f/top.h.

Compiler options are listed in gcc/toplev.c in the array f_options. An option not listed in lang_options is looked up in f_options and handled from there.

The defaults for compiler options are set in the global definitions for the corresponding variables, some of which are in gcc/toplev.c.

You can set different defaults for Fortran-oriented or Fortran-reticent compiler options by changing the source code of g77 and rebuilding. How to do this depends on the version of g77:

G77 0.5.24 (EGCS 1.1)
G77 0.5.25 (EGCS 1.2 - which became GCC 2.95)
Change the lang_init_options routine in gcc/gcc/f/com.c.

(Note that these versions of g77 perform internal consistency checking automatically when the -fversion option is specified.)

G77 0.5.23
G77 0.5.24 (EGCS 1.0)
Change the way f771 handles the -fset-g77-defaults option, which is always provided as the first option when called by g77 or gcc.

This code is in ffe_decode_options in gcc/gcc/f/top.c. Have it change just the variables that you want to default to a different setting for Fortran compiles compared to compiles of other languages.

The -fset-g77-defaults option is passed to f771 automatically because of the specification information kept in gcc/gcc/f/lang-specs.h. This file tells the gcc command how to recognize, in this case, Fortran source files (those to be preprocessed, and those that are not), and further, how to invoke the appropriate programs (including f771) to process those source files.

It is in gcc/gcc/f/lang-specs.h that -fset-g77-defaults, -fversion, and other options are passed, as appropriate, even when the user has not explicitly specified them. Other "internal" options such as -quiet also are passed via this mechanism.


Node:Adjustable Arrays, Next:Alternate Entry Points, Previous:Arrays, Up:Debugging and Interfacing

Adjustable Arrays (DIMENSION)

Adjustable and automatic arrays in Fortran require the implementation (in this case, the g77 compiler) to "memorize" the expressions that dimension the arrays each time the procedure is invoked. This is so that subsequent changes to variables used in those expressions, made during execution of the procedure, do not have any effect on the dimensions of those arrays.

For example:

REAL ARRAY(5)
DATA ARRAY/5*2/
CALL X(ARRAY, 5)
END
SUBROUTINE X(A, N)
DIMENSION A(N)
N = 20
PRINT *, N, A
END

Here, the implementation should, when running the program, print something like:

20   2.  2.  2.  2.  2.

Note that this shows that while the value of N was successfully changed, the size of the A array remained at 5 elements.

To support this, g77 generates code that executes before any user code (and before the internally generated computed GOTO to handle alternate entry points, as described below) that evaluates each (nonconstant) expression in the list of subscripts for an array, and saves the result of each such evaluation to be used when determining the size of the array (instead of re-evaluating the expressions).

So, in the above example, when X is first invoked, code is executed that copies the value of N to a temporary. And that same temporary serves as the actual high bound for the single dimension of the A array (the low bound being the constant 1). Since the user program cannot (legitimately) change the value of the temporary during execution of the procedure, the size of the array remains constant during each invocation.

For alternate entry points, the code g77 generates takes into account the possibility that a dummy adjustable array is not actually passed to the actual entry point being invoked at that time. In that case, the public procedure implementing the entry point passes to the master private procedure implementing all the code for the entry points a NULL pointer where a pointer to that adjustable array would be expected. The g77-generated code doesn't attempt to evaluate any of the expressions in the subscripts for an array if the pointer to that array is NULL at run time in such cases. (Don't depend on this particular implementation by writing code that purposely passes NULL pointers where the callee expects adjustable arrays, even if you know the callee won't reference the arrays--nor should you pass NULL pointers for any dummy arguments used in calculating the bounds of such arrays or leave undefined any values used for that purpose in COMMON--because the way g77 implements these things might change in the future!)


Node:AdjustL Intrinsic, Next:AdjustR Intrinsic, Previous:ACos Intrinsic, Up:Table of Intrinsic Functions

AdjustL Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL AdjustL to use this name for an external procedure.


Node:AdjustR Intrinsic, Next:AImag Intrinsic, Previous:AdjustL Intrinsic, Up:Table of Intrinsic Functions

AdjustR Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL AdjustR to use this name for an external procedure.


Node:AImag Intrinsic, Next:AInt Intrinsic, Previous:AdjustR Intrinsic, Up:Table of Intrinsic Functions

AImag Intrinsic

AImag(Z)

AImag: REAL function. This intrinsic is valid when argument Z is COMPLEX(KIND=1). When Z is any other COMPLEX type, this intrinsic is valid only when used as the argument to REAL(), as explained below.

Z: COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the (possibly converted) imaginary part of Z.

Use of AIMAG() with an argument of a type other than COMPLEX(KIND=1) is restricted to the following case:

REAL(AIMAG(Z))

This expression converts the imaginary part of Z to REAL(KIND=1).

See REAL() and AIMAG() of Complex, for more information.


Node:AIMax0 Intrinsic, Next:AIMin0 Intrinsic, Previous:ACosD Intrinsic, Up:Other Intrinsics

AIMax0 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL AIMax0 to use this name for an external procedure.


Node:AIMin0 Intrinsic, Next:AJMax0 Intrinsic, Previous:AIMax0 Intrinsic, Up:Other Intrinsics

AIMin0 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL AIMin0 to use this name for an external procedure.


Node:AInt Intrinsic, Next:Alarm Intrinsic, Previous:AImag Intrinsic, Up:Table of Intrinsic Functions

AInt Intrinsic

AInt(A)

AInt: REAL function, the KIND= value of the type being that of argument A.

A: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns A with the fractional portion of its magnitude truncated and its sign preserved. (Also called "truncation towards zero".)

See ANInt Intrinsic, for how to round to nearest whole number.

See Int Intrinsic, for how to truncate and then convert number to INTEGER.


Node:AJMax0 Intrinsic, Next:AJMin0 Intrinsic, Previous:AIMin0 Intrinsic, Up:Other Intrinsics

AJMax0 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL AJMax0 to use this name for an external procedure.


Node:AJMin0 Intrinsic, Next:ASinD Intrinsic, Previous:AJMax0 Intrinsic, Up:Other Intrinsics

AJMin0 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL AJMin0 to use this name for an external procedure.


Node:Alarm Intrinsic, Next:All Intrinsic, Previous:AInt Intrinsic, Up:Table of Intrinsic Functions

Alarm Intrinsic

CALL Alarm(Seconds, Handler, Status)

Seconds: INTEGER; scalar; INTENT(IN).

Handler: Signal handler (INTEGER FUNCTION or SUBROUTINE) or dummy/global INTEGER(KIND=1) scalar.

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Causes external subroutine Handler to be executed after a delay of Seconds seconds by using alarm(1) to set up a signal and signal(2) to catch it. If Status is supplied, it will be returned with the number of seconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm. See Signal Intrinsic (subroutine).


Node:Aliasing Assumed To Work, Next:Output Assumed To Flush, Previous:Surprising Interpretations of Code, Up:Working Programs

Aliasing Assumed To Work

The -falias-check, -fargument-alias, -fargument-noalias, and -fno-argument-noalias-global options, introduced in version 0.5.20 and g77's version 2.7.2.2.f.2 of gcc, were withdrawn as of g77 version 0.5.23 due to their not being supported by gcc version 2.8.

These options control the assumptions regarding aliasing (overlapping) of writes and reads to main memory (core) made by the gcc back end.

The information below still is useful, but applies to only those versions of g77 that support the alias analysis implied by support for these options.

These options are effective only when compiling with -O (specifying any level other than -O0) or with -falias-check.

The default for Fortran code is -fargument-noalias-global. (The default for C code and code written in other C-based languages is -fargument-alias. These defaults apply regardless of whether you use g77 or gcc to compile your code.)

Note that, on some systems, compiling with -fforce-addr in effect can produce more optimal code when the default aliasing options are in effect (and when optimization is enabled).

If your program is not working when compiled with optimization, it is possible it is violating the Fortran standards (77 and 90) by relying on the ability to "safely" modify variables and arrays that are aliased, via procedure calls, to other variables and arrays, without using EQUIVALENCE to explicitly set up this kind of aliasing.

(The FORTRAN 77 standard's prohibition of this sort of overlap, generally referred to therein as "storage assocation", appears in Sections 15.9.3.6. This prohibition allows implementations, such as g77, to, for example, implement the passing of procedures and even values in COMMON via copy operations into local, perhaps more efficiently accessed temporaries at entry to a procedure, and, where appropriate, via copy operations back out to their original locations in memory at exit from that procedure, without having to take into consideration the order in which the local copies are updated by the code, among other things.)

To test this hypothesis, try compiling your program with the -fargument-alias option, which causes the compiler to revert to assumptions essentially the same as made by versions of g77 prior to 0.5.20.

If the program works using this option, that strongly suggests that the bug is in your program. Finding and fixing the bug(s) should result in a program that is more standard-conforming and that can be compiled by g77 in a way that results in a faster executable.

(You might want to try compiling with -fargument-noalias, a kind of half-way point, to see if the problem is limited to aliasing between dummy arguments and COMMON variables--this option assumes that such aliasing is not done, while still allowing aliasing among dummy arguments.)

An example of aliasing that is invalid according to the standards is shown in the following program, which might not produce the expected results when executed:

I = 1
CALL FOO(I, I)
PRINT *, I
END

SUBROUTINE FOO(J, K)
J = J + K
K = J * K
PRINT *, J, K
END

The above program attempts to use the temporary aliasing of the J and K arguments in FOO to effect a pathological behavior--the simultaneous changing of the values of both J and K when either one of them is written.

The programmer likely expects the program to print these values:

2  4
4

However, since the program is not standard-conforming, an implementation's behavior when running it is undefined, because subroutine FOO modifies at least one of the arguments, and they are aliased with each other. (Even if one of the assignment statements was deleted, the program would still violate these rules. This kind of on-the-fly aliasing is permitted by the standard only when none of the aliased items are defined, or written, while the aliasing is in effect.)

As a practical example, an optimizing compiler might schedule the J = part of the second line of FOO after the reading of J and K for the J * K expression, resulting in the following output:

2  2
2

Essentially, compilers are promised (by the standard and, therefore, by programmers who write code they claim to be standard-conforming) that if they cannot detect aliasing via static analysis of a single program unit's EQUIVALENCE and COMMON statements, no such aliasing exists. In such cases, compilers are free to assume that an assignment to one variable will not change the value of another variable, allowing it to avoid generating code to re-read the value of the other variable, to re-schedule reads and writes, and so on, to produce a faster executable.

The same promise holds true for arrays (as seen by the called procedure)--an element of one dummy array cannot be aliased with, or overlap, any element of another dummy array or be in a COMMON area known to the procedure.

(These restrictions apply only when the procedure defines, or writes to, one of the aliased variables or arrays.)

Unfortunately, there is no way to find all possible cases of violations of the prohibitions against aliasing in Fortran code. Static analysis is certainly imperfect, as is run-time analysis, since neither can catch all violations. (Static analysis can catch all likely violations, and some that might never actually happen, while run-time analysis can catch only those violations that actually happen during a particular run. Neither approach can cope with programs mixing Fortran code with routines written in other languages, however.)

Currently, g77 provides neither static nor run-time facilities to detect any cases of this problem, although other products might. Run-time facilities are more likely to be offered by future versions of g77, though patches improving g77 so that it provides either form of detection are welcome.


Node:Aligned Data, Next:Prefer Automatic Uninitialized Variables, Up:Faster Programs

Aligned Data

On some systems, such as those with Pentium Pro CPUs, programs that make heavy use of REAL(KIND=2) (DOUBLE PRECISION) might run much slower than possible due to the compiler not aligning these 64-bit values to 64-bit boundaries in memory. (The effect also is present, though to a lesser extent, on the 586 (Pentium) architecture.)

The Intel x86 architecture generally ensures that these programs will work on all its implementations, but particular implementations (such as Pentium Pro) perform better with more strict alignment. (Such behavior isn't unique to the Intel x86 architecture.) Other architectures might demand 64-bit alignment of 64-bit data.

There are a variety of approaches to use to address this problem:

  • Order your COMMON and EQUIVALENCE areas such that the variables and arrays with the widest alignment guidelines come first.

    For example, on most systems, this would mean placing
COMPLEX(KIND=2), REAL(KIND=2), and
INTEGER(KIND=2) entities first, followed by REAL(KIND=1),
INTEGER(KIND=1), and LOGICAL(KIND=1) entities, then
INTEGER(KIND=6) entities, and finally CHARACTER
and INTEGER(KIND=3) entities.

    The reason to use such placement is it makes it more likely that your data will be aligned properly, without requiring you to do detailed analysis of each aggregate (COMMON and EQUIVALENCE) area.

    Specifically, on systems where the above guidelines are appropriate, placing CHARACTER entities before REAL(KIND=2) entities can work just as well, but only if the number of bytes occupied by the CHARACTER entities is divisible by the recommended alignment for REAL(KIND=2).

    By ordering the placement of entities in aggregate areas according to the simple guidelines above, you avoid having to carefully count the number of bytes occupied by each entity to determine whether the actual alignment of each subsequent entity meets the alignment guidelines for the type of that entity.

    If you don't ensure correct alignment of COMMON elements, the compiler may be forced by some systems to violate the Fortran semantics by adding padding to get DOUBLE PRECISION data properly aligned. If the unfortunate practice is employed of overlaying different types of data in the COMMON block, the different variants of this block may become misaligned with respect to each other. Even if your platform doesn't require strict alignment, COMMON should be laid out as above for portability. (Unfortunately the FORTRAN 77 standard didn't anticipate this possible requirement, which is compiler-independent on a given platform.)

  • Use the (x86-specific) -malign-double option when compiling programs for the Pentium and Pentium Pro architectures (called 586 and 686 in the gcc configuration subsystem). The warning about this in the gcc manual isn't generally relevant to Fortran, but using it will force COMMON to be padded if necessary to align DOUBLE PRECISION data.

    When DOUBLE PRECISION data is forcibly aligned in COMMON by g77 due to specifying -malign-double, g77 issues a warning about the need to insert padding.

    In this case, each and every program unit that uses the same COMMON area must specify the same layout of variables and their types for that area and be compiled with -malign-double as well. g77 will issue warnings in each case, but as long as every program unit using that area is compiled with the same warnings, the resulting object files should work when linked together unless the program makes additional assumptions about COMMON area layouts that are outside the scope of the FORTRAN 77 standard, or uses EQUIVALENCE or different layouts in ways that assume no padding is ever inserted by the compiler.

  • Ensure that crt0.o or crt1.o on your system guarantees a 64-bit aligned stack for main(). The recent one from GNU (glibc2) will do this on x86 systems, but we don't know of any other x86 setups where it will be right. Read your system's documentation to determine if it is appropriate to upgrade to a more recent version to obtain the optimal alignment.

Progress is being made on making this work "out of the box" on future versions of g77, gcc, and some of the relevant operating systems (such as GNU/Linux).

A package that tests the degree to which a Fortran compiler (such as g77) aligns 64-bit floating-point variables and arrays is available at ftp://alpha.gnu.org/gnu/g77/align/.


Node:All Intrinsic, Next:Allocated Intrinsic, Previous:Alarm Intrinsic, Up:Table of Intrinsic Functions

All Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL All to use this name for an external procedure.


Node:Allocated Intrinsic, Next:ALog Intrinsic, Previous:All Intrinsic, Up:Table of Intrinsic Functions

Allocated Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Allocated to use this name for an external procedure.


Node:ALog Intrinsic, Next:ALog10 Intrinsic, Previous:Allocated Intrinsic, Up:Table of Intrinsic Functions

ALog Intrinsic

ALog(X)

ALog: REAL(KIND=1) function.

X: REAL(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of LOG() that is specific to one type for X. See Log Intrinsic.


Node:ALog10 Intrinsic, Next:AMax0 Intrinsic, Previous:ALog Intrinsic, Up:Table of Intrinsic Functions

ALog10 Intrinsic

ALog10(X)

ALog10: REAL(KIND=1) function.

X: REAL(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of LOG10() that is specific to one type for X. See Log10 Intrinsic.


Node:Alternate Entry Points, Next:Alternate Returns, Previous:Adjustable Arrays, Up:Debugging and Interfacing

Alternate Entry Points (ENTRY)

The GBE does not understand the general concept of alternate entry points as Fortran provides via the ENTRY statement. g77 gets around this by using an approach to compiling procedures having at least one ENTRY statement that is almost identical to the approach used by f2c. (An alternate approach could be used that would probably generate faster, but larger, code that would also be a bit easier to debug.)

Information on how g77 implements ENTRY is provided for those trying to debug such code. The choice of implementation seems unlikely to affect code (compiled in other languages) that interfaces to such code.

g77 compiles exactly one public procedure for the primary entry point of a procedure plus each ENTRY point it specifies, as usual. That is, in terms of the public interface, there is no difference between

SUBROUTINE X
END
SUBROUTINE Y
END

and:

SUBROUTINE X
ENTRY Y
END

The difference between the above two cases lies in the code compiled for the X and Y procedures themselves, plus the fact that, for the second case, an extra internal procedure is compiled.

For every Fortran procedure with at least one ENTRY statement, g77 compiles an extra procedure named __g77_masterfun_x, where x is the name of the primary entry point (which, in the above case, using the standard compiler options, would be x_ in C).

This extra procedure is compiled as a private procedure--that is, a procedure not accessible by name to separately compiled modules. It contains all the code in the program unit, including the code for the primary entry point plus for every entry point. (The code for each public procedure is quite short, and explained later.)

The extra procedure has some other interesting characteristics.

The argument list for this procedure is invented by g77. It contains a single integer argument named __g77_which_entrypoint, passed by value (as in Fortran's %VAL() intrinsic), specifying the entry point index--0 for the primary entry point, 1 for the first entry point (the first ENTRY statement encountered), 2 for the second entry point, and so on.

It also contains, for functions returning CHARACTER and (when -ff2c is in effect) COMPLEX functions, and for functions returning different types among the ENTRY statements (e.g. REAL FUNCTION R() containing ENTRY I()), an argument named __g77_result that is expected at run time to contain a pointer to where to store the result of the entry point. For CHARACTER functions, this storage area is an array of the appropriate number of characters; for COMPLEX functions, it is the appropriate area for the return type; for multiple-return-type functions, it is a union of all the supported return types (which cannot include CHARACTER, since combining CHARACTER and non-CHARACTER return types via ENTRY in a single function is not supported by g77).

For CHARACTER functions, the __g77_result argument is followed by yet another argument named __g77_length that, at run time, specifies the caller's expected length of the returned value. Note that only CHARACTER*(*) functions and entry points actually make use of this argument, even though it is always passed by all callers of public CHARACTER functions (since the caller does not generally know whether such a function is CHARACTER*(*) or whether there are any other callers that don't have that information).

The rest of the argument list is the union of all the arguments specified for all the entry points (in their usual forms, e.g. CHARACTER arguments have extra length arguments, all appended at the end of this list). This is considered the "master list" of arguments.

The code for this procedure has, before the code for the first executable statement, code much like that for the following Fortran statement:

       GOTO (100000,100001,100002), __g77_which_entrypoint
100000 ...code for primary entry point...
100001 ...code immediately following first ENTRY statement...
100002 ...code immediately following second ENTRY statement...

(Note that invalid Fortran statement labels and variable names are used in the above example to highlight the fact that it represents code generated by the g77 internals, not code to be written by the user.)

It is this code that, when the procedure is called, picks which entry point to start executing.

Getting back to the public procedures (x and Y in the original example), those procedures are fairly simple. Their interfaces are just like they would be if they were self-contained procedures (without ENTRY), of course, since that is what the callers expect. Their code consists of simply calling the private procedure, described above, with the appropriate extra arguments (the entry point index, and perhaps a pointer to a multiple-type- return variable, local to the public procedure, that contains all the supported returnable non-character types). For arguments that are not listed for a given entry point that are listed for other entry points, and therefore that are in the "master list" for the private procedure, null pointers (in C, the NULL macro) are passed. Also, for entry points that are part of a multiple-type- returning function, code is compiled after the call of the private procedure to extract from the multi-type union the appropriate result, depending on the type of the entry point in question, returning that result to the original caller.

When debugging a procedure containing alternate entry points, you can either set a break point on the public procedure itself (e.g. a break point on X or Y) or on the private procedure that contains most of the pertinent code (e.g. __g77_masterfun_x). If you do the former, you should use the debugger's command to "step into" the called procedure to get to the actual code; with the latter approach, the break point leaves you right at the actual code, skipping over the public entry point and its call to the private procedure (unless you have set a break point there as well, of course).

Further, the list of dummy arguments that is visible when the private procedure is active is going to be the expanded version of the list for whichever particular entry point is active, as explained above, and the way in which return values are handled might well be different from how they would be handled for an equivalent single-entry function.


Node:Alternate Returns, Next:Assigned Statement Labels, Previous:Alternate Entry Points, Up:Debugging and Interfacing

Alternate Returns (SUBROUTINE and RETURN)

Subroutines with alternate returns (e.g. SUBROUTINE X(*) and CALL X(*50)) are implemented by g77 as functions returning the C int type. The actual alternate-return arguments are omitted from the calling sequence. Instead, the caller uses the return value to do a rough equivalent of the Fortran computed-GOTO statement, as in GOTO (50), X() in the example above (where X is quietly declared as an INTEGER(KIND=1) function), and the callee just returns whatever integer is specified in the RETURN statement for the subroutine For example, RETURN 1 is implemented as X = 1 followed by RETURN in C, and RETURN by itself is X = 0 and RETURN).


Node:AMax0 Intrinsic, Next:AMax1 Intrinsic, Previous:ALog10 Intrinsic, Up:Table of Intrinsic Functions

AMax0 Intrinsic

AMax0(A-1, A-2, ..., A-n)

AMax0: REAL(KIND=1) function.

A: INTEGER(KIND=1); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MAX() that is specific to one type for A and a different return type. See Max Intrinsic.


Node:AMax1 Intrinsic, Next:AMin0 Intrinsic, Previous:AMax0 Intrinsic, Up:Table of Intrinsic Functions

AMax1 Intrinsic

AMax1(A-1, A-2, ..., A-n)

AMax1: REAL(KIND=1) function.

A: REAL(KIND=1); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MAX() that is specific to one type for A. See Max Intrinsic.


Node:Ambiguous Dialects, Next:Unused Labels, Previous:Invalid FORMAT Specifiers, Up:Missing Features

Ambiguous Dialects

g77 needs a set of options such as -Wugly*, -Wautomatic, -Wvxt, -Wf90, and so on. These would warn about places in the user's source where ambiguities are found, helpful in resolving ambiguities in the program's dialect or dialects.


Node:AMin0 Intrinsic, Next:AMin1 Intrinsic, Previous:AMax1 Intrinsic, Up:Table of Intrinsic Functions

AMin0 Intrinsic

AMin0(A-1, A-2, ..., A-n)

AMin0: REAL(KIND=1) function.

A: INTEGER(KIND=1); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MIN() that is specific to one type for A and a different return type. See Min Intrinsic.


Node:AMin1 Intrinsic, Next:AMod Intrinsic, Previous:AMin0 Intrinsic, Up:Table of Intrinsic Functions

AMin1 Intrinsic

AMin1(A-1, A-2, ..., A-n)

AMin1: REAL(KIND=1) function.

A: REAL(KIND=1); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MIN() that is specific to one type for A. See Min Intrinsic.


Node:AMod Intrinsic, Next:And Intrinsic, Previous:AMin1 Intrinsic, Up:Table of Intrinsic Functions

AMod Intrinsic

AMod(A, P)

AMod: REAL(KIND=1) function.

A: REAL(KIND=1); scalar; INTENT(IN).

P: REAL(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MOD() that is specific to one type for A. See Mod Intrinsic.


Node:Ampersands, Previous:Long Lines, Up:Source Form

Ampersand Continuation Line

A & in column 1 of fixed-form source denotes an arbitrary-length continuation line, imitating the behavior of f2c.


Node:And Intrinsic, Next:ANInt Intrinsic, Previous:AMod Intrinsic, Up:Table of Intrinsic Functions

And Intrinsic

And(I, J)

And: INTEGER or LOGICAL function, the exact type being the result of cross-promoting the types of all the arguments.

I: INTEGER or LOGICAL; scalar; INTENT(IN).

J: INTEGER or LOGICAL; scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Returns value resulting from boolean AND of pair of bits in each of I and J.


Node:ANInt Intrinsic, Next:Any Intrinsic, Previous:And Intrinsic, Up:Table of Intrinsic Functions

ANInt Intrinsic

ANInt(A)

ANInt: REAL function, the KIND= value of the type being that of argument A.

A: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns A with the fractional portion of its magnitude eliminated by rounding to the nearest whole number and with its sign preserved.

A fractional portion exactly equal to .5 is rounded to the whole number that is larger in magnitude. (Also called "Fortran round".)

See AInt Intrinsic, for how to truncate to whole number.

See NInt Intrinsic, for how to round and then convert number to INTEGER.


Node:Any Intrinsic, Next:ASin Intrinsic, Previous:ANInt Intrinsic, Up:Table of Intrinsic Functions

Any Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Any to use this name for an external procedure.


Node:Arbitrary Concatenation, Next:SELECT CASE on CHARACTER Type, Previous:Intrinsics in PARAMETER Statements, Up:Missing Features

Arbitrary Concatenation

g77 doesn't support arbitrary operands for concatenation in contexts where run-time allocation is required. For example:

SUBROUTINE X(A)
CHARACTER*(*) A
CALL FOO(A // 'suffix')


Node:Array Bounds Expressions, Next:POINTER Statements, Previous:Full Support for Compiler Types, Up:Missing Features

Array Bounds Expressions

g77 doesn't support more general expressions to dimension arrays, such as array element references, function references, etc.

For example, g77 currently does not accept the following:

SUBROUTINE X(M, N)
INTEGER N(10), M(N(2), N(1))


Node:Array Size, Next:Character-variable Length, Previous:Year 2000 (Y2K) Problems, Up:Run-time Environment Limits

Array Size

Currently, g77 uses the default INTEGER type for array indexes, which limits the sizes of single-dimension arrays on systems offering a larger address space than can be addressed by that type. (That g77 puts all arrays in memory could be considered another limitation--it could use large temporary files--but that decision is left to the programmer as an implementation choice by most Fortran implementations.)

It is not yet clear whether this limitation never, sometimes, or always applies to the sizes of multiple-dimension arrays as a whole.

For example, on a system with 64-bit addresses and 32-bit default INTEGER, an array with a size greater than can be addressed by a 32-bit offset can be declared using multiple dimensions. Such an array is therefore larger than a single-dimension array can be, on the same system.

Whether large multiple-dimension arrays are reliably supported depends mostly on the gcc back end (code generator) used by g77, and has not yet been fully investigated.


Node:Arrays, Next:Adjustable Arrays, Previous:Complex Variables, Up:Debugging and Interfacing

Arrays (DIMENSION)

Fortran uses "column-major ordering" in its arrays. This differs from other languages, such as C, which use "row-major ordering". The difference is that, with Fortran, array elements adjacent to each other in memory differ in the first subscript instead of the last; A(5,10,20) immediately follows A(4,10,20), whereas with row-major ordering it would follow A(5,10,19).

This consideration affects not only interfacing with and debugging Fortran code, it can greatly affect how code is designed and written, especially when code speed and size is a concern.

Fortran also differs from C, a popular language for interfacing and to support directly in debuggers, in the way arrays are treated. In C, arrays are single-dimensional and have interesting relationships to pointers, neither of which is true for Fortran. As a result, dealing with Fortran arrays from within an environment limited to C concepts can be challenging.

For example, accessing the array element A(5,10,20) is easy enough in Fortran (use A(5,10,20)), but in C some difficult machinations are needed. First, C would treat the A array as a single-dimension array. Second, C does not understand low bounds for arrays as does Fortran. Third, C assumes a low bound of zero (0), while Fortran defaults to a low bound of one (1) and can supports an arbitrary low bound. Therefore, calculations must be done to determine what the C equivalent of A(5,10,20) would be, and these calculations require knowing the dimensions of A.

For DIMENSION A(2:11,21,0:29), the calculation of the offset of A(5,10,20) would be:

  (5-2)
+ (10-1)*(11-2+1)
+ (20-0)*(11-2+1)*(21-1+1)
= 4293

So the C equivalent in this case would be a[4293].

When using a debugger directly on Fortran code, the C equivalent might not work, because some debuggers cannot understand the notion of low bounds other than zero. However, unlike f2c, g77 does inform the GBE that a multi-dimensional array (like A in the above example) is really multi-dimensional, rather than a single-dimensional array, so at least the dimensionality of the array is preserved.

Debuggers that understand Fortran should have no trouble with non-zero low bounds, but for non-Fortran debuggers, especially C debuggers, the above example might have a C equivalent of a[4305]. This calculation is arrived at by eliminating the subtraction of the lower bound in the first parenthesized expression on each line--that is, for (5-2) substitute (5), for (10-1) substitute (10), and for (20-0) substitute (20). Actually, the implication of this can be that the expression *(&a[2][1][0] + 4293) works fine, but that a[20][10][5] produces the equivalent of *(&a[0][0][0] + 4305) because of the missing lower bounds.

Come to think of it, perhaps the behavior is due to the debugger internally compensating for the lower bounds by offsetting the base address of a, leaving &a set lower, in this case, than &a[2][1][0] (the address of its first element as identified by subscripts equal to the corresponding lower bounds).

You know, maybe nobody really needs to use arrays.


Node:ASin Intrinsic, Next:Associated Intrinsic, Previous:Any Intrinsic, Up:Table of Intrinsic Functions

ASin Intrinsic

ASin(X)

ASin: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the arc-sine (inverse sine) of X in radians.

See Sin Intrinsic, for the inverse of this function.


Node:ASinD Intrinsic, Next:ATan2D Intrinsic, Previous:AJMin0 Intrinsic, Up:Other Intrinsics

ASinD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL ASinD to use this name for an external procedure.


Node:Assigned Statement Labels, Next:Run-time Library Errors, Previous:Alternate Returns, Up:Debugging and Interfacing

Assigned Statement Labels (ASSIGN and GOTO)

For portability to machines where a pointer (such as to a label, which is how g77 implements ASSIGN and its relatives, the assigned-GOTO and assigned-FORMAT-I/O statements) is wider (bitwise) than an INTEGER(KIND=1), g77 uses a different memory location to hold the ASSIGNed value of a variable than it does the numerical value in that variable, unless the variable is wide enough (can hold enough bits).

In particular, while g77 implements

I = 10

as, in C notation, i = 10;, it implements

ASSIGN 10 TO I

as, in GNU's extended C notation (for the label syntax), __g77_ASSIGN_I = &&L10; (where L10 is just a massaging of the Fortran label 10 to make the syntax C-like; g77 doesn't actually generate the name L10 or any other name like that, since debuggers cannot access labels anyway).

While this currently means that an ASSIGN statement does not overwrite the numeric contents of its target variable, do not write any code depending on this feature. g77 has already changed this implementation across versions and might do so in the future. This information is provided only to make debugging Fortran programs compiled with the current version of g77 somewhat easier. If there's no debugger-visible variable named __g77_ASSIGN_I in a program unit that does ASSIGN 10 TO I, that probably means g77 has decided it can store the pointer to the label directly into I itself.

See Ugly Assigned Labels, for information on a command-line option to force g77 to use the same storage for both normal and assigned-label uses of a variable.


Node:Associated Intrinsic, Next:ATan Intrinsic, Previous:ASin Intrinsic, Up:Table of Intrinsic Functions

Associated Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Associated to use this name for an external procedure.


Node:ATan Intrinsic, Next:ATan2 Intrinsic, Previous:Associated Intrinsic, Up:Table of Intrinsic Functions

ATan Intrinsic

ATan(X)

ATan: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the arc-tangent (inverse tangent) of X in radians.

See Tan Intrinsic, for the inverse of this function.


Node:ATan2 Intrinsic, Next:BesJ0 Intrinsic, Previous:ATan Intrinsic, Up:Table of Intrinsic Functions

ATan2 Intrinsic

ATan2(Y, X)

ATan2: REAL function, the exact type being the result of cross-promoting the types of all the arguments.

Y: REAL; scalar; INTENT(IN).

X: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the arc-tangent (inverse tangent) of the complex number (Y, X) in radians.

See Tan Intrinsic, for the inverse of this function.


Node:ATan2D Intrinsic, Next:ATanD Intrinsic, Previous:ASinD Intrinsic, Up:Other Intrinsics

ATan2D Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL ATan2D to use this name for an external procedure.


Node:ATanD Intrinsic, Next:BITest Intrinsic, Previous:ATan2D Intrinsic, Up:Other Intrinsics

ATanD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL ATanD to use this name for an external procedure.


Node:AUTOMATIC Statement, Next:Suppressing Space Padding, Previous:ENCODE and DECODE, Up:Missing Features

AUTOMATIC Statement

g77 doesn't support the AUTOMATIC statement that f2c does.

AUTOMATIC would identify a variable or array as not being SAVE'd, which is normally the default, but which would be especially useful for code that, generally, needed to be compiled with the -fno-automatic option.

AUTOMATIC also would serve as a hint to the compiler that placing the variable or array--even a very large array-on the stack is acceptable.

AUTOMATIC would not, by itself, designate the containing procedure as recursive.

AUTOMATIC should work syntactically like SAVE, in that AUTOMATIC with no variables listed should apply to all pertinent variables and arrays (which would not include common blocks or their members).

Variables and arrays denoted as AUTOMATIC would not be permitted to be initialized via DATA or other specification of any initial values, requiring explicit initialization, such as via assignment statements.

Perhaps UNSAVE and STATIC, as strict semantic opposites to SAVE and AUTOMATIC, should be provided as well.


Node:Avoid f2c Compatibility, Next:Use Submodel Options, Previous:Prefer Automatic Uninitialized Variables, Up:Faster Programs

Avoid f2c Compatibility

If you aren't linking with any code compiled using f2c, try using the -fno-f2c option when compiling all the code in your program. (Note that libf2c is not an example of code that is compiled using f2c--it is compiled by a C compiler, typically gcc.)


Node:Backslash in Constants, Next:Initializing Before Specifying, Up:Non-bugs

Backslash in Constants

In the opinion of many experienced Fortran users, -fno-backslash should be the default, not -fbackslash, as currently set by g77.

First of all, you can always specify -fno-backslash to turn off this processing.

Despite not being within the spirit (though apparently within the letter) of the ANSI FORTRAN 77 standard, g77 defaults to -fbackslash because that is what most UNIX f77 commands default to, and apparently lots of code depends on this feature.

This is a particularly troubling issue. The use of a C construct in the midst of Fortran code is bad enough, worse when it makes existing Fortran programs stop working (as happens when programs written for non-UNIX systems are ported to UNIX systems with compilers that provide the -fbackslash feature as the default--sometimes with no option to turn it off).

The author of GNU Fortran wished, for reasons of linguistic purity, to make -fno-backslash the default for GNU Fortran and thus require users of UNIX f77 and f2c to specify -fbackslash to get the UNIX behavior.

However, the realization that g77 is intended as a replacement for UNIX f77, caused the author to choose to make g77 as compatible with f77 as feasible, which meant making -fbackslash the default.

The primary focus on compatibility is at the source-code level, and the question became "What will users expect a replacement for f77 to do, by default?" Although at least one UNIX f77 does not provide -fbackslash as a default, it appears that the majority of them do, which suggests that the majority of code that is compiled by UNIX f77 compilers expects -fbackslash to be the default.

It is probably the case that more code exists that would not work with -fbackslash in force than code that requires it be in force.

However, most of that code is not being compiled with f77, and when it is, new build procedures (shell scripts, makefiles, and so on) must be set up anyway so that they work under UNIX. That makes a much more natural and safe opportunity for non-UNIX users to adapt their build procedures for g77's default of -fbackslash than would exist for the majority of UNIX f77 users who would have to modify existing, working build procedures to explicitly specify -fbackslash if that was not the default.

One suggestion has been to configure the default for -fbackslash (and perhaps other options as well) based on the configuration of g77.

This is technically quite straightforward, but will be avoided even in cases where not configuring defaults to be dependent on a particular configuration greatly inconveniences some users of legacy code.

Many users appreciate the GNU compilers because they provide an environment that is uniform across machines. These users would be inconvenienced if the compiler treated things like the format of the source code differently on certain machines.

Occasionally users write programs intended only for a particular machine type. On these occasions, the users would benefit if the GNU Fortran compiler were to support by default the same dialect as the other compilers on that machine. But such applications are rare. And users writing a program to run on more than one type of machine cannot possibly benefit from this kind of compatibility. (This is consistent with the design goals for gcc. To change them for g77, you must first change them for gcc. Do not ask the maintainers of g77 to do this for you, or to disassociate g77 from the widely understood, if not widely agreed-upon, goals for GNU compilers in general.)

This is why GNU Fortran does and will treat backslashes in the same fashion on all types of machines (by default). See Direction of Language Development, for more information on this overall philosophy guiding the development of the GNU Fortran language.

Of course, users strongly concerned about portability should indicate explicitly in their build procedures which options are expected by their source code, or write source code that has as few such expectations as possible.

For example, avoid writing code that depends on backslash (\) being interpreted either way in particular, such as by starting a program unit with:

CHARACTER BACKSL
PARAMETER (BACKSL = '\\')

Then, use concatenation of BACKSL anyplace a backslash is desired. In this way, users can write programs which have the same meaning in many Fortran dialects.

(However, this technique does not work for Hollerith constants--which is just as well, since the only generally portable uses for Hollerith constants are in places where character constants can and should be used instead, for readability.)


Node:BesJ0 Intrinsic, Next:BesJ1 Intrinsic, Previous:ATan2 Intrinsic, Up:Table of Intrinsic Functions

BesJ0 Intrinsic

BesJ0(X)

BesJ0: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Calculates the Bessel function of the first kind of order 0 of X. See bessel(3m), on whose implementation the function depends.


Node:BesJ1 Intrinsic, Next:BesJN Intrinsic, Previous:BesJ0 Intrinsic, Up:Table of Intrinsic Functions

BesJ1 Intrinsic

BesJ1(X)

BesJ1: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Calculates the Bessel function of the first kind of order 1 of X. See bessel(3m), on whose implementation the function depends.


Node:BesJN Intrinsic, Next:BesY0 Intrinsic, Previous:BesJ1 Intrinsic, Up:Table of Intrinsic Functions

BesJN Intrinsic

BesJN(N, X)

BesJN: REAL function, the KIND= value of the type being that of argument X.

N: INTEGER not wider than the default kind; scalar; INTENT(IN).

X: REAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Calculates the Bessel function of the first kind of order N of X. See bessel(3m), on whose implementation the function depends.


Node:BesY0 Intrinsic, Next:BesY1 Intrinsic, Previous:BesJN Intrinsic, Up:Table of Intrinsic Functions

BesY0 Intrinsic

BesY0(X)

BesY0: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Calculates the Bessel function of the second kind of order 0 of X. See bessel(3m), on whose implementation the function depends.


Node:BesY1 Intrinsic, Next:BesYN Intrinsic, Previous:BesY0 Intrinsic, Up:Table of Intrinsic Functions

BesY1 Intrinsic

BesY1(X)

BesY1: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Calculates the Bessel function of the second kind of order 1 of X. See bessel(3m), on whose implementation the function depends.


Node:BesYN Intrinsic, Next:Bit_Size Intrinsic, Previous:BesY1 Intrinsic, Up:Table of Intrinsic Functions

BesYN Intrinsic

BesYN(N, X)

BesYN: REAL function, the KIND= value of the type being that of argument X.

N: INTEGER not wider than the default kind; scalar; INTENT(IN).

X: REAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Calculates the Bessel function of the second kind of order N of X. See bessel(3m), on whose implementation the function depends.


Node:Better Diagnostics, Previous:Internals Improvements, Up:Projects

Better Diagnostics

These are things users might not ask about, or that need to be looked into, before worrying about. Also here are items that involve reducing unnecessary diagnostic clutter.

  • When FUNCTION and ENTRY point types disagree (CHARACTER lengths, type classes, and so on), ANY-ize the offending ENTRY point and any new dummies it specifies.
  • Speed up and improve error handling for data when repeat-count is specified. For example, don't output 20 unnecessary messages after the first necessary one for:
    INTEGER X(20)
CONTINUE
DATA (X(I), J= 1, 20) /20*5/
END

    (The CONTINUE statement ensures the DATA statement is processed in the context of executable, not specification, statements.)


Node:Better List-directed I/O, Next:Default to Console I/O, Previous:Portable Unformatted Files, Up:Missing Features

Better List-directed I/O

Values output using list-directed I/O (PRINT *, R, D) should be written with a field width, precision, and so on appropriate for the type (precision) of each value.

(Currently, no distinction is made between single-precision and double-precision values by libf2c.)

It is likely this item will require the libg77 project to be undertaken.

In the meantime, use of formatted I/O is recommended. While it might be of little consolation, g77 does support FORMAT(F<WIDTH>.4), for example, as long as WIDTH is defined as a named constant (via PARAMETER). That at least allows some compile-time specification of the precision of a data type, perhaps controlled by preprocessing directives.


Node:Better Optimization, Next:Simplify Porting, Previous:Efficiency, Up:Projects

Better Optimization

Much of this work should be put off until after g77 has all the features necessary for its widespread acceptance as a useful F77 compiler. However, perhaps this work can be done in parallel during the feature-adding work.

  • Do the equivalent of the trick of putting extern inline in front of every function definition in libg2c and #include'ing the resulting file in f2c+gcc--that is, inline all run-time-library functions that are at all worth inlining. (Some of this has already been done, such as for integral exponentiation.)
  • When doing CHAR_VAR = CHAR_FUNC(...), and it's clear that types line up and CHAR_VAR is addressable or not a VAR_DECL, make CHAR_VAR, not a temporary, be the receiver for CHAR_FUNC. (This is now done for COMPLEX variables.)
  • Design and implement Fortran-specific optimizations that don't really belong in the back end, or where the front end needs to give the back end more info than it currently does.
  • Design and implement a new run-time library interface, with the code going into libgcc so no special linking is required to link Fortran programs using standard language features. This library would speed up lots of things, from I/O (using precompiled formats, doing just one, or, at most, very few, calls for arrays or array sections, and so on) to general computing (array/section implementations of various intrinsics, implementation of commonly performed loops that aren't likely to be optimally compiled otherwise, etc.).

    Among the important things the library would do are:

    • Be a one-stop-shop-type library, hence shareable and usable by all, in that what are now library-build-time options in libg2c would be moved at least to the g77 compile phase, if not to finer grains (such as choosing how list-directed I/O formatting is done by default at OPEN time, for preconnected units via options or even statements in the main program unit, maybe even on a per-I/O basis with appropriate pragma-like devices).
  • Probably requiring the new library design, change interface to normally have COMPLEX functions return their values in the way gcc would if they were declared __complex__ float, rather than using the mechanism currently used by CHARACTER functions (whereby the functions are compiled as returning void and their first arg is a pointer to where to store the result). (Don't append underscores to external names for COMPLEX functions in some cases once g77 uses gcc rather than f2c calling conventions.)
  • Do something useful with doiter references where possible. For example, CALL FOO(I) cannot modify I if within a DO loop that uses I as the iteration variable, and the back end might find that info useful in determining whether it needs to read I back into a register after the call. (It normally has to do that, unless it knows FOO never modifies its passed-by-reference argument, which is rarely the case for Fortran-77 code.)


Node:Better Pedantic Compilation, Next:Warn About Implicit Conversions, Previous:Modifying DO Variable, Up:Missing Features

Better Pedantic Compilation

g77 needs to support -fpedantic more thoroughly, and use it only to generate warnings instead of rejecting constructs outright. Have it warn: if a variable that dimensions an array is not a dummy or placed explicitly in COMMON (F77 does not allow it to be placed in COMMON via EQUIVALENCE); if specification statements follow statement-function-definition statements; about all sorts of syntactic extensions.


Node:Better Source Model, Next:Fortran 90 Support, Up:Missing Features

Better Source Model

g77 needs to provide, as the default source-line model, a "pure visual" mode, where the interpretation of a source program in this mode can be accurately determined by a user looking at a traditionally displayed rendition of the program (assuming the user knows whether the program is fixed or free form).

The design should assume the user cannot tell tabs from spaces and cannot see trailing spaces on lines, but has canonical tab stops and, for fixed-form source, has the ability to always know exactly where column 72 is (since the Fortran standard itself requires this for fixed-form source).

This would change the default treatment of fixed-form source to not treat lines with tabs as if they were infinitely long--instead, they would end at column 72 just as if the tabs were replaced by spaces in the canonical way.

As part of this, provide common alternate models (Digital, f2c, and so on) via command-line options. This includes allowing arbitrarily long lines for free-form source as well as fixed-form source and providing various limits and diagnostics as appropriate.

Also, g77 should offer, perhaps even default to, warnings when characters beyond the last valid column are anything other than spaces. This would mean code with "sequence numbers" in columns 73 through 80 would be rejected, and there's a lot of that kind of code around, but one of the most frequent bugs encountered by new users is accidentally writing fixed-form source code into and beyond column 73. So, maybe the users of old code would be able to more easily handle having to specify, say, a -Wno-col73to80 option.


Node:Better Warnings, Next:Gracefully Handle Sensible Bad Code, Previous:Enabling Debug Lines, Up:Missing Features

Better Warnings

Because of how g77 generates code via the back end, it doesn't always provide warnings the user wants. Consider:

PROGRAM X
PRINT *, A
END

Currently, the above is not flagged as a case of using an uninitialized variable, because g77 generates a run-time library call that looks, to the GBE, like it might actually modify A at run time. (And, in fact, depending on the previous run-time library call, it would!)

Fixing this requires one of the following:

  • Switch to new library, libg77, that provides a more "clean" interface, vis-a-vis input, output, and modified arguments, so the GBE can tell what's going on.

    This would provide a pretty big performance improvement, at least theoretically, and, ultimately, in practice, for some types of code.

  • Have g77 pass a pointer to a temporary containing a copy of A, instead of to A itself. The GBE would then complain about the copy operation involving a potentially uninitialized variable.

    This might also provide a performance boost for some code, because A might then end up living in a register, which could help with inner loops.

  • Have g77 use a GBE construct similar to ADDR_EXPR but with extra information on the fact that the item pointed to won't be modified (a la const in C).

    Probably the best solution for now, but not quite trivial to implement in the general case.


Node:Bit Operations on Floating-point Data, Next:Really Ugly Character Assignments, Previous:Fortran Preprocessor, Up:Missing Features

Bit Operations on Floating-point Data

g77 does not allow REAL and other non-integral types for arguments to intrinsics like And, Or, and Shift.

For example, this program is rejected by g77, because the intrinsic Iand does not accept REAL arguments:

DATA A/7.54/, B/9.112/
PRINT *, IAND(A, B)
END


Node:BITest Intrinsic, Next:BJTest Intrinsic, Previous:ATanD Intrinsic, Up:Other Intrinsics

BITest Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL BITest to use this name for an external procedure.


Node:Bit_Size Intrinsic, Next:BTest Intrinsic, Previous:BesYN Intrinsic, Up:Table of Intrinsic Functions

Bit_Size Intrinsic

Bit_Size(I)

Bit_Size: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar.

Intrinsic groups: f90.

Description:

Returns the number of bits (integer precision plus sign bit) represented by the type for I.

See BTest Intrinsic, for how to test the value of a bit in a variable or array.

See IBSet Intrinsic, for how to set a bit in a variable to 1.

See IBClr Intrinsic, for how to set a bit in a variable to 0.


Node:BJTest Intrinsic, Next:CDAbs Intrinsic, Previous:BITest Intrinsic, Up:Other Intrinsics

BJTest Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL BJTest to use this name for an external procedure.


Node:Block Data and Libraries, Next:Loops, Previous:Advantages Over f2c, Up:Collected Fortran Wisdom

Block Data and Libraries

To ensure that block data program units are linked, especially a concern when they are put into libraries, give each one a name (as in BLOCK DATA FOO) and make sure there is an EXTERNAL FOO statement in every program unit that uses any common block initialized by the corresponding BLOCK DATA. g77 currently compiles a BLOCK DATA as if it were a SUBROUTINE, that is, it generates an actual procedure having the appropriate name. The procedure does nothing but return immediately if it happens to be called. For EXTERNAL FOO, where FOO is not otherwise referenced in the same program unit, g77 assumes there exists a BLOCK DATA FOO in the program and ensures that by generating a reference to it so the linker will make sure it is present. (Specifically, g77 outputs in the data section a static pointer to the external name FOO.)

The implementation g77 currently uses to make this work is one of the few things not compatible with f2c as currently shipped. f2c currently does nothing with EXTERNAL FOO except issue a warning that FOO is not otherwise referenced, and, for BLOCK DATA FOO, f2c doesn't generate a dummy procedure with the name FOO. The upshot is that you shouldn't mix f2c and g77 in this particular case. If you use f2c to compile BLOCK DATA FOO, then any g77-compiled program unit that says EXTERNAL FOO will result in an unresolved reference when linked. If you do the opposite, then FOO might not be linked in under various circumstances (such as when FOO is in a library, or you're using a "clever" linker--so clever, it produces a broken program with little or no warning by omitting initializations of global data because they are contained in unreferenced procedures).

The changes you make to your code to make g77 handle this situation, however, appear to be a widely portable way to handle it. That is, many systems permit it (as they should, since the FORTRAN 77 standard permits EXTERNAL FOO when FOO is a block data program unit), and of the ones that might not link BLOCK DATA FOO under some circumstances, most of them appear to do so once EXTERNAL FOO is present in the appropriate program units.

Here is the recommended approach to modifying a program containing a program unit such as the following:

BLOCK DATA FOO
COMMON /VARS/ X, Y, Z
DATA X, Y, Z / 3., 4., 5. /
END

If the above program unit might be placed in a library module, then ensure that every program unit in every program that references that particular COMMON area uses the EXTERNAL statement to force the area to be initialized.

For example, change a program unit that starts with

INTEGER FUNCTION CURX()
COMMON /VARS/ X, Y, Z
CURX = X
END

so that it uses the EXTERNAL statement, as in:

INTEGER FUNCTION CURX()
COMMON /VARS/ X, Y, Z
EXTERNAL FOO
CURX = X
END

That way, CURX is compiled by g77 (and many other compilers) so that the linker knows it must include FOO, the BLOCK DATA program unit that sets the initial values for the variables in VAR, in the executable program.


Node:BTest Intrinsic, Next:CAbs Intrinsic, Previous:Bit_Size Intrinsic, Up:Table of Intrinsic Functions

BTest Intrinsic

BTest(I, Pos)

BTest: LOGICAL(KIND=1) function.

I: INTEGER; scalar; INTENT(IN).

Pos: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Returns .TRUE. if bit Pos in I is 1, .FALSE. otherwise.

(Bit 0 is the low-order (rightmost) bit, adding the value or 1, to the number if set to 1; bit 1 is the next-higher-order bit, adding or 2; bit 2 adds or 4; and so on.)

See Bit_Size Intrinsic, for how to obtain the number of bits in a type. The leftmost bit of I is BIT_SIZE(I-1).


Node:Bug Criteria, Next:Bug Lists, Up:Bugs

Have You Found a Bug?

If you are not sure whether you have found a bug, here are some guidelines:

  • If the compiler gets a fatal signal, for any input whatever, that is a compiler bug. Reliable compilers never crash--they just remain obsolete.
  • If the compiler produces invalid assembly code, for any input whatever, that is a compiler bug, unless the compiler reports errors (not just warnings) which would ordinarily prevent the assembler from being run.
  • If the compiler produces valid assembly code that does not correctly execute the input source code, that is a compiler bug.

    However, you must double-check to make sure, because you might have run into an incompatibility between GNU Fortran and traditional Fortran. These incompatibilities might be considered bugs, but they are inescapable consequences of valuable features.

    Or you might have a program whose behavior is undefined, which happened by chance to give the desired results with another Fortran compiler. It is best to check the relevant Fortran standard thoroughly if it is possible that the program indeed does something undefined.

    After you have localized the error to a single source line, it should be easy to check for these things. If your program is correct and well defined, you have found a compiler bug.

    It might help if, in your submission, you identified the specific language in the relevant Fortran standard that specifies the desired behavior, if it isn't likely to be obvious and agreed-upon by all Fortran users.

  • If the compiler produces an error message for valid input, that is a compiler bug.
  • If the compiler does not produce an error message for invalid input, that is a compiler bug. However, you should note that your idea of "invalid input" might be someone else's idea of "an extension" or "support for traditional practice".
  • If you are an experienced user of Fortran compilers, your suggestions for improvement of GNU Fortran are welcome in any case.

Many, perhaps most, bug reports against g77 turn out to be bugs in the user's code. While we find such bug reports educational, they sometimes take a considerable amount of time to track down or at least respond to--time we could be spending making g77, not some user's code, better.

Some steps you can take to verify that the bug is not certainly in the code you're compiling with g77:

  • Compile your code using the g77 options -W -Wall -O. These options enable many useful warning; the -O option enables flow analysis that enables the uninitialized-variable warning.

    If you investigate the warnings and find evidence of possible bugs in your code, fix them first and retry g77.

  • Compile your code using the g77 options -finit-local-zero, -fno-automatic, -ffloat-store, and various combinations thereof.

    If your code works with any of these combinations, that is not proof that the bug isn't in g77--a g77 bug exposed by your code might simply be avoided, or have a different, more subtle effect, when different options are used--but it can be a strong indicator that your code is making unwarranted assumptions about the Fortran dialect and/or underlying machine it is being compiled and run on.

    See Overly Convenient Command-Line Options, for information on the -fno-automatic and -finit-local-zero options and how to convert their use into selective changes in your own code.

  • Validate your code with ftnchek or a similar code-checking tool. ftnchek can be found at ftp://ftp.netlib.org/fortran or ftp://ftp.dsm.fordham.edu.

    Here are some sample Makefile rules using ftnchek "project" files to do cross-file checking and sfmakedepend (from ftp://ahab.rutgers.edu/pub/perl/sfmakedepend) to maintain dependencies automatically. These assume the use of GNU make.

    # Dummy suffix for ftnchek targets:
.SUFFIXES: .chek
.PHONY: chekall

# How to compile .f files (for implicit rule):
FC = g77
# Assume `include' directory:
FFLAGS = -Iinclude -g -O -Wall

# Flags for ftnchek:
CHEK1 = -array=0 -include=includes -noarray
CHEK2 = -nonovice -usage=1 -notruncation
CHEKFLAGS = $(CHEK1) $(CHEK2)

# Run ftnchek with all the .prj files except the one corresponding
# to the target's root:
%.chek : %.f ; \
  ftnchek $(filter-out $*.prj,$(PRJS)) $(CHEKFLAGS) \
    -noextern -library $<

# Derive a project file from a source file:
%.prj : %.f ; \
  ftnchek $(CHEKFLAGS) -noextern -project -library $<

# The list of objects is assumed to be in variable OBJS.
# Sources corresponding to the objects:
SRCS = $(OBJS:%.o=%.f)
# ftnchek project files:
PRJS = $(OBJS:%.o=%.prj)

# Build the program
prog: $(OBJS) ; \
  $(FC) -o $ $(OBJS)

chekall: $(PRJS) ; \
  ftnchek $(CHEKFLAGS) $(PRJS)

prjs: $(PRJS)

# For Emacs M-x find-tag:
TAGS: $(SRCS) ; \
  etags $(SRCS)

# Rebuild dependencies:
depend: ; \
  sfmakedepend -I $(PLTLIBDIR) -I includes -a prj $(SRCS1)

  • Try your code out using other Fortran compilers, such as f2c. If it does not work on at least one other compiler (assuming the compiler supports the features the code needs), that is a strong indicator of a bug in the code.

    However, even if your code works on many compilers except g77, that does not mean the bug is in g77. It might mean the bug is in your code, and that g77 simply exposes it more readily than other compilers.


Node:Bug Lists, Next:Bug Reporting, Previous:Bug Criteria, Up:Bugs

Where to Report Bugs

Send bug reports for GNU Fortran to gcc-bugs@gcc.gnu.org or bug-gcc@gnu.org.

Often people think of posting bug reports to a newsgroup instead of mailing them. This sometimes appears to work, but it has one problem which can be crucial: a newsgroup posting does not contain a mail path back to the sender. Thus, if maintainers need more information, they might be unable to reach you. For this reason, you should always send bug reports by mail to the proper mailing list.

As a last resort, send bug reports on paper to:

GNU Compiler Bugs
Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307, USA


Node:Bug Reporting, Previous:Bug Lists, Up:Bugs

How to Report Bugs

The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!

Often people omit facts because they think they know what causes the problem and they conclude that some details don't matter. Thus, you might assume that the name of the variable you use in an example does not matter. Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that name is stored in memory; perhaps, if the name were different, the contents of that location would fool the compiler into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable someone to fix the bug if it is not known. It isn't very important what happens if the bug is already known. Therefore, always write your bug reports on the assumption that the bug is not known.

Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" This cannot help us fix a bug, so it is rarely helpful. We respond by asking for enough details to enable us to investigate. You might as well expedite matters by sending them to begin with. (Besides, there are enough bells ringing around here as it is.)

Try to make your bug report self-contained. If we have to ask you for more information, it is best if you include all the previous information in your response, as well as the information that was missing.

Please report each bug in a separate message. This makes it easier for us to track which bugs have been fixed and to forward your bugs reports to the appropriate maintainer.

Do not compress and encode any part of your bug report using programs such as uuencode. If you do so it will slow down the processing of your bug. If you must submit multiple large files, use shar, which allows us to read your message without having to run any decompression programs.

(As a special exception for GNU Fortran bug-reporting, at least for now, if you are sending more than a few lines of code, if your program's source file format contains "interesting" things like trailing spaces or strange characters, or if you need to include binary data files, it is acceptable to put all the files together in a tar archive, and, whether you need to do that, it is acceptable to then compress the single file (tar archive or source file) using gzip and encode it via uuencode. Do not use any MIME stuff--the current maintainer can't decode this. Using compress instead of gzip is acceptable, assuming you have licensed the use of the patented algorithm in compress from Unisys.)

To enable someone to investigate the bug, you should include all these things:

  • The version of GNU Fortran. You can get this by running g77 with the -v option. (Ignore any error messages that might be displayed when the linker is run.)

    Without this, we won't know whether there is any point in looking for the bug in the current version of GNU Fortran.

  • A complete input file that will reproduce the bug.

    If your source file(s) require preprocessing (for example, their names have suffixes like .F, .fpp, .FPP, and .r), and the bug is in the compiler proper (f771) or in a subsequent phase of processing, run your source file through the C preprocessor by doing g77 -E sourcefile > newfile. Then, include the contents of newfile in the bug report. (When you do this, use the same preprocessor options--such as -I, -D, and -U--that you used in actual compilation.)

    A single statement is not enough of an example. In order to compile it, it must be embedded in a complete file of compiler input. The bug might depend on the details of how this is done.

    Without a real example one can compile, all anyone can do about your bug report is wish you luck. It would be futile to try to guess how to provoke the bug. For example, bugs in register allocation and reloading can depend on every little detail of the source and include files that trigger them.

  • Note that you should include with your bug report any files included by the source file (via the #include or INCLUDE directive) that you send, and any files they include, and so on.

    It is not necessary to replace the #include and INCLUDE directives with the actual files in the version of the source file that you send, but it might make submitting the bug report easier in the end. However, be sure to reproduce the bug using the exact version of the source material you submit, to avoid wild-goose chases.

  • The command arguments you gave GNU Fortran to compile that example and observe the bug. For example, did you use -O? To guarantee you won't omit something important, list all the options.

    If we were to try to guess the arguments, we would probably guess wrong and then we would not encounter the bug.

  • The type of machine you are using, and the operating system name and version number. (Much of this information is printed by g77 -v--if you include that, send along any additional info you have that you don't see clearly represented in that output.)
  • The operands you gave to the configure command when you installed the compiler.
  • A complete list of any modifications you have made to the compiler source. (We don't promise to investigate the bug unless it happens in an unmodified compiler. But if you've made modifications and don't tell us, then you are sending us on a wild-goose chase.)

    Be precise about these changes. A description in English is not enough--send a context diff for them.

    Adding files of your own (such as a machine description for a machine we don't support) is a modification of the compiler source.

  • Details of any other deviations from the standard procedure for installing GNU Fortran.
  • A description of what behavior you observe that you believe is incorrect. For example, "The compiler gets a fatal signal," or, "The assembler instruction at line 208 in the output is incorrect."

    Of course, if the bug is that the compiler gets a fatal signal, then one can't miss it. But if the bug is incorrect output, the maintainer might not notice unless it is glaringly wrong. None of us has time to study all the assembler code from a 50-line Fortran program just on the chance that one instruction might be wrong. We need you to do this part!

    Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of the compiler is out of synch, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and the copy here would not. If you said to expect a crash, then when the compiler here fails to crash, we would know that the bug was not happening. If you don't say to expect a crash, then we would not know whether the bug was happening. We would not be able to draw any conclusion from our observations.

    If the problem is a diagnostic when building GNU Fortran with some other compiler, say whether it is a warning or an error.

    Often the observed symptom is incorrect output when your program is run. Sad to say, this is not enough information unless the program is short and simple. None of us has time to study a large program to figure out how it would work if compiled correctly, much less which line of it was compiled wrong. So you will have to do that. Tell us which source line it is, and what incorrect result happens when that line is executed. A person who understands the program can find this as easily as finding a bug in the program itself.

  • If you send examples of assembler code output from GNU Fortran, please use -g when you make them. The debugging information includes source line numbers which are essential for correlating the output with the input.
  • If you wish to mention something in the GNU Fortran source, refer to it by context, not by line number.

    The line numbers in the development sources don't match those in your sources. Your line numbers would convey no convenient information to the maintainers.

  • Additional information from a debugger might enable someone to find a problem on a machine which he does not have available. However, you need to think when you collect this information if you want it to have any chance of being useful.

    For example, many people send just a backtrace, but that is never useful by itself. A simple backtrace with arguments conveys little about GNU Fortran because the compiler is largely data-driven; the same functions are called over and over for different RTL insns, doing different things depending on the details of the insn.

    Most of the arguments listed in the backtrace are useless because they are pointers to RTL list structure. The numeric values of the pointers, which the debugger prints in the backtrace, have no significance whatever; all that matters is the contents of the objects they point to (and most of the contents are other such pointers).

    In addition, most compiler passes consist of one or more loops that scan the RTL insn sequence. The most vital piece of information about such a loop--which insn it has reached--is usually in a local variable, not in an argument.

    What you need to provide in addition to a backtrace are the values of the local variables for several stack frames up. When a local variable or an argument is an RTX, first print its value and then use the GDB command pr to print the RTL expression that it points to. (If GDB doesn't run on your machine, use your debugger to call the function debug_rtx with the RTX as an argument.) In general, whenever a variable is a pointer, its value is no use without the data it points to.

Here are some things that are not necessary:

  • A description of the envelope of the bug.

    Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it.

    This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. You might as well save your time for something else.

    Of course, if you can find a simpler example to report instead of the original one, that is a convenience. Errors in the output will be easier to spot, running under the debugger will take less time, etc. Most GNU Fortran bugs involve just one function, so the most straightforward way to simplify an example is to delete all the function definitions except the one where the bug occurs. Those earlier in the file may be replaced by external declarations if the crucial function depends on them. (Exception: inline functions might affect compilation of functions defined later in the file.)

    However, simplification is not vital; if you don't want to do this, report the bug anyway and send the entire test case you used.

  • In particular, some people insert conditionals #ifdef BUG around a statement which, if removed, makes the bug not happen. These are just clutter; we won't pay any attention to them anyway. Besides, you should send us preprocessor output, and that can't have conditionals.
  • A patch for the bug.

    A patch for the bug is useful if it is a good one. But don't omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all.

    Sometimes with a program as complicated as GNU Fortran it is very hard to construct an example that will make the program follow a certain path through the code. If you don't send the example, we won't be able to construct one, so we won't be able to verify that the bug is fixed.

    And if we can't understand what bug you are trying to fix, or why your patch should be an improvement, we won't install it. A test case will help us to understand.

    See http://gcc.gnu.org/contribute.html for guidelines on how to make it easy for us to understand and install your patches.

  • A guess about what the bug is or what it depends on.

    Such guesses are usually wrong. Even the maintainer can't guess right about such things without first using the debugger to find the facts.

  • A core dump file.

    We have no way of examining a core dump for your type of machine unless we have an identical system--and if we do have one, we should be able to reproduce the crash ourselves.


Node:Bugs, Next:Service, Previous:Open Questions, Up:Top

Reporting Bugs

Your bug reports play an essential role in making GNU Fortran reliable.

When you encounter a problem, the first thing to do is to see if it is already known. See Trouble. If it isn't known, then you should report the problem.

Reporting a bug might help you by bringing a solution to your problem, or it might not. (If it does not, look in the service directory; see Service.) In any case, the principal function of a bug report is to help the entire community by making the next version of GNU Fortran work better. Bug reports are your contribution to the maintenance of GNU Fortran.

Since the maintainers are very overloaded, we cannot respond to every bug report. However, if the bug has not been fixed, we are likely to send you a patch and ask you to tell us whether it works.

In order for a bug report to serve its purpose, you must include the information that makes for fixing the bug.

  • Criteria: Have you really found a bug?
  • Where: Where to send your bug report.
  • Reporting: How to report a bug effectively.

See Known Causes of Trouble with GNU Fortran, for information on problems we already know about.

See How To Get Help with GNU Fortran, for information on where to ask for help.


Node:But-bugs, Next:Known Bugs, Up:Trouble

Bugs Not In GNU Fortran

These are bugs to which the maintainers often have to reply, "but that isn't a bug in g77...". Some of these already are fixed in new versions of other software; some still need to be fixed; some are problems with how g77 is installed or is being used; some are the result of bad hardware that causes software to misbehave in sometimes bizarre ways; some just cannot be addressed at this time until more is known about the problem.

Please don't re-report these bugs to the g77 maintainers--if you must remind someone how important it is to you that the problem be fixed, talk to the people responsible for the other products identified below, but preferably only after you've tried the latest versions of those products. The g77 maintainers have their hands full working on just fixing and improving g77, without serving as a clearinghouse for all bugs that happen to affect g77 users.

See Collected Fortran Wisdom, for information on behavior of Fortran programs, and the programs that compile them, that might be thought to indicate bugs.

  • Signal 11 and Friends: Strange behavior by any software.
  • Cannot Link Fortran Programs: Unresolved references.
  • Large Common Blocks: Problems on older GNU/Linux systems.
  • Debugger Problems: When the debugger crashes.
  • NeXTStep Problems: Misbehaving executables.
  • Stack Overflow: More misbehaving executables.
  • Nothing Happens: Less behaving executables.
  • Strange Behavior at Run Time: Executables misbehaving due to bugs in your program.
  • Floating-point Errors: The results look wrong, but....


Node:C++ Considerations, Next:Startup Code, Previous:f2c Skeletons and Prototypes, Up:Interoperating with C and C++

C++ Considerations

f2c can be used to generate suitable code for compilation with a C++ system using the -C++ option. The important thing about linking g77-compiled code with C++ is that the prototypes for the g77 routines must specify C linkage to avoid name mangling. So, use an extern "C" declaration. f2c's -C++ option will take care of this when generating skeletons or prototype files as above, and also avoid clashes with C++ reserved words in addition to those in C.


Node:C Access to Type Information, Next:f2c Skeletons and Prototypes, Previous:C Interfacing Tools, Up:Interoperating with C and C++

Accessing Type Information in C

Generally, C code written to link with g77 code--calling and/or being called from Fortran--should #include <g2c.h> to define the C versions of the Fortran types. Don't assume Fortran INTEGER types correspond to C ints, for instance; instead, declare them as integer, a type defined by g2c.h. g2c.h is installed where gcc will find it by default, assuming you use a copy of gcc compatible with g77, probably built at the same time as g77.


Node:C Interfacing Tools, Next:C Access to Type Information, Up:Interoperating with C and C++

C Interfacing Tools

Even if you don't actually use it as a compiler, f2c from ftp://ftp.netlib.org/f2c/src, can be a useful tool when you're interfacing (linking) Fortran and C. See Generating Skeletons and Prototypes with f2c.

To use f2c for this purpose you only need retrieve and build the src directory from the distribution, consult the README instructions there for machine-specifics, and install the f2c program on your path.

Something else that might be useful is cfortran.h from ftp://zebra.desy.de/cfortran. This is a fairly general tool which can be used to generate interfaces for calling in both directions between Fortran and C. It can be used in f2c mode with g77--consult its documentation for details.


Node:CAbs Intrinsic, Next:CCos Intrinsic, Previous:BTest Intrinsic, Up:Table of Intrinsic Functions

CAbs Intrinsic

CAbs(A)

CAbs: REAL(KIND=1) function.

A: COMPLEX(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of ABS() that is specific to one type for A. See Abs Intrinsic.


Node:Cannot Link Fortran Programs, Next:Large Common Blocks, Previous:Signal 11 and Friends, Up:But-bugs

Cannot Link Fortran Programs

On some systems, perhaps just those with out-of-date (shared?) libraries, unresolved-reference errors happen when linking g77-compiled programs (which should be done using g77).

If this happens to you, try appending -lc to the command you use to link the program, e.g. g77 foo.f -lc. g77 already specifies -lg2c -lm when it calls the linker, but it cannot also specify -lc because not all systems have a file named libc.a.

It is unclear at this point whether there are legitimately installed systems where -lg2c -lm is insufficient to resolve code produced by g77.

If your program doesn't link due to unresolved references to names like _main, make sure you're using the g77 command to do the link, since this command ensures that the necessary libraries are loaded by specifying -lg2c -lm when it invokes the gcc command to do the actual link. (Use the -v option to discover more about what actually happens when you use the g77 and gcc commands.)

Also, try specifying -lc as the last item on the g77 command line, in case that helps.


Node:Carriage Returns, Next:Tabs, Up:Source Form

Carriage Returns

Carriage returns (\r) in source lines are ignored. This is somewhat different from f2c, which seems to treat them as spaces outside character/Hollerith constants, and encodes them as \r inside such constants.


Node:Case Sensitivity, Next:VXT Fortran, Previous:Dollar Signs, Up:Other Dialects

Case Sensitivity

GNU Fortran offers the programmer way too much flexibility in deciding how source files are to be treated vis-a-vis uppercase and lowercase characters. There are 66 useful settings that affect case sensitivity, plus 10 settings that are nearly useless, with the remaining 116 settings being either redundant or useless.

None of these settings have any effect on the contents of comments (the text after a c or C in Column 1, for example) or of character or Hollerith constants. Note that things like the E in the statement CALL FOO(3.2E10) and the TO in ASSIGN 10 TO LAB are considered built-in keywords, and so are affected by these settings.

Low-level switches are identified in this section as follows:

  • A Source Case Conversion:
    • 0 Preserve (see Note 1)
    • 1 Convert to Upper Case
    • 2 Convert to Lower Case
  • B Built-in Keyword Matching:
    • 0 Match Any Case (per-character basis)
    • 1 Match Upper Case Only
    • 2 Match Lower Case Only
    • 3 Match InitialCaps Only (see tables for spellings)
  • C Built-in Intrinsic Matching:
    • 0 Match Any Case (per-character basis)
    • 1 Match Upper Case Only
    • 2 Match Lower Case Only
    • 3 Match InitialCaps Only (see tables for spellings)
  • D User-defined Symbol Possibilities (warnings only):
    • 0 Allow Any Case (per-character basis)
    • 1 Allow Upper Case Only
    • 2 Allow Lower Case Only
    • 3 Allow InitialCaps Only (see Note 2)

Note 1: g77 eventually will support NAMELIST in a manner that is consistent with these source switches--in the sense that input will be expected to meet the same requirements as source code in terms of matching symbol names and keywords (for the exponent letters).

Currently, however, NAMELIST is supported by libg2c, which uppercases NAMELIST input and symbol names for matching. This means not only that NAMELIST output currently shows symbol (and keyword) names in uppercase even if lower-case source conversion (option A2) is selected, but that NAMELIST cannot be adequately supported when source case preservation (option A0) is selected.

If A0 is selected, a warning message will be output for each NAMELIST statement to this effect. The behavior of the program is undefined at run time if two or more symbol names appear in a given NAMELIST such that the names are identical when converted to upper case (e.g. NAMELIST /X/ VAR, Var, var). For complete and total elegance, perhaps there should be a warning when option A2 is selected, since the output of NAMELIST is currently in uppercase but will someday be lowercase (when a libg77 is written), but that seems to be overkill for a product in beta test.

Note 2: Rules for InitialCaps names are:

  • Must be a single uppercase letter, or
  • Must start with an uppercase letter and contain at least one lowercase letter.

So A, Ab, ABc, AbC, and Abc are valid InitialCaps names, but AB, A2, and ABC are not. Note that most, but not all, built-in names meet these requirements--the exceptions are some of the two-letter format specifiers, such as BN and BZ.

Here are the names of the corresponding command-line options:

A0: -fsource-case-preserve
A1: -fsource-case-upper
A2: -fsource-case-lower

B0: -fmatch-case-any
B1: -fmatch-case-upper
B2: -fmatch-case-lower
B3: -fmatch-case-initcap

C0: -fintrin-case-any
C1: -fintrin-case-upper
C2: -fintrin-case-lower
C3: -fintrin-case-initcap

D0: -fsymbol-case-any
D1: -fsymbol-case-upper
D2: -fsymbol-case-lower
D3: -fsymbol-case-initcap

Useful combinations of the above settings, along with abbreviated option names that set some of these combinations all at once:

 1: A0--  B0---  C0---  D0---    -fcase-preserve
 2: A0--  B0---  C0---  D-1--
 3: A0--  B0---  C0---  D--2-
 4: A0--  B0---  C0---  D---3
 5: A0--  B0---  C-1--  D0---
 6: A0--  B0---  C-1--  D-1--
 7: A0--  B0---  C-1--  D--2-
 8: A0--  B0---  C-1--  D---3
 9: A0--  B0---  C--2-  D0---
10: A0--  B0---  C--2-  D-1--
11: A0--  B0---  C--2-  D--2-
12: A0--  B0---  C--2-  D---3
13: A0--  B0---  C---3  D0---
14: A0--  B0---  C---3  D-1--
15: A0--  B0---  C---3  D--2-
16: A0--  B0---  C---3  D---3
17: A0--  B-1--  C0---  D0---
18: A0--  B-1--  C0---  D-1--
19: A0--  B-1--  C0---  D--2-
20: A0--  B-1--  C0---  D---3
21: A0--  B-1--  C-1--  D0---
22: A0--  B-1--  C-1--  D-1--    -fcase-strict-upper
23: A0--  B-1--  C-1--  D--2-
24: A0--  B-1--  C-1--  D---3
25: A0--  B-1--  C--2-  D0---
26: A0--  B-1--  C--2-  D-1--
27: A0--  B-1--  C--2-  D--2-
28: A0--  B-1--  C--2-  D---3
29: A0--  B-1--  C---3  D0---
30: A0--  B-1--  C---3  D-1--
31: A0--  B-1--  C---3  D--2-
32: A0--  B-1--  C---3  D---3
33: A0--  B--2-  C0---  D0---
34: A0--  B--2-  C0---  D-1--
35: A0--  B--2-  C0---  D--2-
36: A0--  B--2-  C0---  D---3
37: A0--  B--2-  C-1--  D0---
38: A0--  B--2-  C-1--  D-1--
39: A0--  B--2-  C-1--  D--2-
40: A0--  B--2-  C-1--  D---3
41: A0--  B--2-  C--2-  D0---
42: A0--  B--2-  C--2-  D-1--
43: A0--  B--2-  C--2-  D--2-    -fcase-strict-lower
44: A0--  B--2-  C--2-  D---3
45: A0--  B--2-  C---3  D0---
46: A0--  B--2-  C---3  D-1--
47: A0--  B--2-  C---3  D--2-
48: A0--  B--2-  C---3  D---3
49: A0--  B---3  C0---  D0---
50: A0--  B---3  C0---  D-1--
51: A0--  B---3  C0---  D--2-
52: A0--  B---3  C0---  D---3
53: A0--  B---3  C-1--  D0---
54: A0--  B---3  C-1--  D-1--
55: A0--  B---3  C-1--  D--2-
56: A0--  B---3  C-1--  D---3
57: A0--  B---3  C--2-  D0---
58: A0--  B---3  C--2-  D-1--
59: A0--  B---3  C--2-  D--2-
60: A0--  B---3  C--2-  D---3
61: A0--  B---3  C---3  D0---
62: A0--  B---3  C---3  D-1--
63: A0--  B---3  C---3  D--2-
64: A0--  B---3  C---3  D---3    -fcase-initcap
65: A-1-  B01--  C01--  D01--    -fcase-upper
66: A--2  B0-2-  C0-2-  D0-2-    -fcase-lower

Number 22 is the "strict" ANSI FORTRAN 77 model wherein all input (except comments, character constants, and Hollerith strings) must be entered in uppercase. Use -fcase-strict-upper to specify this combination.

Number 43 is like Number 22 except all input must be lowercase. Use -fcase-strict-lower to specify this combination.

Number 65 is the "classic" ANSI FORTRAN 77 model as implemented on many non-UNIX machines whereby all the source is translated to uppercase. Use -fcase-upper to specify this combination.

Number 66 is the "canonical" UNIX model whereby all the source is translated to lowercase. Use -fcase-lower to specify this combination.

There are a few nearly useless combinations:

67: A-1-  B01--  C01--  D--2-
68: A-1-  B01--  C01--  D---3
69: A-1-  B01--  C--23  D01--
70: A-1-  B01--  C--23  D--2-
71: A-1-  B01--  C--23  D---3
72: A--2  B01--  C0-2-  D-1--
73: A--2  B01--  C0-2-  D---3
74: A--2  B01--  C-1-3  D0-2-
75: A--2  B01--  C-1-3  D-1--
76: A--2  B01--  C-1-3  D---3

The above allow some programs to be compiled but with restrictions that make most useful programs impossible: Numbers 67 and 72 warn about any user-defined symbol names (such as SUBROUTINE FOO); Numbers 68 and 73 warn about any user-defined symbol names longer than one character that don't have at least one non-alphabetic character after the first; Numbers 69 and 74 disallow any references to intrinsics; and Numbers 70, 71, 75, and 76 are combinations of the restrictions in 67+69, 68+69, 72+74, and 73+74, respectively.

All redundant combinations are shown in the above tables anyplace where more than one setting is shown for a low-level switch. For example, B0-2- means either setting 0 or 2 is valid for switch B. The "proper" setting in such a case is the one that copies the setting of switch A--any other setting might slightly reduce the speed of the compiler, though possibly to an unmeasurable extent.

All remaining combinations are useless in that they prevent successful compilation of non-null source files (source files with something other than comments).


Node:CCos Intrinsic, Next:Ceiling Intrinsic, Previous:CAbs Intrinsic, Up:Table of Intrinsic Functions

CCos Intrinsic

CCos(X)

CCos: COMPLEX(KIND=1) function.

X: COMPLEX(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of COS() that is specific to one type for X. See Cos Intrinsic.


Node:CDAbs Intrinsic, Next:CDCos Intrinsic, Previous:BJTest Intrinsic, Up:Other Intrinsics

CDAbs Intrinsic

CDAbs(A)

CDAbs: REAL(KIND=2) function.

A: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of ABS() that is specific to one type for A. See Abs Intrinsic.


Node:CDCos Intrinsic, Next:CDExp Intrinsic, Previous:CDAbs Intrinsic, Up:Other Intrinsics

CDCos Intrinsic

CDCos(X)

CDCos: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of COS() that is specific to one type for X. See Cos Intrinsic.


Node:CDExp Intrinsic, Next:CDLog Intrinsic, Previous:CDCos Intrinsic, Up:Other Intrinsics

CDExp Intrinsic

CDExp(X)

CDExp: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of EXP() that is specific to one type for X. See Exp Intrinsic.


Node:CDLog Intrinsic, Next:CDSin Intrinsic, Previous:CDExp Intrinsic, Up:Other Intrinsics

CDLog Intrinsic

CDLog(X)

CDLog: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of LOG() that is specific to one type for X. See Log Intrinsic.


Node:CDSin Intrinsic, Next:CDSqRt Intrinsic, Previous:CDLog Intrinsic, Up:Other Intrinsics

CDSin Intrinsic

CDSin(X)

CDSin: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of SIN() that is specific to one type for X. See Sin Intrinsic.


Node:CDSqRt Intrinsic, Next:ChDir Intrinsic (function), Previous:CDSin Intrinsic, Up:Other Intrinsics

CDSqRt Intrinsic

CDSqRt(X)

CDSqRt: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of SQRT() that is specific to one type for X. See SqRt Intrinsic.


Node:Ceiling Intrinsic, Next:CExp Intrinsic, Previous:CCos Intrinsic, Up:Table of Intrinsic Functions

Ceiling Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Ceiling to use this name for an external procedure.


Node:CExp Intrinsic, Next:Char Intrinsic, Previous:Ceiling Intrinsic, Up:Table of Intrinsic Functions

CExp Intrinsic

CExp(X)

CExp: COMPLEX(KIND=1) function.

X: COMPLEX(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of EXP() that is specific to one type for X. See Exp Intrinsic.


Node:Challenges Posed, Next:Transforming Statements, Previous:Two-pass Design, Up:Front End

Challenges Posed

Consider the following Fortran code, which uses various extensions (including some to Fortran 90):

SUBROUTINE X(A)
CHARACTER*(*) A
COMPLEX CFUNC
INTEGER*2 CLOCKS(200)
INTEGER IFUNC

CALL SYSTEM_CLOCK (CLOCKS (IFUNC (CFUNC ('('//A//')'))))

The above poses the following challenges to any Fortran compiler that uses run-time interfaces, and a run-time library, roughly similar to those used by g77:

  • Assuming the library routine that supports SYSTEM_CLOCK expects to set an INTEGER*4 variable via its COUNT argument, the compiler must make available to it a temporary variable of that type.
  • Further, after the SYSTEM_CLOCK library routine returns, the compiler must ensure that the temporary variable it wrote is copied into the appropriate element of the CLOCKS array. (This assumes the compiler doesn't just reject the code, which it should if it is compiling under some kind of a "strict" option.)
  • To determine the correct index into the CLOCKS array, (putting aside the fact that the index, in this particular case, need not be computed until after the SYSTEM_CLOCK library routine returns), the compiler must ensure that the IFUNC function is called.

    That requires evaluating its argument, which requires, for g77 (assuming -ff2c is in force), reserving a temporary variable of type COMPLEX for use as a repository for the return value being computed by CFUNC.

  • Before invoking CFUNC, is argument must be evaluated, which requires allocating, at run time, a temporary large enough to hold the result of the concatenation, as well as actually performing the concatenation.
  • The large temporary needed during invocation of CFUNC should, ideally, be deallocated (or, at least, left to the GBE to dispose of, as it sees fit) as soon as CFUNC returns, which means before IFUNC is called (as it might need a lot of dynamically allocated memory).

g77 currently doesn't support all of the above, but, so that it might someday, it has evolved to handle at least some of the above requirements.

Meeting the above requirements is made more challenging by conforming to the requirements of the GBEL/GBE combination.


Node:Changes, Next:Language, Previous:News, Up:Top

User-visible Changes

This chapter describes changes to g77 that are visible to the programmers who actually write and maintain Fortran code they compile with g77. Information on changes to installation procedures, changes to the documentation, and bug fixes is not provided here, unless it is likely to affect how users use g77. See News About GNU Fortran, for information on such changes to g77.

Note that two variants of g77 are tracked below. The egcs variant is described vis-a-vis previous versions of egcs and/or an official FSF version, as appropriate. Note that all such variants are obsolete as of July 1999 - the information is retained here only for its historical value.

Therefore, egcs versions sometimes have multiple listings to help clarify how they differ from other versions, though this can make getting a complete picture of what a particular egcs version contains somewhat more difficult.

For information on bugs in the GCC-3.1 version of g77, see Known Bugs In GNU Fortran.

The following information was last updated on 2002-04-13:

In GCC 3.1 (formerly known as g77-0.5.27) versus GCC 3.0:

  • Problem Reports fixed (in chronological order of submission):
    947
    Data statement initialization with subscript of kind INTEGER*2
    3743
    Reference to intrinsic `ISHFT' invalid
    3807
    Function BESJN(integer,double) problems
    3957
    g77 -pipe -xf77-cpp-input sends output to stdout
    4279
    g77 -h" gives bogus output
    4730
    ICE on valid input using CALL EXIT(%VAL(...))
    4752
    g77 -v -c -xf77-version /dev/null -xnone causes ice
    4885
    BACKSPACE example that doesn't work as of gcc/g77-3.0.x
    5122
    g77 rejects accepted use of INTEGER*2 as type of DATA statement loop index
    5397
    ICE on compiling source with 540 000 000 REAL array
    5473
    ICE on BESJN(integer*8,real)
    5837
    bug in loop unrolling
  • g77 now has its man page generated from the texinfo documentation, to guarantee that it remains up to date.
  • g77 used to reject the following program on 32-bit targets:
    PROGRAM PROG
DIMENSION A(140 000 000)
END
    with the message:
    prog.f: In program `prog':
prog.f:2:
         DIMENSION A(140 000 000)
                   ^
Array `a' at (^) is too large to handle
    because 140 000 000 reals is larger than the largest bit-extent that can be expressed in 32 bits. However, bit-sizes never play a role after offsets have been converted to byte addresses. Therefore this check has been removed. Note: On GNU/Linux systems one has to compile programs that occupy more than 1 Gbyte statically, i.e. g77 -static ....
  • Based on work done by Juergen Pfeifer (juergen.pfeifer@gmx.net) libf2c is now a shared library. One can still link in all objects with the program by specifying the -static option.
  • Robert Anderson (rwa@alumni.princeton.edu) thought up a two line change that enables g77 to compile such code as:
    SUBROUTINE SUB(A, N)
DIMENSION N(2)
DIMENSION A(N(1),N(2))
A(1,1) = 1.
END
    Note the use of array elements in the bounds of the adjustable array A.
  • George Helffrich (george@geo.titech.ac.jp) implemented a change in substring index checking (when specifying -fbounds-check) that permits the use of zero length substrings of the form string(1:0).
  • Based on code developed by Pedro Vazquez (vazquez@penelope.iqm.unicamp.br), the libf2c library is now able to read and write files larger than 2 Gbyte on 32-bit target machines, if the operating system supports this.

In 0.5.26, GCC 3.0 versus GCC 2.95:

  • When a REWIND was issued after a WRITE statement on an unformatted file, the implicit truncation was performed by copying the truncated file to /tmp and copying the result back. This has been fixed by using the ftruncate OS function. Thanks go to the GAMESS developers for bringing this to our attention.
  • Using options -g, -ggdb or -gdwarf[-2] (where appropriate for your target) now also enables debugging information for COMMON BLOCK and EQUIVALENCE items to be emitted. Thanks go to Andrew Vaught (andy@xena.eas.asu.edu) and George Helffrich (george@geology.bristol.ac.uk) for fixing this longstanding problem.
  • It is not necessary anymore to use the option -femulate-complex to compile Fortran code using COMPLEX arithmetic, even on 64-bit machines (like the Alpha). This will improve code generation.
  • INTRINSIC arithmetic functions are now treated as routines that do not depend on anything but their argument(s). This enables further instruction scheduling, because it is known that they cannot read or modify arbitrary locations.

In 0.5.25, GCC 2.95 (EGCS 1.2) versus EGCS 1.1.2:

  • The new -fbounds-check option causes g77 to compile run-time bounds checks of array subscripts, as well as of substring start and end points.
  • libg2c now supports building as multilibbed library, which provides better support for systems that require options such as -mieee to work properly.
  • Source file names with the suffixes .FOR and .FPP now are recognized by g77 as if they ended in .for and .fpp, respectively.
  • The order of arguments to the subroutine forms of the CTime, DTime, ETime, and TtyNam intrinsics has been swapped. The argument serving as the returned value for the corresponding function forms now is the second argument, making these consistent with the other subroutine forms of libU77 intrinsics.
  • g77 now warns about a reference to an intrinsic that has an interface that is not Year 2000 (Y2K) compliant. Also, libg2c has been changed to increase the likelihood of catching references to the implementations of these intrinsics using the EXTERNAL mechanism (which would avoid the new warnings).

    See Year 2000 (Y2K) Problems, for more information.

  • -fno-emulate-complex is now the default option. This should result in improved performance of code that uses the COMPLEX data type.
  • The -malign-double option now reliably aligns all double-precision variables and arrays on Intel x86 targets.
  • g77 no longer generates code to maintain errno, a C-language concept, when performing operations such as the SqRt intrinsic.
  • Support for the -fugly option has been removed.

In 0.5.24 versus 0.5.23:

There is no g77 version 0.5.24 at this time, or planned. 0.5.24 is the version number designated for bug fixes and, perhaps, some new features added, to 0.5.23. Version 0.5.23 requires gcc 2.8.1, as 0.5.24 was planned to require.

Due to EGCS becoming GCC (which is now an acronym for "GNU Compiler Collection"), and EGCS 1.2 becoming officially designated GCC 2.95, there seems to be no need for an actual 0.5.24 release.

To reduce the confusion already resulting from use of 0.5.24 to designate g77 versions within EGCS versions 1.0 and 1.1, as well as in versions of g77 documentation and notices during that period, "mainline" g77 version numbering resumes at 0.5.25 with GCC 2.95 (EGCS 1.2), skipping over 0.5.24 as a placeholder version number.

To repeat, there is no g77 0.5.24, but there is now a 0.5.25. Please remain calm and return to your keypunch units.

In EGCS 1.1.2 versus EGCS 1.1.1:

In EGCS 1.1.1 versus EGCS 1.1:

In EGCS 1.1 versus EGCS 1.0.3:

  • Support FORMAT(I<expr>) when expr is a compile-time constant INTEGER expression.
  • Fix g77 -g option so procedures that use ENTRY can be stepped through, line by line, in gdb.
  • Allow any REAL argument to intrinsics Second and CPU_Time.
  • Use tempnam, if available, to open scratch files (as in OPEN(STATUS='SCRATCH')) so that the TMPDIR environment variable, if present, is used.
  • g77's version of libf2c separates out the setting of global state (such as command-line arguments and signal handling) from main.o into distinct, new library archive members.

    This should make it easier to write portable applications that have their own (non-Fortran) main() routine properly set up the libf2c environment, even when libf2c (now libg2c) is a shared library.

  • The g77 command now expects the run-time library to be named libg2c.a instead of libf2c.a, to ensure that a version other than the one built and installed as part of the same g77 version is picked up.
  • Some diagnostics have been changed from warnings to errors, to prevent inadvertent use of the resulting, probably buggy, programs. These mostly include diagnostics about use of unsupported features in the OPEN, INQUIRE, READ, and WRITE statements, and about truncations of various sorts of constants.

In EGCS 1.1 versus g77 0.5.23:

  • g77 now treats %LOC(expr) and LOC(expr) as "ordinary" expressions when they are used as arguments in procedure calls. This change applies only to global (filewide) analysis, making it consistent with how g77 actually generates code for these cases.

    Previously, g77 treated these expressions as denoting special "pointer" arguments for the purposes of filewide analysis.

  • Align static double-precision variables and arrays on Intel x86 targets regardless of whether -malign-double is specified.

    Generally, this affects only local variables and arrays having the SAVE attribute or given initial values via DATA.

  • The g77 driver now ensures that -lg2c is specified in the link phase prior to any occurrence of -lm. This prevents accidentally linking to a routine in the SunOS4 -lm library when the generated code wants to link to the one in libf2c (libg2c).
  • g77 emits more debugging information when -g is used.

    This new information allows, for example, which __g77_length_a to be used in gdb to determine the type of the phantom length argument supplied with CHARACTER variables.

    This information pertains to internally-generated type, variable, and other information, not to the longstanding deficiencies vis-a-vis COMMON and EQUIVALENCE.

  • The F90 Date_and_Time intrinsic now is supported.
  • The F90 System_Clock intrinsic allows the optional arguments (except for the Count argument) to be omitted.

In 0.5.23 versus 0.5.22:

  • This release contains several regressions against version 0.5.22 of g77, due to using the "vanilla" gcc back end instead of patching it to fix a few bugs and improve performance in a few cases.

    Features that have been dropped from this version of g77 due to their being implemented via g77-specific patches to the gcc back end in previous releases include:

    • Support for __restrict__ keyword, the options -fargument-alias, -fargument-noalias, and -fargument-noalias-global, and the corresponding alias-analysis code.

      (egcs has the alias-analysis code, but not the __restrict__ keyword. egcs g77 users benefit from the alias-analysis code despite the lack of the __restrict__ keyword, which is a C-language construct.)

    • Support for the GNU compiler options -fmove-all-movables, -freduce-all-givs, and -frerun-loop-opt.

      (egcs supports these options. g77 users of egcs benefit from them even if they are not explicitly specified, because the defaults are optimized for g77 users.)

    • Support for the -W option warning about integer division by zero.
    • The Intel x86-specific option -malign-double applying to stack-allocated data as well as statically-allocate data.
  • Support gcc version 2.8, and remove support for prior versions of gcc.
  • Remove support for the --driver option, as g77 now does all the driving, just like gcc.
  • The g77 command now expects the run-time library to be named libg2c.a instead of libf2c.a, to ensure that a version other than the one built and installed as part of the same g77 version is picked up.
  • g77's version of libf2c separates out the setting of global state (such as command-line arguments and signal handling) from main.o into distinct, new library archive members.

    This should make it easier to write portable applications that have their own (non-Fortran) main() routine properly set up the libf2c environment, even when libf2c (now libg2c) is a shared library.

  • Some diagnostics have been changed from warnings to errors, to prevent inadvertent use of the resulting, probably buggy, programs. These mostly include diagnostics about use of unsupported features in the OPEN, INQUIRE, READ, and WRITE statements, and about truncations of various sorts of constants.

In 0.5.22 versus 0.5.21:

  • Fix Signal intrinsic so it offers portable support for 64-bit systems (such as Digital Alphas running GNU/Linux).
  • Support FORMAT(I<expr>) when expr is a compile-time constant INTEGER expression.
  • Fix g77 -g option so procedures that use ENTRY can be stepped through, line by line, in gdb.
  • Allow any REAL argument to intrinsics Second and CPU_Time.
  • Allow any numeric argument to intrinsics Int2 and Int8.
  • Use tempnam, if available, to open scratch files (as in OPEN(STATUS='SCRATCH')) so that the TMPDIR environment variable, if present, is used.
  • Rename the gcc keyword restrict to __restrict__, to avoid rejecting valid, existing, C programs. Support for restrict is now more like support for complex.
  • Fix -fugly-comma to affect invocations of only external procedures. Restore rejection of gratuitous trailing omitted arguments to intrinsics, as in I=MAX(3,4,,).
  • Fix compiler so it accepts -fgnu-intrinsics-* and -fbadu77-intrinsics-* options.

In EGCS 1.0.2 versus EGCS 1.0.1:

  • Fix compiler so it accepts -fgnu-intrinsics-* and -fbadu77-intrinsics-* options.

In EGCS 1.0.1 versus EGCS 1.0:

In EGCS 1.0 versus g77 0.5.21:

  • Version 1.0 of egcs contains several regressions against version 0.5.21 of g77, due to using the "vanilla" gcc back end instead of patching it to fix a few bugs and improve performance in a few cases.

    Features that have been dropped from this version of g77 due to their being implemented via g77-specific patches to the gcc back end in previous releases include:

    • Support for the C-language restrict keyword.
    • Support for the -W option warning about integer division by zero.
    • The Intel x86-specific option -malign-double applying to stack-allocated data as well as statically-allocate data.
  • Remove support for the --driver option, as g77 now does all the driving, just like gcc.
  • Allow any numeric argument to intrinsics Int2 and Int8.

In 0.5.21:

  • When the -W option is specified, gcc, g77, and other GNU compilers that incorporate the gcc back end as modified by g77, issue a warning about integer division by constant zero.
  • New option -Wno-globals disables warnings about "suspicious" use of a name both as a global name and as the implicit name of an intrinsic, and warnings about disagreements over the number or natures of arguments passed to global procedures, or the natures of the procedures themselves.

    The default is to issue such warnings, which are new as of this version of g77.

  • New option -fno-globals disables diagnostics about potentially fatal disagreements analysis problems, such as disagreements over the number or natures of arguments passed to global procedures, or the natures of those procedures themselves.

    The default is to issue such diagnostics and flag the compilation as unsuccessful. With this option, the diagnostics are issued as warnings, or, if -Wno-globals is specified, are not issued at all.

    This option also disables inlining of global procedures, to avoid compiler crashes resulting from coding errors that these diagnostics normally would identify.

  • Fix libU77 routines that accept file and other names to strip trailing blanks from them, for consistency with other implementations. Blanks may be forcibly appended to such names by appending a single null character (CHAR(0)) to the significant trailing blanks.
  • Fix CHMOD intrinsic to work with file names that have embedded blanks, commas, and so on.
  • Fix SIGNAL intrinsic so it accepts an optional third Status argument.
  • Make many changes to libU77 intrinsics to support existing code more directly.

    Such changes include allowing both subroutine and function forms of many routines, changing MCLOCK() and TIME() to return INTEGER(KIND=1) values, introducing MCLOCK8() and TIME8() to return INTEGER(KIND=2) values, and placing functions that are intended to perform side effects in a new intrinsic group, badu77.

  • Add options -fbadu77-intrinsics-delete, -fbadu77-intrinsics-hide, and so on.
  • Add INT2 and INT8 intrinsics.
  • Add CPU_TIME intrinsic.
  • Add ALARM intrinsic.
  • CTIME intrinsic now accepts any INTEGER argument, not just INTEGER(KIND=2).
  • g77 driver now prints version information (such as produced by g77 -v) to stderr instead of stdout.
  • The .r suffix now designates a Ratfor source file, to be preprocessed via the ratfor command, available separately.

In 0.5.20:

  • The -fno-typeless-boz option is now the default.

    This option specifies that non-decimal-radix constants using the prefixed-radix form (such as Z'1234') are to be interpreted as INTEGER(KIND=1) constants. Specify -ftypeless-boz to cause such constants to be interpreted as typeless.

    (Version 0.5.19 introduced -fno-typeless-boz and its inverse.)

    See Options Controlling Fortran Dialect, for information on the -ftypeless-boz option.

  • Options -ff90-intrinsics-enable and -fvxt-intrinsics-enable now are the defaults.

    Some programs might use names that clash with intrinsic names defined (and now enabled) by these options or by the new libU77 intrinsics. Users of such programs might need to compile them differently (using, for example, -ff90-intrinsics-disable) or, better yet, insert appropriate EXTERNAL statements specifying that these names are not intended to be names of intrinsics.

  • The ALWAYS_FLUSH macro is no longer defined when building libf2c, which should result in improved I/O performance, especially over NFS.

    Note: If you have code that depends on the behavior of libf2c when built with ALWAYS_FLUSH defined, you will have to modify libf2c accordingly before building it from this and future versions of g77.

    See Output Assumed To Flush, for more information.

  • Dave Love's implementation of libU77 has been added to the version of libf2c distributed with and built as part of g77. g77 now knows about the routines in this library as intrinsics.
  • New option -fvxt specifies that the source file is written in VXT Fortran, instead of GNU Fortran.

    See VXT Fortran, for more information on the constructs recognized when the -fvxt option is specified.

  • The -fvxt-not-f90 option has been deleted, along with its inverse, -ff90-not-vxt.

    If you used one of these deleted options, you should re-read the pertinent documentation to determine which options, if any, are appropriate for compiling your code with this version of g77.

    See Other Dialects, for more information.

  • The -fugly option now issues a warning, as it likely will be removed in a future version.

    (Enabling all the -fugly-* options is unlikely to be feasible, or sensible, in the future, so users should learn to specify only those -fugly-* options they really need for a particular source file.)

  • The -fugly-assumed option, introduced in version 0.5.19, has been changed to better accommodate old and new code.

    See Ugly Assumed-Size Arrays, for more information.

  • Related to supporting Alpha (AXP) machines, the LOC() intrinsic and %LOC() construct now return values of INTEGER(KIND=0) type, as defined by the GNU Fortran language.

    This type is wide enough (holds the same number of bits) as the character-pointer type on the machine.

    On most machines, this won't make a difference, whereas, on Alphas and other systems with 64-bit pointers, the INTEGER(KIND=0) type is equivalent to INTEGER(KIND=2) (often referred to as INTEGER*8) instead of the more common INTEGER(KIND=1) (often referred to as INTEGER*4).

  • Emulate COMPLEX arithmetic in the g77 front end, to avoid bugs in complex support in the gcc back end. New option -fno-emulate-complex causes g77 to revert the 0.5.19 behavior.
  • Dummy arguments are no longer assumed to potentially alias (overlap) other dummy arguments or COMMON areas when any of these are defined (assigned to) by Fortran code.

    This can result in faster and/or smaller programs when compiling with optimization enabled, though on some systems this effect is observed only when -fforce-addr also is specified.

    New options -falias-check, -fargument-alias, -fargument-noalias, and -fno-argument-noalias-global control the way g77 handles potential aliasing.

    See Aliasing Assumed To Work, for detailed information on why the new defaults might result in some programs no longer working the way they did when compiled by previous versions of g77.

  • New option -fugly-assign specifies that the same memory locations are to be used to hold the values assigned by both statements I = 3 and ASSIGN 10 TO I, for example. (Normally, g77 uses a separate memory location to hold assigned statement labels.)

    See Ugly Assigned Labels, for more information.

  • FORMAT and ENTRY statements now are allowed to precede IMPLICIT NONE statements.
  • Enable full support of INTEGER(KIND=2) (often referred to as INTEGER*8) available in libf2c and f2c.h so that f2c users may make full use of its features via the g77 version of f2c.h and the INTEGER(KIND=2) support routines in the g77 version of libf2c.
  • Improve g77 driver and libf2c so that g77 -v yields version information on the library.
  • The SNGL and FLOAT intrinsics now are specific intrinsics, instead of synonyms for the generic intrinsic REAL.
  • New intrinsics have been added. These are REALPART, IMAGPART, COMPLEX, LONG, and SHORT.
  • A new group of intrinsics, gnu, has been added to contain the new REALPART, IMAGPART, and COMPLEX intrinsics. An old group, dcp, has been removed.
  • Complain about industry-wide ambiguous references REAL(expr) and AIMAG(expr), where expr is DOUBLE COMPLEX (or any complex type other than COMPLEX), unless -ff90 option specifies Fortran 90 interpretation or new -fugly-complex option, in conjunction with -fnot-f90, specifies f2c interpretation.

In previous versions:

Information on previous versions is archived in gcc/gcc/f/news.texi following the test of the DOC-OLDNEWS macro.


Node:Char Intrinsic, Next:ChDir Intrinsic (subroutine), Previous:CExp Intrinsic, Up:Table of Intrinsic Functions

Char Intrinsic

Char(I)

Char: CHARACTER*1 function.

I: INTEGER; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the character corresponding to the code specified by I, using the system's native character set.

Because the system's native character set is used, the correspondence between character and their codes is not necessarily the same between GNU Fortran implementations.

Note that no intrinsic exists to convert a numerical value to a printable character string. For example, there is no intrinsic that, given an INTEGER or REAL argument with the value 154, returns the CHARACTER result '154'.

Instead, you can use internal-file I/O to do this kind of conversion. For example:

INTEGER VALUE
CHARACTER*10 STRING
VALUE = 154
WRITE (STRING, '(I10)'), VALUE
PRINT *, STRING
END

The above program, when run, prints:

        154

See IChar Intrinsic, for the inverse of the CHAR function.

See AChar Intrinsic, for the function corresponding to the ASCII character set.


Node:Character and Hollerith Constants, Previous:Ease of Debugging, Up:Advantages Over f2c

Character and Hollerith Constants

To avoid the extensive hassle that would be needed to avoid this, f2c uses C character constants to encode character and Hollerith constants. That means a constant like 'HELLO' is translated to "hello" in C, which further means that an extra null byte is present at the end of the constant. This null byte is superfluous.

g77 does not generate such null bytes. This represents significant savings of resources, such as on systems where /dev/null or /dev/zero represent bottlenecks in the systems' performance, because g77 simply asks for fewer zeros from the operating system than f2c. (Avoiding spurious use of zero bytes, each byte typically have eight zero bits, also reduces the liabilities in case Microsoft's rumored patent on the digits 0 and 1 is upheld.)


Node:Character Set, Next:Lines, Up:Characters Lines Sequence

GNU Fortran Character Set

(Corresponds to Section 3.1 of ANSI X3.9-1978 FORTRAN 77.)

Letters include uppercase letters (the twenty-six characters of the English alphabet) and lowercase letters (their lowercase equivalent). Generally, lowercase letters may be used in place of uppercase letters, though in character and Hollerith constants, they are distinct.

Special characters include:

  • Semicolon (;)
  • Exclamation point (!)
  • Double quote (")
  • Backslash (\)
  • Question mark (?)
  • Hash mark (#)
  • Ampersand (&)
  • Percent sign (%)
  • Underscore (_)
  • Open angle (<)
  • Close angle (>)
  • The FORTRAN 77 special characters (<SPC>, =, +, -, *, /, (, ), ,, ., $, ', and :)

Note that this document refers to <SPC> as space, while X3.9-1978 FORTRAN 77 refers to it as blank.


Node:Character Type, Previous:Integer Type, Up:Data Types and Constants

Character Type

(Corresponds to Section 4.8 of ANSI X3.9-1978 FORTRAN 77.)

A character constant may be delimited by a pair of double quotes (") instead of apostrophes. In this case, an apostrophe within the constant represents a single apostrophe, while a double quote is represented in the source text of the constant by two consecutive double quotes with no intervening spaces.

A character constant may be empty (have a length of zero).

A character constant may include a substring specification, The value of such a constant is the value of the substring--for example, the value of 'hello'(3:5) is the same as the value of 'llo'.


Node:Character-variable Length, Next:Year 10000 (Y10K) Problems, Previous:Array Size, Up:Run-time Environment Limits

Character-variable Length

Currently, g77 uses the default INTEGER type for the lengths of CHARACTER variables and array elements.

This means that, for example, a system with a 64-bit address space and a 32-bit default INTEGER type does not, under g77, support a CHARACTER*n declaration where n is greater than 2147483647.


Node:Characters Lines Sequence, Next:Data Types and Constants, Previous:Terms and Concepts, Up:Language

Characters, Lines, and Execution Sequence

(The following information augments or overrides the information in Chapter 3 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 3 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

  • Character Set:
  • Lines:
  • Continuation Line:
  • Statements:
  • Statement Labels:
  • Order:
  • INCLUDE:
  • Cpp-style directives:


Node:ChDir Intrinsic (function), Next:ChMod Intrinsic (function), Previous:CDSqRt Intrinsic, Up:Other Intrinsics

ChDir Intrinsic (function)

ChDir(Dir)

ChDir: INTEGER(KIND=1) function.

Dir: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Sets the current working directory to be Dir. Returns 0 on success or a non-zero error code. See chdir(3).

Caution: Using this routine during I/O to a unit connected with a non-absolute file name can cause subsequent I/O on such a unit to fail because the I/O library might reopen files by name.

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See ChDir Intrinsic (subroutine).


Node:ChDir Intrinsic (subroutine), Next:ChMod Intrinsic (subroutine), Previous:Char Intrinsic, Up:Table of Intrinsic Functions

ChDir Intrinsic (subroutine)

CALL ChDir(Dir, Status)

Dir: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Sets the current working directory to be Dir. If the Status argument is supplied, it contains 0 on success or a non-zero error code otherwise upon return. See chdir(3).

Caution: Using this routine during I/O to a unit connected with a non-absolute file name can cause subsequent I/O on such a unit to fail because the I/O library might reopen files by name.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See ChDir Intrinsic (function).


Node:ChMod Intrinsic (function), Next:CosD Intrinsic, Previous:ChDir Intrinsic (function), Up:Other Intrinsics

ChMod Intrinsic (function)

ChMod(Name, Mode)

ChMod: INTEGER(KIND=1) function.

Name: CHARACTER; scalar; INTENT(IN).

Mode: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Changes the access mode of file Name according to the specification Mode, which is given in the format of chmod(1). A null character (CHAR(0)) marks the end of the name in Name--otherwise, trailing blanks in Name are ignored. Currently, Name must not contain the single quote character.

Returns 0 on success or a non-zero error code otherwise.

Note that this currently works by actually invoking /bin/chmod (or the chmod found when the library was configured) and so might fail in some circumstances and will, anyway, be slow.

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See ChMod Intrinsic (subroutine).


Node:ChMod Intrinsic (subroutine), Next:CLog Intrinsic, Previous:ChDir Intrinsic (subroutine), Up:Table of Intrinsic Functions

ChMod Intrinsic (subroutine)

CALL ChMod(Name, Mode, Status)

Name: CHARACTER; scalar; INTENT(IN).

Mode: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Changes the access mode of file Name according to the specification Mode, which is given in the format of chmod(1). A null character (CHAR(0)) marks the end of the name in Name--otherwise, trailing blanks in Name are ignored. Currently, Name must not contain the single quote character.

If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return.

Note that this currently works by actually invoking /bin/chmod (or the chmod found when the library was configured) and so might fail in some circumstances and will, anyway, be slow.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See ChMod Intrinsic (function).


Node:CLog Intrinsic, Next:Cmplx Intrinsic, Previous:ChMod Intrinsic (subroutine), Up:Table of Intrinsic Functions

CLog Intrinsic

CLog(X)

CLog: COMPLEX(KIND=1) function.

X: COMPLEX(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of LOG() that is specific to one type for X. See Log Intrinsic.


Node:CMPAMBIG, Next:EXPIMP, Up:Diagnostics

CMPAMBIG

Ambiguous use of intrinsic intrinsic ...

The type of the argument to the invocation of the intrinsic intrinsic is a COMPLEX type other than COMPLEX(KIND=1). Typically, it is COMPLEX(KIND=2), also known as DOUBLE COMPLEX.

The interpretation of this invocation depends on the particular dialect of Fortran for which the code was written. Some dialects convert the real part of the argument to REAL(KIND=1), thus losing precision; other dialects, and Fortran 90, do no such conversion.

So, GNU Fortran rejects such invocations except under certain circumstances, to avoid making an incorrect assumption that results in generating the wrong code.

To determine the dialect of the program unit, perhaps even whether that particular invocation is properly coded, determine how the result of the intrinsic is used.

The result of intrinsic is expected (by the original programmer) to be REAL(KIND=1) (the non-Fortran-90 interpretation) if:

  • It is passed as an argument to a procedure that explicitly or implicitly declares that argument REAL(KIND=1).

    For example, a procedure with no DOUBLE PRECISION or IMPLICIT DOUBLE PRECISION statement specifying the dummy argument corresponding to an actual argument of REAL(Z), where Z is declared DOUBLE COMPLEX, strongly suggests that the programmer expected REAL(Z) to return REAL(KIND=1) instead of REAL(KIND=2).

  • It is used in a context that would otherwise not include any REAL(KIND=2) but where treating the intrinsic invocation as REAL(KIND=2) would result in unnecessary promotions and (typically) more expensive operations on the wider type.

    For example:

    DOUBLE COMPLEX Z
...
R(1) = T * REAL(Z)

    The above example suggests the programmer expected the real part of Z to be converted to REAL(KIND=1) before being multiplied by T (presumed, along with R above, to be type REAL(KIND=1)).

    Otherwise, the conversion would have to be delayed until after the multiplication, requiring not only an extra conversion (of T to REAL(KIND=2)), but a (typically) more expensive multiplication (a double-precision multiplication instead of a single-precision one).

The result of intrinsic is expected (by the original programmer) to be REAL(KIND=2) (the Fortran 90 interpretation) if:

  • It is passed as an argument to a procedure that explicitly or implicitly declares that argument REAL(KIND=2).

    For example, a procedure specifying a DOUBLE PRECISION dummy argument corresponding to an actual argument of REAL(Z), where Z is declared DOUBLE COMPLEX, strongly suggests that the programmer expected REAL(Z) to return REAL(KIND=2) instead of REAL(KIND=1).

  • It is used in an expression context that includes other REAL(KIND=2) operands, or is assigned to a REAL(KIND=2) variable or array element.

    For example:

    DOUBLE COMPLEX Z
DOUBLE PRECISION R, T
...
R(1) = T * REAL(Z)

    The above example suggests the programmer expected the real part of Z to not be converted to REAL(KIND=1) by the REAL() intrinsic.

    Otherwise, the conversion would have to be immediately followed by a conversion back to REAL(KIND=2), losing the original, full precision of the real part of Z, before being multiplied by T.

Once you have determined whether a particular invocation of intrinsic expects the Fortran 90 interpretation, you can:

  • Change it to DBLE(expr) (if intrinsic is REAL) or DIMAG(expr) (if intrinsic is AIMAG) if it expected the Fortran 90 interpretation.

    This assumes expr is COMPLEX(KIND=2)--if it is some other type, such as COMPLEX*32, you should use the appropriate intrinsic, such as the one to convert to REAL*16 (perhaps DBLEQ() in place of DBLE(), and QIMAG() in place of DIMAG()).

  • Change it to REAL(intrinsic(expr)), otherwise. This converts to REAL(KIND=1) in all working Fortran compilers.

If you don't want to change the code, and you are certain that all ambiguous invocations of intrinsic in the source file have the same expectation regarding interpretation, you can:

  • Compile with the g77 option -ff90, to enable the Fortran 90 interpretation.
  • Compile with the g77 options -fno-f90 -fugly-complex, to enable the non-Fortran-90 interpretations.

See REAL() and AIMAG() of Complex, for more information on this issue.

Note: If the above suggestions don't produce enough evidence as to whether a particular program expects the Fortran 90 interpretation of this ambiguous invocation of intrinsic, there is one more thing you can try.

If you have access to most or all the compilers used on the program to create successfully tested and deployed executables, read the documentation for, and also test out, each compiler to determine how it treats the intrinsic intrinsic in this case. (If all the compilers don't agree on an interpretation, there might be lurking bugs in the deployed versions of the program.)

The following sample program might help:

      PROGRAM JCB003
C
C Written by James Craig Burley 1997-02-23.
C
C Determine how compilers handle non-standard REAL
C and AIMAG on DOUBLE COMPLEX operands.
C
      DOUBLE COMPLEX Z
      REAL R
      Z = (3.3D0, 4.4D0)
      R = Z
      CALL DUMDUM(Z, R)
      R = REAL(Z) - R
      IF (R .NE. 0.) PRINT *, 'REAL() is Fortran 90'
      IF (R .EQ. 0.) PRINT *, 'REAL() is not Fortran 90'
      R = 4.4D0
      CALL DUMDUM(Z, R)
      R = AIMAG(Z) - R
      IF (R .NE. 0.) PRINT *, 'AIMAG() is Fortran 90'
      IF (R .EQ. 0.) PRINT *, 'AIMAG() is not Fortran 90'
      END
C
C Just to make sure compiler doesn't use naive flow
C analysis to optimize away careful work above,
C which might invalidate results....
C
      SUBROUTINE DUMDUM(Z, R)
      DOUBLE COMPLEX Z
      REAL R
      END

If the above program prints contradictory results on a particular compiler, run away!


Node:CMPLX() of DOUBLE PRECISION, Next:MIL-STD 1753, Previous:REAL() and AIMAG() of Complex, Up:Functions and Subroutines

CMPLX() of DOUBLE PRECISION

In accordance with Fortran 90 and at least some (perhaps all) other compilers, the GNU Fortran language defines CMPLX() as always returning a result that is type COMPLEX(KIND=1).

This means CMPLX(D1,D2), where D1 and D2 are REAL(KIND=2) (DOUBLE PRECISION), is treated as:

CMPLX(SNGL(D1), SNGL(D2))

(It was necessary for Fortran 90 to specify this behavior for DOUBLE PRECISION arguments, since that is the behavior mandated by FORTRAN 77.)

The GNU Fortran language also provides the DCMPLX() intrinsic, which is provided by some FORTRAN 77 compilers to construct a DOUBLE COMPLEX entity from of DOUBLE PRECISION operands. However, this solution does not scale well when more COMPLEX types (having various precisions and ranges) are offered by Fortran implementations.

Fortran 90 extends the CMPLX() intrinsic by adding an extra argument used to specify the desired kind of complex result. However, this solution is somewhat awkward to use, and g77 currently does not support it.

The GNU Fortran language provides a simple way to build a complex value out of two numbers, with the precise type of the value determined by the types of the two numbers (via the usual type-promotion mechanism):

COMPLEX(real, imag)

When real and imag are the same REAL types, COMPLEX() performs no conversion other than to put them together to form a complex result of the same (complex version of real) type.

See Complex Intrinsic, for more information.


Node:Cmplx Intrinsic, Next:Complex Intrinsic, Previous:CLog Intrinsic, Up:Table of Intrinsic Functions

Cmplx Intrinsic

Cmplx(X, Y)

Cmplx: COMPLEX(KIND=1) function.

X: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Y: INTEGER or REAL; OPTIONAL (must be omitted if X is COMPLEX); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

If X is not type COMPLEX, constructs a value of type COMPLEX(KIND=1) from the real and imaginary values specified by X and Y, respectively. If Y is omitted, 0. is assumed.

If X is type COMPLEX, converts it to type COMPLEX(KIND=1).

See Complex Intrinsic, for information on easily constructing a COMPLEX value of arbitrary precision from REAL arguments.


Node:Code Gen Options, Next:Environment Variables, Previous:Directory Options, Up:Invoking G77

Options for Code Generation Conventions

These machine-independent options control the interface conventions used in code generation.

Most of them have both positive and negative forms; the negative form of -ffoo would be -fno-foo. In the table below, only one of the forms is listed--the one which is not the default. You can figure out the other form by either removing no- or adding it.

-fno-automatic
Treat each program unit as if the SAVE statement was specified for every local variable and array referenced in it. Does not affect common blocks. (Some Fortran compilers provide this option under the name -static.)
-finit-local-zero
Specify that variables and arrays that are local to a program unit (not in a common block and not passed as an argument) are to be initialized to binary zeros.

Since there is a run-time penalty for initialization of variables that are not given the SAVE attribute, it might be a good idea to also use -fno-automatic with -finit-local-zero.

-fno-f2c
Do not generate code designed to be compatible with code generated by f2c use the GNU calling conventions instead.

The f2c calling conventions require functions that return type REAL(KIND=1) to actually return the C type double, and functions that return type COMPLEX to return the values via an extra argument in the calling sequence that points to where to store the return value. Under the GNU calling conventions, such functions simply return their results as they would in GNU C--REAL(KIND=1) functions return the C type float, and COMPLEX functions return the GNU C type complex (or its struct equivalent).

This does not affect the generation of code that interfaces with the libg2c library.

However, because the libg2c library uses f2c calling conventions, g77 rejects attempts to pass intrinsics implemented by routines in this library as actual arguments when -fno-f2c is used, to avoid bugs when they are actually called by code expecting the GNU calling conventions to work.

For example, INTRINSIC ABS;CALL FOO(ABS) is rejected when -fno-f2c is in force. (Future versions of the g77 run-time library might offer routines that provide GNU-callable versions of the routines that implement the f2c intrinsics that may be passed as actual arguments, so that valid programs need not be rejected when -fno-f2c is used.)

Caution: If -fno-f2c is used when compiling any source file used in a program, it must be used when compiling all Fortran source files used in that program.

-ff2c-library
Specify that use of libg2c (or the original libf2c) is required. This is the default for the current version of g77

Currently it is not valid to specify -fno-f2c-library. This option is provided so users can specify it in shell scripts that build programs and libraries that require the libf2c library, even when being compiled by future versions of g77 that might otherwise default to generating code for an incompatible library.

-fno-underscoring
Do not transform names of entities specified in the Fortran source file by appending underscores to them.

With -funderscoring in effect, g77 appends two underscores to names with underscores and one underscore to external names with no underscores. (g77 also appends two underscores to internal names with underscores to avoid naming collisions with external names. The -fno-second-underscore option disables appending of the second underscore in all cases.)

This is done to ensure compatibility with code produced by many UNIX Fortran compilers, including f2c which perform the same transformations.

Use of -fno-underscoring is not recommended unless you are experimenting with issues such as integration of (GNU) Fortran into existing system environments (vis-a-vis existing libraries, tools, and so on).

For example, with -funderscoring, and assuming other defaults like -fcase-lower and that j() and max_count() are external functions while my_var and lvar are local variables, a statement like

I = J() + MAX_COUNT (MY_VAR, LVAR)

is implemented as something akin to:

i = j_() + max_count__(&my_var__, &lvar);

With -fno-underscoring, the same statement is implemented as:

i = j() + max_count(&my_var, &lvar);

Use of -fno-underscoring allows direct specification of user-defined names while debugging and when interfacing g77 code with other languages.

Note that just because the names match does not mean that the interface implemented by g77 for an external name matches the interface implemented by some other language for that same name. That is, getting code produced by g77 to link to code produced by some other compiler using this or any other method can be only a small part of the overall solution--getting the code generated by both compilers to agree on issues other than naming can require significant effort, and, unlike naming disagreements, linkers normally cannot detect disagreements in these other areas.

Also, note that with -fno-underscoring, the lack of appended underscores introduces the very real possibility that a user-defined external name will conflict with a name in a system library, which could make finding unresolved-reference bugs quite difficult in some cases--they might occur at program run time, and show up only as buggy behavior at run time.

In future versions of g77 we hope to improve naming and linking issues so that debugging always involves using the names as they appear in the source, even if the names as seen by the linker are mangled to prevent accidental linking between procedures with incompatible interfaces.

-fno-second-underscore
Do not append a second underscore to names of entities specified in the Fortran source file.

This option has no effect if -fno-underscoring is in effect.

Otherwise, with this option, an external name such as MAX_COUNT is implemented as a reference to the link-time external symbol max_count_, instead of max_count__.

-fno-ident
Ignore the #ident directive.
-fzeros
Treat initial values of zero as if they were any other value.

As of version 0.5.18, g77 normally treats DATA and other statements that are used to specify initial values of zero for variables and arrays as if no values were actually specified, in the sense that no diagnostics regarding multiple initializations are produced.

This is done to speed up compiling of programs that initialize large arrays to zeros.

Use -fzeros to revert to the simpler, slower behavior that can catch multiple initializations by keeping track of all initializations, zero or otherwise.

Caution: Future versions of g77 might disregard this option (and its negative form, the default) or interpret it somewhat differently. The interpretation changes will affect only non-standard programs; standard-conforming programs should not be affected.

-femulate-complex
Implement COMPLEX arithmetic via emulation, instead of using the facilities of the gcc back end that provide direct support of complex arithmetic.

(gcc had some bugs in its back-end support for complex arithmetic, due primarily to the support not being completed as of version 2.8.1 and egcs 1.1.2.)

Use -femulate-complex if you suspect code-generation bugs, or experience compiler crashes, that might result from g77 using the COMPLEX support in the gcc back end. If using that option fixes the bugs or crashes you are seeing, that indicates a likely g77 bugs (though, all compiler crashes are considered bugs), so, please report it. (Note that the known bugs, now believed fixed, produced compiler crashes rather than causing the generation of incorrect code.)

Use of this option should not affect how Fortran code compiled by g77 works in terms of its interfaces to other code, e.g. that compiled by f2c

As of GCC version 3.0, this option is not necessary anymore.

Caution: Future versions of g77 might ignore both forms of this option.

-falias-check
-fargument-alias
-fargument-noalias
-fno-argument-noalias-global
Version info: These options are not supported by versions of g77 based on gcc version 2.8.

These options specify to what degree aliasing (overlap) is permitted between arguments (passed as pointers) and COMMON (external, or public) storage.

The default for Fortran code, as mandated by the FORTRAN 77 and Fortran 90 standards, is -fargument-noalias-global. The default for code written in the C language family is -fargument-alias.

Note that, on some systems, compiling with -fforce-addr in effect can produce more optimal code when the default aliasing options are in effect (and when optimization is enabled).

See Aliasing Assumed To Work, for detailed information on the implications of compiling Fortran code that depends on the ability to alias dummy arguments.

-fno-globals
Disable diagnostics about inter-procedural analysis problems, such as disagreements about the type of a function or a procedure's argument, that might cause a compiler crash when attempting to inline a reference to a procedure within a program unit. (The diagnostics themselves are still produced, but as warnings, unless -Wno-globals is specified, in which case no relevant diagnostics are produced.)

Further, this option disables such inlining, to avoid compiler crashes resulting from incorrect code that would otherwise be diagnosed.

As such, this option might be quite useful when compiling existing, "working" code that happens to have a few bugs that do not generally show themselves, but which g77 diagnoses.

Use of this option therefore has the effect of instructing g77 to behave more like it did up through version 0.5.19.1, when it paid little or no attention to disagreements between program units about a procedure's type and argument information, and when it performed no inlining of procedures (except statement functions).

Without this option, g77 defaults to performing the potentially inlining procedures as it started doing in version 0.5.20, but as of version 0.5.21, it also diagnoses disagreements that might cause such inlining to crash the compiler as (fatal) errors, and warns about similar disagreements that are currently believed to not likely to result in the compiler later crashing or producing incorrect code.

-fflatten-arrays
Use back end's C-like constructs (pointer plus offset) instead of its ARRAY_REF construct to handle all array references.

Note: This option is not supported. It is intended for use only by g77 developers, to evaluate code-generation issues. It might be removed at any time.

-fbounds-check
-ffortran-bounds-check
Enable generation of run-time checks for array subscripts and substring start and end points against the (locally) declared minimum and maximum values.

The current implementation uses the libf2c library routine s_rnge to print the diagnostic.

However, whereas f2c generates a single check per reference for a multi-dimensional array, of the computed offset against the valid offset range (0 through the size of the array), g77 generates a single check per subscript expression. This catches some cases of potential bugs that f2c does not, such as references to below the beginning of an assumed-size array.

g77 also generates checks for CHARACTER substring references, something f2c currently does not do.

Use the new -ffortran-bounds-check option to specify bounds-checking for only the Fortran code you are compiling, not necessarily for code written in other languages.

Note: To provide more detailed information on the offending subscript, g77 provides the libg2c run-time library routine s_rnge with somewhat differently-formatted information. Here's a sample diagnostic:

Subscript out of range on file line 4, procedure rnge.f/bf.
Attempt to access the -6-th element of variable b[subscript-2-of-2].
Aborted

The above message indicates that the offending source line is line 4 of the file rnge.f, within the program unit (or statement function) named bf. The offended array is named b. The offended array dimension is the second for a two-dimensional array, and the offending, computed subscript expression was -6.

For a CHARACTER substring reference, the second line has this appearance:

Attempt to access the 11-th element of variable a[start-substring].

This indicates that the offended CHARACTER variable or array is named a, the offended substring position is the starting (leftmost) position, and the offending substring expression is 11.

(Though the verbage of s_rnge is not ideal for the purpose of the g77 compiler, the above information should provide adequate diagnostic abilities to it users.)

See Options for Code Generation Conventions, for information on more options offered by the GBE shared by g77 gcc and other GNU compilers.

Some of these do not work when compiling programs written in Fortran:

-fpcc-struct-return
-freg-struct-return
You should not use these except strictly the same way as you used them to build the version of libg2c with which you will be linking all code compiled by g77 with the same option.
-fshort-double
This probably either has no effect on Fortran programs, or makes them act loopy.
-fno-common
Do not use this when compiling Fortran programs, or there will be Trouble.
-fpack-struct
This probably will break any calls to the libg2c library, at the very least, even if it is built with the same option.


Node:Collected Fortran Wisdom, Next:Trouble, Previous:Debugging and Interfacing, Up:Top

Collected Fortran Wisdom

Most users of g77 can be divided into two camps:

  • Those writing new Fortran code to be compiled by g77.
  • Those using g77 to compile existing, "legacy" code.

Users writing new code generally understand most of the necessary aspects of Fortran to write "mainstream" code, but often need help deciding how to handle problems, such as the construction of libraries containing BLOCK DATA.

Users dealing with "legacy" code sometimes don't have much experience with Fortran, but believe that the code they're compiling already works when compiled by other compilers (and might not understand why, as is sometimes the case, it doesn't work when compiled by g77).

The following information is designed to help users do a better job coping with existing, "legacy" Fortran code, and with writing new code as well.

  • Advantages Over f2c: If f2c is so great, why g77?
  • Block Data and Libraries: How g77 solves a common problem.
  • Loops: Fortran DO loops surprise many people.
  • Working Programs: Getting programs to work should be done first.
  • Overly Convenient Options: Temptations to avoid, habits to not form.
  • Faster Programs: Everybody wants these, but at what cost?


Node:Common Blocks, Next:Local Equivalence Areas, Previous:Names, Up:Debugging and Interfacing

Common Blocks (COMMON)

g77 names and lays out COMMON areas the same way f2c does, for compatibility with f2c.


Node:Compiler Intrinsics, Previous:Compiler Constants, Up:Compiler

Compiler Intrinsics

g77 offers an ever-widening set of intrinsics. Currently these all are procedures (functions and subroutines).

Some of these intrinsics are unimplemented, but their names reserved to reduce future problems with existing code as they are implemented. Others are implemented as part of the GNU Fortran language, while yet others are provided for compatibility with other dialects of Fortran but are not part of the GNU Fortran language.

To manage these distinctions, g77 provides intrinsic groups, a facility that is simply an extension of the intrinsic groups provided by the GNU Fortran language.

  • Intrinsic Groups: How intrinsics are grouped for easy management.
  • Other Intrinsics: Intrinsics other than those in the GNU Fortran language.


Node:Compiler Limits, Next:Run-time Environment Limits, Up:Compiler

Compiler Limits

g77, as with GNU tools in general, imposes few arbitrary restrictions on lengths of identifiers, number of continuation lines, number of external symbols in a program, and so on.

For example, some other Fortran compiler have an option (such as -Nlx) to increase the limit on the number of continuation lines. Also, some Fortran compilation systems have an option (such as -Nxx) to increase the limit on the number of external symbols.

g77, gcc, and GNU ld (the GNU linker) have no equivalent options, since they do not impose arbitrary limits in these areas.

g77 does currently limit the number of dimensions in an array to the same degree as do the Fortran standards--seven (7). This restriction might be lifted in a future version.


Node:Compiler Options, Next:Compiler Speed, Previous:Diagnostic Abilities, Up:Advantages Over f2c

Compiler Options

g77 offers compiler options that f2c doesn't, most of which are designed to more easily accommodate legacy code:

  • Two that control the automatic appending of extra underscores to external names
  • One that allows dollar signs ($) in symbol names
  • A variety that control acceptance of various "ugly" constructs
  • Several that specify acceptable use of upper and lower case in the source code
  • Many that enable, disable, delete, or hide groups of intrinsics
  • One to specify the length of fixed-form source lines (normally 72)
  • One to specify the the source code is written in Fortran-90-style free-form

However, f2c offers a few that g77 doesn't, like an option to have REAL default to REAL*8. It is expected that g77 will offer all of the missing options pertinent to being a Fortran compiler at some time in the future.


Node:Compiler Speed, Next:Program Speed, Previous:Compiler Options, Up:Advantages Over f2c

Compiler Speed

Saving the steps of writing and then rereading C code is a big reason why g77 should be able to compile code much faster than using f2c in conjunction with the equivalent invocation of gcc.

However, due to g77's youth, lots of self-checking is still being performed. As a result, this improvement is as yet unrealized (though the potential seems to be there for quite a big speedup in the future). It is possible that, as of version 0.5.18, g77 is noticeably faster compiling many Fortran source files than using f2c in conjunction with gcc.


Node:Compiler Types, Next:Compiler Constants, Previous:Run-time Environment Limits, Up:Compiler

Compiler Types

Fortran implementations have a fair amount of freedom given them by the standard as far as how much storage space is used and how much precision and range is offered by the various types such as LOGICAL(KIND=1), INTEGER(KIND=1), REAL(KIND=1), REAL(KIND=2), COMPLEX(KIND=1), and CHARACTER. Further, many compilers offer so-called *n notation, but the interpretation of n varies across compilers and target architectures.

The standard requires that LOGICAL(KIND=1), INTEGER(KIND=1),
and REAL(KIND=1)
occupy the same amount of storage space, and that COMPLEX(KIND=1)
and REAL(KIND=2) take twice as much storage space as REAL(KIND=1).
Further, it requires that COMPLEX(KIND=1)
entities be ordered such that when a COMPLEX(KIND=1) variable is
storage-associated (such as via EQUIVALENCE)
with a two-element REAL(KIND=1) array named R, R(1)
corresponds to the real element and R(2) to the imaginary
element of the COMPLEX(KIND=1) variable.

(Few requirements as to precision or ranges of any of these are placed on the implementation, nor is the relationship of storage sizes of these types to the CHARACTER type specified, by the standard.)

g77 follows the above requirements, warning when compiling a program requires placement of items in memory that contradict the requirements of the target architecture. (For example, a program can require placement of a REAL(KIND=2) on a boundary that is not an even multiple of its size, but still an even multiple of the size of a REAL(KIND=1) variable. On some target architectures, using the canonical mapping of Fortran types to underlying architectural types, such placement is prohibited by the machine definition or the Application Binary Interface (ABI) in force for the configuration defined for building gcc and g77. g77 warns about such situations when it encounters them.)

g77 follows consistent rules for configuring the mapping between Fortran types, including the *n notation, and the underlying architectural types as accessed by a similarly-configured applicable version of the gcc compiler. These rules offer a widely portable, consistent Fortran/C environment, although they might well conflict with the expectations of users of Fortran compilers designed and written for particular architectures.

These rules are based on the configuration that is in force for the version of gcc built in the same release as g77 (and which was therefore used to build both the g77 compiler components and the libg2c run-time library):

REAL(KIND=1)
Same as float type.
REAL(KIND=2)
Same as whatever floating-point type that is twice the size of a float--usually, this is a double.
INTEGER(KIND=1)
Same as an integral type that is occupies the same amount of memory storage as float--usually, this is either an int or a long int.
LOGICAL(KIND=1)
Same gcc type as INTEGER(KIND=1).
INTEGER(KIND=2)
Twice the size, and usually nearly twice the range, as INTEGER(KIND=1)--usually, this is either a long int or a long long int.
LOGICAL(KIND=2)
Same gcc type as INTEGER(KIND=2).
INTEGER(KIND=3)
Same gcc type as signed char.
LOGICAL(KIND=3)
Same gcc type as INTEGER(KIND=3).
INTEGER(KIND=6)
Twice the size, and usually nearly twice the range, as INTEGER(KIND=3)--usually, this is a short.
LOGICAL(KIND=6)
Same gcc type as INTEGER(KIND=6).
COMPLEX(KIND=1)
Two REAL(KIND=1) scalars (one for the real part followed by one for the imaginary part).
COMPLEX(KIND=2)
Two REAL(KIND=2) scalars.
numeric-type*n
(Where numeric-type is any type other than CHARACTER.) Same as whatever gcc type occupies n times the storage space of a gcc char item.
DOUBLE PRECISION
Same as REAL(KIND=2).
DOUBLE COMPLEX
Same as COMPLEX(KIND=2).

Note that the above are proposed correspondences and might change in future versions of g77--avoid writing code depending on them.

Other types supported by g77 are derived from gcc types such as char, short, int, long int, long long int, long double, and so on. That is, whatever types gcc already supports, g77 supports now or probably will support in a future version. The rules for the numeric-type*n notation apply to these types, and new values for numeric-type(KIND=n) will be assigned in a way that encourages clarity, consistency, and portability.


Node:Compiler, Next:Other Dialects, Previous:Language, Up:Top

The GNU Fortran Compiler

The GNU Fortran compiler, g77, supports programs written in the GNU Fortran language and in some other dialects of Fortran.

Some aspects of how g77 works are universal regardless of dialect, and yet are not properly part of the GNU Fortran language itself. These are described below.

Note: This portion of the documentation definitely needs a lot of work!

  • Compiler Limits:
  • Run-time Environment Limits:
  • Compiler Types:
  • Compiler Constants:
  • Compiler Intrinsics:


Node:Complex Intrinsic, Next:Conjg Intrinsic, Previous:Cmplx Intrinsic, Up:Table of Intrinsic Functions

Complex Intrinsic

Complex(Real, Imag)

Complex: COMPLEX function, the exact type being the result of cross-promoting the types of all the arguments.

Real: INTEGER or REAL; scalar; INTENT(IN).

Imag: INTEGER or REAL; scalar; INTENT(IN).

Intrinsic groups: gnu.

Description:

Returns a COMPLEX value that has Real and Imag as its real and imaginary parts, respectively.

If Real and Imag are the same type, and that type is not INTEGER, no data conversion is performed, and the type of the resulting value has the same kind value as the types of Real and Imag.

If Real and Imag are not the same type, the usual type-promotion rules are applied to both, converting either or both to the appropriate REAL type. The type of the resulting value has the same kind value as the type to which both Real and Imag were converted, in this case.

If Real and Imag are both INTEGER, they are both converted to REAL(KIND=1), and the result of the COMPLEX() invocation is type COMPLEX(KIND=1).

Note: The way to do this in standard Fortran 90 is too hairy to describe here, but it is important to note that CMPLX(D1,D2) returns a COMPLEX(KIND=1) result even if D1 and D2 are type REAL(KIND=2). Hence the availability of COMPLEX() in GNU Fortran.


Node:Complex Variables, Next:Arrays, Previous:Local Equivalence Areas, Up:Debugging and Interfacing

Complex Variables (COMPLEX)

As of 0.5.20, g77 defaults to handling COMPLEX types (and related intrinsics, constants, functions, and so on) in a manner that makes direct debugging involving these types in Fortran language mode difficult.

Essentially, g77 implements these types using an internal construct similar to C's struct, at least as seen by the gcc back end.

Currently, the back end, when outputting debugging info with the compiled code for the assembler to digest, does not detect these struct types as being substitutes for Fortran complex. As a result, the Fortran language modes of debuggers such as gdb see these types as C struct types, which they might or might not support.

Until this is fixed, switch to C language mode to work with entities of COMPLEX type and then switch back to Fortran language mode afterward. (In gdb, this is accomplished via set lang c and either set lang fortran or set lang auto.)


Node:Conformance, Next:Notation Used, Previous:Standard Support, Up:Language

Conformance

(The following information augments or overrides the information in Section 1.4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 1 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

The definition of the GNU Fortran language is akin to that of the ANSI FORTRAN 77 language in that it does not generally require conforming implementations to diagnose cases where programs do not conform to the language.

However, g77 as a compiler is being developed in a way that is intended to enable it to diagnose such cases in an easy-to-understand manner.

A program that conforms to the GNU Fortran language should, when compiled, linked, and executed using a properly installed g77 system, perform as described by the GNU Fortran language definition. Reasons for different behavior include, among others:

  • Use of resources (memory--heap, stack, and so on; disk space; CPU time; etc.) exceeds those of the system.
  • Range and/or precision of calculations required by the program exceeds that of the system.
  • Excessive reliance on behaviors that are system-dependent (non-portable Fortran code).
  • Bugs in the program.
  • Bug in g77.
  • Bugs in the system.

Despite these "loopholes", the availability of a clear specification of the language of programs submitted to g77, as this document is intended to provide, is considered an important aspect of providing a robust, clean, predictable Fortran implementation.

The definition of the GNU Fortran language, while having no special legal status, can therefore be viewed as a sort of contract, or agreement. This agreement says, in essence, "if you write a program in this language, and run it in an environment (such as a g77 system) that supports this language, the program should behave in a largely predictable way".


Node:Conjg Intrinsic, Next:Cos Intrinsic, Previous:Complex Intrinsic, Up:Table of Intrinsic Functions

Conjg Intrinsic

Conjg(Z)

Conjg: COMPLEX function, the KIND= value of the type being that of argument Z.

Z: COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the complex conjugate:

COMPLEX(REALPART(Z), -IMAGPART(Z))


Node:Constants, Next:Integer Type, Previous:Types, Up:Data Types and Constants

Constants

(Corresponds to Section 4.2 of ANSI X3.9-1978 FORTRAN 77.)

A typeless constant has one of the following forms:

'binary-digits'B
'octal-digits'O
'hexadecimal-digits'Z
'hexadecimal-digits'X

binary-digits, octal-digits, and hexadecimal-digits are nonempty strings of characters in the set 01, 01234567, and 0123456789ABCDEFabcdef, respectively. (The value for A (and a) is 10, for B and b is 11, and so on.)

A prefix-radix constant, such as Z'ABCD', can optionally be treated as typeless. See Options Controlling Fortran Dialect, for information on the -ftypeless-boz option.

Typeless constants have values that depend on the context in which they are used.

All other constants, called typed constants, are interpreted--converted to internal form--according to their inherent type. Thus, context is never a determining factor for the type, and hence the interpretation, of a typed constant. (All constants in the ANSI FORTRAN 77 language are typed constants.)

For example, 1 is always type INTEGER(KIND=1) in GNU Fortran (called default INTEGER in Fortran 90), 9.435784839284958 is always type REAL(KIND=1) (even if the additional precision specified is lost, and even when used in a REAL(KIND=2) context), 1E0 is always type REAL(KIND=2), and 1D0 is always type REAL(KIND=2).


Node:Construct Names, Next:CYCLE and EXIT, Previous:END DO, Up:Control Statements

Construct Names

The GNU Fortran language supports construct names as defined by the Fortran 90 standard. These names are local to the program unit and are defined as follows:

construct-name: block-statement

Here, construct-name is the construct name itself; its definition is connoted by the single colon (:); and block-statement is an IF, DO, or SELECT CASE statement that begins a block.

A block that is given a construct name must also specify the same construct name in its termination statement:

END block construct-name

Here, block must be IF, DO, or SELECT, as appropriate.


Node:Context-Sensitive Intrinsicness, Next:Context-Sensitive Constants, Previous:Initializing Before Specifying, Up:Non-bugs

Context-Sensitive Intrinsicness

g77 treats procedure references to possible intrinsic names as always enabling their intrinsic nature, regardless of whether the form of the reference is valid for that intrinsic.

For example, CALL SQRT is interpreted by g77 as an invalid reference to the SQRT intrinsic function, because the reference is a subroutine invocation.

First, g77 recognizes the statement CALL SQRT as a reference to a procedure named SQRT, not to a variable with that name (as it would for a statement such as V = SQRT).

Next, g77 establishes that, in the program unit being compiled, SQRT is an intrinsic--not a subroutine that happens to have the same name as an intrinsic (as would be the case if, for example, EXTERNAL SQRT was present).

Finally, g77 recognizes that the form of the reference is invalid for that particular intrinsic. That is, it recognizes that it is invalid for an intrinsic function, such as SQRT, to be invoked as a subroutine.

At that point, g77 issues a diagnostic.

Some users claim that it is "obvious" that CALL SQRT references an external subroutine of their own, not an intrinsic function.

However, g77 knows about intrinsic subroutines, not just functions, and is able to support both having the same names, for example.

As a result of this, g77 rejects calls to intrinsics that are not subroutines, and function invocations of intrinsics that are not functions, just as it (and most compilers) rejects invocations of intrinsics with the wrong number (or types) of arguments.

So, use the EXTERNAL SQRT statement in a program unit that calls a user-written subroutine named SQRT.


Node:Continuation Line, Next:Statements, Previous:Lines, Up:Characters Lines Sequence

Continuation Line

(Corresponds to Section 3.2.3 of ANSI X3.9-1978 FORTRAN 77.)

A continuation line is any line that both

  • Contains a continuation character, and
  • Contains only spaces in columns 1 through 5

A continuation character is any character of the GNU Fortran character set other than space (<SPC>) or zero (0) in column 6, or a digit (0 through 9) in column 7 through 72 of a line that has only spaces to the left of that digit.

The continuation character is ignored as far as the content of the statement is concerned.

The GNU Fortran language places no limit on the number of continuation lines in a statement. In practice, the limit depends on a variety of factors, such as available memory, statement content, and so on, but no GNU Fortran system may impose an arbitrary limit.


Node:Contributors, Next:Funding, Previous:GNU Free Documentation License, Up:Top

Contributors to GNU Fortran

In addition to James Craig Burley, who wrote the front end, many people have helped create and improve GNU Fortran.

  • The packaging and compiler portions of GNU Fortran are based largely on the GNU CC compiler. See Contributors to GCC, for more information.
  • The run-time library used by GNU Fortran is a repackaged version of the libf2c library (combined from the libF77 and libI77 libraries) provided as part of f2c, available for free from netlib sites on the Internet.
  • Cygnus Support and The Free Software Foundation contributed significant money and/or equipment to Craig's efforts.
  • The following individuals served as alpha testers prior to g77's public release. This work consisted of testing, researching, sometimes debugging, and occasionally providing small amounts of code and fixes for g77, plus offering plenty of helpful advice to Craig:
    • Jonathan Corbet
    • Dr. Mark Fernyhough
    • Takafumi Hayashi (The University of Aizu)--takafumi@u-aizu.ac.jp
    • Kate Hedstrom
    • Michel Kern (INRIA and Rice University)--Michel.Kern@inria.fr
    • Dr. A. O. V. Le Blanc
    • Dave Love
    • Rick Lutowski
    • Toon Moene
    • Rick Niles
    • Derk Reefman
    • Wayne K. Schroll
    • Bill Thorson
    • Pedro A. M. Vazquez
    • Ian Watson
  • Dave Love (d.love@dl.ac.uk) wrote the libU77 part of the run-time library.
  • Scott Snyder (snyder@d0sgif.fnal.gov) provided the patch to add rudimentary support for INTEGER*1, INTEGER*2, and LOGICAL*1. This inspired Craig to add further support, even though the resulting support would still be incomplete.
  • David Ronis (ronis@onsager.chem.mcgill.ca) inspired and encouraged Craig to rewrite the documentation in texinfo format by contributing a first pass at a translation of the old g77-0.5.16/f/DOC file.
  • Toon Moene (toon@moene.indiv.nluug.nl) performed some analysis of generated code as part of an overall project to improve g77 code generation to at least be as good as f2c used in conjunction with gcc. So far, this has resulted in the three, somewhat experimental, options added by g77 to the gcc compiler and its back end.

    (These, in turn, had made their way into the egcs version of the compiler, and do not exist in gcc version 2.8 or versions of g77 based on that version of gcc.)

  • John Carr (jfc@mit.edu) wrote the alias analysis improvements.
  • Thanks to Mary Cortani and the staff at Craftwork Solutions (support@craftwork.com) for all of their support.
  • Many other individuals have helped debug, test, and improve g77 over the past several years, and undoubtedly more people will be doing so in the future. If you have done so, and would like to see your name listed in the above list, please ask! The default is that people wish to remain anonymous.


Node:Control Statements, Next:Functions and Subroutines, Previous:Specification Statements, Up:Language

Control Statements

(The following information augments or overrides the information in Chapter 11 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 11 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

  • DO WHILE:
  • END DO:
  • Construct Names:
  • CYCLE and EXIT:


Node:Copying, Next:GNU Free Documentation License, Previous:Top, Up:Top

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
    NO WARRANTY
  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) year  name of author

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.


Node:Cos Intrinsic, Next:CosH Intrinsic, Previous:Conjg Intrinsic, Up:Table of Intrinsic Functions

Cos Intrinsic

Cos(X)

Cos: REAL or COMPLEX function, the exact type being that of argument X.

X: REAL or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the cosine of X, an angle measured in radians.

See ACos Intrinsic, for the inverse of this function.


Node:CosD Intrinsic, Next:DACosD Intrinsic, Previous:ChMod Intrinsic (function), Up:Other Intrinsics

CosD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL CosD to use this name for an external procedure.


Node:CosH Intrinsic, Next:Count Intrinsic, Previous:Cos Intrinsic, Up:Table of Intrinsic Functions

CosH Intrinsic

CosH(X)

CosH: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the hyperbolic cosine of X.


Node:Count Intrinsic, Next:CPU_Time Intrinsic, Previous:CosH Intrinsic, Up:Table of Intrinsic Functions

Count Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Count to use this name for an external procedure.


Node:Cpp-style directives, Previous:INCLUDE, Up:Characters Lines Sequence

Cpp-style directives

cpp output-style # directives (see C Preprocessor Output) are recognized by the compiler even when the preprocessor isn't run on the input (as it is when compiling .F files). (Note the distinction between these cpp # output directives and #line input directives.)


Node:CPU_Time Intrinsic, Next:CShift Intrinsic, Previous:Count Intrinsic, Up:Table of Intrinsic Functions

CPU_Time Intrinsic

CALL CPU_Time(Seconds)

Seconds: REAL; scalar; INTENT(OUT).

Intrinsic groups: f90.

Description:

Returns in Seconds the current value of the system time. This implementation of the Fortran 95 intrinsic is just an alias for second See Second Intrinsic (subroutine).

On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wraparounds) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.


Node:CShift Intrinsic, Next:CSin Intrinsic, Previous:CPU_Time Intrinsic, Up:Table of Intrinsic Functions

CShift Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL CShift to use this name for an external procedure.


Node:CSin Intrinsic, Next:CSqRt Intrinsic, Previous:CShift Intrinsic, Up:Table of Intrinsic Functions

CSin Intrinsic

CSin(X)

CSin: COMPLEX(KIND=1) function.

X: COMPLEX(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of SIN() that is specific to one type for X. See Sin Intrinsic.


Node:CSqRt Intrinsic, Next:CTime Intrinsic (subroutine), Previous:CSin Intrinsic, Up:Table of Intrinsic Functions

CSqRt Intrinsic

CSqRt(X)

CSqRt: COMPLEX(KIND=1) function.

X: COMPLEX(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of SQRT() that is specific to one type for X. See SqRt Intrinsic.


Node:CTime Intrinsic (function), Next:DAbs Intrinsic, Previous:CTime Intrinsic (subroutine), Up:Table of Intrinsic Functions

CTime Intrinsic (function)

CTime(STime)

CTime: CHARACTER*(*) function.

STime: INTEGER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Converts STime, a system time value, such as returned by TIME8(), to a string of the form Sat Aug 19 18:13:14 1995, and returns that string as the function value.

See Time8 Intrinsic.

For information on other intrinsics with the same name: See CTime Intrinsic (subroutine).


Node:CTime Intrinsic (subroutine), Next:CTime Intrinsic (function), Previous:CSqRt Intrinsic, Up:Table of Intrinsic Functions

CTime Intrinsic (subroutine)

CALL CTime(STime, Result)

STime: INTEGER; scalar; INTENT(IN).

Result: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Converts STime, a system time value, such as returned by TIME8(), to a string of the form Sat Aug 19 18:13:14 1995, and returns that string in Result.

See Time8 Intrinsic.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine.

For information on other intrinsics with the same name: See CTime Intrinsic (function).


Node:DAbs Intrinsic, Next:DACos Intrinsic, Previous:CTime Intrinsic (function), Up:Table of Intrinsic Functions

DAbs Intrinsic

DAbs(A)

DAbs: REAL(KIND=2) function.

A: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of ABS() that is specific to one type for A. See Abs Intrinsic.


Node:DACos Intrinsic, Next:DASin Intrinsic, Previous:DAbs Intrinsic, Up:Table of Intrinsic Functions

DACos Intrinsic

DACos(X)

DACos: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of ACOS() that is specific to one type for X. See ACos Intrinsic.


Node:DACosD Intrinsic, Next:DASinD Intrinsic, Previous:CosD Intrinsic, Up:Other Intrinsics

DACosD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DACosD to use this name for an external procedure.


Node:DASin Intrinsic, Next:DATan Intrinsic, Previous:DACos Intrinsic, Up:Table of Intrinsic Functions

DASin Intrinsic

DASin(X)

DASin: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of ASIN() that is specific to one type for X. See ASin Intrinsic.


Node:DASinD Intrinsic, Next:DATan2D Intrinsic, Previous:DACosD Intrinsic, Up:Other Intrinsics

DASinD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DASinD to use this name for an external procedure.


Node:Data Types and Constants, Next:Expressions, Previous:Characters Lines Sequence, Up:Language

Data Types and Constants

(The following information augments or overrides the information in Chapter 4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 4 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

To more concisely express the appropriate types for entities, this document uses the more concise Fortran 90 nomenclature such as INTEGER(KIND=1) instead of the more traditional, but less portably concise, byte-size-based nomenclature such as INTEGER*4, wherever reasonable.

When referring to generic types--in contexts where the specific precision and range of a type are not important--this document uses the generic type names INTEGER, LOGICAL, REAL, COMPLEX, and CHARACTER.

In some cases, the context requires specification of a particular type. This document uses the KIND= notation to accomplish this throughout, sometimes supplying the more traditional notation for clarification, though the traditional notation might not work the same way on all GNU Fortran implementations.

Use of KIND= makes this document more concise because g77 is able to define values for KIND= that have the same meanings on all systems, due to the way the Fortran 90 standard specifies these values are to be used.

(In particular, that standard permits an implementation to arbitrarily assign nonnegative values. There are four distinct sets of assignments: one to the CHARACTER type; one to the INTEGER type; one to the LOGICAL type; and the fourth to both the REAL and COMPLEX types. Implementations are free to assign these values in any order, leave gaps in the ordering of assignments, and assign more than one value to a representation.)

This makes KIND= values superior to the values used in non-standard statements such as INTEGER*4, because the meanings of the values in those statements vary from machine to machine, compiler to compiler, even operating system to operating system.

However, use of KIND= is not generally recommended when writing portable code (unless, for example, the code is going to be compiled only via g77, which is a widely ported compiler). GNU Fortran does not yet have adequate language constructs to permit use of KIND= in a fashion that would make the code portable to Fortran 90 implementations; and, this construct is known to not be accepted by many popular FORTRAN 77 implementations, so it cannot be used in code that is to be ported to those.

The distinction here is that this document is able to use specific values for KIND= to concisely document the types of various operations and operands.

A Fortran program should use the FORTRAN 77 designations for the appropriate GNU Fortran types--such as INTEGER for INTEGER(KIND=1), REAL for REAL(KIND=1), and DOUBLE COMPLEX for COMPLEX(KIND=2)--and, where no such designations exist, make use of appropriate techniques (preprocessor macros, parameters, and so on) to specify the types in a fashion that may be easily adjusted to suit each particular implementation to which the program is ported. (These types generally won't need to be adjusted for ports of g77.)

Further details regarding GNU Fortran data types and constants are provided below.

  • Types:
  • Constants:
  • Integer Type:
  • Character Type:


Node:DATan Intrinsic, Next:DATan2 Intrinsic, Previous:DASin Intrinsic, Up:Table of Intrinsic Functions

DATan Intrinsic

DATan(X)

DATan: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of ATAN() that is specific to one type for X. See ATan Intrinsic.


Node:DATan2 Intrinsic, Next:Date_and_Time Intrinsic, Previous:DATan Intrinsic, Up:Table of Intrinsic Functions

DATan2 Intrinsic

DATan2(Y, X)

DATan2: REAL(KIND=2) function.

Y: REAL(KIND=2); scalar; INTENT(IN).

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of ATAN2() that is specific to one type for Y and X. See ATan2 Intrinsic.


Node:DATan2D Intrinsic, Next:DATanD Intrinsic, Previous:DASinD Intrinsic, Up:Other Intrinsics

DATan2D Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DATan2D to use this name for an external procedure.


Node:DATanD Intrinsic, Next:Date Intrinsic, Previous:DATan2D Intrinsic, Up:Other Intrinsics

DATanD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DATanD to use this name for an external procedure.


Node:Date Intrinsic, Next:DbleQ Intrinsic, Previous:DATanD Intrinsic, Up:Other Intrinsics

Date Intrinsic

CALL Date(Date)

Date: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: vxt.

Description:

Returns Date in the form dd-mmm-yy, representing the numeric day of the month dd, a three-character abbreviation of the month name mmm and the last two digits of the year yy, e.g. 25-Nov-96.

This intrinsic is not recommended, due to the year 2000 approaching. Therefore, programs making use of this intrinsic might not be Year 2000 (Y2K) compliant. See CTime Intrinsic (subroutine), for information on obtaining more digits for the current (or any) date.


Node:Date_and_Time Intrinsic, Next:DbesJ0 Intrinsic, Previous:DATan2 Intrinsic, Up:Table of Intrinsic Functions

Date_and_Time Intrinsic

CALL Date_and_Time(Date, Time, Zone, Values)

Date: CHARACTER; scalar; INTENT(OUT).

Time: CHARACTER; OPTIONAL; scalar; INTENT(OUT).

Zone: CHARACTER; OPTIONAL; scalar; INTENT(OUT).

Values: INTEGER(KIND=1); OPTIONAL; DIMENSION(8); INTENT(OUT).

Intrinsic groups: f90.

Description:

Returns:

Date
The date in the form ccyymmdd: century, year, month and day;
Time
The time in the form hhmmss.ss: hours, minutes, seconds and milliseconds;
Zone
The difference between local time and UTC (GMT) in the form Shhmm: sign, hours and minutes, e.g. -0500 (winter in New York);
Values
The year, month of the year, day of the month, time difference in minutes from UTC, hour of the day, minutes of the hour, seconds of the minute, and milliseconds of the second in successive values of the array.

Programs making use of this intrinsic might not be Year 10000 (Y10K) compliant. For example, the date might appear, to such programs, to wrap around (change from a larger value to a smaller one) as of the Year 10000.

On systems where a millisecond timer isn't available, the millisecond value is returned as zero.


Node:DbesJ0 Intrinsic, Next:DbesJ1 Intrinsic, Previous:Date_and_Time Intrinsic, Up:Table of Intrinsic Functions

DbesJ0 Intrinsic

DbesJ0(X)

DbesJ0: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of BESJ0() that is specific to one type for X. See BesJ0 Intrinsic.


Node:DbesJ1 Intrinsic, Next:DbesJN Intrinsic, Previous:DbesJ0 Intrinsic, Up:Table of Intrinsic Functions

DbesJ1 Intrinsic

DbesJ1(X)

DbesJ1: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of BESJ1() that is specific to one type for X. See BesJ1 Intrinsic.


Node:DbesJN Intrinsic, Next:DbesY0 Intrinsic, Previous:DbesJ1 Intrinsic, Up:Table of Intrinsic Functions

DbesJN Intrinsic

DbesJN(N, X)

DbesJN: REAL(KIND=2) function.

N: INTEGER not wider than the default kind; scalar; INTENT(IN).

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of BESJN() that is specific to one type for X. See BesJN Intrinsic.


Node:DbesY0 Intrinsic, Next:DbesY1 Intrinsic, Previous:DbesJN Intrinsic, Up:Table of Intrinsic Functions

DbesY0 Intrinsic

DbesY0(X)

DbesY0: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of BESY0() that is specific to one type for X. See BesY0 Intrinsic.


Node:DbesY1 Intrinsic, Next:DbesYN Intrinsic, Previous:DbesY0 Intrinsic, Up:Table of Intrinsic Functions

DbesY1 Intrinsic

DbesY1(X)

DbesY1: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of BESY1() that is specific to one type for X. See BesY1 Intrinsic.


Node:DbesYN Intrinsic, Next:Dble Intrinsic, Previous:DbesY1 Intrinsic, Up:Table of Intrinsic Functions

DbesYN Intrinsic

DbesYN(N, X)

DbesYN: REAL(KIND=2) function.

N: INTEGER not wider than the default kind; scalar; INTENT(IN).

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of BESYN() that is specific to one type for X. See BesYN Intrinsic.


Node:Dble Intrinsic, Next:DCos Intrinsic, Previous:DbesYN Intrinsic, Up:Table of Intrinsic Functions

Dble Intrinsic

Dble(A)

Dble: REAL(KIND=2) function.

A: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns A converted to double precision (REAL(KIND=2)). If A is COMPLEX, the real part of A is used for the conversion and the imaginary part disregarded.

See Sngl Intrinsic, for the function that converts to single precision.

See Int Intrinsic, for the function that converts to INTEGER.

See Complex Intrinsic, for the function that converts to COMPLEX.


Node:DbleQ Intrinsic, Next:DCmplx Intrinsic, Previous:Date Intrinsic, Up:Other Intrinsics

DbleQ Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DbleQ to use this name for an external procedure.


Node:DCmplx Intrinsic, Next:DConjg Intrinsic, Previous:DbleQ Intrinsic, Up:Other Intrinsics

DCmplx Intrinsic

DCmplx(X, Y)

DCmplx: COMPLEX(KIND=2) function.

X: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Y: INTEGER or REAL; OPTIONAL (must be omitted if X is COMPLEX); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

If X is not type COMPLEX, constructs a value of type COMPLEX(KIND=2) from the real and imaginary values specified by X and Y, respectively. If Y is omitted, 0D0 is assumed.

If X is type COMPLEX, converts it to type COMPLEX(KIND=2).

Although this intrinsic is not standard Fortran, it is a popular extension offered by many compilers that support DOUBLE COMPLEX, since it offers the easiest way to convert to DOUBLE COMPLEX without using Fortran 90 features (such as the KIND= argument to the CMPLX() intrinsic).

(CMPLX(0D0, 0D0) returns a single-precision COMPLEX result, as required by standard FORTRAN 77. That's why so many compilers provide DCMPLX(), since DCMPLX(0D0, 0D0) returns a DOUBLE COMPLEX result. Still, DCMPLX() converts even REAL*16 arguments to their REAL*8 equivalents in most dialects of Fortran, so neither it nor CMPLX() allow easy construction of arbitrary-precision values without potentially forcing a conversion involving extending or reducing precision. GNU Fortran provides such an intrinsic, called COMPLEX().)

See Complex Intrinsic, for information on easily constructing a COMPLEX value of arbitrary precision from REAL arguments.


Node:DConjg Intrinsic, Next:DCosD Intrinsic, Previous:DCmplx Intrinsic, Up:Other Intrinsics

DConjg Intrinsic

DConjg(Z)

DConjg: COMPLEX(KIND=2) function.

Z: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of CONJG() that is specific to one type for Z. See Conjg Intrinsic.


Node:DCos Intrinsic, Next:DCosH Intrinsic, Previous:Dble Intrinsic, Up:Table of Intrinsic Functions

DCos Intrinsic

DCos(X)

DCos: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of COS() that is specific to one type for X. See Cos Intrinsic.


Node:DCosD Intrinsic, Next:DFloat Intrinsic, Previous:DConjg Intrinsic, Up:Other Intrinsics

DCosD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DCosD to use this name for an external procedure.


Node:DCosH Intrinsic, Next:DDiM Intrinsic, Previous:DCos Intrinsic, Up:Table of Intrinsic Functions

DCosH Intrinsic

DCosH(X)

DCosH: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of COSH() that is specific to one type for X. See CosH Intrinsic.


Node:DDiM Intrinsic, Next:DErF Intrinsic, Previous:DCosH Intrinsic, Up:Table of Intrinsic Functions

DDiM Intrinsic

DDiM(X, Y)

DDiM: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Y: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of DIM() that is specific to one type for X and Y. See DiM Intrinsic.


Node:Debug Line, Next:Dollar Signs, Previous:Trailing Comment, Up:Other Dialects

Debug Line

Use of D or d as the first character (column 1) of a source line denotes a debug line.

In turn, a debug line is treated as either a comment line or a normal line, depending on whether debug lines are enabled.

When treated as a comment line, a line beginning with D or d is treated as if it the first character was C or c, respectively. When treated as a normal line, such a line is treated as if the first character was <SPC> (space).

(Currently, g77 provides no means for treating debug lines as normal lines.)


Node:Debugger Problems, Next:NeXTStep Problems, Previous:Large Common Blocks, Up:But-bugs

Debugger Problems

There are some known problems when using gdb on code compiled by g77. Inadequate investigation as of the release of 0.5.16 results in not knowing which products are the culprit, but gdb-4.14 definitely crashes when, for example, an attempt is made to print the contents of a COMPLEX(KIND=2) dummy array, on at least some GNU/Linux machines, plus some others. Attempts to access assumed-size arrays are also known to crash recent versions of gdb. (gdb's Fortran support was done for a different compiler and isn't properly compatible with g77.)


Node:Debugging and Interfacing, Next:Collected Fortran Wisdom, Previous:Other Languages, Up:Top

Debugging and Interfacing

GNU Fortran currently generates code that is object-compatible with the f2c converter. Also, it avoids limitations in the current GBE, such as the inability to generate a procedure with multiple entry points, by generating code that is structured differently (in terms of procedure names, scopes, arguments, and so on) than might be expected.

As a result, writing code in other languages that calls on, is called by, or shares in-memory data with g77-compiled code generally requires some understanding of the way g77 compiles code for various constructs.

Similarly, using a debugger to debug g77-compiled code, even if that debugger supports native Fortran debugging, generally requires this sort of information.

This section describes some of the basic information on how g77 compiles code for constructs involving interfaces to other languages and to debuggers.

Caution: Much or all of this information pertains to only the current release of g77, sometimes even to using certain compiler options with g77 (such as -fno-f2c). Do not write code that depends on this information without clearly marking said code as nonportable and subject to review for every new release of g77. This information is provided primarily to make debugging of code generated by this particular release of g77 easier for the user, and partly to make writing (generally nonportable) interface code easier. Both of these activities require tracking changes in new version of g77 as they are installed, because new versions can change the behaviors described in this section.

  • Main Program Unit: How g77 compiles a main program unit.
  • Procedures: How g77 constructs parameter lists for procedures.
  • Functions: Functions returning floating-point or character data.
  • Names: Naming of user-defined variables, procedures, etc.
  • Common Blocks: Accessing common variables while debugging.
  • Local Equivalence Areas: Accessing EQUIVALENCE while debugging.
  • Complex Variables: How g77 performs complex arithmetic.
  • Arrays: Dealing with (possibly multi-dimensional) arrays.
  • Adjustable Arrays: Special consideration for adjustable arrays.
  • Alternate Entry Points: How g77 implements alternate ENTRY.
  • Alternate Returns: How g77 handles alternate returns.
  • Assigned Statement Labels: How g77 handles ASSIGN.
  • Run-time Library Errors: Meanings of some IOSTAT= values.


Node:Debugging Options, Next:Optimize Options, Previous:Warning Options, Up:Invoking G77

Options for Debugging Your Program or GNU Fortran

GNU Fortran has various special options that are used for debugging either your program or g77

-g
Produce debugging information in the operating system's native format (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging information.

A sample debugging session looks like this (note the use of the breakpoint):

$ cat gdb.f
      PROGRAM PROG
      DIMENSION A(10)
      DATA A /1.,2.,3.,4.,5.,6.,7.,8.,9.,10./
      A(5) = 4.
      PRINT*,A
      END
$ g77 -g -O gdb.f
$ gdb a.out
...
(gdb) break MAIN__
Breakpoint 1 at 0x8048e96: file gdb.f, line 4.
(gdb) run
Starting program: /home/toon/g77-bugs/./a.out
Breakpoint 1, MAIN__ () at gdb.f:4
4             A(5) = 4.
Current language:  auto; currently fortran
(gdb) print a(5)
$1 = 5
(gdb) step
5             PRINT*,A
(gdb) print a(5)
$2 = 4
...
One could also add the setting of the breakpoint and the first run command to the file .gdbinit in the current directory, to simplify the debugging session.

See Options for Debugging Your Program or GCC, for more information on debugging options.


Node:DErF Intrinsic, Next:DErFC Intrinsic, Previous:DDiM Intrinsic, Up:Table of Intrinsic Functions

DErF Intrinsic

DErF(X)

DErF: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of ERF() that is specific to one type for X. See ErF Intrinsic.


Node:DErFC Intrinsic, Next:DExp Intrinsic, Previous:DErF Intrinsic, Up:Table of Intrinsic Functions

DErFC Intrinsic

DErFC(X)

DErFC: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of ERFC() that is specific to one type for X. See ErFC Intrinsic.


Node:DExp Intrinsic, Next:Digits Intrinsic, Previous:DErFC Intrinsic, Up:Table of Intrinsic Functions

DExp Intrinsic

DExp(X)

DExp: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of EXP() that is specific to one type for X. See Exp Intrinsic.


Node:DFloat Intrinsic, Next:DFlotI Intrinsic, Previous:DCosD Intrinsic, Up:Other Intrinsics

DFloat Intrinsic

DFloat(A)

DFloat: REAL(KIND=2) function.

A: INTEGER; scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of REAL() that is specific to one type for A. See Real Intrinsic.


Node:DFlotI Intrinsic, Next:DFlotJ Intrinsic, Previous:DFloat Intrinsic, Up:Other Intrinsics

DFlotI Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DFlotI to use this name for an external procedure.


Node:DFlotJ Intrinsic, Next:DImag Intrinsic, Previous:DFlotI Intrinsic, Up:Other Intrinsics

DFlotJ Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DFlotJ to use this name for an external procedure.


Node:Diagnostic Abilities, Next:Compiler Options, Previous:Language Extensions, Up:Advantages Over f2c

Diagnostic Abilities

g77 offers better diagnosis of problems in FORMAT statements. f2c doesn't, for example, emit any diagnostic for FORMAT(XZFAJG10324), leaving that to be diagnosed, at run time, by the libf2c run-time library.


Node:Diagnostics, Next:Index, Previous:Front End, Up:Top

Diagnostics

Some diagnostics produced by g77 require sufficient explanation that the explanations are given below, and the diagnostics themselves identify the appropriate explanation.

Identification uses the GNU Info format--specifically, the info command that displays the explanation is given within square brackets in the diagnostic. For example:

foo.f:5: Invalid statement [info -f g77 M FOOEY]

More details about the above diagnostic is found in the g77 Info documentation, menu item M, submenu item FOOEY, which is displayed by typing the UNIX command info -f g77 M FOOEY.

Other Info readers, such as EMACS, may be just as easily used to display the pertinent node. In the above example, g77 is the Info document name, M is the top-level menu item to select, and, in that node (named Diagnostics, the name of this chapter, which is the very text you're reading now), FOOEY is the menu item to select.

  • CMPAMBIG: Ambiguous use of intrinsic.
  • EXPIMP: Intrinsic used explicitly and implicitly.
  • INTGLOB: Intrinsic also used as name of global.
  • LEX: Various lexer messages
  • GLOBALS: Disagreements about globals.
  • LINKFAIL: When linking f771 fails.
  • Y2KBAD: Use of non-Y2K-compliant intrinsic.


Node:Digits Intrinsic, Next:DiM Intrinsic, Previous:DExp Intrinsic, Up:Table of Intrinsic Functions

Digits Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Digits to use this name for an external procedure.


Node:DiM Intrinsic, Next:DInt Intrinsic, Previous:Digits Intrinsic, Up:Table of Intrinsic Functions

DiM Intrinsic

DiM(X, Y)

DiM: INTEGER or REAL function, the exact type being the result of cross-promoting the types of all the arguments.

X: INTEGER or REAL; scalar; INTENT(IN).

Y: INTEGER or REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns X-Y if X is greater than Y; otherwise returns zero.


Node:DImag Intrinsic, Next:DReal Intrinsic, Previous:DFlotJ Intrinsic, Up:Other Intrinsics

DImag Intrinsic

DImag(Z)

DImag: REAL(KIND=2) function.

Z: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c, vxt.

Description:

Archaic form of AIMAG() that is specific to one type for Z. See AImag Intrinsic.


Node:DInt Intrinsic, Next:DLog Intrinsic, Previous:DiM Intrinsic, Up:Table of Intrinsic Functions

DInt Intrinsic

DInt(A)

DInt: REAL(KIND=2) function.

A: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of AINT() that is specific to one type for A. See AInt Intrinsic.


Node:Direction of Language Development, Next:Standard Support, Up:Language

Direction of Language Development

The purpose of the following description of the GNU Fortran language is to promote wide portability of GNU Fortran programs.

GNU Fortran is an evolving language, due to the fact that g77 itself is in beta test. Some current features of the language might later be redefined as dialects of Fortran supported by g77 when better ways to express these features are added to g77, for example. Such features would still be supported by g77, but would be available only when one or more command-line options were used.

The GNU Fortran language is distinct from the GNU Fortran compilation system (g77).

For example, g77 supports various dialects of Fortran--in a sense, these are languages other than GNU Fortran--though its primary purpose is to support the GNU Fortran language, which also is described in its documentation and by its implementation.

On the other hand, non-GNU compilers might offer support for the GNU Fortran language, and are encouraged to do so.

Currently, the GNU Fortran language is a fairly fuzzy object. It represents something of a cross between what g77 accepts when compiling using the prevailing defaults and what this document describes as being part of the language.

Future versions of g77 are expected to clarify the definition of the language in the documentation. Often, this will mean adding new features to the language, in the form of both new documentation and new support in g77. However, it might occasionally mean removing a feature from the language itself to "dialect" status. In such a case, the documentation would be adjusted to reflect the change, and g77 itself would likely be changed to require one or more command-line options to continue supporting the feature.

The development of the GNU Fortran language is intended to strike a balance between:

  • Serving as a mostly-upwards-compatible language from the de facto UNIX Fortran dialect as supported by f77.
  • Offering new, well-designed language features. Attributes of such features include not making existing code any harder to read (for those who might be unaware that the new features are not in use) and not making state-of-the-art compilers take longer to issue diagnostics, among others.
  • Supporting existing, well-written code without gratuitously rejecting non-standard constructs, regardless of the origin of the code (its dialect).
  • Offering default behavior and command-line options to reduce and, where reasonable, eliminate the need for programmers to make any modifications to code that already works in existing production environments.
  • Diagnosing constructs that have different meanings in different systems, languages, and dialects, while offering clear, less ambiguous ways to express each of the different meanings so programmers can change their code appropriately.

One of the biggest practical challenges for the developers of the GNU Fortran language is meeting the sometimes contradictory demands of the above items.

For example, a feature might be widely used in one popular environment, but the exact same code that utilizes that feature might not work as expected--perhaps it might mean something entirely different--in another popular environment.

Traditionally, Fortran compilers--even portable ones--have solved this problem by simply offering the appropriate feature to users of the respective systems. This approach treats users of various Fortran systems and dialects as remote "islands", or camps, of programmers, and assume that these camps rarely come into contact with each other (or, especially, with each other's code).

Project GNU takes a radically different approach to software and language design, in that it assumes that users of GNU software do not necessarily care what kind of underlying system they are using, regardless of whether they are using software (at the user-interface level) or writing it (for example, writing Fortran or C code).

As such, GNU users rarely need consider just what kind of underlying hardware (or, in many cases, operating system) they are using at any particular time. They can use and write software designed for a general-purpose, widely portable, heterogenous environment--the GNU environment.

In line with this philosophy, GNU Fortran must evolve into a product that is widely ported and portable not only in the sense that it can be successfully built, installed, and run by users, but in the larger sense that its users can use it in the same way, and expect largely the same behaviors from it, regardless of the kind of system they are using at any particular time.

This approach constrains the solutions g77 can use to resolve conflicts between various camps of Fortran users. If these two camps disagree about what a particular construct should mean, g77 cannot simply be changed to treat that particular construct as having one meaning without comment (such as a warning), lest the users expecting it to have the other meaning are unpleasantly surprised that their code misbehaves when executed.

The use of the ASCII backslash character in character constants is an excellent (and still somewhat unresolved) example of this kind of controversy. See Backslash in Constants. Other examples are likely to arise in the future, as g77 developers strive to improve its ability to accept an ever-wider variety of existing Fortran code without requiring significant modifications to said code.

Development of GNU Fortran is further constrained by the desire to avoid requiring programmers to change their code. This is important because it allows programmers, administrators, and others to more faithfully evaluate and validate g77 (as an overall product and as new versions are distributed) without having to support multiple versions of their programs so that they continue to work the same way on their existing systems (non-GNU perhaps, but possibly also earlier versions of g77).


Node:Directory Options, Next:Code Gen Options, Previous:Preprocessor Options, Up:Invoking G77

Options for Directory Search

These options affect how the cpp preprocessor searches for files specified via the #include directive. Therefore, when compiling Fortran programs, they are meaningful when the preprocessor is used.

Some of these options also affect how g77 searches for files specified via the INCLUDE directive, although files included by that directive are not, themselves, preprocessed. These options are:

-I-
-Idir
These affect interpretation of the INCLUDE directive (as well as of the #include directive of the cpp preprocessor).

Note that -Idir must be specified without any spaces between -I and the directory name--that is, -Ifoo/bar is valid, but -I foo/bar is rejected by the g77 compiler (though the preprocessor supports the latter form). Also note that the general behavior of -I and INCLUDE is pretty much the same as of -I with #include in the cpp preprocessor, with regard to looking for header.gcc files and other such things.

See Options for Directory Search, for information on the -I option.


Node:Disappointments, Next:Non-bugs, Previous:Missing Features, Up:Trouble

Disappointments and Misunderstandings

These problems are perhaps regrettable, but we don't know any practical way around them for now.

  • Mangling of Names: SUBROUTINE FOO is given external name foo_.
  • Multiple Definitions of External Names: No doing both COMMON /FOO/ and SUBROUTINE FOO.
  • Limitation on Implicit Declarations: No IMPLICIT CHARACTER*(*).


Node:Distensions, Previous:Pedantic Compilation, Up:Other Dialects

Distensions

The -fugly-* command-line options determine whether certain features supported by VAX FORTRAN and other such compilers, but considered too ugly to be in code that can be changed to use safer and/or more portable constructs, are accepted. These are humorously referred to as "distensions", extensions that just plain look ugly in the harsh light of day.

  • Ugly Implicit Argument Conversion: Disabled via -fno-ugly-args.
  • Ugly Assumed-Size Arrays: Enabled via -fugly-assumed.
  • Ugly Null Arguments: Enabled via -fugly-comma.
  • Ugly Complex Part Extraction: Enabled via -fugly-complex.
  • Ugly Conversion of Initializers: Disabled via -fno-ugly-init.
  • Ugly Integer Conversions: Enabled via -fugly-logint.
  • Ugly Assigned Labels: Enabled via -fugly-assign.


Node:DLog Intrinsic, Next:DLog10 Intrinsic, Previous:DInt Intrinsic, Up:Table of Intrinsic Functions

DLog Intrinsic

DLog(X)

DLog: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of LOG() that is specific to one type for X. See Log Intrinsic.


Node:DLog10 Intrinsic, Next:DMax1 Intrinsic, Previous:DLog Intrinsic, Up:Table of Intrinsic Functions

DLog10 Intrinsic

DLog10(X)

DLog10: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of LOG10() that is specific to one type for X. See Log10 Intrinsic.


Node:DMax1 Intrinsic, Next:DMin1 Intrinsic, Previous:DLog10 Intrinsic, Up:Table of Intrinsic Functions

DMax1 Intrinsic

DMax1(A-1, A-2, ..., A-n)

DMax1: REAL(KIND=2) function.

A: REAL(KIND=2); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MAX() that is specific to one type for A. See Max Intrinsic.


Node:DMin1 Intrinsic, Next:DMod Intrinsic, Previous:DMax1 Intrinsic, Up:Table of Intrinsic Functions

DMin1 Intrinsic

DMin1(A-1, A-2, ..., A-n)

DMin1: REAL(KIND=2) function.

A: REAL(KIND=2); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MIN() that is specific to one type for A. See Min Intrinsic.


Node:DMod Intrinsic, Next:DNInt Intrinsic, Previous:DMin1 Intrinsic, Up:Table of Intrinsic Functions

DMod Intrinsic

DMod(A, P)

DMod: REAL(KIND=2) function.

A: REAL(KIND=2); scalar; INTENT(IN).

P: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MOD() that is specific to one type for A. See Mod Intrinsic.


Node:DNInt Intrinsic, Next:Dot_Product Intrinsic, Previous:DMod Intrinsic, Up:Table of Intrinsic Functions

DNInt Intrinsic

DNInt(A)

DNInt: REAL(KIND=2) function.

A: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of ANINT() that is specific to one type for A. See ANInt Intrinsic.


Node:DO WHILE, Next:END DO, Up:Control Statements

DO WHILE

The DO WHILE statement, a feature of both the MIL-STD 1753 and Fortran 90 standards, is provided by the GNU Fortran language. The Fortran 90 "do forever" statement comprising just DO is also supported.


Node:Dollar Signs, Next:Case Sensitivity, Previous:Debug Line, Up:Other Dialects

Dollar Signs in Symbol Names

Dollar signs ($) are allowed in symbol names (after the first character) when the -fdollar-ok option is specified.


Node:Dot_Product Intrinsic, Next:DProd Intrinsic, Previous:DNInt Intrinsic, Up:Table of Intrinsic Functions

Dot_Product Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Dot_Product to use this name for an external procedure.


Node:DOUBLE COMPLEX, Previous:NAMELIST, Up:Specification Statements

DOUBLE COMPLEX Statement

DOUBLE COMPLEX is a type-statement (and type) that specifies the type COMPLEX(KIND=2) in GNU Fortran.


Node:Double Notation, Next:Star Notation, Up:Types

Double Notation

The GNU Fortran language supports two uses of the keyword DOUBLE to specify a specific kind of type:

  • DOUBLE PRECISION, equivalent to REAL(KIND=2)
  • DOUBLE COMPLEX, equivalent to COMPLEX(KIND=2)

Use one of the above forms where a type name is valid.

While use of this notation is popular, it doesn't scale well in a language or dialect rich in intrinsic types, as is the case for the GNU Fortran language (especially planned future versions of it).

After all, one rarely sees type names such as DOUBLE INTEGER, QUADRUPLE REAL, or QUARTER INTEGER. Instead, INTEGER*8, REAL*16, and INTEGER*1 often are substituted for these, respectively, even though they do not always have the same meanings on all systems. (And, the fact that DOUBLE REAL does not exist as such is an inconsistency.)

Therefore, this document uses "double notation" only on occasion for the benefit of those readers who are accustomed to it.


Node:Double Quote Meaning, Next:Exclamation Point, Up:VXT Fortran

Meaning of Double Quote

g77 treats double-quote (") as beginning an octal constant of INTEGER(KIND=1) type when the -fvxt option is specified. The form of this octal constant is

"octal-digits

where octal-digits is a nonempty string of characters in the set 01234567.

For example, the -fvxt option permits this:

PRINT *, "20
END

The above program would print the value 16.

See Integer Type, for information on the preferred construct for integer constants specified using GNU Fortran's octal notation.

(In the GNU Fortran language, the double-quote character (") delimits a character constant just as does apostrophe ('). There is no way to allow both constructs in the general case, since statements like PRINT *,"2000 !comment?" would be ambiguous.)


Node:DProd Intrinsic, Next:DSign Intrinsic, Previous:Dot_Product Intrinsic, Up:Table of Intrinsic Functions

DProd Intrinsic

DProd(X, Y)

DProd: REAL(KIND=2) function.

X: REAL(KIND=1); scalar; INTENT(IN).

Y: REAL(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns DBLE(X)*DBLE(Y).


Node:DReal Intrinsic, Next:DSinD Intrinsic, Previous:DImag Intrinsic, Up:Other Intrinsics

DReal Intrinsic

DReal(A)

DReal: REAL(KIND=2) function.

A: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: vxt.

Description:

Converts A to REAL(KIND=2).

If A is type COMPLEX, its real part is converted (if necessary) to REAL(KIND=2), and its imaginary part is disregarded.

Although this intrinsic is not standard Fortran, it is a popular extension offered by many compilers that support DOUBLE COMPLEX, since it offers the easiest way to extract the real part of a DOUBLE COMPLEX value without using the Fortran 90 REAL() intrinsic in a way that produces a return value inconsistent with the way many FORTRAN 77 compilers handle REAL() of a DOUBLE COMPLEX value.

See RealPart Intrinsic, for information on a GNU Fortran intrinsic that avoids these areas of confusion.

See Dble Intrinsic, for information on the standard FORTRAN 77 replacement for DREAL().

See REAL() and AIMAG() of Complex, for more information on this issue.


Node:Dropping f2c Compatibility, Next:Compilers Other Than f2c, Up:Other Compilers

Dropping f2c Compatibility

Specifying -fno-f2c allows g77 to generate, in some cases, faster code, by not needing to allow to the possibility of linking with code compiled by f2c.

For example, this affects how REAL(KIND=1), COMPLEX(KIND=1), and COMPLEX(KIND=2) functions are called. With -fno-f2c, they are compiled as returning the appropriate gcc type (float, __complex__ float, __complex__ double, in many configurations).

With -ff2c in force, they are compiled differently (with perhaps slower run-time performance) to accommodate the restrictions inherent in f2c's use of K&R C as an intermediate language--REAL(KIND=1) functions return C's double type, while COMPLEX functions return void and use an extra argument pointing to a place for the functions to return their values.

It is possible that, in some cases, leaving -ff2c in force might produce faster code than using -fno-f2c. Feel free to experiment, but remember to experiment with changing the way entire programs and their Fortran libraries are compiled at a time, since this sort of experimentation affects the interface of code generated for a Fortran source file--that is, it affects object compatibility.

Note that f2c compatibility is a fairly static target to achieve, though not necessarily perfectly so, since, like g77, it is still being improved. However, specifying -fno-f2c causes g77 to generate code that will probably be incompatible with code generated by future versions of g77 when the same option is in force. You should make sure you are always able to recompile complete programs from source code when upgrading to new versions of g77 or f2c, especially when using options such as -fno-f2c.

Therefore, if you are using g77 to compile libraries and other object files for possible future use and you don't want to require recompilation for future use with subsequent versions of g77, you might want to stick with f2c compatibility for now, and carefully watch for any announcements about changes to the f2c/libf2c interface that might affect existing programs (thus requiring recompilation).

It is probable that a future version of g77 will not, by default, generate object files compatible with f2c, and that version probably would no longer use libf2c. If you expect to depend on this compatibility in the long term, use the options -ff2c -ff2c-library when compiling all of the applicable code. This should cause future versions of g77 either to produce compatible code (at the expense of the availability of some features and performance), or at the very least, to produce diagnostics.

(The library g77 produces will no longer be named libg2c when it is no longer generally compatible with libf2c. It will likely be referred to, and, if installed as a distinct library, named libg77, or some other as-yet-unused name.)


Node:DSign Intrinsic, Next:DSin Intrinsic, Previous:DProd Intrinsic, Up:Table of Intrinsic Functions

DSign Intrinsic

DSign(A, B)

DSign: REAL(KIND=2) function.

A: REAL(KIND=2); scalar; INTENT(IN).

B: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of SIGN() that is specific to one type for A and B. See Sign Intrinsic.


Node:DSin Intrinsic, Next:DSinH Intrinsic, Previous:DSign Intrinsic, Up:Table of Intrinsic Functions

DSin Intrinsic

DSin(X)

DSin: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of SIN() that is specific to one type for X. See Sin Intrinsic.


Node:DSinD Intrinsic, Next:DTanD Intrinsic, Previous:DReal Intrinsic, Up:Other Intrinsics

DSinD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DSinD to use this name for an external procedure.


Node:DSinH Intrinsic, Next:DSqRt Intrinsic, Previous:DSin Intrinsic, Up:Table of Intrinsic Functions

DSinH Intrinsic

DSinH(X)

DSinH: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of SINH() that is specific to one type for X. See SinH Intrinsic.


Node:DSqRt Intrinsic, Next:DTan Intrinsic, Previous:DSinH Intrinsic, Up:Table of Intrinsic Functions

DSqRt Intrinsic

DSqRt(X)

DSqRt: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of SQRT() that is specific to one type for X. See SqRt Intrinsic.


Node:DTan Intrinsic, Next:DTanH Intrinsic, Previous:DSqRt Intrinsic, Up:Table of Intrinsic Functions

DTan Intrinsic

DTan(X)

DTan: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of TAN() that is specific to one type for X. See Tan Intrinsic.


Node:DTanD Intrinsic, Next:DTime Intrinsic (function), Previous:DSinD Intrinsic, Up:Other Intrinsics

DTanD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL DTanD to use this name for an external procedure.


Node:DTanH Intrinsic, Next:DTime Intrinsic (subroutine), Previous:DTan Intrinsic, Up:Table of Intrinsic Functions

DTanH Intrinsic

DTanH(X)

DTanH: REAL(KIND=2) function.

X: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of TANH() that is specific to one type for X. See TanH Intrinsic.


Node:DTime Intrinsic (function), Next:FGet Intrinsic (function), Previous:DTanD Intrinsic, Up:Other Intrinsics

DTime Intrinsic (function)

DTime(TArray)

DTime: REAL(KIND=1) function.

TArray: REAL(KIND=1); DIMENSION(2); INTENT(OUT).

Intrinsic groups: badu77.

Description:

Initially, return the number of seconds of runtime since the start of the process's execution as the function value, and the user and system components of this in TArray(1) and TArray(2) respectively. The functions' value is equal to TArray(1) + TArray(2).

Subsequent invocations of DTIME() return values accumulated since the previous invocation.

On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wraparounds) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See DTime Intrinsic (subroutine).


Node:DTime Intrinsic (subroutine), Next:EOShift Intrinsic, Previous:DTanH Intrinsic, Up:Table of Intrinsic Functions

DTime Intrinsic (subroutine)

CALL DTime(TArray, Result)

TArray: REAL(KIND=1); DIMENSION(2); INTENT(OUT).

Result: REAL(KIND=1); scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Initially, return the number of seconds of runtime since the start of the process's execution in Result, and the user and system components of this in TArray(1) and TArray(2) respectively. The value of Result is equal to TArray(1) + TArray(2).

Subsequent invocations of DTIME() set values based on accumulations since the previous invocation.

On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wraparounds) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine.

For information on other intrinsics with the same name: See DTime Intrinsic (function).


Node:Dummy Array Without Dimensioning Dummy, Next:Invalid FORMAT Specifiers, Previous:Invalid Use of Hollerith Constant, Up:Missing Features

Dummy Array Without Dimensioning Dummy

g77 should complain when a list of dummy arguments containing an adjustable dummy array does not also contain every variable listed in the dimension list of the adjustable array.

Currently, g77 does complain about a variable that dimensions an array but doesn't appear in any dummy list or COMMON area, but this needs to be extended to catch cases where it doesn't appear in every dummy list that also lists any arrays it dimensions.

For example, g77 should warn about the entry point ALT below, since it includes ARRAY but not ISIZE in its list of arguments:

SUBROUTINE PRIMARY(ARRAY, ISIZE)
REAL ARRAY(ISIZE)
ENTRY ALT(ARRAY)


Node:Ease of Debugging, Next:Character and Hollerith Constants, Previous:Program Speed, Up:Advantages Over f2c

Ease of Debugging

Because g77 compiles directly to assembler code like gcc, instead of translating to an intermediate language (C) as does f2c, support for debugging can be better for g77 than f2c.

However, although g77 might be somewhat more "native" in terms of debugging support than f2c plus gcc, there still are a lot of things "not quite right". Many of the important ones should be resolved in the near future.

For example, g77 doesn't have to worry about reserved names like f2c does. Given FOR = WHILE, f2c must necessarily translate this to something other than for = while;, because C reserves those words.

However, g77 does still uses things like an extra level of indirection for ENTRY-laden procedures--in this case, because the back end doesn't yet support multiple entry points.

Another example is that, given

COMMON A, B
EQUIVALENCE (B, C)

the g77 user should be able to access the variables directly, by name, without having to traverse C-like structures and unions, while f2c is unlikely to ever offer this ability (due to limitations in the C language).

However, due to apparent bugs in the back end, g77 currently doesn't take advantage of this facility at all--it doesn't emit any debugging information for COMMON and EQUIVALENCE areas, other than information on the array of char it creates (and, in the case of local EQUIVALENCE, names) for each such area.

Yet another example is arrays. g77 represents them to the debugger using the same "dimensionality" as in the source code, while f2c must necessarily convert them all to one-dimensional arrays to fit into the confines of the C language. However, the level of support offered by debuggers for interactive Fortran-style access to arrays as compiled by g77 can vary widely. In some cases, it can actually be an advantage that f2c converts everything to widely supported C semantics.

In fairness, g77 could do many of the things f2c does to get things working at least as well as f2c--for now, the developers prefer making g77 work the way they think it is supposed to, and finding help improving the other products (the back end of gcc; gdb; and so on) to get things working properly.


Node:Efficiency, Next:Better Optimization, Up:Projects

Improve Efficiency

Don't bother doing any performance analysis until most of the following items are taken care of, because there's no question they represent serious space/time problems, although some of them show up only given certain kinds of (popular) input.

  • Improve malloc package and its uses to specify more info about memory pools and, where feasible, use obstacks to implement them.
  • Skip over uninitialized portions of aggregate areas (arrays, COMMON areas, EQUIVALENCE areas) so zeros need not be output. This would reduce memory usage for large initialized aggregate areas, even ones with only one initialized element.

    As of version 0.5.18, a portion of this item has already been accomplished.

  • Prescan the statement (in sta.c) so that the nature of the statement is determined as much as possible by looking entirely at its form, and not looking at any context (previous statements, including types of symbols). This would allow ripping out of the statement-confirmation, symbol retraction/confirmation, and diagnostic inhibition mechanisms. Plus, it would result in much-improved diagnostics. For example, CALL some-intrinsic(...), where the intrinsic is not a subroutine intrinsic, would result actual error instead of the unimplemented-statement catch-all.
  • Throughout g77, don't pass line/column pairs where a simple ffewhere type, which points to the error as much as is desired by the configuration, will do, and don't pass ffelexToken types where a simple ffewhere type will do. Then, allow new default configuration of ffewhere such that the source line text is not preserved, and leave it to things like Emacs' next-error function to point to them (now that next-error supports column, or, perhaps, character-offset, numbers). The change in calling sequences should improve performance somewhat, as should not having to save source lines. (Whether this whole item will improve performance is questionable, but it should improve maintainability.)
  • Handle DATA (A(I),I=1,1000000)/1000000*2/ more efficiently, especially as regards the assembly output. Some of this might require improving the back end, but lots of improvement in space/time required in g77 itself can be fairly easily obtained without touching the back end. Maybe type-conversion, where necessary, can be speeded up as well in cases like the one shown (converting the 2 into 2.).
  • If analysis shows it to be worthwhile, optimize lex.c.
  • Consider redesigning lex.c to not need any feedback during tokenization, by keeping track of enough parse state on its own.


Node:Enabling Debug Lines, Next:Better Warnings, Previous:Increasing Precision/Range, Up:Missing Features

Enabling Debug Lines

An option such as -fdebug-lines should be provided to turn fixed-form lines beginning with D to be treated as if they began with a space, instead of as if they began with a C (as comment lines).


Node:ENCODE and DECODE, Next:AUTOMATIC Statement, Previous:OPEN CLOSE and INQUIRE Keywords, Up:Missing Features

ENCODE and DECODE

g77 doesn't support ENCODE or DECODE.

These statements are best replaced by READ and WRITE statements involving internal files (CHARACTER variables and arrays).

For example, replace a code fragment like

      INTEGER*1 LINE(80)
...
      DECODE (80, 9000, LINE) A, B, C
...
9000  FORMAT (1X, 3(F10.5))

with:

      CHARACTER*80 LINE
...
      READ (UNIT=LINE, FMT=9000) A, B, C
...
9000  FORMAT (1X, 3(F10.5))

Similarly, replace a code fragment like

      INTEGER*1 LINE(80)
...
      ENCODE (80, 9000, LINE) A, B, C
...
9000  FORMAT (1X, 'OUTPUT IS ', 3(F10.5))

with:

      CHARACTER*80 LINE
...
      WRITE (UNIT=LINE, FMT=9000) A, B, C
...
9000  FORMAT (1X, 'OUTPUT IS ', 3(F10.5))

It is entirely possible that ENCODE and DECODE will be supported by a future version of g77.


Node:END DO, Next:Construct Names, Previous:DO WHILE, Up:Control Statements

END DO

The END DO statement is provided by the GNU Fortran language.

This statement is used in one of two ways:

  • The Fortran 90 meaning, in which it specifies the termination point of a single DO loop started with a DO statement that specifies no termination label.
  • The MIL-STD 1753 meaning, in which it specifies the termination point of one or more DO loops, all of which start with a DO statement that specify the label defined for the END DO statement.

    This kind of END DO statement is merely a synonym for CONTINUE, except it is permitted only when the statement is labeled and a target of one or more labeled DO loops.

    It is expected that this use of END DO will be removed from the GNU Fortran language in the future, though it is likely that it will long be supported by g77 as a dialect form.


Node:Environment Variables, Previous:Code Gen Options, Up:Invoking G77

Environment Variables Affecting GNU Fortran

GNU Fortran currently does not make use of any environment variables to control its operation above and beyond those that affect the operation of gcc.

See Environment Variables Affecting GCC, for information on environment variables.


Node:EOShift Intrinsic, Next:Epsilon Intrinsic, Previous:DTime Intrinsic (subroutine), Up:Table of Intrinsic Functions

EOShift Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL EOShift to use this name for an external procedure.


Node:Epsilon Intrinsic, Next:ErF Intrinsic, Previous:EOShift Intrinsic, Up:Table of Intrinsic Functions

Epsilon Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Epsilon to use this name for an external procedure.


Node:Equivalence Versus Equality, Next:Order of Side Effects, Previous:Context-Sensitive Constants, Up:Non-bugs

Equivalence Versus Equality

Use of .EQ. and .NE. on LOGICAL operands is not supported, except via -fugly-logint, which is not recommended except for legacy code (where the behavior expected by the code is assumed).

Legacy code should be changed, as resources permit, to use .EQV. and .NEQV. instead, as these are permitted by the various Fortran standards.

New code should never be written expecting .EQ. or .NE. to work if either of its operands is LOGICAL.

The problem with supporting this "feature" is that there is unlikely to be consensus on how it works, as illustrated by the following sample program:

LOGICAL L,M,N
DATA L,M,N /3*.FALSE./
IF (L.AND.M.EQ.N) PRINT *,'L.AND.M.EQ.N'
END

The issue raised by the above sample program is: what is the precedence of .EQ. (and .NE.) when applied to LOGICAL operands?

Some programmers will argue that it is the same as the precedence for .EQ. when applied to numeric (such as INTEGER) operands. By this interpretation, the subexpression M.EQ.N must be evaluated first in the above program, resulting in a program that, when run, does not execute the PRINT statement.

Other programmers will argue that the precedence is the same as the precedence for .EQV., which is restricted by the standards to LOGICAL operands. By this interpretation, the subexpression L.AND.M must be evaluated first, resulting in a program that does execute the PRINT statement.

Assigning arbitrary semantic interpretations to syntactic expressions that might legitimately have more than one "obvious" interpretation is generally unwise.

The creators of the various Fortran standards have done a good job in this case, requiring a distinct set of operators (which have their own distinct precedence) to compare LOGICAL operands. This requirement results in expression syntax with more certain precedence (without requiring substantial context), making it easier for programmers to read existing code. g77 will avoid muddying up elements of the Fortran language that were well-designed in the first place.

(Ask C programmers about the precedence of expressions such as (a) & (b) and (a) - (b)--they cannot even tell you, without knowing more context, whether the & and - operators are infix (binary) or unary!)

Most dangerous of all is the fact that, even assuming consensus on its meaning, an expression like L.AND.M.EQ.N, if it is the result of a typographical error, doesn't look like it has such a typo. Even experienced Fortran programmers would not likely notice that L.AND.M.EQV.N was, in fact, intended.

So, this is a prime example of a circumstance in which a quality compiler diagnoses the code, instead of leaving it up to someone debugging it to know to turn on special compiler options that might diagnose it.


Node:ErF Intrinsic, Next:ErFC Intrinsic, Previous:Epsilon Intrinsic, Up:Table of Intrinsic Functions

ErF Intrinsic

ErF(X)

ErF: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns the error function of X. See erf(3m), which provides the implementation.


Node:ErFC Intrinsic, Next:ETime Intrinsic (subroutine), Previous:ErF Intrinsic, Up:Table of Intrinsic Functions

ErFC Intrinsic

ErFC(X)

ErFC: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns the complementary error function of X: ERFC(R) = 1 - ERF(R) (except that the result might be more accurate than explicitly evaluating that formulae would give). See erfc(3m), which provides the implementation.


Node:ETime Intrinsic (function), Next:Exit Intrinsic, Previous:ETime Intrinsic (subroutine), Up:Table of Intrinsic Functions

ETime Intrinsic (function)

ETime(TArray)

ETime: REAL(KIND=1) function.

TArray: REAL(KIND=1); DIMENSION(2); INTENT(OUT).

Intrinsic groups: unix.

Description:

Return the number of seconds of runtime since the start of the process's execution as the function value, and the user and system components of this in TArray(1) and TArray(2) respectively. The functions' value is equal to TArray(1) + TArray(2).

On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wraparounds) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

For information on other intrinsics with the same name: See ETime Intrinsic (subroutine).


Node:ETime Intrinsic (subroutine), Next:ETime Intrinsic (function), Previous:ErFC Intrinsic, Up:Table of Intrinsic Functions

ETime Intrinsic (subroutine)

CALL ETime(TArray, Result)

TArray: REAL(KIND=1); DIMENSION(2); INTENT(OUT).

Result: REAL(KIND=1); scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Return the number of seconds of runtime since the start of the process's execution in Result, and the user and system components of this in TArray(1) and TArray(2) respectively. The value of Result is equal to TArray(1) + TArray(2).

On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wraparounds) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine.

For information on other intrinsics with the same name: See ETime Intrinsic (function).


Node:Exclamation Point, Previous:Double Quote Meaning, Up:VXT Fortran

Meaning of Exclamation Point in Column 6

g77 treats an exclamation point (!) in column 6 of a fixed-form source file as a continuation character rather than as the beginning of a comment (as it does in any other column) when the -fvxt option is specified.

The following program, when run, prints a message indicating whether it is interpreted according to GNU Fortran (and Fortran 90) rules or VXT Fortran rules:

C234567  (This line begins in column 1.)
      I = 0
     !1
      IF (I.EQ.0) PRINT *, ' I am a VXT Fortran program'
      IF (I.EQ.1) PRINT *, ' I am a Fortran 90 program'
      IF (I.LT.0 .OR. I.GT.1) PRINT *, ' I am a HAL 9000 computer'
      END

(In the GNU Fortran and Fortran 90 languages, exclamation point is a valid character and, unlike space (<SPC>) or zero (0), marks a line as a continuation line when it appears in column 6.)


Node:Exit Intrinsic, Next:Exp Intrinsic, Previous:ETime Intrinsic (function), Up:Table of Intrinsic Functions

Exit Intrinsic

CALL Exit(Status)

Status: INTEGER not wider than the default kind; OPTIONAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Exit the program with status Status after closing open Fortran I/O units and otherwise behaving as exit(2). If Status is omitted the canonical `success' value will be returned to the system.


Node:Exp Intrinsic, Next:Exponent Intrinsic, Previous:Exit Intrinsic, Up:Table of Intrinsic Functions

Exp Intrinsic

Exp(X)

Exp: REAL or COMPLEX function, the exact type being that of argument X.

X: REAL or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns e**X, where e is approximately 2.7182818.

See Log Intrinsic, for the inverse of this function.


Node:EXPIMP, Next:INTGLOB, Previous:CMPAMBIG, Up:Diagnostics

EXPIMP

Intrinsic intrinsic referenced ...

The intrinsic is explicitly declared in one program unit in the source file and implicitly used as an intrinsic in another program unit in the same source file.

This diagnostic is designed to catch cases where a program might depend on using the name intrinsic as an intrinsic in one program unit and as a global name (such as the name of a subroutine or function) in another, but g77 recognizes the name as an intrinsic in both cases.

After verifying that the program unit making implicit use of the intrinsic is indeed written expecting the intrinsic, add an INTRINSIC intrinsic statement to that program unit to prevent this warning.

This and related warnings are disabled by using the -Wno-globals option when compiling.

Note that this warning is not issued for standard intrinsics. Standard intrinsics include those described in the FORTRAN 77 standard and, if -ff90 is specified, those described in the Fortran 90 standard. Such intrinsics are not as likely to be confused with user procedures as intrinsics provided as extensions to the standard by g77.


Node:Explicit Assembler Code, Next:Q Edit Descriptor, Previous:Expressions in FORMAT Statements, Up:Missing Features

Explicit Assembler Code

g77 needs to provide some way, a la gcc, for g77 code to specify explicit assembler code.


Node:Exponent Intrinsic, Next:FDate Intrinsic (subroutine), Previous:Exp Intrinsic, Up:Table of Intrinsic Functions

Exponent Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Exponent to use this name for an external procedure.


Node:expr.c, Next:stc.c, Previous:stb.c, Up:Overview of Translation Process

expr.c


Node:Expressions in FORMAT Statements, Next:Explicit Assembler Code, Previous:FLUSH Statement, Up:Missing Features

Expressions in FORMAT Statements

g77 doesn't support FORMAT(I<J>) and the like. Supporting this requires a significant redesign or replacement of libg2c.

However, g77 does support this construct when the expression is constant (as of version 0.5.22). For example:

      PARAMETER (IWIDTH = 12)
10    FORMAT (I<IWIDTH>)

Otherwise, at least for output (PRINT and WRITE), Fortran code making use of this feature can be rewritten to avoid it by constructing the FORMAT string in a CHARACTER variable or array, then using that variable or array in place of the FORMAT statement label to do the original PRINT or WRITE.

Many uses of this feature on input can be rewritten this way as well, but not all can. For example, this can be rewritten:

      READ 20, I
20    FORMAT (I<J>)

However, this cannot, in general, be rewritten, especially when ERR= and END= constructs are employed:

      READ 30, J, I
30    FORMAT (I<J>)


Node:Expressions, Next:Specification Statements, Previous:Data Types and Constants, Up:Language

Expressions

(The following information augments or overrides the information in Chapter 6 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 6 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

  • %LOC():


Node:f2c Skeletons and Prototypes, Next:C++ Considerations, Previous:C Access to Type Information, Up:Interoperating with C and C++

Generating Skeletons and Prototypes with f2c

A simple and foolproof way to write g77-callable C routines--e.g. to interface with an existing library--is to write a file (named, for example, fred.f) of dummy Fortran skeletons comprising just the declaration of the routine(s) and dummy arguments plus END statements. Then run f2c on file fred.f to produce fred.c into which you can edit useful code, confident the calling sequence is correct, at least. (There are some errors otherwise commonly made in generating C interfaces with f2c conventions, such as not using doublereal as the return type of a REAL FUNCTION.)

f2c also can help with calling Fortran from C, using its -P option to generate C prototypes appropriate for calling the Fortran.1 If the Fortran code containing any routines to be called from C is in file joe.f, use the command f2c -P joe.f to generate the file joe.P containing prototype information. #include this in the C which has to call the Fortran routines to make sure you get it right.

See Arrays (DIMENSION), for information on the differences between the way Fortran (including compilers like g77) and C handle arrays.

Footnotes

  1. The files generated like this can also be used for inter-unit consistency checking of dummy and actual arguments, although the ftnchek tool from ftp://ftp.netlib.org/fortran or ftp://ftp.dsm.fordham.edu is probably better for this purpose.


Node:f77/f2c Intrinsics, Next:Table of Intrinsic Functions, Previous:MIL-STD 1753, Up:Functions and Subroutines

f77/f2c Intrinsics

The bit-manipulation intrinsics supported by traditional f77 and by f2c are available in the GNU Fortran language. These include AND, LSHIFT, OR, RSHIFT, and XOR.

Also supported are the intrinsics CDABS, CDCOS, CDEXP, CDLOG, CDSIN, CDSQRT, DCMPLX, DCONJG, DFLOAT, DIMAG, DREAL, and IMAG, ZABS, ZCOS, ZEXP, ZLOG, ZSIN, and ZSQRT.


Node:Faster Programs, Previous:Overly Convenient Options, Up:Collected Fortran Wisdom

Faster Programs

Aside from the usual gcc options, such as -O, -ffast-math, and so on, consider trying some of the following approaches to speed up your program (once you get it working).

  • Aligned Data:
  • Prefer Automatic Uninitialized Variables:
  • Avoid f2c Compatibility:
  • Use Submodel Options:


Node:FDate Intrinsic (function), Next:FGet Intrinsic (subroutine), Previous:FDate Intrinsic (subroutine), Up:Table of Intrinsic Functions

FDate Intrinsic (function)

FDate()

FDate: CHARACTER*(*) function.

Intrinsic groups: unix.

Description:

Returns the current date (using the same format as CTIME()).

Equivalent to:

CTIME(TIME8())

Programs making use of this intrinsic might not be Year 10000 (Y10K) compliant. For example, the date might appear, to such programs, to wrap around (change from a larger value to a smaller one) as of the Year 10000.

See CTime Intrinsic (function).

For information on other intrinsics with the same name: See FDate Intrinsic (subroutine).


Node:FDate Intrinsic (subroutine), Next:FDate Intrinsic (function), Previous:Exponent Intrinsic, Up:Table of Intrinsic Functions

FDate Intrinsic (subroutine)

CALL FDate(Date)

Date: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Returns the current date (using the same format as CTIME()) in Date.

Equivalent to:

CALL CTIME(Date, TIME8())

Programs making use of this intrinsic might not be Year 10000 (Y10K) compliant. For example, the date might appear, to such programs, to wrap around (change from a larger value to a smaller one) as of the Year 10000.

See CTime Intrinsic (subroutine).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine.

For information on other intrinsics with the same name: See FDate Intrinsic (function).


Node:FGet Intrinsic (function), Next:FGetC Intrinsic (function), Previous:DTime Intrinsic (function), Up:Other Intrinsics

FGet Intrinsic (function)

FGet(C)

FGet: INTEGER(KIND=1) function.

C: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: badu77.

Description:

Reads a single character into C in stream mode from unit 5 (by-passing normal formatted input) using getc(3). Returns 0 on success, -1 on end-of-file, and the error code from ferror(3) otherwise.

Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable.

For information on other intrinsics with the same name: See FGet Intrinsic (subroutine).


Node:FGet Intrinsic (subroutine), Next:FGetC Intrinsic (subroutine), Previous:FDate Intrinsic (function), Up:Table of Intrinsic Functions

FGet Intrinsic (subroutine)

CALL FGet(C, Status)

C: CHARACTER; scalar; INTENT(OUT).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Reads a single character into C in stream mode from unit 5 (by-passing normal formatted output) using getc(3). Returns in Status 0 on success, -1 on end-of-file, and the error code from ferror(3) otherwise.

Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable.

For information on other intrinsics with the same name: See FGet Intrinsic (function).


Node:FGetC Intrinsic (function), Next:FloatI Intrinsic, Previous:FGet Intrinsic (function), Up:Other Intrinsics

FGetC Intrinsic (function)

FGetC(Unit, C)

FGetC: INTEGER(KIND=1) function.

Unit: INTEGER; scalar; INTENT(IN).

C: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: badu77.

Description:

Reads a single character into C in stream mode from unit Unit (by-passing normal formatted output) using getc(3). Returns 0 on success, -1 on end-of-file, and the error code from ferror(3) otherwise.

Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable.

For information on other intrinsics with the same name: See FGetC Intrinsic (subroutine).


Node:FGetC Intrinsic (subroutine), Next:Float Intrinsic, Previous:FGet Intrinsic (subroutine), Up:Table of Intrinsic Functions

FGetC Intrinsic (subroutine)

CALL FGetC(Unit, C, Status)

Unit: INTEGER; scalar; INTENT(IN).

C: CHARACTER; scalar; INTENT(OUT).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Reads a single character into C in stream mode from unit Unit (by-passing normal formatted output) using getc(3). Returns in Status 0 on success, -1 on end-of-file, and the error code from ferror(3) otherwise.

Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable.

For information on other intrinsics with the same name: See FGetC Intrinsic (function).


Node:Float Intrinsic, Next:Floor Intrinsic, Previous:FGetC Intrinsic (subroutine), Up:Table of Intrinsic Functions

Float Intrinsic

Float(A)

Float: REAL(KIND=1) function.

A: INTEGER; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of REAL() that is specific to one type for A. See Real Intrinsic.


Node:FloatI Intrinsic, Next:FloatJ Intrinsic, Previous:FGetC Intrinsic (function), Up:Other Intrinsics

FloatI Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL FloatI to use this name for an external procedure.


Node:Floating-point Errors, Previous:Strange Behavior at Run Time, Up:But-bugs

Floating-point Errors

Some programs appear to produce inconsistent floating-point results compiled by g77 versus by other compilers.

Often the reason for this behavior is the fact that floating-point values are represented on almost all Fortran systems by approximations, and these approximations are inexact even for apparently simple values like 0.1, 0.2, 0.3, 0.4, 0.6, 0.7, 0.8, 0.9, 1.1, and so on. Most Fortran systems, including all current ports of g77, use binary arithmetic to represent these approximations.

Therefore, the exact value of any floating-point approximation as manipulated by g77-compiled code is representable by adding some combination of the values 1.0, 0.5, 0.25, 0.125, and so on (just keep dividing by two) through the precision of the fraction (typically around 23 bits for REAL(KIND=1), 52 for REAL(KIND=2)), then multiplying the sum by a integral power of two (in Fortran, by 2**N) that typically is between -127 and +128 for REAL(KIND=1) and -1023 and +1024 for REAL(KIND=2), then multiplying by -1 if the number is negative.

So, a value like 0.2 is exactly represented in decimal--since it is a fraction, 2/10, with a denominator that is compatible with the base of the number system (base 10). However, 2/10 cannot be represented by any finite number of sums of any of 1.0, 0.5, 0.25, and so on, so 0.2 cannot be exactly represented in binary notation.

(On the other hand, decimal notation can represent any binary number in a finite number of digits. Decimal notation cannot do so with ternary, or base-3, notation, which would represent floating-point numbers as sums of any of 1/1, 1/3, 1/9, and so on. After all, no finite number of decimal digits can exactly represent 1/3. Fortunately, few systems use ternary notation.)

Moreover, differences in the way run-time I/O libraries convert between these approximations and the decimal representation often used by programmers and the programs they write can result in apparent differences between results that do not actually exist, or exist to such a small degree that they usually are not worth worrying about.

For example, consider the following program:

PRINT *, 0.2
END

When compiled by g77, the above program might output 0.20000003, while another compiler might produce a executable that outputs 0.2.

This particular difference is due to the fact that, currently, conversion of floating-point values by the libg2c library, used by g77, handles only double-precision values.

Since 0.2 in the program is a single-precision value, it is converted to double precision (still in binary notation) before being converted back to decimal. The conversion to binary appends binary zero digits to the original value--which, again, is an inexact approximation of 0.2--resulting in an approximation that is much less exact than is connoted by the use of double precision.

(The appending of binary zero digits has essentially the same effect as taking a particular decimal approximation of 1/3, such as 0.3333333, and appending decimal zeros to it, producing 0.33333330000000000. Treating the resulting decimal approximation as if it really had 18 or so digits of valid precision would make it seem a very poor approximation of 1/3.)

As a result of converting the single-precision approximation to double precision by appending binary zeros, the conversion of the resulting double-precision value to decimal produces what looks like an incorrect result, when in fact the result is inexact, and is probably no less inaccurate or imprecise an approximation of 0.2 than is produced by other compilers that happen to output the converted value as "exactly" 0.2. (Some compilers behave in a way that can make them appear to retain more accuracy across a conversion of a single-precision constant to double precision. See Context-Sensitive Constants, to see why this practice is illusory and even dangerous.)

Note that a more exact approximation of the constant is computed when the program is changed to specify a double-precision constant:

PRINT *, 0.2D0
END

Future versions of g77 and/or libg2c might convert single-precision values directly to decimal, instead of converting them to double precision first. This would tend to result in output that is more consistent with that produced by some other Fortran implementations.

A useful source of information on floating-point computation is David Goldberg, `What Every Computer Scientist Should Know About Floating-Point Arithmetic', Computing Surveys, 23, March 1991, pp. 5-48. An online version is available at http://docs.sun.com/, and there is a supplemented version, in PostScript form, at http://www.validgh.com/goldberg/paper.ps.

Information related to the IEEE 754 floating-point standard by a leading light can be found at http://http.cs.berkeley.edu/%7Ewkahan/ieee754status/; see also slides from the short course referenced from http://http.cs.berkeley.edu/%7Efateman/. http://www.linuxsupportline.com/%7Ebillm/ has a brief guide to IEEE 754, a somewhat x86-GNU/Linux-specific FAQ, and library code for GNU/Linux x86 systems.

The supplement to the PostScript-formatted Goldberg document, referenced above, is available in HTML format. See `Differences Among IEEE 754 Implementations' by Doug Priest, available online at http://www.validgh.com/goldberg/addendum.html. This document explores some of the issues surrounding computing of extended (80-bit) results on processors such as the x86, especially when those results are arbitrarily truncated to 32-bit or 64-bit values by the compiler as "spills".

(Note: g77 specifically, and gcc generally, does arbitrarily truncate 80-bit results during spills as of this writing. It is not yet clear whether a future version of the GNU compiler suite will offer 80-bit spills as an option, or perhaps even as the default behavior.)

The GNU C library provides routines for controlling the FPU, and other documentation about this.

See Floating-point precision, regarding IEEE 754 conformance.


Node:Floating-point Exception Handling, Next:Nonportable Conversions, Previous:POSIX Standard, Up:Missing Features

Floating-point Exception Handling

The gcc backend and, consequently, g77, currently provides no general control over whether or not floating-point exceptions are trapped or ignored. (Ignoring them typically results in NaN values being propagated in systems that conform to IEEE 754.) The behaviour is normally inherited from the system-dependent startup code, though some targets, such as the Alpha, have code generation options which change the behaviour.

Most systems provide some C-callable mechanism to change this; this can be invoked at startup using gcc's constructor attribute. For example, just compiling and linking the following C code with your program will turn on exception trapping for the "common" exceptions on a GNU system using glibc 2.2 or newer:

#define _GNU_SOURCE 1
#include <fenv.h>
static void __attribute__ ((constructor))
trapfpe ()
{
  /* Enable some exceptions.  At startup all exceptions are masked.  */

  feenableexcept (FE_INVALID|FE_DIVBYZERO|FE_OVERFLOW);
}

A convenient trick is to compile this something like:

gcc -o libtrapfpe.a trapfpe.c
and then use it by adding -trapfpe to the g77 command line when linking.


Node:Floating-point precision, Next:Inconsistent Calling Sequences, Previous:Large File Unit Numbers, Up:Working Programs

Floating-point precision

If your program depends on exact IEEE 754 floating-point handling it may help on some systems--specifically x86 or m68k hardware--to use the -ffloat-store option or to reset the precision flag on the floating-point unit. See Optimize Options.

However, it might be better simply to put the FPU into double precision mode and not take the performance hit of -ffloat-store. On x86 and m68k GNU systems you can do this with a technique similar to that for turning on floating-point exceptions (see Floating-point Exception Handling). The control word could be set to double precision by some code like this one:

#include <fpu_control.h>
{
  fpu_control_t cw = (_FPU_DEFAULT & ~_FPU_EXTENDED) | _FPU_DOUBLE;
  _FPU_SETCW(cw);
}
(It is not clear whether this has any effect on the operation of the GNU maths library, but we have no evidence of it causing trouble.)

Some targets (such as the Alpha) may need special options for full IEEE conformance. See Hardware Models and Configurations.


Node:FloatJ Intrinsic, Next:FPut Intrinsic (function), Previous:FloatI Intrinsic, Up:Other Intrinsics

FloatJ Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL FloatJ to use this name for an external procedure.


Node:Floor Intrinsic, Next:Flush Intrinsic, Previous:Float Intrinsic, Up:Table of Intrinsic Functions

Floor Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Floor to use this name for an external procedure.


Node:Flush Intrinsic, Next:FNum Intrinsic, Previous:Floor Intrinsic, Up:Table of Intrinsic Functions

Flush Intrinsic

CALL Flush(Unit)

Unit: INTEGER; OPTIONAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Flushes Fortran unit(s) currently open for output. Without the optional argument, all such units are flushed, otherwise just the unit specified by Unit.

Some non-GNU implementations of Fortran provide this intrinsic as a library procedure that might or might not support the (optional) Unit argument.


Node:FLUSH Statement, Next:Expressions in FORMAT Statements, Previous:READONLY Keyword, Up:Missing Features

FLUSH Statement

g77 could perhaps use a FLUSH statement that does what CALL FLUSH does, but that supports * as the unit designator (same unit as for PRINT) and accepts ERR= and/or IOSTAT= specifiers.


Node:FNum Intrinsic, Next:FPut Intrinsic (subroutine), Previous:Flush Intrinsic, Up:Table of Intrinsic Functions

FNum Intrinsic

FNum(Unit)

FNum: INTEGER(KIND=1) function.

Unit: INTEGER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns the Unix file descriptor number corresponding to the open Fortran I/O unit Unit. This could be passed to an interface to C I/O routines.


Node:Fortran 90 Features, Previous:I/O, Up:Language

Fortran 90 Features

For convenience this section collects a list (probably incomplete) of the Fortran 90 features supported by the GNU Fortran language, even if they are documented elsewhere. See Characters, Lines, and Execution Sequence, for information on additional fixed source form lexical issues. Further, the free source form is supported through the -ffree-form option. Other Fortran 90 features can be turned on by the -ff90 option; see Fortran 90. For information on the Fortran 90 intrinsics available, see Table of Intrinsic Functions.

Automatic arrays in procedures
Character assignments
In character assignments, the variable being assigned may occur on the right hand side of the assignment.
Character strings
Strings may have zero length and substrings of character constants are permitted. Character constants may be enclosed in double quotes (") as well as single quotes. See Character Type.
Construct names
(Symbolic tags on blocks.) See Construct Names.
CYCLE and EXIT
See The CYCLE and EXIT Statements.
DOUBLE COMPLEX
See DOUBLE COMPLEX Statement.
DO WHILE
See DO WHILE.
END decoration
See Statements.
END DO
See END DO.
KIND
IMPLICIT NONE
INCLUDE statements
See INCLUDE.
List-directed and namelist I/O on internal files
Binary, octal and hexadecimal constants
These are supported more generally than required by Fortran 90. See Integer Type.
O and Z edit descriptors
NAMELIST
See NAMELIST.
OPEN specifiers
STATUS='REPLACE' is supported.
The FILE= specifier may be omitted in an OPEN statement if
STATUS='SCRATCH' is supplied.
FORMAT edit descriptors
The Z edit descriptor is supported.
Relational operators
The operators <, <=, ==, /=, > and >= may be used instead of .LT., .LE., .EQ., .NE., .GT. and .GE. respectively.
SELECT CASE
Not fully implemented. See SELECT CASE on CHARACTER Type.
Specification statements
A limited subset of the Fortran 90 syntax and semantics for variable declarations is supported, including KIND. See Kind Notation. (KIND is of limited usefulness in the absence of the KIND-related intrinsics, since these intrinsics permit writing more widely portable code.) An example of supported KIND usage is:
INTEGER (KIND=1) :: FOO=1, BAR=2
CHARACTER (LEN=3) FOO
PARAMETER and DIMENSION attributes aren't supported.


Node:Fortran 90 Support, Next:Intrinsics in PARAMETER Statements, Previous:Better Source Model, Up:Missing Features

Fortran 90 Support

g77 does not support many of the features that distinguish Fortran 90 (and, now, Fortran 95) from ANSI FORTRAN 77.

Some Fortran 90 features are supported, because they make sense to offer even to die-hard users of F77. For example, many of them codify various ways F77 has been extended to meet users' needs during its tenure, so g77 might as well offer them as the primary way to meet those same needs, even if it offers compatibility with one or more of the ways those needs were met by other F77 compilers in the industry.

Still, many important F90 features are not supported, because no attempt has been made to research each and every feature and assess its viability in g77. In the meantime, users who need those features must use Fortran 90 compilers anyway, and the best approach to adding some F90 features to GNU Fortran might well be to fund a comprehensive project to create GNU Fortran 95.


Node:Fortran 90, Next:Pedantic Compilation, Previous:VXT Fortran, Up:Other Dialects

Fortran 90

The GNU Fortran language includes a number of features that are part of Fortran 90, even when the -ff90 option is not specified. The features enabled by -ff90 are intended to be those that, when -ff90 is not specified, would have another meaning to g77--usually meaning something invalid in the GNU Fortran language.

So, the purpose of -ff90 is not to specify whether g77 is to gratuitously reject Fortran 90 constructs. The -pedantic option specified with -fno-f90 is intended to do that, although its implementation is certainly incomplete at this point.

When -ff90 is specified:

  • The type of REAL(expr) and AIMAG(expr), where expr is COMPLEX type, is the same type as the real part of expr.

    For example, assuming Z is type COMPLEX(KIND=2),
REAL(Z) would return a value of type REAL(KIND=2),
not of type REAL(KIND=1), since -ff90 is specified.


Node:Fortran Dialect Options, Next:Warning Options, Previous:Shorthand Options, Up:Invoking G77

Options Controlling Fortran Dialect

The following options control the dialect of Fortran that the compiler accepts:

-ffree-form
-fno-fixed-form
Specify that the source file is written in free form (introduced in Fortran 90) instead of the more-traditional fixed form.
-ff90
Allow certain Fortran-90 constructs.

This option controls whether certain Fortran 90 constructs are recognized. (Other Fortran 90 constructs might or might not be recognized depending on other options such as -fvxt, -ff90-intrinsics-enable, and the current level of support for Fortran 90.)

See Fortran 90, for more information.

-fvxt
Specify the treatment of certain constructs that have different meanings depending on whether the code is written in GNU Fortran (based on FORTRAN 77 and akin to Fortran 90) or VXT Fortran (more like VAX FORTRAN).

The default is -fno-vxt. -fvxt specifies that the VXT Fortran interpretations for those constructs are to be chosen.

See VXT Fortran, for more information.

-fdollar-ok
Allow $ as a valid character in a symbol name.
-fno-backslash
Specify that \ is not to be specially interpreted in character and Hollerith constants a la C and many UNIX Fortran compilers.

For example, with -fbackslash in effect, A\nB specifies three characters, with the second one being newline. With -fno-backslash, it specifies four characters, A, \, n, and B.

Note that g77 implements a fairly general form of backslash processing that is incompatible with the narrower forms supported by some other compilers. For example, 'A\003B' is a three-character string in g77 whereas other compilers that support backslash might not support the three-octal-digit form, and thus treat that string as longer than three characters.

See Backslash in Constants, for information on why -fbackslash is the default instead of -fno-backslash.

-fno-ugly-args
Disallow passing Hollerith and typeless constants as actual arguments (for example, CALL FOO(4HABCD)).

See Ugly Implicit Argument Conversion, for more information.

-fugly-assign
Use the same storage for a given variable regardless of whether it is used to hold an assigned-statement label (as in ASSIGN 10 TO I) or used to hold numeric data (as in I = 3).

See Ugly Assigned Labels, for more information.

-fugly-assumed
Assume any dummy array with a final dimension specified as 1 is really an assumed-size array, as if * had been specified for the final dimension instead of 1.

For example, DIMENSION X(1) is treated as if it had read DIMENSION X(*).

See Ugly Assumed-Size Arrays, for more information.

-fugly-comma
In an external-procedure invocation, treat a trailing comma in the argument list as specification of a trailing null argument, and treat an empty argument list as specification of a single null argument.

For example, CALL FOO(,) is treated as CALL FOO(%VAL(0), %VAL(0)). That is, two null arguments are specified by the procedure call when -fugly-comma is in force. And F = FUNC() is treated as F = FUNC(%VAL(0)).

The default behavior, -fno-ugly-comma, is to ignore a single trailing comma in an argument list. So, by default, CALL FOO(X,) is treated exactly the same as CALL FOO(X).

See Ugly Null Arguments, for more information.

-fugly-complex
Do not complain about REAL(expr) or AIMAG(expr) when expr is a COMPLEX type other than COMPLEX(KIND=1)--usually this is used to permit COMPLEX(KIND=2) (DOUBLE COMPLEX) operands.

The -ff90 option controls the interpretation of this construct.

See Ugly Complex Part Extraction, for more information.

-fno-ugly-init
Disallow use of Hollerith and typeless constants as initial values (in PARAMETER and DATA statements), and use of character constants to initialize numeric types and vice versa.

For example, DATA I/'F'/, CHRVAR/65/, J/4HABCD/ is disallowed by -fno-ugly-init.

See Ugly Conversion of Initializers, for more information.

-fugly-logint
Treat INTEGER and LOGICAL variables and expressions as potential stand-ins for each other.

For example, automatic conversion between INTEGER and LOGICAL is enabled, for many contexts, via this option.

See Ugly Integer Conversions, for more information.

-fonetrip
Executable iterative DO loops are to be executed at least once each time they are reached.

ANSI FORTRAN 77 and more recent versions of the Fortran standard specify that the body of an iterative DO loop is not executed if the number of iterations calculated from the parameters of the loop is less than 1. (For example, DO 10 I = 1, 0.) Such a loop is called a zero-trip loop.

Prior to ANSI FORTRAN 77, many compilers implemented DO loops such that the body of a loop would be executed at least once, even if the iteration count was zero. Fortran code written assuming this behavior is said to require one-trip loops. For example, some code written to the FORTRAN 66 standard expects this behavior from its DO loops, although that standard did not specify this behavior.

The -fonetrip option specifies that the source file(s) being compiled require one-trip loops.

This option affects only those loops specified by the (iterative) DO statement and by implied-DO lists in I/O statements. Loops specified by implied-DO lists in DATA and specification (non-executable) statements are not affected.

-ftypeless-boz
Specifies that prefix-radix non-decimal constants, such as Z'ABCD', are typeless instead of INTEGER(KIND=1).

You can test for yourself whether a particular compiler treats the prefix form as INTEGER(KIND=1) or typeless by running the following program:

EQUIVALENCE (I, R)
R = Z'ABCD1234'
J = Z'ABCD1234'
IF (J .EQ. I) PRINT *, 'Prefix form is TYPELESS'
IF (J .NE. I) PRINT *, 'Prefix form is INTEGER'
END

Reports indicate that many compilers process this form as INTEGER(KIND=1), though a few as typeless, and at least one based on a command-line option specifying some kind of compatibility.

-fintrin-case-initcap
-fintrin-case-upper
-fintrin-case-lower
-fintrin-case-any
Specify expected case for intrinsic names. -fintrin-case-lower is the default.
-fmatch-case-initcap
-fmatch-case-upper
-fmatch-case-lower
-fmatch-case-any
Specify expected case for keywords. -fmatch-case-lower is the default.
-fsource-case-upper
-fsource-case-lower
-fsource-case-preserve
Specify whether source text other than character and Hollerith constants is to be translated to uppercase, to lowercase, or preserved as is. -fsource-case-lower is the default.
-fsymbol-case-initcap
-fsymbol-case-upper
-fsymbol-case-lower
-fsymbol-case-any
Specify valid cases for user-defined symbol names. -fsymbol-case-any is the default.
-fcase-strict-upper
Same as -fintrin-case-upper -fmatch-case-upper -fsource-case-preserve -fsymbol-case-upper. (Requires all pertinent source to be in uppercase.)
-fcase-strict-lower
Same as -fintrin-case-lower -fmatch-case-lower -fsource-case-preserve -fsymbol-case-lower. (Requires all pertinent source to be in lowercase.)
-fcase-initcap
Same as -fintrin-case-initcap -fmatch-case-initcap -fsource-case-preserve -fsymbol-case-initcap. (Requires all pertinent source to be in initial capitals, as in Print *,SqRt(Value).)
-fcase-upper
Same as -fintrin-case-any -fmatch-case-any -fsource-case-upper -fsymbol-case-any. (Maps all pertinent source to uppercase.)
-fcase-lower
Same as -fintrin-case-any -fmatch-case-any -fsource-case-lower -fsymbol-case-any. (Maps all pertinent source to lowercase.)
-fcase-preserve
Same as -fintrin-case-any -fmatch-case-any -fsource-case-preserve -fsymbol-case-any. (Preserves all case in user-defined symbols, while allowing any-case matching of intrinsics and keywords. For example, call Foo(i,I) would pass two different variables named i and I to a procedure named Foo.)
-fbadu77-intrinsics-delete
-fbadu77-intrinsics-hide
-fbadu77-intrinsics-disable
-fbadu77-intrinsics-enable
Specify status of UNIX intrinsics having inappropriate forms. -fbadu77-intrinsics-enable is the default. See Intrinsic Groups.
-ff2c-intrinsics-delete
-ff2c-intrinsics-hide
-ff2c-intrinsics-disable
-ff2c-intrinsics-enable
Specify status of f2c-specific intrinsics. -ff2c-intrinsics-enable is the default. See Intrinsic Groups.
-ff90-intrinsics-delete
-ff90-intrinsics-hide
-ff90-intrinsics-disable
-ff90-intrinsics-enable
Specify status of F90-specific intrinsics. -ff90-intrinsics-enable is the default. See Intrinsic Groups.
-fgnu-intrinsics-delete
-fgnu-intrinsics-hide
-fgnu-intrinsics-disable
-fgnu-intrinsics-enable
Specify status of Digital's COMPLEX-related intrinsics. -fgnu-intrinsics-enable is the default. See Intrinsic Groups.
-fmil-intrinsics-delete
-fmil-intrinsics-hide
-fmil-intrinsics-disable
-fmil-intrinsics-enable
Specify status of MIL-STD-1753-specific intrinsics. -fmil-intrinsics-enable is the default. See Intrinsic Groups.
-funix-intrinsics-delete
-funix-intrinsics-hide
-funix-intrinsics-disable
-funix-intrinsics-enable
Specify status of UNIX intrinsics. -funix-intrinsics-enable is the default. See Intrinsic Groups.
-fvxt-intrinsics-delete
-fvxt-intrinsics-hide
-fvxt-intrinsics-disable
-fvxt-intrinsics-enable
Specify status of VXT intrinsics. -fvxt-intrinsics-enable is the default. See Intrinsic Groups.
-ffixed-line-length-n
Set column after which characters are ignored in typical fixed-form lines in the source file, and through which spaces are assumed (as if padded to that length) after the ends of short fixed-form lines.

Popular values for n include 72 (the standard and the default), 80 (card image), and 132 (corresponds to "extended-source" options in some popular compilers). n may be none, meaning that the entire line is meaningful and that continued character constants never have implicit spaces appended to them to fill out the line. -ffixed-line-length-0 means the same thing as -ffixed-line-length-none.

See Source Form, for more information.


Node:Fortran Preprocessor, Next:Bit Operations on Floating-point Data, Previous:Suppressing Space Padding, Up:Missing Features

Fortran Preprocessor

g77 should offer a preprocessor designed specifically for Fortran to replace cpp -traditional. There are several out there worth evaluating, at least.

Such a preprocessor would recognize Hollerith constants, properly parse comments and character constants, and so on. It might also recognize, process, and thus preprocess files included via the INCLUDE directive.


Node:FPut Intrinsic (function), Next:FPutC Intrinsic (function), Previous:FloatJ Intrinsic, Up:Other Intrinsics

FPut Intrinsic (function)

FPut(C)

FPut: INTEGER(KIND=1) function.

C: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Writes the single character C in stream mode to unit 6 (by-passing normal formatted output) using getc(3). Returns 0 on success, the error code from ferror(3) otherwise.

Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable.

For information on other intrinsics with the same name: See FPut Intrinsic (subroutine).


Node:FPut Intrinsic (subroutine), Next:FPutC Intrinsic (subroutine), Previous:FNum Intrinsic, Up:Table of Intrinsic Functions

FPut Intrinsic (subroutine)

CALL FPut(C, Status)

C: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Writes the single character C in stream mode to unit 6 (by-passing normal formatted output) using putc(3). Returns in Status 0 on success, the error code from ferror(3) otherwise.

Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable.

For information on other intrinsics with the same name: See FPut Intrinsic (function).


Node:FPutC Intrinsic (function), Next:IDate Intrinsic (VXT), Previous:FPut Intrinsic (function), Up:Other Intrinsics

FPutC Intrinsic (function)

FPutC(Unit, C)

FPutC: INTEGER(KIND=1) function.

Unit: INTEGER; scalar; INTENT(IN).

C: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Writes the single character C in stream mode to unit Unit (by-passing normal formatted output) using putc(3). Returns 0 on success, the error code from ferror(3) otherwise.

Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable.

For information on other intrinsics with the same name: See FPutC Intrinsic (subroutine).


Node:FPutC Intrinsic (subroutine), Next:Fraction Intrinsic, Previous:FPut Intrinsic (subroutine), Up:Table of Intrinsic Functions

FPutC Intrinsic (subroutine)

CALL FPutC(Unit, C, Status)

Unit: INTEGER; scalar; INTENT(IN).

C: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Writes the single character Unit in stream mode to unit 6 (by-passing normal formatted output) using putc(3). Returns in C 0 on success, the error code from ferror(3) otherwise.

Stream I/O should not be mixed with normal record-oriented (formatted or unformatted) I/O on the same unit; the results are unpredictable.

For information on other intrinsics with the same name: See FPutC Intrinsic (function).


Node:Fraction Intrinsic, Next:FSeek Intrinsic, Previous:FPutC Intrinsic (subroutine), Up:Table of Intrinsic Functions

Fraction Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Fraction to use this name for an external procedure.


Node:Front End, Next:Diagnostics, Previous:Projects, Up:Top

Front End

This chapter describes some aspects of the design and implementation of the g77 front end.

To find about things that are "To Be Determined" or "To Be Done", search for the string TBD. If you want to help by working on one or more of these items, email gcc@gcc.gnu.org. If you're planning to do more than just research issues and offer comments, see http://www.gnu.org/software/contribute.html for steps you might need to take first.

  • Overview of Sources:
  • Overview of Translation Process:
  • Philosophy of Code Generation:
  • Two-pass Design:
  • Challenges Posed:
  • Transforming Statements:
  • Transforming Expressions:
  • Internal Naming Conventions:


Node:FSeek Intrinsic, Next:FStat Intrinsic (subroutine), Previous:Fraction Intrinsic, Up:Table of Intrinsic Functions

FSeek Intrinsic

CALL FSeek(Unit, Offset, Whence, ErrLab)

Unit: INTEGER; scalar; INTENT(IN).

Offset: INTEGER; scalar; INTENT(IN).

Whence: INTEGER; scalar; INTENT(IN).

ErrLab: *label, where label is the label of an executable statement; OPTIONAL.

Intrinsic groups: unix.

Description:

Attempts to move Fortran unit Unit to the specified Offset: absolute offset if Whence=0; relative to the current offset if Whence=1; relative to the end of the file if Whence=2. It branches to label ErrLab if Unit is not open or if the call otherwise fails.


Node:FStat Intrinsic (function), Next:FTell Intrinsic (subroutine), Previous:FStat Intrinsic (subroutine), Up:Table of Intrinsic Functions

FStat Intrinsic (function)

FStat(Unit, SArray)

FStat: INTEGER(KIND=1) function.

Unit: INTEGER; scalar; INTENT(IN).

SArray: INTEGER(KIND=1); DIMENSION(13); INTENT(OUT).

Intrinsic groups: unix.

Description:

Obtains data about the file open on Fortran I/O unit Unit and places them in the array SArray. The values in this array are extracted from the stat structure as returned by fstat(2) q.v., as follows:

  1. Device ID
  2. Inode number
  3. File mode
  4. Number of links
  5. Owner's uid
  6. Owner's gid
  7. ID of device containing directory entry for file (0 if not available)
  8. File size (bytes)
  9. Last access time
  10. Last modification time
  11. Last file status change time
  12. Preferred I/O block size (-1 if not available)
  13. Number of blocks allocated (-1 if not available)

Not all these elements are relevant on all systems. If an element is not relevant, it is returned as 0.

Returns 0 on success or a non-zero error code.

For information on other intrinsics with the same name: See FStat Intrinsic (subroutine).


Node:FStat Intrinsic (subroutine), Next:FStat Intrinsic (function), Previous:FSeek Intrinsic, Up:Table of Intrinsic Functions

FStat Intrinsic (subroutine)

CALL FStat(Unit, SArray, Status)

Unit: INTEGER; scalar; INTENT(IN).

SArray: INTEGER(KIND=1); DIMENSION(13); INTENT(OUT).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Obtains data about the file open on Fortran I/O unit Unit and places them in the array SArray. The values in this array are extracted from the stat structure as returned by fstat(2) q.v., as follows:

  1. Device ID
  2. Inode number
  3. File mode
  4. Number of links
  5. Owner's uid
  6. Owner's gid
  7. ID of device containing directory entry for file (0 if not available)
  8. File size (bytes)
  9. Last access time
  10. Last modification time
  11. Last file status change time
  12. Preferred I/O block size (-1 if not available)
  13. Number of blocks allocated (-1 if not available)

Not all these elements are relevant on all systems. If an element is not relevant, it is returned as 0.

If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See FStat Intrinsic (function).


Node:FTell Intrinsic (function), Next:GError Intrinsic, Previous:FTell Intrinsic (subroutine), Up:Table of Intrinsic Functions

FTell Intrinsic (function)

FTell(Unit)

FTell: INTEGER(KIND=1) function.

Unit: INTEGER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns the current offset of Fortran unit Unit (or -1 if Unit is not open).

For information on other intrinsics with the same name: See FTell Intrinsic (subroutine).


Node:FTell Intrinsic (subroutine), Next:FTell Intrinsic (function), Previous:FStat Intrinsic (function), Up:Table of Intrinsic Functions

FTell Intrinsic (subroutine)

CALL FTell(Unit, Offset)

Unit: INTEGER; scalar; INTENT(IN).

Offset: INTEGER(KIND=1); scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Sets Offset to the current offset of Fortran unit Unit (or to -1 if Unit is not open).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine.

For information on other intrinsics with the same name: See FTell Intrinsic (function).


Node:Full Support for Compiler Types, Next:Array Bounds Expressions, Previous:Popular Non-standard Types, Up:Missing Features

Full Support for Compiler Types

g77 doesn't support INTEGER, REAL, and COMPLEX equivalents for all applicable back-end-supported types (char, short int, int, long int, long long int, and long double). This means providing intrinsic support, and maybe constant support (using F90 syntax) as well, and, for most machines will result in automatic support of INTEGER*1, INTEGER*2, INTEGER*8, maybe even REAL*16, and so on.


Node:Functions and Subroutines, Next:Scope and Classes of Names, Previous:Control Statements, Up:Language

Functions and Subroutines

(The following information augments or overrides the information in Chapter 15 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 15 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

  • %VAL():
  • %REF():
  • %DESCR():
  • Generics and Specifics:
  • REAL() and AIMAG() of Complex:
  • CMPLX() of DOUBLE PRECISION:
  • MIL-STD 1753:
  • f77/f2c Intrinsics:
  • Table of Intrinsic Functions:


Node:Functions, Next:Names, Previous:Procedures, Up:Debugging and Interfacing

Functions (FUNCTION and RETURN)

g77 handles in a special way functions that return the following types:

  • CHARACTER
  • COMPLEX
  • REAL(KIND=1)

For CHARACTER, g77 implements a subroutine (a C function returning void) with two arguments prepended: __g77_result, which the caller passes as a pointer to a char array expected to hold the return value, and __g77_length, which the caller passes as an ftnlen value specifying the length of the return value as declared in the calling program. For CHARACTER*(*), the called function uses __g77_length to determine the size of the array that __g77_result points to; otherwise, it ignores that argument.

For COMPLEX, when -ff2c is in force, g77 implements a subroutine with one argument prepended: __g77_result, which the caller passes as a pointer to a variable of the type of the function. The called function writes the return value into this variable instead of returning it as a function value. When -fno-f2c is in force, g77 implements a COMPLEX function as gcc's __complex__ float or __complex__ double function (or an emulation thereof, when -femulate-complex is in effect), returning the result of the function in the same way as gcc would.

For REAL(KIND=1), when -ff2c is in force, g77 implements a function that actually returns REAL(KIND=2) (typically C's double type). When -fno-f2c is in force, REAL(KIND=1) functions return float.


Node:Funding GNU Fortran, Next:Getting Started, Previous:Funding, Up:Top

Funding GNU Fortran

James Craig Burley (craig@jcb-sc.com), the original author of g77, stopped working on it in September 1999 (He has a web page at http://world.std.com/%7Eburley.)

GNU Fortran is currently maintained by Toon Moene (toon@moene.indiv.nluug.nl), with the help of countless other volunteers.

As with other GNU software, funding is important because it can pay for needed equipment, personnel, and so on.

The FSF provides information on the best way to fund ongoing development of GNU software (such as GNU Fortran) in documents such as the "GNUS Bulletin". Email gnu@gnu.org for information on funding the FSF.

Another important way to support work on GNU Fortran is to volunteer to help out.

Email gcc@gcc.gnu.org to volunteer for this work.

However, we strongly expect that there will never be a version 0.6 of g77. Work on this compiler has stopped as of the release of GCC 3.1, except for bug fixing. g77 will be succeeded by g95 - see http://g95.sourceforge.net.

See Funding Free Software, for more information.


Node:Funding, Next:Funding GNU Fortran, Previous:Contributors, Up:Top

Funding Free Software

If you want to have more free software a few years from now, it makes sense for you to help encourage people to contribute funds for its development. The most effective approach known is to encourage commercial redistributors to donate.

Users of free software systems can boost the pace of development by encouraging for-a-fee distributors to donate part of their selling price to free software developers--the Free Software Foundation, and others.

The way to convince distributors to do this is to demand it and expect it from them. So when you compare distributors, judge them partly by how much they give to free software development. Show distributors they must compete to be the one who gives the most.

To make this approach work, you must insist on numbers that you can compare, such as, "We will donate ten dollars to the Frobnitz project for each disk sold." Don't be satisfied with a vague promise, such as "A portion of the profits are donated," since it doesn't give a basis for comparison.

Even a precise fraction "of the profits from this disk" is not very meaningful, since creative accounting and unrelated business decisions can greatly alter what fraction of the sales price counts as profit. If the price you pay is $50, ten percent of the profit is probably less than a dollar; it might be a few cents, or nothing at all.

Some redistributors do development work themselves. This is useful too; but to keep everyone honest, you need to inquire how much they do, and what kind. Some kinds of development make much more long-term difference than others. For example, maintaining a separate version of a program contributes very little; maintaining the standard version of a program for the whole community contributes much. Easy new ports contribute little, since someone else would surely do them; difficult ports such as adding a new CPU to the GNU Compiler Collection contribute more; major new features or packages contribute the most.

By establishing the idea that supporting further development is "the proper thing to do" when distributing free software for a fee, we can assure a steady flow of resources into making more free software.

Copyright © 1994 Free Software Foundation, Inc.
Verbatim copying and redistribution of this section is permitted
without royalty; alteration is not permitted.


Node:G77 and GCC, Next:Invoking G77, Previous:What is GNU Fortran?, Up:Top

Compile Fortran, C, or Other Programs

A GNU Fortran installation includes a modified version of the gcc command.

In a non-Fortran installation, gcc recognizes C, C++, and Objective-C source files.

In a GNU Fortran installation, gcc also recognizes Fortran source files and accepts Fortran-specific command-line options, plus some command-line options that are designed to cater to Fortran users but apply to other languages as well.

See Compile C; C++; Objective-C; Ada; Fortran; or Java, for information on the way different languages are handled by the GNU CC compiler (gcc).

Also provided as part of GNU Fortran is the g77 command. The g77 command is designed to make compiling and linking Fortran programs somewhat easier than when using the gcc command for these tasks. It does this by analyzing the command line somewhat and changing it appropriately before submitting it to the gcc command.

Use the -v option with g77 to see what is going on--the first line of output is the invocation of the gcc command.


Node:g77stripcard, Next:lex.c, Up:Overview of Translation Process

g77stripcard

The g77stripcard program handles removing content beyond column 72 (adjustable via a command-line option), optionally warning about that content being something other than trailing whitespace or Fortran commentary.

This program is needed because lex.c doesn't pay attention to maximum line lengths at all, to make it easier to maintain, as well as faster (for sources that don't depend on the maximum column length vis-a-vis trailing non-blank non-commentary content).

Just how this program will be run--whether automatically for old source (perhaps as the default for .f files?)--is not yet determined.

In the meantime, it might as well be implemented as a typical UNIX pipe.

It should accept a -fline-length-n option, with the default line length set to 72.

When the text it strips off the end of a line is not blank (not spaces and tabs), it should insert an additional comment line (beginning with !, so it works for both fixed-form and free-form files) containing the text, following the stripped line. The inserted comment should have a prefix of some kind, TBD, that distinguishes the comment as representing stripped text. Users could use that to sed out such lines, if they wished--it seems silly to provide a command-line option to delete information when it can be so easily filtered out by another program.

(This inserted comment should be designed to "fit in" well with whatever the Fortran community is using these days for preprocessor, translator, and other such products, like OpenMP. What that's all about, and how g77 can elegantly fit its special comment conventions into it all, is TBD as well. We don't want to reinvent the wheel here, but if there turn out to be too many conflicting conventions, we might have to invent one that looks nothing like the others, but which offers their host products a better infrastructure in which to fit and coexist peacefully.)

g77stripcard probably shouldn't do any tab expansion or other fancy stuff. People can use expand or other pre-filtering if they like. The idea here is to keep each stage quite simple, while providing excellent performance for "normal" code.

(Code with junk beyond column 73 is not really "normal", as it comes from a card-punch heritage, and will be increasingly hard for tomorrow's Fortran programmers to read.)


Node:Generics and Specifics, Next:REAL() and AIMAG() of Complex, Previous:%DESCR(), Up:Functions and Subroutines

Generics and Specifics

The ANSI FORTRAN 77 language defines generic and specific intrinsics. In short, the distinctions are:

  • Specific intrinsics have specific types for their arguments and a specific return type.
  • Generic intrinsics are treated, on a case-by-case basis in the program's source code, as one of several possible specific intrinsics.

    Typically, a generic intrinsic has a return type that is determined by the type of one or more of its arguments.

The GNU Fortran language generalizes these concepts somewhat, especially by providing intrinsic subroutines and generic intrinsics that are treated as either a specific intrinsic subroutine or a specific intrinsic function (e.g. SECOND).

However, GNU Fortran avoids generalizing this concept to the point where existing code would be accepted as meaning something possibly different than what was intended.

For example, ABS is a generic intrinsic, so all working code written using ABS of an INTEGER argument expects an INTEGER return value. Similarly, all such code expects that ABS of an INTEGER*2 argument returns an INTEGER*2 return value.

Yet, IABS is a specific intrinsic that accepts only an INTEGER(KIND=1) argument. Code that passes something other than an INTEGER(KIND=1) argument to IABS is not valid GNU Fortran code, because it is not clear what the author intended.

For example, if J is INTEGER(KIND=6), IABS(J) is not defined by the GNU Fortran language, because the programmer might have used that construct to mean any of the following, subtly different, things:

  • Convert J to INTEGER(KIND=1) first (as if IABS(INT(J)) had been written).
  • Convert the result of the intrinsic to INTEGER(KIND=1) (as if INT(ABS(J)) had been written).
  • No conversion (as if ABS(J) had been written).

The distinctions matter especially when types and values wider than INTEGER(KIND=1) (such as INTEGER(KIND=2)), or when operations performing more "arithmetic" than absolute-value, are involved.

The following sample program is not a valid GNU Fortran program, but might be accepted by other compilers. If so, the output is likely to be revealing in terms of how a given compiler treats intrinsics (that normally are specific) when they are given arguments that do not conform to their stated requirements:

      PROGRAM JCB002
C Version 1:
C Modified 1999-02-15 (Burley) to delete my email address.
C Modified 1997-05-21 (Burley) to accommodate compilers that implement
C INT(I1-I2) as INT(I1)-INT(I2) given INTEGER*2 I1,I2.
C
C Version 0:
C Written by James Craig Burley 1997-02-20.
C
C Purpose:
C Determine how compilers handle non-standard IDIM
C on INTEGER*2 operands, which presumably can be
C extrapolated into understanding how the compiler
C generally treats specific intrinsics that are passed
C arguments not of the correct types.
C
C If your compiler implements INTEGER*2 and INTEGER
C as the same type, change all INTEGER*2 below to
C INTEGER*1.
C
      INTEGER*2 I0, I4
      INTEGER I1, I2, I3
      INTEGER*2 ISMALL, ILARGE
      INTEGER*2 ITOOLG, ITWO
      INTEGER*2 ITMP
      LOGICAL L2, L3, L4
C
C Find smallest INTEGER*2 number.
C
      ISMALL=0
 10   I0 = ISMALL-1
      IF ((I0 .GE. ISMALL) .OR. (I0+1 .NE. ISMALL)) GOTO 20
      ISMALL = I0
      GOTO 10
 20   CONTINUE
C
C Find largest INTEGER*2 number.
C
      ILARGE=0
 30   I0 = ILARGE+1
      IF ((I0 .LE. ILARGE) .OR. (I0-1 .NE. ILARGE)) GOTO 40
      ILARGE = I0
      GOTO 30
 40   CONTINUE
C
C Multiplying by two adds stress to the situation.
C
      ITWO = 2
C
C Need a number that, added to -2, is too wide to fit in I*2.
C
      ITOOLG = ISMALL
C
C Use IDIM the straightforward way.
C
      I1 = IDIM (ILARGE, ISMALL) * ITWO + ITOOLG
C
C Calculate result for first interpretation.
C
      I2 = (INT (ILARGE) - INT (ISMALL)) * ITWO + ITOOLG
C
C Calculate result for second interpretation.
C
      ITMP = ILARGE - ISMALL
      I3 = (INT (ITMP)) * ITWO + ITOOLG
C
C Calculate result for third interpretation.
C
      I4 = (ILARGE - ISMALL) * ITWO + ITOOLG
C
C Print results.
C
      PRINT *, 'ILARGE=', ILARGE
      PRINT *, 'ITWO=', ITWO
      PRINT *, 'ITOOLG=', ITOOLG
      PRINT *, 'ISMALL=', ISMALL
      PRINT *, 'I1=', I1
      PRINT *, 'I2=', I2
      PRINT *, 'I3=', I3
      PRINT *, 'I4=', I4
      PRINT *
      L2 = (I1 .EQ. I2)
      L3 = (I1 .EQ. I3)
      L4 = (I1 .EQ. I4)
      IF (L2 .AND. .NOT.L3 .AND. .NOT.L4) THEN
         PRINT *, 'Interp 1: IDIM(I*2,I*2) => IDIM(INT(I*2),INT(I*2))'
         STOP
      END IF
      IF (L3 .AND. .NOT.L2 .AND. .NOT.L4) THEN
         PRINT *, 'Interp 2: IDIM(I*2,I*2) => INT(DIM(I*2,I*2))'
         STOP
      END IF
      IF (L4 .AND. .NOT.L2 .AND. .NOT.L3) THEN
         PRINT *, 'Interp 3: IDIM(I*2,I*2) => DIM(I*2,I*2)'
         STOP
      END IF
      PRINT *, 'Results need careful analysis.'
      END

No future version of the GNU Fortran language will likely permit specific intrinsic invocations with wrong-typed arguments (such as IDIM in the above example), since it has been determined that disagreements exist among many production compilers on the interpretation of such invocations. These disagreements strongly suggest that Fortran programmers, and certainly existing Fortran programs, disagree about the meaning of such invocations.

The first version of JCB002 didn't accommodate some compilers' treatment of INT(I1-I2) where I1 and I2 are INTEGER*2. In such a case, these compilers apparently convert both operands to INTEGER*4 and then do an INTEGER*4 subtraction, instead of doing an INTEGER*2 subtraction on the original values in I1 and I2.

However, the results of the careful analyses done on the outputs of programs compiled by these various compilers show that they all implement either Interp 1 or Interp 2 above.

Specifically, it is believed that the new version of JCB002 above will confirm that:

  • Digital Semiconductor ("DEC") Alpha OSF/1, HP-UX 10.0.1, AIX 3.2.5 f77 compilers all implement Interp 1.
  • IRIX 5.3 f77 compiler implements Interp 2.
  • Solaris 2.5, SunOS 4.1.3, DECstation ULTRIX 4.3, and IRIX 6.1 f77 compilers all implement Interp 3.

If you get different results than the above for the stated compilers, or have results for other compilers that might be worth adding to the above list, please let us know the details (compiler product, version, machine, results, and so on).


Node:GError Intrinsic, Next:GetArg Intrinsic, Previous:FTell Intrinsic (function), Up:Table of Intrinsic Functions

GError Intrinsic

CALL GError(Message)

Message: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Returns the system error message corresponding to the last system error (C errno).


Node:GetArg Intrinsic, Next:GetCWD Intrinsic (subroutine), Previous:GError Intrinsic, Up:Table of Intrinsic Functions

GetArg Intrinsic

CALL GetArg(Pos, Value)

Pos: INTEGER not wider than the default kind; scalar; INTENT(IN).

Value: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Sets Value to the Pos-th command-line argument (or to all blanks if there are fewer than Value command-line arguments); CALL GETARG(0, value) sets value to the name of the program (on systems that support this feature).

See IArgC Intrinsic, for information on how to get the number of arguments.


Node:GetCWD Intrinsic (function), Next:GetEnv Intrinsic, Previous:GetCWD Intrinsic (subroutine), Up:Table of Intrinsic Functions

GetCWD Intrinsic (function)

GetCWD(Name)

GetCWD: INTEGER(KIND=1) function.

Name: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Places the current working directory in Name. Returns 0 on success, otherwise a non-zero error code (ENOSYS if the system does not provide getcwd(3) or getwd(3)).

For information on other intrinsics with the same name: See GetCWD Intrinsic (subroutine).


Node:GetCWD Intrinsic (subroutine), Next:GetCWD Intrinsic (function), Previous:GetArg Intrinsic, Up:Table of Intrinsic Functions

GetCWD Intrinsic (subroutine)

CALL GetCWD(Name, Status)

Name: CHARACTER; scalar; INTENT(OUT).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Places the current working directory in Name. If the Status argument is supplied, it contains 0 success or a non-zero error code upon return (ENOSYS if the system does not provide getcwd(3) or getwd(3)).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See GetCWD Intrinsic (function).


Node:GetEnv Intrinsic, Next:GetGId Intrinsic, Previous:GetCWD Intrinsic (function), Up:Table of Intrinsic Functions

GetEnv Intrinsic

CALL GetEnv(Name, Value)

Name: CHARACTER; scalar; INTENT(IN).

Value: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Sets Value to the value of environment variable given by the value of Name ($name in shell terms) or to blanks if $name has not been set. A null character (CHAR(0)) marks the end of the name in Name--otherwise, trailing blanks in Name are ignored.


Node:GetGId Intrinsic, Next:GetLog Intrinsic, Previous:GetEnv Intrinsic, Up:Table of Intrinsic Functions

GetGId Intrinsic

GetGId()

GetGId: INTEGER(KIND=1) function.

Intrinsic groups: unix.

Description:

Returns the group id for the current process.


Node:GetLog Intrinsic, Next:GetPId Intrinsic, Previous:GetGId Intrinsic, Up:Table of Intrinsic Functions

GetLog Intrinsic

CALL GetLog(Login)

Login: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Returns the login name for the process in Login.

Caution: On some systems, the getlogin(3) function, which this intrinsic calls at run time, is either not implemented or returns a null pointer. In the latter case, this intrinsic returns blanks in Login.


Node:GetPId Intrinsic, Next:GetUId Intrinsic, Previous:GetLog Intrinsic, Up:Table of Intrinsic Functions

GetPId Intrinsic

GetPId()

GetPId: INTEGER(KIND=1) function.

Intrinsic groups: unix.

Description:

Returns the process id for the current process.


Node:Getting Started, Next:What is GNU Fortran?, Previous:Funding GNU Fortran, Up:Top

Getting Started

If you don't need help getting started reading the portions of this manual that are most important to you, you should skip this portion of the manual.

If you are new to compilers, especially Fortran compilers, or new to how compilers are structured under UNIX and UNIX-like systems, you'll want to see What is GNU Fortran?.

If you are new to GNU compilers, or have used only one GNU compiler in the past and not had to delve into how it lets you manage various versions and configurations of gcc, you should see G77 and GCC.

Everyone except experienced g77 users should see Invoking G77.

If you're acquainted with previous versions of g77, you should see News About GNU Fortran. Further, if you've actually used previous versions of g77, especially if you've written or modified Fortran code to be compiled by previous versions of g77, you should see Changes.

If you intend to write or otherwise compile code that is not already strictly conforming ANSI FORTRAN 77--and this is probably everyone--you should see Language.

If you run into trouble getting Fortran code to compile, link, run, or work properly, you might find answers if you see Debugging and Interfacing, see Collected Fortran Wisdom, and see Trouble. You might also find that the problems you are encountering are bugs in g77--see Bugs, for information on reporting them, after reading the other material.

If you need further help with g77, or with freely redistributable software in general, see Service.

If you would like to help the g77 project, see Funding GNU Fortran, for information on helping financially, and see Projects, for information on helping in other ways.

If you're generally curious about the future of g77, see Projects. If you're curious about its past, see Contributors, and see Funding GNU Fortran.

To see a few of the questions maintainers of g77 have, and that you might be able to answer, see Open Questions.


Node:GetUId Intrinsic, Next:GMTime Intrinsic, Previous:GetPId Intrinsic, Up:Table of Intrinsic Functions

GetUId Intrinsic

GetUId()

GetUId: INTEGER(KIND=1) function.

Intrinsic groups: unix.

Description:

Returns the user id for the current process.


Node:GLOBALS, Next:LINKFAIL, Previous:LEX, Up:Diagnostics

GLOBALS

Global name name defined at ... already defined...
Global name name at ... has different type...
Too many arguments passed to name at ...
Too few arguments passed to name at ...
Argument #n of name is ...

These messages all identify disagreements about the global procedure named name among different program units (usually including name itself).

Whether a particular disagreement is reported as a warning or an error can depend on the relative order of the disagreeing portions of the source file.

Disagreements between a procedure invocation and the subsequent procedure itself are, usually, diagnosed as errors when the procedure itself precedes the invocation. Other disagreements are diagnosed via warnings.

This distinction, between warnings and errors, is due primarily to the present tendency of the gcc back end to inline only those procedure invocations that are preceded by the corresponding procedure definitions. If the gcc back end is changed to inline "forward references", in which invocations precede definitions, the g77 front end will be changed to treat both orderings as errors, accordingly.

The sorts of disagreements that are diagnosed by g77 include
whether a procedure is a subroutine or function;
if it is a function, the type of the return value of the procedure;
the number of arguments the procedure accepts;
and the type of each argument.

Disagreements regarding global names among program units in a Fortran program should be fixed in the code itself. However, if that is not immediately practical, and the code has been working for some time, it is possible it will work when compiled with the -fno-globals option.

The -fno-globals option causes these diagnostics to all be warnings and disables all inlining of references to global procedures (to avoid subsequent compiler crashes and bad-code generation). Use of the -Wno-globals option as well as -fno-globals suppresses all of these diagnostics. (-Wno-globals by itself disables only the warnings, not the errors.)

After using -fno-globals to work around these problems, it is wise to stop using that option and address them by fixing the Fortran code, because such problems, while they might not actually result in bugs on some systems, indicate that the code is not as portable as it could be. In particular, the code might appear to work on a particular system, but have bugs that affect the reliability of the data without exhibiting any other outward manifestations of the bugs.


Node:GMTime Intrinsic, Next:HostNm Intrinsic (subroutine), Previous:GetUId Intrinsic, Up:Table of Intrinsic Functions

GMTime Intrinsic

CALL GMTime(STime, TArray)

STime: INTEGER(KIND=1); scalar; INTENT(IN).

TArray: INTEGER(KIND=1); DIMENSION(9); INTENT(OUT).

Intrinsic groups: unix.

Description:

Given a system time value STime, fills TArray with values extracted from it appropriate to the GMT time zone using gmtime(3).

The array elements are as follows:

  1. Seconds after the minute, range 0-59 or 0-61 to allow for leap seconds
  2. Minutes after the hour, range 0-59
  3. Hours past midnight, range 0-23
  4. Day of month, range 0-31
  5. Number of months since January, range 0-12
  6. Years since 1900
  7. Number of days since Sunday, range 0-6
  8. Days since January 1
  9. Daylight savings indicator: positive if daylight savings is in effect, zero if not, and negative if the information isn't available.


Node:GNU Free Documentation License, Next:Contributors, Previous:Copying, Up:Top

GNU Free Documentation License

Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.


Node:Gotchas (Transforming), Next:TBD (Transforming), Previous:ste.c, Up:Overview of Translation Process

Gotchas (Transforming)

This section is not about transforming "gotchas" into something else. It is about the weirder aspects of transforming Fortran, however that's defined, into a more modern, canonical form.

Multi-character Lexemes

Each lexeme carries with it a pointer to where it appears in the source.

To provide the ability for diagnostics to point to column numbers, in addition to line numbers and names, lexemes that represent more than one (significant) character in the source code need, generally, to provide pointers to where each character appears in the source.

This provides the ability to properly identify the precise location of the problem in code like

SUBROUTINE X
END
BLOCK DATA X
END

which, in fixed-form source, would result in single lexemes consisting of the strings SUBROUTINEX and BLOCKDATAX. (The problem is that X is defined twice, so a pointer to the X in the second definition, as well as a follow-up pointer to the corresponding pointer in the first, would be preferable to pointing to the beginnings of the statements.)

This need also arises when parsing (and diagnosing) FORMAT statements.

Further, it arises when diagnosing FMT= specifiers that contain constants (or partial constants, or even propagated constants!) in I/O statements, as in:

PRINT '(I2, 3HAB)', J

(A pointer to the beginning of the prematurely-terminated Hollerith constant, and/or to the close parenthese, is preferable to a pointer to the open-parenthese or the apostrophe that precedes it.)

Multi-character lexemes, which would seem to naturally include at least digit strings, alphanumeric strings, CHARACTER constants, and Hollerith constants, therefore need to provide location information on each character. (Maybe Hollerith constants don't, but it's unnecessary to except them.)

The question then arises, what about other multi-character lexemes, such as ** and //, and Fortran 90's (/, /), ::, and so on?

Turns out there's a need to identify the location of the second character of these two-character lexemes. For example, in I(/J) = K, the slash needs to be diagnosed as the problem, not the open parenthese. Similarly, it is preferable to diagnose the second slash in I = J // K rather than the first, given the implicit typing rules, which would result in the compiler disallowing the attempted concatenation of two integers. (Though, since that's more of a semantic issue, it's not that much preferable.)

Even sequences that could be parsed as digit strings could use location info, for example, to diagnose the 9 in the octal constant O'129'. (This probably will be parsed as a character string, to be consistent with the parsing of Z'129A'.)

To avoid the hassle of recording the location of the second character, while also preserving the general rule that each significant character is distinctly pointed to by the lexeme that contains it, it's best to simply not have any fixed-size lexemes larger than one character.

This new design is expected to make checking for two * lexemes in a row much easier than the old design, so this is not much of a sacrifice. It probably makes the lexer much easier to implement than it makes the parser harder.

Space-padding Lexemes

Certain lexemes need to be padded with virtual spaces when the end of the line (or file) is encountered.

This is necessary in fixed form, to handle lines that don't extend to column 72, assuming that's the line length in effect.

Bizarre Free-form Hollerith Constants

Last I checked, the Fortran 90 standard actually required the compiler to silently accept something like

FORMAT ( 1 2   Htwelve chars )

as a valid FORMAT statement specifying a twelve-character Hollerith constant.

The implication here is that, since the new lexer is a zero-feedback one, it won't know that the special case of a FORMAT statement being parsed requires apparently distinct lexemes 1 and 2 to be treated as a single lexeme.

(This is a horrible misfeature of the Fortran 90 language. It's one of many such misfeatures that almost make me want to not support them, and forge ahead with designing a new "GNU Fortran" language that has the features, but not the misfeatures, of Fortran 90, and provide utility programs to do the conversion automatically.)

So, the lexer must gather distinct chunks of decimal strings into a single lexeme in contexts where a single decimal lexeme might start a Hollerith constant.

(Which probably means it might as well do that all the time for all multi-character lexemes, even in free-form mode, leaving it to subsequent phases to pull them apart as they see fit.)

Compare the treatment of this to how

CHARACTER * 4 5 HEY

and

CHARACTER * 12 HEY

must be treated--the former must be diagnosed, due to the separation between lexemes, the latter must be accepted as a proper declaration.

Hollerith Constants

Recognizing a Hollerith constant--specifically, that an H or h after a digit string begins such a constant--requires some knowledge of context.

Hollerith constants (such as 2HAB) can appear after:

  • (
  • ,
  • =
  • +, -, /
  • *, except as noted below

Hollerith constants don't appear after:

  • CHARACTER*, which can be treated generally as any * that is the second lexeme of a statement
Confusing Function Keyword

While

REAL FUNCTION FOO ()

must be a FUNCTION statement and

REAL FUNCTION FOO (5)

must be a type-definition statement,

REAL FUNCTION FOO (names)

where names is a comma-separated list of names, can be one or the other.

The only way to disambiguate that statement (short of mandating free-form source or a short maximum length for name for external procedures) is based on the context of the statement.

In particular, the statement is known to be within an already-started program unit (but not at the outer level of the CONTAINS block), it is a type-declaration statement.

Otherwise, the statement is a FUNCTION statement, in that it begins a function program unit (external, or, within CONTAINS, nested).

Weird READ

The statement

READ (N)

is equivalent to either

READ (UNIT=(N))

or

READ (FMT=(N))

depending on which would be valid in context.

Specifically, if N is type INTEGER, READ (FMT=(N)) would not be valid, because parentheses may not be used around N, whereas they may around it in READ (UNIT=(N)).

Further, if N is type CHARACTER, the opposite is true--READ (UNIT=(N)) is not valid, but READ (FMT=(N)) is.

Strictly speaking, if anything follows

READ (N)

in the statement, whether the first lexeme after the close parenthese is a comma could be used to disambiguate the two cases, without looking at the type of N, because the comma is required for the READ (FMT=(N)) interpretation and disallowed for the READ (UNIT=(N)) interpretation.

However, in practice, many Fortran compilers allow the comma for the READ (UNIT=(N)) interpretation anyway (in that they generally allow a leading comma before an I/O list in an I/O statement), and much code takes advantage of this allowance.

(This is quite a reasonable allowance, since the juxtaposition of a comma-separated list immediately after an I/O control-specification list, which is also comma-separated, without an intervening comma, looks sufficiently "wrong" to programmers that they can't resist the itch to insert the comma. READ (I, J), K, L simply looks cleaner than READ (I, J) K, L.)

So, type-based disambiguation is needed unless strict adherence to the standard is always assumed, and we're not going to assume that.


Node:Gracefully Handle Sensible Bad Code, Next:Non-standard Conversions, Previous:Better Warnings, Up:Missing Features

Gracefully Handle Sensible Bad Code

g77 generally should continue processing for warnings and recoverable (user) errors whenever possible--that is, it shouldn't gratuitously make bad or useless code.

For example:

INTRINSIC ZABS
CALL FOO(ZABS)
END

When compiling the above with -ff2c-intrinsics-disable, g77 should indeed complain about passing ZABS, but it still should compile, instead of rejecting the entire CALL statement. (Some of this is related to improving the compiler internals to improve how statements are analyzed.)


Node:HostNm Intrinsic (function), Next:Huge Intrinsic, Previous:HostNm Intrinsic (subroutine), Up:Table of Intrinsic Functions

HostNm Intrinsic (function)

HostNm(Name)

HostNm: INTEGER(KIND=1) function.

Name: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Fills Name with the system's host name returned by gethostname(2), returning 0 on success or a non-zero error code (ENOSYS if the system does not provide gethostname(2)).

On some systems (specifically SCO) it might be necessary to link the "socket" library if you call this routine. Typically this means adding -lg2c -lsocket -lm to the g77 command line when linking the program.

For information on other intrinsics with the same name: See HostNm Intrinsic (subroutine).


Node:HostNm Intrinsic (subroutine), Next:HostNm Intrinsic (function), Previous:GMTime Intrinsic, Up:Table of Intrinsic Functions

HostNm Intrinsic (subroutine)

CALL HostNm(Name, Status)

Name: CHARACTER; scalar; INTENT(OUT).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Fills Name with the system's host name returned by gethostname(2). If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return (ENOSYS if the system does not provide gethostname(2)).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

On some systems (specifically SCO) it might be necessary to link the "socket" library if you call this routine. Typically this means adding -lg2c -lsocket -lm to the g77 command line when linking the program.

For information on other intrinsics with the same name: See HostNm Intrinsic (function).


Node:Huge Intrinsic, Next:IAbs Intrinsic, Previous:HostNm Intrinsic (function), Up:Table of Intrinsic Functions

Huge Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Huge to use this name for an external procedure.


Node:I/O, Next:Fortran 90 Features, Previous:Scope and Classes of Names, Up:Language

I/O

A dollar sign at the end of an output format specification suppresses the newline at the end of the output.

Edit descriptors in FORMAT statements may contain compile-time INTEGER constant expressions in angle brackets, such as

10    FORMAT (I<WIDTH>)

The OPEN specifier NAME= is equivalent to FILE=.

These Fortran 90 features are supported:

  • The O and Z edit descriptors are supported for I/O of integers in octal and hexadecimal formats, respectively.
  • The FILE= specifier may be omitted in an OPEN statement if STATUS='SCRATCH' is supplied. The STATUS='REPLACE' specifier is supported.


Node:IAbs Intrinsic, Next:IAChar Intrinsic, Previous:Huge Intrinsic, Up:Table of Intrinsic Functions

IAbs Intrinsic

IAbs(A)

IAbs: INTEGER(KIND=1) function.

A: INTEGER(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of ABS() that is specific to one type for A. See Abs Intrinsic.


Node:IAChar Intrinsic, Next:IAnd Intrinsic, Previous:IAbs Intrinsic, Up:Table of Intrinsic Functions

IAChar Intrinsic

IAChar(C)

IAChar: INTEGER(KIND=1) function.

C: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: f2c, f90.

Description:

Returns the code for the ASCII character in the first character position of C.

See AChar Intrinsic, for the inverse of this function.

See IChar Intrinsic, for the function corresponding to the system's native character set.


Node:IAnd Intrinsic, Next:IArgC Intrinsic, Previous:IAChar Intrinsic, Up:Table of Intrinsic Functions

IAnd Intrinsic

IAnd(I, J)

IAnd: INTEGER function, the exact type being the result of cross-promoting the types of all the arguments.

I: INTEGER; scalar; INTENT(IN).

J: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Returns value resulting from boolean AND of pair of bits in each of I and J.


Node:IArgC Intrinsic, Next:IBClr Intrinsic, Previous:IAnd Intrinsic, Up:Table of Intrinsic Functions

IArgC Intrinsic

IArgC()

IArgC: INTEGER(KIND=1) function.

Intrinsic groups: unix.

Description:

Returns the number of command-line arguments.

This count does not include the specification of the program name itself.


Node:IBClr Intrinsic, Next:IBits Intrinsic, Previous:IArgC Intrinsic, Up:Table of Intrinsic Functions

IBClr Intrinsic

IBClr(I, Pos)

IBClr: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar; INTENT(IN).

Pos: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Returns the value of I with bit Pos cleared (set to zero). See BTest Intrinsic, for information on bit positions.


Node:IBits Intrinsic, Next:IBSet Intrinsic, Previous:IBClr Intrinsic, Up:Table of Intrinsic Functions

IBits Intrinsic

IBits(I, Pos, Len)

IBits: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar; INTENT(IN).

Pos: INTEGER; scalar; INTENT(IN).

Len: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Extracts a subfield of length Len from I, starting from bit position Pos and extending left for Len bits. The result is right-justified and the remaining bits are zeroed. The value of Pos+Len must be less than or equal to the value BIT_SIZE(I). See Bit_Size Intrinsic.


Node:IBSet Intrinsic, Next:IChar Intrinsic, Previous:IBits Intrinsic, Up:Table of Intrinsic Functions

IBSet Intrinsic

IBSet(I, Pos)

IBSet: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar; INTENT(IN).

Pos: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Returns the value of I with bit Pos set (to one). See BTest Intrinsic, for information on bit positions.


Node:IChar Intrinsic, Next:IDate Intrinsic (UNIX), Previous:IBSet Intrinsic, Up:Table of Intrinsic Functions

IChar Intrinsic

IChar(C)

IChar: INTEGER(KIND=1) function.

C: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the code for the character in the first character position of C.

Because the system's native character set is used, the correspondence between character and their codes is not necessarily the same between GNU Fortran implementations.

Note that no intrinsic exists to convert a printable character string to a numerical value. For example, there is no intrinsic that, given the CHARACTER value '154', returns an INTEGER or REAL value with the value 154.

Instead, you can use internal-file I/O to do this kind of conversion. For example:

INTEGER VALUE
CHARACTER*10 STRING
STRING = '154'
READ (STRING, '(I10)'), VALUE
PRINT *, VALUE
END

The above program, when run, prints:

 154

See Char Intrinsic, for the inverse of the ICHAR function.

See IAChar Intrinsic, for the function corresponding to the ASCII character set.


Node:IDate Intrinsic (UNIX), Next:IDiM Intrinsic, Previous:IChar Intrinsic, Up:Table of Intrinsic Functions

IDate Intrinsic (UNIX)

CALL IDate(TArray)

TArray: INTEGER(KIND=1); DIMENSION(3); INTENT(OUT).

Intrinsic groups: unix.

Description:

Fills TArray with the numerical values at the current local time of day, month (in the range 1-12), and year in elements 1, 2, and 3, respectively. The year has four significant digits.

Programs making use of this intrinsic might not be Year 10000 (Y10K) compliant. For example, the date might appear, to such programs, to wrap around (change from a larger value to a smaller one) as of the Year 10000.

For information on other intrinsics with the same name: See IDate Intrinsic (VXT).


Node:IDate Intrinsic (VXT), Next:IIAbs Intrinsic, Previous:FPutC Intrinsic (function), Up:Other Intrinsics

IDate Intrinsic (VXT)

CALL IDate(M, D, Y)

M: INTEGER(KIND=1); scalar; INTENT(OUT).

D: INTEGER(KIND=1); scalar; INTENT(OUT).

Y: INTEGER(KIND=1); scalar; INTENT(OUT).

Intrinsic groups: vxt.

Description:

Returns the numerical values of the current local time. The month (in the range 1-12) is returned in M, the day (in the range 1-7) in D, and the year in Y (in the range 0-99).

This intrinsic is not recommended, due to the year 2000 approaching. Therefore, programs making use of this intrinsic might not be Year 2000 (Y2K) compliant. For example, the date might appear, to such programs, to wrap around (change from a larger value to a smaller one) as of the Year 2000.

See IDate Intrinsic (UNIX), for information on obtaining more digits for the current date.

For information on other intrinsics with the same name: See IDate Intrinsic (UNIX).


Node:IDiM Intrinsic, Next:IDInt Intrinsic, Previous:IDate Intrinsic (UNIX), Up:Table of Intrinsic Functions

IDiM Intrinsic

IDiM(X, Y)

IDiM: INTEGER(KIND=1) function.

X: INTEGER(KIND=1); scalar; INTENT(IN).

Y: INTEGER(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of DIM() that is specific to one type for X and Y. See DiM Intrinsic.


Node:IDInt Intrinsic, Next:IDNInt Intrinsic, Previous:IDiM Intrinsic, Up:Table of Intrinsic Functions

IDInt Intrinsic

IDInt(A)

IDInt: INTEGER(KIND=1) function.

A: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of INT() that is specific to one type for A. See Int Intrinsic.


Node:IDNInt Intrinsic, Next:IEOr Intrinsic, Previous:IDInt Intrinsic, Up:Table of Intrinsic Functions

IDNInt Intrinsic

IDNInt(A)

IDNInt: INTEGER(KIND=1) function.

A: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of NINT() that is specific to one type for A. See NInt Intrinsic.


Node:IEOr Intrinsic, Next:IErrNo Intrinsic, Previous:IDNInt Intrinsic, Up:Table of Intrinsic Functions

IEOr Intrinsic

IEOr(I, J)

IEOr: INTEGER function, the exact type being the result of cross-promoting the types of all the arguments.

I: INTEGER; scalar; INTENT(IN).

J: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Returns value resulting from boolean exclusive-OR of pair of bits in each of I and J.


Node:IErrNo Intrinsic, Next:IFix Intrinsic, Previous:IEOr Intrinsic, Up:Table of Intrinsic Functions

IErrNo Intrinsic

IErrNo()

IErrNo: INTEGER(KIND=1) function.

Intrinsic groups: unix.

Description:

Returns the last system error number (corresponding to the C errno).


Node:IFix Intrinsic, Next:Imag Intrinsic, Previous:IErrNo Intrinsic, Up:Table of Intrinsic Functions

IFix Intrinsic

IFix(A)

IFix: INTEGER(KIND=1) function.

A: REAL(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of INT() that is specific to one type for A. See Int Intrinsic.


Node:IIAbs Intrinsic, Next:IIAnd Intrinsic, Previous:IDate Intrinsic (VXT), Up:Other Intrinsics

IIAbs Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIAbs to use this name for an external procedure.


Node:IIAnd Intrinsic, Next:IIBClr Intrinsic, Previous:IIAbs Intrinsic, Up:Other Intrinsics

IIAnd Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIAnd to use this name for an external procedure.


Node:IIBClr Intrinsic, Next:IIBits Intrinsic, Previous:IIAnd Intrinsic, Up:Other Intrinsics

IIBClr Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIBClr to use this name for an external procedure.


Node:IIBits Intrinsic, Next:IIBSet Intrinsic, Previous:IIBClr Intrinsic, Up:Other Intrinsics

IIBits Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIBits to use this name for an external procedure.


Node:IIBSet Intrinsic, Next:IIDiM Intrinsic, Previous:IIBits Intrinsic, Up:Other Intrinsics

IIBSet Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIBSet to use this name for an external procedure.


Node:IIDiM Intrinsic, Next:IIDInt Intrinsic, Previous:IIBSet Intrinsic, Up:Other Intrinsics

IIDiM Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIDiM to use this name for an external procedure.


Node:IIDInt Intrinsic, Next:IIDNnt Intrinsic, Previous:IIDiM Intrinsic, Up:Other Intrinsics

IIDInt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIDInt to use this name for an external procedure.


Node:IIDNnt Intrinsic, Next:IIEOr Intrinsic, Previous:IIDInt Intrinsic, Up:Other Intrinsics

IIDNnt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIDNnt to use this name for an external procedure.


Node:IIEOr Intrinsic, Next:IIFix Intrinsic, Previous:IIDNnt Intrinsic, Up:Other Intrinsics

IIEOr Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIEOr to use this name for an external procedure.


Node:IIFix Intrinsic, Next:IInt Intrinsic, Previous:IIEOr Intrinsic, Up:Other Intrinsics

IIFix Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIFix to use this name for an external procedure.


Node:IInt Intrinsic, Next:IIOr Intrinsic, Previous:IIFix Intrinsic, Up:Other Intrinsics

IInt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IInt to use this name for an external procedure.


Node:IIOr Intrinsic, Next:IIQint Intrinsic, Previous:IInt Intrinsic, Up:Other Intrinsics

IIOr Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIOr to use this name for an external procedure.


Node:IIQint Intrinsic, Next:IIQNnt Intrinsic, Previous:IIOr Intrinsic, Up:Other Intrinsics

IIQint Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIQint to use this name for an external procedure.


Node:IIQNnt Intrinsic, Next:IIShftC Intrinsic, Previous:IIQint Intrinsic, Up:Other Intrinsics

IIQNnt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIQNnt to use this name for an external procedure.


Node:IIShftC Intrinsic, Next:IISign Intrinsic, Previous:IIQNnt Intrinsic, Up:Other Intrinsics

IIShftC Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IIShftC to use this name for an external procedure.


Node:IISign Intrinsic, Next:IMax0 Intrinsic, Previous:IIShftC Intrinsic, Up:Other Intrinsics

IISign Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IISign to use this name for an external procedure.


Node:Imag Intrinsic, Next:ImagPart Intrinsic, Previous:IFix Intrinsic, Up:Table of Intrinsic Functions

Imag Intrinsic

Imag(Z)

Imag: REAL function, the KIND= value of the type being that of argument Z.

Z: COMPLEX; scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

The imaginary part of Z is returned, without conversion.

Note: The way to do this in standard Fortran 90 is AIMAG(Z). However, when, for example, Z is DOUBLE COMPLEX, AIMAG(Z) means something different for some compilers that are not true Fortran 90 compilers but offer some extensions standardized by Fortran 90 (such as the DOUBLE COMPLEX type, also known as COMPLEX(KIND=2)).

The advantage of IMAG() is that, while not necessarily more or less portable than AIMAG(), it is more likely to cause a compiler that doesn't support it to produce a diagnostic than generate incorrect code.

See REAL() and AIMAG() of Complex, for more information.


Node:ImagPart Intrinsic, Next:Index Intrinsic, Previous:Imag Intrinsic, Up:Table of Intrinsic Functions

ImagPart Intrinsic

ImagPart(Z)

ImagPart: REAL function, the KIND= value of the type being that of argument Z.

Z: COMPLEX; scalar; INTENT(IN).

Intrinsic groups: gnu.

Description:

The imaginary part of Z is returned, without conversion.

Note: The way to do this in standard Fortran 90 is AIMAG(Z). However, when, for example, Z is DOUBLE COMPLEX, AIMAG(Z) means something different for some compilers that are not true Fortran 90 compilers but offer some extensions standardized by Fortran 90 (such as the DOUBLE COMPLEX type, also known as COMPLEX(KIND=2)).

The advantage of IMAGPART() is that, while not necessarily more or less portable than AIMAG(), it is more likely to cause a compiler that doesn't support it to produce a diagnostic than generate incorrect code.

See REAL() and AIMAG() of Complex, for more information.


Node:IMax0 Intrinsic, Next:IMax1 Intrinsic, Previous:IISign Intrinsic, Up:Other Intrinsics

IMax0 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IMax0 to use this name for an external procedure.


Node:IMax1 Intrinsic, Next:IMin0 Intrinsic, Previous:IMax0 Intrinsic, Up:Other Intrinsics

IMax1 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IMax1 to use this name for an external procedure.


Node:IMin0 Intrinsic, Next:IMin1 Intrinsic, Previous:IMax1 Intrinsic, Up:Other Intrinsics

IMin0 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IMin0 to use this name for an external procedure.


Node:IMin1 Intrinsic, Next:IMod Intrinsic, Previous:IMin0 Intrinsic, Up:Other Intrinsics

IMin1 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IMin1 to use this name for an external procedure.


Node:IMod Intrinsic, Next:INInt Intrinsic, Previous:IMin1 Intrinsic, Up:Other Intrinsics

IMod Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IMod to use this name for an external procedure.


Node:INCLUDE, Next:Cpp-style directives, Previous:Order, Up:Characters Lines Sequence

Including Source Text

Additional source text may be included in the processing of the source file via the INCLUDE directive:

INCLUDE filename

The source text to be included is identified by filename, which is a literal GNU Fortran character constant. The meaning and interpretation of filename depends on the implementation, but typically is a filename.

(g77 treats it as a filename that it searches for in the current directory and/or directories specified via the -I command-line option.)

The effect of the INCLUDE directive is as if the included text directly replaced the directive in the source file prior to interpretation of the program. Included text may itself use INCLUDE. The depth of nested INCLUDE references depends on the implementation, but typically is a positive integer.

This virtual replacement treats the statements and INCLUDE directives in the included text as syntactically distinct from those in the including text.

Therefore, the first non-comment line of the included text must not be a continuation line. The included text must therefore have, after the non-comment lines, either an initial line (statement), an INCLUDE directive, or nothing (the end of the included text).

Similarly, the including text may end the INCLUDE directive with a semicolon or the end of the line, but it cannot follow an INCLUDE directive at the end of its line with a continuation line. Thus, the last statement in an included text may not be continued.

Any statements between two INCLUDE directives on the same line are treated as if they appeared in between the respective included texts. For example:

INCLUDE 'A'; PRINT *, 'B'; INCLUDE 'C'; END PROGRAM

If the text included by INCLUDE 'A' constitutes a PRINT *, 'A' statement and the text included by INCLUDE 'C' constitutes a PRINT *, 'C' statement, then the output of the above sample program would be

A
B
C

(with suitable allowances for how an implementation defines its handling of output).

Included text must not include itself directly or indirectly, regardless of whether the filename used to reference the text is the same.

Note that INCLUDE is not a statement. As such, it is neither a non-executable or executable statement. However, if the text it includes constitutes one or more executable statements, then the placement of INCLUDE is subject to effectively the same restrictions as those on executable statements.

An INCLUDE directive may be continued across multiple lines as if it were a statement. This permits long names to be used for filename.


Node:Inconsistent Calling Sequences, Previous:Floating-point precision, Up:Working Programs

Inconsistent Calling Sequences

Code containing inconsistent calling sequences in the same file is normally rejected--see GLOBALS. (Use, say, ftnchek to ensure consistency across source files. See Generating Skeletons and Prototypes with f2c.)

Mysterious errors, which may appear to be code generation problems, can appear specifically on the x86 architecture with some such inconsistencies. On x86 hardware, floating-point return values of functions are placed on the floating-point unit's register stack, not the normal stack. Thus calling a REAL or DOUBLE PRECISION FUNCTION as some other sort of procedure, or vice versa, scrambles the floating-point stack. This may break unrelated code executed later. Similarly if, say, external C routines are written incorrectly.


Node:Increasing Precision/Range, Next:Enabling Debug Lines, Previous:Support for Threads, Up:Missing Features

Increasing Precision/Range

Some compilers, such as f2c, have an option (-r8, -qrealsize=8 or similar) that provides automatic treatment of REAL entities such that they have twice the storage size, and a corresponding increase in the range and precision, of what would normally be the REAL(KIND=1) (default REAL) type. (This affects COMPLEX the same way.)

They also typically offer another option (-i8) to increase INTEGER entities so they are twice as large (with roughly twice as much range).

(There are potential pitfalls in using these options.)

g77 does not yet offer any option that performs these kinds of transformations. Part of the problem is the lack of detailed specifications regarding exactly how these options affect the interpretation of constants, intrinsics, and so on.

Until g77 addresses this need, programmers could improve the portability of their code by modifying it to not require compile-time options to produce correct results. Some free tools are available which may help, specifically in Toolpack (which one would expect to be sound) and the fortran section of the Netlib repository.

Use of preprocessors can provide a fairly portable means to work around the lack of widely portable methods in the Fortran language itself (though increasing acceptance of Fortran 90 would alleviate this problem).


Node:Index, Previous:Diagnostics, Up:Top

Index

  • !: LEX, Exclamation Point, Trailing Comment, Character Set, Statements Comments Lines
  • ": Character Set
  • #: Cpp-style directives, Character Set
  • #define: Overall Options
  • #if: Overall Options
  • #include: Overall Options
  • #include directive: Bug Reporting
  • $: Dollar Signs
  • %: Character Set
  • %DESCR() construct: %DESCR()
  • %LOC() construct: %LOC()
  • %REF() construct: %REF()
  • %VAL() construct: %VAL()
  • &: Character Set
  • *: LEX
  • *n notation: Compiler Types, Star Notation
  • --driver option: Changes, News
  • -falias-check option: Aliasing Assumed To Work, Code Gen Options
  • -fargument-alias option: Aliasing Assumed To Work, Code Gen Options
  • -fargument-noalias option: Aliasing Assumed To Work, Code Gen Options
  • -fbadu77-intrinsics-delete option: Fortran Dialect Options
  • -fbadu77-intrinsics-disable option: Fortran Dialect Options
  • -fbadu77-intrinsics-enable option: Fortran Dialect Options
  • -fbadu77-intrinsics-hide option: Fortran Dialect Options
  • -fbounds-check option: Code Gen Options
  • -fcaller-saves option: Optimize Options
  • -fcase-initcap option: Fortran Dialect Options
  • -fcase-lower option: Fortran Dialect Options
  • -fcase-preserve option: Fortran Dialect Options
  • -fcase-strict-lower option: Fortran Dialect Options
  • -fcase-strict-upper option: Fortran Dialect Options
  • -fcase-upper option: Fortran Dialect Options
  • -fdelayed-branch option: Optimize Options
  • -fdollar-ok option: Fortran Dialect Options
  • -femulate-complex option: Code Gen Options
  • -fexpensive-optimizations option: Optimize Options
  • -ff2c-intrinsics-delete option: Fortran Dialect Options
  • -ff2c-intrinsics-disable option: Fortran Dialect Options
  • -ff2c-intrinsics-enable option: Fortran Dialect Options
  • -ff2c-intrinsics-hide option: Fortran Dialect Options
  • -ff2c-library option: Code Gen Options
  • -ff66 option: Shorthand Options
  • -ff77 option: Shorthand Options
  • -ff90: Fortran 90 Features
  • -ff90 option: Fortran Dialect Options
  • -ff90-intrinsics-delete option: Fortran Dialect Options
  • -ff90-intrinsics-disable option: Fortran Dialect Options
  • -ff90-intrinsics-enable option: Fortran Dialect Options
  • -ff90-intrinsics-hide option: Fortran Dialect Options
  • -ffast-math option: Optimize Options
  • -ffixed-line-length-n option: Fortran Dialect Options
  • -fflatten-arrays option: Code Gen Options
  • -ffloat-store option: Optimize Options
  • -fforce-addr option: Optimize Options
  • -fforce-mem option: Optimize Options
  • -ffortran-bounds-check option: Code Gen Options
  • -ffree-form: Fortran 90 Features
  • -ffree-form option: Fortran Dialect Options
  • -fgnu-intrinsics-delete option: Fortran Dialect Options
  • -fgnu-intrinsics-disable option: Fortran Dialect Options
  • -fgnu-intrinsics-enable option: Fortran Dialect Options
  • -fgnu-intrinsics-hide option: Fortran Dialect Options
  • -fgroup-intrinsics-hide option: Overly Convenient Options
  • -finit-local-zero option: Overly Convenient Options, Code Gen Options
  • -fintrin-case-any option: Fortran Dialect Options
  • -fintrin-case-initcap option: Fortran Dialect Options
  • -fintrin-case-lower option: Fortran Dialect Options
  • -fintrin-case-upper option: Fortran Dialect Options
  • -fmatch-case-any option: Fortran Dialect Options
  • -fmatch-case-initcap option: Fortran Dialect Options
  • -fmatch-case-lower option: Fortran Dialect Options
  • -fmatch-case-upper option: Fortran Dialect Options
  • -fmil-intrinsics-delete option: Fortran Dialect Options
  • -fmil-intrinsics-disable option: Fortran Dialect Options
  • -fmil-intrinsics-enable option: Fortran Dialect Options
  • -fmil-intrinsics-hide option: Fortran Dialect Options
  • -fno-argument-noalias-global option: Aliasing Assumed To Work, Code Gen Options
  • -fno-automatic option: Overly Convenient Options, Code Gen Options
  • -fno-backslash option: Fortran Dialect Options
  • -fno-common option: Code Gen Options
  • -fno-f2c option: Avoid f2c Compatibility, Code Gen Options
  • -fno-f77 option: Shorthand Options
  • -fno-fixed-form option: Fortran Dialect Options
  • -fno-globals option: Code Gen Options
  • -fno-ident option: Code Gen Options
  • -fno-inline option: Optimize Options
  • -fno-move-all-movables option: Optimize Options
  • -fno-reduce-all-givs option: Optimize Options
  • -fno-rerun-loop-opt option: Optimize Options
  • -fno-second-underscore: f2c Skeletons and Prototypes
  • -fno-second-underscore option: Names, Code Gen Options
  • -fno-silent option: Overall Options
  • -fno-trapping-math option: Optimize Options
  • -fno-ugly option: Shorthand Options
  • -fno-ugly-args option: Fortran Dialect Options
  • -fno-ugly-init option: Fortran Dialect Options
  • -fno-underscoring option: Names, Code Gen Options
  • -fonetrip option: Fortran Dialect Options
  • -fpack-struct option: Code Gen Options
  • -fpcc-struct-return option: Code Gen Options
  • -fpedantic option: Warning Options
  • -fPIC option: News
  • -freg-struct-return option: Code Gen Options
  • -frerun-cse-after-loop option: Optimize Options
  • -fschedule-insns option: Optimize Options
  • -fschedule-insns2 option: Optimize Options
  • -fset-g77-defaults option: Overall Options
  • -fshort-double option: Code Gen Options
  • -fsource-case-lower option: Fortran Dialect Options
  • -fsource-case-preserve option: Fortran Dialect Options
  • -fsource-case-upper option: Fortran Dialect Options
  • -fstrength-reduce option: Optimize Options
  • -fsymbol-case-any option: Fortran Dialect Options
  • -fsymbol-case-initcap option: Fortran Dialect Options
  • -fsymbol-case-lower option: Fortran Dialect Options
  • -fsymbol-case-upper option: Fortran Dialect Options
  • -fsyntax-only option: Warning Options
  • -ftypeless-boz option: Fortran Dialect Options
  • -fugly option: Shorthand Options
  • -fugly-assign option: Fortran Dialect Options
  • -fugly-assumed option: Fortran Dialect Options
  • -fugly-comma option: Fortran Dialect Options
  • -fugly-complex option: Fortran Dialect Options
  • -fugly-logint option: Fortran Dialect Options
  • -funix-intrinsics-delete option: Fortran Dialect Options
  • -funix-intrinsics-disable option: Fortran Dialect Options
  • -funix-intrinsics-enable option: Fortran Dialect Options
  • -funix-intrinsics-hide option: Fortran Dialect Options
  • -funroll-all-loops option: Optimize Options
  • -funroll-loops option: Optimize Options
  • -funsafe-math-optimizations option: Optimize Options
  • -fversion option: Overall Options
  • -fvxt option: Fortran Dialect Options
  • -fvxt-intrinsics-delete option: Fortran Dialect Options
  • -fvxt-intrinsics-disable option: Fortran Dialect Options
  • -fvxt-intrinsics-enable option: Fortran Dialect Options
  • -fvxt-intrinsics-hide option: Fortran Dialect Options
  • -fzeros option: Code Gen Options
  • -g option: Debugging Options
  • -I- option: Directory Options
  • -i8: Increasing Precision/Range
  • -Idir option: Directory Options
  • -malign-double: Changes, News
  • -malign-double option: Aligned Data, Optimize Options
  • -Nl option: Compiler Limits
  • -Nx option: Compiler Limits
  • -O2: News
  • -pedantic option: Warning Options
  • -pedantic-errors option: Warning Options
  • -qrealsize=8: Increasing Precision/Range
  • -r8: Increasing Precision/Range
  • -u option: Warning Options
  • -v option: G77 and GCC
  • -W option: Warning Options
  • -w option: Warning Options
  • -Waggregate-return option: Warning Options
  • -Wall option: Warning Options
  • -Wcomment option: Warning Options
  • -Wconversion option: Warning Options
  • -Werror option: Warning Options
  • -Wformat option: Warning Options
  • -Wid-clash-len option: Warning Options
  • -Wimplicit option: Warning Options
  • -Wlarger-than-len option: Warning Options
  • -Wno-globals option: Warning Options
  • -Wparentheses option: Warning Options
  • -Wredundant-decls option: Warning Options
  • -Wshadow option: Warning Options
  • -Wsurprising option: Warning Options
  • -Wswitch option: Warning Options
  • -Wtraditional option: Warning Options
  • -Wuninitialized option: Warning Options
  • -Wunused option: Warning Options
  • -x f77-cpp-input option: LEX
  • .EQV., with integer operands: Equivalence Versus Equality
  • .F filename suffix: Overall Options
  • .f filename suffix: Overall Options
  • .FOR filename suffix: Overall Options
  • .for filename suffix: Overall Options
  • .FPP filename suffix: Overall Options
  • .fpp filename suffix: Overall Options
  • .gdbinit: Main Program Unit
  • .r filename suffix: Overall Options
  • /*: Trailing Comment, Overall Options
  • /WARNINGS=DECLARATIONS switch: Warning Options
  • 80-bit spills: Floating-point Errors
  • ;: Character Set, Statements Comments Lines
  • <: Character Set
  • <> edit descriptor: I/O
  • >: Character Set
  • ?: Character Set
  • \: Character Set
  • _: Character Set
  • Abort intrinsic: Abort Intrinsic
  • Abs intrinsic: Abs Intrinsic
  • ACCEPT statement: TYPE and ACCEPT I/O Statements
  • Access intrinsic: Access Intrinsic
  • AChar intrinsic: AChar Intrinsic
  • ACos intrinsic: ACos Intrinsic
  • ACosD intrinsic: ACosD Intrinsic
  • adding options: Adding Options
  • adjustable arrays: Adjustable Arrays
  • AdjustL intrinsic: AdjustL Intrinsic
  • AdjustR intrinsic: AdjustR Intrinsic
  • AImag intrinsic: AImag Intrinsic
  • AImag intrinsic: REAL() and AIMAG() of Complex
  • AIMax0 intrinsic: AIMax0 Intrinsic
  • AIMin0 intrinsic: AIMin0 Intrinsic
  • AInt intrinsic: AInt Intrinsic
  • AJMax0 intrinsic: AJMax0 Intrinsic
  • AJMin0 intrinsic: AJMin0 Intrinsic
  • Alarm intrinsic: Alarm Intrinsic
  • aliasing: Known Bugs, Aliasing Assumed To Work
  • aligned data: Aligned Data
  • aligned stack: Aligned Data
  • alignment: Aligned Data, Changes, News
  • alignment testing: Aligned Data
  • All intrinsic: All Intrinsic
  • all warnings: Warning Options
  • Allocated intrinsic: Allocated Intrinsic
  • ALog intrinsic: ALog Intrinsic
  • ALog10 intrinsic: ALog10 Intrinsic
  • Alpha, support: Known Bugs
  • alternate entry points: Alternate Entry Points
  • alternate returns: Alternate Returns
  • ALWAYS_FLUSH: Output Assumed To Flush
  • AMax0 intrinsic: AMax0 Intrinsic
  • AMax1 intrinsic: AMax1 Intrinsic
  • AMin0 intrinsic: AMin0 Intrinsic
  • AMin1 intrinsic: AMin1 Intrinsic
  • AMod intrinsic: AMod Intrinsic
  • ampersand: Character Set
  • ampersand continuation line: Ampersands
  • And intrinsic: Bit Operations on Floating-point Data
  • And intrinsic: And Intrinsic
  • ANInt intrinsic: ANInt Intrinsic
  • ANS carriage control: OPEN CLOSE and INQUIRE Keywords
  • ANSI FORTRAN 77 standard: Language
  • ANSI FORTRAN 77 support: Standard Support
  • anti-aliasing: Aliasing Assumed To Work
  • Any intrinsic: Any Intrinsic
  • arguments, null: Ugly Null Arguments
  • arguments, omitting: Ugly Null Arguments
  • arguments, unused: Unused Arguments, Warning Options
  • array bounds checking: Code Gen Options
  • array bounds, adjustable: Array Bounds Expressions
  • array elements, in adjustable array bounds: Array Bounds Expressions
  • array ordering: Arrays
  • array performance: Code Gen Options
  • array size: Array Size
  • arrays: Arrays
  • arrays, adjustable: Adjustable Arrays
  • arrays, assumed-size: Ugly Assumed-Size Arrays
  • arrays, automatic: Large Automatic Arrays, Stack Overflow, Overly Convenient Options, Adjustable Arrays
  • arrays, dimensioning: Adjustable Arrays, Array Size
  • arrays, flattening: Code Gen Options
  • as command: What is GNU Fortran?
  • ASin intrinsic: ASin Intrinsic
  • ASinD intrinsic: ASinD Intrinsic
  • assembler: What is GNU Fortran?
  • assembly code: What is GNU Fortran?
  • assembly code, invalid: Bug Criteria
  • ASSIGN statement: Assigned Statement Labels, Ugly Assigned Labels
  • assigned labels: Ugly Assigned Labels
  • assigned statement labels: Assigned Statement Labels
  • Associated intrinsic: Associated Intrinsic
  • association, storage: Aliasing Assumed To Work
  • assumed-size arrays: Ugly Assumed-Size Arrays
  • asterisk: LEX
  • ATan intrinsic: ATan Intrinsic
  • ATan2 intrinsic: ATan2 Intrinsic
  • ATan2D intrinsic: ATan2D Intrinsic
  • ATanD intrinsic: ATanD Intrinsic
  • automatic arrays: Large Automatic Arrays, Stack Overflow, Overly Convenient Options, Adjustable Arrays
  • AUTOMATIC statement: AUTOMATIC Statement
  • automatic variables: AUTOMATIC Statement
  • back end, gcc: Philosophy of Code Generation, What is GNU Fortran?
  • backslash: Backslash in Constants, Character Set, Fortran Dialect Options
  • backtrace for bug reports: Bug Reporting
  • badu77 intrinsics: Fortran Dialect Options
  • badu77 intrinsics group: Intrinsic Groups
  • basic concepts: What is GNU Fortran?
  • Bear-poking: Philosophy of Code Generation
  • beginners: Getting Started
  • BesJ0 intrinsic: BesJ0 Intrinsic
  • BesJ1 intrinsic: BesJ1 Intrinsic
  • BesJN intrinsic: BesJN Intrinsic
  • BesY0 intrinsic: BesY0 Intrinsic
  • BesY1 intrinsic: BesY1 Intrinsic
  • BesYN intrinsic: BesYN Intrinsic
  • binary data: Portable Unformatted Files
  • Bit_Size intrinsic: Bit_Size Intrinsic
  • BITest intrinsic: BITest Intrinsic
  • BJTest intrinsic: BJTest Intrinsic
  • blank: Lines, Character Set
  • block data: Multiple Definitions of External Names
  • block data and libraries: Block Data and Libraries
  • BLOCK DATA statement: Multiple Definitions of External Names, Block Data and Libraries
  • bounds checking: Code Gen Options
  • BTest intrinsic: BTest Intrinsic
  • bug criteria: Bug Criteria
  • bug report mailing lists: Bug Lists
  • bugs: Bugs
  • bugs, finding: What is GNU Fortran?
  • bugs, known: Trouble
  • bus error: Strange Behavior at Run Time, NeXTStep Problems
  • but-bugs: But-bugs
  • byte ordering: Portable Unformatted Files
  • C library: Strange Behavior at Run Time
  • C preprocessor: Overall Options
  • C routines calling Fortran: Debugging and Interfacing
  • C++: C++ Considerations
  • C++, linking with: Interoperating with C and C++
  • C, linking with: Interoperating with C and C++
  • CAbs intrinsic: CAbs Intrinsic
  • calling C routines: Debugging and Interfacing
  • card image: Fortran Dialect Options
  • carriage control: OPEN CLOSE and INQUIRE Keywords
  • carriage returns: Carriage Returns
  • case sensitivity: Case Sensitivity
  • cc1 program: What is GNU Fortran?
  • cc1plus program: What is GNU Fortran?
  • CCos intrinsic: CCos Intrinsic
  • CDAbs intrinsic: CDAbs Intrinsic
  • CDCos intrinsic: CDCos Intrinsic
  • CDExp intrinsic: CDExp Intrinsic
  • CDLog intrinsic: CDLog Intrinsic
  • CDSin intrinsic: CDSin Intrinsic
  • CDSqRt intrinsic: CDSqRt Intrinsic
  • Ceiling intrinsic: Ceiling Intrinsic
  • CExp intrinsic: CExp Intrinsic
  • cfortran.h: C Interfacing Tools
  • changes, user-visible: Changes
  • Char intrinsic: Char Intrinsic
  • character assignments: Fortran 90 Features
  • character constants: Character and Hollerith Constants, Ugly Conversion of Initializers, Double Quote Meaning, Fortran Dialect Options
  • character set: Fortran Dialect Options
  • CHARACTER*(*): Arbitrary Concatenation
  • CHARACTER, null: Character Type
  • character-variable length: Character-variable Length
  • characters: Character Set
  • characters, comma: Ugly Null Arguments
  • characters, comment: LEX, Exclamation Point, Trailing Comment, Statements Comments Lines
  • characters, continuation: LEX, Exclamation Point, Statements Comments Lines
  • ChDir intrinsic: ChDir Intrinsic (function), ChDir Intrinsic (subroutine)
  • checking subscripts: Code Gen Options
  • checking substrings: Code Gen Options
  • checks, of internal consistency: Overall Options
  • ChMod intrinsic: ChMod Intrinsic (function), ChMod Intrinsic (subroutine)
  • CLog intrinsic: CLog Intrinsic
  • close angle: Character Set
  • close bracket: Character Set
  • CLOSE statement: OPEN CLOSE and INQUIRE Keywords
  • Cmplx intrinsic: Cmplx Intrinsic
  • Cmplx intrinsic: CMPLX() of DOUBLE PRECISION
  • code generation, conventions: Code Gen Options
  • code generation, improving: Better Optimization
  • code generator: Philosophy of Code Generation, What is GNU Fortran?
  • code, assembly: What is GNU Fortran?
  • code, displaying main source: Known Bugs
  • code, in-line: What is GNU Fortran?
  • code, legacy: Collected Fortran Wisdom
  • code, machine: What is GNU Fortran?
  • code, source: Case Sensitivity, Source Form, Lines, What is GNU Fortran?
  • code, user: Cannot Link Fortran Programs
  • code, writing: Collected Fortran Wisdom
  • column-major ordering: Arrays
  • columns 73 through 80: Better Source Model
  • comma, trailing: Ugly Null Arguments
  • command options: Invoking G77
  • commands, as: What is GNU Fortran?
  • commands, g77: G77 and GCC, What is GNU Fortran?
  • commands, gcc: G77 and GCC, What is GNU Fortran?
  • commands, gdb: What is GNU Fortran?
  • commands, ld: What is GNU Fortran?
  • comment: LEX, Trailing Comment, Statements Comments Lines
  • comment character: Exclamation Point
  • comment line, debug: Enabling Debug Lines, Debug Line
  • common blocks: Mangling of Names, Known Bugs, Common Blocks
  • common blocks, large: Large Common Blocks
  • COMMON layout: Aligned Data
  • COMMON statement: Multiple Definitions of External Names, Common Blocks
  • comparing logical expressions: Equivalence Versus Equality
  • compatibility, f2c: Avoid f2c Compatibility
  • compatibility, f2c: Block Data and Libraries
  • compatibility, f2c: Code Gen Options
  • compatibility, f2c: Shorthand Options, Overall Options
  • compatibility, f77: Shorthand Options
  • compatibility, FORTRAN 66: Fortran Dialect Options, Shorthand Options
  • compatibility, FORTRAN 77: Standard Support
  • compatibility, Fortran 90: Fortran 90
  • compilation, in-line: GLOBALS, Code Gen Options, Optimize Options
  • compilation, pedantic: Pedantic Compilation
  • compilation, status: Overall Options
  • compiler bugs, reporting: Bug Reporting
  • compiler limits: Compiler Limits
  • compiler memory usage: Known Bugs
  • compiler speed: Known Bugs
  • compilers: What is GNU Fortran?
  • compiling programs: G77 and GCC
  • Complex intrinsic: Complex Intrinsic
  • COMPLEX intrinsics: Fortran Dialect Options
  • complex performance: Known Bugs
  • COMPLEX statement: Complex Variables
  • complex values: Ugly Complex Part Extraction
  • complex variables: Complex Variables
  • COMPLEX(KIND=1) type: Compiler Types
  • COMPLEX(KIND=2) type: Compiler Types
  • components of g77: What is GNU Fortran?
  • concatenation: Arbitrary Concatenation
  • concepts, basic: What is GNU Fortran?
  • conformance, IEEE 754: Floating-point precision, Optimize Options
  • Conjg intrinsic: Conjg Intrinsic
  • consistency checks: Overall Options
  • constants: Compiler Constants, Constants
  • constants, character: Character and Hollerith Constants, Ugly Conversion of Initializers, Double Quote Meaning
  • constants, context-sensitive: Context-Sensitive Constants
  • constants, Hollerith: Character and Hollerith Constants, Ugly Conversion of Initializers, Ugly Implicit Argument Conversion
  • constants, integer: Known Bugs
  • constants, octal: Double Quote Meaning
  • constants, prefix-radix: Fortran Dialect Options
  • constants, types: Fortran Dialect Options
  • construct names: Construct Names
  • context-sensitive constants: Context-Sensitive Constants
  • context-sensitive intrinsics: Context-Sensitive Intrinsicness
  • continuation character: LEX, Exclamation Point, Statements Comments Lines
  • continuation line, ampersand: Ampersands
  • continuation line, number of: Continuation Line
  • contributors: Contributors
  • conversions, nonportable: Nonportable Conversions
  • core dump: Bug Criteria
  • Cos intrinsic: Cos Intrinsic
  • CosD intrinsic: CosD Intrinsic
  • CosH intrinsic: CosH Intrinsic
  • Count intrinsic: Count Intrinsic
  • cpp preprocessor: Overall Options
  • cpp program: LEX, Bug Reporting, Preprocessor Options, Overall Options, What is GNU Fortran?
  • CPU_Time intrinsic: CPU_Time Intrinsic
  • Cray pointers: POINTER Statements
  • credits: Contributors
  • CShift intrinsic: CShift Intrinsic
  • CSin intrinsic: CSin Intrinsic
  • CSqRt intrinsic: CSqRt Intrinsic
  • CTime intrinsic: CTime Intrinsic (function), CTime Intrinsic (subroutine)
  • CYCLE statement: CYCLE and EXIT
  • DAbs intrinsic: DAbs Intrinsic
  • DACos intrinsic: DACos Intrinsic
  • DACosD intrinsic: DACosD Intrinsic
  • DASin intrinsic: DASin Intrinsic
  • DASinD intrinsic: DASinD Intrinsic
  • DATA statement: Known Bugs, Code Gen Options
  • data types: Compiler Types
  • data, aligned: Aligned Data
  • data, overwritten: Strange Behavior at Run Time
  • DATan intrinsic: DATan Intrinsic
  • DATan2 intrinsic: DATan2 Intrinsic
  • DATan2D intrinsic: DATan2D Intrinsic
  • DATanD intrinsic: DATanD Intrinsic
  • Date intrinsic: Date Intrinsic
  • Date_and_Time intrinsic: Date_and_Time Intrinsic
  • date_y2kbuggy_0: Year 2000 (Y2K) Problems
  • DbesJ0 intrinsic: DbesJ0 Intrinsic
  • DbesJ1 intrinsic: DbesJ1 Intrinsic
  • DbesJN intrinsic: DbesJN Intrinsic
  • DbesY0 intrinsic: DbesY0 Intrinsic
  • DbesY1 intrinsic: DbesY1 Intrinsic
  • DbesYN intrinsic: DbesYN Intrinsic
  • Dble intrinsic: Dble Intrinsic
  • DbleQ intrinsic: DbleQ Intrinsic
  • DCmplx intrinsic: DCmplx Intrinsic
  • DConjg intrinsic: DConjg Intrinsic
  • DCos intrinsic: DCos Intrinsic
  • DCosD intrinsic: DCosD Intrinsic
  • DCosH intrinsic: DCosH Intrinsic
  • DDiM intrinsic: DDiM Intrinsic
  • debug line: Enabling Debug Lines, Debug Line
  • debug_rtx: Bug Reporting
  • debugger: Known Bugs, What is GNU Fortran?
  • debugging: Names, Main Program Unit, Debugging and Interfacing
  • debugging information options: Debugging Options
  • debugging main source code: Known Bugs
  • DECODE statement: ENCODE and DECODE
  • deleted intrinsics: Intrinsic Groups
  • DErF intrinsic: DErF Intrinsic
  • DErFC intrinsic: DErFC Intrinsic
  • DExp intrinsic: DExp Intrinsic
  • DFloat intrinsic: DFloat Intrinsic
  • DFlotI intrinsic: DFlotI Intrinsic
  • DFlotJ intrinsic: DFlotJ Intrinsic
  • diagnostics: Diagnostics
  • diagnostics, incorrect: What is GNU Fortran?
  • dialect options: Fortran Dialect Options
  • Digital Fortran features: Fortran Dialect Options
  • Digits intrinsic: Digits Intrinsic
  • DiM intrinsic: DiM Intrinsic
  • DImag intrinsic: DImag Intrinsic
  • DIMENSION statement: Array Bounds Expressions
  • DIMENSION statement: Adjustable Arrays, Arrays
  • DIMENSION X(1): Ugly Assumed-Size Arrays
  • dimensioning arrays: Adjustable Arrays
  • DInt intrinsic: DInt Intrinsic
  • direction of language development: Direction of Language Development
  • directive, #include: Bug Reporting
  • directive, INCLUDE: Bug Reporting, Directory Options, Preprocessor Options
  • directory, options: Directory Options
  • directory, search paths for inclusion: Directory Options
  • disabled intrinsics: Intrinsic Groups
  • disk full: Output Assumed To Flush
  • displaying main source code: Known Bugs
  • disposition of files: OPEN CLOSE and INQUIRE Keywords
  • distensions: Distensions
  • DLog intrinsic: DLog Intrinsic
  • DLog10 intrinsic: DLog10 Intrinsic
  • DMax1 intrinsic: DMax1 Intrinsic
  • DMin1 intrinsic: DMin1 Intrinsic
  • DMod intrinsic: DMod Intrinsic
  • DNInt intrinsic: DNInt Intrinsic
  • DNRM2: News
  • DO: DO WHILE
  • DO loops, one-trip: Fortran Dialect Options
  • DO loops, zero-trip: Fortran Dialect Options
  • DO statement: Loops, Warning Options
  • DO WHILE: DO WHILE, Optimize Options
  • dollar sign: Dollar Signs, I/O, Fortran Dialect Options
  • Dot_Product intrinsic: Dot_Product Intrinsic
  • DOUBLE COMPLEX: DOUBLE COMPLEX
  • DOUBLE COMPLEX type: Compiler Types
  • DOUBLE PRECISION type: Compiler Types
  • double quote: Character Set
  • double quoted character constants: Fortran 90 Features, Character Type
  • double quotes: Double Quote Meaning
  • double-precision performance: Changes, News
  • DProd intrinsic: DProd Intrinsic
  • DReal intrinsic: DReal Intrinsic
  • driver, gcc command as: What is GNU Fortran?
  • DSign intrinsic: DSign Intrinsic
  • DSin intrinsic: DSin Intrinsic
  • DSinD intrinsic: DSinD Intrinsic
  • DSinH intrinsic: DSinH Intrinsic
  • DSqRt intrinsic: DSqRt Intrinsic
  • DTan intrinsic: DTan Intrinsic
  • DTanD intrinsic: DTanD Intrinsic
  • DTanH intrinsic: DTanH Intrinsic
  • DTime intrinsic: DTime Intrinsic (function), DTime Intrinsic (subroutine)
  • dummies, unused: Warning Options
  • edit descriptor, <>: I/O
  • edit descriptor, O: I/O
  • edit descriptor, Q: Q Edit Descriptor
  • edit descriptor, Z: Fortran 90 Features, I/O
  • effecting IMPLICIT NONE: Warning Options
  • efficiency: Efficiency
  • ELF support: News
  • empty CHARACTER strings: Character Type
  • enabled intrinsics: Intrinsic Groups
  • ENCODE statement: ENCODE and DECODE
  • END DO: END DO
  • entry points: Alternate Entry Points
  • ENTRY statement: Alternate Entry Points
  • environment variables: Environment Variables
  • EOShift intrinsic: EOShift Intrinsic
  • Epsilon intrinsic: Epsilon Intrinsic
  • equivalence areas: Known Bugs, Local Equivalence Areas
  • EQUIVALENCE statement: Local Equivalence Areas
  • ErF intrinsic: ErF Intrinsic
  • ErFC intrinsic: ErFC Intrinsic
  • error messages: Warnings and Errors, Run-time Library Errors
  • error messages, incorrect: What is GNU Fortran?
  • error values: Run-time Library Errors
  • errors, linker: Large Common Blocks
  • ETime intrinsic: ETime Intrinsic (function), ETime Intrinsic (subroutine)
  • exceptions, floating-point: Floating-point Exception Handling
  • exclamation point: LEX, Exclamation Point, Trailing Comment, Character Set, Statements Comments Lines
  • executable file: What is GNU Fortran?
  • Exit intrinsic: Exit Intrinsic
  • EXIT statement: CYCLE and EXIT
  • Exp intrinsic: Exp Intrinsic
  • Exponent intrinsic: Exponent Intrinsic
  • extended-source option: Fortran Dialect Options
  • extensions, file name: Overall Options
  • extensions, from Fortran 90: Fortran 90 Features
  • extensions, more: More Extensions
  • extensions, VXT: VXT Fortran
  • external names: Mangling of Names
  • extra warnings: Warning Options
  • f2c: Increasing Precision/Range
  • f2c compatibility: Avoid f2c Compatibility
  • f2c compatibility: Block Data and Libraries, Debugging and Interfacing
  • f2c compatibility: Code Gen Options
  • f2c compatibility: Shorthand Options, Overall Options
  • f2c intrinsics: Fortran Dialect Options
  • f2c intrinsics group: Intrinsic Groups
  • f77 compatibility: Shorthand Options
  • f77 support: Backslash in Constants
  • f771, program: What is GNU Fortran?
  • f90 intrinsics group: Intrinsic Groups
  • fatal signal: Bug Criteria
  • FDate intrinsic: FDate Intrinsic (function), FDate Intrinsic (subroutine)
  • FDL, GNU Free Documentation License: GNU Free Documentation License
  • features, language: Direction of Language Development
  • features, ugly: Distensions, Shorthand Options
  • FFE: Front End, What is GNU Fortran?
  • fflush(): Output Assumed To Flush
  • FGet intrinsic: FGet Intrinsic (function), FGet Intrinsic (subroutine)
  • FGetC intrinsic: FGetC Intrinsic (function), FGetC Intrinsic (subroutine)
  • file format not recognized: What is GNU Fortran?
  • file formats: Portable Unformatted Files
  • file name extension: Overall Options
  • file name suffix: Overall Options
  • file type: Overall Options
  • file, source: Source Form, Lines, What is GNU Fortran?
  • files, executable: What is GNU Fortran?
  • fixed form: Source Form, Lines, Fortran Dialect Options
  • Float intrinsic: Float Intrinsic
  • FloatI intrinsic: FloatI Intrinsic
  • floating-point errors: Floating-point Errors
  • floating-point, errors: Inconsistent Calling Sequences
  • floating-point, exceptions: Floating-point Exception Handling
  • floating-point, precision: Floating-point precision, Optimize Options
  • FloatJ intrinsic: FloatJ Intrinsic
  • Floor intrinsic: Floor Intrinsic
  • Flush intrinsic: Flush Intrinsic
  • flushing output: Output Assumed To Flush
  • FNum intrinsic: FNum Intrinsic
  • FORM='PRINT': OPEN CLOSE and INQUIRE Keywords
  • FORMAT descriptors: Fortran 90 Features, I/O
  • FORMAT statement: Q Edit Descriptor, Expressions in FORMAT Statements
  • FORTRAN 66: Fortran Dialect Options, Shorthand Options
  • FORTRAN 77 compatibility: Standard Support
  • Fortran 90: Fortran 90 Features
  • Fortran 90, compatibility: Fortran 90
  • Fortran 90, features: Fortran Dialect Options
  • Fortran 90, intrinsics: Fortran Dialect Options
  • Fortran 90, support: Fortran 90 Support
  • Fortran preprocessor: Overall Options
  • forward references: GLOBALS
  • FPE handling: Floating-point Exception Handling
  • FPut intrinsic: FPut Intrinsic (function), FPut Intrinsic (subroutine)
  • FPutC intrinsic: FPutC Intrinsic (function), FPutC Intrinsic (subroutine)
  • Fraction intrinsic: Fraction Intrinsic
  • free form: Source Form, Lines, Fortran Dialect Options
  • front end, g77: Front End
  • front end, g77: What is GNU Fortran?
  • FSeek intrinsic: FSeek Intrinsic
  • FSF, funding the: Funding GNU Fortran
  • FStat intrinsic: FStat Intrinsic (function), FStat Intrinsic (subroutine)
  • FTell intrinsic: FTell Intrinsic (function), FTell Intrinsic (subroutine)
  • function references, in adjustable array bounds: Array Bounds Expressions
  • FUNCTION statement: Functions, Procedures
  • functions: Functions
  • functions, mistyped: Not My Type
  • funding improvements: Funding GNU Fortran
  • funding the FSF: Funding GNU Fortran
  • g77 options, --driver: Changes, News
  • g77 options, -v: G77 and GCC
  • g77, command: G77 and GCC, What is GNU Fortran?
  • g77, components of: What is GNU Fortran?
  • g77, front end: Front End
  • g77, front end: What is GNU Fortran?
  • g77, modifying: Overall Options
  • G77_date_y2kbuggy_0: Year 2000 (Y2K) Problems
  • G77_vxtidate_y2kbuggy_0: Year 2000 (Y2K) Problems
  • GBE: Philosophy of Code Generation, What is GNU Fortran?
  • GBEL: Philosophy of Code Generation
  • gcc, back end: Philosophy of Code Generation
  • gcc, back end: What is GNU Fortran?
  • gcc, command: G77 and GCC, What is GNU Fortran?
  • gcc, command as driver: What is GNU Fortran?
  • gcc, not recognizing Fortran source: What is GNU Fortran?
  • gdb, command: What is GNU Fortran?
  • gdb, support: Debugger Problems
  • generic intrinsics: Generics and Specifics
  • GError intrinsic: GError Intrinsic
  • GetArg intrinsic: Main Program Unit
  • GetArg intrinsic: GetArg Intrinsic
  • GetCWD intrinsic: GetCWD Intrinsic (function), GetCWD Intrinsic (subroutine)
  • GetEnv intrinsic: GetEnv Intrinsic
  • GetGId intrinsic: GetGId Intrinsic
  • GetLog intrinsic: GetLog Intrinsic
  • GetPId intrinsic: GetPId Intrinsic
  • getting started: Getting Started
  • GetUId intrinsic: GetUId Intrinsic
  • global names, warning: Code Gen Options, Warning Options
  • GMTime intrinsic: GMTime Intrinsic
  • GNU Back End (GBE): Philosophy of Code Generation, What is GNU Fortran?
  • GNU Back End Language (GBEL): Philosophy of Code Generation
  • GNU Fortran command options: Invoking G77
  • GNU Fortran Front End (FFE): Front End, What is GNU Fortran?
  • gnu intrinsics group: Intrinsic Groups
  • GOTO statement: Assigned Statement Labels
  • groups of intrinsics: Intrinsic Groups
  • hardware errors: Signal 11 and Friends
  • hash mark: Character Set
  • HDF: Portable Unformatted Files
  • hidden intrinsics: Intrinsic Groups
  • Hollerith constants: Character and Hollerith Constants, Ugly Conversion of Initializers, Ugly Implicit Argument Conversion, Fortran Dialect Options
  • horizontal tab: Tabs
  • HostNm intrinsic: HostNm Intrinsic (function), HostNm Intrinsic (subroutine)
  • Huge intrinsic: Huge Intrinsic
  • I/O, errors: Run-time Library Errors
  • I/O, flushing: Output Assumed To Flush
  • IAbs intrinsic: IAbs Intrinsic
  • IAChar intrinsic: IAChar Intrinsic
  • IAnd intrinsic: IAnd Intrinsic
  • IArgC intrinsic: Main Program Unit
  • IArgC intrinsic: IArgC Intrinsic
  • IBClr intrinsic: IBClr Intrinsic
  • IBits intrinsic: IBits Intrinsic
  • IBSet intrinsic: IBSet Intrinsic
  • IChar intrinsic: IChar Intrinsic
  • IDate intrinsic: IDate Intrinsic (VXT), IDate Intrinsic (UNIX)
  • IDiM intrinsic: IDiM Intrinsic
  • IDInt intrinsic: IDInt Intrinsic
  • IDNInt intrinsic: IDNInt Intrinsic
  • IEEE 754 conformance: Floating-point precision, Optimize Options
  • IEOr intrinsic: IEOr Intrinsic
  • IErrNo intrinsic: IErrNo Intrinsic
  • IFix intrinsic: IFix Intrinsic
  • IIAbs intrinsic: IIAbs Intrinsic
  • IIAnd intrinsic: IIAnd Intrinsic
  • IIBClr intrinsic: IIBClr Intrinsic
  • IIBits intrinsic: IIBits Intrinsic
  • IIBSet intrinsic: IIBSet Intrinsic
  • IIDiM intrinsic: IIDiM Intrinsic
  • IIDInt intrinsic: IIDInt Intrinsic
  • IIDNnt intrinsic: IIDNnt Intrinsic
  • IIEOr intrinsic: IIEOr Intrinsic
  • IIFix intrinsic: IIFix Intrinsic
  • IInt intrinsic: IInt Intrinsic
  • IIOr intrinsic: IIOr Intrinsic
  • IIQint intrinsic: IIQint Intrinsic
  • IIQNnt intrinsic: IIQNnt Intrinsic
  • IIShftC intrinsic: IIShftC Intrinsic
  • IISign intrinsic: IISign Intrinsic
  • illegal unit number: Large File Unit Numbers
  • Imag intrinsic: Imag Intrinsic
  • imaginary part: Complex Variables, Ugly Complex Part Extraction
  • ImagPart intrinsic: ImagPart Intrinsic
  • IMax0 intrinsic: IMax0 Intrinsic
  • IMax1 intrinsic: IMax1 Intrinsic
  • IMin0 intrinsic: IMin0 Intrinsic
  • IMin1 intrinsic: IMin1 Intrinsic
  • IMod intrinsic: IMod Intrinsic
  • IMPLICIT CHARACTER*(*) statement: Limitation on Implicit Declarations
  • implicit declaration, warning: Warning Options
  • IMPLICIT NONE, similar effect: Warning Options
  • implicit typing: Not My Type
  • improvements, funding: Funding GNU Fortran
  • in-line code: GLOBALS, Code Gen Options, Optimize Options, What is GNU Fortran?
  • INCLUDE directive: Bug Reporting, INCLUDE, Directory Options, Preprocessor Options
  • included files: Bug Reporting
  • inclusion, directory search paths for: Directory Options
  • inconsistent floating-point results: Floating-point Errors
  • incorrect diagnostics: What is GNU Fortran?
  • incorrect error messages: What is GNU Fortran?
  • incorrect use of language: What is GNU Fortran?
  • increasing maximum unit number: Large File Unit Numbers
  • increasing precision: Increasing Precision/Range
  • increasing range: Increasing Precision/Range
  • Index intrinsic: Index Intrinsic
  • indexed (iterative) DO: Optimize Options
  • infinite spaces printed: Strange Behavior at Run Time
  • INInt intrinsic: INInt Intrinsic
  • initialization, bug: Known Bugs
  • initialization, of local variables: Code Gen Options
  • initialization, run-time: Startup Code
  • initialization, statement placement: Initializing Before Specifying
  • INot intrinsic: INot Intrinsic
  • INQUIRE statement: OPEN CLOSE and INQUIRE Keywords
  • installation trouble: Trouble
  • Int intrinsic: Int Intrinsic
  • Int2 intrinsic: Int2 Intrinsic
  • Int8 intrinsic: Int8 Intrinsic
  • integer constants: Known Bugs
  • INTEGER(KIND=1) type: Compiler Types
  • INTEGER(KIND=2) type: Compiler Types
  • INTEGER(KIND=3) type: Compiler Types
  • INTEGER(KIND=6) type: Compiler Types
  • INTEGER*2 support: Popular Non-standard Types
  • INTEGER*8 support: Full Support for Compiler Types
  • Intel x86: News
  • interfacing: Debugging and Interfacing
  • internal consistency checks: Overall Options
  • intrinsics, Abort: Abort Intrinsic
  • intrinsics, Abs: Abs Intrinsic
  • intrinsics, Access: Access Intrinsic
  • intrinsics, AChar: AChar Intrinsic
  • intrinsics, ACos: ACos Intrinsic
  • intrinsics, ACosD: ACosD Intrinsic
  • intrinsics, AdjustL: AdjustL Intrinsic
  • intrinsics, AdjustR: AdjustR Intrinsic
  • intrinsics, AImag: AImag Intrinsic
  • intrinsics, AImag: REAL() and AIMAG() of Complex
  • intrinsics, AIMax0: AIMax0 Intrinsic
  • intrinsics, AIMin0: AIMin0 Intrinsic
  • intrinsics, AInt: AInt Intrinsic
  • intrinsics, AJMax0: AJMax0 Intrinsic
  • intrinsics, AJMin0: AJMin0 Intrinsic
  • intrinsics, Alarm: Alarm Intrinsic
  • intrinsics, All: All Intrinsic
  • intrinsics, Allocated: Allocated Intrinsic
  • intrinsics, ALog: ALog Intrinsic
  • intrinsics, ALog10: ALog10 Intrinsic
  • intrinsics, AMax0: AMax0 Intrinsic
  • intrinsics, AMax1: AMax1 Intrinsic
  • intrinsics, AMin0: AMin0 Intrinsic
  • intrinsics, AMin1: AMin1 Intrinsic
  • intrinsics, AMod: AMod Intrinsic
  • intrinsics, And: Bit Operations on Floating-point Data
  • intrinsics, And: And Intrinsic
  • intrinsics, ANInt: ANInt Intrinsic
  • intrinsics, Any: Any Intrinsic
  • intrinsics, ASin: ASin Intrinsic
  • intrinsics, ASinD: ASinD Intrinsic
  • intrinsics, Associated: Associated Intrinsic
  • intrinsics, ATan: ATan Intrinsic
  • intrinsics, ATan2: ATan2 Intrinsic
  • intrinsics, ATan2D: ATan2D Intrinsic
  • intrinsics, ATanD: ATanD Intrinsic
  • intrinsics, badu77: Fortran Dialect Options
  • intrinsics, BesJ0: BesJ0 Intrinsic
  • intrinsics, BesJ1: BesJ1 Intrinsic
  • intrinsics, BesJN: BesJN Intrinsic
  • intrinsics, BesY0: BesY0 Intrinsic
  • intrinsics, BesY1: BesY1 Intrinsic
  • intrinsics, BesYN: BesYN Intrinsic
  • intrinsics, Bit_Size: Bit_Size Intrinsic
  • intrinsics, BITest: BITest Intrinsic
  • intrinsics, BJTest: BJTest Intrinsic
  • intrinsics, BTest: BTest Intrinsic
  • intrinsics, CAbs: CAbs Intrinsic
  • intrinsics, CCos: CCos Intrinsic
  • intrinsics, CDAbs: CDAbs Intrinsic
  • intrinsics, CDCos: CDCos Intrinsic
  • intrinsics, CDExp: CDExp Intrinsic
  • intrinsics, CDLog: CDLog Intrinsic
  • intrinsics, CDSin: CDSin Intrinsic
  • intrinsics, CDSqRt: CDSqRt Intrinsic
  • intrinsics, Ceiling: Ceiling Intrinsic
  • intrinsics, CExp: CExp Intrinsic
  • intrinsics, Char: Char Intrinsic
  • intrinsics, ChDir: ChDir Intrinsic (function), ChDir Intrinsic (subroutine)
  • intrinsics, ChMod: ChMod Intrinsic (function), ChMod Intrinsic (subroutine)
  • intrinsics, CLog: CLog Intrinsic
  • intrinsics, Cmplx: Cmplx Intrinsic
  • intrinsics, Cmplx: CMPLX() of DOUBLE PRECISION
  • intrinsics, Complex: Complex Intrinsic
  • intrinsics, COMPLEX: Fortran Dialect Options
  • intrinsics, Conjg: Conjg Intrinsic
  • intrinsics, context-sensitive: Context-Sensitive Intrinsicness
  • intrinsics, Cos: Cos Intrinsic
  • intrinsics, CosD: CosD Intrinsic
  • intrinsics, CosH: CosH Intrinsic
  • intrinsics, Count: Count Intrinsic
  • intrinsics, CPU_Time: CPU_Time Intrinsic
  • intrinsics, CShift: CShift Intrinsic
  • intrinsics, CSin: CSin Intrinsic
  • intrinsics, CSqRt: CSqRt Intrinsic
  • intrinsics, CTime: CTime Intrinsic (function), CTime Intrinsic (subroutine)
  • intrinsics, DAbs: DAbs Intrinsic
  • intrinsics, DACos: DACos Intrinsic
  • intrinsics, DACosD: DACosD Intrinsic
  • intrinsics, DASin: DASin Intrinsic
  • intrinsics, DASinD: DASinD Intrinsic
  • intrinsics, DATan: DATan Intrinsic
  • intrinsics, DATan2: DATan2 Intrinsic
  • intrinsics, DATan2D: DATan2D Intrinsic
  • intrinsics, DATanD: DATanD Intrinsic
  • intrinsics, Date: Date Intrinsic
  • intrinsics, Date_and_Time: Date_and_Time Intrinsic
  • intrinsics, DbesJ0: DbesJ0 Intrinsic
  • intrinsics, DbesJ1: DbesJ1 Intrinsic
  • intrinsics, DbesJN: DbesJN Intrinsic
  • intrinsics, DbesY0: DbesY0 Intrinsic
  • intrinsics, DbesY1: DbesY1 Intrinsic
  • intrinsics, DbesYN: DbesYN Intrinsic
  • intrinsics, Dble: Dble Intrinsic
  • intrinsics, DbleQ: DbleQ Intrinsic
  • intrinsics, DCmplx: DCmplx Intrinsic
  • intrinsics, DConjg: DConjg Intrinsic
  • intrinsics, DCos: DCos Intrinsic
  • intrinsics, DCosD: DCosD Intrinsic
  • intrinsics, DCosH: DCosH Intrinsic
  • intrinsics, DDiM: DDiM Intrinsic
  • intrinsics, deleted: Intrinsic Groups
  • intrinsics, DErF: DErF Intrinsic
  • intrinsics, DErFC: DErFC Intrinsic
  • intrinsics, DExp: DExp Intrinsic
  • intrinsics, DFloat: DFloat Intrinsic
  • intrinsics, DFlotI: DFlotI Intrinsic
  • intrinsics, DFlotJ: DFlotJ Intrinsic
  • intrinsics, Digits: Digits Intrinsic
  • intrinsics, DiM: DiM Intrinsic
  • intrinsics, DImag: DImag Intrinsic
  • intrinsics, DInt: DInt Intrinsic
  • intrinsics, disabled: Intrinsic Groups
  • intrinsics, DLog: DLog Intrinsic
  • intrinsics, DLog10: DLog10 Intrinsic
  • intrinsics, DMax1: DMax1 Intrinsic
  • intrinsics, DMin1: DMin1 Intrinsic
  • intrinsics, DMod: DMod Intrinsic
  • intrinsics, DNInt: DNInt Intrinsic
  • intrinsics, Dot_Product: Dot_Product Intrinsic
  • intrinsics, DProd: DProd Intrinsic
  • intrinsics, DReal: DReal Intrinsic
  • intrinsics, DSign: DSign Intrinsic
  • intrinsics, DSin: DSin Intrinsic
  • intrinsics, DSinD: DSinD Intrinsic
  • intrinsics, DSinH: DSinH Intrinsic
  • intrinsics, DSqRt: DSqRt Intrinsic
  • intrinsics, DTan: DTan Intrinsic
  • intrinsics, DTanD: DTanD Intrinsic
  • intrinsics, DTanH: DTanH Intrinsic
  • intrinsics, DTime: DTime Intrinsic (function), DTime Intrinsic (subroutine)
  • intrinsics, enabled: Intrinsic Groups
  • intrinsics, EOShift: EOShift Intrinsic
  • intrinsics, Epsilon: Epsilon Intrinsic
  • intrinsics, ErF: ErF Intrinsic
  • intrinsics, ErFC: ErFC Intrinsic
  • intrinsics, ETime: ETime Intrinsic (function), ETime Intrinsic (subroutine)
  • intrinsics, Exit: Exit Intrinsic
  • intrinsics, Exp: Exp Intrinsic
  • intrinsics, Exponent: Exponent Intrinsic
  • intrinsics, f2c: Fortran Dialect Options
  • intrinsics, FDate: FDate Intrinsic (function), FDate Intrinsic (subroutine)
  • intrinsics, FGet: FGet Intrinsic (function), FGet Intrinsic (subroutine)
  • intrinsics, FGetC: FGetC Intrinsic (function), FGetC Intrinsic (subroutine)
  • intrinsics, Float: Float Intrinsic
  • intrinsics, FloatI: FloatI Intrinsic
  • intrinsics, FloatJ: FloatJ Intrinsic
  • intrinsics, Floor: Floor Intrinsic
  • intrinsics, Flush: Flush Intrinsic
  • intrinsics, FNum: FNum Intrinsic
  • intrinsics, Fortran 90: Fortran Dialect Options
  • intrinsics, FPut: FPut Intrinsic (function), FPut Intrinsic (subroutine)
  • intrinsics, FPutC: FPutC Intrinsic (function), FPutC Intrinsic (subroutine)
  • intrinsics, Fraction: Fraction Intrinsic
  • intrinsics, FSeek: FSeek Intrinsic
  • intrinsics, FStat: FStat Intrinsic (function), FStat Intrinsic (subroutine)
  • intrinsics, FTell: FTell Intrinsic (function), FTell Intrinsic (subroutine)
  • intrinsics, generic: Generics and Specifics
  • intrinsics, GError: GError Intrinsic
  • intrinsics, GetArg: Main Program Unit
  • intrinsics, GetArg: GetArg Intrinsic
  • intrinsics, GetCWD: GetCWD Intrinsic (function), GetCWD Intrinsic (subroutine)
  • intrinsics, GetEnv: GetEnv Intrinsic
  • intrinsics, GetGId: GetGId Intrinsic
  • intrinsics, GetLog: GetLog Intrinsic
  • intrinsics, GetPId: GetPId Intrinsic
  • intrinsics, GetUId: GetUId Intrinsic
  • intrinsics, GMTime: GMTime Intrinsic
  • intrinsics, groups: Intrinsic Groups
  • intrinsics, groups of: Intrinsic Groups
  • intrinsics, hidden: Intrinsic Groups
  • intrinsics, HostNm: HostNm Intrinsic (function), HostNm Intrinsic (subroutine)
  • intrinsics, Huge: Huge Intrinsic
  • intrinsics, IAbs: IAbs Intrinsic
  • intrinsics, IAChar: IAChar Intrinsic
  • intrinsics, IAnd: IAnd Intrinsic
  • intrinsics, IArgC: Main Program Unit
  • intrinsics, IArgC: IArgC Intrinsic
  • intrinsics, IBClr: IBClr Intrinsic
  • intrinsics, IBits: IBits Intrinsic
  • intrinsics, IBSet: IBSet Intrinsic
  • intrinsics, IChar: IChar Intrinsic
  • intrinsics, IDate: IDate Intrinsic (VXT), IDate Intrinsic (UNIX)
  • intrinsics, IDiM: IDiM Intrinsic
  • intrinsics, IDInt: IDInt Intrinsic
  • intrinsics, IDNInt: IDNInt Intrinsic
  • intrinsics, IEOr: IEOr Intrinsic
  • intrinsics, IErrNo: IErrNo Intrinsic
  • intrinsics, IFix: IFix Intrinsic
  • intrinsics, IIAbs: IIAbs Intrinsic
  • intrinsics, IIAnd: IIAnd Intrinsic
  • intrinsics, IIBClr: IIBClr Intrinsic
  • intrinsics, IIBits: IIBits Intrinsic
  • intrinsics, IIBSet: IIBSet Intrinsic
  • intrinsics, IIDiM: IIDiM Intrinsic
  • intrinsics, IIDInt: IIDInt Intrinsic
  • intrinsics, IIDNnt: IIDNnt Intrinsic
  • intrinsics, IIEOr: IIEOr Intrinsic
  • intrinsics, IIFix: IIFix Intrinsic
  • intrinsics, IInt: IInt Intrinsic
  • intrinsics, IIOr: IIOr Intrinsic
  • intrinsics, IIQint: IIQint Intrinsic
  • intrinsics, IIQNnt: IIQNnt Intrinsic
  • intrinsics, IIShftC: IIShftC Intrinsic
  • intrinsics, IISign: IISign Intrinsic
  • intrinsics, Imag: Imag Intrinsic
  • intrinsics, ImagPart: ImagPart Intrinsic
  • intrinsics, IMax0: IMax0 Intrinsic
  • intrinsics, IMax1: IMax1 Intrinsic
  • intrinsics, IMin0: IMin0 Intrinsic
  • intrinsics, IMin1: IMin1 Intrinsic
  • intrinsics, IMod: IMod Intrinsic
  • intrinsics, Index: Index Intrinsic
  • intrinsics, INInt: INInt Intrinsic
  • intrinsics, INot: INot Intrinsic
  • intrinsics, Int: Int Intrinsic
  • intrinsics, Int2: Int2 Intrinsic
  • intrinsics, Int8: Int8 Intrinsic
  • intrinsics, IOr: IOr Intrinsic
  • intrinsics, IRand: IRand Intrinsic
  • intrinsics, IsaTty: IsaTty Intrinsic
  • intrinsics, IShft: IShft Intrinsic
  • intrinsics, IShftC: IShftC Intrinsic
  • intrinsics, ISign: ISign Intrinsic
  • intrinsics, ITime: ITime Intrinsic
  • intrinsics, IZExt: IZExt Intrinsic
  • intrinsics, JIAbs: JIAbs Intrinsic
  • intrinsics, JIAnd: JIAnd Intrinsic
  • intrinsics, JIBClr: JIBClr Intrinsic
  • intrinsics, JIBits: JIBits Intrinsic
  • intrinsics, JIBSet: JIBSet Intrinsic
  • intrinsics, JIDiM: JIDiM Intrinsic
  • intrinsics, JIDInt: JIDInt Intrinsic
  • intrinsics, JIDNnt: JIDNnt Intrinsic
  • intrinsics, JIEOr: JIEOr Intrinsic
  • intrinsics, JIFix: JIFix Intrinsic
  • intrinsics, JInt: JInt Intrinsic
  • intrinsics, JIOr: JIOr Intrinsic
  • intrinsics, JIQint: JIQint Intrinsic
  • intrinsics, JIQNnt: JIQNnt Intrinsic
  • intrinsics, JIShft: JIShft Intrinsic
  • intrinsics, JIShftC: JIShftC Intrinsic
  • intrinsics, JISign: JISign Intrinsic
  • intrinsics, JMax0: JMax0 Intrinsic
  • intrinsics, JMax1: JMax1 Intrinsic
  • intrinsics, JMin0: JMin0 Intrinsic
  • intrinsics, JMin1: JMin1 Intrinsic
  • intrinsics, JMod: JMod Intrinsic
  • intrinsics, JNInt: JNInt Intrinsic
  • intrinsics, JNot: JNot Intrinsic
  • intrinsics, JZExt: JZExt Intrinsic
  • intrinsics, Kill: Kill Intrinsic (function), Kill Intrinsic (subroutine)
  • intrinsics, Kind: Kind Intrinsic
  • intrinsics, LBound: LBound Intrinsic
  • intrinsics, Len: Len Intrinsic
  • intrinsics, Len_Trim: Len_Trim Intrinsic
  • intrinsics, LGe: LGe Intrinsic
  • intrinsics, LGt: LGt Intrinsic
  • intrinsics, Link: Link Intrinsic (function), Link Intrinsic (subroutine)
  • intrinsics, LLe: LLe Intrinsic
  • intrinsics, LLt: LLt Intrinsic
  • intrinsics, LnBlnk: LnBlnk Intrinsic
  • intrinsics, Loc: Loc Intrinsic
  • intrinsics, Log: Log Intrinsic
  • intrinsics, Log10: Log10 Intrinsic
  • intrinsics, Logical: Logical Intrinsic
  • intrinsics, Long: Long Intrinsic
  • intrinsics, LShift: LShift Intrinsic
  • intrinsics, LStat: LStat Intrinsic (function), LStat Intrinsic (subroutine)
  • intrinsics, LTime: LTime Intrinsic
  • intrinsics, MatMul: MatMul Intrinsic
  • intrinsics, Max: Max Intrinsic
  • intrinsics, Max0: Max0 Intrinsic
  • intrinsics, Max1: Max1 Intrinsic
  • intrinsics, MaxExponent: MaxExponent Intrinsic
  • intrinsics, MaxLoc: MaxLoc Intrinsic
  • intrinsics, MaxVal: MaxVal Intrinsic
  • intrinsics, MClock: MClock Intrinsic
  • intrinsics, MClock8: MClock8 Intrinsic
  • intrinsics, Merge: Merge Intrinsic
  • intrinsics, MIL-STD 1753: Fortran Dialect Options
  • intrinsics, Min: Min Intrinsic
  • intrinsics, Min0: Min0 Intrinsic
  • intrinsics, Min1: Min1 Intrinsic
  • intrinsics, MinExponent: MinExponent Intrinsic
  • intrinsics, MinLoc: MinLoc Intrinsic
  • intrinsics, MinVal: MinVal Intrinsic
  • intrinsics, Mod: Mod Intrinsic
  • intrinsics, Modulo: Modulo Intrinsic
  • intrinsics, MvBits: MvBits Intrinsic
  • intrinsics, Nearest: Nearest Intrinsic
  • intrinsics, NInt: NInt Intrinsic
  • intrinsics, Not: Not Intrinsic
  • intrinsics, Or: Bit Operations on Floating-point Data
  • intrinsics, Or: Or Intrinsic
  • intrinsics, others: Other Intrinsics
  • intrinsics, Pack: Pack Intrinsic
  • intrinsics, PError: PError Intrinsic
  • intrinsics, Precision: Precision Intrinsic
  • intrinsics, Present: Present Intrinsic
  • intrinsics, Product: Product Intrinsic
  • intrinsics, QAbs: QAbs Intrinsic
  • intrinsics, QACos: QACos Intrinsic
  • intrinsics, QACosD: QACosD Intrinsic
  • intrinsics, QASin: QASin Intrinsic
  • intrinsics, QASinD: QASinD Intrinsic
  • intrinsics, QATan: QATan Intrinsic
  • intrinsics, QATan2: QATan2 Intrinsic
  • intrinsics, QATan2D: QATan2D Intrinsic
  • intrinsics, QATanD: QATanD Intrinsic
  • intrinsics, QCos: QCos Intrinsic
  • intrinsics, QCosD: QCosD Intrinsic
  • intrinsics, QCosH: QCosH Intrinsic
  • intrinsics, QDiM: QDiM Intrinsic
  • intrinsics, QExp: QExp Intrinsic
  • intrinsics, QExt: QExt Intrinsic
  • intrinsics, QExtD: QExtD Intrinsic
  • intrinsics, QFloat: QFloat Intrinsic
  • intrinsics, QInt: QInt Intrinsic
  • intrinsics, QLog: QLog Intrinsic
  • intrinsics, QLog10: QLog10 Intrinsic
  • intrinsics, QMax1: QMax1 Intrinsic
  • intrinsics, QMin1: QMin1 Intrinsic
  • intrinsics, QMod: QMod Intrinsic
  • intrinsics, QNInt: QNInt Intrinsic
  • intrinsics, QSin: QSin Intrinsic
  • intrinsics, QSinD: QSinD Intrinsic
  • intrinsics, QSinH: QSinH Intrinsic
  • intrinsics, QSqRt: QSqRt Intrinsic
  • intrinsics, QTan: QTan Intrinsic
  • intrinsics, QTanD: QTanD Intrinsic
  • intrinsics, QTanH: QTanH Intrinsic
  • intrinsics, Radix: Radix Intrinsic
  • intrinsics, Rand: Rand Intrinsic
  • intrinsics, Random_Number: Random_Number Intrinsic
  • intrinsics, Random_Seed: Random_Seed Intrinsic
  • intrinsics, Range: Range Intrinsic
  • intrinsics, Real: Real Intrinsic
  • intrinsics, Real: REAL() and AIMAG() of Complex
  • intrinsics, RealPart: RealPart Intrinsic
  • intrinsics, Rename: Rename Intrinsic (function), Rename Intrinsic (subroutine)
  • intrinsics, Repeat: Repeat Intrinsic
  • intrinsics, Reshape: Reshape Intrinsic
  • intrinsics, RRSpacing: RRSpacing Intrinsic
  • intrinsics, RShift: RShift Intrinsic
  • intrinsics, Scale: Scale Intrinsic
  • intrinsics, Scan: Scan Intrinsic
  • intrinsics, Secnds: Secnds Intrinsic
  • intrinsics, Second: Second Intrinsic (subroutine), Second Intrinsic (function)
  • intrinsics, Selected_Int_Kind: Selected_Int_Kind Intrinsic
  • intrinsics, Selected_Real_Kind: Selected_Real_Kind Intrinsic
  • intrinsics, Set_Exponent: Set_Exponent Intrinsic
  • intrinsics, Shape: Shape Intrinsic
  • intrinsics, Shift: Bit Operations on Floating-point Data
  • intrinsics, Short: Short Intrinsic
  • intrinsics, Sign: Sign Intrinsic
  • intrinsics, Signal: Signal Intrinsic (function), Signal Intrinsic (subroutine)
  • intrinsics, Sin: Sin Intrinsic
  • intrinsics, SinD: SinD Intrinsic
  • intrinsics, SinH: SinH Intrinsic
  • intrinsics, Sleep: Sleep Intrinsic
  • intrinsics, Sngl: Sngl Intrinsic
  • intrinsics, SnglQ: SnglQ Intrinsic
  • intrinsics, Spacing: Spacing Intrinsic
  • intrinsics, Spread: Spread Intrinsic
  • intrinsics, SqRt: SqRt Intrinsic
  • intrinsics, SRand: SRand Intrinsic
  • intrinsics, Stat: Stat Intrinsic (function), Stat Intrinsic (subroutine)
  • intrinsics, Sum: Sum Intrinsic
  • intrinsics, SymLnk: SymLnk Intrinsic (function), SymLnk Intrinsic (subroutine)
  • intrinsics, System: System Intrinsic (function), System Intrinsic (subroutine)
  • intrinsics, System_Clock: System_Clock Intrinsic
  • intrinsics, table of: Table of Intrinsic Functions
  • intrinsics, Tan: Tan Intrinsic
  • intrinsics, TanD: TanD Intrinsic
  • intrinsics, TanH: TanH Intrinsic
  • intrinsics, Time: Time Intrinsic (VXT), Time Intrinsic (UNIX)
  • intrinsics, Time8: Time8 Intrinsic
  • intrinsics, Tiny: Tiny Intrinsic
  • intrinsics, Transfer: Transfer Intrinsic
  • intrinsics, Transpose: Transpose Intrinsic
  • intrinsics, Trim: Trim Intrinsic
  • intrinsics, TtyNam: TtyNam Intrinsic (function), TtyNam Intrinsic (subroutine)
  • intrinsics, UBound: UBound Intrinsic
  • intrinsics, UMask: UMask Intrinsic (function), UMask Intrinsic (subroutine)
  • intrinsics, UNIX: Fortran Dialect Options
  • intrinsics, Unlink: Unlink Intrinsic (function), Unlink Intrinsic (subroutine)
  • intrinsics, Unpack: Unpack Intrinsic
  • intrinsics, Verify: Verify Intrinsic
  • intrinsics, VXT: Fortran Dialect Options
  • intrinsics, XOr: XOr Intrinsic
  • intrinsics, ZAbs: ZAbs Intrinsic
  • intrinsics, ZCos: ZCos Intrinsic
  • intrinsics, ZExp: ZExp Intrinsic
  • intrinsics, ZExt: ZExt Intrinsic
  • intrinsics, ZLog: ZLog Intrinsic
  • intrinsics, ZSin: ZSin Intrinsic
  • intrinsics, ZSqRt: ZSqRt Intrinsic
  • Introduction: Top
  • invalid assembly code: Bug Criteria
  • invalid input: Bug Criteria
  • IOr intrinsic: IOr Intrinsic
  • IOSTAT=: Run-time Library Errors
  • IRand intrinsic: IRand Intrinsic
  • IsaTty intrinsic: IsaTty Intrinsic
  • IShft intrinsic: IShft Intrinsic
  • IShftC intrinsic: IShftC Intrinsic
  • ISign intrinsic: ISign Intrinsic
  • iterative DO: Optimize Options
  • ITime intrinsic: ITime Intrinsic
  • ix86 floating-point: Floating-point precision
  • ix86 FPU stack: Inconsistent Calling Sequences
  • IZExt intrinsic: IZExt Intrinsic
  • JCB002 program: Generics and Specifics
  • JCB003 program: CMPAMBIG
  • JIAbs intrinsic: JIAbs Intrinsic
  • JIAnd intrinsic: JIAnd Intrinsic
  • JIBClr intrinsic: JIBClr Intrinsic
  • JIBits intrinsic: JIBits Intrinsic
  • JIBSet intrinsic: JIBSet Intrinsic
  • JIDiM intrinsic: JIDiM Intrinsic
  • JIDInt intrinsic: JIDInt Intrinsic
  • JIDNnt intrinsic: JIDNnt Intrinsic
  • JIEOr intrinsic: JIEOr Intrinsic
  • JIFix intrinsic: JIFix Intrinsic
  • JInt intrinsic: JInt Intrinsic
  • JIOr intrinsic: JIOr Intrinsic
  • JIQint intrinsic: JIQint Intrinsic
  • JIQNnt intrinsic: JIQNnt Intrinsic
  • JIShft intrinsic: JIShft Intrinsic
  • JIShftC intrinsic: JIShftC Intrinsic
  • JISign intrinsic: JISign Intrinsic
  • JMax0 intrinsic: JMax0 Intrinsic
  • JMax1 intrinsic: JMax1 Intrinsic
  • JMin0 intrinsic: JMin0 Intrinsic
  • JMin1 intrinsic: JMin1 Intrinsic
  • JMod intrinsic: JMod Intrinsic
  • JNInt intrinsic: JNInt Intrinsic
  • JNot intrinsic: JNot Intrinsic
  • JZExt intrinsic: JZExt Intrinsic
  • keywords, RECURSIVE: RECURSIVE Keyword
  • Kill intrinsic: Kill Intrinsic (function), Kill Intrinsic (subroutine)
  • Kind intrinsic: Kind Intrinsic
  • KIND= notation: Kind Notation
  • known causes of trouble: Trouble
  • lack of recursion: RECURSIVE Keyword
  • language, dialect options: Fortran Dialect Options
  • language, features: Direction of Language Development
  • language, incorrect use of: What is GNU Fortran?
  • large aggregate areas: Known Bugs
  • large common blocks: Large Common Blocks
  • layout of COMMON blocks: Aligned Data
  • LBound intrinsic: LBound Intrinsic
  • ld command: What is GNU Fortran?
  • ld, can't find _main: Cannot Link Fortran Programs
  • ld, can't find strange names: Cannot Link Fortran Programs
  • ld, error linking user code: Cannot Link Fortran Programs
  • ld, errors: Large Common Blocks
  • left angle: Character Set
  • left bracket: Character Set
  • legacy code: Collected Fortran Wisdom
  • Len intrinsic: Len Intrinsic
  • Len_Trim intrinsic: Len_Trim Intrinsic
  • length of source lines: Fortran Dialect Options
  • letters, lowercase: Case Sensitivity
  • letters, uppercase: Case Sensitivity
  • LGe intrinsic: LGe Intrinsic
  • LGt intrinsic: LGt Intrinsic
  • libc, non-ANSI or non-default: Strange Behavior at Run Time
  • libf2c library: What is GNU Fortran?
  • libg2c library: What is GNU Fortran?
  • libraries: What is GNU Fortran?
  • libraries, containing BLOCK DATA: Block Data and Libraries
  • libraries, libf2c: What is GNU Fortran?
  • libraries, libg2c: What is GNU Fortran?
  • limits, array dimensions: Compiler Limits
  • limits, array size: Array Size
  • limits, compiler: Compiler Limits
  • limits, continuation lines: Compiler Limits, Continuation Line
  • limits, lengths of names: Compiler Limits, Syntactic Items
  • limits, lengths of source lines: Fortran Dialect Options
  • limits, multi-dimension arrays: Array Size
  • limits, on character-variable length: Character-variable Length
  • limits, rank: Compiler Limits
  • limits, run-time library: Run-time Environment Limits
  • limits, timings: Secnds Intrinsic, DTime Intrinsic (function), Time8 Intrinsic, Time Intrinsic (UNIX), System_Clock Intrinsic, Second Intrinsic (subroutine), Second Intrinsic (function), MClock8 Intrinsic, MClock Intrinsic, ETime Intrinsic (function), ETime Intrinsic (subroutine), DTime Intrinsic (subroutine), CPU_Time Intrinsic
  • limits, Y10K: Time Intrinsic (VXT), IDate Intrinsic (UNIX), FDate Intrinsic (function), FDate Intrinsic (subroutine), Date_and_Time Intrinsic
  • limits, Y2K: IDate Intrinsic (VXT)
  • lines: Lines
  • lines, continuation: Continuation Line
  • lines, length: Fortran Dialect Options
  • lines, long: Long Lines
  • lines, short: Short Lines
  • Link intrinsic: Link Intrinsic (function), Link Intrinsic (subroutine)
  • linking: What is GNU Fortran?
  • linking against non-standard library: Strange Behavior at Run Time
  • linking error for user code: Cannot Link Fortran Programs
  • linking error, user code: Cannot Link Fortran Programs
  • linking with C: Interoperating with C and C++
  • linking, errors: Large Common Blocks
  • LLe intrinsic: LLe Intrinsic
  • LLt intrinsic: LLt Intrinsic
  • LnBlnk intrinsic: LnBlnk Intrinsic
  • Loc intrinsic: Loc Intrinsic
  • local equivalence areas: Local Equivalence Areas
  • Log intrinsic: Log Intrinsic
  • Log10 intrinsic: Log10 Intrinsic
  • logical expressions, comparing: Equivalence Versus Equality
  • Logical intrinsic: Logical Intrinsic
  • LOGICAL(KIND=1) type: Compiler Types
  • LOGICAL(KIND=2) type: Compiler Types
  • LOGICAL(KIND=3) type: Compiler Types
  • LOGICAL(KIND=6) type: Compiler Types
  • LOGICAL*1 support: Popular Non-standard Types
  • Long intrinsic: Long Intrinsic
  • long source lines: Long Lines
  • long time: Timer Wraparounds
  • loops, optimizing: Optimize Options
  • loops, speeding up: Optimize Options
  • loops, unrolling: Optimize Options
  • lowercase letters: Case Sensitivity
  • LShift intrinsic: LShift Intrinsic
  • LStat intrinsic: LStat Intrinsic (function), LStat Intrinsic (subroutine)
  • LTime intrinsic: LTime Intrinsic
  • machine code: What is GNU Fortran?
  • macro options: Shorthand Options
  • main program unit, debugging: Main Program Unit
  • main(): Main Program Unit
  • MAIN__(): Main Program Unit
  • Makefile example: Bug Criteria
  • MAP statement: STRUCTURE UNION RECORD MAP
  • MatMul intrinsic: MatMul Intrinsic
  • Max intrinsic: Max Intrinsic
  • Max0 intrinsic: Max0 Intrinsic
  • Max1 intrinsic: Max1 Intrinsic
  • MaxExponent intrinsic: MaxExponent Intrinsic
  • maximum number of dimensions: Compiler Limits
  • maximum rank: Compiler Limits
  • maximum unit number: Large File Unit Numbers
  • MaxLoc intrinsic: MaxLoc Intrinsic
  • MaxVal intrinsic: MaxVal Intrinsic
  • MClock intrinsic: MClock Intrinsic
  • MClock8 intrinsic: MClock8 Intrinsic
  • memory usage, of compiler: Known Bugs
  • Merge intrinsic: Merge Intrinsic
  • messages, run-time: Run-time Library Errors
  • messages, warning: Warning Options
  • messages, warning and error: Warnings and Errors
  • mil intrinsics group: Intrinsic Groups
  • MIL-STD 1753: MIL-STD 1753, END DO, DO WHILE, Fortran Dialect Options
  • Min intrinsic: Min Intrinsic
  • Min0 intrinsic: Min0 Intrinsic
  • Min1 intrinsic: Min1 Intrinsic
  • MinExponent intrinsic: MinExponent Intrinsic
  • MinLoc intrinsic: MinLoc Intrinsic
  • MinVal intrinsic: MinVal Intrinsic
  • mistakes: What is GNU Fortran?
  • mistyped functions: Not My Type
  • mistyped variables: Not My Type
  • Mod intrinsic: Mod Intrinsic
  • modifying g77: Overall Options
  • Modulo intrinsic: Modulo Intrinsic
  • multi-dimension arrays: Array Size
  • MvBits intrinsic: MvBits Intrinsic
  • MXUNIT: Large File Unit Numbers
  • name space: Mangling of Names
  • NAMELIST statement: NAMELIST
  • naming conflicts: Multiple Definitions of External Names
  • naming issues: Mangling of Names
  • naming programs: Nothing Happens
  • NaN values: Floating-point Exception Handling
  • Nearest intrinsic: Nearest Intrinsic
  • negative forms of options: Invoking G77
  • negative time: Timer Wraparounds
  • Netlib: Increasing Precision/Range, C Interfacing Tools
  • network file system: Output Assumed To Flush
  • new users: Getting Started
  • newbies: Getting Started
  • NeXTStep problems: NeXTStep Problems
  • NFS: Output Assumed To Flush
  • NInt intrinsic: NInt Intrinsic
  • nonportable conversions: Nonportable Conversions
  • Not intrinsic: Not Intrinsic
  • nothing happens: Nothing Happens
  • null arguments: Ugly Null Arguments
  • null byte, trailing: Character and Hollerith Constants
  • null CHARACTER strings: Character Type
  • number of continuation lines: Continuation Line
  • number of dimensions, maximum: Compiler Limits
  • number of trips: Loops
  • O edit descriptor: I/O
  • octal constants: Double Quote Meaning
  • omitting arguments: Ugly Null Arguments
  • one-trip DO loops: Fortran Dialect Options
  • open angle: Character Set
  • open bracket: Character Set
  • OPEN statement: OPEN CLOSE and INQUIRE Keywords
  • optimization, better: Better Optimization
  • optimization, for Pentium: Aligned Data
  • optimize options: Optimize Options
  • options, --driver: Changes, News
  • options, -falias-check: Aliasing Assumed To Work, Code Gen Options
  • options, -fargument-alias: Aliasing Assumed To Work, Code Gen Options
  • options, -fargument-noalias: Aliasing Assumed To Work, Code Gen Options
  • options, -fbadu77-intrinsics-delete: Fortran Dialect Options
  • options, -fbadu77-intrinsics-disable: Fortran Dialect Options
  • options, -fbadu77-intrinsics-enable: Fortran Dialect Options
  • options, -fbadu77-intrinsics-hide: Fortran Dialect Options
  • options, -fcaller-saves: Optimize Options
  • options, -fcase-initcap: Fortran Dialect Options
  • options, -fcase-lower: Fortran Dialect Options
  • options, -fcase-preserve: Fortran Dialect Options
  • options, -fcase-strict-lower: Fortran Dialect Options
  • options, -fcase-strict-upper: Fortran Dialect Options
  • options, -fcase-upper: Fortran Dialect Options
  • options, -fdelayed-branch: Optimize Options
  • options, -fdollar-ok: Fortran Dialect Options
  • options, -femulate-complex: Code Gen Options
  • options, -fexpensive-optimizations: Optimize Options
  • options, -ff2c-intrinsics-delete: Fortran Dialect Options
  • options, -ff2c-intrinsics-disable: Fortran Dialect Options
  • options, -ff2c-intrinsics-enable: Fortran Dialect Options
  • options, -ff2c-intrinsics-hide: Fortran Dialect Options
  • options, -ff2c-library: Code Gen Options
  • options, -ff66: Shorthand Options
  • options, -ff77: Shorthand Options
  • options, -ff90: Fortran Dialect Options
  • options, -ff90-intrinsics-delete: Fortran Dialect Options
  • options, -ff90-intrinsics-disable: Fortran Dialect Options
  • options, -ff90-intrinsics-enable: Fortran Dialect Options
  • options, -ff90-intrinsics-hide: Fortran Dialect Options
  • options, -ffast-math: Optimize Options
  • options, -ffixed-line-length-n: Fortran Dialect Options
  • options, -ffloat-store: Optimize Options
  • options, -fforce-addr: Optimize Options
  • options, -fforce-mem: Optimize Options
  • options, -ffree-form: Fortran Dialect Options
  • options, -fgnu-intrinsics-delete: Fortran Dialect Options
  • options, -fgnu-intrinsics-disable: Fortran Dialect Options
  • options, -fgnu-intrinsics-enable: Fortran Dialect Options
  • options, -fgnu-intrinsics-hide: Fortran Dialect Options
  • options, -fgroup-intrinsics-hide: Overly Convenient Options
  • options, -finit-local-zero: Overly Convenient Options, Code Gen Options
  • options, -fintrin-case-any: Fortran Dialect Options
  • options, -fintrin-case-initcap: Fortran Dialect Options
  • options, -fintrin-case-lower: Fortran Dialect Options
  • options, -fintrin-case-upper: Fortran Dialect Options
  • options, -fmatch-case-any: Fortran Dialect Options
  • options, -fmatch-case-initcap: Fortran Dialect Options
  • options, -fmatch-case-lower: Fortran Dialect Options
  • options, -fmatch-case-upper: Fortran Dialect Options
  • options, -fmil-intrinsics-delete: Fortran Dialect Options
  • options, -fmil-intrinsics-disable: Fortran Dialect Options
  • options, -fmil-intrinsics-enable: Fortran Dialect Options
  • options, -fmil-intrinsics-hide: Fortran Dialect Options
  • options, -fno-argument-noalias-global: Aliasing Assumed To Work, Code Gen Options
  • options, -fno-automatic: Overly Convenient Options, Code Gen Options
  • options, -fno-backslash: Fortran Dialect Options
  • options, -fno-common: Code Gen Options
  • options, -fno-f2c: Avoid f2c Compatibility, Code Gen Options
  • options, -fno-f77: Shorthand Options
  • options, -fno-fixed-form: Fortran Dialect Options
  • options, -fno-globals: Code Gen Options
  • options, -fno-ident: Code Gen Options
  • options, -fno-inline: Optimize Options
  • options, -fno-move-all-movables: Optimize Options
  • options, -fno-reduce-all-givs: Optimize Options
  • options, -fno-rerun-loop-opt: Optimize Options
  • options, -fno-second-underscore: Code Gen Options
  • options, -fno-silent: Overall Options
  • options, -fno-trapping-math: Optimize Options
  • options, -fno-ugly: Shorthand Options
  • options, -fno-ugly-args: Fortran Dialect Options
  • options, -fno-ugly-init: Fortran Dialect Options
  • options, -fno-underscoring: Names, Code Gen Options
  • options, -fonetrip: Fortran Dialect Options
  • options, -fpack-struct: Code Gen Options
  • options, -fpcc-struct-return: Code Gen Options
  • options, -fpedantic: Warning Options
  • options, -fPIC: News
  • options, -freg-struct-return: Code Gen Options
  • options, -frerun-cse-after-loop: Optimize Options
  • options, -fschedule-insns: Optimize Options
  • options, -fschedule-insns2: Optimize Options
  • options, -fset-g77-defaults: Overall Options
  • options, -fshort-double: Code Gen Options
  • options, -fsource-case-lower: Fortran Dialect Options
  • options, -fsource-case-preserve: Fortran Dialect Options
  • options, -fsource-case-upper: Fortran Dialect Options
  • options, -fstrength-reduce: Optimize Options
  • options, -fsymbol-case-any: Fortran Dialect Options
  • options, -fsymbol-case-initcap: Fortran Dialect Options
  • options, -fsymbol-case-lower: Fortran Dialect Options
  • options, -fsymbol-case-upper: Fortran Dialect Options
  • options, -fsyntax-only: Warning Options
  • options, -ftypeless-boz: Fortran Dialect Options
  • options, -fugly: Shorthand Options
  • options, -fugly-assign: Fortran Dialect Options
  • options, -fugly-assumed: Fortran Dialect Options
  • options, -fugly-comma: Fortran Dialect Options
  • options, -fugly-complex: Fortran Dialect Options
  • options, -fugly-logint: Fortran Dialect Options
  • options, -funix-intrinsics-delete: Fortran Dialect Options
  • options, -funix-intrinsics-disable: Fortran Dialect Options
  • options, -funix-intrinsics-enable: Fortran Dialect Options
  • options, -funix-intrinsics-hide: Fortran Dialect Options
  • options, -funroll-all-loops: Optimize Options
  • options, -funroll-loops: Optimize Options
  • options, -funsafe-math-optimizations: Optimize Options
  • options, -fversion: Overall Options
  • options, -fvxt: Fortran Dialect Options
  • options, -fvxt-intrinsics-delete: Fortran Dialect Options
  • options, -fvxt-intrinsics-disable: Fortran Dialect Options
  • options, -fvxt-intrinsics-enable: Fortran Dialect Options
  • options, -fvxt-intrinsics-hide: Fortran Dialect Options
  • options, -fzeros: Code Gen Options
  • options, -g: Debugging Options
  • options, -I-: Directory Options
  • options, -Idir: Directory Options
  • options, -malign-double: Aligned Data, Optimize Options
  • options, -Nl: Compiler Limits
  • options, -Nx: Compiler Limits
  • options, -pedantic: Warning Options
  • options, -pedantic-errors: Warning Options
  • options, -v: G77 and GCC
  • options, -W: Warning Options
  • options, -w: Warning Options
  • options, -Waggregate-return: Warning Options
  • options, -Wall: Warning Options
  • options, -Wcomment: Warning Options
  • options, -Wconversion: Warning Options
  • options, -Werror: Warning Options
  • options, -Wformat: Warning Options
  • options, -Wid-clash-len: Warning Options
  • options, -Wimplicit: Warning Options
  • options, -Wlarger-than-len: Warning Options
  • options, -Wno-globals: Warning Options
  • options, -Wparentheses: Warning Options
  • options, -Wredundant-decls: Warning Options
  • options, -Wshadow: Warning Options
  • options, -Wsurprising: Warning Options
  • options, -Wswitch: Warning Options
  • options, -Wtraditional: Warning Options
  • options, -Wuninitialized: Warning Options
  • options, -Wunused: Warning Options
  • options, -x f77-cpp-input: LEX
  • options, adding: Adding Options
  • options, code generation: Code Gen Options
  • options, debugging: Debugging Options
  • options, dialect: Fortran Dialect Options
  • options, directory search: Directory Options
  • options, GNU Fortran command: Invoking G77
  • options, macro: Shorthand Options
  • options, negative forms: Invoking G77
  • options, optimization: Optimize Options
  • options, overall: Overall Options
  • options, overly convenient: Overly Convenient Options
  • options, preprocessor: Preprocessor Options
  • options, shorthand: Shorthand Options
  • options, warnings: Warning Options
  • Or intrinsic: Bit Operations on Floating-point Data
  • Or intrinsic: Or Intrinsic
  • order of evaluation, side effects: Order of Side Effects
  • ordering, array: Arrays
  • other intrinsics: Other Intrinsics
  • output, flushing: Output Assumed To Flush
  • overall options: Overall Options
  • overflow: Warning Options
  • overlapping arguments: Aliasing Assumed To Work
  • overlays: Aliasing Assumed To Work
  • overly convenient options: Overly Convenient Options
  • overwritten data: Strange Behavior at Run Time
  • Pack intrinsic: Pack Intrinsic
  • padding: Known Bugs
  • parallel processing: Support for Threads
  • PARAMETER statement: Old-style PARAMETER Statements, Intrinsics in PARAMETER Statements
  • parameters, unused: Warning Options
  • paths, search: Directory Options
  • PDB: Portable Unformatted Files
  • pedantic compilation: Pedantic Compilation
  • Pentium optimizations: Aligned Data
  • percent sign: Character Set
  • PError intrinsic: PError Intrinsic
  • placing initialization statements: Initializing Before Specifying
  • POINTER statement: POINTER Statements
  • pointers: Ugly Assigned Labels, Kind Notation
  • Poking the bear: Philosophy of Code Generation
  • porting, simplify: Simplify Porting
  • pound sign: Character Set
  • Precision intrinsic: Precision Intrinsic
  • precision, increasing: Increasing Precision/Range
  • prefix-radix constants: Fortran Dialect Options
  • preprocessor: LEX, Bug Reporting, Cpp-style directives, Overall Options, What is GNU Fortran?
  • preprocessor options: Preprocessor Options
  • Present intrinsic: Present Intrinsic
  • printing compilation status: Overall Options
  • printing main source: Known Bugs
  • printing version information: Overall Options, What is GNU Fortran?
  • procedures: Procedures
  • Product intrinsic: Product Intrinsic
  • PROGRAM statement: Main Program Unit
  • programs, cc1: What is GNU Fortran?
  • programs, cc1plus: What is GNU Fortran?
  • programs, compiling: G77 and GCC
  • programs, cpp: LEX, Bug Reporting, Preprocessor Options, Overall Options, What is GNU Fortran?
  • programs, f771: What is GNU Fortran?
  • programs, ratfor: Overall Options
  • programs, speeding up: Faster Programs
  • programs, test: Nothing Happens
  • projects: Projects
  • Q edit descriptor: Q Edit Descriptor
  • QAbs intrinsic: QAbs Intrinsic
  • QACos intrinsic: QACos Intrinsic
  • QACosD intrinsic: QACosD Intrinsic
  • QASin intrinsic: QASin Intrinsic
  • QASinD intrinsic: QASinD Intrinsic
  • QATan intrinsic: QATan Intrinsic
  • QATan2 intrinsic: QATan2 Intrinsic
  • QATan2D intrinsic: QATan2D Intrinsic
  • QATanD intrinsic: QATanD Intrinsic
  • QCos intrinsic: QCos Intrinsic
  • QCosD intrinsic: QCosD Intrinsic
  • QCosH intrinsic: QCosH Intrinsic
  • QDiM intrinsic: QDiM Intrinsic
  • QExp intrinsic: QExp Intrinsic
  • QExt intrinsic: QExt Intrinsic
  • QExtD intrinsic: QExtD Intrinsic
  • QFloat intrinsic: QFloat Intrinsic
  • QInt intrinsic: QInt Intrinsic
  • QLog intrinsic: QLog Intrinsic
  • QLog10 intrinsic: QLog10 Intrinsic
  • QMax1 intrinsic: QMax1 Intrinsic
  • QMin1 intrinsic: QMin1 Intrinsic
  • QMod intrinsic: QMod Intrinsic
  • QNInt intrinsic: QNInt Intrinsic
  • QSin intrinsic: QSin Intrinsic
  • QSinD intrinsic: QSinD Intrinsic
  • QSinH intrinsic: QSinH Intrinsic
  • QSqRt intrinsic: QSqRt Intrinsic
  • QTan intrinsic: QTan Intrinsic
  • QTanD intrinsic: QTanD Intrinsic
  • QTanH intrinsic: QTanH Intrinsic
  • question mark: Character Set
  • questionable instructions: What is GNU Fortran?
  • Radix intrinsic: Radix Intrinsic
  • Rand intrinsic: Rand Intrinsic
  • Random_Number intrinsic: Random_Number Intrinsic
  • Random_Seed intrinsic: Random_Seed Intrinsic
  • range checking: Code Gen Options
  • Range intrinsic: Range Intrinsic
  • range, increasing: Increasing Precision/Range
  • rank, maximum: Compiler Limits
  • ratfor: Overall Options
  • Ratfor preprocessor: Overall Options
  • READONLY: READONLY Keyword
  • reads and writes, scheduling: Aliasing Assumed To Work
  • Real intrinsic: Real Intrinsic
  • Real intrinsic: REAL() and AIMAG() of Complex
  • real part: Ugly Complex Part Extraction
  • REAL(KIND=1) type: Compiler Types
  • REAL(KIND=2) type: Compiler Types
  • REAL*16 support: Full Support for Compiler Types
  • RealPart intrinsic: RealPart Intrinsic
  • recent versions: Changes, News
  • RECORD statement: STRUCTURE UNION RECORD MAP
  • recursion, lack of: RECURSIVE Keyword
  • RECURSIVE keyword: RECURSIVE Keyword
  • reference works: Language
  • Rename intrinsic: Rename Intrinsic (function), Rename Intrinsic (subroutine)
  • Repeat intrinsic: Repeat Intrinsic
  • reporting bugs: Bugs
  • reporting compilation status: Overall Options
  • Reshape intrinsic: Reshape Intrinsic
  • results, inconsistent: Floating-point Errors
  • RETURN statement: Alternate Returns, Functions
  • return type of functions: Functions
  • right angle: Character Set
  • right bracket: Character Set
  • rounding errors: Floating-point Errors
  • row-major ordering: Arrays
  • RRSpacing intrinsic: RRSpacing Intrinsic
  • RShift intrinsic: RShift Intrinsic
  • run-time, dynamic allocation: Arbitrary Concatenation
  • run-time, initialization: Startup Code
  • run-time, library: What is GNU Fortran?
  • run-time, options: Code Gen Options
  • SAVE statement: Code Gen Options
  • saved variables: Variables Assumed To Be Saved
  • Scale intrinsic: Scale Intrinsic
  • Scan intrinsic: Scan Intrinsic
  • scheduling of reads and writes: Aliasing Assumed To Work
  • scope: Scope and Classes of Names, Scope of Names and Labels
  • search path: Directory Options
  • search paths, for included files: Directory Options
  • Secnds intrinsic: Secnds Intrinsic
  • Second intrinsic: Second Intrinsic (subroutine), Second Intrinsic (function)
  • segmentation violation: Strange Behavior at Run Time, Stack Overflow, NeXTStep Problems
  • Selected_Int_Kind intrinsic: Selected_Int_Kind Intrinsic
  • Selected_Real_Kind intrinsic: Selected_Real_Kind Intrinsic
  • semicolon: Character Set, Statements Comments Lines
  • sequence numbers: Better Source Model
  • Set_Exponent intrinsic: Set_Exponent Intrinsic
  • Shape intrinsic: Shape Intrinsic
  • SHARED: READONLY Keyword
  • Shift intrinsic: Bit Operations on Floating-point Data
  • Short intrinsic: Short Intrinsic
  • short source lines: Short Lines
  • short time: Timer Wraparounds
  • shorthand options: Shorthand Options
  • side effects, order of evaluation: Order of Side Effects
  • Sign intrinsic: Sign Intrinsic
  • signal 11: Signal 11 and Friends
  • Signal intrinsic: Signal Intrinsic (function), Signal Intrinsic (subroutine)
  • signature of procedures: Procedures
  • simplify porting: Simplify Porting
  • Sin intrinsic: Sin Intrinsic
  • SinD intrinsic: SinD Intrinsic
  • SinH intrinsic: SinH Intrinsic
  • Sleep intrinsic: Sleep Intrinsic
  • Sngl intrinsic: Sngl Intrinsic
  • SnglQ intrinsic: SnglQ Intrinsic
  • Solaris: Strange Behavior at Run Time
  • source code: Case Sensitivity, Source Form, Lines, What is GNU Fortran?
  • source file: What is GNU Fortran?
  • source file format: Case Sensitivity, Source Form, Lines, Fortran Dialect Options
  • source format: Source Form, Lines
  • source lines, long: Long Lines
  • source lines, short: Short Lines
  • space: Lines, Character Set
  • space, endless printing of: Strange Behavior at Run Time
  • space, padding with: Short Lines
  • Spacing intrinsic: Spacing Intrinsic
  • SPC: Lines, Character Set
  • speed, of compiler: Known Bugs
  • speed, of loops: Optimize Options
  • speed, of programs: Faster Programs
  • spills of floating-point results: Floating-point Errors
  • Spread intrinsic: Spread Intrinsic
  • SqRt intrinsic: SqRt Intrinsic
  • SRand intrinsic: SRand Intrinsic
  • stack, 387 coprocessor: News
  • stack, aligned: Aligned Data
  • stack, overflow: Stack Overflow
  • standard, ANSI FORTRAN 77: Language
  • standard, support for: Standard Support
  • startup code: Startup Code
  • Stat intrinsic: Stat Intrinsic (function), Stat Intrinsic (subroutine)
  • statement labels, assigned: Assigned Statement Labels
  • statements, ACCEPT: TYPE and ACCEPT I/O Statements
  • statements, ASSIGN: Assigned Statement Labels, Ugly Assigned Labels
  • statements, AUTOMATIC: AUTOMATIC Statement
  • statements, BLOCK DATA: Multiple Definitions of External Names, Block Data and Libraries
  • statements, CLOSE: OPEN CLOSE and INQUIRE Keywords
  • statements, COMMON: Multiple Definitions of External Names, Common Blocks
  • statements, COMPLEX: Complex Variables
  • statements, CYCLE: CYCLE and EXIT
  • statements, DATA: Known Bugs, Code Gen Options
  • statements, DECODE: ENCODE and DECODE
  • statements, DIMENSION: Array Bounds Expressions
  • statements, DIMENSION: Adjustable Arrays, Arrays
  • statements, DO: Loops, Warning Options
  • statements, ENCODE: ENCODE and DECODE
  • statements, ENTRY: Alternate Entry Points
  • statements, EQUIVALENCE: Local Equivalence Areas
  • statements, EXIT: CYCLE and EXIT
  • statements, FORMAT: Expressions in FORMAT Statements
  • statements, FUNCTION: Functions, Procedures
  • statements, GOTO: Assigned Statement Labels
  • statements, IMPLICIT CHARACTER*(*): Limitation on Implicit Declarations
  • statements, INQUIRE: OPEN CLOSE and INQUIRE Keywords
  • statements, MAP: STRUCTURE UNION RECORD MAP
  • statements, NAMELIST: NAMELIST
  • statements, OPEN: OPEN CLOSE and INQUIRE Keywords
  • statements, PARAMETER: Old-style PARAMETER Statements, Intrinsics in PARAMETER Statements
  • statements, POINTER: POINTER Statements
  • statements, PROGRAM: Main Program Unit
  • statements, RECORD: STRUCTURE UNION RECORD MAP
  • statements, RETURN: Alternate Returns, Functions
  • statements, SAVE: Code Gen Options
  • statements, separated by semicolon: Statements Comments Lines
  • statements, STRUCTURE: STRUCTURE UNION RECORD MAP
  • statements, SUBROUTINE: Alternate Returns, Procedures
  • statements, TYPE: TYPE and ACCEPT I/O Statements
  • statements, UNION: STRUCTURE UNION RECORD MAP
  • STATIC: AUTOMATIC Statement
  • static variables: Variables Assumed To Be Saved
  • status, compilation: Overall Options
  • storage association: Aliasing Assumed To Work
  • strings, empty: Character Type
  • STRUCTURE statement: STRUCTURE UNION RECORD MAP
  • structures: Known Bugs
  • submodels: Use Submodel Options
  • SUBROUTINE statement: Alternate Returns, Procedures
  • subroutines: Alternate Returns
  • subscript checking: Code Gen Options
  • substring checking: Code Gen Options
  • suffixes, file name: Overall Options
  • Sum intrinsic: Sum Intrinsic
  • support, Alpha: Known Bugs
  • support, ELF: News
  • support, f77: Backslash in Constants
  • support, FORTRAN 77: Standard Support
  • support, Fortran 90: Fortran 90 Support
  • support, gdb: Debugger Problems
  • suppressing warnings: Warning Options
  • symbol names: Names, Fortran Dialect Options
  • symbol names, scope and classes: Scope and Classes of Names
  • symbol names, transforming: Code Gen Options
  • symbol names, underscores: Code Gen Options
  • SymLnk intrinsic: SymLnk Intrinsic (function), SymLnk Intrinsic (subroutine)
  • synchronous write errors: Output Assumed To Flush
  • syntax checking: Warning Options
  • System intrinsic: System Intrinsic (function), System Intrinsic (subroutine)
  • System_Clock intrinsic: System_Clock Intrinsic
  • tab character: Tabs
  • table of intrinsics: Table of Intrinsic Functions
  • Tan intrinsic: Tan Intrinsic
  • TanD intrinsic: TanD Intrinsic
  • TanH intrinsic: TanH Intrinsic
  • test programs: Nothing Happens
  • testing alignment: Aligned Data
  • textbooks: Language
  • threads: Support for Threads
  • Time intrinsic: Time Intrinsic (VXT), Time Intrinsic (UNIX)
  • Time8 intrinsic: Time8 Intrinsic
  • Tiny intrinsic: Tiny Intrinsic
  • Toolpack: Increasing Precision/Range
  • trailing comma: Ugly Null Arguments
  • trailing comment: LEX, Trailing Comment, Statements Comments Lines
  • trailing null byte: Character and Hollerith Constants
  • Transfer intrinsic: Transfer Intrinsic
  • transforming symbol names: Names, Code Gen Options
  • translation of user programs: What is GNU Fortran?
  • Transpose intrinsic: Transpose Intrinsic
  • Trim intrinsic: Trim Intrinsic
  • trips, number of: Loops
  • truncation, of floating-point values: Floating-point Errors
  • truncation, of long lines: Long Lines
  • TtyNam intrinsic: TtyNam Intrinsic (function), TtyNam Intrinsic (subroutine)
  • TYPE statement: TYPE and ACCEPT I/O Statements
  • types, COMPLEX(KIND=1): Compiler Types
  • types, COMPLEX(KIND=2): Compiler Types
  • types, constants: Compiler Constants, Constants, Fortran Dialect Options
  • types, DOUBLE COMPLEX: Compiler Types
  • types, DOUBLE PRECISION: Compiler Types
  • types, file: Overall Options
  • types, Fortran/C: C Access to Type Information
  • types, INTEGER(KIND=1): Compiler Types
  • types, INTEGER(KIND=2): Compiler Types
  • types, INTEGER(KIND=3): Compiler Types
  • types, INTEGER(KIND=6): Compiler Types
  • types, INTEGER*2: Popular Non-standard Types
  • types, INTEGER*8: Full Support for Compiler Types
  • types, LOGICAL(KIND=1): Compiler Types
  • types, LOGICAL(KIND=2): Compiler Types
  • types, LOGICAL(KIND=3): Compiler Types
  • types, LOGICAL(KIND=6): Compiler Types
  • types, LOGICAL*1: Popular Non-standard Types
  • types, of data: Compiler Types
  • types, REAL(KIND=1): Compiler Types
  • types, REAL(KIND=2): Compiler Types
  • types, REAL*16: Full Support for Compiler Types
  • UBound intrinsic: UBound Intrinsic
  • ugly features: Distensions, Shorthand Options
  • UMask intrinsic: UMask Intrinsic (function), UMask Intrinsic (subroutine)
  • undefined behavior: Bug Criteria
  • undefined function value: Bug Criteria
  • undefined reference (_main): Cannot Link Fortran Programs
  • underscore: Mangling of Names, Underscores in Symbol Names, Character Set, Code Gen Options
  • unformatted files: Portable Unformatted Files
  • uninitialized variables: Variables Assumed To Be Zero, Code Gen Options, Warning Options
  • UNION statement: STRUCTURE UNION RECORD MAP
  • unit numbers: Large File Unit Numbers
  • UNIX f77: Shorthand Options
  • UNIX intrinsics: Fortran Dialect Options
  • Unlink intrinsic: Unlink Intrinsic (function), Unlink Intrinsic (subroutine)
  • Unpack intrinsic: Unpack Intrinsic
  • unrecognized file format: What is GNU Fortran?
  • unresolved reference (various): Cannot Link Fortran Programs
  • unrolling loops: Optimize Options
  • UNSAVE: AUTOMATIC Statement
  • unsupported warnings: Warning Options
  • unused arguments: Unused Arguments, Warning Options
  • unused dummies: Warning Options
  • unused parameters: Warning Options
  • unused variables: Warning Options
  • uppercase letters: Case Sensitivity
  • user-visible changes: Changes
  • variables, assumed to be zero: Variables Assumed To Be Zero
  • variables, automatic: AUTOMATIC Statement
  • variables, initialization of: Code Gen Options
  • variables, mistyped: Not My Type
  • variables, retaining values across calls: Variables Assumed To Be Saved
  • variables, uninitialized: Code Gen Options, Warning Options
  • variables, unused: Warning Options
  • Verify intrinsic: Verify Intrinsic
  • version information, printing: Overall Options, What is GNU Fortran?
  • versions, recent: Changes, News
  • VXT extensions: VXT Fortran, Fortran Dialect Options
  • VXT intrinsics: Fortran Dialect Options
  • vxtidate_y2kbuggy_0: Year 2000 (Y2K) Problems
  • warnings: What is GNU Fortran?
  • warnings vs errors: Warnings and Errors
  • warnings, all: Warning Options
  • warnings, extra: Warning Options
  • warnings, global names: Code Gen Options, Warning Options
  • warnings, implicit declaration: Warning Options
  • warnings, suppressing: Warning Options
  • warnings, unsupported: Warning Options
  • wisdom: Collected Fortran Wisdom
  • wraparound: Run-time Environment Limits
  • wraparound, timings: Secnds Intrinsic, DTime Intrinsic (function), Time8 Intrinsic, Time Intrinsic (UNIX), System_Clock Intrinsic, Second Intrinsic (subroutine), Second Intrinsic (function), MClock8 Intrinsic, MClock Intrinsic, ETime Intrinsic (function), ETime Intrinsic (subroutine), DTime Intrinsic (subroutine), CPU_Time Intrinsic
  • wraparound, Y10K: Time Intrinsic (VXT), IDate Intrinsic (UNIX), FDate Intrinsic (function), FDate Intrinsic (subroutine), Date_and_Time Intrinsic
  • wraparound, Y2K: IDate Intrinsic (VXT)
  • writes, flushing: Output Assumed To Flush
  • writing code: Collected Fortran Wisdom
  • x86 floating-point: Floating-point precision
  • x86 FPU stack: Inconsistent Calling Sequences
  • XOr intrinsic: XOr Intrinsic
  • Y10K compliance: Time Intrinsic (VXT), Year 10000 (Y10K) Problems, IDate Intrinsic (UNIX), FDate Intrinsic (function), FDate Intrinsic (subroutine), Date_and_Time Intrinsic
  • Y2K compliance: Y2KBAD, IDate Intrinsic (VXT), Date Intrinsic, Year 2000 (Y2K) Problems
  • y2kbuggy: Year 2000 (Y2K) Problems
  • Year 10000 compliance: Time Intrinsic (VXT), Year 10000 (Y10K) Problems, IDate Intrinsic (UNIX), FDate Intrinsic (function), FDate Intrinsic (subroutine), Date_and_Time Intrinsic
  • Year 2000 compliance: Y2KBAD, IDate Intrinsic (VXT), Date Intrinsic, Year 2000 (Y2K) Problems
  • Z edit descriptor: Fortran 90 Features, I/O
  • ZAbs intrinsic: ZAbs Intrinsic
  • ZCos intrinsic: ZCos Intrinsic
  • zero byte, trailing: Character and Hollerith Constants
  • zero-initialized variables: Variables Assumed To Be Zero
  • zero-length CHARACTER: Character Type
  • zero-trip DO loops: Fortran Dialect Options
  • ZExp intrinsic: ZExp Intrinsic
  • ZExt intrinsic: ZExt Intrinsic
  • ZLog intrinsic: ZLog Intrinsic
  • ZSin intrinsic: ZSin Intrinsic
  • ZSqRt intrinsic: ZSqRt Intrinsic


Node:Index Intrinsic, Next:Int Intrinsic, Previous:ImagPart Intrinsic, Up:Table of Intrinsic Functions

Index Intrinsic

Index(String, Substring)

Index: INTEGER(KIND=1) function.

String: CHARACTER; scalar; INTENT(IN).

Substring: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the position of the start of the first occurrence of string Substring as a substring in String, counting from one. If Substring doesn't occur in String, zero is returned.


Node:Informational Messages, Next:Uninitialized Variables at Run Time, Previous:Unused Labels, Up:Missing Features

Informational Messages

g77 needs an option to suppress information messages (notes). -w does this but also suppresses warnings. The default should be to suppress info messages.

Perhaps info messages should simply be eliminated.


Node:INInt Intrinsic, Next:INot Intrinsic, Previous:IMod Intrinsic, Up:Other Intrinsics

INInt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL INInt to use this name for an external procedure.


Node:Initializing Before Specifying, Next:Context-Sensitive Intrinsicness, Previous:Backslash in Constants, Up:Non-bugs

Initializing Before Specifying

g77 does not allow DATA VAR/1/ to appear in the source code before COMMON VAR, DIMENSION VAR(10), INTEGER VAR, and so on. In general, g77 requires initialization of a variable or array to be specified after all other specifications of attributes (type, size, placement, and so on) of that variable or array are specified (though confirmation of data type is permitted).

It is possible g77 will someday allow all of this, even though it is not allowed by the FORTRAN 77 standard.

Then again, maybe it is better to have g77 always require placement of DATA so that it can possibly immediately write constants to the output file, thus saving time and space.

That is, DATA A/1000000*1/ should perhaps always be immediately writable to canonical assembler, unless it's already known to be in a COMMON area following as-yet-uninitialized stuff, and to do this it cannot be followed by COMMON A.


Node:INot Intrinsic, Next:IZExt Intrinsic, Previous:INInt Intrinsic, Up:Other Intrinsics

INot Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL INot to use this name for an external procedure.


Node:Int Intrinsic, Next:Int2 Intrinsic, Previous:Index Intrinsic, Up:Table of Intrinsic Functions

Int Intrinsic

Int(A)

Int: INTEGER(KIND=1) function.

A: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns A with the fractional portion of its magnitude truncated and its sign preserved, converted to type INTEGER(KIND=1).

If A is type COMPLEX, its real part is truncated and converted, and its imaginary part is disregarded.

See NInt Intrinsic, for how to convert, rounded to nearest whole number.

See AInt Intrinsic, for how to truncate to whole number without converting.


Node:Int2 Intrinsic, Next:Int8 Intrinsic, Previous:Int Intrinsic, Up:Table of Intrinsic Functions

Int2 Intrinsic

Int2(A)

Int2: INTEGER(KIND=6) function.

A: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: gnu.

Description:

Returns A with the fractional portion of its magnitude truncated and its sign preserved, converted to type INTEGER(KIND=6).

If A is type COMPLEX, its real part is truncated and converted, and its imaginary part is disgregarded.

See Int Intrinsic.

The precise meaning of this intrinsic might change in a future version of the GNU Fortran language, as more is learned about how it is used.


Node:Int8 Intrinsic, Next:IOr Intrinsic, Previous:Int2 Intrinsic, Up:Table of Intrinsic Functions

Int8 Intrinsic

Int8(A)

Int8: INTEGER(KIND=2) function.

A: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: gnu.

Description:

Returns A with the fractional portion of its magnitude truncated and its sign preserved, converted to type INTEGER(KIND=2).

If A is type COMPLEX, its real part is truncated and converted, and its imaginary part is disgregarded.

See Int Intrinsic.

The precise meaning of this intrinsic might change in a future version of the GNU Fortran language, as more is learned about how it is used.


Node:Integer Type, Next:Character Type, Previous:Constants, Up:Data Types and Constants

Integer Type

(Corresponds to Section 4.3 of ANSI X3.9-1978 FORTRAN 77.)

An integer constant also may have one of the following forms:

B'binary-digits'
O'octal-digits'
Z'hexadecimal-digits'
X'hexadecimal-digits'

binary-digits, octal-digits, and hexadecimal-digits are nonempty strings of characters in the set 01, 01234567, and 0123456789ABCDEFabcdef, respectively. (The value for A (and a) is 10, for B and b is 11, and so on.)


Node:Internal Naming Conventions, Previous:Transforming Expressions, Up:Front End

Internal Naming Conventions

Names exported by FFE modules have the following (regular-expression) forms. Note that all names beginning ffemod or FFEmod, where mod is lowercase or uppercase alphanumerics, respectively, are exported by the module ffemod, with the source code doing the exporting in mod.h. (Usually, the source code for the implementation is in mod.c.)

Identifiers that don't fit the following forms are not considered exported, even if they are according to the C language. (For example, they might be made available to other modules solely for use within expansions of exported macros, not for use within any source code in those other modules.)

ffemod
The single typedef exported by the module.
FFEumod_[A-Z][A-Z0-9_]*
(Where umod is the uppercase for of mod.)

A #define or enum constant of the type ffemod.

ffemod[A-Z][A-Z][a-z0-9]*
A typedef exported by the module.

The portion of the identifier after ffemod is referred to as ctype, a capitalized (mixed-case) form of type.

FFEumod_type[A-Z][A-Z0-9_]*[A-Z0-9]?
(Where umod is the uppercase for of mod.)

A #define or enum constant of the type ffemodtype, where type is the lowercase form of ctype in an exported typedef.

ffemod_value
A function that does or returns something, as described by value (see below).
ffemod_value_input
A function that does or returns something based primarily on the thing described by input (see below).

Below are names used for value and input, along with their definitions.

col
A column number within a line (first column is number 1).
file
An encapsulation of a file's name.
find
Looks up an instance of some type that matches specified criteria, and returns that, even if it has to create a new instance or crash trying to find it (as appropriate).
initialize
Initializes, usually a module. No type.
int
A generic integer of type int.
is
A generic integer that contains a true (non-zero) or false (zero) value.
len
A generic integer that contains the length of something.
line
A line number within a source file, or a global line number.
lookup
Looks up an instance of some type that matches specified criteria, and returns that, or returns nil.
name
A text that points to a name of something.
new
Makes a new instance of the indicated type. Might return an existing one if appropriate--if so, similar to find without crashing.
pt
Pointer to a particular character (line, column pairs) in the input file (source code being compiled).
run
Performs some herculean task. No type.
terminate
Terminates, usually a module. No type.
text
A char * that points to generic text.


Node:Internals Documentation, Next:Internals Improvements, Previous:Machine Model, Up:Projects

Internals Documentation

Better info on how g77 works and how to port it is needed.

See Front End, which contains some information on g77 internals.


Node:Internals Improvements, Next:Better Diagnostics, Previous:Internals Documentation, Up:Projects

Internals Improvements

Some more items that would make g77 more reliable and easier to maintain:

  • Generally make expression handling focus more on critical syntax stuff, leaving semantics to callers. For example, anything a caller can check, semantically, let it do so, rather than having expr.c do it. (Exceptions might include things like diagnosing FOO(I--K:)=BAR where FOO is a PARAMETER--if it seems important to preserve the left-to-right-in-source order of production of diagnostics.)
  • Come up with better naming conventions for -D to establish requirements to achieve desired implementation dialect via proj.h.
  • Clean up used tokens and ffewheres in ffeglobal_terminate_1.
  • Replace sta.c outpooldisp mechanism with malloc_pool_use.
  • Check for opANY in more places in com.c, std.c, and ste.c, and get rid of the opCONVERT(opANY) kludge (after determining if there is indeed no real need for it).
  • Utility to read and check bad.def messages and their references in the code, to make sure calls are consistent with message templates.
  • Search and fix &ffe... and similar so that ffe...ptr... macros are available instead (a good argument for wishing this could have written all this stuff in C++, perhaps). On the other hand, it's questionable whether this sort of improvement is really necessary, given the availability of tools such as Emacs and Perl, which make finding any address-taking of structure members easy enough?
  • Some modules truly export the member names of their structures (and the structures themselves), maybe fix this, and fix other modules that just appear to as well (by appending _, though it'd be ugly and probably not worth the time).
  • Implement C macros RETURNS(value) and SETS(something,value) in proj.h and use them throughout g77 source code (especially in the definitions of access macros in .h files) so they can be tailored to catch code writing into a RETURNS() or reading from a SETS().
  • Decorate throughout with const and other such stuff.
  • All F90 notational derivations in the source code are still based on the S8.112 version of the draft standard. Probably should update to the official standard, or put documentation of the rules as used in the code...uh...in the code.
  • Some ffebld_new calls (those outside of ffeexpr.c or inside but invoked via paths not involving ffeexpr_lhs or ffeexpr_rhs) might be creating things in improper pools, leading to such things staying around too long or (doubtful, but possible and dangerous) not long enough.
  • Some ffebld_list_new (or whatever) calls might not be matched by ffebld_list_bottom (or whatever) calls, which might someday matter. (It definitely is not a problem just yet.)
  • Probably not doing clean things when we fail to EQUIVALENCE something due to alignment/mismatch or other problems--they end up without ffestorag objects, so maybe the backend (and other parts of the front end) can notice that and handle like an opANY (do what it wants, just don't complain or crash). Most of this seems to have been addressed by now, but a code review wouldn't hurt.


Node:Interoperating with C and C++, Up:Other Languages

Tools and advice for interoperating with C and C++

The following discussion assumes that you are running g77 in f2c compatibility mode, i.e. not using -fno-f2c. It provides some advice about quick and simple techniques for linking Fortran and C (or C++), the most common requirement. For the full story consult the description of code generation. See Debugging and Interfacing.

When linking Fortran and C, it's usually best to use g77 to do the linking so that the correct libraries are included (including the maths one). If you're linking with C++ you will want to add -lstdc++, -lg++ or whatever. If you need to use another driver program (or ld directly), you can find out what linkage options g77 passes by running g77 -v.

  • C Interfacing Tools:
  • C Access to Type Information:
  • f2c Skeletons and Prototypes:
  • C++ Considerations:
  • Startup Code:


Node:INTGLOB, Next:LEX, Previous:EXPIMP, Up:Diagnostics

INTGLOB

Same name `intrinsic' given ...

The name intrinsic is used for a global entity (a common block or a program unit) in one program unit and implicitly used as an intrinsic in another program unit.

This diagnostic is designed to catch cases where a program intends to use a name entirely as a global name, but g77 recognizes the name as an intrinsic in the program unit that references the name, a situation that would likely produce incorrect code.

For example:

INTEGER FUNCTION TIME()
...
END
...
PROGRAM SAMP
INTEGER TIME
PRINT *, 'Time is ', TIME()
END

The above example defines a program unit named TIME, but the reference to TIME in the main program unit SAMP is normally treated by g77 as a reference to the intrinsic TIME() (unless a command-line option that prevents such treatment has been specified).

As a result, the program SAMP will not invoke the TIME function in the same source file.

Since g77 recognizes libU77 procedures as intrinsics, and since some existing code uses the same names for its own procedures as used by some libU77 procedures, this situation is expected to arise often enough to make this sort of warning worth issuing.

After verifying that the program unit making implicit use of the intrinsic is indeed written expecting the intrinsic, add an INTRINSIC intrinsic statement to that program unit to prevent this warning.

Or, if you believe the program unit is designed to invoke the program-defined procedure instead of the intrinsic (as recognized by g77), add an EXTERNAL intrinsic statement to the program unit that references the name to prevent this warning.

This and related warnings are disabled by using the -Wno-globals option when compiling.

Note that this warning is not issued for standard intrinsics. Standard intrinsics include those described in the FORTRAN 77 standard and, if -ff90 is specified, those described in the Fortran 90 standard. Such intrinsics are not as likely to be confused with user procedures as intrinsics provided as extensions to the standard by g77.


Node:Intrinsic Groups, Next:Other Intrinsics, Up:Compiler Intrinsics

Intrinsic Groups

A given specific intrinsic belongs in one or more groups. Each group is deleted, disabled, hidden, or enabled by default or a command-line option. The meaning of each term follows.

Deleted
No intrinsics are recognized as belonging to that group.
Disabled
Intrinsics are recognized as belonging to the group, but references to them (other than via the INTRINSIC statement) are disallowed through that group.
Hidden
Intrinsics in that group are recognized and enabled (if implemented) only if the first mention of the actual name of an intrinsic in a program unit is in an INTRINSIC statement.
Enabled
Intrinsics in that group are recognized and enabled (if implemented).

The distinction between deleting and disabling a group is illustrated by the following example. Assume intrinsic FOO belongs only to group FGR. If group FGR is deleted, the following program unit will successfully compile, because FOO() will be seen as a reference to an external function named FOO:

PRINT *, FOO()
END

If group FGR is disabled, compiling the above program will produce diagnostics, either because the FOO intrinsic is improperly invoked or, if properly invoked, it is not enabled. To change the above program so it references an external function FOO instead of the disabled FOO intrinsic, add the following line to the top:

EXTERNAL FOO

So, deleting a group tells g77 to pretend as though the intrinsics in that group do not exist at all, whereas disabling it tells g77 to recognize them as (disabled) intrinsics in intrinsic-like contexts.

Hiding a group is like enabling it, but the intrinsic must be first named in an INTRINSIC statement to be considered a reference to the intrinsic rather than to an external procedure. This might be the "safest" way to treat a new group of intrinsics when compiling old code, because it allows the old code to be generally written as if those new intrinsics never existed, but to be changed to use them by inserting INTRINSIC statements in the appropriate places. However, it should be the goal of development to use EXTERNAL for all names of external procedures that might be intrinsic names.

If an intrinsic is in more than one group, it is enabled if any of its containing groups are enabled; if not so enabled, it is hidden if any of its containing groups are hidden; if not so hidden, it is disabled if any of its containing groups are disabled; if not so disabled, it is deleted. This extra complication is necessary because some intrinsics, such as IBITS, belong to more than one group, and hence should be enabled if any of the groups to which they belong are enabled, and so on.

The groups are:

badu77
UNIX intrinsics having inappropriate forms (usually functions that have intended side effects).
gnu
Intrinsics the GNU Fortran language supports that are extensions to the Fortran standards (77 and 90).
f2c
Intrinsics supported by AT&T's f2c converter and/or libf2c.
f90
Fortran 90 intrinsics.
mil
MIL-STD 1753 intrinsics (MVBITS, IAND, BTEST, and so on).
unix
UNIX intrinsics (IARGC, EXIT, ERF, and so on).
vxt
VAX/VMS FORTRAN (current as of v4) intrinsics.


Node:Intrinsics in PARAMETER Statements, Next:Arbitrary Concatenation, Previous:Fortran 90 Support, Up:Missing Features

Intrinsics in PARAMETER Statements

g77 doesn't allow intrinsics in PARAMETER statements.

Related to this, g77 doesn't allow non-integral exponentiation in PARAMETER statements, such as PARAMETER (R=2**.25). It is unlikely g77 will ever support this feature, as doing it properly requires complete emulation of a target computer's floating-point facilities when building g77 as a cross-compiler. But, if the gcc back end is enhanced to provide such a facility, g77 will likely use that facility in implementing this feature soon afterwards.


Node:Invalid FORMAT Specifiers, Next:Ambiguous Dialects, Previous:Dummy Array Without Dimensioning Dummy, Up:Missing Features

Invalid FORMAT Specifiers

g77 should check FORMAT specifiers for validity as it does FORMAT statements.

For example, a diagnostic would be produced for:

PRINT 'HI THERE!'  !User meant PRINT *, 'HI THERE!'


Node:Invalid Use of Hollerith Constant, Next:Dummy Array Without Dimensioning Dummy, Previous:Warn About Implicit Conversions, Up:Missing Features

Invalid Use of Hollerith Constant

g77 should disallow statements like RETURN 2HAB, which are invalid in both source forms (unlike RETURN (2HAB), which probably still makes no sense but at least can be reliably parsed). Fixed-form processing rejects it, but not free-form, except in a way that is a bit difficult to understand.


Node:Invoking G77, Next:News, Previous:G77 and GCC, Up:Top

GNU Fortran Command Options

The g77 command supports all the options supported by the gcc command. See GCC Command Options, for information on the non-Fortran-specific aspects of the gcc command (and, therefore, the g77 command).

All gcc and g77 options are accepted both by g77 and by gcc (as well as any other drivers built at the same time, such as g++), since adding g77 to the gcc distribution enables acceptance of g77 options by all of the relevant drivers.

In some cases, options have positive and negative forms; the negative form of -ffoo would be -fno-foo. This manual documents only one of these two forms, whichever one is not the default.

  • Option Summary: Brief list of all g77 options, without explanations.
  • Overall Options: Controlling the kind of output: an executable, object files, assembler files, or preprocessed source.
  • Shorthand Options: Options that are shorthand for other options.
  • Fortran Dialect Options: Controlling the variant of Fortran language compiled.
  • Warning Options: How picky should the compiler be?
  • Debugging Options: Symbol tables, measurements, and debugging dumps.
  • Optimize Options: How much optimization?
  • Preprocessor Options: Controlling header files and macro definitions. Also, getting dependency information for Make.
  • Directory Options: Where to find header files and libraries. Where to find the compiler executable files.
  • Code Gen Options: Specifying conventions for function calls, data layout and register usage.
  • Environment Variables: Env vars that affect GNU Fortran.


Node:IOr Intrinsic, Next:IRand Intrinsic, Previous:Int8 Intrinsic, Up:Table of Intrinsic Functions

IOr Intrinsic

IOr(I, J)

IOr: INTEGER function, the exact type being the result of cross-promoting the types of all the arguments.

I: INTEGER; scalar; INTENT(IN).

J: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Returns value resulting from boolean OR of pair of bits in each of I and J.


Node:IRand Intrinsic, Next:IsaTty Intrinsic, Previous:IOr Intrinsic, Up:Table of Intrinsic Functions

IRand Intrinsic

IRand(Flag)

IRand: INTEGER(KIND=1) function.

Flag: INTEGER; OPTIONAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns a uniform quasi-random number up to a system-dependent limit. If Flag is 0, the next number in sequence is returned; if Flag is 1, the generator is restarted by calling the UNIX function srand(0); if Flag has any other value, it is used as a new seed with srand().

See SRand Intrinsic.

Note: As typically implemented (by the routine of the same name in the C library), this random number generator is a very poor one, though the BSD and GNU libraries provide a much better implementation than the `traditional' one. On a different system you almost certainly want to use something better.


Node:IsaTty Intrinsic, Next:IShft Intrinsic, Previous:IRand Intrinsic, Up:Table of Intrinsic Functions

IsaTty Intrinsic

IsaTty(Unit)

IsaTty: LOGICAL(KIND=1) function.

Unit: INTEGER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns .TRUE. if and only if the Fortran I/O unit specified by Unit is connected to a terminal device. See isatty(3).


Node:IShft Intrinsic, Next:IShftC Intrinsic, Previous:IsaTty Intrinsic, Up:Table of Intrinsic Functions

IShft Intrinsic

IShft(I, Shift)

IShft: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar; INTENT(IN).

Shift: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

All bits representing I are shifted Shift places. Shift.GT.0 indicates a left shift, Shift.EQ.0 indicates no shift and Shift.LT.0 indicates a right shift. If the absolute value of the shift count is greater than BIT_SIZE(I), the result is undefined. Bits shifted out from the left end or the right end are lost. Zeros are shifted in from the opposite end.

See IShftC Intrinsic, for the circular-shift equivalent.


Node:IShftC Intrinsic, Next:ISign Intrinsic, Previous:IShft Intrinsic, Up:Table of Intrinsic Functions

IShftC Intrinsic

IShftC(I, Shift, Size)

IShftC: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar; INTENT(IN).

Shift: INTEGER; scalar; INTENT(IN).

Size: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

The rightmost Size bits of the argument I are shifted circularly Shift places, i.e. the bits shifted out of one end are shifted into the opposite end. No bits are lost. The unshifted bits of the result are the same as the unshifted bits of I. The absolute value of the argument Shift must be less than or equal to Size. The value of Size must be greater than or equal to one and less than or equal to BIT_SIZE(I).

See IShft Intrinsic, for the logical shift equivalent.


Node:ISign Intrinsic, Next:ITime Intrinsic, Previous:IShftC Intrinsic, Up:Table of Intrinsic Functions

ISign Intrinsic

ISign(A, B)

ISign: INTEGER(KIND=1) function.

A: INTEGER(KIND=1); scalar; INTENT(IN).

B: INTEGER(KIND=1); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of SIGN() that is specific to one type for A and B. See Sign Intrinsic.


Node:IZExt Intrinsic, Next:JIAbs Intrinsic, Previous:INot Intrinsic, Up:Other Intrinsics

IZExt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL IZExt to use this name for an external procedure.


Node:JIAbs Intrinsic, Next:JIAnd Intrinsic, Previous:IZExt Intrinsic, Up:Other Intrinsics

JIAbs Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIAbs to use this name for an external procedure.


Node:JIAnd Intrinsic, Next:JIBClr Intrinsic, Previous:JIAbs Intrinsic, Up:Other Intrinsics

JIAnd Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIAnd to use this name for an external procedure.


Node:JIBClr Intrinsic, Next:JIBits Intrinsic, Previous:JIAnd Intrinsic, Up:Other Intrinsics

JIBClr Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIBClr to use this name for an external procedure.


Node:JIBits Intrinsic, Next:JIBSet Intrinsic, Previous:JIBClr Intrinsic, Up:Other Intrinsics

JIBits Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIBits to use this name for an external procedure.


Node:JIBSet Intrinsic, Next:JIDiM Intrinsic, Previous:JIBits Intrinsic, Up:Other Intrinsics

JIBSet Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIBSet to use this name for an external procedure.


Node:JIDInt Intrinsic, Next:JIDNnt Intrinsic, Previous:JIDiM Intrinsic, Up:Other Intrinsics

JIDInt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIDInt to use this name for an external procedure.


Node:JIDNnt Intrinsic, Next:JIEOr Intrinsic, Previous:JIDInt Intrinsic, Up:Other Intrinsics

JIDNnt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIDNnt to use this name for an external procedure.


Node:JIEOr Intrinsic, Next:JIFix Intrinsic, Previous:JIDNnt Intrinsic, Up:Other Intrinsics

JIEOr Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIEOr to use this name for an external procedure.


Node:JIFix Intrinsic, Next:JInt Intrinsic, Previous:JIEOr Intrinsic, Up:Other Intrinsics

JIFix Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIFix to use this name for an external procedure.


Node:JInt Intrinsic, Next:JIOr Intrinsic, Previous:JIFix Intrinsic, Up:Other Intrinsics

JInt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JInt to use this name for an external procedure.


Node:JIOr Intrinsic, Next:JIQint Intrinsic, Previous:JInt Intrinsic, Up:Other Intrinsics

JIOr Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIOr to use this name for an external procedure.


Node:JIQint Intrinsic, Next:JIQNnt Intrinsic, Previous:JIOr Intrinsic, Up:Other Intrinsics

JIQint Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIQint to use this name for an external procedure.


Node:JIQNnt Intrinsic, Next:JIShft Intrinsic, Previous:JIQint Intrinsic, Up:Other Intrinsics

JIQNnt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIQNnt to use this name for an external procedure.


Node:JIShft Intrinsic, Next:JIShftC Intrinsic, Previous:JIQNnt Intrinsic, Up:Other Intrinsics

JIShft Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIShft to use this name for an external procedure.


Node:JIShftC Intrinsic, Next:JISign Intrinsic, Previous:JIShft Intrinsic, Up:Other Intrinsics

JIShftC Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JIShftC to use this name for an external procedure.


Node:JISign Intrinsic, Next:JMax0 Intrinsic, Previous:JIShftC Intrinsic, Up:Other Intrinsics

JISign Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JISign to use this name for an external procedure.


Node:JMax0 Intrinsic, Next:JMax1 Intrinsic, Previous:JISign Intrinsic, Up:Other Intrinsics

JMax0 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JMax0 to use this name for an external procedure.


Node:JMax1 Intrinsic, Next:JMin0 Intrinsic, Previous:JMax0 Intrinsic, Up:Other Intrinsics

JMax1 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JMax1 to use this name for an external procedure.


Node:JMin1 Intrinsic, Next:JMod Intrinsic, Previous:JMin0 Intrinsic, Up:Other Intrinsics

JMin1 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JMin1 to use this name for an external procedure.


Node:JMod Intrinsic, Next:JNInt Intrinsic, Previous:JMin1 Intrinsic, Up:Other Intrinsics

JMod Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JMod to use this name for an external procedure.


Node:JNInt Intrinsic, Next:JNot Intrinsic, Previous:JMod Intrinsic, Up:Other Intrinsics

JNInt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JNInt to use this name for an external procedure.


Node:JNot Intrinsic, Next:JZExt Intrinsic, Previous:JNInt Intrinsic, Up:Other Intrinsics

JNot Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JNot to use this name for an external procedure.


Node:JZExt Intrinsic, Next:Kill Intrinsic (function), Previous:JNot Intrinsic, Up:Other Intrinsics

JZExt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL JZExt to use this name for an external procedure.


Node:Kill Intrinsic (function), Next:Link Intrinsic (function), Previous:JZExt Intrinsic, Up:Other Intrinsics

Kill Intrinsic (function)

Kill(Pid, Signal)

Kill: INTEGER(KIND=1) function.

Pid: INTEGER; scalar; INTENT(IN).

Signal: INTEGER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Sends the signal specified by Signal to the process Pid. Returns 0 on success or a non-zero error code. See kill(2).

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See Kill Intrinsic (subroutine).


Node:Kill Intrinsic (subroutine), Next:Kind Intrinsic, Previous:ITime Intrinsic, Up:Table of Intrinsic Functions

Kill Intrinsic (subroutine)

CALL Kill(Pid, Signal, Status)

Pid: INTEGER; scalar; INTENT(IN).

Signal: INTEGER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Sends the signal specified by Signal to the process Pid. If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return. See kill(2).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See Kill Intrinsic (function).


Node:Kind Intrinsic, Next:LBound Intrinsic, Previous:Kill Intrinsic (subroutine), Up:Table of Intrinsic Functions

Kind Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Kind to use this name for an external procedure.


Node:Kind Notation, Previous:Star Notation, Up:Types

Kind Notation

The following notation specifies the kind-type selector of a type:

generic-type(KIND=n)

Use the above form where a type name is valid.

generic-type must be a generic type--one of INTEGER, REAL, COMPLEX, LOGICAL, or CHARACTER. n must be an integer initialization expression that is a positive, nonzero value.

Programmers are discouraged from writing these values directly into their code. Future versions of the GNU Fortran language will offer facilities that will make the writing of code portable to g77 and Fortran 90 implementations simpler.

However, writing code that ports to existing FORTRAN 77 implementations depends on avoiding the KIND= construct.

The KIND= construct is thus useful in the context of GNU Fortran for two reasons:

  • It provides a means to specify a type in a fashion that is portable across all GNU Fortran implementations (though not other FORTRAN 77 and Fortran 90 implementations).
  • It provides a sort of Rosetta stone for this document to use to concisely describe the types of various operations and operands.

The values of n in the GNU Fortran language are assigned using a scheme that:

  • Attempts to maximize the ability of readers of this document to quickly familiarize themselves with assignments for popular types
  • Provides a unique value for each specific desired meaning
  • Provides a means to automatically assign new values so they have a "natural" relationship to existing values, if appropriate, or, if no such relationship exists, will not interfere with future values assigned on the basis of such relationships
  • Avoids using values that are similar to values used in the existing, popular *n notation, to prevent readers from expecting that these implied correspondences work on all GNU Fortran implementations

The assignment system accomplishes this by assigning to each "fundamental meaning" of a specific type a unique prime number. Combinations of fundamental meanings--for example, a type that is two times the size of some other type--are assigned values of n that are the products of the values for those fundamental meanings.

A prime value of n is never given more than one fundamental meaning, to avoid situations where some code or system cannot reasonably provide those meanings in the form of a single type.

The values of n assigned so far are:

KIND=0
This value is reserved for future use.

The planned future use is for this value to designate, explicitly, context-sensitive kind-type selection. For example, the expression 1D0 * 0.1_0 would be equivalent to 1D0 * 0.1D0.

KIND=1
This corresponds to the default types for REAL, INTEGER, LOGICAL, COMPLEX, and CHARACTER, as appropriate.

These are the "default" types described in the Fortran 90 standard, though that standard does not assign any particular KIND= value to these types.

(Typically, these are REAL*4, INTEGER*4, LOGICAL*4, and COMPLEX*8.)

KIND=2
This corresponds to types that occupy twice as much storage as the default types. REAL(KIND=2) is DOUBLE PRECISION (typically REAL*8), COMPLEX(KIND=2) is DOUBLE COMPLEX (typically COMPLEX*16),

These are the "double precision" types described in the Fortran 90 standard, though that standard does not assign any particular KIND= value to these types.

n of 4 thus corresponds to types that occupy four times as much storage as the default types, n of 8 to types that occupy eight times as much storage, and so on.

The INTEGER(KIND=2) and LOGICAL(KIND=2) types are not necessarily supported by every GNU Fortran implementation.

KIND=3
This corresponds to types that occupy as much storage as the default CHARACTER type, which is the same effective type as CHARACTER(KIND=1) (making that type effectively the same as CHARACTER(KIND=3)).

(Typically, these are INTEGER*1 and LOGICAL*1.)

n of 6 thus corresponds to types that occupy twice as much storage as the n=3 types, n of 12 to types that occupy four times as much storage, and so on.

These are not necessarily supported by every GNU Fortran implementation.

KIND=5
This corresponds to types that occupy half the storage as the default (n=1) types.

(Typically, these are INTEGER*2 and LOGICAL*2.)

n of 25 thus corresponds to types that occupy one-quarter as much storage as the default types.

These are not necessarily supported by every GNU Fortran implementation.

KIND=7
This is valid only as INTEGER(KIND=7) and denotes the INTEGER type that has the smallest storage size that holds a pointer on the system.

A pointer representable by this type is capable of uniquely addressing a CHARACTER*1 variable, array, array element, or substring.

(Typically this is equivalent to INTEGER*4 or, on 64-bit systems, INTEGER*8. In a compatible C implementation, it typically would be the same size and semantics of the C type void *.)

Note that these are proposed correspondences and might change in future versions of g77--avoid writing code depending on them while g77, and therefore the GNU Fortran language it defines, is in beta testing.

Values not specified in the above list are reserved to future versions of the GNU Fortran language.

Implementation-dependent meanings will be assigned new, unique prime numbers so as to not interfere with other implementation-dependent meanings, and offer the possibility of increasing the portability of code depending on such types by offering support for them in other GNU Fortran implementations.

Other meanings that might be given unique values are:

  • Types that make use of only half their storage size for representing precision and range.

    For example, some compilers offer options that cause INTEGER types to occupy the amount of storage that would be needed for INTEGER(KIND=2) types, but the range remains that of INTEGER(KIND=1).

  • The IEEE single floating-point type.
  • Types with a specific bit pattern (endianness), such as the little-endian form of INTEGER(KIND=1). These could permit, conceptually, use of portable code and implementations on data files written by existing systems.

Future prime numbers should be given meanings in as incremental a fashion as possible, to allow for flexibility and expressiveness in combining types.

For example, instead of defining a prime number for little-endian IEEE doubles, one prime number might be assigned the meaning "little-endian", another the meaning "IEEE double", and the value of n for a little-endian IEEE double would thus naturally be the product of those two respective assigned values. (It could even be reasonable to have IEEE values result from the products of prime values denoting exponent and fraction sizes and meanings, hidden bit usage, availability and representations of special values such as subnormals, infinities, and Not-A-Numbers (NaNs), and so on.)

This assignment mechanism, while not inherently required for future versions of the GNU Fortran language, is worth using because it could ease management of the "space" of supported types much easier in the long run.

The above approach suggests a mechanism for specifying inheritance of intrinsic (built-in) types for an entire, widely portable product line. It is certainly reasonable that, unlike programmers of other languages offering inheritance mechanisms that employ verbose names for classes and subclasses, along with graphical browsers to elucidate the relationships, Fortran programmers would employ a mechanism that works by multiplying prime numbers together and finding the prime factors of such products.

Most of the advantages for the above scheme have been explained above. One disadvantage is that it could lead to the defining, by the GNU Fortran language, of some fairly large prime numbers. This could lead to the GNU Fortran language being declared "munitions" by the United States Department of Defense.


Node:Known Bugs, Next:Missing Features, Previous:But-bugs, Up:Trouble

Known Bugs In GNU Fortran

This section identifies bugs that g77 users might run into in the GCC-3.1 version of g77. This includes bugs that are actually in the gcc back end (GBE) or in libf2c, because those sets of code are at least somewhat under the control of (and necessarily intertwined with) g77, so it isn't worth separating them out.

For information on bugs in other versions of g77, see News About GNU Fortran. There, lists of bugs fixed in various versions of g77 can help determine what bugs existed in prior versions.

An online, "live" version of this document (derived directly from the mainline, development version of g77 within gcc) is available via http://www.gnu.org/software/gcc/onlinedocs/g77_bugs.html. Follow the "Known Bugs" link.

The following information was last updated on 2002-02-01:

  • g77 fails to warn about use of a "live" iterative-DO variable as an implied-DO variable in a WRITE or PRINT statement (although it does warn about this in a READ statement).
  • Something about g77's straightforward handling of label references and definitions sometimes prevents the GBE from unrolling loops. Until this is solved, try inserting or removing CONTINUE statements as the terminal statement, using the END DO form instead, and so on.
  • Some confusion in diagnostics concerning failing INCLUDE statements from within INCLUDE'd or #include'd files.
  • g77 assumes that INTEGER(KIND=1) constants range from -2**31 to 2**31-1 (the range for two's-complement 32-bit values), instead of determining their range from the actual range of the type for the configuration (and, someday, for the constant).

    Further, it generally doesn't implement the handling of constants very well in that it makes assumptions about the configuration that it no longer makes regarding variables (types).

    Included with this item is the fact that g77 doesn't recognize that, on IEEE-754/854-compliant systems, 0./0. should produce a NaN and no warning instead of the value 0. and a warning.

  • g77 uses way too much memory and CPU time to process large aggregate areas having any initialized elements.

    For example, REAL A(1000000) followed by DATA A(1)/1/ takes up way too much time and space, including the size of the generated assembler file.

    Version 0.5.18 improves cases like this--specifically, cases of sparse initialization that leave large, contiguous areas uninitialized--significantly. However, even with the improvements, these cases still require too much memory and CPU time.

    (Version 0.5.18 also improves cases where the initial values are zero to a much greater degree, so if the above example ends with DATA A(1)/0/, the compile-time performance will be about as good as it will ever get, aside from unrelated improvements to the compiler.)

    Note that g77 does display a warning message to notify the user before the compiler appears to hang. A warning message is issued when g77 sees code that provides initial values (e.g. via DATA) to an aggregate area (COMMON or EQUIVALENCE, or even a large enough array or CHARACTER variable) that is large enough to increase g77's compile time by roughly a factor of 10.

    This size currently is quite small, since g77 currently has a known bug requiring too much memory and time to handle such cases. In gcc/gcc/f/data.c, the macro FFEDATA_sizeTOO_BIG_INIT_ is defined to the minimum size for the warning to appear. The size is specified in storage units, which can be bytes, words, or whatever, on a case-by-case basis.

    After changing this macro definition, you must (of course) rebuild and reinstall g77 for the change to take effect.

    Note that, as of version 0.5.18, improvements have reduced the scope of the problem for sparse initialization of large arrays, especially those with large, contiguous uninitialized areas. However, the warning is issued at a point prior to when g77 knows whether the initialization is sparse, and delaying the warning could mean it is produced too late to be helpful.

    Therefore, the macro definition should not be adjusted to reflect sparse cases. Instead, adjust it to generate the warning when densely initialized arrays begin to cause responses noticeably slower than linear performance would suggest.

  • When debugging, after starting up the debugger but before being able to see the source code for the main program unit, the user must currently set a breakpoint at MAIN__ (or MAIN___ or MAIN_ if MAIN__ doesn't exist) and run the program until it hits the breakpoint. At that point, the main program unit is activated and about to execute its first executable statement, but that's the state in which the debugger should start up, as is the case for languages like C.
  • Debugging g77-compiled code using debuggers other than gdb is likely not to work.

    Getting g77 and gdb to work together is a known problem--getting g77 to work properly with other debuggers, for which source code often is unavailable to g77 developers, seems like a much larger, unknown problem, and is a lower priority than making g77 and gdb work together properly.

    On the other hand, information about problems other debuggers have with g77 output might make it easier to properly fix g77, and perhaps even improve gdb, so it is definitely welcome. Such information might even lead to all relevant products working together properly sooner.

  • g77 doesn't work perfectly on 64-bit configurations such as the Digital Semiconductor ("DEC") Alpha.

    This problem is largely resolved as of version 0.5.23.

  • g77 currently inserts needless padding for things like COMMON A,IPAD where A is CHARACTER*1 and IPAD is INTEGER(KIND=1) on machines like x86, because the back end insists that IPAD be aligned to a 4-byte boundary, but the processor has no such requirement (though it is usually good for performance).

    The gcc back end needs to provide a wider array of specifications of alignment requirements and preferences for targets, and front ends like g77 should take advantage of this when it becomes available.

  • The libf2c routines that perform some run-time arithmetic on COMPLEX operands were modified circa version 0.5.20 of g77 to work properly even in the presence of aliased operands.

    While the g77 and netlib versions of libf2c differ on how this is accomplished, the main differences are that we believe the g77 version works properly even in the presence of partially aliased operands.

    However, these modifications have reduced performance on targets such as x86, due to the extra copies of operands involved.


Node:Labels Visible to Debugger, Previous:Default to Console I/O, Up:Missing Features

Labels Visible to Debugger

g77 should output debugging information for statements labels, for use by debuggers that know how to support them. Same with weirder things like construct names. It is not yet known if any debug formats or debuggers support these.


Node:Language Extensions, Next:Diagnostic Abilities, Up:Advantages Over f2c

Language Extensions

g77 offers several extensions to FORTRAN 77 language that f2c doesn't:

  • Automatic arrays
  • CYCLE and EXIT
  • Construct names
  • SELECT CASE
  • KIND= and LEN= notation
  • Semicolon as statement separator
  • Constant expressions in FORMAT statements (such as FORMAT(I<J>), where J is a PARAMETER named constant)
  • MvBits intrinsic
  • libU77 (Unix-compatibility) library, with routines known to compiler as intrinsics (so they work even when compiler options are used to change the interfaces used by Fortran routines)

g77 also implements iterative DO loops so that they work even in the presence of certain "extreme" inputs, unlike f2c. See Loops.

However, f2c offers a few that g77 doesn't, such as:

  • Intrinsics in PARAMETER statements
  • Array bounds expressions (such as REAL M(N(2)))
  • AUTOMATIC statement

It is expected that g77 will offer some or all of these missing features at some time in the future.


Node:Language, Next:Compiler, Previous:Changes, Up:Top

The GNU Fortran Language

GNU Fortran supports a variety of extensions to, and dialects of, the Fortran language. Its primary base is the ANSI FORTRAN 77 standard, currently available on the network at http://www.fortran.com/fortran/F77_std/rjcnf0001.html or as monolithic text at http://www.fortran.com/fortran/F77_std/f77_std.html. It offers some extensions that are popular among users of UNIX f77 and f2c compilers, some that are popular among users of other compilers (such as Digital products), some that are popular among users of the newer Fortran 90 standard, and some that are introduced by GNU Fortran.

(If you need a text on Fortran, a few freely available electronic references have pointers from http://www.fortran.com/fortran/Books/. There is a `cooperative net project', User Notes on Fortran Programming at ftp://vms.huji.ac.il/fortran/ and mirrors elsewhere; some of this material might not apply specifically to g77.)

Part of what defines a particular implementation of a Fortran system, such as g77, is the particular characteristics of how it supports types, constants, and so on. Much of this is left up to the implementation by the various Fortran standards and accepted practice in the industry.

The GNU Fortran language is described below. Much of the material is organized along the same lines as the ANSI FORTRAN 77 standard itself.

See Other Dialects, for information on features g77 supports that are not part of the GNU Fortran language.

Note: This portion of the documentation definitely needs a lot of work!

Relationship to the ANSI FORTRAN 77 standard:

  • Direction of Language Development: Where GNU Fortran is headed.
  • Standard Support: Degree of support for the standard.

    Extensions to the ANSI FORTRAN 77 standard:

  • Conformance:
  • Notation Used:
  • Terms and Concepts:
  • Characters Lines Sequence:
  • Data Types and Constants:
  • Expressions:
  • Specification Statements:
  • Control Statements:
  • Functions and Subroutines:
  • Scope and Classes of Names:
  • I/O:
  • Fortran 90 Features:


Node:Large Automatic Arrays, Next:Support for Threads, Previous:Nonportable Conversions, Up:Missing Features

Large Automatic Arrays

Currently, automatic arrays always are allocated on the stack. For situations where the stack cannot be made large enough, g77 should offer a compiler option that specifies allocation of automatic arrays in heap storage.


Node:Large Common Blocks, Next:Debugger Problems, Previous:Cannot Link Fortran Programs, Up:But-bugs

Large Common Blocks

On some older GNU/Linux systems, programs with common blocks larger than 16MB cannot be linked without some kind of error message being produced.

This is a bug in older versions of ld, fixed in more recent versions of binutils, such as version 2.6.


Node:Large File Unit Numbers, Next:Floating-point precision, Previous:Output Assumed To Flush, Up:Working Programs

Large File Unit Numbers

If your program crashes at run time with a message including the text illegal unit number, that probably is a message from the run-time library, libg2c.

The message means that your program has attempted to use a file unit number that is out of the range accepted by libg2c. Normally, this range is 0 through 99, and the high end of the range is controlled by a libg2c source-file macro named MXUNIT.

If you can easily change your program to use unit numbers in the range 0 through 99, you should do so.

As distributed, whether as part of f2c or g77, libf2c accepts file unit numbers only in the range 0 through 99. For example, a statement such as WRITE (UNIT=100) causes a run-time crash in libf2c, because the unit number, 100, is out of range.

If you know that Fortran programs at your installation require the use of unit numbers higher than 99, you can change the value of the MXUNIT macro, which represents the maximum unit number, to an appropriately higher value.

To do this, edit the file gcc/libf2c/libI77/fio.h in your g77 source tree, changing the following line:

#define MXUNIT 100

Change the line so that the value of MXUNIT is defined to be at least one greater than the maximum unit number used by the Fortran programs on your system.

(For example, a program that does WRITE (UNIT=255) would require MXUNIT set to at least 256 to avoid crashing.)

Then build or rebuild g77 as appropriate.

Note: Changing this macro has no effect on other limits your system might place on the number of files open at the same time. That is, the macro might allow a program to do WRITE (UNIT=100), but the library and operating system underlying libf2c might disallow it if many other files have already been opened (via OPEN or implicitly via READ, WRITE, and so on). Information on how to increase these other limits should be found in your system's documentation.


Node:LBound Intrinsic, Next:Len Intrinsic, Previous:Kind Intrinsic, Up:Table of Intrinsic Functions

LBound Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL LBound to use this name for an external procedure.


Node:Len Intrinsic, Next:Len_Trim Intrinsic, Previous:LBound Intrinsic, Up:Table of Intrinsic Functions

Len Intrinsic

Len(String)

Len: INTEGER(KIND=1) function.

String: CHARACTER; scalar.

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the length of String.

If String is an array, the length of an element of String is returned.

Note that String need not be defined when this intrinsic is invoked, since only the length, not the content, of String is needed.

See Bit_Size Intrinsic, for the function that determines the size of its argument in bits.


Node:Len_Trim Intrinsic, Next:LGe Intrinsic, Previous:Len Intrinsic, Up:Table of Intrinsic Functions

Len_Trim Intrinsic

Len_Trim(String)

Len_Trim: INTEGER(KIND=1) function.

String: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: f90.

Description:

Returns the index of the last non-blank character in String. LNBLNK and LEN_TRIM are equivalent.


Node:lex.c, Next:sta.c, Previous:g77stripcard, Up:Overview of Translation Process

lex.c

To help make the lexer simple, fast, and easy to maintain, while also having g77 generally encourage Fortran programmers to write simple, maintainable, portable code by maximizing the performance of compiling that kind of code:

  • There'll be just one lexer, for both fixed-form and free-form source.
  • It'll care about the form only when handling the first 7 columns of text, stuff like spaces between strings of alphanumerics, and how lines are continued.

    Some other distinctions will be handled by subsequent phases, so at least one of them will have to know which form is involved.

    For example, I = 2 . 4 is acceptable in fixed form, and works in free form as well given the implementation g77 presently uses. But the standard requires a diagnostic for it in free form, so the parser has to be able to recognize that the lexemes aren't contiguous (information the lexer does have to provide) and that free-form source is being parsed, so it can provide the diagnostic.

    The g77 lexer doesn't try to gather 2 . 4 into a single lexeme. Otherwise, it'd have to know a whole lot more about how to parse Fortran, or subsequent phases (mainly parsing) would have two paths through lots of critical code--one to handle the lexeme 2, ., and 4 in sequence, another to handle the lexeme 2.4.

  • It won't worry about line lengths (beyond the first 7 columns for fixed-form source).

    That is, once it starts parsing the "statement" part of a line (column 7 for fixed-form, column 1 for free-form), it'll keep going until it finds a newline, rather than ignoring everything past a particular column (72 or 132).

    The implication here is that there shouldn't be anything past that last column, other than whitespace or commentary, because users using typical editors (or viewing output as typically printed) won't necessarily know just where the last column is.

    Code that has "garbage" beyond the last column (almost certainly only fixed-form code with a punched-card legacy, such as code using columns 73-80 for "sequence numbers") will have to be run through g77stripcard first.

    Also, keeping track of the maximum column position while also watching out for the end of a line and while reading from a file just makes things slower. Since a file must be read, and watching for the end of the line is necessary (unless the typical input file was preprocessed to include the necessary number of trailing spaces), dropping the tracking of the maximum column position is the only way to reduce the complexity of the pertinent code while maintaining high performance.

  • ASCII encoding is assumed for the input file.

    Code written in other character sets will have to be converted first.

  • Tabs (ASCII code 9) will be converted to spaces via the straightforward approach.

    Specifically, a tab is converted to between one and eight spaces as necessary to reach column n, where dividing (n - 1) by eight results in a remainder of zero.

    That saves having to pass most source files through expand.

  • Linefeeds (ASCII code 10) mark the ends of lines.
  • A carriage return (ASCII code 13) is accept if it immediately precedes a linefeed, in which case it is ignored.

    Otherwise, it is rejected (with a diagnostic).

  • Any other characters other than the above that are not part of the GNU Fortran Character Set (see Character Set) are rejected with a diagnostic.

    This includes backspaces, form feeds, and the like.

    (It might make sense to allow a form feed in column 1 as long as that's the only character on a line. It certainly wouldn't seem to cost much in terms of performance.)

  • The end of the input stream (EOF) ends the current line.
  • The distinction between uppercase and lowercase letters will be preserved.

    It will be up to subsequent phases to decide to fold case.

    Current plans are to permit any casing for Fortran (reserved) keywords while preserving casing for user-defined names. (This might not be made the default for .f files, though.)

    Preserving case seems necessary to provide more direct access to facilities outside of g77, such as to C or Pascal code.

    Names of intrinsics will probably be matchable in any case,

    (How external SiN; r = sin(x) would be handled is TBD. I think old g77 might already handle that pretty elegantly, but whether we can cope with allowing the same fragment to reference a different procedure, even with the same interface, via s = SiN(r), needs to be determined. If it can't, we need to make sure that when code introduces a user-defined name, any intrinsic matching that name using a case-insensitive comparison is "turned off".)

  • Backslashes in CHARACTER and Hollerith constants are not allowed.

    This avoids the confusion introduced by some Fortran compiler vendors providing C-like interpretation of backslashes, while others provide straight-through interpretation.

    Some kind of lexical construct (TBD) will be provided to allow flagging of a CHARACTER (but probably not a Hollerith) constant that permits backslashes. It'll necessarily be a prefix, such as:

    PRINT *, C'This line has a backspace \b here.'
PRINT *, F'This line has a straight backslash \ here.'

    Further, command-line options might be provided to specify that one prefix or the other is to be assumed as the default for CHARACTER constants.

    However, it seems more helpful for g77 to provide a program that converts prefix all constants (or just those containing backslashes) with the desired designation, so printouts of code can be read without knowing the compile-time options used when compiling it.

    If such a program is provided (let's name it g77slash for now), then a command-line option to g77 should not be provided. (Though, given that it'll be easy to implement, it might be hard to resist user requests for it "to compile faster than if we have to invoke another filter".)

    This program would take a command-line option to specify the default interpretation of slashes, affecting which prefix it uses for constants.

    g77slash probably should automatically convert Hollerith constants that contain slashes to the appropriate CHARACTER constants. Then g77 wouldn't have to define a prefix syntax for Hollerith constants specifying whether they want C-style or straight-through backslashes.

  • To allow for form-neutral INCLUDE files without requiring them to be preprocessed, the fixed-form lexer should offer an extension (if possible) allowing a trailing & to be ignored, especially if after column 72, as it would be using the traditional Unix Fortran source model (which ignores everything after column 72).

The above implements nearly exactly what is specified by Character Set, and Lines, except it also provides automatic conversion of tabs and ignoring of newline-related carriage returns, as well as accommodating form-neutral INCLUDE files.

It also implements the "pure visual" model, by which is meant that a user viewing his code in a typical text editor (assuming it's not preprocessed via g77stripcard or similar) doesn't need any special knowledge of whether spaces on the screen are really tabs, whether lines end immediately after the last visible non-space character or after a number of spaces and tabs that follow it, or whether the last line in the file is ended by a newline.

Most editors don't make these distinctions, the ANSI FORTRAN 77 standard doesn't require them to, and it permits a standard-conforming compiler to define a method for transforming source code to "standard form" however it wants.

So, GNU Fortran defines it such that users have the best chance of having the code be interpreted the way it looks on the screen of the typical editor.

(Fancy editors should never be required to correctly read code written in classic two-dimensional-plaintext form. By correct reading I mean ability to read it, book-like, without mistaking text ignored by the compiler for program code and vice versa, and without having to count beyond the first several columns. The vague meaning of ASCII TAB, among other things, complicates this somewhat, but as long as "everyone", including the editor, other tools, and printer, agrees about the every-eighth-column convention, the GNU Fortran "pure visual" model meets these requirements. Any language or user-visible source form requiring special tagging of tabs, the ends of lines after spaces/tabs, and so on, fails to meet this fairly straightforward specification. Fortunately, Fortran itself does not mandate such a failure, though most vendor-supplied defaults for their Fortran compilers do fail to meet this specification for readability.)

Further, this model provides a clean interface to whatever preprocessors or code-generators are used to produce input to this phase of g77. Mainly, they need not worry about long lines.


Node:LEX, Next:GLOBALS, Previous:INTGLOB, Up:Diagnostics

LEX

Unrecognized character ...
Invalid first character ...
Line too long ...
Non-numeric character ...
Continuation indicator ...
Label at ... invalid with continuation line indicator ...
Character constant ...
Continuation line ...
Statement at ... begins with invalid token

Although the diagnostics identify specific problems, they can be produced when general problems such as the following occur:

  • The source file contains something other than Fortran code.

    If the code in the file does not look like many of the examples elsewhere in this document, it might not be Fortran code. (Note that Fortran code often is written in lower case letters, while the examples in this document use upper case letters, for stylistic reasons.)

    For example, if the file contains lots of strange-looking characters, it might be APL source code; if it contains lots of parentheses, it might be Lisp source code; if it contains lots of bugs, it might be C++ source code.

  • The source file contains free-form Fortran code, but -ffree-form was not specified on the command line to compile it.

    Free form is a newer form for Fortran code. The older, classic form is called fixed form.

    Fixed-form code is visually fairly distinctive, because numerical labels and comments are all that appear in the first five columns of a line, the sixth column is reserved to denote continuation lines, and actual statements start at or beyond column 7. Spaces generally are not significant, so if you see statements such as REALX,Y and DO10I=1,100, you are looking at fixed-form code. Comment lines are indicated by the letter C or the symbol * in column 1. (Some code uses ! or /* to begin in-line comments, which many compilers support.)

    Free-form code is distinguished from fixed-form source primarily by the fact that statements may start anywhere. (If lots of statements start in columns 1 through 6, that's a strong indicator of free-form source.) Consecutive keywords must be separated by spaces, so REALX,Y is not valid, while REAL X,Y is. There are no comment lines per se, but ! starts a comment anywhere in a line (other than within a character or Hollerith constant).

    See Source Form, for more information.

  • The source file is in fixed form and has been edited without sensitivity to the column requirements.

    Statements in fixed-form code must be entirely contained within columns 7 through 72 on a given line. Starting them "early" is more likely to result in diagnostics than finishing them "late", though both kinds of errors are often caught at compile time.

    For example, if the following code fragment is edited by following the commented instructions literally, the result, shown afterward, would produce a diagnostic when compiled:

    C On XYZZY systems, remove "C" on next line:
C     CALL XYZZY_RESET

    The result of editing the above line might be:

    C On XYZZY systems, remove "C" on next line:
     CALL XYZZY_RESET

    However, that leaves the first C in the CALL statement in column 6, making it a comment line, which is not really what the author intended, and which is likely to result in one of the above-listed diagnostics.

    Replacing the C in column 1 with a space is the proper change to make, to ensure the CALL keyword starts in or after column 7.

    Another common mistake like this is to forget that fixed-form source lines are significant through only column 72, and that, normally, any text beyond column 72 is ignored or is diagnosed at compile time.

    See Source Form, for more information.

  • The source file requires preprocessing, and the preprocessing is not being specified at compile time.

    A source file containing lines beginning with #define, #include, #if, and so on is likely one that requires preprocessing.

    If the file's suffix is .f, .for, or .FOR, the file normally will be compiled without preprocessing by g77.

    Change the file's suffix from .f to .F (or, on systems with case-insensitive file names, to .fpp or .FPP), from .for to .fpp, or from .FOR to .FPP. g77 compiles files with such names with preprocessing.

    Or, learn how to use gcc's -x option to specify the language f77-cpp-input for Fortran files that require preprocessing. See Options Controlling the Kind of Output.

  • The source file is preprocessed, and the results of preprocessing result in syntactic errors that are not necessarily obvious to someone examining the source file itself.

    Examples of errors resulting from preprocessor macro expansion include exceeding the line-length limit, improperly starting, terminating, or incorporating the apostrophe or double-quote in a character constant, improperly forming a Hollerith constant, and so on.

    See Options Controlling the Kind of Output, for suggestions about how to use, and not use, preprocessing for Fortran code.


Node:LGe Intrinsic, Next:LGt Intrinsic, Previous:Len_Trim Intrinsic, Up:Table of Intrinsic Functions

LGe Intrinsic

LGe(String_A, String_B)

LGe: LOGICAL(KIND=1) function.

String_A: CHARACTER; scalar; INTENT(IN).

String_B: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns .TRUE. if String_A.GE.String_B, .FALSE. otherwise. String_A and String_B are interpreted as containing ASCII character codes. If either value contains a character not in the ASCII character set, the result is processor dependent.

If the String_A and String_B are not the same length, the shorter is compared as if spaces were appended to it to form a value that has the same length as the longer.

The lexical comparison intrinsics LGe, LGt, LLe, and LLt differ from the corresponding intrinsic operators .GE., .GT., .LE., .LT.. Because the ASCII collating sequence is assumed, the following expressions always return .TRUE.:

LGE ('0', ' ')
LGE ('A', '0')
LGE ('a', 'A')

The following related expressions do not always return .TRUE., as they are not necessarily evaluated assuming the arguments use ASCII encoding:

'0' .GE. ' '
'A' .GE. '0'
'a' .GE. 'A'

The same difference exists between LGt and .GT.; between LLe and .LE.; and between LLt and .LT..


Node:LGt Intrinsic, Next:Link Intrinsic (subroutine), Previous:LGe Intrinsic, Up:Table of Intrinsic Functions

LGt Intrinsic

LGt(String_A, String_B)

LGt: LOGICAL(KIND=1) function.

String_A: CHARACTER; scalar; INTENT(IN).

String_B: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns .TRUE. if String_A.GT.String_B, .FALSE. otherwise. String_A and String_B are interpreted as containing ASCII character codes. If either value contains a character not in the ASCII character set, the result is processor dependent.

If the String_A and String_B are not the same length, the shorter is compared as if spaces were appended to it to form a value that has the same length as the longer.

See LGe Intrinsic, for information on the distinction between the LGT intrinsic and the .GT. operator.


Node:Limitation on Implicit Declarations, Previous:Multiple Definitions of External Names, Up:Disappointments

Limitation on Implicit Declarations

g77 disallows IMPLICIT CHARACTER*(*). This is not standard-conforming.


Node:Lines, Next:Continuation Line, Previous:Character Set, Up:Characters Lines Sequence

Lines

(Corresponds to Section 3.2 of ANSI X3.9-1978 FORTRAN 77.)

The way a Fortran compiler views source files depends entirely on the implementation choices made for the compiler, since those choices are explicitly left to the implementation by the published Fortran standards.

The GNU Fortran language mandates a view applicable to UNIX-like text files--files that are made up of an arbitrary number of lines, each with an arbitrary number of characters (sometimes called stream-based files).

This view does not apply to types of files that are specified as having a particular number of characters on every single line (sometimes referred to as record-based files).

Because a "line in a program unit is a sequence of 72 characters", to quote X3.9-1978, the GNU Fortran language specifies that a stream-based text file is translated to GNU Fortran lines as follows:

  • A newline in the file is the character that represents the end of a line of text to the underlying system. For example, on ASCII-based systems, a newline is the <NL> character, which has ASCII value 10 (decimal).
  • Each newline in the file serves to end the line of text that precedes it (and that does not contain a newline).
  • The end-of-file marker (EOF) also serves to end the line of text that precedes it (and that does not contain a newline).
  • Any line of text that is shorter than 72 characters is padded to that length with spaces (called "blanks" in the standard).
  • Any line of text that is longer than 72 characters is truncated to that length, but the truncated remainder must consist entirely of spaces.
  • Characters other than newline and the GNU Fortran character set are invalid.

For the purposes of the remainder of this description of the GNU Fortran language, the translation described above has already taken place, unless otherwise specified.

The result of the above translation is that the source file appears, in terms of the remainder of this description of the GNU Fortran language, as if it had an arbitrary number of 72-character lines, each character being among the GNU Fortran character set.

For example, if the source file itself has two newlines in a row, the second newline becomes, after the above translation, a single line containing 72 spaces.


Node:Link Intrinsic (function), Next:QAbs Intrinsic, Previous:Kill Intrinsic (function), Up:Other Intrinsics

Link Intrinsic (function)

Link(Path1, Path2)

Link: INTEGER(KIND=1) function.

Path1: CHARACTER; scalar; INTENT(IN).

Path2: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Makes a (hard) link from file Path1 to Path2. A null character (CHAR(0)) marks the end of the names in Path1 and Path2--otherwise, trailing blanks in Path1 and Path2 are ignored. Returns 0 on success or a non-zero error code. See link(2).

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See Link Intrinsic (subroutine).


Node:Link Intrinsic (subroutine), Next:LLe Intrinsic, Previous:LGt Intrinsic, Up:Table of Intrinsic Functions

Link Intrinsic (subroutine)

CALL Link(Path1, Path2, Status)

Path1: CHARACTER; scalar; INTENT(IN).

Path2: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Makes a (hard) link from file Path1 to Path2. A null character (CHAR(0)) marks the end of the names in Path1 and Path2--otherwise, trailing blanks in Path1 and Path2 are ignored. If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return. See link(2).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See Link Intrinsic (function).


Node:LINKFAIL, Next:Y2KBAD, Previous:GLOBALS, Up:Diagnostics

LINKFAIL

On AIX 4.1, g77 might not build with the native (non-GNU) tools due to a linker bug in coping with the -bbigtoc option which leads to a Relocation overflow error. The GNU linker is not recommended on current AIX versions, though; it was developed under a now-unsupported version. This bug is said to be fixed by `update PTF U455193 for APAR IX75823'.

Compiling with -mminimal-toc might solve this problem, e.g. by adding

BOOT_CFLAGS='-mminimal-toc -O2 -g'
to the make bootstrap command line.


Node:LLe Intrinsic, Next:LLt Intrinsic, Previous:Link Intrinsic (subroutine), Up:Table of Intrinsic Functions

LLe Intrinsic

LLe(String_A, String_B)

LLe: LOGICAL(KIND=1) function.

String_A: CHARACTER; scalar; INTENT(IN).

String_B: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns .TRUE. if String_A.LE.String_B, .FALSE. otherwise. String_A and String_B are interpreted as containing ASCII character codes. If either value contains a character not in the ASCII character set, the result is processor dependent.

If the String_A and String_B are not the same length, the shorter is compared as if spaces were appended to it to form a value that has the same length as the longer.

See LGe Intrinsic, for information on the distinction between the LLE intrinsic and the .LE. operator.


Node:LLt Intrinsic, Next:LnBlnk Intrinsic, Previous:LLe Intrinsic, Up:Table of Intrinsic Functions

LLt Intrinsic

LLt(String_A, String_B)

LLt: LOGICAL(KIND=1) function.

String_A: CHARACTER; scalar; INTENT(IN).

String_B: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns .TRUE. if String_A.LT.String_B, .FALSE. otherwise. String_A and String_B are interpreted as containing ASCII character codes. If either value contains a character not in the ASCII character set, the result is processor dependent.

If the String_A and String_B are not the same length, the shorter is compared as if spaces were appended to it to form a value that has the same length as the longer.

See LGe Intrinsic, for information on the distinction between the LLT intrinsic and the .LT. operator.


Node:LnBlnk Intrinsic, Next:Loc Intrinsic, Previous:LLt Intrinsic, Up:Table of Intrinsic Functions

LnBlnk Intrinsic

LnBlnk(String)

LnBlnk: INTEGER(KIND=1) function.

String: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns the index of the last non-blank character in String. LNBLNK and LEN_TRIM are equivalent.


Node:Loc Intrinsic, Next:Log Intrinsic, Previous:LnBlnk Intrinsic, Up:Table of Intrinsic Functions

Loc Intrinsic

Loc(Entity)

Loc: INTEGER(KIND=7) function.

Entity: Any type; cannot be a constant or expression.

Intrinsic groups: unix.

Description:

The LOC() intrinsic works the
same way as the %LOC() construct.
See The %LOC() Construct, for
more information.


Node:Local Equivalence Areas, Next:Complex Variables, Previous:Common Blocks, Up:Debugging and Interfacing

Local Equivalence Areas (EQUIVALENCE)

g77 treats storage-associated areas involving a COMMON block as explained in the section on common blocks.

A local EQUIVALENCE area is a collection of variables and arrays connected to each other in any way via EQUIVALENCE, none of which are listed in a COMMON statement.

(Note: g77 version 0.5.18 and earlier chose the name for x using a different method when more than one name was in the list of names of entities placed at the beginning of the array. Though the documentation specified that the first name listed in the EQUIVALENCE statements was chosen for x, g77 in fact chose the name using a method that was so complicated, it seemed easier to change it to an alphabetical sort than to describe the previous method in the documentation.)


Node:Log Intrinsic, Next:Log10 Intrinsic, Previous:Loc Intrinsic, Up:Table of Intrinsic Functions

Log Intrinsic

Log(X)

Log: REAL or COMPLEX function, the exact type being that of argument X.

X: REAL or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the natural logarithm of X, which must be greater than zero or, if type COMPLEX, must not be zero.

See Exp Intrinsic, for the inverse of this function.

See Log10 Intrinsic, for the `common' (base-10) logarithm function.


Node:Logical Intrinsic, Next:Long Intrinsic, Previous:Log10 Intrinsic, Up:Table of Intrinsic Functions

Logical Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Logical to use this name for an external procedure.


Node:Long Intrinsic, Next:LShift Intrinsic, Previous:Logical Intrinsic, Up:Table of Intrinsic Functions

Long Intrinsic

Long(A)

Long: INTEGER(KIND=1) function.

A: INTEGER(KIND=6); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Archaic form of INT() that is specific to one type for A. See Int Intrinsic.

The precise meaning of this intrinsic might change in a future version of the GNU Fortran language, as more is learned about how it is used.


Node:Long Lines, Next:Ampersands, Previous:Short Lines, Up:Source Form

Long Lines

Source lines longer than the applicable length are truncated to that length. Currently, g77 does not warn if the truncated characters are not spaces, to accommodate existing code written for systems that treated truncated text as commentary (especially in columns 73 through 80).

See Options Controlling Fortran Dialect, for information on the -ffixed-line-length-n option, which can be used to set the line length applicable to fixed-form source files.


Node:Loops, Next:Working Programs, Previous:Block Data and Libraries, Up:Collected Fortran Wisdom

Loops

The meaning of a DO loop in Fortran is precisely specified in the Fortran standard...and is quite different from what many programmers might expect.

In particular, Fortran iterative DO loops are implemented as if the number of trips through the loop is calculated before the loop is entered.

The number of trips for a loop is calculated from the start, end, and increment values specified in a statement such as:

DO iter = start, end, increment

The trip count is evaluated using a fairly simple formula based on the three values following the = in the statement, and it is that trip count that is effectively decremented during each iteration of the loop. If, at the beginning of an iteration of the loop, the trip count is zero or negative, the loop terminates. The per-loop-iteration modifications to iter are not related to determining whether to terminate the loop.

There are two important things to remember about the trip count:

  • It can be negative, in which case it is treated as if it was zero--meaning the loop is not executed at all.
  • The type used to calculate the trip count is the same type as iter, but the final calculation, and thus the type of the trip count itself, always is INTEGER(KIND=1).

These two items mean that there are loops that cannot be written in straightforward fashion using the Fortran DO.

For example, on a system with the canonical 32-bit two's-complement implementation of INTEGER(KIND=1), the following loop will not work:

DO I = -2000000000, 2000000000

Although the start and end values are well within the range of INTEGER(KIND=1), the trip count is not. The expected trip count is 40000000001, which is outside the range of INTEGER(KIND=1) on many systems.

Instead, the above loop should be constructed this way:

I = -2000000000
DO
  IF (I .GT. 2000000000) EXIT
  ...
  I = I + 1
END DO

The simple DO construct and the EXIT statement (used to leave the innermost loop) are F90 features that g77 supports.

Some Fortran compilers have buggy implementations of DO, in that they don't follow the standard. They implement DO as a straightforward translation to what, in C, would be a for statement. Instead of creating a temporary variable to hold the trip count as calculated at run time, these compilers use the iteration variable iter to control whether the loop continues at each iteration.

The bug in such an implementation shows up when the trip count is within the range of the type of iter, but the magnitude of ABS(end) + ABS(incr) exceeds that range. For example:

DO I = 2147483600, 2147483647

A loop started by the above statement will work as implemented by g77, but the use, by some compilers, of a more C-like implementation akin to

for (i = 2147483600; i <= 2147483647; ++i)

produces a loop that does not terminate, because i can never be greater than 2147483647, since incrementing it beyond that value overflows i, setting it to -2147483648. This is a large, negative number that still is less than 2147483647.

Another example of unexpected behavior of DO involves using a nonintegral iteration variable iter, that is, a REAL variable. Consider the following program:

      DATA BEGIN, END, STEP /.1, .31, .007/
      DO 10 R = BEGIN, END, STEP
         IF (R .GT. END) PRINT *, R, ' .GT. ', END, '!!'
         PRINT *,R
10    CONTINUE
      PRINT *,'LAST = ',R
      IF (R .LE. END) PRINT *, R, ' .LE. ', END, '!!'
      END

A C-like view of DO would hold that the two "exclamatory" PRINT statements are never executed. However, this is the output of running the above program as compiled by g77 on a GNU/Linux ix86 system:

 .100000001
 .107000001
 .114
 .120999999
 ...
 .289000005
 .296000004
 .303000003
LAST =   .310000002
 .310000002 .LE.   .310000002!!

Note that one of the two checks in the program turned up an apparent violation of the programmer's expectation--yet, the loop is correctly implemented by g77, in that it has 30 iterations. This trip count of 30 is correct when evaluated using the floating-point representations for the begin, end, and incr values (.1, .31, .007) on GNU/Linux ix86 are used. On other systems, an apparently more accurate trip count of 31 might result, but, nevertheless, g77 is faithfully following the Fortran standard, and the result is not what the author of the sample program above apparently expected. (Such other systems might, for different values in the DATA statement, violate the other programmer's expectation, for example.)

Due to this combination of imprecise representation of floating-point values and the often-misunderstood interpretation of DO by standard-conforming compilers such as g77, use of DO loops with REAL iteration variables is not recommended. Such use can be caught by specifying -Wsurprising. See Warning Options, for more information on this option.


Node:LShift Intrinsic, Next:LStat Intrinsic (subroutine), Previous:Long Intrinsic, Up:Table of Intrinsic Functions

LShift Intrinsic

LShift(I, Shift)

LShift: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar; INTENT(IN).

Shift: INTEGER; scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Returns I shifted to the left Shift bits.

Although similar to the expression I*(2**Shift), there are important differences. For example, the sign of the result is not necessarily the same as the sign of I.

Currently this intrinsic is defined assuming the underlying representation of I is as a two's-complement integer. It is unclear at this point whether that definition will apply when a different representation is involved.

See LShift Intrinsic, for the inverse of this function.

See IShft Intrinsic, for information on a more widely available left-shifting intrinsic that is also more precisely defined.


Node:LStat Intrinsic (function), Next:LTime Intrinsic, Previous:LStat Intrinsic (subroutine), Up:Table of Intrinsic Functions

LStat Intrinsic (function)

LStat(File, SArray)

LStat: INTEGER(KIND=1) function.

File: CHARACTER; scalar; INTENT(IN).

SArray: INTEGER(KIND=1); DIMENSION(13); INTENT(OUT).

Intrinsic groups: unix.

Description:

Obtains data about the given file File and places them in the array SArray. A null character (CHAR(0)) marks the end of the name in File--otherwise, trailing blanks in File are ignored. If File is a symbolic link it returns data on the link itself, so the routine is available only on systems that support symbolic links. The values in this array are extracted from the stat structure as returned by fstat(2) q.v., as follows:

  1. Device ID
  2. Inode number
  3. File mode
  4. Number of links
  5. Owner's uid
  6. Owner's gid
  7. ID of device containing directory entry for file (0 if not available)
  8. File size (bytes)
  9. Last access time
  10. Last modification time
  11. Last file status change time
  12. Preferred I/O block size (-1 if not available)
  13. Number of blocks allocated (-1 if not available)

Not all these elements are relevant on all systems. If an element is not relevant, it is returned as 0.

Returns 0 on success or a non-zero error code (ENOSYS if the system does not provide lstat(2)).

For information on other intrinsics with the same name: See LStat Intrinsic (subroutine).


Node:LStat Intrinsic (subroutine), Next:LStat Intrinsic (function), Previous:LShift Intrinsic, Up:Table of Intrinsic Functions

LStat Intrinsic (subroutine)

CALL LStat(File, SArray, Status)

File: CHARACTER; scalar; INTENT(IN).

SArray: INTEGER(KIND=1); DIMENSION(13); INTENT(OUT).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Obtains data about the given file File and places them in the array SArray. A null character (CHAR(0)) marks the end of the name in File--otherwise, trailing blanks in File are ignored. If File is a symbolic link it returns data on the link itself, so the routine is available only on systems that support symbolic links. The values in this array are extracted from the stat structure as returned by fstat(2) q.v., as follows:

  1. Device ID
  2. Inode number
  3. File mode
  4. Number of links
  5. Owner's uid
  6. Owner's gid
  7. ID of device containing directory entry for file (0 if not available)
  8. File size (bytes)
  9. Last access time
  10. Last modification time
  11. Last file status change time
  12. Preferred I/O block size (-1 if not available)
  13. Number of blocks allocated (-1 if not available)

Not all these elements are relevant on all systems. If an element is not relevant, it is returned as 0.

If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return (ENOSYS if the system does not provide lstat(2)).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See LStat Intrinsic (function).


Node:LTime Intrinsic, Next:MatMul Intrinsic, Previous:LStat Intrinsic (function), Up:Table of Intrinsic Functions

LTime Intrinsic

CALL LTime(STime, TArray)

STime: INTEGER(KIND=1); scalar; INTENT(IN).

TArray: INTEGER(KIND=1); DIMENSION(9); INTENT(OUT).

Intrinsic groups: unix.

Description:

Given a system time value STime, fills TArray with values extracted from it appropriate to the GMT time zone using localtime(3).

The array elements are as follows:

  1. Seconds after the minute, range 0-59 or 0-61 to allow for leap seconds
  2. Minutes after the hour, range 0-59
  3. Hours past midnight, range 0-23
  4. Day of month, range 0-31
  5. Number of months since January, range 0-12
  6. Years since 1900
  7. Number of days since Sunday, range 0-6
  8. Days since January 1
  9. Daylight savings indicator: positive if daylight savings is in effect, zero if not, and negative if the information isn't available.


Node:Machine Model, Next:Internals Documentation, Previous:More Extensions, Up:Projects

Machine Model

This items pertain to generalizing g77's view of the machine model to more fully accept whatever the GBE provides it via its configuration.

  • Switch to using REAL_VALUE_TYPE to represent floating-point constants exclusively so the target float format need not be required. This means changing the way g77 handles initialization of aggregate areas having more than one type, such as REAL and INTEGER, because currently it initializes them as if they were arrays of char and uses the bit patterns of the constants of the various types in them to determine what to stuff in elements of the arrays.
  • Rely more and more on back-end info and capabilities, especially in the area of constants (where having the g77 front-end's IL just store the appropriate tree nodes containing constants might be best).
  • Suite of C and Fortran programs that a user/administrator can run on a machine to help determine the configuration for g77 before building and help determine if the compiler works (especially with whatever libraries are installed) after building.


Node:Main Program Unit, Next:Procedures, Up:Debugging and Interfacing

Main Program Unit (PROGRAM)

When g77 compiles a main program unit, it gives it the public procedure name MAIN__. The libg2c library has the actual main() procedure as is typical of C-based environments, and it is this procedure that performs some initial start-up activity and then calls MAIN__.

Generally, g77 and libg2c are designed so that you need not include a main program unit written in Fortran in your program--it can be written in C or some other language. Especially for I/O handling, this is the case, although g77 version 0.5.16 includes a bug fix for libg2c that solved a problem with using the OPEN statement as the first Fortran I/O activity in a program without a Fortran main program unit.

However, if you don't intend to use g77 (or f2c) to compile your main program unit--that is, if you intend to compile a main() procedure using some other language--you should carefully examine the code for main() in libg2c, found in the source file gcc/libf2c/libF77/main.c, to see what kinds of things might need to be done by your main() in order to provide the Fortran environment your Fortran code is expecting.

For example, libg2c's main() sets up the information used by the IARGC and GETARG intrinsics. Bypassing libg2c's main() without providing a substitute for this activity would mean that invoking IARGC and GETARG would produce undefined results.

When debugging, one implication of the fact that main(), which is the place where the debugged program "starts" from the debugger's point of view, is in libg2c is that you won't be starting your Fortran program at a point you recognize as your Fortran code.

The standard way to get around this problem is to set a break point (a one-time, or temporary, break point will do) at the entrance to MAIN__, and then run the program. A convenient way to do so is to add the gdb command

tbreak MAIN__

to the file .gdbinit in the directory in which you're debugging (using gdb).

After doing this, the debugger will see the current execution point of the program as at the beginning of the main program unit of your program.

Of course, if you really want to set a break point at some other place in your program and just start the program running, without first breaking at MAIN__, that should work fine.


Node:Mangling of Names, Next:Multiple Definitions of External Names, Up:Disappointments

Mangling of Names in Source Code

The current external-interface design, which includes naming of external procedures, COMMON blocks, and the library interface, has various usability problems, including things like adding underscores where not really necessary (and preventing easier inter-language operability) and yet not providing complete namespace freedom for user C code linked with Fortran apps (due to the naming of functions in the library, among other things).

Project GNU should at least get all this "right" for systems it fully controls, such as the Hurd, and provide defaults and options for compatibility with existing systems and interoperability with popular existing compilers.


Node:MatMul Intrinsic, Next:Max Intrinsic, Previous:LTime Intrinsic, Up:Table of Intrinsic Functions

MatMul Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL MatMul to use this name for an external procedure.


Node:Max Intrinsic, Next:Max0 Intrinsic, Previous:MatMul Intrinsic, Up:Table of Intrinsic Functions

Max Intrinsic

Max(A-1, A-2, ..., A-n)

Max: INTEGER or REAL function, the exact type being the result of cross-promoting the types of all the arguments.

A: INTEGER or REAL; at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the argument with the largest value.

See Min Intrinsic, for the opposite function.


Node:Max0 Intrinsic, Next:Max1 Intrinsic, Previous:Max Intrinsic, Up:Table of Intrinsic Functions

Max0 Intrinsic

Max0(A-1, A-2, ..., A-n)

Max0: INTEGER(KIND=1) function.

A: INTEGER(KIND=1); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MAX() that is specific to one type for A. See Max Intrinsic.


Node:Max1 Intrinsic, Next:MaxExponent Intrinsic, Previous:Max0 Intrinsic, Up:Table of Intrinsic Functions

Max1 Intrinsic

Max1(A-1, A-2, ..., A-n)

Max1: INTEGER(KIND=1) function.

A: REAL(KIND=1); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MAX() that is specific to one type for A and a different return type. See Max Intrinsic.


Node:MaxExponent Intrinsic, Next:MaxLoc Intrinsic, Previous:Max1 Intrinsic, Up:Table of Intrinsic Functions

MaxExponent Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL MaxExponent to use this name for an external procedure.


Node:MaxLoc Intrinsic, Next:MaxVal Intrinsic, Previous:MaxExponent Intrinsic, Up:Table of Intrinsic Functions

MaxLoc Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL MaxLoc to use this name for an external procedure.


Node:MaxVal Intrinsic, Next:MClock Intrinsic, Previous:MaxLoc Intrinsic, Up:Table of Intrinsic Functions

MaxVal Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL MaxVal to use this name for an external procedure.


Node:MClock Intrinsic, Next:MClock8 Intrinsic, Previous:MaxVal Intrinsic, Up:Table of Intrinsic Functions

MClock Intrinsic

MClock()

MClock: INTEGER(KIND=1) function.

Intrinsic groups: unix.

Description:

Returns the number of clock ticks since the start of the process. Supported on systems with clock(3) (q.v.).

This intrinsic is not fully portable, such as to systems with 32-bit INTEGER types but supporting times wider than 32 bits. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

See MClock8 Intrinsic, for information on a similar intrinsic that might be portable to more GNU Fortran implementations, though to fewer Fortran compilers.

If the system does not support clock(3), -1 is returned.


Node:MClock8 Intrinsic, Next:Merge Intrinsic, Previous:MClock Intrinsic, Up:Table of Intrinsic Functions

MClock8 Intrinsic

MClock8()

MClock8: INTEGER(KIND=2) function.

Intrinsic groups: unix.

Description:

Returns the number of clock ticks since the start of the process. Supported on systems with clock(3) (q.v.).

Warning: this intrinsic does not increase the range of the timing values over that returned by clock(3). On a system with a 32-bit clock(3), MCLOCK8 will return a 32-bit value, even though converted to an INTEGER(KIND=2) value. That means overflows of the 32-bit value can still occur. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

No Fortran implementations other than GNU Fortran are known to support this intrinsic at the time of this writing. See MClock Intrinsic, for information on a similar intrinsic that might be portable to more Fortran compilers, though to fewer GNU Fortran implementations.

If the system does not support clock(3), -1 is returned.


Node:Merge Intrinsic, Next:Min Intrinsic, Previous:MClock8 Intrinsic, Up:Table of Intrinsic Functions

Merge Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Merge to use this name for an external procedure.


Node:MIL-STD 1753, Next:f77/f2c Intrinsics, Previous:CMPLX() of DOUBLE PRECISION, Up:Functions and Subroutines

MIL-STD 1753 Support

The GNU Fortran language includes the MIL-STD 1753 intrinsics BTEST, IAND, IBCLR, IBITS, IBSET, IEOR, IOR, ISHFT, ISHFTC, MVBITS, and NOT.


Node:Min Intrinsic, Next:Min0 Intrinsic, Previous:Merge Intrinsic, Up:Table of Intrinsic Functions

Min Intrinsic

Min(A-1, A-2, ..., A-n)

Min: INTEGER or REAL function, the exact type being the result of cross-promoting the types of all the arguments.

A: INTEGER or REAL; at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the argument with the smallest value.

See Max Intrinsic, for the opposite function.


Node:Min0 Intrinsic, Next:Min1 Intrinsic, Previous:Min Intrinsic, Up:Table of Intrinsic Functions

Min0 Intrinsic

Min0(A-1, A-2, ..., A-n)

Min0: INTEGER(KIND=1) function.

A: INTEGER(KIND=1); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MIN() that is specific to one type for A. See Min Intrinsic.


Node:Min1 Intrinsic, Next:MinExponent Intrinsic, Previous:Min0 Intrinsic, Up:Table of Intrinsic Functions

Min1 Intrinsic

Min1(A-1, A-2, ..., A-n)

Min1: INTEGER(KIND=1) function.

A: REAL(KIND=1); at least two such arguments must be provided; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of MIN() that is specific to one type for A and a different return type. See Min Intrinsic.


Node:MinExponent Intrinsic, Next:MinLoc Intrinsic, Previous:Min1 Intrinsic, Up:Table of Intrinsic Functions

MinExponent Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL MinExponent to use this name for an external procedure.


Node:MinLoc Intrinsic, Next:MinVal Intrinsic, Previous:MinExponent Intrinsic, Up:Table of Intrinsic Functions

MinLoc Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL MinLoc to use this name for an external procedure.


Node:MinVal Intrinsic, Next:Mod Intrinsic, Previous:MinLoc Intrinsic, Up:Table of Intrinsic Functions

MinVal Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL MinVal to use this name for an external procedure.


Node:Missing Features, Next:Disappointments, Previous:Known Bugs, Up:Trouble

Missing Features

This section lists features we know are missing from g77, and which we want to add someday. (There is no priority implied in the ordering below.)

GNU Fortran language:

  • Better Source Model:
  • Fortran 90 Support:
  • Intrinsics in PARAMETER Statements:
  • Arbitrary Concatenation:
  • SELECT CASE on CHARACTER Type:
  • RECURSIVE Keyword:
  • Popular Non-standard Types:
  • Full Support for Compiler Types:
  • Array Bounds Expressions:
  • POINTER Statements:
  • Sensible Non-standard Constructs:
  • READONLY Keyword:
  • FLUSH Statement:
  • Expressions in FORMAT Statements:
  • Explicit Assembler Code:
  • Q Edit Descriptor:

    GNU Fortran dialects:

  • Old-style PARAMETER Statements:
  • TYPE and ACCEPT I/O Statements:
  • STRUCTURE UNION RECORD MAP:
  • OPEN CLOSE and INQUIRE Keywords:
  • ENCODE and DECODE:
  • AUTOMATIC Statement:
  • Suppressing Space Padding:
  • Fortran Preprocessor:
  • Bit Operations on Floating-point Data:
  • Really Ugly Character Assignments:

    New facilities:

  • POSIX Standard:
  • Floating-point Exception Handling:
  • Nonportable Conversions:
  • Large Automatic Arrays:
  • Support for Threads:
  • Increasing Precision/Range:
  • Enabling Debug Lines:

    Better diagnostics:

  • Better Warnings:
  • Gracefully Handle Sensible Bad Code:
  • Non-standard Conversions:
  • Non-standard Intrinsics:
  • Modifying DO Variable:
  • Better Pedantic Compilation:
  • Warn About Implicit Conversions:
  • Invalid Use of Hollerith Constant:
  • Dummy Array Without Dimensioning Dummy:
  • Invalid FORMAT Specifiers:
  • Ambiguous Dialects:
  • Unused Labels:
  • Informational Messages:

    Run-time facilities:

  • Uninitialized Variables at Run Time:
  • Portable Unformatted Files:
  • Better List-directed I/O:
  • Default to Console I/O:

    Debugging:

  • Labels Visible to Debugger:


Node:Mod Intrinsic, Next:Modulo Intrinsic, Previous:MinVal Intrinsic, Up:Table of Intrinsic Functions

Mod Intrinsic

Mod(A, P)

Mod: INTEGER or REAL function, the exact type being the result of cross-promoting the types of all the arguments.

A: INTEGER or REAL; scalar; INTENT(IN).

P: INTEGER or REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns remainder calculated as:

A - (INT(A / P) * P)

P must not be zero.


Node:Modifying DO Variable, Next:Better Pedantic Compilation, Previous:Non-standard Intrinsics, Up:Missing Features

Modifying DO Variable

g77 should warn about modifying DO variables via EQUIVALENCE. (The internal information gathered to produce this warning might also be useful in setting the internal "doiter" flag for a variable or even array reference within a loop, since that might produce faster code someday.)

For example, this code is invalid, so g77 should warn about the invalid assignment to NOTHER:

EQUIVALENCE (I, NOTHER)
DO I = 1, 100
   IF (I.EQ. 10) NOTHER = 20
END DO


Node:Modulo Intrinsic, Next:MvBits Intrinsic, Previous:Mod Intrinsic, Up:Table of Intrinsic Functions

Modulo Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Modulo to use this name for an external procedure.


Node:More Extensions, Next:Machine Model, Previous:Simplify Porting, Up:Projects

More Extensions

These extensions are not the sort of things users ask for "by name", but they might improve the usability of g77, and Fortran in general, in the long run. Some of these items really pertain to improving g77 internals so that some popular extensions can be more easily supported.

  • Look through all the documentation on the GNU Fortran language, dialects, compiler, missing features, bugs, and so on. Many mentions of incomplete or missing features are sprinkled throughout. It is not worth repeating them here.
  • Consider adding a NUMERIC type to designate typeless numeric constants, named and unnamed. The idea is to provide a forward-looking, effective replacement for things like the old-style PARAMETER statement when people really need typelessness in a maintainable, portable, clearly documented way. Maybe TYPELESS would include CHARACTER, POINTER, and whatever else might come along. (This is not really a call for polymorphism per se, just an ability to express limited, syntactic polymorphism.)
  • Support OPEN(...,KEY=(...),...).
  • Support arbitrary file unit numbers, instead of limiting them to 0 through MXUNIT-1. (This is a libg2c issue.)
  • OPEN(NOSPANBLOCKS,...) is treated as
OPEN(UNIT=NOSPANBLOCKS,...), so a
later UNIT= in the first example is invalid.
Make sure this is what users of this feature would expect.
  • Currently g77 disallows READ(1'10) since it is an obnoxious syntax, but supporting it might be pretty easy if needed. More details are needed, such as whether general expressions separated by an apostrophe are supported, or maybe the record number can be a general expression, and so on.
  • Support STRUCTURE, UNION, MAP, and RECORD fully. Currently there is no support at all for %FILL in STRUCTURE and related syntax, whereas the rest of the stuff has at least some parsing support. This requires either major changes to libg2c or its replacement.
  • F90 and g77 probably disagree about label scoping relative to INTERFACE and END INTERFACE, and their contained procedure interface bodies (blocks?).
  • ENTRY doesn't support F90 RESULT() yet, since that was added after S8.112.
  • Empty-statement handling (10 ;;CONTINUE;;) probably isn't consistent with the final form of the standard (it was vague at S8.112).
  • It seems to be an "open" question whether a file, immediately after being OPENed,is positioned at the beginning, the end, or wherever--it might be nice to offer an option of opening to "undefined" status, requiring an explicit absolute-positioning operation to be performed before any other (besides CLOSE) to assist in making applications port to systems (some IBM?) that OPEN to the end of a file or some such thing.


Node:Multiple Definitions of External Names, Next:Limitation on Implicit Declarations, Previous:Mangling of Names, Up:Disappointments

Multiple Definitions of External Names

g77 doesn't allow a common block and an external procedure or BLOCK DATA to have the same name. Some systems allow this, but g77 does not, to be compatible with f2c.

g77 could special-case the way it handles BLOCK DATA, since it is not compatible with f2c in this particular area (necessarily, since g77 offers an important feature here), but it is likely that such special-casing would be very annoying to people with programs that use EXTERNAL FOO, with no other mention of FOO in the same program unit, to refer to external procedures, since the result would be that g77 would treat these references as requests to force-load BLOCK DATA program units.

In that case, if g77 modified names of BLOCK DATA so they could have the same names as COMMON, users would find that their programs wouldn't link because the FOO procedure didn't have its name translated the same way.

(Strictly speaking, g77 could emit a null-but-externally-satisfying definition of FOO with its name transformed as if it had been a BLOCK DATA, but that probably invites more trouble than it's worth.)


Node:MvBits Intrinsic, Next:Nearest Intrinsic, Previous:Modulo Intrinsic, Up:Table of Intrinsic Functions

MvBits Intrinsic

CALL MvBits(From, FromPos, Len, TO, ToPos)

From: INTEGER; scalar; INTENT(IN).

FromPos: INTEGER; scalar; INTENT(IN).

Len: INTEGER; scalar; INTENT(IN).

TO: INTEGER with same KIND= value as for From; scalar; INTENT(INOUT).

ToPos: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Moves Len bits from positions FromPos through FromPos+Len-1 of From to positions ToPos through FromPos+Len-1 of TO. The portion of argument TO not affected by the movement of bits is unchanged. Arguments From and TO are permitted to be the same numeric storage unit. The values of FromPos+Len and ToPos+Len must be less than or equal to BIT_SIZE(From).


Node:NAMELIST, Next:DOUBLE COMPLEX, Up:Specification Statements

NAMELIST Statement

The NAMELIST statement, and related I/O constructs, are supported by the GNU Fortran language in essentially the same way as they are by f2c.

This follows Fortran 90 with the restriction that on NAMELIST input, subscripts must have the form

subscript [ : subscript [ : stride]]
i.e.
&xx x(1:3,8:10:2)=1,2,3,4,5,6/
is allowed, but not, say,
&xx x(:3,8::2)=1,2,3,4,5,6/

As an extension of the Fortran 90 form, $ and $END may be used in place of & and / in NAMELIST input, so that

$&xx x(1:3,8:10:2)=1,2,3,4,5,6 $end
could be used instead of the example above.


Node:Names, Next:Common Blocks, Previous:Functions, Up:Debugging and Interfacing

Names

Fortran permits each implementation to decide how to represent names as far as how they're seen in other contexts, such as debuggers and when interfacing to other languages, and especially as far as how casing is handled.

External names--names of entities that are public, or "accessible", to all modules in a program--normally have an underscore (_) appended by g77, to generate code that is compatible with f2c. External names include names of Fortran things like common blocks, external procedures (subroutines and functions, but not including statement functions, which are internal procedures), and entry point names.

However, use of the -fno-underscoring option disables this kind of transformation of external names (though inhibiting the transformation certainly improves the chances of colliding with incompatible externals written in other languages--but that might be intentional.

When -funderscoring is in force, any name (external or local) that already has at least one underscore in it is implemented by g77 by appending two underscores. (This second underscore can be disabled via the -fno-second-underscore option.) External names are changed this way for f2c compatibility. Local names are changed this way to avoid collisions with external names that are different in the source code--f2c does the same thing, but there's no compatibility issue there except for user expectations while debugging.

For example:

Max_Cost = 0

Here, a user would, in the debugger, refer to this variable using the name max_cost__ (or MAX_COST__ or Max_Cost__, as described below). (We hope to improve g77 in this regard in the future--don't write scripts depending on this behavior! Also, consider experimenting with the -fno-underscoring option to try out debugging without having to massage names by hand like this.)

g77 provides a number of command-line options that allow the user to control how case mapping is handled for source files. The default is the traditional UNIX model for Fortran compilers--names are mapped to lower case. Other command-line options can be specified to map names to upper case, or to leave them exactly as written in the source file.

For example:

Foo = 9.436

Here, it is normally the case that the variable assigned will be named foo. This would be the name to enter when using a debugger to access the variable.

However, depending on the command-line options specified, the name implemented by g77 might instead be FOO or even Foo, thus affecting how debugging is done.

Also:

Call Foo

This would normally call a procedure that, if it were in a separate C program, be defined starting with the line:

void foo_()

However, g77 command-line options could be used to change the casing of names, resulting in the name FOO_ or Foo_ being given to the procedure instead of foo_, and the -fno-underscoring option could be used to inhibit the appending of the underscore to the name.


Node:Nearest Intrinsic, Next:NInt Intrinsic, Previous:MvBits Intrinsic, Up:Table of Intrinsic Functions

Nearest Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Nearest to use this name for an external procedure.


Node:News, Next:Changes, Previous:Invoking G77, Up:Top

News About GNU Fortran

Changes made to recent versions of GNU Fortran are listed below, with the most recent version first.

The changes are generally listed in order:

  1. Code-generation and run-time-library bug-fixes
  2. Compiler and run-time-library crashes involving valid code that have been fixed
  3. New features
  4. Fixes and enhancements to existing features
  5. New diagnostics
  6. Internal improvements
  7. Miscellany

This order is not strict--for example, some items involve a combination of these elements.

Note that two variants of g77 are tracked below. The egcs variant is described vis-a-vis previous versions of egcs and/or an official FSF version, as appropriate. Note that all such variants are obsolete as of July 1999 - the information is retained here only for its historical value.

Therefore, egcs versions sometimes have multiple listings to help clarify how they differ from other versions, though this can make getting a complete picture of what a particular egcs version contains somewhat more difficult.

For information on bugs in the GCC-3.1 version of g77, see Known Bugs In GNU Fortran.

An online, "live" version of this document (derived directly from the mainline, development version of g77 within gcc) is available at http://www.gnu.org/software/gcc/onlinedocs/g77_news.html.

The following information was last updated on 2002-04-13:

In GCC 3.1 (formerly known as g77-0.5.27) versus GCC 3.0:

  • Problem Reports fixed (in chronological order of submission):
    947
    Data statement initialization with subscript of kind INTEGER*2
    3743
    Reference to intrinsic `ISHFT' invalid
    3807
    Function BESJN(integer,double) problems
    3957
    g77 -pipe -xf77-cpp-input sends output to stdout
    4279
    g77 -h" gives bogus output
    4730
    ICE on valid input using CALL EXIT(%VAL(...))
    4752
    g77 -v -c -xf77-version /dev/null -xnone causes ice
    4885
    BACKSPACE example that doesn't work as of gcc/g77-3.0.x
    5122
    g77 rejects accepted use of INTEGER*2 as type of DATA statement loop index
    5397
    ICE on compiling source with 540 000 000 REAL array
    5473
    ICE on BESJN(integer*8,real)
    5837
    bug in loop unrolling
  • g77 now has its man page generated from the texinfo documentation, to guarantee that it remains up to date.
  • g77 used to reject the following program on 32-bit targets:
    PROGRAM PROG
DIMENSION A(140 000 000)
END
    with the message:
    prog.f: In program `prog':
prog.f:2:
         DIMENSION A(140 000 000)
                   ^
Array `a' at (^) is too large to handle
    because 140 000 000 reals is larger than the largest bit-extent that can be expressed in 32 bits. However, bit-sizes never play a role after offsets have been converted to byte addresses. Therefore this check has been removed. Note: On GNU/Linux systems one has to compile programs that occupy more than 1 Gbyte statically, i.e. g77 -static ....
  • Based on work done by Juergen Pfeifer (juergen.pfeifer@gmx.net) libf2c is now a shared library. One can still link in all objects with the program by specifying the -static option.
  • Robert Anderson (rwa@alumni.princeton.edu) thought up a two line change that enables g77 to compile such code as:
    SUBROUTINE SUB(A, N)
DIMENSION N(2)
DIMENSION A(N(1),N(2))
A(1,1) = 1.
END
    Note the use of array elements in the bounds of the adjustable array A.
  • George Helffrich (george@geo.titech.ac.jp) implemented a change in substring index checking (when specifying -fbounds-check) that permits the use of zero length substrings of the form string(1:0).
  • Based on code developed by Pedro Vazquez (vazquez@penelope.iqm.unicamp.br), the libf2c library is now able to read and write files larger than 2 Gbyte on 32-bit target machines, if the operating system supports this.

In 0.5.26, GCC 3.0 versus GCC 2.95:

  • When a REWIND was issued after a WRITE statement on an unformatted file, the implicit truncation was performed by copying the truncated file to /tmp and copying the result back. This has been fixed by using the ftruncate OS function. Thanks go to the GAMESS developers for bringing this to our attention.
  • Using options -g, -ggdb or -gdwarf[-2] (where appropriate for your target) now also enables debugging information for COMMON BLOCK and EQUIVALENCE items to be emitted. Thanks go to Andrew Vaught (andy@xena.eas.asu.edu) and George Helffrich (george@geology.bristol.ac.uk) for fixing this longstanding problem.
  • It is not necessary anymore to use the option -femulate-complex to compile Fortran code using COMPLEX arithmetic, even on 64-bit machines (like the Alpha). This will improve code generation.
  • INTRINSIC arithmetic functions are now treated as routines that do not depend on anything but their argument(s). This enables further instruction scheduling, because it is known that they cannot read or modify arbitrary locations.
  • Upgrade to libf2c as of 2000-12-05.

    This fixes a bug where a namelist containing initialization of LOGICAL items and a variable starting with T or F would be read incorrectly.

  • The TtyNam intrinsics now set Name to all spaces (at run time) if the system has no ttyname implementation available.
  • Upgrade to libf2c as of 1999-06-28.

    This fixes a bug whereby input to a NAMELIST read involving a repeat count, such as K(5)=10*3, was not properly handled by libf2c. The first item was written to K(5), but the remaining nine were written elsewhere (still within the array), not necessarily starting at K(6).

In 0.5.25, GCC 2.95 (EGCS 1.2) versus EGCS 1.1.2:

  • g77 no longer generates bad code for assignments, or other conversions, of REAL or COMPLEX constant expressions to type INTEGER(KIND=2) (often referred to as INTEGER*8).

    For example, INTEGER*8 J; J = 4E10 now works as documented.

  • g77 no longer truncates INTEGER(KIND=2) (usually INTEGER*8) subscript expressions when evaluating array references on systems with pointers widers than INTEGER(KIND=1) (such as Alphas).
  • g77 no longer generates bad code for an assignment to a COMPLEX variable or array that partially overlaps one or more of the sources of the same assignment (a very rare construction). It now assigns through a temporary, in cases where such partial overlap is deemed possible.
  • libg2c (libf2c) no longer loses track of the file being worked on during a BACKSPACE operation.
  • libg2c (libf2c) fixes a bug whereby input to a NAMELIST read involving a repeat count, such as K(5)=10*3, was not properly handled by libf2c. The first item was written to K(5), but the remaining nine were written elsewhere (still within the array), not necessarily starting at K(6).
  • Automatic arrays now seem to be working on HP-UX systems.
  • The Date intrinsic now returns the correct result on big-endian systems.
  • Fix g77 so it no longer crashes when compiling I/O statements using keywords that define INTEGER values, such as IOSTAT=j, where j is other than default INTEGER (such as INTEGER*2). Instead, it issues a diagnostic.
  • Fix g77 so it properly handles DATA A/rpt*val/, where rpt is not default INTEGER, such as INTEGER*2, instead of producing a spurious diagnostic. Also fix DATA (A(I),I=1,N), where N is not default INTEGER to work instead of crashing g77.
  • The -ax option is now obeyed when compiling Fortran programs. (It is passed to the f771 driver.)
  • The new -fbounds-check option causes g77 to compile run-time bounds checks of array subscripts, as well as of substring start and end points.
  • libg2c now supports building as multilibbed library, which provides better support for systems that require options such as -mieee to work properly.
  • Source file names with the suffixes .FOR and .FPP now are recognized by g77 as if they ended in .for and .fpp, respectively.
  • The order of arguments to the subroutine forms of the CTime, DTime, ETime, and TtyNam intrinsics has been swapped. The argument serving as the returned value for the corresponding function forms now is the second argument, making these consistent with the other subroutine forms of libU77 intrinsics.
  • g77 now warns about a reference to an intrinsic that has an interface that is not Year 2000 (Y2K) compliant. Also, libg2c has been changed to increase the likelihood of catching references to the implementations of these intrinsics using the EXTERNAL mechanism (which would avoid the new warnings).

    See Year 2000 (Y2K) Problems, for more information.

  • g77 now warns about a reference to a function when the corresponding subsequent function program unit disagrees with the reference concerning the type of the function.
  • -fno-emulate-complex is now the default option. This should result in improved performance of code that uses the COMPLEX data type.
  • The -malign-double option now reliably aligns all double-precision variables and arrays on Intel x86 targets.
  • Even without the -malign-double option, g77 reliably aligns local double-precision variables that are not in EQUIVALENCE areas and not SAVE'd.
  • g77 now open-codes ("inlines") division of COMPLEX operands instead of generating a run-time call to the libf2c routines c_div or z_div, unless the -Os option is specified.
  • g77 no longer generates code to maintain errno, a C-language concept, when performing operations such as the SqRt intrinsic.
  • g77 developers can temporarily use the -fflatten-arrays option to compare how the compiler handles code generation using C-like constructs as compared to the Fortran-like method constructs normally used.
  • A substantial portion of the g77 front end's code-generation component was rewritten. It now generates code using facilities more robustly supported by the gcc back end. One effect of this rewrite is that some codes no longer produce a spurious "label lab used before containing binding contour" message.
  • Support for the -fugly option has been removed.
  • Improve documentation and indexing, including information on Year 2000 (Y2K) compliance, and providing more information on internals of the front end.
  • Upgrade to libf2c as of 1999-05-10.

In 0.5.24 versus 0.5.23:

There is no g77 version 0.5.24 at this time, or planned. 0.5.24 is the version number designated for bug fixes and, perhaps, some new features added, to 0.5.23. Version 0.5.23 requires gcc 2.8.1, as 0.5.24 was planned to require.

Due to EGCS becoming GCC (which is now an acronym for "GNU Compiler Collection"), and EGCS 1.2 becoming officially designated GCC 2.95, there seems to be no need for an actual 0.5.24 release.

To reduce the confusion already resulting from use of 0.5.24 to designate g77 versions within EGCS versions 1.0 and 1.1, as well as in versions of g77 documentation and notices during that period, "mainline" g77 version numbering resumes at 0.5.25 with GCC 2.95 (EGCS 1.2), skipping over 0.5.24 as a placeholder version number.

To repeat, there is no g77 0.5.24, but there is now a 0.5.25. Please remain calm and return to your keypunch units.

In EGCS 1.1.2 versus EGCS 1.1.1:

  • Fix the IDate intrinsic (VXT) (in libg2c) so the returned year is in the documented, non-Y2K-compliant range of 0-99, instead of being returned as 100 in the year 2000.

    See IDate Intrinsic (VXT), for more information.

  • Fix the Date_and_Time intrinsic (in libg2c) to return the milliseconds value properly in Values(8).
  • Fix the LStat intrinsic (in libg2c) to return device-ID information properly in SArray(7).
  • Improve documentation.

In EGCS 1.1.1 versus EGCS 1.1:

  • Fix libg2c so it performs an implicit ENDFILE operation (as appropriate) whenever a REWIND is done.

    (This bug was introduced in 0.5.23 and egcs 1.1 in g77's version of libf2c.)

  • Fix libg2c so it no longer crashes with a spurious diagnostic upon doing any I/O following a direct formatted write.

    (This bug was introduced in 0.5.23 and egcs 1.1 in g77's version of libf2c.)

  • Fix g77 so it no longer crashes compiling references to the Rand intrinsic on some systems.
  • Fix g77 portion of installation process so it works better on some systems (those with shells requiring else true clauses on if constructs for the completion code to be set properly).

In EGCS 1.1 versus EGCS 1.0.3:

  • Fix bugs in the libU77 intrinsic HostNm that wrote one byte beyond the end of its CHARACTER argument, and in the libU77 intrinsics GMTime and LTime that overwrote their arguments.
  • Assumed arrays with negative bounds (such as REAL A(-1:*)) no longer elicit spurious diagnostics from g77, even on systems with pointers having different sizes than integers.

    This bug is not known to have existed in any recent version of gcc. It was introduced in an early release of egcs.

  • Valid combinations of EXTERNAL, passing that external as a dummy argument without explicitly giving it a type, and, in a subsequent program unit, referencing that external as an external function with a different type no longer crash g77.
  • CASE DEFAULT no longer crashes g77.
  • The -Wunused option no longer issues a spurious warning about the "master" procedure generated by g77 for procedures containing ENTRY statements.
  • Support FORMAT(I<expr>) when expr is a compile-time constant INTEGER expression.
  • Fix g77 -g option so procedures that use ENTRY can be stepped through, line by line, in gdb.
  • Allow any REAL argument to intrinsics Second and CPU_Time.
  • Use tempnam, if available, to open scratch files (as in OPEN(STATUS='SCRATCH')) so that the TMPDIR environment variable, if present, is used.
  • g77's version of libf2c separates out the setting of global state (such as command-line arguments and signal handling) from main.o into distinct, new library archive members.

    This should make it easier to write portable applications that have their own (non-Fortran) main() routine properly set up the libf2c environment, even when libf2c (now libg2c) is a shared library.

  • g77 no longer installs the f77 command and f77.1 man page in the /usr or /usr/local hierarchy, even if the f77-install-ok file exists in the source or build directory. See the installation documentation for more information.
  • g77 no longer installs the libf2c.a library and f2c.h include file in the /usr or /usr/local hierarchy, even if the f2c-install-ok or f2c-exists-ok files exist in the source or build directory. See the installation documentation for more information.
  • The libf2c.a library produced by g77 has been renamed to libg2c.a. It is installed only in the gcc "private" directory hierarchy, gcc-lib. This allows system administrators and users to choose which version of the libf2c library from netlib they wish to use on a case-by-case basis. See the installation documentation for more information.
  • The f2c.h include (header) file produced by g77 has been renamed to g2c.h. It is installed only in the gcc "private" directory hierarchy, gcc-lib. This allows system administrators and users to choose which version of the include file from netlib they wish to use on a case-by-case basis. See the installation documentation for more information.
  • The g77 command now expects the run-time library to be named libg2c.a instead of libf2c.a, to ensure that a version other than the one built and installed as part of the same g77 version is picked up.
  • During the configuration and build process, g77 creates subdirectories it needs only as it needs them. Other cleaning up of the configuration and build process has been performed as well.
  • install-info now used to update the directory of Info documentation to contain an entry for g77 (during installation).
  • Some diagnostics have been changed from warnings to errors, to prevent inadvertent use of the resulting, probably buggy, programs. These mostly include diagnostics about use of unsupported features in the OPEN, INQUIRE, READ, and WRITE statements, and about truncations of various sorts of constants.
  • Improve compilation of FORMAT expressions so that a null byte is appended to the last operand if it is a constant. This provides a cleaner run-time diagnostic as provided by libf2c for statements like PRINT '(I1', 42.
  • Improve documentation and indexing.
  • The upgrade to libf2c as of 1998-06-18 should fix a variety of problems, including those involving some uses of the T format specifier, and perhaps some build (porting) problems as well.

In EGCS 1.1 versus g77 0.5.23:

  • Fix a code-generation bug that afflicted Intel x86 targets when -O2 was specified compiling, for example, an old version of the DNRM2 routine.

    The x87 coprocessor stack was being mismanaged in cases involving assigned GOTO and ASSIGN.

  • g77 no longer produces incorrect code and initial values for EQUIVALENCE and COMMON aggregates that, due to "unnatural" ordering of members vis-a-vis their types, require initial padding.
  • Fix g77 crash compiling code containing the construct CMPLX(0.) or similar.
  • g77 no longer crashes when compiling code containing specification statements such as INTEGER(KIND=7) PTR.
  • g77 no longer crashes when compiling code such as J = SIGNAL(1, 2).
  • g77 now treats %LOC(expr) and LOC(expr) as "ordinary" expressions when they are used as arguments in procedure calls. This change applies only to global (filewide) analysis, making it consistent with how g77 actually generates code for these cases.

    Previously, g77 treated these expressions as denoting special "pointer" arguments for the purposes of filewide analysis.

  • Fix g77 crash (or apparently infinite run-time) when compiling certain complicated expressions involving COMPLEX arithmetic (especially multiplication).
  • Align static double-precision variables and arrays on Intel x86 targets regardless of whether -malign-double is specified.

    Generally, this affects only local variables and arrays having the SAVE attribute or given initial values via DATA.

  • The g77 driver now ensures that -lg2c is specified in the link phase prior to any occurrence of -lm. This prevents accidentally linking to a routine in the SunOS4 -lm library when the generated code wants to link to the one in libf2c (libg2c).
  • g77 emits more debugging information when -g is used.

    This new information allows, for example, which __g77_length_a to be used in gdb to determine the type of the phantom length argument supplied with CHARACTER variables.

    This information pertains to internally-generated type, variable, and other information, not to the longstanding deficiencies vis-a-vis COMMON and EQUIVALENCE.

  • The F90 Date_and_Time intrinsic now is supported.
  • The F90 System_Clock intrinsic allows the optional arguments (except for the Count argument) to be omitted.
  • Upgrade to libf2c as of 1998-06-18.
  • Improve documentation and indexing.

In 0.5.23 versus 0.5.22:

  • This release contains several regressions against version 0.5.22 of g77, due to using the "vanilla" gcc back end instead of patching it to fix a few bugs and improve performance in a few cases.

    Features that have been dropped from this version of g77 due to their being implemented via g77-specific patches to the gcc back end in previous releases include:

    • Support for __restrict__ keyword, the options -fargument-alias, -fargument-noalias, and -fargument-noalias-global, and the corresponding alias-analysis code.

      (egcs has the alias-analysis code, but not the __restrict__ keyword. egcs g77 users benefit from the alias-analysis code despite the lack of the __restrict__ keyword, which is a C-language construct.)

    • Support for the GNU compiler options -fmove-all-movables, -freduce-all-givs, and -frerun-loop-opt.

      (egcs supports these options. g77 users of egcs benefit from them even if they are not explicitly specified, because the defaults are optimized for g77 users.)

    • Support for the -W option warning about integer division by zero.
    • The Intel x86-specific option -malign-double applying to stack-allocated data as well as statically-allocate data.

    Note that the gcc/f/gbe/ subdirectory has been removed from this distribution as a result of g77 no longer including patches for the gcc back end.

  • Fix bugs in the libU77 intrinsic HostNm that wrote one byte beyond the end of its CHARACTER argument, and in the libU77 intrinsics GMTime and LTime that overwrote their arguments.
  • Support gcc version 2.8, and remove support for prior versions of gcc.
  • Remove support for the --driver option, as g77 now does all the driving, just like gcc.
  • CASE DEFAULT no longer crashes g77.
  • Valid combinations of EXTERNAL, passing that external as a dummy argument without explicitly giving it a type, and, in a subsequent program unit, referencing that external as an external function with a different type no longer crash g77.
  • g77 no longer installs the f77 command and f77.1 man page in the /usr or /usr/local hierarchy, even if the f77-install-ok file exists in the source or build directory. See the installation documentation for more information.
  • g77 no longer installs the libf2c.a library and f2c.h include file in the /usr or /usr/local hierarchy, even if the f2c-install-ok or f2c-exists-ok files exist in the source or build directory. See the installation documentation for more information.
  • The libf2c.a library produced by g77 has been renamed to libg2c.a. It is installed only in the gcc "private" directory hierarchy, gcc-lib. This allows system administrators and users to choose which version of the libf2c library from netlib they wish to use on a case-by-case basis. See the installation documentation for more information.
  • The f2c.h include (header) file produced by g77 has been renamed to g2c.h. It is installed only in the gcc "private" directory hierarchy, gcc-lib. This allows system administrators and users to choose which version of the include file from netlib they wish to use on a case-by-case basis. See the installation documentation for more information.
  • The g77 command now expects the run-time library to be named libg2c.a instead of libf2c.a, to ensure that a version other than the one built and installed as part of the same g77 version is picked up.
  • The -Wunused option no longer issues a spurious warning about the "master" procedure generated by g77 for procedures containing ENTRY statements.
  • g77's version of libf2c separates out the setting of global state (such as command-line arguments and signal handling) from main.o into distinct, new library archive members.

    This should make it easier to write portable applications that have their own (non-Fortran) main() routine properly set up the libf2c environment, even when libf2c (now libg2c) is a shared library.

  • During the configuration and build process, g77 creates subdirectories it needs only as it needs them, thus avoiding unnecessary creation of, for example, stage1/f/runtime when doing a non-bootstrap build. Other cleaning up of the configuration and build process has been performed as well.
  • install-info now used to update the directory of Info documentation to contain an entry for g77 (during installation).
  • Some diagnostics have been changed from warnings to errors, to prevent inadvertent use of the resulting, probably buggy, programs. These mostly include diagnostics about use of unsupported features in the OPEN, INQUIRE, READ, and WRITE statements, and about truncations of various sorts of constants.
  • Improve documentation and indexing.
  • Upgrade to libf2c as of 1998-04-20.

    This should fix a variety of problems, including those involving some uses of the T format specifier, and perhaps some build (porting) problems as well.

In 0.5.22 versus 0.5.21:

  • Fix code generation for iterative DO loops that have one or more references to the iteration variable, or to aliases of it, in their control expressions. For example, DO 10 J=2,J now is compiled correctly.
  • Fix a code-generation bug that afflicted Intel x86 targets when -O2 was specified compiling, for example, an old version of the DNRM2 routine.

    The x87 coprocessor stack was being mismanaged in cases involving assigned GOTO and ASSIGN.

  • Fix DTime intrinsic so as not to truncate results to integer values (on some systems).
  • Fix Signal intrinsic so it offers portable support for 64-bit systems (such as Digital Alphas running GNU/Linux).
  • Fix run-time crash involving NAMELIST on 64-bit machines such as Alphas.
  • Fix g77 version of libf2c so it no longer produces a spurious I/O recursion diagnostic at run time when an I/O operation (such as READ *,I) is interrupted in a manner that causes the program to be terminated via the f_exit routine (such as via C-c).
  • Fix g77 crash triggered by CASE statement with an omitted lower or upper bound.
  • Fix g77 crash compiling references to CPU_Time intrinsic.
  • Fix g77 crash (or apparently infinite run-time) when compiling certain complicated expressions involving COMPLEX arithmetic (especially multiplication).
  • Fix g77 crash on statements such as PRINT *, (REAL(Z(I)),I=1,2), where Z is DOUBLE COMPLEX.
  • Fix a g++ crash.
  • Support FORMAT(I<expr>) when expr is a compile-time constant INTEGER expression.
  • Fix g77 -g option so procedures that use ENTRY can be stepped through, line by line, in gdb.
  • Fix a profiling-related bug in gcc back end for Intel x86 architecture.
  • Allow any REAL argument to intrinsics Second and CPU_Time.
  • Allow any numeric argument to intrinsics Int2 and Int8.
  • Use tempnam, if available, to open scratch files (as in OPEN(STATUS='SCRATCH')) so that the TMPDIR environment variable, if present, is used.
  • Rename the gcc keyword restrict to __restrict__, to avoid rejecting valid, existing, C programs. Support for restrict is now more like support for complex.
  • Fix -fpedantic to not reject procedure invocations such as I=J() and CALL FOO().
  • Fix -fugly-comma to affect invocations of only external procedures. Restore rejection of gratuitous trailing omitted arguments to intrinsics, as in I=MAX(3,4,,).
  • Fix compiler so it accepts -fgnu-intrinsics-* and -fbadu77-intrinsics-* options.
  • Improve diagnostic messages from libf2c so it is more likely that the printing of the active format string is limited to the string, with no trailing garbage being printed.

    (Unlike f2c, g77 did not append a null byte to its compiled form of every format string specified via a FORMAT statement. However, f2c would exhibit the problem anyway for a statement like PRINT '(I)garbage', 1 by printing (I)garbage as the format string.)

  • Improve compilation of FORMAT expressions so that a null byte is appended to the last operand if it is a constant. This provides a cleaner run-time diagnostic as provided by libf2c for statements like PRINT '(I1', 42.
  • Fix various crashes involving code with diagnosed errors.
  • Fix cross-compilation bug when configuring libf2c.
  • Improve diagnostics.
  • Improve documentation and indexing.
  • Upgrade to libf2c as of 1997-09-23. This fixes a formatted-I/O bug that afflicted 64-bit systems with 32-bit integers (such as Digital Alpha running GNU/Linux).

In EGCS 1.0.2 versus EGCS 1.0.1:

  • Fix g77 crash triggered by CASE statement with an omitted lower or upper bound.
  • Fix g77 crash on statements such as PRINT *, (REAL(Z(I)),I=1,2), where Z is DOUBLE COMPLEX.
  • Fix -fPIC (such as compiling for ELF targets) on the Intel x86 architecture target so invalid assembler code is no longer produced.
  • Fix -fpedantic to not reject procedure invocations such as I=J() and CALL FOO().
  • Fix -fugly-comma to affect invocations of only external procedures. Restore rejection of gratuitous trailing omitted arguments to intrinsics, as in I=MAX(3,4,,).
  • Fix compiler so it accepts -fgnu-intrinsics-* and -fbadu77-intrinsics-* options.

In EGCS 1.0.1 versus EGCS 1.0:

  • Fix run-time crash involving NAMELIST on 64-bit machines such as Alphas.

In EGCS 1.0 versus g77 0.5.21:

  • Version 1.0 of egcs contains several regressions against version 0.5.21 of g77, due to using the "vanilla" gcc back end instead of patching it to fix a few bugs and improve performance in a few cases.

    Features that have been dropped from this version of g77 due to their being implemented via g77-specific patches to the gcc back end in previous releases include:

    • Support for the C-language restrict keyword.
    • Support for the -W option warning about integer division by zero.
    • The Intel x86-specific option -malign-double applying to stack-allocated data as well as statically-allocate data.

    Note that the gcc/f/gbe/ subdirectory has been removed from this distribution as a result of g77 being fully integrated with the egcs variant of the gcc back end.

  • Fix code generation for iterative DO loops that have one or more references to the iteration variable, or to aliases of it, in their control expressions. For example, DO 10 J=2,J now is compiled correctly.
  • Fix DTime intrinsic so as not to truncate results to integer values (on some systems).
  • Some Fortran code, miscompiled by g77 built on gcc version 2.8.1 on m68k-next-nextstep3 configurations when using the -O2 option, is now compiled correctly. It is believed that a C function known to miscompile on that configuration when using the -O2 -funroll-loops options also is now compiled correctly.
  • Remove support for non-egcs versions of gcc.
  • Remove support for the --driver option, as g77 now does all the driving, just like gcc.
  • Allow any numeric argument to intrinsics Int2 and Int8.
  • Improve diagnostic messages from libf2c so it is more likely that the printing of the active format string is limited to the string, with no trailing garbage being printed.

    (Unlike f2c, g77 did not append a null byte to its compiled form of every format string specified via a FORMAT statement. However, f2c would exhibit the problem anyway for a statement like PRINT '(I)garbage', 1 by printing (I)garbage as the format string.)

  • Upgrade to libf2c as of 1997-09-23. This fixes a formatted-I/O bug that afflicted 64-bit systems with 32-bit integers (such as Digital Alpha running GNU/Linux).

In 0.5.21:

  • Fix a code-generation bug introduced by 0.5.20 caused by loop unrolling (by specifying -funroll-loops or similar). This bug afflicted all code compiled by version 2.7.2.2.f.2 of gcc (C, C++, Fortran, and so on).
  • Fix a code-generation bug manifested when combining local EQUIVALENCE with a DATA statement that follows the first executable statement (or is treated as an executable-context statement as a result of using the -fpedantic option).
  • Fix a compiler crash that occurred when an integer division by a constant zero is detected. Instead, when the -W option is specified, the gcc back end issues a warning about such a case. This bug afflicted all code compiled by version 2.7.2.2.f.2 of gcc (C, C++, Fortran, and so on).
  • Fix a compiler crash that occurred in some cases of procedure inlining. (Such cases became more frequent in 0.5.20.)
  • Fix a compiler crash resulting from using DATA or similar to initialize a COMPLEX variable or array to zero.
  • Fix compiler crashes involving use of AND, OR, or XOR intrinsics.
  • Fix compiler bug triggered when using a COMMON or EQUIVALENCE variable as the target of an ASSIGN or assigned-GOTO statement.
  • Fix compiler crashes due to using the name of a some non-standard intrinsics (such as FTell or FPutC) as such and as the name of a procedure or common block. Such dual use of a name in a program is allowed by the standard.
  • Place automatic arrays on the stack, even if SAVE or the -fno-automatic option is in effect. This avoids a compiler crash in some cases.
  • The -malign-double option now reliably aligns DOUBLE PRECISION optimally on Pentium and Pentium Pro architectures (586 and 686 in gcc).
  • New option -Wno-globals disables warnings about "suspicious" use of a name both as a global name and as the implicit name of an intrinsic, and warnings about disagreements over the number or natures of arguments passed to global procedures, or the natures of the procedures themselves.

    The default is to issue such warnings, which are new as of this version of g77.

  • New option -fno-globals disables diagnostics about potentially fatal disagreements analysis problems, such as disagreements over the number or natures of arguments passed to global procedures, or the natures of those procedures themselves.

    The default is to issue such diagnostics and flag the compilation as unsuccessful. With this option, the diagnostics are issued as warnings, or, if -Wno-globals is specified, are not issued at all.

    This option also disables inlining of global procedures, to avoid compiler crashes resulting from coding errors that these diagnostics normally would identify.

  • Diagnose cases where a reference to a procedure disagrees with the type of that procedure, or where disagreements about the number or nature of arguments exist. This avoids a compiler crash.
  • Fix parsing bug whereby g77 rejected a second initialization specification immediately following the first's closing / without an intervening comma in a DATA statement, and the second specification was an implied-DO list.
  • Improve performance of the gcc back end so certain complicated expressions involving COMPLEX arithmetic (especially multiplication) don't appear to take forever to compile.
  • Fix a couple of profiling-related bugs in gcc back end.
  • Integrate GNU Ada's (GNAT's) changes to the back end, which consist almost entirely of bug fixes. These fixes are circa version 3.10p of GNAT.
  • Include some other gcc fixes that seem useful in g77's version of gcc. (See gcc/ChangeLog for details--compare it to that file in the vanilla gcc-2.7.2.3.tar.gz distribution.)
  • Fix libU77 routines that accept file and other names to strip trailing blanks from them, for consistency with other implementations. Blanks may be forcibly appended to such names by appending a single null character (CHAR(0)) to the significant trailing blanks.
  • Fix CHMOD intrinsic to work with file names that have embedded blanks, commas, and so on.
  • Fix SIGNAL intrinsic so it accepts an optional third Status argument.
  • Fix IDATE() intrinsic subroutine (VXT form) so it accepts arguments in the correct order. Documentation fixed accordingly, and for GMTIME() and LTIME() as well.
  • Make many changes to libU77 intrinsics to support existing code more directly.

    Such changes include allowing both subroutine and function forms of many routines, changing MCLOCK() and TIME() to return INTEGER(KIND=1) values, introducing MCLOCK8() and TIME8() to return INTEGER(KIND=2) values, and placing functions that are intended to perform side effects in a new intrinsic group, badu77.

  • Improve libU77 so it is more portable.
  • Add options -fbadu77-intrinsics-delete, -fbadu77-intrinsics-hide, and so on.
  • Fix crashes involving diagnosed or invalid code.
  • g77 and gcc now do a somewhat better job detecting and diagnosing arrays that are too large to handle before these cause diagnostics during the assembler or linker phase, a compiler crash, or generation of incorrect code.
  • Make some fixes to alias analysis code.
  • Add support for restrict keyword in gcc front end.
  • Support gcc version 2.7.2.3 (modified by g77 into version 2.7.2.3.f.1), and remove support for prior versions of gcc.
  • Incorporate GNAT's patches to the gcc back end into g77's, so GNAT users do not need to apply GNAT's patches to build both GNAT and g77 from the same source tree.
  • Modify make rules and related code so that generation of Info documentation doesn't require compilation using gcc. Now, any ANSI C compiler should be adequate to produce the g77 documentation (in particular, the tables of intrinsics) from scratch.
  • Add INT2 and INT8 intrinsics.
  • Add CPU_TIME intrinsic.
  • Add ALARM intrinsic.
  • CTIME intrinsic now accepts any INTEGER argument, not just INTEGER(KIND=2).
  • Warn when explicit type declaration disagrees with the type of an intrinsic invocation.
  • Support *f771 entry in gcc specs file.
  • Fix typo in make rule g77-cross, used only for cross-compiling.
  • Fix libf2c build procedure to re-archive library if previous attempt to archive was interrupted.
  • Change gcc to unroll loops only during the last invocation (of as many as two invocations) of loop optimization.
  • Improve handling of -fno-f2c so that code that attempts to pass an intrinsic as an actual argument, such as CALL FOO(ABS), is rejected due to the fact that the run-time-library routine is, effectively, compiled with -ff2c in effect.
  • Fix g77 driver to recognize -fsyntax-only as an option that inhibits linking, just like -c or -S, and to recognize and properly handle the -nostdlib, -M, -MM, -nodefaultlibs, and -Xlinker options.
  • Upgrade to libf2c as of 1997-08-16.
  • Modify libf2c to consistently and clearly diagnose recursive I/O (at run time).
  • g77 driver now prints version information (such as produced by g77 -v) to stderr instead of stdout.
  • The .r suffix now designates a Ratfor source file, to be preprocessed via the ratfor command, available separately.
  • Fix some aspects of how gcc determines what kind of system is being configured and what kinds are supported. For example, GNU Linux/Alpha ELF systems now are directly supported.
  • Improve diagnostics.
  • Improve documentation and indexing.
  • Include all pertinent files for libf2c that come from netlib.bell-labs.com; give any such files that aren't quite accurate in g77's version of libf2c the suffix .netlib.
  • Reserve INTEGER(KIND=0) for future use.

In 0.5.20:

  • The -fno-typeless-boz option is now the default.

    This option specifies that non-decimal-radix constants using the prefixed-radix form (such as Z'1234') are to be interpreted as INTEGER(KIND=1) constants. Specify -ftypeless-boz to cause such constants to be interpreted as typeless.

    (Version 0.5.19 introduced -fno-typeless-boz and its inverse.)

    See Options Controlling Fortran Dialect, for information on the -ftypeless-boz option.

  • Options -ff90-intrinsics-enable and -fvxt-intrinsics-enable now are the defaults.

    Some programs might use names that clash with intrinsic names defined (and now enabled) by these options or by the new libU77 intrinsics. Users of such programs might need to compile them differently (using, for example, -ff90-intrinsics-disable) or, better yet, insert appropriate EXTERNAL statements specifying that these names are not intended to be names of intrinsics.

  • The ALWAYS_FLUSH macro is no longer defined when building libf2c, which should result in improved I/O performance, especially over NFS.

    Note: If you have code that depends on the behavior of libf2c when built with ALWAYS_FLUSH defined, you will have to modify libf2c accordingly before building it from this and future versions of g77.

    See Output Assumed To Flush, for more information.

  • Dave Love's implementation of libU77 has been added to the version of libf2c distributed with and built as part of g77. g77 now knows about the routines in this library as intrinsics.
  • New option -fvxt specifies that the source file is written in VXT Fortran, instead of GNU Fortran.

    See VXT Fortran, for more information on the constructs recognized when the -fvxt option is specified.

  • The -fvxt-not-f90 option has been deleted, along with its inverse, -ff90-not-vxt.

    If you used one of these deleted options, you should re-read the pertinent documentation to determine which options, if any, are appropriate for compiling your code with this version of g77.

    See Other Dialects, for more information.

  • The -fugly option now issues a warning, as it likely will be removed in a future version.

    (Enabling all the -fugly-* options is unlikely to be feasible, or sensible, in the future, so users should learn to specify only those -fugly-* options they really need for a particular source file.)

  • The -fugly-assumed option, introduced in version 0.5.19, has been changed to better accommodate old and new code.

    See Ugly Assumed-Size Arrays, for more information.

  • Make a number of fixes to the g77 front end and the gcc back end to better support Alpha (AXP) machines. This includes providing at least one bug-fix to the gcc back end for Alphas.
  • Related to supporting Alpha (AXP) machines, the LOC() intrinsic and %LOC() construct now return values of INTEGER(KIND=0) type, as defined by the GNU Fortran language.

    This type is wide enough (holds the same number of bits) as the character-pointer type on the machine.

    On most machines, this won't make a difference, whereas, on Alphas and other systems with 64-bit pointers, the INTEGER(KIND=0) type is equivalent to INTEGER(KIND=2) (often referred to as INTEGER*8) instead of the more common INTEGER(KIND=1) (often referred to as INTEGER*4).

  • Emulate COMPLEX arithmetic in the g77 front end, to avoid bugs in complex support in the gcc back end. New option -fno-emulate-complex causes g77 to revert the 0.5.19 behavior.
  • Fix bug whereby REAL A(1), for example, caused a compiler crash if -fugly-assumed was in effect and A was a local (automatic) array. That case is no longer affected by the new handling of -fugly-assumed.
  • Fix g77 command driver so that g77 -o foo.f no longer deletes foo.f before issuing other diagnostics, and so the -x option is properly handled.
  • Enable inlining of subroutines and functions by the gcc back end. This works as it does for gcc itself--program units may be inlined for invocations that follow them in the same program unit, as long as the appropriate compile-time options are specified.
  • Dummy arguments are no longer assumed to potentially alias (overlap) other dummy arguments or COMMON areas when any of these are defined (assigned to) by Fortran code.

    This can result in faster and/or smaller programs when compiling with optimization enabled, though on some systems this effect is observed only when -fforce-addr also is specified.

    New options -falias-check, -fargument-alias, -fargument-noalias, and -fno-argument-noalias-global control the way g77 handles potential aliasing.

    See Aliasing Assumed To Work, for detailed information on why the new defaults might result in some programs no longer working the way they did when compiled by previous versions of g77.

  • The CONJG() and DCONJG() intrinsics now are compiled in-line.
  • The bug-fix for 0.5.19.1 has been re-done. The g77 compiler has been changed back to assume libf2c has no aliasing problems in its implementations of the COMPLEX (and DOUBLE COMPLEX) intrinsics. The libf2c has been changed to have no such problems.

    As a result, 0.5.20 is expected to offer improved performance over 0.5.19.1, perhaps as good as 0.5.19 in most or all cases, due to this change alone.

    Note: This change requires version 0.5.20 of libf2c, at least, when linking code produced by any versions of g77 other than 0.5.19.1. Use g77 -v to determine the version numbers of the libF77, libI77, and libU77 components of the libf2c library. (If these version numbers are not printed--in particular, if the linker complains about unresolved references to names like g77__fvers__--that strongly suggests your installation has an obsolete version of libf2c.)

  • New option -fugly-assign specifies that the same memory locations are to be used to hold the values assigned by both statements I = 3 and ASSIGN 10 TO I, for example. (Normally, g77 uses a separate memory location to hold assigned statement labels.)

    See Ugly Assigned Labels, for more information.

  • FORMAT and ENTRY statements now are allowed to precede IMPLICIT NONE statements.
  • Produce diagnostic for unsupported SELECT CASE on CHARACTER type, instead of crashing, at compile time.
  • Fix crashes involving diagnosed or invalid code.
  • Change approach to building libf2c archive (libf2c.a) so that members are added to it only when truly necessary, so the user that installs an already-built g77 doesn't need to have write access to the build tree (whereas the user doing the build might not have access to install new software on the system).
  • Support gcc version 2.7.2.2 (modified by g77 into version 2.7.2.2.f.2), and remove support for prior versions of gcc.
  • Upgrade to libf2c as of 1997-02-08, and fix up some of the build procedures.
  • Improve general build procedures for g77, fixing minor bugs (such as deletion of any file named f771 in the parent directory of gcc/).
  • Enable full support of INTEGER(KIND=2) (often referred to as INTEGER*8) available in libf2c and f2c.h so that f2c users may make full use of its features via the g77 version of f2c.h and the INTEGER(KIND=2) support routines in the g77 version of libf2c.
  • Improve g77 driver and libf2c so that g77 -v yields version information on the library.
  • The SNGL and FLOAT intrinsics now are specific intrinsics, instead of synonyms for the generic intrinsic REAL.
  • New intrinsics have been added. These are REALPART, IMAGPART, COMPLEX, LONG, and SHORT.
  • A new group of intrinsics, gnu, has been added to contain the new REALPART, IMAGPART, and COMPLEX intrinsics. An old group, dcp, has been removed.
  • Complain about industry-wide ambiguous references REAL(expr) and AIMAG(expr), where expr is DOUBLE COMPLEX (or any complex type other than COMPLEX), unless -ff90 option specifies Fortran 90 interpretation or new -fugly-complex option, in conjunction with -fnot-f90, specifies f2c interpretation.
  • Make improvements to diagnostics.
  • Speed up compiler a bit.
  • Improvements to documentation and indexing, including a new chapter containing information on one, later more, diagnostics that users are directed to pull up automatically via a message in the diagnostic itself.

    (Hence the menu item M for the node Diagnostics in the top-level menu of the Info documentation.)

In previous versions:

Information on previous versions is archived in gcc/gcc/f/news.texi following the test of the DOC-OLDNEWS macro.


Node:NeXTStep Problems, Next:Stack Overflow, Previous:Debugger Problems, Up:But-bugs

NeXTStep Problems

Developers of Fortran code on NeXTStep (all architectures) have to watch out for the following problem when writing programs with large, statically allocated (i.e. non-stack based) data structures (common blocks, saved arrays).

Due to the way the native loader (/bin/ld) lays out data structures in virtual memory, it is very easy to create an executable wherein the __DATA segment overlaps (has addresses in common) with the UNIX STACK segment.

This leads to all sorts of trouble, from the executable simply not executing, to bus errors. The NeXTStep command line tool ebadexec points to the problem as follows:

% /bin/ebadexec a.out
/bin/ebadexec: __LINKEDIT segment (truncated address = 0x3de000
rounded size = 0x2a000) of executable file: a.out overlaps with UNIX
STACK segment (truncated address = 0x400000 rounded size =
0x3c00000) of executable file: a.out

(In the above case, it is the __LINKEDIT segment that overlaps the stack segment.)

This can be cured by assigning the __DATA segment (virtual) addresses beyond the stack segment. A conservative estimate for this is from address 6000000 (hexadecimal) onwards--this has always worked for me [Toon Moene]:

% g77 -segaddr __DATA 6000000 test.f
% ebadexec a.out
ebadexec: file: a.out appears to be executable
%

Browsing through gcc/gcc/f/Makefile.in, you will find that the f771 program itself also has to be linked with these flags--it has large statically allocated data structures. (Version 0.5.18 reduces this somewhat, but probably not enough.)

(The above item was contributed by Toon Moene (toon@moene.indiv.nluug.nl).)


Node:NInt Intrinsic, Next:Not Intrinsic, Previous:Nearest Intrinsic, Up:Table of Intrinsic Functions

NInt Intrinsic

NInt(A)

NInt: INTEGER(KIND=1) function.

A: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns A with the fractional portion of its magnitude eliminated by rounding to the nearest whole number and with its sign preserved, converted to type INTEGER(KIND=1).

If A is type COMPLEX, its real part is rounded and converted.

A fractional portion exactly equal to .5 is rounded to the whole number that is larger in magnitude. (Also called "Fortran round".)

See Int Intrinsic, for how to convert, truncate to whole number.

See ANInt Intrinsic, for how to round to nearest whole number without converting.


Node:No Passing Dummy Assumed-length, Next:No Pathological Implied-DO, Previous:No Passing External Assumed-length, Up:Standard Support

No Passing Dummy Assumed-length

g77 disallows passing of a dummy procedure as an actual argument if the procedure's type is declared CHARACTER*(*).

SUBROUTINE BAR(CFUNC)
CHARACTER*(*) CFUNC
EXTERNAL CFUNC
CALL FOO(CFUNC)
END

It isn't clear whether the standard considers this conforming.


Node:No Passing External Assumed-length, Next:No Passing Dummy Assumed-length, Up:Standard Support

No Passing External Assumed-length

g77 disallows passing of an external procedure as an actual argument if the procedure's type is declared CHARACTER*(*). For example:

CHARACTER*(*) CFUNC
EXTERNAL CFUNC
CALL FOO(CFUNC)
END

It isn't clear whether the standard considers this conforming.


Node:No Pathological Implied-DO, Next:No Useless Implied-DO, Previous:No Passing Dummy Assumed-length, Up:Standard Support

No Pathological Implied-DO

The DO variable for an implied-DO construct in a DATA statement may not be used as the DO variable for an outer implied-DO construct. For example, this fragment is disallowed by g77:

DATA ((A(I, I), I= 1, 10), I= 1, 10) /.../

This also is disallowed by Fortran 90, as it offers no additional capabilities and would have a variety of possible meanings.

Note that it is very unlikely that any production Fortran code tries to use this unsupported construct.


Node:No Useless Implied-DO, Previous:No Pathological Implied-DO, Up:Standard Support

No Useless Implied-DO

An array element initializer in an implied-DO construct in a DATA statement must contain at least one reference to the DO variables of each outer implied-DO construct. For example, this fragment is disallowed by g77:

DATA (A, I= 1, 1) /1./

This also is disallowed by Fortran 90, as FORTRAN 77's more permissive requirements offer no additional capabilities. However, g77 doesn't necessarily diagnose all cases where this requirement is not met.

Note that it is very unlikely that any production Fortran code tries to use this unsupported construct.


Node:Non-bugs, Next:Warnings and Errors, Previous:Disappointments, Up:Trouble

Certain Changes We Don't Want to Make

This section lists changes that people frequently request, but which we do not make because we think GNU Fortran is better without them.

  • Backslash in Constants: Why '\\' is a constant that is one, not two, characters long.
  • Initializing Before Specifying: Why DATA VAR/1/ can't precede COMMON VAR.
  • Context-Sensitive Intrinsicness: Why CALL SQRT won't work.
  • Context-Sensitive Constants: Why 9.435784839284958 is a single-precision constant, and might be interpreted as 9.435785 or similar.
  • Equivalence Versus Equality: Why .TRUE. .EQ. .TRUE. won't work.
  • Order of Side Effects: Why J = IFUNC() - IFUNC() might not behave as expected.


Node:Non-standard Conversions, Next:Non-standard Intrinsics, Previous:Gracefully Handle Sensible Bad Code, Up:Missing Features

Non-standard Conversions

-Wconversion and related should flag places where non-standard conversions are found. Perhaps much of this would be part of -Wugly*.


Node:Non-standard Intrinsics, Next:Modifying DO Variable, Previous:Non-standard Conversions, Up:Missing Features

Non-standard Intrinsics

g77 needs a new option, like -Wintrinsics, to warn about use of non-standard intrinsics without explicit INTRINSIC statements for them. This would help find code that might fail silently when ported to another compiler.


Node:Nonportable Conversions, Next:Large Automatic Arrays, Previous:Floating-point Exception Handling, Up:Missing Features

Nonportable Conversions

g77 doesn't accept some particularly nonportable, silent data-type conversions such as LOGICAL to REAL (as in A=.FALSE., where A is type REAL), that other compilers might quietly accept.

Some of these conversions are accepted by g77 when the -fugly-logint option is specified. Perhaps it should accept more or all of them.


Node:Not Intrinsic, Next:Or Intrinsic, Previous:NInt Intrinsic, Up:Table of Intrinsic Functions

Not Intrinsic

Not(I)

Not: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar; INTENT(IN).

Intrinsic groups: mil, f90, vxt.

Description:

Returns value resulting from boolean NOT of each bit in I.


Node:Not My Type, Next:Variables Assumed To Be Zero, Up:Working Programs

Not My Type

A fruitful source of bugs in Fortran source code is use, or mis-use, of Fortran's implicit-typing feature, whereby the type of a variable, array, or function is determined by the first character of its name.

Simple cases of this include statements like LOGX=9.227, without a statement such as REAL LOGX. In this case, LOGX is implicitly given INTEGER(KIND=1) type, with the result of the assignment being that it is given the value 9.

More involved cases include a function that is defined starting with a statement like DOUBLE PRECISION FUNCTION IPS(...). Any caller of this function that does not also declare IPS as type DOUBLE PRECISION (or, in GNU Fortran, REAL(KIND=2)) is likely to assume it returns INTEGER, or some other type, leading to invalid results or even program crashes.

The -Wimplicit option might catch failures to properly specify the types of variables, arrays, and functions in the code.

However, in code that makes heavy use of Fortran's implicit-typing facility, this option might produce so many warnings about cases that are working, it would be hard to find the one or two that represent bugs. This is why so many experienced Fortran programmers strongly recommend widespread use of the IMPLICIT NONE statement, despite it not being standard FORTRAN 77, to completely turn off implicit typing. (g77 supports IMPLICIT NONE, as do almost all FORTRAN 77 compilers.)

Note that -Wimplicit catches only implicit typing of names. It does not catch implicit typing of expressions such as X**(2/3). Such expressions can be buggy as well--in fact, X**(2/3) is equivalent to X**0, due to the way Fortran expressions are given types and then evaluated. (In this particular case, the programmer probably wanted X**(2./3.).)


Node:Notation Used, Next:Terms and Concepts, Previous:Conformance, Up:Language

Notation Used in This Chapter

(The following information augments or overrides the information in Section 1.5 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 1 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

In this chapter, "must" denotes a requirement, "may" denotes permission, and "must not" and "may not" denote prohibition. Terms such as "might", "should", and "can" generally add little or nothing in the way of weight to the GNU Fortran language itself, but are used to explain or illustrate the language.

For example:

``The FROBNITZ statement must precede all executable
statements in a program unit, and may not specify any dummy
arguments.  It may specify local or common variables and arrays.
Its use should be limited to portions of the program designed to
be non-portable and system-specific, because it might cause the
containing program unit to behave quite differently on different
systems.''

Insofar as the GNU Fortran language is specified, the requirements and permissions denoted by the above sample statement are limited to the placement of the statement and the kinds of things it may specify. The rest of the statement--the content regarding non-portable portions of the program and the differing behavior of program units containing the FROBNITZ statement--does not pertain the GNU Fortran language itself. That content offers advice and warnings about the FROBNITZ statement.

Remember: The GNU Fortran language definition specifies both what constitutes a valid GNU Fortran program and how, given such a program, a valid GNU Fortran implementation is to interpret that program.

It is not incumbent upon a valid GNU Fortran implementation to behave in any particular way, any consistent way, or any predictable way when it is asked to interpret input that is not a valid GNU Fortran program.

Such input is said to have undefined behavior when interpreted by a valid GNU Fortran implementation, though an implementation may choose to specify behaviors for some cases of inputs that are not valid GNU Fortran programs.

Other notation used herein is that of the GNU texinfo format, which is used to generate printed hardcopy, on-line hypertext (Info), and on-line HTML versions, all from a single source document. This notation is used as follows:

  • Keywords defined by the GNU Fortran language are shown in uppercase, as in: COMMON, INTEGER, and BLOCK DATA.

    Note that, in practice, many Fortran programs are written in lowercase--uppercase is used in this manual as a means to readily distinguish keywords and sample Fortran-related text from the prose in this document.

  • Portions of actual sample program, input, or output text look like this: Actual program text.

    Generally, uppercase is used for all Fortran-specific and Fortran-related text, though this does not always include literal text within Fortran code.

    For example: PRINT *, 'My name is Bob'.

  • A metasyntactic variable--that is, a name used in this document to serve as a placeholder for whatever text is used by the user or programmer--appears as shown in the following example:

    "The INTEGER ivar statement specifies that ivar is a variable or array of type INTEGER."

    In the above example, any valid text may be substituted for the metasyntactic variable ivar to make the statement apply to a specific instance, as long as the same text is substituted for both occurrences of ivar.

  • Ellipses ("...") are used to indicate further text that is either unimportant or expanded upon further, elsewhere.
  • Names of data types are in the style of Fortran 90, in most cases.

    See Kind Notation, for information on the relationship between Fortran 90 nomenclature (such as INTEGER(KIND=1)) and the more traditional, less portably concise nomenclature (such as INTEGER*4).


Node:Nothing Happens, Next:Strange Behavior at Run Time, Previous:Stack Overflow, Up:But-bugs

Nothing Happens

It is occasionally reported that a "simple" program, such as a "Hello, World!" program, does nothing when it is run, even though the compiler reported no errors, despite the program containing nothing other than a simple PRINT statement.

This most often happens because the program has been compiled and linked on a UNIX system and named test, though other names can lead to similarly unexpected run-time behavior on various systems.

Essentially this problem boils down to giving your program a name that is already known to the shell you are using to identify some other program, which the shell continues to execute instead of your program when you invoke it via, for example:

sh# test
sh#

Under UNIX and many other system, a simple command name invokes a searching mechanism that might well not choose the program located in the current working directory if there is another alternative (such as the test command commonly installed on UNIX systems).

The reliable way to invoke a program you just linked in the current directory under UNIX is to specify it using an explicit pathname, as in:

sh# ./test
 Hello, World!
sh#

Users who encounter this problem should take the time to read up on how their shell searches for commands, how to set their search path, and so on. The relevant UNIX commands to learn about include man, info (on GNU systems), setenv (or set and env), which, and find.


Node:Old-style PARAMETER Statements, Next:TYPE and ACCEPT I/O Statements, Previous:Q Edit Descriptor, Up:Missing Features

Old-style PARAMETER Statements

g77 doesn't accept PARAMETER I=1. Supporting this obsolete form of the PARAMETER statement would not be particularly hard, as most of the parsing code is already in place and working.

Until time/money is spent implementing it, you might as well fix your code to use the standard form, PARAMETER (I=1) (possibly needing INTEGER I preceding the PARAMETER statement as well, otherwise, in the obsolete form of PARAMETER, the type of the variable is set from the type of the constant being assigned to it).


Node:OPEN CLOSE and INQUIRE Keywords, Next:ENCODE and DECODE, Previous:STRUCTURE UNION RECORD MAP, Up:Missing Features

OPEN, CLOSE, and INQUIRE Keywords

g77 doesn't have support for keywords such as DISP='DELETE' in the OPEN, CLOSE, and INQUIRE statements. These extensions are easy to add to g77 itself, but require much more work on libg2c.

g77 doesn't support FORM='PRINT' or an equivalent to translate the traditional `carriage control' characters in column 1 of output to use backspaces, carriage returns and the like. However programs exist to translate them in output files (or standard output). These are typically called either fpr or asa. You can get a version of asa from ftp://sunsite.unc.edu/pub/Linux/devel/lang/fortran for GNU systems which will probably build easily on other systems. Alternatively, fpr is in BSD distributions in various archive sites.


Node:Open Questions, Next:Bugs, Previous:Trouble, Up:Top

Open Questions

Please consider offering useful answers to these questions!

  • LOC() and other intrinsics are probably somewhat misclassified. Is the a need for more precise classification of intrinsics, and if so, what are the appropriate groupings? Is there a need to individually enable/disable/delete/hide intrinsics from the command line?


Node:Optimize Options, Next:Preprocessor Options, Previous:Debugging Options, Up:Invoking G77

Options That Control Optimization

Most Fortran users will want to use no optimization when developing and testing programs, and use -O or -O2 when compiling programs for late-cycle testing and for production use. However, note that certain diagnostics--such as for uninitialized variables--depend on the flow analysis done by -O, i.e. you must use -O or -O2 to get such diagnostics.

The following flags have particular applicability when compiling Fortran programs:

-malign-double
(Intel x86 architecture only.)

Noticeably improves performance of g77 programs making heavy use of REAL(KIND=2) (DOUBLE PRECISION) data on some systems. In particular, systems using Pentium, Pentium Pro, 586, and 686 implementations of the i386 architecture execute programs faster when REAL(KIND=2) (DOUBLE PRECISION) data are aligned on 64-bit boundaries in memory.

This option can, at least, make benchmark results more consistent across various system configurations, versions of the program, and data sets.

Note: The warning in the gcc documentation about this option does not apply, generally speaking, to Fortran code compiled by g77

See Aligned Data, for more information on alignment issues.

Also also note: The negative form of -malign-double is -mno-align-double, not -benign-double.

-ffloat-store
Might help a Fortran program that depends on exact IEEE conformance on some machines, but might slow down a program that doesn't.

This option is effective when the floating-point unit is set to work in IEEE 854 `extended precision'--as it typically is on x86 and m68k GNU systems--rather than IEEE 754 double precision. -ffloat-store tries to remove the extra precision by spilling data from floating-point registers into memory and this typically involves a big performance hit. However, it doesn't affect intermediate results, so that it is only partially effective. `Excess precision' is avoided in code like:

a = b + c
d = a * e
but not in code like:
      d = (b + c) * e

For another, potentially better, way of controlling the precision, see Floating-point precision.

-fforce-mem
-fforce-addr
Might improve optimization of loops.
-fno-inline
Don't compile statement functions inline. Might reduce the size of a program unit--which might be at expense of some speed (though it should compile faster). Note that if you are not optimizing, no functions can be expanded inline.
-ffast-math
Might allow some programs designed to not be too dependent on IEEE behavior for floating-point to run faster, or die trying. Sets -funsafe-math-optimizations, and -fno-trapping-math.
-funsafe-math-optimizations
Allow optimizations that may be give incorrect results for certain IEEE inputs.
-fno-trapping-math
Allow the compiler to assume that floating-point arithmetic will not generate traps on any inputs. This is useful, for example, when running a program using IEEE "non-stop" floating-point arithmetic.
-fstrength-reduce
Might make some loops run faster.
-frerun-cse-after-loop
-fexpensive-optimizations
-fdelayed-branch
-fschedule-insns
-fschedule-insns2
-fcaller-saves
Might improve performance on some code.
-funroll-loops
Typically improves performance on code using iterative DO loops by unrolling them and is probably generally appropriate for Fortran, though it is not turned on at any optimization level. Note that outer loop unrolling isn't done specifically; decisions about whether to unroll a loop are made on the basis of its instruction count.

Also, no `loop discovery'1 is done, so only loops written with DO benefit from loop optimizations, including--but not limited to--unrolling. Loops written with IF and GOTO are not currently recognized as such. This option unrolls only iterative DO loops, not DO WHILE loops.

-funroll-all-loops
Probably improves performance on code using DO WHILE loops by unrolling them in addition to iterative DO loops. In the absence of DO WHILE, this option is equivalent to -funroll-loops but possibly slower.
-fno-move-all-movables
-fno-reduce-all-givs
-fno-rerun-loop-opt
Version info: These options are not supported by versions of g77 based on gcc version 2.8.

Each of these might improve performance on some code.

Analysis of Fortran code optimization and the resulting optimizations triggered by the above options were contributed by Toon Moene (toon@moene.indiv.nluug.nl).

These three options are intended to be removed someday, once they have helped determine the efficacy of various approaches to improving the performance of Fortran code.

Please let us know how use of these options affects the performance of your production code. We're particularly interested in code that runs faster when these options are disabled, and in non-Fortran code that benefits when they are enabled via the above gcc command-line options.

See Options That Control Optimization, for more information on options to optimize the generated machine code.

Footnotes

  1. loop discovery refers to the process by which a compiler, or indeed any reader of a program, determines which portions of the program are more likely to be executed repeatedly as it is being run. Such discovery typically is done early when compiling using optimization techniques, so the ``discovered'' loops get more attention---and more run-time resources, such as registers---from the compiler. It is easy to ``discover'' loops that are constructed out of looping constructs in the language (such as Fortran's DO). For some programs, ``discovering'' loops constructed out of lower-level constructs (such as IF and GOTO) can lead to generation of more optimal code than otherwise.


Node:Option Summary, Next:Overall Options, Up:Invoking G77

Option Summary

Here is a summary of all the options specific to GNU Fortran, grouped by type. Explanations are in the following sections.

Overall Options
See Options Controlling the Kind of Output.
-fversion  -fset-g77-defaults  -fno-silent

Shorthand Options
See Shorthand Options.
-ff66  -fno-f66  -ff77  -fno-f77  -fno-ugly

Fortran Language Options
See Options Controlling Fortran Dialect.
-ffree-form  -fno-fixed-form  -ff90
-fvxt  -fdollar-ok  -fno-backslash
-fno-ugly-args  -fno-ugly-assign  -fno-ugly-assumed
-fugly-comma  -fugly-complex  -fugly-init  -fugly-logint
-fonetrip  -ftypeless-boz
-fintrin-case-initcap  -fintrin-case-upper
-fintrin-case-lower  -fintrin-case-any
-fmatch-case-initcap  -fmatch-case-upper
-fmatch-case-lower  -fmatch-case-any
-fsource-case-upper  -fsource-case-lower
-fsource-case-preserve
-fsymbol-case-initcap  -fsymbol-case-upper
-fsymbol-case-lower  -fsymbol-case-any
-fcase-strict-upper  -fcase-strict-lower
-fcase-initcap  -fcase-upper  -fcase-lower  -fcase-preserve
-ff2c-intrinsics-delete  -ff2c-intrinsics-hide
-ff2c-intrinsics-disable  -ff2c-intrinsics-enable
-fbadu77-intrinsics-delete  -fbadu77-intrinsics-hide
-fbadu77-intrinsics-disable  -fbadu77-intrinsics-enable
-ff90-intrinsics-delete  -ff90-intrinsics-hide
-ff90-intrinsics-disable  -ff90-intrinsics-enable
-fgnu-intrinsics-delete  -fgnu-intrinsics-hide
-fgnu-intrinsics-disable  -fgnu-intrinsics-enable
-fmil-intrinsics-delete  -fmil-intrinsics-hide
-fmil-intrinsics-disable  -fmil-intrinsics-enable
-funix-intrinsics-delete  -funix-intrinsics-hide
-funix-intrinsics-disable  -funix-intrinsics-enable
-fvxt-intrinsics-delete  -fvxt-intrinsics-hide
-fvxt-intrinsics-disable  -fvxt-intrinsics-enable
-ffixed-line-length-n  -ffixed-line-length-none

Warning Options
See Options to Request or Suppress Warnings.
-fsyntax-only  -pedantic  -pedantic-errors  -fpedantic
-w  -Wno-globals  -Wimplicit  -Wunused  -Wuninitialized
-Wall  -Wsurprising
-Werror  -W

Debugging Options
See Options for Debugging Your Program or GCC.
-g

Optimization Options
See Options that Control Optimization.
-malign-double
-ffloat-store  -fforce-mem  -fforce-addr  -fno-inline
-ffast-math  -fstrength-reduce  -frerun-cse-after-loop
-funsafe-math-optimizations -fno-trapping-math
-fexpensive-optimizations  -fdelayed-branch
-fschedule-insns  -fschedule-insn2  -fcaller-saves
-funroll-loops  -funroll-all-loops
-fno-move-all-movables  -fno-reduce-all-givs
-fno-rerun-loop-opt

Directory Options
See Options for Directory Search.
-Idir  -I-

Code Generation Options
See Options for Code Generation Conventions.
-fno-automatic  -finit-local-zero  -fno-f2c
-ff2c-library  -fno-underscoring  -fno-ident
-fpcc-struct-return  -freg-struct-return
-fshort-double  -fno-common  -fpack-struct
-fzeros  -fno-second-underscore
-femulate-complex
-falias-check  -fargument-alias
-fargument-noalias  -fno-argument-noalias-global
-fno-globals  -fflatten-arrays
-fbounds-check  -ffortran-bounds-check
  • Overall Options: Controlling the kind of output: an executable, object files, assembler files, or preprocessed source.
  • Shorthand Options: Options that are shorthand for other options.
  • Fortran Dialect Options: Controlling the variant of Fortran language compiled.
  • Warning Options: How picky should the compiler be?
  • Debugging Options: Symbol tables, measurements, and debugging dumps.
  • Optimize Options: How much optimization?
  • Preprocessor Options: Controlling header files and macro definitions. Also, getting dependency information for Make.
  • Directory Options: Where to find header files and libraries. Where to find the compiler executable files.
  • Code Gen Options: Specifying conventions for function calls, data layout and register usage.


Node:Order of Side Effects, Previous:Equivalence Versus Equality, Up:Non-bugs

Order of Side Effects

g77 does not necessarily produce code that, when run, performs side effects (such as those performed by function invocations) in the same order as in some other compiler--or even in the same order as another version, port, or invocation (using different command-line options) of g77.

It is never safe to depend on the order of evaluation of side effects. For example, an expression like this may very well behave differently from one compiler to another:

J = IFUNC() - IFUNC()

There is no guarantee that IFUNC will be evaluated in any particular order. Either invocation might happen first. If IFUNC returns 5 the first time it is invoked, and returns 12 the second time, J might end up with the value 7, or it might end up with -7.

Generally, in Fortran, procedures with side-effects intended to be visible to the caller are best designed as subroutines, not functions. Examples of such side-effects include:

  • The generation of random numbers that are intended to influence return values.
  • Performing I/O (other than internal I/O to local variables).
  • Updating information in common blocks.

An example of a side-effect that is not intended to be visible to the caller is a function that maintains a cache of recently calculated results, intended solely to speed repeated invocations of the function with identical arguments. Such a function can be safely used in expressions, because if the compiler optimizes away one or more calls to the function, operation of the program is unaffected (aside from being speeded up).


Node:Order, Next:INCLUDE, Previous:Statement Labels, Up:Characters Lines Sequence

Order of Statements and Lines

(Corresponds to Section 3.5 of ANSI X3.9-1978 FORTRAN 77.)

Generally, DATA statements may precede executable statements. However, specification statements pertaining to any entities initialized by a DATA statement must precede that DATA statement. For example, after DATA I/1/, INTEGER I is not permitted, but INTEGER J is permitted.

The last line of a program unit may be an END statement, or may be:

  • An END PROGRAM statement, if the program unit is a main program.
  • An END SUBROUTINE statement, if the program unit is a subroutine.
  • An END FUNCTION statement, if the program unit is a function.
  • An END BLOCK DATA statement, if the program unit is a block data.


Node:Other Compilers, Next:Other Languages, Previous:Other Dialects, Up:Top

Other Compilers

An individual Fortran source file can be compiled to an object (*.o) file instead of to the final program executable. This allows several portions of a program to be compiled at different times and linked together whenever a new version of the program is needed. However, it introduces the issue of object compatibility across the various object files (and libraries, or *.a files) that are linked together to produce any particular executable file.

Object compatibility is an issue when combining, in one program, Fortran code compiled by more than one compiler (or more than one configuration of a compiler). If the compilers disagree on how to transform the names of procedures, there will normally be errors when linking such programs. Worse, if the compilers agree on naming, but disagree on issues like how to pass parameters, return arguments, and lay out COMMON areas, the earliest detected errors might be the incorrect results produced by the program (and that assumes these errors are detected, which is not always the case).

Normally, g77 generates code that is object-compatible with code generated by a version of f2c configured (with, for example, f2c.h definitions) to be generally compatible with g77 as built by gcc. (Normally, f2c will, by default, conform to the appropriate configuration, but it is possible that older or perhaps even newer versions of f2c, or versions having certain configuration changes to f2c internals, will produce object files that are incompatible with g77.)

For example, a Fortran string subroutine argument will become two arguments on the C side: a char * and an int length.

Much of this compatibility results from the fact that g77 uses the same run-time library, libf2c, used by f2c, though g77 gives its version the name libg2c so as to avoid conflicts when linking, installing them in the same directories, and so on.

Other compilers might or might not generate code that is object-compatible with libg2c and current g77, and some might offer such compatibility only when explicitly selected via a command-line option to the compiler.

Note: This portion of the documentation definitely needs a lot of work!

  • Dropping f2c Compatibility: When speed is more important.
  • Compilers Other Than f2c: Interoperation with code from other compilers.


Node:Other Dialects, Next:Other Compilers, Previous:Compiler, Up:Top

Other Dialects

GNU Fortran supports a variety of features that are not considered part of the GNU Fortran language itself, but are representative of various dialects of Fortran that g77 supports in whole or in part.

Any of the features listed below might be disallowed by g77 unless some command-line option is specified. Currently, some of the features are accepted using the default invocation of g77, but that might change in the future.

Note: This portion of the documentation definitely needs a lot of work!

  • Source Form: Details of fixed-form and free-form source.
  • Trailing Comment: Use of /* to start a comment.
  • Debug Line: Use of D in column 1.
  • Dollar Signs: Use of $ in symbolic names.
  • Case Sensitivity: Uppercase and lowercase in source files.
  • VXT Fortran: ...versus the GNU Fortran language.
  • Fortran 90: ...versus the GNU Fortran language.
  • Pedantic Compilation: Enforcing the standard.
  • Distensions: Misfeatures supported by GNU Fortran.


Node:Other Intrinsics, Previous:Intrinsic Groups, Up:Compiler Intrinsics

Other Intrinsics

g77 supports intrinsics other than those in the GNU Fortran language proper. This set of intrinsics is described below.

  • ACosD Intrinsic: (Reserved for future use.)

  • AIMax0 Intrinsic: (Reserved for future use.)
  • AIMin0 Intrinsic: (Reserved for future use.)

  • AJMax0 Intrinsic: (Reserved for future use.)
  • AJMin0 Intrinsic: (Reserved for future use.)

  • ASinD Intrinsic: (Reserved for future use.)

  • ATan2D Intrinsic: (Reserved for future use.)
  • ATanD Intrinsic: (Reserved for future use.)

  • BITest Intrinsic: (Reserved for future use.)

  • BJTest Intrinsic: (Reserved for future use.)

  • CDAbs Intrinsic: Absolute value (archaic).
  • CDCos Intrinsic: Cosine (archaic).
  • CDExp Intrinsic: Exponential (archaic).
  • CDLog Intrinsic: Natural logarithm (archaic).
  • CDSin Intrinsic: Sine (archaic).
  • CDSqRt Intrinsic: Square root (archaic).

  • ChDir Intrinsic (function): Change directory.

  • ChMod Intrinsic (function): Change file modes.

  • CosD Intrinsic: (Reserved for future use.)

  • DACosD Intrinsic: (Reserved for future use.)

  • DASinD Intrinsic: (Reserved for future use.)

  • DATan2D Intrinsic: (Reserved for future use.)
  • DATanD Intrinsic: (Reserved for future use.)
  • Date Intrinsic: Get current date as dd-Mon-yy.

  • DbleQ Intrinsic: (Reserved for future use.)

  • DCmplx Intrinsic: Construct COMPLEX(KIND=2) value.
  • DConjg Intrinsic: Complex conjugate (archaic).

  • DCosD Intrinsic: (Reserved for future use.)

  • DFloat Intrinsic: Conversion (archaic).

  • DFlotI Intrinsic: (Reserved for future use.)
  • DFlotJ Intrinsic: (Reserved for future use.)

  • DImag Intrinsic: Convert/extract imaginary part of complex (archaic).

  • DReal Intrinsic: Convert value to type REAL(KIND=2).

  • DSinD Intrinsic: (Reserved for future use.)

  • DTanD Intrinsic: (Reserved for future use.)

  • DTime Intrinsic (function): Get elapsed time since last time.

  • FGet Intrinsic (function): Read a character from unit 5 stream-wise.

  • FGetC Intrinsic (function): Read a character stream-wise.

  • FloatI Intrinsic: (Reserved for future use.)
  • FloatJ Intrinsic: (Reserved for future use.)

  • FPut Intrinsic (function): Write a character to unit 6 stream-wise.

  • FPutC Intrinsic (function): Write a character stream-wise.

  • IDate Intrinsic (VXT): Get local time info (VAX/VMS).

  • IIAbs Intrinsic: (Reserved for future use.)
  • IIAnd Intrinsic: (Reserved for future use.)
  • IIBClr Intrinsic: (Reserved for future use.)
  • IIBits Intrinsic: (Reserved for future use.)
  • IIBSet Intrinsic: (Reserved for future use.)
  • IIDiM Intrinsic: (Reserved for future use.)
  • IIDInt Intrinsic: (Reserved for future use.)
  • IIDNnt Intrinsic: (Reserved for future use.)
  • IIEOr Intrinsic: (Reserved for future use.)
  • IIFix Intrinsic: (Reserved for future use.)
  • IInt Intrinsic: (Reserved for future use.)
  • IIOr Intrinsic: (Reserved for future use.)
  • IIQint Intrinsic: (Reserved for future use.)
  • IIQNnt Intrinsic: (Reserved for future use.)
  • IIShftC Intrinsic: (Reserved for future use.)
  • IISign Intrinsic: (Reserved for future use.)

  • IMax0 Intrinsic: (Reserved for future use.)
  • IMax1 Intrinsic: (Reserved for future use.)
  • IMin0 Intrinsic: (Reserved for future use.)
  • IMin1 Intrinsic: (Reserved for future use.)
  • IMod Intrinsic: (Reserved for future use.)

  • INInt Intrinsic: (Reserved for future use.)
  • INot Intrinsic: (Reserved for future use.)

  • IZExt Intrinsic: (Reserved for future use.)
  • JIAbs Intrinsic: (Reserved for future use.)
  • JIAnd Intrinsic: (Reserved for future use.)
  • JIBClr Intrinsic: (Reserved for future use.)
  • JIBits Intrinsic: (Reserved for future use.)
  • JIBSet Intrinsic: (Reserved for future use.)
  • JIDiM Intrinsic: (Reserved for future use.)
  • JIDInt Intrinsic: (Reserved for future use.)
  • JIDNnt Intrinsic: (Reserved for future use.)
  • JIEOr Intrinsic: (Reserved for future use.)
  • JIFix Intrinsic: (Reserved for future use.)
  • JInt Intrinsic: (Reserved for future use.)
  • JIOr Intrinsic: (Reserved for future use.)
  • JIQint Intrinsic: (Reserved for future use.)
  • JIQNnt Intrinsic: (Reserved for future use.)
  • JIShft Intrinsic: (Reserved for future use.)
  • JIShftC Intrinsic: (Reserved for future use.)
  • JISign Intrinsic: (Reserved for future use.)
  • JMax0 Intrinsic: (Reserved for future use.)
  • JMax1 Intrinsic: (Reserved for future use.)
  • JMin0 Intrinsic: (Reserved for future use.)
  • JMin1 Intrinsic: (Reserved for future use.)
  • JMod Intrinsic: (Reserved for future use.)
  • JNInt Intrinsic: (Reserved for future use.)
  • JNot Intrinsic: (Reserved for future use.)
  • JZExt Intrinsic: (Reserved for future use.)

  • Kill Intrinsic (function): Signal a process.

  • Link Intrinsic (function): Make hard link in file system.

  • QAbs Intrinsic: (Reserved for future use.)
  • QACos Intrinsic: (Reserved for future use.)
  • QACosD Intrinsic: (Reserved for future use.)
  • QASin Intrinsic: (Reserved for future use.)
  • QASinD Intrinsic: (Reserved for future use.)
  • QATan Intrinsic: (Reserved for future use.)
  • QATan2 Intrinsic: (Reserved for future use.)
  • QATan2D Intrinsic: (Reserved for future use.)
  • QATanD Intrinsic: (Reserved for future use.)
  • QCos Intrinsic: (Reserved for future use.)
  • QCosD Intrinsic: (Reserved for future use.)
  • QCosH Intrinsic: (Reserved for future use.)
  • QDiM Intrinsic: (Reserved for future use.)
  • QExp Intrinsic: (Reserved for future use.)
  • QExt Intrinsic: (Reserved for future use.)
  • QExtD Intrinsic: (Reserved for future use.)
  • QFloat Intrinsic: (Reserved for future use.)
  • QInt Intrinsic: (Reserved for future use.)
  • QLog Intrinsic: (Reserved for future use.)
  • QLog10 Intrinsic: (Reserved for future use.)
  • QMax1 Intrinsic: (Reserved for future use.)
  • QMin1 Intrinsic: (Reserved for future use.)
  • QMod Intrinsic: (Reserved for future use.)
  • QNInt Intrinsic: (Reserved for future use.)
  • QSin Intrinsic: (Reserved for future use.)
  • QSinD Intrinsic: (Reserved for future use.)
  • QSinH Intrinsic: (Reserved for future use.)
  • QSqRt Intrinsic: (Reserved for future use.)
  • QTan Intrinsic: (Reserved for future use.)
  • QTanD Intrinsic: (Reserved for future use.)
  • QTanH Intrinsic: (Reserved for future use.)

  • Rename Intrinsic (function): Rename file.

  • Secnds Intrinsic: Get local time offset since midnight.

  • Signal Intrinsic (function): Muck with signal handling.

  • SinD Intrinsic: (Reserved for future use.)

  • SnglQ Intrinsic: (Reserved for future use.)

  • SymLnk Intrinsic (function): Make symbolic link in file system.

  • System Intrinsic (function): Invoke shell (system) command.

  • TanD Intrinsic: (Reserved for future use.)

  • Time Intrinsic (VXT): Get the time as a character value.

  • UMask Intrinsic (function): Set file creation permissions mask.

  • Unlink Intrinsic (function): Unlink file.

  • ZExt Intrinsic: (Reserved for future use.)


Node:Other Languages, Next:Debugging and Interfacing, Previous:Other Compilers, Up:Top

Other Languages

Note: This portion of the documentation definitely needs a lot of work!

  • Interoperating with C and C++:


Node:Output Assumed To Flush, Next:Large File Unit Numbers, Previous:Aliasing Assumed To Work, Up:Working Programs

Output Assumed To Flush

For several versions prior to 0.5.20, g77 configured its version of the libf2c run-time library so that one of its configuration macros, ALWAYS_FLUSH, was defined.

This was done as a result of a belief that many programs expected output to be flushed to the operating system (under UNIX, via the fflush() library call) with the result that errors, such as disk full, would be immediately flagged via the relevant ERR= and IOSTAT= mechanism.

Because of the adverse effects this approach had on the performance of many programs, g77 no longer configures libf2c (now named libg2c in its g77 incarnation) to always flush output.

If your program depends on this behavior, either insert the appropriate CALL FLUSH statements, or modify the sources to the libg2c, rebuild and reinstall g77, and relink your programs with the modified library.

(Ideally, libg2c would offer the choice at run-time, so that a compile-time option to g77 or f2c could result in generating the appropriate calls to flushing or non-flushing library routines.)

Some Fortran programs require output (writes) to be flushed to the operating system (under UNIX, via the fflush() library call) so that errors, such as disk full, are immediately flagged via the relevant ERR= and IOSTAT= mechanism, instead of such errors being flagged later as subsequent writes occur, forcing the previously written data to disk, or when the file is closed.

Essentially, the difference can be viewed as synchronous error reporting (immediate flagging of errors during writes) versus asynchronous, or, more precisely, buffered error reporting (detection of errors might be delayed).

libg2c supports flagging write errors immediately when it is built with the ALWAYS_FLUSH macro defined. This results in a libg2c that runs slower, sometimes quite a bit slower, under certain circumstances--for example, accessing files via the networked file system NFS--but the effect can be more reliable, robust file I/O.

If you know that Fortran programs requiring this level of precision of error reporting are to be compiled using the version of g77 you are building, you might wish to modify the g77 source tree so that the version of libg2c is built with the ALWAYS_FLUSH macro defined, enabling this behavior.

To do this, find this line in gcc/libf2c/f2c.h in your g77 source tree:

/* #define ALWAYS_FLUSH */

Remove the leading /* , so the line begins with #define, and the trailing  */.

Then build or rebuild g77 as appropriate.


Node:Overall Options, Next:Shorthand Options, Previous:Option Summary, Up:Invoking G77

Options Controlling the Kind of Output

Compilation can involve as many as four stages: preprocessing, code generation (often what is really meant by the term "compilation"), assembly, and linking, always in that order. The first three stages apply to an individual source file, and end by producing an object file; linking combines all the object files (those newly compiled, and those specified as input) into an executable file.

For any given input file, the file name suffix determines what kind of program is contained in the file--that is, the language in which the program is written is generally indicated by the suffix. Suffixes specific to GNU Fortran are listed below. See Options Controlling the Kind of Output, for information on suffixes recognized by GNU CC.

file.f
file.for
file.FOR
Fortran source code that should not be preprocessed.

Such source code cannot contain any preprocessor directives, such as #include, #define, #if, and so on.

You can force .f files to be preprocessed by cpp by using -x f77-cpp-input. See LEX.

file.F
file.fpp
file.FPP
Fortran source code that must be preprocessed (by the C preprocessor cpp, which is part of GNU CC).

Note that preprocessing is not extended to the contents of files included by the INCLUDE directive--the #include preprocessor directive must be used instead.

file.r
Ratfor source code, which must be preprocessed by the ratfor command, which is available separately (as it is not yet part of the GNU Fortran distribution). One version in Fortran, adapted for use with g77 is at ftp://members.aol.com/n8tm/rat7.uue (of uncertain copyright status). Another, public domain version in C is at http://sepwww.stanford.edu/sep/prof/ratfor.shar.2.

UNIX users typically use the file.f and file.F nomenclature. Users of other operating systems, especially those that cannot distinguish upper-case letters from lower-case letters in their file names, typically use the file.for and file.fpp nomenclature.

Use of the preprocessor cpp allows use of C-like constructs such as #define and #include, but can lead to unexpected, even mistaken, results due to Fortran's source file format. It is recommended that use of the C preprocessor be limited to #include and, in conjunction with #define, only #if and related directives, thus avoiding in-line macro expansion entirely. This recommendation applies especially when using the traditional fixed source form. With free source form, fewer unexpected transformations are likely to happen, but use of constructs such as Hollerith and character constants can nevertheless present problems, especially when these are continued across multiple source lines. These problems result, primarily, from differences between the way such constants are interpreted by the C preprocessor and by a Fortran compiler.

Another example of a problem that results from using the C preprocessor is that a Fortran comment line that happens to contain any characters "interesting" to the C preprocessor, such as a backslash at the end of the line, is not recognized by the preprocessor as a comment line, so instead of being passed through "raw", the line is edited according to the rules for the preprocessor. For example, the backslash at the end of the line is removed, along with the subsequent newline, resulting in the next line being effectively commented out--unfortunate if that line is a non-comment line of important code!

Note: The -traditional and -undef flags are supplied to cpp by default, to help avoid unpleasant surprises. See Options Controlling the Preprocessor. This means that ANSI C preprocessor features (such as the # operator) aren't available, and only variables in the C reserved namespace (generally, names with a leading underscore) are liable to substitution by C predefines. Thus, if you want to do system-specific tests, use, for example, #ifdef __linux__ rather than #ifdef linux. Use the -v option to see exactly how the preprocessor is invoked.

Unfortunately, the -traditional flag will not avoid an error from anything that cpp sees as an unterminated C comment, such as:

C Some Fortran compilers accept /* as starting
C an inline comment.
See Trailing Comment.

The following options that affect overall processing are recognized by the g77 and gcc commands in a GNU Fortran installation:

-fversion
Ensure that the g77 version of the compiler phase is reported, if run, and, starting in egcs version 1.1, that internal consistency checks in the f771 program are run.

This option is supplied automatically when -v or --verbose is specified as a command-line option for g77 or gcc and when the resulting commands compile Fortran source files.

In GCC 3.1, this is changed back to the behaviour gcc displays for .c files.

-fset-g77-defaults
Version info: This option was obsolete as of egcs version 1.1. The effect is instead achieved by the lang_init_options routine in gcc/gcc/f/com.c.

Set up whatever gcc options are to apply to Fortran compilations, and avoid running internal consistency checks that might take some time.

This option is supplied automatically when compiling Fortran code via the g77 or gcc command. The description of this option is provided so that users seeing it in the output of, say, g77 -v understand why it is there.

Also, developers who run f771 directly might want to specify it by hand to get the same defaults as they would running f771 via g77 or gcc However, such developers should, after linking a new f771 executable, invoke it without this option once, e.g. via ./f771 -quiet < /dev/null, to ensure that they have not introduced any internal inconsistencies (such as in the table of intrinsics) before proceeding--g77 will crash with a diagnostic if it detects an inconsistency.

-fno-silent
Print (to stderr) the names of the program units as they are compiled, in a form similar to that used by popular UNIX f77 implementations and f2c

See Options Controlling the Kind of Output, for information on more options that control the overall operation of the gcc command (and, by extension, the g77 command).


Node:Overly Convenient Options, Next:Faster Programs, Previous:Working Programs, Up:Collected Fortran Wisdom

Overly Convenient Command-line Options

These options should be used only as a quick-and-dirty way to determine how well your program will run under different compilation models without having to change the source. Some are more problematic than others, depending on how portable and maintainable you want the program to be (and, of course, whether you are allowed to change it at all is crucial).

You should not continue to use these command-line options to compile a given program, but rather should make changes to the source code:

-finit-local-zero
(This option specifies that any uninitialized local variables and arrays have default initialization to binary zeros.)

Many other compilers do this automatically, which means lots of Fortran code developed with those compilers depends on it.

It is safer (and probably would produce a faster program) to find the variables and arrays that need such initialization and provide it explicitly via DATA, so that -finit-local-zero is not needed.

Consider using -Wuninitialized (which requires -O) to find likely candidates, but do not specify -finit-local-zero or -fno-automatic, or this technique won't work.

-fno-automatic
(This option specifies that all local variables and arrays are to be treated as if they were named in SAVE statements.)

Many other compilers do this automatically, which means lots of Fortran code developed with those compilers depends on it.

The effect of this is that all non-automatic variables and arrays are made static, that is, not placed on the stack or in heap storage. This might cause a buggy program to appear to work better. If so, rather than relying on this command-line option (and hoping all compilers provide the equivalent one), add SAVE statements to some or all program unit sources, as appropriate. Consider using -Wuninitialized (which requires -O) to find likely candidates, but do not specify -finit-local-zero or -fno-automatic, or this technique won't work.

The default is -fautomatic, which tells g77 to try and put variables and arrays on the stack (or in fast registers) where possible and reasonable. This tends to make programs faster.

Note: Automatic variables and arrays are not affected by this option. These are variables and arrays that are necessarily automatic, either due to explicit statements, or due to the way they are declared. Examples include local variables and arrays not given the SAVE attribute in procedures declared RECURSIVE, and local arrays declared with non-constant bounds (automatic arrays). Currently, g77 supports only automatic arrays, not RECURSIVE procedures or other means of explicitly specifying that variables or arrays are automatic.

-fgroup-intrinsics-hide
Change the source code to use EXTERNAL for any external procedure that might be the name of an intrinsic. It is easy to find these using -fgroup-intrinsics-disable.


Node:Overview of Sources, Next:Overview of Translation Process, Up:Front End

Overview of Sources

The current directory layout includes the following:

{No value for `srcdir'}/gcc/
Non-g77 files in gcc
{No value for `srcdir'}/gcc/f/
GNU Fortran front end sources
{No value for `srcdir'}/libf2c/
libg2c configuration and g2c.h file generation
{No value for `srcdir'}/libf2c/libF77/
General support and math portion of libg2c
{No value for `srcdir'}/libf2c/libI77/
I/O portion of libg2c
{No value for `srcdir'}/libf2c/libU77/
Additional interfaces to Unix libc for libg2c

Components of note in g77 are described below.

f/ as a whole contains the source for g77, while libf2c/ contains a portion of the separate program f2c. Note that the libf2c code is not part of the program g77, just distributed with it.

f/ contains text files that document the Fortran compiler, source files for the GNU Fortran Front End (FFE), and some other stuff. The g77 compiler code is placed in f/ because it, along with its contents, is designed to be a subdirectory of a gcc source directory, gcc/, which is structured so that language-specific front ends can be "dropped in" as subdirectories. The C++ front end (g++), is an example of this--it resides in the cp/ subdirectory. Note that the C front end (also referred to as gcc) is an exception to this, as its source files reside in the gcc/ directory itself.

libf2c/ contains the run-time libraries for the f2c program, also used by g77. These libraries normally referred to collectively as libf2c. When built as part of g77, libf2c is installed under the name libg2c to avoid conflict with any existing version of libf2c, and thus is often referred to as libg2c when the g77 version is specifically being referred to.

The netlib version of libf2c/ contains two distinct libraries, libF77 and libI77, each in their own subdirectories. In g77, this distinction is not made, beyond maintaining the subdirectory structure in the source-code tree.

libf2c/ is not part of the program g77, just distributed with it. It contains files not present in the official (netlib) version of libf2c, and also contains some minor changes made from libf2c, to fix some bugs, and to facilitate automatic configuration, building, and installation of libf2c (as libg2c) for use by g77 users. See libf2c/README for more information, including licensing conditions governing distribution of programs containing code from libg2c.

libg2c, g77's version of libf2c, adds Dave Love's implementation of libU77, in the libf2c/libU77/ directory. This library is distributed under the GNU Library General Public License (LGPL)--see the file libf2c/libU77/COPYING.LIB for more information, as this license governs distribution conditions for programs containing code from this portion of the library.

Files of note in f/ and libf2c/ are described below:

f/BUGS
Lists some important bugs known to be in g77. Or use Info (or GNU Emacs Info mode) to read the "Actual Bugs" node of the g77 documentation:
info -f f/g77.info -n "Actual Bugs"

f/ChangeLog
Lists recent changes to g77 internals.
libf2c/ChangeLog
Lists recent changes to libg2c internals.
f/NEWS
Contains the per-release changes. These include the user-visible changes described in the node "Changes" in the g77 documentation, plus internal changes of import. Or use:
info -f f/g77.info -n News

f/g77.info*
The g77 documentation, in Info format, produced by building g77.

All users of g77 (not just installers) should read this, using the more command if neither the info command, nor GNU Emacs (with its Info mode), are available, or if users aren't yet accustomed to using these tools. All of these files are readable as "plain text" files, though they're easier to navigate using Info readers such as info and GNU Emacs Info mode.

If you want to explore the FFE code, which lives entirely in f/, here are a few clues. The file g77spec.c contains the g77-specific source code for the g77 command only--this just forms a variant of the gcc command, so, just as the gcc command itself does not contain the C front end, the g77 command does not contain the Fortran front end (FFE). The FFE code ends up in an executable named f771, which does the actual compiling, so it contains the FFE plus the gcc back end (GBE), the latter to do most of the optimization, and the code generation.

The file parse.c is the source file for yyparse(), which is invoked by the GBE to start the compilation process, for f771.

The file top.c contains the top-level FFE function ffe_file and it (along with top.h) define all ffe_[a-z].*, ffe[A-Z].*, and FFE_[A-Za-z].* symbols.

The file fini.c is a main() program that is used when building the FFE to generate C header and source files for recognizing keywords. The files malloc.c and malloc.h comprise a memory manager that defines all malloc_[a-z].*, malloc[A-Z].*, and MALLOC_[A-Za-z].* symbols.

All other modules named xyz are comprised of all files named xyz*.ext and define all ffexyz_[a-z].*, ffexyz[A-Z].*, and FFEXYZ_[A-Za-z].* symbols. If you understand all this, congratulations--it's easier for me to remember how it works than to type in these regular expressions. But it does make it easy to find where a symbol is defined. For example, the symbol ffexyz_set_something would be defined in xyz.h and implemented there (if it's a macro) or in xyz.c.

The "porting" files of note currently are:

proj.c
proj.h
This defines the "language" used by all the other source files, the language being Standard C plus some useful things like ARRAY_SIZE and such.
target.c
target.h
These describe the target machine in terms of what data types are supported, how they are denoted (to what C type does an INTEGER*8 map, for example), how to convert between them, and so on. Over time, versions of g77 rely less on this file and more on run-time configuration based on GBE info in com.c.
com.c
com.h
These are the primary interface to the GBE.
ste.c
ste.h
This contains code for implementing recognized executable statements in the GBE.
src.c
src.h
These contain information on the format(s) of source files (such as whether they are never to be processed as case-insensitive with regard to Fortran keywords).

If you want to debug the f771 executable, for example if it crashes, note that the global variables lineno and input_filename are usually set to reflect the current line being read by the lexer during the first-pass analysis of a program unit and to reflect the current line being processed during the second-pass compilation of a program unit.

If an invocation of the function ffestd_exec_end is on the stack, the compiler is in the second pass, otherwise it is in the first.

(This information might help you reduce a test case and/or work around a bug in g77 until a fix is available.)


Node:Overview of Translation Process, Next:Philosophy of Code Generation, Previous:Overview of Sources, Up:Front End

Overview of Translation Process

The order of phases translating source code to the form accepted by the GBE is:

  1. Stripping punched-card sources (g77stripcard.c)
  2. Lexing (lex.c)
  3. Stand-alone statement identification (sta.c)
  4. INCLUDE handling (sti.c)
  5. Order-dependent statement identification (stq.c)
  6. Parsing (stb.c and expr.c)
  7. Constructing (stc.c)
  8. Collecting (std.c)
  9. Expanding (ste.c)

To get a rough idea of how a particularly twisted Fortran statement gets treated by the passes, consider:

      FORMAT(I2 4H)=(J/
     &   I3)

The job of lex.c is to know enough about Fortran syntax rules to break the statement up into distinct lexemes without requiring any feedback from subsequent phases:

`FORMAT'
`('
`I24H'
`)'
`='
`('
`J'
`/'
`I3'
`)'

The job of sta.c is to figure out the kind of statement, or, at least, statement form, that sequence of lexemes represent.

The sooner it can do this (in terms of using the smallest number of lexemes, starting with the first for each statement), the better, because that leaves diagnostics for problems beyond the recognition of the statement form to subsequent phases, which can usually better describe the nature of the problem.

In this case, the = at "level zero" (not nested within parentheses) tells sta.c that this is an assignment-form, not FORMAT, statement.

An assignment-form statement might be a statement-function definition or an executable assignment statement.

To make that determination, sta.c looks at the first two lexemes.

Since the second lexeme is (, the first must represent an array for this to be an assignment statement, else it's a statement function.

Either way, sta.c hands off the statement to stq.c (via sti.c, which expands INCLUDE files). stq.c figures out what a statement that is, on its own, ambiguous, must actually be based on the context established by previous statements.

So, stq.c watches the statement stream for executable statements, END statements, and so on, so it knows whether A(B)=C is (intended as) a statement-function definition or an assignment statement.

After establishing the context-aware statement info, stq.c passes the original sample statement on to stb.c (either its statement-function parser or its assignment-statement parser).

stb.c forms a statement-specific record containing the pertinent information. That information includes a source expression and, for an assignment statement, a destination expression. Expressions are parsed by expr.c.

This record is passed to stc.c, which copes with the implications of the statement within the context established by previous statements.

For example, if it's the first statement in the file or after an END statement, stc.c recognizes that, first of all, a main program unit is now being lexed (and tells that to std.c before telling it about the current statement).

stc.c attaches whatever information it can, usually derived from the context established by the preceding statements, and passes the information to std.c.

std.c saves this information away, since the GBE cannot cope with information that might be incomplete at this stage.

For example, I3 might later be determined to be an argument to an alternate ENTRY point.

When std.c is told about the end of an external (top-level) program unit, it passes all the information it has saved away on statements in that program unit to ste.c.

ste.c "expands" each statement, in sequence, by constructing the appropriate GBE information and calling the appropriate GBE routines.

Details on the transformational phases follow. Keep in mind that Fortran numbering is used, so the first character on a line is column 1, decimal numbering is used, and so on.

  • g77stripcard:
  • lex.c:
  • sta.c:
  • sti.c:
  • stq.c:
  • stb.c:
  • expr.c:
  • stc.c:
  • std.c:
  • ste.c:

  • Gotchas (Transforming):
  • TBD (Transforming):


Node:Pack Intrinsic, Next:PError Intrinsic, Previous:Or Intrinsic, Up:Table of Intrinsic Functions

Pack Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Pack to use this name for an external procedure.


Node:Pedantic Compilation, Next:Distensions, Previous:Fortran 90, Up:Other Dialects

Pedantic Compilation

The -fpedantic command-line option specifies that g77 is to warn about code that is not standard-conforming. This is useful for finding some extensions g77 accepts that other compilers might not accept. (Note that the -pedantic and -pedantic-errors options always imply -fpedantic.)

With -fno-f90 in force, ANSI FORTRAN 77 is used as the standard for conforming code. With -ff90 in force, Fortran 90 is used.

The constructs for which g77 issues diagnostics when -fpedantic and -fno-f90 are in force are:

  • Automatic arrays, as in
    SUBROUTINE X(N)
REAL A(N)
...

    where A is not listed in any ENTRY statement, and thus is not a dummy argument.

  • The commas in READ (5), I and WRITE (10), J.

    These commas are disallowed by FORTRAN 77, but, while strictly superfluous, are syntactically elegant, especially given that commas are required in statements such as READ 99, I and PRINT *, J. Many compilers permit the superfluous commas for this reason.

  • DOUBLE COMPLEX, either explicitly or implicitly.

    An explicit use of this type is via a DOUBLE COMPLEX or IMPLICIT DOUBLE COMPLEX statement, for examples.

    An example of an implicit use is the expression C*D, where C is COMPLEX(KIND=1) and D is DOUBLE PRECISION. This expression is prohibited by ANSI FORTRAN 77 because the rules of promotion would suggest that it produce a DOUBLE COMPLEX result--a type not provided for by that standard.

  • Automatic conversion of numeric expressions to INTEGER(KIND=1) in contexts such as:
    • Array-reference indexes.
    • Alternate-return values.
    • Computed GOTO.
    • FORMAT run-time expressions (not yet supported).
    • Dimension lists in specification statements.
    • Numbers for I/O statements (such as READ (UNIT=3.2), I)
    • Sizes of CHARACTER entities in specification statements.
    • Kind types in specification entities (a Fortran 90 feature).
    • Initial, terminal, and incrementation parameters for implied-DO constructs in DATA statements.
  • Automatic conversion of LOGICAL expressions to INTEGER in contexts such as arithmetic IF (where COMPLEX expressions are disallowed anyway).
  • Zero-size array dimensions, as in:
    INTEGER I(10,20,4:2)
  • Zero-length CHARACTER entities, as in:
    PRINT *, ''
  • Substring operators applied to character constants and named constants, as in:
    PRINT *, 'hello'(3:5)
  • Null arguments passed to statement function, as in:
    PRINT *, FOO(,3)
  • Disagreement among program units regarding whether a given COMMON area is SAVEd (for targets where program units in a single source file are "glued" together as they typically are for UNIX development environments).
  • Disagreement among program units regarding the size of a named COMMON block.
  • Specification statements following first DATA statement.

    (In the GNU Fortran language, DATA I/1/ may be followed by INTEGER J, but not INTEGER I. The -fpedantic option disallows both of these.)

  • Semicolon as statement separator, as in:
    CALL FOO; CALL BAR
  • Use of & in column 1 of fixed-form source (to indicate continuation).
  • Use of CHARACTER constants to initialize numeric entities, and vice versa.
  • Expressions having two arithmetic operators in a row, such as X*-Y.

If -fpedantic is specified along with -ff90, the following constructs result in diagnostics:

  • Use of semicolon as a statement separator on a line that has an INCLUDE directive.


Node:PError Intrinsic, Next:Precision Intrinsic, Previous:Pack Intrinsic, Up:Table of Intrinsic Functions

PError Intrinsic

CALL PError(String)

String: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Prints (on the C stderr stream) a newline-terminated error message corresponding to the last system error. This is prefixed by String, a colon and a space. See perror(3).


Node:Philosophy of Code Generation, Next:Two-pass Design, Previous:Overview of Translation Process, Up:Front End

Philosophy of Code Generation

Don't poke the bear.

The g77 front end generates code via the gcc back end.

The gcc back end (GBE) is a large, complex labyrinth of intricate code written in a combination of the C language and specialized languages internal to gcc.

While the code that implements the GBE is written in a combination of languages, the GBE itself is, to the front end for a language like Fortran, best viewed as a compiler that compiles its own, unique, language.

The GBE's "source", then, is written in this language, which consists primarily of a combination of calls to GBE functions and tree nodes (which are, themselves, created by calling GBE functions).

So, the g77 generates code by, in effect, translating the Fortran code it reads into a form "written" in the "language" of the gcc back end.

This language will heretofore be referred to as GBEL, for GNU Back End Language.

GBEL is an evolving language, not fully specified in any published form as of this writing. It offers many facilities, but its "core" facilities are those that corresponding most directly to those needed to support gcc (compiling code written in GNU C).

The g77 Fortran Front End (FFE) is designed and implemented to navigate the currents and eddies of ongoing GBEL and gcc development while also delivering on the potential of an integrated FFE (as compared to using a converter like f2c and feeding the output into gcc).

Goals of the FFE's code-generation strategy include:

  • High likelihood of generation of correct code, or, failing that, producing a fatal diagnostic or crashing.
  • Generation of highly optimized code, as directed by the user via GBE-specific (versus g77-specific) constructs, such as command-line options.
  • Fast overall (FFE plus GBE) compilation.
  • Preservation of source-level debugging information.

The strategies historically, and currently, used by the FFE to achieve these goals include:

  • Use of GBEL constructs that most faithfully encapsulate the semantics of Fortran.
  • Avoidance of GBEL constructs that are so rarely used, or limited to use in specialized situations not related to Fortran, that their reliability and performance has not yet been established as sufficient for use by the FFE.
  • Flexible design, to readily accommodate changes to specific code-generation strategies, perhaps governed by command-line options.

"Don't poke the bear" somewhat summarizes the above strategies. The GBE is the bear. The FFE is designed and implemented to avoid poking it in ways that are likely to just annoy it. The FFE usually either tackles it head-on, or avoids treating it in ways dissimilar to how the gcc front end treats it.

For example, the FFE uses the native array facility in the back end instead of the lower-level pointer-arithmetic facility used by gcc when compiling f2c output). Theoretically, this presents more opportunities for optimization, faster compile times, and the production of more faithful debugging information. These benefits were not, however, immediately realized, mainly because gcc itself makes little or no use of the native array facility.

Complex arithmetic is a case study of the evolution of this strategy. When originally implemented, the GBEL had just evolved its own native complex-arithmetic facility, so the FFE took advantage of that.

When porting g77 to 64-bit systems, it was discovered that the GBE didn't really implement its native complex-arithmetic facility properly.

The short-term solution was to rewrite the FFE to instead use the lower-level facilities that'd be used by gcc-compiled code (assuming that code, itself, didn't use the native complex type provided, as an extension, by gcc), since these were known to work, and, in any case, if shown to not work, would likely be rapidly fixed (since they'd likely not work for vanilla C code in similar circumstances).

However, the rewrite accommodated the original, native approach as well by offering a command-line option to select it over the emulated approach. This allowed users, and especially GBE maintainers, to try out fixes to complex-arithmetic support in the GBE while g77 continued to default to compiling more code correctly, albeit producing (typically) slower executables.

As of April 1999, it appeared that the last few bugs in the GBE's support of its native complex-arithmetic facility were worked out. The FFE was changed back to default to using that native facility, leaving emulation as an option.

Later during the release cycle (which was called EGCS 1.2, but soon became GCC 2.95), bugs in the native facility were found. Reactions among various people included "the last thing we should do is change the default back", "we must change the default back", and "let's figure out whether we can narrow down the bugs to few enough cases to allow the now-months-long-tested default to remain the same". The latter viewpoint won that particular time. The bugs exposed other concerns regarding ABI compliance when the ABI specified treatment of complex data as different from treatment of what Fortran and GNU C consider the equivalent aggregation (structure) of real (or float) pairs.

Other Fortran constructs--arrays, character strings, complex division, COMMON and EQUIVALENCE aggregates, and so on--involve issues similar to those pertaining to complex arithmetic.

So, it is possible that the history of how the FFE handled complex arithmetic will be repeated, probably in modified form (and hopefully over shorter timeframes), for some of these other facilities.


Node:POINTER Statements, Next:Sensible Non-standard Constructs, Previous:Array Bounds Expressions, Up:Missing Features

POINTER Statements

g77 doesn't support pointers or allocatable objects (other than automatic arrays). This set of features is probably considered just behind intrinsics in PARAMETER statements on the list of large, important things to add to g77.

In the meantime, consider using the INTEGER(KIND=7) declaration to specify that a variable must be able to hold a pointer. This construct is not portable to other non-GNU compilers, but it is portable to all machines GNU Fortran supports when g77 is used.

See Functions and Subroutines, for information on %VAL(), %REF(), and %DESCR() constructs, which are useful for passing pointers to procedures written in languages other than Fortran.


Node:Popular Non-standard Types, Next:Full Support for Compiler Types, Previous:RECURSIVE Keyword, Up:Missing Features

Popular Non-standard Types

g77 doesn't fully support INTEGER*2, LOGICAL*1, and similar. In the meantime, version 0.5.18 provides rudimentary support for them.


Node:Portable Unformatted Files, Next:Better List-directed I/O, Previous:Uninitialized Variables at Run Time, Up:Missing Features

Portable Unformatted Files

g77 has no facility for exchanging unformatted files with systems using different number formats--even differing only in endianness (byte order)--or written by other compilers. Some compilers provide facilities at least for doing byte-swapping during unformatted I/O.

It is unrealistic to expect to cope with exchanging unformatted files with arbitrary other compiler runtimes, but the g77 runtime should at least be able to read files written by g77 on systems with different number formats, particularly if they differ only in byte order.

In case you do need to write a program to translate to or from g77 (libf2c) unformatted files, they are written as follows:

Sequential
Unformatted sequential records consist of

  1. A number giving the length of the record contents;
  2. the length of record contents again (for backspace).

The record length is of C type long; this means that it is 8 bytes on 64-bit systems such as Alpha GNU/Linux and 4 bytes on other systems, such as x86 GNU/Linux. Consequently such files cannot be exchanged between 64-bit and 32-bit systems, even with the same basic number format.

Direct access
Unformatted direct access files form a byte stream of length records*recl bytes, where records is the maximum record number (REC=records) written and recl is the record length in bytes specified in the OPEN statement (RECL=recl). Data appear in the records as determined by the relevant WRITE statement. Dummy records with arbitrary contents appear in the file in place of records which haven't been written.

Thus for exchanging a sequential or direct access unformatted file between big- and little-endian 32-bit systems using IEEE 754 floating point it would be sufficient to reverse the bytes in consecutive words in the file if, and only if, only REAL*4, COMPLEX, INTEGER*4 and/or LOGICAL*4 data have been written to it by g77.

If necessary, it is possible to do byte-oriented i/o with g77's FGETC and FPUTC intrinsics. Byte-swapping can be done in Fortran by equivalencing larger sized variables to an INTEGER*1 array or a set of scalars.

If you need to exchange binary data between arbitrary system and compiler variations, we recommend using a portable binary format with Fortran bindings, such as NCSA's HDF (http://hdf.ncsa.uiuc.edu/) or PACT's PDB1 (http://www.llnl.gov/def_sci/pact/pact_homepage.html). (Unlike, say, CDF or XDR, HDF-like systems write in the native number formats and only incur overhead when they are read on a system with a different format.) A future g77 runtime library should use such techniques.

Footnotes

  1. No, not that one.


Node:POSIX Standard, Next:Floating-point Exception Handling, Previous:Really Ugly Character Assignments, Up:Missing Features

POSIX Standard

g77 should support the POSIX standard for Fortran.


Node:Precision Intrinsic, Next:Present Intrinsic, Previous:PError Intrinsic, Up:Table of Intrinsic Functions

Precision Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Precision to use this name for an external procedure.


Node:Prefer Automatic Uninitialized Variables, Next:Avoid f2c Compatibility, Previous:Aligned Data, Up:Faster Programs

Prefer Automatic Uninitialized Variables

If you're using -fno-automatic already, you probably should change your code to allow compilation with -fautomatic (the default), to allow the program to run faster.

Similarly, you should be able to use -fno-init-local-zero (the default) instead of -finit-local-zero. This is because it is rare that every variable affected by these options in a given program actually needs to be so affected.

For example, -fno-automatic, which effectively SAVEs every local non-automatic variable and array, affects even things like DO iteration variables, which rarely need to be SAVEd, and this often reduces run-time performances. Similarly, -fno-init-local-zero forces such variables to be initialized to zero--when SAVEd (such as when -fno-automatic), this by itself generally affects only startup time for a program, but when not SAVEd, it can slow down the procedure every time it is called.

See Overly Convenient Command-Line Options, for information on the -fno-automatic and -finit-local-zero options and how to convert their use into selective changes in your own code.


Node:Preprocessor Options, Next:Directory Options, Previous:Optimize Options, Up:Invoking G77

Options Controlling the Preprocessor

These options control the C preprocessor, which is run on each C source file before actual compilation.

See Options Controlling the Preprocessor, for information on C preprocessor options.

Some of these options also affect how g77 processes the INCLUDE directive. Since this directive is processed even when preprocessing is not requested, it is not described in this section. See Options for Directory Search, for information on how g77 processes the INCLUDE directive.

However, the INCLUDE directive does not apply preprocessing to the contents of the included file itself.

Therefore, any file that contains preprocessor directives (such as #include, #define, and #if) must be included via the #include directive, not via the INCLUDE directive. Therefore, any file containing preprocessor directives, if included, is necessarily included by a file that itself contains preprocessor directives.


Node:Present Intrinsic, Next:Product Intrinsic, Previous:Precision Intrinsic, Up:Table of Intrinsic Functions

Present Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Present to use this name for an external procedure.


Node:Procedures, Next:Functions, Previous:Main Program Unit, Up:Debugging and Interfacing

Procedures (SUBROUTINE and FUNCTION)

Currently, g77 passes arguments via reference--specifically, by passing a pointer to the location in memory of a variable, array, array element, a temporary location that holds the result of evaluating an expression, or a temporary or permanent location that holds the value of a constant.

Procedures that accept CHARACTER arguments are implemented by g77 so that each CHARACTER argument has two actual arguments.

The first argument occupies the expected position in the argument list and has the user-specified name. This argument is a pointer to an array of characters, passed by the caller.

The second argument is appended to the end of the user-specified calling sequence and is named __g77_length_x, where x is the user-specified name. This argument is of the C type ftnlen (see gcc/libf2c/g2c.h.in for information on that type) and is the number of characters the caller has allocated in the array pointed to by the first argument.

A procedure will ignore the length argument if X is not declared CHARACTER*(*), because for other declarations, it knows the length. Not all callers necessarily "know" this, however, which is why they all pass the extra argument.

The contents of the CHARACTER argument are specified by the address passed in the first argument (named after it). The procedure can read or write these contents as appropriate.

When more than one CHARACTER argument is present in the argument list, the length arguments are appended in the order the original arguments appear. So CALL FOO('HI','THERE') is implemented in C as foo("hi","there",2,5);, ignoring the fact that g77 does not provide the trailing null bytes on the constant strings (f2c does provide them, but they are unnecessary in a Fortran environment, and you should not expect them to be there).

Note that the above information applies to CHARACTER variables and arrays only. It does not apply to external CHARACTER functions or to intrinsic CHARACTER functions. That is, no second length argument is passed to FOO in this case:

CHARACTER X
EXTERNAL X
CALL FOO(X)

Nor does FOO expect such an argument in this case:

SUBROUTINE FOO(X)
CHARACTER X
EXTERNAL X

Because of this implementation detail, if a program has a bug such that there is disagreement as to whether an argument is a procedure, and the type of the argument is CHARACTER, subtle symptoms might appear.


Node:Product Intrinsic, Next:Radix Intrinsic, Previous:Present Intrinsic, Up:Table of Intrinsic Functions

Product Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Product to use this name for an external procedure.


Node:Program Speed, Next:Ease of Debugging, Previous:Compiler Speed, Up:Advantages Over f2c

Program Speed

g77 has the potential to better optimize code than f2c, even when gcc is used to compile the output of f2c, because f2c must necessarily translate Fortran into a somewhat lower-level language (C) that cannot preserve all the information that is potentially useful for optimization, while g77 can gather, preserve, and transmit that information directly to the GBE.

For example, g77 implements ASSIGN and assigned GOTO using direct assignment of pointers to labels and direct jumps to labels, whereas f2c maps the assigned labels to integer values and then uses a C switch statement to encode the assigned GOTO statements.

However, as is typical, theory and reality don't quite match, at least not in all cases, so it is still the case that f2c plus gcc can generate code that is faster than g77.

Version 0.5.18 of g77 offered default settings and options, via patches to the gcc back end, that allow for better program speed, though some of these improvements also affected the performance of programs translated by f2c and then compiled by g77's version of gcc.

Version 0.5.20 of g77 offers further performance improvements, at least one of which (alias analysis) is not generally applicable to f2c (though f2c could presumably be changed to also take advantage of this new capability of the gcc back end, assuming this is made available in an upcoming release of gcc).


Node:Projects, Next:Front End, Previous:Adding Options, Up:Top

Projects

If you want to contribute to g77 by doing research, design, specification, documentation, coding, or testing, the following information should give you some ideas. More relevant information might be available from ftp://alpha.gnu.org/gnu/g77/projects/.

  • Efficiency: Make g77 itself compile code faster.
  • Better Optimization: Teach g77 to generate faster code.
  • Simplify Porting: Make g77 easier to configure, build, and install.
  • More Extensions: Features many users won't know to ask for.
  • Machine Model: g77 should better leverage gcc.
  • Internals Documentation: Make maintenance easier.
  • Internals Improvements: Make internals more robust.
  • Better Diagnostics: Make using g77 on new code easier.


Node:Q Edit Descriptor, Next:Old-style PARAMETER Statements, Previous:Explicit Assembler Code, Up:Missing Features

Q Edit Descriptor

The Q edit descriptor in FORMATs isn't supported. (This is meant to get the number of characters remaining in an input record.) Supporting this requires a significant redesign or replacement of libg2c.

A workaround might be using internal I/O or the stream-based intrinsics. See FGetC Intrinsic (subroutine).


Node:QAbs Intrinsic, Next:QACos Intrinsic, Previous:Link Intrinsic (function), Up:Other Intrinsics

QAbs Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QAbs to use this name for an external procedure.


Node:QACos Intrinsic, Next:QACosD Intrinsic, Previous:QAbs Intrinsic, Up:Other Intrinsics

QACos Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QACos to use this name for an external procedure.


Node:QACosD Intrinsic, Next:QASin Intrinsic, Previous:QACos Intrinsic, Up:Other Intrinsics

QACosD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QACosD to use this name for an external procedure.


Node:QASin Intrinsic, Next:QASinD Intrinsic, Previous:QACosD Intrinsic, Up:Other Intrinsics

QASin Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QASin to use this name for an external procedure.


Node:QASinD Intrinsic, Next:QATan Intrinsic, Previous:QASin Intrinsic, Up:Other Intrinsics

QASinD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QASinD to use this name for an external procedure.


Node:QATan Intrinsic, Next:QATan2 Intrinsic, Previous:QASinD Intrinsic, Up:Other Intrinsics

QATan Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QATan to use this name for an external procedure.


Node:QATan2 Intrinsic, Next:QATan2D Intrinsic, Previous:QATan Intrinsic, Up:Other Intrinsics

QATan2 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QATan2 to use this name for an external procedure.


Node:QATan2D Intrinsic, Next:QATanD Intrinsic, Previous:QATan2 Intrinsic, Up:Other Intrinsics

QATan2D Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QATan2D to use this name for an external procedure.


Node:QATanD Intrinsic, Next:QCos Intrinsic, Previous:QATan2D Intrinsic, Up:Other Intrinsics

QATanD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QATanD to use this name for an external procedure.


Node:QCos Intrinsic, Next:QCosD Intrinsic, Previous:QATanD Intrinsic, Up:Other Intrinsics

QCos Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QCos to use this name for an external procedure.


Node:QCosD Intrinsic, Next:QCosH Intrinsic, Previous:QCos Intrinsic, Up:Other Intrinsics

QCosD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QCosD to use this name for an external procedure.


Node:QCosH Intrinsic, Next:QDiM Intrinsic, Previous:QCosD Intrinsic, Up:Other Intrinsics

QCosH Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QCosH to use this name for an external procedure.


Node:QDiM Intrinsic, Next:QExp Intrinsic, Previous:QCosH Intrinsic, Up:Other Intrinsics

QDiM Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QDiM to use this name for an external procedure.


Node:QExp Intrinsic, Next:QExt Intrinsic, Previous:QDiM Intrinsic, Up:Other Intrinsics

QExp Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QExp to use this name for an external procedure.


Node:QExt Intrinsic, Next:QExtD Intrinsic, Previous:QExp Intrinsic, Up:Other Intrinsics

QExt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QExt to use this name for an external procedure.


Node:QExtD Intrinsic, Next:QFloat Intrinsic, Previous:QExt Intrinsic, Up:Other Intrinsics

QExtD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QExtD to use this name for an external procedure.


Node:QFloat Intrinsic, Next:QInt Intrinsic, Previous:QExtD Intrinsic, Up:Other Intrinsics

QFloat Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QFloat to use this name for an external procedure.


Node:QInt Intrinsic, Next:QLog Intrinsic, Previous:QFloat Intrinsic, Up:Other Intrinsics

QInt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QInt to use this name for an external procedure.


Node:QLog Intrinsic, Next:QLog10 Intrinsic, Previous:QInt Intrinsic, Up:Other Intrinsics

QLog Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QLog to use this name for an external procedure.


Node:QLog10 Intrinsic, Next:QMax1 Intrinsic, Previous:QLog Intrinsic, Up:Other Intrinsics

QLog10 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QLog10 to use this name for an external procedure.


Node:QMax1 Intrinsic, Next:QMin1 Intrinsic, Previous:QLog10 Intrinsic, Up:Other Intrinsics

QMax1 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QMax1 to use this name for an external procedure.


Node:QMin1 Intrinsic, Next:QMod Intrinsic, Previous:QMax1 Intrinsic, Up:Other Intrinsics

QMin1 Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QMin1 to use this name for an external procedure.


Node:QMod Intrinsic, Next:QNInt Intrinsic, Previous:QMin1 Intrinsic, Up:Other Intrinsics

QMod Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QMod to use this name for an external procedure.


Node:QNInt Intrinsic, Next:QSin Intrinsic, Previous:QMod Intrinsic, Up:Other Intrinsics

QNInt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QNInt to use this name for an external procedure.


Node:QSin Intrinsic, Next:QSinD Intrinsic, Previous:QNInt Intrinsic, Up:Other Intrinsics

QSin Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QSin to use this name for an external procedure.


Node:QSinD Intrinsic, Next:QSinH Intrinsic, Previous:QSin Intrinsic, Up:Other Intrinsics

QSinD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QSinD to use this name for an external procedure.


Node:QSinH Intrinsic, Next:QSqRt Intrinsic, Previous:QSinD Intrinsic, Up:Other Intrinsics

QSinH Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QSinH to use this name for an external procedure.


Node:QSqRt Intrinsic, Next:QTan Intrinsic, Previous:QSinH Intrinsic, Up:Other Intrinsics

QSqRt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QSqRt to use this name for an external procedure.


Node:QTan Intrinsic, Next:QTanD Intrinsic, Previous:QSqRt Intrinsic, Up:Other Intrinsics

QTan Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QTan to use this name for an external procedure.


Node:QTanD Intrinsic, Next:QTanH Intrinsic, Previous:QTan Intrinsic, Up:Other Intrinsics

QTanD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QTanD to use this name for an external procedure.


Node:QTanH Intrinsic, Next:Rename Intrinsic (function), Previous:QTanD Intrinsic, Up:Other Intrinsics

QTanH Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL QTanH to use this name for an external procedure.


Node:Radix Intrinsic, Next:Rand Intrinsic, Previous:Product Intrinsic, Up:Table of Intrinsic Functions

Radix Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Radix to use this name for an external procedure.


Node:Rand Intrinsic, Next:Random_Number Intrinsic, Previous:Radix Intrinsic, Up:Table of Intrinsic Functions

Rand Intrinsic

Rand(Flag)

Rand: REAL(KIND=1) function.

Flag: INTEGER; OPTIONAL; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns a uniform quasi-random number between 0 and 1. If Flag is 0, the next number in sequence is returned; if Flag is 1, the generator is restarted by calling srand(0); if Flag has any other value, it is used as a new seed with srand.

See SRand Intrinsic.

Note: As typically implemented (by the routine of the same name in the C library), this random number generator is a very poor one, though the BSD and GNU libraries provide a much better implementation than the `traditional' one. On a different system you almost certainly want to use something better.


Node:Random_Number Intrinsic, Next:Random_Seed Intrinsic, Previous:Rand Intrinsic, Up:Table of Intrinsic Functions

Random_Number Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Random_Number to use this name for an external procedure.


Node:Random_Seed Intrinsic, Next:Range Intrinsic, Previous:Random_Number Intrinsic, Up:Table of Intrinsic Functions

Random_Seed Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Random_Seed to use this name for an external procedure.


Node:Range Intrinsic, Next:Real Intrinsic, Previous:Random_Seed Intrinsic, Up:Table of Intrinsic Functions

Range Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Range to use this name for an external procedure.


Node:REAL() and AIMAG() of Complex, Next:CMPLX() of DOUBLE PRECISION, Previous:Generics and Specifics, Up:Functions and Subroutines

REAL() and AIMAG() of Complex

The GNU Fortran language disallows REAL(expr) and AIMAG(expr), where expr is any COMPLEX type other than COMPLEX(KIND=1), except when they are used in the following way:

REAL(REAL(expr))
REAL(AIMAG(expr))

The above forms explicitly specify that the desired effect is to convert the real or imaginary part of expr, which might be some REAL type other than REAL(KIND=1), to type REAL(KIND=1), and have that serve as the value of the expression.

The GNU Fortran language offers clearly named intrinsics to extract the real and imaginary parts of a complex entity without any conversion:

REALPART(expr)
IMAGPART(expr)

To express the above using typical extended FORTRAN 77, use the following constructs (when expr is COMPLEX(KIND=2)):

DBLE(expr)
DIMAG(expr)

The FORTRAN 77 language offers no way to explicitly specify the real and imaginary parts of a complex expression of arbitrary type, apparently as a result of requiring support for only one COMPLEX type (COMPLEX(KIND=1)). The concepts of converting an expression to type REAL(KIND=1) and of extracting the real part of a complex expression were thus "smooshed" by FORTRAN 77 into a single intrinsic, since they happened to have the exact same effect in that language (due to having only one COMPLEX type).

Note: When -ff90 is in effect, g77 treats REAL(expr), where expr is of type COMPLEX, as REALPART(expr), whereas with -fugly-complex -fno-f90 in effect, it is treated as REAL(REALPART(expr)).

See Ugly Complex Part Extraction, for more information.


Node:Real Intrinsic, Next:RealPart Intrinsic, Previous:Range Intrinsic, Up:Table of Intrinsic Functions

Real Intrinsic

Real(A)

Real: REAL function.
The exact type is REAL(KIND=1) when argument A is
any type other than COMPLEX, or when it is COMPLEX(KIND=1).
When A is any COMPLEX type other than COMPLEX(KIND=1),
this intrinsic is valid only when used as the argument to
REAL(), as explained below.

A: INTEGER, REAL, or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Converts A to REAL(KIND=1).

Use of REAL() with a COMPLEX argument (other than COMPLEX(KIND=1)) is restricted to the following case:

REAL(REAL(A))

This expression converts the real part of A to REAL(KIND=1).

See RealPart Intrinsic, for information on a GNU Fortran intrinsic that extracts the real part of an arbitrary COMPLEX value.

See REAL() and AIMAG() of Complex, for more information.


Node:Really Ugly Character Assignments, Next:POSIX Standard, Previous:Bit Operations on Floating-point Data, Up:Missing Features

Really Ugly Character Assignments

An option such as -fugly-char should be provided to allow

REAL*8 A1
DATA A1 / '12345678' /

and:

REAL*8 A1
A1 = 'ABCDEFGH'


Node:RealPart Intrinsic, Next:Rename Intrinsic (subroutine), Previous:Real Intrinsic, Up:Table of Intrinsic Functions

RealPart Intrinsic

RealPart(Z)

RealPart: REAL function, the KIND= value of the type being that of argument Z.

Z: COMPLEX; scalar; INTENT(IN).

Intrinsic groups: gnu.

Description:

The real part of Z is returned, without conversion.

Note: The way to do this in standard Fortran 90 is REAL(Z). However, when, for example, Z is COMPLEX(KIND=2), REAL(Z) means something different for some compilers that are not true Fortran 90 compilers but offer some extensions standardized by Fortran 90 (such as the DOUBLE COMPLEX type, also known as COMPLEX(KIND=2)).

The advantage of REALPART() is that, while not necessarily more or less portable than REAL(), it is more likely to cause a compiler that doesn't support it to produce a diagnostic than generate incorrect code.

See REAL() and AIMAG() of Complex, for more information.


Node:RECURSIVE Keyword, Next:Popular Non-standard Types, Previous:SELECT CASE on CHARACTER Type, Up:Missing Features

RECURSIVE Keyword

g77 doesn't support the RECURSIVE keyword that F90 compilers do. Nor does it provide any means for compiling procedures designed to do recursion.

All recursive code can be rewritten to not use recursion, but the result is not pretty.


Node:Rename Intrinsic (function), Next:Secnds Intrinsic, Previous:QTanH Intrinsic, Up:Other Intrinsics

Rename Intrinsic (function)

Rename(Path1, Path2)

Rename: INTEGER(KIND=1) function.

Path1: CHARACTER; scalar; INTENT(IN).

Path2: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Renames the file Path1 to Path2. A null character (CHAR(0)) marks the end of the names in Path1 and Path2--otherwise, trailing blanks in Path1 and Path2 are ignored. See rename(2). Returns 0 on success or a non-zero error code.

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See Rename Intrinsic (subroutine).


Node:Rename Intrinsic (subroutine), Next:Repeat Intrinsic, Previous:RealPart Intrinsic, Up:Table of Intrinsic Functions

Rename Intrinsic (subroutine)

CALL Rename(Path1, Path2, Status)

Path1: CHARACTER; scalar; INTENT(IN).

Path2: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Renames the file Path1 to Path2. A null character (CHAR(0)) marks the end of the names in Path1 and Path2--otherwise, trailing blanks in Path1 and Path2 are ignored. See rename(2). If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See Rename Intrinsic (function).


Node:Repeat Intrinsic, Next:Reshape Intrinsic, Previous:Rename Intrinsic (subroutine), Up:Table of Intrinsic Functions

Repeat Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Repeat to use this name for an external procedure.


Node:Reshape Intrinsic, Next:RRSpacing Intrinsic, Previous:Repeat Intrinsic, Up:Table of Intrinsic Functions

Reshape Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Reshape to use this name for an external procedure.


Node:RRSpacing Intrinsic, Next:RShift Intrinsic, Previous:Reshape Intrinsic, Up:Table of Intrinsic Functions

RRSpacing Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL RRSpacing to use this name for an external procedure.


Node:RShift Intrinsic, Next:Scale Intrinsic, Previous:RRSpacing Intrinsic, Up:Table of Intrinsic Functions

RShift Intrinsic

RShift(I, Shift)

RShift: INTEGER function, the KIND= value of the type being that of argument I.

I: INTEGER; scalar; INTENT(IN).

Shift: INTEGER; scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Returns I shifted to the right Shift bits.

Although similar to the expression I/(2**Shift), there are important differences. For example, the sign of the result is undefined.

Currently this intrinsic is defined assuming the underlying representation of I is as a two's-complement integer. It is unclear at this point whether that definition will apply when a different representation is involved.

See RShift Intrinsic, for the inverse of this function.

See IShft Intrinsic, for information on a more widely available right-shifting intrinsic that is also more precisely defined.


Node:Run-time Environment Limits, Next:Compiler Types, Previous:Compiler Limits, Up:Compiler

Run-time Environment Limits

As a portable Fortran implementation, g77 offers its users direct access to, and otherwise depends upon, the underlying facilities of the system used to build g77, the system on which g77 itself is used to compile programs, and the system on which the g77-compiled program is actually run. (For most users, the three systems are of the same type--combination of operating environment and hardware--often the same physical system.)

The run-time environment for a particular system inevitably imposes some limits on a program's use of various system facilities. These limits vary from system to system.

Even when such limits might be well beyond the possibility of being encountered on a particular system, the g77 run-time environment has certain built-in limits, usually, but not always, stemming from intrinsics with inherently limited interfaces.

Currently, the g77 run-time environment does not generally offer a less-limiting environment by augmenting the underlying system's own environment.

Therefore, code written in the GNU Fortran language, while syntactically and semantically portable, might nevertheless make non-portable assumptions about the run-time environment--assumptions that prove to be false for some particular environments.

The GNU Fortran language, the g77 compiler and run-time environment, and the g77 documentation do not yet offer comprehensive portable work-arounds for such limits, though programmers should be able to find their own in specific instances.

Not all of the limitations are described in this document. Some of the known limitations include:

  • Timer Wraparounds:
  • Year 2000 (Y2K) Problems:
  • Array Size:
  • Character-variable Length:
  • Year 10000 (Y10K) Problems:


Node:Run-time Library Errors, Previous:Assigned Statement Labels, Up:Debugging and Interfacing

Run-time Library Errors

The libg2c library currently has the following table to relate error code numbers, returned in IOSTAT= variables, to messages. This information should, in future versions of this document, be expanded upon to include detailed descriptions of each message.

In line with good coding practices, any of the numbers in the list below should not be directly written into Fortran code you write. Instead, make a separate INCLUDE file that defines PARAMETER names for them, and use those in your code, so you can more easily change the actual numbers in the future.

The information below is culled from the definition of F_err in f/runtime/libI77/err.c in the g77 source tree.

100: "error in format"
101: "illegal unit number"
102: "formatted io not allowed"
103: "unformatted io not allowed"
104: "direct io not allowed"
105: "sequential io not allowed"
106: "can't backspace file"
107: "null file name"
108: "can't stat file"
109: "unit not connected"
110: "off end of record"
111: "truncation failed in endfile"
112: "incomprehensible list input"
113: "out of free space"
114: "unit not connected"
115: "read unexpected character"
116: "bad logical input field"
117: "bad variable type"
118: "bad namelist name"
119: "variable not in namelist"
120: "no end record"
121: "variable count incorrect"
122: "subscript for scalar variable"
123: "invalid array section"
124: "substring out of bounds"
125: "subscript out of bounds"
126: "can't read file"
127: "can't write file"
128: "'new' file exists"
129: "can't append to file"
130: "non-positive record number"
131: "I/O started while already doing I/O"


Node:Scale Intrinsic, Next:Scan Intrinsic, Previous:RShift Intrinsic, Up:Table of Intrinsic Functions

Scale Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Scale to use this name for an external procedure.


Node:Scan Intrinsic, Next:Second Intrinsic (function), Previous:Scale Intrinsic, Up:Table of Intrinsic Functions

Scan Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Scan to use this name for an external procedure.


Node:Scope and Classes of Names, Next:I/O, Previous:Functions and Subroutines, Up:Language

Scope and Classes of Symbolic Names

(The following information augments or overrides the information in Chapter 18 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 18 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

  • Underscores in Symbol Names:


Node:Scope of Names and Labels, Previous:Statements Comments Lines, Up:Terms and Concepts

Scope of Symbolic Names and Statement Labels

(Corresponds to Section 2.9 of ANSI X3.9-1978 FORTRAN 77.)

Included in the list of entities that have a scope of a program unit are construct names (a Fortran 90 feature). See Construct Names, for more information.


Node:Secnds Intrinsic, Next:Signal Intrinsic (function), Previous:Rename Intrinsic (function), Up:Other Intrinsics

Secnds Intrinsic

Secnds(T)

Secnds: REAL(KIND=1) function.

T: REAL(KIND=1); scalar; INTENT(IN).

Intrinsic groups: vxt.

Description:

Returns the local time in seconds since midnight minus the value T.

This values returned by this intrinsic become numerically less than previous values (they wrap around) during a single run of the compiler program, under normal circumstances (such as running through the midnight hour).


Node:Second Intrinsic (function), Next:Second Intrinsic (subroutine), Previous:Scan Intrinsic, Up:Table of Intrinsic Functions

Second Intrinsic (function)

Second()

Second: REAL(KIND=1) function.

Intrinsic groups: unix.

Description:

Returns the process's runtime in seconds--the same value as the UNIX function etime returns.

On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wraparounds) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

For information on other intrinsics with the same name: See Second Intrinsic (subroutine).


Node:Second Intrinsic (subroutine), Next:Selected_Int_Kind Intrinsic, Previous:Second Intrinsic (function), Up:Table of Intrinsic Functions

Second Intrinsic (subroutine)

CALL Second(Seconds)

Seconds: REAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Returns the process's runtime in seconds in Seconds--the same value as the UNIX function etime returns.

On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wraparounds) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

This routine is known from Cray Fortran. See CPU_Time Intrinsic, for a standard equivalent.

For information on other intrinsics with the same name: See Second Intrinsic (function).


Node:SELECT CASE on CHARACTER Type, Next:RECURSIVE Keyword, Previous:Arbitrary Concatenation, Up:Missing Features

SELECT CASE on CHARACTER Type

Character-type selector/cases for SELECT CASE currently are not supported.


Node:Selected_Int_Kind Intrinsic, Next:Selected_Real_Kind Intrinsic, Previous:Second Intrinsic (subroutine), Up:Table of Intrinsic Functions

Selected_Int_Kind Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Selected_Int_Kind to use this name for an external procedure.


Node:Selected_Real_Kind Intrinsic, Next:Set_Exponent Intrinsic, Previous:Selected_Int_Kind Intrinsic, Up:Table of Intrinsic Functions

Selected_Real_Kind Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Selected_Real_Kind to use this name for an external procedure.


Node:Sensible Non-standard Constructs, Next:READONLY Keyword, Previous:POINTER Statements, Up:Missing Features

Sensible Non-standard Constructs

g77 rejects things other compilers accept, like INTRINSIC SQRT,SQRT. As time permits in the future, some of these things that are easy for humans to read and write and unlikely to be intended to mean something else will be accepted by g77 (though -fpedantic should trigger warnings about such non-standard constructs).

Until g77 no longer gratuitously rejects sensible code, you might as well fix your code to be more standard-conforming and portable.

The kind of case that is important to except from the recommendation to change your code is one where following good coding rules would force you to write non-standard code that nevertheless has a clear meaning.

For example, when writing an INCLUDE file that defines a common block, it might be appropriate to include a SAVE statement for the common block (such as SAVE /CBLOCK/), so that variables defined in the common block retain their values even when all procedures declaring the common block become inactive (return to their callers).

However, putting SAVE statements in an INCLUDE file would prevent otherwise standard-conforming code from also specifying the SAVE statement, by itself, to indicate that all local variables and arrays are to have the SAVE attribute.

For this reason, g77 already has been changed to allow this combination, because although the general problem of gratuitously rejecting unambiguous and "safe" constructs still exists in g77, this particular construct was deemed useful enough that it was worth fixing g77 for just this case.

So, while there is no need to change your code to avoid using this particular construct, there might be other, equally appropriate but non-standard constructs, that you shouldn't have to stop using just because g77 (or any other compiler) gratuitously rejects it.

Until the general problem is solved, if you have any such construct you believe is worthwhile using (e.g. not just an arbitrary, redundant specification of an attribute), please submit a bug report with an explanation, so we can consider fixing g77 just for cases like yours.


Node:Service, Next:Adding Options, Previous:Bugs, Up:Top

How To Get Help with GNU Fortran

If you need help installing, using or changing GNU Fortran, there are two ways to find it:

  • Look in the service directory for someone who might help you for a fee. The service directory is found in the file named SERVICE in the GNU CC distribution.
  • Send a message to gcc-help@gcc.gnu.org.


Node:Set_Exponent Intrinsic, Next:Shape Intrinsic, Previous:Selected_Real_Kind Intrinsic, Up:Table of Intrinsic Functions

Set_Exponent Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Set_Exponent to use this name for an external procedure.


Node:Shape Intrinsic, Next:Short Intrinsic, Previous:Set_Exponent Intrinsic, Up:Table of Intrinsic Functions

Shape Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Shape to use this name for an external procedure.


Node:Short Intrinsic, Next:Sign Intrinsic, Previous:Shape Intrinsic, Up:Table of Intrinsic Functions

Short Intrinsic

Short(A)

Short: INTEGER(KIND=6) function.

A: INTEGER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns A with the fractional portion of its magnitude truncated and its sign preserved, converted to type INTEGER(KIND=6).

If A is type COMPLEX, its real part is truncated and converted, and its imaginary part is disgregarded.

See Int Intrinsic.

The precise meaning of this intrinsic might change in a future version of the GNU Fortran language, as more is learned about how it is used.


Node:Short Lines, Next:Long Lines, Previous:Tabs, Up:Source Form

Short Lines

Source lines shorter than the applicable fixed-form length are treated as if they were padded with spaces to that length. (None of this is relevant to source files written in free form.)

This affects only continued character and Hollerith constants, and is a different interpretation than provided by some other popular compilers (although a bit more consistent with the traditional punched-card basis of Fortran and the way the Fortran standard expressed fixed source form).

g77 might someday offer an option to warn about cases where differences might be seen as a result of this treatment, and perhaps an option to specify the alternate behavior as well.

Note that this padding cannot apply to lines that are effectively of infinite length--such lines are specified using command-line options like -ffixed-line-length-none, for example.


Node:Shorthand Options, Next:Fortran Dialect Options, Previous:Overall Options, Up:Invoking G77

Shorthand Options

The following options serve as "shorthand" for other options accepted by the compiler:

-fugly
Note: This option is no longer supported. The information, below, is provided to aid in the conversion of old scripts.

Specify that certain "ugly" constructs are to be quietly accepted. Same as:

-fugly-args -fugly-assign -fugly-assumed
-fugly-comma -fugly-complex -fugly-init
-fugly-logint

These constructs are considered inappropriate to use in new or well-maintained portable Fortran code, but widely used in old code. See Distensions, for more information.

-fno-ugly
Specify that all "ugly" constructs are to be noisily rejected. Same as:
-fno-ugly-args -fno-ugly-assign -fno-ugly-assumed
-fno-ugly-comma -fno-ugly-complex -fno-ugly-init
-fno-ugly-logint

See Distensions, for more information.

-ff66
Specify that the program is written in idiomatic FORTRAN 66. Same as -fonetrip -fugly-assumed.

The -fno-f66 option is the inverse of -ff66. As such, it is the same as -fno-onetrip -fno-ugly-assumed.

The meaning of this option is likely to be refined as future versions of g77 provide more compatibility with other existing and obsolete Fortran implementations.

-ff77
Specify that the program is written in idiomatic UNIX FORTRAN 77 and/or the dialect accepted by the f2c product. Same as -fbackslash -fno-typeless-boz.

The meaning of this option is likely to be refined as future versions of g77 provide more compatibility with other existing and obsolete Fortran implementations.

-fno-f77
The -fno-f77 option is not the inverse of -ff77. It specifies that the program is not written in idiomatic UNIX FORTRAN 77 or f2c but in a more widely portable dialect. -fno-f77 is the same as -fno-backslash.

The meaning of this option is likely to be refined as future versions of g77 provide more compatibility with other existing and obsolete Fortran implementations.


Node:Sign Intrinsic, Next:Signal Intrinsic (subroutine), Previous:Short Intrinsic, Up:Table of Intrinsic Functions

Sign Intrinsic

Sign(A, B)

Sign: INTEGER or REAL function, the exact type being the result of cross-promoting the types of all the arguments.

A: INTEGER or REAL; scalar; INTENT(IN).

B: INTEGER or REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns ABS(A)*s, where s is +1 if B.GE.0, -1 otherwise.

See Abs Intrinsic, for the function that returns the magnitude of a value.


Node:Signal 11 and Friends, Next:Cannot Link Fortran Programs, Up:But-bugs

Signal 11 and Friends

A whole variety of strange behaviors can occur when the software, or the way you are using the software, stresses the hardware in a way that triggers hardware bugs. This might seem hard to believe, but it happens frequently enough that there exist documents explaining in detail what the various causes of the problems are, what typical symptoms look like, and so on.

Generally these problems are referred to in this document as "signal 11" crashes, because the Linux kernel, running on the most popular hardware (the Intel x86 line), often stresses the hardware more than other popular operating systems. When hardware problems do occur under GNU/Linux on x86 systems, these often manifest themselves as "signal 11" problems, as illustrated by the following diagnostic:

sh# g77 myprog.f
gcc: Internal compiler error: program f771 got fatal signal 11
sh#

It is very important to remember that the above message is not the only one that indicates a hardware problem, nor does it always indicate a hardware problem.

In particular, on systems other than those running the Linux kernel, the message might appear somewhat or very different, as it will if the error manifests itself while running a program other than the g77 compiler. For example, it will appear somewhat different when running your program, when running Emacs, and so on.

How to cope with such problems is well beyond the scope of this manual.

However, users of Linux-based systems (such as GNU/Linux) should review http://www.bitwizard.nl/sig11/, a source of detailed information on diagnosing hardware problems, by recognizing their common symptoms.

Users of other operating systems and hardware might find this reference useful as well. If you know of similar material for another hardware/software combination, please let us know so we can consider including a reference to it in future versions of this manual.


Node:Signal Intrinsic (function), Next:SinD Intrinsic, Previous:Secnds Intrinsic, Up:Other Intrinsics

Signal Intrinsic (function)

Signal(Number, Handler)

Signal: INTEGER(KIND=7) function.

Number: INTEGER; scalar; INTENT(IN).

Handler: Signal handler (INTEGER FUNCTION or SUBROUTINE) or dummy/global INTEGER(KIND=1) scalar.

Intrinsic groups: badu77.

Description:

If Handler is a an EXTERNAL routine, arranges for it to be invoked with a single integer argument (of system-dependent length) when signal Number occurs. If Handler is an integer, it can be used to turn off handling of signal Number or revert to its default action. See signal(2).

Note that Handler will be called using C conventions, so the value of its argument in Fortran terms is obtained by applying %LOC() (or LOC()) to it.

The value returned by signal(2) is returned.

Due to the side effects performed by this intrinsic, the function form is not recommended.

Warning: If the returned value is stored in an INTEGER(KIND=1) (default INTEGER) argument, truncation of the original return value occurs on some systems (such as Alphas, which have 64-bit pointers but 32-bit default integers), with no warning issued by g77 under normal circumstances.

Therefore, the following code fragment might silently fail on some systems:

INTEGER RTN
EXTERNAL MYHNDL
RTN = SIGNAL(signum, MYHNDL)
...
! Restore original handler:
RTN = SIGNAL(signum, RTN)

The reason for the failure is that RTN might not hold all the information on the original handler for the signal, thus restoring an invalid handler. This bug could manifest itself as a spurious run-time failure at an arbitrary point later during the program's execution, for example.

Warning: Use of the libf2c run-time library function signal_ directly (such as via EXTERNAL SIGNAL) requires use of the %VAL() construct to pass an INTEGER value (such as SIG_IGN or SIG_DFL) for the Handler argument.

However, while RTN = SIGNAL(signum, %VAL(SIG_IGN)) works when SIGNAL is treated as an external procedure (and resolves, at link time, to libf2c's signal_ routine), this construct is not valid when SIGNAL is recognized as the intrinsic of that name.

Therefore, for maximum portability and reliability, code such references to the SIGNAL facility as follows:

INTRINSIC SIGNAL
...
RTN = SIGNAL(signum, SIG_IGN)

g77 will compile such a call correctly, while other compilers will generally either do so as well or reject the INTRINSIC SIGNAL statement via a diagnostic, allowing you to take appropriate action.

For information on other intrinsics with the same name: See Signal Intrinsic (subroutine).


Node:Signal Intrinsic (subroutine), Next:Sin Intrinsic, Previous:Sign Intrinsic, Up:Table of Intrinsic Functions

Signal Intrinsic (subroutine)

CALL Signal(Number, Handler, Status)

Number: INTEGER; scalar; INTENT(IN).

Handler: Signal handler (INTEGER FUNCTION or SUBROUTINE) or dummy/global INTEGER(KIND=1) scalar.

Status: INTEGER(KIND=7); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

If Handler is a an EXTERNAL routine, arranges for it to be invoked with a single integer argument (of system-dependent length) when signal Number occurs. If Handler is an integer, it can be used to turn off handling of signal Number or revert to its default action. See signal(2).

Note that Handler will be called using C conventions, so the value of its argument in Fortran terms Fortran terms is obtained by applying %LOC() (or LOC()) to it.

The value returned by signal(2) is written to Status, if that argument is supplied. Otherwise the return value is ignored.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

Warning: Use of the libf2c run-time library function signal_ directly (such as via EXTERNAL SIGNAL) requires use of the %VAL() construct to pass an INTEGER value (such as SIG_IGN or SIG_DFL) for the Handler argument.

However, while CALL SIGNAL(signum, %VAL(SIG_IGN)) works when SIGNAL is treated as an external procedure (and resolves, at link time, to libf2c's signal_ routine), this construct is not valid when SIGNAL is recognized as the intrinsic of that name.

Therefore, for maximum portability and reliability, code such references to the SIGNAL facility as follows:

INTRINSIC SIGNAL
...
CALL SIGNAL(signum, SIG_IGN)

g77 will compile such a call correctly, while other compilers will generally either do so as well or reject the INTRINSIC SIGNAL statement via a diagnostic, allowing you to take appropriate action.

For information on other intrinsics with the same name: See Signal Intrinsic (function).


Node:Simplify Porting, Next:More Extensions, Previous:Better Optimization, Up:Projects

Simplify Porting

Making g77 easier to configure, port, build, and install, either as a single-system compiler or as a cross-compiler, would be very useful.

  • A new library (replacing libg2c) should improve portability as well as produce more optimal code. Further, g77 and the new library should conspire to simplify naming of externals, such as by removing unnecessarily added underscores, and to reduce/eliminate the possibility of naming conflicts, while making debugger more straightforward.

    Also, it should make multi-language applications more feasible, such as by providing Fortran intrinsics that get Fortran unit numbers given C FILE * descriptors.

  • Possibly related to a new library, g77 should produce the equivalent of a gcc main(argc, argv) function when it compiles a main program unit, instead of compiling something that must be called by a library implementation of main().

    This would do many useful things such as provide more flexibility in terms of setting up exception handling, not requiring programmers to start their debugging sessions with breakpoint MAIN__ followed by run, and so on.

  • The GBE needs to understand the difference between alignment requirements and desires. For example, on Intel x86 machines, g77 currently imposes overly strict alignment requirements, due to the back end, but it would be useful for Fortran and C programmers to be able to override these recommendations as long as they don't violate the actual processor requirements.


Node:Sin Intrinsic, Next:SinH Intrinsic, Previous:Signal Intrinsic (subroutine), Up:Table of Intrinsic Functions

Sin Intrinsic

Sin(X)

Sin: REAL or COMPLEX function, the exact type being that of argument X.

X: REAL or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the sine of X, an angle measured in radians.

See ASin Intrinsic, for the inverse of this function.


Node:SinD Intrinsic, Next:SnglQ Intrinsic, Previous:Signal Intrinsic (function), Up:Other Intrinsics

SinD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL SinD to use this name for an external procedure.


Node:SinH Intrinsic, Next:Sleep Intrinsic, Previous:Sin Intrinsic, Up:Table of Intrinsic Functions

SinH Intrinsic

SinH(X)

SinH: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the hyperbolic sine of X.


Node:Sleep Intrinsic, Next:Sngl Intrinsic, Previous:SinH Intrinsic, Up:Table of Intrinsic Functions

Sleep Intrinsic

CALL Sleep(Seconds)

Seconds: INTEGER(KIND=1); scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Causes the process to pause for Seconds seconds. See sleep(2).


Node:Sngl Intrinsic, Next:Spacing Intrinsic, Previous:Sleep Intrinsic, Up:Table of Intrinsic Functions

Sngl Intrinsic

Sngl(A)

Sngl: REAL(KIND=1) function.

A: REAL(KIND=2); scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Archaic form of REAL() that is specific to one type for A. See Real Intrinsic.


Node:SnglQ Intrinsic, Next:SymLnk Intrinsic (function), Previous:SinD Intrinsic, Up:Other Intrinsics

SnglQ Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL SnglQ to use this name for an external procedure.


Node:Spacing Intrinsic, Next:Spread Intrinsic, Previous:Sngl Intrinsic, Up:Table of Intrinsic Functions

Spacing Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Spacing to use this name for an external procedure.


Node:Specification Statements, Next:Control Statements, Previous:Expressions, Up:Language

Specification Statements

(The following information augments or overrides the information in Chapter 8 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 8 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

  • NAMELIST:
  • DOUBLE COMPLEX:


Node:Spread Intrinsic, Next:SqRt Intrinsic, Previous:Spacing Intrinsic, Up:Table of Intrinsic Functions

Spread Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Spread to use this name for an external procedure.


Node:SqRt Intrinsic, Next:SRand Intrinsic, Previous:Spread Intrinsic, Up:Table of Intrinsic Functions

SqRt Intrinsic

SqRt(X)

SqRt: REAL or COMPLEX function, the exact type being that of argument X.

X: REAL or COMPLEX; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the square root of X, which must not be negative.

To calculate and represent the square root of a negative number, complex arithmetic must be used. For example, SQRT(COMPLEX(X)).

The inverse of this function is SQRT(X) * SQRT(X).


Node:SRand Intrinsic, Next:Stat Intrinsic (subroutine), Previous:SqRt Intrinsic, Up:Table of Intrinsic Functions

SRand Intrinsic

CALL SRand(Seed)

Seed: INTEGER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Reinitialises the generator with the seed in Seed. See IRand Intrinsic. See Rand Intrinsic.


Node:sta.c, Next:sti.c, Previous:lex.c, Up:Overview of Translation Process

sta.c


Node:Stack Overflow, Next:Nothing Happens, Previous:NeXTStep Problems, Up:But-bugs

Stack Overflow

g77 code might fail at runtime (probably with a "segmentation violation") due to overflowing the stack. This happens most often on systems with an environment that provides substantially more heap space (for use when arbitrarily allocating and freeing memory) than stack space.

Often this can be cured by increasing or removing your shell's limit on stack usage, typically using limit stacksize (in csh and derivatives) or ulimit -s (in sh and derivatives).

Increasing the allowed stack size might, however, require changing some operating system or system configuration parameters.

You might be able to work around the problem by compiling with the -fno-automatic option to reduce stack usage, probably at the expense of speed.

g77, on most machines, puts many variables and arrays on the stack where possible, and can be configured (by changing FFECOM_sizeMAXSTACKITEM in gcc/gcc/f/com.c) to force smaller-sized entities into static storage (saving on stack space) or permit larger-sized entities to be put on the stack (which can improve run-time performance, as it presents more opportunities for the GBE to optimize the generated code).

Note: Putting more variables and arrays on the stack might cause problems due to system-dependent limits on stack size. Also, the value of FFECOM_sizeMAXSTACKITEM has no effect on automatic variables and arrays. See But-bugs, for more information. Note: While libg2c places a limit on the range of Fortran file-unit numbers, the underlying library and operating system might impose different kinds of limits. For example, some systems limit the number of files simultaneously open by a running program. Information on how to increase these limits should be found in your system's documentation.

However, if your program uses large automatic arrays (for example, has declarations like REAL A(N) where A is a local array and N is a dummy or COMMON variable that can have a large value), neither use of -fno-automatic, nor changing the cut-off point for g77 for using the stack, will solve the problem by changing the placement of these large arrays, as they are necessarily automatic.

g77 currently provides no means to specify that automatic arrays are to be allocated on the heap instead of the stack. So, other than increasing the stack size, your best bet is to change your source code to avoid large automatic arrays. Methods for doing this currently are outside the scope of this document.

(Note: If your system puts stack and heap space in the same memory area, such that they are effectively combined, then a stack overflow probably indicates a program that is either simply too large for the system, or buggy.)


Node:Standard Support, Next:Conformance, Previous:Direction of Language Development, Up:Language

ANSI FORTRAN 77 Standard Support

GNU Fortran supports ANSI FORTRAN 77 with the following caveats. In summary, the only ANSI FORTRAN 77 features g77 doesn't support are those that are probably rarely used in actual code, some of which are explicitly disallowed by the Fortran 90 standard.

  • No Passing External Assumed-length: CHAR*(*) CFUNC restriction.
  • No Passing Dummy Assumed-length: CHAR*(*) CFUNC restriction.
  • No Pathological Implied-DO: No ((..., I=...), I=...).
  • No Useless Implied-DO: No (A, I=1, 1).


Node:Star Notation, Next:Kind Notation, Previous:Double Notation, Up:Types

Star Notation

The following notation specifies the storage size for a type:

generic-type*n

generic-type must be a generic type--one of INTEGER, REAL, COMPLEX, LOGICAL, or CHARACTER. n must be one or more digits comprising a decimal integer number greater than zero.

Use the above form where a type name is valid.

The *n notation specifies that the amount of storage occupied by variables and array elements of that type is n times the storage occupied by a CHARACTER*1 variable.

This notation might indicate a different degree of precision and/or range for such variables and array elements, and the functions that return values of types using this notation. It does not limit the precision or range of values of that type in any particular way--use explicit code to do that.

Further, the GNU Fortran language requires no particular values for n to be supported by an implementation via the *n notation. g77 supports INTEGER*1 (as INTEGER(KIND=3)) on all systems, for example, but not all implementations are required to do so, and g77 is known to not support REAL*1 on most (or all) systems.

As a result, except for generic-type of CHARACTER, uses of this notation should be limited to isolated portions of a program that are intended to handle system-specific tasks and are expected to be non-portable.

(Standard FORTRAN 77 supports the *n notation for only CHARACTER, where it signifies not only the amount of storage occupied, but the number of characters in entities of that type. However, almost all Fortran compilers have supported this notation for generic types, though with a variety of meanings for n.)

Specifications of types using the *n notation always are interpreted as specifications of the appropriate types described in this document using the KIND=n notation, described below.

While use of this notation is popular, it doesn't serve well in the context of a widely portable dialect of Fortran, such as the GNU Fortran language.

For example, even on one particular machine, two or more popular Fortran compilers might well disagree on the size of a type declared INTEGER*2 or REAL*16. Certainly there is known to be disagreement over such things among Fortran compilers on different systems.

Further, this notation offers no elegant way to specify sizes that are not even multiples of the "byte size" typically designated by INTEGER*1. Use of "absurd" values (such as INTEGER*1000) would certainly be possible, but would perhaps be stretching the original intent of this notation beyond the breaking point in terms of widespread readability of documentation and code making use of it.

Therefore, this document uses "star notation" only on occasion for the benefit of those readers who are accustomed to it.


Node:Startup Code, Previous:C++ Considerations, Up:Interoperating with C and C++

Startup Code

Unlike with some runtime systems, it shouldn't be necessary (unless there are bugs) to use a Fortran main program unit to ensure the runtime--specifically the I/O system--is initialized.

However, to use the g77 intrinsics GETARG and IARGC, either the main routine from the libg2c library must be used, or the f_setarg routine (new as of egcs version 1.1 and g77 version 0.5.23) must be called with the appropriate argc and argv arguments prior to the program calling GETARG or IARGC.

To provide more flexibility for mixed-language programming involving g77 while allowing for shared libraries, as of egcs version 1.1 and g77 version 0.5.23, g77's main routine in libg2c does the following, in order:

  1. Calls f_setarg with the incoming argc and argv arguments, in the same order as for main itself.

    This sets up the command-line environment for GETARG and IARGC.

  2. Calls f_setsig (with no arguments).

    This sets up the signaling and exception environment.

  3. Calls f_init (with no arguments).

    This initializes the I/O environment, though that should not be necessary, as all I/O functions in libf2c are believed to call f_init automatically, if necessary.

    (A future version of g77 might skip this explicit step, to speed up normal exit of a program.)

  4. Arranges for f_exit to be called (with no arguments) when the program exits.

    This ensures that the I/O environment is properly shut down before the program exits normally. Otherwise, output buffers might not be fully flushed, scratch files might not be deleted, and so on.

    The simple way main does this is to call f_exit itself after calling MAIN__ (in the next step).

    However, this does not catch the cases where the program might call exit directly, instead of using the EXIT intrinsic (implemented as exit_ in libf2c).

    So, main attempts to use the operating environment's onexit or atexit facility, if available, to cause f_exit to be called automatically upon any invocation of exit.

  5. Calls MAIN__ (with no arguments).

    This starts executing the Fortran main program unit for the application. (Both g77 and f2c currently compile a main program unit so that its global name is MAIN__.)

  6. If no onexit or atexit is provided by the system, calls f_exit.
  7. Calls exit with a zero argument, to signal a successful program termination.
  8. Returns a zero value to the caller, to signal a successful program termination, in case exit doesn't exit on the system.

All of the above names are C extern names, i.e. not mangled.

When using the main procedure provided by g77 without a Fortran main program unit, you need to provide MAIN__ as the entry point for your C code. (Make sure you link the object file that defines that entry point with the rest of your program.)

To provide your own main procedure in place of g77's, make sure you specify the object file defining that procedure before -lg2c on the g77 command line. Since the -lg2c option is implicitly provided, this is usually straightforward. (Use the --verbose option to see how and where g77 implicitly adds -lg2c in a command line that will link the program. Feel free to specify -lg2c explicitly, as appropriate.)

However, when providing your own main, make sure you perform the appropriate tasks in the appropriate order. For example, if your main does not call f_setarg, make sure the rest of your application does not call GETARG or IARGC.

And, if your main fails to ensure that f_exit is called upon program exit, some files might end up incompletely written, some scratch files might be left lying around, and some existing files being written might be left with old data not properly truncated at the end.

Note that, generally, the g77 operating environment does not depend on a procedure named MAIN__ actually being called prior to any other g77-compiled code. That is, MAIN__ does not, itself, set up any important operating-environment characteristics upon which other code might depend. This might change in future versions of g77, with appropriate notification in the release notes.

For more information, consult the source code for the above routines. These are in gcc/libf2c/libF77/, named main.c, setarg.c, setsig.c, getarg_.c, and iargc_.c.

Also, the file gcc/gcc/f/com.c contains the code g77 uses to open-code (inline) references to IARGC.


Node:Stat Intrinsic (function), Next:Sum Intrinsic, Previous:Stat Intrinsic (subroutine), Up:Table of Intrinsic Functions

Stat Intrinsic (function)

Stat(File, SArray)

Stat: INTEGER(KIND=1) function.

File: CHARACTER; scalar; INTENT(IN).

SArray: INTEGER(KIND=1); DIMENSION(13); INTENT(OUT).

Intrinsic groups: unix.

Description:

Obtains data about the given file File and places them in the array SArray. A null character (CHAR(0)) marks the end of the name in File--otherwise, trailing blanks in File are ignored. The values in this array are extracted from the stat structure as returned by fstat(2) q.v., as follows:

  1. Device ID
  2. Inode number
  3. File mode
  4. Number of links
  5. Owner's uid
  6. Owner's gid
  7. ID of device containing directory entry for file (0 if not available)
  8. File size (bytes)
  9. Last access time
  10. Last modification time
  11. Last file status change time
  12. Preferred I/O block size (-1 if not available)
  13. Number of blocks allocated (-1 if not available)

Not all these elements are relevant on all systems. If an element is not relevant, it is returned as 0.

Returns 0 on success or a non-zero error code.

For information on other intrinsics with the same name: See Stat Intrinsic (subroutine).


Node:Stat Intrinsic (subroutine), Next:Stat Intrinsic (function), Previous:SRand Intrinsic, Up:Table of Intrinsic Functions

Stat Intrinsic (subroutine)

CALL Stat(File, SArray, Status)

File: CHARACTER; scalar; INTENT(IN).

SArray: INTEGER(KIND=1); DIMENSION(13); INTENT(OUT).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Obtains data about the given file File and places them in the array SArray. A null character (CHAR(0)) marks the end of the name in File--otherwise, trailing blanks in File are ignored. The values in this array are extracted from the stat structure as returned by fstat(2) q.v., as follows:

  1. Device ID
  2. Inode number
  3. File mode
  4. Number of links
  5. Owner's uid
  6. Owner's gid
  7. ID of device containing directory entry for file (0 if not available)
  8. File size (bytes)
  9. Last access time
  10. Last modification time
  11. Last file status change time
  12. Preferred I/O block size (-1 if not available)
  13. Number of blocks allocated (-1 if not available)

Not all these elements are relevant on all systems. If an element is not relevant, it is returned as 0.

If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See Stat Intrinsic (function).


Node:Statement Labels, Next:Order, Previous:Statements, Up:Characters Lines Sequence

Statement Labels

(Corresponds to Section 3.4 of ANSI X3.9-1978 FORTRAN 77.)

A statement separated from its predecessor via a semicolon may be labeled as follows:

  • The semicolon is followed by the label for the statement, which in turn follows the label.
  • The label must be no more than five digits in length.
  • The first digit of the label for the statement is not the first non-space character on a line. Otherwise, that character is treated as a continuation character.

A statement may have only one label defined for it.


Node:Statements Comments Lines, Next:Scope of Names and Labels, Previous:Syntactic Items, Up:Terms and Concepts

Statements, Comments, and Lines

(Corresponds to Section 2.3 of ANSI X3.9-1978 FORTRAN 77.)

Use of an exclamation point (!) to begin a trailing comment (a comment that extends to the end of the same source line) is permitted under the following conditions:

  • The exclamation point does not appear in column 6. Otherwise, it is treated as an indicator of a continuation line.
  • The exclamation point appears outside a character or Hollerith constant. Otherwise, the exclamation point is considered part of the constant.
  • The exclamation point appears to the left of any other possible trailing comment. That is, a trailing comment may contain exclamation points in their commentary text.

Use of a semicolon (;) as a statement separator is permitted under the following conditions:

  • The semicolon appears outside a character or Hollerith constant. Otherwise, the semicolon is considered part of the constant.
  • The semicolon appears to the left of a trailing comment. Otherwise, the semicolon is considered part of that comment.
  • Neither a logical IF statement nor a non-construct WHERE statement (a Fortran 90 feature) may be followed (in the same, possibly continued, line) by a semicolon used as a statement separator.

    This restriction avoids the confusion that can result when reading a line such as:

    IF (VALIDP) CALL FOO; CALL BAR

    Some readers might think the CALL BAR is executed only if VALIDP is .TRUE., while others might assume its execution is unconditional.

    (At present, g77 does not diagnose code that violates this restriction.)


Node:Statements Needing Temporaries, Next:Transforming DO WHILE, Up:Transforming Statements

Statements Needing Temporaries

Any temporaries needed during, but not beyond, execution of a Fortran statement, are made local to the scope of that statement's block.

This allows the GBE to share storage for these temporaries among the various statements without the FFE having to manage that itself.

(The GBE could, of course, decide to optimize management of these temporaries. For example, it could, theoretically, schedule some of the computations involving these temporaries to occur in parallel. More practically, it might leave the storage for some temporaries "live" beyond their scopes, to reduce the number of manipulations of the stack pointer at run time.)

Temporaries needed across distinct statement boundaries usually are associated with Fortran blocks (such as DO/END DO). (Also, there might be temporaries not associated with blocks at all--these would be in the scope of the entire program unit.)

Each Fortran block should get its own block/scope in the GBE. This is best, because it allows temporaries to be more naturally handled. However, it might pose problems when handling labels (in particular, when they're the targets of GOTOs outside the Fortran block), and generally just hassling with replicating parts of the gcc front end (because the FFE needs to support an arbitrary number of nested back-end blocks if each Fortran block gets one).

So, there might still be a need for top-level temporaries, whose "owning" scope is that of the containing procedure.

Also, there seems to be problems declaring new variables after generating code (within a block) in the back end, leading to, e.g., label not defined before binding contour or similar messages, when compiling with -fstack-check or when compiling for certain targets.

Because of that, and because sometimes these temporaries are not discovered until in the middle of of generating code for an expression statement (as in the case of the optimization for X**I), it seems best to always pre-scan all the expressions that'll be expanded for a block before generating any of the code for that block.

This pre-scan then handles discovering and declaring, to the back end, the temporaries needed for that block.

It's also important to treat distinct items in an I/O list as distinct statements deserving their own blocks. That's because there's a requirement that each I/O item be fully processed before the next one, which matters in cases like READ (*,*), I, A(I)--the element of A read in the second item must be determined from the value of I read in the first item.


Node:Statements, Next:Statement Labels, Previous:Continuation Line, Up:Characters Lines Sequence

Statements

(Corresponds to Section 3.3 of ANSI X3.9-1978 FORTRAN 77.)

Statements may be written using an arbitrary number of continuation lines.

Statements may be separated using the semicolon (;), except that the logical IF and non-construct WHERE statements may not be separated from subsequent statements using only a semicolon as statement separator.

The END PROGRAM, END SUBROUTINE, END FUNCTION, and END BLOCK DATA statements are alternatives to the END statement. These alternatives may be written as normal statements--they are not subject to the restrictions of the END statement.

However, no statement other than END may have an initial line that appears to be an END statement--even END PROGRAM, for example, must not be written as:

      END
     &PROGRAM


Node:stb.c, Next:expr.c, Previous:stq.c, Up:Overview of Translation Process

stb.c


Node:stc.c, Next:std.c, Previous:expr.c, Up:Overview of Translation Process

stc.c


Node:std.c, Next:ste.c, Previous:stc.c, Up:Overview of Translation Process

std.c


Node:ste.c, Next:Gotchas (Transforming), Previous:std.c, Up:Overview of Translation Process

ste.c


Node:sti.c, Next:stq.c, Previous:sta.c, Up:Overview of Translation Process

sti.c


Node:stq.c, Next:stb.c, Previous:sti.c, Up:Overview of Translation Process

stq.c


Node:Strange Behavior at Run Time, Next:Floating-point Errors, Previous:Nothing Happens, Up:But-bugs

Strange Behavior at Run Time

g77 code might fail at runtime with "segmentation violation", "bus error", or even something as subtle as a procedure call overwriting a variable or array element that it is not supposed to touch.

These can be symptoms of a wide variety of actual bugs that occurred earlier during the program's run, but manifested themselves as visible problems some time later.

Overflowing the bounds of an array--usually by writing beyond the end of it--is one of two kinds of bug that often occurs in Fortran code. (Compile your code with the -fbounds-check option to catch many of these kinds of errors at program run time.)

The other kind of bug is a mismatch between the actual arguments passed to a procedure and the dummy arguments as declared by that procedure.

Both of these kinds of bugs, and some others as well, can be difficult to track down, because the bug can change its behavior, or even appear to not occur, when using a debugger.

That is, these bugs can be quite sensitive to data, including data representing the placement of other data in memory (that is, pointers, such as the placement of stack frames in memory).

g77 now offers the ability to catch and report some of these problems at compile, link, or run time, such as by generating code to detect references to beyond the bounds of most arrays (except assumed-size arrays), and checking for agreement between calling and called procedures. Future improvements are likely to be made in the procedure-mismatch area, at least.

In the meantime, finding and fixing the programming bugs that lead to these behaviors is, ultimately, the user's responsibility, as difficult as that task can sometimes be.

One runtime problem that has been observed might have a simple solution. If a formatted WRITE produces an endless stream of spaces, check that your program is linked against the correct version of the C library. The configuration process takes care to account for your system's normal libc not being ANSI-standard, which will otherwise cause this behaviour. If your system's default library is ANSI-standard and you subsequently link against a non-ANSI one, there might be problems such as this one.

Specifically, on Solaris2 systems, avoid picking up the BSD library from /usr/ucblib.


Node:STRUCTURE UNION RECORD MAP, Next:OPEN CLOSE and INQUIRE Keywords, Previous:TYPE and ACCEPT I/O Statements, Up:Missing Features

STRUCTURE, UNION, RECORD, MAP

g77 doesn't support STRUCTURE, UNION, RECORD, MAP. This set of extensions is quite a bit lower on the list of large, important things to add to g77, partly because it requires a great deal of work either upgrading or replacing libg2c.


Node:Sum Intrinsic, Next:SymLnk Intrinsic (subroutine), Previous:Stat Intrinsic (function), Up:Table of Intrinsic Functions

Sum Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Sum to use this name for an external procedure.


Node:Support for Threads, Next:Increasing Precision/Range, Previous:Large Automatic Arrays, Up:Missing Features

Support for Threads

Neither the code produced by g77 nor the libg2c library are thread-safe, nor does g77 have support for parallel processing (other than the instruction-level parallelism available on some processors). A package such as PVM might help here.


Node:Suppressing Space Padding, Next:Fortran Preprocessor, Previous:AUTOMATIC Statement, Up:Missing Features

Suppressing Space Padding of Source Lines

g77 should offer VXT-Fortran-style suppression of virtual spaces at the end of a source line if an appropriate command-line option is specified.

This affects cases where a character constant is continued onto the next line in a fixed-form source file, as in the following example:

10    PRINT *,'HOW MANY
     1 SPACES?'

g77, and many other compilers, virtually extend the continued line through column 72 with spaces that become part of the character constant, but Digital Fortran normally didn't, leaving only one space between MANY and SPACES? in the output of the above statement.

Fairly recently, at least one version of Digital Fortran was enhanced to provide the other behavior when a command-line option is specified, apparently due to demand from readers of the USENET group comp.lang.fortran to offer conformance to this widespread practice in the industry. g77 should return the favor by offering conformance to Digital's approach to handling the above example.


Node:Surprising Interpretations of Code, Next:Aliasing Assumed To Work, Previous:Unused Arguments, Up:Working Programs

Surprising Interpretations of Code

The -Wsurprising option can help find bugs involving expression evaluation or in the way DO loops with non-integral iteration variables are handled. Cases found by this option might indicate a difference of interpretation between the author of the code involved, and a standard-conforming compiler such as g77. Such a difference might produce actual bugs.

In any case, changing the code to explicitly do what the programmer might have expected it to do, so g77 and other compilers are more likely to follow the programmer's expectations, might be worthwhile, especially if such changes make the program work better.


Node:SymLnk Intrinsic (function), Next:System Intrinsic (function), Previous:SnglQ Intrinsic, Up:Other Intrinsics

SymLnk Intrinsic (function)

SymLnk(Path1, Path2)

SymLnk: INTEGER(KIND=1) function.

Path1: CHARACTER; scalar; INTENT(IN).

Path2: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Makes a symbolic link from file Path1 to Path2. A null character (CHAR(0)) marks the end of the names in Path1 and Path2--otherwise, trailing blanks in Path1 and Path2 are ignored. Returns 0 on success or a non-zero error code (ENOSYS if the system does not provide symlink(2)).

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See SymLnk Intrinsic (subroutine).


Node:SymLnk Intrinsic (subroutine), Next:System Intrinsic (subroutine), Previous:Sum Intrinsic, Up:Table of Intrinsic Functions

SymLnk Intrinsic (subroutine)

CALL SymLnk(Path1, Path2, Status)

Path1: CHARACTER; scalar; INTENT(IN).

Path2: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Makes a symbolic link from file Path1 to Path2. A null character (CHAR(0)) marks the end of the names in Path1 and Path2--otherwise, trailing blanks in Path1 and Path2 are ignored. If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return (ENOSYS if the system does not provide symlink(2)).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See SymLnk Intrinsic (function).


Node:Syntactic Items, Next:Statements Comments Lines, Up:Terms and Concepts

Syntactic Items

(Corresponds to Section 2.2 of ANSI X3.9-1978 FORTRAN 77.)

In GNU Fortran, a symbolic name is at least one character long, and has no arbitrary upper limit on length. However, names of entities requiring external linkage (such as external functions, external subroutines, and COMMON areas) might be restricted to some arbitrary length by the system. Such a restriction is no more constrained than that of one through six characters.

Underscores (_) are accepted in symbol names after the first character (which must be a letter).


Node:System Intrinsic (function), Next:TanD Intrinsic, Previous:SymLnk Intrinsic (function), Up:Other Intrinsics

System Intrinsic (function)

System(Command)

System: INTEGER(KIND=1) function.

Command: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Passes the command Command to a shell (see system(3)). Returns the value returned by system(3), presumably 0 if the shell command succeeded. Note that which shell is used to invoke the command is system-dependent and environment-dependent.

Due to the side effects performed by this intrinsic, the function form is not recommended. However, the function form can be valid in cases where the actual side effects performed by the call are unimportant to the application.

For example, on a UNIX system, SAME = SYSTEM('cmp a b') does not perform any side effects likely to be important to the program, so the programmer would not care if the actual system call (and invocation of cmp) was optimized away in a situation where the return value could be determined otherwise, or was not actually needed (SAME not actually referenced after the sample assignment statement).

For information on other intrinsics with the same name: See System Intrinsic (subroutine).


Node:System Intrinsic (subroutine), Next:System_Clock Intrinsic, Previous:SymLnk Intrinsic (subroutine), Up:Table of Intrinsic Functions

System Intrinsic (subroutine)

CALL System(Command, Status)

Command: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Passes the command Command to a shell (see system(3)). If argument Status is present, it contains the value returned by system(3), presumably 0 if the shell command succeeded. Note that which shell is used to invoke the command is system-dependent and environment-dependent.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See System Intrinsic (function).


Node:System_Clock Intrinsic, Next:Tan Intrinsic, Previous:System Intrinsic (subroutine), Up:Table of Intrinsic Functions

System_Clock Intrinsic

CALL System_Clock(Count, Rate, Max)

Count: INTEGER(KIND=1); scalar; INTENT(OUT).

Rate: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Max: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: f90.

Description:

Returns in Count the current value of the system clock; this is the value returned by the UNIX function times(2) in this implementation, but isn't in general. Rate is the number of clock ticks per second and Max is the maximum value this can take, which isn't very useful in this implementation since it's just the maximum C unsigned int value.

On some systems, the underlying timings are represented using types with sufficiently small limits that overflows (wraparounds) are possible, such as 32-bit types. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.


Node:Table of Intrinsic Functions, Previous:f77/f2c Intrinsics, Up:Functions and Subroutines

Table of Intrinsic Functions

(Corresponds to Section 15.10 of ANSI X3.9-1978 FORTRAN 77.)

The GNU Fortran language adds various functions, subroutines, types, and arguments to the set of intrinsic functions in ANSI FORTRAN 77. The complete set of intrinsics supported by the GNU Fortran language is described below.

Note that a name is not treated as that of an intrinsic if it is specified in an EXTERNAL statement in the same program unit; if a command-line option is used to disable the groups to which the intrinsic belongs; or if the intrinsic is not named in an INTRINSIC statement and a command-line option is used to hide the groups to which the intrinsic belongs.

So, it is recommended that any reference in a program unit to an intrinsic procedure that is not a standard FORTRAN 77 intrinsic be accompanied by an appropriate INTRINSIC statement in that program unit. This sort of defensive programming makes it more likely that an implementation will issue a diagnostic rather than generate incorrect code for such a reference.

The terminology used below is based on that of the Fortran 90 standard, so that the text may be more concise and accurate:

  • OPTIONAL means the argument may be omitted.
  • A-1, A-2, ..., A-n means more than one argument (generally named A) may be specified.
  • scalar means the argument must not be an array (must be a variable or array element, or perhaps a constant if expressions are permitted).
  • DIMENSION(4) means the argument must be an array having 4 elements.
  • INTENT(IN) means the argument must be an expression (such as a constant or a variable that is defined upon invocation of the intrinsic).
  • INTENT(OUT) means the argument must be definable by the invocation of the intrinsic (that is, must not be a constant nor an expression involving operators other than array reference and substring reference).
  • INTENT(INOUT) means the argument must be defined prior to, and definable by, invocation of the intrinsic (a combination of the requirements of INTENT(IN) and INTENT(OUT).
  • See Kind Notation, for an explanation of KIND.
  • Abort Intrinsic: Abort the program.

  • Abs Intrinsic: Absolute value.

  • Access Intrinsic: Check file accessibility.

  • AChar Intrinsic: ASCII character from code.

  • ACos Intrinsic: Arc cosine.

  • AdjustL Intrinsic: (Reserved for future use.)
  • AdjustR Intrinsic: (Reserved for future use.)

  • AImag Intrinsic: Convert/extract imaginary part of complex.

  • AInt Intrinsic: Truncate to whole number.

  • Alarm Intrinsic: Execute a routine after a given delay.

  • All Intrinsic: (Reserved for future use.)
  • Allocated Intrinsic: (Reserved for future use.)

  • ALog Intrinsic: Natural logarithm (archaic).
  • ALog10 Intrinsic: Common logarithm (archaic).
  • AMax0 Intrinsic: Maximum value (archaic).
  • AMax1 Intrinsic: Maximum value (archaic).
  • AMin0 Intrinsic: Minimum value (archaic).
  • AMin1 Intrinsic: Minimum value (archaic).
  • AMod Intrinsic: Remainder (archaic).

  • And Intrinsic: Boolean AND.

  • ANInt Intrinsic: Round to nearest whole number.

  • Any Intrinsic: (Reserved for future use.)

  • ASin Intrinsic: Arc sine.

  • Associated Intrinsic: (Reserved for future use.)

  • ATan Intrinsic: Arc tangent.
  • ATan2 Intrinsic: Arc tangent.

  • BesJ0 Intrinsic: Bessel function.
  • BesJ1 Intrinsic: Bessel function.
  • BesJN Intrinsic: Bessel function.
  • BesY0 Intrinsic: Bessel function.
  • BesY1 Intrinsic: Bessel function.
  • BesYN Intrinsic: Bessel function.

  • Bit_Size Intrinsic: Number of bits in argument's type.

  • BTest Intrinsic: Test bit.

  • CAbs Intrinsic: Absolute value (archaic).
  • CCos Intrinsic: Cosine (archaic).

  • Ceiling Intrinsic: (Reserved for future use.)

  • CExp Intrinsic: Exponential (archaic).
  • Char Intrinsic: Character from code.

  • ChDir Intrinsic (subroutine): Change directory.

  • ChMod Intrinsic (subroutine): Change file modes.

  • CLog Intrinsic: Natural logarithm (archaic).
  • Cmplx Intrinsic: Construct COMPLEX(KIND=1) value.

  • Complex Intrinsic: Build complex value from real and imaginary parts.

  • Conjg Intrinsic: Complex conjugate.
  • Cos Intrinsic: Cosine.

  • CosH Intrinsic: Hyperbolic cosine.

  • Count Intrinsic: (Reserved for future use.)
  • CPU_Time Intrinsic: Get current CPU time.
  • CShift Intrinsic: (Reserved for future use.)

  • CSin Intrinsic: Sine (archaic).
  • CSqRt Intrinsic: Square root (archaic).

  • CTime Intrinsic (subroutine): Convert time to Day Mon dd hh:mm:ss yyyy.
  • CTime Intrinsic (function): Convert time to Day Mon dd hh:mm:ss yyyy.

  • DAbs Intrinsic: Absolute value (archaic).
  • DACos Intrinsic: Arc cosine (archaic).

  • DASin Intrinsic: Arc sine (archaic).

  • DATan Intrinsic: Arc tangent (archaic).
  • DATan2 Intrinsic: Arc tangent (archaic).

  • Date_and_Time Intrinsic: Get the current date and time.

  • DbesJ0 Intrinsic: Bessel function (archaic).
  • DbesJ1 Intrinsic: Bessel function (archaic).
  • DbesJN Intrinsic: Bessel function (archaic).
  • DbesY0 Intrinsic: Bessel function (archaic).
  • DbesY1 Intrinsic: Bessel function (archaic).
  • DbesYN Intrinsic: Bessel function (archaic).

  • Dble Intrinsic: Convert to double precision.

  • DCos Intrinsic: Cosine (archaic).

  • DCosH Intrinsic: Hyperbolic cosine (archaic).
  • DDiM Intrinsic: Difference magnitude (archaic).

  • DErF Intrinsic: Error function (archaic).
  • DErFC Intrinsic: Complementary error function (archaic).

  • DExp Intrinsic: Exponential (archaic).

  • Digits Intrinsic: (Reserved for future use.)

  • DiM Intrinsic: Difference magnitude (non-negative subtract).

  • DInt Intrinsic: Truncate to whole number (archaic).
  • DLog Intrinsic: Natural logarithm (archaic).
  • DLog10 Intrinsic: Common logarithm (archaic).
  • DMax1 Intrinsic: Maximum value (archaic).
  • DMin1 Intrinsic: Minimum value (archaic).
  • DMod Intrinsic: Remainder (archaic).
  • DNInt Intrinsic: Round to nearest whole number (archaic).

  • Dot_Product Intrinsic: (Reserved for future use.)

  • DProd Intrinsic: Double-precision product.

  • DSign Intrinsic: Apply sign to magnitude (archaic).
  • DSin Intrinsic: Sine (archaic).

  • DSinH Intrinsic: Hyperbolic sine (archaic).
  • DSqRt Intrinsic: Square root (archaic).
  • DTan Intrinsic: Tangent (archaic).

  • DTanH Intrinsic: Hyperbolic tangent (archaic).

  • DTime Intrinsic (subroutine): Get elapsed time since last time.

  • EOShift Intrinsic: (Reserved for future use.)
  • Epsilon Intrinsic: (Reserved for future use.)

  • ErF Intrinsic: Error function.
  • ErFC Intrinsic: Complementary error function.
  • ETime Intrinsic (subroutine): Get elapsed time for process.
  • ETime Intrinsic (function): Get elapsed time for process.
  • Exit Intrinsic: Terminate the program.

  • Exp Intrinsic: Exponential.

  • Exponent Intrinsic: (Reserved for future use.)

  • FDate Intrinsic (subroutine): Get current time as Day Mon dd hh:mm:ss yyyy.
  • FDate Intrinsic (function): Get current time as Day Mon dd hh:mm:ss yyyy.
  • FGet Intrinsic (subroutine): Read a character from unit 5 stream-wise.

  • FGetC Intrinsic (subroutine): Read a character stream-wise.

  • Float Intrinsic: Conversion (archaic).

  • Floor Intrinsic: (Reserved for future use.)

  • Flush Intrinsic: Flush buffered output.
  • FNum Intrinsic: Get file descriptor from Fortran unit number.
  • FPut Intrinsic (subroutine): Write a character to unit 6 stream-wise.

  • FPutC Intrinsic (subroutine): Write a character stream-wise.

  • Fraction Intrinsic: (Reserved for future use.)

  • FSeek Intrinsic: Position file (low-level).
  • FStat Intrinsic (subroutine): Get file information.
  • FStat Intrinsic (function): Get file information.
  • FTell Intrinsic (subroutine): Get file position (low-level).
  • FTell Intrinsic (function): Get file position (low-level).
  • GError Intrinsic: Get error message for last error.
  • GetArg Intrinsic: Obtain command-line argument.
  • GetCWD Intrinsic (subroutine): Get current working directory.
  • GetCWD Intrinsic (function): Get current working directory.
  • GetEnv Intrinsic: Get environment variable.
  • GetGId Intrinsic: Get process group id.
  • GetLog Intrinsic: Get login name.
  • GetPId Intrinsic: Get process id.
  • GetUId Intrinsic: Get process user id.
  • GMTime Intrinsic: Convert time to GMT time info.
  • HostNm Intrinsic (subroutine): Get host name.
  • HostNm Intrinsic (function): Get host name.

  • Huge Intrinsic: (Reserved for future use.)

  • IAbs Intrinsic: Absolute value (archaic).

  • IAChar Intrinsic: ASCII code for character.

  • IAnd Intrinsic: Boolean AND.

  • IArgC Intrinsic: Obtain count of command-line arguments.

  • IBClr Intrinsic: Clear a bit.
  • IBits Intrinsic: Extract a bit subfield of a variable.
  • IBSet Intrinsic: Set a bit.

  • IChar Intrinsic: Code for character.

  • IDate Intrinsic (UNIX): Get local time info.

  • IDiM Intrinsic: Difference magnitude (archaic).
  • IDInt Intrinsic: Convert to INTEGER value truncated to whole number (archaic).
  • IDNInt Intrinsic: Convert to INTEGER value rounded to nearest whole number (archaic).

  • IEOr Intrinsic: Boolean XOR.

  • IErrNo Intrinsic: Get error number for last error.

  • IFix Intrinsic: Conversion (archaic).

  • Imag Intrinsic: Extract imaginary part of complex.

  • ImagPart Intrinsic: Extract imaginary part of complex.

  • Index Intrinsic: Locate a CHARACTER substring.

  • Int Intrinsic: Convert to INTEGER value truncated to whole number.

  • Int2 Intrinsic: Convert to INTEGER(KIND=6) value truncated to whole number.
  • Int8 Intrinsic: Convert to INTEGER(KIND=2) value truncated to whole number.

  • IOr Intrinsic: Boolean OR.

  • IRand Intrinsic: Random number.
  • IsaTty Intrinsic: Is unit connected to a terminal?

  • IShft Intrinsic: Logical bit shift.
  • IShftC Intrinsic: Circular bit shift.

  • ISign Intrinsic: Apply sign to magnitude (archaic).

  • ITime Intrinsic: Get local time of day.

  • Kill Intrinsic (subroutine): Signal a process.

  • Kind Intrinsic: (Reserved for future use.)
  • LBound Intrinsic: (Reserved for future use.)

  • Len Intrinsic: Length of character entity.

  • Len_Trim Intrinsic: Get last non-blank character in string.

  • LGe Intrinsic: Lexically greater than or equal.
  • LGt Intrinsic: Lexically greater than.

  • Link Intrinsic (subroutine): Make hard link in file system.

  • LLe Intrinsic: Lexically less than or equal.
  • LLt Intrinsic: Lexically less than.

  • LnBlnk Intrinsic: Get last non-blank character in string.
  • Loc Intrinsic: Address of entity in core.

  • Log Intrinsic: Natural logarithm.
  • Log10 Intrinsic: Common logarithm.

  • Logical Intrinsic: (Reserved for future use.)

  • Long Intrinsic: Conversion to INTEGER(KIND=1) (archaic).

  • LShift Intrinsic: Left-shift bits.

  • LStat Intrinsic (subroutine): Get file information.
  • LStat Intrinsic (function): Get file information.
  • LTime Intrinsic: Convert time to local time info.

  • MatMul Intrinsic: (Reserved for future use.)

  • Max Intrinsic: Maximum value.
  • Max0 Intrinsic: Maximum value (archaic).
  • Max1 Intrinsic: Maximum value (archaic).

  • MaxExponent Intrinsic: (Reserved for future use.)
  • MaxLoc Intrinsic: (Reserved for future use.)
  • MaxVal Intrinsic: (Reserved for future use.)

  • MClock Intrinsic: Get number of clock ticks for process.
  • MClock8 Intrinsic: Get number of clock ticks for process.

  • Merge Intrinsic: (Reserved for future use.)

  • Min Intrinsic: Minimum value.
  • Min0 Intrinsic: Minimum value (archaic).
  • Min1 Intrinsic: Minimum value (archaic).

  • MinExponent Intrinsic: (Reserved for future use.)
  • MinLoc Intrinsic: (Reserved for future use.)
  • MinVal Intrinsic: (Reserved for future use.)

  • Mod Intrinsic: Remainder.

  • Modulo Intrinsic: (Reserved for future use.)

  • MvBits Intrinsic: Moving a bit field.

  • Nearest Intrinsic: (Reserved for future use.)

  • NInt Intrinsic: Convert to INTEGER value rounded to nearest whole number.

  • Not Intrinsic: Boolean NOT.

  • Or Intrinsic: Boolean OR.

  • Pack Intrinsic: (Reserved for future use.)

  • PError Intrinsic: Print error message for last error.

  • Precision Intrinsic: (Reserved for future use.)
  • Present Intrinsic: (Reserved for future use.)
  • Product Intrinsic: (Reserved for future use.)

  • Radix Intrinsic: (Reserved for future use.)

  • Rand Intrinsic: Random number.

  • Random_Number Intrinsic: (Reserved for future use.)
  • Random_Seed Intrinsic: (Reserved for future use.)
  • Range Intrinsic: (Reserved for future use.)

  • Real Intrinsic: Convert value to type REAL(KIND=1).

  • RealPart Intrinsic: Extract real part of complex.

  • Rename Intrinsic (subroutine): Rename file.

  • Repeat Intrinsic: (Reserved for future use.)
  • Reshape Intrinsic: (Reserved for future use.)
  • RRSpacing Intrinsic: (Reserved for future use.)

  • RShift Intrinsic: Right-shift bits.

  • Scale Intrinsic: (Reserved for future use.)
  • Scan Intrinsic: (Reserved for future use.)

  • Second Intrinsic (function): Get CPU time for process in seconds.
  • Second Intrinsic (subroutine): Get CPU time for process in seconds.

  • Selected_Int_Kind Intrinsic: (Reserved for future use.)
  • Selected_Real_Kind Intrinsic: (Reserved for future use.)
  • Set_Exponent Intrinsic: (Reserved for future use.)
  • Shape Intrinsic: (Reserved for future use.)

  • Short Intrinsic: Convert to INTEGER(KIND=6) value truncated to whole number.

  • Sign Intrinsic: Apply sign to magnitude.

  • Signal Intrinsic (subroutine): Muck with signal handling.

  • Sin Intrinsic: Sine.

  • SinH Intrinsic: Hyperbolic sine.

  • Sleep Intrinsic: Sleep for a specified time.

  • Sngl Intrinsic: Convert (archaic).

  • Spacing Intrinsic: (Reserved for future use.)
  • Spread Intrinsic: (Reserved for future use.)

  • SqRt Intrinsic: Square root.

  • SRand Intrinsic: Random seed.
  • Stat Intrinsic (subroutine): Get file information.
  • Stat Intrinsic (function): Get file information.

  • Sum Intrinsic: (Reserved for future use.)

  • SymLnk Intrinsic (subroutine): Make symbolic link in file system.

  • System Intrinsic (subroutine): Invoke shell (system) command.

  • System_Clock Intrinsic: Get current system clock value.

  • Tan Intrinsic: Tangent.

  • TanH Intrinsic: Hyperbolic tangent.

  • Time Intrinsic (UNIX): Get current time as time value.

  • Time8 Intrinsic: Get current time as time value.

  • Tiny Intrinsic: (Reserved for future use.)
  • Transfer Intrinsic: (Reserved for future use.)
  • Transpose Intrinsic: (Reserved for future use.)
  • Trim Intrinsic: (Reserved for future use.)

  • TtyNam Intrinsic (subroutine): Get name of terminal device for unit.
  • TtyNam Intrinsic (function): Get name of terminal device for unit.

  • UBound Intrinsic: (Reserved for future use.)

  • UMask Intrinsic (subroutine): Set file creation permissions mask.

  • Unlink Intrinsic (subroutine): Unlink file.

  • Unpack Intrinsic: (Reserved for future use.)
  • Verify Intrinsic: (Reserved for future use.)

  • XOr Intrinsic: Boolean XOR.
  • ZAbs Intrinsic: Absolute value (archaic).
  • ZCos Intrinsic: Cosine (archaic).
  • ZExp Intrinsic: Exponential (archaic).

  • ZLog Intrinsic: Natural logarithm (archaic).
  • ZSin Intrinsic: Sine (archaic).
  • ZSqRt Intrinsic: Square root (archaic).


Node:Tabs, Next:Short Lines, Previous:Carriage Returns, Up:Source Form

Tabs

A source line with a <TAB> character anywhere in it is treated as entirely significant--however long it is--instead of ending in column 72 (for fixed-form source) or 132 (for free-form source). This also is different from f2c, which encodes tabs as \t (the ASCII <TAB> character) inside character and Hollerith constants, but nevertheless seems to treat the column position as if it had been affected by the canonical tab positioning.

g77 effectively translates tabs to the appropriate number of spaces (a la the default for the UNIX expand command) before doing any other processing, other than (currently) noting whether a tab was found on a line and using this information to decide how to interpret the length of the line and continued constants.


Node:Tan Intrinsic, Next:TanH Intrinsic, Previous:System_Clock Intrinsic, Up:Table of Intrinsic Functions

Tan Intrinsic

Tan(X)

Tan: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the tangent of X, an angle measured in radians.

See ATan Intrinsic, for the inverse of this function.


Node:TanD Intrinsic, Next:Time Intrinsic (VXT), Previous:System Intrinsic (function), Up:Other Intrinsics

TanD Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL TanD to use this name for an external procedure.


Node:TanH Intrinsic, Next:Time Intrinsic (UNIX), Previous:Tan Intrinsic, Up:Table of Intrinsic Functions

TanH Intrinsic

TanH(X)

TanH: REAL function, the KIND= value of the type being that of argument X.

X: REAL; scalar; INTENT(IN).

Intrinsic groups: (standard FORTRAN 77).

Description:

Returns the hyperbolic tangent of X.


Node:TBD (Transforming), Previous:Gotchas (Transforming), Up:Overview of Translation Process

TBD (Transforming)

Continue researching gotchas, designing the transformational process, and implementing it.

Specific issues to resolve:

  • Just where should (if it was implemented) USE processing take place?

    This gets into the whole issue of how g77 should handle the concept of modules. I think GNAT already takes on this issue, but don't know more than that. Jim Giles has written extensively on comp.lang.fortran about his opinions on module handling, as have others. Jim's views should be taken into account.

    Actually, Richard M. Stallman (RMS) also has written up some guidelines for implementing such things, but I'm not sure where I read them. Perhaps the old gcc2@cygnus.com list.

    If someone could dig references to these up and get them to me, that would be much appreciated! Even though modules are not on the short-term list for implementation, it'd be helpful to know now how to avoid making them harder to implement them later.

  • Should the g77 command become just a script that invokes all the various preprocessing that might be needed, thus making it seem slower than necessary for legacy code that people are unwilling to convert, or should we provide a separate script for that, thus encouraging people to convert their code once and for all?

    At least, a separate script to behave as old g77 did, perhaps named g77old, might ease the transition, as might a corresponding one that converts source codes named g77oldnew.

    These scripts would take all the pertinent options g77 used to take and run the appropriate filters, passing the results to g77 or just making new sources out of them (in a subdirectory, leaving the user to do the dirty deed of moving or copying them over the old sources).

  • Do other Fortran compilers provide a prefix syntax to govern the treatment of backslashes in CHARACTER (or Hollerith) constants?

    Knowing what other compilers provide would help.

  • Is it okay to drop support for the -fintrin-case-initcap, -fmatch-case-initcap, -fsymbol-case-initcap, and -fcase-initcap options?

    I've asked info-gnu-fortran@gnu.org for input on this. Not having to support these makes it easier to write the new front end, and might also avoid complicated its design.

    The consensus to date (1999-11-17) has been to drop this support. Can't recall anybody saying they're using it, in fact.


Node:Terms and Concepts, Next:Characters Lines Sequence, Previous:Notation Used, Up:Language

Fortran Terms and Concepts

(The following information augments or overrides the information in Chapter 2 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran language. Chapter 2 of that document otherwise serves as the basis for the relevant aspects of GNU Fortran.)

  • Syntactic Items:
  • Statements Comments Lines:
  • Scope of Names and Labels:


Node:Time Intrinsic (UNIX), Next:Time8 Intrinsic, Previous:TanH Intrinsic, Up:Table of Intrinsic Functions

Time Intrinsic (UNIX)

Time()

Time: INTEGER(KIND=1) function.

Intrinsic groups: unix.

Description:

Returns the current time encoded as an integer (in the manner of the UNIX function time(3)). This value is suitable for passing to CTIME, GMTIME, and LTIME.

This intrinsic is not fully portable, such as to systems with 32-bit INTEGER types but supporting times wider than 32 bits. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

See Time8 Intrinsic, for information on a similar intrinsic that might be portable to more GNU Fortran implementations, though to fewer Fortran compilers.

For information on other intrinsics with the same name: See Time Intrinsic (VXT).


Node:Time Intrinsic (VXT), Next:UMask Intrinsic (function), Previous:TanD Intrinsic, Up:Other Intrinsics

Time Intrinsic (VXT)

CALL Time(Time)

Time: CHARACTER*8; scalar; INTENT(OUT).

Intrinsic groups: vxt.

Description:

Returns in Time a character representation of the current time as obtained from ctime(3).

Programs making use of this intrinsic might not be Year 10000 (Y10K) compliant. For example, the date might appear, to such programs, to wrap around (change from a larger value to a smaller one) as of the Year 10000.

See FDate Intrinsic (subroutine), for an equivalent routine.

For information on other intrinsics with the same name: See Time Intrinsic (UNIX).


Node:Time8 Intrinsic, Next:Tiny Intrinsic, Previous:Time Intrinsic (UNIX), Up:Table of Intrinsic Functions

Time8 Intrinsic

Time8()

Time8: INTEGER(KIND=2) function.

Intrinsic groups: unix.

Description:

Returns the current time encoded as a long integer (in the manner of the UNIX function time(3)). This value is suitable for passing to CTIME, GMTIME, and LTIME.

Warning: this intrinsic does not increase the range of the timing values over that returned by time(3). On a system with a 32-bit time(3), TIME8 will return a 32-bit value, even though converted to an INTEGER(KIND=2) value. That means overflows of the 32-bit value can still occur. Therefore, the values returned by this intrinsic might be, or become, negative, or numerically less than previous values, during a single run of the compiled program.

No Fortran implementations other than GNU Fortran are known to support this intrinsic at the time of this writing. See Time Intrinsic (UNIX), for information on a similar intrinsic that might be portable to more Fortran compilers, though to fewer GNU Fortran implementations.


Node:Timer Wraparounds, Next:Year 2000 (Y2K) Problems, Up:Run-time Environment Limits

Timer Wraparounds

Intrinsics that return values computed from system timers, whether elapsed (wall-clock) timers, process CPU timers, or other kinds of timers, are prone to experiencing wrap-around errors (or returning wrapped-around values from successive calls) due to insufficient ranges offered by the underlying system's timers.

Some of the symptoms of such behaviors include apparently negative time being computed for a duration, an extremely short amount of time being computed for a long duration, and an extremely long amount of time being computed for a short duration.

See the following for intrinsics known to have potential problems in these areas on at least some systems: CPU_Time Intrinsic, DTime Intrinsic (function), DTime Intrinsic (subroutine), ETime Intrinsic (function), ETime Intrinsic (subroutine), MClock Intrinsic, MClock8 Intrinsic, Secnds Intrinsic, Second Intrinsic (function), Second Intrinsic (subroutine), System_Clock Intrinsic, Time Intrinsic (UNIX), Time Intrinsic (VXT), Time8 Intrinsic.


Node:Tiny Intrinsic, Next:Transfer Intrinsic, Previous:Time8 Intrinsic, Up:Table of Intrinsic Functions

Tiny Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Tiny to use this name for an external procedure.


Node:Trailing Comment, Next:Debug Line, Previous:Source Form, Up:Other Dialects

Trailing Comment

g77 supports use of /* to start a trailing comment. In the GNU Fortran language, ! is used for this purpose.

/* is not in the GNU Fortran language because the use of /* in a program might suggest to some readers that a block, not trailing, comment is started (and thus ended by */, not end of line), since that is the meaning of /* in C.

Also, such readers might think they can use // to start a trailing comment as an alternative to /*, but // already denotes concatenation, and such a "comment" might actually result in a program that compiles without error (though it would likely behave incorrectly).


Node:Transfer Intrinsic, Next:Transpose Intrinsic, Previous:Tiny Intrinsic, Up:Table of Intrinsic Functions

Transfer Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Transfer to use this name for an external procedure.


Node:Transforming Block IF, Next:Transforming SELECT CASE, Previous:Transforming Iterative DO, Up:Transforming Statements

Transforming Block IF

Consider:

SUBROUTINE X(A,B,C)
CHARACTER*(*) A, B, C
LOGICAL LFUNC

IF (LFUNC (A//B)) THEN
  CALL SUBR1
ELSE IF (LFUNC (A//C)) THEN
  CALL SUBR2
ELSE
  CALL SUBR3
END

The arguments to the two calls to LFUNC require dynamic allocation (at run time), but are not required during execution of the CALL statements.

So, the scopes of those temporaries must be within blocks inside the block corresponding to the Fortran IF block.

This cannot be represented "naturally" in vanilla C, nor in GBEL. The if, elseif, else, and endif constructs provided by both languages must, for a given if block, share the same C/GBE block.

Therefore, any temporaries needed during evaluation of expr while executing ELSE IF(expr) must either have been predeclared at the top of the corresponding IF block, or declared within a new block for that ELSE IF--a block that, since it cannot contain the else or else if itself (due to the above requirement), actually implements the rest of the IF block's ELSE IF and ELSE statements within an inner block.

The FFE takes the latter approach.


Node:Transforming DO WHILE, Next:Transforming Iterative DO, Previous:Statements Needing Temporaries, Up:Transforming Statements

Transforming DO WHILE

DO WHILE(expr) must be implemented so that temporaries needed to evaluate expr are generated just for the test, each time.

Consider how DO WHILE (A//B .NE. 'END'); ...; END DO is transformed:

for (;;)
  {
    int temp0;

    {
      char temp1[large];

      libg77_catenate (temp1, a, b);
      temp0 = libg77_ne (temp1, 'END');
    }

    if (! temp0)
      break;

    ...
  }

In this case, it seems like a time/space tradeoff between allocating and deallocating temp1 for each iteration and allocating it just once for the entire loop.

However, if temp1 is allocated just once for the entire loop, it could be the wrong size for subsequent iterations of that loop in cases like DO WHILE (A(I:J)//B .NE. 'END'), because the body of the loop might modify I or J.

So, the above implementation is used, though a more optimal one can be used in specific circumstances.


Node:Transforming Expressions, Next:Internal Naming Conventions, Previous:Transforming Statements, Up:Front End

Transforming Expressions

The interactions between statements, expressions, and subexpressions at program run time can be viewed as:

action(expr)

Here, action is the series of steps performed to effect the statement, and expr is the expression whose value is used by action.

Expanding the above shows a typical order of events at run time:

Evaluate expr
Perform action, using result of evaluation of expr
Clean up after evaluating expr

So, if evaluating expr requires allocating memory, that memory can be freed before performing action only if it is not needed to hold the result of evaluating expr. Otherwise, it must be freed no sooner than after action has been performed.

The above are recursive definitions, in the sense that they apply to subexpressions of expr.

That is, evaluating expr involves evaluating all of its subexpressions, performing the action that computes the result value of expr, then cleaning up after evaluating those subexpressions.

The recursive nature of this evaluation is implemented via recursive-descent transformation of the top-level statements, their expressions, their subexpressions, and so on.

However, that recursive-descent transformation is, due to the nature of the GBEL, focused primarily on generating a single stream of code to be executed at run time.

Yet, from the above, it's clear that multiple streams of code must effectively be simultaneously generated during the recursive-descent analysis of statements.

The primary stream implements the primary action items, while at least two other streams implement the evaluation and clean-up items.

Requirements imposed by expressions include:

  • Whether the caller needs to have a temporary ready to hold the value of the expression.
  • Other stuff???


Node:Transforming Iterative DO, Next:Transforming Block IF, Previous:Transforming DO WHILE, Up:Transforming Statements

Transforming Iterative DO

An iterative DO loop (one that specifies an iteration variable) is required by the Fortran standards to be implemented as though an iteration count is computed before entering the loop body, and that iteration count used to determine the number of times the loop body is to be performed (assuming the loop isn't cut short via GOTO or EXIT).

The FFE handles this by allocating a temporary variable to contain the computed number of iterations. Since this variable must be in a scope that includes the entire loop, a GBEL block is created for that loop, and the variable declared as belonging to the scope of that block.


Node:Transforming SELECT CASE, Previous:Transforming Block IF, Up:Transforming Statements

Transforming SELECT CASE

SELECT CASE poses a few interesting problems for code generation, if efficiency and frugal stack management are important.

Consider SELECT CASE (I('PREFIX'//A)), where A is CHARACTER*(*). In a case like this--basically, in any case where largish temporaries are needed to evaluate the expression--those temporaries should not be "live" during execution of any of the CASE blocks.

So, evaluation of the expression is best done within its own block, which in turn is within the SELECT CASE block itself (which contains the code for the CASE blocks as well, though each within their own block).

Otherwise, we'd have the rough equivalent of this pseudo-code:

{
  char temp[large];

  libg77_catenate (temp, 'prefix', a);

  switch (i (temp))
    {
    case 0:
      ...
    }
}

And that would leave temp[large] in scope during the CASE blocks (although a clever back end *could* see that it isn't referenced in them, and thus free that temp before executing the blocks).

So this approach is used instead:

{
  int temp0;

  {
    char temp1[large];

    libg77_catenate (temp1, 'prefix', a);
    temp0 = i (temp1);
  }

  switch (temp0)
    {
    case 0:
      ...
    }
}

Note how temp1 goes out of scope before starting the switch, thus making it easy for a back end to free it.

The problem that solution has, however, is with SELECT CASE('prefix'//A) (which is currently not supported).

Unless the GBEL is extended to support arbitrarily long character strings in its case facility, the FFE has to implement SELECT CASE on CHARACTER (probably excepting CHARACTER*1) using a cascade of if, elseif, else, and endif constructs in GBEL.

To prevent the (potentially large) temporary, needed to hold the selected expression itself ('prefix'//A), from being in scope during execution of the CASE blocks, two approaches are available:

  • Pre-evaluate all the CASE tests, producing an integer ordinal that is used, a la temp0 in the earlier example, as if SELECT CASE(temp0) had been written.

    Each corresponding CASE is replaced with CASE(i), where i is the ordinal for that case, determined while, or before, generating the cascade of if-related constructs to cope with CHARACTER selection.

  • Make temp0 above just large enough to hold the longest CASE string that'll actually be compared against the expression (in this case, 'prefix'//A).

    Since that length must be constant (because CASE expressions are all constant), it won't be so large, and, further, temp1 need not be dynamically allocated, since normal CHARACTER assignment can be used into the fixed-length temp0.

Both of these solutions require SELECT CASE implementation to be changed so all the corresponding CASE statements are seen during the actual code generation for SELECT CASE.


Node:Transforming Statements, Next:Transforming Expressions, Previous:Challenges Posed, Up:Front End

Transforming Statements

Most Fortran statements are given their own block, and, for temporary variables they might need, their own scope. (A block is what distinguishes { foo (); } from just foo (); in C. A scope is included with every such block, providing a distinct name space for local variables.)

Label definitions for the statement precede this block, so 10 PRINT *, I is handled more like fl10: { ... } than { fl10: ... } (where fl10 is just a notation meaning "Fortran Label 10" for the purposes of this document).

  • Statements Needing Temporaries:
  • Transforming DO WHILE:
  • Transforming Iterative DO:
  • Transforming Block IF:
  • Transforming SELECT CASE:


Node:Transpose Intrinsic, Next:Trim Intrinsic, Previous:Transfer Intrinsic, Up:Table of Intrinsic Functions

Transpose Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Transpose to use this name for an external procedure.


Node:Trim Intrinsic, Next:TtyNam Intrinsic (subroutine), Previous:Transpose Intrinsic, Up:Table of Intrinsic Functions

Trim Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Trim to use this name for an external procedure.


Node:TtyNam Intrinsic (function), Next:UBound Intrinsic, Previous:TtyNam Intrinsic (subroutine), Up:Table of Intrinsic Functions

TtyNam Intrinsic (function)

TtyNam(Unit)

TtyNam: CHARACTER*(*) function.

Unit: INTEGER; scalar; INTENT(IN).

Intrinsic groups: unix.

Description:

Returns the name of the terminal device open on logical unit Unit or a blank string if Unit is not connected to a terminal.

For information on other intrinsics with the same name: See TtyNam Intrinsic (subroutine).


Node:TtyNam Intrinsic (subroutine), Next:TtyNam Intrinsic (function), Previous:Trim Intrinsic, Up:Table of Intrinsic Functions

TtyNam Intrinsic (subroutine)

CALL TtyNam(Unit, Name)

Unit: INTEGER; scalar; INTENT(IN).

Name: CHARACTER; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Sets Name to the name of the terminal device open on logical unit Unit or to a blank string if Unit is not connected to a terminal.

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine.

For information on other intrinsics with the same name: See TtyNam Intrinsic (function).


Node:Two-pass Code, Next:Why Two Passes, Up:Two-pass Design

Two-pass Code

Most of the code that turns the first pass (parsing) into a second pass for code generation is in gcc/gcc/f/std.c.

It has external functions, called mainly by siblings in gcc/gcc/f/stc.c, that record the information on statements and expressions in the order they are seen in the source code. These functions save that information.

It also has an external function that revisits that information, calling the siblings in gcc/gcc/f/ste.c, which handles the actual code generation (by generating GBEL code, that is, by calling GBE routines to represent and specify expressions, statements, and so on).


Node:Two-pass Design, Next:Challenges Posed, Previous:Philosophy of Code Generation, Up:Front End

Two-pass Design

The FFE does not tell the GBE anything about a program unit until after the last statement in that unit has been parsed. (A program unit is a Fortran concept that corresponds, in the C world, mostly closely to functions definitions in ISO C. That is, a program unit in Fortran is like a top-level function in C. Nested functions, found among the extensions offered by GNU C, correspond roughly to Fortran's statement functions.)

So, while parsing the code in a program unit, the FFE saves up all the information on statements, expressions, names, and so on, until it has seen the last statement.

At that point, the FFE revisits the saved information (in what amounts to a second pass over the program unit) to perform the actual translation of the program unit into GBEL, ultimating in the generation of assembly code for it.

Some lookahead is performed during this second pass, so the FFE could be viewed as a "two-plus-pass" design.

  • Two-pass Code:
  • Why Two Passes:


Node:TYPE and ACCEPT I/O Statements, Next:STRUCTURE UNION RECORD MAP, Previous:Old-style PARAMETER Statements, Up:Missing Features

TYPE and ACCEPT I/O Statements

g77 doesn't support the I/O statements TYPE and ACCEPT. These are common extensions that should be easy to support, but also are fairly easy to work around in user code.

Generally, any TYPE fmt,list I/O statement can be replaced by PRINT fmt,list. And, any ACCEPT fmt,list statement can be replaced by READ fmt,list.


Node:Types, Next:Constants, Up:Data Types and Constants

Data Types

(Corresponds to Section 4.1 of ANSI X3.9-1978 FORTRAN 77.)

GNU Fortran supports these types:

  1. Integer (generic type INTEGER)
  2. Real (generic type REAL)
  3. Double precision
  4. Complex (generic type COMPLEX)
  5. Logical (generic type LOGICAL)
  6. Character (generic type CHARACTER)
  7. Double Complex

(The types numbered 1 through 6 above are standard FORTRAN 77 types.)

The generic types shown above are referred to in this document using only their generic type names. Such references usually indicate that any specific type (kind) of that generic type is valid.

For example, a context described in this document as accepting the COMPLEX type also is likely to accept the DOUBLE COMPLEX type.

The GNU Fortran language supports three ways to specify a specific kind of a generic type.

  • Double Notation: As in DOUBLE COMPLEX.
  • Star Notation: As in INTEGER*4.
  • Kind Notation: As in INTEGER(KIND=1).


Node:UBound Intrinsic, Next:UMask Intrinsic (subroutine), Previous:TtyNam Intrinsic (function), Up:Table of Intrinsic Functions

UBound Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL UBound to use this name for an external procedure.


Node:Ugly Assigned Labels, Previous:Ugly Integer Conversions, Up:Distensions

Ugly Assigned Labels

The -fugly-assign option forces g77 to use the same storage for assigned labels as it would for a normal assignment to the same variable.

For example, consider the following code fragment:

I = 3
ASSIGN 10 TO I

Normally, for portability and improved diagnostics, g77 reserves distinct storage for a "sibling" of I, used only for ASSIGN statements to that variable (along with the corresponding assigned-GOTO and assigned-FORMAT-I/O statements that reference the variable).

However, some code (that violates the ANSI FORTRAN 77 standard) attempts to copy assigned labels among variables involved with ASSIGN statements, as in:

ASSIGN 10 TO I
ISTATE(5) = I
...
J = ISTATE(ICUR)
GOTO J

Such code doesn't work under g77 unless -fugly-assign is specified on the command-line, ensuring that the value of I referenced in the second line is whatever value g77 uses to designate statement label 10, so the value may be copied into the ISTATE array, later retrieved into a variable of the appropriate type (J), and used as the target of an assigned-GOTO statement.

Note: To avoid subtle program bugs, when -fugly-assign is specified, g77 requires the type of variables specified in assigned-label contexts must be the same type returned by %LOC(). On many systems, this type is effectively the same as INTEGER(KIND=1), while, on others, it is effectively the same as INTEGER(KIND=2).

Do not depend on g77 actually writing valid pointers to these variables, however. While g77 currently chooses that implementation, it might be changed in the future.

See Assigned Statement Labels (ASSIGN and GOTO), for implementation details on assigned-statement labels.


Node:Ugly Assumed-Size Arrays, Next:Ugly Null Arguments, Previous:Ugly Implicit Argument Conversion, Up:Distensions

Ugly Assumed-Size Arrays

The -fugly-assumed option enables the treatment of any array with a final dimension specified as 1 as an assumed-size array, as if * had been specified instead.

For example, DIMENSION X(1) is treated as if it had read DIMENSION X(*) if X is listed as a dummy argument in a preceding SUBROUTINE, FUNCTION, or ENTRY statement in the same program unit.

Use an explicit lower bound to avoid this interpretation. For example, DIMENSION X(1:1) is never treated as if it had read DIMENSION X(*) or DIMENSION X(1:*). Nor is DIMENSION X(2-1) affected by this option, since that kind of expression is unlikely to have been intended to designate an assumed-size array.

This option is used to prevent warnings being issued about apparent out-of-bounds reference such as X(2) = 99.

It also prevents the array from being used in contexts that disallow assumed-size arrays, such as PRINT *,X. In such cases, a diagnostic is generated and the source file is not compiled.

The construct affected by this option is used only in old code that pre-exists the widespread acceptance of adjustable and assumed-size arrays in the Fortran community.

Note: This option does not affect how DIMENSION X(1) is treated if X is listed as a dummy argument only after the DIMENSION statement (presumably in an ENTRY statement). For example, -fugly-assumed has no effect on the following program unit:

SUBROUTINE X
REAL A(1)
RETURN
ENTRY Y(A)
PRINT *, A
END


Node:Ugly Complex Part Extraction, Next:Ugly Conversion of Initializers, Previous:Ugly Null Arguments, Up:Distensions

Ugly Complex Part Extraction

The -fugly-complex option enables use of the REAL() and AIMAG() intrinsics with arguments that are COMPLEX types other than COMPLEX(KIND=1).

With -ff90 in effect, these intrinsics return the unconverted real and imaginary parts (respectively) of their argument.

With -fno-f90 in effect, these intrinsics convert the real and imaginary parts to REAL(KIND=1), and return the result of that conversion.

Due to this ambiguity, the GNU Fortran language defines these constructs as invalid, except in the specific case where they are entirely and solely passed as an argument to an invocation of the REAL() intrinsic. For example,

REAL(REAL(Z))

is permitted even when Z is COMPLEX(KIND=2) and -fno-ugly-complex is in effect, because the meaning is clear.

g77 enforces this restriction, unless -fugly-complex is specified, in which case the appropriate interpretation is chosen and no diagnostic is issued.

See CMPAMBIG, for information on how to cope with existing code with unclear expectations of REAL() and AIMAG() with COMPLEX(KIND=2) arguments.

See RealPart Intrinsic, for information on the REALPART() intrinsic, used to extract the real part of a complex expression without conversion. See ImagPart Intrinsic, for information on the IMAGPART() intrinsic, used to extract the imaginary part of a complex expression without conversion.


Node:Ugly Conversion of Initializers, Next:Ugly Integer Conversions, Previous:Ugly Complex Part Extraction, Up:Distensions

Ugly Conversion of Initializers

The constructs disabled by -fno-ugly-init are:

  • Use of Hollerith and typeless constants in contexts where they set initial (compile-time) values for variables, arrays, and named constants--that is, DATA and PARAMETER statements, plus type-declaration statements specifying initial values.

    Here are some sample initializations that are disabled by the -fno-ugly-init option:

    PARAMETER (VAL='9A304FFE'X)
REAL*8 STRING/8HOUTPUT00/
DATA VAR/4HABCD/

  • In the same contexts as above, use of character constants to initialize numeric items and vice versa (one constant per item).

    Here are more sample initializations that are disabled by the -fno-ugly-init option:

    INTEGER IA
CHARACTER BELL
PARAMETER (IA = 'A')
PARAMETER (BELL = 7)

  • Use of Hollerith and typeless constants on the right-hand side of assignment statements to numeric types, and in other contexts (such as passing arguments in invocations of intrinsic procedures and statement functions) that are treated as assignments to known types (the dummy arguments, in these cases).

    Here are sample statements that are disabled by the -fno-ugly-init option:

    IVAR = 4HABCD
PRINT *, IMAX0(2HAB, 2HBA)

The above constructs, when used, can tend to result in non-portable code. But, they are widely used in existing Fortran code in ways that often are quite portable. Therefore, they are enabled by default.


Node:Ugly Implicit Argument Conversion, Next:Ugly Assumed-Size Arrays, Up:Distensions

Implicit Argument Conversion

The -fno-ugly-args option disables passing typeless and Hollerith constants as actual arguments in procedure invocations. For example:

CALL FOO(4HABCD)
CALL BAR('123'O)

These constructs can be too easily used to create non-portable code, but are not considered as "ugly" as others. Further, they are widely used in existing Fortran source code in ways that often are quite portable. Therefore, they are enabled by default.


Node:Ugly Integer Conversions, Next:Ugly Assigned Labels, Previous:Ugly Conversion of Initializers, Up:Distensions

Ugly Integer Conversions

The constructs enabled via -fugly-logint are:

  • Automatic conversion between INTEGER and LOGICAL as dictated by context (typically implies nonportable dependencies on how a particular implementation encodes .TRUE. and .FALSE.).
  • Use of a LOGICAL variable in ASSIGN and assigned-GOTO statements.

The above constructs are disabled by default because use of them tends to lead to non-portable code. Even existing Fortran code that uses that often turns out to be non-portable, if not outright buggy.

Some of this is due to differences among implementations as far as how .TRUE. and .FALSE. are encoded as INTEGER values--Fortran code that assumes a particular coding is likely to use one of the above constructs, and is also likely to not work correctly on implementations using different encodings.

See Equivalence Versus Equality, for more information.


Node:Ugly Null Arguments, Next:Ugly Complex Part Extraction, Previous:Ugly Assumed-Size Arrays, Up:Distensions

Ugly Null Arguments

The -fugly-comma option enables use of a single trailing comma to mean "pass an extra trailing null argument" in a list of actual arguments to an external procedure, and use of an empty list of arguments to such a procedure to mean "pass a single null argument".

(Null arguments often are used in some procedure-calling schemes to indicate omitted arguments.)

For example, CALL FOO(,) means "pass two null arguments", rather than "pass one null argument". Also, CALL BAR() means "pass one null argument".

This construct is considered "ugly" because it does not provide an elegant way to pass a single null argument that is syntactically distinct from passing no arguments. That is, this construct changes the meaning of code that makes no use of the construct.

So, with -fugly-comma in force, CALL FOO() and I = JFUNC() pass a single null argument, instead of passing no arguments as required by the Fortran 77 and 90 standards.

Note: Many systems gracefully allow the case where a procedure call passes one extra argument that the called procedure does not expect.

So, in practice, there might be no difference in the behavior of a program that does CALL FOO() or I = JFUNC() and is compiled with -fugly-comma in force as compared to its behavior when compiled with the default, -fno-ugly-comma, in force, assuming FOO and JFUNC do not expect any arguments to be passed.


Node:UMask Intrinsic (function), Next:Unlink Intrinsic (function), Previous:Time Intrinsic (VXT), Up:Other Intrinsics

UMask Intrinsic (function)

UMask(Mask)

UMask: INTEGER(KIND=1) function.

Mask: INTEGER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Sets the file creation mask to Mask and returns the old value. See umask(2).

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See UMask Intrinsic (subroutine).


Node:UMask Intrinsic (subroutine), Next:Unlink Intrinsic (subroutine), Previous:UBound Intrinsic, Up:Table of Intrinsic Functions

UMask Intrinsic (subroutine)

CALL UMask(Mask, Old)

Mask: INTEGER; scalar; INTENT(IN).

Old: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Sets the file creation mask to Mask and returns the old value in argument Old if it is supplied. See umask(2).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine.

For information on other intrinsics with the same name: See UMask Intrinsic (function).


Node:Underscores in Symbol Names, Up:Scope and Classes of Names

Underscores in Symbol Names

Underscores (_) are accepted in symbol names after the first character (which must be a letter).


Node:Uninitialized Variables at Run Time, Next:Portable Unformatted Files, Previous:Informational Messages, Up:Missing Features

Uninitialized Variables at Run Time

g77 needs an option to initialize everything (not otherwise explicitly initialized) to "weird" (machine-dependent) values, e.g. NaNs, bad (non-NULL) pointers, and largest-magnitude integers, would help track down references to some kinds of uninitialized variables at run time.

Note that use of the options -O -Wuninitialized can catch many such bugs at compile time.


Node:Unlink Intrinsic (function), Next:ZExt Intrinsic, Previous:UMask Intrinsic (function), Up:Other Intrinsics

Unlink Intrinsic (function)

Unlink(File)

Unlink: INTEGER(KIND=1) function.

File: CHARACTER; scalar; INTENT(IN).

Intrinsic groups: badu77.

Description:

Unlink the file File. A null character (CHAR(0)) marks the end of the name in File--otherwise, trailing blanks in File are ignored. Returns 0 on success or a non-zero error code. See unlink(2).

Due to the side effects performed by this intrinsic, the function form is not recommended.

For information on other intrinsics with the same name: See Unlink Intrinsic (subroutine).


Node:Unlink Intrinsic (subroutine), Next:Unpack Intrinsic, Previous:UMask Intrinsic (subroutine), Up:Table of Intrinsic Functions

Unlink Intrinsic (subroutine)

CALL Unlink(File, Status)

File: CHARACTER; scalar; INTENT(IN).

Status: INTEGER(KIND=1); OPTIONAL; scalar; INTENT(OUT).

Intrinsic groups: unix.

Description:

Unlink the file File. A null character (CHAR(0)) marks the end of the name in File--otherwise, trailing blanks in File are ignored. If the Status argument is supplied, it contains 0 on success or a non-zero error code upon return. See unlink(2).

Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) Status argument.

For information on other intrinsics with the same name: See Unlink Intrinsic (function).


Node:Unpack Intrinsic, Next:Verify Intrinsic, Previous:Unlink Intrinsic (subroutine), Up:Table of Intrinsic Functions

Unpack Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Unpack to use this name for an external procedure.


Node:Unused Arguments, Next:Surprising Interpretations of Code, Previous:Unwanted Variables, Up:Working Programs

Unused Arguments

As with unused variables, It is possible that unused arguments to a procedure might indicate a bug. Compile with -W -Wunused option to catch cases of unused arguments.

Note that -W also enables warnings regarding overflow of floating-point constants under certain circumstances.


Node:Unused Labels, Next:Informational Messages, Previous:Ambiguous Dialects, Up:Missing Features

Unused Labels

g77 should warn about unused labels when -Wunused is in effect.


Node:Unwanted Variables, Next:Unused Arguments, Previous:Variables Assumed To Be Saved, Up:Working Programs

Unwanted Variables

The -Wunused option can find bugs involving implicit typing, sometimes more easily than using -Wimplicit in code that makes heavy use of implicit typing. An unused variable or array might indicate that the spelling for its declaration is different from that of its intended uses.

Other than cases involving typos, unused variables rarely indicate actual bugs in a program. However, investigating such cases thoroughly has, on occasion, led to the discovery of code that had not been completely written--where the programmer wrote declarations as needed for the whole algorithm, wrote some or even most of the code for that algorithm, then got distracted and forgot that the job was not complete.


Node:Use Submodel Options, Previous:Avoid f2c Compatibility, Up:Faster Programs

Use Submodel Options

Using an appropriate -m option to generate specific code for your CPU may be worthwhile, though it may mean the executable won't run on other versions of the CPU that don't support the same instruction set. See Hardware Models and Configurations. For instance on an x86 system the compiler might have been built--as shown by g77 -v--for the target i386-pc-linux-gnu, i.e. an i386 CPU. In that case to generate code best optimized for a Pentium you could use the option -march=pentium.

For recent CPUs that don't have explicit support in the released version of gcc, it might still be possible to get improvements with certain -m options.

-fomit-frame-pointer can help performance on x86 systems and others. It will, however, inhibit debugging on the systems on which it is not turned on anyway by -O.


Node:Variables Assumed To Be Saved, Next:Unwanted Variables, Previous:Variables Assumed To Be Zero, Up:Working Programs

Variables Assumed To Be Saved

Many Fortran programs were developed on systems that saved the values of all, or some, variables and arrays across procedure calls. As a result, many of these programs depend, sometimes inadvertently, on being able to assign a value to a variable, perform a RETURN to a calling procedure, and, upon subsequent invocation, reference the previously assigned variable to obtain the value.

They expect this despite not using the SAVE statement to specify that the value in a variable is expected to survive procedure returns and calls. Depending on variables and arrays to retain values across procedure calls without using SAVE to require it violates the Fortran standards.

You can ask g77 to assume SAVE is specified for all relevant (local) variables and arrays by using the -fno-automatic option.

Note that a program that works better when compiled with the -fno-automatic option is almost certainly depending on not having to use the SAVE statement as required by the Fortran standard. It might be worthwhile finding such cases and fixing them, using techniques such as compiling with the -O -Wuninitialized options using g77.


Node:Variables Assumed To Be Zero, Next:Variables Assumed To Be Saved, Previous:Not My Type, Up:Working Programs

Variables Assumed To Be Zero

Many Fortran programs were developed on systems that provided automatic initialization of all, or some, variables and arrays to zero. As a result, many of these programs depend, sometimes inadvertently, on this behavior, though to do so violates the Fortran standards.

You can ask g77 for this behavior by specifying the -finit-local-zero option when compiling Fortran code. (You might want to specify -fno-automatic as well, to avoid code-size inflation for non-optimized compilations.)

Note that a program that works better when compiled with the -finit-local-zero option is almost certainly depending on a particular system's, or compiler's, tendency to initialize some variables to zero. It might be worthwhile finding such cases and fixing them, using techniques such as compiling with the -O -Wuninitialized options using g77.


Node:Verify Intrinsic, Next:XOr Intrinsic, Previous:Unpack Intrinsic, Up:Table of Intrinsic Functions

Verify Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL Verify to use this name for an external procedure.


Node:VXT Fortran, Next:Fortran 90, Previous:Case Sensitivity, Up:Other Dialects

VXT Fortran

g77 supports certain constructs that have different meanings in VXT Fortran than they do in the GNU Fortran language.

Generally, this manual uses the invented term VXT Fortran to refer VAX FORTRAN (circa v4). That compiler offered many popular features, though not necessarily those that are specific to the VAX processor architecture, the VMS operating system, or Digital Equipment Corporation's Fortran product line. (VAX and VMS probably are trademarks of Digital Equipment Corporation.)

An extension offered by a Digital Fortran product that also is offered by several other Fortran products for different kinds of systems is probably going to be considered for inclusion in g77 someday, and is considered a VXT Fortran feature.

The -fvxt option generally specifies that, where the meaning of a construct is ambiguous (means one thing in GNU Fortran and another in VXT Fortran), the VXT Fortran meaning is to be assumed.

  • Double Quote Meaning: "2000 as octal constant.
  • Exclamation Point: ! in column 6.


Node:Warn About Implicit Conversions, Next:Invalid Use of Hollerith Constant, Previous:Better Pedantic Compilation, Up:Missing Features

Warn About Implicit Conversions

g77 needs a -Wpromotions option to warn if source code appears to expect automatic, silent, and somewhat dangerous compiler-assisted conversion of REAL(KIND=1) constants to REAL(KIND=2) based on context.

For example, it would warn about cases like this:

DOUBLE PRECISION FOO
PARAMETER (TZPHI = 9.435784839284958)
FOO = TZPHI * 3D0


Node:Warning Options, Next:Debugging Options, Previous:Fortran Dialect Options, Up:Invoking G77

Options to Request or Suppress Warnings

Warnings are diagnostic messages that report constructions which are not inherently erroneous but which are risky or suggest there might have been an error.

You can request many specific warnings with options beginning -W, for example -Wimplicit to request warnings on implicit declarations. Each of these specific warning options also has a negative form beginning -Wno- to turn off warnings; for example, -Wno-implicit. This manual lists only one of the two forms, whichever is not the default.

These options control the amount and kinds of warnings produced by GNU Fortran:

-fsyntax-only
Check the code for syntax errors, but don't do anything beyond that.
-pedantic
Issue warnings for uses of extensions to ANSI FORTRAN 77. -pedantic also applies to C-language constructs where they occur in GNU Fortran source files, such as use of \e in a character constant within a directive like #include.

Valid ANSI FORTRAN 77 programs should compile properly with or without this option. However, without this option, certain GNU extensions and traditional Fortran features are supported as well. With this option, many of them are rejected.

Some users try to use -pedantic to check programs for strict ANSI conformance. They soon find that it does not do quite what they want--it finds some non-ANSI practices, but not all. However, improvements to g77 in this area are welcome.

-pedantic-errors
Like -pedantic, except that errors are produced rather than warnings.
-fpedantic
Like -pedantic, but applies only to Fortran constructs.
-w
Inhibit all warning messages.
-Wno-globals
Inhibit warnings about use of a name as both a global name (a subroutine, function, or block data program unit, or a common block) and implicitly as the name of an intrinsic in a source file.

Also inhibit warnings about inconsistent invocations and/or definitions of global procedures (function and subroutines). Such inconsistencies include different numbers of arguments and different types of arguments.

-Wimplicit
Warn whenever a variable, array, or function is implicitly declared. Has an effect similar to using the IMPLICIT NONE statement in every program unit. (Some Fortran compilers provide this feature by an option named -u or /WARNINGS=DECLARATIONS.)
-Wunused
Warn whenever a variable is unused aside from its declaration.
-Wuninitialized
Warn whenever an automatic variable is used without first being initialized.

These warnings are possible only in optimizing compilation, because they require data-flow information that is computed only when optimizing. If you don't specify -O, you simply won't get these warnings.

These warnings occur only for variables that are candidates for register allocation. Therefore, they do not occur for a variable whose address is taken, or whose size is other than 1, 2, 4 or 8 bytes. Also, they do not occur for arrays, even when they are in registers.

Note that there might be no warning about a variable that is used only to compute a value that itself is never used, because such computations may be deleted by data-flow analysis before the warnings are printed.

These warnings are made optional because GNU Fortran is not smart enough to see all the reasons why the code might be correct despite appearing to have an error. Here is one example of how this can happen:

SUBROUTINE DISPAT(J)
IF (J.EQ.1) I=1
IF (J.EQ.2) I=4
IF (J.EQ.3) I=5
CALL FOO(I)
END

If the value of J is always 1, 2 or 3, then I is always initialized, but GNU Fortran doesn't know this. Here is another common case:

SUBROUTINE MAYBE(FLAG)
LOGICAL FLAG
IF (FLAG) VALUE = 9.4
...
IF (FLAG) PRINT *, VALUE
END

This has no bug because VALUE is used only if it is set.

-Wall
The -Wunused and -Wuninitialized options combined. These are all the options which pertain to usage that we recommend avoiding and that we believe is easy to avoid. (As more warnings are added to g77 some might be added to the list enabled by -Wall.)

The remaining -W... options are not implied by -Wall because they warn about constructions that we consider reasonable to use, on occasion, in clean programs.

-Wsurprising
Warn about "suspicious" constructs that are interpreted by the compiler in a way that might well be surprising to someone reading the code. These differences can result in subtle, compiler-dependent (even machine-dependent) behavioral differences. The constructs warned about include:
  • Expressions having two arithmetic operators in a row, such as X*-Y. Such a construct is nonstandard, and can produce unexpected results in more complicated situations such as X**-Y*Z. g77 along with many other compilers, interprets this example differently than many programmers, and a few other compilers. Specifically, g77 interprets X**-Y*Z as (X**(-Y))*Z, while others might think it should be interpreted as X**(-(Y*Z)).

    A revealing example is the constant expression 2**-2*1., which g77 evaluates to .25, while others might evaluate it to 0., the difference resulting from the way precedence affects type promotion.

    (The -fpedantic option also warns about expressions having two arithmetic operators in a row.)

  • Expressions with a unary minus followed by an operand and then a binary operator other than plus or minus. For example, -2**2 produces a warning, because the precedence is -(2**2), yielding -4, not (-2)**2, which yields 4, and which might represent what a programmer expects.

    An example of an expression producing different results in a surprising way is -I*S, where I holds the value -2147483648 and S holds 0.5. On many systems, negating I results in the same value, not a positive number, because it is already the lower bound of what an INTEGER(KIND=1) variable can hold. So, the expression evaluates to a positive number, while the "expected" interpretation, (-I)*S, would evaluate to a negative number.

    Even cases such as -I*J produce warnings, even though, in most configurations and situations, there is no computational difference between the results of the two interpretations--the purpose of this warning is to warn about differing interpretations and encourage a better style of coding, not to identify only those places where bugs might exist in the user's code.

  • DO loops with DO variables that are not of integral type--that is, using REAL variables as loop control variables. Although such loops can be written to work in the "obvious" way, the way g77 is required by the Fortran standard to interpret such code is likely to be quite different from the way many programmers expect. (This is true of all DO loops, but the differences are pronounced for non-integral loop control variables.)

    See Loops, for more information.

-Werror
Make all warnings into errors.
-W
Turns on "extra warnings" and, if optimization is specified via -O, the -Wuninitialized option. (This might change in future versions of g77

"Extra warnings" are issued for:

  • Unused parameters to a procedure (when -Wunused also is specified).
  • Overflows involving floating-point constants (not available for certain configurations).

See Options to Request or Suppress Warnings, for information on more options offered by the GBE shared by g77 gcc and other GNU compilers.

Some of these have no effect when compiling programs written in Fortran:

-Wcomment
-Wformat
-Wparentheses
-Wswitch
-Wtraditional
-Wshadow
-Wid-clash-len
-Wlarger-than-len
-Wconversion
-Waggregate-return
-Wredundant-decls
These options all could have some relevant meaning for GNU Fortran programs, but are not yet supported.


Node:Warnings and Errors, Previous:Non-bugs, Up:Trouble

Warning Messages and Error Messages

The GNU compiler can produce two kinds of diagnostics: errors and warnings. Each kind has a different purpose:

  • Errors report problems that make it impossible to compile your program. GNU Fortran reports errors with the source file name, line number, and column within the line where the problem is apparent.
  • Warnings report other unusual conditions in your code that might indicate a problem, although compilation can (and does) proceed. Warning messages also report the source file name, line number, and column information, but include the text warning: to distinguish them from error messages.

Warnings might indicate danger points where you should check to make sure that your program really does what you intend; or the use of obsolete features; or the use of nonstandard features of GNU Fortran. Many warnings are issued only if you ask for them, with one of the -W options (for instance, -Wall requests a variety of useful warnings).

Note: Currently, the text of the line and a pointer to the column is printed in most g77 diagnostics.

See Options to Request or Suppress Warnings, for more detail on these and related command-line options.


Node:What is GNU Fortran?, Next:G77 and GCC, Previous:Getting Started, Up:Top

What is GNU Fortran?

GNU Fortran, or g77, is designed initially as a free replacement for, or alternative to, the UNIX f77 command. (Similarly, gcc is designed as a replacement for the UNIX cc command.)

g77 also is designed to fit in well with the other fine GNU compilers and tools.

Sometimes these design goals conflict--in such cases, resolution often is made in favor of fitting in well with Project GNU. These cases are usually identified in the appropriate sections of this manual.

As compilers, g77, gcc, and f77 share the following characteristics:

  • They read a user's program, stored in a file and containing instructions written in the appropriate language (Fortran, C, and so on). This file contains source code.
  • They translate the user's program into instructions a computer can carry out more quickly than it takes to translate the instructions in the first place. These instructions are called machine code--code designed to be efficiently translated and processed by a machine such as a computer. Humans usually aren't as good writing machine code as they are at writing Fortran or C, because it is easy to make tiny mistakes writing machine code. When writing Fortran or C, it is easy to make big mistakes.
  • They provide information in the generated machine code that can make it easier to find bugs in the program (using a debugging tool, called a debugger, such as gdb).
  • They locate and gather machine code already generated to perform actions requested by statements in the user's program. This machine code is organized into libraries and is located and gathered during the link phase of the compilation process. (Linking often is thought of as a separate step, because it can be directly invoked via the ld command. However, the g77 and gcc commands, as with most compiler commands, automatically perform the linking step by calling on ld directly, unless asked to not do so by the user.)
  • They attempt to diagnose cases where the user's program contains incorrect usages of the language. The diagnostics produced by the compiler indicate the problem and the location in the user's source file where the problem was first noticed. The user can use this information to locate and fix the problem. (Sometimes an incorrect usage of the language leads to a situation where the compiler can no longer make any sense of what follows--while a human might be able to--and thus ends up complaining about many "problems" it encounters that, in fact, stem from just one problem, usually the first one reported.)
  • They attempt to diagnose cases where the user's program contains a correct usage of the language, but instructs the computer to do something questionable. These diagnostics often are in the form of warnings, instead of the errors that indicate incorrect usage of the language.

How these actions are performed is generally under the control of the user. Using command-line options, the user can specify how persnickety the compiler is to be regarding the program (whether to diagnose questionable usage of the language), how much time to spend making the generated machine code run faster, and so on.

g77 consists of several components:

  • A modified version of the gcc command, which also might be installed as the system's cc command. (In many cases, cc refers to the system's "native" C compiler, which might be a non-GNU compiler, or an older version of gcc considered more stable or that is used to build the operating system kernel.)
  • The g77 command itself, which also might be installed as the system's f77 command.
  • The libg2c run-time library. This library contains the machine code needed to support capabilities of the Fortran language that are not directly provided by the machine code generated by the g77 compilation phase.

    libg2c is just the unique name g77 gives to its version of libf2c to distinguish it from any copy of libf2c installed from f2c (or versions of g77 that built libf2c under that same name) on the system.

    The maintainer of libf2c currently is dmg@bell-labs.com.

  • The compiler itself, internally named f771.

    Note that f771 does not generate machine code directly--it generates assembly code that is a more readable form of machine code, leaving the conversion to actual machine code to an assembler, usually named as.

gcc is often thought of as "the C compiler" only, but it does more than that. Based on command-line options and the names given for files on the command line, gcc determines which actions to perform, including preprocessing, compiling (in a variety of possible languages), assembling, and linking.

For example, the command gcc foo.c drives the file foo.c through the preprocessor cpp, then the C compiler (internally named cc1), then the assembler (usually as), then the linker (ld), producing an executable program named a.out (on UNIX systems).

As another example, the command gcc foo.cc would do much the same as gcc foo.c, but instead of using the C compiler named cc1, gcc would use the C++ compiler (named cc1plus).

In a GNU Fortran installation, gcc recognizes Fortran source files by name just like it does C and C++ source files. It knows to use the Fortran compiler named f771, instead of cc1 or cc1plus, to compile Fortran files.

Non-Fortran-related operation of gcc is generally unaffected by installing the GNU Fortran version of gcc. However, without the installed version of gcc being the GNU Fortran version, gcc will not be able to compile and link Fortran programs--and since g77 uses gcc to do most of the actual work, neither will g77!

The g77 command is essentially just a front-end for the gcc command. Fortran users will normally use g77 instead of gcc, because g77 knows how to specify the libraries needed to link with Fortran programs (libg2c and lm). g77 can still compile and link programs and source files written in other languages, just like gcc.

The command g77 -v is a quick way to display lots of version information for the various programs used to compile a typical preprocessed Fortran source file--this produces much more output than gcc -v currently does. (If it produces an error message near the end of the output--diagnostics from the linker, usually ld--you might have an out-of-date libf2c that improperly handles complex arithmetic.) In the output of this command, the line beginning GNU Fortran Front End identifies the version number of GNU Fortran; immediately preceding that line is a line identifying the version of gcc with which that version of g77 was built.

The libf2c library is distributed with GNU Fortran for the convenience of its users, but is not part of GNU Fortran. It contains the procedures needed by Fortran programs while they are running.

For example, while code generated by g77 is likely to do additions, subtractions, and multiplications in line--in the actual compiled code--it is not likely to do trigonometric functions this way.

Instead, operations like trigonometric functions are compiled by the f771 compiler (invoked by g77 when compiling Fortran code) into machine code that, when run, calls on functions in libg2c, so libg2c must be linked with almost every useful program having any component compiled by GNU Fortran. (As mentioned above, the g77 command takes care of all this for you.)

The f771 program represents most of what is unique to GNU Fortran. While much of the libg2c component comes from the libf2c component of f2c, a free Fortran-to-C converter distributed by Bellcore (AT&T), plus libU77, provided by Dave Love, and the g77 command is just a small front-end to gcc, f771 is a combination of two rather large chunks of code.

One chunk is the so-called GNU Back End, or GBE, which knows how to generate fast code for a wide variety of processors. The same GBE is used by the C, C++, and Fortran compiler programs cc1, cc1plus, and f771, plus others. Often the GBE is referred to as the "gcc back end" or even just "gcc"--in this manual, the term GBE is used whenever the distinction is important.

The other chunk of f771 is the majority of what is unique about GNU Fortran--the code that knows how to interpret Fortran programs to determine what they are intending to do, and then communicate that knowledge to the GBE for actual compilation of those programs. This chunk is called the Fortran Front End (FFE). The cc1 and cc1plus programs have their own front ends, for the C and C++ languages, respectively. These fronts ends are responsible for diagnosing incorrect usage of their respective languages by the programs the process, and are responsible for most of the warnings about questionable constructs as well. (The GBE handles producing some warnings, like those concerning possible references to undefined variables.)

Because so much is shared among the compilers for various languages, much of the behavior and many of the user-selectable options for these compilers are similar. For example, diagnostics (error messages and warnings) are similar in appearance; command-line options like -Wall have generally similar effects; and the quality of generated code (in terms of speed and size) is roughly similar (since that work is done by the shared GBE).


Node:Why Two Passes, Previous:Two-pass Code, Up:Two-pass Design

Why Two Passes

The need for two passes was not immediately evident during the design and implementation of the code in the FFE that was to produce GBEL. Only after a few kludges, to handle things like incorrectly-guessed ASSIGN label nature, had been implemented, did enough evidence pile up to make it clear that std.c had to be introduced to intercept, save, then revisit as part of a second pass, the digested contents of a program unit.

Other such missteps have occurred during the evolution of the FFE, because of the different goals of the FFE and the GBE.

Because the GBE's original, and still primary, goal was to directly support the GNU C language, the GBEL, and the GBE itself, requires more complexity on the part of most front ends than it requires of gcc's.

For example, the GBEL offers an interface that permits the gcc front end to implement most, or all, of the language features it supports, without the front end having to make use of non-user-defined variables. (It's almost certainly the case that all of K&R C, and probably ANSI C as well, is handled by the gcc front end without declaring such variables.)

The FFE, on the other hand, must resort to a variety of "tricks" to achieve its goals.

Consider the following C code:

int
foo (int a, int b)
{
  int c = 0;

  if ((c = bar (c)) == 0)
    goto done;

  quux (c << 1);

done:
  return c;
}

Note what kinds of objects are declared, or defined, before their use, and before any actual code generation involving them would normally take place:

  • Return type of function
  • Entry point(s) of function
  • Dummy arguments
  • Variables
  • Initial values for variables

Whereas, the following items can, and do, suddenly appear "out of the blue" in C:

  • Label references
  • Function references

Not surprisingly, the GBE faithfully permits the latter set of items to be "discovered" partway through GBEL "programs", just as they are permitted to in C.

Yet, the GBE has tended, at least in the past, to be reticent to fully support similar "late" discovery of items in the former set.

This makes Fortran a poor fit for the "safe" subset of GBEL. Consider:

      FUNCTION X (A, ARRAY, ID1)
      CHARACTER*(*) A
      DOUBLE PRECISION X, Y, Z, TMP, EE, PI
      REAL ARRAY(ID1*ID2)
      COMMON ID2
      EXTERNAL FRED

      ASSIGN 100 TO J
      CALL FOO (I)
      IF (I .EQ. 0) PRINT *, A(0)
      GOTO 200

      ENTRY Y (Z)
      ASSIGN 101 TO J
200   PRINT *, A(1)
      READ *, TMP
      GOTO J
100   X = TMP * EE
      RETURN
101   Y = TMP * PI
      CALL FRED
      DATA EE, PI /2.71D0, 3.14D0/
      END

Here are some observations about the above code, which, while somewhat contrived, conforms to the FORTRAN 77 and Fortran 90 standards:

  • The return type of function X is not known until the DOUBLE PRECISION line has been parsed.
  • Whether A is a function or a variable is not known until the PRINT *, A(0) statement has been parsed.
  • The bounds of the array of argument ARRAY depend on a computation involving the subsequent argument ID1 and the blank-common member ID2.
  • Whether Y and Z are local variables, additional function entry points, or dummy arguments to additional entry points is not known until the ENTRY statement is parsed.
  • Similarly, whether TMP is a local variable is not known until the READ *, TMP statement is parsed.
  • The initial values for EE and PI are not known until after the DATA statement is parsed.
  • Whether FRED is a function returning type REAL or a subroutine (which can be thought of as returning type void or, to support alternate returns in a simple way, type int) is not known until the CALL FRED statement is parsed.
  • Whether 100 is a FORMAT label or the label of an executable statement is not known until the X = statement is parsed. (These two types of labels get very different treatment, especially when ASSIGN'ed.)
  • That J is a local variable is not known until the first ASSIGN statement is parsed. (This happens after executable code has been seen.)

Very few of these "discoveries" can be accommodated by the GBE as it has evolved over the years. The GBEL doesn't support several of them, and those it might appear to support don't always work properly, especially in combination with other GBEL and GBE features, as implemented in the GBE.

(Had the GBE and its GBEL originally evolved to support g77, the shoe would be on the other foot, so to speak--most, if not all, of the above would be directly supported by the GBEL, and a few C constructs would probably not, as they are in reality, be supported. Both this mythical, and today's real, GBE caters to its GBEL by, sometimes, scrambling around, cleaning up after itself--after discovering that assumptions it made earlier during code generation are incorrect. That's not a great design, since it indicates significant code paths that might be rarely tested but used in some key production environments.)

So, the FFE handles these discrepancies--between the order in which it discovers facts about the code it is compiling, and the order in which the GBEL and GBE support such discoveries--by performing what amounts to two passes over each program unit.

(A few ambiguities can remain at that point, such as whether, given EXTERNAL BAZ and no other reference to BAZ in the program unit, it is a subroutine, a function, or a block-data--which, in C-speak, governs its declared return type. Fortunately, these distinctions are easily finessed for the procedure, library, and object-file interfaces supported by g77.)


Node:Working Programs, Next:Overly Convenient Options, Previous:Loops, Up:Collected Fortran Wisdom

Working Programs

Getting Fortran programs to work in the first place can be quite a challenge--even when the programs already work on other systems, or when using other compilers.

g77 offers some facilities that might be useful for tracking down bugs in such programs.

  • Not My Type:
  • Variables Assumed To Be Zero:
  • Variables Assumed To Be Saved:
  • Unwanted Variables:
  • Unused Arguments:
  • Surprising Interpretations of Code:
  • Aliasing Assumed To Work:
  • Output Assumed To Flush:
  • Large File Unit Numbers:
  • Floating-point precision:
  • Inconsistent Calling Sequences:


Node:XOr Intrinsic, Next:ZAbs Intrinsic, Previous:Verify Intrinsic, Up:Table of Intrinsic Functions

XOr Intrinsic

XOr(I, J)

XOr: INTEGER or LOGICAL function, the exact type being the result of cross-promoting the types of all the arguments.

I: INTEGER or LOGICAL; scalar; INTENT(IN).

J: INTEGER or LOGICAL; scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Returns value resulting from boolean exclusive-OR of pair of bits in each of I and J.


Node:Y2KBAD, Previous:LINKFAIL, Up:Diagnostics

Y2KBAD

Intrinsic `name', invoked at (^), known to be non-Y2K-compliant...

This diagnostic indicates that the specific intrinsic invoked by the name name is known to have an interface that is not Year-2000 (Y2K) compliant.

See Year 2000 (Y2K) Problems.


Node:Year 10000 (Y10K) Problems, Previous:Character-variable Length, Up:Run-time Environment Limits

Year 10000 (Y10K) Problems

Most intrinsics returning, or computing values based on, date information are prone to Year-10000 (Y10K) problems, due to supporting only 4 digits for the year.

See the following for examples: FDate Intrinsic (function), FDate Intrinsic (subroutine), IDate Intrinsic (UNIX), Time Intrinsic (VXT), Date_and_Time Intrinsic.


Node:Year 2000 (Y2K) Problems, Next:Array Size, Previous:Timer Wraparounds, Up:Run-time Environment Limits

Year 2000 (Y2K) Problems

While the g77 compiler itself is believed to be Year-2000 (Y2K) compliant, some intrinsics are not, and, potentially, some underlying systems are not, perhaps rendering some Y2K-compliant intrinsics non-compliant when used on those particular systems.

Fortran code that uses non-Y2K-compliant intrinsics (listed below) is, itself, almost certainly not compliant, and should be modified to use Y2K-compliant intrinsics instead.

Fortran code that uses no non-Y2K-compliant intrinsics, but which currently is running on a non-Y2K-compliant system, can be made more Y2K compliant by compiling and linking it for use on a new Y2K-compliant system, such as a new version of an old, non-Y2K-compliant, system.

Currently, information on Y2K and related issues is being maintained at http://www.gnu.org/software/year2000-list.html.

See the following for intrinsics known to have potential problems in these areas on at least some systems: Date Intrinsic, IDate Intrinsic (VXT).

The libg2c library shipped with any g77 that warns about invocation of a non-Y2K-compliant intrinsic has renamed the EXTERNAL procedure names of those intrinsics. This is done so that the libg2c implementations of these intrinsics cannot be directly linked to as EXTERNAL names (which normally would avoid the non-Y2K-intrinsic warning).

The renamed forms of the EXTERNAL names of these renamed procedures may be linked to by appending the string _y2kbug to the name of the procedure in the source code. For example:

CHARACTER*20 STR
INTEGER YY, MM, DD
EXTERNAL DATE_Y2KBUG, VXTIDATE_Y2KBUG
CALL DATE_Y2KBUG (STR)
CALL VXTIDATE_Y2KBUG (MM, DD, YY)

(Note that the EXTERNAL statement is not actually required, since the modified names are not recognized as intrinsics by the current version of g77. But it is shown in this specific case, for purposes of illustration.)

The renaming of EXTERNAL procedure names of these intrinsics causes unresolved references at link time. For example, EXTERNAL DATE; CALL DATE(STR) is normally compiled by g77 as, in C, date_(&str, 20);. This, in turn, links to the date_ procedure in the libE77 portion of libg2c, which purposely calls a nonexistent procedure named G77_date_y2kbuggy_0. The resulting link-time error is designed, via this name, to encourage the programmer to look up the index entries to this portion of the g77 documentation.

Generally, we recommend that the EXTERNAL method of invoking procedures in libg2c not be used. When used, some of the correctness checking normally performed by g77 is skipped.

In particular, it is probably better to use the INTRINSIC method of invoking non-Y2K-compliant procedures, so anyone compiling the code can quickly notice the potential Y2K problems (via the warnings printing by g77) without having to even look at the code itself.

If there are problems linking libg2c to code compiled by g77 that involve the string y2kbug, and these are not explained above, that probably indicates that a version of libg2c older than g77 is being linked to, or that the new library is being linked to code compiled by an older version of g77.

That's because, as of the version that warns about non-Y2K-compliant intrinsic invocation, g77 references the libg2c implementations of those intrinsics using new names, containing the string y2kbug.

So, linking newly-compiled code (invoking one of the intrinsics in question) to an old library might yield an unresolved reference to G77_date_y2kbug_0. (The old library calls it G77_date_0.)

Similarly, linking previously-compiled code to a new library might yield an unresolved reference to G77_vxtidate_0. (The new library calls it G77_vxtidate_y2kbug_0.)

The proper fix for the above problems is to obtain the latest release of g77 and related products (including libg2c) and install them on all systems, then recompile, relink, and install (as appropriate) all existing Fortran programs.

(Normally, this sort of renaming is steadfastly avoided. In this case, however, it seems more important to highlight potential Y2K problems than to ease the transition of potentially non-Y2K-compliant code to new versions of g77 and libg2c.)


Node:ZAbs Intrinsic, Next:ZCos Intrinsic, Previous:XOr Intrinsic, Up:Table of Intrinsic Functions

ZAbs Intrinsic

ZAbs(A)

ZAbs: REAL(KIND=2) function.

A: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Archaic form of ABS() that is specific to one type for A. See Abs Intrinsic.


Node:ZCos Intrinsic, Next:ZExp Intrinsic, Previous:ZAbs Intrinsic, Up:Table of Intrinsic Functions

ZCos Intrinsic

ZCos(X)

ZCos: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Archaic form of COS() that is specific to one type for X. See Cos Intrinsic.


Node:ZExp Intrinsic, Next:ZLog Intrinsic, Previous:ZCos Intrinsic, Up:Table of Intrinsic Functions

ZExp Intrinsic

ZExp(X)

ZExp: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Archaic form of EXP() that is specific to one type for X. See Exp Intrinsic.


Node:ZExt Intrinsic, Previous:Unlink Intrinsic (function), Up:Other Intrinsics

ZExt Intrinsic

This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use EXTERNAL ZExt to use this name for an external procedure.


Node:ZLog Intrinsic, Next:ZSin Intrinsic, Previous:ZExp Intrinsic, Up:Table of Intrinsic Functions

ZLog Intrinsic

ZLog(X)

ZLog: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Archaic form of LOG() that is specific to one type for X. See Log Intrinsic.


Node:ZSin Intrinsic, Next:ZSqRt Intrinsic, Previous:ZLog Intrinsic, Up:Table of Intrinsic Functions

ZSin Intrinsic

ZSin(X)

ZSin: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Archaic form of SIN() that is specific to one type for X. See Sin Intrinsic.


Node:ZSqRt Intrinsic, Previous:ZSin Intrinsic, Up:Table of Intrinsic Functions

ZSqRt Intrinsic

ZSqRt(X)

ZSqRt: COMPLEX(KIND=2) function.

X: COMPLEX(KIND=2); scalar; INTENT(IN).

Intrinsic groups: f2c.

Description:

Archaic form of SQRT() that is specific to one type for X. See SqRt Intrinsic.


Guide to GNU gcj

Table of Contents

  • Introduction
  • GNU GENERAL PUBLIC LICENSE
    • Preamble
    • How to Apply These Terms to Your New Programs
  • GNU Free Documentation License
    • ADDENDUM: How to use this License for your documents
  • Invoking gcj
    • Input and output files
    • Input Options
    • Encodings
    • Warnings
    • Code Generation
    • Configure-time Options
  • Compatibility with the Java Platform
  • Invoking gcjh
  • Invoking jv-scan
  • Invoking jcf-dump
  • Invoking gij
  • Invoking jv-convert
  • Invoking rmic
  • Invoking rmiregistry
  • About CNI
    • Basic concepts
      • Limitations
    • Packages
      • Leaving out package names
    • Primitive types
      • Reference types associated with primitive types
    • Interfaces
    • Objects and Classes
      • Classes
      • Object fields
      • Access specifiers
    • Class Initialization
    • Object allocation
    • Arrays
      • Creating arrays
    • Methods
      • Overloading
      • Static methods
      • Object Constructors
      • Instance methods
      • Interface methods
    • Strings
    • Interoperating with C/C++
    • Exception Handling
    • Synchronization
    • Invocation
      • Handling uncaught exceptions
      • Example
    • Reflection
  • Resources

Node:Top, Next:Copying, Up:(dir)

Introduction

This manual describes how to use gcj, the GNU compiler for the Java programming language. gcj can generate both .class files and object files, and it can read both Java source code and .class files.

  • Copying: The GNU General Public License
  • GNU Free Documentation License: How you can share and copy this manual
  • Invoking gcj: Compiler options supported by gcj
  • Compatibility: Compatibility between gcj and other tools for Java
  • Invoking gcjh: Generate header files from class files
  • Invoking jv-scan: Print information about source files
  • Invoking jcf-dump: Print information about class files
  • Invoking gij: Interpreting Java bytecodes
  • Invoking jv-convert: Converting from one encoding to another
  • Invoking rmic: Generate stubs for Remote Method Invocation.
  • Invoking rmiregistry: The remote object registry.
  • About CNI: Description of the Cygnus Native Interface
  • Resources: Where to look for more information


Guide to GNU gcj

Node:About CNI, Next:Resources, Previous:Invoking rmiregistry, Up:Top

About CNI

This documents CNI, the Cygnus Native Interface, which is is a convenient way to write Java native methods using C++. This is a more efficient, more convenient, but less portable alternative to the standard JNI (Java Native Interface).

  • Basic concepts: Introduction to using CNI.
  • Packages: How packages are mapped to C++.
  • Primitive types: Handling Java types in C++.
  • Interfaces: How Java interfaces map to C++.
  • Objects and Classes: C++ and Java classes.
  • Class Initialization: How objects are initialized.
  • Object allocation: How to create Java objects in C++.
  • Arrays: Dealing with Java arrays in C++.
  • Methods: Java methods in C++.
  • Strings: Information about Java Strings.
  • Mixing with C++: How CNI can interoperate with C++.
  • Exception Handling: How exceptions are handled.
  • Synchronization: Synchronizing between Java and C++.
  • Invocation: Starting the Java runtime from C++.
  • Reflection: Using reflection from C++.


Guide to GNU gcj

Node:Arrays, Next:Methods, Previous:Object allocation, Up:About CNI

Arrays

While in many ways Java is similar to C and C++, it is quite different in its treatment of arrays. C arrays are based on the idea of pointer arithmetic, which would be incompatible with Java's security requirements. Java arrays are true objects (array types inherit from java.lang.Object). An array-valued variable is one that contains a reference (pointer) to an array object.

Referencing a Java array in C++ code is done using the JArray template, which as defined as follows:

class __JArray : public java::lang::Object
{
public:
  int length;
};

template<class T>
class JArray : public __JArray
{
  T data[0];
public:
  T& operator[](jint i) { return data[i]; }
};

There are a number of typedefs which correspond to typedefs from the JNI. Each is the type of an array holding objects of the relevant type:

typedef __JArray *jarray;
typedef JArray<jobject> *jobjectArray;
typedef JArray<jboolean> *jbooleanArray;
typedef JArray<jbyte> *jbyteArray;
typedef JArray<jchar> *jcharArray;
typedef JArray<jshort> *jshortArray;
typedef JArray<jint> *jintArray;
typedef JArray<jlong> *jlongArray;
typedef JArray<jfloat> *jfloatArray;
typedef JArray<jdouble> *jdoubleArray;

T* elements (JArray array) Method on template<class T>
This template function can be used to get a pointer to the elements of the array. For instance, you can fetch a pointer to the integers that make up an int[] like so:
extern jintArray foo;
jint *intp = elements (foo);

The name of this function may change in the future.

jobjectArray JvNewObjectArray (jsize length, jclass klass, jobject init) Function
Here klass is the type of elements of the array and init is the initial value put into every slot in the array.

Creating arrays

For each primitive type there is a function which can be used to create a new array of that type. The name of the function is of the form:

JvNewTypeArray

For example:

JvNewBooleanArray

can be used to create an array of Java primitive boolean types.

The following function definition is the template for all such functions:

jbooleanArray JvNewBooleanArray (jint length) Function
Create's an array length indices long.

jsize JvGetArrayLength (jarray array) Function
Returns the length of the array.


Guide to GNU gcj

Node:Basic concepts, Next:Packages, Up:About CNI

Basic concepts

In terms of languages features, Java is mostly a subset of C++. Java has a few important extensions, plus a powerful standard class library, but on the whole that does not change the basic similarity. Java is a hybrid object-oriented language, with a few native types, in addition to class types. It is class-based, where a class may have static as well as per-object fields, and static as well as instance methods. Non-static methods may be virtual, and may be overloaded. Overloading is resolved at compile time by matching the actual argument types against the parameter types. Virtual methods are implemented using indirect calls through a dispatch table (virtual function table). Objects are allocated on the heap, and initialized using a constructor method. Classes are organized in a package hierarchy.

All of the listed attributes are also true of C++, though C++ has extra features (for example in C++ objects may be allocated not just on the heap, but also statically or in a local stack frame). Because gcj uses the same compiler technology as G++ (the GNU C++ compiler), it is possible to make the intersection of the two languages use the same ABI (object representation and calling conventions). The key idea in CNI is that Java objects are C++ objects, and all Java classes are C++ classes (but not the other way around). So the most important task in integrating Java and C++ is to remove gratuitous incompatibilities.

You write CNI code as a regular C++ source file. (You do have to use a Java/CNI-aware C++ compiler, specifically a recent version of G++.)

A CNI C++ source file must have:

#include <gcj/cni.h>

and then must include one header file for each Java class it uses, e.g.:

#include <java/lang/Character.h>
#include <java/util/Date.h>
#include <java/lang/IndexOutOfBoundsException.h>

These header files are automatically generated by gcjh.

CNI provides some functions and macros to make using Java objects and primitive types from C++ easier. In general, these CNI functions and macros start with the Jv prefix, for example the function JvNewObjectArray. This convention is used to avoid conflicts with other libraries. Internal functions in CNI start with the prefix _Jv_. You should not call these; if you find a need to, let us know and we will try to come up with an alternate solution. (This manual lists _Jv_AllocBytes as an example; CNI should instead provide a JvAllocBytes function.)

Limitations

Whilst a Java class is just a C++ class that doesn't mean that you are freed from the shackles of Java, a CNI C++ class must adhere to the rules of the Java programming language.

For example: it is not possible to declare a method in a CNI class that will take a C string (char*) as an argument, or to declare a member variable of some non-Java datatype.


Guide to GNU gcj

Node:Class Initialization, Next:Object allocation, Previous:Objects and Classes, Up:About CNI

Class Initialization

Java requires that each class be automatically initialized at the time of the first active use. Initializing a class involves initializing the static fields, running code in class initializer methods, and initializing base classes. There may also be some implementation specific actions, such as allocating String objects corresponding to string literals in the code.

The GCJ compiler inserts calls to JvInitClass at appropriate places to ensure that a class is initialized when required. The C++ compiler does not insert these calls automatically--it is the programmer's responsibility to make sure classes are initialized. However, this is fairly painless because of the conventions assumed by the Java system.

First, libgcj will make sure a class is initialized before an instance of that object is created. This is one of the responsibilities of the new operation. This is taken care of both in Java code, and in C++ code. (When the G++ compiler sees a new of a Java class, it will call a routine in libgcj to allocate the object, and that routine will take care of initializing the class.) It follows that you can access an instance field, or call an instance (non-static) method and be safe in the knowledge that the class and all of its base classes have been initialized.

Invoking a static method is also safe. This is because the Java compiler adds code to the start of a static method to make sure the class is initialized. However, the C++ compiler does not add this extra code. Hence, if you write a native static method using CNI, you are responsible for calling JvInitClass before doing anything else in the method (unless you are sure it is safe to leave it out).

Accessing a static field also requires the class of the field to be initialized. The Java compiler will generate code to call Jv_InitClass before getting or setting the field. However, the C++ compiler will not generate this extra code, so it is your responsibility to make sure the class is initialized before you access a static field from C++.


Guide to GNU gcj

Node:Code Generation, Next:Configure-time Options, Previous:Warnings, Up:Invoking gcj

Code Generation

In addition to the many gcc options controlling code generation, gcj has several options specific to itself.

--main=CLASSNAME
This option is used when linking to specify the name of the class whose main method should be invoked when the resulting executable is run. 1
-Dname[=value]
This option can only be used with --main. It defines a system property named name with value value. If value is not specified then it defaults to the empty string. These system properties are initialized at the program's startup and can be retrieved at runtime using the java.lang.System.getProperty method.
-C
This option is used to tell gcj to generate bytecode (.class files) rather than object code.
--resource resource-name
This option is used to tell gcj to compile the contents of a given file to object code so it may be accessed at runtime with the core protocol handler as core:/resource-name. Note that resource-name is the name of the resource as found at runtime; for instance, it could be used in a call to ResourceBundle.getBundle. The actual file name to be compiled this way must be specified separately.
-d directory
When used with -C, this causes all generated .class files to be put in the appropriate subdirectory of directory. By default they will be put in subdirectories of the current working directory.
-fno-bounds-check
By default, gcj generates code which checks the bounds of all array indexing operations. With this option, these checks are omitted, which can improve performance for code that uses arrays extensively. Note that this can result in unpredictable behavior if the code in question actually does violate array bounds constraints. It is safe to use this option if you are sure that your code will never throw an ArrayIndexOutOfBoundsException.
-fno-store-check
Don't generate array store checks. When storing objects into arrays, a runtime check is normally generated in order to ensure that the object is assignment compatible with the component type of the array (which may not be known at compile-time). With this option, these checks are omitted. This can improve performance for code which stores objects into arrays frequently. It is safe to use this option if you are sure your code will never throw an ArrayStoreException.
-fjni
With gcj there are two options for writing native methods: CNI and JNI. By default gcj assumes you are using CNI. If you are compiling a class with native methods, and these methods are implemented using JNI, then you must use -fjni. This option causes gcj to generate stubs which will invoke the underlying JNI methods.
-fno-optimize-static-class-initialization
When the optimization level is greather or equal to -O2, gcj will try to optimize the way calls into the runtime are made to initialize static classes upon their first use (this optimization isn't carried out if -C was specified.) When compiling to native code, -fno-optimize-static-class-initialization will turn this optimization off, regardless of the optimization level in use.

Footnotes

  1. The linker by default looks for a global function named main. Since Java does not have global functions, and a collection of Java classes may have more than one class with a main method, you need to let the linker know which of those main methods it should invoke when starting the application.


Guide to GNU gcj

Node:Compatibility, Next:Invoking gcjh, Previous:Invoking gcj, Up:Top

Compatibility with the Java Platform

As we believe it is important that the Java platform not be fragmented, gcj and libgcj try to conform to the relevant Java specifications. However, limited manpower and incomplete and unclear documentation work against us. So, there are caveats to using gcj.

This list of compatibility issues is by no means complete.

  • gcj implements the JDK 1.1 language. It supports inner classes, though these are known to still be buggy. It does not yet support the Java 2 strictfp keyword (it recognizes the keyword but ignores it).
  • libgcj is largely compatible with the JDK 1.2 libraries. However, libgcj is missing many packages, most notably java.awt. There are also individual missing classes and methods. We currently do not have a list showing differences between libgcj and the Java 2 platform.
  • Sometimes the libgcj implementation of a method or class differs from the JDK implementation. This is not always a bug. Still, if it affects you, it probably makes sense to report it so that we can discuss the appropriate response.


Guide to GNU gcj

Node:Configure-time Options, Previous:Code Generation, Up:Invoking gcj

Configure-time Options

Some gcj code generations options affect the resulting ABI, and so can only be meaningfully given when libgcj, the runtime package, is configured. libgcj puts the appropriate options from this group into a spec file which is read by gcj. These options are listed here for completeness; if you are using libgcj then you won't want to touch these options.

-fuse-boehm-gc
This enables the use of the Boehm GC bitmap marking code. In particular this causes gcj to put an object marking descriptor into each vtable.
-fhash-synchronization
By default, synchronization data (the data used for synchronize, wait, and notify) is pointed to by a word in each object. With this option gcj assumes that this information is stored in a hash table and not in the object itself.
-fuse-divide-subroutine
On some systems, a library routine is called to perform integer division. This is required to get exception handling correct when dividing by zero.
-fcheck-references
On some systems it's necessary to insert inline checks whenever accessing an object via a reference. On other systems you won't need this because null pointer accesses are caught automatically by the processor.


Guide to GNU gcj

Node:Copying, Next:GNU Free Documentation License, Previous:Top, Up:Top

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
    NO WARRANTY
  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) year  name of author

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.


Guide to GNU gcj

Node:Encodings, Next:Warnings, Previous:Input Options, Up:Invoking gcj

Encodings

The Java programming language uses Unicode throughout. In an effort to integrate well with other locales, gcj allows .java files to be written using almost any encoding. gcj knows how to convert these encodings into its internal encoding at compile time.

You can use the --encoding=NAME option to specify an encoding (of a particular character set) to use for source files. If this is not specified, the default encoding comes from your current locale. If your host system has insufficient locale support, then gcj assumes the default encoding to be the UTF-8 encoding of Unicode.

To implement --encoding, gcj simply uses the host platform's iconv conversion routine. This means that in practice gcj is limited by the capabilities of the host platform.

The names allowed for the argument --encoding vary from platform to platform (since they are not standardized anywhere). However, gcj implements the encoding named UTF-8 internally, so if you choose to use this for your source files you can be assured that it will work on every host.


Guide to GNU gcj

Node:Exception Handling, Next:Synchronization, Previous:Mixing with C++, Up:About CNI

Exception Handling

While C++ and Java share a common exception handling framework, things are not yet perfectly integrated. The main issue is that the run-time type information facilities of the two languages are not integrated.

Still, things work fairly well. You can throw a Java exception from C++ using the ordinary throw construct, and this exception can be caught by Java code. Similarly, you can catch an exception thrown from Java using the C++ catch construct.

Here is an example:

if (i >= count)
   throw new java::lang::IndexOutOfBoundsException();

Normally, G++ will automatically detect when you are writing C++ code that uses Java exceptions, and handle them appropriately. However, if C++ code only needs to execute destructors when Java exceptions are thrown through it, GCC will guess incorrectly. Sample problematic code:

struct S { ~S(); };

extern void bar();    // Is implemented in Java and may throw exceptions.

void foo()
{
  S s;
  bar();
}

The usual effect of an incorrect guess is a link failure, complaining of a missing routine called __gxx_personality_v0.

You can inform the compiler that Java exceptions are to be used in a translation unit, irrespective of what it might think, by writing #pragma GCC java_exceptions at the head of the file. This #pragma must appear before any functions that throw or catch exceptions, or run destructors when exceptions are thrown through them.


Guide to GNU gcj

Node:GNU Free Documentation License, Next:Invoking gcj, Previous:Copying, Up:Top

GNU Free Documentation License

Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.


Guide to GNU gcj

Node:Input and output files, Next:Input Options, Up:Invoking gcj

Input and output files

A gcj command is like a gcc command, in that it consists of a number of options and file names. The following kinds of input file names are supported:

file.java
Java source files.
file.class
Java bytecode files.
file.zip
file.jar
An archive containing one or more .class files, all of which are compiled. The archive may be compressed.
@file
A file containing a whitespace-separated list of input file names. (Currently, these must all be .java source files, but that may change.) Each named file is compiled, just as if it had been on the command line.
library.a
library.so
-llibname
Libraries to use when linking. See the gcc manual.

You can specify more than one input file on the gcj command line, in which case they will all be compiled. If you specify a -o FILENAME option, all the input files will be compiled together, producing a single output file, named FILENAME. This is allowed even when using -S or -c, but not when using -C or --resource. (This is an extension beyond the what plain gcc allows.) (If more than one input file is specified, all must currently be .java files, though we hope to fix this.)


Guide to GNU gcj

Node:Input Options, Next:Encodings, Previous:Input and output files, Up:Invoking gcj

Input Options

gcj has options to control where it looks to find files it needs. For instance, gcj might need to load a class that is referenced by the file it has been asked to compile. Like other compilers for the Java language, gcj has a notion of a class path. There are several options and environment variables which can be used to manipulate the class path. When gcj looks for a given class, it searches the class path looking for matching .class or .java file. gcj comes with a built-in class path which points at the installed libgcj.jar, a file which contains all the standard classes.

In the below, a directory or path component can refer either to an actual directory on the filesystem, or to a .zip or .jar file, which gcj will search as if it is a directory.

-Idir
All directories specified by -I are kept in order and prepended to the class path constructed from all the other options. Unless compatibility with tools like javac is imported, we recommend always using -I instead of the other options for manipulating the class path.
--classpath=path
This sets the class path to path, a colon-separated list of paths (on Windows-based systems, a semicolon-separate list of paths). This does not override the builtin ("boot") search path.
--CLASSPATH=path
Deprecated synonym for --classpath.
--bootclasspath=path
Where to find the standard builtin classes, such as java.lang.String.
--extdirs=path
For each directory in the path, place the contents of that directory at the end of the class path.
CLASSPATH
This is an environment variable which holds a list of paths.

The final class path is constructed like so:

  • First come all directories specified via -I.
  • If --classpath is specified, its value is appended. Otherwise, if the CLASSPATH environment variable is specified, then its value is appended. Otherwise, the current directory (".") is appended.
  • If --bootclasspath was specified, append its value. Otherwise, append the built-in system directory, libgcj.jar.
  • Finaly, if --extdirs was specified, append the contents of the specified directories at the end of the class path. Otherwise, append the contents of the built-in extdirs at $(prefix)/share/java/ext.

The classfile built by gcj for the class java.lang.Object (and placed in libgcj.jar) contains a special zero length attribute gnu.gcj.gcj-compiled. The compiler looks for this attribute when loading java.lang.Object and will report an error if it isn't found, unless it compiles to bytecode (the option -fforce-classes-archive-check can be used to override this behavior in this particular case.)

-fforce-classes-archive-check
This forces the compiler to always check for the special zero length attribute gnu.gcj.gcj-compiled in java.lang.Object and issue an error if it isn't found.


Guide to GNU gcj

Node:Interfaces, Next:Objects and Classes, Previous:Primitive types, Up:About CNI

Interfaces

A Java class can implement zero or more interfaces, in addition to inheriting from a single base class.

CNI allows CNI code to implement methods of interfaces. You can also call methods through interface references, with some limitations.

CNI doesn't understand interface inheritance at all yet. So, you can only call an interface method when the declared type of the field being called matches the interface which declares that method. The workaround is to cast the interface reference to the right superinterface.

For example if you have:

interface A
{
  void a();
}

interface B extends A
{
  void b();
}

and declare a variable of type B in C++, you can't call a() unless you cast it to an A first.


Guide to GNU gcj

Node:Invocation, Next:Reflection, Previous:Synchronization, Up:About CNI

Invocation

CNI permits C++ applications to make calls into Java classes, in addition to allowing Java code to call into C++. Several functions, known as the invocation API, are provided to support this.

jint JvCreateJavaVM (void* vm_args) Function
Initializes the Java runtime. This function performs essential initialization of the threads interface, garbage collector, exception handling and other key aspects of the runtime. It must be called once by an application with a non-Java main() function, before any other Java or CNI calls are made. It is safe, but not recommended, to call JvCreateJavaVM() more than once provided it is only called from a single thread. The vmargs parameter can be used to specify initialization parameters for the Java runtime. It may be NULL. This function returns 0 upon success, or -1 if the runtime is already initialized.

Note: In GCJ 3.1, the vm_args parameter is ignored. It may be used in a future release.

java::lang::Thread* JvAttachCurrentThread (jstring name, java::lang::ThreadGroup* group) Function
Registers an existing thread with the Java runtime. This must be called once from each thread, before that thread makes any other Java or CNI calls. It must be called after JvCreateJavaVM. name specifies a name for the thread. It may be NULL, in which case a name will be generated. group is the ThreadGroup in which this thread will be a member. If it is NULL, the thread will be a member of the main thread group. The return value is the Java Thread object that represents the thread. It is safe to call JvAttachCurrentThread() more than once from the same thread. If the thread is already attached, the call is ignored and the current thread object is returned.

jint JvDetachCurrentThread () Function
Unregisters a thread from the Java runtime. This should be called by threads that were attached using JvAttachCurrentThread(), after they have finished making calls to Java code. This ensures that any resources associated with the thread become eligible for garbage collection. This function returns 0 upon success, or -1 if the current thread is not attached.

Handling uncaught exceptions

If an exception is thrown from Java code called using the invocation API, and no handler for the exception can be found, the runtime will abort the application. In order to make the application more robust, it is recommended that code which uses the invocation API be wrapped by a top-level try/catch block that catches all Java exceptions.

Example

The following code demonstrates the use of the invocation API. In this example, the C++ application initializes the Java runtime and attaches itself. The java.lang.System class is initialized in order to access its out field, and a Java string is printed. Finally, the thread is detached from the runtime once it has finished making Java calls. Everything is wrapped with a try/catch block to provide a default handler for any uncaught exceptions.

The example can be compiled with c++ test.cc -lgcj.

// test.cc
#include <gcj/cni.h>
#include <java/lang/System.h>
#include <java/io/PrintStream.h>
#include <java/lang/Throwable.h>

int main(int argc, char *argv)
{
  using namespace java::lang;

  try
  {
    JvCreateJavaVM(NULL);
    JvAttachCurrentThread(NULL, NULL);

    String *message = JvNewStringLatin1("Hello from C++");
    JvInitClass(&System.class$);
    System::out->println(message);

    JvDetachCurrentThread();
  }
  catch (Throwable *t)
  {
    System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
    t->printStackTrace();
  }
}


Guide to GNU gcj

Node:Invoking gcj, Next:Compatibility, Previous:GNU Free Documentation License, Up:Top

Invoking gcj

As gcj is just another front end to gcc, it supports many of the same options as gcc. See Option Summary. This manual only documents the options specific to gcj.

  • Input and output files:
  • Input Options: How gcj finds files
  • Encodings: Options controlling source file encoding
  • Warnings: Options controlling warnings specific to gcj
  • Code Generation: Options controlling the output of gcj
  • Configure-time Options: Options you won't use


Guide to GNU gcj

Node:Invoking gcjh, Next:Invoking jv-scan, Previous:Compatibility, Up:Top

Invoking gcjh

The gcjh program is used to generate header files from class files. It can generate both CNI and JNI header files, as well as stub implementation files which can be used as a basis for implementing the required native methods.

-stubs
This causes gcjh to generate stub files instead of header files. By default the stub file will be named after the class, with a suffix of .cc. In JNI mode, the default output file will have the suffix .c.
-jni
This tells gcjh to generate a JNI header or stub. By default, CNI headers are generated.
-add text
Inserts text into the class body. This is ignored in JNI mode.
-append text
Inserts text into the header file after the class declaration. This is ignored in JNI mode.
-friend text
Inserts text into the class as a friend declaration. This is ignored in JNI mode.
-prepend text
Inserts text into the header file before the class declaration. This is ignored in JNI mode.
--classpath=path
--CLASSPATH=path
-Idirectory
-d directory
-o file
These options are all identical to the corresponding gcj options.
-o file
Sets the output file name. This cannot be used if there is more than one class on the command line.
-td directory
Sets the name of the directory to use for temporary files.
-M
Print all dependencies to stdout; suppress ordinary output.
-MM
Print non-system dependencies to stdout; suppress ordinary output.
-MD
Print all dependencies to stdout.
-MMD
Print non-system dependencies to stdout.
--help
Print help about gcjh and exit. No further processing is done.
--version
Print version information for gcjh and exit. No further processing is done.
-v, --verbose
Print extra information while running.

All remaining options are considered to be names of classes.


Guide to GNU gcj

Node:Invoking gij, Next:Invoking jv-convert, Previous:Invoking jcf-dump, Up:Top

Invoking gij

gij is a Java bytecode interpreter included with libgcj. gij is not available on every platform; porting it requires a small amount of assembly programming which has not been done for all the targets supported by gcj.

The primary argument to gij is the name of a class or, with -jar, a jar file. Options before this argument are interpreted by gij; remaining options are passed to the interpreted program.

If a class name is specified and this class does not have a main method with the appropriate signature (a static void method with a String[] as its sole argument), then gij will print an error and exit.

If a jar file is specified then gij will use information in it to determine which class' main method will be invoked.

gij will invoke the main method with all the remaining command-line options.

Note that gij is not limited to interpreting code. Because libgcj includes a class loader which can dynamically load shared objects, it is possible to give gij the name of a class which has been compiled and put into a shared library on the class path.

-Dname[=value]
This defines a system property named name with value value. If value is not specified then it defaults to the empty string. These system properties are initialized at the program's startup and can be retrieved at runtime using the java.lang.System.getProperty method.
-ms=number
This sets the initial heap size.
-mx=number
This sets the maximum heap size.
-jar
This indicates that the name passed to gij should be interpreted as the name of a jar file, not a class.
--help
Print help, then exit.
--version
Print version number, then exit.


Guide to GNU gcj

Node:Invoking jcf-dump, Next:Invoking gij, Previous:Invoking jv-scan, Up:Top

Invoking jcf-dump

This is a class file examiner, similar to javap. It will print information about a number of classes, which are specifed by class name or file name.

-c
Disassemble method bodies. By default method bodies are not printed.
--javap
Generate output in javap format. The implementation of this feature is very incomplete.
--classpath=path
--CLASSPATH=path
-Idirectory
-o file
These options as the same as the corresponding gcj options.
--help
Print help, then exit.
--version
Print version number, then exit.
-v, --verbose
Print extra information while running.


Guide to GNU gcj

Node:Invoking jv-convert, Next:Invoking rmic, Previous:Invoking gij, Up:Top

Invoking jv-convert

jv-convert [OPTION] ... [INPUTFILE [OUTPUTFILE]]

jv-convert is a utility included with libgcj which converts a file from one encoding to another. It is similar to the Unix iconv utility.

The encodings supported by jv-convert are platform-dependent. Currently there is no way to get a list of all supported encodings.

--encoding name
--from name
Use name as the input encoding. The default is the current locale's encoding.
--to name
Use name as the output encoding. The default is the JavaSrc encoding; this is ASCII with \u escapes for non-ASCII characters.
-i file
Read from file. The default is to read from standard input.
-o file
Write to file. The default is to write to standard output.
--reverse
Swap the input and output encodings.
--help
Print a help message, then exit.
--version
Print version information, then exit.


Guide to GNU gcj

Node:Invoking jv-scan, Next:Invoking jcf-dump, Previous:Invoking gcjh, Up:Top

Invoking jv-scan

The jv-scan program can be used to print information about a Java source file (.java file).

--complexity
This prints a complexity measure, related to cyclomatic complexity, for each input file.
--encoding=name
This works like the corresponding gcj option.
--print-main
This prints the name of the class in this file containing a main method.
--list-class
This lists the names of all classes defined in the input files.
--list-filename
If --list-class is given, this option causes jv-scan to also print the name of the file in which each class was found.
-o file
Print output to the named file.
--help
Print help, then exit.
--version
Print version number, then exit.


Guide to GNU gcj

Node:Invoking rmic, Next:Invoking rmiregistry, Previous:Invoking jv-convert, Up:Top

Invoking rmic

rmic [OPTION] ... class ...

rmic is a utility included with libgcj which generates stubs for remote objects.

Note that this program isn't yet fully compatible with the JDK rmic. Some options, such as -classpath, are recognized but currently ignored. We have left these options undocumented for now.

Long options can also be given with a GNU-style leading --. For instance, --help is accepted.

-keep
-keepgenerated
By default, rmic deletes intermediate files. Either of these options causes it not to delete such files.
-v1.1
Cause rmic to create stubs and skeletons for the 1.1 protocol version.
-vcompat
Cause rmic to create stubs and skeletons compatible with both the 1.1 and 1.2 protocol versions. This is the default.
-v1.2
Cause rmic to create stubs and skeletons for the 1.2 protocol version.
-nocompile
Don't compile the generated files.
-verbose
Print information about what rmic is doing.
-d directory
Put output files in directory. By default the files are put in the current working directory.
-help
Print a help message, then exit.
-version
Print version information, then exit.


Guide to GNU gcj

Node:Invoking rmiregistry, Next:About CNI, Previous:Invoking rmic, Up:Top

Invoking rmiregistry

rmiregistry [OPTION] ... [port]

rmiregistry starts a remote object registry on the current host. If no port number is specified, then port 1099 is used.

--help
Print a help message, then exit.
--version
Print version information, then exit.


Guide to GNU gcj

Node:Methods, Next:Strings, Previous:Arrays, Up:About CNI

Methods

Java methods are mapped directly into C++ methods. The header files generated by gcjh include the appropriate method definitions. Basically, the generated methods have the same names and corresponding types as the Java methods, and are called in the natural manner.

Overloading

Both Java and C++ provide method overloading, where multiple methods in a class have the same name, and the correct one is chosen (at compile time) depending on the argument types. The rules for choosing the correct method are (as expected) more complicated in C++ than in Java, but given a set of overloaded methods generated by gcjh the C++ compiler will choose the expected one.

Common assemblers and linkers are not aware of C++ overloading, so the standard implementation strategy is to encode the parameter types of a method into its assembly-level name. This encoding is called mangling, and the encoded name is the mangled name. The same mechanism is used to implement Java overloading. For C++/Java interoperability, it is important that both the Java and C++ compilers use the same encoding scheme.

Static methods

Static Java methods are invoked in CNI using the standard C++ syntax, using the :: operator rather than the . operator.

For example:

jint i = java::lang::Math::round((jfloat) 2.3);

C++ method definition syntax is used to define a static native method. For example:

#include <java/lang/Integer>
java::lang::Integer*
java::lang::Integer::getInteger(jstring str)
{
  ...
}

Object Constructors

Constructors are called implicitly as part of object allocation using the new operator.

For example:

java::lang::Integer *x = new java::lang::Integer(234);

Java does not allow a constructor to be a native method. This limitation can be coded round however because a constructor can call a native method.

Instance methods

Calling a Java instance method from a C++ CNI method is done using the standard C++ syntax, e.g.:

// First create the Java object.
java::lang::Integer *x = new java::lang::Integer(234);
// Now call a method.
jint prim_value = x->intValue();
if (x->longValue == 0)
  ...

Defining a Java native instance method is also done the natural way:

#include <java/lang/Integer.h>

jdouble
java::lang:Integer::doubleValue()
{
  return (jdouble) value;
}

Interface methods

In Java you can call a method using an interface reference. This is supported, but not completly. See Interfaces.


Guide to GNU gcj

Node:Mixing with C++, Next:Exception Handling, Previous:Strings, Up:About CNI

Interoperating with C/C++

Because CNI is designed to represent Java classes and methods it cannot be mixed readily with C/C++ types.

One important restriction is that Java classes cannot have non-Java type instance or static variables and cannot have methods which take non-Java types as arguments or return non-Java types.

None of the following is possible with CNI:

class ::MyClass : public java::lang::Object
{
   char* variable;  // char* is not a valid Java type.
}

uint
::SomeClass::someMethod (char *arg)
{
  .
  .
  .
}   // uint is not a valid Java type, neither is char*

Of course, it is ok to use C/C++ types within the scope of a method:

jint
::SomeClass::otherMethod (jstring str)
{
   char *arg = ...
   .
   .
   .
}

But this restriction can cause a problem so CNI includes the gnu.gcj.RawData class. The RawData class is a non-scanned reference type. In other words variables declared of type RawData can contain any data and are not checked by the compiler in any way.

This means that you can put C/C++ data structures (including classes) in your CNI classes, as long as you use the appropriate cast.

Here are some examples:

class ::MyClass : public java::lang::Object
{
   gnu.gcj.RawData string;

   MyClass ();
   gnu.gcj.RawData getText ();
   void printText ();
}

::MyClass::MyClass ()
{
   char* text = ...
   string = text;
}

gnu.gcj.RawData
::MyClass::getText ()
{
   return string;
}

void
::MyClass::printText ()
{
  printf("%s\n", (char*) string);
}


Guide to GNU gcj

Node:Object allocation, Next:Arrays, Previous:Class Initialization, Up:About CNI

Object allocation

New Java objects are allocated using a class instance creation expression, e.g.:

new Type ( ... )

The same syntax is used in C++. The main difference is that C++ objects have to be explicitly deleted; in Java they are automatically deleted by the garbage collector. Using CNI, you can allocate a new Java object using standard C++ syntax and the C++ compiler will allocate memory from the garbage collector. If you have overloaded constructors, the compiler will choose the correct one using standard C++ overload resolution rules.

For example:

java::util::Hashtable *ht = new java::util::Hashtable(120);

void* _Jv_AllocBytes (jsize size) Function
Allocates size bytes from the heap. The memory is not scanned by the garbage collector but it freed if no references to it are discovered.


Guide to GNU gcj

Node:Objects and Classes, Next:Class Initialization, Previous:Interfaces, Up:About CNI

Objects and Classes

Classes

All Java classes are derived from java.lang.Object. C++ does not have a unique root class, but we use the C++ class java::lang::Object as the C++ version of the java.lang.Object Java class. All other Java classes are mapped into corresponding C++ classes derived from java::lang::Object.

Interface inheritance (the implements keyword) is currently not reflected in the C++ mapping.

Object fields

Each object contains an object header, followed by the instance fields of the class, in order. The object header consists of a single pointer to a dispatch or virtual function table. (There may be extra fields in front of the object, for example for memory management, but this is invisible to the application, and the reference to the object points to the dispatch table pointer.)

The fields are laid out in the same order, alignment, and size as in C++. Specifically, 8-bite and 16-bit native types (byte, short, char, and boolean) are not widened to 32 bits. Note that the Java VM does extend 8-bit and 16-bit types to 32 bits when on the VM stack or temporary registers.

If you include the gcjh-generated header for a class, you can access fields of Java classes in the natural way. For example, given the following Java class:

public class Int
{
  public int i;
  public Integer (int i) { this.i = i; }
  public static zero = new Integer(0);
}

you can write:

#include <gcj/cni.h>;
#include <Int>;

Int*
mult (Int *p, jint k)
{
  if (k == 0)
    return Int::zero;  // Static member access.
  return new Int(p->i * k);
}

Access specifiers

CNI does not strictly enforce the Java access specifiers, because Java permissions cannot be directly mapped into C++ permission. Private Java fields and methods are mapped to private C++ fields and methods, but other fields and methods are mapped to public fields and methods.


Guide to GNU gcj

Node:Packages, Next:Primitive types, Previous:Basic concepts, Up:About CNI

Packages

The only global names in Java are class names, and packages. A package can contain zero or more classes, and also zero or more sub-packages. Every class belongs to either an unnamed package or a package that has a hierarchical and globally unique name.

A Java package is mapped to a C++ namespace. The Java class java.lang.String is in the package java.lang, which is a sub-package of java. The C++ equivalent is the class java::lang::String, which is in the namespace java::lang which is in the namespace java.

Here is how you could express this:

(// Declare the class(es), possibly in a header file:
namespace java {
  namespace lang {
    class Object;
    class String;
    ...
  }
}

class java::lang::String : public java::lang::Object
{
  ...
};

The gcjh tool automatically generates the nessary namespace declarations.

Leaving out package names

Always using the fully-qualified name of a java class can be tiresomely verbose. Using the full qualified name also ties the code to a single package making code changes necessary should the class move from one package to another. The Java package declaration specifies that the following class declarations are in the named package, without having to explicitly name the full package qualifiers. The package declaration can be followed by zero or more import declarations, which allows either a single class or all the classes in a package to be named by a simple identifier. C++ provides something similar with the using declaration and directive.

In Java:

import package-name.class-name;

allows the program text to refer to class-name as a shorthand for the fully qualified name: package-name.class-name.

To achieve the same effect C++, you have to do this:

using package-name::class-name;

Java can also cause imports on demand, like this:

import package-name.*;

Doing this allows any class from the package package-name to be refered to only by its class-name within the program text.

The same effect can be achieved in C++ like this:

using namespace package-name;


Guide to GNU gcj

Node:Primitive types, Next:Interfaces, Previous:Packages, Up:About CNI

Primitive types

Java provides 8 primitives types which represent integers, floats, characters and booleans (and also the void type). C++ has its own very similar concrete types. Such types in C++ however are not always implemented in the same way (an int might be 16, 32 or 64 bits for example) so CNI provides a special C++ type for each primitive Java type:

Java type | C/C++ typename | Description
char | jchar | 16 bit Unicode character
boolean | jboolean | logical (true or false) values
byte | jbyte | 8-bit signed integer
short | jshort | 16 bit signed integer
int | jint | 32 bit signed integer
long | jlong | 64 bit signed integer
float | jfloat | 32 bit IEEE floating point number
double | jdouble | 64 bit IEEE floating point number
void | void | no value

When refering to a Java type You should always use these C++ typenames (e.g.: jint) to avoid disappointment.

Reference types associated with primitive types

In Java each primitive type has an associated reference type, e.g.: boolean has an associated java.lang.Boolean class. In order to make working with such classes easier GCJ provides the macro JvPrimClass:

JvPrimClass type macro
Return a pointer to the Class object corresponding to the type supplied.
JvPrimClass(void) => java.lang.Void.TYPE


Guide to GNU gcj

Node:Reflection, Previous:Invocation, Up:About CNI

Reflection

Reflection is possible with CNI code, it functions similarly to how it functions with JNI.

The types jfieldID and jmethodID are as in JNI.

The functions:

  • JvFromReflectedField,
  • JvFromReflectedMethod,
  • JvToReflectedField
  • JvToFromReflectedMethod

will be added shortly, as will other functions corresponding to JNI.


Guide to GNU gcj

Node:Resources, Previous:About CNI, Up:Top

Resources

While writing gcj and libgcj we have, of course, relied heavily on documentation from Sun Microsystems. In particular we have used The Java Language Specification (both first and second editions), the Java Class Libraries (volumes one and two), and the Java Virtual Machine Specification. In addition we've used the online documentation at http://java.sun.com/.

The current gcj home page is http://gcc.gnu.org/java/.

For more information on gcc, see http://gcc.gnu.org/.

Some libgcj testing is done using the Mauve test suite. This is a free software Java class library test suite which is being written because the JCK is not free. See http://sources.redhat.com/mauve/ for more information.


Guide to GNU gcj

Node:Strings, Next:Mixing with C++, Previous:Methods, Up:About CNI

Strings

CNI provides a number of utility functions for working with Java Java String objects. The names and interfaces are analogous to those of JNI.

jstring JvNewString (const char* chars, jsize len) Function
Returns a Java String object with characters from the C string chars up to the index len in that array.

jstring JvNewStringLatin1 (const char* bytes, jsize len) Function
Returns a Java String made up of len bytes from bytes.

jstring JvNewStringLatin1 (const char* bytes) Function
As above but the length of the String is strlen(bytes).

jstring JvNewStringUTF (const char* bytes) Function
Returns a String which is made up of the UTF encoded characters present in the C string bytes.

jchar* JvGetStringChars (jstring str) Function
Returns a pointer to an array of characters making up the String str.

int JvGetStringUTFLength (jstring str) Function
Returns the number of bytes required to encode the contents of the String str in UTF-8.

jsize JvGetStringUTFRegion (jstring str, jsize start, jsize len, char* buf) Function
Puts the UTF-8 encoding of a region of the String str into the buffer buf. The region to fetch is marked by start and len.

Note that buf is a buffer, not a C string. It is not null terminated.


Guide to GNU gcj

Node:Synchronization, Next:Invocation, Previous:Exception Handling, Up:About CNI

Synchronization

Each Java object has an implicit monitor. The Java VM uses the instruction monitorenter to acquire and lock a monitor, and monitorexit to release it.

The corresponding CNI macros are JvMonitorEnter and JvMonitorExit (JNI has similar methods MonitorEnter and MonitorExit).

The Java source language does not provide direct access to these primitives. Instead, there is a synchronized statement that does an implicit monitorenter before entry to the block, and does a monitorexit on exit from the block. Note that the lock has to be released even when the block is abnormally terminated by an exception, which means there is an implicit try finally surrounding synchronization locks.

From C++, it makes sense to use a destructor to release a lock. CNI defines the following utility class:

class JvSynchronize() {
  jobject obj;
  JvSynchronize(jobject o) { obj = o; JvMonitorEnter(o); }
  ~JvSynchronize() { JvMonitorExit(obj); }
};

So this Java code:

synchronized (OBJ)
{
   CODE
}

might become this C++ code:

{
   JvSynchronize dummy (OBJ);
   CODE;
}

Java also has methods with the synchronized attribute. This is equivalent to wrapping the entire method body in a synchronized statement. (Alternatively, an implementation could require the caller to do the synchronization. This is not practical for a compiler, because each virtual method call would have to test at run-time if synchronization is needed.) Since in gcj the synchronized attribute is handled by the method implementation, it is up to the programmer of a synchronized native method to handle the synchronization (in the C++ implementation of the method). In otherwords, you need to manually add JvSynchronize in a native synchornized method.


Guide to GNU gcj

Node:Warnings, Next:Code Generation, Previous:Encodings, Up:Invoking gcj

Warnings

gcj implements several warnings. As with other generic gcc warnings, if an option of the form -Wfoo enables a warning, then -Wno-foo will disable it. Here we've chosen to document the form of the warning which will have an effect - the default being the opposite of what is listed.

-Wredundant-modifiers
With this flag, gcj will warn about redundant modifiers. For instance, it will warn if an interface method is declared public.
-Wextraneous-semicolon
This causes gcj to warn about empty statements. Empty statements have been deprecated.
-Wno-out-of-date
This option will cause gcj not to warn when a source file is newer than its matching class file. By default gcj will warn about this.
-Wunused
This is the same as gcc's -Wunused.
-Wall
This is the same as -Wredundant-modifiers -Wextraneous-semicolon -Wunused.


Debugging with GDB

The GNU Source-Level Debugger

Ninth Edition, for GDB version 5.1.1

January 2002

Richard Stallman, Roland Pesch, Stan Shebs, et al.

Table of Contents

  • Summary of GDB
    • Free software
    • Free Software Needs Free Documentation
    • Contributors to GDB
  • A Sample GDB Session
  • Getting In and Out of GDB
    • Invoking GDB
      • Choosing files
      • Choosing modes
    • Quitting GDB
    • Shell commands
  • GDB Commands
    • Command syntax
    • Command completion
    • Getting help
  • Running Programs Under GDB
    • Compiling for debugging
    • Starting your program
    • Your program's arguments
    • Your program's environment
    • Your program's working directory
    • Your program's input and output
    • Debugging an already-running process
    • Killing the child process
    • Debugging programs with multiple threads
    • Debugging programs with multiple processes
  • Stopping and Continuing
    • Breakpoints, watchpoints, and catchpoints
      • Setting breakpoints
      • Setting watchpoints
      • Setting catchpoints
      • Deleting breakpoints
      • Disabling breakpoints
      • Break conditions
      • Breakpoint command lists
      • Breakpoint menus
      • "Cannot insert breakpoints"
    • Continuing and stepping
    • Signals
    • Stopping and starting multi-thread programs
  • Examining the Stack
    • Stack frames
    • Backtraces
    • Selecting a frame
    • Information about a frame
  • Examining Source Files
    • Printing source lines
    • Searching source files
    • Specifying source directories
    • Source and machine code
  • Examining Data
    • Expressions
    • Program variables
    • Artificial arrays
    • Output formats
    • Examining memory
    • Automatic display
    • Print settings
    • Value history
    • Convenience variables
    • Registers
    • Floating point hardware
    • Memory Region Attributes
      • Attributes
        • Memory Access Mode
        • Memory Access Size
        • Data Cache
  • Tracepoints
    • Commands to Set Tracepoints
      • Create and Delete Tracepoints
      • Enable and Disable Tracepoints
      • Tracepoint Passcounts
      • Tracepoint Action Lists
      • Listing Tracepoints
      • Starting and Stopping Trace Experiment
    • Using the collected data
      • tfind n
      • tdump
      • save-tracepoints filename
    • Convenience Variables for Tracepoints
  • Using GDB with Different Languages
    • Switching between source languages
      • List of filename extensions and languages
      • Setting the working language
      • Having GDB infer the source language
    • Displaying the language
    • Type and range checking
      • An overview of type checking
      • An overview of range checking
    • Supported languages
      • C and C++
        • C and C++ operators
        • C and C++ constants
        • C++ expressions
        • C and C++ defaults
        • C and C++ type and range checks
        • GDB and C
        • GDB features for C++
      • Modula-2
        • Operators
        • Built-in functions and procedures
        • Constants
        • Modula-2 defaults
        • Deviations from standard Modula-2
        • Modula-2 type and range checks
        • The scope operators :: and .
        • GDB and Modula-2
      • Chill
        • How modes are displayed
        • Locations and their accesses
        • Values and their Operations
        • Chill type and range checks
        • Chill defaults
  • Examining the Symbol Table
  • Altering Execution
    • Assignment to variables
    • Continuing at a different address
    • Giving your program a signal
    • Returning from a function
    • Calling program functions
    • Patching programs
  • GDB Files
    • Commands to specify files
    • Errors reading symbol files
  • Specifying a Debugging Target
    • Active targets
    • Commands for managing targets
    • Choosing target byte order
    • Remote debugging
      • The GDB remote serial protocol
        • What the stub can do for you
        • What you must do for the stub
        • Putting it all together
        • Communication protocol
        • Using the gdbserver program
        • Using the gdbserve.nlm program
    • Kernel Object Display
  • Configuration-Specific Information
    • Native
      • HP-UX
      • SVR4 process information
      • Features for Debugging DJGPP Programs
    • Embedded Operating Systems
      • Using GDB with VxWorks
        • Connecting to VxWorks
        • VxWorks download
        • Running tasks
    • Embedded Processors
      • AMD A29K Embedded
        • A29K UDI
        • EBMON protocol for AMD29K
        • Communications setup
        • EB29K cross-debugging
        • Remote log
      • ARM
      • Hitachi H8/300
        • Connecting to Hitachi boards
        • Using the E7000 in-circuit emulator
        • Special GDB commands for Hitachi micros
      • H8/500
      • Intel i960
        • Startup with Nindy
        • Options for Nindy
        • Nindy reset command
      • Mitsubishi M32R/D
      • M68k
      • M88K
      • MIPS Embedded
      • PowerPC
      • HP PA Embedded
      • Hitachi SH
      • Tsqware Sparclet
        • Setting file to debug
        • Connecting to Sparclet
        • Sparclet download
        • Running and debugging
      • Fujitsu Sparclite
      • Tandem ST2000
      • Zilog Z8000
    • Architectures
      • A29K
      • Alpha
      • MIPS
  • Controlling GDB
    • Prompt
    • Command editing
    • Command history
    • Screen size
    • Numbers
    • Optional warnings and messages
    • Optional messages about internal happenings
  • Canned Sequences of Commands
    • User-defined commands
    • User-defined command hooks
    • Command files
    • Commands for controlled output
  • GDB Text User Interface
    • TUI overview
    • TUI Key Bindings
    • TUI specific commands
    • TUI configuration variables
  • Using GDB under GNU Emacs
  • GDB Annotations
    • What is an Annotation?
    • The Server Prefix
    • Values
    • Frames
    • Displays
    • Annotation for GDB Input
    • Errors
    • Information on Breakpoints
    • Invalidation Notices
    • Running the Program
    • Displaying Source
    • Annotations We Might Want in the Future
  • The GDB/MI Interface
    • Function and Purpose
    • Notation and Terminology
    • GDB/MI Command Syntax
      • GDB/MI Input Syntax
      • GDB/MI Output Syntax
      • Simple Examples of GDB/MI Interaction
    • GDB/MI Compatibility with CLI
    • GDB/MI Output Records
      • GDB/MI Result Records
      • GDB/MI Stream Records
      • GDB/MI Out-of-band Records
    • GDB/MI Command Description Format
    • GDB/MI Breakpoint table commands
    • GDB/MI Data Manipulation
    • GDB/MI Program control
    • Miscellaneous GDB commands in GDB/MI
    • GDB/MI Stack Manipulation Commands
    • GDB/MI Symbol Query Commands
    • GDB/MI Target Manipulation Commands
    • GDB/MI Thread Commands
    • GDB/MI Tracepoint Commands
    • GDB/MI Variable Objects
  • Reporting Bugs in GDB
    • Have you found a bug?
    • How to report bugs
  • Command Line Editing
    • Introduction to Line Editing
    • Readline Interaction
      • Readline Bare Essentials
      • Readline Movement Commands
      • Readline Killing Commands
      • Readline Arguments
      • Searching for Commands in the History
    • Readline Init File
      • Readline Init File Syntax
      • Conditional Init Constructs
      • Sample Init File
    • Bindable Readline Commands
      • Commands For Moving
      • Commands For Manipulating The History
      • Commands For Changing Text
      • Killing And Yanking
      • Specifying Numeric Arguments
      • Letting Readline Type For You
      • Keyboard Macros
      • Some Miscellaneous Commands
    • Readline vi Mode
  • Using History Interactively
    • History Expansion
      • Event Designators
      • Word Designators
      • Modifiers
  • Formatting Documentation
  • Installing GDB
    • Compiling GDB in another directory
    • Specifying names for hosts and targets
    • configure options
  • GNU Free Documentation License
    • ADDENDUM: How to use this License for your documents
  • Index

@dircategory Programming & development tools. * Gdb: (gdb). The GNU debugger.

Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Published by the Free Software Foundation
59 Temple Place - Suite 330,
Boston, MA 02111-1307 USA
ISBN 1-882114-77-9

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Free Software" and "Free Software Needs Free Documentation", with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below.

(a) The Free Software Foundation's Back-Cover Text is: "You have
freedom to copy and modify this GNU Manual, like GNU software.  Copies
published by the Free Software Foundation raise funds for GNU
development."

@node Top

@top Debugging with @value{GDBN}

This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.

This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
@value{GDBVN}.

Copyright (C) 1988-2000 Free Software Foundation, Inc.

@menu
* Summary::                     Summary of @value{GDBN}
* Sample Session::              A sample @value{GDBN} session

* Invocation::                  Getting in and out of @value{GDBN}
* Commands::                    @value{GDBN} commands
* Running::                     Running programs under @value{GDBN}
* Stopping::                    Stopping and continuing
* Stack::                       Examining the stack
* Source::                      Examining source files
* Data::                        Examining data

* Languages::                   Using @value{GDBN} with different languages

* Symbols::                     Examining the symbol table
* Altering::                    Altering execution
* GDB Files::                   @value{GDBN} files
* Targets::                     Specifying a debugging target
* Configurations::              Configuration-specific information
* Controlling GDB::             Controlling @value{GDBN}
* Sequences::                   Canned sequences of commands
* Emacs::                       Using @value{GDBN} under @sc{gnu} Emacs
* Annotations::                 @value{GDBN}'s annotation interface.

* GDB Bugs::                    Reporting bugs in @value{GDBN}
* Formatting Documentation::    How to format and print @value{GDBN} documentation

* Command Line Editing::        Command Line Editing
* Using History Interactively:: Using History Interactively
* Installing GDB::              Installing GDB
* GNU Free Documentation License::  The license for this documentation
* Index::                       Index
@end menu

Summary of GDB

The purpose of a debugger such as GDB is to allow you to see what is going on "inside" another program while it executes--or what another program was doing at the moment it crashed.

GDB can do four main kinds of things (plus other things in support of these) to help you catch bugs in the act:

  • Start your program, specifying anything that might affect its behavior.
  • Make your program stop on specified conditions.
  • Examine what has happened, when your program has stopped.
  • Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another.

You can use GDB to debug programs written in C and C++. For more information, see section Supported languages. For more information, see section C and C++.

Support for Modula-2 and Chill is partial. For information on Modula-2, see section Modula-2. For information on Chill, see section Chill.

Debugging Pascal programs which use sets, subranges, file variables, or nested functions does not currently work. GDB does not support entering expressions, printing values, or similar features using Pascal syntax.

GDB can be used to debug programs written in Fortran, although it may be necessary to refer to some variables with a trailing underscore.

  • Free Software: Freely redistributable software
  • Contributors: Contributors to GDB

Free software

GDB is free software, protected by the GNU General Public License (GPL). The GPL gives you the freedom to copy or adapt a licensed program--but every person getting a copy also gets with it the freedom to modify that copy (which means that they must get access to the source code), and the freedom to distribute further copies. Typical software companies use copyrights to limit your freedoms; the Free Software Foundation uses the GPL to preserve these freedoms.

Fundamentally, the General Public License is a license which says that you have these freedoms and that you cannot take these freedoms away from anyone else.

Free Software Needs Free Documentation

The biggest deficiency in the free software community today is not in the software--it is the lack of good free documentation that we can include with the free software. Many of our most important programs do not come with free reference manuals and free introductory texts. Documentation is an essential part of any software package; when an important free software package does not come with a free manual and a free tutorial, that is a major gap. We have many such gaps today.

Consider Perl, for instance. The tutorial manuals that people normally use are non-free. How did this come about? Because the authors of those manuals published them with restrictive terms--no copying, no modification, source files not available--which exclude them from the free software world.

That wasn't the first time this sort of thing happened, and it was far from the last. Many times we have heard a GNU user eagerly describe a manual that he is writing, his intended contribution to the community, only to learn that he had ruined everything by signing a publication contract to make it non-free.

Free documentation, like free software, is a matter of freedom, not price. The problem with the non-free manual is not that publishers charge a price for printed copies--that in itself is fine. (The Free Software Foundation sells printed copies of manuals, too.) The problem is the restrictions on the use of the manual. Free manuals are available in source code form, and give you permission to copy and modify. Non-free manuals do not allow this.

The criteria of freedom for a free manual are roughly the same as for free software. Redistribution (including the normal kinds of commercial redistribution) must be permitted, so that the manual can accompany every copy of the program, both on-line and on paper.

Permission for modification of the technical content is crucial too. When people modify the software, adding or changing features, if they are conscientious they will change the manual too--so they can provide accurate and clear documentation for the modified program. A manual that leaves you no choice but to write a new manual to document a changed version of the program is not really available to our community.

Some kinds of limits on the way modification is handled are acceptable. For example, requirements to preserve the original author's copyright notice, the distribution terms, or the list of authors, are ok. It is also no problem to require modified versions to include notice that they were modified. Even entire sections that may not be deleted or changed are acceptable, as long as they deal with nontechnical topics (like this one). These kinds of restrictions are acceptable because they don't obstruct the community's normal use of the manual.

However, it must be possible to modify all the technical content of the manual, and then distribute the result in all the usual media, through all the usual channels. Otherwise, the restrictions obstruct the use of the manual, it is not free, and we need another manual to replace it.

Please spread the word about this issue. Our community continues to lose manuals to proprietary publishing. If we spread the word that free software needs free reference manuals and free tutorials, perhaps the next person who wants to contribute by writing documentation will realize, before it is too late, that only free manuals contribute to the free software community.

If you are writing documentation, please insist on publishing it under the GNU Free Documentation License or another free documentation license. Remember that this decision requires your approval--you don't have to let the publisher decide. Some commercial publishers will use a free license if you insist, but they will not propose the option; it is up to you to raise the issue and say firmly that this is what you want. If the publisher you are dealing with refuses, please try other publishers. If you're not sure whether a proposed license is free, write to licensing@gnu.org.

You can encourage commercial publishers to sell more free, copylefted manuals and tutorials by buying them, and particularly by buying copies from the publishers that paid for their writing or for major improvements. Meanwhile, try to avoid buying non-free documentation at all. Check the distribution terms of a manual before you buy it, and insist that whoever seeks your business must respect your freedom. Check the history of the book, and try to reward the publishers that have paid or pay the authors to work on it.

The Free Software Foundation maintains a list of free documentation published by other publishers, at http://www.fsf.org/doc/other-free-books.html.

Contributors to GDB

Richard Stallman was the original author of GDB, and of many other GNU programs. Many others have contributed to its development. This section attempts to credit major contributors. One of the virtues of free software is that everyone is free to contribute to it; with regret, we cannot actually acknowledge everyone here. The file `ChangeLog' in the GDB distribution approximates a blow-by-blow account.

Changes much prior to version 2.0 are lost in the mists of time.

Plea: Additions to this section are particularly welcome. If you or your friends (or enemies, to be evenhanded) have been unfairly omitted from this list, we would like to add your names!

So that they may not regard their many labors as thankless, we
particularly thank those who shepherded GDB through major
releases:
Andrew Cagney (releases 5.0 and 5.1);
Jim Blandy (release 4.18);
Jason Molenda (release 4.17);
Stan Shebs (release 4.14);
Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
Jim Kingdon (releases 3.5, 3.4, and 3.3);
and Randy Smith (releases 3.2, 3.1, and 3.0).

Richard Stallman, assisted at various times by Peter TerMaat, Chris Hanson, and Richard Mlynarik, handled releases through 2.8.

Michael Tiemann is the author of most of the GNU C++ support in GDB, with significant additional contributions from Per Bothner and Daniel Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ was by Peter TerMaat (who also did much general update work leading to release 3.0).

GDB uses the BFD subroutine library to examine multiple object-file formats; BFD was a joint project of David V. Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.

David Johnson wrote the original COFF support; Pace Willison did the original support for encapsulated COFF.

Brent Benson of Harris Computer Systems contributed DWARF2 support.

Adam de Boor and Bradley Davis contributed the ISI Optimum V support. Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS support. Jean-Daniel Fekete contributed Sun 386i support. Chris Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. David Johnson contributed Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. Jeff Law contributed HP PA and SOM support. Keith Packard contributed NS32K support. Doug Rabson contributed Acorn Risc Machine support. Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith contributed Convex support (and Fortran debugging). Jonathan Stone contributed Pyramid support. Michael Tiemann contributed SPARC support. Tim Tucker contributed support for the Gould NP1 and Gould Powernode. Pace Willison contributed Intel 386 support. Jay Vosburgh contributed Symmetry support.

Andreas Schwab contributed M68K Linux support.

Rich Schaefer and Peter Schauer helped with support of SunOS shared libraries.

Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about several machine instruction sets.

Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM contributed remote debugging modules for the i960, VxWorks, A29K UDI, and RDI targets, respectively.

Brian Fox is the author of the readline libraries providing command-line editing and command history.

Andrew Beers of SUNY Buffalo wrote the language-switching code, the Modula-2 support, and contributed the Languages chapter of this manual.

Fred Fish wrote most of the support for Unix System Vr4. He also enhanced the command-completion support to cover C++ overloaded symbols.

Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and Super-H processors.

NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.

Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors.

Toshiba sponsored the support for the TX39 Mips processor.

Matsushita sponsored the support for the MN10200 and MN10300 processors.

Fujitsu sponsored the support for SPARClite and FR30 processors.

Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware watchpoints.

Michael Snyder added support for tracepoints.

Stu Grossman wrote gdbserver.

Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly innumerable bug fixes and cleanups throughout GDB.

The following people at the Hewlett-Packard Company contributed support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 (narrow mode), HP's implementation of kernel threads, HP's aC++ compiler, and the terminal user interface: Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific information in this manual.

DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert Hoehne made significant contributions to the DJGPP port.

Cygnus Solutions has sponsored GDB maintenance and much of its development since 1991. Cygnus engineers who have worked on GDB fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David Zuhn have made contributions both large and small.

A Sample GDB Session

You can use this manual at your leisure to read all about GDB. However, a handful of commands are enough to get started using the debugger. This chapter illustrates those commands.

In this sample session, we emphasize user input like this: input, to make it easier to pick out from the surrounding output.

One of the preliminary versions of GNU m4 (a generic macro processor) exhibits the following bug: sometimes, when we change its quote strings from the default, the commands used to capture one macro definition within another stop working. In the following short m4 session, we define a macro foo which expands to 0000; we then use the m4 built-in defn to define bar as the same thing. However, when we change the open quote string to <QUOTE> and the close quote string to <UNQUOTE>, the same procedure fails to define a new synonym baz:

$ cd gnu/m4
$ ./m4
define(foo,0000)

foo
0000
define(bar,defn(`foo'))

bar
0000
changequote(<QUOTE>,<UNQUOTE>)

define(baz,defn(<QUOTE>foo<UNQUOTE>))
baz
C-d
m4: End of input: 0: fatal error: EOF in string

Let us use GDB to try to see what is going on.

$ gdb m4
GDB is free software and you are welcome to distribute copies
 of it under certain conditions; type "show copying" to see
 the conditions.
There is absolutely no warranty for GDB; type "show warranty"
 for details.

GDB 5.1.1, Copyright 1999 Free Software Foundation, Inc...
(gdb)

GDB reads only enough symbol data to know where to find the rest when needed; as a result, the first prompt comes up very quickly. We now tell GDB to use a narrower display width than usual, so that examples fit in this manual.

(gdb) set width 70

We need to see how the m4 built-in changequote works. Having looked at the source, we know the relevant subroutine is m4_changequote, so we set a breakpoint there with the GDB break command.

(gdb) break m4_changequote
Breakpoint 1 at 0x62f4: file builtin.c, line 879.

Using the run command, we start m4 running under GDB control; as long as control does not reach the m4_changequote subroutine, the program runs as usual:

(gdb) run
Starting program: /work/Editorial/gdb/gnu/m4/m4
define(foo,0000)

foo
0000

To trigger the breakpoint, we call changequote. GDB suspends execution of m4, displaying information about the context where it stops.

changequote(<QUOTE>,<UNQUOTE>)

Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
    at builtin.c:879
879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))

Now we use the command n (next) to advance execution to the next line of the current function.

(gdb) n
882         set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
 : nil,

set_quotes looks like a promising subroutine. We can go into it by using the command s (step) instead of next. step goes to the next line to be executed in any subroutine, so it steps into set_quotes.

(gdb) s
set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
    at input.c:530
530         if (lquote != def_lquote)

The display that shows the subroutine where m4 is now suspended (and its arguments) is called a stack frame display. It shows a summary of the stack. We can use the backtrace command (which can also be spelled bt), to see where we are in the stack as a whole: the backtrace command displays a stack frame for each active subroutine.

(gdb) bt
#0  set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
    at input.c:530
#1  0x6344 in m4_changequote (argc=3, argv=0x33c70)
    at builtin.c:882
#2  0x8174 in expand_macro (sym=0x33320) at macro.c:242
#3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
    at macro.c:71
#4  0x79dc in expand_input () at macro.c:40
#5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195

We step through a few more lines to see what happens. The first two times, we can use `s'; the next two times we use n to avoid falling into the xstrdup subroutine.

(gdb) s
0x3b5c  532         if (rquote != def_rquote)
(gdb) s
0x3b80  535         lquote = (lq == nil || *lq == '\0') ?  \
def_lquote : xstrdup(lq);
(gdb) n
536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
 : xstrdup(rq);
(gdb) n
538         len_lquote = strlen(rquote);

The last line displayed looks a little odd; we can examine the variables lquote and rquote to see if they are in fact the new left and right quotes we specified. We use the command p (print) to see their values.

(gdb) p lquote
$1 = 0x35d40 "<QUOTE>"
(gdb) p rquote
$2 = 0x35d50 "<UNQUOTE>"

lquote and rquote are indeed the new left and right quotes. To look at some context, we can display ten lines of source surrounding the current line with the l (list) command.

(gdb) l
533             xfree(rquote);
534
535         lquote = (lq == nil || *lq == '\0') ? def_lquote\
 : xstrdup (lq);
536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
 : xstrdup (rq);
537
538         len_lquote = strlen(rquote);
539         len_rquote = strlen(lquote);
540     }
541
542     void

Let us step past the two lines that set len_lquote and len_rquote, and then examine the values of those variables.

(gdb) n
539         len_rquote = strlen(lquote);
(gdb) n
540     }
(gdb) p len_lquote
$3 = 9
(gdb) p len_rquote
$4 = 7

That certainly looks wrong, assuming len_lquote and len_rquote are meant to be the lengths of lquote and rquote respectively. We can set them to better values using the p command, since it can print the value of any expression--and that expression can include subroutine calls and assignments.

(gdb) p len_lquote=strlen(lquote)
$5 = 7
(gdb) p len_rquote=strlen(rquote)
$6 = 9

Is that enough to fix the problem of using the new quotes with the m4 built-in defn? We can allow m4 to continue executing with the c (continue) command, and then try the example that caused trouble initially:

(gdb) c
Continuing.

define(baz,defn(<QUOTE>foo<UNQUOTE>))

baz
0000

Success! The new quotes now work just as well as the default ones. The problem seems to have been just the two typos defining the wrong lengths. We allow m4 exit by giving it an EOF as input:

C-d
Program exited normally.

The message `Program exited normally.' is from GDB; it indicates m4 has finished executing. We can end our GDB session with the GDB quit command.

(gdb) quit

Getting In and Out of GDB

This chapter discusses how to start GDB, and how to get out of it. The essentials are:

  • type `gdb' to start GDB.
  • type quit or C-d to exit.
  • Invoking GDB: How to start GDB
  • Quitting GDB: How to quit GDB
  • Shell Commands: How to use shell commands inside GDB

Invoking GDB

Invoke GDB by running the program gdb. Once started, GDB reads commands from the terminal until you tell it to exit.

You can also run gdb with a variety of arguments and options, to specify more of your debugging environment at the outset.

The command-line options described here are designed to cover a variety of situations; in some environments, some of these options may effectively be unavailable.

The most usual way to start GDB is with one argument, specifying an executable program:

gdb program

You can also start with both an executable program and a core file specified:

gdb program core

You can, instead, specify a process ID as a second argument, if you want to debug a running process:

gdb program 1234

would attach GDB to process 1234 (unless you also have a file named `1234'; GDB does check for a core file first).

Taking advantage of the second command-line argument requires a fairly complete operating system; when you use GDB as a remote debugger attached to a bare board, there may not be any notion of "process", and there is often no way to get a core dump. GDB will warn you if it is unable to attach or to read core dumps.

You can run gdb without printing the front material, which describes GDB's non-warranty, by specifying -silent:

gdb -silent

You can further control how GDB starts up by using command-line options. GDB itself can remind you of the options available.

Type

gdb -help

to display all available options and briefly describe their use (`gdb -h' is a shorter equivalent).

All options and command line arguments you give are processed in sequential order. The order makes a difference when the `-x' option is used.

  • File Options: Choosing files
  • Mode Options: Choosing modes

Choosing files

When GDB starts, it reads any arguments other than options as specifying an executable file and core file (or process ID). This is the same as if the arguments were specified by the `-se' and `-c' options respectively. (GDB reads the first argument that does not have an associated option flag as equivalent to the `-se' option followed by that argument; and the second argument that does not have an associated option flag, if any, as equivalent to the `-c' option followed by that argument.)

If GDB has not been configured to included core file support, such as for most embedded targets, then it will complain about a second argument and ignore it.

Many options have both long and short forms; both are shown in the following list. GDB also recognizes the long forms if you truncate them, so long as enough of the option is present to be unambiguous. (If you prefer, you can flag option arguments with `--' rather than `-', though we illustrate the more usual convention.)

-symbols file
-s file
Read symbol table from file file.
-exec file
-e file
Use file file as the executable file to execute when appropriate, and for examining pure data in conjunction with a core dump.
-se file
Read symbol table from file file and use it as the executable file.
-core file
-c file
Use file file as a core dump to examine.
-c number
Connect to process ID number, as with the attach command (unless there is a file in core-dump format named number, in which case `-c' specifies that file as a core dump to read).
-command file
-x file
Execute GDB commands from file file. See section Command files.
-directory directory
-d directory
Add directory to the path to search for source files.
-m
-mapped
Warning: this option depends on operating system facilities that are not supported on all systems.
If memory-mapped files are available on your system through the mmap system call, you can use this option to have GDB write the symbols from your program into a reusable file in the current directory. If the program you are debugging is called `/tmp/fred', the mapped symbol file is `/tmp/fred.syms'. Future GDB debugging sessions notice the presence of this file, and can quickly map in symbol information from it, rather than reading the symbol table from the executable program. The `.syms' file is specific to the host machine where GDB is run. It holds an exact image of the internal GDB symbol table. It cannot be shared across multiple host platforms.
-r
-readnow
Read each symbol file's entire symbol table immediately, rather than the default, which is to read it incrementally as it is needed. This makes startup slower, but makes future operations faster.

You typically combine the -mapped and -readnow options in order to build a `.syms' file that contains complete symbol information. (See section Commands to specify files, for information on `.syms' files.) A simple GDB invocation to do nothing but build a `.syms' file for future use is:

gdb -batch -nx -mapped -readnow programname

Choosing modes

You can run GDB in various alternative modes--for example, in batch mode or quiet mode.

-nx
-n
Do not execute commands found in any initialization files (normally called `.gdbinit', or `gdb.ini' on PCs). Normally, GDB executes the commands in these files after all the command options and arguments have been processed. See section Command files.
-quiet
-silent
-q
"Quiet". Do not print the introductory and copyright messages. These messages are also suppressed in batch mode.
-batch
Run in batch mode. Exit with status 0 after processing all the command files specified with `-x' (and all commands from initialization files, if not inhibited with `-n'). Exit with nonzero status if an error occurs in executing the GDB commands in the command files. Batch mode may be useful for running GDB as a filter, for example to download and run a program on another computer; in order to make this more useful, the message
Program exited normally.
(which is ordinarily issued whenever a program running under GDB control terminates) is not issued when running in batch mode.
-nowindows
-nw
"No windows". If GDB comes with a graphical user interface (GUI) built in, then this option tells GDB to only use the command-line interface. If no GUI is available, this option has no effect.
-windows
-w
If GDB includes a GUI, then this option requires it to be used if possible.
-cd directory
Run GDB using directory as its working directory, instead of the current directory.
-fullname
-f
GNU Emacs sets this option when it runs GDB as a subprocess. It tells GDB to output the full file name and line number in a standard, recognizable fashion each time a stack frame is displayed (which includes each time your program stops). This recognizable format looks like two `\032' characters, followed by the file name, line number and character position separated by colons, and a newline. The Emacs-to-GDB interface program uses the two `\032' characters as a signal to display the source code for the frame.
-epoch
The Epoch Emacs-GDB interface sets this option when it runs GDB as a subprocess. It tells GDB to modify its print routines so as to allow Epoch to display values of expressions in a separate window.
-annotate level
This option sets the annotation level inside GDB. Its effect is identical to using `set annotate level' (see section GDB Annotations). Annotation level controls how much information does GDB print together with its prompt, values of expressions, source lines, and other types of output. Level 0 is the normal, level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 2 is the maximum annotation suitable for programs that control GDB.
-async
Use the asynchronous event loop for the command-line interface. GDB processes all events, such as user keyboard input, via a special event loop. This allows GDB to accept and process user commands in parallel with the debugged process being run(1), so you don't need to wait for control to return to GDB before you type the next command. (Note: as of version 5.1, the target side of the asynchronous operation is not yet in place, so `-async' does not work fully yet.) When the standard input is connected to a terminal device, GDB uses the asynchronous event loop by default, unless disabled by the `-noasync' option.
-noasync
Disable the asynchronous event loop for the command-line interface.
-baud bps
-b bps
Set the line speed (baud rate or bits per second) of any serial interface used by GDB for remote debugging.
-tty device
-t device
Run using device for your program's standard input and output.
-tui
Activate the Terminal User Interface when starting. The Terminal User Interface manages several text windows on the terminal, showing source, assembly, registers and GDB command outputs (see section GDB Text User Interface). Do not use this option if you run GDB from Emacs (see section Using GDB under GNU Emacs).
-interpreter interp
Use the interpreter interp for interface with the controlling program or device. This option is meant to be set by programs which communicate with GDB using it as a back end. `--interpreter=mi' (or `--interpreter=mi1') causes GDB to use the gdb/mi interface (see section The GDB/MI Interface). The older GDB/MI interface, included in GDB version 5.0 can be selected with `--interpreter=mi0'.
-write
Open the executable and core files for both reading and writing. This is equivalent to the `set write on' command inside GDB (see section Patching programs).
-statistics
This option causes GDB to print statistics about time and memory usage after it completes each command and returns to the prompt.
-version
This option causes GDB to print its version number and no-warranty blurb, and exit.

Quitting GDB

quit [expression]
q
To exit GDB, use the quit command (abbreviated q), or type an end-of-file character (usually C-d). If you do not supply expression, GDB will terminate normally; otherwise it will terminate using the result of expression as the error code.

An interrupt (often C-c) does not exit from GDB, but rather terminates the action of any GDB command that is in progress and returns to GDB command level. It is safe to type the interrupt character at any time because GDB does not allow it to take effect until a time when it is safe.

If you have been using GDB to control an attached process or device, you can release it with the detach command (see section Debugging an already-running process).

Shell commands

If you need to execute occasional shell commands during your debugging session, there is no need to leave or suspend GDB; you can just use the shell command.

shell command string
Invoke a standard shell to execute command string. If it exists, the environment variable SHELL determines which shell to run. Otherwise GDB uses the default shell (`/bin/sh' on Unix systems, `COMMAND.COM' on MS-DOS, etc.).

The utility make is often needed in development environments. You do not have to use the shell command for this purpose in GDB:

make make-args
Execute the make program with the specified arguments. This is equivalent to `shell make make-args'.

GDB Commands

You can abbreviate a GDB command to the first few letters of the command name, if that abbreviation is unambiguous; and you can repeat certain GDB commands by typing just RET. You can also use the TAB key to get GDB to fill out the rest of a word in a command (or to show you the alternatives available, if there is more than one possibility).

  • Command Syntax: How to give commands to GDB
  • Completion: Command completion
  • Help: How to ask GDB for help

Command syntax

A GDB command is a single line of input. There is no limit on how long it can be. It starts with a command name, which is followed by arguments whose meaning depends on the command name. For example, the command step accepts an argument which is the number of times to step, as in `step 5'. You can also use the step command with no arguments. Some commands do not allow any arguments.

GDB command names may always be truncated if that abbreviation is unambiguous. Other possible command abbreviations are listed in the documentation for individual commands. In some cases, even ambiguous abbreviations are allowed; for example, s is specially defined as equivalent to step even though there are other commands whose names start with s. You can test abbreviations by using them as arguments to the help command.

A blank line as input to GDB (typing just RET) means to repeat the previous command. Certain commands (for example, run) will not repeat this way; these are commands whose unintentional repetition might cause trouble and which you are unlikely to want to repeat.

The list and x commands, when you repeat them with RET, construct new arguments rather than repeating exactly as typed. This permits easy scanning of source or memory.

GDB can also use RET in another way: to partition lengthy output, in a way similar to the common utility more (see section Screen size). Since it is easy to press one RET too many in this situation, GDB disables command repetition after any command that generates this sort of display.

Any text from a # to the end of the line is a comment; it does nothing. This is useful mainly in command files (see section Command files).

Command completion

GDB can fill in the rest of a word in a command for you, if there is only one possibility; it can also show you what the valid possibilities are for the next word in a command, at any time. This works for GDB commands, GDB subcommands, and the names of symbols in your program.

Press the TAB key whenever you want GDB to fill out the rest of a word. If there is only one possibility, GDB fills in the word, and waits for you to finish the command (or press RET to enter it). For example, if you type

(gdb) info bre TAB

GDB fills in the rest of the word `breakpoints', since that is the only info subcommand beginning with `bre':

(gdb) info breakpoints

You can either press RET at this point, to run the info breakpoints command, or backspace and enter something else, if `breakpoints' does not look like the command you expected. (If you were sure you wanted info breakpoints in the first place, you might as well just type RET immediately after `info bre', to exploit command abbreviations rather than command completion).

If there is more than one possibility for the next word when you press TAB, GDB sounds a bell. You can either supply more characters and try again, or just press TAB a second time; GDB displays all the possible completions for that word. For example, you might want to set a breakpoint on a subroutine whose name begins with `make_', but when you type b make_TAB GDB just sounds the bell. Typing TAB again displays all the function names in your program that begin with those characters, for example:

(gdb) b make_ TAB
GDB sounds bell; press TAB again, to see:
make_a_section_from_file     make_environ
make_abs_section             make_function_type
make_blockvector             make_pointer_type
make_cleanup                 make_reference_type
make_command                 make_symbol_completion_list
(gdb) b make_

After displaying the available possibilities, GDB copies your partial input (`b make_' in the example) so you can finish the command.

If you just want to see the list of alternatives in the first place, you can press M-? rather than pressing TAB twice. M-? means META ?. You can type this either by holding down a key designated as the META shift on your keyboard (if there is one) while typing ?, or as ESC followed by ?.

Sometimes the string you need, while logically a "word", may contain parentheses or other characters that GDB normally excludes from its notion of a word. To permit word completion to work in this situation, you may enclose words in ' (single quote marks) in GDB commands.

The most likely situation where you might need this is in typing the name of a C++ function. This is because C++ allows function overloading (multiple definitions of the same function, distinguished by argument type). For example, when you want to set a breakpoint you may need to distinguish whether you mean the version of name that takes an int parameter, name(int), or the version that takes a float parameter, name(float). To use the word-completion facilities in this situation, type a single quote ' at the beginning of the function name. This alerts GDB that it may need to consider more information than usual when you press TAB or M-? to request word completion:

(gdb) b 'bubble( M-?
bubble(double,double)    bubble(int,int)
(gdb) b 'bubble(

In some cases, GDB can tell that completing a name requires using quotes. When this happens, GDB inserts the quote for you (while completing as much as it can) if you do not type the quote in the first place:

(gdb) b bub TAB
GDB alters your input line to the following, and rings a bell:
(gdb) b 'bubble(

In general, GDB can tell that a quote is needed (and inserts it) if you have not yet started typing the argument list when you ask for completion on an overloaded symbol.

For more information about overloaded functions, see section C++ expressions. You can use the command set overload-resolution off to disable overload resolution; see section GDB features for C++.

Getting help

You can always ask GDB itself for information on its commands, using the command help.

help
h
You can use help (abbreviated h) with no arguments to display a short list of named classes of commands:
(gdb) help
List of classes of commands:

aliases -- Aliases of other commands
breakpoints -- Making program stop at certain points
data -- Examining data
files -- Specifying and examining files
internals -- Maintenance commands
obscure -- Obscure features
running -- Running the program
stack -- Examining the stack
status -- Status inquiries
support -- Support facilities
tracepoints -- Tracing of program execution without

               stopping the program
user-defined -- User-defined commands

Type "help" followed by a class name for a list of
commands in that class.
Type "help" followed by command name for full
documentation.
Command name abbreviations are allowed if unambiguous.
(gdb)
help class
Using one of the general help classes as an argument, you can get a list of the individual commands in that class. For example, here is the help display for the class status:
(gdb) help status
Status inquiries.

List of commands:

info -- Generic command for showing things
 about the program being debugged
show -- Generic command for showing things
 about the debugger

Type "help" followed by command name for full
documentation.
Command name abbreviations are allowed if unambiguous.
(gdb)
help command
With a command name as help argument, GDB displays a short paragraph on how to use that command.
apropos args
The apropos args command searches through all of the GDB commands, and their documentation, for the regular expression specified in args. It prints out all matches found. For example:
apropos reload
results in:
set symbol-reloading -- Set dynamic symbol table reloading
                                 multiple times in one run
show symbol-reloading -- Show dynamic symbol table reloading
                                 multiple times in one run
complete args
The complete args command lists all the possible completions for the beginning of a command. Use args to specify the beginning of the command you want completed. For example:
complete i
results in:
if
ignore
info
inspect
This is intended for use by GNU Emacs.

In addition to help, you can use the GDB commands info and show to inquire about the state of your program, or the state of GDB itself. Each command supports many topics of inquiry; this manual introduces each of them in the appropriate context. The listings under info and under show in the Index point to all the sub-commands. See section Index.

info
This command (abbreviated i) is for describing the state of your program. For example, you can list the arguments given to your program with info args, list the registers currently in use with info registers, or list the breakpoints you have set with info breakpoints. You can get a complete list of the info sub-commands with help info.
set
You can assign the result of an expression to an environment variable with set. For example, you can set the GDB prompt to a $-sign with set prompt $.
show
In contrast to info, show is for describing the state of GDB itself. You can change most of the things you can show, by using the related command set; for example, you can control what number system is used for displays with set radix, or simply inquire which is currently in use with show radix. To display all the settable parameters and their current values, you can use show with no arguments; you may also use info set. Both commands produce the same display.

Here are three miscellaneous show subcommands, all of which are exceptional in lacking corresponding set commands:

show version
Show what version of GDB is running. You should include this information in GDB bug-reports. If multiple versions of GDB are in use at your site, you may need to determine which version of GDB you are running; as GDB evolves, new commands are introduced, and old ones may wither away. Also, many system vendors ship variant versions of GDB, and there are variant versions of GDB in GNU/Linux distributions as well. The version number is the same as the one announced when you start GDB.
show copying
Display information about permission for copying GDB.
show warranty
Display the GNU "NO WARRANTY" statement, or a warranty, if your version of GDB comes with one.

Running Programs Under GDB

When you run a program under GDB, you must first generate debugging information when you compile it.

You may start GDB with its arguments, if any, in an environment of your choice. If you are doing native debugging, you may redirect your program's input and output, debug an already running process, or kill a child process.

  • Compilation: Compiling for debugging
  • Starting: Starting your program
  • Arguments: Your program's arguments
  • Environment: Your program's environment
  • Working Directory: Your program's working directory
  • Input/Output: Your program's input and output
  • Attach: Debugging an already-running process
  • Kill Process: Killing the child process
  • Threads: Debugging programs with multiple threads
  • Processes: Debugging programs with multiple processes

Compiling for debugging

In order to debug a program effectively, you need to generate debugging information when you compile it. This debugging information is stored in the object file; it describes the data type of each variable or function and the correspondence between source line numbers and addresses in the executable code.

To request debugging information, specify the `-g' option when you run the compiler.

Many C compilers are unable to handle the `-g' and `-O' options together. Using those compilers, you cannot generate optimized executables containing debugging information.

GCC, the GNU C compiler, supports `-g' with or without `-O', making it possible to debug optimized code. We recommend that you always use `-g' whenever you compile a program. You may think your program is correct, but there is no sense in pushing your luck.

When you debug a program compiled with `-g -O', remember that the optimizer is rearranging your code; the debugger shows you what is really there. Do not be too surprised when the execution path does not exactly match your source file! An extreme example: if you define a variable, but never use it, GDB never sees that variable--because the compiler optimizes it out of existence.

Some things do not work as well with `-g -O' as with just `-g', particularly on machines with instruction scheduling. If in doubt, recompile with `-g' alone, and if this fixes the problem, please report it to us as a bug (including a test case!).

Older versions of the GNU C compiler permitted a variant option `-gg' for debugging information. GDB no longer supports this format; if your GNU C compiler has this option, do not use it.

Starting your program

run
r
Use the run command to start your program under GDB. You must first specify the program name (except on VxWorks) with an argument to GDB (see section Getting In and Out of GDB), or by using the file or exec-file command (see section Commands to specify files).

If you are running your program in an execution environment that supports processes, run creates an inferior process and makes that process run your program. (In environments without processes, run jumps to the start of your program.)

The execution of a program is affected by certain information it receives from its superior. GDB provides ways to specify this information, which you must do before starting your program. (You can change it after starting your program, but such changes only affect your program the next time you start it.) This information may be divided into four categories:

The arguments.
Specify the arguments to give your program as the arguments of the run command. If a shell is available on your target, the shell is used to pass the arguments, so that you may use normal conventions (such as wildcard expansion or variable substitution) in describing the arguments. In Unix systems, you can control which shell is used with the SHELL environment variable. See section Your program's arguments.
The environment.
Your program normally inherits its environment from GDB, but you can use the GDB commands set environment and unset environment to change parts of the environment that affect your program. See section Your program's environment.
The working directory.
Your program inherits its working directory from GDB. You can set the GDB working directory with the cd command in GDB. See section Your program's working directory.
The standard input and output.
Your program normally uses the same device for standard input and standard output as GDB is using. You can redirect input and output in the run command line, or you can use the tty command to set a different device for your program. See section Your program's input and output. Warning: While input and output redirection work, you cannot use pipes to pass the output of the program you are debugging to another program; if you attempt this, GDB is likely to wind up debugging the wrong program.

When you issue the run command, your program begins to execute immediately. See section Stopping and Continuing, for discussion of how to arrange for your program to stop. Once your program has stopped, you may call functions in your program, using the print or call commands. See section Examining Data.

If the modification time of your symbol file has changed since the last time GDB read its symbols, GDB discards its symbol table, and reads it again. When it does this, GDB tries to retain your current breakpoints.

Your program's arguments

The arguments to your program can be specified by the arguments of the run command. They are passed to a shell, which expands wildcard characters and performs redirection of I/O, and thence to your program. Your SHELL environment variable (if it exists) specifies what shell GDB uses. If you do not define SHELL, GDB uses the default shell (`/bin/sh' on Unix).

On non-Unix systems, the program is usually invoked directly by GDB, which emulates I/O redirection via the appropriate system calls, and the wildcard characters are expanded by the startup code of the program, not by the shell.

run with no arguments uses the same arguments used by the previous run, or those set by the set args command.

set args
Specify the arguments to be used the next time your program is run. If set args has no arguments, run executes your program with no arguments. Once you have run your program with arguments, using set args before the next run is the only way to run it again without arguments.
show args
Show the arguments to give your program when it is started.

Your program's environment

The environment consists of a set of environment variables and their values. Environment variables conventionally record such things as your user name, your home directory, your terminal type, and your search path for programs to run. Usually you set up environment variables with the shell and they are inherited by all the other programs you run. When debugging, it can be useful to try running your program with a modified environment without having to start GDB over again.

path directory
Add directory to the front of the PATH environment variable (the search path for executables) that will be passed to your program. The value of PATH used by GDB does not change. You may specify several directory names, separated by whitespace or by a system-dependent separator character (`:' on Unix, `;' on MS-DOS and MS-Windows). If directory is already in the path, it is moved to the front, so it is searched sooner. You can use the string `$cwd' to refer to whatever is the current working directory at the time GDB searches the path. If you use `.' instead, it refers to the directory where you executed the path command. GDB replaces `.' in the directory argument (with the current path) before adding directory to the search path.
show paths
Display the list of search paths for executables (the PATH environment variable).
show environment [varname]
Print the value of environment variable varname to be given to your program when it starts. If you do not supply varname, print the names and values of all environment variables to be given to your program. You can abbreviate environment as env.
set environment varname [=value]
Set environment variable varname to value. The value changes for your program only, not for GDB itself. value may be any string; the values of environment variables are just strings, and any interpretation is supplied by your program itself. The value parameter is optional; if it is eliminated, the variable is set to a null value. For example, this command:
set env USER = foo
tells the debugged program, when subsequently run, that its user is named `foo'. (The spaces around `=' are used for clarity here; they are not actually required.)
unset environment varname
Remove variable varname from the environment to be passed to your program. This is different from `set env varname ='; unset environment removes the variable from the environment, rather than assigning it an empty value.

Warning: On Unix systems, GDB runs your program using the shell indicated by your SHELL environment variable if it exists (or /bin/sh if not). If your SHELL variable names a shell that runs an initialization file--such as `.cshrc' for C-shell, or `.bashrc' for BASH--any variables you set in that file affect your program. You may wish to move setting of environment variables to files that are only run when you sign on, such as `.login' or `.profile'.

Your program's working directory

Each time you start your program with run, it inherits its working directory from the current working directory of GDB. The GDB working directory is initially whatever it inherited from its parent process (typically the shell), but you can specify a new working directory in GDB with the cd command.

The GDB working directory also serves as a default for the commands that specify files for GDB to operate on. See section Commands to specify files.

cd directory
Set the GDB working directory to directory.
pwd
Print the GDB working directory.

Your program's input and output

By default, the program you run under GDB does input and output to the same terminal that GDB uses. GDB switches the terminal to its own terminal modes to interact with you, but it records the terminal modes your program was using and switches back to them when you continue running your program.

info terminal
Displays information recorded by GDB about the terminal modes your program is using.

You can redirect your program's input and/or output using shell redirection with the run command. For example,

run > outfile

starts your program, diverting its output to the file `outfile'.

Another way to specify where your program should do input and output is with the tty command. This command accepts a file name as argument, and causes this file to be the default for future run commands. It also resets the controlling terminal for the child process, for future run commands. For example,

tty /dev/ttyb

directs that processes started with subsequent run commands default to do input and output on the terminal `/dev/ttyb' and have that as their controlling terminal.

An explicit redirection in run overrides the tty command's effect on the input/output device, but not its effect on the controlling terminal.

When you use the tty command or redirect input in the run command, only the input for your program is affected. The input for GDB still comes from your terminal.

Debugging an already-running process

attach process-id
This command attaches to a running process--one that was started outside GDB. (info files shows your active targets.) The command takes as argument a process ID. The usual way to find out the process-id of a Unix process is with the ps utility, or with the `jobs -l' shell command. attach does not repeat if you press RET a second time after executing the command.

To use attach, your program must be running in an environment which supports processes; for example, attach does not work for programs on bare-board targets that lack an operating system. You must also have permission to send the process a signal.

When you use attach, the debugger finds the program running in the process first by looking in the current working directory, then (if the program is not found) by using the source file search path (see section Specifying source directories). You can also use the file command to load the program. See section Commands to specify files.

The first thing GDB does after arranging to debug the specified process is to stop it. You can examine and modify an attached process with all the GDB commands that are ordinarily available when you start processes with run. You can insert breakpoints; you can step and continue; you can modify storage. If you would rather the process continue running, you may use the continue command after attaching GDB to the process.

detach
When you have finished debugging the attached process, you can use the detach command to release it from GDB control. Detaching the process continues its execution. After the detach command, that process and GDB become completely independent once more, and you are ready to attach another process or start one with run. detach does not repeat if you press RET again after executing the command.

If you exit GDB or use the run command while you have an attached process, you kill that process. By default, GDB asks for confirmation if you try to do either of these things; you can control whether or not you need to confirm by using the set confirm command (see section Optional warnings and messages).

Killing the child process

kill
Kill the child process in which your program is running under GDB.

This command is useful if you wish to debug a core dump instead of a running process. GDB ignores any core dump file while your program is running.

On some operating systems, a program cannot be executed outside GDB while you have breakpoints set on it inside GDB. You can use the kill command in this situation to permit running your program outside the debugger.

The kill command is also useful if you wish to recompile and relink your program, since on many systems it is impossible to modify an executable file while it is running in a process. In this case, when you next type run, GDB notices that the file has changed, and reads the symbol table again (while trying to preserve your current breakpoint settings).

Debugging programs with multiple threads

In some operating systems, such as HP-UX and Solaris, a single program may have more than one thread of execution. The precise semantics of threads differ from one operating system to another, but in general the threads of a single program are akin to multiple processes--except that they share one address space (that is, they can all examine and modify the same variables). On the other hand, each thread has its own registers and execution stack, and perhaps private memory.

GDB provides these facilities for debugging multi-thread programs:

  • automatic notification of new threads
  • `thread threadno', a command to switch among threads
  • `info threads', a command to inquire about existing threads
  • `thread apply [threadno] [all] args', a command to apply a command to a list of threads
  • thread-specific breakpoints

Warning: These facilities are not yet available on every GDB configuration where the operating system supports threads. If your GDB does not support threads, these commands have no effect. For example, a system without thread support shows no output from `info threads', and always rejects the thread command, like this:

(gdb) info threads
(gdb) thread 1
Thread ID 1 not known.  Use the "info threads" command to
see the IDs of currently known threads.

The GDB thread debugging facility allows you to observe all threads while your program runs--but whenever GDB takes control, one thread in particular is always the focus of debugging. This thread is called the current thread. Debugging commands show program information from the perspective of the current thread.

Whenever GDB detects a new thread in your program, it displays the target system's identification for the thread with a message in the form `[New systag]'. systag is a thread identifier whose form varies depending on the particular system. For example, on LynxOS, you might see

[New process 35 thread 27]

when GDB notices a new thread. In contrast, on an SGI system, the systag is simply something like `process 368', with no further qualifier.

For debugging purposes, GDB associates its own thread number--always a single integer--with each thread in your program.

info threads
Display a summary of all threads currently in your program. GDB displays for each thread (in this order):
  1. the thread number assigned by GDB
  2. the target system's thread identifier (systag)
  3. the current stack frame summary for that thread
An asterisk `*' to the left of the GDB thread number indicates the current thread. For example,
(gdb) info threads
  3 process 35 thread 27  0x34e5 in sigpause ()
  2 process 35 thread 23  0x34e5 in sigpause ()
* 1 process 35 thread 13  main (argc=1, argv=0x7ffffff8)
    at threadtest.c:68

On HP-UX systems:

For debugging purposes, GDB associates its own thread number--a small integer assigned in thread-creation order--with each thread in your program.

Whenever GDB detects a new thread in your program, it displays both GDB's thread number and the target system's identification for the thread with a message in the form `[New systag]'. systag is a thread identifier whose form varies depending on the particular system. For example, on HP-UX, you see

[New thread 2 (system thread 26594)]

when GDB notices a new thread.

info threads
Display a summary of all threads currently in your program. GDB displays for each thread (in this order):
  1. the thread number assigned by GDB
  2. the target system's thread identifier (systag)
  3. the current stack frame summary for that thread
An asterisk `*' to the left of the GDB thread number indicates the current thread. For example,
(gdb) info threads
    * 3 system thread 26607  worker (wptr=0x7b09c318 "@") \

                               at quicksort.c:137
      2 system thread 26606  0x7b0030d8 in __ksleep () \

                               from /usr/lib/libc.2
      1 system thread 27905  0x7b003498 in _brk () \

                               from /usr/lib/libc.2
thread threadno
Make thread number threadno the current thread. The command argument threadno is the internal GDB thread number, as shown in the first field of the `info threads' display. GDB responds by displaying the system identifier of the thread you selected, and its current stack frame summary:
(gdb) thread 2
[Switching to process 35 thread 23]
0x34e5 in sigpause ()
As with the `[New ...]' message, the form of the text after `Switching to' depends on your system's conventions for identifying threads.
thread apply [threadno] [all] args
The thread apply command allows you to apply a command to one or more threads. Specify the numbers of the threads that you want affected with the command argument threadno. threadno is the internal GDB thread number, as shown in the first field of the `info threads' display. To apply a command to all threads, use thread apply all args.

Whenever GDB stops your program, due to a breakpoint or a signal, it automatically selects the thread where that breakpoint or signal happened. GDB alerts you to the context switch with a message of the form `[Switching to systag]' to identify the thread.

See section Stopping and starting multi-thread programs, for more information about how GDB behaves when you stop and start programs with multiple threads.

See section Setting watchpoints, for information about watchpoints in programs with multiple threads.

Debugging programs with multiple processes

On most systems, GDB has no special support for debugging programs which create additional processes using the fork function. When a program forks, GDB will continue to debug the parent process and the child process will run unimpeded. If you have set a breakpoint in any code which the child then executes, the child will get a SIGTRAP signal which (unless it catches the signal) will cause it to terminate.

However, if you want to debug the child process there is a workaround which isn't too painful. Put a call to sleep in the code which the child process executes after the fork. It may be useful to sleep only if a certain environment variable is set, or a certain file exists, so that the delay need not occur when you don't want to run GDB on the child. While the child is sleeping, use the ps program to get its process ID. Then tell GDB (a new invocation of GDB if you are also debugging the parent process) to attach to the child process (see section Debugging an already-running process). From that point on you can debug the child process just like any other process which you attached to.

On HP-UX (11.x and later only?), GDB provides support for debugging programs that create additional processes using the fork or vfork function.

By default, when a program forks, GDB will continue to debug the parent process and the child process will run unimpeded.

If you want to follow the child process instead of the parent process, use the command set follow-fork-mode.

set follow-fork-mode mode
Set the debugger response to a program call of fork or vfork. A call to fork or vfork creates a new process. The mode can be:
parent
The original process is debugged after a fork. The child process runs unimpeded. This is the default.
child
The new process is debugged after a fork. The parent process runs unimpeded.
ask
The debugger will ask for one of the above choices.
show follow-fork-mode
Display the current debugger response to a fork or vfork call.

If you ask to debug a child process and a vfork is followed by an exec, GDB executes the new target up to the first breakpoint in the new target. If you have a breakpoint set on main in your original program, the breakpoint will also be set on the child process's main.

When a child process is spawned by vfork, you cannot debug the child or parent until an exec call completes.

If you issue a run command to GDB after an exec call executes, the new target restarts. To restart the parent process, use the file command with the parent executable name as its argument.

You can use the catch command to make GDB stop whenever a fork, vfork, or exec call is made. See section Setting catchpoints.

Stopping and Continuing

The principal purposes of using a debugger are so that you can stop your program before it terminates; or so that, if your program runs into trouble, you can investigate and find out why.

Inside GDB, your program may stop for any of several reasons, such as a signal, a breakpoint, or reaching a new line after a GDB command such as step. You may then examine and change variables, set new breakpoints or remove old ones, and then continue execution. Usually, the messages shown by GDB provide ample explanation of the status of your program--but you can also explicitly request this information at any time.

info program
Display information about the status of your program: whether it is running or not, what process it is, and why it stopped.
  • Breakpoints: Breakpoints, watchpoints, and catchpoints
  • Continuing and Stepping: Resuming execution
  • Signals: Signals
  • Thread Stops: Stopping and starting multi-thread programs

Breakpoints, watchpoints, and catchpoints

A breakpoint makes your program stop whenever a certain point in the program is reached. For each breakpoint, you can add conditions to control in finer detail whether your program stops. You can set breakpoints with the break command and its variants (see section Setting breakpoints), to specify the place where your program should stop by line number, function name or exact address in the program.

In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set breakpoints in shared libraries before the executable is run. There is a minor limitation on HP-UX systems: you must wait until the executable is run in order to set breakpoints in shared library routines that are not called directly by the program (for example, routines that are arguments in a pthread_create call).

A watchpoint is a special breakpoint that stops your program when the value of an expression changes. You must use a different command to set watchpoints (see section Setting watchpoints), but aside from that, you can manage a watchpoint like any other breakpoint: you enable, disable, and delete both breakpoints and watchpoints using the same commands.

You can arrange to have values from your program displayed automatically whenever GDB stops at a breakpoint. See section Automatic display.

A catchpoint is another special breakpoint that stops your program when a certain kind of event occurs, such as the throwing of a C++ exception or the loading of a library. As with watchpoints, you use a different command to set a catchpoint (see section Setting catchpoints), but aside from that, you can manage a catchpoint like any other breakpoint. (To stop when your program receives a signal, use the handle command; see section Signals.)

GDB assigns a number to each breakpoint, watchpoint, or catchpoint when you create it; these numbers are successive integers starting with one. In many of the commands for controlling various features of breakpoints you use the breakpoint number to say which breakpoint you want to change. Each breakpoint may be enabled or disabled; if disabled, it has no effect on your program until you enable it again.

Some GDB commands accept a range of breakpoints on which to operate. A breakpoint range is either a single breakpoint number, like `5', or two such numbers, in increasing order, separated by a hyphen, like `5-7'. When a breakpoint range is given to a command, all breakpoint in that range are operated on.

  • Set Breaks: Setting breakpoints
  • Set Watchpoints: Setting watchpoints
  • Set Catchpoints: Setting catchpoints
  • Delete Breaks: Deleting breakpoints
  • Disabling: Disabling breakpoints
  • Conditions: Break conditions
  • Break Commands: Breakpoint command lists
  • Breakpoint Menus: Breakpoint menus
  • Error in Breakpoints: "Cannot insert breakpoints"

Setting breakpoints

Breakpoints are set with the break command (abbreviated b). The debugger convenience variable `$bpnum' records the number of the breakpoint you've set most recently; see section Convenience variables, for a discussion of what you can do with convenience variables.

You have several ways to say where the breakpoint should go.

break function
Set a breakpoint at entry to function function. When using source languages that permit overloading of symbols, such as C++, function may refer to more than one possible place to break. See section Breakpoint menus, for a discussion of that situation.
break +offset
break -offset
Set a breakpoint some number of lines forward or back from the position at which execution stopped in the currently selected stack frame. (See section Stack frames, for a description of stack frames.)
break linenum
Set a breakpoint at line linenum in the current source file. The current source file is the last file whose source text was printed. The breakpoint will stop your program just before it executes any of the code on that line.
break filename:linenum
Set a breakpoint at line linenum in source file filename.
break filename:function
Set a breakpoint at entry to function function found in file filename. Specifying a file name as well as a function name is superfluous except when multiple files contain similarly named functions.
break *address
Set a breakpoint at address address. You can use this to set breakpoints in parts of your program which do not have debugging information or source files.
break
When called without any arguments, break sets a breakpoint at the next instruction to be executed in the selected stack frame (see section Examining the Stack). In any selected frame but the innermost, this makes your program stop as soon as control returns to that frame. This is similar to the effect of a finish command in the frame inside the selected frame--except that finish does not leave an active breakpoint. If you use break without an argument in the innermost frame, GDB stops the next time it reaches the current location; this may be useful inside loops. GDB normally ignores breakpoints when it resumes execution, until at least one instruction has been executed. If it did not do this, you would be unable to proceed past a breakpoint without first disabling the breakpoint. This rule applies whether or not the breakpoint already existed when your program stopped.
break ... if cond
Set a breakpoint with condition cond; evaluate the expression cond each time the breakpoint is reached, and stop only if the value is nonzero--that is, if cond evaluates as true. `...' stands for one of the possible arguments described above (or no argument) specifying where to break. See section Break conditions, for more information on breakpoint conditions.
tbreak args
Set a breakpoint enabled only for one stop. args are the same as for the break command, and the breakpoint is set in the same way, but the breakpoint is automatically deleted after the first time your program stops there. See section Disabling breakpoints.
hbreak args
Set a hardware-assisted breakpoint. args are the same as for the break command and the breakpoint is set in the same way, but the breakpoint requires hardware support and some target hardware may not have this support. The main purpose of this is EPROM/ROM code debugging, so you can set a breakpoint at an instruction without changing the instruction. This can be used with the new trap-generation provided by SPARClite DSU and some x86-based targets. These targets will generate traps when a program accesses some data or instruction address that is assigned to the debug registers. However the hardware breakpoint registers can take a limited number of breakpoints. For example, on the DSU, only two data breakpoints can be set at a time, and GDB will reject this command if more than two are used. Delete or disable unused hardware breakpoints before setting new ones (see section Disabling breakpoints). See section Break conditions.
thbreak args
Set a hardware-assisted breakpoint enabled only for one stop. args are the same as for the hbreak command and the breakpoint is set in the same way. However, like the tbreak command, the breakpoint is automatically deleted after the first time your program stops there. Also, like the hbreak command, the breakpoint requires hardware support and some target hardware may not have this support. See section Disabling breakpoints. See also section Break conditions.
rbreak regex
Set breakpoints on all functions matching the regular expression regex. This command sets an unconditional breakpoint on all matches, printing a list of all breakpoints it set. Once these breakpoints are set, they are treated just like the breakpoints set with the break command. You can delete them, disable them, or make them conditional the same way as any other breakpoint. The syntax of the regular expression is the standard one used with tools like `grep'. Note that this is different from the syntax used by shells, so for instance foo* matches all functions that include an fo followed by zero or more os. There is an implicit .* leading and trailing the regular expression you supply, so to match only functions that begin with foo, use ^foo. When debugging C++ programs, rbreak is useful for setting breakpoints on overloaded functions that are not members of any special classes.
info breakpoints [n]
info break [n]
info watchpoints [n]
Print a table of all breakpoints, watchpoints, and catchpoints set and not deleted, with the following columns for each breakpoint:
Breakpoint Numbers
Type
Breakpoint, watchpoint, or catchpoint.
Disposition
Whether the breakpoint is marked to be disabled or deleted when hit.
Enabled or Disabled
Enabled breakpoints are marked with `y'. `n' marks breakpoints that are not enabled.
Address
Where the breakpoint is in your program, as a memory address.
What
Where the breakpoint is in the source for your program, as a file and line number.
If a breakpoint is conditional, info break shows the condition on the line following the affected breakpoint; breakpoint commands, if any, are listed after that. info break with a breakpoint number n as argument lists only that breakpoint. The convenience variable $_ and the default examining-address for the x command are set to the address of the last breakpoint listed (see section Examining memory). info break displays a count of the number of times the breakpoint has been hit. This is especially useful in conjunction with the ignore command. You can ignore a large number of breakpoint hits, look at the breakpoint info to see how many times the breakpoint was hit, and then run again, ignoring one less than that number. This will get you quickly to the last hit of that breakpoint.

GDB allows you to set any number of breakpoints at the same place in your program. There is nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (see section Break conditions).

GDB itself sometimes sets breakpoints in your program for special purposes, such as proper handling of longjmp (in C programs). These internal breakpoints are assigned negative numbers, starting with -1; `info breakpoints' does not display them.

You can see these breakpoints with the GDB maintenance command `maint info breakpoints'.

maint info breakpoints
Using the same format as `info breakpoints', display both the breakpoints you've set explicitly, and those GDB is using for internal purposes. Internal breakpoints are shown with negative breakpoint numbers. The type column identifies what kind of breakpoint is shown:
breakpoint
Normal, explicitly set breakpoint.
watchpoint
Normal, explicitly set watchpoint.
longjmp
Internal breakpoint, used to handle correctly stepping through longjmp calls.
longjmp resume
Internal breakpoint at the target of a longjmp.
until
Temporary internal breakpoint used by the GDB until command.
finish
Temporary internal breakpoint used by the GDB finish command.
shlib events
Shared library events.

Setting watchpoints

You can use a watchpoint to stop execution whenever the value of an expression changes, without having to predict a particular place where this may happen.

Depending on your system, watchpoints may be implemented in software or hardware. GDB does software watchpointing by single-stepping your program and testing the variable's value each time, which is hundreds of times slower than normal execution. (But this may still be worth it, to catch errors where you have no clue what part of your program is the culprit.)

On some systems, such as HP-UX, Linux and some other x86-based targets, GDB includes support for hardware watchpoints, which do not slow down the running of your program.

watch expr
Set a watchpoint for an expression. GDB will break when expr is written into by the program and its value changes.
rwatch expr
Set a watchpoint that will break when watch expr is read by the program.
awatch expr
Set a watchpoint that will break when expr is either read or written into by the program.
info watchpoints
This command prints a list of watchpoints, breakpoints, and catchpoints; it is the same as info break.

GDB sets a hardware watchpoint if possible. Hardware watchpoints execute very quickly, and the debugger reports a change in value at the exact instruction where the change occurs. If GDB cannot set a hardware watchpoint, it sets a software watchpoint, which executes more slowly and reports the change in value at the next statement, not the instruction, after the change occurs.

When you issue the watch command, GDB reports

Hardware watchpoint num: expr

if it was able to set a hardware watchpoint.

Currently, the awatch and rwatch commands can only set hardware watchpoints, because accesses to data that don't change the value of the watched expression cannot be detected without examining every instruction as it is being executed, and GDB does not do that currently. If GDB finds that it is unable to set a hardware breakpoint with the awatch or rwatch command, it will print a message like this:

Expression cannot be implemented with read/access watchpoint.

Sometimes, GDB cannot set a hardware watchpoint because the data type of the watched expression is wider than what a hardware watchpoint on the target machine can handle. For example, some systems can only watch regions that are up to 4 bytes wide; on such systems you cannot set hardware watchpoints for an expression that yields a double-precision floating-point number (which is typically 8 bytes wide). As a work-around, it might be possible to break the large region into a series of smaller ones and watch them with separate watchpoints.

If you set too many hardware watchpoints, GDB might be unable to insert all of them when you resume the execution of your program. Since the precise number of active watchpoints is unknown until such time as the program is about to be resumed, GDB might not be able to warn you about this when you set the watchpoints, and the warning will be printed only when the program is resumed:

Hardware watchpoint num: Could not insert watchpoint

If this happens, delete or disable some of the watchpoints.

The SPARClite DSU will generate traps when a program accesses some data or instruction address that is assigned to the debug registers. For the data addresses, DSU facilitates the watch command. However the hardware breakpoint registers can only take two data watchpoints, and both watchpoints must be the same kind. For example, you can set two watchpoints with watch commands, two with rwatch commands, or two with awatch commands, but you cannot set one watchpoint with one command and the other with a different command. GDB will reject the command if you try to mix watchpoints. Delete or disable unused watchpoint commands before setting new ones.

If you call a function interactively using print or call, any watchpoints you have set will be inactive until GDB reaches another kind of breakpoint or the call completes.

GDB automatically deletes watchpoints that watch local (automatic) variables, or expressions that involve such variables, when they go out of scope, that is, when the execution leaves the block in which these variables were defined. In particular, when the program being debugged terminates, all local variables go out of scope, and so only watchpoints that watch global variables remain set. If you rerun the program, you will need to set all such watchpoints again. One way of doing that would be to set a code breakpoint at the entry to the main function and when it breaks, set all the watchpoints.

Warning: In multi-thread programs, watchpoints have only limited usefulness. With the current watchpoint implementation, GDB can only watch the value of an expression in a single thread. If you are confident that the expression can only change due to the current thread's activity (and if you are also confident that no other thread can become current), then you can use watchpoints as usual. However, GDB may not notice when a non-current thread's activity changes the expression.

HP-UX Warning: In multi-thread programs, software watchpoints have only limited usefulness. If GDB creates a software watchpoint, it can only watch the value of an expression in a single thread. If you are confident that the expression can only change due to the current thread's activity (and if you are also confident that no other thread can become current), then you can use software watchpoints as usual. However, GDB may not notice when a non-current thread's activity changes the expression. (Hardware watchpoints, in contrast, watch an expression in all threads.)

Setting catchpoints

You can use catchpoints to cause the debugger to stop for certain kinds of program events, such as C++ exceptions or the loading of a shared library. Use the catch command to set a catchpoint.

catch event
Stop when event occurs. event can be any of the following:
throw
The throwing of a C++ exception.
catch
The catching of a C++ exception.
exec
A call to exec. This is currently only available for HP-UX.
fork
A call to fork. This is currently only available for HP-UX.
vfork
A call to vfork. This is currently only available for HP-UX.
load
load libname
The dynamic loading of any shared library, or the loading of the library libname. This is currently only available for HP-UX.
unload
unload libname
The unloading of any dynamically loaded shared library, or the unloading of the library libname. This is currently only available for HP-UX.
tcatch event
Set a catchpoint that is enabled only for one stop. The catchpoint is automatically deleted after the first time the event is caught.

Use the info break command to list the current catchpoints.

There are currently some limitations to C++ exception handling (catch throw and catch catch) in GDB:

  • If you call a function interactively, GDB normally returns control to you when the function has finished executing. If the call raises an exception, however, the call may bypass the mechanism that returns control to you and cause your program either to abort or to simply continue running until it hits a breakpoint, catches a signal that GDB is listening for, or exits. This is the case even if you set a catchpoint for the exception; catchpoints on exceptions are disabled within interactive calls.
  • You cannot raise an exception interactively.
  • You cannot install an exception handler interactively.

Sometimes catch is not the best way to debug exception handling: if you need to know exactly where an exception is raised, it is better to stop before the exception handler is called, since that way you can see the stack before any unwinding takes place. If you set a breakpoint in an exception handler instead, it may not be easy to find out where the exception was raised.

To stop just before an exception handler is called, you need some knowledge of the implementation. In the case of GNU C++, exceptions are raised by calling a library function named __raise_exception which has the following ANSI C interface:

    /* addr is where the exception identifier is stored.
       id is the exception identifier.  */
    void __raise_exception (void **addr, void *id);

To make the debugger catch all exceptions before any stack unwinding takes place, set a breakpoint on __raise_exception (see section Breakpoints, watchpoints, and catchpoints).

With a conditional breakpoint (see section Break conditions) that depends on the value of id, you can stop your program when a specific exception is raised. You can use multiple conditional breakpoints to stop your program when any of a number of exceptions are raised.

Deleting breakpoints

It is often necessary to eliminate a breakpoint, watchpoint, or catchpoint once it has done its job and you no longer want your program to stop there. This is called deleting the breakpoint. A breakpoint that has been deleted no longer exists; it is forgotten.

With the clear command you can delete breakpoints according to where they are in your program. With the delete command you can delete individual breakpoints, watchpoints, or catchpoints by specifying their breakpoint numbers.

It is not necessary to delete a breakpoint to proceed past it. GDB automatically ignores breakpoints on the first instruction to be executed when you continue execution without changing the execution address.

clear
Delete any breakpoints at the next instruction to be executed in the selected stack frame (see section Selecting a frame). When the innermost frame is selected, this is a good way to delete a breakpoint where your program just stopped.
clear function
clear filename:function
Delete any breakpoints set at entry to the function function.
clear linenum
clear filename:linenum
Delete any breakpoints set at or within the code of the specified line.
delete [breakpoints] [range...]
Delete the breakpoints, watchpoints, or catchpoints of the breakpoint ranges specified as arguments. If no argument is specified, delete all breakpoints (GDB asks confirmation, unless you have set confirm off). You can abbreviate this command as d.

Disabling breakpoints

Rather than deleting a breakpoint, watchpoint, or catchpoint, you might prefer to disable it. This makes the breakpoint inoperative as if it had been deleted, but remembers the information on the breakpoint so that you can enable it again later.

You disable and enable breakpoints, watchpoints, and catchpoints with the enable and disable commands, optionally specifying one or more breakpoint numbers as arguments. Use info break or info watch to print a list of breakpoints, watchpoints, and catchpoints if you do not know which numbers to use.

A breakpoint, watchpoint, or catchpoint can have any of four different states of enablement:

  • Enabled. The breakpoint stops your program. A breakpoint set with the break command starts out in this state.
  • Disabled. The breakpoint has no effect on your program.
  • Enabled once. The breakpoint stops your program, but then becomes disabled.
  • Enabled for deletion. The breakpoint stops your program, but immediately after it does so it is deleted permanently. A breakpoint set with the tbreak command starts out in this state.

You can use the following commands to enable or disable breakpoints, watchpoints, and catchpoints:

disable [breakpoints] [range...]
Disable the specified breakpoints--or all breakpoints, if none are listed. A disabled breakpoint has no effect but is not forgotten. All options such as ignore-counts, conditions and commands are remembered in case the breakpoint is enabled again later. You may abbreviate disable as dis.
enable [breakpoints] [range...]
Enable the specified breakpoints (or all defined breakpoints). They become effective once again in stopping your program.
enable [breakpoints] once range...
Enable the specified breakpoints temporarily. GDB disables any of these breakpoints immediately after stopping your program.
enable [breakpoints] delete range...
Enable the specified breakpoints to work once, then die. GDB deletes any of these breakpoints as soon as your program stops there.

Except for a breakpoint set with tbreak (see section Setting breakpoints), breakpoints that you set are initially enabled; subsequently, they become disabled or enabled only when you use one of the commands above. (The command until can set and delete a breakpoint of its own, but it does not change the state of your other breakpoints; see section Continuing and stepping.)

Break conditions

The simplest sort of breakpoint breaks every time your program reaches a specified place. You can also specify a condition for a breakpoint. A condition is just a Boolean expression in your programming language (see section Expressions). A breakpoint with a condition evaluates the expression each time your program reaches it, and your program stops only if the condition is true.

This is the converse of using assertions for program validation; in that situation, you want to stop when the assertion is violated--that is, when the condition is false. In C, if you want to test an assertion expressed by the condition assert, you should set the condition `! assert' on the appropriate breakpoint.

Conditions are also accepted for watchpoints; you may not need them, since a watchpoint is inspecting the value of an expression anyhow--but it might be simpler, say, to just set a watchpoint on a variable name, and specify a condition that tests whether the new value is an interesting one.

Break conditions can have side effects, and may even call functions in your program. This can be useful, for example, to activate functions that log program progress, or to use your own print functions to format special data structures. The effects are completely predictable unless there is another enabled breakpoint at the same address. (In that case, GDB might see the other breakpoint first and stop your program without checking the condition of this one.) Note that breakpoint commands are usually more convenient and flexible than break conditions for the purpose of performing side effects when a breakpoint is reached (see section Breakpoint command lists).

Break conditions can be specified when a breakpoint is set, by using `if' in the arguments to the break command. See section Setting breakpoints. They can also be changed at any time with the condition command.

You can also use the if keyword with the watch command. The catch command does not recognize the if keyword; condition is the only way to impose a further condition on a catchpoint.

condition bnum expression
Specify expression as the break condition for breakpoint, watchpoint, or catchpoint number bnum. After you set a condition, breakpoint bnum stops your program only if the value of expression is true (nonzero, in C). When you use condition, GDB checks expression immediately for syntactic correctness, and to determine whether symbols in it have referents in the context of your breakpoint. If expression uses symbols not referenced in the context of the breakpoint, GDB prints an error message:
No symbol "foo" in current context.
GDB does not actually evaluate expression at the time the condition command (or a command that sets a breakpoint with a condition, like break if ...) is given, however. See section Expressions.
condition bnum
Remove the condition from breakpoint number bnum. It becomes an ordinary unconditional breakpoint.

A special case of a breakpoint condition is to stop only when the breakpoint has been reached a certain number of times. This is so useful that there is a special way to do it, using the ignore count of the breakpoint. Every breakpoint has an ignore count, which is an integer. Most of the time, the ignore count is zero, and therefore has no effect. But if your program reaches a breakpoint whose ignore count is positive, then instead of stopping, it just decrements the ignore count by one and continues. As a result, if the ignore count value is n, the breakpoint does not stop the next n times your program reaches it.

ignore bnum count
Set the ignore count of breakpoint number bnum to count. The next count times the breakpoint is reached, your program's execution does not stop; other than to decrement the ignore count, GDB takes no action. To make the breakpoint stop the next time it is reached, specify a count of zero. When you use continue to resume execution of your program from a breakpoint, you can specify an ignore count directly as an argument to continue, rather than using ignore. See section Continuing and stepping. If a breakpoint has a positive ignore count and a condition, the condition is not checked. Once the ignore count reaches zero, GDB resumes checking the condition. You could achieve the effect of the ignore count with a condition such as `$foo-- <= 0' using a debugger convenience variable that is decremented each time. See section Convenience variables.

Ignore counts apply to breakpoints, watchpoints, and catchpoints.

Breakpoint command lists

You can give any breakpoint (or watchpoint or catchpoint) a series of commands to execute when your program stops due to that breakpoint. For example, you might want to print the values of certain expressions, or enable other breakpoints.

commands [bnum]
... command-list ...
end
Specify a list of commands for breakpoint number bnum. The commands themselves appear on the following lines. Type a line containing just end to terminate the commands. To remove all commands from a breakpoint, type commands and follow it immediately with end; that is, give no commands. With no bnum argument, commands refers to the last breakpoint, watchpoint, or catchpoint set (not to the breakpoint most recently encountered).

Pressing RET as a means of repeating the last GDB command is disabled within a command-list.

You can use breakpoint commands to start your program up again. Simply use the continue command, or step, or any other command that resumes execution.

Any other commands in the command list, after a command that resumes execution, are ignored. This is because any time you resume execution (even with a simple next or step), you may encounter another breakpoint--which could have its own command list, leading to ambiguities about which list to execute.

If the first command you specify in a command list is silent, the usual message about stopping at a breakpoint is not printed. This may be desirable for breakpoints that are to print a specific message and then continue. If none of the remaining commands print anything, you see no sign that the breakpoint was reached. silent is meaningful only at the beginning of a breakpoint command list.

The commands echo, output, and printf allow you to print precisely controlled output, and are often useful in silent breakpoints. See section Commands for controlled output.

For example, here is how you could use breakpoint commands to print the value of x at entry to foo whenever x is positive.

break foo if x>0
commands
silent
printf "x is %d\n",x
cont
end

One application for breakpoint commands is to compensate for one bug so you can test for another. Put a breakpoint just after the erroneous line of code, give it a condition to detect the case in which something erroneous has been done, and give it commands to assign correct values to any variables that need them. End with the continue command so that your program does not stop, and start with the silent command so that no output is produced. Here is an example:

break 403
commands
silent
set x = y + 4
cont
end

Breakpoint menus

Some programming languages (notably C++) permit a single function name to be defined several times, for application in different contexts. This is called overloading. When a function name is overloaded, `break function' is not enough to tell GDB where you want a breakpoint. If you realize this is a problem, you can use something like `break function(types)' to specify which particular version of the function you want. Otherwise, GDB offers you a menu of numbered choices for different possible breakpoints, and waits for your selection with the prompt `>'. The first two options are always `[0] cancel' and `[1] all'. Typing 1 sets a breakpoint at each definition of function, and typing 0 aborts the break command without setting any new breakpoints.

For example, the following session excerpt shows an attempt to set a breakpoint at the overloaded symbol String::after. We choose three particular definitions of that function name:

(gdb) b String::after
[0] cancel
[1] all
[2] file:String.cc; line number:867
[3] file:String.cc; line number:860
[4] file:String.cc; line number:875
[5] file:String.cc; line number:853
[6] file:String.cc; line number:846
[7] file:String.cc; line number:735
> 2 4 6
Breakpoint 1 at 0xb26c: file String.cc, line 867.
Breakpoint 2 at 0xb344: file String.cc, line 875.
Breakpoint 3 at 0xafcc: file String.cc, line 846.
Multiple breakpoints were set.
Use the "delete" command to delete unwanted
 breakpoints.
(gdb)

"Cannot insert breakpoints"

Under some operating systems, breakpoints cannot be used in a program if any other process is running that program. In this situation, attempting to run or continue a program with a breakpoint causes GDB to print an error message:

Cannot insert breakpoints.
The same program may be running in another process.

When this happens, you have three ways to proceed:

  1. Remove or disable the breakpoints, then continue.
  2. Suspend GDB, and copy the file containing your program to a new name. Resume GDB and use the exec-file command to specify that GDB should run your program under that name. Then start your program again.
  3. Relink your program so that the text segment is nonsharable, using the linker option `-N'. The operating system limitation may not apply to nonsharable executables.

A similar message can be printed if you request too many active hardware-assisted breakpoints and watchpoints:

Stopped; cannot insert breakpoints.
You may have requested too many hardware breakpoints and watchpoints.

This message is printed when you attempt to resume the program, since only then GDB knows exactly how many hardware breakpoints and watchpoints it needs to insert.

When this message is printed, you need to disable or remove some of the hardware-assisted breakpoints and watchpoints, and then continue.

Continuing and stepping

Continuing means resuming program execution until your program completes normally. In contrast, stepping means executing just one more "step" of your program, where "step" may mean either one line of source code, or one machine instruction (depending on what particular command you use). Either when continuing or when stepping, your program may stop even sooner, due to a breakpoint or a signal. (If it stops due to a signal, you may want to use handle, or use `signal 0' to resume execution. See section Signals.)

continue [ignore-count]
c [ignore-count]
fg [ignore-count]
Resume program execution, at the address where your program last stopped; any breakpoints set at that address are bypassed. The optional argument ignore-count allows you to specify a further number of times to ignore a breakpoint at this location; its effect is like that of ignore (see section Break conditions). The argument ignore-count is meaningful only when your program stopped due to a breakpoint. At other times, the argument to continue is ignored. The synonyms c and fg (for foreground, as the debugged program is deemed to be the foreground program) are provided purely for convenience, and have exactly the same behavior as continue.

To resume execution at a different place, you can use return (see section Returning from a function) to go back to the calling function; or jump (see section Continuing at a different address) to go to an arbitrary location in your program.

A typical technique for using stepping is to set a breakpoint (see section Breakpoints, watchpoints, and catchpoints) at the beginning of the function or the section of your program where a problem is believed to lie, run your program until it stops at that breakpoint, and then step through the suspect area, examining the variables that are interesting, until you see the problem happen.

step
Continue running your program until control reaches a different source line, then stop it and return control to GDB. This command is abbreviated s.

Warning: If you use the step command while control is within a function that was compiled without debugging information, execution proceeds until control reaches a function that does have debugging information. Likewise, it will not step into a function which is compiled without debugging information. To step through functions without debugging information, use the stepi command, described below.

The step command only stops at the first instruction of a source line. This prevents the multiple stops that could otherwise occur in switch statements, for loops, etc. step continues to stop if a function that has debugging information is called within the line. In other words, step steps inside any functions called within the line. Also, the step command only enters a function if there is line number information for the function. Otherwise it acts like the next command. This avoids problems when using cc -gl on MIPS machines. Previously, step entered subroutines if there was any debugging information about the routine.
step count
Continue running as in step, but do so count times. If a breakpoint is reached, or a signal not related to stepping occurs before count steps, stepping stops right away.
next [count]
Continue to the next source line in the current (innermost) stack frame. This is similar to step, but function calls that appear within the line of code are executed without stopping. Execution stops when control reaches a different line of code at the original stack level that was executing when you gave the next command. This command is abbreviated n. An argument count is a repeat count, as for step. The next command only stops at the first instruction of a source line. This prevents multiple stops that could otherwise occur in switch statements, for loops, etc.
set step-mode
set step-mode on
The set step-mode on command causes the step command to stop at the first instruction of a function which contains no debug line information rather than stepping over it. This is useful in cases where you may be interested in inspecting the machine instructions of a function which has no symbolic info and do not want GDB to automatically skip over this function.
set step-mode off
Causes the step command to step over any functions which contains no debug information. This is the default.
finish
Continue running until just after function in the selected stack frame returns. Print the returned value (if any). Contrast this with the return command (see section Returning from a function).
until
u
Continue running until a source line past the current line, in the current stack frame, is reached. This command is used to avoid single stepping through a loop more than once. It is like the next command, except that when until encounters a jump, it automatically continues execution until the program counter is greater than the address of the jump. This means that when you reach the end of a loop after single stepping though it, until makes your program continue execution until it exits the loop. In contrast, a next command at the end of a loop simply steps back to the beginning of the loop, which forces you to step through the next iteration. until always stops your program if it attempts to exit the current stack frame. until may produce somewhat counterintuitive results if the order of machine code does not match the order of the source lines. For example, in the following excerpt from a debugging session, the f (frame) command shows that execution is stopped at line 206; yet when we use until, we get to line 195:
(gdb) f
#0  main (argc=4, argv=0xf7fffae8) at m4.c:206
206                 expand_input();
(gdb) until
195             for ( ; argc > 0; NEXTARG) {
This happened because, for execution efficiency, the compiler had generated code for the loop closure test at the end, rather than the start, of the loop--even though the test in a C for-loop is written before the body of the loop. The until command appeared to step back to the beginning of the loop when it advanced to this expression; however, it has not really gone to an earlier statement--not in terms of the actual machine code. until with no argument works by means of single instruction stepping, and hence is slower than until with an argument.
until location
u location
Continue running your program until either the specified location is reached, or the current stack frame returns. location is any of the forms of argument acceptable to break (see section Setting breakpoints). This form of the command uses breakpoints, and hence is quicker than until without an argument.
stepi
stepi arg
si
Execute one machine instruction, then stop and return to the debugger. It is often useful to do `display/i $pc' when stepping by machine instructions. This makes GDB automatically display the next instruction to be executed, each time your program stops. See section Automatic display. An argument is a repeat count, as in step.
nexti
nexti arg
ni
Execute one machine instruction, but if it is a function call, proceed until the function returns. An argument is a repeat count, as in next.

Signals

A signal is an asynchronous event that can happen in a program. The operating system defines the possible kinds of signals, and gives each kind a name and a number. For example, in Unix SIGINT is the signal a program gets when you type an interrupt character (often C-c); SIGSEGV is the signal a program gets from referencing a place in memory far away from all the areas in use; SIGALRM occurs when the alarm clock timer goes off (which happens only if your program has requested an alarm).

Some signals, including SIGALRM, are a normal part of the functioning of your program. Others, such as SIGSEGV, indicate errors; these signals are fatal (they kill your program immediately) if the program has not specified in advance some other way to handle the signal. SIGINT does not indicate an error in your program, but it is normally fatal so it can carry out the purpose of the interrupt: to kill the program.

GDB has the ability to detect any occurrence of a signal in your program. You can tell GDB in advance what to do for each kind of signal.

Normally, GDB is set up to let the non-erroneous signals like SIGALRM be silently passed to your program (so as not to interfere with their role in the program's functioning) but to stop your program immediately whenever an error signal happens. You can change these settings with the handle command.

info signals
info handle
Print a table of all the kinds of signals and how GDB has been told to handle each one. You can use this to see the signal numbers of all the defined types of signals. info handle is an alias for info signals.
handle signal keywords...
Change the way GDB handles signal signal. signal can be the number of a signal or its name (with or without the `SIG' at the beginning); a list of signal numbers of the form `low-high'; or the word `all', meaning all the known signals. The keywords say what change to make.

The keywords allowed by the handle command can be abbreviated. Their full names are:

nostop
GDB should not stop your program when this signal happens. It may still print a message telling you that the signal has come in.
stop
GDB should stop your program when this signal happens. This implies the print keyword as well.
print
GDB should print a message when this signal happens.
noprint
GDB should not mention the occurrence of the signal at all. This implies the nostop keyword as well.
pass
noignore
GDB should allow your program to see this signal; your program can handle the signal, or else it may terminate if the signal is fatal and not handled. pass and noignore are synonyms.
nopass
ignore
GDB should not allow your program to see this signal. nopass and ignore are synonyms.

When a signal stops your program, the signal is not visible to the program until you continue. Your program sees the signal then, if pass is in effect for the signal in question at that time. In other words, after GDB reports a signal, you can use the handle command with pass or nopass to control whether your program sees that signal when you continue.

The default is set to nostop, noprint, pass for non-erroneous signals such as SIGALRM, SIGWINCH and SIGCHLD, and to stop, print, pass for the erroneous signals.

You can also use the signal command to prevent your program from seeing a signal, or cause it to see a signal it normally would not see, or to give it any signal at any time. For example, if your program stopped due to some sort of memory reference error, you might store correct values into the erroneous variables and continue, hoping to see more execution; but your program would probably terminate immediately as a result of the fatal signal once it saw the signal. To prevent this, you can continue with `signal 0'. See section Giving your program a signal.

Stopping and starting multi-thread programs

When your program has multiple threads (see section Debugging programs with multiple threads), you can choose whether to set breakpoints on all threads, or on a particular thread.

break linespec thread threadno
break linespec thread threadno if ...
linespec specifies source lines; there are several ways of writing them, but the effect is always to specify some source line. Use the qualifier `thread threadno' with a breakpoint command to specify that you only want GDB to stop the program when a particular thread reaches this breakpoint. threadno is one of the numeric thread identifiers assigned by GDB, shown in the first column of the `info threads' display. If you do not specify `thread threadno' when you set a breakpoint, the breakpoint applies to all threads of your program. You can use the thread qualifier on conditional breakpoints as well; in this case, place `thread threadno' before the breakpoint condition, like this:
(gdb) break frik.c:13 thread 28 if bartab > lim

Whenever your program stops under GDB for any reason, all threads of execution stop, not just the current thread. This allows you to examine the overall state of the program, including switching between threads, without worrying that things may change underfoot.

Conversely, whenever you restart the program, all threads start executing. This is true even when single-stepping with commands like step or next.

In particular, GDB cannot single-step all threads in lockstep. Since thread scheduling is up to your debugging target's operating system (not controlled by GDB), other threads may execute more than one statement while the current thread completes a single step. Moreover, in general other threads stop in the middle of a statement, rather than at a clean statement boundary, when the program stops.

You might even find your program stopped in another thread after continuing or even single-stepping. This happens whenever some other thread runs into a breakpoint, a signal, or an exception before the first thread completes whatever you requested.

On some OSes, you can lock the OS scheduler and thus allow only a single thread to run.

set scheduler-locking mode
Set the scheduler locking mode. If it is off, then there is no locking and any thread may run at any time. If on, then only the current thread may run when the inferior is resumed. The step mode optimizes for single-stepping. It stops other threads from "seizing the prompt" by preempting the current thread while you are stepping. Other threads will only rarely (or never) get a chance to run when you step. They are more likely to run when you `next' over a function call, and they are completely free to run when you use commands like `continue', `until', or `finish'. However, unless another thread hits a breakpoint during its timeslice, they will never steal the GDB prompt away from the thread that you are debugging.
show scheduler-locking
Display the current scheduler locking mode.

Examining the Stack

When your program has stopped, the first thing you need to know is where it stopped and how it got there.

Each time your program performs a function call, information about the call is generated. That information includes the location of the call in your program, the arguments of the call, and the local variables of the function being called. The information is saved in a block of data called a stack frame. The stack frames are allocated in a region of memory called the call stack.

When your program stops, the GDB commands for examining the stack allow you to see all of this information.

One of the stack frames is selected by GDB and many GDB commands refer implicitly to the selected frame. In particular, whenever you ask GDB for the value of a variable in your program, the value is found in the selected frame. There are special GDB commands to select whichever frame you are interested in. See section Selecting a frame.

When your program stops, GDB automatically selects the currently executing frame and describes it briefly, similar to the frame command (see section Information about a frame).

  • Frames: Stack frames
  • Backtrace: Backtraces
  • Selection: Selecting a frame
  • Frame Info: Information on a frame

Stack frames

The call stack is divided up into contiguous pieces called stack frames, or frames for short; each frame is the data associated with one call to one function. The frame contains the arguments given to the function, the function's local variables, and the address at which the function is executing.

When your program is started, the stack has only one frame, that of the function main. This is called the initial frame or the outermost frame. Each time a function is called, a new frame is made. Each time a function returns, the frame for that function invocation is eliminated. If a function is recursive, there can be many frames for the same function. The frame for the function in which execution is actually occurring is called the innermost frame. This is the most recently created of all the stack frames that still exist.

Inside your program, stack frames are identified by their addresses. A stack frame consists of many bytes, each of which has its own address; each kind of computer has a convention for choosing one byte whose address serves as the address of the frame. Usually this address is kept in a register called the frame pointer register while execution is going on in that frame.

GDB assigns numbers to all existing stack frames, starting with zero for the innermost frame, one for the frame that called it, and so on upward. These numbers do not really exist in your program; they are assigned by GDB to give you a way of designating stack frames in GDB commands.

Some compilers provide a way to compile functions so that they operate without stack frames. (For example, the gcc option

`-fomit-frame-pointer'

generates functions without a frame.) This is occasionally done with heavily used library functions to save the frame setup time. GDB has limited facilities for dealing with these function invocations. If the innermost function invocation has no stack frame, GDB nevertheless regards it as though it had a separate frame, which is numbered zero as usual, allowing correct tracing of the function call chain. However, GDB has no provision for frameless functions elsewhere in the stack.

frame args
The frame command allows you to move from one stack frame to another, and to print the stack frame you select. args may be either the address of the frame or the stack frame number. Without an argument, frame prints the current stack frame.
select-frame
The select-frame command allows you to move from one stack frame to another without printing the frame. This is the silent version of frame.

Backtraces

A backtrace is a summary of how your program got where it is. It shows one line per frame, for many frames, starting with the currently executing frame (frame zero), followed by its caller (frame one), and on up the stack.

backtrace
bt
Print a backtrace of the entire stack: one line per frame for all frames in the stack. You can stop the backtrace at any time by typing the system interrupt character, normally C-c.
backtrace n
bt n
Similar, but print only the innermost n frames.
backtrace -n
bt -n
Similar, but print only the outermost n frames.

The names where and info stack (abbreviated info s) are additional aliases for backtrace.

Each line in the backtrace shows the frame number and the function name. The program counter value is also shown--unless you use set print address off. The backtrace also shows the source file name and line number, as well as the arguments to the function. The program counter value is omitted if it is at the beginning of the code for that line number.

Here is an example of a backtrace. It was made with the command `bt 3', so it shows the innermost three frames.

#0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
    at builtin.c:993
#1  0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
#2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
    at macro.c:71
(More stack frames follow...)

The display for frame zero does not begin with a program counter value, indicating that your program has stopped at the beginning of the code for line 993 of builtin.c.

Selecting a frame

Most commands for examining the stack and other data in your program work on whichever stack frame is selected at the moment. Here are the commands for selecting a stack frame; all of them finish by printing a brief description of the stack frame just selected.

frame n
f n
Select frame number n. Recall that frame zero is the innermost (currently executing) frame, frame one is the frame that called the innermost one, and so on. The highest-numbered frame is the one for main.
frame addr
f addr
Select the frame at address addr. This is useful mainly if the chaining of stack frames has been damaged by a bug, making it impossible for GDB to assign numbers properly to all frames. In addition, this can be useful when your program has multiple stacks and switches between them. On the SPARC architecture, frame needs two addresses to select an arbitrary frame: a frame pointer and a stack pointer. On the MIPS and Alpha architecture, it needs two addresses: a stack pointer and a program counter. On the 29k architecture, it needs three addresses: a register stack pointer, a program counter, and a memory stack pointer.
up n
Move n frames up the stack. For positive numbers n, this advances toward the outermost frame, to higher frame numbers, to frames that have existed longer. n defaults to one.
down n
Move n frames down the stack. For positive numbers n, this advances toward the innermost frame, to lower frame numbers, to frames that were created more recently. n defaults to one. You may abbreviate down as do.

All of these commands end by printing two lines of output describing the frame. The first line shows the frame number, the function name, the arguments, and the source file and line number of execution in that frame. The second line shows the text of that source line.

For example:

(gdb) up
#1  0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
    at env.c:10
10              read_input_file (argv[i]);

After such a printout, the list command with no arguments prints ten lines centered on the point of execution in the frame. See section Printing source lines.

up-silently n
down-silently n
These two commands are variants of up and down, respectively; they differ in that they do their work silently, without causing display of the new frame. They are intended primarily for use in GDB command scripts, where the output might be unnecessary and distracting.

Information about a frame

There are several other commands to print information about the selected stack frame.

frame
f
When used without any argument, this command does not change which frame is selected, but prints a brief description of the currently selected stack frame. It can be abbreviated f. With an argument, this command is used to select a stack frame. See section Selecting a frame.
info frame
info f
This command prints a verbose description of the selected stack frame, including:
  • the address of the frame
  • the address of the next frame down (called by this frame)
  • the address of the next frame up (caller of this frame)
  • the language in which the source code corresponding to this frame is written
  • the address of the frame's arguments
  • the address of the frame's local variables
  • the program counter saved in it (the address of execution in the caller frame)
  • which registers were saved in the frame
The verbose description is useful when something has gone wrong that has made the stack format fail to fit the usual conventions.
info frame addr
info f addr
Print a verbose description of the frame at address addr, without selecting that frame. The selected frame remains unchanged by this command. This requires the same kind of address (more than one for some architectures) that you specify in the frame command. See section Selecting a frame.
info args
Print the arguments of the selected frame, each on a separate line.
info locals
Print the local variables of the selected frame, each on a separate line. These are all variables (declared either static or automatic) accessible at the point of execution of the selected frame.
info catch
Print a list of all the exception handlers that are active in the current stack frame at the current point of execution. To see other exception handlers, visit the associated frame (using the up, down, or frame commands); then type info catch. See section Setting catchpoints.

Examining Source Files

GDB can print parts of your program's source, since the debugging information recorded in the program tells GDB what source files were used to build it. When your program stops, GDB spontaneously prints the line where it stopped. Likewise, when you select a stack frame (see section Selecting a frame), GDB prints the line where execution in that frame has stopped. You can print other portions of source files by explicit command.

If you use GDB through its GNU Emacs interface, you may prefer to use Emacs facilities to view source; see section Using GDB under GNU Emacs.

  • List: Printing source lines
  • Search: Searching source files
  • Source Path: Specifying source directories
  • Machine Code: Source and machine code

Printing source lines

To print lines from a source file, use the list command (abbreviated l). By default, ten lines are printed. There are several ways to specify what part of the file you want to print.

Here are the forms of the list command most commonly used:

list linenum
Print lines centered around line number linenum in the current source file.
list function
Print lines centered around the beginning of function function.
list
Print more lines. If the last lines printed were printed with a list command, this prints lines following the last lines printed; however, if the last line printed was a solitary line printed as part of displaying a stack frame (see section Examining the Stack), this prints lines centered around that line.
list -
Print lines just before the lines last printed.

By default, GDB prints ten source lines with any of these forms of the list command. You can change this using set listsize:

set listsize count
Make the list command display count source lines (unless the list argument explicitly specifies some other number).
show listsize
Display the number of lines that list prints.

Repeating a list command with RET discards the argument, so it is equivalent to typing just list. This is more useful than listing the same lines again. An exception is made for an argument of `-'; that argument is preserved in repetition so that each repetition moves up in the source file.

In general, the list command expects you to supply zero, one or two linespecs. Linespecs specify source lines; there are several ways of writing them, but the effect is always to specify some source line. Here is a complete description of the possible arguments for list:

list linespec
Print lines centered around the line specified by linespec.
list first,last
Print lines from first to last. Both arguments are linespecs.
list ,last
Print lines ending with last.
list first,
Print lines starting with first.
list +
Print lines just after the lines last printed.
list -
Print lines just before the lines last printed.
list
As described in the preceding table.

Here are the ways of specifying a single source line--all the kinds of linespec.

number
Specifies line number of the current source file. When a list command has two linespecs, this refers to the same source file as the first linespec.
+offset
Specifies the line offset lines after the last line printed. When used as the second linespec in a list command that has two, this specifies the line offset lines down from the first linespec.
-offset
Specifies the line offset lines before the last line printed.
filename:number
Specifies line number in the source file filename.
function
Specifies the line that begins the body of the function function. For example: in C, this is the line with the open brace.
filename:function
Specifies the line of the open-brace that begins the body of the function function in the file filename. You only need the file name with a function name to avoid ambiguity when there are identically named functions in different source files.
*address
Specifies the line containing the program address address. address may be any expression.

Searching source files

There are two commands for searching through the current source file for a regular expression.

forward-search regexp
search regexp
The command `forward-search regexp' checks each line, starting with the one following the last line listed, for a match for regexp. It lists the line that is found. You can use the synonym `search regexp' or abbreviate the command name as fo.
reverse-search regexp
The command `reverse-search regexp' checks each line, starting with the one before the last line listed and going backward, for a match for regexp. It lists the line that is found. You can abbreviate this command as rev.

Specifying source directories

Executable programs sometimes do not record the directories of the source files from which they were compiled, just the names. Even when they do, the directories could be moved between the compilation and your debugging session. GDB has a list of directories to search for source files; this is called the source path. Each time GDB wants a source file, it tries all the directories in the list, in the order they are present in the list, until it finds a file with the desired name. Note that the executable search path is not used for this purpose. Neither is the current working directory, unless it happens to be in the source path.

If GDB cannot find a source file in the source path, and the object program records a directory, GDB tries that directory too. If the source path is empty, and there is no record of the compilation directory, GDB looks in the current directory as a last resort.

Whenever you reset or rearrange the source path, GDB clears out any information it has cached about where source files are found and where each line is in the file.

When you start GDB, its source path includes only `cdir' and `cwd', in that order. To add other directories, use the directory command.

directory dirname ...
dir dirname ...
Add directory dirname to the front of the source path. Several directory names may be given to this command, separated by `:' (`;' on MS-DOS and MS-Windows, where `:' usually appears as part of absolute file names) or whitespace. You may specify a directory that is already in the source path; this moves it forward, so GDB searches it sooner. You can use the string `$cdir' to refer to the compilation directory (if one is recorded), and `$cwd' to refer to the current working directory. `$cwd' is not the same as `.'---the former tracks the current working directory as it changes during your GDB session, while the latter is immediately expanded to the current directory at the time you add an entry to the source path.
directory
Reset the source path to empty again. This requires confirmation.
show directories
Print the source path: show which directories it contains.

If your source path is cluttered with directories that are no longer of interest, GDB may sometimes cause confusion by finding the wrong versions of source. You can correct the situation as follows:

  1. Use directory with no argument to reset the source path to empty.
  2. Use directory with suitable arguments to reinstall the directories you want in the source path. You can add all the directories in one command.

Source and machine code

You can use the command info line to map source lines to program addresses (and vice versa), and the command disassemble to display a range of addresses as machine instructions. When run under GNU Emacs mode, the info line command causes the arrow to point to the line specified. Also, info line prints addresses in symbolic form as well as hex.

info line linespec
Print the starting and ending addresses of the compiled code for source line linespec. You can specify source lines in any of the ways understood by the list command (see section Printing source lines).

For example, we can use info line to discover the location of the object code for the first line of function m4_changequote:

(gdb) info line m4_changequote
Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.

We can also inquire (using *addr as the form for linespec) what source line covers a particular address:

(gdb) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.

After info line, the default address for the x command is changed to the starting address of the line, so that `x/i' is sufficient to begin examining the machine code (see section Examining memory). Also, this address is saved as the value of the convenience variable $_ (see section Convenience variables).

disassemble
This specialized command dumps a range of memory as machine instructions. The default memory range is the function surrounding the program counter of the selected frame. A single argument to this command is a program counter value; GDB dumps the function surrounding this value. Two arguments specify a range of addresses (first inclusive, second exclusive) to dump.

The following example shows the disassembly of a range of addresses of HP PA-RISC 2.0 code:

(gdb) disas 0x32c4 0x32e4
Dump of assembler code from 0x32c4 to 0x32e4:
0x32c4 <main+204>:      addil 0,dp
0x32c8 <main+208>:      ldw 0x22c(sr0,r1),r26
0x32cc <main+212>:      ldil 0x3000,r31
0x32d0 <main+216>:      ble 0x3f8(sr4,r31)
0x32d4 <main+220>:      ldo 0(r31),rp
0x32d8 <main+224>:      addil -0x800,dp
0x32dc <main+228>:      ldo 0x588(r1),r26
0x32e0 <main+232>:      ldil 0x3000,r31
End of assembler dump.

Some architectures have more than one commonly-used set of instruction mnemonics or other syntax.

set disassembly-flavor instruction-set
Select the instruction set to use when disassembling the program via the disassemble or x/i commands. Currently this command is only defined for the Intel x86 family. You can set instruction-set to either intel or att. The default is att, the AT&T flavor used by default by Unix assemblers for x86-based targets.

Examining Data

The usual way to examine data in your program is with the print command (abbreviated p), or its synonym inspect. It evaluates and prints the value of an expression of the language your program is written in (see section Using GDB with Different Languages).

print expr
print /f expr
expr is an expression (in the source language). By default the value of expr is printed in a format appropriate to its data type; you can choose a different format by specifying `/f', where f is a letter specifying the format; see section Output formats.
print
print /f
If you omit expr, GDB displays the last value again (from the value history; see section Value history). This allows you to conveniently inspect the same value in an alternative format.

A more low-level way of examining data is with the x command. It examines data in memory at a specified address and prints it in a specified format. See section Examining memory.

If you are interested in information about types, or about how the fields of a struct or a class are declared, use the ptype exp command rather than print. See section Examining the Symbol Table.

  • Expressions: Expressions
  • Variables: Program variables
  • Arrays: Artificial arrays
  • Output Formats: Output formats
  • Memory: Examining memory
  • Auto Display: Automatic display
  • Print Settings: Print settings
  • Value History: Value history
  • Convenience Vars: Convenience variables
  • Registers: Registers
  • Floating Point Hardware: Floating point hardware
  • Memory Region Attributes: Memory region attributes

Expressions

print and many other GDB commands accept an expression and compute its value. Any kind of constant, variable or operator defined by the programming language you are using is valid in an expression in GDB. This includes conditional expressions, function calls, casts and string constants. It unfortunately does not include symbols defined by preprocessor #define commands.

GDB supports array constants in expressions input by the user. The syntax is {element, element...}. For example, you can use the command print {1, 2, 3} to build up an array in memory that is malloced in the target program.

Because C is so widespread, most of the expressions shown in examples in this manual are in C. See section Using GDB with Different Languages, for information on how to use expressions in other languages.

In this section, we discuss operators that you can use in GDB expressions regardless of your programming language.

Casts are supported in all languages, not just in C, because it is so useful to cast a number into a pointer in order to examine a structure at that address in memory.

GDB supports these operators, in addition to those common to programming languages:

@
`@' is a binary operator for treating parts of memory as arrays. See section Artificial arrays, for more information.
::
`::' allows you to specify a variable in terms of the file or function where it is defined. See section Program variables.
{type} addr
Refers to an object of type type stored at address addr in memory. addr may be any expression whose value is an integer or pointer (but parentheses are required around binary operators, just as in a cast). This construct is allowed regardless of what kind of data is normally supposed to reside at addr.

Program variables

The most common kind of expression to use is the name of a variable in your program.

Variables in expressions are understood in the selected stack frame (see section Selecting a frame); they must be either:

  • global (or file-static)

or

  • visible according to the scope rules of the programming language from the point of execution in that frame

This means that in the function

foo (a)
     int a;
{
  bar (a);
  {
    int b = test ();
    bar (b);
  }
}

you can examine and use the variable a whenever your program is executing within the function foo, but you can only use or examine the variable b while your program is executing inside the block where b is declared.

There is an exception: you can refer to a variable or function whose scope is a single source file even if the current execution point is not in this file. But it is possible to have more than one such variable or function with the same name (in different source files). If that happens, referring to that name has unpredictable effects. If you wish, you can specify a static variable in a particular function or file, using the colon-colon notation:

file::variable
function::variable

Here file or function is the name of the context for the static variable. In the case of file names, you can use quotes to make sure GDB parses the file name as a single word--for example, to print a global value of x defined in `f2.c':

(gdb) p 'f2.c'::x

This use of `::' is very rarely in conflict with the very similar use of the same notation in C++. GDB also supports use of the C++ scope resolution operator in GDB expressions.

Warning: Occasionally, a local variable may appear to have the wrong value at certain points in a function--just after entry to a new scope, and just before exit.

You may see this problem when you are stepping by machine instructions. This is because, on most machines, it takes more than one instruction to set up a stack frame (including local variable definitions); if you are stepping by machine instructions, variables may appear to have the wrong values until the stack frame is completely built. On exit, it usually also takes more than one machine instruction to destroy a stack frame; after you begin stepping through that group of instructions, local variable definitions may be gone.

This may also happen when the compiler does significant optimizations. To be sure of always seeing accurate values, turn off all optimization when compiling.

Another possible effect of compiler optimizations is to optimize unused variables out of existence, or assign variables to registers (as opposed to memory addresses). Depending on the support for such cases offered by the debug info format used by the compiler, GDB might not be able to display values for such local variables. If that happens, GDB will print a message like this:

No symbol "foo" in current context.

To solve such problems, either recompile without optimizations, or use a different debug info format, if the compiler supports several such formats. For example, GCC, the GNU C/C++ compiler usually supports the `-gstabs' option. `-gstabs' produces debug info in a format that is superior to formats such as COFF. You may be able to use DWARF2 (`-gdwarf-2'), which is also an effective form for debug info. See section `Options for Debugging Your Program or GNU CC' in Using GNU CC, for more information.

Artificial arrays

It is often useful to print out several successive objects of the same type in memory; a section of an array, or an array of dynamically determined size for which only a pointer exists in the program.

You can do this by referring to a contiguous span of memory as an artificial array, using the binary operator `@'. The left operand of `@' should be the first element of the desired array and be an individual object. The right operand should be the desired length of the array. The result is an array value whose elements are all of the type of the left argument. The first element is actually the left argument; the second element comes from bytes of memory immediately following those that hold the first element, and so on. Here is an example. If a program says

int *array = (int *) malloc (len * sizeof (int));

you can print the contents of array with

p *array@len

The left operand of `@' must reside in memory. Array values made with `@' in this way behave just like other arrays in terms of subscripting, and are coerced to pointers when used in expressions. Artificial arrays most often appear in expressions via the value history (see section Value history), after printing one out.

Another way to create an artificial array is to use a cast. This re-interprets a value as if it were an array. The value need not be in memory:

(gdb) p/x (short[2])0x12345678
$1 = {0x1234, 0x5678}

As a convenience, if you leave the array length out (as in `(type[])value') GDB calculates the size to fill the value (as `sizeof(value)/sizeof(type)':

(gdb) p/x (short[])0x12345678
$2 = {0x1234, 0x5678}

Sometimes the artificial array mechanism is not quite enough; in moderately complex data structures, the elements of interest may not actually be adjacent--for example, if you are interested in the values of pointers in an array. One useful work-around in this situation is to use a convenience variable (see section Convenience variables) as a counter in an expression that prints the first interesting value, and then repeat that expression via RET. For instance, suppose you have an array dtab of pointers to structures, and you are interested in the values of a field fv in each structure. Here is an example of what you might type:

set $i = 0
p dtab[$i++]->fv
RET
RET
...

Output formats

By default, GDB prints a value according to its data type. Sometimes this is not what you want. For example, you might want to print a number in hex, or a pointer in decimal. Or you might want to view data in memory at a certain address as a character string or as an instruction. To do these things, specify an output format when you print a value.

The simplest use of output formats is to say how to print a value already computed. This is done by starting the arguments of the print command with a slash and a format letter. The format letters supported are:

x
Regard the bits of the value as an integer, and print the integer in hexadecimal.
d
Print as integer in signed decimal.
u
Print as integer in unsigned decimal.
o
Print as integer in octal.
t
Print as integer in binary. The letter `t' stands for "two". (2)
a
Print as an address, both absolute in hexadecimal and as an offset from the nearest preceding symbol. You can use this format used to discover where (in what function) an unknown address is located:
(gdb) p/a 0x54320
$3 = 0x54320 <_initialize_vx+396>
The command info symbol 0x54320 yields similar results. See section Examining the Symbol Table.
c
Regard as an integer and print it as a character constant.
f
Regard the bits of the value as a floating point number and print using typical floating point syntax.

For example, to print the program counter in hex (see section Registers), type

p/x $pc

Note that no space is required before the slash; this is because command names in GDB cannot contain a slash.

To reprint the last value in the value history with a different format, you can use the print command with just a format and no expression. For example, `p/x' reprints the last value in hex.

Examining memory

You can use the command x (for "examine") to examine memory in any of several formats, independently of your program's data types.

x/nfu addr
x addr
x
Use the x command to examine memory.

n, f, and u are all optional parameters that specify how much memory to display and how to format it; addr is an expression giving the address where you want to start displaying memory. If you use defaults for nfu, you need not type the slash `/'. Several commands set convenient defaults for addr.

n, the repeat count
The repeat count is a decimal integer; the default is 1. It specifies how much memory (counting by units u) to display.
f, the display format
The display format is one of the formats used by print, `s' (null-terminated string), or `i' (machine instruction). The default is `x' (hexadecimal) initially. The default changes each time you use either x or print.
u, the unit size
The unit size is any of
b
Bytes.
h
Halfwords (two bytes).
w
Words (four bytes). This is the initial default.
g
Giant words (eight bytes).
Each time you specify a unit size with x, that size becomes the default unit the next time you use x. (For the `s' and `i' formats, the unit size is ignored and is normally not written.)
addr, starting display address
addr is the address where you want GDB to begin displaying memory. The expression need not have a pointer value (though it may); it is always interpreted as an integer address of a byte of memory. See section Expressions, for more information on expressions. The default for addr is usually just after the last address examined--but several other commands also set the default address: info breakpoints (to the address of the last breakpoint listed), info line (to the starting address of a line), and print (if you use it to display a value from memory).

For example, `x/3uh 0x54320' is a request to display three halfwords (h) of memory, formatted as unsigned decimal integers (`u'), starting at address 0x54320. `x/4xw $sp' prints the four words (`w') of memory above the stack pointer (here, `$sp'; see section Registers) in hexadecimal (`x').

Since the letters indicating unit sizes are all distinct from the letters specifying output formats, you do not have to remember whether unit size or format comes first; either order works. The output specifications `4xw' and `4wx' mean exactly the same thing. (However, the count n must come first; `wx4' does not work.)

Even though the unit size u is ignored for the formats `s' and `i', you might still want to use a count n; for example, `3i' specifies that you want to see three machine instructions, including any operands. The command disassemble gives an alternative way of inspecting machine instructions; see section Source and machine code.

All the defaults for the arguments to x are designed to make it easy to continue scanning memory with minimal specifications each time you use x. For example, after you have inspected three machine instructions with `x/3i addr', you can inspect the next seven with just `x/7'. If you use RET to repeat the x command, the repeat count n is used again; the other arguments default as for successive uses of x.

The addresses and contents printed by the x command are not saved in the value history because there is often too much of them and they would get in the way. Instead, GDB makes these values available for subsequent use in expressions as values of the convenience variables $_ and $__. After an x command, the last address examined is available for use in expressions in the convenience variable $_. The contents of that address, as examined, are available in the convenience variable $__.

If the x command has a repeat count, the address and contents saved are from the last memory unit printed; this is not the same as the last address printed if several units were printed on the last line of output.

Automatic display

If you find that you want to print the value of an expression frequently (to see how it changes), you might want to add it to the automatic display list so that GDB prints its value each time your program stops. Each expression added to the list is given a number to identify it; to remove an expression from the list, you specify that number. The automatic display looks like this:

2: foo = 38
3: bar[5] = (struct hack *) 0x3804

This display shows item numbers, expressions and their current values. As with displays you request manually using x or print, you can specify the output format you prefer; in fact, display decides whether to use print or x depending on how elaborate your format specification is--it uses x if you specify a unit size, or one of the two formats (`i' and `s') that are only supported by x; otherwise it uses print.

display expr
Add the expression expr to the list of expressions to display each time your program stops. See section Expressions. display does not repeat if you press RET again after using it.
display/fmt expr
For fmt specifying only a display format and not a size or count, add the expression expr to the auto-display list but arrange to display it each time in the specified format fmt. See section Output formats.
display/fmt addr
For fmt `i' or `s', or including a unit-size or a number of units, add the expression addr as a memory address to be examined each time your program stops. Examining means in effect doing `x/fmt addr'. See section Examining memory.

For example, `display/i $pc' can be helpful, to see the machine instruction about to be executed each time execution stops (`$pc' is a common name for the program counter; see section Registers).

undisplay dnums...
delete display dnums...
Remove item numbers dnums from the list of expressions to display. undisplay does not repeat if you press RET after using it. (Otherwise you would just get the error `No display number ...'.)
disable display dnums...
Disable the display of item numbers dnums. A disabled display item is not printed automatically, but is not forgotten. It may be enabled again later.
enable display dnums...
Enable display of item numbers dnums. It becomes effective once again in auto display of its expression, until you specify otherwise.
display
Display the current values of the expressions on the list, just as is done when your program stops.
info display
Print the list of expressions previously set up to display automatically, each one with its item number, but without showing the values. This includes disabled expressions, which are marked as such. It also includes expressions which would not be displayed right now because they refer to automatic variables not currently available.

If a display expression refers to local variables, then it does not make sense outside the lexical context for which it was set up. Such an expression is disabled when execution enters a context where one of its variables is not defined. For example, if you give the command display last_char while inside a function with an argument last_char, GDB displays this argument while your program continues to stop inside that function. When it stops elsewhere--where there is no variable last_char---the display is disabled automatically. The next time your program stops where last_char is meaningful, you can enable the display expression once again.

Print settings

GDB provides the following ways to control how arrays, structures, and symbols are printed.

These settings are useful for debugging programs in any language:

set print address
set print address on
GDB prints memory addresses showing the location of stack traces, structure values, pointer values, breakpoints, and so forth, even when it also displays the contents of those addresses. The default is on. For example, this is what a stack frame display looks like with set print address on:
(gdb) f
#0  set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
    at input.c:530
530         if (lquote != def_lquote)
set print address off
Do not print addresses when displaying their contents. For example, this is the same stack frame displayed with set print address off:
(gdb) set print addr off
(gdb) f
#0  set_quotes (lq="<<", rq=">>") at input.c:530
530         if (lquote != def_lquote)
You can use `set print address off' to eliminate all machine dependent displays from the GDB interface. For example, with print address off, you should get the same text for backtraces on all machines--whether or not they involve pointer arguments.
show print address
Show whether or not addresses are to be printed.

When GDB prints a symbolic address, it normally prints the closest earlier symbol plus an offset. If that symbol does not uniquely identify the address (for example, it is a name whose scope is a single source file), you may need to clarify. One way to do this is with info line, for example `info line *0x4537'. Alternately, you can set GDB to print the source file and line number when it prints a symbolic address:

set print symbol-filename on
Tell GDB to print the source file name and line number of a symbol in the symbolic form of an address.
set print symbol-filename off
Do not print source file name and line number of a symbol. This is the default.
show print symbol-filename
Show whether or not GDB will print the source file name and line number of a symbol in the symbolic form of an address.

Another situation where it is helpful to show symbol filenames and line numbers is when disassembling code; GDB shows you the line number and source file that corresponds to each instruction.

Also, you may wish to see the symbolic form only if the address being printed is reasonably close to the closest earlier symbol:

set print max-symbolic-offset max-offset
Tell GDB to only display the symbolic form of an address if the offset between the closest earlier symbol and the address is less than max-offset. The default is 0, which tells GDB to always print the symbolic form of an address if any symbol precedes it.
show print max-symbolic-offset
Ask how large the maximum offset is that GDB prints in a symbolic address.

If you have a pointer and you are not sure where it points, try `set print symbol-filename on'. Then you can determine the name and source file location of the variable where it points, using `p/a pointer'. This interprets the address in symbolic form. For example, here GDB shows that a variable ptt points at another variable t, defined in `hi2.c':

(gdb) set print symbol-filename on
(gdb) p/a ptt
$4 = 0xe008 <t in hi2.c>

Warning: For pointers that point to a local variable, `p/a' does not show the symbol name and filename of the referent, even with the appropriate set print options turned on.

Other settings control how different kinds of objects are printed:

set print array
set print array on
Pretty print arrays. This format is more convenient to read, but uses more space. The default is off.
set print array off
Return to compressed format for arrays.
show print array
Show whether compressed or pretty format is selected for displaying arrays.
set print elements number-of-elements
Set a limit on how many elements of an array GDB will print. If GDB is printing a large array, it stops printing after it has printed the number of elements set by the set print elements command. This limit also applies to the display of strings. When GDB starts, this limit is set to 200. Setting number-of-elements to zero means that the printing is unlimited.
show print elements
Display the number of elements of a large array that GDB will print. If the number is 0, then the printing is unlimited.
set print null-stop
Cause GDB to stop printing the characters of an array when the first NULL is encountered. This is useful when large arrays actually contain only short strings. The default is off.
set print pretty on
Cause GDB to print structures in an indented format with one member per line, like this:
$1 = {
  next = 0x0,
  flags = {
    sweet = 1,
    sour = 1
  },
  meat = 0x54 "Pork"
}
set print pretty off
Cause GDB to print structures in a compact format, like this:
$1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \
meat = 0x54 "Pork"}
This is the default format.
show print pretty
Show which format GDB is using to print structures.
set print sevenbit-strings on
Print using only seven-bit characters; if this option is set, GDB displays any eight-bit characters (in strings or character values) using the notation \nnn. This setting is best if you are working in English (ASCII) and you use the high-order bit of characters as a marker or "meta" bit.
set print sevenbit-strings off
Print full eight-bit characters. This allows the use of more international character sets, and is the default.
show print sevenbit-strings
Show whether or not GDB is printing only seven-bit characters.
set print union on
Tell GDB to print unions which are contained in structures. This is the default setting.
set print union off
Tell GDB not to print unions which are contained in structures.
show print union
Ask GDB whether or not it will print unions which are contained in structures. For example, given the declarations
typedef enum {Tree, Bug} Species;
typedef enum {Big_tree, Acorn, Seedling} Tree_forms;
typedef enum {Caterpillar, Cocoon, Butterfly}
              Bug_forms;

struct thing {
  Species it;
  union {
    Tree_forms tree;
    Bug_forms bug;
  } form;
};

struct thing foo = {Tree, {Acorn}};
with set print union on in effect `p foo' would print
$1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}
and with set print union off in effect it would print
$1 = {it = Tree, form = {...}}

These settings are of interest when debugging C++ programs:

set print demangle
set print demangle on
Print C++ names in their source form rather than in the encoded ("mangled") form passed to the assembler and linker for type-safe linkage. The default is on.
show print demangle
Show whether C++ names are printed in mangled or demangled form.
set print asm-demangle
set print asm-demangle on
Print C++ names in their source form rather than their mangled form, even in assembler code printouts such as instruction disassemblies. The default is off.
show print asm-demangle
Show whether C++ names in assembly listings are printed in mangled or demangled form.
set demangle-style style
Choose among several encoding schemes used by different compilers to represent C++ names. The choices for style are currently:
auto
Allow GDB to choose a decoding style by inspecting your program.
gnu
Decode based on the GNU C++ compiler (g++) encoding algorithm. This is the default.
hp
Decode based on the HP ANSI C++ (aCC) encoding algorithm.
lucid
Decode based on the Lucid C++ compiler (lcc) encoding algorithm.
arm
Decode using the algorithm in the C++ Annotated Reference Manual. Warning: this setting alone is not sufficient to allow debugging cfront-generated executables. GDB would require further enhancement to permit that.
If you omit style, you will see a list of possible formats.
show demangle-style
Display the encoding style currently in use for decoding C++ symbols.
set print object
set print object on
When displaying a pointer to an object, identify the actual (derived) type of the object rather than the declared type, using the virtual function table.
set print object off
Display only the declared type of objects, without reference to the virtual function table. This is the default setting.
show print object
Show whether actual, or declared, object types are displayed.
set print static-members
set print static-members on
Print static members when displaying a C++ object. The default is on.
set print static-members off
Do not print static members when displaying a C++ object.
show print static-members
Show whether C++ static members are printed, or not.
set print vtbl
set print vtbl on
Pretty print C++ virtual function tables. The default is off. (The vtbl commands do not work on programs compiled with the HP ANSI C++ compiler (aCC).)
set print vtbl off
Do not pretty print C++ virtual function tables.
show print vtbl
Show whether C++ virtual function tables are pretty printed, or not.

Value history

Values printed by the print command are saved in the GDB value history. This allows you to refer to them in other expressions. Values are kept until the symbol table is re-read or discarded (for example with the file or symbol-file commands). When the symbol table changes, the value history is discarded, since the values may contain pointers back to the types defined in the symbol table.

The values printed are given history numbers by which you can refer to them. These are successive integers starting with one. print shows you the history number assigned to a value by printing `$num = ' before the value; here num is the history number.

To refer to any previous value, use `$' followed by the value's history number. The way print labels its output is designed to remind you of this. Just $ refers to the most recent value in the history, and $$ refers to the value before that. $$n refers to the nth value from the end; $$2 is the value just prior to $$, $$1 is equivalent to $$, and $$0 is equivalent to $.

For example, suppose you have just printed a pointer to a structure and want to see the contents of the structure. It suffices to type

p *$

If you have a chain of structures where the component next points to the next one, you can print the contents of the next one with this:

p *$.next

You can print successive links in the chain by repeating this command--which you can do by just typing RET.

Note that the history records values, not expressions. If the value of x is 4 and you type these commands:

print x
set x=5

then the value recorded in the value history by the print command remains 4 even though the value of x has changed.

show values
Print the last ten values in the value history, with their item numbers. This is like `p $$9' repeated ten times, except that show values does not change the history.
show values n
Print ten history values centered on history item number n.
show values +
Print ten history values just after the values last printed. If no more values are available, show values + produces no display.

Pressing RET to repeat show values n has exactly the same effect as `show values +'.

Convenience variables

GDB provides convenience variables that you can use within GDB to hold on to a value and refer to it later. These variables exist entirely within GDB; they are not part of your program, and setting a convenience variable has no direct effect on further execution of your program. That is why you can use them freely.

Convenience variables are prefixed with `$'. Any name preceded by `$' can be used for a convenience variable, unless it is one of the predefined machine-specific register names (see section Registers). (Value history references, in contrast, are numbers preceded by `$'. See section Value history.)

You can save a value in a convenience variable with an assignment expression, just as you would set a variable in your program. For example:

set $foo = *object_ptr

would save in $foo the value contained in the object pointed to by object_ptr.

Using a convenience variable for the first time creates it, but its value is void until you assign a new value. You can alter the value with another assignment at any time.

Convenience variables have no fixed types. You can assign a convenience variable any type of value, including structures and arrays, even if that variable already has a value of a different type. The convenience variable, when used as an expression, has the type of its current value.

show convenience
Print a list of convenience variables used so far, and their values. Abbreviated show conv.

One of the ways to use a convenience variable is as a counter to be incremented or a pointer to be advanced. For example, to print a field from successive elements of an array of structures:

set $i = 0
print bar[$i++]->contents

Repeat that command by typing RET.

Some convenience variables are created automatically by GDB and given values likely to be useful.

$_
The variable $_ is automatically set by the x command to the last address examined (see section Examining memory). Other commands which provide a default address for x to examine also set $_ to that address; these commands include info line and info breakpoint. The type of $_ is void * except when set by the x command, in which case it is a pointer to the type of $__.
$__
The variable $__ is automatically set by the x command to the value found in the last address examined. Its type is chosen to match the format in which the data was printed.
$_exitcode
The variable $_exitcode is automatically set to the exit code when the program being debugged terminates.

On HP-UX systems, if you refer to a function or variable name that begins with a dollar sign, GDB searches for a user or system name first, before it searches for a convenience variable.

Registers

You can refer to machine register contents, in expressions, as variables with names starting with `$'. The names of registers are different for each machine; use info registers to see the names used on your machine.

info registers
Print the names and values of all registers except floating-point registers (in the selected stack frame).
info all-registers
Print the names and values of all registers, including floating-point registers.
info registers regname ...
Print the relativized value of each specified register regname. As discussed in detail below, register values are normally relative to the selected stack frame. regname may be any register name valid on the machine you are using, with or without the initial `$'.

GDB has four "standard" register names that are available (in expressions) on most machines--whenever they do not conflict with an architecture's canonical mnemonics for registers. The register names $pc and $sp are used for the program counter register and the stack pointer. $fp is used for a register that contains a pointer to the current stack frame, and $ps is used for a register that contains the processor status. For example, you could print the program counter in hex with

p/x $pc

or print the instruction to be executed next with

x/i $pc

or add four to the stack pointer(3) with

set $sp += 4

Whenever possible, these four standard register names are available on your machine even though the machine has different canonical mnemonics, so long as there is no conflict. The info registers command shows the canonical names. For example, on the SPARC, info registers displays the processor status register as $psr but you can also refer to it as $ps; and on x86-based machines $ps is an alias for the EFLAGS register.

GDB always considers the contents of an ordinary register as an integer when the register is examined in this way. Some machines have special registers which can hold nothing but floating point; these registers are considered to have floating point values. There is no way to refer to the contents of an ordinary register as floating point value (although you can print it as a floating point value with `print/f $regname').

Some registers have distinct "raw" and "virtual" data formats. This means that the data format in which the register contents are saved by the operating system is not the same one that your program normally sees. For example, the registers of the 68881 floating point coprocessor are always saved in "extended" (raw) format, but all C programs expect to work with "double" (virtual) format. In such cases, GDB normally works with the virtual format only (the format that makes sense for your program), but the info registers command prints the data in both formats.

Normally, register values are relative to the selected stack frame (see section Selecting a frame). This means that you get the value that the register would contain if all stack frames farther in were exited and their saved registers restored. In order to see the true contents of hardware registers, you must select the innermost frame (with `frame 0').

However, GDB must deduce where registers are saved, from the machine code generated by your compiler. If some registers are not saved, or if GDB is unable to locate the saved registers, the selected stack frame makes no difference.

Floating point hardware

Depending on the configuration, GDB may be able to give you more information about the status of the floating point hardware.

info float
Display hardware-dependent information about the floating point unit. The exact contents and layout vary depending on the floating point chip. Currently, `info float' is supported on the ARM and x86 machines.

Memory Region Attributes

Memory region attributes allow you to describe special handling required by regions of your target's memory. GDB uses attributes to determine whether to allow certain types of memory accesses; whether to use specific width accesses; and whether to cache target memory.

Defined memory regions can be individually enabled and disabled. When a memory region is disabled, GDB uses the default attributes when accessing memory in that region. Similarly, if no memory regions have been defined, GDB uses the default attributes when accessing all memory.

When a memory region is defined, it is given a number to identify it; to enable, disable, or remove a memory region, you specify that number.

mem address1 address1 attributes...
Define memory region bounded by address1 and address2 with attributes attributes....
delete mem nums...
Remove memory region numbers nums.
disable mem nums...
Disable memory region numbers nums. A disabled memory region is not forgotten. It may be enabled again later.
enable mem nums...
Enable memory region numbers nums.
info mem
Print a table of all defined memory regions, with the following columns for each region.
Memory Region Number
Enabled or Disabled.
Enabled memory regions are marked with `y'. Disabled memory regions are marked with `n'.
Lo Address
The address defining the inclusive lower bound of the memory region.
Hi Address
The address defining the exclusive upper bound of the memory region.
Attributes
The list of attributes set for this memory region.

Attributes

Memory Access Mode

The access mode attributes set whether GDB may make read or write accesses to a memory region.

While these attributes prevent GDB from performing invalid memory accesses, they do nothing to prevent the target system, I/O DMA, etc. from accessing memory.

ro
Memory is read only.
wo
Memory is write only.
rw
Memory is read/write (default).

Memory Access Size

The acccess size attributes tells GDB to use specific sized accesses in the memory region. Often memory mapped device registers require specific sized accesses. If no access size attribute is specified, GDB may use accesses of any size.

8
Use 8 bit memory accesses.
16
Use 16 bit memory accesses.
32
Use 32 bit memory accesses.
64
Use 64 bit memory accesses.

Data Cache

The data cache attributes set whether GDB will cache target memory. While this generally improves performance by reducing debug protocol overhead, it can lead to incorrect results because GDB does not know about volatile variables or memory mapped device registers.

cache
Enable GDB to cache target memory.
nocache (default)
Disable GDB from caching target memory.

Tracepoints

In some applications, it is not feasible for the debugger to interrupt the program's execution long enough for the developer to learn anything helpful about its behavior. If the program's correctness depends on its real-time behavior, delays introduced by a debugger might cause the program to change its behavior drastically, or perhaps fail, even when the code itself is correct. It is useful to be able to observe the program's behavior without interrupting it.

Using GDB's trace and collect commands, you can specify locations in the program, called tracepoints, and arbitrary expressions to evaluate when those tracepoints are reached. Later, using the tfind command, you can examine the values those expressions had when the program hit the tracepoints. The expressions may also denote objects in memory--structures or arrays, for example--whose values GDB should record; while visiting a particular tracepoint, you may inspect those objects as if they were in memory at that moment. However, because GDB records these values without interacting with you, it can do so quickly and unobtrusively, hopefully not disturbing the program's behavior.

The tracepoint facility is currently available only for remote targets. See section Specifying a Debugging Target. In addition, your remote target must know how to collect trace data. This functionality is implemented in the remote stub; however, none of the stubs distributed with GDB support tracepoints as of this writing.

This chapter describes the tracepoint commands and features.

  • Set Tracepoints
  • Analyze Collected Data
  • Tracepoint Variables

Commands to Set Tracepoints

Before running such a trace experiment, an arbitrary number of tracepoints can be set. Like a breakpoint (see section Setting breakpoints), a tracepoint has a number assigned to it by GDB. Like with breakpoints, tracepoint numbers are successive integers starting from one. Many of the commands associated with tracepoints take the tracepoint number as their argument, to identify which tracepoint to work on.

For each tracepoint, you can specify, in advance, some arbitrary set of data that you want the target to collect in the trace buffer when it hits that tracepoint. The collected data can include registers, local variables, or global data. Later, you can use GDB commands to examine the values these data had at the time the tracepoint was hit.

This section describes commands to set tracepoints and associated conditions and actions.

  • Create and Delete Tracepoints
  • Enable and Disable Tracepoints
  • Tracepoint Passcounts
  • Tracepoint Actions
  • Listing Tracepoints
  • Starting and Stopping Trace Experiment

Create and Delete Tracepoints

trace
The trace command is very similar to the break command. Its argument can be a source line, a function name, or an address in the target program. See section Setting breakpoints. The trace command defines a tracepoint, which is a point in the target program where the debugger will briefly stop, collect some data, and then allow the program to continue. Setting a tracepoint or changing its commands doesn't take effect until the next tstart command; thus, you cannot change the tracepoint attributes once a trace experiment is running. Here are some examples of using the trace command:
(gdb) trace foo.c:121    // a source file and line number

(gdb) trace +2           // 2 lines forward

(gdb) trace my_function  // first source line of function

(gdb) trace *my_function // EXACT start address of function

(gdb) trace *0x2117c4    // an address
You can abbreviate trace as tr. The convenience variable $tpnum records the tracepoint number of the most recently set tracepoint.
delete tracepoint [num]
Permanently delete one or more tracepoints. With no argument, the default is to delete all tracepoints. Examples:
(gdb) delete trace 1 2 3 // remove three tracepoints

(gdb) delete trace       // remove all tracepoints
You can abbreviate this command as del tr.

Enable and Disable Tracepoints

disable tracepoint [num]
Disable tracepoint num, or all tracepoints if no argument num is given. A disabled tracepoint will have no effect during the next trace experiment, but it is not forgotten. You can re-enable a disabled tracepoint using the enable tracepoint command.
enable tracepoint [num]
Enable tracepoint num, or all tracepoints. The enabled tracepoints will become effective the next time a trace experiment is run.

Tracepoint Passcounts

passcount [n [num]]
Set the passcount of a tracepoint. The passcount is a way to automatically stop a trace experiment. If a tracepoint's passcount is n, then the trace experiment will be automatically stopped on the n'th time that tracepoint is hit. If the tracepoint number num is not specified, the passcount command sets the passcount of the most recently defined tracepoint. If no passcount is given, the trace experiment will run until stopped explicitly by the user. Examples:
(gdb) passcount 5 2 // Stop on the 5th execution of
                                   // tracepoint 2

(gdb) passcount 12  // Stop on the 12th execution of the
                                   // most recently defined tracepoint.
(gdb) trace foo
(gdb) pass 3
(gdb) trace bar
(gdb) pass 2
(gdb) trace baz
(gdb) pass 1        // Stop tracing when foo has been
                                    // executed 3 times OR when bar has
                                    // been executed 2 times
                                    // OR when baz has been executed 1 time.

Tracepoint Action Lists

actions [num]
This command will prompt for a list of actions to be taken when the tracepoint is hit. If the tracepoint number num is not specified, this command sets the actions for the one that was most recently defined (so that you can define a tracepoint and then say actions without bothering about its number). You specify the actions themselves on the following lines, one action at a time, and terminate the actions list with a line containing just end. So far, the only defined actions are collect and while-stepping. To remove all actions from a tracepoint, type `actions num' and follow it immediately with `end'.
(gdb) collect data // collect some data

(gdb) while-stepping 5 // single-step 5 times, collect data

(gdb) end              // signals the end of actions.
In the following example, the action list begins with collect commands indicating the things to be collected when the tracepoint is hit. Then, in order to single-step and collect additional data following the tracepoint, a while-stepping command is used, followed by the list of things to be collected while stepping. The while-stepping command is terminated by its own separate end command. Lastly, the action list is terminated by an end command.
(gdb) trace foo
(gdb) actions
Enter actions for tracepoint 1, one per line:
> collect bar,baz
> collect $regs
> while-stepping 12
  > collect $fp, $sp
  > end
end
collect expr1, expr2, ...
Collect values of the given expressions when the tracepoint is hit. This command accepts a comma-separated list of any valid expressions. In addition to global, static, or local variables, the following special arguments are supported:
$regs
collect all registers
$args
collect all function arguments
$locals
collect all local variables.
You can give several consecutive collect commands, each one with a single argument, or one collect command with several arguments separated by commas: the effect is the same. The command info scope (see section Examining the Symbol Table) is particularly useful for figuring out what data to collect.
while-stepping n
Perform n single-step traces after the tracepoint, collecting new data at each step. The while-stepping command is followed by the list of what to collect while stepping (followed by its own end command):
> while-stepping 12
  > collect $regs, myglobal
  > end
>
You may abbreviate while-stepping as ws or stepping.

Listing Tracepoints

info tracepoints [num]
Display information about the tracepoint num. If you don't specify a tracepoint number, displays information about all the tracepoints defined so far. For each tracepoint, the following information is shown:
  • its number
  • whether it is enabled or disabled
  • its address
  • its passcount as given by the passcount n command
  • its step count as given by the while-stepping n command
  • where in the source files is the tracepoint set
  • its action list as given by the actions command
(gdb) info trace
Num Enb Address    PassC StepC What
1   y   0x002117c4 0     0     <gdb_asm>
2   y   0x0020dc64 0     0     in g_test at g_test.c:1375
3   y   0x0020b1f4 0     0     in get_data at ../foo.c:41
(gdb)
This command can be abbreviated info tp.

Starting and Stopping Trace Experiment

tstart
This command takes no arguments. It starts the trace experiment, and begins collecting data. This has the side effect of discarding all the data collected in the trace buffer during the previous trace experiment.
tstop
This command takes no arguments. It ends the trace experiment, and stops collecting data. Note: a trace experiment and data collection may stop automatically if any tracepoint's passcount is reached (see section Tracepoint Passcounts), or if the trace buffer becomes full.
tstatus
This command displays the status of the current trace data collection.

Here is an example of the commands we described so far:

(gdb) trace gdb_c_test
(gdb) actions
Enter actions for tracepoint #1, one per line.
> collect $regs,$locals,$args
> while-stepping 11
  > collect $regs
  > end
> end
(gdb) tstart
    [time passes ...]
(gdb) tstop

Using the collected data

After the tracepoint experiment ends, you use GDB commands for examining the trace data. The basic idea is that each tracepoint collects a trace snapshot every time it is hit and another snapshot every time it single-steps. All these snapshots are consecutively numbered from zero and go into a buffer, and you can examine them later. The way you examine them is to focus on a specific trace snapshot. When the remote stub is focused on a trace snapshot, it will respond to all GDB requests for memory and registers by reading from the buffer which belongs to that snapshot, rather than from real memory or registers of the program being debugged. This means that all GDB commands (print, info registers, backtrace, etc.) will behave as if we were currently debugging the program state as it was when the tracepoint occurred. Any requests for data that are not in the buffer will fail.

  • tfind: How to select a trace snapshot
  • tdump: How to display all data for a snapshot
  • save-tracepoints: How to save tracepoints for a future run

tfind n

The basic command for selecting a trace snapshot from the buffer is tfind n, which finds trace snapshot number n, counting from zero. If no argument n is given, the next snapshot is selected.

Here are the various forms of using the tfind command.

tfind start
Find the first snapshot in the buffer. This is a synonym for tfind 0 (since 0 is the number of the first snapshot).
tfind none
Stop debugging trace snapshots, resume live debugging.
tfind end
Same as `tfind none'.
tfind
No argument means find the next trace snapshot.
tfind -
Find the previous trace snapshot before the current one. This permits retracing earlier steps.
tfind tracepoint num
Find the next snapshot associated with tracepoint num. Search proceeds forward from the last examined trace snapshot. If no argument num is given, it means find the next snapshot collected for the same tracepoint as the current snapshot.
tfind pc addr
Find the next snapshot associated with the value addr of the program counter. Search proceeds forward from the last examined trace snapshot. If no argument addr is given, it means find the next snapshot with the same value of PC as the current snapshot.
tfind outside addr1, addr2
Find the next snapshot whose PC is outside the given range of addresses.
tfind range addr1, addr2
Find the next snapshot whose PC is between addr1 and addr2.
tfind line [file:]n
Find the next snapshot associated with the source line n. If the optional argument file is given, refer to line n in that source file. Search proceeds forward from the last examined trace snapshot. If no argument n is given, it means find the next line other than the one currently being examined; thus saying tfind line repeatedly can appear to have the same effect as stepping from line to line in a live debugging session.

The default arguments for the tfind commands are specifically designed to make it easy to scan through the trace buffer. For instance, tfind with no argument selects the next trace snapshot, and tfind - with no argument selects the previous trace snapshot. So, by giving one tfind command, and then simply hitting RET repeatedly you can examine all the trace snapshots in order. Or, by saying tfind - and then hitting RET repeatedly you can examine the snapshots in reverse order. The tfind line command with no argument selects the snapshot for the next source line executed. The tfind pc command with no argument selects the next snapshot with the same program counter (PC) as the current frame. The tfind tracepoint command with no argument selects the next trace snapshot collected by the same tracepoint as the current one.

In addition to letting you scan through the trace buffer manually, these commands make it easy to construct GDB scripts that scan through the trace buffer and print out whatever collected data you are interested in. Thus, if we want to examine the PC, FP, and SP registers from each trace frame in the buffer, we can say this:

(gdb) tfind start
(gdb) while ($trace_frame != -1)
> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
          $trace_frame, $pc, $sp, $fp
> tfind
> end

Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14

Or, if we want to examine the variable X at each source line in the buffer:

(gdb) tfind start
(gdb) while ($trace_frame != -1)
> printf "Frame %d, X == %d\n", $trace_frame, X
> tfind line
> end

Frame 0, X = 1
Frame 7, X = 2
Frame 13, X = 255

tdump

This command takes no arguments. It prints all the data collected at the current trace snapshot.

(gdb) trace 444
(gdb) actions
Enter actions for tracepoint #2, one per line:
> collect $regs, $locals, $args, gdb_long_test
> end

(gdb) tstart

(gdb) tfind line 444
#0  gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
at gdb_test.c:444
444        printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )

(gdb) tdump
Data collected at tracepoint 2, trace frame 1:
d0             0xc4aa0085       -995491707
d1             0x18     24
d2             0x80     128
d3             0x33     51
d4             0x71aea3d        119204413
d5             0x22     34
d6             0xe0     224
d7             0x380035 3670069
a0             0x19e24a 1696330
a1             0x3000668        50333288
a2             0x100    256
a3             0x322000 3284992
a4             0x3000698        50333336
a5             0x1ad3cc 1758156
fp             0x30bf3c 0x30bf3c
sp             0x30bf34 0x30bf34
ps             0x0      0
pc             0x20b2c8 0x20b2c8
fpcontrol      0x0      0
fpstatus       0x0      0
fpiaddr        0x0      0
p = 0x20e5b4 "gdb-test"
p1 = (void *) 0x11
p2 = (void *) 0x22
p3 = (void *) 0x33
p4 = (void *) 0x44
p5 = (void *) 0x55
p6 = (void *) 0x66
gdb_long_test = 17 '\021'

(gdb)

save-tracepoints filename

This command saves all current tracepoint definitions together with their actions and passcounts, into a file `filename' suitable for use in a later debugging session. To read the saved tracepoint definitions, use the source command (see section Command files).

Convenience Variables for Tracepoints

(int) $trace_frame
The current trace snapshot (a.k.a. frame) number, or -1 if no snapshot is selected.
(int) $tracepoint
The tracepoint for the current trace snapshot.
(int) $trace_line
The line number for the current trace snapshot.
(char []) $trace_file
The source file for the current trace snapshot.
(char []) $trace_func
The name of the function containing $tracepoint.

Note: $trace_file is not suitable for use in printf, use output instead.

Here's a simple example of using these convenience variables for stepping through all the trace snapshots and printing some of their data.

(gdb) tfind start

(gdb) while $trace_frame != -1
> output $trace_file
> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
> tfind
> end

Using GDB with Different Languages

Although programming languages generally have common aspects, they are rarely expressed in the same manner. For instance, in ANSI C, dereferencing a pointer p is accomplished by *p, but in Modula-2, it is accomplished by p^. Values can also be represented (and displayed) differently. Hex numbers in C appear as `0x1ae', while in Modula-2 they appear as `1AEH'.

Language-specific information is built into GDB for some languages, allowing you to express operations like the above in your program's native language, and allowing GDB to output values in a manner consistent with the syntax of your program's native language. The language you use to build expressions is called the working language.

  • Setting: Switching between source languages
  • Show: Displaying the language
  • Checks: Type and range checks
  • Support: Supported languages

Switching between source languages

There are two ways to control the working language--either have GDB set it automatically, or select it manually yourself. You can use the set language command for either purpose. On startup, GDB defaults to setting the language automatically. The working language is used to determine how expressions you type are interpreted, how values are printed, etc.

In addition to the working language, every source file that GDB knows about has its own working language. For some object file formats, the compiler might indicate which language a particular source file is in. However, most of the time GDB infers the language from the name of the file. The language of a source file controls whether C++ names are demangled--this way backtrace can show each frame appropriately for its own language. There is no way to set the language of a source file from within GDB, but you can set the language associated with a filename extension. See section Displaying the language.

This is most commonly a problem when you use a program, such as cfront or f2c, that generates C but is written in another language. In that case, make the program use #line directives in its C output; that way GDB will know the correct language of the source code of the original program, and will display that source code, not the generated C code.

  • Filenames: Filename extensions and languages.
  • Manually: Setting the working language manually
  • Automatically: Having GDB infer the source language

List of filename extensions and languages

If a source file name ends in one of the following extensions, then GDB infers that its language is the one indicated.

`.c'
C source file
`.C'
`.cc'
`.cp'
`.cpp'
`.cxx'
`.c++'
C++ source file
`.f'
`.F'
Fortran source file
`.ch'
`.c186'
`.c286'
CHILL source file
`.mod'
Modula-2 source file
`.s'
`.S'
Assembler source file. This actually behaves almost like C, but GDB does not skip over function prologues when stepping.

In addition, you may set the language associated with a filename extension. See section Displaying the language.

Setting the working language

If you allow GDB to set the language automatically, expressions are interpreted the same way in your debugging session and your program.

If you wish, you may set the language manually. To do this, issue the command `set language lang', where lang is the name of a language, such as c or modula-2. For a list of the supported languages, type `set language'.

Setting the language manually prevents GDB from updating the working language automatically. This can lead to confusion if you try to debug a program when the working language is not the same as the source language, when an expression is acceptable to both languages--but means different things. For instance, if the current source file were written in C, and GDB was parsing Modula-2, a command such as:

print a = b + c

might not have the effect you intended. In C, this means to add b and c and place the result in a. The result printed would be the value of a. In Modula-2, this means to compare a to the result of b+c, yielding a BOOLEAN value.

Having GDB infer the source language

To have GDB set the working language automatically, use `set language local' or `set language auto'. GDB then infers the working language. That is, when your program stops in a frame (usually by encountering a breakpoint), GDB sets the working language to the language recorded for the function in that frame. If the language for a frame is unknown (that is, if the function or block corresponding to the frame was defined in a source file that does not have a recognized extension), the current working language is not changed, and GDB issues a warning.

This may not seem necessary for most programs, which are written entirely in one source language. However, program modules and libraries written in one source language can be used by a main program written in a different source language. Using `set language auto' in this case frees you from having to set the working language manually.

Displaying the language

The following commands help you find out which language is the working language, and also what language source files were written in.

show language
Display the current working language. This is the language you can use with commands such as print to build and compute expressions that may involve variables in your program.
info frame
Display the source language for this frame. This language becomes the working language if you use an identifier from this frame. See section Information about a frame, to identify the other information listed here.
info source
Display the source language of this source file. See section Examining the Symbol Table, to identify the other information listed here.

In unusual circumstances, you may have source files with extensions not in the standard list. You can then set the extension associated with a language explicitly:

set extension-language .ext language
Set source files with extension .ext to be assumed to be in the source language language.
info extensions
List all the filename extensions and the associated languages.

Type and range checking

Warning: In this release, the GDB commands for type and range checking are included, but they do not yet have any effect. This section documents the intended facilities.

Some languages are designed to guard you against making seemingly common errors through a series of compile- and run-time checks. These include checking the type of arguments to functions and operators, and making sure mathematical overflows are caught at run time. Checks such as these help to ensure a program's correctness once it has been compiled by eliminating type mismatches, and providing active checks for range errors when your program is running.

GDB can check for conditions like the above if you wish. Although GDB does not check the statements in your program, it can check expressions entered directly into GDB for evaluation via the print command, for example. As with the working language, GDB can also decide whether or not to check automatically based on your program's source language. See section Supported languages, for the default settings of supported languages.

  • Type Checking: An overview of type checking
  • Range Checking: An overview of range checking

An overview of type checking

Some languages, such as Modula-2, are strongly typed, meaning that the arguments to operators and functions have to be of the correct type, otherwise an error occurs. These checks prevent type mismatch errors from ever causing any run-time problems. For example,

1 + 2 => 3
but
error--> 1 + 2.3

The second example fails because the CARDINAL 1 is not type-compatible with the REAL 2.3.

For the expressions you use in GDB commands, you can tell the GDB type checker to skip checking; to treat any mismatches as errors and abandon the expression; or to only issue warnings when type mismatches occur, but evaluate the expression anyway. When you choose the last of these, GDB evaluates expressions like the second example above, but also issues a warning.

Even if you turn type checking off, there may be other reasons related to type that prevent GDB from evaluating an expression. For instance, GDB does not know how to add an int and a struct foo. These particular type errors have nothing to do with the language in use, and usually arise from expressions, such as the one described above, which make little sense to evaluate anyway.

Each language defines to what degree it is strict about type. For instance, both Modula-2 and C require the arguments to arithmetical operators to be numbers. In C, enumerated types and pointers can be represented as numbers, so that they are valid arguments to mathematical operators. See section Supported languages, for further details on specific languages.

GDB provides some additional commands for controlling the type checker:

set check type auto
Set type checking on or off based on the current working language. See section Supported languages, for the default settings for each language.
set check type on
set check type off
Set type checking on or off, overriding the default setting for the current working language. Issue a warning if the setting does not match the language default. If any type mismatches occur in evaluating an expression while type checking is on, GDB prints a message and aborts evaluation of the expression.
set check type warn
Cause the type checker to issue warnings, but to always attempt to evaluate the expression. Evaluating the expression may still be impossible for other reasons. For example, GDB cannot add numbers and structures.
show type
Show the current setting of the type checker, and whether or not GDB is setting it automatically.

An overview of range checking

In some languages (such as Modula-2), it is an error to exceed the bounds of a type; this is enforced with run-time checks. Such range checking is meant to ensure program correctness by making sure computations do not overflow, or indices on an array element access do not exceed the bounds of the array.

For expressions you use in GDB commands, you can tell GDB to treat range errors in one of three ways: ignore them, always treat them as errors and abandon the expression, or issue warnings but evaluate the expression anyway.

A range error can result from numerical overflow, from exceeding an array index bound, or when you type a constant that is not a member of any type. Some languages, however, do not treat overflows as an error. In many implementations of C, mathematical overflow causes the result to "wrap around" to lower values--for example, if m is the largest integer value, and s is the smallest, then

m + 1 => s

This, too, is specific to individual languages, and in some cases specific to individual compilers or machines. See section Supported languages, for further details on specific languages.

GDB provides some additional commands for controlling the range checker:

set check range auto
Set range checking on or off based on the current working language. See section Supported languages, for the default settings for each language.
set check range on
set check range off
Set range checking on or off, overriding the default setting for the current working language. A warning is issued if the setting does not match the language default. If a range error occurs and range checking is on, then a message is printed and evaluation of the expression is aborted.
set check range warn
Output messages when the GDB range checker detects a range error, but attempt to evaluate the expression anyway. Evaluating the expression may still be impossible for other reasons, such as accessing memory that the process does not own (a typical example from many Unix systems).
show range
Show the current setting of the range checker, and whether or not it is being set automatically by GDB.

Supported languages

GDB supports C, C++, Fortran, Java, Chill, assembly, and Modula-2. Some GDB features may be used in expressions regardless of the language you use: the GDB @ and :: operators, and the `{type}addr' construct (see section Expressions) can be used with the constructs of any supported language.

The following sections detail to what degree each source language is supported by GDB. These sections are not meant to be language tutorials or references, but serve only as a reference guide to what the GDB expression parser accepts, and what input and output formats should look like for different languages. There are many good books written on each of these languages; please look to these for a language reference or tutorial.

  • C: C and C++
  • Modula-2: Modula-2
  • Chill: Chill

C and C++

Since C and C++ are so closely related, many features of GDB apply to both languages. Whenever this is the case, we discuss those languages together.

The C++ debugging facilities are jointly implemented by the C++ compiler and GDB. Therefore, to debug your C++ code effectively, you must compile your C++ programs with a supported C++ compiler, such as GNU g++, or the HP ANSI C++ compiler (aCC).

For best results when using GNU C++, use the stabs debugging format. You can select that format explicitly with the g++ command-line options `-gstabs' or `-gstabs+'. See section `Options for Debugging Your Program or GNU CC' in Using GNU CC, for more information.

  • C Operators: C and C++ operators
  • C Constants: C and C++ constants
  • C plus plus expressions: C++ expressions
  • C Defaults: Default settings for C and C++
  • C Checks: C and C++ type and range checks
  • Debugging C: GDB and C
  • Debugging C plus plus: GDB features for C++

C and C++ operators

Operators must be defined on values of specific types. For instance, + is defined on numbers, but not on structures. Operators are often defined on groups of types.

For the purposes of C and C++, the following definitions hold:

  • Integral types include int with any of its storage-class specifiers; char; enum; and, for C++, bool.
  • Floating-point types include float, double, and long double (if supported by the target platform).
  • Pointer types include all types defined as (type *).
  • Scalar types include all of the above.

The following operators are supported. They are listed here in order of increasing precedence:

,
The comma or sequencing operator. Expressions in a comma-separated list are evaluated from left to right, with the result of the entire expression being the last expression evaluated.
=
Assignment. The value of an assignment expression is the value assigned. Defined on scalar types.
op=
Used in an expression of the form a op= b, and translated to a = a op b. op= and = have the same precedence. op is any one of the operators |, ^, &, <<, >>, +, -, *, /, %.
?:
The ternary operator. a ? b : c can be thought of as: if a then b else c. a should be of an integral type.
||
Logical OR. Defined on integral types.
&&
Logical AND. Defined on integral types.
|
Bitwise OR. Defined on integral types.
^
Bitwise exclusive-OR. Defined on integral types.
&
Bitwise AND. Defined on integral types.
==, !=
Equality and inequality. Defined on scalar types. The value of these expressions is 0 for false and non-zero for true.
<, >, <=, >=
Less than, greater than, less than or equal, greater than or equal. Defined on scalar types. The value of these expressions is 0 for false and non-zero for true.
<<, >>
left shift, and right shift. Defined on integral types.
@
The GDB "artificial array" operator (see section Expressions).
+, -
Addition and subtraction. Defined on integral types, floating-point types and pointer types.
*, /, %
Multiplication, division, and modulus. Multiplication and division are defined on integral and floating-point types. Modulus is defined on integral types.
++, --
Increment and decrement. When appearing before a variable, the operation is performed before the variable is used in an expression; when appearing after it, the variable's value is used before the operation takes place.
*
Pointer dereferencing. Defined on pointer types. Same precedence as ++.
&
Address operator. Defined on variables. Same precedence as ++. For debugging C++, GDB implements a use of `&' beyond what is allowed in the C++ language itself: you can use `&(&ref)' (or, if you prefer, simply `&&ref') to examine the address where a C++ reference variable (declared with `&ref') is stored.
-
Negative. Defined on integral and floating-point types. Same precedence as ++.
!
Logical negation. Defined on integral types. Same precedence as ++.
~
Bitwise complement operator. Defined on integral types. Same precedence as ++.
., ->
Structure member, and pointer-to-structure member. For convenience, GDB regards the two as equivalent, choosing whether to dereference a pointer based on the stored type information. Defined on struct and union data.
.*, ->*
Dereferences of pointers to members.
[]
Array indexing. a[i] is defined as *(a+i). Same precedence as ->.
()
Function parameter list. Same precedence as ->.
::
C++ scope resolution operator. Defined on struct, union, and class types.
::
Doubled colons also represent the GDB scope operator (see section Expressions). Same precedence as ::, above.

If an operator is redefined in the user code, GDB usually attempts to invoke the redefined version instead of using the operator's predefined meaning.

  • C Constants

C and C++ constants

GDB allows you to express the constants of C and C++ in the following ways:

  • Integer constants are a sequence of digits. Octal constants are specified by a leading `0' (i.e. zero), and hexadecimal constants by a leading `0x' or `0X'. Constants may also end with a letter `l', specifying that the constant should be treated as a long value.
  • Floating point constants are a sequence of digits, followed by a decimal point, followed by a sequence of digits, and optionally followed by an exponent. An exponent is of the form: `e[[+]|-]nnn', where nnn is another sequence of digits. The `+' is optional for positive exponents. A floating-point constant may also end with a letter `f' or `F', specifying that the constant should be treated as being of the float (as opposed to the default double) type; or with a letter `l' or `L', which specifies a long double constant.
  • Enumerated constants consist of enumerated identifiers, or their integral equivalents.
  • Character constants are a single character surrounded by single quotes ('), or a number--the ordinal value of the corresponding character (usually its ASCII value). Within quotes, the single character may be represented by a letter or by escape sequences, which are of the form `\nnn', where nnn is the octal representation of the character's ordinal value; or of the form `\x', where `x' is a predefined special character--for example, `\n' for newline.
  • String constants are a sequence of character constants surrounded by double quotes ("). Any valid character constant (as described above) may appear. Double quotes within the string must be preceded by a backslash, so for instance `"a\"b'c"' is a string of five characters.
  • Pointer constants are an integral value. You can also write pointers to constants using the C operator `&'.
  • Array constants are comma-separated lists surrounded by braces `{' and `}'; for example, `{1,2,3}' is a three-element array of integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and `{&"hi", &"there", &"fred"}' is a three-element array of pointers.
  • C plus plus expressions
  • C Defaults
  • C Checks
  • Debugging C

C++ expressions

GDB expression handling can interpret most C++ expressions.

Warning: GDB can only debug C++ code if you use the proper compiler. Typically, C++ debugging depends on the use of additional debugging information in the symbol table, and thus requires special support. In particular, if your compiler generates a.out, MIPS ECOFF, RS/6000 XCOFF, or ELF with stabs extensions to the symbol table, these facilities are all available. (With GNU CC, you can use the `-gstabs' option to request stabs debugging extensions explicitly.) Where the object code format is standard COFF or DWARF in ELF, on the other hand, most of the C++ support in GDB does not work.

  1. Member function calls are allowed; you can use expressions like
    count = aml->GetOriginal(x, y)
  2. While a member function is active (in the selected stack frame), your expressions have the same namespace available as the member function; that is, GDB allows implicit references to the class instance pointer this following the same rules as C++.
  3. You can call overloaded functions; GDB resolves the function call to the right definition, with some restrictions. GDB does not perform overload resolution involving user-defined type conversions, calls to constructors, or instantiations of templates that do not exist in the program. It also cannot handle ellipsis argument lists or default arguments. It does perform integral conversions and promotions, floating-point promotions, arithmetic conversions, pointer conversions, conversions of class objects to base classes, and standard conversions such as those of functions or arrays to pointers; it requires an exact match on the number of function arguments. Overload resolution is always performed, unless you have specified set overload-resolution off. See section GDB features for C++. You must specify set overload-resolution off in order to use an explicit function signature to call an overloaded function, as in
    p 'foo(char,int)'('x', 13)
    The GDB command-completion facility can simplify this; see section Command completion.
  4. GDB understands variables declared as C++ references; you can use them in expressions just as you do in C++ source--they are automatically dereferenced. In the parameter list shown when GDB displays a frame, the values of reference variables are not displayed (unlike other variables); this avoids clutter, since references are often used for large structures. The address of a reference variable is always shown, unless you have specified `set print address off'.
  5. GDB supports the C++ name resolution operator ::---your expressions can use it just as expressions in your program do. Since one scope may be defined in another, you can use :: repeatedly if necessary, for example in an expression like `scope1::scope2::name'. GDB also allows resolving name scope by reference to source files, in both C and C++ debugging (see section Program variables).

In addition, when used with HP's C++ compiler, GDB supports calling virtual functions correctly, printing out virtual bases of objects, calling functions in a base subobject, casting objects, and invoking user-defined operators.

C and C++ defaults

If you allow GDB to set type and range checking automatically, they both default to off whenever the working language changes to C or C++. This happens regardless of whether you or GDB selects the working language.

If you allow GDB to set the language automatically, it recognizes source files whose names end with `.c', `.C', or `.cc', etc, and when GDB enters code compiled from one of these files, it sets the working language to C or C++. See section Having GDB infer the source language, for further details.

C and C++ type and range checks

By default, when GDB parses C or C++ expressions, type checking is not used. However, if you turn type checking on, GDB considers two variables type equivalent if:

  • The two variables are structured and have the same structure, union, or enumerated tag.
  • The two variables have the same type name, or types that have been declared equivalent through typedef.

Range checking, if turned on, is done on mathematical operations. Array indices are not checked, since they are often used to index a pointer that is not itself an array.

GDB and C

The set print union and show print union commands apply to the union type. When set to `on', any union that is inside a struct or class is also printed. Otherwise, it appears as `{...}'.

The @ operator aids in the debugging of dynamic arrays, formed with pointers and a memory allocation function. See section Expressions.

  • Debugging C plus plus

GDB features for C++

Some GDB commands are particularly useful with C++, and some are designed specifically for use with C++. Here is a summary:

breakpoint menus
When you want a breakpoint in a function whose name is overloaded, GDB breakpoint menus help you specify which function definition you want. See section Breakpoint menus.
rbreak regex
Setting breakpoints using regular expressions is helpful for setting breakpoints on overloaded functions that are not members of any special classes. See section Setting breakpoints.
catch throw
catch catch
Debug C++ exception handling using these commands. See section Setting catchpoints.
ptype typename
Print inheritance relationships as well as other information for type typename. See section Examining the Symbol Table.
set print demangle
show print demangle
set print asm-demangle
show print asm-demangle
Control whether C++ symbols display in their source form, both when displaying code as C++ source and when displaying disassemblies. See section Print settings.
set print object
show print object
Choose whether to print derived (actual) or declared types of objects. See section Print settings.
set print vtbl
show print vtbl
Control the format for printing virtual function tables. See section Print settings. (The vtbl commands do not work on programs compiled with the HP ANSI C++ compiler (aCC).)
set overload-resolution on
Enable overload resolution for C++ expression evaluation. The default is on. For overloaded functions, GDB evaluates the arguments and searches for a function whose signature matches the argument types, using the standard C++ conversion rules (see section C++ expressions, for details). If it cannot find a match, it emits a message.
set overload-resolution off
Disable overload resolution for C++ expression evaluation. For overloaded functions that are not class member functions, GDB chooses the first function of the specified name that it finds in the symbol table, whether or not its arguments are of the correct type. For overloaded functions that are class member functions, GDB searches for a function whose signature exactly matches the argument types.
Overloaded symbol names
You can specify a particular definition of an overloaded symbol, using the same notation that is used to declare such symbols in C++: type symbol(types) rather than just symbol. You can also use the GDB command-line word completion facilities to list the available choices, or to finish the type list for you. See section Command completion, for details on how to do this.

Modula-2

The extensions made to GDB to support Modula-2 only support output from the GNU Modula-2 compiler (which is currently being developed). Other Modula-2 compilers are not currently supported, and attempting to debug executables produced by them is most likely to give an error as GDB reads in the executable's symbol table.

  • M2 Operators: Built-in operators
  • Built-In Func/Proc: Built-in functions and procedures
  • M2 Constants: Modula-2 constants
  • M2 Defaults: Default settings for Modula-2
  • Deviations: Deviations from standard Modula-2
  • M2 Checks: Modula-2 type and range checks
  • M2 Scope: The scope operators :: and .
  • GDB/M2: GDB and Modula-2

Operators

Operators must be defined on values of specific types. For instance, + is defined on numbers, but not on structures. Operators are often defined on groups of types. For the purposes of Modula-2, the following definitions hold:

  • Integral types consist of INTEGER, CARDINAL, and their subranges.
  • Character types consist of CHAR and its subranges.
  • Floating-point types consist of REAL.
  • Pointer types consist of anything declared as POINTER TO type.
  • Scalar types consist of all of the above.
  • Set types consist of SET and BITSET types.
  • Boolean types consist of BOOLEAN.

The following operators are supported, and appear in order of increasing precedence:

,
Function argument or array index separator.
:=
Assignment. The value of var := value is value.
<, >
Less than, greater than on integral, floating-point, or enumerated types.
<=, >=
Less than or equal to, greater than or equal to on integral, floating-point and enumerated types, or set inclusion on set types. Same precedence as <.
=, <>, #
Equality and two ways of expressing inequality, valid on scalar types. Same precedence as <. In GDB scripts, only <> is available for inequality, since # conflicts with the script comment character.
IN
Set membership. Defined on set types and the types of their members. Same precedence as <.
OR
Boolean disjunction. Defined on boolean types.
AND, &
Boolean conjunction. Defined on boolean types.
@
The GDB "artificial array" operator (see section Expressions).
+, -
Addition and subtraction on integral and floating-point types, or union and difference on set types.
*
Multiplication on integral and floating-point types, or set intersection on set types.
/
Division on floating-point types, or symmetric set difference on set types. Same precedence as *.
DIV, MOD
Integer division and remainder. Defined on integral types. Same precedence as *.
-
Negative. Defined on INTEGER and REAL data.
^
Pointer dereferencing. Defined on pointer types.
NOT
Boolean negation. Defined on boolean types. Same precedence as ^.
.
RECORD field selector. Defined on RECORD data. Same precedence as ^.
[]
Array indexing. Defined on ARRAY data. Same precedence as ^.
()
Procedure argument list. Defined on PROCEDURE objects. Same precedence as ^.
::, .
GDB and Modula-2 scope operators.

Warning: Sets and their operations are not yet supported, so GDB treats the use of the operator IN, or the use of operators +, -, *, /, =, , <>, #, <=, and >= on sets as an error.

Built-in functions and procedures

Modula-2 also makes available several built-in procedures and functions. In describing these, the following metavariables are used:

a
represents an ARRAY variable.
c
represents a CHAR constant or variable.
i
represents a variable or constant of integral type.
m
represents an identifier that belongs to a set. Generally used in the same function with the metavariable s. The type of s should be SET OF mtype (where mtype is the type of m).
n
represents a variable or constant of integral or floating-point type.
r
represents a variable or constant of floating-point type.
t
represents a type.
v
represents a variable.
x
represents a variable or constant of one of many types. See the explanation of the function for details.

All Modula-2 built-in procedures also return a result, described below.

ABS(n)
Returns the absolute value of n.
CAP(c)
If c is a lower case letter, it returns its upper case equivalent, otherwise it returns its argument.
CHR(i)
Returns the character whose ordinal value is i.
DEC(v)
Decrements the value in the variable v by one. Returns the new value.
DEC(v,i)
Decrements the value in the variable v by i. Returns the new value.
EXCL(m,s)
Removes the element m from the set s. Returns the new set.
FLOAT(i)
Returns the floating point equivalent of the integer i.
HIGH(a)
Returns the index of the last member of a.
INC(v)
Increments the value in the variable v by one. Returns the new value.
INC(v,i)
Increments the value in the variable v by i. Returns the new value.
INCL(m,s)
Adds the element m to the set s if it is not already there. Returns the new set.
MAX(t)
Returns the maximum value of the type t.
MIN(t)
Returns the minimum value of the type t.
ODD(i)
Returns boolean TRUE if i is an odd number.
ORD(x)
Returns the ordinal value of its argument. For example, the ordinal value of a character is its ASCII value (on machines supporting the ASCII character set). x must be of an ordered type, which include integral, character and enumerated types.
SIZE(x)
Returns the size of its argument. x can be a variable or a type.
TRUNC(r)
Returns the integral part of r.
VAL(t,i)
Returns the member of the type t whose ordinal value is i.

Warning: Sets and their operations are not yet supported, so GDB treats the use of procedures INCL and EXCL as an error.

Constants

GDB allows you to express the constants of Modula-2 in the following ways:

  • Integer constants are simply a sequence of digits. When used in an expression, a constant is interpreted to be type-compatible with the rest of the expression. Hexadecimal integers are specified by a trailing `H', and octal integers by a trailing `B'.
  • Floating point constants appear as a sequence of digits, followed by a decimal point and another sequence of digits. An optional exponent can then be specified, in the form `E[+|-]nnn', where `[+|-]nnn' is the desired exponent. All of the digits of the floating point constant must be valid decimal (base 10) digits.
  • Character constants consist of a single character enclosed by a pair of like quotes, either single (') or double ("). They may also be expressed by their ordinal value (their ASCII value, usually) followed by a `C'.
  • String constants consist of a sequence of characters enclosed by a pair of like quotes, either single (') or double ("). Escape sequences in the style of C are also allowed. See section C and C++ constants, for a brief explanation of escape sequences.
  • Enumerated constants consist of an enumerated identifier.
  • Boolean constants consist of the identifiers TRUE and FALSE.
  • Pointer constants consist of integral values only.
  • Set constants are not yet supported.

Modula-2 defaults

If type and range checking are set automatically by GDB, they both default to on whenever the working language changes to Modula-2. This happens regardless of whether you or GDB selected the working language.

If you allow GDB to set the language automatically, then entering code compiled from a file whose name ends with `.mod' sets the working language to Modula-2. See section Having GDB infer the source language, for further details.

Deviations from standard Modula-2

A few changes have been made to make Modula-2 programs easier to debug. This is done primarily via loosening its type strictness:

  • Unlike in standard Modula-2, pointer constants can be formed by integers. This allows you to modify pointer variables during debugging. (In standard Modula-2, the actual address contained in a pointer variable is hidden from you; it can only be modified through direct assignment to another pointer variable or expression that returned a pointer.)
  • C escape sequences can be used in strings and characters to represent non-printable characters. GDB prints out strings with these escape sequences embedded. Single non-printable characters are printed using the `CHR(nnn)' format.
  • The assignment operator (:=) returns the value of its right-hand argument.
  • All built-in procedures both modify and return their argument.

Modula-2 type and range checks

Warning: in this release, GDB does not yet perform type or range checking.

GDB considers two Modula-2 variables type equivalent if:

  • They are of types that have been declared equivalent via a TYPE t1 = t2 statement
  • They have been declared on the same line. (Note: This is true of the GNU Modula-2 compiler, but it may not be true of other compilers.)

As long as type checking is enabled, any attempt to combine variables whose types are not equivalent is an error.

Range checking is done on all mathematical operations, assignment, array index bounds, and all built-in functions and procedures.

The scope operators :: and .

There are a few subtle differences between the Modula-2 scope operator (.) and the GDB scope operator (::). The two have similar syntax:

module . id
scope :: id

where scope is the name of a module or a procedure, module the name of a module, and id is any declared identifier within your program, except another module.

Using the :: operator makes GDB search the scope specified by scope for the identifier id. If it is not found in the specified scope, then GDB searches all scopes enclosing the one specified by scope.

Using the . operator makes GDB search the current scope for the identifier specified by id that was imported from the definition module specified by module. With this operator, it is an error if the identifier id was not imported from definition module module, or if id is not an identifier in module.

GDB and Modula-2

Some GDB commands have little use when debugging Modula-2 programs. Five subcommands of set print and show print apply specifically to C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'. The first four apply to C++, and the last to the C union type, which has no direct analogue in Modula-2.

The @ operator (see section Expressions), while available with any language, is not useful with Modula-2. Its intent is to aid the debugging of dynamic arrays, which cannot be created in Modula-2 as they can in C or C++. However, because an address can be specified by an integral constant, the construct `{type}adrexp' is still useful.

In GDB scripts, the Modula-2 inequality operator # is interpreted as the beginning of a comment. Use <> instead.

Chill

The extensions made to GDB to support Chill only support output from the GNU Chill compiler. Other Chill compilers are not currently supported, and attempting to debug executables produced by them is most likely to give an error as GDB reads in the executable's symbol table.

This section covers the Chill related topics and the features of GDB which support these topics.

  • How modes are displayed: How modes are displayed
  • Locations: Locations and their accesses
  • Values and their Operations: Values and their Operations
  • Chill type and range checks
  • Chill defaults

How modes are displayed

The Chill Datatype- (Mode) support of GDB is directly related with the functionality of the GNU Chill compiler, and therefore deviates slightly from the standard specification of the Chill language. The provided modes are:

Discrete modes:
  • Integer Modes which are predefined by BYTE, UBYTE, INT, UINT, LONG, ULONG,
  • Boolean Mode which is predefined by BOOL,
  • Character Mode which is predefined by CHAR,
  • Set Mode which is displayed by the keyword SET.
    (gdb) ptype x
type = SET (karli = 10, susi = 20, fritzi = 100)
    If the type is an unnumbered set the set element values are omitted.
  • Range Mode which is displayed by
    type = <basemode>(<lower bound> : <upper bound>)
    where <lower bound>, <upper bound> can be of any discrete literal expression (e.g. set element names).
Powerset Mode:
A Powerset Mode is displayed by the keyword POWERSET followed by the member mode of the powerset. The member mode can be any discrete mode.
(gdb) ptype x
type = POWERSET SET (egon, hugo, otto)
Reference Modes:
  • Bound Reference Mode which is displayed by the keyword REF followed by the mode name to which the reference is bound.
  • Free Reference Mode which is displayed by the keyword PTR.
Procedure mode
The procedure mode is displayed by type = PROC(<parameter list>) <return mode> EXCEPTIONS (<exception list>). The <parameter list> is a list of the parameter modes. <return mode> indicates the mode of the result of the procedure if any. The exceptionlist lists all possible exceptions which can be raised by the procedure.
Synchronization Modes:
  • Event Mode which is displayed by
    EVENT (<event length>)
    where (<event length>) is optional.
  • Buffer Mode which is displayed by
    BUFFER (<buffer length>)<buffer element mode>
    where (<buffer length>) is optional.
Timing Modes:
  • Duration Mode which is predefined by DURATION
  • Absolute Time Mode which is predefined by TIME
Real Modes:
Real Modes are predefined with REAL and LONG_REAL.
String Modes:
  • Character String Mode which is displayed by
    CHARS(<string length>)
    followed by the keyword VARYING if the String Mode is a varying mode
  • Bit String Mode which is displayed by
    BOOLS(<string
length>)
Array Mode:
The Array Mode is displayed by the keyword ARRAY(<range>) followed by the element mode (which may in turn be an array mode).
(gdb) ptype x
type = ARRAY (1:42)
          ARRAY (1:20)
             SET (karli = 10, susi = 20, fritzi = 100)
Structure Mode
The Structure mode is displayed by the keyword STRUCT(<field list>). The <field list> consists of names and modes of fields of the structure. Variant structures have the keyword CASE <field> OF <variant fields> ESAC in their field list. Since the current version of the GNU Chill compiler doesn't implement tag processing (no runtime checks of variant fields, and therefore no debugging info), the output always displays all variant fields.
(gdb) ptype str
type = STRUCT (
    as x,
    bs x,
    CASE bs OF
    (karli):
        cs a
    (ott):
        ds x
    ESAC
)

Locations and their accesses

A location in Chill is an object which can contain values.

A value of a location is generally accessed by the (declared) name of the location. The output conforms to the specification of values in Chill programs. How values are specified is the topic of the next section, section Values and their Operations.

The pseudo-location RESULT (or result) can be used to display or change the result of a currently-active procedure:

set result := EXPR

This does the same as the Chill action RESULT EXPR (which is not available in GDB).

Values of reference mode locations are printed by PTR(<hex value>) in case of a free reference mode, and by (REF <reference mode>) (<hex-value>) in case of a bound reference. <hex value> represents the address where the reference points to. To access the value of the location referenced by the pointer, use the dereference operator `->'.

Values of procedure mode locations are displayed by

{ PROC
(<argument modes> ) <return mode> } <address> <name of procedure
location>

<argument modes> is a list of modes according to the parameter specification of the procedure and <address> shows the address of the entry point.

Substructures of string mode-, array mode- or structure mode-values (e.g. array slices, fields of structure locations) are accessed using certain operations which are described in the next section, section Values and their Operations.

A location value may be interpreted as having a different mode using the location conversion. This mode conversion is written as <mode name>(<location>). The user has to consider that the sizes of the modes have to be equal otherwise an error occurs. Furthermore, no range checking of the location against the destination mode is performed, and therefore the result can be quite confusing.

(gdb) print int (s(3 up 4)) XXX TO be filled in !! XXX

Values and their Operations

Values are used to alter locations, to investigate complex structures in more detail or to filter relevant information out of a large amount of data. There are several (mode dependent) operations defined which enable such investigations. These operations are not only applicable to constant values but also to locations, which can become quite useful when debugging complex structures. During parsing the command line (e.g. evaluating an expression) GDB treats location names as the values behind these locations.

This section describes how values have to be specified and which operations are legal to be used with such values.

Literal Values
Literal values are specified in the same manner as in GNU Chill programs. For detailed specification refer to the GNU Chill implementation Manual chapter 1.5.
Tuple Values
A tuple is specified by <mode name>[<tuple>], where <mode name> can be omitted if the mode of the tuple is unambiguous. This unambiguity is derived from the context of a evaluated expression. <tuple> can be one of the following:
  • Powerset Tuple
  • Array Tuple
  • Structure Tuple Powerset tuples, array tuples and structure tuples are specified in the same manner as in Chill programs refer to z200/88 chpt 5.2.5.
String Element Value
A string element value is specified by
<string value>(<index>)
where <index> is a integer expression. It delivers a character value which is equivalent to the character indexed by <index> in the string.
String Slice Value
A string slice value is specified by <string value>(<slice spec>), where <slice spec> can be either a range of integer expressions or specified by <start expr> up <size>. <size> denotes the number of elements which the slice contains. The delivered value is a string value, which is part of the specified string.
Array Element Values
An array element value is specified by <array value>(<expr>) and delivers a array element value of the mode of the specified array.
Array Slice Values
An array slice is specified by <array value>(<slice spec>), where <slice spec> can be either a range specified by expressions or by <start expr> up <size>. <size> denotes the number of arrayelements the slice contains. The delivered value is an array value which is part of the specified array.
Structure Field Values
A structure field value is derived by <structure value>.<field name>, where <field name> indicates the name of a field specified in the mode definition of the structure. The mode of the delivered value corresponds to this mode definition in the structure definition.
Procedure Call Value
The procedure call value is derived from the return value of the procedure(4). Values of duration mode locations are represented by ULONG literals. Values of time mode locations appear as
TIME(<secs>:<nsecs>)
Zero-adic Operator Value
The zero-adic operator value is derived from the instance value for the current active process.
Expression Values
The value delivered by an expression is the result of the evaluation of the specified expression. If there are error conditions (mode incompatibility, etc.) the evaluation of expressions is aborted with a corresponding error message. Expressions may be parenthesised which causes the evaluation of this expression before any other expression which uses the result of the parenthesised expression. The following operators are supported by GDB:
OR, ORIF, XOR
AND, ANDIF
NOT
Logical operators defined over operands of boolean mode.
=, /=
Equality and inequality operators defined over all modes.
>, >=
<, <=
Relational operators defined over predefined modes.
+, -
*, /, MOD, REM
Arithmetic operators defined over predefined modes.
-
Change sign operator.
//
String concatenation operator.
()
String repetition operator.
->
Referenced location operator which can be used either to take the address of a location (->loc), or to dereference a reference location (loc->).
OR, XOR
AND
NOT
Powerset and bitstring operators.
>, >=
<, <=
Powerset inclusion operators.
IN
Membership operator.

Chill type and range checks

GDB considers two Chill variables mode equivalent if the sizes of the two modes are equal. This rule applies recursively to more complex datatypes which means that complex modes are treated equivalent if all element modes (which also can be complex modes like structures, arrays, etc.) have the same size.

Range checking is done on all mathematical operations, assignment, array index bounds and all built in procedures.

Strong type checks are forced using the GDB command set check strong. This enforces strong type and range checks on all operations where Chill constructs are used (expressions, built in functions, etc.) in respect to the semantics as defined in the z.200 language specification.

All checks can be disabled by the GDB command set check off.

Chill defaults

If type and range checking are set automatically by GDB, they both default to on whenever the working language changes to Chill. This happens regardless of whether you or GDB selected the working language.

If you allow GDB to set the language automatically, then entering code compiled from a file whose name ends with `.ch' sets the working language to Chill. See section Having GDB infer the source language, for further details.

Examining the Symbol Table

The commands described in this chapter allow you to inquire about the symbols (names of variables, functions and types) defined in your program. This information is inherent in the text of your program and does not change as your program executes. GDB finds it in your program's symbol table, in the file indicated when you started GDB (see section Choosing files), or by one of the file-management commands (see section Commands to specify files).

Occasionally, you may need to refer to symbols that contain unusual characters, which GDB ordinarily treats as word delimiters. The most frequent case is in referring to static variables in other source files (see section Program variables). File names are recorded in object files as debugging symbols, but GDB would ordinarily parse a typical file name, like `foo.c', as the three words `foo' `.' `c'. To allow GDB to recognize `foo.c' as a single symbol, enclose it in single quotes; for example,

p 'foo.c'::x

looks up the value of x in the scope of the file `foo.c'.

info address symbol
Describe where the data for symbol is stored. For a register variable, this says which register it is kept in. For a non-register local variable, this prints the stack-frame offset at which the variable is always stored. Note the contrast with `print &symbol', which does not work at all for a register variable, and for a stack local variable prints the exact address of the current instantiation of the variable.
info symbol addr
Print the name of a symbol which is stored at the address addr. If no symbol is stored exactly at addr, GDB prints the nearest symbol and an offset from it:
(gdb) info symbol 0x54320
_initialize_vx + 396 in section .text
This is the opposite of the info address command. You can use it to find out the name of a variable or a function given its address.
whatis expr
Print the data type of expression expr. expr is not actually evaluated, and any side-effecting operations (such as assignments or function calls) inside it do not take place. See section Expressions.
whatis
Print the data type of $, the last value in the value history.
ptype typename
Print a description of data type typename. typename may be the name of a type, or for C code it may have the form `class class-name', `struct struct-tag', `union union-tag' or `enum enum-tag'.
ptype expr
ptype
Print a description of the type of expression expr. ptype differs from whatis by printing a detailed description, instead of just the name of the type. For example, for this variable declaration:
struct complex {double real; double imag;} v;
the two commands give this output:
(gdb) whatis v
type = struct complex
(gdb) ptype v
type = struct complex {
    double real;
    double imag;
}
As with whatis, using ptype without an argument refers to the type of $, the last value in the value history.
info types regexp
info types
Print a brief description of all types whose names match regexp (or all types in your program, if you supply no argument). Each complete typename is matched as though it were a complete line; thus, `i type value' gives information on all types in your program whose names include the string value, but `i type ^value$' gives information only on types whose complete name is value. This command differs from ptype in two ways: first, like whatis, it does not print a detailed description; second, it lists all source files where a type is defined.
info scope addr
List all the variables local to a particular scope. This command accepts a location--a function name, a source line, or an address preceded by a `*', and prints all the variables local to the scope defined by that location. For example:
(gdb) info scope command_line_handler
Scope for command_line_handler:
Symbol rl is an argument at stack/frame offset 8, length 4.
Symbol linebuffer is in static storage at address 0x150a18, length 4.
Symbol linelength is in static storage at address 0x150a1c, length 4.
Symbol p is a local variable in register $esi, length 4.
Symbol p1 is a local variable in register $ebx, length 4.
Symbol nline is a local variable in register $edx, length 4.
Symbol repeat is a local variable at frame offset -8, length 4.
This command is especially useful for determining what data to collect during a trace experiment, see section Tracepoint Action Lists.
info source
Show the name of the current source file--that is, the source file for the function containing the current point of execution--and the language it was written in.
info sources
Print the names of all source files in your program for which there is debugging information, organized into two lists: files whose symbols have already been read, and files whose symbols will be read when needed.
info functions
Print the names and data types of all defined functions.
info functions regexp
Print the names and data types of all defined functions whose names contain a match for regular expression regexp. Thus, `info fun step' finds all functions whose names include step; `info fun ^step' finds those whose names start with step.
info variables
Print the names and data types of all variables that are declared outside of functions (i.e., excluding local variables).
info variables regexp
Print the names and data types of all variables (except for local variables) whose names contain a match for regular expression regexp. Some systems allow individual object files that make up your program to be replaced without stopping and restarting your program. For example, in VxWorks you can simply recompile a defective object file and keep on running. If you are running on one of these systems, you can allow GDB to reload the symbols for automatically relinked modules:
set symbol-reloading on
Replace symbol definitions for the corresponding source file when an object file with a particular name is seen again.
set symbol-reloading off
Do not replace symbol definitions when encountering object files of the same name more than once. This is the default state; if you are not running on a system that permits automatic relinking of modules, you should leave symbol-reloading off, since otherwise GDB may discard symbols when linking large programs, that may contain several modules (from different directories or libraries) with the same name.
show symbol-reloading
Show the current on or off setting.
set opaque-type-resolution on
Tell GDB to resolve opaque types. An opaque type is a type declared as a pointer to a struct, class, or union---for example, struct MyType *---that is used in one source file although the full declaration of struct MyType is in another source file. The default is on. A change in the setting of this subcommand will not take effect until the next time symbols for a file are loaded.
set opaque-type-resolution off
Tell GDB not to resolve opaque types. In this case, the type is printed as follows:
{<no data fields>}
show opaque-type-resolution
Show whether opaque types are resolved or not.
maint print symbols filename
maint print psymbols filename
maint print msymbols filename
Write a dump of debugging symbol data into the file filename. These commands are used to debug the GDB symbol-reading code. Only symbols with debugging data are included. If you use `maint print symbols', GDB includes all the symbols for which it has already collected full details: that is, filename reflects symbols for only those files whose symbols GDB has read. You can use the command info sources to find out which files these are. If you use `maint print psymbols' instead, the dump shows information about symbols that GDB only knows partially--that is, symbols defined in files that GDB has skimmed, but not yet read completely. Finally, `maint print msymbols' dumps just the minimal symbol information required for each object file from which GDB has read some symbols. See section Commands to specify files, for a discussion of how GDB reads symbols (in the description of symbol-file).

Altering Execution

Once you think you have found an error in your program, you might want to find out for certain whether correcting the apparent error would lead to correct results in the rest of the run. You can find the answer by experiment, using the GDB features for altering execution of the program.

For example, you can store new values into variables or memory locations, give your program a signal, restart it at a different address, or even return prematurely from a function.

  • Assignment: Assignment to variables
  • Jumping: Continuing at a different address
  • Signaling: Giving your program a signal
  • Returning: Returning from a function
  • Calling: Calling your program's functions
  • Patching: Patching your program

Assignment to variables

To alter the value of a variable, evaluate an assignment expression. See section Expressions. For example,

print x=4

stores the value 4 into the variable x, and then prints the value of the assignment expression (which is 4). See section Using GDB with Different Languages, for more information on operators in supported languages.

If you are not interested in seeing the value of the assignment, use the set command instead of the print command. set is really the same as print except that the expression's value is not printed and is not put in the value history (see section Value history). The expression is evaluated only for its effects.

If the beginning of the argument string of the set command appears identical to a set subcommand, use the set variable command instead of just set. This command is identical to set except for its lack of subcommands. For example, if your program has a variable width, you get an error if you try to set a new value with just `set width=13', because GDB has the command set width:

(gdb) whatis width
type = double
(gdb) p width
$4 = 13
(gdb) set width=47
Invalid syntax in expression.

The invalid expression, of course, is `=47'. In order to actually set the program's variable width, use

(gdb) set var width=47

Because the set command has many subcommands that can conflict with the names of program variables, it is a good idea to use the set variable command instead of just set. For example, if your program has a variable g, you run into problems if you try to set a new value with just `set g=4', because GDB has the command set gnutarget, abbreviated set g:

(gdb) whatis g
type = double
(gdb) p g
$1 = 1
(gdb) set g=4
(gdb) p g
$2 = 1
(gdb) r
The program being debugged has been started already.
Start it from the beginning? (y or n) y
Starting program: /home/smith/cc_progs/a.out
"/home/smith/cc_progs/a.out": can't open to read symbols:
                                 Invalid bfd target.
(gdb) show g
The current BFD target is "=4".

The program variable g did not change, and you silently set the gnutarget to an invalid value. In order to set the variable g, use

(gdb) set var g=4

GDB allows more implicit conversions in assignments than C; you can freely store an integer value into a pointer variable or vice versa, and you can convert any structure to any other structure that is the same length or shorter.

To store values into arbitrary places in memory, use the `{...}' construct to generate a value of specified type at a specified address (see section Expressions). For example, {int}0x83040 refers to memory location 0x83040 as an integer (which implies a certain size and representation in memory), and

set {int}0x83040 = 4

stores the value 4 into that memory location.

Continuing at a different address

Ordinarily, when you continue your program, you do so at the place where it stopped, with the continue command. You can instead continue at an address of your own choosing, with the following commands:

jump linespec
Resume execution at line linespec. Execution stops again immediately if there is a breakpoint there. See section Printing source lines, for a description of the different forms of linespec. It is common practice to use the tbreak command in conjunction with jump. See section Setting breakpoints. The jump command does not change the current stack frame, or the stack pointer, or the contents of any memory location or any register other than the program counter. If line linespec is in a different function from the one currently executing, the results may be bizarre if the two functions expect different patterns of arguments or of local variables. For this reason, the jump command requests confirmation if the specified line is not in the function currently executing. However, even bizarre results are predictable if you are well acquainted with the machine-language code of your program.
jump *address
Resume execution at the instruction at address address.

On many systems, you can get much the same effect as the jump command by storing a new value into the register $pc. The difference is that this does not start your program running; it only changes the address of where it will run when you continue. For example,

set $pc = 0x485

makes the next continue command or stepping command execute at address 0x485, rather than at the address where your program stopped. See section Continuing and stepping.

The most common occasion to use the jump command is to back up--perhaps with more breakpoints set--over a portion of a program that has already executed, in order to examine its execution in more detail.

Giving your program a signal

signal signal
Resume execution where your program stopped, but immediately give it the signal signal. signal can be the name or the number of a signal. For example, on many systems signal 2 and signal SIGINT are both ways of sending an interrupt signal. Alternatively, if signal is zero, continue execution without giving a signal. This is useful when your program stopped on account of a signal and would ordinary see the signal when resumed with the continue command; `signal 0' causes it to resume without a signal. signal does not repeat when you press RET a second time after executing the command.

Invoking the signal command is not the same as invoking the kill utility from the shell. Sending a signal with kill causes GDB to decide what to do with the signal depending on the signal handling tables (see section Signals). The signal command passes the signal directly to your program.

Returning from a function

return
return expression
You can cancel execution of a function call with the return command. If you give an expression argument, its value is used as the function's return value.

When you use return, GDB discards the selected stack frame (and all frames within it). You can think of this as making the discarded frame return prematurely. If you wish to specify a value to be returned, give that value as the argument to return.

This pops the selected stack frame (see section Selecting a frame), and any other frames inside of it, leaving its caller as the innermost remaining frame. That frame becomes selected. The specified value is stored in the registers used for returning values of functions.

The return command does not resume execution; it leaves the program stopped in the state that would exist if the function had just returned. In contrast, the finish command (see section Continuing and stepping) resumes execution until the selected stack frame returns naturally.

Calling program functions

call expr
Evaluate the expression expr without displaying void returned values.

You can use this variant of the print command if you want to execute a function from your program, but without cluttering the output with void returned values. If the result is not void, it is printed and saved in the value history.

For the A29K, a user-controlled variable call_scratch_address, specifies the location of a scratch area to be used when GDB calls a function in the target. This is necessary because the usual method of putting the scratch area on the stack does not work in systems that have separate instruction and data spaces.

Patching programs

By default, GDB opens the file containing your program's executable code (or the corefile) read-only. This prevents accidental alterations to machine code; but it also prevents you from intentionally patching your program's binary.

If you'd like to be able to patch the binary, you can specify that explicitly with the set write command. For example, you might want to turn on internal debugging flags, or even to make emergency repairs.

set write on
set write off
If you specify `set write on', GDB opens executable and core files for both reading and writing; if you specify `set write off' (the default), GDB opens them read-only. If you have already loaded a file, you must load it again (using the exec-file or core-file command) after changing set write, for your new setting to take effect.
show write
Display whether executable files and core files are opened for writing as well as reading.

GDB Files

GDB needs to know the file name of the program to be debugged, both in order to read its symbol table and in order to start your program. To debug a core dump of a previous run, you must also tell GDB the name of the core dump file.

  • Files: Commands to specify files
  • Symbol Errors: Errors reading symbol files

Commands to specify files

You may want to specify executable and core dump file names. The usual way to do this is at start-up time, using the arguments to GDB's start-up commands (see section Getting In and Out of GDB).

Occasionally it is necessary to change to a different file during a GDB session. Or you may run GDB and forget to specify a file you want to use. In these situations the GDB commands to specify new files are useful.

file filename
Use filename as the program to be debugged. It is read for its symbols and for the contents of pure memory. It is also the program executed when you use the run command. If you do not specify a directory and the file is not found in the GDB working directory, GDB uses the environment variable PATH as a list of directories to search, just as the shell does when looking for a program to run. You can change the value of this variable, for both GDB and your program, using the path command. On systems with memory-mapped files, an auxiliary file named `filename.syms' may hold symbol table information for filename. If so, GDB maps in the symbol table from `filename.syms', starting up more quickly. See the descriptions of the file options `-mapped' and `-readnow' (available on the command line, and with the commands file, symbol-file, or add-symbol-file, described below), for more information.
file
file with no argument makes GDB discard any information it has on both executable file and the symbol table.
exec-file [ filename ]
Specify that the program to be run (but not the symbol table) is found in filename. GDB searches the environment variable PATH if necessary to locate your program. Omitting filename means to discard information on the executable file.
symbol-file [ filename ]
Read symbol table information from file filename. PATH is searched when necessary. Use the file command to get both symbol table and program to run from the same file. symbol-file with no argument clears out GDB information on your program's symbol table. The symbol-file command causes GDB to forget the contents of its convenience variables, the value history, and all breakpoints and auto-display expressions. This is because they may contain pointers to the internal data recording symbols and data types, which are part of the old symbol table data being discarded inside GDB. symbol-file does not repeat if you press RET again after executing it once. When GDB is configured for a particular environment, it understands debugging information in whatever format is the standard generated for that environment; you may use either a GNU compiler, or other compilers that adhere to the local conventions. Best results are usually obtained from GNU compilers; for example, using gcc you can generate debugging information for optimized code. For most kinds of object files, with the exception of old SVR3 systems using COFF, the symbol-file command does not normally read the symbol table in full right away. Instead, it scans the symbol table quickly to find which source files and which symbols are present. The details are read later, one source file at a time, as they are needed. The purpose of this two-stage reading strategy is to make GDB start up faster. For the most part, it is invisible except for occasional pauses while the symbol table details for a particular source file are being read. (The set verbose command can turn these pauses into messages if desired. See section Optional warnings and messages.) We have not implemented the two-stage strategy for COFF yet. When the symbol table is stored in COFF format, symbol-file reads the symbol table data in full right away. Note that "stabs-in-COFF" still does the two-stage strategy, since the debug info is actually in stabs format.
symbol-file filename [ -readnow ] [ -mapped ]
file filename [ -readnow ] [ -mapped ]
You can override the GDB two-stage strategy for reading symbol tables by using the `-readnow' option with any of the commands that load symbol table information, if you want to be sure GDB has the entire symbol table available. If memory-mapped files are available on your system through the mmap system call, you can use another option, `-mapped', to cause GDB to write the symbols for your program into a reusable file. Future GDB debugging sessions map in symbol information from this auxiliary symbol file (if the program has not changed), rather than spending time reading the symbol table from the executable program. Using the `-mapped' option has the same effect as starting GDB with the `-mapped' command-line option. You can use both options together, to make sure the auxiliary symbol file has all the symbol information for your program. The auxiliary symbol file for a program called myprog is called `myprog.syms'. Once this file exists (so long as it is newer than the corresponding executable), GDB always attempts to use it when you debug myprog; no special options or commands are needed. The `.syms' file is specific to the host machine where you run GDB. It holds an exact image of the internal GDB symbol table. It cannot be shared across multiple host platforms.
core-file [ filename ]
Specify the whereabouts of a core dump file to be used as the "contents of memory". Traditionally, core files contain only some parts of the address space of the process that generated them; GDB can access the executable file itself for other parts. core-file with no argument specifies that no core file is to be used. Note that the core file is ignored when your program is actually running under GDB. So, if you have been running your program and you wish to debug a core file instead, you must kill the subprocess in which the program is running. To do this, use the kill command (see section Killing the child process).
add-symbol-file filename address
add-symbol-file filename address [ -readnow ] [ -mapped ]
add-symbol-file filename -ssection address
The add-symbol-file command reads additional symbol table information from the file filename. You would use this command when filename has been dynamically loaded (by some other means) into the program that is running. address should be the memory address at which the file has been loaded; GDB cannot figure this out for itself. You can additionally specify an arbitrary number of `-ssection address' pairs, to give an explicit section name and base address for that section. You can specify any address as an expression. The symbol table of the file filename is added to the symbol table originally read with the symbol-file command. You can use the add-symbol-file command any number of times; the new symbol data thus read keeps adding to the old. To discard all old symbol data instead, use the symbol-file command without any arguments. add-symbol-file does not repeat if you press RET after using it. You can use the `-mapped' and `-readnow' options just as with the symbol-file command, to change how GDB manages the symbol table information for filename.
add-shared-symbol-file
The add-shared-symbol-file command can be used only under Harris' CXUX operating system for the Motorola 88k. GDB automatically looks for shared libraries, however if GDB does not find yours, you can run add-shared-symbol-file. It takes no arguments.
section
The section command changes the base address of section SECTION of the exec file to ADDR. This can be used if the exec file does not contain section addresses, (such as in the a.out format), or when the addresses specified in the file itself are wrong. Each section must be changed separately. The info files command, described below, lists all the sections and their addresses.
info files
info target
info files and info target are synonymous; both print the current target (see section Specifying a Debugging Target), including the names of the executable and core dump files currently in use by GDB, and the files from which symbols were loaded. The command help target lists all possible targets rather than current ones.

All file-specifying commands allow both absolute and relative file names as arguments. GDB always converts the file name to an absolute file name and remembers it that way.

GDB supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared libraries.

GDB automatically loads symbol definitions from shared libraries when you use the run command, or when you examine a core file. (Before you issue the run command, GDB does not understand references to a function in a shared library, however--unless you are debugging a core file).

On HP-UX, if the program loads a library explicitly, GDB automatically loads the symbols at the time of the shl_load call.

info share
info sharedlibrary
Print the names of the shared libraries which are currently loaded.
sharedlibrary regex
share regex
Load shared object library symbols for files matching a Unix regular expression. As with files loaded automatically, it only loads shared libraries required by your program for a core file or after typing run. If regex is omitted all shared libraries required by your program are loaded.

On HP-UX systems, GDB detects the loading of a shared library and automatically reads in symbols from the newly loaded library, up to a threshold that is initially set but that you can modify if you wish.

Beyond that threshold, symbols from shared libraries must be explicitly loaded. To load these symbols, use the command sharedlibrary filename. The base address of the shared library is determined automatically by GDB and need not be specified.

To display or set the threshold, use the commands:

set auto-solib-add threshold
Set the autoloading size threshold, in megabytes. If threshold is nonzero, symbols from all shared object libraries will be loaded automatically when the inferior begins execution or when the dynamic linker informs GDB that a new library has been loaded, until the symbol table of the program and libraries exceeds this threshold. Otherwise, symbols must be loaded manually, using the sharedlibrary command. The default threshold is 100 megabytes.
show auto-solib-add
Display the current autoloading size threshold, in megabytes.

Errors reading symbol files

While reading a symbol file, GDB occasionally encounters problems, such as symbol types it does not recognize, or known bugs in compiler output. By default, GDB does not notify you of such problems, since they are relatively common and primarily of interest to people debugging compilers. If you are interested in seeing information about ill-constructed symbol tables, you can either ask GDB to print only one message about each such type of problem, no matter how many times the problem occurs; or you can ask GDB to print more messages, to see how many times the problems occur, with the set complaints command (see section Optional warnings and messages).

The messages currently printed, and their meanings, include:

inner block not inside outer block in symbol
The symbol information shows where symbol scopes begin and end (such as at the start of a function or a block of statements). This error indicates that an inner scope block is not fully contained in its outer scope blocks. GDB circumvents the problem by treating the inner block as if it had the same scope as the outer block. In the error message, symbol may be shown as "(don't know)" if the outer block is not a function.
block at address out of order
The symbol information for symbol scope blocks should occur in order of increasing addresses. This error indicates that it does not do so. GDB does not circumvent this problem, and has trouble locating symbols in the source file whose symbols it is reading. (You can often determine what source file is affected by specifying set verbose on. See section Optional warnings and messages.)
bad block start address patched
The symbol information for a symbol scope block has a start address smaller than the address of the preceding source line. This is known to occur in the SunOS 4.1.1 (and earlier) C compiler. GDB circumvents the problem by treating the symbol scope block as starting on the previous source line.
bad string table offset in symbol n
Symbol number n contains a pointer into the string table which is larger than the size of the string table. GDB circumvents the problem by considering the symbol to have the name foo, which may cause other problems if many symbols end up with this name.
unknown symbol type 0xnn
The symbol information contains new data types that GDB does not yet know how to read. 0xnn is the symbol type of the uncomprehended information, in hexadecimal. GDB circumvents the error by ignoring this symbol information. This usually allows you to debug your program, though certain symbols are not accessible. If you encounter such a problem and feel like debugging it, you can debug gdb with itself, breakpoint on complain, then go up to the function read_dbx_symtab and examine *bufp to see the symbol.
stub type has NULL name
GDB could not find the full definition for a struct or class.
const/volatile indicator missing (ok if using g++ v1.x), got...
The symbol information for a C++ member function is missing some information that recent versions of the compiler should have output for it.
info mismatch between compiler and debugger
GDB could not parse a type specification output by the compiler.

Specifying a Debugging Target

A target is the execution environment occupied by your program.

Often, GDB runs in the same host environment as your program; in that case, the debugging target is specified as a side effect when you use the file or core commands. When you need more flexibility--for example, running GDB on a physically separate host, or controlling a standalone system over a serial port or a realtime system over a TCP/IP connection--you can use the target command to specify one of the target types configured for GDB (see section Commands for managing targets).

  • Active Targets: Active targets
  • Target Commands: Commands for managing targets
  • Byte Order: Choosing target byte order
  • Remote: Remote debugging
  • KOD: Kernel Object Display

Active targets

There are three classes of targets: processes, core files, and executable files. GDB can work concurrently on up to three active targets, one in each class. This allows you to (for example) start a process and inspect its activity without abandoning your work on a core file.

For example, if you execute `gdb a.out', then the executable file a.out is the only active target. If you designate a core file as well--presumably from a prior run that crashed and coredumped--then GDB has two active targets and uses them in tandem, looking first in the corefile target, then in the executable file, to satisfy requests for memory addresses. (Typically, these two classes of target are complementary, since core files contain only a program's read-write memory--variables and so on--plus machine status, while executable files contain only the program text and initialized data.)

When you type run, your executable file becomes an active process target as well. When a process target is active, all GDB commands requesting memory addresses refer to that target; addresses in an active core file or executable file target are obscured while the process target is active.

Use the core-file and exec-file commands to select a new core file or executable target (see section Commands to specify files). To specify as a target a process that is already running, use the attach command (see section Debugging an already-running process).

Commands for managing targets

target type parameters
Connects the GDB host environment to a target machine or process. A target is typically a protocol for talking to debugging facilities. You use the argument type to specify the type or protocol of the target machine. Further parameters are interpreted by the target protocol, but typically include things like device names or host names to connect with, process numbers, and baud rates. The target command does not repeat if you press RET again after executing the command.
help target
Displays the names of all targets available. To display targets currently selected, use either info target or info files (see section Commands to specify files).
help target name
Describe a particular target, including any parameters necessary to select it.
set gnutarget args
GDB uses its own library BFD to read your files. GDB knows whether it is reading an executable, a core, or a .o file; however, you can specify the file format with the set gnutarget command. Unlike most target commands, with gnutarget the target refers to a program, not a machine.

Warning: To specify a file format with set gnutarget, you must know the actual BFD name.

See section Commands to specify files.
show gnutarget
Use the show gnutarget command to display what file format gnutarget is set to read. If you have not set gnutarget, GDB will determine the file format for each file automatically, and show gnutarget displays `The current BDF target is "auto"'.

Here are some common targets (available, or not, depending on the GDB configuration):

target exec program
An executable file. `target exec program' is the same as `exec-file program'.
target core filename
A core dump file. `target core filename' is the same as `core-file filename'.
target remote dev
Remote serial target in GDB-specific protocol. The argument dev specifies what serial device to use for the connection (e.g. `/dev/ttya'). See section Remote debugging. target remote supports the load command. This is only useful if you have some other way of getting the stub to the target system, and you can put it somewhere in memory where it won't get clobbered by the download.
target sim
Builtin CPU simulator. GDB includes simulators for most architectures. In general,
        target sim
        load
        run
works; however, you cannot assume that a specific memory map, device drivers, or even basic I/O is available, although some simulators do provide these. For info about any processor-specific simulator details, see the appropriate section in section Embedded Processors.

Some configurations may include these targets as well:

target nrom dev
NetROM ROM emulator. This target only supports downloading.

Different targets are available on different configurations of GDB; your configuration may have more or fewer targets.

Many remote targets require you to download the executable's code once you've successfully established a connection.

load filename
Depending on what remote debugging facilities are configured into GDB, the load command may be available. Where it exists, it is meant to make filename (an executable) available for debugging on the remote system--by downloading, or dynamic linking, for example. load also records the filename symbol table in GDB, like the add-symbol-file command. If your GDB does not have a load command, attempting to execute it gets the error message "You can't do that when your target is ..." The file is loaded at whatever address is specified in the executable. For some object file formats, you can specify the load address when you link the program; for other formats, like a.out, the object file format specifies a fixed address. load does not repeat if you press RET again after using it.

Choosing target byte order

Some types of processors, such as the MIPS, PowerPC, and Hitachi SH, offer the ability to run either big-endian or little-endian byte orders. Usually the executable or symbol will include a bit to designate the endian-ness, and you will not need to worry about which to use. However, you may still find it useful to adjust GDB's idea of processor endian-ness manually.

set endian big
Instruct GDB to assume the target is big-endian.
set endian little
Instruct GDB to assume the target is little-endian.
set endian auto
Instruct GDB to use the byte order associated with the executable.
show endian
Display GDB's current idea of the target byte order.

Note that these commands merely adjust interpretation of symbolic data on the host, and that they have absolutely no effect on the target system.

Remote debugging

If you are trying to debug a program running on a machine that cannot run GDB in the usual way, it is often useful to use remote debugging. For example, you might use remote debugging on an operating system kernel, or on a small system which does not have a general purpose operating system powerful enough to run a full-featured debugger.

Some configurations of GDB have special serial or TCP/IP interfaces to make this work with particular debugging targets. In addition, GDB comes with a generic serial protocol (specific to GDB, but not specific to any particular target system) which you can use if you write the remote stubs--the code that runs on the remote system to communicate with GDB.

Other remote targets may be available in your configuration of GDB; use help target to list them.

  • Remote Serial: GDB remote serial protocol

The GDB remote serial protocol

To debug a program running on another machine (the debugging target machine), you must first arrange for all the usual prerequisites for the program to run by itself. For example, for a C program, you need:

  1. A startup routine to set up the C runtime environment; these usually have a name like `crt0'. The startup routine may be supplied by your hardware supplier, or you may have to write your own.
  2. A C subroutine library to support your program's subroutine calls, notably managing input and output.
  3. A way of getting your program to the other machine--for example, a download program. These are often supplied by the hardware manufacturer, but you may have to write your own from hardware documentation.

The next step is to arrange for your program to use a serial port to communicate with the machine where GDB is running (the host machine). In general terms, the scheme looks like this:

On the host,
GDB already understands how to use this protocol; when everything else is set up, you can simply use the `target remote' command (see section Specifying a Debugging Target).
On the target,
you must link with your program a few special-purpose subroutines that implement the GDB remote serial protocol. The file containing these subroutines is called a debugging stub. On certain remote targets, you can use an auxiliary program gdbserver instead of linking a stub into your program. See section Using the gdbserver program, for details.

The debugging stub is specific to the architecture of the remote machine; for example, use `sparc-stub.c' to debug programs on SPARC boards.

These working remote stubs are distributed with GDB:

i386-stub.c
For Intel 386 and compatible architectures.
m68k-stub.c
For Motorola 680x0 architectures.
sh-stub.c
For Hitachi SH architectures.
sparc-stub.c
For SPARC architectures.
sparcl-stub.c
For Fujitsu SPARCLITE architectures.

The `README' file in the GDB distribution may list other recently added stubs.

  • Stub Contents: What the stub can do for you
  • Bootstrapping: What you must do for the stub
  • Debug Session: Putting it all together
  • Protocol: Definition of the communication protocol
  • Server: Using the `gdbserver' program
  • NetWare: Using the `gdbserve.nlm' program

What the stub can do for you

The debugging stub for your architecture supplies these three subroutines:

set_debug_traps
This routine arranges for handle_exception to run when your program stops. You must call this subroutine explicitly near the beginning of your program.
handle_exception
This is the central workhorse, but your program never calls it explicitly--the setup code arranges for handle_exception to run when a trap is triggered. handle_exception takes control when your program stops during execution (for example, on a breakpoint), and mediates communications with GDB on the host machine. This is where the communications protocol is implemented; handle_exception acts as the GDB representative on the target machine. It begins by sending summary information on the state of your program, then continues to execute, retrieving and transmitting any information GDB needs, until you execute a GDB command that makes your program resume; at that point, handle_exception returns control to your own code on the target machine.
breakpoint
Use this auxiliary subroutine to make your program contain a breakpoint. Depending on the particular situation, this may be the only way for GDB to get control. For instance, if your target machine has some sort of interrupt button, you won't need to call this; pressing the interrupt button transfers control to handle_exception---in effect, to GDB. On some machines, simply receiving characters on the serial port may also trigger a trap; again, in that situation, you don't need to call breakpoint from your own program--simply running `target remote' from the host GDB session gets control. Call breakpoint if none of these is true, or if you simply want to make certain your program stops at a predetermined point for the start of your debugging session.

What you must do for the stub

The debugging stubs that come with GDB are set up for a particular chip architecture, but they have no information about the rest of your debugging target machine.

First of all you need to tell the stub how to communicate with the serial port.

int getDebugChar()
Write this subroutine to read a single character from the serial port. It may be identical to getchar for your target system; a different name is used to allow you to distinguish the two if you wish.
void putDebugChar(int)
Write this subroutine to write a single character to the serial port. It may be identical to putchar for your target system; a different name is used to allow you to distinguish the two if you wish.

If you want GDB to be able to stop your program while it is running, you need to use an interrupt-driven serial driver, and arrange for it to stop when it receives a ^C (`\003', the control-C character). That is the character which GDB uses to tell the remote system to stop.

Getting the debugging target to return the proper status to GDB probably requires changes to the standard stub; one quick and dirty way is to just execute a breakpoint instruction (the "dirty" part is that GDB reports a SIGTRAP instead of a SIGINT).

Other routines you need to supply are:

void exceptionHandler (int exception_number, void *exception_address)
Write this function to install exception_address in the exception handling tables. You need to do this because the stub does not have any way of knowing what the exception handling tables on your target system are like (for example, the processor's table might be in ROM, containing entries which point to a table in RAM). exception_number is the exception number which should be changed; its meaning is architecture-dependent (for example, different numbers might represent divide by zero, misaligned access, etc). When this exception occurs, control should be transferred directly to exception_address, and the processor state (stack, registers, and so on) should be just as it is when a processor exception occurs. So if you want to use a jump instruction to reach exception_address, it should be a simple jump, not a jump to subroutine. For the 386, exception_address should be installed as an interrupt gate so that interrupts are masked while the handler runs. The gate should be at privilege level 0 (the most privileged level). The SPARC and 68k stubs are able to mask interrupts themselves without help from exceptionHandler.
void flush_i_cache()
On SPARC and SPARCLITE only, write this subroutine to flush the instruction cache, if any, on your target machine. If there is no instruction cache, this subroutine may be a no-op. On target machines that have instruction caches, GDB requires this function to make certain that the state of your program is stable.

You must also make sure this library routine is available:

void *memset(void *, int, int)
This is the standard library function memset that sets an area of memory to a known value. If you have one of the free versions of libc.a, memset can be found there; otherwise, you must either obtain it from your hardware manufacturer, or write your own.

If you do not use the GNU C compiler, you may need other standard library subroutines as well; this varies from one stub to another, but in general the stubs are likely to use any of the common library subroutines which gcc generates as inline code.

Putting it all together

In summary, when your program is ready to debug, you must follow these steps.

  1. Make sure you have defined the supporting low-level routines (see section What you must do for the stub):
    getDebugChar, putDebugChar,
flush_i_cache, memset, exceptionHandler.
  2. Insert these lines near the top of your program:
    set_debug_traps();
breakpoint();
  3. For the 680x0 stub only, you need to provide a variable called exceptionHook. Normally you just use:
    void (*exceptionHook)() = 0;
    but if before calling set_debug_traps, you set it to point to a function in your program, that function is called when GDB continues after stopping on a trap (for example, bus error). The function indicated by exceptionHook is called with one parameter: an int which is the exception number.
  4. Compile and link together: your program, the GDB debugging stub for your target architecture, and the supporting subroutines.
  5. Make sure you have a serial connection between your target machine and the GDB host, and identify the serial port on the host.
  6. Download your program to your target machine (or get it there by whatever means the manufacturer provides), and start it.
  7. To start remote debugging, run GDB on the host machine, and specify as an executable file the program that is running in the remote machine. This tells GDB how to find your program's symbols and the contents of its pure text.
  8. Establish communication using the target remote command. Its argument specifies how to communicate with the target machine--either via a devicename attached to a direct serial line, or a TCP port (usually to a terminal server which in turn has a serial line to the target). For example, to use a serial line connected to the device named `/dev/ttyb':
    target remote /dev/ttyb
    To use a TCP connection, use an argument of the form host:port. For example, to connect to port 2828 on a terminal server named manyfarms:
    target remote manyfarms:2828

Now you can use all the usual commands to examine and change data and to step and continue the remote program.

To resume the remote program and stop debugging it, use the detach command.

Whenever GDB is waiting for the remote program, if you type the interrupt character (often C-C), GDB attempts to stop the program. This may or may not succeed, depending in part on the hardware and the serial drivers the remote system uses. If you type the interrupt character once again, GDB displays this prompt:

Interrupted while waiting for the program.
Give up (and stop debugging it)?  (y or n)

If you type y, GDB abandons the remote debugging session. (If you decide you want to try again later, you can use `target remote' again to connect once more.) If you type n, GDB goes back to waiting.

Communication protocol

The stub files provided with GDB implement the target side of the communication protocol, and the GDB side is implemented in the GDB source file `remote.c'. Normally, you can simply allow these subroutines to communicate, and ignore the details. (If you're implementing your own stub file, you can still ignore the details: start with one of the existing stub files. `sparc-stub.c' is the best organized, and therefore the easiest to read.)

However, there may be occasions when you need to know something about the protocol--for example, if there is only one serial port to your target machine, you might want your program to do something special if it recognizes a packet meant for GDB.

In the examples below, `<-' and `->' are used to indicate transmitted and received data respectfully.

All GDB commands and responses (other than acknowledgments) are sent as a packet. A packet is introduced with the character `$', the actual packet-data, and the terminating character `#' followed by a two-digit checksum:

$packet-data#checksum

The two-digit checksum is computed as the modulo 256 sum of all characters between the leading `$' and the trailing `#' (an eight bit unsigned checksum).

Implementors should note that prior to GDB 5.0 the protocol specification also included an optional two-digit sequence-id:

$sequence-id:packet-data#checksum

That sequence-id was appended to the acknowledgment. GDB has never output sequence-ids. Stubs that handle packets added since GDB 5.0 must not accept sequence-id.

When either the host or the target machine receives a packet, the first response expected is an acknowledgment: either `+' (to indicate the package was received correctly) or `-' (to request retransmission):

<- $packet-data#checksum
-> +

The host (GDB) sends commands, and the target (the debugging stub incorporated in your program) sends a response. In the case of step and continue commands, the response is only sent when the operation has completed (the target has again stopped).

packet-data consists of a sequence of characters with the exception of `#' and `$' (see `X' packet for additional exceptions).

Fields within the packet should be separated using `,' `;' or `:'. Except where otherwise noted all numbers are represented in HEX with leading zeros suppressed.

Implementors should note that prior to GDB 5.0, the character `:' could not appear as the third character in a packet (as it would potentially conflict with the sequence-id).

Response data can be run-length encoded to save space. A `*' means that the next character is an ASCII encoding giving a repeat count which stands for that many repetitions of the character preceding the `*'. The encoding is n+29, yielding a printable character where n >=3 (which is where rle starts to win). The printable characters `$', `#', `+' and `-' or with a numeric value greater than 126 should not be used.

Some remote systems have used a different run-length encoding mechanism loosely refered to as the cisco encoding. Following the `*' character are two hex digits that indicate the size of the packet.

So:

"0* "

means the same as "0000".

The error response returned for some packets includes a two character error number. That number is not well defined.

For any command not supported by the stub, an empty response (`$#00') should be returned. That way it is possible to extend the protocol. A newer GDB can tell if a packet is supported based on that response.

A stub is required to support the `g', `G', `m', `M', `c', and `s' commands. All other commands are optional.

Below is a complete list of all currently defined commands and their corresponding response data:
Packet | Request | Description
extended mode | ! | Enable extended mode. In extended mode, the remote server is made persistent. The `R' packet is used to restart the program being debugged.
 | reply `OK' | The remote target both supports and has enabled extended mode.
last signal | ? | Indicate the reason the target halted. The reply is the same as for step and continue.
 | reply | see below
reserved | a | Reserved for future use
set program arguments (reserved) | A arglen,argnum,arg,... |
 |  | Initialized `argv[]' array passed into program. arglen specifies the number of bytes in the hex encoded byte stream arg. See `gdbserver' for more details.
 | reply OK
 | reply E NN
set baud (deprecated) | b baud | Change the serial line speed to baud. JTC: When does the transport layer state change? When it's received, or after the ACK is transmitted. In either case, there are problems if the command or the acknowledgment packet is dropped. Stan: If people really wanted to add something like this, and get it working for the first time, they ought to modify ser-unix.c to send some kind of out-of-band message to a specially-setup stub and have the switch happen "in between" packets, so that from remote protocol's point of view, nothing actually happened.
set breakpoint (deprecated) | B addr,mode | Set (mode is `S') or clear (mode is `C') a breakpoint at addr. This has been replaced by the `Z' and `z' packets.
continue | c addr | addr is address to resume. If addr is omitted, resume at current address.
 | reply | see below
continue with signal | C sig;addr | Continue with signal sig (hex signal number). If ;addr is omitted, resume at same address.
 | reply | see below
toggle debug (deprecated) | d | toggle debug flag.
detach | D | Detach GDB from the remote system. Sent to the remote target before GDB disconnects.
 | reply no response | GDB does not check for any response after sending this packet.
reserved | e | Reserved for future use
reserved | E | Reserved for future use
reserved | f | Reserved for future use
reserved | F | Reserved for future use
read registers | g | Read general registers.
 | reply XX... | Each byte of register data is described by two hex digits. The bytes with the register are transmitted in target byte order. The size of each register and their position within the `g' packet are determined by the GDB internal macros REGISTER_RAW_SIZE and REGISTER_NAME macros. The specification of several standard g packets is specified below.
 | E NN | for an error.
write regs | G XX... | See `g' for a description of the XX... data.
 | reply OK | for success
 | reply E NN | for an error
reserved | h | Reserved for future use
set thread | H ct... | Set thread for subsequent operations (`m', `M', `g', `G', et.al.). c = `c' for thread used in step and continue; t... can be -1 for all threads. c = `g' for thread used in other operations. If zero, pick a thread, any thread.
 | reply OK | for success
 | reply E NN | for an error
cycle step (draft) | i addr,nnn | Step the remote target by a single clock cycle. If ,nnn is present, cycle step nnn cycles. If addr is present, cycle step starting at that address.
signal then cycle step (reserved) | I | See `i' and `S' for likely syntax and semantics.
reserved | j | Reserved for future use
reserved | J | Reserved for future use
kill request | k | FIXME: There is no description of how operate when a specific thread context has been selected (ie. does 'k' kill only that thread?).
reserved | l | Reserved for future use
reserved | L | Reserved for future use
read memory | m addr,length | Read length bytes of memory starting at address addr. Neither GDB nor the stub assume that sized memory transfers are assumed using word alligned accesses. FIXME: A word aligned memory transfer mechanism is needed.
 | reply XX... | XX... is mem contents. Can be fewer bytes than requested if able to read only part of the data. Neither GDB nor the stub assume that sized memory transfers are assumed using word alligned accesses. FIXME: A word aligned memory transfer mechanism is needed.
 | reply E NN | NN is errno
write mem | M addr,length:XX... | Write length bytes of memory starting at address addr. XX... is the data.
 | reply OK | for success
 | reply E NN | for an error (this includes the case where only part of the data was written).
reserved | n | Reserved for future use
reserved | N | Reserved for future use
reserved | o | Reserved for future use
reserved | O | Reserved for future use
read reg (reserved) | p n... | See write register.
 | return r.... | The hex encoded value of the register in target byte order.
write reg | P n...=r... | Write register n... with value r..., which contains two hex digits for each byte in the register (target byte order).
 | reply OK | for success
 | reply E NN | for an error
general query | q query | Request info about query. In general GDB queries have a leading upper case letter. Custom vendor queries should use a company prefix (in lower case) ex: `qfsf.var'. query may optionally be followed by a `,' or `;' separated list. Stubs must ensure that they match the full query name.
 | reply XX... | Hex encoded data from query. The reply can not be empty.
 | reply E NN | error reply
 | reply `' | Indicating an unrecognized query.
general set | Q var=val | Set value of var to val. See `q' for a discussing of naming conventions.
reset (deprecated) | r | Reset the entire system.
remote restart | R XX | Restart the program being debugged. XX, while needed, is ignored. This packet is only available in extended mode.
 | no reply | The `R' packet has no reply.
step | s addr | addr is address to resume. If addr is omitted, resume at same address.
 | reply | see below
step with signal | S sig;addr | Like `C' but step not continue.
 | reply | see below
search | t addr:PP,MM | Search backwards starting at address addr for a match with pattern PP and mask MM. PP and MM are 4 bytes. addr must be at least 3 digits.
thread alive | T XX | Find out if the thread XX is alive.
 | reply OK | thread is still alive
 | reply E NN | thread is dead
reserved | u | Reserved for future use
reserved | U | Reserved for future use
reserved | v | Reserved for future use
reserved | V | Reserved for future use
reserved | w | Reserved for future use
reserved | W | Reserved for future use
reserved | x | Reserved for future use
write mem (binary) | X addr,length:XX... | addr is address, length is number of bytes, XX... is binary data. The characters $, #, and 0x7d are escaped using 0x7d.
 | reply OK | for success
 | reply E NN | for an error
reserved | y | Reserved for future use
reserved | Y | Reserved for future use
remove break or watchpoint (draft) | z t,addr,length | See `Z'.
insert break or watchpoint (draft) | Z t,addr,length | t is type: `0' - software breakpoint, `1' - hardware breakpoint, `2' - write watchpoint, `3' - read watchpoint, `4' - access watchpoint; addr is address; length is in bytes. For a software breakpoint, length specifies the size of the instruction to be patched. For hardware breakpoints and watchpoints length specifies the memory region to be monitored. To avoid potential problems with duplicate packets, the operations should be implemented in an idempotent way.
 | reply E NN | for an error
 | reply OK | for success
 | `' | If not supported.
reserved | <other> | Reserved for future use

The `C', `c', `S', `s' and `?' packets can receive any of the below as a reply. In the case of the `C', `c', `S' and `s' packets, that reply is only returned when the target halts. In the below the exact meaning of `signal number' is poorly defined. In general one of the UNIX signal numbering conventions is used.
S AA | AA is the signal number
T AAn...:r...;n...:r...;n...:r...; | AA = two hex digit signal number; n... = register number (hex), r... = target byte ordered register contents, size defined by REGISTER_RAW_SIZE; n... = `thread', r... = thread process ID, this is a hex integer; n... = other string not starting with valid hex digit. GDB should ignore this n..., r... pair and go on to the next. This way we can extend the protocol.
W AA | The process exited, and AA is the exit status. This is only applicable for certains sorts of targets.
X AA | The process terminated with signal AA.
N AA;t...;d...;b... (obsolete) | AA = signal number; t... = address of symbol "_start"; d... = base of data section; b... = base of bss section. Note: only used by Cisco Systems targets. The difference between this reply and the "qOffsets" query is that the 'N' packet may arrive spontaneously whereas the 'qOffsets' is a query initiated by the host debugger.
O XX... | XX... is hex encoding of ASCII data. This can happen at any time while the program is running and the debugger should continue to wait for 'W', 'T', etc.

The following set and query packets have already been defined.
current thread | qC | Return the current thread id.
 | reply QC pid | Where pid is a HEX encoded 16 bit process id.
 | reply * | Any other reply implies the old pid.
all thread ids | qfThreadInfo
 | qsThreadInfo | Obtain a list of active thread ids from the target (OS). Since there may be too many active threads to fit into one reply packet, this query works iteratively: it may require more than one query/reply sequence to obtain the entire list of threads. The first query of the sequence will be the qfThreadInfo query; subsequent queries in the sequence will be the qsThreadInfo query.
 |  | NOTE: replaces the qL query (see below).
 | reply m<id> | A single thread id
 | reply m<id>,<id>... | a comma-separated list of thread ids
 | reply l | (lower case 'el') denotes end of list.
 |  | In response to each query, the target will reply with a list of one or more thread ids, in big-endian hex, separated by commas. GDB will respond to each reply with a request for more thread ids (using the qs form of the query), until the target responds with l (lower-case el, for 'last').
extra thread info | qThreadExtraInfo,id |
 |  | Where <id> is a thread-id in big-endian hex. Obtain a printable string description of a thread's attributes from the target OS. This string may contain anything that the target OS thinks is interesting for GDB to tell the user about the thread. The string is displayed in GDB's `info threads' display. Some examples of possible thread extra info strings are "Runnable", or "Blocked on Mutex".
 | reply XX... | Where XX... is a hex encoding of ASCII data, comprising the printable string containing the extra information about the thread's attributes.
query LIST or threadLIST (deprecated) | qL startflagthreadcountnextthread |
 |  | Obtain thread information from RTOS. Where: startflag (one hex digit) is one to indicate the first query and zero to indicate a subsequent query; threadcount (two hex digits) is the maximum number of threads the response packet can contain; and nextthread (eight hex digits), for subsequent queries (startflag is zero), is returned in the response as argthread.
 |  | NOTE: this query is replaced by the qfThreadInfo query (see above).
 | reply qM countdoneargthreadthread... |
 |  | Where: count (two hex digits) is the number of threads being returned; done (one hex digit) is zero to indicate more threads and one indicates no further threads; argthreadid (eight hex digits) is nextthread from the request packet; thread... is a sequence of thread IDs from the target. threadid (eight hex digits). See remote.c:parse_threadlist_response().
compute CRC of memory block | qCRC:addr,length |
 | reply E NN | An error (such as memory fault)
 | reply C CRC32 | A 32 bit cyclic redundancy check of the specified memory region.
query sect offs | qOffsets | Get section offsets that the target used when re-locating the downloaded image. Note: while a Bss offset is included in the response, GDB ignores this and instead applies the Data offset to the Bss section.
 | reply Text=xxx;Data=yyy;Bss=zzz
thread info request | qP modethreadid |
 |  | Returns information on threadid. Where: mode is a hex encoded 32 bit mode; threadid is a hex encoded 64 bit thread ID.
 | reply * | See remote.c:remote_unpack_thread_info_response().
remote command | qRcmd,COMMAND |
 |  | COMMAND (hex encoded) is passed to the local interpreter for execution. Invalid commands should be reported using the output string. Before the final result packet, the target may also respond with a number of intermediate O OUTPUT console output packets. Implementors should note that providing access to a stubs's interpreter may have security implications.
 | reply OK | A command response with no output.
 | reply OUTPUT | A command response with the hex encoded output string OUTPUT.
 | reply E NN | Indicate a badly formed request.
 | reply `' | When `q'`Rcmd' is not recognized.
symbol lookup | qSymbol:: | Notify the target that GDB is prepared to serve symbol lookup requests. Accept requests from the target for the values of symbols.
 | reply OK | The target does not need to look up any (more) symbols.
 | reply qSymbol:sym_name | The target requests the value of symbol sym_name (hex encoded). GDB may provide the value by using the qSymbol:sym_value:sym_name message, described below.
symbol value | qSymbol:sym_value:sym_name | Set the value of SYM_NAME to SYM_VALUE.
 |  | sym_name (hex encoded) is the name of a symbol whose value the target has previously requested.
 |  | sym_value (hex) is the value for symbol sym_name. If GDB cannot supply a value for sym_name, then this field will be empty.
 | reply OK | The target does not need to look up any (more) symbols.
 | reply qSymbol:sym_name | The target requests the value of a new symbol sym_name (hex encoded). GDB will continue to supply the values of symbols (if available), until the target ceases to request them.

The following `g'/`G' packets have previously been defined. In the below, some thirty-two bit registers are transferred as sixty-four bits. Those registers should be zero/sign extended (which?) to fill the space allocated. Register bytes are transfered in target byte order. The two nibbles within a register byte are transfered most-significant - least-significant.
MIPS32 | All registers are transfered as thirty-two bit quantities in the order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point registers; fsr; fir; fp.
MIPS64 | All registers are transfered as sixty-four bit quantities (including thirty-two bit registers such as sr). The ordering is the same as MIPS32.

Example sequence of a target being re-started. Notice how the restart does not get any direct output:

<- R00
-> +
target restarts
<- ?
-> +
-> T001:1234123412341234
<- +

Example sequence of a target being stepped by a single instruction:

<- G1445...
-> +
<- s
-> +
time passes
-> T001:1234123412341234
<- +
<- g
-> +
-> 1455...
<- +

Using the gdbserver program

gdbserver is a control program for Unix-like systems, which allows you to connect your program with a remote GDB via target remote---but without linking in the usual debugging stub.

gdbserver is not a complete replacement for the debugging stubs, because it requires essentially the same operating-system facilities that GDB itself does. In fact, a system that can run gdbserver to connect to a remote GDB could also run GDB locally! gdbserver is sometimes useful nevertheless, because it is a much smaller program than GDB itself. It is also easier to port than all of GDB, so you may be able to get started more quickly on a new system by using gdbserver. Finally, if you develop code for real-time systems, you may find that the tradeoffs involved in real-time operation make it more convenient to do as much development work as possible on another system, for example by cross-compiling. You can use gdbserver to make a similar choice for debugging.

GDB and gdbserver communicate via either a serial line or a TCP connection, using the standard GDB remote serial protocol.

On the target machine,
you need to have a copy of the program you want to debug. gdbserver does not need your program's symbol table, so you can strip the program if necessary to save space. GDB on the host system does all the symbol handling. To use the server, you must tell it how to communicate with GDB; the name of your program; and the arguments for your program. The syntax is:
target> gdbserver comm program [ args ... ]
comm is either a device name (to use a serial line) or a TCP hostname and portnumber. For example, to debug Emacs with the argument `foo.txt' and communicate with GDB over the serial port `/dev/com1':
target> gdbserver /dev/com1 emacs foo.txt
gdbserver waits passively for the host GDB to communicate with it. To use a TCP connection instead of a serial line:
target> gdbserver host:2345 emacs foo.txt
The only difference from the previous example is the first argument, specifying that you are communicating with the host GDB via TCP. The `host:2345' argument means that gdbserver is to expect a TCP connection from machine `host' to local TCP port 2345. (Currently, the `host' part is ignored.) You can choose any number you want for the port number as long as it does not conflict with any TCP ports already in use on the target system (for example, 23 is reserved for telnet).(5) You must use the same port number with the host GDB target remote command.
On the GDB host machine,
you need an unstripped copy of your program, since GDB needs symbols and debugging information. Start up GDB as usual, using the name of the local copy of your program as the first argument. (You may also need the `--baud' option if the serial line is running at anything other than 9600bps.) After that, use target remote to establish communications with gdbserver. Its argument is either a device name (usually a serial device, like `/dev/ttyb'), or a TCP port descriptor in the form host:PORT. For example:
(gdb) target remote /dev/ttyb
communicates with the server via serial line `/dev/ttyb', and
(gdb) target remote the-target:2345
communicates via a TCP connection to port 2345 on host `the-target'. For TCP connections, you must start up gdbserver prior to using the target remote command. Otherwise you may get an error whose text depends on the host system, but which usually looks something like `Connection refused'.

Using the gdbserve.nlm program

gdbserve.nlm is a control program for NetWare systems, which allows you to connect your program with a remote GDB via target remote.

GDB and gdbserve.nlm communicate via a serial line, using the standard GDB remote serial protocol.

On the target machine,
you need to have a copy of the program you want to debug. gdbserve.nlm does not need your program's symbol table, so you can strip the program if necessary to save space. GDB on the host system does all the symbol handling. To use the server, you must tell it how to communicate with GDB; the name of your program; and the arguments for your program. The syntax is:
load gdbserve [ BOARD=board ] [ PORT=port ]
              [ BAUD=baud ] program [ args ... ]
board and port specify the serial line; baud specifies the baud rate used by the connection. port and node default to 0, baud defaults to 9600bps. For example, to debug Emacs with the argument `foo.txt'and communicate with GDB over serial port number 2 or board 1 using a 19200bps connection:
load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
On the GDB host machine,
you need an unstripped copy of your program, since GDB needs symbols and debugging information. Start up GDB as usual, using the name of the local copy of your program as the first argument. (You may also need the `--baud' option if the serial line is running at anything other than 9600bps. After that, use target remote to establish communications with gdbserve.nlm. Its argument is a device name (usually a serial device, like `/dev/ttyb'). For example:
(gdb) target remote /dev/ttyb
communications with the server via serial line `/dev/ttyb'.

Kernel Object Display

Some targets support kernel object display. Using this facility, GDB communicates specially with the underlying operating system and can display information about operating system-level objects such as mutexes and other synchronization objects. Exactly which objects can be displayed is determined on a per-OS basis.

Use the set os command to set the operating system. This tells GDB which kernel object display module to initialize:

(gdb) set os cisco

If set os succeeds, GDB will display some information about the operating system, and will create a new info command which can be used to query the target. The info command is named after the operating system:

(gdb) info cisco
List of Cisco Kernel Objects
Object     Description
any        Any and all objects

Further subcommands can be used to query about particular objects known by the kernel.

There is currently no way to determine whether a given operating system is supported other than to try it.

Configuration-Specific Information

While nearly all GDB commands are available for all native and cross versions of the debugger, there are some exceptions. This chapter describes things that are only available in certain configurations.

There are three major categories of configurations: native configurations, where the host and target are the same, embedded operating system configurations, which are usually the same for several different processor architectures, and bare embedded processors, which are quite different from each other.

  • Native
  • Embedded OS
  • Embedded Processors
  • Architectures

Native

This section describes details specific to particular native configurations.

  • HP-UX: HP-UX
  • SVR4 Process Information: SVR4 process information
  • DJGPP Native: Features specific to the DJGPP port

HP-UX

On HP-UX systems, if you refer to a function or variable name that begins with a dollar sign, GDB searches for a user or system name first, before it searches for a convenience variable.

SVR4 process information

Many versions of SVR4 provide a facility called `/proc' that can be used to examine the image of a running process using file-system subroutines. If GDB is configured for an operating system with this facility, the command info proc is available to report on several kinds of information about the process running your program. info proc works only on SVR4 systems that include the procfs code. This includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not HP-UX or Linux, for example.

info proc
Summarize available information about the process.
info proc mappings
Report on the address ranges accessible in the program, with information on whether your program may read, write, or execute each range.
info proc times
Starting time, user CPU time, and system CPU time for your program and its children.
info proc id
Report on the process IDs related to your program: its own process ID, the ID of its parent, the process group ID, and the session ID.
info proc status
General information on the state of the process. If the process is stopped, this report includes the reason for stopping, and any signal received.
info proc all
Show all the above information about the process.

Features for Debugging DJGPP Programs

DJGPP is the port of GNU development tools to MS-DOS and MS-Windows. DJGPP programs are 32-bit protected-mode programs that use the DPMI (DOS Protected-Mode Interface) API to run on top of real-mode DOS systems and their emulations.

GDB supports native debugging of DJGPP programs, and defines a few commands specific to the DJGPP port. This subsection describes those commands.

info dos
This is a prefix of DJGPP-specific commands which print information about the target system and important OS structures.
info dos sysinfo
This command displays assorted information about the underlying platform: the CPU type and features, the OS version and flavor, the DPMI version, and the available conventional and DPMI memory.
info dos gdt
info dos ldt
info dos idt
These 3 commands display entries from, respectively, Global, Local, and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor tables are data structures which store a descriptor for each segment that is currently in use. The segment's selector is an index into a descriptor table; the table entry for that index holds the descriptor's base address and limit, and its attributes and access rights. A typical DJGPP program uses 3 segments: a code segment, a data segment (used for both data and the stack), and a DOS segment (which allows access to DOS/BIOS data structures and absolute addresses in conventional memory). However, the DPMI host will usually define additional segments in order to support the DPMI environment. These commands allow to display entries from the descriptor tables. Without an argument, all entries from the specified table are displayed. An argument, which should be an integer expression, means display a single entry whose index is given by the argument. For example, here's a convenient way to display information about the debugged program's data segment:
(gdb) info dos ldt $ds
0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)
This comes in handy when you want to see whether a pointer is outside the data segment's limit (i.e. garbled).
info dos pde
info dos pte
These two commands display entries from, respectively, the Page Directory and the Page Tables. Page Directories and Page Tables are data structures which control how virtual memory addresses are mapped into physical addresses. A Page Table includes an entry for every page of memory that is mapped into the program's address space; there may be several Page Tables, each one holding up to 4096 entries. A Page Directory has up to 4096 entries, one each for every Page Table that is currently in use. Without an argument, info dos pde displays the entire Page Directory, and info dos pte displays all the entries in all of the Page Tables. An argument, an integer expression, given to the info dos pde command means display only that entry from the Page Directory table. An argument given to the info dos pte command means display entries from a single Page Table, the one pointed to by the specified entry in the Page Directory. These commands are useful when your program uses DMA (Direct Memory Access), which needs physical addresses to program the DMA controller. These commands are supported only with some DPMI servers.
info dos address-pte addr
This command displays the Page Table entry for a specified linear address. The argument linear address addr should already have the appropriate segment's base address added to it, because this command accepts addresses which may belong to any segment. For example, here's how to display the Page Table entry for the page where the variable i is stored:
(gdb) info dos address-pte __djgpp_base_address + (char *)&i
Page Table entry for address 0x11a00d30:
Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30
This says that i is stored at offset 0xd30 from the page whose physical base address is 0x02698000, and prints all the attributes of that page. Note that you must cast the addresses of variables to a char *, since otherwise the value of __djgpp_base_address, the base address of all variables and functions in a DJGPP program, will be added using the rules of C pointer arithmetics: if i is declared an int, GDB will add 4 times the value of __djgpp_base_address to the address of i. Here's another example, it displays the Page Table entry for the transfer buffer:
(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)
Page Table entry for address 0x29110:
Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110
(The + 3 offset is because the transfer buffer's address is the 3rd member of the _go32_info_block structure.) The output of this command clearly shows that addresses in conventional memory are mapped 1:1, i.e. the physical and linear addresses are identical. This command is supported only with some DPMI servers.

Embedded Operating Systems

This section describes configurations involving the debugging of embedded operating systems that are available for several different architectures.

  • VxWorks: Using GDB with VxWorks

GDB includes the ability to debug programs running on various real-time operating systems.

Using GDB with VxWorks

target vxworks machinename
A VxWorks system, attached via TCP/IP. The argument machinename is the target system's machine name or IP address.

On VxWorks, load links filename dynamically on the current target system as well as adding its symbols in GDB.

GDB enables developers to spawn and debug tasks running on networked VxWorks targets from a Unix host. Already-running tasks spawned from the VxWorks shell can also be debugged. GDB uses code that runs on both the Unix host and on the VxWorks target. The program gdb is installed and executed on the Unix host. (It may be installed with the name vxgdb, to distinguish it from a GDB for debugging programs on the host itself.)

VxWorks-timeout args
All VxWorks-based targets now support the option vxworks-timeout. This option is set by the user, and args represents the number of seconds GDB waits for responses to rpc's. You might use this if your VxWorks target is a slow software simulator or is on the far side of a thin network line.

The following information on connecting to VxWorks was current when this manual was produced; newer releases of VxWorks may use revised procedures.

To use GDB with VxWorks, you must rebuild your VxWorks kernel to include the remote debugging interface routines in the VxWorks library `rdb.a'. To do this, define INCLUDE_RDB in the VxWorks configuration file `configAll.h' and rebuild your VxWorks kernel. The resulting kernel contains `rdb.a', and spawns the source debugging task tRdbTask when VxWorks is booted. For more information on configuring and remaking VxWorks, see the manufacturer's manual.

Once you have included `rdb.a' in your VxWorks system image and set your Unix execution search path to find GDB, you are ready to run GDB. From your Unix host, run gdb (or vxgdb, depending on your installation).

GDB comes up showing the prompt:

(vxgdb)
  • VxWorks Connection: Connecting to VxWorks
  • VxWorks Download: VxWorks download
  • VxWorks Attach: Running tasks

Connecting to VxWorks

The GDB command target lets you connect to a VxWorks target on the network. To connect to a target whose host name is "tt", type:

(vxgdb) target vxworks tt

GDB displays messages like these:

Attaching remote machine across net...
Connected to tt.

GDB then attempts to read the symbol tables of any object modules loaded into the VxWorks target since it was last booted. GDB locates these files by searching the directories listed in the command search path (see section Your program's environment); if it fails to find an object file, it displays a message such as:

prog.o: No such file or directory.

When this happens, add the appropriate directory to the search path with the GDB command path, and execute the target command again.

VxWorks download

If you have connected to the VxWorks target and you want to debug an object that has not yet been loaded, you can use the GDB load command to download a file from Unix to VxWorks incrementally. The object file given as an argument to the load command is actually opened twice: first by the VxWorks target in order to download the code, then by GDB in order to read the symbol table. This can lead to problems if the current working directories on the two systems differ. If both systems have NFS mounted the same filesystems, you can avoid these problems by using absolute paths. Otherwise, it is simplest to set the working directory on both systems to the directory in which the object file resides, and then to reference the file by its name, without any path. For instance, a program `prog.o' may reside in `vxpath/vw/demo/rdb' in VxWorks and in `hostpath/vw/demo/rdb' on the host. To load this program, type this on VxWorks:

-> cd "vxpath/vw/demo/rdb"

Then, in GDB, type:

(vxgdb) cd hostpath/vw/demo/rdb
(vxgdb) load prog.o

GDB displays a response similar to this:

Reading symbol data from wherever/vw/demo/rdb/prog.o... done.

You can also use the load command to reload an object module after editing and recompiling the corresponding source file. Note that this makes GDB delete all currently-defined breakpoints, auto-displays, and convenience variables, and to clear the value history. (This is necessary in order to preserve the integrity of debugger's data structures that reference the target system's symbol table.)

Running tasks

You can also attach to an existing task using the attach command as follows:

(vxgdb) attach task

where task is the VxWorks hexadecimal task ID. The task can be running or suspended when you attach to it. Running tasks are suspended at the time of attachment.

Embedded Processors

This section goes into details specific to particular embedded configurations.

  • A29K Embedded: AMD A29K Embedded
  • ARM: ARM
  • H8/300: Hitachi H8/300
  • H8/500: Hitachi H8/500
  • i960: Intel i960
  • M32R/D: Mitsubishi M32R/D
  • M68K: Motorola M68K
  • M88K: Motorola M88K
  • MIPS Embedded: MIPS Embedded
  • PA: HP PA Embedded
  • PowerPC
  • SH: Hitachi SH
  • Sparclet: Tsqware Sparclet
  • Sparclite: Fujitsu Sparclite
  • ST2000: Tandem ST2000
  • Z8000: Zilog Z8000

AMD A29K Embedded

  • A29K UDI
  • A29K EB29K
  • Comms (EB29K): Communications setup
  • gdb-EB29K: EB29K cross-debugging
  • Remote Log: Remote log
target adapt dev
Adapt monitor for A29K.
target amd-eb dev speed PROG
Remote PC-resident AMD EB29K board, attached over serial lines. dev is the serial device, as for target remote; speed allows you to specify the linespeed; and PROG is the name of the program to be debugged, as it appears to DOS on the PC. See section EBMON protocol for AMD29K.

A29K UDI

GDB supports AMD's UDI ("Universal Debugger Interface") protocol for debugging the a29k processor family. To use this configuration with AMD targets running the MiniMON monitor, you need the program MONTIP, available from AMD at no charge. You can also use GDB with the UDI-conformant a29k simulator program ISSTIP, also available from AMD.

target udi keyword
Select the UDI interface to a remote a29k board or simulator, where keyword is an entry in the AMD configuration file `udi_soc'. This file contains keyword entries which specify parameters used to connect to a29k targets. If the `udi_soc' file is not in your working directory, you must set the environment variable `UDICONF' to its pathname.

EBMON protocol for AMD29K

AMD distributes a 29K development board meant to fit in a PC, together with a DOS-hosted monitor program called EBMON. As a shorthand term, this development system is called the "EB29K". To use GDB from a Unix system to run programs on the EB29K board, you must first connect a serial cable between the PC (which hosts the EB29K board) and a serial port on the Unix system. In the following, we assume you've hooked the cable between the PC's `COM1' port and `/dev/ttya' on the Unix system.

Communications setup

The next step is to set up the PC's port, by doing something like this in DOS on the PC:

C:\> MODE com1:9600,n,8,1,none

This example--run on an MS DOS 4.0 system--sets the PC port to 9600 bps, no parity, eight data bits, one stop bit, and no "retry" action; you must match the communications parameters when establishing the Unix end of the connection as well.

To give control of the PC to the Unix side of the serial line, type the following at the DOS console:

C:\> CTTY com1

(Later, if you wish to return control to the DOS console, you can use the command CTTY con---but you must send it over the device that had control, in our example over the `COM1' serial line.)

From the Unix host, use a communications program such as tip or cu to communicate with the PC; for example,

cu -s 9600 -l /dev/ttya

The cu options shown specify, respectively, the linespeed and the serial port to use. If you use tip instead, your command line may look something like the following:

tip -9600 /dev/ttya

Your system may require a different name where we show `/dev/ttya' as the argument to tip. The communications parameters, including which port to use, are associated with the tip argument in the "remote" descriptions file--normally the system table `/etc/remote'.

Using the tip or cu connection, change the DOS working directory to the directory containing a copy of your 29K program, then start the PC program EBMON (an EB29K control program supplied with your board by AMD). You should see an initial display from EBMON similar to the one that follows, ending with the EBMON prompt `#'---

C:\> G:

G:\> CD \usr\joe\work29k

G:\USR\JOE\WORK29K> EBMON
Am29000 PC Coprocessor Board Monitor, version 3.0-18
Copyright 1990 Advanced Micro Devices, Inc.
Written by Gibbons and Associates, Inc.

Enter '?' or 'H' for help

PC Coprocessor Type   = EB29K
I/O Base              = 0x208
Memory Base           = 0xd0000

Data Memory Size      = 2048KB
Available I-RAM Range = 0x8000 to 0x1fffff
Available D-RAM Range = 0x80002000 to 0x801fffff

PageSize              = 0x400
Register Stack Size   = 0x800
Memory Stack Size     = 0x1800

CPU PRL               = 0x3
Am29027 Available     = No
Byte Write Available  = Yes

# ~.

Then exit the cu or tip program (done in the example by typing ~. at the EBMON prompt). EBMON keeps running, ready for GDB to take over.

For this example, we've assumed what is probably the most convenient way to make sure the same 29K program is on both the PC and the Unix system: a PC/NFS connection that establishes "drive `G:'" on the PC as a file system on the Unix host. If you do not have PC/NFS or something similar connecting the two systems, you must arrange some other way--perhaps floppy-disk transfer--of getting the 29K program from the Unix system to the PC; GDB does not download it over the serial line.

EB29K cross-debugging

Finally, cd to the directory containing an image of your 29K program on the Unix system, and start GDB---specifying as argument the name of your 29K program:

cd /usr/joe/work29k
gdb myfoo

Now you can use the target command:

target amd-eb /dev/ttya 9600 MYFOO

In this example, we've assumed your program is in a file called `myfoo'. Note that the filename given as the last argument to target amd-eb should be the name of the program as it appears to DOS. In our example this is simply MYFOO, but in general it can include a DOS path, and depending on your transfer mechanism may not resemble the name on the Unix side.

At this point, you can set any breakpoints you wish; when you are ready to see your program run on the 29K board, use the GDB command run.

To stop debugging the remote program, use the GDB detach command.

To return control of the PC to its console, use tip or cu once again, after your GDB session has concluded, to attach to EBMON. You can then type the command q to shut down EBMON, returning control to the DOS command-line interpreter. Type CTTY con to return command input to the main DOS console, and type ~. to leave tip or cu.

Remote log

The target amd-eb command creates a file `eb.log' in the current working directory, to help debug problems with the connection. `eb.log' records all the output from EBMON, including echoes of the commands sent to it. Running `tail -f' on this file in another window often helps to understand trouble with EBMON, or unexpected events on the PC side of the connection.

ARM

target rdi dev
ARM Angel monitor, via RDI library interface to ADP protocol. You may use this target to communicate with both boards running the Angel monitor, or with the EmbeddedICE JTAG debug device.
target rdp dev
ARM Demon monitor.

Hitachi H8/300

target hms dev
A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. Use special commands device and speed to control the serial line and the communications speed used.
target e7000 dev
E7000 emulator for Hitachi H8 and SH.
target sh3 dev
target sh3e dev
Hitachi SH-3 and SH-3E target systems.

When you select remote debugging to a Hitachi SH, H8/300, or H8/500 board, the load command downloads your program to the Hitachi board and also opens it as the current executable target for GDB on your host (like the file command).

GDB needs to know these things to talk to your Hitachi SH, H8/300, or H8/500:

  1. that you want to use `target hms', the remote debugging interface for Hitachi microprocessors, or `target e7000', the in-circuit emulator for the Hitachi SH and the Hitachi 300H. (`target hms' is the default when GDB is configured specifically for the Hitachi SH, H8/300, or H8/500.)
  2. what serial device connects your host to your Hitachi board (the first serial device available on your host is the default).
  3. what speed to use over the serial device.
  • Hitachi Boards: Connecting to Hitachi boards.
  • Hitachi ICE: Using the E7000 In-Circuit Emulator.
  • Hitachi Special: Special GDB commands for Hitachi micros.

Connecting to Hitachi boards

Use the special GDB command `device port' if you need to explicitly set the serial device. The default port is the first available port on your host. This is only necessary on Unix hosts, where it is typically something like `/dev/ttya'.

GDB has another special command to set the communications speed: `speed bps'. This command also is only used from Unix hosts; on DOS hosts, set the line speed as usual from outside GDB with the DOS mode command (for instance, mode com2:9600,n,8,1,p for a 9600bps connection).

The `device' and `speed' commands are available only when you use a Unix host to debug your Hitachi microprocessor programs. If you use a DOS host, GDB depends on an auxiliary terminate-and-stay-resident program called asynctsr to communicate with the development board through a PC serial port. You must also use the DOS mode command to set up the serial port on the DOS side.

The following sample session illustrates the steps needed to start a program under GDB control on an H8/300. The example uses a sample H8/300 program called `t.x'. The procedure is the same for the Hitachi SH and the H8/500.

First hook up your development board. In this example, we use a board attached to serial port COM2; if you use a different serial port, substitute its name in the argument of the mode command. When you call asynctsr, the auxiliary comms program used by the debugger, you give it just the numeric part of the serial port's name; for example, `asyncstr 2' below runs asyncstr on COM2.

C:\H8300\TEST> asynctsr 2
C:\H8300\TEST> mode com2:9600,n,8,1,p

Resident portion of MODE loaded

COM2: 9600, n, 8, 1, p

Warning: We have noticed a bug in PC-NFS that conflicts with asynctsr. If you also run PC-NFS on your DOS host, you may need to disable it, or even boot without it, to use asynctsr to control your development board.

Now that serial communications are set up, and the development board is connected, you can start up GDB. Call gdb with the name of your program as the argument. GDB prompts you, as usual, with the prompt `(gdb)'. Use two special commands to begin your debugging session: `target hms' to specify cross-debugging to the Hitachi board, and the load command to download your program to the board. load displays the names of the program's sections, and a `*' for each 2K of data downloaded. (If you want to refresh GDB data on symbols or on the executable file without downloading, use the GDB commands file or symbol-file. These commands, and load itself, are described in section Commands to specify files.)

(eg-C:\H8300\TEST) gdb t.x
GDB is free software and you are welcome to distribute copies
 of it under certain conditions; type "show copying" to see
 the conditions.
There is absolutely no warranty for GDB; type "show warranty"
for details.
GDB 5.1.1, Copyright 1992 Free Software Foundation, Inc...
(gdb) target hms
Connected to remote H8/300 HMS system.
(gdb) load t.x
.text   : 0x8000 .. 0xabde ***********
.data   : 0xabde .. 0xad30 *
.stack  : 0xf000 .. 0xf014 *

At this point, you're ready to run or debug your program. From here on, you can use all the usual GDB commands. The break command sets breakpoints; the run command starts your program; print or x display data; the continue command resumes execution after stopping at a breakpoint. You can use the help command at any time to find out more about GDB commands.

Remember, however, that operating system facilities aren't available on your development board; for example, if your program hangs, you can't send an interrupt--but you can press the RESET switch!

Use the RESET button on the development board

  • to interrupt your program (don't use ctl-C on the DOS host--it has no way to pass an interrupt signal to the development board); and
  • to return to the GDB command prompt after your program finishes normally. The communications protocol provides no other way for GDB to detect program completion.

In either case, GDB sees the effect of a RESET on the development board as a "normal exit" of your program.

Using the E7000 in-circuit emulator

You can use the E7000 in-circuit emulator to develop code for either the Hitachi SH or the H8/300H. Use one of these forms of the `target e7000' command to connect GDB to your E7000:

target e7000 port speed
Use this form if your E7000 is connected to a serial port. The port argument identifies what serial port to use (for example, `com2'). The third argument is the line speed in bits per second (for example, `9600').
target e7000 hostname
If your E7000 is installed as a host on a TCP/IP network, you can just specify its hostname; GDB uses telnet to connect.

Special GDB commands for Hitachi micros

Some GDB commands are available only for the H8/300:

set machine h8300
set machine h8300h
Condition GDB for one of the two variants of the H8/300 architecture with `set machine'. You can use `show machine' to check which variant is currently in effect.

H8/500

set memory mod
show memory
Specify which H8/500 memory model (mod) you are using with `set memory'; check which memory model is in effect with `show memory'. The accepted values for mod are small, big, medium, and compact.

Intel i960

target mon960 dev
MON960 monitor for Intel i960.
target nindy devicename
An Intel 960 board controlled by a Nindy Monitor. devicename is the name of the serial device to use for the connection, e.g. `/dev/ttya'.

Nindy is a ROM Monitor program for Intel 960 target systems. When GDB is configured to control a remote Intel 960 using Nindy, you can tell GDB how to connect to the 960 in several ways:

  • Through command line options specifying serial port, version of the Nindy protocol, and communications speed;
  • By responding to a prompt on startup;
  • By using the target command at any point during your GDB session. See section Commands for managing targets.

With the Nindy interface to an Intel 960 board, load downloads filename to the 960 as well as adding its symbols in GDB.

  • Nindy Startup: Startup with Nindy
  • Nindy Options: Options for Nindy
  • Nindy Reset: Nindy reset command

Startup with Nindy

If you simply start gdb without using any command-line options, you are prompted for what serial port to use, before you reach the ordinary GDB prompt:

Attach /dev/ttyNN -- specify NN, or "quit" to quit:

Respond to the prompt with whatever suffix (after `/dev/tty') identifies the serial port you want to use. You can, if you choose, simply start up with no Nindy connection by responding to the prompt with an empty line. If you do this and later wish to attach to Nindy, use target (see section Commands for managing targets).

Options for Nindy

These are the startup options for beginning your GDB session with a Nindy-960 board attached:

-r port
Specify the serial port name of a serial interface to be used to connect to the target system. This option is only available when GDB is configured for the Intel 960 target architecture. You may specify port as any of: a full pathname (e.g. `-r /dev/ttya'), a device name in `/dev' (e.g. `-r ttya'), or simply the unique suffix for a specific tty (e.g. `-r a').
-O
(An uppercase letter "O", not a zero.) Specify that GDB should use the "old" Nindy monitor protocol to connect to the target system. This option is only available when GDB is configured for the Intel 960 target architecture.

Warning: if you specify `-O', but are actually trying to connect to a target system that expects the newer protocol, the connection fails, appearing to be a speed mismatch. GDB repeatedly attempts to reconnect at several different line speeds. You can abort this process with an interrupt.

-brk
Specify that GDB should first send a BREAK signal to the target system, in an attempt to reset it, before connecting to a Nindy target.

Warning: Many target systems do not have the hardware that this requires; it only works with a few boards.

The standard `-b' option controls the line speed used on the serial port.

Nindy reset command

reset
For a Nindy target, this command sends a "break" to the remote target system; this is only useful if the target has been equipped with a circuit to perform a hard reset (or some other interesting action) when a break is detected.

Mitsubishi M32R/D

target m32r dev
Mitsubishi M32R/D ROM monitor.

M68k

The Motorola m68k configuration includes ColdFire support, and target command for the following ROM monitors.

target abug dev
ABug ROM monitor for M68K.
target cpu32bug dev
CPU32BUG monitor, running on a CPU32 (M68K) board.
target dbug dev
dBUG ROM monitor for Motorola ColdFire.
target est dev
EST-300 ICE monitor, running on a CPU32 (M68K) board.
target rom68k dev
ROM 68K monitor, running on an M68K IDP board.

If GDB is configured with m68*-ericsson-*, it will instead have only a single special target command:

target es1800 dev
ES-1800 emulator for M68K.

[context?]

target rombug dev
ROMBUG ROM monitor for OS/9000.

M88K

target bug dev
BUG monitor, running on a MVME187 (m88k) board.

MIPS Embedded

GDB can use the MIPS remote debugging protocol to talk to a MIPS board attached to a serial line. This is available when you configure GDB with `--target=mips-idt-ecoff'.

Use these GDB commands to specify the connection to your target board:

target mips port
To run a program on the board, start up gdb with the name of your program as the argument. To connect to the board, use the command `target mips port', where port is the name of the serial port connected to the board. If the program has not already been downloaded to the board, you may use the load command to download it. You can then use all the usual GDB commands. For example, this sequence connects to the target board through a serial port, and loads and runs a program called prog through the debugger:
host$ gdb prog
GDB is free software and ...
(gdb) target mips /dev/ttyb
(gdb) load prog
(gdb) run
target mips hostname:portnumber
On some GDB host configurations, you can specify a TCP connection (for instance, to a serial line managed by a terminal concentrator) instead of a serial port, using the syntax `hostname:portnumber'.
target pmon port
PMON ROM monitor.
target ddb port
NEC's DDB variant of PMON for Vr4300.
target lsi port
LSI variant of PMON.
target r3900 dev
Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
target array dev
Array Tech LSI33K RAID controller board.

GDB also supports these special commands for MIPS targets:

set processor args
show processor
Use the set processor command to set the type of MIPS processor when you want to access processor-type-specific registers. For example, set processor r3041 tells GDB to use the CPU registers appropriate for the 3041 chip. Use the show processor command to see what MIPS processor GDB is using. Use the info reg command to see what registers GDB is using.
set mipsfpu double
set mipsfpu single
set mipsfpu none
show mipsfpu
If your target board does not support the MIPS floating point coprocessor, you should use the command `set mipsfpu none' (if you need this, you may wish to put the command in your GDB init file). This tells GDB how to find the return value of functions which return floating point values. It also allows GDB to avoid saving the floating point registers when calling functions on the board. If you are using a floating point coprocessor with only single precision floating point support, as on the R4650 processor, use the command `set mipsfpu single'. The default double precision floating point coprocessor may be selected using `set mipsfpu double'. In previous versions the only choices were double precision or no floating point, so `set mipsfpu on' will select double precision and `set mipsfpu off' will select no floating point. As usual, you can inquire about the mipsfpu variable with `show mipsfpu'.
set remotedebug n
show remotedebug
You can see some debugging information about communications with the board by setting the remotedebug variable. If you set it to 1 using `set remotedebug 1', every packet is displayed. If you set it to 2, every character is displayed. You can check the current value at any time with the command `show remotedebug'.
set timeout seconds
set retransmit-timeout seconds
show timeout
show retransmit-timeout
You can control the timeout used while waiting for a packet, in the MIPS remote protocol, with the set timeout seconds command. The default is 5 seconds. Similarly, you can control the timeout used while waiting for an acknowledgement of a packet with the set retransmit-timeout seconds command. The default is 3 seconds. You can inspect both values with show timeout and show retransmit-timeout. (These commands are only available when GDB is configured for `--target=mips-idt-ecoff'.) The timeout set by set timeout does not apply when GDB is waiting for your program to stop. In that case, GDB waits forever because it has no way of knowing how long the program is going to run before stopping.

PowerPC

target dink32 dev
DINK32 ROM monitor.
target ppcbug dev
target ppcbug1 dev
PPCBUG ROM monitor for PowerPC.
target sds dev
SDS monitor, running on a PowerPC board (such as Motorola's ADS).

HP PA Embedded

target op50n dev
OP50N monitor, running on an OKI HPPA board.
target w89k dev
W89K monitor, running on a Winbond HPPA board.

Hitachi SH

target hms dev
A Hitachi SH board attached via serial line to your host. Use special commands device and speed to control the serial line and the communications speed used.
target e7000 dev
E7000 emulator for Hitachi SH.
target sh3 dev
target sh3e dev
Hitachi SH-3 and SH-3E target systems.

Tsqware Sparclet

GDB enables developers to debug tasks running on Sparclet targets from a Unix host. GDB uses code that runs on both the Unix host and on the Sparclet target. The program gdb is installed and executed on the Unix host.

remotetimeout args
GDB supports the option remotetimeout. This option is set by the user, and args represents the number of seconds GDB waits for responses.

When compiling for debugging, include the options `-g' to get debug information and `-Ttext' to relocate the program to where you wish to load it on the target. You may also want to add the options `-n' or `-N' in order to reduce the size of the sections. Example:

sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N

You can use objdump to verify that the addresses are what you intended:

sparclet-aout-objdump --headers --syms prog

Once you have set your Unix execution search path to find GDB, you are ready to run GDB. From your Unix host, run gdb (or sparclet-aout-gdb, depending on your installation).

GDB comes up showing the prompt:

(gdbslet)
  • Sparclet File: Setting the file to debug
  • Sparclet Connection: Connecting to Sparclet
  • Sparclet Download: Sparclet download
  • Sparclet Execution: Running and debugging

Setting file to debug

The GDB command file lets you choose with program to debug.

(gdbslet) file prog

GDB then attempts to read the symbol table of `prog'. GDB locates the file by searching the directories listed in the command search path. If the file was compiled with debug information (option "-g"), source files will be searched as well. GDB locates the source files by searching the directories listed in the directory search path (see section Your program's environment). If it fails to find a file, it displays a message such as:

prog: No such file or directory.

When this happens, add the appropriate directories to the search paths with the GDB commands path and dir, and execute the target command again.

Connecting to Sparclet

The GDB command target lets you connect to a Sparclet target. To connect to a target on serial port "ttya", type:

(gdbslet) target sparclet /dev/ttya
Remote target sparclet connected to /dev/ttya
main () at ../prog.c:3

GDB displays messages like these:

Connected to ttya.

Sparclet download

Once connected to the Sparclet target, you can use the GDB load command to download the file from the host to the target. The file name and load offset should be given as arguments to the load command. Since the file format is aout, the program must be loaded to the starting address. You can use objdump to find out what this value is. The load offset is an offset which is added to the VMA (virtual memory address) of each of the file's sections. For instance, if the program `prog' was linked to text address 0x1201000, with data at 0x12010160 and bss at 0x12010170, in GDB, type:

(gdbslet) load prog 0x12010000
Loading section .text, size 0xdb0 vma 0x12010000

If the code is loaded at a different address then what the program was linked to, you may need to use the section and add-symbol-file commands to tell GDB where to map the symbol table.

Running and debugging

You can now begin debugging the task using GDB's execution control commands, b, step, run, etc. See the GDB manual for the list of commands.

(gdbslet) b main
Breakpoint 1 at 0x12010000: file prog.c, line 3.
(gdbslet) run
Starting program: prog
Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
3        char *symarg = 0;
(gdbslet) step
4        char *execarg = "hello!";
(gdbslet)

Fujitsu Sparclite

target sparclite dev
Fujitsu sparclite boards, used only for the purpose of loading. You must use an additional command to debug the program. For example: target remote dev using GDB standard remote protocol.

Tandem ST2000

GDB may be used with a Tandem ST2000 phone switch, running Tandem's STDBUG protocol.

To connect your ST2000 to the host system, see the manufacturer's manual. Once the ST2000 is physically attached, you can run:

target st2000 dev speed

to establish it as your debugging environment. dev is normally the name of a serial device, such as `/dev/ttya', connected to the ST2000 via a serial line. You can instead specify dev as a TCP connection (for example, to a serial line attached via a terminal concentrator) using the syntax hostname:portnumber.

The load and attach commands are not defined for this target; you must load your program into the ST2000 as you normally would for standalone operation. GDB reads debugging information (such as symbols) from a separate, debugging version of the program available on your host computer.

These auxiliary GDB commands are available to help you with the ST2000 environment:

st2000 command
Send a command to the STDBUG monitor. See the manufacturer's manual for available commands.
connect
Connect the controlling terminal to the STDBUG command monitor. When you are done interacting with STDBUG, typing either of two character sequences gets you back to the GDB command prompt: RET~. (Return, followed by tilde and period) or RET~C-d (Return, followed by tilde and control-D).

Zilog Z8000

When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 simulator.

For the Z8000 family, `target sim' simulates either the Z8002 (the unsegmented variant of the Z8000 architecture) or the Z8001 (the segmented variant). The simulator recognizes which architecture is appropriate by inspecting the object code.

target sim args
Debug programs on a simulated CPU. If the simulator supports setup options, specify them via args.

After specifying this target, you can debug programs for the simulated CPU in the same style as programs for your host computer; use the file command to load a new program image, the run command to run your program, and so on.

As well as making available all the usual machine registers (see section Registers), the Z8000 simulator provides three additional items of information as specially named registers:

cycles
Counts clock-ticks in the simulator.
insts
Counts instructions run in the simulator.
time
Execution time in 60ths of a second.

You can refer to these values in GDB expressions with the usual conventions; for example, `b fputc if $cycles>5000' sets a conditional breakpoint that suspends only after at least 5000 simulated clock ticks.

Architectures

This section describes characteristics of architectures that affect all uses of GDB with the architecture, both native and cross.

  • A29K
  • Alpha
  • MIPS

A29K

set rstack_high_address address
On AMD 29000 family processors, registers are saved in a separate register stack. There is no way for GDB to determine the extent of this stack. Normally, GDB just assumes that the stack is "large enough". This may result in GDB referencing memory locations that do not exist. If necessary, you can get around this problem by specifying the ending address of the register stack with the set rstack_high_address command. The argument should be an address, which you probably want to precede with `0x' to specify in hexadecimal.
show rstack_high_address
Display the current limit of the register stack, on AMD 29000 family processors.

Alpha

See the following section.

MIPS

Alpha- and MIPS-based computers use an unusual stack frame, which sometimes requires GDB to search backward in the object code to find the beginning of a function.

To improve response time (especially for embedded applications, where GDB may be restricted to a slow serial line for this search) you may want to limit the size of this search, using one of these commands:

set heuristic-fence-post limit
Restrict GDB to examining at most limit bytes in its search for the beginning of a function. A value of 0 (the default) means there is no limit. However, except for 0, the larger the limit the more bytes heuristic-fence-post must search and therefore the longer it takes to run.
show heuristic-fence-post
Display the current limit.

These commands are available only when GDB is configured for debugging programs on Alpha or MIPS processors.

Controlling GDB

You can alter the way GDB interacts with you by using the set command. For commands controlling how GDB displays data, see section Print settings. Other settings are described here.

  • Prompt: Prompt
  • Editing: Command editing
  • History: Command history
  • Screen Size: Screen size
  • Numbers: Numbers
  • Messages/Warnings: Optional warnings and messages
  • Debugging Output: Optional messages about internal happenings

Prompt

GDB indicates its readiness to read a command by printing a string called the prompt. This string is normally `(gdb)'. You can change the prompt string with the set prompt command. For instance, when debugging GDB with GDB, it is useful to change the prompt in one of the GDB sessions so that you can always tell which one you are talking to.

Note: set prompt does not add a space for you after the prompt you set. This allows you to set a prompt which ends in a space or a prompt that does not.

set prompt newprompt
Directs GDB to use newprompt as its prompt string henceforth.
show prompt
Prints a line of the form: `Gdb's prompt is: your-prompt'

Command editing

GDB reads its input commands via the readline interface. This GNU library provides consistent behavior for programs which provide a command line interface to the user. Advantages are GNU Emacs-style or vi-style inline editing of commands, csh-like history substitution, and a storage and recall of command history across debugging sessions.

You may control the behavior of command line editing in GDB with the command set.

set editing
set editing on
Enable command line editing (enabled by default).
set editing off
Disable command line editing.
show editing
Show whether command line editing is enabled.

Command history

GDB can keep track of the commands you type during your debugging sessions, so that you can be certain of precisely what happened. Use these commands to manage the GDB command history facility.

set history filename fname
Set the name of the GDB command history file to fname. This is the file where GDB reads an initial command history list, and where it writes the command history from this session when it exits. You can access this list through history expansion or through the history command editing characters listed below. This file defaults to the value of the environment variable GDBHISTFILE, or to `./.gdb_history' (`./_gdb_history' on MS-DOS) if this variable is not set.
set history save
set history save on
Record command history in a file, whose name may be specified with the set history filename command. By default, this option is disabled.
set history save off
Stop recording command history in a file.
set history size size
Set the number of commands which GDB keeps in its history list. This defaults to the value of the environment variable HISTSIZE, or to 256 if this variable is not set.

History expansion assigns special meaning to the character !.

Since ! is also the logical not operator in C, history expansion is off by default. If you decide to enable history expansion with the set history expansion on command, you may sometimes need to follow ! (when it is used as logical not, in an expression) with a space or a tab to prevent it from being expanded. The readline history facilities do not attempt substitution on the strings != and !(, even when history expansion is enabled.

The commands to control history expansion are:

set history expansion on
set history expansion
Enable history expansion. History expansion is off by default.
set history expansion off
Disable history expansion. The readline code comes with more complete documentation of editing and history expansion features. Users unfamiliar with GNU Emacs or vi may wish to read it.
show history
show history filename
show history save
show history size
show history expansion
These commands display the state of the GDB history parameters. show history by itself displays all four states.
show commands
Display the last ten commands in the command history.
show commands n
Print ten commands centered on command number n.
show commands +
Print ten commands just after the commands last printed.

Screen size

Certain commands to GDB may produce large amounts of information output to the screen. To help you read all of it, GDB pauses and asks you for input at the end of each page of output. Type RET when you want to continue the output, or q to discard the remaining output. Also, the screen width setting determines when to wrap lines of output. Depending on what is being printed, GDB tries to break the line at a readable place, rather than simply letting it overflow onto the following line.

Normally GDB knows the size of the screen from the terminal driver software. For example, on Unix GDB uses the termcap data base together with the value of the TERM environment variable and the stty rows and stty cols settings. If this is not correct, you can override it with the set height and set width commands:

set height lpp
show height
set width cpl
show width
These set commands specify a screen height of lpp lines and a screen width of cpl characters. The associated show commands display the current settings. If you specify a height of zero lines, GDB does not pause during output no matter how long the output is. This is useful if output is to a file or to an editor buffer. Likewise, you can specify `set width 0' to prevent GDB from wrapping its output.

Numbers

You can always enter numbers in octal, decimal, or hexadecimal in GDB by the usual conventions: octal numbers begin with `0', decimal numbers end with `.', and hexadecimal numbers begin with `0x'. Numbers that begin with none of these are, by default, entered in base 10; likewise, the default display for numbers--when no particular format is specified--is base 10. You can change the default base for both input and output with the set radix command.

set input-radix base
Set the default base for numeric input. Supported choices for base are decimal 8, 10, or 16. base must itself be specified either unambiguously or using the current default radix; for example, any of
set radix 012
set radix 10.
set radix 0xa
sets the base to decimal. On the other hand, `set radix 10' leaves the radix unchanged no matter what it was.
set output-radix base
Set the default base for numeric display. Supported choices for base are decimal 8, 10, or 16. base must itself be specified either unambiguously or using the current default radix.
show input-radix
Display the current default base for numeric input.
show output-radix
Display the current default base for numeric display.

Optional warnings and messages

By default, GDB is silent about its inner workings. If you are running on a slow machine, you may want to use the set verbose command. This makes GDB tell you when it does a lengthy internal operation, so you will not think it has crashed.

Currently, the messages controlled by set verbose are those which announce that the symbol table for a source file is being read; see symbol-file in section Commands to specify files.

set verbose on
Enables GDB output of certain informational messages.
set verbose off
Disables GDB output of certain informational messages.
show verbose
Displays whether set verbose is on or off.

By default, if GDB encounters bugs in the symbol table of an object file, it is silent; but if you are debugging a compiler, you may find this information useful (see section Errors reading symbol files).

set complaints limit
Permits GDB to output limit complaints about each type of unusual symbols before becoming silent about the problem. Set limit to zero to suppress all complaints; set it to a large number to prevent complaints from being suppressed.
show complaints
Displays how many symbol complaints GDB is permitted to produce.

By default, GDB is cautious, and asks what sometimes seems to be a lot of stupid questions to confirm certain commands. For example, if you try to run a program which is already running:

(gdb) run
The program being debugged has been started already.
Start it from the beginning? (y or n)

If you are willing to unflinchingly face the consequences of your own commands, you can disable this "feature":

set confirm off
Disables confirmation requests.
set confirm on
Enables confirmation requests (the default).
show confirm
Displays state of confirmation requests.

Optional messages about internal happenings

set debug arch
Turns on or off display of gdbarch debugging info. The default is off
show debug arch
Displays the current state of displaying gdbarch debugging info.
set debug event
Turns on or off display of GDB event debugging info. The default is off.
show debug event
Displays the current state of displaying GDB event debugging info.
set debug expression
Turns on or off display of GDB expression debugging info. The default is off.
show debug expression
Displays the current state of displaying GDB expression debugging info.
set debug overload
Turns on or off display of GDB C++ overload debugging info. This includes info such as ranking of functions, etc. The default is off.
show debug overload
Displays the current state of displaying GDB C++ overload debugging info.
set debug remote
Turns on or off display of reports on all packets sent back and forth across the serial line to the remote machine. The info is printed on the GDB standard output stream. The default is off.
show debug remote
Displays the state of display of remote packets.
set debug serial
Turns on or off display of GDB serial debugging info. The default is off.
show debug serial
Displays the current state of displaying GDB serial debugging info.
set debug target
Turns on or off display of GDB target debugging info. This info includes what is going on at the target level of GDB, as it happens. The default is off.
show debug target
Displays the current state of displaying GDB target debugging info.
set debug varobj
Turns on or off display of GDB variable object debugging info. The default is off.
show debug varobj
Displays the current state of displaying GDB variable object debugging info.

Canned Sequences of Commands

Aside from breakpoint commands (see section Breakpoint command lists), GDB provides two ways to store sequences of commands for execution as a unit: user-defined commands and command files.

  • Define: User-defined commands
  • Hooks: User-defined command hooks
  • Command Files: Command files
  • Output: Commands for controlled output

User-defined commands

A user-defined command is a sequence of GDB commands to which you assign a new name as a command. This is done with the define command. User commands may accept up to 10 arguments separated by whitespace. Arguments are accessed within the user command via $arg0...$arg9. A trivial example:

define adder
  print $arg0 + $arg1 + $arg2

To execute the command use:

adder 1 2 3

This defines the command adder, which prints the sum of its three arguments. Note the arguments are text substitutions, so they may reference variables, use complex expressions, or even perform inferior functions calls.

define commandname
Define a command named commandname. If there is already a command by that name, you are asked to confirm that you want to redefine it. The definition of the command is made up of other GDB command lines, which are given following the define command. The end of these commands is marked by a line containing end.
if
Takes a single argument, which is an expression to evaluate. It is followed by a series of commands that are executed only if the expression is true (nonzero). There can then optionally be a line else, followed by a series of commands that are only executed if the expression was false. The end of the list is marked by a line containing end.
while
The syntax is similar to if: the command takes a single argument, which is an expression to evaluate, and must be followed by the commands to execute, one per line, terminated by an end. The commands are executed repeatedly as long as the expression evaluates to true.
document commandname
Document the user-defined command commandname, so that it can be accessed by help. The command commandname must already be defined. This command reads lines of documentation just as define reads the lines of the command definition, ending with end. After the document command is finished, help on command commandname displays the documentation you have written. You may use the document command again to change the documentation of a command. Redefining the command with define does not change the documentation.
help user-defined
List all user-defined commands, with the first line of the documentation (if any) for each.
show user
show user commandname
Display the GDB commands used to define commandname (but not its documentation). If no commandname is given, display the definitions for all user-defined commands.

When user-defined commands are executed, the commands of the definition are not printed. An error in any command stops execution of the user-defined command.

If used interactively, commands that would ask for confirmation proceed without asking when used inside a user-defined command. Many GDB commands that normally print messages to say what they are doing omit the messages when used in a user-defined command.

User-defined command hooks

You may define hooks, which are a special kind of user-defined command. Whenever you run the command `foo', if the user-defined command `hook-foo' exists, it is executed (with no arguments) before that command.

A hook may also be defined which is run after the command you executed. Whenever you run the command `foo', if the user-defined command `hookpost-foo' exists, it is executed (with no arguments) after that command. Post-execution hooks may exist simultaneously with pre-execution hooks, for the same command.

It is valid for a hook to call the command which it hooks. If this occurs, the hook is not re-executed, thereby avoiding infinte recursion.

In addition, a pseudo-command, `stop' exists. Defining (`hook-stop') makes the associated commands execute every time execution stops in your program: before breakpoint commands are run, displays are printed, or the stack frame is printed.

For example, to ignore SIGALRM signals while single-stepping, but treat them normally during normal execution, you could define:

define hook-stop
handle SIGALRM nopass
end

define hook-run
handle SIGALRM pass
end

define hook-continue
handle SIGLARM pass
end

As a further example, to hook at the begining and end of the echo command, and to add extra text to the beginning and end of the message, you could define:

define hook-echo
echo <<<---
end

define hookpost-echo
echo --->>>\n
end

(gdb) echo Hello World
<<<---Hello World--->>>
(gdb)

You can define a hook for any single-word command in GDB, but not for command aliases; you should define a hook for the basic command name, e.g. backtrace rather than bt. If an error occurs during the execution of your hook, execution of GDB commands stops and GDB issues a prompt (before the command that you actually typed had a chance to run).

If you try to define a hook which does not match any known command, you get a warning from the define command.

Command files

A command file for GDB is a file of lines that are GDB commands. Comments (lines starting with #) may also be included. An empty line in a command file does nothing; it does not mean to repeat the last command, as it would from the terminal.

When you start GDB, it automatically executes commands from its init files. These are files named `.gdbinit' on Unix and `gdb.ini' on DOS/Windows. During startup, GDB does the following:

  1. Reads the init file (if any) in your home directory(6).
  2. Processes command line options and operands.
  3. Reads the init file (if any) in the current working directory.
  4. Reads command files specified by the `-x' option.

The init file in your home directory can set options (such as `set complaints') that affect subsequent processing of command line options and operands. Init files are not executed if you use the `-nx' option (see section Choosing modes).

On some configurations of GDB, the init file is known by a different name (these are typically environments where a specialized form of GDB may need to coexist with other forms, hence a different name for the specialized version's init file). These are the environments with special init file names:

  • VxWorks (Wind River Systems real-time OS): `.vxgdbinit'
  • OS68K (Enea Data Systems real-time OS): `.os68gdbinit'
  • ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit'

You can also request the execution of a command file with the source command:

source filename
Execute the command file filename.

The lines in a command file are executed sequentially. They are not printed as they are executed. An error in any command terminates execution of the command file.

Commands that would ask for confirmation if used interactively proceed without asking when used in a command file. Many GDB commands that normally print messages to say what they are doing omit the messages when called from command files.

Commands for controlled output

During the execution of a command file or a user-defined command, normal GDB output is suppressed; the only output that appears is what is explicitly printed by the commands in the definition. This section describes three commands useful for generating exactly the output you want.

echo text
Print text. Nonprinting characters can be included in text using C escape sequences, such as `\n' to print a newline. No newline is printed unless you specify one. In addition to the standard C escape sequences, a backslash followed by a space stands for a space. This is useful for displaying a string with spaces at the beginning or the end, since leading and trailing spaces are otherwise trimmed from all arguments. To print ` and foo = ', use the command `echo \ and foo = \ '. A backslash at the end of text can be used, as in C, to continue the command onto subsequent lines. For example,
echo This is some text\n\
which is continued\n\
onto several lines.\n
produces the same output as
echo This is some text\n
echo which is continued\n
echo onto several lines.\n
output expression
Print the value of expression and nothing but that value: no newlines, no `$nn = '. The value is not entered in the value history either. See section Expressions, for more information on expressions.
output/fmt expression
Print the value of expression in format fmt. You can use the same formats as for print. See section Output formats, for more information.
printf string, expressions...
Print the values of the expressions under the control of string. The expressions are separated by commas and may be either numbers or pointers. Their values are printed as specified by string, exactly as if your program were to execute the C subroutine
printf (string, expressions...);
For example, you can print two values in hex like this:
printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
The only backslash-escape sequences that you can use in the format string are the simple ones that consist of backslash followed by a letter.

GDB Text User Interface

  • TUI Overview: TUI overview
  • TUI Keys: TUI key bindings
  • TUI Commands: TUI specific commands
  • TUI Configuration: TUI configuration variables

The GDB Text User Interface, TUI in short, is a terminal interface which uses the curses library to show the source file, the assembly output, the program registers and GDB commands in separate text windows. The TUI is available only when GDB is configured with the --enable-tui configure option (see section configure options).

TUI overview

The TUI has two display modes that can be switched while GDB runs:

  • A curses (or TUI) mode in which it displays several text windows on the terminal.
  • A standard mode which corresponds to the GDB configured without the TUI.

In the TUI mode, GDB can display several text window on the terminal:

command
This window is the GDB command window with the GDB prompt and the GDB outputs. The GDB input is still managed using readline but through the TUI. The command window is always visible.
source
The source window shows the source file of the program. The current line as well as active breakpoints are displayed in this window. The current program position is shown with the `>' marker and active breakpoints are shown with `*' markers.
assembly
The assembly window shows the disassembly output of the program.
register
This window shows the processor registers. It detects when a register is changed and when this is the case, registers that have changed are highlighted.

The source, assembly and register windows are attached to the thread and the frame position. They are updated when the current thread changes, when the frame changes or when the program counter changes. These three windows are arranged by the TUI according to several layouts. The layout defines which of these three windows are visible. The following layouts are available:

  • source
  • assembly
  • source and assembly
  • source and registers
  • assembly and registers

TUI Key Bindings

The TUI installs several key bindings in the readline keymaps (see section Command Line Editing). They allow to leave or enter in the TUI mode or they operate directly on the TUI layout and windows. The following key bindings are installed for both TUI mode and the GDB standard mode.

C-x C-a
C-x a
C-x A
Enter or leave the TUI mode. When the TUI mode is left, the curses window management is left and GDB operates using its standard mode writing on the terminal directly. When the TUI mode is entered, the control is given back to the curses windows. The screen is then refreshed.
C-x 1
Use a TUI layout with only one window. The layout will either be `source' or `assembly'. When the TUI mode is not active, it will switch to the TUI mode. Think of this key binding as the Emacs C-x 1 binding.
C-x 2
Use a TUI layout with at least two windows. When the current layout shows already two windows, a next layout with two windows is used. When a new layout is chosen, one window will always be common to the previous layout and the new one. Think of it as the Emacs C-x 2 binding.

The following key bindings are handled only by the TUI mode:

PgUp
Scroll the active window one page up.
PgDn
Scroll the active window one page down.
Up
Scroll the active window one line up.
Down
Scroll the active window one line down.
Left
Scroll the active window one column left.
Right
Scroll the active window one column right.
C-L
Refresh the screen.

In the TUI mode, the arrow keys are used by the active window for scrolling. This means they are not available for readline. It is necessary to use other readline key bindings such as C-p, C-n, C-b and C-f.

TUI specific commands

The TUI has specific commands to control the text windows. These commands are always available, that is they do not depend on the current terminal mode in which GDB runs. When GDB is in the standard mode, using these commands will automatically switch in the TUI mode.

layout next
Display the next layout.
layout prev
Display the previous layout.
layout src
Display the source window only.
layout asm
Display the assembly window only.
layout split
Display the source and assembly window.
layout regs
Display the register window together with the source or assembly window.
focus next | prev | src | asm | regs | split
Set the focus to the named window. This command allows to change the active window so that scrolling keys can be affected to another window.
refresh
Refresh the screen. This is similar to using C-L key.
update
Update the source window and the current execution point.
winheight name +count
winheight name -count
Change the height of the window name by count lines. Positive counts increase the height, while negative counts decrease it.

TUI configuration variables

The TUI has several configuration variables that control the appearance of windows on the terminal.

set tui border-kind kind
Select the border appearance for the source, assembly and register windows. The possible values are the following:
space
Use a space character to draw the border.
ascii
Use ascii characters + - and | to draw the border.
acs
Use the Alternate Character Set to draw the border. The border is drawn using character line graphics if the terminal supports them.
set tui active-border-mode mode
Select the attributes to display the border of the active window. The possible values are normal, standout, reverse, half, half-standout, bold and bold-standout.
set tui border-mode mode
Select the attributes to display the border of other windows. The mode can be one of the following:
normal
Use normal attributes to display the border.
standout
Use standout mode.
reverse
Use reverse video mode.
half
Use half bright mode.
half-standout
Use half bright and standout mode.
bold
Use extra bright or bold mode.
bold-standout
Use extra bright or bold and standout mode.

Using GDB under GNU Emacs

A special interface allows you to use GNU Emacs to view (and edit) the source files for the program you are debugging with GDB.

To use this interface, use the command M-x gdb in Emacs. Give the executable file you want to debug as an argument. This command starts GDB as a subprocess of Emacs, with input and output through a newly created Emacs buffer.

Using GDB under Emacs is just like using GDB normally except for two things:

  • All "terminal" input and output goes through the Emacs buffer.

This applies both to GDB commands and their output, and to the input and output done by the program you are debugging.

This is useful because it means that you can copy the text of previous commands and input them again; you can even use parts of the output in this way.

All the facilities of Emacs' Shell mode are available for interacting with your program. In particular, you can send signals the usual way--for example, C-c C-c for an interrupt, C-c C-z for a stop.

  • GDB displays source code through Emacs.

Each time GDB displays a stack frame, Emacs automatically finds the source file for that frame and puts an arrow (`=>') at the left margin of the current line. Emacs uses a separate buffer for source display, and splits the screen to show both your GDB session and the source.

Explicit GDB list or search commands still produce output as usual, but you probably have no reason to use them from Emacs.

Warning: If the directory where your program resides is not your current directory, it can be easy to confuse Emacs about the location of the source files, in which case the auxiliary display buffer does not appear to show your source. GDB can find programs by searching your environment's PATH variable, so the GDB input and output session proceeds normally; but Emacs does not get enough information back from GDB to locate the source files in this situation. To avoid this problem, either start GDB mode from the directory where your program resides, or specify an absolute file name when prompted for the M-x gdb argument.

A similar confusion can result if you use the GDB file command to switch to debugging a program in some other location, from an existing GDB buffer in Emacs.

By default, M-x gdb calls the program called `gdb'. If you need to call GDB by a different name (for example, if you keep several configurations around, with different names) you can set the Emacs variable gdb-command-name; for example,

(setq gdb-command-name "mygdb")

(preceded by M-: or ESC :, or typed in the *scratch* buffer, or in your `.emacs' file) makes Emacs call the program named "mygdb" instead.

In the GDB I/O buffer, you can use these special Emacs commands in addition to the standard Shell mode commands:

C-h m
Describe the features of Emacs' GDB Mode.
M-s
Execute to another source line, like the GDB step command; also update the display window to show the current file and location.
M-n
Execute to next source line in this function, skipping all function calls, like the GDB next command. Then update the display window to show the current file and location.
M-i
Execute one instruction, like the GDB stepi command; update display window accordingly.
M-x gdb-nexti
Execute to next instruction, using the GDB nexti command; update display window accordingly.
C-c C-f
Execute until exit from the selected stack frame, like the GDB finish command.
M-c
Continue execution of your program, like the GDB continue command. Warning: In Emacs v19, this command is C-c C-p.
M-u
Go up the number of frames indicated by the numeric argument (see section `Numeric Arguments' in The GNU Emacs Manual), like the GDB up command. Warning: In Emacs v19, this command is C-c C-u.
M-d
Go down the number of frames indicated by the numeric argument, like the GDB down command. Warning: In Emacs v19, this command is C-c C-d.
C-x &
Read the number where the cursor is positioned, and insert it at the end of the GDB I/O buffer. For example, if you wish to disassemble code around an address that was displayed earlier, type disassemble; then move the cursor to the address display, and pick up the argument for disassemble by typing C-x &. You can customize this further by defining elements of the list gdb-print-command; once it is defined, you can format or otherwise process numbers picked up by C-x & before they are inserted. A numeric argument to C-x & indicates that you wish special formatting, and also acts as an index to pick an element of the list. If the list element is a string, the number to be inserted is formatted using the Emacs function format; otherwise the number is passed as an argument to the corresponding list element.

In any source file, the Emacs command C-x SPC (gdb-break) tells GDB to set a breakpoint on the source line point is on.

If you accidentally delete the source-display buffer, an easy way to get it back is to type the command f in the GDB buffer, to request a frame display; when you run under Emacs, this recreates the source buffer if necessary to show you the context of the current frame.

The source files displayed in Emacs are in ordinary Emacs buffers which are visiting the source files in the usual way. You can edit the files with these buffers if you wish; but keep in mind that GDB communicates with Emacs in terms of line numbers. If you add or delete lines from the text, the line numbers that GDB knows cease to correspond properly with the code.

GDB Annotations

This chapter describes annotations in GDB. Annotations are designed to interface GDB to graphical user interfaces or other similar programs which want to interact with GDB at a relatively high level.

  • Annotations Overview: What annotations are; the general syntax.
  • Server Prefix: Issuing a command without affecting user state.
  • Value Annotations: Values are marked as such.
  • Frame Annotations: Stack frames are annotated.
  • Displays: GDB can be told to display something periodically.
  • Prompting: Annotations marking GDB's need for input.
  • Errors: Annotations for error messages.
  • Breakpoint Info: Information on breakpoints.
  • Invalidation: Some annotations describe things now invalid.
  • Annotations for Running Whether the program is running, how it stopped, etc.
  • Source Annotations: Annotations describing source code.
  • TODO: Annotations which might be added in the future.

What is an Annotation?

To produce annotations, start GDB with the --annotate=2 option.

Annotations start with a newline character, two `control-z' characters, and the name of the annotation. If there is no additional information associated with this annotation, the name of the annotation is followed immediately by a newline. If there is additional information, the name of the annotation is followed by a space, the additional information, and a newline. The additional information cannot contain newline characters.

Any output not beginning with a newline and two `control-z' characters denotes literal output from GDB. Currently there is no need for GDB to output a newline followed by two `control-z' characters, but if there was such a need, the annotations could be extended with an `escape' annotation which means those three characters as output.

A simple example of starting up GDB with annotations is:

$ gdb --annotate=2
GNU GDB 5.0
Copyright 2000 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License,
and you are welcome to change it and/or distribute copies of it
under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty"
for details.
This GDB was configured as "sparc-sun-sunos4.1.3"

^Z^Zpre-prompt
(gdb)
^Z^Zprompt
quit

^Z^Zpost-prompt
$

Here `quit' is input to GDB; the rest is output from GDB. The three lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are annotations; the rest is output from GDB.

The Server Prefix

To issue a command to GDB without affecting certain aspects of the state which is seen by users, prefix it with `server '. This means that this command will not affect the command history, nor will it affect GDB's notion of which command to repeat if RET is pressed on a line by itself.

The server prefix does not affect the recording of values into the value history; to print a value without recording it into the value history, use the output command instead of the print command.

Values

When a value is printed in various contexts, GDB uses annotations to delimit the value from the surrounding text.

If a value is printed using print and added to the value history, the annotation looks like

^Z^Zvalue-history-begin history-number value-flags
history-string
^Z^Zvalue-history-value
the-value
^Z^Zvalue-history-end

where history-number is the number it is getting in the value history, history-string is a string, such as `$5 = ', which introduces the value to the user, the-value is the output corresponding to the value itself, and value-flags is `*' for a value which can be dereferenced and `-' for a value which cannot.

If the value is not added to the value history (it is an invalid float or it is printed with the output command), the annotation is similar:

^Z^Zvalue-begin value-flags
the-value
^Z^Zvalue-end

When GDB prints an argument to a function (for example, in the output from the backtrace command), it annotates it as follows:

^Z^Zarg-begin
argument-name
^Z^Zarg-name-end
separator-string
^Z^Zarg-value value-flags
the-value
^Z^Zarg-end

where argument-name is the name of the argument, separator-string is text which separates the name from the value for the user's benefit (such as `='), and value-flags and the-value have the same meanings as in a value-history-begin annotation.

When printing a structure, GDB annotates it as follows:

^Z^Zfield-begin value-flags
field-name
^Z^Zfield-name-end
separator-string
^Z^Zfield-value
the-value
^Z^Zfield-end

where field-name is the name of the field, separator-string is text which separates the name from the value for the user's benefit (such as `='), and value-flags and the-value have the same meanings as in a value-history-begin annotation.

When printing an array, GDB annotates it as follows:

^Z^Zarray-section-begin array-index value-flags

where array-index is the index of the first element being annotated and value-flags has the same meaning as in a value-history-begin annotation. This is followed by any number of elements, where is element can be either a single element:

`,' whitespace         ; omitted for the first element
the-value
^Z^Zelt

or a repeated element

`,' whitespace         ; omitted for the first element
the-value
^Z^Zelt-rep number-of-repititions
repetition-string
^Z^Zelt-rep-end

In both cases, the-value is the output for the value of the element and whitespace can contain spaces, tabs, and newlines. In the repeated case, number-of-repititons is the number of consecutive array elements which contain that value, and repetition-string is a string which is designed to convey to the user that repitition is being depicted.

Once all the array elements have been output, the array annotation is ended with

^Z^Zarray-section-end

Frames

Whenever GDB prints a frame, it annotates it. For example, this applies to frames printed when GDB stops, output from commands such as backtrace or up, etc.

The frame annotation begins with

^Z^Zframe-begin level address
level-string

where level is the number of the frame (0 is the innermost frame, and other frames have positive numbers), address is the address of the code executing in that frame, and level-string is a string designed to convey the level to the user. address is in the form `0x' followed by one or more lowercase hex digits (note that this does not depend on the language). The frame ends with

^Z^Zframe-end

Between these annotations is the main body of the frame, which can consist of

  • ^Z^Zfunction-call
function-call-string
    where function-call-string is text designed to convey to the user that this frame is associated with a function call made by GDB to a function in the program being debugged.
  • ^Z^Zsignal-handler-caller
signal-handler-caller-string
    where signal-handler-caller-string is text designed to convey to the user that this frame is associated with whatever mechanism is used by this operating system to call a signal handler (it is the frame which calls the signal handler, not the frame for the signal handler itself).
  • A normal frame. This can optionally (depending on whether this is thought of as interesting information for the user to see) begin with
    ^Z^Zframe-address
address
^Z^Zframe-address-end
separator-string
    where address is the address executing in the frame (the same address as in the frame-begin annotation, but printed in a form which is intended for user consumption--in particular, the syntax varies depending on the language), and separator-string is a string intended to separate this address from what follows for the user's benefit. Then comes
    ^Z^Zframe-function-name
function-name
^Z^Zframe-args
arguments
    where function-name is the name of the function executing in the frame, or `??' if not known, and arguments are the arguments to the frame, with parentheses around them (each argument is annotated individually as well, see section Values). If source information is available, a reference to it is then printed:
    ^Z^Zframe-source-begin
source-intro-string
^Z^Zframe-source-file
filename
^Z^Zframe-source-file-end
:
^Z^Zframe-source-line
line-number
^Z^Zframe-source-end
    where source-intro-string separates for the user's benefit the reference from the text which precedes it, filename is the name of the source file, and line-number is the line number within that file (the first line is line 1). If GDB prints some information about where the frame is from (which library, which load segment, etc.; currently only done on the RS/6000), it is annotated with
    ^Z^Zframe-where
information
    Then, if source is to actually be displayed for this frame (for example, this is not true for output from the backtrace command), then a source annotation (see section Displaying Source) is displayed. Unlike most annotations, this is output instead of the normal text which would be output, not in addition.

Displays

When GDB is told to display something using the display command, the results of the display are annotated:

^Z^Zdisplay-begin
number
^Z^Zdisplay-number-end
number-separator
^Z^Zdisplay-format
format
^Z^Zdisplay-expression
expression
^Z^Zdisplay-expression-end
expression-separator
^Z^Zdisplay-value
value
^Z^Zdisplay-end

where number is the number of the display, number-separator is intended to separate the number from what follows for the user, format includes information such as the size, format, or other information about how the value is being displayed, expression is the expression being displayed, expression-separator is intended to separate the expression from the text that follows for the user, and value is the actual value being displayed.

Annotation for GDB Input

When GDB prompts for input, it annotates this fact so it is possible to know when to send output, when the output from a given command is over, etc.

Different kinds of input each have a different input type. Each input type has three annotations: a pre- annotation, which denotes the beginning of any prompt which is being output, a plain annotation, which denotes the end of the prompt, and then a post- annotation which denotes the end of any echo which may (or may not) be associated with the input. For example, the prompt input type features the following annotations:

^Z^Zpre-prompt
^Z^Zprompt
^Z^Zpost-prompt

The input types are

prompt
When GDB is prompting for a command (the main GDB prompt).
commands
When GDB prompts for a set of commands, like in the commands command. The annotations are repeated for each command which is input.
overload-choice
When GDB wants the user to select between various overloaded functions.
query
When GDB wants the user to confirm a potentially dangerous operation.
prompt-for-continue
When GDB is asking the user to press return to continue. Note: Don't expect this to work well; instead use set height 0 to disable prompting. This is because the counting of lines is buggy in the presence of annotations.

Errors

^Z^Zquit

This annotation occurs right before GDB responds to an interrupt.

^Z^Zerror

This annotation occurs right before GDB responds to an error.

Quit and error annotations indicate that any annotations which GDB was in the middle of may end abruptly. For example, if a value-history-begin annotation is followed by a error, one cannot expect to receive the matching value-history-end. One cannot expect not to receive it either, however; an error annotation does not necessarily mean that GDB is immediately returning all the way to the top level.

A quit or error annotation may be preceded by

^Z^Zerror-begin

Any output between that and the quit or error annotation is the error message.

Warning messages are not yet annotated.

Information on Breakpoints

The output from the info breakpoints command is annotated as follows:

^Z^Zbreakpoints-headers
header-entry
^Z^Zbreakpoints-table

where header-entry has the same syntax as an entry (see below) but instead of containing data, it contains strings which are intended to convey the meaning of each field to the user. This is followed by any number of entries. If a field does not apply for this entry, it is omitted. Fields may contain trailing whitespace. Each entry consists of:

^Z^Zrecord
^Z^Zfield 0
number
^Z^Zfield 1
type
^Z^Zfield 2
disposition
^Z^Zfield 3
enable
^Z^Zfield 4
address
^Z^Zfield 5
what
^Z^Zfield 6
frame
^Z^Zfield 7
condition
^Z^Zfield 8
ignore-count
^Z^Zfield 9
commands

Note that address is intended for user consumption--the syntax varies depending on the language.

The output ends with

^Z^Zbreakpoints-table-end

Invalidation Notices

The following annotations say that certain pieces of state may have changed.

^Z^Zframes-invalid
The frames (for example, output from the backtrace command) may have changed.
^Z^Zbreakpoints-invalid
The breakpoints may have changed. For example, the user just added or deleted a breakpoint.

Running the Program

When the program starts executing due to a GDB command such as step or continue,

^Z^Zstarting

is output. When the program stops,

^Z^Zstopped

is output. Before the stopped annotation, a variety of annotations describe how the program stopped.

^Z^Zexited exit-status
The program exited, and exit-status is the exit status (zero for successful exit, otherwise nonzero).
^Z^Zsignalled
The program exited with a signal. After the ^Z^Zsignalled, the annotation continues:
intro-text
^Z^Zsignal-name
name
^Z^Zsignal-name-end
middle-text
^Z^Zsignal-string
string
^Z^Zsignal-string-end
end-text
where name is the name of the signal, such as SIGILL or SIGSEGV, and string is the explanation of the signal, such as Illegal Instruction or Segmentation fault. intro-text, middle-text, and end-text are for the user's benefit and have no particular format.
^Z^Zsignal
The syntax of this annotation is just like signalled, but GDB is just saying that the program received the signal, not that it was terminated with it.
^Z^Zbreakpoint number
The program hit breakpoint number number.
^Z^Zwatchpoint number
The program hit watchpoint number number.

Displaying Source

The following annotation is used instead of displaying source code:

^Z^Zsource filename:line:character:middle:addr

where filename is an absolute file name indicating which source file, line is the line number within that file (where 1 is the first line in the file), character is the character position within the file (where 0 is the first character in the file) (for most debug formats this will necessarily point to the beginning of a line), middle is `middle' if addr is in the middle of the line, or `beg' if addr is at the beginning of the line, and addr is the address in the target program associated with the source which is being displayed. addr is in the form `0x' followed by one or more lowercase hex digits (note that this does not depend on the language).

Annotations We Might Want in the Future

    - target-invalid
      the target might have changed (registers, heap contents, or
      execution status).  For performance, we might eventually want
      to hit `registers-invalid' and `all-registers-invalid' with
      greater precision

    - systematic annotation for set/show parameters (including
      invalidation notices).

    - similarly, `info' returns a list of candidates for invalidation
      notices.

The GDB/MI Interface

Function and Purpose

GDB/MI is a line based machine oriented text interface to GDB. It is specifically intended to support the development of systems which use the debugger as just one small component of a larger system.

This chapter is a specification of the GDB/MI interface. It is written in the form of a reference manual.

Note that GDB/MI is still under construction, so some of the features described below are incomplete and subject to change.

Notation and Terminology

This chapter uses the following notation:

  • | separates two alternatives.
  • [ something ] indicates that something is optional: it may or may not be given.
  • ( group )* means that group inside the parentheses may repeat zero or more times.
  • ( group )+ means that group inside the parentheses may repeat one or more times.
  • "string" means a literal string.

Acknowledgments

In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and Elena Zannoni.

  • GDB/MI Command Syntax
  • GDB/MI Compatibility with CLI
  • GDB/MI Output Records
  • GDB/MI Command Description Format
  • GDB/MI Breakpoint Table Commands
  • GDB/MI Data Manipulation
  • GDB/MI Program Control
  • GDB/MI Miscellaneous Commands
  • GDB/MI Stack Manipulation
  • GDB/MI Symbol Query
  • GDB/MI Target Manipulation
  • GDB/MI Thread Commands
  • GDB/MI Tracepoint Commands
  • GDB/MI Variable Objects

GDB/MI Command Syntax

  • GDB/MI Input Syntax
  • GDB/MI Output Syntax
  • GDB/MI Simple Examples

GDB/MI Input Syntax

command ==>
cli-command | mi-command
cli-command ==>
[ token ] cli-command nl, where cli-command is any existing GDB CLI command.
mi-command ==>
[ token ] "-" operation ( " " option )* [ " --" ] ( " " parameter )* nl
token ==>
"any sequence of digits"
option ==>
"-" parameter [ " " parameter ]
parameter ==>
non-blank-sequence | c-string
operation ==>
any of the operations described in this chapter
non-blank-sequence ==>
anything, provided it doesn't contain special characters such as "-", nl, """ and of course " "
c-string ==>
""" seven-bit-iso-c-string-content """
nl ==>
CR | CR-LF

Notes:

  • The CLI commands are still handled by the MI interpreter; their output is described below.
  • The token, when present, is passed back when the command finishes.
  • Some MI commands accept optional arguments as part of the parameter list. Each option is identified by a leading `-' (dash) and may be followed by an optional argument parameter. Options occur first in the parameter list and can be delimited from normal parameters using `--' (this is useful when some parameters begin with a dash).

Pragmatics:

  • We want easy access to the existing CLI syntax (for debugging).
  • We want it to be easy to spot a MI operation.

GDB/MI Output Syntax

The output from GDB/MI consists of zero or more out-of-band records followed, optionally, by a single result record. This result record is for the most recent command. The sequence of output records is terminated by `(gdb)'.

If an input command was prefixed with a token then the corresponding output for that command will also be prefixed by that same token.

output ==>
( out-of-band-record )* [ result-record ] "(gdb)" nl
result-record ==>
[ token ] "^" result-class ( "," result )* nl
out-of-band-record ==>
async-record | stream-record
async-record ==>
exec-async-output | status-async-output | notify-async-output
exec-async-output ==>
[ token ] "*" async-output
status-async-output ==>
[ token ] "+" async-output
notify-async-output ==>
[ token ] "=" async-output
async-output ==>
async-class ( "," result )* nl
result-class ==>
"done" | "running" | "connected" | "error" | "exit"
async-class ==>
"stopped" | others (where others will be added depending on the needs--this is still in development).
result ==>
variable "=" value
variable ==>
string
value ==>
const | tuple | list
const ==>
c-string
tuple ==>
"{}" | "{" result ( "," result )* "}"
list ==>
"[]" | "[" value ( "," value )* "]" | "[" result ( "," result )* "]"
stream-record ==>
console-stream-output | target-stream-output | log-stream-output
console-stream-output ==>
"~" c-string
target-stream-output ==>
"@" c-string
log-stream-output ==>
"&" c-string
nl ==>
CR | CR-LF
token ==>
any sequence of digits.

Notes:

  • All output sequences end in a single line containing a period.
  • The token is from the corresponding request. If an execution command is interrupted by the `-exec-interrupt' command, the token associated with the `*stopped' message is the one of the original execution command, not the one of the interrupt command.
  • status-async-output contains on-going status information about the progress of a slow operation. It can be discarded. All status output is prefixed by `+'.
  • exec-async-output contains asynchronous state change on the target (stopped, started, disappeared). All async output is prefixed by `*'.
  • notify-async-output contains supplementary information that the client should handle (e.g., a new breakpoint information). All notify output is prefixed by `='.
  • console-stream-output is output that should be displayed as is in the console. It is the textual response to a CLI command. All the console output is prefixed by `~'.
  • target-stream-output is the output produced by the target program. All the target output is prefixed by `@'.
  • log-stream-output is output text coming from GDB's internals, for instance messages that should be displayed as part of an error log. All the log output is prefixed by `&'.
  • New GDB/MI commands should only output lists containing values.

See section GDB/MI Stream Records, for more details about the various output records.

Simple Examples of GDB/MI Interaction

This subsection presents several simple examples of interaction using the GDB/MI interface. In these examples, `->' means that the following line is passed to GDB/MI as input, while `<-' means the output received from GDB/MI.

Target Stop

Here's an example of stopping the inferior process:

-> -stop
<- (gdb)

and later:

<- *stop,reason="stop",address="0x123",source="a.c:123"
<- (gdb)

Simple CLI Command

Here's an example of a simple CLI command being passed through GDB/MI and on to the CLI.

-> print 1+2
<- ~3\n
<- (gdb)

Command With Side Effects

-> -symbol-file xyz.exe
<- *breakpoint,nr="3",address="0x123",source="a.c:123"
<- (gdb)

A Bad Command

Here's what happens if you pass a non-existent command:

-> -rubbish
<- error,"Rubbish not found"
<- (gdb)

GDB/MI Compatibility with CLI

To help users familiar with GDB's existing CLI interface, GDB/MI accepts existing CLI commands. As specified by the syntax, such commands can be directly entered into the GDB/MI interface and GDB will respond.

This mechanism is provided as an aid to developers of GDB/MI clients and not as a reliable interface into the CLI. Since the command is being interpreteted in an environment that assumes GDB/MI behaviour, the exact output of such commands is likely to end up being an un-supported hybrid of GDB/MI and CLI output.

GDB/MI Output Records

  • GDB/MI Result Records
  • GDB/MI Stream Records
  • GDB/MI Out-of-band Records

GDB/MI Result Records

In addition to a number of out-of-band notifications, the response to a GDB/MI command includes one of the following result indications:

"^done" [ "," results ]
The synchronous operation was successful, results are the return values.
"^running"
The asynchronous operation was successfully started. The target is running.
"^error" "," c-string
The operation failed. The c-string contains the corresponding error message.

GDB/MI Stream Records

GDB internally maintains a number of output streams: the console, the target, and the log. The output intended for each of these streams is funneled through the GDB/MI interface using stream records.

Each stream record begins with a unique prefix character which identifies its stream (see section GDB/MI Output Syntax). In addition to the prefix, each stream record contains a string-output. This is either raw text (with an implicit new line) or a quoted C string (which does not contain an implicit newline).

"~" string-output
The console output stream contains text that should be displayed in the CLI console window. It contains the textual responses to CLI commands.
"@" string-output
The target output stream contains any textual output from the running target.
"&" string-output
The log stream contains debugging messages being produced by GDB's internals.

GDB/MI Out-of-band Records

Out-of-band records are used to notify the GDB/MI client of additional changes that have occurred. Those changes can either be a consequence of GDB/MI (e.g., a breakpoint modified) or a result of target activity (e.g., target stopped).

The following is a preliminary list of possible out-of-band records.

"*" "stop"

GDB/MI Command Description Format

The remaining sections describe blocks of commands. Each block of commands is laid out in a fashion similar to this section.

Note the the line breaks shown in the examples are here only for readability. They don't appear in the real output. Also note that the commands with a non-available example (N.A.) are not yet implemented.

Motivation

The motivation for this collection of commands.

Introduction

A brief introduction to this collection of commands as a whole.

Commands

For each command in the block, the following is described:

Synopsis

 -command args...

GDB Command

The corresponding GDB CLI command.

Result

Out-of-band

Notes

Example

GDB/MI Breakpoint table commands

This section documents GDB/MI commands for manipulating breakpoints.

The -break-after Command

Synopsis

 -break-after number count

The breakpoint number number is not in effect until it has been hit count times. To see how this is reflected in the output of the `-break-list' command, see the description of the `-break-list' command below.

GDB Command

The corresponding GDB command is `ignore'.

Example

(gdb)
-break-insert main
^done,bkpt={number="1",addr="0x000100d0",file="hello.c",line="5"}
(gdb)
-break-after 1 3
~
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
ignore="3"}]}
(gdb)

The -break-condition Command

Synopsis

 -break-condition number expr

Breakpoint number will stop the program only if the condition in expr is true. The condition becomes part of the `-break-list' output (see the description of the `-break-list' command below).

GDB Command

The corresponding GDB command is `condition'.

Example

(gdb)
-break-condition 1 1
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
times="0",ignore="3"}]}
(gdb)

The -break-delete Command

Synopsis

 -break-delete ( breakpoint )+

Delete the breakpoint(s) whose number(s) are specified in the argument list. This is obviously reflected in the breakpoint list.

GDB command

The corresponding GDB command is `delete'.

Example

(gdb)
-break-delete 1
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="0",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[]}
(gdb)

The -break-disable Command

Synopsis

 -break-disable ( breakpoint )+

Disable the named breakpoint(s). The field `enabled' in the break list is now set to `n' for the named breakpoint(s).

GDB Command

The corresponding GDB command is `disable'.

Example

(gdb)
-break-disable 2
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]}
(gdb)

The -break-enable Command

Synopsis

 -break-enable ( breakpoint )+

Enable (previously disabled) breakpoint(s).

GDB Command

The corresponding GDB command is `enable'.

Example

(gdb)
-break-enable 2
^done
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}]}
(gdb)

The -break-info Command

Synopsis

 -break-info breakpoint

Get information about a single breakpoint.

GDB command

The corresponding GDB command is `info break breakpoint'.

Example

N.A.

The -break-insert Command

Synopsis

 -break-insert [ -t ] [ -h ] [ -r ]
    [ -c condition ] [ -i ignore-count ]
    [ -p thread ] [ line | addr ]

If specified, line, can be one of:

  • function
  • filename:linenum
  • filename:function
  • *address

The possible optional parameters of this command are:

`-t'
Insert a tempoary breakpoint.
`-h'
Insert a hardware breakpoint.
`-c condition'
Make the breakpoint conditional on condition.
`-i ignore-count'
Initialize the ignore-count.
`-r'
Insert a regular breakpoint in all the functions whose names match the given regular expression. Other flags are not applicable to regular expresson.

Result

The result is in the form:

 ^done,bkptno="number",func="funcname",
  file="filename",line="lineno"

where number is the GDB number for this breakpoint, funcname is the name of the function where the breakpoint was inserted, filename is the name of the source file which contains this function, and lineno is the source line number within that file.

Note: this format is open to change.

GDB Command

The corresponding GDB commands are `break', `tbreak', `hbreak', `thbreak', and `rbreak'.

Example

(gdb)
-break-insert main
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
(gdb)
-break-insert -t foo
^done,bkpt={number="2",addr="0x00010774",file="recursive2.c",line="11"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"},
bkpt={number="2",type="breakpoint",disp="del",enabled="y",
addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"}]}
(gdb)
-break-insert -r foo.*
~int foo(int, int);
^done,bkpt={number="3",addr="0x00010774",file="recursive2.c",line="11"}
(gdb)

The -break-list Command

Synopsis

 -break-list

Displays the list of inserted breakpoints, showing the following fields:

`Number'
number of the breakpoint
`Type'
type of the breakpoint: `breakpoint' or `watchpoint'
`Disposition'
should the breakpoint be deleted or disabled when it is hit: `keep' or `nokeep'
`Enabled'
is the breakpoint enabled or no: `y' or `n'
`Address'
memory location at which the breakpoint is set
`What'
logical location of the breakpoint, expressed by function name, file name, line number
`Times'
number of times the breakpoint has been hit

If there are no breakpoints or watchpoints, the BreakpointTable body field is an empty list.

GDB Command

The corresponding GDB command is `info break'.

Example

(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x000100d0",func="main",file="hello.c",line="5",times="0"},
bkpt={number="2",type="breakpoint",disp="keep",enabled="y",
addr="0x00010114",func="foo",file="hello.c",line="13",times="0"}]}
(gdb)

Here's an example of the result when there are no breakpoints:

(gdb)
-break-list
^done,BreakpointTable={nr_rows="0",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[]}
(gdb)

The -break-watch Command

Synopsis

 -break-watch [ -a | -r ]

Create a watchpoint. With the `-a' option it will create an access watchpoint, i.e. a watchpoint that triggers either on a read from or on a write to the memory location. With the `-r' option, the watchpoint created is a read watchpoint, i.e. it will trigger only when the memory location is accessed for reading. Without either of the options, the watchpoint created is a regular watchpoint, i.e. it will trigger when the memory location is accessed for writing. See section Setting watchpoints.

Note that `-break-list' will report a single list of watchpoints and breakpoints inserted.

GDB Command

The corresponding GDB commands are `watch', `awatch', and `rwatch'.

Example

Setting a watchpoint on a variable in the main function:

(gdb)
-break-watch x
^done,wpt={number="2",exp="x"}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",wpt={number="2",exp="x"},
value={old="-268439212",new="55"},
frame={func="main",args=[],file="recursive2.c",line="5"}
(gdb)

Setting a watchpoint on a variable local to a function. GDB will stop the program execution twice: first for the variable changing value, then for the watchpoint going out of scope.

(gdb)
-break-watch C
^done,wpt={number="5",exp="C"}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",
wpt={number="5",exp="C"},value={old="-276895068",new="3"},
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="5",
frame={func="callee3",args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
(gdb)

Listing breakpoints and watchpoints, at different points in the program execution. Note that once the watchpoint goes out of scope, it is deleted.

(gdb)
-break-watch C
^done,wpt={number="2",exp="C"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
bkpt={number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",times="0"}]}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-trigger",wpt={number="2",exp="C"},
value={old="-276895068",new="3"},
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="2",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"},
bkpt={number="2",type="watchpoint",disp="keep",
enabled="y",addr="",what="C",times="-5"}]}
(gdb)
-exec-continue
^running
^done,reason="watchpoint-scope",wpnum="2",
frame={func="callee3",args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
(gdb)
-break-list
^done,BreakpointTable={nr_rows="1",nr_cols="6",
hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"},
{width="14",alignment="-1",col_name="type",colhdr="Type"},
{width="4",alignment="-1",col_name="disp",colhdr="Disp"},
{width="3",alignment="-1",col_name="enabled",colhdr="Enb"},
{width="10",alignment="-1",col_name="addr",colhdr="Address"},
{width="40",alignment="2",col_name="what",colhdr="What"}],
body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}]}
(gdb)

GDB/MI Data Manipulation

This section describes the GDB/MI commands that manipulate data: examine memory and registers, evaluate expressions, etc.

The -data-disassemble Command

Synopsis

 -data-disassemble
    [ -s start-addr -e end-addr ]
  | [ -f filename -l linenum [ -n lines ] ]
  -- mode

Where:

`start-addr'
is the beginning address (or $pc)
`end-addr'
is the end address
`filename'
is the name of the file to disassemble
`linenum'
is the line number to disassemble around
`lines'
is the the number of disassembly lines to be produced. If it is -1, the whole function will be disassembled, in case no end-addr is specified. If end-addr is specified as a non-zero value, and lines is lower than the number of disassembly lines between start-addr and end-addr, only lines lines are displayed; if lines is higher than the number of lines between start-addr and end-addr, only the lines up to end-addr are displayed.
`mode'
is either 0 (meaning only disassembly) or 1 (meaning mixed source and disassembly).

Result

The output for each instruction is composed of four fields:

  • Address
  • Func-name
  • Offset
  • Instruction

Note that whatever included in the instruction field, is not manipulated directely by GDB/MI, i.e. it is not possible to adjust its format.

GDB Command

There's no direct mapping from this command to the CLI.

Example

Disassemble from the current value of $pc to $pc + 20:

(gdb)
-data-disassemble -s $pc -e "$pc + 20" -- 0
^done,
asm_insns=[
{address="0x000107c0",func-name="main",offset="4",
inst="mov  2, %o0"},
{address="0x000107c4",func-name="main",offset="8",
inst="sethi  %hi(0x11800), %o2"},
{address="0x000107c8",func-name="main",offset="12",
inst="or  %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"},
{address="0x000107cc",func-name="main",offset="16",
inst="sethi  %hi(0x11800), %o2"},
{address="0x000107d0",func-name="main",offset="20",
inst="or  %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}]
(gdb)

Disassemble the whole main function. Line 32 is part of main.

-data-disassemble -f basics.c -l 32 -- 0
^done,asm_insns=[
{address="0x000107bc",func-name="main",offset="0",
inst="save  %sp, -112, %sp"},
{address="0x000107c0",func-name="main",offset="4",
inst="mov   2, %o0"},
{address="0x000107c4",func-name="main",offset="8",
inst="sethi %hi(0x11800), %o2"},
[...]
{address="0x0001081c",func-name="main",offset="96",inst="ret "},
{address="0x00010820",func-name="main",offset="100",inst="restore "}]
(gdb)

Disassemble 3 instructions from the start of main:

(gdb)
-data-disassemble -f basics.c -l 32 -n 3 -- 0
^done,asm_insns=[
{address="0x000107bc",func-name="main",offset="0",
inst="save  %sp, -112, %sp"},
{address="0x000107c0",func-name="main",offset="4",
inst="mov  2, %o0"},
{address="0x000107c4",func-name="main",offset="8",
inst="sethi  %hi(0x11800), %o2"}]
(gdb)

Disassemble 3 instructions from the start of main in mixed mode:

(gdb)
-data-disassemble -f basics.c -l 32 -n 3 -- 1
^done,asm_insns=[
src_and_asm_line={line="31",
file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
  testsuite/gdb.mi/basics.c",line_asm_insn=[
{address="0x000107bc",func-name="main",offset="0",
inst="save  %sp, -112, %sp"}]},
src_and_asm_line={line="32",
file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
  testsuite/gdb.mi/basics.c",line_asm_insn=[
{address="0x000107c0",func-name="main",offset="4",
inst="mov  2, %o0"},
{address="0x000107c4",func-name="main",offset="8",
inst="sethi  %hi(0x11800), %o2"}]}]
(gdb)

The -data-evaluate-expression Command

Synopsis

 -data-evaluate-expression expr

Evaluate expr as an expression. The expression could contain an inferior function call. The function call will execute synchronously. If the expression contains spaces, it must be enclosed in double quotes.

GDB Command

The corresponding GDB commands are `print', `output', and `call'. In gdbtk only, there's a corresponding `gdb_eval' command.

Example

In the following example, the numbers that precede the commands are the tokens described in section GDB/MI Command Syntax. Notice how GDB/MI returns the same tokens in its output.

211-data-evaluate-expression A
211^done,value="1"
(gdb)
311-data-evaluate-expression &A
311^done,value="0xefffeb7c"
(gdb)
411-data-evaluate-expression A+3
411^done,value="4"
(gdb)
511-data-evaluate-expression "A + 3"
511^done,value="4"
(gdb)

The -data-list-changed-registers Command

Synopsis

 -data-list-changed-registers

Display a list of the registers that have changed.

GDB Command

GDB doesn't have a direct analog for this command; gdbtk has the corresponding command `gdb_changed_register_list'.

Example

On a PPC MBX board:

(gdb)
-exec-continue
^running

(gdb)
*stopped,reason="breakpoint-hit",bkptno="1",frame={func="main",
args=[],file="try.c",line="5"}
(gdb)
-data-list-changed-registers
^done,changed-registers=["0","1","2","4","5","6","7","8","9",
"10","11","13","14","15","16","17","18","19","20","21","22","23",
"24","25","26","27","28","30","31","64","65","66","67","69"]
(gdb)

The -data-list-register-names Command

Synopsis

 -data-list-register-names [ ( regno )+ ]

Show a list of register names for the current target. If no arguments are given, it shows a list of the names of all the registers. If integer numbers are given as arguments, it will print a list of the names of the registers corresponding to the arguments. To ensure consistency between a register name and its number, the output list may include empty register names.

GDB Command

GDB does not have a command which corresponds to `-data-list-register-names'. In gdbtk there is a corresponding command `gdb_regnames'.

Example

For the PPC MBX board:

(gdb)
-data-list-register-names
^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
"", "pc","ps","cr","lr","ctr","xer"]
(gdb)
-data-list-register-names 1 2 3
^done,register-names=["r1","r2","r3"]
(gdb)

The -data-list-register-values Command

Synopsis

 -data-list-register-values fmt [ ( regno )*]

Display the registers' contents. fmt is the format according to which the registers' contents are to be returned, followed by an optional list of numbers specifying the registers to display. A missing list of numbers indicates that the contents of all the registers must be returned.

Allowed formats for fmt are:

x
Hexadecimal
o
Octal
t
Binary
d
Decimal
r
Raw
N
Natural

GDB Command

The corresponding GDB commands are `info reg', `info all-reg', and (in gdbtk) `gdb_fetch_registers'.

Example

For a PPC MBX board (note: line breaks are for readability only, they don't appear in the actual output):

(gdb)
-data-list-register-values r 64 65
^done,register-values=[{number="64",value="0xfe00a300"},
{number="65",value="0x00029002"}]
(gdb)
-data-list-register-values x
^done,register-values=[{number="0",value="0xfe0043c8"},
{number="1",value="0x3fff88"},{number="2",value="0xfffffffe"},
{number="3",value="0x0"},{number="4",value="0xa"},
{number="5",value="0x3fff68"},{number="6",value="0x3fff58"},
{number="7",value="0xfe011e98"},{number="8",value="0x2"},
{number="9",value="0xfa202820"},{number="10",value="0xfa202808"},
{number="11",value="0x1"},{number="12",value="0x0"},
{number="13",value="0x4544"},{number="14",value="0xffdfffff"},
{number="15",value="0xffffffff"},{number="16",value="0xfffffeff"},
{number="17",value="0xefffffed"},{number="18",value="0xfffffffe"},
{number="19",value="0xffffffff"},{number="20",value="0xffffffff"},
{number="21",value="0xffffffff"},{number="22",value="0xfffffff7"},
{number="23",value="0xffffffff"},{number="24",value="0xffffffff"},
{number="25",value="0xffffffff"},{number="26",value="0xfffffffb"},
{number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"},
{number="29",value="0x0"},{number="30",value="0xfe010000"},
{number="31",value="0x0"},{number="32",value="0x0"},
{number="33",value="0x0"},{number="34",value="0x0"},
{number="35",value="0x0"},{number="36",value="0x0"},
{number="37",value="0x0"},{number="38",value="0x0"},
{number="39",value="0x0"},{number="40",value="0x0"},
{number="41",value="0x0"},{number="42",value="0x0"},
{number="43",value="0x0"},{number="44",value="0x0"},
{number="45",value="0x0"},{number="46",value="0x0"},
{number="47",value="0x0"},{number="48",value="0x0"},
{number="49",value="0x0"},{number="50",value="0x0"},
{number="51",value="0x0"},{number="52",value="0x0"},
{number="53",value="0x0"},{number="54",value="0x0"},
{number="55",value="0x0"},{number="56",value="0x0"},
{number="57",value="0x0"},{number="58",value="0x0"},
{number="59",value="0x0"},{number="60",value="0x0"},
{number="61",value="0x0"},{number="62",value="0x0"},
{number="63",value="0x0"},{number="64",value="0xfe00a300"},
{number="65",value="0x29002"},{number="66",value="0x202f04b5"},
{number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"},
{number="69",value="0x20002b03"}]
(gdb)

The -data-read-memory Command

Synopsis

 -data-read-memory [ -o byte-offset ]
   address word-format word-size
   nr-rows nr-cols [ aschar ]

where:

`address'
An expression specifying the address of the first memory word to be read. Complex expressions containing embedded white space should be quoted using the C convention.
`word-format'
The format to be used to print the memory words. The notation is the same as for GDB's print command (see section Output formats).
`word-size'
The size of each memory word in bytes.
`nr-rows'
The number of rows in the output table.
`nr-cols'
The number of columns in the output table.
`aschar'
If present, indicates that each row should include an ASCII dump. The value of aschar is used as a padding character when a byte is not a member of the printable ASCII character set (printable ASCII characters are those whose code is between 32 and 126, inclusively).
`byte-offset'
An offset to add to the address before fetching memory.

This command displays memory contents as a table of nr-rows by nr-cols words, each word being word-size bytes. In total, nr-rows * nr-cols * word-size bytes are read (returned as `total-bytes'). Should less then the requested number of bytes be returned by the target, the missing words are identified using `N/A'. The number of bytes read from the target is returned in `nr-bytes' and the starting address used to read memory in `addr'.

The address of the next/previous row or page is available in `next-row' and `prev-row', `next-page' and `prev-page'.

GDB Command

The corresponding GDB command is `x'. gdbtk has `gdb_get_mem' memory read command.

Example

Read six bytes of memory starting at bytes+6 but then offset by -6 bytes. Format as three rows of two columns. One byte per word. Display each word in hex.

(gdb)
9-data-read-memory -o -6 -- bytes+6 x 1 3 2
9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
prev-page="0x0000138a",memory=[
{addr="0x00001390",data=["0x00","0x01"]},
{addr="0x00001392",data=["0x02","0x03"]},
{addr="0x00001394",data=["0x04","0x05"]}]
(gdb)

Read two bytes of memory starting at address shorts + 64 and display as a single word formatted in decimal.

(gdb)
5-data-read-memory shorts+64 d 2 1 1
5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
next-row="0x00001512",prev-row="0x0000150e",
next-page="0x00001512",prev-page="0x0000150e",memory=[
{addr="0x00001510",data=["128"]}]
(gdb)

Read thirty two bytes of memory starting at bytes+16 and format as eight rows of four columns. Include a string encoding with `x' used as the non-printable character.

(gdb)
4-data-read-memory bytes+16 x 1 8 4 x
4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
next-row="0x000013c0",prev-row="0x0000139c",
next-page="0x000013c0",prev-page="0x00001380",memory=[
{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"},
{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"},
{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"},
{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"},
{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"},
{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"},
{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"},
{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}]
(gdb)

The -display-delete Command

Synopsis

 -display-delete number

Delete the display number.

GDB Command

The corresponding GDB command is `delete display'.

Example

N.A.

The -display-disable Command

Synopsis

 -display-disable number

Disable display number.

GDB Command

The corresponding GDB command is `disable display'.

Example

N.A.

The -display-enable Command

Synopsis

 -display-enable number

Enable display number.

GDB Command

The corresponding GDB command is `enable display'.

Example

N.A.

The -display-insert Command

Synopsis

 -display-insert expression

Display expression every time the program stops.

GDB Command

The corresponding GDB command is `display'.

Example

N.A.

The -display-list Command

Synopsis

 -display-list

List the displays. Do not show the current values.

GDB Command

The corresponding GDB command is `info display'.

Example

N.A.

The -environment-cd Command

Synopsis

 -environment-cd pathdir

Set GDB's working directory.

GDB Command

The corresponding GDB command is `cd'.

Example

(gdb)
-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
^done
(gdb)

The -environment-directory Command

Synopsis

 -environment-directory pathdir

Add directory pathdir to beginning of search path for source files.

GDB Command

The corresponding GDB command is `dir'.

Example

(gdb)
-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
^done
(gdb)

The -environment-path Command

Synopsis

 -environment-path ( pathdir )+

Add directories pathdir to beginning of search path for object files.

GDB Command

The corresponding GDB command is `path'.

Example

(gdb)
-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb
^done
(gdb)

The -environment-pwd Command

Synopsis

 -environment-pwd

Show the current working directory.

GDB command

The corresponding GDB command is `pwd'.

Example

(gdb)
-environment-pwd
~Working directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb.
^done
(gdb)

GDB/MI Program control

Program termination

As a result of execution, the inferior program can run to completion, if it doesn't encounter any breakpoints. In this case the output will include an exit code, if the program has exited exceptionally.

Examples

Program exited normally:

(gdb)
-exec-run
^running
(gdb)
x = 55
*stopped,reason="exited-normally"
(gdb)

Program exited exceptionally:

(gdb)
-exec-run
^running
(gdb)
x = 55
*stopped,reason="exited",exit-code="01"
(gdb)

Another way the program can terminate is if it receives a signal such as SIGINT. In this case, GDB/MI displays this:

(gdb)
*stopped,reason="exited-signalled",signal-name="SIGINT",
signal-meaning="Interrupt"

The -exec-abort Command

Synopsis

 -exec-abort

Kill the inferior running program.

GDB Command

The corresponding GDB command is `kill'.

Example

N.A.

The -exec-arguments Command

Synopsis

 -exec-arguments args

Set the inferior program arguments, to be used in the next `-exec-run'.

GDB Command

The corresponding GDB command is `set args'.

Example

Don't have one around.

The -exec-continue Command

Synopsis

 -exec-continue

Asynchronous command. Resumes the execution of the inferior program until a breakpoint is encountered, or until the inferior exits.

GDB Command

The corresponding GDB corresponding is `continue'.

Example

-exec-continue
^running
(gdb)
@Hello world
*stopped,reason="breakpoint-hit",bkptno="2",frame={func="foo",args=[],
file="hello.c",line="13"}
(gdb)

The -exec-finish Command

Synopsis

 -exec-finish

Asynchronous command. Resumes the execution of the inferior program until the current function is exited. Displays the results returned by the function.

GDB Command

The corresponding GDB command is `finish'.

Example

Function returning void.

-exec-finish
^running
(gdb)
@hello from foo
*stopped,reason="function-finished",frame={func="main",args=[],
file="hello.c",line="7"}
(gdb)

Function returning other than void. The name of the internal GDB variable storing the result is printed, together with the value itself.

-exec-finish
^running
(gdb)
*stopped,reason="function-finished",frame={addr="0x000107b0",func="foo",
args=[{name="a",value="1"],{name="b",value="9"}},
file="recursive2.c",line="14"},
gdb-result-var="$1",return-value="0"
(gdb)

The -exec-interrupt Command

Synopsis

 -exec-interrupt

Asynchronous command. Interrupts the background execution of the target. Note how the token associated with the stop message is the one for the execution command that has been interrupted. The token for the interrupt itself only appears in the `^done' output. If the user is trying to interrupt a non-running program, an error message will be printed.

GDB Command

The corresponding GDB command is `interrupt'.

Example

(gdb)
111-exec-continue
111^running

(gdb)
222-exec-interrupt
222^done
(gdb)
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
frame={addr="0x00010140",func="foo",args=[],file="try.c",line="13"}
(gdb)

(gdb)
-exec-interrupt
^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
(gdb)

The -exec-next Command

Synopsis

 -exec-next

Asynchronous command. Resumes execution of the inferior program, stopping when the beginning of the next source line is reached.

GDB Command

The corresponding GDB command is `next'.

Example

-exec-next
^running
(gdb)
*stopped,reason="end-stepping-range",line="8",file="hello.c"
(gdb)

The -exec-next-instruction Command

Synopsis

 -exec-next-instruction

Asynchronous command. Executes one machine instruction. If the instruction is a function call continues until the function returns. If the program stops at an instruction in the middle of a source line, the address will be printed as well.

GDB Command

The corresponding GDB command is `nexti'.

Example

(gdb)
-exec-next-instruction
^running

(gdb)
*stopped,reason="end-stepping-range",
addr="0x000100d4",line="5",file="hello.c"
(gdb)

The -exec-return Command

Synopsis

 -exec-return

Makes current function return immediately. Doesn't execute the inferior. Displays the new current frame.

GDB Command

The corresponding GDB command is `return'.

Example

(gdb)
200-break-insert callee4
200^done,bkpt={number="1",addr="0x00010734",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
(gdb)
000-exec-run
000^running
(gdb)
000*stopped,reason="breakpoint-hit",bkptno="1",
frame={func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"}
(gdb)
205-break-delete
205^done
(gdb)
111-exec-return
111^done,frame={level="0 ",func="callee3",
args=[{name="strarg",
value="0x11940 \"A string argument.\""}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"}
(gdb)

The -exec-run Command

Synopsis

 -exec-run

Asynchronous command. Starts execution of the inferior from the beginning. The inferior executes until either a breakpoint is encountered or the program exits.

GDB Command

The corresponding GDB command is `run'.

Example

(gdb)
-break-insert main
^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"}
(gdb)
-exec-run
^running
(gdb)
*stopped,reason="breakpoint-hit",bkptno="1",
frame={func="main",args=[],file="recursive2.c",line="4"}
(gdb)

The -exec-show-arguments Command

Synopsis

 -exec-show-arguments

Print the arguments of the program.

GDB Command

The corresponding GDB command is `show args'.

Example

N.A.

The -exec-step Command

Synopsis

 -exec-step

Asynchronous command. Resumes execution of the inferior program, stopping when the beginning of the next source line is reached, if the next source line is not a function call. If it is, stop at the first instruction of the called function.

GDB Command

The corresponding GDB command is `step'.

Example

Stepping into a function:

-exec-step
^running
(gdb)
*stopped,reason="end-stepping-range",
frame={func="foo",args=[{name="a",value="10"},
{name="b",value="0"}],file="recursive2.c",line="11"}
(gdb)

Regular stepping:

-exec-step
^running
(gdb)
*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
(gdb)

The -exec-step-instruction Command

Synopsis

 -exec-step-instruction

Asynchronous command. Resumes the inferior which executes one machine instruction. The output, once GDB has stopped, will vary depending on whether we have stopped in the middle of a source line or not. In the former case, the address at which the program stopped will be printed as well.

GDB Command

The corresponding GDB command is `stepi'.

Example

(gdb)
-exec-step-instruction
^running

(gdb)
*stopped,reason="end-stepping-range",
frame={func="foo",args=[],file="try.c",line="10"}
(gdb)
-exec-step-instruction
^running

(gdb)
*stopped,reason="end-stepping-range",
frame={addr="0x000100f4",func="foo",args=[],file="try.c",line="10"}
(gdb)

The -exec-until Command

Synopsis

 -exec-until [ location ]

Asynchronous command. Executes the inferior until the location specified in the argument is reached. If there is no argument, the inferior executes until a source line greater than the current one is reached. The reason for stopping in this case will be `location-reached'.

GDB Command

The corresponding GDB command is `until'.

Example

(gdb)
-exec-until recursive2.c:6
^running
(gdb)
x = 55
*stopped,reason="location-reached",frame={func="main",args=[],
file="recursive2.c",line="6"}
(gdb)

The -file-exec-and-symbols Command

Synopsis

 -file-exec-and-symbols file

Specify the executable file to be debugged. This file is the one from which the symbol table is also read. If no file is specified, the command clears the executable and symbol information. If breakpoints are set when using this command with no arguments, GDB will produce error messages. Otherwise, no output is produced, except a completion notification.

GDB Command

The corresponding GDB command is `file'.

Example

(gdb)
-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb)

The -file-exec-file Command

Synopsis

 -file-exec-file file

Specify the executable file to be debugged. Unlike `-file-exec-and-symbols', the symbol table is not read from this file. If used without argument, GDB clears the information about the executable file. No output is produced, except a completion notification.

GDB Command

The corresponding GDB command is `exec-file'.

Example

(gdb)
-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb)

The -file-list-exec-sections Command

Synopsis

 -file-list-exec-sections

List the sections of the current executable file.

GDB Command

The GDB command `info file' shows, among the rest, the same information as this command. gdbtk has a corresponding command `gdb_load_info'.

Example

N.A.

The -file-list-exec-source-files Command

Synopsis

 -file-list-exec-source-files

List the source files for the current executable.

GDB Command

There's no GDB command which directly corresponds to this one. gdbtk has an analogous command `gdb_listfiles'.

Example

N.A.

The -file-list-shared-libraries Command

Synopsis

 -file-list-shared-libraries

List the shared libraries in the program.

GDB Command

The corresponding GDB command is `info shared'.

Example

N.A.

The -file-list-symbol-files Command

Synopsis

 -file-list-symbol-files

List symbol files.

GDB Command

The corresponding GDB command is `info file' (part of it).

Example

N.A.

The -file-symbol-file Command

Synopsis

 -file-symbol-file file

Read symbol table info from the specified file argument. When used without arguments, clears GDB's symbol table info. No output is produced, except for a completion notification.

GDB Command

The corresponding GDB command is `symbol-file'.

Example

(gdb)
-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
^done
(gdb)

Miscellaneous GDB commands in GDB/MI

The -gdb-exit Command

Synopsis

 -gdb-exit

Exit GDB immediately.

GDB Command

Approximately corresponds to `quit'.

Example

(gdb)
-gdb-exit

The -gdb-set Command

Synopsis

 -gdb-set

Set an internal GDB variable.

GDB Command

The corresponding GDB command is `set'.

Example

(gdb)
-gdb-set $foo=3
^done
(gdb)

The -gdb-show Command

Synopsis

 -gdb-show

Show the current value of a GDB variable.

GDB command

The corresponding GDB command is `show'.

Example

(gdb)
-gdb-show annotate
^done,value="0"
(gdb)

The -gdb-version Command

Synopsis

 -gdb-version

Show version information for GDB. Used mostly in testing.

GDB Command

There's no equivalent GDB command. GDB by default shows this information when you start an interactive session.

Example

(gdb)
-gdb-version
~GNU gdb 5.2.1
~Copyright 2000 Free Software Foundation, Inc.
~GDB is free software, covered by the GNU General Public License, and
~you are welcome to change it and/or distribute copies of it under
~ certain conditions.
~Type "show copying" to see the conditions.
~There is absolutely no warranty for GDB.  Type "show warranty" for
~ details.
~This GDB was configured as
 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
^done
(gdb)

GDB/MI Stack Manipulation Commands

The -stack-info-frame Command

Synopsis

 -stack-info-frame

Get info on the current frame.

GDB Command

The corresponding GDB command is `info frame' or `frame' (without arguments).

Example

N.A.

The -stack-info-depth Command

Synopsis

 -stack-info-depth [ max-depth ]

Return the depth of the stack. If the integer argument max-depth is specified, do not count beyond max-depth frames.

GDB Command

There's no equivalent GDB command.

Example

For a stack with frame levels 0 through 11:

(gdb)
-stack-info-depth
^done,depth="12"
(gdb)
-stack-info-depth 4
^done,depth="4"
(gdb)
-stack-info-depth 12
^done,depth="12"
(gdb)
-stack-info-depth 11
^done,depth="11"
(gdb)
-stack-info-depth 13
^done,depth="12"
(gdb)

The -stack-list-arguments Command

Synopsis

 -stack-list-arguments show-values
    [ low-frame high-frame ]

Display a list of the arguments for the frames between low-frame and high-frame (inclusive). If low-frame and high-frame are not provided, list the arguments for the whole call stack.

The show-values argument must have a value of 0 or 1. A value of 0 means that only the names of the arguments are listed, a value of 1 means that both names and values of the arguments are printed.

GDB Command

GDB does not have an equivalent command. gdbtk has a `gdb_get_args' command which partially overlaps with the functionality of `-stack-list-arguments'.

Example

(gdb)
-stack-list-frames
^done,
stack=[
frame={level="0 ",addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
frame={level="1 ",addr="0x0001076c",func="callee3",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
frame={level="2 ",addr="0x0001078c",func="callee2",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
frame={level="3 ",addr="0x000107b4",func="callee1",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
frame={level="4 ",addr="0x000107e0",func="main",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"}]
(gdb)
-stack-list-arguments 0
^done,
stack-args=[
frame={level="0",args=[]},
frame={level="1",args=[name="strarg"]},
frame={level="2",args=[name="intarg",name="strarg"]},
frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]},
frame={level="4",args=[]}]
(gdb)
-stack-list-arguments 1
^done,
stack-args=[
frame={level="0",args=[]},
frame={level="1",
 args=[{name="strarg",value="0x11940 \"A string argument.\""}]},
frame={level="2",args=[
{name="intarg",value="2"},
{name="strarg",value="0x11940 \"A string argument.\""}]},
{frame={level="3",args=[
{name="intarg",value="2"},
{name="strarg",value="0x11940 \"A string argument.\""},
{name="fltarg",value="3.5"}]},
frame={level="4",args=[]}]
(gdb)
-stack-list-arguments 0 2 2
^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}]
(gdb)
-stack-list-arguments 1 2 2
^done,stack-args=[frame={level="2",
args=[{name="intarg",value="2"},
{name="strarg",value="0x11940 \"A string argument.\""}]}]
(gdb)

The -stack-list-frames Command

Synopsis

 -stack-list-frames [ low-frame high-frame ]

List the frames currently on the stack. For each frame it displays the following info:

`level'
The frame number, 0 being the topmost frame, i.e. the innermost function.
`addr'
The $pc value for that frame.
`func'
Function name.
`file'
File name of the source file where the function lives.
`line'
Line number corresponding to the $pc.

If invoked without arguments, this command prints a backtrace for the whole stack. If given two integer arguments, it shows the frames whose levels are between the two arguments (inclusive). If the two arguments are equal, it shows the single frame at the corresponding level.

GDB Command

The corresponding GDB commands are `backtrace' and `where'.

Example

Full stack backtrace:

(gdb)
-stack-list-frames
^done,stack=
[frame={level="0 ",addr="0x0001076c",func="foo",
  file="recursive2.c",line="11"},
frame={level="1 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="2 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="3 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="4 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="5 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="6 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="7 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="8 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="9 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="10",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="11",addr="0x00010738",func="main",
  file="recursive2.c",line="4"}]
(gdb)

Show frames between low_frame and high_frame:

(gdb)
-stack-list-frames 3 5
^done,stack=
[frame={level="3 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="4 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"},
frame={level="5 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"}]
(gdb)

Show a single frame:

(gdb)
-stack-list-frames 3 3
^done,stack=
[frame={level="3 ",addr="0x000107a4",func="foo",
  file="recursive2.c",line="14"}]
(gdb)

The -stack-list-locals Command

Synopsis

 -stack-list-locals print-values

Display the local variable names for the current frame. With an argument of 0 prints only the names of the variables, with argument of 1 prints also their values.

GDB Command

`info locals' in GDB, `gdb_get_locals' in gdbtk.

Example

(gdb)
-stack-list-locals 0
^done,locals=[name="A",name="B",name="C"]
(gdb)
-stack-list-locals 1
^done,locals=[{name="A",value="1"},{name="B",value="2"},
  {name="C",value="3"}]
(gdb)

The -stack-select-frame Command

Synopsis

 -stack-select-frame framenum

Change the current frame. Select a different frame framenum on the stack.

GDB Command

The corresponding GDB commands are `frame', `up', `down', `select-frame', `up-silent', and `down-silent'.

Example

(gdb)
-stack-select-frame 2
^done
(gdb)

GDB/MI Symbol Query Commands

The -symbol-info-address Command

Synopsis

 -symbol-info-address symbol

Describe where symbol is stored.

GDB Command

The corresponding GDB command is `info address'.

Example

N.A.

The -symbol-info-file Command

Synopsis

 -symbol-info-file

Show the file for the symbol.

GDB Command

There's no equivalent GDB command. gdbtk has `gdb_find_file'.

Example

N.A.

The -symbol-info-function Command

Synopsis

 -symbol-info-function

Show which function the symbol lives in.

GDB Command

`gdb_get_function' in gdbtk.

Example

N.A.

The -symbol-info-line Command

Synopsis

 -symbol-info-line

Show the core addresses of the code for a source line.

GDB Command

The corresponding GDB comamnd is `info line'. gdbtk has the `gdb_get_line' and `gdb_get_file' commands.

Example

N.A.

The -symbol-info-symbol Command

Synopsis

 -symbol-info-symbol addr

Describe what symbol is at location addr.

GDB Command

The corresponding GDB command is `info symbol'.

Example

N.A.

The -symbol-list-functions Command

Synopsis

 -symbol-list-functions

List the functions in the executable.

GDB Command

`info functions' in GDB, `gdb_listfunc' and `gdb_search' in gdbtk.

Example

N.A.

The -symbol-list-types Command

Synopsis

 -symbol-list-types

List all the type names.

GDB Command

The corresponding commands are `info types' in GDB, `gdb_search' in gdbtk.

Example

N.A.

The -symbol-list-variables Command

Synopsis

 -symbol-list-variables

List all the global and static variable names.

GDB Command

`info variables' in GDB, `gdb_search' in gdbtk.

Example

N.A.

The -symbol-locate Command

Synopsis

 -symbol-locate

GDB Command

`gdb_loc' in gdbtk.

Example

N.A.

The -symbol-type Command

Synopsis

 -symbol-type variable

Show type of variable.

GDB Command

The corresponding GDB command is `ptype', gdbtk has `gdb_obj_variable'.

Example

N.A.

GDB/MI Target Manipulation Commands

The -target-attach Command

Synopsis

 -target-attach pid | file

Attach to a process pid or a file file outside of GDB.

GDB command

The corresponding GDB command is `attach'.

Example

N.A.

The -target-compare-sections Command

Synopsis

 -target-compare-sections [ section ]

Compare data of section section on target to the exec file. Without the argument, all sections are compared.

GDB Command

The GDB equivalent is `compare-sections'.

Example

N.A.

The -target-detach Command

Synopsis

 -target-detach

Disconnect from the remote target. There's no output.

GDB command

The corresponding GDB command is `detach'.

Example

(gdb)
-target-detach
^done
(gdb)

The -target-download Command

Synopsis

 -target-download

Loads the executable onto the remote target. It prints out an update message every half second, which includes the fields:

`section'
The name of the section.
`section-sent'
The size of what has been sent so far for that section.
`section-size'
The size of the section.
`total-sent'
The total size of what was sent so far (the current and the previous sections).
`total-size'
The size of the overall executable to download.

Each message is sent as status record (see section GDB/MI Output Syntax).

In addition, it prints the name and size of the sections, as they are downloaded. These messages include the following fields:

`section'
The name of the section.
`section-size'
The size of the section.
`total-size'
The size of the overall executable to download.

At the end, a summary is printed.

GDB Command

The corresponding GDB command is `load'.

Example

Note: each status message appears on a single line. Here the messages have been broken down so that they can fit onto a page.

(gdb)
-target-download
+download,{section=".text",section-size="6668",total-size="9880"}
+download,{section=".text",section-sent="512",section-size="6668",
total-sent="512",total-size="9880"}
+download,{section=".text",section-sent="1024",section-size="6668",
total-sent="1024",total-size="9880"}
+download,{section=".text",section-sent="1536",section-size="6668",
total-sent="1536",total-size="9880"}
+download,{section=".text",section-sent="2048",section-size="6668",
total-sent="2048",total-size="9880"}
+download,{section=".text",section-sent="2560",section-size="6668",
total-sent="2560",total-size="9880"}
+download,{section=".text",section-sent="3072",section-size="6668",
total-sent="3072",total-size="9880"}
+download,{section=".text",section-sent="3584",section-size="6668",
total-sent="3584",total-size="9880"}
+download,{section=".text",section-sent="4096",section-size="6668",
total-sent="4096",total-size="9880"}
+download,{section=".text",section-sent="4608",section-size="6668",
total-sent="4608",total-size="9880"}
+download,{section=".text",section-sent="5120",section-size="6668",
total-sent="5120",total-size="9880"}
+download,{section=".text",section-sent="5632",section-size="6668",
total-sent="5632",total-size="9880"}
+download,{section=".text",section-sent="6144",section-size="6668",
total-sent="6144",total-size="9880"}
+download,{section=".text",section-sent="6656",section-size="6668",
total-sent="6656",total-size="9880"}
+download,{section=".init",section-size="28",total-size="9880"}
+download,{section=".fini",section-size="28",total-size="9880"}
+download,{section=".data",section-size="3156",total-size="9880"}
+download,{section=".data",section-sent="512",section-size="3156",
total-sent="7236",total-size="9880"}
+download,{section=".data",section-sent="1024",section-size="3156",
total-sent="7748",total-size="9880"}
+download,{section=".data",section-sent="1536",section-size="3156",
total-sent="8260",total-size="9880"}
+download,{section=".data",section-sent="2048",section-size="3156",
total-sent="8772",total-size="9880"}
+download,{section=".data",section-sent="2560",section-size="3156",
total-sent="9284",total-size="9880"}
+download,{section=".data",section-sent="3072",section-size="3156",
total-sent="9796",total-size="9880"}
^done,address="0x10004",load-size="9880",transfer-rate="6586",
write-rate="429"
(gdb)

The -target-exec-status Command

Synopsis

 -target-exec-status

Provide information on the state of the target (whether it is running or not, for instance).

GDB Command

There's no equivalent GDB command.

Example

N.A.

The -target-list-available-targets Command

Synopsis

 -target-list-available-targets

List the possible targets to connect to.

GDB Command

The corresponding GDB command is `help target'.

Example

N.A.

The -target-list-current-targets Command

Synopsis

 -target-list-current-targets

Describe the current target.

GDB Command

The corresponding information is printed by `info file' (among other things).

Example

N.A.

The -target-list-parameters Command

Synopsis

 -target-list-parameters

GDB Command

No equivalent.

Example

N.A.

The -target-select Command

Synopsis

 -target-select type parameters ...

Connect GDB to the remote target. This command takes two args:

`type'
The type of target, for instance `async', `remote', etc.
`parameters'
Device names, host names and the like. See section Commands for managing targets, for more details.

The output is a connection notification, followed by the address at which the target program is, in the following form:

^connected,addr="address",func="function name",
  args=[arg list]

GDB Command

The corresponding GDB command is `target'.

Example

(gdb)
-target-select async /dev/ttya
^connected,addr="0xfe00a300",func="??",args=[]
(gdb)

GDB/MI Thread Commands

The -thread-info Command

Synopsis

 -thread-info

GDB command

No equivalent.

Example

N.A.

The -thread-list-all-threads Command

Synopsis

 -thread-list-all-threads

GDB Command

The equivalent GDB command is `info threads'.

Example

N.A.

The -thread-list-ids Command

Synopsis

 -thread-list-ids

Produces a list of the currently known GDB thread ids. At the end of the list it also prints the total number of such threads.

GDB Command

Part of `info threads' supplies the same information.

Example

No threads present, besides the main process:

(gdb)
-thread-list-ids
^done,thread-ids={},number-of-threads="0"
(gdb)

Several threads:

(gdb)
-thread-list-ids
^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
number-of-threads="3"
(gdb)

The -thread-select Command

Synopsis

 -thread-select threadnum

Make threadnum the current thread. It prints the number of the new current thread, and the topmost frame for that thread.

GDB Command

The corresponding GDB command is `thread'.

Example

(gdb)
-exec-next
^running
(gdb)
*stopped,reason="end-stepping-range",thread-id="2",line="187",
file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
(gdb)
-thread-list-ids
^done,
thread-ids={thread-id="3",thread-id="2",thread-id="1"},
number-of-threads="3"
(gdb)
-thread-select 3
^done,new-thread-id="3",
frame={level="0 ",func="vprintf",
args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
{name="arg",value="0x2"}],file="vprintf.c",line="31"}
(gdb)

GDB/MI Tracepoint Commands

The tracepoint commands are not yet implemented.

GDB/MI Variable Objects

Motivation for Variable Objects in GDB/MI

For the implementation of a variable debugger window (locals, watched expressions, etc.), we are proposing the adaptation of the existing code used by Insight.

The two main reasons for that are:

  1. It has been proven in practice (it is already on its second generation).
  2. It will shorten development time (needless to say how important it is now).

The original interface was designed to be used by Tcl code, so it was slightly changed so it could be used through GDB/MI. This section describes the GDB/MI operations that will be available and gives some hints about their use.

Note: In addition to the set of operations described here, we expect the GUI implementation of a variable window to require, at least, the following operations:

  • -gdb-show output-radix
  • -stack-list-arguments
  • -stack-list-locals
  • -stack-select-frame

Introduction to Variable Objects in GDB/MI

The basic idea behind variable objects is the creation of a named object to represent a variable, an expression, a memory location or even a CPU register. For each object created, a set of operations is available for examining or changing its properties.

Furthermore, complex data types, such as C structures, are represented in a tree format. For instance, the struct type variable is the root and the children will represent the struct members. If a child is itself of a complex type, it will also have children of its own. Appropriate language differences are handled for C, C++ and Java.

When returning the actual values of the objects, this facility allows for the individual selection of the display format used in the result creation. It can be chosen among: binary, decimal, hexadecimal, octal and natural. Natural refers to a default format automatically chosen based on the variable type (like decimal for an int, hex for pointers, etc.).

The following is the complete set of GDB/MI operations defined to access this functionality:
Operation | Description
-var-create | create a variable object
-var-delete | delete the variable object and its children
-var-set-format | set the display format of this variable
-var-show-format | show the display format of this variable
-var-info-num-children | tells how many children this object has
-var-list-children | return a list of the object's children
-var-info-type | show the type of this variable object
-var-info-expression | print what this variable object represents
-var-show-attributes | is this variable editable? does it exist here?
-var-evaluate-expression | get the value of this variable
-var-assign | set the value of this variable
-var-update | update the variable and its children

In the next subsection we describe each operation in detail and suggest how it can be used.

Description And Use of Operations on Variable Objects

The -var-create Command

Synopsis

 -var-create {name | "-"}
    {frame-addr | "*"} expression

This operation creates a variable object, which allows the monitoring of a variable, the result of an expression, a memory cell or a CPU register.

The name parameter is the string by which the object can be referenced. It must be unique. If `-' is specified, the varobj system will generate a string "varNNNNNN" automatically. It will be unique provided that one does not specify name on that format. The command fails if a duplicate name is found.

The frame under which the expression should be evaluated can be specified by frame-addr. A `*' indicates that the current frame should be used.

expression is any expression valid on the current language set (must not begin with a `*'), or one of the following:

  • `*addr', where addr is the address of a memory cell
  • `*addr-addr' -- a memory address range (TBD)
  • `$regname' -- a CPU register name

Result

This operation returns the name, number of children and the type of the object created. Type is returned as a string as the ones generated by the GDB CLI:

 name="name",numchild="N",type="type"

The -var-delete Command

Synopsis

 -var-delete name

Deletes a previously created variable object and all of its children.

Returns an error if the object name is not found.

The -var-set-format Command

Synopsis

 -var-set-format name format-spec

Sets the output format for the value of the object name to be format-spec.

The syntax for the format-spec is as follows:

 format-spec ==>
 {binary | decimal | hexadecimal | octal | natural}

The -var-show-format Command

Synopsis

 -var-show-format name

Returns the format used to display the value of the object name.

 format ==>
 format-spec

The -var-info-num-children Command

Synopsis

 -var-info-num-children name

Returns the number of children of a variable object name:

 numchild=n

The -var-list-children Command

Synopsis

 -var-list-children name

Returns a list of the children of the specified variable object:

 numchild=n,children={{name=name,
 numchild=n,type=type},(repeats N times)}

The -var-info-type Command

Synopsis

 -var-info-type name

Returns the type of the specified variable name. The type is returned as a string in the same format as it is output by the GDB CLI:

 type=typename

The -var-info-expression Command

Synopsis

 -var-info-expression name

Returns what is represented by the variable object name:

 lang=lang-spec,exp=expression

where lang-spec is {"C" | "C++" | "Java"}.

The -var-show-attributes Command

Synopsis

 -var-show-attributes name

List attributes of the specified variable object name:

 status=attr [ ( ,attr )* ]

where attr is { { editable | noneditable } | TBD }.

The -var-evaluate-expression Command

Synopsis

 -var-evaluate-expression name

Evaluates the expression that is represented by the specified variable object and returns its value as a string in the current format specified for the object:

 value=value

The -var-assign Command

Synopsis

 -var-assign name expression

Assigns the value of expression to the variable object specified by name. The object must be `editable'.

The -var-update Command

Synopsis

 -var-update {name | "*"}

Update the value of the variable object name by evaluating its expression after fetching all the new values from memory or registers. A `*' causes all existing variable objects to be updated.

Reporting Bugs in GDB

Your bug reports play an essential role in making GDB reliable.

Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of GDB work better. Bug reports are your contribution to the maintenance of GDB.

In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug.

  • Bug Criteria: Have you found a bug?
  • Bug Reporting: How to report bugs

Have you found a bug?

If you are not sure whether you have found a bug, here are some guidelines:

  • If the debugger gets a fatal signal, for any input whatever, that is a GDB bug. Reliable debuggers never crash.
  • If GDB produces an error message for valid input, that is a bug. (Note that if you're cross debugging, the problem may also be somewhere in the connection to the target.)
  • If GDB does not produce an error message for invalid input, that is a bug. However, you should note that your idea of "invalid input" might be our idea of "an extension" or "support for traditional practice".
  • If you are an experienced user of debugging tools, your suggestions for improvement of GDB are welcome in any case.

How to report bugs

A number of companies and individuals offer support for GNU products. If you obtained GDB from a support organization, we recommend you contact that organization first.

You can find contact information for many support companies and individuals in the file `etc/SERVICE' in the GNU Emacs distribution.

In any event, we also recommend that you send bug reports for GDB to this addresses:

bug-gdb@gnu.org

Do not send bug reports to `info-gdb', or to `help-gdb', or to any newsgroups. Most users of GDB do not want to receive bug reports. Those that do have arranged to receive `bug-gdb'.

The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which serves as a repeater. The mailing list and the newsgroup carry exactly the same messages. Often people think of posting bug reports to the newsgroup instead of mailing them. This appears to work, but it has one problem which can be crucial: a newsgroup posting often lacks a mail path back to the sender. Thus, if we need to ask for more information, we may be unable to reach you. For this reason, it is better to send bug reports to the mailing list.

As a last resort, send bug reports on paper to:

GNU Debugger Bugs
Free Software Foundation Inc.
59 Temple Place - Suite 330
Boston, MA 02111-1307
USA

The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!

Often people omit facts because they think they know what causes the problem and assume that some details do not matter. Thus, you might assume that the name of the variable you use in an example does not matter. Well, probably it does not, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that name is stored in memory; perhaps, if the name were different, the contents of that location would fool the debugger into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable us to fix the bug. It may be that the bug has been reported previously, but neither you nor we can know that unless your bug report is complete and self-contained.

Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" Those bug reports are useless, and we urge everyone to refuse to respond to them except to chide the sender to report bugs properly.

To enable us to fix the bug, you should include all these things:

  • The version of GDB. GDB announces it if you start with no arguments; you can also print it at any time using show version. Without this, we will not know whether there is any point in looking for the bug in the current version of GDB.
  • The type of machine you are using, and the operating system name and version number.
  • What compiler (and its version) was used to compile GDB---e.g. "gcc--2.8.1".
  • What compiler (and its version) was used to compile the program you are debugging--e.g. "gcc--2.8.1", or "HP92453-01 A.10.32.03 HP C Compiler". For GCC, you can say gcc --version to get this information; for other compilers, see the documentation for those compilers.
  • The command arguments you gave the compiler to compile your example and observe the bug. For example, did you use `-O'? To guarantee you will not omit something important, list them all. A copy of the Makefile (or the output from make) is sufficient. If we were to try to guess the arguments, we would probably guess wrong and then we might not encounter the bug.
  • A complete input script, and all necessary source files, that will reproduce the bug.
  • A description of what behavior you observe that you believe is incorrect. For example, "It gets a fatal signal." Of course, if the bug is that GDB gets a fatal signal, then we will certainly notice it. But if the bug is incorrect output, we might not notice unless it is glaringly wrong. You might as well not give us a chance to make a mistake. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of GDB is out of synch, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations.
  • If you wish to suggest changes to the GDB source, send us context diffs. If you even discuss something in the GDB source, refer to it by context, not by line number. The line numbers in our development sources will not match those in your sources. Your line numbers would convey no useful information to us.

Here are some things that are not necessary:

  • A description of the envelope of the bug. Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it. This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. We recommend that you save your time for something else. Of course, if you can find a simpler example to report instead of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take less time, and so on. However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used.
  • A patch for the bug. A patch for the bug does help us if it is a good one. But do not omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. Sometimes with a program as complicated as GDB it is very hard to construct an example that will make the program follow a certain path through the code. If you do not send us the example, we will not be able to construct one, so we will not be able to verify that the bug is fixed. And if we cannot understand what bug you are trying to fix, or why your patch should be an improvement, we will not install it. A test case will help us to understand.
  • A guess about what the bug is or what it depends on. Such guesses are usually wrong. Even we cannot guess right about such things without first using the debugger to find the facts.

Command Line Editing

This chapter describes the basic features of the GNU command line editing interface.

  • Introduction and Notation: Notation used in this text.
  • Readline Interaction: The minimum set of commands for editing a line.
  • Readline Init File: Customizing Readline from a user's view.
  • Bindable Readline Commands: A description of most of the Readline commands available for binding
  • Readline vi Mode: A short description of how to make Readline behave like the vi editor.

Introduction to Line Editing

The following paragraphs describe the notation used to represent keystrokes.

The text C-k is read as `Control-K' and describes the character produced when the k key is pressed while the Control key is depressed.

The text M-k is read as `Meta-K' and describes the character produced when the Meta key (if you have one) is depressed, and the k key is pressed. The Meta key is labeled ALT on many keyboards. On keyboards with two keys labeled ALT (usually to either side of the space bar), the ALT on the left side is generally set to work as a Meta key. The ALT key on the right may also be configured to work as a Meta key or may be configured as some other modifier, such as a Compose key for typing accented characters.

If you do not have a Meta or ALT key, or another key working as a Meta key, the identical keystroke can be generated by typing ESC first, and then typing k. Either process is known as metafying the k key.

The text M-C-k is read as `Meta-Control-k' and describes the character produced by metafying C-k.

In addition, several keys have their own names. Specifically, DEL, ESC, LFD, SPC, RET, and TAB all stand for themselves when seen in this text, or in an init file (see section Readline Init File). If your keyboard lacks a LFD key, typing C-j will produce the desired character. The RET key may be labeled Return or Enter on some keyboards.

Readline Interaction

Often during an interactive session you type in a long line of text, only to notice that the first word on the line is misspelled. The Readline library gives you a set of commands for manipulating the text as you type it in, allowing you to just fix your typo, and not forcing you to retype the majority of the line. Using these editing commands, you move the cursor to the place that needs correction, and delete or insert the text of the corrections. Then, when you are satisfied with the line, you simply press RETURN. You do not have to be at the end of the line to press RETURN; the entire line is accepted regardless of the location of the cursor within the line.

  • Readline Bare Essentials: The least you need to know about Readline.
  • Readline Movement Commands: Moving about the input line.
  • Readline Killing Commands: How to delete text, and how to get it back!
  • Readline Arguments: Giving numeric arguments to commands.
  • Searching: Searching through previous lines.

Readline Bare Essentials

In order to enter characters into the line, simply type them. The typed character appears where the cursor was, and then the cursor moves one space to the right. If you mistype a character, you can use your erase character to back up and delete the mistyped character.

Sometimes you may mistype a character, and not notice the error until you have typed several other characters. In that case, you can type C-b to move the cursor to the left, and then correct your mistake. Afterwards, you can move the cursor to the right with C-f.

When you add text in the middle of a line, you will notice that characters to the right of the cursor are `pushed over' to make room for the text that you have inserted. Likewise, when you delete text behind the cursor, characters to the right of the cursor are `pulled back' to fill in the blank space created by the removal of the text. A list of the bare essentials for editing the text of an input line follows.

C-b
Move back one character.
C-f
Move forward one character.
DEL or Backspace
Delete the character to the left of the cursor.
C-d
Delete the character underneath the cursor.
Printing characters
Insert the character into the line at the cursor.
C-_ or C-x C-u
Undo the last editing command. You can undo all the way back to an empty line.

(Depending on your configuration, the Backspace key be set to delete the character to the left of the cursor and the DEL key set to delete the character underneath the cursor, like C-d, rather than the character to the left of the cursor.)

Readline Movement Commands

The above table describes the most basic keystrokes that you need in order to do editing of the input line. For your convenience, many other commands have been added in addition to C-b, C-f, C-d, and DEL. Here are some commands for moving more rapidly about the line.

C-a
Move to the start of the line.
C-e
Move to the end of the line.
M-f
Move forward a word, where a word is composed of letters and digits.
M-b
Move backward a word.
C-l
Clear the screen, reprinting the current line at the top.

Notice how C-f moves forward a character, while M-f moves forward a word. It is a loose convention that control keystrokes operate on characters while meta keystrokes operate on words.

Readline Killing Commands

Killing text means to delete the text from the line, but to save it away for later use, usually by yanking (re-inserting) it back into the line. (`Cut' and `paste' are more recent jargon for `kill' and `yank'.)

If the description for a command says that it `kills' text, then you can be sure that you can get the text back in a different (or the same) place later.

When you use a kill command, the text is saved in a kill-ring. Any number of consecutive kills save all of the killed text together, so that when you yank it back, you get it all. The kill ring is not line specific; the text that you killed on a previously typed line is available to be yanked back later, when you are typing another line.

Here is the list of commands for killing text.

C-k
Kill the text from the current cursor position to the end of the line.
M-d
Kill from the cursor to the end of the current word, or, if between words, to the end of the next word. Word boundaries are the same as those used by M-f.
M-DEL
Kill from the cursor the start of the previous word, or, if between words, to the start of the previous word. Word boundaries are the same as those used by M-b.
C-w
Kill from the cursor to the previous whitespace. This is different than M-DEL because the word boundaries differ.

Here is how to yank the text back into the line. Yanking means to copy the most-recently-killed text from the kill buffer.

C-y
Yank the most recently killed text back into the buffer at the cursor.
M-y
Rotate the kill-ring, and yank the new top. You can only do this if the prior command is C-y or M-y.

Readline Arguments

You can pass numeric arguments to Readline commands. Sometimes the argument acts as a repeat count, other times it is the sign of the argument that is significant. If you pass a negative argument to a command which normally acts in a forward direction, that command will act in a backward direction. For example, to kill text back to the start of the line, you might type `M-- C-k'.

The general way to pass numeric arguments to a command is to type meta digits before the command. If the first `digit' typed is a minus sign (`-'), then the sign of the argument will be negative. Once you have typed one meta digit to get the argument started, you can type the remainder of the digits, and then the command. For example, to give the C-d command an argument of 10, you could type `M-1 0 C-d'.

Searching for Commands in the History

Readline provides commands for searching through the command history for lines containing a specified string. There are two search modes: incremental and non-incremental.

Incremental searches begin before the user has finished typing the search string. As each character of the search string is typed, Readline displays the next entry from the history matching the string typed so far. An incremental search requires only as many characters as needed to find the desired history entry. To search backward in the history for a particular string, type C-r. Typing C-s searches forward through the history. The characters present in the value of the isearch-terminators variable are used to terminate an incremental search. If that variable has not been assigned a value, the ESC and C-J characters will terminate an incremental search. C-g will abort an incremental search and restore the original line. When the search is terminated, the history entry containing the search string becomes the current line.

To find other matching entries in the history list, type C-r or C-s as appropriate. This will search backward or forward in the history for the next entry matching the search string typed so far. Any other key sequence bound to a Readline command will terminate the search and execute that command. For instance, a RET will terminate the search and accept the line, thereby executing the command from the history list.

Non-incremental searches read the entire search string before starting to search for matching history lines. The search string may be typed by the user or be part of the contents of the current line.

Readline Init File

Although the Readline library comes with a set of Emacs-like keybindings installed by default, it is possible to use a different set of keybindings. Any user can customize programs that use Readline by putting commands in an inputrc file, conventionally in his home directory. The name of this file is taken from the value of the environment variable INPUTRC. If that variable is unset, the default is `~/.inputrc'.

When a program which uses the Readline library starts up, the init file is read, and the key bindings are set.

In addition, the C-x C-r command re-reads this init file, thus incorporating any changes that you might have made to it.

  • Readline Init File Syntax: Syntax for the commands in the inputrc file.
  • Conditional Init Constructs: Conditional key bindings in the inputrc file.
  • Sample Init File: An example inputrc file.

Readline Init File Syntax

There are only a few basic constructs allowed in the Readline init file. Blank lines are ignored. Lines beginning with a `#' are comments. Lines beginning with a `$' indicate conditional constructs (see section Conditional Init Constructs). Other lines denote variable settings and key bindings.

Variable Settings
You can modify the run-time behavior of Readline by altering the values of variables in Readline using the set command within the init file. Here is how to change from the default Emacs-like key binding to use vi line editing commands:
set editing-mode vi
A great deal of run-time behavior is changeable with the following variables.
bell-style
Controls what happens when Readline wants to ring the terminal bell. If set to `none', Readline never rings the bell. If set to `visible', Readline uses a visible bell if one is available. If set to `audible' (the default), Readline attempts to ring the terminal's bell.
comment-begin
The string to insert at the beginning of the line when the insert-comment command is executed. The default value is "#".
completion-ignore-case
If set to `on', Readline performs filename matching and completion in a case-insensitive fashion. The default value is `off'.
completion-query-items
The number of possible completions that determines when the user is asked whether he wants to see the list of possibilities. If the number of possible completions is greater than this value, Readline will ask the user whether or not he wishes to view them; otherwise, they are simply listed. The default limit is 100.
convert-meta
If set to `on', Readline will convert characters with the eighth bit set to an ASCII key sequence by stripping the eighth bit and prefixing an ESC character, converting them to a meta-prefixed key sequence. The default value is `on'.
disable-completion
If set to `On', Readline will inhibit word completion. Completion characters will be inserted into the line as if they had been mapped to self-insert. The default is `off'.
editing-mode
The editing-mode variable controls which default set of key bindings is used. By default, Readline starts up in Emacs editing mode, where the keystrokes are most similar to Emacs. This variable can be set to either `emacs' or `vi'.
enable-keypad
When set to `on', Readline will try to enable the application keypad when it is called. Some systems need this to enable the arrow keys. The default is `off'.
expand-tilde
If set to `on', tilde expansion is performed when Readline attempts word completion. The default is `off'.
horizontal-scroll-mode
This variable can be set to either `on' or `off'. Setting it to `on' means that the text of the lines being edited will scroll horizontally on a single screen line when they are longer than the width of the screen, instead of wrapping onto a new screen line. By default, this variable is set to `off'.
input-meta
If set to `on', Readline will enable eight-bit input (it will not strip the eighth bit from the characters it reads), regardless of what the terminal claims it can support. The default value is `off'. The name meta-flag is a synonym for this variable.
isearch-terminators
The string of characters that should terminate an incremental search without subsequently executing the character as a command (see section Searching for Commands in the History). If this variable has not been given a value, the characters ESC and C-J will terminate an incremental search.
keymap
Sets Readline's idea of the current keymap for key binding commands. Acceptable keymap names are emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-command, and vi-insert. vi is equivalent to vi-command; emacs is equivalent to emacs-standard. The default value is emacs. The value of the editing-mode variable also affects the default keymap.
mark-directories
If set to `on', completed directory names have a slash appended. The default is `on'.
mark-modified-lines
This variable, when set to `on', causes Readline to display an asterisk (`*') at the start of history lines which have been modified. This variable is `off' by default.
output-meta
If set to `on', Readline will display characters with the eighth bit set directly rather than as a meta-prefixed escape sequence. The default is `off'.
print-completions-horizontally
If set to `on', Readline will display completions with matches sorted horizontally in alphabetical order, rather than down the screen. The default is `off'.
show-all-if-ambiguous
This alters the default behavior of the completion functions. If set to `on', words which have more than one possible completion cause the matches to be listed immediately instead of ringing the bell. The default value is `off'.
visible-stats
If set to `on', a character denoting a file's type is appended to the filename when listing possible completions. The default is `off'.
Key Bindings
The syntax for controlling key bindings in the init file is simple. First you need to find the name of the command that you want to change. The following sections contain tables of the command name, the default keybinding, if any, and a short description of what the command does. Once you know the name of the command, simply place the name of the key you wish to bind the command to, a colon, and then the name of the command on a line in the init file. The name of the key can be expressed in different ways, depending on which is most comfortable for you.
keyname: function-name or macro
keyname is the name of a key spelled out in English. For example:
Control-u: universal-argument
Meta-Rubout: backward-kill-word
Control-o: "> output"
In the above example, C-u is bound to the function universal-argument, and C-o is bound to run the macro expressed on the right hand side (that is, to insert the text `> output' into the line).
"keyseq": function-name or macro
keyseq differs from keyname above in that strings denoting an entire key sequence can be specified, by placing the key sequence in double quotes. Some GNU Emacs style key escapes can be used, as in the following example, but the special character names are not recognized.
"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
"\e[11~": "Function Key 1"
In the above example, C-u is bound to the function universal-argument (just as it was in the first example), `C-x C-r' is bound to the function re-read-init-file, and `ESC [ 1 1 ~' is bound to insert the text `Function Key 1'.
The following GNU Emacs style escape sequences are available when specifying key sequences:
\C-
control prefix
\M-
meta prefix
\e
an escape character
\\
backslash
\"
", a double quotation mark
\'
', a single quote or apostrophe
In addition to the GNU Emacs style escape sequences, a second set of backslash escapes is available:
\a
alert (bell)
\b
backspace
\d
delete
\f
form feed
\n
newline
\r
carriage return
\t
horizontal tab
\v
vertical tab
\nnn
the character whose ASCII code is the octal value nnn (one to three digits)
\xnnn
the character whose ASCII code is the hexadecimal value nnn (one to three digits)
When entering the text of a macro, single or double quotes must be used to indicate a macro definition. Unquoted text is assumed to be a function name. In the macro body, the backslash escapes described above are expanded. Backslash will quote any other character in the macro text, including `"' and `''. For example, the following binding will make `C-x \' insert a single `\' into the line:
"\C-x\\": "\\"

Conditional Init Constructs

Readline implements a facility similar in spirit to the conditional compilation features of the C preprocessor which allows key bindings and variable settings to be performed as the result of tests. There are four parser directives used.

$if
The $if construct allows bindings to be made based on the editing mode, the terminal being used, or the application using Readline. The text of the test extends to the end of the line; no characters are required to isolate it.
mode
The mode= form of the $if directive is used to test whether Readline is in emacs or vi mode. This may be used in conjunction with the `set keymap' command, for instance, to set bindings in the emacs-standard and emacs-ctlx keymaps only if Readline is starting out in emacs mode.
term
The term= form may be used to include terminal-specific key bindings, perhaps to bind the key sequences output by the terminal's function keys. The word on the right side of the `=' is tested against both the full name of the terminal and the portion of the terminal name before the first `-'. This allows sun to match both sun and sun-cmd, for instance.
application
The application construct is used to include application-specific settings. Each program using the Readline library sets the application name, and you can test for it. This could be used to bind key sequences to functions useful for a specific program. For instance, the following command adds a key sequence that quotes the current or previous word in Bash:
$if Bash
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif
$endif
This command, as seen in the previous example, terminates an $if command.
$else
Commands in this branch of the $if directive are executed if the test fails.
$include
This directive takes a single filename as an argument and reads commands and bindings from that file.
$include /etc/inputrc

Sample Init File

Here is an example of an inputrc file. This illustrates key binding, variable assignment, and conditional syntax.

# This file controls the behaviour of line input editing for
# programs that use the Gnu Readline library.  Existing programs
# include FTP, Bash, and Gdb.
#
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
# First, include any systemwide bindings and variable assignments from
# /etc/Inputrc
$include /etc/Inputrc

#
# Set various bindings for emacs mode.

set editing-mode emacs

$if mode=emacs

Meta-Control-h:	backward-kill-word	Text after the function name is ignored

#
# Arrow keys in keypad mode
#
#"\M-OD":        backward-char
#"\M-OC":        forward-char
#"\M-OA":        previous-history
#"\M-OB":        next-history
#
# Arrow keys in ANSI mode
#
"\M-[D":        backward-char
"\M-[C":        forward-char
"\M-[A":        previous-history
"\M-[B":        next-history
#
# Arrow keys in 8 bit keypad mode
#
#"\M-\C-OD":       backward-char
#"\M-\C-OC":       forward-char
#"\M-\C-OA":       previous-history
#"\M-\C-OB":       next-history
#
# Arrow keys in 8 bit ANSI mode
#
#"\M-\C-[D":       backward-char
#"\M-\C-[C":       forward-char
#"\M-\C-[A":       previous-history
#"\M-\C-[B":       next-history

C-q: quoted-insert

$endif

# An old-style binding.  This happens to be the default.
TAB: complete

# Macros that are convenient for shell interaction
$if Bash
# edit the path
"\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
# prepare to type a quoted word -- insert open and close
# double quotes and move to just after the open quote
"\C-x\"": "\"\"\C-b"
# insert a backslash (testing backslash escapes in sequences
# and macros)
"\C-x\\": "\\"
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
# Add a binding to refresh the line, which is unbound
"\C-xr": redraw-current-line
# Edit variable on current line.
"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
$endif

# use a visible bell if one is available
set bell-style visible

# don't strip characters to 7 bits when reading
set input-meta on

# allow iso-latin1 characters to be inserted rather than converted to
# prefix-meta sequences
set convert-meta off

# display characters with the eighth bit set directly rather than
# as meta-prefixed characters
set output-meta on

# if there are more than 150 possible completions for a word, ask the
# user if he wants to see all of them
set completion-query-items 150

# For FTP
$if Ftp
"\C-xg": "get \M-?"
"\C-xt": "put \M-?"
"\M-.": yank-last-arg
$endif

Bindable Readline Commands

  • Commands For Moving: Moving about the line.
  • Commands For History: Getting at previous lines.
  • Commands For Text: Commands for changing text.
  • Commands For Killing: Commands for killing and yanking.
  • Numeric Arguments: Specifying numeric arguments, repeat counts.
  • Commands For Completion: Getting Readline to do the typing for you.
  • Keyboard Macros: Saving and re-executing typed characters
  • Miscellaneous Commands: Other miscellaneous commands.

This section describes Readline commands that may be bound to key sequences.

Command names without an accompanying key sequence are unbound by default. In the following descriptions, point refers to the current cursor position, and mark refers to a cursor position saved by the set-mark command. The text between the point and mark is referred to as the region.

Commands For Moving

beginning-of-line (C-a)
Move to the start of the current line.
end-of-line (C-e)
Move to the end of the line.
forward-char (C-f)
Move forward a character.
backward-char (C-b)
Move back a character.
forward-word (M-f)
Move forward to the end of the next word. Words are composed of letters and digits.
backward-word (M-b)
Move back to the start of the current or previous word. Words are composed of letters and digits.
clear-screen (C-l)
Clear the screen and redraw the current line, leaving the current line at the top of the screen.
redraw-current-line ()
Refresh the current line. By default, this is unbound.

Commands For Manipulating The History

accept-line (Newline, Return)
Accept the line regardless of where the cursor is. If this line is non-empty, add it to the history list. If this line was a history line, then restore the history line to its original state.
previous-history (C-p)
Move `up' through the history list.
next-history (C-n)
Move `down' through the history list.
beginning-of-history (M-<)
Move to the first line in the history.
end-of-history (M->)
Move to the end of the input history, i.e., the line currently being entered.
reverse-search-history (C-r)
Search backward starting at the current line and moving `up' through the history as necessary. This is an incremental search.
forward-search-history (C-s)
Search forward starting at the current line and moving `down' through the the history as necessary. This is an incremental search.
non-incremental-reverse-search-history (M-p)
Search backward starting at the current line and moving `up' through the history as necessary using a non-incremental search for a string supplied by the user.
non-incremental-forward-search-history (M-n)
Search forward starting at the current line and moving `down' through the the history as necessary using a non-incremental search for a string supplied by the user.
history-search-forward ()
Search forward through the history for the string of characters between the start of the current line and the point. This is a non-incremental search. By default, this command is unbound.
history-search-backward ()
Search backward through the history for the string of characters between the start of the current line and the point. This is a non-incremental search. By default, this command is unbound.
yank-nth-arg (M-C-y)
Insert the first argument to the previous command (usually the second word on the previous line). With an argument n, insert the nth word from the previous command (the words in the previous command begin with word 0). A negative argument inserts the nth word from the end of the previous command.
yank-last-arg (M-., M-_)
Insert last argument to the previous command (the last word of the previous history entry). With an argument, behave exactly like yank-nth-arg. Successive calls to yank-last-arg move back through the history list, inserting the last argument of each line in turn.

Commands For Changing Text

delete-char (C-d)
Delete the character under the cursor. If the cursor is at the beginning of the line, there are no characters in the line, and the last character typed was not bound to delete-char, then return EOF.
backward-delete-char (Rubout)
Delete the character behind the cursor. A numeric argument means to kill the characters instead of deleting them.
forward-backward-delete-char ()
Delete the character under the cursor, unless the cursor is at the end of the line, in which case the character behind the cursor is deleted. By default, this is not bound to a key.
quoted-insert (C-q, C-v)
Add the next character typed to the line verbatim. This is how to insert key sequences like C-q, for example.
tab-insert (M-TAB)
Insert a tab character.
self-insert (a, b, A, 1, !, ...)
Insert yourself.
transpose-chars (C-t)
Drag the character before the cursor forward over the character at the cursor, moving the cursor forward as well. If the insertion point is at the end of the line, then this transposes the last two characters of the line. Negative arguments have no effect.
transpose-words (M-t)
Drag the word before point past the word after point, moving point past that word as well.
upcase-word (M-u)
Uppercase the current (or following) word. With a negative argument, uppercase the previous word, but do not move the cursor.
downcase-word (M-l)
Lowercase the current (or following) word. With a negative argument, lowercase the previous word, but do not move the cursor.
capitalize-word (M-c)
Capitalize the current (or following) word. With a negative argument, capitalize the previous word, but do not move the cursor.

Killing And Yanking

kill-line (C-k)
Kill the text from point to the end of the line.
backward-kill-line (C-x Rubout)
Kill backward to the beginning of the line.
unix-line-discard (C-u)
Kill backward from the cursor to the beginning of the current line.
kill-whole-line ()
Kill all characters on the current line, no matter point is. By default, this is unbound.
kill-word (M-d)
Kill from point to the end of the current word, or if between words, to the end of the next word. Word boundaries are the same as forward-word.
backward-kill-word (M-DEL)
Kill the word behind point. Word boundaries are the same as backward-word.
unix-word-rubout (C-w)
Kill the word behind point, using white space as a word boundary. The killed text is saved on the kill-ring.
delete-horizontal-space ()
Delete all spaces and tabs around point. By default, this is unbound.
kill-region ()
Kill the text in the current region. By default, this command is unbound.
copy-region-as-kill ()
Copy the text in the region to the kill buffer, so it can be yanked right away. By default, this command is unbound.
copy-backward-word ()
Copy the word before point to the kill buffer. The word boundaries are the same as backward-word. By default, this command is unbound.
copy-forward-word ()
Copy the word following point to the kill buffer. The word boundaries are the same as forward-word. By default, this command is unbound.
yank (C-y)
Yank the top of the kill ring into the buffer at the current cursor position.
yank-pop (M-y)
Rotate the kill-ring, and yank the new top. You can only do this if the prior command is yank or yank-pop.

Specifying Numeric Arguments

digit-argument (M-0, M-1, ... M--)
Add this digit to the argument already accumulating, or start a new argument. M-- starts a negative argument.
universal-argument ()
This is another way to specify an argument. If this command is followed by one or more digits, optionally with a leading minus sign, those digits define the argument. If the command is followed by digits, executing universal-argument again ends the numeric argument, but is otherwise ignored. As a special case, if this command is immediately followed by a character that is neither a digit or minus sign, the argument count for the next command is multiplied by four. The argument count is initially one, so executing this function the first time makes the argument count four, a second time makes the argument count sixteen, and so on. By default, this is not bound to a key.

Letting Readline Type For You

complete (TAB)
Attempt to do completion on the text before the cursor. This is application-specific. Generally, if you are typing a filename argument, you can do filename completion; if you are typing a command, you can do command completion; if you are typing in a symbol to GDB, you can do symbol name completion; if you are typing in a variable to Bash, you can do variable name completion, and so on.
possible-completions (M-?)
List the possible completions of the text before the cursor.
insert-completions (M-*)
Insert all completions of the text before point that would have been generated by possible-completions.
menu-complete ()
Similar to complete, but replaces the word to be completed with a single match from the list of possible completions. Repeated execution of menu-complete steps through the list of possible completions, inserting each match in turn. At the end of the list of completions, the bell is rung and the original text is restored. An argument of n moves n positions forward in the list of matches; a negative argument may be used to move backward through the list. This command is intended to be bound to TAB, but is unbound by default.
delete-char-or-list ()
Deletes the character under the cursor if not at the beginning or end of the line (like delete-char). If at the end of the line, behaves identically to possible-completions. This command is unbound by default.

Keyboard Macros

start-kbd-macro (C-x ()
Begin saving the characters typed into the current keyboard macro.
end-kbd-macro (C-x ))
Stop saving the characters typed into the current keyboard macro and save the definition.
call-last-kbd-macro (C-x e)
Re-execute the last keyboard macro defined, by making the characters in the macro appear as if typed at the keyboard.

Some Miscellaneous Commands

re-read-init-file (C-x C-r)
Read in the contents of the inputrc file, and incorporate any bindings or variable assignments found there.
abort (C-g)
Abort the current editing command and ring the terminal's bell (subject to the setting of bell-style).
do-uppercase-version (M-a, M-b, M-x, ...)
If the metafied character x is lowercase, run the command that is bound to the corresponding uppercase character.
prefix-meta (ESC)
Make the next character typed be metafied. This is for keyboards without a meta key. Typing `ESC f' is equivalent to typing `M-f'.
undo (C-_, C-x C-u)
Incremental undo, separately remembered for each line.
revert-line (M-r)
Undo all changes made to this line. This is like executing the undo command enough times to get back to the beginning.
tilde-expand (M-~)
Perform tilde expansion on the current word.
set-mark (C-@)
Set the mark to the current point. If a numeric argument is supplied, the mark is set to that position.
exchange-point-and-mark (C-x C-x)
Swap the point with the mark. The current cursor position is set to the saved position, and the old cursor position is saved as the mark.
character-search (C-])
A character is read and point is moved to the next occurrence of that character. A negative count searches for previous occurrences.
character-search-backward (M-C-])
A character is read and point is moved to the previous occurrence of that character. A negative count searches for subsequent occurrences.
insert-comment (M-#)
The value of the comment-begin variable is inserted at the beginning of the current line, and the line is accepted as if a newline had been typed.
dump-functions ()
Print all of the functions and their key bindings to the Readline output stream. If a numeric argument is supplied, the output is formatted in such a way that it can be made part of an inputrc file. This command is unbound by default.
dump-variables ()
Print all of the settable variables and their values to the Readline output stream. If a numeric argument is supplied, the output is formatted in such a way that it can be made part of an inputrc file. This command is unbound by default.
dump-macros ()
Print all of the Readline key sequences bound to macros and the strings they ouput. If a numeric argument is supplied, the output is formatted in such a way that it can be made part of an inputrc file. This command is unbound by default.

Readline vi Mode

While the Readline library does not have a full set of vi editing functions, it does contain enough to allow simple editing of the line. The Readline vi mode behaves as specified in the POSIX 1003.2 standard.

In order to switch interactively between emacs and vi editing modes, use the command M-C-j (toggle-editing-mode). The Readline default is emacs mode.

When you enter a line in vi mode, you are already placed in `insertion' mode, as if you had typed an `i'. Pressing ESC switches you into `command' mode, where you can edit the text of the line with the standard vi movement keys, move to previous history lines with `k' and subsequent lines with `j', and so forth.

Using History Interactively

This chapter describes how to use the GNU History Library interactively, from a user's standpoint. It should be considered a user's guide.

  • History Interaction: What it feels like using History as a user.

History Expansion

The History library provides a history expansion feature that is similar to the history expansion provided by csh. This section describes the syntax used to manipulate the history information.

History expansions introduce words from the history list into the input stream, making it easy to repeat commands, insert the arguments to a previous command into the current input line, or fix errors in previous commands quickly.

History expansion takes place in two parts. The first is to determine which line from the history list should be used during substitution. The second is to select portions of that line for inclusion into the current one. The line selected from the history is called the event, and the portions of that line that are acted upon are called words. Various modifiers are available to manipulate the selected words. The line is broken into words in the same fashion that Bash does, so that several words surrounded by quotes are considered one word. History expansions are introduced by the appearance of the history expansion character, which is `!' by default.

  • Event Designators: How to specify which history line to use.
  • Word Designators: Specifying which words are of interest.
  • Modifiers: Modifying the results of substitution.

Event Designators

An event designator is a reference to a command line entry in the history list.

!
Start a history substitution, except when followed by a space, tab, the end of the line, `=' or `('.
!n
Refer to command line n.
!-n
Refer to the command n lines back.
!!
Refer to the previous command. This is a synonym for `!-1'.
!string
Refer to the most recent command starting with string.
!?string[?]
Refer to the most recent command containing string. The trailing `?' may be omitted if the string is followed immediately by a newline.
^string1^string2^
Quick Substitution. Repeat the last command, replacing string1 with string2. Equivalent to !!:s/string1/string2/.
!#
The entire command line typed so far.

Word Designators

Word designators are used to select desired words from the event. A `:' separates the event specification from the word designator. It may be omitted if the word designator begins with a `^', `$', `*', `-', or `%'. Words are numbered from the beginning of the line, with the first word being denoted by 0 (zero). Words are inserted into the current line separated by single spaces.

For example,

!!
designates the preceding command. When you type this, the preceding command is repeated in toto.
!!:$
designates the last argument of the preceding command. This may be shortened to !$.
!fi:2
designates the second argument of the most recent command starting with the letters fi.

Here are the word designators:

0 (zero)
The 0th word. For many applications, this is the command word.
n
The nth word.
^
The first argument; that is, word 1.
$
The last argument.
%
The word matched by the most recent `?string?' search.
x-y
A range of words; `-y' abbreviates `0-y'.
*
All of the words, except the 0th. This is a synonym for `1-$'. It is not an error to use `*' if there is just one word in the event; the empty string is returned in that case.
x*
Abbreviates `x-$'
x-
Abbreviates `x-$' like `x*', but omits the last word.

If a word designator is supplied without an event specification, the previous command is used as the event.

Modifiers

After the optional word designator, you can add a sequence of one or more of the following modifiers, each preceded by a `:'.

h
Remove a trailing pathname component, leaving only the head.
t
Remove all leading pathname components, leaving the tail.
r
Remove a trailing suffix of the form `.suffix', leaving the basename.
e
Remove all but the trailing suffix.
p
Print the new command but do not execute it.
s/old/new/
Substitute new for the first occurrence of old in the event line. Any delimiter may be used in place of `/'. The delimiter may be quoted in old and new with a single backslash. If `&' appears in new, it is replaced by old. A single backslash will quote the `&'. The final delimiter is optional if it is the last character on the input line.
&
Repeat the previous substitution.
g
Cause changes to be applied over the entire event line. Used in conjunction with `s', as in gs/old/new/, or with `&'.

Formatting Documentation

The GDB 4 release includes an already-formatted reference card, ready for printing with PostScript or Ghostscript, in the `gdb' subdirectory of the main source directory(7). If you can use PostScript or Ghostscript with your printer, you can print the reference card immediately with `refcard.ps'.

The release also includes the source for the reference card. You can format it, using TeX, by typing:

make refcard.dvi

The GDB reference card is designed to print in landscape mode on US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches high. You will need to specify this form of printing as an option to your DVI output program.

All the documentation for GDB comes as part of the machine-readable distribution. The documentation is written in Texinfo format, which is a documentation system that uses a single source file to produce both on-line information and a printed manual. You can use one of the Info formatting commands to create the on-line version of the documentation and TeX (or texi2roff) to typeset the printed version.

GDB includes an already formatted copy of the on-line Info version of this manual in the `gdb' subdirectory. The main Info file is `gdb-5.1.1/gdb/gdb.info', and it refers to subordinate files matching `gdb.info*' in the same directory. If necessary, you can print out these files, or read them with any editor; but they are easier to read using the info subsystem in GNU Emacs or the standalone info program, available as part of the GNU Texinfo distribution.

If you want to format these Info files yourself, you need one of the Info formatting programs, such as texinfo-format-buffer or makeinfo.

If you have makeinfo installed, and are in the top level GDB source directory (`gdb-5.1.1', in the case of version 5.1.1), you can make the Info file by typing:

cd gdb
make gdb.info

If you want to typeset and print copies of this manual, you need TeX, a program to print its DVI output files, and `texinfo.tex', the Texinfo definitions file.

TeX is a typesetting program; it does not print files directly, but produces output files called DVI files. To print a typeset document, you need a program to print DVI files. If your system has TeX installed, chances are it has such a program. The precise command to use depends on your system; lpr -d is common; another (for PostScript devices) is dvips. The DVI print command may require a file name without any extension or a `.dvi' extension.

TeX also requires a macro definitions file called `texinfo.tex'. This file tells TeX how to typeset a document written in Texinfo format. On its own, TeX cannot either read or typeset a Texinfo file. `texinfo.tex' is distributed with GDB and is located in the `gdb-version-number/texinfo' directory.

If you have TeX and a DVI printer program installed, you can typeset and print this manual. First switch to the the `gdb' subdirectory of the main source directory (for example, to `gdb-5.1.1/gdb') and type:

make gdb.dvi

Then give `gdb.dvi' to your DVI printing program.

Installing GDB

GDB comes with a configure script that automates the process of preparing GDB for installation; you can then use make to build the gdb program. (8)

The GDB distribution includes all the source code you need for GDB in a single directory, whose name is usually composed by appending the version number to `gdb'.

For example, the GDB version 5.1.1 distribution is in the `gdb-5.1.1' directory. That directory contains:

gdb-5.1.1/configure (and supporting files)
script for configuring GDB and all its supporting libraries
gdb-5.1.1/gdb
the source specific to GDB itself
gdb-5.1.1/bfd
source for the Binary File Descriptor library
gdb-5.1.1/include
GNU include files
gdb-5.1.1/libiberty
source for the `-liberty' free software library
gdb-5.1.1/opcodes
source for the library of opcode tables and disassemblers
gdb-5.1.1/readline
source for the GNU command-line interface
gdb-5.1.1/glob
source for the GNU filename pattern-matching subroutine
gdb-5.1.1/mmalloc
source for the GNU memory-mapped malloc package

The simplest way to configure and build GDB is to run configure from the `gdb-version-number' source directory, which in this example is the `gdb-5.1.1' directory.

First switch to the `gdb-version-number' source directory if you are not already in it; then run configure. Pass the identifier for the platform on which GDB will run as an argument.

For example:

cd gdb-5.1.1
./configure host
make

where host is an identifier such as `sun4' or `decstation', that identifies the platform where GDB will run. (You can often leave off host; configure tries to guess the correct value by examining your system.)

Running `configure host' and then running make builds the `bfd', `readline', `mmalloc', and `libiberty' libraries, then gdb itself. The configured source files, and the binaries, are left in the corresponding source directories.

configure is a Bourne-shell (/bin/sh) script; if your system does not recognize this automatically when you run a different shell, you may need to run sh on it explicitly:

sh configure host

If you run configure from a directory that contains source directories for multiple libraries or programs, such as the `gdb-5.1.1' source directory for version 5.1.1, configure creates configuration files for every directory level underneath (unless you tell it not to, with the `--norecursion' option).

You can run the configure script from any of the subordinate directories in the GDB distribution if you only want to configure that subdirectory, but be sure to specify a path to it.

For example, with version 5.1.1, type the following to configure only the bfd subdirectory:

cd gdb-5.1.1/bfd
../configure host

You can install gdb anywhere; it has no hardwired paths. However, you should make sure that the shell on your path (named by the `SHELL' environment variable) is publicly readable. Remember that GDB uses the shell to start your program--some systems refuse to let GDB debug child processes whose programs are not readable.

  • Separate Objdir: Compiling GDB in another directory
  • Config Names: Specifying names for hosts and targets
  • Configure Options: Summary of options for configure

Compiling GDB in another directory

If you want to run GDB versions for several host or target machines, you need a different gdb compiled for each combination of host and target. configure is designed to make this easy by allowing you to generate each configuration in a separate subdirectory, rather than in the source directory. If your make program handles the `VPATH' feature (GNU make does), running make in each of these directories builds the gdb program specified there.

To build gdb in a separate directory, run configure with the `--srcdir' option to specify where to find the source. (You also need to specify a path to find configure itself from your working directory. If the path to configure would be the same as the argument to `--srcdir', you can leave out the `--srcdir' option; it is assumed.)

For example, with version 5.1.1, you can build GDB in a separate directory for a Sun 4 like this:

cd gdb-5.1.1
mkdir ../gdb-sun4
cd ../gdb-sun4
../gdb-5.1.1/configure sun4
make

When configure builds a configuration using a remote source directory, it creates a tree for the binaries with the same structure (and using the same names) as the tree under the source directory. In the example, you'd find the Sun 4 library `libiberty.a' in the directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.

One popular reason to build several GDB configurations in separate directories is to configure GDB for cross-compiling (where GDB runs on one machine--the host---while debugging programs that run on another machine--the target). You specify a cross-debugging target by giving the `--target=target' option to configure.

When you run make to build a program or library, you must run it in a configured directory--whatever directory you were in when you called configure (or one of its subdirectories).

The Makefile that configure generates in each source directory also runs recursively. If you type make in a source directory such as `gdb-5.1.1' (or in a separate configured directory configured with `--srcdir=dirname/gdb-5.1.1'), you will build all the required libraries, and then build GDB.

When you have multiple hosts or targets configured in separate directories, you can run make on them in parallel (for example, if they are NFS-mounted on each of the hosts); they will not interfere with each other.

Specifying names for hosts and targets

The specifications used for hosts and targets in the configure script are based on a three-part naming scheme, but some short predefined aliases are also supported. The full naming scheme encodes three pieces of information in the following pattern:

architecture-vendor-os

For example, you can use the alias sun4 as a host argument, or as the value for target in a --target=target option. The equivalent full name is `sparc-sun-sunos4'.

The configure script accompanying GDB does not provide any query facility to list all supported host and target names or aliases. configure calls the Bourne shell script config.sub to map abbreviations to full names; you can read the script, if you wish, or you can use it to test your guesses on abbreviations--for example:

% sh config.sub i386-linux
i386-pc-linux-gnu
% sh config.sub alpha-linux
alpha-unknown-linux-gnu
% sh config.sub hp9k700
hppa1.1-hp-hpux
% sh config.sub sun4
sparc-sun-sunos4.1.1
% sh config.sub sun3
m68k-sun-sunos4.1.1
% sh config.sub i986v
Invalid configuration `i986v': machine `i986v' not recognized

config.sub is also distributed in the GDB source directory (`gdb-5.1.1', for version 5.1.1).

configure options

Here is a summary of the configure options and arguments that are most often useful for building GDB. configure also has several other options not listed here. See Info file `configure.info', node `What Configure Does', for a full explanation of configure.

configure [--help]
          [--prefix=dir]
          [--exec-prefix=dir]
          [--srcdir=dirname]
          [--norecursion] [--rm]
          [--target=target]
          host

You may introduce options with a single `-' rather than `--' if you prefer; but you may abbreviate option names if you use `--'.

--help
Display a quick summary of how to invoke configure.
--prefix=dir
Configure the source to install programs and files under directory `dir'.
--exec-prefix=dir
Configure the source to install programs under directory `dir'.
--srcdir=dirname
Warning: using this option requires GNU make, or another make that implements the VPATH feature.
Use this option to make configurations in directories separate from the GDB source directories. Among other things, you can use this to build (or maintain) several configurations simultaneously, in separate directories. configure writes configuration specific files in the current directory, but arranges for them to use the source in the directory dirname. configure creates directories under the working directory in parallel to the source directories below dirname.
--norecursion
Configure only the directory level where configure is executed; do not propagate configuration to subdirectories.
--target=target
Configure GDB for cross-debugging programs running on the specified target. Without this option, GDB is configured to debug programs that run on the same machine (host) as GDB itself. There is no convenient way to generate a list of all available targets.
host ...
Configure GDB to run on the specified host. There is no convenient way to generate a list of all available hosts.

There are many other options available as well, but they are generally needed for special purposes only.

GNU Free Documentation License

Version 1.1, March 2000

Copyright (C) 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
  2. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you." A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque." Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
  3. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies.
  4. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
  5. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    D. Preserve all the copyright notices of the Document.
    E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    H. Include an unaltered copy of this License.
    I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    M. Delete any section entitled "Endorsements." Such a section may not be included in the Modified Version.
    N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.
    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
  6. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications." You must delete all sections entitled "Endorsements."
  7. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
  8. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
  9. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
  10. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  11. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright (C)  year  your name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being list their titles, with the
Front-Cover Texts being list, and with the Back-Cover Texts being list.
A copy of the license is included in the section entitled "GNU
Free Documentation License."

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Index

Jump to: " - # - $ - - - . - / - : - @ - ^ - 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 - {

"

  • "No symbol "foo" in current context"

    • #

  • # (a comment)
  • # in Modula-2

    • $

  • $
  • $$
  • $_, convenience variable
  • $_ and info breakpoints
  • $_ and info line
  • $_, $__, and value history
  • $__, convenience variable
  • $_exitcode, convenience variable
  • $bpnum, convenience variable
  • $cdir, convenience variable
  • $cwdr, convenience variable
  • $tpnum
  • $trace_file
  • $trace_frame
  • $trace_func
  • $trace_line
  • $tracepoint

    • -

  • --annotate
  • --async
  • --batch
  • --baud
  • --cd
  • --command
  • --core
  • --directory
  • --epoch
  • --exec
  • --fullname
  • --interpreter
  • --mapped
  • --noasync
  • --nowindows
  • --nx
  • --quiet
  • --readnow
  • --se
  • --silent
  • --statistics
  • --symbols
  • --tty
  • --tui
  • --version
  • --windows
  • --write
  • -b
  • -break-after
  • -break-condition
  • -break-delete
  • -break-disable
  • -break-enable
  • -break-info
  • -break-insert
  • -break-list
  • -break-watch
  • -c
  • -d
  • -data-disassemble
  • -data-evaluate-expression
  • -data-list-changed-registers
  • -data-list-register-names
  • -data-list-register-values
  • -data-read-memory
  • -display-delete
  • -display-disable
  • -display-enable
  • -display-insert
  • -display-list
  • -e
  • -environment-cd
  • -environment-directory
  • -environment-path
  • -environment-pwd
  • -exec-abort
  • -exec-arguments
  • -exec-continue
  • -exec-finish
  • -exec-interrupt
  • -exec-next
  • -exec-next-instruction
  • -exec-return
  • -exec-run
  • -exec-show-arguments
  • -exec-step
  • -exec-step-instruction
  • -exec-until
  • -f
  • -file-exec-and-symbols
  • -file-exec-file
  • -file-list-exec-sections
  • -file-list-exec-source-files
  • -file-list-shared-libraries
  • -file-list-symbol-files
  • -file-symbol-file
  • -gdb-exit
  • -gdb-set
  • -gdb-show
  • -gdb-version
  • -m
  • -n
  • -nw
  • -q
  • -r
  • -s
  • -stack-info-depth
  • -stack-info-frame
  • -stack-list-arguments
  • -stack-list-frames
  • -stack-list-locals
  • -stack-select-frame
  • -symbol-info-address
  • -symbol-info-file
  • -symbol-info-function
  • -symbol-info-line
  • -symbol-info-symbol
  • -symbol-list-functions
  • -symbol-list-types
  • -symbol-list-variables
  • -symbol-locate
  • -symbol-type
  • -t
  • -target-attach
  • -target-compare-sections
  • -target-detach
  • -target-download
  • -target-exec-status
  • -target-list-available-targets
  • -target-list-current-targets
  • -target-list-parameters
  • -target-select
  • -thread-info
  • -thread-list-all-threads
  • -thread-list-ids
  • -thread-select
  • -var-assign
  • -var-create
  • -var-delete
  • -var-evaluate-expression
  • -var-info-expression
  • -var-info-num-children
  • -var-info-type
  • -var-list-children
  • -var-set-format
  • -var-show-attributes
  • -var-show-format
  • -var-update
  • -w
  • -x

    • .

  • ., Modula-2 scope operator
  • `.esgdbinit'
  • `.gdbinit'
  • `.os68gdbinit'
  • `.vxgdbinit'

    • /

  • /proc

    • :

  • ::, context for variables/functions
  • ::, in Modula-2

    • @

  • @, referencing memory as an array

    • ^

  • ^done
  • ^error
  • ^running

    • a

  • a.out and C++
  • abbreviation
  • abort (C-g)
  • accept-line (Newline, Return)
  • acknowledgment, for GDB remote
  • actions
  • active targets
  • add-shared-symbol-file
  • add-symbol-file
  • address of a symbol
  • Alpha stack
  • AMD 29K register stack
  • AMD EB29K
  • AMD29K via UDI
  • annotations
  • annotations for breakpoints
  • annotations for display
  • annotations for errors, warnings and interrupts
  • annotations for frames
  • annotations for invalidation messages
  • annotations for prompts
  • annotations for running programs
  • annotations for source display
  • annotations for values
  • apropos
  • arg-begin
  • arg-end
  • arg-name-end
  • arg-value
  • arguments (to your program)
  • array-section-end
  • artificial array
  • assembly instructions, assembly instructions
  • assignment
  • async output in GDB/MI
  • AT&T disassembly flavor
  • attach, attach
  • automatic display
  • automatic thread selection
  • awatch

    • b

  • b (break)
  • backtrace
  • backtraces
  • backward-char (C-b)
  • backward-delete-char (Rubout)
  • backward-kill-line (C-x Rubout)
  • backward-kill-word (M-DEL)
  • backward-word (M-b)
  • beginning-of-history (M-&#60;)
  • beginning-of-line (C-a)
  • bell-style
  • break
  • break ... thread threadno
  • break in overloaded functions
  • breakpoint
  • breakpoint commands
  • breakpoint commands for GDB/MI
  • breakpoint conditions
  • breakpoint numbers
  • breakpoint on events
  • breakpoint on memory address
  • breakpoint on variable modification
  • breakpoint ranges
  • breakpoint subroutine, remote
  • breakpoints
  • breakpoints and threads
  • breakpoints-headers
  • breakpoints-invalid
  • breakpoints-table
  • breakpoints-table-end
  • bt (backtrace)
  • bug criteria
  • bug reports
  • bugs in GDB

    • c

  • c (continue)
  • C and C++
  • C and C++ checks
  • C and C++ constants
  • C and C++ defaults
  • C and C++ operators
  • C++
  • C++ and object formats
  • C++ exception handling
  • C++ scope resolution
  • C++ support, not in COFF
  • C++ symbol decoding style
  • C++ symbol display
  • C-L
  • C-x 1
  • C-x 2
  • C-x A
  • C-x a
  • C-x C-a
  • call
  • call overloaded functions
  • call stack
  • call-last-kbd-macro (C-x e)
  • calling functions
  • calling make
  • capitalize-word (M-c)
  • casts, to view memory
  • catch
  • catch catch
  • catch exceptions, list active handlers
  • catch exec
  • catch fork
  • catch load
  • catch throw
  • catch unload
  • catch vfork
  • catchpoints
  • catchpoints, setting
  • cd
  • cdir
  • character-search (C-])
  • character-search-backward (M-C-])
  • checks, range
  • checks, type
  • checksum, for GDB remote
  • Chill
  • choosing target byte order
  • clear
  • clear-screen (C-l)
  • clearing breakpoints, watchpoints, catchpoints
  • COFF versus C++
  • collect (tracepoints)
  • collected data discarded
  • colon, doubled as scope operator
  • colon-colon, context for variables/functions
  • command editing
  • command files
  • command hooks
  • command line editing
  • commands, commands
  • commands for C++
  • commands to STDBUG (ST2000)
  • comment
  • comment-begin
  • compatibility, GDB/MI and CLI
  • compilation directory
  • compiling, on Sparclet
  • complete
  • complete (TAB)
  • completion
  • completion of quoted strings
  • completion-query-items
  • condition
  • conditional breakpoints
  • configuring GDB
  • confirmation
  • connect (to STDBUG)
  • console output in GDB/MI
  • continue
  • continuing
  • continuing threads
  • control C, and remote debugging
  • controlling terminal
  • convenience variables
  • convenience variables for tracepoints
  • convert-meta
  • copy-backward-word ()
  • copy-forward-word ()
  • copy-region-as-kill ()
  • core
  • core dump file
  • core-file
  • crash of debugger
  • current directory
  • current stack frame
  • current thread
  • cwd

    • d

  • d (delete)
  • data manipulation, in GDB/MI
  • debugger crash
  • debugging optimized code
  • debugging stub, example
  • debugging target
  • define
  • delete
  • delete breakpoints
  • delete display
  • delete mem
  • delete tracepoint
  • delete-char (C-d)
  • delete-char-or-list ()
  • delete-horizontal-space ()
  • deleting breakpoints, watchpoints, catchpoints
  • demangling
  • descriptor tables display
  • detach
  • device
  • digit-argument (M-0, M-1, ... M--)
  • dir
  • direct memory access (DMA) on MS-DOS
  • directories for source files
  • directory
  • directory, compilation
  • directory, current
  • dis (disable)
  • disable
  • disable breakpoints, disable breakpoints
  • disable display
  • disable mem
  • disable tracepoint
  • disable-completion
  • disassemble
  • display
  • display of expressions
  • display-begin
  • display-end
  • display-expression
  • display-expression-end
  • display-format
  • display-number-end
  • display-value
  • DJGPP debugging
  • do (down)
  • do-uppercase-version (M-a, M-b, M-x, ...)
  • document
  • documentation
  • Down
  • down
  • down-silently
  • downcase-word (M-l)
  • download to H8/300 or H8/500
  • download to Hitachi SH
  • download to Nindy-960
  • download to Sparclet
  • download to VxWorks
  • dump all data collected at tracepoint
  • dump-functions ()
  • dump-macros ()
  • dump-variables ()
  • dynamic linking

    • e

  • `eb.log', a log file for EB29K
  • EB29K board
  • EBMON
  • echo
  • ECOFF and C++
  • editing
  • editing command lines
  • editing-mode
  • ELF/DWARF and C++
  • ELF/stabs and C++
  • else
  • elt
  • elt-rep
  • elt-rep-end
  • Emacs
  • enable
  • enable breakpoints, enable breakpoints
  • enable display
  • enable mem
  • enable tracepoint
  • enable-keypad
  • end
  • end-kbd-macro (C-x ))
  • end-of-history (M-&#62;)
  • end-of-line (C-e)
  • entering numbers
  • environment (of your program)
  • error
  • error on valid input
  • error-begin
  • event designators
  • event handling
  • examining data
  • examining memory
  • exception handlers
  • exception handlers, how to list
  • exceptionHandler
  • exchange-point-and-mark (C-x C-x)
  • exec-file
  • executable file
  • exited
  • exiting GDB
  • expand-tilde
  • expressions
  • expressions in C or C++
  • expressions in C++
  • expressions in Modula-2

    • f

  • f (frame)
  • fatal signal
  • fatal signals
  • fg (resume foreground execution)
  • field
  • field-begin
  • field-end
  • field-name-end
  • field-value
  • file
  • find trace snapshot
  • finish
  • flinching
  • floating point
  • floating point registers
  • floating point, MIPS remote
  • flush_i_cache
  • focus
  • focus of debugging
  • foo
  • fork, debugging programs which call
  • format options
  • formatted output
  • Fortran
  • forward-backward-delete-char ()
  • forward-char (C-f)
  • forward-search
  • forward-search-history (C-s)
  • forward-word (M-f)
  • frame number
  • frame pointer
  • frame, command
  • frame, definition
  • frame, selecting
  • frame-address
  • frame-address-end
  • frame-args
  • frame-begin
  • frame-end
  • frame-function-name
  • frame-source-begin
  • frame-source-end
  • frame-source-file
  • frame-source-file-end
  • frame-source-line
  • frame-where
  • frameless execution
  • frames-invalid
  • free memory information (MS-DOS)
  • Fujitsu
  • function-call
  • functions without line info, and stepping

    • g

  • g++, GNU C++ compiler
  • garbled pointers
  • GDB bugs, reporting
  • GDB reference card
  • `gdb.ini'
  • GDB/MI, breakpoint commands
  • GDB/MI, compatibility with CLI
  • GDB/MI, data manipulation
  • GDB/MI, input syntax
  • GDB/MI, its purpose
  • GDB/MI, out-of-band records
  • GDB/MI, output syntax
  • GDB/MI, result records
  • GDB/MI, simple examples
  • GDB/MI, stream records
  • GDBHISTFILE
  • gdbserve.nlm
  • gdbserver
  • GDT
  • getDebugChar
  • GNU C++
  • GNU Emacs

    • h

  • h (help)
  • H8/300 or H8/500 download
  • handle
  • handle_exception
  • handling signals
  • hardware watchpoints
  • hbreak
  • help
  • help target
  • help user-defined
  • heuristic-fence-post (Alpha, MIPS)
  • history events
  • history expansion, history expansion
  • history file
  • history number
  • history save
  • history size
  • history substitution
  • history-search-backward ()
  • history-search-forward ()
  • Hitachi
  • Hitachi SH download
  • hook
  • hook-
  • hookpost
  • hookpost-
  • hooks, for commands
  • hooks, post-command
  • hooks, pre-command
  • horizontal-scroll-mode

    • i

  • i (info)
  • i/o
  • i386
  • `i386-stub.c'
  • i960
  • IDT
  • if
  • ignore
  • ignore count (of breakpoint)
  • INCLUDE_RDB
  • info
  • info address
  • info all-registers
  • info args
  • info breakpoints
  • info catch
  • info display
  • info dos
  • info extensions
  • info f (info frame)
  • info files
  • info float
  • info frame
  • info frame, show the source language
  • info functions
  • info line
  • info locals
  • info mem
  • info proc
  • info proc id
  • info proc mappings
  • info proc status
  • info proc times
  • info program
  • info registers
  • info s (info stack)
  • info scope
  • info set
  • info share
  • info sharedlibrary
  • info signals
  • info source
  • info source, show the source language
  • info sources
  • info stack
  • info symbol
  • info target
  • info terminal
  • info threads, info threads
  • info tracepoints
  • info types
  • info variables
  • info watchpoints
  • information about tracepoints
  • inheritance
  • init file
  • init file name
  • initial frame
  • initialization file, readline
  • innermost frame
  • input syntax for GDB/MI
  • input-meta
  • insert-comment (M-#)
  • insert-completions (M-*)
  • inspect
  • installation
  • instructions, assembly, instructions, assembly
  • Intel
  • Intel disassembly flavor
  • interaction, readline
  • internal GDB breakpoints
  • interrupt
  • interrupting remote programs
  • interrupting remote targets
  • invalid input
  • isearch-terminators

    • j

  • jump

    • k

  • kernel object
  • kernel object display
  • keymap
  • kill
  • kill ring
  • kill-line (C-k)
  • kill-region ()
  • kill-whole-line ()
  • kill-word (M-d)
  • killing text
  • KOD

    • l

  • l (list)
  • languages
  • last tracepoint number
  • latest breakpoint
  • layout asm
  • layout next
  • layout prev
  • layout regs
  • layout split
  • layout src
  • LDT
  • leaving GDB
  • Left
  • linespec
  • list
  • list output in GDB/MI
  • listing machine instructions, listing machine instructions
  • load filename
  • local variables
  • locate address
  • log file for EB29K
  • log output in GDB/MI

    • m

  • m680x0
  • `m68k-stub.c'
  • machine instructions, machine instructions
  • maint info breakpoints
  • maint print psymbols
  • maint print symbols
  • make
  • mapped
  • mark-modified-lines
  • mem
  • member functions
  • memory models, H8/500
  • memory region attributes
  • memory tracing
  • memory, viewing as typed object
  • memory-mapped symbol file
  • memset
  • menu-complete ()
  • meta-flag
  • MIPS boards
  • MIPS remote floating point
  • MIPS remotedebug protocol
  • MIPS stack
  • Modula-2
  • Modula-2 built-ins
  • Modula-2 checks
  • Modula-2 constants
  • Modula-2 defaults
  • Modula-2 operators
  • Modula-2, deviations from
  • Modula-2, GDB support
  • Motorola 680x0
  • MS-DOS system info
  • MS-DOS-specific commands
  • multiple processes
  • multiple targets
  • multiple threads

    • n

  • n (next)
  • names of symbols
  • namespace in C++
  • native DJGPP debugging
  • negative breakpoint numbers
  • New systag message
  • New systag message, on HP-UX
  • next
  • next-history (C-n)
  • nexti
  • ni (nexti)
  • Nindy
  • non-incremental-forward-search-history (M-n)
  • non-incremental-reverse-search-history (M-p)
  • notation, readline
  • notational conventions, for GDB/MI
  • notify output in GDB/MI
  • number representation
  • numbers for breakpoints

    • o

  • object formats and C++
  • online documentation
  • optimized code, debugging
  • out-of-band records in GDB/MI
  • outermost frame
  • output
  • output formats
  • output syntax of GDB/MI
  • output-meta
  • overload-choice
  • overloaded functions, calling
  • overloaded functions, overload resolution
  • overloading
  • overloading in C++

    • p

  • packets, reporting on stdout
  • page tables display (MS-DOS)
  • partial symbol dump
  • Pascal
  • passcount
  • patching binaries
  • path
  • pauses in output
  • PgDn
  • PgUp
  • physical address from linear address
  • pipes
  • pointer, finding referent
  • possible-completions (M-?)
  • post-commands
  • post-overload-choice
  • post-prompt
  • post-prompt-for-continue
  • post-query
  • pre-commands
  • pre-overload-choice
  • pre-prompt
  • pre-prompt-for-continue
  • pre-query
  • prefix-meta (ESC)
  • previous-history (C-p)
  • print
  • print settings
  • printf
  • printing data
  • process image
  • processes, multiple
  • prompt, prompt
  • prompt-for-continue
  • protocol, GDB remote serial
  • ptype
  • putDebugChar
  • pwd

    • q

  • q (quit)
  • query
  • quit
  • quit [expression]
  • quoted-insert (C-q, C-v)
  • quotes in commands
  • quoting names

    • r

  • r (run)
  • raise exceptions
  • range checking
  • ranges of breakpoints
  • rbreak
  • re-read-init-file (C-x C-r)
  • reading symbols immediately
  • readline
  • readnow
  • recent tracepoint number
  • record
  • redirection
  • redraw-current-line ()
  • reference card
  • reference declarations
  • refresh
  • register stack, AMD29K
  • registers
  • regular expression
  • reloading symbols
  • remote connection without stubs
  • remote debugging
  • remote programs, interrupting
  • remote serial debugging summary
  • remote serial debugging, overview
  • remote serial protocol
  • remote serial stub
  • remote serial stub list
  • remote serial stub, initialization
  • remote serial stub, main routine
  • remote stub, example
  • remote stub, support routines
  • remotedebug, MIPS protocol
  • remotetimeout
  • remove actions from a tracepoint
  • repeating commands
  • reporting bugs in GDB
  • reset
  • response time, MIPS debugging
  • result records in GDB/MI
  • resuming execution
  • RET (repeat last command)
  • retransmit-timeout, MIPS protocol
  • return
  • returning from a function
  • reverse-search
  • reverse-search-history (C-r)
  • revert-line (M-r)
  • Right
  • run
  • running
  • running 29K programs
  • running and debugging Sparclet programs
  • running VxWorks tasks
  • running, on Sparclet
  • rwatch

    • s

  • s (step)
  • save tracepoints for future sessions
  • save-tracepoints
  • saving symbol table
  • scope
  • search
  • searching
  • section
  • segment descriptor tables
  • select trace snapshot
  • select-frame
  • selected frame
  • selecting frame silently
  • self-insert (a, b, A, 1, !, ...)
  • sequence-id, for GDB remote
  • serial connections, debugging
  • serial device, Hitachi micros
  • serial line speed, Hitachi micros
  • serial line, target remote
  • serial protocol, GDB remote
  • server prefix for annotations
  • set
  • set args
  • set auto-solib-add
  • set check range
  • set check type
  • set check, range
  • set check, type
  • set complaints
  • set confirm
  • set debug arch
  • set debug event
  • set debug expression
  • set debug overload
  • set debug remote
  • set debug serial
  • set debug target
  • set debug varobj
  • set demangle-style
  • set disassembly-flavor
  • set editing
  • set endian auto
  • set endian big
  • set endian little
  • set environment
  • set extension-language
  • set follow-fork-mode
  • set gnutarget
  • set height
  • set history expansion
  • set history filename
  • set history save
  • set history size
  • set input-radix
  • set language
  • set listsize
  • set machine
  • set memory mod
  • set mipsfpu
  • set opaque-type-resolution
  • set output-radix
  • set overload-resolution
  • set print address
  • set print array
  • set print asm-demangle
  • set print demangle
  • set print elements
  • set print max-symbolic-offset
  • set print null-stop
  • set print object
  • set print pretty
  • set print sevenbit-strings
  • set print static-members
  • set print symbol-filename
  • set print union
  • set print vtbl
  • set processor args
  • set prompt
  • set remotedebug, MIPS protocol
  • set retransmit-timeout
  • set rstack_high_address
  • set step-mode
  • set symbol-reloading
  • set timeout
  • set tracepoint
  • set tui active-border-mode
  • set tui border-kind
  • set tui border-mode
  • set variable
  • set verbose
  • set width
  • set write
  • set-mark (C-@)
  • set_debug_traps
  • setting variables
  • setting watchpoints
  • SH
  • `sh-stub.c'
  • share
  • shared libraries
  • sharedlibrary
  • shell
  • shell escape
  • show
  • show args
  • show auto-solib-add
  • show check range
  • show check type
  • show complaints
  • show confirm
  • show convenience
  • show copying
  • show debug arch
  • show debug event
  • show debug expression
  • show debug overload
  • show debug remote
  • show debug serial
  • show debug target
  • show debug varobj
  • show demangle-style
  • show directories
  • show editing
  • show environment
  • show gnutarget
  • show height
  • show history
  • show input-radix
  • show language
  • show listsize
  • show machine
  • show mipsfpu
  • show opaque-type-resolution
  • show output-radix
  • show paths
  • show print address
  • show print array
  • show print asm-demangle
  • show print demangle
  • show print elements
  • show print max-symbolic-offset
  • show print object
  • show print pretty
  • show print sevenbit-strings
  • show print static-members
  • show print symbol-filename
  • show print union
  • show print vtbl
  • show processor
  • show prompt
  • show remotedebug, MIPS protocol
  • show retransmit-timeout
  • show rstack_high_address
  • show symbol-reloading
  • show timeout
  • show user
  • show values
  • show verbose
  • show version
  • show warranty
  • show width
  • show write
  • show-all-if-ambiguous
  • shows
  • si (stepi)
  • signal, signal
  • signal-handler-caller
  • signal-name
  • signal-name-end
  • signal-string
  • signal-string-end
  • signalled
  • signals
  • silent
  • sim
  • simulator, Z8000
  • size of screen
  • software watchpoints
  • source, source
  • source path
  • Sparc
  • `sparc-stub.c'
  • `sparcl-stub.c'
  • Sparclet
  • SparcLite
  • speed
  • ST2000 auxiliary commands
  • st2000 cmd
  • stack frame
  • stack on Alpha
  • stack on MIPS
  • stack traces
  • stacking targets
  • start a new trace experiment
  • start-kbd-macro (C-x ()
  • starting, starting
  • status of trace data collection
  • status output in GDB/MI
  • STDBUG commands (ST2000)
  • step
  • stepi
  • stepping
  • stepping into functions with no line info
  • stop a running trace experiment
  • stop, a pseudo-command
  • stopped threads
  • stopping
  • stream records in GDB/MI
  • stub example, remote debugging
  • stupid questions
  • switching threads
  • switching threads automatically
  • symbol decoding style, C++
  • symbol dump
  • symbol from address
  • symbol names
  • symbol overloading
  • symbol table
  • symbol-file
  • symbols, reading immediately
  • sysinfo

    • t

  • tab-insert (M-TAB)
  • target
  • target abug
  • target adapt
  • target amd-eb
  • target array
  • target bug
  • target byte order
  • target core
  • target cpu32bug
  • target dbug
  • target ddb port
  • target dink32
  • target e7000, with H8/300
  • target e7000, with Hitachi ICE
  • target e7000, with Hitachi SH
  • target es1800
  • target est
  • target exec
  • target hms, and serial protocol
  • target hms, with H8/300
  • target hms, with Hitachi SH
  • target lsi port
  • target m32r
  • target mips port
  • target mon960
  • target nindy
  • target nrom
  • target op50n
  • target output in GDB/MI
  • target pmon port
  • target ppcbug
  • target ppcbug1
  • target r3900
  • target rdi
  • target rdp
  • target remote
  • target rom68k
  • target rombug
  • target sds
  • target sh3, with H8/300
  • target sh3, with SH
  • target sh3e, with H8/300
  • target sh3e, with SH
  • target sim
  • target sim, with Z8000
  • target sparclite
  • target vxworks
  • target w89k
  • tbreak
  • TCP port, target remote
  • tdump
  • terminal
  • tfind
  • thbreak
  • this, inside C++ member functions
  • thread apply
  • thread breakpoints
  • thread identifier (GDB), thread identifier (GDB)
  • thread identifier (system)
  • thread identifier (system), on HP-UX
  • thread number, thread number
  • thread threadno
  • threads and watchpoints
  • threads of execution
  • threads, automatic switching
  • threads, continuing
  • threads, stopped
  • tilde-expand (M-~)
  • timeout, MIPS protocol
  • trace
  • trace experiment, status of
  • tracebacks
  • tracepoint actions
  • tracepoint data, display
  • tracepoint deletion
  • tracepoint number
  • tracepoint pass count
  • tracepoint variables
  • tracepoints
  • transpose-chars (C-t)
  • transpose-words (M-t)
  • tstart
  • tstatus
  • tstop
  • tty
  • TUI
  • TUI commands
  • TUI configuration variables
  • TUI key bindings
  • type casting memory
  • type checking
  • type conversions in C++

    • u

  • u (until)
  • UDI
  • udi
  • undisplay
  • undo (C-_, C-x C-u)
  • universal-argument ()
  • unix-line-discard (C-u)
  • unix-word-rubout (C-w)
  • unknown address, locating
  • unset environment
  • until
  • Up
  • up
  • up-silently
  • upcase-word (M-u)
  • update
  • user-defined command

    • v

  • value history
  • value-begin
  • value-end
  • value-history-begin
  • value-history-end
  • value-history-value
  • variable name conflict
  • variable objects in GDB/MI
  • variable values, wrong
  • variables, setting
  • version number
  • visible-stats
  • VxWorks
  • vxworks-timeout

    • w

  • watch
  • watchpoint
  • watchpoints
  • watchpoints and threads
  • whatis
  • where
  • while
  • while-stepping (tracepoints)
  • wild pointer, interpreting
  • winheight
  • word completion
  • working directory
  • working directory (of your program)
  • working language
  • writing into corefiles
  • writing into executables
  • wrong values

    • x

  • x (examine memory)
  • x(examine), and info line
  • XCOFF and C++

    • y

  • yank (C-y)
  • yank-last-arg (M-., M-_)
  • yank-nth-arg (M-C-y)
  • yank-pop (M-y)
  • yanking text

    • z

  • Z8000
  • Zilog Z8000 simulator

    • {

  • {type}
    • @contents

    Footnotes

    (1)

    GDB built with DJGPP tools for MS-DOS/MS-Windows supports this mode of operation, but the event loop is suspended when the debuggee runs.

    (2)

    `b' cannot be used because these format letters are also used with the x command, where `b' stands for "byte"; see section Examining memory.

    (3)

    This is a way of removing one word from the stack, on machines where stacks grow downward in memory (most machines, nowadays). This assumes that the innermost stack frame is selected; setting $sp is not allowed when other stack frames are selected. To pop entire frames off the stack, regardless of machine architecture, use return; see section Returning from a function.

    (4)

    If a procedure call is used for instance in an expression, then this procedure is called with all its side effects. This can lead to confusing results if used carelessly.

    (5)

    If you choose a port number that conflicts with another service, gdbserver prints an error message and exits.

    (6)

    On DOS/Windows systems, the home directory is the one pointed to by the HOME environment variable.

    (7)

    In `gdb-5.1.1/gdb/refcard.ps' of the version 5.1.1 release.

    (8)

    If you have a more recent version of GDB than 5.1.1, look at the `README' file in the sources; we may have improved the installation procedures since publishing this manual.

    This document was generated on 14 February 2002 using texi2html 1.56k.


GNU

GNU gettext utilities

1. Introduction
2. PO Files and PO Mode Basics
3. Preparing Program Sources
4. Making the PO Template File
5. Creating a New PO File
6. Updating Existing PO Files
7. Manipulating PO Files
8. Producing Binary MO Files
9. The User's View
10. The Programmer's View
11. The Translator's View
12. The Maintainer's View
13. Other Programming Languages
14. Concluding Remarks

A. Language Codes | ISO 639 language codes
B. Country Codes | ISO 3166 country codes

Program Index | Index of Programs
Option Index | Index of Command-Line Options
Variable Index | Index of Environment Variables
PO Mode Index | Index of Emacs PO Mode Commands
Autoconf Macro Index | Index of Autoconf Macros
General Index

-- The Detailed Node Listing ---

Introduction

1.1 The Purpose of GNU gettext
1.2 I18n, L10n, and Such
1.3 Aspects in Native Language Support
1.4 Files Conveying Translations
1.5 Overview of GNU gettext

PO Files and PO Mode Basics

2.1 Completing GNU gettext Installation
2.2 The Format of PO Files
2.3 Main PO mode Commands Main Commands
2.4 Entry Positioning
2.5 Normalizing Strings in Entries

Preparing Program Sources

3.1 Triggering gettext Operations
3.2 Preparing Translatable Strings
3.3 How Marks Appear in Sources
3.4 Marking Translatable Strings
3.5 Special Comments preceding Keywords Telling something about the following string
3.6 Special Cases of Translatable Strings

Making the PO Template File

4.1 Invoking the xgettext Program

Creating a New PO File

5.1 Invoking the msginit Program
5.2 Filling in the Header Entry

Updating Existing PO Files

6.1 Invoking the msgmerge Program
6.2 Translated Entries
6.3 Fuzzy Entries
6.4 Untranslated Entries
6.5 Obsolete Entries
6.6 Modifying Translations
6.7 Modifying Comments
6.8 Details of Sub Edition Mode for Editing Translations
6.9 C Sources Context
6.10 Consulting Auxiliary PO Files
6.11 Using Translation Compendia

Using Translation Compendia

6.11.1 Creating Compendia | Merging translations for later use
6.11.2 Using Compendia | Using older translations if they fit

Manipulating PO Files

7.1 Invoking the msgcat Program
7.2 Invoking the msgconv Program
7.3 Invoking the msggrep Program
7.4 Invoking the msgfilter Program
7.5 Invoking the msguniq Program
7.6 Invoking the msgcomm Program
7.7 Invoking the msgcmp Program
7.8 Invoking the msgattrib Program
7.9 Invoking the msgen Program
7.10 Invoking the msgexec Program

Producing Binary MO Files

8.1 Invoking the msgfmt Program
8.2 Invoking the msgunfmt Program
8.3 The Format of GNU MO Files

The User's View

9.1 The Current `ABOUT-NLS' Matrix
9.2 Magic for Installers
9.3 Magic for End Users

The Programmer's View

10.1 About catgets
10.2 About gettext
10.3 Comparing the Two Interfaces Comparing the two interfaces
10.4 Using libintl.a in own programs
10.5 Being a gettext grok
10.6 Temporary Notes for the Programmers Chapter

About catgets

10.1.1 The Interface | The interface
10.1.2 Problems with the catgets Interface?! | Problems with the catgets interface?!

About gettext

10.2.1 The Interface | The interface
10.2.2 Solving Ambiguities | Solving ambiguities
10.2.3 Locating Message Catalog Files | Locating message catalog files
10.2.4 How to specify the output character set gettext uses | How to request conversion to Unicode
10.2.5 Additional functions for plural forms | Additional functions for handling plurals
10.2.6 How to use gettext in GUI programs | Another technique for solving ambiguities
10.2.7 Optimization of the *gettext functions

Temporary Notes for the Programmers Chapter

10.6.1 Temporary - Two Possible Implementations
10.6.2 Temporary - About catgets
10.6.3 Temporary - Why a single implementation
10.6.4 Temporary - Notes

The Translator's View

11.1 Introduction 0
11.2 Introduction 1
11.3 Discussions
11.4 Organization
11.5 Information Flow

Organization

11.4.1 Central Coordination
11.4.2 National Teams
11.4.3 Mailing Lists

National Teams

11.4.2.1 Sub-Cultures
11.4.2.2 Organizational Ideas

The Maintainer's View

12.1 Flat or Non-Flat Directory Structures
12.2 Prerequisite Works
12.3 Invoking the gettextize Program
12.4 Files You Must Create or Alter
12.5 Autoconf macros for use in `configure.in'

Files You Must Create or Alter

12.4.1 `POTFILES.in' in `po/'
12.4.2 `LINGUAS' in `po/'
12.4.3 `Makefile' pieces in `po/'
12.4.4 `configure.in' at top level
12.4.5 `config.guess', `config.sub' at top level
12.4.6 `aclocal.m4' at top level
12.4.7 `acconfig.h' at top level
12.4.8 `Makefile.in' at top level
12.4.9 `Makefile.in' in `src/'
12.4.10 `gettext.h' in `lib/'

Autoconf macros for use in `configure.in'

12.5.1 AM_GNU_GETTEXT in `gettext.m4'
12.5.2 AM_ICONV in `iconv.m4'

Other Programming Languages

13.1 The Language Implementor's View
13.2 The Programmer's View
13.3 The Translator's View
13.4 The Maintainer's View
13.5 Individual Programming Languages
13.6 Internationalizable Data

Individual Programming Languages

13.5.1 C, C++, Objective C
13.5.2 sh - Shell Script
13.5.3 bash - Bourne-Again Shell Script
13.5.4 Python
13.5.5 GNU clisp - Common Lisp
13.5.6 GNU clisp C sources
13.5.7 Emacs Lisp
13.5.8 librep
13.5.9 GNU Smalltalk
13.5.10 Java
13.5.11 GNU awk
13.5.12 Pascal - Free Pascal Compiler
13.5.13 wxWindows library
13.5.14 YCP - YaST2 scripting language
13.5.15 Tcl - Tk's scripting language
13.5.16 Perl
13.5.17 PHP Hypertext Preprocessor
13.5.18 Pike

Internationalizable Data

13.6.1 POT - Portable Object Template
13.6.2 Resource String Table
13.6.3 Glade - GNOME user interface description

Concluding Remarks

14.1 History of GNU gettext
14.2 Related Readings

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Introduction

This manual is still in DRAFT state. Some sections are still empty, or almost. We keep merging material from other sources (essentially e-mail folders) while the proper integration of this material is delayed.

In this manual, we use he when speaking of the programmer or maintainer, she when speaking of the translator, and they when speaking of the installers or end users of the translated program. This is only a convenience for clarifying the documentation. It is absolutely not meant to imply that some roles are more appropriate to males or females. Besides, as you might guess, GNU gettext is meant to be useful for people using computers, whatever their sex, race, religion or nationality!

This chapter explains the goals sought in the creation of GNU gettext and the free Translation Project. Then, it explains a few broad concepts around Native Language Support, and positions message translation with regard to other aspects of national and cultural variance, as they apply to to programs. It also surveys those files used to convey the translations. It explains how the various tools interact in the initial generation of these files, and later, how the maintenance cycle should usually operate.

Please send suggestions and corrections to:

Internet address:
    bug-gnu-gettext@gnu.org

Please include the manual's edition number and update date in your messages.

1.1 The Purpose of GNU gettext
1.2 I18n, L10n, and Such
1.3 Aspects in Native Language Support
1.4 Files Conveying Translations
1.5 Overview of GNU gettext

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.1 The Purpose of GNU gettext

Usually, programs are written and documented in English, and use English at execution time to interact with users. This is true not only of GNU software, but also of a great deal of commercial and free software. Using a common language is quite handy for communication between developers, maintainers and users from all countries. On the other hand, most people are less comfortable with English than with their own native language, and would prefer to use their mother tongue for day to day's work, as far as possible. Many would simply love to see their computer screen showing a lot less of English, and far more of their own language.

However, to many people, this dream might appear so far fetched that they may believe it is not even worth spending time thinking about it. They have no confidence at all that the dream might ever become true. Yet some have not lost hope, and have organized themselves. The Translation Project is a formalization of this hope into a workable structure, which has a good chance to get all of us nearer the achievement of a truly multi-lingual set of programs.

GNU gettext is an important step for the Translation Project, as it is an asset on which we may build many other steps. This package offers to programmers, translators and even users, a well integrated set of tools and documentation. Specifically, the GNU gettext utilities are a set of tools that provides a framework within which other free packages may produce multi-lingual messages. These tools include

  • A set of conventions about how programs should be written to support message catalogs.

  • A directory and file naming organization for the message catalogs themselves.

  • A runtime library supporting the retrieval of translated messages.

  • A few stand-alone programs to massage in various ways the sets of translatable strings, or already translated strings.

  • A special mode for Emacs(1) which helps preparing these sets and bringing them up to date.

GNU gettext is designed to minimize the impact of internationalization on program sources, keeping this impact as small and hardly noticeable as possible. Internationalization has better chances of succeeding if it is very light weighted, or at least, appear to be so, when looking at program sources.

The Translation Project also uses the GNU gettext distribution as a vehicle for documenting its structure and methods. This goes beyond the strict technicalities of documenting the GNU gettext proper. By so doing, translators will find in a single place, as far as possible, all they need to know for properly doing their translating work. Also, this supplemental documentation might also help programmers, and even curious users, in understanding how GNU gettext is related to the remainder of the Translation Project, and consequently, have a glimpse at the big picture.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.2 I18n, L10n, and Such

Two long words appear all the time when we discuss support of native language in programs, and these words have a precise meaning, worth being explained here, once and for all in this document. The words are internationalization and localization. Many people, tired of writing these long words over and over again, took the habit of writing i18n and l10n instead, quoting the first and last letter of each word, and replacing the run of intermediate letters by a number merely telling how many such letters there are. But in this manual, in the sake of clarity, we will patiently write the names in full, each time...

By internationalization, one refers to the operation by which a program, or a set of programs turned into a package, is made aware of and able to support multiple languages. This is a generalization process, by which the programs are untied from calling only English strings or other English specific habits, and connected to generic ways of doing the same, instead. Program developers may use various techniques to internationalize their programs. Some of these have been standardized. GNU gettext offers one of these standards. See section 10. The Programmer's View.

By localization, one means the operation by which, in a set of programs already internationalized, one gives the program all needed information so that it can adapt itself to handle its input and output in a fashion which is correct for some native language and cultural habits. This is a particularisation process, by which generic methods already implemented in an internationalized program are used in specific ways. The programming environment puts several functions to the programmers disposal which allow this runtime configuration. The formal description of specific set of cultural habits for some country, together with all associated translations targeted to the same native language, is called the locale for this language or country. Users achieve localization of programs by setting proper values to special environment variables, prior to executing those programs, identifying which locale should be used.

In fact, locale message support is only one component of the cultural data that makes up a particular locale. There are a whole host of routines and functions provided to aid programmers in developing internationalized software and which allow them to access the data stored in a particular locale. When someone presently refers to a particular locale, they are obviously referring to the data stored within that particular locale. Similarly, if a programmer is referring to "accessing the locale routines", they are referring to the complete suite of routines that access all of the locale's information.

One uses the expression Native Language Support, or merely NLS, for speaking of the overall activity or feature encompassing both internationalization and localization, allowing for multi-lingual interactions in a program. In a nutshell, one could say that internationalization is the operation by which further localizations are made possible.

Also, very roughly said, when it comes to multi-lingual messages, internationalization is usually taken care of by programmers, and localization is usually taken care of by translators.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.3 Aspects in Native Language Support

For a totally multi-lingual distribution, there are many things to translate beyond output messages.

  • As of today, GNU gettext offers a complete toolset for translating messages output by C programs. Perl scripts and shell scripts will also need to be translated. Even if there are today some hooks by which this can be done, these hooks are not integrated as well as they should be.

  • Some programs, like autoconf or bison, are able to produce other programs (or scripts). Even if the generating programs themselves are internationalized, the generated programs they produce may need internationalization on their own, and this indirect internationalization could be automated right from the generating program. In fact, quite usually, generating and generated programs could be internationalized independently, as the effort needed is fairly orthogonal.

  • A few programs include textual tables which might need translation themselves, independently of the strings contained in the program itself. For example, RFC 1345 gives an English description for each character which the recode program is able to reconstruct at execution. Since these descriptions are extracted from the RFC by mechanical means, translating them properly would require a prior translation of the RFC itself.

  • Almost all programs accept options, which are often worded out so to be descriptive for the English readers; one might want to consider offering translated versions for program options as well.

  • Many programs read, interpret, compile, or are somewhat driven by input files which are texts containing keywords, identifiers, or replies which are inherently translatable. For example, one may want gcc to allow diacriticized characters in identifiers or use translated keywords; `rm -i' might accept something else than `y' or `n' for replies, etc. Even if the program will eventually make most of its output in the foreign languages, one has to decide whether the input syntax, option values, etc., are to be localized or not.

  • The manual accompanying a package, as well as all documentation files in the distribution, could surely be translated, too. Translating a manual, with the intent of later keeping up with updates, is a major undertaking in itself, generally.

As we already stressed, translation is only one aspect of locales. Other internationalization aspects are system services and are handled in GNU libc. There are many attributes that are needed to define a country's cultural conventions. These attributes include beside the country's native language, the formatting of the date and time, the representation of numbers, the symbols for currency, etc. These local rules are termed the country's locale. The locale represents the knowledge needed to support the country's native attributes.

There are a few major areas which may vary between countries and hence, define what a locale must describe. The following list helps putting multi-lingual messages into the proper context of other tasks related to locales. See the GNU libc manual for details.

Characters and Codesets

The codeset most commonly used through out the USA and most English speaking parts of the world is the ASCII codeset. However, there are many characters needed by various locales that are not found within this codeset. The 8-bit ISO 8859-1 code set has most of the special characters needed to handle the major European languages. However, in many cases, the ISO 8859-1 font is not adequate: it doesn't even handle the major European currency. Hence each locale will need to specify which codeset they need to use and will need to have the appropriate character handling routines to cope with the codeset.

Currency

The symbols used vary from country to country as does the position used by the symbol. Software needs to be able to transparently display currency figures in the native mode for each locale.

Dates

The format of date varies between locales. For example, Christmas day in 1994 is written as 12/25/94 in the USA and as 25/12/94 in Australia. Other countries might use ISO 8061 dates, etc.

Time of the day may be noted as hh:mm, hh.mm, or otherwise. Some locales require time to be specified in 24-hour mode rather than as AM or PM. Further, the nature and yearly extent of the Daylight Saving correction vary widely between countries.

Numbers

Numbers can be represented differently in different locales. For example, the following numbers are all written correctly for their respective locales:

12,345.67       English
12.345,67       German
 12345,67       French
1,2345.67       Asia

Some programs could go further and use different unit systems, like English units or Metric units, or even take into account variants about how numbers are spelled in full.

Messages

The most obvious area is the language support within a locale. This is where GNU gettext provides the means for developers and users to easily change the language that the software uses to communicate to the user.

Components of locale outside of message handling are standardized in the ISO C standard and the SUSV2 specification. GNU libc fully implements this, and most other modern systems provide a more or less reasonable support for at least some of the missing components.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.4 Files Conveying Translations

The letters PO in `.po' files means Portable Object, to distinguish it from `.mo' files, where MO stands for Machine Object. This paradigm, as well as the PO file format, is inspired by the NLS standard developed by Uniforum, and first implemented by Sun in their Solaris system.

PO files are meant to be read and edited by humans, and associate each original, translatable string of a given package with its translation in a particular target language. A single PO file is dedicated to a single target language. If a package supports many languages, there is one such PO file per language supported, and each package has its own set of PO files. These PO files are best created by the xgettext program, and later updated or refreshed through the msgmerge program. Program xgettext extracts all marked messages from a set of C files and initializes a PO file with empty translations. Program msgmerge takes care of adjusting PO files between releases of the corresponding sources, commenting obsolete entries, initializing new ones, and updating all source line references. Files ending with `.pot' are kind of base translation files found in distributions, in PO file format.

MO files are meant to be read by programs, and are binary in nature. A few systems already offer tools for creating and handling MO files as part of the Native Language Support coming with the system, but the format of these MO files is often different from system to system, and non-portable. The tools already provided with these systems don't support all the features of GNU gettext. Therefore GNU gettext uses its own format for MO files. Files ending with `.gmo' are really MO files, when it is known that these files use the GNU format.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.5 Overview of GNU gettext

The following diagram summarizes the relation between the files handled by GNU gettext and the tools acting on these files. It is followed by somewhat detailed explanations, which you should read while keeping an eye on the diagram. Having a clear understanding of these interrelations will surely help programmers, translators and maintainers.

Original C Sources ---> PO mode ---> Marked C Sources ---.
                                                         |
              .---------<--- GNU gettext Library         |
.--- make <---+                                          |
|             `---------<--------------------+-----------'
|                                            |
|   .-----<--- PACKAGE.pot <--- xgettext <---'   .---<--- PO Compendium
|   |                                            |             ^
|   |                                            `---.         |
|   `---.                                            +---> PO mode ---.
|       +----> msgmerge ------> LANG.po ---->--------'                |
|   .---'                                                             |
|   |                                                                 |
|   `-------------<---------------.                                   |
|                                 +--- New LANG.po <------------------'
|   .--- LANG.gmo <--- msgfmt <---'
|   |
|   `---> install ---> /.../LANG/PACKAGE.mo ---.
|                                              +---> "Hello world!"
`-------> install ---> /.../bin/PROGRAM -------'

The indication `PO mode' appears in two places in this picture, and you may safely read it as merely meaning "hand editing", using any editor of your choice, really. However, for those of you being the lucky users of Emacs, PO mode has been specifically created for providing a cozy environment for editing or modifying PO files. While editing a PO file, PO mode allows for the easy browsing of auxiliary and compendium PO files, as well as for following references into the set of C program sources from which PO files have been derived. It has a few special features, among which are the interactive marking of program strings as translatable, and the validatation of PO files with easy repositioning to PO file lines showing errors.

As a programmer, the first step to bringing GNU gettext into your package is identifying, right in the C sources, those strings which are meant to be translatable, and those which are untranslatable. This tedious job can be done a little more comfortably using emacs PO mode, but you can use any means familiar to you for modifying your C sources. Beside this some other simple, standard changes are needed to properly initialize the translation library. See section 3. Preparing Program Sources, for more information about all this.

For newly written software the strings of course can and should be marked while writing it. The gettext approach makes this very easy. Simply put the following lines at the beginning of each file or in a central header file:

#define _(String) (String)
#define N_(String) String
#define textdomain(Domain)
#define bindtextdomain(Package, Directory)

Doing this allows you to prepare the sources for internationalization. Later when you feel ready for the step to use the gettext library simply replace these definitions by the following:

#include <libintl.h>
#define _(String) gettext (String)
#define gettext_noop(String) String
#define N_(String) gettext_noop (String)

and link against `libintl.a' or `libintl.so'. Note that on GNU systems, you don't need to link with libintl because the gettext library functions are already contained in GNU libc. That is all you have to change.

Once the C sources have been modified, the xgettext program is used to find and extract all translatable strings, and create a PO template file out of all these. This `package.pot' file contains all original program strings. It has sets of pointers to exactly where in C sources each string is used. All translations are set to empty. The letter t in `.pot' marks this as a Template PO file, not yet oriented towards any particular language. See section 4.1 Invoking the xgettext Program, for more details about how one calls the xgettext program. If you are really lazy, you might be interested at working a lot more right away, and preparing the whole distribution setup (see section 12. The Maintainer's View). By doing so, you spare yourself typing the xgettext command, as make should now generate the proper things automatically for you!

The first time through, there is no `lang.po' yet, so the msgmerge step may be skipped and replaced by a mere copy of `package.pot' to `lang.po', where lang represents the target language. See 5. Creating a New PO File for details.

Then comes the initial translation of messages. Translation in itself is a whole matter, still exclusively meant for humans, and whose complexity far overwhelms the level of this manual. Nevertheless, a few hints are given in some other chapter of this manual (see section 11. The Translator's View). You will also find there indications about how to contact translating teams, or becoming part of them, for sharing your translating concerns with others who target the same native language.

While adding the translated messages into the `lang.po' PO file, if you do not have Emacs handy, you are on your own for ensuring that your efforts fully respect the PO file format, and quoting conventions (see section 2.2 The Format of PO Files). This is surely not an impossible task, as this is the way many people have handled PO files already for Uniforum or Solaris. On the other hand, by using PO mode in Emacs, most details of PO file format are taken care of for you, but you have to acquire some familiarity with PO mode itself. Besides main PO mode commands (see section 2.3 Main PO mode Commands), you should know how to move between entries (see section 2.4 Entry Positioning), and how to handle untranslated entries (see section 6.4 Untranslated Entries).

If some common translations have already been saved into a compendium PO file, translators may use PO mode for initializing untranslated entries from the compendium, and also save selected translations into the compendium, updating it (see section 6.11 Using Translation Compendia). Compendium files are meant to be exchanged between members of a given translation team.

Programs, or packages of programs, are dynamic in nature: users write bug reports and suggestion for improvements, maintainers react by modifying programs in various ways. The fact that a package has already been internationalized should not make maintainers shy of adding new strings, or modifying strings already translated. They just do their job the best they can. For the Translation Project to work smoothly, it is important that maintainers do not carry translation concerns on their already loaded shoulders, and that translators be kept as free as possible of programming concerns.

The only concern maintainers should have is carefully marking new strings as translatable, when they should be, and do not otherwise worry about them being translated, as this will come in proper time. Consequently, when programs and their strings are adjusted in various ways by maintainers, and for matters usually unrelated to translation, xgettext would construct `package.pot' files which are evolving over time, so the translations carried by `lang.po' are slowly fading out of date.

It is important for translators (and even maintainers) to understand that package translation is a continuous process in the lifetime of a package, and not something which is done once and for all at the start. After an initial burst of translation activity for a given package, interventions are needed once in a while, because here and there, translated entries become obsolete, and new untranslated entries appear, needing translation.

The msgmerge program has the purpose of refreshing an already existing `lang.po' file, by comparing it with a newer `package.pot' template file, extracted by xgettext out of recent C sources. The refreshing operation adjusts all references to C source locations for strings, since these strings move as programs are modified. Also, msgmerge comments out as obsolete, in `lang.po', those already translated entries which are no longer used in the program sources (see section 6.5 Obsolete Entries). It finally discovers new strings and inserts them in the resulting PO file as untranslated entries (see section 6.4 Untranslated Entries). See section 6.1 Invoking the msgmerge Program, for more information about what msgmerge really does.

Whatever route or means taken, the goal is to obtain an updated `lang.po' file offering translations for all strings.

The temporal mobility, or fluidity of PO files, is an integral part of the translation game, and should be well understood, and accepted. People resisting it will have a hard time participating in the Translation Project, or will give a hard time to other participants! In particular, maintainers should relax and include all available official PO files in their distributions, even if these have not recently been updated, without exerting pressure on the translator teams to get the job done. The pressure should rather come from the community of users speaking a particular language, and maintainers should consider themselves fairly relieved of any concern about the adequacy of translation files. On the other hand, translators should reasonably try updating the PO files they are responsible for, while the package is undergoing pretest, prior to an official distribution.

Once the PO file is complete and dependable, the msgfmt program is used for turning the PO file into a machine-oriented format, which may yield efficient retrieval of translations by the programs of the package, whenever needed at runtime (see section 8.3 The Format of GNU MO Files). See section 8.1 Invoking the msgfmt Program, for more information about all modes of execution for the msgfmt program.

Finally, the modified and marked C sources are compiled and linked with the GNU gettext library, usually through the operation of make, given a suitable `Makefile' exists for the project, and the resulting executable is installed somewhere users will find it. The MO files themselves should also be properly installed. Given the appropriate environment variables are set (see section 9.3 Magic for End Users), the program should localize itself automatically, whenever it executes.

The remainder of this manual has the purpose of explaining in depth the various steps outlined above.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. PO Files and PO Mode Basics

The GNU gettext toolset helps programmers and translators at producing, updating and using translation files, mainly those PO files which are textual, editable files. This chapter stresses the format of PO files, and contains a PO mode starter. PO mode description is spread throughout this manual instead of being concentrated in one place. Here we present only the basics of PO mode.

2.1 Completing GNU gettext Installation
2.2 The Format of PO Files
2.3 Main PO mode Commands Main Commands
2.4 Entry Positioning
2.5 Normalizing Strings in Entries

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 Completing GNU gettext Installation

Once you have received, unpacked, configured and compiled the GNU gettext distribution, the `make install' command puts in place the programs xgettext, msgfmt, gettext, and msgmerge, as well as their available message catalogs. To top off a comfortable installation, you might also want to make the PO mode available to your Emacs users.

During the installation of the PO mode, you might want to modify your file `.emacs', once and for all, so it contains a few lines looking like:

(setq auto-mode-alist
      (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
(autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t)

Later, whenever you edit some `.po' file, or any file having the string `.po.' within its name, Emacs loads `po-mode.elc' (or `po-mode.el') as needed, and automatically activates PO mode commands for the associated buffer. The string PO appears in the mode line for any buffer for which PO mode is active. Many PO files may be active at once in a single Emacs session.

If you are using Emacs version 20 or newer, and have already installed the appropriate international fonts on your system, you may also tell Emacs how to determine automatically the coding system of every PO file. This will often (but not always) cause the necessary fonts to be loaded and used for displaying the translations on your Emacs screen. For this to happen, add the lines:

(modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
                            'po-find-file-coding-system)
(autoload 'po-find-file-coding-system "po-mode")

to your `.emacs' file. If, with this, you still see boxes instead of international characters, try a different font set (via Shift Mouse button 1).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 The Format of PO Files

A PO file is made up of many entries, each entry holding the relation between an original untranslated string and its corresponding translation. All entries in a given PO file usually pertain to a single project, and all translations are expressed in a single target language. One PO file entry has the following schematic structure:

white-space
#  translator-comments
#. automatic-comments
#: reference...
#, flag...
msgid untranslated-string
msgstr translated-string

The general structure of a PO file should be well understood by the translator. When using PO mode, very little has to be known about the format details, as PO mode takes care of them for her.

Entries begin with some optional white space. Usually, when generated through GNU gettext tools, there is exactly one blank line between entries. Then comments follow, on lines all starting with the character #. There are two kinds of comments: those which have some white space immediately following the #, which comments are created and maintained exclusively by the translator, and those which have some non-white character just after the #, which comments are created and maintained automatically by GNU gettext tools. All comments, of either kind, are optional.

After white space and comments, entries show two strings, namely first the untranslated string as it appears in the original program sources, and then, the translation of this string. The original string is introduced by the keyword msgid, and the translation, by msgstr. The two strings, untranslated and translated, are quoted in various ways in the PO file, using " delimiters and \ escapes, but the translator does not really have to pay attention to the precise quoting format, as PO mode fully takes care of quoting for her.

The msgid strings, as well as automatic comments, are produced and managed by other GNU gettext tools, and PO mode does not provide means for the translator to alter these. The most she can do is merely deleting them, and only by deleting the whole entry. On the other hand, the msgstr string, as well as translator comments, are really meant for the translator, and PO mode gives her the full control she needs.

The comment lines beginning with #, are special because they are not completely ignored by the programs as comments generally are. The comma separated list of flags is used by the msgfmt program to give the user some better diagnostic messages. Currently there are two forms of flags defined:

fuzzy
This flag can be generated by the msgmerge program or it can be inserted by the translator herself. It shows that the msgstr string might not be a correct translation (anymore). Only the translator can judge if the translation requires further modification, or is acceptable as is. Once satisfied with the translation, she then removes this fuzzy attribute. The msgmerge program inserts this when it combined the msgid and msgstr entries after fuzzy search only. See section 6.3 Fuzzy Entries.

c-format
no-c-format
These flags should not be added by a human. Instead only the xgettext program adds them. In an automated PO file processing system as proposed here the user changes would be thrown away again as soon as the xgettext program generates a new template file.

In case the c-format flag is given for a string the msgfmt does some more tests to check to validity of the translation. See section 8.1 Invoking the msgfmt Program.

A different kind of entries is used for translations which involve plural forms.

white-space
#  translator-comments
#. automatic-comments
#: reference...
#, flag...
msgid untranslated-string-singular
msgid_plural untranslated-string-plural
msgstr[0] translated-string-case-0
...
msgstr[N] translated-string-case-n

It happens that some lines, usually whitespace or comments, follow the very last entry of a PO file. Such lines are not part of any entry, and PO mode is unable to take action on those lines. By using the PO mode function M-x po-normalize, the translator may get rid of those spurious lines. See section 2.5 Normalizing Strings in Entries.

The remainder of this section may be safely skipped by those using PO mode, yet it may be interesting for everybody to have a better idea of the precise format of a PO file. On the other hand, those not having Emacs handy should carefully continue reading on.

Each of untranslated-string and translated-string respects the C syntax for a character string, including the surrounding quotes and embedded backslashed escape sequences. When the time comes to write multi-line strings, one should not use escaped newlines. Instead, a closing quote should follow the last character on the line to be continued, and an opening quote should resume the string at the beginning of the following PO file line. For example:

msgid ""
"Here is an example of how one might continue a very long string\n"
"for the common case the string represents multi-line output.\n"

In this example, the empty string is used on the first line, to allow better alignment of the H from the word `Here' over the f from the word `for'. In this example, the msgid keyword is followed by three strings, which are meant to be concatenated. Concatenating the empty string does not change the resulting overall string, but it is a way for us to comply with the necessity of msgid to be followed by a string on the same line, while keeping the multi-line presentation left-justified, as we find this to be a cleaner disposition. The empty string could have been omitted, but only if the string starting with `Here' was promoted on the first line, right after msgid.(2) It was not really necessary either to switch between the two last quoted strings immediately after the newline `\n', the switch could have occurred after any other character, we just did it this way because it is neater.

One should carefully distinguish between end of lines marked as `\n' inside quotes, which are part of the represented string, and end of lines in the PO file itself, outside string quotes, which have no incidence on the represented string.

Outside strings, white lines and comments may be used freely. Comments start at the beginning of a line with `#' and extend until the end of the PO file line. Comments written by translators should have the initial `#' immediately followed by some white space. If the `#' is not immediately followed by white space, this comment is most likely generated and managed by specialized GNU tools, and might disappear or be replaced unexpectedly when the PO file is given to msgmerge.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.3 Main PO mode Commands

After setting up Emacs with something similar to the lines in 2.1 Completing GNU gettext Installation, PO mode is activated for a window when Emacs finds a PO file in that window. This puts the window read-only and establishes a po-mode-map, which is a genuine Emacs mode, in a way that is not derived from text mode in any way. Functions found on po-mode-hook, if any, will be executed.

When PO mode is active in a window, the letters `PO' appear in the mode line for that window. The mode line also displays how many entries of each kind are held in the PO file. For example, the string `132t+3f+10u+2o' would tell the translator that the PO mode contains 132 translated entries (see section 6.2 Translated Entries, 3 fuzzy entries (see section 6.3 Fuzzy Entries), 10 untranslated entries (see section 6.4 Untranslated Entries) and 2 obsolete entries (see section 6.5 Obsolete Entries). Zero-coefficients items are not shown. So, in this example, if the fuzzy entries were unfuzzied, the untranslated entries were translated and the obsolete entries were deleted, the mode line would merely display `145t' for the counters.

The main PO commands are those which do not fit into the other categories of subsequent sections. These allow for quitting PO mode or for managing windows in special ways.

_
Undo last modification to the PO file (po-undo).

Q
Quit processing and save the PO file (po-quit).

q
Quit processing, possibly after confirmation (po-confirm-and-quit).

0
Temporary leave the PO file window (po-other-window).

?
h
Show help about PO mode (po-help).

=
Give some PO file statistics (po-statistics).

V
Batch validate the format of the whole PO file (po-validate).

The command _ (po-undo) interfaces to the Emacs undo facility. See section `Undoing Changes' in The Emacs Editor. Each time U is typed, modifications which the translator did to the PO file are undone a little more. For the purpose of undoing, each PO mode command is atomic. This is especially true for the RET command: the whole edition made by using a single use of this command is undone at once, even if the edition itself implied several actions. However, while in the editing window, one can undo the edition work quite parsimoniously.

The commands Q (po-quit) and q (po-confirm-and-quit) are used when the translator is done with the PO file. The former is a bit less verbose than the latter. If the file has been modified, it is saved to disk first. In both cases, and prior to all this, the commands check if any untranslated messages remain in the PO file and, if so, the translator is asked if she really wants to leave off working with this PO file. This is the preferred way of getting rid of an Emacs PO file buffer. Merely killing it through the usual command C-x k (kill-buffer) is not the tidiest way to proceed.

The command 0 (po-other-window) is another, softer way, to leave PO mode, temporarily. It just moves the cursor to some other Emacs window, and pops one if necessary. For example, if the translator just got PO mode to show some source context in some other, she might discover some apparent bug in the program source that needs correction. This command allows the translator to change sex, become a programmer, and have the cursor right into the window containing the program she (or rather he) wants to modify. By later getting the cursor back in the PO file window, or by asking Emacs to edit this file once again, PO mode is then recovered.

The command h (po-help) displays a summary of all available PO mode commands. The translator should then type any character to resume normal PO mode operations. The command ? has the same effect as h.

The command = (po-statistics) computes the total number of entries in the PO file, the ordinal of the current entry (counted from 1), the number of untranslated entries, the number of obsolete entries, and displays all these numbers.

The command V (po-validate) launches msgfmt in checking and verbose mode over the current PO file. This command first offers to save the current PO file on disk. The msgfmt tool, from GNU gettext, has the purpose of creating a MO file out of a PO file, and PO mode uses the features of this program for checking the overall format of a PO file, as well as all individual entries.

The program msgfmt runs asynchronously with Emacs, so the translator regains control immediately while her PO file is being studied. Error output is collected in the Emacs `*compilation*' buffer, displayed in another window. The regular Emacs command C-x` (next-error), as well as other usual compile commands, allow the translator to reposition quickly to the offending parts of the PO file. Once the cursor is on the line in error, the translator may decide on any PO mode action which would help correcting the error.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.4 Entry Positioning

The cursor in a PO file window is almost always part of an entry. The only exceptions are the special case when the cursor is after the last entry in the file, or when the PO file is empty. The entry where the cursor is found to be is said to be the current entry. Many PO mode commands operate on the current entry, so moving the cursor does more than allowing the translator to browse the PO file, this also selects on which entry commands operate.

Some PO mode commands alter the position of the cursor in a specialized way. A few of those special purpose positioning are described here, the others are described in following sections (for a complete list try C-h m):

.
Redisplay the current entry (po-current-entry).

n
Select the entry after the current one (po-next-entry).

p
Select the entry before the current one (po-previous-entry).

<
Select the first entry in the PO file (po-first-entry).

>
Select the last entry in the PO file (po-last-entry).

m
Record the location of the current entry for later use (po-push-location).

r
Return to a previously saved entry location (po-pop-location).

x
Exchange the current entry location with the previously saved one (po-exchange-location).

Any Emacs command able to reposition the cursor may be used to select the current entry in PO mode, including commands which move by characters, lines, paragraphs, screens or pages, and search commands. However, there is a kind of standard way to display the current entry in PO mode, which usual Emacs commands moving the cursor do not especially try to enforce. The command . (po-current-entry) has the sole purpose of redisplaying the current entry properly, after the current entry has been changed by means external to PO mode, or the Emacs screen otherwise altered.

It is yet to be decided if PO mode helps the translator, or otherwise irritates her, by forcing a rigid window disposition while she is doing her work. We originally had quite precise ideas about how windows should behave, but on the other hand, anyone used to Emacs is often happy to keep full control. Maybe a fixed window disposition might be offered as a PO mode option that the translator might activate or deactivate at will, so it could be offered on an experimental basis. If nobody feels a real need for using it, or a compulsion for writing it, we should drop this whole idea. The incentive for doing it should come from translators rather than programmers, as opinions from an experienced translator are surely more worth to me than opinions from programmers thinking about how others should do translation.

The commands n (po-next-entry) and p (po-previous-entry) move the cursor the entry following, or preceding, the current one. If n is given while the cursor is on the last entry of the PO file, or if p is given while the cursor is on the first entry, no move is done.

The commands < (po-first-entry) and > (po-last-entry) move the cursor to the first entry, or last entry, of the PO file. When the cursor is located past the last entry in a PO file, most PO mode commands will return an error saying `After last entry'. Moreover, the commands < and > have the special property of being able to work even when the cursor is not into some PO file entry, and one may use them for nicely correcting this situation. But even these commands will fail on a truly empty PO file. There are development plans for the PO mode for it to interactively fill an empty PO file from sources. See section 3.4 Marking Translatable Strings.

The translator may decide, before working at the translation of a particular entry, that she needs to browse the remainder of the PO file, maybe for finding the terminology or phraseology used in related entries. She can of course use the standard Emacs idioms for saving the current cursor location in some register, and use that register for getting back, or else, use the location ring.

PO mode offers another approach, by which cursor locations may be saved onto a special stack. The command m (po-push-location) merely adds the location of current entry to the stack, pushing the already saved locations under the new one. The command r (po-pop-location) consumes the top stack element and repositions the cursor to the entry associated with that top element. This position is then lost, for the next r will move the cursor to the previously saved location, and so on until no locations remain on the stack.

If the translator wants the position to be kept on the location stack, maybe for taking a look at the entry associated with the top element, then go elsewhere with the intent of getting back later, she ought to use m immediately after r.

The command x (po-exchange-location) simultaneously repositions the cursor to the entry associated with the top element of the stack of saved locations, and replaces that top element with the location of the current entry before the move. Consequently, repeating the x command toggles alternatively between two entries. For achieving this, the translator will position the cursor on the first entry, use m, then position to the second entry, and merely use x for making the switch.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.5 Normalizing Strings in Entries

There are many different ways for encoding a particular string into a PO file entry, because there are so many different ways to split and quote multi-line strings, and even, to represent special characters by backslashed escaped sequences. Some features of PO mode rely on the ability for PO mode to scan an already existing PO file for a particular string encoded into the msgid field of some entry. Even if PO mode has internally all the built-in machinery for implementing this recognition easily, doing it fast is technically difficult. To facilitate a solution to this efficiency problem, we decided on a canonical representation for strings.

A conventional representation of strings in a PO file is currently under discussion, and PO mode experiments with a canonical representation. Having both xgettext and PO mode converging towards a uniform way of representing equivalent strings would be useful, as the internal normalization needed by PO mode could be automatically satisfied when using xgettext from GNU gettext. An explicit PO mode normalization should then be only necessary for PO files imported from elsewhere, or for when the convention itself evolves.

So, for achieving normalization of at least the strings of a given PO file needing a canonical representation, the following PO mode command is available:

M-x po-normalize
Tidy the whole PO file by making entries more uniform.

The special command M-x po-normalize, which has no associated keys, revises all entries, ensuring that strings of both original and translated entries use uniform internal quoting in the PO file. It also removes any crumb after the last entry. This command may be useful for PO files freshly imported from elsewhere, or if we ever improve on the canonical quoting format we use. This canonical format is not only meant for getting cleaner PO files, but also for greatly speeding up msgid string lookup for some other PO mode commands.

M-x po-normalize presently makes three passes over the entries. The first implements heuristics for converting PO files for GNU gettext 0.6 and earlier, in which msgid and msgstr fields were using K&R style C string syntax for multi-line strings. These heuristics may fail for comments not related to obsolete entries and ending with a backslash; they also depend on subsequent passes for finalizing the proper commenting of continued lines for obsolete entries. This first pass might disappear once all oldish PO files would have been adjusted. The second and third pass normalize all msgid and msgstr strings respectively. They also clean out those trailing backslashes used by XView's msgfmt for continued lines.

Having such an explicit normalizing command allows for importing PO files from other sources, but also eases the evolution of the current convention, evolution driven mostly by aesthetic concerns, as of now. It is easy to make suggested adjustments at a later time, as the normalizing command and eventually, other GNU gettext tools should greatly automate conformance. A description of the canonical string format is given below, for the particular benefit of those not having Emacs handy, and who would nevertheless want to handcraft their PO files in nice ways.

Right now, in PO mode, strings are single line or multi-line. A string goes multi-line if and only if it has embedded newlines, that is, if it matches `[^\n]\n+[^\n]'. So, we would have:

msgstr "\n\nHello, world!\n\n\n"

but, replacing the space by a newline, this becomes:

msgstr ""
"\n"
"\n"
"Hello,\n"
"world!\n"
"\n"
"\n"

We are deliberately using a caricatural example, here, to make the point clearer. Usually, multi-lines are not that bad looking. It is probable that we will implement the following suggestion. We might lump together all initial newlines into the empty string, and also all newlines introducing empty lines (that is, for n > 1, the n-1'th last newlines would go together on a separate string), so making the previous example appear:

msgstr "\n\n"
"Hello,\n"
"world!\n"
"\n\n"

There are a few yet undecided little points about string normalization, to be documented in this manual, once these questions settle.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. Preparing Program Sources

For the programmer, changes to the C source code fall into three categories. First, you have to make the localization functions known to all modules needing message translation. Second, you should properly trigger the operation of GNU gettext when the program initializes, usually from the main function. Last, you should identify and especially mark all constant strings in your program needing translation.

Presuming that your set of programs, or package, has been adjusted so all needed GNU gettext files are available, and your `Makefile' files are adjusted (see section 12. The Maintainer's View), each C module having translated C strings should contain the line:

#include <libintl.h>

The remaining changes to your C sources are discussed in the further sections of this chapter.

3.1 Triggering gettext Operations
3.2 Preparing Translatable Strings
3.3 How Marks Appear in Sources
3.4 Marking Translatable Strings
3.5 Special Comments preceding Keywords Telling something about the following string
3.6 Special Cases of Translatable Strings

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 Triggering gettext Operations

The initialization of locale data should be done with more or less the same code in every program, as demonstrated below:

int
main (argc, argv)
     int argc;
     char argv;
{
  ...
  setlocale (LC_ALL, "");
  bindtextdomain (PACKAGE, LOCALEDIR);
  textdomain (PACKAGE);
  ...
}

PACKAGE and LOCALEDIR should be provided either by `config.h' or by the Makefile. For now consult the gettext or hello sources for more information.

The use of LC_ALL might not be appropriate for you. LC_ALL includes all locale categories and especially LC_CTYPE. This later category is responsible for determining character classes with the isalnum etc. functions from `ctype.h' which could especially for programs, which process some kind of input language, be wrong. For example this would mean that a source code using the ç (c-cedilla character) is runnable in France but not in the U.S.

Some systems also have problems with parsing numbers using the scanf functions if an other but the LC_ALL locale is used. The standards say that additional formats but the one known in the "C" locale might be recognized. But some systems seem to reject numbers in the "C" locale format. In some situation, it might also be a problem with the notation itself which makes it impossible to recognize whether the number is in the "C" locale or the local format. This can happen if thousands separator characters are used. Some locales define this character accordfing to the national conventions to '.' which is the same character used in the "C" locale to denote the decimal point.

So it is sometimes necessary to replace the LC_ALL line in the code above by a sequence of setlocale lines

{
  ...
  setlocale (LC_CTYPE, "");
  setlocale (LC_MESSAGES, "");
  ...
}

On all POSIX conformant systems the locale categories LC_CTYPE, LC_COLLATE, LC_MONETARY, LC_NUMERIC, and LC_TIME are available. On some modern systems there is also a locale LC_MESSAGES which is called on some old, XPG2 compliant systems LC_RESPONSES.

Note that changing the LC_CTYPE also affects the functions declared in the <ctype.h> standard header. If this is not desirable in your application (for example in a compiler's parser), you can use a set of substitute functions which hardwire the C locale, such as found in the <c-ctype.h> and <c-ctype.c> files in the gettext source distribution.

It is also possible to switch the locale forth and back between the environment dependent locale and the C locale, but this approach is normally avoided because a setlocale call is expensive, because it is tedious to determine the places where a locale switch is needed in a large program's source, and because switching a locale is not multithread-safe.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 Preparing Translatable Strings

Before strings can be marked for translations, they sometimes need to be adjusted. Usually preparing a string for translation is done right before marking it, during the marking phase which is described in the next sections. What you have to keep in mind while doing that is the following.

  • Decent English style.

  • Entire sentences.

  • Split at paragraphs.

  • Use format strings instead of string concatenation.

Let's look at some examples of these guidelines.

Translatable strings should be in good English style. If slang language with abbreviations and shortcuts is used, often translators will not understand the message and will produce very inappropriate translations.

"%s: is parameter\n"

This is nearly untranslatable: Is the displayed item a parameter or the parameter?

"No match"

The ambiguity in this message makes it ununderstandable: Is the program attempting to set something on fire? Does it mean "The given object does not match the template"? Does it mean "The template does not fit for any of the objects"?

In both cases, adding more words to the message will help both the translator and the English speaking user.

Translatable strings should be entire sentences. It is often not possible to translate single verbs or adjectives in a substitutable way.

printf ("File %s is %s protected", filename, rw ? "write" : "read");

Most translators will not look at the source and will thus only see the string "File %s is %s protected", which is unintelligible. Change this to

printf (rw ? "File %s is write protected" : "File %s is read protected",
        filename);

This way the translator will not only understand the message, she will also be able to find the appropriate grammatical construction. The French translator for example translates "write protected" like "protected against writing".

Often sentences don't fit into a single line. If a sentence is output using two subsequent printf statements, like this

printf ("Locale charset \"%s\" is different from\n", lcharset);
printf ("input file charset \"%s\".\n", fcharset);

the translator would have to translate two half sentences, but nothing in the POT file would tell her that the two half sentences belong together. It is necessary to merge the two printf statements so that the translator can handle the entire sentence at once and decide at which place to insert a line break in the translation (if at all):

printf ("Locale charset \"%s\" is different from\n\
input file charset \"%s\".\n", lcharset, fcharset);

You may now ask: how about two or more adjacent sentences? Like in this case:

puts ("Apollo 13 scenario: Stack overflow handling failed.");
puts ("On the next stack overflow we will crash!!!");

Should these two statements merged into a single one? I would recommend to merge them if the two sentences are related to each other, because then it makes it easier for the translator to understand and translate both. On the other hand, if one of the two messages is a stereotypic one, occurring in other places as well, you will do a favour to the translator by not merging the two. (Identical messages occurring in several places are combined by xgettext, so the translator has to handle them once only.)

Translatable strings should be limited to one paragraph; don't let a single message be longer than ten lines. The reason is that when the translatable string changes, the translator is faced with the task of updating the entire translated string. Maybe only a single word will have changed in the English string, but the translator doesn't see that (with the current translation tools), therefore she has to proofread the entire message.

Many GNU programs have a `--help' output that extends over several screen pages. It is a courtesy towards the translators to split such a message into several ones of five to ten lines each. While doing that, you can also attempt to split the documented options into groups, such as the input options, the output options, and the informative output options. This will help every user to find the option he is looking for.

Hardcoded string concatenation is sometimes used to construct English strings:

strcpy (s, "Replace ");
strcat (s, object1);
strcat (s, " with ");
strcat (s, object2);
strcat (s, "?");

In order to present to the translator only entire sentences, and also because in some languages the translator might want to swap the order of object1 and object2, it is necessary to change this to use a format string:

sprintf (s, "Replace %s with %s?", object1, object2);

A similar case is compile time concatenation of strings. The ISO C 99 include file <inttypes.h> contains a macro PRId64 that can be used as a formatting directive for outputting an `int64_t' integer through printf. It expands to a constant string, usually "d" or "ld" or "lld" or something like this, depending on the platform. Assume you have code like

printf ("The amount is %0" PRId64 "\n"), number);

After marking, this cannot become

printf (gettext ("The amount is %0") PRId64 "\n"), number);

because it would simply be invalid C syntax. It cannot become

printf (gettext ("The amount is %0" PRId64 "\n")), number);

because the value of PRId64 is not known to xgettext, and even if were, there would be three or more possibilities, and the translator would have to translate three or more strings that differ in a single letter.

The solution for this problem is to change the code like this:

char buf1[100];
sprintf (buf1, "%0" PRId64, number);
printf (gettext ("The amount is %s\n"), buf1);

This means, you put the platform dependent code in one statement, and the internationalization code in a different statement. Note that a buffer length of 100 is safe, because all available hardware integer types are limited to 128 bits, and to print a 128 bit integer one needs at most 54 characters, regardless whether in decimal, octal or hexadecimal.

All this applies to other programming languages as well. For example, in Java, string contenation is very frequently used, because it is a compiler built-in operator. Like in C, in Java, you would change

System.out.println("Replace "+object1+" with "+object2+"?");

into a statement involving a format string:

System.out.println(
    MessageFormat.format("Replace {0} with {1}?",
                         new Object[] { object1, object2 }));

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 How Marks Appear in Sources

All strings requiring translation should be marked in the C sources. Marking is done in such a way that each translatable string appears to be the sole argument of some function or preprocessor macro. There are only a few such possible functions or macros meant for translation, and their names are said to be marking keywords. The marking is attached to strings themselves, rather than to what we do with them. This approach has more uses. A blatant example is an error message produced by formatting. The format string needs translation, as well as some strings inserted through some `%s' specification in the format, while the result from sprintf may have so many different instances that it is impractical to list them all in some `error_string_out()' routine, say.

This marking operation has two goals. The first goal of marking is for triggering the retrieval of the translation, at run time. The keyword are possibly resolved into a routine able to dynamically return the proper translation, as far as possible or wanted, for the argument string. Most localizable strings are found in executable positions, that is, attached to variables or given as parameters to functions. But this is not universal usage, and some translatable strings appear in structured initializations. See section 3.6 Special Cases of Translatable Strings.

The second goal of the marking operation is to help xgettext at properly extracting all translatable strings when it scans a set of program sources and produces PO file templates.

The canonical keyword for marking translatable strings is `gettext', it gave its name to the whole GNU gettext package. For packages making only light use of the `gettext' keyword, macro or function, it is easily used as is. However, for packages using the gettext interface more heavily, it is usually more convenient to give the main keyword a shorter, less obtrusive name. Indeed, the keyword might appear on a lot of strings all over the package, and programmers usually do not want nor need their program sources to remind them forcefully, all the time, that they are internationalized. Further, a long keyword has the disadvantage of using more horizontal space, forcing more indentation work on sources for those trying to keep them within 79 or 80 columns.

Many packages use `_' (a simple underline) as a keyword, and write `_("Translatable string")' instead of `gettext ("Translatable string")'. Further, the coding rule, from GNU standards, wanting that there is a space between the keyword and the opening parenthesis is relaxed, in practice, for this particular usage. So, the textual overhead per translatable string is reduced to only three characters: the underline and the two parentheses. However, even if GNU gettext uses this convention internally, it does not offer it officially. The real, genuine keyword is truly `gettext' indeed. It is fairly easy for those wanting to use `_' instead of `gettext' to declare:

#include <libintl.h>
#define _(String) gettext (String)

instead of merely using `#include <libintl.h>'.

Later on, the maintenance is relatively easy. If, as a programmer, you add or modify a string, you will have to ask yourself if the new or altered string requires translation, and include it within `_()' if you think it should be translated. `"%s: %d"' is an example of string not requiring translation!

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4 Marking Translatable Strings

In PO mode, one set of features is meant more for the programmer than for the translator, and allows him to interactively mark which strings, in a set of program sources, are translatable, and which are not. Even if it is a fairly easy job for a programmer to find and mark such strings by other means, using any editor of his choice, PO mode makes this work more comfortable. Further, this gives translators who feel a little like programmers, or programmers who feel a little like translators, a tool letting them work at marking translatable strings in the program sources, while simultaneously producing a set of translation in some language, for the package being internationalized.

The set of program sources, targetted by the PO mode commands describe here, should have an Emacs tags table constructed for your project, prior to using these PO file commands. This is easy to do. In any shell window, change the directory to the root of your project, then execute a command resembling:

etags src/*.[hc] lib/*.[hc]

presuming here you want to process all `.h' and `.c' files from the `src/' and `lib/' directories. This command will explore all said files and create a `TAGS' file in your root directory, somewhat summarizing the contents using a special file format Emacs can understand.

For packages following the GNU coding standards, there is a make goal tags or TAGS which constructs the tag files in all directories and for all files containing source code.

Once your `TAGS' file is ready, the following commands assist the programmer at marking translatable strings in his set of sources. But these commands are necessarily driven from within a PO file window, and it is likely that you do not even have such a PO file yet. This is not a problem at all, as you may safely open a new, empty PO file, mainly for using these commands. This empty PO file will slowly fill in while you mark strings as translatable in your program sources.

,
Search through program sources for a string which looks like a candidate for translation (po-tags-search).

M-,
Mark the last string found with `_()' (po-mark-translatable).

M-.
Mark the last string found with a keyword taken from a set of possible keywords. This command with a prefix allows some management of these keywords (po-select-mark-and-mark).

The , (po-tags-search) command searches for the next occurrence of a string which looks like a possible candidate for translation, and displays the program source in another Emacs window, positioned in such a way that the string is near the top of this other window. If the string is too big to fit whole in this window, it is positioned so only its end is shown. In any case, the cursor is left in the PO file window. If the shown string would be better presented differently in different native languages, you may mark it using M-, or M-.. Otherwise, you might rather ignore it and skip to the next string by merely repeating the , command.

A string is a good candidate for translation if it contains a sequence of three or more letters. A string containing at most two letters in a row will be considered as a candidate if it has more letters than non-letters. The command disregards strings containing no letters, or isolated letters only. It also disregards strings within comments, or strings already marked with some keyword PO mode knows (see below).

If you have never told Emacs about some `TAGS' file to use, the command will request that you specify one from the minibuffer, the first time you use the command. You may later change your `TAGS' file by using the regular Emacs command M-x visit-tags-table, which will ask you to name the precise `TAGS' file you want to use. See section `Tag Tables' in The Emacs Editor.

Each time you use the , command, the search resumes from where it was left by the previous search, and goes through all program sources, obeying the `TAGS' file, until all sources have been processed. However, by giving a prefix argument to the command (C-u ,), you may request that the search be restarted all over again from the first program source; but in this case, strings that you recently marked as translatable will be automatically skipped.

Using this , command does not prevent using of other regular Emacs tags commands. For example, regular tags-search or tags-query-replace commands may be used without disrupting the independent , search sequence. However, as implemented, the initial , command (or the , command is used with a prefix) might also reinitialize the regular Emacs tags searching to the first tags file, this reinitialization might be considered spurious.

The M-, (po-mark-translatable) command will mark the recently found string with the `_' keyword. The M-. (po-select-mark-and-mark) command will request that you type one keyword from the minibuffer and use that keyword for marking the string. Both commands will automatically create a new PO file untranslated entry for the string being marked, and make it the current entry (making it easy for you to immediately proceed to its translation, if you feel like doing it right away). It is possible that the modifications made to the program source by M-, or M-. render some source line longer than 80 columns, forcing you to break and re-indent this line differently. You may use the O command from PO mode, or any other window changing command from Emacs, to break out into the program source window, and do any needed adjustments. You will have to use some regular Emacs command to return the cursor to the PO file window, if you want command , for the next string, say.

The M-. command has a few built-in speedups, so you do not have to explicitly type all keywords all the time. The first such speedup is that you are presented with a preferred keyword, which you may accept by merely typing RET at the prompt. The second speedup is that you may type any non-ambiguous prefix of the keyword you really mean, and the command will complete it automatically for you. This also means that PO mode has to know all your possible keywords, and that it will not accept mistyped keywords.

If you reply ? to the keyword request, the command gives a list of all known keywords, from which you may choose. When the command is prefixed by an argument (C-u M-.), it inhibits updating any program source or PO file buffer, and does some simple keyword management instead. In this case, the command asks for a keyword, written in full, which becomes a new allowed keyword for later M-. commands. Moreover, this new keyword automatically becomes the preferred keyword for later commands. By typing an already known keyword in response to C-u M-., one merely changes the preferred keyword and does nothing more.

All keywords known for M-. are recognized by the , command when scanning for strings, and strings already marked by any of those known keywords are automatically skipped. If many PO files are opened simultaneously, each one has its own independent set of known keywords. There is no provision in PO mode, currently, for deleting a known keyword, you have to quit the file (maybe using q) and reopen it afresh. When a PO file is newly brought up in an Emacs window, only `gettext' and `_' are known as keywords, and `gettext' is preferred for the M-. command. In fact, this is not useful to prefer `_', as this one is already built in the M-, command.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5 Special Comments preceding Keywords

In C programs strings are often used within calls of functions from the printf family. The special thing about these format strings is that they can contain format specifiers introduced with %. Assume we have the code

printf (gettext ("String `%s' has %d characters\n"), s, strlen (s));

A possible German translation for the above string might be:

"%d Zeichen lang ist die Zeichenkette `%s'"

A C programmer, even if he cannot speak German, will recognize that there is something wrong here. The order of the two format specifiers is changed but of course the arguments in the printf don't have. This will most probably lead to problems because now the length of the string is regarded as the address.

To prevent errors at runtime caused by translations the msgfmt tool can check statically whether the arguments in the original and the translation string match in type and number. If this is not the case and the `-c' option has been passed to msgfmt, msgfmt will give an error and refuse to produce a MO file. Thus consequent use of `msgfmt -c' will catch the error, so that it cannot cause cause problems at runtime.

If the word order in the above German translation would be correct one would have to write

"%2$d Zeichen lang ist die Zeichenkette `%1$s'"

The routines in msgfmt know about this special notation.

Because not all strings in a program must be format strings it is not useful for msgfmt to test all the strings in the `.po' file. This might cause problems because the string might contain what looks like a format specifier, but the string is not used in printf.

Therefore the xgettext adds a special tag to those messages it thinks might be a format string. There is no absolute rule for this, only a heuristic. In the `.po' file the entry is marked using the c-format flag in the #, comment line (see section 2.2 The Format of PO Files).

The careful reader now might say that this again can cause problems. The heuristic might guess it wrong. This is true and therefore xgettext knows about special kind of comment which lets the programmer take over the decision. If in the same line or the immediately preceding line of the gettext keyword the xgettext program find a comment containing the words xgettext:c-format it will mark the string in any case with the c-format flag. This kind of comment should be used when xgettext does not recognize the string as a format string but is really is one and it should be tested. Please note that when the comment is in the same line of the gettext keyword, it must be before the string to be translated.

This situation happens quite often. The printf function is often called with strings which do not contain a format specifier. Of course one would normally use fputs but it does happen. In this case xgettext does not recognize this as a format string but what happens if the translation introduces a valid format specifier? The printf function will try to access one of the parameter but none exists because the original code does not refer to any parameter.

xgettext of course could make a wrong decision the other way round, i.e. a string marked as a format string actually is not a format string. In this case the msgfmt might give too many warnings and would prevent translating the `.po' file. The method to prevent this wrong decision is similar to the one used above, only the comment to use must contain the string xgettext:no-c-format.

If a string is marked with c-format and this is not correct the user can find out who is responsible for the decision. See 4.1 Invoking the xgettext Program to see how the --debug option can be used for solving this problem.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6 Special Cases of Translatable Strings

The attentive reader might now point out that it is not always possible to mark translatable string with gettext or something like this. Consider the following case:

{
  static const char *messages[] = {
    "some very meaningful message",
    "and another one"
  };
  const char *string;
  ...
  string
    = index > 1 ? "a default message" : messages[index];

  fputs (string);
  ...
}

While it is no problem to mark the string "a default message" it is not possible to mark the string initializers for messages. What is to be done? We have to fulfill two tasks. First we have to mark the strings so that the xgettext program (see section 4.1 Invoking the xgettext Program) can find them, and second we have to translate the string at runtime before printing them.

The first task can be fulfilled by creating a new keyword, which names a no-op. For the second we have to mark all access points to a string from the array. So one solution can look like this:

#define gettext_noop(String) String

{
  static const char *messages[] = {
    gettext_noop ("some very meaningful message"),
    gettext_noop ("and another one")
  };
  const char *string;
  ...
  string
    = index > 1 ? gettext ("a default message") : gettext (messages[index]);

  fputs (string);
  ...
}

Please convince yourself that the string which is written by fputs is translated in any case. How to get xgettext know the additional keyword gettext_noop is explained in 4.1 Invoking the xgettext Program.

The above is of course not the only solution. You could also come along with the following one:

#define gettext_noop(String) String

{
  static const char *messages[] = {
    gettext_noop ("some very meaningful message",
    gettext_noop ("and another one")
  };
  const char *string;
  ...
  string
    = index > 1 ? gettext_noop ("a default message") : messages[index];

  fputs (gettext (string));
  ...
}

But this has a drawback. The programmer has to take care that he uses gettext_noop for the string "a default message". A use of gettext could have in rare cases unpredictable results.

One advantage is that you need not make control flow analysis to make sure the output is really translated in any case. But this analysis is generally not very difficult. If it should be in any situation you can use this second method in this situation.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Making the PO Template File

After preparing the sources, the programmer creates a PO template file. This section explains how to use xgettext for this purpose.

4.1 Invoking the xgettext Program

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 Invoking the xgettext Program

xgettext [option] [inputfile] ...

The xgettext program extracts translatable strings from given input files.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.1 Input file location

`inputfile ...'
Input files.

`-f file'
`--files-from=file'
Read the names of the input files from file instead of getting them from the command line.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If inputfile is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.2 Output file location

`-d name'
`--default-domain=name'
Use `name.po' for output (instead of `messages.po').

`-o file'
`--output=file'
Write output to specified file (instead of `name.po' or `messages.po').

`-p dir'
`--output-dir=dir'
Output files will be placed in directory dir.

If the output file is `-' or `/dev/stdout', the output is written to standard output.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.3 Choice of input file language

`-L name'
`--language=name'
Specifies the language of the input files. The supported languages are C, C++, ObjectiveC, PO, Python, Lisp, EmacsLisp, librep, Java, awk, YCP, Tcl, RST, Glade.

`-C'
`--c++'
This is a shorthand for --language=C++.

By default the language is guessed depending on the input file name extension.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.4 Operation mode

`-j'
`--join-existing'
Join messages with existing file.

`-x file'
`--exclude-file=file'
Entries from file are not extracted. file should be a PO or POT file.

`-c [tag]'
`--add-comments[=tag]'
Place comment block with tag (or those preceding keyword lines) in output file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.5 Language=C/C++ specific options

`-a'
`--extract-all'
Extract all strings.

`-k keywordspec'
`--keyword[=keywordspec]'
Additional keyword to be looked for (without keywordspec means not to use default keywords).

If keywordspec is a C identifer id, xgettext looks for strings in the first argument of each call to the function or macro id. If keywordspec is of the form `id:argnum', xgettext looks for strings in the argnumth argument of the call. If keywordspec is of the form `id:argnum1,argnum2', xgettext looks for strings in the argnum1st argument and in the argnum2nd argument of the call, and treats them as singular/plural variants for a message with plural handling.

The default keyword specifications, which are always looked for if not explicitly disabled, are gettext, dgettext:2, dcgettext:2, ngettext:1,2, dngettext:2,3, dcngettext:2,3, and gettext_noop.

`-T'
`--trigraphs'
Understand ANSI C trigraphs for input.

`--debug'
Use the flags c-format and possible-c-format to show who was responsible for marking a message as a format string. The latter form is used if the xgettext program decided, the format form is used if the programmer prescribed it.

By default only the c-format form is used. The translator should not have to care about these details.

This implementation of xgettext is able to process a few awkward cases, like strings in preprocessor macros, ANSI concatenation of adjacent strings, and escaped end of lines for continued strings.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.6 Output details

`--force-po'
Always write an output file even if no message is defined.

`-i'
`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`-n'
`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

`--omit-header'
Don't write header with `msgid ""' entry.

This is useful for testing purposes because it eliminates a source of variance for generated .gmo files. With --omit-header, two invocations of xgettext on the same files with the same options at different times are guaranteed to produce the same results.

`--copyright-holder=string'
Set the copyright holder in the output. string should be the copyright holder of the surrounding package. (Note that the msgstr strings, extracted from the package's sources, belong to the copyright holder of the package.) Translators are expected to transfer or disclaim the copyright for their translations, so that package maintainers can distribute them without legal risk. If string is empty, the output files are marked as being in the public domain; in this case, the translators are expected to disclaim their copyright, again so that package maintainers can distribute them without legal risk.

The default value for string is the Free Software Foundation, Inc., simply because xgettext was first used in the GNU project.

`--foreign-user'
Omit FSF copyright in output. This option is equivalent to `--copyright-holder="'. It can be useful for packages outside the GNU project that want their translations to be in the public domain.

`-m [string]'
`--msgstr-prefix[=string]'
Use string (or "" if not specified) as prefix for msgstr entries.

`-M [string]'
`--msgstr-suffix[=string]'
Use string (or "" if not specified) as suffix for msgstr entries.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.7 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Creating a New PO File

When starting a new translation, the translator creates a file called `LANG.po', as a copy of the `package.pot' template file with modifications in the initial comments (at the beginning of the file) and in the header entry (the first entry, near the beginning of the file).

The easiest way to do so is by use of the `msginit' program. For example:

$ cd PACKAGE-VERSION
$ cd po
$ msginit --verbose

The alternative way is to do the copy and modifications by hand. To do so, the translator copies `package.pot' to `LANG.po'. Then she modifies the initial comments and the header entry of this file.

5.1 Invoking the msginit Program
5.2 Filling in the Header Entry

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 Invoking the msginit Program

msginit [option]

The msginit program creates a new PO file, initializing the meta information with values from the user's environment.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.1 Input file location

`-i inputfile'
`--input=inputfile'
Input POT file.

If no inputfile is given, the current directory is searched for the POT file. If it is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.2 Output file location

`-o file'
`--output-file=file'
Write output to specified PO file.

If no output file is given, it depends on the `--locale' option or the user's locale setting. If it is `-', the results are written to standard output.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.3 Output details

`-l ll_CC'
`--locale=ll_CC'
Set target locale. ll should be a language code, and CC should be a country code. The command `locale -a' can be used to output a list of all installed locales. The default is the user's locale setting.

`--no-translator'
Declares that the PO file will not have a human translator and is instead automatically generated.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1.4 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 Filling in the Header Entry

The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and "FIRST AUTHOR , YEAR" ought to be replaced by sensible information. This can be done in any text editor; if Emacs is used and it switched to PO mode automatically (because it has recognized the file's suffix), you can disable it by typing M-x fundamental-mode.

Modifying the header entry can already be done using PO mode: in Emacs, type M-x po-mode RET and then RET again to start editing the entry. You should fill in the following fields.

Project-Id-Version
This is the name and version of the package.

POT-Creation-Date
This has already been filled in by xgettext.

PO-Revision-Date
You don't need to fill this in. It will be filled by the Emacs PO mode when you save the file.

Last-Translator
Fill in your name and email address (without double quotes).

Language-Team
Fill in the English name of the language, and the email address or homepage URL of the language team you are part of.

Before starting a translation, it is a good idea to get in touch with your translation team, not only to make sure you don't do duplicated work, but also to coordinate difficult linguistic issues.

In the Free Translation Project, each translation team has its own mailing list. The up-to-date list of teams can be found at the Free Translation Project's homepage, http://www.iro.umontreal.ca/contrib/po/HTML/, in the "National teams" area.

Content-Type
Replace `CHARSET' with the character encoding used for your language, in your locale, or UTF-8. This field is needed for correct operation of the msgmerge and msgfmt programs, as well as for users whose locale's character encoding differs from yours (see 10.2.4 How to specify the output character set gettext uses).

You get the character encoding of your locale by running the shell command `locale charmap'. If the result is `C' or `ANSI_X3.4-1968', which is equivalent to `ASCII' (= `US-ASCII'), it means that your locale is not correctly configured. In this case, ask your translation team which charset to use. `ASCII' is not usable for any language except Latin.

Because the PO files must be portable to operating systems with less advanced internationalization facilities, the character encodings that can be used are limited to those supported by both GNU libc and GNU libiconv. These are: ASCII, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, ISO-8859-13, ISO-8859-15, KOI8-R, KOI8-U, CP850, CP866, CP874, CP932, CP949, CP950, CP1250, CP1251, CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, GB2312, EUC-JP, EUC-KR, EUC-TW, BIG5, BIG5-HKSCS, GBK, GB18030, SHIFT_JIS, JOHAB, TIS-620, VISCII, UTF-8.

In the GNU system, the following encodings are frequently used for the corresponding languages.

  • ISO-8859-1 for Afrikaans, Albanian, Basque, Catalan, Dutch, English, Estonian, Faroese, Finnish, French, Galician, German, Greenlandic, Icelandic, Indonesian, Irish, Italian, Malay, Norwegian, Portuguese, Spanish, Swedish,
  • ISO-8859-2 for Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak, Slovenian,
  • ISO-8859-3 for Maltese,
  • ISO-8859-5 for Macedonian, Serbian,
  • ISO-8859-6 for Arabic,
  • ISO-8859-7 for Greek,
  • ISO-8859-8 for Hebrew,
  • ISO-8859-9 for Turkish,
  • ISO-8859-13 for Latvian, Lithuanian,
  • ISO-8859-15 for Basque, Catalan, Dutch, English, Finnish, French, Galician, German, Irish, Italian, Portuguese, Spanish, Swedish,
  • KOI8-R for Russian,
  • KOI8-U for Ukrainian,
  • CP1251 for Bulgarian, Byelorussian,
  • GB2312, GBK, GB18030 for simplified writing of Chinese,
  • BIG5, BIG5-HKSCS for traditional writing of Chinese,
  • EUC-JP for Japanese,
  • EUC-KR for Korean,
  • TIS-620 for Thai,
  • UTF-8 for any language, including those listed above.

When single quote characters or double quote characters are used in translations for your language, and your locale's encoding is one of the ISO-8859-* charsets, it is best if you create your PO files in UTF-8 encoding, instead of your locale's encoding. This is because in UTF-8 the real quote characters can be represented (single quote characters: U+2018, U+2019, double quote characters: U+201C, U+201D), whereas none of ISO-8859-* charsets has them all. Users in UTF-8 locales will see the real quote characters, whereas users in ISO-8859-* locales will see the vertical apostrophe and the vertical double quote instead (because that's what the character set conversion will transliterate them to).

To enter such quote characters under X11, you can change your keyboard mapping using the xmodmap program. The X11 names of the quote characters are "leftsinglequotemark", "rightsinglequotemark", "leftdoublequotemark", "rightdoublequotemark", "singlelowquotemark", "doublelowquotemark".

Note that only recent versions of GNU Emacs support the UTF-8 encoding: Emacs 20 with Mule-UCS, and Emacs 21. As of January 2001, XEmacs doesn't support the UTF-8 encoding.

The character encoding name can be written in either upper or lower case. Usually upper case is preferred.

Content-Transfer-Encoding
Set this to 8bit.

Plural-Forms
This field is optional. It is only needed if the PO file has plural forms. You can find them by searching for the `msgid_plural' keyword. The format of the plural forms field is described in 10.2.5 Additional functions for plural forms.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Updating Existing PO Files

6.1 Invoking the msgmerge Program
6.2 Translated Entries
6.3 Fuzzy Entries
6.4 Untranslated Entries
6.5 Obsolete Entries
6.6 Modifying Translations
6.7 Modifying Comments
6.8 Details of Sub Edition Mode for Editing Translations
6.9 C Sources Context
6.10 Consulting Auxiliary PO Files
6.11 Using Translation Compendia

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1 Invoking the msgmerge Program

msgmerge [option] def.po ref.pot

The msgmerge program merges two Uniforum style .po files together. The def.po file is an existing PO file with translations which will be taken over to the newly created file as long as they still match; comments will be preserved, but extracted comments and file positions will be discarded. The ref.pot file is the last created PO file with up-to-date source references but old translations, or a PO Template file (generally created by xgettext); any translations or comments in the file will be discarded, however dot comments and file positions will be preserved. Where an exact match cannot be found, fuzzy matching is used to produce better results.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1.1 Input file location

`def.po'
Translations referring to old sources.

`ref.pot'
References to the new sources.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

`-C file'
`--compendium=file'
Specify an additional library of message translations. See section 6.11 Using Translation Compendia. This option may be specified more than once.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1.2 Operation mode

`-U'
`--update'
Update def.po. Do nothing if def.po is already up to date.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1.3 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1.4 Output file location in update mode

The result is written back to def.po.

`--backup=control'
Make a backup of def.po

`--suffix=suffix'
Override the usual backup suffix.

The version control method may be selected via the --backup option or through the VERSION_CONTROL environment variable. Here are the values:

`none'
`off'
Never make backups (even if --backup is given).

`numbered'
`t'
Make numbered backups.

`existing'
`nil'
Make numbered backups if numbered backups for this file already exist, otherwise make simple backups.

`simple'
`never'
Always make simple backups.

The backup suffix is `~', unless set with --suffix or the SIMPLE_BACKUP_SUFFIX environment variable.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1.5 Operation modifiers

`-m'
`--multi-domain'
Apply ref.pot to each of the domains in def.po.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1.6 Output details

`--force-po'
Always write an output file even if it contains no message.

`-i'
`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1.7 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

`-v'
`--verbose'
Increase verbosity level.

`-q'
`--quiet'
`--silent'
Suppress progress indicators.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.2 Translated Entries

Each PO file entry for which the msgstr field has been filled with a translation, and which is not marked as fuzzy (see section 6.3 Fuzzy Entries), is said to be a translated entry. Only translated entries will later be compiled by GNU msgfmt and become usable in programs. Other entry types will be excluded; translation will not occur for them.

Some commands are more specifically related to translated entry processing.

t
Find the next translated entry (po-next-translated-entry).

T
Find the previous translated entry (po-previous-translated-entry).

The commands t (po-next-translated-entry) and T (po-previous-translated-entry) move forwards or backwards, chasing for an translated entry. If none is found, the search is extended and wraps around in the PO file buffer.

Translated entries usually result from the translator having edited in a translation for them, 6.6 Modifying Translations. However, if the variable po-auto-fuzzy-on-edit is not nil, the entry having received a new translation first becomes a fuzzy entry, which ought to be later unfuzzied before becoming an official, genuine translated entry. See section 6.3 Fuzzy Entries.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3 Fuzzy Entries

Each PO file entry may have a set of attributes, which are qualities given a name and explicitely associated with the translation, using a special system comment. One of these attributes has the name fuzzy, and entries having this attribute are said to have a fuzzy translation. They are called fuzzy entries, for short.

Fuzzy entries, even if they account for translated entries for most other purposes, usually call for revision by the translator. Those may be produced by applying the program msgmerge to update an older translated PO files according to a new PO template file, when this tool hypothesises that some new msgid has been modified only slightly out of an older one, and chooses to pair what it thinks to be the old translation for the new modified entry. The slight alteration in the original string (the msgid string) should often be reflected in the translated string, and this requires the intervention of the translator. For this reason, msgmerge might mark some entries as being fuzzy.

Also, the translator may decide herself to mark an entry as fuzzy for her own convenience, when she wants to remember that the entry has to be later revisited. So, some commands are more specifically related to fuzzy entry processing.

z
Find the next fuzzy entry (po-next-fuzzy-entry).

Z
Find the previous fuzzy entry (po-previous-fuzzy-entry).

TAB
Remove the fuzzy attribute of the current entry (po-unfuzzy).

The commands z (po-next-fuzzy-entry) and Z (po-previous-fuzzy-entry) move forwards or backwards, chasing for a fuzzy entry. If none is found, the search is extended and wraps around in the PO file buffer.

The command TAB (po-unfuzzy) removes the fuzzy attribute associated with an entry, usually leaving it translated. Further, if the variable po-auto-select-on-unfuzzy has not the nil value, the TAB command will automatically chase for another interesting entry to work on. The initial value of po-auto-select-on-unfuzzy is nil.

The initial value of po-auto-fuzzy-on-edit is nil. However, if the variable po-auto-fuzzy-on-edit is set to t, any entry edited through the RET command is marked fuzzy, as a way to ensure some kind of double check, later. In this case, the usual paradigm is that an entry becomes fuzzy (if not already) whenever the translator modifies it. If she is satisfied with the translation, she then uses TAB to pick another entry to work on, clearing the fuzzy attribute on the same blow. If she is not satisfied yet, she merely uses SPC to chase another entry, leaving the entry fuzzy.

The translator may also use the DEL command (po-fade-out-entry) over any translated entry to mark it as being fuzzy, when she wants to easily leave a trace she wants to later return working at this entry.

Also, when time comes to quit working on a PO file buffer with the q command, the translator is asked for confirmation, if fuzzy string still exists.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4 Untranslated Entries

When xgettext originally creates a PO file, unless told otherwise, it initializes the msgid field with the untranslated string, and leaves the msgstr string to be empty. Such entries, having an empty translation, are said to be untranslated entries. Later, when the programmer slightly modifies some string right in the program, this change is later reflected in the PO file by the appearance of a new untranslated entry for the modified string.

The usual commands moving from entry to entry consider untranslated entries on the same level as active entries. Untranslated entries are easily recognizable by the fact they end with `msgstr ""'.

The work of the translator might be (quite naively) seen as the process of seeking for an untranslated entry, editing a translation for it, and repeating these actions until no untranslated entries remain. Some commands are more specifically related to untranslated entry processing.

u
Find the next untranslated entry (po-next-untranslated-entry).

U
Find the previous untranslated entry (po-previous-untransted-entry).

k
Turn the current entry into an untranslated one (po-kill-msgstr).

The commands u (po-next-untranslated-entry) and U (po-previous-untransted-entry) move forwards or backwards, chasing for an untranslated entry. If none is found, the search is extended and wraps around in the PO file buffer.

An entry can be turned back into an untranslated entry by merely emptying its translation, using the command k (po-kill-msgstr). See section 6.6 Modifying Translations.

Also, when time comes to quit working on a PO file buffer with the q command, the translator is asked for confirmation, if some untranslated string still exists.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.5 Obsolete Entries

By obsolete PO file entries, we mean those entries which are commented out, usually by msgmerge when it found that the translation is not needed anymore by the package being localized.

The usual commands moving from entry to entry consider obsolete entries on the same level as active entries. Obsolete entries are easily recognizable by the fact that all their lines start with #, even those lines containing msgid or msgstr.

Commands exist for emptying the translation or reinitializing it to the original untranslated string. Commands interfacing with the kill ring may force some previously saved text into the translation. The user may interactively edit the translation. All these commands may apply to obsolete entries, carefully leaving the entry obsolete after the fact.

Moreover, some commands are more specifically related to obsolete entry processing.

o
Find the next obsolete entry (po-next-obsolete-entry).

O
Find the previous obsolete entry (po-previous-obsolete-entry).

DEL
Make an active entry obsolete, or zap out an obsolete entry (po-fade-out-entry).

The commands o (po-next-obsolete-entry) and O (po-previous-obsolete-entry) move forwards or backwards, chasing for an obsolete entry. If none is found, the search is extended and wraps around in the PO file buffer.

PO mode does not provide ways for un-commenting an obsolete entry and making it active, because this would reintroduce an original untranslated string which does not correspond to any marked string in the program sources. This goes with the philosophy of never introducing useless msgid values.

However, it is possible to comment out an active entry, so making it obsolete. GNU gettext utilities will later react to the disappearance of a translation by using the untranslated string. The command DEL (po-fade-out-entry) pushes the current entry a little further towards annihilation. If the entry is active (it is a translated entry), then it is first made fuzzy. If it is already fuzzy, then the entry is merely commented out, with confirmation. If the entry is already obsolete, then it is completely deleted from the PO file. It is easy to recycle the translation so deleted into some other PO file entry, usually one which is untranslated. See section 6.6 Modifying Translations.

Here is a quite interesting problem to solve for later development of PO mode, for those nights you are not sleepy. The idea would be that PO mode might become bright enough, one of these days, to make good guesses at retrieving the most probable candidate, among all obsolete entries, for initializing the translation of a newly appeared string. I think it might be a quite hard problem to do this algorithmically, as we have to develop good and efficient measures of string similarity. Right now, PO mode completely lets the decision to the translator, when the time comes to find the adequate obsolete translation, it merely tries to provide handy tools for helping her to do so.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.6 Modifying Translations

PO mode prevents direct modification of the PO file, by the usual means Emacs gives for altering a buffer's contents. By doing so, it pretends helping the translator to avoid little clerical errors about the overall file format, or the proper quoting of strings, as those errors would be easily made. Other kinds of errors are still possible, but some may be caught and diagnosed by the batch validation process, which the translator may always trigger by the V command. For all other errors, the translator has to rely on her own judgment, and also on the linguistic reports submitted to her by the users of the translated package, having the same mother tongue.

When the time comes to create a translation, correct an error diagnosed mechanically or reported by a user, the translators have to resort to using the following commands for modifying the translations.

RET
Interactively edit the translation (po-edit-msgstr).

LFD
C-j
Reinitialize the translation with the original, untranslated string (po-msgid-to-msgstr).

k
Save the translation on the kill ring, and delete it (po-kill-msgstr).

w
Save the translation on the kill ring, without deleting it (po-kill-ring-save-msgstr).

y
Replace the translation, taking the new from the kill ring (po-yank-msgstr).

The command RET (po-edit-msgstr) opens a new Emacs window meant to edit in a new translation, or to modify an already existing translation. The new window contains a copy of the translation taken from the current PO file entry, all ready for edition, expunged of all quoting marks, fully modifiable and with the complete extent of Emacs modifying commands. When the translator is done with her modifications, she may use C-c C-c to close the subedit window with the automatically requoted results, or C-c C-k to abort her modifications. See section 6.8 Details of Sub Edition, for more information.

The command LFD (po-msgid-to-msgstr) initializes, or reinitializes the translation with the original string. This command is normally used when the translator wants to redo a fresh translation of the original string, disregarding any previous work.

It is possible to arrange so, whenever editing an untranslated entry, the LFD command be automatically executed. If you set po-auto-edit-with-msgid to t, the translation gets initialised with the original string, in case none exists already. The default value for po-auto-edit-with-msgid is nil.

In fact, whether it is best to start a translation with an empty string, or rather with a copy of the original string, is a matter of taste or habit. Sometimes, the source language and the target language are so different that is simply best to start writing on an empty page. At other times, the source and target languages are so close that it would be a waste to retype a number of words already being written in the original string. A translator may also like having the original string right under her eyes, as she will progressively overwrite the original text with the translation, even if this requires some extra editing work to get rid of the original.

The command k (po-kill-msgstr) merely empties the translation string, so turning the entry into an untranslated one. But while doing so, its previous contents is put apart in a special place, known as the kill ring. The command w (po-kill-ring-save-msgstr) has also the effect of taking a copy of the translation onto the kill ring, but it otherwise leaves the entry alone, and does not remove the translation from the entry. Both commands use exactly the Emacs kill ring, which is shared between buffers, and which is well known already to Emacs lovers.

The translator may use k or w many times in the course of her work, as the kill ring may hold several saved translations. From the kill ring, strings may later be reinserted in various Emacs buffers. In particular, the kill ring may be used for moving translation strings between different entries of a single PO file buffer, or if the translator is handling many such buffers at once, even between PO files.

To facilitate exchanges with buffers which are not in PO mode, the translation string put on the kill ring by the k command is fully unquoted before being saved: external quotes are removed, multi-line strings are concatenated, and backslash escaped sequences are turned into their corresponding characters. In the special case of obsolete entries, the translation is also uncommented prior to saving.

The command y (po-yank-msgstr) completely replaces the translation of the current entry by a string taken from the kill ring. Following Emacs terminology, we then say that the replacement string is yanked into the PO file buffer. See section `Yanking' in The Emacs Editor. The first time y is used, the translation receives the value of the most recent addition to the kill ring. If y is typed once again, immediately, without intervening keystrokes, the translation just inserted is taken away and replaced by the second most recent addition to the kill ring. By repeating y many times in a row, the translator may travel along the kill ring for saved strings, until she finds the string she really wanted.

When a string is yanked into a PO file entry, it is fully and automatically requoted for complying with the format PO files should have. Further, if the entry is obsolete, PO mode then appropriately push the inserted string inside comments. Once again, translators should not burden themselves with quoting considerations besides, of course, the necessity of the translated string itself respective to the program using it.

Note that k or w are not the only commands pushing strings on the kill ring, as almost any PO mode command replacing translation strings (or the translator comments) automatically saves the old string on the kill ring. The main exceptions to this general rule are the yanking commands themselves.

To better illustrate the operation of killing and yanking, let's use an actual example, taken from a common situation. When the programmer slightly modifies some string right in the program, his change is later reflected in the PO file by the appearance of a new untranslated entry for the modified string, and the fact that the entry translating the original or unmodified string becomes obsolete. In many cases, the translator might spare herself some work by retrieving the unmodified translation from the obsolete entry, then initializing the untranslated entry msgstr field with this retrieved translation. Once this done, the obsolete entry is not wanted anymore, and may be safely deleted.

When the translator finds an untranslated entry and suspects that a slight variant of the translation exists, she immediately uses m to mark the current entry location, then starts chasing obsolete entries with o, hoping to find some translation corresponding to the unmodified string. Once found, she uses the DEL command for deleting the obsolete entry, knowing that DEL also kills the translation, that is, pushes the translation on the kill ring. Then, r returns to the initial untranslated entry, and y then yanks the saved translation right into the msgstr field. The translator is then free to use RET for fine tuning the translation contents, and maybe to later use u, then m again, for going on with the next untranslated string.

When some sequence of keys has to be typed over and over again, the translator may find it useful to become better acquainted with the Emacs capability of learning these sequences and playing them back under request. See section `Keyboard Macros' in The Emacs Editor.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.7 Modifying Comments

Any translation work done seriously will raise many linguistic difficulties, for which decisions have to be made, and the choices further documented. These documents may be saved within the PO file in form of translator comments, which the translator is free to create, delete, or modify at will. These comments may be useful to herself when she returns to this PO file after a while.

Comments not having whitespace after the initial `#', for example, those beginning with `#.' or `#:', are not translator comments, they are exclusively created by other gettext tools. So, the commands below will never alter such system added comments, they are not meant for the translator to modify. See section 2.2 The Format of PO Files.

The following commands are somewhat similar to those modifying translations, so the general indications given for those apply here. See section 6.6 Modifying Translations.

#
Interactively edit the translator comments (po-edit-comment).

K
Save the translator comments on the kill ring, and delete it (po-kill-comment).

W
Save the translator comments on the kill ring, without deleting it (po-kill-ring-save-comment).

Y
Replace the translator comments, taking the new from the kill ring (po-yank-comment).

These commands parallel PO mode commands for modifying the translation strings, and behave much the same way as they do, except that they handle this part of PO file comments meant for translator usage, rather than the translation strings. So, if the descriptions given below are slightly succinct, it is because the full details have already been given. See section 6.6 Modifying Translations.

The command # (po-edit-comment) opens a new Emacs window containing a copy of the translator comments on the current PO file entry. If there are no such comments, PO mode understands that the translator wants to add a comment to the entry, and she is presented with an empty screen. Comment marks (#) and the space following them are automatically removed before edition, and reinstated after. For translator comments pertaining to obsolete entries, the uncommenting and recommenting operations are done twice. Once in the editing window, the keys C-c C-c allow the translator to tell she is finished with editing the comment. See section 6.8 Details of Sub Edition, for further details.

Functions found on po-subedit-mode-hook, if any, are executed after the string has been inserted in the edit buffer.

The command K (po-kill-comment) gets rid of all translator comments, while saving those comments on the kill ring. The command W (po-kill-ring-save-comment) takes a copy of the translator comments on the kill ring, but leaves them undisturbed in the current entry. The command Y (po-yank-comment) completely replaces the translator comments by a string taken at the front of the kill ring. When this command is immediately repeated, the comments just inserted are withdrawn, and replaced by other strings taken along the kill ring.

On the kill ring, all strings have the same nature. There is no distinction between translation strings and translator comments strings. So, for example, let's presume the translator has just finished editing a translation, and wants to create a new translator comment to document why the previous translation was not good, just to remember what was the problem. Foreseeing that she will do that in her documentation, the translator may want to quote the previous translation in her translator comments. To do so, she may initialize the translator comments with the previous translation, still at the head of the kill ring. Because editing already pushed the previous translation on the kill ring, she merely has to type M-w prior to #, and the previous translation will be right there, all ready for being introduced by some explanatory text.

On the other hand, presume there are some translator comments already and that the translator wants to add to those comments, instead of wholly replacing them. Then, she should edit the comment right away with #. Once inside the editing window, she can use the regular Emacs commands C-y (yank) and M-y (yank-pop) to get the previous translation where she likes.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.8 Details of Sub Edition

The PO subedit minor mode has a few peculiarities worth being described in fuller detail. It installs a few commands over the usual editing set of Emacs, which are described below.

C-c C-c
Complete edition (po-subedit-exit).

C-c C-k
Abort edition (po-subedit-abort).

C-c C-a
Consult auxiliary PO files (po-subedit-cycle-auxiliary).

The window's contents represents a translation for a given message, or a translator comment. The translator may modify this window to her heart's content. Once this is done, the command C-c C-c (po-subedit-exit) may be used to return the edited translation into the PO file, replacing the original translation, even if it moved out of sight or if buffers were switched.

If the translator becomes unsatisfied with her translation or comment, to the extent she prefers keeping what was existent prior to the RET or # command, she may use the command C-c C-k (po-subedit-abort) to merely get rid of edition, while preserving the original translation or comment. Another way would be for her to exit normally with C-c C-c, then type U once for undoing the whole effect of last edition.

The command C-c C-a (po-subedit-cycle-auxiliary) allows for glancing through translations already achieved in other languages, directly while editing the current translation. This may be quite convenient when the translator is fluent at many languages, but of course, only makes sense when such completed auxiliary PO files are already available to her (see section 6.10 Consulting Auxiliary PO Files).

Functions found on po-subedit-mode-hook, if any, are executed after the string has been inserted in the edit buffer.

While editing her translation, the translator should pay attention to not inserting unwanted RET (newline) characters at the end of the translated string if those are not meant to be there, or to removing such characters when they are required. Since these characters are not visible in the editing buffer, they are easily introduced by mistake. To help her, RET automatically puts the character < at the end of the string being edited, but this < is not really part of the string. On exiting the editing window with C-c C-c, PO mode automatically removes such < and all whitespace added after it. If the translator adds characters after the terminating <, it looses its delimiting property and integrally becomes part of the string. If she removes the delimiting <, then the edited string is taken as is, with all trailing newlines, even if invisible. Also, if the translated string ought to end itself with a genuine <, then the delimiting < may not be removed; so the string should appear, in the editing window, as ending with two < in a row.

When a translation (or a comment) is being edited, the translator may move the cursor back into the PO file buffer and freely move to other entries, browsing at will. If, with an edition pending, the translator wanders in the PO file buffer, she may decide to start modifying another entry. Each entry being edited has its own subedit buffer. It is possible to simultaneously edit the translation and the comment of a single entry, or to edit entries in different PO files, all at once. Typing RET on a field already being edited merely resumes that particular edit. Yet, the translator should better be comfortable at handling many Emacs windows!

Pending subedits may be completed or aborted in any order, regardless of how or when they were started. When many subedits are pending and the translator asks for quitting the PO file (with the q command), subedits are automatically resumed one at a time, so she may decide for each of them.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.9 C Sources Context

PO mode is particularily powerful when used with PO files created through GNU gettext utilities, as those utilities insert special comments in the PO files they generate. Some of these special comments relate the PO file entry to exactly where the untranslated string appears in the program sources.

When the translator gets to an untranslated entry, she is fairly often faced with an original string which is not as informative as it normally should be, being succinct, cryptic, or otherwise ambiguous. Before chosing how to translate the string, she needs to understand better what the string really means and how tight the translation has to be. Most of times, when problems arise, the only way left to make her judgment is looking at the true program sources from where this string originated, searching for surrounding comments the programmer might have put in there, and looking around for helping clues of any kind.

Surely, when looking at program sources, the translator will receive more help if she is a fluent programmer. However, even if she is not versed in programming and feels a little lost in C code, the translator should not be shy at taking a look, once in a while. It is most probable that she will still be able to find some of the hints she needs. She will learn quickly to not feel uncomfortable in program code, paying more attention to programmer's comments, variable and function names (if he dared chosing them well), and overall organization, than to programmation itself.

The following commands are meant to help the translator at getting program source context for a PO file entry.

s
Resume the display of a program source context, or cycle through them (po-cycle-source-reference).

M-s
Display of a program source context selected by menu (po-select-source-reference).

S
Add a directory to the search path for source files (po-consider-source-path).

M-S
Delete a directory from the search path for source files (po-ignore-source-path).

The commands s (po-cycle-source-reference) and M-s (po-select-source-reference) both open another window displaying some source program file, and already positioned in such a way that it shows an actual use of the string to be translated. By doing so, the command gives source program context for the string. But if the entry has no source context references, or if all references are unresolved along the search path for program sources, then the command diagnoses this as an error.

Even if s (or M-s) opens a new window, the cursor stays in the PO file window. If the translator really wants to get into the program source window, she ought to do it explicitly, maybe by using command O.

When s is typed for the first time, or for a PO file entry which is different of the last one used for getting source context, then the command reacts by giving the first context available for this entry, if any. If some context has already been recently displayed for the current PO file entry, and the translator wandered off to do other things, typing s again will merely resume, in another window, the context last displayed. In particular, if the translator moved the cursor away from the context in the source file, the command will bring the cursor back to the context. By using s many times in a row, with no other commands intervening, PO mode will cycle to the next available contexts for this particular entry, getting back to the first context once the last has been shown.

The command M-s behaves differently. Instead of cycling through references, it lets the translator choose a particular reference among many, and displays that reference. It is best used with completion, if the translator types TAB immediately after M-s, in response to the question, she will be offered a menu of all possible references, as a reminder of which are the acceptable answers. This command is useful only where there are really many contexts available for a single string to translate.

Program source files are usually found relative to where the PO file stands. As a special provision, when this fails, the file is also looked for, but relative to the directory immediately above it. Those two cases take proper care of most PO files. However, it might happen that a PO file has been moved, or is edited in a different place than its normal location. When this happens, the translator should tell PO mode in which directory normally sits the genuine PO file. Many such directories may be specified, and all together, they constitute what is called the search path for program sources. The command S (po-consider-source-path) is used to interactively enter a new directory at the front of the search path, and the command M-S (po-ignore-source-path) is used to select, with completion, one of the directories she does not want anymore on the search path.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.10 Consulting Auxiliary PO Files

PO mode is able to help the knowledgeable translator, being fluent in many languages, at taking advantage of translations already achieved in other languages she just happens to know. It provides these other language translations as additional context for her own work. Moreover, it has features to ease the production of translations for many languages at once, for translators preferring to work in this way.

An auxiliary PO file is an existing PO file meant for the same package the translator is working on, but targeted to a different mother tongue language. Commands exist for declaring and handling auxiliary PO files, and also for showing contexts for the entry under work.

Here are the auxiliary file commands available in PO mode.

a
Seek auxiliary files for another translation for the same entry (po-cycle-auxiliary).

C-c C-a
Switch to a particular auxiliary file (po-select-auxiliary).

A
Declare this PO file as an auxiliary file (po-consider-as-auxiliary).

M-A
Remove this PO file from the list of auxiliary files (po-ignore-as-auxiliary).

Command A (po-consider-as-auxiliary) adds the current PO file to the list of auxiliary files, while command M-A (po-ignore-as-auxiliary just removes it.

The command a (po-cycle-auxiliary) seeks all auxiliary PO files, round-robin, searching for a translated entry in some other language having an msgid field identical as the one for the current entry. The found PO file, if any, takes the place of the current PO file in the display (its window gets on top). Before doing so, the current PO file is also made into an auxiliary file, if not already. So, a in this newly displayed PO file will seek another PO file, and so on, so repeating a will eventually yield back the original PO file.

The command C-c C-a (po-select-auxiliary) asks the translator for her choice of a particular auxiliary file, with completion, and then switches to that selected PO file. The command also checks if the selected file has an msgid field identical as the one for the current entry, and if yes, this entry becomes current. Otherwise, the cursor of the selected file is left undisturbed.

For all this to work fully, auxiliary PO files will have to be normalized, in that way that msgid fields should be written exactly the same way. It is possible to write msgid fields in various ways for representing the same string, different writing would break the proper behaviour of the auxiliary file commands of PO mode. This is not expected to be much a problem in practice, as most existing PO files have their msgid entries written by the same GNU gettext tools.

However, PO files initially created by PO mode itself, while marking strings in source files, are normalised differently. So are PO files resulting of the the `M-x normalize' command. Until these discrepancies between PO mode and other GNU gettext tools get fully resolved, the translator should stay aware of normalisation issues.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.11 Using Translation Compendia

A compendium is a special PO file containing a set of translations recurring in many different packages. The translator can use gettext tools to build a new compendium, to add entries to her compendium, and to initialize untranslated entries, or to update already translated entries, from translations kept in the compendium.

6.11.1 Creating Compendia | Merging translations for later use
6.11.2 Using Compendia | Using older translations if they fit

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.11.1 Creating Compendia

Basically every PO file consisting of translated entries only can be declared as a valid compendium. Often the translator wants to have special compendia; let's consider two cases: concatenating PO files and extracting a message subset from a PO file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.11.1.1 Concatenate PO Files

To concatenate several valid PO files into one compendium file you can use `msgcomm' or `msgcat' (the latter preferred):

msgcat -o compendium.po file1.po file2.po

By default, msgcat will accumulate divergent translations for the same string. Those occurences will be marked as fuzzy and highly visible decorated; calling msgcat on `file1.po':

#: src/hello.c:200
#, c-format
msgid "Report bugs to <%s>.\n"
msgstr "Comunicar `bugs' a <%s>.\n"

and `file2.po':

#: src/bye.c:100
#, c-format
msgid "Report bugs to <%s>.\n"
msgstr "Comunicar \"bugs\" a <%s>.\n"

will result in:

#: src/hello.c:200 src/bye.c:100
#, fuzzy, c-format
msgid "Report bugs to <%s>.\n"
msgstr ""
"#-#-#-#-#  file1.po  #-#-#-#-#\n"
"Comunicar `bugs' a <%s>.\n"
"#-#-#-#-#  file2.po  #-#-#-#-#\n"
"Comunicar \"bugs\" a <%s>.\n"

The translator will have to resolve this "conflict" manually; she has to decide whether the first or the second version is appropriate (or provide a new translation), to delete the "marker lines", and finally to remove the fuzzy mark.

If the translator knows in advance the first found translation of a message is always the best translation she can make use to the `--use-first' switch:

msgcat --use-first -o compendium.po file1.po file2.po

A good compendium file must not contain fuzzy or untranslated entries. If input files are "dirty" you must preprocess the input files or postprocess the result using `msgattrib --translated --no-fuzzy'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.11.1.2 Extract a Message Subset from a PO File

Nobody wants to translate the same messages again and again; thus you may wish to have a compendium file containing `getopt.c' messages.

To extract a message subset (e.g., all `getopt.c' messages) from an existing PO file into one compendium file you can use `msggrep':

msggrep --location src/getopt.c -o compendium.po file.po

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.11.2 Using Compendia

You can use a compendium file to initialize a translation from scratch or to update an already existing translation.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.11.2.1 Initialize a New Translation File

Since a PO file with translations does not exist the translator can merely use `/dev/null' to fake the "old" translation file.

msgmerge --compendium compendium.po -o file.po /dev/null file.pot

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.11.2.2 Update an Existing Translation File

Concatenate the compendium file(s) and the existing PO, merge the result with the POT file and remove the obsolete entries (optional, here done using `sed'):

msgcat --use-first -o update.po compendium1.po compendium2.po file.po
msgmerge update.po file.pot | sed -e '/^#~/d' > file.po

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. Manipulating PO Files

Sometimes it is necessary to manipulate PO files in a way that is better performed automatically than by hand. GNU gettext includes a complete set of tools for this purpose.

When merging two packages into a single package, the resulting POT file will be the concatenation of the two packages' POT files. Thus the maintainer must concatenate the two existing package translations into a single translation catalog, for each language. This is best performed using `msgcat'. It is then the translators' duty to deal with any possible conflicts that arose during the merge.

When a translator takes over the translation job from another translator, but she uses a different character encoding in her locale, she will convert the catalog to her character encoding. This is best done through the `msgconv' program.

When a maintainer takes a source file with tagged messages from another package, he should also take the existing translations for this source file (and not let the translators do the same job twice). One way to do this is through `msggrep', another is to create a POT file for that source file and use `msgmerge'.

When a translator wants to adjust some translation catalog for a special dialect or orthography -- for example, German as written in Switzerland versus German as written in Germany -- she needs to apply some text processing to every message in the catalog. The tool for doing this is `msgfilter'.

Another use of msgfilter is to produce approximately the POT file for which a given PO file was made. This can be done through a filter command like `msgfilter sed -e d | sed -e '/^# /d''. Note that the original POT file may have had different comments and different plural message counts, that's why it's better to use the original POT file if available.

When a translator wants to check her translations, for example according to orthography rules or using a non-interactive spell checker, she can do so using the `msgexec' program.

When third party tools create PO or POT files, sometimes duplicates cannot be avoided. But the GNU gettext tools give an error when they encounter duplicate msgids in the same file and in the same domain. To merge duplicates, the `msguniq' program can be used.

`msgcomm' is a more general tool for keeping or throwing away duplicates, occurring in different files.

`msgcmp' can be used to check whether a translation catalog is completely translated.

`msgattrib' can be used to select and extract only the fuzzy or untranslated messages of a translation catalog.

`msgen' is useful as a first step for preparing English translation catalogs. It copies each message's msgid to its msgstr.

7.1 Invoking the msgcat Program
7.2 Invoking the msgconv Program
7.3 Invoking the msggrep Program
7.4 Invoking the msgfilter Program
7.5 Invoking the msguniq Program
7.6 Invoking the msgcomm Program
7.7 Invoking the msgcmp Program
7.8 Invoking the msgattrib Program
7.9 Invoking the msgen Program
7.10 Invoking the msgexec Program

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1 Invoking the msgcat Program

msgcat [option] [inputfile]...

The msgcat program concatenates and merges the specified PO files. It finds messages which are common to two or more of the specified PO files. By using the --more-than option, greater commonality may be requested before messages are printed. Conversely, the --less-than option may be used to specify less commonality before messages are printed (i.e. `--less-than=2' will only print the unique messages). Translations, comments and extract comments will be cumulated, except that if --use-first is specified, they will be taken from the first PO file to define them. File positions from all PO files will be cumulated.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1.1 Input file location

`inputfile ...'
Input files.

`-f file'
`--files-from=file'
Read the names of the input files from file instead of getting them from the command line.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If inputfile is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1.2 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1.3 Message selection

`-< number'
`--less-than=number'
Print messages with less than number definitions, defaults to infinite if not set.

`-> number'
`--more-than=number'
Print messages with more than number definitions, defaults to 0 if not set.

`-u'
`--unique'
Shorthand for `--less-than=2'. Requests that only unique messages be printed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1.4 Output details

`-t'
`--to-code=name'
Specify encoding for output.

`--use-first'
Use first available translation for each message. Don't merge several translations into one.

`--force-po'
Always write an output file even if it contains no message.

`-i'
`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`-n'
`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1.5 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2 Invoking the msgconv Program

msgconv [option] [inputfile]

The msgconv program converts a translation catalog to a different character encoding.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2.1 Input file location

`inputfile'
Input PO file.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If no inputfile is given or if it is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2.2 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2.3 Conversion target

`-t'
`--to-code=name'
Specify encoding for output.

The default encoding is the current locale's encoding.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2.4 Output details

`--force-po'
Always write an output file even if it contains no message.

`-i'
`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2.5 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3 Invoking the msggrep Program

msggrep [option] [inputfile]

The msggrep program extracts all messages of a translation catalog that match a given pattern or belong to some given source files.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3.1 Input file location

`inputfile'
Input PO file.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If no inputfile is given or if it is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3.2 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3.3 Message selection

  [-N sourcefile]... [-M domainname]...
  [-K msgid-pattern] [-T msgstr-pattern] [-C comment-pattern]

A message is selected if

  • it comes from one of the specified source files,
  • or if it comes from one of the specified domains,
  • or if `-K' is given and its key (msgid or msgid_plural) matches msgid-pattern,
  • or if `-T' is given and its translation (msgstr) matches msgstr-pattern,
  • or if `-C' is given and the translator's comment matches comment-pattern.

When more than one selection criterion is specified, the set of selected messages is the union of the selected messages of each criterion.

msgid-pattern or msgstr-pattern syntax:
  [-E | -F] [-e pattern | -f file]...
patterns are basic regular expressions by default, or extended regular expressions if -E is given, or fixed strings if -F is given.

`-N sourcefile'
`--location=sourcefile'
Select messages extracted from sourcefile. sourcefile can be either a literal file name or a wildcard pattern.

`-M domainname'
`--domain=domainname'
Select messages belonging to domain domainname.

`-K'
`--msgid'
Start of patterns for the msgid.

`-T'
`--msgstr'
Start of patterns for the msgstr.

`-E'
`--extended-regexp'
Specify that pattern is an extended regular expression.

`-F'
`--fixed-strings'
Specify that pattern is a set of newline-separated strings.

`-e pattern'
`--regexp=pattern'
Use pattern as a regular expression.

`-f file'
`--file=file'
Obtain pattern from file.

`-i'
`--ignore-case'
Ignore case distinctions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3.4 Output details

`--force-po'
Always write an output file even if it contains no message.

`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`--sort-by-file'
Sort output by file location.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3.5 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4 Invoking the msgfilter Program

msgfilter [option] filter [filter-option]

The msgfilter program applies a filter to all translations of a translation catalog.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.1 Input file location

`-i inputfile'
`--input=inputfile'
Input PO file.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If no inputfile is given or if it is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.2 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.3 The filter

The filter can be any program that reads a translation from standard input and writes a modified translation to standard output. A frequently used filter is `sed'.

Note: It is your responsibility to ensure that the filter can cope with input encoded in the translation catalog's encoding. If the filter wants input in a particular encoding, you can in a first step convert the translation catalog to that encoding using the `msgconv' program, before invoking `msgfilter'. If the filter wants input in the locale's encoding, but you want to avoid the locale's encoding, then you can first convert the translation catalog to UTF-8 using the `msgconv' program and then make `msgfilter' work in an UTF-8 locale, by using the LC_ALL environment variable.

Note: Most translations in a translation catalog don't end with a newline character. For this reason, it is important that the filter recognizes its last input line even if it ends without a newline, and that it doesn't add an undesired trailing newline at the end. The `sed' program on some platforms is known to ignore the last line of input if it is not terminated with a newline. You can use GNU sed instead; it does not have this limitation.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.4 Useful filter-options when the filter is `sed'

`-e script'
`--expression=script'
Add script to the commands to be executed.

`-f scriptfile'
`--file=scriptfile'
Add the contents of scriptfile to the commands to be executed.

`-n'
`--quiet'
`--silent'
Suppress automatic printing of pattern space.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.5 Output details

`--force-po'
Always write an output file even if it contains no message.

`--indent'
Write the .po file using indented style.

`--keep-header'
Keep the header entry, i.e. the message with `msgid ""', unmodified, instead of filtering it. By default, the header entry is subject to filtering like any other message.

`--no-location'
Do not write `#: filename:line' lines.

`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4.6 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5 Invoking the msguniq Program

msguniq [option] [inputfile]

The msguniq program unifies duplicate translations in a translation catalog. It finds duplicate translations of the same message ID. Such duplicates are invalid input for other programs like msgfmt, msgmerge or msgcat. By default, duplicates are merged together. When using the `--repeated' option, only duplicates are output, and all other messages are discarded. Comments and extracted comments will be cumulated, except that if `--use-first' is specified, they will be taken from the first translation. File positions will be cumulated. When using the `--unique' option, duplicates are discarded.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.1 Input file location

`inputfile'
Input PO file.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If no inputfile is given or if it is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.2 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.3 Message selection

`-d'
`--repeated'
Print only duplicates.

`-u'
`--unique'
Print only unique messages, discard duplicates.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.4 Output details

`-t'
`--to-code=name'
Specify encoding for output.

`--use-first'
Use first available translation for each message. Don't merge several translations into one.

`--force-po'
Always write an output file even if it contains no message.

`-i'
`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`-n'
`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.5 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.6 Invoking the msgcomm Program

msgcomm [option] [inputfile]...

The msgcomm program finds messages which are common to two or more of the specified PO files. By using the --more-than option, greater commonality may be requested before messages are printed. Conversely, the --less-than option may be used to specify less commonality before messages are printed (i.e. `--less-than=2' will only print the unique messages). Translations, comments and extract comments will be preserved, but only from the first PO file to define them. File positions from all PO files will be cumulated.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.6.1 Input file location

`inputfile ...'
Input files.

`-f file'
`--files-from=file'
Read the names of the input files from file instead of getting them from the command line.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If inputfile is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.6.2 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.6.3 Message selection

`-< number'
`--less-than=number'
Print messages with less than number definitions, defaults to infinite if not set.

`-> number'
`--more-than=number'
Print messages with more than number definitions, defaults to 1 if not set.

`-u'
`--unique'
Shorthand for `--less-than=2'. Requests that only unique messages be printed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.6.4 Output details

`--force-po'
Always write an output file even if it contains no message.

`-i'
`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`-n'
`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

`--omit-header'
Don't write header with `msgid ""' entry.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.6.5 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.7 Invoking the msgcmp Program

msgcmp [option] def.po ref.pot

The msgcmp program compares two Uniforum style .po files to check that both contain the same set of msgid strings. The def.po file is an existing PO file with the translations. The ref.pot file is the last created PO file, or a PO Template file (generally created by xgettext). This is useful for checking that you have translated each and every message in your program. Where an exact match cannot be found, fuzzy matching is used to produce better diagnostics.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.7.1 Input file location

`def.po'
Translations.

`ref.pot'
References to the sources.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.7.2 Operation modifiers

`-m'
`--multi-domain'
Apply ref.pot to each of the domains in def.po.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.7.3 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8 Invoking the msgattrib Program

msgattrib [option] [inputfile]

The msgattrib program filters the messages of a translation catalog according to their attributes, and manipulates the attributes.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8.1 Input file location

`inputfile'
Input PO file.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If no inputfile is given or if it is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8.2 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8.3 Message selection

`--translated'
Keep translated messages, remove untranslated messages.

`--untranslated'
Keep untranslated messages, remove translated messages.

`--no-fuzzy'
Remove `fuzzy' marked messages.

`--only-fuzzy'
Keep `fuzzy' marked messages, remove all other messsages.

`--no-obsolete'
Remove obsolete #~ messages.

`--only-obsolete'
Keep obsolete #~ messages, remove all other messages.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8.4 Attribute manipulation

Attributes are modified after the message selection/removal has been performed.

`--set-fuzzy'
Set all messages `fuzzy'.

`--clear-fuzzy'
Set all messages non-`fuzzy'.

`--set-obsolete'
Set all messages obsolete.

`--clear-obsolete'
Set all messages non-obsolete.

`--fuzzy'
Synonym for `--only-fuzzy --clear-fuzzy': It keeps only the fuzzy messages and removes their `fuzzy' mark.

`--obsolete'
Synonym for `--only-obsolete --clear-obsolete': It keeps only the obsolete messages and makes them non-obsolete.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8.5 Output details

`--force-po'
Always write an output file even if it contains no message.

`-i'
`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`-n'
`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8.6 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.9 Invoking the msgen Program

msgen [option] inputfile

The msgen program creates an English translation catalog. The input file is the last created English PO file, or a PO Template file (generally created by xgettext). Untranslated entries are assigned a translation that is identical to the msgid, and are marked fuzzy.

Note: `msginit --no-translator --locale=en' performs a very similar task. The main difference is that msginit cares specially about the header entry, whereas msgen doesn't.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.9.1 Input file location

`inputfile'
Input PO or POT file.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If inputfile is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.9.2 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.9.3 Output details

`--force-po'
Always write an output file even if it contains no message.

`-i'
`--indent'
Write the .po file using indented style.

`--no-location'
Do not write `#: filename:line' lines.

`--add-location'
Generate `#: filename:line' lines (default).

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

`-F'
`--sort-by-file'
Sort output by file location.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.9.4 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.10 Invoking the msgexec Program

msgexec [option] command [command-option]

The msgexec program applies a command to all translations of a translation catalog. The command can be any program that reads a translation from standard input. It is invoked once for each translation. Its output becomes msgexec's output. msgexec's return code is the maximum return code across all invocations.

A special builtin command called `0' outputs the translation, followed by a null byte. The output of `msgexec 0' is suitable as input for `xargs -0'.

During each command invocation, the environment variable MSGEXEC_MSGID is bound to the message's msgid, and the environment variable MSGEXEC_LOCATION is bound to the location in the PO file of the message.

Note: It is your responsibility to ensure that the command can cope with input encoded in the translation catalog's encoding. If the command wants input in a particular encoding, you can in a first step convert the translation catalog to that encoding using the `msgconv' program, before invoking `msgexec'. If the command wants input in the locale's encoding, but you want to avoid the locale's encoding, then you can first convert the translation catalog to UTF-8 using the `msgconv' program and then make `msgexec' work in an UTF-8 locale, by using the LC_ALL environment variable.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.10.1 Input file location

`-i inputfile'
`--input=inputfile'
Input PO file.

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If no inputfile is given or if it is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.10.2 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. Producing Binary MO Files

8.1 Invoking the msgfmt Program
8.2 Invoking the msgunfmt Program
8.3 The Format of GNU MO Files

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1 Invoking the msgfmt Program

msgfmt [option] filename.po ...

The msgfmt programs generates a binary message catalog from a textual translation description.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.1 Input file location

`filename.po ...'

`-D directory'
`--directory=directory'
Add directory to the list of directories. Source files are searched relative to this list of directories. The resulting `.po' file will be written relative to the current directory, though.

If an input file is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.2 Operation mode

`-j'
`--java'
Java mode: generate a Java ResourceBundle class.

`--java2'
Like --java, and assume Java2 (JDK 1.2 or higher).

`--tcl'
Tcl mode: generate a tcl/msgcat `.msg' file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.3 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

`--strict'
Direct the program to work strictly following the Uniforum/Sun implementation. Currently this only affects the naming of the output file. If this option is not given the name of the output file is the same as the domain name. If the strict Uniforum mode is enabled the suffix `.mo' is added to the file name if it is not already present.

We find this behaviour of Sun's implementation rather silly and so by default this mode is not selected.

If the output file is `-', output is written to standard output.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.4 Output file location in Java mode

`-r resource'
`--resource=resource'
Specify the resource name.

`-l locale'
`--locale=locale'
Specify the locale name, either a language specification of the form ll or a combined language and country specification of the form ll_CC.

`-d directory'
Specify the base directory of classes directory hierarchy.

The class name is determined by appending the locale name to the resource name, separated with an underscore. The `-d' option is mandatory. The class is written under the specified directory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.5 Output file location in Tcl mode

`-l locale'
`--locale=locale'
Specify the locale name, either a language specification of the form ll or a combined language and country specification of the form ll_CC.

`-d directory'
Specify the base directory of `.msg' message catalogs.

The `-l' and `-d' options are mandatory. The `.msg' file is written in the specified directory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.6 Input file interpretation

`-c'
`--check'
Perform all the checks implied by --check-format, --check-header, --check-domain.

`--check-format'
Check language dependent format strings.

If the string represents a format string used in a printf-like function both strings should have the same number of `%' format specifiers, with matching types. If the flag c-format or possible-c-format appears in the special comment #, for this entry a check is performed. For example, the check will diagnose using `%.*s' against `%s', or `%d' against `%s', or `%d' against `%x'. It can even handle positional parameters.

Normally the xgettext program automatically decides whether a string is a format string or not. This algorithm is not perfect, though. It might regard a string as a format string though it is not used in a printf-like function and so msgfmt might report errors where there are none.

To solve this problem the programmer can dictate the decision to the xgettext program (see section 3.5 Special Comments preceding Keywords). The translator should not consider removing the flag from the #, line. This "fix" would be reversed again as soon as msgmerge is called the next time.

`--check-header'
Verify presence and contents of the header entry. See section 5.2 Filling in the Header Entry, for a description of the various fields in the header entry.

`--check-domain'
Check for conflicts between domain directives and the --output-file option

`-C'
`--check-compatibility'
Check that GNU msgfmt behaves like X/Open msgfmt. This will give an error when attempting to use the GNU extensions.

`--check-accelerators[=char]'
Check presence of keyboard accelerators for menu items. This is based on the convention used in some GUIs that a keyboard accelerator in a menu item string is designated by an immediately preceding `&' character. Sometimes a keyboard accelerator is also called "keyboard mnemonic". This check verifies that if the untranslated string has exactly one `&' character, the translated string has exactly one `&' as well. If this option is given with a char argument, this char should be a non-alphanumeric character and is used as keyboard acceleator mark instead of `&'.

`-f'
`--use-fuzzy'
Use fuzzy entries in output. Note that using this option is usually wrong, because fuzzy messages are exactly those which have not been validated by a human translator.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.7 Output details

`-a number'
`--alignment=number'
Align strings to number bytes (default: 1).

`--no-hash'
Don't include a hash table in the binary file. Lookup will be more expensive at run time (binary search instead of hash table lookup).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1.8 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

`--statistics'
Print statistics about translations.

`-v'
`--verbose'
Increase verbosity level.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2 Invoking the msgunfmt Program

msgunfmt [option] [file]...

The msgunfmt program converts a binary message catalog to a Uniforum style .po file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.1 Operation mode

`-j'
`--java'
Java mode: input is a Java ResourceBundle class.

`--tcl'
Tcl mode: input is a tcl/msgcat `.msg' file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.2 Input file location

`file ...'
Input .mo files.

If no input file is given or if it is `-', standard input is read.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.3 Input file location in Java mode

`-r resource'
`--resource=resource'
Specify the resource name.

`-l locale'
`--locale=locale'
Specify the locale name, either a language specification of the form ll or a combined language and country specification of the form ll_CC.

The class name is determined by appending the locale name to the resource name, separated with an underscore. The class is located using the CLASSPATH.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.4 Input file location in Tcl mode

`-l locale'
`--locale=locale'
Specify the locale name, either a language specification of the form ll or a combined language and country specification of the form ll_CC.

`-d directory'
Specify the base directory of `.msg' message catalogs.

The `-l' and `-d' options are mandatory. The `.msg' file is located in the specified directory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.5 Output file location

`-o file'
`--output-file=file'
Write output to specified file.

The results are written to standard output if no output file is specified or if it is `-'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.6 Output details

`--force-po'
Always write an output file even if it contains no message.

`-i'
`--indent'
Write the .po file using indented style.

`--strict'
Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions.

`-w number'
`--width=number'
Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given number.

`--no-wrap'
Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split.

`-s'
`--sort-output'
Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2.7 Informative output

`-h'
`--help'
Display this help and exit.

`-V'
`--version'
Output version information and exit.

`-v'
`--verbose'
Increase verbosity level.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.3 The Format of GNU MO Files

The format of the generated MO files is best described by a picture, which appears below.

The first two words serve the identification of the file. The magic number will always signal GNU MO files. The number is stored in the byte order of the generating machine, so the magic number really is two numbers: 0x950412de and 0xde120495. The second word describes the current revision of the file format. For now the revision is 0. This might change in future versions, and ensures that the readers of MO files can distinguish new formats from old ones, so that both can be handled correctly. The version is kept separate from the magic number, instead of using different magic numbers for different formats, mainly because `/etc/magic' is not updated often. It might be better to have magic separated from internal format version identification.

Follow a number of pointers to later tables in the file, allowing for the extension of the prefix part of MO files without having to recompile programs reading them. This might become useful for later inserting a few flag bits, indication about the charset used, new tables, or other things.

Then, at offset O and offset T in the picture, two tables of string descriptors can be found. In both tables, each string descriptor uses two 32 bits integers, one for the string length, another for the offset of the string in the MO file, counting in bytes from the start of the file. The first table contains descriptors for the original strings, and is sorted so the original strings are in increasing lexicographical order. The second table contains descriptors for the translated strings, and is parallel to the first table: to find the corresponding translation one has to access the array slot in the second array with the same index.

Having the original strings sorted enables the use of simple binary search, for when the MO file does not contain an hashing table, or for when it is not practical to use the hashing table provided in the MO file. This also has another advantage, as the empty string in a PO file GNU gettext is usually translated into some system information attached to that particular MO file, and the empty string necessarily becomes the first in both the original and translated tables, making the system information very easy to find.

The size S of the hash table can be zero. In this case, the hash table itself is not contained in the MO file. Some people might prefer this because a precomputed hashing table takes disk space, and does not win that much speed. The hash table contains indices to the sorted array of strings in the MO file. Conflict resolution is done by double hashing. The precise hashing algorithm used is fairly dependent on GNU gettext code, and is not documented here.

As for the strings themselves, they follow the hash file, and each is terminated with a NUL, and this NUL is not counted in the length which appears in the string descriptor. The msgfmt program has an option selecting the alignment for MO file strings. With this option, each string is separately aligned so it starts at an offset which is a multiple of the alignment value. On some RISC machines, a correct alignment will speed things up.

Plural forms are stored by letting the plural of the original string follow the singular of the original string, separated through a NUL byte. The length which appears in the string descriptor includes both. However, only the singular of the original string takes part in the hash table lookup. The plural variants of the translation are all stored consecutively, separated through a NUL byte. Here also, the length in the string descriptor includes all of them.

Nothing prevents a MO file from having embedded NULs in strings. However, the program interface currently used already presumes that strings are NUL terminated, so embedded NULs are somewhat useless. But the MO file format is general enough so other interfaces would be later possible, if for example, we ever want to implement wide characters right in MO files, where NUL bytes may accidently appear. (No, we don't want to have wide characters in MO files. They would make the file unnecessarily large, and the `wchar_t' type being platform dependent, MO files would be platform dependent as well.)

This particular issue has been strongly debated in the GNU gettext development forum, and it is expectable that MO file format will evolve or change over time. It is even possible that many formats may later be supported concurrently. But surely, we have to start somewhere, and the MO file format described here is a good start. Nothing is cast in concrete, and the format may later evolve fairly easily, so we should feel comfortable with the current approach.

        byte
             +------------------------------------------+
          0  | magic number = 0x950412de                |
             |                                          |
          4  | file format revision = 0                 |
             |                                          |
          8  | number of strings                        |  == N
             |                                          |
         12  | offset of table with original strings    |  == O
             |                                          |
         16  | offset of table with translation strings |  == T
             |                                          |
         20  | size of hashing table                    |  == S
             |                                          |
         24  | offset of hashing table                  |  == H
             |                                          |
             .                                          .
             .    (possibly more entries later)         .
             .                                          .
             |                                          |
          O  | length & offset 0th string  ----------------.
      O + 8  | length & offset 1st string  ------------------.
              ...                                    ...   | |
O + ((N-1)*8)| length & offset (N-1)th string           |  | |
             |                                          |  | |
          T  | length & offset 0th translation  ---------------.
      T + 8  | length & offset 1st translation  -----------------.
              ...                                    ...   | | | |
T + ((N-1)*8)| length & offset (N-1)th translation      |  | | | |
             |                                          |  | | | |
          H  | start hash table                         |  | | | |
              ...                                    ...   | | | |
  H + S * 4  | end hash table                           |  | | | |
             |                                          |  | | | |
             | NUL terminated 0th string  <----------------' | | |
             |                                          |    | | |
             | NUL terminated 1st string  <------------------' | |
             |                                          |      | |
              ...                                    ...       | |
             |                                          |      | |
             | NUL terminated 0th translation  <---------------' |
             |                                          |        |
             | NUL terminated 1st translation  <-----------------'
             |                                          |
              ...                                    ...
             |                                          |
             +------------------------------------------+

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. The User's View

When GNU gettext will truly have reached its goal, average users should feel some kind of astonished pleasure, seeing the effect of that strange kind of magic that just makes their own native language appear everywhere on their screens. As for naive users, they would ideally have no special pleasure about it, merely taking their own language for granted, and becoming rather unhappy otherwise.

So, let's try to describe here how we would like the magic to operate, as we want the users' view to be the simplest, among all ways one could look at GNU gettext. All other software engineers: programmers, translators, maintainers, should work together in such a way that the magic becomes possible. This is a long and progressive undertaking, and information is available about the progress of the Translation Project.

When a package is distributed, there are two kinds of users: installers who fetch the distribution, unpack it, configure it, compile it and install it for themselves or others to use; and end users that call programs of the package, once these have been installed at their site. GNU gettext is offering magic for both installers and end users.

9.1 The Current `ABOUT-NLS' Matrix
9.2 Magic for Installers
9.3 Magic for End Users

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1 The Current `ABOUT-NLS' Matrix

Languages are not equally supported in all packages using GNU gettext. To know if some package uses GNU gettext, one may check the distribution for the `ABOUT-NLS' information file, for some `ll.po' files, often kept together into some `po/' directory, or for an `intl/' directory. Internationalized packages have usually many `ll.po' files, where ll represents the language. 9.3 Magic for End Users for a complete description of the format for ll.

More generally, a matrix is available for showing the current state of the Translation Project, listing which packages are prepared for multi-lingual messages, and which languages are supported by each. Because this information changes often, this matrix is not kept within this GNU gettext manual. This information is often found in file `ABOUT-NLS' from various distributions, but is also as old as the distribution itself. A recent copy of this `ABOUT-NLS' file, containing up-to-date information, should generally be found on the Translation Project sites, and also on most GNU archive sites.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.2 Magic for Installers

By default, packages fully using GNU gettext, internally, are installed in such a way that they to allow translation of messages. At configuration time, those packages should automatically detect whether the underlying host system already provides the GNU gettext functions. If not, the GNU gettext library should be automatically prepared and used. Installers may use special options at configuration time for changing this behavior. The command `./configure --with-included-gettext' bypasses system gettext to use the included GNU gettext instead, while `./configure --disable-nls' produces programs totally unable to translate messages.

Internationalized packages have usually many `ll.po' files. Unless translations are disabled, all those available are installed together with the package. However, the environment variable LINGUAS may be set, prior to configuration, to limit the installed set. LINGUAS should then contain a space separated list of two-letter codes, stating which languages are allowed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3 Magic for End Users

We consider here those packages using GNU gettext internally, and for which the installers did not disable translation at configure time. Then, users only have to set the LANG environment variable to the appropriate `ll_CC' combination prior to using the programs in the package. See section 9.1 The Current `ABOUT-NLS' Matrix. For example, let's presume a German site. At the shell prompt, users merely have to execute `setenv LANG de_DE' (in csh) or `export LANG; LANG=de_DE' (in sh). They could even do this from their `.login' or `.profile' file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10. The Programmer's View

One aim of the current message catalog implementation provided by GNU gettext was to use the system's message catalog handling, if the installer wishes to do so. So we perhaps should first take a look at the solutions we know about. The people in the POSIX committee did not manage to agree on one of the semi-official standards which we'll describe below. In fact they couldn't agree on anything, so they decided only to include an example of an interface. The major Unix vendors are split in the usage of the two most important specifications: X/Open's catgets vs. Uniforum's gettext interface. We'll describe them both and later explain our solution of this dilemma.

10.1 About catgets
10.2 About gettext
10.3 Comparing the Two Interfaces Comparing the two interfaces
10.4 Using libintl.a in own programs
10.5 Being a gettext grok
10.6 Temporary Notes for the Programmers Chapter

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.1 About catgets

The catgets implementation is defined in the X/Open Portability Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the process of creating this standard seemed to be too slow for some of the Unix vendors so they created their implementations on preliminary versions of the standard. Of course this leads again to problems while writing platform independent programs: even the usage of catgets does not guarantee a unique interface.

Another, personal comment on this that only a bunch of committee members could have made this interface. They never really tried to program using this interface. It is a fast, memory-saving implementation, an user can happily live with it. But programmers hate it (at least I and some others do...)

But we must not forget one point: after all the trouble with transfering the rights on Unix(tm) they at last came to X/Open, the very same who published this specification. This leads me to making the prediction that this interface will be in future Unix standards (e.g. Spec1170) and therefore part of all Unix implementation (implementations, which are allowed to wear this name).

10.1.1 The Interface | The interface
10.1.2 Problems with the catgets Interface?! | Problems with the catgets interface?!

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.1.1 The Interface

The interface to the catgets implementation consists of three functions which correspond to those used in file access: catopen to open the catalog for using, catgets for accessing the message tables, and catclose for closing after work is done. Prototypes for the functions and the needed definitions are in the <nl_types.h> header file.

catopen is used like in this:

nl_catd catd = catopen ("catalog_name", 0);

The function takes as the argument the name of the catalog. This usual refers to the name of the program or the package. The second parameter is not further specified in the standard. I don't even know whether it is implemented consistently among various systems. So the common advice is to use 0 as the value. The return value is a handle to the message catalog, equivalent to handles to file returned by open.

This handle is of course used in the catgets function which can be used like this:

char *translation = catgets (catd, set_no, msg_id, "original string");

The first parameter is this catalog descriptor. The second parameter specifies the set of messages in this catalog, in which the message described by msg_id is obtained. catgets therefore uses a three-stage addressing:

catalog name => set number => message ID => translation

The fourth argument is not used to address the translation. It is given as a default value in case when one of the addressing stages fail. One important thing to remember is that although the return type of catgets is char * the resulting string must not be changed. It should better be const char *, but the standard is published in 1988, one year before ANSI C.

The last of these function functions is used and behaves as expected:

catclose (catd);

After this no catgets call using the descriptor is legal anymore.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.1.2 Problems with the catgets Interface?!

Now that this description seemed to be really easy -- where are the problems we speak of? In fact the interface could be used in a reasonable way, but constructing the message catalogs is a pain. The reason for this lies in the third argument of catgets: the unique message ID. This has to be a numeric value for all messages in a single set. Perhaps you could imagine the problems keeping such a list while changing the source code. Add a new message here, remove one there. Of course there have been developed a lot of tools helping to organize this chaos but one as the other fails in one aspect or the other. We don't want to say that the other approach has no problems but they are far more easy to manage.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2 About gettext

The definition of the gettext interface comes from a Uniforum proposal and it is followed by at least one major Unix vendor (Sun) in its last developments. It is not specified in any official standard, though.

The main points about this solution is that it does not follow the method of normal file handling (open-use-close) and that it does not burden the programmer so many task, especially the unique key handling. Of course here also a unique key is needed, but this key is the message itself (how long or short it is). See 10.3 Comparing the Two Interfaces for a more detailed comparison of the two methods.

The following section contains a rather detailed description of the interface. We make it that detailed because this is the interface we chose for the GNU gettext Library. Programmers interested in using this library will be interested in this description.

10.2.1 The Interface | The interface
10.2.2 Solving Ambiguities | Solving ambiguities
10.2.3 Locating Message Catalog Files | Locating message catalog files
10.2.4 How to specify the output character set gettext uses | How to request conversion to Unicode
10.2.5 Additional functions for plural forms | Additional functions for handling plurals
10.2.6 How to use gettext in GUI programs | Another technique for solving ambiguities
10.2.7 Optimization of the *gettext functions

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2.1 The Interface

The minimal functionality an interface must have is a) to select a domain the strings are coming from (a single domain for all programs is not reasonable because its construction and maintenance is difficult, perhaps impossible) and b) to access a string in a selected domain.

This is principally the description of the gettext interface. It has a global domain which unqualified usages reference. Of course this domain is selectable by the user.

char *textdomain (const char *domain_name);

This provides the possibility to change or query the current status of the current global domain of the LC_MESSAGE category. The argument is a null-terminated string, whose characters must be legal in the use in filenames. If the domain_name argument is NULL, the function returns the current value. If no value has been set before, the name of the default domain is returned: messages. Please note that although the return value of textdomain is of type char * no changing is allowed. It is also important to know that no checks of the availability are made. If the name is not available you will see this by the fact that no translations are provided.

To use a domain set by textdomain the function

char *gettext (const char *msgid);

is to be used. This is the simplest reasonable form one can imagine. The translation of the string msgid is returned if it is available in the current domain. If not available the argument itself is returned. If the argument is NULL the result is undefined.

One things which should come into mind is that no explicit dependency to the used domain is given. The current value of the domain for the LC_MESSAGES locale is used. If this changes between two executions of the same gettext call in the program, both calls reference a different message catalog.

For the easiest case, which is normally used in internationalized packages, once at the beginning of execution a call to textdomain is issued, setting the domain to a unique name, normally the package name. In the following code all strings which have to be translated are filtered through the gettext function. That's all, the package speaks your language.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2.2 Solving Ambiguities

While this single name domain works well for most applications there might be the need to get translations from more than one domain. Of course one could switch between different domains with calls to textdomain, but this is really not convenient nor is it fast. A possible situation could be one case subject to discussion during this writing: all error messages of functions in the set of common used functions should go into a separate domain error. By this mean we would only need to translate them once. Another case are messages from a library, as these have to be independent of the current domain set by the application.

For this reasons there are two more functions to retrieve strings:

char *dgettext (const char *domain_name, const char *msgid);
char *dcgettext (const char *domain_name, const char *msgid,
                 int category);

Both take an additional argument at the first place, which corresponds to the argument of textdomain. The third argument of dcgettext allows to use another locale but LC_MESSAGES. But I really don't know where this can be useful. If the domain_name is NULL or category has an value beside the known ones, the result is undefined. It should also be noted that this function is not part of the second known implementation of this function family, the one found in Solaris.

A second ambiguity can arise by the fact, that perhaps more than one domain has the same name. This can be solved by specifying where the needed message catalog files can be found.

char *bindtextdomain (const char *domain_name,
                      const char *dir_name);

Calling this function binds the given domain to a file in the specified directory (how this file is determined follows below). Especially a file in the systems default place is not favored against the specified file anymore (as it would be by solely using textdomain). A NULL pointer for the dir_name parameter returns the binding associated with domain_name. If domain_name itself is NULL nothing happens and a NULL pointer is returned. Here again as for all the other functions is true that none of the return value must be changed!

It is important to remember that relative path names for the dir_name parameter can be trouble. Since the path is always computed relative to the current directory different results will be achieved when the program executes a chdir command. Relative paths should always be avoided to avoid dependencies and unreliabilities.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2.3 Locating Message Catalog Files

Because many different languages for many different packages have to be stored we need some way to add these information to file message catalog files. The way usually used in Unix environments is have this encoding in the file name. This is also done here. The directory name given in bindtextdomains second argument (or the default directory), followed by the value and name of the locale and the domain name are concatenated:

dir_name/locale/LC_category/domain_name.mo

The default value for dir_name is system specific. For the GNU library, and for packages adhering to its conventions, it's:
/usr/local/share/locale

locale is the value of the locale whose name is this LC_category. For gettext and dgettext this LC_category is always LC_MESSAGES.(3) The value of the locale is determined through setlocale (LC_category, NULL). (4) dcgettext specifies the locale category by the third argument.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2.4 How to specify the output character set gettext uses

gettext not only looks up a translation in a message catalog. It also converts the translation on the fly to the desired output character set. This is useful if the user is working in a different character set than the translator who created the message catalog, because it avoids distributing variants of message catalogs which differ only in the character set.

The output character set is, by default, the value of nl_langinfo (CODESET), which depends on the LC_CTYPE part of the current locale. But programs which store strings in a locale independent way (e.g. UTF-8) can request that gettext and related functions return the translations in that encoding, by use of the bind_textdomain_codeset function.

Note that the msgid argument to gettext is not subject to character set conversion. Also, when gettext does not find a translation for msgid, it returns msgid unchanged -- independently of the current output character set. It is therefore recommended that all msgids be US-ASCII strings.

Function: char * bind_textdomain_codeset (const char *domainname, const char *codeset)
The bind_textdomain_codeset function can be used to specify the output character set for message catalogs for domain domainname. The codeset argument must be a valid codeset name which can be used for the iconv_open function, or a null pointer.

If the codeset parameter is the null pointer, bind_textdomain_codeset returns the currently selected codeset for the domain with the name domainname. It returns NULL if no codeset has yet been selected.

The bind_textdomain_codeset function can be used several times. If used multiple times with the same domainname argument, the later call overrides the settings made by the earlier one.

The bind_textdomain_codeset function returns a pointer to a string containing the name of the selected codeset. The string is allocated internally in the function and must not be changed by the user. If the system went out of core during the execution of bind_textdomain_codeset, the return value is NULL and the global variable errno is set accordingly.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2.5 Additional functions for plural forms

The functions of the gettext family described so far (and all the catgets functions as well) have one problem in the real world which have been neglected completely in all existing approaches. What is meant here is the handling of plural forms.

Looking through Unix source code before the time anybody thought about internationalization (and, sadly, even afterwards) one can often find code similar to the following:

   printf ("%d file%s deleted", n, n == 1 ? "" : "s");

After the first complaints from people internationalizing the code people either completely avoided formulations like this or used strings like "file(s)". Both look unnatural and should be avoided. First tries to solve the problem correctly looked like this:

   if (n == 1)
     printf ("%d file deleted", n);
   else
     printf ("%d files deleted", n);

But this does not solve the problem. It helps languages where the plural form of a noun is not simply constructed by adding an `s' but that is all. Once again people fell into the trap of believing the rules their language is using are universal. But the handling of plural forms differs widely between the language families. For example, Rafal Maszkowski <rzm@mat.uni.torun.pl> reports:

In Polish we use e.g. plik (file) this way:
1 plik
2,3,4 pliki
5-21 pliko'w
22-24 pliki
25-31 pliko'w
and so on (o' means 8859-2 oacute which should be rather okreska, similar to aogonek).

There are two things which can differ between languages (and even inside language families);

  • The form how plural forms are built differs. This is a problem with languages which have many irregularities. German, for instance, is a drastic case. Though English and German are part of the same language family (Germanic), the almost regular forming of plural noun forms (appending an `s') is hardly found in German.

  • The number of plural forms differ. This is somewhat surprising for those who only have experiences with Romanic and Germanic languages since here the number is the same (there are two).

    But other language families have only one form or many forms. More information on this in an extra section.

The consequence of this is that application writers should not try to solve the problem in their code. This would be localization since it is only usable for certain, hardcoded language environments. Instead the extended gettext interface should be used.

These extra functions are taking instead of the one key string two strings and a numerical argument. The idea behind this is that using the numerical argument and the first string as a key, the implementation can select using rules specified by the translator the right plural form. The two string arguments then will be used to provide a return value in case no message catalog is found (similar to the normal gettext behavior). In this case the rules for Germanic language is used and it is assumed that the first string argument is the singular form, the second the plural form.

This has the consequence that programs without language catalogs can display the correct strings only if the program itself is written using a Germanic language. This is a limitation but since the GNU C library (as well as the GNU gettext package) are written as part of the GNU package and the coding standards for the GNU project require program being written in English, this solution nevertheless fulfills its purpose.

Function: char * ngettext (const char *msgid1, const char *msgid2, unsigned long int n)
The ngettext function is similar to the gettext function as it finds the message catalogs in the same way. But it takes two extra arguments. The msgid1 parameter must contain the singular form of the string to be converted. It is also used as the key for the search in the catalog. The msgid2 parameter is the plural form. The parameter n is used to determine the plural form. If no message catalog is found msgid1 is returned if n == 1, otherwise msgid2.

An example for the use of this function is:

printf (ngettext ("%d file removed", "%d files removed", n), n);

Please note that the numeric value n has to be passed to the printf function as well. It is not sufficient to pass it only to ngettext.

Function: char * dngettext (const char *domain, const char *msgid1, const char *msgid2, unsigned long int n)
The dngettext is similar to the dgettext function in the way the message catalog is selected. The difference is that it takes two extra parameter to provide the correct plural form. These two parameters are handled in the same way ngettext handles them.

Function: char * dcngettext (const char *domain, const char *msgid1, const char *msgid2, unsigned long int n, int category)
The dcngettext is similar to the dcgettext function in the way the message catalog is selected. The difference is that it takes two extra parameter to provide the correct plural form. These two parameters are handled in the same way ngettext handles them.

Now, how do these functions solve the problem of the plural forms? Without the input of linguists (which was not available) it was not possible to determine whether there are only a few different forms in which plural forms are formed or whether the number can increase with every new supported language.

Therefore the solution implemented is to allow the translator to specify the rules of how to select the plural form. Since the formula varies with every language this is the only viable solution except for hardcoding the information in the code (which still would require the possibility of extensions to not prevent the use of new languages).

The information about the plural form selection has to be stored in the header entry of the PO file (the one with the empty msgid string). The plural form information looks like this:

Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;

The nplurals value must be a decimal number which specifies how many different plural forms exist for this language. The string following plural is an expression which is using the C language syntax. Exceptions are that no negative numbers are allowed, numbers must be decimal, and the only variable allowed is n. This expression will be evaluated whenever one of the functions ngettext, dngettext, or dcngettext is called. The numeric value passed to these functions is then substituted for all uses of the variable n in the expression. The resulting value then must be greater or equal to zero and smaller than the value given as the value of nplurals.

The following rules are known at this point. The language with families are listed. But this does not necessarily mean the information can be generalized for the whole family (as can be easily seen in the table below).(5)

Only one form:
Some languages only require one single form. There is no distinction between the singular and plural form. An appropriate header entry would look like this:

Plural-Forms: nplurals=1; plural=0;

Languages with this property include:

Finno-Ugric family
Hungarian
Asian family
Japanese, Korean
Turkic/Altaic family
Turkish

Two forms, singular used for one only
This is the form used in most existing programs since it is what English is using. A header entry would look like this:

Plural-Forms: nplurals=2; plural=n != 1;

(Note: this uses the feature of C expressions that boolean expressions have to value zero or one.)

Languages with this property include:

Germanic family
Danish, Dutch, English, German, Norwegian, Swedish
Finno-Ugric family
Estonian, Finnish
Latin/Greek family
Greek
Semitic family
Hebrew
Romanic family
Italian, Portuguese, Spanish
Artificial
Esperanto

Two forms, singular used for zero and one
Exceptional case in the language family. The header entry would be:

Plural-Forms: nplurals=2; plural=n>1;

Languages with this property include:

Romanic family
French, Brazilian Portuguese

Three forms, special case for zero
The header entry would be:

Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;

Languages with this property include:

Baltic family
Latvian

Three forms, special cases for one and two
The header entry would be:

Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;

Languages with this property include:

Celtic
Gaeilge (Irish)

Three forms, special case for numbers ending in 1[2-9]
The header entry would look like this:

Plural-Forms: nplurals=3; \
    plural=n%10==1 && n%100!=11 ? 0 : \
           n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;

Languages with this property include:

Baltic family
Lithuanian

Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
The header entry would look like this:

Plural-Forms: nplurals=3; \
    plural=n%10==1 && n%100!=11 ? 0 : \
           n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;

Languages with this property include:

Slavic family
Croatian, Czech, Russian, Slovak, Ukrainian

Three forms, special case for one and some numbers ending in 2, 3, or 4
The header entry would look like this:

Plural-Forms: nplurals=3; \
    plural=n==1 ? 0 : \
           n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;

Languages with this property include:

Slavic family
Polish

Four forms, special case for one and all numbers ending in 02, 03, or 04
The header entry would look like this:

Plural-Forms: nplurals=4; \
    plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;

Languages with this property include:

Slavic family
Slovenian

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2.6 How to use gettext in GUI programs

One place where the gettext functions, if used normally, have big problems is within programs with graphical user interfaces (GUIs). The problem is that many of the strings which have to be translated are very short. They have to appear in pull-down menus which restricts the length. But strings which are not containing entire sentences or at least large fragments of a sentence may appear in more than one situation in the program but might have different translations. This is especially true for the one-word strings which are frequently used in GUI programs.

As a consequence many people say that the gettext approach is wrong and instead catgets should be used which indeed does not have this problem. But there is a very simple and powerful method to handle these kind of problems with the gettext functions.

As as example consider the following fictional situation. A GUI program has a menu bar with the following entries:

+------------+------------+--------------------------------------+
| File       | Printer    |                                      |
+------------+------------+--------------------------------------+
| Open     | | Select   |
| New      | | Open     |
+----------+ | Connect  |
             +----------+

To have the strings File, Printer, Open, New, Select, and Connect translated there has to be at some point in the code a call to a function of the gettext family. But in two places the string passed into the function would be Open. The translations might not be the same and therefore we are in the dilemma described above.

One solution to this problem is to artificially enlengthen the strings to make them unambiguous. But what would the program do if no translation is available? The enlengthened string is not what should be printed. So we should use a little bit modified version of the functions.

To enlengthen the strings a uniform method should be used. E.g., in the example above the strings could be chosen as

Menu|File
Menu|Printer
Menu|File|Open
Menu|File|New
Menu|Printer|Select
Menu|Printer|Open
Menu|Printer|Connect

Now all the strings are different and if now instead of gettext the following little wrapper function is used, everything works just fine:

  char *
  sgettext (const char *msgid)
  {
    char *msgval = gettext (msgid);
    if (msgval == msgid)
      msgval = strrchr (msgid, '|') + 1;
    return msgval;
  }

What this little function does is to recognize the case when no translation is available. This can be done very efficiently by a pointer comparison since the return value is the input value. If there is no translation we know that the input string is in the format we used for the Menu entries and therefore contains a | character. We simply search for the last occurrence of this character and return a pointer to the character following it. That's it!

If one now consistently uses the enlengthened string form and replaces the gettext calls with calls to sgettext (this is normally limited to very few places in the GUI implementation) then it is possible to produce a program which can be internationalized.

The other gettext functions (dgettext, dcgettext and the ngettext equivalents) can and should have corresponding functions as well which look almost identical, except for the parameters and the call to the underlying function.

Now there is of course the question why such functions do not exist in the GNU gettext package? There are two parts of the answer to this question.

  • They are easy to write and therefore can be provided by the project they are used in. This is not an answer by itself and must be seen together with the second part which is:

  • There is no way the gettext package can contain a version which can work everywhere. The problem is the selection of the character to separate the prefix from the actual string in the enlenghtened string. The examples above used | which is a quite good choice because it resembles a notation frequently used in this context and it also is a character not often used in message strings.

    But what if the character is used in message strings? Or if the chose character is not available in the character set on the machine one compiles (e.g., | is not required to exist for ISO C; this is why the `iso646.h' file exists in ISO C programming environments).

There is only one more comment to be said. The wrapper function above requires that the translations strings are not enlengthened themselves. This is only logical. There is no need to disambiguate the strings (since they are never used as keys for a search) and one also saves quite some memory and disk space by doing this.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2.7 Optimization of the *gettext functions

At this point of the discussion we should talk about an advantage of the GNU gettext implementation. Some readers might have pointed out that an internationalized program might have a poor performance if some string has to be translated in an inner loop. While this is unavoidable when the string varies from one run of the loop to the other it is simply a waste of time when the string is always the same. Take the following example:

{
  while (...)
    {
      puts (gettext ("Hello world"));
    }
}

When the locale selection does not change between two runs the resulting string is always the same. One way to use this is:

{
  str = gettext ("Hello world");
  while (...)
    {
      puts (str);
    }
}

But this solution is not usable in all situation (e.g. when the locale selection changes) nor does it lead to legible code.

For this reason, GNU gettext caches previous translation results. When the same translation is requested twice, with no new message catalogs being loaded in between, gettext will, the second time, find the result through a single cache lookup.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.3 Comparing the Two Interfaces

The following discussion is perhaps a little bit colored. As said above we implemented GNU gettext following the Uniforum proposal and this surely has its reasons. But it should show how we came to this decision.

First we take a look at the developing process. When we write an application using NLS provided by gettext we proceed as always. Only when we come to a string which might be seen by the users and thus has to be translated we use gettext("...") instead of "...". At the beginning of each source file (or in a central header file) we define

#define gettext(String) (String)

Even this definition can be avoided when the system supports the gettext function in its C library. When we compile this code the result is the same as if no NLS code is used. When you take a look at the GNU gettext code you will see that we use _("...") instead of gettext("..."). This reduces the number of additional characters per translatable string to 3 (in words: three).

When now a production version of the program is needed we simply replace the definition

#define _(String) (String)

by

#include <libintl.h>
#define _(String) gettext (String)

Additionally we run the program `xgettext' on all source code file which contain translatable strings and that's it: we have a running program which does not depend on translations to be available, but which can use any that becomes available.

The same procedure can be done for the gettext_noop invocations (see section 3.6 Special Cases of Translatable Strings). One usually defines gettext_noop as a no-op macro. So you should consider the following code for your project:

#define gettext_noop(String) String
#define N_(String) gettext_noop (String)

N_ is a short form similar to _. The `Makefile' in the `po/' directory of GNU gettext knows by default both of the mentioned short forms so you are invited to follow this proposal for your own ease.

Now to catgets. The main problem is the work for the programmer. Every time he comes to a translatable string he has to define a number (or a symbolic constant) which has also be defined in the message catalog file. He also has to take care for duplicate entries, duplicate message IDs etc. If he wants to have the same quality in the message catalog as the GNU gettext program provides he also has to put the descriptive comments for the strings and the location in all source code files in the message catalog. This is nearly a Mission: Impossible.

But there are also some points people might call advantages speaking for catgets. If you have a single word in a string and this string is used in different contexts it is likely that in one or the other language the word has different translations. Example:

printf ("%s: %d", gettext ("number"), number_of_errors)

printf ("you should see %d %s", number_count,
        number_count == 1 ? gettext ("number") : gettext ("numbers"))

Here we have to translate two times the string "number". Even if you do not speak a language beside English it might be possible to recognize that the two words have a different meaning. In German the first appearance has to be translated to "Anzahl" and the second to "Zahl".

Now you can say that this example is really esoteric. And you are right! This is exactly how we felt about this problem and decide that it does not weight that much. The solution for the above problem could be very easy:

printf ("%s %d", gettext ("number:"), number_of_errors)

printf (number_count == 1 ? gettext ("you should see %d number")
                          : gettext ("you should see %d numbers"),
        number_count)

We believe that we can solve all conflicts with this method. If it is difficult one can also consider changing one of the conflicting string a little bit. But it is not impossible to overcome.

catgets allows same original entry to have different translations, but gettext has another, scalable approach for solving ambiguities of this kind: See section 10.2.2 Solving Ambiguities.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.4 Using libintl.a in own programs

Starting with version 0.9.4 the library libintl.h should be self-contained. I.e., you can use it in your own programs without providing additional functions. The `Makefile' will put the header and the library in directories selected using the $(prefix).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.5 Being a gettext grok

To fully exploit the functionality of the GNU gettext library it is surely helpful to read the source code. But for those who don't want to spend that much time in reading the (sometimes complicated) code here is a list comments:

  • Changing the language at runtime

    For interactive programs it might be useful to offer a selection of the used language at runtime. To understand how to do this one need to know how the used language is determined while executing the gettext function. The method which is presented here only works correctly with the GNU implementation of the gettext functions.

    In the function dcgettext at every call the current setting of the highest priority environment variable is determined and used. Highest priority means here the following list with decreasing priority:

    1. LANGUAGE
    2. LC_ALL
    3. LC_xxx, according to selected locale
    4. LANG

    Afterwards the path is constructed using the found value and the translation file is loaded if available.

    What is now when the value for, say, LANGUAGE changes. According to the process explained above the new value of this variable is found as soon as the dcgettext function is called. But this also means the (perhaps) different message catalog file is loaded. In other words: the used language is changed.

    But there is one little hook. The code for gcc-2.7.0 and up provides some optimization. This optimization normally prevents the calling of the dcgettext function as long as no new catalog is loaded. But if dcgettext is not called the program also cannot find the LANGUAGE variable be changed (see section 10.2.7 Optimization of the *gettext functions). A solution for this is very easy. Include the following code in the language switching function.

      /* Change language.  */
  setenv ("LANGUAGE", "fr", 1);

  /* Make change known.  */
  {
    extern int  _nl_msg_cat_cntr;
    ++_nl_msg_cat_cntr;
  }

    The variable _nl_msg_cat_cntr is defined in `loadmsgcat.c'. You don't need to know what this is for. But it can be used to detect whether a gettext implementation is GNU gettext and not non-GNU system's native gettext implementation.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.6 Temporary Notes for the Programmers Chapter

10.6.1 Temporary - Two Possible Implementations
10.6.2 Temporary - About catgets
10.6.3 Temporary - Why a single implementation
10.6.4 Temporary - Notes

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.6.1 Temporary - Two Possible Implementations

There are two competing methods for language independent messages: the X/Open catgets method, and the Uniforum gettext method. The catgets method indexes messages by integers; the gettext method indexes them by their English translations. The catgets method has been around longer and is supported by more vendors. The gettext method is supported by Sun, and it has been heard that the COSE multi-vendor initiative is supporting it. Neither method is a POSIX standard; the POSIX.1 committee had a lot of disagreement in this area.

Neither one is in the POSIX standard. There was much disagreement in the POSIX.1 committee about using the gettext routines vs. catgets (XPG). In the end the committee couldn't agree on anything, so no messaging system was included as part of the standard. I believe the informative annex of the standard includes the XPG3 messaging interfaces, "...as an example of a messaging system that has been implemented..."

They were very careful not to say anywhere that you should use one set of interfaces over the other. For more on this topic please see the Programming for Internationalization FAQ.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.6.2 Temporary - About catgets

There have been a few discussions of late on the use of catgets as a base. I think it important to present both sides of the argument and hence am opting to play devil's advocate for a little bit.

I'll not deny the fact that catgets could have been designed a lot better. It currently has quite a number of limitations and these have already been pointed out.

However there is a great deal to be said for consistency and standardization. A common recurring problem when writing Unix software is the myriad portability problems across Unix platforms. It seems as if every Unix vendor had a look at the operating system and found parts they could improve upon. Undoubtedly, these modifications are probably innovative and solve real problems. However, software developers have a hard time keeping up with all these changes across so many platforms.

And this has prompted the Unix vendors to begin to standardize their systems. Hence the impetus for Spec1170. Every major Unix vendor has committed to supporting this standard and every Unix software developer waits with glee the day they can write software to this standard and simply recompile (without having to use autoconf) across different platforms.

As I understand it, Spec1170 is roughly based upon version 4 of the X/Open Portability Guidelines (XPG4). Because catgets and friends are defined in XPG4, I'm led to believe that catgets is a part of Spec1170 and hence will become a standardized component of all Unix systems.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.6.3 Temporary - Why a single implementation

Now it seems kind of wasteful to me to have two different systems installed for accessing message catalogs. If we do want to remedy catgets deficiencies why don't we try to expand catgets (in a compatible manner) rather than implement an entirely new system. Otherwise, we'll end up with two message catalog access systems installed with an operating system - one set of routines for packages using GNU gettext for their internationalization, and another set of routines (catgets) for all other software. Bloated?

Supposing another catalog access system is implemented. Which do we recommend? At least for Linux, we need to attract as many software developers as possible. Hence we need to make it as easy for them to port their software as possible. Which means supporting catgets. We will be implementing the libintl code within our libc, but does this mean we also have to incorporate another message catalog access scheme within our libc as well? And what about people who are going to be using the libintl + non-catgets routines. When they port their software to other platforms, they're now going to have to include the front-end (libintl) code plus the back-end code (the non-catgets access routines) with their software instead of just including the libintl code with their software.

Message catalog support is however only the tip of the iceberg. What about the data for the other locale categories. They also have a number of deficiencies. Are we going to abandon them as well and develop another duplicate set of routines (should libintl expand beyond message catalog support)?

Like many parts of Unix that can be improved upon, we're stuck with balancing compatibility with the past with useful improvements and innovations for the future.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.6.4 Temporary - Notes

X/Open agreed very late on the standard form so that many implementations differ from the final form. Both of my system (old Linux catgets and Ultrix-4) have a strange variation.

OK. After incorporating the last changes I have to spend some time on making the GNU/Linux libc gettext functions. So in future Solaris is not the only system having gettext.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11. The Translator's View

11.1 Introduction 0
11.2 Introduction 1
11.3 Discussions
11.4 Organization
11.5 Information Flow

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.1 Introduction 0

Free software is going international! The Translation Project is a way to get maintainers, translators and users all together, so free software will gradually become able to speak many native languages.

The GNU gettext tool set contains everything maintainers need for internationalizing their packages for messages. It also contains quite useful tools for helping translators at localizing messages to their native language, once a package has already been internationalized.

To achieve the Translation Project, we need many interested people who like their own language and write it well, and who are also able to synergize with other translators speaking the same language. If you'd like to volunteer to work at translating messages, please send mail to your translating team.

Each team has its own mailing list, courtesy of Linux International. You may reach your translating team at the address `ll@li.org', replacing ll by the two-letter ISO 639 code for your language. Language codes are not the same as country codes given in ISO 3166. The following translating teams exist:

Chinese zh, Czech cs, Danish da, Dutch nl, Esperanto eo, Finnish fi, French fr, Irish ga, German de, Greek el, Italian it, Japanese ja, Indonesian in, Norwegian no, Polish pl, Portuguese pt, Russian ru, Spanish es, Swedish sv and Turkish tr.

For example, you may reach the Chinese translating team by writing to `zh@li.org'. When you become a member of the translating team for your own language, you may subscribe to its list. For example, Swedish people can send a message to `sv-request@li.org', having this message body:

subscribe

Keep in mind that team members should be interested in working at translations, or at solving translational difficulties, rather than merely lurking around. If your team does not exist yet and you want to start one, please write to `translation@iro.umontreal.ca'; you will then reach the coordinator for all translator teams.

A handful of GNU packages have already been adapted and provided with message translations for several languages. Translation teams have begun to organize, using these packages as a starting point. But there are many more packages and many languages for which we have no volunteer translators. If you would like to volunteer to work at translating messages, please send mail to `translation@iro.umontreal.ca' indicating what language(s) you can work on.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.2 Introduction 1

This is now official, GNU is going international! Here is the announcement submitted for the January 1995 GNU Bulletin:

A handful of GNU packages have already been adapted and provided with message translations for several languages. Translation teams have begun to organize, using these packages as a starting point. But there are many more packages and many languages for which we have no volunteer translators. If you'd like to volunteer to work at translating messages, please send mail to `translation@iro.umontreal.ca' indicating what language(s) you can work on.

This document should answer many questions for those who are curious about the process or would like to contribute. Please at least skim over it, hoping to cut down a little of the high volume of e-mail generated by this collective effort towards internationalization of free software.

Most free programming which is widely shared is done in English, and currently, English is used as the main communicating language between national communities collaborating to free software. This very document is written in English. This will not change in the foreseeable future.

However, there is a strong appetite from national communities for having more software able to write using national language and habits, and there is an on-going effort to modify free software in such a way that it becomes able to do so. The experiments driven so far raised an enthusiastic response from pretesters, so we believe that internationalization of free software is dedicated to succeed.

For suggestion clarifications, additions or corrections to this document, please e-mail to `translation@iro.umontreal.ca'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.3 Discussions

Facing this internationalization effort, a few users expressed their concerns. Some of these doubts are presented and discussed, here.

  • Smaller groups

    Some languages are not spoken by a very large number of people, so people speaking them sometimes consider that there may not be all that much demand such versions of free software packages. Moreover, many people being into computers, in some countries, generally seem to prefer English versions of their software.

    On the other end, people might enjoy their own language a lot, and be very motivated at providing to themselves the pleasure of having their beloved free software speaking their mother tongue. They do themselves a personal favor, and do not pay that much attention to the number of people beneficiating of their work.

  • Misinterpretation

    Other users are shy to push forward their own language, seeing in this some kind of misplaced propaganda. Someone thought there must be some users of the language over the networks pestering other people with it.

    But any spoken language is worth localization, because there are people behind the language for whom the language is important and dear to their hearts.

  • Odd translations

    The biggest problem is to find the right translations so that everybody can understand the messages. Translations are usually a little odd. Some people get used to English, to the extent they may find translations into their own language "rather pushy, obnoxious and sometimes even hilarious." As a French speaking man, I have the experience of those instruction manuals for goods, so poorly translated in French in Korea or Taiwan...

    The fact is that we sometimes have to create a kind of national computer culture, and this is not easy without the collaboration of many people liking their mother tongue. This is why translations are better achieved by people knowing and loving their own language, and ready to work together at improving the results they obtain.

  • Dependencies over the GPL or LGPL

    Some people wonder if using GNU gettext necessarily brings their package under the protective wing of the GNU General Public License or the GNU Library General Public License, when they do not want to make their program free, or want other kinds of freedom. The simplest answer is "normally not".

    The GNU gettext library, i.e. the contents of libintl, is covered by the GNU Library General Public License. The rest of the GNU gettext package is covered by the GNU General Public License.

    The mere marking of localizable strings in a package, or conditional inclusion of a few lines for initialization, is not really including GPL'ed or LGPL'ed code. However, since the localization routines in libintl are under the LGPL, the LGPL needs to be considered. It gives the right to distribute the complete unmodified source of libintl even with non-free programs. It also gives the right to use libintl as a shared library, even for non-free programs. But it gives the right to use libintl as a static library or to incorporate libintl into another library only to free software.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.4 Organization

On a larger scale, the true solution would be to organize some kind of fairly precise set up in which volunteers could participate. I gave some thought to this idea lately, and realize there will be some touchy points. I thought of writing to Richard Stallman to launch such a project, but feel it might be good to shake out the ideas between ourselves first. Most probably that Linux International has some experience in the field already, or would like to orchestrate the volunteer work, maybe. Food for thought, in any case!

I guess we have to setup something early, somehow, that will help many possible contributors of the same language to interlock and avoid work duplication, and further be put in contact for solving together problems particular to their tongue (in most languages, there are many difficulties peculiar to translating technical English). My Swedish contributor acknowledged these difficulties, and I'm well aware of them for French.

This is surely not a technical issue, but we should manage so the effort of locale contributors be maximally useful, despite the national team layer interface between contributors and maintainers.

The Translation Project needs some setup for coordinating language coordinators. Localizing evolving programs will surely become a permanent and continuous activity in the free software community, once well started. The setup should be minimally completed and tested before GNU gettext becomes an official reality. The e-mail address `translation@iro.umontreal.ca' has been setup for receiving offers from volunteers and general e-mail on these topics. This address reaches the Translation Project coordinator.

11.4.1 Central Coordination
11.4.2 National Teams
11.4.3 Mailing Lists

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.4.1 Central Coordination

I also think GNU will need sooner than it thinks, that someone setup a way to organize and coordinate these groups. Some kind of group of groups. My opinion is that it would be good that GNU delegates this task to a small group of collaborating volunteers, shortly. Perhaps in `gnu.announce' a list of this national committee's can be published.

My role as coordinator would simply be to refer to Ulrich any German speaking volunteer interested to localization of free software packages, and maybe helping national groups to initially organize, while maintaining national registries for until national groups are ready to take over. In fact, the coordinator should ease volunteers to get in contact with one another for creating national teams, which should then select one coordinator per language, or country (regionalized language). If well done, the coordination should be useful without being an overwhelming task, the time to put delegations in place.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.4.2 National Teams

I suggest we look for volunteer coordinators/editors for individual languages. These people will scan contributions of translation files for various programs, for their own languages, and will ensure high and uniform standards of diction.

From my current experience with other people in these days, those who provide localizations are very enthusiastic about the process, and are more interested in the localization process than in the program they localize, and want to do many programs, not just one. This seems to confirm that having a coordinator/editor for each language is a good idea.

We need to choose someone who is good at writing clear and concise prose in the language in question. That is hard--we can't check it ourselves. So we need to ask a few people to judge each others' writing and select the one who is best.

I announce my prerelease to a few dozen people, and you would not believe all the discussions it generated already. I shudder to think what will happen when this will be launched, for true, officially, world wide. Who am I to arbitrate between two Czekolsovak users contradicting each other, for example?

I assume that your German is not much better than my French so that I would not be able to judge about these formulations. What I would suggest is that for each language there is a group for people who maintain the PO files and judge about changes. I suspect there will be cultural differences between how such groups of people will behave. Some will have relaxed ways, reach consensus easily, and have anyone of the group relate to the maintainers, while others will fight to death, organize heavy administrations up to national standards, and use strict channels.

The German team is putting out a good example. Right now, they are maybe half a dozen people revising translations of each other and discussing the linguistic issues. I do not even have all the names. Ulrich Drepper is taking care of coordinating the German team. He subscribed to all my pretest lists, so I do not even have to warn him specifically of incoming releases.

I'm sure, that is a good idea to get teams for each language working on translations. That will make the translations better and more consistent.

11.4.2.1 Sub-Cultures
11.4.2.2 Organizational Ideas

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.4.2.1 Sub-Cultures

Taking French for example, there are a few sub-cultures around computers which developed diverging vocabularies. Picking volunteers here and there without addressing this problem in an organized way, soon in the project, might produce a distasteful mix of internationalized programs, and possibly trigger endless quarrels among those who really care.

Keeping some kind of unity in the way French localization of internationalized programs is achieved is a difficult (and delicate) job. Knowing the latin character of French people (:-), if we take this the wrong way, we could end up nowhere, or spoil a lot of energies. Maybe we should begin to address this problem seriously before GNU gettext become officially published. And I suspect that this means soon!

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.4.2.2 Organizational Ideas

I expect the next big changes after the official release. Please note that I use the German translation of the short GPL message. We need to set a few good examples before the localization goes out for true in the free software community. Here are a few points to discuss:

  • Each group should have one FTP server (at least one master).

  • The files on the server should reflect the latest version (of course!) and it should also contain a RCS directory with the corresponding archives (I don't have this now).

  • There should also be a ChangeLog file (this is more useful than the RCS archive but can be generated automatically from the later by Emacs).

  • A core group should judge about questionable changes (for now this group consists solely by me but I ask some others occasionally; this also seems to work).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.4.3 Mailing Lists

If we get any inquiries about GNU gettext, send them on to:

`translation@iro.umontreal.ca'

The `*-pretest' lists are quite useful to me, maybe the idea could be generalized to many GNU, and non-GNU packages. But each maintainer his/her way!

François, we have a mechanism in place here at `gnu.ai.mit.edu' to track teams, support mailing lists for them and log members. We have a slight preference that you use it. If this is OK with you, I can get you clued in.

Things are changing! A few years ago, when Daniel Fekete and I asked for a mailing list for GNU localization, nested at the FSF, we were politely invited to organize it anywhere else, and so did we. For communicating with my pretesters, I later made a handful of mailing lists located at iro.umontreal.ca and administrated by majordomo. These lists have been very dependable so far...

I suspect that the German team will organize itself a mailing list located in Germany, and so forth for other countries. But before they organize for true, it could surely be useful to offer mailing lists located at the FSF to each national team. So yes, please explain me how I should proceed to create and handle them.

We should create temporary mailing lists, one per country, to help people organize. Temporary, because once regrouped and structured, it would be fair the volunteers from country bring back their list in there and manage it as they want. My feeling is that, in the long run, each team should run its own list, from within their country. There also should be some central list to which all teams could subscribe as they see fit, as long as each team is represented in it.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.5 Information Flow

There will surely be some discussion about this messages after the packages are finally released. If people now send you some proposals for better messages, how do you proceed? Jim, please note that right now, as I put forward nearly a dozen of localizable programs, I receive both the translations and the coordination concerns about them.

If I put one of my things to pretest, Ulrich receives the announcement and passes it on to the German team, who make last minute revisions. Then he submits the translation files to me as the maintainer. For free packages I do not maintain, I would not even hear about it. This scheme could be made to work for the whole Translation Project, I think. For security reasons, maybe Ulrich (national coordinators, in fact) should update central registry kept at the Translation Project (Jim, me, or Len's recruits) once in a while.

In December/January, I was aggressively ready to internationalize all of GNU, giving myself the duty of one small GNU package per week or so, taking many weeks or months for bigger packages. But it does not work this way. I first did all the things I'm responsible for. I've nothing against some missionary work on other maintainers, but I'm also loosing a lot of energy over it--same debates over again.

And when the first localized packages are released we'll get a lot of responses about ugly translations :-). Surely, and we need to have beforehand a fairly good idea about how to handle the information flow between the national teams and the package maintainers.

Please start saving somewhere a quick history of each PO file. I know for sure that the file format will change, allowing for comments. It would be nice that each file has a kind of log, and references for those who want to submit comments or gripes, or otherwise contribute. I sent a proposal for a fast and flexible format, but it is not receiving acceptance yet by the GNU deciders. I'll tell you when I have more information about this.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12. The Maintainer's View

The maintainer of a package has many responsibilities. One of them is ensuring that the package will install easily on many platforms, and that the magic we described earlier (see section 9. The User's View) will work for installers and end users.

Of course, there are many possible ways by which GNU gettext might be integrated in a distribution, and this chapter does not cover them in all generality. Instead, it details one possible approach which is especially adequate for many free software distributions following GNU standards, or even better, Gnits standards, because GNU gettext is purposely for helping the internationalization of the whole GNU project, and as many other good free packages as possible. So, the maintainer's view presented here presumes that the package already has a `configure.in' file and uses GNU Autoconf.

Nevertheless, GNU gettext may surely be useful for free packages not following GNU standards and conventions, but the maintainers of such packages might have to show imagination and initiative in organizing their distributions so gettext work for them in all situations. There are surely many, out there.

Even if gettext methods are now stabilizing, slight adjustments might be needed between successive gettext versions, so you should ideally revise this chapter in subsequent releases, looking for changes.

12.1 Flat or Non-Flat Directory Structures
12.2 Prerequisite Works
12.3 Invoking the gettextize Program
12.4 Files You Must Create or Alter
12.5 Autoconf macros for use in `configure.in'

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.1 Flat or Non-Flat Directory Structures

Some free software packages are distributed as tar files which unpack in a single directory, these are said to be flat distributions. Other free software packages have a one level hierarchy of subdirectories, using for example a subdirectory named `doc/' for the Texinfo manual and man pages, another called `lib/' for holding functions meant to replace or complement C libraries, and a subdirectory `src/' for holding the proper sources for the package. These other distributions are said to be non-flat.

We cannot say much about flat distributions. A flat directory structure has the disadvantage of increasing the difficulty of updating to a new version of GNU gettext. Also, if you have many PO files, this could somewhat pollute your single directory. Also, GNU gettext's libintl sources consist of C sources, shell scripts, sed scripts and complicated Makefile rules, which don't fit well into an existing flat structure. For these reasons, we recommend to use non-flat approach in this case as well.

Maybe because GNU gettext itself has a non-flat structure, we have more experience with this approach, and this is what will be described in the remaining of this chapter. Some maintainers might use this as an opportunity to unflatten their package structure.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.2 Prerequisite Works

There are some works which are required for using GNU gettext in one of your package. These works have some kind of generality that escape the point by point descriptions used in the remainder of this chapter. So, we describe them here.

  • Before attempting to use gettextize you should install some other packages first. Ensure that recent versions of GNU m4, GNU Autoconf and GNU gettext are already installed at your site, and if not, proceed to do this first. If you get to install these things, beware that GNU m4 must be fully installed before GNU Autoconf is even configured.

    To further ease the task of a package maintainer the automake package was designed and implemented. GNU gettext now uses this tool and the `Makefile's in the `intl/' and `po/' therefore know about all the goals necessary for using automake and `libintl' in one project.

    Those four packages are only needed by you, as a maintainer; the installers of your own package and end users do not really need any of GNU m4, GNU Autoconf, GNU gettext, or GNU automake for successfully installing and running your package, with messages properly translated. But this is not completely true if you provide internationalized shell scripts within your own package: GNU gettext shall then be installed at the user site if the end users want to see the translation of shell script messages.

  • Your package should use Autoconf and have a `configure.in' or `configure.ac' file. If it does not, you have to learn how. The Autoconf documentation is quite well written, it is a good idea that you print it and get familiar with it.

  • Your C sources should have already been modified according to instructions given earlier in this manual. See section 3. Preparing Program Sources.

  • Your `po/' directory should receive all PO files submitted to you by the translator teams, each having `ll.po' as a name. This is not usually easy to get translation work done before your package gets internationalized and available! Since the cycle has to start somewhere, the easiest for the maintainer is to start with absolutely no PO files, and wait until various translator teams get interested in your package, and submit PO files.

It is worth adding here a few words about how the maintainer should ideally behave with PO files submissions. As a maintainer, your role is to authenticate the origin of the submission as being the representative of the appropriate translating teams of the Translation Project (forward the submission to `translation@iro.umontreal.ca' in case of doubt), to ensure that the PO file format is not severely broken and does not prevent successful installation, and for the rest, to merely put these PO files in `po/' for distribution.

As a maintainer, you do not have to take on your shoulders the responsibility of checking if the translations are adequate or complete, and should avoid diving into linguistic matters. Translation teams drive themselves and are fully responsible of their linguistic choices for the Translation Project. Keep in mind that translator teams are not driven by maintainers. You can help by carefully redirecting all communications and reports from users about linguistic matters to the appropriate translation team, or explain users how to reach or join their team. The simplest might be to send them the `ABOUT-NLS' file.

Maintainers should never ever apply PO file bug reports themselves, short-cutting translation teams. If some translator has difficulty to get some of her points through her team, it should not be an option for her to directly negotiate translations with maintainers. Teams ought to settle their problems themselves, if any. If you, as a maintainer, ever think there is a real problem with a team, please never try to solve a team's problem on your own.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.3 Invoking the gettextize Program

Some files are consistently and identically needed in every package internationalized through GNU gettext. As a matter of convenience, the gettextize program puts all these files right in your package. This program has the following synopsis:

gettextize [ option... ] [ directory ]

and accepts the following options:

`-c'
`--copy'
Copy the needed files instead of making symbolic links. Using links would allow the package to always use the latest gettext code available on the system, but it might disturb some mechanism the maintainer is used to apply to the sources. Because running gettextize is easy there shouldn't be problems with using copies.

`-f'
`--force'
Force replacement of files which already exist.

`--intl'
Install the libintl sources in a subdirectory named `intl/'. This libintl will be used to provide internationalization on systems that don't have GNU libintl installed. If this option is omitted, the call to AM_GNU_GETTEXT in `configure.in' should read: `AM_GNU_GETTEXT([external])', and internationalization will not be enabled on systems lacking GNU gettext.

`--no-changelog'
Don't update or create ChangeLog files. By default, gettextize logs all changes (file additions, modifications ans removals) in a file called `ChangeLog' in each affected directory.

`--help'
Display this help and exit.

`--version'
Output version information and exit.

If directory is given, this is the top level directory of a package to prepare for using GNU gettext. If not given, it is assumed that the current directory is the top level directory of such a package.

The program gettextize provides the following files. However, no existing file will be replaced unless the option --force (-f) is specified.

  1. The `ABOUT-NLS' file is copied in the main directory of your package, the one being at the top level. This file gives the main indications about how to install and use the Native Language Support features of your program. You might elect to use a more recent copy of this `ABOUT-NLS' file than the one provided through gettextize, if you have one handy. You may also fetch a more recent copy of file `ABOUT-NLS' from Translation Project sites, and from most GNU archive sites.

  2. A `po/' directory is created for eventually holding all translation files, but initially only containing the file `po/Makefile.in.in' from the GNU gettext distribution. (beware the double `.in' in the file name) and a few auxiliary files. If the `po/' directory already exists, it will be preserved along with the files it contains, and only `Makefile.in.in' and the auxiliary files will be overwritten.

  3. Only if `--intl' has been specified: A `intl/' directory is created and filled with most of the files originally in the `intl/' directory of the GNU gettext distribution. Also, if option --force (-f) is given, the `intl/' directory is emptied first.

  4. The `config.rpath' file is copied into the directory containing configuration support files. It is needed by the AM_GNU_GETTEXT autoconf macro.

If your site support symbolic links, gettextize will not actually copy the files into your package, but establish symbolic links instead. This avoids duplicating the disk space needed in all packages. Merely using the `-h' option while creating the tar archive of your distribution will resolve each link by an actual copy in the distribution archive. So, to insist, you really should use `-h' option with tar within your dist goal of your main `Makefile.in'.

It is interesting to understand that most new files for supporting GNU gettext facilities in one package go in `intl/' and `po/' subdirectories. One distinction between these two directories is that `intl/' is meant to be completely identical in all packages using GNU gettext, while all newly created files, which have to be different, go into `po/'. There is a common `Makefile.in.in' in `po/', because the `po/' directory needs its own `Makefile', and it has been designed so it can be identical in all packages.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4 Files You Must Create or Alter

Besides files which are automatically added through gettextize, there are many files needing revision for properly interacting with GNU gettext. If you are closely following GNU standards for Makefile engineering and auto-configuration, the adaptations should be easier to achieve. Here is a point by point description of the changes needed in each.

So, here comes a list of files, each one followed by a description of all alterations it needs. Many examples are taken out from the GNU gettext 0.11.2 distribution itself, or from the GNU hello distribution (http://www.franken.de/users/gnu/ke/hello or http://www.gnu.franken.de/ke/hello/) You may indeed refer to the source code of the GNU gettext and GNU hello packages, as they are intended to be good examples for using GNU gettext functionality.

12.4.1 `POTFILES.in' in `po/'
12.4.2 `LINGUAS' in `po/'
12.4.3 `Makefile' pieces in `po/'
12.4.4 `configure.in' at top level
12.4.5 `config.guess', `config.sub' at top level
12.4.6 `aclocal.m4' at top level
12.4.7 `acconfig.h' at top level
12.4.8 `Makefile.in' at top level
12.4.9 `Makefile.in' in `src/'
12.4.10 `gettext.h' in `lib/'

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.1 `POTFILES.in' in `po/'

The `po/' directory should receive a file named `POTFILES.in'. This file tells which files, among all program sources, have marked strings needing translation. Here is an example of such a file:

# List of source files containing translatable strings.
# Copyright (C) 1995 Free Software Foundation, Inc.

# Common library files
lib/error.c
lib/getopt.c
lib/xmalloc.c

# Package source files
src/gettext.c
src/msgfmt.c
src/xgettext.c

Hash-marked comments and white lines are ignored. All other lines list those source files containing strings marked for translation (see section 3.3 How Marks Appear in Sources), in a notation relative to the top level of your whole distribution, rather than the location of the `POTFILES.in' file itself.

When a C file is automatically generated by a tool, like flex or bison, that doesn't introduce translatable strings by itself, it is recommended to list in `po/POTFILES.in' the real source file (ending in `.l' in the case of flex, or in `.y' in the case of bison), not the generated C file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.2 `LINGUAS' in `po/'

The `po/' directory should also receive a file named `LINGUAS'. This file contains the list of available translations. It is a whitespace separated list. Hash-marked comments and white lines are ignored. Here is an example file:

# Set of available languages.
de fr

This example means that German and French PO files are available, so that these languages are currently supported by your package. If you want to further restrict, at installation time, the set of installed languages, this should not be done by modifying the `LINGUAS' file, but rather by using the LINGUAS environment variable (see section 9.2 Magic for Installers).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.3 `Makefile' pieces in `po/'

The `po/' directory also has a file named `Makevars'. It can be left unmodified if your package has a single message domain and, accordingly, a single `po/' directory. Only packages which have multiple `po/' directories at different locations need to adjust the three variables defined in `Makevars'.

`po/Makevars' gets inserted into the `po/Makefile' when the latter is created. At the same time, all files called `Rules-*' in the `po/' directory get appended to the `po/Makefile'. They present an opportunity to add rules for special PO files to the Makefile, without needing to mess with `po/Makefile.in.in'.

GNU gettext comes with a `Rules-quot' file, containing rules for building catalogs `en@quot.po' and `en@boldquot.po'. The effect of `en@quot.po' is that people who set their LANGUAGE environment variable to `en@quot' will get messages with proper looking symmetric Unicode quotation marks instead of abusing the ASCII grave accent and the ASCII apostrophe for indicating quotations. To enable this catalog, simply add en@quot to the `po/LINGUAS' file. The effect of `en@boldquot.po' is that people who set LANGUAGE to `en@boldquot' will get not only proper quotation marks, but also the quoted text will be shown in a bold font on terminals and consoles. This catalog is useful only for command-line programs, not GUI programs. To enable it, similarly add en@boldquot to the `po/LINGUAS' file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.4 `configure.in' at top level

`configure.in' or `configure.ac' - this is the source from which autoconf generates the `configure' script.

  1. Declare the package and version.

    This is done by a set of lines like these:

    PACKAGE=gettext
VERSION=0.11.2
AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
AC_SUBST(PACKAGE)
AC_SUBST(VERSION)

    or, if you are using GNU automake, by a line like this:

    AM_INIT_AUTOMAKE(gettext, 0.11.2)

    Of course, you replace `gettext' with the name of your package, and `0.11.2' by its version numbers, exactly as they should appear in the packaged tar file name of your distribution (`gettext-0.11.2.tar.gz', here).

  2. Check for internationalization support.

    Here is the main m4 macro for triggering internationalization support. Just add this line to `configure.in':

    AM_GNU_GETTEXT

    This call is purposely simple, even if it generates a lot of configure time checking and actions.

    If you have suppressed the `intl/' subdirectory by calling gettextize without `--intl' option, this call should read

    AM_GNU_GETTEXT([external])

  3. Have output files created.

    The AC_OUTPUT directive, at the end of your `configure.in' file, needs to be modified in two ways:

    AC_OUTPUT([existing configuration files intl/Makefile po/Makefile.in],
[existing additional actions])

    The modification to the first argument to AC_OUTPUT asks for substitution in the `intl/' and `po/' directories. Note the `.in' suffix used for `po/' only. This is because the distributed file is really `po/Makefile.in.in'.

    If you have suppressed the `intl/' subdirectory by calling gettextize without `--intl' option, then you don't need to add intl/Makefile to the AC_OUTPUT line.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.5 `config.guess', `config.sub' at top level

If you haven't suppressed the `intl/' subdirectory, you need to add the GNU `config.guess' and `config.sub' files to your distribution. They are needed because the `intl/' directory has platform dependent support for determining the locale's character encoding and therefore needs to identify the platform.

You can obtain the newest version of `config.guess' and `config.sub' from `ftp://ftp.gnu.org/pub/gnu/config/'. Less recent versions are also contained in the GNU automake and GNU libtool packages.

Normally, `config.guess' and `config.sub' are put at the top level of a distribution. But it is also possible to put them in a subdirectory, altogether with other configuration support files like `install-sh', `ltconfig', `ltmain.sh', `mkinstalldirs' or `missing'. All you need to do, other than moving the files, is to add the following line to your `configure.in'.

AC_CONFIG_AUX_DIR([subdir])

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.6 `aclocal.m4' at top level

If you do not have an `aclocal.m4' file in your distribution, the simplest is to concatenate the files `codeset.m4', `gettext.m4', `glibc21.m4', `iconv.m4', `isc-posix.m4', `lcmessage.m4', `lib-ld.m4', `lib-link.m4', `lib-prefix.m4', `progtest.m4' from GNU gettext's `m4/' directory into a single file. If you have suppressed the `intl/' directory, only `gettext.m4', `iconv.m4', `lib-ld.m4', `lib-link.m4', `lib-prefix.m4', `progtest.m4' need to be concatenated.

If you already have an `aclocal.m4' file, then you will have to merge the said macro files into your `aclocal.m4'. Note that if you are upgrading from a previous release of GNU gettext, you should most probably replace the macros (AM_GNU_GETTEXT, etc.), as they usually change a little from one release of GNU gettext to the next. Their contents may vary as we get more experience with strange systems out there.

If you are using GNU automake 1.5 or newer, it is enough to put these macro files into a subdirectory named `m4/' and add the line

ACLOCAL_AMFLAGS = -I m4

to your top level `Makefile.am'.

These macros check for the internationalization support functions and related informations. Hopefully, once stabilized, these macros might be integrated in the standard Autoconf set, because this piece of m4 code will be the same for all projects using GNU gettext.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.7 `acconfig.h' at top level

Earlier GNU gettext releases required to put definitions for ENABLE_NLS, HAVE_GETTEXT and HAVE_LC_MESSAGES, HAVE_STPCPY, PACKAGE and VERSION into an `acconfig.h' file. This is not needed any more; you can remove them from your `acconfig.h' file unless your package uses them independently from the `intl/' directory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.8 `Makefile.in' at top level

Here are a few modifications you need to make to your main, top-level `Makefile.in' file.

  1. Add the following lines near the beginning of your `Makefile.in', so the `dist:' goal will work properly (as explained further down):

    PACKAGE = @PACKAGE@
VERSION = @VERSION@

  2. Add file `ABOUT-NLS' to the DISTFILES definition, so the file gets distributed.

  3. Wherever you process subdirectories in your `Makefile.in', be sure you also process dir subdirectories `intl' and `po'. Special rules in the `Makefiles' take care for the case where no internationalization is wanted.

    If you are using Makefiles, either generated by automake, or hand-written so they carefully follow the GNU coding standards, the effected goals for which the new subdirectories must be handled include `installdirs', `install', `uninstall', `clean', `distclean'.

    Here is an example of a canonical order of processing. In this example, we also define SUBDIRS in Makefile.in for it to be further used in the `dist:' goal.

    SUBDIRS = doc intl lib src po

    Note that you must arrange for `make' to descend into the intl directory before descending into other directories containing code which make use of the libintl.h header file. For this reason, here we mention intl before lib and src.

  4. A delicate point is the `dist:' goal, as both `intl/Makefile' and `po/Makefile' will later assume that the proper directory has been set up from the main `Makefile'. Here is an example at what the `dist:' goal might look like:

    distdir = $(PACKAGE)-$(VERSION)
dist: Makefile
    rm -fr $(distdir)
    mkdir $(distdir)
    chmod 777 $(distdir)
    for file in $(DISTFILES); do \
      ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
    done
    for subdir in $(SUBDIRS); do \
      mkdir $(distdir)/$$subdir || exit 1; \
      chmod 777 $(distdir)/$$subdir; \
      (cd $$subdir && $(MAKE) $@) || exit 1; \
    done
    tar chozf $(distdir).tar.gz $(distdir)
    rm -fr $(distdir)

Note that if you are using GNU automake, `Makefile.in' is automatically generated from `Makefile.am', and all needed changes to `Makefile.am' are already made by running `gettextize'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.9 `Makefile.in' in `src/'

Some of the modifications made in the main `Makefile.in' will also be needed in the `Makefile.in' from your package sources, which we assume here to be in the `src/' subdirectory. Here are all the modifications needed in `src/Makefile.in':

  1. In view of the `dist:' goal, you should have these lines near the beginning of `src/Makefile.in':

    PACKAGE = @PACKAGE@
VERSION = @VERSION@

  2. If not done already, you should guarantee that top_srcdir gets defined. This will serve for cpp include files. Just add the line:

    top_srcdir = @top_srcdir@

  3. You might also want to define subdir as `src', later allowing for almost uniform `dist:' goals in all your `Makefile.in'. At list, the `dist:' goal below assume that you used:

    subdir = src

  4. The main function of your program will normally call bindtextdomain (see see section 3.1 Triggering gettext Operations), like this:

    bindtextdomain (PACKAGE, LOCALEDIR);

    To make LOCALEDIR known to the program, add the following lines to Makefile.in:

    datadir = @datadir@
localedir = $(datadir)/locale
DEFS = -DLOCALEDIR=\"$(localedir)\" @DEFS@

    Note that @datadir@ defaults to `$(prefix)/share', thus $(localedir) defaults to `$(prefix)/share/locale'.

  5. You should ensure that the final linking will use @LIBINTL@ or @LTLIBINTL@ as a library. @LIBINTL@ is for use without libtool, @LTLIBINTL@ is for use with libtool. An easy way to achieve this is to manage that it gets into LIBS, like this:

    LIBS = @LIBINTL@ @LIBS@

    In most packages internationalized with GNU gettext, one will find a directory `lib/' in which a library containing some helper functions will be build. (You need at least the few functions which the GNU gettext Library itself needs.) However some of the functions in the `lib/' also give messages to the user which of course should be translated, too. Taking care of this, the support library (say `libsupport.a') should be placed before @LIBINTL@ and @LIBS@ in the above example. So one has to write this:

    LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@

  6. You should also ensure that directory `intl/' will be searched for C preprocessor include files in all circumstances. So, you have to manage so both `-I../intl' and `-I$(top_srcdir)/intl' will be given to the C compiler.

  7. Your `dist:' goal has to conform with others. Here is a reasonable definition for it:

    distdir = ../$(PACKAGE)-$(VERSION)/$(subdir)
dist: Makefile $(DISTFILES)
    for file in $(DISTFILES); do \
      ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
    done

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4.10 `gettext.h' in `lib/'

Internationalization of packages, as provided by GNU gettext, is optional. It can be turned off in two situations:

  • When the installer has specified `./configure --disable-nls'. This can be useful when small binaries are more important than features, for example when building utilities for boot diskettes. It can also be useful in order to get some specific C compiler warnings about code quality with some older versions of GCC (older than 3.0).

  • When the package does not include the intl/ subdirectory, and the libintl.h header (with its associated libintl library, if any) is not already installed on the system, it is preferrable that the package builds without internationalization support, rather than to give a compilation error.

A C preprocessor macro can be used to detect these two cases. Usually, when libintl.h was found and not explicitly disabled, the ENABLE_NLS macro will be defined to 1 in the autoconf generated configuration file (usually called `config.h'). In the two negative situations, however, this macro will not be defined, thus it will evaluate to 0 in C preprocessor expressions.

`gettext.h' is a convenience header file for conditional use of `<libintl.h>', depending on the ENABLE_NLS macro. If ENABLE_NLS is set, it includes `<libintl.h>'; otherwise it defines no-op substitutes for the libintl.h functions. We recommend the use of "gettext.h" over direct use of `<libintl.h>', so that portability to older systems is guaranteed and installers can turn off internationalization if they want to. In the C code, you will then write

#include "gettext.h"

instead of

#include <libintl.h>

The location of gettext.h is usually in a directory containing auxiliary include files. In many GNU packages, there is a directory `lib/' containing helper functions; `gettext.h' fits there. In other packages, it can go into the `src' directory.

Do not install the gettext.h file in public locations. Every package that needs it should contain a copy of it on its own.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.5 Autoconf macros for use in `configure.in'

GNU gettext installs macros for use in a package's `configure.in' or `configure.ac'. See section `Introduction' in The Autoconf Manual. The primary macro is, of course, AM_GNU_GETTEXT.

12.5.1 AM_GNU_GETTEXT in `gettext.m4'
12.5.2 AM_ICONV in `iconv.m4'

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.5.1 AM_GNU_GETTEXT in `gettext.m4'

The AM_GNU_GETTEXT macro tests for the presence of the GNU gettext function family in either the C library or a separate libintl library (shared or static libraries are both supported) or in the package's `intl/' directory.

AM_GNU_GETTEXT accepts up to three optional arguments. The general syntax is

AM_GNU_GETTEXT([intlsymbol], [needsymbol], [intldir])

intlsymbol can be one of `external', `no-libtool', `use-libtool'. The default (if it is not specified or empty) is `no-libtool'. intlsymbol should be `external' for packages with no `intl/' directory, and `no-libtool' or `use-libtool' for packages with an `intl/' directory. If intlsymbol is `use-libtool', then a libtool library $(top_builddir)/intl/libintl.la will be created (shared and/or static, depending on --{enable,disable}-{shared,static} and on the presence of AM_DISABLE_SHARED). If intlsymbol is `no-libtool', a static library $(top_builddir)/intl/libintl.a will be created.

If needsymbol is specified and is `need-ngettext', then GNU gettext implementations (in libc or libintl) without the ngettext() function will be ignored.

intldir is used to find the intl libraries. If empty, the value `$(top_builddir)/intl/' is used.

The AM_GNU_GETTEXT macro determines whether GNU gettext is available and should be used. If so, it sets the USE_NLS variable to `yes'; it defines ENABLE_NLS to 1 in the autoconf generated configuration file (usually called `config.h'); it sets the variables LIBINTL and LTLIBINTL to the linker options for use in a Makefile (LIBINTL for use without libtool, LTLIBINTL for use with libtool); it adds an `-I' option to CPPFLAGS if necessary. In the negative case, it sets USE_NLS to `no'; it sets LIBINTL and LTLIBINTL to empty and doesn't change CPPFLAGS.

The complexities that AM_GNU_GETTEXT deals with are the following:

  • Some operating systems have gettext in the C library, for example glibc. Some have it in a separate library libintl. GNU libintl might have been installed as part of the GNU gettext package.

  • GNU libintl, if installed, is not necessarily already in the search path (CPPFLAGS for the include file search path, LDFLAGS for the library search path).

  • Except for glibc, the operating system's native gettext cannot exploit the GNU mo files, doesn't have the necessary locale dependency features, and cannot convert messages from the catalog's text encoding to the user's locale encoding.

  • GNU libintl, if installed, is not necessarily already in the run time library search path. To avoid the need for setting an environment variable like LD_LIBRARY_PATH, the macro adds the appropriate run time search path options to the LIBINTL and LTLIBINTL variables. This works on most systems, but not on some operating systems with limited shared library support, like SCO.

  • GNU libintl relies on POSIX iconv. The macro checks for linker options needed to use iconv and appends them to the LIBINTL and LTLIBINTL variables.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.5.2 AM_ICONV in `iconv.m4'

The AM_ICONV macro tests for the presence of the POSIX iconv function family in either the C library or a separate libiconv library. If found, it sets the am_cv_func_iconv variable to `yes'; it defines HAVE_ICONV to 1 in the autoconf generated configuration file (usually called `config.h'); it defines ICONV_CONST to `const' or to empty, depending on whether the second argument of iconv() is of type `const char **' or `char **'; it sets the variables LIBICONV and LTLIBICONV to the linker options for use in a Makefile (LIBICONV for use without libtool, LTLIBICONV for use with libtool); it adds an `-I' option to CPPFLAGS if necessary. If not found, it sets LIBICONV and LTLIBICONV to empty and doesn't change CPPFLAGS.

The complexities that AM_ICONV deals with are the following:

  • Some operating systems have iconv in the C library, for example glibc. Some have it in a separate library libiconv, for example OSF/1 or FreeBSD. Regardless of the operating system, GNU libiconv might have been installed. In that case, it should be used instead of the operating system's native iconv.

  • GNU libiconv, if installed, is not necessarily already in the search path (CPPFLAGS for the include file search path, LDFLAGS for the library search path).

  • GNU libiconv is binary incompatible with some operating system's native iconv, for example on FreeBSD. Use of an `iconv.h' and `libiconv.so' that don't fit together would produce program crashes.

  • GNU libiconv, if installed, is not necessarily already in the run time library search path. To avoid the need for setting an environment variable like LD_LIBRARY_PATH, the macro adds the appropriate run time search path options to the LIBICONV variable. This works on most systems, but not on some operating systems with limited shared library support, like SCO.

`iconv.m4' is distributed with the GNU gettext package because `gettext.m4' relies on it.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13. Other Programming Languages

While the presentation of gettext focuses mostly on C and implicitly applies to C++ as well, its scope is far broader than that: Many programming languages, scripting languages and other textual data like GUI resources or package descriptions can make use of the gettext approach.

13.1 The Language Implementor's View
13.2 The Programmer's View
13.3 The Translator's View
13.4 The Maintainer's View
13.5 Individual Programming Languages
13.6 Internationalizable Data

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.1 The Language Implementor's View

All programming and scripting languages that have the notion of strings are eligible to supporting gettext. Supporting gettext means the following:

  1. You should add to the language a syntax for translatable strings. In principle, a function call of gettext would do, but a shorthand syntax helps keeping the legibility of internationalized programs. For example, in C we use the syntax _("string"), in bash we use the syntax $"string", and in GNU awk we use the shorthand _"string".

  2. You should arrange that evaluation of such a translatable string at runtime calls the gettext function, or performs equivalent processing.

  3. Similarly, you should make the functions ngettext, dcgettext, dcngettext available from within the language. These functions are less often used, but are nevertheless necessary for particular purposes: ngettext for correct plural handling, and dcgettext and dcngettext for obeying other locale environment variables than LC_MESSAGES, such as LC_TIME or LC_MONETARY. For these latter functions, you need to make the LC_* constants, available in the C header <locale.h>, referenceable from within the language, usually either as enumeration values or as strings.

  4. You should allow the programmer to designate a message domain, either by making the textdomain function available from within the language, or by introducing a magic variable called TEXTDOMAIN. Similarly, you should allow the programmer to designate where to search for message catalogs, by providing access to the bindtextdomain function.

  5. You should either perform a setlocale (LC_ALL, "") call during the startup of your language runtime, or allow the programmer to do so. Remember that gettext will act as a no-op if the LC_MESSAGES and LC_CTYPE locale facets are not both set.

  6. A programmer should have a way to extract translatable strings from a program into a PO file. The GNU xgettext program is being extended to support very different programming languages. Please contact the GNU gettext maintainers to help them doing this. If the string extractor is best integrated into your language's parser, GNU xgettext can function as a front end to your string extractor.

  7. The language's library should have a string formatting facility where the arguments of a format string are denoted by a positional number or a name. This is needed because for some languages and some messages with more than one substitutable argument, the translation will need to output the substituted arguments in different order. See section 3.5 Special Comments preceding Keywords.

  8. If the language has more than one implementation, and not all of the implementations use gettext, but the programs should be portable across implementations, you should provide a no-i18n emulation, that makes the other implementations accept programs written for yours, without actually translating the strings.

  9. To help the programmer in the task of marking translatable strings, which is usually performed using the Emacs PO mode, you are welcome to contact the GNU gettext maintainers, so they can add support for your language to `po-mode.el'.

On the implementation side, three approaches are possible, with different effects on portability and copyright:

  • You may integrate the GNU gettext's `intl/' directory in your package, as described in 12. The Maintainer's View. This allows you to have internationalization on all kinds of platforms. Note that when you then distribute your package, it legally falls under the GNU General Public License, and the GNU project will be glad about your contribution to the Free Software pool.

  • You may link against GNU gettext functions if they are found in the C library. For example, an autoconf test for gettext() and ngettext() will detect this situation. For the moment, this test will succeed on GNU systems and not on other platforms. No severe copyright restrictions apply.

  • You may emulate or reimplement the GNU gettext functionality. This has the advantage of full portability and no copyright restrictions, but also the drawback that you have to reimplement the GNU gettext features (such as the LANGUAGE environment variable, the locale aliases database, the automatic charset conversion, and plural handling).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.2 The Programmer's View

For the programmer, the general procedure is the same as for the C language. The Emacs PO mode supports other languages, and the GNU xgettext string extractor recognizes other languages based on the file extension or a command-line option. In some languages, setlocale is not needed because it is already performed by the underlying language runtime.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.3 The Translator's View

The translator works exactly as in the C language case. The only difference is that when translating format strings, she has to be aware of the language's particular syntax for positional arguments in format strings.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.4 The Maintainer's View

For the maintainer, the general procedure differs from the C language case in two ways.

  • For those languages that don't use GNU gettext, the `intl/' directory is not needed and can be omitted. This means that the maintainer calls the gettextize program without the `--intl' option, and that he invokes the AM_GNU_GETTEXT autoconf macro via `AM_GNU_GETTEXT([external])'.

  • If only a single programming language is used, the XGETTEXT_OPTIONS variable in `po/Makevars' (see section 12.4.3 `Makefile' pieces in `po/') should be adjusted to match the xgettext options for that particular programming language. If the package uses more than one programming language with gettext support, it becomes necessary to change the POT file construction rule in `po/Makefile.in.in'. It is recommended to make one xgettext invocation per programming language, each with the options appropriate for that language, and to combine the resulting files using msgcat.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5 Individual Programming Languages

13.5.1 C, C++, Objective C
13.5.2 sh - Shell Script
13.5.3 bash - Bourne-Again Shell Script
13.5.4 Python
13.5.5 GNU clisp - Common Lisp
13.5.6 GNU clisp C sources
13.5.7 Emacs Lisp
13.5.8 librep
13.5.9 GNU Smalltalk
13.5.10 Java
13.5.11 GNU awk
13.5.12 Pascal - Free Pascal Compiler
13.5.13 wxWindows library
13.5.14 YCP - YaST2 scripting language
13.5.15 Tcl - Tk's scripting language
13.5.16 Perl
13.5.17 PHP Hypertext Preprocessor
13.5.18 Pike

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.1 C, C++, Objective C

RPMs
gcc, gpp, gobjc, glibc, gettext

File extension
For C: c, h.
For C++: C, c++, cc, cxx, cpp, hpp.
For Objective C: m.

String syntax
"abc"

gettext shorthand
_("abc")

gettext/ngettext functions
gettext, dgettext, dcgettext, ngettext, dngettext, dcngettext

textdomain
textdomain function

bindtextdomain
bindtextdomain function

setlocale
Programmer must call setlocale (LC_ALL, "")

Prerequisite
#include <libintl.h>
#include <locale.h>
#define _(string) gettext (string)

Use or emulate GNU gettext
Use

Extractor
xgettext -k_

Formatting with positions
fprintf "%2$d %1$d" (POSIX but not C 99)

Portability
autoconf (gettext.m4) and #if ENABLE_NLS

po-mode marking
yes

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.2 sh - Shell Script

RPMs
bash, gettext

File extension
sh

String syntax
"abc", 'abc', abc

gettext shorthand
"`gettext "abc"`"

gettext/ngettext functions
gettext, ngettext programs

textdomain
environment variable TEXTDOMAIN

bindtextdomain
environment variable TEXTDOMAINDIR

setlocale
automatic

Prerequisite
---

Use or emulate GNU gettext
use

Extractor
---

Formatting with positions
---

Portability
---

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.3 bash - Bourne-Again Shell Script

RPMs
bash 2.0 or newer, gettext

File extension
sh

String syntax
"abc", 'abc', abc

gettext shorthand
$"abc"

gettext/ngettext functions
gettext, ngettext programs

textdomain
environment variable TEXTDOMAIN

bindtextdomain
environment variable TEXTDOMAINDIR

setlocale
automatic

Prerequisite
---

Use or emulate GNU gettext
use

Extractor
bash --dump-po-strings

Formatting with positions
---

Portability
---

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.4 Python

RPMs
python

File extension
py

String syntax
'abc', u'abc', r'abc', ur'abc',
"abc", u"abc", r"abc", ur"abc",
"'abc"', u"'abc"', r"'abc"', ur"'abc"',
"""abc""", u"""abc""", r"""abc""", ur"""abc"""

gettext shorthand
_('abc') etc.

gettext/ngettext functions
gettext.gettext, gettext.dgettext, also ugettext

textdomain
gettext.textdomain function, or gettext.install(domain) function

bindtextdomain
gettext.bindtextdomain function, or gettext.install(domain,localedir) function

setlocale
not used by the gettext emulation

Prerequisite
import gettext

Use or emulate GNU gettext
emulate. Bug: uses only the first found .mo file, not all of them

Extractor
xgettext

Formatting with positions
'...%(ident)d...' % { 'ident': value }

Portability
fully portable

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.5 GNU clisp - Common Lisp

RPMs
clisp 2.28 or newer

File extension
lisp

String syntax
"abc"

gettext shorthand
(_ "abc"), (ENGLISH "abc")

gettext/ngettext functions
i18n:gettext, i18n:ngettext

textdomain
i18n:textdomain

bindtextdomain
i18n:textdomaindir

setlocale
automatic

Prerequisite
---

Use or emulate GNU gettext
use

Extractor
xgettext -k_ -kENGLISH

Formatting with positions
format "~1@*~D ~0@*~D"

Portability
On platforms without gettext, no translation.

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.6 GNU clisp C sources

RPMs
clisp

File extension
d

String syntax
"abc"

gettext shorthand
ENGLISH ? "abc" : ""
GETTEXT("abc")
GETTEXTL("abc")

gettext/ngettext functions
clgettext, clgettextl

textdomain
---

bindtextdomain
---

setlocale
automatic

Prerequisite
#include "lispbibl.c"

Use or emulate GNU gettext
use

Extractor
clisp-xgettext

Formatting with positions
fprintf "%2$d %1$d" (POSIX but not C 99)

Portability
On platforms without gettext, no translation.

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.7 Emacs Lisp

RPMs
emacs, xemacs

File extension
el

String syntax
"abc"

gettext shorthand
(_"abc")

gettext/ngettext functions
gettext, dgettext (xemacs only)

textdomain
domain special form (xemacs only)

bindtextdomain
bind-text-domain function (xemacs only)

setlocale
automatic

Prerequisite
---

Use or emulate GNU gettext
use

Extractor
xgettext

Formatting with positions
format "%2$d %1$d"

Portability
Only XEmacs. Without I18N3 defined at build time, no translation.

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.8 librep

RPMs
librep 0.15.3 or newer

File extension
jl

String syntax
"abc"

gettext shorthand
(_"abc")

gettext/ngettext functions
gettext

textdomain
textdomain function

bindtextdomain
bindtextdomain function

setlocale
---

Prerequisite
(require 'rep.i18n.gettext)

Use or emulate GNU gettext
use

Extractor
xgettext

Formatting with positions
format "%2$d %1$d"

Portability
On platforms without gettext, no translation.

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.9 GNU Smalltalk

RPMs
smalltalk

File extension
st

String syntax
"abc"

gettext shorthand
NLS? "abc"
self? "abc"

gettext/ngettext functions
LcMessagesDomain>>#at:, LcMessagesDomain>>#at:plural:with:

textdomain
LcMessages>>#? (returns a LcMessagesDomain object).
Example: Locale default messages ? 'gettext'

bindtextdomain
LcMessages>>#domain:directory: (returns a LcMessagesDomain object)

setlocale
You can obtain any Locale object from Locale class methods such as #fromString: or #default.
Example: Locale default messages gives the LcMessages object for the default locale.

Prerequisite
The gettext code is contained in the `I18N' package.

Use or emulate GNU gettext
emulate

Extractor
---

Formatting with positions
'%1 %2' bindWith: 'Hello' with: 'world'

Portability
fully portable

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.10 Java

RPMs
java, java2

File extension
java

String syntax
"abc"

gettext shorthand
_("abc")

gettext/ngettext functions
GettextResource.gettext, GettextResource.ngettext

textdomain
---, use ResourceBundle.getResource instead

bindtextdomain
---, use CLASSPATH instead

setlocale
automatic

Prerequisite
---

Use or emulate GNU gettext
---, uses a Java specific message catalog format

Extractor
xgettext -k_

Formatting with positions
MessageFormat.format "{1,number} {0,number}"

Portability
fully portable

po-mode marking
---

Before marking strings as internationalizable, uses of the string concatenation operator need to be converted to MessageFormat applications. For example, "file "+filename+" not found" becomes MessageFormat.format("file {0} not found", new Object[] { filename }). Only after this is done, can the strings be marked and extracted.

GNU gettext uses the native Java internationalization mechanism, namely ResourceBundles. To convert a PO file to a ResourceBundle, the msgfmt program can be used with the option --java or --java2. To convert a ResourceBundle back to a PO file, the msgunfmt program can be used with the option --java.

Two different programmatic APIs can be used to access ResourceBundles. Note that both APIs work with all kinds of ResourceBundles, whether GNU gettext generated classes, or other .class or .properties files.

  1. The java.util.ResourceBundle API.

    In particular, its getString function returns a string translation. Note that a missing translation yields a MissingResourceException.

    This has the advantage of being the standard API. And it does not require any additional libraries, only the msgfmt generated .class files. But it cannot do plural handling, even if the resource was generated from a PO file with plural handling.

  2. The gnu.gettext.GettextResource API.

    Reference documentation in Javadoc 1.1 style format is in the javadoc1 directory and in Javadoc 2 style format in the javadoc2 directory.

    Its gettext function returns a string translation. Note that when a translation is missing, the msgid argument is returned unchanged.

    This has the advantage of having the ngettext function for plural handling.

    To use this API, one needs the libintl.jar file which is part of the GNU gettext package and distributed under the LGPL.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.11 GNU awk

RPMs
gawk 3.1 or newer

File extension
awk

String syntax
"abc"

gettext shorthand
_"abc"

gettext/ngettext functions
dcgettext, missing dcngettext in gawk-3.1.0

textdomain
TEXTDOMAIN variable

bindtextdomain
bindtextdomain function

setlocale
automatic, but missing setlocale (LC_MESSAGES, "") in gawk-3.1.0

Prerequisite
---

Use or emulate GNU gettext
use

Extractor
xgettext

Formatting with positions
printf "%2$d %1$d" (GNU awk only)

Portability
On platforms without gettext, no translation. On non-GNU awks, you must define dcgettext, dcngettext and bindtextdomain yourself.

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.12 Pascal - Free Pascal Compiler

RPMs
fpk

File extension
pp, pas

String syntax
'abc'

gettext shorthand
automatic

gettext/ngettext functions
---, use ResourceString data type instead

textdomain
---, use TranslateResourceStrings function instead

bindtextdomain
---, use TranslateResourceStrings function instead

setlocale
automatic, but uses only LANG, not LC_MESSAGES or LC_ALL

Prerequisite
{$mode delphi} or {$mode objfpc}
uses gettext;

Use or emulate GNU gettext
emulate partially

Extractor
ppc386 followed by xgettext or rstconv

Formatting with positions
uses sysutils;
format "%1:d %0:d"

Portability
?

po-mode marking
---

The Pascal compiler has special support for the ResourceString data type. It generates a .rst file. This is then converted to a .pot file by use of xgettext or rstconv. At runtime, a .mo file corresponding to translations of this .pot file can be loaded using the TranslateResourceStrings function in the gettext unit.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.13 wxWindows library

RPMs
wxGTK, gettext

File extension
cpp

String syntax
"abc"

gettext shorthand
_("abc")

gettext/ngettext functions
wxLocale::GetString, wxGetTranslation

textdomain
wxLocale::AddCatalog

bindtextdomain
wxLocale::AddCatalogLookupPathPrefix

setlocale
wxLocale::Init, wxSetLocale

Prerequisite
#include <wx/intl.h>

Use or emulate GNU gettext
emulate, see include/wx/intl.h and src/common/intl.cpp

Extractor
xgettext

Formatting with positions
---

Portability
fully portable

po-mode marking
yes

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.14 YCP - YaST2 scripting language

RPMs
libycp, libycp-devel, yast2-core-translator

File extension
ycp

String syntax
"abc"

gettext shorthand
_("abc")

gettext/ngettext functions
_() with 1 or 3 arguments

textdomain
textdomain statement

bindtextdomain
---

setlocale
---

Prerequisite
---

Use or emulate GNU gettext
use maps instead

Extractor
xgettext

Formatting with positions
sformat "%2 %1"

Portability
fully portable

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.15 Tcl - Tk's scripting language

RPMs
tcl

File extension
tcl

String syntax
"abc"

gettext shorthand
[_ "abc"]

gettext/ngettext functions
::msgcat::mc

textdomain
---

bindtextdomain
---, use ::msgcat::mcload instead

setlocale
automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL

Prerequisite
package require msgcat
proc _ {s} {return [::msgcat::mc $s]}

Use or emulate GNU gettext
---, uses a Tcl specific message catalog format

Extractor
xgettext -k_

Formatting with positions
format "%2\$d %1\$d"

Portability
fully portable

po-mode marking
---

Before marking strings as internationalizable, substitutions of variables into the string need to be converted to format applications. For example, "file $filename not found" becomes [format "file %s not found" $filename]. Only after this is done, can the strings be marked and extracted. After marking, this example becomes [format [_ "file %s not found"] $filename] or [msgcat::mc "file %s not found" $filename]. Note that the msgcat::mc function implicitly calls format when more than one argument is given.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.16 Perl

RPMs
perl, perl-gettext

File extension
pl, PL

String syntax
"abc"

gettext shorthand
---

gettext/ngettext functions
gettext, dgettext, dcgettext

textdomain
textdomain function

bindtextdomain
bindtextdomain function

setlocale
Use setlocale (LC_ALL, "");

Prerequisite
use POSIX;
use Locale::gettext;

Use or emulate GNU gettext
use

Extractor
?

Formatting with positions
---

Portability
?

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.17 PHP Hypertext Preprocessor

RPMs
mod_php4, phplib, phpdoc

File extension
php, php3, php4

String syntax
"abc"

gettext shorthand
_("abc")

gettext/ngettext functions
gettext, dgettext, dcgettext

textdomain
textdomain function

bindtextdomain
bindtextdomain function

setlocale
setlocale function

Prerequisite
---

Use or emulate GNU gettext
use

Extractor
---

Formatting with positions
---

Portability
On platforms without gettext, the functions are not available.

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.5.18 Pike

RPMs
roxen

File extension
pike

String syntax
"abc"

gettext shorthand
---

gettext/ngettext functions
gettext, dgettext, dcgettext

textdomain
textdomain function

bindtextdomain
bindtextdomain function

setlocale
setlocale function

Prerequisite
import Locale.Gettext;

Use or emulate GNU gettext
use

Extractor
---

Formatting with positions
---

Portability
On platforms without gettext, the functions are not available.

po-mode marking
---

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.6 Internationalizable Data

Here is a list of other data formats which can be internationalized using GNU gettext.

13.6.1 POT - Portable Object Template
13.6.2 Resource String Table
13.6.3 Glade - GNOME user interface description

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.6.1 POT - Portable Object Template

RPMs
gettext

File extension
pot, po

Extractor
xgettext

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.6.2 Resource String Table

RPMs
fpk

File extension
rst

Extractor
xgettext, rstconv

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13.6.3 Glade - GNOME user interface description

RPMs
glade, libglade, xml-i18n-tools

File extension
glade

Extractor
xgettext, libglade-xgettext

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

14. Concluding Remarks

We would like to conclude this GNU gettext manual by presenting an history of the Translation Project so far. We finally give a few pointers for those who want to do further research or readings about Native Language Support matters.

14.1 History of GNU gettext
14.2 Related Readings

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

14.1 History of GNU gettext

Internationalization concerns and algorithms have been informally and casually discussed for years in GNU, sometimes around GNU libc, maybe around the incoming Hurd, or otherwise (nobody clearly remembers). And even then, when the work started for real, this was somewhat independently of these previous discussions.

This all began in July 1994, when Patrick D'Cruze had the idea and initiative of internationalizing version 3.9.2 of GNU fileutils. He then asked Jim Meyering, the maintainer, how to get those changes folded into an official release. That first draft was full of #ifdefs and somewhat disconcerting, and Jim wanted to find nicer ways. Patrick and Jim shared some tries and experimentations in this area. Then, feeling that this might eventually have a deeper impact on GNU, Jim wanted to know what standards were, and contacted Richard Stallman, who very quickly and verbally described an overall design for what was meant to become glocale, at that time.

Jim implemented glocale and got a lot of exhausting feedback from Patrick and Richard, of course, but also from Mitchum DSouza (who wrote a catgets-like package), Roland McGrath, maybe David MacKenzie, François Pinard, and Paul Eggert, all pushing and pulling in various directions, not always compatible, to the extent that after a couple of test releases, glocale was torn apart.

While Jim took some distance and time and became dad for a second time, Roland wanted to get GNU libc internationalized, and got Ulrich Drepper involved in that project. Instead of starting from glocale, Ulrich rewrote something from scratch, but more conformant to the set of guidelines who emerged out of the glocale effort. Then, Ulrich got people from the previous forum to involve themselves into this new project, and the switch from glocale to what was first named msgutils, renamed nlsutils, and later gettext, became officially accepted by Richard in May 1995 or so.

Let's summarize by saying that Ulrich Drepper wrote GNU gettext in April 1995. The first official release of the package, including PO mode, occurred in July 1995, and was numbered 0.7. Other people contributed to the effort by providing a discussion forum around Ulrich, writing little pieces of code, or testing. These are quoted in the THANKS file which comes with the GNU gettext distribution.

While this was being done, François adapted half a dozen of GNU packages to glocale first, then later to gettext, putting them in pretest, so providing along the way an effective user environment for fine tuning the evolving tools. He also took the responsibility of organizing and coordinating the Translation Project. After nearly a year of informal exchanges between people from many countries, translator teams started to exist in May 1995, through the creation and support by Patrick D'Cruze of twenty unmoderated mailing lists for that many native languages, and two moderated lists: one for reaching all teams at once, the other for reaching all willing maintainers of internationalized free software packages.

François also wrote PO mode in June 1995 with the collaboration of Greg McGary, as a kind of contribution to Ulrich's package. He also gave a hand with the GNU gettext Texinfo manual.

In 1997, Ulrich Drepper released the GNU libc 2.0, which included the gettext, textdomain and bindtextdomain functions.

In 2000, Ulrich Drepper added plural form handling (the ngettext function) to GNU libc. Later, in 2001, he released GNU libc 2.2.x, which is the first free C library with full internationalization support.

Ulrich being quite busy in his role of General Maintainer of GNU libc, he handed over the GNU gettext maintenance to Bruno Haible in 2000. Bruno added the plural form handling to the tools as well, added support for UTF-8 and CJK locales, and wrote a few new tools for manipulating PO files.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

14.2 Related Readings

Eugene H. Dorr (`dorre@well.com') maintains an interesting bibliography on internationalization matters, called Internationalization Reference List, which is available as:
ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/i18n-books.txt

Michael Gschwind (`mike@vlsivie.tuwien.ac.at') maintains a Frequently Asked Questions (FAQ) list, entitled Programming for Internationalisation. This FAQ discusses writing programs which can handle different language conventions, character sets, etc.; and is applicable to all character set encodings, with particular emphasis on ISO 8859-1. It is regularly published in Usenet groups `comp.unix.questions', `comp.std.internat', `comp.software.international', `comp.lang.c', `comp.windows.x', `comp.std.c', `comp.answers' and `news.answers'. The home location of this document is:
ftp://ftp.vlsivie.tuwien.ac.at/pub/8bit/ISO-programming

Patrick D'Cruze (`pdcruze@li.org') wrote a tutorial about NLS matters, and Jochen Hein (`Hein@student.tu-clausthal.de') took over the responsibility of maintaining it. It may be found as:
ftp://sunsite.unc.edu/pub/Linux/utils/nls/catalogs/Incoming/...
     ...locale-tutorial-0.8.txt.gz
This site is mirrored in:
ftp://ftp.ibp.fr/pub/linux/sunsite/

A French version of the same tutorial should be findable at:
ftp://ftp.ibp.fr/pub/linux/french/docs/
together with French translations of many Linux-related documents.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

A. Language Codes

The ISO 639 standard defines two character codes for many languages. All abbreviations for languages used in the Translation Project should come from this standard.

`aa'
Afar.
`ab'
Abkhazian.
`ae'
Avestan.
`af'
Afrikaans.
`am'
Amharic.
`ar'
Arabic.
`as'
Assamese.
`ay'
Aymara.
`az'
Azerbaijani.
`ba'
Bashkir.
`be'
Byelorussian; Belarusian.
`bg'
Bulgarian.
`bh'
Bihari.
`bi'
Bislama.
`bn'
Bengali; Bangla.
`bo'
Tibetan.
`br'
Breton.
`bs'
Bosnian.
`ca'
Catalan.
`ce'
Chechen.
`ch'
Chamorro.
`co'
Corsican.
`cs'
Czech.
`cu'
Church Slavic.
`cv'
Chuvash.
`cy'
Welsh.
`da'
Danish.
`de'
German.
`dz'
Dzongkha; Bhutani.
`el'
Greek.
`en'
English.
`eo'
Esperanto.
`es'
Spanish.
`et'
Estonian.
`eu'
Basque.
`fa'
Persian.
`fi'
Finnish.
`fj'
Fijian; Fiji.
`fo'
Faroese.
`fr'
French.
`fy'
Frisian.
`ga'
Irish.
`gd'
Scots; Gaelic.
`gl'
Gallegan; Galician.
`gn'
Guarani.
`gu'
Gujarati.
`gv'
Manx.
`ha'
Hausa (?).
`he'
Hebrew (formerly iw).
`hi'
Hindi.
`ho'
Hiri Motu.
`hr'
Croatian.
`hu'
Hungarian.
`hy'
Armenian.
`hz'
Herero.
`ia'
Interlingua.
`id'
Indonesian (formerly in).
`ie'
Interlingue.
`ik'
Inupiak.
`io'
Ido.
`is'
Icelandic.
`it'
Italian.
`iu'
Inuktitut.
`ja'
Japanese.
`jv'
Javanese.
`ka'
Georgian.
`ki'
Kikuyu.
`kj'
Kuanyama.
`kk'
Kazakh.
`kl'
Kalaallisut; Greenlandic.
`km'
Khmer; Cambodian.
`kn'
Kannada.
`ko'
Korean.
`ks'
Kashmiri.
`ku'
Kurdish.
`kv'
Komi.
`kw'
Cornish.
`ky'
Kirghiz.
`la'
Latin.
`lb'
Letzeburgesch.
`ln'
Lingala.
`lo'
Lao; Laotian.
`lt'
Lithuanian.
`lv'
Latvian; Lettish.
`mg'
Malagasy.
`mh'
Marshall.
`mi'
Maori.
`mk'
Macedonian.
`ml'
Malayalam.
`mn'
Mongolian.
`mo'
Moldavian.
`mr'
Marathi.
`ms'
Malay.
`mt'
Maltese.
`my'
Burmese.
`na'
Nauru.
`nb'
Norwegian Bokmål.
`nd'
Ndebele, North.
`ne'
Nepali.
`ng'
Ndonga.
`nl'
Dutch.
`nn'
Norwegian Nynorsk.
`no'
Norwegian.
`nr'
Ndebele, South.
`nv'
Navajo.
`ny'
Chichewa; Nyanja.
`oc'
Occitan; Provençal.
`om'
(Afan) Oromo.
`or'
Oriya.
`os'
Ossetian; Ossetic.
`pa'
Panjabi; Punjabi.
`pi'
Pali.
`pl'
Polish.
`ps'
Pashto, Pushto.
`pt'
Portuguese.
`qu'
Quechua.
`rm'
Rhaeto-Romance.
`rn'
Rundi; Kirundi.
`ro'
Romanian.
`ru'
Russian.
`rw'
Kinyarwanda.
`sa'
Sanskrit.
`sc'
Sardinian.
`sd'
Sindhi.
`se'
Northern Sami.
`sg'
Sango; Sangro.
`si'
Sinhalese.
`sk'
Slovak.
`sl'
Slovenian.
`sm'
Samoan.
`sn'
Shona.
`so'
Somali.
`sq'
Albanian.
`sr'
Serbian.
`ss'
Swati; Siswati.
`st'
Sesotho; Sotho, Southern.
`su'
Sundanese.
`sv'
Swedish.
`sw'
Swahili.
`ta'
Tamil.
`te'
Telugu.
`tg'
Tajik.
`th'
Thai.
`ti'
Tigrinya.
`tk'
Turkmen.
`tl'
Tagalog.
`tn'
Tswana; Setswana.
`to'
Tonga (?).
`tr'
Turkish.
`ts'
Tsonga.
`tt'
Tatar.
`tw'
Twi.
`ty'
Tahitian.
`ug'
Uighur.
`uk'
Ukrainian.
`ur'
Urdu.
`uz'
Uzbek.
`vi'
Vietnamese.
`vo'
Volap@"{u}k; Volapuk.
`wa'
Walloon.
`wo'
Wolof.
`xh'
Xhosa.
`yi'
Yiddish (formerly ji).
`yo'
Yoruba.
`za'
Zhuang.
`zh'
Chinese.
`zu'
Zulu.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

B. Country Codes

The ISO 3166 standard defines two character codes for many countries and territories. All abbreviations for countries used in the Translation Project should come from this standard.

`AD'
Andorra.
`AE'
United Arab Emirates.
`AF'
Afghanistan.
`AG'
Antigua and Barbuda.
`AI'
Anguilla.
`AL'
Albania.
`AM'
Armenia.
`AN'
Netherlands Antilles.
`AO'
Angola.
`AQ'
Antarctica.
`AR'
Argentina.
`AS'
Samoa (American).
`AT'
Austria.
`AU'
Australia.
`AW'
Aruba.
`AZ'
Azerbaijan.
`BA'
Bosnia and Herzegovina.
`BB'
Barbados.
`BD'
Bangladesh.
`BE'
Belgium.
`BF'
Burkina Faso.
`BG'
Bulgaria.
`BH'
Bahrain.
`BI'
Burundi.
`BJ'
Benin.
`BM'
Bermuda.
`BN'
Brunei.
`BO'
Bolivia.
`BR'
Brazil.
`BS'
Bahamas.
`BT'
Bhutan.
`BV'
Bouvet Island.
`BW'
Botswana.
`BY'
Belarus.
`BZ'
Belize.
`CA'
Canada.
`CC'
Cocos (Keeling) Islands.
`CD'
Congo (Dem. Rep.).
`CF'
Central African Rep..
`CG'
Congo (Rep.).
`CH'
Switzerland.
`CI'
Cote d'Ivoire.
`CK'
Cook Islands.
`CL'
Chile.
`CM'
Cameroon.
`CN'
China.
`CO'
Colombia.
`CR'
Costa Rica.
`CU'
Cuba.
`CV'
Cape Verde.
`CX'
Christmas Island.
`CY'
Cyprus.
`CZ'
Czech Republic.
`DE'
Germany.
`DJ'
Djibouti.
`DK'
Denmark.
`DM'
Dominica.
`DO'
Dominican Republic.
`DZ'
Algeria.
`EC'
Ecuador.
`EE'
Estonia.
`EG'
Egypt.
`EH'
Western Sahara.
`ER'
Eritrea.
`ES'
Spain.
`ET'
Ethiopia.
`FI'
Finland.
`FJ'
Fiji.
`FK'
Falkland Islands.
`FM'
Micronesia.
`FO'
Faeroe Islands.
`FR'
France.
`GA'
Gabon.
`GB'
Britain (UK).
`GD'
Grenada.
`GE'
Georgia.
`GF'
French Guiana.
`GH'
Ghana.
`GI'
Gibraltar.
`GL'
Greenland.
`GM'
Gambia.
`GN'
Guinea.
`GP'
Guadeloupe.
`GQ'
Equatorial Guinea.
`GR'
Greece.
`GS'
South Georgia and the South Sandwich Islands.
`GT'
Guatemala.
`GU'
Guam.
`GW'
Guinea-Bissau.
`GY'
Guyana.
`HK'
Hong Kong.
`HM'
Heard Island and McDonald Islands.
`HN'
Honduras.
`HR'
Croatia.
`HT'
Haiti.
`HU'
Hungary.
`ID'
Indonesia.
`IE'
Ireland.
`IL'
Israel.
`IN'
India.
`IO'
British Indian Ocean Territory.
`IQ'
Iraq.
`IR'
Iran.
`IS'
Iceland.
`IT'
Italy.
`JM'
Jamaica.
`JO'
Jordan.
`JP'
Japan.
`KE'
Kenya.
`KG'
Kyrgyzstan.
`KH'
Cambodia.
`KI'
Kiribati.
`KM'
Comoros.
`KN'
St Kitts and Nevis.
`KP'
Korea (North).
`KR'
Korea (South).
`KW'
Kuwait.
`KY'
Cayman Islands.
`KZ'
Kazakhstan.
`LA'
Laos.
`LB'
Lebanon.
`LC'
St Lucia.
`LI'
Liechtenstein.
`LK'
Sri Lanka.
`LR'
Liberia.
`LS'
Lesotho.
`LT'
Lithuania.
`LU'
Luxembourg.
`LV'
Latvia.
`LY'
Libya.
`MA'
Morocco.
`MC'
Monaco.
`MD'
Moldova.
`MG'
Madagascar.
`MH'
Marshall Islands.
`MK'
Macedonia.
`ML'
Mali.
`MM'
Myanmar (Burma).
`MN'
Mongolia.
`MO'
Macao.
`MP'
Northern Mariana Islands.
`MQ'
Martinique.
`MR'
Mauritania.
`MS'
Montserrat.
`MT'
Malta.
`MU'
Mauritius.
`MV'
Maldives.
`MW'
Malawi.
`MX'
Mexico.
`MY'
Malaysia.
`MZ'
Mozambique.
`NA'
Namibia.
`NC'
New Caledonia.
`NE'
Niger.
`NF'
Norfolk Island.
`NG'
Nigeria.
`NI'
Nicaragua.
`NL'
Netherlands.
`NO'
Norway.
`NP'
Nepal.
`NR'
Nauru.
`NU'
Niue.
`NZ'
New Zealand.
`OM'
Oman.
`PA'
Panama.
`PE'
Peru.
`PF'
French Polynesia.
`PG'
Papua New Guinea.
`PH'
Philippines.
`PK'
Pakistan.
`PL'
Poland.
`PM'
St Pierre and Miquelon.
`PN'
Pitcairn.
`PR'
Puerto Rico.
`PS'
Palestine.
`PT'
Portugal.
`PW'
Palau.
`PY'
Paraguay.
`QA'
Qatar.
`RE'
Reunion.
`RO'
Romania.
`RU'
Russia.
`RW'
Rwanda.
`SA'
Saudi Arabia.
`SB'
Solomon Islands.
`SC'
Seychelles.
`SD'
Sudan.
`SE'
Sweden.
`SG'
Singapore.
`SH'
St Helena.
`SI'
Slovenia.
`SJ'
Svalbard and Jan Mayen.
`SK'
Slovakia.
`SL'
Sierra Leone.
`SM'
San Marino.
`SN'
Senegal.
`SO'
Somalia.
`SR'
Suriname.
`ST'
Sao Tome and Principe.
`SV'
El Salvador.
`SY'
Syria.
`SZ'
Swaziland.
`TC'
Turks and Caicos Is.
`TD'
Chad.
`TF'
French Southern and Antarctic Lands.
`TG'
Togo.
`TH'
Thailand.
`TJ'
Tajikistan.
`TK'
Tokelau.
`TM'
Turkmenistan.
`TN'
Tunisia.
`TO'
Tonga.
`TP'
East Timor.
`TR'
Turkey.
`TT'
Trinidad and Tobago.
`TV'
Tuvalu.
`TW'
Taiwan.
`TZ'
Tanzania.
`UA'
Ukraine.
`UG'
Uganda.
`UM'
US minor outlying islands.
`US'
United States.
`UY'
Uruguay.
`UZ'
Uzbekistan.
`VA'
Vatican City.
`VC'
St Vincent.
`VE'
Venezuela.
`VG'
Virgin Islands (UK).
`VI'
Virgin Islands (US).
`VN'
Vietnam.
`VU'
Vanuatu.
`WF'
Wallis and Futuna.
`WS'
Samoa (Western).
`YE'
Yemen.
`YT'
Mayotte.
`YU'
Yugoslavia.
`ZA'
South Africa.
`ZM'
Zambia.
`ZW'
Zimbabwe.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Program Index

Jump to: G M N X

 | Index Entry | Section
G |  |
 | gettext | 13.5.2 sh - Shell Script
 | gettext | 13.5.3 bash - Bourne-Again Shell Script
 | gettextize | 12.3 Invoking the gettextize Program
M |  |
 | msgattrib | 7.8 Invoking the msgattrib Program
 | msgcat | 7.1 Invoking the msgcat Program
 | msgcmp | 7.7 Invoking the msgcmp Program
 | msgcomm | 7.6 Invoking the msgcomm Program
 | msgconv | 7.2 Invoking the msgconv Program
 | msgen | 7.9 Invoking the msgen Program
 | msgexec | 7.10 Invoking the msgexec Program
 | msgfilter | 7.4 Invoking the msgfilter Program
 | msgfmt | 8.1 Invoking the msgfmt Program
 | msggrep | 7.3 Invoking the msggrep Program
 | msginit | 5.1 Invoking the msginit Program
 | msgmerge | 6.1 Invoking the msgmerge Program
 | msgunfmt | 8.2 Invoking the msgunfmt Program
 | msguniq | 7.5 Invoking the msguniq Program
N |  |
 | ngettext | 13.5.2 sh - Shell Script
 | ngettext | 13.5.3 bash - Bourne-Again Shell Script
X |  |
 | xgettext | 4.1 Invoking the xgettext Program

Jump to: G M N X

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Option Index

Jump to: -

 | Index Entry | Section
- |  |
 | --add-comments, xgettext option | 4.1.4 Operation mode
 | --add-location, msgattrib option | 7.8.5 Output details
 | --add-location, msgcat option | 7.1.4 Output details
 | --add-location, msgcomm option | 7.6.4 Output details
 | --add-location, msgconv option | 7.2.4 Output details
 | --add-location, msgen option | 7.9.3 Output details
 | --add-location, msgfilter option | 7.4.5 Output details
 | --add-location, msggrep option | 7.3.4 Output details
 | --add-location, msgmerge option | 6.1.6 Output details
 | --add-location, msguniq option | 7.5.4 Output details
 | --add-location, xgettext option | 4.1.6 Output details
 | --alignment, msgfmt option | 8.1.7 Output details
 | --backup, msgmerge option | 6.1.4 Output file location in update mode
 | --c++, xgettext option | 4.1.3 Choice of input file language
 | --check, msgfmt option | 8.1.6 Input file interpretation
 | --check-accelerators, msgfmt option | 8.1.6 Input file interpretation
 | --check-compatibility, msgfmt option | 8.1.6 Input file interpretation
 | --check-domain, msgfmt option | 8.1.6 Input file interpretation
 | --check-format, msgfmt option | 8.1.6 Input file interpretation
 | --check-header, msgfmt option | 8.1.6 Input file interpretation
 | --clear-fuzzy, msgattrib option | 7.8.4 Attribute manipulation
 | --clear-obsolete, msgattrib option | 7.8.4 Attribute manipulation
 | --compendium, msgmerge option | 6.1.1 Input file location
 | --copy, gettextize option | 12.3 Invoking the gettextize Program
 | --copyright-holder, xgettext option | 4.1.6 Output details
 | --debug, xgettext option | 4.1.5 Language=C/C++ specific options
 | --default-domain, xgettext option | 4.1.2 Output file location
 | --directory, msgattrib option | 7.8.1 Input file location
 | --directory, msgcat option | 7.1.1 Input file location
 | --directory, msgcmp option | 7.7.1 Input file location
 | --directory, msgcomm option | 7.6.1 Input file location
 | --directory, msgconv option | 7.2.1 Input file location
 | --directory, msgen option | 7.9.1 Input file location
 | --directory, msgexec option | 7.10.1 Input file location
 | --directory, msgfilter option | 7.4.1 Input file location
 | --directory, msgfmt option | 8.1.1 Input file location
 | --directory, msggrep option | 7.3.1 Input file location
 | --directory, msgmerge option | 6.1.1 Input file location
 | --directory, msguniq option | 7.5.1 Input file location
 | --directory, xgettext option | 4.1.1 Input file location
 | --domain, msggrep option | 7.3.3 Message selection
 | --exclude-file, xgettext option | 4.1.4 Operation mode
 | --expression, msgfilter option | 7.4.4 Useful filter-options when the filter is `sed'
 | --extended-regexp, msggrep option | 7.3.3 Message selection
 | --extract-all, xgettext option | 4.1.5 Language=C/C++ specific options
 | --file, msgfilter option | 7.4.4 Useful filter-options when the filter is `sed'
 | --file, msggrep option | 7.3.3 Message selection
 | --files-from, msgcat option | 7.1.1 Input file location
 | --files-from, msgcomm option | 7.6.1 Input file location
 | --files-from, xgettext option | 4.1.1 Input file location
 | --fixed-strings, msggrep option | 7.3.3 Message selection
 | --force, gettextize option | 12.3 Invoking the gettextize Program
 | --force-po, msgattrib option | 7.8.5 Output details
 | --force-po, msgcat option | 7.1.4 Output details
 | --force-po, msgcomm option | 7.6.4 Output details
 | --force-po, msgconv option | 7.2.4 Output details
 | --force-po, msgen option | 7.9.3 Output details
 | --force-po, msgfilter option | 7.4.5 Output details
 | --force-po, msggrep option | 7.3.4 Output details
 | --force-po, msgmerge option | 6.1.6 Output details
 | --force-po, msgunfmt option | 8.2.6 Output details
 | --force-po, msguniq option | 7.5.4 Output details
 | --force-po, xgettext option | 4.1.6 Output details
 | --foreign-user, xgettext option | 4.1.6 Output details
 | --fuzzy, msgattrib option | 7.8.4 Attribute manipulation
 | --help, gettextize option | 12.3 Invoking the gettextize Program
 | --help, msgattrib option | 7.8.6 Informative output
 | --help, msgcat option | 7.1.5 Informative output
 | --help, msgcmp option | 7.7.3 Informative output
 | --help, msgcomm option | 7.6.5 Informative output
 | --help, msgconv option | 7.2.5 Informative output
 | --help, msgen option | 7.9.4 Informative output
 | --help, msgexec option | 7.10.2 Informative output
 | --help, msgfilter option | 7.4.6 Informative output
 | --help, msgfmt option | 8.1.8 Informative output
 | --help, msggrep option | 7.3.5 Informative output
 | --help, msginit option | 5.1.4 Informative output
 | --help, msgmerge option | 6.1.7 Informative output
 | --help, msgunfmt option | 8.2.7 Informative output
 | --help, msguniq option | 7.5.5 Informative output
 | --help, xgettext option | 4.1.7 Informative output
 | --ignore-case, msggrep option | 7.3.3 Message selection
 | --indent, msgattrib option | 7.8.5 Output details
 | --indent, msgcat option | 7.1.4 Output details
 | --indent, msgcomm option | 7.6.4 Output details
 | --indent, msgconv option | 7.2.4 Output details
 | --indent, msgen option | 7.9.3 Output details
 | --indent, msgfilter option | 7.4.5 Output details
 | --indent, msggrep option | 7.3.4 Output details
 | --indent, msgmerge option | 6.1.6 Output details
 | --indent, msgunfmt option | 8.2.6 Output details
 | --indent, msguniq option | 7.5.4 Output details
 | --indent, xgettext option | 4.1.6 Output details
 | --input, msgexec option | 7.10.1 Input file location
 | --input, msgfilter option | 7.4.1 Input file location
 | --input, msginit option | 5.1.1 Input file location
 | --intl, gettextize option | 12.3 Invoking the gettextize Program
 | --java, msgfmt option | 8.1.2 Operation mode
 | --java, msgunfmt option | 8.2.1 Operation mode
 | --java2, msgfmt option | 8.1.2 Operation mode
 | --join-existing, xgettext option | 4.1.4 Operation mode
 | --keep-header, msgfilter option | 7.4.5 Output details
 | --keyword, xgettext option | 4.1.5 Language=C/C++ specific options
 | --language, xgettext option | 4.1.3 Choice of input file language
 | --less-than, msgcat option | 7.1.3 Message selection
 | --less-than, msgcomm option | 7.6.3 Message selection
 | --locale, msgfmt option | 8.1.4 Output file location in Java mode
 | --locale, msgfmt option | 8.1.5 Output file location in Tcl mode
 | --locale, msginit option | 5.1.3 Output details
 | --locale, msgunfmt option | 8.2.3 Input file location in Java mode
 | --locale, msgunfmt option | 8.2.4 Input file location in Tcl mode
 | --location, msggrep option | 7.3.3 Message selection
 | --more-than, msgcat option | 7.1.3 Message selection
 | --more-than, msgcomm option | 7.6.3 Message selection
 | --msgid, msggrep option | 7.3.3 Message selection
 | --msgstr, msggrep option | 7.3.3 Message selection
 | --msgstr-prefix, xgettext option | 4.1.6 Output details
 | --msgstr-suffix, xgettext option | 4.1.6 Output details
 | --multi-domain, msgcmp option | 7.7.2 Operation modifiers
 | --multi-domain, msgmerge option | 6.1.5 Operation modifiers
 | --no-changelog, gettextize option | 12.3 Invoking the gettextize Program
 | --no-fuzzy, msgattrib option | 7.8.3 Message selection
 | --no-hash, msgfmt option | 8.1.7 Output details
 | --no-location, msgattrib option | 7.8.5 Output details
 | --no-location, msgcat option | 7.1.4 Output details
 | --no-location, msgcomm option | 7.6.4 Output details
 | --no-location, msgconv option | 7.2.4 Output details
 | --no-location, msgen option | 7.9.3 Output details
 | --no-location, msgfilter option | 7.4.5 Output details
 | --no-location, msggrep option | 7.3.4 Output details
 | --no-location, msgmerge option | 6.1.6 Output details
 | --no-location, msguniq option | 7.5.4 Output details
 | --no-location, xgettext option | 4.1.6 Output details
 | --no-obsolete, msgattrib option | 7.8.3 Message selection
 | --no-translator, msginit option | 5.1.3 Output details
 | --no-wrap, msgattrib option | 7.8.5 Output details
 | --no-wrap, msgcat option | 7.1.4 Output details
 | --no-wrap, msgcomm option | 7.6.4 Output details
 | --no-wrap, msgconv option | 7.2.4 Output details
 | --no-wrap, msgen option | 7.9.3 Output details
 | --no-wrap, msgfilter option | 7.4.5 Output details
 | --no-wrap, msggrep option | 7.3.4 Output details
 | --no-wrap, msginit option | 5.1.3 Output details
 | --no-wrap, msgmerge option | 6.1.6 Output details
 | --no-wrap, msgunfmt option | 8.2.6 Output details
 | --no-wrap, msguniq option | 7.5.4 Output details
 | --no-wrap, xgettext option | 4.1.6 Output details
 | --obsolete, msgattrib option | 7.8.4 Attribute manipulation
 | --omit-header, msgcomm option | 7.6.4 Output details
 | --omit-header, xgettext option | 4.1.6 Output details
 | --only-fuzzy, msgattrib option | 7.8.3 Message selection
 | --only-obsolete, msgattrib option | 7.8.3 Message selection
 | --output, xgettext option | 4.1.2 Output file location
 | --output-dir, xgettext option | 4.1.2 Output file location
 | --output-file, msgattrib option | 7.8.2 Output file location
 | --output-file, msgcat option | 7.1.2 Output file location
 | --output-file, msgcomm option | 7.6.2 Output file location
 | --output-file, msgconv option | 7.2.2 Output file location
 | --output-file, msgen option | 7.9.2 Output file location
 | --output-file, msgfilter option | 7.4.2 Output file location
 | --output-file, msgfmt option | 8.1.3 Output file location
 | --output-file, msggrep option | 7.3.2 Output file location
 | --output-file, msginit option | 5.1.2 Output file location
 | --output-file, msgmerge option | 6.1.3 Output file location
 | --output-file, msgunfmt option | 8.2.5 Output file location
 | --output-file, msguniq option | 7.5.2 Output file location
 | --quiet, msgfilter option | 7.4.4 Useful filter-options when the filter is `sed'
 | --quiet, msgmerge option | 6.1.7 Informative output
 | --regexp=, msggrep option | 7.3.3 Message selection
 | --repeated, msguniq option | 7.5.3 Message selection
 | --resource, msgfmt option | 8.1.4 Output file location in Java mode
 | --resource, msgunfmt option | 8.2.3 Input file location in Java mode
 | --set-fuzzy, msgattrib option | 7.8.4 Attribute manipulation
 | --set-obsolete, msgattrib option | 7.8.4 Attribute manipulation
 | --silent, msgfilter option | 7.4.4 Useful filter-options when the filter is `sed'
 | --silent, msgmerge option | 6.1.7 Informative output
 | --sort-by-file, msgattrib option | 7.8.5 Output details
 | --sort-by-file, msgcat option | 7.1.4 Output details
 | --sort-by-file, msgcomm option | 7.6.4 Output details
 | --sort-by-file, msgconv option | 7.2.4 Output details
 | --sort-by-file, msgen option | 7.9.3 Output details
 | --sort-by-file, msgfilter option | 7.4.5 Output details
 | --sort-by-file, msggrep option | 7.3.4 Output details
 | --sort-by-file, msgmerge option | 6.1.6 Output details
 | --sort-by-file, msguniq option | 7.5.4 Output details
 | --sort-by-file, xgettext option | 4.1.6 Output details
 | --sort-output, msgattrib option | 7.8.5 Output details
 | --sort-output, msgcat option | 7.1.4 Output details
 | --sort-output, msgcomm option | 7.6.4 Output details
 | --sort-output, msgconv option | 7.2.4 Output details
 | --sort-output, msgen option | 7.9.3 Output details
 | --sort-output, msgfilter option | 7.4.5 Output details
 | --sort-output, msggrep option | 7.3.4 Output details
 | --sort-output, msgmerge option | 6.1.6 Output details
 | --sort-output, msgunfmt option | 8.2.6 Output details
 | --sort-output, msguniq option | 7.5.4 Output details
 | --sort-output, xgettext option | 4.1.6 Output details
 | --statistics, msgfmt option | 8.1.8 Informative output
 | --strict, msgattrib option | 7.8.5 Output details
 | --strict, msgcat option | 7.1.4 Output details
 | --strict, msgcomm option | 7.6.4 Output details
 | --strict, msgconv option | 7.2.4 Output details
 | --strict, msgen option | 7.9.3 Output details
 | --strict, msgfilter option | 7.4.5 Output details
 | --strict, msgfmt option | 8.1.3 Output file location
 | --strict, msggrep option | 7.3.4 Output details
 | --strict, msgmerge option | 6.1.6 Output details
 | --strict, msgunfmt option | 8.2.6 Output details
 | --strict, msguniq option | 7.5.4 Output details
 | --strict, xgettext option | 4.1.6 Output details
 | --suffix, msgmerge option | 6.1.4 Output file location in update mode
 | --tcl, msgfmt option | 8.1.2 Operation mode
 | --tcl, msgunfmt option | 8.2.1 Operation mode
 | --to-code, msgcat option | 7.1.4 Output details
 | --to-code, msgconv option | 7.2.3 Conversion target
 | --to-code, msguniq option | 7.5.4 Output details
 | --translated, msgattrib option | 7.8.3 Message selection
 | --trigraphs, xgettext option | 4.1.5 Language=C/C++ specific options
 | --unique, msgcat option | 7.1.3 Message selection
 | --unique, msgcomm option | 7.6.3 Message selection
 | --unique, msguniq option | 7.5.3 Message selection
 | --untranslated, msgattrib option | 7.8.3 Message selection
 | --update, msgmerge option | 6.1.2 Operation mode
 | --use-first, msgcat option | 7.1.4 Output details
 | --use-first, msguniq option | 7.5.4 Output details
 | --use-fuzzy, msgfmt option | 8.1.6 Input file interpretation
 | --verbose, msgfmt option | 8.1.8 Informative output
 | --verbose, msgmerge option | 6.1.7 Informative output
 | --verbose, msgunfmt option | 8.2.7 Informative output
 | --version, gettextize option | 12.3 Invoking the gettextize Program
 | --version, msgattrib option | 7.8.6 Informative output
 | --version, msgcat option | 7.1.5 Informative output
 | --version, msgcmp option | 7.7.3 Informative output
 | --version, msgcomm option | 7.6.5 Informative output
 | --version, msgconv option | 7.2.5 Informative output
 | --version, msgen option | 7.9.4 Informative output
 | --version, msgexec option | 7.10.2 Informative output
 | --version, msgfilter option | 7.4.6 Informative output
 | --version, msgfmt option | 8.1.8 Informative output
 | --version, msggrep option | 7.3.5 Informative output
 | --version, msginit option | 5.1.4 Informative output
 | --version, msgmerge option | 6.1.7 Informative output
 | --version, msgunfmt option | 8.2.7 Informative output
 | --version, msguniq option | 7.5.5 Informative output
 | --version, xgettext option | 4.1.7 Informative output
 | --width, msgattrib option | 7.8.5 Output details
 | --width, msgcat option | 7.1.4 Output details
 | --width, msgcomm option | 7.6.4 Output details
 | --width, msgconv option | 7.2.4 Output details
 | --width, msgen option | 7.9.3 Output details
 | --width, msgfilter option | 7.4.5 Output details
 | --width, msggrep option | 7.3.4 Output details
 | --width, msginit option | 5.1.3 Output details
 | --width, msgmerge option | 6.1.6 Output details
 | --width, msgunfmt option | 8.2.6 Output details
 | --width, msguniq option | 7.5.4 Output details
 | --width, xgettext option | 4.1.6 Output details
 | -<, msgcat option | 7.1.3 Message selection
 | -<, msgcomm option | 7.6.3 Message selection
 | ->, msgcat option | 7.1.3 Message selection
 | ->, msgcomm option | 7.6.3 Message selection
 | -a, msgfmt option | 8.1.7 Output details
 | -a, xgettext option | 4.1.5 Language=C/C++ specific options
 | -c, gettextize option | 12.3 Invoking the gettextize Program
 | -c, msgfmt option | 8.1.6 Input file interpretation
 | -C, msgfmt option | 8.1.6 Input file interpretation
 | -C, msgmerge option | 6.1.1 Input file location
 | -c, xgettext option | 4.1.4 Operation mode
 | -C, xgettext option | 4.1.3 Choice of input file language
 | -D, msgattrib option | 7.8.1 Input file location
 | -D, msgcat option | 7.1.1 Input file location
 | -D, msgcmp option | 7.7.1 Input file location
 | -D, msgcomm option | 7.6.1 Input file location
 | -D, msgconv option | 7.2.1 Input file location
 | -D, msgen option | 7.9.1 Input file location
 | -D, msgexec option | 7.10.1 Input file location
 | -D, msgfilter option | 7.4.1 Input file location
 | -d, msgfmt option | 8.1.4 Output file location in Java mode
 | -D, msgfmt option | 8.1.1 Input file location
 | -d, msgfmt option | 8.1.5 Output file location in Tcl mode
 | -D, msggrep option | 7.3.1 Input file location
 | -D, msgmerge option | 6.1.1 Input file location
 | -d, msgunfmt option | 8.2.4 Input file location in Tcl mode
 | -D, msguniq option | 7.5.1 Input file location
 | -d, msguniq option | 7.5.3 Message selection
 | -D, xgettext option | 4.1.1 Input file location
 | -d, xgettext option | 4.1.2 Output file location
 | -e, msgfilter option | 7.4.4 Useful filter-options when the filter is `sed'
 | -E, msggrep option | 7.3.3 Message selection
 | -e, msggrep option | 7.3.3 Message selection
 | -f, gettextize option | 12.3 Invoking the gettextize Program
 | -F, msgattrib option | 7.8.5 Output details
 | -F, msgcat option | 7.1.4 Output details
 | -f, msgcat option | 7.1.1 Input file location
 | -f, msgcomm option | 7.6.1 Input file location
 | -F, msgcomm option | 7.6.4 Output details
 | -F, msgconv option | 7.2.4 Output details
 | -F, msgen option | 7.9.3 Output details
 | -f, msgfilter option | 7.4.4 Useful filter-options when the filter is `sed'
 | -F, msgfilter option | 7.4.5 Output details
 | -f, msgfmt option | 8.1.6 Input file interpretation
 | -F, msggrep option | 7.3.3 Message selection
 | -f, msggrep option | 7.3.3 Message selection
 | -F, msgmerge option | 6.1.6 Output details
 | -F, msguniq option | 7.5.4 Output details
 | -f, xgettext option | 4.1.1 Input file location
 | -F, xgettext option | 4.1.6 Output details
 | -h, msgattrib option | 7.8.6 Informative output
 | -h, msgcat option | 7.1.5 Informative output
 | -h, msgcmp option | 7.7.3 Informative output
 | -h, msgcomm option | 7.6.5 Informative output
 | -h, msgconv option | 7.2.5 Informative output
 | -h, msgen option | 7.9.4 Informative output
 | -h, msgexec option | 7.10.2 Informative output
 | -h, msgfilter option | 7.4.6 Informative output
 | -h, msgfmt option | 8.1.8 Informative output
 | -h, msggrep option | 7.3.5 Informative output
 | -h, msginit option | 5.1.4 Informative output
 | -h, msgmerge option | 6.1.7 Informative output
 | -h, msgunfmt option | 8.2.7 Informative output
 | -h, msguniq option | 7.5.5 Informative output
 | -h, xgettext option | 4.1.7 Informative output
 | -i, msgattrib option | 7.8.5 Output details
 | -i, msgcat option | 7.1.4 Output details
 | -i, msgcomm option | 7.6.4 Output details
 | -i, msgconv option | 7.2.4 Output details
 | -i, msgen option | 7.9.3 Output details
 | -i, msgexec option | 7.10.1 Input file location
 | -i, msgfilter option | 7.4.1 Input file location
 | -i, msggrep option | 7.3.3 Message selection
 | -i, msginit option | 5.1.1 Input file location
 | -i, msgmerge option | 6.1.6 Output details
 | -i, msgunfmt option | 8.2.6 Output details
 | -i, msguniq option | 7.5.4 Output details
 | -i, xgettext option | 4.1.6 Output details
 | -j, msgfmt option | 8.1.2 Operation mode
 | -j, msgunfmt option | 8.2.1 Operation mode
 | -j, xgettext option | 4.1.4 Operation mode
 | -K, msggrep option | 7.3.3 Message selection
 | -k, xgettext option | 4.1.5 Language=C/C++ specific options
 | -l, msgfmt option | 8.1.4 Output file location in Java mode
 | -l, msgfmt option | 8.1.5 Output file location in Tcl mode
 | -l, msginit option | 5.1.3 Output details
 | -l, msgunfmt option | 8.2.3 Input file location in Java mode
 | -l, msgunfmt option | 8.2.4 Input file location in Tcl mode
 | -L, xgettext option | 4.1.3 Choice of input file language
 | -m, msgcmp option | 7.7.2 Operation modifiers
 | -M, msggrep option | 7.3.3 Message selection
 | -m, msgmerge option | 6.1.5 Operation modifiers
 | -m, xgettext option | 4.1.6 Output details
 | -M, xgettext option | 4.1.6 Output details
 | -n, msgattrib option | 7.8.5 Output details
 | -n, msgcat option | 7.1.4 Output details
 | -n, msgcomm option | 7.6.4 Output details
 | -n, msgfilter option | 7.4.4 Useful filter-options when the filter is `sed'
 | -N, msggrep option | 7.3.3 Message selection
 | -n, msguniq option | 7.5.4 Output details
 | -n, xgettext option | 4.1.6 Output details
 | -o, msgattrib option | 7.8.2 Output file location
 | -o, msgcat option | 7.1.2 Output file location
 | -o, msgcomm option | 7.6.2 Output file location
 | -o, msgconv option | 7.2.2 Output file location
 | -o, msgen option | 7.9.2 Output file location
 | -o, msgfilter option | 7.4.2 Output file location
 | -o, msgfmt option | 8.1.3 Output file location
 | -o, msggrep option | 7.3.2 Output file location
 | -o, msginit option | 5.1.2 Output file location
 | -o, msgmerge option | 6.1.3 Output file location
 | -o, msgunfmt option | 8.2.5 Output file location
 | -o, msguniq option | 7.5.2 Output file location
 | -o, xgettext option | 4.1.2 Output file location
 | -p, xgettext option | 4.1.2 Output file location
 | -q, msgmerge option | 6.1.7 Informative output
 | -r, msgfmt option | 8.1.4 Output file location in Java mode
 | -r, msgunfmt option | 8.2.3 Input file location in Java mode
 | -s, msgattrib option | 7.8.5 Output details
 | -s, msgcat option | 7.1.4 Output details
 | -s, msgcomm option | 7.6.4 Output details
 | -s, msgconv option | 7.2.4 Output details
 | -s, msgen option | 7.9.3 Output details
 | -s, msgfilter option | 7.4.5 Output details
 | -s, msgmerge option | 6.1.6 Output details
 | -s, msgunfmt option | 8.2.6 Output details
 | -s, msguniq option | 7.5.4 Output details
 | -s, xgettext option | 4.1.6 Output details
 | -t, msgcat option | 7.1.4 Output details
 | -t, msgconv option | 7.2.3 Conversion target
 | -T, msggrep option | 7.3.3 Message selection
 | -t, msguniq option | 7.5.4 Output details
 | -T, xgettext option | 4.1.5 Language=C/C++ specific options
 | -u, msgcat option | 7.1.3 Message selection
 | -u, msgcomm option | 7.6.3 Message selection
 | -U, msgmerge option | 6.1.2 Operation mode
 | -u, msguniq option | 7.5.3 Message selection
 | -V, msgattrib option | 7.8.6 Informative output
 | -V, msgcat option | 7.1.5 Informative output
 | -V, msgcmp option | 7.7.3 Informative output
 | -V, msgcomm option | 7.6.5 Informative output
 | -V, msgconv option | 7.2.5 Informative output
 | -V, msgen option | 7.9.4 Informative output
 | -V, msgexec option | 7.10.2 Informative output
 | -V, msgfilter option | 7.4.6 Informative output
 | -v, msgfmt option | 8.1.8 Informative output
 | -V, msgfmt option | 8.1.8 Informative output
 | -V, msggrep option | 7.3.5 Informative output
 | -V, msginit option | 5.1.4 Informative output
 | -v, msgmerge option | 6.1.7 Informative output
 | -V, msgmerge option | 6.1.7 Informative output
 | -V, msgunfmt option | 8.2.7 Informative output
 | -v, msgunfmt option | 8.2.7 Informative output
 | -V, msguniq option | 7.5.5 Informative output
 | -V, xgettext option | 4.1.7 Informative output
 | -w, msgattrib option | 7.8.5 Output details
 | -w, msgcat option | 7.1.4 Output details
 | -w, msgcomm option | 7.6.4 Output details
 | -w, msgconv option | 7.2.4 Output details
 | -w, msgen option | 7.9.3 Output details
 | -w, msgfilter option | 7.4.5 Output details
 | -w, msggrep option | 7.3.4 Output details
 | -w, msginit option | 5.1.3 Output details
 | -w, msgmerge option | 6.1.6 Output details
 | -w, msgunfmt option | 8.2.6 Output details
 | -w, msguniq option | 7.5.4 Output details
 | -w, xgettext option | 4.1.6 Output details
 | -x, xgettext option | 4.1.4 Operation mode

Jump to: -

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Variable Index

Jump to: L M T

 | Index Entry | Section
L |  |
 | LANG, environment variable | 9.3 Magic for End Users
 | LANG, environment variable | 10.5 Being a gettext grok
 | LANGUAGE, environment variable | 10.5 Being a gettext grok
 | LANGUAGE, environment variable | 12.4.3 `Makefile' pieces in `po/'
 | LC_ALL, environment variable | 10.5 Being a gettext grok
 | LC_COLLATE, environment variable | 10.5 Being a gettext grok
 | LC_CTYPE, environment variable | 10.5 Being a gettext grok
 | LC_MESSAGES, environment variable | 10.5 Being a gettext grok
 | LC_MONETARY, environment variable | 10.5 Being a gettext grok
 | LC_NUMERIC, environment variable | 10.5 Being a gettext grok
 | LC_TIME, environment variable | 10.5 Being a gettext grok
 | LINGUAS, environment variable | 9.2 Magic for Installers
M |  |
 | MSGEXEC_LOCATION, environment variable | 7.10 Invoking the msgexec Program
 | MSGEXEC_MSGID, environment variable | 7.10 Invoking the msgexec Program
T |  |
 | TEXTDOMAIN, environment variable | 13.5.2 sh - Shell Script
 | TEXTDOMAIN, environment variable | 13.5.3 bash - Bourne-Again Shell Script
 | TEXTDOMAINDIR, environment variable | 13.5.2 sh - Shell Script
 | TEXTDOMAINDIR, environment variable | 13.5.3 bash - Bourne-Again Shell Script

Jump to: L M T

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

PO Mode Index

Jump to: # , . 0 < = > ? _
A C D E F H I K L M N O P Q R S T U V W X Y Z

 | Index Entry | Section
# |  |
 | #, PO Mode command | 6.7 Modifying Comments
 | #, PO Mode command | 6.7 Modifying Comments
, |  |
 | ,, PO Mode command | 3.4 Marking Translatable Strings
. |  |
 | ., PO Mode command | 2.4 Entry Positioning
 | ., PO Mode command | 2.4 Entry Positioning
 | `.emacs' customizations | 2.1 Completing GNU gettext Installation
0 |  |
 | 0, PO Mode command | 2.3 Main PO mode Commands
 | 0, PO Mode command | 2.3 Main PO mode Commands
< |  |
 | <, PO Mode command | 2.4 Entry Positioning
 | <, PO Mode command | 2.4 Entry Positioning
= |  |
 | =, PO Mode command | 2.3 Main PO mode Commands
 | =, PO Mode command | 2.3 Main PO mode Commands
> |  |
 | >, PO Mode command | 2.4 Entry Positioning
 | >, PO Mode command | 2.4 Entry Positioning
? |  |
 | ?, PO Mode command | 2.3 Main PO mode Commands
 | ?, PO Mode command | 2.3 Main PO mode Commands
_ |  |
 | _, PO Mode command | 2.3 Main PO mode Commands
 | _, PO Mode command | 2.3 Main PO mode Commands
A |  |
 | A, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | a, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | A, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | a, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | auxiliary PO file | 6.10 Consulting Auxiliary PO Files
C |  |
 | C-c C-a, PO Mode command | 6.8 Details of Sub Edition
 | C-c C-a, PO Mode command | 6.8 Details of Sub Edition
 | C-c C-a, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | C-c C-a, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | C-c C-c, PO Mode command | 6.8 Details of Sub Edition
 | C-c C-c, PO Mode command | 6.8 Details of Sub Edition
 | C-c C-k, PO Mode command | 6.8 Details of Sub Edition
 | C-c C-k, PO Mode command | 6.8 Details of Sub Edition
 | C-j, PO Mode command | 6.6 Modifying Translations
 | C-j, PO Mode command | 6.6 Modifying Translations
 | commands | 2.3 Main PO mode Commands
 | comment out PO file entry | 6.5 Obsolete Entries
 | consulting program sources | 6.9 C Sources Context
 | consulting translations to other languages | 6.10 Consulting Auxiliary PO Files
 | current entry of a PO file | 2.4 Entry Positioning
 | cut and paste for translated strings | 6.6 Modifying Translations
D |  |
 | DEL, PO Mode command | 6.3 Fuzzy Entries
 | DEL, PO Mode command | 6.5 Obsolete Entries
 | DEL, PO Mode command | 6.5 Obsolete Entries
E |  |
 | editing comments | 6.7 Modifying Comments
 | editing multiple entries | 6.8 Details of Sub Edition
 | editing translations | 6.6 Modifying Translations
 | etags, using for marking strings | 3.4 Marking Translatable Strings
 | exiting PO subedit | 6.8 Details of Sub Edition
F |  |
 | find source fragment for a PO file entry | 6.9 C Sources Context
H |  |
 | h, PO Mode command | 2.3 Main PO mode Commands
 | h, PO Mode command | 2.3 Main PO mode Commands
I |  |
 | installing PO mode | 2.1 Completing GNU gettext Installation
K |  |
 | K, PO Mode command | 6.7 Modifying Comments
 | k, PO Mode command | 6.4 Untranslated Entries
 | k, PO Mode command | 6.4 Untranslated Entries
 | K, PO Mode command | 6.7 Modifying Comments
 | k, PO Mode command | 6.6 Modifying Translations
 | k, PO Mode command | 6.6 Modifying Translations
L |  |
 | LFD, PO Mode command | 6.6 Modifying Translations
 | LFD, PO Mode command | 6.6 Modifying Translations
 | looking at the source to aid translation | 6.9 C Sources Context
M |  |
 | m, PO Mode command | 2.4 Entry Positioning
 | m, PO Mode command | 2.4 Entry Positioning
 | M-,, PO Mode command | 3.4 Marking Translatable Strings
 | M-., PO Mode command | 3.4 Marking Translatable Strings
 | M-A, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | M-A, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | M-s, PO Mode command | 6.9 C Sources Context
 | M-S, PO Mode command | 6.9 C Sources Context
 | M-s, PO Mode command | 6.9 C Sources Context
 | M-S, PO Mode command | 6.9 C Sources Context
 | marking strings for translation | 3.4 Marking Translatable Strings
 | moving by fuzzy entries | 6.3 Fuzzy Entries
 | moving by obsolete entries | 6.5 Obsolete Entries
 | moving by translated entries | 6.2 Translated Entries
 | moving by untranslated entries | 6.4 Untranslated Entries
 | moving through a PO file | 2.4 Entry Positioning
N |  |
 | n, PO Mode command | 2.4 Entry Positioning
 | n, PO Mode command | 2.4 Entry Positioning
 | next-error, stepping through PO file validation results | 2.3 Main PO mode Commands
 | normalize, PO Mode command | 6.10 Consulting Auxiliary PO Files
O |  |
 | O, PO Mode command | 6.5 Obsolete Entries
 | o, PO Mode command | 6.5 Obsolete Entries
 | O, PO Mode command | 6.5 Obsolete Entries
 | o, PO Mode command | 6.5 Obsolete Entries
 | obsolete active entry | 6.5 Obsolete Entries
P |  |
 | p, PO Mode command | 2.4 Entry Positioning
 | p, PO Mode command | 2.4 Entry Positioning
 | pending subedits | 6.8 Details of Sub Edition
 | po-auto-edit-with-msgid, PO Mode variable | 6.6 Modifying Translations
 | po-auto-fuzzy-on-edit, PO Mode variable | 6.2 Translated Entries
 | po-auto-select-on-unfuzzy, PO Mode variable | 6.3 Fuzzy Entries
 | po-confirm-and-quit, PO Mode command | 2.3 Main PO mode Commands
 | po-consider-as-auxiliary, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | po-consider-source-path, PO Mode command | 6.9 C Sources Context
 | po-current-entry, PO Mode command | 2.4 Entry Positioning
 | po-cycle-auxiliary, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | po-cycle-source-reference, PO Mode command | 6.9 C Sources Context
 | po-edit-comment, PO Mode command | 6.7 Modifying Comments
 | po-edit-msgstr, PO Mode command | 6.6 Modifying Translations
 | po-exchange-location, PO Mode command | 2.4 Entry Positioning
 | po-fade-out-entry, PO Mode command | 6.3 Fuzzy Entries
 | po-fade-out-entry, PO Mode command | 6.5 Obsolete Entries
 | po-first-entry, PO Mode command | 2.4 Entry Positioning
 | po-help, PO Mode command | 2.3 Main PO mode Commands
 | po-ignore-as-auxiliary, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | po-ignore-source-path, PO Mode command | 6.9 C Sources Context
 | po-kill-comment, PO Mode command | 6.7 Modifying Comments
 | po-kill-msgstr, PO Mode command | 6.4 Untranslated Entries
 | po-kill-msgstr, PO Mode command | 6.6 Modifying Translations
 | po-kill-ring-save-comment, PO Mode command | 6.7 Modifying Comments
 | po-kill-ring-save-msgstr, PO Mode command | 6.6 Modifying Translations
 | po-last-entry, PO Mode command | 2.4 Entry Positioning
 | po-mark-translatable, PO Mode command | 3.4 Marking Translatable Strings
 | po-msgid-to-msgstr, PO Mode command | 6.6 Modifying Translations
 | po-next-entry, PO Mode command | 2.4 Entry Positioning
 | po-next-fuzzy-entry, PO Mode command | 6.3 Fuzzy Entries
 | po-next-obsolete-entry, PO Mode command | 6.5 Obsolete Entries
 | po-next-translated-entry, PO Mode command | 6.2 Translated Entries
 | po-next-untranslated-entry, PO Mode command | 6.4 Untranslated Entries
 | po-normalize, PO Mode command | 2.2 The Format of PO Files
 | po-normalize, PO Mode command | 2.5 Normalizing Strings in Entries
 | po-other-window, PO Mode command | 2.3 Main PO mode Commands
 | po-pop-location, PO Mode command | 2.4 Entry Positioning
 | po-previous-entry, PO Mode command | 2.4 Entry Positioning
 | po-previous-fuzzy-entry, PO Mode command | 6.3 Fuzzy Entries
 | po-previous-obsolete-entry, PO Mode command | 6.5 Obsolete Entries
 | po-previous-translated-entry, PO Mode command | 6.2 Translated Entries
 | po-previous-untransted-entry, PO Mode command | 6.4 Untranslated Entries
 | po-push-location, PO Mode command | 2.4 Entry Positioning
 | po-quit, PO Mode command | 2.3 Main PO mode Commands
 | po-select-auxiliary, PO Mode command | 6.10 Consulting Auxiliary PO Files
 | po-select-mark-and-mark, PO Mode command | 3.4 Marking Translatable Strings
 | po-select-source-reference, PO Mode command | 6.9 C Sources Context
 | po-statistics, PO Mode command | 2.3 Main PO mode Commands
 | po-subedit-abort, PO Mode command | 6.8 Details of Sub Edition
 | po-subedit-cycle-auxiliary, PO Mode command | 6.8 Details of Sub Edition
 | po-subedit-exit, PO Mode command | 6.8 Details of Sub Edition
 | po-subedit-mode-hook, PO Mode variable | 6.7 Modifying Comments
 | po-tags-search, PO Mode command | 3.4 Marking Translatable Strings
 | po-undo, PO Mode command | 2.3 Main PO mode Commands
 | po-unfuzzy, PO Mode command | 6.3 Fuzzy Entries
 | po-validate, PO Mode command | 2.3 Main PO mode Commands
 | po-yank-comment, PO Mode command | 6.7 Modifying Comments
 | po-yank-msgstr, PO Mode command | 6.6 Modifying Translations
Q |  |
 | q, PO Mode command | 2.3 Main PO mode Commands
 | Q, PO Mode command | 2.3 Main PO mode Commands
 | q, PO Mode command | 2.3 Main PO mode Commands
 | Q, PO Mode command | 2.3 Main PO mode Commands
R |  |
 | r, PO Mode command | 2.4 Entry Positioning
 | r, PO Mode command | 2.4 Entry Positioning
 | RET, PO Mode command | 6.6 Modifying Translations
 | RET, PO Mode command | 6.6 Modifying Translations
S |  |
 | S, PO Mode command | 6.9 C Sources Context
 | s, PO Mode command | 6.9 C Sources Context
 | s, PO Mode command | 6.9 C Sources Context
 | S, PO Mode command | 6.9 C Sources Context
 | starting a string translation | 6.6 Modifying Translations
 | string normalization in entries | 2.5 Normalizing Strings in Entries
 | subedit minor mode | 6.8 Details of Sub Edition
T |  |
 | T, PO Mode command | 6.2 Translated Entries
 | t, PO Mode command | 6.2 Translated Entries
 | t, PO Mode command | 6.2 Translated Entries
 | T, PO Mode command | 6.2 Translated Entries
 | TAB, PO Mode command | 6.3 Fuzzy Entries
 | TAB, PO Mode command | 6.3 Fuzzy Entries
 | `TAGS', and marking translatable strings | 3.4 Marking Translatable Strings
U |  |
 | u, PO Mode command | 6.4 Untranslated Entries
 | U, PO Mode command | 6.4 Untranslated Entries
 | u, PO Mode command | 6.4 Untranslated Entries
 | U, PO Mode command | 6.4 Untranslated Entries
 | use the source, Luke | 6.9 C Sources Context
 | using obsolete translations to make new entries | 6.6 Modifying Translations
 | using translation compendia | 6.11 Using Translation Compendia
V |  |
 | V, PO Mode command | 2.3 Main PO mode Commands
 | V, PO Mode command | 2.3 Main PO mode Commands
W |  |
 | W, PO Mode command | 6.7 Modifying Comments
 | w, PO Mode command | 6.6 Modifying Translations
 | W, PO Mode command | 6.7 Modifying Comments
 | w, PO Mode command | 6.6 Modifying Translations
X |  |
 | x, PO Mode command | 2.4 Entry Positioning
 | x, PO Mode command | 2.4 Entry Positioning
Y |  |
 | Y, PO Mode command | 6.7 Modifying Comments
 | y, PO Mode command | 6.6 Modifying Translations
 | y, PO Mode command | 6.6 Modifying Translations
 | Y, PO Mode command | 6.7 Modifying Comments
Z |  |
 | Z, PO Mode command | 6.3 Fuzzy Entries
 | z, PO Mode command | 6.3 Fuzzy Entries
 | Z, PO Mode command | 6.3 Fuzzy Entries
 | z, PO Mode command | 6.3 Fuzzy Entries

Jump to: # , . 0 < = > ? _
A C D E F H I K L M N O P Q R S T U V W X Y Z

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Autoconf Macro Index

Jump to: A

 | Index Entry | Section
A |  |
 | AM_GNU_GETTEXT | 12.5.1 AM_GNU_GETTEXT in `gettext.m4'
 | AM_ICONV | 12.5.2 AM_ICONV in `iconv.m4'

Jump to: A

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

General Index

Jump to: _
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

 | Index Entry | Section
_ |  |
 | _, a macro to mark strings for translation | 3.3 How Marks Appear in Sources
 | _nl_msg_cat_cntr | 10.5 Being a gettext grok
A |  |
 | `ABOUT-NLS' file | 9.1 The Current `ABOUT-NLS' Matrix
 | `acconfig.h' file | 12.4.7 `acconfig.h' at top level
 | accumulating translations | 6.11.1.1 Concatenate PO Files
 | `aclocal.m4' file | 12.4.6 `aclocal.m4' at top level
 | adding keywords, xgettext | 4.1.5 Language=C/C++ specific options
 | ambiguities | 3.2 Preparing Translatable Strings
 | apply a filter to translations | 7.4 Invoking the msgfilter Program
 | apply command to all translations in a catalog | 7.10 Invoking the msgexec Program
 | attribute manipulation | 7.8 Invoking the msgattrib Program
 | attribute, fuzzy | 6.3 Fuzzy Entries
 | attributes of a PO file entry | 6.3 Fuzzy Entries
 | attributes, manipulating | 7. Manipulating PO Files
 | autoconf macros for gettext | 12.5 Autoconf macros for use in `configure.in'
 | auxiliary PO file | 6.10 Consulting Auxiliary PO Files
 | available translations | 9.1 The Current `ABOUT-NLS' Matrix
 | awk | 13.5.11 GNU awk
B |  |
 | backup old file, and msgmerge program | 6.1.4 Output file location in update mode
 | bash | 13.5.3 bash - Bourne-Again Shell Script
 | bibliography | 14.2 Related Readings
 | big picture | 1.5 Overview of GNU gettext
 | bind_textdomain_codeset | 10.2.4 How to specify the output character set gettext uses
 | bug report address | 1. Introduction
C |  |
 | C and C-like languages | 13.5.1 C, C++, Objective C
 | C trigraphs | 4.1.5 Language=C/C++ specific options
 | c-format flag | 2.2 The Format of PO Files
 | c-format, and xgettext | 3.5 Special Comments preceding Keywords
 | catalog encoding and msgexec output | 7.10 Invoking the msgexec Program
 | catclose, a catgets function | 10.1.1 The Interface
 | catgets, a catgets function | 10.1.1 The Interface
 | catgets, X/Open specification | 10.1 About catgets
 | catopen, a catgets function | 10.1.1 The Interface
 | character encoding | 1.3 Aspects in Native Language Support
 | charset conversion at runtime | 10.2.4 How to specify the output character set gettext uses
 | charset of PO files | 5.2 Filling in the Header Entry
 | check format strings | 8.1.6 Input file interpretation
 | checking of translations | 7. Manipulating PO Files
 | clisp | 13.5.5 GNU clisp - Common Lisp
 | clisp C sources | 13.5.6 GNU clisp C sources
 | codeset | 1.3 Aspects in Native Language Support
 | comments in PO files | 2.2 The Format of PO Files
 | Common Lisp | 13.5.5 GNU clisp - Common Lisp
 | compare PO files | 7.7 Invoking the msgcmp Program
 | comparison of interfaces | 10.3 Comparing the Two Interfaces
 | compatibility with X/Open msgfmt | 8.1.6 Input file interpretation
 | compendium | 6.11 Using Translation Compendia
 | compendium, creating | 6.11.1 Creating Compendia
 | concatenate PO files | 7.1 Invoking the msgcat Program
 | concatenating PO files into a compendium | 6.11.1.1 Concatenate PO Files
 | concatenation of strings | 3.2 Preparing Translatable Strings
 | convert binary message catalog into PO file | 8.2 Invoking the msgunfmt Program
 | convert translations to a different encoding | 7.2 Invoking the msgconv Program
 | converting a package to use gettext | 12.2 Prerequisite Works
 | country codes | B. Country Codes
 | create new PO file | 5.1 Invoking the msginit Program
 | creating a new PO file | 5. Creating a New PO File
 | creating compendia | 6.11.1 Creating Compendia
 | currency symbols | 1.3 Aspects in Native Language Support
D |  |
 | date format | 1.3 Aspects in Native Language Support
 | dcngettext | 10.2.5 Additional functions for plural forms
 | debugging messages marked as format strings | 4.1.5 Language=C/C++ specific options
 | dialect | 7. Manipulating PO Files
 | disabling NLS | 12.4.10 `gettext.h' in `lib/'
 | dngettext | 10.2.5 Additional functions for plural forms
 | domain ambiguities | 10.2.2 Solving Ambiguities
 | duplicate elimination | 7. Manipulating PO Files
 | duplicate removal | 7.5 Invoking the msguniq Program
E |  |
 | editing comments in PO files | 6.7 Modifying Comments
 | editing translations | 6.6 Modifying Translations
 | Emacs Lisp | 13.5.7 Emacs Lisp
 | encoding | 1.3 Aspects in Native Language Support
 | encoding conversion | 7. Manipulating PO Files
 | encoding conversion at runtime | 10.2.4 How to specify the output character set gettext uses
 | encoding for your language | 5.2 Filling in the Header Entry
 | encoding list | 5.2 Filling in the Header Entry
 | encoding of PO files | 5.2 Filling in the Header Entry
 | evolution of packages | 1.5 Overview of GNU gettext
 | extracting parts of a PO file into a compendium | 6.11.1.2 Extract a Message Subset from a PO File
F |  |
 | file format, `.mo' | 8.3 The Format of GNU MO Files
 | file format, `.po' | 2.2 The Format of PO Files
 | files, `.po' and `.mo' | 1.4 Files Conveying Translations
 | files, `.pot' | 1.5 Overview of GNU gettext
 | filter messages according to attributes | 7.8 Invoking the msgattrib Program
 | find common messages | 7.6 Invoking the msgcomm Program
 | force use of fuzzy entries | 8.1.6 Input file interpretation
 | format strings | 3.5 Special Comments preceding Keywords
 | Free Pascal | 13.5.12 Pascal - Free Pascal Compiler
 | fuzzy entries | 6.3 Fuzzy Entries
 | fuzzy flag | 2.2 The Format of PO Files
G |  |
 | gawk | 13.5.11 GNU awk
 | generate binary message catalog from PO file | 8.1 Invoking the msgfmt Program
 | generate translation catalog in English | 7.9 Invoking the msgen Program
 | gettext files | 12.4 Files You Must Create or Alter
 | gettext installation | 2.1 Completing GNU gettext Installation
 | gettext interface | 10.2.1 The Interface
 | gettext vs catgets | 10.3 Comparing the Two Interfaces
 | gettext, a programmer's view | 10.2 About gettext
 | `gettext.h' file | 12.4.10 `gettext.h' in `lib/'
 | gettextize program, usage | 12.3 Invoking the gettextize Program
 | GUI programs | 10.2.6 How to use gettext in GUI programs
H |  |
 | hash table, inside MO files | 8.3 The Format of GNU MO Files
 | he, she, and they | 1. Introduction
 | header entry of a PO file | 5.2 Filling in the Header Entry
 | help option | 3.2 Preparing Translatable Strings
 | history of GNU gettext | 14.1 History of GNU gettext
I |  |
 | i18n | 1.2 I18n, L10n, and Such
 | importing PO files | 2.5 Normalizing Strings in Entries
 | include file `libintl.h' | 1.5 Overview of GNU gettext
 | include file `libintl.h' | 3. Preparing Program Sources
 | include file `libintl.h' | 10.3 Comparing the Two Interfaces
 | include file `libintl.h' | 12.4.10 `gettext.h' in `lib/'
 | initialization | 3.1 Triggering gettext Operations
 | initialize new PO file | 5.1 Invoking the msginit Program
 | initialize translations from a compendium | 6.11.2.1 Initialize a New Translation File
 | installing gettext | 2.1 Completing GNU gettext Installation
 | interface to catgets | 10.1.1 The Interface
 | internationalization | 1.2 I18n, L10n, and Such
 | inttypes.h | 3.2 Preparing Translatable Strings
 | ISO 3166 | B. Country Codes
 | ISO 639 | A. Language Codes
J |  |
 | Java | 13.5.10 Java
 | Java mode, and msgfmt program | 8.1.2 Operation mode
 | Java mode, and msgunfmt program | 8.2.1 Operation mode
 | Java, string concatenation | 3.2 Preparing Translatable Strings
K |  |
 | keyboard accelerator checking | 8.1.6 Input file interpretation
L |  |
 | l10n | 1.2 I18n, L10n, and Such
 | language codes | A. Language Codes
 | language selection | 9.3 Magic for End Users
 | language selection at runtime | 10.5 Being a gettext grok
 | large package | 10.2.2 Solving Ambiguities
 | libiconv library | 12.5.2 AM_ICONV in `iconv.m4'
 | libintl for Java | 13.5.10 Java
 | libintl library | 12.5.1 AM_GNU_GETTEXT in `gettext.m4'
 | librep Lisp | 13.5.8 librep
 | `LINGUAS' file | 12.4.2 `LINGUAS' in `po/'
 | link with `libintl' | 1.5 Overview of GNU gettext
 | Linux | 1.3 Aspects in Native Language Support
 | Linux | 1.5 Overview of GNU gettext
 | Linux | 5.2 Filling in the Header Entry
 | Lisp | 13.5.5 GNU clisp - Common Lisp
 | list of translation teams, where to find | 5.2 Filling in the Header Entry
 | locale facet, LC_ALL | 3.1 Triggering gettext Operations
 | locale facet, LC_COLLATE | 3.1 Triggering gettext Operations
 | locale facet, LC_CTYPE | 1.3 Aspects in Native Language Support
 | locale facet, LC_CTYPE | 3.1 Triggering gettext Operations
 | locale facet, LC_CTYPE | 3.1 Triggering gettext Operations
 | locale facet, LC_MESSAGES | 1.3 Aspects in Native Language Support
 | locale facet, LC_MESSAGES | 3.1 Triggering gettext Operations
 | locale facet, LC_MONETARY | 1.3 Aspects in Native Language Support
 | locale facet, LC_MONETARY | 3.1 Triggering gettext Operations
 | locale facet, LC_NUMERIC | 1.3 Aspects in Native Language Support
 | locale facet, LC_NUMERIC | 3.1 Triggering gettext Operations
 | locale facet, LC_RESPONSES | 3.1 Triggering gettext Operations
 | locale facet, LC_TIME | 1.3 Aspects in Native Language Support
 | locale facet, LC_TIME | 3.1 Triggering gettext Operations
 | locale facets | 1.3 Aspects in Native Language Support
 | locale program | 5.2 Filling in the Header Entry
 | localization | 1.2 I18n, L10n, and Such
M |  |
 | magic signature of MO files | 8.3 The Format of GNU MO Files
 | `Makevars' file | 12.4.3 `Makefile' pieces in `po/'
 | manipulating PO files | 7. Manipulating PO Files
 | marking string initializers | 3.6 Special Cases of Translatable Strings
 | marking strings that require translation | 3.3 How Marks Appear in Sources
 | marking strings, preparations | 3.2 Preparing Translatable Strings
 | marking translatable strings | 1.5 Overview of GNU gettext
 | menu entries | 10.2.6 How to use gettext in GUI programs
 | menu, keyboard accelerator support | 8.1.6 Input file interpretation
 | merge PO files | 7.1 Invoking the msgcat Program
 | merging two PO files | 7. Manipulating PO Files
 | message catalog files location | 10.2.3 Locating Message Catalog Files
 | messages | 1.3 Aspects in Native Language Support
 | migration from earlier versions of gettext | 12.2 Prerequisite Works
 | mnemonics of menu entries | 8.1.6 Input file interpretation
 | MO file's format | 8.3 The Format of GNU MO Files
 | modify message attrributes | 7.8.4 Attribute manipulation
 | msgattrib program, usage | 7.8 Invoking the msgattrib Program
 | msgcat program, usage | 7.1 Invoking the msgcat Program
 | msgcmp program, usage | 7.7 Invoking the msgcmp Program
 | msgcomm program, usage | 7.6 Invoking the msgcomm Program
 | msgconv program, usage | 7.2 Invoking the msgconv Program
 | msgen program, usage | 7.9 Invoking the msgen Program
 | msgexec program, usage | 7.10 Invoking the msgexec Program
 | msgfilter filter and catalog encoding | 7.4.3 The filter
 | msgfilter program, usage | 7.4 Invoking the msgfilter Program
 | msgfmt program, usage | 8.1 Invoking the msgfmt Program
 | msggrep program, usage | 7.3 Invoking the msggrep Program
 | msgid | 2.2 The Format of PO Files
 | msgid_plural | 2.2 The Format of PO Files
 | msginit program, usage | 5.1 Invoking the msginit Program
 | msgmerge program, usage | 6.1 Invoking the msgmerge Program
 | msgstr | 2.2 The Format of PO Files
 | msgunfmt program, usage | 8.2 Invoking the msgunfmt Program
 | msguniq program, usage | 7.5 Invoking the msguniq Program
 | multi-line strings | 2.5 Normalizing Strings in Entries
N |  |
 | N_, a convenience macro | 10.3 Comparing the Two Interfaces
 | Native Language Support | 1.2 I18n, L10n, and Such
 | Natural Language Support | 1.2 I18n, L10n, and Such
 | newlines in PO files | 2.2 The Format of PO Files
 | ngettext | 10.2.5 Additional functions for plural forms
 | NLS | 1.2 I18n, L10n, and Such
 | no-c-format flag | 2.2 The Format of PO Files
 | no-c-format, and xgettext | 3.5 Special Comments preceding Keywords
 | nplurals, in a PO file header | 10.2.5 Additional functions for plural forms
 | number format | 1.3 Aspects in Native Language Support
O |  |
 | Object Pascal | 13.5.12 Pascal - Free Pascal Compiler
 | obsolete entries | 6.5 Obsolete Entries
 | optimization of gettext functions | 10.2.7 Optimization of the *gettext functions
 | orthography | 7. Manipulating PO Files
 | output to stdout, xgettext | 4.1.2 Output file location
 | overview of gettext | 1.5 Overview of GNU gettext
P |  |
 | package and version declaration in `configure.in' | 12.4.4 `configure.in' at top level
 | package build and installation options | 9.2 Magic for Installers
 | package maintainer's view of gettext | 12. The Maintainer's View
 | paragraphs | 3.2 Preparing Translatable Strings
 | Pascal | 13.5.12 Pascal - Free Pascal Compiler
 | Perl | 13.5.16 Perl
 | PHP | 13.5.17 PHP Hypertext Preprocessor
 | Pike | 13.5.18 Pike
 | plural form formulas | 10.2.5 Additional functions for plural forms
 | plural forms | 10.2.5 Additional functions for plural forms
 | plural forms, in MO files | 8.3 The Format of GNU MO Files
 | plural, in a PO file header | 10.2.5 Additional functions for plural forms
 | PO files' format | 2.2 The Format of PO Files
 | PO mode (Emacs) commands | 2.3 Main PO mode Commands
 | PO template file | 4. Making the PO Template File
 | portability problems with sed | 7.4.3 The filter
 | `POTFILES.in' file | 12.4.1 `POTFILES.in' in `po/'
 | preparing programs for translation | 3. Preparing Program Sources
 | problems with catgets interface | 10.1.2 Problems with the catgets Interface?!
 | programming languages | 13.1 The Language Implementor's View
 | Python | 13.5.4 Python
Q |  |
 | quotation marks | 5.2 Filling in the Header Entry
 | quotation marks | 12.4.3 `Makefile' pieces in `po/'
 | quote characters, use in PO files | 5.2 Filling in the Header Entry
R |  |
 | related reading | 14.2 Related Readings
 | RST | 13.6.2 Resource String Table
S |  |
 | scripting languages | 13.1 The Language Implementor's View
 | search messages in a catalog | 7.3 Invoking the msggrep Program
 | selecting message language | 9.3 Magic for End Users
 | sentences | 3.2 Preparing Translatable Strings
 | setting up gettext at build time | 9.2 Magic for Installers
 | setting up gettext at run time | 9.3 Magic for End Users
 | several domains | 10.2.2 Solving Ambiguities
 | sex | 1. Introduction
 | sgettext | 10.2.6 How to use gettext in GUI programs
 | she, he, and they | 1. Introduction
 | shell scripts | 13.5.2 sh - Shell Script
 | Smalltalk | 13.5.9 GNU Smalltalk
 | sorting msgcat output | 7.1.4 Output details
 | sorting msgmerge output | 6.1.6 Output details
 | sorting msgunfmt output | 8.2.6 Output details
 | sorting output of xgettext | 4.1.6 Output details
 | specifying plural form in a PO file | 10.2.5 Additional functions for plural forms
 | standard output, and msgcat | 7.1.2 Output file location
 | standard output, and msgmerge program | 6.1.3 Output file location
 | string concatenation | 3.2 Preparing Translatable Strings
 | string normalization in entries | 2.5 Normalizing Strings in Entries
 | style | 3.2 Preparing Translatable Strings
 | supported languages, xgettext | 4.1.3 Choice of input file language
T |  |
 | Tcl | 13.5.15 Tcl - Tk's scripting language
 | Tcl mode, and msgfmt program | 8.1.2 Operation mode
 | Tcl mode, and msgunfmt program | 8.2.1 Operation mode
 | template PO file | 1.5 Overview of GNU gettext
 | testing `.po' files for equivalence | 4.1.6 Output details
 | Tk's scripting language | 13.5.15 Tcl - Tk's scripting language
 | translated entries | 6.2 Translated Entries
 | translating menu entries | 10.2.6 How to use gettext in GUI programs
 | translation aspects | 1.3 Aspects in Native Language Support
 | Translation Matrix | 9.1 The Current `ABOUT-NLS' Matrix
 | Translation Project | 1.1 The Purpose of GNU gettext
 | turning off NLS support | 12.4.10 `gettext.h' in `lib/'
 | tutorial of gettext usage | 1.5 Overview of GNU gettext
U |  |
 | unify duplicate translations | 7.5 Invoking the msguniq Program
 | untranslated entries | 6.4 Untranslated Entries
 | update translations from a compendium | 6.11.2.2 Update an Existing Translation File
 | upgrading to new versions of gettext | 12.2 Prerequisite Works
V |  |
 | version control for backup files, msgmerge | 6.1.4 Output file location in update mode
W |  |
 | wxWindows library | 13.5.13 wxWindows library
X |  |
 | xargs, and output from msgexec | 7.10 Invoking the msgexec Program
 | xgettext program, usage | 4.1 Invoking the xgettext Program
 | xmodmap program, and typing quotation marks | 5.2 Filling in the Header Entry
Y |  |
 | YaST2 scripting language | 13.5.14 YCP - YaST2 scripting language
 | YCP | 13.5.14 YCP - YaST2 scripting language

Jump to: _
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

[Top] [Contents] [Index] [ ? ]

Footnotes

(1)

In this manual, all mentions of Emacs refers to either GNU Emacs or to XEmacs, which people sometimes call FSF Emacs and Lucid Emacs, respectively.

(2)

This limitation is not imposed by GNU gettext, but is for compatibility with the msgfmt implementation on Solaris.

(3)

Some system, eg Ultrix, don't have LC_MESSAGES. Here we use a more or less arbitrary value for it, namely 1729, the smallest positive integer which can be represented in two different ways as the sum of two cubes.

(4)

When the system does not support setlocale its behavior in setting the locale values is simulated by looking at the environment variables.

(5)

Additions are welcome. Send appropriate information to bug-glibc-manual@gnu.org.

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Introduction
      1.1 The Purpose of GNU gettext
      1.2 I18n, L10n, and Such
      1.3 Aspects in Native Language Support
      1.4 Files Conveying Translations
      1.5 Overview of GNU gettext
    2. PO Files and PO Mode Basics
      2.1 Completing GNU gettext Installation
      2.2 The Format of PO Files
      2.3 Main PO mode Commands
      2.4 Entry Positioning
      2.5 Normalizing Strings in Entries
    3. Preparing Program Sources
      3.1 Triggering gettext Operations
      3.2 Preparing Translatable Strings
      3.3 How Marks Appear in Sources
      3.4 Marking Translatable Strings
      3.5 Special Comments preceding Keywords
      3.6 Special Cases of Translatable Strings
    4. Making the PO Template File
      4.1 Invoking the xgettext Program
        4.1.1 Input file location
        4.1.2 Output file location
        4.1.3 Choice of input file language
        4.1.4 Operation mode
        4.1.5 Language=C/C++ specific options
        4.1.6 Output details
        4.1.7 Informative output
    5. Creating a New PO File
      5.1 Invoking the msginit Program
        5.1.1 Input file location
        5.1.2 Output file location
        5.1.3 Output details
        5.1.4 Informative output
      5.2 Filling in the Header Entry
    6. Updating Existing PO Files
      6.1 Invoking the msgmerge Program
        6.1.1 Input file location
        6.1.2 Operation mode
        6.1.3 Output file location
        6.1.4 Output file location in update mode
        6.1.5 Operation modifiers
        6.1.6 Output details
        6.1.7 Informative output
      6.2 Translated Entries
      6.3 Fuzzy Entries
      6.4 Untranslated Entries
      6.5 Obsolete Entries
      6.6 Modifying Translations
      6.7 Modifying Comments
      6.8 Details of Sub Edition
      6.9 C Sources Context
      6.10 Consulting Auxiliary PO Files
      6.11 Using Translation Compendia
        6.11.1 Creating Compendia
          6.11.1.1 Concatenate PO Files
          6.11.1.2 Extract a Message Subset from a PO File
        6.11.2 Using Compendia
          6.11.2.1 Initialize a New Translation File
          6.11.2.2 Update an Existing Translation File
    7. Manipulating PO Files
      7.1 Invoking the msgcat Program
        7.1.1 Input file location
        7.1.2 Output file location
        7.1.3 Message selection
        7.1.4 Output details
        7.1.5 Informative output
      7.2 Invoking the msgconv Program
        7.2.1 Input file location
        7.2.2 Output file location
        7.2.3 Conversion target
        7.2.4 Output details
        7.2.5 Informative output
      7.3 Invoking the msggrep Program
        7.3.1 Input file location
        7.3.2 Output file location
        7.3.3 Message selection
        7.3.4 Output details
        7.3.5 Informative output
      7.4 Invoking the msgfilter Program
        7.4.1 Input file location
        7.4.2 Output file location
        7.4.3 The filter
        7.4.4 Useful filter-options when the filter is `sed'
        7.4.5 Output details
        7.4.6 Informative output
      7.5 Invoking the msguniq Program
        7.5.1 Input file location
        7.5.2 Output file location
        7.5.3 Message selection
        7.5.4 Output details
        7.5.5 Informative output
      7.6 Invoking the msgcomm Program
        7.6.1 Input file location
        7.6.2 Output file location
        7.6.3 Message selection
        7.6.4 Output details
        7.6.5 Informative output
      7.7 Invoking the msgcmp Program
        7.7.1 Input file location
        7.7.2 Operation modifiers
        7.7.3 Informative output
      7.8 Invoking the msgattrib Program
        7.8.1 Input file location
        7.8.2 Output file location
        7.8.3 Message selection
        7.8.4 Attribute manipulation
        7.8.5 Output details
        7.8.6 Informative output
      7.9 Invoking the msgen Program
        7.9.1 Input file location
        7.9.2 Output file location
        7.9.3 Output details
        7.9.4 Informative output
      7.10 Invoking the msgexec Program
        7.10.1 Input file location
        7.10.2 Informative output
    8. Producing Binary MO Files
      8.1 Invoking the msgfmt Program
        8.1.1 Input file location
        8.1.2 Operation mode
        8.1.3 Output file location
        8.1.4 Output file location in Java mode
        8.1.5 Output file location in Tcl mode
        8.1.6 Input file interpretation
        8.1.7 Output details
        8.1.8 Informative output
      8.2 Invoking the msgunfmt Program
        8.2.1 Operation mode
        8.2.2 Input file location
        8.2.3 Input file location in Java mode
        8.2.4 Input file location in Tcl mode
        8.2.5 Output file location
        8.2.6 Output details
        8.2.7 Informative output
      8.3 The Format of GNU MO Files
    9. The User's View
      9.1 The Current `ABOUT-NLS' Matrix
      9.2 Magic for Installers
      9.3 Magic for End Users
    10. The Programmer's View
      10.1 About catgets
        10.1.1 The Interface
        10.1.2 Problems with the catgets Interface?!
      10.2 About gettext
        10.2.1 The Interface
        10.2.2 Solving Ambiguities
        10.2.3 Locating Message Catalog Files
        10.2.4 How to specify the output character set gettext uses
        10.2.5 Additional functions for plural forms
        10.2.6 How to use gettext in GUI programs
        10.2.7 Optimization of the *gettext functions
      10.3 Comparing the Two Interfaces
      10.4 Using libintl.a in own programs
      10.5 Being a gettext grok
      10.6 Temporary Notes for the Programmers Chapter
        10.6.1 Temporary - Two Possible Implementations
        10.6.2 Temporary - About catgets
        10.6.3 Temporary - Why a single implementation
        10.6.4 Temporary - Notes
    11. The Translator's View
      11.1 Introduction 0
      11.2 Introduction 1
      11.3 Discussions
      11.4 Organization
        11.4.1 Central Coordination
        11.4.2 National Teams
          11.4.2.1 Sub-Cultures
          11.4.2.2 Organizational Ideas
        11.4.3 Mailing Lists
      11.5 Information Flow
    12. The Maintainer's View
      12.1 Flat or Non-Flat Directory Structures
      12.2 Prerequisite Works
      12.3 Invoking the gettextize Program
      12.4 Files You Must Create or Alter
        12.4.1 `POTFILES.in' in `po/'
        12.4.2 `LINGUAS' in `po/'
        12.4.3 `Makefile' pieces in `po/'
        12.4.4 `configure.in' at top level
        12.4.5 `config.guess', `config.sub' at top level
        12.4.6 `aclocal.m4' at top level
        12.4.7 `acconfig.h' at top level
        12.4.8 `Makefile.in' at top level
        12.4.9 `Makefile.in' in `src/'
        12.4.10 `gettext.h' in `lib/'
      12.5 Autoconf macros for use in `configure.in'
        12.5.1 AM_GNU_GETTEXT in `gettext.m4'
        12.5.2 AM_ICONV in `iconv.m4'
    13. Other Programming Languages
      13.1 The Language Implementor's View
      13.2 The Programmer's View
      13.3 The Translator's View
      13.4 The Maintainer's View
      13.5 Individual Programming Languages
        13.5.1 C, C++, Objective C
        13.5.2 sh - Shell Script
        13.5.3 bash - Bourne-Again Shell Script
        13.5.4 Python
        13.5.5 GNU clisp - Common Lisp
        13.5.6 GNU clisp C sources
        13.5.7 Emacs Lisp
        13.5.8 librep
        13.5.9 GNU Smalltalk
        13.5.10 Java
        13.5.11 GNU awk
        13.5.12 Pascal - Free Pascal Compiler
        13.5.13 wxWindows library
        13.5.14 YCP - YaST2 scripting language
        13.5.15 Tcl - Tk's scripting language
        13.5.16 Perl
        13.5.17 PHP Hypertext Preprocessor
        13.5.18 Pike
      13.6 Internationalizable Data
        13.6.1 POT - Portable Object Template
        13.6.2 Resource String Table
        13.6.3 Glade - GNOME user interface description
    14. Concluding Remarks
      14.1 History of GNU gettext
      14.2 Related Readings
    A. Language Codes
    B. Country Codes
    Program Index
    Option Index
    Variable Index
    PO Mode Index
    Autoconf Macro Index
    General Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Introduction
2. PO Files and PO Mode Basics
3. Preparing Program Sources
4. Making the PO Template File
5. Creating a New PO File
6. Updating Existing PO Files
7. Manipulating PO Files
8. Producing Binary MO Files
9. The User's View
10. The Programmer's View
11. The Translator's View
12. The Maintainer's View
13. Other Programming Languages
14. Concluding Remarks
A. Language Codes
B. Country Codes
Program Index
Option Index
Variable Index
PO Mode Index
Autoconf Macro Index
General Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on May 6, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on May 6, 2002 using texi2html


GNU MP 4.0.1

This manual describes how to install and use the GNU multiple precision arithmetic library, version 4.0.1.

Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "A GNU Manual", and with the Back-Cover Texts being "You have freedom to copy and modify this GNU Manual, like GNU software". A copy of the license is included in C. GNU Free Documentation License.

GNU MP Copying Conditions | GMP Copying Conditions (LGPL).
1. Introduction to GNU MP | Brief introduction to GNU MP.
2. Installing GMP | How to configure and compile the GMP library.
3. GMP Basics | What every GMP user should know.
4. Reporting Bugs | How to usefully report bugs.
5. Integer Functions | Functions for arithmetic on signed integers.
6. Rational Number Functions | Functions for arithmetic on rational numbers.
7. Floating-point Functions | Functions for arithmetic on floats.
8. Low-level Functions | Fast functions for natural numbers.
9. Random Number Functions | Functions for generating random numbers.
10. Formatted Output | printf style output.
11. Formatted Input | scanf style input.
12. C++ Class Interface | Class wrappers around GMP types.
13. Berkeley MP Compatible Functions | All functions found in BSD MP.
14. Custom Allocation | How to customize the internal allocation.
15. Language Bindings | Using GMP from other languages.
16. Algorithms | What happens behind the scenes.
17. Internals | How values are represented behind the scenes.

A. Contributors | Who brings your this library?
B. References | Some useful papers and books to read.
C. GNU Free Documentation License
Concept Index
Function and Type Index

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

GNU MP Copying Conditions

This library is free; this means that everyone is free to use it and free to redistribute it on a free basis. The library is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of this library that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of the library, that you receive source code or else can get it if you want it, that you can change this library or use pieces of it in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the GNU MP library, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the GNU MP library. If it is modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.

The precise conditions of the license for the GNU MP library are found in the Lesser General Public License version 2.1 that accompanies the source code, see `COPYING.LIB'. Certain demonstration programs are provided under the terms of the plain General Public License version 2, see `COPYING'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Introduction to GNU MP

GNU MP is a portable library written in C for arbitrary precision arithmetic on integers, rational numbers, and floating-point numbers. It aims to provide the fastest possible arithmetic for all applications that need higher precision than is directly supported by the basic C types.

Many applications use just a few hundred bits of precision; but some applications may need thousands or even millions of bits. GMP is designed to give good performance for both, by choosing algorithms based on the sizes of the operands, and by carefully keeping the overhead at a minimum.

The speed of GMP is achieved by using fullwords as the basic arithmetic type, by using sophisticated algorithms, by including carefully optimized assembly code for the most common inner loops for many different CPUs, and by a general emphasis on speed (as opposed to simplicity or elegance).

There is carefully optimized assembly code for these CPUs: ARM, DEC Alpha 21064, 21164, and 21264, AMD 29000, AMD K6, K6-2 and Athlon, Hitachi SuperH and SH-2, HPPA 1.0, 1.1 and 2.0, Intel Pentium, Pentium Pro/II/III, Pentium 4, generic x86, Intel IA-64, i960, Motorola MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC 32 and 64, National NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC, generic SPARCv8, UltraSPARC, DEC VAX, and Zilog Z8000. Some optimizations also for Cray vector systems, Clipper, IBM ROMP (RT), and Pyramid AP/XP.

There is a mailing list for GMP users. To join it, send a mail to gmp-request@swox.com with the word `subscribe' in the message body (not in the subject line).

For up-to-date information on GMP, please see the GMP web pages at

http://swox.com/gmp/

The latest version of the library is available at

ftp://ftp.gnu.org/gnu/gmp

Many sites around the world mirror `ftp.gnu.org', please use a mirror near you, see http://www.gnu.org/order/ftp.html for a full list.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1.1 How to use this Manual

Everyone should read 3. GMP Basics. If you need to install the library yourself, then read 2. Installing GMP. If you have a system with multiple ABIs, then read 2.2 ABI and ISA, for the compiler options that must be used on applications.

The rest of the manual can be used for later reference, although it is probably a good idea to glance through it.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. Installing GMP

GMP has an autoconf/automake/libtool based configuration system. On a Unix-like system a basic build can be done with

./configure
make

Some self-tests can be run with

make check

And you can install (under `/usr/local' by default) with

make install

If you experience problems, please report them to bug-gmp@gnu.org. See 4. Reporting Bugs, for information on what to include in useful bug reports.

2.1 Build Options
2.2 ABI and ISA
2.3 Notes for Package Builds
2.4 Notes for Particular Systems
2.5 Known Build Problems

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 Build Options

All the usual autoconf configure options are available, run `./configure --help' for a summary. The file `INSTALL.autoconf' has some generic installation information too.

Non-Unix Systems

`configure' requires various Unix-like tools. On an MS-DOS system Cygwin, DJGPP or MINGW can be used. See

http://www.cygnus.com/cygwin
http://www.delorie.com/djgpp
http://www.mingw.org

The `macos' directory contains an unsupported port to MacOS 9 on Power Macintosh. Note that MacOS X "Darwin" can use the normal `./configure'.

It might be possible to build without the help of `configure', certainly all the code is there, but unfortunately you'll be on your own.

Build Directory

To compile in a separate build directory, cd to that directory, and prefix the configure command with the path to the GMP source directory. For example

cd /my/build/dir
/my/sources/gmp-4.0.1/configure

Not all `make' programs have the necessary features (VPATH) to support this. In particular, SunOS and Slowaris make have bugs that make them unable to build in a separate directory. Use GNU make instead.

`--disable-shared', `--disable-static'

By default both shared and static libraries are built (where possible), but one or other can be disabled. Shared libraries result in smaller executables and permit code sharing between separate running processes, but on some CPUs are slightly slower, having a small cost on each function call.

Native Compilation, `--build=CPU-VENDOR-OS'

For normal native compilation, the system can be specified with `--build'. By default `./configure' uses the output from running `./config.guess'. On some systems `./config.guess' can determine the exact CPU type, on others it will be necessary to give it explicitly. For example,

./configure --build=ultrasparc-sun-solaris2.7

In all cases the `OS' part is important, since it controls how libtool generates shared libraries. Running `./config.guess' is the simplest way to see what it should be, if you don't know already.

Cross Compilation, `--host=CPU-VENDOR-OS'

When cross-compiling, the system used for compiling is given by `--build' and the system where the library will run is given by `--host'. For example when using a FreeBSD Athlon system to build GNU/Linux m68k binaries,

./configure --build=athlon-pc-freebsd3.5 --host=m68k-mac-linux-gnu

Compiler tools are sought first with the host system type as a prefix. For example m68k-mac-linux-gnu-ranlib is checked for, then plain ranlib. This makes it possible for a set of cross-compiling tools to co-exist with native tools. The prefix is the argument to `--host', and this can be an alias, such as `m68k-linux'. But note that tools don't have to be setup this way, it's enough to just have a PATH with a suitable cross-compiling cc etc.

Compiling for a different CPU in the same family as the build system is a form of cross-compilation, though very possibly this would merely be with special options on a native compiler. In any case `./configure' avoids depending on being able to run code on the build system, which is important when creating binaries for a newer CPU since they very possibly won't run on the build system.

Currently a warning is given unless an explicit `--build' is used when cross-compiling, because it may not be possible to correctly guess the build system type if the PATH has only a cross-compiling cc.

Note that the `--target' option is not appropriate for GMP. It's for use when building compiler tools, with `--host' being where they will run, and `--target' what they'll produce code for. Ordinary programs or libraries like GMP are only interested in the `--host' part, being where they'll run. (Some past versions of GMP used `--target' incorrectly.)

CPU types

In general, if you want a library that runs as fast as possible, you should configure GMP for the exact CPU type your system uses. However, this may mean the binaries won't run on older members of the family, and might run slower on other members, older or newer. The best idea is always to build GMP for the exact machine type you intend to run it on.

The following CPUs have specific support. See `configure.in' for details of what code and compiler options they select.

  • Alpha: `alpha', `alphaev5', `alphaev56', `alphapca56', `alphaev6', `alphaev67'

  • Cray: `c90', `j90', `t90', `sv1'

  • HPPA: `hppa1.0', `hppa1.1', `hppa2.0', `hppa2.0n', `hppa2.0w'

  • MIPS: `mips', `mips3', `mips64'

  • Motorola: `m68k', `m68000', `m68010', `m68020', `m68030', `m68040', `m68060', `m68302', `m68360', `m88k', `m88110'

  • POWER: `power', `power1', `power2', `power2sc', `powerpc', `powerpc64'

  • SPARC: `sparc', `sparcv8', `microsparc', `supersparc', `sparcv9', `ultrasparc', `sparc64'

  • 80x86 family: `i386', `i486', `i586', `pentium', `pentiummmx', `pentiumpro', `pentium2', `pentium3', `pentium4', `k6', `k62', `k63', `athlon'

  • Other: `a29k', `arm', `clipper', `i960', `ns32k', `pyramid', `sh', `sh2', `vax', `z8k'

CPUs not listed will use generic C code.

Generic C Build

If some of the assembly code causes problems, or if otherwise desired, the generic C code can be selected with CPU `none'. For example,

./configure --build=none-unknown-freebsd3.5

Note that this will run quite slowly, but it should be portable and should at least make it possible to get something running if all else fails.

`ABI'

On some systems GMP supports multiple ABIs (application binary interfaces), meaning data type sizes and calling conventions. By default GMP chooses the best ABI available, but a particular ABI can be selected. For example

./configure --build=mips64-sgi-irix6 ABI=n32

See 2.2 ABI and ISA, for the available choices on relevant CPUs, and what applications need to do.

`CC', `CFLAGS'

By default the C compiler used is chosen from among some likely candidates, with gcc normally preferred if it's present. The usual `CC=whatever' can be passed to `./configure' to choose something different.

For some systems, default compiler flags are set based on the CPU and compiler. The usual `CFLAGS="-whatever"' can be passed to `./configure' to use something different or to set good flags for systems GMP doesn't otherwise know.

The `CC' and `CFLAGS' used are printed during `./configure', and can be found in each generated `Makefile'. This is the easiest way to check the defaults when considering changing or adding something.

Note that when `CC' and `CFLAGS' are specified on a system supporting multiple ABIs it's important to give an explicit `ABI=whatever', since GMP can't determine the ABI just from the flags and won't be able to select the correct assembler code.

If just `CC' is selected then normal default `CFLAGS' for that compiler will be used (if GMP recognises it). For example `CC=gcc' can be used to force the use of GCC, with default flags (and default ABI).

`CPPFLAGS'

Any flags like `-D' defines or `-I' includes required by the preprocessor should be set in `CPPFLAGS' rather than `CFLAGS'. Compiling is done with both `CPPFLAGS' and `CFLAGS', but preprocessing uses just `CPPFLAGS'. This distinction is because most preprocessors won't accept all the flags the compiler does. Preprocessing is done separately in some configure tests, and in the `ansi2knr' support for K&R compilers.

C++ Support, `--enable-cxx'
C++ support in GMP can be enabled with `--enable-cxx', in which case a C++ compiler will be required. As a convenience `--enable-cxx=detect' can be used to enable C++ support only if a compiler can be found. The C++ support consists of a library `libgmpxx.la' and header file `gmpxx.h'.

A separate `libgmpxx.la' has been adopted rather than having C++ objects within `libgmp.la' in order to ensure dynamic linked C programs aren't bloated by a dependency on the C++ standard library, and to avoid any chance that the C++ compiler could be required when linking plain C programs.

`libgmpxx.la' will use certain internals from `libgmp.la' and can only be expected to work with `libgmp.la' from the same GMP version. Future changes to the relevant internals will be accompanied by renaming, so a mismatch will cause unresolved symbols rather than perhaps mysterious misbehaviour.

In general `libgmpxx.la' will be usable only with the C++ compiler that built it, since name mangling and runtime support are usually incompatible between different compilers.

`CXX', `CXXFLAGS'
When C++ support is enabled, the C++ compiler and its flags can be set with variables `CXX' and `CXXFLAGS' in the usual way. The default for `CXX' is the first compiler that works from a list of likely candidates, with g++ normally preferred when available. The default for `CXXFLAGS' is to try `CFLAGS', `CFLAGS' without `-g', then for g++ either `-g -O2' or `-O2', or for other compilers `-g' or nothing. Trying `CFLAGS' this way is convenient when using `gcc' and `g++' together, since the flags for `gcc' will usually suit `g++'.

It's important that the C and C++ compilers match, meaning their startup and runtime support routines are compatible and that they generate code in the same ABI (if there's a choice of ABIs on the system). `./configure' isn't currently able to check these things very well itself, so for that reason `--disable-cxx' is the default, to avoid a build failure due to a compiler mismatch. Perhaps this will change in the future.

Incidentally, it's normally not good enough to set `CXX' to the same as `CC'. Although gcc for instance recognises `foo.cc' as C++ code, only g++ will invoke the linker the right way when building an executable or shared library from object files.

Temporary Memory, `--enable-alloca=<choice>'

GMP allocates temporary workspace using one of the following three methods, which can be selected with for instance `--enable-alloca=malloc-reentrant'.

  • `alloca' - C library or compiler builtin.
  • `malloc-reentrant' - the heap, in a re-entrant fashion.
  • `malloc-notreentrant' - the heap, with global variables.

For convenience, the following choices are also available. `--disable-alloca' is the same as `--enable-alloca=no'.

  • `yes' - a synonym for `alloca'.
  • `no' - a synonym for `malloc-reentrant'.
  • `reentrant' - alloca if available, otherwise `malloc-reentrant'. This is the default.
  • `notreentrant' - alloca if available, otherwise `malloc-notreentrant'.

alloca is reentrant and fast, and is recommended, but when working with large numbers it can overflow the available stack space, in which case one of the two malloc methods will need to be used. Alternately it might be possible to increase available stack with limit, ulimit or setrlimit, or under DJGPP with stubedit or _stklen. Note that depending on the system the only indication of stack overflow might be a segmentation violation.

`malloc-reentrant' is, as the name suggests, reentrant and thread safe, but `malloc-notreentrant' is faster and should be used if reentrancy is not required.

The two malloc methods in fact use the memory allocation functions selected by mp_set_memory_functions, these being malloc and friends by default. See section 14. Custom Allocation.

An additional choice `--enable-alloca=debug' is available, to help when debugging memory related problems (see section 3.10 Debugging).

FFT Multiplication, `--disable-fft'

By default multiplications are done using Karatsuba, 3-way Toom-Cook, and Fermat FFT. The FFT is only used on large to very large operands and can be disabled to save code size if desired.

Berkeley MP, `--enable-mpbsd'

The Berkeley MP compatibility library (`libmp') and header file (`mp.h') are built and installed only if `--enable-mpbsd' is used. See section 13. Berkeley MP Compatible Functions.

MPFR, `--enable-mpfr'

The optional MPFR functions are built and installed only if `--enable-mpfr' is used. These are in a separate library `libmpfr.a' and are documented separately too (see section `Introduction to MPFR' in MPFR).

Assertion Checking, `--enable-assert'

This option enables some consistency checking within the library. This can be of use while debugging, see section 3.10 Debugging.

Execution Profiling, `--enable-profiling=prof/gprof'

Profiling support can be enabled either for prof or gprof. This adds `-p' or `-pg' respectively to `CFLAGS', and for some systems adds corresponding mcount calls to the assembler code. See section 3.11 Profiling.

`MPN_PATH'

Various assembler versions of mpn subroutines are provided, and, for a given CPU, a search is made though a path to choose a version of each. For example `sparcv8' has path `sparc32/v8 sparc32 generic', which means it looks first for v8 code, then plain sparc32, and finally falls back on generic C. Knowledgeable users with special requirements can specify a path with `MPN_PATH="dir list"'. This will normally be unnecessary because all sensible paths should be available under one or other CPU.

Demonstration Programs

The `demos' subdirectory has some sample programs using GMP. These aren't built or installed, but there's a `Makefile' with rules for them. For instance,

make pexpr
./pexpr 68^975+10

Documentation

The document you're now reading is `gmp.texi'. The usual automake targets are available to make PostScript `gmp.ps' and/or DVI `gmp.dvi'.

HTML can be produced with `makeinfo --html', see section `Generating HTML' in Texinfo. Or alternately `texi2html', see section `About' in Texinfo To HTML.

PDF can be produced with `texi2dvi --pdf' (see section `PDF Output' in Texinfo) or with `pdftex'.

Some supplementary notes can be found in the `doc' subdirectory.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 ABI and ISA

ABI (Application Binary Interface) refers to the calling conventions between functions, meaning what registers are used and what sizes the various C data types are. ISA (Instruction Set Architecture) refers to the instructions and registers a CPU has available.

Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI defined, the latter for compatibility with older CPUs in the family. GMP supports some CPUs like this in both ABIs. In fact within GMP `ABI' means a combination of chip ABI, plus how GMP chooses to use it. For example in some 32-bit ABIs, GMP may support a limb as either a 32-bit long or a 64-bit long long.

By default GMP chooses the best ABI available for a given system, and this generally gives significantly greater speed. But an ABI can be chosen explicitly to make GMP compatible with other libraries, or particular application requirements. For example,

./configure ABI=32

In all cases it's vital that all object code used in a given program is compiled for the same ABI.

Usually a limb is implemented as a long. When a long long limb is used this is encoded in the generated `gmp.h'. This is convenient for applications, but it does mean that `gmp.h' will vary, and can't be just copied around. `gmp.h' remains compiler independent though, since all compilers for a particular ABI will be expected to use the same limb type.

Currently no attempt is made to follow whatever conventions a system has for installing library or header files built for a particular ABI. This will probably only matter when installing multiple builds of GMP, and it might be as simple as configuring with a special `libdir', or it might require more than that. Note that builds for different ABIs need to done separately, with a fresh ./configure and make each.

HPPA 2.0 (`hppa2.0*')

`ABI=2.0w'

The 2.0w ABI uses 64-bit limbs and pointers and is available on HP-UX 11 or up when using cc. gcc support for this is in progress. Applications must be compiled with

cc  +DD64

`ABI=2.0n'

The 2.0n ABI means the 32-bit HPPA 1.0 ABI but with a 64-bit limb using long long. This is available on HP-UX 10 or up when using cc. No gcc support is planned for this. Applications must be compiled with

cc  +DA2.0 +e

`ABI=1.0'

HPPA 2.0 CPUs can run all HPPA 1.0 and 1.1 code in the 32-bit HPPA 1.0 ABI. No special compiler options are needed for applications.

All three ABIs are available for CPUs `hppa2.0w' and `hppa2.0', but for CPU `hppa2.0n' only 2.0n or 1.0 are allowed.

MIPS under IRIX 6 (`mips*-*-irix[6789]')

IRIX 6 supports the n32 and 64 ABIs and always has a 64-bit MIPS 3 or better CPU. In both these ABIs GMP uses a 64-bit limb. A new enough gcc is required (2.95 for instance).

`ABI=n32'

The n32 ABI is 32-bit pointers and integers, but with a 64-bit limb using a long long. Applications must be compiled with

gcc  -mabi=n32
cc   -n32

`ABI=64'

The 64-bit ABI is 64-bit pointers and integers. Applications must be compiled with

gcc  -mabi=64
cc   -64

Note that MIPS GNU/Linux, as of kernel version 2.2, doesn't have the necessary support for n32 or 64 and so only gets a 32-bit limb and the MIPS 2 code.

PowerPC 64 (`powerpc64*')

`ABI=aix64'

The AIX 64 ABI uses 64-bit limbs and pointers and is available on systems `powerpc64*-*-aix*'. Applications must be compiled (and linked) with

gcc  -maix64
xlc  -q64

`ABI=32L'

This uses the 32-bit ABI but a 64-bit limb using GCC long long in 64-bit registers. Applications must be compiled with

gcc  -mpowerpc64

`ABI=32'

This is the basic 32-bit PowerPC ABI. No special compiler options are needed for applications.

Sparc V9 (`sparcv9' and `ultrasparc*')

`ABI=64'

The 64-bit V9 ABI is available on Solaris 2.7 and up and GNU/Linux. GCC 2.95 or up, or Sun cc is required. Applications must be compiled with

gcc  -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9
cc   -xarch=v9

`ABI=32'

On Solaris 2.6 and earlier, and on Solaris 2.7 with the kernel in 32-bit mode, only the plain V8 32-bit ABI can be used, since the kernel doesn't save all registers. GMP still uses as much of the V9 ISA as it can in these circumstances. No special compiler options are required for applications, though using something like the following requesting V9 code within the V8 ABI is recommended.

gcc  -mv8plus
cc   -xarch=v8plus

gcc 2.8 and earlier only supports `-mv8' though.

Don't be confused by the names of these sparc `-m' and `-x' options, they're called `arch' but they effectively control the ABI.

On Solaris 2.7 with the kernel in 32-bit-mode, a normal native build will reject `ABI=64' because the resulting executables won't run. `ABI=64' can still be built if desired by making it look like a cross-compile, for example

./configure --build=none --host=sparcv9-sun-solaris2.7 ABI=64

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.3 Notes for Package Builds

GMP should present no great difficulties for packaging in a binary distribution.

Libtool is used to build the library and `-version-info' is set appropriately, having started from `3:0:0' in GMP 3.0. The GMP 4 series will be upwardly binary compatible in each release and will be upwardly binary compatible with all of the GMP 3 series. Additional function interfaces may be added in each release, so on systems where libtool versioning is not fully checked by the loader an auxiliary mechanism may be needed to express that a dynamic linked application depends on a new enough GMP.

An auxiliary mechanism may also be needed to express that `libgmpxx.la' (from `--enable-cxx', see section 2.1 Build Options) requires `libgmp.la' from the same GMP version, since this is not done by the libtool versioning, nor otherwise. A mismatch will result in unresolved symbols from the linker, or perhaps the loader.

When building a package for a CPU family, care should be taken to use `--host' (or `--build') to choose the least common denominator among the CPUs which might use the package. For example this might necessitate `i386' for x86s, or plain `sparc' (meaning V7) for SPARCs.

Users who care about speed will want GMP built for their exact CPU type, to make use of the available optimizations. Providing a way to suitably rebuild a package may be useful. This could be as simple as making it possible for a user to omit `--build' (and `--host') so `./config.guess' will detect the CPU. But a way to manually specify a `--build' will be wanted for systems where `./config.guess' is inexact.

Note that `gmp.h' is a generated file, and will be architecture and ABI dependent.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.4 Notes for Particular Systems

AIX 3 and 4

On systems `*-*-aix[34]*' shared libraries are disabled by default, since some versions of the native ar fail on the convenience libraries used. A shared build can be attempted with

./configure --enable-shared --disable-static

Note that the `--disable-static' is necessary because in a shared build libtool makes `libgmp.a' a symlink to `libgmp.so', apparently for the benefit of old versions of ld which only recognise `.a', but unfortunately this is done even if a fully functional ld is available.

ARM

On systems `arm*-*-*', versions of GCC up to and including 2.95.3 have a bug in unsigned division, giving wrong results for some operands. GMP `./configure' will demand GCC 2.95.4 or later.

Microsoft Windows
On systems `*-*-cygwin*', `*-*-mingw*' and `*-*-pw32*' by default GMP builds only a static library, but a DLL can be built instead using

./configure --disable-static --enable-shared

Static and DLL libraries can't both be built, since certain export directives in `gmp.h' must be different. `--enable-cxx' cannot be used when building a DLL, since libtool doesn't currently support C++ DLLs. This might change in the future.

GCC is recommended for compiling GMP, but the resulting DLL can be used with any compiler. On mingw only the standard Windows libraries will be needed, on Cygwin the usual cygwin runtime will be required.

Motorola 68k CPU Types

`m68k' is taken to mean 68000. `m68020' or higher will give a performance boost on applicable CPUs. `m68360' can be used for CPU32 series chips. `m68302' can be used for "Dragonball" series chips, though this is merely a synonym for `m68000'.

OpenBSD 2.6

m4 in this release of OpenBSD has a bug in eval that makes it unsuitable for `.asm' file processing. `./configure' will detect the problem and either abort or choose another m4 in the PATH. The bug is fixed in OpenBSD 2.7, so either upgrade or use GNU m4.

Power CPU Types

In GMP, CPU types `power' and `powerpc' will each use instructions not available on the other, so it's important to choose the right one for the CPU that will be used. Currently GMP has no assembler code support for using just the common instruction subset. To get executables that run on both, the current suggestion is to use the generic C code (CPU `none'), possibly with appropriate compiler options (like `-mcpu=common' for gcc). CPU `rs6000' (which is not a CPU but a family of workstations) is accepted by `config.sub', but is currently equivalent to `none'.

Sparc CPU Types

`sparcv8' or `supersparc' on relevant systems will give a significant performance increase over the V7 code.

SunOS 4

/usr/bin/m4 lacks various features needed to process `.asm' files, and instead `./configure' will automatically use /usr/5bin/m4, which we believe is always available (if not then use GNU m4).

x86 CPU Types

`i386' selects generic code which will run reasonably well on all x86 chips.

`i586', `pentium' or `pentiummmx' code is good for the intended P5 Pentium chips, but quite slow when run on Intel P6 class chips (PPro, P-II, P-III). `i386' is a better choice when making binaries that must run on both.

`pentium4' and an SSE2 capable assembler are important for best results on Pentium 4. The specific code is for instance roughly a 2x{} to 3x code.

x86 MMX and SSE2 Code

If the CPU selected has MMX code but the assembler doesn't support it, a warning is given and non-MMX code is used instead. This will be an inferior build, since the MMX code that's present is there because it's faster than the corresponding plain integer code. The same applies to SSE2.

Old versions of `gas' don't support MMX instructions, in particular version 1.92.3 that comes with FreeBSD 2.2.8 doesn't (and unfortunately there's no newer assembler for that system).

Solaris 2.6 and 2.7 as generate incorrect object code for register to register movq instructions, and so can't be used for MMX code. Install a recent gas if MMX code is wanted on these systems.

x86 GCC `-march=pentiumpro'

GCC 2.95.2 and 2.95.3 miscompiled some versions of `mpz/powm.c' when `-march=pentiumpro' was used, so for relevant CPUs that option is only in the default CFLAGS for GCC 2.95.4 and up.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.5 Known Build Problems

You might find more up-to-date information at http://swox.com/gmp/.

DJGPP

The DJGPP port of bash 2.03 is unable to run the `configure' script, it exits silently, having died writing a preamble to `config.log'. Use bash 2.04 or higher.

`make all' was found to run out of memory during the final `libgmp.la' link on one system tested, despite having 64Mb available. A separate `make libgmp.la' helped, perhaps recursing into the various subdirectories uses up memory.

GNU binutils strip

GNU binutils strip should not be used on the static libraries `libgmp.a' and `libmp.a', neither directly nor via `make install-strip'. It can be used on the shared libraries `libgmp.so' and `libmp.so' though.

Currently (binutils 2.10.0), strip unpacks an archive then operates on the files, but GMP contains multiple object files of the same name (eg. three versions of `init.o'), and they overwrite each other, leaving only the one that happens to be last.

If stripped static libraries are wanted, the suggested workaround is to build normally, strip the separate object files, and do another `make all' to rebuild. Alternately `CFLAGS' with `-g' omitted can always be used if it's just debugging which is unwanted.

NeXT prior to 3.3

The system compiler on old versions of NeXT was a massacred and old GCC, even if it called itself `cc'. This compiler cannot be used to build GMP, you need to get a real GCC, and install that. (NeXT may have fixed this in release 3.3 of their system.)

POWER and PowerPC

Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP on POWER or PowerPC. If you want to use GCC for these machines, get GCC 2.7.2.1 (or later).

Sequent Symmetry

Use the GNU assembler instead of the system assembler, since the latter has serious bugs.

Solaris 2.6

The system sed prints an error "Output line too long" when libtool builds `libgmp.la'. This doesn't seem cause any obvious ill effects, but GNU sed is recommended, to avoid any doubt.

Sparc Solaris 2.7 with gcc 2.95.2 in ABI=32

A shared library build of GMP seems to fail in this combination, it builds but then fails the tests, apparently due to some incorrect data relocations within gmp_randinit_lc_2exp_size. The exact cause is unknown, `--disable-shared' is recommended.

Windows DLL test programs

When creating a DLL version of `libgmp', libtool creates wrapper scripts like `t-mul' for programs that would normally be `t-mul.exe', in order to setup the right library paths etc. This works fine, but the absence of `t-mul.exe' etc causes make to think they need recompiling every time, which is an annoyance when re-running a `make check'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. GMP Basics

All declarations needed to use GMP are collected in the include file `gmp.h'. It is designed to work with both C and C++ compilers.

#include <gmp.h>

Note however that prototypes for GMP functions with FILE * parameters are only provided if <stdio.h> is included too.

#include <stdio.h>
#include <gmp.h>

Using functions, macros, data types, etc. not documented in this manual is strongly discouraged. If you do so your application is guaranteed to be incompatible with future versions of GMP.

3.1 Nomenclature and Types
3.2 Function Classes
3.3 Variable Conventions
3.4 Parameter Conventions
3.5 Memory Management
3.6 Reentrancy
3.7 Useful Macros and Constants
3.8 Compatibility with older versions
3.9 Efficiency
3.10 Debugging
3.11 Profiling
3.12 Autoconf

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 Nomenclature and Types

In this manual, integer usually means a multiple precision integer, as defined by the GMP library. The C data type for such integers is mpz_t. Here are some examples of how to declare such integers:

mpz_t sum;

struct foo { mpz_t x, y; };

mpz_t vec[20];

Rational number means a multiple precision fraction. The C data type for these fractions is mpq_t. For example:

mpq_t quotient;

Floating point number or Float for short, is an arbitrary precision mantissa with a limited precision exponent. The C data type for such objects is mpf_t.

A limb means the part of a multi-precision number that fits in a single machine word. (We chose this word because a limb of the human body is analogous to a digit, only larger, and containing several digits.) Normally a limb is 32 or 64 bits. The C data type for a limb is mp_limb_t.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 Function Classes

There are six classes of functions in the GMP library:

  1. Functions for signed integer arithmetic, with names beginning with mpz_. The associated type is mpz_t. There are about 150 functions in this class.

  2. Functions for rational number arithmetic, with names beginning with mpq_. The associated type is mpq_t. There are about 40 functions in this class, but the integer functions can be used for arithmetic on the numerator and denominator separately.

  3. Functions for floating-point arithmetic, with names beginning with mpf_. The associated type is mpf_t. There are about 60 functions is this class.

  4. Functions compatible with Berkeley MP, such as itom, madd, and mult. The associated type is MINT.

  5. Fast low-level functions that operate on natural numbers. These are used by the functions in the preceding groups, and you can also call them directly from very time-critical user programs. These functions' names begin with mpn_. The associated type is array of mp_limb_t. There are about 30 (hard-to-use) functions in this class.

  6. Miscellaneous functions. Functions for setting up custom allocation and functions for generating random numbers.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 Variable Conventions

GMP functions generally have output arguments before input arguments. This notation is by analogy with the assignment operator. The BSD MP compatibility functions are exceptions, having the output arguments last.

GMP lets you use the same variable for both input and output in one call. For example, the main function for integer multiplication, mpz_mul, can be used to square x and put the result back in x with

mpz_mul (x, x, x);

Before you can assign to a GMP variable, you need to initialize it by calling one of the special initialization functions. When you're done with a variable, you need to clear it out, using one of the functions for that purpose. Which function to use depends on the type of variable. See the chapters on integer functions, rational number functions, and floating-point functions for details.

A variable should only be initialized once, or at least cleared between each initialization. After a variable has been initialized, it may be assigned to any number of times.

For efficiency reasons, avoid excessive initializing and clearing. In general, initialize near the start of a function and clear near the end. For example,

void
foo (void)
{
  mpz_t  n;
  int    i;
  mpz_init (n);
  for (i = 1; i < 100; i++)
    {
      mpz_mul (n, ...);
      mpz_fdiv_q (n, ...);
      ...
    }
  mpz_clear (n);
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4 Parameter Conventions

When a GMP variable is used as a function parameter, it's effectively a call-by-reference, meaning if the function stores a value there it will change the original in the caller.

When a function is going to return a GMP result, it should designate a parameter that it sets, like the library functions do. More than one value can be returned by having more than one output parameter, again like the library functions. A return of an mpz_t etc doesn't return the object, only a pointer, and this is almost certainly not what's wanted.

Here's an example accepting an mpz_t parameter, doing a calculation, and storing the result to the indicated parameter.

void
foo (mpz_t result, mpz_t param, unsigned long n)
{
  unsigned long  i;
  mpz_mul_ui (result, param, n);
  for (i = 1; i < n; i++)
    mpz_add_ui (result, result, i*7);
}

int
main (void)
{
  mpz_t  r, n;
  mpz_init (r);
  mpz_init_set_str (n, "123456", 0);
  foo (r, n, 20L);
  gmp_printf ("%Zd\n", r);
  return 0;
}

foo works even if the mainline passes the same variable as both param and result, just like the library functions. But sometimes this is tricky to arrange, and an application might not want to bother supporting that sort of thing.

For interest, the GMP types mpz_t etc are implemented as one-element arrays of certain structures. This is why declaring a variable creates an object with the fields GMP needs, but then using it as a parameter passes a pointer to the object. Note that the actual fields in each mpz_t etc are for internal use only and should not be accessed directly by code that expects to be compatible with future GMP releases.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5 Memory Management

The GMP types like mpz_t are small, containing only a couple of sizes, and pointers to allocated data. Once a variable is initialized, GMP takes care of all space allocation. Additional space is allocated whenever a variable doesn't have enough.

mpz_t and mpq_t variables never reduce their allocated space. Normally this is the best policy, since it avoids frequent reallocation. Applications that need to return memory to the heap at some particular point can use mpz_realloc2, or clear variables no longer needed.

mpf_t variables, in the current implementation, use a fixed amount of space, determined by the chosen precision and allocated at initialization, so their size doesn't change.

All memory is allocated using malloc and friends by default, but this can be changed, see 14. Custom Allocation. Temporary memory on the stack is also used (via alloca), but this can be changed at build-time if desired, see 2.1 Build Options.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6 Reentrancy

GMP is reentrant and thread-safe, with some exceptions:

  • If configured with `--enable-alloca=malloc-notreentrant' (or with `--enable-alloca=notreentrant' when alloca is not available), then naturally GMP is not reentrant.

  • mpf_set_default_prec and mpf_init use a global variable for the selected precision. mpf_init2 can be used instead.

  • mp_set_memory_functions uses global variables to store the selected memory allocation functions.

  • mpz_random and the other old random number functions use a global random state and are hence not reentrant. The newer random number functions that accept a gmp_randstate_t parameter can be used instead.

  • If the memory allocation functions set by a call to mp_set_memory_functions (or malloc and friends by default) are not reentrant, then GMP will not be reentrant either.

  • If the standard I/O functions such as fwrite are not reentrant then the GMP I/O functions using them will not be reentrant either.

  • It's safe for two threads to read from the same GMP variable simultaneously, but it's not safe for one to read while the another might be writing, nor for two threads to write simultaneously. It's not safe for two threads to generate a random number from the same gmp_randstate_t simultaneously, since this involves an update of that variable.

  • On SCO systems the default <ctype.h> macros use per-file static variables and may not be reentrant, depending whether the compiler optimizes away fetches from them. The GMP text-based input functions are affected.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.7 Useful Macros and Constants

Global Constant: const int mp_bits_per_limb
The number of bits per limb.

Macro: __GNU_MP_VERSION
Macro: __GNU_MP_VERSION_MINOR
Macro: __GNU_MP_VERSION_PATCHLEVEL
The major and minor GMP version, and patch level, respectively, as integers. For GMP i.j, these numbers will be i, j, and 0, respectively. For GMP i.j.k, these numbers will be i, j, and k, respectively.

Global Constant: const char * const gmp_version
The GMP version number, as a null-terminated string, in the form "i.j" or "i.j.k". This release is "4.0.1".

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.8 Compatibility with older versions

This version of GMP is upwardly binary compatible with all 3.x versions, and upwardly compatible at the source level with all 2.x versions, with the following exceptions.

  • mpn_gcd had its source arguments swapped as of GMP 3.0, for consistency with other mpn functions.

  • mpf_get_prec counted precision slightly differently in GMP 3.0 and 3.0.1, but in 3.1 reverted to the 2.x style.

There are a number of compatibility issues between GMP 1 and GMP 2 that of course also apply when porting applications from GMP 1 to GMP 4. Please see the GMP 2 manual for details.

The Berkeley MP compatibility library (see section 13. Berkeley MP Compatible Functions) is source and binary compatible with the standard `libmp'.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.9 Efficiency

Small operands
On small operands, the time for function call overheads and memory allocation can be significant in comparison to actual calculation. This is unavoidable in a general purpose variable precision library, although GMP attempts to be as efficient as it can on both large and small operands.

Static Linking
On some CPUs, in particular the x86s, the static `libgmp.a' should be used for maximum speed, since the PIC code in the shared `libgmp.so' will have a small overhead on each function call and global data address. For many programs this will be insignificant, but for long calculations there's a gain to be had.

Initializing and clearing
Avoid excessive initializing and clearing of variables, since this can be quite time consuming, especially in comparison to otherwise fast operations like addition.

A language interpreter might want to keep a free list or stack of initialized variables ready for use. It should be possible to integrate something like that with a garbage collector too.

Reallocations
An mpz_t or mpq_t variable used to hold successively increasing values will have its memory repeatedly realloced, which could be quite slow or could fragment memory, depending on the C library. If an application can estimate the final size then mpz_init2 or mpz_realloc2 can be called to allocate the necessary space from the beginning (see section 5.1 Initialization Functions).

It doesn't matter if a size set with mpz_init2 or mpz_realloc2 is too small, since all functions will do a further reallocation if necessary. Badly overestimating memory required will waste space though.

2exp functions
It's up to an application to call functions like mpz_mul_2exp when appropriate. General purpose functions like mpz_mul make no attempt to identify powers of two or other special forms, because such inputs will usually be very rare and testing every time would be wasteful.

ui and si functions
The ui functions and the small number of si functions exist for convenience and should be used where applicable. But if for example an mpz_t contains a value that fits in an unsigned long there's no need extract it and call a ui function, just use the regular mpz function.

In-Place Operations
mpz_abs, mpq_abs, mpf_abs, mpz_neg, mpq_neg and mpf_neg are fast when used for in-place operations like mpz_abs(x,x), since in the current implementation only a single field of x needs changing. On suitable compilers (GCC for instance) this is inlined too.

mpz_add_ui, mpz_sub_ui, mpf_add_ui and mpf_sub_ui benefit from an in-place operation like mpz_add_ui(x,x,y), since usually only one or two limbs of x will need to be changed. The same applies to the full precision mpz_add etc if y is small. If y is big then cache locality may be helped, but that's all.

mpz_mul is currently the opposite, a separate destination is slightly better. A call like mpz_mul(x,x,y) will, unless y is only one limb, make a temporary copy of x before forming the result. Normally that copying will only be a tiny fraction of the time for the multiply, so this is not a particularly important consideration.

mpz_set, mpq_set, mpq_set_num, mpf_set, etc, make no attempt to recognise a copy of something to itself, so a call like mpz_set(x,x) will be wasteful. Naturally that would never be written deliberately, but if it might arise from two pointers to the same object then a test to avoid it might be desirable.

if (x != y)
  mpz_set (x, y);

Note that it's never worth introducing extra mpz_set calls just to get in-place operations. If a result should go to a particular variable then just direct it there and let GMP take care of data movement.

Divisibility Testing (Small Integers)

mpz_divisible_ui_p and mpz_congruent_ui_p are the best functions for testing whether an mpz_t is divisible by an individual small integer. They use an algorithm which is faster than mpz_tdiv_ui, but which gives no useful information about the actual remainder, only whether it's zero (or a particular value).

However when testing divisibility by several small integers, it's best to take a remainder modulo their product, to save multi-precision operations. For instance to test whether a number is divisible by any of 23, 29 or 31 take a remainder modulo 23*31 = 20677 and then test that.

The division functions like mpz_tdiv_q_ui which give a quotient as well as a remainder are generally a little slower than the remainder-only functions like mpz_tdiv_ui. If the quotient is only rarely wanted then it's probably best to just take a remainder and then go back and calculate the quotient if and when it's wanted (mpz_divexact_ui can be used if the remainder is zero).

Rational Arithmetic
The mpq functions operate on mpq_t values with no common factors in the numerator and denominator. Common factors are checked-for and cast out as necessary. In general, cancelling factors every time is the best approach since it minimizes the sizes for subsequent operations.

However, applications that know something about the factorization of the values they're working with might be able to avoid some of the GCDs used for canonicalization, or swap them for divisions. For example when multiplying by a prime it's enough to check for factors of it in the denominator instead of doing a full GCD. Or when forming a big product it might be known that very little cancellation will be possible, and so canonicalization can be left to the end.

The mpq_numref and mpq_denref macros give access to the numerator and denominator to do things outside the scope of the supplied mpq functions. See section 6.5 Applying Integer Functions to Rationals.

The canonical form for rationals allows mixed-type mpq_t and integer additions or subtractions to be done directly with multiples of the denominator. This will be somewhat faster than mpq_add. For example,

/* mpq increment */
mpz_add (mpq_numref(q), mpq_numref(q), mpq_denref(q));

/* mpq += unsigned long */
mpz_addmul_ui (mpq_numref(q), mpq_denref(q), 123UL);

/* mpq -= mpz */
mpz_submul (mpq_numref(q), mpq_denref(q), z);

Number Sequences
Functions like mpz_fac_ui, mpz_fib_ui and mpz_bin_uiui are designed for calculating isolated values. If a range of values is wanted it's probably best to call to get a starting point and iterate from there.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.10 Debugging

Stack Overflow
Depending on the system, a segmentation violation or bus error might be the only indication of stack overflow. See `--enable-alloca' choices in 2.1 Build Options, for how to address this.

Heap Problems
The most likely cause of application problems with GMP is heap corruption. Failing to init GMP variables will have unpredictable effects, and corruption arising elsewhere in a program may well affect GMP. Initializing GMP variables more than once or failing to clear them will cause memory leaks.

In all such cases a malloc debugger is recommended. On a GNU or BSD system the standard C library malloc has some diagnostic facilities, see section `Allocation Debugging' in The GNU C Library Reference Manual, or `man 3 malloc'. Other possibilities, in no particular order, include

http://www.inf.ethz.ch/personal/biere/projects/ccmalloc
http://quorum.tamu.edu/jon/gnu  (debauch)
http://dmalloc.com
http://www.perens.com/FreeSoftware  (electric fence)
http://packages.debian.org/fda
http://www.gnupdate.org/components/leakbug
http://people.redhat.com/~otaylor/memprof
http://www.cbmamiga.demon.co.uk/mpatrol

Stack Backtraces
On some systems the compiler options GMP uses by default can interfere with debugging. In particular on x86 and 68k systems `-fomit-frame-pointer' is used and this generally inhibits stack backtracing. Recompiling without such options may help while debugging, though the usual caveats about it potentially moving a memory problem or hiding a compiler bug will apply.

GNU Debugger
A sample `.gdbinit' is included in the distribution, showing how to call some undocumented dump functions to print GMP variables from within GDB. Note that these functions shouldn't be used in final application code since they're undocumented and may be subject to incompatible changes in future versions of GMP.

Source File Paths
GMP has multiple source files with the same name, in different directories. For example `mpz', `mpq', `mpf' and `mpfr' each have an `init.c'. If the debugger can't already determine the right one it may help to build with absolute paths on each C file. One way to do that is to use a separate object directory with an absolute path to the source directory.

cd /my/build/dir
/my/source/dir/gmp-4.0.1/configure

This works via VPATH, and might require GNU make. Alternately it might be possible to change the .c.lo rules appropriately.

Assertion Checking
The build option `--enable-assert' is available to add some consistency checks to the library (see 2.1 Build Options). These are likely to be of limited value to most applications. Assertion failures are just as likely to indicate memory corruption as a library or compiler bug.

Applications using the low-level mpn functions, however, will benefit from `--enable-assert' since it adds checks on the parameters of most such functions, many of which have subtle restrictions on their usage. Note however that only the generic C code has checks, not the assembler code, so CPU `none' should be used for maximum checking.

Temporary Memory Checking
The build option `--enable-alloca=debug' arranges that each block of temporary memory in GMP is allocated with a separate call to malloc (or the allocation function set with mp_set_memory_functions).

This can help a malloc debugger detect accesses outside the intended bounds, or detect memory not released. In a normal build, on the other hand, temporary memory is allocated in blocks which GMP divides up for its own use, or may be allocated with a compiler builtin alloca which will go nowhere near any malloc debugger hooks.

Other Problems
Any suspected bug in GMP itself should be isolated to make sure it's not an application problem, see 4. Reporting Bugs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.11 Profiling

Running a program under a profiler is a good way to find where it's spending most time and where improvements can be best sought.

Depending on the system, it may be possible to get a flat profile, meaning simple timer sampling of the program counter, with no special GMP build options, just a `-p' when compiling the mainline. This is a good way to ensure minimum interference with normal operation. The necessary symbol type and size information exists in most of the GMP assembler code.

The `--enable-profiling' build option can be used to add suitable compiler flags, either for prof (`-p') or gprof (`-pg'), see 2.1 Build Options. Which of the two is available and what they do will depend on the system, and possibly on support available in `libc'. For some systems appropriate corresponding mcount calls are added to the assembler code too.

On x86 systems prof gives call counting, so that average time spent in a function can be determined. gprof, where supported, adds call graph construction, so for instance calls to mpn_add_n from mpz_add and from mpz_mul can be differentiated.

On x86 and 68k systems `-pg' and `-fomit-frame-pointer' are incompatible, so the latter is not used when gprof profiling is selected, which may result in poorer code generation. If prof profiling is selected instead it should still be possible to use gprof, but only the `gprof -p' flat profile and call counts can be expected to be valid, not the `gprof -q' call graph.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.12 Autoconf

Autoconf based applications can easily check whether GMP is installed. The only thing to be noted is that GMP library symbols from version 3 onwards have prefixes like __gmpz. The following therefore would be a simple test,

AC_CHECK_LIB(gmp, __gmpz_init)

This just uses the default AC_CHECK_LIB actions for found or not found, but an application that must have GMP would want to generate an error if not found. For example,

AC_CHECK_LIB(gmp, __gmpz_init, , [AC_MSG_ERROR(
[GNU MP not found, see http://swox.com/gmp])])

If functions added in some particular version of GMP are required, then one of those can be used when checking. For example mpz_mul_si was added in GMP 3.1,
AC_CHECK_LIB(gmp, __gmpz_mul_si, , [AC_MSG_ERROR(
[GNU MP not found, or not 3.1 or up, see http://swox.com/gmp])])

An alternative would be to test the version number in `gmp.h' using say AC_EGREP_CPP. That would make it possible to test the exact version, if some particular sub-minor release is known to be necessary.

An application that can use either GMP 2 or 3 will need to test for __gmpz_init (GMP 3 and up) or mpz_init (GMP 2), and it's also worth checking for `libgmp2' since Debian GNU/Linux systems used that name in the past. For example,

AC_CHECK_LIB(gmp, __gmpz_init, ,
  [AC_CHECK_LIB(gmp, mpz_init, ,
    [AC_CHECK_LIB(gmp2, mpz_init)])])

In general it's suggested that applications should simply demand a new enough GMP rather than trying to provide supplements for features not available in past versions.

Occasionally an application will need or want to know the size of a type at configuration or preprocessing time, not just with sizeof in the code. This can be done in the normal way with mp_limb_t etc, but GMP 4.0 or up is best for this, since prior versions needed certain `-D' defines on systems using a long long limb. The following would suit Autoconf 2.50 or up,

AC_CHECK_SIZEOF(mp_limb_t, , [#include <gmp.h>])

The optional mpfr functions are provided in a separate `libmpfr.a', and this might be from GMP with `--enable-mpfr' or from MPFR installed separately. Either way `libmpfr' depends on `libgmp', it doesn't stand alone. Currently only a static `libmpfr.a' will be available, not a shared library, since upward binary compatibility is not guaranteed.

AC_CHECK_LIB(mpfr, mpfr_add, , [AC_MSG_ERROR(
[Need MPFR either from GNU MP 4 or separate MPFR package.
See http://www.mpfr.org or http://swox.com/gmp])

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Reporting Bugs

If you think you have found a bug in the GMP library, please investigate it and report it. We have made this library available to you, and it is not too much to ask you to report the bugs you find.

Before you report a bug, check it's not already addressed in 2.5 Known Build Problems, or perhaps 2.4 Notes for Particular Systems. You may also want to check http://swox.com/gmp/ for patches for this release.

Please include the following in any report,

  • The GMP version number, and if pre-packaged or patched then say so.

  • A test program that makes it possible for us to reproduce the bug. Include instructions on how to run the program.

  • A description of what is wrong. If the results are incorrect, in what way. If you get a crash, say so.

  • If you get a crash, include a stack backtrace from the debugger if it's informative (`where' in gdb, or `$C' in adb).

  • Please do not send core dumps, executables or straces.

  • The configuration options you used when building GMP, if any.

  • The name of the compiler and its version. For gcc, get the version with `gcc -v', otherwise perhaps `what `which cc`', or similar.

  • The output from running `uname -a'.

  • The output from running `./config.guess', and from running `./configfsf.guess' (might be the same).

  • If the bug is related to `configure', then the contents of `config.log'.

  • If the bug is related to an `asm' file not assembling, then the contents of `config.m4' and the offending line or lines from the temporary `mpn/tmp-<file>.s'.

Please make an effort to produce a self-contained report, with something definite that can be tested or debugged. Vague queries or piecemeal messages are difficult to act on and don't help the development effort.

It is not uncommon that an observed problem is actually due to a bug in the compiler; the GMP code tends to explore interesting corners in compilers.

If your bug report is good, we will do our best to help you get a corrected version of the library; if the bug report is poor, we won't do anything about it (except maybe ask you to send a better report).

Send your report to: bug-gmp@gnu.org.

If you think something in this manual is unclear, or downright incorrect, or if the language needs to be improved, please send a note to the same address.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Integer Functions

This chapter describes the GMP functions for performing integer arithmetic. These functions start with the prefix mpz_.

GMP integers are stored in objects of type mpz_t.

5.1 Initialization Functions
5.2 Assignment Functions
5.3 Combined Initialization and Assignment Functions
5.4 Conversion Functions
5.5 Arithmetic Functions
5.6 Division Functions
5.7 Exponentiation Functions
5.8 Root Extraction Functions
5.9 Number Theoretic Functions
5.10 Comparison Functions
5.11 Logical and Bit Manipulation Functions
5.12 Input and Output Functions
5.13 Random Number Functions
5.14 Miscellaneous Functions

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 Initialization Functions

The functions for integer arithmetic assume that all integer objects are initialized. You do that by calling the function mpz_init. For example,

{
  mpz_t integ;
  mpz_init (integ);
  ...
  mpz_add (integ, ...);
  ...
  mpz_sub (integ, ...);

  /* Unless the program is about to exit, do ... */
  mpz_clear (integ);
}

As you can see, you can store new values any number of times, once an object is initialized.

Function: void mpz_init (mpz_t integer)
Initialize integer, and set its value to 0.

Function: void mpz_init2 (mpz_t integer, unsigned long n)
Initialize integer, with space for n bits, and set its value to 0.

n is only the initial space, integer will grow automatically in the normal way, if necessary, for subsequent values stored. mpz_init2 makes it possible to avoid such reallocations if a maximum size is known in advance.

Function: void mpz_clear (mpz_t integer)
Free the space occupied by integer. Call this function for all mpz_t variables when you are done with them.

Function: void mpz_realloc2 (mpz_t integer, unsigned long n)
Change the space allocated for integer to n bits. The value in integer is preserved if it fits, or is set to 0 if not.

This function can be used to increase the space for a variable in order to avoid repeated automatic reallocations, or to decrease it to give memory back to the heap.

Function: void mpz_array_init (mpz_t integer_array[], size_t array_size, mp_size_t fixed_num_bits)
This is a special type of initialization. Fixed space of fixed_num_bits bits is allocated to each of the array_size integers in integer_array.

The space will not be automatically increased, unlike the normal mpz_init, but instead an application must ensure it's sufficient for any value stored. The following space requirements apply to various functions,

  • mpz_abs, mpz_neg, mpz_set, mpz_set_si and mpz_set_ui need room for the value they store.

  • mpz_add, mpz_add_ui, mpz_sub and mpz_sub_ui need room for the larger of the two operands, plus an extra mp_bits_per_limb.

  • mpz_mul, mpz_mul_ui and mpz_mul_ui need room for the sum of the number of bits in their operands, but each rounded up to a multiple of mp_bits_per_limb.

  • mpz_swap can be used between two array variables, but not between an array and a normal variable.

For other functions, or if in doubt, the suggestion is to calculate in a regular mpz_init variable and copy the result to an array variable with mpz_set.

mpz_array_init can reduce memory usage in algorithms that need large arrays of integers, since it avoids allocating and reallocating lots of small memory blocks. There is no way to free the storage allocated by this function. Don't call mpz_clear!

Function: void * _mpz_realloc (mpz_t integer, mp_size_t new_alloc)
Change the space for integer to new_alloc limbs. The value in integer is preserved if it fits, or is set to 0 if not. The return value is not useful to applications and should be ignored.

mpz_realloc2 is the preferred way to accomplish allocation changes like this. mpz_realloc2 and _mpz_realloc are the same except that _mpz_realloc takes the new size in limbs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 Assignment Functions

These functions assign new values to already initialized integers (see section 5.1 Initialization Functions).

Function: void mpz_set (mpz_t rop, mpz_t op)
Function: void mpz_set_ui (mpz_t rop, unsigned long int op)
Function: void mpz_set_si (mpz_t rop, signed long int op)
Function: void mpz_set_d (mpz_t rop, double op)
Function: void mpz_set_q (mpz_t rop, mpq_t op)
Function: void mpz_set_f (mpz_t rop, mpf_t op)
Set the value of rop from op.

mpz_set_d, mpz_set_q and mpz_set_f truncate op to make it an integer.

Function: int mpz_set_str (mpz_t rop, char *str, int base)
Set the value of rop from str, a null-terminated C string in base base. White space is allowed in the string, and is simply ignored. The base may vary from 2 to 36. If base is 0, the actual base is determined from the leading characters: if the first two characters are "0x" or "0X", hexadecimal is assumed, otherwise if the first character is "0", octal is assumed, otherwise decimal is assumed.

This function returns 0 if the entire string is a valid number in base base. Otherwise it returns -1.

[It turns out that it is not entirely true that this function ignores white-space. It does ignore it between digits, but not after a minus sign or within or after "0x". We are considering changing the definition of this function, making it fail when there is any white-space in the input, since that makes a lot of sense. Send your opinion of this change to bug-gmp@gnu.org. Do you really want it to accept "3 14" as meaning 314 as it does now?]

Function: void mpz_swap (mpz_t rop1, mpz_t rop2)
Swap the values rop1 and rop2 efficiently.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.3 Combined Initialization and Assignment Functions

For convenience, GMP provides a parallel series of initialize-and-set functions which initialize the output and then store the value there. These functions' names have the form mpz_init_set...

Here is an example of using one:

{
  mpz_t pie;
  mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);
  ...
  mpz_sub (pie, ...);
  ...
  mpz_clear (pie);
}

Once the integer has been initialized by any of the mpz_init_set... functions, it can be used as the source or destination operand for the ordinary integer functions. Don't use an initialize-and-set function on a variable already initialized!

Function: void mpz_init_set (mpz_t rop, mpz_t op)
Function: void mpz_init_set_ui (mpz_t rop, unsigned long int op)
Function: void mpz_init_set_si (mpz_t rop, signed long int op)
Function: void mpz_init_set_d (mpz_t rop, double op)
Initialize rop with limb space and set the initial numeric value from op.

Function: int mpz_init_set_str (mpz_t rop, char *str, int base)
Initialize rop and set its value like mpz_set_str (see its documentation above for details).

If the string is a correct base base number, the function returns 0; if an error occurs it returns -1. rop is initialized even if an error occurs. (I.e., you have to call mpz_clear for it.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4 Conversion Functions

This section describes functions for converting GMP integers to standard C types. Functions for converting to GMP integers are described in 5.2 Assignment Functions and 5.12 Input and Output Functions.

Function: unsigned long int mpz_get_ui (mpz_t op)
Return the least significant part from op. This function combined with
mpz_tdiv_q_2exp(..., op, CHAR_BIT*sizeof(unsigned long int)) can be used to decompose an integer into unsigned longs.

Function: signed long int mpz_get_si (mpz_t op)
If op fits into a signed long int return the value of op. Otherwise return the least significant part of op, with the same sign as op.

If op is too large to fit in a signed long int, the returned result is probably not very useful. To find out if the value will fit, use the function mpz_fits_slong_p.

Function: double mpz_get_d (mpz_t op)
Convert op to a double.

Function: double mpz_get_d_2exp (signed long int exp, mpz_t op)
Find d and exp such that \N\\times 2^{exp}, d times 2 raised to exp}, with 0.5<=<1}, is a good approximation to op.

Function: char * mpz_get_str (char *str, int base, mpz_t op)
Convert op to a string of digits in base base. The base may vary from 2 to 36.

If str is NULL, the result string is allocated using the current allocation function (see section 14. Custom Allocation). The block will be strlen(str)+1 bytes, that being exactly enough for the string and null-terminator.

If str is not NULL, it should point to a block of storage large enough for the result, that being mpz_sizeinbase (op, base) + 2. The two extra bytes are for a possible minus sign, and the null-terminator.

A pointer to the result string is returned, being either the allocated block, or the given str.

Function: mp_limb_t mpz_getlimbn (mpz_t op, mp_size_t n)
Return limb number n from op. The sign of op is ignored, just the absolute value is used. The least significant limb is number 0.

mpz_size can be used to find how many limbs make up op. mpz_getlimbn returns zero if n is outside the range 0 to mpz_size(op)-1.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.5 Arithmetic Functions

Function: void mpz_add (mpz_t rop, mpz_t op1, mpz_t op2)
Function: void mpz_add_ui (mpz_t rop, mpz_t op1, unsigned long int op2)
Set rop to op1 + op2.

Function: void mpz_sub (mpz_t rop, mpz_t op1, mpz_t op2)
Function: void mpz_sub_ui (mpz_t rop, mpz_t op1, unsigned long int op2)
Set rop to op1 - op2.

Function: void mpz_mul (mpz_t rop, mpz_t op1, mpz_t op2)
Function: void mpz_mul_si (mpz_t rop, mpz_t op1, long int op2)
Function: void mpz_mul_ui (mpz_t rop, mpz_t op1, unsigned long int op2)
Set rop to op1 times.

Function: void mpz_addmul (mpz_t rop, mpz_t op1, mpz_t op2)
Function: void mpz_addmul_ui (mpz_t rop, mpz_t op1, unsigned long int op2)
Set rop to rop + op1 times.

Function: void mpz_submul (mpz_t rop, mpz_t op1, mpz_t op2)
Function: void mpz_submul_ui (mpz_t rop, mpz_t op1, unsigned long int op2)
Set rop to rop - op1 times.

Function: void mpz_mul_2exp (mpz_t rop, mpz_t op1, unsigned long int op2)
Set rop to \N\ \times 2^{op2}, op1 times 2 raised to op2}. This operation can also be defined as a left shift by op2 bits.

Function: void mpz_neg (mpz_t rop, mpz_t op)
Set rop to -op.

Function: void mpz_abs (mpz_t rop, mpz_t op)
Set rop to the absolute value of op.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.6 Division Functions

Division is undefined if the divisor is zero. Passing a zero divisor to the division or modulo functions (including the modular powering functions mpz_powm and mpz_powm_ui), will cause an intentional division by zero. This lets a program handle arithmetic exceptions in these functions the same way as for normal C int arithmetic.

Function: void mpz_cdiv_q (mpz_t q, mpz_t n, mpz_t d)
Function: void mpz_cdiv_r (mpz_t r, mpz_t n, mpz_t d)
Function: void mpz_cdiv_qr (mpz_t q, mpz_t r, mpz_t n, mpz_t d)
Function: unsigned long int mpz_cdiv_q_ui (mpz_t q, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_cdiv_r_ui (mpz_t r, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_cdiv_qr_ui (mpz_t q, mpz_t r, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_cdiv_ui (mpz_t n, unsigned long int d)
Function: void mpz_cdiv_q_2exp (mpz_t q, mpz_t n, unsigned long int b)
Function: void mpz_cdiv_r_2exp (mpz_t r, mpz_t n, unsigned long int b)

Function: void mpz_fdiv_q (mpz_t q, mpz_t n, mpz_t d)
Function: void mpz_fdiv_r (mpz_t r, mpz_t n, mpz_t d)
Function: void mpz_fdiv_qr (mpz_t q, mpz_t r, mpz_t n, mpz_t d)
Function: unsigned long int mpz_fdiv_q_ui (mpz_t q, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_fdiv_r_ui (mpz_t r, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_fdiv_qr_ui (mpz_t q, mpz_t r, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_fdiv_ui (mpz_t n, unsigned long int d)
Function: void mpz_fdiv_q_2exp (mpz_t q, mpz_t n, unsigned long int b)
Function: void mpz_fdiv_r_2exp (mpz_t r, mpz_t n, unsigned long int b)

Function: void mpz_tdiv_q (mpz_t q, mpz_t n, mpz_t d)
Function: void mpz_tdiv_r (mpz_t r, mpz_t n, mpz_t d)
Function: void mpz_tdiv_qr (mpz_t q, mpz_t r, mpz_t n, mpz_t d)
Function: unsigned long int mpz_tdiv_q_ui (mpz_t q, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_tdiv_r_ui (mpz_t r, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_tdiv_qr_ui (mpz_t q, mpz_t r, mpz_t n, unsigned long int d)
Function: unsigned long int mpz_tdiv_ui (mpz_t n, unsigned long int d)
Function: void mpz_tdiv_q_2exp (mpz_t q, mpz_t n, unsigned long int b)
Function: void mpz_tdiv_r_2exp (mpz_t r, mpz_t n, unsigned long int b)

Divide n by d, forming a quotient q and/or remainder r. For the 2exp functions, \N\=2^b, d=2^b}. The rounding is in three styles, each suiting different applications.

  • cdiv rounds q up towards +infinity, and r will have the opposite sign to d. The c stands for "ceil".

  • fdiv rounds q down towards -infinity, and r will have the same sign as d. The f stands for "floor".

  • tdiv rounds q towards zero, and r will have the same sign as n. The t stands for "truncate".

In all cases q and r will satisfy \N\=qd+r, n=q*d+r}, and r will satisfy 0<=<abs}.

The q functions calculate only the quotient, the r functions only the remainder, and the qr functions calculate both. Note that for qr the same variable cannot be passed for both q and r, or results will be unpredictable.

For the ui variants the return value is the remainder, and in fact returning the remainder is all the div_ui functions do. For tdiv and cdiv the remainder can be negative, so for those the return value is the absolute value of the remainder.

The 2exp functions are right shifts and bit masks, but of course rounding the same as the other functions. For positive n both mpz_fdiv_q_2exp and mpz_tdiv_q_2exp are simple bitwise right shifts. For negative n, mpz_fdiv_q_2exp is effectively an arithmetic right shift treating n as twos complement the same as the bitwise logical functions do, whereas mpz_tdiv_q_2exp effectively treats n as sign and magnitude.

Function: void mpz_mod (mpz_t r, mpz_t n, mpz_t d)
Function: unsigned long int mpz_mod_ui (mpz_t r, mpz_t n, unsigned long int d)
Set r to n mod d. The sign of the divisor is ignored; the result is always non-negative.

mpz_mod_ui is identical to mpz_fdiv_r_ui above, returning the remainder as well as setting r. See mpz_fdiv_ui above if only the return value is wanted.

Function: void mpz_divexact (mpz_t q, mpz_t n, mpz_t d)
Function: void mpz_divexact_ui (mpz_t q, mpz_t n, unsigned long d)
Set q to n/d. These functions produce correct results only when it is known in advance that d divides n.

These routines are much faster than the other division functions, and are the best choice when exact division is known to occur, for example reducing a rational to lowest terms.

Function: int mpz_divisible_p (mpz_t n, mpz_t d)
Function: int mpz_divisible_ui_p (mpz_t n, unsigned long int d)
Function: int mpz_divisible_2exp_p (mpz_t n, unsigned long int b)
Return non-zero if n is exactly divisible by d, or in the case of mpz_divisible_2exp_p by 2^b.

Function: int mpz_congruent_p (mpz_t n, mpz_t c, mpz_t d)
Function: int mpz_congruent_ui_p (mpz_t n, unsigned long int c, unsigned long int d)
Function: int mpz_congruent_2exp_p (mpz_t n, mpz_t c, unsigned long int b)
Return non-zero if n is congruent to c modulo d, or in the case of mpz_congruent_2exp_p modulo 2^b.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.7 Exponentiation Functions

Function: void mpz_powm (mpz_t rop, mpz_t base, mpz_t exp, mpz_t mod)
Function: void mpz_powm_ui (mpz_t rop, mpz_t base, unsigned long int exp, mpz_t mod)
Set rop to \N\ \bmod mod, (base raised to exp) modulo mod}.

Negative exp is supported if an inverse base^-1 mod mod exists (see mpz_invert in 5.9 Number Theoretic Functions). If an inverse doesn't exist then a divide by zero is raised.

Function: void mpz_pow_ui (mpz_t rop, mpz_t base, unsigned long int exp)
Function: void mpz_ui_pow_ui (mpz_t rop, unsigned long int base, unsigned long int exp)
Set rop to \N\, base raised to exp}. The case 0^0 yields 1.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.8 Root Extraction Functions

Function: int mpz_root (mpz_t rop, mpz_t op, unsigned long int n)
Set rop to \N\\rfloor, the truncated integer part of the nth root of op. Return non-zero if the computation was exact, i.e., if op is rop to the nth power.

Function: void mpz_sqrt (mpz_t rop, mpz_t op)
Set rop to \N\}\rfloor, the truncated integer part of the square root of op.

Function: void mpz_sqrtrem (mpz_t rop1, mpz_t rop2, mpz_t op)
Set rop1 to \N\}\rfloor, the truncated integer part of the square root of op}, like mpz_sqrt. Set rop2 to the remainder \N\ - rop1^2), op-rop1*rop1}, which will be zero if op is a perfect square.

If rop1 and rop2 are the same variable, the results are undefined.

Function: int mpz_perfect_power_p (mpz_t op)
Return non-zero if op is a perfect power, i.e., if there exist integers a and b, with b>1, such that \N\=a^b, op equals a raised to the power b}.

Under this definition both 0 and 1 are considered to be perfect powers. Negative values of op are accepted, but of course can only be odd perfect powers.

Function: int mpz_perfect_square_p (mpz_t op)
Return non-zero if op is a perfect square, i.e., if the square root of op is an integer. Under this definition both 0 and 1 are considered to be perfect squares.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.9 Number Theoretic Functions

Function: int mpz_probab_prime_p (mpz_t n, int reps)
Determine whether n is prime. Return 2 if n is definitely prime, return 1 if n is probably prime (without being certain), or return 0 if n is definitely composite.

This function does some trial divisions, then some Miller-Rabin probabilistic primality tests. reps controls how many such tests are done, 5 to 10 is a reasonable number, more will reduce the chances of a composite being returned as "probably prime".

Miller-Rabin and similar tests can be more properly called compositeness tests. Numbers which fail are known to be composite but those which pass might be prime or might be composite. Only a few composites pass, hence those which pass are considered probably prime.

Function: void mpz_nextprime (mpz_t rop, mpz_t op)
Set rop to the next prime greater than op.

This function uses a probabilistic algorithm to identify primes. For practical purposes it's adequate, the chance of a composite passing will be extremely small.

Function: void mpz_gcd (mpz_t rop, mpz_t op1, mpz_t op2)
Set rop to the greatest common divisor of op1 and op2. The result is always positive even if one or both input operands are negative.

Function: unsigned long int mpz_gcd_ui (mpz_t rop, mpz_t op1, unsigned long int op2)
Compute the greatest common divisor of op1 and op2. If rop is not NULL, store the result there.

If the result is small enough to fit in an unsigned long int, it is returned. If the result does not fit, 0 is returned, and the result is equal to the argument op1. Note that the result will always fit if op2 is non-zero.

Function: void mpz_gcdext (mpz_t g, mpz_t s, mpz_t t, mpz_t a, mpz_t b)
Compute g, s, and t, such that a* + b* = g = gcd, b). If t is NULL, that argument is not computed.

Function: void mpz_lcm (mpz_t rop, mpz_t op1, mpz_t op2)
Function: void mpz_lcm_ui (mpz_t rop, mpz_t op1, unsigned long op2)
Set rop to the least common multiple of op1 and op2. rop is always positive, irrespective of the signs of op1 and op2. rop will be zero if either op1 or op2 is zero.

Function: int mpz_invert (mpz_t rop, mpz_t op1, mpz_t op2)
Compute the inverse of op1 modulo op2 and put the result in rop. If the inverse exists, the return value is non-zero and rop will satisfy 0 <= < op2. If an inverse doesn't exist the return value is zero and rop is undefined.

Function: int mpz_jacobi (mpz_t a, mpz_t b)
Calculate the Jacobi symbol \N\{\left(a \over b\right), (a/b)}. This is defined only for b odd.

Function: int mpz_legendre (mpz_t a, mpz_t p)
Calculate the Legendre symbol \N\{\left(a \over p\right), (a/p)}. This is defined only for p an odd positive prime, and for such p it's identical to the Jacobi symbol.

Function: int mpz_kronecker (mpz_t a, mpz_t b)
Function: int mpz_kronecker_si (mpz_t a, long b)
Function: int mpz_kronecker_ui (mpz_t a, unsigned long b)
Function: int mpz_si_kronecker (long a, mpz_t b)
Function: int mpz_ui_kronecker (unsigned long a, mpz_t b)
Calculate the Jacobi symbol \N\{\left(a \over b\right), (a/b)} with the Kronecker extension \N\{\left(a \over 2\right) = \left(2 \over a\right), (a/2)=(2/a)} when a odd, or (a/2)=0 when a even.

When b is odd the Jacobi symbol and Kronecker symbol are identical, so mpz_kronecker_ui etc can be used for mixed precision Jacobi symbols too.

For more information see Henri Cohen section 1.4.2 (see section B. References), or any number theory textbook. See also the example program `demos/qcn.c' which uses mpz_kronecker_ui.

Function: unsigned long int mpz_remove (mpz_t rop, mpz_t op, mpz_t f)
Remove all occurrences of the factor f from op and store the result in rop. Return the multiplicity of f in op.

Function: void mpz_fac_ui (mpz_t rop, unsigned long int op)
Set rop to op!, the factorial of op.

Function: void mpz_bin_ui (mpz_t rop, mpz_t n, unsigned long int k)
Function: void mpz_bin_uiui (mpz_t rop, unsigned long int n, unsigned long int k)
Compute the binomial coefficient \N\\atop{k}\right), n over k} and store the result in rop. Negative values of n are supported by mpz_bin_ui, using the identity \N\\atop{k}\right) = (-1)^k \left({n+k-1}\atop{k}\right), bin(-n,k)}, see Knuth volume 1 section 1.2.6 part G.

Function: void mpz_fib_ui (mpz_t fn, unsigned long int n)
Function: void mpz_fib2_ui (mpz_t fn, mpz_t fnsub1, unsigned long int n)
mpz_fib_ui sets fn to to F[n], the n'th Fibonacci number. mpz_fib2_ui sets fn to F[n], and fnsub1 to \N\,F[n-1]}.

These functions are designed for calculating isolated Fibonacci numbers. When a sequence of values is wanted it's best to start with mpz_fib2_ui and iterate the defining \N\ = F_n + F_{n-1}, F[n+1]=F[n]+F[n-1]} or similar.

Function: void mpz_lucnum_ui (mpz_t ln, unsigned long int n)
Function: void mpz_lucnum2_ui (mpz_t ln, mpz_t lnsub1, unsigned long int n)
mpz_lucnum_ui sets ln to to L[n], the n'th Lucas number. mpz_lucnum2_ui sets ln to L[n], and lnsub1 to \N\,L[n-1]}.

These functions are designed for calculating isolated Lucas numbers. When a sequence of values is wanted it's best to start with mpz_lucnum2_ui and iterate the defining \N\ = L_n + L_{n-1}, L[n+1]=L[n]+L[n-1]} or similar.

The Fibonacci numbers and Lucas numbers are related sequences, so it's never necessary to call both mpz_fib2_ui and mpz_lucnum2_ui. The formulas for going from Fibonacci to Lucas can be found in 16.7.4 Lucas Numbers, the reverse is straightforward too.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.10 Comparison Functions

Function: int mpz_cmp (mpz_t op1, mpz_t op2)
Function: int mpz_cmp_d (mpz_t op1, double op2)
Macro: int mpz_cmp_si (mpz_t op1, signed long int op2)
Macro: int mpz_cmp_ui (mpz_t op1, unsigned long int op2)
Compare op1 and op2. Return a positive value if op1 > op2, zero if op1 = op2, or a negative value if op1 < op2.

Note that mpz_cmp_ui and mpz_cmp_si are macros and will evaluate their arguments more than once.

Function: int mpz_cmpabs (mpz_t op1, mpz_t op2)
Function: int mpz_cmpabs_d (mpz_t op1, double op2)
Function: int mpz_cmpabs_ui (mpz_t op1, unsigned long int op2)
Compare the absolute values of op1 and op2. Return a positive value if abs > abs, zero if abs = abs, or a negative value if abs < abs.

Note that mpz_cmpabs_si is a macro and will evaluate its arguments more than once.

Macro: int mpz_sgn (mpz_t op)
Return +1 if op > 0, 0 if op = 0, and -1 if op < 0.

This function is actually implemented as a macro. It evaluates its argument multiple times.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.11 Logical and Bit Manipulation Functions

These functions behave as if twos complement arithmetic were used (although sign-magnitude is the actual implementation). The least significant bit is number 0.

Function: void mpz_and (mpz_t rop, mpz_t op1, mpz_t op2)
Set rop to op1 logical-and op2.

Function: void mpz_ior (mpz_t rop, mpz_t op1, mpz_t op2)
Set rop to op1 inclusive-or op2.

Function: void mpz_xor (mpz_t rop, mpz_t op1, mpz_t op2)
Set rop to op1 exclusive-or op2.

Function: void mpz_com (mpz_t rop, mpz_t op)
Set rop to the one's complement of op.

Function: unsigned long int mpz_popcount (mpz_t op)
If op>=, return the population count of op, which is the number of 1 bits in the binary representation. If op<0, the number of 1s is infinite, and the return value is MAX_ULONG, the largest possible unsigned long.

Function: unsigned long int mpz_hamdist (mpz_t op1, mpz_t op2)
If op1 and op2 are both >= or both <0, return the hamming distance between the two operands, which is the number of bit positions where op1 and op2 have different bit values. If one operand is >= and the other <0 then the number of bits different is infinite, and the return value is MAX_ULONG, the largest possible unsigned long.

Function: unsigned long int mpz_scan0 (mpz_t op, unsigned long int starting_bit)
Function: unsigned long int mpz_scan1 (mpz_t op, unsigned long int starting_bit)
Scan op, starting from bit starting_bit, towards more significant bits, until the first 0 or 1 bit (respectively) is found. Return the index of the found bit.

If the bit at starting_bit is already what's sought, then starting_bit is returned.

If there's no bit found, then MAX_ULONG is returned. This will happen in mpz_scan0 past the end of a positive number, or mpz_scan1 past the end of a negative.

Function: void mpz_setbit (mpz_t rop, unsigned long int bit_index)
Set bit bit_index in rop.

Function: void mpz_clrbit (mpz_t rop, unsigned long int bit_index)
Clear bit bit_index in rop.

Function: int mpz_tstbit (mpz_t op, unsigned long int bit_index)
Test bit bit_index in op and return 0 or 1 accordingly.

5.12 Input and Output Functions

Functions that perform input from a stdio stream, and functions that output to a stdio stream. Passing a NULL pointer for a stream argument to any of these functions will make them read from stdin and write to stdout, respectively.

When using any of these functions, it is a good idea to include `stdio.h' before `gmp.h', since that will allow `gmp.h' to define prototypes for these functions.

Function: size_t mpz_out_str (FILE *stream, int base, mpz_t op)
Output op on stdio stream stream, as a string of digits in base base. The base may vary from 2 to 36.

Return the number of bytes written, or if an error occurred, return 0.

Function: size_t mpz_inp_str (mpz_t rop, FILE *stream, int base)
Input a possibly white-space preceded string in base base from stdio stream stream, and put the read integer in rop. The base may vary from 2 to 36. If base is 0, the actual base is determined from the leading characters: if the first two characters are `0x' or `0X', hexadecimal is assumed, otherwise if the first character is `0', octal is assumed, otherwise decimal is assumed.

Return the number of bytes read, or if an error occurred, return 0.

Function: size_t mpz_out_raw (FILE *stream, mpz_t op)
Output op on stdio stream stream, in raw binary format. The integer is written in a portable format, with 4 bytes of size information, and that many bytes of limbs. Both the size and the limbs are written in decreasing significance order (i.e., in big-endian).

The output can be read with mpz_inp_raw.

Return the number of bytes written, or if an error occurred, return 0.

The output of this can not be read by mpz_inp_raw from GMP 1, because of changes necessary for compatibility between 32-bit and 64-bit machines.

Function: size_t mpz_inp_raw (mpz_t rop, FILE *stream)
Input from stdio stream stream in the format written by mpz_out_raw, and put the result in rop. Return the number of bytes read, or if an error occurred, return 0.

This routine can read the output from mpz_out_raw also from GMP 1, in spite of changes necessary for compatibility between 32-bit and 64-bit machines.

5.13 Random Number Functions

The random number functions of GMP come in two groups; older function that rely on a global state, and newer functions that accept a state parameter that is read and modified. Please see the 9. Random Number Functions for more information on how to use and not to use random number functions.

Function: void mpz_urandomb (mpz_t rop, gmp_randstate_t state, unsigned long int n)
Generate a uniformly distributed random integer in the range 0 to \N\{2^n-1, 2^n-1, inclusive.

The variable state must be initialized by calling one of the gmp_randinit functions (9.1 Random State Initialization) before invoking this function.

Function: void mpz_urandomm (mpz_t rop, gmp_randstate_t state, mpz_t n)
Generate a uniform random integer in the range 0 to n-1, inclusive.

The variable state must be initialized by calling one of the gmp_randinit functions (9.1 Random State Initialization) before invoking this function.

Function: void mpz_rrandomb (mpz_t rop, gmp_randstate_t state, unsigned long int n)
Generate a random integer with long strings of zeros and ones in the binary representation. Useful for testing functions and algorithms, since this kind of random numbers have proven to be more likely to trigger corner-case bugs. The random number will be in the range 0 to 2^n-1, inclusive.

The variable state must be initialized by calling one of the gmp_randinit functions (9.1 Random State Initialization) before invoking this function.

Function: void mpz_random (mpz_t rop, mp_size_t max_size)
Generate a random integer of at most max_size limbs. The generated random number doesn't satisfy any particular requirements of randomness. Negative random numbers are generated when max_size is negative.

This function is obsolete. Use mpz_urandomb or mpz_urandomm instead.

Function: void mpz_random2 (mpz_t rop, mp_size_t max_size)
Generate a random integer of at most max_size limbs, with long strings of zeros and ones in the binary representation. Useful for testing functions and algorithms, since this kind of random numbers have proven to be more likely to trigger corner-case bugs. Negative random numbers are generated when max_size is negative.

This function is obsolete. Use mpz_rrandomb instead.

5.14 Miscellaneous Functions

Function: int mpz_fits_ulong_p (mpz_t op)
Function: int mpz_fits_slong_p (mpz_t op)
Function: int mpz_fits_uint_p (mpz_t op)
Function: int mpz_fits_sint_p (mpz_t op)
Function: int mpz_fits_ushort_p (mpz_t op)
Function: int mpz_fits_sshort_p (mpz_t op)
Return non-zero iff the value of op fits in an unsigned long int, signed long int, unsigned int, signed int, unsigned short int, or signed short int, respectively. Otherwise, return zero.

Macro: int mpz_odd_p (mpz_t op)
Macro: int mpz_even_p (mpz_t op)
Determine whether op is odd or even, respectively. Return non-zero if yes, zero if no. These macros evaluate their argument more than once.

Function: size_t mpz_size (mpz_t op)
Return the size of op measured in number of limbs. If op is zero, the returned value will be zero.

Function: size_t mpz_sizeinbase (mpz_t op, int base)
Return the size of op measured in number of digits in base base. The base may vary from 2 to 36. The sign of op is ignored, just the absolute value is used. The returned value will be exact or 1 too big. If base is a power of 2, the returned value will always be exact.

This function is useful in order to allocate the right amount of space before converting op to a string. The right amount of allocation is normally two more than the value returned by mpz_sizeinbase (one extra for a minus sign and one for the null-terminator).

6. Rational Number Functions

This chapter describes the GMP functions for performing arithmetic on rational numbers. These functions start with the prefix mpq_.

Rational numbers are stored in objects of type mpq_t.

All rational arithmetic functions assume operands have a canonical form, and canonicalize their result. The canonical from means that the denominator and the numerator have no common factors, and that the denominator is positive. Zero has the unique representation 0/1.

Pure assignment functions do not canonicalize the assigned variable. It is the responsibility of the user to canonicalize the assigned variable before any arithmetic operations are performed on that variable.

Function: void mpq_canonicalize (mpq_t op)
Remove any factors that are common to the numerator and denominator of op, and make the denominator positive.

6.1 Initialization and Assignment Functions
6.2 Conversion Functions
6.3 Arithmetic Functions
6.4 Comparison Functions
6.5 Applying Integer Functions to Rationals
6.6 Input and Output Functions

6.1 Initialization and Assignment Functions

Function: void mpq_init (mpq_t dest_rational)
Initialize dest_rational and set it to 0/1. Each variable should normally only be initialized once, or at least cleared out (using the function mpq_clear) between each initialization.

Function: void mpq_clear (mpq_t rational_number)
Free the space occupied by rational_number. Make sure to call this function for all mpq_t variables when you are done with them.

Function: void mpq_set (mpq_t rop, mpq_t op)
Function: void mpq_set_z (mpq_t rop, mpz_t op)
Assign rop from op.

Function: void mpq_set_ui (mpq_t rop, unsigned long int op1, unsigned long int op2)
Function: void mpq_set_si (mpq_t rop, signed long int op1, unsigned long int op2)
Set the value of rop to op1/op2. Note that if op1 and op2 have common factors, rop has to be passed to mpq_canonicalize before any operations are performed on rop.

Function: int mpq_set_str (mpq_t rop, char *str, int base)
Set rop from a null-terminated string str in the given base.

The string can be an integer like "41" or a fraction like "41/152". The fraction must be in canonical form (see section 6. Rational Number Functions), or if not then mpq_canonicalize must be called.

The numerator and optional denominator are parsed the same as in mpz_set_str (see section 5.2 Assignment Functions). White space is allowed in the string, and is simply ignored. The base can vary from 2 to 36, or if base is 0 then the leading characters are used: 0x for hex, 0 for octal, or decimal otherwise. Note that this is done separately for the numerator and denominator, so for instance 0xEF/100 is 239/100, whereas 0xEF/0x100 is 239/256.

The return value is 0 if the entire string is a valid number, or -1 if not.

Function: void mpq_swap (mpq_t rop1, mpq_t rop2)
Swap the values rop1 and rop2 efficiently.

6.2 Conversion Functions

Function: double mpq_get_d (mpq_t op)
Convert op to a double.

Function: void mpq_set_d (mpq_t rop, double op)
Function: void mpq_set_f (mpq_t rop, mpf_t op)
Set rop to the value of op, without rounding.

Function: char * mpq_get_str (char *str, int base, mpq_t op)
Convert op to a string of digits in base base. The base may vary from 2 to 36. The string will be of the form `num/den', or if the denominator is 1 then just `num'.

If str is NULL, the result string is allocated using the current allocation function (see section 14. Custom Allocation). The block will be strlen(str)+1 bytes, that being exactly enough for the string and null-terminator.

If str is not NULL, it should point to a block of storage large enough for the result, that being

mpz_sizeinbase (mpq_numref(op), base)
+ mpz_sizeinbase (mpq_denref(op), base) + 3

The three extra bytes are for a possible minus sign, possible slash, and the null-terminator.

A pointer to the result string is returned, being either the allocated block, or the given str.

6.3 Arithmetic Functions

Function: void mpq_add (mpq_t sum, mpq_t addend1, mpq_t addend2)
Set sum to addend1 + addend2.

Function: void mpq_sub (mpq_t difference, mpq_t minuend, mpq_t subtrahend)
Set difference to minuend - subtrahend.

Function: void mpq_mul (mpq_t product, mpq_t multiplier, mpq_t multiplicand)
Set product to multiplier times.

Function: void mpq_mul_2exp (mpq_t rop, mpq_t op1, unsigned long int op2)
Set rop to \N\ \times 2^{op2, op1 times 2 raised to op2.

Function: void mpq_div (mpq_t quotient, mpq_t dividend, mpq_t divisor)
Set quotient to dividend/divisor.

Function: void mpq_div_2exp (mpq_t rop, mpq_t op1, unsigned long int op2)
Set rop to \N\/2^{op2}, op1 divided by 2 raised to op2}.

Function: void mpq_neg (mpq_t negated_operand, mpq_t operand)
Set negated_operand to -operand.

Function: void mpq_abs (mpq_t rop, mpq_t op)
Set rop to the absolute value of op.

Function: void mpq_inv (mpq_t inverted_number, mpq_t number)
Set inverted_number to 1/number. If the new denominator is zero, this routine will divide by zero.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4 Comparison Functions

Function: int mpq_cmp (mpq_t op1, mpq_t op2)
Compare op1 and op2. Return a positive value if op1 > op2, zero if op1 = op2, and a negative value if op1 < op2.

To determine if two rationals are equal, mpq_equal is faster than mpq_cmp.

Macro: int mpq_cmp_ui (mpq_t op1, unsigned long int num2, unsigned long int den2)
Macro: int mpq_cmp_si (mpq_t op1, long int num2, unsigned long int den2)
Compare op1 and num2/den2. Return a positive value if op1 > num2/den2, zero if op1 = num2/den2, and a negative value if op1 < num2/den2.

num2 and den2 are allowed to have common factors.

These functions are implemented as a macros and evaluate their arguments multiple times.

Macro: int mpq_sgn (mpq_t op)
Return +1 if op > 0, 0 if op = 0, and -1 if op < 0.

This function is actually implemented as a macro. It evaluates its arguments multiple times.

Function: int mpq_equal (mpq_t op1, mpq_t op2)
Return non-zero if op1 and op2 are equal, zero if they are non-equal. Although mpq_cmp can be used for the same purpose, this function is much faster.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.5 Applying Integer Functions to Rationals

The set of mpq functions is quite small. In particular, there are few functions for either input or output. The following functions give direct access to the numerator and denominator of an mpq_t.

Note that if an assignment to the numerator and/or denominator could take an mpq_t out of the canonical form described at the start of this chapter (see section 6. Rational Number Functions) then mpq_canonicalize must be called before any other mpq functions are applied to that mpq_t.

Macro: mpz_t mpq_numref (mpq_t op)
Macro: mpz_t mpq_denref (mpq_t op)
Return a reference to the numerator and denominator of op, respectively. The mpz functions can be used on the result of these macros.

Function: void mpq_get_num (mpz_t numerator, mpq_t rational)
Function: void mpq_get_den (mpz_t denominator, mpq_t rational)
Function: void mpq_set_num (mpq_t rational, mpz_t numerator)
Function: void mpq_set_den (mpq_t rational, mpz_t denominator)
Get or set the numerator or denominator of a rational. These functions are equivalent to calling mpz_set with an appropriate mpq_numref or mpq_denref. Direct use of mpq_numref or mpq_denref is recommended instead of these functions.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.6 Input and Output Functions

When using any of these functions, it's a good idea to include `stdio.h' before `gmp.h', since that will allow `gmp.h' to define prototypes for these functions.

Passing a NULL pointer for a stream argument to any of these functions will make them read from stdin and write to stdout, respectively.

Function: size_t mpq_out_str (FILE *stream, int base, mpq_t op)
Output op on stdio stream stream, as a string of digits in base base. The base may vary from 2 to 36. Output is in the form `num/den' or if the denominator is 1 then just `num'.

Return the number of bytes written, or if an error occurred, return 0.

Function: size_t mpq_inp_str (mpq_t rop, FILE *stream, int base)
Read a string of digits from stream and convert them to a rational in rop. Any initial white-space characters are read and discarded. Return the number of characters read (including white space), or 0 if a rational could not be read.

The input can be a fraction like `17/63' or just an integer like `123'. Reading stops at the first character not in this form, and white space is not permitted within the string. If the input might not be in canonical form, then mpq_canonicalize must be called (see section 6. Rational Number Functions).

The base can be between 2 and 36, or can be 0 in which case the leading characters of the string determine the base, `0x' or `0X' for hexadecimal, `0' for octal, or decimal otherwise. The leading characters are examined separately for the numerator and denominator of a fraction, so for instance `0x10/11' is 16/11, whereas `0x10/0x11' is 16/17.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. Floating-point Functions

GMP floating point numbers are stored in objects of type mpf_t and functions operating on them have an mpf_ prefix.

The mantissa of each float has a user-selectable precision, limited only by available memory. Each variable has its own precision, and that can be increased or decreased at any time.

The exponent of each float is a fixed precision, one machine word on most systems. In the current implementation the exponent is a count of limbs, so for example on a 32-bit system this means a range of roughly 2^-68719476768 to 2^68719476736, or on a 64-bit system this will be greater. Note however mpf_get_str can only return an exponent which fits an mp_exp_t and currently mpf_set_str doesn't accept exponents bigger than a long.

Each variable keeps a size for the mantissa data actually in use. This means that if a float is exactly represented in only a few bits then only those bits will be used in a calculation, even if the selected precision is high.

All calculations are performed to the precision of the destination variable. Each function is defined to calculate with "infinite precision" followed by a truncation to the destination precision, but of course the work done is only what's needed to determine a result under that definition.

The precision selected for a variable is a minimum value, GMP may increase it a little to facilitate efficient calculation. Currently this means rounding up to a whole limb, and then sometimes having a further partial limb, depending on the high limb of the mantissa. But applications shouldn't be concerned by such details.

mpf functions and variables have no special notion of infinity or not-a-number, and applications must take care not to overflow the exponent or results will be unpredictable. This might change in a future release.

Note that the mpf functions are not intended as a smooth extension to IEEE P754 arithmetic. In particular results obtained on one computer often differ from the results on a computer with a different word size.

7.1 Initialization Functions
7.2 Assignment Functions
7.3 Combined Initialization and Assignment Functions
7.4 Conversion Functions
7.5 Arithmetic Functions
7.6 Comparison Functions
7.7 Input and Output Functions
7.8 Miscellaneous Functions

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1 Initialization Functions

Function: void mpf_set_default_prec (unsigned long int prec)
Set the default precision to be at least prec bits. All subsequent calls to mpf_init will use this precision, but previously initialized variables are unaffected.

Function: unsigned long int mpf_get_default_prec (void)
Return the default default precision actually used.

An mpf_t object must be initialized before storing the first value in it. The functions mpf_init and mpf_init2 are used for that purpose.

Function: void mpf_init (mpf_t x)
Initialize x to 0. Normally, a variable should be initialized once only or at least be cleared, using mpf_clear, between initializations. The precision of x is undefined unless a default precision has already been established by a call to mpf_set_default_prec.

Function: void mpf_init2 (mpf_t x, unsigned long int prec)
Initialize x to 0 and set its precision to be at least prec bits. Normally, a variable should be initialized once only or at least be cleared, using mpf_clear, between initializations.

Function: void mpf_clear (mpf_t x)
Free the space occupied by x. Make sure to call this function for all mpf_t variables when you are done with them.

Here is an example on how to initialize floating-point variables:
{
  mpf_t x, y;
  mpf_init (x);			/* use default precision */
  mpf_init2 (y, 256);		/* precision at least 256 bits */
  ...
  /* Unless the program is about to exit, do ... */
  mpf_clear (x);
  mpf_clear (y);
}

The following three functions are useful for changing the precision during a calculation. A typical use would be for adjusting the precision gradually in iterative algorithms like Newton-Raphson, making the computation precision closely match the actual accurate part of the numbers.

Function: unsigned long int mpf_get_prec (mpf_t op)
Return the current precision of op, in bits.

Function: void mpf_set_prec (mpf_t rop, unsigned long int prec)
Set the precision of rop to be at least prec bits. The value in rop will be truncated to the new precision.

This function requires a call to realloc, and so should not be used in a tight loop.

Function: void mpf_set_prec_raw (mpf_t rop, unsigned long int prec)
Set the precision of rop to be at least prec bits, without changing the memory allocated.

prec must be no more than the allocated precision for rop, that being the precision when rop was initialized, or in the most recent mpf_set_prec.

The value in rop is unchanged, and in particular if it had a higher precision than prec it will retain that higher precision. New values written to rop will use the new prec.

Before calling mpf_clear or the full mpf_set_prec, another mpf_set_prec_raw call must be made to restore rop to its original allocated precision. Failing to do so will have unpredictable results.

mpf_get_prec can be used before mpf_set_prec_raw to get the original allocated precision. After mpf_set_prec_raw it reflects the prec value set.

mpf_set_prec_raw is an efficient way to use an mpf_t variable at different precisions during a calculation, perhaps to gradually increase precision in an iteration, or just to use various different precisions for different purposes during a calculation.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2 Assignment Functions

These functions assign new values to already initialized floats (see section 7.1 Initialization Functions).

Function: void mpf_set (mpf_t rop, mpf_t op)
Function: void mpf_set_ui (mpf_t rop, unsigned long int op)
Function: void mpf_set_si (mpf_t rop, signed long int op)
Function: void mpf_set_d (mpf_t rop, double op)
Function: void mpf_set_z (mpf_t rop, mpz_t op)
Function: void mpf_set_q (mpf_t rop, mpq_t op)
Set the value of rop from op.

Function: int mpf_set_str (mpf_t rop, char *str, int base)
Set the value of rop from the string in str. The string is of the form `M@N' or, if the base is 10 or less, alternatively `MeN'. `M' is the mantissa and `N' is the exponent. The mantissa is always in the specified base. The exponent is either in the specified base or, if base is negative, in decimal. The decimal point expected is taken from the current locale, on systems providing localeconv.

The argument base may be in the ranges 2 to 36, or -36 to -2. Negative values are used to specify that the exponent is in decimal.

Unlike the corresponding mpz function, the base will not be determined from the leading characters of the string if base is 0. This is so that numbers like `0.23' are not interpreted as octal.

White space is allowed in the string, and is simply ignored. [This is not really true; white-space is ignored in the beginning of the string and within the mantissa, but not in other places, such as after a minus sign or in the exponent. We are considering changing the definition of this function, making it fail when there is any white-space in the input, since that makes a lot of sense. Please tell us your opinion about this change. Do you really want it to accept "3 14" as meaning 314 as it does now?]

This function returns 0 if the entire string is a valid number in base base. Otherwise it returns -1.

Function: void mpf_swap (mpf_t rop1, mpf_t rop2)
Swap rop1 and rop2 efficiently. Both the values and the precisions of the two variables are swapped.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3 Combined Initialization and Assignment Functions

For convenience, GMP provides a parallel series of initialize-and-set functions which initialize the output and then store the value there. These functions' names have the form mpf_init_set...

Once the float has been initialized by any of the mpf_init_set... functions, it can be used as the source or destination operand for the ordinary float functions. Don't use an initialize-and-set function on a variable already initialized!

Function: void mpf_init_set (mpf_t rop, mpf_t op)
Function: void mpf_init_set_ui (mpf_t rop, unsigned long int op)
Function: void mpf_init_set_si (mpf_t rop, signed long int op)
Function: void mpf_init_set_d (mpf_t rop, double op)
Initialize rop and set its value from op.

The precision of rop will be taken from the active default precision, as set by mpf_set_default_prec.

Function: int mpf_init_set_str (mpf_t rop, char *str, int base)
Initialize rop and set its value from the string in str. See mpf_set_str above for details on the assignment operation.

Note that rop is initialized even if an error occurs. (I.e., you have to call mpf_clear for it.)

The precision of rop will be taken from the active default precision, as set by mpf_set_default_prec.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4 Conversion Functions

Function: double mpf_get_d (mpf_t op)
Convert op to a double.

Function: double mpf_get_d_2exp (signed long int exp, mpf_t op)
Find d and exp such that \N\\times 2^{exp}, d times 2 raised to exp}, with 0.5<=<1}, is a good approximation to op. This is similar to the standard C function frexp.

Function: long mpf_get_si (mpf_t op)
Function: unsigned long mpf_get_ui (mpf_t op)
Convert op to a long or unsigned long, truncating any fraction part. If op is too big for the return type, the result is undefined.

See also mpf_fits_slong_p and mpf_fits_ulong_p (see section 7.8 Miscellaneous Functions).

Function: char * mpf_get_str (char *str, mp_exp_t *expptr, int base, size_t n_digits, mpf_t op)
Convert op to a string of digits in base base. base can be 2 to 36. Up to n_digits digits will be generated. Trailing zeros are not returned. No more digits than can be accurately represented by op are ever generated. If n_digits is 0 then that accurate maximum number of digits are generated.

If str is NULL, the result string is allocated using the current allocation function (see section 14. Custom Allocation). The block will be strlen(str)+1 bytes, that being exactly enough for the string and null-terminator.

If str is not NULL, it should point to a block of n\_digits + 2 bytes, that being enough for the mantissa, a possible minus sign, and a null-terminator. When n_digits is 0 to get all significant digits, an application won't be able to know the space required, and str should be NULL in that case.

The generated string is a fraction, with an implicit radix point immediately to the left of the first digit. The applicable exponent is written through the expptr pointer. For example, the number 3.1416 would be returned as string "31416" and exponent 1.

When op is zero, an empty string is produced and the exponent returned is 0.

A pointer to the result string is returned, being either the allocated block or the given str.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5 Arithmetic Functions

Function: void mpf_add (mpf_t rop, mpf_t op1, mpf_t op2)
Function: void mpf_add_ui (mpf_t rop, mpf_t op1, unsigned long int op2)
Set rop to op1 + op2.

Function: void mpf_sub (mpf_t rop, mpf_t op1, mpf_t op2)
Function: void mpf_ui_sub (mpf_t rop, unsigned long int op1, mpf_t op2)
Function: void mpf_sub_ui (mpf_t rop, mpf_t op1, unsigned long int op2)
Set rop to op1 - op2.

Function: void mpf_mul (mpf_t rop, mpf_t op1, mpf_t op2)
Function: void mpf_mul_ui (mpf_t rop, mpf_t op1, unsigned long int op2)
Set rop to op1 times.

Division is undefined if the divisor is zero, and passing a zero divisor to the divide functions will make these functions intentionally divide by zero. This lets the user handle arithmetic exceptions in these functions in the same manner as other arithmetic exceptions.

Function: void mpf_div (mpf_t rop, mpf_t op1, mpf_t op2)
Function: void mpf_ui_div (mpf_t rop, unsigned long int op1, mpf_t op2)
Function: void mpf_div_ui (mpf_t rop, mpf_t op1, unsigned long int op2)
Set rop to op1/op2.

Function: void mpf_sqrt (mpf_t rop, mpf_t op)
Function: void mpf_sqrt_ui (mpf_t rop, unsigned long int op)
Set rop to \N\}, the square root of op}.

Function: void mpf_pow_ui (mpf_t rop, mpf_t op1, unsigned long int op2)
Set rop to \N\^{op2}, op1 raised to the power op2}.

Function: void mpf_neg (mpf_t rop, mpf_t op)
Set rop to -op.

Function: void mpf_abs (mpf_t rop, mpf_t op)
Set rop to the absolute value of op.

Function: void mpf_mul_2exp (mpf_t rop, mpf_t op1, unsigned long int op2)
Set rop to \N\ \times 2^{op2}, op1 times 2 raised to op2}.

Function: void mpf_div_2exp (mpf_t rop, mpf_t op1, unsigned long int op2)
Set rop to \N\/2^{op2}, op1 divided by 2 raised to op2}.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.6 Comparison Functions

Function: int mpf_cmp (mpf_t op1, mpf_t op2)
Function: int mpf_cmp_d (mpf_t op1, double op2)
Function: int mpf_cmp_ui (mpf_t op1, unsigned long int op2)
Function: int mpf_cmp_si (mpf_t op1, signed long int op2)
Compare op1 and op2. Return a positive value if op1 > op2, zero if op1 = op2, and a negative value if op1 < op2.

Function: int mpf_eq (mpf_t op1, mpf_t op2, unsigned long int op3)
Return non-zero if the first op3 bits of op1 and op2 are equal, zero otherwise. I.e., test of op1 and op2 are approximately equal.

Caution: Currently only whole limbs are compared, and only in an exact fashion. In the future values like 1000 and 0111 may be considered the same to 3 bits (on the basis that their difference is that small).

Function: void mpf_reldiff (mpf_t rop, mpf_t op1, mpf_t op2)
Compute the relative difference between op1 and op2 and store the result in rop. This is abs/op1}.

Macro: int mpf_sgn (mpf_t op)
Return +1 if op > 0, 0 if op = 0, and -1 if op < 0.

This function is actually implemented as a macro. It evaluates its arguments multiple times.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.7 Input and Output Functions

Functions that perform input from a stdio stream, and functions that output to a stdio stream. Passing a NULL pointer for a stream argument to any of these functions will make them read from stdin and write to stdout, respectively.

When using any of these functions, it is a good idea to include `stdio.h' before `gmp.h', since that will allow `gmp.h' to define prototypes for these functions.

Function: size_t mpf_out_str (FILE *stream, int base, size_t n_digits, mpf_t op)
Print op to stream, as a string of digits. Return the number of bytes written, or if an error occurred, return 0.

The mantissa is prefixed with an `0.' and is in the given base, which may vary from 2 to 36. An exponent then printed, separated by an `e', or if base is greater than 10 then by an `@'. The exponent is always in decimal. The decimal point follows the current locale, on systems providing localeconv.

Up to n_digits will be printed from the mantissa, except that no more digits than are accurately representable by op will be printed. n_digits can be 0 to select that accurate maximum.

Function: size_t mpf_inp_str (mpf_t rop, FILE *stream, int base)
Read a string in base base from stream, and put the read float in rop. The string is of the form `M@N' or, if the base is 10 or less, alternatively `MeN'. `M' is the mantissa and `N' is the exponent. The mantissa is always in the specified base. The exponent is either in the specified base or, if base is negative, in decimal. The decimal point expected is taken from the current locale, on systems providing localeconv.

The argument base may be in the ranges 2 to 36, or -36 to -2. Negative values are used to specify that the exponent is in decimal.

Unlike the corresponding mpz function, the base will not be determined from the leading characters of the string if base is 0. This is so that numbers like `0.23' are not interpreted as octal.

Return the number of bytes read, or if an error occurred, return 0.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.8 Miscellaneous Functions

Function: void mpf_ceil (mpf_t rop, mpf_t op)
Function: void mpf_floor (mpf_t rop, mpf_t op)
Function: void mpf_trunc (mpf_t rop, mpf_t op)
Set rop to op rounded to an integer. mpf_ceil rounds to the next higher integer, mpf_floor to the next lower, and mpf_trunc to the integer towards zero.

Function: int mpf_integer_p (mpf_t op)
Return non-zero if op is an integer.

Function: int mpf_fits_ulong_p (mpf_t op)
Function: int mpf_fits_slong_p (mpf_t op)
Function: int mpf_fits_uint_p (mpf_t op)
Function: int mpf_fits_sint_p (mpf_t op)
Function: int mpf_fits_ushort_p (mpf_t op)
Function: int mpf_fits_sshort_p (mpf_t op)
Return non-zero if op would fit in the respective C data type, when truncated to an integer.

Function: void mpf_urandomb (mpf_t rop, gmp_randstate_t state, unsigned long int nbits)
Generate a uniformly distributed random float in rop, such that {0 <= < 1}, with nbits significant bits in the mantissa.

The variable state must be initialized by calling one of the gmp_randinit functions (9.1 Random State Initialization) before invoking this function.

Function: void mpf_random2 (mpf_t rop, mp_size_t max_size, mp_exp_t exp)
Generate a random float of at most max_size limbs, with long strings of zeros and ones in the binary representation. The exponent of the number is in the interval -exp to exp. This function is useful for testing functions and algorithms, since this kind of random numbers have proven to be more likely to trigger corner-case bugs. Negative random numbers are generated when max_size is negative.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. Low-level Functions

This chapter describes low-level GMP functions, used to implement the high-level GMP functions, but also intended for time-critical user code.

These functions start with the prefix mpn_.

The mpn functions are designed to be as fast as possible, not to provide a coherent calling interface. The different functions have somewhat similar interfaces, but there are variations that make them hard to use. These functions do as little as possible apart from the real multiple precision computation, so that no time is spent on things that not all callers need.

A source operand is specified by a pointer to the least significant limb and a limb count. A destination operand is specified by just a pointer. It is the responsibility of the caller to ensure that the destination has enough space for storing the result.

With this way of specifying operands, it is possible to perform computations on subranges of an argument, and store the result into a subrange of a destination.

A common requirement for all functions is that each source area needs at least one limb. No size argument may be zero. Unless otherwise stated, in-place operations are allowed where source and destination are the same, but not where they only partly overlap.

The mpn functions are the base for the implementation of the mpz_, mpf_, and mpq_ functions.

This example adds the number beginning at s1p and the number beginning at s2p and writes the sum at destp. All areas have n limbs.

cy = mpn_add_n (destp, s1p, s2p, n)

In the notation used here, a source operand is identified by the pointer to the least significant limb, and the limb count in braces. For example, {s1p, s1n}.

Function: mp_limb_t mpn_add_n (mp_limb_t *rp, const mp_limb_t *s1p, const mp_limb_t *s2p, mp_size_t n)
Add {s1p, n} and {s2p, n}, and write the n least significant limbs of the result to rp. Return carry, either 0 or 1.

This is the lowest-level function for addition. It is the preferred function for addition, since it is written in assembly for most CPUs. For addition of a variable to itself (i.e., s1p equals s2p, use mpn_lshift with a count of 1 for optimal speed.

Function: mp_limb_t mpn_add_1 (mp_limb_t *rp, const mp_limb_t *s1p, mp_size_t n, mp_limb_t s2limb)
Add {s1p, n} and s2limb, and write the n least significant limbs of the result to rp. Return carry, either 0 or 1.

Function: mp_limb_t mpn_add (mp_limb_t *rp, const mp_limb_t *s1p, mp_size_t s1n, const mp_limb_t *s2p, mp_size_t s2n)
Add {s1p, s1n} and {s2p, s2n}, and write the s1n least significant limbs of the result to rp. Return carry, either 0 or 1.

This function requires that s1n is greater than or equal to s2n.

Function: mp_limb_t mpn_sub_n (mp_limb_t *rp, const mp_limb_t *s1p, const mp_limb_t *s2p, mp_size_t n)
Subtract {s2p, n} from {s1p, n}, and write the n least significant limbs of the result to rp. Return borrow, either 0 or 1.

This is the lowest-level function for subtraction. It is the preferred function for subtraction, since it is written in assembly for most CPUs.

Function: mp_limb_t mpn_sub_1 (mp_limb_t *rp, const mp_limb_t *s1p, mp_size_t n, mp_limb_t s2limb)
Subtract s2limb from {s1p, n}, and write the n least significant limbs of the result to rp. Return borrow, either 0 or 1.

Function: mp_limb_t mpn_sub (mp_limb_t *rp, const mp_limb_t *s1p, mp_size_t s1n, const mp_limb_t *s2p, mp_size_t s2n)
Subtract {s2p, s2n} from {s1p, s1n}, and write the s1n least significant limbs of the result to rp. Return borrow, either 0 or 1.

This function requires that s1n is greater than or equal to s2n.

Function: void mpn_mul_n (mp_limb_t *rp, const mp_limb_t *s1p, const mp_limb_t *s2p, mp_size_t n)
Multiply {s1p, n} and {s2p, n}, and write the 2*n-limb result to rp.

The destination has to have space for 2*n limbs, even if the product's most significant limb is zero.

Function: mp_limb_t mpn_mul_1 (mp_limb_t *rp, const mp_limb_t *s1p, mp_size_t n, mp_limb_t s2limb)
Multiply {s1p, n} by s2limb, and write the n least significant limbs of the product to rp. Return the most significant limb of the product. {s1p, n} and {rp, n} are allowed to overlap provided rp <=.

This is a low-level function that is a building block for general multiplication as well as other operations in GMP. It is written in assembly for most CPUs.

Don't call this function if s2limb is a power of 2; use mpn_lshift with a count equal to the logarithm of s2limb instead, for optimal speed.

Function: mp_limb_t mpn_addmul_1 (mp_limb_t *rp, const mp_limb_t *s1p, mp_size_t n, mp_limb_t s2limb)
Multiply {s1p, n} and s2limb, and add the n least significant limbs of the product to {rp, n} and write the result to rp. Return the most significant limb of the product, plus carry-out from the addition.

This is a low-level function that is a building block for general multiplication as well as other operations in GMP. It is written in assembly for most CPUs.

Function: mp_limb_t mpn_submul_1 (mp_limb_t *rp, const mp_limb_t *s1p, mp_size_t n, mp_limb_t s2limb)
Multiply {s1p, n} and s2limb, and subtract the n least significant limbs of the product from {rp, n} and write the result to rp. Return the most significant limb of the product, minus borrow-out from the subtraction.

This is a low-level function that is a building block for general multiplication and division as well as other operations in GMP. It is written in assembly for most CPUs.

Function: mp_limb_t mpn_mul (mp_limb_t *rp, const mp_limb_t *s1p, mp_size_t s1n, const mp_limb_t *s2p, mp_size_t s2n)
Multiply {s1p, s1n} and {s2p, s2n}, and write the result to rp. Return the most significant limb of the result.

The destination has to have space for s1n + s2n limbs, even if the result might be one limb smaller.

This function requires that s1n is greater than or equal to s2n. The destination must be distinct from both input operands.

Function: void mpn_tdiv_qr (mp_limb_t *qp, mp_limb_t *rp, mp_size_t qxn, const mp_limb_t *np, mp_size_t nn, const mp_limb_t *dp, mp_size_t dn)
Divide {np, nn} by {dp, dn} and put the quotient at {qp, nn-dn+1} and the remainder at {rp, dn}. The quotient is rounded towards 0.

No overlap is permitted between arguments. nn must be greater than or equal to dn. The most significant limb of dp must be non-zero. The qxn operand must be zero.

Function: mp_limb_t mpn_divrem (mp_limb_t *r1p, mp_size_t qxn, mp_limb_t *rs2p, mp_size_t rs2n, const mp_limb_t *s3p, mp_size_t s3n)
[This function is obsolete. Please call mpn_tdiv_qr instead for best performance.]

Divide {rs2p, rs2n} by {s3p, s3n}, and write the quotient at r1p, with the exception of the most significant limb, which is returned. The remainder replaces the dividend at rs2p; it will be s3n limbs long (i.e., as many limbs as the divisor).

In addition to an integer quotient, qxn fraction limbs are developed, and stored after the integral limbs. For most usages, qxn will be zero.

It is required that rs2n is greater than or equal to s3n. It is required that the most significant bit of the divisor is set.

If the quotient is not needed, pass rs2p + s3n as r1p. Aside from that special case, no overlap between arguments is permitted.

Return the most significant limb of the quotient, either 0 or 1.

The area at r1p needs to be rs2n - s3n + qxn limbs large.

Function: mp_limb_t mpn_divrem_1 (mp_limb_t *r1p, mp_size_t qxn, mp_limb_t *s2p, mp_size_t s2n, mp_limb_t s3limb)
Macro: mp_limb_t mpn_divmod_1 (mp_limb_t *r1p, mp_limb_t *s2p, mp_size_t s2n, mp_limb_t s3limb)
Divide {s2p, s2n} by s3limb, and write the quotient at r1p. Return the remainder.

The integer quotient is written to {r1p+qxn, s2n} and in addition qxn fraction limbs are developed and written to {r1p, qxn}. Either or both s2n and qxn can be zero. For most usages, qxn will be zero.

mpn_divmod_1 exists for upward source compatibility and is simply a macro calling mpn_divrem_1 with a qxn of 0.

The areas at r1p and s2p have to be identical or completely separate, not partially overlapping.

Function: mp_limb_t mpn_divmod (mp_limb_t *r1p, mp_limb_t *rs2p, mp_size_t rs2n, const mp_limb_t *s3p, mp_size_t s3n)
[This function is obsolete. Please call mpn_tdiv_qr instead for best performance.]

Macro: mp_limb_t mpn_divexact_by3 (mp_limb_t *rp, mp_limb_t *sp, mp_size_t n)
Function: mp_limb_t mpn_divexact_by3c (mp_limb_t *rp, mp_limb_t *sp, mp_size_t n, mp_limb_t carry)
Divide {sp, n} by 3, expecting it to divide exactly, and writing the result to {rp, n}. If 3 divides exactly, the return value is zero and the result is the quotient. If not, the return value is non-zero and the result won't be anything useful.

mpn_divexact_by3c takes an initial carry parameter, which can be the return value from a previous call, so a large calculation can be done piece by piece from low to high. mpn_divexact_by3 is simply a macro calling mpn_divexact_by3c with a 0 carry parameter.

These routines use a multiply-by-inverse and will be faster than mpn_divrem_1 on CPUs with fast multiplication but slow division.

The source a, result q, size n, initial carry i, and return value c satisfy c*b^n + a-i = 3*q, where \N\}, b=2^mp_bits_per_limb}. The return c is always 0, 1 or 2, and the initial carry i must also be 0, 1 or 2 (these are both borrows really). When c=0 clearly q=(a-i)/3. When c!=0, the remainder (a-i) mod is given by 3-c, because b == 1 mod (when mp_bits_per_limb is even, which is always so currently).

Function: mp_limb_t mpn_mod_1 (mp_limb_t *s1p, mp_size_t s1n, mp_limb_t s2limb)
Divide {s1p, s1n} by s2limb, and return the remainder. s1n can be zero.

Function: mp_limb_t mpn_bdivmod (mp_limb_t *rp, mp_limb_t *s1p, mp_size_t s1n, const mp_limb_t *s2p, mp_size_t s2n, unsigned long int d)
This function puts the low floor(d)/mp\_bits\_per\_limb limbs of q = {s1p, s1n}/{s2p, s2n} mod 2^d at rp, and returns the high d mod mp_bits_per_limb bits of q.

{s1p, s1n} - q * {s2p, s2n} mod \N\{2 \GMPraise{s1n*mp\_bits\_per\_limb, 2^(s1n*mp\_bits\_per\_limb) is placed at s1p. Since the low floor(d)/mp\_bits\_per\_limb limbs of this difference are zero, it is possible to overwrite the low limbs at s1p with this difference, provided rp <=.

This function requires that s1n * mp\_bits\_per\_limb >=, and that {s2p, s2n} is odd.

This interface is preliminary. It might change incompatibly in future revisions.

Function: mp_limb_t mpn_lshift (mp_limb_t *rp, const mp_limb_t *sp, mp_size_t n, unsigned int count)
Shift {sp, n} left by count bits, and write the result to {rp, n}. The bits shifted out at the left are returned in the least significant count bits of the return value (the rest of the return value is zero).

count must be in the range 1 to mp_bits_per_limb-1. The regions {sp, n} and {rp, n} may overlap, provided rp >=.

This function is written in assembly for most CPUs.

Function: mp_limb_t mpn_rshift (mp_limb_t *rp, const mp_limb_t *sp, mp_size_t n, unsigned int count)
Shift {sp, n} right by count bits, and write the result to {rp, n}. The bits shifted out at the right are returned in the most significant count bits of the return value (the rest of the return value is zero).

count must be in the range 1 to mp_bits_per_limb-1. The regions {sp, n} and {rp, n} may overlap, provided rp <=.

This function is written in assembly for most CPUs.

Function: int mpn_cmp (const mp_limb_t *s1p, const mp_limb_t *s2p, mp_size_t n)
Compare {s1p, n} and {s2p, n} and return a positive value if s1 > s2, 0 if they are equal, or a negative value if s1 < s2.

Function: mp_size_t mpn_gcd (mp_limb_t *rp, mp_limb_t *s1p, mp_size_t s1n, mp_limb_t *s2p, mp_size_t s2n)
Set {rp, retval} to the greatest common divisor of {s1p, s1n} and {s2p, s2n}. The result can be up to s2n limbs, the return value is the actual number produced. Both source operands are destroyed.

{s1p, s1n} must have at least as many bits as {s2p, s2n}. {s2p, s2n} must be odd. Both operands must have non-zero most significant limbs.

Function: mp_limb_t mpn_gcd_1 (const mp_limb_t *s1p, mp_size_t s1n, mp_limb_t s2limb)
Return the greatest common divisor of {s1p, s1n} and s2limb. Both operands must be non-zero.

Function: mp_size_t mpn_gcdext (mp_limb_t *r1p, mp_limb_t *r2p, mp_size_t *r2n, mp_limb_t *s1p, mp_size_t s1n, mp_limb_t *s2p, mp_size_t s2n)
Calculate the greatest common divisor of {s1p, s1n} and {s2p, s2n}. Store the gcd at {r1p, retval} and the first cofactor at {r2p, *r2n}, with *r2n negative if the cofactor is negative. r1p and r2p should each have room for s1n+1 limbs, but the return value and value stored through r2n indicate the actual number produced.

{s1p, s1n} >=, s2n} is required, and both must be non-zero. The regions {s1p, s1n+1} and {s2p, s2n+1} are destroyed (i.e. the operands plus an extra limb past the end of each).

The cofactor r1 will satisfy r2*s1 + k*s2 = r1. The second cofactor k is not calculated but can easily be obtained from (r1 - r2*s1) / s2.

Function: mp_size_t mpn_sqrtrem (mp_limb_t *r1p, mp_limb_t *r2p, const mp_limb_t *sp, mp_size_t n)
Compute the square root of {sp, n} and put the result at {r1p, ceil(n)/2} and the remainder at {r2p, retval}. r2p needs space for n limbs, but the return value indicates how many are produced.

The most significant limb of {sp, n} must be non-zero. The areas {r1p, ceil(n)/2} and {sp, n} must be completely separate. The areas {r2p, n} and {sp, n} must be either identical or completely separate.

If the remainder is not wanted then r2p can be NULL, and in this case the return value is zero or non-zero according to whether the remainder would have been zero or non-zero.

A return value of zero indicates a perfect square. See also mpz_perfect_square_p.

Function: mp_size_t mpn_get_str (unsigned char *str, int base, mp_limb_t *s1p, mp_size_t s1n)
Convert {s1p, s1n} to a raw unsigned char array at str in base base, and return the number of characters produced. There may be leading zeros in the string. The string is not in ASCII; to convert it to printable format, add the ASCII codes for `0' or `A', depending on the base and range.

The most significant limb of the input {s1p, s1n} must be non-zero. The area {s1p, s1n+1} is clobbered.

The area at str has to have space for the largest possible number represented by a s1n long limb array, plus one extra character.

Function: mp_size_t mpn_set_str (mp_limb_t *r1p, const char *str, size_t strsize, int base)
Convert the raw unsigned char array at str of length strsize to a limb array. The base of str is base. strsize must be at least 1.

Return the number of limbs stored in r1p.

Function: unsigned long int mpn_scan0 (const mp_limb_t *s1p, unsigned long int bit)
Scan s1p from bit position bit for the next clear bit.

It is required that there be a clear bit within the area at s1p at or beyond bit position bit, so that the function has something to return.

Function: unsigned long int mpn_scan1 (const mp_limb_t *s1p, unsigned long int bit)
Scan s1p from bit position bit for the next set bit.

It is required that there be a set bit within the area at s1p at or beyond bit position bit, so that the function has something to return.

Function: void mpn_random (mp_limb_t *r1p, mp_size_t r1n)
Function: void mpn_random2 (mp_limb_t *r1p, mp_size_t r1n)
Generate a random number of length r1n and store it at r1p. The most significant limb is always non-zero. mpn_random generates uniformly distributed limb data, mpn_random2 generates long strings of zeros and ones in the binary representation.

mpn_random2 is intended for testing the correctness of the mpn routines.

Function: unsigned long int mpn_popcount (const mp_limb_t *s1p, mp_size_t n)
Count the number of set bits in {s1p, n}.

Function: unsigned long int mpn_hamdist (const mp_limb_t *s1p, const mp_limb_t *s2p, mp_size_t n)
Compute the hamming distance between {s1p, n} and {s2p, n}.

Function: int mpn_perfect_square_p (const mp_limb_t *s1p, mp_size_t n)
Return non-zero iff {s1p, n} is a perfect square.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. Random Number Functions

Sequences of pseudo-random numbers in GMP are generated using a variable of type gmp_randstate_t, which holds an algorithm selection and a current state. Such a variable must be initialized by a call to one of the gmp_randinit functions, and can be seeded with one of the gmp_randseed functions.

The functions actually generating random numbers are described in 5.13 Random Number Functions, and 7.8 Miscellaneous Functions.

The older style random number functions don't accept a gmp_randstate_t parameter but instead share a global variable of that type. They use a default algorithm and are currently not seeded (though perhaps that will change in the future). The new functions accepting a gmp_randstate_t are recommended for applications that care about randomness.

9.1 Random State Initialization
9.2 Random State Seeding

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1 Random State Initialization

Function: void gmp_randinit_default (gmp_randstate_t state)
Initialize state with a default algorithm. This will be a compromise between speed and randomness, and is recommended for applications with no special requirements.

Function: void gmp_randinit_lc_2exp (gmp_randstate_t state, mpz_t a, unsigned long c, unsigned long m2exp)
Initialize state with a linear congruential algorithm \N\X + c) mod 2^{m2exp}, X = (a*X + c) mod 2^m2exp}.

The low bits of X in this algorithm are not very random. The least significant bit will have a period no more than 2, and the second bit no more than 4, etc. For this reason only the high half of each X is actually used.

When a random number of more than m2exp/2 bits is to be generated, multiple iterations of the recurrence are used and the results concatenated.

Function: int gmp_randinit_lc_2exp_size (gmp_randstate_t state, unsigned long size)
Initialize state for a linear congruential algorithm as per gmp_randinit_lc_2exp. a, c and m2exp are selected from a table, chosen so that size bits (or more) of each X will be used, ie. m2exp >=/2.

If successful the return value is non-zero. If size is bigger than the table data provides then the return value is zero. The maximum size currently supported is 128.

Function: void gmp_randinit (gmp_randstate_t state, gmp_randalg_t alg, ...)
This function is obsolete.

Initialize state with an algorithm selected by alg. The only choice is GMP_RAND_ALG_LC, which is gmp_randinit_lc_2exp_size. A third parameter of type unsigned long is required, this is the size for that function. GMP_RAND_ALG_DEFAULT or 0 are the same as GMP_RAND_ALG_LC.

gmp_randinit sets bits in gmp_errno to indicate an error. GMP_ERROR_UNSUPPORTED_ARGUMENT if alg is unsupported, or GMP_ERROR_INVALID_ARGUMENT if the size parameter is too big.

Function: void gmp_randclear (gmp_randstate_t state)
Free all memory occupied by state.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.2 Random State Seeding

Function: void gmp_randseed (gmp_randstate_t state, mpz_t seed)
Function: void gmp_randseed_ui (gmp_randstate_t state, unsigned long int seed)
Set an initial seed value into state.

The size of a seed determines how many different sequences of random numbers that it's possible to generate. The "quality" of the seed is the randomness of a given seed compared to the previous seed used, and this affects the randomness of separate number sequences. The method for choosing a seed is critical if the generated numbers are to be used for important applications, such as generating cryptographic keys.

Traditionally the system time has been used to seed, but care needs to be taken with this. If an application seeds often and the resolution of the system clock is low, then the same sequence of numbers might be repeated. Also, the system time is quite easy to guess, so if unpredictability is required then it should definitely not be the only source for the seed value. On some systems there's a special device `/dev/random' which provides random data better suited for use as a seed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10. Formatted Output

10.1 Format Strings
10.2 Functions
10.3 C++ Formatted Output

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.1 Format Strings

gmp_printf and friends accept format strings similar to the standard C printf (see section `Formatted Output' in The GNU C Library Reference Manual). A format specification is of the form

% [flags] [width] [.[precision]] [type] conv

GMP adds types `Z', `Q' and `F' for mpz_t, mpq_t and mpf_t respectively. `Z' and `Q' behave like integers. `Q' will print a `/' and a denominator, if needed. `F' behaves like a float. For example,

mpz_t z;
gmp_printf ("%s is an mpz %Zd\n", "here", z);

mpq_t q;
gmp_printf ("a hex rational: %#40Qx\n", q);

mpf_t f;
int   n;
gmp_printf ("fixed point mpf %.*Ff with %d digits\n", n, f, n);

All the standard C printf types behave the same as the C library printf, and can be freely intermixed with the GMP extensions. In the current implementation the standard parts of the format string are simply handed to printf and only the GMP extensions handled directly.

The flags accepted are as follows. GLIBC style `'' (see section `Locales and Internationalization' in The GNU C Library Reference Manual) is only for the standard C types (not the GMP types), and only if the C library supports it.

0 | pad with zeros (rather than spaces)
# show the base with `0x', `0X' or `0'
+ always show a sign
(space) | show a space or a `-' sign
' group digits, GLIBC style (not GMP types)

The standard types accepted are as follows. `h' and `l' are portable, the rest will depend on the compiler (or include files) for the type and the C library for the output.

h | short
hh | char
j | intmax_t or uintmax_t
l | long or wchar_t
ll | same as L
L | long long or long double
q | quad_t or u_quad_t
t | ptrdiff_t
z | size_t

The GMP types are

F | mpf_t, float conversions
Q | mpq_t, integer conversions
Z | mpz_t, integer conversions

The conversions accepted are as follows. `a' and `A' are always supported for mpf_t but depend on the C library for standard C float types. `m' and `p' depend on the C library.

a A | hex floats, GLIBC style
c | character
d | decimal integer
e E | scientific format float
f | fixed point float
i | same as d
g G | fixed or scientific float
m | strerror string, GLIBC style
n | characters written so far
o | octal integer
p | pointer
s | string
u | unsigned integer
x X | hex integer

`o', `x' and `X' are unsigned for the standard C types, but for `Z' and `Q' a sign is included. `u' is not meaningful for Z and Q.

`n' can be used with any of the types, even the GMP types.

Other types or conversions that might be accepted by the C library printf cannot be used through gmp_printf, this includes for instance extensions registered with GLIBC register_printf_function. Also currently there's no support for POSIX `$' style numbered arguments (perhaps this will be added in the future).

The precision field has it's usual meaning for integer `Z' and float `F' types, but is currently undefined for `Q' and should not be used with that.

mpf_t conversions only ever generate as many digits as can be accurately represented by the operand, the same as mpf_get_str does. Zeros will be used if necessary to pad to the requested precision. This happens even for an `f' conversion of an mpf_t which is an integer, for instance 2^1024 in an mpf_t of 128 bits precision will only produce about 20 digits, then pad with zeros to the decimal point. An empty precision field like `%.Fe' or `%.Ff' can be used to specifically request all significant digits.

The decimal point character (or string) is taken from the current locale settings on systems which provide localeconv (see section `Locales and Internationalization' in The GNU C Library Reference Manual). The C library will normally do the same for standard float output.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.2 Functions

Each of the following functions is similar to the corresponding C library function. The basic printf forms take a variable argument list. The vprintf forms take an argument pointer, see section `Variadic Functions' in The GNU C Library Reference Manual, or `man 3 va_start'.

It should be emphasised that if a format string is invalid, or the arguments don't match what the format specifies, then the behaviour of any of these functions will be unpredictable. GCC format string checking is not available, since it doesn't recognise the GMP extensions.

The file based functions gmp_printf and gmp_fprintf will return -1 to indicate a write error. All the functions can return -1 if the C library printf variant in use returns -1, but this shouldn't normally occur.

Function: int gmp_printf (const char *fmt, ...)
Function: int gmp_vprintf (const char *fmt, va_list ap)
Print to the standard output stdout. Return the number of characters written, or -1 if an error occurred.

Function: int gmp_fprintf (FILE *fp, const char *fmt, ...)
Function: int gmp_vfprintf (FILE *fp, const char *fmt, va_list ap)
Print to the stream fp. Return the number of characters written, or -1 if an error occurred.

Function: int gmp_sprintf (char *buf, const char *fmt, ...)
Function: int gmp_vsprintf (char *buf, const char *fmt, va_list ap)
Form a null-terminated string in buf. Return the number of characters written, excluding the terminating null.

No overlap is permitted between the space at buf and the string fmt.

These functions are not recommended, since there's no protection against exceeding the space available at buf.

Function: int gmp_snprintf (char *buf, size_t size, const char *fmt, ...)
Function: int gmp_vsnprintf (char *buf, size_t size, const char *fmt, va_list ap)
Form a null-terminated string in buf. No more than size bytes will be written. To get the full output, size must be enough for the string and null-terminator.

The return value is the total number of characters which ought to have been produced, excluding the terminating null. If retval >= size then the actual output has been truncated to the first size-1 characters, and a null appended.

No overlap is permitted between the region {buf,size} and the fmt string.

Notice the return value is in ISO C99 snprintf style. This is so even if the C library vsnprintf is the older GLIBC 2.0.x style.

Function: int gmp_asprintf (char **pp, const char *fmt, ...)
Function: int gmp_vasprintf (char *pp, const char *fmt, va_list ap)
Form a null-terminated string in a block of memory obtained from the current memory allocation function (see section 14. Custom Allocation). The block will be the size of the string and null-terminator. Put the address of the block in *pp. Return the number of characters produced, excluding the null-terminator.

Unlike the C library asprintf, gmp_asprintf doesn't return -1 if there's no more memory available, it lets the current allocation function handle that.

Function: int gmp_obstack_printf (struct obstack *ob, const char *fmt, ...)
Function: int gmp_obstack_vprintf (struct obstack *ob, const char *fmt, va_list ap)
Append to the current obstack object, in the same style as obstack_printf. Return the number of characters written. A null-terminator is not written.

fmt cannot be within the current obstack object, since the object might move as it grows.

These functions are available only when the C library provides the obstack feature, which probably means only on GNU systems, see section `Obstacks' in The GNU C Library Reference Manual.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10.3 C++ Formatted Output

The following functions are provided in `libgmpxx', which is built if C++ support is enabled (see section 2.1 Build Options). Prototypes are available from <gmp.h>.

Function: ostream& operator<< (ostream& stream, mpz_t op)
Print op to stream, using its ios formatting settings. ios::width is reset to 0 after output, the same as the standard ostream operator<< routines do.

In hex or octal, op is printed as a signed number, the same as for decimal. This is unlike the standard operator<< routines on int etc, which instead give twos complement.

Function: ostream& operator<< (ostream& stream, mpq_t op)
Print op to stream, using its ios formatting settings. ios::width is reset to 0 after output, the same as the standard ostream operator<< routines do.

Output will be a fraction like `5/9', or if the denominator is 1 then just a plain integer like `123'.

In hex or octal, op is printed as a signed value, the same as for decimal. If ios::showbase is set then a base indicator is shown on both the numerator and denominator (if the denominator is required).

Function: ostream& operator<< (ostream& stream, mpf_t op)
Print op to stream, using its ios formatting settings. ios::width is reset to 0 after output, the same as the standard ostream operator<< routines do. The decimal point follows the current locale, on systems providing localeconv.

Hex and octal are supported, unlike the standard operator<< routines on double etc. The mantissa will be in hex or octal, the exponent will be in decimal. For hex the exponent delimiter is an `@'. This is as per mpf_out_str. ios::showbase is supported, and will put a base on the mantissa.

These operators mean that GMP types can be printed in the usual C++ way, for example,

mpz_t  z;
int    n;
...
cout << "iteration " << n << " value " << z << "\n";

But note that ostream output (and istream input, see section 11.3 C++ Formatted Input) is the only overloading available and using for instance + with an mpz_t will have unpredictable results.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11. Formatted Input

11.1 Formatted Input Strings
11.2 Formatted Input Functions
11.3 C++ Formatted Input

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.1 Formatted Input Strings

gmp_scanf and friends accept format strings similar to the standard C scanf (see section `Formatted Input' in The GNU C Library Reference Manual). A format specification is of the form

% [flags] [width] [type] conv

GMP adds types `Z', `Q' and `F' for mpz_t, mpq_t and mpf_t respectively. `Z' and `Q' behave like integers. `Q' will read a `/' and a denominator, if present. `F' behaves like a float.

GMP variables don't require an & when passed to gmp_scanf, since they're already "call-by-reference". For example,

/* to read say "a(5) = 1234" */
int   n;
mpz_t z;
gmp_scanf ("a(%d) = %Zd\n", &n, z);

mpq_t q1, q2;
gmp_sscanf ("0377 + 0x10/0x11", "%Qi + %Qi", q1, q2);

/* to read say "topleft (1.55,-2.66)" */
mpf_t x, y;
char  buf[32];
gmp_scanf ("%31s (%Ff,%Ff)", buf, x, y);

All the standard C scanf types behave the same as in the C library scanf, and can be freely intermixed with the GMP extensions. In the current implementation the standard parts of the format string are simply handed to scanf and only the GMP extensions handled directly.

The flags accepted are as follows. `a' and `'' will depend on support from the C library, and `'' cannot be used with GMP types.

* read but don't store
a allocate a buffer (string conversions)
' group digits, GLIBC style (not GMP types)

The standard types accepted are as follows. `h' and `l' are portable, the rest will depend on the compiler (or include files) for the type and the C library for the input.

h | short
hh | char
j | intmax_t or uintmax_t
l | long or wchar_t
ll | same as L
L | long long or long double
q | quad_t or u_quad_t
t | ptrdiff_t
z | size_t

The GMP types are

F | mpf_t, float conversions
Q | mpq_t, integer conversions
Z | mpz_t, integer conversions

The conversions accepted are as follows. `p' and `[' will depend on support from the C library, the rest are standard.

c | character or characters
d | decimal integer
e E f g G | float
i | integer with base indicator
n | characters written so far
o | octal integer
p | pointer
s | string of non-whitespace characters
u | decimal integer
x X | hex integer
[ string of characters in a set

`e', `E', `f', `g' and `G' are identical, they all read either fixed point or scientific format, and either `e' or `E' for the exponent in scientific format.

`x' and `X' are identical, both accept both upper and lower case hexadecimal.

`o', `u', `x' and `X' all read positive or negative values. For the standard C types these are described as "unsigned" conversions, but that merely affects certain overflow handling, negatives are still allowed (see strtoul, section `Parsing of Integers' in The GNU C Library Reference Manual). For GMP types there are no overflows, and `d' and `u' are identical.

`Q' type reads the numerator and (optional) denominator as given. If the value might not be in canonical form then mpq_canonicalize must be called before using it in any calculations (see section 6. Rational Number Functions).

`Qi' will read a base specification separately for the numerator and denominator. For example `0x10/11' would be 16/11, whereas `0x10/0x11' would be 16/17.

`n' can be used with any of the types above, even the GMP types. `*' to suppress assignment is allowed, though the field would then do nothing at all.

Other conversions or types that might be accepted by the C library scanf cannot be used through gmp_scanf.

Whitespace is read and discarded before a field, except for `c' and `[' conversions.

For float conversions, the decimal point character (or string) expected is taken from the current locale settings on systems which provide localeconv (see section `Locales and Internationalization' in The GNU C Library Reference Manual). The C library will normally do the same for standard float input.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.2 Formatted Input Functions

Each of the following functions is similar to the corresponding C library function. The plain scanf forms take a variable argument list. The vscanf forms take an argument pointer, see section `Variadic Functions' in The GNU C Library Reference Manual, or `man 3 va_start'.

It should be emphasised that if a format string is invalid, or the arguments don't match what the format specifies, then the behaviour of any of these functions will be unpredictable. GCC format string checking is not available, since it doesn't recognise the GMP extensions.

No overlap is permitted between the fmt string and any of the results produced.

Function: int gmp_scanf (const char *fmt, ...)
Function: int gmp_vscanf (const char *fmt, va_list ap)
Read from the standard input stdin.

Function: int gmp_fscanf (FILE *fp, const char *fmt, ...)
Function: int gmp_vfscanf (FILE *fp, const char *fmt, va_list ap)
Read from the stream fp.

Function: int gmp_sscanf (const char *s, const char *fmt, ...)
Function: int gmp_vsscanf (const char *s, const char *fmt, va_list ap)
Read from a null-terminated string s.

The return value from each of these functions is the same as the standard C99 scanf, namely the number of fields successfully parsed and stored. `%n' fields and fields read but suppressed by `*' don't count towards the return value.

If end of file or file error, or end of string, is reached when a match is required, and when no previous non-suppressed fields have matched, then the return value is EOF instead of 0. A match is required for a literal character in the format string or a field other than `%n'. Whitespace in the format string is only an optional match and won't induce an EOF in this fashion. Leading whitespace read and discarded for a field doesn't count as a match.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

11.3 C++ Formatted Input

The following functions are provided in `libgmpxx', which is built only if C++ support is enabled (see section 2.1 Build Options). Prototypes are available from <gmp.h>.

Function: istream& operator>> (istream& stream, mpz_t rop)
Read rop from stream, using its ios formatting settings.

Function: istream& operator>> (istream& stream, mpq_t rop)
Read rop from stream, using its ios formatting settings.

An integer like `123' will be read, or a fraction like `5/9'. If the fraction is not in canonical form then mpq_canonicalize must be called (see section 6. Rational Number Functions).

Function: istream& operator>> (istream& stream, mpf_t rop)
Read rop from stream, using its ios formatting settings.

Hex or octal floats are not supported, but might be in the future.

These operators mean that GMP types can be read in the usual C++ way, for example,

mpz_t  z;
...
cin >> z;

But note that istream input (and ostream output, see section 10.3 C++ Formatted Output) is the only overloading available and using for instance + with an mpz_t will have unpredictable results.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12. C++ Class Interface

This chapter describes the C++ class based interface to GMP.

All GMP C language types and functions can be used in C++ programs, since `gmp.h' has extern "C" qualifiers, but the class interface offers overloaded functions and operators which may be more convenient.

Due to the implementation of this interface, a reasonably recent C++ compiler is required, one supporting namespaces, partial specialization of templates and member templates. For GCC this means version 2.91 or later.

Everything described in this chapter is to be considered preliminary and might be subject to incompatible changes if some unforeseen difficulty reveals itself.

12.1 C++ Interface General
12.2 C++ Interface Integers
12.3 C++ Interface Rationals
12.4 C++ Interface Floats
12.5 C++ Interface MPFR
12.6 C++ Interface Random Numbers
12.7 C++ Interface Limitations

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.1 C++ Interface General

All the C++ classes and functions are available with

#include <gmpxx.h>

The classes defined are

Class: mpz_class
Class: mpq_class
Class: mpf_class

The standard operators and various standard functions are overloaded to allow arithmetic with these classes. For example,

int
main (void)
{
  mpz_class a, b, c;

  a = 1234;
  b = "-5678";
  c = a+b;
  cout << "sum is " << c << "\n";
  cout << "absolute value is " << abs(c) << "\n";

  return 0;
}

An important feature of the implementation is that an expression like a=b+c results in a single call to the corresponding mpz_add, without using a temporary for the b+c part. Expressions which by their nature imply intermediate values, like a=b*c+d*e, still use temporaries though.

The classes can be freely intermixed in expressions, as can the classes and the standard C++ types.

Conversions back from the classes to standard C++ types aren't done automatically, instead member functions like get_si are provided (see the following sections for details).

Also there are no automatic conversions from the classes to the corresponding GMP C types, instead a reference to the underlying C object can be obtained with the following functions,

Function: mpz_t mpz_class::get_mpz_t ()
Function: mpq_t mpq_class::get_mpq_t ()
Function: mpf_t mpf_class::get_mpf_t ()

These can be used to call a C function which doesn't have a C++ class interface. For example to set a to the GCD of b and c,

mpz_class a, b, c;
...
mpz_gcd (a.get_mpz_t(), b.get_mpz_t(), c.get_mpz_t());

In the other direction, a class can be initialized from the corresponding GMP C type, or assigned to if an explicit constructor is used. In both cases this makes a copy of the value, it doesn't create any sort of association. For example,

mpz_t z;
// ... init and calculate z ...
mpz_class x(z);
mpz_class y;
y = mpz_class (z);

There are no namespace setups in `gmpxx.h', all types and functions are simply put into the global namespace. This is what `gmp.h' has done in the past, and continues to do for compatibility. The extras provided by `gmpxx.h' follow GMP naming conventions and are unlikely to clash with anything.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.2 C++ Interface Integers

Function: void mpz_class::mpz_class (type n)
Construct an mpz_class. All the standard C++ types may be used, except long long and long double, and all the GMP C++ classes can be used. Any necessary conversion follows the corresponding C function, for example double follows mpz_set_d (see section 5.2 Assignment Functions).

Function: void mpz_class::mpz_class (mpz_t z)
Construct an mpz_class from an mpz_t. The value in z is copied into the new mpz_class, there won't be any permanent association between it and z.

Function: void mpz_class::mpz_class (const char *s)
Function: void mpz_class::mpz_class (const char *s, int base)
Function: void mpz_class::mpz_class (const string& s)
Function: void mpz_class::mpz_class (const string& s, int base)
Construct an mpz_class converted from a string using mpz_set_str, (see section 5.2 Assignment Functions). If the base is not given then 0 is used.

Function: mpz_class operator/ (mpz_class a, mpz_class d)
Function: mpz_class operator% (mpz_class a, mpz_class d)
Divisions involving mpz_class round towards zero, as per the mpz_tdiv_q and mpz_tdiv_r functions (see section 5.6 Division Functions). This corresponds to the rounding used for plain int calculations on most machines.

The mpz_fdiv... or mpz_cdiv... functions can always be called directly if desired. For example,

mpz_class q, a, d;
...
mpz_fdiv_q (q.get_mpz_t(), a.get_mpz_t(), d.get_mpz_t());

Function: mpz_class abs (mpz_class op1)
Function: int cmp (mpz_class op1, type op2)
Function: int cmp (type op1, mpz_class op2)
Function: double mpz_class::get_d (void)
Function: long mpz_class::get_si (void)
Function: unsigned long mpz_class::get_ui (void)
Function: bool mpz_class::fits_sint_p (void)
Function: bool mpz_class::fits_slong_p (void)
Function: bool mpz_class::fits_sshort_p (void)
Function: bool mpz_class::fits_uint_p (void)
Function: bool mpz_class::fits_ulong_p (void)
Function: bool mpz_class::fits_ushort_p (void)
Function: int sgn (mpz_class op)
Function: mpz_class sqrt (mpz_class op)
These functions provide a C++ class interface to the corresponding GMP C routines.

cmp can be used with any of the classes or the standard C++ types, except long long and long double.

Overloaded operators for combinations of mpz_class and double are provided for completeness, but it should be noted that if the given double is not an integer then the way any rounding is done is currently unspecified. The rounding might take place at the start, in the middle, or at the end of the operation, and it might change in the future.

Conversions between mpz_class and double, however, are defined to follow the corresponding C functions mpz_get_d and mpz_set_d. And comparisons are always made exactly, as per mpz_cmp_d.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.3 C++ Interface Rationals

In all the following constructors, if a fraction is given then it should be in canonical form, or if not then mpq_class::canonicalize called.

Function: void mpq_class::mpq_class (type op)
Function: void mpq_class::mpq_class (integer num, integer den)
Construct an mpq_class. The initial value can be a single value of any type, or a pair of integers (mpz_class or standard C++ integer types) representing a fraction, except that long long and long double are not supported. For example,

mpq_class q (99);
mpq_class q (1.75);
mpq_class q (1, 3);

Function: void mpq_class::mpq_class (mpq_t q)
Construct an mpq_class from an mpq_t. The value in q is copied into the new mpq_class, there won't be any permanent association between it and q.

Function: void mpq_class::mpq_class (const char *s)
Function: void mpq_class::mpq_class (const char *s, int base)
Function: void mpq_class::mpq_class (const string& s)
Function: void mpq_class::mpq_class (const string& s, int base)
Construct an mpq_class converted from a string using mpq_set_str, (see section 6.1 Initialization and Assignment Functions). If the base is not given then 0 is used.

Function: void mpq_class::canonicalize ()
Put an mpq_class into canonical form, as per 6. Rational Number Functions. All arithmetic operators require their operands in canonical form, and will return results in canonical form.

Function: mpq_class abs (mpq_class op)
Function: int cmp (mpq_class op1, type op2)
Function: int cmp (type op1, mpq_class op2)
Function: double mpq_class::get_d (void)
Function: int sgn (mpq_class op)
These functions provide a C++ class interface to the corresponding GMP C routines.

cmp can be used with any of the classes or the standard C++ types, except long long and long double.

Function: mpz_class& mpq_class::get_num ()
Function: mpz_class& mpq_class::get_den ()
Get a reference to an mpz_class which is the numerator or denominator of an mpq_class. This can be used both for read and write access. If the object returned is modified, it modifies the original mpq_class.

If direct manipulation might produce a non-canonical value, then mpq_class::canonicalize must be called before further operations.

Function: mpz_t mpq_class::get_num_mpz_t ()
Function: mpz_t mpq_class::get_den_mpz_t ()
Get a reference to the underlying mpz_t numerator or denominator of an mpq_class. This can be passed to C functions expecting an mpz_t. Any modifications made to the mpz_t will modify the original mpq_class.

If direct manipulation might produce a non-canonical value, then mpq_class::canonicalize must be called before further operations.

Function: istream& operator>> (istream& stream, mpq_class& rop);
Read rop from stream, using its ios formatting settings, the same as mpq_t operator>> (see section 11.3 C++ Formatted Input).

If the rop read might not be in canonical form then mpq_class::canonicalize must be called.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.4 C++ Interface Floats

When an expression requires the use of temporary intermediate mpf_class values, like f=g*h+x*y, those temporaries will have the same precision as the destination f. Explicit constructors can be used if this doesn't suit.

Function: mpf_class::mpf_class (type op)
Function: mpf_class::mpf_class (type op, unsigned long prec)
Construct an mpf_class. Any standard C++ type can be used, except long long and long double, and any of the GMP C++ classes can be used.

If prec is given, the initial precision is that value, in bits. If prec is not given, then the initial precision is determined by the type of op given. An mpz_class, mpq_class, string, or C++ builtin type will give the default mpf precision (see section 7.1 Initialization Functions). An mpf_class or expression will give the precision of that value. The precision of a binary expression is the higher of the two operands.

mpf_class f(1.5);        // default precision
mpf_class f(1.5, 500);   // 500 bits (at least)
mpf_class f(x);          // precision of x
mpf_class f(abs(x));     // precision of x
mpf_class f(-g, 1000);   // 1000 bits (at least)
mpf_class f(x+y);        // greater of precisions of x and y

Function: mpf_class abs (mpf_class op)
Function: mpf_class ceil (mpf_class op)
Function: int cmp (mpf_class op1, type op2)
Function: int cmp (type op1, mpf_class op2)
Function: mpf_class floor (mpf_class op)
Function: mpf_class hypot (mpf_class op1, mpf_class op2)
Function: double mpf_class::get_d (void)
Function: long mpf_class::get_si (void)
Function: unsigned long mpf_class::get_ui (void)
Function: bool mpf_class::fits_sint_p (void)
Function: bool mpf_class::fits_slong_p (void)
Function: bool mpf_class::fits_sshort_p (void)
Function: bool mpf_class::fits_uint_p (void)
Function: bool mpf_class::fits_ulong_p (void)
Function: bool mpf_class::fits_ushort_p (void)
Function: int sgn (mpf_class op)
Function: mpf_class sqrt (mpf_class op)
Function: mpf_class trunc (mpf_class op)
These functions provide a C++ class interface to the corresponding GMP C routines.

cmp can be used with any of the classes or the standard C++ types, except long long and long double.

The accuracy provided by hypot is not currently guaranteed.

Function: unsigned long int mpf_class::get_prec ()
Function: void mpf_class::set_prec (unsigned long prec)
Function: void mpf_class::set_prec_raw (unsigned long prec)
Get or set the current precision of an mpf_class.

The restrictions described for mpf_set_prec_raw (see section 7.1 Initialization Functions) apply to mpf_class::set_prec_raw. Note in particular that the mpf_class must be restored to it's allocated precision before being destroyed. This must be done by application code, there's no automatic mechanism for it.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.5 C++ Interface MPFR

The C++ class interface to MPFR is provided if MPFR is enabled (see section 2.1 Build Options). This interface must be regarded as preliminary and possibly subject to incompatible changes in the future, since MPFR itself is preliminary. All definitions can be obtained with

#include <mpfrxx.h>

This defines

Class: mpfr_class

which behaves similarly to mpf_class (see section 12.4 C++ Interface Floats).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.6 C++ Interface Random Numbers

Class: gmp_randclass
The C++ class interface to the GMP random number functions uses gmp_randclass to hold an algorithm selection and current state, as per gmp_randstate_t.

Function: gmp_randclass::gmp_randclass (void (*randinit) (gmp_randstate_t, ...), ...)
Construct a gmp_randclass, using a call to the given randinit function (see section 9.1 Random State Initialization). The arguments expected are the same as randinit, but with mpz_class instead of mpz_t. For example,

gmp_randclass r1 (gmp_randinit_default);
gmp_randclass r2 (gmp_randinit_lc_2exp_size, 32);
gmp_randclass r3 (gmp_randinit_lc_2exp, a, c, m2exp);

gmp_randinit_lc_2exp_size can fail if the size requested is too big, the behaviour of gmp_randclass::gmp_randclass is undefined in this case (perhaps this will change in the future).

Function: gmp_randclass::gmp_randclass (gmp_randalg_t alg, ...)
Construct a gmp_randclass using the same parameters as gmp_randinit (see section 9.1 Random State Initialization). This function is obsolete and the above randinit style should be preferred.

Function: void gmp_randclass::seed (unsigned long int s)
Function: void gmp_randclass::seed (mpz_class s)
Seed a random number generator. See see section 9. Random Number Functions, for how to choose a good seed.

Function: mpz_class gmp_randclass::get_z_bits (unsigned long bits)
Function: mpz_class gmp_randclass::get_z_bits (mpz_class bits)
Generate a random integer with a specified number of bits.

Function: mpz_class gmp_randclass::get_z_range (mpz_class n)
Generate a random integer in the range 0 to n-1 inclusive.

Function: mpf_class gmp_randclass::get_f ()
Function: mpf_class gmp_randclass::get_f (unsigned long prec)
Generate a random float f in the range 0 <= f < 1. f will be to prec bits precision, or if prec is not given then to the precision of the destination. For example,

gmp_randclass  r;
...
mpf_class  f (0, 512);   // 512 bits precision
f = r.get_f();           // random number, 512 bits

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

12.7 C++ Interface Limitations

mpq_class and Templated Reading
A generic piece of template code probably won't know that mpq_class requires a canonicalize call if inputs read with operator>> might be non-canonical. This can lead to incorrect results.

operator>> behaves as it does for reasons of efficiency. A canonicalize can be quite time consuming on large operands, and is best avoided if it's not necessary.

But this potential difficulty reduces the usefulness of mpq_class. Perhaps a mechanism to tell operator>> what to do will be adopted in the future, maybe a preprocessor define, a global flag, or an ios flag pressed into service. Or maybe, at the risk of inconsistency, the mpq_class operator>> could canonicalize and leave mpq_t operator>> not doing so, for use on those occasions when that's acceptable. Send feedback or alternate ideas to bug-gmp@gnu.org.

Subclassing
Subclassing the GMP C++ classes works, but is not currently recommended.

Expressions involving subclasses resolve correctly (or seem to), but in normal C++ fashion the subclass doesn't inherit constructors and assignments. There's many of those in the GMP classes, and a good way to reestablish them in a subclass is not yet provided.

Templated Expressions

A subtle difficulty exists when using expressions together with application-defined template functions. Consider the following, with T intended to be some numeric type,

template <class T>
T fun (const T &, const T &);

When used with, say, plain mpz_class variables, it works fine: T is resolved as mpz_class.

mpz_class f(1), g(2);
fun (f, g);    // Good

But when one of the arguments is an expression, it doesn't work.

mpz_class f(1), g(2), h(3);
fun (f, g+h);  // Bad

This is because g+h ends up being a certain expression template type internal to gmpxx.h, which the C++ template resolution rules are unable to automatically convert to mpz_class. The workaround is simply to add an explicit cast.

mpz_class f(1), g(2), h(3);
fun (f, mpz_class(g+h));  // Good

Similarly, within fun it may be necessary to cast an expression to type T when calling a templated fun2.

template <class T>
void fun (T f, T g)
{
  fun2 (f, f+g);     // Bad
}

template <class T>
void fun (T f, T g)
{
  fun2 (f, T(f+g));  // Good
}

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

13. Berkeley MP Compatible Functions

These functions are intended to be fully compatible with the Berkeley MP library which is available on many BSD derived U*ix systems. The `--enable-mpbsd' option must be used when building GNU MP to make these available (see section 2. Installing GMP).

The original Berkeley MP library has a usage restriction: you cannot use the same variable as both source and destination in a single function call. The compatible functions in GNU MP do not share this restriction--inputs and outputs may overlap.

It is not recommended that new programs are written using these functions. Apart from the incomplete set of functions, the interface for initializing MINT objects is more error prone, and the pow function collides with pow in `libm.a'.

Include the header `mp.h' to get the definition of the necessary types and functions. If you are on a BSD derived system, make sure to include GNU `mp.h' if you are going to link the GNU `libmp.a' to your program. This means that you probably need to give the `-I<dir>' option to the compiler, where `<dir>' is the directory where you have GNU `mp.h'.

Function: MINT * itom (signed short int initial_value)
Allocate an integer consisting of a MINT object and dynamic limb space. Initialize the integer to initial_value. Return a pointer to the MINT object.

Function: MINT * xtom (char *initial_value)
Allocate an integer consisting of a MINT object and dynamic limb space. Initialize the integer from initial_value, a hexadecimal, null-terminated C string. Return a pointer to the MINT object.

Function: void move (MINT *src, MINT *dest)
Set dest to src by copying. Both variables must be previously initialized.

Function: void madd (MINT *src_1, MINT *src_2, MINT *destination)
Add src_1 and src_2 and put the sum in destination.

Function: void msub (MINT *src_1, MINT *src_2, MINT *destination)
Subtract src_2 from src_1 and put the difference in destination.

Function: void mult (MINT *src_1, MINT *src_2, MINT *destination)
Multiply src_1 and src_2 and put the product in destination.

Function: void mdiv (MINT *dividend, MINT *divisor, MINT *quotient, MINT *remainder)
Function: void sdiv (MINT *dividend, signed short int divisor, MINT *quotient, signed short int *remainder)
Set quotient to dividend/divisor, and remainder to dividend mod divisor. The quotient is rounded towards zero; the remainder has the same sign as the dividend unless it is zero.

Some implementations of these functions work differently--or not at all--for negative arguments.

Function: void msqrt (MINT *op, MINT *root, MINT *remainder)
Set root to \N\}\rfloor, the truncated integer part of the square root of op}, like mpz_sqrt. Set remainder to \N\ - root^2), op-root*root}, i.e. zero if op is a perfect square.

If root and remainder are the same variable, the results are undefined.

Function: void pow (MINT *base, MINT *exp, MINT *mod, MINT *dest)
Set dest to (base raised to exp) modulo mod.

Function: void rpow (MINT *base, signed short int exp, MINT *dest)
Set dest to base raised to exp.

Function: void gcd (MINT *op1, MINT *op2, MINT *res)
Set res to the greatest common divisor of op1 and op2.

Function: int mcmp (MINT *op1, MINT *op2)
Compare op1 and op2. Return a positive value if op1 > op2, zero if op1 = op2, and a negative value if op1 < op2.

Function: void min (MINT *dest)
Input a decimal string from stdin, and put the read integer in dest. SPC and TAB are allowed in the number string, and are ignored.

Function: void mout (MINT *src)
Output src to stdout, as a decimal string. Also output a newline.

Function: char * mtox (MINT *op)
Convert op to a hexadecimal string, and return a pointer to the string. The returned string is allocated using the default memory allocation function, malloc by default.

Function: void mfree (MINT *op)
De-allocate, the space used by op. This function should only be passed a value returned by itom or xtom.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

14. Custom Allocation

By default GMP uses malloc, realloc and free for memory allocation, and if they fail GMP prints a message to the standard error output and terminates the program.

Alternate functions can be specified to allocate memory in a different way or to have a different error action on running out of memory.

This feature is available in the Berkeley compatibility library (see section 13. Berkeley MP Compatible Functions) as well as the main GMP library.

Function: void mp_set_memory_functions (
void *(*alloc_func_ptr) (size_t),
void *(*realloc_func_ptr) (void *, size_t, size_t),
void (*free_func_ptr) (void *, size_t))
Replace the current allocation functions from the arguments. If an argument is NULL, the corresponding default function is used.

These functions will be used for all memory allocation done by GMP, apart from temporary space from alloca if that function is available and GMP is configured to use it (see section 2.1 Build Options).

Be sure to call mp_set_memory_functions only when there are no active GMP objects allocated using the previous memory functions! Usually that means calling it before any other GMP function.

The functions supplied should fit the following declarations:

Function: void * allocate_function (size_t alloc_size)
Return a pointer to newly allocated space with at least alloc_size bytes.

Function: void * reallocate_function (void *ptr, size_t old_size, size_t new_size)
Resize a previously allocated block ptr of old_size bytes to be new_size bytes.

The block may be moved if necessary or if desired, and in that case the smaller of old_size and new_size bytes must be copied to the new location. The return value is a pointer to the resized block, that being the new location if moved or just ptr if not.

ptr is never NULL, it's always a previously allocated block. new_size may be bigger or smaller than old_size.

Function: void deallocate_function (void *ptr, size_t size)
De-allocate the space pointed to by ptr.

ptr is never NULL, it's always a previously allocated block of size bytes.

A byte here means the unit used by the sizeof operator.

The old_size parameters to reallocate_function and deallocate_function are passed for convenience, but of course can be ignored if not needed. The default functions using malloc and friends for instance don't use them.

No error return is allowed from any of these functions, if they return then they must have performed the specified operation. In particular note that allocate_function or reallocate_function mustn't return NULL.

Getting a different fatal error action is a good use for custom allocation functions, for example giving a graphical dialog rather than the default print to stderr. How much is possible when genuinely out of memory is another question though.

There's currently no defined way for the allocation functions to recover from an error such as out of memory, they must terminate program execution. A longjmp or throwing a C++ exception will have undefined results. This may change in the future.

GMP may use allocated blocks to hold pointers to other allocated blocks. This will limit the assumptions a conservative garbage collection scheme can make.

Since the default GMP allocation uses malloc and friends, those functions will be linked in even if the first thing a program does is an mp_set_memory_functions. It's necessary to change the GMP sources if this is a problem.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

15. Language Bindings

The following packages and projects offer access to GMP from languages other than C, though perhaps with varying levels of functionality and efficiency.

C++
  • GMP C++ class interface, see section 12. C++ Class Interface
    Straightforward interface, expression templates to eliminate temporaries.
  • ALP http://www.inria.fr/saga/logiciels/ALP
    Linear algebra and polynomials using templates.
  • CLN http://clisp.cons.org/~haible/packages-cln.html"
    High level classes for arithmetic.
  • LiDIA http://www.informatik.tu-darmstadt.de/TI/LiDIA
    A C++ library for computational number theory.
  • NTL http://www.shoup.net/ntl
    A C++ number theory library.

Fortran
  • Omni F77 http://pdplab.trc.rwcp.or.jp/pdperf/Omni/home.html
    Arbitrary precision floats.

Haskell
  • Glasgow Haskell Compiler http://www.haskell.org/ghc

Java
  • Kaffe http://www.kaffe.org
  • Kissme http://kissme.sourceforge.net

Lisp
  • GNU Common Lisp http://www.gnu.org/software/gcl/gcl.html
    In the process of switching to GMP for bignums.
  • Librep http://librep.sourceforge.net

M4
  • GNU m4 betas http://www.seindal.dk/rene/gnu
    Optionally provides an arbitrary precision mpeval.

ML
  • MLton compiler http://www.sourcelight.com/MLton

Oz
  • Mozart http://www.mozart-oz.org

Perl
  • GMP module, see `demos/perl' in the GMP sources.
  • Math::GMP http://www.cpan.org
    Compatible with Math::BigInt, but not as many functions as the GMP module above.

Pike
  • mpz module in the standard distribution, http://pike.idonex.com

Prolog
  • SWI Prolog http://www.swi.psy.uva.nl/projects/SWI-Prolog
    Arbitrary precision floats.

Python
  • mpz module in the standard distribution, http://www.python.org

Scheme
  • RScheme http://www.rscheme.org

Other
  • DrGenius http://drgenius.seul.org
    Geometry system and mathematical programming language.
  • GiNaC http://www.ginac.de
    C++ computer algebra using CLN.
  • Maxima http://www.ma.utexas.edu/users/wfs/maxima.html
    Macsyma computer algebra using GCL.
  • Q http://www.musikwissenschaft.uni-mainz.de/~ag/q
    Equational programming system.
  • Yacas http://www.xs4all.nl/~apinkus/yacas.html
    Computer algebra system.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16. Algorithms

This chapter is an introduction to some of the algorithms used for various GMP operations. The code is likely to be hard to understand without knowing something about the algorithms.

Some GMP internals are mentioned, but applications that expect to be compatible with future GMP releases should take care to use only the documented functions.

16.1 Multiplication
16.2 Division Algorithms
16.3 Greatest Common Divisor
16.4 Powering Algorithms
16.5 Root Extraction Algorithms
16.6 Radix Conversion
16.7 Other Algorithms
16.8 Assembler Coding

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1 Multiplication

Nx{}N limb multiplications and squares are done using one of four algorithms, as the size N increases.

Algorithm | Threshold
Basecase | (none)
Karatsuba | KARATSUBA_MUL_THRESHOLD
Toom-3 | TOOM3_MUL_THRESHOLD
FFT | FFT_MUL_THRESHOLD

Similarly for squaring, with the SQR thresholds. Note though that the FFT is only used if GMP is configured with `--enable-fft', see section 2.1 Build Options.

Nx{}M multiplications of operands with different sizes above KARATSUBA_MUL_THRESHOLD are currently done by splitting into Mx{}M pieces. The Karatsuba and Toom-3 routines then operate only on equal size operands. This is not very efficient, and is slated for improvement in the future.

16.1.1 Basecase Multiplication
16.1.2 Karatsuba Multiplication
16.1.3 Toom-Cook 3-Way Multiplication
16.1.4 FFT Multiplication
16.1.5 Other Multiplication

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1.1 Basecase Multiplication

Basecase Nx{}M multiplication is a straightforward rectangular set of cross-products, the same as long multiplication done by hand and for that reason sometimes known as the schoolbook or grammar school method. This is an O(N*M) algorithm. See Knuth section 4.3.1 algorithm M (see section B. References), and the `mpn/generic/mul_basecase.c' code.

Assembler implementations of mpn_mul_basecase are essentially the same as the generic C code, but have all the usual assembler tricks and obscurities introduced for speed.

A square can be done in roughly half the time of a multiply, by using the fact that the cross products above and below the diagonal are the same. A triangle of products below the diagonal is formed, doubled (left shift by one bit), and then the products on the diagonal added. This can be seen in `mpn/generic/sqr_basecase.c'. Again the assembler implementations take essentially the same approach.

     u0  u1  u2  u3  u4
   +---+---+---+---+---+
u0 | d |   |   |   |   |
   +---+---+---+---+---+
u1 |   | d |   |   |   |
   +---+---+---+---+---+
u2 |   |   | d |   |   |
   +---+---+---+---+---+
u3 |   |   |   | d |   |
   +---+---+---+---+---+
u4 |   |   |   |   | d |
   +---+---+---+---+---+

In practice squaring isn't a full 2x{} faster than multiplying, it's usually around 1.5x probably indicates mpn_sqr_basecase wants improving on that CPU.

On some CPUs mpn_mul_basecase can be faster than the generic C mpn_sqr_basecase. BASECASE_SQR_THRESHOLD is the size at which to use mpn_sqr_basecase, this will be zero if that routine should be used always.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1.2 Karatsuba Multiplication

The Karatsuba multiplication algorithm is described in Knuth section 4.3.3 part A, and various other textbooks. A brief description is given here.

The inputs x and y are treated as each split into two parts of equal length (or the most significant part one limb shorter if N is odd).

 high              low
+----------+----------+
|    x1    |    x0    |
+----------+----------+

+----------+----------+
|    y1    |    y0    |
+----------+----------+

Let b be the power of 2 where the split occurs, ie. if x0 is k limbs (y0 the same) then \N\}, b=2^(k*mp_bits_per_limb)}. With that x=x1*b+x0 and y=y1*b+y0, and the following holds,

\N\{xy = (b^2+b)x_1y_1 - b(x_1-x_0)(y_1-y_0) + (b+1)x_0y_0,
  x*y = (b^2+b)*x1*y1 - b*(x1-x0)*(y1-y0) + (b+1)*x0*y0}

This formula means doing only three multiplies of (N/2)x{}(N/2) limbs, whereas a basecase multiply of Nx{}N limbs is equivalent to four multiplies of (N/2)x etc represent the positions where the three products must be added.

 high                              low
+--------+--------+ +--------+--------+
|      x1*y1      | |      x0*y0      |
+--------+--------+ +--------+--------+
          +--------+--------+
      add |      x1*y1      |
          +--------+--------+
          +--------+--------+
      add |      x0*y0      |
          +--------+--------+
          +--------+--------+
      sub | (x1-x0)*(y1-y0) |
          +--------+--------+

The term (x1-x0)*(y1-y0) is best calculated as an absolute value, and the sign used to choose to add or subtract. Notice the sum \N\(x_0y_0)+\mathop{\rm low}(x_1y_1), high(x0*y0)+low(x1*y1)} occurs twice, so it's possible to do 5*k limb additions, rather than 6*k, but in GMP extra function call overheads outweigh the saving.

Squaring is similar to multiplying, but with x=y the formula reduces to an equivalent with three squares,

\N\{x^2 = (b^2+b)x_1^2 - b(x_1-x_0)^2 + (b+1)x_0^2,
   x^2 = (b^2+b)*x1^2 - b*(x1-x0)^2 + (b+1)*x0^2}

The final result is accumulated from those three squares the same way as for the three multiplies above. The middle term (x1-x0)^2 is now always positive.

A similar formula for both multiplying and squaring can be constructed with a middle term (x1+x0)*(y1+y0). But those sums can exceed k limbs, leading to more carry handling and additions than the form above.

Karatsuba multiplication is asymptotically an O(N^1.585) algorithm, the exponent being log(3)/log(2), representing 3 multiplies each 1/2 the size of the inputs. This is a big improvement over the basecase multiply at O(N^2) and the advantage soon overcomes the extra additions Karatsuba performs.

KARATSUBA_MUL_THRESHOLD can be as little as 10 limbs. The SQR threshold is usually about twice the MUL. The basecase algorithm will take a time of the form M(N) = a*N^2 + b*N + c and the Karatsuba algorithm \N\{K(N) = 3M(N/2) + dN + e, K(N) = 3*M(N/2) + d*N + e}. Clearly per-crossproduct speedups in the basecase code reduce a and decrease the threshold, but linear style speedups reducing b will actually increase the threshold. The latter can be seen for instance when adding an optimized mpn_sqr_diagonal to mpn_sqr_basecase. Of course all speedups reduce total time, and in that sense the algorithm thresholds are merely of academic interest.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1.3 Toom-Cook 3-Way Multiplication

The Karatsuba formula is the simplest case of a general approach to splitting inputs that leads to both Toom-Cook and FFT algorithms. A description of Toom-Cook can be found in Knuth section 4.3.3, with an example 3-way calculation after Theorem A. The 3-way form used in GMP is described here.

The operands are each considered split into 3 pieces of equal length (or the most significant part 1 or 2 limbs shorter than the others).

 high                         low
+----------+----------+----------+
|    x2    |    x1    |    x0    |
+----------+----------+----------+

+----------+----------+----------+
|    y2    |    y1    |    y0    |
+----------+----------+----------+

These parts are treated as the coefficients of two polynomials

\N\{X(t) = x_2t^2 + x_1t + x_0,
   X(t) = x2*t^2 + x1*t + x0}
\N\{Y(t) = y_2t^2 + y_1t + y_0,
   Y(t) = y2*t^2 + y1*t + y0}

Again let b equal the power of 2 which is the size of the x0, x1, y0 and y1 pieces, ie. if they're k limbs each then \N\}, b=2^(k*mp_bits_per_limb)}. With this x=X(b) and y=Y(b).

Let a polynomial W(t)=X(t)*Y(t) and suppose its coefficients are

\N\{W(t) = w_4t^4 + w_3t^3 + w_2t^2 + w_1t + w_0,
   W(t) = w4*t^4 + w3*t^3 + w2*t^2 + w1*t + w0}

The w[i] are going to be determined, and when they are they'll give the final result using w=W(b), since x*y=X(b)*Y(b)=W(b). The coefficients will be roughly b^2 each, and the final W(b) will be an addition like,

 high                                        low
+-------+-------+
|       w4      |
+-------+-------+
       +--------+-------+
       |        w3      |
       +--------+-------+
               +--------+-------+
               |        w2      |
               +--------+-------+
                       +--------+-------+
                       |        w1      |
                       +--------+-------+
                                +-------+-------+
                                |       w0      |
                                +-------+-------+

The w[i] coefficients could be formed by a simple set of cross products, like w4=x2*y2, w3=x2*y1+x1*y2, w2=x2*y0+x1*y1+x0*y2 etc, but this would need all nine x[i]*y[j] for i,j=0,1,2, and would be equivalent merely to a basecase multiply. Instead the following approach is used.

X(t) and Y(t) are evaluated and multiplied at 5 points, giving values of W(t) at those points. The points used can be chosen in various ways, but in GMP the following are used

Point | Value
t=0 | x0*y0, which gives w0 immediately
t=2 | (4*x2+2*x1+x0)*(4*y2+2*y1+y0)
t=1 | (x2+x1+x0)*(y2+y1+y0)
\N\,t=1/2} | (x2+2*x1+4*x0)*(y2+2*y1+4*y0)
t=inf | x2*y2, which gives w4 immediately

At \N\,t=1/2} the value calculated is actually \N\)Y({1\over2}), 16*X(1/2)*Y(1/2)}, giving a value for \N\),16*W(1/2)}, and this is always an integer. At t=inf the value is actually \N\ {X(t)Y(t)\over t^4}, X(t)*Y(t)/t^4 in the limit as t approaches infinity}, but it's much easier to think of as simply x2*y2 giving w4 immediately (much like x0*y0 at t=0 gives w0 immediately).

Now each of the points substituted into W(t)=w4*t^4+...+w0 gives a linear combination of the w[i] coefficients, and the value of those combinations has just been calculated.

   W(0)   =                                 w0
16*W(1/2) =    w4 + 2*w3 + 4*w2 + 8*w1 + 16*w0
   W(1)   =    w4 +   w3 +   w2 +   w1 +    w0
   W(2)   = 16*w4 + 8*w3 + 4*w2 + 2*w1 +    w0
   W(inf) =    w4

This is a set of five equations in five unknowns, and some elementary linear algebra quickly isolates each w[i], by subtracting multiples of one equation from another.

In the code the set of five values W(0),...,W(inf) will represent those certain linear combinations. By adding or subtracting one from another as necessary, values which are each w[i] alone are arrived at. This involves only a few subtractions of small multiples (some of which are powers of 2), and so is fast. A couple of divisions remain by powers of 2 and one division by 3 (or by 6 rather), and that last uses the special mpn_divexact_by3 (see section 16.2.4 Exact Division).

In the code the values w4, w2 and w0 are formed in the destination with pointers E, C and A, and w3 and w1 in temporary space D and B are added to them. There are extra limbs tD, tC and tB at the high end of w3, w2 and w1 which are handled separately. The final addition then is as follows.

 high                                        low
+-------+-------+-------+-------+-------+-------+
|       E       |       C       |       A       |
+-------+-------+-------+-------+-------+-------+
         +------+-------++------+-------+
         |      D       ||      B       |
         +------+-------++------+-------+
      --      --      --
     |tD|    |tC|    |tB|
      --      --      --

The conversion of W(t) values to the coefficients is interpolation. A polynomial of degree 4 like W(t) is uniquely determined by values known at 5 different points. The points can be chosen to make the linear equations come out with a convenient set of steps for isolating the w[i].

In `mpn/generic/mul_n.c' the interpolate3 routine performs the interpolation. The open-coded one-pass version may be a bit hard to understand, the steps performed can be better seen in the USE_MORE_MPN version.

Squaring follows the same procedure as multiplication, but there's only one X(t) and it's evaluated at 5 points, and those values squared to give values of W(t). The interpolation is then identical, and in fact the same interpolate3 subroutine is used for both squaring and multiplying.

Toom-3 is asymptotically O(N^1.465), the exponent being log(5)/log(3), representing 5 recursive multiplies of 1/3 the original size. This is an improvement over Karatsuba at O(N^1.585), though Toom-Cook does more work in the evaluation and interpolation and so it only realizes its advantage above a certain size.

Near the crossover between Toom-3 and Karatsuba there's generally a range of sizes where the difference between the two is small. TOOM3_MUL_THRESHOLD is a somewhat arbitrary point in that range and successive runs of the tune program can give different values due to small variations in measuring. A graph of time versus size for the two shows the effect, see `tune/README'.

At the fairly small sizes where the Toom-3 thresholds occur it's worth remembering that the asymptotic behaviour for Karatsuba and Toom-3 can't be expected to make accurate predictions, due of course to the big influence of all sorts of overheads, and the fact that only a few recursions of each are being performed. Even at large sizes there's a good chance machine dependent effects like cache architecture will mean actual performance deviates from what might be predicted.

The formula given above for the Karatsuba algorithm has an equivalent for Toom-3 involving only five multiplies, but this would be complicated and unenlightening.

An alternate view of Toom-3 can be found in Zuras (see section B. References), using a vector to represent the x and y splits and a matrix multiplication for the evaluation and interpolation stages. The matrix inverses are not meant to be actually used, and they have elements with values much greater than in fact arise in the interpolation steps. The diagram shown for the 3-way is attractive, but again doesn't have to be implemented that way and for example with a bit of rearrangement just one division by 6 can be done.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1.4 FFT Multiplication

At large to very large sizes a Fermat style FFT multiplication is used, following Schönhage and Strassen (see section B. References). Descriptions of FFTs in various forms can be found in many textbooks, for instance Knuth section 4.3.3 part C or Lipson chapter IX. A brief description of the form used in GMP is given here.

The multiplication done is x*y mod 2^N+1, for a given N. A full product x*y is obtained by choosing \N\{N \ge \mathop{\rm bits}(x)+\mathop{\rm bits}(y), N>=bits(x)+bits(y)} and padding x and y with high zero limbs. The modular product is the native form for the algorithm, so padding to get a full product is unavoidable.

The algorithm follows a split, evaluate, pointwise multiply, interpolate and combine similar to that described above for Karatsuba and Toom-3. A k parameter controls the split, with an FFT-k splitting into 2^k pieces of M=N/2^k bits each. N must be a multiple of \N\, (2^k)*mp_bits_per_limb} so the split falls on limb boundaries, avoiding bit shifts in the split and combine stages.

The evaluations, pointwise multiplications, and interpolation, are all done modulo \N\+1, 2^N'+1} where N' is 2M+k+3 rounded up to a multiple of 2^k and of mp_bits_per_limb. The results of interpolation will be the following negacyclic convolution of the input pieces, and the choice of N' ensures these sums aren't truncated.

           ---
           \         b
w[n] =     /     (-1) * x[i] * y[j]
           ---
       i+j==b*2^k+n
          b=0,1

The points used for the evaluation are g^i for i=0 to 2^k-1 where \N\, g=2^(2N'/2^k)}. g is a 2^k'th root of unity mod \N\+1,2^N'+1}, which produces necessary cancellations at the interpolation stage, and it's also a power of 2 so the fast fourier transforms used for the evaluation and interpolation do only shifts, adds and negations.

The pointwise multiplications are done modulo \N\+1, 2^N'+1} and either recurse into a further FFT or use a plain multiplication (Toom-3, Karatsuba or basecase), whichever is optimal at the size N'. The interpolation is an inverse fast fourier transform. The resulting set of sums of \N\{x_iy_j, x[i]*y[j]} are added at appropriate offsets to give the final result.

Squaring is the same, but x is the only input so it's one transform at the evaluate stage and the pointwise multiplies are squares. The interpolation is the same.

For a mod 2^N+1 product, an FFT-k is an \N\), O(N^(k/(k-1)))} algorithm, the exponent representing 2^k recursed modular multiplies each \N\,1/2^(k-1)} the size of the original. Each successive k is an asymptotic improvement, but overheads mean each is only faster at bigger and bigger sizes. In the code, FFT_MUL_TABLE and FFT_SQR_TABLE are the thresholds where each k is used. Each new k effectively swaps some multiplying for some shifts, adds and overheads.

A mod 2^N+1 product can be formed with a normal Nx2N bit multiply plus a subtraction, so an FFT and Toom-3 etc can be compared directly. A k=4 FFT at O(N^1.333) can be expected to be the first faster than Toom-3 at O(N^1.465). In practice this is what's found, with FFT_MODF_MUL_THRESHOLD and FFT_MODF_SQR_THRESHOLD being between 300 and 1000 limbs, depending on the CPU. So far it's been found that only very large FFTs recurse into pointwise multiplies above these sizes.

When an FFT is to give a full product, the change of N to 2N doesn't alter the theoretical complexity for a given k, but for the purposes of considering where an FFT might be first used it can be assumed that the FFT is recursing into a normal multiply and that on that basis it's doing 2^k recursed multiplies each \N\,1/2^(k-2)} the size of the inputs, making it \N\), O(N^(k/(k-2)))}. This would mean k=7 at O(N^1.4) would be the first FFT faster than Toom-3. In practice FFT_MUL_THRESHOLD and FFT_SQR_THRESHOLD have been found to be in the k=8 range, somewhere between 3000 and 10000 limbs.

The way N is split into 2^k pieces and then 2M+k+3 is rounded up to a multiple of 2^k and mp_bits_per_limb means that when 2^k>= the effective N is a multiple of \N\,2^(2k-1)} bits. The +k+3 means some values of N just under such a multiple will be rounded to the next. The complexity calculations above assume that a favourable size is used, meaning one which isn't padded through rounding, and it's also assumed that the extra +k+3 bits are negligible at typical FFT sizes.

The practical effect of the \N\,2^(2k-1)} constraint is to introduce a step-effect into measured speeds. For example k=8 will round N up to a multiple of 32768 bits, so for a 32-bit limb there'll be 512 limb groups of sizes for which mpn_mul_n runs at the same speed. Or for k=9 groups of 2048 limbs, k=10 groups of 8192 limbs, etc. In practice it's been found each k is used at quite small multiples of its size constraint and so the step effect is quite noticeable in a time versus size graph.

The threshold determinations currently measure at the mid-points of size steps, but this is sub-optimal since at the start of a new step it can happen that it's better to go back to the previous k for a while. Something more sophisticated for FFT_MUL_TABLE and FFT_SQR_TABLE will be needed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.1.5 Other Multiplication

The 3-way Toom-Cook algorithm described above (see section 16.1.3 Toom-Cook 3-Way Multiplication) generalizes to split into an arbitrary number of pieces, as per Knuth section 4.3.3 algorithm C. This is not currently used, though it's possible a Toom-4 might fit in between Toom-3 and the FFTs. The notes here are merely for interest.

In general a split into r+1 pieces is made, and evaluations and pointwise multiplications done at 2*r+1 points. A 4-way split does 7 pointwise multiplies, 5-way does 9, etc. Asymptotically an (r+1)-way algorithm is \N\, O(N^(log(2*r+1)/log(r+1)))}. Only the pointwise multiplications count towards big-O complexity, but the time spent in the evaluate and interpolate stages grows with r and has a significant practical impact, with the asymptotic advantage of each r realized only at bigger and bigger sizes. The overheads grow as O(N*r), whereas in an r=2^k FFT they grow only as O(N*log(r)).

Knuth algorithm C evaluates at points 0,1,2,...,2*r, but exercise 4 uses -r,...,0,...,r and the latter saves some small multiplies in the evaluate stage (or rather trades them for additions), and has a further saving of nearly half the interpolate steps. The idea is to separate odd and even final coefficients and then perform algorithm C steps C7 and C8 on them separately. The divisors at step C7 become j^2 and the multipliers at C8 become 2*t*j-j^2.

Splitting odd and even parts through positive and negative points can be thought of as using -1 as a square root of unity. If a 4th root of unity was available then a further split and speedup would be possible, but no such root exists for plain integers. Going to complex integers with \N\, i=sqrt(-1)} doesn't help, essentially because in cartesian form it takes three real multiplies to do a complex multiply. The existence of 2^k'th roots of unity in a suitable ring or field lets the fast fourier transform keep splitting and get to O(N*log(r)).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2 Division Algorithms

16.2.1 Single Limb Division
16.2.2 Basecase Division
16.2.3 Divide and Conquer Division
16.2.4 Exact Division
16.2.5 Exact Remainder
16.2.6 Small Quotient Division

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2.1 Single Limb Division

Nx1 divisions from high to low, either with a hardware divide instruction or a multiplication by inverse, whichever is best on a given CPU.

The multiply by inverse follows section 8 of "Division by Invariant Integers using Multiplication" by Granlund and Montgomery (see section B. References) and is implemented as udiv_qrnnd_preinv in `gmp-impl.h'. The idea is to have a fixed-point approximation to 1/d (see invert_limb) and then multiply by the high limb (plus one bit) of the dividend to get a quotient q. With d normalized (high bit set), q is no more than 1 too small. Subtracting q*d from the dividend gives a remainder, and reveals whether q or q-1 is correct.

The result is a division done with two multiplications and four or five arithmetic operations. On CPUs with low latency multipliers this can be much faster than a hardware divide, though the cost of calculating the inverse at the start may mean it's only better on inputs bigger than say 4 or 5 limbs.

When a divisor must be normalized, either for the generic C __udiv_qrnnd_c or the multiply by inverse, the division performed is actually a*2^k by d*2^k where a is the dividend and k is the power necessary to have the high bit of d*2^k set. The bit shifts for the dividend are usually accomplished "on the fly" meaning by extracting the appropriate bits at each step. Done this way the quotient limbs come out aligned ready to store. When only the remainder is wanted, an alternative is to take the dividend limbs unshifted and calculate \N\{r = a \bmod d2^k, r = a mod d*2^k} followed by an extra final step \N\{r2^k \bmod d2^k, r*2^k mod d*2^k}. This can help on CPUs with poor bit shifts or few registers.

The multiply by inverse can be done two limbs at a time. The calculation is basically the same, but the inverse is two limbs and the divisor treated as if padded with a low zero limb. This means more work, since the inverse will need a 2x1s to do that are independent and can therefore be done partly or wholly in parallel. Likewise for a 2x. The net effect is to process two limbs with roughly the same two multiplies worth of latency that one limb at a time gives. This extends to 3 or 4 limbs at a time, though the extra work to apply the inverse will almost certainly soon reach the limits of multiplier throughput.

A similar approach in reverse can be taken to process just half a limb at a time if the divisor is only a half limb. In this case the 1x{}1 multiply for the inverse effectively becomes two \N\1, (1/2)x1} for each limb, which can be a saving on CPUs with a fast half limb multiply, or in fact if the only multiply is a half limb, and especially if it's not pipelined.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2.2 Basecase Division

Basecase Nx{}M division is like long division done by hand, but in base \N\}, 2^mp_bits_per_limb}. See Knuth section 4.3.1 algorithm D, and `mpn/generic/sb_divrem_mn.c'.

Briefly stated, while the dividend remains larger than the divisor, a high quotient limb is formed and the Nx subtracted at the top end of the dividend. With a normalized divisor (most significant bit set), each quotient limb can be formed with a 2x{}1 division and a 1x1 division is by the high limb of the divisor and is done either with a hardware divide or a multiply by inverse (the same as in 16.2.1 Single Limb Division) whichever is faster. Such a quotient is sometimes one too big, requiring an addback of the divisor, but that happens rarely.

With Q=N-M being the number of quotient limbs, this is an O(Q*M) algorithm and will run at a speed similar to a basecase Qx{}M multiplication, differing in fact only in the extra multiply and divide for each of the Q quotient limbs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2.3 Divide and Conquer Division

For divisors larger than DC_THRESHOLD, division is done by dividing. Or to be precise by a recursive divide and conquer algorithm based on work by Moenck and Borodin, Jebelean, and Burnikel and Ziegler (see section B. References).

The algorithm consists essentially of recognising that a 2Nx{}N division can be done with the basecase division algorithm (see section 16.2.2 Basecase Division), but using N/2 limbs as a base, not just a single limb. This way the multiplications that arise are (N/2)x{}(N/2) and can take advantage of Karatsuba and higher multiplication algorithms (see section 16.1 Multiplication). The "digits" of the quotient are formed by recursive Nx{}(N/2) divisions.

If the (N/2)x{}(N/2) multiplies are done with a basecase multiplication then the work is about the same as a basecase division, but with more function call overheads and with some subtractions separated from the multiplies. These overheads mean that it's only when N/2 is above KARATSUBA_MUL_THRESHOLD that divide and conquer is of use.

DC_THRESHOLD is based on the divisor size N, so it will be somewhere above twice KARATSUBA_MUL_THRESHOLD, but how much above depends on the CPU. An optimized mpn_mul_basecase can lower DC_THRESHOLD a little by offering a ready-made advantage over repeated mpn_submul_1 calls.

Divide and conquer is asymptotically O(M(N)*log(N)) where M(N) is the time for an Nx{}N multiplication done with FFTs. The actual time is a sum over multiplications of the recursed sizes, as can be seen near the end of section 2.2 of Burnikel and Ziegler. For example, within the Toom-3 range, divide and conquer is 2.63*M(N). With higher algorithms the M(N) term improves and the multiplier tends to \N\{\log N, log(N)}. In practice, at moderate to large sizes, a 2Nx{}N division is about 2 to 4 times slower than an Nx{}N multiplication.

Newton's method used for division is asymptotically O(M(N)) and should therefore be superior to divide and conquer, but it's believed this would only be for large to very large N.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2.4 Exact Division

A so-called exact division is when the dividend is known to be an exact multiple of the divisor. Jebelean's exact division algorithm uses this knowledge to make some significant optimizations (see section B. References).

The idea can be illustrated in decimal for example with 368154 divided by 543. Because the low digit of the dividend is 4, the low digit of the quotient must be 8. This is arrived at from \N\ 7 \bmod 10, 4*7 mod 10}, using the fact 7 is the modular inverse of 3 (the low digit of the divisor), since \N\ 7 \mathop{\equiv} 1 \bmod 10, 3*7 == 1 mod 10}. So \N\543 = 4344,8*543=4344} can be subtracted from the dividend leaving 363810. Notice the low digit has become zero.

The procedure is repeated at the second digit, with the next quotient digit 7 (\N\ 7 \bmod 10, 7 == 1*7 mod 10}), subtracting \N\543 = 3801,7*543=3801}, leaving 325800. And finally at the third digit with quotient digit 6 (\N\ 7 \bmod 10, 8*7 mod 10}), subtracting \N\543 = 3258,6*543=3258} leaving 0. So the quotient is 678.

Notice however that the multiplies and subtractions don't need to extend past the low three digits of the dividend, since that's enough to determine the three quotient digits. For the last quotient digit no subtraction is needed at all. On a 2Nx{}N division like this one, only about half the work of a normal basecase division is necessary.

For an NxM quotient limbs, the saving over a normal basecase division is in two parts. Firstly, each of the Q quotient limbs needs only one multiply, not a 2x{}1 divide and multiply. Secondly, the crossproducts are reduced when Q>M to Q*M-M*(M+1)/2, or when Q<= to \N\{Q(Q-1)/2, Q*(Q-1)/2. Notice the savings are complementary. If Q is big then many divisions are saved, or if Q is small then the crossproducts reduce to a small number.

The modular inverse used is calculated efficiently by modlimb_invert in `gmp-impl.h'. This does four multiplies for a 32-bit limb, or six for a 64-bit limb. `tune/modlinv.c' has some alternate implementations that might suit processors better at bit twiddling than multiplying.

The sub-quadratic exact division described by Jebelean in "Exact Division with Karatsuba Complexity" is not currently implemented. It uses a rearrangement similar to the divide and conquer for normal division (see section 16.2.3 Divide and Conquer Division), but operating from low to high. A further possibility not currently implemented is "Bidirectional Exact Integer Division" by Krandick and Jebelean which forms quotient limbs from both the high and low ends of the dividend, and can halve once more the number of crossproducts needed in a 2Nx{}N division.

A special case exact division by 3 exists in mpn_divexact_by3, supporting Toom-3 multiplication and mpq canonicalizations. It forms quotient digits with a multiply by the modular inverse of 3 (which is 0xAA..AAB) and uses two comparisons to determine a borrow for the next limb. The multiplications don't need to be on the dependent chain, as long as the effect of the borrows is applied. Only a few optimized assembler implementations currently exist.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2.5 Exact Remainder

If the exact division algorithm is done with a full subtraction at each stage and the dividend isn't a multiple of the divisor, then low zero limbs are produced but with a remainder in the high limbs. For dividend a, divisor d, quotient q, and \N\}, b = 2^mp_bits_per_limb}, then this remainder r is of the form

a = q*d + r*b^n

n represents the number of zero limbs produced by the subtractions, that being the number of limbs produced for q. r will be in the range 0<= and can be viewed as a remainder, but one shifted up by a factor of b^n.

Carrying out full subtractions at each stage means the same number of cross products must be done as a normal division, but there's still some single limb divisions saved. When d is a single limb some simplifications arise, providing good speedups on a number of processors.

mpn_bdivmod, mpn_divexact_by3, mpn_modexact_1_odd and the redc function in mpz_powm differ subtly in how they return r, leading to some negations in the above formula, but all are essentially the same.

Clearly r is zero when a is a multiple of d, and this leads to divisibility or congruence tests which are potentially more efficient than a normal division.

The factor of b^n on r can be ignored in a GCD when d is odd, hence the use of mpn_bdivmod in mpn_gcd, and the use of mpn_modexact_1_odd by mpn_gcd_1 and mpz_kronecker_ui etc (see section 16.3 Greatest Common Divisor).

Montgomery's REDC method for modular multiplications uses operands of the form of \N\, x*b^-n and \N\, y*b^-n} and on calculating \N\) (yb^{-n}), (x*b^-n)*(y*b^-n)} uses the factor of b^n in the exact remainder to reach a product in the same form \N\, (x*y)*b^-n} (see section 16.4.2 Modular Powering).

Notice that r generally gives no useful information about the ordinary remainder a mod d since b^n mod d could be anything. If however b^n == 1 mod d, then r is the negative of the ordinary remainder. This occurs whenever d is a factor of b^n-1, as for example with 3 in mpn_divexact_by3. Other such factors include 5, 17 and 257, but no particular use has been found for this.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.2.6 Small Quotient Division

An NxM is small can be optimized somewhat.

An ordinary basecase division normalizes the divisor by shifting it to make the high bit set, shifting the dividend accordingly, and shifting the remainder back down at the end of the calculation. This is wasteful if only a few quotient limbs are to be formed. Instead a division of just the top 2*Q limbs of the dividend by the top Q limbs of the divisor can be used to form a trial quotient. This requires only those limbs normalized, not the whole of the divisor and dividend.

A multiply and subtract then applies the trial quotient to the M-Q unused limbs of the divisor and N-Q dividend limbs (which includes Q limbs remaining from the trial quotient division). The starting trial quotient can be 1 or 2 too big, but all cases of 2 too big and most cases of 1 too big are detected by first comparing the most significant limbs that will arise from the subtraction. An addback is done if the quotient still turns out to be 1 too big.

This whole procedure is essentially the same as one step of the basecase algorithm done in a Q limb base, though with the trial quotient test done only with the high limbs, not an entire Q limb "digit" product. The correctness of this weaker test can be established by following the argument of Knuth section 4.3.1 exercise 20 but with the \N\{v_2 \GMPhat q > b \GMPhat r + u_2, v2*q>b*r+u2} condition appropriately relaxed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.3 Greatest Common Divisor

16.3.1 Binary GCD
16.3.2 Accelerated GCD
16.3.3 Extended GCD
16.3.4 Jacobi Symbol

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.3.1 Binary GCD

At small sizes GMP uses an O(N^2) binary style GCD. This is described in many textbooks, for example Knuth section 4.5.2 algorithm B. It simply consists of successively reducing operands a and b using gcd(min(a-b)), and also that if a and b are first made odd then abs is even and factors of two can be discarded.

Variants like letting a-b become negative and doing a different next step are of interest only as far as they suit particular CPUs, since on small operands it's machine dependent factors that determine performance.

The Euclidean GCD algorithm, as per Knuth algorithms E and A, reduces using a mod b but this has so far been found to be slower everywhere. One reason the binary method does well is that the implied quotient at each step is usually small, so often only one or two subtractions are needed to get the same effect as a division. Quotients 1, 2 and 3 for example occur 67.7% of the time, see Knuth section 4.5.3 Theorem E.

When the implied quotient is large, meaning b is much smaller than a, then a division is worthwhile. This is the basis for the initial a mod b reductions in mpn_gcd and mpn_gcd_1 (the latter for both Nx1 cases). But after that initial reduction, big quotients occur too rarely to make it worth checking for them.

16.3.2 Accelerated GCD

For sizes above GCD_ACCEL_THRESHOLD, GMP uses the Accelerated GCD algorithm described independently by Weber and Jebelean (the latter as the "Generalized Binary" algorithm), see section B. References. This algorithm is still O(N^2), but is much faster than the binary algorithm since it does fewer multi-precision operations. It consists of alternating the k-ary reduction by Sorenson, and a "dmod" exact remainder reduction.

For operands u and v the k-ary reduction replaces u with n*v-d*u where n and d are single limb values chosen to give two trailing zero limbs on that value, which can be stripped. n and d are calculated using an algorithm similar to half of a two limb GCD (see find_a in `mpn/generic/gcd.c').

When u and v differ in size by more than a certain number of bits, a dmod is performed to zero out bits at the low end of the larger. It consists of an exact remainder style division applied to an appropriate number of bits (see section 16.2.4 Exact Division, and see section 16.2.5 Exact Remainder). This is faster than a k-ary reduction but useful only when the operands differ in size. There's a dmod after each k-ary reduction, and if the dmod leaves the operands still differing in size then it's repeated.

The k-ary reduction step can introduce spurious factors into the GCD calculated, and these are eliminated at the end by taking GCDs with the original inputs gcd(v,g)) using the binary algorithm. Since g is almost always small this takes very little time.

At small sizes the algorithm needs a good implementation of find_a. At larger sizes it's dominated by mpn_addmul_1 applying n and d.

16.3.3 Extended GCD

The extended GCD calculates gcd and also cofactors x and y satisfying \N\b), a*x+b*y=gcd(a,. Lehmer's multi-step improvement of the extended Euclidean algorithm is used. See Knuth section 4.5.2 algorithm L, and `mpn/generic/gcdext.c'. This is an O(N^2) algorithm.

The multipliers at each step are found using single limb calculations for sizes up to GCDEXT_THRESHOLD, or double limb calculations above that. The single limb code is faster but doesn't produce full-limb multipliers, hence not making full use of the mpn_addmul_1 calls.

When a CPU has a data-dependent multiplier, meaning one which is faster on operands with fewer bits, the extra work in the double-limb calculation might only save some looping overheads, leading to a large GCDEXT_THRESHOLD.

Currently the single limb calculation doesn't optimize for the small quotients that often occur, and this can lead to unusually low values of GCDEXT_THRESHOLD, depending on the CPU.

An analysis of double-limb calculations can be found in "A Double-Digit Lehmer-Euclid Algorithm" by Jebelean (see section B. References). The code in GMP was developed independently.

It should be noted that when a double limb calculation is used, it's used for the whole of that GCD, it doesn't fall back to single limb part way through. This is because as the algorithm proceeds, the inputs a and b are reduced, but the cofactors x and y grow, so the multipliers at each step are applied to a roughly constant total number of limbs.

16.3.4 Jacobi Symbol

mpz_jacobi and mpz_kronecker are currently implemented with a simple binary algorithm similar to that described for the GCDs (see section 16.3.1 Binary GCD). They're not very fast when both inputs are large. Lehmer's multi-step improvement or a binary based multi-step algorithm is likely to be better.

When one operand fits a single limb, and that includes mpz_kronecker_ui and friends, an initial reduction is done with either mpn_mod_1 or mpn_modexact_1_odd, followed by the binary algorithm on a single limb. The binary algorithm is well suited to a single limb, and the whole calculation in this case is quite efficient.

In all the routines sign changes for the result are accumulated using some bit twiddling, avoiding table lookups or conditional jumps.

16.4 Powering Algorithms

16.4.1 Normal Powering
16.4.2 Modular Powering

16.4.1 Normal Powering

Normal mpz or mpf powering uses a simple binary algorithm, successively squaring and then multiplying by the base when a 1 bit is seen in the exponent, as per Knuth section 4.6.3. The "left to right" variant described there is used rather than algorithm A, since it's just as easy and can be done with somewhat less temporary memory.

16.4.2 Modular Powering

Modular powering is implemented using a 2^k-ary sliding window algorithm, as per "Handbook of Applied Cryptography" algorithm 14.85 (see section B. References). k is chosen according to the size of the exponent. Larger exponents use larger values of k, the choice being made to minimize the average number of multiplications that must supplement the squaring.

The modular multiplies and squares use either a simple division or the REDC method by Montgomery (see section B. References). REDC is a little faster, essentially saving N single limb divisions in a fashion similar to an exact remainder (see section 16.2.5 Exact Remainder). The current REDC has some limitations. It's only O(N^2) so above POWM_THRESHOLD division becomes faster and is used. It doesn't attempt to detect small bases, but rather always uses a REDC form, which is usually a full size operand. And lastly it's only applied to odd moduli.

16.5 Root Extraction Algorithms

16.5.1 Square Root
16.5.2 Nth Root
16.5.3 Perfect Square
16.5.4 Perfect Power

16.5.1 Square Root

Square roots are taken using the "Karatsuba Square Root" algorithm by Paul Zimmermann (see section B. References). This is expressed in a divide and conquer form, but as noted in the paper it can also be viewed as a discrete variant of Newton's method.

In the Karatsuba multiplication range this is an \N\ M(N/2)),O(1.5*M(N/2)) algorithm, where M(n) is the time to multiply two numbers of n limbs. In the FFT multiplication range this grows to a bound of O(6*M(N/2)). In practice a factor of about 1.5 to 1.8 is found in the Karatsuba and Toom-3 ranges, growing to 2 or 3 in the FFT range.

The algorithm does all its calculations in integers and the resulting mpn_sqrtrem is used for both mpz_sqrt and mpf_sqrt. The extended precision given by mpf_sqrt_ui is obtained by padding with zero limbs.

16.5.2 Nth Root

Integer Nth roots are taken using Newton's method with the following iteration, where A is the input and n is the root to be taken.

         1         A
a[i+1] = - * ( --------- + (n-1)*a[i] )
         n     a[i]^(n-1)

The initial approximation a[1] is generated bitwise by successively powering a trial root with or without new 1 bits, aiming to be just above the true root. The iteration converges quadratically when started from a good approximation. When n is large more initial bits are needed to get good convergence. The current implementation is not particularly well optimized.

16.5.3 Perfect Square

mpz_perfect_square_p is able to quickly exclude most non-squares by checking whether the input is a quadratic residue modulo some small integers.

The first test is modulo 256 which means simply examining the least significant byte. Only 44 different values occur as the low byte of a square, so 82.8% of non-squares can be immediately excluded. Similar tests modulo primes from 3 to 29 exclude 99.5% of those remaining, or if a limb is 64 bits then primes up to 53 are used, excluding 99.99%. A single Nx{1 remainder using PP from `gmp-impl.h' quickly gives all these remainders.

A square root must still be taken for any value that passes the residue tests, to verify it's really a square and not one of the 0.086% (or 0.000156% for 64 bits) non-squares that get through. See section 16.5.1 Square Root.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.5.4 Perfect Power

Detecting perfect powers is required by some factorization algorithms. Currently mpz_perfect_power_p is implemented using repeated Nth root extractions, though naturally only prime roots need to be considered. (See section 16.5.2 Nth Root.)

If a prime divisor p with multiplicity e can be found, then only roots which are divisors of e need to be considered, much reducing the work necessary. To this end divisibility by a set of small primes is checked.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.6 Radix Conversion

Radix conversions are less important than other algorithms. A program dominated by conversions should probably use a different data representation.

16.6.1 Binary to Radix
16.6.2 Radix to Binary

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.6.1 Binary to Radix

Conversions from binary to a power-of-2 radix use a simple and fast O(N) bit extraction algorithm.

Conversions from binary to other radices use repeated divisions, first by the biggest power of the radix that fits in a single limb, then by the radix on the remainders. This is an O(N^2) algorithm and can be quite time-consuming on large inputs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.6.2 Radix to Binary

Conversions from a power-of-2 radix into binary use a simple and fast O(N) bitwise concatenation algorithm.

Conversions from other radices use repeated multiplications, first accumulating as many digits as fit in a limb, then doing an Nx{}1 multi-precision multiplication. This is O(N^2) and is certainly sub-optimal on sizes above the Karatsuba multiply threshold.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.7 Other Algorithms

16.7.1 Factorial
16.7.2 Binomial Coefficients
16.7.3 Fibonacci Numbers
16.7.4 Lucas Numbers

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.7.1 Factorial

Factorials n! are calculated by a simple product from 1 to n, but arranged into certain sub-products.

First as many factors as fit in a limb are accumulated, then two of those multiplied to give a 2-limb product. When two 2-limb products are ready they're multiplied to a 4-limb product, and when two 4-limbs are ready they're multiplied to an 8-limb product, etc. A stack of outstanding products is built up, with two of the same size multiplied together when ready.

Arranging for multiplications to have operands the same (or nearly the same) size means the Karatsuba and higher multiplication algorithms can be used. And even on sizes below the Karatsuba threshold an Nx{}N multiply will give a basecase multiply more to work on.

An obvious improvement not currently implemented would be to strip factors of 2 from the products and apply them at the end with a bit shift. Another possibility would be to determine the prime factorization of the result (which can be done easily), and use a powering method, at each stage squaring then multiplying in those primes with a 1 in their exponent at that point. The advantage would be some multiplies turned into squares.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.7.2 Binomial Coefficients

Binomial coefficients \N\\atop{k}\right), C(n, are calculated by first arranging k <= using \N\\atop{k\right) = \left({n}\atop{n-k}\right), C(n,n-k)} if necessary, and then evaluating the following product simply from i=2 to i=k.

                      k  (n-k+i)
C(n,k) =  (n-k+1) * prod -------
                     i=2    i

It's easy to show that each denominator i will divide the product so far, so the exact division algorithm is used (see section 16.2.4 Exact Division).

The numerators n-k+i and denominators i are first accumulated into as many fit a limb, to save multi-precision operations, though for mpz_bin_ui this applies only to the divisors, since n is an mpz_t and n-k+i in general won't fit in a limb at all.

An obvious improvement would be to strip factors of 2 from each multiplier and divisor and count them separately, to be applied with a bit shift at the end. Factors of 3 and perhaps 5 could even be handled similarly. Another possibility, if n is not too big, would be to determine the prime factorization of the result based on the factorials involved, and power up those primes appropriately. This would help most when k is near n/2.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.7.3 Fibonacci Numbers

The Fibonacci functions mpz_fib_ui and mpz_fib2_ui are designed for calculating isolated F[n] or F[n],\N\,F[n-1]} values efficiently.

For small n, a table of single limb values in __gmp_fib_table is used. On a 32-bit limb this goes up to \N\,F[47]}, or on a 64-bit limb up to \N\,F[93]}. For convenience the table starts at \N\,F[-1]}.

Beyond the table, values are generated with a binary powering algorithm, calculating a pair F[n] and \N\,F[n-1]} working from high to low across the bits of n. The formulas used are

F[2k+1] = 4*F[k]^2 - F[k-1]^2 + 2*(-1)^k
F[2k-1] =   F[k]^2 + F[k-1]^2

F[2k] = F[2k+1] - F[2k-1]

At each step, k is the high b bits of n. If the next bit of n is 0 then \N\,F[2k]},\N\,F[2k-1]} is used, or if it's a 1 then \N\,F[2k+1]},\N\,F[2k]} is used, and the process repeated until all bits of n are incorporated. Notice these formulas require just two squares per bit of n.

It'd be possible to handle the first few n above the single limb table with simple additions, using the defining Fibonacci recurrence \N\ = F_k + F_{k-1}, F[k+1]=F[k]+F[k-1]}, but this is not done since it usually turns out to be faster for only about 10 or 20 values of n, and including a block of code for just those doesn't seem worthwhile. If they really mattered it'd be better to extend the data table.

Using a table avoids lots of calculations on small numbers, and makes small n go fast. A bigger table would make more small n go fast, it's just a question of balancing size against desired speed. For GMP the code is kept compact, with the emphasis primarily on a good powering algorithm.

mpz_fib2_ui returns both F[n] and \N\,F[n-1]}, but mpz_fib_ui is only interested in F[n]. In this case the last step of the algorithm can become one multiply instead of two squares. One of the following two formulas is used, according as n is odd or even.

F[2k]   = F[k]*(F[k]+2F[k-1])

F[2k+1] = (2F[k]+F[k-1])*(2F[k]-F[k-1]) + 2*(-1)^k

\N\,F[2k+1]} here is the same as above, just rearranged to be a multiply. For interest, the 2*(-1)^k term both here and above can be applied just to the low limb of the calculation, without a carry or borrow into further limbs, which saves some code size. See comments with mpz_fib_ui and the internal mpn_fib2_ui for how this is done.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.7.4 Lucas Numbers

mpz_lucnum2_ui derives a pair of Lucas numbers from a pair of Fibonacci numbers with the following simple formulas.

L[k]   =   F[k] + 2*F[k-1]
L[k-1] = 2*F[k] -   F[k-1]

mpz_lucnum_ui is only interested in L[n], and some work can be saved. Trailing zero bits on n can be handled with a single square each.

L[2k] = L[k]^2 - 2*(-1)^k

And the lowest 1 bit can be handled with one multiply of a pair of Fibonacci numbers, similar to what mpz_fib_ui does.

L[2k+1] = 5*F[k-1]*(2*F[k]+F[k-1]) - 4*(-1)^k

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8 Assembler Coding

The assembler subroutines in GMP are the most significant source of speed at small to moderate sizes. At larger sizes algorithm selection becomes more important, but of course speedups in low level routines will still speed up everything proportionally.

Carry handling and widening multiplies that are important for GMP can't be easily expressed in C. GCC asm blocks help a lot and are provided in `longlong.h', but hand coding low level routines invariably offers a speedup over generic C by a factor of anything from 2 to 10.

16.8.1 Code Organisation
16.8.2 Assembler Basics
16.8.3 Carry Propagation
16.8.4 Cache Handling
16.8.5 Floating Point
16.8.6 SIMD Instructions
16.8.7 Software Pipelining
16.8.8 Loop Unrolling

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8.1 Code Organisation

The various `mpn' subdirectories contain machine-dependent code, written in C or assembler. The `mpn/generic' subdirectory contains default code, used when there's no machine-specific version of a particular file.

Each `mpn' subdirectory is for an ISA family. Generally 32-bit and 64-bit variants in a family cannot share code and will have separate directories. Within a family further subdirectories may exist for CPU variants.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8.2 Assembler Basics

mpn_addmul_1 and mpn_submul_1 are the most important routines for overall GMP performance. All multiplications and divisions come down to repeated calls to these. mpn_add_n, mpn_sub_n, mpn_lshift and mpn_rshift are next most important.

On some CPUs assembler versions of the internal functions mpn_mul_basecase and mpn_sqr_basecase give significant speedups, mainly through avoiding function call overheads. They can also potentially make better use of a wide superscalar processor.

The restrictions on overlaps between sources and destinations (see section 8. Low-level Functions) are designed to facilitate a variety of implementations. For example, knowing mpn_add_n won't have partly overlapping sources and destination means reading can be done far ahead of writing on superscalar processors, and loops can be vectorized on a vector processor, depending on the carry handling.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8.3 Carry Propagation

The problem that presents most challenges in GMP is propagating carries from one limb to the next. In functions like mpn_addmul_1 and mpn_add_n, carries are the only dependencies between limb operations.

On processors with carry flags, a straightforward CISC style adc is generally best. AMD K6 mpn_addmul_1 however is an example of an unusual set of circumstances where a branch works out better.

On RISC processors generally an add and compare for overflow is used. This sort of thing can be seen in `mpn/generic/aors_n.c'. Some carry propagation schemes require 4 instructions, meaning at least 4 cycles per limb, but other schemes may use just 1 or 2. On wide superscalar processors performance may be completely determined by the number of dependent instructions between carry-in and carry-out for each limb.

On vector processors good use can be made of the fact that a carry bit only very rarely propagates more than one limb. When adding a single bit to a limb, there's only a carry out if that limb was 0xFF...FF which on random data will be only 1 in \N\}, 2^mp_bits_per_limb}. `mpn/cray/add_n.c' is an example of this, it adds all limbs in parallel, adds one set of carry bits in parallel and then only rarely needs to fall through to a loop propagating further carries.

On the x86s, GCC (as of version 2.95.2) doesn't generate particularly good code for the RISC style idioms that are necessary to handle carry bits in C. Often conditional jumps are generated where adc or sbb forms would be better. And so unfortunately almost any loop involving carry bits needs to be coded in assembler for best results.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8.4 Cache Handling

GMP aims to perform well both on operands that fit entirely in L1 cache and those that don't. In the assembler subroutines this means prefetching, either always or when large enough operands are presented.

Pre-fetching sources combines well with loop unrolling, since a prefetch can be initiated once per unrolled loop (or more than once if the loop processes more than one cache line).

Pre-fetching destinations won't be necessary if the CPU has a big enough store queue. Older processors without a write-allocate L1 however will want destination prefetching, to avoid repeated write-throughs, unless they can keep up with the rate at which destination limbs are produced.

The distance ahead to prefetch will be determined by the rate data is processed versus the time it takes to bring a line up to L1. Naturally the net data rate from L2 or RAM will always limit the rate of data processing. Prefetch distance may also be limited by the number of prefetches the processor can have in progress at any one time.

If a special prefetch instruction doesn't exist then a plain load can be used, so long as the CPU supports out-of-order loads. But this may mean having a second copy of a loop so that the last few limbs can be processed without prefetching, since reading past the end of an operand must be avoided.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8.5 Floating Point

Floating point arithmetic is used in GMP for multiplications on CPUs with poor integer multipliers. Floating point generally doesn't suit other operations like additions or shifts, due to difficulties implementing carry handling.

With IEEE 53-bit double precision floats, integer multiplications producing up to 53 bits will give exact results. Breaking a multiplication into 16x48} bit pieces is convenient. With some care though three 21x53} bit products can be used to do a 64x32 parts uses the sign bit.

Generally limbs want to be treated as unsigned, but on some CPUs floating point conversions only treat integers as signed. Copying through a zero extended memory region or testing and adjusting for a sign bit may be necessary.

Currently floating point FFTs aren't used for large multiplications. On some processors they probably have a good chance of being worthwhile, if great care is taken with precision control.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8.6 SIMD Instructions

The single-instruction multiple-data support in current microprocessors is aimed at signal processing algorithms where each data point can be treated more or less independently. There's generally not much support for propagating the sort of carries that arise in GMP.

SIMD multiplications of say four 16x{}16 bit multiplies only do as much work as one 32x{}32 from GMP's point of view, and need some shifts and adds besides. But of course if say the SIMD form is fully pipelined and uses less instruction decoding then it may still be worthwhile.

On the 80x86 chips, MMX has so far found a use in mpn_rshift and mpn_lshift since it allows 64-bit operations, and is used in a special case for 16-bit multipliers in the P55 mpn_mul_1. 3DNow and SSE haven't found a use so far.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8.7 Software Pipelining

Software pipelining consists of scheduling instructions around the branch point in a loop. For example a loop taking a checksum of an array of limbs might have a load and an add, but the load wouldn't be for that add, rather for the one next time around the loop. Each load then is effectively scheduled back in the previous iteration, allowing latency to be hidden.

Naturally this is wanted only when doing things like loads or multiplies that take a few cycles to complete, and only where a CPU has multiple functional units so that other work can be done while waiting.

A pipeline with several stages will have a data value in progress at each stage and each loop iteration moves them along one stage. This is like juggling.

Within the loop some moves between registers may be necessary to have the right values in the right places for each iteration. Loop unrolling can help this, with each unrolled block able to use different registers for different values, even if some shuffling is still needed just before going back to the top of the loop.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

16.8.8 Loop Unrolling

Loop unrolling consists of replicating code so that several limbs are processed in each loop. At a minimum this reduces loop overheads by a corresponding factor, but it can also allow better register usage, for example alternately using one register combination and then another. Judicious use of m4 macros can help avoid lots of duplication in the source code.

Unrolling is commonly done to a power of 2 multiple so the number of unrolled loops and the number of remaining limbs can be calculated with a shift and mask. But other multiples can be used too, just by subtracting each n limbs processed from a counter and waiting for less than n remaining (or offsetting the counter by n so it goes negative when there's less than n remaining).

The limbs not a multiple of the unrolling can be handled in various ways, for example

  • A simple loop at the end (or the start) to process the excess. Care will be wanted that it isn't too much slower than the unrolled part.

  • A set of binary tests, for example after an 8-limb unrolling, test for 4 more limbs to process, then a further 2 more or not, and finally 1 more or not. This will probably take more code space than a simple loop.

  • A switch statement, providing separate code for each possible excess, for example an 8-limb unrolling would have separate code for 0 remaining, 1 remaining, etc, up to 7 remaining. This might take a lot of code, but may be the best way to optimize all cases in combination with a deep pipelined loop.

  • A computed jump into the middle of the loop, thus making the first iteration handle the excess. This should make times smoothly increase with size, which is attractive, but setups for the jump and adjustments for pointers can be tricky and could become quite difficult in combination with deep pipelining.

One way to write the setups and finishups for a pipelined unrolled loop is simply to duplicate the loop at the start and the end, then delete instructions at the start which have no valid antecedents, and delete instructions at the end whose results are unwanted. Sizes not a multiple of the unrolling can then be handled as desired.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17. Internals

This chapter is provided only for informational purposes and the various internals described here may change in future GMP releases. Applications expecting to be compatible with future releases should use only the documented interfaces described in previous chapters.

17.1 Integer Internals
17.2 Rational Internals
17.3 Float Internals
17.4 Raw Output Internals
17.5 C++ Interface Internals

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17.1 Integer Internals

mpz_t variables represent integers using sign and magnitude, in space dynamically allocated and reallocated. The fields are as follows.

_mp_size
The number of limbs, or the negative of that when representing a negative integer. Zero is represented by _mp_size set to zero, in which case the _mp_d data is unused.

_mp_d
A pointer to an array of limbs which is the magnitude. These are stored "little endian" as per the mpn functions, so _mp_d[0] is the least significant limb and _mp_d[ABS(_mp_size)-1] is the most significant. Whenever _mp_size is non-zero, the most significant limb is non-zero.

Currently there's always at least one limb allocated, so for instance mpz_set_ui never needs to reallocate, and mpz_get_ui can fetch _mp_d[0] unconditionally (though its value is then only wanted if _mp_size is non-zero).

_mp_alloc
_mp_alloc is the number of limbs currently allocated at _mp_d, and naturally _mp_alloc >= ABS(_mp_size). When an mpz routine is about to (or might be about to) increase _mp_size, it checks _mp_alloc to see whether there's enough space, and reallocates if not. MPZ_REALLOC is generally used for this.

The various bitwise logical functions like mpz_and behave as if negative values were twos complement. But sign and magnitude is always used internally, and necessary adjustments are made during the calculations. Sometimes this isn't pretty, but sign and magnitude are best for other routines.

Some internal temporary variables are setup with MPZ_TMP_INIT and these have _mp_d space obtained from TMP_ALLOC rather than the memory allocation functions. Care is taken to ensure that these are big enough that no reallocation is necessary (since it would have unpredictable consequences).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17.2 Rational Internals

mpq_t variables represent rationals using an mpz_t numerator and denominator (see section 17.1 Integer Internals).

The canonical form adopted is denominator positive (and non-zero), no common factors between numerator and denominator, and zero uniquely represented as 0/1.

It's believed that casting out common factors at each stage of a calculation is best in general. A GCD is an O(N^2) operation so it's better to do a few small ones immediately than to delay and have to do a big one later. Knowing the numerator and denominator have no common factors can be used for example in mpq_mul to make only two cross GCDs necessary, not four.

This general approach to common factors is badly sub-optimal in the presence of simple factorizations or little prospect for cancellation, but GMP has no way to know when this will occur. As per 3.9 Efficiency, that's left to applications. The mpq_t framework might still suit, with mpq_numref and mpq_denref for direct access to the numerator and denominator, or of course mpz_t variables can be used directly.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

17.3 Float Internals

Efficient calculation is the primary aim of GMP floats and the use of whole limbs and simple rounding facilitates this.

mpf_t floats have a variable precision mantissa and a single machine word signed exponent. The mantissa is represented using sign and magnitude.

   most                   least
significant            significant
   limb                   limb

                            _mp_d
 |---- _mp_exp --->           |
  _____ _____ _____ _____ _____
 |_____|_____|_____|_____|_____|
                   . <------------ radix point

  <-------- _mp_size --------->

The fields are as follows.

_mp_size
The number of limbs currently in use, or the negative of that when representing a negative value. Zero is represented by _mp_size and _mp_exp both set to zero, and in that case the _mp_d data is unused. (In the future _mp_exp might be undefined when representing zero.)

_mp_prec
The precision of the mantissa, in limbs. In any calculation the aim is to produce _mp_prec limbs of result (the most significant being non-zero).

_mp_d
A pointer to the array of limbs which is the absolute value of the mantissa. These are stored "little endian" as per the mpn functions, so _mp_d[0] is the least significant limb and _mp_d[ABS(_mp_size)-1] the most significant.

The most significant limb is always non-zero, but there are no other restrictions on its value, in particular the highest 1 bit can be anywhere within the limb.

_mp_prec+1 limbs are allocated to _mp_d, the extra limb being for convenience (see below). There are no reallocations during a calculation, only in a change of precision with mpf_set_prec.

_mp_exp
The exponent, in limbs, determining the location of the implied radix point. Zero means the radix point is just above the most significant limb. Positive values mean a radix point offset towards the lower limbs and hence a value >=, as for example in the diagram above. Negative exponents mean a radix point further above the highest limb.

Naturally the exponent can be any value, it doesn't have to fall within the limbs as the diagram shows, it can be a long way above or a long way below. Limbs other than those included in the {_mp_d,_mp_size} data are treated as zero.

The following various points should be noted.

Low Zeros
The least significant limbs _mp_d[0] etc can be zero, though such low zeros can always be ignored. Routines likely to produce low zeros check and avoid them to save time in subsequent calculations, but for most routines they're quite unlikely and aren't checked.

Mantissa Size Range
The _mp_size count of limbs in use can be less than _mp_prec if the value can be represented in less. This means low precision values or small integers stored in a high precision mpf_t can still be operated on efficiently.

_mp_size can also be greater than _mp_prec. Firstly a value is allowed to use all of the _mp_prec+1 limbs available at _mp_d, and secondly when mpf_set_prec_raw lowers _mp_prec it leaves _mp_size unchanged and so the size can be arbitrarily bigger than _mp_prec.

Rounding
All rounding is done on limb boundaries. Calculating _mp_prec limbs with the high non-zero will ensure the application requested minimum precision is obtained.

The use of simple "trunc" rounding towards zero is efficient, since there's no need to examine extra limbs and increment or decrement.

Bit Shifts
Since the exponent is in limbs, there are no bit shifts in basic operations like mpf_add and mpf_mul. When differing exponents are encountered all that's needed is to adjust pointers to line up the relevant limbs.

Of course mpf_mul_2exp and mpf_div_2exp will require bit shifts, but the choice is between an exponent in limbs which requires shifts there, or one in bits which requires them almost everywhere else.

Use of _mp_prec+1 Limbs
The extra limb on _mp_d (_mp_prec+1 rather than just _mp_prec) helps when an mpf routine might get a carry from its operation. mpf_add for instance will do an mpn_add of _mp_prec limbs. If there's no carry then that's the result, but if there is a carry then it's stored in the extra limb of space and _mp_size becomes _mp_prec+1.

Whenever _mp_prec+1 limbs are held in a variable, the low limb is not needed for the intended precision, only the _mp_prec high limbs. But zeroing it out or moving the rest down is unnecessary. Subsequent routines reading the value will simply take the high limbs they need, and this will be _mp_prec if their target has that same precision. This is no more than a pointer adjustment, and must be checked anyway since the destination precision can be different from the sources.

Copy functions like mpf_set will retain a full _mp_prec+1 limbs if available. This ensures that a variable which has _mp_size equal to _mp_prec+1 will get its full exact value copied. Strictly speaking this is unnecessary since only _mp_prec limbs are needed for the application's requested precision, but it's considered that an mpf_set from one variable into another of the same precision ought to produce an exact copy.

Application Precisions
__GMPF_BITS_TO_PREC converts an application requested precision to an _mp_prec. The value in bits is rounded up to a whole limb then an extra limb is added since the most significant limb of _mp_d is only non-zero and therefore might contain only one bit.

__GMPF_PREC_TO_BITS does the reverse conversion, and removes the extra limb from _mp_prec before converting to bits. The net effect of reading back with mpf_get_prec is simply the precision rounded up to a multiple of mp_bits_per_limb.

Note that the extra limb added here for the high only being non-zero is in addition to the extra limb allocated to _mp_d. For example with a 32-bit limb, an application request for 250 bits will be rounded up to 8 limbs, then an extra added for the high being only non-zero, giving an _mp_prec of 9. _mp_d then gets 10 limbs allocated. Reading back with mpf_get_prec will take _mp_prec subtract 1 limb and multiply by 32, giving 256 bits.

Strictly speaking, the fact the high limb has at least one bit means that a float with, say, 3 limbs of 32-bits each will be holding at least 65 bits, but for the purposes of mpf_t it's considered simply to be 64 bits, a nice multiple of the limb size.

17.4 Raw Output Internals

mpz_out_raw uses the following format.

+------+------------------------+
| size |       data bytes       |
+------+------------------------+

The size is 4 bytes written most significant byte first, being the number of subsequent data bytes, or the twos complement negative of that when a negative integer is represented. The data bytes are the absolute value of the integer, written most significant byte first.

The most significant data byte is always non-zero, so the output is the same on all systems, irrespective of limb size.

In GMP 1, leading zero bytes were written to pad the data bytes to a multiple of the limb size. mpz_inp_raw will still accept this, for compatibility.

The use of "big endian" for both the size and data fields is deliberate, it makes the data easy to read in a hex dump of a file. Unfortunately it also means that the limb data must be reversed when reading or writing, so neither a big endian nor little endian system can just read and write _mp_d.

17.5 C++ Interface Internals

A system of expression templates is used to ensure something like a=b+c turns into a simple call to mpz_add etc. For mpf_class and mpfr_class the scheme also ensures the precision of the final destination is used for any temporaries within a statement like f=w*x+y*z. These are important features which a naive implementation cannot provide.

A simplified description of the scheme follows. The true scheme is complicated by the fact that expressions have different return types. For detailed information, refer to the source code.

To perform an operation, say, addition, we first define a "function object" evaluating it,

struct __gmp_binary_plus
{
  static void eval(mpf_t f, mpf_t g, mpf_t h) { mpf_add(f, g, h); }
};

And an "additive expression" object,

__gmp_expr<__gmp_binary_expr<mpf_class, mpf_class, __gmp_binary_plus> >
operator+(const mpf_class &f, const mpf_class &g)
{
  return __gmp_expr
    <__gmp_binary_expr<mpf_class, mpf_class, __gmp_binary_plus> >(f, g);
}

The seemingly redundant __gmp_expr<__gmp_binary_expr<...>> is used to encapsulate any possible kind of expression into a single template type. In fact even mpf_class etc are typedef specializations of __gmp_expr.

Next we define assignment of __gmp_expr to mpf_class.

template <class T>
mpf_class & mpf_class::operator=(const __gmp_expr<T> &expr)
{
  expr.eval(this->get_mpf_t(), this->precision());
  return *this;
}

template <class Op>
void __gmp_expr<__gmp_binary_expr<mpf_class, mpf_class, Op> >::eval
(mpf_t f, unsigned long int precision)
{
  Op::eval(f, expr.val1.get_mpf_t(), expr.val2.get_mpf_t());
}

where expr.val1 and expr.val2 are references to the expression's operands (here expr is the __gmp_binary_expr stored within the __gmp_expr).

This way, the expression is actually evaluated only at the time of assignment, when the required precision (that of f) is known. Furthermore the target mpf_t is now available, thus we can call mpf_add directly with f as the output argument.

Compound expressions are handled by defining operators taking subexpressions as their arguments, like this:

template <class T, class U>
__gmp_expr
<__gmp_binary_expr<__gmp_expr<T>, __gmp_expr<U>, __gmp_binary_plus> >
operator+(const __gmp_expr<T> &expr1, const __gmp_expr<U> &expr2)
{
  return __gmp_expr
    <__gmp_binary_expr<__gmp_expr<T>, __gmp_expr<U>, __gmp_binary_plus> >
    (expr1, expr2);
}

And the corresponding specializations of __gmp_expr::eval:

template <class T, class U, class Op>
void __gmp_expr
<__gmp_binary_expr<__gmp_expr<T>, __gmp_expr<U>, Op> >::eval
(mpf_t f, unsigned long int precision)
{
  // declare two temporaries
  mpf_class temp1(expr.val1, precision), temp2(expr.val2, precision);
  Op::eval(f, temp1.get_mpf_t(), temp2.get_mpf_t());
}

The expression is thus recursively evaluated to any level of complexity and all subexpressions are evaluated to the precision of f.

A. Contributors

Torbjorn Granlund wrote the original GMP library and is still developing and maintaining it. Several other individuals and organizations have contributed to GMP in various ways. Here is a list in chronological order:

Gunnar Sjoedin and Hans Riesel helped with mathematical problems in early versions of the library.

Richard Stallman contributed to the interface design and revised the first version of this manual.

Brian Beuning and Doug Lea helped with testing of early versions of the library and made creative suggestions.

John Amanatides of York University in Canada contributed the function mpz_probab_prime_p.

Paul Zimmermann of Inria sparked the development of GMP 2, with his comparisons between bignum packages.

Ken Weber (Kent State University, Universidade Federal do Rio Grande do Sul) contributed mpz_gcd, mpz_divexact, mpn_gcd, and mpn_bdivmod, partially supported by CNPq (Brazil) grant 301314194-2.

Per Bothner of Cygnus Support helped to set up GMP to use Cygnus' configure. He has also made valuable suggestions and tested numerous intermediary releases.

Joachim Hollman was involved in the design of the mpf interface, and in the mpz design revisions for version 2.

Bennet Yee contributed the initial versions of mpz_jacobi and mpz_legendre.

Andreas Schwab contributed the files `mpn/m68k/lshift.S' and `mpn/m68k/rshift.S' (now in `.asm' form).

The development of floating point functions of GNU MP 2, were supported in part by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO (POlynomial System SOlving).

GNU MP 2 was finished and released by SWOX AB, SWEDEN, in cooperation with the IDA Center for Computing Sciences, USA.

Robert Harley of Inria, France and David Seal of ARM, England, suggested clever improvements for population count.

Robert Harley also wrote highly optimized Karatsuba and 3-way Toom multiplication functions for GMP 3. He also contributed the ARM assembly code.

Torsten Ekedahl of the Mathematical department of Stockholm University provided significant inspiration during several phases of the GMP development. His mathematical expertise helped improve several algorithms.

Paul Zimmermann wrote the Divide and Conquer division code, the REDC code, the REDC-based mpz_powm code, the FFT multiply code, and the Karatsuba square root. The ECMNET project Paul is organizing was a driving force behind many of the optimizations in GMP 3.

Linus Nordberg wrote the new configure system based on autoconf and implemented the new random functions.

Kent Boortz made the Macintosh port.

Kevin Ryde worked on a number of things: optimized x86 code, m4 asm macros, parameter tuning, speed measuring, the configure system, function inlining, divisibility tests, bit scanning, Jacobi symbols, Fibonacci and Lucas number functions, printf and scanf functions, perl interface, demo expression parser, the algorithms chapter in the manual, gmpasm-mode.el, and various miscellaneous improvements elsewhere.

Steve Root helped write the optimized alpha 21264 assembly code.

Gerardo Ballabio wrote the `gmpxx.h' C++ class interface and the C++ istream input routines.

GNU MP 4.0.1 was finished and released by Torbjorn Granlund and Kevin Ryde. Torbjorn's work was partially funded by the IDA Center for Computing Sciences, USA.

(This list is chronological, not ordered after significance. If you have contributed to GMP but are not listed above, please tell tege@swox.com about the omission!)

B. References

B.1 Books

  • Henri Cohen, "A Course in Computational Algebraic Number Theory", Graduate Texts in Mathematics number 138, Springer-Verlag, 1993.

  • Donald E. Knuth, "The Art of Computer Programming", volume 2, "Seminumerical Algorithms", 3rd edition, Addison-Wesley, 1998.

  • John D. Lipson, "Elements of Algebra and Algebraic Computing", The Benjamin Cummings Publishing Company Inc, 1981.

  • Alfred J. Menezes, Paul C. van Oorschot and Scott A. Vanstone, "Handbook of Applied Cryptography", http://www.cacr.math.uwaterloo.ca/hac/

  • Richard M. Stallman, "Using and Porting GCC", Free Software Foundation, 1999, available online http://www.gnu.org/software/gcc/onlinedocs/, and in the GCC package ftp://ftp.gnu.org/gnu/gcc/

B.2 Papers

  • Christoph Burnikel and Joachim Ziegler, "Fast Recursive Division", Max-Planck-Institut fuer Informatik Research Report MPI-I-98-1-022, { http://www.mpi-sb.mpg.de/~ziegler/TechRep.ps.gz

  • Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant Integers using Multiplication", in Proceedings of the SIGPLAN PLDI'94 Conference, June 1994. Also available ftp://ftp.cwi.nl/pub/pmontgom/divcnst.psa4.gz (and .psl.gz).

  • Peter L. Montgomery, "Modular Multiplication Without Trial Division", in Mathematics of Computation, volume 44, number 170, April 1985.

  • Tudor Jebelean, "An algorithm for exact division", Journal of Symbolic Computation, volume 15, 1993, pp. 169-180. Research report version available {} ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1992/92-35.ps.gz

  • Tudor Jebelean, "Exact Division with Karatsuba Complexity - Extended Abstract", RISC-Linz technical report 96-31, {} ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1996/96-31.ps.gz

  • Tudor Jebelean, "Practical Integer Division with Karatsuba Complexity", ISSAC 97, pp. 339-341. Technical report available {} ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1996/96-29.ps.gz

  • Tudor Jebelean, "A Generalization of the Binary GCD Algorithm", ISSAC 93, pp. 111-116. Technical report version available {} ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1993/93-01.ps.gz

  • Tudor Jebelean, "A Double-Digit Lehmer-Euclid Algorithm for Finding the GCD of Long Integers", Journal of Symbolic Computation, volume 19, 1995, pp. 145-157. Technical report version also available {} ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1992/92-69.ps.gz

  • Werner Krandick and Tudor Jebelean, "Bidirectional Exact Integer Division", Journal of Symbolic Computation, volume 21, 1996, pp. 441-455. Early technical report version also available ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1994/94-50.ps.gz

  • R. Moenck and A. Borodin, "Fast Modular Transforms via Division", Proceedings of the 13th Annual IEEE Symposium on Switching and Automata Theory, October 1972, pp. 90-96. Reprinted as "Fast Modular Transforms", Journal of Computer and System Sciences, volume 8, number 3, June 1974, pp. 366-386.

  • Arnold Schönhage and Volker Strassen, "Schnelle Multiplikation grosser Zahlen", Computing 7, 1971, pp. 281-292.

  • Kenneth Weber, "The accelerated integer GCD algorithm", ACM Transactions on Mathematical Software, volume 21, number 1, March 1995, pp. 111-122.

  • Paul Zimmermann, "Karatsuba Square Root", INRIA Research Report 3805, November 1999, http://www.inria.fr/RRRT/RR-3805.html

  • Paul Zimmermann, "A Proof of GMP Fast Division and Square Root Implementations", {} http://www.loria.fr/~zimmerma/papers/proof-div-sqrt.ps.gz

  • Dan Zuras, "On Squaring and Multiplying Large Integers", ARITH-11: IEEE Symposium on Computer Arithmetic, 1993, pp. 260 to 271. Reprinted as "More on Multiplying and Squaring Large Integers", IEEE Transactions on Computers, volume 43, number 8, August 1994, pp. 899-908.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

C. GNU Free Documentation License

Version 1.1, March 2000

Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

    The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

    A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

    The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

    4. Preserve all the copyright notices of the Document.

    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

    8. Include an unaltered copy of this License.

    9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

    11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.

    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

    13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.

    14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

C.1 ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Concept Index

Jump to: A B C D E F G H I J K L M N O P R S T U V W

 | Index Entry | Section
A |  |
 | ABI | 2.2 ABI and ISA
 | About this manual | 1.1 How to use this Manual
 | Algorithms | 16. Algorithms
 | alloca | 2.1 Build Options
 | Allocation of memory | 14. Custom Allocation
 | Anonymous FTP of latest version | 1. Introduction to GNU MP
 | Application Binary Interface | 2.2 ABI and ISA
 | Arithmetic functions | 5.5 Arithmetic Functions
 | Arithmetic functions | 6.3 Arithmetic Functions
 | Arithmetic functions | 7.5 Arithmetic Functions
 | Assignment functions | 5.2 Assignment Functions
 | Assignment functions | 7.2 Assignment Functions
 | Autoconf detections | 3.12 Autoconf
B |  |
 | Basics | 3. GMP Basics
 | Berkeley MP compatible functions | 13. Berkeley MP Compatible Functions
 | Binomial coefficient functions | 5.9 Number Theoretic Functions
 | Bit manipulation functions | 5.11 Logical and Bit Manipulation Functions
 | Bit shift left | 5.5 Arithmetic Functions
 | Bit shift right | 5.6 Division Functions
 | Bits per limb | 3.7 Useful Macros and Constants
 | BSD MP compatible functions | 13. Berkeley MP Compatible Functions
 | Bug reporting | 4. Reporting Bugs
 | Build notes for binary packaging | 2.3 Notes for Package Builds
 | Build notes for particular systems | 2.4 Notes for Particular Systems
 | Build options | 2.1 Build Options
 | Build problems known | 2.5 Known Build Problems
C |  |
 | C++ Interface | 12. C++ Class Interface
 | C++ istream input | 11.3 C++ Formatted Input
 | C++ ostream output | 10.3 C++ Formatted Output
 | Comparison functions | 5.10 Comparison Functions
 | Comparison functions | 6.4 Comparison Functions
 | Comparison functions | 7.6 Comparison Functions
 | Compatibility with older versions | 3.8 Compatibility with older versions
 | Conditions for copying GNU MP | GNU MP Copying Conditions
 | Configuring GMP | 2. Installing GMP
 | Constants | 3.7 Useful Macros and Constants
 | Contributors | A. Contributors
 | Conventions for parameters | 3.4 Parameter Conventions
 | Conventions for variables | 3.3 Variable Conventions
 | Conversion functions | 5.4 Conversion Functions
 | Conversion functions | 6.2 Conversion Functions
 | Conversion functions | 7.4 Conversion Functions
 | Copying conditions | GNU MP Copying Conditions
 | CPUs supported | 1. Introduction to GNU MP
 | Custom allocation | 14. Custom Allocation
D |  |
 | Debugging | 3.10 Debugging
 | Demonstration programs | 2.1 Build Options
 | Division algorithms | 16.2 Division Algorithms
 | Division functions | 5.6 Division Functions
 | Division functions | 6.3 Arithmetic Functions
 | Division functions | 7.5 Arithmetic Functions
E |  |
 | Efficiency | 3.9 Efficiency
 | Exact division functions | 5.6 Division Functions
 | Example programs | 2.1 Build Options
 | Exponentiation functions | 5.7 Exponentiation Functions
 | Exponentiation functions | 7.5 Arithmetic Functions
 | Extended GCD | 5.9 Number Theoretic Functions
F |  |
 | Factorial functions | 5.9 Number Theoretic Functions
 | FDL, GNU Free Documentation License | C. GNU Free Documentation License
 | Fibonacci sequence functions | 5.9 Number Theoretic Functions
 | Float arithmetic functions | 7.5 Arithmetic Functions
 | Float assignment functions | 7.2 Assignment Functions
 | Float comparison functions | 7.6 Comparison Functions
 | Float conversion functions | 7.4 Conversion Functions
 | Float functions | 7. Floating-point Functions
 | Float init and assign functions | 7.3 Combined Initialization and Assignment Functions
 | Float initialization functions | 7.1 Initialization Functions
 | Float input and output functions | 7.7 Input and Output Functions
 | Float miscellaneous functions | 7.8 Miscellaneous Functions
 | Float sign tests | 7.6 Comparison Functions
 | Floating-point functions | 7. Floating-point Functions
 | Floating-point number | 3.1 Nomenclature and Types
 | Formatted input | 11. Formatted Input
 | Formatted output | 10. Formatted Output
 | FTP of latest version | 1. Introduction to GNU MP
 | Function classes | 3.2 Function Classes
G |  |
 | GMP version number | 3.7 Useful Macros and Constants
 | `gmp.h' | 3. GMP Basics
 | GNU Free Documentation License | C. GNU Free Documentation License
 | Greatest common divisor algorithms | 16.3 Greatest Common Divisor
 | Greatest common divisor functions | 5.9 Number Theoretic Functions
H |  |
 | Home page | 1. Introduction to GNU MP
I |  |
 | I/O functions | 5.12 Input and Output Functions
 | I/O functions | 6.6 Input and Output Functions
 | I/O functions | 7.7 Input and Output Functions
 | Initialization and assignment functions | 5.3 Combined Initialization and Assignment Functions
 | Initialization and assignment functions | 6.1 Initialization and Assignment Functions
 | Initialization and assignment functions | 7.3 Combined Initialization and Assignment Functions
 | Initialization functions | 5.1 Initialization Functions
 | Initialization functions | 7.1 Initialization Functions
 | Input functions | 5.12 Input and Output Functions
 | Input functions | 6.6 Input and Output Functions
 | Input functions | 7.7 Input and Output Functions
 | Installing GMP | 2. Installing GMP
 | Instruction Set Architecture | 2.2 ABI and ISA
 | Integer | 3.1 Nomenclature and Types
 | Integer arithmetic functions | 5.5 Arithmetic Functions
 | Integer assignment functions | 5.2 Assignment Functions
 | Integer bit manipulation functions | 5.11 Logical and Bit Manipulation Functions
 | Integer comparison functions | 5.10 Comparison Functions
 | Integer conversion functions | 5.4 Conversion Functions
 | Integer division functions | 5.6 Division Functions
 | Integer exponentiation functions | 5.7 Exponentiation Functions
 | Integer functions | 5. Integer Functions
 | Integer init and assign | 5.3 Combined Initialization and Assignment Functions
 | Integer initialization functions | 5.1 Initialization Functions
 | Integer input and output functions | 5.12 Input and Output Functions
 | Integer miscellaneous functions | 5.14 Miscellaneous Functions
 | Integer random number functions | 5.13 Random Number Functions
 | Integer root functions | 5.8 Root Extraction Functions
 | Integer sign tests | 5.10 Comparison Functions
 | Introduction | 1. Introduction to GNU MP
 | ISA | 2.2 ABI and ISA
 | istream input | 11.3 C++ Formatted Input
J |  |
 | Jacobi symbol functions | 5.9 Number Theoretic Functions
K |  |
 | Kronecker symbol functions | 5.9 Number Theoretic Functions
L |  |
 | Latest version of GMP | 1. Introduction to GNU MP
 | Least common multiple functions | 5.9 Number Theoretic Functions
 | Libtool versioning | 2.3 Notes for Package Builds
 | License conditions | GNU MP Copying Conditions
 | Limb | 3.1 Nomenclature and Types
 | Limb size | 3.7 Useful Macros and Constants
 | Logical functions | 5.11 Logical and Bit Manipulation Functions
 | Low-level functions | 8. Low-level Functions
 | Lucas number functions | 5.9 Number Theoretic Functions
M |  |
 | Mailing list | 1. Introduction to GNU MP
 | Memory allocation | 14. Custom Allocation
 | Memory Management | 3.5 Memory Management
 | Miscellaneous float functions | 7.8 Miscellaneous Functions
 | Miscellaneous integer functions | 5.14 Miscellaneous Functions
 | Modular inverse functions | 5.9 Number Theoretic Functions
 | `mp.h' | 13. Berkeley MP Compatible Functions
 | MPFR | 2.1 Build Options
 | Multi-threading | 3.6 Reentrancy
 | Multiplication algorithms | 16.1 Multiplication
N |  |
 | Nomenclature | 3.1 Nomenclature and Types
 | Number theoretic functions | 5.9 Number Theoretic Functions
 | Numerator and denominator | 6.5 Applying Integer Functions to Rationals
O |  |
 | ostream output | 10.3 C++ Formatted Output
 | Output functions | 5.12 Input and Output Functions
 | Output functions | 6.6 Input and Output Functions
 | Output functions | 7.7 Input and Output Functions
P |  |
 | Packaged builds | 2.3 Notes for Package Builds
 | Parameter conventions | 3.4 Parameter Conventions
 | Powering algorithms | 16.4 Powering Algorithms
 | Powering functions | 5.7 Exponentiation Functions
 | Powering functions | 7.5 Arithmetic Functions
 | Precision of floats | 7. Floating-point Functions
 | Prime testing functions | 5.9 Number Theoretic Functions
 | printf formatted output | 10. Formatted Output
 | Profiling | 3.11 Profiling
R |  |
 | Radix conversion algorithms | 16.6 Radix Conversion
 | Random number functions | 5.13 Random Number Functions
 | Random number functions | 9. Random Number Functions
 | Random number seeding | 9.2 Random State Seeding
 | Random number state | 9.1 Random State Initialization
 | Rational arithmetic functions | 6.3 Arithmetic Functions
 | Rational comparison functions | 6.4 Comparison Functions
 | Rational conversion functions | 6.2 Conversion Functions
 | Rational init and assign | 6.1 Initialization and Assignment Functions
 | Rational input and output functions | 6.6 Input and Output Functions
 | Rational number | 3.1 Nomenclature and Types
 | Rational number functions | 6. Rational Number Functions
 | Rational numerator and denominator | 6.5 Applying Integer Functions to Rationals
 | Rational sign tests | 6.4 Comparison Functions
 | Reentrancy | 3.6 Reentrancy
 | References | B. References
 | Reporting bugs | 4. Reporting Bugs
 | Root extraction algorithms | 16.5 Root Extraction Algorithms
 | Root extraction functions | 5.8 Root Extraction Functions
 | Root extraction functions | 7.5 Arithmetic Functions
S |  |
 | scanf formatted input | 11. Formatted Input
 | Shared library versioning | 2.3 Notes for Package Builds
 | Sign tests | 5.10 Comparison Functions
 | Sign tests | 6.4 Comparison Functions
 | Sign tests | 7.6 Comparison Functions
 | Stack overflow segfaults | 2.1 Build Options
 | Stripped libraries | 2.5 Known Build Problems
T |  |
 | Thread safety | 3.6 Reentrancy
 | Types | 3.1 Nomenclature and Types
U |  |
 | Upward compatibility | 3.8 Compatibility with older versions
 | Useful macros and constants | 3.7 Useful Macros and Constants
 | User-defined precision | 7. Floating-point Functions
V |  |
 | Variable conventions | 3.3 Variable Conventions
 | Version number | 3.7 Useful Macros and Constants
W |  |
 | Web page | 1. Introduction to GNU MP

Jump to: A B C D E F G H I J K L M N O P R S T U V W

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Function and Type Index

Jump to: _
A C D F G H I M O P R S T X

 | Index Entry | Section
_ |  |
 | __GNU_MP_VERSION | 3.7 Useful Macros and Constants
 | __GNU_MP_VERSION_MINOR | 3.7 Useful Macros and Constants
 | __GNU_MP_VERSION_PATCHLEVEL | 3.7 Useful Macros and Constants
 | _mpz_realloc | 5.1 Initialization Functions
A |  |
 | abs | 12.2 C++ Interface Integers
 | abs | 12.3 C++ Interface Rationals
 | abs | 12.4 C++ Interface Floats
 | allocate_function | 14. Custom Allocation
C |  |
 | ceil | 12.4 C++ Interface Floats
 | cmp | 12.2 C++ Interface Integers
 | cmp | 12.2 C++ Interface Integers
 | cmp | 12.3 C++ Interface Rationals
 | cmp | 12.3 C++ Interface Rationals
 | cmp | 12.4 C++ Interface Floats
 | cmp | 12.4 C++ Interface Floats
D |  |
 | deallocate_function | 14. Custom Allocation
F |  |
 | floor | 12.4 C++ Interface Floats
G |  |
 | gcd | 13. Berkeley MP Compatible Functions
 | gmp_asprintf | 10.2 Functions
 | gmp_fprintf | 10.2 Functions
 | gmp_fscanf | 11.2 Formatted Input Functions
 | gmp_obstack_printf | 10.2 Functions
 | gmp_obstack_vprintf | 10.2 Functions
 | gmp_printf | 10.2 Functions
 | gmp_randclass | 12.6 C++ Interface Random Numbers
 | gmp_randclass::get_f | 12.6 C++ Interface Random Numbers
 | gmp_randclass::get_f | 12.6 C++ Interface Random Numbers
 | gmp_randclass::get_z_bits | 12.6 C++ Interface Random Numbers
 | gmp_randclass::get_z_bits | 12.6 C++ Interface Random Numbers
 | gmp_randclass::get_z_range | 12.6 C++ Interface Random Numbers
 | gmp_randclass::gmp_randclass | 12.6 C++ Interface Random Numbers
 | gmp_randclass::gmp_randclass | 12.6 C++ Interface Random Numbers
 | gmp_randclass::seed | 12.6 C++ Interface Random Numbers
 | gmp_randclass::seed | 12.6 C++ Interface Random Numbers
 | gmp_randclear | 9.1 Random State Initialization
 | gmp_randinit | 9.1 Random State Initialization
 | gmp_randinit_default | 9.1 Random State Initialization
 | gmp_randinit_lc_2exp | 9.1 Random State Initialization
 | gmp_randinit_lc_2exp_size | 9.1 Random State Initialization
 | gmp_randseed | 9.2 Random State Seeding
 | gmp_randseed_ui | 9.2 Random State Seeding
 | gmp_scanf | 11.2 Formatted Input Functions
 | gmp_snprintf | 10.2 Functions
 | gmp_sprintf | 10.2 Functions
 | gmp_sscanf | 11.2 Formatted Input Functions
 | gmp_vasprintf | 10.2 Functions
 | gmp_version | 3.7 Useful Macros and Constants
 | gmp_vfprintf | 10.2 Functions
 | gmp_vfscanf | 11.2 Formatted Input Functions
 | gmp_vprintf | 10.2 Functions
 | gmp_vscanf | 11.2 Formatted Input Functions
 | gmp_vsnprintf | 10.2 Functions
 | gmp_vsprintf | 10.2 Functions
 | gmp_vsscanf | 11.2 Formatted Input Functions
H |  |
 | hypot | 12.4 C++ Interface Floats
I |  |
 | itom | 13. Berkeley MP Compatible Functions
M |  |
 | madd | 13. Berkeley MP Compatible Functions
 | mcmp | 13. Berkeley MP Compatible Functions
 | mdiv | 13. Berkeley MP Compatible Functions
 | mfree | 13. Berkeley MP Compatible Functions
 | min | 13. Berkeley MP Compatible Functions
 | mout | 13. Berkeley MP Compatible Functions
 | move | 13. Berkeley MP Compatible Functions
 | mp_bits_per_limb | 3.7 Useful Macros and Constants
 | mp_limb_t | 3.1 Nomenclature and Types
 | mp_set_memory_functions | 14. Custom Allocation
 | mpf_abs | 7.5 Arithmetic Functions
 | mpf_add | 7.5 Arithmetic Functions
 | mpf_add_ui | 7.5 Arithmetic Functions
 | mpf_ceil | 7.8 Miscellaneous Functions
 | mpf_class | 12.1 C++ Interface General
 | mpf_class::fits_sint_p | 12.4 C++ Interface Floats
 | mpf_class::fits_slong_p | 12.4 C++ Interface Floats
 | mpf_class::fits_sshort_p | 12.4 C++ Interface Floats
 | mpf_class::fits_uint_p | 12.4 C++ Interface Floats
 | mpf_class::fits_ulong_p | 12.4 C++ Interface Floats
 | mpf_class::fits_ushort_p | 12.4 C++ Interface Floats
 | mpf_class::get_d | 12.4 C++ Interface Floats
 | mpf_class::get_mpf_t | 12.1 C++ Interface General
 | mpf_class::get_prec | 12.4 C++ Interface Floats
 | mpf_class::get_si | 12.4 C++ Interface Floats
 | mpf_class::get_ui | 12.4 C++ Interface Floats
 | mpf_class::mpf_class | 12.4 C++ Interface Floats
 | mpf_class::mpf_class | 12.4 C++ Interface Floats
 | mpf_class::set_prec | 12.4 C++ Interface Floats
 | mpf_class::set_prec_raw | 12.4 C++ Interface Floats
 | mpf_clear | 7.1 Initialization Functions
 | mpf_cmp | 7.6 Comparison Functions
 | mpf_cmp_d | 7.6 Comparison Functions
 | mpf_cmp_si | 7.6 Comparison Functions
 | mpf_cmp_ui | 7.6 Comparison Functions
 | mpf_div | 7.5 Arithmetic Functions
 | mpf_div_2exp | 7.5 Arithmetic Functions
 | mpf_div_ui | 7.5 Arithmetic Functions
 | mpf_eq | 7.6 Comparison Functions
 | mpf_fits_sint_p | 7.8 Miscellaneous Functions
 | mpf_fits_slong_p | 7.8 Miscellaneous Functions
 | mpf_fits_sshort_p | 7.8 Miscellaneous Functions
 | mpf_fits_uint_p | 7.8 Miscellaneous Functions
 | mpf_fits_ulong_p | 7.8 Miscellaneous Functions
 | mpf_fits_ushort_p | 7.8 Miscellaneous Functions
 | mpf_floor | 7.8 Miscellaneous Functions
 | mpf_get_d | 7.4 Conversion Functions
 | mpf_get_d_2exp | 7.4 Conversion Functions
 | mpf_get_default_prec | 7.1 Initialization Functions
 | mpf_get_prec | 7.1 Initialization Functions
 | mpf_get_si | 7.4 Conversion Functions
 | mpf_get_str | 7.4 Conversion Functions
 | mpf_get_ui | 7.4 Conversion Functions
 | mpf_init | 7.1 Initialization Functions
 | mpf_init2 | 7.1 Initialization Functions
 | mpf_init_set | 7.3 Combined Initialization and Assignment Functions
 | mpf_init_set_d | 7.3 Combined Initialization and Assignment Functions
 | mpf_init_set_si | 7.3 Combined Initialization and Assignment Functions
 | mpf_init_set_str | 7.3 Combined Initialization and Assignment Functions
 | mpf_init_set_ui | 7.3 Combined Initialization and Assignment Functions
 | mpf_inp_str | 7.7 Input and Output Functions
 | mpf_integer_p | 7.8 Miscellaneous Functions
 | mpf_mul | 7.5 Arithmetic Functions
 | mpf_mul_2exp | 7.5 Arithmetic Functions
 | mpf_mul_ui | 7.5 Arithmetic Functions
 | mpf_neg | 7.5 Arithmetic Functions
 | mpf_out_str | 7.7 Input and Output Functions
 | mpf_pow_ui | 7.5 Arithmetic Functions
 | mpf_random2 | 7.8 Miscellaneous Functions
 | mpf_reldiff | 7.6 Comparison Functions
 | mpf_set | 7.2 Assignment Functions
 | mpf_set_d | 7.2 Assignment Functions
 | mpf_set_default_prec | 7.1 Initialization Functions
 | mpf_set_prec | 7.1 Initialization Functions
 | mpf_set_prec_raw | 7.1 Initialization Functions
 | mpf_set_q | 7.2 Assignment Functions
 | mpf_set_si | 7.2 Assignment Functions
 | mpf_set_str | 7.2 Assignment Functions
 | mpf_set_ui | 7.2 Assignment Functions
 | mpf_set_z | 7.2 Assignment Functions
 | mpf_sgn | 7.6 Comparison Functions
 | mpf_sqrt | 7.5 Arithmetic Functions
 | mpf_sqrt_ui | 7.5 Arithmetic Functions
 | mpf_sub | 7.5 Arithmetic Functions
 | mpf_sub_ui | 7.5 Arithmetic Functions
 | mpf_swap | 7.2 Assignment Functions
 | mpf_t | 3.1 Nomenclature and Types
 | mpf_trunc | 7.8 Miscellaneous Functions
 | mpf_ui_div | 7.5 Arithmetic Functions
 | mpf_ui_sub | 7.5 Arithmetic Functions
 | mpf_urandomb | 7.8 Miscellaneous Functions
 | mpfr_class | 12.5 C++ Interface MPFR
 | mpn_add | 8. Low-level Functions
 | mpn_add_1 | 8. Low-level Functions
 | mpn_add_n | 8. Low-level Functions
 | mpn_addmul_1 | 8. Low-level Functions
 | mpn_bdivmod | 8. Low-level Functions
 | mpn_cmp | 8. Low-level Functions
 | mpn_divexact_by3 | 8. Low-level Functions
 | mpn_divexact_by3c | 8. Low-level Functions
 | mpn_divmod | 8. Low-level Functions
 | mpn_divmod_1 | 8. Low-level Functions
 | mpn_divrem | 8. Low-level Functions
 | mpn_divrem_1 | 8. Low-level Functions
 | mpn_gcd | 8. Low-level Functions
 | mpn_gcd_1 | 8. Low-level Functions
 | mpn_gcdext | 8. Low-level Functions
 | mpn_get_str | 8. Low-level Functions
 | mpn_hamdist | 8. Low-level Functions
 | mpn_lshift | 8. Low-level Functions
 | mpn_mod_1 | 8. Low-level Functions
 | mpn_mul | 8. Low-level Functions
 | mpn_mul_1 | 8. Low-level Functions
 | mpn_mul_n | 8. Low-level Functions
 | mpn_perfect_square_p | 8. Low-level Functions
 | mpn_popcount | 8. Low-level Functions
 | mpn_random | 8. Low-level Functions
 | mpn_random2 | 8. Low-level Functions
 | mpn_rshift | 8. Low-level Functions
 | mpn_scan0 | 8. Low-level Functions
 | mpn_scan1 | 8. Low-level Functions
 | mpn_set_str | 8. Low-level Functions
 | mpn_sqrtrem | 8. Low-level Functions
 | mpn_sub | 8. Low-level Functions
 | mpn_sub_1 | 8. Low-level Functions
 | mpn_sub_n | 8. Low-level Functions
 | mpn_submul_1 | 8. Low-level Functions
 | mpn_tdiv_qr | 8. Low-level Functions
 | mpq_abs | 6.3 Arithmetic Functions
 | mpq_add | 6.3 Arithmetic Functions
 | mpq_canonicalize | 6. Rational Number Functions
 | mpq_class | 12.1 C++ Interface General
 | mpq_class::canonicalize | 12.3 C++ Interface Rationals
 | mpq_class::get_d | 12.3 C++ Interface Rationals
 | mpq_class::get_den | 12.3 C++ Interface Rationals
 | mpq_class::get_den_mpz_t | 12.3 C++ Interface Rationals
 | mpq_class::get_mpq_t | 12.1 C++ Interface General
 | mpq_class::get_num | 12.3 C++ Interface Rationals
 | mpq_class::get_num_mpz_t | 12.3 C++ Interface Rationals
 | mpq_class::mpq_class | 12.3 C++ Interface Rationals
 | mpq_class::mpq_class | 12.3 C++ Interface Rationals
 | mpq_class::mpq_class | 12.3 C++ Interface Rationals
 | mpq_class::mpq_class | 12.3 C++ Interface Rationals
 | mpq_class::mpq_class | 12.3 C++ Interface Rationals
 | mpq_class::mpq_class | 12.3 C++ Interface Rationals
 | mpq_class::mpq_class | 12.3 C++ Interface Rationals
 | mpq_clear | 6.1 Initialization and Assignment Functions
 | mpq_cmp | 6.4 Comparison Functions
 | mpq_cmp_si | 6.4 Comparison Functions
 | mpq_cmp_ui | 6.4 Comparison Functions
 | mpq_denref | 6.5 Applying Integer Functions to Rationals
 | mpq_div | 6.3 Arithmetic Functions
 | mpq_div_2exp | 6.3 Arithmetic Functions
 | mpq_equal | 6.4 Comparison Functions
 | mpq_get_d | 6.2 Conversion Functions
 | mpq_get_den | 6.5 Applying Integer Functions to Rationals
 | mpq_get_num | 6.5 Applying Integer Functions to Rationals
 | mpq_get_str | 6.2 Conversion Functions
 | mpq_init | 6.1 Initialization and Assignment Functions
 | mpq_inp_str | 6.6 Input and Output Functions
 | mpq_inv | 6.3 Arithmetic Functions
 | mpq_mul | 6.3 Arithmetic Functions
 | mpq_mul_2exp | 6.3 Arithmetic Functions
 | mpq_neg | 6.3 Arithmetic Functions
 | mpq_numref | 6.5 Applying Integer Functions to Rationals
 | mpq_out_str | 6.6 Input and Output Functions
 | mpq_set | 6.1 Initialization and Assignment Functions
 | mpq_set_d | 6.2 Conversion Functions
 | mpq_set_den | 6.5 Applying Integer Functions to Rationals
 | mpq_set_f | 6.2 Conversion Functions
 | mpq_set_num | 6.5 Applying Integer Functions to Rationals
 | mpq_set_si | 6.1 Initialization and Assignment Functions
 | mpq_set_str | 6.1 Initialization and Assignment Functions
 | mpq_set_ui | 6.1 Initialization and Assignment Functions
 | mpq_set_z | 6.1 Initialization and Assignment Functions
 | mpq_sgn | 6.4 Comparison Functions
 | mpq_sub | 6.3 Arithmetic Functions
 | mpq_swap | 6.1 Initialization and Assignment Functions
 | mpq_t | 3.1 Nomenclature and Types
 | mpz_abs | 5.5 Arithmetic Functions
 | mpz_add | 5.5 Arithmetic Functions
 | mpz_add_ui | 5.5 Arithmetic Functions
 | mpz_addmul | 5.5 Arithmetic Functions
 | mpz_addmul_ui | 5.5 Arithmetic Functions
 | mpz_and | 5.11 Logical and Bit Manipulation Functions
 | mpz_array_init | 5.1 Initialization Functions
 | mpz_bin_ui | 5.9 Number Theoretic Functions
 | mpz_bin_uiui | 5.9 Number Theoretic Functions
 | mpz_cdiv_q | 5.6 Division Functions
 | mpz_cdiv_q_2exp | 5.6 Division Functions
 | mpz_cdiv_q_ui | 5.6 Division Functions
 | mpz_cdiv_qr | 5.6 Division Functions
 | mpz_cdiv_qr_ui | 5.6 Division Functions
 | mpz_cdiv_r | 5.6 Division Functions
 | mpz_cdiv_r_2exp | 5.6 Division Functions
 | mpz_cdiv_r_ui | 5.6 Division Functions
 | mpz_cdiv_ui | 5.6 Division Functions
 | mpz_class | 12.1 C++ Interface General
 | mpz_class::fits_sint_p | 12.2 C++ Interface Integers
 | mpz_class::fits_slong_p | 12.2 C++ Interface Integers
 | mpz_class::fits_sshort_p | 12.2 C++ Interface Integers
 | mpz_class::fits_uint_p | 12.2 C++ Interface Integers
 | mpz_class::fits_ulong_p | 12.2 C++ Interface Integers
 | mpz_class::fits_ushort_p | 12.2 C++ Interface Integers
 | mpz_class::get_d | 12.2 C++ Interface Integers
 | mpz_class::get_mpz_t | 12.1 C++ Interface General
 | mpz_class::get_si | 12.2 C++ Interface Integers
 | mpz_class::get_ui | 12.2 C++ Interface Integers
 | mpz_class::mpz_class | 12.2 C++ Interface Integers
 | mpz_class::mpz_class | 12.2 C++ Interface Integers
 | mpz_class::mpz_class | 12.2 C++ Interface Integers
 | mpz_class::mpz_class | 12.2 C++ Interface Integers
 | mpz_class::mpz_class | 12.2 C++ Interface Integers
 | mpz_class::mpz_class | 12.2 C++ Interface Integers
 | mpz_clear | 5.1 Initialization Functions
 | mpz_clrbit | 5.11 Logical and Bit Manipulation Functions
 | mpz_cmp | 5.10 Comparison Functions
 | mpz_cmp_d | 5.10 Comparison Functions
 | mpz_cmp_si | 5.10 Comparison Functions
 | mpz_cmp_ui | 5.10 Comparison Functions
 | mpz_cmpabs | 5.10 Comparison Functions
 | mpz_cmpabs_d | 5.10 Comparison Functions
 | mpz_cmpabs_ui | 5.10 Comparison Functions
 | mpz_com | 5.11 Logical and Bit Manipulation Functions
 | mpz_congruent_2exp_p | 5.6 Division Functions
 | mpz_congruent_p | 5.6 Division Functions
 | mpz_congruent_ui_p | 5.6 Division Functions
 | mpz_divexact | 5.6 Division Functions
 | mpz_divexact_ui | 5.6 Division Functions
 | mpz_divisible_2exp_p | 5.6 Division Functions
 | mpz_divisible_p | 5.6 Division Functions
 | mpz_divisible_ui_p | 5.6 Division Functions
 | mpz_even_p | 5.14 Miscellaneous Functions
 | mpz_fac_ui | 5.9 Number Theoretic Functions
 | mpz_fdiv_q | 5.6 Division Functions
 | mpz_fdiv_q_2exp | 5.6 Division Functions
 | mpz_fdiv_q_ui | 5.6 Division Functions
 | mpz_fdiv_qr | 5.6 Division Functions
 | mpz_fdiv_qr_ui | 5.6 Division Functions
 | mpz_fdiv_r | 5.6 Division Functions
 | mpz_fdiv_r_2exp | 5.6 Division Functions
 | mpz_fdiv_r_ui | 5.6 Division Functions
 | mpz_fdiv_ui | 5.6 Division Functions
 | mpz_fib2_ui | 5.9 Number Theoretic Functions
 | mpz_fib_ui | 5.9 Number Theoretic Functions
 | mpz_fits_sint_p | 5.14 Miscellaneous Functions
 | mpz_fits_slong_p | 5.14 Miscellaneous Functions
 | mpz_fits_sshort_p | 5.14 Miscellaneous Functions
 | mpz_fits_uint_p | 5.14 Miscellaneous Functions
 | mpz_fits_ulong_p | 5.14 Miscellaneous Functions
 | mpz_fits_ushort_p | 5.14 Miscellaneous Functions
 | mpz_gcd | 5.9 Number Theoretic Functions
 | mpz_gcd_ui | 5.9 Number Theoretic Functions
 | mpz_gcdext | 5.9 Number Theoretic Functions
 | mpz_get_d | 5.4 Conversion Functions
 | mpz_get_d_2exp | 5.4 Conversion Functions
 | mpz_get_si | 5.4 Conversion Functions
 | mpz_get_str | 5.4 Conversion Functions
 | mpz_get_ui | 5.4 Conversion Functions
 | mpz_getlimbn | 5.4 Conversion Functions
 | mpz_hamdist | 5.11 Logical and Bit Manipulation Functions
 | mpz_init | 5.1 Initialization Functions
 | mpz_init2 | 5.1 Initialization Functions
 | mpz_init_set | 5.3 Combined Initialization and Assignment Functions
 | mpz_init_set_d | 5.3 Combined Initialization and Assignment Functions
 | mpz_init_set_si | 5.3 Combined Initialization and Assignment Functions
 | mpz_init_set_str | 5.3 Combined Initialization and Assignment Functions
 | mpz_init_set_ui | 5.3 Combined Initialization and Assignment Functions
 | mpz_inp_raw | 5.12 Input and Output Functions
 | mpz_inp_str | 5.12 Input and Output Functions
 | mpz_invert | 5.9 Number Theoretic Functions
 | mpz_ior | 5.11 Logical and Bit Manipulation Functions
 | mpz_jacobi | 5.9 Number Theoretic Functions
 | mpz_kronecker | 5.9 Number Theoretic Functions
 | mpz_kronecker_si | 5.9 Number Theoretic Functions
 | mpz_kronecker_ui | 5.9 Number Theoretic Functions
 | mpz_lcm | 5.9 Number Theoretic Functions
 | mpz_lcm_ui | 5.9 Number Theoretic Functions
 | mpz_legendre | 5.9 Number Theoretic Functions
 | mpz_lucnum2_ui | 5.9 Number Theoretic Functions
 | mpz_lucnum_ui | 5.9 Number Theoretic Functions
 | mpz_mod | 5.6 Division Functions
 | mpz_mod_ui | 5.6 Division Functions
 | mpz_mul | 5.5 Arithmetic Functions
 | mpz_mul_2exp | 5.5 Arithmetic Functions
 | mpz_mul_si | 5.5 Arithmetic Functions
 | mpz_mul_ui | 5.5 Arithmetic Functions
 | mpz_neg | 5.5 Arithmetic Functions
 | mpz_nextprime | 5.9 Number Theoretic Functions
 | mpz_odd_p | 5.14 Miscellaneous Functions
 | mpz_out_raw | 5.12 Input and Output Functions
 | mpz_out_str | 5.12 Input and Output Functions
 | mpz_perfect_power_p | 5.8 Root Extraction Functions
 | mpz_perfect_square_p | 5.8 Root Extraction Functions
 | mpz_popcount | 5.11 Logical and Bit Manipulation Functions
 | mpz_pow_ui | 5.7 Exponentiation Functions
 | mpz_powm | 5.7 Exponentiation Functions
 | mpz_powm_ui | 5.7 Exponentiation Functions
 | mpz_probab_prime_p | 5.9 Number Theoretic Functions
 | mpz_random | 5.13 Random Number Functions
 | mpz_random2 | 5.13 Random Number Functions
 | mpz_realloc2 | 5.1 Initialization Functions
 | mpz_remove | 5.9 Number Theoretic Functions
 | mpz_root | 5.8 Root Extraction Functions
 | mpz_rrandomb | 5.13 Random Number Functions
 | mpz_scan0 | 5.11 Logical and Bit Manipulation Functions
 | mpz_scan1 | 5.11 Logical and Bit Manipulation Functions
 | mpz_set | 5.2 Assignment Functions
 | mpz_set_d | 5.2 Assignment Functions
 | mpz_set_f | 5.2 Assignment Functions
 | mpz_set_q | 5.2 Assignment Functions
 | mpz_set_si | 5.2 Assignment Functions
 | mpz_set_str | 5.2 Assignment Functions
 | mpz_set_ui | 5.2 Assignment Functions
 | mpz_setbit | 5.11 Logical and Bit Manipulation Functions
 | mpz_sgn | 5.10 Comparison Functions
 | mpz_si_kronecker | 5.9 Number Theoretic Functions
 | mpz_size | 5.14 Miscellaneous Functions
 | mpz_sizeinbase | 5.14 Miscellaneous Functions
 | mpz_sqrt | 5.8 Root Extraction Functions
 | mpz_sqrtrem | 5.8 Root Extraction Functions
 | mpz_sub | 5.5 Arithmetic Functions
 | mpz_sub_ui | 5.5 Arithmetic Functions
 | mpz_submul | 5.5 Arithmetic Functions
 | mpz_submul_ui | 5.5 Arithmetic Functions
 | mpz_swap | 5.2 Assignment Functions
 | mpz_t | 3.1 Nomenclature and Types
 | mpz_tdiv_q | 5.6 Division Functions
 | mpz_tdiv_q_2exp | 5.6 Division Functions
 | mpz_tdiv_q_ui | 5.6 Division Functions
 | mpz_tdiv_qr | 5.6 Division Functions
 | mpz_tdiv_qr_ui | 5.6 Division Functions
 | mpz_tdiv_r | 5.6 Division Functions
 | mpz_tdiv_r_2exp | 5.6 Division Functions
 | mpz_tdiv_r_ui | 5.6 Division Functions
 | mpz_tdiv_ui | 5.6 Division Functions
 | mpz_tstbit | 5.11 Logical and Bit Manipulation Functions
 | mpz_ui_kronecker | 5.9 Number Theoretic Functions
 | mpz_ui_pow_ui | 5.7 Exponentiation Functions
 | mpz_urandomb | 5.13 Random Number Functions
 | mpz_urandomm | 5.13 Random Number Functions
 | mpz_xor | 5.11 Logical and Bit Manipulation Functions
 | msqrt | 13. Berkeley MP Compatible Functions
 | msub | 13. Berkeley MP Compatible Functions
 | mtox | 13. Berkeley MP Compatible Functions
 | mult | 13. Berkeley MP Compatible Functions
O |  |
 | operator% | 12.2 C++ Interface Integers
 | operator/ | 12.2 C++ Interface Integers
 | operator<< | 10.3 C++ Formatted Output
 | operator<< | 10.3 C++ Formatted Output
 | operator<< | 10.3 C++ Formatted Output
 | operator>> | 11.3 C++ Formatted Input
 | operator>> | 11.3 C++ Formatted Input
 | operator>> | 11.3 C++ Formatted Input
 | operator>> | 12.3 C++ Interface Rationals
P |  |
 | pow | 13. Berkeley MP Compatible Functions
R |  |
 | reallocate_function | 14. Custom Allocation
 | rpow | 13. Berkeley MP Compatible Functions
S |  |
 | sdiv | 13. Berkeley MP Compatible Functions
 | sgn | 12.2 C++ Interface Integers
 | sgn | 12.3 C++ Interface Rationals
 | sgn | 12.4 C++ Interface Floats
 | sqrt | 12.2 C++ Interface Integers
 | sqrt | 12.4 C++ Interface Floats
T |  |
 | trunc | 12.4 C++ Interface Floats
X |  |
 | xtom | 13. Berkeley MP Compatible Functions

Jump to: _
A C D F G H I M O P R S T X

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]
[Top] [Contents] [Index] [ ? ]

Table of Contents

    GNU MP Copying Conditions
    1. Introduction to GNU MP
      1.1 How to use this Manual
    2. Installing GMP
      2.1 Build Options
      2.2 ABI and ISA
      2.3 Notes for Package Builds
      2.4 Notes for Particular Systems
      2.5 Known Build Problems
    3. GMP Basics
      3.1 Nomenclature and Types
      3.2 Function Classes
      3.3 Variable Conventions
      3.4 Parameter Conventions
      3.5 Memory Management
      3.6 Reentrancy
      3.7 Useful Macros and Constants
      3.8 Compatibility with older versions
      3.9 Efficiency
      3.10 Debugging
      3.11 Profiling
      3.12 Autoconf
    4. Reporting Bugs
    5. Integer Functions
      5.1 Initialization Functions
      5.2 Assignment Functions
      5.3 Combined Initialization and Assignment Functions
      5.4 Conversion Functions
      5.5 Arithmetic Functions
      5.6 Division Functions
      5.7 Exponentiation Functions
      5.8 Root Extraction Functions
      5.9 Number Theoretic Functions
      5.10 Comparison Functions
      5.11 Logical and Bit Manipulation Functions
      5.12 Input and Output Functions
      5.13 Random Number Functions
      5.14 Miscellaneous Functions
    6. Rational Number Functions
      6.1 Initialization and Assignment Functions
      6.2 Conversion Functions
      6.3 Arithmetic Functions
      6.4 Comparison Functions
      6.5 Applying Integer Functions to Rationals
      6.6 Input and Output Functions
    7. Floating-point Functions
      7.1 Initialization Functions
      7.2 Assignment Functions
      7.3 Combined Initialization and Assignment Functions
      7.4 Conversion Functions
      7.5 Arithmetic Functions
      7.6 Comparison Functions
      7.7 Input and Output Functions
      7.8 Miscellaneous Functions
    8. Low-level Functions
    9. Random Number Functions
      9.1 Random State Initialization
      9.2 Random State Seeding
    10. Formatted Output
      10.1 Format Strings
      10.2 Functions
      10.3 C++ Formatted Output
    11. Formatted Input
      11.1 Formatted Input Strings
      11.2 Formatted Input Functions
      11.3 C++ Formatted Input
    12. C++ Class Interface
      12.1 C++ Interface General
      12.2 C++ Interface Integers
      12.3 C++ Interface Rationals
      12.4 C++ Interface Floats
      12.5 C++ Interface MPFR
      12.6 C++ Interface Random Numbers
      12.7 C++ Interface Limitations
    13. Berkeley MP Compatible Functions
    14. Custom Allocation
    15. Language Bindings
    16. Algorithms
      16.1 Multiplication
        16.1.1 Basecase Multiplication
        16.1.2 Karatsuba Multiplication
        16.1.3 Toom-Cook 3-Way Multiplication
        16.1.4 FFT Multiplication
        16.1.5 Other Multiplication
      16.2 Division Algorithms
        16.2.1 Single Limb Division
        16.2.2 Basecase Division
        16.2.3 Divide and Conquer Division
        16.2.4 Exact Division
        16.2.5 Exact Remainder
        16.2.6 Small Quotient Division
      16.3 Greatest Common Divisor
        16.3.1 Binary GCD
        16.3.2 Accelerated GCD
        16.3.3 Extended GCD
        16.3.4 Jacobi Symbol
      16.4 Powering Algorithms
        16.4.1 Normal Powering
        16.4.2 Modular Powering
      16.5 Root Extraction Algorithms
        16.5.1 Square Root
        16.5.2 Nth Root
        16.5.3 Perfect Square
        16.5.4 Perfect Power
      16.6 Radix Conversion
        16.6.1 Binary to Radix
        16.6.2 Radix to Binary
      16.7 Other Algorithms
        16.7.1 Factorial
        16.7.2 Binomial Coefficients
        16.7.3 Fibonacci Numbers
        16.7.4 Lucas Numbers
      16.8 Assembler Coding
        16.8.1 Code Organisation
        16.8.2 Assembler Basics
        16.8.3 Carry Propagation
        16.8.4 Cache Handling
        16.8.5 Floating Point
        16.8.6 SIMD Instructions
        16.8.7 Software Pipelining
        16.8.8 Loop Unrolling
    17. Internals
      17.1 Integer Internals
      17.2 Rational Internals
      17.3 Float Internals
      17.4 Raw Output Internals
      17.5 C++ Interface Internals
    A. Contributors
    B. References
      B.1 Books
      B.2 Papers
    C. GNU Free Documentation License
      C.1 ADDENDUM: How to use this License for your documents
    Concept Index
    Function and Type Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

GNU MP Copying Conditions
1. Introduction to GNU MP
2. Installing GMP
3. GMP Basics
4. Reporting Bugs
5. Integer Functions
6. Rational Number Functions
7. Floating-point Functions
8. Low-level Functions
9. Random Number Functions
10. Formatted Output
11. Formatted Input
12. C++ Class Interface
13. Berkeley MP Compatible Functions
14. Custom Allocation
15. Language Bindings
16. Algorithms
17. Internals
A. Contributors
B. References
C. GNU Free Documentation License
Concept Index
Function and Type Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on February 23, 2002 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on February 23, 2002 using texi2html


User's Guide to gperf

Table of Contents

  • GNU GENERAL PUBLIC LICENSE
    • Preamble
    • TERMS AND CONDITIONS
    • Appendix: How to Apply These Terms to Your New Programs
  • Contributors to GNU gperf Utility
  • Introduction
  • Static search structures and GNU gperf
  • High-Level Description of GNU gperf
    • Input Format to gperf
      • struct Declarations and C Code Inclusion
      • Format for Keyword Entries
      • Including Additional C Functions
    • Output Format for Generated C Code with gperf
  • Options to the gperf Utility
    • Options that affect Interpretation of the Input File
    • Options to specify the Language for the Output Code
    • Options for fine tuning Details in the Output Code
    • Options for changing the Algorithms employed by gperf
    • Informative Output
  • Known Bugs and Limitations with gperf
  • Things Still Left to Do
  • Implementation Details of GNU gperf
  • Bibliography

User's Guide

for the

GNU GPERF Utility

Douglas C. Schmidt

last updated 14 April 1998

for version 2.7 Copyright (C) 1989-1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU gperf General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU gperf General Public License" may be included in a translation approved by the author instead of in the original English.

GNU GENERAL PUBLIC LICENSE

Version 1, February 1989

Copyright (C) 1989 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The license agreements of most software companies try to keep users at the mercy of those companies. By contrast, our General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. The General Public License applies to the Free Software Foundation's software and to any other program whose authors commit to using it. You can use it for your programs, too.

When we speak of free software, we are referring to freedom, not price. Specifically, the General Public License is designed to make sure that you have the freedom to give away or sell copies of free software, that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of a such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS

  1. This License Agreement applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any work containing the Program or a portion of it, either verbatim or with modifications. Each licensee is addressed as "you".
  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this General Public License and to the absence of any warranty; and give any other recipients of the Program a copy of this General Public License along with the Program. You may charge a fee for the physical act of transferring a copy.
  3. You may modify your copy or copies of the Program or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following:
    • cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and
    • cause the whole of any work that you distribute or publish, that in whole or in part contains the Program or any part thereof, either with or without modifications, to be licensed at no charge to all third parties under the terms of this General Public License (except that you may choose to grant warranty protection to some or all third parties, at your option).
    • If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the simplest and most usual way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this General Public License.
    • You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
    Mere aggregation of another independent work with the Program (or its derivative) on a volume of a storage or distribution medium does not bring the other work under the scope of these terms.
  4. You may copy and distribute the Program (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following:
    • accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or,
    • accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal charge for the cost of distribution) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or,
    • accompany it with the information you received as to where the corresponding source code may be obtained. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.)
    Source code for a work means the preferred form of the work for making modifications to it. For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs, or for standard header files or definitions files that accompany that operating system.
  5. You may not copy, modify, sublicense, distribute or transfer the Program except as expressly provided under this General Public License. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the Program is void, and will automatically terminate your rights to use the Program under this License. However, parties who have received copies, or rights to use copies, from you under this General Public License will not have their licenses terminated so long as such parties remain in full compliance.
  6. By copying, distributing or modifying the Program (or any work based on the Program) you indicate your acceptance of this license to do so, and all its terms and conditions.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein.
  8. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of the license which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the license, you may choose any version ever published by the Free Software Foundation.
  9. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  10. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  11. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

Appendix: How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to humanity, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) 19yy  name of author

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the
program `Gnomovision' (a program to direct compilers to make passes
at assemblers) written by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

That's all there is to it!

Contributors to GNU gperf Utility

  • The GNU gperf perfect hash function generator utility was originally written in GNU C++ by Douglas C. Schmidt. It is now also available in a highly-portable "old-style" C version. The general idea for the perfect hash function generator was inspired by Keith Bostic's algorithm written in C, and distributed to net.sources around 1984. The current program is a heavily modified, enhanced, and extended implementation of Keith's basic idea, created at the University of California, Irvine. Bugs, patches, and suggestions should be reported to <bug-gnu-utils@gnu.org> and <schmidt@ics.uci.edu>.
  • Special thanks is extended to Michael Tiemann and Doug Lea, for providing a useful compiler, and for giving me a forum to exhibit my creation. In addition, Adam de Boor and Nels Olson provided many tips and insights that greatly helped improve the quality and functionality of gperf.

Introduction

gperf is a perfect hash function generator written in C++. It transforms an n element user-specified keyword set W into a perfect hash function F. F uniquely maps keywords in W onto the range 0..k, where k >= n. If k = n then F is a minimal perfect hash function. gperf generates a 0..k element static lookup table and a pair of C functions. These functions determine whether a given character string s occurs in W, using at most one probe into the lookup table.

gperf currently generates the reserved keyword recognizer for lexical analyzers in several production and research compilers and language processing tools, including GNU C, GNU C++, GNU Pascal, GNU Modula 3, and GNU indent. Complete C++ source code for gperf is available via anonymous ftp from ics.uci.edu and ftp.santafe.edu. gperf was also distributed along with the GNU libg++ library for several years. A highly portable, functionally equivalent K&R C version of gperf is archived in comp.sources.unix, volume 20. Finally, a paper describing gperf's design and implementation in greater detail is available in the Second USENIX C++ Conference proceedings.

Static search structures and GNU gperf

A static search structure is an Abstract Data Type with certain fundamental operations, e.g., initialize, insert, and retrieve. Conceptually, all insertions occur before any retrievals. In practice, gperf generates a static array containing search set keywords and any associated attributes specified by the user. Thus, there is essentially no execution-time cost for the insertions. It is a useful data structure for representing static search sets. Static search sets occur frequently in software system applications. Typical static search sets include compiler reserved words, assembler instruction opcodes, and built-in shell interpreter commands. Search set members, called keywords, are inserted into the structure only once, usually during program initialization, and are not generally modified at run-time.

Numerous static search structure implementations exist, e.g., arrays, linked lists, binary search trees, digital search tries, and hash tables. Different approaches offer trade-offs between space utilization and search time efficiency. For example, an n element sorted array is space efficient, though the average-case time complexity for retrieval operations using binary search is proportional to log n. Conversely, hash table implementations often locate a table entry in constant time, but typically impose additional memory overhead and exhibit poor worst case performance.

Minimal perfect hash functions provide an optimal solution for a particular class of static search sets. A minimal perfect hash function is defined by two properties:

  • It allows keyword recognition in a static search set using at most one probe into the hash table. This represents the "perfect" property.
  • The actual memory allocated to store the keywords is precisely large enough for the keyword set, and no larger. This is the "minimal" property.

For most applications it is far easier to generate perfect hash functions than minimal perfect hash functions. Moreover, non-minimal perfect hash functions frequently execute faster than minimal ones in practice. This phenomena occurs since searching a sparse keyword table increases the probability of locating a "null" entry, thereby reducing string comparisons. gperf's default behavior generates near-minimal perfect hash functions for keyword sets. However, gperf provides many options that permit user control over the degree of minimality and perfection.

Static search sets often exhibit relative stability over time. For example, Ada's 63 reserved words have remained constant for nearly a decade. It is therefore frequently worthwhile to expend concerted effort building an optimal search structure once, if it subsequently receives heavy use multiple times. gperf removes the drudgery associated with constructing time- and space-efficient search structures by hand. It has proven a useful and practical tool for serious programming projects. Output from gperf is currently used in several production and research compilers, including GNU C, GNU C++, GNU Pascal, and GNU Modula 3. The latter two compilers are not yet part of the official GNU distribution. Each compiler utilizes gperf to automatically generate static search structures that efficiently identify their respective reserved keywords.

High-Level Description of GNU gperf

The perfect hash function generator gperf reads a set of "keywords" from a keyfile (or from the standard input by default). It attempts to derive a perfect hashing function that recognizes a member of the static keyword set with at most a single probe into the lookup table. If gperf succeeds in generating such a function it produces a pair of C source code routines that perform hashing and table lookup recognition. All generated C code is directed to the standard output. Command-line options described below allow you to modify the input and output format to gperf.

By default, gperf attempts to produce time-efficient code, with less emphasis on efficient space utilization. However, several options exist that permit trading-off execution time for storage space and vice versa. In particular, expanding the generated table size produces a sparse search structure, generally yielding faster searches. Conversely, you can direct gperf to utilize a C switch statement scheme that minimizes data space storage size. Furthermore, using a C switch may actually speed up the keyword retrieval time somewhat. Actual results depend on your C compiler, of course.

In general, gperf assigns values to the characters it is using for hashing until some set of values gives each keyword a unique value. A helpful heuristic is that the larger the hash value range, the easier it is for gperf to find and generate a perfect hash function. Experimentation is the key to getting the most from gperf.

Input Format to gperf

You can control the input keyfile format by varying certain command-line arguments, in particular the `-t' option. The input's appearance is similar to GNU utilities flex and bison (or UNIX utilities lex and yacc). Here's an outline of the general format:

declarations
%%
keywords
%%
functions

Unlike flex or bison, all sections of gperf's input are optional. The following sections describe the input format for each section.

struct Declarations and C Code Inclusion

The keyword input file optionally contains a section for including arbitrary C declarations and definitions, as well as provisions for providing a user-supplied struct. If the `-t' option is enabled, you must provide a C struct as the last component in the declaration section from the keyfile file. The first field in this struct must be a char * identifier called `name', although it is possible to modify this field's name with the `-K' option described below.

Here is simple example, using months of the year and their attributes as input:

struct months { char *name; int number; int days; int leap_days; };
%%
january,   1, 31, 31
february,  2, 28, 29
march,     3, 31, 31
april,     4, 30, 30
may,       5, 31, 31
june,      6, 30, 30
july,      7, 31, 31
august,    8, 31, 31
september, 9, 30, 30
october,  10, 31, 31
november, 11, 30, 30
december, 12, 31, 31

Separating the struct declaration from the list of key words and other fields are a pair of consecutive percent signs, %%, appearing left justified in the first column, as in the UNIX utility lex.

Using a syntax similar to GNU utilities flex and bison, it is possible to directly include C source text and comments verbatim into the generated output file. This is accomplished by enclosing the region inside left-justified surrounding %{, %} pairs. Here is an input fragment based on the previous example that illustrates this feature:

%{
#include <assert.h>
/* This section of code is inserted directly into the output. */
int return_month_days (struct months *months, int is_leap_year);
%}
struct months { char *name; int number; int days; int leap_days; };
%%
january,   1, 31, 31
february,  2, 28, 29
march,     3, 31, 31
...

It is possible to omit the declaration section entirely. In this case the keyfile begins directly with the first keyword line, e.g.:

january,   1, 31, 31
february,  2, 28, 29
march,     3, 31, 31
april,     4, 30, 30
...

Format for Keyword Entries

The second keyfile format section contains lines of keywords and any associated attributes you might supply. A line beginning with `#' in the first column is considered a comment. Everything following the `#' is ignored, up to and including the following newline.

The first field of each non-comment line is always the key itself. It should be given as a simple name, i.e., without surrounding string quotation marks, and be left-justified flush against the first column. In this context, a "field" is considered to extend up to, but not include, the first blank, comma, or newline. Here is a simple example taken from a partial list of C reserved words:

# These are a few C reserved words, see the c.gperf file
# for a complete list of ANSI C reserved words.
unsigned
sizeof
switch
signed
if
default
for
while
return

Note that unlike flex or bison the first %% marker may be elided if the declaration section is empty.

Additional fields may optionally follow the leading keyword. Fields should be separated by commas, and terminate at the end of line. What these fields mean is entirely up to you; they are used to initialize the elements of the user-defined struct provided by you in the declaration section. If the `-t' option is not enabled these fields are simply ignored. All previous examples except the last one contain keyword attributes.

Including Additional C Functions

The optional third section also corresponds closely with conventions found in flex and bison. All text in this section, starting at the final %% and extending to the end of the input file, is included verbatim into the generated output file. Naturally, it is your responsibility to ensure that the code contained in this section is valid C.

Output Format for Generated C Code with gperf

Several options control how the generated C code appears on the standard output. Two C function are generated. They are called hash and in_word_set, although you may modify the name for in_word_set with a command-line option. Both functions require two arguments, a string, char * str, and a length parameter, int len. Their default function prototypes are as follows:

static int hash (char *str, int len);
int in_word_set (char *str, int len);

By default, the generated hash function returns an integer value created by adding len to several user-specified str key positions indexed into an associated values table stored in a local static array. The associated values table is constructed internally by gperf and later output as a static local C array called hash_table; its meaning and properties are described below. See section Implementation Details of GNU gperf. The relevant key positions are specified via the `-k' option when running gperf, as detailed in the Options section below. See section Options to the gperf Utility.

Two options, `-g' (assume you are compiling with GNU C and its inline feature) and `-a' (assume ANSI C-style function prototypes), alter the content of both the generated hash and in_word_set routines. However, function in_word_set may be modified more extensively, in response to your option settings. The options that affect the in_word_set structure are:

    `-t'
    Make use of the user-defined struct.
    `-S total switch statements'
    Generate 1 or more C switch statement rather than use a large, (and potentially sparse) static array. Although the exact time and space savings of this approach vary according to your C compiler's degree of optimization, this method often results in smaller and faster code.

If the `-t' and `-S' options are omitted, the default action is to generate a char * array containing the keys, together with additional null strings used for padding the array. By experimenting with the various input and output options, and timing the resulting C code, you can determine the best option choices for different keyword set characteristics.

Options to the gperf Utility

There are many options to gperf. They were added to make the program more convenient for use with real applications. "On-line" help is readily available via the `-h' option. Here is the complete list of options.

Options that affect Interpretation of the Input File

    `-e keyword delimiter list'
    Allows the user to provide a string containing delimiters used to separate keywords from their attributes. The default is ",\n". This option is essential if you want to use keywords that have embedded commas or newlines. One useful trick is to use -e'TAB', where TAB is the literal tab character.
    `-t'
    Allows you to include a struct type declaration for generated code. Any text before a pair of consecutive %% is consider part of the type declaration. Key words and additional fields may follow this, one group of fields per line. A set of examples for generating perfect hash tables and functions for Ada, C, and G++, Pascal, and Modula 2 and 3 reserved words are distributed with this release.

Options to specify the Language for the Output Code

    `-L generated language name'
    Instructs gperf to generate code in the language specified by the option's argument. Languages handled are currently:
      `KR-C'
      Old-style K&R C. This language is understood by old-style C compilers and ANSI C compilers, but ANSI C compilers may flag warnings (or even errors) because of lacking `const'.
      `C'
      Common C. This language is understood by ANSI C compilers, and also by old-style C compilers, provided that you #define const to empty for compilers which don't know about this keyword.
      `ANSI-C'
      ANSI C. This language is understood by ANSI C compilers and C++ compilers.
      `C++'
      C++. This language is understood by C++ compilers.
    The default is C.
    `-a'
    This option is supported for compatibility with previous releases of gperf. It does not do anything.
    `-g'
    This option is supported for compatibility with previous releases of gperf. It does not do anything.

Options for fine tuning Details in the Output Code

    `-K key name'
    This option is only useful when option `-t' has been given. By default, the program assumes the structure component identifier for the keyword is `name'. This option allows an arbitrary choice of identifier for this component, although it still must occur as the first field in your supplied struct.
    `-H hash function name'
    Allows you to specify the name for the generated hash function. Default name is `hash'. This option permits the use of two hash tables in the same file.
    `-N lookup function name'
    Allows you to specify the name for the generated lookup function. Default name is `in_word_set'. This option permits completely automatic generation of perfect hash functions, especially when multiple generated hash functions are used in the same application.
    `-Z class name'
    This option is only useful when option `-L C++' has been given. It allows you to specify the name of generated C++ class. Default name is Perfect_Hash.
    `-7'
    This option specifies that all strings that will be passed as arguments to the generated hash function and the generated lookup function will solely consist of 7-bit ASCII characters (characters in the range 0..127). (Note that the ANSI C functions isalnum and isgraph do not guarantee that a character is in this range. Only an explicit test like `c >= 'A' && c <= 'Z'' guarantees this.) This was the default in earlier versions of gperf; now the default is to assume 8-bit characters.
    `-c'
    Generates C code that uses the strncmp function to perform string comparisons. The default action is to use strcmp.
    `-C'
    Makes the contents of all generated lookup tables constant, i.e., "readonly". Many compilers can generate more efficient code for this by putting the tables in readonly memory.
    `-E'
    Define constant values using an enum local to the lookup function rather than with #defines. This also means that different lookup functions can reside in the same file. Thanks to James Clark <jjc@ai.mit.edu>.
    `-I'
    Include the necessary system include file, <string.h>, at the beginning of the code. By default, this is not done; the user must include this header file himself to allow compilation of the code.
    `-G'
    Generate the static table of keywords as a static global variable, rather than hiding it inside of the lookup function (which is the default behavior).
    `-W hash table array name'
    Allows you to specify the name for the generated array containing the hash table. Default name is `wordlist'. This option permits the use of two hash tables in the same file, even when the option `-G' is given.
    `-S total switch statements'
    Causes the generated C code to use a switch statement scheme, rather than an array lookup table. This can lead to a reduction in both time and space requirements for some keyfiles. The argument to this option determines how many switch statements are generated. A value of 1 generates 1 switch containing all the elements, a value of 2 generates 2 tables with 1/2 the elements in each switch, etc. This is useful since many C compilers cannot correctly generate code for large switch statements. This option was inspired in part by Keith Bostic's original C program.
    `-T'
    Prevents the transfer of the type declaration to the output file. Use this option if the type is already defined elsewhere.
    `-p'
    This option is supported for compatibility with previous releases of gperf. It does not do anything.

Options for changing the Algorithms employed by gperf

    `-k keys'
    Allows selection of the character key positions used in the keywords' hash function. The allowable choices range between 1-126, inclusive. The positions are separated by commas, e.g., `-k 9,4,13,14'; ranges may be used, e.g., `-k 2-7'; and positions may occur in any order. Furthermore, the meta-character '*' causes the generated hash function to consider all character positions in each key, whereas '$' instructs the hash function to use the "final character" of a key (this is the only way to use a character position greater than 126, incidentally). For instance, the option `-k 1,2,4,6-10,'$'' generates a hash function that considers positions 1,2,4,6,7,8,9,10, plus the last character in each key (which may differ for each key, obviously). Keys with length less than the indicated key positions work properly, since selected key positions exceeding the key length are simply not referenced in the hash function.
    `-l'
    Compare key lengths before trying a string comparison. This might cut down on the number of string comparisons made during the lookup, since keys with different lengths are never compared via strcmp. However, using `-l' might greatly increase the size of the generated C code if the lookup table range is large (which implies that the switch option `-S' is not enabled), since the length table contains as many elements as there are entries in the lookup table.
    `-D'
    Handle keywords whose key position sets hash to duplicate values. Duplicate hash values occur for two reasons:
    • Since gperf does not backtrack it is possible for it to process all your input keywords without finding a unique mapping for each word. However, frequently only a very small number of duplicates occur, and the majority of keys still require one probe into the table.
    • Sometimes a set of keys may have the same names, but possess different attributes. With the -D option gperf treats all these keys as part of an equivalence class and generates a perfect hash function with multiple comparisons for duplicate keys. It is up to you to completely disambiguate the keywords by modifying the generated C code. However, gperf helps you out by organizing the output.
    Option `-D' is extremely useful for certain large or highly redundant keyword sets, e.g., assembler instruction opcodes. Using this option usually means that the generated hash function is no longer perfect. On the other hand, it permits gperf to work on keyword sets that it otherwise could not handle.
    `-f iteration amount'
    Generate the perfect hash function "fast". This decreases gperf's running time at the cost of minimizing generated table-size. The iteration amount represents the number of times to iterate when resolving a collision. `0' means iterate by the number of keywords. This option is probably most useful when used in conjunction with options `-D' and/or `-S' for large keyword sets.
    `-i initial value'
    Provides an initial value for the associate values array. Default is 0. Increasing the initial value helps inflate the final table size, possibly leading to more time efficient keyword lookups. Note that this option is not particularly useful when `-S' is used. Also, `-i' is overriden when the `-r' option is used.
    `-j jump value'
    Affects the "jump value", i.e., how far to advance the associated character value upon collisions. Jump value is rounded up to an odd number, the default is 5. If the jump value is 0 gperf jumps by random amounts.
    `-n'
    Instructs the generator not to include the length of a keyword when computing its hash value. This may save a few assembly instructions in the generated lookup table.
    `-o'
    Reorders the keywords by sorting the keywords so that frequently occuring key position set components appear first. A second reordering pass follows so that keys with "already determined values" are placed towards the front of the keylist. This may decrease the time required to generate a perfect hash function for many keyword sets, and also produce more minimal perfect hash functions. The reason for this is that the reordering helps prune the search time by handling inevitable collisions early in the search process. On the other hand, if the number of keywords is very large using `-o' may increase gperf's execution time, since collisions will begin earlier and continue throughout the remainder of keyword processing. See Cichelli's paper from the January 1980 Communications of the ACM for details.
    `-r'
    Utilizes randomness to initialize the associated values table. This frequently generates solutions faster than using deterministic initialization (which starts all associated values at 0). Furthermore, using the randomization option generally increases the size of the table. If gperf has difficultly with a certain keyword set try using `-r' or `-D'.
    `-s size-multiple'
    Affects the size of the generated hash table. The numeric argument for this option indicates "how many times larger or smaller" the maximum associated value range should be, in relationship to the number of keys. If the size-multiple is negative the maximum associated value is calculated by dividing it into the total number of keys. For example, a value of 3 means "allow the maximum associated value to be about 3 times larger than the number of input keys". Conversely, a value of -3 means "allow the maximum associated value to be about 3 times smaller than the number of input keys". Negative values are useful for limiting the overall size of the generated hash table, though this usually increases the number of duplicate hash values. If `generate switch' option `-S' is not enabled, the maximum associated value influences the static array table size, and a larger table should decrease the time required for an unsuccessful search, at the expense of extra table space. The default value is 1, thus the default maximum associated value about the same size as the number of keys (for efficiency, the maximum associated value is always rounded up to a power of 2). The actual table size may vary somewhat, since this technique is essentially a heuristic. In particular, setting this value too high slows down gperf's runtime, since it must search through a much larger range of values. Judicious use of the `-f' option helps alleviate this overhead, however.

Informative Output

    `-h'
    Prints a short summary on the meaning of each program option. Aborts further program execution.
    `-v'
    Prints out the current version number.
    `-d'
    Enables the debugging option. This produces verbose diagnostics to "standard error" when gperf is executing. It is useful both for maintaining the program and for determining whether a given set of options is actually speeding up the search for a solution. Some useful information is dumped at the end of the program when the `-d' option is enabled.

Known Bugs and Limitations with gperf

The following are some limitations with the current release of gperf:

  • The gperf utility is tuned to execute quickly, and works quickly for small to medium size data sets (around 1000 keywords). It is extremely useful for maintaining perfect hash functions for compiler keyword sets. Several recent enhancements now enable gperf to work efficiently on much larger keyword sets (over 15,000 keywords). When processing large keyword sets it helps greatly to have over 8 megs of RAM. However, since gperf does not backtrack no guaranteed solution occurs on every run. On the other hand, it is usually easy to obtain a solution by varying the option parameters. In particular, try the `-r' option, and also try changing the default arguments to the `-s' and `-j' options. To guarantee a solution, use the `-D' and `-S' options, although the final results are not likely to be a perfect hash function anymore! Finally, use the `-f' option if you want gperf to generate the perfect hash function fast, with less emphasis on making it minimal.
  • The size of the generate static keyword array can get extremely large if the input keyword file is large or if the keywords are quite similar. This tends to slow down the compilation of the generated C code, and greatly inflates the object code size. If this situation occurs, consider using the `-S' option to reduce data size, potentially increasing keyword recognition time a negligible amount. Since many C compilers cannot correctly generated code for large switch statements it is important to qualify the -S option with an appropriate numerical argument that controls the number of switch statements generated.
  • The maximum number of key positions selected for a given key has an arbitrary limit of 126. This restriction should be removed, and if anyone considers this a problem write me and let me know so I can remove the constraint.

Things Still Left to Do

It should be "relatively" easy to replace the current perfect hash function algorithm with a more exhaustive approach; the perfect hash module is essential independent from other program modules. Additional worthwhile improvements include:

  • Make the algorithm more robust. At present, the program halts with an error diagnostic if it can't find a direct solution and the `-D' option is not enabled. A more comprehensive, albeit computationally expensive, approach would employ backtracking or enable alternative options and retry. It's not clear how helpful this would be, in general, since most search sets are rather small in practice.
  • Another useful extension involves modifying the program to generate "minimal" perfect hash functions (under certain circumstances, the current version can be rather extravagant in the generated table size). Again, this is mostly of theoretical interest, since a sparse table often produces faster lookups, and use of the `-S' switch option can minimize the data size, at the expense of slightly longer lookups (note that the gcc compiler generally produces good code for switch statements, reducing the need for more complex schemes).
  • In addition to improving the algorithm, it would also be useful to generate a C++ class or Ada package as the code output, in addition to the current C routines.

Implementation Details of GNU gperf

A paper describing the high-level description of the data structures and algorithms used to implement gperf will soon be available. This paper is useful not only from a maintenance and enhancement perspective, but also because they demonstrate several clever and useful programming techniques, e.g., `Iteration Number' boolean arrays, double hashing, a "safe" and efficient method for reading arbitrarily long input from a file, and a provably optimal algorithm for simultaneously determining both the minimum and maximum elements in a list.

Bibliography

[1] Chang, C.C.: A Scheme for Constructing Ordered Minimal Perfect Hashing Functions Information Sciences 39(1986), 187-195. [2] Cichelli, Richard J. Author's Response to "On Cichelli's Minimal Perfect Hash Functions Method" Communications of the ACM, 23, 12(December 1980), 729. [3] Cichelli, Richard J. Minimal Perfect Hash Functions Made Simple Communications of the ACM, 23, 1(January 1980), 17-19. [4] Cook, C. R. and Oldehoeft, R.R. A Letter Oriented Minimal Perfect Hashing Function SIGPLAN Notices, 17, 9(September 1982), 18-27.

[5] Cormack, G. V. and Horspool, R. N. S. and Kaiserwerth, M. Practical Perfect Hashing Computer Journal, 28, 1(January 1985), 54-58. [6] Jaeschke, G. Reciprocal Hashing: A Method for Generating Minimal Perfect Hashing Functions Communications of the ACM, 24, 12(December 1981), 829-833.

[7] Jaeschke, G. and Osterburg, G. On Cichelli's Minimal Perfect Hash Functions Method Communications of the ACM, 23, 12(December 1980), 728-729.

[8] Sager, Thomas J. A Polynomial Time Generator for Minimal Perfect Hash Functions Communications of the ACM, 28, 5(December 1985), 523-532

[9] Schmidt, Douglas C. GPERF: A Perfect Hash Function Generator Second USENIX C++ Conference Proceedings, April 1990.

[10] Sebesta, R.W. and Taylor, M.A. Minimal Perfect Hash Functions for Reserved Word Lists SIGPLAN Notices, 20, 12(September 1985), 47-53.

[11] Sprugnoli, R. Perfect Hashing Functions: A Single Probe Retrieving Method for Static Sets Communications of the ACM, 20 11(November 1977), 841-850.

[12] Stallman, Richard M. Using and Porting GNU CC Free Software Foundation, 1988.

[13] Stroustrup, Bjarne The C++ Programming Language. Addison-Wesley, 1986.

[14] Tiemann, Michael D. User's Guide to GNU C++ Free Software Foundation, 1989.

This document was generated on 7 November 1998 using the texi2html translator version 1.52.


GNU gprof

The GNU Profiler

Jay Fenlason and Richard Stallman

Table of Contents

  • Introduction to Profiling
  • Compiling a Program for Profiling
  • Executing the Program
  • gprof Command Summary
    • Output Options
    • Analysis Options
    • Miscellaneous Options
    • Depricated Options
    • Symspecs
  • Interpreting gprof's Output
    • The Flat Profile
    • The Call Graph
      • The Primary Line
      • Lines for a Function's Callers
      • Lines for a Function's Subroutines
      • How Mutually Recursive Functions Are Described
    • Line-by-line Profiling
    • The Annotated Source Listing
  • Inaccuracy of gprof Output
    • Statistical Sampling Error
    • Estimating children Times
  • Answers to Common Questions
  • Incompatibilities with Unix gprof
  • Details of Profiling
    • Implementation of Profiling
    • Profiling Data File Format
      • Histogram Records
      • Call-Graph Records
      • Basic-Block Execution Count Records
    • gprof's Internal Operation
      • Debugging gprof

This manual describes the GNU profiler, gprof, and how you can use it to determine which parts of a program are taking most of the execution time. We assume that you know how to write, compile, and execute programs. GNU gprof was written by Jay Fenlason.

This manual was edited January 1993 by Jeffrey Osier and updated September 1997 by Brent Baccala.

Copyright (C) 1988, 1992, 1997, 1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the same conditions as for modified versions.

Introduction to Profiling

Profiling allows you to learn where your program spent its time and which functions called which other functions while it was executing. This information can show you which pieces of your program are slower than you expected, and might be candidates for rewriting to make your program execute faster. It can also tell you which functions are being called more or less often than you expected. This may help you spot bugs that had otherwise been unnoticed.

Since the profiler uses information collected during the actual execution of your program, it can be used on programs that are too large or too complex to analyze by reading the source. However, how your program is run will affect the information that shows up in the profile data. If you don't use some feature of your program while it is being profiled, no profile information will be generated for that feature.

Profiling has several steps:

  • You must compile and link your program with profiling enabled. See section Compiling a Program for Profiling.
  • You must execute your program to generate a profile data file. See section Executing the Program.
  • You must run gprof to analyze the profile data. See section gprof Command Summary.

The next three chapters explain these steps in greater detail.

Several forms of output are available from the analysis.

The flat profile shows how much time your program spent in each function, and how many times that function was called. If you simply want to know which functions burn most of the cycles, it is stated concisely here. See section The Flat Profile.

The call graph shows, for each function, which functions called it, which other functions it called, and how many times. There is also an estimate of how much time was spent in the subroutines of each function. This can suggest places where you might try to eliminate function calls that use a lot of time. See section The Call Graph.

The annotated source listing is a copy of the program's source code, labeled with the number of times each line of the program was executed. See section The Annotated Source Listing.

To better understand how profiling works, you may wish to read a description of its implementation. See section Implementation of Profiling.

Compiling a Program for Profiling

The first step in generating profile information for your program is to compile and link it with profiling enabled.

To compile a source file for profiling, specify the `-pg' option when you run the compiler. (This is in addition to the options you normally use.)

To link the program for profiling, if you use a compiler such as cc to do the linking, simply specify `-pg' in addition to your usual options. The same option, `-pg', alters either compilation or linking to do what is necessary for profiling. Here are examples:

cc -g -c myprog.c utils.c -pg
cc -o myprog myprog.o utils.o -pg

The `-pg' option also works with a command that both compiles and links:

cc -o myprog myprog.c utils.c -g -pg

If you run the linker ld directly instead of through a compiler such as cc, you may have to specify a profiling startup file `gcrt0.o' as the first input file instead of the usual startup file `crt0.o'. In addition, you would probably want to specify the profiling C library, `libc_p.a', by writing `-lc_p' instead of the usual `-lc'. This is not absolutely necessary, but doing this gives you number-of-calls information for standard library functions such as read and open. For example:

ld -o myprog /lib/gcrt0.o myprog.o utils.o -lc_p

If you compile only some of the modules of the program with `-pg', you can still profile the program, but you won't get complete information about the modules that were compiled without `-pg'. The only information you get for the functions in those modules is the total time spent in them; there is no record of how many times they were called, or from where. This will not affect the flat profile (except that the calls field for the functions will be blank), but will greatly reduce the usefulness of the call graph.

If you wish to perform line-by-line profiling, you will also need to specify the `-g' option, instructing the compiler to insert debugging symbols into the program that match program addresses to source code lines. See section Line-by-line Profiling.

In addition to the `-pg' and `-g' options, you may also wish to specify the `-a' option when compiling. This will instrument the program to perform basic-block counting. As the program runs, it will count how many times it executed each branch of each `if' statement, each iteration of each `do' loop, etc. This will enable gprof to construct an annotated source code listing showing how many times each line of code was executed.

Executing the Program

Once the program is compiled for profiling, you must run it in order to generate the information that gprof needs. Simply run the program as usual, using the normal arguments, file names, etc. The program should run normally, producing the same output as usual. It will, however, run somewhat slower than normal because of the time spent collecting and the writing the profile data.

The way you run the program--the arguments and input that you give it--may have a dramatic effect on what the profile information shows. The profile data will describe the parts of the program that were activated for the particular input you use. For example, if the first command you give to your program is to quit, the profile data will show the time used in initialization and in cleanup, but not much else.

Your program will write the profile data into a file called `gmon.out' just before exiting. If there is already a file called `gmon.out', its contents are overwritten. There is currently no way to tell the program to write the profile data under a different name, but you can rename the file afterward if you are concerned that it may be overwritten.

In order to write the `gmon.out' file properly, your program must exit normally: by returning from main or by calling exit. Calling the low-level function _exit does not write the profile data, and neither does abnormal termination due to an unhandled signal.

The `gmon.out' file is written in the program's current working directory at the time it exits. This means that if your program calls chdir, the `gmon.out' file will be left in the last directory your program chdir'd to. If you don't have permission to write in this directory, the file is not written, and you will get an error message.

Older versions of the GNU profiling library may also write a file called `bb.out'. This file, if present, contains an human-readable listing of the basic-block execution counts. Unfortunately, the appearance of a human-readable `bb.out' means the basic-block counts didn't get written into `gmon.out'. The Perl script bbconv.pl, included with the gprof source distribution, will convert a `bb.out' file into a format readable by gprof.

gprof Command Summary

After you have a profile data file `gmon.out', you can run gprof to interpret the information in it. The gprof program prints a flat profile and a call graph on standard output. Typically you would redirect the output of gprof into a file with `>'.

You run gprof like this:

gprof options [executable-file [profile-data-files...]] [> outfile]

Here square-brackets indicate optional arguments.

If you omit the executable file name, the file `a.out' is used. If you give no profile data file name, the file `gmon.out' is used. If any file is not in the proper format, or if the profile data file does not appear to belong to the executable file, an error message is printed.

You can give more than one profile data file by entering all their names after the executable file name; then the statistics in all the data files are summed together.

The order of these options does not matter.

Output Options

These options specify which of several output formats gprof should produce.

Many of these options take an optional symspec to specify functions to be included or excluded. These options can be specified multiple times, with different symspecs, to include or exclude sets of symbols. See section Symspecs.

Specifying any of these options overrides the default (`-p -q'), which prints a flat profile and call graph analysis for all functions.

-A[symspec]
--annotated-source[=symspec]
The `-A' option causes gprof to print annotated source code. If symspec is specified, print output only for matching symbols. See section The Annotated Source Listing.
-b
--brief
If the `-b' option is given, gprof doesn't print the verbose blurbs that try to explain the meaning of all of the fields in the tables. This is useful if you intend to print out the output, or are tired of seeing the blurbs.
-C[symspec]
--exec-counts[=symspec]
The `-C' option causes gprof to print a tally of functions and the number of times each was called. If symspec is specified, print tally only for matching symbols. If the profile data file contains basic-block count records, specifing the `-l' option, along with `-C', will cause basic-block execution counts to be tallied and displayed.
-i
--file-info
The `-i' option causes gprof to display summary information about the profile data file(s) and then exit. The number of histogram, call graph, and basic-block count records is displayed.
-I dirs
--directory-path=dirs
The `-I' option specifies a list of search directories in which to find source files. Environment variable GPROF_PATH can also be used to convery this information. Used mostly for annotated source output.
-J[symspec]
--no-annotated-source[=symspec]
The `-J' option causes gprof not to print annotated source code. If symspec is specified, gprof prints annotated source, but excludes matching symbols.
-L
--print-path
Normally, source filenames are printed with the path component suppressed. The `-L' option causes gprof to print the full pathname of source filenames, which is determined from symbolic debugging information in the image file and is relative to the directory in which the compiler was invoked.
-p[symspec]
--flat-profile[=symspec]
The `-p' option causes gprof to print a flat profile. If symspec is specified, print flat profile only for matching symbols. See section The Flat Profile.
-P[symspec]
--no-flat-profile[=symspec]
The `-P' option causes gprof to suppress printing a flat profile. If symspec is specified, gprof prints a flat profile, but excludes matching symbols.
-q[symspec]
--graph[=symspec]
The `-q' option causes gprof to print the call graph analysis. If symspec is specified, print call graph only for matching symbols and their children. See section The Call Graph.
-Q[symspec]
--no-graph[=symspec]
The `-Q' option causes gprof to suppress printing the call graph. If symspec is specified, gprof prints a call graph, but excludes matching symbols.
-y
--separate-files
This option affects annotated source output only. Normally, gprof prints annotated source files to standard-output. If this option is specified, annotated source for a file named `path/filename' is generated in the file `filename-ann'.
-Z[symspec]
--no-exec-counts[=symspec]
The `-Z' option causes gprof not to print a tally of functions and the number of times each was called. If symspec is specified, print tally, but exclude matching symbols.
--function-ordering
The `--function-ordering' option causes gprof to print a suggested function ordering for the program based on profiling data. This option suggests an ordering which may improve paging, tlb and cache behavior for the program on systems which support arbitrary ordering of functions in an executable. The exact details of how to force the linker to place functions in a particular order is system dependent and out of the scope of this manual.
--file-ordering map_file
The `--file-ordering' option causes gprof to print a suggested .o link line ordering for the program based on profiling data. This option suggests an ordering which may improve paging, tlb and cache behavior for the program on systems which do not support arbitrary ordering of functions in an executable. Use of the `-a' argument is highly recommended with this option. The map_file argument is a pathname to a file which provides function name to object file mappings. The format of the file is similar to the output of the program nm.
c-parse.o:00000000 T yyparse
c-parse.o:00000004 C yyerrflag
c-lang.o:00000000 T maybe_objc_method_name
c-lang.o:00000000 T print_lang_statistics
c-lang.o:00000000 T recognize_objc_keyword
c-decl.o:00000000 T print_lang_identifier
c-decl.o:00000000 T print_lang_type
...
GNU nm `--extern-only' `--defined-only' `-v' `--print-file-name' can be used to create map_file.
-T
--traditional
The `-T' option causes gprof to print its output in "traditional" BSD style.
-w width
--width=width
Sets width of output lines to width. Currently only used when printing the function index at the bottom of the call graph.
-x
--all-lines
This option affects annotated source output only. By default, only the lines at the beginning of a basic-block are annotated. If this option is specified, every line in a basic-block is annotated by repeating the annotation for the first line. This behavior is similar to tcov's `-a'.
--demangle
--no-demangle
These options control whether C++ symbol names should be demangled when printing output. The default is to demangle symbols. The --no-demangle option may be used to turn off demangling.

Analysis Options

-a
--no-static
The `-a' option causes gprof to suppress the printing of statically declared (private) functions. (These are functions whose names are not listed as global, and which are not visible outside the file/function/block where they were defined.) Time spent in these functions, calls to/from them, etc, will all be attributed to the function that was loaded directly before it in the executable file. This option affects both the flat profile and the call graph.
-c
--static-call-graph
The `-c' option causes the call graph of the program to be augmented by a heuristic which examines the text space of the object file and identifies function calls in the binary machine code. Since normal call graph records are only generated when functions are entered, this option identifies children that could have been called, but never were. Calls to functions that were not compiled with profiling enabled are also identified, but only if symbol table entries are present for them. Calls to dynamic library routines are typically not found by this option. Parents or children identified via this heuristic are indicated in the call graph with call counts of `0'.
-D
--ignore-non-functions
The `-D' option causes gprof to ignore symbols which are not known to be functions. This option will give more accurate profile data on systems where it is supported (Solaris and HPUX for example).
-k from/to
The `-k' option allows you to delete from the call graph any arcs from symbols matching symspec from to those matching symspec to.
-l
--line
The `-l' option enables line-by-line profiling, which causes histogram hits to be charged to individual source code lines, instead of functions. If the program was compiled with basic-block counting enabled, this option will also identify how many times each line of code was executed. While line-by-line profiling can help isolate where in a large function a program is spending its time, it also significantly increases the running time of gprof, and magnifies statistical inaccuracies. See section Statistical Sampling Error.
-m num
--min-count=num
This option affects execution count output only. Symbols that are executed less than num times are suppressed.
-n[symspec]
--time[=symspec]
The `-n' option causes gprof, in its call graph analysis, to only propagate times for symbols matching symspec.
-N[symspec]
--no-time[=symspec]
The `-n' option causes gprof, in its call graph analysis, not to propagate times for symbols matching symspec.
-z
--display-unused-functions
If you give the `-z' option, gprof will mention all functions in the flat profile, even those that were never called, and that had no time spent in them. This is useful in conjunction with the `-c' option for discovering which routines were never called.

Miscellaneous Options

-d[num]
--debug[=num]
The `-d num' option specifies debugging options. If num is not specified, enable all debugging. See section Debugging gprof.
-Oname
--file-format=name
Selects the format of the profile data files. Recognized formats are `auto' (the default), `bsd', `magic', and `prof' (not yet supported).
-s
--sum
The `-s' option causes gprof to summarize the information in the profile data files it read in, and write out a profile data file called `gmon.sum', which contains all the information from the profile data files that gprof read in. The file `gmon.sum' may be one of the specified input files; the effect of this is to merge the data in the other input files into `gmon.sum'. Eventually you can run gprof again without `-s' to analyze the cumulative data in the file `gmon.sum'.
-v
--version
The `-v' flag causes gprof to print the current version number, and then exit.

Depricated Options

These options have been replaced with newer versions that use symspecs.
-e function_name
The `-e function' option tells gprof to not print information about the function function_name (and its children...) in the call graph. The function will still be listed as a child of any functions that call it, but its index number will be shown as `[not printed]'. More than one `-e' option may be given; only one function_name may be indicated with each `-e' option.
-E function_name
The -E function option works like the -e option, but time spent in the function (and children who were not called from anywhere else), will not be used to compute the percentages-of-time for the call graph. More than one `-E' option may be given; only one function_name may be indicated with each `-E' option.
-f function_name
The `-f function' option causes gprof to limit the call graph to the function function_name and its children (and their children...). More than one `-f' option may be given; only one function_name may be indicated with each `-f' option.
-F function_name
The `-F function' option works like the -f option, but only time spent in the function and its children (and their children...) will be used to determine total-time and percentages-of-time for the call graph. More than one `-F' option may be given; only one function_name may be indicated with each `-F' option. The `-F' option overrides the `-E' option.

Note that only one function can be specified with each -e, -E, -f or -F option. To specify more than one function, use multiple options. For example, this command:

gprof -e boring -f foo -f bar myprogram > gprof.output

lists in the call graph all functions that were reached from either foo or bar and were not reachable from boring.

Symspecs

Many of the output options allow functions to be included or excluded using symspecs (symbol specifications), which observe the following syntax:

  filename_containing_a_dot
| funcname_not_containing_a_dot
| linenumber
| ( [ any_filename ] `:' ( any_funcname | linenumber ) )

Here are some sample symspecs:

main.c
Selects everything in file "main.c"---the dot in the string tells gprof to interpret the string as a filename, rather than as a function name. To select a file whose name does not contain a dot, a trailing colon should be specified. For example, "odd:" is interpreted as the file named "odd".
main
Selects all functions named "main". Notice that there may be multiple instances of the same function name because some of the definitions may be local (i.e., static). Unless a function name is unique in a program, you must use the colon notation explained below to specify a function from a specific source file. Sometimes, function names contain dots. In such cases, it is necessar to add a leading colon to the name. For example, ":.mul" selects function ".mul".
main.c:main
Selects function "main" in file "main.c".
main.c:134
Selects line 134 in file "main.c".

Interpreting gprof's Output

gprof can produce several different output styles, the most important of which are described below. The simplest output styles (file information, execution count, and function and file ordering) are not described here, but are documented with the respective options that trigger them. See section Output Options.

The Flat Profile

The flat profile shows the total amount of time your program spent executing each function. Unless the `-z' option is given, functions with no apparent time spent in them, and no apparent calls to them, are not mentioned. Note that if a function was not compiled for profiling, and didn't run long enough to show up on the program counter histogram, it will be indistinguishable from a function that was never called.

This is part of a flat profile for a small program:

Flat profile:

Each sample counts as 0.01 seconds.
  %   cumulative   self              self     total
 time   seconds   seconds    calls  ms/call  ms/call  name
 33.34      0.02     0.02     7208     0.00     0.00  open
 16.67      0.03     0.01      244     0.04     0.12  offtime
 16.67      0.04     0.01        8     1.25     1.25  memccpy
 16.67      0.05     0.01        7     1.43     1.43  write
 16.67      0.06     0.01                             mcount
  0.00      0.06     0.00      236     0.00     0.00  tzset
  0.00      0.06     0.00      192     0.00     0.00  tolower
  0.00      0.06     0.00       47     0.00     0.00  strlen
  0.00      0.06     0.00       45     0.00     0.00  strchr
  0.00      0.06     0.00        1     0.00    50.00  main
  0.00      0.06     0.00        1     0.00     0.00  memcpy
  0.00      0.06     0.00        1     0.00    10.11  print
  0.00      0.06     0.00        1     0.00     0.00  profil
  0.00      0.06     0.00        1     0.00    50.00  report
...

The functions are sorted by first by decreasing run-time spent in them, then by decreasing number of calls, then alphabetically by name. The functions `mcount' and `profil' are part of the profiling aparatus and appear in every flat profile; their time gives a measure of the amount of overhead due to profiling.

Just before the column headers, a statement appears indicating how much time each sample counted as. This sampling period estimates the margin of error in each of the time figures. A time figure that is not much larger than this is not reliable. In this example, each sample counted as 0.01 seconds, suggesting a 100 Hz sampling rate. The program's total execution time was 0.06 seconds, as indicated by the `cumulative seconds' field. Since each sample counted for 0.01 seconds, this means only six samples were taken during the run. Two of the samples occured while the program was in the `open' function, as indicated by the `self seconds' field. Each of the other four samples occured one each in `offtime', `memccpy', `write', and `mcount'. Since only six samples were taken, none of these values can be regarded as particularly reliable. In another run, the `self seconds' field for `mcount' might well be `0.00' or `0.02'. See section Statistical Sampling Error, for a complete discussion.

The remaining functions in the listing (those whose `self seconds' field is `0.00') didn't appear in the histogram samples at all. However, the call graph indicated that they were called, so therefore they are listed, sorted in decreasing order by the `calls' field. Clearly some time was spent executing these functions, but the paucity of histogram samples prevents any determination of how much time each took.

Here is what the fields in each line mean:

% time
This is the percentage of the total execution time your program spent in this function. These should all add up to 100%.
cumulative seconds
This is the cumulative total number of seconds the computer spent executing this functions, plus the time spent in all the functions above this one in this table.
self seconds
This is the number of seconds accounted for by this function alone. The flat profile listing is sorted first by this number.
calls
This is the total number of times the function was called. If the function was never called, or the number of times it was called cannot be determined (probably because the function was not compiled with profiling enabled), the calls field is blank.
self ms/call
This represents the average number of milliseconds spent in this function per call, if this function is profiled. Otherwise, this field is blank for this function.
total ms/call
This represents the average number of milliseconds spent in this function and its descendants per call, if this function is profiled. Otherwise, this field is blank for this function. This is the only field in the flat profile that uses call graph analysis.
name
This is the name of the function. The flat profile is sorted by this field alphabetically after the self seconds and calls fields are sorted.

The Call Graph

The call graph shows how much time was spent in each function and its children. From this information, you can find functions that, while they themselves may not have used much time, called other functions that did use unusual amounts of time.

Here is a sample call from a small program. This call came from the same gprof run as the flat profile example in the previous chapter.

granularity: each sample hit covers 2 byte(s) for 20.00% of 0.05 seconds

index % time    self  children    called     name
                                                 <spontaneous>
[1]    100.0    0.00    0.05                 start [1]
                0.00    0.05       1/1           main [2]
                0.00    0.00       1/2           on_exit [28]
                0.00    0.00       1/1           exit [59]
-----------------------------------------------
                0.00    0.05       1/1           start [1]
[2]    100.0    0.00    0.05       1         main [2]
                0.00    0.05       1/1           report [3]
-----------------------------------------------
                0.00    0.05       1/1           main [2]
[3]    100.0    0.00    0.05       1         report [3]
                0.00    0.03       8/8           timelocal [6]
                0.00    0.01       1/1           print [9]
                0.00    0.01       9/9           fgets [12]
                0.00    0.00      12/34          strncmp <cycle 1> [40]
                0.00    0.00       8/8           lookup [20]
                0.00    0.00       1/1           fopen [21]
                0.00    0.00       8/8           chewtime [24]
                0.00    0.00       8/16          skipspace [44]
-----------------------------------------------
[4]     59.8    0.01        0.02       8+472     <cycle 2 as a whole>	[4]
                0.01        0.02     244+260         offtime <cycle 2> [7]
                0.00        0.00     236+1           tzset <cycle 2> [26]
-----------------------------------------------

The lines full of dashes divide this table into entries, one for each function. Each entry has one or more lines.

In each entry, the primary line is the one that starts with an index number in square brackets. The end of this line says which function the entry is for. The preceding lines in the entry describe the callers of this function and the following lines describe its subroutines (also called children when we speak of the call graph).

The entries are sorted by time spent in the function and its subroutines.

The internal profiling function mcount (see section The Flat Profile) is never mentioned in the call graph.

The Primary Line

The primary line in a call graph entry is the line that describes the function which the entry is about and gives the overall statistics for this function.

For reference, we repeat the primary line from the entry for function report in our main example, together with the heading line that shows the names of the fields:

index  % time    self  children called     name
...
[3]    100.0    0.00    0.05       1         report [3]

Here is what the fields in the primary line mean:

index
Entries are numbered with consecutive integers. Each function therefore has an index number, which appears at the beginning of its primary line. Each cross-reference to a function, as a caller or subroutine of another, gives its index number as well as its name. The index number guides you if you wish to look for the entry for that function.
% time
This is the percentage of the total time that was spent in this function, including time spent in subroutines called from this function. The time spent in this function is counted again for the callers of this function. Therefore, adding up these percentages is meaningless.
self
This is the total amount of time spent in this function. This should be identical to the number printed in the seconds field for this function in the flat profile.
children
This is the total amount of time spent in the subroutine calls made by this function. This should be equal to the sum of all the self and children entries of the children listed directly below this function.
called
This is the number of times the function was called. If the function called itself recursively, there are two numbers, separated by a `+'. The first number counts non-recursive calls, and the second counts recursive calls. In the example above, the function report was called once from main.
name
This is the name of the current function. The index number is repeated after it. If the function is part of a cycle of recursion, the cycle number is printed between the function's name and the index number (see section How Mutually Recursive Functions Are Described). For example, if function gnurr is part of cycle number one, and has index number twelve, its primary line would be end like this:
gnurr <cycle 1> [12]

Lines for a Function's Callers

A function's entry has a line for each function it was called by. These lines' fields correspond to the fields of the primary line, but their meanings are different because of the difference in context.

For reference, we repeat two lines from the entry for the function report, the primary line and one caller-line preceding it, together with the heading line that shows the names of the fields:

index  % time    self  children called     name
...
                0.00    0.05       1/1           main [2]
[3]    100.0    0.00    0.05       1         report [3]

Here are the meanings of the fields in the caller-line for report called from main:

self
An estimate of the amount of time spent in report itself when it was called from main.
children
An estimate of the amount of time spent in subroutines of report when report was called from main. The sum of the self and children fields is an estimate of the amount of time spent within calls to report from main.
called
Two numbers: the number of times report was called from main, followed by the total number of nonrecursive calls to report from all its callers.
name and index number
The name of the caller of report to which this line applies, followed by the caller's index number. Not all functions have entries in the call graph; some options to gprof request the omission of certain functions. When a caller has no entry of its own, it still has caller-lines in the entries of the functions it calls. If the caller is part of a recursion cycle, the cycle number is printed between the name and the index number.

If the identity of the callers of a function cannot be determined, a dummy caller-line is printed which has `<spontaneous>' as the "caller's name" and all other fields blank. This can happen for signal handlers.

Lines for a Function's Subroutines

A function's entry has a line for each of its subroutines--in other words, a line for each other function that it called. These lines' fields correspond to the fields of the primary line, but their meanings are different because of the difference in context.

For reference, we repeat two lines from the entry for the function main, the primary line and a line for a subroutine, together with the heading line that shows the names of the fields:

index  % time    self  children called     name
...
[2]    100.0    0.00    0.05       1         main [2]
                0.00    0.05       1/1           report [3]

Here are the meanings of the fields in the subroutine-line for main calling report:

self
An estimate of the amount of time spent directly within report when report was called from main.
children
An estimate of the amount of time spent in subroutines of report when report was called from main. The sum of the self and children fields is an estimate of the total time spent in calls to report from main.
called
Two numbers, the number of calls to report from main followed by the total number of nonrecursive calls to report. This ratio is used to determine how much of report's self and children time gets credited to main. See section Estimating children Times.
name
The name of the subroutine of main to which this line applies, followed by the subroutine's index number. If the caller is part of a recursion cycle, the cycle number is printed between the name and the index number.

How Mutually Recursive Functions Are Described

The graph may be complicated by the presence of cycles of recursion in the call graph. A cycle exists if a function calls another function that (directly or indirectly) calls (or appears to call) the original function. For example: if a calls b, and b calls a, then a and b form a cycle.

Whenever there are call paths both ways between a pair of functions, they belong to the same cycle. If a and b call each other and b and c call each other, all three make one cycle. Note that even if b only calls a if it was not called from a, gprof cannot determine this, so a and b are still considered a cycle.

The cycles are numbered with consecutive integers. When a function belongs to a cycle, each time the function name appears in the call graph it is followed by `<cycle number>'.

The reason cycles matter is that they make the time values in the call graph paradoxical. The "time spent in children" of a should include the time spent in its subroutine b and in b's subroutines--but one of b's subroutines is a! How much of a's time should be included in the children of a, when a is indirectly recursive?

The way gprof resolves this paradox is by creating a single entry for the cycle as a whole. The primary line of this entry describes the total time spent directly in the functions of the cycle. The "subroutines" of the cycle are the individual functions of the cycle, and all other functions that were called directly by them. The "callers" of the cycle are the functions, outside the cycle, that called functions in the cycle.

Here is an example portion of a call graph which shows a cycle containing functions a and b. The cycle was entered by a call to a from main; both a and b called c.

index  % time    self  children called     name
----------------------------------------
                 1.77        0    1/1        main [2]
[3]     91.71    1.77        0    1+5    <cycle 1 as a whole> [3]
                 1.02        0    3          b <cycle 1> [4]
                 0.75        0    2          a <cycle 1> [5]
----------------------------------------
                                  3          a <cycle 1> [5]
[4]     52.85    1.02        0    0      b <cycle 1> [4]
                                  2          a <cycle 1> [5]
                    0        0    3/6        c [6]
----------------------------------------
                 1.77        0    1/1        main [2]
                                  2          b <cycle 1> [4]
[5]     38.86    0.75        0    1      a <cycle 1> [5]
                                  3          b <cycle 1> [4]
                    0        0    3/6        c [6]
----------------------------------------

(The entire call graph for this program contains in addition an entry for main, which calls a, and an entry for c, with callers a and b.)

index  % time    self  children called     name
                                             <spontaneous>
[1]    100.00       0     1.93    0      start [1]
                 0.16     1.77    1/1        main [2]
----------------------------------------
                 0.16     1.77    1/1        start [1]
[2]    100.00    0.16     1.77    1      main [2]
                 1.77        0    1/1        a <cycle 1> [5]
----------------------------------------
                 1.77        0    1/1        main [2]
[3]     91.71    1.77        0    1+5    <cycle 1 as a whole> [3]
                 1.02        0    3          b <cycle 1> [4]
                 0.75        0    2          a <cycle 1> [5]
                    0        0    6/6        c [6]
----------------------------------------
                                  3          a <cycle 1> [5]
[4]     52.85    1.02        0    0      b <cycle 1> [4]
                                  2          a <cycle 1> [5]
                    0        0    3/6        c [6]
----------------------------------------
                 1.77        0    1/1        main [2]
                                  2          b <cycle 1> [4]
[5]     38.86    0.75        0    1      a <cycle 1> [5]
                                  3          b <cycle 1> [4]
                    0        0    3/6        c [6]
----------------------------------------
                    0        0    3/6        b <cycle 1> [4]
                    0        0    3/6        a <cycle 1> [5]
[6]      0.00       0        0    6      c [6]
----------------------------------------

The self field of the cycle's primary line is the total time spent in all the functions of the cycle. It equals the sum of the self fields for the individual functions in the cycle, found in the entry in the subroutine lines for these functions.

The children fields of the cycle's primary line and subroutine lines count only subroutines outside the cycle. Even though a calls b, the time spent in those calls to b is not counted in a's children time. Thus, we do not encounter the problem of what to do when the time in those calls to b includes indirect recursive calls back to a.

The children field of a caller-line in the cycle's entry estimates the amount of time spent in the whole cycle, and its other subroutines, on the times when that caller called a function in the cycle.

The calls field in the primary line for the cycle has two numbers: first, the number of times functions in the cycle were called by functions outside the cycle; second, the number of times they were called by functions in the cycle (including times when a function in the cycle calls itself). This is a generalization of the usual split into nonrecursive and recursive calls.

The calls field of a subroutine-line for a cycle member in the cycle's entry says how many time that function was called from functions in the cycle. The total of all these is the second number in the primary line's calls field.

In the individual entry for a function in a cycle, the other functions in the same cycle can appear as subroutines and as callers. These lines show how many times each function in the cycle called or was called from each other function in the cycle. The self and children fields in these lines are blank because of the difficulty of defining meanings for them when recursion is going on.

Line-by-line Profiling

gprof's `-l' option causes the program to perform line-by-line profiling. In this mode, histogram samples are assigned not to functions, but to individual lines of source code. The program usually must be compiled with a `-g' option, in addition to `-pg', in order to generate debugging symbols for tracking source code lines.

The flat profile is the most useful output table in line-by-line mode. The call graph isn't as useful as normal, since the current version of gprof does not propagate call graph arcs from source code lines to the enclosing function. The call graph does, however, show each line of code that called each function, along with a count.

Here is a section of gprof's output, without line-by-line profiling. Note that ct_init accounted for four histogram hits, and 13327 calls to init_block.

Flat profile:

Each sample counts as 0.01 seconds.
  %   cumulative   self              self     total
 time   seconds   seconds    calls  us/call  us/call  name
 30.77      0.13     0.04     6335     6.31     6.31  ct_init

             Call graph (explanation follows)

granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds

index % time    self  children    called     name

                0.00    0.00       1/13496       name_too_long
                0.00    0.00      40/13496       deflate
                0.00    0.00     128/13496       deflate_fast
                0.00    0.00   13327/13496       ct_init
[7]      0.0    0.00    0.00   13496         init_block

Now let's look at some of gprof's output from the same program run, this time with line-by-line profiling enabled. Note that ct_init's four histogram hits are broken down into four lines of source code - one hit occured on each of lines 349, 351, 382 and 385. In the call graph, note how ct_init's 13327 calls to init_block are broken down into one call from line 396, 3071 calls from line 384, 3730 calls from line 385, and 6525 calls from 387.

Flat profile:

Each sample counts as 0.01 seconds.
  %   cumulative   self
 time   seconds   seconds    calls  name
  7.69      0.10     0.01           ct_init (trees.c:349)
  7.69      0.11     0.01           ct_init (trees.c:351)
  7.69      0.12     0.01           ct_init (trees.c:382)
  7.69      0.13     0.01           ct_init (trees.c:385)

             Call graph (explanation follows)

granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds

  % time    self  children    called     name

            0.00    0.00       1/13496       name_too_long (gzip.c:1440)
            0.00    0.00       1/13496       deflate (deflate.c:763)
            0.00    0.00       1/13496       ct_init (trees.c:396)
            0.00    0.00       2/13496       deflate (deflate.c:727)
            0.00    0.00       4/13496       deflate (deflate.c:686)
            0.00    0.00       5/13496       deflate (deflate.c:675)
            0.00    0.00      12/13496       deflate (deflate.c:679)
            0.00    0.00      16/13496       deflate (deflate.c:730)
            0.00    0.00     128/13496       deflate_fast (deflate.c:654)
            0.00    0.00    3071/13496       ct_init (trees.c:384)
            0.00    0.00    3730/13496       ct_init (trees.c:385)
            0.00    0.00    6525/13496       ct_init (trees.c:387)
[6]  0.0    0.00    0.00   13496         init_block (trees.c:408)

The Annotated Source Listing

gprof's `-A' option triggers an annotated source listing, which lists the program's source code, each function labeled with the number of times it was called. You may also need to specify the `-I' option, if gprof can't find the source code files.

Compiling with `gcc ... -g -pg -a' augments your program with basic-block counting code, in addition to function counting code. This enables gprof to determine how many times each line of code was exeucted. For example, consider the following function, taken from gzip, with line numbers added:

 1 ulg updcrc(s, n)
 2     uch *s;
 3     unsigned n;
 4 {
 5     register ulg c;
 6
 7     static ulg crc = (ulg)0xffffffffL;
 8
 9     if (s == NULL) {
10         c = 0xffffffffL;
11     } else {
12         c = crc;
13         if (n) do {
14             c = crc_32_tab[...];
15         } while (--n);
16     }
17     crc = c;
18     return c ^ 0xffffffffL;
19 }

updcrc has at least five basic-blocks. One is the function itself. The if statement on line 9 generates two more basic-blocks, one for each branch of the if. A fourth basic-block results from the if on line 13, and the contents of the do loop form the fifth basic-block. The compiler may also generate additional basic-blocks to handle various special cases.

A program augmented for basic-block counting can be analyzed with gprof -l -A. I also suggest use of the `-x' option, which ensures that each line of code is labeled at least once. Here is updcrc's annotated source listing for a sample gzip run:

                ulg updcrc(s, n)
                    uch *s;
                    unsigned n;
            2 ->{
                    register ulg c;

                    static ulg crc = (ulg)0xffffffffL;

            2 ->    if (s == NULL) {
            1 ->	c = 0xffffffffL;
            1 ->    } else {
            1 ->	c = crc;
            1 ->        if (n) do {
        26312 ->            c = crc_32_tab[...];
26312,1,26311 ->        } while (--n);
                    }
            2 ->    crc = c;
            2 ->    return c ^ 0xffffffffL;
            2 ->}

In this example, the function was called twice, passing once through each branch of the if statement. The body of the do loop was executed a total of 26312 times. Note how the while statement is annotated. It began execution 26312 times, once for each iteration through the loop. One of those times (the last time) it exited, while it branched back to the beginning of the loop 26311 times.

Inaccuracy of gprof Output

Statistical Sampling Error

The run-time figures that gprof gives you are based on a sampling process, so they are subject to statistical inaccuracy. If a function runs only a small amount of time, so that on the average the sampling process ought to catch that function in the act only once, there is a pretty good chance it will actually find that function zero times, or twice.

By contrast, the number-of-calls and basic-block figures are derived by counting, not sampling. They are completely accurate and will not vary from run to run if your program is deterministic.

The sampling period that is printed at the beginning of the flat profile says how often samples are taken. The rule of thumb is that a run-time figure is accurate if it is considerably bigger than the sampling period.

The actual amount of error can be predicted. For n samples, the expected error is the square-root of n. For example, if the sampling period is 0.01 seconds and foo's run-time is 1 second, n is 100 samples (1 second/0.01 seconds), sqrt(n) is 10 samples, so the expected error in foo's run-time is 0.1 seconds (10*0.01 seconds), or ten percent of the observed value. Again, if the sampling period is 0.01 seconds and bar's run-time is 100 seconds, n is 10000 samples, sqrt(n) is 100 samples, so the expected error in bar's run-time is 1 second, or one percent of the observed value. It is likely to vary this much on the average from one profiling run to the next. (Sometimes it will vary more.)

This does not mean that a small run-time figure is devoid of information. If the program's total run-time is large, a small run-time for one function does tell you that that function used an insignificant fraction of the whole program's time. Usually this means it is not worth optimizing.

One way to get more accuracy is to give your program more (but similar) input data so it will take longer. Another way is to combine the data from several runs, using the `-s' option of gprof. Here is how:

  1. Run your program once.
  2. Issue the command `mv gmon.out gmon.sum'.
  3. Run your program again, the same as before.
  4. Merge the new data in `gmon.out' into `gmon.sum' with this command:
    gprof -s executable-file gmon.out gmon.sum
  5. Repeat the last two steps as often as you wish.
  6. Analyze the cumulative data using this command:
    gprof executable-file gmon.sum > output-file

Estimating children Times

Some of the figures in the call graph are estimates--for example, the children time values and all the the time figures in caller and subroutine lines.

There is no direct information about these measurements in the profile data itself. Instead, gprof estimates them by making an assumption about your program that might or might not be true.

The assumption made is that the average time spent in each call to any function foo is not correlated with who called foo. If foo used 5 seconds in all, and 2/5 of the calls to foo came from a, then foo contributes 2 seconds to a's children time, by assumption.

This assumption is usually true enough, but for some programs it is far from true. Suppose that foo returns very quickly when its argument is zero; suppose that a always passes zero as an argument, while other callers of foo pass other arguments. In this program, all the time spent in foo is in the calls from callers other than a. But gprof has no way of knowing this; it will blindly and incorrectly charge 2 seconds of time in foo to the children of a.

We hope some day to put more complete data into `gmon.out', so that this assumption is no longer needed, if we can figure out how. For the nonce, the estimated figures are usually more useful than misleading.

Answers to Common Questions

How do I find which lines in my program were executed the most times?
Compile your program with basic-block counting enabled, run it, then use the following pipeline:
gprof -l -C objfile | sort -k 3 -n -r
This listing will show you the lines in your code executed most often, but not necessarily those that consumed the most time.
How do I find which lines in my program called a particular function?
Use gprof -l and lookup the function in the call graph. The callers will be broken down by function and line number.
How do I analyze a program that runs for less than a second?
Try using a shell script like this one:
for i in `seq 1 100`; do
  fastprog
  mv gmon.out gmon.out.$i
done

gprof -s fastprog gmon.out.*

gprof fastprog gmon.sum
If your program is completely deterministic, all the call counts will be simple multiples of 100 (i.e. a function called once in each run will appear with a call count of 100).

Incompatibilities with Unix gprof

GNU gprof and Berkeley Unix gprof use the same data file `gmon.out', and provide essentially the same information. But there are a few differences.

  • GNU gprof uses a new, generalized file format with support for basic-block execution counts and non-realtime histograms. A magic cookie and version number allows gprof to easily identify new style files. Old BSD-style files can still be read. See section Profiling Data File Format.
  • For a recursive function, Unix gprof lists the function as a parent and as a child, with a calls field that lists the number of recursive calls. GNU gprof omits these lines and puts the number of recursive calls in the primary line.
  • When a function is suppressed from the call graph with `-e', GNU gprof still lists it as a subroutine of functions that call it.
  • GNU gprof accepts the `-k' with its argument in the form `from/to', instead of `from to'.
  • In the annotated source listing, if there are multiple basic blocks on the same line, GNU gprof prints all of their counts, seperated by commas.
  • The blurbs, field widths, and output formats are different. GNU gprof prints blurbs after the tables, so that you can see the tables without skipping the blurbs.

Details of Profiling

Implementation of Profiling

Profiling works by changing how every function in your program is compiled so that when it is called, it will stash away some information about where it was called from. From this, the profiler can figure out what function called it, and can count how many times it was called. This change is made by the compiler when your program is compiled with the `-pg' option, which causes every function to call mcount (or _mcount, or __mcount, depending on the OS and compiler) as one of its first operations.

The mcount routine, included in the profiling library, is responsible for recording in an in-memory call graph table both its parent routine (the child) and its parent's parent. This is typically done by examining the stack frame to find both the address of the child, and the return address in the original parent. Since this is a very machine-dependant operation, mcount itself is typically a short assembly-language stub routine that extracts the required information, and then calls __mcount_internal (a normal C function) with two arguments - frompc and selfpc. __mcount_internal is responsible for maintaining the in-memory call graph, which records frompc, selfpc, and the number of times each of these call arcs was transversed.

GCC Version 2 provides a magical function (__builtin_return_address), which allows a generic mcount function to extract the required information from the stack frame. However, on some architectures, most notably the SPARC, using this builtin can be very computationally expensive, and an assembly language version of mcount is used for performance reasons.

Number-of-calls information for library routines is collected by using a special version of the C library. The programs in it are the same as in the usual C library, but they were compiled with `-pg'. If you link your program with `gcc ... -pg', it automatically uses the profiling version of the library.

Profiling also involves watching your program as it runs, and keeping a histogram of where the program counter happens to be every now and then. Typically the program counter is looked at around 100 times per second of run time, but the exact frequency may vary from system to system.

This is done is one of two ways. Most UNIX-like operating systems provide a profil() system call, which registers a memory array with the kernel, along with a scale factor that determines how the program's address space maps into the array. Typical scaling values cause every 2 to 8 bytes of address space to map into a single array slot. On every tick of the system clock (assuming the profiled program is running), the value of the program counter is examined and the corresponding slot in the memory array is incremented. Since this is done in the kernel, which had to interrupt the process anyway to handle the clock interrupt, very little additional system overhead is required.

However, some operating systems, most notably Linux 2.0 (and earlier), do not provide a profil() system call. On such a system, arrangements are made for the kernel to periodically deliver a signal to the process (typically via setitimer()), which then performs the same operation of examining the program counter and incrementing a slot in the memory array. Since this method requires a signal to be delivered to user space every time a sample is taken, it uses considerably more overhead than kernel-based profiling. Also, due to the added delay required to deliver the signal, this method is less accurate as well.

A special startup routine allocates memory for the histogram and either calls profil() or sets up a clock signal handler. This routine (monstartup) can be invoked in several ways. On Linux systems, a special profiling startup file gcrt0.o, which invokes monstartup before main, is used instead of the default crt0.o. Use of this special startup file is one of the effects of using `gcc ... -pg' to link. On SPARC systems, no special startup files are used. Rather, the mcount routine, when it is invoked for the first time (typically when main is called), calls monstartup.

If the compiler's `-a' option was used, basic-block counting is also enabled. Each object file is then compiled with a static array of counts, initially zero. In the executable code, every time a new basic-block begins (i.e. when an if statement appears), an extra instruction is inserted to increment the corresponding count in the array. At compile time, a paired array was constructed that recorded the starting address of each basic-block. Taken together, the two arrays record the starting address of every basic-block, along with the number of times it was executed.

The profiling library also includes a function (mcleanup) which is typically registered using atexit() to be called as the program exits, and is responsible for writing the file `gmon.out'. Profiling is turned off, various headers are output, and the histogram is written, followed by the call-graph arcs and the basic-block counts.

The output from gprof gives no indication of parts of your program that are limited by I/O or swapping bandwidth. This is because samples of the program counter are taken at fixed intervals of the program's run time. Therefore, the time measurements in gprof output say nothing about time that your program was not running. For example, a part of the program that creates so much data that it cannot all fit in physical memory at once may run very slowly due to thrashing, but gprof will say it uses little time. On the other hand, sampling by run time has the advantage that the amount of load due to other users won't directly affect the output you get.

Profiling Data File Format

The old BSD-derived file format used for profile data does not contain a magic cookie that allows to check whether a data file really is a gprof file. Furthermore, it does not provide a version number, thus rendering changes to the file format almost impossible. GNU gprof uses a new file format that provides these features. For backward compatibility, GNU gprof continues to support the old BSD-derived format, but not all features are supported with it. For example, basic-block execution counts cannot be accommodated by the old file format.

The new file format is defined in header file `gmon_out.h'. It consists of a header containing the magic cookie and a version number, as well as some spare bytes available for future extensions. All data in a profile data file is in the native format of the host on which the profile was collected. GNU gprof adapts automatically to the byte-order in use.

In the new file format, the header is followed by a sequence of records. Currently, there are three different record types: histogram records, call-graph arc records, and basic-block execution count records. Each file can contain any number of each record type. When reading a file, GNU gprof will ensure records of the same type are compatible with each other and compute the union of all records. For example, for basic-block execution counts, the union is simply the sum of all execution counts for each basic-block.

Histogram Records

Histogram records consist of a header that is followed by an array of bins. The header contains the text-segment range that the histogram spans, the size of the histogram in bytes (unlike in the old BSD format, this does not include the size of the header), the rate of the profiling clock, and the physical dimension that the bin counts represent after being scaled by the profiling clock rate. The physical dimension is specified in two parts: a long name of up to 15 characters and a single character abbreviation. For example, a histogram representing real-time would specify the long name as "seconds" and the abbreviation as "s". This feature is useful for architectures that support performance monitor hardware (which, fortunately, is becoming increasingly common). For example, under DEC OSF/1, the "uprofile" command can be used to produce a histogram of, say, instruction cache misses. In this case, the dimension in the histogram header could be set to "i-cache misses" and the abbreviation could be set to "1" (because it is simply a count, not a physical dimension). Also, the profiling rate would have to be set to 1 in this case.

Histogram bins are 16-bit numbers and each bin represent an equal amount of text-space. For example, if the text-segment is one thousand bytes long and if there are ten bins in the histogram, each bin represents one hundred bytes.

Call-Graph Records

Call-graph records have a format that is identical to the one used in the BSD-derived file format. It consists of an arc in the call graph and a count indicating the number of times the arc was traversed during program execution. Arcs are specified by a pair of addresses: the first must be within caller's function and the second must be within the callee's function. When performing profiling at the function level, these addresses can point anywhere within the respective function. However, when profiling at the line-level, it is better if the addresses are as close to the call-site/entry-point as possible. This will ensure that the line-level call-graph is able to identify exactly which line of source code performed calls to a function.

Basic-Block Execution Count Records

Basic-block execution count records consist of a header followed by a sequence of address/count pairs. The header simply specifies the length of the sequence. In an address/count pair, the address identifies a basic-block and the count specifies the number of times that basic-block was executed. Any address within the basic-address can be used.

gprof's Internal Operation

Like most programs, gprof begins by processing its options. During this stage, it may building its symspec list (sym_ids.c:sym_id_add), if options are specified which use symspecs. gprof maintains a single linked list of symspecs, which will eventually get turned into 12 symbol tables, organized into six include/exclude pairs - one pair each for the flat profile (INCL_FLAT/EXCL_FLAT), the call graph arcs (INCL_ARCS/EXCL_ARCS), printing in the call graph (INCL_GRAPH/EXCL_GRAPH), timing propagation in the call graph (INCL_TIME/EXCL_TIME), the annotated source listing (INCL_ANNO/EXCL_ANNO), and the execution count listing (INCL_EXEC/EXCL_EXEC).

After option processing, gprof finishes building the symspec list by adding all the symspecs in default_excluded_list to the exclude lists EXCL_TIME and EXCL_GRAPH, and if line-by-line profiling is specified, EXCL_FLAT as well. These default excludes are not added to EXCL_ANNO, EXCL_ARCS, and EXCL_EXEC.

Next, the BFD library is called to open the object file, verify that it is an object file, and read its symbol table (core.c:core_init), using bfd_canonicalize_symtab after mallocing an appropiate sized array of asymbols. At this point, function mappings are read (if the `--file-ordering' option has been specified), and the core text space is read into memory (if the `-c' option was given).

gprof's own symbol table, an array of Sym structures, is now built. This is done in one of two ways, by one of two routines, depending on whether line-by-line profiling (`-l' option) has been enabled. For normal profiling, the BFD canonical symbol table is scanned. For line-by-line profiling, every text space address is examined, and a new symbol table entry gets created every time the line number changes. In either case, two passes are made through the symbol table - one to count the size of the symbol table required, and the other to actually read the symbols. In between the two passes, a single array of type Sym is created of the appropiate length. Finally, symtab.c:symtab_finalize is called to sort the symbol table and remove duplicate entries (entries with the same memory address).

The symbol table must be a contiguous array for two reasons. First, the qsort library function (which sorts an array) will be used to sort the symbol table. Also, the symbol lookup routine (symtab.c:sym_lookup), which finds symbols based on memory address, uses a binary search algorithm which requires the symbol table to be a sorted array. Function symbols are indicated with an is_func flag. Line number symbols have no special flags set. Additionally, a symbol can have an is_static flag to indicate that it is a local symbol.

With the symbol table read, the symspecs can now be translated into Syms (sym_ids.c:sym_id_parse). Remember that a single symspec can match multiple symbols. An array of symbol tables (syms) is created, each entry of which is a symbol table of Syms to be included or excluded from a particular listing. The master symbol table and the symspecs are examined by nested loops, and every symbol that matches a symspec is inserted into the appropriate syms table. This is done twice, once to count the size of each required symbol table, and again to build the tables, which have been malloced between passes. From now on, to determine whether a symbol is on an include or exclude symspec list, gprof simply uses its standard symbol lookup routine on the appropriate table in the syms array.

Now the profile data file(s) themselves are read (gmon_io.c:gmon_out_read), first by checking for a new-style `gmon.out' header, then assuming this is an old-style BSD `gmon.out' if the magic number test failed.

New-style histogram records are read by hist.c:hist_read_rec. For the first histogram record, allocate a memory array to hold all the bins, and read them in. When multiple profile data files (or files with multiple histogram records) are read, the starting address, ending address, number of bins and sampling rate must match between the various histograms, or a fatal error will result. If everything matches, just sum the additional histograms into the existing in-memory array.

As each call graph record is read (call_graph.c:cg_read_rec), the parent and child addresses are matched to symbol table entries, and a call graph arc is created by cg_arcs.c:arc_add, unless the arc fails a symspec check against INCL_ARCS/EXCL_ARCS. As each arc is added, a linked list is maintained of the parent's child arcs, and of the child's parent arcs. Both the child's call count and the arc's call count are incremented by the record's call count.

Basic-block records are read (basic_blocks.c:bb_read_rec), but only if line-by-line profiling has been selected. Each basic-block address is matched to a corresponding line symbol in the symbol table, and an entry made in the symbol's bb_addr and bb_calls arrays. Again, if multiple basic-block records are present for the same address, the call counts are cumulative.

A gmon.sum file is dumped, if requested (gmon_io.c:gmon_out_write).

If histograms were present in the data files, assign them to symbols (hist.c:hist_assign_samples) by iterating over all the sample bins and assigning them to symbols. Since the symbol table is sorted in order of ascending memory addresses, we can simple follow along in the symbol table as we make our pass over the sample bins. This step includes a symspec check against INCL_FLAT/EXCL_FLAT. Depending on the histogram scale factor, a sample bin may span multiple symbols, in which case a fraction of the sample count is allocated to each symbol, proportional to the degree of overlap. This effect is rare for normal profiling, but overlaps are more common during line-by-line profiling, and can cause each of two adjacent lines to be credited with half a hit, for example.

If call graph data is present, cg_arcs.c:cg_assemble is called. First, if `-c' was specified, a machine-dependant routine (find_call) scans through each symbol's machine code, looking for subroutine call instructions, and adding them to the call graph with a zero call count. A topological sort is performed by depth-first numbering all the symbols (cg_dfn.c:cg_dfn), so that children are always numbered less than their parents, then making a array of pointers into the symbol table and sorting it into numerical order, which is reverse topological order (children appear before parents). Cycles are also detected at this point, all members of which are assigned the same topological number. Two passes are now made through this sorted array of symbol pointers. The first pass, from end to beginning (parents to children), computes the fraction of child time to propogate to each parent and a print flag. The print flag reflects symspec handling of INCL_GRAPH/EXCL_GRAPH, with a parent's include or exclude (print or no print) property being propagated to its children, unless they themselves explicitly appear in INCL_GRAPH or EXCL_GRAPH. A second pass, from beginning to end (children to parents) actually propogates the timings along the call graph, subject to a check against INCL_TIME/EXCL_TIME. With the print flag, fractions, and timings now stored in the symbol structures, the topological sort array is now discarded, and a new array of pointers is assembled, this time sorted by propagated time.

Finally, print the various outputs the user requested, which is now fairly straightforward. The call graph (cg_print.c:cg_print) and flat profile (hist.c:hist_print) are regurgitations of values already computed. The annotated source listing (basic_blocks.c:print_annotated_source) uses basic-block information, if present, to label each line of code with call counts, otherwise only the function call counts are presented.

The function ordering code is marginally well documented in the source code itself (cg_print.c). Basically, the functions with the most use and the most parents are placed first, followed by other functions with the most use, followed by lower use functions, followed by unused functions at the end.

Debugging gprof

If gprof was compiled with debugging enabled, the `-d' option triggers debugging output (to stdout) which can be helpful in understanding its operation. The debugging number specified is interpreted as a sum of the following options:

2 - Topological sort
Monitor depth-first numbering of symbols during call graph analysis
4 - Cycles
Shows symbols as they are identified as cycle heads
16 - Tallying
As the call graph arcs are read, show each arc and how the total calls to each function are tallied
32 - Call graph arc sorting
Details sorting individual parents/children within each call graph entry
64 - Reading histogram and call graph records
Shows address ranges of histograms as they are read, and each call graph arc
128 - Symbol table
Reading, classifying, and sorting the symbol table from the object file. For line-by-line profiling (`-l' option), also shows line numbers being assigned to memory addresses.
256 - Static call graph
Trace operation of `-c' option
512 - Symbol table and arc table lookups
Detail operation of lookup routines
1024 - Call graph propagation
Shows how function times are propagated along the call graph
2048 - Basic-blocks
Shows basic-block records as they are read from profile data (only meaningful with `-l' option)
4096 - Symspecs
Shows symspec-to-symbol pattern matching operation
8192 - Annotate source
Tracks operation of `-A' option

This document was generated on 7 November 1998 using the texi2html translator version 1.52.


grep, print lines matching a pattern

grep, searching for a pattern

version 2.4, 13 November 1999

Alain Magloire et al.

Table of Contents

  • Introduction
  • Invoking @command{grep}
    • GNU Extensions
    • Environment Variables
  • Diagnostics
  • @command{grep} programs
  • Regular Expressions
  • Usage
  • Reporting bugs
  • Concept Index
  • Index

Introduction

@command{grep} searches the input files for lines containing a match to a given pattern list. When it finds a match in a line, it copies the line to standard output (by default), or does whatever other sort of output you have requested with options. @command{grep} expects to do the matching on text. Since newline is also a separator for the list of patterns, there is no way to match newline characters in a text.

Invoking @command{grep}

@command{grep} comes with a rich set of options from POSIX.2 and GNU extensions.

`-c'
`--count'
Suppress normal output; instead print a count of matching lines for each input file. With the `-v', `--invert-match' option, count non-matching lines.
`-e pattern'
`--regexp=pattern'
Use pattern as the pattern; useful to protect patterns beginning with a `-'.
`-f file'
`--file=file'
Obtain patterns from file, one per line. The empty file contains zero patterns, and therefore matches nothing.
`-i'
`--ignore-case'
Ignore case distinctions in both the pattern and the input files.
`-l'
`--files-with-matches'
Suppress normal output; instead print the name of each input file from which output would normally have been printed. The scanning of every file will stop on the first match.
`-n'
`--line-number'
Prefix each line of output with the line number within its input file.
`-q'
`--quiet'
`--silent'
Quiet; suppress normal output. The scanning of every file will stop on the first match. Also see the `-s' or `--no-messages' option.
`-s'
`--no-messages'
Suppress error messages about nonexistent or unreadable files. Portability note: unlike GNU @command{grep}, traditional @command{grep} did not conform to POSIX.2, because traditional @command{grep} lacked a `-q' option and its `-s' option behaved like GNU @command{grep}'s `-q' option. Shell scripts intended to be portable to traditional @command{grep} should avoid both `-q' and `-s' and should redirect output to `/dev/null' instead.
`-v'
`--invert-match'
Invert the sense of matching, to select non-matching lines.
`-x'
`--line-regexp'
Select only those matches that exactly match the whole line.

GNU Extensions

`-A num'
`--after-context=num'
Print num lines of trailing context after matching lines.
`-B num'
`--before-context=num'
Print num lines of leading context before matching lines.
`-C num'
`--context=[num]'
Print num lines (default 2) of output context.
`-num'
Same as `--context=num' lines of leading and trailing context. However, grep will never print any given line more than once.
`-V'
`--version'
Print the version number of @command{grep} to the standard output stream. This version number should be included in all bug reports.
`--help'
Print a usage message briefly summarizing these command-line options and the bug-reporting address, then exit.
`-b'
`--byte-offset'
Print the byte offset within the input file before each line of output. When @command{grep} runs on MS-DOS or MS-Windows, the printed byte offsets depend on whether the `-u' (`--unix-byte-offsets') option is used; see below.
`-d action'
`--directories=action'
If an input file is a directory, use action to process it. By default, action is `read', which means that directories are read just as if they were ordinary files (some operating systems and filesystems disallow this, and will cause @command{grep} to print error messages for every directory). If action is `skip', directories are silently skipped. If action is `recurse', @command{grep} reads all files under each directory, recursively; this is equivalent to the `-r' option.
`-H'
`--with-filename'
Print the filename for each match.
`-h'
`--no-filename'
Suppress the prefixing of filenames on output when multiple files are searched.
`-L'
`--files-without-match'
Suppress normal output; instead print the name of each input file from which no output would normally have been printed. The scanning of every file will stop on the first match.
`-a'
`--text'
Do not suppress output lines that contain binary data. Normally, if the first few bytes of a file indicate that the file contains binary data, grep outputs only a message saying that the file matches the pattern. This option causes grep to act as if the file is a text file, even if it would otherwise be treated as binary. Warning: the result might be binary garbage printed to the terminal, which can have nasty side-effects if the terminal driver interprets some of it as commands.
`-w'
`--word-regexp'
Select only those lines containing matches that form whole words. The test is that the matching substring must either be at the beginning of the line, or preceded by a non-word constituent character. Similarly, it must be either at the end of the line or followed by a non-word constituent character. Word-constituent characters are letters, digits, and the underscore.
`-r'
`--recursive'
For each directory mentioned in the command line, read and process all files in that directory, recursively. This is the same as the `-d recurse' option.
`-y'
Obsolete synonym for `-i'.
`-U'
`--binary'
Treat the file(s) as binary. By default, under MS-DOS and MS-Windows, @command{grep} guesses the file type by looking at the contents of the first 32kB read from the file. If @command{grep} decides the file is a text file, it strips the CR characters from the original file contents (to make regular expressions with ^ and $ work correctly). Specifying `-U' overrules this guesswork, causing all files to be read and passed to the matching mechanism verbatim; if the file is a text file with CR/LF pairs at the end of each line, this will cause some regular expressions to fail. This option has no effect on platforms other than MS-DOS and MS-Windows.
`-u'
`--unix-byte-offsets'
Report Unix-style byte offsets. This switch causes @command{grep} to report byte offsets as if the file were Unix style text file, i.e., the byte offsets ignore the CR characters which were stripped. This will produce results identical to running @command{grep} on a Unix machine. This option has no effect unless `-b' option is also used; it has no effect on platforms other than MS-DOS and MS-Windows.
`--mmap'
If possible, use the mmap system call to read input, instead of the default read system call. In some situations, `--mmap' yields better performance. However, `--mmap' can cause undefined behavior (including core dumps) if an input file shrinks while @command{grep} is operating, or if an I/O error occurs.
`-Z'
`--null'
Output a zero byte (the ASCII NUL character) instead of the character that normally follows a file name. For example, `grep -lZ' outputs a zero byte after each file name instead of the usual newline. This option makes the output unambiguous, even in the presence of file names containing unusual characters like newlines. This option can be used with commands like `find -print0', `perl -0', `sort -z', and `xargs -0' to process arbitrary file names, even those that contain newline characters.
`-z'
`--null-data'
Treat the input as a set of lines, each terminated by a zero byte (the ASCII NUL character) instead of a newline. Like the `-Z' or `--null' option, this option can be used with commands like `sort -z' to process arbitrary file names.

Several additional options control which variant of the @command{grep} matching engine is used. See section @command{grep} programs.

Environment Variables

Grep's behavior is affected by the following environment variables.

GREP_OPTIONS
This variable specifies default options to be placed in front of any explicit options. For example, if GREP_OPTIONS is `--text --directories=skip', @command{grep} behaves as if the two options `--text' and `--directories=skip' had been specified before any explicit options. Option specifications are separated by whitespace. A backslash escapes the next character, so it can be used to specify an option containing whitespace or a backslash.
LC_ALL
LC_MESSAGES
LANG
These variables specify the LC_MESSAGES locale, which determines the language that @command{grep} uses for messages. The locale is determined by the first of these variables that is set. American English is used if none of these environment variables are set, or if the message catalog is not installed, or if @command{grep} was not compiled with national language support (NLS).
LC_ALL
LC_CTYPE
LANG
These variables specify the LC_CTYPE locale, which determines the type of characters, e.g., which characters are whitespace. The locale is determined by the first of these variables that is set. The POSIX locale is used if none of these environment variables are set, or if the locale catalog is not installed, or if @command{grep} was not compiled with national language support (NLS).
POSIXLY_CORRECT
If set, @command{grep} behaves as POSIX.2 requires; otherwise, @command{grep} behaves more like other GNU programs. POSIX.2 requires that options that follow file names must be treated as file names; by default, such options are permuted to the front of the operand list and are treated as options. Also, POSIX.2 requires that unrecognized options be diagnosed as "illegal", but since they are not really against the law the default is to diagnose them as "invalid". POSIXLY_CORRECT also disables _N_GNU_nonoption_argv_flags_, described below.
_N_GNU_nonoption_argv_flags_
(Here N is @command{grep}'s numeric process ID.) If the ith character of this environment variable's value is `1', do not consider the ith operand of @command{grep} to be an option, even if it appears to be one. A shell can put this variable in the environment for each command it runs, specifying which operands are the results of file name wildcard expansion and therefore should not be treated as options. This behavior is available only with the GNU C library, and only when POSIXLY_CORRECT is not set.

Diagnostics

Normally, exit status is 0 if matches were found, and 1 if no matches were found (the `-v' option inverts the sense of the exit status). Exit status is 2 if there were syntax errors in the pattern, inaccessible input files, or other system errors.

@command{grep} programs

@command{grep} searches the named input files (or standard input if no files are named, or the file name `-' is given) for lines containing a match to the given pattern. By default, @command{grep} prints the matching lines. There are three major variants of @command{grep}, controlled by the following options.

`-G'
`--basic-regexp'
Interpret pattern as a basic regular expression. This is the default.
`-E'
`--extended-regexp'
Interpret pattern as an extended regular expression.
`-F'
`--fixed-strings'
Interpret pattern as a list of fixed strings, separated by newlines, any of which is to be matched.

In addition, two variant programs EGREP and FGREP are available. EGREP is the same as `grep -E'. FGREP is the same as `grep -F'.

Regular Expressions

A regular expression is a pattern that describes a set of strings. Regular expressions are constructed analogously to arithmetic expressions, by using various operators to combine smaller expressions. @command{grep} understands two different versions of regular expression syntax: "basic" and "extended". In GNU @command{grep}, there is no difference in available functionality using either syntax. In other implementations, basic regular expressions are less powerful. The following description applies to extended regular expressions; differences for basic regular expressions are summarized afterwards.

The fundamental building blocks are the regular expressions that match a single character. Most characters, including all letters and digits, are regular expressions that match themselves. Any metacharacter with special meaning may be quoted by preceding it with a backslash. A list of characters enclosed by `[' and `]' matches any single character in that list; if the first character of the list is the caret `^', then it matches any character not in the list. For example, the regular expression `[0123456789]' matches any single digit. A range of ASCII characters may be specified by giving the first and last characters, separated by a hyphen.

Finally, certain named classes of characters are predefined, as follows. Their interpretation depends on the LC_CTYPE locale; the interpretation below is that of the POSIX locale, which is the default if no LC_CTYPE locale is specified.

`[:alnum:]'
Any of `[:digit:]' or `[:alpha:]'
`[:alpha:]'
Any letter:
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 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.
`[:blank:]'
Space or tab.
`[:cntrl:]'
Any character with octal codes 000 through 037, or DEL (octal code 177).
`[:digit:]'
Any one of 0 1 2 3 4 5 6 7 8 9.
`[:graph:]'
Anything that is not a `[:alnum:]' or `[:punct:]'.
`[:lower:]'
Any one of 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.
`[:print:]'
Any character from the `[:space:]' class, and any character that is not in the `[:graph:]' class.
`[:punct:]'
Any one of ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~.
`[:space:]'
Any one of CR FF HT NL VT SPACE.
`[:upper:]'
Any one of 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.
`[:xdigit:]'
Any one of a b c d e f A B C D E F 0 1 2 3 4 5 6 7 8 9.

For example, `[[:alnum:]]' means `[0-9A-Za-z]', except the latter form is dependent upon the ASCII character encoding, whereas the former is portable. (Note that the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets delimiting the bracket list.) Most metacharacters lose their special meaning inside lists. To include a literal `]', place it first in the list. Similarly, to include a literal `^', place it anywhere but first. Finally, to include a literal `-', place it last.

The period `.' matches any single character. The symbol `\w' is a synonym for `[[:alnum:]]' and `\W' is a synonym for `[^[:alnum]]'.

The caret `^' and the dollar sign `$' are metacharacters that respectively match the empty string at the beginning and end of a line. The symbols `\<' and `\>' respectively match the empty string at the beginning and end of a word. The symbol `\b' matches the empty string at the edge of a word, and `\B' matches the empty string provided it's not at the edge of a word.

A regular expression may be followed by one of several repetition operators:

`?'
The preceding item is optional and will be matched at most once.
`*'
The preceding item will be matched zero or more times.
`+'
The preceding item will be matched one or more times.
`{n}'
The preceding item is matched exactly n times.
`{n,}'
The preceding item is matched n or more times.
`{n,m}'
The preceding item is matched at least n times, but not more than m times.

Two regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating two substrings that respectively match the concatenated subexpressions.

Two regular expressions may be joined by the infix operator `|'; the resulting regular expression matches any string matching either subexpression.

Repetition takes precedence over concatenation, which in turn takes precedence over alternation. A whole subexpression may be enclosed in parentheses to override these precedence rules.

The backreference `\n', where n is a single digit, matches the substring previously matched by the nth parenthesized subexpression of the regular expression.

In basic regular expressions the metacharacters `?', `+', `{', `|', `(', and `)' lose their special meaning; instead use the backslashed versions `\?', `\+', `\{', `\|', `\(', and `\)'.

Traditional @command{egrep} did not support the `{' metacharacter, and some @command{egrep} implementations support `\{' instead, so portable scripts should avoid `{' in `egrep' patterns and should use `[{]' to match a literal `{'.

GNU @command{egrep} attempts to support traditional usage by assuming that `{' is not special if it would be the start of an invalid interval specification. For example, the shell command `egrep '{1'' searches for the two-character string `{1' instead of reporting a syntax error in the regular expression. POSIX.2 allows this behavior as an extension, but portable scripts should avoid it.

Usage

Here is an example shell command that invokes GNU @command{grep}:

grep -i 'hello.*world' menu.h main.c

This lists all lines in the files `menu.h' and `main.c' that contain the string `hello' followed by the string `world'; this is because `.*' matches zero or more characters within a line. See section Regular Expressions. The `-i' option causes @command{grep} to ignore case, causing it to match the line `Hello, world!', which it would not otherwise match. See section Invoking @command{grep}, for more details about how to invoke @command{grep}.

Here are some common questions and answers about @command{grep} usage.

  1. How can I list just the names of matching files?
    grep -l 'main' *.c
    lists the names of all C files in the current directory whose contents mention `main'.
  2. How do I search directories recursively?
    grep -r 'hello' /home/gigi
    searches for `hello' in all files under the directory `/home/gigi'. For more control of which files are searched, use @command{find}, @command{grep} and @command{xargs}. For example, the following command searches only C files:
    find /home/gigi -name '*.c' -print | xargs grep 'hello' /dev/null
  3. What if a pattern has a leading `-'?
    grep -e '--cut here--' *
    searches for all lines matching `--cut here--'. Without `-e', @command{grep} would attempt to parse `--cut here--' as a list of options.
  4. Suppose I want to search for a whole word, not a part of a word?
    grep -w 'hello' *
    searches only for instances of `hello' that are entire words; it does not match `Othello'. For more control, use `\<' and `\>' to match the start and end of words. For example:
    grep 'hello\>' *
    searches only for words ending in `hello', so it matches the word `Othello'.
  5. How do I output context around the matching lines?
    grep -C 2 'hello' *
    prints two lines of context around each matching line.
  6. How do I force grep to print the name of the file? Append `/dev/null':
    grep 'eli' /etc/passwd /dev/null
  7. Why do people use strange regular expressions on @command{ps} output?
    ps -ef | grep '[c]ron'
    If the pattern had been written without the square brackets, it would have matched not only the @command{ps} output line for @command{cron}, but also the @command{ps} output line for @command{grep}.
  8. Why does @command{grep} report "Binary file matches"? If @command{grep} listed all matching "lines" from a binary file, it would probably generate output that is not useful, and it might even muck up your display. So GNU @command{grep} suppresses output from files that appear to be binary files. To force GNU @command{grep} to output lines even from files that appear to be binary, use the `-a' or `--text' option.
  9. Why doesn't `grep -lv' print nonmatching file names? `grep -lv' lists the names of all files containing one or more lines that do not match. To list the names of all files that contain no matching lines, use the `-L' or `--files-without-match' option.
  10. I can do OR with `|', but what about AND?
    grep 'paul' /etc/motd | grep 'franc,ois'
    finds all lines that contain both `paul' and `franc,ois'.
  11. How can I search in both standard input and in files? Use the special file name `-':
    cat /etc/passwd | grep 'alain' - /etc/motd

Reporting bugs

Email bug reports to bug-gnu-utils@gnu.org. Be sure to include the word "grep" somewhere in the "Subject:" field.

Large repetition counts in the `{m,n}' construct may cause @command{grep} to use lots of memory. In addition, certain other obscure regular expressions require exponential time and space, and may cause grep to run out of memory. Backreferences are very slow, and may require exponential time.

Concept Index

This is a general index of all issues discussed in this manual, with the exception of the @command{grep} commands and command-line options.

a

  • after context
  • alphabetic characters
  • alphanumeric characters
  • asterisk

    • b

  • basic regular expressions
  • before context
  • binary files
  • binary files, DOS/Windows
  • blank characters
  • braces, one argument
  • braces, second argument omitted
  • braces, two arguments
  • Bugs, reporting
  • byte offset
  • byte offsets, on DOS/Windows

    • c

  • case insensitive search
  • case insensitive search, obsolete option
  • character classes
  • character type
  • classes of characters
  • context
  • context lines, after match
  • context lines, before match
  • control characters
  • counting lines

    • d

  • default options environment variable
  • digit characters
  • directory search
  • DOS byte offsets
  • DOS/Windows binary files

    • e

  • environment variables

    • f

  • FAQ about @command{grep} usage
  • files which don't match

    • g

  • graphic characters

    • h

  • hexadecimal digits

    • i

  • interval specifications
  • invert matching

    • l

  • language of messages
  • line numbering
  • lower-case alphabetic characters

    • m

  • match sub-expression at most once
  • match sub-expression n or more times
  • match sub-expression n times
  • match sub-expression zero or more times
  • match the whole line
  • matching basic regular expressions
  • matching extended regular expressions
  • matching fixed strings
  • matching whole words
  • memory mapped input
  • message language

    • n

  • names of matching files
  • national language support, national language support
  • NLS, NLS
  • no filename prefix
  • numeric characters

    • p

  • pattern from file
  • pattern list
  • plus sign
  • print non-matching lines
  • printable characters
  • punctuation characters

    • q

  • question mark
  • quiet, silent

    • r

  • recursive search
  • regular expressions

    • s

  • searching directory trees
  • Searching for a pattern.
  • space characters
  • suppress binary data
  • suppress error messages

    • t

  • translation of message language

    • u

  • upper-case alphabetic characters
  • Usage summary, printing
  • Usage, examples
  • Using @command{grep}, Q&A

    • v

  • Version, printing

    • w

  • whitespace characters
  • with filename prefix

    • x

  • xdigit class

    • z

  • zero-terminated file names
  • zero-terminated lines

    • Index

    This is an alphabetical list of all @command{grep} commands, command-line options, and environment variables.

    _

  • _N_GNU_nonoption_argv_flags_

    • g

  • GREP_OPTIONS

    • l

  • LANG, LANG
  • LC_ALL, LC_ALL
  • LC_CTYPE
  • LC_MESSAGES

    • p

  • POSIXLY_CORRECT

    • This document was generated on 11 January 2000 using the texi2html translator version 1.54.


GRUB Manual

Node:Top, Next:Introduction, Up:(dir)

GRUB manual

This is the documentation of GNU GRUB, the GRand Unified Bootloader, a flexible and powerful boot loader program for PCs.

This edition documents version 0.92.

  • Introduction: Capturing the spirit of GRUB
  • Naming convention: Names of your drives in GRUB
  • Installation: Installing GRUB on your drive
  • Booting: How to boot different operating systems
  • Configuration: Writing your own configuration file
  • Network: Downloading OS images from a network
  • Serial terminal: Using GRUB via a serial line
  • Preset Menu: Embedding a configuration file into GRUB
  • Security: Improving the security
  • Images: GRUB image files
  • Filesystem: Filesystem syntax and semantics
  • Interface: The menu and the command-line
  • Commands: The list of available builtin commands
  • Troubleshooting: Error messages produced by GRUB
  • Invoking the grub shell: How to use the grub shell
  • Invoking grub-install: How to use the GRUB installer
  • Invoking grub-md5-crypt: How to generate a cryptic password
  • Invoking mbchk: How to use the Multiboot checker
  • FAQ: Frequently asked questions
  • Obtaining and Building GRUB: How to obtain and build GRUB
  • Reporting bugs: Where you should send a bug report
  • Future: Some future plans on GRUB
  • Internals: Hacking GRUB
  • Index:

Node:Introduction, Next:Naming convention, Previous:Top, Up:Top

Introduction to GRUB

  • Overview: What exactly GRUB is and how to use it
  • History: From maggot to house fly
  • Features: GRUB features
  • Role of a boot loader: The role of a boot loader

Node:Overview, Next:History, Up:Introduction

Overview

Briefly, a boot loader is the first software program that runs when a computer starts. It is responsible for loading and transferring control to an operating system kernel software (such as Linux or GNU Mach). The kernel, in turn, initializes the rest of the operating system (e.g. a GNU system).

GNU GRUB is a very powerful boot loader, which can load a wide variety of free operating systems, as well as proprietary operating systems with chain-loading1. GRUB is designed to address the complexity of booting a personal computer; both the program and this manual are tightly bound to that computer platform, although porting to other platforms may be addressed in the future.

One of the important features in GRUB is flexibility; GRUB understands filesystems and kernel executable formats, so you can load an arbitrary operating system the way you like, without recording the physical position of your kernel on the disk.

Thus you can load the kernel just by specifying its file name and the drive (and the partition) where the kernel resides. To let GRUB know the drive and the file name, you can either type in them manually via the command-line interface (see Command-line interface), or use the nice menu interface (see Menu interface) through which you can easily select which OS it boots. To allow you to customize the menu, GRUB will load a preexisting configuration file (see Configuration). Note that you can not only enter the command-line interface whenever you like, but also you can edit specific menu entries prior to using them.

In the following chapters, you will learn how to specify a drive or a partition, and a file name (see Naming convention) to GRUB, how to install GRUB on your drive (see Installation), and how to boot your OSes (see Booting), step by step.

Node:History, Next:Features, Previous:Overview, Up:Introduction

History of GRUB

GRUB originated in 1995 when Erich Boleyn was trying to boot the GNU Hurd with the University of Utah's Mach 4 microkernel (now known as GNU Mach). Erich and Brian Ford designed the Multiboot Specification (see Multiboot Specification), because they were determined not to add to the large number of mutually-incompatible PC boot methods.

Erich then began modifying the FreeBSD boot loader so that it would understand Multiboot. He soon realized that it would be a lot easier to write his own boot loader from scratch than to keep working on the FreeBSD boot loader, and so GRUB was born.

Erich added many features to GRUB, but other priorities prevented him from keeping up with the demands of its quickly-expanding user base. In 1999, Gordon Matzigkeit and Yoshinori K. Okuji adopted GRUB as an official GNU package, and opened its development by making the latest sources available via anonymous CVS. See Obtaining and Building GRUB, for more information.

Node:Features, Next:Role of a boot loader, Previous:History, Up:Introduction

GRUB features

The primary requirement for GRUB is that it be compliant with the Multiboot Specification, which is described in Multiboot Specification.

The other goals, listed in approximate order of importance, are:

  • Basic functions must be straightforward for end-users.
  • Rich functionality to support kernel experts and designers.
  • Backward compatibility for booting FreeBSD, NetBSD, OpenBSD, and Linux. Proprietary kernels (such as DOS, Windows NT, and OS/2) are supported via a chain-loading function.

Except for specific compatibility modes (chain-loading and the Linux piggyback format), all kernels will be started in much the same state as in the Multiboot Specification. Only kernels loaded at 1 megabyte or above are presently supported. Any attempt to load below that boundary will simply result in immediate failure and an error message reporting the problem.

In addition to the requirements above, GRUB has the following features (note that the Multiboot Specification doesn't require all the features that GRUB supports):

Recognize multiple executable formats
Support many of the a.out variants plus ELF. Symbol tables are also loaded.
Support non-Multiboot kernels
Support many of the various free 32-bit kernels that lack Multiboot compliance (primarily FreeBSD, NetBSD, OpenBSD, and Linux). Chain-loading of other boot loaders is also supported.
Load multiples modules
Fully support the Multiboot feature of loading multiple modules.
Load a configuration file
Support a human-readable text configuration file with preset boot commands. You can also load another configuration file dynamically and embed a preset configuration file in a GRUB image file. The list of commands (see Commands) are a superset of those supported on the command-line. An example configuration file is provided in Configuration.
Provide a menu interface
A menu interface listing the preset boot commands, with a programmable timeout, is available. There is no fixed limit on the number of boot entries, and the current implementation has space for several hundred.
Have a flexible command-line interface
A fairly flexible command-line interface, accessible from the menu, is available to edit any preset commands, or write a new boot command set from scratch. If no configuration file is present, GRUB drops to the command-line.

The list of commands (see Commands) are a subset of those supported for configuration files. Editing commands closely resembles the Bash command-line (see Bash), with <TAB>-completion of commands, devices, partitions, and files in a directory depending on context.

Support multiple filesystem types
Support multiple filesystem types transparently, plus a useful explicit blocklist notation. The currently supported filesystem types are BSD FFS, DOS FAT16 and FAT32, Minix fs, Linux ext2fs, ReiserFS, JFS, XFS, and VSTa fs. See Filesystem, for more information.
Support automatic decompression
Can decompress files which were compressed by gzip. This function is both automatic and transparent to the user (i.e. all functions operate upon the uncompressed contents of the specified files). This greatly reduces a file size and the loading time, a particularly major benefit for floppies.2

It is conceivable that some kernel modules should be loaded in a compressed state, so a different module-loading command can be specified to avoid uncompressing the modules.

Access data on any installed device
Support reading data from any or all floppy or hard disk(s) recognized by the BIOS, independent of the setting of the root device.
Be independent of drive geometry translations
Unlike many other boot loaders, GRUB makes the particular drive translation irrelevant. A drive installed and running with one translation may be converted to another translation without any adverse effects or changes in GRUB's configuration.
Detect all installed RAM
GRUB can generally find all the installed RAM on a PC-compatible machine. It uses an advanced BIOS query technique for finding all memory regions. As described on the Multiboot Specification (see Multiboot Specification), not all kernels make use of this information, but GRUB provides it for those who do.
Support Logical Block Address mode
In traditional disk calls (called CHS mode), there is a geometry translation problem, that is, the BIOS cannot access over 1024 cylinders, so the accessible space is limited to at least 508 MB and to at most 8GB. GRUB can't universally solve this problem, as there is no standard interface used in all machines. However, several newer machines have the new interface, Logical Block Address (LBA) mode. GRUB automatically detects if LBA mode is available and uses it if available. In LBA mode, GRUB can access the entire disk.
Support network booting
GRUB is basically a disk-based boot loader but also has network support. You can load OS images from a network by using the TFTP protocol.
Support remote terminals
To support computers with no console, GRUB provides remote terminal support, so that you can control GRUB from a remote host. Only serial terminal support is implemented at the moment.

Node:Role of a boot loader, Previous:Features, Up:Introduction

The role of a boot loader

The following is a quotation from Gordon Matzigkeit, a GRUB fanatic:

Some people like to acknowledge both the operating system and kernel when they talk about their computers, so they might say they use "GNU/Linux" or "GNU/Hurd". Other people seem to think that the kernel is the most important part of the system, so they like to call their GNU operating systems "Linux systems."

I, personally, believe that this is a grave injustice, because the boot loader is the most important software of all. I used to refer to the above systems as either "LILO"3 or "GRUB" systems.

Unfortunately, nobody ever understood what I was talking about; now I just use the word "GNU" as a pseudonym for GRUB.

So, if you ever hear people talking about their alleged "GNU" systems, remember that they are actually paying homage to the best boot loader around... GRUB!

We, the GRUB maintainers, do not (usually) encourage Gordon's level of fanaticism, but it helps to remember that boot loaders deserve recognition. We hope that you enjoy using GNU GRUB as much as we did writing it.

Node:Naming convention, Next:Installation, Previous:Introduction, Up:Top

Naming convention

The device syntax used in GRUB is a wee bit different from what you may have seen before in your operating system(s), and you need to know it so that you can specify a drive/partition.

Look at the following examples and explanations:

(fd0)

First of all, GRUB requires that the device name is enclosed with ( and ). The fd part means that it is a floppy disk. The number 0 is the drive number, which is counted from zero. This expression means that GRUB will use the whole floppy disk.

(hd0,1)

Here, hd means it is a hard disk drive. The first integer 0 indicates the drive number, that is, the first hard disk, while the second integer, 1, indicates the partition number (or the PC slice number in the BSD terminology). Once again, please note that the partition numbers are counted from zero, not from one. This expression means the second partition of the first hard disk drive. In this case, GRUB uses one partition of the disk, instead of the whole disk.

(hd0,4)

This specifies the first extended partition of the first hard disk drive. Note that the partition numbers for extended partitions are counted from 4, regardless of the actual number of primary partitions on your hard disk.

(hd1,a)

This means the BSD a partition of the second hard disk. If you need to specify which PC slice number should be used, use something like this: (hd1,0,a). If the PC slice number is omitted, GRUB searches for the first PC slice which has a BSD a partition.

Of course, to actually access the disks or partitions with GRUB, you need to use the device specification in a command, like root (fd0) or unhide (hd0,2). To help you find out which number is a partition you want, the GRUB command-line (see Command-line interface) options have argument completion. That means that, for example, you only need to type root (, followed by a <TAB>, and GRUB will display the list of drives, partitions, or file names, so it should be quite easy to determine the name of your target partition, even with minimal knowledge of the syntax.

Note that GRUB does not distinguish IDE from SCSI - it simply counts the drive numbers from zero, regardless of their type. Normally, any IDE drive number is less than any SCSI drive number, although that is not true if you change the boot sequence by swapping IDE and SCSI drives in your BIOS.

Now the question is, how to specify a file? Again, see this example:

(hd0,0)/vmlinuz

This specifies the file named vmlinuz, found on the first partition of the first hard disk drive. Note that the argument completion works with file names, too.

That was easy, admit it. Do read the next chapter, to find out how to actually install GRUB on your drive.

Node:Installation, Next:Booting, Previous:Naming convention, Up:Top

Installation

First, you need to have GRUB itself properly installed on your system, (see Obtaining and Building GRUB) either from the source tarball, or as a package for your OS.

To use GRUB, you need to install it on your drive. There are two ways of doing that - either using the utility grub-install (see Invoking grub-install) on a UNIX-like OS, or by using the native Stage 2. These are quite similar, however, the utility might probe a wrong BIOS drive, so better be careful.

Also, if you install GRUB on a UNIX-like OS, please make sure that you have an emergency boot disk ready, so that you can rescue your computer if, by any chance, your hard drive becomes unusable (unbootable).

GRUB comes with boot images, which are normally installed in the directory /usr/share/grub/i386-pc. You need to copy the files stage1, stage2, and *stage1_5 to the directory /boot/grub. Here the directory where GRUB images are installed and the directory where GRUB will use to find them are called image directory and boot directory, respectively.

  • Creating a GRUB boot floppy:
  • Installing GRUB natively:
  • Installing GRUB using grub-install:

Node:Creating a GRUB boot floppy, Next:Installing GRUB natively, Up:Installation

Creating a GRUB boot floppy

To create a GRUB boot floppy, you need to take the files stage1 and stage2 from the image directory, and write them to the first and the second block of the floppy disk, respectively.

Caution: This procedure will destroy any data currently stored on the floppy.

On a UNIX-like operating system, that is done with the following commands:

# cd /usr/share/grub/i386-pc
# dd if=stage1 of=/dev/fd0 bs=512 count=1
1+0 records in
1+0 records out
# dd if=stage2 of=/dev/fd0 bs=512 seek=1
153+1 records in
153+1 records out
#

The device file name may be different. Consult the manual for your OS.

Node:Installing GRUB natively, Next:Installing GRUB using grub-install, Previous:Creating a GRUB boot floppy, Up:Installation

Installing GRUB natively

Caution: Installing GRUB's stage1 in this manner will erase the normal boot-sector used by an OS.

GRUB can currently boot GNU Mach, Linux, FreeBSD, NetBSD, and OpenBSD directly, so using it on a boot sector should be okay. But generally, it would be a good idea to back up the first sector of the partition on which you are installing GRUB's stage1. This isn't as important if you are installing GRUB on the first sector of a hard disk, since it's easy to reinitialize it (e.g. by running FDISK /MBR from DOS).

If you decide to install GRUB in the native environment, which is definitely desirable, you'll need to create the GRUB boot disk, and reboot your computer with it. Otherwise, see Installing GRUB using grub-install, for more details.

Once started, GRUB will show the command-line interface (see Command-line interface). First, set the GRUB's root device 4 to the boot directory, like this:

grub> root (hd0,0)

If you are not sure which partition actually holds these files, use the command find (see find), like this:

grub> find /boot/grub/stage1

This will search for the file name /boot/grub/stage1 and show the devices which contain the file.

Once you've set the root device correctly, run the command setup (see setup):

grub> setup (hd0)

This command will install GRUB on the MBR in the first drive. If you want to install GRUB into the boot sector of a partition instead of the MBR, specify a partition into which you want to install GRUB:

grub> setup (hd0,0)

If you install GRUB into a partition or a drive other than the first one, you must chain-load GRUB from another boot loader. Refer to the manual for the boot loader to know how to chain-load GRUB.

Now you can boot GRUB without a GRUB floppy. See the chapter Booting to find out how to boot your operating systems from GRUB.

Node:Installing GRUB using grub-install, Previous:Installing GRUB natively, Up:Installation

Installing GRUB using grub-install

Caution: This procedure is definitely deprecated, because there are several posibilities that your computer can be unbootable. For example, most operating systems don't tell GRUB how to map BIOS drives to OS devices correctly, GRUB merely guesses the mapping. This will succeed in most cases, but not always. So GRUB provides you with a user-defined map file called device map, which you must fix, if it is wrong. See Device map, for more details.

Unfortunately, if you do want to install GRUB under a UNIX-like OS (such as GNU), invoke the program grub-install (see Invoking grub-install) as the superuser (root).

The usage is basically very easy. You only need to specify one argument to the program, namely, where to install GRUB. The argument can be either of a device file or a GRUB's drive/partition. So, this will install GRUB into the MBR of the first IDE disk under Linux:

# grub-install /dev/hda

Likewise, under GNU/Hurd, this has the same effect:

# grub-install /dev/hd0

If it is the first BIOS drive, this is the same as well:

# grub-install '(hd0)'

But all the above examples assume that you use GRUB images under the root directory. If you want GRUB to use images under a directory other than the root directory, you need to specify the option --root-directory. The typical usage is that you create a GRUB boot floppy with a filesystem. Here is an example:

# mke2fs /dev/fd0
# mount -t ext2 /dev/fd0 /mnt
# grub-install --root-directory=/mnt '(fd0)'
# umount /mnt

Another example is in case that you have a separate boot partition which is mounted at /boot. Since GRUB is a boot loader, it doesn't know anything about mountpoints at all. Thus, you need to run grub-install like this:

# grub-install --root-directory=/boot /dev/hda

By the way, as noted above, it is quite difficult to guess BIOS drives correctly under a UNIX-like OS. Thus, grub-install will prompt you to check if it could really guess the correct mappings, after the installation. The format is defined in Device map. Please be careful enough. If the output is wrong, it is unlikely that your computer can boot with no problem.

Note that grub-install is actually just a shell script and the real task is done by the grub shell grub (see Invoking the grub shell). Therefore, you may run grub directly to install GRUB, without using grub-install. Don't do that, however, unless you are very familiar with the internals of GRUB. Installing a boot loader on a running OS may be extremely dangerous.

Node:Booting, Next:Configuration, Previous:Installation, Up:Top

Booting

For Multiboot-compliant kernels, GRUB can load them in a consistent way, but, for some free operating systems, you need to use some OS-specific magic.

  • General boot methods: How to boot OSes with GRUB genenerally
  • OS-specific notes: Notes on some operating systems

Node:General boot methods, Next:OS-specific notes, Up:Booting

How to boot operating systems

GRUB has two distinct boot methods. One of the two is to load an operating system directly, and the other is to chain-load another boot loader which then will load an operating system actually. Generally speaking, the former is desirable, because you don't need to install or maintain other boot loaders and GRUB is flexible enough to load an operating system from an arbitrary disk/partition. However, the latter is sometimes required, since GRUB doesn't support all the existing operating systems natively.

  • Loading an operating system directly:
  • Chain-loading:

Node:Loading an operating system directly, Next:Chain-loading, Up:General boot methods

How to boot an OS directly with GRUB

Multiboot (see Multiboot Specification) is the native format supported by GRUB. For the sake of convenience, there are also support for Linux, FreeBSD, NetBSD and OpenBSD. If you want to boot other operating systems, you will have to chain-load them (see Chain-loading).

Generally, GRUB can boot any Multiboot-compliant OS in the following steps:

  1. Set GRUB's root device to the drive where the OS images are stored by the command root (see root).
  2. Load the kernel image by the command kernel (see kernel).
  3. If you need modules, load them with the command module (see module) or modulenounzip (see modulenounzip).
  4. Run the command boot (see boot).

Linux, FreeBSD, NetBSD and OpenBSD can be booted in a similar manner. You can load a kernel image by the command kernel and then run the command boot. If the kernel requires some parameters, just append the parameters to kernel, after the file name of the kernel. Also, please refer to OS-specific notes, for the information on your OS-specific issues.

Node:Chain-loading, Previous:Loading an operating system directly, Up:General boot methods

Load another boot loader to boot unsupported operating systems

If you want to boot an unsupported operating system (e.g. Windows 95), chain-load a boot loader for the operating system. Normally, the boot loader is embedded in the boot sector of the partition on which the operating system is installed.

  1. Set GRUB's root device to the partition by the command rootnoverify (see rootnoverify):
    grub> rootnoverify (hd0,0)
  2. Set the active flag in the partition by the command makeactive 5 (see makeactive):
    grub> makeactive
  3. Load the boot loader by the command chainloader (see chainloader):
    grub> chainloader +1

    +1 indicates that GRUB should read one sector from the start of the partition. The complete description about this syntax can be found in Block list syntax.

  4. Run the command boot (see boot).

However, DOS and Windows have some deficiencies, so you might have to use more complicated instructions. See DOS/Windows, for more information.

Node:OS-specific notes, Previous:General boot methods, Up:Booting

Some caveats on OS-specific issues

Here, we describe some caveats on several operating systems.

  • GNU/Hurd:
  • GNU/Linux:
  • FreeBSD:
  • NetBSD:
  • OpenBSD:
  • DOS/Windows:
  • SCO UnixWare:

Node:GNU/Hurd, Next:GNU/Linux, Up:OS-specific notes

GNU/Hurd

Since GNU/Hurd is Multiboot-compliant, it is easy to boot it; there is nothing special about it. But do not forget that you have to specify a root partition to the kernel.

  1. Set GRUB's root device to the same drive as GNU/Hurd's. Probably the command find /boot/gnumach or similar can help you (see find).
  2. Load the kernel and the module, like this:
    grub> kernel /boot/gnumach root=hd0s1
grub> module /boot/serverboot
  3. Run the command boot (see boot).

Node:GNU/Linux, Next:FreeBSD, Previous:GNU/Hurd, Up:OS-specific notes

GNU/Linux

It is relatively easy to boot GNU/Linux from GRUB, because it somewhat resembles to boot a Multiboot-compliant OS.

  1. Set GRUB's root device to the same drive as GNU/Linux's. Probably the command find /vmlinuz or similar can help you (see find).
  2. Load the kernel:
    grub> kernel /vmlinuz root=/dev/hda1

    If you need to specify some kernel parameters, just append them to the command. For example, to set vga to ext, do this:

    grub> kernel /vmlinuz root=/dev/hda1 vga=ext

    See the documentation in the Linux source tree for the complete information on the available options.

  3. If you use an initrd, execute the command initrd (see initrd) after kernel:
    grub> initrd /initrd
  4. Finally, run the command boot (see boot).

Caution: If you use an initrd and specify the mem= option to the kernel, to let it use less than actual memory size, you will also have to specify the same memory size to GRUB. To let GRUB know the size, run the command uppermem before loading the kernel. See uppermem, for more information.

Node:FreeBSD, Next:NetBSD, Previous:GNU/Linux, Up:OS-specific notes

FreeBSD

GRUB can load the kernel directly, either in ELF or a.out format. But this is not recommended, since FreeBSD's bootstrap interface sometimes changes heavily, so GRUB can't guarantee to pass kernel parameters correctly.

Thus, we'd recommend loading the very flexible loader /boot/loader instead. See this example:

grub> root (hd0,a)
grub> kernel /boot/loader
grub> boot

Node:NetBSD, Next:OpenBSD, Previous:FreeBSD, Up:OS-specific notes

NetBSD

GRUB can load NetBSD a.out and ELF directly, follow these steps:

  1. Set GRUB's root device with root (see root).
  2. Load the kernel with kernel (see kernel). You should append the ugly option --type=netbsd, if you want to load an ELF kernel, like this:
    grub> kernel --type=netbsd /netbsd-elf
  3. Run boot (see boot).

For now, however, GRUB doesn't allow you to pass kernel parameters, so it may be better to chain-load it instead, for more information please see Chain-loading.

Node:OpenBSD, Next:DOS/Windows, Previous:NetBSD, Up:OS-specific notes

OpenBSD

The booting instruction is exactly the same as for NetBSD (see NetBSD).

Node:DOS/Windows, Next:SCO UnixWare, Previous:OpenBSD, Up:OS-specific notes

DOS/Windows

GRUB cannot boot DOS or Windows directly, so you must chain-load them (see Chain-loading). However, their boot loaders have some critical deficiencies, so it may not work to just chain-load them. To overcome the problems, GRUB provides you with two helper functions.

If you have installed DOS (or Windows) on a non-first hard disk, you have to use the disk swapping technique, because that OS cannot boot from any disks but the first one. The workaround used in GRUB is the command map (see map), like this:

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

This performs a virtual swap between your first and second hard drive.

Caution: This is effective only if DOS (or Windows) uses BIOS to access the swapped disks. If that OS uses a special driver for the disks, this probably won't work.

Another problem arises if you installed more than one set of DOS/Windows onto one disk, because they could be confused if there are more than one primary partitions for DOS/Windows. Certainly you should avoid doing this, but there is a solution if you do want to do so. Use the partition hiding/unhiding technique.

If GRUB hides a DOS (or Windows) partition (see hide), DOS (or Windows) will ignore the partition. If GRUB unhides a DOS (or Windows) partition (see unhide), DOS (or Windows) will detect the partition. Thus, if you have installed DOS (or Windows) on the first and the second partition of the first hard disk, and you want to boot the copy on the first partition, do the following:

grub> unhide (hd0,0)
grub> hide (hd0,1)
grub> rootnoverify (hd0,0)
grub> chainloader +1
grub> makeactive
grub> boot

Node:SCO UnixWare, Previous:DOS/Windows, Up:OS-specific notes

SCO UnixWare

It is known that the signature in the boot loader for SCO UnixWare is wrong, so you will have to specify the option --force to chainloader (see chainloader), like this:

grub> rootnoverify (hd1,0)
grub> chainloader --force +1
grub> makeactive
grub> boot

Node:Configuration, Next:Network, Previous:Booting, Up:Top

Configuration

You probably noticed that you need to type several commands to boot your OS. There's a solution to that - GRUB provides a menu interface (see Menu interface) from which you can select an item (using arrow keys) that will do everything to boot an OS.

To enable the menu, you need a configuration file, menu.lst under the boot directory. We'll analyze an example file.

The file first contains some general settings, the menu interface related options. You can put these commands (see Menu-specific commands) before any of the items (starting with title (see title)).

#
# Sample boot menu configuration file
#

As you may have guessed, these lines are comments. Lines starting with a hash character (#), and blank lines, are ignored by GRUB.

# By default, boot the first entry.
default 0

The first entry (here, counting starts with number zero, not one!) will be the default choice.

# Boot automatically after 30 secs.
timeout 30

As the comment says, GRUB will boot automatically in 30 seconds, unless interrupted with a keypress.

# Fallback to the second entry.
fallback 1

If, for any reason, the default entry doesn't work, fall back to the second one (this is rarely used, for obvious reasons).

Note that the complete descriptions of these commands, which are menu interface specific, can be found in Menu-specific commands. Other descriptions can be found in Commands.

Now, on to the actual OS definitions. You will see that each entry begins with a special command, title (see title), and the action is described after it. Note that there is no command boot (see boot) at the end of each item. That is because GRUB automatically executes boot if it loads other commands successfully.

The argument for the command title is used to display a short title/description of the entry in the menu. Since title displays the argument as is, you can write basically anything in there.

# For booting GNU/Hurd
title  GNU/Hurd
root   (hd0,0)
kernel /boot/gnumach.gz root=hd0s1
module /boot/serverboot.gz

This boots GNU/Hurd from the first hard disk.

# For booting GNU/Linux
title  GNU/Linux
kernel (hd1,0)/vmlinuz root=/dev/hdb1

This boots GNU/Linux, but from the second hard disk.

# For booting Mach (getting kernel from floppy)
title  Utah Mach4 multiboot
root   (hd0,2)
pause  Insert the diskette now^G!!
kernel (fd0)/boot/kernel root=hd0s3
module (fd0)/boot/bootstrap

This boots Mach with a kernel on a floppy, but the root filesystem at hd0s3. It also contains a pause line (see pause), which will cause GRUB to display a prompt and delay, before actually executing the rest of the commands and booting.

# For booting FreeBSD
title  FreeBSD
root   (hd0,2,a)
kernel /boot/loader

This item will boot FreeBSD kernel loaded from the a partition of the third PC slice of the first hard disk.

# For booting OS/2
title OS/2
root  (hd0,1)
makeactive
# chainload OS/2 bootloader from the first sector
chainloader +1
# This is similar to "chainload", but loads a specific file
#chainloader /boot/chain.os2

This will boot OS/2, using a chain-loader (see Chain-loading).

# For booting Windows NT or Windows95
title Windows NT / Windows 95 boot menu
root        (hd0,0)
makeactive
chainloader +1
# For loading DOS if Windows NT is installed
# chainload /bootsect.dos

The same as the above, but for Windows.

# For installing GRUB into the hard disk
title Install GRUB into the hard disk
root    (hd0,0)
setup   (hd0)

This will just (re)install GRUB onto the hard disk.

# Change the colors.
title Change the colors
color light-green/brown blink-red/blue

In the last entry, the command color is used (see color), to change the menu colors (try it!). This command is somewhat special, because it can be used both in the command-line and in the menu. GRUB has several such commands, see General commands.

We hope that you now understand how to use the basic features of GRUB. To learn more about GRUB, see the following chapters.

Node:Network, Next:Serial terminal, Previous:Configuration, Up:Top

Downloading OS images from a network

Although GRUB is a disk-based boot loader, it does provide network support. To use the network support, you need to enable at least one network driver in the GRUB build process. For more information please see netboot/README.netboot in the source distribution.

  • General usage of network support:
  • Diskless:

Node:General usage of network support, Next:Diskless, Up:Network

How to set up your network

GRUB requires a file server and optionally a server that will assign an IP address to the machine on which GRUB is running. For the former, only TFTP is supported at the moment. The latter is either BOOTP, DHCP or a RARP server6. It is not necessary to run both the servers on one computer. How to configure these servers is beyond the scope of this document, so please refer to the manuals specific to those protocols/servers.

If you decided to use a server to assign an IP address, set up the server and run bootp (see bootp), dhcp (see dhcp) or rarp (see rarp) for BOOTP, DHCP or RARP, respectively. Each command will show an assigned IP address, a netmask, an IP address for your TFTP server and a gateway. If any of the addresses is wrong or it causes an error, probably the configuration of your servers isn't set up properly.

Otherwise, run ifconfig, like this:

grub> ifconfig --address=192.168.110.23 --server=192.168.110.14

You can also use ifconfig in conjugation with bootp, dhcp or rarp (e.g. to reassign the server address manually). See ifconfig, for more details.

Finally, download your OS images from your network. The network can be accessed using the network drive (nd). Everything else is very similar to the normal instructions (see Booting).

Here is an example:

grub> bootp
Probing... [NE*000]
NE2000 base ...
Address: 192.168.110.23    Netmask: 255.255.255.0
Server: 192.168.110.14     Gateway: 192.168.110.1

grub> root (nd)
grub> kernel /tftproot/gnumach.gz root=sd0s1
grub> module /tftproot/serverboot.gz
grub> boot

Node:Diskless, Previous:General usage of network support, Up:Network

Booting from a network

It is sometimes very useful to boot from a network, especially, when you use a machine which has no local disk. In this case, you need to obtain a kind of Net Boot ROM, such as a PXE ROM or a free software package like Etherboot. Such a Boot ROM first boots the machine, sets up the network card installed into the machine, and downloads a second stage boot image from the network. Then, the second image will try to boot an operating system from the network actually.

GRUB provides two second stage images, nbgrub and pxegrub (see Images). Those images are the same as the normal Stage 2, except that they set up a network automatically, and try to load a configuration file from the network, if specified. The usage is very simple: If the machine has a PXE ROM, use pxegrub. If the machine has a NBI loader such as Etherboot, use nbgrub. There is no difference between them but their formats. As how to load a second stage image you want to use should be described in the manual on your Net Boot ROM, please refer to the manual, for more information.

However, there is one thing specific to GRUB. Namely, how to specify a configuration file in a BOOTP/DHCP server. For now, GRUB uses the tag 150, to get the name of a configuration file. This below is an example about a BOOTP configuration:

.allhost:hd=/tmp:bf=null:\
        :ds=145.71.35.1 145.71.32.1:\
        :sm=255.255.254.0:\
        :gw=145.71.35.1:\
        :sa=145.71.35.5:

foo:ht=1:ha=63655d0334a7:ip=145.71.35.127:\
        :bf=/nbgrub:\
        :tc=.allhost:\
        :T150="(nd)/tftpboot/menu.lst.foo":

Note that you should specify the drive name (nd) in the name of the configuration file. That is because you can change the root drive before downloading the configuration from the TFTP server, when the preset menu feature is used (see Preset Menu).

See the manual about your BOOTP/DHCP server, for more information. The exact syntax should differ from the example, more or less.

Node:Serial terminal, Next:Preset Menu, Previous:Network, Up:Top

Using GRUB via a serial line

This chapter describes how to use the serial terminal support in GRUB.

If you have many computers or computers with no display/keyboard, it would be very useful to control the computers with serial communications. To connect a computer with another via a serial line, you need to prepare a null-modem (cross) serial cable, and you may need to have multiport serial boards, if your computer doesn't have extra serial ports. In addition, a terminal emulator is also required, such as minicom. Refer to a manual of your operating system, for more information.

As for GRUB, the instruction to set up a serial terminal is quite simple. First of all, make sure that you haven't specified the option --disable-serial to the configure script when you built your GRUB images. If you get them in binary form, probably they have serial terminal support already.

Then, initialize your serial terminal after GRUB starts up. Here is an example:

grub> serial --unit=0 --speed=9600
grub> terminal serial

The command serial initializes the serial unit 0 with the speed 9600bps. The serial unit 0 is usually called COM1, so, if you want to use COM2, you must specify --unit=1 instead. This command accepts many other options, so please refer to serial, for more details.

The command terminal (see terminal) chooses which type of terminal you want to use. In that case above, the terminal will be a serial terminal, but you can also pass console to the command, like terminal serial console. In this case, a terminal in which you press any key will be selected as a GRUB terminal.

However, note that GRUB assumes that your terminal emulator is compatible with VT100 by default. This is true for most terminal emulators nowadays, but you should pass the option --dumb to the command, if your terminal emulator is not VT100-compatible or implements few VT100 escape sequences. If you specify the option, then GRUB provides you with an alternative menu interface, because the normal menu requires several fancy features for your terminal.

Node:Preset Menu, Next:Security, Previous:Serial terminal, Up:Top

Embedding a configuration file into GRUB

GRUB supports preset menu which is always loaded before starting. The preset menu feature is useful, for example, when your computer has no console but a serial cable. In this case, it is critical to set up the serial terminal as soon as possible, since you cannot see any message until the serial terminal begins to work. So it is nice to run the commands serial (see serial) and terminal (see terminal) sooner than anything else at the start-up time.

It is slightly complicated how the preset menu works:

  1. GRUB checks if the preset menu feature is used, and loads the preset menu, if available. This includes running commands and reading boot entries, like an ordinary configuration file.
  2. GRUB checks if the configuration file is available. Note that this check is performed regardless of the existence of the preset menu. The configuration file is loaded, even after the preset menu was loaded.
  3. When the preset menu includes any boot entries, they are cleared when the configuration file is loaded. It doesn't matter whether the configuration file has any entries or no entry. The boot entries in the preset menu are used only when GRUB fails in loading the configuration file.

To enable the preset menu feature, you must specify a file to the configure script with the option --enable-preset-menu. The file has the same semantics as normal configuration files (see Configuration).

Another point you should take care is that the diskless support (see Diskless) diverts the preset menu. Diskless images embed a preset menu to execute the command bootp (see bootp) automatically, unless you specify your own preset menu to the configure script. This means that you must put commands to initialize a network in the preset menu yourself, because diskless images don't set it up implicitly, when you use the preset menu explicitly.

Therefore, a typical preset menu used with diskless support would be like this:

# Set up the serial terminal, first of all.
serial --unit=0 --speed=19200
terminal --timeout=0 serial

# Initialize the network.
dhcp

Node:Security, Next:Images, Previous:Preset Menu, Up:Top

Protecting your computer from cracking

You may be interested in how to prevent ordinary users from doing whatever they like, if you share your computer with other people. So this chapter describes how to improve the security of GRUB.

One thing which could be a security hole is that the user can do too many things with GRUB, because GRUB allows to modify its configuration and run arbitrary commands at run-time. For example, the user can read even /etc/passwd in the command-line interface by the command cat (see cat). So it is necessary to disable all the interactive operations.

Thus, GRUB provides password feature, so that only administrators can start the interactive operations (i.e. editing menu entries and entering the command-line interface). To use this feature, you need to run the command password in your configuration file (see password), like this:

password --md5 PASSWORD

If this is specified, GRUB disallows any interactive control, until you press the key <p> and enter a correct password. The option --md5 tells GRUB that PASSWORD is in MD5 format. If it is omitted, GRUB assumes the PASSWORD is in clear text.

You can encrypt your password with the command md5crypt (see md5crypt). For example, run the grub shell (see Invoking the grub shell), and enter your password:

grub> md5crypt
Password: **********
Encrypted: $1$U$JK7xFegdxWH6VuppCUSIb.

Then, cut and paste the encrypted password to your configuration file.

Also, you can specify an optional argument to password. See this example:

password PASSWORD /boot/grub/menu-admin.lst

In this case, GRUB will load /boot/grub/menu-admin.lst as a configuration file when you enter the valid password.

Another thing which may be dangerous is that any user can choose any menu entry. Usually, this wouldn't be problematic, but you might want to permit only administrators to run some of your menu entries, such as an entry for booting an insecure OS like DOS.

GRUB provides the command lock (see lock). This command always fails until you enter a valid password, so you can use it, like this:

title Boot DOS
lock
rootnoverify (hd0,1)
makeactive
chainload +1

You should insert lock right after title, because any user can execute commands in an entry, until GRUB encounters lock.

You can also use the command password instead of lock. In this case the boot process will ask for the password and stop if it was entered incorrectly. Since the password takes its own PASSWORD argument this is useful if you want different passwords for different entries.

Node:Images, Next:Filesystem, Previous:Security, Up:Top

GRUB image files

GRUB consists of several images: two essential stages, optional stages called Stage 1.5, and two network boot images. Here is a short overview of them. See Internals, for more details.

stage1
This is an essential image used for booting up GRUB. Usually, this is embedded in a MBR or the boot sector of a partition. Because a PC boot sector is 512 bytes, the size of this image is exactly 512 bytes.

All stage1 must do is to load Stage 2 or Stage 1.5 from a local disk. Because of the size restriction, stage1 encodes the location of Stage 2 (or Stage 1.5) in a block list format, so it never understand any filesystem structure.

stage2
This is the core image of GRUB. This does all things but booting up itself. Usually, this is put in a filesystem, but that is not required.
e2fs_stage1_5
fat_stage1_5
ffs_stage1_5
jfs_stage1_5
minix_stage1_5
reiserfs_stage1_5
vstafs_stage1_5
xfs_stage1_5
These are called Stage 1.5, because the purpose is a bridge between stage1 and stage2, that is to say, Stage 1.5 is loaded by Stage 1 and Stage 1.5 loads Stage 2. The difference between stage1 and *_stage1_5 is that the former doesn't understand any filesystem but the latter does an filesystem (e.g. e2fs_stage1_5 understands ext2fs). So you can move the location of Stage 2 to another safely, even after GRUB has been installed.

While Stage 2 cannot generally be embedded in a fixed area as the size is so large, Stage 1.5 can be installed into the area right after a MBR, or the boot loader area of a ReiserFS or a FFS.

nbgrub
This is a network boot image for the Network Image Proposal used by some network boot loaders, such as Etherboot. This is mostly the same as Stage 2, but this also sets up a network and loads a configuration file from the network.
pxegrub
This is another network boot image for the Preboot Execution Environment used by several Netboot ROMs. This is identical to nbgrub, except for the format.

Node:Filesystem, Next:Interface, Previous:Images, Up:Top

Filesystem syntax and semantics

GRUB uses a special syntax for specifying disk drives which can be accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish between IDE, ESDI, SCSI, or others. You must know yourself which BIOS device is equivalent to which OS device. Normally, that will be clear if you see the files in a device or use the command find (see find).

  • Device syntax: How to specify devices
  • File name syntax: How to specify files
  • Block list syntax: How to specify block lists

Node:Device syntax, Next:File name syntax, Up:Filesystem

How to specify devices

The device syntax is like this:

(device[,part-num][,bsd-subpart-letter])

[] means the parameter is optional. device should be either fd or hd followed by a digit, like fd0. But you can also set device to a hexadecimal or a decimal, which is a BIOS drive number, so the following are equivalent:

(hd0)
(0x80)
(128)

part-num represents the partition number of device, starting from zero for primary partitions and from four for extended partitions, and bsd-subpart-letter represents the BSD disklabel subpartition, such as a or e.

A shortcut for specifying BSD subpartitions is (device,bsd-subpart-letter), in this case, GRUB searches for the first PC partition containing a BSD disklabel, then finds the subpartition bsd-subpart-letter. Here is an example:

(hd0,a)

The syntax like (hd0) represents using the entire disk (or the MBR when installing GRUB), while the syntax like (hd0,0) represents using the partition of the disk (or the boot sector of the partition when installing GRUB).

If you enabled the network support, the special drive, (nd), is also available. Before using the network drive, you must initialize the network. See Network, for more information.

Node:File name syntax, Next:Block list syntax, Previous:Device syntax, Up:Filesystem

How to specify files

There are two ways to specify files, by absolute file name and by block list.

An absolute file name resembles a Unix absolute file name, using / for the directory separator (not \ as in DOS). One example is (hd0,0)/boot/grub/menu.lst. This means the file /boot/grub/menu.lst in the first partition of the first hard disk. If you omit the device name in an absolute file name, GRUB uses GRUB's root device implicitly. So if you set the root device to, say, (hd1,0) by the command root (see root), then /boot/kernel is the same as (hd1,0)/boot/kernel.

Node:Block list syntax, Previous:File name syntax, Up:Filesystem

How to specify block lists

A block list is used for specifying a file that doesn't appear in the filesystem, like a chainloader. The syntax is [offset]+length[,[offset]+length].... Here is an example:

0+100,200+1,300+300

This represents that GRUB should read blocks 0 through 99, block 200, and blocks 300 through 599. If you omit an offset, then GRUB assumes the offset is zero.

Like the file name syntax (see File name syntax), if a blocklist does not contain a device name, then GRUB uses GRUB's root device. So (hd0,1)+1 is the same as +1 when the root device is (hd0,1).

Node:Interface, Next:Commands, Previous:Filesystem, Up:Top

GRUB's user interface

GRUB has both a simple menu interface for choosing preset entries from a configuration file, and a highly flexible command-line for performing any desired combination of boot commands.

GRUB looks for its configuration file as soon as it is loaded. If one is found, then the full menu interface is activated using whatever entries were found in the file. If you choose the command-line menu option, or if the configuration file was not found, then GRUB drops to the command-line interface.

  • Command-line interface: The flexible command-line interface
  • Menu interface: The simple menu interface
  • Menu entry editor: Editing a menu entry
  • Hidden menu interface: The hidden menu interface

Node:Command-line interface, Next:Menu interface, Up:Interface

The flexible command-line interface

The command-line interface provides a prompt and after it an editable text area much like a command-line in Unix or DOS. Each command is immediately executed after it is entered7. The commands (see Command-line and menu entry commands) are a subset of those available in the configuration file, used with exactly the same syntax.

Cursor movement and editing of the text on the line can be done via a subset of the functions available in the Bash shell:

<C-f>
<PC right key>
Move forward one character.
<C-b>
<PC left key>
Move back one character.
<C-a>
<HOME>
Move to the start of the line.
<C-e>
<END>
Move the the end of the line.
<C-d>
<DEL>
Delete the character underneath the cursor.
<C-h>
<BS>
Delete the character to the left of the cursor.
<C-k>
Kill the text from the current cursor position to the end of the line.
<C-u>
Kill backward from the cursor to the beginning of the line.
<C-y>
Yank the killed text back into the buffer at the cursor.
<C-p>
<PC up key>
Move up through the history list.
<C-n>
<PC down key>
Move down through the history list.

When typing commands interactively, if the cursor is within or before the first word in the command-line, pressing the <TAB> key (or <C-i>) will display a listing of the available commands, and if the cursor is after the first word, the <TAB> will provide a completion listing of disks, partitions, and file names depending on the context.

Note that you cannot use the completion functionality in the TFTP filesystem. This is because TFTP doesn't support file name listing for the security.

Node:Menu interface, Next:Menu entry editor, Previous:Command-line interface, Up:Interface

The simple menu interface

The menu interface is quite easy to use. Its commands are both reasonably intuitive and described on screen.

Basically, the menu interface provides a list of boot entries to the user to choose from. Use the arrow keys to select the entry of choice, then press <RET> to run it. An optional timeout is available to boot the default entry (the first one if not set), which is aborted by pressing any key.

Commands are available to enter a bare command-line by pressing <c> (which operates exactly like the non-config-file version of GRUB, but allows one to return to the menu if desired by pressing <ESC>) or to edit any of the boot entries by pressing <e>.

If you protect the menu interface with a password (see Security), all you can do is choose an entry by pressing <RET>, or press <p> to enter the password.

Node:Menu entry editor, Next:Hidden menu interface, Previous:Menu interface, Up:Interface

Editing a menu entry

The menu entry editor looks much like the main menu interface, but the lines in the menu are individual commands in the selected entry instead of entry names.

If an <ESC> is pressed in the editor, it aborts all the changes made to the configuration entry and returns to the main menu interface.

When a particular line is selected, the editor places the user at a special version of the GRUB command-line to edit that line. When the user hits <RET>, GRUB replaces the line in question in the boot entry with the changes (unless it was aborted via <ESC>, in which case the changes are thrown away).

If you want to add a new line to the menu entry, press <o> if adding a line after the current line or press <O> if before the current line.

To delete a line, hit the key <d>. Although GRUB does not support undo unfortunately, you can do almost the same thing by just returning to the main menu.

Node:Hidden menu interface, Previous:Menu entry editor, Up:Interface

The hidden menu interface

When your terminal is dumb or you request GRUB of hiding the menu interface explicitly with the command hiddenmenu (see hiddenmenu), GRUB doesn't show the menu interface (see Menu interface) and automatically boots the default entry, unless interrupted by pressing <ESC>.

When you interrupt the timeout and your terminal is dumb, GRUB falls back to the command-line interface (see Command-line interface).

Node:Commands, Next:Troubleshooting, Previous:Interface, Up:Top

The list of available commands

In this chapter, we list all commands that are available in GRUB.

Commands belong to different groups. A few can only be used in the global section of the configuration file (or "menu"); most of them can be entered on the command-line and can be either used in the menu or in the menu entries.

  • Menu-specific commands:
  • General commands:
  • Command-line and menu entry commands:

Node:Menu-specific commands, Next:General commands, Up:Commands

The list of commands for the menu only

The semantics used in parsing the configuration file are the following:

  • The menu-specific commands have to be used before any others.
  • The files must be in plain-text format.
  • # at the beginning of a line in a configuration file means it is only a comment.
  • Options are separated by spaces.
  • All numbers can be either decimal or hexadecimal. A hexadecimal number must be preceded by 0x, and is case-insensitive.
  • Extra options or text at the end of the line is ignored unless otherwise specified.
  • Unrecognized commands are added to the current entry, except before entries start, where they are ignored.

These commands can only be used in the menu:

  • default: Set the default entry
  • fallback: Set the fallback entry
  • hiddenmenu: Hide the menu interface
  • timeout: Set the timeout
  • title: Start a menu entry

Node:default, Next:fallback, Up:Menu-specific commands

default

default num Command
Set the default entry to the entry number num. Numbering starts from 0, and the entry number 0 is the default if the command is not used.

You can specify saved instead of a number. In this case, the default entry is the entry saved with the command savedefault. See savedefault, for more information.

Node:fallback, Next:hiddenmenu, Previous:default, Up:Menu-specific commands

fallback

fallback num Command
Go into unattended boot mode: if the default boot entry has any errors, instead of waiting for the user to do anything, immediately start over using the num entry (same numbering as the default command (see default)). This obviously won't help if the machine was rebooted by a kernel that GRUB loaded.

Node:hiddenmenu, Next:timeout, Previous:fallback, Up:Menu-specific commands

hiddenmenu

hiddenmenu Command
Don't display the menu. If the command is used, no menu will be displayed on the control terminal, and the default entry will be booted after the timeout expired. The user can still request the menu to be displayed by pressing <ESC> before the timeout expires. See also Hidden menu interface.

Node:timeout, Next:title, Previous:hiddenmenu, Up:Menu-specific commands

timeout

timeout sec Command
Set a timeout, in sec seconds, before automatically booting the default entry (normally the first entry defined).

Node:title, Previous:timeout, Up:Menu-specific commands

title

title name ... Command
Start a new boot entry, and set its name to the contents of the rest of the line, starting with the first non-space character.

Node:General commands, Next:Command-line and menu entry commands, Previous:Menu-specific commands, Up:Commands

The list of general commands

Commands usable both in the menu and in the command-line.

  • bootp: Initialize a network device via BOOTP
  • color: Color the menu interface
  • device: Specify a file as a drive
  • dhcp: Initialize a network device via DHCP
  • hide: Hide a partition
  • ifconfig: Configure a network device manually
  • pager: Change the state of the internal pager
  • partnew: Make a primary partition
  • parttype: Change the type of a partition
  • password: Set a password for the menu interface
  • rarp: Initialize a network device via RARP
  • serial: Set up a serial device
  • setkey: Configure the key map
  • terminal: Choose a terminal
  • tftpserver: Specify a TFTP server
  • unhide: Unhide a partition

Node:bootp, Next:color, Up:General commands

bootp

bootp [--with-configfile] Command
Initialize a network device via the BOOTP protocol. This command is only available if GRUB is compiled with netboot support. See also Network.

If you specify --with-configfile to this command, GRUB will fetch and load a configuration file specified by your BOOTP server with the vendor tag 150.

Node:color, Next:device, Previous:bootp, Up:General commands

color

color normal [highlight] Command
Change the menu colors. The color normal is used for most lines in the menu (see Menu interface), and the color highlight is used to highlight the line where the cursor points. If you omit highlight, then the inverted color of normal is used for the highlighted line. The format of a color is foreground/background. foreground and background are symbolic color names. A symbolic color name must be one of these:
  • black
  • blue
  • green
  • cyan
  • red
  • magenta
  • brown
  • light-gray

    These below can be specified only for the foreground.

  • dark-gray
  • light-blue
  • light-green
  • light-cyan
  • light-red
  • light-magenta
  • yellow
  • white

But only the first eight names can be used for background. You can prefix blink- to foreground if you want a blinking foreground color.

This command can be used in the configuration file and on the command line, so you may write something like this in your configuration file:

# Set default colors.
color light-gray/blue black/light-gray

# Change the colors.
title OS-BS like
color magenta/blue black/magenta

Node:device, Next:dhcp, Previous:color, Up:General commands

device

device drive file Command
In the grub shell, specify the file file as the actual drive for a BIOS drive drive. You can use this command to create a disk image, and/or to fix the drives guessed by GRUB when GRUB fails to determine them correctly, like this:
grub> device (fd0) /floppy-image
grub> device (hd0) /dev/sd0

This command can be used only in the grub shell (see Invoking the grub shell).

Node:dhcp, Next:hide, Previous:device, Up:General commands

dhcp

dhcp [--with-configfile] Command
Initialize a network device via the DHCP protocol. Currently, this command is just an alias for bootp, since the two protocols are very similar. This command is only available if GRUB is compiled with netboot support. See also Network.

If you specify --with-configfile to this command, GRUB will fetch and load a configuration file specified by your DHCP server with the vendor tag 150.

Node:hide, Next:ifconfig, Previous:dhcp, Up:General commands

hide

hide partition Command
Hide the partition partition by setting the hidden bit in its partition type code. This is useful only when booting DOS or Windows and multiple primary FAT partitions exist in one disk. See also DOS/Windows.

Node:ifconfig, Next:pager, Previous:hide, Up:General commands

ifconfig

ifconfig [--server=server] [--gateway=gateway] [--mask=mask] [--address=address] Command
Configure the IP address, the netmask, the gateway, and the server address of a network device manually. The values must be in dotted decimal format, like 192.168.11.178. The order of the options is not important. This command shows current network configuration, if no option is specified. See also Network.

Node:pager, Next:partnew, Previous:ifconfig, Up:General commands

pager

pager [flag] Command
Toggle or set the state of the internal pager. If flag is on, the internal pager is enabled. If flag is off, it is disabled. If no argument is given, the state is toggled.

Node:partnew, Next:parttype, Previous:pager, Up:General commands

partnew

partnew part type from to Command
Create a new primary partition. part is a partition specification in GRUB syntax (see Naming convention); type is the partition type and must be a number in the range 0-0xff; from and to are the starting and ending sectors, expressed as an absolute sector number.

Node:parttype, Next:password, Previous:partnew, Up:General commands

parttype

parttype part type Command
Change the type of an existing partition. part is a partition specification in GRUB syntax (see Naming convention); type is the new partition type and must be a number in the range 0-0xff.

Node:password, Next:rarp, Previous:parttype, Up:General commands

password

password [--md5] passwd [new-config-file] Command
If used in the first section of a menu file, disable all interactive editing control (menu entry editor and command-line) and entries protected by the command lock. If the password passwd is entered, it loads the new-config-file as a new config file and restarts the GRUB Stage 2, if new-config-file is specified. Otherwise, GRUB will just unlock the privileged instructions. You can also use this command in the script section, in which case it will ask for the password, before continueing. The option --md5 tells GRUB that passwd is encrypted with md5crypt (see md5crypt).

Node:rarp, Next:serial, Previous:password, Up:General commands

rarp

rarp Command
Initialize a network device via the RARP protocol. This command is only available if GRUB is compiled with netboot support. See also Network.

Node:serial, Next:setkey, Previous:rarp, Up:General commands

serial

serial [--unit=unit] [--port=port] [--speed=speed] [--word=word] [--parity=parity] [--stop=stop] [--device=dev] Command
Initialize a serial device. unit is a number in the range 0-3 specifying which serial port to use; default is 0, that corresponds the port often called COM1. port is the I/O port where the UART is to be found; if specified it takes precedence over unit. speed is the transmission speed; default is 9600. word and stop are the number of data bits and stop bits. Data bits must be in the range 5-8 and stop bits are 1 or 2. Default is 8 data bits and one stop bit. parity is one of no, odd, even and defaults to no. The option --device can only be used in the grub shell and is used to specify the tty device to be used in the host operating system (see Invoking the grub shell).

The serial port is not used as a communication channel unless the terminal command is used (see terminal).

This command is only available if GRUB is compiled with serial support. See also Serial terminal.

Node:setkey, Next:terminal, Previous:serial, Up:General commands

setkey

setkey [to_key from_key] Command
Change the keyboard map. The key from_key is mapped to the key to_key. If no argument is specified, reset key mappings. Note that this command does not exchange the keys. If you want to exchange the keys, run this command again with the arguments exchanged, like this:
grub> setkey capslock control
grub> setkey control capslock

A key must be an alphabet, a digit, or one of these symbols: escape, exclam, at, numbersign, dollar, percent, caret, ampersand, asterisk, parenleft, parenright, minus, underscore, equal, plus, backspace, tab, bracketleft, braceleft, bracketright, braceright, enter, control, semicolon, colon, quote, doublequote, backquote, tilde, shift, backslash, bar, comma, less, period, greater, slash, question, alt, space, capslock, FX (X is a digit), and delete. This table describes to which character each of the symbols corresponds:

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

Node:terminal, Next:tftpserver, Previous:setkey, Up:General commands

terminal

terminal [--dumb] [--timeout=secs] [--lines=lines] [--silent] [console] [serial] [hercules] Command
Select a terminal for user interaction. The terminal is assumed to be VT100-compatible unless --dumb is specified. If both console and serial are specified, then GRUB will use the one where a key is entered first or the first when the timeout expires. If neither are specified, the current setting is reported. This command is only available if GRUB is compiled with serial support. See also Serial terminal.

This may not make sense for most users, but GRUB supports Hercules console as well. Hercules console is usable like the ordinary console, and the usage is quite similar to that for serial terminals: specify hercules as the argument.

The option --lines defines the number of lines in your terminal, and it is used for the internal pager function. If you don't specify this option, the number is assumed as 24.

The option --silent suppresses the message to prompt you to hit any key. This might be useful if your system has no terminal device.

Node:tftpserver, Next:unhide, Previous:terminal, Up:General commands

tftpserver

tftpserver ipaddr Command
Caution: This command exists only for backward compatibility. Use ifconfig (see ifconfig) instead.

Override a TFTP server address returned by a BOOTP/DHCP/RARP server. The argument ipaddr must be in dotted decimal format, like 192.168.0.15. This command is only available if GRUB is compiled with netboot support. See also Network.

Node:unhide, Previous:tftpserver, Up:General commands

unhide

unhide partition Command
Unhide the partition partition by clearing the hidden bit in its partition type code. This is useful only when booting DOS or Windows and multiple primary partitions exist in one disk. See also DOS/Windows.

Node:Command-line and menu entry commands, Previous:General commands, Up:Commands

The list of command-line and menu entry commands

These commands are usable in the command-line and in menu entries. If you forget a command, you can run the command help (see help).

  • blocklist: Get the block list notation of a file
  • boot: Start up your operating system
  • cat: Show the contents of a file
  • chainloader: Chain-load another boot loader
  • cmp: Compare two files
  • configfile: Load a configuration file
  • debug: Toggle the debug flag
  • displayapm: Display APM information
  • displaymem: Display memory configuration
  • embed: Embed Stage 1.5
  • find: Find a file
  • fstest: Test a filesystem
  • geometry: Manipulate the geometry of a drive
  • halt: Shut down your computer
  • help: Show help messages
  • impsprobe: Probe SMP
  • initrd: Load an initrd
  • install: Install GRUB
  • ioprobe: Probe I/O ports used for a drive
  • kernel: Load a kernel
  • lock: Lock a menu entry
  • makeactive: Make a partition active
  • map: Map a drive to another
  • md5crypt: Encrypt a password in MD5 format
  • module: Load a module
  • modulenounzip: Load a module without decompression
  • pause: Wait for a key press
  • quit: Exit from the grub shell
  • reboot: Reboot your computer
  • read: Read data from memory
  • root: Set GRUB's root device
  • rootnoverify: Set GRUB's root device without mounting
  • savedefault: Save current entry as the default entry
  • setup: Set up GRUB's installation automatically
  • testload: Load a file for testing a filesystem
  • testvbe: Test VESA BIOS EXTENSION
  • uppermem: Set the upper memory size
  • vbeprobe: Probe VESA BIOS EXTENSION

Node:blocklist, Next:boot, Up:Command-line and menu entry commands

blocklist

blocklist file Command
Print the block list notation of the file file. See Block list syntax.

Node:boot, Next:cat, Previous:blocklist, Up:Command-line and menu entry commands

boot

boot Command
Boot the OS/chain-loader which has been loaded. Only necessary if running the fully interactive command-line (it is implicit at the end of a menu entry).

Node:cat, Next:chainloader, Previous:boot, Up:Command-line and menu entry commands

cat

cat file Command
Display the contents of the file file. This command may be useful to remind you of your OS's root partition:
grub> cat /etc/fstab

Node:chainloader, Next:cmp, Previous:cat, Up:Command-line and menu entry commands

chainloader

chainloader [--force] file Command
Load file as a chain-loader. Like any other file loaded by the filesystem code, it can use the blocklist notation to grab the first sector of the current partition with +1. If you specify the option --force, then load file forcibly, whether it has a correct signature or not. This is required when you want to load a defective boot loader, such as SCO UnixWare 7.1 (see SCO UnixWare).

Node:cmp, Next:configfile, Previous:chainloader, Up:Command-line and menu entry commands

cmp

cmp file1 file2 Command
Compare the file file1 with the file file2. If they differ in size, print the sizes like this:
Differ in size: 0x1234 [foo], 0x4321 [bar]

If the sizes are equal but the bytes at an offset differ, then print the bytes like this:

Differ at the offset 777: 0xbe [foo], 0xef [bar]

If they are completely identical, nothing will be printed.

Node:configfile, Next:debug, Previous:cmp, Up:Command-line and menu entry commands

configfile

configfile file Command
Load file as a configuration file.

Node:debug, Next:displayapm, Previous:configfile, Up:Command-line and menu entry commands

debug

debug Command
Toggle debug mode (by default it is off). When debug mode is on, some extra messages are printed to show disk activity. This global debug flag is mainly useful for GRUB developers when testing new code.

Node:displayapm, Next:displaymem, Previous:debug, Up:Command-line and menu entry commands

displayapm

displayapm Command
Display APM BIOS information.

Node:displaymem, Next:embed, Previous:displayapm, Up:Command-line and menu entry commands

displaymem

displaymem Command
Display what GRUB thinks the system address space map of the machine is, including all regions of physical RAM installed. GRUB's upper/lower memory display uses the standard BIOS interface for the available memory in the first megabyte, or lower memory, and a synthesized number from various BIOS interfaces of the memory starting at 1MB and going up to the first chipset hole for upper memory (the standard PC upper memory interface is limited to reporting a maximum of 64MB).

Node:embed, Next:find, Previous:displaymem, Up:Command-line and menu entry commands

embed

embed stage1_5 device Command
Embed the Stage 1.5 stage1_5 in the sectors after the MBR if device is a drive, or in the boot loader area if device is a FFS partition or a ReiserFS partition.8 Print the number of sectors which stage1_5 occupies, if successful.

Usually, you don't need to run this command directly. See setup.

Node:find, Next:fstest, Previous:embed, Up:Command-line and menu entry commands

find

find filename Command
Search for the file name filename in all of partitions and print the list of the devices which contain the file. The file name filename should be an absolute file name like /boot/grub/stage1.

Node:fstest, Next:geometry, Previous:find, Up:Command-line and menu entry commands

fstest

fstest Command
Toggle filesystem test mode. Filesystem test mode, when turned on, prints out data corresponding to all the device reads and what values are being sent to the low-level routines. The format is <partition-offset-sector, byte-offset, byte-length> for high-level reads inside a partition, and [disk-offset-sector] for low-level sector requests from the disk. Filesystem test mode is turned off by any use of the install (see install) or testload (see testload) commands.

Node:geometry, Next:halt, Previous:fstest, Up:Command-line and menu entry commands

geometry

geometry drive [cylinder head sector [total_sector]] Command
Print the information for the drive drive. In the grub shell, you can set the geometry of the drive arbitrarily. The number of the cylinders, the one of the heads, the one of the sectors and the one of the total sectors are set to CYLINDER, HEAD, SECTOR and TOTAL_SECTOR, respectively. If you omit TOTAL_SECTOR, then it will be calculated based on the C/H/S values automatically.

Node:halt, Next:help, Previous:geometry, Up:Command-line and menu entry commands

halt

halt --no-apm Command
The command halts the computer. If the --no-apm option is specified, no APM BIOS call is performed. Otherwise, the computer is shut down using APM.

Node:help, Next:impsprobe, Previous:halt, Up:Command-line and menu entry commands

help

help --all [pattern ...] Command
Display helpful information about builtin commands. If you do not specify pattern, this command shows short descriptions of most of available commands. If you specify the option --all to this command, short descriptions of rarely used commands (such as testload) are displayed as well.

If you specify any patterns, it displays longer information about each of the commands which match those patterns.

Node:impsprobe, Next:initrd, Previous:help, Up:Command-line and menu entry commands

impsprobe

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

Node:initrd, Next:install, Previous:impsprobe, Up:Command-line and menu entry commands

initrd

initrd file ... Command
Load an initial ramdisk for a Linux format boot image and set the appropriate parameters in the Linux setup area in memory. See also GNU/Linux.

Node:install, Next:ioprobe, Previous:initrd, Up:Command-line and menu entry commands

install

install [--force-lba] [--stage2=os_stage2_file] stage1_file [d] dest_dev stage2_file [addr] [p] [config_file] [real_config_file] Command
This command is fairly complex, and you should not use this command unless you are familiar with GRUB. Use setup (see setup) instead.

In short, it will perform a full install presuming the Stage 2 or Stage 1.59 is in its final install location.

In slightly more detail, it will load stage1_file, validate that it is a GRUB Stage 1 of the right version number, install a blocklist for loading stage2_file as a Stage 2. If the option d is present, the Stage 1 will always look for the actual disk stage2_file was installed on, rather than using the booting drive. The Stage 2 will be loaded at address addr, which must be 0x8000 for a true Stage 2, and 0x2000 for a Stage 1.5. If addr is not present, GRUB will determine the address automatically. It then writes the completed Stage 1 to the first block of the device dest_dev. If the options p or config_file are present, then it reads the first block of stage2, modifies it with the values of the partition stage2_file was found on (for p) or places the string config_file into the area telling the stage2 where to look for a configuration file at boot time. Likewise, if real_config_file is present and stage2_file is a Stage 1.5, then the Stage 2 config_file is patched with the configuration file name real_config_file. This command preserves the DOS BPB (and for hard disks, the partition table) of the sector the Stage 1 is to be installed into.

Caution: Several buggy BIOSes don't pass a booting drive properly when booting from a hard disk drive. Therefore, you will have to specify the option d, whether your Stage2 resides at the booting drive or not, if you have such a BIOS unfortunately. We know these are defective in that:

Fujitsu LifeBook 400 BIOS version 31J0103A
HP Vectra XU 6/200 BIOS version GG.06.11

Caution2: A number of BIOSes don't return a correct LBA support bitmap even if they do have the support. So GRUB provides a solution to ignore the wrong bitmap, that is, the option --force-lba. Don't use this option if you know that your BIOS doesn't have LBA support.

Caution3: You must specify the option --stage2 in the grub shell, if you cannot unmount the filesystem where your stage2 file resides. The argument should be the file name in your operating system.

Node:ioprobe, Next:kernel, Previous:install, Up:Command-line and menu entry commands

ioprobe

ioprobe drive Command
Probe I/O ports used for the drive drive. This command will list the I/O ports on the screen. For technical information, See Internals.

Node:kernel, Next:lock, Previous:ioprobe, Up:Command-line and menu entry commands

kernel

kernel [--type=type] [--no-mem-option] file ... Command
Attempt to load the primary boot image (Multiboot a.out or ELF, Linux zImage or bzImage, FreeBSD a.out, NetBSD a.out, etc.) from file. The rest of the line is passed verbatim as the kernel command-line. Any modules must be reloaded after using this command.

This command also accepts the option --type so that you can specify the kernel type of file explicitly. The argument type must be one of these: netbsd, freebsd, openbsd, linux, biglinux, and multiboot. However, you need to specify it only if you want to load a NetBSD ELF kernel, because GRUB can automatically determine a kernel type in the other cases, quite safely.

The option --no-mem-option is effective only for Linux. If the option is specified, GRUB doesn't pass the option mem= to the kernel.

Node:lock, Next:makeactive, Previous:kernel, Up:Command-line and menu entry commands

lock

lock Command
Prevent normal users from executing arbitrary menu entries. You must use the command password if you really want this command to be useful (see password).

This command is used in a menu, as shown in this example:

title This entry is too dangerous to be executed by normal users
lock
root (hd0,a)
kernel /no-security-os

See also Security.

Node:makeactive, Next:map, Previous:lock, Up:Command-line and menu entry commands

makeactive

makeactive Command
Set the active partition on the root disk to GRUB's root device. This command is limited to primary PC partitions on a hard disk.

Node:map, Next:md5crypt, Previous:makeactive, Up:Command-line and menu entry commands

map

map to_drive from_drive Command
Map the drive from_drive to the drive to_drive. This is necessary when you chain-load some operating systems, such as DOS, if such an OS resides at a non-first drive. Here is an example:
grub> map (hd0) (hd1)
grub> map (hd1) (hd0)

The example exchanges the order between the first hard disk and the second hard disk. See also DOS/Windows.

Node:md5crypt, Next:module, Previous:map, Up:Command-line and menu entry commands

md5crypt

md5crypt Command
Prompt to enter a password, and encrypt it in MD5 format. The encrypted password can be used with the command password (see password). See also Security.

Node:module, Next:modulenounzip, Previous:md5crypt, Up:Command-line and menu entry commands

module

module file ... Command
Load a boot module file for a Multiboot format boot image (no interpretation of the file contents are made, so that user of this command must know what the kernel in question expects). The rest of the line is passed as the module command-line, like the kernel command. You must load a Multiboot kernel image before loading any module. See also modulenounzip.

Node:modulenounzip, Next:pause, Previous:module, Up:Command-line and menu entry commands

modulenounzip

modulenounzip file ... Command
The same as module (see module), except that automatic decompression is disabled.

Node:pause, Next:quit, Previous:modulenounzip, Up:Command-line and menu entry commands

pause

pause message ... Command
Print the message, then wait until a key is pressed. Note that placing <^G> (ASCII code 7) in the message will cause the speaker to emit the standard beep sound, which is useful when prompting the user to change floppies.

Node:quit, Next:reboot, Previous:pause, Up:Command-line and menu entry commands

quit

quit Command
Exit from the grub shell grub (see Invoking the grub shell). This command can be used only in the grub shell.

Node:reboot, Next:read, Previous:quit, Up:Command-line and menu entry commands

reboot

reboot Command
Reboot the computer.

Node:read, Next:root, Previous:reboot, Up:Command-line and menu entry commands

read

read addr Command
Read a 32-bit value from memory at address addr and display it in hex format.

Node:root, Next:rootnoverify, Previous:read, Up:Command-line and menu entry commands

root

root device [hdbias] Command
Set the current root device to the device device, then attempt to mount it to get the partition size (for passing the partition descriptor in ES:ESI, used by some chain-loaded boot loaders), the BSD drive-type (for booting BSD kernels using their native boot format), and correctly determine the PC partition where a BSD sub-partition is located. The optional hdbias parameter is a number to tell a BSD kernel how many BIOS drive numbers are on controllers before the current one. For example, if there is an IDE disk and a SCSI disk, and your FreeBSD root partition is on the SCSI disk, then use a 1 for hdbias.

See also rootnoverify.

Node:rootnoverify, Next:savedefault, Previous:root, Up:Command-line and menu entry commands

rootnoverify

rootnoverify device [hdbias] Command
Similar to root (see root), but don't attempt to mount the partition. This is useful for when an OS is outside of the area of the disk that GRUB can read, but setting the correct root device is still desired. Note that the items mentioned in root above which derived from attempting the mount will not work correctly.

Node:savedefault, Next:setup, Previous:rootnoverify, Up:Command-line and menu entry commands

savedefault

savedefault Command
Save the current menu entry as a default entry. Here is an example:
default saved
timeout 10

title GNU/Linux
root (hd0,0)
kernel /boot/vmlinuz root=/dev/sda1 vga=ext
initrd /boot/initrd
savedefault

title FreeBSD
root (hd0,a)
kernel /boot/loader
savedefault

With this configuration, GRUB will choose the entry booted previously as the default entry. See also default.

Node:setup, Next:testload, Previous:savedefault, Up:Command-line and menu entry commands

setup

setup [--force-lba] [--stage2=os_stage2_file] [--prefix=dir] install_device [image_device] Command
Set up the installation of GRUB automatically. This command uses the more flexible command install (see install) in the backend and installs GRUB into the device install_device. If image_device is specified, then find the GRUB images (see Images) in the device image_device, otherwise use the current root device, which can be set by the command root. If install_device is a hard disk, then embed a Stage 1.5 in the disk if possible.

The option --prefix specifies the directory under which GRUB images are put. If it is not specified, GRUB automatically searches them in /boot/grub and /grub.

The options --force-lba and --stage2 are just passed to install if specified. See install, for more information.

Node:testload, Next:testvbe, Previous:setup, Up:Command-line and menu entry commands

testload

testload file Command
Read the entire contents of file in several different ways and compares them, to test the filesystem code. The output is somewhat cryptic, but if no errors are reported and the final i=X, filepos=Y reading has X and Y equal, then it is definitely consistent, and very likely works correctly subject to a consistent offset error. If this test succeeds, then a good next step is to try loading a kernel.

Node:testvbe, Next:uppermem, Previous:testload, Up:Command-line and menu entry commands

testvbe

testvbe mode Command
Test the VESA BIOS EXTENSION mode mode. This command will switch your video card to the graphics mode, and show an endless animation. Hit any key to return. See also vbeprobe.

Node:uppermem, Next:vbeprobe, Previous:testvbe, Up:Command-line and menu entry commands

uppermem

uppermem kbytes Command
Force GRUB to assume that only kbytes kilobytes of upper memory are installed. Any system address range maps are discarded.

Caution: This should be used with great caution, and should only be necessary on some old machines. GRUB's BIOS probe can pick up all RAM on all new machines the author has ever heard of. It can also be used for debugging purposes to lie to an OS.

Node:vbeprobe, Previous:uppermem, Up:Command-line and menu entry commands

vbeprobe

vbeprobe [mode] Command
Probe VESA BIOS EXTENSION information. If the mode mode is specified, show only the information about mode. Otherwise, this command lists up available VBE modes on the screen. See also testvbe.

Node:Troubleshooting, Next:Invoking the grub shell, Previous:Commands, Up:Top

Error messages reported by GRUB

This chapter describes error messages reported by GRUB when you encounter trouble. See Invoking the grub shell, if your problem is specific to the grub shell.

  • Stage1 errors: Errors reported by the Stage 1
  • Stage1.5 errors: Errors reported by the Stage 1.5
  • Stage2 errors: Errors reported by the Stage 2

Node:Stage1 errors, Next:Stage1.5 errors, Up:Troubleshooting

Errors reported by the Stage 1

The general way that the Stage 1 handles errors is to print an error string and then halt. Pressing <CTRL>-<ALT>-<DEL> will reboot.

The following is a comprehensive list of error messages for the Stage 1:

Hard Disk Error
The stage2 or stage1.5 is being read from a hard disk, and the attempt to determine the size and geometry of the hard disk failed.
Floppy Error
The stage2 or stage1.5 is being read from a floppy disk, and the attempt to determine the size and geometry of the floppy disk failed. It's listed as a separate error since the probe sequence is different than for hard disks.
Read Error
A disk read error happened while trying to read the stage2 or stage1.5.
Geom Error
The location of the stage2 or stage1.5 is not in the portion of the disk supported directly by the BIOS read calls. This could occur because the BIOS translated geometry has been changed by the user or the disk is moved to another machine or controller after installation, or GRUB was not installed using itself (if it was, the Stage 2 version of this error would have been seen during that process and it would not have completed the install).

Node:Stage1.5 errors, Next:Stage2 errors, Previous:Stage1 errors, Up:Troubleshooting

Errors reported by the Stage 1.5

The general way that the Stage 1.5 handles errors is to print an error number in the form Error num and then halt. Pressing <CTRL>-<ALT>-<DEL> will reboot.

The error numbers correspond to the errors reported by Stage 2. See Stage2 errors.

Node:Stage2 errors, Previous:Stage1.5 errors, Up:Troubleshooting

Errors reported by the Stage 2

The general way that the Stage 2 handles errors is to abort the operation in question, print an error string, then (if possible) either continue based on the fact that an error occurred or wait for the user to deal with the error.

The following is a comprehensive list of error messages for the Stage 2 (error numbers for the Stage 1.5 are listed before the colon in each description):

1 : Filename must be either an absolute filename or blocklist
This error is returned if a file name is requested which doesn't fit the syntax/rules listed in the Filesystem.
2 : Bad file or directory type
This error is returned if a file requested is not a regular file, but something like a symbolic link, directory, or FIFO.
3 : Bad or corrupt data while decompressing file
This error is returned if the run-length decompression code gets an internal error. This is usually from a corrupt file.
4 : Bad or incompatible header in compressed file
This error is returned if the file header for a supposedly compressed file is bad.
5 : Partition table invalid or corrupt
This error is returned if the sanity checks on the integrity of the partition table fail. This is a bad sign.
6 : Mismatched or corrupt version of stage1/stage2
This error is returned if the install command is pointed to incompatible or corrupt versions of the stage1 or stage2. It can't detect corruption in general, but this is a sanity check on the version numbers, which should be correct.
7 : Loading below 1MB is not supported
This error is returned if the lowest address in a kernel is below the 1MB boundary. The Linux zImage format is a special case and can be handled since it has a fixed loading address and maximum size.
8 : Kernel must be loaded before booting
This error is returned if GRUB is told to execute the boot sequence without having a kernel to start.
9 : Unknown boot failure
This error is returned if the boot attempt did not succeed for reasons which are unknown.
10 : Unsupported Multiboot features requested
This error is returned when the Multiboot features word in the Multiboot header requires a feature that is not recognized. The point of this is that the kernel requires special handling which GRUB is likely unable to provide.
11 : Unrecognized device string
This error is returned if a device string was expected, and the string encountered didn't fit the syntax/rules listed in the Filesystem.
12 : Invalid device requested
This error is returned if a device string is recognizable but does not fall under the other device errors.
13 : Invalid or unsupported executable format
This error is returned if the kernel image being loaded is not recognized as Multiboot or one of the supported native formats (Linux zImage or bzImage, FreeBSD, or NetBSD).
14 : Filesystem compatibility error, cannot read whole file
Some of the filesystem reading code in GRUB has limits on the length of the files it can read. This error is returned when the user runs into such a limit.
15 : File not found
This error is returned if the specified file name cannot be found, but everything else (like the disk/partition info) is OK.
16 : Inconsistent filesystem structure
This error is returned by the filesystem code to denote an internal error caused by the sanity checks of the filesystem structure on disk not matching what it expects. This is usually caused by a corrupt filesystem or bugs in the code handling it in GRUB.
17 : Cannot mount selected partition
This error is returned if the partition requested exists, but the filesystem type cannot be recognized by GRUB.
18 : Selected cylinder exceeds maximum supported by BIOS
This error is returned when a read is attempted at a linear block address beyond the end of the BIOS translated area. This generally happens if your disk is larger than the BIOS can handle (512MB for (E)IDE disks on older machines or larger than 8GB in general).
19 : Linux kernel must be loaded before initrd
This error is returned if the initrd command is used before loading a Linux kernel. Similar to the above error, it only makes sense in that case anyway.
20 : Multiboot kernel must be loaded before modules
This error is returned if the module load command is used before loading a Multiboot kernel. It only makes sense in this case anyway, as GRUB has no idea how to communicate the presence of location of such modules to a non-Multiboot-aware kernel.
21 : Selected disk does not exist
This error is returned if the device part of a device- or full file name refers to a disk or BIOS device that is not present or not recognized by the BIOS in the system.
22 : No such partition
This error is returned if a partition is requested in the device part of a device- or full file name which isn't on the selected disk.
23 : Error while parsing number
This error is returned if GRUB was expecting to read a number and encountered bad data.
24 : Attempt to access block outside partition
This error is returned if a linear block address is outside of the disk partition. This generally happens because of a corrupt filesystem on the disk or a bug in the code handling it in GRUB (it's a great debugging tool).
25 : Disk read error
This error is returned if there is a disk read error when trying to probe or read data from a particular disk.
26 : Too many symbolic links
This error is returned if the link count is beyond the maximum (currently 5), possibly the symbolic links are looped.
27 : Unrecognized command
This error is returned if an unrecognized command is entered into the command-line or in a boot sequence section of a configuration file and that entry is selected.
28 : Selected item cannot fit into memory
This error is returned if a kernel, module, or raw file load command is either trying to load its data such that it won't fit into memory or it is simply too big.
29 : Disk write error
This error is returned if there is a disk write error when trying to write to a particular disk. This would generally only occur during an install of set active partition command.
30 : Invalid argument
This error is returned if an argument specified to a command is invalid.
31 : File is not sector aligned
This error may occur only when you access a ReiserFS partition by block-lists (e.g. the command install). In this case, you should mount the partition with the -o notail option.
32 : Must be authenticated
This error is returned if you try to run a locked entry. You should enter a correct password before running such an entry.
33 : Serial device not configured
This error is returned if you try to change your terminal to a serial one before initializing any serial device.
34 : No spare sectors on the disk
This error is returned if a disk doesn't have enough spare space. This happens when you try to embed Stage 1.5 into the unused sectors after the MBR, but the first partition starts right after the MBR or they are used by EZ-BIOS.

Node:Invoking the grub shell, Next:Invoking grub-install, Previous:Troubleshooting, Up:Top

Invoking the grub shell

This chapter documents the grub shell grub. Note that the grub shell is an emulator; it doesn't run under the native environment, so it sometimes does something wrong. Therefore, you shouldn't trust it too much. If there is anything wrong with it, don't hesitate to try the native GRUB environment, especially when it guesses a wrong map between BIOS drives and OS devices.

  • Basic usage: How to use the grub shell
  • Installation under UNIX: How to install GRUB via grub
  • Device map: The map between BIOS drives and OS devices

Node:Basic usage, Next:Installation under UNIX, Up:Invoking the grub shell

Introduction into the grub shell

You can use the command grub for installing GRUB under your operating systems and for a testbed when you add a new feature into GRUB or when fix a bug. grub is almost the same as the Stage 2, and, in fact, it shares the source code with the Stage 2 and you can use the same commands (see Commands) in grub. It is emulated by replacing BIOS calls with UNIX system calls and libc functions.

The command grub accepts the following options:

--help
Print a summary of the command-line options and exit.
--version
Print the version number of GRUB and exit.
--verbose
Print some verbose messages for debugging purpose.
--device-map=file
Use the device map file file. The format is described in Device map.
--no-floppy
Do not probe any floppy drive. This option has no effect if the option --device-map is specified (see Device map).
--probe-second-floppy
Probe the second floppy drive. If this option is not specified, the grub shell does not probe it, as that sometimes takes a long time. If you specify the device map file (see Device map), the grub shell just ignores this option.
--config-file=file
Read the configuration file file instead of /boot/grub/menu.lst. The format is the same as the normal GRUB syntax. See Filesystem, for more information.
--boot-drive=drive
Set the stage2 boot_drive to drive. This argument should be an integer (decimal, octal or hexadecimal).
--install-partition=par
Set the stage2 install_partition to par. This argument should be an integer (decimal, octal or hexadecimal).
--no-config-file
Do not use the configuration file even if it can be read.
--no-curses
Do not use the curses interface even if it is available.
--batch
This option has the same meaning as --no-config-file --no-curses.
--read-only
Disable writing to any disk.
--hold
Wait until a debugger will attach. This option is useful when you want to debug the startup code.

Node:Installation under UNIX, Next:Device map, Previous:Basic usage, Up:Invoking the grub shell

How to install GRUB via grub

The installation procedure is the same as under the native Stage 2. See Installation, for more information. The command grub-specific information is described here.

What you should be careful about is buffer cache. grub makes use of raw devices instead of filesystems that your operating systems serve, so there exists a potential problem that some cache inconsistency may corrupt your filesystems. What we recommend is:

  • If you can unmount drives to which GRUB may write any amount of data, unmount them before running grub.
  • If a drive cannot be unmounted but can be mounted with the read-only flag, mount it in read-only mode. That should be secure.
  • If a drive must be mounted with the read-write flag, make sure that any activity is not being done on it during running the command grub.
  • Reboot your operating system as soon as possible. Probably that is not required if you follow these rules above, but reboot is the most secure way.

In addition, enter the command quit when you finish the installation. That is very important because quit makes the buffer cache consistent. Do not push <C-c>.

If you want to install GRUB non-interactively, specify --batch option in the command-line. This is a simple example:

#!/bin/sh

# Use /usr/sbin/grub if you are on an older system.
/sbin/grub --batch <<EOT 1>/dev/null 2>/dev/null
root (hd0,0)
setup (hd0)
quit
EOT

Node:Device map, Previous:Installation under UNIX, Up:Invoking the grub shell

The map between BIOS drives and OS devices

When you specify the option --device-map (see Basic usage), the grub shell creates the device map file automatically unless it already exists. The file name /boot/grub/device.map is preferred.

If the device map file exists, the grub shell reads it to map BIOS drives to OS devices. This file consists of lines like this:

device file

device is a drive, which syntax is the same as the one in GRUB (see Device syntax), and file is an OS's file, which is normally a device file.

The reason why the grub shell gives you the device map file is that it cannot guess the map between BIOS drives and OS devices correctly in some environments. For example, if you exchange the boot sequence between IDE and SCSI in your BIOS, it mistakes the order.

Thus, edit the file if the grub shell makes a mistake. You can put any comments in the file if needed, as the grub shell assumes that a line is just a comment if the first character is #.

Node:Invoking grub-install, Next:Invoking grub-md5-crypt, Previous:Invoking the grub shell, Up:Top

Invoking grub-install

The program grub-install installs GRUB on your drive by the grub shell (see Invoking the grub shell). You must specify the device name on which you want to install GRUB, like this:

grub-install install_device

The device name install_device is an OS device name or a GRUB device name.

grub-install accepts the following options:

--help
Print a summary of the command-line options and exit.
--version
Print the version number of GRUB and exit.
--force-lba
Force GRUB to use LBA mode even for a buggy BIOS. Use this option only if your BIOS doesn't work in LBA mode even though it supports LBA mode.
--root-directory=dir
Install GRUB images under the directory dir instead of the root directory. This option is useful when you want to install GRUB into a separate partition or a removable disk. Here is an example when you have a separate boot partition which is mounted on /boot:
grub-install --root-directory=/boot '(hd0)'

--grub-shell=file
Use file as the grub shell. You can append arbitrary options to file after the file name, like this:
grub-install --grub-shell="grub --read-only" /dev/fd0

--recheck
Recheck the device map, even if /boot/grub/device.map already exists. You should use this option whenever you add/remove a disk into/from your computer.

Node:Invoking grub-md5-crypt, Next:Invoking mbchk, Previous:Invoking grub-install, Up:Top

Invoking grub-md5-crypt

The program grub-md5-crypt encrypts a password in MD5 format. This is just a frontend of the grub shell (see Invoking the grub shell). Passwords encrypted by this program can be used with the command password (see password).

grub-md5-crypt accepts the following options:

--help
Print a summary of the command-line options and exit.
--version
Print the version information and exit.
--grub-shell=file
Use file as the grub shell.

Node:Invoking mbchk, Next:FAQ, Previous:Invoking grub-md5-crypt, Up:Top

Invoking mbchk

The program mbchk checks for the format of a Multiboot kernel. We recommend using this program before booting your own kernel by GRUB.

mbchk accepts the following options:

--help
Print a summary of the command-line options and exit.
--version
Print the version number of GRUB and exit.
--quiet
Suppress all normal output.

Node:FAQ, Next:Obtaining and Building GRUB, Previous:Invoking mbchk, Up:Top

Frequently asked questions

How does GNU GRUB differ from Erich's original GRUB?
GNU GRUB is the successor of Erich's great GRUB. He couldn't work on GRUB because of some other tasks, so the current maintainers Yoshinori K. Okuji and Gordon Matzigkeit took over the maintainership, and opened the development in order for everybody to participate it.

Technically speaking, GNU GRUB has many features that are not seen in the original GRUB. For example, GNU GRUB can be installed on UNIX-like operating system (such as GNU/Hurd) via the grub shell /sbin/grub (or /usr/sbin/grub on older systems), it supports Logical Block Address (LBA) mode that solves the 1024 cylinders problem, and <TAB> completes a file name when it's unique. Of course, many bug fixes are done as well, so it is recommended to use GNU GRUB.

Can GRUB boot my operating system from over 8GB hard disks?
That depends on your BIOS and your operating system. You must make sure that your drive is accessible in LBA mode. Generally, that is configurable in BIOS setting utility. Read the manual for your BIOS for more information.

Furthermore, some operating systems (i.e. DOS) cannot access any large disk, so the problem is not solved by any kind of boot loader. GNU/Hurd and GNU/Linux can surely boot from such a large disk.

Can I put Stage2 into a partition which is over 1024 cylinders?
Yes, if your BIOS supports the LBA mode.
How to create a GRUB boot floppy with the menu interface?
The easiest way is:

  1. Create filesystem in your floppy disk. For example:
    $ mke2fs /dev/fd0
  2. Mount it on somewhere, say, /mnt.
  3. Copy the GRUB images to /mnt/boot/grub. Only stage1, stage2 and menu.lst are necessary. You may not copy stage1.5s.
  4. Run the following command (substitute /usr/sbin/grub for /sbin/grub if you are using an older system):
    $ /sbin/grub --batch <<EOT
root (fd0)
setup (fd0)
quit
EOT

How to specify a partition?
See Device syntax.
GRUB does not recognize my GNU/Hurd partition.
I don't know why, but the authors of FDISK programs have assigned the partition type 0x63 to the GNU Hurd incorrectly. So use 0x83 if the partition contains ext2fs filesystem, and use 0xA5 if the partition contains ffs filesystem, whether the partition owner is the Hurd or not. We will use 0x63 for the GNU Hurd filesystem that has not been implemented yet.
I've installed a recent version of binutils, but GRUB still crashes.
Please check for the version of your binutils by this command:
ld -v

This will show two versions, but only the latter is important. If the version is identical with what you have installed, the installation was not bad.

Well, please try:

gcc -Wl,-v 2>&1 | grep "GNU ld"

If this is not identical with the result above, you should specify the directory where you have installed binutils for the script configure, like this:

./configure --with-binutils=/usr/local/bin

If you follow the instructions above but GRUB still crashes, probably there is a serious bug in GRUB. See Reporting bugs.

GRUB hangs up when accessing my SCSI disk.
Check if you have turned on the support for INT 13 extension (LBA). If so, disable the support and see if GRUB can now access your SCSI disk. This will make it clear that your SCSI BIOS sucks.

For now, we know the following doesn't provide working LBA mode:

Adaptec AIC-7880

In the case where you have such a SCSI controller unfortunately, you cannot use the LBA mode, though GRUB still works fine in the CHS mode (so the well-known 1024 cylinders problem comes again to you).

Caution: Actually it has not been verified yet if this bug is due to the SCSI BIOS or GRUB itself, frankly speaking. Because the developers haven't seen it by their own eyes. This is why it is desirable that you investigate the cause seriously if you have the skill.

How can I specify an arbitrary memory size to Linux?
Pass a mem= option to your Linux kernel, like this:
grub> kernel /vmlinuz mem=128M

You may pass other options in the same way. See See GNU/Linux, for more details.

I have a separate boot partition and GRUB doesn't recognize it.
This is often reported as a bug, but this is not a bug really. This is a feature.

Because GRUB is a boot loader and it normally runs under no operating system, it doesn't know where a partition is mounted under your operating systems. So, if you have the partition /boot and you install GRUB images into the directory /boot/grub, GRUB recognizes that the images lies under the directory /grub but not /boot/grub. That's fine, since there is no guarantee that all of your operating systems mount the same partition as /boot.

There are several solutions for this situation.

  1. Install GRUB into the directory /boot/boot/grub instead of /boot/grub. This may sound ugly but should work fine.
  2. Create a symbolic link before installing GRUB, like cd /boot && ln -s . boot. This works only if the filesystem of the boot partition supports symbolic links and GRUB supports the feature as well.
  3. Install GRUB with the command install, to specify the paths of GRUB images explicitly. Here is an example:
    grub> root (hd0,1)
grub> install /grub/stage1 d (hd0) /grub/stage2 p /grub/menu.lst

How to uninstall GRUB from my hard disk drive?
There is no concept uninstall in boot loaders, because if you uninstall a boot loader, an unbootable machine would simply remain. So all you need to do is overwrite another boot loader you like to your disk, that is, install the boot loader without uninstalling GRUB.

For example, if you want to install the boot loader for Windows, just run FDISK /MBR on Windows. If you want to install LILO10, run /sbin/lilo on GNU/Linux.

GRUB hangs when accessing my large IDE disk.
If your disk is bigger than 32GB, probably updating your mainboard BIOS will solve your problem. This bug is well-known and most vendors should provide fixed versions. For example, if you have ASUS-P3BF, upgrading the BIOS to V1007beta1 or later can fix it. Please ask your vendor, for more information.
Why don't Linux, FreeBSD, NetBSD, etc. become Multiboot-compliant?
Please ask the relevant maintainers. If all free kernels were Multiboot-compliant (see Multiboot Specification), the world would be an utopia...

Node:Obtaining and Building GRUB, Next:Reporting bugs, Previous:FAQ, Up:Top

How to obtain and build GRUB

Caution: GRUB requires binutils-2.9.1.0.23 or later because the GNU assembler has been changed so that it can produce real 16bits machine code between 2.9.1 and 2.9.1.0.x. See http://sources.redhat.com/binutils/, to obtain information on how to get the latest version.

GRUB is available from the GNU alpha archive site ftp://alpha.gnu.org/gnu/grub or any of its mirrors. The file will be named grub-version.tar.gz. The current version is 0.92, so the file you should grab is: ftp://alpha.gnu.org/gnu/grub/grub-0.92.tar.gz

To unbundle GRUB use the instruction:

zcat grub-0.92.tar.gz | tar xvf -

which will create a directory called grub-0.92 with all the sources. You can look at the file INSTALL for detailed instructions on how to build and install GRUB, but you should be able to just do:

cd grub-0.92
./configure
make install

This will install the grub shell grub (see Invoking the grub shell), the Multiboot checker mbchk (see Invoking mbchk), and the GRUB images. This will also install the GRUB manual.

Also, the latest version is available from the CVS. The repository is:

:pserver:anoncvs@subversions.gnu.org:/cvsroot/grub

and the module is:

grub

The password for anoncvs is empty. So the instruction is:

cvs -d :pserver:anoncvs@subversions.gnu.org:/cvsroot/grub login
Password: <ENTER>
cvs -d :pserver:anoncvs@subversions.gnu.org:/cvsroot/grub co grub

Node:Reporting bugs, Next:Future, Previous:Obtaining and Building GRUB, Up:Top

Reporting bugs

This is the guideline of how to report bugs. Take a look at this list below before you send e-mail to bug-grub@gnu.org:

  1. Before unsettled, read this manual through and through, in particular See FAQ.
  2. Always mention the information on your GRUB. The version number and the configuration are quite important. If you build it yourself, write the options specified to the configure script and your operating system, including the versions of gcc and binutils.
  3. If you get troubled with the installation, inform us of how you installed GRUB. Don't omit error messages, if any. Just GRUB hangs up when it boots is not enough.

    The information on your hardware is also essential. These are especially important: the geometries and the partition tables of your hard disk drives and your BIOS.

  4. If GRUB cannot boot your operating system, write down all on the screen. Don't paraphrase them, like The foo OS crashes with GRUB, even though it can boot with the bar boot loader fine. Mention the commands you executed, the messages printed by them, and information on your operating system including the version number.
  5. Explain what you wanted to do. It is very useful to know your purpose and your wish, and how GRUB didn't satisfy you.
  6. If you can investigate the problem yourself, please do. That will give you and us much more information on the problem. Attaching a patch is even better.

    When you attach a patch, make the patch in unified diff format, and write ChangeLog entries. But, even when you make a patch, don't forget to explain the problem, so that we can understand what your patch is for.

  7. Write down anything that you think might be related. Please understand that we often need to reproduce the same problem you encounterred in our environment. So your information should be sufficient for us to do the same thing--Don't forget that we cannot see your computer directly. If you are not sure whether to state a fact or leave it out, state it! Reporting too many things is quite better than omitting an important thing.

If you realize the guideline above, send e-mail to bug-grub@gnu.org, and we will try to fix the bugs.

Node:Future, Next:Internals, Previous:Reporting bugs, Up:Top

Where GRUB will go

Here are some ideas that might happen in the future:

  • Support dynamic loading.
  • Add real memory management.
  • Add a real scripting language.
  • Support internationalization.
  • Support other architectures than i386-pc.

See the file TODO in the source distribution, for more information.

Node:Internals, Next:Index, Previous:Future, Up:Top

Hacking GRUB

This chapter documents the user-invisible aspect of GRUB.

As a general rule of software development, it is impossible to keep the descriptions of the internals up-to-date, and it is quite hard to document everything. So refer to the source code, whenever you are not satisfied with this documentation. Please assume that this gives just hints to you.

  • Memory map: The memory map of various components
  • Embedded data: Embedded variables in GRUB
  • Filesystem interface: The generic interface for filesystems
  • Command interface: The generic interface for built-ins
  • Bootstrap tricks: The bootstrap mechanism used in GRUB
  • I/O ports detection: How to probe I/O ports used by INT 13H
  • Memory detection: How to detect all installed RAM
  • Low-level disk I/O: INT 13H disk I/O interrupts
  • MBR: The structure of Master Boot Record
  • Partition table: The format of partition tables
  • Submitting patches: Where and how you should send patches

Node:Memory map, Next:Embedded data, Up:Internals

The memory map of various components

GRUB consists of two distinct components, called stages, which are loaded at different times in the boot process. Because they run mutual-exclusively, sometimes a memory area overlaps with another memory area. And, even in one stage, a single memory area can be used for various purposes, because their usages are mutually exclusive.

Here is the memory map of the various components:

0 to 4K-1
BIOS and real mode interrupts
0x07BE to 0x07FF
Partition table passed to another boot loader
down from 8K-1
Real mode stack
0x2000 to ?
The optional Stage 1.5 is loaded here
0x2000 to 0x7FFF
Command-line buffer for Multiboot kernels and modules
0x7C00 to 0x7DFF
Stage 1 is loaded here by BIOS or another boot loader
0x7F00 to 0x7F42
LBA drive parameters
0x8000 to ?
Stage2 is loaded here
The end of Stage 2 to 416K-1
Heap, in particular used for the menu
down from 416K-1
Protected mode stack
416K to 448K-1
Filesystem buffer
448K to 479.5K-1
Raw device buffer
479.5K to 480K-1
512-byte scratch area
480K to 512K-1
Buffers for various functions, such as password, command-line, cut and paste, and completion.
The last 1K of lower memory
Disk swapping code and data

See the file stage2/shared.h, for more information.

Node:Embedded data, Next:Filesystem interface, Previous:Memory map, Up:Internals

Embedded variables in GRUB

Stage 1 and Stage 2 have embedded variables whose locations are well-defined, so that the installation can patch the binary file directly without recompilation of the stages.

In Stage 1, these are defined:

0x3E
The version number (not GRUB's, but the installation mechanism's).
0x40
The boot drive. If it is 0xFF, use a drive passed by BIOS.
0x41
The flag for if forcing LBA.
0x42
The starting address of Stage 2.
0x44
The first sector of Stage 2.
0x48
The starting segment of Stage 2.
0x1FE
The signature (0xAA55).

See the file stage1/stage1.S, for more information.

In the first sector of Stage 1.5 and Stage 2, the block lists are recorded between firstlist and lastlist. The address of lastlist is determined when assembling the file stage2/start.S.

The trick here is that it is actually read backward, and the first 8-byte block list is not read here, but after the pointer is decremented 8 bytes, then after reading it, it decrements again, reads, and so on, until it is finished. The terminating condition is when the number of sectors to be read in the next block list is zero.

The format of a block list can be seen from the example in the code just before the firstlist label. Note that it is always from the beginning of the disk, but not relative to the partition boundaries.

In the second sector of Stage 1.5 and Stage 2, these are defined:

0x6
The version number (likewise, the installation mechanism's).
0x8
The installed partition.
0xC
The saved entry number.
0x10
The identifier.
0x11
The flag for if forcing LBA.
0x12
The version string (GRUB's).
0x12 + the length of the version string
The name of a configuration file.

See the file stage2/asm.S, for more information.

Node:Filesystem interface, Next:Command interface, Previous:Embedded data, Up:Internals

The generic interface for filesystems

For any particular partition, it is presumed that only one of the normal filesystems such as FAT, FFS, or ext2fs can be used, so there is a switch table managed by the functions in disk_io.c. The notation is that you can only mount one at a time.

The block list filesystem has a special place in the system. In addition to the normal filesystem (or even without one mounted), you can access disk blocks directly (in the indicated partition) via the block list notation. Using the block list filesystem doesn't effect any other filesystem mounts.

The variables which can be read by the filesystem backend are:

current_drive
The current BIOS drive number (numbered from 0, if a floppy, and numbered from 0x80, if a hard disk).
current_partition
The current partition number.
current_slice
The current partition type.
saved_drive
The drive part of the root device.
saved_partition
The partition part of the root device.
part_start
The current partition starting address, in sectors.
part_length
The current partition length, in sectors.
print_possibilities
True when the dir function should print the possible completions of a file, and false when it should try to actually open a file of that name.
FSYS_BUF
Filesystem buffer which is 32K in size, to use in any way which the filesystem backend desires.

The variables which need to be written by a filesystem backend are:

filepos
The current position in the file, in sectors.

Caution: the value of filepos can be changed out from under the filesystem code in the current implementation. Don't depend on it being the same for later calls into the backend code!

filemax
The length of the file.
disk_read_func
The value of disk_read_hook only during reading of data for the file, not any other fs data, inodes, FAT tables, whatever, then set to NULL at all other times (it will be NULL by default). If this isn't done correctly, then the testload and install commands won't work correctly.

The functions expected to be used by the filesystem backend are:

devread
Only read sectors from within a partition. Sector 0 is the first sector in the partition.
grub_read
If the backend uses the block list code, then grub_read can be used, after setting block_file to 1.
print_a_completion
If print_possibilities is true, call print_a_completion for each possible file name. Otherwise, the file name completion won't work.

The functions expected to be defined by the filesystem backend are described at least moderately in the file filesys.h. Their usage is fairly evident from their use in the functions in disk_io.c, look for the use of the fsys_table array.

Caution: The semantics are such that then mounting the filesystem, presume the filesystem buffer FSYS_BUF is corrupted, and (re-)load all important contents. When opening and reading a file, presume that the data from the mount is available, and doesn't get corrupted by the open/read (i.e. multiple opens and/or reads will be done with only one mount if in the same filesystem).

Node:Command interface, Next:Bootstrap tricks, Previous:Filesystem interface, Up:Internals

The generic interface for built-ins

GRUB built-in commands are defined in a uniformal interface, whether they are menu-specific or can be used anywhere. The definition of a builtin command consists of two parts: the code itself and the table of the information.

The code must be a function which takes two arguments, a command-line string and flags, and returns an int value. The flags argument specifies how the function is called, using a bit mask. The return value must be zero if successful, otherwise non-zero. So it is normally enough to return errnum.

The table of the information is represented by the structure struct builtin, which contains the name of the command, a pointer to the function, flags, a short description of the command and a long description of the command. Since the descriptions are used only for help messages interactively, you don't have to define them, if the command may not be called interactively (such as title).

The table is finally registered in the table builtin_table, so that run_script and enter_cmdline can find the command. See the files cmdline.c and builtins.c, for more details.

Node:Bootstrap tricks, Next:I/O ports detection, Previous:Command interface, Up:Internals

The bootstrap mechanism used in GRUB

The disk space can be used in a boot loader is very restricted because a MBR (see MBR) is only 512 bytes but it also contains a partition table (see Partition table) and a BPB. So the question is how to make a boot loader code enough small to be fit in a MBR.

However, GRUB is a very large program, so we break GRUB into 2 (or 3) distinct components, Stage 1 and Stage 2 (and optionally Stage 1.5). See Memory map, for more information.

We embed Stage 1 in a MBR or in the boot sector of a partition, and place Stage 2 in a filesystem. The optional Stage 1.5 can be installed in a filesystem, in the boot loader area in a FFS or a ReiserFS, and in the sectors right after a MBR, because Stage 1.5 is enough small and the sectors right after a MBR is normally an unused region. The size of this region is the number of sectors per head minus 1.

Thus, all Stage1 must do is just load Stage2 or Stage1.5. But even if Stage 1 needs not to support the user interface or the filesystem interface, it is impossible to make Stage 1 less than 400 bytes, because GRUB should support both the CHS mode and the LBA mode (see Low-level disk I/O).

The solution used by GRUB is that Stage 1 loads only the first sector of Stage 2 (or Stage 1.5) and Stage 2 itself loads the rest. The flow of Stage 1 is:

  1. Initialize the system briefly.
  2. Detect the geometry and the accessing mode of the loading drive.
  3. Load the first sector of Stage 2.
  4. Jump to the starting address of the Stage 2.

The flow of Stage 2 (and Stage 1.5) is:

  1. Load the rest of itself to the real starting address, that is, the starting address plus 512 bytes. The block lists are stored in the last part of the first sector.
  2. Long jump to the real starting address.

Note that Stage 2 (or Stage 1.5) does not probe the geometry or the accessing mode of the loading drive, since Stage 1 has already probed them.

Node:I/O ports detection, Next:Memory detection, Previous:Bootstrap tricks, Up:Internals

How to probe I/O ports used by INT 13H

FIXME: I will write this chapter after implementing the new technique.

Node:Memory detection, Next:Low-level disk I/O, Previous:I/O ports detection, Up:Internals

How to detect all installed RAM

FIXME: I doubt if Erich didn't write this chapter only himself wholly, so I will rewrite this chapter.

Node:Low-level disk I/O, Next:MBR, Previous:Memory detection, Up:Internals

INT 13H disk I/O interrupts

FIXME: I'm not sure where some part of the original chapter is derived, so I will rewrite this chapter.

Node:MBR, Next:Partition table, Previous:Low-level disk I/O, Up:Internals

The structure of Master Boot Record

FIXME: Likewise.

Node:Partition table, Next:Submitting patches, Previous:MBR, Up:Internals

The format of partition tables

FIXME: Probably the original chapter is derived from "How It Works", so I will rewrite this chapter.

Node:Submitting patches, Previous:Partition table, Up:Internals

Where and how you should send patches

When you write patches for GRUB, please send them to the mailing list bug-grub@gnu.org. Here is the list of items of which you should take care:

  • Please make your patch as small as possible. Generally, it is not a good thing to make one big patch which changes many things. Instead, segregate features and produce many patches.
  • Use as late code as possible, for the original code. The CVS repository always has the current version (see Obtaining and Building GRUB).
  • Write ChangeLog entries. See Change Logs, if you don't know how to write ChangeLog.
  • Make patches in unified diff format. diff -urN is appropriate in most cases.
  • Don't make patches reversely. Reverse patches are difficult to read and use.
  • Be careful enough of the license term and the copyright. Because GRUB is under GNU General Public License, you may not steal code from software whose license is incompatible against GPL. And, if you copy code written by others, you must not ignore their copyrights. Feel free to ask GRUB maintainers, whenever you are not sure what you should do.
  • If your patch is too large to send in e-mail, put it at somewhere we can see. Usually, you shouldn't send e-mail over 20K.

Node:Index, Previous:Internals, Up:Top

Index

  • blocklist: blocklist
  • boot: boot
  • bootp: bootp
  • cat: cat
  • chainloader: chainloader
  • cmp: cmp
  • color: color
  • configfile: configfile
  • current_drive: Filesystem interface
  • current_partition: Filesystem interface
  • current_slice: Filesystem interface
  • debug: debug
  • default: default
  • device: device
  • devread: Filesystem interface
  • dhcp: dhcp
  • disk_read_func: Filesystem interface
  • displayapm: displayapm
  • displaymem: displaymem
  • embed: embed
  • fallback: fallback
  • filemax: Filesystem interface
  • filepos: Filesystem interface
  • find: find
  • fstest: fstest
  • FSYS_BUF: Filesystem interface
  • geometry: geometry
  • grub_read: Filesystem interface
  • halt: halt
  • help: help
  • hiddenmenu: hiddenmenu
  • hide: hide
  • ifconfig: ifconfig
  • impsprobe: impsprobe
  • initrd: initrd
  • install: install
  • ioprobe: ioprobe
  • kernel: kernel
  • lock: lock
  • makeactive: makeactive
  • map: map
  • md5crypt: md5crypt
  • module: module
  • modulenounzip: modulenounzip
  • pager: pager
  • part_length: Filesystem interface
  • part_start: Filesystem interface
  • partnew: partnew
  • parttype: parttype
  • password: password
  • pause: pause
  • print_a_completion: Filesystem interface
  • print_possibilities: Filesystem interface
  • quit: quit
  • rarp: rarp
  • read: read
  • reboot: reboot
  • root: root
  • rootnoverify: rootnoverify
  • saved_drive: Filesystem interface
  • saved_partition: Filesystem interface
  • savedefault: savedefault
  • serial: serial
  • setkey: setkey
  • setup: setup
  • terminal: terminal
  • testload: testload
  • testvbe: testvbe
  • tftpserver: tftpserver
  • timeout: timeout
  • title: title
  • unhide: unhide
  • uppermem: uppermem
  • vbeprobe: vbeprobe

Table of Contents

  • GRUB manual
  • Introduction to GRUB
    • Overview
    • History of GRUB
    • GRUB features
    • The role of a boot loader
  • Naming convention
  • Installation
    • Creating a GRUB boot floppy
    • Installing GRUB natively
    • Installing GRUB using grub-install
  • Booting
    • How to boot operating systems
      • How to boot an OS directly with GRUB
      • Load another boot loader to boot unsupported operating systems
    • Some caveats on OS-specific issues
      • GNU/Hurd
      • GNU/Linux
      • FreeBSD
      • NetBSD
      • OpenBSD
      • DOS/Windows
      • SCO UnixWare
  • Configuration
  • Downloading OS images from a network
    • How to set up your network
    • Booting from a network
  • Using GRUB via a serial line
  • Embedding a configuration file into GRUB
  • Protecting your computer from cracking
  • GRUB image files
  • Filesystem syntax and semantics
    • How to specify devices
    • How to specify files
    • How to specify block lists
  • GRUB's user interface
    • The flexible command-line interface
    • The simple menu interface
    • Editing a menu entry
    • The hidden menu interface
  • The list of available commands
    • The list of commands for the menu only
      • default
      • fallback
      • hiddenmenu
      • timeout
      • title
    • The list of general commands
      • bootp
      • color
      • device
      • dhcp
      • hide
      • ifconfig
      • pager
      • partnew
      • parttype
      • password
      • rarp
      • serial
      • setkey
      • terminal
      • tftpserver
      • unhide
    • The list of command-line and menu entry commands
      • blocklist
      • boot
      • cat
      • chainloader
      • cmp
      • configfile
      • debug
      • displayapm
      • displaymem
      • embed
      • find
      • fstest
      • geometry
      • halt
      • help
      • impsprobe
      • initrd
      • install
      • ioprobe
      • kernel
      • lock
      • makeactive
      • map
      • md5crypt
      • module
      • modulenounzip
      • pause
      • quit
      • reboot
      • read
      • root
      • rootnoverify
      • savedefault
      • setup
      • testload
      • testvbe
      • uppermem
      • vbeprobe
  • Error messages reported by GRUB
    • Errors reported by the Stage 1
    • Errors reported by the Stage 1.5
    • Errors reported by the Stage 2
  • Invoking the grub shell
    • Introduction into the grub shell
    • How to install GRUB via grub
    • The map between BIOS drives and OS devices
  • Invoking grub-install
  • Invoking grub-md5-crypt
  • Invoking mbchk
  • Frequently asked questions
  • How to obtain and build GRUB
  • Reporting bugs
  • Where GRUB will go
  • Hacking GRUB
    • The memory map of various components
    • Embedded variables in GRUB
    • The generic interface for filesystems
    • The generic interface for built-ins
    • The bootstrap mechanism used in GRUB
    • How to probe I/O ports used by INT 13H
    • How to detect all installed RAM
    • INT 13H disk I/O interrupts
    • The structure of Master Boot Record
    • The format of partition tables
    • Where and how you should send patches
  • Index

Footnotes

  1. chain-load is the mechanism for loading unsupported operating systems by loading another boot loader. It is typically used for loading DOS or Windows.

  2. There are a few pathological cases where loading a very badly organized ELF kernel might take longer, but in practice this never happen.

  3. The LInux LOader, a boot loader that everybody uses, but nobody likes.

  4. Note that GRUB's root device doesn't necessarily mean your OS's root partition; if you need to specify a root partition for your OS, add the argument into the command kernel.

  5. This is not necessary for most of the modern operating systems.

  6. RARP is deprecated, since it cannot serve much information

  7. However, this behavior will be changed in the future version, in a user-invisible way.

  8. The latter feature has not been implemented yet.

  9. They're loaded the same way, so we will refer to the Stage 1.5 as a Stage 2 from now on.

  10. I can't imagine why you want to do such a thing, though


Gzip User's Manual

gzip

The data compression program

Edition 1.2.4, for Gzip Version 1.2.4

July 1993

by Jean-loup Gailly

Table of Contents

  • GNU GENERAL PUBLIC LICENSE
    • Preamble
    • TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
    • How to Apply These Terms to Your New Programs
  • Overview
  • Sample Output
  • Invoking gzip
  • Advanced usage
  • Environment
  • Using gzip on tapes
  • Reporting Bugs
  • Concept Index

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and an idea of what it does.
Copyright (C) 19yy  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

Overview

gzip reduces the size of the named files using Lempel-Ziv coding (LZ77). Whenever possible, each file is replaced by one with the extension `.gz', while keeping the same ownership modes, access and modification times. (The default extension is `-gz' for VMS, `z' for MSDOS, OS/2 FAT and Atari.) If no files are specified or if a file name is "-", the standard input is compressed to the standard output. gzip will only attempt to compress regular files. In particular, it will ignore symbolic links.

If the new file name is too long for its file system, gzip truncates it. gzip attempts to truncate only the parts of the file name longer than 3 characters. (A part is delimited by dots.) If the name consists of small parts only, the longest parts are truncated. For example, if file names are limited to 14 characters, gzip.msdos.exe is compressed to gzi.msd.exe.gz. Names are not truncated on systems which do not have a limit on file name length.

By default, gzip keeps the original file name and timestamp in the compressed file. These are used when decompressing the file with the `-N' option. This is useful when the compressed file name was truncated or when the time stamp was not preserved after a file transfer.

Compressed files can be restored to their original form using `gzip -d' or gunzip or zcat. If the original name saved in the compressed file is not suitable for its file system, a new name is constructed from the original one to make it legal.

gunzip takes a list of files on its command line and replaces each file whose name ends with `.gz', `.z', `.Z', `-gz', `-z' or `_z' and which begins with the correct magic number with an uncompressed file without the original extension. gunzip also recognizes the special extensions `.tgz' and `.taz' as shorthands for `.tar.gz' and `.tar.Z' respectively. When compressing, gzip uses the `.tgz' extension if necessary instead of truncating a file with a `.tar' extension.

gunzip can currently decompress files created by gzip, zip, compress or pack. The detection of the input format is automatic. When using the first two formats, gunzip checks a 32 bit CRC (cyclic redundancy check). For pack, gunzip checks the uncompressed length. The compress format was not designed to allow consistency checks. However gunzip is sometimes able to detect a bad `.Z' file. If you get an error when uncompressing a `.Z' file, do not assume that the `.Z' file is correct simply because the standard uncompress does not complain. This generally means that the standard uncompress does not check its input, and happily generates garbage output. The SCO `compress -H' format (lzh compression method) does not include a CRC but also allows some consistency checks.

Files created by zip can be uncompressed by gzip only if they have a single member compressed with the 'deflation' method. This feature is only intended to help conversion of tar.zip files to the tar.gz format. To extract zip files with several members, use unzip instead of gunzip.

zcat is identical to `gunzip -c'. zcat uncompresses either a list of files on the command line or its standard input and writes the uncompressed data on standard output. zcat will uncompress files that have the correct magic number whether they have a `.gz' suffix or not.

gzip uses the Lempel-Ziv algorithm used in zip and PKZIP. The amount of compression obtained depends on the size of the input and the distribution of common substrings. Typically, text such as source code or English is reduced by 60-70%. Compression is generally much better than that achieved by LZW (as used in compress), Huffman coding (as used in pack), or adaptive Huffman coding (compact).

Compression is always performed, even if the compressed file is slightly larger than the original. The worst case expansion is a few bytes for the gzip file header, plus 5 bytes every 32K block, or an expansion ratio of 0.015% for large files. Note that the actual number of used disk blocks almost never increases. gzip preserves the mode, ownership and timestamps of files when compressing or decompressing.

Sample Output

Here are some realistic examples of running gzip.

This is the output of the command `gzip -h':

gzip 1.2.4 (18 Aug 93)
usage: gzip [-cdfhlLnNrtvV19] [-S suffix] [file ...]
 -c --stdout      write on standard output, keep original files unchanged
 -d --decompress  decompress
 -f --force       force overwrite of output file and compress links
 -h --help        give this help
 -l --list        list compressed file contents
 -L --license     display software license
 -n --no-name     do not save or restore the original name and time stamp
 -N --name        save or restore the original name and time stamp
 -q --quiet       suppress all warnings
 -r --recursive   operate recursively on directories
 -S .suf  --suffix .suf     use suffix .suf on compressed files
 -t --test        test compressed file integrity
 -v --verbose     verbose mode
 -V --version     display version number
 -1 --fast        compress faster
 -9 --best        compress better
 file...          files to (de)compress. If none given, use standard input.

This is the output of the command `gzip -v texinfo.tex':

texinfo.tex:             71.6% -- replaced with texinfo.tex.gz

The following command will find all gzip files in the current directory and subdirectories, and extract them in place without destroying the original:

find . -name '*.gz' -print | sed 's/^\(.*\)[.]gz$/gunzip < "&" > "\1"/' | sh

Invoking gzip

The format for running the gzip program is:

gzip option ...

gzip supports the following options:

`--stdout'
`--to-stdout'
`-c'
Write output on standard output; keep original files unchanged. If there are several input files, the output consists of a sequence of independently compressed members. To obtain better compression, concatenate all input files before compressing them.
`--decompress'
`--uncompress'
`-d'
Decompress.
`--force'
`-f'
Force compression or decompression even if the file has multiple links or the corresponding file already exists, or if the compressed data is read from or written to a terminal. If the input data is not in a format recognized by gzip, and if the option --stdout is also given, copy the input data without change to the standard ouput: let zcat behave as cat. If `-f' is not given, and when not running in the background, gzip prompts to verify whether an existing file should be overwritten.
`--help'
`-h'
Print an informative help message describing the options then quit.
`--list'
`-l'
For each compressed file, list the following fields:
compressed size: size of the compressed file
uncompressed size: size of the uncompressed file
ratio: compression ratio (0.0% if unknown)
uncompressed_name: name of the uncompressed file
The uncompressed size is given as `-1' for files not in gzip format, such as compressed `.Z' files. To get the uncompressed size for such a file, you can use:
zcat file.Z | wc -c
In combination with the --verbose option, the following fields are also displayed:
method: compression method (deflate,compress,lzh,pack)
crc: the 32-bit CRC of the uncompressed data
date & time: time stamp for the uncompressed file
The crc is given as ffffffff for a file not in gzip format. With --verbose, the size totals and compression ratio for all files is also displayed, unless some sizes are unknown. With --quiet, the title and totals lines are not displayed.
`--license'
`-L'
Display the gzip license then quit.
`--no-name'
`-n'
When compressing, do not save the original file name and time stamp by default. (The original name is always saved if the name had to be truncated.) When decompressing, do not restore the original file name if present (remove only the gzip suffix from the compressed file name) and do not restore the original time stamp if present (copy it from the compressed file). This option is the default when decompressing.
`--name'
`-N'
When compressing, always save the original file name and time stamp; this is the default. When decompressing, restore the original file name and time stamp if present. This option is useful on systems which have a limit on file name length or when the time stamp has been lost after a file transfer.
`--quiet'
`-q'
Suppress all warning messages.
`--recursive'
`-r'
Travel the directory structure recursively. If any of the file names specified on the command line are directories, gzip will descend into the directory and compress all the files it finds there (or decompress them in the case of gunzip).
`--suffix suf'
`-S suf'
Use suffix `suf' instead of `.gz'. Any suffix can be given, but suffixes other than `.z' and `.gz' should be avoided to avoid confusion when files are transferred to other systems. A null suffix forces gunzip to try decompression on all given files regardless of suffix, as in:
gunzip -S "" *        (*.* for MSDOS)
Previous versions of gzip used the `.z' suffix. This was changed to avoid a conflict with pack.
`--test'
`-t'
Test. Check the compressed file integrity.
`--verbose'
`-v'
Verbose. Display the name and percentage reduction for each file compressed.
`--version'
`-V'
Version. Display the version number and compilation options, then quit.
`--fast'
`--best'
`-n'
Regulate the speed of compression using the specified digit n, where `-1' or `--fast' indicates the fastest compression method (less compression) and `--best' or `-9' indicates the slowest compression method (optimal compression). The default compression level is `-6' (that is, biased towards high compression at expense of speed).

Advanced usage

Multiple compressed files can be concatenated. In this case, gunzip will extract all members at once. If one member is damaged, other members might still be recovered after removal of the damaged member. Better compression can be usually obtained if all members are decompressed and then recompressed in a single step.

This is an example of concatenating gzip files:

gzip -c file1  > foo.gz
gzip -c file2 >> foo.gz

Then

gunzip -c foo

is equivalent to

cat file1 file2

In case of damage to one member of a `.gz' file, other members can still be recovered (if the damaged member is removed). However, you can get better compression by compressing all members at once:

cat file1 file2 | gzip > foo.gz

compresses better than

gzip -c file1 file2 > foo.gz

If you want to recompress concatenated files to get better compression, do:

zcat old.gz | gzip > new.gz

If a compressed file consists of several members, the uncompressed size and CRC reported by the `--list' option applies to the last member only. If you need the uncompressed size for all members, you can use:

zcat file.gz | wc -c

If you wish to create a single archive file with multiple members so that members can later be extracted independently, use an archiver such as tar or zip. GNU tar supports the `-z' option to invoke gzip transparently. gzip is designed as a complement to tar, not as a replacement.

Environment

The environment variable GZIP can hold a set of default options for gzip. These options are interpreted first and can be overwritten by explicit command line parameters. For example:

for sh:    GZIP="-8v --name"; export GZIP
for csh:   setenv GZIP "-8v --name"
for MSDOS: set GZIP=-8v --name

On Vax/VMS, the name of the environment variable is GZIP_OPT, to avoid a conflict with the symbol set for invocation of the program.

Using gzip on tapes

When writing compressed data to a tape, it is generally necessary to pad the output with zeroes up to a block boundary. When the data is read and the whole block is passed to gunzip for decompression, gunzip detects that there is extra trailing garbage after the compressed data and emits a warning by default. You have to use the `--quiet' option to suppress the warning. This option can be set in the GZIP environment variable, as in:

for sh:    GZIP="-q"  tar -xfz --block-compress /dev/rst0
for csh:   (setenv GZIP "-q"; tar -xfz --block-compress /dev/rst0)

In the above example, gzip is invoked implicitly by the `-z' option of GNU tar. Make sure that the same block size (`-b' option of tar) is used for reading and writing compressed data on tapes. (This example assumes you are using the GNU version of tar.)

Reporting Bugs

If you find a bug in gzip, please send electronic mail to `jloup@chorus.fr' or, if this fails, to `bug-gnu-utils@prep.ai.mit.edu'. Include the version number, which you can find by running `gzip -V'. Also include in your message the hardware and operating system, the compiler used to compile gzip, a description of the bug behavior, and the input to gzip that triggered the bug.

Concept Index

Jump to: b - c - e - i - o - s - t

b

  • bugs

    • c

  • concatenated files

    • e

  • Environment

    • i

  • invoking

    • o

  • options
  • overview

    • s

  • sample

    • t

  • tapes

    • This document was generated on 7 November 1998 using the texi2html translator version 1.52.


jwhois, Whois client

jwhois

Version 2.4

28 December 1999

Jonas Öberg (jonas@gnu.org)

Introduction

JWHOIS is an Internet Whois client that queries hosts for information according to RFC 954 - NICNAME/WHOIS. JWHOIS is configured via a configuration file that contains information about all known Whois servers. Upon execution, the host to query is selected based on the information in the configuration file.

The configuration file is highly customizable and makes heavy use of regular expressions.

Invocation

JWHOIS uses the following command-line options:

`--version'
Print the program version and licensing information.
`--help'
Print a usage message summarizing the command-line options.
`-c FILE'
`--config=FILE'
Reads configuration from FILE instead of from the default system global configuration file.
`-h HOST'
`--host=HOST'
Overrides any specifications in the configuration file and queries HOST directly.
`-p PORT'
`--port=PORT'
Specifies a port number to use when querying a HOST
`-f'
`--force-lookup'
This option forces the client to look up an entry from the source Whois server, even if a current copy is available in the system cache.
`-d'
`--disable-cache'
This disables the cache functionality.
`-v'
`--verbose'
Enables verbose debugging output where available.

The query can optionally contain the character `@' followed by a host name to direct the search to that host. This works exactly like specifying the host with `--host'.

RIPE Extensions

RIPE (Réseaux IP Européens) has defined a number of options that can be used against a RIPE-compatible whois server (ripe.net, apnic.net and others). Unfortunately, there is really no way of telling whether a host we are connecting to is RIPE-compatible or not. RIPE extensions are therefore not directly incorporated into the JWHOIS client. A list of the options can be found in RIPE Document 157 which you can get from the RIPE ftp server, ftp://ftp.ripe.net/ripe/docs/.

It is possible to use these options together with JWHOIS by changing the format of the query slightly. If you were to search for all entries in the RIPE database which lists the admin-c, tech-c or zone-c as CO19-RIPE, you could use the following command syntax:

$ jwhois -h whois.ripe.net -- -i admin-c,tech-c,zone-c CO19-RIPE

`--' is used to separate the RIPE options from the jwhois options.

Site Configuration

JWHOIS is configurable via its configuration file, normally called `jwhois.conf'. This file is looked for in the sysconfdir that was specified when compiling the program (default is `/usr/local/etc/' on most systems).

If no configuration file can be found, JWHOIS will default all queries to whois.internic.net.

An example configuration file that includes most known Whois servers can be found in the example subdirectory of the official distribution.

The configuration file is split into a number of blocks. Each block can contain a number of different options which are explained in the sections below. You can also get an overview of the syntax by looking at the example configuration file included in the distribution.

  • Global: Global configuration options
  • Whois-servers: Whois server configuration
  • Content-redirect: The content-redirect block

Global

The only available global options are related to the cache features in jwhois See section Cache Functionality. By default, the location of the configuration file is `/usr/local/var/jwhois.db', but this can be changed at compile time. The option @option{cachefile} also changes the location.

The default expire time for all cached objects it 7 days (168 hours). this can be changed with the @option{cacheexpire} option. The value is the number of hours that objects is considered to be current.

Example:

cachefile = "/var/lib/jwhois.db";
cacheexpire = 168;

Whois-servers

When making a query, JWHOIS looks at the @option{whois-servers} block to determine which host to send the query to. The option @option{type} can be set to change between two different kinds of matching; @option{cidr} or @option{regex}.

@option{regex} matches using standard regular expressions. @option{cidr} matches using CIDR net blocks.

The value of all objects can take one of two forms. Either a hostname or the special option @option{struct}. The later asks JWHOIS to look at another option block in the configuration file.

When matching using CIDR net blocks, the key can take the special value @option{default} which matches everything.

whois-servers {
        type = regex;
        ".*-[A-Z]+$" = "struct handles";
        ".*" = "whois.internic.net";
};
handles {
        type = regex;
        ".*-RIPE$" = "whois.ripe.net";
        default = "whois.arin.net";
};

Content-redirect

@option{content-redirect} is a special block designed to parse the output returned by a Whois server looking for special regular expressions and then sending the same query to the Whois server gotten from the regular expression.

The key value is the name of the Whois server that this expression is applicable to. This is matched using regular expressions. The value is the regexp that is looked for in the output, with hostname and optional port number enclosed in so called subexpressions or groups.

content-redirect {
        ".*" = ".*Whois Server: \\(.*\\)";
};

Cache Functionality

JWHOIS implements support for maintaining a cache of Whois data received from Whois servers. This is NOT enabled by default but has to be compiled into the client specifically. The design is such that a central database is maintained by the client and because all users should have access to that database, the program must have the set-group-on-execution bit set and the database must be both read and writable by the group.

The configuration options available are CACHEFILE and CACHEEXPIRE which sets the database filename and the expire time for cached object. When an object expires from the cache, it is reloaded from the Whois server the next time it is requested. The expire time is measured in hours.

Reporting bugs

Email bug reports to bug-jwhois@gnu.org.

This document was generated on 28 December 1999 using texi2html 1.56k.


Using LD, the GNU linker

Using ld

The GNU linker

ld version 2

January 1994

Steve Chamberlain
Cygnus Support

Table of Contents

  • Overview
  • Invocation
    • Command Line Options
    • Environment Variables
  • Command Language
    • Linker Scripts
    • Expressions
      • Integers
      • Symbol Names
      • The Location Counter
      • Operators
      • Evaluation
      • Assignment: Defining Symbols
      • Arithmetic Functions
      • Semicolons
    • Memory Layout
    • Specifying Output Sections
      • Section Definitions
      • Section Placement
      • Section Data Expressions
      • Optional Section Attributes
      • Overlays
    • ELF Program Headers
    • The Entry Point
    • Version Script
    • Option Commands
  • Machine Dependent Features
    • ld and the H8/300
    • ld and the Intel 960 family
  • BFD
    • How it works: an outline of BFD
      • Information Loss
      • The BFD canonical object-file format
  • Reporting Bugs
    • Have you found a bug?
    • How to report bugs
  • MRI Compatible Script Files
  • Index

Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Overview

ld combines a number of object and archive files, relocates their data and ties up symbol references. Usually the last step in compiling a program is to run ld.

ld accepts Linker Command Language files written in a superset of AT&T's Link Editor Command Language syntax, to provide explicit and total control over the linking process.

This version of ld uses the general purpose BFD libraries to operate on object files. This allows ld to read, combine, and write object files in many different formats--for example, COFF or a.out. Different formats may be linked together to produce any available kind of object file. See section BFD, for more information.

Aside from its flexibility, the GNU linker is more helpful than other linkers in providing diagnostic information. Many linkers abandon execution immediately upon encountering an error; whenever possible, ld continues executing, allowing you to identify other errors (or, in some cases, to get an output file in spite of the error).

Invocation

The GNU linker ld is meant to cover a broad range of situations, and to be as compatible as possible with other linkers. As a result, you have many choices to control its behavior.

Command Line Options

The linker supports a plethora of command-line options, but in actual practice few of them are used in any particular context. For instance, a frequent use of ld is to link standard Unix object files on a standard, supported Unix system. On such a system, to link a file hello.o:

ld -o output /lib/crt0.o hello.o -lc

This tells ld to produce a file called output as the result of linking the file /lib/crt0.o with hello.o and the library libc.a, which will come from the standard search directories. (See the discussion of the `-l' option below.)

The command-line options to ld may be specified in any order, and may be repeated at will. Repeating most options with a different argument will either have no further effect, or override prior occurrences (those further to the left on the command line) of that option. Options which may be meaningfully specified more than once are noted in the descriptions below.

Non-option arguments are objects files which are to be linked together. They may follow, precede, or be mixed in with command-line options, except that an object file argument may not be placed between an option and its argument.

Usually the linker is invoked with at least one object file, but you can specify other forms of binary input files using `-l', `-R', and the script command language. If no binary input files at all are specified, the linker does not produce any output, and issues the message `No input files'.

If the linker can not recognize the format of an object file, it will assume that it is a linker script. A script specified in this way augments the main linker script used for the link (either the default linker script or the one specified by using `-T'). This feature permits the linker to link against a file which appears to be an object or an archive, but actually merely defines some symbol values, or uses INPUT or GROUP to load other objects. Note that specifying a script in this way should only be used to augment the main linker script; if you want to use some command that logically can only appear once, such as the SECTIONS or MEMORY command, you must replace the default linker script using the `-T' option. See section Command Language.

For options whose names are a single letter, option arguments must either follow the option letter without intervening whitespace, or be given as separate arguments immediately following the option that requires them.

For options whose names are multiple letters, either one dash or two can precede the option name; for example, `--oformat' and `--oformat' are equivalent. Arguments to multiple-letter options must either be separated from the option name by an equals sign, or be given as separate arguments immediately following the option that requires them. For example, `--oformat srec' and `--oformat=srec' are equivalent. Unique abbreviations of the names of multiple-letter options are accepted.

-akeyword
This option is supported for HP/UX compatibility. The keyword argument must be one of the strings `archive', `shared', or `default'. `-aarchive' is functionally equivalent to `-Bstatic', and the other two keywords are functionally equivalent to `-Bdynamic'. This option may be used any number of times.
-Aarchitecture
--architecture=architecture
In the current release of ld, this option is useful only for the Intel 960 family of architectures. In that ld configuration, the architecture argument identifies the particular architecture in the 960 family, enabling some safeguards and modifying the archive-library search path. See section ld and the Intel 960 family, for details. Future releases of ld may support similar functionality for other architecture families.
-b input-format
--format=input-format
ld may be configured to support more than one kind of object file. If your ld is configured this way, you can use the `-b' option to specify the binary format for input object files that follow this option on the command line. Even when ld is configured to support alternative object formats, you don't usually need to specify this, as ld should be configured to expect as a default input format the most usual format on each machine. input-format is a text string, the name of a particular format supported by the BFD libraries. (You can list the available binary formats with `objdump -i'.) See section BFD. You may want to use this option if you are linking files with an unusual binary format. You can also use `-b' to switch formats explicitly (when linking object files of different formats), by including `-b input-format' before each group of object files in a particular format. The default format is taken from the environment variable GNUTARGET. See section Environment Variables. You can also define the input format from a script, using the command TARGET; see section Option Commands.
-c MRI-commandfile
--mri-script=MRI-commandfile
For compatibility with linkers produced by MRI, ld accepts script files written in an alternate, restricted command language, described in section MRI Compatible Script Files. Introduce MRI script files with the option `-c'; use the `-T' option to run linker scripts written in the general-purpose ld scripting language. If MRI-cmdfile does not exist, ld looks for it in the directories specified by any `-L' options.
-d
-dc
-dp
These three options are equivalent; multiple forms are supported for compatibility with other linkers. They assign space to common symbols even if a relocatable output file is specified (with `-r'). The script command FORCE_COMMON_ALLOCATION has the same effect. See section Option Commands.
-e entry
--entry=entry
Use entry as the explicit symbol for beginning execution of your program, rather than the default entry point. See section The Entry Point, for a discussion of defaults and other ways of specifying the entry point.
-E
--export-dynamic
When creating a dynamically linked executable, add all symbols to the dynamic symbol table. The dynamic symbol table is the set of symbols which are visible from dynamic objects at run time. If you do not use this option, the dynamic symbol table will normally contain only those symbols which are referenced by some dynamic object mentioned in the link. If you use dlopen to load a dynamic object which needs to refer back to the symbols defined by the program, rather than some other dynamic object, then you will probably need to use this option when linking the program itself.
-f
--auxiliary name
When creating an ELF shared object, set the internal DT_AUXILIARY field to the specified name. This tells the dynamic linker that the symbol table of the shared object should be used as an auxiliary filter on the symbol table of the shared object name. If you later link a program against this filter object, then, when you run the program, the dynamic linker will see the DT_AUXILIARY field. If the dynamic linker resolves any symbols from the filter object, it will first check whether there is a definition in the shared object name. If there is one, it will be used instead of the definition in the filter object. The shared object name need not exist. Thus the shared object name may be used to provide an alternative implementation of certain functions, perhaps for debugging or for machine specific performance. This option may be specified more than once. The DT_AUXILIARY entries will be created in the order in which they appear on the command line.
-F name
--filter name
When creating an ELF shared object, set the internal DT_FILTER field to the specified name. This tells the dynamic linker that the symbol table of the shared object which is being created should be used as a filter on the symbol table of the shared object name. If you later link a program against this filter object, then, when you run the program, the dynamic linker will see the DT_FILTER field. The dynamic linker will resolve symbols according to the symbol table of the filter object as usual, but it will actually link to the definitions found in the shared object name. Thus the filter object can be used to select a subset of the symbols provided by the object name. Some older linkers used the -F option throughout a compilation toolchain for specifying object-file format for both input and output object files. The GNU linker uses other mechanisms for this purpose: the -b, --format, --oformat options, the TARGET command in linker scripts, and the GNUTARGET environment variable. The GNU linker will ignore the -F option when not creating an ELF shared object.
--force-exe-suffix
Make sure that an output file has a .exe suffix. If a successfully built fully linked output file does not have a .exe or .dll suffix, this option forces the linker to copy the output file to one of the same name with a .exe suffix. This option is useful when using unmodified Unix makefiles on a Microsoft Windows host, since some versions of Windows won't run an image unless it ends in a .exe suffix.
-g
Ignored. Provided for compatibility with other tools.
-Gvalue
--gpsize=value
Set the maximum size of objects to be optimized using the GP register to size. This is only meaningful for object file formats such as MIPS ECOFF which supports putting large and small objects into different sections. This is ignored for other object file formats.
-hname
-soname=name
When creating an ELF shared object, set the internal DT_SONAME field to the specified name. When an executable is linked with a shared object which has a DT_SONAME field, then when the executable is run the dynamic linker will attempt to load the shared object specified by the DT_SONAME field rather than the using the file name given to the linker.
-i
Perform an incremental link (same as option `-r').
-larchive
--library=archive
Add archive file archive to the list of files to link. This option may be used any number of times. ld will search its path-list for occurrences of libarchive.a for every archive specified. On systems which support shared libraries, ld may also search for libraries with extensions other than .a. Specifically, on ELF and SunOS systems, ld will search a directory for a library with an extension of .so before searching for one with an extension of .a. By convention, a .so extension indicates a shared library. The linker will search an archive only once, at the location where it is specified on the command line. If the archive defines a symbol which was undefined in some object which appeared before the archive on the command line, the linker will include the appropriate file(s) from the archive. However, an undefined symbol in an object appearing later on the command line will not cause the linker to search the archive again. See the -( option for a way to force the linker to search archives multiple times. You may list the same archive multiple times on the command line. This type of archive searching is standard for Unix linkers. However, if you are using ld on AIX, note that it is different from the behaviour of the AIX linker.
-Lsearchdir
--library-path=searchdir
Add path searchdir to the list of paths that ld will search for archive libraries and ld control scripts. You may use this option any number of times. The directories are searched in the order in which they are specified on the command line. Directories specified on the command line are searched before the default directories. All -L options apply to all -l options, regardless of the order in which the options appear. The default set of paths searched (without being specified with `-L') depends on which emulation mode ld is using, and in some cases also on how it was configured. See section Environment Variables. The paths can also be specified in a link script with the SEARCH_DIR command. Directories specified this way are searched at the point in which the linker script appears in the command line.
-memulation
Emulate the emulation linker. You can list the available emulations with the `--verbose' or `-V' options. If the `-m' option is not used, the emulation is taken from the LDEMULATION environment variable, if that is defined. Otherwise, the default emulation depends upon how the linker was configured.
-M
--print-map
Print a link map to the standard output. A link map provides information about the link, including the following:
  • Where object files and symbols are mapped into memory.
  • How common symbols are allocated.
  • All archive members included in the link, with a mention of the symbol which caused the archive member to be brought in.
-n
--nmagic
Set the text segment to be read only, and mark the output as NMAGIC if possible.
-N
--omagic
Set the text and data sections to be readable and writable. Also, do not page-align the data segment. If the output format supports Unix style magic numbers, mark the output as OMAGIC.
-o output
--output=output
Use output as the name for the program produced by ld; if this option is not specified, the name `a.out' is used by default. The script command OUTPUT can also specify the output file name.
-r
--relocateable
Generate relocatable output--i.e., generate an output file that can in turn serve as input to ld. This is often called partial linking. As a side effect, in environments that support standard Unix magic numbers, this option also sets the output file's magic number to OMAGIC. If this option is not specified, an absolute file is produced. When linking C++ programs, this option will not resolve references to constructors; to do that, use `-Ur'. This option does the same thing as `-i'.
-R filename
--just-symbols=filename
Read symbol names and their addresses from filename, but do not relocate it or include it in the output. This allows your output file to refer symbolically to absolute locations of memory defined in other programs. You may use this option more than once. For compatibility with other ELF linkers, if the -R option is followed by a directory name, rather than a file name, it is treated as the -rpath option.
-s
--strip-all
Omit all symbol information from the output file.
-S
--strip-debug
Omit debugger symbol information (but not all symbols) from the output file.
-t
--trace
Print the names of the input files as ld processes them.
-T commandfile
--script=commandfile
Read link commands from the file commandfile. These commands replace ld's default link script (rather than adding to it), so commandfile must specify everything necessary to describe the target format. You must use this option if you want to use a command which can only appear once in a linker script, such as the SECTIONS or MEMORY command. See section Command Language. If commandfile does not exist, ld looks for it in the directories specified by any preceding `-L' options. Multiple `-T' options accumulate.
-u symbol
--undefined=symbol
Force symbol to be entered in the output file as an undefined symbol. Doing this may, for example, trigger linking of additional modules from standard libraries. `-u' may be repeated with different option arguments to enter additional undefined symbols.
-v
--version
-V
Display the version number for ld. The -V option also lists the supported emulations.
-x
--discard-all
Delete all local symbols.
-X
--discard-locals
Delete all temporary local symbols. For most targets, this is all local symbols whose names begin with `L'.
-y symbol
--trace-symbol=symbol
Print the name of each linked file in which symbol appears. This option may be given any number of times. On many systems it is necessary to prepend an underscore. This option is useful when you have an undefined symbol in your link but don't know where the reference is coming from.
-Y path
Add path to the default library search path. This option exists for Solaris compatibility.
-z keyword
This option is ignored for Solaris compatibility.
-( archives -)
--start-group archives --end-group
The archives should be a list of archive files. They may be either explicit file names, or `-l' options. The specified archives are searched repeatedly until no new undefined references are created. Normally, an archive is searched only once in the order that it is specified on the command line. If a symbol in that archive is needed to resolve an undefined symbol referred to by an object in an archive that appears later on the command line, the linker would not be able to resolve that reference. By grouping the archives, they all be searched repeatedly until all possible references are resolved. Using this option has a significant performance cost. It is best to use it only when there are unavoidable circular references between two or more archives.
-assert keyword
This option is ignored for SunOS compatibility.
-Bdynamic
-dy
-call_shared
Link against dynamic libraries. This is only meaningful on platforms for which shared libraries are supported. This option is normally the default on such platforms. The different variants of this option are for compatibility with various systems. You may use this option multiple times on the command line: it affects library searching for -l options which follow it.
-Bstatic
-dn
-non_shared
-static
Do not link against shared libraries. This is only meaningful on platforms for which shared libraries are supported. The different variants of this option are for compatibility with various systems. You may use this option multiple times on the command line: it affects library searching for -l options which follow it.
-Bsymbolic
When creating a shared library, bind references to global symbols to the definition within the shared library, if any. Normally, it is possible for a program linked against a shared library to override the definition within the shared library. This option is only meaningful on ELF platforms which support shared libraries.
--cref
Output a cross reference table. If a linker map file is being generated, the cross reference table is printed to the map file. Otherwise, it is printed on the standard output. The format of the table is intentionally simple, so that it may be easily processed by a script if necessary. The symbols are printed out, sorted by name. For each symbol, a list of file names is given. If the symbol is defined, the first file listed is the location of the definition. The remaining files contain references to the symbol.
--defsym symbol=expression
Create a global symbol in the output file, containing the absolute address given by expression. You may use this option as many times as necessary to define multiple symbols in the command line. A limited form of arithmetic is supported for the expression in this context: you may give a hexadecimal constant or the name of an existing symbol, or use + and - to add or subtract hexadecimal constants or symbols. If you need more elaborate expressions, consider using the linker command language from a script (see section Assignment: Defining Symbols). Note: there should be no white space between symbol, the equals sign ("="), and expression.
--dynamic-linker file
Set the name of the dynamic linker. This is only meaningful when generating dynamically linked ELF executables. The default dynamic linker is normally correct; don't use this unless you know what you are doing.
-EB
Link big-endian objects. This affects the default output format.
-EL
Link little-endian objects. This affects the default output format.
--embedded-relocs
This option is only meaningful when linking MIPS embedded PIC code, generated by the -membedded-pic option to the GNU compiler and assembler. It causes the linker to create a table which may be used at runtime to relocate any data which was statically initialized to pointer values. See the code in testsuite/ld-empic for details.
--help
Print a summary of the command-line options on the standard output and exit.
-Map mapfile
Print a link map to the file mapfile. See the description of the `-M' option, above.
--no-keep-memory
ld normally optimizes for speed over memory usage by caching the symbol tables of input files in memory. This option tells ld to instead optimize for memory usage, by rereading the symbol tables as necessary. This may be required if ld runs out of memory space while linking a large executable.
--no-warn-mismatch
Normally ld will give an error if you try to link together input files that are mismatched for some reason, perhaps because they have been compiled for different processors or for different endiannesses. This option tells ld that it should silently permit such possible errors. This option should only be used with care, in cases when you have taken some special action that ensures that the linker errors are inappropriate.
--no-whole-archive
Turn off the effect of the --whole-archive option for subsequent archive files.
--noinhibit-exec
Retain the executable output file whenever it is still usable. Normally, the linker will not produce an output file if it encounters errors during the link process; it exits without writing an output file when it issues any error whatsoever.
--oformat output-format
ld may be configured to support more than one kind of object file. If your ld is configured this way, you can use the `--oformat' option to specify the binary format for the output object file. Even when ld is configured to support alternative object formats, you don't usually need to specify this, as ld should be configured to produce as a default output format the most usual format on each machine. output-format is a text string, the name of a particular format supported by the BFD libraries. (You can list the available binary formats with `objdump -i'.) The script command OUTPUT_FORMAT can also specify the output format, but this option overrides it. See section BFD.
-qmagic
This option is ignored for Linux compatibility.
-Qy
This option is ignored for SVR4 compatibility.
--relax
An option with machine dependent effects. This option is only supported on a few targets. See section ld and the H8/300. See section ld and the Intel 960 family. On some platforms, the `--relax' option performs global optimizations that become possible when the linker resolves addressing in the program, such as relaxing address modes and synthesizing new instructions in the output object file. On platforms where this is not supported, `--relax' is accepted, but ignored.
--retain-symbols-file filename
Retain only the symbols listed in the file filename, discarding all others. filename is simply a flat file, with one symbol name per line. This option is especially useful in environments (such as VxWorks) where a large global symbol table is accumulated gradually, to conserve run-time memory. `--retain-symbols-file' does not discard undefined symbols, or symbols needed for relocations. You may only specify `--retain-symbols-file' once in the command line. It overrides `-s' and `-S'.
-rpath dir
Add a directory to the runtime library search path. This is used when linking an ELF executable with shared objects. All -rpath arguments are concatenated and passed to the runtime linker, which uses them to locate shared objects at runtime. The -rpath option is also used when locating shared objects which are needed by shared objects explicitly included in the link; see the description of the -rpath-link option. If -rpath is not used when linking an ELF executable, the contents of the environment variable LD_RUN_PATH will be used if it is defined. The -rpath option may also be used on SunOS. By default, on SunOS, the linker will form a runtime search patch out of all the -L options it is given. If a -rpath option is used, the runtime search path will be formed exclusively using the -rpath options, ignoring the -L options. This can be useful when using gcc, which adds many -L options which may be on NFS mounted filesystems. For compatibility with other ELF linkers, if the -R option is followed by a directory name, rather than a file name, it is treated as the -rpath option.
-rpath-link DIR
When using ELF or SunOS, one shared library may require another. This happens when an ld -shared link includes a shared library as one of the input files. When the linker encounters such a dependency when doing a non-shared, non-relocateable link, it will automatically try to locate the required shared library and include it in the link, if it is not included explicitly. In such a case, the -rpath-link option specifies the first set of directories to search. The -rpath-link option may specify a sequence of directory names either by specifying a list of names separated by colons, or by appearing multiple times. The linker uses the following search paths to locate required shared libraries.
  1. Any directories specified by -rpath-link options.
  2. Any directories specified by -rpath options. The difference between -rpath and -rpath-link is that directories specified by -rpath options are included in the executable and used at runtime, whereas the -rpath-link option is only effective at link time.
  3. On an ELF system, if the -rpath and rpath-link options were not used, search the contents of the environment variable LD_RUN_PATH.
  4. On SunOS, if the -rpath option was not used, search any directories specified using -L options.
  5. For a native linker, the contents of the environment variable LD_LIBRARY_PATH.
  6. The default directories, normally `/lib' and `/usr/lib'.
If the required shared library is not found, the linker will issue a warning and continue with the link.
-shared
-Bshareable
Create a shared library. This is currently only supported on ELF, XCOFF and SunOS platforms. On SunOS, the linker will automatically create a shared library if the -e option is not used and there are undefined symbols in the link.
--sort-common
This option tells ld to sort the common symbols by size when it places them in the appropriate output sections. First come all the one byte symbols, then all the two bytes, then all the four bytes, and then everything else. This is to prevent gaps between symbols due to alignment constraints.
--split-by-file
Similar to --split-by-reloc but creates a new output section for each input file.
--split-by-reloc count
Trys to creates extra sections in the output file so that no single output section in the file contains more than count relocations. This is useful when generating huge relocatable for downloading into certain real time kernels with the COFF object file format; since COFF cannot represent more than 65535 relocations in a single section. Note that this will fail to work with object file formats which do not support arbitrary sections. The linker will not split up individual input sections for redistribution, so if a single input section contains more than count relocations one output section will contain that many relocations.
--stats
Compute and display statistics about the operation of the linker, such as execution time and memory usage.
--traditional-format
For some targets, the output of ld is different in some ways from the output of some existing linker. This switch requests ld to use the traditional format instead. For example, on SunOS, ld combines duplicate entries in the symbol string table. This can reduce the size of an output file with full debugging information by over 30 percent. Unfortunately, the SunOS dbx program can not read the resulting program (gdb has no trouble). The `--traditional-format' switch tells ld to not combine duplicate entries.
-Tbss org
-Tdata org
-Ttext org
Use org as the starting address for--respectively--the bss, data, or the text segment of the output file. org must be a single hexadecimal integer; for compatibility with other linkers, you may omit the leading `0x' usually associated with hexadecimal values.
-Ur
For anything other than C++ programs, this option is equivalent to `-r': it generates relocatable output--i.e., an output file that can in turn serve as input to ld. When linking C++ programs, `-Ur' does resolve references to constructors, unlike `-r'. It does not work to use `-Ur' on files that were themselves linked with `-Ur'; once the constructor table has been built, it cannot be added to. Use `-Ur' only for the last partial link, and `-r' for the others.
--verbose
Display the version number for ld and list the linker emulations supported. Display which input files can and cannot be opened. Display the linker script if using a default builtin script.
--version-script=version-scriptfile
Specify the name of a version script to the linker. This is typically used when creating shared libraries to specify additional information about the version heirarchy for the library being created. This option is only meaningful on ELF platforms which support shared libraries. See section Version Script.
--warn-common
Warn when a common symbol is combined with another common symbol or with a symbol definition. Unix linkers allow this somewhat sloppy practice, but linkers on some other operating systems do not. This option allows you to find potential problems from combining global symbols. Unfortunately, some C libraries use this practice, so you may get some warnings about symbols in the libraries as well as in your programs. There are three kinds of global symbols, illustrated here by C examples:
`int i = 1;'
A definition, which goes in the initialized data section of the output file.
`extern int i;'
An undefined reference, which does not allocate space. There must be either a definition or a common symbol for the variable somewhere.
`int i;'
A common symbol. If there are only (one or more) common symbols for a variable, it goes in the uninitialized data area of the output file. The linker merges multiple common symbols for the same variable into a single symbol. If they are of different sizes, it picks the largest size. The linker turns a common symbol into a declaration, if there is a definition of the same variable.
The `--warn-common' option can produce five kinds of warnings. Each warning consists of a pair of lines: the first describes the symbol just encountered, and the second describes the previous symbol encountered with the same name. One or both of the two symbols will be a common symbol.
  1. Turning a common symbol into a reference, because there is already a definition for the symbol.
    file(section): warning: common of `symbol'
   overridden by definition
file(section): warning: defined here
  2. Turning a common symbol into a reference, because a later definition for the symbol is encountered. This is the same as the previous case, except that the symbols are encountered in a different order.
    file(section): warning: definition of `symbol'
   overriding common
file(section): warning: common is here
  3. Merging a common symbol with a previous same-sized common symbol.
    file(section): warning: multiple common
   of `symbol'
file(section): warning: previous common is here
  4. Merging a common symbol with a previous larger common symbol.
    file(section): warning: common of `symbol'
   overridden by larger common
file(section): warning: larger common is here
  5. Merging a common symbol with a previous smaller common symbol. This is the same as the previous case, except that the symbols are encountered in a different order.
    file(section): warning: common of `symbol'
   overriding smaller common
file(section): warning: smaller common is here
--warn-constructors
Warn if any global constructors are used. This is only useful for a few object file formats. For formats like COFF or ELF, the linker can not detect the use of global constructors.
--warn-multiple-gp
Warn if multiple global pointer values are required in the output file. This is only meaningful for certain processors, such as the Alpha. Specifically, some processors put large-valued constants in a special section. A special register (the global pointer) points into the middle of this section, so that constants can be loaded efficiently via a base-register relative addressing mode. Since the offset in base-register relative mode is fixed and relatively small (e.g., 16 bits), this limits the maximum size of the constant pool. Thus, in large programs, it is often necessary to use multiple global pointer values in order to be able to address all possible constants. This option causes a warning to be issued whenever this case occurs.
--warn-once
Only warn once for each undefined symbol, rather than once per module which refers to it.
--warn-section-align
Warn if the address of an output section is changed because of alignment. Typically, the alignment will be set by an input section. The address will only be changed if it not explicitly specified; that is, if the SECTIONS command does not specify a start address for the section (see section Specifying Output Sections).
--whole-archive
For each archive mentioned on the command line after the --whole-archive option, include every object file in the archive in the link, rather than searching the archive for the required object files. This is normally used to turn an archive file into a shared library, forcing every object to be included in the resulting shared library. This option may be used more than once.
--wrap symbol
Use a wrapper function for symbol. Any undefined reference to symbol will be resolved to __wrap_symbol. Any undefined reference to __real_symbol will be resolved to symbol. This can be used to provide a wrapper for a system function. The wrapper function should be called __wrap_symbol. If it wishes to call the system function, it should call __real_symbol. Here is a trivial example:
void *
__wrap_malloc (int c)
{
  printf ("malloc called with %ld\n", c);
  return __real_malloc (c);
}
If you link other code with this file using --wrap malloc, then all calls to malloc will call the function __wrap_malloc instead. The call to __real_malloc in __wrap_malloc will call the real malloc function. You may wish to provide a __real_malloc function as well, so that links without the --wrap option will succeed. If you do this, you should not put the definition of __real_malloc in the same file as __wrap_malloc; if you do, the assembler may resolve the call before the linker has a chance to wrap it to malloc.

Environment Variables

You can change the behavior of ld with the environment variables GNUTARGET and LDEMULATION.

GNUTARGET determines the input-file object format if you don't use `-b' (or its synonym `--format'). Its value should be one of the BFD names for an input format (see section BFD). If there is no GNUTARGET in the environment, ld uses the natural format of the target. If GNUTARGET is set to default then BFD attempts to discover the input format by examining binary input files; this method often succeeds, but there are potential ambiguities, since there is no method of ensuring that the magic number used to specify object-file formats is unique. However, the configuration procedure for BFD on each system places the conventional format for that system first in the search-list, so ambiguities are resolved in favor of convention.

LDEMULATION determines the default emulation if you don't use the `-m' option. The emulation can affect various aspects of linker behaviour, particularly the default linker script. You can list the available emulations with the `--verbose' or `-V' options. If the `-m' option is not used, and the LDEMULATION environment variable is not defined, the default emulation depends upon how the linker was configured.

Command Language

The command language provides explicit control over the link process, allowing complete specification of the mapping between the linker's input files and its output. It controls:

  • input files
  • file formats
  • output file layout
  • addresses of sections
  • placement of common blocks

You may supply a command file (also known as a linker script) to the linker either explicitly through the `-T' option, or implicitly as an ordinary file. Normally you should use the `-T' option. An implicit linker script should only be used when you want to augment, rather than replace, the default linker script; typically an implicit linker script would consist only of INPUT or GROUP commands.

If the linker opens a file which it cannot recognize as a supported object or archive format, nor as a linker script, it reports an error.

Linker Scripts

The ld command language is a collection of statements; some are simple keywords setting a particular option, some are used to select and group input files or name output files; and two statement types have a fundamental and pervasive impact on the linking process.

The most fundamental command of the ld command language is the SECTIONS command (see section Specifying Output Sections). Every meaningful command script must have a SECTIONS command: it specifies a "picture" of the output file's layout, in varying degrees of detail. No other command is required in all cases.

The MEMORY command complements SECTIONS by describing the available memory in the target architecture. This command is optional; if you don't use a MEMORY command, ld assumes sufficient memory is available in a contiguous block for all output. See section Memory Layout.

You may include comments in linker scripts just as in C: delimited by `/*' and `*/'. As in C, comments are syntactically equivalent to whitespace.

Expressions

Many useful commands involve arithmetic expressions. The syntax for expressions in the command language is identical to that of C expressions, with the following features:

  • All expressions evaluated as integers and are of "long" or "unsigned long" type.
  • All constants are integers.
  • All of the C arithmetic operators are provided.
  • You may reference, define, and create global variables.
  • You may call special purpose built-in functions.

Integers

An octal integer is `0' followed by zero or more of the octal digits (`01234567').

_as_octal = 0157255;

A decimal integer starts with a non-zero digit followed by zero or more digits (`0123456789').

_as_decimal = 57005;

A hexadecimal integer is `0x' or `0X' followed by one or more hexadecimal digits chosen from `0123456789abcdefABCDEF'.

_as_hex = 0xdead;

To write a negative integer, use the prefix operator `-' (see section Operators).

_as_neg = -57005;

Additionally the suffixes K and M may be used to scale a constant by respectively. For example, the following all refer to the same quantity:

        _fourk_1 = 4K;
        _fourk_2 = 4096;
        _fourk_3 = 0x1000;

Symbol Names

Unless quoted, symbol names start with a letter, underscore, or point and may include any letters, underscores, digits, points, and hyphens. Unquoted symbol names must not conflict with any keywords. You can specify a symbol which contains odd characters or has the same name as a keyword, by surrounding the symbol name in double quotes:

        "SECTION" = 9;
        "with a space" = "also with a space" + 10;

Since symbols can contain many non-alphabetic characters, it is safest to delimit symbols with spaces. For example, `A-B' is one symbol, whereas `A - B' is an expression involving subtraction.

The Location Counter

The special linker variable dot `.' always contains the current output location counter. Since the . always refers to a location in an output section, it must always appear in an expression within a SECTIONS command. The . symbol may appear anywhere that an ordinary symbol is allowed in an expression, but its assignments have a side effect. Assigning a value to the . symbol will cause the location counter to be moved. This may be used to create holes in the output section. The location counter may never be moved backwards.

SECTIONS
{
  output :
  {
  file1(.text)
  . = . + 1000;
  file2(.text)
  . += 1000;
  file3(.text)
  } = 0x1234;
}

In the previous example, file1 is located at the beginning of the output section, then there is a 1000 byte gap. Then file2 appears, also with a 1000 byte gap following before file3 is loaded. The notation `= 0x1234' specifies what data to write in the gaps (see section Optional Section Attributes).

@vfill

Operators

The linker recognizes the standard C set of arithmetic operators, with the standard bindings and precedence levels: { @obeylines@parskip=0pt@parindent=0pt @dag@quad Prefix operators. @ddag@quad See section Assignment: Defining Symbols. }

Evaluation

The linker uses "lazy evaluation" for expressions; it only calculates an expression when absolutely necessary. The linker needs the value of the start address, and the lengths of memory regions, in order to do any linking at all; these values are computed as soon as possible when the linker reads in the command file. However, other values (such as symbol values) are not known or needed until after storage allocation. Such values are evaluated later, when other information (such as the sizes of output sections) is available for use in the symbol assignment expression.

Assignment: Defining Symbols

You may create global symbols, and assign values (addresses) to global symbols, using any of the C assignment operators:

symbol = expression ;
symbol &= expression ;
symbol += expression ;
symbol -= expression ;
symbol *= expression ;
symbol /= expression ;

Two things distinguish assignment from other operators in ld expressions.

  • Assignment may only be used at the root of an expression; `a=b+3;' is allowed, but `a+b=3;' is an error.
  • You must place a trailing semicolon (";") at the end of an assignment statement.

Assignment statements may appear:

  • as commands in their own right in an ld script; or
  • as independent statements within a SECTIONS command; or
  • as part of the contents of a section definition in a SECTIONS command.

The first two cases are equivalent in effect--both define a symbol with an absolute address. The last case defines a symbol whose address is relative to a particular section (see section Specifying Output Sections).

When a linker expression is evaluated and assigned to a variable, it is given either an absolute or a relocatable type. An absolute expression type is one in which the symbol contains the value that it will have in the output file; a relocatable expression type is one in which the value is expressed as a fixed offset from the base of a section.

The type of the expression is controlled by its position in the script file. A symbol assigned within a section definition is created relative to the base of the section; a symbol assigned in any other place is created as an absolute symbol. Since a symbol created within a section definition is relative to the base of the section, it will remain relocatable if relocatable output is requested. A symbol may be created with an absolute value even when assigned to within a section definition by using the absolute assignment function ABSOLUTE. For example, to create an absolute symbol whose address is the last byte of an output section named .data:

SECTIONS{ ...
  .data :
    {
      *(.data)
      _edata = ABSOLUTE(.) ;
    }
... }

The linker tries to put off the evaluation of an assignment until all the terms in the source expression are known (see section Evaluation). For instance, the sizes of sections cannot be known until after allocation, so assignments dependent upon these are not performed until after allocation. Some expressions, such as those depending upon the location counter dot, `.' must be evaluated during allocation. If the result of an expression is required, but the value is not available, then an error results. For example, a script like the following

SECTIONS { ...
  text 9+this_isnt_constant :
    { ...
    }
... }

will cause the error message "Non constant expression for initial address".

In some cases, it is desirable for a linker script to define a symbol only if it is referenced, and only if it is not defined by any object included in the link. For example, traditional linkers defined the symbol `etext'. However, ANSI C requires that the user be able to use `etext' as a function name without encountering an error. The PROVIDE keyword may be used to define a symbol, such as `etext', only if it is referenced but not defined. The syntax is PROVIDE(symbol = expression).

Arithmetic Functions

The command language includes a number of built-in functions for use in link script expressions.

ABSOLUTE(exp)
Return the absolute (non-relocatable, as opposed to non-negative) value of the expression exp. Primarily useful to assign an absolute value to a symbol within a section definition, where symbol values are normally section-relative.
ADDR(section)
Return the absolute address of the named section. Your script must previously have defined the location of that section. In the following example, symbol_1 and symbol_2 are assigned identical values:
SECTIONS{ ...
  .output1 :
    {
    start_of_output_1 = ABSOLUTE(.);
    ...
    }
  .output :
    {
    symbol_1 = ADDR(.output1);
    symbol_2 = start_of_output_1;
    }
... }
LOADADDR(section)
Return the absolute load address of the named section. This is normally the same as ADDR, but it may be different if the AT keyword is used in the section definition (see section Optional Section Attributes).
ALIGN(exp)
Return the result of the current location counter (.) aligned to the next exp boundary. exp must be an expression whose value is a power of two. This is equivalent to
(. + exp - 1) & ~(exp - 1)
ALIGN doesn't change the value of the location counter--it just does arithmetic on it. As an example, to align the output .data section to the next 0x2000 byte boundary after the preceding section and to set a variable within the section to the next 0x8000 boundary after the input sections:
SECTIONS{ ...
  .data ALIGN(0x2000): {
    *(.data)
    variable = ALIGN(0x8000);
  }
... }
The first use of ALIGN in this example specifies the location of a section because it is used as the optional start attribute of a section definition (see section Optional Section Attributes). The second use simply defines the value of a variable. The built-in NEXT is closely related to ALIGN.
DEFINED(symbol)
Return 1 if symbol is in the linker global symbol table and is defined, otherwise return 0. You can use this function to provide default values for symbols. For example, the following command-file fragment shows how to set a global symbol begin to the first location in the .text section--but if a symbol called begin already existed, its value is preserved:
SECTIONS{ ...
  .text : {
    begin = DEFINED(begin) ? begin : . ;
    ...
  }
... }
NEXT(exp)
Return the next unallocated address that is a multiple of exp. This function is closely related to ALIGN(exp); unless you use the MEMORY command to define discontinuous memory for the output file, the two functions are equivalent.
SIZEOF(section)
Return the size in bytes of the named section, if that section has been allocated. In the following example, symbol_1 and symbol_2 are assigned identical values:
SECTIONS{ ...
  .output {
    .start = . ;
    ...
    .end = . ;
    }
  symbol_1 = .end - .start ;
  symbol_2 = SIZEOF(.output);
... }
SIZEOF_HEADERS
sizeof_headers
Return the size in bytes of the output file's headers. You can use this number as the start address of the first section, if you choose, to facilitate paging.
MAX(exp1, exp2)
Returns the maximum of exp1 and exp2.
MIN(exp1, exp2)
Returns the minimum of exp1 and exp2.

Semicolons

Semicolons (";") are required in the following places. In all other places they can appear for aesthetic reasons but are otherwise ignored.

Assignment
Semicolons must appear at the end of assignment expressions. See section Assignment: Defining Symbols
PHDRS
Semicolons must appear at the end of a PHDRS statement. See section ELF Program Headers

Memory Layout

The linker's default configuration permits allocation of all available memory. You can override this configuration by using the MEMORY command. The MEMORY command describes the location and size of blocks of memory in the target. By using it carefully, you can describe which memory regions may be used by the linker, and which memory regions it must avoid. The linker does not shuffle sections to fit into the available regions, but does move the requested sections into the correct regions and issue errors when the regions become too full.

A command file may contain at most one use of the MEMORY command; however, you can define as many blocks of memory within it as you wish. The syntax is:

MEMORY
  {
    name (attr) : ORIGIN = origin, LENGTH = len
    ...
  }
name
is a name used internally by the linker to refer to the region. Any symbol name may be used. The region names are stored in a separate name space, and will not conflict with symbols, file names or section names. Use distinct names to specify multiple regions.
(attr)
is an optional list of attributes that specify whether to use a particular memory to place sections that are not listed in the linker script. Valid attribute lists must be made up of the characters "ALIRWX" that match section attributes. If you omit the attribute list, you may omit the parentheses around it as well. The attributes currently supported are:
`Letter'
Section Attribute
`R'
Read-only sections.
`W'
Read/write sections.
`X'
Sections containing executable code.
`A'
Allocated sections.
`I'
Initialized sections.
`L'
Same as I.
`!'
Invert the sense of any of the following attributes.
origin
is the start address of the region in physical memory. It is an expression that must evaluate to a constant before memory allocation is performed. The keyword ORIGIN may be abbreviated to org or o (but not, for example, `ORG').
len
is the size in bytes of the region (an expression). The keyword LENGTH may be abbreviated to len or l.

For example, to specify that memory has two regions available for allocation--one starting at 0 for 256 kilobytes, and the other starting at 0x40000000 for four megabytes. The rom memory region will get all sections without an explicit memory register that are either read-only or contain code, while the ram memory region will get the sections.

MEMORY
  {
  rom (rx)  : ORIGIN = 0, LENGTH = 256K
  ram (!rx) : org = 0x40000000, l = 4M
  }

Once you have defined a region of memory named mem, you can direct specific output sections there by using a command ending in `>mem' within the SECTIONS command (see section Optional Section Attributes). If the combined output sections directed to a region are too big for the region, the linker will issue an error message.

Specifying Output Sections

The SECTIONS command controls exactly where input sections are placed into output sections, their order in the output file, and to which output sections they are allocated.

You may use at most one SECTIONS command in a script file, but you can have as many statements within it as you wish. Statements within the SECTIONS command can do one of three things:

  • define the entry point;
  • assign a value to a symbol;
  • describe the placement of a named output section, and which input sections go into it.

You can also use the first two operations--defining the entry point and defining symbols--outside the SECTIONS command: see section The Entry Point, and section Assignment: Defining Symbols. They are permitted here as well for your convenience in reading the script, so that symbols and the entry point can be defined at meaningful points in your output-file layout.

If you do not use a SECTIONS command, the linker places each input section into an identically named output section in the order that the sections are first encountered in the input files. If all input sections are present in the first file, for example, the order of sections in the output file will match the order in the first input file.

Section Definitions

The most frequently used statement in the SECTIONS command is the section definition, which specifies the properties of an output section: its location, alignment, contents, fill pattern, and target memory region. Most of these specifications are optional; the simplest form of a section definition is

SECTIONS { ...
  secname : {
    contents
  }
... }

secname is the name of the output section, and contents a specification of what goes there--for example, a list of input files or sections of input files (see section Section Placement). The whitespace around secname is required, so that the section name is unambiguous. The other whitespace shown is optional. You do need the colon `:' and the braces `{}', however.

secname must meet the constraints of your output format. In formats which only support a limited number of sections, such as a.out, the name must be one of the names supported by the format (a.out, for example, allows only .text, .data or .bss). If the output format supports any number of sections, but with numbers and not names (as is the case for Oasys), the name should be supplied as a quoted numeric string. A section name may consist of any sequence of characters, but any name which does not conform to the standard ld symbol name syntax must be quoted. See section Symbol Names.

The special secname `/DISCARD/' may be used to discard input sections. Any sections which are assigned to an output section named `/DISCARD/' are not included in the final link output.

The linker will not create output sections which do not have any contents. This is for convenience when referring to input sections that may or may not exist. For example,

.foo { *(.foo) }

will only create a `.foo' section in the output file if there is a `.foo' section in at least one input file.

Section Placement

In a section definition, you can specify the contents of an output section by listing particular input files, by listing particular input-file sections, or by a combination of the two. You can also place arbitrary data in the section, and define symbols relative to the beginning of the section.

The contents of a section definition may include any of the following kinds of statement. You can include as many of these as you like in a single section definition, separated from one another by whitespace.

filename
You may simply name a particular input file to be placed in the current output section; all sections from that file are placed in the current section definition. If the file name has already been mentioned in another section definition, with an explicit section name list, then only those sections which have not yet been allocated are used. To specify a list of particular files by name:
.data : { afile.o bfile.o cfile.o }
The example also illustrates that multiple statements can be included in the contents of a section definition, since each file name is a separate statement.
filename( section )
filename( section , section, ... )
filename( section section ... )
You can name one or more sections from your input files, for insertion in the current output section. If you wish to specify a list of input-file sections inside the parentheses, separate the section names with whitespace.
* (section)
* (section, section, ...)
* (section section ...)
Instead of explicitly naming particular input files in a link control script, you can refer to all files from the ld command line: use `*' instead of a particular file name before the parenthesized input-file section list. If you have already explicitly included some files by name, `*' refers to all remaining files--those whose places in the output file have not yet been defined. For example, to copy sections 1 through 4 from an Oasys file into the .text section of an a.out file, and sections 13 and 14 into the .data section:
SECTIONS {
  .text :{
    *("1" "2" "3" "4")
  }

  .data :{
    *("13" "14")
  }
}
`[ section ... ]' used to be accepted as an alternate way to specify named sections from all unallocated input files. Because some operating systems (VMS) allow brackets in file names, that notation is no longer supported.
filename( COMMON )
*( COMMON )
Specify where in your output file to place uninitialized data with this notation. *(COMMON) by itself refers to all uninitialized data from all input files (so far as it is not yet allocated); filename(COMMON) refers to uninitialized data from a particular file. Both are special cases of the general mechanisms for specifying where to place input-file sections: ld permits you to refer to uninitialized data as if it were in an input-file section named COMMON, regardless of the input file's format.

In any place where you may use a specific file or section name, you may also use a wildcard pattern. The linker handles wildcards much as the Unix shell does. A `*' character matches any number of characters. A `?' character matches any single character. The sequence `[chars]' will match a single instance of any of the chars; the `-' character may be used to specify a range of characters, as in `[a-z]' to match any lower case letter. A `\' character may be used to quote the following character.

When a file name is matched with a wildcard, the wildcard characters will not match a `/' character (used to separate directory names on Unix). A pattern consisting of a single `*' character is an exception; it will always match any file name. In a section name, the wildcard characters will match a `/' character.

Wildcards only match files which are explicitly specified on the command line. The linker does not search directories to expand wildcards. However, if you specify a simple file name--a name with no wildcard characters--in a linker script, and the file name is not also specified on the command line, the linker will attempt to open the file as though it appeared on the command line.

In the following example, the command script arranges the output file into three consecutive sections, named .text, .data, and .bss, taking the input for each from the correspondingly named sections of all the input files:

SECTIONS {
  .text : { *(.text) }
  .data : { *(.data) }
  .bss :  { *(.bss)  *(COMMON) }
}

The following example reads all of the sections from file all.o and places them at the start of output section outputa which starts at location 0x10000. All of section .input1 from file foo.o follows immediately, in the same output section. All of section .input2 from foo.o goes into output section outputb, followed by section .input1 from foo1.o. All of the remaining .input1 and .input2 sections from any files are written to output section outputc.

SECTIONS {
  outputa 0x10000 :
    {
    all.o
    foo.o (.input1)
    }
  outputb :
    {
    foo.o (.input2)
    foo1.o (.input1)
    }
  outputc :
    {
    *(.input1)
    *(.input2)
    }
}

This example shows how wildcard patterns might be used to partition files. All .text sections are placed in .text, and all .bss sections are placed in .bss. For all files beginning with an upper case character, the .data section is placed into .DATA; for all other files, the .data section is placed into .data.

SECTIONS {
  .text : { *(.text) }
  .DATA : { [A-Z]*(.data) }
  .data : { *(.data) }
  .bss : { *(.bss) }
}

Section Data Expressions

The foregoing statements arrange, in your output file, data originating from your input files. You can also place data directly in an output section from the link command script. Most of these additional statements involve expressions (see section Expressions). Although these statements are shown separately here for ease of presentation, no such segregation is needed within a section definition in the SECTIONS command; you can intermix them freely with any of the statements we've just described.

CREATE_OBJECT_SYMBOLS
Create a symbol for each input file in the current section, set to the address of the first byte of data written from that input file. For instance, with a.out files it is conventional to have a symbol for each input file. You can accomplish this by defining the output .text section as follows:
SECTIONS {
  .text 0x2020 :
     {
    CREATE_OBJECT_SYMBOLS
    *(.text)
    _etext = ALIGN(0x2000);
    }
  ...
}
If sample.ld is a file containing this script, and a.o, b.o, c.o, and d.o are four input files with contents like the following---
/* a.c */

afunction() { }
int adata=1;
int abss;
`ld -M -T sample.ld a.o b.o c.o d.o' would create a map like this, containing symbols matching the object file names:
00000000 A __DYNAMIC
00004020 B _abss
00004000 D _adata
00002020 T _afunction
00004024 B _bbss
00004008 D _bdata
00002038 T _bfunction
00004028 B _cbss
00004010 D _cdata
00002050 T _cfunction
0000402c B _dbss
00004018 D _ddata
00002068 T _dfunction
00004020 D _edata
00004030 B _end
00004000 T _etext
00002020 t a.o
00002038 t b.o
00002050 t c.o
00002068 t d.o
symbol = expression ;
symbol f= expression ;
symbol is any symbol name (see section Symbol Names). "f=" refers to any of the operators &= += -= *= /= which combine arithmetic and assignment. When you assign a value to a symbol within a particular section definition, the value is relative to the beginning of the section (see section Assignment: Defining Symbols). If you write
SECTIONS {
  abs = 14 ;
  ...
  .data : { ... rel = 14 ; ... }
  abs2 = 14 + ADDR(.data);
  ...
}
abs and rel do not have the same value; rel has the same value as abs2.
BYTE(expression)
SHORT(expression)
LONG(expression)
QUAD(expression)
SQUAD(expression)
By including one of these four statements in a section definition, you can explicitly place one, two, four, eight unsigned, or eight signed bytes (respectively) at the current address of that section. When using a 64 bit host or target, QUAD and SQUAD are the same. When both host and target are 32 bits, QUAD uses an unsigned 32 bit value, and SQUAD sign extends the value. Both will use the correct endianness when writing out the value. Multiple-byte quantities are represented in whatever byte order is appropriate for the output file format (see section BFD).
FILL(expression)
Specify the "fill pattern" for the current section. Any otherwise unspecified regions of memory within the section (for example, regions you skip over by assigning a new value to the location counter `.') are filled with the two least significant bytes from the expression argument. A FILL statement covers memory locations after the point it occurs in the section definition; by including more than one FILL statement, you can have different fill patterns in different parts of an output section.

Optional Section Attributes

Here is the full syntax of a section definition, including all the optional portions:

SECTIONS {
...
secname start BLOCK(align) (NOLOAD) : AT ( ldadr )
  { contents } >region :phdr =fill
...
}

secname and contents are required. See section Section Definitions, and section Section Placement, for details on contents. The remaining elements---start, BLOCK(align), (NOLOAD), AT ( ldadr ), >region, :phdr, and =fill---are all optional.

start
You can force the output section to be loaded at a specified address by specifying start immediately following the section name. start can be represented as any expression. The following example generates section output at location 0x40000000:
SECTIONS {
  ...
  output 0x40000000: {
    ...
    }
  ...
}
BLOCK(align)
You can include BLOCK() specification to advance the location counter . prior to the beginning of the section, so that the section will begin at the specified alignment. align is an expression.
(NOLOAD)
The `(NOLOAD)' directive will mark a section to not be loaded at run time. The linker will process the section normally, but will mark it so that a program loader will not load it into memory. For example, in the script sample below, the ROM section is addressed at memory location `0' and does not need to be loaded when the program is run. The contents of the ROM section will appear in the linker output file as usual.
SECTIONS {
  ROM  0  (NOLOAD)  : { ... }
  ...
}
AT ( ldadr )
The expression ldadr that follows the AT keyword specifies the load address of the section. The default (if you do not use the AT keyword) is to make the load address the same as the relocation address. This feature is designed to make it easy to build a ROM image. For example, this SECTIONS definition creates two output sections: one called `.text', which starts at 0x1000, and one called `.mdata', which is loaded at the end of the `.text' section even though its relocation address is 0x2000. The symbol _data is defined with the value 0x2000:
SECTIONS
  {
  .text 0x1000 : { *(.text) _etext = . ; }
  .mdata 0x2000 :
    AT ( ADDR(.text) + SIZEOF ( .text ) )
    { _data = . ; *(.data); _edata = . ;  }
  .bss 0x3000 :
    { _bstart = . ;  *(.bss) *(COMMON) ; _bend = . ;}
}
The run-time initialization code (for C programs, usually crt0) for use with a ROM generated this way has to include something like the following, to copy the initialized data from the ROM image to its runtime address:
char *src = _etext;
char *dst = _data;

/* ROM has data at end of text; copy it. */
while (dst < _edata) {
  *dst++ = *src++;
}

/* Zero bss */
for (dst = _bstart; dst< _bend; dst++)
  *dst = 0;
>region
Assign this section to a previously defined region of memory. See section Memory Layout.
:phdr
Assign this section to a segment described by a program header. See section ELF Program Headers. If a section is assigned to one or more segments, then all subsequent allocated sections will be assigned to those segments as well, unless they use an explicitly :phdr modifier. To prevent a section from being assigned to a segment when it would normally default to one, use :NONE.
=fill
Including =fill in a section definition specifies the initial fill value for that section. You may use any expression to specify fill. Any unallocated holes in the current output section when written to the output file will be filled with the two least significant bytes of the value, repeated as necessary. You can also change the fill value with a FILL statement in the contents of a section definition.

Overlays

The OVERLAY command provides an easy way to describe sections which are to be loaded as part of a single memory image but are to be run at the same memory address. At run time, some sort of overlay manager will copy the overlaid sections in and out of the runtime memory address as required, perhaps by simply manipulating addressing bits. This approach can be useful, for example, when a certain region of memory is faster than another.

The OVERLAY command is used within a SECTIONS command. It appears as follows:

  OVERLAY start : [ NOCROSSREFS ] AT ( ldaddr )
   {
     secname1 { contents } :phdr =fill
     secname2 { contents } :phdr =fill
     ...
   } >region :phdr =fill

Everything is optional except OVERLAY (a keyword), and each section must have a name (secname1 and secname2 above). The section definitions within the OVERLAY construct are identical to those within the general SECTIONS contruct (see section Specifying Output Sections), except that no addresses and no memory regions may be defined for sections within an OVERLAY.

The sections are all defined with the same starting address. The load addresses of the sections are arranged such that they are consecutive in memory starting at the load address used for the OVERLAY as a whole (as with normal section definitions, the load address is optional, and defaults to the start address; the start address is also optional, and defaults to .).

If the NOCROSSREFS keyword is used, and there any references among the sections, the linker will report an error. Since the sections all run at the same address, it normally does not make sense for one section to refer directly to another. See section Option Commands.

For each section within the OVERLAY, the linker automatically defines two symbols. The symbol __load_start_secname is defined as the starting load address of the section. The symbol __load_stop_secname is defined as the final load address of the section. Any characters within secname which are not legal within C identifiers are removed. C (or assembler) code may use these symbols to move the overlaid sections around as necessary.

At the end of the overlay, the value of . is set to the start address of the overlay plus the size of the largest section.

Here is an example. Remember that this would appear inside a SECTIONS construct.

  OVERLAY 0x1000 : AT (0x4000)
   {
     .text0 { o1/*.o(.text) }
     .text1 { o2/*.o(.text) }
   }

This will define both .text0 and .text1 to start at address 0x1000. .text0 will be loaded at address 0x4000, and .text1 will be loaded immediately after .text0. The following symbols will be defined: __load_start_text0, __load_stop_text0, __load_start_text1, __load_stop_text1.

C code to copy overlay .text1 into the overlay area might look like the following.

  extern char __load_start_text1, __load_stop_text1;
  memcpy ((char *) 0x1000, &__load_start_text1,
          &__load_stop_text1 - &__load_start_text1);

Note that the OVERLAY command is just syntactic sugar, since everything it does can be done using the more basic commands. The above example could have been written identically as follows.

  .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
  __load_start_text0 = LOADADDR (.text0);
  __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
  .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
  __load_start_text1 = LOADADDR (.text1);
  __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
  . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));

ELF Program Headers

The ELF object file format uses program headers, which are read by the system loader and describe how the program should be loaded into memory. These program headers must be set correctly in order to run the program on a native ELF system. The linker will create reasonable program headers by default. However, in some cases, it is desirable to specify the program headers more precisely; the PHDRS command may be used for this purpose. When the PHDRS command is used, the linker will not generate any program headers itself.

The PHDRS command is only meaningful when generating an ELF output file. It is ignored in other cases. This manual does not describe the details of how the system loader interprets program headers; for more information, see the ELF ABI. The program headers of an ELF file may be displayed using the `-p' option of the objdump command.

This is the syntax of the PHDRS command. The words PHDRS, FILEHDR, AT, and FLAGS are keywords.

PHDRS
{
  name type [ FILEHDR ] [ PHDRS ] [ AT ( address ) ]
        [ FLAGS ( flags ) ] ;
}

The name is used only for reference in the SECTIONS command of the linker script. It does not get put into the output file.

Certain program header types describe segments of memory which are loaded from the file by the system loader. In the linker script, the contents of these segments are specified by directing allocated output sections to be placed in the segment. To do this, the command describing the output section in the SECTIONS command should use `:name', where name is the name of the program header as it appears in the PHDRS command. See section Optional Section Attributes.

It is normal for certain sections to appear in more than one segment. This merely implies that one segment of memory contains another. This is specified by repeating `:name', using it once for each program header in which the section is to appear.

If a section is placed in one or more segments using `:name', then all subsequent allocated sections which do not specify `:name' are placed in the same segments. This is for convenience, since generally a whole set of contiguous sections will be placed in a single segment. To prevent a section from being assigned to a segment when it would normally default to one, use :NONE.

The FILEHDR and PHDRS keywords which may appear after the program header type also indicate contents of the segment of memory. The FILEHDR keyword means that the segment should include the ELF file header. The PHDRS keyword means that the segment should include the ELF program headers themselves.

The type may be one of the following. The numbers indicate the value of the keyword.

PT_NULL (0)
Indicates an unused program header.
PT_LOAD (1)
Indicates that this program header describes a segment to be loaded from the file.
PT_DYNAMIC (2)
Indicates a segment where dynamic linking information can be found.
PT_INTERP (3)
Indicates a segment where the name of the program interpreter may be found.
PT_NOTE (4)
Indicates a segment holding note information.
PT_SHLIB (5)
A reserved program header type, defined but not specified by the ELF ABI.
PT_PHDR (6)
Indicates a segment where the program headers may be found.
expression
An expression giving the numeric type of the program header. This may be used for types not defined above.

It is possible to specify that a segment should be loaded at a particular address in memory. This is done using an AT expression. This is identical to the AT command used in the SECTIONS command (see section Optional Section Attributes). Using the AT command for a program header overrides any information in the SECTIONS command.

Normally the segment flags are set based on the sections. The FLAGS keyword may be used to explicitly specify the segment flags. The value of flags must be an integer. It is used to set the p_flags field of the program header.

Here is an example of the use of PHDRS. This shows a typical set of program headers used on a native ELF system.

PHDRS
{
  headers PT_PHDR PHDRS ;
  interp PT_INTERP ;
  text PT_LOAD FILEHDR PHDRS ;
  data PT_LOAD ;
  dynamic PT_DYNAMIC ;
}

SECTIONS
{
  . = SIZEOF_HEADERS;
  .interp : { *(.interp) } :text :interp
  .text : { *(.text) } :text
  .rodata : { *(.rodata) } /* defaults to :text */
  ...
  . = . + 0x1000; /* move to a new page in memory */
  .data : { *(.data) } :data
  .dynamic : { *(.dynamic) } :data :dynamic
  ...
}

The Entry Point

The linker command language includes a command specifically for defining the first executable instruction in an output file (its entry point). Its argument is a symbol name:

ENTRY(symbol)

Like symbol assignments, the ENTRY command may be placed either as an independent command in the command file, or among the section definitions within the SECTIONS command--whatever makes the most sense for your layout.

ENTRY is only one of several ways of choosing the entry point. You may indicate it in any of the following ways (shown in descending order of priority: methods higher in the list override methods lower down).

  • the `-e' entry command-line option;
  • the ENTRY(symbol) command in a linker control script;
  • the value of the symbol start, if present;
  • the address of the first byte of the .text section, if present;
  • The address 0.

For example, you can use these rules to generate an entry point with an assignment statement: if no symbol start is defined within your input files, you can simply define it, assigning it an appropriate value---

start = 0x2020;

The example shows an absolute address, but you can use any expression. For example, if your input object files use some other symbol-name convention for the entry point, you can just assign the value of whatever symbol contains the start address to start:

start = other_symbol ;

Version Script

The linker command script includes a command specifically for specifying a version script, and is only meaningful for ELF platforms that support shared libraries. A version script can be build directly into the linker script that you are using, or you can supply the version script as just another input file to the linker at the time that you link. The command script syntax is:

VERSION { version script contents }

The version script can also be specified to the linker by means of the `--version-script' linker command line option. Version scripts are only meaningful when creating shared libraries.

The format of the version script itself is identical to that used by Sun's linker in Solaris 2.5. Versioning is done by defining a tree of version nodes with the names and interdependencies specified in the version script. The version script can specify which symbols are bound to which version nodes, and it can reduce a specified set of symbols to local scope so that they are not globally visible outside of the shared library.

The easiest way to demonstrate the version script language is with a few examples.

VERS_1.1 {
     global:
         foo1;
     local:
         old*;
         original*;
         new*;
};

VERS_1.2 {
         foo2;
} VERS_1.1;

VERS_2.0 {
         bar1; bar2;
} VERS_1.2;

In this example, three version nodes are defined. `VERS_1.1' is the first version node defined, and has no other dependencies. The symbol `foo1' is bound to this version node, and a number of symbols that have appeared within various object files are reduced in scope to local so that they are not visible outside of the shared library.

Next, the node `VERS_1.2' is defined. It depends upon `VERS_1.1'. The symbol `foo2' is bound to this version node.

Finally, the node `VERS_2.0' is defined. It depends upon `VERS_1.2'. The symbols `bar1' and `bar2' are bound to this version node.

Symbols defined in the library which aren't specifically bound to a version node are effectively bound to an unspecified base version of the library. It is possible to bind all otherwise unspecified symbols to a given version node using `global: *' somewhere in the version script.

Lexically the names of the version nodes have no specific meaning other than what they might suggest to the person reading them. The `2.0' version could just as well have appeared in between `1.1' and `1.2'. However, this would be a confusing way to write a version script.

When you link an application against a shared library that has versioned symbols, the application itself knows which version of each symbol it requires, and it also knows which version nodes it needs from each shared library it is linked against. Thus at runtime, the dynamic loader can make a quick check to make sure that the libraries you have linked against do in fact supply all of the version nodes that the application will need to resolve all of the dynamic symbols. In this way it is possible for the dynamic linker to know with certainty that all external symbols that it needs will be resolvable without having to search for each symbol reference.

The symbol versioning is in effect a much more sophisticated way of doing minor version checking that SunOS does. The fundamental problem that is being addressed here is that typically references to external functions are bound on an as-needed basis, and are not all bound when the application starts up. If a shared library is out of date, a required interface may be missing; when the application tries to use that interface, it may suddenly and unexpectedly fail. With symbol versioning, the user will get a warning when they start their program if the libraries being used with the application are too old.

There are several GNU extensions to Sun's versioning approach. The first of these is the ability to bind a symbol to a version node in the source file where the symbol is defined instead of in the versioning script. This was done mainly to reduce the burden on the library maintainer. This can be done by putting something like:

__asm__(".symver original_foo,foo@VERS_1.1");

in the C source file. This renamed the function `original_foo' to be an alias for `foo' bound to the version node `VERS_1.1'. The `local:' directive can be used to prevent the symbol `original_foo' from being exported.

The second GNU extension is to allow multiple versions of the same function to appear in a given shared library. In this way an incompatible change to an interface can take place without increasing the major version number of the shared library, while still allowing applications linked against the old interface to continue to function.

This can only be accomplished by using multiple `.symver' directives in the assembler. An example of this would be:

__asm__(".symver original_foo,foo@");
__asm__(".symver old_foo,foo@VERS_1.1");
__asm__(".symver old_foo1,foo@VERS_1.2");
__asm__(".symver new_foo,foo@@VERS_2.0");

In this example, `foo@' represents the symbol `foo' bound to the unspecified base version of the symbol. The source file that contains this example would define 4 C functions: `original_foo', `old_foo', `old_foo1', and `new_foo'.

When you have multiple definitions of a given symbol, there needs to be some way to specify a default version to which external references to this symbol will be bound. This can be accomplished with the `foo@@VERS_2.0' type of `.symver' directive. Only one version of a symbol can be declared 'default' in this manner - otherwise you would effectively have multiple definitions of the same symbol.

If you wish to bind a reference to a specific version of the symbol within the shared library, you can use the aliases of convenience (i.e. `old_foo'), or you can use the `.symver' directive to specifically bind to an external version of the function in question.

Option Commands

The command language includes a number of other commands that you can use for specialized purposes. They are similar in purpose to command-line options.

CONSTRUCTORS
When linking using the a.out object file format, the linker uses an unusual set construct to support C++ global constructors and destructors. When linking object file formats which do not support arbitrary sections, such as ECOFF and XCOFF, the linker will automatically recognize C++ global constructors and destructors by name. For these object file formats, the CONSTRUCTORS command tells the linker where this information should be placed. The CONSTRUCTORS command is ignored for other object file formats. The symbol __CTOR_LIST__ marks the start of the global constructors, and the symbol __DTOR_LIST marks the end. The first word in the list is the number of entries, followed by the address of each constructor or destructor, followed by a zero word. The compiler must arrange to actually run the code. For these object file formats GNU C++ calls constructors from a subroutine __main; a call to __main is automatically inserted into the startup code for main. GNU C++ runs destructors either by using atexit, or directly from the function exit. For object file formats such as COFF or ELF which support multiple sections, GNU C++ will normally arrange to put the addresses of global constructors and destructors into the .ctors and .dtors sections. Placing the following sequence into your linker script will build the sort of table which the GNU C++ runtime code expects to see.
      __CTOR_LIST__ = .;
      LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
      *(.ctors)
      LONG(0)
      __CTOR_END__ = .;
      __DTOR_LIST__ = .;
      LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
      *(.dtors)
      LONG(0)
      __DTOR_END__ = .;
Normally the compiler and linker will handle these issues automatically, and you will not need to concern yourself with them. However, you may need to consider this if you are using C++ and writing your own linker scripts.
FLOAT
NOFLOAT
These keywords were used in some older linkers to request a particular math subroutine library. ld doesn't use the keywords, assuming instead that any necessary subroutines are in libraries specified using the general mechanisms for linking to archives; but to permit the use of scripts that were written for the older linkers, the keywords FLOAT and NOFLOAT are accepted and ignored.
FORCE_COMMON_ALLOCATION
This command has the same effect as the `-d' command-line option: to make ld assign space to common symbols even if a relocatable output file is specified (`-r').
INCLUDE filename
Include the linker script filename at this point. The file will be searched for in the current directory, and in any directory specified with the -L option. You can nest calls to INCLUDE up to 10 levels deep.
INPUT ( file, file, ... )
INPUT ( file file ... )
Use this command to include binary input files in the link, without including them in a particular section definition. Specify the full name for each file, including `.a' if required. ld searches for each file through the archive-library search path, just as for files you specify on the command line. See the description of `-L' in section Command Line Options. If you use `-lfile', ld will transform the name to libfile.a as with the command line argument `-l'.
GROUP ( file, file, ... )
GROUP ( file file ... )
This command is like INPUT, except that the named files should all be archives, and they are searched repeatedly until no new undefined references are created. See the description of `-(' in section Command Line Options.
OUTPUT ( filename )
Use this command to name the link output file filename. The effect of OUTPUT(filename) is identical to the effect of `-o filename', which overrides it. You can use this command to supply a default output-file name other than a.out.
OUTPUT_ARCH ( bfdname )
Specify a particular output machine architecture, with one of the names used by the BFD back-end routines (see section BFD). This command is often unnecessary; the architecture is most often set implicitly by either the system BFD configuration or as a side effect of the OUTPUT_FORMAT command.
OUTPUT_FORMAT ( bfdname )
When ld is configured to support multiple object code formats, you can use this command to specify a particular output format. bfdname is one of the names used by the BFD back-end routines (see section BFD). The effect is identical to the effect of the `--oformat' command-line option. This selection affects only the output file; the related command TARGET affects primarily input files.
SEARCH_DIR ( path )
Add path to the list of paths where ld looks for archive libraries. SEARCH_DIR(path) has the same effect as `-Lpath' on the command line.
STARTUP ( filename )
Ensure that filename is the first input file used in the link process.
TARGET ( format )
When ld is configured to support multiple object code formats, you can use this command to change the input-file object code format (like the command-line option `-b' or its synonym `--format'). The argument format is one of the strings used by BFD to name binary formats. If TARGET is specified but OUTPUT_FORMAT is not, the last TARGET argument is also used as the default format for the ld output file. See section BFD. If you don't use the TARGET command, ld uses the value of the environment variable GNUTARGET, if available, to select the output file format. If that variable is also absent, ld uses the default format configured for your machine in the BFD libraries.
NOCROSSREFS ( section section ... )
This command may be used to tell ld to issue an error about any references among certain sections. In certain types of programs, particularly on embedded systems, when one section is loaded into memory, another section will not be. Any direct references between the two sections would be errors. For example, it would be an error if code in one section called a function defined in the other section. The NOCROSSREFS command takes a list of section names. If ld detects any cross references between the sections, it reports an error and returns a non-zero exit status. The NOCROSSREFS command uses output section names, defined in the SECTIONS command. It does not use the names of input sections.

Machine Dependent Features

ld has additional features on some platforms; the following sections describe them. Machines where ld has no additional functionality are not listed.

ld and the H8/300

For the H8/300, ld can perform these global optimizations when you specify the `--relax' command-line option.

relaxing address modes
ld finds all jsr and jmp instructions whose targets are within eight bits, and turns them into eight-bit program-counter relative bsr and bra instructions, respectively.
synthesizing instructions
ld finds all mov.b instructions which use the sixteen-bit absolute address form, but refer to the top page of memory, and changes them to use the eight-bit address form. (That is: the linker turns `mov.b @aa:16' into `mov.b @aa:8' whenever the address aa is in the top page of memory).

ld and the Intel 960 family

You can use the `-Aarchitecture' command line option to specify one of the two-letter names identifying members of the 960 family; the option specifies the desired output target, and warns of any incompatible instructions in the input files. It also modifies the linker's search strategy for archive libraries, to support the use of libraries specific to each particular architecture, by including in the search loop names suffixed with the string identifying the architecture.

For example, if your ld command line included `-ACA' as well as `-ltry', the linker would look (in its built-in search paths, and in any paths you specify with `-L') for a library with the names

try
libtry.a
tryca
libtryca.a

The first two possibilities would be considered in any event; the last two are due to the use of `-ACA'.

You can meaningfully use `-A' more than once on a command line, since the 960 architecture family allows combination of target architectures; each use will add another pair of name variants to search for when `-l' specifies a library.

ld supports the `--relax' option for the i960 family. If you specify `--relax', ld finds all balx and calx instructions whose targets are within 24 bits, and turns them into 24-bit program-counter relative bal and cal instructions, respectively. ld also turns cal instructions into bal instructions when it determines that the target subroutine is a leaf routine (that is, the target subroutine does not itself call any subroutines).

BFD

The linker accesses object and archive files using the BFD libraries. These libraries allow the linker to use the same routines to operate on object files whatever the object file format. A different object file format can be supported simply by creating a new BFD back end and adding it to the library. To conserve runtime memory, however, the linker and associated tools are usually configured to support only a subset of the object file formats available. You can use objdump -i (see section `objdump' in The GNU Binary Utilities) to list all the formats available for your configuration.

As with most implementations, BFD is a compromise between several conflicting requirements. The major factor influencing BFD design was efficiency: any time used converting between formats is time which would not have been spent had BFD not been involved. This is partly offset by abstraction payback; since BFD simplifies applications and back ends, more time and care may be spent optimizing algorithms for a greater speed.

One minor artifact of the BFD solution which you should bear in mind is the potential for information loss. There are two places where useful information can be lost using the BFD mechanism: during conversion and during output. See section Information Loss.

How it works: an outline of BFD

When an object file is opened, BFD subroutines automatically determine the format of the input object file. They then build a descriptor in memory with pointers to routines that will be used to access elements of the object file's data structures.

As different information from the the object files is required, BFD reads from different sections of the file and processes them. For example, a very common operation for the linker is processing symbol tables. Each BFD back end provides a routine for converting between the object file's representation of symbols and an internal canonical format. When the linker asks for the symbol table of an object file, it calls through a memory pointer to the routine from the relevant BFD back end which reads and converts the table into a canonical form. The linker then operates upon the canonical form. When the link is finished and the linker writes the output file's symbol table, another BFD back end routine is called to take the newly created symbol table and convert it into the chosen output format.

Information Loss

Information can be lost during output. The output formats supported by BFD do not provide identical facilities, and information which can be described in one form has nowhere to go in another format. One example of this is alignment information in b.out. There is nowhere in an a.out format file to store alignment information on the contained data, so when a file is linked from b.out and an a.out image is produced, alignment information will not propagate to the output file. (The linker will still use the alignment information internally, so the link is performed correctly).

Another example is COFF section names. COFF files may contain an unlimited number of sections, each one with a textual section name. If the target of the link is a format which does not have many sections (e.g., a.out) or has sections without names (e.g., the Oasys format), the link cannot be done simply. You can circumvent this problem by describing the desired input-to-output section mapping with the linker command language.

Information can be lost during canonicalization. The BFD internal canonical form of the external formats is not exhaustive; there are structures in input formats for which there is no direct representation internally. This means that the BFD back ends cannot maintain all possible data richness through the transformation between external to internal and back to external formats.

This limitation is only a problem when an application reads one format and writes another. Each BFD back end is responsible for maintaining as much data as possible, and the internal BFD canonical form has structures which are opaque to the BFD core, and exported only to the back ends. When a file is read in one format, the canonical form is generated for BFD and the application. At the same time, the back end saves away any information which may otherwise be lost. If the data is then written back in the same format, the back end routine will be able to use the canonical form provided by the BFD core as well as the information it prepared earlier. Since there is a great deal of commonality between back ends, there is no information lost when linking or copying big endian COFF to little endian COFF, or a.out to b.out. When a mixture of formats is linked, the information is only lost from the files whose format differs from the destination.

The BFD canonical object-file format

The greatest potential for loss of information occurs when there is the least overlap between the information provided by the source format, that stored by the canonical format, and that needed by the destination format. A brief description of the canonical form may help you understand which kinds of data you can count on preserving across conversions.

files
Information stored on a per-file basis includes target machine architecture, particular implementation format type, a demand pageable bit, and a write protected bit. Information like Unix magic numbers is not stored here--only the magic numbers' meaning, so a ZMAGIC file would have both the demand pageable bit and the write protected text bit set. The byte order of the target is stored on a per-file basis, so that big- and little-endian object files may be used with one another.
sections
Each section in the input file contains the name of the section, the section's original address in the object file, size and alignment information, various flags, and pointers into other BFD data structures.
symbols
Each symbol contains a pointer to the information for the object file which originally defined it, its name, its value, and various flag bits. When a BFD back end reads in a symbol table, it relocates all symbols to make them relative to the base of the section where they were defined. Doing this ensures that each symbol points to its containing section. Each symbol also has a varying amount of hidden private data for the BFD back end. Since the symbol points to the original file, the private data format for that symbol is accessible. ld can operate on a collection of symbols of wildly different formats without problems. Normal global and simple local symbols are maintained on output, so an output file (no matter its format) will retain symbols pointing to functions and to global, static, and common variables. Some symbol information is not worth retaining; in a.out, type information is stored in the symbol table as long symbol names. This information would be useless to most COFF debuggers; the linker has command line switches to allow users to throw it away. There is one word of type information within the symbol, so if the format supports symbol type information within symbols (for example, COFF, IEEE, Oasys) and the type is simple enough to fit within one word (nearly everything but aggregates), the information will be preserved.
relocation level
Each canonical BFD relocation record contains a pointer to the symbol to relocate to, the offset of the data to relocate, the section the data is in, and a pointer to a relocation type descriptor. Relocation is performed by passing messages through the relocation type descriptor and the symbol pointer. Therefore, relocations can be performed on output data using a relocation method that is only available in one of the input formats. For instance, Oasys provides a byte relocation format. A relocation record requesting this relocation type would point indirectly to a routine to perform this, so the relocation may be performed on a byte being written to a 68k COFF file, even though 68k COFF has no such relocation type.
line numbers
Object formats can contain, for debugging purposes, some form of mapping between symbols, source line numbers, and addresses in the output file. These addresses have to be relocated along with the symbol information. Each symbol with an associated list of line number records points to the first record of the list. The head of a line number list consists of a pointer to the symbol, which allows finding out the address of the function whose line number is being described. The rest of the list is made up of pairs: offsets into the section and line numbers. Any format which can simply derive this information can pass it successfully between formats (COFF, IEEE and Oasys).

Reporting Bugs

Your bug reports play an essential role in making ld reliable.

Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of ld work better. Bug reports are your contribution to the maintenance of ld.

In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug.

Have you found a bug?

If you are not sure whether you have found a bug, here are some guidelines:

  • If the linker gets a fatal signal, for any input whatever, that is a ld bug. Reliable linkers never crash.
  • If ld produces an error message for valid input, that is a bug.
  • If ld does not produce an error message for invalid input, that may be a bug. In the general case, the linker can not verify that object files are correct.
  • If you are an experienced user of linkers, your suggestions for improvement of ld are welcome in any case.

How to report bugs

A number of companies and individuals offer support for GNU products. If you obtained ld from a support organization, we recommend you contact that organization first.

You can find contact information for many support companies and individuals in the file `etc/SERVICE' in the GNU Emacs distribution.

In any event, we also recommend that you send bug reports for ld to `bug-gnu-utils@gnu.org'.

The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!

Often people omit facts because they think they know what causes the problem and assume that some details do not matter. Thus, you might assume that the name of a symbol you use in an example does not matter. Well, probably it does not, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that name is stored in memory; perhaps, if the name were different, the contents of that location would fool the linker into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable us to fix the bug if it is new to us. Therefore, always write your bug reports on the assumption that the bug has not been reported previously.

Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" Those bug reports are useless, and we urge everyone to refuse to respond to them except to chide the sender to report bugs properly.

To enable us to fix the bug, you should include all these things:

  • The version of ld. ld announces it if you start it with the `--version' argument. Without this, we will not know whether there is any point in looking for the bug in the current version of ld.
  • Any patches you may have applied to the ld source, including any patches made to the BFD library.
  • The type of machine you are using, and the operating system name and version number.
  • What compiler (and its version) was used to compile ld---e.g. "gcc-2.7".
  • The command arguments you gave the linker to link your example and observe the bug. To guarantee you will not omit something important, list them all. A copy of the Makefile (or the output from make) is sufficient. If we were to try to guess the arguments, we would probably guess wrong and then we might not encounter the bug.
  • A complete input file, or set of input files, that will reproduce the bug. It is generally most helpful to send the actual object files, uuencoded if necessary to get them through the mail system. Making them available for anonymous FTP is not as good, but may be the only reasonable choice for large object files. If the source files were assembled using gas or compiled using gcc, then it may be OK to send the source files rather than the object files. In this case, be sure to say exactly what version of gas or gcc was used to produce the object files. Also say how gas or gcc were configured.
  • A description of what behavior you observe that you believe is incorrect. For example, "It gets a fatal signal." Of course, if the bug is that ld gets a fatal signal, then we will certainly notice it. But if the bug is incorrect output, we might not notice unless it is glaringly wrong. You might as well not give us a chance to make a mistake. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of ld is out of synch, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations.
  • If you wish to suggest changes to the ld source, send us context diffs, as generated by diff with the `-u', `-c', or `-p' option. Always send diffs from the old file to the new file. If you even discuss something in the ld source, refer to it by context, not by line number. The line numbers in our development sources will not match those in your sources. Your line numbers would convey no useful information to us.

Here are some things that are not necessary:

  • A description of the envelope of the bug. Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it. This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. We recommend that you save your time for something else. Of course, if you can find a simpler example to report instead of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take less time, and so on. However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used.
  • A patch for the bug. A patch for the bug does help us if it is a good one. But do not omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. Sometimes with a program as complicated as ld it is very hard to construct an example that will make the program follow a certain path through the code. If you do not send us the example, we will not be able to construct one, so we will not be able to verify that the bug is fixed. And if we cannot understand what bug you are trying to fix, or why your patch should be an improvement, we will not install it. A test case will help us to understand.
  • A guess about what the bug is or what it depends on. Such guesses are usually wrong. Even we cannot guess right about such things without first using the debugger to find the facts.

MRI Compatible Script Files

To aid users making the transition to GNU ld from the MRI linker, ld can use MRI compatible linker scripts as an alternative to the more general-purpose linker scripting language described in section Command Language. MRI compatible linker scripts have a much simpler command set than the scripting language otherwise used with ld. GNU ld supports the most commonly used MRI linker commands; these commands are described here.

In general, MRI scripts aren't of much use with the a.out object file format, since it only has three sections and MRI scripts lack some features to make use of them.

You can specify a file containing an MRI-compatible script using the `-c' command-line option.

Each command in an MRI-compatible script occupies its own line; each command line starts with the keyword that identifies the command (though blank lines are also allowed for punctuation). If a line of an MRI-compatible script begins with an unrecognized keyword, ld issues a warning message, but continues processing the script.

Lines beginning with `*' are comments.

You can write these commands using all upper-case letters, or all lower case; for example, `chip' is the same as `CHIP'. The following list shows only the upper-case form of each command.

ABSOLUTE secname
ABSOLUTE secname, secname, ... secname
Normally, ld includes in the output file all sections from all the input files. However, in an MRI-compatible script, you can use the ABSOLUTE command to restrict the sections that will be present in your output program. If the ABSOLUTE command is used at all in a script, then only the sections named explicitly in ABSOLUTE commands will appear in the linker output. You can still use other input sections (whatever you select on the command line, or using LOAD) to resolve addresses in the output file.
ALIAS out-secname, in-secname
Use this command to place the data from input section in-secname in a section called out-secname in the linker output file. in-secname may be an integer.
ALIGN secname = expression
Align the section called secname to expression. The expression should be a power of two.
BASE expression
Use the value of expression as the lowest address (other than absolute addresses) in the output file.
CHIP expression
CHIP expression, expression
This command does nothing; it is accepted only for compatibility.
END
This command does nothing whatever; it's only accepted for compatibility.
FORMAT output-format
Similar to the OUTPUT_FORMAT command in the more general linker language, but restricted to one of these output formats:
  1. S-records, if output-format is `S'
  2. IEEE, if output-format is `IEEE'
  3. COFF (the `coff-m68k' variant in BFD), if output-format is `COFF'
LIST anything...
Print (to the standard output file) a link map, as produced by the ld command-line option `-M'. The keyword LIST may be followed by anything on the same line, with no change in its effect.
LOAD filename
LOAD filename, filename, ... filename
Include one or more object file filename in the link; this has the same effect as specifying filename directly on the ld command line.
NAME output-name
output-name is the name for the program produced by ld; the MRI-compatible command NAME is equivalent to the command-line option `-o' or the general script language command OUTPUT.
ORDER secname, secname, ... secname
ORDER secname secname secname
Normally, ld orders the sections in its output file in the order in which they first appear in the input files. In an MRI-compatible script, you can override this ordering with the ORDER command. The sections you list with ORDER will appear first in your output file, in the order specified.
PUBLIC name=expression
PUBLIC name,expression
PUBLIC name expression
Supply a value (expression) for external symbol name used in the linker input files.
SECT secname, expression
SECT secname=expression
SECT secname expression
You can use any of these three forms of the SECT command to specify the start address (expression) for section secname. If you have more than one SECT statement for the same secname, only the first sets the start address.

Index

Jump to: " - * - - - . - 0 - : - ; - = - > - [ - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - q - r - s - t - u - v - w

"

  • "

    • *

  • *( COMMON )
  • *(section)

    • -

  • -(
  • --architecture=arch
  • --auxiliary
  • --cref
  • --defsym symbol=exp
  • --discard-all
  • --discard-locals
  • --dynamic-linker file
  • --embedded-relocs
  • --entry=entry
  • --export-dynamic
  • --filter
  • --force-exe-suffix
  • --format=format
  • --gpsize
  • --help
  • --just-symbols=file
  • --library-path=dir
  • --library=archive
  • --mri-script=MRI-cmdfile
  • --nmagic
  • --no-keep-memory
  • --no-warn-mismatch
  • --no-whole-archive
  • --noinhibit-exec
  • --oformat
  • --omagic
  • --output=output
  • --print-map
  • --relax
  • --relax on i960
  • --relocateable
  • --script=script
  • --sort-common
  • --split-by-file
  • --split-by-reloc
  • --stats
  • --strip-all
  • --strip-debug
  • --trace
  • --trace-symbol=symbol
  • --traditional-format
  • --undefined=symbol
  • --verbose
  • --version
  • --version-script=version-scriptfile
  • --warn-comon
  • --warn-constructors
  • --warn-multiple-gp
  • --warn-once
  • --warn-section-align
  • --whole-archive
  • --wrap
  • -Aarch
  • -akeyword
  • -assert keyword
  • -b format
  • -Bdynamic
  • -Bshareable
  • -Bstatic
  • -Bsymbolic
  • -c MRI-cmdfile
  • -call_shared
  • -d
  • -dc
  • -dn
  • -dp
  • -dy
  • -E
  • -e entry
  • -EB
  • -EL
  • -F
  • -f
  • -G
  • -g
  • -hname
  • -i
  • -larchive
  • -Ldir
  • -M
  • -m emulation
  • -Map
  • -N
  • -n
  • -non_shared
  • -o output
  • -qmagic
  • -Qy
  • -r
  • -R file
  • -rpath
  • -rpath-link
  • -S
  • -s
  • -shared
  • -soname=name
  • -static
  • -t
  • -T script
  • -Tbss org
  • -Tdata org
  • -Ttext org
  • -u symbol
  • -Ur
  • -V
  • -v
  • -X
  • -x
  • -Y path
  • -y symbol
  • -z keyword

    • .

  • .

    • 0

  • 0x

    • :

  • :phdr

    • ;

  • ;

    • =

  • =fill

    • >

  • >region

    • [

  • [section...], not supported

    • a

  • ABSOLUTE (MRI)
  • absolute and relocatable symbols
  • ABSOLUTE(exp)
  • ADDR(section)
  • ALIAS (MRI)
  • ALIGN (MRI)
  • ALIGN(exp)
  • aligning sections
  • allocating memory
  • architectures
  • archive files, from cmd line
  • arithmetic
  • arithmetic operators
  • assignment in scripts
  • assignment, in section defn
  • AT ( ldadr )

    • b

  • back end
  • BASE (MRI)
  • BFD canonical format
  • BFD requirements
  • big-endian objects
  • binary input files
  • binary input format
  • BLOCK(align)
  • bug criteria
  • bug reports
  • bugs in ld
  • BYTE(expression)

    • c

  • C++ constructors, arranging in link
  • CHIP (MRI)
  • combining symbols, warnings on
  • command files
  • command line
  • commands, fundamental
  • comments
  • common allocation, common allocation
  • commons in output
  • compatibility, MRI
  • CONSTRUCTORS
  • constructors
  • constructors, arranging in link
  • contents of a section
  • crash of linker
  • CREATE_OBJECT_SYMBOLS
  • cross reference table
  • cross references
  • current output location

    • d

  • dbx
  • decimal integers
  • default emulation
  • default input format
  • DEFINED(symbol)
  • deleting local symbols
  • direct output
  • discontinuous memory
  • dot
  • dynamic linker, from command line
  • dynamic symbol table

    • e

  • ELF program headers
  • emulation
  • emulation, default
  • END (MRI)
  • endianness
  • entry point, defaults
  • entry point, from command line
  • ENTRY(symbol)
  • error on valid input
  • expression evaluation order
  • expression syntax
  • expression, absolute
  • expressions in a section

    • f

  • fatal signal
  • filename
  • filename symbols
  • filename(section)
  • files and sections, section defn
  • files, including in output sections
  • fill pattern, entire section
  • FILL(expression)
  • first input file
  • first instruction
  • FLOAT
  • FORCE_COMMON_ALLOCATION
  • FORMAT (MRI)
  • format, output file
  • functions in expression language
  • fundamental script commands

    • g

  • GNU linker
  • GNUTARGET, GNUTARGET
  • GROUP ( files )
  • grouping input files
  • groups of archives

    • h

  • H8/300 support
  • header size
  • help
  • hexadecimal integers
  • holes
  • holes, filling

    • i

  • i960 support
  • INCLUDE filename
  • including a linker script
  • including an entire archive
  • incremental link
  • INPUT ( files )
  • input file format
  • input filename symbols
  • input files, displaying
  • input files, section defn
  • input format, input format
  • input sections to output section
  • integer notation
  • integer suffixes
  • internal object-file format
  • invalid input

    • k

  • K and M integer suffixes

    • l

  • l =
  • L, deleting symbols beginning
  • layout of output file
  • lazy evaluation
  • ld bugs, reporting
  • LDEMULATION
  • len =
  • LENGTH =
  • link map
  • link-time runtime library search path
  • linker crash
  • LIST (MRI)
  • little-endian objects
  • LOAD (MRI)
  • load address, specifying
  • LOADADDR(section)
  • loading, preventing
  • local symbols, deleting
  • location counter
  • LONG(expression)

    • m

  • M and K integer suffixes
  • machine architecture, output
  • machine dependencies
  • MAX
  • MEMORY
  • memory region attributes
  • memory regions and sections
  • memory usage
  • MIN
  • MIPS embedded PIC code
  • MRI compatibility

    • n

  • NAME (MRI)
  • names
  • naming memory regions
  • naming output sections
  • naming the output file, naming the output file
  • negative integers
  • NEXT(exp)
  • NMAGIC
  • NOCROSSREFS ( sections )
  • NOFLOAT
  • NOLOAD
  • Non constant expression

    • o

  • o =
  • objdump -i
  • object file management
  • object files
  • object formats available
  • object size
  • octal integers
  • OMAGIC
  • opening object files
  • Operators for arithmetic
  • options
  • ORDER (MRI)
  • org =
  • ORIGIN =
  • OUTPUT ( filename )
  • output file after errors
  • output file layout
  • OUTPUT_ARCH ( bfdname )
  • OUTPUT_FORMAT ( bfdname )
  • OVERLAY
  • overlays

    • p

  • partial link
  • path for libraries
  • PHDRS
  • precedence in expressions
  • prevent unnecessary loading
  • program headers
  • program headers and sections
  • provide
  • PUBLIC (MRI)

    • q

  • QUAD(expression)
  • quoted symbol names

    • r

  • read-only text
  • read/write from cmd line
  • regions of memory
  • relaxing addressing modes
  • relaxing on H8/300
  • relaxing on i960
  • relocatable and absolute symbols
  • relocatable output
  • reporting bugs in ld
  • requirements for BFD
  • retaining specified symbols
  • rounding up location counter
  • runtime library name
  • runtime library search path

    • s

  • scaled integers
  • script files
  • search directory, from cmd line
  • search path, libraries
  • SEARCH_DIR ( path )
  • SECT (MRI)
  • section address, section address
  • section alignment
  • section alignment, warnings on
  • section definition
  • section defn, full syntax
  • section fill pattern
  • section load address
  • section size
  • section start
  • section, assigning to memory region
  • section, assigning to program header
  • SECTIONS
  • segment origins, cmd line
  • semicolon
  • shared libraries
  • SHORT(expression)
  • SIZEOF(section)
  • sizeof_headers
  • SIZEOF_HEADERS
  • specify load address
  • SQUAD(expression)
  • standard Unix system
  • start address, section
  • start of execution
  • STARTUP ( filename )
  • strip all symbols
  • strip debugger symbols
  • stripping all but some symbols
  • suffixes for integers
  • symbol defaults
  • symbol definition, scripts
  • symbol names
  • symbol tracing
  • symbol versions
  • symbol-only input
  • symbol = expression ;
  • symbol f= expression ;
  • symbols, from command line
  • symbols, relocatable and absolute
  • symbols, retaining selectively
  • synthesizing linker
  • synthesizing on H8/300

    • t

  • TARGET ( format )
  • traditional format

    • u

  • unallocated address, next
  • undefined symbol
  • undefined symbols, warnings on
  • uninitialized data
  • unspecified memory
  • usage

    • v

  • variables, defining
  • verbose
  • version
  • version script
  • version script, symbol versions
  • VERSION {script text}
  • versions of symbols

    • w

  • warnings, on combining symbols
  • warnings, on section alignment
  • warnings, on undefined symbols
  • what is this?

    • This document was generated on 7 November 1998 using the texi2html translator version 1.52.


Libtool

GNU Libtool

For version 1.4.2, 10 September 2001

Gordon Matzigkeit
Alexandre Oliva
Thomas Tanner
Gary V. Vaughan

Table of Contents

  • Introduction
    • Motivation for writing libtool
    • Implementation issues
    • Other implementations
    • A postmortem analysis of other implementations
  • The libtool paradigm
  • Using libtool
    • Creating object files
    • Linking libraries
    • Linking executables
    • Debugging executables
    • Installing libraries
    • Installing executables
    • Linking static libraries
  • Invoking libtool
    • Compile mode
    • Link mode
    • Execute mode
    • Install mode
    • Finish mode
    • Uninstall mode
    • Clean mode
  • Integrating libtool with your package
    • Writing `Makefile' rules for libtool
    • Using Automake with libtool
    • Configuring libtool
      • The AC_PROG_LIBTOOL macro
    • Including libtool in your package
      • Invoking libtoolize
      • Autoconf `.o' macros
    • Static-only libraries
  • Library interface versions
    • What are library interfaces?
    • Libtool's versioning system
    • Updating library version information
    • Managing release information
  • Tips for interface design
    • Writing C header files
  • Inter-library dependencies
  • Dlopened modules
    • Building modules to dlopen
    • Dlpreopening
    • Finding the correct name to dlopen
    • Unresolved dlopen issues
  • Using libltdl
    • How to use libltdl in your programs
    • Creating modules that can be dlopened
    • Using libtldl in a multi threaded environment
    • Data associated with loaded modules
    • How to create and register new module loaders
      • Error handling within user module loaders
    • How to distribute libltdl with your package
  • Using libtool with other languages
    • Writing libraries for C++
  • Troubleshooting
    • The libtool test suite
      • Description of test suite
      • When tests fail
    • Reporting bugs
  • Maintenance notes for libtool
    • Porting libtool to new systems
      • Information sources
      • Porting inter-library dependencies support
    • Tested platforms
    • Platform quirks
      • References
      • Compilers
      • Reloadable objects
      • Multiple dependencies
      • Archivers
    • libtool script contents
    • Cheap tricks
  • GNU Free Documentation License
    • Preamble
    • APPLICABILITY AND DEFINITIONS
    • VERBATIM COPYING
    • COPYING IN QUANTITY
    • MODIFICATIONS
    • COMBINING DOCUMENTS
    • COLLECTIONS OF DOCUMENTS
    • AGGREGATION WITH INDEPENDENT WORKS
    • TRANSLATION
    • TERMINATION
    • FUTURE REVISIONS OF THIS LICENSE
    • ADDENDUM: How to use this License for your documents
  • Index

Introduction

In the past, if a source code package developer wanted to take advantage of the power of shared libraries, he needed to write custom support code for each platform on which his package ran. He also had to design a configuration interface so that the package installer could choose what sort of libraries were built.

GNU Libtool simplifies the developer's job by encapsulating both the platform-specific dependencies, and the user interface, in a single script. GNU Libtool is designed so that the complete functionality of each host type is available via a generic interface, but nasty quirks are hidden from the programmer.

GNU Libtool's consistent interface is reassuring... users don't need to read obscure documentation in order to have their favorite source package build shared libraries. They just run your package configure script (or equivalent), and libtool does all the dirty work.

There are several examples throughout this document. All assume the same environment: we want to build a library, `libhello', in a generic way.

`libhello' could be a shared library, a static library, or both... whatever is available on the host system, as long as libtool has been ported to it.

This chapter explains the original design philosophy of libtool. Feel free to skip to the next chapter, unless you are interested in history, or want to write code to extend libtool in a consistent way.

Motivation for writing libtool

Since early 1995, several different GNU developers have recognized the importance of having shared library support for their packages. The primary motivation for such a change is to encourage modularity and reuse of code (both conceptually and physically) in GNU programs.

Such a demand means that the way libraries are built in GNU packages needs to be general, to allow for any library type the package installer might want. The problem is compounded by the absence of a standard procedure for creating shared libraries on different platforms.

The following sections outline the major issues facing shared library support in GNU, and how shared library support could be standardized with libtool.

The following specifications were used in developing and evaluating this system:

  1. The system must be as elegant as possible.
  2. The system must be fully integrated with the GNU Autoconf and Automake utilities, so that it will be easy for GNU maintainers to use. However, the system must not require these tools, so that it can be used by non-GNU packages.
  3. Portability to other (non-GNU) architectures and tools is desirable.

Implementation issues

The following issues need to be addressed in any reusable shared library system, specifically libtool:

  1. The package installer should be able to control what sort of libraries are built.
  2. It can be tricky to run dynamically linked programs whose libraries have not yet been installed. LD_LIBRARY_PATH must be set properly (if it is supported), or programs fail to run.
  3. The system must operate consistently even on hosts which don't support shared libraries.
  4. The commands required to build shared libraries may differ wildly from host to host. These need to be determined at configure time in a consistent way.
  5. It is not always obvious with which suffix a shared library should be installed. This makes it difficult for `Makefile' rules, since they generally assume that file names are the same from host to host.
  6. The system needs a simple library version number abstraction, so that shared libraries can be upgraded in place. The programmer should be informed how to design the interfaces to the library to maximize binary compatibility.
  7. The install `Makefile' target should warn the package installer to set the proper environment variables (LD_LIBRARY_PATH or equivalent), or run ldconfig.

Other implementations

Even before libtool was developed, many free software packages built and installed their own shared libraries. At first, these packages were examined to avoid reinventing existing features.

Now it is clear that none of these packages have documented the details of shared library systems that libtool requires. So, other packages have been more or less abandoned as influences.

A postmortem analysis of other implementations

In all fairness, each of the implementations that were examined do the job that they were intended to do, for a number of different host systems. However, none of these solutions seem to function well as a generalized, reusable component.

Most were too complex to use (much less modify) without understanding exactly what the implementation does, and they were generally not documented.

The main difficulty is that different vendors have different views of what libraries are, and none of the packages which were examined seemed to be confident enough to settle on a single paradigm that just works.

Ideally, libtool would be a standard that would be implemented as series of extensions and modifications to existing library systems to make them work consistently. However, it is not an easy task to convince operating system developers to mend their evil ways, and people want to build shared libraries right now, even on buggy, broken, confused operating systems.

For this reason, libtool was designed as an independent shell script. It isolates the problems and inconsistencies in library building that plague `Makefile' writers by wrapping the compiler suite on different platforms with a consistent, powerful interface.

With luck, libtool will be useful to and used by the GNU community, and that the lessons that were learned in writing it will be taken up by designers of future library systems.

The libtool paradigm

At first, libtool was designed to support an arbitrary number of library object types. After libtool was ported to more platforms, a new paradigm gradually developed for describing the relationship between libraries and programs.

In summary, "libraries are programs with multiple entry points, and more formally defined interfaces."

Version 0.7 of libtool was a complete redesign and rewrite of libtool to reflect this new paradigm. So far, it has proved to be successful: libtool is simpler and more useful than before.

The best way to introduce the libtool paradigm is to contrast it with the paradigm of existing library systems, with examples from each. It is a new way of thinking, so it may take a little time to absorb, but when you understand it, the world becomes simpler.

Using libtool

It makes little sense to talk about using libtool in your own packages until you have seen how it makes your life simpler. The examples in this chapter introduce the main features of libtool by comparing the standard library building procedure to libtool's operation on two different platforms:

`a23'
An Ultrix 4.2 platform with only static libraries.
`burger'
A NetBSD/i386 1.2 platform with shared libraries.

You can follow these examples on your own platform, using the preconfigured libtool script that was installed with libtool (see section Configuring libtool).

Source files for the following examples are taken from the `demo' subdirectory of the libtool distribution. Assume that we are building a library, `libhello', out of the files `foo.c' and `hello.c'.

Note that the `foo.c' source file uses the cos math library function, which is usually found in the standalone math library, and not the C library (see section `Trigonometric Functions' in The GNU C Library Reference Manual). So, we need to add -lm to the end of the link line whenever we link `foo.o' or `foo.lo' into an executable or a library (see section Inter-library dependencies).

The same rule applies whenever you use functions that don't appear in the standard C library... you need to add the appropriate -lname flag to the end of the link line when you link against those objects.

After we have built that library, we want to create a program by linking `main.o' against `libhello'.

Creating object files

To create an object file from a source file, the compiler is invoked with the `-c' flag (and any other desired flags):

burger$ gcc -g -O -c main.c
burger$

The above compiler command produces an object file, `main.o', from the source file `main.c'.

For most library systems, creating object files that become part of a static library is as simple as creating object files that are linked to form an executable:

burger$ gcc -g -O -c foo.c
burger$ gcc -g -O -c hello.c
burger$

Shared libraries, however, may only be built from position-independent code (PIC). So, special flags must be passed to the compiler to tell it to generate PIC rather than the standard position-dependent code.

Since this is a library implementation detail, libtool hides the complexity of PIC compiler flags by using separate library object files (which end in `.lo' instead of `.o'). On systems without shared libraries (or without special PIC compiler flags), these library object files are identical to "standard" object files.

To create library object files for `foo.c' and `hello.c', simply invoke libtool with the standard compilation command as arguments (see section Compile mode):

a23$ libtool gcc -g -O -c foo.c
gcc -g -O -c foo.c
echo timestamp > foo.lo
a23$ libtool gcc -g -O -c hello.c
gcc -g -O -c hello.c
echo timestamp > hello.lo
a23$

Note that libtool creates two files for each invocation. The `.lo' file is a library object, which may be built into a shared library, and the `.o' file is a standard object file. On `a23', the library objects are just timestamps, because only static libraries are supported.

On shared library systems, libtool automatically inserts the PIC generation flags into the compilation command, so that the library object and the standard object differ:

burger$ libtool gcc -g -O -c foo.c
gcc -g -O -c -fPIC -DPIC foo.c
mv -f foo.o foo.lo
gcc -g -O -c foo.c >/dev/null 2>&1
burger$ libtool gcc -g -O -c hello.c
gcc -g -O -c -fPIC -DPIC hello.c
mv -f hello.o hello.lo
gcc -g -O -c hello.c >/dev/null 2>&1
burger$

Notice that the second run of GCC has its output discarded. This is done so that compiler warnings aren't annoyingly duplicated.

Linking libraries

Without libtool, the programmer would invoke the ar command to create a static library:

burger$ ar cru libhello.a hello.o foo.o
burger$

But of course, that would be too simple, so many systems require that you run the ranlib command on the resulting library (to give it better karma, or something):

burger$ ranlib libhello.a
burger$

It seems more natural to use the C compiler for this task, given libtool's "libraries are programs" approach. So, on platforms without shared libraries, libtool simply acts as a wrapper for the system ar (and possibly ranlib) commands.

Again, the libtool library name differs from the standard name (it has a `.la' suffix instead of a `.a' suffix). The arguments to libtool are the same ones you would use to produce an executable named `libhello.la' with your compiler (see section Link mode):

a23$ libtool gcc -g -O -o libhello.la foo.o hello.o
libtool: cannot build libtool library `libhello.la' from non-libtool \
                objects
a23$

Aha! Libtool caught a common error... trying to build a library from standard objects instead of library objects. This doesn't matter for static libraries, but on shared library systems, it is of great importance.

So, let's try again, this time with the library object files. Remember also that we need to add -lm to the link command line because `foo.c' uses the cos math library function (see section Using libtool).

Another complication in building shared libraries is that we need to specify the path to the directory in which they (eventually) will be installed (in this case, `/usr/local/lib')(1):

a23$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \
                -rpath /usr/local/lib -lm
mkdir .libs
ar cru .libs/libhello.a foo.o hello.o
ranlib .libs/libhello.a
creating libhello.la
a23$

Now, let's try the same trick on the shared library platform:

burger$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \
                -rpath /usr/local/lib -lm
mkdir .libs
ld -Bshareable -o .libs/libhello.so.0.0 foo.lo hello.lo -lm
ar cru .libs/libhello.a foo.o hello.o
ranlib .libs/libhello.a
creating libhello.la
burger$

Now that's significantly cooler... libtool just ran an obscure ld command to create a shared library, as well as the static library.

Note how libtool creates extra files in the `.libs' subdirectory, rather than the current directory. This feature is to make it easier to clean up the build directory, and to help ensure that other programs fail horribly if you accidentally forget to use libtool when you should.

Linking executables

If you choose at this point to install the library (put it in a permanent location) before linking executables against it, then you don't need to use libtool to do the linking. Simply use the appropriate `-L' and `-l' flags to specify the library's location.

Some system linkers insist on encoding the full directory name of each shared library in the resulting executable. Libtool has to work around this misfeature by special magic to ensure that only permanent directory names are put into installed executables.

The importance of this bug must not be overlooked: it won't cause programs to crash in obvious ways. It creates a security hole, and possibly even worse, if you are modifying the library source code after you have installed the package, you will change the behaviour of the installed programs!

So, if you want to link programs against the library before you install it, you must use libtool to do the linking.

Here's the old way of linking against an uninstalled library:

burger$ gcc -g -O -o hell.old main.o libhello.a -lm
burger$

Libtool's way is almost the same(2) (see section Link mode):

a23$ libtool gcc -g -O -o hell main.o libhello.la -lm
gcc -g -O -o hell main.o ./.libs/libhello.a -lm
a23$

That looks too simple to be true. All libtool did was transform `libhello.la' to `./.libs/libhello.a', but remember that `a23' has no shared libraries.

On `burger' the situation is different:

burger$ libtool gcc -g -O -o hell main.o libhello.la -lm
gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm
creating hell
burger$

Now assume `libhello.la' had already been installed, and you want to link a new program with it. You could figure out where it lives by yourself, then run:

burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello

However, unless `/usr/local/lib' is in the standard library search path, you won't be able to run test. However, if you use libtool to link the already-installed libtool library, it will do The Right Thing (TM) for you:

burger$ libtool gcc -g -O -o test test.o /usr/local/lib/libhello.la
gcc -g -O -o .libs/test test.o -Wl,--rpath
-Wl,/usr/local/lib /usr/local/lib/libhello.a -lm
creating test
burger$

Note that libtool added the necessary run-time path flag, as well as `-lm', the library libhello.la depended upon. Nice, huh?

Since libtool created a wrapper script, you should use libtool to install it and debug it too. However, since the program does not depend on any uninstalled libtool library, it is probably usable even without the wrapper script. Libtool could probably be made smarter to avoid the creation of the wrapper script in this case, but this is left as an exercise for the reader.

Notice that the executable, hell, was actually created in the `.libs' subdirectory. Then, a wrapper script was created in the current directory.

On NetBSD 1.2, libtool encodes the installation directory of `libhello', by using the `-R/usr/local/lib' compiler flag. Then, the wrapper script guarantees that the executable finds the correct shared library (the one in `./.libs') until it is properly installed.

Let's compare the two different programs:

burger$ time ./hell.old
Welcome to GNU Hell!
** This is not GNU Hello.  There is no built-in mail reader. **
        0.21 real         0.02 user         0.08 sys
burger$ time ./hell
Welcome to GNU Hell!
** This is not GNU Hello.  There is no built-in mail reader. **
        0.63 real         0.09 user         0.59 sys
burger$

The wrapper script takes significantly longer to execute, but at least the results are correct, even though the shared library hasn't been installed yet.

So, what about all the space savings that shared libraries are supposed to yield?

burger$ ls -l hell.old libhello.a
-rwxr-xr-x  1 gord  gord  15481 Nov 14 12:11 hell.old
-rw-r--r--  1 gord  gord   4274 Nov 13 18:02 libhello.a
burger$ ls -l .libs/hell .libs/libhello.*
-rwxr-xr-x  1 gord  gord  11647 Nov 14 12:10 .libs/hell
-rw-r--r--  1 gord  gord   4274 Nov 13 18:44 .libs/libhello.a
-rwxr-xr-x  1 gord  gord  12205 Nov 13 18:44 .libs/libhello.so.0.0
burger$

Well, that sucks. Maybe I should just scrap this project and take up basket weaving.

Actually, it just proves an important point: shared libraries incur overhead because of their (relative) complexity. In this situation, the price of being dynamic is eight kilobytes, and the payoff is about four kilobytes. So, having a shared `libhello' won't be an advantage until we link it against at least a few more programs.

Debugging executables

If `hell' was a complicated program, you would certainly want to test and debug it before installing it on your system. In the above section, you saw how the libtool wrapper script makes it possible to run the program directly, but unfortunately, this mechanism interferes with the debugger:

burger$ gdb hell
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.

"hell": not in executable format: File format not recognized

(gdb) quit
burger$

Sad. It doesn't work because GDB doesn't know where the executable lives. So, let's try again, by invoking GDB directly on the executable:

burger$ gdb .libs/hell
trick:/home/src/libtool/demo$ gdb .libs/hell
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
(gdb) break main
Breakpoint 1 at 0x8048547: file main.c, line 29.
(gdb) run
Starting program: /home/src/libtool/demo/.libs/hell
/home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2'

Program exited with code 020.
(gdb) quit
burger$

Argh. Now GDB complains because it cannot find the shared library that `hell' is linked against. So, we must use libtool in order to properly set the library path and run the debugger. Fortunately, we can forget all about the `.libs' directory, and just run it on the executable wrapper (see section Execute mode):

burger$ libtool gdb hell
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
(gdb) break main
Breakpoint 1 at 0x8048547: file main.c, line 29.
(gdb) run
Starting program: /home/src/libtool/demo/.libs/hell

Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29
29	  printf ("Welcome to GNU Hell!\n");
(gdb) quit
The program is running.  Quit anyway (and kill it)? (y or n) y
burger$

Installing libraries

Installing libraries on a non-libtool system is quite straightforward... just copy them into place:(3)

burger$ su
Password: ********
burger# cp libhello.a /usr/local/lib/libhello.a
burger#

Oops, don't forget the ranlib command:

burger# ranlib /usr/local/lib/libhello.a
burger#

Libtool installation is quite simple, as well. Just use the install or cp command that you normally would (see section Install mode):

a23# libtool cp libhello.la /usr/local/lib/libhello.la
cp libhello.la /usr/local/lib/libhello.la
cp .libs/libhello.a /usr/local/lib/libhello.a
ranlib /usr/local/lib/libhello.a
a23#

Note that the libtool library `libhello.la' is also installed, to help libtool with uninstallation (see section Uninstall mode) and linking (see section Linking executables) and to help programs with dlopening (see section Dlopened modules).

Here is the shared library example:

burger# libtool install -c libhello.la /usr/local/lib/libhello.la
install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0
install -c libhello.la /usr/local/lib/libhello.la
install -c .libs/libhello.a /usr/local/lib/libhello.a
ranlib /usr/local/lib/libhello.a
burger#

It is safe to specify the `-s' (strip symbols) flag if you use a BSD-compatible install program when installing libraries. Libtool will either ignore the `-s' flag, or will run a program that will strip only debugging and compiler symbols from the library.

Once the libraries have been put in place, there may be some additional configuration that you need to do before using them. First, you must make sure that where the library is installed actually agrees with the `-rpath' flag you used to build it.

Then, running `libtool -n --finish libdir' can give you further hints on what to do (see section Finish mode):

burger# libtool -n --finish /usr/local/lib
PATH="$PATH:/sbin" ldconfig -m /usr/local/lib
-----------------------------------------------------------------
Libraries have been installed in:
   /usr/local/lib

To link against installed libraries in a given directory, LIBDIR,
you must use the `-LLIBDIR' flag during linking.

 You will also need to do one of the following:
   - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
     during execution
   - add LIBDIR to the `LD_RUN_PATH' environment variable
     during linking
   - use the `-RLIBDIR' linker flag

See any operating system documentation about shared libraries for
more information, such as the ld and ld.so manual pages.
-----------------------------------------------------------------
burger#

After you have completed these steps, you can go on to begin using the installed libraries. You may also install any executables that depend on libraries you created.

Installing executables

If you used libtool to link any executables against uninstalled libtool libraries (see section Linking executables), you need to use libtool to install the executables after the libraries have been installed (see section Installing libraries).

So, for our Ultrix example, we would run:

a23# libtool install -c hell /usr/local/bin/hell
install -c hell /usr/local/bin/hell
a23#

On shared library systems, libtool just ignores the wrapper script and installs the correct binary:

burger# libtool install -c hell /usr/local/bin/hell
install -c .libs/hell /usr/local/bin/hell
burger#

Linking static libraries

Why return to ar and ranlib silliness when you've had a taste of libtool? Well, sometimes it is desirable to create a static archive that can never be shared. The most frequent case is when you have a set of object files that you use to build several different programs. You can create a "convenience library" out of those objects, and link programs with the library, instead of listing all object files for every program. This technique is often used to overcome GNU automake's lack of support for linking object files built from sources in other directories, because it supports linking with libraries from other directories. This limitation applies to GNU automake up to release 1.4; newer releases should support sources in other directories.

If you just want to link this convenience library into programs, then you could just ignore libtool entirely, and use the old ar and ranlib commands (or the corresponding GNU automake `_LIBRARIES' rules). You can even install a convenience library (but you probably don't want to) using libtool:

burger$ libtool ./install-sh -c libhello.a /local/lib/libhello.a
./install-sh -c libhello.a /local/lib/libhello.a
ranlib /local/lib/libhello.a
burger$

Using libtool for static library installation protects your library from being accidentally stripped (if the installer used the `-s' flag), as well as automatically running the correct ranlib command.

But libtool libraries are more than just collections of object files: they can also carry library dependency information, which old archives do not. If you want to create a libtool static convenience library, you can omit the `-rpath' flag and use `-static' to indicate that you're only interested in a static library. When you link a program with such a library, libtool will actually link all object files and dependency libraries into the program.

If you omit both `-rpath' and `-static', libtool will create a convenience library that can be used to create other libtool libraries, even shared ones. Just like in the static case, the library behaves as an alias to a set of object files and dependency libraries, but in this case the object files are suitable for inclusion in shared libraries. But be careful not to link a single convenience library, directly or indirectly, into a single program or library, otherwise you may get errors about symbol redefinitions.

When GNU automake is used, you should use noinst_LTLIBRARIES instead of lib_LTLIBRARIES for convenience libraries, so that the `-rpath' option is not passed when they are linked.

As a rule of thumb, link a libtool convenience library into at most one libtool library, and never into a program, and link libtool static convenience libraries only into programs, and only if you need to carry library dependency information to the user of the static convenience library.

Another common situation where static linking is desirable is in creating a standalone binary. Use libtool to do the linking and add the `-all-static' flag.

Invoking libtool

The libtool program has the following synopsis:

libtool [option]... [mode-arg]...

and accepts the following options:

`--config'
Display libtool configuration variables and exit.
`--debug'
Dump a trace of shell script execution to standard output. This produces a lot of output, so you may wish to pipe it to less (or more) or redirect to a file.
`-n'
`--dry-run'
Don't create, modify, or delete any files, just show what commands would be executed by libtool.
`--features'
Display basic configuration options. This provides a way for packages to determine whether shared or static libraries will be built.
`--finish'
Same as `--mode=finish'.
`--help'
Display a help message and exit. If `--mode=mode' is specified, then detailed help for mode is displayed.
`--mode=mode'
Use mode as the operation mode. By default, the operation mode is inferred from the mode-args. If mode is specified, it must be one of the following:
`compile'
Compile a source file into a libtool object.
`execute'
Automatically set the library path so that another program can use uninstalled libtool-generated programs or libraries.
`finish'
Complete the installation of libtool libraries on the system.
`install'
Install libraries or executables.
`link'
Create a library or an executable.
`uninstall'
Delete installed libraries or executables.
`clean'
Delete uninstalled libraries or executables.
`--version'
Print libtool version information and exit.

The mode-args are a variable number of arguments, depending on the selected operation mode. In general, each mode-arg is interpreted by programs libtool invokes, rather than libtool itself.

Compile mode

For compile mode, mode-args is a compiler command to be used in creating a `standard' object file. These arguments should begin with the name of the C compiler, and contain the `-c' compiler flag so that only an object file is created.

Libtool determines the name of the output file by removing the directory component from the source file name, then substituting the source code suffix (e.g. `.c' for C source code) with the library object suffix, `.lo'.

If shared libraries are being built, any necessary PIC generation flags are substituted into the compilation command. You can pass compiler and linker specific flags using `-Wc,flag' and `-Xcompiler flag' or `-Wl,flag' and `-Xlinker flag', respectively.

If the `-static' option is given, then a `.o' file is built, even if libtool was configured with `--disable-static'.

Note that the `-o' option is now fully supported. It is emulated on the platforms that don't support it (by locking and moving the objects), so it is really easy to use libtool, just with minor modifications to your Makefiles. Typing for example

libtool gcc -c foo/x.c -o foo/x.lo

will do what you expect.

Note, however, that, if the compiler does not support `-c' and `-o', it is impossible to compile `foo/x.c' without overwriting an existing `./x.o'. Therefore, if you do have a source file `./x.c', make sure you introduce dependencies in your `Makefile' to make sure `./x.o' (or `./x.lo') is re-created after any sub-directory's `x.lo':

x.o x.lo: foo/x.lo bar/x.lo

This will also ensure that make won't try to use a temporarily corrupted `x.o' to create a program or library. It may cause needless recompilation on platforms that support `-c' and `-o' together, but it's the only way to make it safe for those that don't.

Link mode

Link mode links together object files (including library objects) to form another library or to create an executable program.

mode-args consist of a command using the C compiler to create an output file (with the `-o' flag) from several object files.

The following components of mode-args are treated specially:

`-all-static'
If output-file is a program, then do not link it against any shared libraries at all. If output-file is a library, then only create a static library.
`-avoid-version'
Tries to avoid versioning (see section Library interface versions) for libraries and modules, i.e. no version information is stored and no symbolic links are created. If the platform requires versioning, this option has no effect.
`-dlopen file'
Same as `-dlpreopen file', if native dlopening is not supported on the host platform (see section Dlopened modules) or if the program is linked with `-static' or `-all-static'. Otherwise, no effect. If file is self libtool will make sure that the program can dlopen itself, either by enabling -export-dynamic or by falling back to `-dlpreopen self'.
`-dlpreopen file'
Link file into the output program, and add its symbols to lt_preloaded_symbols (see section Dlpreopening). If file is self, the symbols of the program itself will be added to lt_preloaded_symbols. If file is force libtool will make sure that lt_preloaded_symbols is always defined, regardless of whether it's empty or not.
`-export-dynamic'
Allow symbols from output-file to be resolved with dlsym (see section Dlopened modules).
`-export-symbols symfile'
Tells the linker to export only the symbols listed in symfile. The symbol file should end in `.sym' and must contain the name of one symbol per line. This option has no effect on some platforms. By default all symbols are exported.
`-export-symbols-regex regex'
Same as `-export-symbols', except that only symbols matching the regular expression regex are exported. By default all symbols are exported.
`-Llibdir'
Search libdir for required libraries that have already been installed.
`-lname'
output-file requires the installed library `libname'. This option is required even when output-file is not an executable.
`-module'
Creates a library that can be dlopened (see section Dlopened modules). This option doesn't work for programs. Module names don't need to be prefixed with 'lib'. In order to prevent name clashes, however, 'libname' and 'name' must not be used at the same time in your package.
`-no-fast-install'
Disable fast-install mode for the executable output-file. Useful if the program won't be necessarily installed.
`-no-install'
Link an executable output-file that can't be installed and therefore doesn't need a wrapper script. Useful if the program is only used in the build tree, e.g., for testing or generating other files.
`-no-undefined'
Declare that output-file does not depend on any other libraries. Some platforms cannot create shared libraries that depend on other libraries (see section Inter-library dependencies).
`-o output-file'
Create output-file from the specified objects and libraries.
`-release release'
Specify that the library was generated by release release of your package, so that users can easily tell which versions are newer than others. Be warned that no two releases of your package will be binary compatible if you use this flag. If you want binary compatibility, use the `-version-info' flag instead (see section Library interface versions).
`-rpath libdir'
If output-file is a library, it will eventually be installed in libdir. If output-file is a program, add libdir to the run-time path of the program.
`-R libdir'
If output-file is a program, add libdir to its run-time path. If output-file is a library, add -Rlibdir to its dependency_libs, so that, whenever the library is linked into a program, libdir will be added to its run-time path.
`-static'
If output-file is a program, then do not link it against any uninstalled shared libtool libraries. If output-file is a library, then only create a static library.
`-version-info current[:revision[:age]]'
If output-file is a libtool library, use interface version information current, revision, and age to build it (see section Library interface versions). Do not use this flag to specify package release information, rather see the `-release' flag.
`-Wl,flag'
`-Xlinker flag'
Pass a linker specific flag directly to the linker.

If the output-file ends in `.la', then a libtool library is created, which must be built only from library objects (`.lo' files). The `-rpath' option is required. In the current implementation, libtool libraries may not depend on other uninstalled libtool libraries (see section Inter-library dependencies).

If the output-file ends in `.a', then a standard library is created using ar and possibly ranlib.

If output-file ends in `.o' or `.lo', then a reloadable object file is created from the input files (generally using `ld -r'). This method is often called partial linking.

Otherwise, an executable program is created.

Execute mode

For execute mode, the library path is automatically set, then a program is executed.

The first of the mode-args is treated as a program name, with the rest as arguments to that program.

The following components of mode-args are treated specially:

`-dlopen file'
Add the directory containing file to the library path.

This mode sets the library path environment variable according to any `-dlopen' flags.

If any of the args are libtool executable wrappers, then they are translated into the name of their corresponding uninstalled binary, and any of their required library directories are added to the library path.

Install mode

In install mode, libtool interprets mode-args as an installation command beginning with cp, or a BSD-compatible install program.

The rest of the mode-args are interpreted as arguments to that command.

The command is run, and any necessary unprivileged post-installation commands are also completed.

Finish mode

Finish mode helps system administrators install libtool libraries so that they can be located and linked into user programs.

Each mode-arg is interpreted as the name of a library directory. Running this command may require superuser privileges, so the `--dry-run' option may be useful.

Uninstall mode

Uninstall mode deletes installed libraries, executables and objects.

The first mode-arg is the name of the program to use to delete files (typically `/bin/rm').

The remaining mode-args are either flags for the deletion program (beginning with a `-'), or the names of files to delete.

Clean mode

Clean mode deletes uninstalled libraries, executables, objects and libtool's temporary files associated with them.

The first mode-arg is the name of the program to use to delete files (typically `/bin/rm').

The remaining mode-args are either flags for the deletion program (beginning with a `-'), or the names of files to delete.

Integrating libtool with your package

This chapter describes how to integrate libtool with your packages so that your users can install hassle-free shared libraries.

Writing `Makefile' rules for libtool

Libtool is fully integrated with Automake (see section `Introduction' in The Automake Manual), starting with Automake version 1.2.

If you want to use libtool in a regular `Makefile' (or `Makefile.in'), you are on your own. If you're not using Automake 1.2, and you don't know how to incorporate libtool into your package you need to do one of the following:

  1. Download Automake (version 1.2 or later) from your nearest GNU mirror, install it, and start using it.
  2. Learn how to write `Makefile' rules by hand. They're sometimes complex, but if you're clever enough to write rules for compiling your old libraries, then you should be able to figure out new rules for libtool libraries (hint: examine the `Makefile.in' in the `demo' subdirectory of the libtool distribution... note especially that it was automatically generated from the `Makefile.am' by Automake).

Using Automake with libtool

Libtool library support is implemented under the `LTLIBRARIES' primary.

Here are some samples from the Automake `Makefile.am' in the libtool distribution's `demo' subdirectory.

First, to link a program against a libtool library, just use the `program_LDADD' variable:

bin_PROGRAMS = hell hell.debug

# Build hell from main.c and libhello.la
hell_SOURCES = main.c
hell_LDADD = libhello.la

# Create an easier-to-debug version of hell.
hell_debug_SOURCES = main.c
hell_debug_LDADD = libhello.la
hell_debug_LDFLAGS = -static

The flags `-dlopen' or `-dlpreopen' (see section Link mode) would fit better in the program_LDADD variable. Unfortunately, GNU automake, up to release 1.4, doesn't accept these flags in a program_LDADD variable, so you have the following alternatives:

  • add them to program_LDFLAGS, and list the libraries in program_DEPENDENCIES, then wait for a release of GNU automake that accepts these flags where they belong;
  • surround the flags between quotes, but then you must set program_DEPENDENCIES too:
    program_LDADD = "-dlopen" libfoo.la
program_DEPENDENCIES = libfoo.la
  • set and `AC_SUBST' variables DLOPEN and DLPREOPEN in `configure.in' and use `@DLOPEN@' and `@DLPREOPEN@' as replacements for the explicit flags `-dlopen' and `-dlpreopen' in `program_LDADD'. Automake will discard `AC_SUBST'ed variables from dependencies, so it will behave exactly as we expect it to behave when it accepts these flags in `program_LDADD'. But hey!, this is ugly!

You may use the `program_LDFLAGS' variable to stuff in any flags you want to pass to libtool while linking `program' (such as `-static' to avoid linking uninstalled shared libtool libraries).

Building a libtool library is almost as trivial... note the use of `libhello_la_LDFLAGS' to pass the `-version-info' (see section Library interface versions) option to libtool:

# Build a libtool library, libhello.la for installation in libdir.
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello.c foo.c
libhello_la_LDFLAGS = -version-info 3:12:1

The `-rpath' option is passed automatically by Automake (except for libraries listed as noinst_LTLIBRARIES), so you should not specify it.

See section `The Automake Manual' in The Automake Manual, for more information.

Configuring libtool

Libtool requires intimate knowledge of your compiler suite and operating system in order to be able to create shared libraries and link against them properly. When you install the libtool distribution, a system-specific libtool script is installed into your binary directory.

However, when you distribute libtool with your own packages (see section Including libtool in your package), you do not always know which compiler suite and operating system are used to compile your package.

For this reason, libtool must be configured before it can be used. This idea should be familiar to anybody who has used a GNU configure script. configure runs a number of tests for system features, then generates the `Makefiles' (and possibly a `config.h' header file), after which you can run make and build the package.

Libtool adds its own tests to your configure script in order to generate a libtool script for the installer's host machine.

The AC_PROG_LIBTOOL macro

If you are using GNU Autoconf (or Automake), you should add a call to AC_PROG_LIBTOOL to your `configure.in' file. This macro adds many new tests to the configure script so that the generated libtool script will understand the characteristics of the host:

Macro: AC_PROG_LIBTOOL
Macro: AM_PROG_LIBTOOL
Add support for the `--enable-shared' and `--disable-shared' configure flags.(4) AM_PROG_LIBTOOL was the old name for this macro, and although supported at the moment is deprecated.

By default, this macro turns on shared libraries if they are available, and also enables static libraries if they don't conflict with the shared libraries. You can modify these defaults by calling either the AC_DISABLE_SHARED or AC_DISABLE_STATIC macros:

# Turn off shared libraries during beta-testing, since they
# make the build process take too long.
AC_DISABLE_SHARED
AC_PROG_LIBTOOL

The user may specify modified forms of the configure flags `--enable-shared' and `--enable-static' to choose whether shared or static libraries are built based on the name of the package. For example, to have shared `bfd' and `gdb' libraries built, but not shared `libg++', you can run all three configure scripts as follows:

trick$ ./configure --enable-shared=bfd,gdb

In general, specifying `--enable-shared=pkgs' is the same as configuring with `--enable-shared' every package named in the comma-separated pkgs list, and every other package with `--disable-shared'. The `--enable-static=pkgs' flag behaves similarly, but it uses `--enable-static' and `--disable-static'. The same applies to the `--enable-fast-install=pkgs' flag, which uses `--enable-fast-install' and `--disable-fast-install'.

The package name `default' matches any packages which have not set their name in the PACKAGE environment variable.

This macro also sets the shell variable LIBTOOL_DEPS, that you can use to automatically update the libtool script if it becomes out-of-date. In order to do that, add to your `configure.in':

AC_PROG_LIBTOOL
AC_SUBST(LIBTOOL_DEPS)

and, to `Makefile.in' or `Makefile.am':

LIBTOOL_DEPS = @LIBTOOL_DEPS@
libtool: $(LIBTOOL_DEPS)
        $(SHELL) ./config.status --recheck

If you are using GNU automake, you can omit the assignment, as automake will take care of it. You'll obviously have to create some dependency on `libtool'.

Macro: AC_LIBTOOL_DLOPEN
Enable checking for dlopen support. This macro should be used if the package makes use of the `-dlopen' and `-dlpreopen' flags, otherwise libtool will assume that the system does not support dlopening. The macro must be called before AC_PROG_LIBTOOL.

Macro: AC_LIBTOOL_WIN32_DLL
This macro should be used if the package has been ported to build clean dlls on win32 platforms. Usually this means that any library data items are exported with __declspec(dllexport) and imported with __declspec(dllimport). If this macro is not used, libtool will assume that the package libraries are not dll clean and will build only static libraries on win32 hosts.

This macro must be called before AC_PROG_LIBTOOL, and provision must be made to pass `-no-undefined' to libtool in link mode from the package Makefile. Naturally, if you pass `-no-undefined', you must ensure that all the library symbols really are defined at link time!

Macro: AC_DISABLE_FAST_INSTALL
Change the default behaviour for AC_PROG_LIBTOOL to disable optimization for fast installation. The user may still override this default, depending on platform support, by specifying `--enable-fast-install'.

Macro: AC_DISABLE_SHARED
Macro: AM_DISABLE_SHARED
Change the default behaviour for AC_PROG_LIBTOOL to disable shared libraries. The user may still override this default by specifying `--enable-shared'.

Macro: AC_DISABLE_STATIC
Macro: AM_DISABLE_STATIC
Change the default behaviour for AC_PROG_LIBTOOL to disable static libraries. The user may still override this default by specifying `--enable-static'.

The tests in AC_PROG_LIBTOOL also recognize the following environment variables:

Variable: CC
The C compiler that will be used by the generated libtool. If this is not set, AC_PROG_LIBTOOL will look for gcc or cc.

Variable: CFLAGS
Compiler flags used to generate standard object files. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: CPPFLAGS
C preprocessor flags. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: LD
The system linker to use (if the generated libtool requires one). If this is not set, AC_PROG_LIBTOOL will try to find out what is the linker used by CC.

Variable: LDFLAGS
The flags to be used by libtool when it links a program. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: LIBS
The libraries to be used by AC_PROG_LIBTOOL when it links a program. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: NM
Program to use rather than checking for nm.

Variable: RANLIB
Program to use rather than checking for ranlib.

Variable: LN_S
A command that creates a link of a program, a soft-link if possible, a hard-link otherwise. AC_PROG_LIBTOOL will check for a suitable program if this variable is not set.

Variable: DLLTOOL
Program to use rather than checking for dlltool. Only meaningful for Cygwin/MS-Windows.

Variable: OBJDUMP
Program to use rather than checking for objdump. Only meaningful for Cygwin/MS-Windows.

Variable: AS
Program to use rather than checking for as. Only used on Cygwin/MS-Windows at the moment.

When you invoke the libtoolize program (see section Invoking libtoolize), it will tell you where to find a definition of AC_PROG_LIBTOOL. If you use Automake, the aclocal program will automatically add AC_PROG_LIBTOOL support to your configure script.

Nevertheless, it is advisable to include a copy of `libtool.m4' in `acinclude.m4', so that, even if `aclocal.m4' and `configure' are rebuilt for any reason, the appropriate libtool macros will be used. The alternative is to hope the user will have a compatible version of `libtool.m4' installed and accessible for aclocal. This may lead to weird errors when versions don't match.

Including libtool in your package

In order to use libtool, you need to include the following files with your package:

`config.guess'
Attempt to guess a canonical system name.
`config.sub'
Canonical system name validation subroutine script.
`ltmain.sh'
A generic script implementing basic libtool functionality.

Note that the libtool script itself should not be included with your package. See section Configuring libtool.

You should use the libtoolize program, rather than manually copying these files into your package.

Invoking libtoolize

The libtoolize program provides a standard way to add libtool support to your package. In the future, it may implement better usage checking, or other features to make libtool even easier to use.

The libtoolize program has the following synopsis:

libtoolize [option]...

and accepts the following options:

`--automake'
Work silently, and assume that Automake libtool support is used. `libtoolize --automake' is used by Automake to add libtool files to your package, when AC_PROG_LIBTOOL appears in your `configure.in'.
`--copy'
`-c'
Copy files from the libtool data directory rather than creating symlinks.
`--debug'
Dump a trace of shell script execution to standard output. This produces a lot of output, so you may wish to pipe it to less (or more) or redirect to a file.
`--dry-run'
`-n'
Don't run any commands that modify the file system, just print them out.
`--force'
`-f'
Replace existing libtool files. By default, libtoolize won't overwrite existing files.
`--help'
Display a help message and exit.
`--ltdl'
Install libltdl in a subdirectory of your package.
`--ltdl-tar'
Add the file libltdl.tar.gz to your package.
`--version'
Print libtoolize version information and exit.

If libtoolize detects an explicit call to AC_CONFIG_AUX_DIR (see section `The Autoconf Manual' in The Autoconf Manual) in your `configure.in', it will put the files in the specified directory.

libtoolize displays hints for adding libtool support to your package, as well.

Autoconf `.o' macros

The Autoconf package comes with a few macros that run tests, then set a variable corresponding to the name of an object file. Sometimes it is necessary to use corresponding names for libtool objects.

Here are the names of variables that list libtool objects:

Variable: LTALLOCA
Substituted by AC_FUNC_ALLOCA (see section `The Autoconf Manual' in The Autoconf Manual). Is either empty, or contains `alloca.lo'.

Variable: LTLIBOBJS
Substituted by AC_REPLACE_FUNCS (see section `The Autoconf Manual' in The Autoconf Manual), and a few other functions.

Unfortunately, the stable release of Autoconf (2.13, at the time of this writing) does not have any way for libtool to provide support for these variables. So, if you depend on them, use the following code immediately before the call to AC_OUTPUT in your `configure.in':

LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
AC_SUBST(LTLIBOBJS)
LTALLOCA=`echo "$ALLOCA" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
AC_SUBST(LTALLOCA)
AC_OUTPUT(...)

Static-only libraries

When you are developing a package, it is often worthwhile to configure your package with the `--disable-shared' flag, or to override the defaults for AC_PROG_LIBTOOL by using the AC_DISABLE_SHARED Autoconf macro (see section The AC_PROG_LIBTOOL macro). This prevents libtool from building shared libraries, which has several advantages:

  • compilation is twice as fast, which can speed up your development cycle,
  • debugging is easier because you don't need to deal with any complexities added by shared libraries, and
  • you can see how libtool behaves on static-only platforms.

You may want to put a small note in your package `README' to let other developers know that `--disable-shared' can save them time. The following example note is taken from the GIMP(5) distribution `README':

The GIMP uses GNU Libtool in order to build shared libraries on a
variety of systems. While this is very nice for making usable
binaries, it can be a pain when trying to debug a program. For that
reason, compilation of shared libraries can be turned off by
specifying the `--disable-shared' option to `configure'.

Library interface versions

The most difficult issue introduced by shared libraries is that of creating and resolving runtime dependencies. Dependencies on programs and libraries are often described in terms of a single name, such as sed. So, one may say "libtool depends on sed," and that is good enough for most purposes.

However, when an interface changes regularly, we need to be more specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the description of an interface consists of a name, and a "version number."

Even that sort of description is not accurate enough for some purposes. What if Emacs 20 changes enough to break Gnus 5.1?

The same problem exists in shared libraries: we require a formal version system to describe the sorts of dependencies that programs have on shared libraries, so that the dynamic linker can guarantee that programs are linked only against libraries that provide the interface they require.

What are library interfaces?

Interfaces for libraries may be any of the following (and more):

  • global variables: both names and types
  • global functions: argument types and number, return types, and function names
  • standard input, standard output, standard error, and file formats
  • sockets, pipes, and other inter-process communication protocol formats

Note that static functions do not count as interfaces, because they are not directly available to the user of the library.

Libtool's versioning system

Libtool has its own formal versioning system. It is not as flexible as some, but it is definitely the simplest of the more powerful versioning systems.

Think of a library as exporting several sets of interfaces, arbitrarily represented by integers. When a program is linked against a library, it may use any subset of those interfaces.

Libtool's description of the interfaces that a program uses is simple: it encodes the least and the greatest interface numbers in the resulting binary (first-interface, last-interface).

The dynamic linker is guaranteed that if a library supports every interface number between first-interface and last-interface, then the program can be relinked against that library.

Note that this can cause problems because libtool's compatibility requirements are actually stricter than is necessary.

Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that libtool is used to link `test' against `libhello'.

Libtool encodes the numbers 5 and 19 in `test', and the dynamic linker will only link `test' against libraries that support every interface between 5 and 19. So, the dynamic linker refuses to link `test' against `libhello'!

In order to eliminate this problem, libtool only allows libraries to declare consecutive interface numbers. So, `libhello' can declare at most that it supports interfaces 16 through 19. Then, the dynamic linker will link `test' against `libhello'.

So, libtool library versions are described by three integers:

current
The most recent interface number that this library implements.
revision
The implementation number of the current interface.
age
The difference between the newest and oldest interfaces that this library implements. In other words, the library implements all the interface numbers in the range from number current - age to current.

If two libraries have identical current and age numbers, then the dynamic linker chooses the library with the greater revision number.

Updating library version information

If you want to use libtool's versioning system, then you must specify the version information to libtool using the `-version-info' flag during link mode (see section Link mode).

This flag accepts an argument of the form `current[:revision[:age]]'. So, passing `-version-info 3:12:1' sets current to 3, revision to 12, and age to 1.

If either revision or age are omitted, they default to 0. Also note that age must be less than or equal to the current interface number.

Here are a set of rules to help you update your library version information:

  1. Start with version information of `0:0:0' for each libtool library.
  2. Update the version information only immediately before a public release of your software. More frequent updates are unnecessary, and only guarantee that the current interface number gets larger faster.
  3. If the library source code has changed at all since the last update, then increment revision (`c:r:a' becomes `c:r+1:a').
  4. If any interfaces have been added, removed, or changed since the last update, increment current, and set revision to 0.
  5. If any interfaces have been added since the last public release, then increment age.
  6. If any interfaces have been removed since the last public release, then set age to 0.

Never try to set the interface numbers so that they correspond to the release number of your package. This is an abuse that only fosters misunderstanding of the purpose of library versions. Instead, use the `-release' flag (see section Managing release information), but be warned that every release of your package will not be binary compatible with any other release.

Managing release information

Often, people want to encode the name of the package release into the shared library so that it is obvious to the user which package their programs are linked against. This convention is used especially on GNU/Linux:

trick$ ls /usr/lib/libbfd*
/usr/lib/libbfd.a	    /usr/lib/libbfd.so.2.7.0.2
/usr/lib/libbfd.so
trick$

On `trick', `/usr/lib/libbfd.so' is a symbolic link to `libbfd.so.2.7.0.2', which was distributed as a part of `binutils-2.7.0.2'.

Unfortunately, this convention conflicts directly with libtool's idea of library interface versions, because the library interface rarely changes at the same time that the release number does, and the library suffix is never the same across all platforms.

So, in order to accommodate both views, you can use the `-release' flag in order to set release information for libraries which you do not want to use `-version-info'. For the `libbfd' example, the next release which uses libtool should be built with `-release 2.9.0', which will produce the following files on GNU/Linux:

trick$ ls /usr/lib/libbfd*
/usr/lib/libbfd-2.9.0.so     /usr/lib/libbfd.a
/usr/lib/libbfd.so
trick$

In this case, `/usr/lib/libbfd.so' is a symbolic link to `libbfd-2.9.0.so'. This makes it obvious that the user is dealing with `binutils-2.9.0', without compromising libtool's idea of interface versions.

Note that this option causes a modification of the library name, so do not use it unless you want to break binary compatibility with any past library releases. In general, you should only use `-release' for package-internal libraries or for ones whose interfaces change very frequently.

Tips for interface design

Writing a good library interface takes a lot of practice and thorough understanding of the problem that the library is intended to solve.

If you design a good interface, it won't have to change often, you won't have to keep updating documentation, and users won't have to keep relearning how to use the library.

Here is a brief list of tips for library interface design, which may help you in your exploits:

Plan ahead
Try to make every interface truly minimal, so that you won't need to delete entry points very often.
Avoid interface changes
Some people love redesigning and changing entry points just for the heck of it (note: renaming a function is considered changing an entry point). Don't be one of those people. If you must redesign an interface, then try to leave compatibility functions behind so that users don't need to rewrite their existing code.
Use opaque data types
The fewer data type definitions a library user has access to, the better. If possible, design your functions to accept a generic pointer (which you can cast to an internal data type), and provide access functions rather than allowing the library user to directly manipulate the data. That way, you have the freedom to change the data structures without changing the interface. This is essentially the same thing as using abstract data types and inheritance in an object-oriented system.
Use header files
If you are careful to document each of your library's global functions and variables in header files, and include them in your library source files, then the compiler will let you know if you make any interface changes by accident (see section Writing C header files).
Use the static keyword (or equivalent) whenever possible
The fewer global functions your library has, the more flexibility you'll have in changing them. Static functions and variables may change forms as often as you like... your users cannot access them, so they aren't interface changes.

Writing C header files

Writing portable C header files can be difficult, since they may be read by different types of compilers:

C++ compilers
C++ compilers require that functions be declared with full prototypes, since C++ is more strongly typed than C. C functions and variables also need to be declared with the extern "C" directive, so that the names aren't mangled. See section Writing libraries for C++, for other issues relevant to using C++ with libtool.
ANSI C compilers
ANSI C compilers are not as strict as C++ compilers, but functions should be prototyped to avoid unnecessary warnings when the header file is #included.
non-ANSI C compilers
Non-ANSI compilers will report errors if functions are prototyped.

These complications mean that your library interface headers must use some C preprocessor magic in order to be usable by each of the above compilers.

`foo.h' in the `demo' subdirectory of the libtool distribution serves as an example for how to write a header file that can be safely installed in a system directory.

Here are the relevant portions of that file:

/* BEGIN_C_DECLS should be used at the beginning of your declarations,
   so that C++ compilers don't mangle their names.  Use END_C_DECLS at
   the end of C declarations. */
#undef BEGIN_C_DECLS
#undef END_C_DECLS
#ifdef __cplusplus
# define BEGIN_C_DECLS extern "C" {
# define END_C_DECLS }
#else
# define BEGIN_C_DECLS /* empty */
# define END_C_DECLS /* empty */
#endif

/* PARAMS is a macro used to wrap function prototypes, so that
   compilers that don't understand ANSI C prototypes still work,
   and ANSI C compilers can issue warnings about type mismatches. */
#undef PARAMS
#if defined (__STDC__) || defined (_AIX) \
        || (defined (__mips) && defined (_SYSTYPE_SVR4)) \
        || defined(WIN32) || defined(__cplusplus)
# define PARAMS(protos) protos
#else
# define PARAMS(protos) ()
#endif

These macros are used in `foo.h' as follows:

#ifndef FOO_H
#define FOO_H 1

/* The above macro definitions. */
#include "..."

BEGIN_C_DECLS

int foo PARAMS((void));
int hello PARAMS((void));

END_C_DECLS

#endif /* !FOO_H */

Note that the `#ifndef FOO_H' prevents the body of `foo.h' from being read more than once in a given compilation.

Also the only thing that must go outside the BEGIN_C_DECLS/END_C_DECLS pair are #include lines. Strictly speaking it is only C symbol names that need to be protected, but your header files will be more maintainable if you have a single pair of of these macros around the majority of the header contents.

You should use these definitions of PARAMS, BEGIN_C_DECLS, and END_C_DECLS into your own headers. Then, you may use them to create header files that are valid for C++, ANSI, and non-ANSI compilers(6).

Do not be naive about writing portable code. Following the tips given above will help you miss the most obvious problems, but there are definitely other subtle portability issues. You may need to cope with some of the following issues:

  • Pre-ANSI compilers do not always support the void * generic pointer type, and so need to use char * in its place.
  • The const, inline and signed keywords are not supported by some compilers, especially pre-ANSI compilers.
  • The long double type is not supported by many compilers.

Inter-library dependencies

By definition, every shared library system provides a way for executables to depend on libraries, so that symbol resolution is deferred until runtime.

An inter-library dependency is one in which a library depends on other libraries. For example, if the libtool library `libhello' uses the cos function, then it has an inter-library dependency on `libm', the math library that implements cos.

Some shared library systems provide this feature in an internally-consistent way: these systems allow chains of dependencies of potentially infinite length.

However, most shared library systems are restricted in that they only allow a single level of dependencies. In these systems, programs may depend on shared libraries, but shared libraries may not depend on other shared libraries.

In any event, libtool provides a simple mechanism for you to declare inter-library dependencies: for every library `libname' that your own library depends on, simply add a corresponding -lname option to the link line when you create your library. To make an example of our `libhello' that depends on `libm':

burger$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \
                -rpath /usr/local/lib -lm
burger$

When you link a program against `libhello', you don't need to specify the same `-l' options again: libtool will do that for you, in order to guarantee that all the required libraries are found. This restriction is only necessary to preserve compatibility with static library systems and simple dynamic library systems.

Some platforms, such as AIX, do not even allow you this flexibility. In order to build a shared library, it must be entirely self-contained (that is, have references only to symbols that are found in the `.lo' files or the specified `-l' libraries), and you need to specify the -no-undefined flag. By default, libtool builds only static libraries on these kinds of platforms.

The simple-minded inter-library dependency tracking code of libtool releases prior to 1.2 was disabled because it was not clear when it was possible to link one library with another, and complex failures would occur. A more complex implementation of this concept was re-introduced before release 1.3, but it has not been ported to all platforms that libtool supports. The default, conservative behavior is to avoid linking one library with another, introducing their inter-dependencies only when a program is linked with them.

Dlopened modules

It can sometimes be confusing to discuss dynamic linking, because the term is used to refer to two different concepts:

  1. Compiling and linking a program against a shared library, which is resolved automatically at run time by the dynamic linker. In this process, dynamic linking is transparent to the application.
  2. The application calling functions such as dlopen,(7) which load arbitrary, user-specified modules at runtime. This type of dynamic linking is explicitly controlled by the application.

To mitigate confusion, this manual refers to the second type of dynamic linking as dlopening a module.

The main benefit to dlopening object modules is the ability to access compiled object code to extend your program, rather than using an interpreted language. In fact, dlopen calls are frequently used in language interpreters to provide an efficient way to extend the language.

As of version 1.4.2, libtool provides support for dlopened modules. However, you should indicate that your package is willing to use such support, by using the macro `AC_LIBTOOL_DLOPEN' in `configure.in'. If this macro is not used (or it is used after `AC_PROG_LIBTOOL'), libtool will assume no dlopening mechanism is available, and will try to simulate it.

This chapter discusses how you as a dlopen application developer might use libtool to generate dlopen-accessible modules.

Building modules to dlopen

On some operating systems, a program symbol must be specially declared in order to be dynamically resolved with the dlsym (or equivalent) function.

Libtool provides the `-export-dynamic' and `-module' link flags (see section Link mode), which do this declaration. You need to use these flags if you are linking an application program that dlopens other modules or a libtool library that will also be dlopened.

For example, if we wanted to build a shared library, `libhello', that would later be dlopened by an application, we would add `-module' to the other link flags:

burger$ libtool gcc -module -o libhello.la foo.lo \
                hello.lo -rpath /usr/local/lib -lm
burger$

If symbols from your executable are needed to satisfy unresolved references in a library you want to dlopen you will have to use the flag `-export-dynamic'. You should use `-export-dynamic' while linking the executable that calls dlopen:

burger$ libtool gcc -export-dynamic -o hell-dlopener main.o
burger$

Dlpreopening

Libtool provides special support for dlopening libtool object and libtool library files, so that their symbols can be resolved even on platforms without any dlopen and dlsym functions.

Consider the following alternative ways of loading code into your program, in order of increasing "laziness":

  1. Linking against object files that become part of the program executable, whether or not they are referenced. If an object file cannot be found, then the linker refuses to create the executable.
  2. Declaring a static library to the linker, so that it is searched at link time in order to satisfy any undefined references in the above object files. If the static library cannot be found, then the linker refuses to link the executable.
  3. Declaring a shared library to the runtime linker, so that it is searched at runtime in order to satisfy any undefined references in the above files. If the shared library cannot be found, then the dynamic linker aborts the program before it runs.
  4. Dlopening a module, so that the application can resolve its own, dynamically-computed references. If there is an error opening the module, or the module is not found, then the application can recover without crashing.

Libtool emulates `-dlopen' on static platforms by linking objects into the program at compile time, and creating data structures that represent the program's symbol table.

In order to use this feature, you must declare the objects you want your application to dlopen by using the `-dlopen' or `-dlpreopen' flags when you link your program (see section Link mode).

Structure: struct lt_dlsymlist { const char *name; lt_ptr address; }
The name attribute is a null-terminated character string of the symbol name, such as "fprintf". The address attribute is a generic pointer to the appropriate object, such as &fprintf.

Variable: const lt_dlsymlist * lt_preloaded_symbols
An array of lt_symbol structures, representing all the preloaded symbols linked into the program. For each `-dlpreloaded' file there is an element with the name of the file and a address of 0, followed by all symbols exported from this file. For the executable itself the special name @PROGRAM@ is used. The last element has a name and address of 0.

Some compilers may allow identifiers which are not valid in ANSI C, such as dollar signs. Libtool only recognizes valid ANSI C symbols (an initial ASCII letter or underscore, followed by zero or more ASCII letters, digits, and underscores), so non-ANSI symbols will not appear in lt_preloaded_symbols.

Finding the correct name to dlopen

After a library has been linked with `-module', it can be dlopened. Unfortunately, because of the variation in library names, your package needs to determine the correct file to dlopen.

The most straightforward and flexible implementation is to determine the name at runtime, by finding the installed `.la' file, and searching it for the following lines:

# The name that we can dlopen.
dlname='dlname'

If dlname is empty, then the library cannot be dlopened. Otherwise, it gives the dlname of the library. So, if the library was installed as `/usr/local/lib/libhello.la', and the dlname was `libhello.so.3', then `/usr/local/lib/libhello.so.3' should be dlopened.

If your program uses this approach, then it should search the directories listed in the LD_LIBRARY_PATH (8) environment variable, as well as the directory where libraries will eventually be installed. Searching this variable (or equivalent) will guarantee that your program can find its dlopened modules, even before installation, provided you have linked them using libtool.

Unresolved dlopen issues

The following problems are not solved by using libtool's dlopen support:

  • Dlopen functions are generally only available on shared library platforms. If you want your package to be portable to static platforms, you have to use either libltdl (see section Using libltdl) or develop your own alternatives to dlopening dynamic code. Most reasonable solutions involve writing wrapper functions for the dlopen family, which do package-specific tricks when dlopening is unsupported or not available on a given platform.
  • There are major differences in implementations of the dlopen family of functions. Some platforms do not even use the same function names (notably HP-UX, with its shl_load family).
  • The application developer must write a custom search function in order to discover the correct module filename to supply to dlopen.

Using libltdl

Libtool provides a small library, called `libltdl', that aims at hiding the various difficulties of dlopening libraries from programmers. It consists of a header-file and a small C source file that can be distributed with applications that need dlopening functionality. On some platforms, whose dynamic linkers are too limited for a simple implementation of `libltdl' services, it requires GNU DLD, or it will only emulate dynamic linking with libtool's dlpreopening mechanism.

libltdl supports currently the following dynamic linking mechanisms:

  • dlopen (Solaris, Linux and various BSD flavors)
  • shl_load (HP-UX)
  • LoadLibrary (Win16 and Win32)
  • load_add_on (BeOS)
  • GNU DLD (emulates dynamic linking for static libraries)
  • libtool's dlpreopen (see see section Dlpreopening)

libltdl is licensed under the terms of the GNU Library General Public License, with the following exception:

As a special exception to the GNU Lesser General Public License, if you distribute this file as part of a program or library that is built using GNU libtool, you may include it under the same distribution terms that you use for the rest of that program.

How to use libltdl in your programs

The libltdl API is similar to the dlopen interface of Solaris and Linux, which is very simple but powerful.

To use libltdl in your program you have to include the header file `ltdl.h':

#include <ltdl.h>

The last release of libltdl used some symbols that violated the POSIX namespace conventions. These symbols are now deprecated, and have been replaced by those described here. If you have code that relies on the old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before you include `ltdl.h' provides conversion macros. Whichever set of symbols you use, the new api is not binary compatible with the last, so you will need to recompile your application in order to use this version of libltdl.

Note that libltdl is not threadsafe, i.e. a multithreaded application has to use a mutex for libltdl. It was reported that GNU/Linux's glibc 2.0's dlopen with `RTLD_LAZY' (which libltdl uses by default) is not thread-safe, but this problem is supposed to be fixed in glibc 2.1. On the other hand, `RTLD_NOW' was reported to introduce problems in multi-threaded applications on FreeBSD. Working around these problems is left as an exercise for the reader; contributions are certainly welcome.

The following types are defined in `ltdl.h':

Type: lt_ptr
lt_ptr is a generic pointer.

Type: lt_dlhandle
lt_dlhandle is a module "handle". Every lt_dlopened module has a handle associated with it.

Type: lt_dlsymlist
lt_dlsymlist is a symbol list for dlpreopened modules. This structure is described in see section Dlpreopening.

libltdl provides the following functions:

Function: int lt_dlinit (void)
Initialize libltdl. This function must be called before using libltdl and may be called several times. Return 0 on success, otherwise the number of errors.

Function: int lt_dlexit (void)
Shut down libltdl and close all modules. This function will only then shut down libltdl when it was called as many times as lt_dlinit has been successfully called. Return 0 on success, otherwise the number of errors.

Function: lt_dlhandle lt_dlopen (const char *filename)
Open the module with the file name filename and return a handle for it. lt_dlopen is able to open libtool dynamic modules, preloaded static modules, the program itself and native dynamic libraries.

Unresolved symbols in the module are resolved using its dependency libraries (not implemented yet) and previously dlopened modules. If the executable using this module was linked with the -export-dynamic flag, then the global symbols in the executable will also be used to resolve references in the module.

If filename is NULL and the program was linked with -export-dynamic or -dlopen self, lt_dlopen will return a handle for the program itself, which can be used to access its symbols.

If libltdl cannot find the library and the file name filename does not have a directory component it will additionally search in the following search paths for the module (in the order as follows):

  1. user-defined search path: This search path can be set by the program using the functions lt_dlsetsearchpath and lt_dladdsearchdir.
  2. libltdl's search path: This search path is the value of the environment variable LTDL_LIBRARY_PATH.
  3. system library search path: The system dependent library search path (e.g. on Linux it is LD_LIBRARY_PATH).

Each search path must be a colon-separated list of absolute directories, for example, "/usr/lib/mypkg:/lib/foo".

If the same module is loaded several times, the same handle is returned. If lt_dlopen fails for any reason, it returns NULL.

Function: lt_dlhandle lt_dlopenext (const char *filename)
The same as lt_dlopen, except that it tries to append different file name extensions to the file name. If the file with the file name filename cannot be found libltdl tries to append the following extensions:

  1. the libtool archive extension `.la'
  2. the extension used for native dynamic libraries on the host platform, e.g., `.so', `.sl', etc.

This lookup strategy was designed to allow programs that don't have knowledge about native dynamic libraries naming conventions to be able to dlopen such libraries as well as libtool modules transparently.

Function: int lt_dlclose (lt_dlhandle handle)
Decrement the reference count on the module handle. If it drops to zero and no other module depends on this module, then the module is unloaded. Return 0 on success.

Function: lt_ptr lt_dlsym (lt_dlhandle handle, const char *name)
Return the address in the module handle, where the symbol given by the null-terminated string name is loaded. If the symbol cannot be found, NULL is returned.

Function: {const char *}lt_dlerror (void)
Return a human readable string describing the most recent error that occurred from any of libltdl's functions. Return NULL if no errors have occurred since initialization or since it was last called.

Function: int lt_dlpreload (const lt_dlsymlist *preloaded)
Register the list of preloaded modules preloaded. If preloaded is NULL, then all previously registered symbol lists, except the list set by lt_dlpreload_default, are deleted. Return 0 on success.

Function: int lt_dlpreload_default (const lt_dlsymlist *preloaded)
Set the default list of preloaded modules to preloaded, which won't be deleted by lt_dlpreload. Note that this function does not require libltdl to be initialized using lt_dlinit and can be used in the program to register the default preloaded modules. Instead of calling this function directly, most programs will use the macro LTDL_SET_PRELOADED_SYMBOLS.

Return 0 on success.

Macro: LTDL_SET_PRELOADED_SYMBOLS()
Set the default list of preloaded symbols. Should be used in your program to initialize libltdl's list of preloaded modules.

#include <ltdl.h>

int main() {
  /* ... */
  LTDL_SET_PRELOADED_SYMBOLS();
  /* ... */
}

Function: int lt_dladdsearchdir (const char *search_dir)
Add the search directory search_dir to the user-defined library search path. Return 0 on success.

Function: int lt_dlsetsearchpath (const char *search_path)
Replace the current user-defined library search path with search_path, which must be a colon-separated list of absolute directories. Return 0 on success.

Function: {const char *}lt_dlgetsearchpath (void)
Return the current user-defined library search path.

Function: int lt_dlmakeresident (lt_dlhandle handle)
Mark a module so that it cannot be `lt_dlclose'd. This can be useful if a module implements some core functionality in your project, which would cause your code to crash if removed. Return 0 on success.

If you use `lt_dlopen (NULL)' to get a handle for the running binary, that handle will always be marked as resident, and consequently cannot be successfully `lt_dlclose'd.

Function: int lt_dlisresident (lt_dlhandle handle)
Check whether a particular module has been marked as resident, returning 1 if it has or 0 otherwise. If there is an error while executing this function, return -1 and set an error message for retrieval with lt_dlerror.

Variable: lt_ptr (*) (size_t size) lt_dlmalloc
Variable: void (*) (lt_ptr ptr) lt_dlfree
These variables are set to malloc and free, by default, but you can set them to any other functions that provides equivalent functionality. However, you must not modify their values after calling any libltdl function other than lt_dlpreopen_default or the macro LTDL_SET_PRELOADED_SYMBOLS.

Creating modules that can be dlopened

Libtool modules are like normal libtool libraries with a few exceptions:

You have to link the module with libtool's `-module' switch, and you should link any program that is intended to dlopen the module with `-dlopen modulename.la' so that libtool can dlpreopen the module on platforms which don't support dlopening. If the module depends on any other libraries, make sure you specify them either when you link the module or when you link programs that dlopen it. If you want to disable see section Library interface versions for a specific module you should link it with the `-avoid-version' switch. Note that libtool modules don't need to have a "lib" prefix. However, automake 1.4 or higher is required to build such modules.

Usually a set of modules provide the same interface, i.e, exports the same symbols, so that a program can dlopen them without having to know more about their internals. In order to avoid symbol conflicts all exported symbols must be prefixed with "modulename_LTX_" (`modulename' is the name of the module). Internal symbols must be named in such a way that they won't conflict with other modules, for example, by prefixing them with "_modulename_". Although some platforms support having the same symbols defined more than once it is generally not portable and it makes it impossible to dlpreopen such modules. libltdl will automatically cut the prefix off to get the real name of the symbol. Additionally, it supports modules which don't use a prefix so that you can also dlopen non-libtool modules.

`foo1.c' gives an example of a portable libtool module. Exported symbols are prefixed with "foo1_LTX_", internal symbols with "_foo1_". Aliases are defined at the beginning so that the code is more readable.

/* aliases for the exported symbols */
#define foo	foo1_LTX_foo
#define bar	foo1_LTX_bar

/* a global variable definition */
int bar = 1;

/* a private function */
int _foo1_helper() {
  return bar;
}

/* an exported function */
int foo() {
  return _foo1_helper();
}

The `Makefile.am' contains the necessary rules to build the module `foo1.la':

...
lib_LTLIBRARIES = foo1.la

foo1_la_SOURCES = foo1.c
foo1_la_LDFLAGS = -module
...

Using libtldl in a multi threaded environment

Using the lt_dlmutex_register() function, and by providing some appropriate callback function definitions, libltdl can be used in a multi-threaded environment.

Type: void lt_dlmutex_lock (void)
This is the type of a function pointer holding the address of a function which will be called at the start of parts of the libltdl implementation code which require a mutex lock.

Because libltdl is inherantly recursive, it is important that the locking mechanism employed by these callback functions are reentrant, or else strange problems will occur.

Type: void lt_dlmutex_unlock (void)
The type of a matching unlock function.

Type: void lt_dlmutex_seterror (const char *error);
Many of the functions in the libltdl API have a special return value to indicate to the client that an error has occured. Normally (in single threaded applications) a string describing that error can be retrieved from internal storage with lt_dlerror().

A function of this type must be registered with the library in order for it to work in a multi-threaded context. The function should store any error message passed in thread local storage.

Type: const char * lt_dlmutex_geterror (void)
The type of a matching callback function to retrieve the last stored error message from thread local storage.

When regeistered correctly this function will be used by lt_dlerror()) from all threads to retrieve error messages for the client.

Function: int lt_dlmutex_register (lt_dlmutex_lock *lock, lt_dlmutex_unlock *unlock, lt_dlmutex_set_error *seterror, lt_dlmutex_geterror *geterror)
Use this function to register one of each of function ttypes described above in preparation for multi-threaded use of libltdl. All arguments must be valid non-NULL function addresses, or else all NULL to return to single threaded operation.

Data associated with loaded modules

Some of the internal information about each loaded module that is maintained by libltdl is available to the user, in the form of this structure:

Type: struct lt_dlinfo { char *filename; char *name; int ref_count; }
lt_dlinfo is used to store information about a module. The filename attribute is a null-terminated character string of the real module file name. If the module is a libtool module then name is its module name (e.g. "libfoo" for "dir/libfoo.la"), otherwise it is set to NULL. The ref_count attribute is a reference counter that describes how often the same module is currently loaded.

The following function will return a pointer to libltdl's internal copy of this structure for the given handle:

Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle handle)
Return a pointer to a struct that contains some information about the module handle. The contents of the struct must not be modified. Return NULL on failure.

Furthermore, in order to save you from having to keep a list of the handles of all the modules you have loaded, these functions allow you to iterate over libltdl's list of loaded modules:

Function: int lt_dlforeach (int (*func) (lt_dlhandle handle, lt_ptr data), lt_ptr data)
For each loaded module call the function func. The argument handle is the handle of one of the loaded modules, data is the data argument passed to lt_dlforeach. As soon as func returns a non-zero value for one of the handles, lt_dlforeach will stop calling func and immediately return 1. Otherwise 0 is returned.

Function: lt_dlhandle lt_dlhandle_next (lt_dlhandle place)
Iterate over the loaded module handles, returning the first handle in the list if place is NULL, and the next one on subsequent calls. If place is the last element in the list of loaded modules, this function returns NULL.

Of course, you would still need to maintain your own list of loaded module handles to parallel the list maintained by libltdl if there are any other data that you need to associate with each handle for the purposes of your application. However, if you use the following API calls to associate your application data with individual module handles as they are loaded there is actually no need to do that. You must first obtain a unique caller id from libltdl which you subsequently use to retrieve the data you stored earlier. This allows for different libraries that each wish to store their own data against loaded modules to do so without interfering with one another's data.

Type: lt_dlcaller_id
The opaque type used to hold individual data set keys.

Function: lt_dlcaller_id lt_dlcaller_register (void)
Use this to obtain a unique key to store and retrieve individual sets of per module data.

Function: lt_ptr lt_dlcaller_set_data (lt_dlcaller_id key, lt_dlhandle handle, lt_ptr data)
Set data as the set of data uniquely associated with key and handle for later retrieval. This function returns the data previously associated with key and handle if any. A result of 0, may indicate that a diagnostic for the last error (if any) is available from lt_dlerror().

For example, to correctly remove some associated data:

    lt_ptr stale = lt_dlcaller_set_data (key, handle, 0);
    if (stale == NULL)
      {
        char *error_msg = lt_dlerror ();

        if (error_msg != NULL)
          {
            my_error_handler (error_msg);
            return STATUS_FAILED;
          }
      }
    else
      {
        free (stale);
      }

Function: lt_ptr lt_dlcaller_get_data (lt_dlcaller_id key, lt_dlhandle handle)
Return the address of the data associated with key and handle, or else NULL if there is none.

The preceding functions can be combined with lt_dlforeach to implement search and apply operations without the need for your application to track the modules that have been loaded and unloaded:

int
my_dlcaller_callback (lt_dlhandle handle, lt_ptr key_ptr)
{
  struct my_module_data *my_data;

  my_data = lt_dlcaller_get_data (handle, (lt_dlcaller_id) *key_ptr);

  return process (my_data);
}

int
my_dlcaller_foreach (lt_dlcaller_id key)
{
  lt_dlforeach (my_dlcaller_callback, (lt_ptr) &key);
}

How to create and register new module loaders

Sometimes libltdl's many ways of gaining access to modules are not sufficient for the purposes of a project. You can write your own loader, and register it with libltdl so that lt_dlopen will be able to use it.

Writing a loader involves writing at least three functions which can be called by lt_dlopen, lt_dlsym and lt_dlclose. Optionally, you can provide a finalisation function to perform any cleanup operations when lt_dlexit executes, and a symbol prefix string which will be prepended to any symbols passed to lt_dlsym. These functions must match the function pointer types below, after which they can be allocated to an instance of lt_user_dlloader and registered.

Registering the loader requires that you choose a name for it, so that it can be recognised by lt_dlloader_find and removed with lt_dlloader_remove. The name you choose must be unique, and not already in use by libltdl's builtin loaders:

"dlopen"
The system dynamic library loader, if one exists.
"dld"
The GNU dld loader, if `libdld' was installed when libltdl was built.
"dlpreload"
The loader for lt_dlopening of preloaded static modules.

The prefix "dl" is reserved for loaders supplied with future versions of libltdl, so you should not use that for your own loader names.

The following types are defined in `ltdl.h':

Type: lt_module
lt_module is a dlloader dependent module. The dynamic module loader extensions communicate using these low level types.

Type: lt_dlloader
lt_dlloader is a handle for module loader types.

Type: lt_dlloader_data
lt_dlloader_data is used for specifying loader instance data.

Type: struct lt_user_dlloader {const char *sym_prefix; lt_module_open *module_open;lt_module_close *module_close; lt_find_sym *find_sym; lt_dlloader_exit *dlloader_exit; lt_dlloader_data dlloader_data; }
If you want to define a new way to open dynamic modules, and have the lt_dlopen API use it, you need to instantiate one of these structures and pass it to lt_dlloader_add. You can pass whatever you like in the dlloader_data field, and it will be passed back as the value of the first parameter to each of the functions specified in the function pointer fields.

Type: lt_module lt_module_open (lt_user_data loader_data, const char *filename)
The type of the loader function for an lt_dlloader module loader. The value set in the dlloader_data field of the struct lt_user_dlloader structure will be passed into this function in the loader_data parameter. Implementation of such a function should attempt to load the named module, and return an lt_module suitable for passing in to the associated lt_module_close and lt_sym_find function pointers. If the function fails it should return NULL, and set the error message with lt_dlseterror.

Type: int lt_module_close (lt_dlloader_data loader_data, lt_module module)
The type of the unloader function for a user defined module loader. Implementatation of such a function should attempt to release any resources tied up by the module module, and then unload it from memory. If the function fails for some reason, set the error message with lt_dlseterror and return non-zero.

Type: lt_ptr lt_find_sym (lt_user_data loader_data, lt_module module, const char *symbol)
The type of the symbol lookup function for a user defined module loader. Implementation of such a function should return the address of the named symbol in the module module, or else set the error message with lt_dlseterror and return NULL if lookup fails.

Type: int lt_dlloader_exit (lt_user_data loader_data)
The type of the finalisation function for a user defined module loader. Implementation of such a function should free any resources associated with the loader, including any user specified data in the dlloader_data field of the lt_user_dlloader. If non-NULL, the function will be called by lt_dlexit, and lt_dlloader_remove.

For example:

int
register_myloader (void)
{
  lt_user_dlloader dlloader;

  /* User modules are responsible for their own initialisation. */
  if (myloader_init () != 0)
    return MYLOADER_INIT_ERROR;

  dlloader.sym_prefix    = NULL;
  dlloader.module_open   = myloader_open;
  dlloader.module_close  = myloader_close;
  dlloader.find_sym      = myloader_find_sym.
  dlloader.dlloader_exit = myloader_exit;
  dlloader.dlloader_data = (lt_user_data)myloader_function;

  /* Add my loader as the default module loader. */
  if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, "myloader") != 0)
    return ERROR;

  return OK;
}

Note that if there is any initialisation required for the loader, it must be performed manually before the loader is registered -- libltdl doesn't handle user loader initialisation.

Finalisation is handled by libltdl however, and it is important to ensure the dlloader_exit callback releases any resources claimed during the initialisation phase.

libltdl provides the following functions for writing your own module loaders:

Function: int lt_dlloader_add (lt_dlloader *place, lt_user_dlloader *dlloader, const char *loader_name)
Add a new module loader to the list of all loaders, either as the last loader (if place is NULL), else immediately before the loader passed as place. loader_name will be returned by lt_dlloader_name if it is subsequently passed a newly registered loader. These loader_names must be unique, or lt_dlloader_remove and lt_dlloader_find cannot work. Returns 0 for success.

{
  /* Make myloader be the last one. */
  if (lt_dlloader_add (NULL, myloader) != 0)
    perror (lt_dlerror ());
}

Function: int lt_dlloader_remove (const char *loader_name)
Remove the loader identified by the unique name, loader_name. Before this can succeed, all modules opened by the named loader must have been closed. Returns 0 for success, otherwise an error message can be obtained from lt_dlerror.

{
  /* Remove myloader. */
  if (lt_dlloader_remove ("myloader") != 0)
    perror (lt_dlerror ());
}

Function: {lt_dlloader *}lt_dlloader_next (lt_dlloader *place)
Iterate over the module loaders, returning the first loader if place is NULL, and the next one on subsequent calls. The handle is for use with lt_dlloader_add.

{
  /* Make myloader be the first one. */
  if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0)
    return ERROR;
}

Function: {lt_dlloader *}lt_dlloader_find (const char *loader_name)
Return the first loader with a matching loader_name identifier, or else NULL, if the identifier is not found.

The identifiers which may be used by libltdl itself, if the host architecture supports them are dlopen (9), dld and dlpreload.

{
  /* Add a user loader as the next module loader to be tried if
     the standard dlopen loader were to fail when lt_dlopening. */
  if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0)
    return ERROR;
}

Function: {const char *}lt_dlloader_name (lt_dlloader *place)
Return the identifying name of PLACE, as obtained from lt_dlloader_next or lt_dlloader_find. If this function fails, it will return NULL and set an error for retrieval with lt_dlerror.

Function: {lt_user_data *}lt_dlloader_data (lt_dlloader *place)
Return the address of the dlloader_data of PLACE, as obtained from lt_dlloader_next or lt_dlloader_find. If this function fails, it will return NULL and set an error for retrieval with lt_dlerror.

Error handling within user module loaders

Function: int lt_dladderror (const char *diagnostic)
This function allows you to integrate your own error messages into lt_dlerror. Pass in a suitable diagnostic message for return by lt_dlerror, and an error identifier for use with lt_dlseterror is returned.

If the allocation of an identifier fails, this function returns -1.

int myerror = lt_dladderror ("Doh!");
if (myerror < 0)
  perror (lt_dlerror ());

Function: int lt_dlseterror (int errorcode)
When writing your own module loaders, you should use this function to raise errors so that they are propogated through the lt_dlerror interface. All of the standard errors used by libltdl are declared in `ltdl.h', or you can add more of your own with lt_dladderror. This function returns 0 on success.

if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0)
  perror (lt_dlerror ());

How to distribute libltdl with your package

Even though libltdl is installed together with libtool, you may wish to include libltdl in the distribution of your package, for the convenience of users of your package that don't have libtool or libltdl installed. In this case, you must decide whether to manually add the ltdl objects to your package, or else which flavor of libltdl you want to use: a convenience library or an installable libtool library.

The most simplistic way to add libltdl to your package is to copy the source files, `ltdl.c' and `ltdl.h', to a source directory withing your package and to build and link them along with the rest of your sources. To help you do this, the m4 macros for autoconf are available in `ltdl.m4'. You must ensure that they are available in `aclocal.m4' before you run autoconf -- by appending the contents of `ltdl.m4' to `acinclude.m4', if you are using automake, or to `aclocal.m4' if you are not. Having made the macros available, you must add a call to the `AC_LIB_LTDL' macro to your package's `configure.in' to perform the configure time checks required to build `ltdl.o' correctly. This method has problems if you then try to link the package binaries with an installed libltdl, or a library which depends on libltdl: you may have problems with duplicate symbol definitions.

One advantage of the convenience library is that it is not installed, so the fact that you use libltdl will not be apparent to the user, and it will not overwrite a pre-installed version of libltdl a user might have. On the other hand, if you want to upgrade libltdl for any reason (e.g. a bugfix) you'll have to recompile your package instead of just replacing an installed version of libltdl. However, if your programs or libraries are linked with other libraries that use such a pre-installed version of libltdl, you may get linker errors or run-time crashes. Another problem is that you cannot link the convenience library into more than one libtool library, then link a single program with these libraries, because you may get duplicate symbols. In general you can safely use the convenience library in programs which don't depend on other libraries that might use libltdl too. In order to enable this flavor of libltdl, you should add the line `AC_LIBLTDL_CONVENIENCE' to your `configure.in', before `AC_PROG_LIBTOOL'.

In order to select the installable version of libltdl, you should add a call of the macro `AC_LIBLTDL_INSTALLABLE' to your `configure.in' before `AC_PROG_LIBTOOL'. This macro will check whether libltdl is already installed and, if not, request the libltdl embedded in your package to be built and installed. Note, however, that no version checking is performed. The user may override the test and determine that the libltdl embedded must be installed, regardless of the existence of another version, using the configure switch `--enable-ltdl-install'.

In order to embed libltdl into your package, just add `--ltdl' to the libtoolize command line. It will copy the libltdl sources to a subdirectory `libltdl' in your package. Both macros accept an optional argument to specify the location of the `libltdl' directory. By the default both macros assume that it is `${top_srcdir}/libltdl'.

Whatever macro you use, it is up to you to ensure that your `configure.in' will configure libltdl, using `AC_CONFIG_SUBDIRS', and that your `Makefile's will start sub-makes within libltdl's directory, using automake's SUBDIRS, for example. Both macros define the shell variables LIBLTDL, to the link flag that you should use to link with libltdl, and INCLTDL, to the preprocessor flag that you should use to compile with programs that include `ltdl.h'. It is up to you to use `AC_SUBST' to ensure that this variable will be available in `Makefile's, or add them to variables that are `AC_SUBST'ed by default, such as LIBS and CPPFLAGS.

If you're using the convenience libltdl, LIBLTDL will be the pathname for the convenience version of libltdl and INCLTDL will be `-I' followed by the directory that contains libltdl, both starting with `${top_builddir}/' or `${top_srcdir}/', respectively.

If you request an installed version of libltdl and one is found(10), LIBLTDL will be set to `-lltdl' and INCLTDL will be empty (which is just a blind assumption that `ltdl.h' is somewhere in the include path if libltdl is in the library path). If an installable version of libltdl must be built, its pathname, starting with `${top_builddir}/', will be stored in LIBLTDL, and INCLTDL will be set just like in the case of convenience library.

So, when you want to link a program with libltdl, be it a convenience, installed or installable library, just compile with `$(INCLTDL)' and link it with `$(LIBLTDL)', using libtool.

You should probably also add `AC_LIBTOOL_DLOPEN' to your `configure.in' before `AC_PROG_LIBTOOL', otherwise libtool will assume no dlopening mechanism is supported, and revert to dlpreopening, which is probably not what you want.

Avoid using the -static or -all-static switches when linking programs with libltdl. This will not work on all platforms, because the dlopening functions may not be available for static linking.

The following example shows you how to embed the convenience libltdl in your package. In order to use the installable variant just replace `AC_LIBLTDL_CONVENIENCE' with `AC_LIBLTDL_INSTALLABLE'. We assume that libltdl was embedded using `libtoolize --ltdl'.

configure.in:

...
dnl Enable building of the convenience library
dnl and set LIBLTDL accordingly
AC_LIBLTDL_CONVENIENCE
dnl Substitute INCLTDL and LIBLTDL in the Makefiles
AC_SUBST(INCLTDL)
AC_SUBST(LIBLTDL)
dnl Check for dlopen support
AC_LIBTOOL_DLOPEN
dnl Configure libtool
AC_PROG_LIBTOOL
dnl Configure libltdl
AC_CONFIG_SUBDIRS(libltdl)
...

Makefile.am:

...
SUBDIRS = libltdl

INCLUDES = $(INCLTDL)

myprog_LDFLAGS = -export-dynamic
# The quotes around -dlopen below fool automake <= 1.4 into accepting it
myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" foo1.la
myprog_DEPENDENCIES = $(LIBLTDL) foo1.la
...

Using libtool with other languages

Libtool was first implemented in order to add support for writing shared libraries in the C language. However, over time, libtool is being integrated with other languages, so that programmers are free to reap the benefits of shared libraries in their favorite programming language.

This chapter describes how libtool interacts with other languages, and what special considerations you need to make if you do not use C.

Writing libraries for C++

Creating libraries of C++ code should be a fairly straightforward process, because its object files differ from C ones in only three ways:

  1. Because of name mangling, C++ libraries are only usable by the C++ compiler that created them. This decision was made by the designers of C++ in order to protect users from conflicting implementations of features such as constructors, exception handling, and RTTI.
  2. On some systems, the C++ compiler must take special actions for the dynamic linker to run dynamic (i.e., run-time) initializers. This means that we should not call `ld' directly to link such libraries, and we should use the C++ compiler instead.
  3. C++ compilers will link some Standard C++ library in by default, but libtool does not know which are these libraries, so it cannot even run the inter-library dependence analyzer to check how to link it in. Therefore, running `ld' to link a C++ program or library is deemed to fail. However, running the C++ compiler directly may lead to problems related with inter-library dependencies.

The conclusion is that libtool is not ready for general use for C++ libraries. You should avoid any global or static variable initializations that would cause an "initializer element is not constant" error if you compiled them with a standard C compiler.

There are other ways of working around this problem, but they are beyond the scope of this manual.

Furthermore, you'd better find out, at configure time, what are the C++ Standard libraries that the C++ compiler will link in by default, and explicitly list them in the link command line. Hopefully, in the future, libtool will be able to do this job by itself.

Troubleshooting

Libtool is under constant development, changing to remain up-to-date with modern operating systems. If libtool doesn't work the way you think it should on your platform, you should read this chapter to help determine what the problem is, and how to resolve it.

The libtool test suite

Libtool comes with its own set of programs that test its capabilities, and report obvious bugs in the libtool program. These tests, too, are constantly evolving, based on past problems with libtool, and known deficiencies in other operating systems.

As described in the `INSTALL' file, you may run make check after you have built libtool (possibly before you install it) in order to make sure that it meets basic functional requirements.

Description of test suite

Here is a list of the current programs in the test suite, and what they test for:

`cdemo-conf.test'
`cdemo-exec.test'
`cdemo-make.test'
`cdemo-static.test'
`cdemo-shared.test'
These programs check to see that the `cdemo' subdirectory of the libtool distribution can be configured and built correctly. The `cdemo' subdirectory contains a demonstration of libtool convenience libraries, a mechanism that allows build-time static libraries to be created, in a way that their components can be later linked into programs or other libraries, even shared ones. The tests `cdemo-make.test' and `cdemo-exec.test' are executed three times, under three different libtool configurations: `cdemo-conf.test' configures `cdemo/libtool' to build both static and shared libraries (the default for platforms that support both), `cdemo-static.test' builds only static libraries (`--disable-shared'), and `cdemo-shared.test' builds only shared libraries (`--disable-static').
`demo-conf.test'
`demo-exec.test'
`demo-inst.test'
`demo-make.test'
`demo-unst.test'
`demo-static.test'
`demo-shared.test'
`demo-nofast.test'
`demo-pic.test'
`demo-nopic.test'
These programs check to see that the `demo' subdirectory of the libtool distribution can be configured, built, installed, and uninstalled correctly. The `demo' subdirectory contains a demonstration of a trivial package that uses libtool. The tests `demo-make.test', `demo-exec.test', `demo-inst.test' and `demo-unst.test' are executed four times, under four different libtool configurations: `demo-conf.test' configures `demo/libtool' to build both static and shared libraries, `demo-static.test' builds only static libraries (`--disable-shared'), and `demo-shared.test' builds only shared libraries (`--disable-static'). `demo-nofast.test' configures `demo/libtool' to disable the fast-install mode (`--enable-fast-install=no'). `demo-pic.test' configures `demo/libtool' to prefer building PIC code (`--with-pic'), `demo-nopic.test' to prefer non-PIC code (`--without-pic').
`deplibs.test'
Many systems cannot link static libraries into shared libraries. libtool uses a deplibs_check_method to prevent such cases. This tests checks whether libtool's deplibs_check_method works properly.
`hardcode.test'
On all systems with shared libraries, the location of the library can be encoded in executables that are linked against it see section Linking executables. This test checks the conditions under which your system linker hardcodes the library location, and guarantees that they correspond to libtool's own notion of how your linker behaves.
`build-relink.test'
Checks whether variable shlibpath_overrides_runpath is properly set. If the test fails and VERBOSE is set, it will indicate what the variable should have been set to.
`noinst-link.test'
Checks whether libtool will not try to link with a previously installed version of a library when it should be linking with a just-built one.
`depdemo-conf.test'
`depdemo-exec.test'
`depdemo-inst.test'
`depdemo-make.test'
`depdemo-unst.test'
`depdemo-static.test'
`depdemo-shared.test'
`depdemo-nofast.test'
These programs check to see that the `depdemo' subdirectory of the libtool distribution can be configured, built, installed, and uninstalled correctly. The `depdemo' subdirectory contains a demonstration of inter-library dependencies with libtool. The test programs link some interdependent libraries. The tests `depdemo-make.test', `depdemo-exec.test', `depdemo-inst.test' and `depdemo-unst.test' are executed four times, under four different libtool configurations: `depdemo-conf.test' configures `depdemo/libtool' to build both static and shared libraries, `depdemo-static.test' builds only static libraries (`--disable-shared'), and `depdemo-shared.test' builds only shared libraries (`--disable-static'). `depdemo-nofast.test' configures `depdemo/libtool' to disable the fast-install mode (`--enable-fast-install=no'.
`mdemo-conf.test'
`mdemo-exec.test'
`mdemo-inst.test'
`mdemo-make.test'
`mdemo-unst.test'
`mdemo-static.test'
`mdemo-shared.test'
These programs check to see that the `mdemo' subdirectory of the libtool distribution can be configured, built, installed, and uninstalled correctly. The `mdemo' subdirectory contains a demonstration of a package that uses libtool and the system independent dlopen wrapper `libltdl' to load modules. The library `libltdl' provides a dlopen wrapper for various platforms (Linux, Solaris, HP/UX etc.) including support for dlpreopened modules (see section Dlpreopening). The tests `mdemo-make.test', `mdemo-exec.test', `mdemo-inst.test' and `mdemo-unst.test' are executed three times, under three different libtool configurations: `mdemo-conf.test' configures `mdemo/libtool' to build both static and shared libraries, `mdemo-static.test' builds only static libraries (`--disable-shared'), and `mdemo-shared.test' builds only shared libraries (`--disable-static').
`dryrun.test'
This test checks whether libtool's --dry-run mode works properly.
`assign.test'
Checks whether we don't put break or continue on the same line as an assignment in the libtool script.
`link.test'
This test guarantees that linking directly against a non-libtool static library works properly.
`link-2.test'
This test makes sure that files ending in `.lo' are never linked directly into a program file.
`nomode.test'
Check whether we can actually get help for libtool.
`quote.test'
This program checks libtool's metacharacter quoting.
`sh.test'
Checks whether a `test' command was forgotten in libtool.
`suffix.test'
When other programming languages are used with libtool (see section Using libtool with other languages), the source files may end in suffixes other than `.c'. This test validates that libtool can handle suffixes for all the file types that it supports, and that it fails when the suffix is invalid.

When tests fail

Each of the above tests are designed to produce no output when they are run via make check. The exit status of each program tells the `Makefile' whether or not the test succeeded.

If a test fails, it means that there is either a programming error in libtool, or in the test program itself.

To investigate a particular test, you may run it directly, as you would a normal program. When the test is invoked in this way, it produces output which may be useful in determining what the problem is.

Another way to have the test programs produce output is to set the VERBOSE environment variable to `yes' before running them. For example, env VERBOSE=yes make check runs all the tests, and has each of them display debugging information.

Reporting bugs

If you think you have discovered a bug in libtool, you should think twice: the libtool maintainer is notorious for passing the buck (or maybe that should be "passing the bug"). Libtool was invented to fix known deficiencies in shared library implementations, so, in a way, most of the bugs in libtool are actually bugs in other operating systems. However, the libtool maintainer would definitely be happy to add support for somebody else's buggy operating system. [I wish there was a good way to do winking smiley-faces in Texinfo.]

Genuine bugs in libtool include problems with shell script portability, documentation errors, and failures in the test suite (see section The libtool test suite).

First, check the documentation and help screens to make sure that the behaviour you think is a problem is not already mentioned as a feature.

Then, you should read the Emacs guide to reporting bugs (see section `Reporting Bugs' in The Emacs Manual). Some of the details listed there are specific to Emacs, but the principle behind them is a general one.

Finally, send a bug report to the libtool bug reporting address bug-libtool@gnu.org with any appropriate facts, such as test suite output (see section When tests fail), all the details needed to reproduce the bug, and a brief description of why you think the behaviour is a bug. Be sure to include the word "libtool" in the subject line, as well as the version number you are using (which can be found by typing libtool --version).

Maintenance notes for libtool

This chapter contains information that the libtool maintainer finds important. It will be of no use to you unless you are considering porting libtool to new systems, or writing your own libtool.

Porting libtool to new systems

Before you embark on porting libtool to an unsupported system, it is worthwhile to send e-mail to the libtool mailing list libtool@gnu.org, to make sure that you are not duplicating existing work.

If you find that any porting documentation is missing, please complain! Complaints with patches and improvements to the documentation, or to libtool itself, are more than welcome.

Information sources

Once it is clear that a new port is necessary, you'll generally need the following information:

canonical system name
You need the output of config.guess for this system, so that you can make changes to the libtool configuration process without affecting other systems.
man pages for ld and cc
These generally describe what flags are used to generate PIC, to create shared libraries, and to link against only static libraries. You may need to follow some cross references to find the information that is required.
man pages for ld.so, rtld, or equivalent
These are a valuable resource for understanding how shared libraries are loaded on the system.
man page for ldconfig, or equivalent
This page usually describes how to install shared libraries.
output from ls -l /lib /usr/lib
This shows the naming convention for shared libraries on the system, including which names should be symbolic links.
any additional documentation
Some systems have special documentation on how to build and install shared libraries.

If you know how to program the Bourne shell, then you can complete the port yourself; otherwise, you'll have to find somebody with the relevant skills who will do the work. People on the libtool mailing list are usually willing to volunteer to help you with new ports, so you can send the information to them.

To do the port yourself, you'll definitely need to modify the libtool.m4 macros in order to make platform-specific changes to the configuration process. You should search that file for the PORTME keyword, which will give you some hints on what you'll need to change. In general, all that is involved is modifying the appropriate configuration variables (see section libtool script contents).

Your best bet is to find an already-supported system that is similar to yours, and make your changes based on that. In some cases, however, your system will differ significantly from every other supported system, and it may be necessary to add new configuration variables, and modify the ltmain.in script accordingly. Be sure to write to the mailing list before you make changes to ltmain.in, since they may have advice on the most effective way of accomplishing what you want.

Porting inter-library dependencies support

Since version 1.2c, libtool has re-introduced the ability to do inter-library dependency on some platforms, thanks to a patch by Toshio Kuratomi badger@prtr-13.ucsc.edu. Here's a shortened version of the message that contained his patch:

The basic architecture is this: in `libtool.m4', the person who writes libtool makes sure `$deplibs' is included in `$archive_cmds' somewhere and also sets the variable `$deplibs_check_method', and maybe `$file_magic_cmd' when `deplibs_check_method' is file_magic.

`deplibs_check_method' can be one of five things:

`file_magic [regex]'
looks in the library link path for libraries that have the right libname. Then it runs `$file_magic_cmd' on the library and checks for a match against regex using egrep. When file_magic_test_file is set by `libtool.m4', it is used as an argument to `$file_magic_cmd' in order to verify whether the regular expression matches its output, and warn the user otherwise.
`test_compile'
just checks whether it is possible to link a program out of a list of libraries, and checks which of those are listed in the output of ldd. It is currently unused, and will probably be dropped in the future.
`pass_all'
will pass everything without any checking. This may work on platforms in which code is position-independent by default and inter-library dependencies are properly supported by the dynamic linker, for example, on DEC OSF/1 3 and 4.
`none'
It causes deplibs to be reassigned deplibs="". That way `archive_cmds' can contain deplibs on all platforms, but not have deplibs used unless needed.
`unknown'
is the default for all systems unless overridden in `libtool.m4'. It is the same as `none', but it documents that we really don't know what the correct value should be, and we welcome patches that improve it.

Then in `ltmain.in' we have the real workhorse: a little initialization and postprocessing (to setup/release variables for use with eval echo libname_spec etc.) and a case statement that decides which method is being used. This is the real code... I wish I could condense it a little more, but I don't think I can without function calls. I've mostly optimized it (moved things out of loops, etc) but there is probably some fat left. I thought I should stop while I was ahead, work on whatever bugs you discover, etc before thinking about more than obvious optimizations.

Tested platforms

This table describes when libtool was last known to be tested on platforms where it claims to support shared libraries:

Note: The vendor-distributed HP-UX sed(1) programs are horribly
broken, and cannot handle libtool's requirements, so users may report
unusual problems.  There is no workaround except to install a working
sed (such as GNU sed) on these systems.

Note: The vendor-distributed NCR MP-RAS cc programs emits
copyright on standard error that confuse tests on size of
`conftest.err'.  The workaround is to specify CC
when run configure with CC='cc -Hnocopyr'.

Platform quirks

This section is dedicated to the sanity of the libtool maintainers.  It
describes the programs that libtool uses, how they vary from system to
system, and how to test for them.

Because libtool is a shell script, it can be difficult to understand
just by reading it from top to bottom.  This section helps show why
libtool does things a certain way.  Combined with the scripts
themselves, you should have a better sense of how to improve libtool, or
write your own.

References

The following is a list of valuable documentation references:

  •

SGI's IRIX Manual Pages, which can be found at
http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man.

  •

Sun's free service area
(http://www.sun.com/service/online/free.html) and documentation
server (http://docs.sun.com/).

  •

Compaq's Tru64 UNIX online documentation is at
(http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html)
with C++ documentation at
(http://tru64unix.compaq.com/cplus/docs/index.htm).

  •

Hewlett-Packard has online documentation at
(http://docs.hp.com/index.html).

  •

IBM has online documentation at
(http://www.rs6000.ibm.com/resource/aix_resource/Pubs/).

Compilers

The only compiler characteristics that affect libtool are the flags
needed (if any) to generate PIC objects.  In general, if a C compiler
supports certain PIC flags, then any derivative compilers support the
same flags.  Until there are some noteworthy exceptions to this rule,
this section will document only C compilers.

The following C compilers have standard command line options, regardless
of the platform:

gcc

This is the GNU C compiler, which is also the system compiler for many
free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, NetBSD, and
OpenBSD, to name a few).

The `-fpic' or `-fPIC' flags can be used to generate
position-independent code.  `-fPIC' is guaranteed to generate
working code, but the code is slower on m68k, m88k, and Sparc chips.
However, using `-fpic' on those chips imposes arbitrary size limits
on the shared libraries.

The rest of this subsection lists compilers by the operating system that
they are bundled with:

aix3*

aix4*

AIX compilers have no PIC flags, since AIX has been ported only to
PowerPC and RS/6000 chips. (11)

hpux10*

Use `+Z' to generate PIC.

osf3*

Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC
platform.

solaris2*

Use `-KPIC' to generate PIC.

sunos4*

Use `-PIC' to generate PIC.

Reloadable objects

On all known systems, a reloadable object can be created by running
ld -r -o output.o input1.o input2.o.  This
reloadable object may be treated as exactly equivalent to other
objects.

Multiple dependencies

On most modern platforms the order that dependent libraries are listed
has no effect on object generation.  In theory, there are platforms
which require libraries which provide missing symbols to other libraries
to listed after those libraries whose symbols they provide.

Particularly, if a pair of static archives each resolve some of the
other's symbols, it might be necessary to list one of those archives
both before and after the other one.  Libtool does not currently cope
with this situation well, since dupicate libraries are removed from
thr link line.

If you find yourself developing on a host that requires you to list
libraries multiple times in order for it to generate correctly linked
objects, you can defeat libtool's removal algorithm like this:

$ libtool ... -lfoo -lbar -Wl,-lfoo

Archivers

On all known systems, building a static library can be accomplished by
running ar cru libname.a obj1.o obj2.o ...,
where the `.a' file is the output library, and each `.o' file is an
object file.

On all known systems, if there is a program named ranlib, then it
must be used to "bless" the created library before linking against it,
with the ranlib libname.a command.  Some systems, like Irix,
use the ar ts command, instead.

libtool script contents

Since version 1.4, the libtool script is generated by
configure (see section Configuring libtool).  In earlier versions,
configure achieved this by calling a helper script called
`ltconfig'.  From libtool version 0.7 to 1.0, this script
simply set shell variables, then sourced the libtool backend,
ltmain.sh.  ltconfig from libtool version 1.1 through 1.3
inlined the contents of ltmain.sh into the generated
libtool, which improved performance on many systems.  The tests
that `ltconfig' used to perform are now kept in `libtool.m4'
where thay can be written using Autoconf.  This has the runtime
performance benefits of inlined ltmain.sh, and improves
the build time a little while considerably easing the amount of raw
shell code that used to need maintaining.

The convention used for naming variables which hold shell commands for
delayed evaluation, is to use the suffix _cmd where a single
line of valid shell script is needed, and the suffix _cmds where
multiple lines of shell script may be delayed for later
evaluation.  By convention, _cmds variables delimit the
evaluation units with the ~ character where necessary.

Here is a listing of each of the configuration variables, and how they
are used within ltmain.sh (see section Configuring libtool):

Variable: AR

The name of the system library archiver.

Variable: CC

The name of the C compiler used to configure libtool.

Variable: LD

The name of the linker that libtool should use internally for reloadable
linking and possibly shared libraries.

Variable: NM

The name of a BSD-compatible nm program, which produces listings
of global symbols in one the following formats:

address C global-variable-name
address D global-variable-name
address T global-function-name

Variable: RANLIB

Set to the name of the ranlib program, if any.

Variable: allow_undefined_flag

The flag that is used by `archive_cmds' in order to declare that
there will be unresolved symbols in the resulting shared library.
Empty, if no such flag is required.  Set to `unsupported' if there
is no way to generate a shared library with references to symbols that
aren't defined in that library.

Variable: always_export_symbols

Whether libtool should automatically generate a list of exported symbols
using export_symbols_cmds before linking an archive.
Set to `yes' or `no'.  Default is `no'.

Variable: archive_cmds

Variable: archive_expsym_cmds

Variable: old_archive_cmds

Commands used to create shared libraries, shared libraries with
`-export-symbols' and static libraries, respectively.

Variable: old_archive_from_new_cmds

If the shared library depends on a static library,
`old_archive_from_new_cmds' contains the commands used to create that
static library.  If this variable is not empty, `old_archive_cmds' is
not used.

Variable: old_archive_from_expsyms_cmds

If a static library must be created from the export symbol list in order to
correctly link with a shared library, `old_archive_from_expsyms_cmds'
contains the commands needed to create that static library.  When these
commands are executed, the variable soname contains the name of the
shared library in question, and the $objdir/$newlib contains the
path of the static library these commands should build.  After executing
these commands, libtool will proceed to link against $objdir/$newlib
instead of soname.

Variable: build_libtool_libs

Whether libtool should build shared libraries on this system.  Set to
`yes' or `no'.

Variable: build_old_libs

Whether libtool should build static libraries on this system.  Set to
`yes' or `no'.

Variable: compiler_c_o

Whether the compiler supports the -c and -o options
simultaneously. Set to `yes' or `no'.

Variable: compiler_o_lo

Whether the compiler supports compiling directly to a ".lo" file,
i.e whether object files do not have to have the suffix ".o".
Set to `yes' or `no'.

Variable: dlopen_support

Whether dlopen is supported on the platform.
Set to `yes' or `no'.

Variable: dlopen_self

Whether it is possible to dlopen the executable itself.
Set to `yes' or `no'.

Variable: dlopen_self_static

Whether it is possible to dlopen the executable itself, when it
is linked statically (`-all-static').  Set to `yes' or
`no'.

Variable: echo

An echo program which does not interpret backslashes as an
escape character.

Variable: exclude_expsyms

List of symbols that should not be listed in the preloaded symbols.

Variable: export_dynamic_flag_spec

Compiler link flag that allows a dlopened shared library to reference
symbols that are defined in the program.

Variable: export_symbols_cmds

Commands to extract exported symbols from libobjs to the
file export_symbols.

Variable: extract_expsyms_cmds

Commands to extract the exported symbols list from a shared library.
These commands are executed if there is no file $objdir/$soname-def,
and should write the names of the exported symbols to that file, for
the use of `old_archive_from_expsyms_cmds'.

Variable: fast_install

Determines whether libtool will privilege the installer or the
developer.  The assumption is that installers will seldom run programs
in the build tree, and the developer will seldom install.  This is only
meaningful on platforms in which shlibpath_overrides_runpath is
not `yes', so fast_install will be set to `needless' in
this case.  If fast_install set to `yes', libtool will create
programs that search for installed libraries, and, if a program is run
in the build tree, a new copy will be linked on-demand to use the
yet-to-be-installed libraries.  If set to `no', libtool will create
programs that use the yet-to-be-installed libraries, and will link
a new copy of the program at install time.  The default value is
`yes' or `needless', depending on platform and configuration
flags, and it can be turned from `yes' to `no' with the
configure flag `--disable-fast-install'.

Variable: finish_cmds

Commands to tell the dynamic linker how to find shared libraries in a
specific directory.

Variable: finish_eval

Same as finish_cmds, except the commands are not displayed.

Variable: fix_srcfile_path

Expression to fix the shell variable $srcfile for the compiler.

Variable: global_symbol_pipe

A pipeline that takes the output of NM, and produces a listing of
raw symbols followed by their C names.  For example:

$ eval "$NM progname | $global_symbol_pipe"
D symbol1 C-symbol1
T symbol2 C-symbol2
C symbol3 C-symbol3
...
$

The first column contains the symbol type (used to tell data from code
on some platforms), but its meaning is system dependent.

Variable: global_symbol_to_cdecl

A pipeline that translates the output of global_symbol_pipe into
proper C declarations.  On platforms whose linkers differentiate code
from data, such as HP/UX, data symbols will be declared as such, and
code symbols will be declared as functions.  On platforms that don't
care, everything is assumed to be data.

Variable: hardcode_action

Either `immediate' or `relink', depending on whether shared
library paths can be hardcoded into executables before they are installed,
or if they need to be relinked.

Variable: hardcode_direct

Set to `yes' or `no', depending on whether the linker
hardcodes directories if a library is directly specified on the command
line (such as `dir/libname.a') when
hardcode_libdir_flag_spec is specified.

Variable: hardcode_into_libs

Whether the platform supports hardcoding of run-paths into libraries.
If enabled, linking of programs will be much simpler but libraries will
need to be relinked during installation.   Set to `yes' or `no'.

Variable: hardcode_libdir_flag_spec

Flag to hardcode a libdir variable into a binary, so that the
dynamic linker searches libdir for shared libraries at runtime.
If it is empty, libtool will try to use some other hardcoding mechanism.

Variable: hardcode_libdir_separator

If the compiler only accepts a single hardcode_libdir_flag, then
this variable contains the string that should separate multiple
arguments to that flag.

Variable: hardcode_minus_L

Set to `yes' or `no', depending on whether the linker
hardcodes directories specified by `-L' flags into the resulting
executable when hardcode_libdir_flag_spec is specified.

Variable: hardcode_shlibpath_var

Set to `yes' or `no', depending on whether the linker
hardcodes directories by writing the contents of `$shlibpath_var'
into the resulting executable when hardcode_libdir_flag_spec is
specified.  Set to `unsupported' if directories specified by
`$shlibpath_var' are searched at run time, but not at link time.

Variable: host

Variable: host_alias

For information purposes, set to the specified and canonical names of
the system that libtool was configured for.

Variable: include_expsyms

List of symbols that must always be exported when using export_symbols.

Variable: libext

The standard old archive suffix (normally "a").

Variable: libname_spec

The format of a library name prefix.  On all Unix systems, static
libraries are called `libname.a', but on some systems (such
as OS/2 or MS-DOS), the library is just called `name.a'.

Variable: library_names_spec

A list of shared library names.  The first is the name of the file,
the rest are symbolic links to the file.  The name in the list is
the file name that the linker finds when given `-lname'.

Variable: link_all_deplibs

Whether libtool must link a program against all its dependency libraries.
Set to `yes' or `no'.  Default is `unknown', which is
a synonym for `yes'.

Variable: link_static_flag

Linker flag (passed through the C compiler) used to prevent dynamic
linking.

Variable: need_lib_prefix

Whether libtool should automatically prefix module names with 'lib'.
Set to `yes' or `no'.  By default, it is `unknown', which
means the same as `yes', but documents that we are not really sure
about it.
`yes' means that it is possible both to dlopen and to
link against a library without 'lib' prefix,
i.e. it requires hardcode_direct to be `yes'.

Variable: need_version

Whether versioning is required for libraries, i.e. whether the
dynamic linker requires a version suffix for all libraries.
Set to `yes' or `no'.  By default, it is `unknown', which
means the same as `yes', but documents that we are not really sure
about it.

Variable: need_locks

Whether files must be locked to prevent conflicts when compiling
simultaneously. Set to `yes' or `no'.

Variable: no_builtin_flag

Compiler flag to disable builtin functions that conflict with declaring
external global symbols as char.

Variable: no_undefined_flag

The flag that is used by `archive_cmds' in order to declare that
there will be no unresolved symbols in the resulting shared library.
Empty, if no such flag is required.

Variable: objdir

The name of the directory that contains temporary libtool files.

Variable: objext

The standard object file suffix (normally "o").

Variable: pic_flag

Any additional compiler flags for building library object files.

Variable: postinstall_cmds

Variable: old_postinstall_cmds

Commands run after installing a shared or static library, respectively.

Variable: postuninstall_cmds

Variable: old_postuninstall_cmds

Commands run after uninstalling a shared or static library, respectively.

Variable: reload_cmds

Variable: reload_flag

Commands to create a reloadable object.

Variable: runpath_var

The environment variable that tells the linker which directories to
hardcode in the resulting executable.

Variable: shlibpath_overrides_runpath

Indicates whether it is possible to override the hard-coded library
search path of a program with an environment variable.  If this is set
to no, libtool may have to create two copies of a program in the build
tree, one to be installed and one to be run in the build tree only.
When each of these copies is created depends on the value of
fast_install.  The default value is `unknown', which is
equivalent to `no'.

Variable: shlibpath_var

The environment variable that tells the dynamic linker where to find
shared libraries.

Variable: soname_spec

The name coded into shared libraries, if different from the real name of
the file.

Variable: striplib

Variable: old_striplib

Command to strip a shared (striplib) or static (old_striplib)
library, respectively.  If these variables are empty, the strip flag
in the install mode will be ignored for libraries (see section Install mode).

Variable: sys_lib_dlsearch_path_spec

Expression to get the run-time system library search path.  Directories
that appear in this list are never hard-coded into executables.

Variable: sys_lib_search_path_spec

Expression to get the compile-time system library search path.  This
variable is used by libtool when it has to test whether a certain
library is shared or static.  The directories listed in
shlibpath_var are automatically appended to this list, every time
libtool runs (i.e., not at configuration time), because some linkers use
this variable to extend the library search path.  Linker switches such
as -L also augment the search path.

Variable: thread_safe_flag_spec

Linker flag (passed through the C compiler) used to generate thread-safe
libraries.

Variable: version_type

The library version numbering type.  One of `libtool',
`freebsd-aout', `freebsd-elf', `irix', `linux',
`osf', `sunos', `windows', or `none'.

Variable: whole_archive_flag_spec

Compiler flag to generate shared objects from convenience archives.

Variable: wl

The C compiler flag that allows libtool to pass a flag directly to the
linker.  Used as: ${wl}some-flag.

Variables ending in `_cmds' or `_eval' contain a
`~'-separated list of commands that are evaled one after
another.  If any of the commands return a nonzero exit status, libtool
generally exits with an error message.

Variables ending in `_spec' are evaled before being used by
libtool.

Cheap tricks

Here are a few tricks that you can use in order to make maintainership
easier:

  •

When people report bugs, ask them to use the `--config',
`--debug', or `--features' flags, if you think they will help
you.  These flags are there to help you get information directly, rather
than having to trust second-hand observation.

  •

Rather than reconfiguring libtool every time I make a change to
ltmain.in, I keep a permanent libtool script in my
PATH, which sources ltmain.in directly.

The following steps describe how to create such a script, where
/home/src/libtool is the directory containing the libtool source
tree, /home/src/libtool/libtool is a libtool script that has been
configured for your platform, and ~/bin is a directory in your
PATH:

    trick$ cd ~/bin
trick$ sed '/^# ltmain\.sh/q' /home/src/libtool/libtool > libtool
trick$ echo '. /home/src/libtool/ltmain.in' >> libtool
trick$ chmod +x libtool
trick$ libtool --version
ltmain.sh (GNU @PACKAGE@) @VERSION@@TIMESTAMP@
trick$

The output of the final `libtool --version' command shows that the
ltmain.in script is being used directly.  Now, modify
~/bin/libtool or /home/src/libtool/ltmain.in directly in
order to test new changes without having to rerun configure.

GNU Free Documentation License

Version 1.1, March 2000

Copyright (C) 2000  Free Software Foundation, Inc.
    59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially.  Secondarily,
this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for
modifications made by others.

This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License.  The "Document", below, refers to any
such manual or work.  Any member of the public is a licensee, and is
addressed as "you".

A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject.  (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.

The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent.  A copy that is
not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML designed for human modification.  Opaque formats include
PostScript, PDF, proprietary formats that can be read and edited only
by proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML produced by some word processors for output
purposes only.

The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

VERBATIM COPYING

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols.  If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.

MODIFICATIONS

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:

  1.

Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document).  You may use the same title as a previous version
if the original publisher of that version gives permission.

  2.

 List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than five).

  3.

State on the Title page the name of the publisher of the
Modified Version, as the publisher.

  4.

 Preserve all the copyright notices of the Document.

  5.

Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.

  6.

Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.

  7.

Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.

  8.

Include an unaltered copy of this License.

  9.

Preserve the section entitled "History", and its title, and add to
it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page.  If
there is no section entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.

  10.

Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on.  These may be placed in the "History" section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.

  11.

In any section entitled "Acknowledgements" or "Dedications",
preserve the section's title, and preserve in the section all the
substance and tone of each of the contributor acknowledgements
and/or dedications given therein.

  12.

Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles.  Section numbers
or the equivalent are not considered part of the section titles.

  13.

Delete any section entitled "Endorsements".  Such a section
may not be included in the Modified Version.

  14.

Do not retitle any existing section as "Endorsements"
or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.

COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History"
in the various original documents, forming one section entitled
"History"; likewise combine any sections entitled "Acknowledgements",
and any sections entitled "Dedications".  You must delete all sections
entitled "Endorsements."

COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.

AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
compilation.  Such a compilation is called an "aggregate", and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate.

TRANSLATION

Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License provided that you also include the
original English version of this License.  In case of a disagreement
between the translation and the original English version of this
License, the original English version will prevail.

TERMINATION

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License.  Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.

FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:

Copyright (c)  YEAR  YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
A copy of the license is included in the section entitled "GNU
Free Documentation License".

If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no
Front-Cover Texts, write "no Front-Cover Texts" instead of
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.

Index

(

  • (const char *loader_name)

  • (lt_dlloader *place), (lt_dlloader *place), (lt_dlloader *place)

  • (void), (void)

    •

    .

  • `.la' files

  • `.libs' subdirectory

  • `.lo' files

    •

    a

  • AC_CONFIG_AUX_DIR

  • AC_DISABLE_FAST_INSTALL

  • AC_DISABLE_SHARED

  • AC_DISABLE_STATIC

  • AC_FUNC_ALLOCA

  • AC_LIBTOOL_DLOPEN

  • AC_LIBTOOL_WIN32_DLL

  • AC_PROG_LIBTOOL

  • AC_REPLACE_FUNCS

  • aclocal

  • allow_undefined_flag

  • always_export_symbols

  • AM_DISABLE_SHARED

  • AM_DISABLE_STATIC

  • AM_PROG_LIBTOOL

  • application-level dynamic linking, application-level dynamic linking

  • AR

  • ar

  • archive_cmds

  • archive_expsym_cmds

  • AS

  • assign.test

  • avoiding shared libraries

    •

    b

  • bug reports

  • buggy system linkers

  • bugs, subtle ones caused by buggy linkers

  • build-relink.test

  • build_libtool_libs

  • build_old_libs

    •

    c

  • C header files, portable

  • C++, pitfalls

  • C++, using

  • C, not using

  • CC, CC

  • cdemo-conf.test

  • cdemo-exec.test

  • cdemo-make.test

  • cdemo-shared.test

  • cdemo-static.test

  • CFLAGS

  • clean mode

  • command options, libtool

  • command options, libtoolize

  • compile mode

  • compiler_c_o

  • compiler_o_lo

  • compiling object files

  • complexity of library systems

  • config.guess

  • config.sub

  • configuring libtool

  • convenience libraries

  • CPPFLAGS

    •

    d

  • debugging libraries

  • definition of libraries

  • demo-conf.test

  • demo-exec.test

  • demo-inst.test

  • demo-make.test

  • demo-nofast.test

  • demo-nopic.test

  • demo-pic.test

  • demo-shared.test

  • demo-static.test

  • demo-unst.test

  • depdemo-conf.test

  • depdemo-exec.test

  • depdemo-inst.test

  • depdemo-make.test

  • depdemo-nofast.test

  • depdemo-shared.test

  • depdemo-static.test

  • depdemo-unst.test

  • dependencies between libraries

  • dependency versioning

  • deplibs.test

  • deplibs_check_method

  • design issues

  • design of library interfaces

  • design philosophy

  • developing libraries

  • dlclose, dlclose

  • dlerror

  • DLLTOOL

  • dlopen, dlopen

  • dlopen_self

  • dlopen_self_static

  • dlopen_support

  • dlopening modules, dlopening modules

  • dlopening, pitfalls

  • dlsym, dlsym

  • double-compilation, avoiding

  • dryrun.test

  • dynamic dependencies

  • dynamic linking, applications, dynamic linking, applications

  • dynamic modules, names

    •

    e

  • echo

  • eliding shared libraries

  • examples of using libtool

  • exclude_expsyms

  • execute mode

  • export_dynamic_flag_spec

  • export_symbols_cmds

  • extract_expsyms_cmds

    •

    f

  • failed tests

  • fast_install

  • file_magic

  • file_magic_cmd

  • file_magic_test_file

  • finish mode

  • finish_cmds

  • finish_eval

  • fix_srcfile_path

  • formal versioning

    •

    g

  • global functions

  • global_symbol_pipe

  • global_symbol_to_cdecl

    •

    h

  • hardcode.test

  • hardcode_action

  • hardcode_direct

  • hardcode_into_libs

  • hardcode_libdir_flag_spec

  • hardcode_libdir_separator

  • hardcode_minus_L

  • hardcode_shlibpath_var

  • header files

  • host

  • host_alias

    •

    i

  • implementation of libtool

  • include files, portable

  • include_expsyms

  • install

  • install mode

  • installation, finishing

  • inter-library dependencies

  • inter-library dependency

    •

    l

  • languages, non-C

  • LD, LD

  • LDFLAGS

  • libext

  • libltdl

  • libname_spec

  • libraries, definition of

  • libraries, finishing installation

  • libraries, stripping

  • library interfaces

  • library interfaces, design

  • library object file

  • library_names_spec

  • LIBS

  • libtool

  • libtool command options

  • libtool examples

  • libtool implementation

  • libtool libraries

  • libtool library versions

  • libtool specifications

  • libtoolize

  • libtoolize command options

  • link mode

  • link-2.test

  • link.test

  • link_all_deplibs

  • link_static_flag

  • linking against installed libraries

  • linking against uninstalled libraries

  • linking with installed libtool libraries

  • linking, partial

  • LN_S

  • lt_dladderror

  • lt_dladdsearchdir

  • lt_dlcaller_get_data

  • lt_dlcaller_id

  • lt_dlcaller_register

  • lt_dlcaller_set_data

  • lt_dlclose

  • lt_dlexit

  • lt_dlforeach

  • lt_dlfree

  • lt_dlgetinfo

  • lt_dlhandle

  • lt_dlhandle_next

  • lt_dlinfo

  • lt_dlinit

  • lt_dlisresident

  • lt_dlloader

  • lt_dlloader_add

  • lt_dlloader_data

  • lt_dlloader_exit

  • lt_dlloader_remove

  • lt_dlmakeresident

  • lt_dlmalloc

  • lt_dlmutex_geterror

  • lt_dlmutex_lock

  • lt_dlmutex_register

  • lt_dlmutex_seterror

  • lt_dlmutex_unlock

  • lt_dlopen

  • lt_dlopenext

  • lt_dlpreload

  • lt_dlpreload_default

  • lt_dlseterror

  • lt_dlsetsearchpath

  • lt_dlsym

  • lt_dlsymlist, lt_dlsymlist

  • lt_find_sym

  • lt_module

  • lt_module_close

  • lt_module_open

  • lt_preloaded_symbols

  • lt_ptr

  • lt_user_dlloader

  • LTALLOCA

  • LTDL_SET_PRELOADED_SYMBOLS()

  • LTLIBOBJS

  • LTLIBRARIES

  • ltmain.sh

    •

    m

  • Makefile

  • Makefile.am

  • Makefile.in

  • mdemo-conf.test

  • mdemo-exec.test

  • mdemo-inst.test

  • mdemo-make.test

  • mdemo-shared.test

  • mdemo-static.test

  • mdemo-unst.test

  • mode, clean

  • mode, compile

  • mode, execute

  • mode, finish

  • mode, install

  • mode, link

  • mode, uninstall

  • modules, dynamic, modules, dynamic

  • motivation for writing libtool

    •

    n

  • names of dynamic modules

  • need_lib_prefix

  • need_locks

  • need_version

  • NM, NM

  • no_builtin_flag

  • no_undefined_flag

  • noinst-link.test

  • nomode.test

  • none

    •

    o

  • objdir

  • OBJDUMP

  • object files, compiling

  • object files, library

  • objext

  • old_archive_cmds

  • old_archive_from_expsyms_cmds

  • old_archive_from_new_cmds

  • old_postinstall_cmds

  • old_postuninstall_cmds

  • old_striplib

  • opaque data types

  • options, libtool command

  • options, libtoolize command

  • other implementations, flaws in

    •

    p

  • partial linking

  • pass_all

  • PIC (position-independent code)

  • pic_flag

  • pitfalls using C++

  • pitfalls with dlopen

  • portable C headers

  • position-independent code

  • postinstall_cmds

  • postinstallation

  • postuninstall_cmds

  • problem reports

  • problems, blaming somebody else for

  • problems, solving

  • program wrapper scripts

    •

    q

  • quote.test

    •

    r

  • RANLIB, RANLIB

  • ranlib

  • reload_cmds

  • reload_flag

  • renaming interface functions

  • reporting bugs

  • reusability of library systems

  • runpath_var

    •

    s

  • saving time

  • security problems with buggy linkers

  • sh.test

  • shared libraries, not using

  • shared library versions

  • shl_load, shl_load

  • shlibpath_overrides_runpath

  • shlibpath_var

  • solving problems

  • soname_spec

  • specifications for libtool

  • standalone binaries

  • static linking

  • strip

  • striplib

  • stripping libraries

  • su

  • suffix.test

  • sys_lib_dlsearch_path_spec

  • sys_lib_search_path_spec

    •

    t

  • test suite

  • test_compile

  • tests, failed

  • thread_safe_flag_spec

  • time, saving

  • tricky design issues

  • trouble with C++

  • trouble with dlopen

  • troubleshooting

    •

    u

  • undefined symbols, allowing

  • uninstall mode

  • unknown

  • unresolved symbols, allowing

  • using shared libraries, not

    •

    v

  • version_type

  • versioning, formal

    •

    w

  • whole_archive_flag_spec

  • wl

  • wrapper scripts for programs

    •

    Footnotes

    (1)

    If you don't
specify an rpath, then libtool builds a libtool convenience
archive, not a shared library (see section Linking static libraries).

    (2)

    However, you should avoid using
`-L' or `-l' flags to link against an uninstalled libtool
library.  Just specify the relative path to the `.la' file, such as
`../intl/libintl.la'.  This is a design decision to eliminate any
ambiguity when linking against uninstalled shared libraries.

    (3)

    Don't
accidentally strip the libraries, though, or they will be unusable.

    (4)

    AC_PROG_LIBTOOL requires that
you define the `Makefile' variable top_builddir in your
`Makefile.in'.  Automake does this automatically, but Autoconf
users should set it to the relative path to the top of your build
directory (`../..', for example).

    (5)

    GNU Image
Manipulation Program, for those who haven't taken the plunge.  See
http://www.gimp.org/.

    (6)

    We used to recommend __P,
__BEGIN_DECLS and __END_DECLS.  This was bad advice since
symbols (even preprocessor macro names) that begin with an underscore
are reserved for the use of the compiler.

    (7)

    HP-UX,
to be different, uses a function named shl_load.

    (8)

    LIBPATH
on AIX, and SHLIB_PATH on HP-UX.

    (9)

    This is used for
the host dependent module loading API -- shl_load and
LoadLibrary for example

    (10)

    Even if libltdl is installed,
`AC_LIBLTDL_INSTALLABLE' may fail to detect it, if libltdl depends
on symbols provided by libraries other than the C library.  In this
case, it will needlessly build and install libltdl.

    (11)

    All code compiled for the PowerPC
and RS/6000 chips (powerpc-*-*, powerpcle-*-*, and
rs6000-*-*) is position-independent, regardless of the operating
system or compiler suite.  So, "regular objects" can be used to build
shared libraries on these systems and no special PIC compiler flags are
required.

This document was generated on 7 October 2001 using the
texi2html
translator version 1.54.


GNU macro processor

GNU m4, version 1.4

A powerful macro processor

Edition 1.4, November 1994

by Ren'e Seindal

Table of Contents

  • Introduction and preliminaries
    • Introduction to m4
    • Historical references
    • Invoking m4
    • Problems and bugs
    • Using this manual
  • Lexical and syntactic conventions
    • Names
    • Quoted strings
    • Other tokens
    • Comments
  • How to invoke macros
    • Macro invocation
    • Preventing macro invocation
    • Macro arguments
    • Quoting macro arguments
    • Macro expansion
  • How to define new macros
    • Defining a macro
    • Arguments to macros
    • Special arguments to macros
    • Deleting a macro
    • Renaming macros
    • Temporarily redefining macros
    • Indirect call of macros
    • Indirect call of builtins
  • Conditionals, loops and recursion
    • Testing macro definitions
    • Comparing strings
    • Loops and recursion
  • How to debug macros and input
    • Displaying macro definitions
    • Tracing macro calls
    • Controlling debugging output
    • Saving debugging output
  • Input control
    • Deleting whitespace in input
    • Changing the quote characters
    • Changing comment delimiters
    • Changing the lexical structure of words
    • Saving input
  • File inclusion
    • Including named files
    • Searching for include files
  • Diverting and undiverting output
    • Diverting output
    • Undiverting output
    • Diversion numbers
    • Discarding diverted text
  • Macros for text handling
    • Calculating length of strings
    • Searching for substrings
    • Searching for regular expressions
    • Extracting substrings
    • Translating characters
    • Substituting text by regular expression
    • Formatted output
  • Macros for doing arithmetic
    • Decrement and increment operators
    • Evaluating integer expressions
  • Running UNIX commands
    • Executing simple commands
    • Reading the output of commands
    • Exit codes
    • Making names for temporary files
  • Miscellaneous builtin macros
    • Printing error messages
    • Exiting from m4
  • Fast loading of frozen states
  • Compatibility with other versions of m4
    • Extensions in GNU m4
    • Facilities in System V m4 not in GNU m4
    • Other incompatibilities
  • Concept index
  • Macro index

Copyright (C) 1989, 90, 91, 92, 93, 94 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

Introduction and preliminaries

This first chapter explains what is GNU m4, where m4 comes from, how to read and use this documentation, how to call the m4 program and how to report bugs about it. It concludes by giving tips for reading the remainder of the manual.

The following chapters then detail all the features of the m4 language.

Introduction to m4

m4 is a macro processor, in the sense that it copies its input to the output, expanding macros as it goes. Macros are either builtin or user-defined, and can take any number of arguments. Besides just doing macro expansion, m4 has builtin functions for including named files, running UNIX commands, doing integer arithmetic, manipulating text in various ways, recursion, etc... m4 can be used either as a front-end to a compiler, or as a macro processor in its own right.

The m4 macro processor is widely available on all UNIXes. Usually, only a small percentage of users are aware of its existence. However, those who do often become commited users. The growing popularity of GNU Autoconf, which prerequires GNU m4 for generating the `configure' scripts, is an incentive for many to install it, while these people will not themselves program in m4. GNU m4 is mostly compatible with the System V, Release 3 version, except for some minor differences. See section Compatibility with other versions of m4 for more details.

Some people found m4 to be fairly addictive. They first use m4 for simple problems, then take bigger and bigger challenges, learning how to write complex m4 sets of macros along the way. Once really addicted, users pursue writing of sophisticated m4 applications even to solve simple problems, devoting more time debugging their m4 scripts than doing real work. Beware that m4 may be dangerous for the health of compulsive programmers.

Historical references

The historical notes included here are fairly incomplete, and not authoritative at all. Please knowledgeable users help us to more properly write this section.

GPM has been an important ancestor of m4. See C. Stratchey: "A General Purpose Macro generator", Computer Journal 8,3 (1965), pp. 225 ff. GPM is also succintly described into David Gries classic "Compiler Construction for Digital Computers".

While GPM was pure, m4 was meant to deal more with the true intricacies of real life: macros could be recognized with being pre-announced, skipping whitespace or end-of-lines was made easier, more constructs were builtin instead of derived, etc.

Originally, m4 was the engine for Rational FORTRAN preprocessor, that is, the ratfor equivalent of cpp.

Invoking m4

The format of the m4 command is:

m4 [option...] [macro-definitions...] [input-file...]

All options begin with `-', or if long option names are used, with a `--'. A long option name need not be written completely, and unambigous prefix is sufficient. m4 understands the following options:

--version
Print the version number of the program on standard output, then immediately exit m4 without reading any input-files.
--help
Print an help summary on standard output, then immediately exit m4 without reading any input-files.
-G
--traditional
Suppress all the extensions made in this implementation, compared to the System V version. See section Compatibility with other versions of m4, for a list of these.
-E
--fatal-warnings
Stop execution and exit m4 once the first warning has been issued, considering all of them to be fatal.
-dflags
--debug=flags
Set the debug-level according to the flags flags. The debug-level controls the format and amount of information presented by the debugging functions. See section Controlling debugging output for more details on the format and meaning of flags.
-lnum
--arglength=num
Restrict the size of the output generated by macro tracing. See section Controlling debugging output for more details.
-ofile
--error-output=file
Redirect debug and trace output to the named file. Error messages are still printed on the standard error output. See section Saving debugging output for more details.
-Idir
--include=dir
Make m4 search dir for included files that are not found in the current working directory. See section Searching for include files for more details.
-e
--interactive
Makes this invocation of m4 interactive. This means that all output will be unbuffered, and interrupts will be ignored.
-s
--synclines
Generate synchronisation lines, for use by the C preprocessor or other similar tools. This is useful, for example, when m4 is used as a front end to a compiler. Source file name and line number information is conveyed by directives of the form `#line linenum "filename"', which are inserted as needed into the middle of the input. Such directives mean that the following line originated or was expanded from the contents of input file filename at line linenum. The `"filename"' part is often omitted when the file name did not change from the previous directive. Synchronisation directives are always given on complete lines per themselves. When a synchronisation discrepancy occurs in the middle of an output line, the associated synchronisation directive is delayed until the beginning of the next generated line.
-P
--prefix-builtins
Internally modify all builtin macro names so they all start with the prefix `m4_'. For example, using this option, one should write `m4_define' instead of `define', and `m4___file__' instead of `__file__'.
-WREGEXP
--word-regexp=REGEXP
Use an alternative syntax for macro names. This experimental option might not be present on all GNU m4 implementations. (see section Changing the lexical structure of words).
-Hn
--hashsize=n
Make the internal hash table for symbol lookup be n entries big. The number should be prime. The default is 509 entries. It should not be necessary to increase this value, unless you define an excessive number of macros.
-Ln
--nesting-limit=n
Artificially limit the nesting of macro calls to n levels, stopping program execution if this limit is ever exceeded. When not specified, nesting is limited to 250 levels. The precise effect of this option might be more correctly associated with textual nesting than dynamic recursion. It has been useful when some complex m4 input was generated by mechanical means. Most users would never need this option. If shown to be obtrusive, this option (which is still experimental) might well disappear. This option does not have the ability to break endless rescanning loops, while these do not necessarily consume much memory or stack space. Through clever usage of rescanning loops, one can request complex, time-consuming computations to m4 with useful results. Putting limitations in this area would break m4 power. There are many pathological cases: `define(`a', `a')a' is only the simplest example (but see section Compatibility with other versions of m4). Expecting GNU m4 to detect these would be a little like expecting a compiler system to detect and diagnose endless loops: it is a quite hard problem in general, if not undecidable!
-Q
--quiet
--silent
Suppress warnings about missing or superflous arguments in macro calls.
-B
-S
-T
These options are present for compatibility with System V m4, but do nothing in this implementation.
-Nn
--diversions=n
These options are present only for compatibility with previous versions of GNU m4, and were controlling the number of possible diversions which could be used at the same time. They do nothing, because there is no fixed limit anymore.

Macro definitions and deletions can be made on the command line, by using the `-D' and `-U' options. They have the following format:

-Dname
-Dname=value
--define=name
--define=name=value
This enters name into the symbol table, before any input files are read. If `=value' is missing, the value is taken to be the empty string. The value can be any string, and the macro can be defined to take arguments, just as if it was defined from within the input.
-Uname
--undefine=name
This deletes any predefined meaning name might have. Obviously, only predefined macros can be deleted in this way.
-tname
--trace=name
This enters name into the symbol table, as undefined but traced. The macro will consequently be traced from the point it is defined.
-Ffile
--freeze-state file
Once execution is finished, write out the frozen state on the specified file (see section Fast loading of frozen states).
-Rfile
--reload-state file
Before execution starts, recover the internal state from the specified frozen file (see section Fast loading of frozen states).

The remaining arguments on the command line are taken to be input file names. If no names are present, the standard input is read. A file name of `-' is taken to mean the standard input.

The input files are read in the sequence given. The standard input can only be read once, so the filename `-' should only appear once on the command line.

Problems and bugs

If you have problems with GNU m4 or think you've found a bug, please report it. Before reporting a bug, make sure you've actually found a real bug. Carefully reread the documentation and see if it really says you can do what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation!

Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possible input file that reproduces the problem. Then send us the input file and the exact results m4 gave you. Also say what you expected to occur; this will help us decide whether the problem was really in the documentation.

Once you've got a precise problem, send e-mail to (Internet) `bug-gnu-utils@prep.ai.mit.edu' or (UUCP) `mit-eddie!prep.ai.mit.edu!bug-gnu-utils'. Please include the version number of m4 you are using. You can get this information with the command `m4 --version'.

Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation or are just obscure features, please report them too.

Using this manual

This manual contains a number of examples of m4 input and output, and a simple notation is used to distinguish input, output and error messages from m4. Examples are set out from the normal text, and shown in a fixed width font, like this

This is an example of an example!

To distinguish input from output, all output from m4 is prefixed by the string `=>', and all error messages by the string `error-->'. Thus

Example of input line
=>Output line from m4
error-->and an error message

As each of the predefined macros in m4 is described, a prototype call of the macro will be shown, giving descriptive names to the arguments, e.g.,

regexp(string, regexp, opt replacement)

All macro arguments in m4 are strings, but some are given special interpretation, e.g., as numbers, filenames, regular expressions, etc.

The `opt' before the third argument shows that this argument is optional--if it is left out, it is taken to be the empty string. An ellipsis (`...') last in the argument list indicates that any number of arguments may follow.

This document consistently writes and uses builtin, without an hyphen, as if it were an English word. This is how the builtin primitive is spelled within m4.

Lexical and syntactic conventions

As m4 reads its input, it separates it into tokens. A token is either a name, a quoted string, or any single character, that is not a part of either a name or a string. Input to m4 can also contain comments.

Names

A name is any sequence of letters, digits, and the character _ (underscore), where the first character is not a digit. If a name has a macro definition, it will be subject to macro expansion (see section How to invoke macros).

Examples of legal names are: `foo', `_tmp', and `name01'.

Quoted strings

A quoted string is a sequence of characters surrounded by the quotes ` and ', where the number of start and end quotes within the string balances. The value of a string token is the text, with one level of quotes stripped off. Thus

`'

is the empty string, and

``quoted''

is the string

`quoted'

The quote characters can be changed at any time, using the builtin macro changequote. See section Changing the quote characters for more information.

Other tokens

Any character, that is neither a part of a name, nor of a quoted string, is a token by itself.

Comments

Comments in m4 are normally delimited by the characters `#' and newline. All characters between the comment delimiters are ignored, but the entire comment (including the delimiters) is passed through to the output--comments are not discarded by m4.

Comments cannot be nested, so the first newline after a `#' ends the comment. The commenting effect of the begin comment character can be inhibited by quoting it.

The comment delimiters can be changed to any string at any time, using the builtin macro changecom. See section Changing comment delimiters for more information.

How to invoke macros

This chapter covers macro invocation, macro arguments and how macro expansion is treated.

Macro invocation

Macro invocations has one of the forms

name

which is a macro invocation without any arguments, or

name(arg1, arg2, ..., argn)

which is a macro invocation with n arguments. Macros can have any number of arguments. All arguments are strings, but different macros might interpret the arguments in different ways.

The opening parenthesis must follow the name directly, with no spaces in between. If it does not, the macro is called with no arguments at all.

For a macro call to have no arguments, the parentheses must be left out. The macro call

name()

is a macro call with one argument, which is the empty string, not a call with no arguments.

Preventing macro invocation

An innovation of the m4 language, compared to some of its predecessors (like Stratchey's GPM, for example), is the ability to recognize macro calls without resorting to any special, prefixed invocation character. While generally useful, this feature might sometimes be the source of spurious, unwanted macro calls. So, GNU m4 offers several mechanisms or techniques for inhibiting the recognition of names as macro calls.

First of all, many builtin macros cannot meaningfully be called without arguments. For any of these macros, whenever an opening parenthesis does not immediately follow their name, the builtin macro call is not triggered. This solves the most usual cases, like for `include' or `eval'. Later in this document, the sentence "This macro is recognized only when given arguments" refers to this specific provision.

There is also a command call option (--prefix-builtins, or -P) which requires all builtin macro names to be prefixed by `m4_' for them to be recognized. The option has no effect whatsoever on user defined macros. For example, with this option, one has to write m4_dnl and even m4_m4exit.

If your version of GNU m4 has the changeword feature compiled in, there it offers far more flexibility in specifying the syntax of macro names, both builtin or user-defined. See section Changing the lexical structure of words for more information on this experimental feature.

Of course, the simplest way to prevent a name to be interpreted as a call to an existing macro is to quote it. The remainder of this section studies a little more deeply how quoting affects macro invocation, and how quoting can be used to inhibit macro invocation.

Even if quoting is usually done over the whole macro name, it can also be done over only a few characters of this name. It is also possible to quote the empty string, but this works only inside the name. For example:

`divert'
`d'ivert
di`ver't
div`'ert

all yield the string `divert'. While in both:

`'divert
divert`'

the divert builtin macro will be called.

The output of macro evaluations is always rescanned. The following example would yield the string `de', exactly as if m4 has been given `substr(abcde, 3, 2)' as input:

define(`x', `substr(ab')
define(`y', `cde, 3, 2)')
x`'y

Unquoted strings on either side of a quoted string are subject to being recognized as macro names. In the following example, quoting the empty string allows for the dnl macro to be recognized as such:

define(`macro', `di$1')
macro(v)`'dnl

Without the quotes, this would rather yield the string `divdnl' followed by an end of line.

Quoting may prevent recognizing as a macro name the concatenation of a macro expansion with the surrounding characters. In this example:

define(`macro', `di$1')
macro(v)`ert'

the input will produce the string `divert'. If the quote was removed, the divert builtin would be called instead.

Macro arguments

When a name is seen, and it has a macro definition, it will be expanded as a macro.

If the name is followed by an opening parenthesis, the arguments will be collected before the macro is called. If too few arguments are supplied, the missing arguments are taken to be the empty string. If there are too many arguments, the excess arguments are ignored.

Normally m4 will issue warnings if a builtin macro is called with an inappropriate number of arguments, but it can be suppressed with the `-Q' command line option. For user defined macros, there is no check of the number of arguments given.

Macros are expanded normally during argument collection, and whatever commas, quotes and parentheses that might show up in the resulting expanded text will serve to define the arguments as well. Thus, if foo expands to `, b, c', the macro call

bar(a foo, d)

is a macro call with four arguments, which are `a ', `b', `c' and `d'. To understand why the first argument contains whitespace, remember that leading unquoted whitespace is never part of an argument, but trailing whitespace always is.

Quoting macro arguments

Each argument has leading unquoted whitespace removed. Within each argument, all unquoted parentheses must match. For example, if foo is a macro,

foo(() (`(') `(')

is a macro call, with one argument, whose value is `() (() ('.

It is common practice to quote all arguments to macros, unless you are sure you want the arguments expanded. Thus, in the above example with the parentheses, the `right' way to do it is like this:

foo(`() (() (')

It is, however, in certain cases necessary to leave out quotes for some arguments, and there is nothing wrong in doing it. It just makes life a bit harder, if you are not careful.

Macro expansion

When the arguments, if any, to a macro call have been collected, the macro is expanded, and the expansion text is pushed back onto the input (unquoted), and reread. The expansion text from one macro call might therefore result in more macros being called, if the calls are included, completely or partially, in the first macro calls' expansion.

Taking a very simple example, if foo expands to `bar', and bar expands to `Hello world', the input

foo

will expand first to `bar', and when this is reread and expanded, into `Hello world'.

How to define new macros

Macros can be defined, redefined and deleted in several different ways. Also, it is possible to redefine a macro, without losing a previous value, which can be brought back at a later time.

Defining a macro

The normal way to define or redefine macros is to use the builtin define:

define(name [, expansion])

which defines name to expand to expansion. If expansion is not given, it is taken to be empty.

The expansion of define is void.

The following example defines the macro foo to expand to the text `Hello World.'.

define(`foo', `Hello world.')
=>
foo
=>Hello world.

The empty line in the output is there because the newline is not a part of the macro definition, and it is consequently copied to the output. This can be avoided by use of the macro dnl. See section Deleting whitespace in input, for details.

The macro define is recognized only with parameters.

Arguments to macros

Macros can have arguments. The nth argument is denoted by $n in the expansion text, and is replaced by the nth actual argument, when the macro is expanded. Here is a example of a macro with two arguments. It simply exchanges the order of the two arguments.

define(`exch', `$2, $1')
=>
exch(arg1, arg2)
=>arg2, arg1

This can be used, for example, if you like the arguments to define to be reversed.

define(`exch', `$2, $1')
=>
define(exch(``expansion text'', ``macro''))
=>
macro
=>expansion text

See section Quoting macro arguments, for an explanation of the double quotes.

GNU m4 allows the number following the `$' to consist of one or more digits, allowing macros to have any number of arguments. This is not so in UNIX implementations of m4, which only recognize one digit.

As a special case, the zero'th argument, $0, is always the name of the macro being expanded.

define(`test', ``Macro name: $0'')
=>
test
=>Macro name: test

If you want quoted text to appear as part of the expansion text, remember that quotes can be nested in quoted strings. Thus, in

define(`foo', `This is macro `foo'.')
=>
foo
=>This is macro foo.

The `foo' in the expansion text is not expanded, since it is a quoted string, and not a name.

Special arguments to macros

There is a special notation for the number of actual arguments supplied, and for all the actual arguments.

The number of actual arguments in a macro call is denoted by $# in the expansion text. Thus, a macro to display the number of arguments given can be

define(`nargs', `$#')
=>
nargs
=>0
nargs()
=>1
nargs(arg1, arg2, arg3)
=>3

The notation $* can be used in the expansion text to denote all the actual arguments, unquoted, with commas in between. For example

define(`echo', `$*')
=>
echo(arg1,    arg2, arg3 , arg4)
=>arg1,arg2,arg3 ,arg4

Often each argument should be quoted, and the notation $@ handles that. It is just like $*, except that it quotes each argument. A simple example of that is:

define(`echo', `$@')
=>
echo(arg1,    arg2, arg3 , arg4)
=>arg1,arg2,arg3 ,arg4

Where did the quotes go? Of course, they were eaten, when the expanded text were reread by m4. To show the difference, try

define(`echo1', `$*')
=>
define(`echo2', `$@')
=>
define(`foo', `This is macro `foo'.')
=>
echo1(foo)
=>This is macro This is macro foo..
echo2(foo)
=>This is macro foo.

See section Tracing macro calls, if you do not understand this.

A `$' sign in the expansion text, that is not followed by anything m4 understands, is simply copied to the macro expansion, as any other text is.

define(`foo', `$$$ hello $$$')
=>
foo
=>$$$ hello $$$

If you want a macro to expand to something like `$12', put a pair of quotes after the $. This will prevent m4 from interpreting the $ sign as a reference to an argument.

Deleting a macro

A macro definition can be removed with undefine:

undefine(name)

which removes the macro name. The macro name must necessarily be quoted, since it will be expanded otherwise.

The expansion of undefine is void.

foo
=>foo
define(`foo', `expansion text')
=>
foo
=>expansion text
undefine(`foo')
=>
foo
=>foo

It is not an error for name to have no macro definition. In that case, undefine does nothing.

The macro undefine is recognized only with parameters.

Renaming macros

It is possible to rename an already defined macro. To do this, you need the builtin defn:

defn(name)

which expands to the quoted definition of name. If the argument is not a defined macro, the expansion is void.

If name is a user-defined macro, the quoted definition is simply the quoted expansion text. If, instead, name is a builtin, the expansion is a special token, which points to the builtin's internal definition. This token is only meaningful as the second argument to define (and pushdef), and is ignored in any other context.

Its normal use is best understood through an example, which shows how to rename undefine to zap:

define(`zap', defn(`undefine'))
=>
zap(`undefine')
=>
undefine(`zap')
=>undefine(zap)

In this way, defn can be used to copy macro definitions, and also definitions of builtin macros. Even if the original macro is removed, the other name can still be used to access the definition.

The macro defn is recognized only with parameters.

Temporarily redefining macros

It is possible to redefine a macro temporarily, reverting to the previous definition at a later time. This is done with the builtins pushdef and popdef:

pushdef(name [, expansion])
popdef(name)

which are quite analogous to define and undefine.

These macros work in a stack-like fashion. A macro is temporarily redefined with pushdef, which replaces an existing definition of name, while saving the previous definition, before the new one is installed. If there is no previous definition, pushdef behaves exactly like define.

If a macro has several definitions (of which only one is accessible), the topmost definition can be removed with popdef. If there is no previous definition, popdef behaves like undefine.

define(`foo', `Expansion one.')
=>
foo
=>Expansion one.
pushdef(`foo', `Expansion two.')
=>
foo
=>Expansion two.
popdef(`foo')
=>
foo
=>Expansion one.
popdef(`foo')
=>
foo
=>foo

If a macro with several definitions is redefined with define, the topmost definition is replaced with the new definition. If it is removed with undefine, all the definitions are removed, and not only the topmost one.

define(`foo', `Expansion one.')
=>
foo
=>Expansion one.
pushdef(`foo', `Expansion two.')
=>
foo
=>Expansion two.
define(`foo', `Second expansion two.')
=>
foo
=>Second expansion two.
undefine(`foo')
=>
foo
=>foo

It is possible to temporarily redefine a builtin with pushdef and defn.

The macros pushdef and popdef are recognized only with parameters.

Indirect call of macros

Any macro can be called indirectly with indir:

indir(name, ...)

which results in a call to the macro name, which is passed the rest of the arguments. This can be used to call macros with "illegal" names (define allows such names to be defined):

define(`$$internal$macro', `Internal macro (name `$0')')
=>
$$internal$macro
=>$$internal$macro
indir(`$$internal$macro')
=>Internal macro (name $$internal$macro)

The point is, here, that larger macro packages can have private macros defined, that will not be called by accident. They can only be called through the builtin indir.

Indirect call of builtins

Builtin macros can be called indirectly with builtin:

builtin(name, ...)

which results in a call to the builtin name, which is passed the rest of the arguments. This can be used, if name has been given another definition that has covered the original.

The macro builtin is recognized only with parameters.

Conditionals, loops and recursion

Macros, expanding to plain text, perhaps with arguments, are not quite enough. We would like to have macros expand to different things, based on decisions taken at run-time. E.g., we need some kind of conditionals. Also, we would like to have some kind of loop construct, so we could do something a number of times, or while some condition is true.

Testing macro definitions

There are two different builtin conditionals in m4. The first is ifdef:

ifdef(name, string-1, opt string-2)

which makes it possible to test whether a macro is defined or not. If name is defined as a macro, ifdef expands to string-1, otherwise to string-2. If string-2 is omitted, it is taken to be the empty string (according to the normal rules).

ifdef(`foo', ``foo' is defined', ``foo' is not defined')
=>foo is not defined
define(`foo', `')
=>
ifdef(`foo', ``foo' is defined', ``foo' is not defined')
=>foo is defined

The macro ifdef is recognized only with parameters.

Comparing strings

The other conditional, ifelse, is much more powerful. It can be used as a way to introduce a long comment, as an if-else construct, or as a multibranch, depending on the number of arguments supplied:

ifelse(comment)
ifelse(string-1, string-2, equal, opt not-equal)
ifelse(string-1, string-2, equal, ...)

Used with only one argument, the ifelse simply discards it and produces no output. This is a common m4 idiom for introducing a block comment, as an alternative to repeatedly using dnl. This special usage is recognized by GNU m4, so that in this case, the warning about missing arguments is never triggered.

If called with three or four arguments, ifelse expands into equal, if string-1 and string-2 are equal (character for character), otherwise it expands to not-equal.

ifelse(foo, bar, `true')
=>
ifelse(foo, foo, `true')
=>true
ifelse(foo, bar, `true', `false')
=>false
ifelse(foo, foo, `true', `false')
=>true

However, ifelse can take more than four arguments. If given more than four arguments, ifelse works like a case or switch statement in traditional programming languages. If string-1 and string-2 are equal, ifelse expands into equal, otherwise the procedure is repeated with the first three arguments discarded. This calls for an example:

ifelse(foo, bar, `third', gnu, gnats, `sixth', `seventh')
=>seventh

Naturally, the normal case will be slightly more advanced than these examples. A common use of ifelse is in macros implementing loops of various kinds.

The macro ifelse is recognized only with parameters.

Loops and recursion

There is no direct support for loops in m4, but macros can be recursive. There is no limit on the number of recursion levels, other than those enforced by your hardware and operating system.

Loops can be programmed using recursion and the conditionals described previously.

There is a builtin macro, shift, which can, among other things, be used for iterating through the actual arguments to a macro:

shift(...)

It takes any number of arguments, and expands to all but the first argument, separated by commas, with each argument quoted.

shift(bar)
=>
shift(foo, bar, baz)
=>bar,baz

An example of the use of shift is this macro, which reverses the order of its arguments:

define(`reverse', `ifelse($#, 0, , $#, 1, ``$1'',
              `reverse(shift($@)), `$1'')')
=>
reverse
=>
reverse(foo)
=>foo
reverse(foo, bar, gnats, and gnus)
=>and gnus, gnats, bar, foo

While not a very interesting macro, it does show how simple loops can be made with shift, ifelse and recursion.

Here is an example of a loop macro that implements a simple forloop. It can, for example, be used for simple counting:

forloop(`i', 1, 8, `i ')
=>1 2 3 4 5 6 7 8

The arguments are a name for the iteration variable, the starting value, the final value, and the text to be expanded for each iteration. With this macro, the macro i is defined only within the loop. After the loop, it retains whatever value it might have had before.

For-loops can be nested, like

forloop(`i', 1, 4, `forloop(`j', 1, 8, `(i, j) ')
')
=>(1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8)
=>(2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8)
=>(3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8)
=>(4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8)
=>

The implementation of the forloop macro is fairly straightforward. The forloop macro itself is simply a wrapper, which saves the previous definition of the first argument, calls the internal macro _forloop, and re-establishes the saved definition of the first argument.

The macro _forloop expands the fourth argument once, and tests to see if it is finished. If it has not finished, it increments the iteration variable (using the predefined macro incr, see section Decrement and increment operators), and recurses.

Here is the actual implementation of forloop:

define(`forloop',
       `pushdef(`$1', `$2')_forloop(`$1', `$2', `$3', `$4')popdef(`$1')')
define(`_forloop',
       `$4`'ifelse($1, `$3', ,
           `define(`$1', incr($1))_forloop(`$1', `$2', `$3', `$4')')')

Notice the careful use of quotes. Only three macro arguments are unquoted, each for its own reason. Try to find out why these three arguments are left unquoted, and see what happens if they are quoted.

Now, even though these two macros are useful, they are still not robust enough for general use. They lack even basic error handling of cases like start value less than final value, and the first argument not being a name. Correcting these errors are left as an exercise to the reader.

How to debug macros and input

When writing macros for m4, most of the time they woould not work as intended (as is the case with most programming languages). There is a little support for macro debugging in m4.

Displaying macro definitions

If you want to see what a name expands into, you can use the builtin dumpdef:

dumpdef(...)

which accepts any number of arguments. If called without any arguments, it displays the definitions of all known names, otherwise it displays the definitions of the names given. The output is printed directly on the standard error output.

The expansion of dumpdef is void.

define(`foo', `Hello world.')
=>
dumpdef(`foo')
error-->foo:	`Hello world.'
=>
dumpdef(`define')
error-->define:	<define>
=>

The last example shows how builtin macros definitions are displayed.

See section Controlling debugging output for information on controlling the details of the display.

Tracing macro calls

It is possible to trace macro calls and expansions through the builtins traceon and traceoff:

traceon(...)
traceoff(...)

When called without any arguments, traceon and traceoff will turn tracing on and off, respectively, for all defined macros. When called with arguments, only the named macros are affected.

The expansion of traceon and traceoff is void.

Whenever a traced macro is called and the arguments have been collected, the call is displayed. If the expansion of the macro call is not void, the expansion can be displayed after the call. The output is printed directly on the standard error output.

define(`foo', `Hello World.')
=>
define(`echo', `$@')
=>
traceon(`foo', `echo')
=>
foo
error-->m4trace: -1- foo -> `Hello World.'
=>Hello World.
echo(gnus, and gnats)
error-->m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
=>gnus,and gnats

The number between dashes is the depth of the expansion. It is one most of the time, signifying an expansion at the outermost level, but it increases when macro arguments contain unquoted macro calls.

See section Controlling debugging output for information on controlling the details of the display.

Controlling debugging output

The `-d' option to m4 controls the amount of details presented, when using the macros described in the preceding sections.

The flags following the option can be one or more of the following:

t
Trace all macro calls made in this invocation of m4.
a
Show the actual arguments in each macro call. This applies to all macro calls if the `t' flag is used, otherwise only the macros covered by calls of traceon.
e
Show the expansion of each macro call, if it is not void. This applies to all macro calls if the `t' flag is used, otherwise only the macros covered by calls of traceon.
q
Quote actual arguments and macro expansions in the display with the current quotes.
c
Show several trace lines for each macro call. A line is shown when the macro is seen, but before the arguments are collected; a second line when the arguments have been collected and a third line after the call has completed.
x
Add a unique `macro call id' to each line of the trace output. This is useful in connection with the `c' flag above.
f
Show the name of the current input file in each trace output line.
l
Show the the current input line number in each trace output line.
p
Print a message when a named file is found through the path search mecanism (see section Searching for include files), giving the actual filename used.
i
Print a message each time the current input file is changed, giving file name and input line number.
V
A shorthand for all of the above flags.

If no flags are specified with the `-d' option, the default is `aeq'. The examples in the previous two sections assumed the default flags.

There is a builtin macro debugmode, which allows on-the-fly control of the debugging output format:

debugmode(opt flags)

The argument flags should be a subset of the letters listed above. As special cases, if the argument starts with a `+', the flags are added to the current debug flags, and if it starts with a `-', they are removed. If no argument is present, the debugging flags are set to zero (as if no `-d' was given), and with an empty argument the flags are reset to the default.

Saving debugging output

Debug and tracing output can be redirected to files using either the `-o' option to m4, or with the builtin macro debugfile:

debugfile(opt filename)

will send all further debug and trace output to filename. If filename is empty, debug and trace output are discarded and if debugfile is called without any arguments, debug and trace output are sent to the standard error output.

Input control

This chapter describes various builtin macros for controlling the input to m4.

Deleting whitespace in input

The builtin dnl reads and discards all characters, up to and including the first newline:

dnl

and it is often used in connection with define, to remove the newline that follow the call to define. Thus

define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
foo
=>Macro foo.

The input up to and including the next newline is discarded, as opposed to the way comments are treated (see section Comments).

Usually, dnl is immediately followed by an end of line or some other whitespace. GNU m4 will produce a warning diagnostic if dnl is followed by an open parenthesis. In this case, dnl will collect and process all arguments, looking for a matching close parenthesis. All predictable side effects resulting from this collection will take place. dnl will return no output. The input following the matching close parenthesis up to and including the next newline, on whatever line containing it, will still be discarded.

Changing the quote characters

The default quote delimiters can be changed with the builtin changequote:

changequote(opt start, opt end)

where start is the new start-quote delimiter and end is the new end-quote delimiter. If any of the arguments are missing, the default quotes (` and ') are used instead of the void arguments.

The expansion of changequote is void.

changequote([, ])
=>
define([foo], [Macro [foo].])
=>
foo
=>Macro foo.

If no single character is appropriate, start and end can be of any length.

changequote([[, ]])
=>
define([[foo]], [[Macro [[[foo]]].]])
=>
foo
=>Macro [foo].

Changing the quotes to the empty strings will effectively disable the quoting mechanism, leaving no way to quote text.

define(`foo', `Macro `FOO'.')
=>
changequote(, )
=>
foo
=>Macro `FOO'.
`foo'
=>`Macro `FOO'.'

There is no way in m4 to quote a string containing an unmatched left quote, except using changequote to change the current quotes.

Neither quote string should start with a letter or `_' (underscore), as they will be confused with names in the input. Doing so disables the quoting mechanism.

Changing comment delimiters

The default comment delimiters can be changed with the builtin macro changecom:

changecom(opt start, opt end)

where start is the new start-comment delimiter and end is the new end-comment delimiter. If any of the arguments are void, the default comment delimiters (# and newline) are used instead of the void arguments. The comment delimiters can be of any length.

The expansion of changecom is void.

define(`comment', `COMMENT')
=>
# A normal comment
=># A normal comment
changecom(`/*', `*/')
=>
# Not a comment anymore
=># Not a COMMENT anymore
But: /* this is a comment now */ while this is not a comment
=>But: /* this is a comment now */ while this is not a COMMENT

Note how comments are copied to the output, much as if they were quoted strings. If you want the text inside a comment expanded, quote the start comment delimiter.

Calling changecom without any arguments disables the commenting mechanism completely.

define(`comment', `COMMENT')
=>
changecom
=>
# Not a comment anymore
=># Not a COMMENT anymore

Changing the lexical structure of words

The macro changeword and all associated functionnality is experimental. It is only available if the --enable-changeword option was given to configure, at GNU m4 installation time. The functionnality might change or even go away in the future. Do not rely on it. Please direct your comments about it the same way you would do for bugs.

A file being processed by m4 is split into quoted strings, words (potential macro names) and simple tokens (any other single character). Initially a word is defined by the following regular expression:

[_a-zA-Z][_a-zA-Z0-9]*

Using changeword, you can change this regular expression. Relaxing m4's lexical rules might be useful (for example) if you wanted to apply translations to a file of numbers:

changeword(`[_a-zA-Z0-9]+')
define(1, 0)
=>1

Tightening the lexical rules is less useful, because it will generally make some of the builtins unavailable. You could use it to prevent accidental call of builtins, for example:

define(`_indir', defn(`indir'))
changeword(`_[_a-zA-Z0-9]*')
esyscmd(foo)
_indir(`esyscmd', `ls')

Because m4 constructs its words a character at a time, there is a restriction on the regular expressions that may be passed to changeword. This is that if your regular expression accepts `foo', it must also accept `f' and `fo'.

changeword has another function. If the regular expression supplied contains any bracketed subexpressions, then text outside the first of these is discarded before symbol lookup. So:

changecom(`/*', `*/')
changeword(`#\([_a-zA-Z0-9]*\)')
#esyscmd(ls)

m4 now requires a `#' mark at the beginning of every macro invocation, so one can use m4 to preprocess shell scripts without getting shift commands swallowed, and plain text without losing various common words.

m4's macro substitution is based on text, while TeX's is based on tokens. changeword can throw this difference into relief. For example, here is the same idea represented in TeX and m4. First, the TeX version:

\def\a{\message{Hello}}
\catcode`\@=0
\catcode`\\=12
=>@a
=>@bye

Then, the m4 version:

define(a, `errprint(`Hello')')
changeword(`@\([_a-zA-Z0-9]*\)')
=>@a

In the TeX example, the first line defines a macro a to print the message `Hello'. The second line defines @ to be usable instead of \ as an escape character. The third line defines \ to be a normal printing character, not an escape. The fourth line invokes the macro a. So, when TeX is run on this file, it displays the message `Hello'.

When the m4 example is passed through m4, it outputs `errprint(Hello)'. The reason for this is that TeX does lexical analysis of macro definition when the macro is defined. m4 just stores the text, postponing the lexical analysis until the macro is used.

You should note that using changeword will slow m4 down by a factor of about seven.

Saving input

It is possible to `save' some text until the end of the normal input has been seen. Text can be saved, to be read again by m4 when the normal input has been exhausted. This feature is normally used to initiate cleanup actions before normal exit, e.g., deleting temporary files.

To save input text, use the builtin m4wrap:

m4wrap(string, ...)

which stores string and the rest of the arguments in a safe place, to be reread when end of input is reached.

define(`cleanup', `This is the `cleanup' actions.
')
=>
m4wrap(`cleanup')
=>
This is the first and last normal input line.
=>This is the first and last normal input line.
^D
=>This is the cleanup actions.

The saved input is only reread when the end of normal input is seen, and not if m4exit is used to exit m4.

It is safe to call m4wrap from saved text, but then the order in which the saved text is reread is undefined. If m4wrap is not used recursively, the saved pieces of text are reread in the opposite order in which they were saved (LIFO--last in, first out).

File inclusion

m4 allows you to include named files at any point in the input.

Including named files

There are two builtin macros in m4 for including files:

include(filename)
sinclude(filename)

both of which cause the file named filename to be read by m4. When the end of the file is reached, input is resumed from the previous input file.

The expansion of include and sinclude is therefore the contents of filename.

It is an error for an included file not to exist. If you do not want error messages about non-existent files, sinclude can be used to include a file, if it exists, expanding to nothing if it does not.

include(`no-such-file')
=>
error-->30.include:2: m4: Cannot open no-such-file: No such file or directory
sinclude(`no-such-file')
=>

Assume in the following that the file `incl.m4' contains the lines:

Include file start
foo
Include file end

Normally file inclusion is used to insert the contents of a file into the input stream. The contents of the file will be read by m4 and macro calls in the file will be expanded:

define(`foo', `FOO')
=>
include(`incl.m4')
=>Include file start
=>FOO
=>Include file end
=>

The fact that include and sinclude expand to the contents of the file can be used to define macros that operate on entire files. Here is an example, which defines `bar' to expand to the contents of `incl.m4':

define(`bar', include(`incl.m4'))
=>
This is `bar':  >>>bar<<<
=>This is bar:  >>>Include file start
=>foo
=>Include file end
=><<<

This use of include is not trivial, though, as files can contain quotes, commas and parentheses, which can interfere with the way the m4 parser works.

The builtin macros include and sinclude are recognized only when given arguments.

Searching for include files

GNU m4 allows included files to be found in other directories than the current working directory.

If a file is not found in the current working directory, and the file name is not absolute, the file will be looked for in a specified search path. First, the directories specified with the `-I' option will be searched, in the order found on the command line. Second, if the `M4PATH' environment variable is set, it is expected to contain a colon-separated list of directories, which will be searched in order.

If the automatic search for include-files causes trouble, the `p' debug flag (see section Controlling debugging output) can help isolate the problem.

Diverting and undiverting output

Diversions are a way of temporarily saving output. The output of m4 can at any time be diverted to a temporary file, and be reinserted into the output stream, undiverted, again at a later time.

Numbered diversions are counted from 0 upwards, diversion number 0 being the normal output stream. The number of simultaneous diversions is limited mainly by the memory used to describe them, because GNU m4 tries to keep diversions in memory. However, there is a limit to the overall memory usable by all diversions taken altogether (512K, currently). When this maximum is about to be exceeded, a temporary file is opened to receive the contents of the biggest diversion still in memory, freeing this memory for other diversions. So, it is theoretically possible that the number of diversions be limited by the number of available file descriptors.

Diverting output

Output is diverted using divert:

divert(opt number)

where number is the diversion to be used. If number is left out, it is assumed to be zero.

The expansion of divert is void.

When all the m4 input will have been processed, all existing diversions are automatically undiverted, in numerical order.

divert(1)
This text is diverted.
divert
=>
This text is not diverted.
=>This text is not diverted.
^D
=>
=>This text is diverted.

Several calls of divert with the same argument do not overwrite the previous diverted text, but append to it.

If output is diverted to a non-existent diversion, it is simply discarded. This can be used to suppress unwanted output. A common example of unwanted output is the trailing newlines after macro definitions. Here is how to avoid them.

divert(-1)
define(`foo', `Macro `foo'.')
define(`bar', `Macro `bar'.')
divert
=>

This is a common programming idiom in m4.

Undiverting output

Diverted text can be undiverted explicitly using the builtin undivert:

undivert(opt number, ...)

which undiverts the diversions given by the arguments, in the order given. If no arguments are supplied, all diversions are undiverted, in numerical order.

The expansion of undivert is void.

divert(1)
This text is diverted.
divert
=>
This text is not diverted.
=>This text is not diverted.
undivert(1)
=>
=>This text is diverted.
=>

Notice the last two blank lines. One of them comes from the newline following undivert, the other from the newline that followed the divert! A diversion often starts with a blank line like this.

When diverted text is undiverted, it is not reread by m4, but rather copied directly to the current output, and it is therefore not an error to undivert into a diversion.

When a diversion has been undiverted, the diverted text is discarded, and it is not possible to bring back diverted text more than once.

divert(1)
This text is diverted first.
divert(0)undivert(1)dnl
=>
=>This text is diverted first.
undivert(1)
=>
divert(1)
This text is also diverted but not appended.
divert(0)undivert(1)dnl
=>
=>This text is also diverted but not appended.

Attempts to undivert the current diversion are silently ignored.

GNU m4 allows named files to be undiverted. Given a non-numeric argument, the contents of the file named will be copied, uninterpreted, to the current output. This complements the builtin include (see section Including named files). To illustrate the difference, assume the file `foo' contains the word `bar':

define(`bar', `BAR')
=>
undivert(`foo')
=>bar
=>
include(`foo')
=>BAR
=>

Diversion numbers

The builtin divnum:

divnum

expands to the number of the current diversion.

Initial divnum
=>Initial 0
divert(1)
Diversion one: divnum
divert(2)
Diversion two: divnum
divert
=>
^D
=>
=>Diversion one: 1
=>
=>Diversion two: 2

The last call of divert without argument is necessary, since the undiverted text would otherwise be diverted itself.

Discarding diverted text

Often it is not known, when output is diverted, whether the diverted text is actually needed. Since all non-empty diversion are brought back on the main output stream when the end of input is seen, a method of discarding a diversion is needed. If all diversions should be discarded, the easiest is to end the input to m4 with `divert(-1)' followed by an explicit `undivert':

divert(1)
Diversion one: divnum
divert(2)
Diversion two: divnum
divert(-1)
undivert
^D

No output is produced at all.

Clearing selected diversions can be done with the following macro:

define(`cleardivert',
`pushdef(`_num', divnum)divert(-1)undivert($@)divert(_num)popdef(`_num')')
=>

It is called just like undivert, but the effect is to clear the diversions, given by the arguments. (This macro has a nasty bug! You should try to see if you can find it and correct it.)

Macros for text handling

There are a number of builtins in m4 for manipulating text in various ways, extracting substrings, searching, substituting, and so on.

Calculating length of strings

The length of a string can be calculated by len:

len(string)

which expands to the length of string, as a decimal number.

len()
=>0
len(`abcdef')
=>6

The builtin macro len is recognized only when given arguments.

Searching for substrings

Searching for substrings is done with index:

index(string, substring)

which expands to the index of the first occurrence of substring in string. The first character in string has index 0. If substring does not occur in string, index expands to `-1'.

index(`gnus, gnats, and armadillos', `nat')
=>7
index(`gnus, gnats, and armadillos', `dag')
=>-1

The builtin macro index is recognized only when given arguments.

Searching for regular expressions

Searching for regular expressions is done with the builtin regexp:

regexp(string, regexp, opt replacement)

which searches for regexp in string. The syntax for regular expressions is the same as in GNU Emacs. See section `Syntax of Regular Expressions' in The GNU Emacs Manual.

If replacement is omitted, regexp expands to the index of the first match of regexp in string. If regexp does not match anywhere in string, it expands to -1.

regexp(`GNUs not Unix', `\<[a-z]\w+')
=>5
regexp(`GNUs not Unix', `\<Q\w*')
=>-1

If replacement is supplied, regexp changes the expansion to this argument, with `\n' substituted by the text matched by the nth parenthesized sub-expression of regexp, `\&' being the text the entire regular expression matched.

regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
=>*** Unix *** nix ***

The builtin macro regexp is recognized only when given arguments.

Extracting substrings

Substrings are extracted with substr:

substr(string, from, opt length)

which expands to the substring of string, which starts at index from, and extends for length characters, or to the end of string, if length is omitted. The starting index of a string is always 0.

substr(`gnus, gnats, and armadillos', 6)
=>gnats, and armadillos
substr(`gnus, gnats, and armadillos', 6, 5)
=>gnats

The builtin macro substr is recognized only when given arguments.

Translating characters

Character translation is done with translit:

translit(string, chars, replacement)

which expands to string, with each character that occurs in chars translated into the character from replacement with the same index.

If replacement is shorter than chars, the excess characters are deleted from the expansion. If replacement is omitted, all characters in string, that are present in chars are deleted from the expansion.

Both chars and replacement can contain character-ranges, e.g., `a-z' (meaning all lowercase letters) or `0-9' (meaning all digits). To include a dash `-' in chars or replacement, place it first or last.

It is not an error for the last character in the range to be `larger' than the first. In that case, the range runs backwards, i.e., `9-0' means the string `9876543210'.

translit(`GNUs not Unix', `A-Z')
=>s not nix
translit(`GNUs not Unix', `a-z', `A-Z')
=>GNUS NOT UNIX
translit(`GNUs not Unix', `A-Z', `z-a')
=>tmfs not fnix

The first example deletes all uppercase letters, the second converts lowercase to uppercase, and the third `mirrors' all uppercase letters, while converting them to lowercase. The two first cases are by far the most common.

The builtin macro translit is recognized only when given arguments.

Substituting text by regular expression

Global substitution in a string is done by patsubst:

patsubst(string, regexp, opt replacement)

which searches string for matches of regexp, and substitutes replacement for each match. The syntax for regular expressions is the same as in GNU Emacs.

The parts of string that are not covered by any match of regexp are copied to the expansion. Whenever a match is found, the search proceeds from the end of the match, so a character from string will never be substituted twice. If regexp matches a string of zero length, the start position for the search is incremented, to avoid infinite loops.

When a replacement is to be made, replacement is inserted into the expansion, with `\n' substituted by the text matched by the nth parenthesized sub-expression of regexp, `\&' being the text the entire regular expression matched.

The replacement argument can be omitted, in which case the text matched by regexp is deleted.

patsubst(`GNUs not Unix', `^', `OBS: ')
=>OBS: GNUs not Unix
patsubst(`GNUs not Unix', `\<', `OBS: ')
=>OBS: GNUs OBS: not OBS: Unix
patsubst(`GNUs not Unix', `\w*', `(\&)')
=>(GNUs)() (not)() (Unix)
patsubst(`GNUs not Unix', `\w+', `(\&)')
=>(GNUs) (not) (Unix)
patsubst(`GNUs not Unix', `[A-Z][a-z]+')
=>GN not

Here is a slightly more realistic example, which capitalizes individual word or whole sentences, by substituting calls of the macros upcase and downcase into the strings.

define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl
define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
define(`capitalize1',
     `regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl
define(`capitalize',
     `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
capitalize(`GNUs not Unix')
=>Gnus Not Unix

The builtin macro patsubst is recognized only when given arguments.

Formatted output

Formatted output can be made with format:

format(format-string, ...)

which works much like the C function printf. The first argument is a format string, which can contain `%' specifications, and the expansion of format is the formatted string.

Its use is best described by a few examples:

define(`foo', `The brown fox jumped over the lazy dog')
=>
format(`The string "%s" is %d characters long', foo, len(foo))
=>The string "The brown fox jumped over the lazy dog" is 38 characters long

Using the forloop macro defined in See section Loops and recursion, this example shows how format can be used to produce tabular output.

forloop(`i', 1, 10, `format(`%6d squared is %10d
', i, eval(i**2))')
=>     1 squared is	    1
=>     2 squared is	    4
=>     3 squared is	    9
=>     4 squared is	   16
=>     5 squared is	   25
=>     6 squared is	   36
=>     7 squared is	   49
=>     8 squared is	   64
=>     9 squared is	   81
=>    10 squared is	  100

The builtin format is modeled after the ANSI C `printf' function, and supports the normal `%' specifiers: `c', `s', `d', `o', `x', `X', `u', `e', `E' and `f'; it supports field widths and precisions, and the modifiers `+', `-', ` ', `0', `#', `h' and `l'. For more details on the functioning of printf, see the C Library Manual.

Macros for doing arithmetic

Integer arithmetic is included in m4, with a C-like syntax. As convenient shorthands, there are builtins for simple increment and decrement operations.

Decrement and increment operators

Increment and decrement of integers are supported using the builtins incr and decr:

incr(number)
decr(number)

which expand to the numerical value of number, incremented, or decremented, respectively, by one.

incr(4)
=>5
decr(7)
=>6

The builtin macros incr and decr are recognized only when given arguments.

Evaluating integer expressions

Integer expressions are evaluated with eval:

eval(expression, opt radix, opt width)

which expands to the value of expression.

Expressions can contain the following operators, listed in order of decreasing precedence.

-
Unary minus
**
Exponentiation
* / %
Multiplication, division and modulo
+ -
Addition and subtraction
<< >>
Shift left or right
== != > >= < <=
Relational operators
!
Logical negation
~
Bitwise negation
&
Bitwise and
^
Bitwise exclusive-or
|
Bitwise or
&&
Logical and
||
Logical or

All operators, except exponentiation, are left associative.

Note that many m4 implementations use `^' as an alternate operator for the exponentiation, while many others use `^' for the bitwise exclusive-or. GNU m4 changed its behavior: it used to exponentiate for `^', it now computes the bitwise exclusive-or.

Numbers without special prefix are given decimal. A simple `0' prefix introduces an octal number. `0x' introduces an hexadecimal number. `0b' introduces a binary number. `0r' introduces a number expressed in any radix between 1 and 36: the prefix should be immediately followed by the decimal expression of the radix, a colon, then the digits making the number. For any radix, the digits are `0', `1', `2', .... Beyond `9', the digits are `a', `b' ... up to `z'. Lower and upper case letters can be used interchangeably in numbers prefixes and as number digits.

Parentheses may be used to group subexpressions whenever needed. For the relational operators, a true relation returns 1, and a false relation return 0.

Here are a few examples of use of eval.

eval(-3 * 5)
=>-15
eval(index(`Hello world', `llo') >= 0)
=>1
define(`square', `eval(($1)**2)')
=>
square(9)
=>81
square(square(5)+1)
=>676
define(`foo', `666')
=>
eval(`foo'/6)
error-->51.eval:14: m4: Bad expression in eval: foo/6
=>
eval(foo/6)
=>111

As the second to last example shows, eval does not handle macro names, even if they expand to a valid expression (or part of a valid expression). Therefore all macros must be expanded before they are passed to eval.

If radix is specified, it specifies the radix to be used in the expansion. The default radix is 10. The result of eval is always taken to be signed. The width argument specifies a minimum output width. The result is zero-padded to extend the expansion to the requested width.

eval(666, 10)
=>666
eval(666, 11)
=>556
eval(666, 6)
=>3030
eval(666, 6, 10)
=>0000003030
eval(-666, 6, 10)
=>-000003030

Take note that radix cannot be larger than 36.

The builtin macro eval is recognized only when given arguments.

Running UNIX commands

There are a few builtin macros in m4 that allow you to run UNIX commands from within m4.

Executing simple commands

Any shell command can be executed, using syscmd:

syscmd(shell-command)

which executes shell-command as a shell command.

The expansion of syscmd is void, not the output from shell-command! Output or error messages from shell-command are not read by m4. See section Reading the output of commands if you need to process the command output.

Prior to executing the command, m4 flushes its output buffers. The default standard input, output and error of shell-command are the same as those of m4.

The builtin macro syscmd is recognized only when given arguments.

Reading the output of commands

If you want m4 to read the output of a UNIX command, use esyscmd:

esyscmd(shell-command)

which expands to the standard output of the shell command shell-command.

Prior to executing the command, m4 flushes its output buffers. The default standard input and error output of shell-command are the same as those of m4. The error output of shell-command is not a part of the expansion: it will appear along with the error output of m4.

Assume you are positioned into the `checks' directory of GNU m4 distribution, then:

define(`vice', `esyscmd(grep Vice ../COPYING)')
=>
vice
=>  Ty Coon, President of Vice
=>

Note how the expansion of esyscmd has a trailing newline.

The builtin macro esyscmd is recognized only when given arguments.

Exit codes

To see whether a shell command succeeded, use sysval:

sysval

which expands to the exit status of the last shell command run with syscmd or esyscmd.

syscmd(`false')
=>
ifelse(sysval, 0, zero, non-zero)
=>non-zero
syscmd(`true')
=>
sysval
=>0

Making names for temporary files

Commands specified to syscmd or esyscmd might need a temporary file, for output or for some other purpose. There is a builtin macro, maketemp, for making temporary file names:

maketemp(template)

which expands to a name of a non-existent file, made from the string template, which should end with the string `XXXXXX'. The six X's are then replaced, usually with something that includes the process id of the m4 process, in order to make the filename unique.

maketemp(`/tmp/fooXXXXXX')
=>/tmp/fooa07346
maketemp(`/tmp/fooXXXXXX')
=>/tmp/fooa07346

As seen in the example, several calls of maketemp might expand to the same string, since the selection criteria is whether the file exists or not. If a file has not been created before the next call, the two macro calls might expand to the same name.

The builtin macro maketemp is recognized only when given arguments.

Miscellaneous builtin macros

This chapter describes various builtins, that do not really belong in any of the previous chapters.

Printing error messages

You can print error messages using errprint:

errprint(message, ...)

which simply prints message and the rest of the arguments on the standard error output.

The expansion of errprint is void.

errprint(`Illegal arguments to forloop
')
error-->Illegal arguments to forloop
=>

A trailing newline is not printed automatically, so it must be supplied as part of the argument, as in the example. (BSD flavored m4's do append a trailing newline on each errprint call).

To make it possible to specify the location of the error, two utility builtins exist:

__file__
__line__

which expands to the quoted name of the current input file, and the current input line number in that file.

errprint(`m4:'__file__:__line__: `Input error
')
error-->m4:56.errprint:2: Input error
=>

Exiting from m4

If you need to exit from m4 before the entire input has been read, you can use m4exit:

m4exit(opt code)

which causes m4 to exit, with exit code code. If code is left out, the exit code is zero.

define(`fatal_error', `errprint(`m4: '__file__: __line__`: fatal error: $*
')m4exit(1)')
=>
fatal_error(`This is a BAD one, buster')
error-->m4: 57.m4exit: 5: fatal error: This is a BAD one, buster

After this macro call, m4 will exit with exit code 1. This macro is only intended for error exits, since the normal exit procedures are not followed, e.g., diverted text is not undiverted, and saved text (see section Saving input) is not reread.

Fast loading of frozen states

Some bigger m4 applications may be built over a common base containing hundreds of definitions and other costly initializations. Usually, the common base is kept in one or more declarative files, which files are listed on each m4 invocation prior to the user's input file, or else, include'd from this input file.

Reading the common base of a big application, over and over again, may be time consuming. GNU m4 offers some machinery to speed up the start of an application using lengthy common bases. Presume the user repeatedly uses:

m4 base.m4 input.m4

with a varying contents of `input.m4', but a rather fixed contents for `base.m4'. Then, the user might rather execute:

m4 -F base.m4f base.m4

once, and further execute, as often as needed:

m4 -R base.m4f input.m4

with the varying input. The first call, containing the -F option, only reads and executes file `base.m4', so defining various application macros and computing other initializations. Only once the input file `base.m4' has been completely processed, GNU m4 produces on `base.m4f' a frozen file, that is, a file which contains a kind of snapshot of the m4 internal state.

Later calls, containing the -R option, are able to reload the internal state of m4's memory, from `base.m4f', prior to reading any other input files. By this mean, instead of starting with a virgin copy of m4, input will be read after having effectively recovered the effect of a prior run. In our example, the effect is the same as if file `base.m4' has been read anew. However, this effect is achieved a lot faster.

Only one frozen file may be created or read in any one m4 invocation. It is not possible to recover two frozen files at once. However, frozen files may be updated incrementally, through using -R and -F options simultaneously. For example, if some care is taken, the command:

m4 file1.m4 file2.m4 file3.m4 file4.m4

could be broken down in the following sequence, accumulating the same output:

m4 -F file1.m4f file1.m4
m4 -R file1.m4f -F file2.m4f file2.m4
m4 -R file2.m4f -F file3.m4f file3.m4
m4 -R file3.m4f file4.m4

Some care is necessary because not every effort has been made for this to work in all cases. In particular, the trace attribute of macros is not handled, nor the current setting of changeword. Also, interactions for some options of m4 being used in one call and not for the next, have not been fully analyzed yet. On the other end, you may be confident that stacks of pushdef'ed definitions are handled correctly, so are undefine'd or renamed builtins, changed strings for quotes or comments.

When an m4 run is to be frozen, the automatic undiversion which takes place at end of execution is inhibited. Instead, all positively numbered diversions are saved into the frozen file. The active diversion number is also transmitted.

A frozen file to be reloaded need not reside in the current directory. It is looked up the same way as an include file (see section Searching for include files).

Frozen files are sharable across architectures. It is safe to write a frozen file one one machine and read it on another, given that the second machine uses the same, or a newer version of GNU m4. These are simple (editable) text files, made up of directives, each starting with a capital letter and ending with a newline (NL). Wherever a directive is expected, the character # introduces a comment line, empty lines are also ignored. In the following descriptions, lengths always refer to corresponding strings. Numbers are always expressed in decimal. The directives are:

V number NL
Confirms the format of the file. number should be 1.
C length1 , length2 NL string1 string2 NL
Uses string1 and string2 as the beginning comment and end comment strings.
Q length1 , length2 NL string1 string2 NL
Uses string1 and string2 as the beginning quote and end quote strings.
F length1 , length2 NL string1 string2 NL
Defines, through pushdef, a definition for string1 expanding to the function whose builtin name is string2.
T length1 , length2 NL string1 string2 NL
Defines, though pushdef, a definition for string1 expanding to the text given by string2.
D number, length NL string NL
Selects diversion number, making it current, then copy string in the current diversion. number may be a negative number for a non-existing diversion. To merely specify an active selection, use this command with an empty string. With 0 as the diversion number, string will be issued on standard output at reload time, however this may not be produced from within m4.

Compatibility with other versions of m4

This chapter describes the differences between this implementation of m4, and the implementation found under UNIX, notably System V, Release 3.

There are also differences in BSD flavors of m4. No attempt is made to summarize these here.

Extensions in GNU m4

This version of m4 contains a few facilities, that do not exist in System V m4. These extra facilities are all suppressed by using the `-G' command line option, unless overridden by other command line options.

  • In the $n notation for macro arguments, n can contain several digits, while the System V m4 only accepts one digit. This allows macros in GNU m4 to take any number of arguments, and not only nine (see section Arguments to macros).
  • Files included with include and sinclude are sought in a user specified search path, if they are not found in the working directory. The search path is specified by the `-I' option and the `M4PATH' environment variable (see section Searching for include files).
  • Arguments to undivert can be non-numeric, in which case the named file will be included uninterpreted in the output (see section Undiverting output).
  • Formatted output is supported through the format builtin, which is modeled after the C library function printf (see section Formatted output).
  • Searches and text substitution through regular expressions are supported by the regexp (see section Searching for regular expressions) and patsubst (see section Substituting text by regular expression) builtins.
  • The output of shell commands can be read into m4 with esyscmd (see section Reading the output of commands).
  • There is indirect access to any builtin macro with builtin (see section Indirect call of builtins).
  • Macros can be called indirectly through indir (see section Indirect call of macros).
  • The name of the current input file and the current input line number are accessible through the builtins __file__ and __line__ (see section Printing error messages).
  • The format of the output from dumpdef and macro tracing can be controlled with debugmode (see section Controlling debugging output).
  • The destination of trace and debug output can be controlled with debugfile (see section Saving debugging output).

In addition to the above extensions, GNU m4 implements the following command line options: `-F', `-G', `-I', `-L', `-R', `-V', `-W', `-d', `-l', `-o' and `-t'. See section Invoking m4, for a description of these options.

Also, the debugging and tracing facilities in GNU m4 are much more extensive than in most other versions of m4.

Facilities in System V m4 not in GNU m4

The version of m4 from System V contains a few facilities that have not been implemented in GNU m4 yet.

  • System V m4 supports multiple arguments to defn. This is not implemented in GNU m4. Its usefulness is unclear to me.

Other incompatibilities

There are a few other incompatibilities between this implementation of m4, and the System V version.

  • GNU m4 implements sync lines differently from System V m4, when text is being diverted. GNU m4 outputs the sync lines when the text is being diverted, and System V m4 when the diverted text is being brought back. The problem is which lines and filenames should be attached to text that is being, or has been, diverted. System V m4 regards all the diverted text as being generated by the source line containing the undivert call, whereas GNU m4 regards the diverted text as being generated at the time it is diverted. I expect the sync line option to be used mostly when using m4 as a front end to a compiler. If a diverted line causes a compiler error, the error messages should most probably refer to the place where the diversion were made, and not where it was inserted again.
  • GNU m4 makes no attempt at prohiting autoreferential definitions like:
    define(`x', `x')
define(`x', `x ')
    There is nothing inherently wrong with defining `x' to return `x'. The wrong thing is to expand `x' unquoted. In m4, one might use macros to hold strings, as we do for variables in other programming languages, further checking them with:
    ifelse(defn(`holder'), `value', ...)
    In cases like this one, an interdiction for a macro to hold its own name would be a useless limitation. Of course, this leave more rope for the GNU m4 user to hang himself! Rescanning hangs may be avoided through careful programming, a little like for endless loops in traditional programming languages.
  • GNU m4 without `-G' option will define the macro __gnu__ to expand to the empty string. On UNIX systems, GNU m4 without the `-G' option will define the macro __unix__, otherwise the macro unix. Both will expand to the empty string.

Concept index

Jump to: a - b - c - d - e - f - g - i - l - m - n - o - p - q - r - s - t - u - w

a

  • Arguments to macros
  • arguments to macros
  • arguments to macros, special
  • arguments, quoted macro
  • arithmetic

    • b

  • builtins, indirect call of

    • c

  • call of builtins, indirect
  • call of macros, indirect
  • changing comment delimiters
  • changing the quote delimiters
  • characters, translating
  • command line, filenames on the
  • command line, macro definitions on the
  • command line, options
  • commands, exit code from UNIX
  • commands, running UNIX
  • comment delimiters, changing
  • comments
  • comments, copied to output
  • comparing strings
  • compatibility
  • conditionals
  • controlling debugging output
  • counting loops

    • d

  • debugging output, controlling
  • debugging output, saving
  • decrement operator
  • defining new macros
  • definitions, displaying macro
  • deleting macros
  • deleting whitespace in input
  • discarding diverted text
  • displaying macro definitions
  • diversion numbers
  • diverted text, discarding
  • diverting output to files
  • dumping into frozen file

    • e

  • error messages, printing
  • evaluation, of integer expressions
  • executing UNIX commands
  • exit code from UNIX commands
  • exiting from m4
  • expansion of macros
  • expansion, tracing macro
  • expressions, evaluation of integer
  • extracting substrings

    • f

  • fast loading of frozen files
  • file inclusion, file inclusion
  • filenames, on the command line
  • files, diverting output to
  • files, names of temporary
  • forloops
  • formatted output
  • frozen files for fast loading

    • g

  • GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions, GNU extensions

    • i

  • included files, search path for
  • inclusion, of files, inclusion, of files
  • increment operator
  • indirect call of builtins
  • indirect call of macros
  • initialization, frozen states
  • input tokens
  • input, saving
  • integer arithmetic
  • integer expression evaluation

    • l

  • length of strings
  • lexical structure of words
  • loops
  • loops, counting

    • m

  • macro definitions, on the command line
  • macro expansion, tracing
  • macro invocation
  • macros, arguments to, macros, arguments to
  • macros, displaying definitions
  • macros, expansion of
  • macros, how to define new
  • macros, how to delete
  • macros, how to rename
  • macros, indirect call of
  • macros, quoted arguments to
  • macros, recursive
  • macros, special arguments to
  • macros, temporary redefinition of
  • messages, printing error
  • multibranches

    • n

  • names

    • o

  • options, command line
  • output, diverting to files
  • output, formatted
  • output, saving debugging

    • p

  • pattern substitution
  • printing error messages

    • q

  • quote delimiters, changing the
  • quoted macro arguments
  • quoted string

    • r

  • recursive macros
  • redefinition of macros, temporary
  • regular expressions, regular expressions
  • reloading a frozen file
  • renaming macros
  • running UNIX commands

    • s

  • saving debugging output
  • saving input
  • search path for included files
  • special arguments to macros
  • strings, length of
  • substitution by regular expression
  • substrings, extracting

    • t

  • temporary filenames
  • temporary redefinition of macros
  • tokens
  • tracing macro expansion
  • translating characters

    • u

  • undefining macros
  • UNIX commands, exit code from
  • UNIX commands, running

    • w

  • words, lexical structure of

    • Macro index

    References are exclusively to the places where a builtin is introduced the first time. Names starting and ending with `__' have these characters removed in the index.

    Jump to: b - c - d - e - f - g - i - l - m - p - r - s - t - u

    b

  • builtin

    • c

  • changecom
  • changequote
  • changeword

    • d

  • debugfile
  • debugmode
  • decr
  • define
  • defn
  • divert
  • divnum
  • dnl
  • dumpdef

    • e

  • errprint
  • esyscmd
  • eval

    • f

  • file
  • format

    • g

  • gnu

    • i

  • ifdef
  • ifelse
  • include
  • incr
  • index
  • indir

    • l

  • len
  • line

    • m

  • m4exit
  • m4wrap
  • maketemp

    • p

  • patsubst
  • popdef
  • pushdef

    • r

  • regexp

    • s

  • shift
  • sinclude
  • substr
  • syscmd
  • sysval

    • t

  • traceoff
  • traceon
  • translit

    • u

  • undefine
  • undivert
  • unix

    • This document was generated on 7 November 1998 using the texi2html translator version 1.52.


mailutils, Programming Manual

mailutils, SDK.

version 0.0.9b, 14 October 2001

Alain Magloire et al.

Table of Contents

  • Introduction
    • References
  • Concrete API
    • POP3
      • Commands
        • Initialization
        • Carrier
        • Apop
        • Capa
        • Dele
        • List
        • Noop
        • Pass
        • Quit
        • Retr
        • Rset
        • Stat
        • Top
        • Uidl
        • User
        • Help functions
        • Timeout
    • IMAP4
      • Commands
        • Initialization
        • Append
        • Capability
        • Create
        • Check
        • Close
        • Copy
        • UID Copy
        • Delete
        • Fetch
        • UID Fetch
        • Examine
        • Expunge
        • List
        • Lsub
        • Namespace
        • Rename
        • Search
        • UID Search
        • Select
        • Status
        • Store
        • UID Store
        • Subscribe
        • Unsubscribe
    • Mbox
        • Initialization
        • Carrier
    • Mh
    • Maildir
    • SMTP
      • Commands
        • Initialization
        • Data
        • Helo
        • Expn
        • Help
        • Mail From
        • Noop
        • Quit
        • Recpt To
        • Reset
        • Verify
        • Help functions
    • Sendmail
    • NNTP
      • Commands
        • Initialization
        • Article
        • Body
        • Group
        • Head
        • Help
        • IHave
        • Last
        • List
        • NewGroups
        • NewNews
        • Next
        • Post
        • Quit
        • Slave
        • Stat
    • Parse822
  • Framework
    • Folder
    • Mailbox
    • Mailer
    • Message
    • Envelope
    • Headers
    • Body
    • Attribute
    • Stream
    • Iterator
    • Authenticator
    • Address
    • Example
    • Locker
    • URL
      • POP3
      • IMAP
      • File
      • Mailto
      • URL functions
    • Example
  • Programs
    • IMAP4 daemon
    • POP3 daemon
    • frm -- List headers from a mailbox.
    • mail -- send and receive mail.
      • Command line options
      • How to specify message sets
      • Composing mail
        • Quitting Compose Mode
        • Getting Help on Compose Escapes: ~?
        • Editing the Message: ~e and ~v.
        • Modifying the Headers: ~h, ~t, ~c, ~b, ~s
        • Enclosing Another Message: ~m and ~M
        • Adding a File to the Message: ~r and ~d
        • Printing And Saving the Message
        • Signing the Message: ~a and ~A
        • Printing Another Message: ~f and ~F
        • Inserting Value of a Mail Variable: ~i
        • Executing Other Mail Commands: ~: and ~-
        • Executing Shell Commands: ~! and ~|
      • Reading mail
        • Quitting the program
        • Obtaining online help
        • Moving within a mailbox
        • Changing mailbox/directory
        • Controlling header display
        • Displaying information
        • Displaying messages
        • Marking messages
        • Disposing of messages
        • Saving messages
        • Editing messages
        • Scripting
        • Aliasing
        • Replying
        • Incorporating new mail
        • Shell escapes
      • How to alter the behavior of mail
      • Personal and system-wide configuration files
    • messages -- Count the number of messages in a mailbox.
    • readmsg -- Extract messages from a folder.
    • sieve
    • guimb -- A mailbox scanning and processing language.
      • Specifying Scheme Program to Execute
      • Specifying Mailboxes to Operate Upon
      • Passing Options to Scheme
      • Guimb Invocation Summary
      • Scheme Procedures and Variables
        • Address Functions
        • Mailbox Functions
        • Message Functions
        • MIME Functions
        • Log Functions
  • Reporting Bugs
  • Acknowledgement
  • Concept Index
  • Index

Introduction

GNU MAILUTILS offers a general purpose library whose aim is to provide a rich set of functions for accessing different mailbox formats and mailers.

References

For more information on,

  • SMTP
    • RFC 2821: Simple Mail Transfer Protocol
    • RFC 2368: The mailto URL scheme
  • POP3
    • RFC 1939: Post Office Protocol - Version 3
    • RFC 1734: POP3 AUTHentication command
    • RFC 1957: Some Observations on Implementations of the Post Office Protocol (POP3)
    • RFC 2449: POP3 Extension Mechanism
    • RFC 2384: POP URL Scheme
  • IMAP4
    • RFC 2060: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
    • RFC 2088: IMAP4 non-synchronizing literals
    • RFC 2193: IMAP4 Mailbox Referrals
    • RFC 2221: IMAP4 Login Referrals
    • RFC 2342: IMAP4 Namespace
    • RFC 2192: IMAP URL Scheme
    • RFC 1731: IMAP4 Authentication Mechanisms
    • RFC 2245: Anonymous SASL Mechanism
  • message formats
    • RFC 2822: Internet Message Format
    • RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies
    • RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
    • RFC 2047: Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text
    • RFC 2049: Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples
    • RFC 2111: Content-ID and Message-ID Uniform Resource Locators
  • miscellaneous related topics
    • RFC 3028: Sieve: A Mail Filtering Language
    • RFC 2298: An Extensible Message Format for Message Disposition Notifications
    • RFC 1738: Uniform Resource Locators (URL)
    • Internet Email Protocols: A Developer's Guide, by Kevin Johnson

Concrete API

POP3

/* Prefix pop3_ is reserved */
#include <mailutils/pop3.h>

The purpose of the Post Office Protocol Version 3 (POP3) is to permit a client to download a maildrop from a remote server. It does not provide complex or extensive operation on the maildrop. When the client successfully authenticates, the server acquires an exclusive access lock on the mailbox and holds it the entire duration of the session. After the authentication, the session enters transaction state and the client may issues commands to access messages in the mailbox.

  • Authorization state @itemize @bullet @item User @item Pass @item Quit @item Capa (extension) @item Auth (extension) @end itemize
  • Transaction state @itemize @bullet @item Stat @item List @item Retr @item Dele @item Noop @item Rset @item Top @item Uidl (extension) @item Quit @item Capa (extension) @end itemize

When the command Quit is issue the session enters the update state. The servers removes all messages marked deleted, releases the exclusive lock and closes the TCP connection.

Commands

An opaque structure pop3_t is use as a handle for the session, it is allocated and initialized by calling pop3_create (). All Functions will wait for a reply from the POP3 server before returning. The duration of the wait can be set by calling pop3_set_timeout (), the default is 10 minutes(1). Once a successful connection is established with pop3_connect (), two builtins authentications are provided pop3_apop () or pop3_user ()/pop3_pass (). The pop3_stat () and pop3_list () functions can be use to get the number and size of messages. Downloading of messages is done via a stream provided by pop3_retr () or pop3_top () (2). The stream_t should be destroyed to indicate to the library that the action is finished. POP3 only provide a single channel for operation, it means only one operation can be done at a time, all the functions will return MU_ERROR_OPERATION_IN_PROGRESS if call during another operation. The functions pop3_list_all (), pop3_uidl_all () and pop3_capa () return iterators pop3_list_current (), pop3_uidl_current () are provided as cover function to format the string return by iterator_current (), iterator_destroy () must be call to release any resources.

In a multithreaded application, only one thread should access pop3_t handles.

Initialization

Function: int pop3_create (pop3_t * pop3)

Allocate and initialize a pop3 handle.

MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER

Function: void pop3_destroy (pop3_t *pop3)

When a POP3 session is finished, the structure must be free ()'ed to reclaim memory.

Function: int pop3_connect (pop3_t, const char *host, unsigned port, int flags)

A connection is established by calling pop3d_open (), the previous connection is close first. If non-blocking the function should be recalled until the return value is not MU_ERROR_TRY_AGAIN or MU_ERROR_IN_PROGRESS.

MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_IN_PROGRESS
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
MU_ERROR_TIMEOUT
MU_ERROR_NO_LOCK

Carrier

Function: int pop3_set_carrier (pop3_t, stream_t carrier);

The type of stream use to contact as server will be set to carrier in the pop3_t handle. Any previous carrier stream in the handle, will be close and release.

MU_ERROR_INVALID_PARAMETER

Function: int pop3_get_carrier (pop3_t, stream_t *carrier);

Return the pop3_t carrier. If none was set, a new tcp stream will be created.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Apop

Function: int pop3_apop (pop3_t, const char *user, const char *secret)

Apop offers an alternative to User/Pass authentication. For intermittent use of POP3, like checking for new mail, it is the preferred the authentication. It reduces the risk of password capture. The user and the shared secret are pass to pop3_apop (), the MD5 digest is calculated by applying the times tamp given by the server in the greeting followed by the secret.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Capa

Function: int pop3_capa (pop3_t, pop3_capa_iterator_t *iterator)

The Capa command is send to the sever and the list of capabilities is return in an iterator. iterator_current () gives an allocated string that should be free ()'ed. Caution: The iterator must be destroy after use, it will discard any remaining responses from CAPA and clear the way for new operations.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>

void print_capabilities (pop3_t pop3)
{
   iterator_t iterator;
   status = pop3_capa (pop3, &iterator);
   if (status == 0)
    {
        for (iterator_first (iterator);
             !iterator_is_done (iterator);
             iterator_next (iterator))
          {
              char *capa;
              if (iterator_current (iterator, &capa) == 0)
               {;
                   printf ("CAPA: %s\n", capa);
                   free (capa);
               }
          }
        pop3_capa_destroy (&iterator);
    }
   else
     printf ("NONE\n");
}

Dele

Function: int pop3_dele (pop3_t, unsigned msgno)

Sends a Dele to the servers who will mark the msgno for deletion. The msgno may not refer to a message already marked deleted. If successful any future reference to msgno in other operations will be an error, unless unmarked by RSET.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

List

Function: int pop3_list (pop3_t, unsigned msgno, size_t *size)

Sends a List for a specific msgno and returns the size.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_list_all (pop3_t, iterator_t *iterator)

Sends A List with no argument to the server. The iterator must be destroy after use, it will discard any remaining response from LIST and clear the way for new operations. A cover function pop3_list_current () around to scan properly the string return by the iterator_current ().

#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>

void print_list (pop3_t pop3)
{
   iterator_t iterator;
   status = pop3_list_all (pop3, &iterator);
   if (status == 0)
    {
        for (iterator_first (iterator);
             !iterator_is_done (iterator);
             iterator_next (iterator))
          {
              unsigned int msgno, size;
              if (pop3_list_current (iterator, &msgno, &size) == 0)
               {
                   printf ("LIST: %d %d\n", msgno, size);
               }
          }
        iterator (&iterator);
    }
   else
     printf ("NONE\n");
}
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_list_current (pop3_t, unsigned int *msgno, size_t *size)

Cover functions around iterator_current () from an iterator created by pop3_list_all () to format the result.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Noop

Function: int pop3_noop (pop3_t)

Sends a NOOP, useful to reset the timeout on the server.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Pass

Function: int pop3_pass (pop3_t, const char *passwd)

Sends the PASS, to authenticate after the USER command.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Quit

Function: int pop3_quit (pop3_t)

Enter the UPDATE state. The server will delete all messages marked deleted before closing the connection.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Retr

Function: int pop3_retr (pop3_t, unsigned msgno, stream_t *)

If successful a stream_t is created to allow downloading of the message, byte-stuff lines or handle internally, CRLFs are converted to LF. All other operations will fail until the stream is destroyed by the caller.

#include <stdio.h>
#include <mailutils/pop3.h>

int
print_message (pop3_t pop3, unsigned int msgno)
{
   stream_t stream;
   int status = pop3_retr (pop3, msgno, &stream);
   if (status == 0)
    {
       size_t n = 0;
       char buf[128];
       while ((stream_readline (stream, buf, sizeof buf, &n) == 0)
              && n)
         printf ("%s", buf);
       stream_release (stream);
    }
   return status;
}
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Rset

Function: int pop3_rset (pop3_t)

Sends a RSET to unmark the messages marked as deleted.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Stat

Function: int pop3_stat (pop3_t, unsigned msgno, unsigned *msg_count, size_t *size)

The number of messages in the mailbox and the size of the mailbox in octets. Caution: The size is in RFC822 where line termination is CRLF, messages marked as deleted are not counted in either total.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Top

Function: int pop3_top (pop3_t, unsigned int msgno, unsigned int lines, stream_t *stream)

If successful a stream is created to allow downloading of the header, byte-stuff lines or handle internally, CRLFs are converted to LF. All other operations will failed until the stream is destroyed by the caller.

#include <stdio.h>
#include <mailutils/pop3.h>

int
print_top (pop3_t pop3, unsigned int msgno, unsigned int lines)
{
    stream_t stream;
    int status = pop3_top (pop3, msgno, lines, &stream);
    if (status == 0)
     {
        size_t n = 0;
        char buf[128];
        while ((stream_readline (stream, buf, sizeof buf, &n) == 0)
               && n)
          printf ("%s", buf);
        stream_release (stream);
     }
  return status;
}
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Uidl

Function: int pop3_uidl (pop3_t, unsigned int msgno, char **uidl)

The Uniq Identifier is return in uidl, the string must be free ()'ed, by the caller.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_uidl_all (pop3_t, iterator_t * iterator)

An iterator object is return to iterate through the response and must be destroyed by the caller.

#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>

void print_uidl (pop3_t pop3)
{
   iterator_t iterator;
   status = pop3_uidl_all (pop3, &iterator);
   if (status == 0)
    {
        for (iterator_first (iterator);
             !iterator_is_done (iterator);
             iterator_next (iterator))
          {
              unsigned int msgno;
              char *uidl;
              if (pop3_uidl_current (iterator, &msgno, &uidl) == 0)
               {
                   printf ("LIST: %d %s\n", msgno, uidl);
                   free (uidl);
               }
          }
        iterator (&iterator);
    }
   else
     printf ("NONE\n");
}
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_uidl_current (iterator_t iterator, unsigned int *msgno, char **uidl)

Cover functions around iterator_current () from an iterator created by pop3_uidl_all () to format the result. The variable uidl should be free ()'ed.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

User

Function: int pop3_user (pop3_t, const char *user)

Sends the User command.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Help functions

Function: int pop3_writeline (pop3_t, const char *format, ...);

Copy in the internal buffer of pop3_t the string, pop3_send () should be called later to flush the string to the POP3 server.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_sendline (pop3_t, const char *cmd);

Cover function for pop3_writeline () and pop3_send ().

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_send (pop3_t, const char *cmd);

Flushes out the strings written by pop3_writeline () in the internal buffer to the channel.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_response (pop3_t, char *buffer, size_t len, size_t *plen)

The last response from the last command is save and can be examine after a failure or success.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Timeout

Function: int pop3_set_timeout (pop3_t, int timeout)

Set the timeout time for I/O on the carrier. The default is 10 minutes. The timeout is given in milliseconds.

Function: int pop3_get_timeout (pop3_t, int *timeout)

Get the timeout time for I/O on the carrier. The timeout is given in milliseconds.

IMAP4

/* Prefix imap4_ is reserved */
#include <mailutils/imap4.h>

Internet Message Access Protocol - Version (4rev1). Not implemented.

Commands

Initialization

Function: int imap4_create (imap4_t *)

Function: int imap4_open (imap4_t, const char *hostname, unsigned int port, int flags)

Function: int imap4d_set_timeout (imap4_t, unsigned int seconds)

Append

Function: int imap4_append (imap4_t)

Capability

Function: int imap4_capability (imap4_t)

Create

Function: int imap4_create_mailbox (imap4_t, const char *mbox)

Check

Function: int imap4_check (imap4_t)

Close

Function: int imap4_close (imap4_t)

Copy

Function: int imap4_copy (imap4_t)

UID Copy

Function: int imap4_uid_copy (imap4_t)

Delete

Function: int imap4_delete (imap4_t)

Fetch

Function: int imap4_fetch (imap4_t)

UID Fetch

Function: int imap4_uid_fetch (imap4_t)

Examine

Function: int imap4_examine (imap4_t)

Expunge

Function: int imap4_expunge (imap4_t)

List

Function: int imap4_list (imap4_t)

Lsub

Function: int imap4_lsub (imap4_t)

Namespace

Function: int imap4_namespace (imap4_t)

Rename

Function: int imap4_rename (imap4_t)

Search

Function: int imap4_search (imap4_t)

UID Search

Function: int imap4_uid_search (imap4_t)

Select

Function: int imap4_select (imap4_t)

Status

Function: int imap4_status (imap4_t)

Store

Function: int imap4_store (imap4_t)

UID Store

Function: int imap4_uid_store (imap4_t)

Subscribe

Function: int imap4_subscribe (imap4_t)

Unsubscribe

Function: int imap4_unsubscribe (imap4_t)

Mbox

/* Prefix mbox_ is reserved */
#include <mailutils/mbox.h>

The most common mailbox format on UNIX platform is mbox. Mbox file is messages separated by the special format string.

   From SP envelope-sender SP date [SP moreinfo]
"From "
is sometimes call the From_.
envelope-sender
is a word with no space.
date
has the same format as asctime ()
moreinfo
are optional values that are seldom used.

A mbox_t is created, initialized and destroyed by mbox_create () and mbox_destroy (). When opening, mbox_open () will do a quick check to see if the format is a valid format or an empty file. The scanning of the mailbox is done by mbox_scan (). The function, mbox_scan (), takes callback functions called during the scanning to provide information. The scanning will cache some of the headers fields for speed. Closing the mailbox, mbox_close () will free any resources like, headers cache, locks etc ... All the messages with attributes marked deleted will only be removed on mbox_expunge (). If only the attributes need to be save but the messages not removed, this can be done by mbox_save_attributes (). New messages are added with mbox_append (). Attributes are saved in the Status: header field, Read is 'R', Seen is 'O', Deleted is 'd' and Reply is 'r'.

Initialization

Function: int mbox_create (mbox_t *mbox)

Allocate and initialize a mbox handle.

MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER

Function: void mbox_destroy (mbox_t mbox)

When a POP3 session is finished, the structure must be free ()'ed to reclaim memory.

Carrier

Function: int mbox_set_carrier (mbox_t, stream_t carrier);

Another type of stream can be provided to work on, the carrier is set in the mbox_t handle. Any previous carrier stream in the handle, will be close and release. Since the parsing code maintain only the offsets off the message the carrier stream must be seekable.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_get_carrier (mbox_t, stream_t *carrier);

Return the mbox_t carrier. If none was set, a new file stream will be created.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function: int mbox_open (mbox_t, const char *filename, int flags)

Open carrier stream with filename and flags. The stream will be quickly examine to see if it is a mbox format.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
MU_ERROR_NO_ENTRY
MU_ERROR_NO_ACCESS
MU_ERROR_NOT_SUPPORTED

Function: int mbox_close (mbox_t)

Close the carrier stream and resources particular to the mailbox.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function: int mbox_uidnext (mbox_t, unsigned long *uidnext)

Return the uidnext, if the mbox_t was not scan mbox_scan () is called first.

MU_ERROR_INVALID_PARAMETER
same as mbox_scan ()

Function: int mbox_uidvalidity (mbox_t, unsigned long *uidvalidity)

Return the uidvalidity, if the mbox_t was not scan mbox_scan () is called first.

MU_ERROR_INVALID_PARAMETER
same as mbox_scan ()

Function: int mbox_get_attribute (mbox_t, unsigned int msgno, attribute_t *attribute)

Return an attribute to indicate the status of message number msgno.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function: int mbox_get_separator (mbox_t, unsigned int msgno, char **sep)

Return an allocated string in sep containing the value "From " separating each message in Unix mbox format. The string should be free ()ed by the caller.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function: int mbox_set_separator (mbox_t, unsigned int msgno, const char *sep)

The variable sep should contain a valid "From " separator that will be use when the expunging.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function: int mbox_get_hstream (mbox_t, unsigned int msgno, stream_t *stream)

Return a stream to read the header of message msgno. The stream should be destroy after usage.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function: int mbox_set_hstream (mbox_t, unsigned int msgno, stream_t stream)

Use stream when expunging for message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_hsize (mbox_t, unsigned int msgno, unsigned int *size)

Return the size of message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_hlines (mbox_t, unsigned int msgno, unsigned int *size)

Return the number of lines of message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_get_bstream (mbox_t, unsigned int msgno, stream_t *stream)

Return a stream to read the body of message msgno. The stream should be destroy after usage.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function: int mbox_set_bstream (mbox_t, unsigned int msgno, stream_t stream)

Use stream when expunging for message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_bsize (mbox_t, unsigned int msgno, unsigned int *size)

Return the size of message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_blines (mbox_t, unsigned int msgno, unsigned int *size)

Return the number of lines of message msgno.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_get_size (mbox_t, unsigned int *size)

Return the size of mailbox.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_save (mbox_t)

Save the changes to the messages back to the mailbox, but do not remove messages mark for deletion in the process.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_mak_deleted (mbox_t, unsigned int msgno)

Mark msgno for deletion.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_unmak_deleted (mbox_t, unsigned int msgno)

Unmark msgno if it was marked for deletion.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_expunge (mbox_t)

Save the changes to the mailbox and in the process remove all messages marked for deletion.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_append (mbox_t, const char *sep, stream_t stream)

Append to the mailbox an rfc822 message represented by stream. The variable sep should contain a valid "From " separator or NULL to get the default.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_append_hb (mbox_t, const char *sep, stream_t hstream, stream_t bstream)

Append to the mailbox an rfc822 message represented by a header, hstream, and a body, bstream. The variable sep should contain a valid "From " separator or NULL to get the default.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_scan (mbox_t, unsigned int start, unsigned int *count)

Start scanning the mailbox for new messages. The variable start can be a message number starting point. The result of the scanning will be in count. The scanning will trigger the mbox_newmsg_cb() callback for each new message and mbox_progress_cb () at different interval to notify progression. The return values of the those callback should be 0 is different then 0 the scanning will be stop an the function returns MU_ERROR_INTERRUPTED.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_INTERRUPTED
MU_ERROR_NO_MEMORY

Function: int mbox_set_progress_cb (mbox_t, int (*callback) (int, void *)), void *arg)

Set the callback function for progress. The variable arg will be pass back in the callback as the second argument.

MU_ERROR_INVALID_PARAMETER

Function: int mbox_set_newmsg_cb (mbox_t, int (*callback) (int, void *)), void *arg)

Set the callback function for new messages. The variable arg will be pass back in the callback as the second argument.

MU_ERROR_INVALID_PARAMETER

Mh

/* Prefix mh_ is reserved */
#include <mailutils/mh.h>

Mail Handler mailbox format. Not implemented.

Maildir

/* Prefix maildir_ is reserved */
#include <mailutils/maildir.h>

QMail mailbox format. Not implemented.

SMTP

/* Prefix smtp_ is reserved */
#include <mailutils/smtp.h>

Simple Mail Transfer Protocol. Not implemented.

Commands

Initialization

Function: int smtp_create (smtp_t *)

Function: void smtp_destroy (smtp_t *)

Function: int smtp_open (smtp_t, const char *host, unsigned int port, int flags)

Data

Function: int smtp_data (smtp_t, stream_t stream)

Helo

Function: int smtp_helo (smtp_t, const char *domain)

Function: int smtp_ehlo (smtp_t, const char *domain)

Expn

Function: int smtp_expn (smtp_t, const char *list, iterator_t *)

Help

Function: int smtp_help (smtp_t, const char *help, iterator_t *)

Mail From

Function: int smtp_mail_from (smtp_t, const char *address, const char *param)

Noop

Function: int smtp_noop (smtp_t)

Quit

Function: int smtp_quit (smtp_t)

Recpt To

Function: int smtp_rcpt_to (smtp_t, const char *address, const char *param)

Reset

Function: int smtp_reset (smtp_t)

Verify

Function: int smtp_verify (smtp_t, const char *user)

Help functions

Function: extern int smtp_readline (smtp_t, char *buffer, size_t len, size_t *len)

Function: extern int smtp_response (smtp_t, char *buffer, size_t len, size_t *len)

Function: extern int smtp_writeline (smtp_t, const char *format, ...)

Function: extern int smtp_sendline (smtp_t, const char *line)

Function: extern int smtp_send (smtp_t

Sendmail

/* Prefix sendmail_ is reserved */
#include <mailutils/sendmail.h>

Spawning Sendmail daemon to deliver mail. Not implemented.

NNTP

/* Prefix nntp_ is reserved */
#include <mailutils/nntp.h>

Network News Transfer Protocol. Not implemented.

Commands

Initialization

Function: int nntp_create (nnpt_t *)

Function: int nntp_destroy (nnpt_t *)

Function: int nntp_open (nnpt_t)

Article

Function: int nntp_article (nnpt_t)

Body

Function: int nntp_body (nntp_t)

Group

Function: int nntp_group (nntp_t)

Head

Function: int nntp_head (nntp_t)

Help

Function: int nntp_help (nntp_t)

IHave

Function: int nntp_ihave (nntp_t)

Last

Function: int nntp_last (nntp_t)

List

Function: int nntp_list (nntp_t)

NewGroups

Function: int nntp_newgroups (nntp_t)

NewNews

Function: int nntp_newnews (nntp_t)

Next

Function: int nntp_next (nntp_t)

Post

Function: int nntp_post (nntp_t)

Quit

Function: int nntp_quit (nntp_t)

Slave

Function: int nntp_slave (nntp_t)

Stat

Function: int nntp_stat (nntp_t)

Parse822

/* Prefix parse822_ is reserved */
#include <mailutils/parse822.h>

Internet Message Format, see Address node for the discussion.

Function: int parse822_address_list (address_t* a, const char* s)

Function: int parse822_mail_box (const char** p, const char* e, address_t* a)

Function: int parse822_group (const char** p, const char* e, address_t* a)

Function: int parse822_address (const char** p, const char* e, address_t* a)

Function: int parse822_route_addr (const char** p, const char* e, address_t* a)

Function: int parse822_route (const char** p, const char* e, char** route)

Function: int parse822_addr_spec (const char** p, const char* e, address_t* a)

Function: int parse822_unix_mbox (const char** p, const char* e, address_t* a)

Function: int parse822_local_part (const char** p, const char* e, char** local_part)

Function: int parse822_domain (const char** p, const char* e, char** domain)

Function: int parse822_sub_domain (const char** p, const char* e, char** sub_domain)

Function: int parse822_domain_ref (const char** p, const char* e, char** domain_ref)

Function: int parse822_domain_literal (const char** p, const char* e, char** domain_literal)

Function: int parse822_quote_string (char** quoted, const char* raw)

Function: int parse822_quote_local_part (char** quoted, const char* raw)

Function: int parse822_field_body (const char** p, const char *e, char** fieldbody)

Function: int parse822_field_name (const char** p, const char *e, char** fieldname)

Framework

Wherever the mail is and whatever format it is stored in, the same operations to manipulate emails are common. To unified the C API, GNU mailutils offers a heteroclite set of objects that work in aggregation to do operations on emails. Each object do a specific task and delegates non related tasks to others. The object comes alive by specifying a URL parameter when created, it will indicate the storage format or protocol (POP3, IMAP4, MH, MAILDIR, etc ..).

                          folder_t                  url_t
  -/var/mail-    +- .. ->+-----------------+   +-->+------------+
 (  alain *-)-+  |       |   url_t       *-|---+   |   port     |
  ----------- |  |       |-----------------|       |   hostname |
 (  jakob *-)-+--+       |   auth_t      *-|---+   |   file     |
  ----------- |          |-----------------|   |   |   ...      |
 (  jeff  *-)-+          |   stream_t      |   |   +------------+
  ----------- |          |-----------------|   |
 (  shaleh*-)-+          |   .....         |   |    auth_t
  ----------             |-----------------|   +-->+------------+
                     +---|-* mailbox_t[]   |       |   ticket_t |
  mailbox_t          |   +-----------------+       +------------+
 +----------------+<-+
 |   locker_t  *--|-------------+
 |----------------|             |
 |   url_t        |             |          locker_t
 |----------------|             +-------->+---------+
 |   stream_t     |                       | lock    |
 |----------------|                       | unlock  |
 |  message_t[] *-|-------+               +---------+
 +----------------+       |                     envelope_t
                          |          +-------->+-----------+
  message_t               |          |         | date      |
 +----------------+<------+          |         | from      |
 |   envelope_t *-|------------------+         | to        |
 |----------------|              header_t      +-----------+
 |   header_t   *-|------------>+--------------+
 |----------------|             |   stream_t   |
 |   body_t     *-|----+        +--------------+
 +----------------+    |    body_t
                       +-->+--------------+
                           |   stream_t   |
                           +--------------+

For example writing a simple from command that will list the From and Subject headers of every mail in a mailbox.

/* sfrom, Simple From */
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <string.h>
#include <mailutils/registrar.h>
#include <mailutils/list.h>
#include <mailutils/mailbox.h>

#define BUFFER_SIZE 64
int
main (int argc, const char **argv)
{
   char from[BUFFER_SIZE];
   char subject[BUFFER_SIZE];
   char *mail;
   mailbox_t mbox;
   int status
   size_t msgno, total = 0;

   mail = (argc == 2) ? argv[1] : getenv ("MAIL");

   /* Register the type of mailbox. IMAP4, POP3 and local format  */
   {
       list_t registrar;
       registrar_get_list (&registrar);
       list_append (registrar, imap_record);
       list_append (registrar, path_record);
       list_append (registrar, pop_record);
   }

   status = mailbox_create (&mbox, mail);
   if (status != 0)
     {
        fprintf (stderr, "mailbox_create: %s\n", strerror (status));
        exit (EXIT_FAILURE);
     }

   status = mailbox_open (mbox, MU_STREAM_READ);
   if (status != 0)
     {
        fprintf (stderr, "mailbox_open: %s\n", strerror (status));
        exit (EXIT_FAILURE);
     }

   mailbox_messages_count (mbox, &total);

   for (msgno = 1; msgno <= total; msgno++)
      {
         message_t msg;
         header_t hdr;

         if ((status = mailbox_get_message (mbox, msgno, &msg)) != 0
             || (status = message_get_header (msg, &hdr)) != 0)
           {
               fprintf (stderr, "Error message:%s\n",
                        strerror (status));
               exit (EXIT_FAILURE);
           }

         status = header_get_value (hdr, MU_HEADER_FROM, from,
                                    sizeof (from), NULL);
         if (status != 0)
            strcpy (from, "(NO FROM)");

         status = header_get_value (hdr, MU_HEADER_SUBJECT, subject,
                                    sizeof (subject), NULL);
         if (status != 0)
            strcpy (subject, "(NO SUBJECT)");

         printf ("%s\t%s\n", from, subject);
      }

    mailbox_close (mbox);
    mailbox_destroy (&mbox);
    return 0;
}

% MAIL=pop://alain@localhost ./sfrom
Passwd: xxxx
Jim Meyering <meyering@foo.org>      fetish(shellutils) beta
Fran@,{c}ois Pinard <pinard@bar.org> recode new alpha
...

Folder

/* Prefix folder_ is reserve */
#include <mailutils/folder.h>

                             folder_t                  url_t
  -/var/mail-    +---//---->/-----------------\    +-->/-----------\
 (  alain *-)-+  |          |  url_t        *-|----+   |  port     |
  ----------- |  |          |-----------------+        |  hostname |
 (  jakob *-)-+--+          |  observer_t   *-|        |  file     |
  ----------- |             |-----------------+        |  ...      |
 (  jeff  *-)-+             |  stream_t       |        \-----------/
  ----------- |             |-----------------|
 (  sean  *-)-+             |  auth_t         |
  ----------                |-----------------|
                            |  mailbox_t(1)   |
                            |-----------------|
                            |  mailbox_t(2)   |
                            |  ......         |
                            |  mailbox_t(n)   |
                            \-----------------/

Function: int folder_create (folder_t *, const char *url)

Function: void folder_destroy (folder_t *)

Function: int folder_open (folder_t, int flag)

Function: int folder_close (folder_t)

Function: int folder_delete (folder_t, const char *mailbox)

Function: int folder_rename (folder_t, const char *, const char *mailbox)

Function: int folder_subscribe (folder_t, const char *mailbox)

Function: int folder_unsubscribe (folder_t, const char *mailbox)

Function: int folder_list (folder_t, const char *ref, const char *wcard, iterator_t *)

Function: int folder_lsub (folder_t, const char *ref, const char *wcar, iterator_t *)

Function: int folder_get_stream (folder_t, stream_t *)

Function: int folder_set_stream (folder_t, stream_t)

Function: int folder_get_observable (folder_t, observable_t *)

Function: int folder_get_debug (folder_t, debug_t *)

Function: int folder_set_debug (folder_t, debug_t)

Function: int folder_get_authority (folder_t, authority_t *)

Function: int folder_set_authority (folder_t, authority_t)

Function: int folder_get_url (folder_t, url_t *)

Function: int folder_set_url (folder_t, url_t)

Mailbox

/* Prefix mailbox_ is reserved */
#include <mailutils/mailbox.h>

Data Type: mailbox_t
The mailbox_t object is used to hold information and it is an opaque data structure to the user. Functions are provided to retrieve information from the data structure.
                             mailbox_t                  url_t
  -/var/mail-    +---//---->/-----------------\    +-->/-----------\
 (  alain   )    |          |  url_t        *-|----+   |  port     |
  -----------    |          |-----------------+        |  hostname |
 (  jakob *-)----+          |  observer_t   *-|        |  file     |
  -----------               |-----------------+        |  ...      |
 (  jeff    )               |  stream_t       |        \-----------/
  -----------               |-----------------|
 (  sean    )               |  locker_t       |
  ----------                |-----------------|
                            |  message_t(1)   |
                            |-----------------|
                            |  message_t(2)   |
                            |  ......         |
                            |  message_t(n)   |
                            \-----------------/

Function: int mailbox_append_message (mailbox_t mbox, message_t message)
The message is appended to the mailbox mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null or message is invalid.

Function: int mailbox_close (mailbox_t mbox)
The stream attach to mbox is closed.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_create (mailbox_t *pmbox, const char *name)
The function mailbox_create allocates and initializes pmbox. The concrete mailbox type instantiate is based on the scheme of the url name.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
The url name supplied is invalid or not supported. pmbox is NULL.
ENOMEM
Not enough memory to allocate resources.

Function: int mailbox_create_default (mailbox_t *pmbox, const char *name)
Create a mailbox with mailbox_create () based on the environment variable $MAIL or the string formed by _PATH_MAILDIR/user" or $LOGNAME if user is null,

Function: void mailbox_destroy (mailbox_t *pmbox)
Destroys and releases resources held by pmbox.

Function: int mailbox_expunge (mailbox_t mbox)
All messages marked for deletion are removed.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_folder (mailbox_t mbox, folder_t *folder)
Get the folder.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_debug (mailbox_t mbox, debug_t *debug)
Get a debug object. The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
mbox is null.
ENOMEM

Function: int mailbox_get_locker (mailbox_t mbox, locker_t *plocker)
Return the locker object.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_message (mailbox_t mbox, size_t msgno, message_t *pmessage)
Retrieve message number msgno, pmessage is allocated and initialized.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null or msgno is invalid.
ENOMEM
Not enough memory.

Function: int mailbox_get_observable (mailbox_t mbox mbox, observable_t*observable)
Get the observable object.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.
ENOMEM
Not enough memory.

Function: int mailbox_get_property (mailbox_t mbox, property_t *property)
Get the property object. The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
mbox is null.
ENOMEM

Function: int mailbox_get_size (mailbox_t mbox, off_t *psize)
Gives the mbox size.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_stream (mailbox_t mbox, stream_t *pstream)
The mailbox stream is put in pstream.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is invalid or pstream is NULL.

Function: int mailbox_get_ticket (mailbox_t mbox, ticket_t ticket)
The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_url (mailbox_t mbox, url_t *purl)
Gives the constructed url.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_is_modified (mailbox_t mbox)
Check if the mailbox been modified by an external source.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_message_unseen (mailbox_t mbox, size_t *pnumber);
Give the number of first unseen message in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_messages_count (mailbox_t mbox, size_t *pnumber);
Give the number of messages in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_messages_recent (mailbox_t mbox, size_t *pnumber);
Give the number of recent messages in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_open (mailbox_t mbox, int flag)
A connection is open, if no stream was provided, a stream is created based on the mbox type. The flag can be OR'ed. See stream_create for flag's description.

The return value is 0 on success and a code number on error conditions:

EAGAIN
EINPROGRESS
Operation in progress.
EBUSY
Resource busy.
MU_ERROR_INVALID_PARAMETER
mbox is null or flag is invalid.
ENOMEM
Not enough memory.

Function: int mailbox_scan (mailbox_t mbox, size_t msgno, size_t *pcount);
Scan the mailbox for new messages starting at message msgno.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.
ENOMEM
Not enough memory.

Function: int mailbox_set_locker (mailbox_t mbox, locker_t locker)
Set the type of locking done by the mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_set_stream (mailbox_t mbox, stream_t stream)
Set the stream connection to use for the mailbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox or stream is NULL.

Function: int mailbox_set_ticket (mailbox_t mbox, ticket_t ticket)
The ticket will be set on the auth_t object on creation.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_uidnext (mailbox_t mbox, size_t *pnumber);
Give the next predicted uid for mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_uidvalidity (mailbox_t mbox, size_t *pnumber);
Give the uid validity of mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Mailer

/* Prefix mailer_ is reserved */
#include <mailutils/mailer.h>

The API is still shaky and undefined.

Function: int mailer_create (mailer_t *, const char *)

Function: void mailer_destroy (mailer_t *)

Function: int mailer_open (mailer_t, int flags)

Function: int mailer_close (mailer_t)

Function: int mailer_send_message (mailer_t, message_t)

Function: int mailer_get_property (mailer_t, property_t *)

Function: int mailer_get_stream (mailer_t, stream_t *)

Function: int mailer_set_stream (mailer_t, stream_t)

Function: int mailer_get_debug (mailer_t, debug_t *)

Function: int mailer_set_debug (mailer_t, debug_t)

Function: int mailer_get_observable (mailer_t, observable_t *)

Function: int mailer_get_url (mailer_t, url_t *)

Message

#include <mailutils/message.h>
/* Prefix message_ is reserve */

The message_t object is a convenient way to manipulate messages. It encapsulates the envelope_t, the header_t and the body_t.

    mailbox_t
    __________                   message_t
   (message[1])        +------>+-----------------------+
    ----------         |       |  envelope_t           |
   (message[2])        |       |-----------------------|
    ----------         |       |  header_t             |
   (message[3])--------+       |-----------------------|
    ----------                 |  body_t               |
   (message[n])                |-----------------------|
    ----------                 |  attribute_t          |
                               |-----------------------|
                               |  stream_t             |
                               +-----------------------+

Function: void message_create (message_t *msg, void *owner)

Function: void message_destroy (message_t *msg, void *owner)
The resources allocate for msg are freed.

Function: int message_get_header (message_t msg, header_t *pheader)
Retrieve msg header.

Function: int message_set_header (message_t msg, header_t header, void *owner)

Function: int message_get_body (message_t msg, body_t *pbody)

Function: int message_set_body (message_t msg, body_t body, void *owner)

Function: int message_is_multipart (message_t msg)
Return non-zero value if message is multi-part.

Function: int message_get_num_parts (message_t msg, size_t *nparts)

Function: int message_get_part (message_t msg, size_t part, message_t *msg)

Function: int message_get_stream (message_t msg, stream_t *pstream)

Function: int message_set_stream (message_t msg, stream_t stream,void *owner )

Function: int message_get_attribute (message_t msg, attribute_t *pattribute)

Function: int message_set_attribute (message_t msg, attribute_t attribute, void *owner)

Function: int message_get_envelope (message_t msg, envelope_t *penvelope)

Function: int message_set_envelope (message_t msg, envelope_t envelope, void *owner)

Function: int message_get_uid (message_t msg, size_t *uid)

Function: int message_get_uidl (message_t msg, char *buffer, size_t buflen, size_t *pwriten)

Function: int message_set_uidl (message_t msg, int (*_get_uidl)(message_t, char *, size_t, size_t *), void *owner)

Function: int message_get_observable (message_t msg, observable_t *observable)

Function: int message_create_attachment (const char *content_type, const char *encoding, const char *filename, message_t *newmsg)

Function: int message_save_attachment (message_t msg, const char *filename, void **data)

Function: int message_encapsulate (message_t msg, message_t *newmsg, void **data)

Function: int message_unencapsulate (message_t msg, message_t *newmsg, void **data);

Envelope

/* Prefix envelope_ is reserved */
#include <mailutils/envelope.h>

Function: int envelope_date (envelope_t, char *, size_t, size_t *);

Get the date that the message was delivered to the mailbox, in something close to ANSI ctime() format: Mon Jul 05 13:08:27 1999.

Function: int envelope_sender (envelope_t, char *, size_t, size_t *);

Get the address that this message was reportedly received from. This would be the "mail from" argument if the message was delivered or received via SMTP, for example.

Function: int envelope_get_message (envelope_t, message_t *);

Function: int envelope_create (envelope_t *, void *);
Primarily for internal use.

Function: void envelope_destroy (envelope_t *, void *);
Primarily for internal use.

Function: int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *);

Primarily for internal use. The implementation of envelope_t depends on the mailbox type, this allows the function which actually gets the sender to be set by the creator of an envelope_t.

Function: int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *);

Primarily for internal use. The implementation of envelope_t depends on the mailbox type, this allows the function which actually gets the date to be set by the creator of an envelope_t.

Headers

/* Prefix header_ is reserved */
#include <mailutils/header.h>

So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII characters will be encoded.

Function: int header_create (header_t *hdr, const char *blurb, size_t len, void *owner)
Initialize a hdr to a supported type. If blurb is not NULL, it is parsed.

Function: void header_destroy (header_t *hdr, void *owner)
The resources allocated for hdr are freed.

Function: int header_set_value (header_t hdr, const char *fn, const char *fv, size_t n, int replace)
Set the field-name fn to field-value fv of size n in hdr. If replace is non-zero the initial value is replaced, if zero it is appended.

Some basic macros are already provided for rfc822.

MU_HDR_RETURN_PATH
Return-Path
MU_HDR_RECEIVED
Received
MU_HDR_DATE
Date
MU_HDR_FROM
From
MU_HDR_RESENT_FROM
Resent-From
MU_HDR_SUBJECT
Subject
MU_HDR_SENDER
Sender
MU_HDR_RESENT_SENDER
Resent-SENDER
MU_HDR_TO
To
MU_HDR_RESENT_TO
Resent-To
MU_HDR_CC
Cc
MU_HDR_RESENT_CC
Resent-Cc
MU_HDR_BCC
Bcc
MU_HDR_RESENT_BCC
Resent-Bcc
MU_HDR_REPLY_TO
Reply-To
MU_HDR_RESENT_REPLY_TO
Resent-Reply-To
MU_HDR_MESSAGE_ID
Message-ID
MU_HDR_RESENT_MESSAGE_ID
Resent-Message-ID
MU_HDR_IN_REPLY_TO
In-Reply-To
MU_HDR_ENCRYPTED
Encrypted
MU_HDR_PRECEDENCE
Precedence
MU_HDR_STATUS
Status
MU_HDR_CONTENT_LENGTH
Content-Length
MU_HDR_CONTENT_TYPE
Content-Type
MU_HDR_MIME_VERSION
MIME-Version

Function: int header_get_value (header_t hdr, const char *fn, char *fv, size_t len, size_t *n)
Value of field-name fn is returned in buffer fv of size len. The number of bytes written is put in n.

Function: int header_aget_value (header_t hdr, const char *fn, char **fv)
The value is allocated.

Function: int header_get_stream (header_t hdr, stream_t *pstream)

Function: int header_set_size (header_t hdr, size_t *size)

Function: int header_set_lines (header_t hdr, size_t *lpines)

Body

/* Prefix body_ is reserved */
#include <mailutils/body.h>

Function: int body_create (body_t *body, void *owner)
Initialize an object bdy.

Function: void body_destroy (body_t *pbody)
The resources allocate are release.

Function: int body_get_stream (body_t body, stream_t *pstream)

Function: int body_set_stream (body_t body, stream_t stream, void *owner)

Function: int body_get_filename __P ((body_t body, char *buffer, size_tbuflen, size_t *pwriten)

Function: int body_set_filename (body_t body, const char*buffer)

Function: int body_size (body_t body, size_t*psize)

Function: int body_lines (body_t body, size_t *plines)

Attribute

/* Prefix attribute_ is reserved */
#include <mailutils/attribute.h>

Function: int attribute_create (attribute_t *pattribute)

Function: void attribute_destroy (attribute_t *pattribute)

Function: int attribute_is_seen (attribute_t attribute)

Function: int attribute_is_answered (attribute_t attribute)

Function: int attribute_is_flagged (attribute_t attribute)

Function: int attribute_is_deleted (attribute_t attribute)

Function: int attribute_is_draft (attribute_t attribute)

Function: int attribute_is_recent (attribute_t attribute)

Function: int attribute_is_read (attribute_t attribute)

Function: int attribute_set_seen (attribute_t attribute)

Function: int attribute_set_answered (attribute_t attribute)

Function: int attribute_set_flagged (attribute_t attribute)

Function: int attribute_set_deleted (attribute_t attribute)

Function: int attribute_set_draft (attribute_t attribute)

Function: int attribute_set_recent (attribute_t attribute)

Function: int attribute_set_read (attribute_t attribute)

Function: int attribute_unset_seen (attribute_t attribute)

Function: int attribute_unset_answered (attribute_t attribute)

Function: int attribute_unset_flagged (attribute_t attribute)

Function: int attribute_unset_deleted (attribute_t attribute)

Function: int attribute_unset_draft (attribute_t attribute)

Function: int attribute_unset_recent (attribute_t attribute)

Function: int attribute_unset_read (attribute_t attribute)

Function: int attribute_is_equal (attribute_t att1, attribute_t att2)

Function: int attribute_copy (attribute_t dst, attribute_t src)

Function: int string_to_attribute (const char *buf, attribute_t *pattr)

Function: int attribute_to_string (attribute_t attr, char *buf, size_t len, size_t *pwriten)

Stream

#include <mailutils/stream.h>

Function: int stream_create (stream_t *pstream, int flags, void *owner)
MU_STREAM_READ
The stream is open read only.
MU_STREAM_WRITE
The stream is open write only.
MU_STREAM_RDWR
The stream is open read and write.
MU_STREAM_APPEND
The stream is open in append mode for writing.
MU_STREAM_CREAT
The stream is created.
MU_STREAM_NONBLOCK
The stream is set non blocking.
MU_STREAM_NO_CHECK
Stream is destroyed without checking for the owner.

Function: void stream_destroy (stream_t *pstream, void *owner)

Function: int stream_open (stream_t stream, const char *name, intport, int flag)

Function: int stream_close (stream_t stream)

Function: int stream_get_fd (stream_t stream, int *pfd)

Function: int stream_read (stream_t stream, char *buffer, size_t buflen, off_t offset, size_t *pwriten)

Function: int stream_readline (stream_t stream, char *buffer, size_t buflen, off_t offset, size_t *pwriten)

Function: int stream_size (stream_t stream, off_t *psize)

Function: int stream_truncate (stream_t stream, off_t size)

Function: int stream_write (stream_t stream, const char *buffer, size_t buflen, off_t offset, size_t *pwriten)

Function: int stream_flush (stream_t stream)

Function: int stream_get_flags (stream_t stream, int *pflags)

Function: int stream_get_state (stream_t stream, int *pstate)
MU_STREAM_STATE_OPEN
Last action was stream_open.
MU_STREAM_STATE_READ
Last action was stream_read or stream_readline.
MU_STREAM_STATE_WRITE
Last action was stream_write.
MU_STREAM_STATE_CLOSE
Last action was stream_close.

Function: int file_stream_create (stream_t *pstream)

Function: int mapfile_stream_create (stream_t *pstream)

Function: int encoder_stream_create (stream_t *pstream, stream_t iostream, const char *encoding)

Function: int decoder_stream_create (stream_t *pstream, stream_t iostream, const char *encoding)

Function: int tcp_stream_create (stream_t *pstream)

An example using tcp_stream_create to make a simple web client:

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <unistd.h>
#include <sys/select.h>

#include <mailutils/io.h>

const char *wbuf = "GET / HTTP/1.0\r\n\r\n";
char rbuf[1024];

int
main(int argc, char **argv)
{
  int ret, off = 0, fd;
  stream_t stream;
  size_t nb;
  fd_set fds;

  argc = argc, argv = argv;

  ret = tcp_stream_create (&stream);
  if (ret != 0)
    {
       fprintf (stderr, "tcp_stream_create: %s\n",
                mailutils_error(ret));
       exit (EXIT_FAILURE);
    }

connect_again:
  ret = stream_open (stream, "www.netscape.com", 80,
                     MU_STREAM_NONBLOCK);
  if (ret != 0)
    {
       if (ret == MU_ERROR_EAGAIN)
         {
             ret = stream_get_fd(stream, &fd);
             if (ret != 0)
               {
                   fprintf (stderr, "stream_get_fd: %s\n",
                            mailutils_error(ret));
                   exit (EXIT_FAILURE);
               }
               FD_ZERO (&fds);
               FD_SET (fd, &fds);
               select (fd+1, NULL, &fds, NULL, NULL);
               goto connect_again;
          }
          fprintf (stderr, "stream_open: %s\n", mailutils_error (ret));
          exit (EXIT_FAILURE);
    }

    ret = stream_get_fd (stream, &fd);
    if (ret != 0)
      {
         fprintf(stderr, "stream_get_fd: %s\n", strerror(ret));
         exit (EXIT_FAILURE);
      }

write_again:
    ret = stream_write (stream, wbuf + off, strlen (wbuf), 0, &nb);
    if (ret != 0 )
      {
         if (ret == EAGAIN)
           {
              FD_ZERO (&fds);
              FD_SET (fd, &fds);
              select (fd + 1, NULL, &fds, NULL, NULL);
              off += nb;
              goto write_again;
           }
         fprintf (stderr, "stream_write: %s\n", strerror(ret));
         exit (EXIT_FAILURE)
      }

      if (nb != strlen (wbuf))
        {
           fprintf(stderr, "stream_write: %s\n", "nb != wbuf length");
           exit (EXIT_FAILURE);
        }

      do
        {
read_again:
           ret = stream_read (stream, rbuf, sizeof (rbuf), 0, &nb);
           if (ret != 0)
             {
                if (ret == EAGAIN)
                  {
                     FD_ZERO (&fds);
                     FD_SET (fd, &fds);
                     select (fd + 1, &fds, NULL, NULL, NULL);
                     goto read_again;
                   }
                 fprintf (stderr, "stream_read: %s\n", strerror(ret));
                 exit(EXIT_FAILURE);
              }
              write (2, rbuf, nb);
         } while (nb);

         ret = stream_close (stream);
         if (ret!= 0)
           {
              fprintf (stderr, "stream_close: %s\n", strerror(ret));
              exit (EXIT_FAILURE);
           }

         stream_destroy (&stream, NULL);
         exit (EXIT_SUCCESS);
}

Iterator

/* Prefix iterator_ is reserved */
#include <mailutils/iterator.h>

Function: int iterator_create (iterator_t *)

Function: void iterator_destroy (iterator_t *)

Function: int iterator_first (iterator_t)

Function: int iterator_next (iterator_t)

Function: int iterator_current (iterator_t, void **pitem)

Function: int iterator_is_done (iterator_t)

Authenticator

/* Prefix auth_ is reserved */
#include <mailutils/auth.h>

There are many ways to authenticate to a server. To be flexible the authentication process is provided by two objects auth_t and ticket_t. The auth_t can implement different protocol like APOP, MD5-AUTH, One Time Passwd etc .. By default if a mailbox does not understand or know how to authenticate it falls back to user/passwd authentication. The ticket_t is a way for Mailboxes and Mailers provide a way to authenticate when the URL does not contain enough information. The default action is to call the function auth_authenticate which will get the user and passwd if not set, this function can be overridden by a custom method.

Function: int auth_create (auth_t *pauth, void *owner)

Function: void auth_destroy (auth_t *pauth, void *owner)

Function: int auth_prologue (auth_t auth)

Function: int auth_authenticate (auth_t auth, char **user, char **passwd)

Function: int auth_epilogue (auth_t auth)

A simple example of an authenticate function:

#include <mailutils/auth.h>
#include <stdio.h>
#include <string.h>

int
my_authenticate (auth_t auth, char **user, char **passwd)
{
  char u[128] = "";
  char p[128] = "";

  /* prompt the user name */
  printf ("User: ");
  fflush (stdout);
  fgets (u, sizeof (u), stdin);
  u[strlen (u) - 1] = '\0'; /* nuke the trailing NL */

  /* prompt the passwd */
  printf ("Passwd: "); fflush (stdout);
  echo_off ();
  fgets (p, sizeof(p), stdin);
  echo_on ();
  p[strlen (p) - 1] = '\0';

  /* duplicate */
  *user = strdup (u);
  *passwd = strdup (p);
  return 0;
}

Address

/* Prefix address_ is reserved */
#include <mailutils/address.h>

The Internet address format is defined in RFC 822. RFC 822 has been updated, and is now superceeded by RFC 2822, which makes some corrections and clarifications. References to RFC 822 here apply equally to RFC 2822.

The RFC 822 format is more flexible than many people realize, here is a quick summary of the syntax this parser implements, see RFC 822 for the details. "[]" pairs mean "optional", "/" means "one or the other", and double-quoted characters are literals.

addr-spec    = local-part "@" domain
mailbox      = addr-spec ["(" display-name ")"] /
               [display-name] "<" [route] addr-spec ">"
mailbox-list = mailbox ["," mailbox-list]
group        = display-name ":" [mailbox-list] ";"
address      = mailbox / group / unix-mbox
address-list = address ["," address-list]

unix-mbox is a non-standard extension meant to deal with the common practice of using user names as addresses in mail utilities. It allows addresses such as "root" to be parsed correctly. These are NOT valid internet email addresses, they must be qualified before use.

Several address functions have a set of common arguments with consistent semantics, these are described here to avoid repetition.

Since an address-list may contain multiple addresses, they are accessed by a one-based index number, no. The index is one-based because pop, imap, and other message stores commonly use one-based counts to access messages and attributes of messages.

If len is greater than 0 it is the length of the buffer buf, and as much of the component as possible will be copied into the buffer. The buffer will be null terminated.

The size of a particular component may be queried by providing 0 for the len of the buffer, in which case the buffer is optional. In this case, if n is provided *n is assigned the length of the component string.

@macro ADDRESSENOMEM

  • ENOMEM Not enough memory to allocate resources. @macro ADDRESSEPARSE
  • ENOENT Invalid RFC822 syntax, parsing failed. @macro ADDRESSENOENT
  • ENOENT The index no is outside of the range of available addresses. @macro ADDRESSEINVAL
  • EINVAL Invalid usage, usually a required argument was null.
    Data Type: address_t
    The address_t object is used to hold information about a parsed RFC822 address list, and is an opaque data structure to the user. Functions are provided to retrieve information about an address in the address list.
    Function: int address_create (address_t *addr, const char *string)
    This function allocates and initializes addr by parsing the RFC822 address-list string. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOMEM @ADDRESSEPARSE
    Function: void address_destroy (address_t *addr)
    The addr is destroyed.
    Function: int address_get_email (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the noth email address component of the address list. This address is the plain email address, correctly quoted, suitable for using in an smtp dialog, for example, or as the address part of a contact book entry. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_personal (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the display-name describing the noth email address. This display-name is optional, so may not be present. If it is not present, but there is an RFC822 comment after the address, that comment will be returned as the personal phrase, as this is a common usage of the comment even though it is not defined in the internet mail standard. A group is a kind of a special case. It has a display-name, followed by an optional mailbox-list. The display-name will be allocated an address all it's own, but all the other elements (local-part, domain, etc.) will be zero-length. So "a group: ;" is valid, will have a count of 1, but address_get_email(), and all the rest, will return zero-length output. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_comments (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the comments extracted while parsing the noth email address. These comments have no defined meaning, and are not currently collected. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_email (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the email addr-spec extracted while parsing the noth email address. This will be 0 length for a unix-mbox. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_local_part (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the local-part of an email addr-spec extracted while parsing the noth email address. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_domain (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the domain of an email addr-spec extracted while parsing the noth email address. This will be 0 length for a unix-mbox. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_route (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the route of an email addr-spec extracted while parsing the noth email address. This is a rarely used RFC822 address syntax, but is legal in SMTP as well. The entire route is returned as a string, those wishing to parse it should look at <mailutils/parse822.h>. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_is_group (address_t *addr, size_t no, size_t len, int* yes)
    Sets *yes to 1 if this address is just the name of a group, 0 otherwise. This is faster than checking if the address has a non-zero length personal, and a zero-length local_part and domain. yes can be null, though that doesn't serve much purpose other than determining that no refers to an address. Currently, there is no way to determine the end of the group. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_to_string (address_t *addr, char* buf, size_t len, size_t* n)
    Returns the entire address list as a single RFC822 formatted address list. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOMEM
    Function: int address_get_count (address_t addr, size_t* count)
    Returns a count of the addresses in the address list. If addr is null, the count is 0. If count is not null, the count will be written to *count. The return value is 0.

    Example

    #include <stdio.h>
#include <errno.h>
#include <mailutils/address.h>

#define EPARSE ENOENT

static const char* err_name(int e)
{
    struct {
    int e;
    const char* s;
    } map[] = {
#define E(e) { e, #e },
    E(ENOENT)
    E(EINVAL)
    E(ENOMEM)
#undef E
    { 0, NULL }
    };
    static char s[sizeof(int) * 8 + 3];
    int i;

    for(i = 0; map[i].s; i++) {
    if(map[i].e == e)
        return map[i].s;
    }
    sprintf(s, "[%d]", e);

    return s;
}

static int parse(const char* str)
{
    size_t no = 0;
    size_t pcount = 0;
    int status;

    char buf[BUFSIZ];

    address_t  address = NULL;

    status = address_create(&address, str);

    address_get_count(address, &pcount);

    if(status) {
    printf("%s=> error %s\n\n", str, err_name(status));
    return 0;
    } else {
    printf("%s=> pcount %d\n", str, pcount);
    }

    for(no = 1; no <= pcount; no++) {
    size_t got = 0;
    int isgroup;

    address_is_group(address, no, &isgroup);

    printf("%d ", no);

    if(isgroup) {
      address_get_personal(address, no, buf, sizeof(buf), &got);

      printf("group <%s>\n", buf);
    } else {
      address_get_email(address, no, buf, sizeof(buf), 0);

      printf("email <%s>\n", buf);
    }

    address_get_personal(address, no, buf, sizeof(buf), &got);

    if(got && !isgroup) printf("   personal <%s>\n", buf);

    address_get_comments(address, no, buf, sizeof(buf), &got);

    if(got) printf("   comments <%s>\n", buf);

    address_get_local_part(address, no, buf, sizeof(buf), &got);

    if(got) {
        printf("   local-part <%s>", buf);

        address_get_domain(address, no, buf, sizeof(buf), &got);

        if(got) printf(" domain <%s>", buf);

        printf("\n");
    }

    address_get_route(address, no, buf, sizeof(buf), &got);

    if(got) printf("   route <%s>\n", buf);
    }
    address_destroy(&address);

    printf("\n");

    return 0;
}

static int parseinput(void)
{
    char buf[BUFSIZ];

    while(fgets(buf, sizeof(buf), stdin) != 0) {
    buf[strlen(buf) - 1] = 0;
    parse(buf);
    }

    return 0;
}

int main(int argc, const char *argv[])
{
    argc = 1;

    if(!argv[argc]) {
    return parseinput();
    }
    for(; argv[argc]; argc++) {
    if(strcmp(argv[argc], "-") == 0) {
        parseinput();
    } else {
        parse(argv[argc]);
    }
    }

    return 0;
}

    Locker

    /* Prefix locker_ is reserved */
#include <mailutils/locker.h>

    Function: int locker_create (locker_t * plocker, char *filename, size_t len, int flags)

    Function: void locker_destroy (locker_t * plocker)

    Function: int locker_lock (locker_t locker, int flag)
    MU_LOCKER_RDLOCK
    MU_LOCKER_WRLOCK
    MU_LOCKER_PID
    MU_LOCKER_FCNTL
    MU_LOCKER_TIME

    Function: int locker_touchlock (locker_t locker)

    Function: int locker_unlock (locker_t locker)

    URL

    A mailbox or a mailer can be described in a URL, the string will contain the necessary information to initialize mailbox_t, or mailer_t properly.

    POP3

    The POP URL scheme contains a POP server, optional port number and the authentication mechanism. The general form is

    pop://[<user>[;AUTH=<auth>]@]<host>[:<port>]
 or
pop://[<user>[:<passwd>]@]<host>[:<port>]

    If :port is omitted the default value is 110. Different forms of authentication can be specified with ;AUTH=type. The special string ;AUTH=* indicates that the client will use a default scheme base on the capability of the server.

    pop://obelix@gaulois.org
pop://asterix;AUTH=*@france.com
pop://falbala;AUTH=+APOP@france.com
pop://obelix;AUTH=+APOP@village.gaulois.org:2000
pop://obelix:menhir@village.gaulois.org:2000

    For more complete information see rfc2368.

    IMAP

    The IMAP URL scheme contains an IMAP server, optional port number and the authentication mechanism. The general form is

    imap://[<user>[;AUTH=<type>]]@<host>[:port][/<mailbox>]
 or
imap://[<user>[:<passwd>]]@<host>[:port][/<mailbox>]

    If :port is omitted the default value is 220. Different forms of authentication can be specified with ;AUTH=type. The special string ;AUTH=* indicates that the client will use a default scheme base on the capability of the server.

    imap://obelix@imap.gaulois.org
imap://asterix;AUTH=*@imap.france.com
imap://asterix:potion@imap.france.com

    For more complete information see rfc2192.

    File

    Local folder should be handle by this URL. It is preferable to let the mailbox recognize the type of mailbox and take the appropriate action.

    file://path
file://var/mail/user
file://home/obelix/Mail

    For MMDF, MH local mailboxes URLs are provided, but it is preferable to use file://path and let the library figure out which one.

    mmdf://path
mh://path

    Mailto

    After setting a mailer, mailto: is used to tell the mailer where and to whom the message is for.

    mailto://hostname

    Mailto can be used to generate short messages, for example to subscribe to mailing lists.

    mailto://bug-mailutils@gnu.org?body=subscribe
mailto://bug-mailutils@gnu.org?Subject=hello&body=subscribe

    For more complete information see rfc2368.

    URL functions

    Helper functions are provided to retrieve and set the URL fields.

    Function: int url_create (url_t *url, const char *name)
    Create and the url data structure, but do not parse it.

    Function: void url_destroy (url_t *)
    Destroy the url and free it's resources.

    Function: int url_parse (url_t url)
    Parses the url, after calling this the get functions can be called.

    The syntax, condensed from RFC 1738, and extended with the ;auth= of RFC 2384 (for POP) and RFC 2192 (for IMAP) is:

    url =
    scheme ":" = "//"

    [ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ]

    host [ ":" port ]

    [ ( "/" urlpath ) | ( "?" query ) ]

    This is a generalized URL syntax, and may not be exactly appropriate for any particular scheme.

    Function: const char* url_to_string (const url_t url)

    Function: int url_get_scheme (const url_t url, char *schem, size_t len, size_t *n)

    Function: int url_get_user (const url_t url, char *usr, size_t len, size_t *n)

    Function: int url_get_passwd (const url_t url, char *passwd, size_t len, size_t *n)

    Function: int url_get_host (const url_t url, char *host, size_t len, size_t *n)

    Function: int url_get_port (const url_t url, long *port)

    Function: int url_get_path (const url_t url, char *path, size_t len, size_t *n)

    Function: int url_get_query (const url_t url, char *query, size_t{len}, size_t *n)

    Function: char* url_decode (const char* s)
    Decodes an RFC 1738 % encoded string, returning the decoded string in allocated memory. If the string is not encoded, this degenerates to a strdup().

    Example

    #include <mailutils/url.h>
#include <stdio.h>
#include <string.h>

int
main ()
{
  char str[1024];
  char buffer[1024];
  long port = 0;
  int len = sizeof (buffer);
  url_t u = NULL;

  while (fgets (str, sizeof (str), stdin) != NULL)
    {
      int rc;

      str[strlen (str) - 1] = '\0'; /* chop newline */
      if(strspn(str, " \t") == strlen(str))
        continue; /* skip empty lines */
      if ((rc = url_create(&u, str)) != 0)
      {
        printf(stderr, "url_create %s ERROR: [%d] %s",
          str, rc, strerror(rc));
        exit (1);
      }
      if ((rc = url_parse (u)) != 0)
        {
          printf ("%s --> FAILED: [%d] %s\n",
            str, rc, strerror(rc));
          continue;
        }
      printf ("%s --> SUCCESS\n", str);

      url_get_scheme (u, buffer, len, NULL);
      printf (" scheme <%s>\n", buffer);

      url_get_user (u, buffer, len, NULL);
      printf (" user <%s>\n", buffer);

      url_get_passwd (u, buffer, len, NULL);
      printf (" passwd <%s>\n", buffer);

      url_get_auth (u, buffer, len, NULL);
      printf (" auth <%s>\n", buffer);

      url_get_host (u, buffer, len, NULL);
      printf (" host <%s>\n", buffer);

      url_get_port (u, &port);
      printf (" port %ld\n", port);

      url_get_path (u, buffer, len, NULL);
      printf (" path <%s>\n", buffer);

      url_get_query (u, buffer, len, NULL);
      printf (" query <%s>\n", buffer);

      url_destroy (&u);

    }
  return 0;
}

    Programs

    GNU Mailutils provides a set of programs for handling the email.

    IMAP4 daemon

    imap4d has two operation modes:

    Inetd
    The server is started from `/etc/inetd.conf' file:
    imap4  stream tcp nowait  root  /usr/local/sbin/imap4d imap4d
    This is the default operation mode.
    Standalone
    The server runs as daemon, forking a child for each new connection. This mode is triggered by `-d' command line switch.

    Command line options

    `-d[NUMBER]'
    `--daemon[=NUMBER]'
    Run in standalone mode. An optional NUMBER specifies the maximum number of child processes the daemon is allowed to fork. When it is omitted, it defaults to 20 processes. Please note, that there should be no whitespace between the `-d' and its parameter.
    `-h'
    `--help'
    Display short help message and exit.
    `-i'
    `--inetd'
    Run in inetd mode.
    `-p NUMBER'
    `--port NUMBER'
    Listen on given port NUMBER. This option is meaningful only in standalone mode. It defaults to port 143.
    `-t NUMBER'
    `--timeout NUMBER'
    Set idle timeout to given NUMBER of seconds. Default is 1800 seconds (30 minutes). The daemon breaks the connection if it receives no commands from the client within that number of seconds.
    `-v'
    `--version'
    Display program version and exit.

    POP3 daemon

    The `pop3d' daemon implements the Post Office Protocol server.

    pop3d has two operation modes:

    Inetd
    The server is started from `/etc/inetd.conf' file:
    pop3  stream tcp nowait  root  /usr/local/sbin/pop3d pop3d
    This is the default operation mode.
    Standalone
    The server runs as daemon, forking a child for each new connection. This mode is triggered by `-d' command line switch.

    Command line options

    `-d[NUMBER]'
    `--daemon[=NUMBER]'
    Run in standalone mode. An optional NUMBER specifies the maximum number of child processes the daemon is allowed to fork. When it is omitted, it defaults to 10 processes. Please note, that there should be no whitespace between the `-d' and its parameter.
    `-h'
    `--help'
    Display short help message and exit.
    `-i'
    `--inetd'
    Run in inetd mode.
    `-p NUMBER'
    `--port NUMBER'
    Listen on given port NUMBER. This option is meaningful only in standalone mode. It defaults to port 110.
    `-t NUMBER'
    `--timeout NUMBER'
    Set idle timeout to given NUMBER of seconds. Default is 600 seconds (10 minutes). The daemon breaks the connection if it receives no commands from the client within that number of seconds.
    `-v'
    `--version'
    Display program version and exit.

    frm -- List headers from a mailbox.

    The `frm' command outputs a header information of the selected messages in a mailbox. By default, `frm' reads the user's system mailbox and outputs the contents of From and Subject headers for each message. If a folder is specified in the command line, the program reads that folder rather than the default mailbox.

    The following command line options alter the behavior of the program:

    `-h'
    `--help'
    Display short help message and exit.
    `-f STRING'
    `--field STRING'
    Display the header named by STRING instead of From Subject pair.
    `-l'
    `--to'
    Include the contents of To header to the output. The output field order is then: To From Subject.
    `-n'
    `--number'
    Prefix each line with corresponding message number.
    `-Q'
    `--Quiet'
    Be very quiet. Nothing is output except error messages. This is useful in shell scripts where only the return status of the program is important.
    `-q'
    `--query'
    Print a message only if there are unread messages in the mailbox.
    `-S'
    `--summary'
    Print a summary line.
    `-s ATTR'
    `--status ATTR'
    Only display headers from messages with the given status. ATTR may be one of the following: `new', `read', `unread'. It is sufficient to specify only first letter of an ATTR. Multiple `-s' options are allowed.
    `-t'
    `--align'
    Tidy mode. Currently is not implemented. Included for compatibility with `frm' program from Elm package.
    `-v'
    `--version'
    Display version information and exit

    mail -- send and receive mail.

    Mail is an enhanced version of standard `/bin/mail' program. As well as its predecessor, it can be used either in sending mode or in reading mode. Mail enters sending mode when one or more email addresses were specified in this command line. In this mode the program waits until user finishes composing the message, then attempts to send it to the specified addresses and exits. See See section Composing mail, for a detailed description of this behavior.

    If the command line contained no email addresses, mail switches to reading mode. In this mode it allows to read and manipulate the contents of a mailbox. The URL of the mailbox to operate upon is taken from the argument of `--file' command line option. If it is not specified, the user's system mailbox is assumed. See section Reading mail for more detail.

    Command line options

    General usage of `mail' program is:

          mail [OPTION...] [address...]

    If [address...] part is present, `mail' switches to mail sending mode, otherwise it operates in mail reading mode.

    `Mail' understands following command line options:

    `-e'
    `--exist'
    Return true if the mailbox contains some messages. Return false otherwise. This is useful for writing shell scripts.
    `-f[FILE]'
    `--file[=FILE]'
    Operate on mailbox FILE. If this option is not specified, the default is user's system mailbox. If it is specified without argument, the default is $HOME/mbox. Please note, that there should be no whitespace between the short variant of the option (`-f'), and its parameter. Similarly, when using long option (`--file'), its argument must be preceded by equal sign.
    `-F'
    `--byname'
    Save messages according to sender. Currently this option is not implemented.
    `-H'
    `--headers'
    Print header summary to stdout and exit.
    `-i'
    `--ignore'
    Ignore interrupts.
    `-n'
    `--norc'
    Do not read the system-wide mailrc file. See section Personal and system-wide configuration files.
    `-N'
    `--nosum'
    Do not display initial header summary.
    `-p'
    `--print'
    `-r'
    `--read'
    Print all mail to standard output. It is equivalent to issuing following commands after starting `mail -N':
     print *
 quit
    `-q'
    `--quit'
    Cause interrupts to terminate program.
    `-s SUBJ'
    `--subject=SUBJ'
    Send a message with a Subject of SUBJ. Valid only in sending mode.
    `-t'
    `--to'
    Switch to sending mode.
    `-u USER'
    `--user=USER'
    Operate on USER's mailbox. This is equivalent to:
            mail -f/spool_path/USER
    with spool_path being the full path to your mailspool directory (`/var/spool/mail' or `/var/mail' on most systems).
    `-?'
    `--help'
    Display a help message.
    `--usage'
    Display a short usage summary.
    `-V'
    `--version'
    Print program version and exit.

    How to specify message sets

    Many mail commands such as print and delete can be given a message list to operate upon. Wherever the message list is omitted, the command operates on the current message.

    The message list in its simplest form is one of:

    .
    Selects current message. It is equivalent to empty message list.
    *
    Selects all messages in the mailbox.
    ^
    Selects first non-deleted message.
    $
    Selects last non-deleted message.

    In its complex form, the message list is a comma or whitespace-separated list of message specifiers. A message specifier is one of

    Message Number
    This specifier addresses the message with the given ordinal number in the mailbox.
    Message range
    Message range is specified as two message numbers separated by a dash. It selects all messages with the number lying within that range.
    Attribute specifier
    An Attribute specifier is a colon followed by a single letter. The Attribute specifier addresses all messages in the mailbox that have the given attribute. These are the valid attribute specifiers:
    `:d'
    Selects all deleted messages.
    `:n'
    Selects all recent messages, i.e. the messages that have not been neither read not seen so far.
    `:o'
    Selects all messages that have been seen.
    `:r'
    Selects all messages that have been read.
    `:u'
    Selects all messages that have not been read.
    `:t'
    Selects all tagged messages (see section Marking messages).
    `:T'
    Selects all untagged messages.
    Header match
    The header match is a string in the form:
    [header:]/string/
    It selects all messages that contain header field header matching given regexp. If the variable regexp is set, the string is assumed to be a POSIX regexp. Otherwise, a header is considered to match string if the latter constitutes a substring of the former (comparison is case-insensitive). If header: part is omitted, it is assumed to be `Subject:'.
    Message body match
    The message body match is a string in the form:
    :/string/
    It selects all messages whose body matches the string. The matching rules are the same as described under "Header match".

    A message specifier can be followed by message part specifier, enclosed in a pair of brackets. A message part specifier controls which part of a message should be operated upon. It is meaningful only for multipart messages. A message part specifier is a comma or whitespace - separated list of part numbers or ranges. Each part number can in turn be message part specifier, thus allowing for operating upon multiply-encoded messages.

    The following are the examples of valid message lists:

    Composing mail

    You can compose the message by simply typing the contents of it, line by line. But usually this is not enough, you would need to edit your text, to quote some messages, etc. `Mail' provides these capabilities through compose escapes. The compose escapes are single-character commands, preceded by special escape character, which defaults to `~'. The combination escape character + command is recognized as a compose escape only if it occurs at the beginning of a line. If the escape character must appear at the beginning of a line, enter it twice. The actual escape character may be changed by setting the value of escape mail variable (see section How to alter the behavior of mail).

    Quitting Compose Mode

    There are several commands allowing you to quit the compose mode.

    Typing the end-of-file character (`C-D') on a line alone finishes compose mode and sends the message to its destination. The `C-D' character looses its special meaning if ignoreeof mail variable is set.

    If mail variable dot is set, typing dot (`.') on a line alone achieves the same effect as `C-D' above.

    Finally, using `~.' escape always quits compose mode and sends out the composed message.

    To abort composing of a message without sending it, type interrupt character (by default, `C-C') twice. This behavior is disabled when mail variable ignore is set. In this case, you can use `~x' escape to achieve the same effect.

    Getting Help on Compose Escapes: ~?

    The `~?' escape prints on screen a brief summary of the available compose escapes. Please note, that `~h' escape prompts for changing the header values, and does not give help.

    Editing the Message: ~e and ~v.

    If you are not satisfied with the message as it is, you can edit it using a text editor specified either by EDITOR or by VISUAL environment variables. The `~e' uses the former, and `~v' uses the latter.

    Please note, that both commands allow you to edit the body of the message, and not its headers. To change message headers, see section Modifying the Headers: ~h, ~t, ~c, ~b, ~s.

    Modifying the Headers: ~h, ~t, ~c, ~b, ~s

    To add new addresses to the list of message recipients, use `~t' command, e.g.:

    ~t name1@domain.net name2

    To add addresses to Cc or Bcc, use `~c' or `~b' escapes respectively.

    To change the Subject header, use `~s' escape, e.g.:

    ~s "Re: your message"

    Finally, to edit all headers, type `~h' escape. This will present you with the values of To, Cc, Bcc, and Subject headers allowing to edit them with normal text editing commands.

    Enclosing Another Message: ~m and ~M

    If you are sending mail from within mail command mode, you can enclose the contents of any message sent to you by using `~m' or `~M' commands. Typing `~m' alone will enclose the contents of the current message, typing `~m 12' will enclose the contents of message #12 and so on.

    The `~m' uses retained and ignored lists when enclosing headers, the `~M' encloses all header fields (see section Controlling header display).

    In both cases, the contents of indentprefix mail variable is prepended to each line enclosed.

    Adding a File to the Message: ~r and ~d

    To append the contents of file filename to the message, type

    ~r filename

    or

    ~< filename

    The `~d' escape is a shorthand for

    ~r dead.letter

    Printing And Saving the Message

    The `~p' escape types the contents of the message entered so far, including headers, on your terminal. You can save the message to an arbitrary file using `~w' escape. It takes the filename as its argument.

    Signing the Message: ~a and ~A

    To save you the effort of typing your signature at the end of each message, you can use `~a' or `~A' escapes. If your signature occupies one line only, save it to the variable sign and use `~a' escape to insert it. Otherwise, if it is longer than one line, save it to a file, store the name of this file in the variable Sign, and use `~A' escape to insert it into the message.

    Printing Another Message: ~f and ~F

    Sometimes it is necessary to view the contents of another message, while composing. These two escapes allow it. Both take the message list as their argument. If they are used without argument, the contents of the current message is printed. The difference between `~f' and `~F' is that the former uses ignored and retained lists to select headers to be displayed, whereas the latter prints all headers (see section Controlling header display).

    Inserting Value of a Mail Variable: ~i

    The `~i' escape enters the value of the named mail variable into the body of the message being composed.

    Executing Other Mail Commands: ~: and ~-

    You can execute a mail command from within compose mode using `~:' or `~-' escapes. For example, typing

    ~: from :t

    will display the from lines of all tagged messages. Note, that executing mail-sending commands (see section Replying) from within the compose mode is not allowed. An attempt to execute such a command will result in diagnostic message "Command not allowed in an escape sequence" being displayed. Also, when starting compose mode immediately from the shell (e.g. running `mail address@domain'), most mail commands are meaningless, since there is no mailbox to operate upon. In this case, the only commands that can reasonably be used are: alias, unalias, alternate, set, and unset.

    Executing Shell Commands: ~! and ~|

    The `~!' escape executes specified command and returns you to `mail' compose mode without altering your message. When used without arguments, it starts your login shell. The `~|' escape pipes the message composed so far through the given shell command and replaces the message with the output the command produced. If the command produced no output, `mail' assumes that something went wrong and retains the old contents of your message.

    Reading mail

    To read messages from a given mailbox, use one of the following ways of invoking `mail':

    mail
    To read messages from your system mailbox.
    mail --file
    To read messages from your mailbox ($HOME/mbox).
    mail --file=path_to_mailbox
    To read messages from the specified mailbox.
    mail --user=user
    To read messages from the system mailbox belonging to user.

    Please note, that usual mailbox permissions won't allow you to use the last variant of invocation, unless you are a super-user. Similarly, the last but one variant is also greatly affected by the permissions the target mailbox has.

    Unless you have started mail with `--norc' command line option, it will read the contents of the system-wide configuration file. Then it reads the contents of user configuration file, if any. See section Personal and system-wide configuration files for detailed description of these files. After this initial setup, `mail' displays the first page of header lines and enters interactive mode. In interactive mode, `mail' displays its prompt (`?', if not set otherwise) and executes the commands the user enters.

    Quitting the program

    Following commands quit the program:

    `quit'
    Terminates the session. If `mail' was operating upon user's system mailbox, then all undeleted and unsaved messages that have been read and are not marked with hold flag are saved to the user's mbox file (`$HOME/mbox'). The messages, marked with delete are removed. The program exits to the Shell, unless saving the mailbox fails, in which case user can escape with the exit command.
    `exit'
    `ex'
    `xit'
    Program exits to the Shell without modifying the mailbox it operates upon.

    Typing EOF (`C-D') alone is equivalent to `quit'.

    Obtaining online help

    Following commands can be used during the session to request online help:

    `help [command]'
    `hel [command]'
    `? [command]'
    Display detailed command synopsis. If no command is given, help for all available commands is displayed.
    `list'
    `*'
    Print a list of available commands.
    `version'
    `ve'
    Display program version.
    `warranty'
    `wa'
    Display program warranty statement.

    Moving within a mailbox

    `next'
    `n'
    Move to the next message.
    `previous'
    `prev'
    Move to the previous message.

    Changing mailbox/directory

    `cd [dir]'
    `chdir [dir]'
    `ch [dir]'
    Change to the specified directory. If dir is omitted, $HOME is assumed.
    `file [mailbox]'
    `fi [mailbox]'
    `folder [mailbox]'
    `fold [mailbox]'
    Read in the contents of the specified mailbox. The current mailbox is updated as if quit command has been issued. If mailbox is omitted, the command prints the current mailbox name followed by the summary information regarding it, e.g.:
    & fold
"/var/spool/mail/gray": 23 messages 22 unread

    Controlling header display

    To control which headers in the message should be displayed, `mail' keeps two lists: a retained header list and an ignored header list. If retained header list is not empty, only the header fields listed in it are displayed when printing the message. Otherwise, if ignored header list is not empty, only the headers not listed in this list are displayed. The uppercase variants of message-displaying commands can be used to print all the headers.

    The following commands modify and display the contents of both lists.

    `discard [header-field-list]'
    `di [header-field-list]'
    `ignore [header-field-list]'
    `ig [header-field-list]'
    Add header-field-list to the ignored list. When used without arguments, this command prints the contents of ignored list.
    `retain [header-field-list]'
    `ret [header-field-list]'
    Add header-field-list to the retained list. When used without arguments, this command prints the contents of retained list.

    Displaying information

    `='
    Displays the current message number.
    `headers [msglist]'
    `h [msglist]'
    Lists the current pageful of headers.
    `from [msglist]'
    `f [msglist]'
    Lists the contents of `From' headers for a given set of messages.
    `z [arg]'
    Presents message headers in pagefuls as described for headers command. When arg is `.', it is generally equivalent to headers. When arg is omitted or is `+', the next pageful of headers is displayed. If arg is `-', the previous pageful of headers is displayed. The latter two forms of z command may also take a numerical argument meaning the number of pages to skip before displaying the headers. For example:
    & z +2
    will skip two pages of messages before displaying the header summary.
    `size [msglist]'
    `si [msglist]'
    Lists the message number and message size in bytes for each message in msglist.
    `folders'
    Displays the value of folder variable.
    `summary'
    `su'
    Displays current mailbox summary. E.g.:
    & summary
"/var/spool/mail/gray": 23 messages 22 unread

    Displaying messages

    `print [msglist]'
    `p [msglist]'
    `type [msglist]'
    `t [msglist]'
    Prints out the messages from msglist. If the variable crt is set and the number of lines in the message is greater than the number of lines on screen, the message is piped through pager command specified by environment variable PAGER. The number of lines on screen is controlled by screen variable.
    `Print [msglist]'
    `P [msglist]'
    `Type [msglist]'
    `T [msglist]'
    Like print but also prints out ignored header fields. See section Controlling header display for detailed description of ignored header lists.
    `decode [msglist]'
    `dec [msglist]'
    Print a multipart message. The decode command decodes and prints out specified message parts. E.g.
    & decode 15[2]
+---------------------------------------
| Message=15[2]
| Type=message/delivery-status
| encoding=7bit
+---------------------------------------
Content-Type: message/delivery-status
...
    `top [msglist]'
    `to [msglist]'
    Prints the top few lines of each message in msglist. The number of lines printed is controlled by the variable toplines and defaults to five.
    `pipe [msglist] [shell-command]'
    `| [msglist] [shell-command]'
    Pipe the contents of specified messages through shell-command. If shell-command is empty but the string variable cmd is set, the value of this variable is used as a command name.

    Marking messages

    `tag [msglist]'
    `ta [msglist]'
    Tag messages. The tagged messages can be referred to in message list using `:t' notation.
    `untag [msglist]'
    `unt [msglist]'
    Clear tags from specified messages. To untag all messages tagged so far type
    & untag :t
    `hold [msglist]'
    `ho [msglist]'
    `preserve [msglist]'
    `pre [msglist]'
    Marks each message to be held in user's system mailbox. This command does not override the effect of delete command.

    Disposing of messages

    `delete [msglist]'
    `d [msglist]'
    Mark messages as deleted. Upon exiting with quit command these messages will be deleted from the mailbox. Until the end of current session the deleted messages can be referred to in message lists using :d notation.
    `undelete [msglist]'
    `u [msglist]'
    Clear delete mark from the specified messages.
    `dp [msglist]'
    `dt [msglist]'
    Deletes the current message and prints the next message. If msglist is specified, deletes all messages from the list and prints the message, immediately following last deleted one.

    Saving messages

    `save [[msglist] file]'
    `s [[msglist] file]'
    Takes a message list and a file name and appends each message in turn to the end of the file. The name of file and number of characters appended to it is echoed on the terminal. Each saved message is marked for deletion as if with delete command, unless the variable keepsave is set.
    `Save [msglist]'
    `S [msglist]'
    Like save, but the file to append messages to is named after the sender of the first message in msglist. For example:
    & from 14 15
 U  14 smith@noldor.arda.org Fri Jun 30 18:11  14/358   The Save c
 U  15 gray@noldor.arda.org  Fri Jun 30 18:30  8/245    Re: The Sa
& Save 14 15
"smith" 22/603
    i.e., 22 characters (603 lines) have been appended to the file "smith". If the file does not exist, it is created.
    `write [[msglist] file]'
    `w [[msglist] file]'
    Similar to save, except that only message body (without the header) is saved.
    `Write [msglist]'
    `W [msglist]'
    Similar to Save, except that only message body (without the header) is saved.
    `mbox [msglist]'
    `mb [msglist]'
    `touch [msglist]'
    `tou [msglist]'
    Mark list of messages to be saved in the user's mailbox ($HOME/mbox) upon exiting via quit command. This is the default action for all read messages, unless you have variable hold set.
    `copy [[msglist] file]'
    `c [[msglist] file]'
    Similar to save, except that saved messages are not marked for deletion.
    `Copy [msglist]'
    `C [msglist]'
    Similar to Save, except that saved messages are not marked for deletion.

    Editing messages

    These command allow to edit messages in a mailbox. Please note, that modified messages currently do not replace original ones. i.e. you have to save them explicitly using your editor's save command if you do not want the effects of your editing to be lost.

    `edit [msglist]'
    `e [msglist]'
    Edits each message in msglist with the editor, specified in EDITOR environment variable.
    `visual [msglist]'
    `v [msglist]'
    Edits each message in msglist with the editor, specified in VISUAL environment variable.

    Scripting

    Comments

    The `#' character introduces an end-of-line comment. All characters until and including the end of line are ignored.

    Displaying arbitrary text

    The `echo' (`ec') command prints its arguments to stdout.

    Sourcing external command files

    The command `source filename' reads commands from the named file. Its minimal abbreviation is `so'.

    Setting and unsetting the variables.

    The mail variables may be set using `set' (`se') command. The command takes a list of assignments. The syntax of an assignment is

    `name=string'
    Assign a string value to the variable. If string contains whitespace characters it must be enclosed in a pair of double-quote characters (`"')
    `name=number'
    Assign a numeric value to the variable.
    `name'
    Assign boolean True value.
    `noname'
    Assign boolean False value.

    Example:

    & set askcc nocrt indentprefix="> "

    This statement sets askcc to True, crt to False, and indentprefix to "> ".

    To unset mail variables use `unset'(`uns') command. The command takes a list of variable names to unset.

    Example: To undo the effect of the previous example, do:

    & unset askcc crt indentprefix

    Conditional statements

    The conditional statement allows to execute a set of mail commands depending on the mode the `mail' program is in. The conditional statement is:

    if cond
...
else
...
endif

    where `...' represents the set of commands to be executed in each branch of the statement. cond can be one of the following:

    `s'
    True if `mail' is operating in mail sending mode.
    `r'
    True if `mail' is operating in mail reading mode.
    `t'
    True if stdout is a terminal device (as opposed to a regular file).

    The conditional statements can be nested to arbitrary depth. The minimal abbreviations for `if', `else' and `endif' commands are `i', `el' and `en'.

    Example:

    if t
set crt prompt="& "
else
unset prompt
endif
if s
alt gray@farlep.net gray@mirddin.farlep.net
set

    Aliasing

    `alias [alias [address...]]'
    `a [alias [address...]]'
    `group [alias [address...]]'
    `g [alias [address...]]'
    With no arguments, prints out all currently-defined aliases. With one argument, prints out that alias. With more than one argument, creates a new alias or changes an old one.
    `unalias [alias...]'
    `una [alias...]'
    Takes a list of names defined by alias commands and discards the remembered groups of users. The alias names no longer have any significance.
    `alternates name...'
    `alt name...'
    The alternates command is useful if you have accounts on several machines. It can be used to inform mail that the listed addresses are really you. When you reply to messages, mail will not send a copy of the message to any of the addresses listed on the alternates list. If the alternates command is given with no argument, the current set of alternate names is displayed.

    Replying

    `mail [address...]'
    `m [address...]'
    Switches to compose mode. After composing the message, sends messages to the specified addresses.
    `reply [msglist]'
    `respond [msglist]'
    `r [msglist]'
    For each message in msglist, switches to compose mode and sends the composed message to the sender and all recipients of the message.
    `Reply [msglist]'
    `Respond [msglist]'
    `R [msglist]'
    Like reply, except that the composed message is sent only to originators of the specified messages.
    `followup [msglist]'
    `fo [msglist]'
    Switches to compose mode. After composing, sends the message to the originators and recipients of all messages in msglist.
    `Followup [msglist]'
    `F [msglist]'
    Similar to followup, but reply message is sent only to originators of messages in msglist.

    Incorporating new mail

    The incorporate (inc) command incorporates newly arrived messages to the displayed list of messages. This is done automatically before returning to `mail' command prompt if the variable autoinc is set.

    Shell escapes

    To run arbitrary shell command from `mail' command prompt, use shell (sh) command. If no arguments are specified, the command starts the user login shell. Otherwise, it uses its first argument as a file name to execute and all subsequent arguments are passed as positional parameters to this command. The shell command can also be spelled as !.

    How to alter the behavior of mail

    Following variables control the behavior of GNU `mail':

    Sign

    Type: String.
    Default: Unset. Contains the filename holding users signature. The contents of this file is appended to the end of a message being composed by ~A escape.
    appenddeadletter

    Type: Boolean.
    Default: False. If this variable is True, the contents of canceled letter is appended to the user's `dead.letter' file. Otherwise it overwrites its contents.
    askbcc

    Type: Boolean.
    Default: False. When set to True the user will be prompted to enter Bcc field before composing the message.
    askcc

    Type: Boolean.
    Default: True. When set to True the user will be prompted to enter Cc field before composing the message.
    asksub

    Type: Boolean.
    Default: True in interactive mode, False otherwise. When set to True the user will be prompted to enter Subject field before composing the message.
    autoinc

    Type: Boolean.
    Default: True. Automatically incorporate newly arrived messages.
    autoprint

    Type: Boolean.
    Default: False. Causes the delete command to behave like dp - thus, after deleting a message, the next one will be typed automatically.
    cmd

    Type: String.
    Default: Unset. Contains default shell command for pipe.
    columns

    Type: Numeric.
    Default: Detected at startup by querying the terminal device. If this fails, the value of environment variable COLUMNS is used. This variable contains the number of columns on terminal screen.
    crt

    Type: Boolean.
    Default: True in interactive mode, False otherwise. If True, any messages with number of lines greater than number of lines on terminal screen (as determined by screen variable) will be printed using program set in the environment variable ENVIRON.
    dot

    Type: Boolean.
    Default: False. If True, causes `mail' to interpret a period alone on a line as the terminator of a message you are sending.
    escape

    Type: String.
    Default: ~ If defined, the first character of this option gives the character to denoting escapes.
    folder

    Type: String.
    Default: Unset. The name of the directory to use for storing folders of messages. If unset, $HOME is assumed.
    header

    Type: Boolean.
    Default: True, unless started with `--nosum' (`-N') option. Whether to run headers command automatically after entering interactive mode.
    hold

    Type: Boolean.
    Default: False. When set to True, the read or saved messages will be stored in user's mailbox (`$HOME/mbox'). Otherwise, they will be held in system mailbox also. This option is in effect only when operating upon user's system mailbox.
    ignore

    Type: Boolean.
    Default: False. When set to True, `mail' will ignore keyboard interrupts when composing messages. Otherwise an interrupt will be taken as a signal to abort composing.
    ignoreeof

    Type: Boolean.
    Default: False. Controls whether typing EOF character terminates the letter being composed.
    indentprefix

    Type: String.
    Default: "\t" (a tab character). String used by the ~m tilde escape for indenting quoted messages.
    keepsave

    Type: Boolean.
    Default: False. Controls whether saved messages should be kept in system mailbox too. This variable is in effect only when operating upon a user's system mailbox.
    metoo

    Type: Boolean.
    Default: False. Usually, when an alias is expanded that contains the sender, the sender is removed from the expansion. Setting this option causes the sender to be included in the group.
    mode

    Type: String.
    Default: The name of current operation mode. Setting this variable does not affect the operation mode of the program.
    noregex

    Type: Boolean.
    Default: False. Setting this to True enables use of regular expressions in `/.../' message specifications.
    outfolder

    Type: String.
    Default: Unset. Contains the directory in which files created by save, write, etc. commands will be stored. When unset, current directory is assumed.
    page

    Type: Boolean.
    Default: False. If set to True, the pipe command will emit a linefeed character after printing each message.
    prompt

    Type: String.
    Default: "? " Contains the command prompt sequence.
    quiet

    Type: Boolean.
    Default: False. When set, suppresses the output of the startup banner.
    quit

    Type: Boolean.
    Default: False, unless started with `--quit' (`-q') option. When set, causes keyboard interrupts to terminate the program.
    rc

    Type: Boolean.
    Default: True, unless started with `--norc' (`-N') option. When this variable is set, `mail' will read the system-wide configuration file upon startup. See section Personal and system-wide configuration files.
    record

    Type: String.
    Default: Unset. When set, any outgoing message will be saved to the named file.
    save

    Type: Boolean.
    Default: True. When set, the aborted messages will be stored in the user's `dead.file'. See also appenddeadletter.
    screen

    Type: Numeric.
    Default: Detected at startup by querying the terminal device. If this fails, the value of environment variable LINES is used. This variable contains the number of lines on terminal screen.
    sendmail

    Type: String.
    Default: sendmail:/usr/lib/sendmail Contains the URL of mail transport agent.
    sign

    Type: String.
    Default: Unset. Contains the user's signature. The contents of this variable is appended to the end of a message being composed by ~a escape. Use Sign variable, if your signature occupies more than one line.
    subject

    Type: String.
    Default: Unset. Contains default subject line. This will be used when asksub is off.
    toplines

    Type: Numeric.
    Default: 5 Number of lines to be displayed by top and Top commands.
    verbose

    Type: Boolean.
    Default: False. When set, the actual delivery of messages is displayed on the user's terminal.

    Personal and system-wide configuration files

    Upon startup, `mail' reads the contents of the two command files: the system-wide configuration file, and the user's configuration file. Each line read from these files is processed like a usual `mail' command.

    When run with `--norc' (`-N') option, `mail' does not read the contents of system-wide configuration file. The user's file, if it exists, is always processed.

    The user's configuration file is located in the user's home directory and is named `.mailrc'. The location and name of the system-wide configuration file is determined when configuring the package via `--with-mail-rc' option. It defaults to `sysconfdir/mail.rc'.

    messages -- Count the number of messages in a mailbox.

    Messages prints on standard output the number of messages contained in each folder specified in command line. If no folders are specified, it operates upon user's system mailbox. For each folder, the following output line is produced:

         Number of messages in folder: number

    where folder represents the folder name, number represents the number of messages.

    The program accepts following command line options:

    `-q'
    `--quite'
    `-s'
    `--silent'
    Be quiet. Display only number of messages per mailbox, without leading text.
    `-?'
    `--help'
    Output help message and exit.
    `--usage'
    Output short usage summary and exit.
    `-V'
    `--version'
    Output program version and exit.

    readmsg -- Extract messages from a folder.

    The program is currently in development

    sieve

    The program is currently in development

    guimb -- A mailbox scanning and processing language.

    `Guimb' is for mailboxes what `awk' is for text files. It processes mailboxes, applying the user-supplied scheme procedures to each of them in turn and saves the resulting output in mailbox format.

    Specifying Scheme Program to Execute

    The Scheme program or expression to be executed is passed to `guimb' via the following options:

    `-e'
    `--expression EXPR'
    Execute scheme expression.
    `-f'
    `--file PROGFILE'
    Read and execute program from PROGFILE.

    You can specify both of them. In this case, the PROGFILE is executed first.

    Specifying Mailboxes to Operate Upon

    There are four basic ways of passing mailboxes to `guimb'.

    guimb [OPTIONS] [mailbox...]
    The resulting mailbox is not saved, unless the user-supplied scheme program saves it.
    guimb [OPTIONS] --mailbox DEFMBOX
    The contents of DEFMBOX is processed and is replaced with the resulting mailbox contents. Useful for applying filters to user's mailbox.
    guimb [OPTIONS] --mailbox DEFMBOX mailbox [mailbox...]
    The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to DEFMBOX.
    guimb [OPTIONS] --user USER [mailbox...]
    The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to the user's system mailbox. This allows to use `guimb' as a mail delivery agent.

    If no mailboxes are specified in the command line, `guimb' reads and processes its standard input.

    Passing Options to Scheme

    Sometimes it is necessary to pass some command line options to the scheme procedure. This can be done via `-g' (`--guile-command') command line option. For example:

    guimb --guile-command -opt --guile-command 24 --file progfile

    In this example, the scheme procedure will see the following command line:

    progfile -opt 24

    If there are many arguments to be passed to Scheme, it is more convenient to enclose them in `-{' and `-}' escapes:

    guimb -{ -opt 24 -} --file progfile

    All arguments enclosed between `-{' and `-}' are not processed by `guimb', they are instead passed to the Scheme program verbatim.

    Guimb Invocation Summary

    This is a short summary of the command line options available to `guimb'.

    `-d'
    `--debug'
    Start with debugging evaluator and backtraces.
    `-e EXPR'
    `--expression EXPR'
    Execute given Scheme expression.
    `-f PROGFILE'
    `--file PROGFILE'
    Read Scheme program from PROGFILE.
    `-g ARG'
    `--guile-command ARG'
    Append ARG to the command line passed to Scheme program.
    `-{ ... -}'
    Pass all command line options enclosed between `-{' and `-}' to Scheme program.
    `-m'
    `--mailbox MBOX'
    Set default mailbox name.
    `-u'
    `--user NAME'
    Act as local MDA for user NAME.
    `-h'
    `--help'
    Display help message.
    `-v'
    `--version'
    Display program version.

    Scheme Procedures and Variables

    Address Functions

    mu-address-get-personal: ADDRESS NUM
    Return personal part of an email address.

    mu-address-get-comments: ADDRESS NUM

    mu-address-get-email: ADDRESS NUM
    Return email part of an email address.

    mu-address-get-domain: ADDRESS NUM
    Return domain part of an email address

    mu-address-get-local: ADDRESS NUM
    Return local part of an email address.

    mu-address-get-count: ADDRESS
    Return number of parts in email address.

    Mailbox Functions

    mu-mailbox-open: URL MODE
    Opens a mailbox specified by URL.

    mu-mailbox-close: MBOX
    Closes mailbox MBOX

    mu-mailbox-get-url: MBOX
    Returns the URL of the mailbox.

    mu-mailbox-get-port: MBOX MODE
    Returns a port associated with the contents of the MBOX. MODE is a string defining operation mode of the stream. It may contain any of the two characters: `r' for reading, `w' for writing.

    mu-mailbox-get-message: MBOX MSGNO
    Retrieve from MBOX message # MSGNO.

    mu-mailbox-messages-count: MBOX
    Returns number of messages in the mailbox.

    mu-mailbox-expunge: MBOX
    Expunges deleted messages from the mailbox.

    mu-mailbox-url: MBOX
    Returns the URL of the mailbox

    mu-mailbox-append-message: MBOX MESG
    Appends the message to the mailbox

    Message Functions

    mu-message-copy: MESG
    Creates the copy of the given message.

    mu-message-set-header: MESG HEADER VALUE REPLACE
    Sets new VALUE to the header HEADER of the message MESG. If the HEADER is already present in the message its value is replaced with the supplied one if the optional REPLACE is #t. Otherwise new header is created and appended.

    mu-message-get-size: MESG
    Returns the size of the given message.

    mu-message-get-lines: MESG
    Returns number of lines in the given message.

    mu-message-get-sender: MESG
    Returns the sender email address for the message MESG.

    mu-message-get-header: MESG HEADER
    Returns the header value of the HEADER in the MESG.

    mu-message-get-header-fields: MESG HEADERS
    Returns the list of headers in the MESG. If optional HEADERS is specified it should be a list of header names to restrict return value to.

    mu-message-set-header-fields: MESG LIST REPLACE
    Set the headers in the message MESG from LIST LIST is a list of (cons HEADER VALUE) Optional parameter REPLACE specifies whether the new header values should replace the headers already present in the message.

    mu-message-delete: MESG FLAG
    Mark given message as deleted. Optional FLAG allows to toggle deleted mark The message is deleted if it is #t and undeleted if it is #f

    mu-message-get-flag: MESG FLAG
    Return value of the attribute FLAG.

    mu-message-set-flag: MESG FLAG VALUE
    Set the given attribute of the message. If optional VALUE is #f, the attribute is unset.

    mu-message-get-user-flag: MESG FLAG
    Returns value of the user attribute FLAG.

    mu-message-set-user-flag: MESG FLAG VALUE
    Set the given user attribute of the message. If optional VALUE is #f, the attribute is unset.

    mu-message-get-port: MESG MODE FULL
    Returns a port associated with the given MESG. MODE is a string defining operation mode of the stream. It may contain any of the two characters: `r' for reading, `w' for writing. If optional FULL argument specified, it should be a boolean value. If it is #t then the returned port will allow access to any part of the message (including headers). If it is #f then the port accesses only the message body (the default).

    mu-message-get-body: MESG
    Returns the message body for the message MESG.

    mu-message-send: MESG MAILER
    Sends the message MESG. Optional MAILER overrides default mailer settings in mu-mailer.

    MIME Functions

    mu-mime-create: FLAGS MESG
    Creates a new MIME object.

    mu-mime-multipart?: MIME
    Returns #t if MIME is a multipart object.

    mu-mime-get-num-parts: MIME
    Returns number of parts in a MIME object.

    mu-mime-get-part: MIME PART
    Returns part number PART from a MIME object.

    mu-mime-add-part: MIME MESG
    Adds MESG to the MIME object.

    mu-mime-get-message: MIME
    Converts MIME object to a message.

    Log Functions

    mu-openlog: IDENT OPTION FACILITY
    Opens a connection to the system logger for Guile program.

    mu-logger: PRIO TEXT
    Generates a log message to be distributed via syslogd.

    mu-closelog:
    Closes the channel to the system logger open by mu-openlog.

    Reporting Bugs

    Email bug reports to bug-mailutils@gnu.org. Be sure to include the word "mailutils" somewhere in the "Subject:" field.

    Acknowledgement

    In no particular order, Jakob Kaivo jkaivo@ndn.net, Jeff Bailey jbailey@gnu.org, Sean Perry shaleh@debian.org, Thomas Fletcher thomasf@qnx.com, Dave Inglis dinglis@qnx.com, Brian Edmond briane@qnx.com, Sam Roberts sroberts@uniserve.com, Sergey Poznyakoff gray@Mirddin.farlep.net, Fran@,{c}ois Pinard pinard@IRO.UMontreal.CA.

    Concept Index

    This is a general index of all issues discussed in this manual

    a

  • Acknowledgement
  • Address
  • address_t
  • Attribute
  • Authenticator

    • b

  • Body

    • c

  • Concrete API

    • e

  • Envelope

    • f

  • Folder
  • Framework

    • h

  • Headers

    • i

  • IMAP4
  • IMAP4 Append
  • IMAP4 Capability
  • IMAP4 Check
  • IMAP4 Close
  • IMAP4 Copy
  • IMAP4 Create
  • IMAP4 Delete
  • IMAP4 Examine
  • IMAP4 Expunge
  • IMAP4 Fetch
  • IMAP4 Initialization
  • IMAP4 List
  • IMAP4 Lsub
  • IMAP4 Namespace
  • IMAP4 Rename
  • IMAP4 Search
  • IMAP4 Select
  • IMAP4 Status
  • IMAP4 Store
  • IMAP4 Subscribe
  • IMAP4 UID Copy
  • IMAP4 UID Fetch
  • IMAP4 UID Search
  • IMAP4 UID Store
  • IMAP4 Unsubscribe
  • Introduction
  • Iterator

    • l

  • Locker

    • m

  • Mailbox
  • mailbox_t
  • Maildir
  • Mailer
  • Mbox
  • Mbox channel
  • Mbox Initialization
  • Message
  • Mh

    • n

  • NNTP
  • NNTP Article
  • NNTP Body
  • NNTP Group
  • NNTP Head
  • NNTP Help
  • NNTP IHave
  • NNTP Initialization
  • NNTP Last
  • NNTP List
  • NNTP NewGroups
  • NNTP NewNews
  • NNTP Next
  • NNTP Post
  • NNTP Quit
  • NNTP Slave
  • NNTP Stat

    • p

  • Parse822
  • POP3
  • POP3 Apop
  • POP3 Capa
  • POP3 channel
  • POP3 Dele
  • POP3 Initialization
  • POP3 List
  • POP3 Noop
  • POP3 Pass
  • POP3 Quit
  • POP3 Retr
  • POP3 Rset
  • POP3 Stat
  • Pop3 Timeout
  • POP3 Top
  • POP3 Uidl
  • POP3 User
  • pop3_t
  • Programs

    • r

  • Reporting Bugs

    • s

  • Sendmail
  • SMTP
  • SMTP Data
  • SMTP Expn
  • SMTP Helo
  • SMTP Help
  • SMTP Help functions
  • SMTP Initialization
  • SMTP Mail From
  • SMTP Noop
  • SMTP Quit
  • SMTP Recpt To
  • SMTP Reset
  • SMTP Verify
  • smtp_t
  • Stream
  • struct pop3_list

    • u

  • URL

    • Index

    This is an alphabetical list of all MAILUTILS functions.

    • a

  • ADDRESS, ADDRESS, ADDRESS, ADDRESS, ADDRESS, ADDRESS
  • address_create
  • address_destroy
  • address_get_comments
  • address_get_count
  • address_get_domain
  • address_get_email, address_get_email
  • address_get_local_part
  • address_get_personal
  • address_get_route
  • address_is_group
  • address_to_string
  • attribute_copy
  • attribute_create
  • attribute_destroy
  • attribute_is_answered
  • attribute_is_deleted
  • attribute_is_draft
  • attribute_is_equal
  • attribute_is_flagged
  • attribute_is_read
  • attribute_is_recent
  • attribute_is_seen
  • attribute_set_answered
  • attribute_set_deleted
  • attribute_set_draft
  • attribute_set_flagged
  • attribute_set_read
  • attribute_set_recent
  • attribute_set_seen
  • attribute_to_string
  • attribute_unset_answered
  • attribute_unset_deleted
  • attribute_unset_draft
  • attribute_unset_flagged
  • attribute_unset_read
  • attribute_unset_recent
  • attribute_unset_seen
  • auth_authenticate
  • auth_create
  • auth_destroy
  • auth_epilogue
  • auth_prologue

    • b

  • body_create
  • body_destroy
  • body_get_filename
  • body_get_stream
  • body_lines
  • body_set_filename
  • body_set_stream
  • body_size

    • c

  • char*

    • d

  • decoder_stream_create

    • e

  • encoder_stream_create
  • envelope_create
  • envelope_date
  • envelope_destroy
  • envelope_get_message
  • envelope_sender
  • envelope_set_date
  • envelope_set_sender

    • f

  • file_stream_create
  • FLAGS
  • folder_close
  • folder_create
  • folder_delete
  • folder_destroy
  • folder_get_authority
  • folder_get_debug
  • folder_get_observable
  • folder_get_stream
  • folder_get_url
  • folder_list
  • folder_lsub
  • folder_open
  • folder_rename
  • folder_set_authority
  • folder_set_debug
  • folder_set_stream
  • folder_set_url
  • folder_subscribe
  • folder_unsubscribe

    • h

  • header_aget_value
  • header_create
  • header_destroy
  • header_get_stream
  • header_get_value
  • header_set_lines
  • header_set_size
  • header_set_value

    • i

  • IDENT
  • imap4_append
  • imap4_capability
  • imap4_check
  • imap4_close
  • imap4_copy
  • imap4_create
  • imap4_create_mailbox
  • imap4_delete
  • imap4_examine
  • imap4_expunge
  • imap4_fetch
  • imap4_list
  • imap4_lsub
  • imap4_namespace
  • imap4_open
  • imap4_rename
  • imap4_search
  • imap4_select
  • imap4_status
  • imap4_store
  • imap4_subscribe
  • imap4_uid_copy
  • imap4_uid_fetch
  • imap4_uid_search
  • imap4_uid_store
  • imap4_unsubscribe
  • imap4d_set_timeout
  • int, int, int, int, int
  • iterator_create
  • iterator_current
  • iterator_destroy
  • iterator_first
  • iterator_is_done
  • iterator_next

    • l

  • locker_create
  • locker_destroy
  • locker_lock
  • locker_touchlock
  • locker_unlock

    • m

  • mailbox_append_message
  • mailbox_close
  • mailbox_create
  • mailbox_create_default
  • mailbox_destroy
  • mailbox_expunge
  • mailbox_get_debug
  • mailbox_get_folder
  • mailbox_get_locker
  • mailbox_get_message
  • mailbox_get_observable
  • mailbox_get_property
  • mailbox_get_size
  • mailbox_get_stream
  • mailbox_get_ticket
  • mailbox_get_url
  • mailbox_is_modified
  • mailbox_message_unseen
  • mailbox_messages_count
  • mailbox_messages_recent
  • mailbox_open
  • mailbox_scan
  • mailbox_set_locker
  • mailbox_set_stream
  • mailbox_set_ticket
  • mailbox_uidnext
  • mailbox_uidvalidity
  • mailer_close
  • mailer_create
  • mailer_destroy
  • mailer_get_debug
  • mailer_get_observable
  • mailer_get_property
  • mailer_get_stream
  • mailer_get_url
  • mailer_open
  • mailer_send_message
  • mailer_set_debug
  • mailer_set_stream
  • mapfile_stream_create
  • MBOX, MBOX, MBOX, MBOX, MBOX, MBOX, MBOX, MBOX
  • mbox_append
  • mbox_append_hb
  • mbox_close
  • mbox_create
  • mbox_destroy
  • mbox_expunge
  • mbox_get_attribute
  • mbox_get_bstream
  • mbox_get_carrier
  • mbox_get_hstream
  • mbox_get_separator
  • mbox_get_size
  • mbox_mak_deleted
  • mbox_open
  • mbox_save
  • mbox_scan
  • mbox_set_blines
  • mbox_set_bsize
  • mbox_set_bstream
  • mbox_set_carrier
  • mbox_set_hlines
  • mbox_set_hsize
  • mbox_set_hstream
  • mbox_set_newmsg_cb
  • mbox_set_progress_cb
  • mbox_set_separator
  • mbox_uidnext
  • mbox_uidvalidity
  • mbox_unmak_deleted
  • MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG, MESG
  • message_create
  • message_create_attachment
  • message_destroy
  • message_encapsulate
  • message_get_attribute
  • message_get_body
  • message_get_envelope
  • message_get_header
  • message_get_num_parts
  • message_get_observable
  • message_get_part
  • message_get_stream
  • message_get_uid
  • message_get_uidl
  • message_is_multipart
  • message_save_attachment
  • message_set_attribute
  • message_set_body
  • message_set_envelope
  • message_set_header
  • message_set_stream
  • message_set_uidl
  • message_unencapsulate
  • MIME, MIME, MIME, MIME, MIME
  • MU_STREAM_APPEND
  • MU_STREAM_CREAT
  • MU_STREAM_NO_CHECK
  • MU_STREAM_NONBLOCK
  • MU_STREAM_RDWR
  • MU_STREAM_READ
  • MU_STREAM_WRITE

    • n

  • nntp_article
  • nntp_body
  • nntp_create
  • nntp_destroy
  • nntp_group
  • nntp_head
  • nntp_help
  • nntp_ihave
  • nntp_last
  • nntp_list
  • nntp_newgroups
  • nntp_newnews
  • nntp_next
  • nntp_open
  • nntp_post
  • nntp_quit
  • nntp_slave
  • nntp_stat

    • p

  • parse822_addr_spec
  • parse822_address
  • parse822_address_list
  • parse822_domain
  • parse822_domain_literal
  • parse822_domain_ref
  • parse822_field_body
  • parse822_field_name
  • parse822_group
  • parse822_local_part
  • parse822_mail_box
  • parse822_quote_local_part
  • parse822_quote_string
  • parse822_route
  • parse822_route_addr
  • parse822_sub_domain
  • parse822_unix_mbox
  • pop3_apop
  • pop3_capa
  • pop3_connect
  • pop3_create
  • pop3_dele
  • pop3_destroy
  • pop3_get_carrier
  • pop3_get_timeout
  • pop3_list
  • pop3_list_all
  • pop3_list_current
  • pop3_noop
  • pop3_pass
  • pop3_quit
  • pop3_response
  • pop3_retr
  • pop3_rset
  • pop3_send
  • pop3_sendline
  • pop3_set_carrier
  • pop3_set_timeout
  • pop3_stat
  • pop3_top
  • pop3_uidl
  • pop3_uidl_all
  • pop3_uidl_current
  • pop3_user
  • pop3_writeline
  • PRIO

    • s

  • smtp_create
  • smtp_data
  • smtp_destroy
  • smtp_ehlo
  • smtp_expn
  • smtp_helo
  • smtp_help
  • smtp_mail_from
  • smtp_noop
  • smtp_open
  • smtp_quit
  • smtp_rcpt_to
  • smtp_reset
  • smtp_verify
  • stream_close
  • stream_create
  • stream_destroy
  • stream_flush
  • stream_get_fd
  • stream_get_flags
  • stream_get_state
  • stream_open
  • stream_read
  • stream_readline
  • stream_size
  • stream_truncate
  • stream_write
  • string_to_attribute

    • t

  • tcp_stream_create

    • u

  • URL
  • url_create
  • url_decode
  • url_destroy
  • url_get_host
  • url_get_passwd
  • url_get_path
  • url_get_port
  • url_get_query
  • url_get_scheme
  • url_get_user
  • url_parse

    • Footnotes

    (1)

    Caution: Although the RFC 1939 specifies that the minimum default timeout is ten minutes many servers has shorter idle period, care should be taken to at least send a pop3_noop () between lengthy period of times.

    (2)

    Caution: Some Internet Service Providers do not permit to leave mail on server and the message will be deleted once downloaded.

    This document was generated on 19 October 2001 using the texi2html translator version 1.54.


GNU Make

A Program for Directing Recompilation

GNU make Version 3.79

April 2000

Richard M. Stallman and Roland McGrath

Table of Contents

  • Overview of make
    • How to Read This Manual
    • Problems and Bugs
  • An Introduction to Makefiles
    • What a Rule Looks Like
    • A Simple Makefile
    • How make Processes a Makefile
    • Variables Make Makefiles Simpler
    • Letting make Deduce the Commands
    • Another Style of Makefile
    • Rules for Cleaning the Directory
  • Writing Makefiles
    • What Makefiles Contain
    • What Name to Give Your Makefile
    • Including Other Makefiles
    • The Variable MAKEFILES
    • How Makefiles Are Remade
    • Overriding Part of Another Makefile
    • How make Reads a Makefile
  • Writing Rules
    • Rule Syntax
    • Using Wildcard Characters in File Names
      • Wildcard Examples
      • Pitfalls of Using Wildcards
      • The Function wildcard
    • Searching Directories for Prerequisites
      • VPATH: Search Path for All Prerequisites
      • The vpath Directive
      • How Directory Searches are Performed
      • Writing Shell Commands with Directory Search
      • Directory Search and Implicit Rules
      • Directory Search for Link Libraries
    • Phony Targets
    • Rules without Commands or Prerequisites
    • Empty Target Files to Record Events
    • Special Built-in Target Names
    • Multiple Targets in a Rule
    • Multiple Rules for One Target
    • Static Pattern Rules
      • Syntax of Static Pattern Rules
      • Static Pattern Rules versus Implicit Rules
    • Double-Colon Rules
    • Generating Prerequisites Automatically
  • Writing the Commands in Rules
    • Command Echoing
    • Command Execution
    • Parallel Execution
    • Errors in Commands
    • Interrupting or Killing make
    • Recursive Use of make
      • How the MAKE Variable Works
      • Communicating Variables to a Sub-make
      • Communicating Options to a Sub-make
      • The `--print-directory' Option
    • Defining Canned Command Sequences
    • Using Empty Commands
  • How to Use Variables
    • Basics of Variable References
    • The Two Flavors of Variables
    • Advanced Features for Reference to Variables
      • Substitution References
      • Computed Variable Names
    • How Variables Get Their Values
    • Setting Variables
    • Appending More Text to Variables
    • The override Directive
    • Defining Variables Verbatim
    • Variables from the Environment
    • Target-specific Variable Values
    • Pattern-specific Variable Values
  • Conditional Parts of Makefiles
    • Example of a Conditional
    • Syntax of Conditionals
    • Conditionals that Test Flags
  • Functions for Transforming Text
    • Function Call Syntax
    • Functions for String Substitution and Analysis
    • Functions for File Names
    • The foreach Function
    • The if Function
    • The call Function
    • The origin Function
    • The shell Function
    • Functions That Control Make
  • How to Run make
    • Arguments to Specify the Makefile
    • Arguments to Specify the Goals
    • Instead of Executing the Commands
    • Avoiding Recompilation of Some Files
    • Overriding Variables
    • Testing the Compilation of a Program
    • Summary of Options
  • Using Implicit Rules
    • Using Implicit Rules
    • Catalogue of Implicit Rules
    • Variables Used by Implicit Rules
    • Chains of Implicit Rules
    • Defining and Redefining Pattern Rules
      • Introduction to Pattern Rules
      • Pattern Rule Examples
      • Automatic Variables
      • How Patterns Match
      • Match-Anything Pattern Rules
      • Canceling Implicit Rules
    • Defining Last-Resort Default Rules
    • Old-Fashioned Suffix Rules
    • Implicit Rule Search Algorithm
  • Using make to Update Archive Files
    • Archive Members as Targets
    • Implicit Rule for Archive Member Targets
      • Updating Archive Symbol Directories
    • Dangers When Using Archives
    • Suffix Rules for Archive Files
  • Features of GNU make
  • Incompatibilities and Missing Features
  • Makefile Conventions
    • General Conventions for Makefiles
    • Utilities in Makefiles
    • Variables for Specifying Commands
    • Variables for Installation Directories
    • Standard Targets for Users
    • Install Command Categories
  • Quick Reference
  • Errors Generated by Make
  • Complex Makefile Example
  • Index of Concepts
  • Index of Functions, Variables, & Directives

Overview of make

The make utility automatically determines which pieces of a large program need to be recompiled, and issues commands to recompile them. This manual describes GNU make, which was implemented by Richard Stallman and Roland McGrath. Development since Version 3.76 has been handled by Paul D. Smith.

GNU make conforms to section 6.2 of IEEE Standard 1003.2-1992 (POSIX.2).

Our examples show C programs, since they are most common, but you can use make with any programming language whose compiler can be run with a shell command. Indeed, make is not limited to programs. You can use it to describe any task where some files must be updated automatically from others whenever the others change.

To prepare to use make, you must write a file called the makefile that describes the relationships among files in your program and provides commands for updating each file. In a program, typically, the executable file is updated from object files, which are in turn made by compiling source files.

Once a suitable makefile exists, each time you change some source files, this simple shell command:

make

suffices to perform all necessary recompilations. The make program uses the makefile data base and the last-modification times of the files to decide which of the files need to be updated. For each of those files, it issues the commands recorded in the data base.

You can provide command line arguments to make to control which files should be recompiled, or how. See section How to Run make.

How to Read This Manual

If you are new to make, or are looking for a general introduction, read the first few sections of each chapter, skipping the later sections. In each chapter, the first few sections contain introductory or general information and the later sections contain specialized or technical information. The exception is section An Introduction to Makefiles, all of which is introductory.

If you are familiar with other make programs, see section Features of GNU make, which lists the enhancements GNU make has, and section Incompatibilities and Missing Features, which explains the few things GNU make lacks that others have.

For a quick summary, see section Summary of Options, section Quick Reference, and section Special Built-in Target Names.

Problems and Bugs

If you have problems with GNU make or think you've found a bug, please report it to the developers; we cannot promise to do anything but we might well want to fix it.

Before reporting a bug, make sure you've actually found a real bug. Carefully reread the documentation and see if it really says you can do what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation!

Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possible makefile that reproduces the problem. Then send us the makefile and the exact results make gave you. Also say what you expected to occur; this will help us decide whether the problem was really in the documentation.

Once you've got a precise problem, please send electronic mail to:

    bug-make@gnu.org

Please include the version number of make you are using. You can get this information with the command `make --version'. Be sure also to include the type of machine and operating system you are using. If possible, include the contents of the file `config.h' that is generated by the configuration process.

An Introduction to Makefiles

You need a file called a makefile to tell make what to do. Most often, the makefile tells make how to compile and link a program.

In this chapter, we will discuss a simple makefile that describes how to compile and link a text editor which consists of eight C source files and three header files. The makefile can also tell make how to run miscellaneous commands when explicitly asked (for example, to remove certain files as a clean-up operation). To see a more complex example of a makefile, see section Complex Makefile Example.

When make recompiles the editor, each changed C source file must be recompiled. If a header file has changed, each C source file that includes the header file must be recompiled to be safe. Each compilation produces an object file corresponding to the source file. Finally, if any source file has been recompiled, all the object files, whether newly made or saved from previous compilations, must be linked together to produce the new executable editor.

What a Rule Looks Like

A simple makefile consists of "rules" with the following shape:

target ... : prerequisites ...
        command
        ...
        ...

A target is usually the name of a file that is generated by a program; examples of targets are executable or object files. A target can also be the name of an action to carry out, such as `clean' (see section Phony Targets).

A prerequisite is a file that is used as input to create the target. A target often depends on several files.

A command is an action that make carries out. A rule may have more than one command, each on its own line. Please note: you need to put a tab character at the beginning of every command line! This is an obscurity that catches the unwary.

Usually a command is in a rule with prerequisites and serves to create a target file if any of the prerequisites change. However, the rule that specifies commands for the target need not have prerequisites. For example, the rule containing the delete command associated with the target `clean' does not have prerequisites.

A rule, then, explains how and when to remake certain files which are the targets of the particular rule. make carries out the commands on the prerequisites to create or update the target. A rule can also explain how and when to carry out an action. See section Writing Rules.

A makefile may contain other text besides rules, but a simple makefile need only contain rules. Rules may look somewhat more complicated than shown in this template, but all fit the pattern more or less.

A Simple Makefile

Here is a straightforward makefile that describes the way an executable file called edit depends on eight object files which, in turn, depend on eight C source and three header files.

In this example, all the C files include `defs.h', but only those defining editing commands include `command.h', and only low level files that change the editor buffer include `buffer.h'.

edit : main.o kbd.o command.o display.o \
       insert.o search.o files.o utils.o
        cc -o edit main.o kbd.o command.o display.o \
                   insert.o search.o files.o utils.o

main.o : main.c defs.h
        cc -c main.c
kbd.o : kbd.c defs.h command.h
        cc -c kbd.c
command.o : command.c defs.h command.h
        cc -c command.c
display.o : display.c defs.h buffer.h
        cc -c display.c
insert.o : insert.c defs.h buffer.h
        cc -c insert.c
search.o : search.c defs.h buffer.h
        cc -c search.c
files.o : files.c defs.h buffer.h command.h
        cc -c files.c
utils.o : utils.c defs.h
        cc -c utils.c
clean :
        rm edit main.o kbd.o command.o display.o \
           insert.o search.o files.o utils.o

We split each long line into two lines using backslash-newline; this is like using one long line, but is easier to read.

To use this makefile to create the executable file called `edit', type:

make

To use this makefile to delete the executable file and all the object files from the directory, type:

make clean

In the example makefile, the targets include the executable file `edit', and the object files `main.o' and `kbd.o'. The prerequisites are files such as `main.c' and `defs.h'. In fact, each `.o' file is both a target and a prerequisite. Commands include `cc -c main.c' and `cc -c kbd.c'.

When a target is a file, it needs to be recompiled or relinked if any of its prerequisites change. In addition, any prerequisites that are themselves automatically generated should be updated first. In this example, `edit' depends on each of the eight object files; the object file `main.o' depends on the source file `main.c' and on the header file `defs.h'.

A shell command follows each line that contains a target and prerequisites. These shell commands say how to update the target file. A tab character must come at the beginning of every command line to distinguish commands lines from other lines in the makefile. (Bear in mind that make does not know anything about how the commands work. It is up to you to supply commands that will update the target file properly. All make does is execute the commands in the rule you have specified when the target file needs to be updated.)

The target `clean' is not a file, but merely the name of an action. Since you normally do not want to carry out the actions in this rule, `clean' is not a prerequisite of any other rule. Consequently, make never does anything with it unless you tell it specifically. Note that this rule not only is not a prerequisite, it also does not have any prerequisites, so the only purpose of the rule is to run the specified commands. Targets that do not refer to files but are just actions are called phony targets. See section Phony Targets, for information about this kind of target. See section Errors in Commands, to see how to cause make to ignore errors from rm or any other command.

How make Processes a Makefile

By default, make starts with the first target (not targets whose names start with `.'). This is called the default goal. (Goals are the targets that make strives ultimately to update. See section Arguments to Specify the Goals.)

In the simple example of the previous section, the default goal is to update the executable program `edit'; therefore, we put that rule first.

Thus, when you give the command:

make

make reads the makefile in the current directory and begins by processing the first rule. In the example, this rule is for relinking `edit'; but before make can fully process this rule, it must process the rules for the files that `edit' depends on, which in this case are the object files. Each of these files is processed according to its own rule. These rules say to update each `.o' file by compiling its source file. The recompilation must be done if the source file, or any of the header files named as prerequisites, is more recent than the object file, or if the object file does not exist.

The other rules are processed because their targets appear as prerequisites of the goal. If some other rule is not depended on by the goal (or anything it depends on, etc.), that rule is not processed, unless you tell make to do so (with a command such as make clean).

Before recompiling an object file, make considers updating its prerequisites, the source file and header files. This makefile does not specify anything to be done for them--the `.c' and `.h' files are not the targets of any rules--so make does nothing for these files. But make would update automatically generated C programs, such as those made by Bison or Yacc, by their own rules at this time.

After recompiling whichever object files need it, make decides whether to relink `edit'. This must be done if the file `edit' does not exist, or if any of the object files are newer than it. If an object file was just recompiled, it is now newer than `edit', so `edit' is relinked.

Thus, if we change the file `insert.c' and run make, make will compile that file to update `insert.o', and then link `edit'. If we change the file `command.h' and run make, make will recompile the object files `kbd.o', `command.o' and `files.o' and then link the file `edit'.

Variables Make Makefiles Simpler

In our example, we had to list all the object files twice in the rule for `edit' (repeated here):

edit : main.o kbd.o command.o display.o \
              insert.o search.o files.o utils.o
        cc -o edit main.o kbd.o command.o display.o \
                   insert.o search.o files.o utils.o

Such duplication is error-prone; if a new object file is added to the system, we might add it to one list and forget the other. We can eliminate the risk and simplify the makefile by using a variable. Variables allow a text string to be defined once and substituted in multiple places later (see section How to Use Variables).

It is standard practice for every makefile to have a variable named objects, OBJECTS, objs, OBJS, obj, or OBJ which is a list of all object file names. We would define such a variable objects with a line like this in the makefile:

objects = main.o kbd.o command.o display.o \
          insert.o search.o files.o utils.o

Then, each place we want to put a list of the object file names, we can substitute the variable's value by writing `$(objects)' (see section How to Use Variables).

Here is how the complete simple makefile looks when you use a variable for the object files:

objects = main.o kbd.o command.o display.o \
          insert.o search.o files.o utils.o

edit : $(objects)
        cc -o edit $(objects)
main.o : main.c defs.h
        cc -c main.c
kbd.o : kbd.c defs.h command.h
        cc -c kbd.c
command.o : command.c defs.h command.h
        cc -c command.c
display.o : display.c defs.h buffer.h
        cc -c display.c
insert.o : insert.c defs.h buffer.h
        cc -c insert.c
search.o : search.c defs.h buffer.h
        cc -c search.c
files.o : files.c defs.h buffer.h command.h
        cc -c files.c
utils.o : utils.c defs.h
        cc -c utils.c
clean :
        rm edit $(objects)

Letting make Deduce the Commands

It is not necessary to spell out the commands for compiling the individual C source files, because make can figure them out: it has an implicit rule for updating a `.o' file from a correspondingly named `.c' file using a `cc -c' command. For example, it will use the command `cc -c main.c -o main.o' to compile `main.c' into `main.o'. We can therefore omit the commands from the rules for the object files. See section Using Implicit Rules.

When a `.c' file is used automatically in this way, it is also automatically added to the list of prerequisites. We can therefore omit the `.c' files from the prerequisites, provided we omit the commands.

Here is the entire example, with both of these changes, and a variable objects as suggested above:

objects = main.o kbd.o command.o display.o \
          insert.o search.o files.o utils.o

edit : $(objects)
        cc -o edit $(objects)

main.o : defs.h
kbd.o : defs.h command.h
command.o : defs.h command.h
display.o : defs.h buffer.h
insert.o : defs.h buffer.h
search.o : defs.h buffer.h
files.o : defs.h buffer.h command.h
utils.o : defs.h

.PHONY : clean
clean :
        -rm edit $(objects)

This is how we would write the makefile in actual practice. (The complications associated with `clean' are described elsewhere. See section Phony Targets, and section Errors in Commands.)

Because implicit rules are so convenient, they are important. You will see them used frequently.

Another Style of Makefile

When the objects of a makefile are created only by implicit rules, an alternative style of makefile is possible. In this style of makefile, you group entries by their prerequisites instead of by their targets. Here is what one looks like:

objects = main.o kbd.o command.o display.o \
          insert.o search.o files.o utils.o

edit : $(objects)
        cc -o edit $(objects)

$(objects) : defs.h
kbd.o command.o files.o : command.h
display.o insert.o search.o files.o : buffer.h

Here `defs.h' is given as a prerequisite of all the object files; `command.h' and `buffer.h' are prerequisites of the specific object files listed for them.

Whether this is better is a matter of taste: it is more compact, but some people dislike it because they find it clearer to put all the information about each target in one place.

Rules for Cleaning the Directory

Compiling a program is not the only thing you might want to write rules for. Makefiles commonly tell how to do a few other things besides compiling a program: for example, how to delete all the object files and executables so that the directory is `clean'.

Here is how we could write a make rule for cleaning our example editor:

clean:
        rm edit $(objects)

In practice, we might want to write the rule in a somewhat more complicated manner to handle unanticipated situations. We would do this:

.PHONY : clean
clean :
        -rm edit $(objects)

This prevents make from getting confused by an actual file called `clean' and causes it to continue in spite of errors from rm. (See section Phony Targets, and section Errors in Commands.)

A rule such as this should not be placed at the beginning of the makefile, because we do not want it to run by default! Thus, in the example makefile, we want the rule for edit, which recompiles the editor, to remain the default goal.

Since clean is not a prerequisite of edit, this rule will not run at all if we give the command `make' with no arguments. In order to make the rule run, we have to type `make clean'. See section How to Run make.

Writing Makefiles

The information that tells make how to recompile a system comes from reading a data base called the makefile.

What Makefiles Contain

Makefiles contain five kinds of things: explicit rules, implicit rules, variable definitions, directives, and comments. Rules, variables, and directives are described at length in later chapters.

  • An explicit rule says when and how to remake one or more files, called the rule's targets. It lists the other files that the targets depend on, call the prerequisites of the target, and may also give commands to use to create or update the targets. See section Writing Rules.
  • An implicit rule says when and how to remake a class of files based on their names. It describes how a target may depend on a file with a name similar to the target and gives commands to create or update such a target. See section Using Implicit Rules.
  • A variable definition is a line that specifies a text string value for a variable that can be substituted into the text later. The simple makefile example shows a variable definition for objects as a list of all object files (see section Variables Make Makefiles Simpler).
  • A directive is a command for make to do something special while reading the makefile. These include:
    • Reading another makefile (see section Including Other Makefiles).
    • Deciding (based on the values of variables) whether to use or ignore a part of the makefile (see section Conditional Parts of Makefiles).
    • Defining a variable from a verbatim string containing multiple lines (see section Defining Variables Verbatim).
  • `#' in a line of a makefile starts a comment. It and the rest of the line are ignored, except that a trailing backslash not escaped by another backslash will continue the comment across multiple lines. Comments may appear on any of the lines in the makefile, except within a define directive, and perhaps within commands (where the shell decides what is a comment). A line containing just a comment (with perhaps spaces before it) is effectively blank, and is ignored.

What Name to Give Your Makefile

By default, when make looks for the makefile, it tries the following names, in order: `GNUmakefile', `makefile' and `Makefile'.

Normally you should call your makefile either `makefile' or `Makefile'. (We recommend `Makefile' because it appears prominently near the beginning of a directory listing, right near other important files such as `README'.) The first name checked, `GNUmakefile', is not recommended for most makefiles. You should use this name if you have a makefile that is specific to GNU make, and will not be understood by other versions of make. Other make programs look for `makefile' and `Makefile', but not `GNUmakefile'.

If make finds none of these names, it does not use any makefile. Then you must specify a goal with a command argument, and make will attempt to figure out how to remake it using only its built-in implicit rules. See section Using Implicit Rules.

If you want to use a nonstandard name for your makefile, you can specify the makefile name with the `-f' or `--file' option. The arguments `-f name' or `--file=name' tell make to read the file name as the makefile. If you use more than one `-f' or `--file' option, you can specify several makefiles. All the makefiles are effectively concatenated in the order specified. The default makefile names `GNUmakefile', `makefile' and `Makefile' are not checked automatically if you specify `-f' or `--file'.

Including Other Makefiles

The include directive tells make to suspend reading the current makefile and read one or more other makefiles before continuing. The directive is a line in the makefile that looks like this:

include filenames...

filenames can contain shell file name patterns.

Extra spaces are allowed and ignored at the beginning of the line, but a tab is not allowed. (If the line begins with a tab, it will be considered a command line.) Whitespace is required between include and the file names, and between file names; extra whitespace is ignored there and at the end of the directive. A comment starting with `#' is allowed at the end of the line. If the file names contain any variable or function references, they are expanded. See section How to Use Variables.

For example, if you have three `.mk' files, `a.mk', `b.mk', and `c.mk', and $(bar) expands to bish bash, then the following expression

include foo *.mk $(bar)

is equivalent to

include foo a.mk b.mk c.mk bish bash

When make processes an include directive, it suspends reading of the containing makefile and reads from each listed file in turn. When that is finished, make resumes reading the makefile in which the directive appears.

One occasion for using include directives is when several programs, handled by individual makefiles in various directories, need to use a common set of variable definitions (see section Setting Variables) or pattern rules (see section Defining and Redefining Pattern Rules).

Another such occasion is when you want to generate prerequisites from source files automatically; the prerequisites can be put in a file that is included by the main makefile. This practice is generally cleaner than that of somehow appending the prerequisites to the end of the main makefile as has been traditionally done with other versions of make. See section Generating Prerequisites Automatically.

If the specified name does not start with a slash, and the file is not found in the current directory, several other directories are searched. First, any directories you have specified with the `-I' or `--include-dir' option are searched (see section Summary of Options). Then the following directories (if they exist) are searched, in this order: `prefix/include' (normally `/usr/local/include' (1)) `/usr/gnu/include', `/usr/local/include', `/usr/include'.

If an included makefile cannot be found in any of these directories, a warning message is generated, but it is not an immediately fatal error; processing of the makefile containing the include continues. Once it has finished reading makefiles, make will try to remake any that are out of date or don't exist. See section How Makefiles Are Remade. Only after it has tried to find a way to remake a makefile and failed, will make diagnose the missing makefile as a fatal error.

If you want make to simply ignore a makefile which does not exist and cannot be remade, with no error message, use the -include directive instead of include, like this:

-include filenames...

This is acts like include in every way except that there is no error (not even a warning) if any of the filenames do not exist. For compatibility with some other make implementations, sinclude is another name for -include.

The Variable MAKEFILES

If the environment variable MAKEFILES is defined, make considers its value as a list of names (separated by whitespace) of additional makefiles to be read before the others. This works much like the include directive: various directories are searched for those files (see section Including Other Makefiles). In addition, the default goal is never taken from one of these makefiles and it is not an error if the files listed in MAKEFILES are not found.

The main use of MAKEFILES is in communication between recursive invocations of make (see section Recursive Use of make). It usually is not desirable to set the environment variable before a top-level invocation of make, because it is usually better not to mess with a makefile from outside. However, if you are running make without a specific makefile, a makefile in MAKEFILES can do useful things to help the built-in implicit rules work better, such as defining search paths (see section Searching Directories for Prerequisites).

Some users are tempted to set MAKEFILES in the environment automatically on login, and program makefiles to expect this to be done. This is a very bad idea, because such makefiles will fail to work if run by anyone else. It is much better to write explicit include directives in the makefiles. See section Including Other Makefiles.

How Makefiles Are Remade

Sometimes makefiles can be remade from other files, such as RCS or SCCS files. If a makefile can be remade from other files, you probably want make to get an up-to-date version of the makefile to read in.

To this end, after reading in all makefiles, make will consider each as a goal target and attempt to update it. If a makefile has a rule which says how to update it (found either in that very makefile or in another one) or if an implicit rule applies to it (see section Using Implicit Rules), it will be updated if necessary. After all makefiles have been checked, if any have actually been changed, make starts with a clean slate and reads all the makefiles over again. (It will also attempt to update each of them over again, but normally this will not change them again, since they are already up to date.)

If you know that one or more of your makefiles cannot be remade and you want to keep make from performing an implicit rule search on them, perhaps for efficiency reasons, you can use any normal method of preventing implicit rule lookup to do so. For example, you can write an explicit rule with the makefile as the target, and an empty command string (see section Using Empty Commands).

If the makefiles specify a double-colon rule to remake a file with commands but no prerequisites, that file will always be remade (see section Double-Colon Rules). In the case of makefiles, a makefile that has a double-colon rule with commands but no prerequisites will be remade every time make is run, and then again after make starts over and reads the makefiles in again. This would cause an infinite loop: make would constantly remake the makefile, and never do anything else. So, to avoid this, make will not attempt to remake makefiles which are specified as targets of a double-colon rule with commands but no prerequisites.

If you do not specify any makefiles to be read with `-f' or `--file' options, make will try the default makefile names; see section What Name to Give Your Makefile. Unlike makefiles explicitly requested with `-f' or `--file' options, make is not certain that these makefiles should exist. However, if a default makefile does not exist but can be created by running make rules, you probably want the rules to be run so that the makefile can be used.

Therefore, if none of the default makefiles exists, make will try to make each of them in the same order in which they are searched for (see section What Name to Give Your Makefile) until it succeeds in making one, or it runs out of names to try. Note that it is not an error if make cannot find or make any makefile; a makefile is not always necessary.

When you use the `-t' or `--touch' option (see section Instead of Executing the Commands), you would not want to use an out-of-date makefile to decide which targets to touch. So the `-t' option has no effect on updating makefiles; they are really updated even if `-t' is specified. Likewise, `-q' (or `--question') and `-n' (or `--just-print') do not prevent updating of makefiles, because an out-of-date makefile would result in the wrong output for other targets. Thus, `make -f mfile -n foo' will update `mfile', read it in, and then print the commands to update `foo' and its prerequisites without running them. The commands printed for `foo' will be those specified in the updated contents of `mfile'.

However, on occasion you might actually wish to prevent updating of even the makefiles. You can do this by specifying the makefiles as goals in the command line as well as specifying them as makefiles. When the makefile name is specified explicitly as a goal, the options `-t' and so on do apply to them.

Thus, `make -f mfile -n mfile foo' would read the makefile `mfile', print the commands needed to update it without actually running them, and then print the commands needed to update `foo' without running them. The commands for `foo' will be those specified by the existing contents of `mfile'.

Overriding Part of Another Makefile

Sometimes it is useful to have a makefile that is mostly just like another makefile. You can often use the `include' directive to include one in the other, and add more targets or variable definitions. However, if the two makefiles give different commands for the same target, make will not let you just do this. But there is another way.

In the containing makefile (the one that wants to include the other), you can use a match-anything pattern rule to say that to remake any target that cannot be made from the information in the containing makefile, make should look in another makefile. See section Defining and Redefining Pattern Rules, for more information on pattern rules.

For example, if you have a makefile called `Makefile' that says how to make the target `foo' (and other targets), you can write a makefile called `GNUmakefile' that contains:

foo:
        frobnicate > foo

%: force
        @$(MAKE) -f Makefile $@
force: ;

If you say `make foo', make will find `GNUmakefile', read it, and see that to make `foo', it needs to run the command `frobnicate > foo'. If you say `make bar', make will find no way to make `bar' in `GNUmakefile', so it will use the commands from the pattern rule: `make -f Makefile bar'. If `Makefile' provides a rule for updating `bar', make will apply the rule. And likewise for any other target that `GNUmakefile' does not say how to make.

The way this works is that the pattern rule has a pattern of just `%', so it matches any target whatever. The rule specifies a prerequisite `force', to guarantee that the commands will be run even if the target file already exists. We give `force' target empty commands to prevent make from searching for an implicit rule to build it--otherwise it would apply the same match-anything rule to `force' itself and create a prerequisite loop!

How make Reads a Makefile

GNU make does its work in two distinct phases. During the first phase it reads all the makefiles, included makefiles, etc. and internalizes all the variables and their values, implicit and explicit rules, and constructs a dependency graph of all the targets and their prerequisites. During the second phase, make uses these internal structures to determine what targets will need to be rebuilt and to invoke the rules necessary to do so.

It's important to understand this two-phase approach because it has a direct impact on how variable and function expansion happens; this is often a source of some confusion when writing makefiles. Here we will present a summary of the phases in which expansion happens for different constructs within the makefile. We say that expansion is immediate if it happens during the first phase: in this case make will expand any variables or functions in that section of a construct as the makefile is parsed. We say that expansion is deferred if expansion is not performed immediately. Expansion of deferred construct is not performed until either the construct appears later in an immediate context, or until the second phase.

You may not be familiar with some of these constructs yet. You can reference this section as you become familiar with them, in later chapters.

Variable Assignment

Variable definitions are parsed as follows:

immediate = deferred
immediate ?= deferred
immediate := immediate
immediate += deferred or immediate

define immediate
  deferred
endef

For the append operator, `+=', the right-hand side is considered immediate if the variable was previously set as a simple variable (`:='), and deferred otherwise.

Conditional Syntax

All instances of conditional syntax are parsed immediately, in their entirety; this includes the ifdef, ifeq, ifndef, and ifneq forms.

Rule Definition

A rule is always expanded the same way, regardless of the form:

immediate : immediate ; deferred
    deferred

That is, the target and prerequisite sections are expanded immediately, and the commands used to construct the target are always deferred. This general rule is true for explicit rules, pattern rules, suffix rules, static pattern rules, and simple prerequisite definitions.

Writing Rules

A rule appears in the makefile and says when and how to remake certain files, called the rule's targets (most often only one per rule). It lists the other files that are the prerequisites of the target, and commands to use to create or update the target.

The order of rules is not significant, except for determining the default goal: the target for make to consider, if you do not otherwise specify one. The default goal is the target of the first rule in the first makefile. If the first rule has multiple targets, only the first target is taken as the default. There are two exceptions: a target starting with a period is not a default unless it contains one or more slashes, `/', as well; and, a target that defines a pattern rule has no effect on the default goal. (See section Defining and Redefining Pattern Rules.)

Therefore, we usually write the makefile so that the first rule is the one for compiling the entire program or all the programs described by the makefile (often with a target called `all'). See section Arguments to Specify the Goals.

Rule Syntax

In general, a rule looks like this:

targets : prerequisites
        command
        ...

or like this:

targets : prerequisites ; command
        command
        ...

The targets are file names, separated by spaces. Wildcard characters may be used (see section Using Wildcard Characters in File Names) and a name of the form `a(m)' represents member m in archive file a (see section Archive Members as Targets). Usually there is only one target per rule, but occasionally there is a reason to have more (see section Multiple Targets in a Rule).

The command lines start with a tab character. The first command may appear on the line after the prerequisites, with a tab character, or may appear on the same line, with a semicolon. Either way, the effect is the same. See section Writing the Commands in Rules.

Because dollar signs are used to start variable references, if you really want a dollar sign in a rule you must write two of them, `$$' (see section How to Use Variables). You may split a long line by inserting a backslash followed by a newline, but this is not required, as make places no limit on the length of a line in a makefile.

A rule tells make two things: when the targets are out of date, and how to update them when necessary.

The criterion for being out of date is specified in terms of the prerequisites, which consist of file names separated by spaces. (Wildcards and archive members (see section Using make to Update Archive Files) are allowed here too.) A target is out of date if it does not exist or if it is older than any of the prerequisites (by comparison of last-modification times). The idea is that the contents of the target file are computed based on information in the prerequisites, so if any of the prerequisites changes, the contents of the existing target file are no longer necessarily valid.

How to update is specified by commands. These are lines to be executed by the shell (normally `sh'), but with some extra features (see section Writing the Commands in Rules).

Using Wildcard Characters in File Names

A single file name can specify many files using wildcard characters. The wildcard characters in make are `*', `?' and `[...]', the same as in the Bourne shell. For example, `*.c' specifies a list of all the files (in the working directory) whose names end in `.c'.

The character `~' at the beginning of a file name also has special significance. If alone, or followed by a slash, it represents your home directory. For example `~/bin' expands to `/home/you/bin'. If the `~' is followed by a word, the string represents the home directory of the user named by that word. For example `~john/bin' expands to `/home/john/bin'. On systems which don't have a home directory for each user (such as MS-DOS or MS-Windows), this functionality can be simulated by setting the environment variable HOME.

Wildcard expansion happens automatically in targets, in prerequisites, and in commands (where the shell does the expansion). In other contexts, wildcard expansion happens only if you request it explicitly with the wildcard function.

The special significance of a wildcard character can be turned off by preceding it with a backslash. Thus, `foo\*bar' would refer to a specific file whose name consists of `foo', an asterisk, and `bar'.

Wildcard Examples

Wildcards can be used in the commands of a rule, where they are expanded by the shell. For example, here is a rule to delete all the object files:

clean:
        rm -f *.o

Wildcards are also useful in the prerequisites of a rule. With the following rule in the makefile, `make print' will print all the `.c' files that have changed since the last time you printed them:

print: *.c
        lpr -p $?
        touch print

This rule uses `print' as an empty target file; see section Empty Target Files to Record Events. (The automatic variable `$?' is used to print only those files that have changed; see section Automatic Variables.)

Wildcard expansion does not happen when you define a variable. Thus, if you write this:

objects = *.o

then the value of the variable objects is the actual string `*.o'. However, if you use the value of objects in a target, prerequisite or command, wildcard expansion will take place at that time. To set objects to the expansion, instead use:

objects := $(wildcard *.o)

See section The Function wildcard.

Pitfalls of Using Wildcards

Now here is an example of a naive way of using wildcard expansion, that does not do what you would intend. Suppose you would like to say that the executable file `foo' is made from all the object files in the directory, and you write this:

objects = *.o

foo : $(objects)
        cc -o foo $(CFLAGS) $(objects)

The value of objects is the actual string `*.o'. Wildcard expansion happens in the rule for `foo', so that each existing `.o' file becomes a prerequisite of `foo' and will be recompiled if necessary.

But what if you delete all the `.o' files? When a wildcard matches no files, it is left as it is, so then `foo' will depend on the oddly-named file `*.o'. Since no such file is likely to exist, make will give you an error saying it cannot figure out how to make `*.o'. This is not what you want!

Actually it is possible to obtain the desired result with wildcard expansion, but you need more sophisticated techniques, including the wildcard function and string substitution. These are described in the following section.

Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to separate directories in pathnames, like so:

  c:\foo\bar\baz.c

This is equivalent to the Unix-style `c:/foo/bar/baz.c' (the `c:' part is the so-called drive letter). When make runs on these systems, it supports backslashes as well as the Unix-style forward slashes in pathnames. However, this support does not include the wildcard expansion, where backslash is a quote character. Therefore, you must use Unix-style slashes in these cases.

The Function wildcard

Wildcard expansion happens automatically in rules. But wildcard expansion does not normally take place when a variable is set, or inside the arguments of a function. If you want to do wildcard expansion in such places, you need to use the wildcard function, like this:

$(wildcard pattern...)

This string, used anywhere in a makefile, is replaced by a space-separated list of names of existing files that match one of the given file name patterns. If no existing file name matches a pattern, then that pattern is omitted from the output of the wildcard function. Note that this is different from how unmatched wildcards behave in rules, where they are used verbatim rather than ignored (see section Pitfalls of Using Wildcards).

One use of the wildcard function is to get a list of all the C source files in a directory, like this:

$(wildcard *.c)

We can change the list of C source files into a list of object files by replacing the `.c' suffix with `.o' in the result, like this:

$(patsubst %.c,%.o,$(wildcard *.c))

(Here we have used another function, patsubst. See section Functions for String Substitution and Analysis.)

Thus, a makefile to compile all C source files in the directory and then link them together could be written as follows:

objects := $(patsubst %.c,%.o,$(wildcard *.c))

foo : $(objects)
        cc -o foo $(objects)

(This takes advantage of the implicit rule for compiling C programs, so there is no need to write explicit rules for compiling the files. See section The Two Flavors of Variables, for an explanation of `:=', which is a variant of `='.)

Searching Directories for Prerequisites

For large systems, it is often desirable to put sources in a separate directory from the binaries. The directory search features of make facilitate this by searching several directories automatically to find a prerequisite. When you redistribute the files among directories, you do not need to change the individual rules, just the search paths.

VPATH: Search Path for All Prerequisites

The value of the make variable VPATH specifies a list of directories that make should search. Most often, the directories are expected to contain prerequisite files that are not in the current directory; however, VPATH specifies a search list that make applies for all files, including files which are targets of rules.

Thus, if a file that is listed as a target or prerequisite does not exist in the current directory, make searches the directories listed in VPATH for a file with that name. If a file is found in one of them, that file may become the prerequisite (see below). Rules may then specify the names of files in the prerequisite list as if they all existed in the current directory. See section Writing Shell Commands with Directory Search.

In the VPATH variable, directory names are separated by colons or blanks. The order in which directories are listed is the order followed by make in its search. (On MS-DOS and MS-Windows, semi-colons are used as separators of directory names in VPATH, since the colon can be used in the pathname itself, after the drive letter.)

For example,

VPATH = src:../headers

specifies a path containing two directories, `src' and `../headers', which make searches in that order.

With this value of VPATH, the following rule,

foo.o : foo.c

is interpreted as if it were written like this:

foo.o : src/foo.c

assuming the file `foo.c' does not exist in the current directory but is found in the directory `src'.

The vpath Directive

Similar to the VPATH variable, but more selective, is the vpath directive (note lower case), which allows you to specify a search path for a particular class of file names: those that match a particular pattern. Thus you can supply certain search directories for one class of file names and other directories (or none) for other file names.

There are three forms of the vpath directive:

vpath pattern directories
Specify the search path directories for file names that match pattern. The search path, directories, is a list of directories to be searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or blanks, just like the search path used in the VPATH variable.
vpath pattern
Clear out the search path associated with pattern.
vpath
Clear all search paths previously specified with vpath directives.

A vpath pattern is a string containing a `%' character. The string must match the file name of a prerequisite that is being searched for, the `%' character matching any sequence of zero or more characters (as in pattern rules; see section Defining and Redefining Pattern Rules). For example, %.h matches files that end in .h. (If there is no `%', the pattern must match the prerequisite exactly, which is not useful very often.)

`%' characters in a vpath directive's pattern can be quoted with preceding backslashes (`\'). Backslashes that would otherwise quote `%' characters can be quoted with more backslashes. Backslashes that quote `%' characters or other backslashes are removed from the pattern before it is compared to file names. Backslashes that are not in danger of quoting `%' characters go unmolested.

When a prerequisite fails to exist in the current directory, if the pattern in a vpath directive matches the name of the prerequisite file, then the directories in that directive are searched just like (and before) the directories in the VPATH variable.

For example,

vpath %.h ../headers

tells make to look for any prerequisite whose name ends in `.h' in the directory `../headers' if the file is not found in the current directory.

If several vpath patterns match the prerequisite file's name, then make processes each matching vpath directive one by one, searching all the directories mentioned in each directive. make handles multiple vpath directives in the order in which they appear in the makefile; multiple directives with the same pattern are independent of each other.

Thus,

vpath %.c foo
vpath %   blish
vpath %.c bar

will look for a file ending in `.c' in `foo', then `blish', then `bar', while

vpath %.c foo:bar
vpath %   blish

will look for a file ending in `.c' in `foo', then `bar', then `blish'.

How Directory Searches are Performed

When a prerequisite is found through directory search, regardless of type (general or selective), the pathname located may not be the one that make actually provides you in the prerequisite list. Sometimes the path discovered through directory search is thrown away.

The algorithm make uses to decide whether to keep or abandon a path found via directory search is as follows:

  1. If a target file does not exist at the path specified in the makefile, directory search is performed.
  2. If the directory search is successful, that path is kept and this file is tentatively stored as the target.
  3. All prerequisites of this target are examined using this same method.
  4. After processing the prerequisites, the target may or may not need to be rebuilt:
    1. If the target does not need to be rebuilt, the path to the file found during directory search is used for any prerequisite lists which contain this target. In short, if make doesn't need to rebuild the target then you use the path found via directory search.
    2. If the target does need to be rebuilt (is out-of-date), the pathname found during directory search is thrown away, and the target is rebuilt using the file name specified in the makefile. In short, if make must rebuild, then the target is rebuilt locally, not in the directory found via directory search.

This algorithm may seem complex, but in practice it is quite often exactly what you want.

Other versions of make use a simpler algorithm: if the file does not exist, and it is found via directory search, then that pathname is always used whether or not the target needs to be built. Thus, if the target is rebuilt it is created at the pathname discovered during directory search.

If, in fact, this is the behavior you want for some or all of your directories, you can use the GPATH variable to indicate this to make.

GPATH has the same syntax and format as VPATH (that is, a space- or colon-delimited list of pathnames). If an out-of-date target is found by directory search in a directory that also appears in GPATH, then that pathname is not thrown away. The target is rebuilt using the expanded path.

Writing Shell Commands with Directory Search

When a prerequisite is found in another directory through directory search, this cannot change the commands of the rule; they will execute as written. Therefore, you must write the commands with care so that they will look for the prerequisite in the directory where make finds it.

This is done with the automatic variables such as `$^' (see section Automatic Variables). For instance, the value of `$^' is a list of all the prerequisites of the rule, including the names of the directories in which they were found, and the value of `$@' is the target. Thus:

foo.o : foo.c
        cc -c $(CFLAGS) $^ -o $@

(The variable CFLAGS exists so you can specify flags for C compilation by implicit rules; we use it here for consistency so it will affect all C compilations uniformly; see section Variables Used by Implicit Rules.)

Often the prerequisites include header files as well, which you do not want to mention in the commands. The automatic variable `$<' is just the first prerequisite:

VPATH = src:../headers
foo.o : foo.c defs.h hack.h
        cc -c $(CFLAGS) $< -o $@

Directory Search and Implicit Rules

The search through the directories specified in VPATH or with vpath also happens during consideration of implicit rules (see section Using Implicit Rules).

For example, when a file `foo.o' has no explicit rule, make considers implicit rules, such as the built-in rule to compile `foo.c' if that file exists. If such a file is lacking in the current directory, the appropriate directories are searched for it. If `foo.c' exists (or is mentioned in the makefile) in any of the directories, the implicit rule for C compilation is applied.

The commands of implicit rules normally use automatic variables as a matter of necessity; consequently they will use the file names found by directory search with no extra effort.

Directory Search for Link Libraries

Directory search applies in a special way to libraries used with the linker. This special feature comes into play when you write a prerequisite whose name is of the form `-lname'. (You can tell something strange is going on here because the prerequisite is normally the name of a file, and the file name of a library generally looks like `libname.a', not like `-lname'.)

When a prerequisite's name has the form `-lname', make handles it specially by searching for the file `libname.so' in the current directory, in directories specified by matching vpath search paths and the VPATH search path, and then in the directories `/lib', `/usr/lib', and `prefix/lib' (normally `/usr/local/lib', but MS-DOS/MS-Windows versions of make behave as if prefix is defined to be the root of the DJGPP installation tree).

If that file is not found, then the file `libname.a' is searched for, in the same directories as above.

For example, if there is a `/usr/lib/libcurses.a' library on your system (and no `/usr/lib/libcurses.so' file), then

foo : foo.c -lcurses
        cc $^ -o $@

would cause the command `cc foo.c /usr/lib/libcurses.a -o foo' to be executed when `foo' is older than `foo.c' or than `/usr/lib/libcurses.a'.

Although the default set of files to be searched for is `libname.so' and `libname.a', this is customizable via the .LIBPATTERNS variable. Each word in the value of this variable is a pattern string. When a prerequisite like `-lname' is seen, make will replace the percent in each pattern in the list with name and perform the above directory searches using that library filename. If no library is found, the next word in the list will be used.

The default value for .LIBPATTERNS is "`lib%.so lib%.a'", which provides the default behavior described above.

You can turn off link library expansion completely by setting this variable to an empty value.

Phony Targets

A phony target is one that is not really the name of a file. It is just a name for some commands to be executed when you make an explicit request. There are two reasons to use a phony target: to avoid a conflict with a file of the same name, and to improve performance.

If you write a rule whose commands will not create the target file, the commands will be executed every time the target comes up for remaking. Here is an example:

clean:
        rm *.o temp

Because the rm command does not create a file named `clean', probably no such file will ever exist. Therefore, the rm command will be executed every time you say `make clean'.

The phony target will cease to work if anything ever does create a file named `clean' in this directory. Since it has no prerequisites, the file `clean' would inevitably be considered up to date, and its commands would not be executed. To avoid this problem, you can explicitly declare the target to be phony, using the special target .PHONY (see section Special Built-in Target Names) as follows:

.PHONY : clean

Once this is done, `make clean' will run the commands regardless of whether there is a file named `clean'.

Since it knows that phony targets do not name actual files that could be remade from other files, make skips the implicit rule search for phony targets (see section Using Implicit Rules). This is why declaring a target phony is good for performance, even if you are not worried about the actual file existing.

Thus, you first write the line that states that clean is a phony target, then you write the rule, like this:

.PHONY: clean
clean:
        rm *.o temp

Another example of the usefulness of phony targets is in conjunction with recursive invocations of make. In this case the makefile will often contain a variable which lists a number of subdirectories to be built. One way to handle this is with one rule whose command is a shell loop over the subdirectories, like this:

SUBDIRS = foo bar baz

subdirs:
        for dir in $(SUBDIRS); do \
          $(MAKE) -C $$dir; \
        done

There are a few of problems with this method, however. First, any error detected in a submake is not noted by this rule, so it will continue to build the rest of the directories even when one fails. This can be overcome by adding shell commands to note the error and exit, but then it will do so even if make is invoked with the -k option, which is unfortunate. Second, and perhaps more importantly, you cannot take advantage of the parallel build capabilities of make using this method, since there is only one rule.

By declaring the subdirectories as phony targets (you must do this as the subdirectory obviously always exists; otherwise it won't be built) you can remove these problems:

SUBDIRS = foo bar baz

.PHONY: subdirs $(SUBDIRS)

subdirs: $(SUBDIRS)

$(SUBDIRS):
        $(MAKE) -C $

foo: baz

Here we've also declared that the `foo' subdirectory cannot be built until after the `baz' subdirectory is complete; this kind of relationship declaration is particularly important when attempting parallel builds.

A phony target should not be a prerequisite of a real target file; if it is, its commands are run every time make goes to update that file. As long as a phony target is never a prerequisite of a real target, the phony target commands will be executed only when the phony target is a specified goal (see section Arguments to Specify the Goals).

Phony targets can have prerequisites. When one directory contains multiple programs, it is most convenient to describe all of the programs in one makefile `./Makefile'. Since the target remade by default will be the first one in the makefile, it is common to make this a phony target named `all' and give it, as prerequisites, all the individual programs. For example:

all : prog1 prog2 prog3
.PHONY : all

prog1 : prog1.o utils.o
        cc -o prog1 prog1.o utils.o

prog2 : prog2.o
        cc -o prog2 prog2.o

prog3 : prog3.o sort.o utils.o
        cc -o prog3 prog3.o sort.o utils.o

Now you can say just `make' to remake all three programs, or specify as arguments the ones to remake (as in `make prog1 prog3').

When one phony target is a prerequisite of another, it serves as a subroutine of the other. For example, here `make cleanall' will delete the object files, the difference files, and the file `program':

.PHONY: cleanall cleanobj cleandiff

cleanall : cleanobj cleandiff
        rm program

cleanobj :
        rm *.o

cleandiff :
        rm *.diff

Rules without Commands or Prerequisites

If a rule has no prerequisites or commands, and the target of the rule is a nonexistent file, then make imagines this target to have been updated whenever its rule is run. This implies that all targets depending on this one will always have their commands run.

An example will illustrate this:

clean: FORCE
        rm $(objects)
FORCE:

Here the target `FORCE' satisfies the special conditions, so the target `clean' that depends on it is forced to run its commands. There is nothing special about the name `FORCE', but that is one name commonly used this way.

As you can see, using `FORCE' this way has the same results as using `.PHONY: clean'.

Using `.PHONY' is more explicit and more efficient. However, other versions of make do not support `.PHONY'; thus `FORCE' appears in many makefiles. See section Phony Targets.

Empty Target Files to Record Events

The empty target is a variant of the phony target; it is used to hold commands for an action that you request explicitly from time to time. Unlike a phony target, this target file can really exist; but the file's contents do not matter, and usually are empty.

The purpose of the empty target file is to record, with its last-modification time, when the rule's commands were last executed. It does so because one of the commands is a touch command to update the target file.

The empty target file should have some prerequisites (otherwise it doesn't make sense). When you ask to remake the empty target, the commands are executed if any prerequisite is more recent than the target; in other words, if a prerequisite has changed since the last time you remade the target. Here is an example:

print: foo.c bar.c
        lpr -p $?
        touch print

With this rule, `make print' will execute the lpr command if either source file has changed since the last `make print'. The automatic variable `$?' is used to print only those files that have changed (see section Automatic Variables).

Special Built-in Target Names

Certain names have special meanings if they appear as targets.

.PHONY
The prerequisites of the special target .PHONY are considered to be phony targets. When it is time to consider such a target, make will run its commands unconditionally, regardless of whether a file with that name exists or what its last-modification time is. See section Phony Targets.
.SUFFIXES
The prerequisites of the special target .SUFFIXES are the list of suffixes to be used in checking for suffix rules. See section Old-Fashioned Suffix Rules.
.DEFAULT
The commands specified for .DEFAULT are used for any target for which no rules are found (either explicit rules or implicit rules). See section Defining Last-Resort Default Rules. If .DEFAULT commands are specified, every file mentioned as a prerequisite, but not as a target in a rule, will have these commands executed on its behalf. See section Implicit Rule Search Algorithm.
.PRECIOUS
The targets which .PRECIOUS depends on are given the following special treatment: if make is killed or interrupted during the execution of their commands, the target is not deleted. See section Interrupting or Killing make. Also, if the target is an intermediate file, it will not be deleted after it is no longer needed, as is normally done. See section Chains of Implicit Rules. In this latter respect it overlaps with the .SECONDARY special target. You can also list the target pattern of an implicit rule (such as `%.o') as a prerequisite file of the special target .PRECIOUS to preserve intermediate files created by rules whose target patterns match that file's name.
.INTERMEDIATE
The targets which .INTERMEDIATE depends on are treated as intermediate files. See section Chains of Implicit Rules. .INTERMEDIATE with no prerequisites has no effect.
.SECONDARY
The targets which .SECONDARY depends on are treated as intermediate files, except that they are never automatically deleted. See section Chains of Implicit Rules. .SECONDARY with no prerequisites causes all targets to be treated as secondary (i.e., no target is removed because it is considered intermediate).
.DELETE_ON_ERROR
If .DELETE_ON_ERROR is mentioned as a target anywhere in the makefile, then make will delete the target of a rule if it has changed and its commands exit with a nonzero exit status, just as it does when it receives a signal. See section Errors in Commands.
.IGNORE
If you specify prerequisites for .IGNORE, then make will ignore errors in execution of the commands run for those particular files. The commands for .IGNORE are not meaningful. If mentioned as a target with no prerequisites, .IGNORE says to ignore errors in execution of commands for all files. This usage of `.IGNORE' is supported only for historical compatibility. Since this affects every command in the makefile, it is not very useful; we recommend you use the more selective ways to ignore errors in specific commands. See section Errors in Commands.
.SILENT
If you specify prerequisites for .SILENT, then make will not print the commands to remake those particular files before executing them. The commands for .SILENT are not meaningful. If mentioned as a target with no prerequisites, .SILENT says not to print any commands before executing them. This usage of `.SILENT' is supported only for historical compatibility. We recommend you use the more selective ways to silence specific commands. See section Command Echoing. If you want to silence all commands for a particular run of make, use the `-s' or `--silent' option (see section Summary of Options).
.EXPORT_ALL_VARIABLES
Simply by being mentioned as a target, this tells make to export all variables to child processes by default. See section Communicating Variables to a Sub-make.
.NOTPARALLEL
If .NOTPARALLEL is mentioned as a target, then this invocation of make will be run serially, even if the `-j' option is given. Any recursively invoked make command will still be run in parallel (unless its makefile contains this target). Any prerequisites on this target are ignored.

Any defined implicit rule suffix also counts as a special target if it appears as a target, and so does the concatenation of two suffixes, such as `.c.o'. These targets are suffix rules, an obsolete way of defining implicit rules (but a way still widely used). In principle, any target name could be special in this way if you break it in two and add both pieces to the suffix list. In practice, suffixes normally begin with `.', so these special target names also begin with `.'. See section Old-Fashioned Suffix Rules.

Multiple Targets in a Rule

A rule with multiple targets is equivalent to writing many rules, each with one target, and all identical aside from that. The same commands apply to all the targets, but their effects may vary because you can substitute the actual target name into the command using `$@'. The rule contributes the same prerequisites to all the targets also.

This is useful in two cases.

  • You want just prerequisites, no commands. For example:
    kbd.o command.o files.o: command.h
    gives an additional prerequisite to each of the three object files mentioned.
  • Similar commands work for all the targets. The commands do not need to be absolutely identical, since the automatic variable `$@' can be used to substitute the particular target to be remade into the commands (see section Automatic Variables). For example:
    bigoutput littleoutput : text.g
        generate text.g -$(subst output,,$@) > $@
    is equivalent to
    bigoutput : text.g
        generate text.g -big > bigoutput
littleoutput : text.g
        generate text.g -little > littleoutput
    Here we assume the hypothetical program generate makes two types of output, one if given `-big' and one if given `-little'. See section Functions for String Substitution and Analysis, for an explanation of the subst function.

Suppose you would like to vary the prerequisites according to the target, much as the variable `$@' allows you to vary the commands. You cannot do this with multiple targets in an ordinary rule, but you can do it with a static pattern rule. See section Static Pattern Rules.

Multiple Rules for One Target

One file can be the target of several rules. All the prerequisites mentioned in all the rules are merged into one list of prerequisites for the target. If the target is older than any prerequisite from any rule, the commands are executed.

There can only be one set of commands to be executed for a file. If more than one rule gives commands for the same file, make uses the last set given and prints an error message. (As a special case, if the file's name begins with a dot, no error message is printed. This odd behavior is only for compatibility with other implementations of make.) There is no reason to write your makefiles this way; that is why make gives you an error message.

An extra rule with just prerequisites can be used to give a few extra prerequisites to many files at once. For example, one usually has a variable named objects containing a list of all the compiler output files in the system being made. An easy way to say that all of them must be recompiled if `config.h' changes is to write the following:

objects = foo.o bar.o
foo.o : defs.h
bar.o : defs.h test.h
$(objects) : config.h

This could be inserted or taken out without changing the rules that really specify how to make the object files, making it a convenient form to use if you wish to add the additional prerequisite intermittently.

Another wrinkle is that the additional prerequisites could be specified with a variable that you set with a command argument to make (see section Overriding Variables). For example,

extradeps=
$(objects) : $(extradeps)

means that the command `make extradeps=foo.h' will consider `foo.h' as a prerequisite of each object file, but plain `make' will not.

If none of the explicit rules for a target has commands, then make searches for an applicable implicit rule to find some commands see section Using Implicit Rules).

Static Pattern Rules

Static pattern rules are rules which specify multiple targets and construct the prerequisite names for each target based on the target name. They are more general than ordinary rules with multiple targets because the targets do not have to have identical prerequisites. Their prerequisites must be analogous, but not necessarily identical.

Syntax of Static Pattern Rules

Here is the syntax of a static pattern rule:

targets ...: target-pattern: dep-patterns ...
        commands
        ...

The targets list specifies the targets that the rule applies to. The targets can contain wildcard characters, just like the targets of ordinary rules (see section Using Wildcard Characters in File Names).

The target-pattern and dep-patterns say how to compute the prerequisites of each target. Each target is matched against the target-pattern to extract a part of the target name, called the stem. This stem is substituted into each of the dep-patterns to make the prerequisite names (one from each dep-pattern).

Each pattern normally contains the character `%' just once. When the target-pattern matches a target, the `%' can match any part of the target name; this part is called the stem. The rest of the pattern must match exactly. For example, the target `foo.o' matches the pattern `%.o', with `foo' as the stem. The targets `foo.c' and `foo.out' do not match that pattern.

The prerequisite names for each target are made by substituting the stem for the `%' in each prerequisite pattern. For example, if one prerequisite pattern is `%.c', then substitution of the stem `foo' gives the prerequisite name `foo.c'. It is legitimate to write a prerequisite pattern that does not contain `%'; then this prerequisite is the same for all targets.

`%' characters in pattern rules can be quoted with preceding backslashes (`\'). Backslashes that would otherwise quote `%' characters can be quoted with more backslashes. Backslashes that quote `%' characters or other backslashes are removed from the pattern before it is compared to file names or has a stem substituted into it. Backslashes that are not in danger of quoting `%' characters go unmolested. For example, the pattern `the\%weird\\%pattern\\' has `the%weird\' preceding the operative `%' character, and `pattern\\' following it. The final two backslashes are left alone because they cannot affect any `%' character.

Here is an example, which compiles each of `foo.o' and `bar.o' from the corresponding `.c' file:

objects = foo.o bar.o

all: $(objects)

$(objects): %.o: %.c
        $(CC) -c $(CFLAGS) $< -o $@

Here `$<' is the automatic variable that holds the name of the prerequisite and `$@' is the automatic variable that holds the name of the target; see section Automatic Variables.

Each target specified must match the target pattern; a warning is issued for each target that does not. If you have a list of files, only some of which will match the pattern, you can use the filter function to remove nonmatching file names (see section Functions for String Substitution and Analysis):

files = foo.elc bar.o lose.o

$(filter %.o,$(files)): %.o: %.c
        $(CC) -c $(CFLAGS) $< -o $@
$(filter %.elc,$(files)): %.elc: %.el
        emacs -f batch-byte-compile $<

In this example the result of `$(filter %.o,$(files))' is `bar.o lose.o', and the first static pattern rule causes each of these object files to be updated by compiling the corresponding C source file. The result of `$(filter %.elc,$(files))' is `foo.elc', so that file is made from `foo.el'.

Another example shows how to use $* in static pattern rules:

bigoutput littleoutput : %output : text.g
        generate text.g -$* > $@

When the generate command is run, $* will expand to the stem, either `big' or `little'.

Static Pattern Rules versus Implicit Rules

A static pattern rule has much in common with an implicit rule defined as a pattern rule (see section Defining and Redefining Pattern Rules). Both have a pattern for the target and patterns for constructing the names of prerequisites. The difference is in how make decides when the rule applies.

An implicit rule can apply to any target that matches its pattern, but it does apply only when the target has no commands otherwise specified, and only when the prerequisites can be found. If more than one implicit rule appears applicable, only one applies; the choice depends on the order of rules.

By contrast, a static pattern rule applies to the precise list of targets that you specify in the rule. It cannot apply to any other target and it invariably does apply to each of the targets specified. If two conflicting rules apply, and both have commands, that's an error.

The static pattern rule can be better than an implicit rule for these reasons:

  • You may wish to override the usual implicit rule for a few files whose names cannot be categorized syntactically but can be given in an explicit list.
  • If you cannot be sure of the precise contents of the directories you are using, you may not be sure which other irrelevant files might lead make to use the wrong implicit rule. The choice might depend on the order in which the implicit rule search is done. With static pattern rules, there is no uncertainty: each rule applies to precisely the targets specified.

Double-Colon Rules

Double-colon rules are rules written with `::' instead of `:' after the target names. They are handled differently from ordinary rules when the same target appears in more than one rule.

When a target appears in multiple rules, all the rules must be the same type: all ordinary, or all double-colon. If they are double-colon, each of them is independent of the others. Each double-colon rule's commands are executed if the target is older than any prerequisites of that rule. This can result in executing none, any, or all of the double-colon rules.

Double-colon rules with the same target are in fact completely separate from one another. Each double-colon rule is processed individually, just as rules with different targets are processed.

The double-colon rules for a target are executed in the order they appear in the makefile. However, the cases where double-colon rules really make sense are those where the order of executing the commands would not matter.

Double-colon rules are somewhat obscure and not often very useful; they provide a mechanism for cases in which the method used to update a target differs depending on which prerequisite files caused the update, and such cases are rare.

Each double-colon rule should specify commands; if it does not, an implicit rule will be used if one applies. See section Using Implicit Rules.

Generating Prerequisites Automatically

In the makefile for a program, many of the rules you need to write often say only that some object file depends on some header file. For example, if `main.c' uses `defs.h' via an #include, you would write:

main.o: defs.h

You need this rule so that make knows that it must remake `main.o' whenever `defs.h' changes. You can see that for a large program you would have to write dozens of such rules in your makefile. And, you must always be very careful to update the makefile every time you add or remove an #include.

To avoid this hassle, most modern C compilers can write these rules for you, by looking at the #include lines in the source files. Usually this is done with the `-M' option to the compiler. For example, the command:

cc -M main.c

generates the output:

main.o : main.c defs.h

Thus you no longer have to write all those rules yourself. The compiler will do it for you.

Note that such a prerequisite constitutes mentioning `main.o' in a makefile, so it can never be considered an intermediate file by implicit rule search. This means that make won't ever remove the file after using it; see section Chains of Implicit Rules.

With old make programs, it was traditional practice to use this compiler feature to generate prerequisites on demand with a command like `make depend'. That command would create a file `depend' containing all the automatically-generated prerequisites; then the makefile could use include to read them in (see section Including Other Makefiles).

In GNU make, the feature of remaking makefiles makes this practice obsolete--you need never tell make explicitly to regenerate the prerequisites, because it always regenerates any makefile that is out of date. See section How Makefiles Are Remade.

The practice we recommend for automatic prerequisite generation is to have one makefile corresponding to each source file. For each source file `name.c' there is a makefile `name.d' which lists what files the object file `name.o' depends on. That way only the source files that have changed need to be rescanned to produce the new prerequisites.

Here is the pattern rule to generate a file of prerequisites (i.e., a makefile) called `name.d' from a C source file called `name.c':

%.d: %.c
        set -e; $(CC) -M $(CPPFLAGS) $< \
                  | sed 's/\($*\)\.o[ :]*/\1.o $@ : /g' > $@; \
                [ -s $@ ] || rm -f $@

See section Defining and Redefining Pattern Rules, for information on defining pattern rules. The `-e' flag to the shell makes it exit immediately if the $(CC) command fails (exits with a nonzero status). Normally the shell exits with the status of the last command in the pipeline (sed in this case), so make would not notice a nonzero status from the compiler.

With the GNU C compiler, you may wish to use the `-MM' flag instead of `-M'. This omits prerequisites on system header files. See section `Options Controlling the Preprocessor' in Using GNU CC, for details.

The purpose of the sed command is to translate (for example):

main.o : main.c defs.h

into:

main.o main.d : main.c defs.h

This makes each `.d' file depend on all the source and header files that the corresponding `.o' file depends on. make then knows it must regenerate the prerequisites whenever any of the source or header files changes.

Once you've defined the rule to remake the `.d' files, you then use the include directive to read them all in. See section Including Other Makefiles. For example:

sources = foo.c bar.c

include $(sources:.c=.d)

(This example uses a substitution variable reference to translate the list of source files `foo.c bar.c' into a list of prerequisite makefiles, `foo.d bar.d'. See section Substitution References, for full information on substitution references.) Since the `.d' files are makefiles like any others, make will remake them as necessary with no further work from you. See section How Makefiles Are Remade.

Writing the Commands in Rules

The commands of a rule consist of shell command lines to be executed one by one. Each command line must start with a tab, except that the first command line may be attached to the target-and-prerequisites line with a semicolon in between. Blank lines and lines of just comments may appear among the command lines; they are ignored. (But beware, an apparently "blank" line that begins with a tab is not blank! It is an empty command; see section Using Empty Commands.)

Users use many different shell programs, but commands in makefiles are always interpreted by `/bin/sh' unless the makefile specifies otherwise. See section Command Execution.

The shell that is in use determines whether comments can be written on command lines, and what syntax they use. When the shell is `/bin/sh', a `#' starts a comment that extends to the end of the line. The `#' does not have to be at the beginning of a line. Text on a line before a `#' is not part of the comment.

Command Echoing

Normally make prints each command line before it is executed. We call this echoing because it gives the appearance that you are typing the commands yourself.

When a line starts with `@', the echoing of that line is suppressed. The `@' is discarded before the command is passed to the shell. Typically you would use this for a command whose only effect is to print something, such as an echo command to indicate progress through the makefile:

@echo About to make distribution files

When make is given the flag `-n' or `--just-print' it only echoes commands, it won't execute them. See section Summary of Options. In this case and only this case, even the commands starting with `@' are printed. This flag is useful for finding out which commands make thinks are necessary without actually doing them.

The `-s' or `--silent' flag to make prevents all echoing, as if all commands started with `@'. A rule in the makefile for the special target .SILENT without prerequisites has the same effect (see section Special Built-in Target Names). .SILENT is essentially obsolete since `@' is more flexible.

Command Execution

When it is time to execute commands to update a target, they are executed by making a new subshell for each line. (In practice, make may take shortcuts that do not affect the results.)

Please note: this implies that shell commands such as cd that set variables local to each process will not affect the following command lines. (2) If you want to use cd to affect the next command, put the two on a single line with a semicolon between them. Then make will consider them a single command and pass them, together, to a shell which will execute them in sequence. For example:

foo : bar/lose
        cd bar; gobble lose > ../foo

If you would like to split a single shell command into multiple lines of text, you must use a backslash at the end of all but the last subline. Such a sequence of lines is combined into a single line, by deleting the backslash-newline sequences, before passing it to the shell. Thus, the following is equivalent to the preceding example:

foo : bar/lose
        cd bar;  \
        gobble lose > ../foo

The program used as the shell is taken from the variable SHELL. By default, the program `/bin/sh' is used.

On MS-DOS, if SHELL is not set, the value of the variable COMSPEC (which is always set) is used instead.

The processing of lines that set the variable SHELL in Makefiles is different on MS-DOS. The stock shell, `command.com', is ridiculously limited in its functionality and many users of make tend to install a replacement shell. Therefore, on MS-DOS, make examines the value of SHELL, and changes its behavior based on whether it points to a Unix-style or DOS-style shell. This allows reasonable functionality even if SHELL points to `command.com'.

If SHELL points to a Unix-style shell, make on MS-DOS additionally checks whether that shell can indeed be found; if not, it ignores the line that sets SHELL. In MS-DOS, GNU make searches for the shell in the following places:

  1. In the precise place pointed to by the value of SHELL. For example, if the makefile specifies `SHELL = /bin/sh', make will look in the directory `/bin' on the current drive.
  2. In the current directory.
  3. In each of the directories in the PATH variable, in order.

In every directory it examines, make will first look for the specific file (`sh' in the example above). If this is not found, it will also look in that directory for that file with one of the known extensions which identify executable files. For example `.exe', `.com', `.bat', `.btm', `.sh', and some others.

If any of these attempts is successful, the value of SHELL will be set to the full pathname of the shell as found. However, if none of these is found, the value of SHELL will not be changed, and thus the line that sets it will be effectively ignored. This is so make will only support features specific to a Unix-style shell if such a shell is actually installed on the system where make runs.

Note that this extended search for the shell is limited to the cases where SHELL is set from the Makefile; if it is set in the environment or command line, you are expected to set it to the full pathname of the shell, exactly as things are on Unix.

The effect of the above DOS-specific processing is that a Makefile that says `SHELL = /bin/sh' (as many Unix makefiles do), will work on MS-DOS unaltered if you have e.g. `sh.exe' installed in some directory along your PATH.

Unlike most variables, the variable SHELL is never set from the environment. This is because the SHELL environment variable is used to specify your personal choice of shell program for interactive use. It would be very bad for personal choices like this to affect the functioning of makefiles. See section Variables from the Environment. However, on MS-DOS and MS-Windows the value of SHELL in the environment is used, since on those systems most users do not set this variable, and therefore it is most likely set specifically to be used by make. On MS-DOS, if the setting of SHELL is not suitable for make, you can set the variable MAKESHELL to the shell that make should use; this will override the value of SHELL.

Parallel Execution

GNU make knows how to execute several commands at once. Normally, make will execute only one command at a time, waiting for it to finish before executing the next. However, the `-j' or `--jobs' option tells make to execute many commands simultaneously.

On MS-DOS, the `-j' option has no effect, since that system doesn't support multi-processing.

If the `-j' option is followed by an integer, this is the number of commands to execute at once; this is called the number of job slots. If there is nothing looking like an integer after the `-j' option, there is no limit on the number of job slots. The default number of job slots is one, which means serial execution (one thing at a time).

One unpleasant consequence of running several commands simultaneously is that output generated by the commands appears whenever each command sends it, so messages from different commands may be interspersed.

Another problem is that two processes cannot both take input from the same device; so to make sure that only one command tries to take input from the terminal at once, make will invalidate the standard input streams of all but one running command. This means that attempting to read from standard input will usually be a fatal error (a `Broken pipe' signal) for most child processes if there are several.

It is unpredictable which command will have a valid standard input stream (which will come from the terminal, or wherever you redirect the standard input of make). The first command run will always get it first, and the first command started after that one finishes will get it next, and so on.

We will change how this aspect of make works if we find a better alternative. In the mean time, you should not rely on any command using standard input at all if you are using the parallel execution feature; but if you are not using this feature, then standard input works normally in all commands.

Finally, handling recursive make invocations raises issues. For more information on this, see section Communicating Options to a Sub-make.

If a command fails (is killed by a signal or exits with a nonzero status), and errors are not ignored for that command (see section Errors in Commands), the remaining command lines to remake the same target will not be run. If a command fails and the `-k' or `--keep-going' option was not given (see section Summary of Options), make aborts execution. If make terminates for any reason (including a signal) with child processes running, it waits for them to finish before actually exiting.

When the system is heavily loaded, you will probably want to run fewer jobs than when it is lightly loaded. You can use the `-l' option to tell make to limit the number of jobs to run at once, based on the load average. The `-l' or `--max-load' option is followed by a floating-point number. For example,

-l 2.5

will not let make start more than one job if the load average is above 2.5. The `-l' option with no following number removes the load limit, if one was given with a previous `-l' option.

More precisely, when make goes to start up a job, and it already has at least one job running, it checks the current load average; if it is not lower than the limit given with `-l', make waits until the load average goes below that limit, or until all the other jobs finish.

By default, there is no load limit.

Errors in Commands

After each shell command returns, make looks at its exit status. If the command completed successfully, the next command line is executed in a new shell; after the last command line is finished, the rule is finished.

If there is an error (the exit status is nonzero), make gives up on the current rule, and perhaps on all rules.

Sometimes the failure of a certain command does not indicate a problem. For example, you may use the mkdir command to ensure that a directory exists. If the directory already exists, mkdir will report an error, but you probably want make to continue regardless.

To ignore errors in a command line, write a `-' at the beginning of the line's text (after the initial tab). The `-' is discarded before the command is passed to the shell for execution.

For example,

clean:
        -rm -f *.o

This causes rm to continue even if it is unable to remove a file.

When you run make with the `-i' or `--ignore-errors' flag, errors are ignored in all commands of all rules. A rule in the makefile for the special target .IGNORE has the same effect, if there are no prerequisites. These ways of ignoring errors are obsolete because `-' is more flexible.

When errors are to be ignored, because of either a `-' or the `-i' flag, make treats an error return just like success, except that it prints out a message that tells you the status code the command exited with, and says that the error has been ignored.

When an error happens that make has not been told to ignore, it implies that the current target cannot be correctly remade, and neither can any other that depends on it either directly or indirectly. No further commands will be executed for these targets, since their preconditions have not been achieved.

Normally make gives up immediately in this circumstance, returning a nonzero status. However, if the `-k' or `--keep-going' flag is specified, make continues to consider the other prerequisites of the pending targets, remaking them if necessary, before it gives up and returns nonzero status. For example, after an error in compiling one object file, `make -k' will continue compiling other object files even though it already knows that linking them will be impossible. See section Summary of Options.

The usual behavior assumes that your purpose is to get the specified targets up to date; once make learns that this is impossible, it might as well report the failure immediately. The `-k' option says that the real purpose is to test as many of the changes made in the program as possible, perhaps to find several independent problems so that you can correct them all before the next attempt to compile. This is why Emacs' compile command passes the `-k' flag by default.

Usually when a command fails, if it has changed the target file at all, the file is corrupted and cannot be used--or at least it is not completely updated. Yet the file's timestamp says that it is now up to date, so the next time make runs, it will not try to update that file. The situation is just the same as when the command is killed by a signal; see section Interrupting or Killing make. So generally the right thing to do is to delete the target file if the command fails after beginning to change the file. make will do this if .DELETE_ON_ERROR appears as a target. This is almost always what you want make to do, but it is not historical practice; so for compatibility, you must explicitly request it.

Interrupting or Killing make

If make gets a fatal signal while a command is executing, it may delete the target file that the command was supposed to update. This is done if the target file's last-modification time has changed since make first checked it.

The purpose of deleting the target is to make sure that it is remade from scratch when make is next run. Why is this? Suppose you type Ctrl-c while a compiler is running, and it has begun to write an object file `foo.o'. The Ctrl-c kills the compiler, resulting in an incomplete file whose last-modification time is newer than the source file `foo.c'. But make also receives the Ctrl-c signal and deletes this incomplete file. If make did not do this, the next invocation of make would think that `foo.o' did not require updating--resulting in a strange error message from the linker when it tries to link an object file half of which is missing.

You can prevent the deletion of a target file in this way by making the special target .PRECIOUS depend on it. Before remaking a target, make checks to see whether it appears on the prerequisites of .PRECIOUS, and thereby decides whether the target should be deleted if a signal happens. Some reasons why you might do this are that the target is updated in some atomic fashion, or exists only to record a modification-time (its contents do not matter), or must exist at all times to prevent other sorts of trouble.

Recursive Use of make

Recursive use of make means using make as a command in a makefile. This technique is useful when you want separate makefiles for various subsystems that compose a larger system. For example, suppose you have a subdirectory `subdir' which has its own makefile, and you would like the containing directory's makefile to run make on the subdirectory. You can do it by writing this:

subsystem:
        cd subdir && $(MAKE)

or, equivalently, this (see section Summary of Options):

subsystem:
        $(MAKE) -C subdir

You can write recursive make commands just by copying this example, but there are many things to know about how they work and why, and about how the sub-make relates to the top-level make.

For your convenience, GNU make sets the variable CURDIR to the pathname of the current working directory for you. If -C is in effect, it will contain the path of the new directory, not the original. The value has the same precedence it would have if it were set in the makefile (by default, an environment variable CURDIR will not override this value). Note that setting this variable has no effect on the operation of make

How the MAKE Variable Works

Recursive make commands should always use the variable MAKE, not the explicit command name `make', as shown here:

subsystem:
        cd subdir && $(MAKE)

The value of this variable is the file name with which make was invoked. If this file name was `/bin/make', then the command executed is `cd subdir && /bin/make'. If you use a special version of make to run the top-level makefile, the same special version will be executed for recursive invocations.

As a special feature, using the variable MAKE in the commands of a rule alters the effects of the `-t' (`--touch'), `-n' (`--just-print'), or `-q' (`--question') option. Using the MAKE variable has the same effect as using a `+' character at the beginning of the command line. See section Instead of Executing the Commands.

Consider the command `make -t' in the above example. (The `-t' option marks targets as up to date without actually running any commands; see section Instead of Executing the Commands.) Following the usual definition of `-t', a `make -t' command in the example would create a file named `subsystem' and do nothing else. What you really want it to do is run `cd subdir && make -t'; but that would require executing the command, and `-t' says not to execute commands.

The special feature makes this do what you want: whenever a command line of a rule contains the variable MAKE, the flags `-t', `-n' and `-q' do not apply to that line. Command lines containing MAKE are executed normally despite the presence of a flag that causes most commands not to be run. The usual MAKEFLAGS mechanism passes the flags to the sub-make (see section Communicating Options to a Sub-make), so your request to touch the files, or print the commands, is propagated to the subsystem.

Communicating Variables to a Sub-make

Variable values of the top-level make can be passed to the sub-make through the environment by explicit request. These variables are defined in the sub-make as defaults, but do not override what is specified in the makefile used by the sub-make makefile unless you use the `-e' switch (see section Summary of Options).

To pass down, or export, a variable, make adds the variable and its value to the environment for running each command. The sub-make, in turn, uses the environment to initialize its table of variable values. See section Variables from the Environment.

Except by explicit request, make exports a variable only if it is either defined in the environment initially or set on the command line, and if its name consists only of letters, numbers, and underscores. Some shells cannot cope with environment variable names consisting of characters other than letters, numbers, and underscores.

The special variables SHELL and MAKEFLAGS are always exported (unless you unexport them). MAKEFILES is exported if you set it to anything.

make automatically passes down variable values that were defined on the command line, by putting them in the MAKEFLAGS variable. See the next section.

Variables are not normally passed down if they were created by default by make (see section Variables Used by Implicit Rules). The sub-make will define these for itself.

If you want to export specific variables to a sub-make, use the export directive, like this:

export variable ...

If you want to prevent a variable from being exported, use the unexport directive, like this:

unexport variable ...

As a convenience, you can define a variable and export it at the same time by doing:

export variable = value

has the same result as:

variable = value
export variable

and

export variable := value

has the same result as:

variable := value
export variable

Likewise,

export variable += value

is just like:

variable += value
export variable

See section Appending More Text to Variables.

You may notice that the export and unexport directives work in make in the same way they work in the shell, sh.

If you want all variables to be exported by default, you can use export by itself:

export

This tells make that variables which are not explicitly mentioned in an export or unexport directive should be exported. Any variable given in an unexport directive will still not be exported. If you use export by itself to export variables by default, variables whose names contain characters other than alphanumerics and underscores will not be exported unless specifically mentioned in an export directive.

The behavior elicited by an export directive by itself was the default in older versions of GNU make. If your makefiles depend on this behavior and you want to be compatible with old versions of make, you can write a rule for the special target .EXPORT_ALL_VARIABLES instead of using the export directive. This will be ignored by old makes, while the export directive will cause a syntax error.

Likewise, you can use unexport by itself to tell make not to export variables by default. Since this is the default behavior, you would only need to do this if export had been used by itself earlier (in an included makefile, perhaps). You cannot use export and unexport by themselves to have variables exported for some commands and not for others. The last export or unexport directive that appears by itself determines the behavior for the entire run of make.

As a special feature, the variable MAKELEVEL is changed when it is passed down from level to level. This variable's value is a string which is the depth of the level as a decimal number. The value is `0' for the top-level make; `1' for a sub-make, `2' for a sub-sub-make, and so on. The incrementation happens when make sets up the environment for a command.

The main use of MAKELEVEL is to test it in a conditional directive (see section Conditional Parts of Makefiles); this way you can write a makefile that behaves one way if run recursively and another way if run directly by you.

You can use the variable MAKEFILES to cause all sub-make commands to use additional makefiles. The value of MAKEFILES is a whitespace-separated list of file names. This variable, if defined in the outer-level makefile, is passed down through the environment; then it serves as a list of extra makefiles for the sub-make to read before the usual or specified ones. See section The Variable MAKEFILES.

Communicating Options to a Sub-make

Flags such as `-s' and `-k' are passed automatically to the sub-make through the variable MAKEFLAGS. This variable is set up automatically by make to contain the flag letters that make received. Thus, if you do `make -ks' then MAKEFLAGS gets the value `ks'.

As a consequence, every sub-make gets a value for MAKEFLAGS in its environment. In response, it takes the flags from that value and processes them as if they had been given as arguments. See section Summary of Options.

Likewise variables defined on the command line are passed to the sub-make through MAKEFLAGS. Words in the value of MAKEFLAGS that contain `=', make treats as variable definitions just as if they appeared on the command line. See section Overriding Variables.

The options `-C', `-f', `-o', and `-W' are not put into MAKEFLAGS; these options are not passed down.

The `-j' option is a special case (see section Parallel Execution). If you set it to some numeric value `N' and your operating system supports it (most any UNIX system will; others typically won't), the parent make and all the sub-makes will communicate to ensure that there are only `N' jobs running at the same time between them all. Note that any job that is marked recursive (see section Instead of Executing the Commands) doesn't count against the total jobs (otherwise we could get `N' sub-makes running and have no slots left over for any real work!)

If your operating system doesn't support the above communication, then `-j 1' is always put into MAKEFLAGS instead of the value you specified. This is because if the `-j' option were passed down to sub-makes, you would get many more jobs running in parallel than you asked for. If you give `-j' with no numeric argument, meaning to run as many jobs as possible in parallel, this is passed down, since multiple infinities are no more than one.

If you do not want to pass the other flags down, you must change the value of MAKEFLAGS, like this:

subsystem:
        cd subdir && $(MAKE) MAKEFLAGS=

The command line variable definitions really appear in the variable MAKEOVERRIDES, and MAKEFLAGS contains a reference to this variable. If you do want to pass flags down normally, but don't want to pass down the command line variable definitions, you can reset MAKEOVERRIDES to empty, like this:

MAKEOVERRIDES =

This is not usually useful to do. However, some systems have a small fixed limit on the size of the environment, and putting so much information into the value of MAKEFLAGS can exceed it. If you see the error message `Arg list too long', this may be the problem. (For strict compliance with POSIX.2, changing MAKEOVERRIDES does not affect MAKEFLAGS if the special target `.POSIX' appears in the makefile. You probably do not care about this.)

A similar variable MFLAGS exists also, for historical compatibility. It has the same value as MAKEFLAGS except that it does not contain the command line variable definitions, and it always begins with a hyphen unless it is empty (MAKEFLAGS begins with a hyphen only when it begins with an option that has no single-letter version, such as `--warn-undefined-variables'). MFLAGS was traditionally used explicitly in the recursive make command, like this:

subsystem:
        cd subdir && $(MAKE) $(MFLAGS)

but now MAKEFLAGS makes this usage redundant. If you want your makefiles to be compatible with old make programs, use this technique; it will work fine with more modern make versions too.

The MAKEFLAGS variable can also be useful if you want to have certain options, such as `-k' (see section Summary of Options), set each time you run make. You simply put a value for MAKEFLAGS in your environment. You can also set MAKEFLAGS in a makefile, to specify additional flags that should also be in effect for that makefile. (Note that you cannot use MFLAGS this way. That variable is set only for compatibility; make does not interpret a value you set for it in any way.)

When make interprets the value of MAKEFLAGS (either from the environment or from a makefile), it first prepends a hyphen if the value does not already begin with one. Then it chops the value into words separated by blanks, and parses these words as if they were options given on the command line (except that `-C', `-f', `-h', `-o', `-W', and their long-named versions are ignored; and there is no error for an invalid option).

If you do put MAKEFLAGS in your environment, you should be sure not to include any options that will drastically affect the actions of make and undermine the purpose of makefiles and of make itself. For instance, the `-t', `-n', and `-q' options, if put in one of these variables, could have disastrous consequences and would certainly have at least surprising and probably annoying effects.

The `--print-directory' Option

If you use several levels of recursive make invocations, the `-w' or `--print-directory' option can make the output a lot easier to understand by showing each directory as make starts processing it and as make finishes processing it. For example, if `make -w' is run in the directory `/u/gnu/make', make will print a line of the form:

make: Entering directory `/u/gnu/make'.

before doing anything else, and a line of the form:

make: Leaving directory `/u/gnu/make'.

when processing is completed.

Normally, you do not need to specify this option because `make' does it for you: `-w' is turned on automatically when you use the `-C' option, and in sub-makes. make will not automatically turn on `-w' if you also use `-s', which says to be silent, or if you use `--no-print-directory' to explicitly disable it.

Defining Canned Command Sequences

When the same sequence of commands is useful in making various targets, you can define it as a canned sequence with the define directive, and refer to the canned sequence from the rules for those targets. The canned sequence is actually a variable, so the name must not conflict with other variable names.

Here is an example of defining a canned sequence of commands:

define run-yacc
yacc $(firstword $^)
mv y.tab.c $@
endef

Here run-yacc is the name of the variable being defined; endef marks the end of the definition; the lines in between are the commands. The define directive does not expand variable references and function calls in the canned sequence; the `$' characters, parentheses, variable names, and so on, all become part of the value of the variable you are defining. See section Defining Variables Verbatim, for a complete explanation of define.

The first command in this example runs Yacc on the first prerequisite of whichever rule uses the canned sequence. The output file from Yacc is always named `y.tab.c'. The second command moves the output to the rule's target file name.

To use the canned sequence, substitute the variable into the commands of a rule. You can substitute it like any other variable (see section Basics of Variable References). Because variables defined by define are recursively expanded variables, all the variable references you wrote inside the define are expanded now. For example:

foo.c : foo.y
        $(run-yacc)

`foo.y' will be substituted for the variable `$^' when it occurs in run-yacc's value, and `foo.c' for `$@'.

This is a realistic example, but this particular one is not needed in practice because make has an implicit rule to figure out these commands based on the file names involved (see section Using Implicit Rules).

In command execution, each line of a canned sequence is treated just as if the line appeared on its own in the rule, preceded by a tab. In particular, make invokes a separate subshell for each line. You can use the special prefix characters that affect command lines (`@', `-', and `+') on each line of a canned sequence. See section Writing the Commands in Rules. For example, using this canned sequence:

define frobnicate
@echo "frobnicating target $@"
frob-step-1 $< -o $@-step-1
frob-step-2 $@-step-1 -o $@
endef

make will not echo the first line, the echo command. But it will echo the following two command lines.

On the other hand, prefix characters on the command line that refers to a canned sequence apply to every line in the sequence. So the rule:

frob.out: frob.in
        @$(frobnicate)

does not echo any commands. (See section Command Echoing, for a full explanation of `@'.)

Using Empty Commands

It is sometimes useful to define commands which do nothing. This is done simply by giving a command that consists of nothing but whitespace. For example:

target: ;

defines an empty command string for `target'. You could also use a line beginning with a tab character to define an empty command string, but this would be confusing because such a line looks empty.

You may be wondering why you would want to define a command string that does nothing. The only reason this is useful is to prevent a target from getting implicit commands (from implicit rules or the .DEFAULT special target; see section Using Implicit Rules and see section Defining Last-Resort Default Rules).

You may be inclined to define empty command strings for targets that are not actual files, but only exist so that their prerequisites can be remade. However, this is not the best way to do that, because the prerequisites may not be remade properly if the target file actually does exist. See section Phony Targets, for a better way to do this.

How to Use Variables

A variable is a name defined in a makefile to represent a string of text, called the variable's value. These values are substituted by explicit request into targets, prerequisites, commands, and other parts of the makefile. (In some other versions of make, variables are called macros.)

Variables and functions in all parts of a makefile are expanded when read, except for the shell commands in rules, the right-hand sides of variable definitions using `=', and the bodies of variable definitions using the define directive.

Variables can represent lists of file names, options to pass to compilers, programs to run, directories to look in for source files, directories to write output in, or anything else you can imagine.

A variable name may be any sequence of characters not containing `:', `#', `=', or leading or trailing whitespace. However, variable names containing characters other than letters, numbers, and underscores should be avoided, as they may be given special meanings in the future, and with some shells they cannot be passed through the environment to a sub-make (see section Communicating Variables to a Sub-make).

Variable names are case-sensitive. The names `foo', `FOO', and `Foo' all refer to different variables.

It is traditional to use upper case letters in variable names, but we recommend using lower case letters for variable names that serve internal purposes in the makefile, and reserving upper case for parameters that control implicit rules or for parameters that the user should override with command options (see section Overriding Variables).

A few variables have names that are a single punctuation character or just a few characters. These are the automatic variables, and they have particular specialized uses. See section Automatic Variables.

Basics of Variable References

To substitute a variable's value, write a dollar sign followed by the name of the variable in parentheses or braces: either `$(foo)' or `${foo}' is a valid reference to the variable foo. This special significance of `$' is why you must write `$$' to have the effect of a single dollar sign in a file name or command.

Variable references can be used in any context: targets, prerequisites, commands, most directives, and new variable values. Here is an example of a common case, where a variable holds the names of all the object files in a program:

objects = program.o foo.o utils.o
program : $(objects)
        cc -o program $(objects)

$(objects) : defs.h

Variable references work by strict textual substitution. Thus, the rule

foo = c
prog.o : prog.$(foo)
        $(foo)$(foo) -$(foo) prog.$(foo)

could be used to compile a C program `prog.c'. Since spaces before the variable value are ignored in variable assignments, the value of foo is precisely `c'. (Don't actually write your makefiles this way!)

A dollar sign followed by a character other than a dollar sign, open-parenthesis or open-brace treats that single character as the variable name. Thus, you could reference the variable x with `$x'. However, this practice is strongly discouraged, except in the case of the automatic variables (see section Automatic Variables).

The Two Flavors of Variables

There are two ways that a variable in GNU make can have a value; we call them the two flavors of variables. The two flavors are distinguished in how they are defined and in what they do when expanded.

The first flavor of variable is a recursively expanded variable. Variables of this sort are defined by lines using `=' (see section Setting Variables) or by the define directive (see section Defining Variables Verbatim). The value you specify is installed verbatim; if it contains references to other variables, these references are expanded whenever this variable is substituted (in the course of expanding some other string). When this happens, it is called recursive expansion.

For example,

foo = $(bar)
bar = $(ugh)
ugh = Huh?

all:;echo $(foo)

will echo `Huh?': `$(foo)' expands to `$(bar)' which expands to `$(ugh)' which finally expands to `Huh?'.

This flavor of variable is the only sort supported by other versions of make. It has its advantages and its disadvantages. An advantage (most would say) is that:

CFLAGS = $(include_dirs) -O
include_dirs = -Ifoo -Ibar

will do what was intended: when `CFLAGS' is expanded in a command, it will expand to `-Ifoo -Ibar -O'. A major disadvantage is that you cannot append something on the end of a variable, as in

CFLAGS = $(CFLAGS) -O

because it will cause an infinite loop in the variable expansion. (Actually make detects the infinite loop and reports an error.)

Another disadvantage is that any functions (see section Functions for Transforming Text) referenced in the definition will be executed every time the variable is expanded. This makes make run slower; worse, it causes the wildcard and shell functions to give unpredictable results because you cannot easily control when they are called, or even how many times.

To avoid all the problems and inconveniences of recursively expanded variables, there is another flavor: simply expanded variables.

Simply expanded variables are defined by lines using `:=' (see section Setting Variables). The value of a simply expanded variable is scanned once and for all, expanding any references to other variables and functions, when the variable is defined. The actual value of the simply expanded variable is the result of expanding the text that you write. It does not contain any references to other variables; it contains their values as of the time this variable was defined. Therefore,

x := foo
y := $(x) bar
x := later

is equivalent to

y := foo bar
x := later

When a simply expanded variable is referenced, its value is substituted verbatim.

Here is a somewhat more complicated example, illustrating the use of `:=' in conjunction with the shell function. (See section The shell Function.) This example also shows use of the variable MAKELEVEL, which is changed when it is passed down from level to level. (See section Communicating Variables to a Sub-make, for information about MAKELEVEL.)

ifeq (0,${MAKELEVEL})
cur-dir   := $(shell pwd)
whoami    := $(shell whoami)
host-type := $(shell arch)
MAKE := ${MAKE} host-type=${host-type} whoami=${whoami}
endif

An advantage of this use of `:=' is that a typical `descend into a directory' command then looks like this:

${subdirs}:
      ${MAKE} cur-dir=${cur-dir}/$@ -C $@ all

Simply expanded variables generally make complicated makefile programming more predictable because they work like variables in most programming languages. They allow you to redefine a variable using its own value (or its value processed in some way by one of the expansion functions) and to use the expansion functions much more efficiently (see section Functions for Transforming Text).

You can also use them to introduce controlled leading whitespace into variable values. Leading whitespace characters are discarded from your input before substitution of variable references and function calls; this means you can include leading spaces in a variable value by protecting them with variable references, like this:

nullstring :=
space := $(nullstring) # end of the line

Here the value of the variable space is precisely one space. The comment `# end of the line' is included here just for clarity. Since trailing space characters are not stripped from variable values, just a space at the end of the line would have the same effect (but be rather hard to read). If you put whitespace at the end of a variable value, it is a good idea to put a comment like that at the end of the line to make your intent clear. Conversely, if you do not want any whitespace characters at the end of your variable value, you must remember not to put a random comment on the end of the line after some whitespace, such as this:

dir := /foo/bar    # directory to put the frobs in

Here the value of the variable dir is `/foo/bar ' (with four trailing spaces), which was probably not the intention. (Imagine something like `$(dir)/file' with this definition!)

There is another assignment operator for variables, `?='. This is called a conditional variable assignment operator, because it only has an effect if the variable is not yet defined. This statement:

FOO ?= bar

is exactly equivalent to this (see section The origin Function):

ifeq ($(origin FOO), undefined)
  FOO = bar
endif

Note that a variable set to an empty value is still defined, so `?=' will not set that variable.

Advanced Features for Reference to Variables

This section describes some advanced features you can use to reference variables in more flexible ways.

Substitution References

A substitution reference substitutes the value of a variable with alterations that you specify. It has the form `$(var:a=b)' (or `${var:a=b}') and its meaning is to take the value of the variable var, replace every a at the end of a word with b in that value, and substitute the resulting string.

When we say "at the end of a word", we mean that a must appear either followed by whitespace or at the end of the value in order to be replaced; other occurrences of a in the value are unaltered. For example:

foo := a.o b.o c.o
bar := $(foo:.o=.c)

sets `bar' to `a.c b.c c.c'. See section Setting Variables.

A substitution reference is actually an abbreviation for use of the patsubst expansion function (see section Functions for String Substitution and Analysis). We provide substitution references as well as patsubst for compatibility with other implementations of make.

Another type of substitution reference lets you use the full power of the patsubst function. It has the same form `$(var:a=b)' described above, except that now a must contain a single `%' character. This case is equivalent to `$(patsubst a,b,$(var))'. See section Functions for String Substitution and Analysis, for a description of the patsubst function.

For example:

foo := a.o b.o c.o
bar := $(foo:%.o=%.c)

sets `bar' to `a.c b.c c.c'.

Computed Variable Names

Computed variable names are a complicated concept needed only for sophisticated makefile programming. For most purposes you need not consider them, except to know that making a variable with a dollar sign in its name might have strange results. However, if you are the type that wants to understand everything, or you are actually interested in what they do, read on.

Variables may be referenced inside the name of a variable. This is called a computed variable name or a nested variable reference. For example,

x = y
y = z
a := $($(x))

defines a as `z': the `$(x)' inside `$($(x))' expands to `y', so `$($(x))' expands to `$(y)' which in turn expands to `z'. Here the name of the variable to reference is not stated explicitly; it is computed by expansion of `$(x)'. The reference `$(x)' here is nested within the outer variable reference.

The previous example shows two levels of nesting, but any number of levels is possible. For example, here are three levels:

x = y
y = z
z = u
a := $($($(x)))

Here the innermost `$(x)' expands to `y', so `$($(x))' expands to `$(y)' which in turn expands to `z'; now we have `$(z)', which becomes `u'.

References to recursively-expanded variables within a variable name are reexpanded in the usual fashion. For example:

x = $(y)
y = z
z = Hello
a := $($(x))

defines a as `Hello': `$($(x))' becomes `$($(y))' which becomes `$(z)' which becomes `Hello'.

Nested variable references can also contain modified references and function invocations (see section Functions for Transforming Text), just like any other reference. For example, using the subst function (see section Functions for String Substitution and Analysis):

x = variable1
variable2 := Hello
y = $(subst 1,2,$(x))
z = y
a := $($($(z)))

eventually defines a as `Hello'. It is doubtful that anyone would ever want to write a nested reference as convoluted as this one, but it works: `$($($(z)))' expands to `$($(y))' which becomes `$($(subst 1,2,$(x)))'. This gets the value `variable1' from x and changes it by substitution to `variable2', so that the entire string becomes `$(variable2)', a simple variable reference whose value is `Hello'.

A computed variable name need not consist entirely of a single variable reference. It can contain several variable references, as well as some invariant text. For example,

a_dirs := dira dirb
1_dirs := dir1 dir2

a_files := filea fileb
1_files := file1 file2

ifeq "$(use_a)" "yes"
a1 := a
else
a1 := 1
endif

ifeq "$(use_dirs)" "yes"
df := dirs
else
df := files
endif

dirs := $($(a1)_$(df))

will give dirs the same value as a_dirs, 1_dirs, a_files or 1_files depending on the settings of use_a and use_dirs.

Computed variable names can also be used in substitution references:

a_objects := a.o b.o c.o
1_objects := 1.o 2.o 3.o

sources := $($(a1)_objects:.o=.c)

defines sources as either `a.c b.c c.c' or `1.c 2.c 3.c', depending on the value of a1.

The only restriction on this sort of use of nested variable references is that they cannot specify part of the name of a function to be called. This is because the test for a recognized function name is done before the expansion of nested references. For example,

ifdef do_sort
func := sort
else
func := strip
endif

bar := a d b g q c

foo := $($(func) $(bar))

attempts to give `foo' the value of the variable `sort a d b g q c' or `strip a d b g q c', rather than giving `a d b g q c' as the argument to either the sort or the strip function. This restriction could be removed in the future if that change is shown to be a good idea.

You can also use computed variable names in the left-hand side of a variable assignment, or in a define directive, as in:

dir = foo
$(dir)_sources := $(wildcard $(dir)/*.c)
define $(dir)_print
lpr $($(dir)_sources)
endef

This example defines the variables `dir', `foo_sources', and `foo_print'.

Note that nested variable references are quite different from recursively expanded variables (see section The Two Flavors of Variables), though both are used together in complex ways when doing makefile programming.

How Variables Get Their Values

Variables can get values in several different ways:

  • You can specify an overriding value when you run make. See section Overriding Variables.
  • You can specify a value in the makefile, either with an assignment (see section Setting Variables) or with a verbatim definition (see section Defining Variables Verbatim).
  • Variables in the environment become make variables. See section Variables from the Environment.
  • Several automatic variables are given new values for each rule. Each of these has a single conventional use. See section Automatic Variables.
  • Several variables have constant initial values. See section Variables Used by Implicit Rules.

Setting Variables

To set a variable from the makefile, write a line starting with the variable name followed by `=' or `:='. Whatever follows the `=' or `:=' on the line becomes the value. For example,

objects = main.o foo.o bar.o utils.o

defines a variable named objects. Whitespace around the variable name and immediately after the `=' is ignored.

Variables defined with `=' are recursively expanded variables. Variables defined with `:=' are simply expanded variables; these definitions can contain variable references which will be expanded before the definition is made. See section The Two Flavors of Variables.

The variable name may contain function and variable references, which are expanded when the line is read to find the actual variable name to use.

There is no limit on the length of the value of a variable except the amount of swapping space on the computer. When a variable definition is long, it is a good idea to break it into several lines by inserting backslash-newline at convenient places in the definition. This will not affect the functioning of make, but it will make the makefile easier to read.

Most variable names are considered to have the empty string as a value if you have never set them. Several variables have built-in initial values that are not empty, but you can set them in the usual ways (see section Variables Used by Implicit Rules). Several special variables are set automatically to a new value for each rule; these are called the automatic variables (see section Automatic Variables).

If you'd like a variable to be set to a value only if it's not already set, then you can use the shorthand operator `?=' instead of `='. These two settings of the variable `FOO' are identical (see section The origin Function):

FOO ?= bar

and

ifeq ($(origin FOO), undefined)
FOO = bar
endif

Appending More Text to Variables

Often it is useful to add more text to the value of a variable already defined. You do this with a line containing `+=', like this:

objects += another.o

This takes the value of the variable objects, and adds the text `another.o' to it (preceded by a single space). Thus:

objects = main.o foo.o bar.o utils.o
objects += another.o

sets objects to `main.o foo.o bar.o utils.o another.o'.

Using `+=' is similar to:

objects = main.o foo.o bar.o utils.o
objects := $(objects) another.o

but differs in ways that become important when you use more complex values.

When the variable in question has not been defined before, `+=' acts just like normal `=': it defines a recursively-expanded variable. However, when there is a previous definition, exactly what `+=' does depends on what flavor of variable you defined originally. See section The Two Flavors of Variables, for an explanation of the two flavors of variables.

When you add to a variable's value with `+=', make acts essentially as if you had included the extra text in the initial definition of the variable. If you defined it first with `:=', making it a simply-expanded variable, `+=' adds to that simply-expanded definition, and expands the new text before appending it to the old value just as `:=' does (see section Setting Variables, for a full explanation of `:='). In fact,

variable := value
variable += more

is exactly equivalent to:

variable := value
variable := $(variable) more

On the other hand, when you use `+=' with a variable that you defined first to be recursively-expanded using plain `=', make does something a bit different. Recall that when you define a recursively-expanded variable, make does not expand the value you set for variable and function references immediately. Instead it stores the text verbatim, and saves these variable and function references to be expanded later, when you refer to the new variable (see section The Two Flavors of Variables). When you use `+=' on a recursively-expanded variable, it is this unexpanded text to which make appends the new text you specify.

variable = value
variable += more

is roughly equivalent to:

temp = value
variable = $(temp) more

except that of course it never defines a variable called temp. The importance of this comes when the variable's old value contains variable references. Take this common example:

CFLAGS = $(includes) -O
...
CFLAGS += -pg # enable profiling

The first line defines the CFLAGS variable with a reference to another variable, includes. (CFLAGS is used by the rules for C compilation; see section Catalogue of Implicit Rules.) Using `=' for the definition makes CFLAGS a recursively-expanded variable, meaning `$(includes) -O' is not expanded when make processes the definition of CFLAGS. Thus, includes need not be defined yet for its value to take effect. It only has to be defined before any reference to CFLAGS. If we tried to append to the value of CFLAGS without using `+=', we might do it like this:

CFLAGS := $(CFLAGS) -pg # enable profiling

This is pretty close, but not quite what we want. Using `:=' redefines CFLAGS as a simply-expanded variable; this means make expands the text `$(CFLAGS) -pg' before setting the variable. If includes is not yet defined, we get ` -O -pg', and a later definition of includes will have no effect. Conversely, by using `+=' we set CFLAGS to the unexpanded value `$(includes) -O -pg'. Thus we preserve the reference to includes, so if that variable gets defined at any later point, a reference like `$(CFLAGS)' still uses its value.

The override Directive

If a variable has been set with a command argument (see section Overriding Variables), then ordinary assignments in the makefile are ignored. If you want to set the variable in the makefile even though it was set with a command argument, you can use an override directive, which is a line that looks like this:

override variable = value

or

override variable := value

To append more text to a variable defined on the command line, use:

override variable += more text

See section Appending More Text to Variables.

The override directive was not invented for escalation in the war between makefiles and command arguments. It was invented so you can alter and add to values that the user specifies with command arguments.

For example, suppose you always want the `-g' switch when you run the C compiler, but you would like to allow the user to specify the other switches with a command argument just as usual. You could use this override directive:

override CFLAGS += -g

You can also use override directives with define directives. This is done as you might expect:

override define foo
bar
endef

See the next section for information about define.

Defining Variables Verbatim

Another way to set the value of a variable is to use the define directive. This directive has an unusual syntax which allows newline characters to be included in the value, which is convenient for defining canned sequences of commands (see section Defining Canned Command Sequences).

The define directive is followed on the same line by the name of the variable and nothing more. The value to give the variable appears on the following lines. The end of the value is marked by a line containing just the word endef. Aside from this difference in syntax, define works just like `=': it creates a recursively-expanded variable (see section The Two Flavors of Variables). The variable name may contain function and variable references, which are expanded when the directive is read to find the actual variable name to use.

define two-lines
echo foo
echo $(bar)
endef

The value in an ordinary assignment cannot contain a newline; but the newlines that separate the lines of the value in a define become part of the variable's value (except for the final newline which precedes the endef and is not considered part of the value).

The previous example is functionally equivalent to this:

two-lines = echo foo; echo $(bar)

since two commands separated by semicolon behave much like two separate shell commands. However, note that using two separate lines means make will invoke the shell twice, running an independent subshell for each line. See section Command Execution.

If you want variable definitions made with define to take precedence over command-line variable definitions, you can use the override directive together with define:

override define two-lines
foo
$(bar)
endef

See section The override Directive.

Variables from the Environment

Variables in make can come from the environment in which make is run. Every environment variable that make sees when it starts up is transformed into a make variable with the same name and value. But an explicit assignment in the makefile, or with a command argument, overrides the environment. (If the `-e' flag is specified, then values from the environment override assignments in the makefile. See section Summary of Options. But this is not recommended practice.)

Thus, by setting the variable CFLAGS in your environment, you can cause all C compilations in most makefiles to use the compiler switches you prefer. This is safe for variables with standard or conventional meanings because you know that no makefile will use them for other things. (But this is not totally reliable; some makefiles set CFLAGS explicitly and therefore are not affected by the value in the environment.)

When make is invoked recursively, variables defined in the outer invocation can be passed to inner invocations through the environment (see section Recursive Use of make). By default, only variables that came from the environment or the command line are passed to recursive invocations. You can use the export directive to pass other variables. See section Communicating Variables to a Sub-make, for full details.

Other use of variables from the environment is not recommended. It is not wise for makefiles to depend for their functioning on environment variables set up outside their control, since this would cause different users to get different results from the same makefile. This is against the whole purpose of most makefiles.

Such problems would be especially likely with the variable SHELL, which is normally present in the environment to specify the user's choice of interactive shell. It would be very undesirable for this choice to affect make. So make ignores the environment value of SHELL (except on MS-DOS and MS-Windows, where SHELL is usually not set. See section Command Execution.)

Target-specific Variable Values

Variable values in make are usually global; that is, they are the same regardless of where they are evaluated (unless they're reset, of course). One exception to that is automatic variables (see section Automatic Variables).

The other exception is target-specific variable values. This feature allows you to define different values for the same variable, based on the target that make is currently building. As with automatic variables, these values are only available within the context of a target's command script (and in other target-specific assignments).

Set a target-specific variable value like this:

target ... : variable-assignment

or like this:

target ... : override variable-assignment

Multiple target values create a target-specific variable value for each member of the target list individually.

The variable-assignment can be any valid form of assignment; recursive (`='), static (`:='), appending (`+='), or conditional (`?='). All variables that appear within the variable-assignment are evaluated within the context of the target: thus, any previously-defined target-specific variable values will be in effect. Note that this variable is actually distinct from any "global" value: the two variables do not have to have the same flavor (recursive vs. static).

Target-specific variables have the same priority as any other makefile variable. Variables provided on the command-line (and in the environment if the `-e' option is in force) will take precedence. Specifying the override directive will allow the target-specific variable value to be preferred.

There is one more special feature of target-specific variables: when you define a target-specific variable, that variable value is also in effect for all prerequisites of this target (unless those prerequisites override it with their own target-specific variable value). So, for example, a statement like this:

prog : CFLAGS = -g
prog : prog.o foo.o bar.o

will set CFLAGS to `-g' in the command script for `prog', but it will also set CFLAGS to `-g' in the command scripts that create `prog.o', `foo.o', and `bar.o', and any command scripts which create their prerequisites.

Pattern-specific Variable Values

In addition to target-specific variable values (see section Target-specific Variable Values), GNU make supports pattern-specific variable values. In this form, a variable is defined for any target that matches the pattern specified. Variables defined in this way are searched after any target-specific variables defined explicitly for that target, and before target-specific variables defined for the parent target.

Set a pattern-specific variable value like this:

pattern ... : variable-assignment

or like this:

pattern ... : override variable-assignment

where pattern is a %-pattern. As with target-specific variable values, multiple pattern values create a pattern-specific variable value for each pattern individually. The variable-assignment can be any valid form of assignment. Any command-line variable setting will take precedence, unless override is specified.

For example:

%.o : CFLAGS = -O

will assign CFLAGS the value of `-O' for all targets matching the pattern %.o.

Conditional Parts of Makefiles

A conditional causes part of a makefile to be obeyed or ignored depending on the values of variables. Conditionals can compare the value of one variable to another, or the value of a variable to a constant string. Conditionals control what make actually "sees" in the makefile, so they cannot be used to control shell commands at the time of execution.

Example of a Conditional

The following example of a conditional tells make to use one set of libraries if the CC variable is `gcc', and a different set of libraries otherwise. It works by controlling which of two command lines will be used as the command for a rule. The result is that `CC=gcc' as an argument to make changes not only which compiler is used but also which libraries are linked.

libs_for_gcc = -lgnu
normal_libs =

foo: $(objects)
ifeq ($(CC),gcc)
        $(CC) -o foo $(objects) $(libs_for_gcc)
else
        $(CC) -o foo $(objects) $(normal_libs)
endif

This conditional uses three directives: one ifeq, one else and one endif.

The ifeq directive begins the conditional, and specifies the condition. It contains two arguments, separated by a comma and surrounded by parentheses. Variable substitution is performed on both arguments and then they are compared. The lines of the makefile following the ifeq are obeyed if the two arguments match; otherwise they are ignored.

The else directive causes the following lines to be obeyed if the previous conditional failed. In the example above, this means that the second alternative linking command is used whenever the first alternative is not used. It is optional to have an else in a conditional.

The endif directive ends the conditional. Every conditional must end with an endif. Unconditional makefile text follows.

As this example illustrates, conditionals work at the textual level: the lines of the conditional are treated as part of the makefile, or ignored, according to the condition. This is why the larger syntactic units of the makefile, such as rules, may cross the beginning or the end of the conditional.

When the variable CC has the value `gcc', the above example has this effect:

foo: $(objects)
        $(CC) -o foo $(objects) $(libs_for_gcc)

When the variable CC has any other value, the effect is this:

foo: $(objects)
        $(CC) -o foo $(objects) $(normal_libs)

Equivalent results can be obtained in another way by conditionalizing a variable assignment and then using the variable unconditionally:

libs_for_gcc = -lgnu
normal_libs =

ifeq ($(CC),gcc)
  libs=$(libs_for_gcc)
else
  libs=$(normal_libs)
endif

foo: $(objects)
        $(CC) -o foo $(objects) $(libs)

Syntax of Conditionals

The syntax of a simple conditional with no else is as follows:

conditional-directive
text-if-true
endif

The text-if-true may be any lines of text, to be considered as part of the makefile if the condition is true. If the condition is false, no text is used instead.

The syntax of a complex conditional is as follows:

conditional-directive
text-if-true
else
text-if-false
endif

If the condition is true, text-if-true is used; otherwise, text-if-false is used instead. The text-if-false can be any number of lines of text.

The syntax of the conditional-directive is the same whether the conditional is simple or complex. There are four different directives that test different conditions. Here is a table of them:

ifeq (arg1, arg2)
ifeq 'arg1' 'arg2'
ifeq "arg1" "arg2"
ifeq "arg1" 'arg2'
ifeq 'arg1' "arg2"
Expand all variable references in arg1 and arg2 and compare them. If they are identical, the text-if-true is effective; otherwise, the text-if-false, if any, is effective. Often you want to test if a variable has a non-empty value. When the value results from complex expansions of variables and functions, expansions you would consider empty may actually contain whitespace characters and thus are not seen as empty. However, you can use the strip function (see section Functions for String Substitution and Analysis) to avoid interpreting whitespace as a non-empty value. For example:
ifeq ($(strip $(foo)),)
text-if-empty
endif
will evaluate text-if-empty even if the expansion of $(foo) contains whitespace characters.
ifneq (arg1, arg2)
ifneq 'arg1' 'arg2'
ifneq "arg1" "arg2"
ifneq "arg1" 'arg2'
ifneq 'arg1' "arg2"
Expand all variable references in arg1 and arg2 and compare them. If they are different, the text-if-true is effective; otherwise, the text-if-false, if any, is effective.
ifdef variable-name
If the variable variable-name has a non-empty value, the text-if-true is effective; otherwise, the text-if-false, if any, is effective. Variables that have never been defined have an empty value. Note that ifdef only tests whether a variable has a value. It does not expand the variable to see if that value is nonempty. Consequently, tests using ifdef return true for all definitions except those like foo =. To test for an empty value, use ifeq ($(foo),). For example,
bar =
foo = $(bar)
ifdef foo
frobozz = yes
else
frobozz = no
endif
sets `frobozz' to `yes', while:
foo =
ifdef foo
frobozz = yes
else
frobozz = no
endif
sets `frobozz' to `no'.
ifndef variable-name
If the variable variable-name has an empty value, the text-if-true is effective; otherwise, the text-if-false, if any, is effective.

Extra spaces are allowed and ignored at the beginning of the conditional directive line, but a tab is not allowed. (If the line begins with a tab, it will be considered a command for a rule.) Aside from this, extra spaces or tabs may be inserted with no effect anywhere except within the directive name or within an argument. A comment starting with `#' may appear at the end of the line.

The other two directives that play a part in a conditional are else and endif. Each of these directives is written as one word, with no arguments. Extra spaces are allowed and ignored at the beginning of the line, and spaces or tabs at the end. A comment starting with `#' may appear at the end of the line.

Conditionals affect which lines of the makefile make uses. If the condition is true, make reads the lines of the text-if-true as part of the makefile; if the condition is false, make ignores those lines completely. It follows that syntactic units of the makefile, such as rules, may safely be split across the beginning or the end of the conditional.

make evaluates conditionals when it reads a makefile. Consequently, you cannot use automatic variables in the tests of conditionals because they are not defined until commands are run (see section Automatic Variables).

To prevent intolerable confusion, it is not permitted to start a conditional in one makefile and end it in another. However, you may write an include directive within a conditional, provided you do not attempt to terminate the conditional inside the included file.

Conditionals that Test Flags

You can write a conditional that tests make command flags such as `-t' by using the variable MAKEFLAGS together with the findstring function (see section Functions for String Substitution and Analysis). This is useful when touch is not enough to make a file appear up to date.

The findstring function determines whether one string appears as a substring of another. If you want to test for the `-t' flag, use `t' as the first string and the value of MAKEFLAGS as the other.

For example, here is how to arrange to use `ranlib -t' to finish marking an archive file up to date:

archive.a: ...
ifneq (,$(findstring t,$(MAKEFLAGS)))
        +touch archive.a
        +ranlib -t archive.a
else
        ranlib archive.a
endif

The `+' prefix marks those command lines as "recursive" so that they will be executed despite use of the `-t' flag. See section Recursive Use of make.

Functions for Transforming Text

Functions allow you to do text processing in the makefile to compute the files to operate on or the commands to use. You use a function in a function call, where you give the name of the function and some text (the arguments) for the function to operate on. The result of the function's processing is substituted into the makefile at the point of the call, just as a variable might be substituted.

Function Call Syntax

A function call resembles a variable reference. It looks like this:

$(function arguments)

or like this:

${function arguments}

Here function is a function name; one of a short list of names that are part of make. You can also essentially create your own functions by using the call builtin function.

The arguments are the arguments of the function. They are separated from the function name by one or more spaces or tabs, and if there is more than one argument, then they are separated by commas. Such whitespace and commas are not part of an argument's value. The delimiters which you use to surround the function call, whether parentheses or braces, can appear in an argument only in matching pairs; the other kind of delimiters may appear singly. If the arguments themselves contain other function calls or variable references, it is wisest to use the same kind of delimiters for all the references; write `$(subst a,b,$(x))', not `$(subst a,b,${x})'. This is because it is clearer, and because only one type of delimiter is matched to find the end of the reference.

The text written for each argument is processed by substitution of variables and function calls to produce the argument value, which is the text on which the function acts. The substitution is done in the order in which the arguments appear.

Commas and unmatched parentheses or braces cannot appear in the text of an argument as written; leading spaces cannot appear in the text of the first argument as written. These characters can be put into the argument value by variable substitution. First define variables comma and space whose values are isolated comma and space characters, then substitute these variables where such characters are wanted, like this:

comma:= ,
empty:=
space:= $(empty) $(empty)
foo:= a b c
bar:= $(subst $(space),$(comma),$(foo))
# bar is now `a,b,c'.

Here the subst function replaces each space with a comma, through the value of foo, and substitutes the result.

Functions for String Substitution and Analysis

Here are some functions that operate on strings:

$(subst from,to,text)
Performs a textual replacement on the text text: each occurrence of from is replaced by to. The result is substituted for the function call. For example,
$(subst ee,EE,feet on the street)
substitutes the string `fEEt on the strEEt'.
$(patsubst pattern,replacement,text)
Finds whitespace-separated words in text that match pattern and replaces them with replacement. Here pattern may contain a `%' which acts as a wildcard, matching any number of any characters within a word. If replacement also contains a `%', the `%' is replaced by the text that matched the `%' in pattern. `%' characters in patsubst function invocations can be quoted with preceding backslashes (`\'). Backslashes that would otherwise quote `%' characters can be quoted with more backslashes. Backslashes that quote `%' characters or other backslashes are removed from the pattern before it is compared file names or has a stem substituted into it. Backslashes that are not in danger of quoting `%' characters go unmolested. For example, the pattern `the\%weird\\%pattern\\' has `the%weird\' preceding the operative `%' character, and `pattern\\' following it. The final two backslashes are left alone because they cannot affect any `%' character. Whitespace between words is folded into single space characters; leading and trailing whitespace is discarded. For example,
$(patsubst %.c,%.o,x.c.c bar.c)
produces the value `x.c.o bar.o'. Substitution references (see section Substitution References) are a simpler way to get the effect of the patsubst function:
$(var:pattern=replacement)
is equivalent to
$(patsubst pattern,replacement,$(var))
The second shorthand simplifies one of the most common uses of patsubst: replacing the suffix at the end of file names.
$(var:suffix=replacement)
is equivalent to
$(patsubst %suffix,%replacement,$(var))
For example, you might have a list of object files:
objects = foo.o bar.o baz.o
To get the list of corresponding source files, you could simply write:
$(objects:.o=.c)
instead of using the general form:
$(patsubst %.o,%.c,$(objects))
$(strip string)
Removes leading and trailing whitespace from string and replaces each internal sequence of one or more whitespace characters with a single space. Thus, `$(strip a b c )' results in `a b c'. The function strip can be very useful when used in conjunction with conditionals. When comparing something with the empty string `' using ifeq or ifneq, you usually want a string of just whitespace to match the empty string (see section Conditional Parts of Makefiles). Thus, the following may fail to have the desired results:
.PHONY: all
ifneq   "$(needs_made)" ""
all: $(needs_made)
else
all:;@echo 'Nothing to make!'
endif
Replacing the variable reference `$(needs_made)' with the function call `$(strip $(needs_made))' in the ifneq directive would make it more robust.
$(findstring find,in)
Searches in for an occurrence of find. If it occurs, the value is find; otherwise, the value is empty. You can use this function in a conditional to test for the presence of a specific substring in a given string. Thus, the two examples,
$(findstring a,a b c)
$(findstring a,b c)
produce the values `a' and `' (the empty string), respectively. See section Conditionals that Test Flags, for a practical application of findstring.
$(filter pattern...,text)
Returns all whitespace-separated words in text that do match any of the pattern words, removing any words that do not match. The patterns are written using `%', just like the patterns used in the patsubst function above. The filter function can be used to separate out different types of strings (such as file names) in a variable. For example:
sources := foo.c bar.c baz.s ugh.h
foo: $(sources)
        cc $(filter %.c %.s,$(sources)) -o foo
says that `foo' depends of `foo.c', `bar.c', `baz.s' and `ugh.h' but only `foo.c', `bar.c' and `baz.s' should be specified in the command to the compiler.
$(filter-out pattern...,text)
Returns all whitespace-separated words in text that do not match any of the pattern words, removing the words that do match one or more. This is the exact opposite of the filter function. Removes all whitespace-separated words in text that do match the pattern words, returning only the words that do not match. This is the exact opposite of the filter function. For example, given:
objects=main1.o foo.o main2.o bar.o
mains=main1.o main2.o
the following generates a list which contains all the object files not in `mains':
$(filter-out $(mains),$(objects))
$(sort list)
Sorts the words of list in lexical order, removing duplicate words. The output is a list of words separated by single spaces. Thus,
$(sort foo bar lose)
returns the value `bar foo lose'. Incidentally, since sort removes duplicate words, you can use it for this purpose even if you don't care about the sort order.

Here is a realistic example of the use of subst and patsubst. Suppose that a makefile uses the VPATH variable to specify a list of directories that make should search for prerequisite files (see section VPATH: Search Path for All Prerequisites). This example shows how to tell the C compiler to search for header files in the same list of directories.

The value of VPATH is a list of directories separated by colons, such as `src:../headers'. First, the subst function is used to change the colons to spaces:

$(subst :, ,$(VPATH))

This produces `src ../headers'. Then patsubst is used to turn each directory name into a `-I' flag. These can be added to the value of the variable CFLAGS, which is passed automatically to the C compiler, like this:

override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))

The effect is to append the text `-Isrc -I../headers' to the previously given value of CFLAGS. The override directive is used so that the new value is assigned even if the previous value of CFLAGS was specified with a command argument (see section The override Directive).

Functions for File Names

Several of the built-in expansion functions relate specifically to taking apart file names or lists of file names.

Each of the following functions performs a specific transformation on a file name. The argument of the function is regarded as a series of file names, separated by whitespace. (Leading and trailing whitespace is ignored.) Each file name in the series is transformed in the same way and the results are concatenated with single spaces between them.

$(dir names...)
Extracts the directory-part of each file name in names. The directory-part of the file name is everything up through (and including) the last slash in it. If the file name contains no slash, the directory part is the string `./'. For example,
$(dir src/foo.c hacks)
produces the result `src/ ./'.
$(notdir names...)
Extracts all but the directory-part of each file name in names. If the file name contains no slash, it is left unchanged. Otherwise, everything through the last slash is removed from it. A file name that ends with a slash becomes an empty string. This is unfortunate, because it means that the result does not always have the same number of whitespace-separated file names as the argument had; but we do not see any other valid alternative. For example,
$(notdir src/foo.c hacks)
produces the result `foo.c hacks'.
$(suffix names...)
Extracts the suffix of each file name in names. If the file name contains a period, the suffix is everything starting with the last period. Otherwise, the suffix is the empty string. This frequently means that the result will be empty when names is not, and if names contains multiple file names, the result may contain fewer file names. For example,
$(suffix src/foo.c src-1.0/bar.c hacks)
produces the result `.c .c'.
$(basename names...)
Extracts all but the suffix of each file name in names. If the file name contains a period, the basename is everything starting up to (and not including) the last period. Periods in the directory part are ignored. If there is no period, the basename is the entire file name. For example,
$(basename src/foo.c src-1.0/bar hacks)
produces the result `src/foo src-1.0/bar hacks'.
$(addsuffix suffix,names...)
The argument names is regarded as a series of names, separated by whitespace; suffix is used as a unit. The value of suffix is appended to the end of each individual name and the resulting larger names are concatenated with single spaces between them. For example,
$(addsuffix .c,foo bar)
produces the result `foo.c bar.c'.
$(addprefix prefix,names...)
The argument names is regarded as a series of names, separated by whitespace; prefix is used as a unit. The value of prefix is prepended to the front of each individual name and the resulting larger names are concatenated with single spaces between them. For example,
$(addprefix src/,foo bar)
produces the result `src/foo src/bar'.
$(join list1,list2)
Concatenates the two arguments word by word: the two first words (one from each argument) concatenated form the first word of the result, the two second words form the second word of the result, and so on. So the nth word of the result comes from the nth word of each argument. If one argument has more words that the other, the extra words are copied unchanged into the result. For example, `$(join a b,.c .o)' produces `a.c b.o'. Whitespace between the words in the lists is not preserved; it is replaced with a single space. This function can merge the results of the dir and notdir functions, to produce the original list of files which was given to those two functions.
$(word n,text)
Returns the nth word of text. The legitimate values of n start from 1. If n is bigger than the number of words in text, the value is empty. For example,
$(word 2, foo bar baz)
returns `bar'.
$(wordlist s,e,text)
Returns the list of words in text starting with word s and ending with word e (inclusive). The legitimate values of s and e start from 1. If s is bigger than the number of words in text, the value is empty. If e is bigger than the number of words in text, words up to the end of text are returned. If s is greater than e, nothing is returned. For example,
$(wordlist 2, 3, foo bar baz)
returns `bar baz'.
$(words text)
Returns the number of words in text. Thus, the last word of text is $(word $(words text),text).
$(firstword names...)
The argument names is regarded as a series of names, separated by whitespace. The value is the first name in the series. The rest of the names are ignored. For example,
$(firstword foo bar)
produces the result `foo'. Although $(firstword text) is the same as $(word 1,text), the firstword function is retained for its simplicity.
$(wildcard pattern)
The argument pattern is a file name pattern, typically containing wildcard characters (as in shell file name patterns). The result of wildcard is a space-separated list of the names of existing files that match the pattern. See section Using Wildcard Characters in File Names.

The foreach Function

The foreach function is very different from other functions. It causes one piece of text to be used repeatedly, each time with a different substitution performed on it. It resembles the for command in the shell sh and the foreach command in the C-shell csh.

The syntax of the foreach function is:

$(foreach var,list,text)

The first two arguments, var and list, are expanded before anything else is done; note that the last argument, text, is not expanded at the same time. Then for each word of the expanded value of list, the variable named by the expanded value of var is set to that word, and text is expanded. Presumably text contains references to that variable, so its expansion will be different each time.

The result is that text is expanded as many times as there are whitespace-separated words in list. The multiple expansions of text are concatenated, with spaces between them, to make the result of foreach.

This simple example sets the variable `files' to the list of all files in the directories in the list `dirs':

dirs := a b c d
files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))

Here text is `$(wildcard $(dir)/*)'. The first repetition finds the value `a' for dir, so it produces the same result as `$(wildcard a/*)'; the second repetition produces the result of `$(wildcard b/*)'; and the third, that of `$(wildcard c/*)'.

This example has the same result (except for setting `dirs') as the following example:

files := $(wildcard a/* b/* c/* d/*)

When text is complicated, you can improve readability by giving it a name, with an additional variable:

find_files = $(wildcard $(dir)/*)
dirs := a b c d
files := $(foreach dir,$(dirs),$(find_files))

Here we use the variable find_files this way. We use plain `=' to define a recursively-expanding variable, so that its value contains an actual function call to be reexpanded under the control of foreach; a simply-expanded variable would not do, since wildcard would be called only once at the time of defining find_files.

The foreach function has no permanent effect on the variable var; its value and flavor after the foreach function call are the same as they were beforehand. The other values which are taken from list are in effect only temporarily, during the execution of foreach. The variable var is a simply-expanded variable during the execution of foreach. If var was undefined before the foreach function call, it is undefined after the call. See section The Two Flavors of Variables.

You must take care when using complex variable expressions that result in variable names because many strange things are valid variable names, but are probably not what you intended. For example,

files := $(foreach Esta escrito en espanol!,b c ch,$(find_files))

might be useful if the value of find_files references the variable whose name is `Esta escrito en espanol!' (es un nombre bastante largo, no?), but it is more likely to be a mistake.

The if Function

The if function provides support for conditional expansion in a functional context (as opposed to the GNU make makefile conditionals such as ifeq (see section Syntax of Conditionals).

An if function call can contain either two or three arguments:

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

The first argument, condition, first has all preceding and trailing whitespace stripped, then is expanded. If it expands to any non-empty string, then the condition is considered to be true. If it expands to an empty string, the condition is considered to be false.

If the condition is true then the second argument, then-part, is evaluated and this is used as the result of the evaluation of the entire if function.

If the condition is false then the third argument, else-part, is evaluated and this is the result of the if function. If there is no third argument, the if function evaluates to nothing (the empty string).

Note that only one of the then-part or the else-part will be evaluated, never both. Thus, either can contain side-effects (such as shell function calls, etc.)

The call Function

The call function is unique in that it can be used to create new parameterized functions. You can write a complex expression as the value of a variable, then use call to expand it with different values.

The syntax of the call function is:

$(call variable,param,param,...)

When make expands this function, it assigns each param to temporary variables $(1), $(2), etc. The variable $(0) will contain variable. There is no maximum number of parameter arguments. There is no minimum, either, but it doesn't make sense to use call with no parameters.

Then variable is expanded as a make variable in the context of these temporary assignments. Thus, any reference to $(1) in the value of variable will resolve to the first param in the invocation of call.

Note that variable is the name of a variable, not a reference to that variable. Therefore you would not normally use a `$' or parentheses when writing it. (You can, however, use a variable reference in the name if you want the name not to be a constant.)

If variable is the name of a builtin function, the builtin function is always invoked (even if a make variable by that name also exists).

The call function expands the param arguments before assigning them to temporary variables. This means that variable values containing references to builtin functions that have special expansion rules, like foreach or if, may not work as you expect.

Some examples may make this clearer.

This macro simply reverses its arguments:

reverse = $(2) $(1)

foo = $(call reverse,a,b)

Here foo will contain `b a'.

This one is slightly more interesting: it defines a macro to search for the first instance of a program in PATH:

pathsearch = $(firstword $(wildcard $(addsufix /$(1),$(subst :, ,$(PATH)))))

LS := $(call pathsearch,ls)

Now the variable LS contains /bin/ls or similar.

The call function can be nested. Each recursive invocation gets its own local values for $(1), etc. that mask the values of higher-level call. For example, here is an implementation of a map function:

map = $(foreach a,$(2),$(call $(1),$(a)))

Now you can map a function that normally takes only one argument, such as origin, to multiple values in one step:

o = $(call map,origin,o map MAKE)

and end up with o containing something like `file file default'.

A final caution: be careful when adding whitespace to the arguments to call. As with other functions, any whitespace contained in the second and subsequent arguments is kept; this can cause strange effects. It's generally safest to remove all extraneous whitespace when providing parameters to call.

The origin Function

The origin function is unlike most other functions in that it does not operate on the values of variables; it tells you something about a variable. Specifically, it tells you where it came from.

The syntax of the origin function is:

$(origin variable)

Note that variable is the name of a variable to inquire about; not a reference to that variable. Therefore you would not normally use a `$' or parentheses when writing it. (You can, however, use a variable reference in the name if you want the name not to be a constant.)

The result of this function is a string telling you how the variable variable was defined:

`undefined'
if variable was never defined.
`default'
if variable has a default definition, as is usual with CC and so on. See section Variables Used by Implicit Rules. Note that if you have redefined a default variable, the origin function will return the origin of the later definition.
`environment'
if variable was defined as an environment variable and the `-e' option is not turned on (see section Summary of Options).
`environment override'
if variable was defined as an environment variable and the `-e' option is turned on (see section Summary of Options).
`file'
if variable was defined in a makefile.
`command line'
if variable was defined on the command line.
`override'
if variable was defined with an override directive in a makefile (see section The override Directive).
`automatic'
if variable is an automatic variable defined for the execution of the commands for each rule (see section Automatic Variables).

This information is primarily useful (other than for your curiosity) to determine if you want to believe the value of a variable. For example, suppose you have a makefile `foo' that includes another makefile `bar'. You want a variable bletch to be defined in `bar' if you run the command `make -f bar', even if the environment contains a definition of bletch. However, if `foo' defined bletch before including `bar', you do not want to override that definition. This could be done by using an override directive in `foo', giving that definition precedence over the later definition in `bar'; unfortunately, the override directive would also override any command line definitions. So, `bar' could include:

ifdef bletch
ifeq "$(origin bletch)" "environment"
bletch = barf, gag, etc.
endif
endif

If bletch has been defined from the environment, this will redefine it.

If you want to override a previous definition of bletch if it came from the environment, even under `-e', you could instead write:

ifneq "$(findstring environment,$(origin bletch))" ""
bletch = barf, gag, etc.
endif

Here the redefinition takes place if `$(origin bletch)' returns either `environment' or `environment override'. See section Functions for String Substitution and Analysis.

The shell Function

The shell function is unlike any other function except the wildcard function (see section The Function wildcard) in that it communicates with the world outside of make.

The shell function performs the same function that backquotes (``') perform in most shells: it does command expansion. This means that it takes an argument that is a shell command and returns the output of the command. The only processing make does on the result, before substituting it into the surrounding text, is to convert each newline or carriage-return / newline pair to a single space. It also removes the trailing (carriage-return and) newline, if it's the last thing in the result.

The commands run by calls to the shell function are run when the function calls are expanded. In most cases, this is when the makefile is read in. The exception is that function calls in the commands of the rules are expanded when the commands are run, and this applies to shell function calls like all others.

Here are some examples of the use of the shell function:

contents := $(shell cat foo)

sets contents to the contents of the file `foo', with a space (rather than a newline) separating each line.

files := $(shell echo *.c)

sets files to the expansion of `*.c'. Unless make is using a very strange shell, this has the same result as `$(wildcard *.c)'.

Functions That Control Make

These functions control the way make runs. Generally, they are used to provide information to the user of the makefile or to cause make to stop if some sort of environmental error is detected.

$(error text...)
Generates a fatal error where the message is text. Note that the error is generated whenever this function is evaluated. So, if you put it inside a command script or on the right side of a recursive variable assignment, it won't be evaluated until later. The text will be expanded before the error is generated. For example,
ifdef ERROR1
$(error error is $(ERROR1))
endif
will generate a fatal error during the read of the makefile if the make variable ERROR1 is defined. Or,
ERR = $(error found an error!)

.PHONY: err
err: ; $(ERR)
will generate a fatal error while make is running, if the err target is invoked.
$(warning text...)
This function works similarly to the error function, above, except that make doesn't exit. Instead, text is expanded and the resulting message is displayed, but processing of the makefile continues. The result of the expansion of this function is the empty string.

How to Run make

A makefile that says how to recompile a program can be used in more than one way. The simplest use is to recompile every file that is out of date. Usually, makefiles are written so that if you run make with no arguments, it does just that.

But you might want to update only some of the files; you might want to use a different compiler or different compiler options; you might want just to find out which files are out of date without changing them.

By giving arguments when you run make, you can do any of these things and many others.

The exit status of make is always one of three values:

0
The exit status is zero if make is successful.
2
The exit status is two if make encounters any errors. It will print messages describing the particular errors.
1
The exit status is one if you use the `-q' flag and make determines that some target is not already up to date. See section Instead of Executing the Commands.

Arguments to Specify the Makefile

The way to specify the name of the makefile is with the `-f' or `--file' option (`--makefile' also works). For example, `-f altmake' says to use the file `altmake' as the makefile.

If you use the `-f' flag several times and follow each `-f' with an argument, all the specified files are used jointly as makefiles.

If you do not use the `-f' or `--file' flag, the default is to try `GNUmakefile', `makefile', and `Makefile', in that order, and use the first of these three which exists or can be made (see section Writing Makefiles).

Arguments to Specify the Goals

The goals are the targets that make should strive ultimately to update. Other targets are updated as well if they appear as prerequisites of goals, or prerequisites of prerequisites of goals, etc.

By default, the goal is the first target in the makefile (not counting targets that start with a period). Therefore, makefiles are usually written so that the first target is for compiling the entire program or programs they describe. If the first rule in the makefile has several targets, only the first target in the rule becomes the default goal, not the whole list.

You can specify a different goal or goals with arguments to make. Use the name of the goal as an argument. If you specify several goals, make processes each of them in turn, in the order you name them.

Any target in the makefile may be specified as a goal (unless it starts with `-' or contains an `=', in which case it will be parsed as a switch or variable definition, respectively). Even targets not in the makefile may be specified, if make can find implicit rules that say how to make them.

Make will set the special variable MAKECMDGOALS to the list of goals you specified on the command line. If no goals were given on the command line, this variable is empty. Note that this variable should be used only in special circumstances.

An example of appropriate use is to avoid including `.d' files during clean rules (see section Generating Prerequisites Automatically), so make won't create them only to immediately remove them again:

sources = foo.c bar.c

ifneq ($(MAKECMDGOALS),clean)
include $(sources:.c=.d)
endif

One use of specifying a goal is if you want to compile only a part of the program, or only one of several programs. Specify as a goal each file that you wish to remake. For example, consider a directory containing several programs, with a makefile that starts like this:

.PHONY: all
all: size nm ld ar as

If you are working on the program size, you might want to say `make size' so that only the files of that program are recompiled.

Another use of specifying a goal is to make files that are not normally made. For example, there may be a file of debugging output, or a version of the program that is compiled specially for testing, which has a rule in the makefile but is not a prerequisite of the default goal.

Another use of specifying a goal is to run the commands associated with a phony target (see section Phony Targets) or empty target (see section Empty Target Files to Record Events). Many makefiles contain a phony target named `clean' which deletes everything except source files. Naturally, this is done only if you request it explicitly with `make clean'. Following is a list of typical phony and empty target names. See section Standard Targets for Users, for a detailed list of all the standard target names which GNU software packages use.

`all'
Make all the top-level targets the makefile knows about.
`clean'
Delete all files that are normally created by running make.
`mostlyclean'
Like `clean', but may refrain from deleting a few files that people normally don't want to recompile. For example, the `mostlyclean' target for GCC does not delete `libgcc.a', because recompiling it is rarely necessary and takes a lot of time.
`distclean'
`realclean'
`clobber'
Any of these targets might be defined to delete more files than `clean' does. For example, this would delete configuration files or links that you would normally create as preparation for compilation, even if the makefile itself cannot create these files.
`install'
Copy the executable file into a directory that users typically search for commands; copy any auxiliary files that the executable uses into the directories where it will look for them.
`print'
Print listings of the source files that have changed.
`tar'
Create a tar file of the source files.
`shar'
Create a shell archive (shar file) of the source files.
`dist'
Create a distribution file of the source files. This might be a tar file, or a shar file, or a compressed version of one of the above, or even more than one of the above.
`TAGS'
Update a tags table for this program.
`check'
`test'
Perform self tests on the program this makefile builds.

Instead of Executing the Commands

The makefile tells make how to tell whether a target is up to date, and how to update each target. But updating the targets is not always what you want. Certain options specify other activities for make.

`-n'
`--just-print'
`--dry-run'
`--recon'
"No-op". The activity is to print what commands would be used to make the targets up to date, but not actually execute them.
`-t'
`--touch'
"Touch". The activity is to mark the targets as up to date without actually changing them. In other words, make pretends to compile the targets but does not really change their contents.
`-q'
`--question'
"Question". The activity is to find out silently whether the targets are up to date already; but execute no commands in either case. In other words, neither compilation nor output will occur.
`-W file'
`--what-if=file'
`--assume-new=file'
`--new-file=file'
"What if". Each `-W' flag is followed by a file name. The given files' modification times are recorded by make as being the present time, although the actual modification times remain the same. You can use the `-W' flag in conjunction with the `-n' flag to see what would happen if you were to modify specific files.

With the `-n' flag, make prints the commands that it would normally execute but does not execute them.

With the `-t' flag, make ignores the commands in the rules and uses (in effect) the command touch for each target that needs to be remade. The touch command is also printed, unless `-s' or .SILENT is used. For speed, make does not actually invoke the program touch. It does the work directly.

With the `-q' flag, make prints nothing and executes no commands, but the exit status code it returns is zero if and only if the targets to be considered are already up to date. If the exit status is one, then some updating needs to be done. If make encounters an error, the exit status is two, so you can distinguish an error from a target that is not up to date.

It is an error to use more than one of these three flags in the same invocation of make.

The `-n', `-t', and `-q' options do not affect command lines that begin with `+' characters or contain the strings `$(MAKE)' or `${MAKE}'. Note that only the line containing the `+' character or the strings `$(MAKE)' or `${MAKE}' is run regardless of these options. Other lines in the same rule are not run unless they too begin with `+' or contain `$(MAKE)' or `${MAKE}' (See section How the MAKE Variable Works.)

The `-W' flag provides two features:

  • If you also use the `-n' or `-q' flag, you can see what make would do if you were to modify some files.
  • Without the `-n' or `-q' flag, when make is actually executing commands, the `-W' flag can direct make to act as if some files had been modified, without actually modifying the files.

Note that the options `-p' and `-v' allow you to obtain other information about make or about the makefiles in use (see section Summary of Options).

Avoiding Recompilation of Some Files

Sometimes you may have changed a source file but you do not want to recompile all the files that depend on it. For example, suppose you add a macro or a declaration to a header file that many other files depend on. Being conservative, make assumes that any change in the header file requires recompilation of all dependent files, but you know that they do not need to be recompiled and you would rather not waste the time waiting for them to compile.

If you anticipate the problem before changing the header file, you can use the `-t' flag. This flag tells make not to run the commands in the rules, but rather to mark the target up to date by changing its last-modification date. You would follow this procedure:

  1. Use the command `make' to recompile the source files that really need recompilation.
  2. Make the changes in the header files.
  3. Use the command `make -t' to mark all the object files as up to date. The next time you run make, the changes in the header files will not cause any recompilation.

If you have already changed the header file at a time when some files do need recompilation, it is too late to do this. Instead, you can use the `-o file' flag, which marks a specified file as "old" (see section Summary of Options). This means that the file itself will not be remade, and nothing else will be remade on its account. Follow this procedure:

  1. Recompile the source files that need compilation for reasons independent of the particular header file, with `make -o headerfile'. If several header files are involved, use a separate `-o' option for each header file.
  2. Touch all the object files with `make -t'.

Overriding Variables

An argument that contains `=' specifies the value of a variable: `v=x' sets the value of the variable v to x. If you specify a value in this way, all ordinary assignments of the same variable in the makefile are ignored; we say they have been overridden by the command line argument.

The most common way to use this facility is to pass extra flags to compilers. For example, in a properly written makefile, the variable CFLAGS is included in each command that runs the C compiler, so a file `foo.c' would be compiled something like this:

cc -c $(CFLAGS) foo.c

Thus, whatever value you set for CFLAGS affects each compilation that occurs. The makefile probably specifies the usual value for CFLAGS, like this:

CFLAGS=-g

Each time you run make, you can override this value if you wish. For example, if you say `make CFLAGS='-g -O'', each C compilation will be done with `cc -c -g -O'. (This illustrates how you can use quoting in the shell to enclose spaces and other special characters in the value of a variable when you override it.)

The variable CFLAGS is only one of many standard variables that exist just so that you can change them this way. See section Variables Used by Implicit Rules, for a complete list.

You can also program the makefile to look at additional variables of your own, giving the user the ability to control other aspects of how the makefile works by changing the variables.

When you override a variable with a command argument, you can define either a recursively-expanded variable or a simply-expanded variable. The examples shown above make a recursively-expanded variable; to make a simply-expanded variable, write `:=' instead of `='. But, unless you want to include a variable reference or function call in the value that you specify, it makes no difference which kind of variable you create.

There is one way that the makefile can change a variable that you have overridden. This is to use the override directive, which is a line that looks like this: `override variable = value' (see section The override Directive).

Testing the Compilation of a Program

Normally, when an error happens in executing a shell command, make gives up immediately, returning a nonzero status. No further commands are executed for any target. The error implies that the goal cannot be correctly remade, and make reports this as soon as it knows.

When you are compiling a program that you have just changed, this is not what you want. Instead, you would rather that make try compiling every file that can be tried, to show you as many compilation errors as possible.

On these occasions, you should use the `-k' or `--keep-going' flag. This tells make to continue to consider the other prerequisites of the pending targets, remaking them if necessary, before it gives up and returns nonzero status. For example, after an error in compiling one object file, `make -k' will continue compiling other object files even though it already knows that linking them will be impossible. In addition to continuing after failed shell commands, `make -k' will continue as much as possible after discovering that it does not know how to make a target or prerequisite file. This will always cause an error message, but without `-k', it is a fatal error (see section Summary of Options).

The usual behavior of make assumes that your purpose is to get the goals up to date; once make learns that this is impossible, it might as well report the failure immediately. The `-k' flag says that the real purpose is to test as much as possible of the changes made in the program, perhaps to find several independent problems so that you can correct them all before the next attempt to compile. This is why Emacs' M-x compile command passes the `-k' flag by default.

Summary of Options

Here is a table of all the options make understands:

`-b'
`-m'
These options are ignored for compatibility with other versions of make.
`-C dir'
`--directory=dir'
Change to directory dir before reading the makefiles. If multiple `-C' options are specified, each is interpreted relative to the previous one: `-C / -C etc' is equivalent to `-C /etc'. This is typically used with recursive invocations of make (see section Recursive Use of make).
`-d'
Print debugging information in addition to normal processing. The debugging information says which files are being considered for remaking, which file-times are being compared and with what results, which files actually need to be remade, which implicit rules are considered and which are applied--everything interesting about how make decides what to do. The -d option is equivalent to `--debug=a' (see below).
`--debug[=options]'
Print debugging information in addition to normal processing. Various levels and types of output can be chosen. With no arguments, print the "basic" level of debugging. Possible arguments are below; only the first character is considered, and values must be comma- or space-separated.
a (all)
All types of debugging output are enabled. This is equivalent to using `-d'.
b (basic)
Basic debugging prints each target that was found to be out-of-date, and whether the build was successful or not.
v (verbose)
A level above `basic'; includes messages about which makefiles were parsed, prerequisites that did not need to be rebuilt, etc. This option also enables `basic' messages.
i (implicit)
Prints messages describing the implicit rule searches for each target. This option also enables `basic' messages.
j (jobs)
Prints messages giving details on the invocation of specific subcommands.
m (makefile)
By default, the above messages are not enabled while trying to remake the makefiles. This option enables messages while rebuilding makefiles, too. Note that the `all' option does enable this option. This option also enables `basic' messages.
`-e'
`--environment-overrides'
Give variables taken from the environment precedence over variables from makefiles. See section Variables from the Environment.
`-f file'
`--file=file'
`--makefile=file'
Read the file named file as a makefile. See section Writing Makefiles.
`-h'
`--help'
Remind you of the options that make understands and then exit.
`-i'
`--ignore-errors'
Ignore all errors in commands executed to remake files. See section Errors in Commands.
`-I dir'
`--include-dir=dir'
Specifies a directory dir to search for included makefiles. See section Including Other Makefiles. If several `-I' options are used to specify several directories, the directories are searched in the order specified.
`-j [jobs]'
`--jobs[=jobs]'
Specifies the number of jobs (commands) to run simultaneously. With no argument, make runs as many jobs simultaneously as possible. If there is more than one `-j' option, the last one is effective. See section Parallel Execution, for more information on how commands are run. Note that this option is ignored on MS-DOS.
`-k'
`--keep-going'
Continue as much as possible after an error. While the target that failed, and those that depend on it, cannot be remade, the other prerequisites of these targets can be processed all the same. See section Testing the Compilation of a Program.
`-l [load]'
`--load-average[=load]'
`--max-load[=load]'
Specifies that no new jobs (commands) should be started if there are other jobs running and the load average is at least load (a floating-point number). With no argument, removes a previous load limit. See section Parallel Execution.
`-n'
`--just-print'
`--dry-run'
`--recon'
Print the commands that would be executed, but do not execute them. See section Instead of Executing the Commands.
`-o file'
`--old-file=file'
`--assume-old=file'
Do not remake the file file even if it is older than its prerequisites, and do not remake anything on account of changes in file. Essentially the file is treated as very old and its rules are ignored. See section Avoiding Recompilation of Some Files.
`-p'
`--print-data-base'
Print the data base (rules and variable values) that results from reading the makefiles; then execute as usual or as otherwise specified. This also prints the version information given by the `-v' switch (see below). To print the data base without trying to remake any files, use `make -qp'. To print the data base of predefined rules and variables, use `make -p -f /dev/null'. The data base output contains filename and linenumber information for command and variable definitions, so it can be a useful debugging tool in complex environments.
`-q'
`--question'
"Question mode". Do not run any commands, or print anything; just return an exit status that is zero if the specified targets are already up to date, one if any remaking is required, or two if an error is encountered. See section Instead of Executing the Commands.
`-r'
`--no-builtin-rules'
Eliminate use of the built-in implicit rules (see section Using Implicit Rules). You can still define your own by writing pattern rules (see section Defining and Redefining Pattern Rules). The `-r' option also clears out the default list of suffixes for suffix rules (see section Old-Fashioned Suffix Rules). But you can still define your own suffixes with a rule for .SUFFIXES, and then define your own suffix rules. Note that only rules are affected by the -r option; default variables remain in effect (see section Variables Used by Implicit Rules); see the `-R' option below.
`-R'
`--no-builtin-variables'
Eliminate use of the built-in rule-specific variables (see section Variables Used by Implicit Rules). You can still define your own, of course. The `-R' option also automatically enables the `-r' option (see above), since it doesn't make sense to have implicit rules without any definitions for the variables that they use.
`-s'
`--silent'
`--quiet'
Silent operation; do not print the commands as they are executed. See section Command Echoing.
`-S'
`--no-keep-going'
`--stop'
Cancel the effect of the `-k' option. This is never necessary except in a recursive make where `-k' might be inherited from the top-level make via MAKEFLAGS (see section Recursive Use of make) or if you set `-k' in MAKEFLAGS in your environment.
`-t'
`--touch'
Touch files (mark them up to date without really changing them) instead of running their commands. This is used to pretend that the commands were done, in order to fool future invocations of make. See section Instead of Executing the Commands.
`-v'
`--version'
Print the version of the make program plus a copyright, a list of authors, and a notice that there is no warranty; then exit.
`-w'
`--print-directory'
Print a message containing the working directory both before and after executing the makefile. This may be useful for tracking down errors from complicated nests of recursive make commands. See section Recursive Use of make. (In practice, you rarely need to specify this option since `make' does it for you; see section The `--print-directory' Option.)
`--no-print-directory'
Disable printing of the working directory under -w. This option is useful when -w is turned on automatically, but you do not want to see the extra messages. See section The `--print-directory' Option.
`-W file'
`--what-if=file'
`--new-file=file'
`--assume-new=file'
Pretend that the target file has just been modified. When used with the `-n' flag, this shows you what would happen if you were to modify that file. Without `-n', it is almost the same as running a touch command on the given file before running make, except that the modification time is changed only in the imagination of make. See section Instead of Executing the Commands.
`--warn-undefined-variables'
Issue a warning message whenever make sees a reference to an undefined variable. This can be helpful when you are trying to debug makefiles which use variables in complex ways.

Using Implicit Rules

Certain standard ways of remaking target files are used very often. For example, one customary way to make an object file is from a C source file using the C compiler, cc.

Implicit rules tell make how to use customary techniques so that you do not have to specify them in detail when you want to use them. For example, there is an implicit rule for C compilation. File names determine which implicit rules are run. For example, C compilation typically takes a `.c' file and makes a `.o' file. So make applies the implicit rule for C compilation when it sees this combination of file name endings.

A chain of implicit rules can apply in sequence; for example, make will remake a `.o' file from a `.y' file by way of a `.c' file. See section Chains of Implicit Rules.

The built-in implicit rules use several variables in their commands so that, by changing the values of the variables, you can change the way the implicit rule works. For example, the variable CFLAGS controls the flags given to the C compiler by the implicit rule for C compilation. See section Variables Used by Implicit Rules.

You can define your own implicit rules by writing pattern rules. See section Defining and Redefining Pattern Rules.

Suffix rules are a more limited way to define implicit rules. Pattern rules are more general and clearer, but suffix rules are retained for compatibility. See section Old-Fashioned Suffix Rules.

Using Implicit Rules

To allow make to find a customary method for updating a target file, all you have to do is refrain from specifying commands yourself. Either write a rule with no command lines, or don't write a rule at all. Then make will figure out which implicit rule to use based on which kind of source file exists or can be made.

For example, suppose the makefile looks like this:

foo : foo.o bar.o
        cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)

Because you mention `foo.o' but do not give a rule for it, make will automatically look for an implicit rule that tells how to update it. This happens whether or not the file `foo.o' currently exists.

If an implicit rule is found, it can supply both commands and one or more prerequisites (the source files). You would want to write a rule for `foo.o' with no command lines if you need to specify additional prerequisites, such as header files, that the implicit rule cannot supply.

Each implicit rule has a target pattern and prerequisite patterns. There may be many implicit rules with the same target pattern. For example, numerous rules make `.o' files: one, from a `.c' file with the C compiler; another, from a `.p' file with the Pascal compiler; and so on. The rule that actually applies is the one whose prerequisites exist or can be made. So, if you have a file `foo.c', make will run the C compiler; otherwise, if you have a file `foo.p', make will run the Pascal compiler; and so on.

Of course, when you write the makefile, you know which implicit rule you want make to use, and you know it will choose that one because you know which possible prerequisite files are supposed to exist. See section Catalogue of Implicit Rules, for a catalogue of all the predefined implicit rules.

Above, we said an implicit rule applies if the required prerequisites "exist or can be made". A file "can be made" if it is mentioned explicitly in the makefile as a target or a prerequisite, or if an implicit rule can be recursively found for how to make it. When an implicit prerequisite is the result of another implicit rule, we say that chaining is occurring. See section Chains of Implicit Rules.

In general, make searches for an implicit rule for each target, and for each double-colon rule, that has no commands. A file that is mentioned only as a prerequisite is considered a target whose rule specifies nothing, so implicit rule search happens for it. See section Implicit Rule Search Algorithm, for the details of how the search is done.

Note that explicit prerequisites do not influence implicit rule search. For example, consider this explicit rule:

foo.o: foo.p

The prerequisite on `foo.p' does not necessarily mean that make will remake `foo.o' according to the implicit rule to make an object file, a `.o' file, from a Pascal source file, a `.p' file. For example, if `foo.c' also exists, the implicit rule to make an object file from a C source file is used instead, because it appears before the Pascal rule in the list of predefined implicit rules (see section Catalogue of Implicit Rules).

If you do not want an implicit rule to be used for a target that has no commands, you can give that target empty commands by writing a semicolon (see section Using Empty Commands).

Catalogue of Implicit Rules

Here is a catalogue of predefined implicit rules which are always available unless the makefile explicitly overrides or cancels them. See section Canceling Implicit Rules, for information on canceling or overriding an implicit rule. The `-r' or `--no-builtin-rules' option cancels all predefined rules.

Not all of these rules will always be defined, even when the `-r' option is not given. Many of the predefined implicit rules are implemented in make as suffix rules, so which ones will be defined depends on the suffix list (the list of prerequisites of the special target .SUFFIXES). The default suffix list is: .out, .a, .ln, .o, .c, .cc, .C, .p, .f, .F, .r, .y, .l, .s, .S, .mod, .sym, .def, .h, .info, .dvi, .tex, .texinfo, .texi, .txinfo, .w, .ch .web, .sh, .elc, .el. All of the implicit rules described below whose prerequisites have one of these suffixes are actually suffix rules. If you modify the suffix list, the only predefined suffix rules in effect will be those named by one or two of the suffixes that are on the list you specify; rules whose suffixes fail to be on the list are disabled. See section Old-Fashioned Suffix Rules, for full details on suffix rules.

Compiling C programs
`n.o' is made automatically from `n.c' with a command of the form `$(CC) -c $(CPPFLAGS) $(CFLAGS)'.
Compiling C++ programs
`n.o' is made automatically from `n.cc' or `n.C' with a command of the form `$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)'. We encourage you to use the suffix `.cc' for C++ source files instead of `.C'.
Compiling Pascal programs
`n.o' is made automatically from `n.p' with the command `$(PC) -c $(PFLAGS)'.
Compiling Fortran and Ratfor programs
`n.o' is made automatically from `n.r', `n.F' or `n.f' by running the Fortran compiler. The precise command used is as follows:
`.f'
`$(FC) -c $(FFLAGS)'.
`.F'
`$(FC) -c $(FFLAGS) $(CPPFLAGS)'.
`.r'
`$(FC) -c $(FFLAGS) $(RFLAGS)'.
Preprocessing Fortran and Ratfor programs
`n.f' is made automatically from `n.r' or `n.F'. This rule runs just the preprocessor to convert a Ratfor or preprocessable Fortran program into a strict Fortran program. The precise command used is as follows:
`.F'
`$(FC) -F $(CPPFLAGS) $(FFLAGS)'.
`.r'
`$(FC) -F $(FFLAGS) $(RFLAGS)'.
Compiling Modula-2 programs
`n.sym' is made from `n.def' with a command of the form `$(M2C) $(M2FLAGS) $(DEFFLAGS)'. `n.o' is made from `n.mod'; the form is: `$(M2C) $(M2FLAGS) $(MODFLAGS)'.
Assembling and preprocessing assembler programs
`n.o' is made automatically from `n.s' by running the assembler, as. The precise command is `$(AS) $(ASFLAGS)'. `n.s' is made automatically from `n.S' by running the C preprocessor, cpp. The precise command is `$(CPP) $(CPPFLAGS)'.
Linking a single object file
`n' is made automatically from `n.o' by running the linker (usually called ld) via the C compiler. The precise command used is `$(CC) $(LDFLAGS) n.o $(LOADLIBES) $(LDLIBS)'. This rule does the right thing for a simple program with only one source file. It will also do the right thing if there are multiple object files (presumably coming from various other source files), one of which has a name matching that of the executable file. Thus,
x: y.o z.o
when `x.c', `y.c' and `z.c' all exist will execute:
cc -c x.c -o x.o
cc -c y.c -o y.o
cc -c z.c -o z.o
cc x.o y.o z.o -o x
rm -f x.o
rm -f y.o
rm -f z.o
In more complicated cases, such as when there is no object file whose name derives from the executable file name, you must write an explicit command for linking. Each kind of file automatically made into `.o' object files will be automatically linked by using the compiler (`$(CC)', `$(FC)' or `$(PC)'; the C compiler `$(CC)' is used to assemble `.s' files) without the `-c' option. This could be done by using the `.o' object files as intermediates, but it is faster to do the compiling and linking in one step, so that's how it's done.
Yacc for C programs
`n.c' is made automatically from `n.y' by running Yacc with the command `$(YACC) $(YFLAGS)'.
Lex for C programs
`n.c' is made automatically from `n.l' by by running Lex. The actual command is `$(LEX) $(LFLAGS)'.
Lex for Ratfor programs
`n.r' is made automatically from `n.l' by by running Lex. The actual command is `$(LEX) $(LFLAGS)'. The convention of using the same suffix `.l' for all Lex files regardless of whether they produce C code or Ratfor code makes it impossible for make to determine automatically which of the two languages you are using in any particular case. If make is called upon to remake an object file from a `.l' file, it must guess which compiler to use. It will guess the C compiler, because that is more common. If you are using Ratfor, make sure make knows this by mentioning `n.r' in the makefile. Or, if you are using Ratfor exclusively, with no C files, remove `.c' from the list of implicit rule suffixes with:
.SUFFIXES:
.SUFFIXES: .o .r .f .l ...
Making Lint Libraries from C, Yacc, or Lex programs
`n.ln' is made from `n.c' by running lint. The precise command is `$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i'. The same command is used on the C code produced from `n.y' or `n.l'.
TeX and Web
`n.dvi' is made from `n.tex' with the command `$(TEX)'. `n.tex' is made from `n.web' with `$(WEAVE)', or from `n.w' (and from `n.ch' if it exists or can be made) with `$(CWEAVE)'. `n.p' is made from `n.web' with `$(TANGLE)' and `n.c' is made from `n.w' (and from `n.ch' if it exists or can be made) with `$(CTANGLE)'.
Texinfo and Info
`n.dvi' is made from `n.texinfo', `n.texi', or `n.txinfo', with the command `$(TEXI2DVI) $(TEXI2DVI_FLAGS)'. `n.info' is made from `n.texinfo', `n.texi', or `n.txinfo', with the command `$(MAKEINFO) $(MAKEINFO_FLAGS)'.
RCS
Any file `n' is extracted if necessary from an RCS file named either `n,v' or `RCS/n,v'. The precise command used is `$(CO) $(COFLAGS)'. `n' will not be extracted from RCS if it already exists, even if the RCS file is newer. The rules for RCS are terminal (see section Match-Anything Pattern Rules), so RCS files cannot be generated from another source; they must actually exist.
SCCS
Any file `n' is extracted if necessary from an SCCS file named either `s.n' or `SCCS/s.n'. The precise command used is `$(GET) $(GFLAGS)'. The rules for SCCS are terminal (see section Match-Anything Pattern Rules), so SCCS files cannot be generated from another source; they must actually exist. For the benefit of SCCS, a file `n' is copied from `n.sh' and made executable (by everyone). This is for shell scripts that are checked into SCCS. Since RCS preserves the execution permission of a file, you do not need to use this feature with RCS. We recommend that you avoid using of SCCS. RCS is widely held to be superior, and is also free. By choosing free software in place of comparable (or inferior) proprietary software, you support the free software movement.

Usually, you want to change only the variables listed in the table above, which are documented in the following section.

However, the commands in built-in implicit rules actually use variables such as COMPILE.c, LINK.p, and PREPROCESS.S, whose values contain the commands listed above.

make follows the convention that the rule to compile a `.x' source file uses the variable COMPILE.x. Similarly, the rule to produce an executable from a `.x' file uses LINK.x; and the rule to preprocess a `.x' file uses PREPROCESS.x.

Every rule that produces an object file uses the variable OUTPUT_OPTION. make defines this variable either to contain `-o $@', or to be empty, depending on a compile-time option. You need the `-o' option to ensure that the output goes into the right file when the source file is in a different directory, as when using VPATH (see section Searching Directories for Prerequisites). However, compilers on some systems do not accept a `-o' switch for object files. If you use such a system, and use VPATH, some compilations will put their output in the wrong place. A possible workaround for this problem is to give OUTPUT_OPTION the value `; mv $*.o $@'.

Variables Used by Implicit Rules

The commands in built-in implicit rules make liberal use of certain predefined variables. You can alter these variables in the makefile, with arguments to make, or in the environment to alter how the implicit rules work without redefining the rules themselves. You can cancel all variables used by implicit rules with the `-R' or `--no-builtin-variables' option.

For example, the command used to compile a C source file actually says `$(CC) -c $(CFLAGS) $(CPPFLAGS)'. The default values of the variables used are `cc' and nothing, resulting in the command `cc -c'. By redefining `CC' to `ncc', you could cause `ncc' to be used for all C compilations performed by the implicit rule. By redefining `CFLAGS' to be `-g', you could pass the `-g' option to each compilation. All implicit rules that do C compilation use `$(CC)' to get the program name for the compiler and all include `$(CFLAGS)' among the arguments given to the compiler.

The variables used in implicit rules fall into two classes: those that are names of programs (like CC) and those that contain arguments for the programs (like CFLAGS). (The "name of a program" may also contain some command arguments, but it must start with an actual executable program name.) If a variable value contains more than one argument, separate them with spaces.

Here is a table of variables used as names of programs in built-in rules:

AR
Archive-maintaining program; default `ar'.
AS
Program for doing assembly; default `as'.
CC
Program for compiling C programs; default `cc'.
CXX
Program for compiling C++ programs; default `g++'.
CO
Program for extracting a file from RCS; default `co'.
CPP
Program for running the C preprocessor, with results to standard output; default `$(CC) -E'.
FC
Program for compiling or preprocessing Fortran and Ratfor programs; default `f77'.
GET
Program for extracting a file from SCCS; default `get'.
LEX
Program to use to turn Lex grammars into C programs or Ratfor programs; default `lex'.
PC
Program for compiling Pascal programs; default `pc'.
YACC
Program to use to turn Yacc grammars into C programs; default `yacc'.
YACCR
Program to use to turn Yacc grammars into Ratfor programs; default `yacc -r'.
MAKEINFO
Program to convert a Texinfo source file into an Info file; default `makeinfo'.
TEX
Program to make TeX DVI files from TeX source; default `tex'.
TEXI2DVI
Program to make TeX DVI files from Texinfo source; default `texi2dvi'.
WEAVE
Program to translate Web into TeX; default `weave'.
CWEAVE
Program to translate C Web into TeX; default `cweave'.
TANGLE
Program to translate Web into Pascal; default `tangle'.
CTANGLE
Program to translate C Web into C; default `ctangle'.
RM
Command to remove a file; default `rm -f'.

Here is a table of variables whose values are additional arguments for the programs above. The default values for all of these is the empty string, unless otherwise noted.

ARFLAGS
Flags to give the archive-maintaining program; default `rv'.
ASFLAGS
Extra flags to give to the assembler (when explicitly invoked on a `.s' or `.S' file).
CFLAGS
Extra flags to give to the C compiler.
CXXFLAGS
Extra flags to give to the C++ compiler.
COFLAGS
Extra flags to give to the RCS co program.
CPPFLAGS
Extra flags to give to the C preprocessor and programs that use it (the C and Fortran compilers).
FFLAGS
Extra flags to give to the Fortran compiler.
GFLAGS
Extra flags to give to the SCCS get program.
LDFLAGS
Extra flags to give to compilers when they are supposed to invoke the linker, `ld'.
LFLAGS
Extra flags to give to Lex.
PFLAGS
Extra flags to give to the Pascal compiler.
RFLAGS
Extra flags to give to the Fortran compiler for Ratfor programs.
YFLAGS
Extra flags to give to Yacc.

Chains of Implicit Rules

Sometimes a file can be made by a sequence of implicit rules. For example, a file `n.o' could be made from `n.y' by running first Yacc and then cc. Such a sequence is called a chain.

If the file `n.c' exists, or is mentioned in the makefile, no special searching is required: make finds that the object file can be made by C compilation from `n.c'; later on, when considering how to make `n.c', the rule for running Yacc is used. Ultimately both `n.c' and `n.o' are updated.

However, even if `n.c' does not exist and is not mentioned, make knows how to envision it as the missing link between `n.o' and `n.y'! In this case, `n.c' is called an intermediate file. Once make has decided to use the intermediate file, it is entered in the data base as if it had been mentioned in the makefile, along with the implicit rule that says how to create it.

Intermediate files are remade using their rules just like all other files. But intermediate files are treated differently in two ways.

The first difference is what happens if the intermediate file does not exist. If an ordinary file b does not exist, and make considers a target that depends on b, it invariably creates b and then updates the target from b. But if b is an intermediate file, then make can leave well enough alone. It won't bother updating b, or the ultimate target, unless some prerequisite of b is newer than that target or there is some other reason to update that target.

The second difference is that if make does create b in order to update something else, it deletes b later on after it is no longer needed. Therefore, an intermediate file which did not exist before make also does not exist after make. make reports the deletion to you by printing a `rm -f' command showing which file it is deleting.

Ordinarily, a file cannot be intermediate if it is mentioned in the makefile as a target or prerequisite. However, you can explicitly mark a file as intermediate by listing it as a prerequisite of the special target .INTERMEDIATE. This takes effect even if the file is mentioned explicitly in some other way.

You can prevent automatic deletion of an intermediate file by marking it as a secondary file. To do this, list it as a prerequisite of the special target .SECONDARY. When a file is secondary, make will not create the file merely because it does not already exist, but make does not automatically delete the file. Marking a file as secondary also marks it as intermediate.

You can list the target pattern of an implicit rule (such as `%.o') as a prerequisite of the special target .PRECIOUS to preserve intermediate files made by implicit rules whose target patterns match that file's name; see section Interrupting or Killing make.

A chain can involve more than two implicit rules. For example, it is possible to make a file `foo' from `RCS/foo.y,v' by running RCS, Yacc and cc. Then both `foo.y' and `foo.c' are intermediate files that are deleted at the end.

No single implicit rule can appear more than once in a chain. This means that make will not even consider such a ridiculous thing as making `foo' from `foo.o.o' by running the linker twice. This constraint has the added benefit of preventing any infinite loop in the search for an implicit rule chain.

There are some special implicit rules to optimize certain cases that would otherwise be handled by rule chains. For example, making `foo' from `foo.c' could be handled by compiling and linking with separate chained rules, using `foo.o' as an intermediate file. But what actually happens is that a special rule for this case does the compilation and linking with a single cc command. The optimized rule is used in preference to the step-by-step chain because it comes earlier in the ordering of rules.

Defining and Redefining Pattern Rules

You define an implicit rule by writing a pattern rule. A pattern rule looks like an ordinary rule, except that its target contains the character `%' (exactly one of them). The target is considered a pattern for matching file names; the `%' can match any nonempty substring, while other characters match only themselves. The prerequisites likewise use `%' to show how their names relate to the target name.

Thus, a pattern rule `%.o : %.c' says how to make any file `stem.o' from another file `stem.c'.

Note that expansion using `%' in pattern rules occurs after any variable or function expansions, which take place when the makefile is read. See section How to Use Variables, and section Functions for Transforming Text.

Introduction to Pattern Rules

A pattern rule contains the character `%' (exactly one of them) in the target; otherwise, it looks exactly like an ordinary rule. The target is a pattern for matching file names; the `%' matches any nonempty substring, while other characters match only themselves.

For example, `%.c' as a pattern matches any file name that ends in `.c'. `s.%.c' as a pattern matches any file name that starts with `s.', ends in `.c' and is at least five characters long. (There must be at least one character to match the `%'.) The substring that the `%' matches is called the stem.

`%' in a prerequisite of a pattern rule stands for the same stem that was matched by the `%' in the target. In order for the pattern rule to apply, its target pattern must match the file name under consideration, and its prerequisite patterns must name files that exist or can be made. These files become prerequisites of the target.

Thus, a rule of the form

%.o : %.c ; command...

specifies how to make a file `n.o', with another file `n.c' as its prerequisite, provided that `n.c' exists or can be made.

There may also be prerequisites that do not use `%'; such a prerequisite attaches to every file made by this pattern rule. These unvarying prerequisites are useful occasionally.

A pattern rule need not have any prerequisites that contain `%', or in fact any prerequisites at all. Such a rule is effectively a general wildcard. It provides a way to make any file that matches the target pattern. See section Defining Last-Resort Default Rules.

Pattern rules may have more than one target. Unlike normal rules, this does not act as many different rules with the same prerequisites and commands. If a pattern rule has multiple targets, make knows that the rule's commands are responsible for making all of the targets. The commands are executed only once to make all the targets. When searching for a pattern rule to match a target, the target patterns of a rule other than the one that matches the target in need of a rule are incidental: make worries only about giving commands and prerequisites to the file presently in question. However, when this file's commands are run, the other targets are marked as having been updated themselves.

The order in which pattern rules appear in the makefile is important since this is the order in which they are considered. Of equally applicable rules, only the first one found is used. The rules you write take precedence over those that are built in. Note however, that a rule whose prerequisites actually exist or are mentioned always takes priority over a rule with prerequisites that must be made by chaining other implicit rules.

Pattern Rule Examples

Here are some examples of pattern rules actually predefined in make. First, the rule that compiles `.c' files into `.o' files:

%.o : %.c
        $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@

defines a rule that can make any file `x.o' from `x.c'. The command uses the automatic variables `$@' and `$<' to substitute the names of the target file and the source file in each case where the rule applies (see section Automatic Variables).

Here is a second built-in rule:

% :: RCS/%,v
        $(CO) $(COFLAGS) $<

defines a rule that can make any file `x' whatsoever from a corresponding file `x,v' in the subdirectory `RCS'. Since the target is `%', this rule will apply to any file whatever, provided the appropriate prerequisite file exists. The double colon makes the rule terminal, which means that its prerequisite may not be an intermediate file (see section Match-Anything Pattern Rules).

This pattern rule has two targets:

%.tab.c %.tab.h: %.y
        bison -d $<

This tells make that the command `bison -d x.y' will make both `x.tab.c' and `x.tab.h'. If the file `foo' depends on the files `parse.tab.o' and `scan.o' and the file `scan.o' depends on the file `parse.tab.h', when `parse.y' is changed, the command `bison -d parse.y' will be executed only once, and the prerequisites of both `parse.tab.o' and `scan.o' will be satisfied. (Presumably the file `parse.tab.o' will be recompiled from `parse.tab.c' and the file `scan.o' from `scan.c', while `foo' is linked from `parse.tab.o', `scan.o', and its other prerequisites, and it will execute happily ever after.)

Automatic Variables

Suppose you are writing a pattern rule to compile a `.c' file into a `.o' file: how do you write the `cc' command so that it operates on the right source file name? You cannot write the name in the command, because the name is different each time the implicit rule is applied.

What you do is use a special feature of make, the automatic variables. These variables have values computed afresh for each rule that is executed, based on the target and prerequisites of the rule. In this example, you would use `$@' for the object file name and `$<' for the source file name.

Here is a table of automatic variables:

$@
The file name of the target of the rule. If the target is an archive member, then `$@' is the name of the archive file. In a pattern rule that has multiple targets (see section Introduction to Pattern Rules), `$@' is the name of whichever target caused the rule's commands to be run.
$%
The target member name, when the target is an archive member. See section Using make to Update Archive Files. For example, if the target is `foo.a(bar.o)' then `$%' is `bar.o' and `$@' is `foo.a'. `$%' is empty when the target is not an archive member.
$<
The name of the first prerequisite. If the target got its commands from an implicit rule, this will be the first prerequisite added by the implicit rule (see section Using Implicit Rules).
$?
The names of all the prerequisites that are newer than the target, with spaces between them. For prerequisites which are archive members, only the member named is used (see section Using make to Update Archive Files).
$^
The names of all the prerequisites, with spaces between them. For prerequisites which are archive members, only the member named is used (see section Using make to Update Archive Files). A target has only one prerequisite on each other file it depends on, no matter how many times each file is listed as a prerequisite. So if you list a prerequisite more than once for a target, the value of $^ contains just one copy of the name.
$+
This is like `$^', but prerequisites listed more than once are duplicated in the order they were listed in the makefile. This is primarily useful for use in linking commands where it is meaningful to repeat library file names in a particular order.
$*
The stem with which an implicit rule matches (see section How Patterns Match). If the target is `dir/a.foo.b' and the target pattern is `a.%.b' then the stem is `dir/foo'. The stem is useful for constructing names of related files. In a static pattern rule, the stem is part of the file name that matched the `%' in the target pattern. In an explicit rule, there is no stem; so `$*' cannot be determined in that way. Instead, if the target name ends with a recognized suffix (see section Old-Fashioned Suffix Rules), `$*' is set to the target name minus the suffix. For example, if the target name is `foo.c', then `$*' is set to `foo', since `.c' is a suffix. GNU make does this bizarre thing only for compatibility with other implementations of make. You should generally avoid using `$*' except in implicit rules or static pattern rules. If the target name in an explicit rule does not end with a recognized suffix, `$*' is set to the empty string for that rule.

`$?' is useful even in explicit rules when you wish to operate on only the prerequisites that have changed. For example, suppose that an archive named `lib' is supposed to contain copies of several object files. This rule copies just the changed object files into the archive:

lib: foo.o bar.o lose.o win.o
        ar r lib $?

Of the variables listed above, four have values that are single file names, and three have values that are lists of file names. These seven have variants that get just the file's directory name or just the file name within the directory. The variant variables' names are formed by appending `D' or `F', respectively. These variants are semi-obsolete in GNU make since the functions dir and notdir can be used to get a similar effect (see section Functions for File Names). Note, however, that the `F' variants all omit the trailing slash which always appears in the output of the dir function. Here is a table of the variants:

`$(@D)'
The directory part of the file name of the target, with the trailing slash removed. If the value of `$@' is `dir/foo.o' then `$(@D)' is `dir'. This value is `.' if `$@' does not contain a slash.
`$(@F)'
The file-within-directory part of the file name of the target. If the value of `$@' is `dir/foo.o' then `$(@F)' is `foo.o'. `$(@F)' is equivalent to `$(notdir $@)'.
`$(*D)'
`$(*F)'
The directory part and the file-within-directory part of the stem; `dir' and `foo' in this example.
`$(%D)'
`$(%F)'
The directory part and the file-within-directory part of the target archive member name. This makes sense only for archive member targets of the form `archive(member)' and is useful only when member may contain a directory name. (See section Archive Members as Targets.)
`$(<D)'
`$(<F)'
The directory part and the file-within-directory part of the first prerequisite.
`$(^D)'
`$(^F)'
Lists of the directory parts and the file-within-directory parts of all prerequisites.
`$(?D)'
`$(?F)'
Lists of the directory parts and the file-within-directory parts of all prerequisites that are newer than the target.

Note that we use a special stylistic convention when we talk about these automatic variables; we write "the value of `$<'", rather than "the variable <" as we would write for ordinary variables such as objects and CFLAGS. We think this convention looks more natural in this special case. Please do not assume it has a deep significance; `$<' refers to the variable named < just as `$(CFLAGS)' refers to the variable named CFLAGS. You could just as well use `$(<)' in place of `$<'.

How Patterns Match

A target pattern is composed of a `%' between a prefix and a suffix, either or both of which may be empty. The pattern matches a file name only if the file name starts with the prefix and ends with the suffix, without overlap. The text between the prefix and the suffix is called the stem. Thus, when the pattern `%.o' matches the file name `test.o', the stem is `test'. The pattern rule prerequisites are turned into actual file names by substituting the stem for the character `%'. Thus, if in the same example one of the prerequisites is written as `%.c', it expands to `test.c'.

When the target pattern does not contain a slash (and it usually does not), directory names in the file names are removed from the file name before it is compared with the target prefix and suffix. After the comparison of the file name to the target pattern, the directory names, along with the slash that ends them, are added on to the prerequisite file names generated from the pattern rule's prerequisite patterns and the file name. The directories are ignored only for the purpose of finding an implicit rule to use, not in the application of that rule. Thus, `e%t' matches the file name `src/eat', with `src/a' as the stem. When prerequisites are turned into file names, the directories from the stem are added at the front, while the rest of the stem is substituted for the `%'. The stem `src/a' with a prerequisite pattern `c%r' gives the file name `src/car'.

Match-Anything Pattern Rules

When a pattern rule's target is just `%', it matches any file name whatever. We call these rules match-anything rules. They are very useful, but it can take a lot of time for make to think about them, because it must consider every such rule for each file name listed either as a target or as a prerequisite.

Suppose the makefile mentions `foo.c'. For this target, make would have to consider making it by linking an object file `foo.c.o', or by C compilation-and-linking in one step from `foo.c.c', or by Pascal compilation-and-linking from `foo.c.p', and many other possibilities.

We know these possibilities are ridiculous since `foo.c' is a C source file, not an executable. If make did consider these possibilities, it would ultimately reject them, because files such as `foo.c.o' and `foo.c.p' would not exist. But these possibilities are so numerous that make would run very slowly if it had to consider them.

To gain speed, we have put various constraints on the way make considers match-anything rules. There are two different constraints that can be applied, and each time you define a match-anything rule you must choose one or the other for that rule.

One choice is to mark the match-anything rule as terminal by defining it with a double colon. When a rule is terminal, it does not apply unless its prerequisites actually exist. Prerequisites that could be made with other implicit rules are not good enough. In other words, no further chaining is allowed beyond a terminal rule.

For example, the built-in implicit rules for extracting sources from RCS and SCCS files are terminal; as a result, if the file `foo.c,v' does not exist, make will not even consider trying to make it as an intermediate file from `foo.c,v.o' or from `RCS/SCCS/s.foo.c,v'. RCS and SCCS files are generally ultimate source files, which should not be remade from any other files; therefore, make can save time by not looking for ways to remake them.

If you do not mark the match-anything rule as terminal, then it is nonterminal. A nonterminal match-anything rule cannot apply to a file name that indicates a specific type of data. A file name indicates a specific type of data if some non-match-anything implicit rule target matches it.

For example, the file name `foo.c' matches the target for the pattern rule `%.c : %.y' (the rule to run Yacc). Regardless of whether this rule is actually applicable (which happens only if there is a file `foo.y'), the fact that its target matches is enough to prevent consideration of any nonterminal match-anything rules for the file `foo.c'. Thus, make will not even consider trying to make `foo.c' as an executable file from `foo.c.o', `foo.c.c', `foo.c.p', etc.

The motivation for this constraint is that nonterminal match-anything rules are used for making files containing specific types of data (such as executable files) and a file name with a recognized suffix indicates some other specific type of data (such as a C source file).

Special built-in dummy pattern rules are provided solely to recognize certain file names so that nonterminal match-anything rules will not be considered. These dummy rules have no prerequisites and no commands, and they are ignored for all other purposes. For example, the built-in implicit rule

%.p :

exists to make sure that Pascal source files such as `foo.p' match a specific target pattern and thereby prevent time from being wasted looking for `foo.p.o' or `foo.p.c'.

Dummy pattern rules such as the one for `%.p' are made for every suffix listed as valid for use in suffix rules (see section Old-Fashioned Suffix Rules).

Canceling Implicit Rules

You can override a built-in implicit rule (or one you have defined yourself) by defining a new pattern rule with the same target and prerequisites, but different commands. When the new rule is defined, the built-in one is replaced. The new rule's position in the sequence of implicit rules is determined by where you write the new rule.

You can cancel a built-in implicit rule by defining a pattern rule with the same target and prerequisites, but no commands. For example, the following would cancel the rule that runs the assembler:

%.o : %.s

Defining Last-Resort Default Rules

You can define a last-resort implicit rule by writing a terminal match-anything pattern rule with no prerequisites (see section Match-Anything Pattern Rules). This is just like any other pattern rule; the only thing special about it is that it will match any target. So such a rule's commands are used for all targets and prerequisites that have no commands of their own and for which no other implicit rule applies.

For example, when testing a makefile, you might not care if the source files contain real data, only that they exist. Then you might do this:

%::
        touch $@

to cause all the source files needed (as prerequisites) to be created automatically.

You can instead define commands to be used for targets for which there are no rules at all, even ones which don't specify commands. You do this by writing a rule for the target .DEFAULT. Such a rule's commands are used for all prerequisites which do not appear as targets in any explicit rule, and for which no implicit rule applies. Naturally, there is no .DEFAULT rule unless you write one.

If you use .DEFAULT with no commands or prerequisites:

.DEFAULT:

the commands previously stored for .DEFAULT are cleared. Then make acts as if you had never defined .DEFAULT at all.

If you do not want a target to get the commands from a match-anything pattern rule or .DEFAULT, but you also do not want any commands to be run for the target, you can give it empty commands (see section Using Empty Commands).

You can use a last-resort rule to override part of another makefile. See section Overriding Part of Another Makefile.

Old-Fashioned Suffix Rules

Suffix rules are the old-fashioned way of defining implicit rules for make. Suffix rules are obsolete because pattern rules are more general and clearer. They are supported in GNU make for compatibility with old makefiles. They come in two kinds: double-suffix and single-suffix.

A double-suffix rule is defined by a pair of suffixes: the target suffix and the source suffix. It matches any file whose name ends with the target suffix. The corresponding implicit prerequisite is made by replacing the target suffix with the source suffix in the file name. A two-suffix rule whose target and source suffixes are `.o' and `.c' is equivalent to the pattern rule `%.o : %.c'.

A single-suffix rule is defined by a single suffix, which is the source suffix. It matches any file name, and the corresponding implicit prerequisite name is made by appending the source suffix. A single-suffix rule whose source suffix is `.c' is equivalent to the pattern rule `% : %.c'.

Suffix rule definitions are recognized by comparing each rule's target against a defined list of known suffixes. When make sees a rule whose target is a known suffix, this rule is considered a single-suffix rule. When make sees a rule whose target is two known suffixes concatenated, this rule is taken as a double-suffix rule.

For example, `.c' and `.o' are both on the default list of known suffixes. Therefore, if you define a rule whose target is `.c.o', make takes it to be a double-suffix rule with source suffix `.c' and target suffix `.o'. Here is the old-fashioned way to define the rule for compiling a C source file:

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

Suffix rules cannot have any prerequisites of their own. If they have any, they are treated as normal files with funny names, not as suffix rules. Thus, the rule:

.c.o: foo.h
        $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<

tells how to make the file `.c.o' from the prerequisite file `foo.h', and is not at all like the pattern rule:

%.o: %.c foo.h
        $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<

which tells how to make `.o' files from `.c' files, and makes all `.o' files using this pattern rule also depend on `foo.h'.

Suffix rules with no commands are also meaningless. They do not remove previous rules as do pattern rules with no commands (see section Canceling Implicit Rules). They simply enter the suffix or pair of suffixes concatenated as a target in the data base.

The known suffixes are simply the names of the prerequisites of the special target .SUFFIXES. You can add your own suffixes by writing a rule for .SUFFIXES that adds more prerequisites, as in:

.SUFFIXES: .hack .win

which adds `.hack' and `.win' to the end of the list of suffixes.

If you wish to eliminate the default known suffixes instead of just adding to them, write a rule for .SUFFIXES with no prerequisites. By special dispensation, this eliminates all existing prerequisites of .SUFFIXES. You can then write another rule to add the suffixes you want. For example,

.SUFFIXES:            # Delete the default suffixes
.SUFFIXES: .c .o .h   # Define our suffix list

The `-r' or `--no-builtin-rules' flag causes the default list of suffixes to be empty.

The variable SUFFIXES is defined to the default list of suffixes before make reads any makefiles. You can change the list of suffixes with a rule for the special target .SUFFIXES, but that does not alter this variable.

Implicit Rule Search Algorithm

Here is the procedure make uses for searching for an implicit rule for a target t. This procedure is followed for each double-colon rule with no commands, for each target of ordinary rules none of which have commands, and for each prerequisite that is not the target of any rule. It is also followed recursively for prerequisites that come from implicit rules, in the search for a chain of rules.

Suffix rules are not mentioned in this algorithm because suffix rules are converted to equivalent pattern rules once the makefiles have been read in.

For an archive member target of the form `archive(member)', the following algorithm is run twice, first using the entire target name t, and second using `(member)' as the target t if the first run found no rule.

  1. Split t into a directory part, called d, and the rest, called n. For example, if t is `src/foo.o', then d is `src/' and n is `foo.o'.
  2. Make a list of all the pattern rules one of whose targets matches t or n. If the target pattern contains a slash, it is matched against t; otherwise, against n.
  3. If any rule in that list is not a match-anything rule, then remove all nonterminal match-anything rules from the list.
  4. Remove from the list all rules with no commands.
  5. For each pattern rule in the list:
    1. Find the stem s, which is the nonempty part of t or n matched by the `%' in the target pattern.
    2. Compute the prerequisite names by substituting s for `%'; if the target pattern does not contain a slash, append d to the front of each prerequisite name.
    3. Test whether all the prerequisites exist or ought to exist. (If a file name is mentioned in the makefile as a target or as an explicit prerequisite, then we say it ought to exist.) If all prerequisites exist or ought to exist, or there are no prerequisites, then this rule applies.
  6. If no pattern rule has been found so far, try harder. For each pattern rule in the list:
    1. If the rule is terminal, ignore it and go on to the next rule.
    2. Compute the prerequisite names as before.
    3. Test whether all the prerequisites exist or ought to exist.
    4. For each prerequisite that does not exist, follow this algorithm recursively to see if the prerequisite can be made by an implicit rule.
    5. If all prerequisites exist, ought to exist, or can be made by implicit rules, then this rule applies.
  7. If no implicit rule applies, the rule for .DEFAULT, if any, applies. In that case, give t the same commands that .DEFAULT has. Otherwise, there are no commands for t.

Once a rule that applies has been found, for each target pattern of the rule other than the one that matched t or n, the `%' in the pattern is replaced with s and the resultant file name is stored until the commands to remake the target file t are executed. After these commands are executed, each of these stored file names are entered into the data base and marked as having been updated and having the same update status as the file t.

When the commands of a pattern rule are executed for t, the automatic variables are set corresponding to the target and prerequisites. See section Automatic Variables.

Using make to Update Archive Files

Archive files are files containing named subfiles called members; they are maintained with the program ar and their main use is as subroutine libraries for linking.

Archive Members as Targets

An individual member of an archive file can be used as a target or prerequisite in make. You specify the member named member in archive file archive as follows:

archive(member)

This construct is available only in targets and prerequisites, not in commands! Most programs that you might use in commands do not support this syntax and cannot act directly on archive members. Only ar and other programs specifically designed to operate on archives can do so. Therefore, valid commands to update an archive member target probably must use ar. For example, this rule says to create a member `hack.o' in archive `foolib' by copying the file `hack.o':

foolib(hack.o) : hack.o
        ar cr foolib hack.o

In fact, nearly all archive member targets are updated in just this way and there is an implicit rule to do it for you. Note: The `c' flag to ar is required if the archive file does not already exist.

To specify several members in the same archive, you can write all the member names together between the parentheses. For example:

foolib(hack.o kludge.o)

is equivalent to:

foolib(hack.o) foolib(kludge.o)

You can also use shell-style wildcards in an archive member reference. See section Using Wildcard Characters in File Names. For example, `foolib(*.o)' expands to all existing members of the `foolib' archive whose names end in `.o'; perhaps `foolib(hack.o) foolib(kludge.o)'.

Implicit Rule for Archive Member Targets

Recall that a target that looks like `a(m)' stands for the member named m in the archive file a.

When make looks for an implicit rule for such a target, as a special feature it considers implicit rules that match `(m)', as well as those that match the actual target `a(m)'.

This causes one special rule whose target is `(%)' to match. This rule updates the target `a(m)' by copying the file m into the archive. For example, it will update the archive member target `foo.a(bar.o)' by copying the file `bar.o' into the archive `foo.a' as a member named `bar.o'.

When this rule is chained with others, the result is very powerful. Thus, `make "foo.a(bar.o)"' (the quotes are needed to protect the `(' and `)' from being interpreted specially by the shell) in the presence of a file `bar.c' is enough to cause the following commands to be run, even without a makefile:

cc -c bar.c -o bar.o
ar r foo.a bar.o
rm -f bar.o

Here make has envisioned the file `bar.o' as an intermediate file. See section Chains of Implicit Rules.

Implicit rules such as this one are written using the automatic variable `$%'. See section Automatic Variables.

An archive member name in an archive cannot contain a directory name, but it may be useful in a makefile to pretend that it does. If you write an archive member target `foo.a(dir/file.o)', make will perform automatic updating with this command:

ar r foo.a dir/file.o

which has the effect of copying the file `dir/file.o' into a member named `file.o'. In connection with such usage, the automatic variables %D and %F may be useful.

Updating Archive Symbol Directories

An archive file that is used as a library usually contains a special member named `__.SYMDEF' that contains a directory of the external symbol names defined by all the other members. After you update any other members, you need to update `__.SYMDEF' so that it will summarize the other members properly. This is done by running the ranlib program:

ranlib archivefile

Normally you would put this command in the rule for the archive file, and make all the members of the archive file prerequisites of that rule. For example,

libfoo.a: libfoo.a(x.o) libfoo.a(y.o) ...
        ranlib libfoo.a

The effect of this is to update archive members `x.o', `y.o', etc., and then update the symbol directory member `__.SYMDEF' by running ranlib. The rules for updating the members are not shown here; most likely you can omit them and use the implicit rule which copies files into the archive, as described in the preceding section.

This is not necessary when using the GNU ar program, which updates the `__.SYMDEF' member automatically.

Dangers When Using Archives

It is important to be careful when using parallel execution (the -j switch; see section Parallel Execution) and archives. If multiple ar commands run at the same time on the same archive file, they will not know about each other and can corrupt the file.

Possibly a future version of make will provide a mechanism to circumvent this problem by serializing all commands that operate on the same archive file. But for the time being, you must either write your makefiles to avoid this problem in some other way, or not use -j.

Suffix Rules for Archive Files

You can write a special kind of suffix rule for dealing with archive files. See section Old-Fashioned Suffix Rules, for a full explanation of suffix rules. Archive suffix rules are obsolete in GNU make, because pattern rules for archives are a more general mechanism (see section Implicit Rule for Archive Member Targets). But they are retained for compatibility with other makes.

To write a suffix rule for archives, you simply write a suffix rule using the target suffix `.a' (the usual suffix for archive files). For example, here is the old-fashioned suffix rule to update a library archive from C source files:

.c.a:
        $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
        $(AR) r $@ $*.o
        $(RM) $*.o

This works just as if you had written the pattern rule:

(%.o): %.c
        $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
        $(AR) r $@ $*.o
        $(RM) $*.o

In fact, this is just what make does when it sees a suffix rule with `.a' as the target suffix. Any double-suffix rule `.x.a' is converted to a pattern rule with the target pattern `(%.o)' and a prerequisite pattern of `%.x'.

Since you might want to use `.a' as the suffix for some other kind of file, make also converts archive suffix rules to pattern rules in the normal way (see section Old-Fashioned Suffix Rules). Thus a double-suffix rule `.x.a' produces two pattern rules: `(%.o): %.x' and `%.a: %.x'.

Features of GNU make

Here is a summary of the features of GNU make, for comparison with and credit to other versions of make. We consider the features of make in 4.2 BSD systems as a baseline. If you are concerned with writing portable makefiles, you should not use the features of make listed here, nor the ones in section Incompatibilities and Missing Features.

Many features come from the version of make in System V.

  • The VPATH variable and its special meaning. See section Searching Directories for Prerequisites. This feature exists in System V make, but is undocumented. It is documented in 4.3 BSD make (which says it mimics System V's VPATH feature).
  • Included makefiles. See section Including Other Makefiles. Allowing multiple files to be included with a single directive is a GNU extension.
  • Variables are read from and communicated via the environment. See section Variables from the Environment.
  • Options passed through the variable MAKEFLAGS to recursive invocations of make. See section Communicating Options to a Sub-make.
  • The automatic variable $% is set to the member name in an archive reference. See section Automatic Variables.
  • The automatic variables $@, $*, $<, $%, and $? have corresponding forms like $(@F) and $(@D). We have generalized this to $^ as an obvious extension. See section Automatic Variables.
  • Substitution variable references. See section Basics of Variable References.
  • The command-line options `-b' and `-m', accepted and ignored. In System V make, these options actually do something.
  • Execution of recursive commands to run make via the variable MAKE even if `-n', `-q' or `-t' is specified. See section Recursive Use of make.
  • Support for suffix `.a' in suffix rules. See section Suffix Rules for Archive Files. This feature is obsolete in GNU make, because the general feature of rule chaining (see section Chains of Implicit Rules) allows one pattern rule for installing members in an archive (see section Implicit Rule for Archive Member Targets) to be sufficient.
  • The arrangement of lines and backslash-newline combinations in commands is retained when the commands are printed, so they appear as they do in the makefile, except for the stripping of initial whitespace.

The following features were inspired by various other versions of make. In some cases it is unclear exactly which versions inspired which others.

  • Pattern rules using `%'. This has been implemented in several versions of make. We're not sure who invented it first, but it's been spread around a bit. See section Defining and Redefining Pattern Rules.
  • Rule chaining and implicit intermediate files. This was implemented by Stu Feldman in his version of make for AT&T Eighth Edition Research Unix, and later by Andrew Hume of AT&T Bell Labs in his mk program (where he terms it "transitive closure"). We do not really know if we got this from either of them or thought it up ourselves at the same time. See section Chains of Implicit Rules.
  • The automatic variable $^ containing a list of all prerequisites of the current target. We did not invent this, but we have no idea who did. See section Automatic Variables. The automatic variable $+ is a simple extension of $^.
  • The "what if" flag (`-W' in GNU make) was (as far as we know) invented by Andrew Hume in mk. See section Instead of Executing the Commands.
  • The concept of doing several things at once (parallelism) exists in many incarnations of make and similar programs, though not in the System V or BSD implementations. See section Command Execution.
  • Modified variable references using pattern substitution come from SunOS 4. See section Basics of Variable References. This functionality was provided in GNU make by the patsubst function before the alternate syntax was implemented for compatibility with SunOS 4. It is not altogether clear who inspired whom, since GNU make had patsubst before SunOS 4 was released.
  • The special significance of `+' characters preceding command lines (see section Instead of Executing the Commands) is mandated by IEEE Standard 1003.2-1992 (POSIX.2).
  • The `+=' syntax to append to the value of a variable comes from SunOS 4 make. See section Appending More Text to Variables.
  • The syntax `archive(mem1 mem2...)' to list multiple members in a single archive file comes from SunOS 4 make. See section Archive Members as Targets.
  • The -include directive to include makefiles with no error for a nonexistent file comes from SunOS 4 make. (But note that SunOS 4 make does not allow multiple makefiles to be specified in one -include directive.) The same feature appears with the name sinclude in SGI make and perhaps others.

The remaining features are inventions new in GNU make:

  • Use the `-v' or `--version' option to print version and copyright information.
  • Use the `-h' or `--help' option to summarize the options to make.
  • Simply-expanded variables. See section The Two Flavors of Variables.
  • Pass command-line variable assignments automatically through the variable MAKE to recursive make invocations. See section Recursive Use of make.
  • Use the `-C' or `--directory' command option to change directory. See section Summary of Options.
  • Make verbatim variable definitions with define. See section Defining Variables Verbatim.
  • Declare phony targets with the special target .PHONY. Andrew Hume of AT&T Bell Labs implemented a similar feature with a different syntax in his mk program. This seems to be a case of parallel discovery. See section Phony Targets.
  • Manipulate text by calling functions. See section Functions for Transforming Text.
  • Use the `-o' or `--old-file' option to pretend a file's modification-time is old. See section Avoiding Recompilation of Some Files.
  • Conditional execution. This feature has been implemented numerous times in various versions of make; it seems a natural extension derived from the features of the C preprocessor and similar macro languages and is not a revolutionary concept. See section Conditional Parts of Makefiles.
  • Specify a search path for included makefiles. See section Including Other Makefiles.
  • Specify extra makefiles to read with an environment variable. See section The Variable MAKEFILES.
  • Strip leading sequences of `./' from file names, so that `./file' and `file' are considered to be the same file.
  • Use a special search method for library prerequisites written in the form `-lname'. See section Directory Search for Link Libraries.
  • Allow suffixes for suffix rules (see section Old-Fashioned Suffix Rules) to contain any characters. In other versions of make, they must begin with `.' and not contain any `/' characters.
  • Keep track of the current level of make recursion using the variable MAKELEVEL. See section Recursive Use of make.
  • Provide any goals given on the command line in the variable MAKECMDGOALS. See section Arguments to Specify the Goals.
  • Specify static pattern rules. See section Static Pattern Rules.
  • Provide selective vpath search. See section Searching Directories for Prerequisites.
  • Provide computed variable references. See section Basics of Variable References.
  • Update makefiles. See section How Makefiles Are Remade. System V make has a very, very limited form of this functionality in that it will check out SCCS files for makefiles.
  • Various new built-in implicit rules. See section Catalogue of Implicit Rules.
  • The built-in variable `MAKE_VERSION' gives the version number of make.

Incompatibilities and Missing Features

The make programs in various other systems support a few features that are not implemented in GNU make. The POSIX.2 standard (IEEE Standard 1003.2-1992) which specifies make does not require any of these features.

  • A target of the form `file((entry))' stands for a member of archive file file. The member is chosen, not by name, but by being an object file which defines the linker symbol entry. This feature was not put into GNU make because of the nonmodularity of putting knowledge into make of the internal format of archive file symbol tables. See section Updating Archive Symbol Directories.
  • Suffixes (used in suffix rules) that end with the character `~' have a special meaning to System V make; they refer to the SCCS file that corresponds to the file one would get without the `~'. For example, the suffix rule `.c~.o' would make the file `n.o' from the SCCS file `s.n.c'. For complete coverage, a whole series of such suffix rules is required. See section Old-Fashioned Suffix Rules. In GNU make, this entire series of cases is handled by two pattern rules for extraction from SCCS, in combination with the general feature of rule chaining. See section Chains of Implicit Rules.
  • In System V make, the string `$$@' has the strange meaning that, in the prerequisites of a rule with multiple targets, it stands for the particular target that is being processed. This is not defined in GNU make because `$$' should always stand for an ordinary `$'. It is possible to get portions of this functionality through the use of static pattern rules (see section Static Pattern Rules). The System V make rule:
    $(targets): $$@.o lib.a
    can be replaced with the GNU make static pattern rule:
    $(targets): %: %.o lib.a
  • In System V and 4.3 BSD make, files found by VPATH search (see section Searching Directories for Prerequisites) have their names changed inside command strings. We feel it is much cleaner to always use automatic variables and thus make this feature obsolete.
  • In some Unix makes, the automatic variable $* appearing in the prerequisites of a rule has the amazingly strange "feature" of expanding to the full name of the target of that rule. We cannot imagine what went on in the minds of Unix make developers to do this; it is utterly inconsistent with the normal definition of $*.
  • In some Unix makes, implicit rule search (see section Using Implicit Rules) is apparently done for all targets, not just those without commands. This means you can do:
    foo.o:
        cc -c foo.c
    and Unix make will intuit that `foo.o' depends on `foo.c'. We feel that such usage is broken. The prerequisite properties of make are well-defined (for GNU make, at least), and doing such a thing simply does not fit the model.
  • GNU make does not include any built-in implicit rules for compiling or preprocessing EFL programs. If we hear of anyone who is using EFL, we will gladly add them.
  • It appears that in SVR4 make, a suffix rule can be specified with no commands, and it is treated as if it had empty commands (see section Using Empty Commands). For example:
    .c.a:
    will override the built-in `.c.a' suffix rule. We feel that it is cleaner for a rule without commands to always simply add to the prerequisite list for the target. The above example can be easily rewritten to get the desired behavior in GNU make:
    .c.a: ;
  • Some versions of make invoke the shell with the `-e' flag, except under `-k' (see section Testing the Compilation of a Program). The `-e' flag tells the shell to exit as soon as any program it runs returns a nonzero status. We feel it is cleaner to write each shell command line to stand on its own and not require this special treatment.

Makefile Conventions

This chapter describes conventions for writing the Makefiles for GNU programs. Using Automake will help you write a Makefile that follows these conventions.

General Conventions for Makefiles

Every Makefile should contain this line:

SHELL = /bin/sh

to avoid trouble on systems where the SHELL variable might be inherited from the environment. (This is never a problem with GNU make.)

Different make programs have incompatible suffix lists and implicit rules, and this sometimes creates confusion or misbehavior. So it is a good idea to set the suffix list explicitly using only the suffixes you need in the particular Makefile, like this:

.SUFFIXES:
.SUFFIXES: .c .o

The first line clears out the suffix list, the second introduces all suffixes which may be subject to implicit rules in this Makefile.

Don't assume that `.' is in the path for command execution. When you need to run programs that are a part of your package during the make, please make sure that it uses `./' if the program is built as part of the make or `$(srcdir)/' if the file is an unchanging part of the source code. Without one of these prefixes, the current search path is used.

The distinction between `./' (the build directory) and `$(srcdir)/' (the source directory) is important because users can build in a separate directory using the `--srcdir' option to `configure'. A rule of the form:

foo.1 : foo.man sedscript
        sed -e sedscript foo.man > foo.1

will fail when the build directory is not the source directory, because `foo.man' and `sedscript' are in the the source directory.

When using GNU make, relying on `VPATH' to find the source file will work in the case where there is a single dependency file, since the make automatic variable `$<' will represent the source file wherever it is. (Many versions of make set `$<' only in implicit rules.) A Makefile target like

foo.o : bar.c
        $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o

should instead be written as

foo.o : bar.c
        $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@

in order to allow `VPATH' to work correctly. When the target has multiple dependencies, using an explicit `$(srcdir)' is the easiest way to make the rule work well. For example, the target above for `foo.1' is best written as:

foo.1 : foo.man sedscript
        sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@

GNU distributions usually contain some files which are not source files--for example, Info files, and the output from Autoconf, Automake, Bison or Flex. Since these files normally appear in the source directory, they should always appear in the source directory, not in the build directory. So Makefile rules to update them should put the updated files in the source directory.

However, if a file does not appear in the distribution, then the Makefile should not put it in the source directory, because building a program in ordinary circumstances should not modify the source directory in any way.

Try to make the build and installation targets, at least (and all their subtargets) work correctly with a parallel make.

Utilities in Makefiles

Write the Makefile commands (and any shell scripts, such as configure) to run in sh, not in csh. Don't use any special features of ksh or bash.

The configure script and the Makefile rules for building and installation should not use any utilities directly except these:

cat cmp cp diff echo egrep expr false grep install-info
ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true

The compression program gzip can be used in the dist rule.

Stick to the generally supported options for these programs. For example, don't use `mkdir -p', convenient as it may be, because most systems don't support it.

It is a good idea to avoid creating symbolic links in makefiles, since a few systems don't support them.

The Makefile rules for building and installation can also use compilers and related programs, but should do so via make variables so that the user can substitute alternatives. Here are some of the programs we mean:

ar bison cc flex install ld ldconfig lex
make makeinfo ranlib texi2dvi yacc

Use the following make variables to run those programs:

$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)

When you use ranlib or ldconfig, you should make sure nothing bad happens if the system does not have the program in question. Arrange to ignore an error from that command, and print a message before the command to tell the user that failure of this command does not mean a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)

If you use symbolic links, you should implement a fallback for systems that don't have symbolic links.

Additional utilities that can be used via Make variables are:

chgrp chmod chown mknod

It is ok to use other utilities in Makefile portions (or scripts) intended only for particular systems where you know those utilities exist.

Variables for Specifying Commands

Makefiles should provide variables for overriding certain commands, options, and so on.

In particular, you should run most utility programs via variables. Thus, if you use Bison, have a variable named BISON whose default value is set with `BISON = bison', and refer to it with $(BISON) whenever you need to use Bison.

File management utilities such as ln, rm, mv, and so on, need not be referred to through variables in this way, since users don't need to replace them with other programs.

Each program-name variable should come with an options variable that is used to supply options to the program. Append `FLAGS' to the program-name variable name to get the options variable name--for example, BISONFLAGS. (The names CFLAGS for the C compiler, YFLAGS for yacc, and LFLAGS for lex, are exceptions to this rule, but we keep them because they are standard.) Use CPPFLAGS in any compilation command that runs the preprocessor, and use LDFLAGS in any compilation command that does linking as well as in any direct use of ld.

If there are C compiler options that must be used for proper compilation of certain files, do not include them in CFLAGS. Users expect to be able to specify CFLAGS freely themselves. Instead, arrange to pass the necessary options to the C compiler independently of CFLAGS, by writing them explicitly in the compilation commands or by defining an implicit rule, like this:

CFLAGS = -g
ALL_CFLAGS = -I. $(CFLAGS)
.c.o:
        $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<

Do include the `-g' option in CFLAGS, because that is not required for proper compilation. You can consider it a default that is only recommended. If the package is set up so that it is compiled with GCC by default, then you might as well include `-O' in the default value of CFLAGS as well.

Put CFLAGS last in the compilation command, after other variables containing compiler options, so the user can use CFLAGS to override the others.

CFLAGS should be used in every invocation of the C compiler, both those which do compilation and those which do linking.

Every Makefile should define the variable INSTALL, which is the basic command for installing a file into the system.

Every Makefile should also define the variables INSTALL_PROGRAM and INSTALL_DATA. (The default for each of these should be $(INSTALL).) Then it should use those variables as the commands for actual installation, for executables and nonexecutables respectively. Use these variables as follows:

$(INSTALL_PROGRAM) foo $(bindir)/foo
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a

Optionally, you may prepend the value of DESTDIR to the target filename. Doing this allows the installer to create a snapshot of the installation to be copied onto the real target filesystem later. Do not set the value of DESTDIR in your Makefile, and do not include it in any installed files. With support for DESTDIR, the above examples become:

$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a

Always use a file name, not a directory name, as the second argument of the installation commands. Use a separate command for each file to be installed.

Variables for Installation Directories

Installation directories should always be named by variables, so it is easy to install in a nonstandard place. The standard names for these variables are described below. They are based on a standard filesystem layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and other modern operating systems.

These two variables set the root for the installation. All the other installation directories should be subdirectories of one of these two, and nothing should be directly installed into these two directories.

`prefix'
A prefix used in constructing the default values of the variables listed below. The default value of prefix should be `/usr/local'. When building the complete GNU system, the prefix will be empty and `/usr' will be a symbolic link to `/'. (If you are using Autoconf, write it as `@prefix@'.) Running `make install' with a different value of prefix from the one used to build the program should not recompile the program.
`exec_prefix'
A prefix used in constructing the default values of some of the variables listed below. The default value of exec_prefix should be $(prefix). (If you are using Autoconf, write it as `@exec_prefix@'.) Generally, $(exec_prefix) is used for directories that contain machine-specific files (such as executables and subroutine libraries), while $(prefix) is used directly for other directories. Running `make install' with a different value of exec_prefix from the one used to build the program should not recompile the program.

Executable programs are installed in one of the following directories.

`bindir'
The directory for installing executable programs that users can run. This should normally be `/usr/local/bin', but write it as `$(exec_prefix)/bin'. (If you are using Autoconf, write it as `@bindir@'.)
`sbindir'
The directory for installing executable programs that can be run from the shell, but are only generally useful to system administrators. This should normally be `/usr/local/sbin', but write it as `$(exec_prefix)/sbin'. (If you are using Autoconf, write it as `@sbindir@'.)
`libexecdir'
The directory for installing executable programs to be run by other programs rather than by users. This directory should normally be `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'. (If you are using Autoconf, write it as `@libexecdir@'.)

Data files used by the program during its execution are divided into categories in two ways.

  • Some files are normally modified by programs; others are never normally modified (though users may edit some of these).
  • Some files are architecture-independent and can be shared by all machines at a site; some are architecture-dependent and can be shared only by machines of the same kind and operating system; others may never be shared between two machines.

This makes for six different possibilities. However, we want to discourage the use of architecture-dependent files, aside from object files and libraries. It is much cleaner to make other data files architecture-independent, and it is generally not hard.

Therefore, here are the variables Makefiles should use to specify directories:

`datadir'
The directory for installing read-only architecture independent data files. This should normally be `/usr/local/share', but write it as `$(prefix)/share'. (If you are using Autoconf, write it as `@datadir@'.) As a special exception, see `$(infodir)' and `$(includedir)' below.
`sysconfdir'
The directory for installing read-only data files that pertain to a single machine--that is to say, files for configuring a host. Mailer and network configuration files, `/etc/passwd', and so forth belong here. All the files in this directory should be ordinary ASCII text files. This directory should normally be `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are using Autoconf, write it as `@sysconfdir@'.) Do not install executables here in this directory (they probably belong in `$(libexecdir)' or `$(sbindir)'). Also do not install files that are modified in the normal course of their use (programs whose purpose is to change the configuration of the system excluded). Those probably belong in `$(localstatedir)'.
`sharedstatedir'
The directory for installing architecture-independent data files which the programs modify while they run. This should normally be `/usr/local/com', but write it as `$(prefix)/com'. (If you are using Autoconf, write it as `@sharedstatedir@'.)
`localstatedir'
The directory for installing data files which the programs modify while they run, and that pertain to one specific machine. Users should never need to modify files in this directory to configure the package's operation; put such configuration information in separate files that go in `$(datadir)' or `$(sysconfdir)'. `$(localstatedir)' should normally be `/usr/local/var', but write it as `$(prefix)/var'. (If you are using Autoconf, write it as `@localstatedir@'.)
`libdir'
The directory for object files and libraries of object code. Do not install executables here, they probably ought to go in `$(libexecdir)' instead. The value of libdir should normally be `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you are using Autoconf, write it as `@libdir@'.)
`infodir'
The directory for installing the Info files for this package. By default, it should be `/usr/local/info', but it should be written as `$(prefix)/info'. (If you are using Autoconf, write it as `@infodir@'.)
`lispdir'
The directory for installing any Emacs Lisp files in this package. By default, it should be `/usr/local/share/emacs/site-lisp', but it should be written as `$(prefix)/share/emacs/site-lisp'. If you are using Autoconf, write the default as `@lispdir@'. In order to make `@lispdir@' work, you need the following lines in your `configure.in' file:
lispdir='${datadir}/emacs/site-lisp'
AC_SUBST(lispdir)
`includedir'
The directory for installing header files to be included by user programs with the C `#include' preprocessor directive. This should normally be `/usr/local/include', but write it as `$(prefix)/include'. (If you are using Autoconf, write it as `@includedir@'.) Most compilers other than GCC do not look for header files in directory `/usr/local/include'. So installing the header files this way is only useful with GCC. Sometimes this is not a problem because some libraries are only really intended to work with GCC. But some libraries are intended to work with other compilers. They should install their header files in two places, one specified by includedir and one specified by oldincludedir.
`oldincludedir'
The directory for installing `#include' header files for use with compilers other than GCC. This should normally be `/usr/include'. (If you are using Autoconf, you can write it as `@oldincludedir@'.) The Makefile commands should check whether the value of oldincludedir is empty. If it is, they should not try to use it; they should cancel the second installation of the header files. A package should not replace an existing header in this directory unless the header came from the same package. Thus, if your Foo package provides a header file `foo.h', then it should install the header file in the oldincludedir directory if either (1) there is no `foo.h' there or (2) the `foo.h' that exists came from the Foo package. To tell whether `foo.h' came from the Foo package, put a magic string in the file--part of a comment--and grep for that string.

Unix-style man pages are installed in one of the following:

`mandir'
The top-level directory for installing the man pages (if any) for this package. It will normally be `/usr/local/man', but you should write it as `$(prefix)/man'. (If you are using Autoconf, write it as `@mandir@'.)
`man1dir'
The directory for installing section 1 man pages. Write it as `$(mandir)/man1'.
`man2dir'
The directory for installing section 2 man pages. Write it as `$(mandir)/man2'
`...'
Don't make the primary documentation for any GNU software be a man page. Write a manual in Texinfo instead. Man pages are just for the sake of people running GNU software on Unix, which is a secondary application only.
`manext'
The file name extension for the installed man page. This should contain a period followed by the appropriate digit; it should normally be `.1'.
`man1ext'
The file name extension for installed section 1 man pages.
`man2ext'
The file name extension for installed section 2 man pages.
`...'
Use these names instead of `manext' if the package needs to install man pages in more than one section of the manual.

And finally, you should set the following variable:

`srcdir'
The directory for the sources being compiled. The value of this variable is normally inserted by the configure shell script. (If you are using Autconf, use `srcdir = @srcdir@'.)

For example:

# Common prefix for installation directories.
# NOTE: This directory must exist when you start the install.
prefix = /usr/local
exec_prefix = $(prefix)
# Where to put the executable for the command `gcc'.
bindir = $(exec_prefix)/bin
# Where to put the directories used by the compiler.
libexecdir = $(exec_prefix)/libexec
# Where to put the Info files.
infodir = $(prefix)/info

If your program installs a large number of files into one of the standard user-specified directories, it might be useful to group them into a subdirectory particular to that program. If you do this, you should write the install rule to create these subdirectories.

Do not expect the user to include the subdirectory name in the value of any of the variables listed above. The idea of having a uniform set of variable names for installation directories is to enable the user to specify the exact same values for several different GNU packages. In order for this to be useful, all the packages must be designed so that they will work sensibly when the user does so.

Standard Targets for Users

All GNU programs should have the following targets in their Makefiles:

`all'
Compile the entire program. This should be the default target. This target need not rebuild any documentation files; Info files should normally be included in the distribution, and DVI files should be made only when explicitly asked for. By default, the Make rules should compile and link with `-g', so that executable programs have debugging symbols. Users who don't mind being helpless can strip the executables later if they wish.
`install'
Compile the program and copy the executables, libraries, and so on to the file names where they should reside for actual use. If there is a simple test to verify that a program is properly installed, this target should run that test. Do not strip executables when installing them. Devil-may-care users can use the install-strip target to do that. If possible, write the install target rule so that it does not modify anything in the directory where the program was built, provided `make all' has just been done. This is convenient for building the program under one user name and installing it under another. The commands should create all the directories in which files are to be installed, if they don't already exist. This includes the directories specified as the values of the variables prefix and exec_prefix, as well as all subdirectories that are needed. One way to do this is by means of an installdirs target as described below. Use `-' before any command for installing a man page, so that make will ignore any errors. This is in case there are systems that don't have the Unix man page documentation system installed. The way to install Info files is to copy them into `$(infodir)' with $(INSTALL_DATA) (see section Variables for Specifying Commands), and then run the install-info program if it is present. install-info is a program that edits the Info `dir' file to add or update the menu entry for the given Info file; it is part of the Texinfo package. Here is a sample rule to install an Info file:
$(DESTDIR)$(infodir)/foo.info: foo.info
        $(POST_INSTALL)
# There may be a newer info file in . than in srcdir.
        -if test -f foo.info; then d=.; \
         else d=$(srcdir); fi; \
        $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
# Run install-info only if it exists.
# Use `if' instead of just prepending `-' to the
# line so we notice real errors from install-info.
# We use `$(SHELL) -c' because some shells do not
# fail gracefully when there is an unknown command.
        if $(SHELL) -c 'install-info --version' \
           >/dev/null 2>&1; then \
          install-info --dir-file=$(DESTDIR)$(infodir)/dir \
                       $(DESTDIR)$(infodir)/foo.info; \
        else true; fi
When writing the install target, you must classify all the commands into three categories: normal ones, pre-installation commands and post-installation commands. See section Install Command Categories.
`uninstall'
Delete all the installed files--the copies that the `install' target creates. This rule should not modify the directories where compilation is done, only the directories where files are installed. The uninstallation commands are divided into three categories, just like the installation commands. See section Install Command Categories.
`install-strip'
Like install, but strip the executable files while installing them. In many cases, the definition of this target can be very simple:
install-strip:
        $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
                install
Normally we do not recommend stripping an executable unless you are sure the program has no bugs. However, it can be reasonable to install a stripped executable for actual execution while saving the unstripped executable elsewhere in case there is a bug.
`clean'
Delete all files from the current directory that are normally created by building the program. Don't delete the files that record the configuration. Also preserve files that could be made by building, but normally aren't because the distribution comes with them. Delete `.dvi' files here if they are not part of the distribution.
`distclean'
Delete all files from the current directory that are created by configuring or building the program. If you have unpacked the source and built the program without creating any other files, `make distclean' should leave only the files that were in the distribution.
`mostlyclean'
Like `clean', but may refrain from deleting a few files that people normally don't want to recompile. For example, the `mostlyclean' target for GCC does not delete `libgcc.a', because recompiling it is rarely necessary and takes a lot of time.
`maintainer-clean'
Delete almost everything from the current directory that can be reconstructed with this Makefile. This typically includes everything deleted by distclean, plus more: C source files produced by Bison, tags tables, Info files, and so on. The reason we say "almost everything" is that running the command `make maintainer-clean' should not delete `configure' even if `configure' can be remade using a rule in the Makefile. More generally, `make maintainer-clean' should not delete anything that needs to exist in order to run `configure' and then begin to build the program. This is the only exception; maintainer-clean should delete everything else that can be rebuilt. The `maintainer-clean' target is intended to be used by a maintainer of the package, not by ordinary users. You may need special tools to reconstruct some of the files that `make maintainer-clean' deletes. Since these files are normally included in the distribution, we don't take care to make them easy to reconstruct. If you find you need to unpack the full distribution again, don't blame us. To help make users aware of this, the commands for the special maintainer-clean target should start with these two:
@echo 'This command is intended for maintainers to use; it'
@echo 'deletes files that may need special tools to rebuild.'
`TAGS'
Update a tags table for this program.
`info'
Generate any Info files needed. The best way to write the rules is as follows:
info: foo.info

foo.info: foo.texi chap1.texi chap2.texi
        $(MAKEINFO) $(srcdir)/foo.texi
You must define the variable MAKEINFO in the Makefile. It should run the makeinfo program, which is part of the Texinfo distribution. Normally a GNU distribution comes with Info files, and that means the Info files are present in the source directory. Therefore, the Make rule for an info file should update it in the source directory. When users build the package, ordinarily Make will not update the Info files because they will already be up to date.
`dvi'
Generate DVI files for all Texinfo documentation. For example:
dvi: foo.dvi

foo.dvi: foo.texi chap1.texi chap2.texi
        $(TEXI2DVI) $(srcdir)/foo.texi
You must define the variable TEXI2DVI in the Makefile. It should run the program texi2dvi, which is part of the Texinfo distribution.(3) Alternatively, write just the dependencies, and allow GNU make to provide the command.
`dist'
Create a distribution tar file for this program. The tar file should be set up so that the file names in the tar file start with a subdirectory name which is the name of the package it is a distribution for. This name can include the version number. For example, the distribution tar file of GCC version 1.40 unpacks into a subdirectory named `gcc-1.40'. The easiest way to do this is to create a subdirectory appropriately named, use ln or cp to install the proper files in it, and then tar that subdirectory. Compress the tar file file with gzip. For example, the actual distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'. The dist target should explicitly depend on all non-source files that are in the distribution, to make sure they are up to date in the distribution. See section `Making Releases' in GNU Coding Standards.
`check'
Perform self-tests (if any). The user must build the program before running the tests, but need not install the program; you should write the self-tests so that they work when the program is built but not installed.

The following targets are suggested as conventional names, for programs in which they are useful.

installcheck
Perform installation tests (if any). The user must build and install the program before running the tests. You should not assume that `$(bindir)' is in the search path.
installdirs
It's useful to add a target named `installdirs' to create the directories where files are installed, and their parent directories. There is a script called `mkinstalldirs' which is convenient for this; you can find it in the Texinfo package. You can use a rule like this:
# Make sure all installation directories (e.g. $(bindir))
# actually exist by making them if necessary.
installdirs: mkinstalldirs
        $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
                                $(libdir) $(infodir) \
                                $(mandir)
This rule should not modify the directories where compilation is done. It should do nothing but create installation directories.

Install Command Categories

When writing the install target, you must classify all the commands into three categories: normal ones, pre-installation commands and post-installation commands.

Normal commands move files into their proper places, and set their modes. They may not alter any files except the ones that come entirely from the package they belong to.

Pre-installation and post-installation commands may alter other files; in particular, they can edit global configuration files or data bases.

Pre-installation commands are typically executed before the normal commands, and post-installation commands are typically run after the normal commands.

The most common use for a post-installation command is to run install-info. This cannot be done with a normal command, since it alters a file (the Info directory) which does not come entirely and solely from the package being installed. It is a post-installation command because it needs to be done after the normal command which installs the package's Info files.

Most programs don't need any pre-installation commands, but we have the feature just in case it is needed.

To classify the commands in the install rule into these three categories, insert category lines among them. A category line specifies the category for the commands that follow.

A category line consists of a tab and a reference to a special Make variable, plus an optional comment at the end. There are three variables you can use, one for each category; the variable name specifies the category. Category lines are no-ops in ordinary execution because these three Make variables are normally undefined (and you should not define them in the makefile).

Here are the three possible category lines, each with a comment that explains what it means:

        $(PRE_INSTALL)     # Pre-install commands follow.
        $(POST_INSTALL)    # Post-install commands follow.
        $(NORMAL_INSTALL)  # Normal commands follow.

If you don't use a category line at the beginning of the install rule, all the commands are classified as normal until the first category line. If you don't use any category lines, all the commands are classified as normal.

These are the category lines for uninstall:

        $(PRE_UNINSTALL)     # Pre-uninstall commands follow.
        $(POST_UNINSTALL)    # Post-uninstall commands follow.
        $(NORMAL_UNINSTALL)  # Normal commands follow.

Typically, a pre-uninstall command would be used for deleting entries from the Info directory.

If the install or uninstall target has any dependencies which act as subroutines of installation, then you should start each dependency's commands with a category line, and start the main target's commands with a category line also. This way, you can ensure that each command is placed in the right category regardless of which of the dependencies actually run.

Pre-installation and post-installation commands should not run any programs except for these:

[ basename bash cat chgrp chmod chown cmp cp dd diff echo
egrep expand expr false fgrep find getopt grep gunzip gzip
hostname install install-info kill ldconfig ln ls md5sum
mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
test touch true uname xargs yes

The reason for distinguishing the commands in this way is for the sake of making binary packages. Typically a binary package contains all the executables and other files that need to be installed, and has its own method of installing them--so it does not need to run the normal installation commands. But installing the binary package does need to execute the pre-installation and post-installation commands.

Programs to build binary packages work by extracting the pre-installation and post-installation commands. Here is one way of extracting the pre-installation commands:

make -n install -o all \
      PRE_INSTALL=pre-install \
      POST_INSTALL=post-install \
      NORMAL_INSTALL=normal-install \
  | gawk -f pre-install.awk

where the file `pre-install.awk' could contain this:

$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
on {print $0}
$0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}

The resulting file of pre-installation commands is executed as a shell script as part of installing the binary package.

Quick Reference

This appendix summarizes the directives, text manipulation functions, and special variables which GNU make understands. See section Special Built-in Target Names, section Catalogue of Implicit Rules, and section Summary of Options, for other summaries.

Here is a summary of the directives GNU make recognizes:

define variable
endef
Define a multi-line, recursively-expanded variable.
See section Defining Canned Command Sequences.
ifdef variable
ifndef variable
ifeq (a,b)
ifeq "a" "b"
ifeq 'a' 'b'
ifneq (a,b)
ifneq "a" "b"
ifneq 'a' 'b'
else
endif
Conditionally evaluate part of the makefile.
See section Conditional Parts of Makefiles.
include file
-include file
sinclude file
Include another makefile.
See section Including Other Makefiles.
override variable = value
override variable := value
override variable += value
override variable ?= value
override define variable
endef
Define a variable, overriding any previous definition, even one from the command line.
See section The override Directive.
export
Tell make to export all variables to child processes by default.
See section Communicating Variables to a Sub-make.
export variable
export variable = value
export variable := value
export variable += value
export variable ?= value
unexport variable
Tell make whether or not to export a particular variable to child processes.
See section Communicating Variables to a Sub-make.
vpath pattern path
Specify a search path for files matching a `%' pattern.
See section The vpath Directive.
vpath pattern
Remove all search paths previously specified for pattern.
vpath
Remove all search paths previously specified in any vpath directive.

Here is a summary of the text manipulation functions (see section Functions for Transforming Text):

$(subst from,to,text)
Replace from with to in text.
See section Functions for String Substitution and Analysis.
$(patsubst pattern,replacement,text)
Replace words matching pattern with replacement in text.
See section Functions for String Substitution and Analysis.
$(strip string)
Remove excess whitespace characters from string.
See section Functions for String Substitution and Analysis.
$(findstring find,text)
Locate find in text.
See section Functions for String Substitution and Analysis.
$(filter pattern...,text)
Select words in text that match one of the pattern words.
See section Functions for String Substitution and Analysis.
$(filter-out pattern...,text)
Select words in text that do not match any of the pattern words.
See section Functions for String Substitution and Analysis.
$(sort list)
Sort the words in list lexicographically, removing duplicates.
See section Functions for String Substitution and Analysis.
$(dir names...)
Extract the directory part of each file name.
See section Functions for File Names.
$(notdir names...)
Extract the non-directory part of each file name.
See section Functions for File Names.
$(suffix names...)
Extract the suffix (the last `.' and following characters) of each file name.
See section Functions for File Names.
$(basename names...)
Extract the base name (name without suffix) of each file name.
See section Functions for File Names.
$(addsuffix suffix,names...)
Append suffix to each word in names.
See section Functions for File Names.
$(addprefix prefix,names...)
Prepend prefix to each word in names.
See section Functions for File Names.
$(join list1,list2)
Join two parallel lists of words.
See section Functions for File Names.
$(word n,text)
Extract the nth word (one-origin) of text.
See section Functions for File Names.
$(words text)
Count the number of words in text.
See section Functions for File Names.
$(wordlist s,e,text)
Returns the list of words in text from s to e.
See section Functions for File Names.
$(firstword names...)
Extract the first word of names.
See section Functions for File Names.
$(wildcard pattern...)
Find file names matching a shell file name pattern (not a `%' pattern).
See section The Function wildcard.
$(error text...)
When this function is evaluated, make generates a fatal error with the message text.
See section Functions That Control Make.
$(warning text...)
When this function is evaluated, make generates a warning with the message text.
See section Functions That Control Make.
$(shell command)
Execute a shell command and return its output.
See section The shell Function.
$(origin variable)
Return a string describing how the make variable variable was defined.
See section The origin Function.
$(foreach var,words,text)
Evaluate text with var bound to each word in words, and concatenate the results.
See section The foreach Function.
$(call var,param,...)
Evaluate the variable var replacing any references to $(1), $(2) with the first, second, etc. param values.
See section The call Function.

Here is a summary of the automatic variables. See section Automatic Variables, for full information.

$@
The file name of the target.
$%
The target member name, when the target is an archive member.
$<
The name of the first prerequisite.
$?
The names of all the prerequisites that are newer than the target, with spaces between them. For prerequisites which are archive members, only the member named is used (see section Using make to Update Archive Files).
$^
$+
The names of all the prerequisites, with spaces between them. For prerequisites which are archive members, only the member named is used (see section Using make to Update Archive Files). The value of $^ omits duplicate prerequisites, while $+ retains them and preserves their order.
$*
The stem with which an implicit rule matches (see section How Patterns Match).
$(@D)
$(@F)
The directory part and the file-within-directory part of $@.
$(*D)
$(*F)
The directory part and the file-within-directory part of $*.
$(%D)
$(%F)
The directory part and the file-within-directory part of $%.
$(<D)
$(<F)
The directory part and the file-within-directory part of $<.
$(^D)
$(^F)
The directory part and the file-within-directory part of $^.
$(+D)
$(+F)
The directory part and the file-within-directory part of $+.
$(?D)
$(?F)
The directory part and the file-within-directory part of $?.

These variables are used specially by GNU make:

MAKEFILES
Makefiles to be read on every invocation of make.
See section The Variable MAKEFILES.
VPATH
Directory search path for files not found in the current directory.
See section VPATH: Search Path for All Prerequisites.
SHELL
The name of the system default command interpreter, usually `/bin/sh'. You can set SHELL in the makefile to change the shell used to run commands. See section Command Execution.
MAKESHELL
On MS-DOS only, the name of the command interpreter that is to be used by make. This value takes precedence over the value of SHELL. See section Command Execution.
MAKE
The name with which make was invoked. Using this variable in commands has special meaning. See section How the MAKE Variable Works.
MAKELEVEL
The number of levels of recursion (sub-makes).
See section Communicating Variables to a Sub-make.
MAKEFLAGS
The flags given to make. You can set this in the environment or a makefile to set flags.
See section Communicating Options to a Sub-make. It is never appropriate to use MAKEFLAGS directly on a command line: its contents may not be quoted correctly for use in the shell. Always allow recursive make's to obtain these values through the environment from its parent.
MAKECMDGOALS
The targets given to make on the command line. Setting this variable has no effect on the operation of make.
See section Arguments to Specify the Goals.
CURDIR
Set to the pathname of the current working directory (after all -C options are processed, if any). Setting this variable has no effect on the operation of make.
See section Recursive Use of make.
SUFFIXES
The default list of suffixes before make reads any makefiles.
.LIBPATTERNS
Defines the naming of the libraries make searches for, and their order.
See section Directory Search for Link Libraries.

Errors Generated by Make

Here is a list of the more common errors you might see generated by make, and some information about what they mean and how to fix them.

Sometimes make errors are not fatal, especially in the presence of a - prefix on a command script line, or the -k command line option. Errors that are fatal are prefixed with the string ***.

Error messages are all either prefixed with the name of the program (usually `make'), or, if the error is found in a makefile, the name of the file and linenumber containing the problem.

In the table below, these common prefixes are left off.

`[foo] Error NN'
`[foo] signal description'
These errors are not really make errors at all. They mean that a program that make invoked as part of a command script returned a non-0 error code (`Error NN'), which make interprets as failure, or it exited in some other abnormal fashion (with a signal of some type). See section Errors in Commands. If no *** is attached to the message, then the subprocess failed but the rule in the makefile was prefixed with the - special character, so make ignored the error.
`missing separator. Stop.'
`missing separator (did you mean TAB instead of 8 spaces?). Stop.'
This means that make could not understand much of anything about the command line it just read. GNU make looks for various kinds of separators (:, =, TAB characters, etc.) to help it decide what kind of commandline it's seeing. This means it couldn't find a valid one. One of the most common reasons for this message is that you (or perhaps your oh-so-helpful editor, as is the case with many MS-Windows editors) have attempted to indent your command scripts with spaces instead of a TAB character. In this case, make will use the second form of the error above. Remember that every line in the command script must begin with a TAB character. Eight spaces do not count. See section Rule Syntax.
`commands commence before first target. Stop.'
`missing rule before commands. Stop.'
This means the first thing in the makefile seems to be part of a command script: it begins with a TAB character and doesn't appear to be a legal make command (such as a variable assignment). Command scripts must always be associated with a target. The second form is generated if the line has a semicolon as the first non-whitespace character; make interprets this to mean you left out the "target: prerequisite" section of a rule. See section Rule Syntax.
`No rule to make target `xxx'.'
`No rule to make target `xxx', needed by `yyy'.'
This means that make decided it needed to build a target, but then couldn't find any instructions in the makefile on how to do that, either explicit or implicit (including in the default rules database). If you want that file to be built, you will need to add a rule to your makefile describing how that target can be built. Other possible sources of this problem are typos in the makefile (if that filename is wrong) or a corrupted source tree (if that file is not supposed to be built, but rather only a prerequisite).
`No targets specified and no makefile found. Stop.'
`No targets. Stop.'
The former means that you didn't provide any targets to be built on the command line, and make couldn't find any makefiles to read in. The latter means that some makefile was found, but it didn't contain any default target and none was given on the command line. GNU make has nothing to do in these situations. See section Arguments to Specify the Makefile.
`Makefile `xxx' was not found.'
`Included makefile `xxx' was not found.'
A makefile specified on the command line (first form) or included (second form) was not found.
`warning: overriding commands for target `xxx''
`warning: ignoring old commands for target `xxx''
GNU make allows commands to be specified only once per target (except for double-colon rules). If you give commands for a target which already has been defined to have commands, this warning is issued and the second set of commands will overwrite the first set. See section Multiple Rules for One Target.
`Circular xxx <- yyy dependency dropped.'
This means that make detected a loop in the dependency graph: after tracing the prerequisite yyy of target xxx, and its prerequisites, etc., one of them depended on xxx again.
`Recursive variable `xxx' references itself (eventually). Stop.'
This means you've defined a normal (recursive) make variable xxx that, when it's expanded, will refer to itself (xxx). This is not allowed; either use simply-expanded variables (:=) or use the append operator (+=). See section How to Use Variables.
`Unterminated variable reference. Stop.'
This means you forgot to provide the proper closing parenthesis or brace in your variable or function reference.
`insufficient arguments to function `xxx'. Stop.'
This means you haven't provided the requisite number of arguments for this function. See the documentation of the function for a description of its arguments. See section Functions for Transforming Text.
`missing target pattern. Stop.'
`multiple target patterns. Stop.'
`target pattern contains no `%'. Stop.'
These are generated for malformed static pattern rules. The first means there's no pattern in the target section of the rule, the second means there are multiple patterns in the target section, and the third means the target doesn't contain a pattern character (%). See section Syntax of Static Pattern Rules.
`warning: -jN forced in submake: disabling jobserver mode.'
This warning and the next are generated if make detects error conditions related to parallel processing on systems where sub-makes can communicate (see section Communicating Options to a Sub-make). This warning is generated if a recursive invocation of a make process is forced to have `-jN' in its argument list (where N is greater than one). This could happen, for example, if you set the MAKE environment variable to `make -j2'. In this case, the sub-make doesn't communicate with other make processes and will simply pretend it has two jobs of its own.
`warning: jobserver unavailable: using -j1. Add `+' to parent make rule.'
In order for make processes to communicate, the parent will pass information to the child. Since this could result in problems if the child process isn't actually a make, the parent will only do this if it thinks the child is a make. The parent uses the normal algorithms to determine this (see section How the MAKE Variable Works). If the makefile is constructed such that the parent doesn't know the child is a make process, then the child will receive only part of the information necessary. In this case, the child will generate this warning message and proceed with its build in a sequential manner.

Complex Makefile Example

Here is the makefile for the GNU tar program. This is a moderately complex makefile.

Because it is the first target, the default goal is `all'. An interesting feature of this makefile is that `testpad.h' is a source file automatically created by the testpad program, itself compiled from `testpad.c'.

If you type `make' or `make all', then make creates the `tar' executable, the `rmt' daemon that provides remote tape access, and the `tar.info' Info file.

If you type `make install', then make not only creates `tar', `rmt', and `tar.info', but also installs them.

If you type `make clean', then make removes the `.o' files, and the `tar', `rmt', `testpad', `testpad.h', and `core' files.

If you type `make distclean', then make not only removes the same files as does `make clean' but also the `TAGS', `Makefile', and `config.status' files. (Although it is not evident, this makefile (and `config.status') is generated by the user with the configure program, which is provided in the tar distribution, but is not shown here.)

If you type `make realclean', then make removes the same files as does `make distclean' and also removes the Info files generated from `tar.texinfo'.

In addition, there are targets shar and dist that create distribution kits.

# Generated automatically from Makefile.in by configure.
# Un*x Makefile for GNU tar program.
# Copyright (C) 1991 Free Software Foundation, Inc.

# This program is free software; you can redistribute
# it and/or modify it under the terms of the GNU
# General Public License ...
...
...

SHELL = /bin/sh

#### Start of system configuration section. ####

srcdir = .

# If you use gcc, you should either run the
# fixincludes script that comes with it or else use
# gcc with the -traditional option.  Otherwise ioctl
# calls will be compiled incorrectly on some systems.
CC = gcc -O
YACC = bison -y
INSTALL = /usr/local/bin/install -c
INSTALLDATA = /usr/local/bin/install -c -m 644

# Things you might add to DEFS:
# -DSTDC_HEADERS        If you have ANSI C headers and
#                       libraries.
# -DPOSIX               If you have POSIX.1 headers and
#                       libraries.
# -DBSD42               If you have sys/dir.h (unless
#                       you use -DPOSIX), sys/file.h,
#                       and st_blocks in `struct stat'.
# -DUSG                 If you have System V/ANSI C
#                       string and memory functions
#                       and headers, sys/sysmacros.h,
#                       fcntl.h, getcwd, no valloc,
#                       and ndir.h (unless
#                       you use -DDIRENT).
# -DNO_MEMORY_H         If USG or STDC_HEADERS but do not
#                       include memory.h.
# -DDIRENT              If USG and you have dirent.h
#                       instead of ndir.h.
# -DSIGTYPE=int         If your signal handlers
#                       return int, not void.
# -DNO_MTIO             If you lack sys/mtio.h
#                       (magtape ioctls).
# -DNO_REMOTE           If you do not have a remote shell
#                       or rexec.
# -DUSE_REXEC           To use rexec for remote tape
#                       operations instead of
#                       forking rsh or remsh.
# -DVPRINTF_MISSING     If you lack vprintf function
#                       (but have _doprnt).
# -DDOPRNT_MISSING      If you lack _doprnt function.
#                       Also need to define
#                       -DVPRINTF_MISSING.
# -DFTIME_MISSING       If you lack ftime system call.
# -DSTRSTR_MISSING      If you lack strstr function.
# -DVALLOC_MISSING      If you lack valloc function.
# -DMKDIR_MISSING       If you lack mkdir and
#                       rmdir system calls.
# -DRENAME_MISSING      If you lack rename system call.
# -DFTRUNCATE_MISSING   If you lack ftruncate
#                       system call.
# -DV7                  On Version 7 Unix (not
#                       tested in a long time).
# -DEMUL_OPEN3          If you lack a 3-argument version
#                       of open, and want to emulate it
#                       with system calls you do have.
# -DNO_OPEN3            If you lack the 3-argument open
#                       and want to disable the tar -k
#                       option instead of emulating open.
# -DXENIX               If you have sys/inode.h
#                       and need it 94 to be included.

DEFS =  -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \
        -DVPRINTF_MISSING -DBSD42
# Set this to rtapelib.o unless you defined NO_REMOTE,
# in which case make it empty.
RTAPELIB = rtapelib.o
LIBS =
DEF_AR_FILE = /dev/rmt8
DEFBLOCKING = 20

CDEBUG = -g
CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \
        -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \
        -DDEFBLOCKING=$(DEFBLOCKING)
LDFLAGS = -g

prefix = /usr/local
# Prefix for each installed program,
# normally empty or `g'.
binprefix =

# The directory to install tar in.
bindir = $(prefix)/bin

# The directory to install the info files in.
infodir = $(prefix)/info

#### End of system configuration section. ####

SRC1 =  tar.c create.c extract.c buffer.c \
        getoldopt.c update.c gnu.c mangle.c
SRC2 =  version.c list.c names.c diffarch.c \
        port.c wildmat.c getopt.c
SRC3 =  getopt1.c regex.c getdate.y
SRCS =  $(SRC1) $(SRC2) $(SRC3)
OBJ1 =  tar.o create.o extract.o buffer.o \
        getoldopt.o update.o gnu.o mangle.o
OBJ2 =  version.o list.o names.o diffarch.o \
        port.o wildmat.o getopt.o
OBJ3 =  getopt1.o regex.o getdate.o $(RTAPELIB)
OBJS =  $(OBJ1) $(OBJ2) $(OBJ3)
AUX =   README COPYING ChangeLog Makefile.in  \
        makefile.pc configure configure.in \
        tar.texinfo tar.info* texinfo.tex \
        tar.h port.h open3.h getopt.h regex.h \
        rmt.h rmt.c rtapelib.c alloca.c \
        msd_dir.h msd_dir.c tcexparg.c \
        level-0 level-1 backup-specs testpad.c

all:    tar rmt tar.info

tar:    $(OBJS)
        $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)

rmt:    rmt.c
        $(CC) $(CFLAGS) $(LDFLAGS) -o $@ rmt.c

tar.info: tar.texinfo
        makeinfo tar.texinfo

install: all
        $(INSTALL) tar $(bindir)/$(binprefix)tar
        -test ! -f rmt || $(INSTALL) rmt /etc/rmt
        $(INSTALLDATA) $(srcdir)/tar.info* $(infodir)

$(OBJS): tar.h port.h testpad.h
regex.o buffer.o tar.o: regex.h
# getdate.y has 8 shift/reduce conflicts.

testpad.h: testpad
        ./testpad

testpad: testpad.o
        $(CC) -o $@ testpad.o

TAGS:   $(SRCS)
        etags $(SRCS)

clean:
        rm -f *.o tar rmt testpad testpad.h core

distclean: clean
        rm -f TAGS Makefile config.status

realclean: distclean
        rm -f tar.info*

shar: $(SRCS) $(AUX)
        shar $(SRCS) $(AUX) | compress \
          > tar-`sed -e '/version_string/!d' \
                     -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
                     -e q
                     version.c`.shar.Z

dist: $(SRCS) $(AUX)
        echo tar-`sed \
             -e '/version_string/!d' \
             -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
             -e q
             version.c` > .fname
        -rm -rf `cat .fname`
        mkdir `cat .fname`
        ln $(SRCS) $(AUX) `cat .fname`
        tar chZf `cat .fname`.tar.Z `cat .fname`
        -rm -rf `cat .fname` .fname

tar.zoo: $(SRCS) $(AUX)
        -rm -rf tmp.dir
        -mkdir tmp.dir
        -rm tar.zoo
        for X in $(SRCS) $(AUX) ; do \
            echo $$X ; \
            sed 's/$$/^M/' $$X \
            > tmp.dir/$$X ; done
        cd tmp.dir ; zoo aM ../tar.zoo *
        -rm -rf tmp.dir

Index of Concepts

#

  • # (comments), in commands
  • # (comments), in makefile
  • #include

    • $

  • $, in function call
  • $, in rules
  • $, in variable name
  • $, in variable reference

    • %

  • %, in pattern rules
  • %, quoting in static pattern
  • %, quoting in patsubst
  • %, quoting in vpath
  • %, quoting with \ (backslash), %, quoting with \ (backslash), %, quoting with \ (backslash)

    • *

  • * (wildcard character)

    • +

  • +, and define
  • +=
  • +=, expansion, +=, expansion

    • ,

  • ,v (RCS file extension)

    • -

  • - (in commands)
  • -, and define
  • --assume-new, --assume-new
  • --assume-new, and recursion
  • --assume-old, --assume-old
  • --assume-old, and recursion
  • --debug
  • --directory, --directory
  • --directory, and recursion
  • --directory, and --print-directory
  • --dry-run, --dry-run, --dry-run
  • --environment-overrides
  • --file, --file, --file
  • --file, and recursion
  • --help
  • --ignore-errors, --ignore-errors
  • --include-dir, --include-dir
  • --jobs, --jobs
  • --jobs, and recursion
  • --just-print, --just-print, --just-print
  • --keep-going, --keep-going, --keep-going
  • --load-average, --load-average
  • --makefile, --makefile, --makefile
  • --max-load, --max-load
  • --new-file, --new-file
  • --new-file, and recursion
  • --no-builtin-rules
  • --no-builtin-variables
  • --no-keep-going
  • --no-print-directory, --no-print-directory
  • --old-file, --old-file
  • --old-file, and recursion
  • --print-data-base
  • --print-directory
  • --print-directory, and recursion
  • --print-directory, disabling
  • --print-directory, and --directory
  • --question, --question
  • --quiet, --quiet
  • --recon, --recon, --recon
  • --silent, --silent
  • --stop
  • --touch, --touch
  • --touch, and recursion
  • --version
  • --warn-undefined-variables
  • --what-if, --what-if
  • -b
  • -C, -C
  • -C, and recursion
  • -C, and -w
  • -d
  • -e
  • -e (shell flag)
  • -f, -f, -f
  • -f, and recursion
  • -h
  • -I, -I
  • -i, -i
  • -j, -j
  • -j, and archive update
  • -j, and recursion
  • -k, -k, -k
  • -l
  • -l (library search)
  • -l (load average)
  • -m
  • -M (to compiler)
  • -MM (to GNU compiler)
  • -n, -n, -n
  • -o, -o
  • -o, and recursion
  • -p
  • -q, -q
  • -R
  • -r
  • -S
  • -s, -s
  • -t, -t
  • -t, and recursion
  • -v
  • -W, -W
  • -w
  • -W, and recursion
  • -w, and recursion
  • -w, disabling
  • -w, and -C

    • .

  • .a (archives)
  • .C
  • .c
  • .cc
  • .ch
  • .d
  • .def
  • .dvi
  • .F
  • .f
  • .info
  • .l
  • .LIBPATTERNS, and link libraries
  • .ln
  • .mod
  • .o, .o
  • .p
  • .PRECIOUS intermediate files
  • .r
  • .S
  • .s
  • .sh
  • .sym
  • .tex
  • .texi
  • .texinfo
  • .txinfo
  • .w
  • .web
  • .y

    • :

  • :: rules (double-colon)
  • :=, :=

    • =

  • =, =
  • =, expansion

    • ?

  • ? (wildcard character)
  • ?=, ?=
  • ?=, expansion

    • @

  • @ (in commands)
  • @, and define

    • [

  • [...] (wildcard characters)

    • \

  • \ (backslash), for continuation lines
  • \ (backslash), in commands
  • \ (backslash), to quote %, \ (backslash), to quote %, \ (backslash), to quote %

    • _

  • __.SYMDEF

    • a

  • algorithm for directory search
  • all (standard target)
  • appending to variables
  • ar
  • archive
  • archive member targets
  • archive symbol directory updating
  • archive, and -j
  • archive, and parallel execution
  • archive, suffix rule for
  • Arg list too long
  • arguments of functions
  • as, as
  • assembly, rule to compile
  • automatic generation of prerequisites, automatic generation of prerequisites
  • automatic variables

    • b

  • backquotes
  • backslash (\), for continuation lines
  • backslash (\), in commands
  • backslash (\), to quote %, backslash (\), to quote %, backslash (\), to quote %
  • backslashes in pathnames and wildcard expansion
  • basename
  • binary packages
  • broken pipe
  • bugs, reporting
  • built-in special targets

    • c

  • C++, rule to compile
  • C, rule to compile
  • cc, cc
  • cd (shell command), cd (shell command)
  • chains of rules
  • check (standard target)
  • clean (standard target)
  • clean target, clean target
  • cleaning up
  • clobber (standard target)
  • co, co
  • combining rules by prerequisite
  • command line variable definitions, and recursion
  • command line variables
  • commands
  • commands, backslash (\) in
  • commands, comments in
  • commands, echoing
  • commands, empty
  • commands, errors in
  • commands, execution
  • commands, execution in parallel
  • commands, expansion
  • commands, how to write
  • commands, instead of executing
  • commands, introduction to
  • commands, quoting newlines in
  • commands, sequences of
  • comments, in commands
  • comments, in makefile
  • compatibility
  • compatibility in exporting
  • compilation, testing
  • computed variable name
  • conditional expansion
  • conditional variable assignment
  • conditionals
  • continuation lines
  • controlling make
  • conventions for makefiles
  • ctangle, ctangle
  • cweave, cweave

    • d

  • data base of make rules
  • deducing commands (implicit rules)
  • default directries for included makefiles
  • default goal, default goal
  • default makefile name
  • default rules, last-resort
  • define, expansion
  • defining variables verbatim
  • deletion of target files, deletion of target files
  • directive
  • directories, printing them
  • directories, updating archive symbol
  • directory part
  • directory search (VPATH)
  • directory search (VPATH), and implicit rules
  • directory search (VPATH), and link libraries
  • directory search (VPATH), and shell commands
  • directory search algorithm
  • directory search, traditional
  • dist (standard target)
  • distclean (standard target)
  • dollar sign ($), in function call
  • dollar sign ($), in rules
  • dollar sign ($), in variable name
  • dollar sign ($), in variable reference
  • double-colon rules
  • duplicate words, removing

    • e

  • E2BIG
  • echoing of commands
  • editor
  • Emacs (M-x compile)
  • empty commands
  • empty targets
  • environment
  • environment, and recursion
  • environment, SHELL in
  • error, stopping on
  • errors (in commands)
  • errors with wildcards
  • execution, in parallel
  • execution, instead of
  • execution, of commands
  • exit status (errors)
  • explicit rule, definition of
  • explicit rule, expansion
  • exporting variables

    • f

  • f77, f77
  • features of GNU make
  • features, missing
  • file name functions
  • file name of makefile
  • file name of makefile, how to specify
  • file name prefix, adding
  • file name suffix
  • file name suffix, adding
  • file name with wildcards
  • file name, basename of
  • file name, directory part
  • file name, nondirectory part
  • files, assuming new
  • files, assuming old
  • files, avoiding recompilation of
  • files, intermediate
  • filtering out words
  • filtering words
  • finding strings
  • flags
  • flags for compilers
  • flavors of variables
  • FORCE
  • force targets
  • Fortran, rule to compile
  • functions
  • functions, for controlling make
  • functions, for file names
  • functions, for text
  • functions, syntax of
  • functions, user defined

    • g

  • g++, g++
  • gcc
  • generating prerequisites automatically, generating prerequisites automatically
  • get, get
  • globbing (wildcards)
  • goal
  • goal, default, goal, default
  • goal, how to specify

    • h

  • home directory

    • i

  • IEEE Standard 1003.2
  • ifdef, expansion
  • ifeq, expansion
  • ifndef, expansion
  • ifneq, expansion
  • implicit rule
  • implicit rule, and directory search
  • implicit rule, and VPATH
  • implicit rule, definition of
  • implicit rule, expansion
  • implicit rule, how to use
  • implicit rule, introduction to
  • implicit rule, predefined
  • implicit rule, search algorithm
  • included makefiles, default directries
  • including (MAKEFILES variable)
  • including other makefiles
  • incompatibilities
  • Info, rule to format
  • install (standard target)
  • intermediate files
  • intermediate files, preserving
  • intermediate targets, explicit
  • interrupt

    • j

  • job slots
  • job slots, and recursion
  • jobs, limiting based on load
  • joining lists of words

    • k

  • killing (interruption)

    • l

  • last-resort default rules
  • ld
  • lex, lex
  • Lex, rule to run
  • libraries for linking, directory search
  • library archive, suffix rule for
  • limiting jobs based on load
  • link libraries, and directory search
  • link libraries, patterns matching
  • linking, predefined rule for
  • lint
  • lint, rule to run
  • list of all prerequisites
  • list of changed prerequisites
  • load average
  • loops in variable expansion
  • lpr (shell command), lpr (shell command)

    • m

  • m2c
  • macro
  • make depend
  • MAKECMDGOALS
  • makefile
  • makefile name
  • makefile name, how to specify
  • makefile rule parts
  • makefile, and MAKEFILES variable
  • makefile, conventions for
  • makefile, how make processes
  • makefile, how to write
  • makefile, including
  • makefile, overriding
  • makefile, parsing
  • makefile, remaking of
  • makefile, simple
  • makeinfo, makeinfo
  • match-anything rule
  • match-anything rule, used to override
  • missing features
  • mistakes with wildcards
  • modified variable reference
  • Modula-2, rule to compile
  • mostlyclean (standard target)
  • multiple rules for one target
  • multiple rules for one target (::)
  • multiple targets
  • multiple targets, in pattern rule

    • n

  • name of makefile
  • name of makefile, how to specify
  • nested variable reference
  • newline, quoting, in commands
  • newline, quoting, in makefile
  • nondirectory part

    • o

  • OBJ
  • obj
  • OBJECTS
  • objects
  • OBJS
  • objs
  • old-fashioned suffix rules
  • options
  • options, and recursion
  • options, setting from environment
  • options, setting in makefiles
  • order of pattern rules
  • origin of variable
  • overriding makefiles
  • overriding variables with arguments
  • overriding with override

    • p

  • parallel execution
  • parallel execution, and archive update
  • parallel execution, overriding
  • parts of makefile rule
  • Pascal, rule to compile
  • pattern rule
  • pattern rule, expansion
  • pattern rules, order of
  • pattern rules, static (not implicit)
  • pattern rules, static, syntax of
  • pattern-specific variables
  • pc, pc
  • phony targets
  • pitfalls of wildcards
  • portability
  • POSIX
  • POSIX.2
  • post-installation commands
  • pre-installation commands
  • precious targets
  • predefined rules and variables, printing
  • prefix, adding
  • prerequisite
  • prerequisite pattern, implicit
  • prerequisite pattern, static (not implicit)
  • prerequisite, expansion
  • prerequisites
  • prerequisites, automatic generation, prerequisites, automatic generation
  • prerequisites, introduction to
  • prerequisites, list of all
  • prerequisites, list of changed
  • prerequisites, varying (static pattern)
  • preserving intermediate files
  • preserving with .PRECIOUS, preserving with .PRECIOUS
  • preserving with .SECONDARY
  • print (standard target)
  • print target, print target
  • printing directories
  • printing of commands
  • printing user warnings
  • problems and bugs, reporting
  • problems with wildcards
  • processing a makefile

    • q

  • question mode
  • quoting %, in static pattern
  • quoting %, in patsubst
  • quoting %, in vpath
  • quoting newline, in commands
  • quoting newline, in makefile

    • r

  • Ratfor, rule to compile
  • RCS, rule to extract from
  • reading makefiles
  • README
  • realclean (standard target)
  • recompilation
  • recompilation, avoiding
  • recording events with empty targets
  • recursion
  • recursion, and -C
  • recursion, and -f
  • recursion, and -j
  • recursion, and -o
  • recursion, and -t
  • recursion, and -W
  • recursion, and -w
  • recursion, and command line variable definitions
  • recursion, and environment
  • recursion, and MAKE variable
  • recursion, and MAKEFILES variable
  • recursion, and options
  • recursion, and printing directories
  • recursion, and variables
  • recursion, level of
  • recursive variable expansion, recursive variable expansion
  • recursively expanded variables
  • reference to variables, reference to variables
  • relinking
  • remaking makefiles
  • removal of target files, removal of target files
  • removing duplicate words
  • removing targets on failure
  • removing, to clean up
  • reporting bugs
  • rm
  • rm (shell command), rm (shell command), rm (shell command), rm (shell command)
  • rule commands
  • rule prerequisites
  • rule syntax
  • rule targets
  • rule, and $
  • rule, double-colon (::)
  • rule, explicit, definition of
  • rule, how to write
  • rule, implicit
  • rule, implicit, and directory search
  • rule, implicit, and VPATH
  • rule, implicit, chains of
  • rule, implicit, definition of
  • rule, implicit, how to use
  • rule, implicit, introduction to
  • rule, implicit, predefined
  • rule, introduction to
  • rule, multiple for one target
  • rule, no commands or prerequisites
  • rule, pattern
  • rule, static pattern
  • rule, static pattern versus implicit
  • rule, with multiple targets

    • s

  • s. (SCCS file prefix)
  • SCCS, rule to extract from
  • search algorithm, implicit rule
  • search path for prerequisites (VPATH)
  • search path for prerequisites (VPATH), and implicit rules
  • search path for prerequisites (VPATH), and link libraries
  • searching for strings
  • secondary files
  • secondary targets
  • sed (shell command)
  • selecting a word
  • selecting word lists
  • sequences of commands
  • setting options from environment
  • setting options in makefiles
  • setting variables
  • several rules for one target
  • several targets in a rule
  • shar (standard target)
  • shell command
  • shell command, and directory search
  • shell command, execution
  • shell command, function for
  • shell file name pattern (in include)
  • shell wildcards (in include)
  • SHELL, MS-DOS specifics
  • signal
  • silent operation
  • simple makefile
  • simple variable expansion
  • simplifying with variables
  • simply expanded variables
  • sorting words
  • spaces, in variable values
  • spaces, stripping
  • special targets
  • specifying makefile name
  • standard input
  • standards conformance
  • standards for makefiles
  • static pattern rule
  • static pattern rule, syntax of
  • static pattern rule, versus implicit
  • stem, stem
  • stem, variable for
  • stopping make
  • strings, searching for
  • stripping whitespace
  • sub-make
  • subdirectories, recursion for
  • substitution variable reference
  • suffix rule
  • suffix rule, for archive
  • suffix, adding
  • suffix, function to find
  • suffix, substituting in variables
  • switches
  • symbol directories, updating archive
  • syntax of rules

    • t

  • tab character (in commands)
  • tabs in rules
  • TAGS (standard target)
  • tangle, tangle
  • tar (standard target)
  • target
  • target pattern, implicit
  • target pattern, static (not implicit)
  • target, deleting on error
  • target, deleting on interrupt
  • target, expansion
  • target, multiple in pattern rule
  • target, multiple rules for one
  • target, touching
  • target-specific variables
  • targets
  • targets without a file
  • targets, built-in special
  • targets, empty
  • targets, force
  • targets, introduction to
  • targets, multiple
  • targets, phony
  • terminal rule
  • test (standard target)
  • testing compilation
  • tex, tex
  • TeX, rule to run
  • texi2dvi, texi2dvi
  • Texinfo, rule to format
  • tilde (~)
  • touch (shell command), touch (shell command)
  • touching files
  • traditional directory search

    • u

  • undefined variables, warning message
  • updating archive symbol directories
  • updating makefiles
  • user defined functions

    • v

  • value
  • value, how a variable gets it
  • variable
  • variable definition
  • variables
  • variables, `$' in name
  • variables, and implicit rule
  • variables, appending to
  • variables, automatic
  • variables, command line
  • variables, command line, and recursion
  • variables, computed names
  • variables, conditional assignment
  • variables, defining verbatim
  • variables, environment, variables, environment
  • variables, exporting
  • variables, flavors
  • variables, how they get their values
  • variables, how to reference
  • variables, loops in expansion
  • variables, modified reference
  • variables, nested references
  • variables, origin of
  • variables, overriding
  • variables, overriding with arguments
  • variables, pattern-specific
  • variables, recursively expanded
  • variables, setting
  • variables, simply expanded
  • variables, spaces in values
  • variables, substituting suffix in
  • variables, substitution reference
  • variables, target-specific
  • variables, warning for undefined
  • varying prerequisites
  • verbatim variable definition
  • vpath
  • VPATH, and implicit rules
  • VPATH, and link libraries

    • w

  • warnings, printing
  • weave, weave
  • Web, rule to run
  • what if
  • whitespace, in variable values
  • whitespace, stripping
  • wildcard
  • wildcard pitfalls
  • wildcard, function
  • wildcard, in archive member
  • wildcard, in include
  • wildcards and MS-DOS/MS-Windows backslashes
  • word, selecting a
  • words, extracting first
  • words, filtering
  • words, filtering out
  • words, finding number
  • words, iterating over
  • words, joining lists
  • words, removing duplicates
  • words, selecting lists of
  • writing rule commands
  • writing rules

    • y

  • yacc
  • yacc, yacc
  • Yacc, rule to run

    • ~

  • ~ (tilde)

    • Index of Functions, Variables, & Directives

    $

  • $%
  • $(%D)
  • $(%F)
  • $(*D)
  • $(*F)
  • $(<D)
  • $(<F)
  • $(?D)
  • $(?F)
  • $(@D)
  • $(@F)
  • $(^D)
  • $(^F)
  • $*
  • $*, and static pattern
  • $+
  • $<
  • $?
  • $@
  • $^

    • %

  • % (automatic variable)
  • %D (automatic variable)
  • %F (automatic variable)

    • *

  • * (automatic variable)
  • * (automatic variable), unsupported bizarre usage
  • *D (automatic variable)
  • *F (automatic variable)

    • +

  • + (automatic variable)

    • .

  • .DEFAULT, .DEFAULT
  • .DEFAULT, and empty commands
  • .DELETE_ON_ERROR, .DELETE_ON_ERROR
  • .EXPORT_ALL_VARIABLES, .EXPORT_ALL_VARIABLES
  • .IGNORE, .IGNORE
  • .INTERMEDIATE
  • .LIBPATTERNS
  • .NOTPARALLEL
  • .PHONY, .PHONY
  • .POSIX
  • .PRECIOUS, .PRECIOUS
  • .SECONDARY
  • .SILENT, .SILENT
  • .SUFFIXES, .SUFFIXES

    • /

  • /usr/gnu/include
  • /usr/include
  • /usr/local/include

    • <

  • < (automatic variable)
  • <D (automatic variable)
  • <F (automatic variable)

    • ?

  • ? (automatic variable)
  • ?D (automatic variable)
  • ?F (automatic variable)

    • @

  • @ (automatic variable)
  • @D (automatic variable)
  • @F (automatic variable)

    • ^

  • ^ (automatic variable)
  • ^D (automatic variable)
  • ^F (automatic variable)

    • a

  • addprefix
  • addsuffix
  • AR
  • ARFLAGS
  • AS
  • ASFLAGS

    • b

  • basename

    • c

  • call
  • CC
  • CFLAGS
  • CO
  • COFLAGS
  • COMSPEC
  • CPP
  • CPPFLAGS
  • CTANGLE
  • CWEAVE
  • CXX
  • CXXFLAGS

    • d

  • define
  • dir

    • e

  • else
  • endef
  • endif
  • error
  • export

    • f

  • FC
  • FFLAGS
  • filter
  • filter-out
  • findstring
  • firstword
  • foreach

    • g

  • GET
  • GFLAGS
  • GNUmakefile
  • GPATH

    • i

  • if
  • ifdef
  • ifeq
  • ifndef
  • ifneq
  • include

    • j

  • join

    • l

  • LDFLAGS
  • LEX
  • LFLAGS

    • m

  • MAKE, MAKE
  • MAKECMDGOALS
  • Makefile
  • makefile
  • MAKEFILES, MAKEFILES
  • MAKEFLAGS
  • MAKEINFO
  • MAKELEVEL, MAKELEVEL
  • MAKEOVERRIDES
  • MFLAGS

    • n

  • notdir

    • o

  • origin
  • OUTPUT_OPTION
  • override

    • p

  • patsubst, patsubst
  • PC
  • PFLAGS

    • r

  • RFLAGS
  • RM

    • s

  • shell
  • SHELL
  • SHELL (command execution)
  • sort
  • strip
  • subst, subst
  • suffix
  • SUFFIXES

    • t

  • TANGLE
  • TEX
  • TEXI2DVI

    • u

  • unexport

    • v

  • VPATH, VPATH
  • vpath, vpath

    • w

  • warning
  • WEAVE
  • wildcard, wildcard
  • word
  • wordlist
  • words

    • y

  • YACC
  • YACCR
  • YFLAGS

    • Footnotes

    (1)

    GNU Make compiled for MS-DOS and MS-Windows behaves as if prefix has been defined to be the root of the DJGPP tree hierarchy.

    (2)

    On MS-DOS, the value of current working directory is global, so changing it will affect the following command lines on those systems.

    (3)

    texi2dvi uses TeX to do the real work of formatting. TeX is not distributed with Texinfo.

    This document was generated on 19 July 2000 using the texi2html translator version 1.54.


GNU Nana: improved support for assertions and logging in C and C++

GNU Nana

Improved support for assertions and logging in C and C++

last updated 27 February 1998 for version 1.14

P.J.Maker (pjm@cs.ntu.edu.au)

Table of Contents

  • Introduction
    • Related work
    • Assert.h considered harmful
    • Scope of this document
  • Installing the Nana library
    • Required Software
    • Optional Software
    • Configure
    • Variables for ./configure
    • Supported Platforms
    • Supported Debuggers
    • Known Problems
    • Bug Reports
    • New Versions
  • Invoking Nana
  • Interface
    • nana.h: the main header file
    • WITHOUT_NANA: disabling all nana code for portability.
    • I.h: C based invariant checking
    • DI.h: debugger based invariant checking
    • L.h: support for printf style logging
    • L_buffer.h: a circular buffer for logging.
    • L_times.h: recording events and times.
    • DL.h: support for printf style logging
    • GDB.h: sending plain gdb commands to the debugger
    • Q.h: support for quantifiers
    • Qstl.h: quantifiers for STL containers.
    • now.h: measuring time
    • eiffel.h: eiffel type assertions
    • assert.h: a drop in replacement for assert.h
    • calls.h: checking/printing many objects/facts.
  • Using Nana
    • Simplest example
    • Syslog
    • GNU Programs: how to avoid nana sometimes
    • Embedded Systems: testing non-deterministic systems.
    • Realtime Systems
    • A database
    • Program Visualisation: pretty pictures
  • FAQ
  • Future work
  • Index

Copyright (C) 1996, 1997, P.J.Maker

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Introduction

Nana is a library that provides support for assertion checking and logging in a space and time efficient manner. The aim is to put common good practise(1) into a library that can be reused rather than writing this stuff every time you begin a new project.

In addition assertion checking and logging code can be implemented using a debugger rather than as inline code with a large saving in code space.

Nana aims to solve the following problems:

  1. Avoid the two executables problem (one with asserts in and another without any). The code space and time costs of having assertion checking and detailed logging code in a program can be high. Normally people construct two versions of the program, one with checking code for testing and one without checking code for production use. With nana one version of the executable can be built for both testing and release since debugger based checking has negligible space and time impact.
  2. Configurable: the nana library is designed to be reconfigured by the user according to their needs. For example we can:
    • Modify the behaviour on assertion failure, e.g. to attempt a system restart rather than just shutting down.
    • Selectively enable and disable assertion checking and logging both at compile and run time.
    • Send the logging information off to various locations, e.g.
      • Users terminal
      • A file for later checking.
      • Another process, e.g. a plotting program or a program that verifies that the system is behaving itself.
      • A circular buffer in memory. This is an old embedded systems trick and is very useful for production systems. The time cost of logging into memory is not large and when your production system in the field has problems you can then see what was happening in the minutes before its unfortunate demise rather than asking some user what was happening before it died.
  3. Time and space efficient. For example the GNU `assert.h' implementation uses 53 bytes for `assert(i>=0)' on a i386. The nana version using the i386 `stp' instruction on assert fail uses 10 bytes. If your willing to accept the time penalty this can be reduced to 0 or 1 byte by using debugger based assertions.
  4. Support for formal methods.
    • Before and after state (e.g. x,x' in the Z notation). Specifications are often written in terms of the state of variables before and after an operation. For example the `isempty' operation on a stack should leave the stack unchanged. To verify this in nana we could use:
      bool isempty(){ /* true iff stack is empty */
  DS($s = s); /* copy s into $s in the debugger */
  ...; /* code to do the operation */
  DI($s == s); /* verify that s hasn't been changed */
}
      These `$..' variables are called convenience variables and are implemented by gdb. They have a global scope and are dynamically typed and initialised automatically to 0. In addition a C only version of before and after state is provided. For example:
      bool isempty() { /* true iff stack is empty */
  ID(int olds); /* declare variable to hold old value */
  IS(olds = s); /* copy s into $s in the debugger */
  ...; /* code to do the operation */
  I(olds == s); /* verify that s hasn't been changed */
}
    • Support for Predicate Calculus. Nana provides some support for universal (forall) and existential (exists one or more) quantification. For example to specify that the string v contains only lower case letters we could use:
        I(A(char *p = v, *p != '\0', p++, islower(*p)));
      These macros can be nested and used as normal boolean values in control constructs as well as assertions. Unfortunately they depend on the GNU CC statement value extensions and so are not portable. The following macros are defined in `Q.h':
      A
      For all values the expression must be true.
      E
      There exists one or more values for which the expression is true.
      E1
      There exists a single value for which the expression is true.
      C
      Returns the number of times the expression is true.
      S
      Returns the sum of the expressions.
      P
      Returns the product of the expressions.
    • Verifying timing. As well as using nana to verify timings with assertions using a hardware supported timer you can also a simulator (e.g. the PSIM power pc simulator by Cagney) with gdb. These simulators can model time and provide a register called `$cycles' which represents the current cycle count of the program. This can be used to check that timing constraints are being meet.
      void process_events() {
  for(;;){
    DS($start = $cycles);
    switch(get_event()){
      case TOO_HOT:
        ...;
        DI($start - $cycles <= 120);
        break;
      case TOO_COLD:
        ...;
        DI($start - $cycles <= 240);
        break;
    }
  }
}

The intended audience for Nana includes:

  • Software Engineers.
  • Formal methods community.
  • Real time programmers.
  • System testers.
  • People teaching programming.

Related work

The Nana project was inspired by some other projects, in particular:

  • Anna - Anna stands for "Annotated Ada" where the programmer inserts various assertions into the code which can be automatically validated. To quote from the WWW Virtual Library entry on Anna:

    Anna is a language for formally specifying the intended behaviour of Ada programs. It extends Ada with various different kinds of specification constructs from ones as simple as assertions, to as complex as algebraic specifications. A tool set has been implemented at Stanford for Anna, including:

    1. standard DIANA extension packages, parsers, pretty-printers;
    2. a semantic checker;
    3. a specification analyser;
    4. an annotation transformer; and
    5. a special debugger that allows program debugging based on formal specifications

    All tools have been developed in Ada and are therefore extremely portable. Anna has thus been ported to many platforms. For more information send e-mail to "anna-request@anna.stanford.edu". Before down loading the huge Anna release, you may wish to copy and read some Anna LaTeX reports.

    Anna is available from: ftp://anna.stanford.edu/pub/anna
  • Eiffel - the Eiffel programming language provides support in the language flexible assertion checking. To quote from the Eiffel page in WWW Virtual library:

    Eiffel is a pure object-oriented language featuring multiple inheritance, polymorphism, static typing and dynamic binding, genericity (constrained and unconstrained), a disciplined exception mechanism, systematic use of assertions to promote programming by contract, and deferred classes for high-level design and analysis.

  • APP - Annotation PreProcessor. The APP was written by David S. Rosenblum and provides assertion checking functions for C and C++. It is implemented using a preprocessor wrapper around the C preprocessor and supports quantifiers and before/after state. See "A Practical Approach to Programming with Assertions" in Vol 21, No. 1, January 1995 of IEEE Transactions on Software Engineering for an interesting paper describing APP. Unfortunately the APP tool doesn't seem to be freely available (I'm willing to be corrected on this). Note that any similarity between my examples and David's are due to morphic resonance.

Nana is essentially a poor mans implementation of some of these ideas which works for C and C++. Ideally in the best of all possible worlds you might want to look at Eiffel or in the military world Ada and Anna. If you use TCL/TK you might also be interested in Jon Cook's `AsserTCL' package.

Assert.h considered harmful

Most C programmers become familiar with assertions from the the assert.h header. As such its a very good thing and has a nice simple implementation. However it is also inefficient and leads some people to the conclusion that assertion checking is an expensive luxury.

The implementation of assert.h as distributed with gcc looks like the following (after a bit of editing):

# ifndef NDEBUG
# define _assert(ex)	{if (!(ex)) \
                         {(void)fprintf(stderr, \
                           "Assertion failed: file \"%s\", line %d\n", \
                           __FILE__, __LINE__);exit(1);}}
# define assert(ex)	_assert(ex)
# else
# define _assert(ex)
# define assert(ex)
# endif

There are are two main problems with this:

  1. Code space overhead: each call to `assert' generates 2 function calls with 4 and 1 arguments plus strings for error messages. If assert.h had library code support we could make the implementation much more space efficient, e.g. by calling a single function on error detection.
  2. The default behaviour simply prints a message and dies, ideally you like to be able to use a debugger to determine why the assertion failed. Even if you run this under the debugger you can't observe the failures of variables are an assert failure because the process exits rather than aborting back to the debugger.

Of course everyone merely rewrites their own `assert' macro so these are not significant objections. The only problem is if the author uses the libraries without modification.

Scope of this document

This document aims to both describe the library and provide a tutorial in its use. Further work is required, particularly on the tutorial sections. If anyone has any suggestions please send them to me.

Installing the Nana library

Nana uses the normal GNU install method in the same way as `gcc' and `gdb'. To install nana in the default location `/usr/local/{bin,lib,include}' you would use:

% gzcat nana-1.10.tar.gz | tar xvf -
% cd nana-1.10
% ./configure
% make
% make install
% make check
% make check-mail
% make subscribe

The check-mail and subscribe targets both send e-mail. If you need to change the mailer used try something like:

% make MAIL=elm subscribe

Note: we need to install nana before running the `make check' target. The `check-mail' target sends the test report via e-mail to the `nana-bug@cs.ntu.edu.au'.

Of course things are never that simple. If you want to install Nana in a different location or change the behaviour on error detection see section Configure.

Each of the sub-directories nana can be compiled and installed separately, e.g. if you don't need the documentation you can just compile and install from the `src' sub-directory after doing the configure statement.

Required Software

The following software is possibly required to run nana.

gcc-2.7.2
Nana makes use of two GNU extensions in its library so you really should be using `gcc'. Some of the code can be used with any C compiler, though it may not be worth the bother. The dependencies on gcc are in `Q.h' which uses the statement value extension and in `L.h' which uses the variable number of arguments extension to `cpp'.
gdb-4.16
A recent version of `gdb' is worthwhile, some early 4.?? versions had problems setting a large number of breakpoints.
gmake
The `configure' script and `Makefiles' are generated using the `automake' and `autoconf' programs. They should be reasonably portable but if you have problems try using GNU make. For example on some old DEC boxes we have had strange behaviour using the system make.

For a listing of porting results including software versions see:

`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'

Optional Software

In addition to the required software you might also be interested in:

  • `http://www.cs.tu-bs.de/softech/ddd/' -- a smart frontend for gdb which can display dynamic data structures such as linked lists, etc.
  • `ftp://ftp.ci.com.au/pub/psim/' -- a cycle level simulator for the PowerPC. A fine piece of work.

Configure

Nana uses a standard GNU autoconf generated configure script. The configure script checks the setup on your machine and then generates the appropriate Makefiles. Some of the things checked by configure include:

  1. Which compiler, compiler flags and libraries to use, e.g. you might need to include a -lposix flag to the linker to build programs on your machine.
  2. Which header (.h) files are available on this machine, e.g. is unistd.h available on this machine.
  3. Where to install programs, header file, man pages, etc.

In addition `configure' uses the host architecture and operating system to generate the `nana-config.h' file. This file contains some macro definitions which define how nana works on particular operating systems and hardware architectures.

For example on `i386' machines we would use the `asm("hlt")' instruction whenever an assertion fails, on a `sparc' we would use `asm("stp")'. Otherwise we would default to a plain C call to `abort()' If `configure' does not recognise your machine it uses plain C code.

You may wish to change these defaults on installation, one method is to edit a local copy of the `nana-config.h' file. Alternately you can define the code yourself in the call to `configure'. For example to redefine the action we take when an error is detected by the I macro we can use:

I_DEFAULT_HANDLER="restart_system()" ./configure

As well as simple calls to routines various other bits of information are passed off to the `I_DEFAULT_HANDLER' such as the expression that failure and a failure code. For example:

% I_DEFAULT_HANDLER="restart(line,file,param)" ./configure

The default for `I_DEFAULT_HANDLER' calls a function which prints a message and then dumps core. Different behaviour on failure can be organised by setting the `I_DEFAULT' to `fast', i.e. plain core dump or `verbose' which prints an error messsage and then does the core dump.

% I_DEFAULT=fast ./configure

For nana the following examples may be useful:

  1. ./configure Accept the default values for everything. In particular the files will be installed in: `/usr/local/{bin,include,lib,man,info}'
  2. ./configure --prefix=~project/tools Install the files into: `~project/tools/{bin,include,lib,man,info}'
  3. ./configure --bindir=~project/bin --libdir=~/project/lib \
    --includedir=~/project/headers --infodir=/usr/local/info \
    --mandir=~/project/doc     The install directory for program (`bin'), etc can all be set with command line arguments to`configure'.
  4. CC=xacc LIBS=-lposix ./configure sun3 If the defaults chosen by `configure' are not correct you can override them by setting variables such as CC before calling `configure'. The `sun3' argument is used to identify the machine we are running on and may be necessary on some machines.
  5. ./configure --help And of course when in doubt ask for help.

For even more details see the file `INSTALL.con' which contains the generic instructions for use with `autoconf' generated `configure' scripts.

Variables for ./configure

The configure program uses the following shell variables to change various defaults. Another method is simply to edit the `nana-config.h' file. Most of these values should be auto detected, so you can ignore this section until your need to save a few bytes of store by using `asm("hlt")' instead of a call to `abort()'.

DI_MAKE_VALID_BREAKPOINT
This text is inserted when the `DI.h' library needs to set a breakpoint in the generated code. It should ideally update all variables which being kept in registers etc so that gdb gets the correct values for each variable. Possible values include:
  1. `asm("nop")' -- a single `nop' instruction to set the breakpoint at. This is the default.
  2. `_vi = 0' -- where `_vi' is a global volatile int.
  3. `_vi = (exprn)' -- where exprn is the expression we are checking for this assertion.
  4. `/* nothing */' -- nothing at all, this means the breakpoint will be set at the start of the next statement which works most of the time. However for some examples this will do the wrong thing.
DL_MAKE_VALID_BREAKPOINT
Used for the same purpose as `DI_MAKE_VALID_BREAKPOINT' for `DL.h'. It also defaults to `asm("nop")'.
I_DEFAULT_HANDLER
The code called when `I.h' detects an error.
asm("hlt")
Some machines use a `hlt' instruction.
asm("stp")
And other machines use a `stp' instruction.
abort()
Or we could use a call to `abort' which is at least standard C. On some machines this is significantly larger than a single `hlt' instruction.
restart()
Or a call to a function which attempts to restart the system.
ALWAYS_INCLUDE_MALLOC
This is a dodgey for some versions of Linux which don't seem to include `malloc' when you include `stdio.h' and use `print'. This causes problems for `gdb' since it uses `malloc' in the executable to implement parts of its functionality. This kludge should be removed!

Supported Platforms

Nana has been tested on the following platforms:

  1. i386-unknown-linux, gcc-2.7.0, gdb-4.16
  2. sparc-sun-sunos4.1.4, gcc-2.7.2.f.1, gdb-4.16
  3. sparc-sun-solaris2.3, gcc-2.7.2, gdb-4.16
  4. alpha-dec-osf3.2, gcc-2.7.2, gdb-4.16
  5. mips-sgi-irix5.3, gcc-2.7.0, gdb-4.16
  6. powerpc-ibm-aix3.2.5, gcc-2.6.3, gdb-4.16

The `alpha-dec-osf3.2', `mips-sgi-irix5.3' and `powerpc-ibm-aix3.2.5' implementations have problems when you compile with `-O2' or `-O3' optimisation. This causes some errors in the the debugger based assertion and logging code since variables can be removed or changed by optimisation. At `-O' everything passes. Regardless of optimisation the C based checking code passes all tests on these platforms.

If you use nana on a new platform please send the `check.log' file to `nana-bug@cs.ntu.edu.au' via the `make check-mail' command. A machine generated list of this information is available at:

`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'

Supported Debuggers

Currently Nana works with the GNU GDB debugger which is available on a wide range of platforms including embedded systems and even provides support for remote debugging. Porting to any reasonable debugger with conditional breakpoints and commands is not very difficult.

As an example of an unreasonable debugger, Nana has been ported to work with the MicroSoft Codeview debugger. The port is small (60 lines of code) but suffers from a problem with variable scoping in Codeview. If a breakpoint is set at a point in the code the expressions are not evaluated from that particular scope. For example setting a breakpoint in the function f cannot access a variable local to f directly. Codeview has a unique (expletive deleted) scope operator which you must use to set the scope `{...}'. This makes the interface somewhat less than beautiful.

Another good thing about CodeView is to try a debug command which prints a message which contains a single open `{'. This of course causes it to hang and was the main problem during the porting to CodeView which took a whole day(2).

If anyone is interested I may release the CodeView implementation, please contact me if you are interested. Of course a better bet is probably to move to the `gdbserver' system. I think `gdb' has been released as a native even for some MicroSoft operating systems.

Other debuggers like DBX don't seem to be worth the trouble since gdb works on those machines. A redesign of the nana internals may also be useful if we decide portability between debuggers is actually useful.

Known Problems

Nana has the following known features (or perhaps problems):

  1. Nana macros which use the debugger such as DI or DL should be on lines by themselves. If you mix code and nana macros on the same line you will get errors, e.g:
    main(){
   int x;
   x = 5; x--; DI(x == 4);
}
    This doesn't work since breakpoints are set at line boundaries rather than statement ones. Of course anyone who writes code like this deserves whatever happens to them.
  2. Optimisation can remove variables so that debugger based assertions (`DI.h') do not work correctly. As usual the interaction between the debugger and the compiler is rather complicated. This may not be a problem if the appropriate compile-time flags are selected, e.g. `-O0 and -O1' work on most platforms.
  3. The `Q.h' macros depend on the statement value extension to GNU CC so if you wish to use them you must use GCC. This can be fixed for C++ in a possibly useful manner, I can't see any solution for C.
  4. The logging macros depend on the Var Args extension provided by the GNU C Preprocessor.(3) We could (probably will) implement a fix for this based on the tricks in the C FAQ. Unfortunately these tricks are not pretty. For now interested users could simply replace their CPP with the GNU CPP if they wished to stay with non-standard compilers.
  5. The `Q.h' macros do not work in the debugger since `gdb' does support the statement expression extension.
  6. Multiline expressions do not work as expected in the debugger since you need to use a blackslash as an escape at the end of the line. For example:
         DI(x +
            10 > 30);
    A few backslashes may solve this particular problem.
  7. Problems with the `configure' script. The `configure' script automatically detects the target operating system and architecture and then generates `nana-config.h'. If the options selected in `nana-config.h' are incorrect they can be edited by hand and installed in the usual include directory. The easiest method is simply to delete all macros in `nana-config.h' since the system defaults to more portable (and less efficient) implementations. If you wish to do this from the configure script you can try giving a unsupported machine type, e.g.
    % ./configure pdp11-dec-ultrix
  8. Some users have reported problems with the configure script detecting vsnprintf. If configure doesn't find it and it does exist then simply define it in `nana-config.h' as per the previous question. If vsnprintf really doesn't exist then get a new C library, possibly the GNU libc.
  9. The use of vsprintf opens a security hole since no bounds checking is done by it. Nana attempts to use vsnprintf which is safe when it exists but it will resort to vsprintf if it can't find vsnprintf. All careful people should make sure that they have a library with vsnprintf.
  10. STL header file errors due to nana. The C++ STL header files for version 3.0 at least must be included before the Q.h file. The problem is caused by the STL files using S as a template argument. Of course Q.h uses S for summing a series. Namespace pollution strikes again. (Thanks to Han Holl for this particular problem).

Bug Reports

If you think you have found a bug in the Nana library, please investigate it and report it.

  • Please make sure that the bug is really in the Nana library.
  • You have to send us a test case that makes it possible for us to reproduce the bug.
  • You also have to explain what is wrong; if you get a crash, or if the results printed are not good and in that case, in what way. Make sure that the bug report includes all information you would need to fix this kind of bug for someone else.

If your bug report is good, we will do our best to help you to get a corrected version of the library; if the bug report is poor, we won't do anything about it (apart from asking you to send better bug reports).

Send your bug report to:

`nana-bug@cs.ntu.edu.au'

Copies of bug reports will be kept at:

`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'

New Versions

New versions of nana will be made available at:

`ftp://ftp.cs.ntu.edu.au/pub/nana/'

If you wish to be informed about new releases of nana then subscribe to the nana mailing list. Send a message containing `subscribe' <your e-mail address> to:

`mailto:nana-request@it.ntu.edu.au'.

A hypermail archive of this list is kept at:

`http://www.cs.ntu.edu.au/hypermail/nana-archive'

If you wish to send a message to the list send it to `mailto:nana@it.ntu.edu.au'.

Invoking Nana

The functions defined by Nana are implemented either as pure C code or as a set of commands which are generated for the debugger. To use the C based support for assertion checking you would use something like:

#include <nana.h> /* this file includes the other nana .h files */

int floor_sqrt(int i) { /* returns floor(sqrt(i) */
  int answer;
  I(i >= 0); /* assert(i >= 0) if i -ve then exit */
  ...; /* code to calculate sqrt(i) */
  L("floor_sqrt(%d) == %d\n",
        i, answer);  /* logs a printf style message */
}

To compile and link the previous code you may need to use the `-Ipath' or `-lnana' flags with the compiler. For example:

% gcc toy.c -lnana

If the nana headers have been installed in a strange location you may need to do something like:

% gcc -I<strange location> toy.c -lnana

The next example uses the debugger versions of `L' and `I'. If the code is run under the debugger these checks will occur, otherwise they take up a negligible amount of space and time.

#include <nana.h> /* this includes the other nana .h files */

int floor_sqrt(int i){
  int answer;
  DI(i >= 0); /* assert(i >= 0) if i -ve then exit */
  ...; /* code to calculate sqrt(i) */
  DL("floor_sqrt(%d) == %d\n", i, answer);  /* logs a printf style message */
}

To generate the debugger commands from the C source we just run the `nana' filter over the program and then execute the commands under gdb using the `source' command.

% nana sqrt.c >sqrt.gdb
% gdb a.out
(gdb) source sqrt.gdb
breakpoint insert: ...
(gdb) run
...
(gdb) quit

Note that any C preprocessor flags which you use must be passed off to the `nana' command. The best way to do this of course is in a Makefile. Something like the following works for GNU Make:

%.nana: %.c
        nana $(CFLAGS) $< >$@

The `nana' filter can also be run over multiple source files in a single run if thats more convenient.

For convenience a number of other simple scripts are provided, in particular to:

nana-run
Run a program under the debugger without prompting, etc. For example:
% nana-run a.out -x main.gdb
output from program
nana-clg
Compiles the program, generates the debugger commands and the runs the program using `nana-run'. For example:
% nana-clg -O3 main.c
output from program
You can change the compiler invoked by `nana-clg' by redefining the `NANACC' environment variable. For example:
% NANACC=g++ nana-clg -O3 main.cc
The installation also `nana-c++lg' which compiles your code using a GNU C++ compiler.
nana-trace
Generates a line by line trace of the execution of a program using GDB. For example:
% nana-trace a.out
54           printf("main()\n");
55           x = distance(5,-5);
distance (i=5, j=-5) at test.c:47
47           i = -i;
48           j = -j;
...
The arguments to `nana-trace' are passed directly to GDB. If you wish display variables or call procedures on each line then could use something like:
% nana-trace -x mycommands.gdb a.out
Where the `mycommands.gdb' contains the GDB commands such as `display x' which causes `x' to be printed every time the debugger gets control of the program.

Interface

This section describes the details of the interface to nana library.

All of the files can be included multiple times without ill--effect since they use the C preprocessor to make sure the header declarations are only seen the first by the compiler. Each of the files can also be included individually.

If any of the following routines have an internal problem (e.g. malloc fails due to lack of memory) they will call the `nana_error' function defined in `nana_error.c'. By default this function prints a message and dumps core using `abort'. If you wish to override this behaviour you should define your own handler before linking in the nana library.

nana.h: the main header file

The `nana.h' file includes most of the other files in the library. In particular it `#include's' the following files:

I.h
DI.h
L.h
DL.h
Q.h
GDB.h

WITHOUT_NANA: disabling all nana code for portability.

If you wish to disable all nana code you can `#define' the `WITHOUT_NANA' macro. This selects versions of the macros defined in `I.h',`L.h', etc which map to `/* empty */'.

So if you are using nana for your development but don't wish to force your customers to use it you can add an option to your `configure' script to define/undefine `WITHOUT_NANA'. In addition you will need to distribute copies of the nana header files with your package to get the stubs.

Note that the `L.h' and `DL.h' macros use the macro variable number of arguments extension provided by GNU C. If you wish your code to be portable you should use the macros `VL((..))', etc rather than `L(..)' to avoid problems with non GNU C preprocessors which only take a fixed number of arguments.

I.h: C based invariant checking

This implements the C based invariant checking code and is a replacement for `assert.h'. The first two macros are the normal user interface; the remainder are used for configuring the behaviour on failure, etc.

Macro: void I (bool exprn)
The exprn should always be true if the program is correct. If the exprn is false a message will be printed, followed by core dump.(4)

Checking can be enabled and disabled by using the I_LEVEL and I_DEFAULT_GUARD macros. See the definitions below for these macros for further details.

Note that exprn should have no side-effects(5) since disabling checking shouldn't change your programs behaviour.

  I(z != 0);
  x = y / z;

Macro: void N (bool exprn)
The opposite of `I', i.e. the expression must never ever be true if the program is working properly. It is equivelant to I(!(e)) and exists as a piece of syntactic sugar which may be helpful for complicated boolean expressions.

char* strdup(char *s) {
  N(s == NULL);
  ...;
}

Macro: int I_LEVEL
The `I_LEVEL' macro is used to globally enable and disable checking by the macros in this file. It can take on one of three values:

0
Disable all checking. Regardless of anything else no code will be generated for I, N, etc.
1
Enable checking only if the corresponding guard condition is true. The guard condition can be used to enable and disable checking at compile and run time.
2
Enable all checking regardless of guard conditions.

I_LEVEL defaults to 1.

Macro: bool I_DEFAULT_GUARD
The I_DEFAULT_GUARD is used to selectively enable or disable checking at compile or run time.

I_DEFAULT_GUARD defaults to TRUE, i.e. always enabled.

A user would typically define I_DEFAULT_GUARD to be global or local variable which is used to turn checking on or off at run--time. For example:

#define I_DEFAULT_GUARD i_guard > 0

extern int i_guard;

Macro: text I_DEFAULT_PARAMS
This is passed off to the I_DEFAULT_HANDLER and defaults to nothing, it is just some text and is intended to pass failure codes (e.g. IEH303) or requests (e.g. HW_DEAD) information off to the handler.

I_DEFAULT_PARAMS defaults to nothing.

Macro: void I_DEFAULT_HANDLER (char *exprn, char *file, int line, param)

When an error is detected the I_DEFAULT_HANDLER will be called to handle the error. The arguments are:

exprn
A string representation of the expression that has failed, e.g. "I(i>=0)".
file
The file that this error occurred in, i.e. __FILE__.
line
The line number for the error, i.e. __LINE__.
param
An optional parameter which can be passed across which defaults to I_DEFAULT_PARAMS. This can be used to pass failure codes or other information from the checking code to the handler.

All of the remaining macros are used to individually override the default values defined above. Normally these macros would be used in a system wide header file to define macros appropriate for the application. For example you might use `IH' to define different checking macros for hardware and software faults.

Macro: void I (bool e)
Macro: void IG (bool e, bool g)
Macro: void IH (bool e, Macro h)
Macro: void IP (bool e, Text p)
Macro: void IGH (bool e, bool g, Macro h)
Macro: void IGP (bool e, bool g, Text p)
Macro: void IHP (bool e, Macro h, Text p)
Macro: void IGHP (bool e, bool g, Macro h, Text p)
Macro: void N (bool e)
Macro: void NG (bool e, bool g)
Macro: void NH (bool e, Macro h)
Macro: void NP (bool e, Text p)
Macro: void NGH (bool e, bool g, Macro h)
Macro: void NGP (bool e, bool g, Text p)
Macro: void NHP (bool e, Macro h, Text p)
Macro: void NGHP (bool e, bool g, Macro h, Text p)

We also provide support for referring to previous values of variables in postconditions. The ID macro is used to create variables to save the old state in. The IS and ISG macros are to set these values.

Macro: void ID (Text decln)
Macro: void IS (Text assignment)
Macro: void ISG (Text decln, bool g)

For example:

void ex(int &r) {
  ID(int oldr = r); /* save parameter */
  g(r);
  I(oldr == r); /* check r is unchanged */
  while(more()) {
    IS(oldr = r); /* assign r to oldr */
    h(r);
    I(oldr == r * r);
  }
}

DI.h: debugger based invariant checking

This implements the debugger based invariant checking code. The first two macros are the normal user interface; the remainder are used for configuring the behaviour on failure, etc. Note that these macros have no effect unless you run your program under the debugger and read in the commands generated by the `nana' command.

Macro: void DI (bool exprn)
The exprn should always be true if the program is working. If it is true then nothing happens otherwise the code given by `DI_DEFAULT_HANDLER' will be called which by default prints a message and dies just like `assert.h'.

The checking using DI can be enabled and disabled by using the DI_LEVEL and DI_DEFAULT_GUARD macros. See the definitions below for these macros for further details.

Note that exprn should have no side-effects(6) since disabling the checking shouldn't change your programs behaviour.

Macro: void DN (bool exprn)
The opposite of `DI', i.e. the expression must never ever be true if the program is working properly. It is equivelant to I(!(e)) and exists as piece of syntactic sugar which is helpful for complicated boolean expressions.

Macro: int DI_LEVEL
The `DI_LEVEL' macro is used to globally enable and disable checking, in particular it can take on one of three values:

0
Disable all checking. Regardless of anything else no code will be generated for DI, DN, etc.
1
Enable checking only if the corresponding guard condition is true. The guard condition can be used to enable and disable checking at compile and run time.
2
Enable all checking regardless of guard conditions, etc.

DI_LEVEL defaults to 1.

Macro: bool DI_DEFAULT_GUARD
The DI_DEFAULT_GUARD is used to selectively enable or disable checking at compile or run time.

DI_DEFAULT_GUARD defaults to TRUE, i.e. always enabled.

A user would typically define DI_DEFAULT_GUARD to be global or local variable which is used to turn checking on or off at run--time. For example:

#define DI_DEFAULT_GUARD (i_guard)

extern int i_guard;

Macro: text DI_DEFAULT_PARAMS
This is passed off to the DI_DEFAULT_HANDLER and defaults to nothing, it is just some text and is intended to pass failure codes (e.g. IEH303) or requests (e.g. HW_DEAD) information off to the handler.

DI_DEFAULT_PARAMS defaults to nothing.

Macro: void DI_DEFAULT_HANDLER (char *exprn, char *file, int line, param)

When an error is detected the DI_DEFAULT_HANDLER will be called to handle the error. The arguments are:

exprn
A string representation of the expression that has failed, e.g. "I(i>=0)".
file
The file that this error occurred in, i.e. __FILE__.
line
The line number for the error, i.e. __LINE__.
param
An optional parameter which can be passed across which defaults to DI_DEFAULT_PARAMS. This can be used to pass failure codes or other information from the checking code to the handler.

Macro: void DI_MAKE_VALID_BREAKPOINT (exprn e)
This macro is used to ensure that a breakpoint can be set at the location we are checking using DI, etc. It defaults to asm("nop") and can be redefined by the user.

Macro: void DI (bool e)
Macro: void DIG (bool e, bool g)
Macro: void DIH (bool e, Macro h)
Macro: void DIP (bool e, Text p)
Macro: void DIGH (bool e, bool g, Macro h)
Macro: void DIGP (bool e, bool g, Text p)
Macro: void DIHP (bool e, Macro h, Text p)
Macro: void DIGHP (bool e, bool g, Macro h, Text p)
Macro: void DN (bool e)
Macro: void DNG (bool e, bool g)
Macro: void DNH (bool e, Macro h)
Macro: void DNP (bool e, Text p)
Macro: void DNGH (bool e, bool g, Macro h)
Macro: void DNGP (bool e, bool g, Text p)
Macro: void DNHP (bool e, Macro h, Text p)
Macro: void DNGHP (bool e, bool g, Macro h, Text p)

All of these macros are used to individually override the default values defined above. Normally these macros would be used in a system wide header file to define macros appropriate for the application.

Macro: void DS (e)
Macro: void DSG (e, g)
These macros are used to assign values to convenience variables in the debugger. Convenience variables are dynamically typed, global in scope and initialised to 0. They start with a single $ and can be used be used for saving the state of program or for counting events. The `DS' macro executes e under the same rules as DI. The `DSG' macro executes e only if the the expression g is true.

Note that `DS' and `DSG' can also be used for modifying C variables and calling functions.

L.h: support for printf style logging

These routines are used to provide logging functions. Messages can be divided into classes and separately enabled and disabled.

Macro: void L (args...)
Used to log a message in a similar way to printf.

Defaults to a using fprintf on stderr.

Macro: void LG (bool guard, args...)
Macro: void LH (function handler, args...)
Macro: void LP (text param, args...)
Macro: void LGP (bool guard, text param, args...)
Macro: void LHP (function handler, text param, args...)
Macro: void LGHP (bool guard, function handler, text param, args...)
And all of the special functions.

The macros such as `L' depend on the GNU CC variable number of arguments to macros extension. If you wish to compile your code on other systems you might wish to use the following variations on `L', etc.

Macro: void VL ((args...))
Macro: void VLG ((bool guard, args...))
Macro: void VLH ((function handler, args...))
Macro: void VLP ((text param, args...))
Macro: void VLGP ((bool guard, text param, args...))
Macro: void VLHP ((function handler, text param, args...))
Macro: void VLGHP ((bool guard, function handler, text param, args...))
Each of these macros calls the corresponding function from the previous group, i.e. by default `VLG' is the same as a call to `LG'. If you define `WITHOUT_NANA' all these macros are translated to `/* empty */'.

Thus you can have nana under GCC whilst the code is still portable to other compilers. However debugging information will not be available on other platforms.

Note: the argument list is surrounded by two sets of brackets. For example:

   VL(("haze in darwin = %d\n", 3.4));

Macro: void L_LEVEL
Used to enable and disable logging independently of guard expressions.

2
Always print message
1
Print message only if the guard expression is true.
0
Never print any messages.

Defaults to 1.

Macro: text L_DEFAULT_HANDLER
The default handler for printing which is simply the name of the logging function or macro.

Defaults to fprintf

Macro: bool L_DEFAULT_GUARD
The default guard condition for logging.

Defaults to TRUE.

Macro: text L_DEFAULT_PARAMS
The default parameter passed off to the logging function or macro.

Defaults to stderr

Macro: void L_SHOW_TIME
If defined then display the time in front of each message.

Macro: char* L_SHOW_TIME_FORMAT
A format string for the time stamp in the log. By default it prints the time out in seconds.

Macro: value L_SHOW_TIME_NOW
The name of a function that returns the time for the time stamp. This defaults to the `now' function from `now.h'.

L_buffer.h: a circular buffer for logging.

A traditional embedded systems trick is to log messages to a circular buffer in core. This has the following benefits:

  1. Speed -- writing to a in core buffer is much faster than spitting out messages to a file on disk. It is often fast enough to leave at least most of the messages in the final product.
  2. Field debugging -- what the ... was the user doing before the system crashed. Oh lets ask them, I'm sure they'll give us a good problem report.

Type: struct L_BUFFER
Used to define buffer variables, it is similar to `FILE*' type in `stdio.h'. To create an instance use `L_buffer_create'.

Function: L_BUFFER* L_buffer_create (size_t size)
Function: L_BUFFER* L_buffer_delete (L_BUFFER *b)
These are used to create or delete a buffer which can contain size characters.

  L_BUFFER *lbuffer;

  lbuffer = L_buffer_create(32*1024); /* create a 32K buffer */
  ...;
  L_buffer_delete(lbuffer); /* and delete it after use */

Function: void L_buffer_wraparound (L_BUFFER *b, int w)
A buffer created by `L_buffer_create' is set up so that the new messages will overwrite the older messages in the buffer. If you wish to disable this overwriting, e.g. to keep the first 32K bytes of your system startup messages you should use `L_buffer_wraparound'. For example:

  L_BUFFER *lb = L_buffer_create(32*1024);
  L_buffer_wraparound(lb, 0); /* disable wraparound */

Function: void L_buffer_printf (L_BUFFER *b, const char *fmt, ...)
Function: void L_buffer_puts (L_BUFFER *b, const char *str)
Function: void L_buffer_putchar (L_BUFFER *b, char ch)
These are the routines which do that actual printing to the buffer.

  L_buffer_printf(lbuffer, "U: user input %c\n", c);
  L_buffer_puts(lbuffer, "warning: its too hot");
  L_buffer_putchar(lbuffer, '*');

Note: a null pointer passed to the `L_buffer_puts' function prints as `(null)'. (7)

Function: void L_buffer_clear (L_BUFFER *b)
Clear the log, i.e. remove all messages and start again.

Function: void L_buffer_dump (L_BUFFER *b, FILE *fp)
Dump the contents of the log *b to the file descriptor *fp. Typically *fp would be `stderr'.

Note that this does not change the contents of the buffer. This is important since we may have a hardware or software problem part of the way through the dump operation and you don't want to loose anything.

To reset the buffer after a successful dump use `L_buffer_clear'.

The output of `L_buffer_dump' consists of a starting message followed by the contents of the log. If a character in the log is not printable we print it out in hex on a line by itself.

* L_buffer_dump =
log message
and another
* non-printable character 0x1
more log messages
* end of dump

You also need to be able to integrate these functions into your design. See `examples/ott.c' for a complicated example. Here we will provide a simplified version which implements a new logging macro called `LFAST' which does a `printf' to the `log_buffer'. If you want to have all messages going to a `L_BUFFER' then you can redefine `L_DEFAULT_HANDLER'.

/* project.h - the project wide include file */

#include <nana.h>
#include <L_buffer.h>

/* LFAST(char *, ...) - log a message to the log_buffer */
/*     ##f translates as the rest of the arguments to LFAST */

#define LFAST(f...) LHP(L_buffer_printf,log_buffer,##f)

extern L_BUFFER *log_buffer; /* the log buffer */

The main program merely creates the log_buffer and eventually calls `L_buffer_dump' to print out the buffer when the system dies.

/* main.c - initialise the system and start things */

#include <project.h>

L_BUFFER *log_buffer;

main() {
  log_buffer = L_buffer_create(16000);
  if(log_buffer == NULL) { /* not enough store */
    ...
  }
  LFAST("system starting at %f\n", now());
  ...;
}

void fatal_error() { /* called on fatal errors */
  FILE *f = fopen("project.errors","w");
  L_buffer_dump(b, stderr); /* print log to stderr */
  L_buffer_dump(b, f); /* print log to file */
}

L_times.h: recording events and times.

This component is used to record events and times with a lower time and space overhead than the `L_buffer.h' component. Instead of using a `printf' style string we simply record the time and a pointer to a string identifying the event in a circular buffer.

Note 0: the string arguments should not be modified after a call since we record pointers to the strings rather than the strings themselves.

Note 1: there is no printf style formatting, e.g. `%d' in this package.

Type: struct L_TIMES
Used to define buffers, it is similar to `FILE*' type in `stdio.h'. To create an instance use `L_times_create'.

Function: L_TIMES* L_times_create (int size)
Function: L_TIMES* L_times_delete (L_BUFFER *b)
These are used to create or delete a buffer which can contain size messages.

Function: void L_times_wraparound (L_TIMES *b, int w)
A buffer created by `L_times_create' is set up so that the new messages will overwrite the oldest messages in the buffer. If you wish to disable this overwriting, e.g. to keep the first few messages messages you could use `L_times_wraparound(b,0)'.

Function: void L_times_add (L_BUFFER *b, char *m, NANA_TIME t)
Add an event identified by message m at time t to b. The type NANA_TIME defaults to `double'.

Function: void L_times_dump (L_TIMES *b, FILE *fd)
Dump the contents of the buffer out.

Function: void L_times_clear (L_TIMES *b)
Clear all the messages from b.

DL.h: support for printf style logging

These routines are used to provide logging functions. Messages can be divided into classes and separately enabled and disabled.

Macro: void DL (args...)
Used to log a message.

Defaults to a using fprintf on stderr.

Macro: void DLG (bool guard, args...)
Macro: void DLH (function handler, args...)
Macro: void DLP (text param, args...)
Macro: void DLGP (bool guard, text param, args...)
Macro: void DLHP (function handler, args...)
Macro: void DLGHP (bool guard, function handler, args...)
And all of the special functions.

The macros such as `DL' depend on the GNU CC variable number of arguments to macros extension. If you wish to compile your code on other systems you might wish to use the following variations on `DL', etc.

Macro: void VDL ((args...))
Macro: void VDLG ((bool guard, args...))
Macro: void VDLH ((function handler, args...))
Macro: void VDLP ((text param, args...))
Macro: void VDLGP ((bool guard, text param, args...))
Macro: void VDLHP ((function handler, args...))
Macro: void VDLGHP ((bool guard, function handler, args...))
Each of these macros calls the corresponding function from the previous group, i.e. by default `VDL' is equivelant to a call to `DL'. If `WITHOUT_NANA' is defined then the call too `VDL' is equivelant to `/* empty */'.

Thus you can have debugging under GCC whilst the code is still portable to other compilers. However debugging information will not be available on other platforms.

Note: the argument list is surrounded by two sets of brackets. For example:

   VDL(("haze in darwin = %d\n", 3.4));

Macro: int DL_LEVEL
Used to enable and disable logging independently of guard expressions.

2
Always print message
1
Print message only if the guard expression is true.
0
Never print any messages.

Defaults to 1.

Macro: text DL_DEFAULT_HANDLER
The default handler for printing which is simply the name of the printing function.

Defaults to fprintf

Macro: bool DL_DEFAULT_GUARD

Defaults to TRUE.

Macro: text DL_DEFAULT_PARAMS
Defaults to stderr

Macro: flag DL_SHOW_TIME
Each message can be given an individual time stamp by defining DL_SHOW_TIME. This causes the _L_gettime routine to be called before each message which generates the timestamp. A default version is provided by the nana library.

GDB.h: sending plain gdb commands to the debugger

`GDB.h' provides macros for generating user specified commands in the output of the `nana' command. They are not included by default in the `nana.h' file.

Macro: void GDB (command)
Emit a single line command when running this file through `nana'. Note that each line must be passed off separately to the `GDB' macro.

This could be used to set debugger options or to define procedures inside `gdb', e.g.

  GDB(define checkstack);
  GDB(  if 0 <= n && n <= 10);
  GDB(    print "stack ok");
  GDB(  else);
  GDB(    print "stack corrupted");
  GDB(  end);
  GDB(end);

Macro: void GDBCALL (command)
Causes a single gdb command to be executed whenever control passes through this line of code. After the users command is executed control automatically returns to the program.

  GDBCALL(set memory_check = 1)

These macros could used for instrumenting code or setting up test harnesses, e.g.

GDB(set $siocall = 0);
GDB(set $sioerr = 0);

void sio_driver() {
  GDBCALL(set $siocall++)
  if(SIO_REQ & 0x010) {
    GDBCALL(set $sioerr++);
    ...
  }
}

Q.h: support for quantifiers

`Q.h' provides support for the quantifiers of predicate logic. For example to check that all elements in a data structure have some property we would use universal (forall, upside down A) quantification. To check that one or more values in a data structure have some property we would use existential (exists, back the front E) quantification. For example:

  /* all values in a[] must be between 0 and 10 */
  I(A(int i = 0, i < n_array, i++, 0 <= a[i] && a[i] <= 10));

  /* there exists a value in linked list l which is smaller than 10 */
  I(E(node *p = l, p != NULL, p = p->next, p->data <= 10));

The first three arguments to `A' and `E' are similar to a C `for' loop which iterates over the values we wish to check. The final argument is the expression that must be true.

The only minor difference from the C `for' loop is that variables may be declared at the start of the loop, even if you are using C rather than C++ which already supports this.(8)

The `Q.h' macros can also be nested and used anywhere a boolean value is required. For example:

  if(A(int i = 0, i < MAXX, i++,
       A(int j = 0, j < MAXY, j++,
         m[i][j] == (i == j ? 1 : 0)))) {
        /* identity matrix, i.e. all 0's except for 1's on */
        /* the diagonal */
        ...
  } else {
        /* not an identity matrix */
        ...
  }

The results from these macros can also be combined using boolean operations, e.g.

  /* the values in a[i]  are either ALL positive or ALL negative */
  I(A(int i = 0, i < MAX, i++, a[i] >= 0)
    ||
    A(int i = 0, i < MAX, i++, a[i] < 0));

Portability: note the macros in this file require the GNU CC/C++ statement expression extension of GCC to work. If your not using GNU CC then for now you are out of luck. At some time in the future we may implement a method which will work for standard C++, standard C is a bit of a challenge.

Portability: unfortunately these macros do not for the `DI' and `DL' macros since the statement expression extension has not been implemented in GDB.

Macro: bool A (init,condition,next,exprn)
For all values generated by `for(int;condition;next)' the exprn must be true.
  I(A(int i = 0, i < MAX, i++, a[i] >= 0)); /* all a[i] are +ve */

Macro: bool E (init,condition,next,exprn)
There exists at least one value for exprn generated by `for (int;condition;next)' which is true.

  /* one or more a[i] >= 0 */
  I(E(int i = 0, i < MAX, i++, a[i] >= 0));

Macro: long C (init,condition,next,exprn)
Returns the number of times the exprn is true over the values generated by `for(int;condition;next)'.

  /* 3 elements of a[] are +ve */
  I(C(int i = 0, i < MAX, i++, a[i] >= 0) == 3);

Macro: bool E1 (init,condition,next,exprn)
There exists only one value generated by `for(int;condition;next)' for which the exprn is true.

  /* a single elements of a[] is +ve */
  I(E1(int i = 0, i < MAX, i++, a[i] >= 0));

Macro: typeof(exprn) S (init,condition,next,exprn)
Sum the values generated by exprn for all values given by `for(int;condition;next)'. The type of the value returned is given by the type of the exprn.(9)

  /* sum of a[] is 10 */
  I(S(int i = 0, i < MAX, i++, a[i]) == 10);

  /* sum of all +ve numbers in a[] is 10 */
  I(S(int i = 0, i < MAX, i++, a[i] >= 0 ? a[i] : 0) == 10);

Macro: typeof(exprn) P (init,condition,next,exprn)
Returns the product of the values generated by exprn for all values given by `for(int;condition;next)'. The type returned is the type of the expression.

  /* product of all the values in a[] is 10 */
  I(P(int i = 0, i < MAX, i++, a[i]) == 10);

  /* a = x^y i.e. x*x..*x y times */
  I(P(int i = 0, i < y, i++, x) == a);

Qstl.h: quantifiers for STL containers.

The Standard Template Library (STL) is a library for C++ that makes extensive use of templates to implement the standard container classes and much more. Each of the container classes provides an interface to iterate over all the objects in the container, e.g.

// MAP is an associate array from location(lat,long) onto the name.
typedef map<location,string,locationlt> MAP;

void print_map_names(MAP& m) { // print out all the names in the map
  for(MAP::iterator i = m.begin(); i != m.end(); ++i) {
    cout << (*i).second << "\n";
  }
}

`Qstl.h' provides the same facilities as `Q.h' but uses the standard STL iterator protocol shown above. The names in `Qstl.h' are generated by appending a `O' (O not zero!) to the names in `Q.h'. In particular:

Macro: bool AO (name,container,predicate)
For all values in the container class the predicate must be true. The predicate refers to individual values using name. See the STL documentation for more details. Another way of putting this is forall name in container the predicate must be true.

  map<int,char *,ltint> m;
  // all keys (or indexes) into m are positive
  I(AO(i, m, (*i).first >= 0));

Macro: bool EO (name,container,predicate)
There exists one or more values in the container class for which the predicate is true.

  map<int,char,ltint> m;

  // one or more characters in m are '$'
  I(EO(i, m, (*i).second == '$'));

Macro: bool E1O (name,container,predicate)
There exists one value in the container for which the predicate is true.

  map<int,char,ltint> m;

  // one characters in m is a '$'
  I(E1O(i, m, (*i).second == '$'));

Macro: int CO (name,container,predicate)
Returns the number of times the predicate was true for all values in the container.

  map<int,char,ltint> m;
  int nalpha;
  // count the number of alphabetic chars in the map
  nalpha = CO(i, m, isalpha((*i).second));

Macro: typeof(exprn) SO (name,container,exprn)
Sum the exprn for all values in the container.

  map<int,float,ltint> m;
  float sum;
  // sum all the values in m
  sum = SO(i, m, (*i).second);

Macro: typeof(exprn) PO (name,container,exprn)
Take the product of the exprn for all values in the container.

  map<int,float,ltint> m;
  float product;
  // multiply all the values in m
  product = PO(i, m, (*i).second);

now.h: measuring time

The `now.h' file provides some simple time measurement routines. It is not included in `nana.h' so you must include this file separately.

It uses the `gettimeofday' system call and has an accuracy of between 1us and 10ms depending on the operating system and hardware configuration.

See the IPM package if you require better measurement tools.(10)

Function: double now ()
Returns the time in seconds since the beginning of time as defined by your system. If you call `now_reset' the time will start again at 0.

Function: double now_reset ()
Reset the times returned by `now' to 0.

Function: double now_delta (double *dp)
Returns the elapsed time between *dp and now(). It then sets *dp to now, thus giving a delta time between particular events.

  t = now();
  for(;;) {
    ...; /* code that must finish in 50ms */
    I(now_delta(&t) <= 0.050);
  }

eiffel.h: eiffel type assertions

Eiffel is a very nice language which provides the assertion checking facilities of nana inside the language itself. The `eiffel.h' library is intended to provide a similar setup to Eiffel in the C++ language. It is a pretty poor emulation, but it is hopefully better than nothing.

Assertion checking is controlled by the EIFFEL_CHECK variable which can take on any of the following values:

CHECK_NO
Disable all checking.
CHECK_REQUIRE
Check the preconditions for each method.
CHECK_ENSURE
And also check the postconditions.
CHECK_INVARIANT
And also check the class invariant before and after each method is called. The programmer should provide a class method called `invariant' which returns `true' if the object is consistent, `false' otherwise.
CHECK_LOOP
And also check the loop invariants.
CHECK_ALL
And also check any assertions using the `CHECK' instruction.

A typical compile flag to the compile might be:

% g++ -c -DEIFFEL_CHECK=CHECK_ALL play.cc

And then we have the actual assertion macros.

Macro: void REQUIRE (exprn)
Called at the beginning of each method. This checks the precondition to a method and the class invariant.

Macro: void ENSURE (exprn)
Called at the end of each method. This checks the postcondition to a method and the class invariant.

Macro: void INVARIANT (exprn)
Used to check a loop invariant.

Macro: void CHECK (exprn)
Used for any other inline assertions.

And finally a small example:

#include <eiffel.h>

class example {
  int nobjects;
  map<location,string,locationlt> layer;
public:
  bool invariant();
  void changeit(location l);
};

bool example::invariant() {
  return AO(i,layer,valid_location((*i).first)) &&
         nobjects >= 0;
}

void example::changeit(string n, location l) {
  REQUIRE(E1O(i,layer,(*i).second == n));
  ...;
  while(..) {
    INVARIANT(...);
    ...
    INVARIANT(...);
  }
  ...
  CHECK(x == 5);
  ...
  ENSURE(layer[l] == n);
}

Note that the invariant checking macro `example::invariant' is called automatically on function entry/exit using the `REQUIRE' and `ENSURE' macros.

assert.h: a drop in replacement for assert.h

A drop in replacement for `assert.h' is provided in the `src' directory. It is not installed by default. If you wish to use it then you need to copy it to your include directory by hand.

This might be of use if you are already using `assert.h' and wish to save some code space since the nana implementation is more space efficient.

Calls to `assert' are translated to calls to `I' and can be disabled by defining `NDEBUG'.

calls.h: checking/printing many objects/facts.

The `calls' module implements a simple list of functions which can be modified and executed at run-time. It is similar in spirit to the ANSI C `atexit' function. It is intended to be used for:

  • Checking the consistency of the components in your system. For example each module could register a self checking function which uses the rest of the nana library. All of these functions would then be called using `calls.h' to check that the entire system is consistent.
  • Printing out the state of your program in a readable format.

Type: typedef FUNC
A pointer to a `void' function which takes a single `void*' argument. The `void *' argument is intended to be used to pass information such as arguments or pointers to objects (e.g. `this' in C++). All of the checking/printing functions must be of this type, e.g.

void print_object(void *f) {
  ...;
}

Type: struct CALL
This structure represents a single call to a function, i.e. a function pointer (`FUNC') and the `void*' argument.

    CALL *head = 0;

Function: void calls_add (CALL **head, FUNC fp, *arg)
Adds a call to function `fp' with argument `arg' to the list pointed to by `head'.

    CALL *global_checks = 0;

    calls_add(&global_checks,complex_ok,(void *)x);

Function: void calls_exec (CALL **head, FUNC fp, void *arg)
Execute all/some of the calls in the list given by `head'. The arguments `fp' and `arg' must both match for each individual call. The null pointer (`0') matches anything whilst any other value requires an exact match between the `CALL' and the arguments to `calls_exec'. For example:

calls_exec(&l,0,0); /* execute all functions in l  */
calls_exec(&l,complex_print,0); /* calls complex_print(*) in l */
calls_exec(&l,0,(void*) &b); /* calls *(&b) in l */
calls_exec(&l,f,(void*) &b); /* calls f(&b) in l */

Function: void calls_delete (CALL **head, FUNC fp, void *arg)
Delete all/some of the calls in the list given by `head'. The arguments `fp' and `arg' must both match for each individual call. The null pointer (`0') matches anything whilst any other value requires an exact match between the `CALL' and the arguments to `calls_delete'. For example:

calls_delete(&l,0,0); /* delete all functions in l  */
calls_delete(&l,complex_print,0); /* delete complex_print(*) in l */
calls_delete(&l,0,(void*) &b); /* delete *(&b) in l */
calls_delete(&l,f,(void*) &b); /* delete f(&b) in l */

Note: that calls are added to the head of the list rather than the tail. This means that the most recently added call will be executed first (as in a stack).

Using Nana

This chapter is intended to provide some hopefully useful examples of Nana. If any of the users of this library would be so kind as to contribute a section on their usage I would be obliged.

This section is under development

Simplest example

As a nice simple, indeed trivial example consider the following:

  1. Include `nana.h' in your project wide include file.
  2. Use `I' to check invariants in your code. In particular all functions or methods should be required to check their pre and post conditions.
  3. Use `DL' to print debugging messages in your code. This means that debugging messages only occur when you run the program under the debugger.(11)

Syslog

`syslog' is a comprehensive logging system written by Eric Allman which is available on most UNIX systems. It provides facilities for sorting messages by source or severity and mechanisms for sending messages off to files, terminals or other machines. See chapter 12 of the "UNIX System Administration Handbook (2nd Edition)" by Nemeth, Snyder, Seebass and Hein for an excellent tutorial on `syslog'.

The rules used by `syslog' are normally defined in `/etc/syslog.conf'. Each line specifies the destination for messages with particular sources and priorities. For example:

# log mail messages at priority info to mailinfo
mail.info /var/log/mailinfo
# log all ftp information to syslog on a remote machine
ftp.* @remote-machine.cs.ntu.edu.au
# all critical errors to console
*.crit   /dev/console

To use `syslog' we merely redefine the default handlers and parameter values for `nana'. For example:

#include <syslog.h>
#define L_DEFAULT_HANDLER syslog /* replaces fprintf(3) by syslog(3) */
#define L_DEFAULT_PARAMS LOG_USER /* default priority for syslog info */
#include <nana.h>

int main() {
     openlog("nana", /* identifier for these log messages */
        LOG_PID, /* also log the process id */
        LOG_DAEMON /* facility */
     );

     L("temperature is falling to %d", 35); /* logged at LOG_USER priority */
     LP(LOG_CRIT, "the snow is falling in Darwin"); /* LOG_CRIT message */

     closelog();
     return 0;
}

This program results in the following addition to `/var/adm/messages':

Jun 12 16:04:46 chingiz nana[2671]: the temperature is falling to 35
Jun 12 16:04:46 chingiz nana[2671]: the snow is falling in Darwin

In addition the `LOG_CRIT' message about snow falling in Darwin is sent to the console for immediate action.

Note: `syslog' normally uses `UDP' for its network communications and that `UDP' does not guarantee delivery.

GNU Programs: how to avoid nana sometimes

Imagine you(12) are building a GNU program. Ideally it should run on systems without any other software including GCC, GDB and even Nana.

To achieve this noble goal you can provide your configure script with a `--without-nana' (13) flag which then `#define's' `WITHOUT_NANA'. You should also use the `VL' macro rather than `L' macro since `L' takes a variable number of arguments and will break non GNU C preprocessors.

int half(int n) {
  /* Don't use L(...) since it takes a variable number of args! */
  VL(("hello world = %d\n", 10)); /* Note the doubled (( */
  ...;
}

Embedded Systems: testing non-deterministic systems.

One of the uses (in fact the original use) for nana is in the testing of non-deterministic systems. These systems behave in a different way each time they are run because of timing or measurement noise. Thus you can't just `diff' the results against a known good run since they run differently each time.

Instead you can use a series of programs which execute over a the results of the program and check that the behaviour meets the specification automatically.

Realtime Systems

Assertions for the timing behaviour of you system can be done in nana nicely. You might also consider using an instruction level simulator such as PSIM and use the `cycles' variable to test realtime constraints.

A database

Ah databases, business boffins using assertions. It would nice to get a real example for this one!

Program Visualisation: pretty pictures

One nice way to use `L', `DL', etc is to punt off the messages off to a program which displays the information. You would use the `L_DEFAULT_PARAM' argument to send commands off to a pipe with gnuplot or TCL/TK interpreter running at the end.

For a small example of this, see `tcl/status.c'.

FAQ

This chapter is intended to answer some general questions about the usage of Nana. Most of the material (perhaps) has been presented elsewhere, my apologies for repeating myself.

  1. Can I use GNU Nana in a commercial product? See the license details in the file `COPYING'. In summary GNU Nana is Free software which has been released under a license that allows commercial use provided the copyright is maintained. It is not under the GPL.
  2. How do you completely disable assertion checking? Set the `I_LEVEL' command to `0' using `-D' or `#define' before including `nana.h'.
  3. How do I find out about future releases? Subscribe to the nana mailing list by using the `make subscribe' target in the nana root directory.
  4. Where do I send bug reports, suggestions, etc? `nana-bug@it.ntu.edu.au' -- bug archive `nana@it.ntu.edu.au' -- mailing list `pjm@cs.ntu.edu.au' -- the author

Future work

As usual, there is more work to be done than time to do it in. Workers or test pilots are invited to apply for the following tasks which may get down in the fullness of time minister. I'm particularly interested in which projects people think are worthwhile (or rubbish).

  1. Ada support - pre 1.00 versions of nana provided support for Ada. Adding a full version of nana into the GNATS compiler would probably be useful, particularly the real time part.
  2. FORTRAN support.
  3. Message browsing (`emacs/fess.el') - a very prototypical mode for browsing message logs is distributed with nana. Features include hiding/showing lines by regular expression or predicate. If someone who knows what they are doing rewrites this that would be a good thing. Or perhaps a modified version of `less' would be useful.
  4. Program Visualisation (`tcl/status.c') - another prototype which uses a small TCL/TK library and nana logging to generate some nice pictures showing the behaviour of the program. For example the history of variables over time can be recorded, graphs drawn and long message logs kept. A new version of this has been created and may be released shortly.
  5. Eiffel shortform program - the shortform of an Eiffel program contains the function signatures (arguments, etc) together with the assertions (pre/post conditions). An extension could perhaps be put in a program such as `DOC++' or `cxref' which extracts the nana assertions.
  6. Automated Testing - combine nana logs with a workbench that lets you verify properties of the logs using programs `gawk' or the `PRECC' (LL infinity version of YACC). This technique has been used on industrial strength products quite successfully.
  7. GNU standards - perhaps it would be worthwhile to set up a prototype for checking and logging in GNU tools.
  8. Extend GDB(1) so that we can support `Q.h' style quantifiers in `DI.h' expressions. Basically we need to add a restricted form of the statement value expression to GDB.
  9. Support for other (particularly ANSI only) compilers.

Index

Jump to: 0 - 1 - 2 - a - c - d - e - f - g - i - l - n - p - q - r - s - t - v

0

  • 0, 0, 0, 0

    • 1

  • 1, 1, 1, 1

    • 2

  • 2, 2, 2, 2

    • a

  • A, A
  • abort()
  • ALWAYS_INCLUDE_MALLOC
  • AO
  • asm("hlt")
  • asm("stp")

    • c

  • C, C
  • calls_add
  • calls_delete
  • calls_exec
  • CHECK
  • CHECK_ALL
  • CHECK_ENSURE
  • CHECK_INVARIANT
  • CHECK_LOOP
  • CHECK_NO
  • CHECK_REQUIRE
  • CO

    • d

  • DI, DI
  • DI.h
  • DI_DEFAULT_GUARD
  • DI_DEFAULT_HANDLER
  • DI_DEFAULT_PARAMS
  • DI_LEVEL
  • DI_MAKE_VALID_BREAKPOINT, DI_MAKE_VALID_BREAKPOINT
  • DIG
  • DIGH
  • DIGHP
  • DIGP
  • DIH
  • DIHP
  • DIP
  • DL
  • DL.h
  • DL_DEFAULT_GUARD
  • DL_DEFAULT_HANDLER
  • DL_DEFAULT_PARAMS
  • DL_LEVEL
  • DL_MAKE_VALID_BREAKPOINT
  • DL_SHOW_TIME
  • DLG
  • DLGHP
  • DLGP
  • DLH
  • DLHP
  • DLP
  • DN, DN
  • DNG
  • DNGH
  • DNGHP
  • DNGP
  • DNH
  • DNHP
  • DNP
  • DS
  • DSG

    • e

  • E, E
  • E1, E1
  • E1O
  • ENSURE
  • EO
  • exprn, exprn

    • f

  • file, file

    • g

  • gcc-2.7.2
  • GDB
  • gdb-4.16
  • GDB.h
  • GDBCALL
  • gmake

    • i

  • I, I
  • I.h
  • I_DEFAULT_GUARD
  • I_DEFAULT_HANDLER, I_DEFAULT_HANDLER
  • I_DEFAULT_PARAMS
  • I_LEVEL
  • ID
  • IG
  • IGH
  • IGHP
  • IGP
  • IH
  • IHP
  • INVARIANT
  • IP
  • IS
  • ISG

    • l

  • L
  • L.h
  • L_BUFFER
  • L_buffer_clear
  • L_buffer_create
  • L_buffer_delete
  • L_buffer_dump
  • L_buffer_printf
  • L_buffer_putchar
  • L_buffer_puts
  • L_buffer_wraparound
  • L_DEFAULT_GUARD
  • L_DEFAULT_HANDLER
  • L_DEFAULT_PARAMS
  • L_LEVEL
  • L_SHOW_TIME
  • L_SHOW_TIME_FORMAT
  • L_SHOW_TIME_NOW
  • L_TIMES
  • L_times_add
  • L_times_clear
  • L_times_create
  • L_times_delete
  • L_times_dump
  • L_times_wraparound
  • LG
  • LGHP
  • LGP
  • LH
  • LHP
  • line, line
  • LP

    • n

  • N, N
  • nana-clg
  • nana-run
  • nana-trace
  • NG
  • NGH
  • NGHP
  • NGP
  • NH
  • NHP
  • now
  • now_delta
  • now_reset
  • NP

    • p

  • P, P
  • param, param
  • PO

    • q

  • Q.h

    • r

  • REQUIRE
  • restart()

    • s

  • S, S
  • SO
  • struct

    • t

  • typedef

    • v

  • VDL
  • VDLG
  • VDLGHP
  • VDLGP
  • VDLH
  • VDLHP
  • VDLP
  • VL
  • VLG
  • VLGHP
  • VLGP
  • VLH
  • VLHP
  • VLP

    • Footnotes

    (1)

    Which is unfortunately quite uncommon in the authors experience.

    (2)

    And about 60 reset cycles where the machine went off into hyperspace

    (3)

    This allows variable number of arguments to C preprocessor macros.

    (4)

    If you don't want a core dump then look at stopping the core dumps with ulimit rather than changing the handler.

    (5)

    Side-effects include such operations as input/output or assignments, e.g. `x++'

    (6)

    Side-effects include operations like input/output or assignments.

    (7)

    This was suggested by Phil Blecker.

    (8)

    ANSI C does not allow variable declarations at the beginning of loops unlike C++. The `Q.h' macros get around this by starting each loop with a new scope.

    (9)

    This uses yet another GNU CC extension, however since we are already using statement expressions we might as well use `typeof' as well.

    (10)

    In the fullness of time, we may integrate these routines in here.

    (11)

    Of course you also need to use the gdb commands generated by the `nana' command, perhaps using `nana-clg'

    (12)

    Gordon Matzigkeit contributed some of the ideas presented here and raised this problem.

    (13)

    Or add a `--with-nana' flag to configure that does the opposite.

    This document was generated on 6 November 1998 using the texi2html translator version 1.52.


nano Command Manual

GNU nano

a small and friendly text editor.

version 0.9.99pre3

Chris Allegretta

Table of Contents

  • Introduction
    • Overview
    • Command Line Options
  • Editor Basics
    • Entering Text
    • Special Functions
    • The Titlebar
    • The Statusbar
    • Shortcut Lists
  • Online Help
  • Feature Toggles
  • The File Browser
  • Pico Compatibility
  • Building and Configure Options

Introduction

GNU nano is a small and friendly text editor. Besides basic text editing, nano offers many extra features like an interactive search and replace, goto line number, auto-indentation, feature toggles, internationalization support, and filename tab completion.

Overview

nano [GNU long option] [option] +LINE [ file ... ]

The original goal for nano was a complete bug-for-bug compatible emulation of Pico, but consistency is now a slightly higher priority. There is a flag to implement (nearly) complete Pico emulation, (option -p or GNU long option --pico). This can also be toggled from within nano by typing Meta-P. See section Pico Compatibility, for more info.

Email bug reports to nano@nano-editor.org.

Command Line Options

nano takes the following options from the command line:

-T [num, --tabsize=[num]
Set the displayed tab length to [num] columns.
-R, --regexp
Turns on regular expression search and search/replace.
-V, --version
Print the version number and copyright and quit.
-c, --const
Constantly display the cursor posititon and line number on the statusbar.
-h, --help
Print the usage and exit.
-i, --autoindent
Automatically indent new lines to the same number of spaces and tabs as the previous line.
-k, --cut
Makes ^K cut from the current cursor position to the end of the current line.
-l, --nofollow
When writing files, if the given file is a symbolic link it is removed and a new file is created.
-m, --mouse
Enables the use of the mouse to select text (currently only useful for running under the X window system).
-p, --pico
Emulate Pico as closely as possible, sacrificing consistency for correct emulation. See section Pico Compatibility, for more info.
-r [#cols], --fill=[#cols].
Wrap lines at column #cols. By default this is the width of the screen, less eight.
-s [prog], --speller=[prog]
Invoke [prog] as the spell checker. By default, nano uses its own interactive spell checker that requires the spell program be installed on your system.
-t, --tempfile
Do not ask whether or not to save the current contents of the file when exiting, assume yes. This is most useful when using nano as the composer of a mailer program. @anchor{Expert Mode}
-x, --nohelp
In Expert Mode, the Shortcut Lists will not appear at the bottom of the screen. This affects the location of the statusbar as well, as in Expert Mode it is located at the very bottom of the editor. Note: When accesing the help system, Expert Mode is temporarily disabled to display the help system navigation keys.
-v, --view
Do not allow the contents of the file to be altered. Note that this flag should NOT be used in place of correct file permissions to implement a read-only file.
-w, --nowrap
Do not wrap long lines at any length. This option overrides any value for -r.
-z, --suspend
Enable suspend ability of nano using the system's suspend keystroke (usually ^Z).
+LINE
Start at line number LINE instead of the default of line 1.

Editor Basics

Entering Text

All key sequences in nano are entered using the keyboard. nano is a "modeless" editor, all keys with the exception of Control and Meta key sequences will enter text into the file being edited.

Special Functions

Special functions use the Control key (displayed in the help and shotcut lists as ^) or the Meta key (displayed as M).

  • Control key sequences are entered by holding down the Control key and pressing the desired letter.
  • Meta key sequences can be entered in a number of possible ways: Pressing the Escape key, then releasing it and pressing the desired key, or holding down the Alt key while pressing the desired key. This varies from keyboard to keyboard, and certain commercial operating systems "swallow" the Alt key so that it never reaches the application. If your operating system does this, you should use the Escape key to generate Meta key sequences.

The Titlebar

The titlebar is the line displayed at the top of the editor. There are three sections: left, center and right. The section on the left displays the version of nano being used. The center section displays the current file name, or "New Buffer" if the file has not yet been named. The section on the right will display "Modified" if the file has been modified since it ws last saved or opened.

Special modes: When nano is in "File browser" mode, the center section will display the current directory instead of the filename. See section The File Browser.

The Statusbar

The statusbar is located three lines from the bottom of the screen (or the bottom line in Expert Mode. @xref{Expert Mode}, for more info.

The Statusbar shows important and informational messages. Any error messages that occur from using the editor will appear on the statusbar. Any questions that are asked of the user will be asked on the statusbar, and any user input (serch strings, file names, etc) will be input on the statusbar.

Shortcut Lists

The Shorcut Lists are the two lines at the bottom of the screen which show some of the more commonly used functions in the editor. The exact functions which are displayed depend on whether Pico Compatibility Mode mode is enabled. See section Pico Compatibility, for more info.

Online Help

The online help system in nano is available by pressing ^G. It is fairly self explanatory, documenting the various parts of the editor and available keystrokes. Navigation is via the ^Y (Page Up) and ^V (Page Down) keys. ^X exits the help system.

Feature Toggles

Toggles allow you to change certain aspects of the editor that would normally be done via command line flags. They are invoked via certain Meta key sequenced. See section Special Functions, for more info. The following toggles are available:

Constant Update Toggle (Meta-C)
toggles the -c (--const) command line flag.
Regular Expressions Toggle (Meta-E)
toggles the -R (--regexp) command line flag.
AutoIndent Toggle (Meta-I)
toggles the -i (--autoindent) command line flag.
Cut To End Toggle (Meta-K)
toggles the -k (--cut) command line flag.
Cut To End Toggle (Meta-M)
toggles the -m (--mouse) command line flag.
Pico Mode Toggle (Meta-P)
toggles the -p (--pico) command line flag. See section Pico Compatibility, for more info.
AutoWrap Toggle (Meta-W)
toggles the -w (--nowrap) command line flag.
Expert/Nohelp Toggle (Meta-X)
toggles the -x (--nohelp) command line flag.
Suspend Toggle (Meta-Z)
toggles the -z (--suspend) command line flag.

The File Browser

When reading or writilg files, pressing ^T will invoke the file browser. Here, one can navigate directories in a graphical manner in order to find the desired file.

Basic movement in the file browser is accomplished with he arrow keys and page up/down. The behavior of the enter (or 's') key varies by what is currently selected. If the currently selected object is a directory, the file browser will enter and display the contects of the directory. If the object is a file, this filename and path are copied to the statusbar and the file browser is exited.

Pico Compatibility

Nano does not completely emulate Pico by default. The following differences apply to the default mode and Pico Compatibility mode:

Displayed Shortcuts
By default, the following shortcuts are displayed in the Shortcut Lists: ^G ^O ^\ ^Y ^K ^C
^X ^R ^W ^V ^U ^T Related functions are listed above or below each other by default. The Justify function is not listed, instead the "Replace" function is displayed. Also, he "Read File" and "WriteOut" functions are aligned for consistency. In Pico Compatibility mode, the default Pico shortcuts are displayed: ^G ^O ^R ^Y ^K ^C
^X ^J ^W ^V ^U ^T
Previous String Text
By default, previously entered string for a function (search string, file name) will be placed on the statusbar, and is editable. This is done so there is consistency across all functions. For example: even if there is a previous replace string, it can always be deleted if one wishes to perform an empty string replace. In Pico Compatibility Mode, the previously entered text in a search or replace will appear in brackets, and is not editable. It is not a simple matter to do an empty string replace when a previous replace string exists, for example. When writing a file, the previous filename will be displayed in the editable text portion of the editor.
Interactive Replace and Spell Checker
It is worth noting that the nano replace function is interactive, i.e. it does not stop after one search string is found and automatically replace it. The nano implementation will stop at each search string found and query whether to replace this instance or not. The internal spell checker operates similarly. Note that these is no way to force these functions to behave in the Pico fashion.

Building and Configure Options

Building nano from source is fairly straightforward if you are familiar with compiling programs with autoconf support:

tar xvfz nano-x.y.z.tar.gz (where x.y.z is the version of nano) cd nano-x.y.z/ ./configure make make install

if you are looking to optimize nano for size, you may want to consider the following command line options:

--disable-tabcomp
Disable the tab completion code when reading or writing files.
--disable-justify
Disable the justify (^J)/unjustify (^U) functions in the editor.
--disable-speller
Disables spell checker abillity.
--disable-help
Disables the help function (^G). Disabling this option maks the binary much smaller, but makes it difficult for new users to learn more than very basic things about using the editor.
--disable-browser
Disables the mini file browser (^O) when reading or writing files.
--enable-tiny
This options disables all the above. It also disables some of the larger internals of the editor, like the marker code (^^) and the cut to line (-k) option which it depends on to work properly. It also disables the function toggles and mouse support.

This document was generated on 14 March 2001 using texi2html 1.56k.


Parted User's Manual

the GNU Parted Manual

GNU Parted, version 1.6.1, 8 May 2002

Andrew Clausen clausen@gnu.org">clausen@gnu.org
Richard M. Kreuter kreuter@anduril.rutgers.edu">kreuter@anduril.rutgers.edu

Table of Contents

  • 1. Introduction
    • 1.1 Overview of GNU Parted
    • 1.2 Software Required for the use of Parted
    • 1.3 Platforms on which GNU Parted runs
    • 1.4 Terms of distribution for GNU Parted
    • 1.5 Building GNU Parted
    • 1.6 Using a Parted Boot Disk
  • 2. Using Parted
    • 2.1 Partitioning Concepts
    • 2.2 Using GNU Parted
    • 2.3 Command Line Options
    • 2.4 Parted Session Commands
      • 2.4.1 check
      • 2.4.2 cp
      • 2.4.3 help
      • 2.4.4 mklabel
      • 2.4.5 mkfs
      • 2.4.6 mkpart
      • 2.4.7 mkpartfs
      • 2.4.8 move
      • 2.4.9 name
      • 2.4.10 print
      • 2.4.11 quit
      • 2.4.12 rescue
      • 2.4.13 resize
      • 2.4.14 rm
      • 2.4.15 select
      • 2.4.16 set
    • 2.5 Example Parted Sessions
      • 2.5.1 Example: Growing a partition into unused space
      • 2.5.2 Example: Resizing an ext2 partition on a crowded disk.
  • 3. BIOSes and Firmware
    • 3.1 The PC BIOS
      • 3.1.1 Using Parted with CHS mode BIOS
      • 3.1.2 Converting from CHS to LBA mode BIOS
      • 3.1.3 Using Parted with LBA mode BIOS
    • 3.2 OpenFirmware of the Apple Macintosh
      • 3.2.1 Old World Macintosh OpenFirmware
      • 3.2.2 New World Macintosh OpenFirmware
    • 3.3 The PC98 BIOS
    • 3.4 SGI / MIPS Firmware
  • 4. Boot Loaders
    • 4.1 LILO: a bootloader for the Linux kernel
    • 4.2 GRUB: The GNU GRand Unified Bootloader
    • 4.3 Legacy Microsoft Operating System Bootloaders
    • 4.4 The Microsoft Windows NT Bootloader
    • 4.5 The Microsoft Windows 2000 Bootloader
    • 4.6 Quik: a bootloader for Macintosh PowerPC's
    • 4.7 Yaboot: a boot loader for Macintosh PowerPC's
  • 5. Operating Systems
    • 5.1 Disk labels used by GNU/Linux and FreeBSD
    • 5.2 Disk labels supported by Microsoft systems and OS/2
    • 5.3 Macintosh Operating System Disk Label Support
  • 6. File Systems supported by Parted
    • 6.1 File Systems Supported by GNU Parted
    • 6.2 GNU Parted and the Second Extended Filesystem
    • 6.3 Legacy Microsoft File System Support
      • 6.3.1 MS DriveSpace partitions
        • 6.3.1.1 Growing a DriveSpace partition
        • 6.3.1.2 Shrinking a DriveSpace partition
        • 6.3.1.3 Copying a DriveSpace partition
    • 6.4 Reiserfs Journalling File System
  • 7. LVM and RAID
    • 7.1 Logical Volume Manager and Redundant Arrays of Inexpensive Disks
    • 7.2 Creating RAID or LVM partitions
    • 7.3 Manipulating a File System on a RAID or LVM volume
      • 7.3.1 Creating a File System on an LVM or RAID Virtual Device
      • 7.3.2 Resizing a File System on an LVM or RAID Virtual Device
      • 7.3.3 Copying a File System from an LVM or RAID Virtual Device to a Partition
      • 7.3.4 Copying a File System to an LVM or RAID Virtual Device
  • 8. Disk Imaging
  • 9. Related Software and Info
  • A. Copying This Manual
    • A.1 GNU Free Documentation License
      • A.1.1 ADDENDUM: How to use this License for your documents
  • B. This manual's history
  • Index

1. Introduction

1.1 Overview of GNU Parted

GNU Parted is a program for creating, destroying, resizing, checking and copying partitions, and the file systems on them.

This is useful for creating space for new operating systems, reorganising disk usage, copying data between hard disks, and "disk imaging" -- replicating installations over many computers.

This documentation assumes knowledge of partitions and file systems. If you want to learn more about these, the Partition mini-HOWTO is recommended reading. It is probably included with your distribution, or it is available at

http://www.linuxdoc.org/HOWTO/mini/Partition/index.html

GNU Parted was designed to minimize the chance of data loss. For example, it was designed to avoid data loss during interruptions (like power failure) and performs many safety checks. However there could be bugs in Parted, so you should back up your important files.

The GNU Parted homepage is www.gnu.org/software/parted. It can be downloaded from ftp.gnu.org/gnu/parted.

The Parted mailing list is parted@gnu.org. To subscribe, write to bug-parted-request@gnu.org with `subscribe' in the subject. Subscription information and archives are available at:

http://mail.gnu.org/mailman/listinfo/bug-parted

Please send bug reports to bug-parted@gnu.org. When sending bug reports, please include the version of GNU Parted. If the bug is related to partition tables, then please include the output from these commands:

# fdisk /dev/hda -l
# fdisk /dev/hda
Command (m for help): p
Command (m for help): x
Extended command (m for help): p

Feel free to ask for help on this list -- just check that your question isn't answered here first. If you don't understand the documentation, please tell us, so we can explain it better. General philosophy is: if you need to ask for help, then something needs to be fixed so you (and others) don't need to ask for help.

Also, we'd love to hear your ideas :-)

1.2 Software Required for the use of Parted

GNU Parted depends on the following packages to build correctly:

  • libuuid, part of the e2fsprogs package. If you don't have this, you can get it from: http://web.mit.edu/tytso/www/linux/e2fsprogs.html If you want to compile Parted and e2fsprogs, note that you will need to make install and make install-libs e2fsprogs.
  • GNU Readline (optional), available from ftp://ftp.gnu.org/gnu/readline If you are compiling Parted, and you don't have readline, you can disable Parted's readline support with the --disable-readline option for @command{configure}.
  • GNU gettext (or compatible software) for compilation, if internationalisation support is desired. ftp://ftp.gnu.org/gnu/gettext
  • libreiserfs, if you want reiserfs support: http://reiserfs.linux.kiev.ua Note that parted will automatically detect libreiserfs at runtime, and enable reiserfs support. libreiserfs is new, and hasn't been widely tested yet.

1.3 Platforms on which GNU Parted runs

Hopefully, this list will grow a lot. If you do not have one of these platforms (Linux at the moment!), then you can use a boot disk. See section 1.6 Using a Parted Boot Disk.

GNU/Linux
Linux versions 2.0 and up, on Alpha, x86 PCs, PC98, Macintosh PowerPC, Sun hardware.
GNU/Hurd
Experimental support.

GNU libc 2.1 or higher is required. You can probably use older versions by using the `--disable-nls' option. See section 1.5 Building GNU Parted. (Note: I think we have now dropped this requirement. TODO: check if libc 2.0 works!)

1.4 Terms of distribution for GNU Parted

GNU Parted is free software, covered by the GNU General Public License Version 2. This should have been included with the Parted distribution, in the COPYING file. If not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Libparted is considered part of GNU Parted. It is covered by the GNU General Public License. It is NOT released under the GNU Lesser General Public License (LGPL).

1.5 Building GNU Parted

If you want to compile GNU Parted, this is generally done with:

$ ./configure
$ make

However, there are a few options for @command{configure}:

--without-readline
turns off use of readline. This is useful for making rescue disks, etc., where few libraries are available.
--disable-debug
don't include assertions
--disable-dynamic-loading
disables dynamic loading of some libraries (only libreiserfs for now, although we hope to expand this). Dynamic loading is useful because it allows you to reuse libparted shared libraries even when you don't know when if some libraries will be available. It has a small overhead (mainly linking with libdl), so it may be useful to disable it on bootdisks if you don't need the flexibility.
--disable-fs
disable all filesystem support
--disable-nls
turns off native language support. This is useful for use with old versions of glibc, or a trimmed down version of glibc suitable for rescue disks.
--disable-shared
turns off shared libraries. This may be necessary for use with old versions of GNU libc, if you get a compile error about a "spilled register". Also useful for boot/rescue disks.
--disable-Werror
ignore warning messages in compilation
--enable-all-static
builds the Parted binary as a fully static binary. This is convienient for boot disks, because you don't need to install any libraries on the boot disk (although, other programs may require them...) Note: you will also want to run strip(1).
--enable-discover-only
support only reading/probing
--enable-mtrace
enable malloc() debugging
--enable-read-only
disable writing (for debugging)

1.6 Using a Parted Boot Disk

If you want run Parted on a machine without GNU/Linux installed, or you want to resize a root or boot partition, you will need to use a boot disk.

A boot disk image is available from:

ftp://ftp.gnu.org/gnu/parted/bootdisk/partboot.img

To actually create the boot disk, the disk image must be written to a floppy disk. In GNU/Linux, this can be done with

# dd if=partboot.img of=/dev/fd0 bs=1440k

Or use RAWRITE.EXE under DOS.

Unfortunately, the boot disk doesn't support a very wide range of hardware. If your hard disk isn't supported, then you will need to make your own boot disk. You can copy the parted binary from the parted bootdisk onto another disk, or try other boot disks, or make your own. You may find mkparted useful, which is a shell script to make custom parted boot disks. It is available at:

ftp://ftp.tux.org/pub/people/kent-robotti/mkparted

To copy parted from the boot disk onto another disk:

  1. Boot from the Parted boot disk.
  2. Insert another ext2-formatted floppy disk. If it isn't formated, you can create a file system with, for example:
    $ parted /dev/fd0 mklabel loop mkpartfs primary ext2 0 1.4
  3. Mount the floppy disk, e.g.,
    $ mount -t ext2 /dev/fd0 /mnt/floppy
  4. Copy `/sbin/parted' to the floppy, e.g.,
    $ cp /sbin/parted /mnt/floppy
  5. Copy `/lib/*' to the floppy, e.g.,
    $ cp /lib/* /mnt/floppy
  6. Unmount the floppy, e.g.,
    $ umount /mnt/floppy
  7. Find a boot disk that does support your hard disk. (Hint: try looking for rescue disks from various distributions on big mirror sites)
  8. Boot off your rescue disk. Mount the disk you copied Parted onto.
  9. Run Parted. For example,
    # cd /mnt/floppy
# LD_LIBRARY_PATH=. ./parted

2. Using Parted

2.1 Partitioning Concepts

Unfortunately, partitioning your disk is rather complicated. This is because there are interactions between many different systems that need to be taken into consideration:

  • The BIOS or firmware - the program that is built into a ROM chip inside your computer, that does memory checks, etc. You can not (easily) change programs in this system. Examples of BIOS or firmware programs: AmiBIOS, Award, Phoenix, OpenFirmware. You will only have one of these programs.
  • The boot loader - the program that allows you to select which operating system you want to use, and loads that operating system. Examples: LILO, GRUB, Yaboot, Quik. You may have more than one boot loader installed, especially if you have more than one type of operating system installed.
  • The operating system (at the moment, this must be GNU/Linux) that runs Parted, and the other operating systems that you use.
  • The file system types - the way the data stored on partitions. Examples of these are: ext2, fat32, hfs, reiserfs. You will often have partitions of of different file system types.

Parted suppports many combinations of BIOS, boot loader, operating system, and file systems, and will support more in the future. To further understand the roles of each, please see section 3. BIOSes and Firmware, section 4. Boot Loaders, section 5. Operating Systems, and section 6. File Systems supported by Parted.

This chapter describes how to use Parted, which is largely the same, no matter what systems you are using. You should read this chapter, then each of chapters on BIOSes, boot loaders, operating systems, and file systems. However, you only need to read the sections that are relevant to you. For example, if you are only using LILO as your boot loader, then you only need to read the introduction, and section 4.1 LILO: a bootloader for the Linux kernel.

2.2 Using GNU Parted

Parted has two modes: command line and interactive. Parted should always be started with:

# parted device

where device is the hard disk device to edit. (If you're lazy, Parted will attempt to guess which device you want.)

In command line mode, this is followed by one or more commands. For example:

# parted /dev/sda resize 1 52 104 mkfs 2 fat16

Options (like --help) can only be specified on the command line.

In interactive mode, commands are entered one at a time at a prompt, and modify the disk immediately. For example:

(parted) resize 1 52.0005 104.5
(parted) mkfs 2 fat16

Unambiguous abbreviations are allowed. For example, you can type "p" instead of "print", and "re" instead of "resize". Commands can be typed in, either in English, or your native language (if your language has been translated). This may create ambiguities.

Also note that you can specify decimal places in the numbers corresponding to partition locations (in megabytes). Negative numbers count from the end of the disk, with "-0" being the end of the disk.

If you don't give a parameter to a command, Parted will ask you for it. For example:

(parted) resize 1
Start? 0
End? 400

Parted will always warn you before doing something that is potentially dangerous, unless it's something that's obviosuly dangerous (i.e. rm, mklabel, mkfs) For example, if you attempt to shrink a partition "too much" (i.e. by more than the free space available), Parted will automatically resize to the minimum it can without losing data. If this minimum is significantly different, it will warn you that it's doing something significanlty different to what you asked. Since many partitioning systems have complicated constraints, Parted will usually do something slightly different to what you asked. (For example, create a partitiong starting at 10.352, not 10.4)

2.3 Command Line Options

When invoked from the command line, parted supports the following syntax:

# parted [option] device [command [argument]]

Available options and commands follow. For detailed explanations of the use of parted commands, see section 2.4 Parted Session Commands. Options begin with a hyphen, commands do not:

Options:

`-h'
`--help'
display a help message
`-i'
`--interactive'
where necessary, prompt for user intervention
`-s'
`--script'
never prompt for user intervention
`-v'
`--version'
display the version

2.4 Parted Session Commands

GNU Parted provides the following commands:

2.4.1 check

Command: check minor

Checks if the file system on partition minor has any errors.

Example:

(parted) check 1

Check the file system on partition 1.

2.4.2 cp

Command: cp [from-device] from-minor to-minor

Copies the file system on the partition from-minor to partition to-minor, deleting the original contents of the destination partition.

An optional device parameter, from-device can be given, which specifies which device the source partition is on.

Supported file systems:

  • ext2, ext3 (provided the destination partition is larger than the source partition)
  • fat16, fat32
  • linux-swap (equivalent to mkswap on destination partition)
  • reiserfs (if libreiserfs is installed)

Example:

(parted) cp /dev/hdb 2 3

Copy partition 2 of `/dev/hdb' (i.e. `/dev/hdb2') to partition on 3, on the device Parted was loaded with, destroying the original contents of partition 3.

2.4.3 help

Command: help [command]

Prints general help, or help on command.

Example:

(parted) help resize

Print help for the resize command.

2.4.4 mklabel

Command: mklabel label-type

Creates a new disk label, of type label-type. The new disk label will have no partitions. This command (normally) won't technically destroy your data, but it will make it will make it basically unusable, and you will need to use the rescue command (see section 9. Related Software and Info) to recover any partitions. Gpart only works for msdos disk labels (AFAIK), but is much better than parted at recovering partitions. Parted works on all partition tables. (1)

label-type must be one of these supported disk labels:

  • bsd
  • loop (raw disk access)
  • gpt
  • mac
  • msdos
  • pc98
  • sun

Example:

(parted) mklabel msdos

Create an msdos style disklabel.

2.4.5 mkfs

Command: mkfs minor fs-type

Makes a file system fs-type on partition minor, destroying all data that resides on that partition.

Supported file systems:

  • ext2
  • mips
  • fat16
  • fat32
  • linux-swap
  • reiserfs (if libreiserfs is installed)

Example:

(parted) mkfs 2 fat32

Make a fat32 file system on partition 2.

2.4.6 mkpart

Command: mkpart part-type [fs-type] start end

Creates a new partition, without creating a new file system on that partition. This is useful for creating partitions for file systems (or LVM, etc.) that Parted doesn't support. You may specify a file system type, to set the appropriate partition code in the partition table for the new partition. fs-type is required for data partitions (i.e., non-extended partitions). start and end are the offset from the beginning of the disk, that is, the "distance" from the start of the disk.

part-type is one of: primary, extended, logical. Extended and logical are only used for msdos and mips disk labels.

fs-type must be on of these supported file systems:

  • ext2
  • fat32
  • fat16
  • HFS
  • linux-swap
  • NTFS
  • reiserfs
  • ufs

Example:

(parted) mkpart logical 0.0 692.1

Create a logical partition that will contain an ext2 filesystem. The partition will start at the beginning of the disk, and end 692.1 megabytes into the disk.

2.4.7 mkpartfs

Command: mkpartfs part-type fs-type start end

Creates a new partition of type part-type with a new file system of type fs-type on it. The new partition will start start megabytes, and end end megabytes from the beginning of the disk. Do not use this command to recover a deleted partition (use mkpart instead).

part-type is one of: primary, extended, logical. Extended and logical are only used for msdos and mips disk labels.

fs-type must be one of these supported file systems:

  • ext2
  • fat32
  • fat16
  • linux-swap
  • reiserfs (if libreiserfs is installed)

Example:

(parted) mkpartfs logical ext2 440 670

Make a logical partition and write an ext2 file system, starting 440 megabytes and ending 670 megabytes from the beginning of the disk.

2.4.8 move

Command: move minor start [end]

Moves partition on the disk, by moving its beginning to start. Note: move never changes the minor number.

If no end is given, the partition's size remains the same.

Supported file systems:

  • ext2, ext3 (provided the destination partition is larger than the source partition)
  • fat32
  • fat16
  • linux-swap
  • reiserfs (if libreiserfs is installed)

Example:

(parted) move 2 150

Move partition with minor number 2 so that it begins 150 megabytes from the start of the disk.

2.4.9 name

Command: name minor name

Sets the name for the partition minor (Mac and PC98 only). The name can be placed in quotes.

Example:

(parted) name 2 'Secret Documents'

Set the name of partition 2 to `Secret Documents'.

2.4.10 print

Command: print

Displays the partition table on the device parted is editing.

Example:

(parted) print
Disk geometry for /dev/hda: 0.000-2445.679 megabytes
Disk label type: msdos
Minor    Start       End     Type      Filesystem  Flags
1          0.031    945.000  primary   FAT         boot, lba
2        945.000   2358.562  primary   ext2
3       2358.562   2445.187  primary   linux-swap

2.4.11 quit

Command: quit

Quits Parted.

It is only after Parted exits that the Linux kernel knows about the changes Parted has made to the disks. However, the changes caused by typing your commands will probably be made to the disk immediately after typing a command. However, Linux's cache, and the disk's hardware cache may delay this.

2.4.12 rescue

Command: rescue start end
rescue lost partitions between start and end

Looks between start and end for file system signatures. If one is found, it will ask you if you want to create a partition for it. This is useful if you accidently deleted a partition with parted's rm command, for example.

Unfortunately, there is no progress meter, because it's hard (but possible FIXME!) to predict how long it's going to take. If Parted finds nothing, it will spend a lot of time looking (which is a bug that should be fixed). However, in the example below, it instanteneously recovered the partition.

Example:

(parted) print
Disk geometry for /dev/hdc: 0.000-8063.507 megabytes
Disk label type: msdos
Minor    Start       End     Type      Filesystem  Flags
1          0.031   8056.032  primary   ext3
(parted) rm
Partition number? 1
(parted) print
Disk geometry for /dev/hdc: 0.000-8063.507 megabytes
Disk label type: msdos
Minor    Start       End     Type      Filesystem  Flags

OUCH! We deleted our ext3 partition!!! Parted comes to the rescue...

(parted) rescue
Start? 0.0005?
End? 8063.5073?
Information: A ext3 primary partition was found at 0.031Mb ->
8056.030Mb.  Do you want to add it to the partition table?
Yes/No/Cancel? y
(parted) print
Disk geometry for /dev/hdc: 0.000-8063.507 megabytes
Disk label type: msdos
Minor    Start       End     Type      Filesystem  Flags
1          0.031   8056.032  primary   ext3

It's back! :)

2.4.13 resize

Command: resize minor start end

Resizes the partition with number minor. The partition will start start from the beginning of the disk, and end end from the beginning of the disk. resize never changes the minor number. Extended partitions can be resized, so long as the new extended partition completely contains all logical partitions.

Note that Parted does not require a file system to be "defragged" (Parted can safely move data around if necessary). It's a waste of time defragging. Don't bother!

Supported file systems:

  • ext2, ext3 - restriction: the new start must be the same as the old start.
  • fat16, fat32
  • linux-swap
  • reiserfs (if libreiserfs is installed)

Example:

(parted) resize 3 200 850

Resize partition 3, so that it begins 200 megabytes and ends 850 megabytes from the beginning of the disk.

2.4.14 rm

Command: rm minor

Removes the partition with number minor. If you accidently delete a partition with this command, use mkpart (not mkpartfs) to recover it. Also, you can use the gpart program (see section 9. Related Software and Info) to recover damaged disk labels.

Note for msdos disk labels: if you delete a logical partition, all logical partitions with a larger minor number will be renumbered. For example, if you delete a logical partition with a minor number of 6, then logical partitions that were number 7, 8 and 9 would be renumbered to 6, 7 and 8 respectively. This means, for example, that you have to update `/etc/fstab' on GNU/Linux systems.

Example:

(parted) rm 3

Remove partition 3.

2.4.15 select

Command: select device

Selects the device, device, for Parted to edit. The device will usually be a Linux hard disk device, or, if direct access to a file system is required -- a partition, software RAID device, or LVM logical volume.

Example:

(parted) select /dev/hdb

Select `/dev/hdb' (the slave device on the first ide controller on Linux) as the device to edit.

2.4.16 set

Command: set minor flag state

Changes a flag on the partition with number minor. A flag can be either "on" or "off". Some or all of these flags will be available, depending on what disk label you are using:

`boot'
(Mac, MSDOS, PC98) - should be enabled if you want to boot off the partition. The semantics vary between disk labels. For MSDOS disk labels, only one partition can be bootable. If you are installing LILO on a partition (see section 4.1 LILO: a bootloader for the Linux kernel), then that partition must be bootable. For PC98 disk labels, all ext2 partitions must be bootable (this is enforced by Parted).
`lba'
(MSDOS) - this flag can be enabled, to tell MS DOS, MS Windows 9x and MS Windows ME based operating systems to use Linear (LBA) mode.
`root'
(Mac) - this flag should be enabled if the partition is the root device to be used by Linux.
`swap'
(Mac) - this flag should be enabled if the partition is the swap device to be used by Linux.
`hidden'
(MSDOS, PC98) - this flag can be enabled to hide partitions from Microsoft operating systems.
`raid'
(MSDOS) - this flag can be enabled to tell linux the partition is a software RAID partition See section 7. LVM and RAID.
`LVM'
(MSDOS) - this flag can be enabled to tell linux the partition is a physical volume.

The print command displays all enabled flags for each partition.

Example:

(parted) set 1 boot on

Set the `boot' flag on partition 1.

2.5 Example Parted Sessions

These examples attempt to cover the most common circumstances, with the exception of disk imaging, which is covered in section 8. Disk Imaging.

2.5.1 Example: Growing a partition into unused space

Suppose your disk layout looks like this:

(parted) print
Disk geometry for /dev/hda: 0.000-1000.000 megabytes
Disk label type: msdos
Minor    Start       End     Type      Filesystem  Flags
1          0.063    500.000  primary   ext2
2        500.000    625.000  primary   linux-swap

There is 375 Mb of free space at the end of the disk (after partition 2). Partition 1 has an ext2 file system, which is the root device. Partition 2 is a swap device.

Suppose you wanted to use the free space at the end of the disk for the file system on partition 1. You could do the following:

  1. These steps will modify both the root file system on partition 1, and the swap device on partition 2. Therefore, you shouldn't be using either partitions. You should probably use a Parted boot disk. See section 1.6 Using a Parted Boot Disk. From the boot disk, run Parted:
    # parted /dev/hda
  2. Remove partition 2 (the swap partition). Normally, you wouldn't want to delete a partition with data on it. However, a swap partition doesn't contain data when it isn't "swapped on" (mounted), so you can remove it, and create a replacement swap partition later.
    (parted) rm 2
  3. Create the new swap partition at the end of the disk:
    (parted) mkpartfs primary linux-swap 875 999.9
(parted) print
Disk geometry for /dev/hda: 0.000-1000.000 megabytes
Disk label type: msdos
Minor    Start       End     Type      Filesystem  Flags
1          0.063    500.000  primary   ext2
2        875.000   1000.000  primary   linux-swap
  4. Grow partition 1, into the adjacent free space:
    (parted) resize 1 0.063 874.9
    All done!
    (parted) print
Disk geometry for /dev/hda: 0.000-1000.000 megabytes
Disk label type: msdos
Minor    Start       End     Type      Filesystem  Flags
1          0.063    874.999  primary   ext2
2        875.000   1000.000  primary   linux-swap

2.5.2 Example: Resizing an ext2 partition on a crowded disk.

Suppose your disk layout looks like this:

(parted) print
Disk geometry for /dev/hda: 0-8063.5 megabytes
Disk label type: msdos
Minor   Start     End    Type            Filesystem     Flags
1          0.0     23.5  primary         ext2           boot
2         23.5   8056.0  extended
5         23.6   3545.6  logical         ext2
6       3545.6   7067.7  logical         ext2
7       7067.7   7326.5  logical         ext2
8       7326.5   7585.4  logical         ext2
9       7585.4   7844.2  logical         linux-swap

$ df -h
Filesystem            Size  Used Avail Use% Mounted on
/dev/hda8             251M   31M  207M  13% /
/dev/hda1              23M  2.4M   19M  11% /boot
/dev/hda5             3.4G  577M  2.7G  18% /usr
/dev/hda6             3.4G  289M  2.9G   9% /home
/dev/hda7             251M   12M  226M   5% /var

Suppose you wanted to increase the `/var' partition (`/dev/hda7') to 1GB, using some space from `/home' (`/dev/hda6').

To resize a partition with Parted, you use the resize command:

(parted) resize partition_number new start new end

new start must be the same as the old start for ext2 partitions (unfortunately). So this process is going to be rather complicated. It is possible, though. (2)

  1. Shrink the `/home' partition (`/dev/hda6') by 500MB:
    # parted /dev/hda
(parted) resize 6 3545.6 6200
  2. Make a new partition in its place. This is where `/var' will be, eventually. This new partition will be numbered 10.
    (parted) mkpartfs logical ext2 6200 7067.7
  3. Copy the old `/var' partition (`/dev/hda7') to the new one (`/dev/hda10').
    (parted) cp 7 10
  4. Delete the old `/var'.
    (parted) rm 7
    At this point: all logical partitions greater than 7 just changed number. So 8, 9 and 10 become 7, 8 and 9 respectively. This renumbering won't take place while any partitions are mounted on that disk (this will happen when you reboot). That's what that warning message is talking about. So you should never attempt to mount a file system touched by Parted (resized or created by Parted), before rebooting, if you get this message.
  5. Resize the new `/var' partition (now numbered 9), adding the space from the old `/var' partition:
    (parted) resize 9 6200 7326.5
(parted) quit
Warning: The kernel was unable to re-read the partition table on
/dev/hda (Device or resource busy).  This means Linux knows nothing
about any modifications you made.  You should reboot your computer
before doing anything with /dev/hda.
  6. Since the partition numbers have changed, `/etc/fstab' must be updated. This can be done before rebooting, because the root device wasn't touched by Parted. (If you want to use Parted to do something to the root device, you need to use the boot disk). If the old `/etc/fstab' looks like this:
    /dev/hda8      /            ext2    defaults        1 1
/dev/hda1      /boot        ext2    defaults        1 2
/dev/hda6      /home        ext2    grpquota,usrquota  0  2
/dev/cdrom     /mnt/cdrom   iso9660 noauto,owner,ro 0 0
/dev/hda5      /usr         ext2    defaults        1 2
/dev/hda7      /var         ext2    grpquota,usrquota  0  2
/dev/fd0       /mnt/floppy  auto    noauto,owner    0 0
none           /proc        proc    defaults        0 0
none           /dev/pts     devpts  gid=5,mode=620  0 0
/dev/hda9      swap         swap    defaults        0 0
    A few lines need to be changed:
    • `/var' is now /dev/hda9 (because we copied it to a new partition)
    • `/dev/hda8' (the root device) has been renumbered to `/dev/hda7'
    • `/dev/hda9' (the swap device) has been renumbered to `/dev/hda8'
    The new `/etc/fstab' looks like this:
    /dev/hda7      /            ext2    defaults        1 1
/dev/hda1      /boot        ext2    defaults        1 2
/dev/hda6      /home        ext2    grpquota,usrquota  0  2
/dev/cdrom     /mnt/cdrom   iso9660 noauto,owner,ro 0 0
/dev/hda5      /usr         ext2    defaults        1 2
/dev/hda9      /var         ext2    grpquota,usrquota  0  2
/dev/fd0       /mnt/floppy  auto    noauto,owner    0 0
none           /proc        proc    defaults        0 0
none           /dev/pts     devpts  gid=5,mode=620  0 0
/dev/hda8      swap         swap    defaults        0 0
  7. Reboot. That's it!

3. BIOSes and Firmware

"BIOS" (Basic Input/Output System) and "firmware" mean the same thing. However, on PC and PC98 based computers, the word BIOS is more common. On Apple Macintosh and Sun computers, the word "firmware" is more common. The BIOS or firmware program is built into a ROM chip inside your computer, that does memory checks, etc. You can not (easily) change this program. Since BIOSes today are generally compatible with BIOSes in use 20 years ago, these programs tend to have an antiquated design. Features have been added in counter-intuitive ways over the years, leading to overly complicated systems that cause a lot of confusion today.

3.1 The PC BIOS

There are a few popular PC BIOSes: AmiBIOS, Award, Phoenix, and others. They all work in a similar way. None of these BIOSes understand or know about partition tables. They affect partitioning indirectly.

The following occurs when your computer boots up:

  1. These BIOSes load the first bit of the boot loader program, stored on the MBR (Master Boot Record) on the hard disk.
  2. The BIOS executes the first bit of the boot loader.
  3. The boot loader program uses the BIOS to load the rest of itself.
  4. The boot loader uses the BIOS to load the operating system (or, perhaps another boot loader, in which case you go to step 2 again).
  5. The operating system may or may not use the BIOS to do normal file system access (Windows usually does, Linux or BSD do not).

Steps (3) to (5) involve programs communicating with the BIOS, to ask it to talk to the disks. There are two ways of talking to the BIOS to do this: by using CHS (Cylinders Heads and Sectors) or LBA (Linear Block Addressing). Older BIOSes will only support CHS. New BIOSes usually support both LBA and CHS, although CHS support may be phased out in the future. (CHS is generally considered to be a horrible legacy system.)

Steps (3) and (4), performed by the boot loader, will always use the same access method -- either always LBA or always CHS. In the case of the Windows boot loader, this is determined by the LBA flag on the Windows boot partition (see section 2.4.16 set for information about about flags). In the case of Linux, you will probably be using either LILO or GRUB as your boot loader. GRUB uses LBA if it is available, and CHS otherwise. LILO requires that you choose when you install it (with the linear, or lba32 options).

Step (5) - IO done by the operating system - only Windows does its IO through the BIOS. [We still don't know enough about the problems, but it seems Windows can have its own problems with CHS mode. People have told us about occassions where Windows corrupts its own file systems, etc. It's really hard for us to know what's going on. We strongly recommend you use LBA, if you can!]

So, there are 3 possible situations, which are all covered here:

  1. You are using CHS mode, and your BIOS only supports CHS mode.
  2. You are using CHS mode, and your BIOS supports both CHS and LBA. So, you want to convert from CHS mode to LBA mode As Soon As Possible TM.
  3. You are using LBA mode already.

3.1.1 Using Parted with CHS mode BIOS

Linux usually detects the BIOS geometry automatically. However, sometimes it gets it wrong. In this case, you should tell it yourself, by passing a parameter to Linux. For example, if Linux thinks your hard drive `/dev/hda' has geometry 256/64/63, but the BIOS setup program says the geometry is 512/32/63, then you would pass this parameter to Linux:

hda=512,32,63

Parameters are passed in different ways, depending what boot-loader you're using. You are probably using LILO. In this case, you add this line to `/etc/lilo.conf': (You then need to run @command{/sbin/lilo}, and reboot for the change to take effect)

append="hda=512,32,63"

Parted can usually detect if Linux has detected the incorrect geometry. However, it cannot do this if there are no partitions on the disk. In this case, you should check yourself. It is very important that you do this.

Sometimes, Parted will complain that the partitions aren't aligned to cylinder boundaries. Parted will give you the option to ignore. If you ignore, then Parted will do some tricks with your partition table. Linux will have no problems. DOS and Windows will have no problems if they are using LBA mode. If DOS/Windows is using CHS mode, then reinstalling the the boot loader (see section 4.3 Legacy Microsoft Operating System Bootloaders) should solve any problems - but switching to LBA mode is preferrable (see see section 3.1.2 Converting from CHS to LBA mode BIOS).

Partitions that are involved in the boot process must end before cylinder 1024, if CHS mode is being used. See the section on boot loaders to determine if a partition is involved in the boot process. The typical setup is to have a small Linux `/boot' partition, a Windows partition and then the Linux partition(s).

3.1.2 Converting from CHS to LBA mode BIOS

To make the Windows boot loader + operating system use LBA mode, just set the LBA flag on all FAT partitions section 2.4.16 set. You should have no problems. If you do have problems booting Windows, then reinstalling the Windows boot loader will fix it section 4.3 Legacy Microsoft Operating System Bootloaders.

Linux doesn't use the BIOS for IO. However, the boot loader (LILO or GRUB) may. GRUB automatically uses LBA, if it is available. LILO requires the "linear" or "lba32" option. So, if LILO still boots after changing `/etc/lilo.conf' reinstalling with @command{/sbin/lilo}, then everything's done! See section 4.1 LILO: a bootloader for the Linux kernel. (If you have problems, just revert back to CHS, by removing "linear" or "lba32", and reinstalling lilo from a boot disk.)

Now that you're using LBA, read on...

3.1.3 Using Parted with LBA mode BIOS

LBA solves all of CHS's problems. However, there is no reliable way for Linux or Parted to know that you're using LBA, so Parted may give you warnings about cylinders not being aligned, or the BIOS geometry being inconsistent, etc. You can ignore these messages if you are using LBA mode. (Old versions of Parted had problems, which have all been solved).

When your disk is in LBA mode, Parted (and most other programs) will say your CHS geometry is X/255/63 - unless you have switched from CHS to LBA.

3.2 OpenFirmware of the Apple Macintosh

There are two major version of the PowerMac's OpenFirmware - one used on "old world", and one on "new world" PowerMac. "New world" refers to coloured PowerPCs manufactured since 1999. They have significant differences. However, both understand partition maps.

Both require that the user choose exactly one partition to be the boot partition (the partition with the boot loader). However, they use different mechanisms to do this.

3.2.1 Old World Macintosh OpenFirmware

The partition chosen to boot is set by various boot loaders, like Quik. So, you shouldn't need to do anything. We could add support for this in Parted, if someone screams loudly enough...

3.2.2 New World Macintosh OpenFirmware

New world OpenFirmware requires the boot partition to be HFS and marked as a boot partition. It uses a different mechanism to be marked as the boot partition. This is controlled with Parted's "boot" flag. For example:

(parted) set 2 boot on

3.3 The PC98 BIOS

The PC98 BIOS allows you to mark any number of partitions as bootable. You can mark or unmark a partition as bootable with Parted's "boot" flag. For example:

(parted) set 2 boot off

3.4 SGI / MIPS Firmware

The SGI / MIPS firmware allows booting from special boot files, which are managed by the partition table. In Parted, these boot files are treated as logical partitions inside an extended partition.

For example:

Disk label type: mips
Minor    Start       End     Type      Filesystem  Name        Flags
9          0.000      2.732  extended
17         0.002      0.002  logical               sgilabel
18         0.003      1.162  logical               symmon
19         1.404      1.670  logical               sash
1          2.732   8555.212  primary   xfs                     root
2       8555.213   8682.270  primary                           swap

Partition 9 is the extended partition (volume header in SGI/MIPS terminology) where the boot files may lie. Partitions 17, 18 and 19 are the boot files. There names can be manipulated with parted's name command. Partitions 1 and 2 are normal partitions. They can't have names.

Note that Linux doesn't see the boot files as partitions (maybe it should?). So /dev/hda17 doesn't exist in Linux. You should use dvhtool(8) to manipulate boot files.

4. Boot Loaders

The boot loader is the program that allows you to select which operating system you want to use, and loads that operating system. You may have more than one boot loader installed, especially if you have more than one type of operating system installed. It is common for boot loaders to be able to load other boot loaders.

When resizing a partition, lots of data gets moved around. Many boot loaders don't understand the file system. They just remember where on the disk the required boot loader information lies. If this information is moved, they must be told where it has been moved. This is done by reinstalling the boot loader (i.e., re-running the installer program for the boot loader, which usually involves issuing a single command at the shell). Not all boot loaders require this.

4.1 LILO: a bootloader for the Linux kernel

LILO is a popular boot loader for x86. LILO's boot loader is usually installed with:

# /sbin/lilo

If you are using a boot disk, then you should do this instead: (where `/dev/hda1' should be replaced with your root device)

# mount /dev/hda1 /mnt
# chroot /mnt /sbin/lilo
# umount /dev/hda1

Old versions of LILO don't support LBA mode (see section 3.1 The PC BIOS). LBA mode is enabled with the lba32 or linear option, in `/etc/lilo.conf' (see the LILO documentation for more info).

If you use LBA mode, you should have no problems, as long as your BIOS supports LBA.

If you use CHS mode, then the partition with your `/boot' directory must finish before cylinder 1024. So, if you have a large disk (say, over 8 gigabytes), you should have a `/boot' partition near the start of your disk.

4.2 GRUB: The GNU GRand Unified Bootloader

GRUB is a relatively new boot loader, for x86. Depending on how GRUB is installed, it may understand the file system, or simply remember where the boot files are stored. It understands the file system if it's using "Stage1.5". If it's not using Stage1.5, or the partition number changes, then you need to reinstall Stage2 (please see the GRUB documentation). Otherwise, you don't need to do anything.

GRUB automatically detects if LBA is available, and will use it if it is available (equivalent to LILO's "lba32" option).

4.3 Legacy Microsoft Operating System Bootloaders

DOS and Windows require you to re-install the boot loader if you change the FAT type (FAT16 or FAT32) of the boot partition. Parted will warn you before attempting to do this. To re-install the boot loader, you can either create a boot disk, or use the boot CDROM. The boot disk method does not work with Windows ME.

  • BOOT DISK METHOD (DOS/Windows 9x)
    1. Create a Windows boot disk
      • Boot Windows. This implies you should make the boot disk before you use parted.
      • Right click on the floppy drive in Windows Explorer.
      • Click on "Format".
      • Mark "Copy system files".
      • Click on "Format".
      • Copy C:\WINDOWS\COMMAND\SYS.COM to A:\ Note: you might have called C:\WINDOWS something else, like C:\WIN98.
    2. Boot off the Windows boot disk, by leaving the boot disk in the floppy drive when booting. You may need to tell your BIOS to boot off the floppy.
    3. Type at the DOS prompt:
      A:\>sys c:
  • CDROM METHOD: (Windows 9x/ME)
    1. Insert the Windows CDROM, and boot from it. (Select "boot without CDROM support").
    2. Type:
      A:\>c:
C:\>cd \windows\command    (might be \win98\command, or similar)
C:\WINDOWS\COMMAND>sys c:
      That's all there is to it.

Also, DOS and Windows impose a few restrictions:

  • The boot partition should be selected with the "boot" flag. Only one boot partition can be selected (sometimes called the "active" partition). For example, to set partition 3 to be the boot partition, do:
    (parted) set 3 boot on
  • The MS DOS and MS Windows 9x/ME can only boot from the first FAT partition. That is, the FAT partition with the smallest minor number, that isn't hidden. Note that boot loaders like GRUB and LILO (and some BIOSes) can change this behaviour...
  • If you are using CHS addressing (rather than LBA addressing), then the boot partition start must be less than cylinder 1024. You can tell MS DOS to use (or not to use) LBA addressing, by enabling or disabling the LBA flag on the boot partition. For example, to enable the LBA flag on partition 2, do:
    (parted) set 2 lba on
    Note: LBA addressing is not supported in MS-DOS 6.22 and lower, as well as all versions of PC-DOS. Warning: some BIOSes won't enable LBA addressing, unless you enable it in the BIOS as well. If for some reason, Windows doesn't boot after changing this flag, this is probably the problem.
  • the "real" MS-DOS (i.e. up to version 6.22) and MS-DOS 7.0 (i.e. Windows 95/95a) don't know about FAT32. It's therefore possible to boot them from the second fat (FAT16 only, of course) partition, when the first fat partition is FAT32. Both have to be primary partitions, so you'll have to set the one you want to boot from as active partition.

4.4 The Microsoft Windows NT Bootloader

Windows NT can't read or boot from FAT32 partitions. Therefore, you should never convert FAT16 partitions to FAT32 partitions, if you want to use them with Windows NT.

4.5 The Microsoft Windows 2000 Bootloader

Windows 2000 require you to re-install the boot loader if you change the FAT type (FAT16 or FAT32) of the system partition. Parted will warn you before attempting to do this. To re-install the boot loader, do:

  1. Boot off the Windows 2000 CD.
  2. It will ask if you want to proceed installing. Hit Enter.
  3. It will then ask you if you want to install a new system, or Repair an existing system. Choose the later (by pressing "R").
  4. It will ask you if you want to do an automatic repair, or if you want to use the recovery console. Choose to use the recovery console.
  5. At the console, type:
    C:\>fixboot
    The system should boot successfully now.

The NT/2000 boot loader also needs:

  • its own boot sector code in a PRIMARY FAT12, FAT16 or NTFS partition (FAT32 possible with Windows 2000), which is called the "system partition". This partition should be marked with the "boot" flag in Parted.
  • the files NTLDR, BOOT.INI and NTDETECT.COM within the system partition. BOOT.INI holds the information about the physical location of the primary partition or logical drive where Windows NT was installed to, called the "boot partition". The boot partition and system partition may be located together in one primary partition.
  • optionally, the file NTBOOTDD.SYS within the system partition, which is the renamed disk driver for your SCSI or IDE controller, when this has no own BIOS (or its BIOS can't access large disks).
  • with MS Windows NT, the system partition should end before cylinder 1024, and must start before cylinder 1024. If it ends after cylinder 1024 and the files necessary to boot are moved past this border MS Windows NT won't start anymore!
  • both the boot and system partition may be resized, without the need for any other changes.
  • if the boot partition's number changes (i.e. its minor number), then the BOOT.INI has to be updated.

4.6 Quik: a bootloader for Macintosh PowerPC's

Quik is a popular boot loader for "Old World" Macintosh PowerPCs. You need to reinstall Quik if you resize an ext2 partition, with:

# /sbin/quik

4.7 Yaboot: a boot loader for Macintosh PowerPC's

Yaboot is a popular boot loader for "new world" Macintosh PowerPCs. ("New-world" refers to coloured PowerPCs manufactured since 1999.)

Yaboot needs its own boot strap partition that must be at least 800k. So, if you are installing GNU/Linux from scratch, you would do something like:

(parted) mklabel mac
(parted) print
Disk geometry for /dev/sda: 0.000-6149.882 megabytes
Disk label type: mac
Minor    Start       End     Filesystem  Name          Flags
1          0.000      0.031              Apple
(parted) mkpart primary hfs 0.032 1
(parted) print
Disk geometry for /dev/hdb: 0.000-6149.882 megabytes
Disk label type: mac
Minor    Start       End     Filesystem  Name          Flags
1          0.000      0.031              Apple
2          0.031      1.000
(parted) set 2 boot on
(parted) print
Disk geometry for /dev/hdb: 0.000-6149.882 megabytes
Disk label type: mac
Minor    Start       End     Filesystem  Name          Flags
1          0.000      0.031              Apple
2          0.031      1.000                            boot

You don't need to reinstall Yaboot after resizing a partition. Yaboot is installed with ybin section 9. Related Software and Info.

5. Operating Systems

Parted only runs under GNU/Linux and GNU/Hurd, at the moment. However, it can be used to resize partitions used by, or shared with other operating systems.

When you want to resize a file system, make sure it is not mounted. Parted can't resize mounted partitions (this may change in the future...).

If you modify the partition table on a disk with a partition mounted on it, you should reboot immediately. Linux won't know about the changes you made the partition table. (This will be fixed, with kernel 2.4, and when we add support for it.)

If you want to resize your root or boot partition, use a boot disk See section 1.6 Using a Parted Boot Disk, or use Andreas Dilger's online ext2 resizer, included in the ext2resize package section 6.2 GNU Parted and the Second Extended Filesystem.

5.1 Disk labels used by GNU/Linux and FreeBSD

Both GNU/Linux and FreeBSD systems are rather flexible about disk labels, supporting many different disk label types.

Because it is rather unusual for a machine to use hard disks with labels normally used on other architectures, standard distributions of the Linux kernel often only support the popular disk labels for the architecture for which the kernel was compiled. For example, a standard Linux kernel compiled for a PC will likely not have support for Mac or Sun disk labels. To access the file systems on disks with unsupported disk labels, the kernel will have to be recompiled.

FreeBSD has a disk label system that is incompatible with MSDOS partition tables, and a partition slice system that is compatible with MSDOS partition tables. Parted only supports the BSD disk label system. It is unlikely to support the partition slice system, because the semantics are rather strange, and don't work like "normal" partition tables do.

5.2 Disk labels supported by Microsoft systems and OS/2

MS Windows and OS/2 only supports the msdos disk label. Therefore, if you create a new disk label, you should use:

(parted) mklabel msdos

5.3 Macintosh Operating System Disk Label Support

MacOS (and OpenFirmware) only understands the mac disk label. Therefore, if you create a new disk label, you should use:

(parted) mklabel mac

Note that for Mac partition maps, you should avoid leaving free space around, because free space regions take up entries in the partition map (and Linux doesn't like having more than 15 entries). For example, if you do:

(parted) print
Disk geometry for /dev/sda: 0.000-6149.882 megabytes
Disk label type: mac
Minor    Start       End     Filesystem  Name          Flags
1          0.000      0.031              Apple
2          0.031      1.000                            boot
3          1.000   1000.000  ext2        root          root
(parted)  mkpartfs primary ext2 1001 2000
(parted) print
Disk geometry for /dev/sda: 0.000-6149.882 megabytes
Disk label type: mac
Minor    Start       End     Filesystem  Name          Flags
1          0.000      0.031              Apple
2          0.031      1.000                            boot
3          1.000   1000.000  ext2        root          root
4       1001.000   2000.000  ext2

There is 1 megabyte of free space between partitions 3 and 4. You can avoid this, by creating partitions 0.1M apart (in which case, Parted automatically "pushes" them together). So, in the above example, you should do this instead:

(parted) mkpartfs primary ext2 1000.1 2000
(parted) print
Disk geometry for /dev/sda: 0.000-6149.882 megabytes
Disk label type: mac
Minor    Start       End     Filesystem  Name          Flags
1          0.000      0.031              Apple
2          0.031      1.000                            boot
3          1.000   1000.000  ext2        root          root
4       1000.000   2000.000  ext2

6. File Systems supported by Parted

6.1 File Systems Supported by GNU Parted

Parted has support for these operations:

  • Filesystem detect create resize copy check
  • ext2 * * *1 *2 *3
  • ext3 * *1 *2 *3
  • fat16 * * *4 *4 *
  • fat32 * * * * *
  • hfs *
  • jfs *
  • linux-swap * * * * *
  • ntfs *
  • reiserfs * *5 *1,5 *5 *3,5
  • ufs *
  • xfs * NOTES: (1) The start of the partition must stay fixed for ext2, ext3 and reiserfs. (2) The partition you copy to must be bigger (or exactly the same size) as the partition you copy from. (3) Limited checking is done when the file system is opened. This is the only checking at the moment. All commands (including resize) will gracefully fail, leaving the file system intact, if there are any errors in the file system (and the vast majority of errors in general). (4) The size of the new partition, after resizing or copying, is restricted by the cluster size for fat (mainly affects FAT16). This is worse than you think, because you don't get to choose your cluster size (it's a bug in Windows, but you want compatibility, right?). So, in practise, you can always shrink your partition (because Parted can shrink the cluster size), but you may not be able to grow the partition to the size you want. If you don't have any problems with using FAT32, you will always be able to grow the partition to the size you want. Summary: you can always shrink your partition. If you can't use FAT32 for some reason, you may not be able to grow your partition. (5) Reiserfs support is enabled if you install libreiserfs, available at reiserfs.linux.kiev.ua. (It is likely to be availabe soon from www.namesys.com... tell us if/when this happens!)

    6.2 GNU Parted and the Second Extended Filesystem

    Parted doesn't directly support for copying ext2 file systems (yet). There are a few ways of achieving this, however:

    • Use Parted's mkfs command (or mkfs.ext2), and then run at the shell: FIXME!!! this doesn't work quite right - but it should be OK for most people...
      # mount -t ext2 /dev/hda2 /mnt/dst
# find /mnt/src -depth | cpio -pm /mnt/dst
    • If the duplicate partition is going to bigger than the original, this can also be done: first, create the new ext2 partition. Then:
      # dd if=/dev/src-device of=/dev/dst-device bs=1024 count=old_size
# parted /dev/hda resize 2 start end
      where old_size is the size of the original partition in kilobytes. start and end are the new start and end for the duplicate partition.

    6.3 Legacy Microsoft File System Support

    Parted can not grow the cluster size of FAT file systems (yet). This places restrictions on resizing and copying partitions. This is often quite bizarre, because Parted can convert file systems between FAT16 and FAT32, which have different restrictions on what the cluster size can be.

    For example, lets say have a 100Mb partition with a cluster size 4k. This partition can't be resized to 400Mb, because the cluster size would need to be changed to 16k. However, it can be resized to 600Mb if you use FAT32. The reverse is true for 600Mb FAT32 file systems.

    Note: when you copy or resize a file system, Parted will ask you if you want to convert between FAT16 and FAT32 (if it is possible). Therefore, if you just want to convert a partition to FAT32 (without resizing), you can just resize the partition to the same size.

    6.3.1 MS DriveSpace partitions

    MS DriveSpace is a program that comes with MS Windows 95 that can be used to compress FAT file systems. I believe this works the same way as DoubleSpace, so everything said here applies should apply to DoubleSpace as well.

    It is possible to use Parted to resize and copy these partitions, but you have to do a few extra things...

    6.3.1.1 Growing a DriveSpace partition

    To increase the size of a DriveSpace partition, do the following

    1. Use Parted's resize command to grow the partition to the desired size.
    2. Use MS DriveSpace to shift the free space from the host drive to the compressed drive.

    6.3.1.2 Shrinking a DriveSpace partition

    To decrease the size of a DriveSpace partition, do the following:

    1. Use MS DriveSpace to shift the free space from the compressed drive to the host drive. The amount of free space shifted corresponds to the desired amount by which to shrink the partition.
    2. Use Parted's resize command to shrink the partition to the desired size. NOTE: Parted doesn't give good feedback on what the numbers, to know how much to shrink the partition by. This is on the TODO list.

    6.3.1.3 Copying a DriveSpace partition

    If you want to copy a DriveSpace partition to a partition that is bigger, then you can follow the instructions for growing a DriveSpace partition, except you copy rather than resize the desired partition, and make sure you use the new partition in DriveSpace.

    However, if you want to copy a DriveSpace partition to a partition that is smaller, things get a bit more complicated:

    1. Use MS DriveSpace to shift free space from the compressed drive to the source host drive. The amount of space shifted should be more than difference between the source partition, and the desired size of the duplicate partition.
    2. Use Parted to copy the source partition to the duplicate partition.
    3. Use MS DriveSpace to shift the free space from the source host drive back to the compressed drive.
    4. Use MS DriveSpace to shift the free space from the duplicate host drive back to the compressed drive.

    6.4 Reiserfs Journalling File System

    Parted supports reiserfs if libreiserfs is installed. Parted detects this at runtime, and automatically enables support. You can download libreiserfs from:

    http://reiserfs.linux.kiev.ua

    Note that libreiserfs is new software, and hasn't been tested widely yet.

    7. LVM and RAID

    7.1 Logical Volume Manager and Redundant Arrays of Inexpensive Disks

    LVM (Logical Volume Manager) is an alternative system to partitioning. It allows logical volumes (i.e. "virtual partitions") to be spread over many physical volumes (i.e. hard disks and/or partitions). LVM is supported on Linux version 2.4, and later.

    RAID (Redundant Array of Inexpensive Disks) is a system for using many disks and/or partitions together, as a "virtual partition". There are a few different modes of utilising software RAID, that are essentially:

    • using multiple (small) disks for a single file system, to improve performance and to make the entire space available available on a single file system.
    • using multiple disks to store redundant copies of information, to improve reliability and performance.

    Software RAID is supported on Linux version 2.0, and later.

    Hardware RAID is supported normally by Parted - so you need not read this section if you are using hardware RAID (as opposed to software RAID).

    LVM, software RAID and partitions are often used simultaneously, but they can all be used independently. LVM and software RAID are often composed of partitions, rather than raw hard disks.

    GNU Parted does not support LVM and software RAID in full, but it is still useful when used in combination with their respective tools. Parted is useful for these tasks:

    • creating a software RAID or LVM partition
    • creating, resizing or copying a file system on a logical volume (or "virtual partition")

    7.2 Creating RAID or LVM partitions

    To create a RAID or LVM partition, you must:

    1. Create a partition with the mkpart command.
    2. Set the LVM or RAID flag on the partition.

    For example:

    (parted) mkpart primary ext2 0 4000
(parted) set 1 lvm on

    Note: the LVM or RAID partition will not be ready for use yet. You still need to run mkraid(8) for RAID, or use the LVM tools to initialise the physical volume, and create logical groups, etc.

    7.3 Manipulating a File System on a RAID or LVM volume

    Parted can manipulate RAID and LVM logical volumes, even though it does not understand RAID or LVM. It utilises Linux's support for RAID and LVM. Therefore, you can only use these methods if your Linux kernel supports RAID and/or LVM.

    To manipulate a file system on a RAID or LVM logical volume (or, a raw partition, for that matter), you can start parted by selecting the logical volume (partition) device. For example:

    # parted /dev/md0

    For the rest of this chapter, "virtual device" will refer to the device Parted is editting (in our example cases, `/dev/md0').

    7.3.1 Creating a File System on an LVM or RAID Virtual Device

    To create a file system on an LVM volume, use the following steps:

    1. Create a loop disk label. This is a fake disk label, that tells Parted to treat the virtual device as a single file system. With this fake disk label, there is either zero or one partition.
      (parted) mklabel loop
    2. Create the file system, by using Parted's mkpartfs command. You should make the start of the file system 0. The partition can end anywhere inside the virtual device. You can find out the size of the virtual device with the print command. For example:
      (parted) print
Disk geometry for /dev/md0: 0.000-47.065 megabytes
Disk label type: loop
Minor    Start       End     Filesystem  Flags
(parted) mkpartfs primary ext2 0 47.065
(parted) print
Disk geometry for /dev/md0: 0.000-47.065 megabytes
Disk label type: loop
Minor    Start       End     Filesystem  Flags
1          0.000     47.065  ext2

    7.3.2 Resizing a File System on an LVM or RAID Virtual Device

    You usually resize the file system at the same times as you resize your virtual device. If you are growing the file system and virtual device, you should grow the device first (with the RAID or LVM tools), and then grow the file system. If you are shrinking the file system and virtual device, you should shrink the file system first, and then the virtual device afterwards.

    To resize the file system in Parted, use the resize command. For example:

    (parted) select /dev/md0
(parted) resize 1 0 20

    7.3.3 Copying a File System from an LVM or RAID Virtual Device to a Partition

    To copy a filesystem from an LVM or RAID virtual device, just use the cp command. For example:

    (parted) select /dev/hda (parted) cp /dev/md0 1 3

    7.3.4 Copying a File System to an LVM or RAID Virtual Device

    To copy a file system from an LVM or RAID virtual device, use the following recipe:

    1. Create the loop disk label on the virtual device. For example:
      (parted) select /dev/md0
(parted) mklabel loop
    2. Create a file system on the virtual device, with the mkpartfs command. For example:
      (parted) mkpartfs primary ext2 0 47.065
    3. Copy the partition with the cp command:
      (parted) select /dev/hda
(parted) cp /dev/md0 3 1

    8. Disk Imaging

    Disk imaging is a method for avoiding the tedious Windows install process. For example, if you want to install Windows and Office on 1000 machines, it'll probably take you about 5 times 1000 hours. Things aren't so bad with GNU/Linux, because there are programs like Red Hat's kickstart, which allow you to automate the install of other programs, or practically anything you need to do. Therefore, disk imaging is really only used for Windows machines. Obviously, we urge you to not use Windows (or any non-free software) at all, but we realise that most organisations would find it impossible switch from Windows to GNU/Linux (or other free software) without a transition period, where both systems are available.

    With disk imaging, you can burn a CD with a disk image of a partition containing Windows and Office, and copy the partition directly onto the hard disks of all the computers, by sticking in a boot disk and the CD, and letting it fly. But the partition on the Windows disk is probably going to be bigger, so the partition will also have to be resized. I've had several people say that they've managed to automate this process with Linux boot floppies and Parted. It is possible to use the CDROM only, by using the floppy as the boot image on the CD. Read the CD writing HOWTO for more information. There are a few weird things you have to do to get this whole thing to work (which will be fixed in the next stable series). Anyway, this is the general process:

    1. Install Windows on a machine, with the setup you want. You can have the partition as big as you want, so long as you don't use more than 640 Mb, and you leave enough room for a complete Linux install, and another 1300 Mb for two copies of the CD image.
    2. Install Linux on the machine.
    3. Make a directory for the CD image (e.g.: `/root/cdimage')
    4. Create a 640 disk image file (e.g.: `/root/cdimage/diskimage') in the CD image directory:
      # dd if=/dev/zero of=/root/cdimage/diskimage bs=1M count=640
    5. Use Parted to copy the Windows partition to the disk image:
      # parted /root/cdimage/diskimage mklabel msdos
# parted /root/cdimage/diskimage mkpart primary fat32 0 639
# parted /root/cdimage/diskimage cp /dev/hda 1 1
    6. Create the CD image from the CD image directory, and burn it to CD with your favourite CD writing tools.
    7. Compile a special version of Parted without native language support and readline support (or download the special RPM from Freshmeat):
      localhost:~/parted-1.0.0# ./configure --disable-nls --without-readline --disable-shared; make
    8. Create a Linux boot disk (see the Bootdisk HOWTO).
    9. Put the cut-down version of Parted on the boot disk (or a supplementary root disk).
    10. Write a shell script to do the following:
      mount /dev/cdrom /mnt/cdrom
parted --script /dev/hda mklabel msdos
parted --script /dev/hda mkpartfs primary fat 0 some-size
parted --script /dev/hda cp /mnt/cdrom/diskimage 1 1
parted --script /dev/hda set 1 boot on
/sbin/halt
      some-size is the size you desire the first partition to use.
    11. Start installing! Stick the floppy + CD into each computer, and let it roll...

    Obviously, I can and will make this process a lot easier. We're considering making a mini-distribution to do this. I wouldn't have time to maintain such a thing -- any volunteers?

    9. Related Software and Info

    If you want to find out more information, feel free to send questions to parted@gnu.org. (!) indicates the information/software is probably included in your distribution.

    These files in the Parted distribution contain further information:

    • ABOUT-NLS - information about using Native Language Support, and the Free Translation Project
    • API - the documentation for the libparted API
    • AUTHORS - who wrote what
    • BUGS - unfixed bugs
    • ChangeLog - record of changes made to Parted
    • COPYING - the GNU General Public License, the terms under which GNU Parted may be distributed
    • COPYING.DOC - the GNU Free Documentation Licence, the term under which Parted's documentation may be distributed.
    • FAT -- information on how the FAT resizer works (for programmers)
    • INSTALL -- how to compile and install Parted, and most other free software
    • TODO -- planned features that are not yet implemented

    These documents are not distributed with Parted, but you may find them useful. Most of these will probably be in your distribution. For example, on Red Hat Linux, look on the CD in `/doc/HOWTO' and `/doc/FAQ'.

    • Filesystems HOWTO http://penguin.cz/~mhi/fs
    • Hard Disk Upgrade mini-HOWTO (!): http://sunsite.unc.edu/LDP/HOWTO
    • Large Disk HOWTO http://www.win.tue.nl/~aeb/linux/Large-Disk.html
    • LILO mini-HOWTO (!) http://sunsite.unc.edu/LDP/HOWTO
    • MILO HOWTO (!) http://sunsite.unc.edu/LDP/HOWTO
    • Linux+OS mini-HOWTOs (!): Linux+DOS+Win95+OS2, Linux+FreeBSD-mini-HOWTO, Linux+Win95, Linux+FreeBSD, Linux+NT-Loader. You can get these from: http://sunsite.unc.edu/LDP/HOWTO
    • Partition mini-HOWTO (!): http://www.linuxdoc.org/HOWTO/mini/Partition/index.html
    • Partition Table HOWTO http://www.win.tue.nl/~aeb/partitions/partition_tables.html
    • Partition Types list http://www.win.tue.nl/~aeb/partitions/partition_types.html
    • Software RAID HOWTO http://linas.org/linux/Software-RAID/Software-RAID.html

    Other related programs are listed here. Some of these also have useful documentation:

    • Disk Drake. Available at www.linux-mandrake.com/diskdrake This is similar in functionality to Parted. The FAT code in Disk Drake is based on our Parted code. Here's how Disk Drake compares to Parted: (which we both agree to :-) Disk Drake is:
      • easier to use, protects you from making mistakes
      • more complete solution (handles `/etc/fstab', lilo, etc.)
      • less support for FAT (can't convert FAT16<->FAT32, can't copy partitions)
      • less support for ext2 (at the moment)
      • less attention to compatibility between (older) DOS/Windows systems
      • no support for non-PC architectures
    • dvhtool (for SGI/MIPS) (!)
    • dosfsck (!)
    • e2fsck, resize2fs e2fsprogs (!) http://web.mit.edu/tytso/www/linux/e2fsprogs.html
    • ext2resize - uses the same code as Parted, but includes some other goodies as well, such as an online ext2 resizer, that doesn't require unmounting. http://ext2resize.sourceforge.net
    • fdisk (!)
    • FIPS (!) (First Interactive Partition Splitter) http://www.igd.fhg.de/~aschaefe/fips RMK: standards: GPL'd
    • GPart - recovers broken partition tables. http://www.stud.uni-hannover.de/user/76201/gpart
    • GNU GRUB - GRand Unified Boot-loader http://www.gnu.org/software/grub/grub.html
    • LILO (!) (LInux LOader) ftp://tsx-11.mit.edu/pub/linux/packages/lilo
    • LVM http://linux.msede.com/lvm
    • mkdosfs (!) (sometimes called mkfs.msdos)
    • mke2fs (!) (sometimes called mkfs.ext2)
    • mkfs (!)
    • mkswap (!)
    • quik (!)
    • reiserfs: NOTE: a reiserfs resizer is included with normal reiserfs distribution. http://devlinux.com/projects/reiserfs Also, an independent reimplementation of reiserfs userland (which parted can utilize) http://reiserfs.linux.kiev.ua. This may be adopted by the other reiserfs people in future...
    • yaboot (!) http://ppclinux.apple.com/~benh/
    • ybin (!) http://www.alaska.net/~erbenson/ybin/

    A. Copying This Manual

    A.1 GNU Free Documentation License

    Version 1.1, March 2000

    Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
    1. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
    2. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, @acronym{SGML} or @acronym{XML} using a publicly available @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed for human modification. Opaque formats include PostScript, @acronym{PDF}, proprietary formats that can be read and edited only by proprietary word processors, @acronym{SGML} or @acronym{XML} for which the @acronym{DTD} and/or processing tools are not generally available, and the machine-generated @acronym{HTML} produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
    3. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies.
    4. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
    5. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
      1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
      2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
      3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
      4. Preserve all the copyright notices of the Document.
      5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
      6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
      7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
      8. Include an unaltered copy of this License.
      9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
      10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
      11. In any section entitled "Acknowledgments" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgments and/or dedications given therein.
      12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
      13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
      14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.
      If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
    6. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgments", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."
    7. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
    8. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
    9. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
    10. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
    11. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

    A.1.1 ADDENDUM: How to use this License for your documents

    To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

      Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

    If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

    If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

    B. This manual's history

    This manual is based on the file, USER, included in GNU Parted version 1.4.22 source distribution. The GNU Parted source distribution is available at ftp.gnu.org/gnu/parted.

    Texinfo formatting by Richard M. Kreuter, 2002.

    This manual is distributed under the GNU Free Documentation License, version 1.1 or later, at your discretion, with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. See section A. Copying This Manual, for details.

    Index

    Jump to: b - c - d - e - f - g - h - i - l - m - n - o - p - q - r - s - t - u - w

    b

  • bios
  • bios, chs mode disk geometry
  • bios, lba mode disk geometry
  • bios, pc
  • boot disk
  • boot floppy
  • boot loaders
  • bugs, reporting
  • building parted

    • c

  • check, command description
  • chs mode bios
  • chs to lba, converting
  • command description, check
  • command description, cp
  • command description, help
  • command description, mkfs
  • command description, mkindex
  • command description, mkpart
  • command description, mkpartfs
  • command description, move
  • command description, name
  • command description, print
  • command description, quit
  • command description, rescu
  • command description, resize
  • command description, rm
  • command description, select
  • command description, set
  • command syntax
  • commands
  • commands, detailed listing
  • commands, overview
  • compiling parted
  • contacting developers
  • cp, command description

    • d

  • description of parted
  • detailed command listing
  • disk imaging
  • disk labels, freebsd
  • disk labels, legacy microsoft and ibm
  • disk labels, linux
  • disk labels, macintosh
  • drivespace partition
  • drivespace partition, copying
  • drivespace partition, growing
  • drivespace partition, shrinking

    • e

  • e2fsprogs
  • example parted sessions
  • example, growing a partition
  • example, resizing a partition on crowded disk
  • ext2 file system support support

    • f

  • fat file system support
  • FDL, GNU Free Documentation License
  • file system support
  • file systems
  • firmware
  • freebsd disk labels
  • further reading

    • g

  • gettext
  • gnu gpl
  • gnu/linux disk labels
  • gpl
  • growing a partition, example
  • grub

    • h

  • help, command description
  • history of this manual

    • i

  • invocation options

    • l

  • lba mode bios
  • legacy microsoft and ibm disk labels
  • legacy microsoft file system support
  • legacy microsoft operating system bootloader
  • libuuid
  • license terms
  • lilo
  • lvm and raid
  • lvm and raid, overview
  • lvm partition creation
  • lvm partition operations
  • lvm, copying from a partition to lvm volume
  • lvm, copying from lvm to a partition
  • lvm, creating a filesystem
  • lvm, resizing a filesystem
  • lvw, overview

    • m

  • macintosh disklabels
  • macintosh open firmware
  • macintosh, new world bootloader
  • macintosh, new world firmware
  • macintosh, old world bootloader
  • macintosh, old world firmware
  • microsoft windows 2000 bootloader
  • microsoft windows nt bootloader
  • mips firmware
  • mkfs, command description
  • mklabel, command description
  • mkpart, command description
  • mkpartfs, command description
  • modes of use
  • move, command description

    • n

  • name, command description
  • new world macintosh bootloader
  • new world macintosh firmware, new world macintosh firmware

    • o

  • old world macintosh bootloader
  • old world macintosh firmware, old world macintosh firmware
  • open firmware, macintosh
  • operating systems
  • options at invocation
  • overview

    • p

  • parted description
  • parted session examples
  • partitioning overview
  • pc bios
  • pc98 bios
  • platforms, supported
  • print, command description

    • q

  • quit, command description

    • r

  • raid and lvm
  • raid partition creation
  • raid partition operations
  • raid, copying from a partition to raid device
  • raid, copying from raid to a partition
  • raid, creating a filesystem
  • raid, overview
  • raid, resizing a filesystem
  • readline
  • reiserfs
  • related documentation
  • related software
  • reporting bugs
  • required software
  • rescue, command description
  • resize, command description
  • resizing a partition on crowded disk, example
  • rm, command description

    • s

  • second extended file system
  • select, command description
  • set, command description
  • sgi firmware
  • software dependencies
  • supported file systems
  • supported platforms

    • t

  • terms of distribution

    • u

  • unsupported platforms

    • w

  • w32 bootloader

    • Footnotes

    (1)

    Everyone seems to have a different word for "disk label" -- these are all the same thing: partition table, partition map. Also, the Master Boot Record on x86 machines is stored in the same sector as Partition Tables (you don't need to know this to use Parted).

    (2)

    If Parted supported moving the start of ext2 partitions (like it does with FAT partitions), then it would be trivial:

    (parted) resize 6 3545.6 6200
(parted) resize 7 6200 7326.5

    This document was generated on 12 May 2002 using texi2html 1.56k.


The Plotutils Package

The GNU Plotting Utilities

Programs and functions for drawing and data plotting

Version 2.2

Robert S. Maier and Nicholas B. Tufillaro

Table of Contents

  • The GNU Plotting Utilities
  • The graph Application
    • Simple examples using graph
    • Rotated, non-square and displaced plots
    • Preparing a plot from more than one dataset
    • Multiplotting: placing multiple plots on a single page
    • Reading binary and other data formats
    • graph command-line options
      • Plot options
      • Dataset options
      • Multiplot options
      • Raw graph options
      • Informational options
    • Environment variables
  • The plot Program
    • How to use plot
    • plot command-line options
    • Environment variables
  • The pic2plot Program
    • What pic2plot is used for
    • pic2plot command-line options
    • Environment variables
  • The tek2plot Program
    • What tek2plot is used for
    • tek2plot command-line options
    • Environment variables
  • The plotfont Utility
    • How to use plotfont
    • plotfont command-line options
    • Environment variables
  • The spline Program
    • How to use spline
    • Advanced use of spline
    • spline command-line options
  • The ode Program
    • Mathematical basics
    • Simple examples using ode
    • Additional examples using ode
    • ode command-line options
    • Diagnostic messages
    • Numerical error and how to avoid it
    • Running time
    • The ode input language formally specified
    • Bibliography on ode and solving differential equations
  • libplot, a Function Library
    • Programming with libplot: An overview
    • C Programming with libplot
      • The C application programming interface
      • C compiling and linking
      • Sample drawings in C
      • Animated GIFs in C
      • X Window System animations in C
      • Advanced X Window System programming
    • C++ Programming with libplotter
      • The Plotter class
      • C++ compiling and linking
      • Sample drawings in C++
    • The functions in libplot: A detailed listing
      • Setup functions
      • Object-drawing functions
      • Attribute-setting functions
      • Mapping functions
    • Device driver parameters
  • Fonts, Strings, and Symbols
    • Available text fonts
    • Cyrillic and Japanese fonts
    • Available text fonts for the X Window System
    • Text string format and escape sequences
    • Available marker symbols
  • Specifying Colors by Name
  • The Graphics Metafile Format
  • Obtaining Auxiliary Software
    • How to get idraw
    • How to get xfig
  • Acknowledgements

The GNU Plotting Utilities

The GNU plotting utilities consist of eight command-line programs: the graphics programs graph, plot, pic2plot, tek2plot, and plotfont, and the mathematical programs spline, ode, and double. Distributed with these programs is GNU libplot, the library on which the graphics programs are based. libplot is a function library for device-independent two-dimensional vector graphics, including vector graphics animations under the X Window System. There are versions for both C and C++.

The graphics programs and libplot can export vector graphics in the following ten formats.

X
If this output option is selected, there is no output file. Output is directed to a popped-up window on an X Window System display.
PNM
This is "portable anymap" format. There are three types of portable anymap: PBM (portable bitmap, for monochrome images), PGM (portable graymap), and PPM (portable pixmap, for colored images). The output file will be in whichever of these three formats is most appropriate. Portable anymaps may be viewed or edited with many applications, such as the free image display application xv.
GIF
This is pseudo-GIF format rather than true GIF format. Unlike GIF format it does not use LZW compression, so it does not transgress the Unisys LZW patent. However, files in pseudo-GIF format may be viewed or edited with any application that understands GIF format, such as xv.
AI
This is the format used by Adobe Illustrator. Files in this format may be edited with Adobe Illustrator (version 5, and more recent versions), or other applications.
PS
This is idraw-editable Postscript format. Files in this format may be sent to a Postscript printer, imported into another document, or edited with the free idraw drawing editor. See section How to get idraw.
Fig
This is a graphics format that may be displayed or edited with the free xfig drawing editor. See section How to get xfig.
PCL 5
This is a powerful version of Hewlett--Packard's Printer Control Language. Files in this format may be sent to a LaserJet printer or compatible device (note that most inkjets do not support PCL 5).
HP-GL
This is Hewlett--Packard's Graphics Language. By default, the modern variant HP-GL/2 is produced. Files in HP-GL or HP-GL/2 format may be imported into a document or sent to a plotter.
Tek
This is the graphics format understood by Tektronix 4014 terminals and emulators, including the emulators built into the xterm terminal emulator program and the MS-DOS version of kermit.
Metafile
This is device-independent GNU graphics metafile format. The plot program can translate it to any of the preceding formats.

Of the command-line graphics programs, the best known is graph, which is an application for plotting two-dimensional scientific data. It reads one or more data files containing datasets, and outputs a plot. The above output formats are supported. The corresponding commands are graph -T X, graph -T pnm, graph -T gif, graph -T ai, graph -T ps, graph -T fig, graph -T pcl, graph -T hpgl, graph -T tek, and graph. graph without a `-T' option (referred to as `raw graph') produces output in GNU metafile format.

graph can read datasets in both ASCII and binary format, and datasets in the `table' format produced by the plotting program gnuplot. It produces a plot with or without axes and labels. You may specify labels and ranges for the axes, and the size and position of the plot on the display. The labels may contain subscripts and subscripts, Greek letters, and other special symbols; there is also support for Cyrillic script (i.e., Russian) and Japanese. You may specify the type of plotting symbol used for each dataset, and such parameters as the style and thickness of the line (if any) used to connect points in a dataset. The plotting of filled regions is supported, as is the drawing of error bars. graph provides full support for multiplotting. With a single invocation of graph, you may produce a plot consisting of many sub-plots, either side by side or inset. Each sub-plot will have its own axes and data.

graph -T X, graph -T tek, and raw graph have a feature that most plotting programs do not have. They can accept input from a pipe, and plot data points to the output in real time. For this to occur, the user must specify ranges for both axes, so that graph does not need to wait until the end of the input before determining them.

The plot program is a so-called plot filter. It can translate GNU graphics metafiles (produced for example by raw graph) into any supported output format. The corresponding commands are plot -T X, plot -T pnm, plot -T gif, plot -T ai, plot -T ps, plot -T fig, plot -T pcl, plot -T hpgl, plot -T tek, and plot. The plot program is useful if you wish to produce output in several different formats while invoking graph only once. It is also useful if you wish to translate files in the traditional `plot(5)' format produced by, e.g., the non-GNU versions of graph provided with some operating systems. GNU metafile format is compatible with plot(5) format.

The pic2plot program can translate from the pic language to any supported output format. The pic language, which was invented at Bell Laboratories, is used for creating box-and-arrow diagrams of the kind frequently found in technical papers and textbooks. The corresponding commands are pic2plot -T X, pic2plot -T pnm, pic2plot -T gif, pic2plot -T ai, pic2plot -T ps, pic2plot -T fig, pic2plot -T pcl, pic2plot -T hpgl, pic2plot -T tek, and pic2plot.

The tek2plot program can translate from Tektronix format to any supported output format. The corresponding commands are tek2plot -T X, tek2plot -T pnm, tek2plot -T gif, tek2plot -T ai, tek2plot -T ps, tek2plot -T fig, tek2plot -T pcl, tek2plot -T hpgl, and tek2plot. tek2plot is useful if you have an older application that produces drawings in Tektronix format.

The plotfont program is a simple utility that displays a character map for any font that is available to graph, plot, pic2plot, or tek2plot. The 35 standard Postscript fonts are available if the `-T X', `-T ai', `-T ps', or `-T fig' options are used. The 45 standard PCL 5 fonts (i.e., "LaserJet" fonts) are available if the `-T ai', `-T pcl' or `-T hpgl' options are used. In the latter two cases (`-T pcl' and `-T hpgl'), a number of Hewlett--Packard vector fonts are available as well. A set of 22 Hershey vector fonts, including Cyrillic fonts and a Japanese font, is always available. When producing output for an X Window System display, any of the graphics programs can use scalable X fonts.

Of the command-line mathematical programs, spline does spline interpolation of scalar or vector-valued data. It normally uses either cubic spline interpolation or exponential splines in tension, but like graph it can function as a real-time filter under some circumstances. Besides splining datasets, it can construct curves, either open or closed, through arbitrarily chosen points in d-dimensional space. ode provides the ability to integrate an ordinary differential equation or a system of ordinary differential equations, when provided with an explicit expression for each equation. It supplements the plotting program gnuplot, which can plot functions but not integrate ordinary differential equations. The final command-line mathematical program, double, is a filter for converting, scaling and cutting binary or ASCII data streams. It is still under development and is not yet documented.

The libplot function library is discussed at length elsewhere in this documentation. It gives C and C++ programs the ability to draw such objects as lines, open and closed polylines, arcs (both circular and elliptic), quadratic and cubic Bezier curves, circles and ellipses, points, marker symbols, and text strings. The filling of objects other than points, marker symbols, and text strings is supported (fill color, as well as pen color, can be set arbitrarily). Text strings can be drawn in any of a large number of fonts. The 35 standard Postscript fonts are supported by the X Window System, Illustrator, Postscript, and xfig drivers, and the 45 standard PCL 5 fonts are supported by the Illustrator, PCL 5 and HP-GL/2 drivers. The latter two also support a number of Hewlett--Packard vector fonts. All drivers, including the PNM, GIF, Tektronix and metafile drivers, support a set of 22 Hershey vector fonts.

The support for drawing text strings is extensive. Text strings may include subscripts and superscripts, and may include characters chosen from more than one font in a typeface. Many non-alphanumeric characters may be included. The entire collection of over 1700 `Hershey glyphs' digitized by Allen V. Hershey at the U.S. Naval Surface Weapons Center, which includes many curious symbols, is built into libplot. Text strings in the so-called EUC-JP encoding (i.e., the Extended Unix Code for Japanese) can be also be drawn. Such strings may include both syllabic Japanese characters (Hiragana and Katakana) and ideographic Japanese characters (Kanji). A library of 603 Kanji, including 596 of the 2965 frequently used Level 1 Kanji, is built into libplot.

The drawing editors idraw and xfig are not distributed along with the GNU plotting utilities. However, they are free software, and you may readily obtain them elsewhere (see section Obtaining Auxiliary Software).

The graph Application

Each invocation of graph reads one or more datasets from files named on the command line or from standard input, and prepares a plot. There are many command-line options for adjusting the visual appearance of the plot. See section graph command-line options, for documentation on all options. The following sections explain how to use the most frequently used options, by giving examples.

Simple examples using graph

By default, graph reads ASCII data from the files specified on the command line, or from standard input if no files are specified. The data are pairs of numbers, interpreted as the x and y coordinates of data points:

0.0  0.0
1.0  0.2
2.0  0.0
3.0  0.4
4.0  0.2
5.0  0.6

Data points do not need to be on different lines, nor do the x and y coordinates of a data point need to be on the same line. However, there should be no blank lines in the input if it is to be viewed as forming a single dataset.

To plot such a dataset with graph, you could do

graph -T ps ascii_data_file > plot.ps

or equivalently

graph -T ps < ascii_data_file > plot.ps

This will produce an encapsulated Postscript file plot.ps, which you may include in another document, display on a screen, or send directly to a printer. (The `--page-size' option, or the PAGESIZE environment variable, specifies the size of the printed page. The default is "letter", i.e., 8.5in by 11in, but "a4" or other ISO or ANSI page sizes can be specified instead.)

You may also do

graph -T fig < ascii_data_file > plot.fig

to produce a file plot.fig that you may edit with the the free xfig drawing editor, or

graph -T ai < ascii_data_file > plot.ai

to produce a file plot.ai that you may edit with Adobe Illustrator. If you do

graph -T hpgl < ascii_data_file > plot.plt

you will produce a file plot.plt in the Hewlett--Packard Graphics Language (HP-GL/2) that you may send to a Hewlett--Packard plotter. Similarly, you may use graph -T pcl to produce a file in PCL 5 format that may be printed on a LaserJet or other laser printer.

You may use graph -T X to pop up a window on an X Window System display, and display the plot in it. For that, you would do

graph -T X < ascii_data_file

If you use graph -T X, no output file will be produced; only a window. The window will vanish if you type `q' or click your mouse in it.

You may also use graph -T pnm to produce a PNM file (a "portable anymap"), and graph -T gif to produce a pseudo-GIF file. If the free image display application xv is available on your system, you would use either of the two commands

graph -T pnm < ascii_data_file | xv -
graph -T gif < ascii_data_file | xv -

to display the output file.

Another thing you can do is use graph -T tek to display a plot on a device that can emulate a Tektronix 4014 graphics terminal. xterm, the X Window System terminal emulator, can do this. Within an xterm window, you would do

graph -T tek < ascii_data_file

xterm normally emulates a VT100 terminal, but when this command is issued from within it, it will pop up a second window (a `Tektronix window') and draw the plot in it. The Japanese terminal emulator kterm should be able to do the same, provided that it is correctly installed. Another piece of software that can emulate a Tektronix 4014 terminal is the MS-DOS version of kermit.

graph may behave differently depending on the environment in which it is invoked. We have already mentioned the PAGESIZE environment variable, which affects the operation of graph -T ai, graph -T ps, graph -T fig, graph -T pcl, and graph -T hpgl. Similarly, the BITMAPSIZE environment variable affects the operation of graph -T X, graph -T pnm, and graph -T gif. The DISPLAY environment variable affects the operation of graph -T X, and the TERM environment variable affects the operation of graph -T tek. There are also several environment variables that affect the operation of graph -T pcl and graph -T hpgl. For a complete discussion of the effects of the environment on graph, see section Environment variables. The following remarks apply irrespective of which output format is specified.

By default, successive points in the dataset are joined by solid line segments, which form a polygonal line or polyline that we call simply a `line'. You may choose the style of line (the `linemode') with the `-m' option:

graph -T ps -m 2 < ascii_data_file > plot.ps

Here `-m 2' indicates that linemode #2 should be used. If the dataset is rendered in monochrome, which is the default, the line can be drawn in one of five distinct styles. Linemodes #1 through #5 signify solid, dotted, dotdashed, shortdashed, and longdashed; thereafter the sequence repeats. If the `-C' option is used, the dataset will be rendered in color. For colored datasets, the line can be drawn in one of 25 distinct styles. Linemodes #1 through #5 signify red, green, blue, magenta, and cyan; all are solid. Linemodes #6 through #10 signify the same five colors, but dotted rather than solid. Linemodes #11 through #16 signify the same five colors, but dotdashed, and so forth. After linemode #25, the sequence repeats. Linemode #0, irrespective of whether the rendering is in monochrome or color, means that the line is not drawn.

If you wish to fill the polygon bounded by the line (i.e., shade it, or fill it with a solid color), you may use the `-q' option. For example,

echo .1 .1 .1 .9 .9 .9 .9 .1 .1 .1 | graph -T ps -C -m 1 -q 0.3 > plot.ps

will plot a square region with vertices (0.1,0.1), (0.1,0.9), (0.9,0.9), and (0.9,0.1). The repetition of the first vertex (0.1,0.1) at the end of the sequence of vertices ensures that the square will be closed: all four segments of its boundary will be drawn. The square will be drawn in red, since the colored version of linemode #1 is requested. The interior of the square will be filled with red to an intensity of 30%, as the `-q 0.3' option specifies. If the intensity were zero, the region would be filled with white, and if it were 1.0, the region would be filled with solid color. If the intensity were negative, the region would be unfilled, or transparent (the default).

You may choose the thickness (`width') of the line, whether it is filled or not, by using the `-W' option. For example, `-W 0.01' specifies that the line should have a thickness equal to 0.01 times the size of the display. Also, you may put symbols at each data point along the line by doing, for example,

graph -T ps -S 3 0.1 < ascii_data_file > plot.ps

where the first argument 3 indicates which symbol to plot. The optional second argument 0.1 specifies the symbol size as a fraction of the size of the `plotting box': the square within which the plot is drawn. Symbol #1 is a dot, symbol #2 is a plus sign, symbol #3 is an asterisk, symbol #4 is a circle, symbol #5 is a cross, and so forth. (See section Available marker symbols.) Symbols 1 through 31 are the same for all display types, and the color of a symbol will be the same as the color of the line it is plotted along.

Actually, you would probably not want to plot symbols at each point in the dataset unless you turn off the line joining the points. For this purpose, the `negative linemode' concept is useful. A line whose linemode is negative is not visible; however, any symbols plotted along it will have the color associated with the corresponding positive linemode. So, for example,

graph -T ps -C -m -3 -S 4 < ascii_data_file > plot.ps

will plot a blue circle at each data point. The circles will not be joined by line segments. By adding the optional second argument to the `-S' option, you may adjust the size of the circles.

graph will automatically generate abscissa (i.e., x) values for you if you use the `-a' option. If this option is used, no abscissa values should be given in the data file. The data points will be taken to be regularly spaced along the abscissa. The two arguments following `-a' on the command line will be taken as the sampling interval and the abscissa value of the first data point. If they are absent, they default to 1.0 and 0.0 respectively. For example, the command

echo 0 1 0 | graph -T ps -a > plot.ps

produces exactly the same plot as

echo 0 0 1 1 2 0 | graph -T ps > plot.ps

graph will plot data with error bars, if the `-I e' option is specified. If it is, the dataset should consist of triples (x,y,error) rather than pairs (x,y). A vertical error bar of the appropriate length will be plotted at each data point. You may plot a symbol at each data point, along with the error bar, by using the `-S' option in the usual way. The symbol will be the same for each point in the dataset. You may use the `-a' option in conjunction with `-I e', if you wish. If you do, the dataset should contain no abscissa (i.e., x) values.

By default the limits on the x and y axes, and the spacing between the labeled ticks on each axis, are computed automatically. You may wish to set them manually. You may accomplish this with the `-x' and `-y' options.

echo 0 0 1 1 2 0 | graph -T ps -x -1 3 -y -1 2 > plot.ps

will produce a plot in which the x axis extends from -1 to 3, and the y axis from -1 to 2. By default, graph tries to place about six numbered ticks on each axis. By including an optional third argument to either `-x' or `-y', you may manually set the spacing of these ticks, also. For example, using `-y -1 2 1' rather than `-y -1 2' will produce a y axis with labeled ticks at -1, 0, 1, and 2, rather than at the locations that graph would choose by default, which would be -1, -0.5, 0, 0.5, 1, 1.5, and 2. In general, if a third argument is present then labeled ticks will be placed at each of its integer multiples.

To make an axis logarithmic, you may use the `-l' option. For example,

echo 1 1 2 3 3 1 | graph -T ps -l x > plot.ps

will produce a plot in which the x axis is logarithmic, but the y axis is linear. To make both axes logarithmic, you would use `-l x -l y'. By default, the upper and lower limits on a logarithmic axis are powers of ten, and there are tick marks at each power of ten and at its integer multiples. The tick marks at the powers of ten are labeled. If the axis spans more than five orders of magnitude, the tick marks at the integer multiples are omitted.

If you have an unusually short logarithmic axis, you may need to increase the number of labeled ticks. To do this, you should specify a tick spacing manually. For example, `-l x -x 1 9 2' would produce a plot in which the x axis is logarithmic and extends from 1 to 9. Labeled ticks would be located at each integer multiple of 2, i.e., at 2, 4, 6, and 8.

You may label the x and y axes with the `-X' and `-Y' options, respectively. For example,

echo 1 1 2 3 3 1 | graph -T ps -l x -X "A Logarithmic Axis" > plot.ps

will label the log axis in the preceding example. By default the label for the y axis (if any) will be rotated 90 degrees, unless you use the `--toggle-rotate-y-label' option. You may specify a `top label', or title for the plot, by using the `-L' option. Doing, for example,

echo 1 1 2 3 3 1 | graph -T ps -l x -L "A Simple Example" > plot.ps

will produce a plot with a title on top.

The size of the x axis and y axis labels is specified with the `-f' option, and the size of the title is specified with the `--title-font-size' option. For example,

echo 1 1 2 3 3 1 | graph -T ps -X "Abscissa" -f 0.1 > plot.ps

will produce a plot in which the font size of the x axis label, and each of the numerical tick labels, is very large (0.1 times the size of the plotting box, i.e., the square within which the plot is drawn).

The font in which the labels specified with the `-X', `-Y', and `-L' options are drawn can be specified with the `-F' option. For example, `-F Times-Roman' will make the labels appear in Times-Roman instead of the default font (which is Helvetica, unless `-T pnm', `-T gif', `-T pcl', `-T hpgl' or `-T tek' is specified). Font names are case-insensitive, so `-F times-roman' will work equally well. The available fonts include 35 Postscript fonts (for all variants of graph other than graph -T pnm, graph -T gif, graph -T pcl, graph -T hpgl and graph -T tek), 45 PCL 5 fonts (for graph -T ai, graph -T pcl and graph -T hpgl), a number of Hewlett--Packard vector fonts (for graph -T pcl and graph -T hpgl), and 22 Hershey vector fonts. The Hershey fonts include HersheyCyrillic, for Russian, and HersheyEUC, for Japanese. For a discussion of the available fonts, see section Available text fonts. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.

The format of the labels drawn with the `-X', `-Y', and `-L' options may be quite intricate. Subscripts, superscripts, square roots, and switching fonts within a typeface are all allowed. The above examples do not illustrate this, but for details, see section Text string format and escape sequences.

Each of the preceding examples produced a plot containing the default sort of grid (a square box, with ticks and labels drawn along its lower edge and its left edge). There are actually several sorts of grid you may request. The `-g 0', `-g 1', `-g 2', and `-g 3' options yield successively fancier grids. What they yield, respectively, is no grid at all, a pair of axes with ticks and labels, a square box with ticks and labels, and a square box with ticks, labels, and grid lines. As you can see, `-g 2' is the default. There is also a `-g 4' option, which yields a slightly different sort of grid: a pair of axes that cross at the origin. This last sort of grid is useful if the x or y coordinates of the data points you are plotting are both positive and negative.

Rotated, non-square and displaced plots

To rotate the plotting box by 90 degrees counterclockwise on your graphics display, you would add `--rotation 90' to the graph command line. You may also specify `--rotation 180', to produce an upside-down plot, or `--rotation 270'.

To alter the linear dimensions of the plotting box, and also to position it in a different part of the display, you could do something like

graph -T ps -h .3 -w .6 -r .1 -u .1 < ascii_data_file > plot.ps

Here the `-h' and `-w' options specify the height and width of the plotting box, and the `-r' and `-u' options indicate how far up and to the right the lower left corner of the plotting box should be positioned. All dimensions are expressed as fractions of the size of the graphics display, which by convention is a square. By default, the height and width of the plotting box equal 0.6, and the `upward shift' and the `rightward shift' equal 0.2. So the above example will produce a plot that is half as tall as usual. Compared to its usual position, the plot will be shifted slightly downward and to the left.

Several command-line options specify sizes or dimensions as fractions of the size of the plotting box, rather than as fractions of the size of the display. For example, `-S 3 .01' specifies that the plotting symbols for the following dataset should be of type #3, and should have a font size equal to 0.01, i.e. 0.01 times the minimum dimension (height or width) of the plotting box. If the `-h' or `-w' options are employed to expand or contract the plot, such sizes or dimensions will scale in tandem. That is presumably the right thing to do.

The `-h', `-w', `-r', and -u options may be combined with the `--rotation' option. If they appear together, the plotting box is first positioned, and then rotated. In fact, `--rotation' specifies how the plot should be mapped to the graphics display, rather than how the plot is designed.

The `graphics display' is an abstraction. For graph -T X, it is a window on an X display. For graph -T pnm and graph -T gif, it is a square or rectangular bitmap. In these three cases, the size of the graphics display can be set by using the --bitmap-size option, or by setting the BITMAPSIZE environment variable. For graph -T tek, the graphics display is a square region occupying the central part of a Tektronix display. (Tektronix displays are 4/3 times as wide as they are high.) For graph -T ai and graph -T ps, by default it is a square region centered on an 8.5in by 11in page (US letter size), occupying its full width with allowance being made for margins. For graph -T fig, by default it is a square region of the same size, positioned in the upper left corner of an xfig display. For graph -T pcl and graph -T hpgl, by default it is a square region of the same size, with position and orientation on the page being controlled by environment variables. The page size used by graph -T ai, graph -T ps, graph -T fig, graph -T pcl, and graph -T hpgl can be set by using the --page-size option, or by setting the environment variable PAGESIZE. For example, setting PAGESIZE to "a4" would position the graphics display appropriately on an A4-size page (21cm by 29.7cm).

Preparing a plot from more than one dataset

It is frequently the case that several datasets need to be displayed on the same plot. If so, you may wish to distinguish the points in different datasets by joining them by lines of different types, or by using plotting symbols of different types.

A more complicated example would be the following. You may have a file containing a dataset that is the result of experimental observations, and a file containing closely spaced points that trace out a theoretical curve. The second file is a dataset in its own right. You would presumably plot it with line segments joining successive points, so as to trace out the theoretical curve. But the first dataset, resulting from experiment, would be plotted without such line segments. In fact, a plotting symbol would be plotted at each of its points.

These examples, and others like them, led us to define a set of seven attributes which define the way in which a dataset should be plotted. These attributes, which can be set by command-line options, are the following.

  1. color/monochrome
  2. linemode
  3. linewidth
  4. symbol type
  5. symbol size
  6. symbol font name
  7. fill fraction

Color/monochrome (a choice of one or the other) is the simplest. This choice is toggled with the `-C' option. The `linemode' (i.e., line style) specifies how the line segments joining successive points should be drawn; it is specified with the `-m' option. Linemode #0 means no linemode at all, for example. `Linewidth' means line thickness; it is specified with the `-W' option. `Symbol type' and `symbol size', which are specified with the `-S' option, specify the symbol plotted at each point of the dataset. `Symbol font name' refers to the font from which plotting symbols #32 and above, which are taken to be characters rather than geometric symbols, are selected. It is set with the `--symbol-font-name' option, and is relevant only if `-S' is used to request such special plotting symbols. Finally, the polygonal line joining the points in a dataset may be filled, to create a filled or shaded polygon. The `fill fraction' is set with the `-q' option. A negative fill fraction means no fill, or transparent; zero means white, and 1.0 means solid, or fully colored.

The preceding seven attributes refer to the way in which datasets are plotted. Datasets may also differ from one another in the way in which they are read from files. The dataset(s) in a file may or may not contain error bars, for example. If a file contains data with error bars, the `-I e' option should occur on the command line before the file name. (The `-I' option specifies the input format for the following files.)

The following illustrates how datasets in three different input files could be plotted simultaneously.

graph -T ps -m 0 -S 3 file_1 -C -m 3 file_2 -C -W 0.02 file_3 > output.ps

The dataset in file_1 will be plotted in linemode #0, so successive points will not be joined by lines. But symbol #3 (an asterisk) will be plotted at each point. The dataset in file_2 will be plotted in color, and linemode #3 will be used. In color plotting, linemode #3 is interpreted as a solid blue line. The second `-C' on the command line turns off color for file_3. The points in the third dataset will be joined by a black line with thickness 0.02, as a fraction of the size (i.e., minimum dimension) of the graphics display.

The above command line could be made even more complicated by specifying additional options (e.g., `-q' or `-I') before each file. In fact the command line could also include such standard options as `-x' or `-y', which specify the range of each axis. Such options, which refer to the plot as a whole rather than to individual datasets, should appear before the first file name. For example, you could do

graph -T ps -x 0 1 0.5 -m 0 -S 3 file_1 -C -m 3 file_2 > output.ps

Note that it is possible to include the special file name `-', which refers to standard input, on the command line. So you may produce a plot in part from files, and in part from input that is piped to graph from another program.

Each input file may include more than one dataset. If so, the command line options preceding a file on the command line will take effect for all datasets in that file. There are two exceptions to this. By default, the linemode is incremented (`bumped') from one dataset to the next. This feature is usually quite convenient. For example, if you do

graph -T ps -m 3 file_1 > output.ps

the first dataset in file_1 will appear in linemode #3, the second in linemode #4, etc. In fact if you do

graph -T ps file_1 file_2 ... > output.ps

without specifying linemode explicitly, the successive datasets read from the files on the command line will appear in linemode #1, linemode #2, .... If you do not like this feature, you may turn it off, or in general toggle it, by using the `-B' option.

You may also control manually the linemode and symbol type used for the datasets within any file. You would do this by including directives in the file itself, rather than on the command line. For example, if the line

#m=-5,S=10

appeared in an ASCII-format input file, it would be interpreted as a directive to switch to linemode #-5 and symbol type #10 for the following dataset. Future releases of graph may provide the ability to set each of the seven dataset attributes in this way.

Multiplotting: placing multiple plots on a single page

It is occasionally useful to display several plots at once on a single page, or on a single graphics display. We call such a composite plot a multiplot. One common sort of multiplot is a small plot inset into a larger one. Another sort is two or more plots side by side.

graph can draw multiplots consisting of an arbitrarily large number of sub-plots. When multiplotting, graph draws each sub-plot in its own `virtual display'. When an ordinary plot is drawn, the virtual display is the same as the physical display. But when a multiplot is drawn, the virtual display may be any smaller square region. The following example illustrates the idea.

graph -T ps data_file_1 --reposition .35 .35 .3 data_file_2

Here data_file_1 is plotted in the usual way. The `--reposition' option specifies that when data_file_2 is plotted, it will be drawn within a virtual display. For the purposes of the `--reposition' option, the physical display is a square with lower left corner (0.0,0.0) and upper right corner (1.0,1.0). In those coordinates, the virtual display will be a square of size 0.3 with lower left corner (0.35,0.35). So the second sub-plot will be inset into the first.

Just as the `-w', `-h', `-r', and `-u' options may be used to set the size and position of a plotting box within the physical display, so they may be used to set the size and position of a plotting box within a virtual display. For example,

graph -T ps data_file_1 --reposition .35 .35 .3 -w .4 -r .3 data_file_2

will yield a multiplot in which the second sub-plot is significantly different. Its plotting box will have a width only 0.4 times the width of the virtual display. However, the plotting box will be centered within the virtual display, since the distance between the left edge of the plotting box and the left edge of the virtual display will be 0.3 times the width of the virtual display.

By convention, before each sub-plot of a multiplot other than the first is drawn, a `blankout region' surrounding its plotting box is erased. (That is, it is filled with white.) This erasure prevents the sub-plots from overlapping and producing a messy result. By default, the blankout region is a rectangular region 30% larger in each dimension than the plotting box for the sub-plot. This is appropriate if the sub-plot is a small one that is inset into the first sub-plot. It may not be appropriate, however, if you are preparing a multiplot in which several sub-plots appear side by side. You may use the `--blankout' option to adjust this parameter. For example, specifying `--blankout 1.0' will make the blankout region for a sub-plot coincide with its plotting box. Specifying `--blankout 0.0' will prevent any blanking out from occurring. The blankout parameter may differ from sub-plot to sub-plot.

It should be emphasized that every sub-plot in a multiplot is a plot in its own right. All the usual options (`-m', `-S', `-x', `-y', etc.) can be applied to each sub-plot separately. The options for a sub-plot should occur on the graph command line immediately after the `--reposition' option that applies to it. Each sub-plot may be prepared from more than a single dataset, also. The names of the data files for each subplot should occur on the command line before the following `--reposition' option, if any.

Reading binary and other data formats

By default, graph reads datasets in ASCII format. But it can also read datasets in any of three binary formats (single precision floating point, double precision floating point, and integer). These three input formats are specified by the `-I d', `-I f', and `-I i' options, respectively.

There are two advantages to using binary data: 1) graph runs significantly faster because the computational overhead for converting data from ASCII to binary is eliminated, and 2) the input files may be significantly smaller. If you have very large datasets, using binary format may reduce storage and runtime costs.

For example, you may create a single precision binary dataset as output from a C language program:

#include <stdio.h>
void write_point (float x, float y)
{
  fwrite(&x, sizeof (float), 1, stdout);
  fwrite(&y, sizeof (float), 1, stdout);
}

You may plot data written this way by doing:

graph -T ps -I f < binary_data_file > plot.ps

@ifnottex The inclusion of multiple datasets within a single binary file is supported. If a binary file contains more than a single dataset, successive datasets should be separated by a single occurrence of the the largest possible number. For single precision datasets this is the quantity FLT_MAX, for double precision datasets it is the quantity DBL_MAX, and for integer datasets it is the quantity INT_MAX. On most machines FLT_MAX is approximately 3.4x10^38, DBL_MAX is approximately 1.8x10^308, and INT_MAX is 2^32-1.

If you are reading datasets from more than one file, it is not required that the files be in the same format. For example,

graph -T ps -I f binary_data_file -I a ascii_data_file > plot.ps

will read binary_data_file in `f' (binary single precision) format, and ascii_data_file in `a' (normal ASCII) format.

There is currently no support for reading and plotting binary data with error bars. If you have data with error bars, you should supply the data to graph in ASCII, and use the `-I e' option.

graph can also read data files in the ASCII `table' format produced by the gnuplot plotting program. For this, you should use the `-I g' option. Such a data file may consist of more than one dataset.

To sum up: there are six supported data formats, `a' (normal ASCII), `e' (ASCII with error bars), `g' (the ASCII `table' format produced by gnuplot), `f' (binary single precision), `d' (binary double precision), and `i' (binary integer). Input files may be in any of these six formats.

graph command-line options

The graph program reads one or more datasets from files named on the command line or from standard input, and prepares a plot. The output format or display type is specified with the `-T' option.

By default, graph reads ASCII data from the files specified on the command line. The data are pairs of numbers, interpreted as the x and y coordinates of data points. If no file names are specified, or the file name `-' is specified, the standard input is read. The output file is written to standard output, unless the `-T X' option is specified. In that case the graph is displayed in a window on an X Window System display, and there is no output file.

There are many command-line options for adjusting the visual appearance of the plot. The relative order of file names and command-line options is important. Only the options that precede a file name on the command line take effect for that file.

The following sections list the possible options. Each option that takes an argument is followed, in parentheses, by the type and default value of the argument. There are five sorts of option.

  1. Options affecting an entire plot. (See section Plot options.)
  2. Options affecting the reading and drawing of individual datasets within a plot. (See section Dataset options.)
  3. Options for multiplotting (drawing several sub-plots within a plot). (See section Multiplot options.)
  4. Options relevant only to raw graph, i.e., relevant only if no display type or output format is specified with the `-T' option. (See section Raw graph options.)
  5. Options requesting information (e.g., `--help'). (See section Informational options.)

@ifnottex The behavior of graph is also affected by a number of environment variables, so there is a section discussing them as well.

Plot options

The following options affect an entire plot. They should normally occur at most once, and should appear on the command line before the first file name. If a multiplot is being drawn, they may (with the exception of the `-T' option) occur more than once. If so, the second and later occurrences should be placed on the command line immediately after each `--reposition x y' option.

`-T type'
`--display-type type'
(String, default "meta".) Select a display type or output format of type type, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Window System, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the format used by Adobe Illustrator, idraw-editable Postscript, the format used by the xfig drawing editor, the Hewlett--Packard PCL 5 printer language, the Hewlett--Packard Graphics Language (by default, HP-GL/2), Tektronix format, and device-independent GNU graphics metafile format.
`-E x|y'
`--toggle-axis-end x|y'
Set the position of the indicated axis to be on the other end of the plotting box from what is currently the case. E.g., `-E y' will cause the y axis to appear on the right of the plot rather than the left, which is the default. Similarly, `-E x' will cause the x axis to appear at the top of the plot rather than the bottom. Note that if the x axis appears at the top, no plot title will be drawn (since there will be no room).
`-f size'
`--font-size size'
(Float, default 0.0525.) Set the size of the font used for the axis and tick labels to be size. The size is specified as a fraction of the minimum dimension (width or height) of the plotting box.
`-F font_name'
`--font-name font_name'
(String, default "Helvetica" except for graph -T pnm, graph -T gif, graph -T pcl, graph -T hpgl, graph -T tek, and raw graph, for all of which "HersheySerif" is the default.) Set the font used for the axis and tick labels, and for the plot title (if any), to be font_name. The choice of font for the plot title may be overridden with the `--title-font-name' option (see below). Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which `-T' option is used. For a list of all fonts, see section Available text fonts. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.
`-g grid_style'
`--grid-style grid_style'
(Integer in the range 0...4, default 2.) Set the grid style for the plot to be grid_style. Grid styles 0 through 3 are progressively more fancy, but style 4 is a somewhat different style.
  1. no axes, tick marks or labels.
  2. a pair of axes, with tick marks and labels.
  3. box around plot, with tick marks and labels.
  4. box around plot, with tick marks and labels; also grid lines.
  5. axes intersect at the origin, with tick marks and labels.
`-h height'
`--height-of-plot height'
(Float, default 0.6.) Set the fractional height of the plot with respect to the height of the display (or virtual display, in the case of a multiplot) to be height. A value of 1.0 will produce a plotting box that fills the available area. Note that tick marks and labels are outside the plotting box, so that values less than 1.0 are generally used.
`-k length'
`--tick-size length'
(Float, default .02.) Set the length of the tick marks on each axis to be length. A value of 1.0 produces tick marks whose length is equal to the minimum dimension (width or height) of the plotting box. A negative length yields tick marks that extend outside the box, rather than inside.
`-K clip_mode'
`--clip-mode clip_mode'
(Integer, default 1.) Set the clip mode for the plot to clip_mode. The clip mode is relevant only if data points are being joined by a line, and the line is not being filled to create a filled region (since filled regions are clipped in a fixed way). There are three clip modes: 0, 1, and 2. Clip mode 0 means that a line segment joining two data points will be plotted only if neither point is outside the plotting box. Clip mode 1 means that it will be plotted if no more than one of the two points is outside, and clip mode 2 means that it will be plotted even if both are outside. In all cases the line segment will be clipped to the plotting box.
`-l x|y'
`--toggle-log-axis x|y'
Set the specified axis to be a log axis rather than a linear axis, or vice versa. By default, both axes are linear axes.
`-L top_label'
`--top-label top_label'
(String, default empty.) Place the text string top_label above the plot, as its `top label', i.e., title. The string may include escape sequences (see section Text string format and escape sequences). The `--title-font-size' option may be used to specify the size of the font. The font is normally the same as the font used for labeling axes and ticks, as selected by the `-F' option. But this can be overridden with the `--title-font-name' option.
`-N x|y'
`--toggle-no-ticks x|y'
Toggle the presence of ticks and tick labels on the specified axis. This applies to the grid styles that normally include ticks and tick labels, i.e., grid styles 1, 2, 3, and 4.
`-r right'
`--right-shift right'
(Float, default 0.2.) Move the plot to the right by a fractional amount right with respect to the width of the display (or virtual display, in the case of a multiplot). This produces a margin on the left side of the plotting box. A value of 0.5 will produce a margin half the width of the available area. Note that the tick marks and labels are drawn in the margin.
`-R x|y'
`--toggle-round-to-next-tick x|y'
Toggle whether or not the upper and lower limits of the specified axis should be expanded, so that they both become integer multiples of the spacing between labeled tick marks. This option is meaningful whenever the user specifies either or both of the limits, by using the `-x' or `-y' option. If the user leaves both limits unspecified, they will always be chosen to satisfy the `integer multiple' constraint.
`-s'
`--save-screen'
Save the screen. This option requests that graph not erase the display device before it begins to plot. This option is relevant only to graph -T tek and raw graph. Tektronix displays and emulators are persistent, in the sense that previously drawn graphics remain visible. So by repeatedly using graph -T tek -s, you can build up a multiplot.
`-t'
`--toggle-transpose-axes'
Transpose the abscissa and ordinate. This causes the axes to be interchanged, and the options that apply to each axis to be applied to the opposite axis. That is, data points are read in as (y, x) pairs, and such options as `-x' and `-X' apply to the y axis rather than the x axis. If the `-I e' option is in force, so that the data points are read with error bars, the orientation of the error bars will be switched between vertical and horizontal.
`-u up'
`--upward-shift up'
(Float, default 0.2.) Move the plot up by a fractional amount up with respect to the height of the display (or virtual display, in the case of a multiplot). This produces a margin below the plotting box. A value of 0.5 will produce a margin half the height of the available area. Note that the tick marks and labels are drawn in the margin.
`-w width'
`--width-of-plot width'
(Float, default 0.6.) Set the fractional width of the plot with respect to the width of the display (or virtual display, in the case of a multiplot) to be width. A value of 1.0 will produce a plotting box that fills the available area. Note that the tick marks and labels are outside the plotting box, so values less than 1.0 are generally used.
`-x [lower_limit [upper_limit [spacing]]]'
`--x-limits [lower_limit [upper_limit [spacing]]]'
(Floats.) The arguments lower_limit and upper_limit specify the limits of the x axis, and the optional argument spacing specifies the spacing of labeled ticks along the axis. If any of the three arguments is missing or is supplied as `-' (i.e., as a single hyphen), it is computed from the data. Both arguments lower_limit and upper_limit must be present if graph is to act as a real-time filter. By default, the supplied limit(s) are strictly respected. However, the `-R x' option may be used to request that they be rounded to the nearest integer multiple of the spacing between labeled ticks. The lower limit will be rounded downward, and the upper limit upward.
`-X x_label'
`--x-label x_label'
(String, default empty.) Set the label for the x axis to be the text string x_label. The string may include escape sequences (see section Text string format and escape sequences). The `-F' and `-f' options may be used to specify the name of the font and the size of the font.
`-y [lower_limit [upper_limit [spacing]]]'
`--y-limits [lower_limit [upper_limit [spacing]]]'
(Floats.) The arguments specify the limits of the y axis, and the spacing of labeled ticks along it, as for the x axis (see above). Both arguments lower_limit and upper_limit must be present if graph is to act as a real-time filter. By default, the supplied limit(s) are strictly respected. However, the `-R y' option may be used to request that they be rounded to the nearest multiple of the tick spacing. The lower limit will be rounded downward, and the upper limit upward.
`-Y y_label'
`--y-label y_label'
(String, default empty.) Set the label for the y axis to be the text string y_label. The string may include escape sequences (see section Text string format and escape sequences). The label will be rotated by 90 degrees so that it is parallel to the axis, unless the `--toggle-rotate-y-label' option is used. Some old X Window System displays do not support rotated labels, and require the `--toggle-rotate-y-label' option. The `-F' and `-f' options can be used to specify the name of the font and the size of the font.
`--bg-color name'
(String, default "white".) Set the color used for the plot background to be name. This is relevant only to graph -T X, graph -T pnm, and graph -T gif. An unrecognized name sets the color to the default. For information on what names are recognized, see section Specifying Colors by Name. The environment variable BG_COLOR can equally well be used to specify the background color. If the `-T gif' option is used, a transparent pseudo-GIF may be produced by setting the TRANSPARENT_COLOR environment variable to the name of the background color. See section Environment variables.
`--bitmap-size bitmap_size'
(String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be bitmap_size. This is relevant only to graph -T X, graph -T pnm, and graph -T gif, for which the graphics display size can be expressed in terms of pixels. The environment variable BITMAPSIZE can equally well be used to specify the size. The graphics display used by graph -T X is an X window. If you choose a rectangular (non-square) window size, the fonts in the plot will be scaled anisotropically, i.e., by different factors in the horizontal and vertical direction. This requires an X11R6 display. Any font that cannot be scaled in this way will be replaced by a default scalable font, such as the Hershey vector font "HersheySerif". For backward compatibility, the X resource Xplot.geometry, which can be set by the user, may be used to set the window size, instead of `--bitmap-size' or BITMAPSIZE.
`--frame-color name'
(String, default "black".) Set the color used for drawing the plot frame, and for drawing monochrome datasets (if any) to be name. An unrecognized name sets the color to the default. For information on what names are recognized, see section Specifying Colors by Name.
`--frame-line-width frame_line_width'
(Float, default -1.0.) Set the thickness of lines in the plot frame, as a fraction of the size (i.e., minimum dimension) of the graphics display, to frame_line_width. A negative value means that the default value for the line thickness provided by the libplot graphics library should be used. This is usually 1/850 times the size of the display, although if `-T X', `-T pnm', or -T gif is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible. graph -T tek does not support drawing lines with other than a default thickness, and graph -T hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).
`--max-line-length max_line_length'
(Integer, default 500.) Set the maximum number of points that a polygonal line drawn through any dataset may contain, before it is flushed to the display device, to equal max_line_length. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. Splitting will not take place if the `-q' option, which requests filling, is used. The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable MAX_LINE_LENGTH can also be used to specify the maximum line length. This option has no effect on graph -T tek or raw graph, since they draw polylines in real time and have no buffer limitations.
`--page-size pagesize'
(String, default "letter".) Set the size of the page on which the plot will be positioned. This is relevant only to graph -T ai, graph -T ps, graph -T fig, graph -T pcl, and graph -T hpgl. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. The environment variable PAGESIZE can equally well be used to specify the page size. For graph -T ai and graph -T ps, the graphics display within which the plot is drawn will be a square region centered on the specified page, occupying its full width (with allowance being made for margins). For graph -T fig, it will be a square region of the same size, located in the upper left corner of an xfig display. For graph -T pcl and graph -T hpgl, the graphics display will be a square region of the same size, but may be positioned differently. Fine control over its positioning on the page can be accomplished by setting certain environment variables (see section Environment variables).
`--pen-colors colors'
(String, default "1=red:2=green:3=blue:4=magenta:5=cyan".) Set the colors of the pens used for drawing plots, as numbered, to be colors. The format should be self-explanatory. An unrecognized name sets the corresponding color to the default. For information on what names are recognized, see section Specifying Colors by Name.
`--rotation angle'
(Integer, default 0.) Set the rotation angle of the plot within the graphics display to be angle degrees. Recognized values are 0, 90, 180, and 270. The rotation is counterclockwise. This option is used for switching between portrait mode and landscape mode. Postmodernists may also find it useful.
`--title-font-name font_name'
(String, default "Helvetica" except for graph -T pnm, graph -T gif, graph -T pcl, graph -T hpgl and graph -T tek, for which "HersheySerif" is the default.) Set the font used for the plot title to be font_name. Normally the font used for the plot title is the same as that used for labeling the axes and the ticks along the axes, as specified by the `-F' option. But the `--title-font-name' option can be used to override this. Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which `-T' option is used. For a list of all fonts, see section Available text fonts. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.
`--title-font-size size'
(Float, default 0.07.) Set the size of the font used for the top label (`title'), as specified by the `-L' option, to be size. The size is specified as a fraction of the minimum dimension (width or height) of the plotting box.
`--toggle-rotate-y-label'
Position the label on the y axis (which is set with the `-Y' option) horizontally instead of vertically, or vice versa. By default the label is rotated, so that it is parallel to the y axis. But some display devices (e.g., old X Window System displays) cannot handle rotated fonts.

Dataset options

The following options affect the way in which individual datasets are read from files, and drawn as part of a plot. They should appear on the command line before the file containing the datasets whose reading or rendering they will affect. They may appear more than once on a command line, if more than one file is to be read.

The following three options affect the way in which datasets are read from files.

`-I data-format'
`--input-format data-format'
This specifies which format the subsequent input file(s) are in.
`a'
ASCII format. Each input file is a sequence of floating point numbers, interpreted as the x and y coordinates of the successive data points in a dataset. The x and y coordinates of a point need not appear on the same line, and points need not appear on different lines. But if a blank line occurs (i.e., two newlines in succession are seen), it is interpreted as the end of a dataset, and the beginning of the next.
`e'
ASCII format, including error bars. Similar to `a' format, except that triples (x,y,error) appear instead of pairs (x,y).
`g'
The ASCII `table' format produced by the gnuplot plotting program.
`f'
@ifnottex Single precision binary format. Each input file is a sequence of single precision floating point numbers, interpreted as forming pairs (x,y). Successive datasets are separated by a single occurrence of the quantity FLT_MAX, which is the largest possible single precision floating point number. On most machines this is approximately 3.4x10^38.
`d'
@ifnottex Double precision binary format. Each input file is a sequence of double precision floating point numbers, interpreted as forming pairs (x,y). Successive datasets are separated by a single occurrence of the quantity DBL_MAX, which is the largest possible double precision floating point number. On most machines this is approximately 1.8x10^308.
`i'
@ifnottex Integer binary format. Each input file is a sequence of integers, interpreted as forming pairs (x,y). Successive datasets are separated by a single occurrence of the quantity INT_MAX, which is the largest possible integer. On most machines this is 2^31-1.
`-a [step_size [lower_limit]]'
`--auto-abscissa [step_size [lower_limit]]'
(Floats, defaults 1.0 and 0.0.) Automatically generate abscissa (x) values. Irrespective of data format (`a', `e', `f', `d', or `i'), this option specifies that the abscissa (x) values are missing from the input file: the dataset(s) to be read contain only ordinate (y) values. The increment from each x value to the next will be step_size, and the first x value will be lower_limit. To return to reading abscissa values from the input, i.e., for subsequent input files, you would use `-a 0', which disables automatic generation of the abscissa values and returns step_size and lower_limit to their default values.
`-B'
`--toggle-auto-bump'
By default the linemode (set with `-m', see below) is `bumped' (incremented by unity) at the beginning of each new dataset. This option toggles auto-bumping: it turns it off if it was on, and on if it was off.

The following options affect the way in which individual datasets are drawn as part of a plot. These options set the six `attributes' (symbol type, symbol font, linemode, line thickness, fill fraction, and color/monochrome) that each dataset has.

`-m line_mode'
`--line-mode line_mode'
(Integer, default 1.) line_mode specifies the mode (i.e., style) of the lines drawn between successive points in a dataset. By convention, linemode #0 means no line at all (points are disconnected). If the dataset is being rendered in monochrome, the interpretation of line_mode is as follows.
  1. solid
  2. dotted
  3. dotdashed
  4. shortdashed
  5. longdashed
Thereafter (i.e., for line_mode greater than 5) the sequence of five linemodes repeats. So besides linemode #0, there are a total of five distinct monochrome linemodes. If the dataset is being rendered in color (as may be requested with the `-C' option), the interpretation of linemodes #1 through #5 is instead
  1. red, solid
  2. green, solid
  3. blue, solid
  4. magenta, solid
  5. cyan, solid
Linemodes #6 through #10 use the same five colors, but are dotted; linemodes #11 through #15 are dotdashed; linemodes #16 through #20 are shortdashed; and linemodes #21 through #25 are longdashed. So besides linemode #0, there are a total of 25 distinct colored linemodes. A negative linemode indicates that no line should be drawn, but that the plotting symbol, if any (see below), should be in the color of the corresponding positive linemode.
`-S [symbol_number [symbol_size]]'
`--symbol [symbol_number [symbol_size]]'
(Integer and float, defaults 0 and 0.03.) Draw a marker symbol at each data point. symbol_number specifies the symbol type, and symbol_size specifies the font size of the symbol, as a fraction of the minimum dimension (width or height) of the plotting box. If the dataset is being rendered in color, the symbol will have the color of the line that is being drawn to connect the data points. You may request that symbols be drawn without any line connecting them by using the `-m' option to specify a negative linemode (see above). The following table lists the first few marker symbols (by convention, symbol #0 means no symbol at all).
  1. dot
  2. plus (+)
  3. asterisk (*)
  4. circle
  5. cross
Marker symbols 0 through 31 are furnished by the libplot graphics library. See section Available marker symbols. Symbol numbers greater than or equal to 32 are interpreted as characters to be selected from a symbol font, which can be set with the `--symbol-font-name' option (see below).
`-W line_width'
`--line-width line_width'
(Float, default -1.0.) Set the thickness of the lines used to join successive points in a dataset, as a fraction of the size (i.e., minimum dimension) of the graphics display, to line_width. A negative value means that the default value for the line thickness provided by the libplot graphics library should be used. This is usually 1/850 times the size of the display, although if `-T X', `-T pnm', or -T gif is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible. graph -T tek does not support drawing lines with other than a default thickness, and graph -T hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).
`-q fill_fraction'
`--fill-fraction fill_fraction'
(Float, default -1.0.) If successive points in a dataset are joined by line segments, set the shading intensity for the polygon formed by the line segments to be fill_fraction. A solid polygon (i.e., one filled with the `pen color' used for drawing the line segments) is obtained by choosing fill_fraction=1.0. The interior of the polygon will be white if fill_fraction=0.0. The polygon will be unfilled (transparent) if fill_fraction is negative. If the polygon intersects itself, the `even-odd fill rule' will normally be used to determine which points are inside rather than outside, i.e., to determine which portions of the polygon should be shaded. The even-odd fill rule is explained in the Postscript Language Reference Manual. The `-q' option has no effect in graph -T tek, and it is only partly effective in graph -T hpgl if the environment variable HPGL_VERSION is set to "1".
`-C'
`--toggle-use-color'
Toggle between color and monochrome rendering of datasets. The interpretation of linemode depends on whether the rendering is being performed in color or monochrome; see the `-m' option above.
`--symbol-font-name symbol_font_name'
(String, default "ZapfDingbats" unless `-T pnm', `-T gif', `-T pcl', `-T hpgl', or -T tek is specified, in which case it is "HersheySerif".) Set the symbol font, from which plotting symbols numbered 32 and higher are selected, to be symbol_font_name. Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which `-T' option is used. For example, if the `-T pcl' or `-T hpgl' option is used then normally the Wingdings font, which is an alternative source of symbols, becomes available. For a list of all fonts, see section Available text fonts. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.

Multiplot options

The following options are used for multiplotting (placing several plots on a display, or a page, at once).

`--reposition x y size'
(Floats, defaults 0.0, 0.0, 1.0) Set the `virtual display' within which the next plot will be drawn to be a square of size size, with lower left corner (x,y). Normalized coordinates are used here: (0,0) means the lower left corner of the physical display and (1,1) means the upper right corner of the physical display. The size of the plot within the virtual display may be adjusted with the `-h' and `-w' options, and its position within the virtual display with the `-u' and `-w' options. After a `--reposition' command, the arguments of those four options will be interpreted in terms of the virtual display, not the physical display.
`--blankout blankout_fraction'
(Float, default 1.3.) When drawing each additional plot of a multiplot, it is desirable to clear the region of the display on which the plot will be drawn. If blankout_fraction=1.0, the region covered by the plot's plotting box will be cleared. If blankout_fraction=1.3, a region 30% larger in each dimension will be cleared. This is appropriate for inset plots; 1.0 would be appropriate for side by side plots. Note that graph -T tek cannot clear regions, and graph -T hpgl cannot clear them if the environment variables HPGL_VERSION and HPGL_OPAQUE_MODE are set to non-default values (i.e., values other than "2" and "yes", respectively).

Raw graph options

The following option is relevant only to raw graph, i.e., is relevant only if no display type or output format is specified with the `-T' option. In this case graph outputs a graphics metafile, which may be translated to other formats by invoking plot. This option should appear on the command line before any file names, since it affects the output of the plot (or multiplot) as a whole.

`-O'
`--portable-output'
Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable META_PORTABLE to "yes".

Informational options

The following options request information.

`--help'
Print a list of command-line options, and then exit.
`--help-fonts'
Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. graph -T X, graph -T ai, graph -T ps, and graph -T fig each support the 35 standard Postscript fonts. graph -T ai, graph -T pcl, and graph -T hpgl support the 45 standard PCL 5 fonts, and graph -T pcl and graph -T hpgl support a number of Hewlett--Packard vector fonts. All of the preceding, together with graph -T pnm, graph -T gif, and graph -T tek, support a set of 22 Hershey vector fonts. Raw graph in principle supports any of these fonts, since its output must be translated to other formats with plot. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.
`--list-fonts'
Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed.
`--version'
Print the version number of graph and the plotting utilities package, and exit.

Environment variables

The behavior of graph is affected by several environment variables. We have already mentioned the environment variables BITMAPSIZE, PAGESIZE, BG_COLOR, and MAX_LINE_LENGTH. They serve as backups for the options `--bitmap-size', `--page-size', `--bg-color', and `--max-line-length'. The remaining environment variables are specific to individual output formats.

graph -T X, which pops up a window on an X Window System display and draws graphics in it, checks the DISPLAY environment variable. The value of this variable determines the display on which the window will be popped up.

graph -T pnm, which produces output in Portable Anymap (PBM/PGM/PPM) format, is affected by the PNM_PORTABLE environment variable. If its value is "yes", the output file will be in the portable (human readable) version of PBM, PGM, or PPM format, rather than the default (binary) version.

graph -T gif, which produces output in pseudo-GIF format, is affected by two environment variables. If the value of the INTERLACE variable is "yes", the pseudo-GIF output file will be in interlaced format. Also, if the value of the TRANSPARENT_COLOR environment variable is the name of a color that appears in the output file, that color will be treated as transparent by most applications that read GIF files. For information on what color names are recognized, see section Specifying Colors by Name.

graph -T pcl, which produces PCL 5 output for Hewlett--Packard printers and plotters, is affected by several environment variables. The position of the graphics display on the page can be adjusted by setting the PCL_XOFFSET and PCL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the PCL_ROTATE environment variable to "yes". This is not the same as the rotation obtained with the --rotation option, which sets the rotation angle of the plot within the display. Besides "no" and "yes", recognized values for the PCL_ROTATE variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively.

The variable PCL_ASSIGN_COLORS is also recognized. It should be set to "yes" when producing PCL 5 output for a color printer or other color device. This will ensure accurate color reproduction by giving the output device complete freedom in assigning colors, internally, to its "logical pens". If it is "no" then the device will use a fixed set of colored pens, and will emulate other colors by shading. The default is "no" because monochrome PCL 5 devices, which are much more common than colored ones, must use shading to emulate color.

graph -T hpgl, which produces Hewlett--Packard Graphics Language output, is also affected by several environment variables. The most important is HPGL_VERSION, which may be set to "1", "1.5", or "2" (the default). "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2. If the version is "1" or "1.5" then the only available fonts will be vector fonts, and all lines will be drawn with a default thickness (the `-W' option will not work). Additionally, if the version is "1" then the filling of arbitrary curves with solid color will not be supported (the `-q' option may be used to fill circles and rectangles aligned with the coordinate axes, though).

The position of the graph -T hpgl graphics display on the page can be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the HPGL_ROTATE environment variable to "yes". This is not the same as the rotation obtained with the --rotation option, which sets the rotation angle of the plot within the display. Besides "no" and "yes", recognized values for the HPGL_ROTATE variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively. "180" and "270" are supported only if HPGL_VERSION is "2" (the default).

Opaque filling and the drawing of visible white lines are supported only if HPGL_VERSION is "2" (the default) and the environment variable HPGL_OPAQUE_MODE is "yes" (the default). If the value is "no" then opaque filling will not be used, and white lines (if any), which are normally drawn with pen #0, will not be drawn. This feature is to accommodate older HP-GL/2 devices. HP-GL/2 pen plotters, for example, do not support opacity or the use of pen #0 to draw visible white lines. Some older HP-GL/2 devices reportedly malfunction if asked to draw opaque objects.

By default, graph -T hpgl will draw with a fixed set of pens. Which pens are present may be specified by setting the HPGL_PENS environment variable. If HPGL_VERSION is "1", the default value of HPGL_PENS is "1=black"; if HPGL_VERSION is "1.5" or "2", the default value of HPGL_PENS is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan". The format should be self-explanatory. By setting HPGL_PENS, you may specify a color for any pen in the range #1...#31. For information on what color names are recognized, see section Specifying Colors by Name. Pen #1 must always be present, though it need not be black. Any other pen in the range #1...#31 may be omitted.

If HPGL_VERSION is "2" then graph -T hpgl will also be affected by the environment variable HPGL_ASSIGN_COLORS. If the value of this variable is "yes", then graph -T hpgl will not be restricted to the palette specified in HPGL_PENS: it will assign colors to "logical pens" in the range #1...#31, as needed. The default value is "no" because other than color LaserJet printers and DesignJet plotters, not many HP-GL/2 devices allow the assignment of colors to logical pens.

graph -T tek, which produces output for a Tektronix terminal or emulator, checks the TERM environment variable. If the value of TERM is "xterm", "xterms", or "kterm", it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm. Before drawing graphics, graph -T tek will emit an escape sequence that causes the terminal emulator's auxiliary Tektronix window, which is normally hidden, to pop up. After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted. The Tektronix window will remain on the screen.

If the value of TERM is "kermit", "ansi.sys", "ansissys", "ansi.sysk", or "ansisysk", it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the MS-DOS version of kermit. Before drawing graphics, graph -T tek will emit an escape sequence that switches the terminal emulator to Tektronix mode. Also, some of the Tektronix control codes emitted by graph -T tek will be kermit-specific. There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported). After drawing graphics, graph -T tek will emit an escape sequence that returns the emulator to VT100 mode. The key sequence `ALT minus' can be employed manually within kermit to switch between the two modes.

The plot Program

How to use plot

The GNU plot filter plot displays GNU graphics metafiles or translates them to other formats. It will take input from files specified on the command line or from standard input. The `-T' option is used to specify the desired output format. Supported output formats include "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta" (the default).

The metafile format is a device-independent format for storage of vector graphics. By default, it is a binary rather than a human-readable format (see section The Graphics Metafile Format). Each of the graph, pic2plot, tek2plot, and plotfont utilities will write a graphics metafile to standard output if no `-T' option is specified on its command line. The libplot graphics library may also be used to produce metafiles. Metafiles may contain arbitrarily many pages of graphics, but each metafile produced by graph contains only a single page.

plot, like the metafile format itself, is useful if you wish to preserve a vector graphics file, and display or edit it with more than one drawing editor. The following example shows how you may do this.

To produce a plot of data arranged as alternating x and y coordinates in an ASCII file, you may use graph as follows:

graph < ascii_data_file > test.meta

The file `test.meta' will be a single-page graphics metafile. Similarly, to create in metafile format a plot consisting of a simple figure, you may do:

echo 0 0 1 1 2 0 | spline | graph > test.meta

To display any such plot on an X Window System display, you would do

plot -T X test.meta

or

plot -T X < test.meta

To print the plot on a Postscript printer, you would do something like

plot -T ps < test.meta | lpr

To edit it with the free idraw drawing editor, you would do

plot -T ps < test.meta > test.ps
idraw test.ps

To produce a "portable anymap" (a file in PBM, PGM, or PPM format, whichever is most appropriate) you would do

plot -T pnm < test.meta > test.pnm

and to produce a pseudo-GIF file, you would do

plot -T gif < test.meta > test.gif

Similarly, to produce a version of the plot that can be edited with Adobe Illustrator, you would do

plot -T ai < test.meta > test.ai

and to produce a version that can be edited with the free xfig drawing editor, you would do

plot -T fig < test.meta > test.fig
xfig test.fig

Other formats may be obtained by using plot -T pcl, plot -T hpgl, and plot -T tek.

plot may behave differently depending on the environment in which it is invoked. In particular, plot -T ai, plot -T ps, plot -T fig, plot -T pcl, and plot -T hpgl are affected by the environment variable PAGESIZE. plot -T X, plot -T pnm, and plot -T gif are affected by the environment variable BITMAPSIZE. The DISPLAY environment variable affects the operation of plot -T X, and the TERM environment variable affects the operation of plot -T tek. There are also several environment variables that affect the operation of plot -T pcl and plot -T hpgl. For a complete discussion of the effects of the environment on plot, see section Environment variables.

plot command-line options

The plot filter plot translates GNU graphics metafiles to other formats. The `-T' option is used to specify the output format or display type. Files in metafile format are produced by GNU graph, pic2plot, tek2plot, plotfont, and other applications that use the GNU libplot graphics library. For technical details on the metafile format, see section The Graphics Metafile Format.

Input file names may be specified anywhere on the command line. That is, the relative order of file names and command-line options does not matter. If no file names are specified, or the file name `-' is specified, the standard input is read. The output file is written to standard output, unless the `-T X' option is specified. In that case the output is displayed in a window or windows on an X Window System display, and there is no output file.

The full set of command-line options is listed below. There are four sorts of option:

  1. Options setting the values of drawing parameters.
  2. Options relevant only to raw plot, i.e., relevant only if no display type or output format is specified with the `-T' option.
  3. Options specifying the type of metafile format the input is in (for backward compatibility only).
  4. Options requesting information (e.g., `--help').

Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.

The following options set the values of drawing parameters.

`-T type'
`--display-type type'
(String, default "meta".) Select a display type or output format of type type, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Window System, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the format used by Adobe Illustrator, idraw-editable Postscript, the format used by the xfig drawing editor, the Hewlett--Packard PCL 5 printer language, the Hewlett--Packard Graphics Language (by default, HP-GL/2), Tektronix format, and device-independent GNU graphics metafile format.
`-p n'
`--page-number n'
(Positive integer.) Display only page number n, within the metafile or sequence of metafiles that is being translated. Metafiles may consist of one or more pages, numbered beginning with 1. Also, each page may contain multiple `frames'. plot -T X or plot -T tek, which plot in real time, will separate successive frames by screen erasures. plot -T pnm, plot -T gif, plot -T ai, plot -T ps, plot -T fig, plot -T pcl, and plot -T hpgl, which do not plot in real time, will display only the last frame of any multi-frame page. The default behavior, if `-p' is not used, is to display all pages. For example, plot -T X displays each page in its own X window. If the `-T pnm' option, the `-T gif' option, the `-T ai' option, or the `-T fig' option is used, the default behavior is to display only the first page, since files in PNM, pseudo-GIF, AI, or Fig format may contain only a single page of graphics. Most metafiles produced by the GNU plotting utilities (e.g., by raw graph) contain only a single page, consisting of two frames: an empty one to clear the display, and a second one containing graphics.
`-s'
`--merge-pages'
Merge all displayed pages into a single page, and also merge all `frames' within each displayed page. This option is useful when merging together single-page plots from different sources. For example, it can be used to merge together plots obtained from separate invocations of graph. This is an alternative form of multiplotting (see section Multiplotting: placing multiple plots on a single page).
`--bitmap-size bitmap_size'
(String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be bitmap_size. This is relevant only to plot -T X, plot -T pnm, and plot -T gif, for which the graphics display size can be expressed in terms of pixels. The environment variable BITMAPSIZE can equally well be used to specify the size. For backward compatibility, the X resource Xplot.geometry, which can be set by the user, may be used to set the window size, instead of `--bitmap-size' or BITMAPSIZE.
`--max-line-length max_line_length'
(Integer, default 500.) Set the maximum number of points that a polygonal line may contain, before it is flushed to the display device, to equal max_line_length. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. Splitting will not take place if the line is the boundary of a filled polygon. The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable MAX_LINE_LENGTH can also be used to specify the maximum line length. This option has no effect on plot -T tek or raw plot, since they draw polylines in real time and have no buffer limitations.
`--page-size pagesize'
(String, default "letter".) Set the size of the page on which the plot will be positioned. This is relevant only to plot -T ai, plot -T ps, plot -T fig, plot -T pcl, and plot -T hpgl. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. The environment variable PAGESIZE can equally well be used to specify the page size. For plot -T ai and plot -T ps, the graphics display within which the plot is drawn will be a square region centered on the specified page, occupying its full width (with allowance being made for margins). For plot -T fig, it will be a square region located of the same size, located in the upper left corner of an xfig display. For plot -T pcl and plot -T hpgl, the graphics display will be a square region of the same size, but may be positioned differently. Fine control over its positioning on the page may be accomplished by setting certain environment variables (see section Environment variables).

The following options set the initial values of additional drawing parameters. All of these may be overridden by directives in the metafile itself. In fact, these options are useful mostly for plotting old metafiles in the pre-GNU `plot(5)' format, which did not include such directives.

`--bg-color name'
(String, default "white".) Set the color used for the plot background to be name. This is relevant only to plot -T X, plot -T pnm, and plot -T gif. An unrecognized name sets the color to the default. For information on what names are recognized, see section Specifying Colors by Name. The environment variable BG_COLOR can equally well be used to specify the background color. If the `-T gif' option is used, a transparent pseudo-GIF may be produced by setting the TRANSPARENT_COLOR environment variable to the name of the background color. See section Environment variables.
`-f font_size'
`--font-size font_size'
(Float, initial value device-dependent.) Set the initial size of the font used for rendering text, as a fraction of the width of the graphics display, to font_size.
`-F font_name'
`--font-name font_name'
(String, default "Helvetica" except for plot -T pnm, plot -T gif, plot -T pcl, plot -T hpgl, plot -T tek, and raw plot, for all of which "HersheySerif" is the default.) Set the font initially used for text (i.e., for `labels') to font_name. Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which `-T' option is used. For a list of all fonts, see section Available text fonts. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.
`-W line_width'
`--line-width line_width'
(Float, default -1.0.) Set the thickness of lines, as a fraction of the size (i.e., minimum dimension) of the graphics display, to line_width. A negative value means that the default value provided by the libplot graphics library should be used. This is usually 1/850 times the size of the display, although if `-T X', `-T pnm', or -T gif is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible. plot -T tek does not support drawing lines with other than a default thickness, and plot -T hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).
`--pen-color name'
(String, default "black".) Set the pen color to be name. An unrecognized name sets the pen color to the default. For information on what color names are recognized, see section Specifying Colors by Name.

The following option is relevant only to raw plot, i.e., relevant only if no output type is specified with the `-T' option. In this case plot outputs a graphics metafile, which may be translated to other formats by a second invocation of plot.

`-O'
`--portable-output'
Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable META_PORTABLE to "yes".

plot will automatically determine which type of GNU metafile format the input is in. There are two types: binary (the default) and portable (human-readable). The binary format is machine-dependent. See section The Graphics Metafile Format.

For compatibility with older plotting software, the reading of input files in the pre-GNU `plot(5)' format is also supported. This is normally a binary format, with each integer in the metafile represented as a pair of bytes. The order of the two bytes is machine dependent. You may specify that input file(s) are in plot(5) format rather than ordinary GNU metafile format by using either the `-h' option ("high byte first") or the `-l' option ("low byte first"), whichever is appropriate. Some non-GNU systems support an ASCII (human-readable) variant of plot(5) format. You may specify that the input is in this format by using the `-A' option. Irrespective of the variant, a file in plot(5) format includes only one page of graphics.

`-h'
`--high-byte-first-input'
Input file(s) are assumed to be in traditional `plot(5)' metafile format, with the high-order byte of each integer occurring first.
`-l'
`--low-byte-first-input'
Input file(s) are assumed to be in traditional `plot(5)' metafile format, with the low-order byte of each integer occurring first.
`-A'
`--ascii-input'
Input file(s) are assumed to be in the ASCII variant of traditional `plot(5)' metafile format.

The following options request information.

`--help'
Print a list of command-line options, and then exit.
`--help-fonts'
Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. plot -T X, plot -T ai, plot -T ps, and plot -T fig each support the 35 standard Postscript fonts. plot -T ai, plot -T pcl, and plot -T hpgl support the 45 standard PCL 5 fonts, and plot -T pcl and plot -T hpgl support a number of Hewlett--Packard vector fonts. All of the preceding, together with plot -T pnm, plot -T gif, and plot -T tek, support a set of 22 Hershey vector fonts. Raw plot in principle supports any of these fonts, since its output must be translated to other formats with plot. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.
`--list-fonts'
Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed.
`--version'
Print the version number of plot and the plotting utilities package, and exit.

Environment variables

The behavior of plot is affected by several environment variables. We have already mentioned the environment variables BITMAPSIZE, PAGESIZE, BG_COLOR, and MAX_LINE_LENGTH. They serve as backups for the options `--bitmap-size', `--page-size', `--bg-color', and `--max-line-length'. The remaining environment variables are specific to individual output formats.

plot -T X, which pops up a window on an X Window System display and draws graphics in it, checks the DISPLAY environment variable. The value of this variable determines the display on which the window will be popped up.

plot -T pnm, which produces output in Portable Anymap (PBM/PGM/PPM) format, is affected by the PNM_PORTABLE environment variable. If its value is "yes", the output file will be in the portable (human readable) version of PBM, PGM, or PPM format, rather than the default (binary) version.

plot -T gif, which produces output in pseudo-GIF format, is affected by two environment variables. If the value of the INTERLACE variable is "yes", the pseudo-GIF output file will be in interlaced format. Also, if the value of the TRANSPARENT_COLOR environment variable is the name of a color that appears in the output file, that color will be treated as transparent by most applications that read GIF files. For information on what color names are recognized, see section Specifying Colors by Name.

plot -T pcl, which produces PCL 5 output for Hewlett--Packard printers and plotters, is affected by several environment variables. The position of the graphics display on the page can be adjusted by setting the PCL_XOFFSET and PCL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the PCL_ROTATE environment variable to "yes". Besides "no" and "yes", recognized values for this variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively.

The variable PCL_ASSIGN_COLORS is also recognized. It should be set to "yes" when producing PCL 5 output for a color printer or other color device. This will ensure accurate color reproduction by giving the output device complete freedom in assigning colors, internally, to its "logical pens". If it is "no" then the device will use a fixed set of colored pens, and will emulate other colors by shading. The default is "no" because monochrome PCL 5 devices, which are much more common than colored ones, must use shading to emulate color.

plot -T hpgl, which produces Hewlett--Packard Graphics Language output, is also affected by several environment variables. The most important is HPGL_VERSION, which may be set to "1", "1.5", or "2" (the default). "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2. If the version is "1" or "1.5" then the only available fonts will be vector fonts, and all lines will be drawn with a default thickness (the `-W' option will not work). Additionally, if the version is "1" then the filling of arbitrary curves with solid color will not be supported (circles and rectangles aligned with the coordinate axes may be filled, though).

The position of the plot -T hpgl graphics display on the page can be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the HPGL_ROTATE environment variable to "yes". Besides "no" and "yes", recognized values for this variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively. "180" and "270" are supported only if HPGL_VERSION is "2" (the default).

Opaque filling and the drawing of visible white lines are supported only if HPGL_VERSION is "2" (the default) and the environment variable HPGL_OPAQUE_MODE is "yes" (the default). If the value is "no" then opaque filling will not be used, and white lines (if any), which are normally drawn with pen #0, will not be drawn. This feature is to accommodate older HP-GL/2 devices. HP-GL/2 pen plotters, for example, do not support opacity or the use of pen #0 to draw visible white lines. Some older HP-GL/2 devices reportedly malfunction if asked to draw opaque objects.

By default, plot -T hpgl will draw with a fixed set of pens. Which pens are present may be specified by setting the HPGL_PENS environment variable. If HPGL_VERSION is "1", the default value of HPGL_PENS is "1=black"; if HPGL_VERSION is "1.5" or "2", the default value of HPGL_PENS is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan". The format should be self-explanatory. By setting HPGL_PENS, you may specify a color for any pen in the range #1...#31. For information on what color names are recognized, see section Specifying Colors by Name. Pen #1 must always be present, though it need not be black. Any other pen in the range #1...#31 may be omitted.

If HPGL_VERSION is "2" then plot -T hpgl will also be affected by the environment variable HPGL_ASSIGN_COLORS. If the value of this variable is "yes", then plot -T hpgl will not be restricted to the palette specified in HPGL_PENS: it will assign colors to "logical pens" in the range #1...#31, as needed. The default value is "no" because other than color LaserJet printers and DesignJet plotters, not many HP-GL/2 devices allow the assignment of colors to logical pens.

plot -T tek, which produces output for a Tektronix terminal or emulator, checks the TERM environment variable. If the value of TERM is "xterm", "xterms", or "kterm", it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm. Before drawing graphics, plot -T tek will emit an escape sequence that causes the terminal emulator's auxiliary Tektronix window, which is normally hidden, to pop up. After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted. The Tektronix window will remain on the screen.

If the value of TERM is "kermit", "ansi.sys", "ansissys", "ansi.sysk", or "ansisysk", it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the MS-DOS version of kermit. Before drawing graphics, plot -T tek will emit an escape sequence that switches the terminal emulator to Tektronix mode. Also, some of the Tektronix control codes emitted by plot -T tek will be kermit-specific. There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported). After drawing graphics, plot -T tek will emit an escape sequence that returns the emulator to VT100 mode. The key sequence `ALT minus' can be employed manually within kermit to switch between the two modes.

The pic2plot Program

What pic2plot is used for

The pic2plot program takes one or more files in the pic language, and either displays the figures that they contain on an X Window System display, or produces an output file containing the figures. Many graphics file formats are supported.

The pic language is a `little language' that was developed at Bell Laboratories for creating box-and-arrow diagrams of the kind frequently found in technical papers and textbooks. A directory containing documentation on the pic language is distributed along with the plotting utilities. On most systems it is installed as `/usr/share/pic2plot' or `/usr/local/share/pic2plot'. The directory includes Brian Kernighan's original technical report on the language, Eric Raymond's tutorial on the GNU implementation, and some sample pic macros contributed by W. Richard Stevens.

The pic language was originally designed to work with the troff document formatter. In that context it is read by a translator called pic, or its GNU counterpart gpic. Since extensive documentation on pic and gpic is available, this section simply gives an example of an input file, and mentions some extra features supported by pic2plot.

A pic file contains one or more figures, each of the box-and-arrow type. Each figure is begun by a line reading .PS, and ended by a line reading .PE. Lines that are not contained in a .PS....PE pair are ignored. Each figure is built from geometrical objects, such as rectangular boxes, circles, ellipses, quarter circles ("arcs"), polygonal lines, and splines. Arcs, polygonal lines, and spline may be equipped with arrowheads. Any object may be labeled with text.

Objects are usually positioned not by specifying their positions in absolute coordinates, but rather by specifying their positions relative to other, previously drawn objects. The following figure is an example.

.PS
box "START"; arrow; circle dashed filled; arrow
circle diam 2 thickness 3 "This is a" "big, thick" "circle" dashed; up
arrow from top of last circle; ellipse "loopback" dashed
arrow dotted from left of last ellipse to top of last box
arc cw radius 1/2 from top of last ellipse; arrow
box "END"
.PE

If you put this example in a file and run `pic2plot -T X' on the file, a window containing the figure will be popped up on your X display. Similarly, if you run `pic2plot -T ps' on the file, a Postscript file containing the figure will be written to standard output. The Postscript file may be edited with the idraw drawing editor. Other graphics formats such as PNM format, pseudo-GIF format, or Fig format (which is editable with the xfig drawing editor) may be obtained similarly. You would use the options `-T pnm', `-T gif', and `-T fig', respectively.

The above example illustrates some of the features of the pic language. By default, successive objects are drawn so as to touch each other. The drawing proceeds in a certain direction, which by default is left-to-right. The `up' command changes this direction to bottom-to-top, so that the next object (the arrow extending from the top of the big circle) will point upward rather than to the right.

Objects have sizes and other attributes, which may be set globally, or specified on a per-object basis. For example, the diameter of a circle may be specified, or the radius of an arc. An arc may be oriented clockwise rather than counterclockwise by specifying the `cw' attribute. The line style of most objects may be altered by specifying the `dashed' or `dotted' attribute. Also, any object may be labeled, by specifying one or more text strings as attributes. A text string may contain escape sequences that shift the font, append subscripts or superscripts, or include non-ASCII characters and mathematical symbols. See section Text string format and escape sequences.

Most sizes and positions are expressed in terms of `virtual inches'. The use of virtual inches is peculiar to pic2plot. The graphics display used by pic2plot, i.e., its drawing region, is defined to be a square, 8 virtual inches wide and 8 virtual inches high. If the page size for the output file is the "letter" size, which is the default for Postscript output, virtual inches will the same as real inches. But a different page size may be specified; for example, by using the `--page-size a4' option. If so, a virtual inch will simply equal one-eighth of the width of the graphics display.

By default, each figure is centered in the graphics display. You may turn off centering, so that you can use absolute coordinates, by using the `-n' option. For example, a figure consisting only of the object `arrow from (8,8) to (4,4)' will be positioned in the absence of centering so that the tip of the arrow is at the center of the display. Its tail will be at the upper right corner.

The thickness of lines is not specified in terms of virtual inches. For compatibility with gpic, it is measured in terms of virtual points. The example above, which specifies the `thickness' attribute of one of the objects, illustrates this. There are 72 virtual points per virtual inch.

If there is more than one figure to be displayed, they will appear in different X windows, or on successive pages of the output file. Some output formats (such as PNM, pseudo-GIF, Illustrator, and Fig) support only a single page of graphics. If any of those output formats is chosen, only the first figure will appear in the output file. Currently, pic2plot cannot produce animated pseudo-GIFs.

The preceding survey does not do justice to the pic language, which is actually a full-featured programming language, with support for variables, looping constructs, etc. Its advanced features make the drawing of large, repetitive diagrams quite easy.

pic2plot command-line options

The pic2plot program translates files in the pic language, which is used for creating box-and-arrow diagrams of the kind frequently found in technical papers and textbooks, to other graphics formats. The output format or display type is specified with the `-T' option. The possible output formats are the same ten formats that are supported by the GNU graph and plot programs.

Input file names may be specified anywhere on the command line. That is, the relative order of file names and command-line options does not matter. If no file names are specified, or the file name `-' is specified, the standard input is read. The output file is written to standard output, unless the `-T X' option is specified. In that case the output is displayed in one or more windows on an X Window System display, and there is no output file.

The full set of command-line options is listed below. There are three sorts of option:

  1. General options.
  2. Options relevant only to raw pic2plot, i.e., relevant only if no display type or output format is specified with the `-T' option.
  3. Options requesting information (e.g., `--help').

Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.

The following are general options.

`-T type'
`--display-type type'
(String, default "meta".) Select a display type or output format of type type, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Window System, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the format used by Adobe Illustrator, idraw-editable Postscript, the format used by the xfig drawing editor, the Hewlett--Packard PCL 5 printer language, the Hewlett--Packard Graphics Language (by default, HP-GL/2), Tektronix format, and device-independent GNU graphics metafile format.
`-d'
`--precision-dashing'
Draw dashed and dotted lines carefully, i.e., draw each dash and dot as a separate object, so that they may be positioned individually. The default is to use the support for dashed and dotted lines provided by the underlying graphics library, libplot. This option may produce slightly better-looking dashed and dotted lines. However, it will come at a price: if an editable output file is produced (i.e., an output file in Illustrator, Postscript or Fig format), it will be difficulty to modify its dashed and dotted lines with a drawing editor.
`-f font_size'
`--font-size font_size'
(Float, default 0.0175.) Set the size of the font used for rendering text, as a fraction of the width of the graphics display, to font_size.
`-F font_name'
`--font-name font_name'
(String, default "Helvetica" except for pic2plot -T pnm, pic2plot -T gif, pic2plot -T pcl, pic2plot -T hpgl, pic2plot -T tek, and raw pic2plot, for all of which "HersheySerif" is the default.) Set the font used for text to font_name. Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which `-T' option is used. For a list of all fonts, see section Available text fonts. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.
`-n'
`--no-centering'
Turn off the automatic centering of each figure. If this option is specified, the position of the objects in each figure may be specified in terms of absolute coordinates. E.g., "line from (0,0) to (4,4)" will draw a line segment from the lower left corner to the center of the graphics display, since the display width and display height are defined to equal 8 virtual inches.
`-W line_width'
`--line-width line_width'
(Float, default -1.0.) Set the default thickness of lines, as a fraction of the size (i.e., minimum dimension) of the graphics display, to line_width. A negative value means that the default value provided by the libplot graphics library should be used. This is usually 1/850 times the size of the display, although if `-T X', `-T pnm', or -T gif is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible. pic2plot -T hpgl does not support drawing lines with other than a default thickness if the environment variable HPGL_VERSION is set to a value less than "2" (the default).
`--bg-color name'
(String, default "white".) Set the color used for the background to be name. This is relevant only to pic2plot -T X, pic2plot -T pnm, and pic2plot -T gif. An unrecognized name sets the color to the default. For information on what names are recognized, see section Specifying Colors by Name. The environment variable BG_COLOR can equally well be used to specify the background color. If the `-T gif' option is used, a transparent pseudo-GIF may be produced by setting the TRANSPARENT_COLOR environment variable to the name of the background color. See section Environment variables.
`--bitmap-size bitmap_size'
(String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be bitmap_size. This is relevant only to pic2plot -T X, pic2plot -T pnm, and pic2plot -T gif, for which the graphics display size can be expressed in terms of pixels. The environment variable BITMAPSIZE can equally well be used to specify the size. The graphics display used by pic2plot -T X is an X window; i.e., one window for each figure. If you choose a rectangular (non-square) window size, the fonts in each figure will be scaled anisotropically, i.e., by different factors in the horizontal and vertical direction. This requires an X11R6 display. Any font that cannot be scaled in this way will be replaced by a default scalable font, such as the Hershey vector font "HersheySerif". For backward compatibility, the X resource Xplot.geometry, which can be set by the user, may be used to set the window size, instead of `--bitmap-size' or BITMAPSIZE.
`--max-line-length max_line_length'
(Integer, default 500.) Set the maximum number of points that a polygonal line may contain, before it is flushed to the display device, to equal max_line_length. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable MAX_LINE_LENGTH can also be used to specify the maximum line length. This option has no effect on raw pic2plot, since it draws polylines in real time and has no buffer limitations.
`--page-size pagesize'
(String, default "letter".) Set the size of the page on which each figure will be positioned. This is relevant only to pic2plot -T ai, pic2plot -T ps, pic2plot -T fig, pic2plot -T pcl, and pic2plot -T hpgl. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. The environment variable PAGESIZE can equally well be used to specify the page size. For pic2plot -T ai and pic2plot -T ps, the graphics display within which each figure is drawn will be a square region centered on the specified page, occupying its full width (with allowance being made for margins). For pic2plot -T fig, it will be a square region of the same size, located in the upper left corner of an xfig display. For pic2plot -T pcl and pic2plot -T hpgl, the graphics display will be a square region of the same size, but may be positioned differently. Fine control its positioning on the page can be accomplished by setting certain environment variables (see section Environment variables).
`--pen-color name'
(String, default "black".) Set the pen color to be name. An unrecognized name sets the pen color to the default. For information on what color names are recognized, see section Specifying Colors by Name.
`--rotation angle'
(Integer, default 0.) Set the rotation angle of each figure within the graphics display to be angle degrees. Recognized values are 0, 90, 180, and 270. The rotation is counterclockwise. This option is used for switching between portrait mode and landscape mode. Postmodernists may also find it useful.

The following option is relevant only to raw pic2plot, i.e., relevant only if no display type or output format is specified with the `-T' option. In this case pic2plot outputs a graphics metafile, which may be translated to other formats by invoking plot.

`-O'
`--portable-output'
Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable META_PORTABLE to "yes".

The following options request information.

`--help'
Print a list of command-line options, and then exit.
`--help-fonts'
Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. pic2plot -T X, pic2plot -T ai, pic2plot -T ps, and pic2plot -T fig each support the 35 standard Postscript fonts. pic2plot -T ai, pic2plot -T pcl, and pic2plot -T hpgl support the 45 standard PCL 5 fonts, and pic2plot -T pcl and pic2plot -T hpgl support a number of Hewlett--Packard vector fonts. All of the preceding, together with pic2plot -T pnm, pic2plot -T gif, and pic2plot -T tek, support a set of 22 Hershey vector fonts. Raw pic2plot in principle supports any of these fonts, since its output must be translated to other formats with plot. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.
`--list-fonts'
Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed.
`--version'
Print the version number of pic2plot and the plotting utilities package, and exit.

Environment variables

The behavior of pic2plot is affected by several environment variables. We have already mentioned the environment variables BITMAPSIZE, PAGESIZE, BG_COLOR, and MAX_LINE_LENGTH. They serve as backups for the options `--bitmap-size', `--page-size', `--bg-color', and `--max-line-length'. The remaining environment variables are specific to individual output formats.

pic2plot -T X, which pops up a window on an X Window System display for each figure, checks the DISPLAY environment variable. The value of this variable determines the display on which the windows will be popped up.

pic2plot -T pnm, which produces output in Portable Anymap (PBM/PGM/PPM) format, is affected by the PNM_PORTABLE environment variable. If its value is "yes", the output file will be in the portable (human readable) version of PBM, PGM, or PPM format, rather than the default (binary) version.

pic2plot -T gif, which produces output in pseudo-GIF format, is affected by two environment variables. If the value of the INTERLACE variable is "yes", the pseudo-GIF output file will be in interlaced format. Also, if the value of the TRANSPARENT_COLOR environment variable is the name of a color that appears in the output file, that color will be treated as transparent by most applications that read GIF files. For information on what color names are recognized, see section Specifying Colors by Name.

pic2plot -T pcl, which produces PCL 5 output for Hewlett--Packard printers and plotters, is affected by several environment variables. The position of the graphics display on the page can be adjusted by setting the PCL_XOFFSET and PCL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the PCL_ROTATE environment variable to "yes". Besides "no" and "yes", recognized values for this variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively.

The variable PCL_ASSIGN_COLORS is also recognized. It should be set to "yes" when producing PCL 5 output for a color printer or other color device. This will ensure accurate color reproduction by giving the output device complete freedom in assigning colors, internally, to its "logical pens". If it is "no" then the device will use a fixed set of colored pens, and will emulate other colors by shading. The default is "no" because monochrome PCL 5 devices, which are much more common than colored ones, must use shading to emulate color.

pic2plot -T hpgl, which produces Hewlett--Packard Graphics Language output, is also affected by several environment variables. The most important is HPGL_VERSION, which may be set to "1", "1.5", or "2" (the default). "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2. If the version is "1" or "1.5" then the only available fonts will be vector fonts, and all lines will be drawn with a default thickness (the `-W' option will not work). Additionally, if the version is "1" then the filling of arbitrary curves with solid color will not be supported (circles and rectangles aligned with the coordinate axes may be filled, though).

The position of the pic2plot -T hpgl graphics display on the page can be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the HPGL_ROTATE environment variable to "yes". Besides "no" and "yes", recognized values for this variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively. "180" and "270" are supported only if HPGL_VERSION is "2" (the default).

Opaque filling and the drawing of visible white lines are supported only if HPGL_VERSION is "2" (the default) and the environment variable HPGL_OPAQUE_MODE is "yes" (the default). If the value is "no" then opaque filling will not be used, and white lines (if any), which are normally drawn with pen #0, will not be drawn. This feature is to accommodate older HP-GL/2 devices. HP-GL/2 pen plotters, for example, do not support opacity or the use of pen #0 to draw visible white lines. Some older HP-GL/2 devices reportedly malfunction if asked to draw opaque objects.

By default, pic2plot -T hpgl will draw with a fixed set of pens. Which pens are present may be specified by setting the HPGL_PENS environment variable. If HPGL_VERSION is "1", the default value of HPGL_PENS is "1=black"; if HPGL_VERSION is "1.5" or "2", the default value of HPGL_PENS is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan". The format should be self-explanatory. By setting HPGL_PENS, you may specify a color for any pen in the range #1...#31. For information on what color names are recognized, see section Specifying Colors by Name. Pen #1 must always be present, though it need not be black. Any other pen in the range #1...#31 may be omitted.

If HPGL_VERSION is "2" then pic2plot -T hpgl will also be affected by the environment variable HPGL_ASSIGN_COLORS. If the value of this variable is "yes", then plot -T hpgl will not be restricted to the palette specified in HPGL_PENS: it will assign colors to "logical pens" in the range #1...#31, as needed. The default value is "no" because other than color LaserJet printers and DesignJet plotters, not many HP-GL/2 devices allow the assignment of colors to logical pens.

pic2plot -T tek, which produces output for a Tektronix terminal or emulator, checks the TERM environment variable. If the value of TERM is "xterm", "xterms", or "kterm", it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm. Before drawing graphics, pic2plot -T tek will emit an escape sequence that causes the terminal emulator's auxiliary Tektronix window, which is normally hidden, to pop up. After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted. The Tektronix window will remain on the screen.

If the value of TERM is "kermit", "ansi.sys", "ansissys", "ansi.sysk", or "ansisysk", it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the MS-DOS version of kermit. Before drawing graphics, pic2plot -T tek will emit an escape sequence that switches the terminal emulator to Tektronix mode. Also, some of the Tektronix control codes emitted by pic2plot -T tek will be kermit-specific. There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported). After drawing graphics, pic2plot -T tek will emit an escape sequence that returns the emulator to VT100 mode. The key sequence `ALT minus' can be employed manually within kermit to switch between the two modes.

The tek2plot Program

What tek2plot is used for

GNU tek2plot is a command-line Tektronix translator. It displays Tektronix graphics files, or translates them to other formats. The `-T' option is used to specify the output format or display type. Supported output formats include "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta" (the default). These are the same formats that are supported by the GNU graph, plot, and pic2plot programs. tek2plot will take input from a file specified on the command line or from standard input, just as the plot filter plot does.

Tektronix graphics files are produced by many older applications, such as SKYMAP, a powerful astronomical display program. A directory containing sample Tektronix graphics files, which you may experiment with, is distributed along with the GNU plotting utilities. On most systems it is installed as `/usr/share/tek2plot' or `/usr/local/share/tek2plot'.

Tektronix graphics format is defined as a noninteractive version of the graphics format understood by Tektronix 4010/4014 terminals, as documented in the 4014 Service Manual, Tektronix Inc., 1974 (Tektronix Part #070-1648-00). tek2plot does not support interactive features such as graphics input mode ("GIN mode") or status enquiry. However, it does support a few additional features provided by popular Tektronix emulators, such as the color extensions supported by the Tektronix emulator contained in the MS-DOS version of kermit.

tek2plot command-line options

The tek2plot program translates the Tektronix graphics files produced by many older applications to other formats. The output format or display type is specified with the `-T' option. The possible output formats are the same ten formats that are supported by the GNU graph, plot, and pic2plot programs.

Input file names may be specified anywhere on the command line. That is, the relative order of file names and command-line options does not matter. If no file names are specified, or the file name `-' is specified, the standard input is read. The output file is written to standard output, unless the `-T X' option is specified. In that case the output is displayed in one or more windows on an X Window System display, and there is no output file.

The full set of command-line options is listed below. There are three sorts of option:

  1. General options.
  2. Options relevant only to raw tek2plot, i.e., relevant only if no display type or output format is specified with the `-T' option.
  3. Options requesting information (e.g., `--help').

Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.

The following are general options.

`-T type'
`--display-type type'
(String, default "meta".) Select a display type or output format of type type, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Window System, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the format used by Adobe Illustrator, idraw-editable Postscript, the format used by the xfig drawing editor, the Hewlett--Packard PCL 5 printer language, the Hewlett--Packard Graphics Language (by default, HP-GL/2), Tektronix format, and device-independent GNU graphics metafile format.
`-p n'
`--page-number n'
(Nonnegative integer.) Display only page number n, within the Tektronix file or sequence of Tektronix files that is being translated. Tektronix files may consist of one or more pages, numbered beginning with zero. The default behavior, if the `-p' option is not used, is to display all nonempty pages in succession. For example, tek2plot -T X displays each page in its own X window. If the `-T pnm' option, the `-T gif' option, the `-T ai' option, or the `-T fig' option is used, the default behavior is to display only the first page, since files in PNM, pseudo-GIF, AI, or Fig format may contain only a single page of graphics. Most Tektronix files consist of either one page (page #0) or two pages (an empty page #0, and page #1). Tektronix files produced by the GNU plotting utilities (e.g., by graph -T tek) are normally of the latter sort.
`-F font_name'
`--font-name font_name'
(String, default "Courier" except for tek2plot -T pnm, tek2plot -T gif, tek2plot -T pcl, tek2plot -T hpgl, and raw tek2plot, for all of which "HersheySerif" is the default.) Set the font used for text to font_name. Font names are case-insensitive. If a font outside the Courier family is chosen, the `--position-chars' option (see below) should probably be used. For a list of all fonts, see section Available text fonts. If the specified font is not available, the default font will be used.
`-W line_width'
`--line-width line_width'
(Float, default -1.0.) Set the thickness of lines, as a fraction of the size (i.e., minimum dimension) of the graphics display, to line_width. A negative value means that the default value provided by the libplot graphics library should be used. This is usually 1/850 times the size of the display, although if `-T X', `-T pnm', or -T gif is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible. tek2plot -T hpgl does not support drawing lines with other than a default thickness if the environment variable HPGL_VERSION is set to a value less than "2" (the default).
`--bg-color name'
(String, default "white".) Set the color used for the background to be name. This is relevant only to tek2plot -T X, tek2plot -T pnm, and tek2plot -T gif. An unrecognized name sets the color to the default. For information on what names are recognized, see section Specifying Colors by Name. The environment variable BG_COLOR can equally well be used to specify the background color. If the `-T gif' option is used, a transparent pseudo-GIF may be produced by setting the TRANSPARENT_COLOR environment variable to the name of the background color. See section Environment variables.
`--bitmap-size bitmap_size'
(String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be bitmap_size. This is relevant only to tek2plot -T X, tek2plot -T pnm, and tek2plot -T gif, for which the graphics display size can be expressed in terms of pixels. The environment variable BITMAPSIZE can equally well be used to specify the size. The graphics display used by tek2plot -T X is an X window. If you choose a rectangular (non-square) window size, the fonts in the plot will be scaled anisotropically, i.e., by different factors in the horizontal and vertical direction. This requires an X11R6 display. Any font that cannot be scaled in this way will be replaced by a default scalable font, such as the Hershey vector font "HersheySerif". For backward compatibility, the X resource Xplot.geometry, which can be set by the user, may be used to set the window size, instead of `--bitmap-size' or BITMAPSIZE.
`--max-line-length max_line_length'
(Integer, default 500.) Set the maximum number of points that a polygonal line may contain, before it is flushed to the display device, to equal max_line_length. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable MAX_LINE_LENGTH can also be used to specify the maximum line length. This option has no effect on raw tek2plot, since it draws polylines in real time and has no buffer limitations.
`--page-size pagesize'
(String, default "letter".) Set the size of the page on which the plot will be positioned. This is relevant only to tek2plot -T ai, tek2plot -T ps, tek2plot -T fig, tek2plot -T pcl, and tek2plot -T hpgl. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. The environment variable PAGESIZE can equally well be used to specify the page size. For tek2plot -T ai and tek2plot -T ps, the graphics display within which the plot is drawn will be a square region centered on the specified page, occupying its full width (with allowance being made for margins). For tek2plot -T fig, it will be a square region of the same size, located in the upper left corner of an xfig display. For tek2plot -T pcl and tek2plot -T hpgl, the graphics display will be a square region of the same size, but may be positioned differently. Fine control its positioning on the page can be accomplished by setting certain environment variables (see section Environment variables).
`--pen-color name'
(String, default "black".) Set the pen color to be name. An unrecognized name sets the pen color to the default. For information on what color names are recognized, see section Specifying Colors by Name.
`--position-chars'
Position the characters in each text string individually on the display. If the text font is not a member of the Courier family, and especially if it is not a fixed-width font, this option is recommended. It will improve the appearance of text strings, at the price of making it difficult to edit the output file with xfig or idraw.
`--rotation angle'
(Integer, default 0.) Set the rotation angle of the plot within the graphics display to be angle degrees. Recognized values are 0, 90, 180, and 270. The rotation is counterclockwise. This option is used for switching between portrait mode and landscape mode. Postmodernists may also find it useful.
`--use-tek-fonts'
Use the bitmap fonts that were used on the original Tektronix 4010/4014 terminal. This option is relevant only to tek2plot -T X. The four relevant bitmap fonts are distributed with most versions of the plotting utilities package, under the names tekfont0...tekfont3. They may easily be installed on any modern X Window System display. For this option to work properly, you must also select a window size of 1024x1024 pixels, either by using the --bitmap-size 1024x1024 option or by setting the value of the Xplot.geometry resource. The reason for this restriction is that bitmap fonts, unlike the scalable fonts that the plotting utilities normally use, cannot be rescaled. This option is useful only if you have a file in Tektronix format that draws text using native Tektronix fonts. Tektronix files produced by the GNU plotting utilities (e.g., by graph -T tek) do not use native Tektronix fonts to draw text.

The following option is relevant only to raw tek2plot, i.e., relevant only if no display type or output format is specified with the `-T' option. In this case tek2plot outputs a graphics metafile, which may be translated to other formats by invoking plot.

`-O'
`--portable-output'
Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable META_PORTABLE to "yes".

The following options request information.

`--help'
Print a list of command-line options, and then exit.
`--help-fonts'
Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. tek2plot -T X, tek2plot -T ai, tek2plot -T ps, and tek2plot -T fig each support the 35 standard Postscript fonts. tek2plot -T ai, tek2plot -T pcl, and tek2plot -T hpgl support the 45 standard PCL 5 fonts, and tek2plot -T pcl and tek2plot -T hpgl support a number of Hewlett--Packard vector fonts. All of the preceding, together with tek2plot -T pnm, tek2plot -T gif, and tek2plot -T tek, support a set of 22 Hershey vector fonts. Raw tek2plot in principle supports any of these fonts, since its output must be translated to other formats with plot. The plotfont utility will produce a character map of any available font. See section The plotfont Utility.
`--list-fonts'
Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed.
`--version'
Print the version number of tek2plot and the plotting utilities package, and exit.

Environment variables

The behavior of tek2plot is affected by several environment variables, which are the same as those that affect graph and plot. For convenience, we list them here.

We have already mentioned the environment variables BITMAPSIZE, PAGESIZE, BG_COLOR, and MAX_LINE_LENGTH. They serve as backups for the options `--bitmap-size', `--page-size', `--bg-color', and `--max-line-length'. The remaining environment variables are specific to individual output formats.

tek2plot -T X, which pops up a window on an X Window System display and draws graphics in it, checks the DISPLAY environment variable. The value of this variable determines the display on which the window will be popped up.

tek2plot -T pnm, which produces output in Portable Anymap (PBM/PGM/PPM) format, is affected by the PNM_PORTABLE environment variable. If its value is "yes", the output file will be in the portable (human readable) version of PBM, PGM, or PPM format, rather than the default (binary) version.

tek2plot -T gif, which produces output in pseudo-GIF format, is affected by two environment variables. If the value of the INTERLACE variable is "yes", the pseudo-GIF output file will be in interlaced format. Also, if the value of the TRANSPARENT_COLOR environment variable is the name of a color that appears in the output file, that color will be treated as transparent by most applications that read GIF files. For information on what color names are recognized, see section Specifying Colors by Name.

tek2plot -T pcl, which produces PCL 5 output for Hewlett--Packard printers and plotters, is affected by several environment variables. The position of the graphics display on the page can be adjusted by setting the PCL_XOFFSET and PCL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the PCL_ROTATE environment variable to "yes". This is not the same as the rotation obtained with the --rotation option, which sets the rotation angle of the plot within the display. Besides "no" and "yes", recognized values for the PCL_ROTATE variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively.

The variable PCL_ASSIGN_COLORS is also recognized. It should be set to "yes" when producing PCL 5 output for a color printer or other color device. This will ensure accurate color reproduction by giving the output device complete freedom in assigning colors, internally, to its "logical pens". If it is "no" then the device will use a fixed set of colored pens, and will emulate other colors by shading. The default is "no" because monochrome PCL 5 devices, which are much more common than colored ones, must use shading to emulate color.

tek2plot -T hpgl, which produces Hewlett--Packard Graphics Language output, is also affected by several environment variables. The most important is HPGL_VERSION, which may be set to "1", "1.5", or "2" (the default). "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2. If the version is "1" or "1.5" then the only available fonts will be vector fonts, and all lines will be drawn with a default thickness (the `-W' option will not work).

The position of the tek2plot -T hpgl graphics display on the page can be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the HPGL_ROTATE environment variable to "yes". This is not the same as the rotation obtained with the --rotation option, which sets the rotation angle of the plot within the display. Besides "no" and "yes", recognized values for the HPGL_ROTATE variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively. "180" and "270" are supported only if HPGL_VERSION is "2" (the default).

The drawing of visible white lines is supported only if HPGL_VERSION is "2" and the environment variable HPGL_OPAQUE_MODE is "yes" (the default). If the value is "no" then white lines (if any), which are normally drawn with pen #0, will not be drawn. This feature is to accommodate older HP-GL/2 devices. HP-GL/2 pen plotters, for example, do not support the use of pen #0 to draw visible white lines. Some older HP-GL/2 devices may, in fact, malfunction if asked to draw opaque objects.

By default, tek2plot -T hpgl will draw with a fixed set of pens. Which pens are present may be specified by setting the HPGL_PENS environment variable. If HPGL_VERSION is "1", the default value of HPGL_PENS is "1=black"; if HPGL_VERSION is "1.5" or "2", the default value of HPGL_PENS is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan". The format should be self-explanatory. By setting HPGL_PENS, you may specify a color for any pen in the range #1...#31. For information on what color names are recognized, see section Specifying Colors by Name. Pen #1 must always be present, though it need not be black. Any other pen in the range #1...#31 may be omitted.

If HPGL_VERSION is "2" then tek2plot -T hpgl will also be affected by the environment variable HPGL_ASSIGN_COLORS. If the value of this variable is "yes", then tek2plot -T hpgl will not be restricted to the palette specified in HPGL_PENS: it will assign colors to "logical pens" in the range #1...#31, as needed. The default value is "no" because other than color LaserJet printers and DesignJet plotters, not many HP-GL/2 devices allow the assignment of colors to logical pens.

The plotfont Utility

How to use plotfont

GNU plotfont is a simple utility that will produce a character map for any font available to the GNU plotting utilities graph, plot, pic2plot, and tek2plot, and the GNU libplot graphics library on which they are based. The map may be displayed on an X Window System display, or produced in any of several output formats. The `-T' option is used to specify the desired output format. Supported output formats include "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta" (the default).

Which fonts are available depends on the choice of display or output format. To get a list of the available fonts, use the `--help-fonts' option. For example,

plotfont -T ps --help-fonts

will list the fonts that are available when producing Postscript output. One of these fonts is "Times-Roman". Doing

plotfont -T ps Times-Roman > map.ps

will produce a character map of the lower half of this font, which consists of printable ASCII characters. The map will be a 12x8 grid, with a character centered in each grid cell. If you include the `-2' option, you will get a map of the upper half of the font.

Most built-in fonts are ISO-Latin-1 fonts, which means that the upper half is arranged according to the ISO-Latin-1 encoding. The "HersheyCyrillic" font is one that is not. If you do

plotfont -T ps -2 HersheyCyrillic > map.ps

you will get a map that illustrates its arrangment, which is called KOI8-R. The KOI8-R arrangement is the standard for Unix and networking applications in the former Soviet Union. So-called dingbats fonts, such as "ZapfDingbats" and "Wingdings", also have an individualistic layout. In most installations of the plotting utilities, the Wingdings font is not available when producing Postscript output. However, it is available when producing output in PCL 5 or HP-GL/2 format. If you do

plotfont -T hpgl Wingdings > map.plt

you will get a Wingdings character map, in HP-GL/2 format, that may be imported into any application that understands HP-GL/2. Similarly, plot -T pcl Wingdings will produce a Wingdings character map in PCL 5 format, which may be printed on a LaserJet or other PCL 5 device.

In all, more than a hundred fonts are built into the plotting utilities. See section Available text fonts. Actually, if you are using the plotting utilities to display output on an X display, you are not restricted to the built-in fonts. Doing

plotfont -T X --help-fonts

produces a list of the built-in fonts that are available, including both Hershey and Postscript fonts. But fonts available on your X display may also be used. The xlsfonts command will list the fonts available on your X display, most font names being given in what is called XLFD format. The plotting utilities refer to X fonts by shortened versions of their XLFD names. For example, the font "Utopia-Regular" is available on many X displays. Its XLFD name is "-adobe-utopia-medium-r-normal--0-0-0-0-p-0-iso8859-1", and its shortened XLFD name is "utopia-medium-r-normal". If you do

plotfont -T X utopia-medium-r-normal

then a character map for this font will be displayed in a popped-up X window.

When using the `-T X' option, you may also use the `--bitmap-size' option to choose the size of the popped-up window. Modern X displays can scale fonts by different amounts in the horizontal and vertical directions. If, for example, you add `--bitmap-size 600x300' to the above command line, both the character map and the Utopia-Regular font within it will be scaled in this way. If your X display does not support font scaling, a scalable font will be substituted.

plotfont command-line options

The plotfont font display utility will produce a character map for any of the fonts available to the GNU plotting utilities graph, plot, pic2plot, and tek2plot, and the GNU libplot graphics library on which they are based. The map may be produced in any supported output format, or displayed on an X Window System display. The output format or display type is specified with the `-T' option.

The names of the fonts for which a character map will be produced may appear anywhere on the plotfont command line. That is, the relative order of font names and command-line options does not matter. The character map is written to standard output, unless the `-T X' option is specified. In that case the character map is displayed in a window on an X Window System display, and there is no output file.

The possible options are listed below. There are three sorts of option:

  1. General options.
  2. Options relevant only to raw plotfont, i.e., relevant only if no display type or output format is specified with the `-T' option.
  3. Options requesting information (e.g., `--help').

Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.

The following are general options.

`-1'
`--lower-half'
Generate a character map for the lower half of each specified font. This is the default.
`-2'
`--upper-half'
Generate a character map for the upper half of each specified font.
`-o'
`--octal'
Number the characters in octal rather than in decimal (the default).
`-x'
`--hexadecimal'
Number the characters in hexadecimal rather than in decimal (the default).
`--box'
Surround each character with a box, showing its extent to left and right. The default is not to do this.
`-j row'
`--jis-row row'
Generate a character map for row row of a Japanese font arranged according to JIS [Japanese Industrial Standard] X0208. The only such font currently available is the HersheyEUC [Extended Unix Code] font. If used, this option overrides the `-1' and `-2' options. The valid rows are 1...94. In the JIS X0208 standard, Roman characters are located in row 3, and Japanese syllabic characters (Hiragana and Katakana) are located in rows 4 and 5. Greek and Cyrillic characters are located in rows 6 and 7. Japanese ideographic characters (Kanji) are located in rows 16...84. Rows 16...47 contain the JIS Level 1 Kanji, which are the most frequently used. They are arranged according to On (old Chinese) reading. Rows 48...84 contain the less frequently used JIS Level 2 Kanji. The HersheyEUC font contains 596 of the 2965 Level 1 Kanji, and seven of the Level 2 Kanji. It uses the 8-bit EUC-JP encoding. This encoding is a multibyte encoding that includes the ASCII character set as well as the JIS X0208 characters. It represents each ASCII character in the usual way, i.e., as a single byte that does not have its high bit set. Each JIS X0208 character is represented as two bytes, each with the high bit set. The first byte contains the row number (plus 32), and the second byte contains the character number.
`-T type'
`--display-type type'
(String, default "meta".) Select a display type or output format of type type, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Window System, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the format used by Adobe Illustrator, idraw-editable Postscript, the format used by the xfig drawing editor, the Hewlett--Packard PCL 5 printer language, the Hewlett--Packard Graphics Language (by default, HP-GL/2), Tektronix format, and device-independent GNU graphics metafile format. Files in PNM, pseudo-GIF, AI, or Fig format may contain only a single page of graphics. So if the `-T pnm' option, the `-T gif' option, the `-T ai' option, or the `-T fig' option is used, a character map will be produced for only the first-specified font.
`--bg-color name'
(String, default "white".) Set the color used for the background to be name. This is relevant only to plotfont -T X, plotfont -T pnm, and plotfont -T gif. An unrecognized name sets the color to the default. For information on what names are recognized, see section Specifying Colors by Name. The environment variable BG_COLOR can equally well be used to specify the background color. If the `-T gif' option is used, a transparent pseudo-GIF may be produced by setting the TRANSPARENT_COLOR environment variable to the name of the background color. See section Environment variables.
`--bitmap-size bitmap_size'
(String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be bitmap_size. This is relevant only to plotfont -T X, plotfont -T pnm, and plotfont -T gif, for which the graphics display size can be expressed in terms of pixels. The environment variable BITMAPSIZE can equally well be used to specify the size. The graphics display used by plotfont -T X is an X window. If you choose a rectangular (non-square) window size, the fonts in the plot will be scaled anisotropically, i.e., by different factors in the horizontal and vertical direction. This requires an X11R6 display. Any font that cannot be scaled in this way will be replaced by a default scalable font, such as the Hershey vector font "HersheySerif". For backward compatibility, the X resource Xplot.geometry, which can be set by the user, may be used to set the window size, instead of `--bitmap-size' or BITMAPSIZE.
`--numbering-font-name font_name'
(String, default "Helvetica" except for plotfont -T pnm, plotfont -T gif, plotfont -T pcl, plotfont -T hpgl and plotfont -T tek, for which "HersheySerif" is the default.) Set the font used for the numbering of the characters in the character map(s) to be font_name.
`--page-size pagesize'
(String, default "letter".) Set the size of the page for which the character map(s) will be produced. This is relevant only to plotfont -T ai, plotfont -T ps, plotfont -T fig, plotfont -T pcl and plotfont -T hpgl. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. The environment variable PAGESIZE can equally well be used to specify the page size. For plotfont -T ai and plotfont -T ps, the graphics display within which each character map is drawn will be a square region centered on the specified page, occupying its full width (with allowance being made for margins). For plotfont -T fig, it will be a square region of the same size, located in the upper left corner of an xfig display. For plotfont -T pcl and plotfont -T hpgl, the graphics display will be a square region of the same size, but may be positioned differently. Fine control over its positioning on the page can be accomplished by setting certain environment variables (see section Environment variables).
`--pen-color name'
(String, default "black".) Set the pen color to be name. An unrecognized name sets the pen color to the default. For information on what color names are recognized, see section Specifying Colors by Name.
`--rotation angle'
(Integer, default 0.) Set the rotation angle of the character map(s) within the graphics display to be angle degrees. Recognized values are 0, 90, 180, and 270. The rotation is counterclockwise. This option is used for switching between portrait mode and landscape mode. Postmodernists may also find it useful.
`--title-font-name font_name'
(String) Set the font used for the title of each character map to be font_name. Normally the font used for the title is the same as the font whose character set is being displayed. This option is useful when producing character maps for unusual fonts such as "ZapfDingbats" and "Wingdings".

The following option is relevant only to raw plotfont, i.e., relevant only if no display type or output format is specified with the `-T' option. In this case plotfont outputs a graphics metafile, which may be translated to other formats by invoking plot.

`-O'
`--portable-output'
Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable META_PORTABLE to "yes".

The following options request information.

`--help'
Print a list of command-line options, and then exit.
`--help-fonts'
Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. plotfont -T X, plotfont -T ai, plotfont -T ps, and plotfont -T fig each support the 35 standard Postscript fonts. plotfont -T ai, plotfont -T pcl, and plotfont -T hpgl support the 45 standard PCL 5 fonts, and plotfont -T pcl and plotfont -T hpgl support a number of Hewlett--Packard vector fonts. All of the preceding, together with plotfont -T pnm, plotfont -T gif, and plotfont -T tek, support a set of 22 Hershey vector fonts. Raw plotfont in principle supports any of these fonts, since its output must be translated to other formats with plot.
`--list-fonts'
Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed.
`--version'
Print the version number of plotfont and the plotting utilities package, and exit.

Environment variables

The behavior of plotfont is affected by several environment variables, which are the same as those that affect graph, plot, and tek2plot. For convenience, we list them here.

We have already mentioned the environment variables BITMAPSIZE, PAGESIZE, and BG_COLOR. They serve as backups for the options `--bitmap-size', `--page-size', and `--bg-color'. The remaining environment variables are specific to individual output formats.

plotfont -T X, which pops up a window on an X Window System display and draws a character map in it, checks the DISPLAY environment variable. The value of this variable determines the display on which the window will be popped up.

plotfont -T pnm, which produces output in Portable Anymap (PBM/PGM/PPM) format, is affected by the PNM_PORTABLE environment variable. If its value is "yes", the output file will be in the portable (human readable) version of PBM, PGM, or PPM format, rather than the default (binary) version.

plotfont -T gif, which produces output in pseudo-GIF format, is affected by two environment variables. If the value of the INTERLACE variable is "yes", the pseudo-GIF output file will be in interlaced format. Also, if the value of the TRANSPARENT_COLOR environment variable is the name of a color that appears in the output file, that color will be treated as transparent by most applications that read GIF files. For information on what color names are recognized, see section Specifying Colors by Name.

plotfont -T pcl, which produces PCL 5 output for Hewlett--Packard printers and plotters, is affected by several environment variables. The position of the graphics display on the page can be adjusted by setting the PCL_XOFFSET and PCL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the PCL_ROTATE environment variable to "yes". This is not the same as the rotation obtained with the --rotation option, which sets the rotation angle of the character map within the display. Besides "no" and "yes", recognized values for the PCL_ROTATE variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively.

The variable PCL_ASSIGN_COLORS is also recognized. It should be set to "yes" when producing PCL 5 output for a color printer or other color device. This will ensure accurate color reproduction by giving the output device complete freedom in assigning colors, internally, to its "logical pens". If it is "no" then the device will use a fixed set of colored pens, and will emulate other colors by shading. The default is "no" because monochrome PCL 5 devices, which are much more common than colored ones, must use shading to emulate color.

plotfont -T hpgl, which produces Hewlett--Packard Graphics Language output, is also affected by several environment variables. The most important is HPGL_VERSION, which may be set to "1", "1.5", or "2" (the default). "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2. If the version is "1" or "1.5" then the only available fonts will be vector fonts.

The position of the plotfont -T hpgl graphics display on the page can be adjusted by setting the HPGL_XOFFSET and HPGL_YOFFSET environment variables, which may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in". Also, the display can be rotated 90 degrees counterclockwise on the page by setting the HPGL_ROTATE environment variable to "yes". This is not the same as the rotation obtained with the --rotation option, which sets the rotation angle of the character map within the display. Besides "no" and "yes", recognized values for the HPGL_ROTATE variable are "0", "90", "180", and "270". "no" and "yes" are equivalent to "0" and "90", respectively. "180" and "270" are supported only if HPGL_VERSION is "2" (the default).

By default, plotfont -T hpgl will draw with a fixed set of pens. Which pens are present may be specified by setting the HPGL_PENS environment variable. If HPGL_VERSION is "1", the default value of HPGL_PENS is "1=black"; if HPGL_VERSION is "1.5" or "2", the default value of HPGL_PENS is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan". The format should be self-explanatory. By setting HPGL_PENS, you may specify a color for any pen in the range #1...#31. For information on what color names are recognized, see section Specifying Colors by Name. Pen #1 must always be present, though it need not be black. Any other pen in the range #1...#31 may be omitted.

If HPGL_VERSION is "2" then plotfont -T hpgl will also be affected by the environment variable HPGL_ASSIGN_COLORS. If the value of this variable is "yes", then plotfont -T hpgl will not be restricted to the palette specified in HPGL_PENS: it will assign colors to "logical pens" in the range #1...#31, as needed. The default value is "no" because other than color LaserJet printers and DesignJet plotters, not many HP-GL/2 devices allow the assignment of colors to logical pens.

plotfont -T tek, which produces output for a Tektronix terminal or emulator, checks the TERM environment variable. If the value of TERM is "xterm", "xterms", or "kterm", it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm. Before drawing graphics, plotfont -T tek will emit an escape sequence that causes the terminal emulator's auxiliary Tektronix window, which is normally hidden, to pop up. After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted. The Tektronix window will remain on the screen.

If the value of TERM is "kermit", "ansi.sys", "ansissys", "ansi.sysk", or "ansisysk", it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the MS-DOS version of kermit. Before drawing graphics, plotfont -T tek will emit an escape sequence that switches the terminal emulator to Tektronix mode. Also, some of the Tektronix control codes emitted by plotfont -T tek will be kermit-specific. There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported). After drawing graphics, plotfont -T tek will emit an escape sequence that returns the emulator to VT100 mode. The key sequence `ALT minus' can be employed manually within kermit to switch between the two modes.

The spline Program

How to use spline

GNU spline is a program for interpolating between the data points in one or more datasets. Each dataset would consist of values for an independent variable and a dependent variable, which may be a vector of specified fixed length. When discussing interpolation, we call these variables `t' and `y', respectively. To emphasize: t is a scalar, but in general the dependent variable y may be a vector.

The simplest case is when there is a single input file, which is in ASCII format, and the vector y is one-dimensional. This is the default. For example, the input file could contain the dataset

0.0  0.0
1.0  1.0
2.0  0.0

which are the coordinates (t,y) of the data points (0,0), (1,1), and (2,0). Data points do not need to be on different lines, nor do the t and y coordinates of a data point need to be on the same line. However, there should be no blank lines in the input if it is to be viewed as forming a single dataset. Also, by default the t coordinate should be monotonically increasing, so that y may be viewed as a function of t.

You would construct a spline (the graph of an `interpolating function') passing through the points in this dataset by doing

spline input_file > output_file

To produce a Postscript plot of the spline with the graph utility, you would do

spline input_file | graph -T ps > output.ps

To display a spline on an X Window System display, you could do

echo 0 0 1 1 2 0 | spline | graph -T X

Notice that the last example avoids the use of the input file altogether. spline will read from standard input if no files are specified on the command line, or if the special file name `-' is specified.

What exactly does spline do? First, it fits a curve (the graph of an interpolating function) through the points in the dataset. Then it splits the interval over which the independent variable t ranges into 100 sub-intervals, and computes the y values at each of the 101 subdivision points. It then outputs each of the pairs (t, y). These are the coordinates of 101 points that lie along a curve that interpolates between the points in the dataset. If there is more than one dataset in the input (separated by blank lines), each dataset is interpolated separately.

You may use the `-n' option to replace `100' by any other positive integer. You may also use the `-t' option to specify an interpolation interval that differs from the default (the interval over which the independent variable ranges). For example, the command

echo 0 0 1 1 2 0 | spline -n 20 -t 1.0 1.5 > output_file

will produce a dataset consisting of 21 (rather than 101) data points, with t values spaced regularly between 1.0 and 1.5 (rather than between 0.0 and 2.0). The data points will lie along a curve passing through (0,0), (1,1), and (2,0). This curve will be a parabola.

In general, the interpolating function will be a piecewise cubic spline. That is, between each pair of adjacent `knots' (points in the input dataset), y will be a cubic function of t. This function will differ, depending on which pair of knots y lies between. At each knot, both the slope and curvature of the cubic pieces to either side will match. In mathematical terms, the interpolating curve will be twice continuously differentiable.

spline supports `adding tension' to the interpolating curve. A nonzero value for the tension can be specified with the `-T' option. For example, a spline under considerable tension can be computed and displayed by doing

echo 0 0 1 0 2 0 | spline -T 10 | graph -T X

As the tension parameter is increased to positive infinity, the spline will converge to a polygonal line. You are meant to think of the spline as being drawn taut. Actually, tension may be negative as well as positive. A spline with negative tension will tend to bow outward, in fact to oscillate sinusoidally. But as the tension decreases to negative infinity, the spline, though oscillatory, will again converge to a polygonal line.

If the tension is positive, its reciprocal will be the maximum range of the independent variable t over which the spline will `like to curve'. Increasing the tension far above zero will accordingly force the spline to consist of short curved sections, centered on the data points, and sections that are almost straight. It follows that tension is a `dimensionful' quantity. If the tension is nonzero, then when the values of the independent variable are multiplied by some common positive factor, the tension should be divided by the same factor to obtain a scaled version of the original spline. If the tension is zero (the default, or cubic spline case), then the computation of the spline will be unaffected by linear scaling of the data.

In mathematical terms, a spline under tension will satisfy the differential equation @ifnottex y""=sgn(tension)*(tension^2)y" between each successive pair of knots. If the tension equals zero, which is the default, the fourth derivative of y with respect to t will equal zero at every point. In this case, y as a function of t will reduce to a cubic polynomial between each successive pair of knots. But if the tension is nonzero, y will not be a polynomial function of t. It may be expressed in terms of exponential functions, however.

Irrespective of whether or not the spline is under tension, you may specify the `-p' option if you wish the spline to be a periodic function of t. This will only work if the y values for the first and last points in the dataset are equal. Otherwise, it would make no sense to compute a periodic interpolation.

It is sometimes useful to interpolate between data points at the same time as they are generated by an auxiliary program. That is, it is useful for spline to function as a real-time filter. spline does not normally act as a filter, since computing an interpolating curve that is as smooth as possible is a global task. But if the `-f' option is specified, spline will indeed function as a filter. A different interpolation algorithm (cubic Bessel interpolation, which is local rather than global) will be used. If `-f' is specified, `-p' may not be specified. Also, if `-f' is specified then an interpolation interval (a range of t values) must be requested explicitly with the `-t' option.

Cubic Bessel interpolation is inherently less smooth than the construction of a global cubic spline. If the `-f' option is specified, the slope of the spline at each knot will be chosen by fitting a parabola through that knot, and the two adjacent knots. The slopes of the two interpolating segments to either side of each interior knot will match at that knot, but typically their curvatures will not. In mathematical terms, the interpolating curve will be continuously differentiable, but in general not twice continuously differentiable. This loss of differentiability is the price that is paid for functioning as a real-time filter.

Advanced use of spline

The preceding section explains how spline can be employed to interpolate a function y of a scalar variable t, in the case when y is a scalar. In this section we explain how to perform more sophisticated interpolations. This includes multidimensional interpolations, and interpolations that are splinings of curves, rather than of functions.

spline can handle the case when y is a vector of arbitrary specified dimensionality. The dimension can be specified with the `-d' option. For example, an input file could contain the multidimensional dataset

0.0  0.0  1.0
1.0  1.0  0.0
2.0  0.0  1.0

which are the coordinates (t,y) of the data points (0,0,1), (1,1,0), and (2,0,1). You would construct a spline (the graph of an interpolating function) passing through the points in this dataset by doing

spline -d 2 input_file > output_file

The option `-d 2' is used because in this example, the dependent variable y is a two-dimensional vector. Each of the components of y will be interpolated independently, and the output file will contain points that lie along the graph of the resulting interpolating function.

When doing multidimensional splining, you may use any of the options that apply in the default one-dimensional case. For example, the `-f' option will yield real-time cubic Bessel interpolation. As in the one-dimensional case, if the `-f' option is used then the `-t' option must be used as well, to specify an interpolation interval (a range of t values). The -p option will yield a periodic spline, i.e., the graph of a periodic vector-valued function. For this, the first and last dataset y values must be the same.

spline can also be used to draw a curve through arbitrarily chosen points in the plane, or in general through arbitrarily chosen points in d-dimensional space. This is not the same as splining, at least as the term is conventionally defined. The reason is that `splining' refers to construction of a function, rather than the construction of a curve that may or may not be the graph of a function. Not every curve is the graph of a function.

The following example shows how you may `spline a curve'. The command

echo 0 0 1 0 1 1 0 1 | spline -d 2 -a -s | graph -T X

will construct a curve in the plane through the four points (0,0), (1,0), (1,1), and (0,1), and graph it on an X Window System display. The `-d 2' option specifies that the dependent variable y is two-dimensional. The `-a' option specifies that t values are missing from the input, and should be automatically generated. By default, the first t value is 0, the second is 1, etc. The `-s' option specifies that the t values should be stripped from the output.

The same technique may be used to spline a closed curve. For example, doing

echo 0 0 1 0 0 1 0 0 | spline -d 2 -a -s -p | graph -T X

will construct and graph a closed, lozenge-shaped curve through the three points (0,0), (1,0), and (0,1). The construction of a closed curve is guaranteed by the `-p' (i.e., `--periodic') option, and by the repetition of the initial point (0,0) at the end of the sequence.

When splining a curve, whether open or closed, you may wish to substitute the `-A' option for the `-a' option. Like the `-a' option, the `-A' option specifies that t values are missing from the input and should be automatically generated. However, the increment from one t value to the next will be the distance between the corresponding values of y. This scheme for generating t values, when constructing a curve through a sequence of points, is the scheme that is used in the well known FITPACK subroutine library. It is probably the best approach when the distances between successive points fluctuate considerably.

A curve through a sequence of points in the plane, whether open or closed, may cross itself. Some interesting visual effects can be obtained by adding negative tension to such a curve. For example, doing

echo 0 0 1 0 1 1 0 0 | spline -d 2 -a -s -p -T -14 -n 500 | graph -T X

will construct a closed curve through the three points (0,0), (1,0), and (0,1), which is wound into curlicues. The `-n 500' option is included because there are so many windings. It specifies that 501 points should be generated, which is enough to draw a smooth curve.

spline command-line options

The spline program will interpolate vector-valued functions of a scalar variable t, and curves in d-dimensional space. The algorithms used by spline are similar to those discussed in D. Kincaid and [E.] W. Cheney, Numerical Analysis (2nd ed., Brooks/Cole, 1996), section 6.4, and C. de Boor, A Practical Guide to Splines (Springer-Verlag, 1978), Chapter 4.

Input file names may be specified anywhere on the command line. That is, the relative order of font names and command-line options does not matter. If no file names are specified, or the file name `-' is specified, the standard input is read.

An input file may contain more than a single dataset. Unless the `-a' or `-A' options are used (see below), each dataset is expected to consist of a sequence of data points, given as alternating t and y values. t is the scalar independent variable, and y is the vector-valued dependent variable. The dimensionality of y is specified with the `-d' option (the default is 1).

If the input file is in ASCII format (the default), its datasets are separated by blank lines. An input file may also contain any number of comment lines, which must begin with the comment character `#'. Comment lines are ignored. They are not treated as blank, i.e., they do not interrupt a dataset in progress.

The options to spline are listed below. There are three sorts of option:

  1. Options specifying the type of interpolation to be performed on each dataset.
  2. Options specifying the input or output format.
  3. Options requesting information (e.g., `--help').

Options that take an argument are followed, in parentheses, by the type and default value of the argument.

The following options specify the type of interpolation to be performed on each dataset.

`-f'
`--filter'
Use a local interpolation algorithm (the cubic Bessel algorithm), so that spline can be used as a real-time filter. The slope of the interpolating curve at each point in a dataset will be chosen by fitting a quadratic function through that point and the two adjacent points in the dataset. If `-f' is specified then the `-t' option, otherwise optional, must be used as well. Also, if `-f' is specified then the `-k', `-p', and `-T' options may not be used. If `-f' is not specified, then a different (global) interpolation algorithm will be used.
`-k k'
`--boundary-condition k'
(Float, default 1.0.) Set the boundary condition parameter for each constructed spline to be k. In each of its components, the spline will satisfy the two boundary conditions y"[0]=ky"[1] and y"[n]=ky"[n-1]. Here y[0] and y[1] signify the values of a specified component of the vector-valued dependent variable y at the first two points of a dataset, and y[n-1] and y[n] the values at the last two points. Setting k to zero will yield a `natural' spline, i.e., one that has zero curvature at the two ends of the dataset. The `-k' option may not be used if `-f' or `-p' is specified.
`-n n'
`--number-of-intervals n'
(Positive integer, default 100.) Subdivide the interval over which interpolation occurs into n subintervals. The number of data points computed, and written to the output, will be n+1.
`-p'
`--periodic'
Construct a periodic spline. If this option is specified, the y values for the first and last points in each dataset must be equal. The `-f' and `-k' options may not be used if `-p' is specified.
`-T tension'
`--tension tension'
(Float, default 0.0.) Set the tension in each interpolating spline to be tension. Between each pair of successive points in a dataset, the constructed spline will satisfy the differential equation @ifnottex y""=sgn(tension)*(tension^2)y" in each of its components. If tension equals zero, the spline will be piecewise cubic. As tension increases to positive infinity, the spline will converge to a polygonal line. The `-T' option may not be used if `-f' is specified.
`-t tmin tmax [tspacing]'
`--t-limits tmin tmax [tspacing]'
For each dataset, set the interval over which interpolation occurs to be the interval between tmin and tmax. If tspacing is not specified, the interval will be divided into the number of subintervals specified by the `-n' option. If the `-t' option is not used, the interval over which interpolation occurs will be the entire range of the independent variable in the dataset. The `-t' option must always be used if the `-f' option is used to request filter-like behavior (see above).

The following options specify the format of the input file(s) and the output file.

`-d dimension'
`--y-dimension dimension'
(Integer, default 1.) Set the dimensionality of the dependent variable y in the input and output files to be dimension.
`-I data-format'
`--input-format data-format'
(Character, default `a'.) Set the data format for the input file(s) to be data-format. The possible data formats are as follows.
`a'
ASCII format. Each file is a sequence of floating point numbers, interpreted as the t and y coordinates of the successive data points in a dataset. If y is d-dimensional, there will be d+1 numbers for each point. The t and y coordinates of a point need not appear on the same line, and points need not appear on different lines. But if a blank line occurs (i.e., two newlines in succession are seen), it is interpreted as the end of a dataset, and the beginning of the next.
`f'
@ifnottex Single precision binary format. Each file is a sequence of floating point numbers, interpreted as the t and y coordinates of the successive data points in a dataset. If y is d-dimensional, there will be d+1 numbers for each point. Successive datasets are separated by a single occurrence of the quantity FLT_MAX, which is the largest possible single precision floating point number. On most machines this is approximately 3.4x10^38.
`d'
@ifnottex Double precision binary format. Each file is a sequence of double precision floating point numbers, interpreted as the t and y coordinates of the successive data points in a dataset. If y is d-dimensional, there will be d+1 numbers for each point. Successive datasets are separated by a single occurrence of the quantity DBL_MAX, which is the largest possible double precision floating point number. On most machines this is approximately 1.8x10^308.
`i'
@ifnottex Integer binary format. Each file is a sequence of integers, interpreted as the t and y coordinates of the successive data points in a dataset. If y is d-dimensional, there will be d+1 numbers for each point. Successive datasets are separated by a single occurrence of the quantity INT_MAX, which is the largest possible integer. On most machines this is 2^31-1.
`-a [step_size [lower_limit]]'
`--auto-abscissa [step_size [lower_limit]]'
(Floats, defaults 1.0 and 0.0.) Automatically generate values for the independent variable (t). Irrespective of data format (`a', `f', `d', or `i'), this option specifies that the values of the independent variable (t) are missing from the input file: the dataset(s) to be read contain only values of the dependent variable (y), so that if y is d-dimensional, there will be only d numbers for each point. The increment from each t value to the next will be step_size, and the first t value will be lower_limit.
`-A'
`--auto-dist-abscissa'
Automatically generate values for the independent variable (t). This is a variant form of the `-a' option. The increment from each t value to the next will be the distance between the corresponding y values, and the first t value will be 0.0. This option is useful when interpolating curves rather than functions (see section Advanced use of spline).
`-O data-format'
`--output-format data-format'
(Character, default `a'.) Set the data format for the output file to be data-format. The interpretation of the data-format argument is the same as for the `-I' option.
`-P significant-digits'
`--precision significant-digits'
(Positive integer, default 6.) Set the numerical precision for the t and y values in the output file to be significant-digits. This takes effect only if the output file is written in `a' format, i.e., in ASCII.
`-s'
`--suppress-abscissa'
Omit the independent variable t from the output file; for each point, supply only the dependent variable y. If y is d-dimensional, there will be only d numbers for each point, not d+1. This option is useful when interpolating curves rather than functions (see section Advanced use of spline).

The following options request information.

`--help'
Print a list of command-line options, and then exit.
`--version'
Print the version number of spline and the plotting utilities package, and exit.

The ode Program

The GNU ode utility can produce a numerical solution to the initial value problem for many systems of first-order ordinary differential equations (ODE's). ode can also be used to solve systems of higher-order ODE's, since a simple procedure converts an n'th-order equation into n first-order equations. The output of ode can easily be piped to graph, so that one or more solution curves may be plotted as they are generated.

Three distinct schemes for numerical solution are implemented: Runge--Kutta--Fehlberg (the default), Adams--Moulton, and Euler. The Runge--Kutta--Fehlberg and Adams--Moulton schemes are available with adaptive stepsize.

Mathematical basics

We begin with some standard definitions. A differential equation is an equation involving an unknown function and its derivatives. A differential equation is ordinary if the unknown function depends on only one independent variable, often denoted t. The order of the differential equation is the order of the highest-order derivative in the equation. One speaks of a family, or system of equations when more than one equation is involved. If the equations are dependent on one another, they are said to be coupled. A solution is any function satisfying the equations. An initial value problem is present when there exist subsidiary conditions on the unknown function and its derivatives, all of which are given at the same value of the independent variable. In principle, such an `initial condition' specifies a unique solution. Questions about the existence and uniqueness of a solution, along with further terminology, are discussed in any introductory text. (See Chapter 1 of Birkhoff and Rota's Ordinary Differential Equations. For this and other references relevant to ode, see section Bibliography on ode and solving differential equations.)

In practical problems, the solution of a differential equation is usually not expressible in terms of elementary functions. Hence the need for a numerical solution.

A numerical scheme for solving an initial value problem produces an approximate solution, using only functional evaluations and the operations of arithmetic. ode solves first-order initial value problems of the form:

@ifnottex

x' = f(t,x,y,...,z)
y' = g(t,x,y,...,z)
   .
   .
   .
z' = h(t,x,y,...,z)

given the initial values for each dependent variable at the initial value of the independent variable t, i.e.,

x(a) = b
y(a) = c
     .
     .
     .
z(a) = d
t = a

@ifnottex where a,b,c,...,d are constants.

@ifnottex For ode to be able to solve such a problem numerically, the functions f,g,...,h must be expressed, using the usual operators (+, -, *, /, and ^), in terms of certain basic functions that ode recognizes. These are the same functions that the plotting program gnuplot recognizes. Moreover, each of f,g,...,h must be given explicitly. ode cannot deal with a system in which one or more of the first derivatives is defined implicitly rather than explicitly.

All schemes for numerical solution involve the calculation of an approximate solution at discrete values of the independent variable t, where the `stepsize' (the difference between any two successive values of t, usually denoted h) may be constant or chosen adaptively. In general, as the stepsize decreases the solution becomes more accurate. In ode, the stepsize can be adjusted by the user.

Simple examples using ode

The following examples should illustrate the procedure of stating an initial value problem and solving it with ode. If these examples are too elementary, see section The ode input language formally specified, for a formal specification of the ode input language. There is also a directory containing examples of ode input, which is distributed along with the GNU plotting utilities. On most systems it is installed as `/usr/share/ode' or `/usr/local/share/ode'.

Our first example is a simple one, namely

y'(t) = y(t)

with the initial condition

y(0) = 1

The solution to this differential equation is

@ifnottex

y(t) = e^t.

In particular

@ifnottex

y(1) = e^1 = 2.718282

to seven digits of accuracy.

You may obtain this result with the aid of ode by typing on the command line the sequence of commands

ode
y' = y
y = 1
print t, y
step 0, 1

Two columns of numbers will appear. Each line will show the value of the independent variable t, and the value of the variable y, as t is `stepped' from 0 to 1. The last line will be

1 2.718282

as expected. You may use the `-p' option to change the precision. If, for example, you type `ode -p 10' rather than `ode', you will get ten digits of accuracy in the output, rather than seven (the default).

After the above output, ode will wait for further instructions. Entering for example the line

step 1, 0

should yield two more columns of numbers, containing the values of t and y that are computed when t is stepped back from 1 to 0. You could type instead

step 1, 2

to increase rather than decrease t. To exit ode, you would type a line containing only `.', i.e. a single period, and tap `return'. ode will also exit if it sees an end-of-file indicator in its input stream, which you may send from your terminal by typing control-D.

Each line of the preceding example should be self-explanatory. A `step' statement sets the beginning and the end of an interval over which the independent variable (here, t) will range, and causes ode to set the numerical scheme in motion. The initial value appearing in the first `step' statement (i.e., 0) and the assignment statement

y = 1

are equivalent to the initial condition y(0) = 1. The statements `y' = y' and `y = 1' are very different: `y' = y' defines a way of computing the derivative of y, while `y = 1' sets the initial value of y. Whenever a `step' statement is encountered, ode tries to step the independent variable through the interval it specifies. Which values are to be printed at each step is specified by the most recent `print' statement. For example,

print t, y, y'

would cause the current value of the independent variable t, the variable y, and its derivative to be printed at each step.

To illustrate ode's ability to take its input or the initial part of its input from a file, you could prepare a file containing the following lines:

# an ode to Euler
y  = 1
y' = y
print t, y, y'

Call this file `euler'. (The `#' line is a comment line, which may appear at any point. Everything from the `#' to the end of the line on which it appears will be ignored.) To process this file with ode, you could type on your terminal

ode -f euler
step 0, 1

These two lines cause ode to read the file `euler', and the stepping to take place. You will now get three quantities (t, y, and y') printed at each of the values of t between 0 and 1. At the conclusion of the stepping, ode will wait for any further commands to be input from the terminal. This example illustrates that

ode -f euler

is not equivalent to

ode < euler

The latter would cause ode to take all its input from the file `euler', while the former allows subsequent input from the terminal. For the latter to produce output, you would need to include a `step' line at the end of the file. You would not need to include a `.' line, however. `.' is used to terminate input only when input is being read from a terminal.

A second simple example involves the numerical solution of a second-order differential equation. Consider the initial value problem

y''(t) = -y(t)
y(0) = 0
y'(0) = 1

Its solution would be

@ifnottex

y(t) = sin(t)

To solve this problem using ode, you must express this second-order equation as two first-order equations. Toward this end you would introduce a new function, called yp say, of the independent variable t. The pair of equations

y' = yp
yp' = -y

would be equivalent to the single equation above. This sort of reduction of an n'th order problem to n first order problems is a standard technique.

To plot the variable y as a function of the variable t, you could create a file containing the lines

# sine : y''(t) = -y(t), y(0) = 0, y'(0) = 1
sine' = cosine
cosine' = -sine
sine = 0
cosine = 1
print t, sine

(y and yp have been renamed sine and cosine, since that is what they will be.) Call this file `sine'. To display the generated data points on an X Window System display as they are generated, you would type

ode -f sine | graph -T X -x 0 10 -y -1 1
step 0, 2*PI
.

After you type the ode line, graph -T X will pop up a window, and after you type the `step' line, the generated dataset will be drawn in it. The `-x 0 10' and `-y -1 1' options, which set the bounds for the two axes, are necessary if you wish to display points in real time: as they are generated. If the axis bounds were not specified on the command line, graph -T X would wait until all points are read from the input before determining the bounds, and drawing the plot.

A slight modification of this example, showing how ode can generate several datasets in succession and plot them on the same graph, would be the following. Suppose that you type on your terminal the following lines.

ode -f sine | graph -T X -C -x 0 10 -y -1 1
step 0, PI
step PI, 2*PI
step 2*PI, 3*PI
.

Then the sine curve will be traced out in three stages. Since the output from each `step' statement ends with a blank line, graph -T X will treat each section of the sine curve as a different dataset. If you are using a color display, each of the three sections will be plotted in a different color. This is a feature provided by graph, which normally changes its linemode after each dataset it reads. If you do not like this feature, you may turn it off by using graph -T X -B instead of graph -T X.

In the above examples, you could use any of the other variants of graph instead of graph -T X. For example, you could use graph -T ps to obtain a plot in encapsulated Postscript format, by typing

ode -f sine | graph -T ps > plot.ps
step 0, 2*PI
.

You should note that of the variants of graph, the seven variants graph -T pnm, graph -T gif, graph -T ai, graph -T ps, graph -T fig, graph -T pcl and graph -T hpgl do not produce output in real time, even when the axis bounds are specified with the `-x' and `-y' options. So if any of these seven variants is used, the plot will be produced only when input from ode is terminated, which will occur when you type `.'.

In the preceding examples, the derivatives of the dependent variables were specified by comparatively simple expressions. They are allowed to be arbitrarily complicated functions of the dependent variables and the independent variable. They may also involve any of the functions that are built into ode. ode has a fair number of functions built in, including abs, sqrt, exp, log, log10, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, and atanh. Less familiar functions which are built into it are besj0, besj1, besy0, besy1, erf, erfc, inverf, lgamma, gamma, norm, invnorm, ibeta, and igamma. These have the same definitions as in the plotting program gnuplot. (All functions take a single argument, except for ibeta, which takes three, and igamma, which takes two). ode also knows the meaning of the constant `PI', as the above examples show. The names of the preceding functions are reserved, so, e.g., `cos' and `sin' may not be used as names for variables.

Other than the restriction of avoiding reserved names and keywords, the names of variables may be chosen arbitrarily. Any sequence of alphanumeric characters starting with an alphabetic character may be used; the first 32 characters are significant. It is worth noting that ode identifies the independent variable by the fact that it is (or should be) the only variable that has not appeared on the left side of a differential equation or an initial value assignment. If there is more than than one such variable then no stepping takes place; instead, an error message is printed. If there is no such variable, a dummy independent variable is invented and given the name `(indep)', internally.

Additional examples using ode

We explain here how to use some additional features of ode. However, the discussion below does not cover all of its capabilities. For a complete list of command-line options, see section ode command-line options.

It is easy to use ode to create plots of great beauty. An example would be a plot of a strange attractor, namely the Lorenz attractor. Suppose that a file named `lorenz' contains the following lines.

# The Lorenz model, a system of three coupled ODE's with parameter r.
x' = -3*(x-y)
y' = -x*z+r*x-y
z' = x*y-z

r = 26
x = 0; y = 1; z = 0

print x, y
step 0, 200

Then executing the command

ode < lorenz | graph -T X -C -x -10 10 -y -10 10

would produce a plot of the Lorenz attractor (strictly speaking, a plot of one of its two-dimensional projections). You may produce a Postscript plot of the Lorenz attractor, and print it, by doing something like

ode < lorenz | graph -T ps -x -10 10 -y -10 10 -W 0 | lpr

The `-W 0' ("zero width") option requests that graph -T ps use the thinnest line possible, to improve the visual appearance of the plot on a printer or other Postscript device.

Besides plotting a visually striking object in real time, the Lorenz attractor example shows how statements may be separated by semicolons, rather than appearing on different lines. It also shows how to use symbolic constants. In the description read by ode the parameter r is a variable like x, y, and z. But unlike them it is not updated during stepping, since no formula for its derivative r' is given.

Our second example deals with the interactive construction of a `phase portrait': a set of solution curves with different initial conditions. Phase portraits are of paramount interest in the qualitative theory of differential equations, and also possess @ae{}sthetic appeal.

Since a description read by ode may contain any number of `step' statements, multiple solution curves may be plotted in a single run. The most recent `print' statement will be used with each `step' statement. In practice, a phase portrait would be drawn from a few well-chosen solution curves. Choosing a good set of solution curves may require experimentation, which makes interactivity and real-time plotting all-important.

As an example, consider a so-called Lotka--Volterra predator--prey model. Suppose that in a lake there are two species of fish: A (the prey) who live by eating a plentiful supply of plants, and B (the predator) who eat A. Let x(t) be the population of A and y(t) the population of B at time t. A crude model for the interaction of A and B is given by the equations

x' = x(a-by)
y' = y(cx-d)

where a, b, c, d are positive constants. To draw a phase portrait for this system interactively, you could type

ode | graph -T X -C -x 0 5 -y 0 5
x' = (a - b*y) * x
y' = (c*x - d) * y
a = 1; b = 1; c = 1; d = 1;
print x, y
x = 1; y = 2
step 0, 10
x = 1; y = 3
step 0, 10
x = 1; y = 4
step 0, 10
x = 1; y = 5
step 0, 10
.

Four curves will be drawn in succession, one per `step' line. They will be periodic; this periodicity is similar to the fluctuations between predator and prey populations that occur in real-world ecosystems. On a color display the curves will appear in different colors, since by default, graph changes the linemode between datasets. That feature may be turned off by using graph -T X -B rather than graph -T X.

It is sometimes useful to use ode and graph to plot discrete points, which are not joined by line segments to form a curve. Our third example illustrates this. Suppose the file `atwoods' contains the lines

m = 1
M = 1.0625
a = 0.5; adot = 0
l = 10; ldot = 0

ldot' = ( m * l * adot * adot - M * 9.8 + m * 9.8 * cos(a) ) / (m + M)
l'    = ldot
adot' = (-1/l) * (9.8 * sin(a) +  2 * adot * ldot)
a'    = adot

print l, ldot
step 0, 400

The first few lines describe the functioning of a so-called swinging Atwood's machine. An ordinary Atwood's machine consists of a taut cord draped over a pulley, with a mass attached to the cord at each end. Normally, the heavier mass (M) would win against the lighter mass (m), and draw it upward. A swinging Atwood's machine allows the lighter mass to swing back and forth as well as move vertically.

The `print l, ldot' statement requests that the vertical position and vertical velocity of the lighter mass be printed out at each step. If you run the command

ode < atwoods | graph -T X -x 9 11 -y -1 1 -m 0 -S 1 -X l -Y ldot

you will obtain a real-time plot. The `-m 0' option requests that successive data points not be joined by line segments, and the `-S 1' option requests that plotting symbol #1 (a dot) be plotted at the location of each point. As you will see if you run this command, the heavy mass does not win against the lighter mass. Instead the machine oscillates non-periodically. Since the motion is non-periodic, the plot benefits from being drawn as a sequence of unconnected points.

We conclude by mentioning a few features of ode that may be useful when things are not going quite right. One of them is the `examine' statement. It may be used to discover pertinent information about any variable in a system. For details, see section The ode input language formally specified.

Another useful feature is that the `print' statement may be used to print out more than just the value of a variable. As we have seen, if the name of the variable is followed by `'', the derivative of the variable will be printed instead. In a similar way, following the variable name with `?', `!', or `~' prints respectively the relative single-step error, the absolute single-step error, or the accumulated error (not currently implemented). These quantities are discussed in section Numerical error and how to avoid it.

The `print' statement may be more complicated than was shown in the preceding examples. Its general structure is

print <pr-list> [every <const>] [from <const>]

The bracket notation `[...]' means that the enclosed statements are optional. Until now we have not mentioned the `every' clause or the `from' clause. The <pr-list> is familiar, however; it is simply a comma-separated list of variables. For example, in the statement

print t, y, y' every 5 from 1

the <pr-list> is <t, y, y'>. The clauses `every 5' and `from 1' specify that printing should take place after every fifth step, and that the printing should begin when the independent variable t reaches 1. An `every' clause is useful if you wish to `thin out' the output generated by a `step' statement, and a `from' clause is useful if you wish to view only the final portion of a solution curve.

ode command-line options

The command-line options to ode are listed below. There are several sorts of option:

  1. Options affecting the way in which input is read.
  2. Options affecting the format of the output.
  3. Options affecting the choice of numerical solution scheme, and the error bounds that will be imposed on it.
  4. Options that request information.

The following option affects the way input is read.

`-f filename'
`--input-file filename'
Read input from filename before reading from standard input.

The following options affect the output format.

`-p significant-digits'
`--precision significant-digits'
(Positive integer, default 6.) When printing numerical results, use a precision specified by significant-digits. If this option is given, the print format will be scientific notation.
`-t'
`--title'
Print a title line at the head of the output, naming the columns. If this option is given, the print format will be scientific notation.

The following options specify the numerical integration scheme. Only one of the three basic option `-R', `-A', and `-E' may be specified. The default is `-R' (Runge--Kutta--Fehlberg).

`-R [stepsize]'
`--runge-kutta [stepsize]'
Use a fifth-order Runge--Kutta--Fehlberg algorithm, with an adaptive stepsize unless a constant stepsize is specified. When a constant stepsize is specified and no error analysis is requested, then a classical fourth-order Runge--Kutta scheme is used.
`-A [stepsize]'
`--adams-moulton [stepsize]'
Use a fourth-order Adams--Moulton predictor--corrector scheme, with an adaptive stepsize unless a constant stepsize, stepsize, is specified. The Runge--Kutta--Fehlberg algorithm is used to get past `bad' points (if any).
`-E [stepsize]'
`--euler [stepsize]'
Use a `quick and dirty' Euler scheme, with a constant stepsize. The default value of stepsize is 0.1. Not recommended for serious applications. The error bound options `-r' and `-e' (see below) may not be used if `-E' is specified.
`-h hmin [hmax]'
`--step-size-bound hmin [hmax]'
Use a lower bound hmin on the stepsize. The numerical scheme will not let the stepsize go below hmin. The default is to allow the stepsize to shrink to the machine limit, i.e., the minimum nonzero double-precision floating point number. The optional argument hmax, if included, specifies a maximum value for the stepsize. It is useful in preventing the numerical routine from skipping quickly over an interesting region.

The following options set the error bounds on the numerical solution scheme.

`-r rmax [rmin]'
`--relative-error-bound rmax [rmin]'
`-e emax [emin]'
`--absolute-error-bound emax [emin]'
@ifnottex The `-r' option sets an upper bound on the relative single-step error. If the `-r' option is used, the relative single-step error in any dependent variable will never exceed rmax (the default for which is 10^(-9)). If this should occur, the solution will be abandoned and an error message will be printed. If the stepsize is not constant, the stepsize will be decreased `adaptively', so that the upper bound on the single-step error is not violated. Thus, choosing a smaller upper bound on the single-step error will cause smaller stepsizes to be chosen. A lower bound rmin may optionally be specified, to suggest when the stepsize should be increased (the default for rmin is rmax/1000). The `-e' option is similar to `-r', but bounds the absolute rather than the relative single-step error.
`-s'
`--suppress-error-bound'
Suppress the ceiling on single-step error, allowing ode to continue even if this ceiling is exceeded. This may result in large numerical errors.

Finally, the following options request information.

`--help'
Print a list of command-line options, and then exit.
`--version'
Print the version number of ode and the plotting utilities package, and exit.

Diagnostic messages

ode is always in one of two states:

  • Reading input. The input includes a specification of a system of ordinary differential equations, together with instructions for solving it numerically: a `print' line and a `step' line.
  • Numerically solving a system, and printing the resulting output.

ode moves from the first to the second state after it sees and processes a `step' line. It returns to the first state after the generated output has been printed. Errors may occur in either the `reading' state or the `solving' state, and may terminate computations or even cause ode to exit. We now explain the possible sorts of error.

While reading input, ode may encounter a syntax error: an ungrammatical line that it is unable to parse. (For a summary of its input grammar, see section The ode input language formally specified.) If so, it emits the error message

ode::nnn: syntax error

where `nnn' is the number of the line containing the error. When the `-f filename' option is used to specify an input file, the error message will read

ode:filename:nnn: syntax error

for errors encountered inside the input file. Subsequently, when ode begins reading the standard input, line numbers will start over again from 1.

No effort is made to recover from syntax errors in the input. However, there is a meager effort to resynchronize, so that more than one syntax error in a file may be found at the same time.

It is also possible that a fatal arithmetic exception (such as a division by zero, or a floating point overflow) may occur while ode is reading input. If such an exception occurs, ode will print an "Floating point exception" error message and exit. Arithmetic exceptions are machine-dependent. On some machines, the line

y = 1/0

would induce an arithmetic exception. Also on some machines (not necessarily the same ones), the lines

y = 1e100
z = y^4

@ifnottex would induce an arithmetic exception. That is because on most machines, the double precision quantities that ode uses internally are limited to a maximum size of approximately 1.8x10^308.

When ode is in the `solving' state, i.e., computing a numerical solution, similar arithmetic exceptions may occur. If so, the solution will be interrupted and a message resembling

ode: arithmetic exception while calculating y'

will be printed. However, ode will not exit; the exception will be `caught'. ode itself recognizes the following exceptional conditions: square root of a negative number, logarithm of a non-positive number, and negative number raised to a non-integer power. ode will catch any of these operations before it is performed, and print an error message specifying which illegal operation it has encountered.

ode: square root of a negative number while calculating y'

would be a typical error message.

If the machine on which ode is running supports the `matherr' facility for reporting errors in the computation of standard mathematical functions, it will be used. This facility reports domain errors and range errors (overflows, underflows, and losses of significance) that could occur when evaluating such functions as `log', `gamma', etc.; again, before they are performed. If the matherr facility is present, the error message will be fairly informative. For example, the error message

ode: range error (overflow) in lgamma while calculating y'

could be generated if the logarithmic gamma function `lgamma' is evaluated at a value of its argument that is too large. The generation of any such message, except a message warning of an underflow, will cause the numerical solution to be interrupted.

There is another sort of error that may occur during numerical solution: the condition that an error ceiling, which the user may set with the `-r' option or the `-e' option, is exceeded. This too will cause the numerical solution to be abandoned, and ode to switch back to reading input.

Numerical error and how to avoid it

This discussion is necessarily incomplete. Entire books exist on any subject mentioned below (e.g., floating point error). Our goals are modest: first, to introduce the basic notions of error analysis as they apply to ode; second, to steer you around the more obvious pitfalls. You should look through a numerical analysis text (e.g., Atkinson's Introduction to Numerical Analysis) before beginning this discussion.

We begin with some key definitions. The error of greatest concern is the difference between the actual solution and the numerical approximation to the solution; this is termed the accumulated error, since the error is built up during each numerical step. Unfortunately, an estimate of this error is usually not available without knowledge of the actual solution. There are, however, several more usable notions of error. The single-step error, in particular, is the difference between the actual solution and the numerical approximation to the solution after any single step, assuming the value at the beginning of the step is correct.

@ifnottex The relative single-step error is the single-step error, divided by the current value of the numerical approximation to the solution. Why not divided by the current value of the solution itself? The reason is that the solution is not exactly known. When free to choose a stepsize, ode will do so on the basis of the relative single-step error. By default, it will choose the stepsize so as to maintain an accuracy of eight significant digits in each step. That is, it will choose the stepsize so as not to violate an upper bound of 10^(-9) on the relative single-step error. This ceiling may be adjusted with the `-r' option.

Where does numerical error come from? There are two sources. The first is the finite precision of machine computation. All computers work with floating point numbers, which are not real numbers, but only an approximation to real numbers. However, all computations performed by ode are done to double precision, so floating point error tends to be relatively small. You may nonetheless detect the difference between real numbers and floating point numbers by experimenting with the `-p 17' option, which will print seventeen significant digits. On most machines, that is the precision of a double precision floating point number.

The second source of numerical error is often called the theoretical truncation error. It is the difference between the actual solution and the approximate solution due solely to the numerical scheme. At the root of many numerical schemes is an infinite series; for ordinary differential equations, it is a Taylor expansion. Since the computer cannot compute all the terms in an infinite series, a numerical scheme necessarily uses a truncated series; hence the term. The single-step error is the sum of the theoretical truncation error and the floating point error, though in practice the floating point error is seldom included. The single-step error estimated by ode consists only of the theoretical truncation error.

We say that a numerical scheme is stable, when applied to a particular initial value problem, if the error accumulated during the solution of the problem over a fixed interval decreases as the stepsize decreases; at least, over a wide range of step sizes. With this definition both the Runge--Kutta--Fehlberg (`-R') scheme and the Adams--Moulton (`-A') scheme are stable (a statement based more on experience than on theoretical results) for a wide class of problems.

After these introductory remarks, we list some common sources of accumulated error and instability in any numerical scheme. Usually, problems with large accumulated error and instability are due to the single-step error in the vicinity of a `bad' point being large.

  1. Singularities. ode should not be used to generate a numerical solution on any interval containing a singularity. That is, ode should not be asked to step over points at which the system of differential equations is singular or undefined. You will find the definitions of singular point, regular singular point, and irregular singular point in any good differential equations text. If you have no favorite, try Birkhoff and Rota's Ordinary Differential Equations, Chapter 9. Always locate and classify the singularities of a system, if any, before applying ode.
  2. Ill-posed problems. For ode to yield an accurate numerical solution on an interval, the true solution must be defined and well-behaved on that interval. The solution must also be real. Whenever any of these conditions is violated, the problem is said to be ill-posed. Ill-posedness may occur even if the system of differential equations is well-behaved on the interval. Strange results, e.g., the stepsize suddenly shrinking to the machine limit or the solution suddenly blowing up, may indicate ill-posedness. As an example of ill-posedness (in fact, an undefined solution) consider the innocent-looking problem: @ifnottex
    y' = y^2
y(1) = -1
    The solution on the domain t > 0 is
    y(t) = -1/t.
    With this problem you must not compute a numerical solution on any interval that includes t=0. To convince yourself of this, try to use the `step' statement
    step 1, -1
    on this system. How does ode react? As another example of ill-posedness, consider the system
    y'=1/y
    which is undefined at y=0. The general solution is @ifnottex
    y = +/- (2(t-C))^(1/2),
    @ifnottex so that if the condition y(2)=2 is imposed, the solution will be (2t)^(1/2). Clearly, if the domain specified in a `step' statement includes negative values of t, the generated solution will be bogus. In general, when using a constant stepsize you should be careful not to `step over' bad points or bad regions. When allowed to choose a stepsize adaptively, ode will often spot bad points, but not always.
  3. Critical points. An autonomous system is one that does not include the independent variable explicitly on the right-hand side of any differential equation. A critical point for such a system is a point at which all right-hand sides equal zero. For example, the system
    y' = 2x
x' = 2y
    has only one critical point, at (x,y) = (0,0). A critical point is sometimes referred to as a stagnation point. That is because a system at a critical point will remain there forever, though a system near a critical point may undergo more violent motion. Under some circumstances, passing near a critical point may give rise to a large accumulated error. As an exercise, solve the system above using ode, with the initial condition x(0) = y(0) = 0. The solution should be constant in time. Now do the same with points near the critical point. What happens? You should always locate the critical points of a system before attempting a solution with ode. Critical points may be classified (as equilibrium, vortex, unstable, stable, etc.) and this classification may be of use. To find out more about this, consult any book dealing with the qualitative theory of differential equations (e.g., Birkhoff and Rota's Ordinary Differential Equations, Chapter 6).
  4. Unsuitable numerical schemes If the results produced by ode are bad in the sense that instability appears to be present, or an unusually small stepsize needs to be chosen needed in order to reduce the single-step error to manageable levels, it may simply be that the numerical scheme being used is not suited to the problem. For example, ode currently has no numerical scheme which handles so-called `stiff' problems very well. As an example, you may wish to examine the stiff problem:
    y' = -100 + 100t + 1
y(0) = 1
    on the domain [0,1]. The exact solution is @ifnottex
    y(t) = e^(-100t) + t.
    It is a useful exercise to solve this problem with ode using various numerical schemes, stepsizes, and relative single-step error bounds, and compare the generated solution curves with the actual solution.

There are several rough and ready heuristic checks you may perform on the accuracy of any numerical solution produced by ode. We discuss them in turn.

  1. Examine the stability of solution curves: do they converge? That is, check how changing the stepsize affects a solution curve. As the stepsize decreases, the curve should converge. If it does not, then either the stepsize is not small enough or the numerical scheme is not suited to the problem. In practice, you would proceed as follows.
    • If using an adaptive stepsize, superimpose the solution curves for successively smaller bounds on the relative single-step error (obtained with, e.g., `-r 1e-9', `-r 1e-11', `-r 1e-13', ...). If the curves converge then the solution is to all appearances stable, and your accuracy is sufficient.
    • If employing a constant stepsize, perform a similar analysis by successively halving the stepsize.
    The following example is one that you may wish to experiment with. Make a file named `qcd' containing:
    # an equation arising in QCD (quantum chromodynamics)
f'   = fp
fp'  = -f*g^2
g'   = gp
gp'  = g*f^2
f = 0; fp = -1; g = 1; gp = -1

print t, f
step 0, 5
    Next make a file named `stability', containing the lines:
    : sserr is the bound on the relative single-step error
for sserr
do
ode -r $sserr < qcd
done | spline -n 500 | graph -T X -C
    This is a `shell script', which when run will superimpose numerical solutions with specified bounds on the relative single-step error. To run it, type:
    sh stability 1 .1 .01 .001
    and a plot of the solutions with the specified error bounds will be drawn. The convergence, showing stability, should be quite illuminating.
  2. Check invariants of the system: are they constant? Many systems have invariant quantities. For example, if the system is a mathematical model of a `conservative' physical system then the `energy' (a particular function of the dependent variables of the system) should be constant in time. In general, knowledge about the qualitative behavior of any dependent variable may be used to check the quality of the solution.
  3. Check a family of solution curves: do they diverge? A rough idea of how error is propagated is obtained by viewing a family of solution curves about the numerical solution in question, obtained by varying the initial conditions. If they diverge sharply---that is, if two solutions which start out very close nonetheless end up far apart--then the quality of the numerical solution is dubious. On the other hand, if the curves do not diverge sharply then any error that is present will in all likelihood not increase by more than an order of magnitude or so over the interval. Problems exhibiting no sharp divergence of neighboring solution curves are sometimes called well-conditioned.

Running time

The time required for ode to solve numerically a system of ordinary differential equations depends on a great many factors. A few of them are: number of equations, complexity of equations (number of operators and nature of the operators), and number of steps taken (a very complicated function of the difficulty of solution, unless constant stepsizes are used). The most effective way to gauge the time required for solution of a system is to clock a short or imprecise run of the problem, and reason as follows: the time required to take two steps is roughly twice that required for one; and there is a relationship between the number of steps required and the relative error ceiling chosen. That relationship depends on the numerical scheme being used, the difficulty of solution, and perhaps on the magnitude of the error ceiling itself. A few carefully planned short runs may be used to determine this relationship, enabling a long but imprecise run to be used as an aid in projecting the cost of a more precise run over the same region. Lastly, if a great deal of data is printed, it is likely that more time is spent in printing the results than in computing the numerical solution.

The ode input language formally specified

The following is a formal specification of the grammar for ode's input language, in Backus--Naur form. Nonterminal symbols in the grammar are enclosed in angle brackets. Terminal tokens are in all capitals. Bare words and symbols stand for themselves.

<program>    ::=        ... empty ...
               |  <program> <statement>

<statement>  ::=  SEP
               |  IDENTIFIER = <const> SEP
               |  IDENTIFIER ' = <expression> SEP
               |  print <printlist> <optevery> <optfrom> SEP
               |  step <const> , <const> , <const> SEP
               |  step <const> , <const> SEP
               |  examine IDENTIFIER SEP

<printlist>  ::=  <printitem>
               |  <printlist> , <printitem>

<printitem>  ::=  IDENTIFIER
               |  IDENTIFIER '
               |  IDENTIFIER ?
               |  IDENTIFIER !
               |  IDENTIFIER ~

<optevery>   ::=        ... empty ...
               |  every <const>

<optfrom>    ::=        ... empty ...
               |  from <const>

<const>      ::=  <expression>

<expression> ::=  ( <expression> )
               |  <expression> + <expression>
               |  <expression> - <expression>
               |  <expression> * <expression>
               |  <expression> / <expression>
               |  <expression> ^ <expression>
               |  FUNCTION ( <expression> )
               |  - <expression>
               |  NUMBER
               |  IDENTIFIER

Since this grammar is ambiguous, the following table summarizes the precedences and associativities of operators within expressions. Precedences decrease from top to bottom.

Class           Operators    Associativity

Exponential         ^            right
Multiplicative      * /          left
Additive            + -          left

As noted in the grammar, there are six types of nontrivial statement. We now explain the effects (the `semantics') of each type, in turn.

  1. IDENTIFIER ' = <expression> This defines a first-order differential equation. The derivative of IDENTIFIER is specified by <expression>. If a dynamic variable does not appear on the left side of a statement of this form, its derivative is assumed to be zero. That is, it is a symbolic constant.
  2. IDENTIFIER = <const> This sets the value of IDENTIFIER to the current value of <expression>. Dynamic variables that have not been initialized in this way are set to zero.
  3. step <const> , <const>
  4. step <const> , <const> , <const> A `step' statement causes the numerical scheme to be executed. The first <const> is the initial value of the independent variable. The second is its final value. The third is a stepsize; if given, it overrides any stepsize that may be specified on the command line. Usually the stepsize is not specified, and it varies adaptively as the computation proceeds.
  5. print <printlist> [ every <const> ] [ from <const> ] A `print' statement controls the content and frequency of the numerical output. <printlist> is a comma-separated list of IDENTIFIERs, where each IDENTIFIER may be followed by `'', denoting the derivative, or `?', denoting the relative single-step error, or `!', denoting the absolute single-step error, or `~', denoting the accumulated error (not currently implemented). The specified values are printed in the order they are found. Both the `every' clause and the `from' clause are optional. If the `every' clause is present, a printing occurs every <const> iterations of the numerical algorithm. The default is to print on every iteration (i.e. `every 1'). The first and last values are always printed. If the `from' clause is present, it means to begin printing when the independent variable reaches or exceeds <const>. The default is to begin printing immediately. If no `print' statement has been supplied, then the independent variable and all dependent variables which have differential equations associated with them are printed. The independent variable is printed first; the dependent variables follow in the order their equations were given.
  6. examine IDENTIFIER An `examine' statement, when executed, causes a table of interesting information about the named variable to be printed on the standard output. For example, if the statement `examine y' were encountered after execution of the `ode to Euler' example discussed elsewhere, the output would be:
    "y" is a dynamic variable
value:2.718282
prime:2.718282
sserr:1.121662e-09
aberr:3.245638e-09
acerr:0
 code:  push "y"
    The phrase `dynamic variable' means that there is a differential equation describing the behavior of y. The numeric items in the table are:
    value
    Current value of the variable.
    prime
    Current derivative of the variable.
    sserr
    Relative single-step error for the last step taken.
    aberr
    Absolute single-step error for the last step taken.
    acerr
    Total error accumulated during the most recent `step' statement. Not currently implemented.
    The `code' section of the table lists the stack operations required to compute the derivative of y (somewhat reminiscent of a reverse Polish calculator). This information may be useful in discovering whether the precedences in the differential equation statement were interpreted correctly, or in determining the time or space expense of a particular calculation. `push "y"' means to load y's value on the stack, which is all that is required to compute its derivative in this case.

The grammar for the ode input language contains four types of terminal token: FUNCTION, IDENTIFIER, NUMBER, and SEP. They have the following meanings.

  1. FUNCTION One of the words: abs, sqrt, exp, log, ln, log10, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, floor, ceil, besj0, besj1, besy0, besy1, erf, erfc, inverf, lgamma, gamma, norm, invnorm, ibeta, igamma. These are defined to have the same meaning as in the plotting program gnuplot. All functions take a single argument, except for ibeta, which takes three, and igamma, which takes two. For trigonometric functions, all arguments are expressed in radians. The atan function is defined to give a value between -PI/2 and PI/2 (inclusive).
  2. IDENTIFIER A sequence of alphanumeric characters starting with an alphabetic character. The first 32 characters are significant. Upper and lower-case letters are distinct. In identifiers, the underscore character is considered alphabetic. Function names and keywords may not be used as identifiers, nor may `PI'.
  3. NUMBER A non-empty sequence of digits possibly containing a decimal point and possibly followed by an exponent. An exponent is `e' or `E', followed by an (optionally signed) one, two, or three-digit number. All numbers and all parts of numbers are radix 10. A number may not contain any white space. The special word `PI' is a number.
  4. SEP A separator: a semicolon or a (non-escaped) newline.

In the ode input language, upper and lower-case letters are distinct. Comments begin with the character `#' and continue to the end of the line. Long lines may be continued onto a second line by ending the first line with a backslash (`\'). That is because the combination backslash-newline is equivalent to a space.

Spaces or tabs are required in the input whenever they are needed to separate identifiers, numbers, and keywords from one another. Except as separators, they are ignored.

Bibliography on ode and solving differential equations

  • K. E. Atkinson, An Introduction to Numerical Analysis, Wiley, 1978. Chapter 6 contains a discussion of the literature on the numerical solution of ordinary differential equations.
  • G. Birkhoff and G. Rota, Ordinary Differential Equations, 4th ed., Wiley, 1989.
  • N. B. Tufillaro, T. Abbott, and J. Reilly, An Experimental Approach to Nonlinear Dynamics and Chaos, Addison--Wesley, 1992. Appendix C discusses an earlier version of ode.
  • N. B. Tufillaro, E. F. Redish, and J. S. Risley, "ode: A numerical simulation of ordinary differential equations," pp. 480--481 in Proceedings of the Conference on Computers in Physics Instruction, Addison--Wesley, 1990.

libplot, a Function Library

Programming with libplot: An overview

GNU libplot is a free function library for drawing two-dimensional vector graphics. It can produce smooth, double-buffered animations for the X Window System, and can export files in many graphics file formats. It is `device-independent' in the sense that its API (application programming interface) is to a large extent independent of the display type or output format.

There are bindings for C, C++, and other languages. The C binding, which is the most frequently used, is also called libplot, and the C++ binding, when it needs to be distinguished, is called libplotter. In this section we use libplot to refer to the library itself, irrespective of binding.

The graphical objects that libplot can draw include paths, circles and ellipses, points, markers, and `adjusted labels' (justified text strings). A path is a sequence of line segments, circular arcs, elliptic arcs, quadratic Bezier curves, and/or cubic Bezier curves. Paths may be open or closed. User-specified filling of paths, circles, and ellipses is supported (fill rule and fill color, as well as pen color, may be specified). There is support for maintaining a Postscript-style stack of graphics contexts, i.e., a stack of drawing attribute sets. Path-related attributes include line thickness, line type, cap type, and join type, and text-related attributes include font name, font size, and text angle.

The fundamental abstraction provided by libplot is that of a Plotter. A Plotter is an object with an interface for the drawing of vector graphics which is similar to the interface provided by a traditional pen plotter. There are many types of Plotter, which differ in the output format they produce. Any number of Plotters, of the same or different types, may exist simultaneously in an application.

The drawing operations supported by Plotters of different types are identical, in agreement with the principle of device independence. So a graphics application that is linked with libplot may easily be written so as to produce output in any or all of the supported output formats.

The following are the currently supported types of Plotter.

  • X Plotters. An X Plotter, when opened, pops up a window on an X Window System display and draws graphics in it. The window will be `spun off' when the Plotter is closed; if it is subsequently reopened, a new window will be popped up. A spun-off window will remain on the screen but will vanish if you type `q' or click your mouse in it. Future releases may permit X Plotters, when reopened, to reuse an existing window.
  • X Drawable Plotters. An X Drawable Plotter draws graphics in one or two specified drawables associated with an X Window System display. A `drawable' is either a window or a pixmap. The drawables must be passed to the Plotter as parameters. (See section Device driver parameters.)
  • PNM Plotters. A PNM Plotter produces a single page of output in "portable anymap" format, and directs it to a file or other specified output stream. There are three types of portable anymap: PBM (portable bitmap, for monochrome graphics), PGM (portable graymap), and PPM (portable pixmap, for colored graphics). The output file will be in whichever of these three formats is most appropriate. The file may be viewed or edited with many applications, such as the free image display application xv.
  • GIF Plotters. A GIF Plotter produces a single page of output in a pseudo-GIF format. Unlike true GIF format, the pseudo-GIF format does not use LZW compression: it uses run-length encoding instead. So it does not transgress the Unisys patent that restricts the use of LZW compression. However, the output file may be viewed or edited with any application that understands GIF format, such as xv. The creation of animated pseudo-GIFs is supported.
  • Illustrator Plotters. An Illustrator Plotter produces a single page of output in the format used by Adobe Illustrator, and directs it to a file or other specified output stream. The file may be edited with Adobe Illustrator (version 5, and more recent versions), or other applications.
  • Postscript Plotters. A Postscript Plotter produces Postscript output and directs it to a file or other specified output stream. If only a single page of graphics is drawn on the Plotter then its output is in EPS (encapsulated Postscript) format, so it may be included in another document. It may also be edited with the idraw drawing editor.
  • Fig Plotters. A Fig Plotter produces a single page of output in Fig format and directs it to a file or other specified output stream. The output may be edited with the xfig drawing editor. The xfig editor will export drawings in various other formats for inclusion in documents.
  • PCL Plotters. A PCL Plotter produces output in PCL 5 format and directs it to a file or other specified output stream. PCL 5 is a powerful version of Hewlett--Packard's Printer Control Language, which supports vector graphics. The output may be sent to a PCL 5 device such as a LaserJet printer or high-end inkjet.
  • HP-GL Plotters. An HP-GL Plotter produces output in the Hewlett--Packard Graphics Language (by default, in HP-GL/2), and directs it to a file or other specified output stream. The output may be imported into another application, or sent to a plotter.
  • Tektronix Plotters. A Tektronix Plotter produces output in Tektronix 4014 format and directs it to a file or other specified output stream. The output may be displayed on any Tektronix 4014 emulator. Such an emulator is built into xterm, the X Window System terminal emulation program. The MS-DOS version of kermit also includes such an emulator.
  • Metafile Plotters. A Metafile Plotter produces output in GNU graphics metafile format and directs it to a file or other specified output stream. This format is an extended version of the `plot(5)' format found on some other operating systems. (See section The Graphics Metafile Format.) It may be translated to other formats by an invocation of GNU plot. (See section The plot Program.)

A distinction among these types of Plotter is that all except X and X Drawable Plotters write graphics to a file or other output stream. An X Plotter pops up its own windows, and an X Drawable Plotter draws graphics in one or two X drawables.

Another distinction is that the first four types of Plotter (X, X Drawable, PNM, and GIF) produce bitmap output, while the remaining types produce output in a vector graphics format. In bitmap output the structure of the graphical objects is lost, but in a vector format it is retained.

An additional distinction is that X, X Drawable, Tektronix and Metafile Plotters are real-time. This means that they draw graphics or write to an output stream as the drawing operations are invoked on them. The remaining types of Plotter are not real-time, since their output streams can only be emitted after all functions have been called. For PNM and GIF Plotters, this is because the bitmap must be constructed before it is written out. For Illustrator and Postscript Plotters, it is because a `bounding box' line must be placed at the head of the output file. For a Fig Plotter, it is because color definitions must be placed at the head of the output file.

The most important operations supported by any Plotter are openpl and closepl, which open and close it. Graphics may be drawn, and drawing attributes set, only within an openpl...closepl pair. The graphics produced within each openpl...closepl pair constitute a `page'. In principle, any Plotter may be opened and closed arbitrarily many times. An X Plotter displays each page in a separate X window, and Postscript, PCL, and HP-GL Plotters render each page as a separate physical page. X Drawable Plotters and Tektronix Plotters manipulate a single drawable or display, on which pages are displayed in succession. Plotters that do not draw in real time (PNM, GIF, Illustrator, Postscript, Fig, PCL, and HP-GL Plotters) may wait until their existence comes to an end (i.e., until they are deleted) before outputting their pages of graphics.

In the current release of libplot, Postscript Plotters delay outputting graphics in this way, but PCL and HP-GL Plotters output each page of graphics individually, i.e., when closepl is invoked. PNM, GIF, Illustrator and Fig Plotters are similar, but output only the first page. That is because PNM, GIF, Illustrator and Fig formats support only a single page of graphics.

There are several other basic operations which any Plotter supports. The `graphics display' drawn in by a Plotter is a square or rectangular region on a display device. But when using any Plotter to draw graphics, a user will specify the coordinates of graphical objects in device-independent `user coordinates', rather than in device coordinates. A Plotter relates the user coordinate system to the device coordinate system by performing an affine transformation, which must be specified by the user.

Immediately after invoking openpl to open a Plotter, an application should invoke the space operation to initialize this transformation. This invocation specifies the rectangular region (in user coordinates) that will be mapped by the Plotter to the graphics display. The affine transformation may be updated at any later time by invoking space again, or by invoking fconcat. The fconcat operation will `concatenate' (i.e., compose) the current affine transformation with any specified affine transformation. This sort of concatenation is a capability familiar from, e.g., Postscript.

Each Plotter maintains a Postscript-style stack of graphics contexts. This makes possible the rapid, efficient drawing of complicated pages of graphics. A graphics context includes the current affine transformation from the user coordinate system to the device coordinate system. It also includes such modal drawing attributes as graphics cursor position, linemode, line thickness, pen and fill colors, and the font used for drawing text. The state of any uncompleted path (if any) is included as well, since paths may be drawn incrementally, one portion (line segment or arc) at a time. The current graphics context is pushed onto the stack by calling savestate, and popped off by calling restorestate.

To permit vector graphics animation, any page of graphics may be split into `frames'. A frame is ended, and a new frame is begun, by invoking the erase operation. On a Plotter that does real-time plotting (i.e., an X, X Drawable, Tektronix, or Metafile Plotter), this erases all plotted objects from the graphics display, allowing a new frame to be drawn. Displaying a sequence of frames in succession creates the illusion of smooth animation.

On most Plotters that do not do real-time plotting (i.e., PNM, Illustrator, Postscript, Fig, PCL, or HP-GL Plotters), invoking erase deletes all plotted objects from an internal buffer. For this reason, most Plotters that do not do real-time plotting will display only the final frame of any multiframe page.

GIF Plotters are in a class by themselves. Even though they do not do real time plotting, a GIF Plotter can produce multi-image output, i.e., an animated pseudo-GIF file, from a multiframe page. As noted above, the pseudo-GIF file produced by a GIF Plotter will contain only the first page of graphics. But if this page consists of multiple frames, then each invocation of erase, after the first, will be treated by default as a separator between successive images.

C Programming with libplot

The C application programming interface

libplot has bindings for several programming languages. Regardless of which language binding is used, the concepts behind libplot (Plotters, and a fixed set of operations that can be applied to any Plotter) remain the same. However, the ways in which Plotters are manipulated (created, selected for use, and deleted) may differ between bindings. This section discusses the C binding.

If you are writing an application in C that will use libplot to draw vector graphics, the first thing you need to know is how, in the C binding, Plotters are manipulated. There are four special functions for this, which you can invoke: newpl, selectpl, deletepl, and the parameter-setting function parampl. Actually, you would usually invoke them under the names pl_newpl, pl_selectpl, pl_deletepl, and pl_parampl. That is because in the C binding, the names of all functions begin with "pl_" unless the header file plotcompat.h is included. See section C compiling and linking.

The pl_newpl function will create a Plotter of specified type. Its first argument may be "X", "Xdrawable", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", or "meta". It returns a nonnegative integer (a "handle") that may be used to refer to the Plotter. Before using a Plotter that you have created (i.e., before invoking any of the libplot operations on it), you must select the Plotter for use by calling pl_selectpl. Only one Plotter may be selected at a time, but by calling pl_selectpl you may switch from Plotter to Plotter at any time, even when the selected Plotter is open. A Plotter that is not currently selected can be deleted, and its storage freed, by calling pl_deletepl.

Strictly speaking, you do not need to call pl_newpl, pl_selectpl, or pl_deletepl in order to draw graphics. That is because at startup, a single Metafile Plotter that writes to standard output (with handle `0') is automatically created and selected. The presence of this default Plotter is for compatibility with pre-GNU versions of libplot. Of course, you may not wish to obtain output in metafile format, and you may not wish to write to standard output.

You should get into the habit of calling pl_deletepl whenever you are finished using a Plotter. In general, Plotters that do not plot graphics in real time (Postscript Plotters in particular) write out graphics only when the plot is finished, and pl_deletepl is called.

The following table summarizes the action of the four functions in the C binding that are used for Plotter manipulation.

int pl_newpl (const char *type, FILE *infile, FILE *outfile, FILE *errfile);
pl_newpl creates a Plotter of type type, where type may be "X", "Xdrawable", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", or "meta". The Plotter will have input stream infile, output stream outfile, and error stream errfile. Any or all of these three may be NULL. Currently, all Plotters are write-only, so infile is ignored. X Plotters and X Drawable Plotters write graphics to an X Window System display rather than to an output stream, so if type is "X" or "Xdrawable" then outfile is ignored as well. Error messages (if any) are written to the stream errfile, unless errfile is NULL. The return value from newpl is a `handle': a nonnegative integer by which the newly created Plotter is referred to. A negative return value indicates the Plotter could not be created.
int pl_selectpl (int handle);
pl_selectpl selects a Plotter, referred to by its handle, for use. If any of the basic libplot operations is subsequently invoked, it will be applied to the selected Plotter. Only one Plotter may be selected at a time. At startup, a single Metafile Plotter that writes to standard output (with handle `0') is automatically created and selected. The handle of the previously selected Plotter is returned. A negative return value indicates the specified Plotter does not exist or could not be selected.
int pl_deletepl (int handle);
pl_deletepl deletes a Plotter, referred to by its handle. The Plotter must not be selected at the time it is deleted. A negative return value indicates the Plotter could not be deleted.
int pl_parampl (const char *parameter, void *value);
pl_parampl sets the value of the device driver parameter parameter to value. Device driver parameters specify Plotter options. The parameter values in effect at the time any Plotter is created are copied into it. For most parameters, value should be a char *, i.e., a string. Unrecognized parameters are ignored. For a list of the recognized parameters and their meaning, see section Device driver parameters.

Up to now we have not discussed the fourth function, pl_parampl. Even though the Plotter interface is largely Plotter-independent, it is useful to be able to specify certain aspects of a Plotter's behavior at the time it is created. Plotter behavior is captured by a manageable number of parameters, which we call device driver parameters. A value for any parameter can be specified by calling pl_parampl. This function does not operate on any particular Plotter: it belongs to the C binding as a whole. The parameter values used by any Plotter are constant over the lifetime of the Plotter, and are those that were in effect when the Plotter was created.

Actually, a slightly more sophisticated rule applies. If at Plotter creation time a parameter is set, the value specified by the most recent call to pl_parampl will be the value used by the Plotter. If at Plotter creation time a parameter is not set, its default value will be used, unless the parameter is string-valued and there is an environment variable of the same name, in which case the value of that environment variable will be used. This rule increases run-time flexibility: an application programmer may allow non-critical driver parameters to be specified by the user via environment variables. Once set, a parameter may be unset by the programmer by calling pl_parampl with a value argument of NULL. This further increases flexibility.

C compiling and linking

The source code for a graphics application written in C, if it is to use libplot, must contain the lines

#include <stdio.h>
#include <plot.h>

The header file plot.h is distributed with libplot, and should have been installed on your system where your C compiler will find it. It contains prototypes for each of the functions in libplot, and some miscellaneous definitions.

In current releases of libplot, the names of all functions begin with the prefix "pl_". For example, the openpl operation is invoked on a Plotter by calling the function pl_openpl. If you wish, you may maintain backward compatibility by also including the header file plotcompat.h. This header file redefines openpl as pl_openpl, and similarly for the other libplot functions.

To link your application with libplot, you would use the appropriate `-l' option(s) on the command line when compiling it. You would use

-lplot -lXaw -lXmu -lXt -lXext -lX11 -lm

or, in recent releases of the X Window System,

-lplot -lXaw -lXmu -lXt -lSM -lICE -lXext -lX11 -lm

(Alternatively, you may need to use `-lplot -lXm -lXt -lXext -lX11 -lm', `-lplot -lXm -lXt -lXext -lX11 -lm -lc -lgen', or `-lplot -lXm -lXt -lXext -lX11 -lm -lc -lPW', on systems that provide Motif widgets instead of Athena widgets. In recent releases of the X Window System, you would insert `-lSM -lICE'. Recent releases of Motif require `-lXp' as well.)

On some platforms, the directories in which libplot or the other libraries are stored must be specified on the command line. For example, the options `-lXaw -lXmu -lXt -lSM -lICE -lXext -lX11', which specify X Window System libraries, may need to be preceded by an option like `-L/usr/X11/lib'.

On most systems libplot is installed as a DLL (dynamically linked library, or `shared' library). This means that the linking with your application will take place at run time rather than compile time. The environment variable LD_LIBRARY_PATH lists the directories which will be searched for DLL's at run time. For your application to be executable, this environment variable should include the directory in which libplot is stored.

Sample drawings in C

The following is a sample application, written in C, that invokes libplot operations to draw vector graphics. It draws an intricate and beautiful path (Bill Gosper's "C" curve, discussed as Item #135 in HAKMEM, MIT Artificial Intelligence Laboratory Memo #239, 1972). As the numeric constant MAXORDER (here equal to 12) is increased, the path will take on the shape of a curly letter "C", which is the envelope of a myriad of epicyclic octagons.

#include <stdio.h>
#include <plot.h>
#define MAXORDER 12

void draw_c_curve (double dx, double dy, int order)
{
  if (order >= MAXORDER)
    pl_fcontrel (dx, dy);     /* continue path along (dx, dy) */
  else
    {
      draw_c_curve (0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
      draw_c_curve (0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);
    }
}

int main ()
{
  int handle;

  /* set a Plotter parameter */
  pl_parampl ("PAGESIZE", "letter");

  /* create a Postscript Plotter that writes to standard output */
  if ((handle = pl_newpl ("ps", stdin, stdout, stderr)) < 0)
    {
      fprintf (stderr, "Couldn't create Plotter\n");
      return 1;
    }
  pl_selectpl (handle);       /* select the Plotter for use */

  if (pl_openpl () < 0)       /* open Plotter */
    {
      fprintf (stderr, "Couldn't open Plotter\n");
      return 1;
    }
  pl_fspace (0.0, 0.0, 1000.0, 1000.0); /* specify user coor system */
  pl_flinewidth (0.25);       /* line thickness in user coordinates */
  pl_pencolorname ("red");    /* path will be drawn in red */
  pl_erase ();                /* erase Plotter's graphics display */
  pl_fmove (600.0, 300.0);    /* position the graphics cursor */
  draw_c_curve (0.0, 400.0, 0);
  if (pl_closepl () < 0)      /* close Plotter */
    {
      fprintf (stderr, "Couldn't close Plotter\n");
      return 1;
    }

  pl_selectpl (0);            /* select default Plotter */
  if (pl_deletepl (handle) < 0) /* delete Plotter we used */
    {
      fprintf (stderr, "Couldn't delete Plotter\n");
      return 1;
    }
  return 0;
}

As you can see, this application begins by calling the pl_newpl function to create a Postscript Plotter. The Postscript Plotter will produce output for a US letter-sized page, though any other standard page size, e.g., "a4", could be substituted. This would be arranged by altering the call to pl_parampl. The PAGESIZE parameter is one of several Plotter parameters that an application programmer may set by calling pl_parampl. For a complete list, see section Device driver parameters.

After the Plotter is created, the application selects it for use, opens it, and draws the "C" curve recursively. The drawing of the curve is accomplished by calling the pl_fmove function to position the Plotter's graphics cursor, and then calling draw_c_curve. This subroutine repeatedly calls pl_fcontrel. The pl_fcontrel function continues a path by adding a line segment to it. The endpoint of each line segment is specified in relative coordinates, i.e., as an offset from the previous cursor position. After the "C" curve is drawn, the Plotter is closed. A Postscript file is written to standard output when pl_deletepl is called to delete the Plotter.

Specifying "pnm", "gif", "ai", "fig", "pcl", "hpgl", "tek", or "meta" as the first argument in the call to pl_newpl, instead of "ps", would yield a Plotter that would write graphics to standard output in the specified format, instead of Postscript. The PAGESIZE parameter is relevant to the "ai", "fig", "pcl", and "hpgl" output formats, but is ignored for the others. Specifying "meta" as the Plotter type may be useful if you wish to avoid recompilation for different output devices. Graphics metafile output may be piped to the plot utility and converted to any other supported output format, or displayed in an X window. See section The plot Program.

If "X" were specified as the first argument of pl_newpl, the curve would be drawn in a popped-up X window, and the output stream argument would be ignored. Which X Window System display the window would pop up on would be determined by the DISPLAY parameter, or if that parameter were not set, by the DISPLAY environment variable. The size of the X window would be determined by the BITMAPSIZE parameter, or if that parameter were not set, by the BITMAPSIZE environment variable. The default value is "570x570". For the "pnm" and "gif" Plotter types, the interpretation of BITMAPSIZE is similar.

You could also specify "Xdrawable" as the Plotter type. For you to make this work, you would need to know a bit about X Window System programming. You would need to create at least one X drawable (i.e., window or a pixmap), and by invoking the pl_parampl function before newpl is called, set it as the value of the parameter XDRAWABLE_DRAWABLE1 or XDRAWABLE_DRAWABLE2. For the parameters that affect X Drawable Plotters, see section Device driver parameters.

The following is another sample application, written in C, that invokes libplot operations to draw vector graphics. It draws a spiral consisting of elliptically boxed text strings, each of which reads "GNU libplot!". This figure will be sent to standard output in Postscript format.

#include <stdio.h>
#include <plot.h>
#include <math.h>
#define SIZE 100.0   /* nominal size of user coordinate frame */
#define EXPAND 2.2   /* expansion factor for elliptical box */

void draw_boxed_string (char *s, double size, double angle)
{
  double true_size, width;

  pl_ftextangle (angle);         /* text inclination angle (degrees) */
  true_size = pl_ffontsize (size);  /* choose font size */
  width = pl_flabelwidth (s);    /* compute width of text string */
  pl_fellipserel (0.0, 0.0,      /* draw surrounding ellipse */
               EXPAND * 0.5 * width, EXPAND * 0.5 * true_size, angle);
  pl_alabel ('c', 'c', s);       /* draw centered text string */
}

int main()
{
  int handle, i;

  /* set a Plotter parameter */
  pl_parampl ("PAGESIZE", "letter");

  /* create a Postscript Plotter that writes to standard output */
  if ((handle = pl_newpl ("ps", stdin, stdout, stderr)) < 0)
    {
      fprintf (stderr, "Couldn't create Plotter\n");
      return 1;
    }
  pl_selectpl (handle);         /* select the Plotter for use */

  if (pl_openpl () < 0)         /* open Plotter */
    {
      fprintf (stderr, "Couldn't open Plotter\n");
      return 1;
    }
  pl_fspace (-(SIZE), -(SIZE), SIZE, SIZE); /* spec. user coor system */
  pl_pencolorname ("blue");     /* pen color will be blue */
  pl_fillcolorname ("white");
  pl_filltype (1);              /* ellipses will be filled with white */
  pl_fontname ("NewCenturySchlbk-Roman"); /* choose a Postscript font */

  for (i = 80; i > 1; i--)      /* loop through angles */
    {
      double theta, radius;

      theta = 0.5 * (double)i;  /* theta is in radians */
      radius = SIZE / pow (theta, 0.35);  /* this yields a spiral */
      pl_fmove (radius * cos (theta), radius * sin (theta));
      draw_boxed_string ("GNU libplot!", 0.04 * radius,
                          (180.0 * theta / M_PI) - 90.0);
    }

  if (pl_closepl () < 0)        /* close Plotter */
    {
      fprintf (stderr, "Couldn't close Plotter\n");
      return 1;
    }
  pl_selectpl (0);
  if (pl_deletepl (handle) < 0) /* delete Plotter we used */
    {
      fprintf (stderr, "Couldn't delete Plotter\n");
      return 1;
    }
  return 0;
}

This example shows what is involved in plotting a text string or text strings. First, the desired font must be retrieved. A font is fully specified by calling pl_fontname, pl_fontsize, and pl_textangle, or their floating point counterparts pl_ffontname, pl_ffontsize, and pl_ftextangle. Since these three functions may be called in any order, each of them returns the size of the font that it selects, as a convenience to the programmer. This may differ slightly from the size specified in the most recent call to pl_fontsize or pl_ffontsize, since many Plotters have only a limited repertory of fonts. The above example plots each text string in the "NewCenturySchlbk-Roman" font, which is available on Postscript Plotters. See section Available text fonts.

If you replace "ps" by "X" in the call to pl_newpl, an X Plotter rather than a Postscript Plotter will be used, and the spiral will be drawn in a popped-up X window. If your X display does not support the "NewCenturySchlbk-Roman" font, you may substitute any other scalable font, such as the widely available "utopia-medium-r-normal". For the format of font names, see section Available text fonts for the X Window System. If the X Plotter is unable to retrieve the font you specify, it will first attempt to use a default scalable font ("Helvetica"), and if that fails, use a default Hershey vector font ("HersheySerif") instead. Hershey fonts are constructed from line segments, so each built-in Hershey font is available on all types of Plotter.

If you are using an older (pre-X11R6) X Window System display, you will find that retrieving a scalable font is a time-consuming operation. The above example may run slowly on some older X displays, since a new font must be retrieved before each text string is drawn. That is because each text string has a different angle of inclination. It is possible to retrieve individual characters from an X11R6 display, rather than retrieving an entire rasterized font. If this feature is available, the X Plotter will automatically take advantage of it to save time.

Animated GIFs in C

Using libplot to create pseudo-GIF files, including animated pseudo-GIFs, is straightforward. A GIF Plotter is a Plotter like any other, and it supports the same drawing operations. However, it has two special properties. (1) It can draw only a single page of graphics, i.e., only the graphics contained in the first openpl...closepl appear in the output file. In this, it resembles other Plotters that do not plot in real time. (2) Within this page, each invocation of erase is normally treated as the beginning of a new image in the output file. There is an exception to this: the first invocation of erase begins a new image only if something has already been drawn.

The reason for the exception is that many programmers who use libplot are in the habit of invoking erase immediately after a Plotter is opened. This is not a bad habit, since a few types of Plotter (e.g., X Drawable and Tektronix Plotters) are `persistent' in the sense that previously drawn graphics remain visible.

The following program creates a simple animated pseudo-GIF, 150 pixels wide and 100 pixels high.

#include <stdio.h>
#include <plot.h>

int main()
{
  int i, handle;

  /* set Plotter parameters */
  pl_parampl ("BITMAPSIZE", "150x100");
  pl_parampl ("BG_COLOR", "orange");
  pl_parampl ("TRANSPARENT_COLOR", "orange");
  pl_parampl ("GIF_ITERATIONS", "100");
  pl_parampl ("GIF_DELAY", "5");

  /* create a GIF Plotter with the specified parameters */
  handle = pl_newpl ("gif", stdin, stdout, stderr);
  pl_selectpl (handle);         /* select the Plotter for use */

  pl_openpl();			/* begin page of graphics */
  pl_space (0, 0, 149, 99);	/* specify user coordinate system */

  pl_pencolorname ("red");      /* objects will be drawn in red */
  pl_linewidth (5);             /* set the line thickness */
  pl_filltype (1);              /* objects will be filled */
  pl_fillcolorname ("black");   /* set the fill color */

  for (i = 0; i < 180 ; i += 15)
    {
      pl_erase ();              /* begin new GIF image */
      pl_ellipse (75, 50, 40, 20, i); /* draw an ellipse */
    }

  pl_closepl ();                /* end page of graphics */
  pl_selectpl (0);              /* select default Plotter */
  pl_deletepl (handle);         /* delete Plotter we used */
  return 0;
}

The animated pseudo-GIF will be written to standard output. It will consist of twelve images, showing the counterclockwise rotation of a black-filled red ellipse through 180 degrees. The pseudo-GIF will be `looped' (see below), so the ellipse will rotate repeatedly.

The parameters of the ellipse are expressed in terms of user coordinates, not pixel coordinates. But the call to pl_space defines user and pixel coordinates to be effectively the same. User coordinates are chosen so that the lower left corner is (0,0) and the upper right corner is (149,99). Since this agrees with the image size, individual pixels may be addressed in terms of integer user coordinates. For example, pl_point(149,99) would set the pixel in the upper right hand corner of the image to the current pen color.

Besides BITMAPSIZE and BG_COLOR, there are several important GIF Plotter parameters that may be set with the pl_parampl function. The TRANSPARENT_COLOR parameter may be set to the name of a color. Pixels in a pseudo-GIF that have that color will be treated as transparent by most software. This is usually used to create a transparent background. In the example above, the background color is specified as orange, but the transparent color is also specified as orange. So the background will not actually be displayed.

The GIF_ITERATIONS parameter, if set, specifies the number of times that a multi-frame pseudo-GIF should be looped. The GIF_DELAY parameter specifies the number of hundredths of a seconds that should elapse between successive images.

The INTERLACE parameter is sometimes useful. If it is set to "yes", the pseudo-GIF will be interlaced. This is of greatest value for single-frame GIFs. For full details on Plotter parameters, see section Device driver parameters.

X Window System animations in C

You may use libplot to produce vector graphics animations on any Plotter that does real-time plotting (i.e., an X, X Drawable, Tektronix, or Metafile Plotter). By definition, the `frames' in any page of graphics are separated by invocations of erase. So the graphics display will be cleared after each frame. If successive frames differ only slightly, a smooth animation will result.

The following is a sample application, written in C, that produces an animation for the X Window System. It displays a `drifting eye'. As the eye drifts across a popped-up window from left to right, it slowly rotates. After the eye has drifted across twice, the window will vanish.

#include <stdio.h>
#include <plot.h>

int main ()
{
  int handle, i = 0, j;

  /* set Plotter parameters */
  pl_parampl ("BITMAPSIZE", "300x150");
  pl_parampl ("VANISH_ON_DELETE", "yes");
  pl_parampl ("USE_DOUBLE_BUFFERING", "yes");

  /* create an X Plotter with the specified parameters */
  if ((handle = pl_newpl ("X", stdin, stdout, stderr)) < 0)
    {
      fprintf (stderr, "Couldn't create Plotter\n");
      return 1;
    }
  pl_selectpl (handle);       /* select the Plotter for use */

  if (pl_openpl () < 0)       /* open Plotter */
    {
      fprintf (stderr, "Couldn't open Plotter\n");
      return 1;
    }
  pl_space (0, 0, 299, 149);  /* specify user coordinate system */
  pl_linewidth (8);           /* line thickness in user coordinates */
  pl_filltype (1);            /* objects will be filled */
  pl_bgcolorname ("saddle brown"); /* background color for the window*/
  for (j = 0; j < 300; j++)
    {
      pl_erase ();            /* erase window */
      pl_pencolorname ("red"); /* choose red pen, with cyan filling */
      pl_fillcolorname ("cyan");
      pl_ellipse (i, 75, 35, 50, i);  /* draw an ellipse */
      pl_colorname ("black"); /* choose black pen, with black filling */
      pl_circle (i, 75, 12);  /* draw a circle [the pupil] */
      i = (i + 2) % 300;      /* shift rightwards */
    }
  if (pl_closepl () < 0)         /* close Plotter */
    {
      fprintf (stderr, "Couldn't close Plotter\n");
      return 1;
    }

  pl_selectpl (0);            /* select default Plotter */
  if (pl_deletepl (handle) < 0) /* delete Plotter we used */
    {
      fprintf (stderr, "Couldn't delete Plotter\n");
      return 1;
    }
  return 0;
}

As you can see, this application begins by calling pl_parampl several times to set device driver parameters, and then calls pl_newpl to create an X Plotter. The X Plotter window will have size 300x150 pixels. This window will vanish when the Plotter is deleted. If the VANISH_ON_DELETE parameter were not set to "yes", the window would remain on the screen until removed by the user (by typing `q' in it, or by clicking with a mouse).

Setting the parameter USE_DOUBLE_BUFFERING to "yes" requests that double buffering be used. This is very important if you wish to produce a smooth animation, with no jerkiness. Normally, an X Plotter draws graphics into a window in real time, and erases the window when pl_erase is called. But if double buffering is used, each frame of graphics is written into an off-screen buffer, and is copied into the window, pixel by pixel, when pl_erase is called or the Plotter is closed. This is a bit counterintuitive, but is exactly what is needed for smooth animation.

After the Plotter is created, it is selected for use and opened. When pl_openpl is called, the window pops up, and the animation begins. In the body of the for loop there is a call to pl_erase, and also a sequence of libplot operations that draws the eye. The pen color and fill color are changed twice with each passage through the loop. You may wish to experiment with the animation parameters to produce the best effects on your video hardware.

The locations of the objects that are plotted in the animation are expressed in terms of user coordinates, not pixel coordinates. But the call to pl_space defines user and pixel coordinates to be effectively the same. User coordinates are chosen so that the lower left corner is (0,0) and the upper right corner is (299,149). Since this agrees with the window size, individual pixels may be addressed in terms of integer user coordinates. For example, pl_point(299,149) would set the pixel in the upper right hand corner of the window to the current pen color.

The following is another sample animation, this time of a rotating letter `A'.

#include <stdio.h>
#include <plot.h>

int main()
{
  int handle, angle = 0;

  /* set Plotter parameters */
  pl_parampl ("BITMAPSIZE", "300x300");
  pl_parampl ("BG_COLOR", "blue"); /* background color for window */
  pl_parampl ("USE_DOUBLE_BUFFERING", "yes");

  /* create an X Plotter with the specified parameters */
  handle = pl_newpl ("X", stdin, stdout, stderr);
  pl_selectpl (handle);

  /* open X Plotter, initialize coordinates, pen, and font */
  pl_openpl ();
  pl_fspace (0.0, 0.0, 1.0, 1.0);  /* use normalized coordinates */
  pl_pencolorname ("white");
  pl_ffontsize (1.0);
  pl_fontname ("NewCenturySchlbk-Roman");

  pl_fmove (.50,.50);           /* move to center */
  while (1)                     /* loop endlessly */
    {
      pl_erase ();
      pl_textangle (angle++);      /* set new rotation angle */
      pl_alabel ('c', 'c', "A");   /* draw a centered `A' */
    }
  pl_closepl();                 /* close Plotter */

  pl_selectpl (0);              /* select default Plotter */
  pl_deletepl (handle);         /* delete Plotter we used */
  return 0;
}

This animation serves as a good test of the capabilities of an X Window System display. On a modern X11R6 display, animation will be smooth and fast. That is because X11R6 displays can rasterize individual characters from a font without rasterizing the entire font. If your X display does not support the "NewCenturySchlbk-Roman" font, you may substitute any other scalable font, such as the widely available "utopia-medium-r-normal". For the format of font names, see section Available text fonts for the X Window System. If the X Plotter is unable to retrieve the font you specify, it will first attempt to use a default scalable font ("Helvetica"). If that too fails, it will use a default Hershey vector font ("HersheySerif") instead.

Animations that use Hershey fonts are normally faster than ones that use Postscript fonts or other X Window System fonts, since the Hershey fonts are constructed from line segments. Rasterizing line segments can be done rapidly. But if you use a scalable font such as "NewCenturySchlbk-Roman" or "utopia-medium-r-normal", you will notice that the rotation speeds up after the letter `A' has rotated through 360 degrees. That is because the `A' at angles past 360 degrees has already been rasterized.

Advanced X Window System programming

Applications that run under the X Window System are normally built using Xt, the X Toolkit. In Xt, an application is constructed from `widgets' such as text entry fields, buttons, sliders, drawing areas, etc. When the application starts up, each widget is configured to respond appropriately to `events', which include key presses and mouse clicks. After the widgets are configured, control is transferred to the Xt event loop.

GNU libplot can be used within the Xt event loop to draw vector graphics. For this, it would use one or more X Drawable Plotters. An X Drawable Plotter is a Plotter that can plot into an off-screen pixmap or an on-screen window, such as a window associated with a widget.

The following sample application shows how an X Drawable Plotter would be used. The application draws a `C' curve, as defined in a previous section, in a popped-up window. The usual Xt command-line options may be used: the window background color is specified with the `-bg' option, the window geometry with `-geometry', etc. The curve is initially drawn in red, but clicking once with the mouse will redraw it in green. A second mouse click will redraw it in red, and so forth. The application will terminate when `q' is typed.

#include <stdio.h>
#include <plot.h>
#include <X11/Xlib.h>
#include <X11/Intrinsic.h>
#include <X11/Shell.h>
#include <X11/StringDefs.h>
#include <X11/Core.h>

int green = 0;                  /* draw in green, not red? */

#define MAXORDER 12
void draw_c_curve (double dx, double dy, int order)
{
  if (order >= MAXORDER)
    pl_fcontrel (dx, dy);       /* continue path along (dx, dy) */
  else
    {
      draw_c_curve (0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
      draw_c_curve (0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);
    }
}

void Redraw (Widget w, XEvent *ev, String *params, Cardinal *n_params)
{
  /* draw C curve */
  pl_erase ();
  pl_pencolorname (green ? "green" : "red");
  pl_fmove (600.0, 300.0);
  draw_c_curve (0.0, 400.0, 0);
  pl_endpath ();
}

void Toggle (Widget w, XEvent *ev, String *params, Cardinal *n_params)
{
  green = (green ? 0 : 1);
  Redraw (w, ev, params, n_params);
}

void Quit (Widget w, XEvent *ev, String *params, Cardinal *n_params)
{
  exit (0);
}

/* mapping of events to actions */
static const String translations =
"<Expose>:      redraw()\n\
<Btn1Down>:     toggle()\n\
<Key>q:         quit()";

/* mapping of actions to subroutines */
static XtActionsRec actions[] =
{
  {"redraw",            Redraw},
  {"toggle",            Toggle},
  {"quit",              Quit},
};

/* default parameters for widgets */
static String default_resources[] =
{
  "Example*geometry:      250x250",
  (String)NULL
};

int main (int argc, char *argv[])
{
  Arg wargs[10];                /* storage of widget args */
  Display *display;             /* X display */
  Widget shell, canvas;         /* toplevel widget; child */
  Window window;                /* child widget's window */
  XtAppContext app_con;         /* application context */
  int handle, i;
  char *bg_colorname = "white";

  /* take background color from command line */
  for (i = 0; i < argc - 1; i++)
    if (strcmp (argv[i], "-bg") == 0)
      bg_colorname = argv[i + 1];

  /* create toplevel shell widget */
  shell = XtAppInitialize (&app_con,
                           (String)"Example", /* app class */
                           NULL,              /* options */
                           (Cardinal)0,       /* num of options */
                           &argc,             /* command line */
                           argv,              /* command line */
                           default_resources,
                           NULL,              /* ArgList */
                           (Cardinal)0        /* num of Args */
                           );

  /* set default widget parameters (including window size) */
  XtAppSetFallbackResources (app_con, default_resources);

  /* map actions to subroutines */
  XtAppAddActions (app_con, actions, XtNumber (actions));

  /* create canvas widget as child of shell widget; realize both */
  XtSetArg(wargs[0], XtNargc, argc);
  XtSetArg(wargs[1], XtNargv, argv);
  canvas = XtCreateManagedWidget ((String)"", coreWidgetClass,
                                  shell, wargs, (Cardinal)2);
  XtRealizeWidget (shell);

  /* for the canvas widget, map events to actions */
  XtSetArg (wargs[0], XtNtranslations,
            XtParseTranslationTable (translations));
  XtSetValues (canvas, wargs, (Cardinal)1);

  /* initialize GNU libplot */
  display = XtDisplay (canvas);
  pl_parampl ("XDRAWABLE_DISPLAY", display);
  window = XtWindow (canvas);
  pl_parampl ("XDRAWABLE_DRAWABLE1", &window);
  pl_parampl ("BG_COLOR", bg_colorname);
  handle = pl_newpl ("Xdrawable", NULL, NULL, stderr);
  pl_selectpl (handle);
  pl_openpl ();
  pl_fspace (0.0, 0.0, 1000.0, 1000.0);
  pl_flinewidth (0.25);

  /* transfer control to X Toolkit event loop (doesn't return) */
  XtAppMainLoop (app_con);

  return 1;
}

Even if you are not familiar with X Window System programming, the structure of this application should be clear. It defines three callbacks: Redraw, Toggle, and Quit. They are invoked respectively in response to (1) a window expose event or mouse click, (2) a mouse click, and (3) a typed `q'. The first drawing of the `C' curve (in red) takes place because the window receives an initial expose event.

This example could be extended to take window resizing into account. Actually, X Drawable Plotters are usually used to draw vector graphics in off-screen pixmaps rather than on-screen windows. Pixmaps, unlike windows, are never resized.

C++ Programming with libplotter

The Plotter class

The C++ binding for libplot is provided by a class library, named libplotter. This library implements a Plotter class, of which all Plotters are instances. Actually, a Plotter would normally be an instance of an appropriate derived class, determined by the Plotter's output format. Derived classes currently include XPlotter, XDrawablePlotter, PNMPlotter, GIFPlotter, AIPlotter, PSPlotter, FigPlotter, PCLPlotter, HPGLPlotter, TekPlotter, and MetaPlotter. The names should be self-explanatory. The operations that may be applied to any Plotter (e.g., the openpl operation, which begins a page of graphics) are implemented as public function members of the Plotter class.

At the time a Plotter is created, its input, output, and error streams must be specified. (The first is ignored, since at present, all Plotters are write-only.) The streams may be specified either as iostreams or as FILE pointers. That is, the two constructors

  Plotter(istream& instream, ostream& outstream, ostream& errstream);
  Plotter(FILE *infile, FILE *outfile, FILE *errfile);

are provided for the base Plotter class, and similarly for each of its derived classes. So, for example, both

PSPlotter plotter(cin, cout, cerr);

and

PSPlotter plotter(stdin, stdout, stderr);

are possible declarations of a Postscript Plotter that writes to standard output. In the iostream case, an ostream with a null stream buffer may be specified as the output stream and/or the error stream, to request that no output take place. In the FILE pointer case, specifying a null FILE pointer would accomplish the same thing. Instances of the XPlotter and XDrawablePlotter classes always ignore the output stream argument, since they write graphics to an X Display rather than to a stream.

The parameter-setting function parampl, which plays an important role in all bindings of libplot, is implemented in libplotter as a static function member of the Plotter class. The following is a formal description.

int Plotter::parampl (const char *parameter, void *value);
Plotter::parampl sets the value of the device driver parameter parameter to value. Device driver parameters specify Plotter options. The parameter values in effect at the time any Plotter is created are copied into it. For most parameters, value should be a char *, i.e., a string. Unrecognized parameters are ignored. For a list of the recognized parameters and their meaning, see section Device driver parameters.

Just as in the C binding, Plotter::parampl gives the programmer fine control over the parameters of subsequently created Plotters. The parameter values used by any Plotter are constant over the lifetime of the Plotter, and are those that were set when the Plotter was created. If at Plotter creation time a parameter is not set, its default value will be used, unless the parameter is string-valued and there is an environment variable of the same name, in which case the value of that environment variable will be used.

Once set, a parameter may be unset by the programmer by calling Plotter::parampl with a value argument of NULL. This further increases flexibility.

C++ compiling and linking

The source code for a graphics application written in C++, if it is to use libplotter, must contain the line

#include <plotter.h>

The header file plotter.h is distributed with libplotter, and should have been installed on your system where your C++ compiler will find it. It declares the Plotter class and its derived class, and also contains some miscellaneous definitions. It includes the header files <iostream.h> and <stdio.h>, so you do not need to include them separately.

To link your application with libplotter, you would use the appropriate `-l' option(s) on the command line when compiling it. You would use

-lplotter -lXaw -lXmu -lXt -lXext -lX11 -lm

or, in recent releases of the X Window System,

-lplotter -lXaw -lXmu -lXt -lSM -lICE -lXext -lX11 -lm

(Alternatively, you may need to use `-lplotter -lXm -lXt -lXext -lX11 -lm', `-lplotter -lXm -lXt -lXext -lX11 -lm -lc -lgen', or `-lplotter -lXm -lXt -lXext -lX11 -lm -lc -lPW', on systems that provide Motif widgets instead of Athena widgets. In recent releases of the X Window System, you would insert `-lSM -lICE'. Recent releases of Motif require `-lXp' as well.)

On some platforms, the directories in which libplotter or the other libraries are stored must be specified on the command line. For example, the options `-lXaw -lXmu -lXt -lSM -lICE -lXext -lX11', which specify X Window System libraries, may need to be preceded by an option like `-L/usr/X11/lib'.

On most systems libplotter is installed as a DLL (dynamically linked library, or `shared' library). This means that the linking with your application will take place at run time rather than compile time. The environment variable LD_LIBRARY_PATH lists the directories which will be searched for DLL's at run time. For your application to be executable, this environment variable should include the directory in which libplotter is stored.

Sample drawings in C++

In a previous section, there are several sample C programs that show how to draw vector graphics using libplot's C binding. See section Sample drawings in C. In this section, we give a modified version of one of the C programs, showing how libplot's C++ binding, i.e., libplotter, can be used similarly.

The following C++ program draws an intricate and beautiful path (Bill Gosper's "C" curve).

#include <plotter.h>
#define MAXORDER 12

void draw_c_curve (Plotter& plotter, double dx, double dy, int order)
{
  if (order >= MAXORDER)
    plotter.fcontrel (dx, dy);	// continue path along (dx, dy)
  else
    {
      draw_c_curve (plotter,
                    0.5 * (dx - dy), 0.5 * (dx + dy), order + 1);
      draw_c_curve (plotter,
                    0.5 * (dx + dy), 0.5 * (dy - dx), order + 1);
    }
}

int main ()
{
  // set a Plotter parameter
  Plotter::parampl ("PAGESIZE", "letter");

  PSPlotter plotter(cin, cout, cerr); // declare Plotter
  if (plotter.openpl () < 0)          // open Plotter
    {
      cerr << "Couldn't open Plotter\n";
      return 1;
    }

  plotter.fspace (0.0, 0.0, 1000.0, 1000.0); // specify user coor system
  plotter.flinewidth (0.25);       // line thickness in user coordinates
  plotter.pencolorname ("red");    // path will be drawn in red
  plotter.erase ();                // erase Plotter's graphics display
  plotter.fmove (600.0, 300.0);    // position the graphics cursor
  draw_c_curve (plotter, 0.0, 400.0, 0);
  if (plotter.closepl () < 0)      // close Plotter
    {
      cerr << "Couldn't close Plotter\n";
      return 1;
    }
  return 0;
}

The above is a straightforward translation of the corresponding C program. Here, plotter is declared as an instance of the PSPlotter class, which will write Postscript graphics to the output stream cout. The graphics are drawn by invoking member functions.

This object-oriented approach to drawing graphics is probably more natural than the approach used by the C binding. With libplotter, the use of multiple Plotters in an application becomes very easy. No switching between Plotters is required: the graphics operations can be immediately invoked on any existing Plotter.

The functions in libplot: A detailed listing

In the current release of GNU libplot, any Plotter supports 92 distinct operations. A language binding for libplot necessarily includes 92 functions that correspond to these operations. In the C binding, these 92 functions belong to the C API (application programming interface). In the C++ binding, they are implemented as public member functions of the Plotter class.

A language binding may also include functions for creating, selecting, and deleting Plotters. For example, the C binding includes the additional functions pl_newpl, pl_selectpl, and pl_deletepl. See section The C application programming interface. In the C binding, the names of all functions should be preceded by "pl_" unless the header file plotcompat.h is included. See section C compiling and linking.

The 92 functions that operate on a specified Plotter are divided into the four sets tabulated below.

  1. Setup functions: functions that open, initialize, or close the Plotter.
  2. Functions that cause the Plotter to draw objects.
  3. Functions that set or affect the Plotter's drawing attributes.
  4. Functions affecting the affine map used by the Plotter to transform user coordinates to device coordinates.

Many functions come in two versions: integer and double precision floating point. Internally, libplot uses double precision floating point. The integer versions are provided for backward compatibility. If there are two versions of a function, the name of the floating point version begins with the letter `f'.

Many functions come in both absolute and relative versions, also. The latter use relative coordinates (i.e., coordinates relative to the current position of the graphics cursor), and their names end in `rel'.

Currently, only a few of the 92 functions have meaningful return values.

Setup functions

The following are the "setup functions" in libplot. They are the basic functions that open, initialize, or close an already-created Plotter. They are listed in the approximate order in which they would be called.

In the C binding, the names of all functions should be preceded by "pl_", unless the header file plotcompat.h is included. See section C compiling and linking. In the C++ binding, these are member functions of the Plotter class and its subclasses.

int openpl ();
openpl opens a Plotter, i.e., begins a page of graphics. This resets the Plotter's drawing attributes to their default values. A negative return value indicates the Plotter could not be opened. Currently, an X Plotter pops up a new window on an X Window System display for each page of graphics, i.e., with each invocation of openpl. Future releases may support window re-use.
int bgcolor (int red, int green, int blue);
bgcolor sets the background color for the Plotter's graphics display, using a 48-bit RGB color model. The arguments red, green and blue specify the red, green and blue intensities of the background color. Each is an integer in the range 0x0000...0xffff, i.e., 0...65535. The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white. bgcolor affects only Plotters that produce bitmaps, i.e., X Plotters, X Drawable Plotters, PNM Plotters, and GIF Plotters. Its effect is simple: the next time the erase operation is invoked on such a Plotter, its display will be filled with the specified color.
int bgcolorname (const char *name);
bgcolorname sets the background color for the the graphics display to be name. For information on what color names are recognized, see section Specifying Colors by Name. Unrecognized colors are interpreted as "white". bgcolorname affects only Plotters that produce bitmaps, i.e., X Plotters, X Drawable Plotters, PNM Plotters, and GIF Plotters. Its effect is simple: the next time the erase operation is invoked on such a Plotter, its display will be filled with the specified color.
int erase ();
erase begins the next frame of a multiframe page, by clearing all previously plotted objects from the graphics display, and filling it with the background color (if any). It is frequently useful to invoke erase at the beginning of each page, i.e., immediately after invoking openpl. That is because some Plotters are persistent, in the sense that objects drawn within an openpl...closepl pair remain on the graphics display even after a new page is begun by a subsequent invocation of openpl. Currently, only X Drawable Plotters and Tektronix Plotters are persistent. Future releases may support optional persistence for X Plotters also. On X Plotters and X Drawable Plotters the effects of invoking erase will be altogether different if the device driver parameter USE_DOUBLE_BUFFERING is set to "yes". In this case, objects will be written to an off-screen buffer rather than to the graphics display, and invoking erase will (1) copy the contents of this buffer to the display, and (2) erase the buffer by filling it with the background color. This `double buffering' feature facilitates smooth animation. See section Device driver parameters.
int space (int x0, int y0, int x1, int y1);
int fspace (double x0, double y0, double x1, double y1);
space and fspace take two pairs of arguments, specifying the positions of the lower left corner and upper right corner of the graphics display, in user coordinates. In other words, calling space or fspace sets the affine transformation from user coordinates to device coordinates. One of these operations must be performed at the beginning of each page of graphics, i.e., immediately after openpl is invoked.
int space2 (int x0, int y0, int x1, int y1, int x2, int y2);
int fspace2 (double x0, double y0, double x1, double y1, double x2, double y2);
space2 and fspace2 are extended versions of space and fspace, and may be used instead. Their arguments are the three defining vertices of an `affine window' (a drawing parallelogram), in user coordinates. The specified vertices are the lower left, the lower right, and the upper left. This window will be mapped affinely onto the graphics display.
int havecap (const char *s);
havecap tests whether or not a Plotter, which need not be open, has a specified capability. The return value is 0, 1, or 2, signifying no/yes/maybe. For unrecognized capabilities the return value is zero. Recognized capabilities include "WIDE_LINES" (i.e., the ability to draw lines with a non-default thickness), "DASH_ARRAY" (the ability to draw in arbitrary dashing styles, as requested by the linedash function), "SETTABLE_BACKGROUND" (the ability to set the color of the background), and "SOLID_FILL". The "HERSHEY_FONTS", "PS_FONTS", "PCL_FONTS", and "STICK_FONTS" capabilities indicate whether or not fonts of a particular class are supported. See section Available text fonts. All Plotters except Tektronix Plotters have the "SOLID_FILL" capability, meaning they can fill paths with solid color. Each such Plotter has at least one of the "EVEN_ODD_FILL" and "NONZERO_WINDING_NUMBER_FILL" capabilities. These indicate the supported rules for determining the `inside' of a path. The `maybe' value is returned for most capabilities by Metafile Plotters, which do no drawing themselves. The output of a Metafile Plotter must be translated to another format, or displayed, by invoking plot.
int flushpl ();
flushpl flushes (i.e., pushes onward) all plotting commands to the display device. This is useful only if the currently selected Plotter does real-time plotting, since it may be used to ensure that all previously plotted objects have been sent to the display and are visible to the user. It has no effect on Plotters that do not do real-time plotting.
int closepl ();
closepl closes a Plotter, i.e., ends a page of graphics. A negative return value indicates the Plotter could not be closed. In the present release of libplot, some Plotters output pages in real time, i.e., with each invocation of closepl. This is true of PCL and HP-GL Plotters, for example. Similarly, Plotters that normally output only a single page (PNM, GIF, Illustrator, and Fig Plotters) do so immediately after that page is ended. However, Postscript Plotters do not output their page(s) of graphics until they are deleted.

Object-drawing functions

The following are the "drawing functions" in libplot. When invoked on a Plotter, these functions cause it to draw objects (paths, circles, ellipses, points, markers, and text strings) on the associated graphics display. A path is a sequence of line segments, arc segments (either circular or elliptic), and/or Bezier curve segments (either quadratic or cubic). Paths are drawn incrementally, one segment at a time.

In the C binding, the names of all functions should be preceded by "pl_", unless the header file plotcompat.h is included. See section C compiling and linking. In the C++ binding, these are member functions of the Plotter class and its subclasses.

int alabel (int horiz_justify, int vert_justify, const char *s);
alabel takes three arguments horiz_justify, vert_justify, and s, which specify an `adjusted label,' i.e., a justified text string. The path under construction (if any) is ended, and the string s is drawn according to the specified justifications. If horiz_justify is equal to `l', `c', or `r', then the string will be drawn with left, center or right justification, relative to the current graphics cursor position. If vert_justify is equal to `b', `x', `c', or `t', then the bottom, baseline, center or top of the string will be placed even with the current graphics cursor position. The graphics cursor is moved to the right end of the string if left justification is specified, and to the left end if right justification is specified. The string may contain escape sequences of various sorts (see section Text string format and escape sequences), though it should not contain line feeds or carriage returns. In fact it should include only printable characters, from the byte ranges 0x20...0x7e and 0xa0...0xff. The string may be plotted at a nonzero angle, if textangle has been called.
int arc (int xc, int yc, int x0, int y0, int x1, int y1);
int farc (double xc, double yc, double x0, double y0, double x1, double y1);
int arcrel (int xc, int yc, int x0, int y0, int x1, int y1);
int farcrel (double xc, double yc, double x0, double y0, double x1, double y1);
arc and farc take six arguments specifying the beginning (x0, y0), end (x1, y1), and center (xc, yc) of a circular arc. If the graphics cursor is at (x0, y0) and a path is under construction, then the arc is added to the path. Otherwise the current path (if any) is ended, and the arc begins a new path. In all cases the graphics cursor is moved to (x1, y1). The direction of the arc (clockwise or counterclockwise) is determined by the convention that the arc, centered at (xc, yc), sweep through an angle of at most 180 degrees. If the three points appear to be collinear, the direction is taken to be counterclockwise. If (xc, yc) is not equidistant from (x0, y0) and (x1, y1) as it should be, it is corrected by being moved to the closest point on the perpendicular bisector of the line segment joining (x0, y0) and (x1, y1). arcrel and farcrel are similar to arc and farc, but use cursor-relative coordinates.
int bezier2 (int x0, int y0, int x1, int y1, int x2, int y2);
int fbezier2 (double x0, double y0, double x1, double y1, double x2, double y2);
int bezier2rel (int x0, int y0, int x1, int y1, int x2, int y2);
int fbezier2rel (double x0, double y0, double x1, double y1, double x2, double y2);
bezier2 and fbezier2 take six arguments specifying the beginning p0=(x0, y0) and end p2=(x2, y2) of a quadratic Bezier curve, and its intermediate control point p1=(x1, y1). If the graphics cursor is at p0 and a path is under construction, then the curve is added to the path. Otherwise the current path (if any) is ended, and the curve begins a new path. In all cases the graphics cursor is moved to p2. bezier2rel and fbezier2rel are similar to bezier2 and fbezier2, but use cursor-relative coordinates. The quadratic Bezier curve is tangent at p0 to the line segment joining p0 to p1, and is tangent at p2 to the line segment joining p1 to p2. So it fits snugly into a triangle with vertices p0, p1, and p2. When using a PCL Plotter to draw Bezier curves on a LaserJet III, you should set the parameter PCL_BEZIERS to "no". That is because the LaserJet III, which was Hewlett--Packard's first PCL 5 printer, does not recognize the Bezier instructions supported by later PCL 5 printers. See section Device driver parameters.
int bezier3 (int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3);
int fbezier3 (double x0, double y0, double x1, double y1, double x2, double y2, double x3, double y3);
int bezier3rel (int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3);
int fbezier3rel (double x0, double y0, double x1, double y1, double x2, double y2, double x3, double y3);
bezier3 and fbezier3 take eight arguments specifying the beginning p0=(x0, y0) and end p3=(x3, y3) of a cubic Bezier curve, and its intermediate control points p1=(x1, y1) and p2=(x2, y2). If the graphics cursor is at p0 and a path is under construction, then the curve is added to the path. Otherwise the current path (if any) is ended, and the curve begins a new path. In all cases the graphics cursor is moved to p3. bezier3rel and fbezier3rel are similar to bezier3 and fbezier3, but use cursor-relative coordinates. The cubic Bezier curve is tangent at p0 to the line segment joining p0 to p1, and is tangent at p3 to the line segment joining p2 to p3. So it fits snugly into a quadrangle with vertices p0, p1, p2, and p3. When using a PCL Plotter to draw Bezier curves on a LaserJet III, you should set the parameter PCL_BEZIERS to "no". That is because the LaserJet III, which was Hewlett--Packard's first PCL 5 printer, does not recognize the Bezier instructions supported by later PCL 5 printers. See section Device driver parameters.
int box (int x1, int y1, int x2, int y2);
int fbox (double x1, double y1, double x2, double y2);
int boxrel (int x1, int y1, int x2, int y2);
int fboxrel (double x1, double y1, double x2, double y2);
box and fbox take four arguments specifying the lower left corner (x1, y1) and upper right corner (x2, y2) of a `box', or rectangle. The path under construction (if any) is ended, and the box is drawn as a new path. This path is also ended, and the graphics cursor is moved to the midpoint of the box. boxrel and fboxrel are similar to box and fbox, but use cursor-relative coordinates.
int circle (int xc, int yc, int r);
int fcircle (double xc, double yc, double r);
int circlerel (int xc, int yc, int r);
int fcirclerel (double xc, double yc, double r);
circle and fcircle take three arguments specifying the center (xc, yc) and radius (r) of a circle. The path under construction (if any) is ended, and the circle is drawn. The graphics cursor is moved to (xc, yc). circlerel and fcirclerel are similar to circle and fcircle, but use cursor-relative coordinates for xc and yc.
int cont (int x, int y);
int fcont (double x, double y);
int contrel (int x, int y);
int fcontrel (double x, double y);
cont and fcont take two arguments specifying the coordinates (x, y) of a point. If a path is under construction, the line segment from the current graphics cursor position to the point (x, y) is added to it. Otherwise the line segment begins a new path. In all cases the graphics cursor is moved to (x, y). contrel and fcontrel are similar to cont and fcont, but use cursor-relative coordinates.
int ellarc (int xc, int yc, int x0, int y0, int x1, int y1);
int fellarc (double xc, double yc, double x0, double y0, double x1, double y1);
int ellarcrel (int xc, int yc, int x0, int y0, int x1, int y1);
int fellarcrel (double xc, double yc, double x0, double y0, double x1, double y1);
ellarc and fellarc take six arguments specifying the three points pc=(xc,yc), p0=(x0,y0), and p1=(x1,y1) that define a so-called quarter ellipse. This is an elliptic arc from p0 to p1 with center pc. If the graphics cursor is at point p0 and a path is under construction, the quarter-ellipse is added to it. Otherwise the path under construction (if any) is ended, and the quarter-ellipse begins a new path. In all cases the graphics cursor is moved to p1. The quarter-ellipse is an affinely transformed version of a quarter circle. It is drawn so as to have control points p0, p1, and p0+p1-pc. This means that it is tangent at p0 to the line segment joining p0 to p0+p1-pc, and is tangent at p1 to the line segment joining p1 to p0+p1-pc. So it fits snugly into a triangle with these three control points as vertices. Notice that the third control point is the reflection of pc through the line joining p0 and p1. ellarcrel and fellarcrel are similar to ellarc and fellarc, but use cursor-relative coordinates.
int ellipse (int xc, int yc, int rx, int ry, int angle);
int fellipse (double xc, double yc, double rx, double ry, double angle);
int ellipserel (int xc, int yc, int rx, int ry, int angle);
int fellipserel (double xc, double yc, double rx, double ry, double angle);
ellipse and fellipse take five arguments specifying the center (xc, yc) of an ellipse, the lengths of its semiaxes (rx and ry), and the inclination of the first semiaxis in the counterclockwise direction from the x axis in the user coordinate system. The path under construction (if any) is ended, and the ellipse is drawn. The graphics cursor is moved to (xc, yc). ellipserel and fellipserel are similar to ellipse and fellipse, but use cursor-relative coordinates.
int endpath ();
endpath terminates the path under construction, if any. A path is constructed by one or more successive calls to cont, line, arc, ellarc, bezier2, bezier3, and/or their floating-point counterparts. The path will also be terminated if any non-path object is drawn, if any path-related drawing attribute is set, or if move or fmove is invoked to set the cursor position. So endpath is almost redundant. However, if a Plotter plots objects in real time, calling endpath will ensure that a constructed path is drawn on the graphics display without delay.
int label (const char *s);
label takes a single string argument s and draws the text contained in s at the current graphics cursor position. The text is left justified, and the graphics cursor is moved to the right end of the string. This function is provided for backward compatibility; the function call label(s) is equivalent to alabel(`l',`x',s).
int labelwidth (const char *s);
double flabelwidth (const char *s);
labelwidth and flabelwidth compute and return the width of a string in the current font, in the user coordinate system. The string is not plotted.
int line (int x1, int y1, int x2, int y2);
int fline (double x1, double y1, double x2, double y2);
int linerel (int x1, int y1, int x2, int y2);
int flinerel (double x1, double y1, double x2, double y2);
line and fline take four arguments specifying the start point (x1, y1) and end point (x2, y2) of a line segment. If the graphics cursor is at (x1, y1) and a path is under construction, the line segment is added to it. Otherwise the path under construction (if any) is ended, and the line segment begins a new path. In all cases the graphics cursor is moved to (x2, y2). linerel and flinerel are similar to line and fline, but use cursor-relative coordinates.
int marker (int x, int y, int type, int size);
int fmarker (double x, double y, int type, double size);
int markerrel (int x, int y, int type, int size);
int fmarkerrel (double x, double y, int type, double size);
marker and fmarker take four arguments specifying the location (x,y) of a marker symbol, its type, and its size in user coordinates. The path under construction (if any) is ended, and the marker symbol is plotted. The graphics cursor is moved to (x,y). markerrel and fmarkerrel are similar to marker and fmarker, but use cursor-relative coordinates for the position (x,y). Marker symbol types 0 through 31 are taken from a standard set, and marker symbol types 32 and above are interpreted as the index of a character in the current text font. See section Available marker symbols.
int point (int x, int y);
int fpoint (double x, double y);
int pointrel (int x, int y);
int fpointrel (double x, double y);
point and fpoint take two arguments specifying the coordinates (x, y) of a point. The path under construction (if any) is ended, and the point is plotted. (Plotters that produce bitmaps draw points as single pixels. Other Plotters draw them as small solid circles, usually the smallest that can be plotted.) The graphics cursor is moved to (x, y). pointrel and fpointrel are similar to point and fpoint, but use cursor-relative coordinates.

Attribute-setting functions

The following are the "attribute functions" in libplot. When invoked on a Plotter, these functions set its drawing attributes, or save them or restore them. Path-related attributes include graphics cursor position, pen color, fill color, fill rule, line thickness, line style, cap style, join style, and miter limit. Text-related attributes include pen color, font name, font size, and text angle.

Setting any path-related drawing attribute automatically terminates the path under construction (if any), as if the endpath operation had been invoked.

In the C binding, the names of all functions should be preceded by "pl_", unless the header file plotcompat.h is included. See section C compiling and linking. In the C++ binding, these are member functions of the Plotter class and its subclasses.

int capmod (const char *s);
capmod sets the cap mode (i.e., cap style) for all paths subsequently drawn on the graphics display. Recognized styles are "butt" (the default), "round", and "projecting". The three styles are visibly distinct only if the line thickness is fairly large. Butt caps do not extend beyond the end of the path. The other two kinds do, however. Round caps are filled semicircles, and projecting caps are filled rectangular regions that extend a distance equal to half the line width beyond the end of the path. PCL and HP-GL Plotters support a fourth cap mode, "triangular". Plotters other than PCL and HP-GL Plotters treat "triangular" as equivalent to "round". This function has no effect on Tektronix Plotters. Also, it has no effect on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default). See section Device driver parameters.
int color (int red, int green, int blue);
color is a convenience function. Calling color is equivalent to calling both pencolor and fillcolor, to set both the the pen color and fill color of all objects subsequently drawn on the graphics display. Note that the physical fill color depends also on the fill fraction, which is specified by calling filltype.
int colorname (const char *name);
colorname is a convenience function. Calling colorname is equivalent to calling both pencolorname and fillcolorname, to set both the the pen color and fill color of all objects subsequently drawn on the graphics display. Note that the physical fill color depends also on the fill fraction, which is specified by calling filltype.
int fillcolor (int red, int green, int blue);
fillcolor sets the fill color of all objects subsequently drawn on the graphics display, using a 48-bit RGB color model. The arguments red, green and blue specify the red, green and blue intensities of the fill color. Each is an integer in the range 0x0000...0xffff, i.e., 0...65535. The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white. Note that the physical fill color depends also on the fill fraction, which is specified by calling filltype.
int fillcolorname (const char *name);
fillcolorname sets the fill color of all objects subsequently drawn on the graphics display to be name. For information on what color names are recognized, see section Specifying Colors by Name. Unrecognized colors are interpreted as "black". Note that the physical fill color depends also on the fill fraction, which is specified by calling filltype.
int fillmod (const char *s);
fillmod sets the fill mode, i.e., fill rule, for all objects subsequently drawn on the graphics display. The fill rule affects only filled, self-intersecting paths: it determines which points are `inside'. Two rules are supported: "even-odd" (the default for all Plotters), and "nonzero-winding". For the distinction, see the Postscript Language Reference Manual. "alternate" is an alias for "even-odd" and "winding" is an alias for "nonzero-winding". Fig Plotters do not support the "nonzero-winding" fill rule, because xfig itself does not support it. Also, HPGL Plotters do not support it if HPGL_VERSION is set to a value less than "2" (the default). See section Device driver parameters. The LaserJet III, which was Hewlett--Packard's first PCL 5 printer, did not support the nonzero-winding fill rule. However, all later PCL 5 printers from Hewlett--Packard support it.
int filltype (int level);
filltype sets the fill fraction for all subsequently drawn objects. A value of 0 for level indicates that objects should be unfilled, or transparent. This is the default. A value in the range 0x0001...0xffff, i.e., 1...65535, indicates that objects should be filled. A value of 1 signifies 100% filling (the fill color will simply be the color specified by calling fillcolor or fillcolorname). If level=0xffff, the fill color will be white. Values between 0x0001 and 0xffff are interpreted as specifying a desaturation, or gray level. For example, 0x8000 specifies 50% filling (the fill color will be intermediate between the color specified by calling fillcolor or fillcolorname, and white). Tektronix Plotters do not support filling, and HP-GL Plotters support filling of arbitrary paths only if the parameter HPGL_VERSION is equal to "1.5" or "2" (the default). (If the version is "1" then only circles and rectangles aligned with the coordinate axes may be filled.) Opaque filling, including white filling, is supported only if the parameter HPGL_VERSION is "2" and the parameter HPGL_OPAQUE_MODE is "yes" (the default). See section Device driver parameters.
int fmiterlimit (double limit);
fmiterlimit sets the miter limit for all paths subsequently drawn on the graphics display. The miter limit controls the treatment of corners, if the join mode is set to "miter" (the default). At a join point of a path, the `miter length' is defined to be the distance between the inner corner and the outer corner. The miter limit is the maximum value that will be tolerated for the miter length divided by the line thickness. If this value is exceeded, the miter will be cut off: the "bevel" join mode will be used instead. Examples of typical values for limit are 10.43 (the default, which cuts off miters if the join angle is less than 11 degrees), 2.0 (the same, for 60 degrees), and 1.414 (the same, for 90 degrees). In general, the miter limit is the cosecant of one-half the minimum angle for mitered joins. The minimum meaningful value for limit is 1.0, which converts all mitered joins to beveled joins, irrespective of join angle. Specifying a value less than 1.0 resets the limit to the default. This function has no effect on X Drawable Plotters or X Plotters, since the X Window System miter limit, which is also 10.43, cannot be altered. It also has no effect on Tektronix Plotters or Fig Plotters, or on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default). See section Device driver parameters.
int fontname (const char *font_name);
double ffontname (const char *font_name);
fontname and ffontname take a single case-insensitive string argument, font_name, specifying the name of the font to be used for all text strings subsequently drawn on the graphics display. (The font for plotting strings is fully specified by calling fontname, fontsize, and textangle.) The size of the font in user coordinates is returned. The default font name depends on the type of Plotter. It is "Helvetica" for all Plotters except PNM, GIF, HP-GL, Tektronix and Metafile Plotters, for which it is "HersheySerif". If the argument font_name is NULL or the empty string, or the font is not available, the default font name will be used. Which fonts are available also depends on the type of Plotter; for a list of all available fonts, see section Available text fonts.
int fontsize (int size);
double ffontsize (double size);
fontsize and ffontsize take a single argument, interpreted as the size, in the user coordinate system, of the font to be used for all text strings subsequently drawn on the graphics display. (The font for plotting strings is fully specified by calling fontname, fontsize, and textangle.) The size of the font in user coordinates is returned. A negative value for size sets the size to the default, which depends on the type of Plotter. Typically, the default font size is 1/50 times the size (i.e., minimum dimension) of the display.
int joinmod (const char *s);
joinmod sets the join mode (i.e., join style) for all paths subsequently drawn on the graphics display. Recognized styles are "miter" (the default), "round", and "bevel". The three styles are visibly distinct only if the line thickness is fairly large. Mitered joins are sharp, rounded joins are round, and beveled joins are squared off. However, unusually sharp joins are never mitered: instead, they are beveled. The angle at which beveling replaces mitering may be specified by calling fmiterlimit. PCL and HP-GL Plotters support a fourth join mode, "triangular". Plotters other than PCL and HP-GL Plotters treat "triangular" as equivalent to "round". This function has no effect on Tektronix Plotters. Also, it has no effect on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default). See section Device driver parameters.
int linedash (int n, const int *dashes, int offset);
int flinedash (int n, const double *dashes, double offset);
linedash and flinedash set the line style for all paths, circles, and ellipses subsequently drawn on the graphics display. They provide much finer control of dash patterns than the linemod function (see below) provides. dashes should be an array of length n. Its elements, which should be positive, are interpreted as distances in the user coordinate system. Along any path, circle, or ellipse, the elements dashes[0]...dashes[n-1] alternately specify the length of a dash and the length of a gap between dashes. When the end of the array is reached, the reading of the array wraps around to the beginning. If the array is empty, i.e., n equals zero, there is no dashing: the drawn line is solid. The offset argument specifies the `phase' of the dash pattern relative to the start of the path. It is interpreted as the distance into the dash pattern at which the dashing should begin. For example, if offset equals zero then the path will begin with a dash, of length dashes[0] in user space. If offset equals dashes[0] then the path will begin with a gap of length dashes[1], and so forth. offset is allowed to be negative. Not all Plotters fully support linedash and flinedash. HP-GL and PCL Plotters cannot dash with a nonzero offset, and in the dash patterns used by X and X Drawable Plotters, each dash and each gap has a maximum length of 255 pixels. linedash and flinedash have no effect on Tektronix and Fig Plotters, and they have no effect on HP-GL Plotters for which the parameter HPGL_VERSION is less than "2" (the default; see section Device driver parameters). Warning: If the map from the user coordinate system to the device coordinate system is not uniform, each dash in a dashed path should ideally be drawn on the graphics display with a length that depends on its direction. But currently, only Postscript Plotters do this. Other Plotters always draw any specified dash with the same length, irrespective of its direction. The length that is used is the minimum length, in the device coordinate system, that can correspond to the specified dash length in the user coordinate system.
int linemod (const char *s);
linemod sets the line style for all paths, circles, and ellipses subsequently drawn on the graphics display. The supported line styles are "solid", "dotted", "dotdashed", "shortdashed", "longdashed", "dotdotdashed", "dotdotdotdashed", and "disconnected". The first seven correspond to the following dash patterns:
"solid"             --------------------------------
"dotted"            -   -   -   -   -   -   -   -
"dotdashed"         ----   -   ----   -   ----   -
"shortdashed"       ----    ----    ----    ----
"longdashed"        -------    -------    -------
"dotdotdashed"      ----   -   -   ----   -   -
"dotdotdotdashed"   ----   -   -   -   ----   -   -   -
In the preceding patterns, each hyphen stands for one line thickness. This is the case for sufficiently thick lines, at least. So for sufficiently thick lines, the distance over which a dash pattern repeats is scaled proportionately to the line thickness. The "disconnected" line style is special. A "disconnected" path is rendered as a set of filled circles, each of which has diameter equal to the nominal line thickness. One of these circles is centered on each of the juncture points of the path (i.e., the endpoints of the line segments or arcs from which it is constructed). Circles and ellipses with "disconnected" line style are invisible. Disconnected paths, circles, and ellipses are not filled. All line styles are supported by all Plotters, with the following exceptions. HP-GL Plotters do not support the "dotdotdotdashed" style unless the parameter HPGL_VERSION is set to "2" (the default). Tektronix Plotters do not support the "dotdotdotdashed" style, and do not support the "dotdotdashed" style unless the parameter TERM is set to "kermit". See section Device driver parameters.
int linewidth (int size);
int flinewidth (double size);
linewidth and flinewidth set the thickness, in the user coordinate system, of all paths, circles, and ellipses subsequently drawn on the graphics display. A negative value resets the thickness to the default. The default thickness depends on the type of Plotter. For most Plotters, it is 1/850 times the size (i.e., minimum dimension) of the display. But for Plotters that produce bitmaps, i.e., X Plotters, X Drawable Plotters, PNM Plotters, and GIF Plotters, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. However, the drawing editors idraw and xfig treat zero-thickness lines as invisible. So when producing editable graphics with a Postscript or Fig Plotter, using a zero line thickness may not be desirable. Tektronix Plotters do not support drawing with other than a default thickness, and HP-GL Plotters do not support doing so if the parameter HPGL_VERSION is set to a value less than "2" (the default; see section Device driver parameters). Warning: If the map from the user coordinate system to the device coordinate system is not uniform, each line segment in a polygonal path should ideally be drawn on the graphics display with a thickness that depends on its direction. But currently, only Postscript Plotters do this. Other Plotters draw all line segments in a path with the same thickness. The thickness that is used is the minimum thickness, in the device coordinate system, that can correspond to the thickness of the path in the user coordinate system.
int move (int x, int y);
int fmove (double x, double y);
int moverel (int x, int y);
int fmoverel (double x, double y);
move and fmove take two arguments specifying the coordinates (x, y) of a point to which the graphics cursor should be moved. The path under construction (if any) is ended, and the graphics cursor is moved to (x, y). This is equivalent to lifting the pen on a plotter and moving it to a new position, without drawing any line. moverel and fmoverel are similar to move and fmove, but use cursor-relative coordinates.
int pencolor (int red, int green, int blue);
pencolor sets the pen color of all objects subsequently drawn on the graphics display, using a 48-bit RGB color model. The arguments red, green and blue specify the red, green and blue intensities of the pen color. Each is an integer in the range 0x0000...0xffff, i.e., 0...65535. The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white. HP-GL Plotters support drawing with a white pen only if the value of the parameter HPGL_VERSION is "2" (the default), and the value of the parameter HPGL_OPAQUE_MODE is "yes" (the default). See section Device driver parameters.
int pencolorname (const char *name);
pencolorname sets the pen color of all objects subsequently drawn on the graphics display to be name. For information on what color names are recognized, see section Specifying Colors by Name. Unrecognized colors are interpreted as "black". HP-GL Plotters support drawing with a white pen only if the value of the parameter HPGL_VERSION is "2" (the default) and the value of the parameter HPGL_OPAQUE_MODE is "yes" (the default). See section Device driver parameters.
int restorestate ();
restorestate pops the current graphics context off the stack of drawing states. The graphics context consists largely of libplot's drawing attributes, which are set by the attribute functions documented in this section. So popping off the graphics context restores the drawing attributes to values they previously had. A path under construction is regarded as part of the graphics context. For this reason, calling restorestate automatically calls endpath to terminate the path under construction, if any. All graphics contexts on the stack are popped off when closepl is called, as if restorestate had been called repeatedly.
int savestate ();
savestate pushes the current graphics context onto the stack of drawing states. The graphics context consists largely of libplot's drawing attributes, which are set by the attribute functions documented in this section. A path under construction, if any, is regarded as part of the graphics context. That is because paths may be drawn incrementally, one line segment or arc at a time. When a graphics context is returned to, the path under construction may be continued.
int textangle (int angle);
double ftextangle (double angle);
textangle and ftextangle take one argument, which specifies the angle in degrees counterclockwise from the x (horizontal) axis in the user coordinate system, for text strings subsequently drawn on the graphics display. The default angle is zero. (The font for plotting strings is fully specified by calling fontname, fontsize, and textangle.) The size of the font for plotting strings, in user coordinates, is returned.

Mapping functions

The following are the "mapping functions" in libplot. When invoked on a Plotter, these functions affect the affine transformation it employs for mapping from the user coordinate system to the device coordinate system. They may be viewed as performing transformations of the user coordinate system. Their names resemble those of the corresponding functions in the Postscript language. For information on how to use them to draw graphics efficiently, consult any good book on Postscript programming, or the Postscript Language Reference Manual.

In the C binding, the names of all functions should be preceded by "pl_", unless the header file plotcompat.h is included. See section C compiling and linking. In the C++ binding, these are member functions of the Plotter class and its subclasses.

int fconcat (double m0, double m1, double m2, double m3, double tx, double ty);
Apply a Postscript-style transformation matrix, i.e., affine map, to the user coordinate system. That is, apply the linear transformation defined by the two-by-two matrix [m0 m1 m2 m3] to the user coordinate system, and also translate by tx units in the x direction and ty units in the y direction, relative to the former user coordinate system. The following three functions (frotate, fscale, ftranslate) are convenience functions that are special cases of fconcat.
int frotate (double theta);
Rotate the user coordinate system axes about their origin by theta degrees, with respect to their former orientation. The position of the user coordinate origin and the size of the x and y units remain unchanged.
int fscale (double sx, double sy);
Make the x and y units in the user coordinate system be the size of sx and sy units in the former user coordinate system. The position of the user coordinate origin and the orientation of the coordinate axes are unchanged.
int ftranslate (double tx, double ty);
Move the origin of the user coordinate system by tx units in the x direction and ty units in the y direction, relative to the former user coordinate system. The size of the x and y units and the orientation of the coordinate axes are unchanged.

Device driver parameters

In designing the libplot library, every effort was made to make the Plotter interface independent of the type of Plotter. To the extent that device dependence exists, it is captured by a manageable number of device driver parameters.

In the C binding, a value for any parameter may be specified by calling the pl_parampl function. The pl_parampl function does not operate on any particular Plotter: it belongs to the C binding as a whole. The parameter values used by any Plotter are constant over the lifetime of the Plotter, and are those that were in effect when the Plotter was created. Each driver parameter has a value that is allowed to be a generic pointer (a void *). For most parameters, this value should be a string (a char *). pl_parampl may be called any number of times. A parameter may be unset by calling pl_parampl with a value argument of NULL.

If at Plotter creation time a parameter is not set, its default value will be used, unless the parameter is string-valued and there is an environment variable of the same name, in which case the value of that environment variable will be used. This rule increases run-time flexibility: an application programmer may allow non-critical driver parameters to be specified by the user via environment variables.

In the C++ binding, the function Plotter::parampl is the analogue of pl_parampl. It is a static member of the Plotter class and its subclasses. Like pl_parampl, it does not act on any particular Plotter: rather, it sets the parameters of subsequently created Plotters.

The following are the currently recognized parameters (unrecognized ones are ignored). The most important ones are DISPLAY, which affects X Plotters, BITMAPSIZE, which affects X Plotters, PNM Plotters, and GIF Plotters, and PAGESIZE, which affects Illustrator, Postscript, Fig, and HP-GL Plotters. These three parameters are listed first and the others alphabetically. Many of the parameters, such as the several whose names begin with "HPGL", affect only a single type of Plotter.

DISPLAY
(Default NULL.) The X Window System display on which the graphics display will be popped up, as an X window. This is relevant only to X Plotters.
BITMAPSIZE
(Default "570x570".) The size of the graphics display in terms of pixels. This is relevant only to X Plotters, PNM Plotters, and GIF Plotters. For X Plotters, the value of this parameter will automatically, if it is not set, be taken from the X resource Xplot.geometry. This is for backward compatibility.
PAGESIZE
(Default "letter".) The size of the page on which the graphics display will be positioned. This is relevant only to Illustrator, Postscript, Fig, PCL, and HP-GL Plotters. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. For Illustrator and Postscript Plotters, the graphics display will be a square region centered on the specified page and occupying its full width, with allowance being made for margins. For Fig Plotters, the graphics display will be a square region of the same size, positioned in the upper left corner of an xfig display. For PCL and HP-GL Plotters, the graphics display will be a square region of the same size, but may be positioned differently. For PCL Plotters, fine control over its positioning on the page may be accomplished by setting the PCL_XOFFSET and PCL_YOFFSET parameters. For HP-GL Plotters, HPGL_XOFFSET and HPGL_YOFFSET are used similarly.
BG_COLOR
(Default "white".) The initial background color of the graphics display, when drawing each page of graphics. This is relevant to X Plotters, PNM Plotters, GIF Plotters, and X Drawable Plotters (for the last, the background color shows up only if erase is invoked). The background color may be changed at any later time by invoking the bgcolor (or bgcolorname) and erase operations. An unrecognized color name sets the background color to the default. For information on what names are recognized, see section Specifying Colors by Name.
GIF_ANIMATION
(Default "yes".) Relevant only to GIF Plotters. "yes" means that the erase operation will have special semantics: with the exception of its first invocation, it will act as a separator between successive images in the written-out pseudo-GIF file. "no" means that erase should act as it does on other Plotters that do not write graphics in real time, i.e., it should erase the image under construction by filling it with the background color. If "no" is specified, the pseudo-GIF file will contain only a single image.
GIF_DELAY
(Default "0".) Relevant only to GIF Plotters. The delay, in hundredths of a second, after each image in a written-out animated pseudo-GIF file. The value should be an integer in the range "0"..."65535".
GIF_ITERATIONS
(Default "0".) Relevant only to GIF Plotters. The number of times that an animated pseudo-GIF file should be `looped'. The value should be an integer in the range "0"..."65535".
HPGL_ASSIGN_COLORS
(Default "no".) Relevant only to HP-GL Plotters, and only if the value of HPGL_VERSION is "2". "no" means to draw with a fixed set of pens, specified by setting the HPGL_PENS parameter. "yes" means that pen colors will not restricted to the palette specified in HPGL_PENS: colors will be assigned to "logical pens" in the range #1...#31, as needed. Other than color LaserJet printers and DesignJet plotters, not many HP-GL/2 devices allow the assignment of colors to logical pens. So this parameter should be used with caution.
HPGL_OPAQUE_MODE
(Default "yes".) Relevant only to HP-GL Plotters, and only if the value of HPGL_VERSION is "2". "yes" means that the HP-GL/2 output device should be switched into opaque mode, rather than transparent mode. This allows objects to be filled with opaque white and other opaque colors. It also allows the drawing of visible white lines, which by convention are drawn with pen #0. Not all HP-GL/2 devices support opaque mode or the use of pen #0 to draw visible white lines. In particular, HP-GL/2 pen plotters do not. Some older HP-GL/2 devices reportedly malfunction if asked to switch into opaque mode. If the output of an HP-GL Plotter is to be sent to such a device, a "no" value is recommended.
HPGL_PENS
(Default "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan" if the value of HPGL_VERSION is "1.5" or "2" and "1=black" if the value of HPGL_VERSION is "1". Relevant only to HP-GL Plotters. The set of available pens; the format should be self-explanatory. The color for any pen in the range #1...#31 may be specified. For information on what color names are recognized, see section Specifying Colors by Name. Pen #1 must always be present, though it need not be black. Any other pen in the range #1...#31 may be omitted.
HPGL_ROTATE
(Default "0".) Relevant only to HP-GL Plotters. The angle, in degrees, by which the graphics display should be rotated on the page relative to the default orientation. Recognized values are "0", "90", "180", and "270"; "no" and "yes" are equivalent to "0" and "90" respectively. This parameter is provided to facilitate switching between portrait and landscape orientations. For HP-GL devices this is frequently a concern, since some HP-GL devices ("plotters") draw with a default landscape orientation, and others ("printers") draw with a default portrait orientation. "180" and "270" are supported only if HPGL_VERSION is "2".
HPGL_VERSION
(Default "2".) Relevant only to HP-GL Plotters. "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2. If the version is less than "2" then the only available fonts will be vector fonts, and all paths will be drawn with a default thickness, so that invoking capmod, joinmod, and fmiterlimit will have no effect. Also, the `nonzero winding number rule' will not be supported when filling paths, so invoking fillmod will have no effect. Additionally, if the version is "1" then the filling of arbitrary paths will not be supported (circles and rectangles aligned with the coordinate axes may be filled, however).
HPGL_XOFFSET, HPGL_YOFFSET
(Defaults "0.0cm" and "0.0cm".) Relevant only to HP-GL Plotters. Adjustments, in the x and y directions, of the position of the graphics display on the page. They may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in".
INTERLACE
(Default "no".) Relevant only to GIF Plotters. If the value is "yes", the pseudo-GIF output file will be interlaced. That means that it will be displayed in an interlaced (nonlinear) way by many applications.
MAX_LINE_LENGTH
(Default "500".) The maximum number of points that a path may contain, before it is flushed to the display device. If this flushing occurs, the path will be split into two or more sub-paths, though the splitting should not be noticeable. Splitting will not be performed if the path is filled. This parameter is relevant to all Plotters except Tektronix and Metafile Plotters. The reason for splitting long paths is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. It is not relevant to Tektronix or Metafile Plotters, since they draw paths in real time and have no buffer limitations.
META_PORTABLE
(Default "no".) Relevant only to Metafile Plotters. "yes" means that the output should be in a portable (human-readable) version of the metafile format, rather than the default (binary) version. See section The Graphics Metafile Format.
PCL_ASSIGN_COLORS
(Default "no".) Relevant only to PCL Plotters. "no" means to draw with a fixed set of pens. "yes" means that pen colors will not restricted to this palette: colors will be assigned to "logical pens", as needed. Other than color LaserJet printers, not many PCL 5 devices allow the assignment of colors to logical pens. So this parameter should be used with caution.
PCL_BEZIERS
(Default "yes".) Relevant only to PCL Plotters. "yes" means that when drawing Bezier curves, the special `Bezier instructions' will be used. "no" means that these instructions will not be used. Instead, each Bezier curve will be approximated and drawn as a polygonal line. Other than the LaserJet III, which was Hewlett--Packard's first PCL 5 printer, all Hewlett--Packard's PCL 5 printers support the Bezier instructions.
PCL_ROTATE
(Default "0".) Relevant only to PCL Plotters. The angle, in degrees, by which the graphics display should be rotated on the page relative to the default orientation. Recognized values are "0", "90", "180", and "270"; "no" and "yes" are equivalent to "0" and "90" respectively. This parameter is provided to facilitate switching between portrait and landscape orientations. For PCL 5 devices this is frequently a concern, since some PCL 5 devices ("plotters") draw with a default landscape orientation, and others ("printers") draw with a default portrait orientation.
PCL_XOFFSET, PCL_YOFFSET
(Defaults "0.0cm" and "0.0cm".) Relevant only to PCL Plotters. Adjustments, in the x and y directions, of the position of the graphics display on the page. They may be specified in centimeters, millimeters, or inches. For example, an offset could be specified as "2cm" or "1.2in".
PNM_PORTABLE
(Default "no".) Relevant only to PNM Plotters. "yes" means that the output should be in a portable (human-readable) version of PBM/PGM/PPM format, rather than the default (binary) version. `Portable' is something of a misnomer, since binary PBM/PGM/PPM files are also portable, in the sense that they are machine-independent.
TERM
(Default NULL.) Relevant only to Tektronix Plotters. If the value is "xterm", "xterms", or "kterm", it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm. Before drawing graphics, a Tektronix Plotter will emit an escape sequence that causes the terminal emulator's auxiliary Tektronix window, which is normally hidden, to pop up. After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted. The Tektronix window will remain on the screen. If the value is "kermit", "ansi.sys", "ansissys", "ansi.sysk", or "ansisysk", it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the MS-DOS version of kermit. Before drawing graphics, a Tektronix Plotter will emit an escape sequence that switches the terminal emulator to Tektronix mode. Also, some of the Tektronix control codes emitted by the Plotter will be kermit-specific. There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported). The "dotdotdashed" line style will be supported, which is also not normally the case. After drawing graphics, the Plotter will emit an escape sequence that returns the emulator to VT100 mode. The key sequence `ALT minus' may be employed manually within kermit to switch between the two modes.
TRANSPARENT_COLOR
(Default "none".) Relevant only to GIF Plotters. If the value is a recognized color name, that color, if it appears in the pseudo-GIF output file, will be treated as transparent by most applications that display GIF files. For information on what names are recognized, see section Specifying Colors by Name. If TRANSPARENT_COLOR is set and an animated pseudo-GIF file is produced, the `restore to background' disposal method will be used for each image in the file. Otherwise, the `unspecified' disposal method will be used.
USE_DOUBLE_BUFFERING
(Default "no".) Relevant only to X Plotters and X Drawable Plotters. If the value is "yes", a double buffering scheme will be used when drawing graphics. Each frame of graphics, within a openpl...closepl pair, will be written to an off-screen buffer rather than to the Plotter's display. When erase is invoked to end a frame, or when closepl is invoked, the contents of the off-screen buffer will be copied to the Plotter's display, pixel by pixel. If successive frames differ only slightly, this will create the illusion of smooth animation. Some X displays provide special hardware support for double buffering. If this support is available, the X Plotter will detect its presence, and will draw graphics using the appropriate extension to the X11 protocol (either DBE or MBX). In this case the animation will be significantly faster; on high-end graphics hardware, at least.
VANISH_ON_DELETE
(Default "no".) Relevant only to X Plotters. If the value is "yes", when a Plotter is deleted, the window or windows that it has popped up will vanish. Otherwise, each such window will remain on the screen until it is removed by the user (by typing `q' in it, or by clicking with a mouse).
XDRAWABLE_COLORMAP
(Default NULL.) Relevant only to X Drawable Plotters. If the value is non-NULL, it should be a Colormap *, a pointer to a colormap from which colors should be allocated. NULL indicates that the colormap to be used should be the default colormap of the default screen of the X display.
XDRAWABLE_DISPLAY
(Default NULL.) Relevant only to X Drawable Plotters. The value should be a Display *, a pointer to the X display with which the drawable(s) to be drawn in are associated.
XDRAWABLE_DRAWABLE1
XDRAWABLE_DRAWABLE2
(Default NULL.) Relevant only to X Drawable Plotters. If set, the value of each of these parameters should be a Drawable *, a pointer to a drawable to be drawn in. A `drawable' is either a window or a pixmap. At the time an X Drawable Plotter is created, at least one of the two parameters must be set. X Drawable Plotters support simultaneous drawing in two drawables because it is often useful to be able to draw graphics simultaneously in both an X window and its background pixmap. If two drawables are specified, they must have the same dimensions and depth, and be associated with the same screen of the X display.

@ifnottex The following appendices contain miscellaneous information on the GNU plotting utilities.

Fonts, Strings, and Symbols

The libplot vector graphics library and applications built on it, such as graph and plot, can draw text strings in a wide variety of fonts. Text strings may include characters from more than one font in a typeface, and may include superscripts, subscripts, and square roots. A wide variety of plotting symbols can also be drawn. The following sections explain how to use these features.

Available text fonts

The libplot library and applications built on it, such as graph, plot, tek2plot, and pic2plot, can use many fonts. These include 22 Hershey vector fonts, 35 Postscript fonts, 45 PCL 5 fonts, and 18 Hewlett--Packard vector fonts. We call these 120 supported fonts the `built-in' fonts. The Hershey fonts are constructed from stroked characters digitized c. 1967 by Dr. Allen V. Hershey at the U.S. Naval Surface Weapons Center in Dahlgren, VA. The 35 Postscript fonts are the outline fonts resident in all modern Postscript printers, and the 45 PCL 5 fonts are the outline fonts resident in modern Hewlett--Packard LaserJet printers and plotters. (The old LaserJet III, which was Hewlett--Packard's first PCL 5 printer, supported only 8 of the 45.) The 18 Hewlett--Packard vector fonts are fonts that are resident in Hewlett--Packard printers and plotters (mostly the latter).

The Hershey fonts can be used by all types of Plotter supported by libplot, and the Postscript fonts can be used by X, Illustrator, Postscript, and Fig Plotters. So, for example, all variants of graph can use the Hershey fonts, and graph -T X, graph -T ai, graph -T ps and graph -T fig can use the Postscript fonts. The PCL 5 fonts can be used by by Illustrator, PCL, and HP-GL Plotters, and by graph -T ai, graph -T pcl, and graph -T hpgl. The Hewlett--Packard vector fonts can be used by by PCL and HP-GL Plotters, and by graph -T pcl and graph -T hpgl. X Plotters and graph -T X are not restricted to the built-in Hershey and Postscript fonts. They can use any X Window System font.

The plotfont utility, which accepts the `-T' option, will print a character map of any font that is available in the specified output format. See section The plotfont Utility.

For the purpose of plotting text strings (see section Text string format and escape sequences), the 120 built-in fonts are divided into typefaces. As you can see from the following tables, our convention is that in any typeface with more than a single font, font #1 is the normal font, font #2 is italic or oblique, font #3 is bold, and font #4 is bold italic or bold oblique. Additional variants (if any) are numbered #5 and higher.

The 22 Hershey fonts are divided into typefaces as follows.

  • HersheySerif
    1. HersheySerif
    2. HersheySerif-Italic
    3. HersheySerif-Bold
    4. HersheySerif-BoldItalic
    5. HersheyCyrillic
    6. HersheyCyrillic-Oblique
    7. HersheyEUC
  • HersheySans
    1. HersheySans
    2. HersheySans-Oblique
    3. HersheySans-Bold
    4. HersheySans-BoldOblique
  • HersheyScript
    1. HersheyScript
    2. HersheyScript
    3. HersheyScript-Bold
    4. HersheyScript-Bold
  • HersheyGothicEnglish
  • HersheyGothicGerman
  • HersheyGothicItalian
  • HersheySerifSymbol
    1. HersheySerifSymbol
    2. HersheySerifSymbol-Oblique
    3. HersheySerifSymbol-Bold
    4. HersheySerifSymbol-BoldOblique
  • HersheySansSymbol
    1. HersheySansSymbol
    2. HersheySansSymbol-Oblique

Nearly all Hershey fonts except the Symbol fonts use the ISO-Latin-1 encoding, which is a superset of ASCII. The Symbol fonts consist of Greek characters and mathematical symbols, and use the symbol font encoding documented in the Postscript Language Reference Manual. By convention, each Hershey typeface contains a symbol font (HersheySerifSymbol or HersheySansSymbol, as appropriate) as font #0.

HersheyCyrillic, HersheyCyrillic-Oblique, and HersheyEUC (which is a Japanese font) are the only non-Symbol Hershey fonts that do not use the ISO-Latin-1 encoding. For their encodings, see section Cyrillic and Japanese fonts.

The 35 Postscript fonts are divided into typefaces as follows.

  • Helvetica
    1. Helvetica
    2. Helvetica-Oblique
    3. Helvetica-Bold
    4. Helvetica-BoldOblique
  • Helvetica-Narrow
    1. Helvetica-Narrow
    2. Helvetica-Narrow-Oblique
    3. Helvetica-Narrow-Bold
    4. Helvetica-Narrow-BoldOblique
  • Times
    1. Times-Roman
    2. Times-Italic
    3. Times-Bold
    4. Times-BoldItalic
  • AvantGarde
    1. AvantGarde-Book
    2. AvantGarde-BookOblique
    3. AvantGarde-Demi
    4. AvantGarde-DemiOblique
  • Bookman
    1. Bookman-Light
    2. Bookman-LightItalic
    3. Bookman-Demi
    4. Bookman-DemiItalic
  • Courier
    1. Courier
    2. Courier-Oblique
    3. Courier-Bold
    4. Courier-BoldOblique
  • NewCenturySchlbk
    1. NewCenturySchlbk-Roman
    2. NewCenturySchlbk-Italic
    3. NewCenturySchlbk-Bold
    4. NewCenturySchlbk-BoldItalic
  • Palatino
    1. Palatino-Roman
    2. Palatino-Italic
    3. Palatino-Bold
    4. Palatino-BoldItalic
  • ZapfChancery-MediumItalic
  • ZapfDingbats
  • Symbol

All Postscript fonts except the ZapfDingbats and Symbol fonts use the ISO-Latin-1 encoding. The encodings used by the ZapfDingbats and Symbol fonts are documented in the Postscript Language Reference Manual. By convention, each Postscript typeface contains the Symbol font as font #0.

The 45 PCL 5 fonts are divided into typefaces as follows.

  • Univers
    1. Univers
    2. Univers-Oblique
    3. Univers-Bold
    4. Univers-BoldOblique
  • UniversCondensed
    1. UniversCondensed
    2. UniversCondensed-Oblique
    3. UniversCondensed-Bold
    4. UniversCondensed-BoldOblique
  • CGTimes
    1. CGTimes-Roman
    2. CGTimes-Italic
    3. CGTimes-Bold
    4. CGTimes-BoldItalic
  • Albertus
    1. AlbertusMedium
    2. AlbertusMedium
    3. AlbertusExtraBold
    4. AlbertusExtraBold
  • AntiqueOlive
    1. AntiqueOlive
    2. AntiqueOlive-Italic
    3. AntiqueOlive-Bold
  • Arial
    1. Arial-Roman
    2. Arial-Italic
    3. Arial-Bold
    4. Arial-BoldItalic
  • ClarendonCondensed
  • Coronet
  • Courier
    1. Courier
    2. Courier-Italic
    3. Courier-Bold
    4. Courier-BoldItalic
  • Garamond
    1. Garamond
    2. Garamond-Italic
    3. Garamond-Bold
    4. Garamond-BoldItalic
  • LetterGothic
    1. LetterGothic-Roman
    2. LetterGothic-Italic
    3. LetterGothic-Bold
    4. LetterGothic-BoldItalic
  • Marigold
  • CGOmega
    1. CGOmega-Roman
    2. CGOmega-Italic
    3. CGOmega-Bold
    4. CGOmega-BoldItalic
  • TimesNewRoman
    1. TimesNewRoman
    2. TimesNewRoman-Italic
    3. TimesNewRoman-Bold
    4. TimesNewRoman-BoldItalic
  • Wingdings
  • Symbol

All PCL 5 fonts except the Wingdings and Symbol fonts use the ISO-Latin-1 encoding. The encoding used by the Symbol font is the symbol font encoding documented in the Postscript Language Reference Manual. By convention, each PCL typeface contains the Symbol font as font #0.

The 18 Hewlett--Packard vector fonts are divided into typefaces as follows.

  • Arc
    1. Arc
    2. Arc-Oblique
    3. Arc-Bold
    4. Arc-BoldOblique
  • Stick
    1. Stick
    2. Stick-Oblique
    3. Stick-Bold
    4. Stick-BoldOblique
  • ArcANK
    1. ArcANK*
    2. ArcANK-Oblique*
    3. ArcANK-Bold*
    4. ArcANK-BoldOblique*
  • StickANK
    1. StickANK*
    2. StickANK-Oblique*
    3. StickANK-Bold*
    4. StickANK-BoldOblique*
  • ArcSymbol*
  • StickSymbol*

The Hewlett--Packard vector fonts with an asterisk (the ANK and Symbol fonts) are only available when producing HP-GL output for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters. The ANK fonts are Japanese fonts (see section Cyrillic and Japanese fonts), and the Symbol fonts contain a few miscellaneous mathematical symbols. To ensure that these fonts are available, you must set the environment variable or driver parameter HPGL_VERSION to "1.5".

All Hewlett--Packard vector fonts except the ANK and Symbol fonts use the ISO-Latin-1 encoding. The Arc fonts are proportional (variable-width) fonts, and the Stick fonts are fixed-width fonts. If HPGL_VERSION is "1.5" then the Arc fonts will be kerned. But if HPGL_VERSION is "2" (the default), there will be no kerning. Apparently Hewlett--Packard dropped support for device-resident kerning tables when moving from HP-GL to modern HP-GL/2 and PCL 5. For information about Hewlett--Packard vector fonts and the way in which they are kerned (in pen plotters, at least), see the article by L. W. Hennessee et al. in the Nov. 1981 issue of the Hewlett--Packard Journal.

To what extent do the fonts supported by libplot contain ligatures? The Postscript fonts, the PCL 5 fonts, and the Hewlett--Packard vector fonts, at least as implemented in libplot, do not contain ligatures. However, six of the 22 Hershey fonts contain ligatures. The character combinations "fi", "ff", "fl", "ffi", and "ffl" are automatically drawn as ligatures in HersheySerif and HersheySerif-Italic. (Also in the two HersheyCyrillic fonts and HersheyEUC, since insofar as printable ASCII characters are concerned, they are identical [or almost identical] to HersheySerif.) In addition, "tz" and "ch" are ligatures in HersheyGothicGerman. The German double-s character `@ss{'}, which is called an `eszet', is not treated as a ligature in any font. To obtain an eszet, you must either request one with the escape sequence "\ss" (see section Text string format and escape sequences), or, if you have an 8-bit keyboard, type an eszet explicitly.

Cyrillic and Japanese fonts

The built-in fonts discussed in the previous section include Cyrillic and Japanese vector fonts. This section explains how these fonts are encoded, i.e., how their character maps are laid out. You may use the plotfont utility to display the character map for any font, including the Cyrillic and Japanese vector fonts. See section The plotfont Utility.

The HersheyCyrillic and HersheyCyrillic-Oblique fonts use an encoding called KOI8-R, a superset of ASCII that has become the de facto standard for Unix and networking applications in the former Soviet Union. Insofar as printable ASCII characters go, they resemble the HersheySerif vector font. But their upper halves are different. The byte range 0xc0...0xdf contains lower-case Cyrillic characters and the byte range 0xe0...0xff contains upper case Cyrillic characters. Additional Cyrillic characters are located at 0xa3 and 0xb3. For more on the encoding scheme, see the official KOI8-R Web page and Internet RFC 1489, which is available from the Information Sciences Institute.

The HersheyEUC font is a vector font that is is used for displaying Japanese text. It uses the 8-bit EUC-JP encoding. EUC stands for `extended Unix code', which is a scheme for encoding Japanese, and also other character sets (e.g., Greek and Cyrillic) as multibyte character strings. The format of EUC strings is explained in Ken Lunde's Understanding Japanese Information Processing (O'Reilly, 1993), which contains much additional information on Japanese text processing. See also his on-line supplement.

In the HersheyEUC font, characters in the printable ASCII range, 0x20...0x7e, are similar to HersheySerif (their encoding is `JIS Roman', an ASCII variant standardized by the Japanese Industrial Standards Committee). Also, each successive pair of bytes in the 0xa1...0xfe range defines a single character in the JIS X0208 standard. The characters in the JIS X0208 standard include Japanese syllabic characters (Hiragana and Katakana), ideographic characters (Kanji), Roman, Greek, and Cyrillic alphabets, punctuation marks, and miscellaneous symbols. For example, the JIS X0208 standard indexes the 83 Hiragana as 0x2421...0x2473. To obtain the EUC code for any JIS X0208 character, you would add 0x80 to each byte (i.e., `set the high bit' on each byte). So the first of the 83 Hiragana (0x2421) would be encoded as the successive pair of bytes 0xa4 and 0xa1.

The implementation of the JIS X0208 standard in the HersheyEUC font is based on Dr. Hershey's digitizations, and is complete enough to be useful. All 83 Hiragana and 86 Katakana are available, though the little-used `half-width Katakana' are not supported. Also, 603 Kanji are available, including 596 of the 2965 JIS Level 1 (i.e., frequently used) Kanji. The Hiragana, the Katakana, and the available Kanji all have the same width. The file `kanji.doc', which on most systems is installed in `/usr/share/libplot' or `/usr/local/share/libplot', lists the 603 available Kanji. Each JIS X0208 character that is unavailable will be drawn as an `undefined character' glyph (a bundle of horizontal lines).

The eight Hewlett--Packard vector fonts in the ArcANK and StickANK typefaces are also used for displaying Japanese text. They are available when producing HP-GL output for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters. To ensure that they are available, you must set the environment variable or driver parameter HPGL_VERSION to "1.5".

ANK stands for Alphabet, Numerals, and Katakana. The ANK fonts use the `Kana-8' encoding. The lower half of each font uses the JIS Roman encoding, and the upper half contains half-width Katakana. Half-width Katakana are simplified Katakana that may need to be equipped with diacritical marks. The diacritical marks are included in the encoding, as separate characters.

Available text fonts for the X Window System

The plotting utilities graph -T X, plot -T X, tek2plot -T X, pic2plot -T X, and plotfont -T X, and the libplot library that they are built on, can draw text on an X Window System display in a wide variety of fonts. This includes the 22 built-in Hershey vector fonts. They can use the 35 built-in Postscript fonts too, if those fonts are available on the X display. Most releases of the plotting utilities include freely distributable versions of the 35 Postscript fonts, in Type 1 format, that are easily installed on any X display.

In fact, the plotting utilities can use most fonts that are available on the current X display. This includes all scalable fonts that have a so-called XLFD (X Logical Font Description) name. For example, the "CharterBT-Roman" font is available on many X displays. It has a formal XLFD name, namely "-bitstream-charter-medium-r-normal--0-0-0-0-p-0-iso8859-1". The plotting utilities would refer to it as "charter-medium-r-normal". The command

echo 0 0 1 1 2 0 | graph -T X -F charter-medium-r-normal

would draw a plot in a popped-up X window, in which all axis ticks are labeled in this font.

You may determine which fonts are available on an X display by using the xlsfonts command. Fonts whose names end in "-0-0-0-0-p-0-iso8859-1" or "-0-0-0-0-m-0-iso8859-1" are scalable ISO-Latin-1 fonts that can be used by libplot's X Plotters and by the plotting utilities that are built on libplot. The two sorts of font are variable-width and fixed-width fonts, respectively. Fonts whose names end in "iso8859-2", etc., and "adobe-fontspecific", may also be used, even though they do not employ the standard ISO-Latin-1 encoding.

The escape sequences that provide access to the non-ASCII `8-bit' characters in the built-in ISO-Latin-1 fonts may be employed when using any ISO-Latin-1 X Window System font. For more on escape sequences, see section Text string format and escape sequences. As an example, "\Po" will yield the British pounds sterling symbol `@pounds{'}. The command

echo 0 0 1 1 | graph -T X -F charter-medium-r-normal -L "A \Po1 Plot"

shows how this symbol could be used in a graph label. In the same way, the escape sequences that provide access to mathematical symbols and Greek characters may be employed when using any X Window System font, whether or not it is an ISO-Latin-1 font.

The plotting utilities, including graph, support a --bitmap-size option. It is meaningful only if the `-T X' option is used, since it sets the size of the popped-up X Window. You may use it to obtain some interesting visual effects. Each of the plotting utilities assumes that it is drawing in a square region, so if you use the `--bitmap-size 800x400' option, your plot will be scaled anisotropically, by a larger factor in the horizontal direction than in the vertical direction. The fonts in the plot will be scaled in the same way. Actually, this requires a modern (X11R6) display. If your X display cannot scale a font, a default scalable font (such as "HersheySerif") will be substituted.

Text string format and escape sequences

Text strings that are drawn by libplot, and by such applications as graph, plot, tek2plot, pic2plot, and plotfont, which are built on libplot, must consist of printable characters. No embedded control characters, such as newlines or carriage returns, are allowed. Technically, a character is `printable' if it comes from either of the two byte ranges 0x20...0x7e and 0xa0...0xff. The former is the printable ASCII range and the latter is the printable `8-bit' range.

Text strings may, however, include embedded `escape sequences' that shift the font, append subscripts or superscripts, or include non-ASCII characters and mathematical symbols. As a consequence, the axis labels on a plot prepared with graph may include such features. So may the text strings that pic2plot uses to label objects.

The format of the escape sequences should look familiar to anyone who is familiar with the TeX or groff document formatters. Each escape sequence consists of three characters: a backslash and two additional characters. The most frequently used escape sequences are as follows.

"\sp"
start superscript mode
"\ep"
end superscript mode
"\sb"
start subscript mode
"\eb"
end subscript mode
"\mk"
mark location
"\rt"
return to marked location

For example, the string "x\sp2\ep" would be interpreted as `x squared'. Subscripts on subscripts, etc., are allowed. Subscripts and superscripts may be vertically aligned by judicious use of the "\mk" and "\rt" escape sequences. For example, "a\mk\sbi\eb\rt\sp2\ep" produces "a sub i squared", with the exponent `2' placed immediately above the subscript.

There are also escape sequences that switch from font to font within a typeface. For an enumeration of the fonts within each typeface, see section Available text fonts. Suppose for example that the current font is Times-Roman, which is font #1 in the `Times' typeface. The string "A \f2very\f1 well labeled axis" would be a string in which the word `very' appears in Times-Italic rather than Times-Roman. That is because Times-Italic is the #2 font in the typeface. Font-switching escape sequences are of the form "\fn", where n is the number of the font to be switched to. For compatibility with groff, "\fR", "\fI", "\fB" are equivalent to "\f1", "\f2", "\f3", respectively. "\fP" will switch the font to the previously used font (only one font is remembered). There is currently no support for switching between fonts in different typefaces.

There are also a few escape sequences for horizontal shifts, which are useful for improving horizontal alignment, such as when shifting between italic and non-italic fonts. "\r1", "\r2", "\r4", "\r6", "\r8", and "\r^" are escape sequences that shift right by 1 em, 1/2 em, 1/4 em, 1/6 em, 1/8 em, and 1/12 em, respectively. "\l1", "\l2", "\l4", "\l6", "\l8", and "\l^" are similar, but shift left instead of right. "A \fIvery\r^\fP well labeled axis" would look slightly better than "A \fIvery\fP well labeled axis".

Square roots are handled with the aid of a special pair of escape sequences, together with the "\mk" and "\rt" sequences discussed above. A square root symbol is begun with "\sr", and continued arbitrarily far to the right with the overbar (`run') escape sequence, "\rn". For example, the string "\sr\mk\rn\rn\rtab" would be plotted as `the square root of ab'. To adjust the length of the overbar, you may need to experiment with the number of times "\rn" appears.

To underline a string, you would use "\ul", the underline escape sequence, one or more times. The "\mk"..."\rt" trick would be employed in the same way. So, for example, "\mk\ul\ul\ul\rtabc" would yield an underlined "abc". To adjust the length of the underline, you may need to experiment with the number of times "\ul" appears. You may also need to use one or more of the abovementioned horizontal shifts. For example, if the "HersheySerif" font were used, "\mk\ul\ul\l8\ul\rtabc" would yield a better underline than "\mk\ul\ul\ul\rtabc".

Besides the preceding escape sequences, there are also escape sequences for the printable non-ASCII characters in each of the built-in ISO-Latin-1 fonts (which means in every built-in font, except for the symbol fonts, the HersheyCyrillic fonts, HersheyEUC, and ZapfDingbats). The useful non-ASCII characters include accented characters among others. Such `8-bit' characters, in the 0xa0...0xff byte range, may be included directly in a text string. But if your terminal does not permit this, you may use the escape sequences for them instead.

There are escape sequences for the mathematical symbols and Greek characters in the symbol fonts, as well. This is how the symbol fonts are usually accessed. Which symbol font the mathematical symbols and Greek characters are taken from depends on whether your current font is a Hershey font or a non-Hershey font. They are taken from the HersheySerifSymbol font or the HersheySansSymbol font in the former case, and from the Symbol font in the latter.

The following are the escape sequences that provide access to the non-ASCII characters of the current font, provided that it is an ISO-Latin-1 font. Each escape sequence is followed by the position of the corresponding character in the ISO-Latin-1 encoding (in decimal), and the official Postscript name of the character. Most names should be self-explanatory. For example, `eacute' is a lower-case `e', equipped with an acute accent.

"\r!"
[161] exclamdown
"\ct"
[162] cent
"\Po"
[163] sterling
"\Cs"
[164] currency
"\Ye"
[165] yen
"\bb"
[166] brokenbar
"\sc"
[167] section
"\ad"
[168] dieresis
"\co"
[169] copyright
"\Of"
[170] ordfeminine
"\Fo"
[171] guillemotleft
"\no"
[172] logicalnot
"\hy"
[173] hyphen
"\rg"
[174] registered
"\a-"
[175] macron
"\de"
[176] degree
"\+-"
[177] plusminus
"\S2"
[178] twosuperior
"\S3"
[179] threesuperior
"\aa"
[180] acute
"\*m"
[181] mu
"\ps"
[182] paragraph
"\md"
[183] periodcentered
"\ac"
[184] cedilla
"\S1"
[185] onesuperior
"\Om"
[186] ordmasculine
"\Fc"
[187] guillemotright
"\14"
[188] onequarter
"\12"
[189] onehalf
"\34"
[190] threequarters
"\r?"
[191] questiondown
"\`A"
[192] Agrave
"\'A"
[193] Aacute
"\^A"
[194] Acircumflex
"\~A"
[195] Atilde
"\:A"
[196] Adieresis
"\oA"
[197] Aring
"\AE"
[198] AE
"\,C"
[199] Ccedilla
"\`E"
[200] Egrave
"\'E"
[201] Eacute
"\^E"
[202] Ecircumflex
"\:E"
[203] Edieresis
"\`I"
[204] Igrave
"\'I"
[205] Iacute
"\^I"
[206] Icircumflex
"\:I"
[207] Idieresis
"\-D"
[208] Eth
"\~N"
[209] Ntilde
"\'O"
[210] Ograve
"\'O"
[211] Oacute
"\^O"
[212] Ocircumflex
"\~O"
[213] Otilde
"\:O"
[214] Odieresis
"\mu"
[215] multiply
"\/O"
[216] Oslash
"\`U"
[217] Ugrave
"\'U"
[218] Uacute
"\^U"
[219] Ucircumflex
"\:U"
[220] Udieresis
"\'Y"
[221] Yacute
"\TP"
[222] Thorn
"\ss"
[223] germandbls
"\`a"
[224] agrave
"\'a"
[225] aacute
"\^a"
[226] acircumflex
"\~a"
[227] atilde
"\:a"
[228] adieresis
"\oa"
[229] aring
"\ae"
[230] ae
"\,c"
[231] ccedilla
"\`e"
[232] egrave
"\'e"
[233] eacute
"\^e"
[234] ecircumflex
"\:e"
[235] edieresis
"\`i"
[236] igrave
"\'i"
[237] iacute
"\^i"
[238] icircumflex
"\:i"
[239] idieresis
"\Sd"
[240] eth
"\~n"
[241] ntilde
"\`o"
[242] ograve
"\'o"
[243] oacute
"\^o"
[244] ocircumflex
"\~o"
[245] otilde
"\:o"
[246] odieresis
"\di"
[247] divide
"\/o"
[248] oslash
"\`u"
[249] ugrave
"\'u"
[250] uacute
"\^u"
[251] ucircumflex
"\:u"
[252] udieresis
"\'y"
[253] yacute
"\Tp"
[254] thorn
"\:y"
[255] ydieresis

The following are the escape sequences that provide access to mathematical symbols and Greek characters in the current symbol font, whether HersheySerifSymbol or HersheySansSymbol (for Hershey fonts) or Symbol (for Postscript fonts). Each escape sequence is followed by the position (in octal) of the corresponding character in the symbol encoding, and the official Postscript name of the character. Many escape sequences and names should be self-explanatory. "\*a" represents a lower-case Greek alpha, for example. For a table displaying each of the characters below, see the Postscript Language Reference Manual.

"\fa"
[0042] universal
"\te"
[0044] existential
"\st"
[0047] suchthat
"\**"
[0052] asteriskmath
"\=~"
[0100] congruent
"\*A"
[0101] Alpha
"\*B"
[0102] Beta
"\*X"
[0103] Chi
"\*D"
[0104] Delta
"\*E"
[0105] Epsilon
"\*F"
[0106] Phi
"\*G"
[0107] Gamma
"\*Y"
[0110] Eta
"\*I"
[0111] Iota
"\+h"
[0112] theta1
"\*K"
[0113] Kappa
"\*L"
[0114] Lambda
"\*M"
[0115] Mu
"\*N"
[0116] Nu
"\*O"
[0117] Omicron
"\*P"
[0120] Pi
"\*H"
[0121] Theta
"\*R"
[0122] Rho
"\*S"
[0123] Sigma
"\*T"
[0124] Tau
"\*U"
[0125] Upsilon
"\ts"
[0126] sigma1
"\*W"
[0127] Omega
"\*C"
[0130] Xi
"\*Q"
[0131] Psi
"\*Z"
[0132] Zeta
"\tf"
[0134] therefore
"\pp"
[0136] perpendicular
"\ul"
[0137] underline
"\rx"
[0140] radicalex
"\*a"
[0141] alpha
"\*b"
[0142] beta
"\*x"
[0143] chi
"\*d"
[0144] delta
"\*e"
[0145] epsilon
"\*f"
[0146] phi
"\*g"
[0147] gamma
"\*y"
[0150] eta
"\*i"
[0151] iota
"\+f"
[0152] phi1
"\*k"
[0153] kappa
"\*l"
[0154] lambda
"\*m"
[0155] mu
"\*n"
[0156] nu
"\*o"
[0157] omicron
"\*p"
[0160] pi
"\*h"
[0161] theta
"\*r"
[0162] rho
"\*s"
[0163] sigma
"\*t"
[0164] tau
"\*u"
[0165] upsilon
"\+p"
[0166] omega1
"\*w"
[0167] omega
"\*c"
[0170] xi
"\*q"
[0171] psi
"\*z"
[0172] zeta
"\ap"
[0176] similar
"\+U"
[0241] Upsilon1
"\fm"
[0242] minute
"\<="
[0243] lessequal
"\f/"
[0244] fraction
"\if"
[0245] infinity
"\Fn"
[0246] florin
"\CL"
[0247] club
"\DI"
[0250] diamond
"\HE"
[0251] heart
"\SP"
[0252] spade
"\<>"
[0253] arrowboth
"\<-"
[0254] arrowleft
"\ua"
[0255] arrowup
"\->"
[0256] arrowright
"\da"
[0257] arrowdown
"\de"
[0260] degree
"\+-"
[0261] plusminus
"\sd"
[0262] second
"\>="
[0263] greaterequal
"\mu"
[0264] multiply
"\pt"
[0265] proportional
"\pd"
[0266] partialdiff
"\bu"
[0267] bullet
"\di"
[0270] divide
"\!="
[0271] notequal
"\=="
[0272] equivalence
"\~~"
[0273] approxequal
"\.."
[0274] ellipsis
NONE
[0275] arrowvertex
"\an"
[0276] arrowhorizex
"\CR"
[0277] carriagereturn
"\Ah"
[0300] aleph
"\Im"
[0301] Ifraktur
"\Re"
[0302] Rfraktur
"\wp"
[0303] weierstrass
"\c*"
[0304] circlemultiply
"\c+"
[0305] circleplus
"\es"
[0306] emptyset
"\ca"
[0307] cap
"\cu"
[0310] cup
"\SS"
[0311] superset
"\ip"
[0312] reflexsuperset
"\n<"
[0313] notsubset
"\SB"
[0314] subset
"\ib"
[0315] reflexsubset
"\mo"
[0316] element
"\nm"
[0317] notelement
"\/_"
[0320] angle
"\gr"
[0321] nabla
"\rg"
[0322] registerserif
"\co"
[0323] copyrightserif
"\tm"
[0324] trademarkserif
"\PR"
[0325] product
"\sr"
[0326] radical
"\md"
[0327] dotmath
"\no"
[0330] logicalnot
"\AN"
[0331] logicaland
"\OR"
[0332] logicalor
"\hA"
[0333] arrowdblboth
"\lA"
[0334] arrowdblleft
"\uA"
[0335] arrowdblup
"\rA"
[0336] arrowdblright
"\dA"
[0337] arrowdbldown
"\lz"
[0340] lozenge
"\la"
[0341] angleleft
"\RG"
[0342] registersans
"\CO"
[0343] copyrightsans
"\TM"
[0344] trademarksans
"\SU"
[0345] summation
NONE
[0346] parenlefttp
NONE
[0347] parenleftex
NONE
[0350] parenleftbt
"\lc"
[0351] bracketlefttp
NONE
[0352] bracketleftex
"\lf"
[0353] bracketleftbt
"\lt"
[0354] bracelefttp
"\lk"
[0355] braceleftmid
"\lb"
[0356] braceleftbt
"\bv"
[0357] braceex
"\eu"
[0360] euro
"\ra"
[0361] angleright
"\is"
[0362] integral
NONE
[0363] integraltp
NONE
[0364] integralex
NONE
[0365] integralbt
NONE
[0366] parenrighttp
NONE
[0367] parenrightex
NONE
[0370] parenrightbt
"\rc"
[0371] bracketrighttp
NONE
[0372] bracketrightex
"\rf"
[0373] bracketrightbt
"\RT"
[0374] bracerighttp
"\rk"
[0375] bracerightmid
"\rb"
[0376] bracerightbt

Finally, there are escape sequences that apply only if the current font is a Hershey font. Most of these escape sequences provide access to special symbols that belong to no font, and are accessible by no other means. These symbols are of two sorts: miscellaneous, and astronomical or zodiacal. The escape sequences for the miscellaneous symbols are as follows.

"\dd"
daggerdbl
"\dg"
dagger
"\hb"
hbar
"\li"
lineintegral
"\IB"
interbang
"\Lb"
lambdabar
"\~-"
modifiedcongruent
"\-+"
minusplus
"\||"
parallel
"\s-"
[variant form of s]

The final escape sequence in the table above, "\s-", yields a letter rather than a symbol. It is provided because in some Hershey fonts, the shape of the lower-case letter `s' differs if it is the last letter in a word. This is the case for HersheyGothicGerman. The German word "besonders", for example, should be written as "besonder\s-" if it is to be rendered correctly in this font. The same is true for the two Hershey symbol fonts, with their Greek alphabets (in Greek text, lower-case final `s' is different from lower-case non-final `s'). In Hershey fonts where there is no distinction between final and non-final `s', "s" and "\s-" are equivalent.

The escape sequences for the astronomical symbols, including the signs for the twelve constellations of the zodiac, are listed in the following table. We stress that that like the preceding miscellaneous escape sequences, they apply only if the current font is a Hershey font.

"\SO"
sun
"\ME"
mercury
"\VE"
venus
"\EA"
earth
"\MA"
mars
"\JU"
jupiter
"\SA"
saturn
"\UR"
uranus
"\NE"
neptune
"\PL"
pluto
"\LU"
moon
"\CT"
comet
"\ST"
star
"\AS"
ascendingnode
"\DE"
descendingnode
"\AR"
aries
"\TA"
taurus
"\GE"
gemini
"\CA"
cancer
"\LE"
leo
"\VI"
virgo
"\LI"
libra
"\SC"
scorpio
"\SG"
sagittarius
"\CP"
capricornus
"\AQ"
aquarius
"\PI"
pisces

The preceding miscellaneous and astronomical symbols are not the only special non-font symbols that can be used if the current font is a Hershey font. The entire library of glyphs digitized by Allen Hershey is built into GNU libplot. So text strings may include any Hershey glyph. Each of the available Hershey glyphs is identified by a four-digit number. Standard Hershey glyph #1 would be specified as "\#H0001". The standard Hershey glyphs range from "\#H0001" to "\#H3999", with a number of gaps. Some additional glyphs designed by others appear in the "\#H4000"..."\#H4194" range. Syllabic Japanese characters (Kana) are located in the "\#H4195"..."\#H4399" range.

You may order a table of nearly all the Hershey glyphs in the "\#H0001"..."\#H3999" range from the U.S. National Technical Information Service, at +1 703 487 4650. Ask for item number PB251845; the current price is about US$40. By way of example, the string

"\#H0744\#H0745\#H0001\#H0002\#H0003\#H0869\#H0907\#H2330\#H2331"

when drawn will display a shamrock, a fleur-de-lys, cartographic (small) letters A, B, C, a bell, a large circle, a treble clef, and a bass clef. Again, this assumes that the current font is a Hershey font.

You may also use Japanese syllabic characters (Hiragana and Katakana) and ideographic characters (Kanji) when drawing strings in any Hershey font. In all, 603 Kanji are available; these are the same Kanji that are available in the HersheyEUC font. The Japanese characters are indexed according to the JIS X0208 standard for Japanese typography, which represents each character by a two-byte sequence. The file `kanji.doc', which is distributed along with the GNU plotting utilities, lists the available Kanji. On most systems it is installed in `/usr/share/libplot' or `/usr/local/share/libplot'.

Each JIS X0208 character would be specified by an escape sequence which expresses this two-byte sequence as four hexadecimal digits, such as "\#J357e". Both bytes must be in the 0x21...0x7e range in order to define a JIS X0208 character. Kanji are located at "\#J3021" and above. Characters appearing elsewhere in the JIS X0208 encoding may be accessed similarly. For example, Hiragana and Katakana are located in the "\#J2421"..."\#J257e" range, and Roman characters in the "\#J2321"..."\#J237e" range. The file `kana.doc', which is installed in the same directory as `kanji.doc', lists the encodings of the Hiragana and Katakana. For more on the JIS X0208 standard, see Ken Lunde's Understanding Japanese Information Processing (O'Reilly, 1993), and his on-line supplement.

The Kanji numbering used in A. N. Nelson's Modern Reader's Japanese-English Character Dictionary, a longtime standard, is also supported. (This dictionary is published by C. E. Tuttle and Co., with ISBN 0-8048-0408-7. A revised edition [ISBN 0-8048-2036-8] appeared in 1997, but uses a different numbering.) `Nelson' escape sequences for Kanji are similar to JIS X0208 escape sequences, but use four decimal instead of four hexadecimal digits. The file `kanji.doc' gives the correspondence between the JIS numbering scheme and the Nelson numbering scheme. For example, "\#N0001" is equivalent to "\#J306c". It also gives the positions of the available Kanji in the Unicode encoding.

All available Kanji have the same width, which is the same as that of the syllabic Japanese characters (Hiragana and Katakana). Each Kanji that is not available will print as an `undefined character' glyph (a bundle of horizontal lines). The same is true for non-Kanji JIS X0208 characters that are not available.

Available marker symbols

The GNU libplot library supports a standard set of marker symbols, numbered 0 through 31. These are the symbols that the graph program will plot at each point of a dataset, if the `-S' option is used. The list is as follows (by convention, marker symbol #0 means no symbol at all).

  1. dot
  2. plus (+)
  3. asterisk (*)
  4. circle
  5. cross
  6. square
  7. triangle
  8. diamond
  9. star
  10. inverted triangle
  11. starburst
  12. fancy plus
  13. fancy cross
  14. fancy square
  15. fancy diamond
  16. filled circle
  17. filled square
  18. filled triangle
  19. filled diamond
  20. filled inverted triangle
  21. filled fancy square
  22. filled fancy diamond
  23. half filled circle
  24. half filled square
  25. half filled triangle
  26. half filled diamond
  27. half filled inverted triangle
  28. half filled fancy square
  29. half filled fancy diamond
  30. octagon
  31. filled octagon

The interpretation of marker symbols 1 through 5 is the same as in the well known GKS (Graphical Kernel System).

Symbols 32 and up are interpreted as characters in a certain text font. For libplot, it is the current font. For graph, it is the font selected with the `--symbol-font-name' option. By default, this is the ZapfDingbats font except in graph -T pnm, graph -T gif, graph -T pcl, graph -T hpgl and graph -T tek. These variants of graph normally have no access to Postscript fonts, so they use the HersheySerif font instead.

Many of the characters in the ZapfDingbats font are suitable for use as marker symbols. For example, character #74 is the Texas star. Doing

echo 0 0 1 2 2 1 3 2 4 0 | graph -T ps -m 0 -S 74 0.1 > plot.ps

will produce a Postscript plot consisting of five data points, not joined by line segments. Each data point will be marked by a Texas star, of a large font size (0.1 times the width of the plotting box).

If you are using graph -T pcl or graph -T hpgl and wish to use font characters as marker symbols, you should consider using the Wingdings font, which is available when producing PCL 5 or HP-GL/2 output. Doing

echo 0 0 1 2 2 1 3 2 4 0 |
    graph -T pcl -m 0 --symbol-font Wingdings -S 181 0.1 > plot.pcl

will produce a PCL 5 plot that is similar to the preceding Postscript plot. The Wingdings font has the Texas star in location #181.

Specifying Colors by Name

Many of the plotting utilities allow colors to be specified by name. For example, graph supports the `--frame-color' option. The other graphics programs support the `--pen-color' option, and they all, including graph support the `--bg-color' option. The libplot library, on which the graphics programs are based, includes the pencolorname, fillcolorname, and bgcolorname functions.

In any of these contexts, 665 distinct color names are recognized, including obscure ones like "dark magenta", "forest green", and "olive drab". Color names are case-insensitive, and spaces are ignored. So, for example, "RosyBrown" is equivalent to "rosy brown", and "DarkGoldenrod3" to "dark goldenrod 3".

The file `colors.txt', which is distributed along with the GNU plotting utilities, lists the available color names. On most systems it is installed in `/usr/share/libplot' or `/usr/local/share/libplot'. The color names are essentially those recognized by recent releases of the X Window System, which on most machines are listed in the file `/usr/lib/X11/rgb.txt'. However, for every color name containing the string "gray", a version containing "grey" has been included. For example, both "dark slate gray 4" and "dark slate grey 4" are recognized color names.

The Graphics Metafile Format

GNU graphics metafiles are produced by the raw variants of graph, plot, pic2plot, tek2plot, and plotfont, and by any other graphics application that uses the Metafile Plotter support contained in GNU libplot. A file in this format is a sort of audit trail: a sequence of plotting commands, each of which may be followed by data. Each plotting command is an `op code': a single ASCII character, indicating a Plotter operation. The data following the command are the arguments passed to the operation, if any.

There are two sorts of GNU graphics metafile: binary (the default) and portable (human-readable). Binary metafiles begin with the magic string "#PLOT 1\n", and portable metafiles with the magic string "#PLOT 2\n". If you wish to transfer metafiles between machines of different types, you should use portable rather than binary format. Portable metafiles are produced by GNU graph and the other plotting utilities if the `-O' option is specified, and by Metafile Plotters if the META_PORTABLE parameter is set to "yes". Both binary and portable metafiles can be translated to other formats by GNU plot.

In the portable format, the arguments of each operation (integers, floating point numbers, or strings) are printed in a human-readable form, separated by spaces, and each argument list ends with a newline. In the binary format, the arguments are represented as integers, single precision floating point numbers, or newline-terminated ASCII strings. Using the newline character as a terminator is acceptable because each libplot operation includes a maximum of one string among its arguments, and such a string may not include a newline. Also, the string must come last among the arguments.

The openpl and closepl operations open and close a Plotter, i.e., begin and end a page of graphics. They are represented by the op codes `o' and `x', respectively. The erase operation, if present, separates frames within a page. On real-time display devices, it is interpreted as a screen erasure. It is represented by the op code `e'.

Each of the 89 other Plotter operations has a corresponding op code, with 12 exceptions. These 12 exceptions are (1) the setup operation flushpl, (2) the operations havecap, labelwidth, and flabelwidth, which merely return information, (3) the colorname, pencolorname, fillcolorname, and bgcolorname operations, which are internally mapped to pencolor, fillcolor, and bgcolor, (4) the frotate, fscale, and ftranslate operations, which are internally mapped to fconcat, and (5) the ffontname operation, which in a metafile would be indistinguishable from fontname. So besides `o' and `x', there are 78 possible op codes, for a total of 80. The following table lists 10 of the op codes other than `o' and `x', followed by the name of the libplot operation they stand for.

Op Code
Operation
`a'
arc
`c'
circle
`e'
erase
`f'
linemod
`l'
line
`m'
move
`n'
cont
`p'
point
`s'
space
`t'
label

The full set of 80 op codes is listed in the header file `plot.h', which is distributed along with the plotting utilities. On most systems it is installed in `/usr/include' or `/usr/local/include'.

It is worth noting that of the 80 op codes, only 50 are used in portable metafiles. That is because in ASCII format, there is no point in distinguishing the floating point libplot operations from their integer counterparts.

The 10 op codes in the table above are actually the op codes of the traditional `plot(5)' format produced by pre-GNU versions of graph and libplot. The use of these op codes make GNU metafile format compatible with plot(5) format. The absence of a magic string, and of the `o' and `x' op codes, makes it possible to distinguish files in plot(5) format from GNU metafiles. GNU plot can convert files in plot(5) format to GNU metafiles in either binary or portable format.

Obtaining Auxiliary Software

How to get idraw

The idraw utility mentioned several times in this documentation is a freely distributable interactive drawing editor for the X Window System. It may be used to edit the output of graph -T ps, or, in general, the output of any application that uses the Postscript Plotter support contained in libplot.

The current version of idraw is maintained by Vectaport, Inc., and is available at their Web site. It is part of the ivtools package, which is a framework for building custom drawing editors. idraw was originally part of the InterViews package, developed by Stanford University and Silicon Graphics. The InterViews package is available at a distribution site but is no longer supported. Retrieving the ivtools package instead is recommended.

Also available at Vectaport's Web site is an enhanced version of idraw called drawtool. drawtool can import bitmapped graphics in TIFF and PBM/PGM/PPM formats, as well as in the X11 bitmap format that idraw can import.

How to get xfig

The xfig utility mentioned several times in this documentation is a freely distributable interactive drawing editor for the X Window System. It may be used to edit the output of graph -T fig, or, in general the output of any application that uses the Fig Plotter support contained in libplot.

The current version is available at ftp://ftp.x.org/contrib/applications/drawing_tools/. It can import graphics in GIF, X11 bitmap, and Postscript formats. Accompanying the editor is a package called transfig, which allows xfig graphics to be exported in many formats. GIF, X11 bitmap, LaTeX, and Postscript formats are supported.

There is a Web page on Fig format, which discusses application software packages that can interoperate with xfig.

Acknowledgements

Several of the GNU plotting utilities were inspired by Unix plotting utilities. A graph utility and various plot filters were present in the first releases of Unix from Bell Laboratories, going at least as far back as the Version 4 distribution (1973). The first supported display device was a Tektronix 611 storage scope. Most of the work on tying the plot filters together and breaking out device-dependent versions of libplot was performed by Lorinda Cherry. By the time of Version 7 Unix (1979) and the subsequent Berkeley releases, the package consisting of graph, plot, spline, and several device-dependent versions of libplot was a standard Unix feature. Supported devices by the early 1980's included Tektronix storage scopes, early graphics terminals, 200dpi electrostatic printer/plotters from Versatec and Varian, and pen plotters from Hewlett--Packard.

In 1989, Rich Murphey wrote the first GNU versions of graph, plot, and spline, and the earliest documentation. Richard Stallman further directed development of the programs and provided editorial support for the documentation. John Interrante, of the InterViews team at Stanford, generously provided the idraw Postscript prologue now included in libplot, and helpful comments. The package as it stood in 1991 was distributed under the name `GNU graphics'.

In 1995 Robert Maier took over development of the package, and designed and wrote the current, maximally device-independent, standalone version of libplot. He also rewrote graph from scratch, turning it into a real-time filter that would use the new library. He fleshed out spline too, by adding support for splines in tension, periodicity, and cubic Bessel interpolation.

libplot now incorporates the X Window System code for filling polygons and drawing wide polygonal lines and arcs. This code is used when producing output in bitmap formats (PNM and pseudo-GIF). It was written by Brian Kelleher, Joel McCormack, Todd Newman, Keith Packard, Robert Scheifler and Ken Whaley, who worked for Digital Equipment Corp., MIT, and/or the X Consortium, and is copyright (C) 1985--89 by the X Consortium.

The pseudo-GIF support now in libplot uses the `miGIF' run-length encoding routines developed by der Maus and ivo, which are copyright (C) 1998 by Hutchison Avenue Software Corporation. The copyright notice and permission notice for the miGIF routines are distributed with the source code distribution of the plotting utilities.

Most development work on ode was performed by Nick Tufillaro in 1978--1994, on a sequence of platforms that extended back to a PDP-11 running Version 4 Unix. In 1997 Robert modified Nick's 1994 version to agree with GNU conventions on coding and command-line parsing, extended it to support the full set of special functions supported by gnuplot, and extended the exception handling.

Many other people aided the development of the plotting utilities package along the way. The Hershey vector fonts now in libplot are of course based on the characters digitized in the mid to late 1960's by Allen V. Hershey, who deserves a vote of thanks. Additional characters and/or marker symbols were taken from the SLAC Unified Graphics System developed by Robert C. Beach in the mid-1970's, and from the fonts designed by Thomas Wolff for Ghostscript. The interpolation algorithms used in spline are based on the algorithms of Alan K. Cline, as described in his papers in the Apr. 1974 issue of Communications of the ACM. The table-driven parser used in tek2plot was written at Berkeley in the mid-1980's by Edward Moy. The `sagitta' algorithm used in an extended form in libplot for drawing circular and elliptic arcs was developed by Peter Karnow of URW and Ken Turkowski of Apple. Raymond Toy helped with the tick mark spacing code in graph and was the first to incorporate GNU getopt. Arthur Smith, formerly of LASSP at Cornell, provided code for his xplot utility. Nelson Beebe exhaustively tested the package installation process.

Robert Maier wrote the documentation, which now incorporates Nick Tufillaro's ode manual. Julie Sussmann checked over the documentation for style and clarity.

This document was generated on 20 June 1999 using the texi2html translator version 1.52.


GNU Radius Manual

Sergey Poznyakoff

Table of Contents

  • Distribution
  • GNU GENERAL PUBLIC LICENSE
    • Preamble
    • TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
    • How to Apply These Terms to Your New Programs
  • Introduction to Radius
  • Radius Glossary
  • Naming Conventions
  • How Radius Operates
    • Attributes
    • Radius Requests
      • Authentication Requests
      • Accounting Requests
    • Matching Rule
    • Processing Requests
      • Proxying
        • Proxy Service
        • Realms
      • Hints
      • Huntgroups
      • User Profiles
  • How to Start the Daemon.
  • Radius Configuration Files
    • Run-Time Configuration Options -- `raddb/config'
      • option block
      • logging block
        • category statement
        • channel statement
        • Example of the logging statement
      • auth statement
      • acct statement
      • proxy statement
      • usedbm statement
      • snmp statement
      • guile statement
      • message statement
    • Dictionary of Attributes -- `raddb/dictionary'
      • Comments
      • $INCLUDE Statement
      • VENDOR Statement
      • ATTRIBUTE statement
      • VALUE Statement
    • Clients List -- `raddb/clients'
      • Example of `clients' file
    • NAS List -- `raddb/naslist'
      • Example of `naslist' file
    • NAS Types -- `raddb/nastypes'
      • Syntax of `raddb/nastypes'
      • Example of nastypes file.
      • Standard NAS types
    • Request Processing Hints -- `raddb/hints'
      • Example of `hints' file
    • Huntgroups -- `raddb/huntgroups'
      • Example of `huntgroups' file.
    • List of Proxy Realms -- `raddb/realms'
      • Example of `realms' file
    • User Profiles -- `raddb/users'
      • Example of `users' file
    • List of Blocked Users -- `raddb/access.deny'
    • SQL Configuration -- `raddb/sqlserver'
      • SQL Client Parameters
      • Authentication Server Parameters
      • Authorization Parameters
      • Accounting Parameters
        • Writing SQL Accounting Query Templates
    • Rewrite functions -- `raddb/rewrite'
    • Login Menus -- `raddb/menus'
      • A menu file syntax.
      • An example of menu files
    • Macro Substitution
  • Authentication
    • Accept Authentication Type
    • Reject Authentication Type
    • Local Password Authentication Type
    • Encrypted Password Authentication Type
    • System Authentication Type
    • SQL Authentication Type
    • PAM Authentication Type
    • Defining Custom Authentication Types
    • Checking Simultaneous Logins
  • Accounting
    • UNIX Accounting
    • Detailed Request Accounting
    • SQL Accounting
    • Defining Custom Accounting Types.
  • Logging
  • Debugging
  • Extensions
    • Rewrite
      • Syntax Overview
      • Quick Start
      • Interaction with Radius
      • Rewriting Incoming Requests
        • Examples of Various Rewrite Functions.
      • Login Verification Functions
        • Examples of login verification functions
      • Attribute Creation Functions
      • Full Syntax Description
        • Rewrite Data Types
        • Rewrite Symbols
        • Rewrite Identifiers
        • Rewrite Declarations
        • Rewrite Statements
        • Rewrite Built-in Functions
    • Guile
      • Data Representation
      • Authentication with Scheme
      • Accounting with Scheme
      • Radius-Specific Functions
  • Utility Programs
    • Radwho
      • Radwho Command Line Options
    • Radlast
      • Radlast Command Line Options
    • Raduse
      • Display
      • Raduse Command Line Options
      • Raduse Interactive Commands
    • Radzap
    • Radgrep
    • Radping
    • Radauth
    • Radctl
    • Builddbm
    • Radscm: A guile interface to radius functions.
  • Client Package
    • Client Configuration
    • radsession
    • nas.scm
    • pam_radius.so
  • Attribute List
    • Authentication Attributes
      • User-Name
      • Password
      • CHAP-Password
      • NAS-IP-Address
      • NAS-Port-Id
      • Service-Type
      • Framed-Protocol
      • Framed-IP-Address
      • Framed-IP-Netmask
      • Framed-Routing
      • Framed-MTU
      • Framed-Compression
      • Reply-Message
      • Callback-Number
      • Callback-Id
      • Framed-Route
      • State
      • Class
      • Vendor-Specific
      • Session-Timeout
      • Idle-Timeout
      • Termination-Action
      • Called-Station-Id
      • Calling-Station-Id
      • NAS-Identifier
      • NAS-Port-Type
    • Accounting Attributes
      • Acct-Status-Type
      • Acct-Delay-Time
      • Acct-Input-Octets
      • Acct-Output-Octets
      • Acct-Session-Id
      • Acct-Authentic
      • Acct-Session-Time
      • Acct-Input-Packets
      • Acct-Output-Packets
      • Acct-Terminate-Cause
    • Radius Internal Attributes
      • Auth-Type
      • Auth-Data
      • Menu
      • Termination-Menu
      • Prefix
      • Suffix
      • Group
      • Crypt-Password
      • Huntgroup-Name
      • Simultaneous-Use
      • Strip-User-Name
      • Fall-Through
      • Add-Port-To-IP-Address
      • Exec-Program
      • Exec-Program-Wait
      • Acct-Ext-Program
      • Hint
      • Pam-Auth
      • Login-Time
      • Replace-User-Name
      • Rewrite-Function
      • Match-Profile
      • Scheme-Procedure
      • Scheme-Acct-Procedure
      • Log-Mode-Mask
      • Acct-Type
  • Reporting Bugs
  • Where to Get Info About GNU Radius
  • Program Index
  • Keyword Index
  • Examples Index
  • Index of Functions and Variables
  • Attribute Index
  • Concept Index

Distribution

GNU Radius is free software; this means that everyone is free to use it and free to redistribute it on certain conditions. GNU Radius is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of GNU Radius that they might get from you. The precise conditions are found in the GNU General Public License that comes with Radius and also appears following this section.

One way to get a copy of GNU Radius is from someone else who has it. You need not ask for our permission to do so, or tell any one else; just copy it. If you have access to the Internet, you can get the latest distribution version of GNU Radius by anonymous FTP. It is available at ftp://ftp.gnu.org/pub/gnu/gnu-radius

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

    Copyright (C) 1989, 1991 Free Software Foundation, Inc.
    675 Mass Ave, Cambridge, MA 02139, USA

    Everyone is permitted to copy and distribute verbatim copies
    of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

    one line to give the program's name and an idea of what it does.
    Copyright (C) 19yy  name of author

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License
    as published by the Free Software Foundation; either version 2
    of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19yy name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
    type `show w'.  This is free software, and you are welcome
    to redistribute it under certain conditions; type `show c'
    for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

    Yoyodyne, Inc., hereby disclaims all copyright
    interest in the program `Gnomovision'
    (which makes passes at compilers) written
    by James Hacker.

    signature of Ty Coon, 1 April 1989
    Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

Introduction to Radius

Radius is a system serving for authentication and accounting. The acronym RADIUS stands for Remote Authentication in Dial-In User Service and usually denotes the underlying protocol name.

Historically, radius servers were used as a means to authenticate the user coming from a dial-in connection, but GNU Radius is much more than an authentication system: it is an advanced, customizable and extensible system for controlling access to the network.

GNU Radius has several built-in authentication and accounting methods. When these methods are not enough, it allows administrator to implement any new method he deems convenient.

GNU Radius includes radius server program capable of serving authentication and accounting requests, and a set of accompanying programs designed to monitor the activity of the server and analyze the information it provides.

Radius Glossary

Throughout this document the following terms are used:

RADIUS
(All capitals) The Remote Authentication in Dial-In User Service protocol as described in RFC 2138, 2865 and 2866.
NAS
NAS stands for Network Access Server. It is a computer or a special device designed to provide access to the network. For example, it can be a computer connected to the network and equipped with several modems. Such NAS would allow the user connecting to one of its modems to access the network.
Service
A service, such as PPP, SLIP, telnet, etc., provided to a user by the NAS.
Session
Every single instance of a service. Session starts when the service was first provided and ends when the service is ended. A user may have multiple sessions active simultaneously if he is allowed to.
Session ID
Session Identifier. A string of characters uniquely identifying the session.
A/V pair
Stands for Attribute-Value pair section Attributes.
Dial-In or Dial-Up user
A user connecting to a service through the modem line.
User Database
A database in which Radius server keeps information about users, their authentication information, etc.
User's Profile
A record in the User Database describing a particular user. User's Profile keeps the authentication and authorization information for that user, i.e. it contains data describing how this user should be authenticated as well as which services he is allowed to be provided and parameters of these services.

Naming Conventions

This chapter describes file naming conventions used throughout this document.

Programs from the GNU Radius package use the following directories to store various configuration and log files:

Configuration or database directory
A directory where all configuration files are stored.
Log directory
A directory where radiusd stores its log files.
Accounting directory
A directory where radiusd stores accounting detail files section Detailed Request Accounting.

The default locations of these directories are determined at compile time. By default these are:

Directory | Short Name | Default location
Configuration directory | raddb | /usr/local/etc/raddb
Log directory | radlog | /var/log
Accounting directory | radacct | /var/log/radacct

These location may differ depending on your local site configuration.

Throughout this document we will refer to these directories by their short names, e.g. saying

    ... this information is contained in file `raddb/sqlserver'

we actually mean `/usr/local/etc/raddb/sqlserver'.

If necessary, locations of these directories can be overridden by specifying appropriate command line options to a program. For example, any program from the GNU Radius package accepts command line option -d or --directory, which introduces the configuration directory path.

How Radius Operates

The main purpose of Radius is to centralize authentication of users coming from various network stations. Its primary usage is for dial-in users, though it can be used for any kind of network connection.

Radius uses the Client/Server model. The main server keeps the centralized user database. Each user's profile in this database determines which services are allowed for this particular user.

The Network Access Server (NAS in short) is a machine that actually provides a service for the user. It can do so, e.g. by running a pool of modems the users can connect to. Otherwise, it can be a machine connected to the network and allowing some form of remote access, like telnet or ssh. It can even be a workstation allowing console logins to it. Whichever service it provides the NAS sends the request to the central Radius server in order to determine whether the user trying to access the service is allowed to do so. Such request carries information about user's login name, password, NAS identifier (such as its IP address), etc.

On receiving such request Radius server retrieves from its database a profile corresponding to the user's login name. The profile basically consists of two parts: a checklist used for authentication and a reply list used for authorization. The server checks the authenticity of the user using first part of the retrieved profile. If this check succeeds, it uses second part of the profile to authorize the user, i.e. to determine which service he should be provided. Then, the server responds with the parameters of the service, such as connection speed, framed IP address, etc. If any of the described checks had failed, the server sends the negative response.

If the server needs some additional information in order to process the request, it asks the NAS to supply such information. Thus, for example, if the user is allowed to use several services, he can be asked which one of them he wishes to use, etc.

When NAS receives the positive authentication response, it initiates the connection.

The NAS can be configured to notify Radius server about such events as session start, session stop or changing some parameters during the session. It can also notify the server about other events, such as NAS shutdown or startup. This is called accounting and the radius server responsible for processing this information is called an accounting server.

  • Attributes: Attributes.
  • Requests: Radius requests.
  • Matching Rule: Rules for request processing.
  • Request processing: How Radius processes incoming requests.

Attributes

The information the Radius requests carry is stored as a list of Attribute-Value pairs. Each pair consists of Attribute number and Attribute value. The Attribute number identifies the type of information the pair carries and the Attribute Value keeps the actual data.

The Value part of an attribute can contain the data of one of the following types:

Integer
A 32-bit unsigned integer value.
IP-number
An IPv4 IP-number.
String
A character string up to 253 characters long.

For convenience, the attributes and the values of some frequently used integer attributes are given symbolic names. These names are assigned to attributes and values in the dictionary file section Dictionary of Attributes -- `raddb/dictionary'.

The attribute numbers range from 1 to 255. The attributes with the numbers greater than 255 are used internally by the sever and cannot be sent to the NAS.

The special attribute 26, Vendor-Specific, is available to allow vendors of the NAS hardware or software to support their own extended attributes. section Vendor-Specific.

Each attribute has a set of properties associated with it. The properties are:

usage flags
These flags determine usage of the attribute in configuration files `huntgroups', `hints' and `users'.
propagation
When a radius server functions in proxy mode, it uses the propagation bit to determine which attributes from the reply packet should be passed back to the requesting NAS (see section Proxy Service).
additivity
Some configuration rules may cause addition of new A/V pairs to the incoming request. Before addition of a new pair, radiusd scans the request to see if it already contains a pair with the same attribute. If it does, the value of additivity determines the further actions:
None
The old pair is retained in the request, the new pair is not added to it.
Replace
The old pair is retained in the request, but its value is replaced with that of the new pair.
Append
The new pair is appended to the end of the pair list.

The attributes are declared in `raddb/dictionary' file. For a detailed description of it, See section ATTRIBUTE statement. For information about particular attributes, See section Attribute List.

Radius Requests

The term request means both the authentication/accounting request from NAS to a Radius server and the response that the server sends back to the NAS.

Each request contains the following fields

`Code '
The code field identifies the type of the request.
`Identifier '
The number in the range 0-255 used to match the request with the reply.
`Length '
The length of the request packet.
`Authenticator '
The 16-byte hash value used to authenticate the packet.
`Attributes '
The list of attribute/value pairs carrying actual information about the request.
  • Authentication Requests
  • Accounting Requests

Authentication Requests

A NAS sends authentication requests (packets with code Access-Request) to a RADIUS server when a user is trying to connect to that NAS. Such requests convey information used to determine whether a user is allowed access to the NAS, and any special services requested for that user.

An Access-Request must contain a User-Name attribute section User-Name. It should contain either a NAS-IP-Address attribute or NAS-Identifier attribute, or both of them. It also must contain either a Password attribute or CHAP-Password attribute. These attributes are passed encoded using a method based on the RSA Message Digest Algorithm MD5.

The Access-Request should contain a NAS-Port or NAS-Port-Type attribute or both unless the type of access being requested does not involve a port or the NAS does not distinguish among its ports.

Upon receiving Access-Request packet for a particular user and authenticating that user, Radius server replies to the NAS that has sent the packet with either of the following packets:

  • Access-Accept
  • Access-Reject
  • Access-Challenge

Radius replies with Access-Accept packet when it has successfully authenticated the user. Such reply packet provides specific configuration information necessary to begin delivery of service to the user.

Radius replies with Access-Reject packet when it was unable to authenticate the user. Such packet may contain a descriptive text encapsulated in one or more Reply-Message attributes. The NAS may display this text along with its response to the user.

Radius replies with Access-Challenge packet when it desires to obtain more information from the user in order to determine its authenticity or to determine the kind of service to be provided to the user.

An Access-Challenge packet may include one or more Reply-Message attributes, and may also include a single State attribute, or none. No other Attributes are permitted in an Access-Challenge.

On receipt of an Access-Challenge, the Identifier field is matched with a pending Access-Request. Additionally, the Response Authenticator field must contain the correct response for the pending Access-Request. Radius discards invalid packets and issues appropriate log message.

If the NAS does not support challenge/response, it treats an Access-Challenge as though it had received an Access-Reject instead. Otherwise, upon receipt of a valid Access-Challenge the NAS prompts the user for a response, possibly displaying the text message provided in Reply-Message attributes of the request. It then sends its original Access-Request with a new request ID and Request Authenticator, with the Password attribute replaced by the encrypted user's response, and including the State attribute from the Access-Challenge, if any.

Accounting Requests

Accounting-Request packets are sent from a NAS to a Radius server to allow for accounting of a service provided to a user.

Upon receipt of an Accounting-Request, the server attempts to record the accounting packet section Accounting, and if it succeeds in doing so it replies with an Accounting-Response packet. Otherwise it sends no reply, which then causes the NAS to retransmit its request within a preconfigured interval of time. Such retransmits will continue until either the server responds with an Accounting-Response packet or a preconfigured number of retransmits is reached, whichever occurs first.

Any attribute valid in an Access-Request or Access-Accept packet is also valid in an Accounting-Request packet, except the following attributes, which are never present in an Accounting-Request packet:

  • User-Password
  • CHAP-Password
  • Reply-Message
  • State

Either NAS-IP-Address or NAS-Identifier must be present in an Accounting-Request. It should contain a NAS-Port or NAS-Port-Type attribute or both unless the service does not involve a port or the NAS does not distinguish among its ports.

If the Accounting-Request packet includes a Framed-IP-Address, that attribute must contain the actual IP address of the user.

There are five types of accounting packets, which differ by the value of Acct-Status-Type attribute. These are:

Session Start Packet.
The session start packet is sent after the user has successfully passed the authentication and has started to receive the requested service. It must contain at least following attributes:
  • Acct-Status-Type = Start
  • User-Name
  • Acct-Session-Id
  • NAS-IP-Address
  • NAS-Port-Id
Session Stop Packet.
The Session Stop Packet is sent after the user has disconnected. It conveys the information about the duration of the session, number of octets transferred, etc. It must contain at least the following attributes:
  • Acct-Status-Type = Stop
  • User-Name
  • NAS-IP-Address
  • Acct-Session-Id
The last three of them are used to find the corresponding Session Start Packet.
Keepalive Packet
The keepalive packet is sent by the NAS when it obtains some new information about the user's session, e.g. it has determined its IP address or has changed the connection speed, etc. The packet must contain at least following attributes:
  • Acct-Status-Type = Alive
  • User-Name
  • NAS-IP-Address
  • Acct-Session-Id
Accounting Off Packet
By sending this packet NAS requests that radius mark all sessions registered from this NAS as finished. Receiving this packet usually means that the NAS is to be shut down, or is about to change its configuration in a way that requires all currently opened sessions to be shut down. The packet must contain at least the following attributes:
  • Acct-Status-Type = Accounting-Off
  • NAS-IP-Address
Accounting On Packet
By sending this packet, the NAS informs radius that it is ready to accept the incoming connections. Usually this packet is sent after startup, or after a major reconfiguration of the NAS. It must contain at least the following attributes:
  • Acct-Status-Type = Accounting-Off
  • NAS-IP-Address

Matching Rule

A record in the radius database describing a particular rule for matching an incoming request is called a Matching Rule. Each such rule defines an action to be taken when the match occurs.

The Matching Rule consists of three distinct parts:

Label
This is used to identify the rule. The special usernames DEFAULT and BEGIN are reserved. These will be described in detail below.
Left-Hand Side (LHS)
The list of attribute-value pairs used for matching the profile against an incoming request.
Right-Hand Side (RHS)
The list of attribute-value pairs that define the action to be taken if the request matches LHS.

The following radius configuration files keep data in a Matching Rule format: `hints', `huntgroups' and `users'. Although they keep data in similar format, the rules that are used to match incoming requests against contents of these files differ from file to file. The following section describes these rules in detail.

Processing Requests

Upon receiving a request Radius applies to it a number of checks to determine whether the request comes from an authorized source. If these checks succeed, the request is processed and answered. Otherwise, the request is dropped and corresponding error message is issued (see section Logging).

The following checks are performed:

Check if the username is supplied
If the packet lacks User-Name attribute it is not processed
Check if the NAS is allowed to speak
The source IP address of the machine that sent the packet is looked up in the `clients' file (see section Clients List -- `raddb/clients'). If no match is found, the request is rejected.
Compute the encryption key
Using the data from the packet and the shared key value from the `clients' file, Radius computes the MD5 encryption key that will be used to decrypt the value of the Password attribute.
Process user-name hints.
User-name hints are special rules that modify the request depending on user name and his credentials. These rules allow to divide users into distinct groups, each group having its own authentication and/or accounting methods. The user-name hints are stored in `raddb/hints' (see section Request Processing Hints -- `raddb/hints').
Process huntgroup rules.
Huntgroup rules allow to segregate incoming requests depending on the NAS and/or port number they came from. These rules are stored in `raddb/huntgroups' (see section Huntgroups -- `raddb/huntgroups').
Determine whether the request must be proxied to another radius
server The requests pertaining to another realm are immediately forwarded to the remote radius server for further processing. See section Proxying, for the description of this process.
Process individual user profiles.
This step applies only to authentication requests.
  • Proxying
  • Hints
  • Huntgroups
  • User Profiles

Proxying

Proxying is a mode of operation when a radius server forwards an incoming requests from a NAS to another radius server, waits for the latter to reply, and forwards the reply back to the requesting NAS. A common use for such operation mode is to provide roaming between several Internet Service Providers (ISPs). Roaming permits the ISPs to share their resources, allowing each other's users to connect to other party's equipment. Thus, users traveling outside the area of one ISP's coverage are still able to access their services through another ISP.

  • Proxy Service
  • Realms

Proxy Service

Suppose the ISP `Local' has a roaming arrangement with the ISP `Remote'. When the user of `Remote' dials in to the NAS of `Local', the NAS sends the authentication request to `Local' radius server. The server then determines that this is a roaming user, stores a copy of the request in its internal queue, and forwards the request to `Remote' radius server for processing. Thus, `Local' radius acts as a client for `Remote' radius. When `Remote' radius responds, the `Local' receives the response, and passes it back to the NAS. The copy of the request from the server's queue serves to determine which NAS originated the request. Before passing the request back to the NAS, radius removes from it the information, specific for `Remote' site, such as Framed-IP-Address, Framed-Netmask, etc. Only the attributes marked with `propagate' flag (see section Attributes) are passed back to the NAS. After removing site-specific attributes, `Local' radius passes the request through its user profiles (see section User Profiles) to insert any local site-specific information that might be needed. Finally, it passes the reply back to the NAS.

The accounting requests are processed in the similar manner, except that no attribute filtering takes place, as the accounting responces do not carry any A/V pairs.

This example illustrates the simplest proxy chain, consisting of only two servers. The proxy chains may consist of several servers. In our example, the `Remote' radius server may also act as a proxy and forward the request to still another radius server, etc.

Note, that when the accounting request passes through a chain of forwarding servers, the accounting records are stored on all servers in the chain.

Realms

Radius server determines which server a request must be forwarded to by request's authentication realm. There are three kinds of realms:

  1. A Named Realm is the part of a user name following the `at sign' (`@'). For example, if the user name is `jsmith@this.net', then `this.net' is the realm. The named realms can be cascaded, e.g. a request with user name `jsmith@this.net@remote.net' will first be forwarded to the radius server of realm `remote.net', which in turn will forward it to `this.net'.
  2. A Default Realm defines the server to which the requests for realms, not mentioned explicitly in the configuration, are forwarded.
  3. An Empty Realm defines the server to which the requests without explicit named realm are forwarded. If the configuration does not define the empty realm, such requests are processed by the server itself.

GNU Radius keeps the information about the realms it serves in configuration file `raddb/realms' (see section List of Proxy Realms -- `raddb/realms').

Hints

User-name hints are special rules that modify the incoming request depending on user name and his credentials. Hints are stored as a list of Matching Rules (see section Matching Rule). Upon receiving a request, radiusd scans the hints entries sequentially, comparing each rule's Label with the value of User-Name attribute from the request. If they coincide, then radiusd appends the contents of the rule's RHS to the request pair-list.

Both user names must match exactly in order for a hint to take effect, unless the hint's checklist contains either Prefix or Suffix attribute. The special name `DEFAULT' or `DEFAULT%d' (where %d denotes any decimal number), used as hint's Label match any username.

The two special attributes, Prefix and Suffix, may be used in LHS to restrict the match to a specified part of a user-name. Both are string attributes. The Prefix instructs radius to accept the hint only if the username begins with the given prefix. Similarly, Suffix instructs radius to accept the hint only if the username ends with the given suffix. A hint may contain both Prefix and Suffix attributes.

In addition to these two attributes, a hint's LHS may contain User-ID and Group attributes.

The following attributes, when used in a hint's RHS have special meaning. They are not appended to the request pair-list. Instead, they are removed after completing their function:

Fall-Through
If this attribute is present, and is set to Yes, radiusd continues scanning the hints, after processing current entry. This allows for applying several hints to a single packet.
Rewrite-Function
If this attribute is present, the specified rewrite function is invoked.
Replace-User-Name
The value of this attribute is expanded (see section Macro Substitution), and replaces the value of User-Name attribute from the request.

The hints rules are defined in `raddb/hints' file (see section Request Processing Hints -- `raddb/hints').

Huntgroups

Huntgroups are special rules, that allow to alter processing of incoming requests, depending on NAS IP address and port number they come from. The rules are stored as a list of Matching Rules (see section Matching Rule). Upon receiving a request, radiusd scans this list sequentially until it finds an entry, such that the conditions set forth in its LHS are matched by the request. If such an entry is found, radiusd verifies that the request meet the conditions described by RHS. If it does not, the request is rejected. In short, a huntgroup requires that any request matching its LHS must match also its RHS. The Label part of the rule is not used in comparisons, instead it is used to label huntgroups. All entries with the same label form a single huntgroup. The special attribute Huntgroup-Name can be used to request a match against a particular huntgroup (see section Huntgroup-Name).

The huntgroups rules are defined in `raddb/huntgroups' file (see section Huntgroups -- `raddb/huntgroups').

User Profiles

User Profiles are the per-user matching rules (see section Matching Rule). Any incoming authentication request is compared with the User Profiles after it has passed both Hints and Huntgroups. Radiusd selects from the User Profiles those rules, whose Label matches the value of User-Name attribute from the incoming request.

The selected profiles form the list of authentication rules for the request. In order for a profile to be selected, its label must either coincide literally with the User-Name value, or it must be one of special labels DEFAULT and BEGIN. The rules in the authentication list are ordered as follows: first go all the profiles with BEGIN label, they are followed by the profiles, whose labels match the User-Name literally, and, finally, these are followed by rules labeled with DEFAULT. (1) Within each of the three sub-lists the rules preserve the order in which they appear in `raddb/users' file. Once the list is constructed, it is scanned sequentially until the rule is found, whose LHS matches the incoming request. If no such rule is found, then the authentication fails. Otherwise, the contents of its RHS is appended to Reply List being constructed. If the RHS of the matched rule contains attribute Fall-Through with the value Yes, the matching continues. When the list is exhausted, the authentication result is sent back to the NAS along with the A/V pairs collected in the Reply List.

The user profiles are defined in `raddb/users' file (see section User Profiles -- `raddb/users').

How to Start the Daemon.

When started radiusd uses the configuration values from the following sources (in order of increasing precedence):

  • Compiled-in defaults
  • `raddb/config' file.
  • Command line arguments

Whenever a command line options has its equivalent in config file the use of this equivalent should be preferred (see section Run-Time Configuration Options -- `raddb/config').

The following command line options are accepted:

-A
--log-auth-detail
Enable detailed authentication logging. When this option is specified each authentication request is logged to the file `radacct/NASNAME/detail.auth', where NASNAME is replaced by the short name of the NAS from `raddb/naslist' section Naming Conventions. Config file equivalent: auth { detail yes; };.
-a DIR
--acct-directory DIR
Specify accounting directory. Config file equivalent: option { acct-dir DIR; };.
-b
--dbm
Enable DBM support. Config file equivalent: usedbm yes;.
-d DIR
--config-directory DIR
--directory D
Specify alternate configuration directory. Default is `/usr/local/etc/raddb'.
-f
--foreground
Stay in foreground. We recommend to use it for debugging purposes only.
-i IP
--ip-address
Specifies the IP address radiusd will listen on. If this option is not specified, the program will listen on all IP addresses, assigned to the machine it runs on. Config file equivalent: option { source-ip IP; };. Please note, that listen statement in `raddb/config' provides a better control over IP addresses to listen on (See section auth statement, and see section acct statement).
-L
--license
Display GNU General Public License and exit.
-l DIR
--logging-directory DIR
Specify alternate logging directory. Config file equivalent: option { log-dir DIR; };.
-mb
--mode b
"Builddbm" mode. Builds a DBM version of a plaintext users database. section Builddbm.
-mc
--mode c
Check configuration files and exit. All errors are reported via usual log channels.
-mt
--mode t
Test mode. In this mode radiusd starts an interactive interpreter which allows to test various aspects of its configuration.
-n
--auth-only
Process only authentication requests.
-p PORTNO
--port PORTNO
Listen the UDP port PORTNO. The accounting port is computed as PORTNO + 1.
-P DIR
--pid-file-dir DIR
Specifies the alternate path for the pidfile.
-S
--log-stripped-names
Log usernames stripped off any prefixes/suffixes. Config file equivalent: auth { strip-names yes };.
-s
--single-process
Run in single process mode. This is for debugging purposes only. We strongly recommend against using this option. Use it only when absolutely necessary.
-v
--version
Display program version and compilation options.
-x DEBUG_LEVEL
--debug DEBUG_LEVEL
Set debugging level. DEBUG_LEVEL is a comma-separated list of assignments in the forms
    MODULE
    MODULE = LEVEL
where MODULE is the module name or any non-ambiguous assignment thereof, LEVEL is the debugging level in the range 0-100. section Debugging Config file equivalent:
    logging {
            category debug {
                    level DEBUG_LEVEL;
            };
    };
-y
--log-auth
Log authentications. With this option enabled, Radius will log any authentication attempt into its logfile section Logging. Config file equivalent: logging { category auth { detail yes; }; }; .
-z
--log-auth-pass
Log passwords along with authentication information. Do not use this option. It is very insecure, since all users' passwords will be echoed in the logfile. This option is provided only for debugging purposes. Config file equivalent:
    logging {
            category auth {
                    print-pass yes;
            };
    };

See section Run-Time Configuration Options -- `raddb/config'.

Radius Configuration Files

This chapter describes the configuration files used by GNU Radius package.

These files are normally found in /usr/local/etc/raddb directory, which is defined at configuration time, although their location can be specified at runtime. In the discussion below we will refer to this directory by `raddb'. See section Naming Conventions.

  • config file: Run-time configuration options.
  • dictionary file: Radius dictionary.
  • clients file: Clients lists the NASes that are allowed to communicate with radius.
  • naslist file: The naslist file keeps general information about the NASes.
  • nastypes file: Information about how to query the NASes about active user sessions.
  • hints file: Important user information that is common for the users whose names match some pattern.
  • huntgroups file: Group users by the NAS (and, possibly, a port number) they come from.
  • realms file: Communication with remote radius servers
  • users file: User profile.
  • access.deny file: List of users which are denied access.
  • sqlserver file: SQL server configuration.
  • rewrite file: Rewrite functions allow to change the input packets.
  • menus file: Menus allow user to select the type of service.
  • Macro Substitution: Macros which are expanded by the actual attribute values.

Run-Time Configuration Options -- `raddb/config'

radiusd uses the configuration values from the following sources (in order of increasing precedence):

  1. Compiled-in defaults
  2. `raddb/config' file.
  3. Command line arguments

This order of precedence applies only on startup. When re-reading of the configuration is initiated either by SIGHUP signal or by SNMP channel any changes in the config file take precedence over command line arguments, since `raddb/config' is the only way to change configuration of the running program.

This chapter discusses the `raddb/config' file in detail.

The `raddb/config' consists of statements and comments. Statements end with a semicolon. Many statements contain a block of sub-statements which also terminate with a semicolon.

Comments can be written in shell, C, or C++ constructs, i.e. any of the following represent a valid comment:

    # A shell comment
    /* A C-style
     * multi-line comment
     */
    // A C++-style comment

These are the basic statements:

  • option: Option block: set the global program options.
  • logging: Fine-tune the logging.
  • auth: Configure authentication service.
  • acct: Configure accounting service.
  • proxy: Configure proxy service.
  • usedbm: Enable the DBM feature.
  • snmp: Configure SNMP service.
  • guile: Configure Guile interface.
  • message: Configure server reply messages.

option block

Syntax:

    option {
            [ source-ip number ; ]
            [ max-requests number ; ]
            [ exec-program-user string ; ]
            [ username-chars string ; ]
            [ log-dir string ; ]
            [ acct-dir string ; ]
    } ;

Usage

The option block defines the global options to be used by radiusd.

Numeric statements

source-ip
Sets the source IP address. When this statement is not present, the IP address of the first available network interface on the machine will be used as source.
max-requests
Sets the maximum number of the requests in queue.

String statements

exec-program-user
Sets effective user id for the programs executed as a result of Exec-Program and Exec-Program-Wait. The effective group id will be retrieved from the `/etc/passwd' entry for the given user.
username-chars
Determines characters that are valid within a username. The alphanumeric characters are always allowed in a username, it is not necessary to specify them in this statement. By default the following characters are allowed in a username: `.-_!@#$%^&\/"'.
log-dir
Specifies the logging directory.
acct-dir
Specifies the accounting directory.

logging block

Syntax:

    logging {
            [ category category_spec {
                    [ channel channel_name ; ]
                    [ print-auth bool ; ]
                    [ print-pass bool ; ]
                    [ print-failed-pass bool ; ]
                    [ level debug_level ; ]
            } ; ]
            [ channel channel_name {
                   (  file string ;
                    | syslog facility . priority ; )
                    [ print-pid bool ; ]
                    [ print-category bool ; ]
                    [ print-cons bool ; ]
                    [ print-level bool ; ]
                    [ print-priority bool ; ]
            }; ]
    } ;

Usage

The logging statement describes the course followed by radiusd's logging information.

  • category: category statement.
  • channel: channel statement.
  • logging example: Example of the logging statement.

category statement

Each line of logging information generated by radiusd has an associated category. The logging statement allows each category of output to be controlled independently of the others. The logging category is defined by category name and a severity. category name determines what part of radiusd daemon is allowed to send its logging information to this channel. It can be any of main, auth, acct, proxy, snmp. priority determines the minimum priority of the messages displayed by this channel. The priorities in ascending order are: debug, info, notice, warn, err, crit, alert, emerg.

The full category specification, category_spec, can take any of the following three forms:

category_name
Print the messages of given category.
priority
Print messages of all categories, abridged by given priority. If the priority is prefixed with `=', only messages with given priority will be displayed. If it is prefixed with `!', the messages with priority other than the specified will be displayed. Otherwise, the messages with priorities equal to or greater than the specified will be displayed.
category_name . priority
Print the messages of given category, abridged by given priority. The priority may be prefixed with either `=' or `!' as described above.

Additional category options valid for auth category are:

print-auth
Log individual authentications.
print-pass
Include passwords for successful authentications. It is very insecure, since all users' passwords will be echoed in the logfile. This option is provided only for debugging purposes.
print-failed-pass
Include passwords for failed authentications.

channel statement

Channels represent methods for recording logging information. Each channel has a unique name, and any categories which specify that name in a channel statement will use that channel.

radiusd can write logging information to files or send it to syslog. The file statement sends the channel's output to the named file (see section Naming Conventions). The syslog statement sends the channel's output to syslog with the specified facility and severity.

Channel options modify the data flowing through the channel:

print-pid
Add the process ID of the process generating the logging information.
print-cons
Also send the logging information to the system console.
print-category
Add the category name to the logging information.
print-priority
print-level
Add the priority name to the logging information.

Example of the logging statement

    logging {
            channel default {
                    file "radius.log";
                    print-category yes;
                    print-priority yes;
            };
            channel info {
                    file "radius.info";
                    print-pid yes;
                    print-cons yes;
                    print-priority yes;
            };
            channel notice {
                    syslog auth.notice;
            };

            category auth {
                    print-auth yes;
                    print-failed-pass yes;
            };
            category notice {
                    channel notice;
            };
            category info {
                    channel info;
            };
            category debug {
                    channel info;
                    level radiusd=1,files;
            };

            category *.!debug {
                    channel default;
            };
    };

auth statement

Syntax:

    auth {
            [ listen addr-list ; ]
            [ port number ; ]
            [ spawn bool ; ]
            [ max-requests number ; ]
            [ time-to-live number ; ]
            [ request-cleanup-delay number ; ]
            [ detail bool ; ]
            [ strip-names bool ; ]
            [ checkrad-assume-logged bool ; ]
            [ password-expire-warning number ; ]
    } ;

Usage:

The auth statement configures the parameters of the authentication service.

listen statement

This statement determines on which addresses radiusd will listen for incoming authentication requests. Its argument is a comma-separated list of items in the form ip:port-number. ip can be either an IP address in familiar "dotted-quad" notation or a hostname. :port-number part may be omitted, in which case the default authentication port is assumed.

If the listen statement is omitted, radiusd will accept incoming requests from any interface on the machine.

Numeric statements

port
Sets the number of UDP port to listen on for the authentication requests.
max-requests
Sets the maximum number of authentication requests in the queue. Any surplus requests will be discarded.
time-to-live
Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.
request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will the completed authentication request reside in the queue.
password-expire-warning
Sets the time interval for password expiration warning. If user's password expires within given number of seconds, radiusd will send a warning along with authentication-acknowledge response. Default is 0.

Boolean statements

spawn
Determines if radiusd should spawn a child to process the request.
detail
When set to true, radiusd will produce the detailed log of each received packet in the file `radacct/NASNAME/detail.auth'. (see section Naming Conventions).
strip-names
Determines whether radiusd should strip any prefixes/suffixes off the username before logging.
checkrad-assume-logged
radiusd consults the value of this variable when the NAS does not responds to checkrad queries (see section Checking Simultaneous Logins). If this variable is set to yes, the daemon will proceed as if the NAS returned "yes", i.e. it will assume the user is logged in. Otherwise radiusd assumes the user is not logged in.

acct statement

Syntax:

    acct {
            [ listen addr-list ; ]
            [ port number ; ]
            [ spawn bool ; ]
            [ detail bool; ]
            [ max-requests number ; ]
            [ time-to-live number ; ]
            [ request-cleanup-delay number ; ]
    } ;

Usage:

The acct statement configures the parameters of the accounting service.

listen statement

This statement determines on which addresses radiusd will listen for incoming accounting requests. Its argument is a comma-separated list of items in the form ip:port-number. ip can be either an IP address in familiar "dotted-quad" notation or a hostname. :port-number part may be omitted, in which case the default accounting port is assumed.

If the listen statement is omitted, radiusd will accept incoming requests from any interface on the machine.

Numeric statements

port
Sets the port number to listen for the authentication requests.
max-requests
Sets the maximum number of accounting requests in the queue. Any surplus requests will be discarded.
time-to-live
Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.
request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will the completed account request reside in the queue.

Boolean statements

spawn
Determines if radiusd should spawn a child to process the request.
detail
When set to false, disables detailed accounting (see section Detailed Request Accounting).

proxy statement

Syntax:

    proxy {
            [ max-requests number ; ]
            [ request-cleanup-delay number ; ]
    } ;

Usage:

The proxy statement configures the parameters of the proxy service.

Numeric statements

max-requests
Sets the maximum number of accounting requests in the queue. Any surplus requests will be discarded.
request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will the completed account request reside in the queue.

usedbm statement

Syntax:

    usedbm ( yes | no ) ;

Usage

The usedbm statement determines whether the DBM support should be enabled.

no
Do not use DBM support at all.
yes
Use only the DBM database and ignore `raddb/users'.

snmp statement

Syntax:

    snmp {
            [ port portno ; ]
            [ spawn bool ; ]
            [ max-requests number ; ]
            [ time-to-live number ; ]
            [ request-cleanup-delay number ; ]
            [ ident string ; ]
            [ community name ( rw | ro ) ; ]
            [ network name network [ network ... ] ; ]
            [ acl {
                    [ allow network_name community_name ; ]
                    [ deny network_name ; ]
            } ; ]
    };

Usage

The snmp statement configures the SNMP service.

Numeric statements

port
Sets the port number to listen for the SNMP requests.
max-requests
Sets the maximum number of SNMP requests in the queue. Any surplus requests will be discarded.
time-to-live
Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.
request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will the completed SNMP request reside in the queue.

Boolean statements

spawn
Determines if radiusd should spawn a child to process the SNMP request.

String statements

ident
Sets the SNMP server identification string.

Community and network definitions

community name ( rw | ro )
Defines the community name as read-write (rw) or read-only (ro).
network name network [ network ... ]
Groups several networks or hosts under one logical network name.

Access-Control List definitions

allow network_name community_name
allow hosts from the group network_name access to community community_name.
deny NETWORK_NAME
Deny access to SNMP service from any host in the group network_name.

guile statement

The guile statement allows to configure server interface with Guile.

Syntax

    guile {
            [ debug bool ; ]
            [ load-path string ; ]
            [ load string ; ]
    };

Usage

Boolean statements

debug
When set to yes, enables debugging evaluator and backtraces on Guile scripts.

String statements

load-path
Add specified pathname to %load-path variable.
load
Load the specified source file on startup.

For the detailed description of Guile extensions interface, See section Guile.

message statement

The message statement allows to set up the messages that are returned to the user with authentication-response packets.

Syntax

    message {
            [ account-closed string ; ]
            [ password-expired string ; ]
            [ password-expire-warning string ; ]
            [ access-denied string ; ]
            [ realm-quota string ; ]
            [ multiple-login string ; ]
            [ second-login string ; ]
            [ timespan-violation string ; ]
    };

All variables in message block take a string argument. In string you can use the usual C backslash notation to represent non-printable characters. The use of %C{} and %R{} sequences is also allowed (see section Macro Substitution).

String statements

account-closed
This message will be returned to the user whose account is administratively closed.
password-expired
This message will be returned to the user whose password has expired.
password-expire-warning
This is a warning message that will be returned along with an authentication-acknowledge packet for the user whose password will expire in less than n seconds. The value of n is set by password-expire-warning variable in auth block. See section auth statement. In this string, you can use the %R{Password-Expire-Days} substitution, to represent the actual number of days left to the expiration date. The default is
    Password Will Expire in %R{Password-Expire-Days} Days\r\n
access-denied
This message is returned to the user who supplies an incorrect password or a not-existent user-name as his authentication credentials.
realm-quota
This message is returned when the user is trying to log in using a realm, and number of users that are currently logged in from this realm reaches maximum value. For a description of realms, See section Realms.
multiple-login
This message is returned to the user, who has logged in more than allowed number of times. For description of how to set the maximum number of concurrent logins, see section Simultaneous-Use.
second-login
This is a special case of multiple-login, which is used when the user's login limit is 1.
timespan-violation
This message is returned to the user who is trying to login outside of allowed time interval. For description of how to limit user's login time, see section Login-Time.

Dictionary of Attributes -- `raddb/dictionary'

The dictionary file `raddb/dictionary' defines the symbolic names for radius attributes and their values (see section Attributes). The file consists of a series of statements. Each statement occupies one line.

In the detailed discussion below we use the following meta-syntactic characters:

number
Denotes a decimal, octal or hexagesimal number. Usual C conventions are honored, i.e. if number starts with `0x' or `0X' it is read as a hex number, if it starts with `0' it is read as an octal number, otherwise it is read as a decimal one.
type
Denotes an attribute type. These are valid attribute types:
string
A string type.
integer
An integer type.
ipaddr
IP address in a dotted-quad form.
date
A date in the format: "MON DD CCYY", where MON is the usual three-character abbreviation, DD is day of month (1-31), CCYY is the year, including the century.

There are following kinds of statements:

  • Comment: Introducing a comment line.
  • $INCLUDE: Include a file.
  • VENDOR: Define a vendor-id.
  • ATTRIBUTE: Define an attribute translation.
  • VALUE: Define a value translation.

Comments

Comments are introduced by a pound sign (`#'). Everything starting from the first occurrence of `#' up to the end of line is ignored.

$INCLUDE Statement

Syntax

    $INCLUDE `filename'

Usage

The $INCLUDE statement causes the contents of the file `filename' to be read in and processed. The file is looked up in the Radius database directory. See section Radius Configuration Files.

VENDOR Statement

Syntax

    VENDOR  Vendor-Name     number

Usage

A VENDOR statement defines the symbolic name for a Vendor-Id. This name can subsequently be used in ATTRIBUTE statements to define Vendor-Specific attribute translations. See section Vendor-Specific.

Example

    VENDOR          Livingston      307

ATTRIBUTE statement

Syntax

    ATTRIBUTE  name  number  type [vendor [flags]]

Usage

The ATTRIBUTE statement defines the translation for an attribute. Its parts have the following meaning:

name
The attribute name.
number
The attribute ID (number).
type
The attribute type.
vendor
Vendor name for vendor-specific attributes. For usual attributes this field is empty or contains a dash (`-').
flags
Flags, defining attribute properties (see section Attributes).

The attribute property flags consist of a sequence of letters, whose meaning is determined by the following rules: (2)

  1. The attribute usage is described by three pairs of symbols, enclosed in square brackets. Each pair describes how the attribute can be used in each of three configuration files. The first pair corresponds to `raddb/users', the second one corresponds to `raddb/hints', and the third one corresponds to `raddb/huntgroups'. Within each pair, the letter `L' in first position means that the attribute is allowed in LHS of a rule. The letter `R' in second position means that the attribute is allowed in RHS of a rule. The absense of any of these letters is indicated by dash (`-'). Thus, the following usage specification:
                [L--RLR]
    means that the attribute may be used in LHS of a rule in `raddb/users', in RHS of a rule in `raddb/hints', and in both sides of a rule in `raddb/huntgroups'.
  2. The attribute additivity is described by one of the following letters:
    =
    Additivity = Replace
    +
    Additivity = Append
    N
    Additivity = None
  3. The presence of letter `P' in property flags raises the propagation bit.

Example

    ATTRIBUTE  Service-Type  6 integer - [LR-RLR]=P

This statement assigns the translation string `Service-Type' to the attribute number 6. It allows the use of this attribute in any part of matching rules, except in LHS of a `raddb/hints' rule. The additivity of Service-Type is set to `Replace'. The attribute will be propagated through the proxy chain.

VALUE Statement

Syntax

    VALUE   Attribute-Translation       Value-Translation       number

Usage

The VALUE statement assigns a translation string to a given value of an integer attribute. Attribute-Translation specifies the attribute and the Value-Translation specifies the name assigned to the value number of this attribute.

Example

The following assigns the translation string `Login-User' to the value 1 of the attribute `Service-Type'.

    VALUE           Service-Type            Login-User              1

Clients List -- `raddb/clients'

The `raddb/clients' lists NASes which are allowed to make authentication requests. As usual, the `#' character introduces a comment. Each record in the file consists of two fields, separated by whitespace. The fields are:

NAS name
Specifies a hostname or IP address of the NAS.
Key
Lists the encryption key shared between the server and this NAS.
  • Example: An example of clients file.

Example of `clients' file

    # This is a list of clients which are allowed to make authentication
    # requests.
    # Each record consists of two fields:
    #       i.  Valid hostname.
    #       ii. The shared encryption key for this hostname.
    #
    #Client Name            Key
    #----------------       -------------------
    myhost.dom.ain          guessme
    merlin                  emrys
    11.10.10.10             secRet

NAS List -- `raddb/naslist'

The `raddb/naslist' file contains a list of NASes known to the Radius server. Each record in the file consist of three fields:

NAS name
Specifies a hostname or IP address of the NAS. The word `DEFAULT' may be used in this field to match any NAS. (3)
Short Name
This field defines a short name under which this NAS will be listed in logfiles. The short name is also used as a name of the subdirectory where the detailed logs are stored.
Type
Specifies the type of this NAS. Using this value radiusd determines the way to query NAS about the presence of a given user on it (see section Checking Simultaneous Logins). The two special types: `true' and `false', can be used to disable NAS querying. When the type field contains `true', radiusd assumes the user is logged in to the NAS, when it contains `false', radiusd assumes the user is not logged in. Otherwise, the type is used as a link to `nastypes' entry (see section NAS Types -- `raddb/nastypes').
Arguments
Additional arguments describing the NAS. Multiple arguments must be separated by commas. No intervening whitespace is allowed in this field.

There are two groups of nas arguments: nas-specific arguments and nas-querying arguments. Nas-specific arguments are used to modify a behavior of radiusd when sending or receiving the information to or from a particular NAS.

Nas-querying arguments control the way radiusd queries a NAS for confirmation of a user's session (see section Checking Simultaneous Logins). These arguments override the ones specified in `nastypes' and can thus be used to override the default values.

The nas-specific arguments currently implemented are:

broken_pass
This is a boolean argument that controls the encryption of user passwords, longer than 16 octets. By default, radiusd uses method specified by RFC 2865. However some NASes, most notably MAX Ascend series, implement a broken method of encoding long passwords. This flag instructs radiusd to use broken method of password encryption for the given NAS.

For the list of nas-querying arguments, See section NAS Types -- `raddb/nastypes'.

  • Example: Example of `naslist' file.

Example of `naslist' file

    # raddb/naslist: contains a list of Network Access Servers
    #
    # Each record consists of following fields:
    #
    #       i.      A valid hostname or IP address for the client.
    #       ii.     The short name to use in the logfiles for this NAS.
    #       iii.    Type of device. Valid values are `true', `false' and
    #               those defined in raddb/nastypes file.

    # NAS Name              Short Name      Type
    #----------------       ----------      ----
    myhost.dom.ain          myhost          unix
    merlin                  merlin          max
    11.10.10.10             arthur          livingston

NAS Types -- `raddb/nastypes'

The `raddb/nastypes' file describes the ways to query NASes about active user sessions.

  • Syntax: Syntax described.
  • Example: Example of nastypes file.
  • Predefined NAS Types: NAS types defined in standard nastypes file.

Syntax of `raddb/nastypes'

Syntax

Each record consists of three fields separated by any amount of whitespace. The fields are:

Type
Type of the NAS which is described in this record.
Method
Method to use to query a NAS of given type.
Arguments
Arguments to pass to this method. Each argument is a pair arg=value, where arg is its name and value is a value assigned to it. The list of predefined argument names follows. Please note, that no intervening whitespace is allowed in this field.

Methods

Version 0.96 of GNU Radius supports two querying methods: finger and snmp.

Arguments

In the discussion below n means numeric and s string value.

The following arguments are predefined:

Common for all methods

function=s
Specifies the check function to use with this method (see section Login Verification Functions). This argument must be present. For description of how this function is applied, see section Checking Simultaneous Logins.
port=n
Use port number n instead of the default for the given method.

Method snmp

password=s
Use community s instead of the default. This argument must be present.
retries=n
Retry n times before giving up.
timeout=n
Timeout n seconds on each retry.

Method finger

timeout=n
Give up if the NAS does not respond within n seconds.
notcp
tcp=0
Disable the use of T/TCP for hosts with a broken TCP implementation.
arg=subst
Send subst to finger, instead of username. subst must be one of macro variables, described below.

Macro variables

The following macro-variables are recognized and substituted when encountered in the value pair of an argument:

`%u '
Expands to username.
`%s '
Expands to session id.
`%d '
Expands to session id converted to decimal representation.
`%p '
Expands to port number.
`%P '
Expands to port number + 1.

Example of nastypes file.

Please note, that in the following example the long lines are broken into several lines for readability.

    # Type     Method          Args
    # ----     ------          ----
    unix       finger       function=check_unix
    max-f      finger       function=check_max_finger
    max        snmp         oid=.1.3.6.1.4.1.529.12.3.1.4.%d,
                            function=check_snmp_u
    as5300-f   finger       function=check_as5300_finger
    as5300     snmp         oid=.1.3.6.1.4.1.9.9.150.1.1.3.1.2.%d,
                            function=check_snmp_u
    livingston snmp         oid=.1.3.6.1.4.1.307.3.2.1.1.1.5.%P,
                            function=check_snmp_s

Standard NAS types

The `nastypes' shipped with version 0.96 of GNU Radius defines following NAS types:

unix -- UNIX boxes running Finger
This type suits for UNIX boxes running finger service able to return information about dial-up users active on them. To enable finger checking of a unix host add following to your `naslist' file:
    #Hostname       Shortname   Type
    #--------       ---------   ----
    nas.name        T           unix
max-f -- MAX Ascend with Finger
Use this type if you have MAX Ascend terminal server that answers finger queries. The `naslist' entry for such NAS will look like:
    #Hostname       Shortname   Type  Flags
    #--------       ---------   ----  -----
    nas.name        T           max-f broken_pass
Please note the use of broken_pass flag. It is needed for most MAX Ascend servers (see section NAS List -- `raddb/naslist').
max -- MAX Ascend, answering SNMP
Use this type if you have MAX Ascend terminal server that answers SNMP queries. The `naslist' entry for such NAS will look like:
    #Hostname       Shortname   Type  Flags
    #--------       ---------   ----  -----
    nas.name        T           max-f broken_pass,community=comm
Replace comm with your actual SNMP community name.
as5300-f -- Cisco AS5300 running finger
as5300 -- Cisco AS5300 answering SNMP
livingston -- Livingston Portmaster
Type livingston queries portmaster using SNMP.

Request Processing Hints -- `raddb/hints'

The `raddb/hints' file is used to modify the contents of the incoming request depending on the username. For a detailed description of this, See section Hints.

The file contains data in Matching Rule format (see section Matching Rule).

The only attributes that can be used in the check list are:

  • Suffix
  • Prefix
  • Group
  • User-ID
  • Example: An example of `hints' file.

Example of `hints' file

    ## If the username starts with `U', append the UUCP hint
    DEFAULT         Prefix = "U", Strip-User-Name = No
                    Hint = "UUCP"
    ## If the username ends with `.slip', append the SLIP service data
    ## and remove the suffix from the user name.
    DEFAULT         Suffix = ".slip",
                       Strip-User-Name = Yes
                    Hint = "SLIP",
                       Service-Type = Framed-User,
                       Framed-Protocol = SLIP

Huntgroups -- `raddb/huntgroups'

The `raddb/huntgroups' contains the definitions of the huntgroups. For a detailed description of huntgroup concept, See section Huntgroups.

The file contains data in Matching Rule format (see section Matching Rule).

  • Example: An example of the `huntgroups' file.

Example of `huntgroups' file.

    ## This defines the packet rewriting function for the server 11.10.10.11
    DEFAULT NAS-IP-Address = 11.10.10.11, Rewrite-Function = "max_fixup"
            NULL

List of Proxy Realms -- `raddb/realms'

The `raddb/realms' file lists remote Radius servers that are allowed to communicate with the local Radius server (see section Proxying).

Each record consists of up to three fields, separated by whitespace. Two of them are mandatory. The fields are:

Realm name
Specifies the name of the realm being defined, i.e. part of the login name after the `@' symbol. The special realm name `NOREALM' defines the empty realm, the name `DEFAULT' defines the default realm (see section Realms).
Remote server
Specifies the remote server to which the requests for this realm should be forwarded. The syntax for this field is
    servername[:auth-port[:acct-port]]
Optional auth-port and acct-port are the authentication and accounting port numbers. If acct-port is omitted, it is computed as auth-port + 1. If auth-port is omitted, the default authentication port number is used.
Flags (optional)

The flags meaningful in `raddb/realms' are

strip
Boolean value. Controls whether the realm name should be stripped off the username before forwarding the request to the remote server. Setting strip enables stripping, setting nostrip disables it. Default is to always strip user names.
quota=num
Set maximum number of concurrent logins allowed from this realm to the given value (num).
  • Example: An example of `realms' file.

Example of `realms' file

Example 1.

    # Realm                 Remote server[:port]            flags
    #----------------       ---------------------           --------
    that.net                radius.that.net                 nostrip
    dom.ain                 server.dom.ain:3000             strip,quota=20

Example 2.

    # Realm                 Remote server[:port]            flags
    #----------------       ---------------------           --------
    NOREALM                 radius.server.net
    that.net                radius.that.net                 nostrip
    dom.ain                 server.dom.ain:3000             strip,quota=20

User Profiles -- `raddb/users'

File `raddb/users' contains the list of User Profiles. For a description of its purpose, See section User Profiles.

  • Example: An example of `users' file.

Example of `users' file

    ## The following entry is matched when the user appends ``.ppp'' to his
    ## username when logging in.
    ## The suffix is removed from the user name, then the password is
    ## looked up in the SQL database.
    ## Users may log in at any time. They get PPP service.
    DEFAULT Suffix = ".ppp",
                    Auth-Type = SQL,
                    Login-Time = "Al",
                    Simultaneous-Use = 1,
                    Strip-User-Name = Yes
            Service-Type = Framed-User,
                    Framed-Protocol = PPP

    ## This is for SLIP users.
    ## This entry is matched when the auth request matches ``SLIP'' hint
    DEFAULT Hint = "SLIP",
                    Auth-Type = Mysql
            Service-Type = Framed-User
                    Framed-Protocol = SLIP

    ## The following authenticates users using system passwd files.
    ## The users are allowed to log in from 7:55 to 23:05 on any weekday,
    ## except the weekend, and from 07:55 to 12:00 on Sunday.
    ## Only one login is allowed per user.
    ## The program telauth is used to further check the authentication
    ## information and provide the reply pairs
    ## Note the use of backslashes to split a long line.
    DEFAULT Auth-Type = System,
                    Login-Time = "Wk0755-2305,Su0755-1200",
                    Simultaneous-Use = 1
            Exec-Program-Wait = "/usr/local/sbin/telauth \
                                 %C{User-Name} \
                                 %C{Calling-Station-Id} \
                                 %C{NAS-IP-Address} \
                                 %C{NAS-Port-Id}"

    ## This particular user is authenticated via PAM. He is presented a
    ## choice from `raddb/menus/menu1' file.
    gray    Auth-Type = Pam
            Menu = menu1

List of Blocked Users -- `raddb/access.deny'

The `raddb/access.deny' file contains a list of user names which are not allowed to log in via Radius. Each user name is listed on a separate line. As usual, the `#' character introduces an end-of-line comment.

SQL Configuration -- `raddb/sqlserver'

The `raddb/sqlserver' file configures the connection to SQL server.

The file uses simple line-oriented `keyword -- value' format. Comments are introduced by `#' character.

The `sqlserver' statements can logically be subdivided into following groups: SQL Client Parameters, configuring the connection between SQL client and the server, Authentication Server Parameters, Authorization Parameters, and Accounting server parameters.

  • SQL Client Parameters
  • Authentication Server Parameters
  • Authorization Parameters
  • Accounting server parameters

SQL Client Parameters

These parameters configure various aspects of connection between SQL client and the server.

interface iface-type
Specifies the SQL interface to use. Currently supported values for iface-type are mysql and postgres. Depending on this, the default communication port number is set: it is 3306 for interface mysql and 5432 for interface postgres. Use of this statement is only meaningful when the package was configured with both --with-mysql and --with-postgres option.
server string
Specifies the hostname or IP address of the SQL server.
port number
Sets the SQL communicaton port number. It can be omitted if your server uses the default port.
login string
Sets the SQL user login name.
password password
Sets the SQL user password.
keepopen bool
Specify whether radiusd should try to keep the connection open. When set to no (the default), radiusd will open new connection before the transaction and close it right after finishing it. We recommend setting keepopen to yes for heavily loaded servers, since opening the new connection can take a substantial amount of time and slow down the operation considerably.
idle_timeout number
Set idle timeout in seconds for an open SQL connection. The connection is closed if it remains inactive longer that this amount of time.

Authentication Server Parameters

These parameters configure the SQL authentication. The general syntax is:

doauth bool
When set to yes, enables authentication via SQL. All auth_ keywords are ignored if doauth is set to no.
auth_max_connections bool
Specifies the maximum number of authentication SQL connections to keep open. This parameter is ignored if keepopen is set to no.
auth_db string
Specifies the name of the database containing authentication information.
auth_query string
Specifies the SQL query to be used to obtain user's password from the database. The query should return exactly one string value -- the password.
group_query string
Specifies the query that retrieves the list of user groups the user belongs to. This query is used when Group or Group-Name attribute appears in the LHS of a user's or hint's profile.

Example of Authentication Server Parameters

Let's suppose the authentication information is kept in the tables passwd and groups.

The passwd table contains user passwords. A user is allowed to have different passwords for different services. The table structure is:

    CREATE TABLE passwd (
      user_name           varchar(32) binary default '' not null,
      service             char(16) default 'Framed-PPP' not null,
      password            char(64)
    );

Additionally, the table groups contains information about user groups a particular user belongs to. Its structure is:

    CREATE TABLE groups (
      user_name           char(32) binary default '' not null,
      user_group          char(32)
    );

The queries used to retrieve the information from these tables will then look like:

    auth_query  SELECT password
                FROM passwd
                WHERE user_name = '%C{User-Name}'
                AND service = '%C{Auth-Data}'

    group_query SELECT user_group
                FROM groups
                WHERE user_name = '%C{User-Name}'

It is supposed, that the information about the particular service a user is wishing to obtain, will be kept in Auth-Data attribute in LHS of a user's profile.

Authorization Parameters

These parameters define queries used to retrieve the authorization information from the SQL database. All the queries refer to the authentication database.

check_attr_query string
This query must return a list of triplets:
    attr-name, attr-value, opcode
The query is executed before comparing the request with the profile entry. The values returned by the query are added to LHS of the entry. opcode here means one of valid operation codes: `=', `!=', `<', `>', `<=', `>='.
reply_attr_query string
This query must return pairs:
    attr-name, attr-value
The query is executed after a successful match, the values it returns are added to the RHS list of the matched entry, and are therefore returned to the NAS in the reply packet.

Example of Authorization Parameters

Suppose your attribute information is stored in a SQL table of the following structure:

    CREATE TABLE attrib (
      user_name varchar(32) default '' not null,
      attr      char(32) default '' not null,
      value     char(128),
      op enum("=", "!=", "<", ">", "<=", ">=") default null
    );

Each row of the table contains the attribute-value pair for a given user. If op field is NULL, the row describes LHS (check) pair. Otherwise, it describes a RHS (reply) pair. The authorization queries for this table will look as follows:

    check_attr_query  SELECT attr,value,op \
                      FROM attrib \
                      WHERE user_name='%u' \
                      AND op IS NOT NULL

    reply_attr_query  SELECT attr,value \
                      FROM attrib \
                      WHERE user_name='%u' \
                      AND op IS NULL

Now, let's suppose the `raddb/users' contains only one entry:

    DEFAULT Auth-Type = SQL
            Service-Type = Framed-User

And the attrib table contains following rows:

=10.10.10.11 @tab NULL
user_name | attr | value | op
jsmith | NAS-IP-Address | 10.10.10.1 |
jsmith | NAS-Port-Id | 20 | <=
jsmith | Framed-Protocol | PPP | NULL
jsmith | Framed-IP-Address |

Then, when the user jsmith is trying to authenticate, the following happens:

  1. Radius finds the matching entry (DEFAULT) in the `raddb/users'.
  2. It queries the database using the check_attr_query. The triplets it returns are then added to the LHS of the profile entry. Thus, the LHS will contain:
        Auth-Type = SQL,
    NAS-IP-Address = 10.10.10.1,
    NAS-Port-Id <= 20
  3. Radius compares the incoming request with the LHS pairs thus obtained. If the comparison fails, it rejects the authentication. Please note, that the Auth-Type attributes itself triggers execution of auth_query, described in the previous section.
  4. After a successful authentication, Radius queries the database, using reply_attr_query, and adds its return to the list of RHS pairs. The RHS pairs will then be:
        Service-Type = Framed-User,
    Framed-Protocol = PPP,
    Framed-IP-Address = 10.10.10.11
    This list is returned to the NAS along with the authentication accept packet.

Thus, this configuration allows the user jsmith to use only NAS 10.10.10.1, ports from 1 to 20 inclusive. If the user meets these conditions, he is allowed to use PPP service, and is assigned IP address 10.10.10.11.

Accounting Parameters

To perform the SQL accounting radiusd needs to know the database where it is to store the accounting information. This information is supplied by the following statements:

doacct bool
When set to yes enables SQL accounting. All acct_ keywords are ignored if doacct is set to no.
acct_db string
Specifies the name of the database where the accounting information is to be stored.
acct_max_connections number
Specifies the maximum number of accounting SQL connections to keep open. This parameter is ignored if keepopen is set to no.

Further, radiusd needs to know which information it is to store into the database and when. Each of five accounting request types (see section Accounting Requests) has a SQL query associated with it. Thus, when radius receives an accounting request, it determines the query to use by the value of Acct-Status-Type attribute.

Following statemens define the accounting queries:

acct_start_query string
Specifies the SQL query to be used when Session Start Packet is received. Typically, this would be some INSERT statement (see section Writing SQL Accounting Query Templates).
acct_stop_query string
Specifies the SQL query to be used when Session Stop Packet is received. Typically, this would be some UPDATE statement.
acct_stop_query string
Specifies the SQL query to be executed upon arrival of a Keepalive Packet. Typically, this would be some UPDATE statement.
acct_nasup_query string
Specifies the SQL query to be used upon arrival of an Accounting Off Packet.
acct_nasdown_query string
Specifies the SQL query to be used when a NAS sends Accounting On Packet.

None of these queries should return any values.

  • Queries: Writing SQL acounting query templates.

Writing SQL Accounting Query Templates

Let's suppose you have an accounting table of the following structure:

    CREATE TABLE calls (
      status              int(3),
      user_name           char(32),
      event_date_time     datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
      nas_ip_address      char(17),
      nas_port_id         int(6),
      acct_session_id     char(16) DEFAULT '' NOT NULL,
      acct_session_time   int(11),
      acct_input_octets   int(11),
      acct_output_octets  int(11),
      connect_term_reason int(4),
      framed_ip_address   char(17),
      called_station_id   char(32),
      calling_station_id  char(32)
    );

On receiving the Session Start Packet we would insert a record into this table with status set to 1. At this point the columns acct_session_time, acct_input_octets, acct_output_octets as well as connect_term_reason are unknown, so we will set them to 0:

    # Query to be used on session start
    acct_start_query     INSERT INTO calls \
                         VALUES(%C{Acct-Status-Type},\
                                '%u',\
                                '%G',\
                                '%C{NAS-IP-Address}',\
                                %C{NAS-Port-Id},\
                                '%C{Acct-Session-Id}',\
                                0,\
                                0,\
                                0,\
                                0,\
                                '%C{Framed-IP-Address}',\
                                '%C{Called-Station-Id}',\
                                '%C{Calling-Station-Id}')

Then, when the Session Stop Packet request arrives we will look up the record having status = 1, user_name matching the value of User-Name attribute, and acct_session_id matching that of Acct-Session-Id attribute. Once the record is found, we will update it, setting

    status = 2
    acct_session_time = value of Acct-Session-Time attribute
    acct_input_octets = value of Acct-Input-Octets attribute
    acct_output_octets = value of Acct-Output-Octets attribute
    connect_term_reason = value of Acct-Terminate-Cause attribute

Thus, every record with status = 1 will represent the active session and every record with status = 2 will represent the finished and correctly closed record. The constructed acct_stop_query is then:

    # Query to be used on session end
    acct_stop_query      UPDATE calls \
                         SET status=%C{Acct-Status-Type},\
                             acct_session_time=%C{Acct-Session-Time},\
                             acct_input_octets=%C{Acct-Input-Octets},\
                             acct_output_octets=%C{Acct-Output-Octets},\
                             connect_term_reason=%C{Acct-Terminate-Cause} \
                         WHERE user_name='%C{User-Name}' \
                         AND status = 1 \
                         AND acct_session_id='%C{Acct-Session-Id}'

Upon receiving a Keepalive Packet we will update the information stored with acct_start_query:

    acct_alive_query  UPDATE calls \
                      SET acct_session_time=%C{Acct-Session-Time},\
                          acct_input_octets=%C{Acct-Input-Octets},\
                          acct_output_octets=%C{Acct-Output-Octets},\
                          framed_ip_address=%C{Framed-IP-Address} \
                      WHERE user_name='%C{User-Name}' \
                      AND status = 1 \
                      AND acct_session_id='%C{Acct-Session-Id}'

Further, there may be times when it is necessary to bring some NAS down. To correctly close the currently active sessions on this NAS we will define a acct_nasdown_query so that it would set status column to 2 and update acct_session_time in all records having status = 1 and nas_ip_address equal to IP address of the NAS. Thus, all sessions on a given NAS will be closed correctly when it brought down. The acct_session_time can be computed as difference between the current time and the time stored in event_date_time column:

    # Query to be used when a NAS goes down, i.e. when it sends
    # Accounting-Off packet
    acct_nasdown_query UPDATE calls \
                       SET status=2,\
                           acct_session_time=unix_timestamp(now())-\
                                   unix_timestamp(event_date_time) \
                       WHERE status=1 \
                       AND nas_ip_address='%C{NAS-IP-Address}'

We have not covered only one case: when a NAS crashes, e.g. due to a power failure. In this case it does not have a time to send Accounting-Off request and all its records remain open. But when the power supply is restored, the NAS will send an Accounting On packet, so we define a acct_nasup_query to set status column to 3 and update acct_session_time in all open records belonging to this NAS. Thus we will know that each record having status = 3 represents a crashed session. The query constructed will be:

    # Query to be used when a NAS goes up, i.e. when it sends
    # Accounting-On packet
    acct_nasup_query   UPDATE calls \
                       SET status=3,\
                           acct_session_time=unix_timestamp(now())-\
                                   unix_timestamp(event_date_time) \
                       WHERE status=1 \
                       AND nas_ip_address='%C{NAS-IP-Address}'

Rewrite functions -- `raddb/rewrite'

The file `raddb/rewrite' contains definitions of Rewrite extension functions. For information regarding Rewrite extension language See section Rewrite.

Login Menus -- `raddb/menus'

The menus is a way to allow user the choice between various services he could be provided. The menu functionality is enabled when Radius is compiled with --enable-livingston-menus option.

A user is presented a menu after it is authenticated if the RHS of his profile record consists of a single A/V pair in the form:

    Menu = <menu-name>

The menu files are stored in directory `raddb/menus'.

  • Syntax: A menu file syntax.
  • Example: An example of menu files.

A menu file syntax.

A menu file is a text file containing a menu declaration and any number of choice descriptions. The menus can be nested to an arbitrary depth.

A comment is introduced by a `#' character. All characters from this one up to the end of line are discarded.

The menu declaration is contained between the words `menu' and `end'. Each of these must be the only word on a line and must start in column 1.

Choice descriptions follow the menu declaration. Each description starts with a line containing choice identifier. A choice identifier is an arbitrary word identifying this choice, or a word `DEFAULT'. It is followed by comma-separated list of A/V pairs which will be returned to the server when a user selects this choice.

An example of menu files

Single-Level Menu

Suppose the following file is stored under `raddb/menus/menu1':

    menu
            *** Welcome EEE user! ***
    Please select an option:

            1. Start CSLIP session
            2. Start PPP session
            3. Quit

            Option:
    end
    # CSLIP choice
    # Framed-IP-Address of 255.255.255.254 indicates that the NAS should
    # select an address for the user from its own IP pool.
    1
            Service-Type = Framed-User,
            Framed-Protocol = SLIP,
            Framed-IP-Address = 255.255.255.254,
            Termination-Menu = "menu1"
    # PPP choice
    2
            Service-Type = Framed-User,
            Framed-Protocol = PPP,
            Framed-IP-Address = 255.255.255.254,
            Termination-Menu = "menu1"
    # A special menu EXIT means abort the session
    3
            Menu = "EXIT"
    # Return to this menu if no valid choice have been entered
    DEFAULT
            Menu = "menu1"

Now, suppose the `raddb/users' contains the following profile entry:

    DEFAULT Auth-Type = System
            Menu = "menu1"

and user `jsmith' has a valid system account and tries to log in from some NAS. Upon authenticating the user, the Radius server sees that his reply pairs contain the Menu attribute. Radius then sends Access-Challenge packet to the NAS with the text of the menu in it. The `jsmith' then sees on his terminal:

            *** Welcome EEE user! ***
    Please select an option:

            1. Start CSLIP session
            2. Start PPP session
            3. Quit

            Option:

He then enters `2'. The NAS sends the Access-Request packet to the server, which sees that user wishes to use option 2 and replies to the NAS with an Access-Accept packet containing the following attributes:

            Service-Type = Framed-User,
            Framed-Protocol = PPP,
            Framed-IP-Address = 255.255.255.254,
            Termination-Menu = "menu1"

The Termination-Menu in this list makes sure the same process will continue when `jsmith' logs out, i.e. he will be presented the same menu again until he enters choice `3' which will disconnect him.

Nested menus

In this example, the `other' choice refers to the menu above.

    menu
            *** Welcome here! ***
    Please enter an option:
            ppp     ---     Start PPP session
            telnet  ---     Begin guest login session
            other   ---     Select other option

            Enter your choice:
    end
    ppp
            Service-Type = Framed-User,
            Framed-Protocol = PPP
    telnet
            Service-Type = Login-User,
            Login-IP-Host = 10.11.11.7,
            Login-Service = Telnet,
            Login-TCP-Port = 23
    other
            Menu = "menu1"
    DEFAULT
            menu = "menu2"

Macro Substitution

Some statements in the configuration files need to use the actual values of the attributes supplied with the request. These are:

  • Exec-Program and Exec-Program-Wait assignments in `users' database
  • SQL query templates in `sqlserver'

In these statements the following macros are replaced by the value of corresponding attributes:

%Cnum
(num is a decimal number). This variable is replaced by the value of attribute number `num'. The attribute is looked up in the incoming request pairlist.
%C{attr-name}
This is replaced by the value of attribute named `attr-name'. The attribute is looked up in the incoming request pairlist.
%Rnum
(num is a decimal number). This variable is replaced by the value of attribute number `num'. The attribute is looked up in the reply pairlist.
%R{attr-name}
This is replaced by the value of attribute named `attr-name'. The attribute is looked up in the reply pairlist.
%D
This is replaced by current date/time (localtime).
%G
This is replaced by current date/time in GMT.

The "`{}' form" allows to specify default value for the substitution. The default value will be used when no such attribute is encountered in the pairlist. The syntax for specifying the default value resembles that of shell environment variables.

The substitution %C{attr-name:-defval} is expanded to the value of attr-name attribute, if it is present in the request pairlist, and to defval otherwise. For example:

            %C{Acct-Session-Time:-0}

will return the value of Acct-Session-Time attribute or 0 if it doesn't exist in the request pairlist.

The substitition %C{attr-name:=defval} is expanded to the value of attr-name attribute. If this attribute is not present in the request pairlist, it will be created and assigned the value defval. E.g.:

            %C{Acct-Session-Time:=0}

The substitution %C{attr-name:?message} is expanded to the value of attr-name attribute, if it is present. Otherwise the diagnostic message "attr-name: message" is issued to the log error channel, and string "message" is returned.

The substitition %C{attr-name:+retval} is expanded to empty string if the attribute attr-name is present in the referenced pairlist. Othervise it is expanded to retval.

You can also use the following shortcuts:

%p
Port number
%n
NAS IP address
%f
Framed IP address
%u
User name
%c
Callback-Number
%i
Calling-Station-Id
%t
MTU
%a
Protocol (SLIP/PPP)
%s
Speed (Connect-Info attribute)

Authentication

An Authentication Type specifies which credentials the user is required to supply in order to be authenticated and where the user's authentication data are stored. It is defined by the value of Auth-Type attribute in LHS of a `users' entry.

  • Accept Auth: Accept unconditionally.
  • Reject Auth: Reject unconditionally.
  • Local Password Auth: Authenticate using plaintext password.
  • Encrypted Password Auth: Authenticate using MD5 encrypted password.
  • System Auth: Authenticate using system account.
  • SQL Auth: Authenticate using SQL.
  • PAM Auth: Authenticate using PAM.
  • Custom Auth: Defining Custom Authentication Types.
  • Checking Simultaneous Logins

Accept Authentication Type

Accept is the simplest authentication type. Users with this authentication type will be authenticated successfully without checking any credentials. Actually this means that only username is required for authentication.

This authentication type is used for each `users' entry, whose LHS contains

    Auth-Type = Accept

This authentication type can be used for guest accounts, e.g. the following profile in `users':

    guest   Auth-Type = Accept,
                    Password != "",
                    Simultaneous-Use = 10
            Service-Type = Framed-User,
                    Framed-Protocol = PPP

allows up to 10 simultaneous guest PPP accounts. To log in using such guest account it is sufficient to use username `guest' and any non-empty password.

Reject Authentication Type

The Reject authentication type causes the request to be rejected unconditionally. It can be used to disable a user account (For another method of disabling user accounts, see section List of Blocked Users -- `raddb/access.deny').

This authentication type is used for each `users' entry, whose LHS contains

    Auth-Type = Reject

Local Password Authentication Type

The Local Password authentication type allows to keep plaintext user passwords. Although the use of this authentication type is strongly discouraged for security reasons, this is the only authentication type that can be used with CHAP authentication.

There are two ways of using this authentication type

Specifying Passwords in users File.

To keep the plaintext passwords in `users' file, the profile entry must follow this pattern:

    user-name  Auth-Type = Local,
                         Password = plaintext

The plaintext is the user's plaintext password. Obviously, user-name may not be DEFAULT nor BEGIN.

Specifying Passwords in SQL Database.

    user-name   Auth-Type = Local,
                          Password-Location = SQL

When the user is authenticated using such profile, its password is retrieved from the authentication database using auth_query. The configuration of SQL authentication is described in detail in section Authentication Server Parameters.

Encrypted Password Authentication Type

The Encrypted Password type allows to keep user's passwords encrypted via DES or MD5 algorythm. There are two ways of using this authentication type.

Specifying Passwords in users File.

    user-name  Auth-Type = Crypt-Local,
                         Password = crypt-pass

The Crypt-Password is a shortcut for the above notation:

    user-name  Crypt-Password = crypt-pass

Specifying Passwords in SQL Database.

    user-name   Auth-Type = Crypt-Local,
                          Password-Location = SQL

Using this profile, the user's password is retrieved from the authentication database using auth_query. The configuration of SQL authentication is described in detail on section Authentication Server Parameters.

The shortcut for this notation is Auth-Type = SQL.

In any case, the passwords used with this authentication type must be either DES or MD5 hashed.

System Authentication Type

The System authentication type requires that the user have a valid system account on the machine where the radius server is running. The use of this type is triggered by setting

    Auth-Type = System

in the LHS of a `users' entry.

SQL Authentication Type

Setting Auth-Type = SQL or Auth-Type = Mysql in the LHS of a `users' entry is a synonim for

    Auth-Type = Crypt-Local, Password-Location = SQL

and is provided as a shortcut and for backward compatibility with previous versions of GNU Radius.

For description of SQL authentication, See section Encrypted Password Authentication Type. The configuration of SQL subsystem is described in See section SQL Configuration -- `raddb/sqlserver'.

PAM Authentication Type

PAM authentication type indicates that a user should be authenticated using PAM (Pluggable Authentication Module) framework. The simplest way of usage is:

    Auth-Type = PAM

Any user whose `users' profile contains the above, will be authenticated via PAM, using service name `radius'. If you wish to use another service name, set it using Auth-Data attribute, e.g.:

    Auth-Type = PAM,
        Auth-Data = pam-service

Defining Custom Authentication Types

The are three ways to define custom authentication types:

  1. Write a PAM module.
  2. Use a Guile procedure.
  3. Use an external program

You can write a PAM module implementing the new authentication type. Then, specifying Auth-Type = PAM allows to apply it (see section PAM Authentication Type).

Alternatively, you may write a Scheme procedure implementing the new authentication type. To apply it, use Scheme-Procedure attribute in RHS. The Auth-Type = Accept can be used in LHS if the whole authentication burden is to be passed to the Scheme procedure. For example, if one wrote a procedure my-auth, to apply it to all users, one will place the following profile in his `users' file:

    DEFAULT  Auth-Type = Accept
             Scheme-Procedure = "my-auth"

For a discussion of how to write Scheme authentication procedures, See section Authentication with Scheme.

The third way to implemement your own authentication method is using an external program. This is less effective than the methods described above, but may be necessary sometimes. To invoke the program, use the following statement in the RHS of `users' entry:

    Exec-Program-Wait = "progname args"

The progname must be the full path to the program, args --- any arguments it needs. The usual substitutions may be used in args to pass any request attributes to the program (see section Macro Substitution).

For a detailed description of Exec-Program-Wait attribute and an example of its use, See section Exec-Program-Wait.

Checking Simultaneous Logins

The number of sessions a user can have open simultaneously can be restricted by setting Simultaneous-Use attribute in the user's profile LHS (see section Simultaneous-Use). By default the number of simultaneous sessions is unlimited.

When a user with limited number of simultaneous logins authenticates himself, Radius first counts the number of the sessions that are already opened by this user. If this number is equal to the value of Simultaneous-Use attribute the authentication request is rejected.

To determine the number of open sessions, Radius scans the `radlog/radutmp' for any open entries marked with the user's login name section UNIX Accounting. Such entries are created when Radius receives an Accounting-Request packet with Acct-Status-Type attribute set to Start. An entry is marked closed when a corresponding Accounting-Request packet arrives with Acct-Status-Type attribute set to Stop.

Since an open entry might be a result of missing Stop packet, Radius queries the NAS whether the session listed in the entry is currently active. If the NAS replies positive, the session count is incremented, if it replies negative, such entry is marked as closed and is not counted. There may also be cases when the NAS is unreachable due to some reasons. In such cases the Radius behavior is determined by the value of checkrad-assume-logged in `config' file section auth statement. If the value is yes, Radius assumes the session is still active and increases the session count, otherwise it proceeds as if the NAS returned negative reply.

To query a NAS, Radius first looks up its type and additional parameters in `naslist' file (see section NAS List -- `raddb/naslist'). If the NAS type is `true', Radius acts as if the NAS returned 1, if the type is `false', it acts as if the NAS returned 0, otherwise it looks up the entry in the `nastypes' which has matching type (see section NAS Types -- `raddb/nastypes'). If such entry does not exist, Radius issues the error message and acts accordingly to the value of configuration variable checkrad-assume-logged. Otherwise, Radius determines the query method to use from the second field of this entry, and constructs its arguments by appending arguments from the `naslist' entry to those of nastypes entry. Please note, that the former take precedence over the latter, and can thus be used to override default values specified in `nastypes'.

Having determined the query method and its argument, Radius queries NAS and analyzes its output by invoking a user-supplied Rewrite function. The function to use is specified by the function= argument to the method. It is called each time a line of output is received from the NAS (for finger queries) or a variable is received (for SNMP queries). The process continues until the function returns 1 or the last line of output is read or a timeout occurs whichever comes first.

If the user-function returns 1 it is taken to mean the user's session is now active at the NAS, otherwise, if it replies 0 or if the end of output is reached, it is taken to mean the user's session is not active.

The syntax conventions for user-supplied functions are described in detail in section Login Verification Functions.

Accounting

By default GNU Radius supports three types of accounting. Any additional accounting methods can be defined using extension mechanisms.

The accounting methods are applied to a request in a following sequence:

  1. UNIX Accounting
  2. Detailed Request Accounting
  3. SQL Accounting
  4. Custom Accounting

In this sequence, only UNIX Accounting is obligatory, all other methods are applied only when enabled.

If any accounting type in this sequence fails, the accounting is deemed to fail and all subsequent methods are not invoked.

  • UNIX Accounting: UNIX style utmp/wtmp accounting.
  • Detailed Request Accounting: Detailed requests.
  • SQL Accounting: Accounting to SQL server.
  • Custom Acct: Defining Custom Accounting Types.

UNIX Accounting

This accounting method is always enabled.

Radius keeps files `radutmp' and `radwtmp' in its logging directory and stores the accounting data there. The utilities radwho and radlast can be used to list information about users' sessions.

Detailed Request Accounting

Radius stores the detailed information about accounting packets it receives in files
`radacct/nasname/detail' (see section Naming Conventions), where nasname is replaceed with the short name of the NAS from the `raddb/naslist' file (see section NAS List -- `raddb/naslist').

By default, this accounting type is always enabled, provided that `radacct' directory exists and is writable (see section Naming Conventions). To turn the detailed accounting off, use detail statement in `config' file. For more information about it, See section acct statement.

The accounting detail files consist of a record per each accounting request. A record includes the timestamp and detailed dump of attributes from the packet, e.g.:

    Fri Dec 15 18:00:24 2000
            Acct-Session-Id = "2193976896017"
            User-Name = "e2"
            Acct-Status-Type = Start
            Acct-Authentic = RADIUS
            Service-Type = Framed-User
            Framed-Protocol = PPP
            Framed-IP-Address = 11.10.10.125
            Calling-Station-Id = "+15678023561"
            NAS-IP-Address = 11.10.10.11
            NAS-Port-Id = 8
            Acct-Delay-Time = 0
            Timestamp = 976896024
            Request-Authenticator = Unverified

    Fri Dec 15 18:32:09 2000
            Acct-Session-Id = "2193976896017"
            User-Name = "e2"
            Acct-Status-Type = Stop
            Acct-Authentic = RADIUS
            Acct-Output-Octets = 5382
            Acct-Input-Octets = 7761
            Service-Type = Framed-User
            Framed-Protocol = PPP
            Framed-IP-Address = 11.10.10.125
            Acct-Session-Time = 1905
            NAS-IP-Address = 11.10.10.11
            NAS-Port-Id = 8
            Acct-Delay-Time = 0
            Timestamp = 976897929
            Request-Authenticator = Unverified

SQL Accounting

The SQL accounting method is enabled when Radius is configured with --enable-sql option and `sqlserver' file in its configuration directory is properly set up (see section SQL Configuration -- `raddb/sqlserver').

This version of GNU Radius (0.96) supports MySQL and PostgreSQL servers. Support for Oracle servers will be added in the nearest future.

With this accounting method enabled, radiusd will store the information about accounting requests in the configured SQL database. The accounting method is fully configurable: the Radius administrator defines both the types of requests to be accounted and the information to be stored into the database. (see section SQL Configuration -- `raddb/sqlserver').

Defining Custom Accounting Types.

If the built-in accounting methods do not meet your requirements, you can implement your own accounting methods. There are two ways for doing so:

  1. Using a Guile procedure.
  2. Using an external program

To use a Guile procedure for accounting, the name of the procedure must be specified as a value to Scheme-Acct-Procedure attribute in RHS list of a `hints' entry, e.g.:

    DEFAULT NULL Scheme-Acct-Procedure = "my-acct"

For a detailed description of Scheme accounting procedures, See section Accounting with Scheme.

Another way of implemementing your own accounting method is using an external program. This is less effective than the methods described above, but may be necessary sometimes. To invoke the program, use the following statement in the LHS of `hints' entry:

    Acct-Ext-Program = "progname args"

The progname must be the full path to the program, args --- any arguments it needs. The usual substitutions may be used in args to pass any request attributes to the program (see section Macro Substitution).

For a detailed description of Acct-Ext-Program, See section Acct-Ext-Program.

Logging

GNU Radius reports every event worth mentioning. The events are segregated by their severity level. Radius discerns the following levels (in order of increasing severity):

Debug
The debug messages section Debugging.
Auth
Under this level every authentication attempt is logged. This is enabled by setting
    level auth;
in category auth statement of `config' file.
Proxy
Messages regarding proxy requests (see section Proxying).
Info
Informational messages.
Notice
Normal, but significant conditions.
Warning
Warning conditions. These mean some deviations from normal work.
Error
Error conditions. Usually these require special attention.
CRIT
Critical conditions due to which Radius is no longer able to continue working. These require urgent actions from the site administrator.

By default, all messages in all levels are output to file `radlog/radius.log'. In addition, messages in level CRIT are also duplicated to the system console. These defaults can be overridden using logging statement in `raddb/config' file (See section logging block, for the description of logging statement syntax, see section Naming Conventions for information about the locations of different radius configuration files).

Debugging

GNU Radius provides extensive debugging features. These are enabled either by -x command option to the radiusd section How to Start the Daemon., or by level statement in debug category section logging block. Both cases require as an argument a valid debug specification.

A debug specification sets the module for which the debugging should be enabled and debugging level. The higher the level is, the more detailed information is provided. The module name and level are separated by an equal sign. If the level is omitted, the highest possible level (100) is assumed. The module name may be abbreviated to first N characters, in which case the first matching module is selected. Several such specifications can be specified, in which case they should be separated by a comma. For example, the following is a valid debug specification:

            proxy.c=10,files.c,config.y=1

It sets debug level 10 for module proxy.c, level 100 for files.c, and 1 for config.y.

The modules and debugging levels are subject to change from release to release.

Extensions

The use of extension language allows to extend the functionality of GNU Radius without having to modify its source code. The two extension languages supported are Rewrite and Scheme. Use of Rewrite is always enabled. Use of Scheme requires Guile version 1.4 or higher.

  • Rewrite: The built-in extension language.
  • Guile: Using Scheme.

Rewrite

Rewrite is the GNU Radius extension language. Its name reflects the fact that it was originally designed to rewrite the broken request packets, so they could be processed as usual (see section Rewriting Incoming Requests). Beside this basic use, however, Rewrite functions are used in verifying the activity of user sessions (see section Checking Simultaneous Logins).

  • Syntax Overview
  • Quick Start
  • Interaction with Radius
  • Rewriting Incoming Requests
  • Login Verification Functions
  • Attribute Creation Functions
  • Full Syntax Description

Syntax Overview

Rewrite syntax resembles that of C. Rewrite has two basic data types: integer and string. It does not have global variables, all variables are automatic. The only exception are the A/V pairs from the incoming request, which are accessible to Rewrite functions via special notation %[attr].

Quick Start

As an example, let's consider the following Rewrite function:

    string
    foo(integer i)
    {
        string rc;
        if (i % 2)
            rc = "odd";
        else
            rc = "even";
        return "the number is " + rc;
    }

The function takes an integer argument and returns string "the number is odd" or "the number is even", depending on the value of i. This illustrates the fact that in Rewrite the addition operator is defined on the string type. The result of such operation is the concatenation of operands.

Another example is a function that adds a prefix to the User-Name attribute:

    integer
    px_add()
    {
            %[User-Name] = "pfx-" + %[User-Name];
            return 0;
    }

The function manipulates the contents of the incoming request, its return value has no special meaning.

Interaction with Radius

A Rewrite function can be invoked in several ways, depending on its purpose. There are three major kinds of Rewrite functions:

  • Functions used to rewrite the incoming requests.
  • Functions designed for simultaneous login verification.
  • Functions used to generate RADIUS attribute values.

Rewriting Incoming Requests

The need of rewriting the incoming requests arises from the fact that some NASes are very particular about the information they send with the requests. There are cases when the information they send is hardly usable or even just unusable. For example, a Cisco AS5300 terminal server used as a voice over IP router packs a lot of information into its Acct-Session-Id attribute. Though the information stored there is otherwise relevant, it makes proper accounting impossible since the Acct-Session-Id attributes in the start and stop packets of the same session become different, and thus Radius cannot determine the Session Start to which the given Session Stop request corresponds (see section Acct-Session-Id).

In order to cope with such NASes, GNU Radius is able to invoke a Rewrite function upon arrival of the packet and before further processing it. This function can transform the packet so, that it obtains the form prescribed by RFCs and its further processing becomes possible.

For example, in the case of AS5300 router, a corresponding rewrite function parses the Acct-Session-Id attribute, breaks it down into fields, stores them into proper attributes, creating them if necessary, and, finally replaces Acct-Session-Id with its real value, which is the same for start and stop records corresponding to a single session. Thus all the information that came with the packet is preserved, but the packet itself is made usable for proper accounting.

A special attribute, Rewrite-Function, is used to trigger invocation of a Rewrite function. Its value is a name of the function to be invoked.

When used in a `naslist' profile, the attribute causes the function to be invoked when the incoming request matches the huntgroup (see section Huntgroups). For example, to have a function fixup invoked for each packet from the NAS 10.10.10.11, the following huntgroup rule may be used:

    DEFAULT  NAS-IP-Address = 11.10.10.11
             Rewrite-Function = "fixup"

The Rewrite-Function attribute may also be used in a `hints' rule. In this case, it will invoke the function if the request matches the rule (see section Hints). For example, this `hints' rule will cause the function to be invoked for each request containing the username starting with `P':

    DEFAULT  Prefix = "P"
             Rewrite-Function = "fixup"

Please note, that in both cases the attribute can be used either in LHS or in RHS pairs of a rule.

The packet rewrite function must be declared as having no arguments, and returning integer value:

    integer fixup()
    {
    }

The actual return value from such a function is ignored, the integer return type is just a matter of convention.

The following subsection present some examples of packet rewriting functions.

  • Example

Examples of Various Rewrite Functions.

The examples found in this chapter are working functions that can be used with various existing NAS types. They are taken from the `rewrite' file contained in distribution of GNU Radius.

1. Port rewriting for MAX Ascend terminal servers

Some MAX Ascend terminal servers pack additional information into NAS-Port-Id attribute. The port number is constructed as XYYZZ, where X = 1 for digital, X = 2 for analog, YY is line number (1 for first PRI/T1/E1, 2 for second, so on), and ZZ = channel number (on the PRI or Channelized T1/E1).

The following rewrite functions are intended to compute the integer port number in the range (1 .. portcnt), where portcnt represents the real number of physical ports available on the NAS. Such port number can be used, for example, with Add-Port-To-IP-Address attribute (see section Add-Port-To-IP-Address).

    /*
     * decode MAX port number
     * input: P        --  The value of NAS-Port-Id attribute
     *        portcnt  --  number of physical ports on the NAS
     */
    integer
    max_decode_port(integer P, integer portcnt)
    {
        if (P > 9999) {
            integer s, l, c;

            s = P / 10000;
            l = (P - (10000 * s))/100;
            c = P - ((10000 * s) + (100 * l));
            return (c-1) + (l-1) * portcnt;
        }
        return P;
    }

    /*
     * Interface function for MAX terminal server with 23 ports.
     * Note that it saves the received NAS-Port-Id attribute in the
     * Orig-NAS-Port-Id attribute. The latter must be defined somewhere
     * in the dictionary
     */
    integer
    max_fixup()
    {
        %[Orig-NAS-Port-Id] = %[NAS-Port-Id]; # Preserve original data
        %[NAS-Port-Id] = max_decode_port(%[NAS-Port-Id], 23);
        return 0;
    }

2. Session ID parsing for Cisco AS 5300 series

Cisco VOIP IOS encodes a lot of other information into its Acct-Session-Id. The pieces of information are separated by `/' character. The part of Acct-Session-Id up to first `/' character is the actual session ID.

On the other hand, its accounting packets lack NAS-Port-Id, though they may contain the vendor-specific pair with code 2 (vendor PEC 9), which is the string in the form `ISDN 9:D:999' (`9' represents a decimal digit). The number after the last `:' character can be used as a port number.

The following code parses Acct-Session-Id attribute and stores the information it contains in various other attributes, generates normal Acct-Session-Id and attempts to generate NAS-Port-Id attribute.

    /*
     * The port rewriting function for Cisco AS5300 used for VoIP.
     * This function is used to generate NAS-Port-Id pair on the basis
     * of vendor-specific pair 2. If the latter is in the form
     * "ISDN 9:D:999" (where each 9 represents a decimal digit), then
     * the function returns the number after the last colon. This is
     * used as a port number.
     */
    integer
    cisco_pid(string A)
    {
        if (A =~
            ".*\([0-9][0-9]*\):[A-Z0-9][A-Z0-9]*:\([0-9][0-9]*\)") {
            return (integer)\2;
        }
        return -1;
    }

    /*
     * This function parses the packed session id.
     * The actual sid is the number before the first slash character.
     * Other possibly relevant fields are also parsed out and saved
     * in the Voip-* A/V pairs. The latter should be defined somewhere
     * in the dictionary.
     * Please note, that the regular expression in this example
     * spans several lines for readability. It should be on one
     * line in real file.
     */
    string
    cisco_sid(string S)
    {
       if (S =~ "\(.[^/]*\)/[^/]*/[^/]*/\([^/]*\)/\([^/]*\)/
                 \([^/]*\)/\([^/]*\)/\([^/]*\)/\([^/]*\)
                 /\([^/]*\).*") {
            %[Voip-Connection-ID] = \2;
            %[Voip-Call-Leg-Type] = \3;
            %[Voip-Connection-Type] = \4;
            %[Voip-Connect-Time] = \5;
            %[Voip-Disconnect-Time] = \6;
            %[Voip-Disconnect-Cause] = \7;
            %[Voip-Remote-IP] = \8;
            return \1;
       }
       return S;
    }

    /*
     * Normalize cisco AS5300 packets
     */
    integer
    cisco_fixup()
    {
        integer pid;

        if ((pid = cisco_pid(%[Cisco-PRI-Circuit])) != -1) {
            if (*%[NAS-Port-Id])
                %[Orig-NAS-Port-Id] = %[NAS-Port-Id];
            %[NAS-Port-Id] = pid;
        }
        if (*%[Acct-Session-Id]) {
            %[Orig-Acct-Session-Id] = %[Acct-Session-Id];
            %[Acct-Session-Id] = cisco_sid(%[Acct-Session-Id]);
        }
        return 0;
    }

3. Username rewriting for NT machines.

Users coming from Windows NT machines often authenticate themselves as `NT_DOMAIN\username'. The following function selects the username part and stores it in the User-Name attribute:

    integer
    login_nt(string uname)
    {
        integer i;

        if ((i = index(uname, '\\')) != -1)
            return substr(uname, i+1, -1);
        return uname;
    }

    integer
    nt_rewrite()
    {
        %[Orig-User-Name] = %[User-Name];
        %[User-Name] = login_nt(%[User-Name]);
        return 0;
    }

Login Verification Functions

A login verification function is invoked to process the output from the NAS. This process is described in section Checking Simultaneous Logins. The function to be invoked for given NAS is defined by function flag in `raddb/nastypes' or `raddb/naslist' files (see section NAS Types -- `raddb/nastypes'). It must be defined as follows:

    integer check(string str, string name, integer pid, string sid)
    {
    }

Its arguments are:

str
Input string. If the query method is finger, this is the string of output received from the NAS with trailing newline stripped off. If the query method is snmp, this is the received variable value converted to its string representation.
name
User name.
pid
Port Id of the session.
sid
Session ID.

The function should return non-0 if its arguments match user's session and 0 otherwise.

  • Example

Examples of login verification functions

As an example, let's consider the function for analyzing a line line of output from a standard UNIX finger service. In each line of finger output the first field contains username, the third field --- tty number (Port ID), and the seventh field contains session ID. The function must return 1 if the three fields match the input user name, port and session IDs.

    integer
    check_unix(string str, string name, integer pid, string sid)
    {
        return field(str, 1) == name
               && field(str, 3) == pid
               && field(str, 7) == sid;
    }

Next example is a function to analyze a line of output from an SNMP query returning a user name. This function must return 1 if entire input line matches the user name.

    integer
    check_username(string str, string name, integer pid, string sid)
    {
        return str == name;
    }

Attribute Creation Functions

These are the functions, used to create RADIUS reply attributes. An attribute creation function can take any number of arguments. The type of its return is determined by the type of RADIUS attribute the value will be assigned to. To invoke the function, write its name in the A/V pair of RHS in `raddb/users' file, e.g.:

    DEFAULT Auth-Type = SQL
            Service-Type = Framed-User,
                    Framed-IP-Address = "=get_ip_addr(10.10.10.1)"

The function get_ip_addr will be invoked after successful authentication and it will be passed IP address 10.10.10.1 as its argument. An example of a useful function, that can be invoked this way:

    integer
    get_ip_address(integer base)
    {
        return base + %[NAS-Port-Id] - %[NAS-Port-Id]/16;
    }

Full Syntax Description

  • Data types
  • Symbols
  • Identifiers
  • Declarations
  • Statements
  • Built-in Functions

Rewrite Data Types

There are only two data types: integer and string, the two being coercible to each other in the sense that a string can be coerced to an integer if it contains a valid ASCII representation of a decimal, octal or hex number, and the integer can always be coerced to a string, the result of such coercion being the ASCII string with decimal representation of the number.

Rewrite Symbols

A symbol is a lexical token. The following symbols are recognized:

Arithmetical operators
These are `+', `-', `*', `/' representing the basic arithmetical operations and `%' meaning remainder.
Comparison operators
These are: `==', `!=', `<', `<=', `>', `>=' with the same meaning they have in C. Special operators are provided for regular expression matching. Binary operator `=~' returns true, if its left-hand-side operand matches the regular expression on its right-hand side. `!~' returns true if the left-hand side operand does not match the regexp on right-hand side. The right-hand side operand of `!~' or `=~' must be a literal string, i.e. the regular expression must be known at compile time.
Unary operators.
Unary operators are `-' and `+' for unary plus and minus, `!' for boolean negation and `*' for testing for the existence of an attribute.
Boolean operators.
These are: `&&' and `||'.
Parentheses `(' and `)'
These are used to change the precedence of operators, to introduce type casts (type coercions), to declare functions and to pass actual arguments to functions.
Curly braces (`{' and `}')
These are used to delimit blocks of code.
Numbers
Numbers follow usual C convention for integers. A number consisting of a sequence of digits, is taken to be octal if it begins with `0' (digit zero) and decimal otherwise. If the sequence of digits is preceded by `0x' or `0X', it is taken to be a hexadecimal integer.
Characters
These follow usual C convention for characters, i.e. either an ASCII character or its value enclosed in a pair of single quotes. The character value begins with `\' (backslash) and consists either of three octal or of two hexadecimal digits. A character does not form a special data type, it is represented internally by an integer.
Quoted strings
These follow usual C conventions for strings.
Attribute values
The incoming request is passed implicitly to functions, invoked via Rewrite-Function attribute. It is kept as an associative array, whose entries can be accessed using the following syntax:
    `%[' attribute-name `]'
Thus notation returns the value of the attribute attribute-name. attribute-name should be a valid Radius dictionary name (see section Dictionary of Attributes -- `raddb/dictionary').
Identifiers
Identifiers represent functions and variables. These are described in the next section.
Regexp group references
A sequence of characters in the form:
    `\number'
refers to the contents of parenthesized group number number obtained as a result of the last executed `=~' command. The regexp group reference has always string data type. E.g.
    string
    basename(string arg)
    {
        if (arg =~ ".*/\(.*\)\..*")
            return \1;
        else
            return arg;
    }
This function strips from arg all leading components up to the last slash character, and all trailing components after the last dot character. It returns arg unaltered, if it does not contain slashes and dots. Roughly, it is analogous to the system basename utility.

Rewrite Identifiers

A valid identifier is a string of characters meeting the following requirements:

  1. It starts with either a lower- or uppercase letter of the Latin alphabet or any of the following symbols: `_', `$'.
  2. It consists of alphanumeric characters, underscores(`_') and dollar signs (`$').

Rewrite Declarations

Function declarations

The Rewrite function is declared as follows:

    type function-name (parameter-list)

where type specifies the return type of the function, function-name declares the symbolic name of the function and parameter-list declares the formal parameters to the function. It is a comma-separated list of declarations in the form:

    type parm-name

type being the parameter type, and parm-name being its symbolic name. Both function-name and parm-name should be valid identifiers.

Variable declarations

There are no global variables in Rewrite. All variables are local. The local variables are declared right after the opening curly brace (`{') and before any executable statements. The declaration syntax is:

    type ident_list ;

Here ident_list is either a valid Rewrite identifier, or a comma- separated list of such identifiers. Please note that, unlike in C, no assignments are allowed in variable declarations.

Rewrite Statements

The Rewrite statements are: expressions, assignments, conditional statements and return statements. A statement is terminated by semicolon.

Expressions

An expression is:

  • A variable identifier
  • A type coercion expression
  • An arithmetic expression
  • A boolean expression
  • An assignment
  • A function call

Type coercion

The type coercion is like a type cast in C. Its syntax is

    `(' type `)' ident

the result of type coercion is as follows:

of the integer number (either decimal, octal or hex) it is converted to the integer, otherwise the result of the conversion is undefined.
type | Variable type | Resulting conversion
integer | integer | No conversion. This results in the same integer value.
integer | string | If the string value of the variable is a valid ASCII representation
string | integer | The ASCII representation (in decimal) of the integer number.
string | string | No conversion. This results in the same string value.

Assignment

An assignment is:

    ident = expression ;

The variable ident is assigned the value of expression.

Function calls

These take the form:

    ident ( arg-list )

where ident is the identifier representing the function, arg-list is a comma-separated list of expressions supplying actual arguments to the function. The function ident references can be either a compiled function or a built-in function.

Please note that, unlike in C, the mismatch between the number of actual arguments and number of formal parameters in the compiled function declaration is not an error but rather a warning.

Rewrite Built-in Functions

The following built-in functions are provided:

Function: integer length (string s)
Returns the length of string s.

Function: integer index (string s, integer c)
Returns the index of the first occurrence of the character c in the string s. Returns -1 if no such occurrence is found.

Function: integer rindex (string s, integer i)
Returns the index of the last occurrence of the character c in the string s. Returns -1 if no such occurrence is found.

Function: string substr (string s, integer start, integer length)
Returns the at most length substring of s starting at position start.

Function: integer logit (string msg)
Outputs its argument to the radius log channel info. Returns 0. The function is intended for debugging purposes.

All character positions in strings are counted from 0.

Guile

The name Guile stands for GNU's Ubiquitous Intelligent Language for Extensions. It provides the Scheme interpreter conforming to R4RS language specification. This section describes use of Guile as an extension language for GNU Radius. It assumes that the reader is sufficiently familiar with the Scheme language. Please, refer to section `Top' in Revised(4) Report on the Algorithmic Language Scheme, for the information about the language. If you wish to know more about the Guile, See section `Overview' in The Guile Reference Manual.

Scheme procedures can be called for processing both authentication and accounting requests. The invocation of a scheme procedure for an authentication request is triggered by Scheme-Procedure attribute, the invocation for an accounting request is triggered by Scheme-Acct-Procedure attribute. The following sections address these issues in more detail.

  • Data Representation
  • Authentication with Scheme
  • Accounting with Scheme
  • Radius-Specific Functions

Data Representation

A/V pair lists are the main object scheme functions operate upon. Scheme is extremely convenient for representation of such objects. A Radius A/V pair is represented by a Scheme pair, e.g.

            Session-Timeout = 10

is represented in Guile as

            (cons "Session-Timeout" 10)

The CAR of the pair can contain either the attribute dictionary name, or the attribute number. Thus, the above pair may also be written in Scheme as

            (cons 27 10)

(Session-Timeout corresponds to attribute number 27).

Lists of A/V pairs are represented by Scheme lists. For example, the following Radius pair list

            User-Name = "jsmith",
                    Password = "guessme",
                    NAS-IP-Address = 10.10.10.1,
                    NAS-Port-Id = 10

is written in Scheme as:

            (list
              (cons "User-Name" "jsmith")
              (cons "Password" "guessme")
              (cons "NAS-IP-Address" "10.10.10.1")
              (cons "NAS-Port-Id" 10))

Authentication with Scheme

The Scheme procedure used for authentication must be declared as follows:

Function Template: auth-function request-list check-list reply-list
Its arguments are:
request-list
The list of A/V pairs from the incoming request
check-list
The list of A/V pairs from the LHS of the profile entry that matched the request.
reply-list
The list of A/V pairs from the RHS of the profile entry that matched the request.

The function return value determines whether the authentication will succeed. The function must return either a boolean value or a pair. The return of #t causes authentication to succeed. The return of #f causes it to fail.

If the function wishes to add something to the reply A/V pairs, it should return a pair in the form:

        (cons return-code list)

Where return-code is a boolean value of the same meaning as described above. The list is a list of A/V pairs to be added to the reply list. For example, the following function will always deny the authentication, returning appropriate message to the user:

    (define (decline-auth request-list check-list reply-list)
      (cons #f
            (list
             (cons "Reply-Message"
                   "\r\nSorry, you are not allowed to log in\r\n"))))

As a more constructive example, let's consider a function that allows the authentication only if a user name is found in its internal database.

    (define staff-data
      (list
       (list "scheme"
             (cons
              (list (cons "NAS-IP-Address" "127.0.0.1"))
              (list (cons "Framed-MTU" "8096")))
             (cons
              '()
              (list (cons "Framed-MTU" "256"))))))

    (define (auth req check reply)
      (let* ((username (assoc "User-Name" req))
             (reqlist (assoc username req))
             (reply-list '()))
        (if username
            (let ((user-data (assoc (cdr username) staff-data)))
              (rad-log L_INFO (format #f "~A" user-data))
              (if user-data
                  (call-with-current-continuation
                   (lambda (xx)
                     (for-each
                      (lambda (pair)
                        (cond
                         ((avl-match? req (car pair))
                          (set! reply-list (avl-merge
                                            reply-list
                                            (cdr pair)))
                          (xx #t))))
                      (cdr user-data))
                     #f)))))
        (cons
         #t
         reply-list)))

To trigger the invocation of the Scheme authentication function, assign its name to Scheme-Procedure attribute in RHS of a corresponding `raddb/users' profile. E.g.:

    DEFAULT Auth-Type = SQL
            Scheme-Procedure = "auth"

Accounting with Scheme

The Scheme accounting procedure must be declared as follows:

Function Template: acct-function-name request-list
Its arguments are:
request-list
The list of A/V pairs from the incoming request

The function must return a boolean value. The accounting succeeds only if it returned #t.

Here is an example of Scheme accounting function. The function dumps the contents of the incoming request to a file:

    (define radius-acct-file "/var/log/acct/radius")

    (define (acct req)
      (call-with-output-file radius-acct-file
        (lambda (port)
          (for-each (lambda (pair)
                      (display (car pair) port)
                      (display "=" port)
                      (display (cdr pair) port)
                      (newline port))
                    req)
          (newline port)))
      #t)

Radius-Specific Functions

Scheme Function: avl-delete av-list attr
Delete from av-list the pairs with attribute attr.

Scheme Function: avl-merge dst src
Merge src into dst.

Scheme Function: avl-match? target list
Return #t if all pairs from list are present in target.

Scheme Function: rad-dict-name->attr name
Return a dictionary entry for the given attribute name or #f if no such name was found in the dictionary.

A dictionary entry is a list in the form:

Scheme List: dict-entry name-string attr-number type-number vendor
Where
name-string
The attribute name
value-number
The attribute number
type-number
The attribute type
vendor
is the vendor PEC, if the attribute is a Vendor-Specific one, or #f otherwise.

Scheme Function: rad-dict-value->name attr value
Returns a dictionary name of the given value for an integer-type attribute attr. attr can be either an attribute number or its dictionary name.

Scheme Function: rad-dict-name->value attr value
Convert a symbolic attribute value name into its integer representation

Scheme Function: rad-dict-pec->vendor pec
Convert PEC to the vendor name

Scheme Function: rad-log-open prio
Open radius logging to the severity level prio.

Scheme Function: rad-log-close
Close radius logging channel open by a previous call to rad-log-open.

Scheme Function: rad-rewrite-execute-string string
Interpret string as an invocation of a function in Rewrite language and execute it.

Return value: return of the corresponding Rewrite call, translated to the Scheme data type.

Scheme Function: rad-rewrite-execute arglist
Execute a Rewrite language function. (car arglist) is interpreted as a name of the Rewrite function to execute, and (cdr arglist) as a list of arguments to be passed to it.

Return value: return of the corresponding Rewrite call, translated to the Scheme data type.

Scheme Function: rad-openlog ident option facility
Scheme interface to the system openlog() call.

Scheme Function: rad-syslog prio text
Scheme interface to the system syslog() call.

Scheme Function: rad-closelog
Scheme interface to the system closelog() call.

Scheme Function: rad-utmp-putent status delay list radutmp_file radwtmp_file
Write the supplied data into the radutmp file. If RADWTMP_FILE is not nil the constructed entry is also appended to WTMP_FILE. list is:

Scheme List: utmp-entry user-name orig-name port-id port-type session-id caller-id framed-ip nas-ip proto

user-name
The user name
orig-name
Original user name from the request
port-id
The value of NAS-Port-Id attribute.
port-type
A number or character indicating the port type.
session-id
Session ID.
caller-id
The value of Calling-Station-Id attribute from the request.
framed-ip
The framed IP address assigned to the user.
nas-ip
The NAS IP address.
proto
Number or character indicating type of the connection.

Utility Programs

    Controlling who and when was logged in
  • Radwho: Show who is logged in by radius now.
  • Radlast: Show the history of logins by radius.
  • Raduse: Monitor the users in real time. Maintenance commands
  • Radzap: Modify the login records.
  • Radgrep: Quickly find the login record.
  • Radping: Ping the remote machine by the username.
  • Radauth: Check if a user can be authenticated.
  • Radctl: Radctl monitor.
  • Builddbm: Create DBM version of the `raddb/users' file. Guile interface
  • Radscm: A guile interface to radius functions.

Radwho

Radwho displays the list of users currently logged in by the Radius server.

Default output information is made compatible with that of the standard @UNIX{} finger(1) utility. For each user the following information is displayed: login name, name, connection protocol, NAS port, login date, NAS name, assigned IP address or corresponding network name.

When used with -l option, the long output format is used. In this format the following information is output:

`Login '
Login name of the user
`SessionID '
Unique session ID assigned by the terminal server.
`Proto '
Connection prototype.
`Port '
Port number
`When '
Login date and time
`From '
The name of NAS that accepted the connection.
`Location '
Framed IP address or the corresponding network name.
`Caller '
Caller station ID ad reported by the NAS.
`Duration '
Duration of the session.
  • Options: Command line options.

Radwho Command Line Options

The following command line options can be used to modify the behavior of the program:

-A
--all
Display the information about logged-out users as well. The logged-out users are shown with Proto field set to HUP.
-c
--calling-id
Display the calling station ID in the second column.
-d NAME
--directory NAME
Set the radius configuration directory name.
-D {short|abbr|full}
--date-formap {short|abbr|full}
Set the date representation. By default dates are output as DOW HH:MM, where DOW means the day of week abbreviation, HH and MM mean hours and minutes respectively. This corresponds to option -D short. Other available formats are:
`abbr '
Abbreviated date: MM/DD HH:MM, where MM is a two-digit month number, DD -- a two-digit day of month.
`full '
Full data output, like this:
    Mon Dec 18 12:29:38 EET 2000
-e STRING
--empty STRING
Display any empty field as STRING. This is useful when the output of radwho is fed to some analyzing program, as it helps to keep the same number of columns on each line of output.
-F
--finger
Start in fingerd mode. In this mode radwho emulates the behavior of fingerd(8) utility. Use this option if starting radwho from the /etc/inetd.conf line like this:
    finger stream tcp nowait nobody /usr/sbin/radwho radwho -fL
This mode is also enabled by default if radwho notices that its name (argv[0]) is `fingerd' or `in.fingerd'.
-H
--no-header
Don't display header line.
-i
--session-id
Display session ID instead of GECOS in the second column.
-I {smart|ip|nodomain}
--ip-format {smart|ip|nodomain}
Change IP address representation. The meaning of the argument is as follows:
`smart '
Select the best representation. The following rules apply:
  1. For a NAS use its short name from `naslist'. If there is no short name, use its long name. If there is no long name either, go to 2.
  2. Resolve IP address to FQDN.
  3. If the IP cannot be resolved, use dotted-quad representation of the IP
`ip '
Display IP in dotted-quad form.
`nodomain '
If the IP can be resolved to a fully qualified domain name, use the hostname part of it, i.e. any characters up to the first dot.
-u
--local-also
Display information about local users from the system `utmp' file. May prove useful when running radwho as a finger daemon.
-n
--no-resolve
Do not resolve IP address. It is a synonym for -I ip.
-o FORMAT
--format FORMAT
Select customized output format. This can also be changed by setting the value of environment variable RADWHO_FORMAT. The format string is a comma-separated list of format specifications in one of the following forms:
field
Output field with its default width, heading and alignment. The field names and corresponding default values are discussed in detail below.
field:width
Output field, use column width width. If width starts with `+', the field will be right-aligned, if it starts with `-', the field will be left-aligned. Otherwise the default alignment will be used
field:width:heading
The same as above, but also supplies the heading for the column
The field names are:
login
Login name
orig
Original login name as supplied with the request.
port
NAS port number
sid
The Session ID
nas
The NAS name or IP address.
ip
Framed IP address assigned to the user, if it is provided framed service.
proto
Connection protocol. Its possible values are:
  • `PPP' for a point-to-point link
  • `SLIP' for a SLIP link
  • `HUP' for closed session
  • `shell' for shell user
date
Date/time when the session started
delay
Delay time section Acct-Delay-Time.
type
Entry type in decimal.
ptype
Port type. This is one of the following letters:
Type | Meaning
`L' | Local connection
`R' | Rlogin connection
`S' | SLIP connection
`C' | CSLIP connection
`P' | PPP connection
`A' | Auto PPP connection
`E' | Telnet session
`T' | "Clear TCP" connection
`U' | TCP login service
`!' Console session
`X' | Shell
time
Total time of the session duration.
clid
The calling station ID.
uname
The GECOS field from local /etc/passwd, corresponding to the login name. If the user does not have a local account, his login name is output.
-s
--secure
Run in secure mode. Queries without a user name are rejected.

Radlast

The radlast utility lists sessions of specified users, NASes, NAS ports and hosts, in reverse time order. By default, each line of output contains the login name, NAS short name and port number from where the session was conducted, host IP address or name, the start and stop times for the session, and the duration of the session. If the session is still continuing, radlast will so indicate.

When specified the -l option, radlast produces long output. It includes following fields:

  • login name
  • NAS short name
  • port number
  • prototype
  • port type
  • Session ID
  • Caller ID
  • Framed IP address
  • Session Start Time
  • Session Stop Time
  • Duration of the Session
  • Options: Command line options.

Radlast Command Line Options

Use following command line options to control the behavior of radlast utility:

-number
-c number
--count number
When given this option radlast will output at most this many lines of information.
-f
--file name
Read the specified file instead of the default `/var/log/radwtmp'.
-h hostname
--host hostname
Report the logins from given host. Host can be either a name or a "dotted quad" internet address.
-n shortname
--nas shortname
Report the logins from given Network Access Server (NAS).
-l
--long-format
"Long" output format. Report all the information stored in `radwtmp' file.
-p number
--port number
Report the logins on a given port. The port may be specified either fully or abbreviated, e.g. radlast -p 3 or radlast -p S03.
-s
--show-seconds
Report the duration of the login session in seconds instead of the default days, hours and minutes.
-t
The same as -p. This flag is provided for compatibility with last(1).
-w
--wide
Widen the duration field to show seconds as well as the default days, hours and minutes.

If multiple arguments are given, the logical OR operation between them is assumed, i.e. the information selected by each argument is printed. This, however, does not apply to -c option. This option is always combined with the rest of command line by logical AND.

The pseudo-user `~reboot' logs in on every reboot of network access server.

If radlast is interrupted, it indicates to what date the search was progressed.

Raduse

The raduse utility shows the usage of dialup lines in the realtime.

  • Display: What is displayed.
  • Options: Command line options modify the default display.
  • Commands: Interactive mode commands.

Display

At the top of output the summary information is displayed. It consists of two lines. First line shows the statistic collection uptime and current date/time. Second line shows total number of lines, number of active lines, number of idle (inactive) lines and load percentage.

The dialup statistics is displayed in the area below. For each dialup line three lines of data are shown.

First line shows the network access server name, port number on that server, number of logins registered on this line, status of the line, amount of time the line keeps the current status, and date and time where the line has switched to the current status.

If the line is currently active, the status field displays login name of the user logged in on this line. If the line is inactive, the word `[Idle]' is displayed.

Second and third lines display active and idle usage summary. They show following data: total time the line is in the given state, maximum amount of time in this state, and starting date and time when maximum duration was perceived.

The example of default display:

    uptime    90+20:35         Sun Dec 17 12:21
    235 lines,  71 active, 164 idle. Pool load 0.30

    max          001  2796 [idle]                 00:05 Sun Dec 17 12:16
                 43+00:17     1+22:39 Fri Sep 22 18:04 - 16:44
                 47+20:22       06:25 Thu Oct 05 02:24 - 08:50
    max          002  2877 [idle]                 00:09 Sun Dec 17 12:11
                 41+06:56       10:55 Sat Oct 28 21:20 - 07:15
                 49+13:35       05:32 Mon Oct 02 00:33 - 06:05
    max          003  3000 [idle]                 00:08 Sun Dec 17 12:12
                 39+14:42       19:44 Thu Nov 02 14:52 - 10:36
                 50+11:22       07:29 Wed Oct 11 23:30 - 06:59
    max          004  2829 jsmith                 00:05 Sun Dec 17 12:15
                 41+21:11     1+00:04 Sun Sep 24 12:17 - 12:21
                 48+23:28       04:51 Sat Oct 07 03:42 - 08:33
    max          005  2913 gray                   00:41 Sun Dec 17 11:40
                 40+12:01       15:24 Mon Dec 11 19:18 - 10:43
                 50+08:03       11:58 Wed Nov 29 13:43 - 01:41
    max          006  3014 roland                 00:39 Sun Dec 17 11:41
                 42+02:10       22:28 Sun Sep 24 13:46 - 12:15
                 48+17:39       05:30 Fri Nov 24 01:57 - 07:28
    max          007  2937 [idle]                 00:06 Sun Dec 17 12:15

This default display can be altered using command line options or interactive commands

Raduse Command Line Options

The following options modify the behavior of raduse:

-b
--brief
Start up in brief mode. In this mode only first line of information for each dialup line is displayed.
-d count
--display count
Show only count displays, then exit. A display is considered to be one update of the screen.
-D
--dump
Dump the statistics database to the standard output and then exit. This is for debugging purposes only.
-I
--no-idle-lines
Do not display idle lines. By default raduse displays all dialup lines.
-i
--interactive
Use interactive mode. In this mode any input is immediately read for processing. section Raduse Interactive Commands section for the description of commands usable in interactive mode. After processing each command the screen is updated immediately, no matter was the command understood or not. This mode is the default when the standard output is an intelligent terminal.
-n
--no-interactive
Use non-interactive mode.
-s num
--delay num
Specify delay in seconds between screen updates.
-w
--widen
Widen the time display fields to show the seconds.
-l
--list-nas
List the names and IP numbers of network access servers and then exit.
-h
--help
Display short usage summary.

Raduse Interactive Commands

The following commands are understood when raduse is in interactive mode. Some commands require an argument. Such commands are followed by the word arg. When raduse gets such command it displays a prompt and waits for user to enter the necessary data.

After processing each command the screen is updated immediately, no matter was the command understood or not.

RET
Refresh the screen immediately
SPC
Refresh the screen immediately
C-l
Clear and redraw the display.
^
(Caret) go to the first page.
b
Toggle brief display mode.
C-b
Move one page backwards.
C-f
Move one page forwards.
i
Toggle idle line display on or off.
j
Move one line forwards.
k
Move one line backwards.
G
$
Move to the last page.
q
Quit the program
s arg
Change the number of seconds to delay between screen updates.
t arg
Display lines on a given Network Access Servers. The user is prompted to input the NAS names. The names should be separated by whitespace. The word `all' returns to display of all NAS lines.

Radzap

radzap searches the Radius accounting database for matching login records and closes them.

At least one of -n, -p options or username must be specified. If they are used in conjunction, they are taken as if joined by logical AND operation.

`radzap' operates in two modes: silent and confirm. The silent mode is enabled by default. When run in this mode, radzap deletes every record that matched the search conditions given.

In confirm mode `radzap' will ask for a confirmation before zapping each matching record. Every line beginning with a `y' is taken as positive response, otherwise it is taken as negative response.

The confirm mode is toggled by the command line option -c.

Syntax

    radzap [options] [username]

Options are:

-c
--confirm
Enable confirm mode.
-q
--quiet
Disable confirm mode.
-h
--help
Display short help summary and exit.
-n NAME
--nas NAME
Specify NAS name to zap user from.
-p PORT
--port PORT
Specify the port number of the session to be zapped. The port number can be specified either in its full form, i.e radzap -p S02 or in its short form, like radzap -p 2.

Radgrep

This utility allows to quickly lookup the user in the radius accounting database using a regular expression match.

radgrep scans the output of radwho utility and outputs only the lines that match given regular expressions.

Syntax

radgrep accepts two sets of options separated by `--' (double-dash) sign. First subset is passed as command line to radwho utility. The second one is passed to grep.

Radping

This utility is a shell program that determines the user's framed IP address and runs ping on that address.

Syntax

    radping username
    radping -c calling-station-id

The second way of invoking the program allows to use calling station ID in order to indicate the user.

Radauth

The radauth utility sends the Radius server Access-Request packet and displays the result it gets. It can be used to test the configuration files. The usage is:

    raduse [-v] username password

The -v or --verbose option forces radauth to be verbose on output.

If you enter `.' (dot) instead of the password, the program will disable echoing on the screen, prompt you to enter the password, and turn the echoing on again, thus preventing the password from being compromised.

The program determines which Radius server to use, the authentication port number and shared secret following the procedure common for all client scripts (see section Client Configuration).

Radctl

Radctl is a control interface to radiusd daemon. It allows user running it to query radiusd about various aspects of its work and issue administrative commands to it.

    radctl -s command [args]

Where command is a command telling radctl which actions to take, and args are optional arguments to the command. Only one command can be specified per invocation.

The valid commands are as follows:

start [args]
If radiusd is not running already, it is started. When present, args are passed as the command line to the server.
stop
Stops running radiusd.
restart [args]
Stops the server and then starts it again. When present, args are passed as the command line to the server.
reload
Causes running radiusd server to re-read its configuration files.
dumpdb
Tells radiusd to dump its user hash table into the file `radlog/radius.parse'. This can be used for debugging configuration files.
status
radiusd reports its memory usage statistics. The information is logged under Info log level.
which
Reports the information about the running copy of radiusd.

Builddbm

Usage

Builddbm converts the plaintext Radius users database into DBM files. Some versions of Radius daemon have used this to speed up the access to the users database.

However, with GNU Radius things go the other way around. The server reads entire plaintext database, converts it into internal form and stores into hash table which provides for fast access. Actually, using DBM version of the users database slows down the access unless the machine which runs Radius daemon is short of address space for the daemon to store the users database into.

Syntax

When used without arguments, builddbm utility attempts to convert file `raddb/users' into `raddb/users.db' or `raddb/users.pag', `raddb/users.dir' pair, depending on the version of DBM library used.

If used with one argument, the argument is taken as the name of the plaintext database file to operate upon.

Use the following command line options to modify the operation of buildbm:

-d dir
Specifies alternate directory for the Radius configuration files. This defaults to `/usr/local/etc/raddb'.
-h
Outputs short usage summary and exits with 0 exit code.

Radscm: A guile interface to radius functions.

Radscm is a Scheme interpreter based on Guile with the addition of special functions and variables for communicating with radiusd. This chapter concentrates on the special features provided by radscm. Please refer to Guile documentation for information about Scheme and Guile See section `Overview' in The Guile Reference Manual.

Variables

Variable: %raddb-path
A path to radius configuration directory.

Function: rad-server-list
A list of radius servers. Each element of the list is:

    (list ID-STR HOST-STR SECRET-STR AUTH-NUM ACCT-NUM CNTL-NUM)

where:

ID-STR | Server ID,
HOST-STR | Server hostname or IP address,
SECRET-STR | Shared secret key to use,
AUTH-NUM | Authentication port number,
ACCT-NUM | Accounting port number,
CNTL-NUM | Control channel port number.

Thus, each entry can be used as an argument to rad-client-set-server or rad-client-add-server.

Functions

Function: rad-send-internal PORT-NUMBER CODE-NUMBER PAIR-LIST
Sends the request to currently selected server. Arguments are:

PORT-NUMBER
Port number to use. These values are allowed:
0 | Authentication port,
1 | Accounting port,
2 | Control port.
The actual port numbers are those configured for the given server.
CODE-NUMBER
Request code.
PAIR-LIST
List of Attribute-value pairs. Each pair is either
            (cons ATTR-NAME-STR VALUE)
or
            (cons ATTR-NUMBER VALUE)

Return:

On success

            (list RETURN-CODE-NUMBER PAIR-LIST)

On failure:

            '()

Function: rad-send PORT-NUMBER CODE-NUMBER PAIR-LIST . VERBOSE
Sends a radius request. Actually it does the same work as rad-send-internal but if VERBOSE is specified, the verbose report about interaction with the radius server is printed.

Function: rad-client-list-servers
List currently configured servers. Two columns for each server are displayed: Server ID and IP address.

Function: rad-get-server
Returns the ID of the currently selected server.

Function: rad-client-set-server LIST
Selects for use the server described by LIST. A LIST should be:

    (list ID-STR HOST-STR SECRET-STR AUTH-NUM ACCT-NUM CNTL-NUM)

where:

ID-STR | Server ID,
HOST-STR | Server hostname or IP address,
SECRET-STR | Shared secret key to use,
AUTH-NUM | Authentication port number,
ACCT-NUM | Accounting port number,
CNTL-NUM | Control channel port number.

Function: rad-client-add-server LIST
Adds the server described by LIST to the list of active servers. A LIST should be:

    (list ID-STR HOST-STR SECRET-STR AUTH-NUM ACCT-NUM CNTL-NUM)

where:

ID-STR | Server ID,
HOST-STR | Server hostname or IP address,
SECRET-STR | Shared secret key to use,
AUTH-NUM | Authentication port number,
ACCT-NUM | Accounting port number,
CNTL-NUM | Control channel port number.

Function: rad-read-no-echo PROMPT-STR
Prints the given PROMPT-STR, disables echoing, reads a string up to the next newline character, restores echoing and returns the string entered. This is the interface to the C getpass(3) function.

Function: rad-client-source-ip IP-STR
Sets the IP address to be used as source. IP-STR can be either an IP address in dotted-quad form or a hostname.

Function: rad-client-timeout NUMBER
Sets the timeout for waiting to the server reply.

Function: rad-client-retry NUMBER
Sets the number of retries for sending requests to a radius server.

Function: rad-format-code DEST-BOOL CODE-NUMBER
Format a radius reply code into a human-readable form. DEST-BOOL has the same meaning as in format.

Function: rad-format-pair DEST-BOOL PAIR
Format a radius attribute/value pair for output. DEST-BOOL has the same meaning as in format. PAIR is either
                    (cons NAME-STR VALUE)

or

                    (cons ATTR-NUMBER VALUE)

where VALUE may be of any type appropriate for the given attribute.

Function: rad-print-pairs DEST-BOOL PAIR-LIST
Output the radius attribute/value pairs from the PAIR-LIST. DEST-BOOL has the same meaning as in format. PAIR-LIST is a list of pairs in the form

                    (cons NAME-STR VALUE)

or

                    (cons ATTR-NUMBER VALUE)

where VALUE may be of any type appropriate for the given attribute.

All "Reply-Message" pairs from the list are concatenated and displayed as one.

Function: rad-format-reply-msg PAIR-LIST . TEXT
Concatenate and print text from all "Reply-Message" pairs from the PAIR-LIST. If TEXT is specified, it is printed before the concatenated text.

Function: rad-list-servers
For each server from rad-server-list print its ID and hostname or IP address.

Function: rad-select-server ID-STR
Select the server identified by ID-STR as a current server. The server data are looked up in rad-server-list variable.

Function: rad-add-server ID-STR
Add the server identified by ID-STR to the list of current servers. The server data are looked up in rad-server-list variable.

Client Package

Beside the radius server and accompanying utilities, GNU Radius provides a set of utilities to be used as radius clients.

Following sections describe in detail the parts of the radius client package.

  • config: Configuration file is common for all client utilities.
  • radsession: Send arbitrary requests to radius server.
  • nas.scm: A NAS implementation for GNU/Linux machines.
  • pam_radius.so: A PAM module for authentication via radius.

Client Configuration

All programs from the client package share the same configuration file: `raddb/client.conf'. The file uses simple line-oriented syntax. Empty lines are ignored, the `#' introduces an end-of-line comment.

The source IP address is introduced with source_ip statement. Its syntax is:

    source_ip ip-addr

where ip-addr must be the IP address in "dotted-quad" notation.

The radius server where to send the requests to is introduced with server statement:

    server name ip-addr secret auth-port acct-port

Its parts are:

name
The server name. It is reserved for further use.
ip-addr
The server IP address.
secret
The shared secret to be used when sending requests to this server
auth-port
Authentication port number.
acct-port
Accounting port number.

If several server statement are present, they are tried in turn until any of them replies to the request.

The amount of time a client program waits for the reply from a server is configured using timeout statement:

    timepout number

If the program does not receive any response within number seconds, it assumes the server does not respond and either retries the transmission or tries next available server. Number of retries is set with retry statement:

    retry number

The example of `raddb/client.conf' follows:

    server first 10.11.10.1 secret 1645 1646
    server second 10.11.10.1 secret 1645 1646
    source_ip 127.0.0.1
    timeout 3
    retry 5

radsession

radsession is a Guile script that sends authentication and accounting requests to the radius server. To invoke the script, run

    radsession options action

Possible actions are:

--auth
Send authentication request.
--start
Send accounting start request.
--stop
Send accounting stop request.

Options determine the contents of the request's pairlist. They are:

-l STRING
--login STRING
Set login name.
-p STRING
--passwd STRING
Set password.
-n IP
--nas IP
Set the value of NAS-IP-Address attribute.
-s STRING
--sid STRING
Set the session id (Acct-Session-Id attribute).
-P NUMBER
--port NUMBER
Set the port number (NAS-Port-Id attribute).
-h
--help
Print short usage message and exit.
-v
--verbose
Verbosely list the contents of the received reply.

nas.scm

nas.scm is a Guile program that allows to convert a GNU/Linux box into a NAS. It requires Guile version 1.4 or better and ppp version 2.3.7 or better.

To use it, you will basically need to do the following:

  1. Create links:
        ln -s libexec/nas.scm /etc/ppp/ip-up
    ln -s libexec/nas.scm /etc/ppp/ip-down
    Here, libexec denotes the location of your libexec directory, where nas.scm is installed. If not overridden at configure time, it defaults to `prefix/libexec'. These links assure the ppp will invoke nas.scm when the user's session starts and ends, thus giving it a possibility to send accounting requests.
  2. Configure file `raddb/client.conf'
  3. Edit file `raddb/nas.rc'. The supplied `nas.rc' template is tailored to work in most environments. The only variables you may need to change are: nas-log-facility, specifying the syslog facility to be used for logging and pppd-args, keeping the arguments to be given to ppp.
  4. Configure your `/etc/inittab' and getty. For example, if you use mgetty, then the `inittab' entries for dial-up lines will look like:
        d0:345:respawn:/sbin/mgetty ttyS0 vt100
    d1:345:respawn:/sbin/mgetty ttyS1 vt100
    ...
    The mgetty's `login.config' will then contain the following line:
        *       -       -       /usr/local/libexec/nas.scm
    If you use agetty, then the `inittab' will contain (with the long lines split for readability):
        d0:345:respawn:/sbin/agetty -mt60 \
       -l /usr/local/libexec/nas.scm 38400,19200,9600 \
       ttyS0 vt100
    d1:345:respawn:/sbin/agetty -mt60 \
       -l /usr/local/libexec/nas.scm 38400,19200,9600 \
       ttyS1 vt100
    ...

pam_radius.so

pam_radius.so is a PAM module for radius authentication. The module understands following command line options:

audit
Enable audit information.
debug[=level]
Enable debugging information. The higher level is, the more debugging info is output. When omitted, level defaults to 100. Please note, that debugging levels equal to or greater than 10 compromise users' passwords, so use them sparingly.
use_authtok
Use authentication token passed from the previous module in stack.
confdir=path
Look for configuration files in path. Default is `$sysconfdir/etc/raddb'.
service_type=type
Add Service-Type=type to the authentication request. type must be a valid value, described in dictionary file.

pam_radius.so module logs its messages under LOG_AUTH syslog facility.

Attribute List

The following sections describe the most frequently used RADIUS attributes. Each attribute is described as follows:

ATTRIBUTE name value type
Users: | user-flags
Hints: | hints-flags
Huntgroups: | huntgroup-flags
Additivity: | additivity
Proxy propagated: | prop

These values have the following meaning:

name
The attribute name.
value
The attribute number.
type
The attribute type.
user-flags
Syntax flags defining in which part of `raddb/users' entry this attribute may be used. The flags consist of two letters: `L' means the attribute can be used in LHS, `R' means it can be used in RHS.
hints-flags
Syntax flags defining in which part of `raddb/hints' entry this attribute may be used.
huntgroup-flags
Syntax flags defining in which part of `raddb/huntgroups' entry this attribute may be used.
additivity
Additivity of the attribute determines what happens if a rule attempts to add to the pair list the attribute, which is already present in this list. Depending on its value, the actions of the server are:
Append
New attribute is appended to the end of the list.
Replace
New attribute replaces the old.
Drop
New attribute is dropped. The old one remains in the list.
prop
Is the attribute propagated back to the NAS if the server works in proxy mode.

The value of N/A in any of this fields signifies "not applicable".

  • Authentication Attributes
  • Accounting Attributes
  • Radius Internal Attributes

Authentication Attributes

These are the attributes the NAS uses in authentication packets and expects to get back in authentication replies. These can be used in matching rules.

  • User-Name
  • Password
  • CHAP-Password
  • NAS-IP-Address
  • NAS-Port-Id
  • Service-Type
  • Framed-Protocol
  • Framed-IP-Address
  • Framed-IP-Netmask
  • Framed-Routing
  • Framed-MTU
  • Framed-Compression
  • Reply-Message
  • Callback-Number
  • Callback-Id
  • Framed-Route
  • State
  • Class
  • Vendor-Specific
  • Session-Timeout
  • Idle-Timeout
  • Termination-Action
  • Called-Station-Id
  • Calling-Station-Id
  • NAS-Identifier
  • NAS-Port-Type

User-Name

ATTRIBUTE User-Name 1 string
Users: | LR
Hints: | -R
Huntgroups: | LR
Additivity: | Replace
Proxy propagated: | Yes

This Attribute indicates the name of the user to be authenticated or accounted. It is used in Access-Request and Accounting attributes. The length of the username is usually limited by some arbitrary value. By default, Radius supports usernames up to 32 characters long. This value can be modified by redefining RUT_USERNAME macro in include/radutmp.h file in the distribution directory and recompiling the program.

Some NASes have peculiarities about sending long usernames. For example, Specialix Jetstream 8500 24 port access server inserts a `/' character after the 10th character if the username is longer than 10 characters. In such cases, we recommend to apply rewrite functions in order to bring username to its "normal" form (see section Rewrite functions -- `raddb/rewrite').

Password

ATTRIBUTE Password 2 string
Users: | L-
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | No

This Password attribute indicates the password of the user to be authenticated, or the user's input following an Access-Challenge. It is only used in Access-Request packets.

On transmission, the password is hidden. The password is first padded at the end with nulls to a multiple of 16 octets. A one- way MD5 hash is calculated over a stream of octets consisting of the shared secret followed by the Request Authenticator. This value is XORed with the first 16 octet segment of the password and placed in the first 16 octets of the String field of the Password Attribute.

If the password is longer than 16 characters, a second one-way MD5 hash is calculated over a stream of octets consisting of the shared secret followed by the result of the first xor. That hash is XORed with the second 16 octet segment of the password and placed in the second 16 octets of the String field of the Password Attribute.

If necessary, this operation is repeated, with each xor result being used along with the shared secret to generate the next hash to xor the next segment of the password, to no more than 128 characters.

CHAP-Password

ATTRIBUTE CHAP-Password 3 string
Users: | L-
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | No

This Attribute indicates the response value provided by a PPP Challenge-Handshake Authentication Protocol (CHAP) user in response to the challenge. It is only used in Access-Request packets.

The CHAP challenge value is found in the CHAP-Challenge Attribute (60) if present in the packet, otherwise in the Request Authenticator field.

NAS-IP-Address

ATTRIBUTE NAS-IP-Address 4 ipaddr
Users: | L-
Hints: | -R
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

This Attribute indicates the identifying IP address of the NAS which is requesting authentication of the user. It is only used in Access-Request packets. Each Access-Request packet should contain either NAS-IP-Address or NAS-Identifier attribute section NAS-Identifier.

NAS-Port-Id

ATTRIBUTE NAS-Port-Id 5 integer
Users: | LR
Hints: | -R
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

This attribute indicates the physical port number of the NAS which is authenticating the user. It is only used in Access-Request packets. Note that this is using "port" in its sense of a physical connection on the NAS, not in the sense of a TCP or UDP port number.

Some NASes try to encode various information in the NAS-Port-Id attribute value. For example MAX Ascend terminal server constructs NAS-Port-Id concatenating line type (one-digit), line number (two-digits), and the channel number (two-digits) thus producing a 5-digit port number. In order to "normalize" such encoded port numbers we recommend to use a rewrite function (see section Rewrite functions -- `raddb/rewrite'). A rewrite function for MAX Ascend servers is provided in the distribution.

Service-Type

ATTRIBUTE Service-Type 6 integer
Users: | LR
Hints: | -R
Huntgroups: | LR
Additivity: | Replace
Proxy propagated: | Yes
    VALUE      Service-Type      Login-User           1
    VALUE      Service-Type      Framed-User          2
    VALUE      Service-Type      Callback-Login-User  3
    VALUE      Service-Type      Callback-Framed-User 4
    VALUE      Service-Type      Outbound-User        5
    VALUE      Service-Type      Administrative-User  6
    VALUE      Service-Type      NAS-Prompt-User      7
    VALUE      Service-Type      Authenticate-Only    8
    VALUE      Service-Type      Call-Check           10

This attribute indicates the type of service the user has requested, or the type of service to be provided. It may be used in both Access-Request and Access-Accept packets.

When used in an Access-Request the Service type represents a hint to the Radius server that the NAS has reason to believe the user would prefer the kind of service indicated.

When used in an Access-Accept, the Service type is an indication to the NAS that the user must be provided this type of service.

The meaning of various service-types is as follows:

Login-User
The user should be connected to a host.
Framed-User
A Framed Protocol should be started for the User, such as PPP or SLIP. The Framed-IP-Address attribute (see section Framed-IP-Address) would supply the IP address to be used.
Callback-Login-User
The user should be disconnected and called back, then connected to a host.
Callback-Framed-User
The user should be disconnected and called back, then a Framed Protocol should be started for the User, such as PPP or SLIP.
Outbound-User
The user should be granted access to outgoing devices.
Administrative-User
The user should be granted access to the administrative interface to the NAS from which privileged commands can be executed.
NAS-Prompt
The user should be provided a command prompt on the NAS from which non-privileged commands can be executed.
Authenticate-Only
Only Authentication is requested, and no authorization information needs to be returned in the Access-Accept
Call-Check
Callback-NAS-Prompt
The user should be disconnected and called back, then provided a command prompt on the NAS from which non-privileged commands can be executed.

Framed-Protocol

ATTRIBUTE Framed-Protocol 7 integer
Users: | LR
Hints: | -R
Huntgroups: | LR
Additivity: | Replace
Proxy propagated: | Yes
    VALUE      Framed-Protocol   PPP                  1
    VALUE      Framed-Protocol   SLIP                 2

This Attribute indicates the framing to be used for framed access. It may be used in both Access-Request and Access-Accept packets.

Framed-IP-Address

ATTRIBUTE Framed-IP-Address 8 ipaddr
Users: | LR
Hints: | -R
Huntgroups: | LR
Additivity: | Replace
Proxy propagated: | No

This Attribute indicates the address to be configured for the user. It may be used in Access-Accept packets. It may be used in an Access-Request packet as a hint by the NAS to the server that it would prefer that address, but the server is not required to honor the hint.

The value 0xFFFFFFFF (255.255.255.255) indicates that the NAS should allow the user to select an address. The value 0xFFFFFFFE (255.255.255.254) indicates that the NAS should select an address for the user (e.g. assigned from a pool of addresses kept by the NAS). Other valid values indicate that the NAS should use that value as the user's IP address.

When used in a RHS, the value of this attribute can optionally be followed by a plus sign. This usage means that the value of NAS-Port-Id must be added to this IP address before replying. For example

            Framed-IP-Address = 10.10.0.1+

Also section Add-Port-To-IP-Address.

Framed-IP-Netmask

ATTRIBUTE Framed-IP-Netmask 9 ipaddr
Users: | LR
Hints: | -R
Huntgroups: | LR
Additivity: | Replace
Proxy propagated: | No

This Attribute indicates the IP netmask to be configured for the user when the user is a router to a network. It may be used in Access-Accept packets. It may be used in an Access-Request packet as a hint by the NAS to the server that it would prefer that netmask, but the server is not required to honor the hint.

Framed-Routing

ATTRIBUTE Framed-Routing 10 integer
Users: | -R
Hints: | -R
Huntgroups: | -R
Additivity: | Replace
Proxy propagated: | No
    VALUE      Framed-Routing    None                 0
    VALUE      Framed-Routing    Broadcast            1
    VALUE      Framed-Routing    Listen               2
    VALUE      Framed-Routing    Broadcast-Listen     3

This Attribute indicates the routing method for the user, when the user is a router to a network. It is only used in Access-Accept packets.

Framed-MTU

ATTRIBUTE Framed-MTU 12 integer
Users: | LR
Hints: | -R
Huntgroups: | -R
Additivity: | Replace
Proxy propagated: | Yes

This Attribute indicates the Maximum Transmission Unit to be configured for the user, when it is not negotiated by some other means (such as PPP). It is only used in Access-Accept packets.

Framed-Compression

ATTRIBUTE Framed-Compression 13 integer
Users: | LR
Hints: | -R
Huntgroups: | LR
Additivity: | Replace
Proxy propagated: | Yes
    VALUE      Framed-Compression  None                 0
    VALUE      Framed-Compression  Van-Jacobson-TCP-IP  1

This Attribute indicates a compression protocol to be used for the link. It may be used in Access-Accept packets. It may be used in an Access-Request packet as a hint to the server that the NAS would prefer to use that compression, but the server is not required to honor the hint.

More than one compression protocol Attribute may be sent. It is the responsibility of the NAS to apply the proper compression protocol to appropriate link traffic.

Reply-Message

ATTRIBUTE Reply-Message 18 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Append
Proxy propagated: | Yes

This Attribute indicates text which may be displayed to the user.

When used in an Access-Accept, it is the success message.

When used in an Access-Reject, it is the failure message. It may indicate a dialog message to prompt the user before another Access-Request attempt.

When used in an Access-Challenge, it may indicate a dialog message to prompt the user for a response.

Multiple Reply-Message attributes may be included and if any are displayed, they must be displayed in the same order as they appear in the packet.

Callback-Number

ATTRIBUTE Callback-Number 19 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | No

This Attribute indicates a dialing string to be used for callback. It may be used in Access-Accept packets. It may be used in an Access-Request packet as a hint to the server that a Callback service is desired, but the server is not required to honor the hint.

Callback-Id

ATTRIBUTE Callback-Id 20 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | No

This Attribute indicates the name of a place to be called, to be interpreted by the NAS. It may be used in Access-Accept packets.

Framed-Route

ATTRIBUTE Framed-Route 22 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | No

This Attribute provides routing information to be configured for the user on the NAS. It is used in the Access-Accept packet and can appear multiple times.

State

ATTRIBUTE State 24 string
Users: | LR
Hints: | LR
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

This Attribute is available to be sent by the server to the client in an Access-Challenge and MUST be sent unmodified from the client to the server in the new Access-Request reply to that challenge, if any.

This Attribute is available to be sent by the server to the client in an Access-Accept that also includes a Termination-Action Attribute with the value of RADIUS-Request. If the NAS performs the Termination-Action by sending a new Access-Request upon termination of the current session, it MUST include the State attribute unchanged in that Access-Request.

In either usage, no interpretation by the client should be made. A packet may have only one State Attribute.

Class

ATTRIBUTE Class 25 string
Users: | LR
Hints: | LR
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

This Attribute is available to be sent by the server to the client in an Access-Accept and should be sent unmodified by the client to the accounting server as part of the Accounting-Request packet if accounting is supported.

Vendor-Specific

ATTRIBUTE Vendor-Specific 26 string
Users: | LR
Hints: | -R
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | No

This Attribute is available to allow vendors to support their own extended Attributes not suitable for general usage.

Session-Timeout

ATTRIBUTE Session-Timeout 27 integer
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | Yes

This Attribute sets the maximum number of seconds of service to be provided to the user before termination of the session or prompt. The server may send this attribute to the client in an Access-Accept or Access-Challenge.

Idle-Timeout

ATTRIBUTE Idle-Timeout 28 integer
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | Yes

This Attribute sets the maximum number of consecutive seconds of idle connection allowed to the user before termination of the session or prompt. The server may send this attribute to the client in an Access-Accept or Access-Challenge.

Termination-Action

ATTRIBUTE Termination-Action 29 integer
Users: | LR
Hints: | -R
Huntgroups: | -R
Additivity: | Replace
Proxy propagated: | No
    VALUE      Termination-Action  Default              0
    VALUE      Termination-Action  RADIUS-Request       1

This Attribute indicates what action the NAS should take when the specified service is completed. It is only used in Access-Accept packets.

Called-Station-Id

ATTRIBUTE Called-Station-Id 30 string
Users: | L-
Hints: | -R
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

This Attribute allows the NAS to send in the Access-Request packet the phone number that the user called, using Dialed Number Identification (DNIS) or similar technology. Note that this may be different from the phone number the call comes in on. It is only used in Access-Request packets.

Calling-Station-Id

ATTRIBUTE Calling-Station-Id 31 string
Users: | L-
Hints: | -R
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

This Attribute allows the NAS to send in the Access-Request packet the phone number that the call came from, using Automatic Number Identification (ANI) or similar technology. It is only used in Access-Request packets.

NAS-Identifier

ATTRIBUTE NAS-Identifier 32 string
Users: | L-
Hints: | -R
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

This Attribute contains a string identifying the NAS originating the Access-Request. It is only used in Access-Request packets. Either NAS-IP-Address or NAS-Identifier should be present in an Access-Request packet.

See section NAS-IP-Address.

NAS-Port-Type

ATTRIBUTE NAS-Port-Type 61 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | Append
Proxy propagated: | No
    VALUE      NAS-Port-Type     Async                0
    VALUE      NAS-Port-Type     Sync                 1
    VALUE      NAS-Port-Type     ISDN                 2
    VALUE      NAS-Port-Type     ISDN-V120            3
    VALUE      NAS-Port-Type     ISDN-V110            4

This Attribute indicates the type of the physical port of the NAS which is authenticating the user. It can be used instead of or in addition to the NAS-Port-Id section NAS-Port-Id attribute. It is only used in Access-Request packets. Either NAS-Port or NAS-Port-Type or both should be present in an Access-Request packet, if the NAS differentiates among its ports.

Accounting Attributes

These are attributes the NAS sends along with accounting requests. These attributes can not be used in matching rules.

  • Acct-Status-Type
  • Acct-Delay-Time
  • Acct-Input-Octets
  • Acct-Output-Octets
  • Acct-Session-Id
  • Acct-Authentic
  • Acct-Session-Time
  • Acct-Input-Packets
  • Acct-Output-Packets
  • Acct-Terminate-Cause

Acct-Status-Type

ATTRIBUTE Acct-Status-Type 40 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A
    VALUE           Acct-Status-Type        Start                   1
    VALUE           Acct-Status-Type        Stop                    2
    VALUE           Acct-Status-Type        Alive                   3
    VALUE           Acct-Status-Type        Accounting-On           7
    VALUE           Acct-Status-Type        Accounting-Off          8

This attribute indicates whether this Accounting-Request marks the beginning of the user service (Start) or the end (Stop).

It may also be used to mark the start of accounting (for example, upon booting) by specifying Accounting-On and to mark the end of accounting (for example, just before a scheduled reboot) by specifying Accounting-Off.

A special value Alive or Interim-Update indicates the packet that contains some additional data to the initial Start record or to the last Alive record.

Acct-Delay-Time

ATTRIBUTE Acct-Delay-Time 41 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A

This attribute indicates how many seconds the client has been trying to send this record for, and can be subtracted from the time of arrival on the server to find the approximate time of the event generating this Accounting-Request. (Network transit time is ignored.)

Acct-Input-Octets

ATTRIBUTE Acct-Input-Octets 42 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A

This attribute indicates how many octets have been received from the port over the course of this service being provided, and can only be present in Accounting-Request records where the Acct-Status-Type is set to Stop.

Acct-Output-Octets

ATTRIBUTE Acct-Output-Octets 43 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A

This attribute indicates how many octets have been sent to the port in the course of delivering this service, and can only be present in Accounting-Request records where the Acct-Status-Type is set to Stop.

Acct-Session-Id

ATTRIBUTE Acct-Session-Id 44 string
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A

This attribute is a unique Accounting ID to make it easy to match start and stop records in a log file. The start and stop records for a given session must have the same Acct-Session-Id. An Accounting-Request packet must have an Acct-Session-Id. An Access-Request packet may have an Acct-Session-Id; if it does, then the NAS must use the same Acct-Session-Id in the Accounting-Request packets for that session.

Acct-Authentic

ATTRIBUTE Acct-Authentic 45 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A
    VALUE           Acct-Authentic          RADIUS          1
    VALUE           Acct-Authentic          Local           2
    VALUE           Acct-Authentic          Remote          3

This attribute may be included in an Accounting-Request to indicate how the user was authenticated, whether by Radius, the NAS itself, or another remote authentication protocol. Users who are delivered service without being authenticated should not generate Accounting records.

Acct-Session-Time

ATTRIBUTE Acct-Session-Time 46 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A

This attribute indicates how many seconds the user has received service for, and can only be present in Accounting-Request records where the Acct-Status-Type is set to Stop.

Acct-Input-Packets

ATTRIBUTE Acct-Input-Packets 47 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A

This attribute indicates how many packets have been received from the port over the course of this service being provided to a Framed User, and can only be present in Accounting-Request records where the Acct-Status-Type is set to Stop.

Acct-Output-Packets

ATTRIBUTE Acct-Output-Packets 48 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A

This attribute indicates how many packets have been sent to the port in the course of delivering this service to a Framed User, and can only be present in Accounting-Request records where the Acct-Status-Type is set to Stop.

Acct-Terminate-Cause

ATTRIBUTE Acct-Terminate-Cause 49 integer
Users: | --
Hints: | --
Huntgroups: | --
Additivity: | N/A
Proxy propagated: | N/A
    VALUE           Acct-Terminate-Cause    User-Request            1
    VALUE           Acct-Terminate-Cause    Lost-Carrier            2
    VALUE           Acct-Terminate-Cause    Lost-Service            3
    VALUE           Acct-Terminate-Cause    Idle-Timeout            4
    VALUE           Acct-Terminate-Cause    Session-Timeout         5
    VALUE           Acct-Terminate-Cause    Admin-Reset             6
    VALUE           Acct-Terminate-Cause    Admin-Reboot            7
    VALUE           Acct-Terminate-Cause    Port-Error              8
    VALUE           Acct-Terminate-Cause    NAS-Error               9
    VALUE           Acct-Terminate-Cause    NAS-Request             10
    VALUE           Acct-Terminate-Cause    NAS-Reboot              11
    VALUE           Acct-Terminate-Cause    Port-Unneeded           12
    VALUE           Acct-Terminate-Cause    Port-Preempted          13
    VALUE           Acct-Terminate-Cause    Port-Suspended          14
    VALUE           Acct-Terminate-Cause    Service-Unavailable     15
    VALUE           Acct-Terminate-Cause    Callback                16
    VALUE           Acct-Terminate-Cause    User-Error              17
    VALUE           Acct-Terminate-Cause    Host-Request            18

This attribute indicates how the session was terminated, and can only be present in Accounting-Request records where the Acct- Status-Type is set to Stop.

Radius Internal Attributes

These are attributes, used by GNU Radius during the processing of a request. They are never returned to NAS. Mostly, they are used in matching rules.

  • Auth-Type
  • Auth-Data
  • Menu
  • Termination-Menu
  • Prefix
  • Suffix
  • Group
  • Crypt-Password
  • Huntgroup-Name
  • Simultaneous-Use
  • Strip-User-Name
  • Fall-Through
  • Add-Port-To-IP-Address
  • Exec-Program
  • Exec-Program-Wait
  • Acct-Ext-Program
  • Hint
  • Pam-Auth
  • Login-Time
  • Replace-User-Name
  • Rewrite-Function
  • Match-Profile
  • Scheme-Procedure
  • Scheme-Acct-Procedure
  • Log-Mode-Mask
  • Acct-Type

Auth-Type

ATTRIBUTE Auth-Type 1000 integer
Users: | L-
Hints: | -R
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | No
    VALUE      Auth-Type         Local                0
    VALUE      Auth-Type         System               1
    VALUE      Auth-Type         Crypt-Local          3
    VALUE      Auth-Type         Reject               4
    VALUE      Auth-Type         SQL                  252
    VALUE      Auth-Type         Pam                  253
    VALUE      Auth-Type         Accept               254

This attribute tells the server which type of authentication to apply to a particular user. It can be used in LHS of the user's profile. See section Authentication.

Radius interprets values of Auth-Type attribute as follows:

Local
The value of the Password attribute from the record is taken as a cleantext password and is compared against the Password value from the input packet.
System
This means that a user's password is stored in a system password type. Radius queries the operating system to determine if the username/password supplied in the incoming packet are OK.
Crypt-Local
The value of the Password attribute from the record is taken as an MD5 hash on the user's password. Radius generates MD5 hash on the supplied Password value and compares both strings.
Reject
Authentication fails.
Accept
Authentication succeeds.
SQL
Mysql
The MD5-encrypted user's password is queried from the SQL database section SQL Authentication Type. Mysql is an alias maintained for compatibility with other versions of Radius.
Pam
The username/password combination is checked using PAM.

Auth-Data

ATTRIBUTE Auth-Data 2006 string
Users: | L-
Hints: | -R
Huntgroups: | -R
Additivity: | Replace
Proxy propagated: | N/A

The Auth-Data can be used to pass additional data to the authentication methods that need them. In version 0.96 of GNU Radius, this attribute may be used in conjunction with SQL and Pam authentication types. When used with Pam authentication type, this attribute holds the name of PAM service to use. This attribute is temporarily appended to the authentication request, so its value can be referenced to as %C{Auth-Data}. See section Authentication Server Parameters, for an example of of using Auth-Data attribute in `raddb/sqlserver':

Menu

ATTRIBUTE Menu 1001 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | No

This attribute should be used in the RHS. If it is used, it should be the only reply item.

The Menu attribute specifies the name of the menu to be presented to the user. The corresponding menu code is looked up in `RADIUS_DIR/menus/' directory (see section Login Menus -- `raddb/menus').

Termination-Menu

ATTRIBUTE Termination-Menu 1002 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | No

This attribute should be used in the RHS. If it is used, it should be the only reply item.

The Termination-Menu specifies the name of the menu file to be presented to the user after finishing his session. The corresponding menu code is looked up in `RADIUS_DIR/menus/' directory (see section Login Menus -- `raddb/menus').

Prefix

ATTRIBUTE Prefix 1003 string
Users: | L-
Hints: | L-
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

The Prefix attribute indicates the prefix which the username should contain in order for a particular record in the profile to be matched. This attribute should be specified in LHS of the `users' or `hints' file.

For example, if the `users' file contained:

    DEFAULT Prefix = "U", Auth-Type = System
                    Service-Type = Login-User

then usernames `Ugray' and `Uyoda' would match this record, whereas `gray' and `yoda' would not.

Both Prefix and Suffix attributes may be specified in a profile. In this case the record is matched only if the username contains both prefix and suffix specified.

section Suffix section Strip-User-Name

Suffix

ATTRIBUTE Suffix 1004 string
Users: | L-
Hints: | L-
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

The Suffix attribute indicates the suffix which the username should contain in order for a particular record in the profile to be matched. This attribute should be specified in LHS of the `users' or `hints' file.

For example, if the `users' file contained:

    DEFAULT Suffix = ".ppp", Auth-Type = System, Strip-User-Name = Yes
            Service-Type = Framed-User,
                    Framed-Protocol = PPP

then usernames `gray.ppp' and `yoda.ppp' would match this record, whereas `gray' and `yoda' would not.

Both Prefix and Suffix attributes may be specified in a profile. In this case the record is matched only if the username contains both prefix and suffix specified.

section Prefix section Strip-User-Name

Group

ATTRIBUTE Group 1005 string
Users: | L-
Hints: | L-
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

Crypt-Password

ATTRIBUTE Crypt-Password 1006 string
Users: | L-
Hints: | --
Huntgroups: | --
Additivity: | Append
Proxy propagated: | No

This attribute is intended to be used in user's profile LHS. It specifies the MD5 hash of the user's password. When this attribute is present, Auth-Type = Crypt-Local is assumed. If both Auth-Type and Crypt-Password are present, the value of Auth-Type is ignored.

See section Auth-Type.

Huntgroup-Name

ATTRIBUTE Huntgroup-Name 221 string
Users: | L-
Hints: | -R
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

The Huntgroup-Name can be used either in LHS of the `users' file record or in RHS of the `huntgroups' file record.

When encountered in a LHS of a particular `users' profile, this attribute indicates the huntgroup name to be matched. Radius looks up the corresponding record in the `huntgroups' file. If such record is found, each A/V pair from its reply-list is compared against the corresponding pair from the request being processed. The request matches only if it contains all the attributes from the specified huntgroup, and their values satisfy the conditions listed in the huntgroup pairs.

For example, suppose that the authentication request contained the following attributes:

    User-Name = "john",
    Password = "guess",
    NAS-IP-Address = 10.11.11.1,
    NAS-Port-Id = 24

Let us further suppose that the `users' file contains the following entry:

    john    Huntgroup-Name = "users_group",
                    Auth-Type = System
            Service-Type = Login

and, finally, `huntgroups' contains the following entry:

    users_group     NAS-IP-Address = 10.11.11.1
                    NAS-Port-Id < 32

Then the authentication request would succeed since it contains NAS-Port-Id attribute and its value is less than 32.

See section Huntgroups -- `raddb/huntgroups'.

Simultaneous-Use

ATTRIBUTE Simultaneous-Use 1034 integer
Users: | L-
Hints: | -R
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | No

This attribute specifies the maximum number of simultaneous logins a given user is permitted to have. When the user is logged in this number of times any surplus attempts to log in are rejected.

See section Checking Simultaneous Logins.

Strip-User-Name

ATTRIBUTE Strip-User-Name 1035 integer
Users: | LR
Hints: | LR
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | No
    VALUE      Strip-User-Name   No                   0
    VALUE      Strip-User-Name   Yes                  1

The value of Strip-User-Name indicates whether Radius should strip any prefixes/suffixes specified in the user's profile from the user name. When set to Yes the usernames would be logged and accounted without any prefixes/suffixes.

A user may have several usernames for different kind of services. In this case differentiating the usernames by their prefixes and stripping them off before accounting would help keeping accounting records consistent.

For example, let's suppose the `users' file contains:

    DEFAULT Suffix = ".ppp",
                    Strip-User-Name = Yes,
                    Auth-Type = SQL
            Service-Type = Framed-User,
                    Framed-Protocol = PPP

    DEFAULT Suffix = ".slip",
                    Strip-User-Name = Yes,
                    Auth-Type = SQL
            Service-Type = Framed-User,
                    Framed-Protocol = SLIP

Now, user `johns' having a valid account in SQL database logs in as `johns.ppp'. He then is provided the PPP service, and his PPP session is accounted under username `johns'. Later on, he logs in as `johns.slip'. In this case he is provided the SLIP service and again his session is accounted under his real username `johns'.

Fall-Through

ATTRIBUTE Fall-Through 1036 integer
Users: | LR
Hints: | LR
Huntgroups: | --
Additivity: | Append
Proxy propagated: | No
    VALUE      Fall-Through      No                   0
    VALUE      Fall-Through      Yes                  1

The Fall-Through attribute should be used in reply-list. If its value is set to Yes in a particular record, it indicates to Radius that it should continue looking up another records even when this record matches the request. It can be used to provide default values for several profiles.

Consider the following example. Let's suppose the `users' file contains the following:

    johns   Auth-Type = SQL
                    Framed-IP-Address = 11.10.10.251,
                    Fall-Through = Yes

    smith   Auth-Type = SQL
                    Framed-IP-Address = 11.10.10.252,
                    Fall-Through = Yes

    DEFAULT NAS-IP-Address = 11.10.10.1
            Service-Type = Framed-User,
                    Framed-Protocol = PPP

Then after successful matching of a particular user's record, the matching will continue until it finds the DEFAULT entry, which would add its RHS to the reply pairs for this request. The effect is, that if user `johns' authenticates successfully it gets the following reply pairs:

            Service-Type = Framed-User,
            Framed-Protocol = PPP,
            Framed-IP-Address = 11.10.10.251

whereas user smith gets

            Service-Type = Framed-User,
            Framed-Protocol = PPP,
            Framed-IP-Address = 11.10.10.252

Please note that the attribute Fall-Through itself is never returned to the NAS.

Add-Port-To-IP-Address

ATTRIBUTE Add-Port-To-IP-Address 1037 integer
Users: | -R
Hints: | -R
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | No
    VALUE      Add-Port-To-IP-Address  No                   0
    VALUE      Add-Port-To-IP-Address  Yes                  1

If this attribute is present in the RHS and has the value of Yes, then the value of NAS-Port-Id attribute from the authentication request will be added to the value of Framed-IP-Address attribute from the RHS, and resulting value will be returned in Framed-IP-Address attribute to the NAS.

This provides the simplest form of organizing IP address pools.

This attribute is implicitly added to the RHS when the value of a Framed-IP-Address attribute ends with `+' sign. For example the following:

            Framed-IP-Address = 10.10.0.1+

is equivalent to

            Framed-IP-Address = 10.10.0.1,
            Add-Port-To-IP-Address = Yes

Exec-Program

ATTRIBUTE Exec-Program 1038 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | No

When present in RHS, the Exec-Program attribute specifies the full pathname and arguments for the program to be executed when the entry matches.

The command line can reference any attributes from both check and reply pairlists using attribute macros (see section Macro Substitution).

Before the execution of the program radiusd switches to uid and gid of user daemon, group daemon. You can override these defaults by setting variables exec-program-user and exec-program-group in configuration file to proper values section option block.

The daemon does not wait for the process to terminate.

Example

Suppose the `users' file contains the following entry:

    DEFAULT Auth-Type = System,
                    Simultaneous-Use = 1
            Exec-Program = "/usr/local/sbin/logauth \
                            %C{User-Name} \
                            %C{Calling-Station-Id}"

Then, upon successful matching, the program `/usr/local/sbin/logauth' will be executed. It will get as its arguments the values of User-Name and Calling-Station-Id attributes from the request pairs.

Exec-Program-Wait

ATTRIBUTE Exec-Program-Wait 1039 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | No

When present in RHS, the Exec-Program-Wait attribute specifies the full pathname and arguments for the program to be executed when the entry matches.

The command line can reference any attributes from both check and reply pairlists using attribute macros section Macro Substitution.

Before the execution of the program radiusd switches to uid and gid of user daemon, group daemon. You can override these defaults by setting variable exec-program-user in configuration file to a proper value. section option block.

The daemon will wait until the program terminates. The return value of its execution determines whether the entry matches. If the program exits with a non-zero code then the match fails. If it exits with a zero code, the match succeeds. In this case the standard output of the program is read and parsed as if it was a pairlist. The attributes thus obtained are added to the entry's reply attributes.

Example

Suppose the `users' file contains the following entry:

    DEFAULT Auth-Type = System,
                    Simultaneous-Use = 1
            Exec-Program-Wait = "/usr/local/sbin/telauth \
                                 %C{User-Name} \
                                 %C{Calling-Station-Id}"

Then, upon successful matching, the program `/usr/local/sbin/telauth' will be executed. It will get as its arguments the values of User-Name and Calling-Station-Id attributes from the request pairs.

The `/usr/local/sbin/telauth' can, for example, contain the following:

    #! /bin/sh

    DB=/var/db/userlist

    if grep "$1:$2" $DB; then
            echo "Service-Type = Login,"
            echo "Session-Timeout = 1200"
            exit 0
    else
            echo "Reply-Message = \"You are not authorized to log in\""
            exit 1
    fi

It is assumed that `/var/db/userlist' contains a list of username:caller-id pairs for those users that are authorized to use login service.

Acct-Ext-Program

ATTRIBUTE Acct-Ext-Program 2008 string
Users: | --
Hints: | -R
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | N/A

The Acct-Ext-Program attribute can be used in RHS of an `raddb/hints' entry to specify the full path and attributes of an external program to be executed for each accounting request.

The command line can reference any attributes from both check and reply pairlists using attribute macros (see section Macro Substitution).

Before the execution of the program radiusd switches to uid and gid of user daemon, group daemon. You can override these defaults by setting variables exec-program-user and exec-program-group in configuration file to proper values section option block.

The accounting program must exit with status 0 to indicate a successive accounting.

Hint

ATTRIBUTE Hint 1040 string
Users: | L-
Hints: | -R
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | No

Use Hint attribute to specify additional matching criterium depending on the hint (see section Request Processing Hints -- `raddb/hints').

Let the `hints' contain:

    DEFAULT         Prefix = "S", Strip-User-Name = No      Hint = "SLIP"

and the `users' file contain:

    DEFAULT Hint = "SLIP",
                    NAS-IP-Address = 11.10.10.12,
                    Auth-Type = System
            Service-Type = Framed-User,
                    Framed-Protocol = SLIP

Then any user having a valid system account and coming from NAS `11.10.10.12' will be provided SLIP service if his username starts with `S'.

Pam-Auth

ATTRIBUTE Pam-Auth 1041 string
Users: | L-
Hints: | -R
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | No

The Pam-Auth attribute can be used in conjunction with

    Auth-Type = Pam

to supply the PAM service name instead of the default `radius'. It is ignored if Auth-Type attribute is not set to Pam.

Login-Time

ATTRIBUTE Login-Time 1042 string
Users: | L-
Hints: | --
Huntgroups: | --
Additivity: | Append
Proxy propagated: | No

The Login-Time attribute specifies the time range when the user is allowed to log in. The attribute should be specified in LHS.

Format of the Login-Time string is the same as that of UUCP time ranges. The following description of time range format is adopted from the documentation for Taylor UUCP package:

A time string may be a list of simple time strings separated with a vertical bar `|' or a comma `,'.

Each simple time string must begin either with a day of week abbreviation (one of: `Su', `Mo', `Tu', `We', `Th', `Fr', or `Sa'), or `Wk' for any day between Monday and Friday inclusive, or `Any' or `Al' for any day.

Following the day may be a range of hours separated with a hyphen using 24 hour time. The range of hours may cross 0; for example `2300-0700' means any time except 7 AM to 11 PM. If no time is given, calls may be made at any time on the specified day(s).

The time string may also be the single word `Never', which does not match any time.

Here are a few sample time strings with an explanation of what they mean.

`Wk2305-0855,Sa,Su2305-1655 '
This means weekdays before 8:55 AM or after 11:05 PM, any time Saturday, or Sunday before 4:55 PM or after 11:05 PM. These are approximately the times during which night rates apply to phone calls in the U.S.A. Note that this time string uses, for example, `2305' rather than `2300'; this will ensure a cheap rate phone call even if the computer clock is running up to five minutes ahead of the real time.
`Wk0905-2255,Su1705-2255 '
This means weekdays from 9:05 AM to 10:55 PM, or Sunday from 5:05 PM to 10:55 PM. This is approximately the opposite of the previous example.
`Any '
This means any day. Since no time is specified, it means any time on any day.

Replace-User-Name

ATTRIBUTE Replace-User-Name 2001 string
Users: | LR
Hints: | LR
Huntgroups: | --
Additivity: | Append
Proxy propagated: | No
    VALUE      Replace-User-Name  No                   0
    VALUE      Replace-User-Name  Yes                  1

Use this attribute to modify username from the incoming packet. The Replace-User-Name can reference any attributes from both LHS and RHS pairlists using attribute macros section Macro Substitution.

For example the following `users' entry

    guest   NAS-IP-Address = 11.10.10.11,
                    Calling-Station-Id != ""
                    Auth-Type = Accept
            Replace-User-Name = "guest#%C{Calling-Station-Id}",
                    Service-Type = Framed-User,
                    Framed-Protocol = PPP

Allows usage of PPP service for username guest, coming from NAS `11.10.10.11' with non-empty Calling-Station-Id attribute. The string consisting of `#' character followed by Calling-Station-Id value is appended to the username.

Rewrite-Function

ATTRIBUTE Rewrite-Function 2004 string
Users: | LR
Hints: | LR
Huntgroups: | LR
Additivity: | Append
Proxy propagated: | No

The Rewrite-Function attribute specifies the name of the rewriting function to be applied to the request. The attribute may be specified in either pairlist in the entries of `hints' or `huntgroups' configuration files.

The corresponding function should be defined in `rewrite' as

    integer name()

i.e. it should return integer value and should not take any arguments.

See section Rewrite functions -- `raddb/rewrite'. See section Request Processing Hints -- `raddb/hints'. See section Huntgroups -- `raddb/huntgroups'.

Match-Profile

ATTRIBUTE Match-Profile 2004 string
Users: | LR
Hints: | -R
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | No

The Match-Profile attribute can be used in LHS and RHS lists of a user profile. Its value is the name of another user's profile (target profile). When Match-Profile is used in the LHS, the incoming packet will match this profile only if it matches the target profile. In this case the reply pairs will be formed concatenating the RHS lists from both profiles. When used in RHS, this attribute causes the reply pairs from the target profile to be appended to the reply from the current profile if the target profile matches the incoming request.

For example:

    IPPOOL  NAS-IP-Address = 10.10.10.1
                    Framed-Protocol = PPP, Framed-IP-Address = "10.10.10.2"

    IPPOOL  NAS-IP-Address = 10.10.11.1
                    Framed-Protocol = PPP, Framed-IP-Address = "10.10.11.2"

    guest   Auth-Type = SQL
                    Service-Type = Framed-User,
            Match-Profile = IPPOOL

In this example, when user "guest" comes from NAS 10.10.10.1 he is assigned IP address 10.10.10.2, otherwise if he is coming from NAS 10.10.11.1 he is assigned IP address 10.10.11.2.

Scheme-Procedure

ATTRIBUTE Scheme-Procedure 2009 string
Users: | -R
Hints: | --
Huntgroups: | --
Additivity: | Append
Proxy propagated: | N/A

The Scheme-Procedure attribute is used to set the name of Scheme authentication procedure. See section Authentication with Scheme, for the information about how to write Scheme authentication procedures.

Scheme-Acct-Procedure

ATTRIBUTE Scheme-Acct-Procedure 2010 string
Users: | --
Hints: | -R
Huntgroups: | --
Additivity: | Replace
Proxy propagated: | N/A

The Scheme-Acct-Procedure attribute is used to set the name of Scheme accounting procedure. See section Accounting with Scheme, for the information about how to write Scheme accounting procedures.

Log-Mode-Mask

ATTRIBUTE Log-Mode-Mask 2007 integer
Users: | L-
Hints: | -R
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | N/A
    VALUE		Log-Mode-Mask		Log-Auth		1
    VALUE		Log-Mode-Mask		Log-Auth-Pass		2
    VALUE		Log-Mode-Mask		Log-Failed-Pass		4
    VALUE		Log-Mode-Mask		Log-Pass		6
    VALUE		Log-Mode-Mask		Log-All			7

Log-Mode-Mask is used to control the verbosity of authentication log messages for given user or class of users. The meaning of its values is:

Log-Auth
Do not log successful authentications.
Log-Auth-Pass
Do not show password with the log message from a successful authentication.
Log-Failed-Pass
Do not show failed password.
Log-Pass
Do not show plaintext password, either failed or succeeded.
Log-All
Do not log authentications at all.

Technical details: After authentication, the server collects all Log-Mode-Mask attributes from the incoming request and LHS of the user's entry. The values of these attributes OR'ed together form a mask which is applied via XOR operation to the current log mode. The value thus obtained is used as effective log mode.

Acct-Type

ATTRIBUTE Acct-Type 2003 integer
Users: | L-
Hints: | -R
Huntgroups: | -R
Additivity: | Append
Proxy propagated: | N/A
    VALUE		Acct-Type		None	0
    VALUE		Acct-Type		System	1
    VALUE		Acct-Type		Detail	2
    VALUE		Acct-Type		SQL	3

The Acct-Type allows to control which accounting methods must be used for a given user or a group of users. In the absense of this attribute, all currently enabled accounting types are used. See section Accounting, for more information about accounting types.

Reporting Bugs

It is possible you will encounter a bug in one of Radius programs. If this happens we would like to hear about it. As the purpose of bug reporting is to improve software, please be sure to include maximum information when reporting a bug. The information needed is:

  • Conditions under which the bug appears.
  • Version of the package you are using.
  • Compilation options used when configuring the package.
  • If the bug is found in radiusd daemon, run `radiusd -v' and include the output it produces.
  • Contents of radius configuration directory (/usr/local/etc/raddb or whatever you have set it to while configuring).
  • Log messages produced.

Send your report to bug-gnu-radius@gnu.org. Allow me a couple of days to answer.

Where to Get Info About GNU Radius

The two places to look for any news regarding GNU Radius are the Radius homepage at http://www.gnu.org/software/radius, and the Radius project page at http://savannah.gnu.org/projects/radius.

The following mailing lists are related to GNU Radius:

info-gnu-radius@gnu.org
This list distributes announcements and progress reports on GNU Radius. This is a moderated list. Please, do not send bug reports or requests for help to this list, there exist special mailing lists for these purposes. To subscribe to the list, visit http://mail.gnu.org/mailman/listinfo/info-gnu-radius.
help-gnu-radius@gnu.org
This list is the place for users and installers of GNU Radius to ask for help. The list is not moderated, but postings are allowed for list members only. To subscribe to the list, visit http://mail.gnu.org/mailman/listinfo/help-gnu-radius.
bug-gnu-radius@gnu.org
This list distributes bug reports, bugfixes, and suggestions for improvements in Radius. User discussion of Radius bugs also occurs here. The list is not moderated, postings are allowed for anybody. To subscribe to the list, visit http://mail.gnu.org/mailman/listinfo/bug-gnu-radius.

Program Index

Jump to: b - n - p - r

b

  • buildbm

    • n

  • nas.scm

    • p

  • pam_radius.so

    • r

  • radauth
  • radctl
  • radgrep
  • radiusd
  • radlast
  • radlast, options
  • radping
  • radscm
  • radsession
  • raduse
  • radwho
  • radzap

    • Keyword Index

    Jump to: $ - a - c - d - e - f - g - i - l - m - n - o - p - r - s - t - u - v

    $

  • $INCLUDE (dictionary)

    • a

  • access-denied
  • account-closed
  • acct statement
  • acct-dir
  • acl
  • allow
  • ATTRIBUTE
  • auth

    • c

  • category
  • channel, channel
  • checkrad-assume-logged
  • community

    • d

  • debug
  • deny
  • detail, detail

    • e

  • exec-program-user

    • f

  • file

    • g

  • guile

    • i

  • ident

    • l

  • level
  • listen, listen
  • load
  • load-path
  • log-dir
  • logging

    • m

  • max-requests, max-requests, max-requests, max-requests, max-requests
  • message
  • multiple-login

    • n

  • network

    • o

  • option

    • p

  • password-expire-warning, password-expire-warning
  • password-expired
  • port, port, port
  • print-auth
  • print-category
  • print-cons
  • print-failed-pass
  • print-level
  • print-pass
  • print-pid
  • print-priority
  • proxy

    • r

  • realm-quota
  • request-cleanup-delay, request-cleanup-delay, request-cleanup-delay, request-cleanup-delay

    • s

  • second-login
  • snmp
  • source-ip
  • spawn, spawn, spawn
  • strip-names
  • syslog

    • t

  • time-to-live, time-to-live, time-to-live
  • timespan-violation

    • u

  • usedbm
  • username-chars

    • v

  • VALUE
  • VENDOR

    • Examples Index

    Jump to: a - c - g - h - i - l - m - n - r - s - u

    a

  • Analyzing SNMP output

    • c

  • Checking UNIX finger output
  • `client.conf'
  • `clients' file

    • g

  • Guest accounts, setting up

    • h

  • `hints' file
  • `huntgroups' file

    • i

  • Invoking Scheme authentication function
  • IP pools for MAX Ascend

    • l

  • logging statement
  • Login verification functions

    • m

  • `menus' file

    • n

  • `naslist' file
  • `nastypes' file

    • r

  • `realms' file
  • Rewrite functions

    • s

  • Scheme accounting function
  • Scheme authentication function
  • Scheme authentication function, invocation

    • u

  • `users' file

    • Index of Functions and Variables

    Jump to: % - a - d - i - l - r - s - u

    %

  • %raddb-path

    • a

  • acct-function-name
  • auth-function
  • avl-delete
  • avl-match?
  • avl-merge

    • d

  • dict-entry

    • i

  • index

    • l

  • length
  • logit

    • r

  • rad-add-server
  • rad-client-add-server
  • rad-client-list-servers
  • rad-client-retry
  • rad-client-set-server
  • rad-client-source-ip
  • rad-client-timeout
  • rad-closelog
  • rad-dict-name->attr
  • rad-dict-name->value
  • rad-dict-pec->vendor
  • rad-dict-value->name
  • rad-format-code
  • rad-format-pair
  • rad-format-reply-msg
  • rad-get-server
  • rad-list-servers
  • rad-log-close
  • rad-log-open
  • rad-openlog
  • rad-print-pairs
  • rad-read-no-echo
  • rad-rewrite-execute
  • rad-rewrite-execute-string
  • rad-select-server
  • rad-send
  • rad-send-internal
  • rad-server-list
  • rad-syslog
  • rad-utmp-putent
  • rindex

    • s

  • substr

    • u

  • utmp-entry

    • Attribute Index

    Jump to: a - c - e - f - g - h - i - l - m - n - p - r - s - t - u - v

    a

  • Acct-Authentic
  • Acct-Delay-Time
  • Acct-Ext-Program
  • Acct-Input-Octets
  • Acct-Input-Packets
  • Acct-Output-Octets
  • Acct-Output-Packets
  • Acct-Session-Id
  • Acct-Session-Time
  • Acct-Status-Type
  • Acct-Terminate-Cause
  • Acct-Type
  • Add-Port-To-IP-Address
  • Auth-Data
  • Auth-Type

    • c

  • Callback-Id
  • Callback-Number
  • Called-Station-Id
  • Calling-Station-Id
  • CHAP-Password
  • Class
  • Crypt-Password

    • e

  • Exec-Program
  • Exec-Program-Wait

    • f

  • Fall-Through
  • Framed-Compression
  • Framed-IP-Address
  • Framed-IP-Netmask
  • Framed-MTU
  • Framed-Protocol
  • Framed-Route
  • Framed-Routing

    • g

  • Group

    • h

  • Hint
  • Huntgroup-Name

    • i

  • Idle-Timeout

    • l

  • Log-Mode-Mask
  • Login-Time

    • m

  • Match-Profile
  • Menu

    • n

  • NAS-Identifier
  • NAS-IP-Address
  • NAS-Port-Id
  • NAS-Port-Type

    • p

  • Pam-Auth
  • Password
  • Prefix

    • r

  • Replace-User-Name
  • Reply-Message
  • Rewrite-Function

    • s

  • Scheme-Acct-Procedure
  • Scheme-Procedure
  • Service-Type
  • Session-Timeout
  • Simultaneous-Use
  • State
  • Strip-User-Name
  • Suffix

    • t

  • Termination-Action
  • Termination-Menu

    • u

  • User-Name

    • v

  • Vendor-Specific

    • Concept Index

    Jump to: a - b - c - d - e - g - h - i - l - m - n - p - r - s - u - w

    a

  • A/V pair, A/V pair
  • Accept Authentication Type
  • `access.deny' file
  • Accounting directory
  • Accounting requests
  • Accounting service parameters
  • Accounting Types
  • Accounting with Scheme
  • Additivity of an attribute
  • Attribute, Attribute
  • Attribute-Value pair, Attribute-Value pair
  • Authentication
  • Authentication requests
  • Authentication service parameters
  • Authentication with Scheme

    • b

  • Built-in functions, Rewrite

    • c

  • CHAP
  • Checking Simultaneous Logins
  • Client Configuration
  • Client Package
  • `client.conf'
  • `clients' file
  • Configuration directory
  • Configuration files (radiusd)
  • Custom Accounting Types
  • Custom Authentication Types
  • Customizing accounting service
  • Customizing authentication server
  • Customizing proxy server
  • Customizing Radiusd Guile interface
  • Customizing reply messages
  • Customizing SNMP server

    • d

  • Data types, Rewrite
  • DBM: enabling
  • Debugging
  • Declarations, Rewrite
  • Deleting hung user sessions
  • Detailed Request Accounting
  • Dial-In user
  • Dial-Up user
  • `dictionary' file
  • Disabling user accounts
  • Display, raduse

    • e

  • Enabling DBM
  • Encrypted Password Authentication Type
  • Extensions

    • g

  • Guest accounts, setting up
  • Guile
  • Guile interface
  • Guile interface configuration
  • Guile, representation of Radius data

    • h

  • Hints, Hints
  • `hints' file
  • Huntgroups, Huntgroups
  • `huntgroups' file

    • i

  • Identifiers, Rewrite
  • Invoking the radius daemon

    • l

  • Label, Matching Rule
  • LHS, Matching Rule
  • Local Password Auth
  • Log directory
  • Logging
  • Logging category
  • Logging channel
  • Logging, `config' statement

    • m

  • Matching Rule
  • MAX Ascend, broken passwords
  • menu, syntax
  • `menus', configuration subdirectory
  • Messages: configuring

    • n

  • Naming conventions
  • NAS, NAS
  • NAS types, standard
  • `naslist' file
  • `nastypes' file
  • `nastypes' file, syntax of
  • Network Access Server, Network Access Server
  • `NOREALM', special realm name

    • p

  • PAM Authentication Type
  • Processing requests
  • Propagation of an attribute
  • Properties of an attribute
  • Proxy Service
  • Proxy service parameters
  • Proxying

    • r

  • `radacct', accounting directory
  • `raddb'
  • `raddb/access.deny' file
  • `raddb/client.conf'
  • `raddb/clients' file
  • `raddb/config' file
  • `raddb/hints' file
  • `raddb/huntgroups' file
  • `raddb/menus', configuration subdirectory
  • `raddb/naslist' file
  • `raddb/realms' file
  • `raddb/rewrite', configuration file
  • `raddb/sqlserver' file.
  • `raddb/users' file
  • Radius daemon invocation
  • Radius dictionary
  • Radius-Specific Scheme Functions
  • Radiusd configuration
  • Radiusd configuration files
  • `radlog'
  • raduse display
  • raduse, command line options
  • radwho, command line options
  • Realms
  • `realms' file
  • Reject Authentication Type
  • Request
  • Requests, accounting
  • Requests, authentication
  • Rewrite
  • Rewrite identifiers
  • Rewrite, applying functions
  • Rewrite, attribute creation functions
  • `rewrite', configuration file
  • Rewrite, data types
  • Rewrite, login verification functions
  • Rewrite, quick start introduction
  • Rewrite, symbols
  • Rewrite, syntax of the language
  • Rewrite, syntax overview
  • Rewrite, usage
  • Rewriting incoming requests
  • RHS, Matching Rule
  • Run-time options (radiusd)

    • s

  • Service
  • Session
  • Session ID
  • Simultaneous logins, checking for
  • SNMP service parameters
  • SQL Accounting
  • SQL accounting query templates
  • SQL accounting query templates, writing of
  • SQL Authentication Type
  • `sqlserver' file.
  • Statements, Rewrite
  • Symbols, Rewrite
  • Syntax of `nastypes'
  • System Authentication Type

    • u

  • UNIX Accounting
  • User Profiles
  • `users' file
  • Utility Programs

    • w

  • Writing SQL accounting query templates

    • Footnotes

    (1)

    For compatibility with other implementations of radius, GNU Radius treats profile labels in the form DEFAULT%d, where %d represents a decimal number, in the same way it treats DEFAULT labels. The same applies to BEGIN labels.

    (2)

    The flags are optional for compatibility with previous versions of GNU Radius. If they are omitted, the default is `[LRLRLR]+'

    (3)

    Logins from DEFAULT NASes are not reported by213.130.0.5 raduse, neither are they reflected in SNMP variables.

    This document was generated on 26 December 2001 using the texi2html translator version 1.52.


sed, a stream editor

version 3.02, 28 June 1998

by Ken Pizzini

Table of Contents

  • Introduction
  • Invocation
  • SED Programs
    • Selecting lines with SED
    • Overview of regular expression syntax
    • Where SED buffers data
    • Often used commands
    • Less frequently used commands
    • Commands for die-hard SED programmers
  • Some sample scripts
  • About the (non-)limitations on line length
  • Other resources for learning about SED
  • Reporting bugs
  • Concept Index
  • Command and Option Index

Introduction

SED is a stream editor. A stream editor is used to perform basic text transformations on an input stream (a file or input from a pipeline). While in some ways similar to an editor which permits scripted edits (such as ED), SED works by making only one pass over the input(s), and is consequently more efficient. But it is SED's ability to filter text in a pipeline which particularly distinguishes it from other types of editors.

Invocation

SED may be invoked with the following command-line options:

`-V'
`--version'
Print out the version of SED that is being run and a copyright notice, then exit.
`-h'
`--help'
Print a usage message briefly summarizing these command-line options and the bug-reporting address, then exit.
`-n'
`--quiet'
`--silent'
By default, SED will print out the pattern space at then end of each cycle through the script. These options disable this automatic printing, and SED will only produce output when explicitly told to via the p command.
`-e script'
`--expression=script'
Add the commands in script to the set of commands to be run while processing the input.
`-f script-file'
`--file=script-file'
Add the commands contained in the file script-file to the set of commands to be run while processing the input.

If no -e, -f, --expression, or --file options are given on the command-line, then the first non-option argument on the command line is taken to be the script to be executed.

If any command-line parameters remain after processing the above, these parameters are interpreted as the names of input files to be processed. A file name of - refers to the standard input stream. The standard input will processed if no file names are specified.

SED Programs

A SED program consists of one or more SED commands, passed in by one or more of the -e, -f, --expression, and --file options, or the first non-option argument if zero of these options are used. This document will refer to "the" SED script; this will be understood to mean the in-order catenation of all of the scripts and script-files passed in.

Each SED command consists of an optional address or address range, followed by a one-character command name and any additional command-specific code.

Selecting lines with SED

Addresses in a SED script can be in any of the following forms:

`number'
Specifying a line number will match only that line in the input. (Note that SED counts lines continuously across all input files.)
`first~step'
This GNU extension matches every stepth line starting with line first. In particular, lines will be selected when there exists a non-negative n such that the current line-number equals first + (n * step). Thus, to select the odd-numbered lines, one would use 1~2; to pick every third line starting with the second, 2~3 would be used; to pick every fifth line starting with the tenth, use 10~5; and 50~0 is just an obscure way of saying 50.
`$'
This address matches the last line of the last file of input.
`/regexp/'
This will select any line which matches the regular expression regexp. If regexp itself includes any / characters, each must be escaped by a backslash (\).
`\%regexp%'
(The % may be replaced by any other single character.) This also matches the regular expression regexp, but allows one to use a different delimiter than /. This is particularly useful if the regexp itself contains a lot of /s, since it avoids the tedious escaping of every /. If regexp itself includes any delimiter characters, each must be escaped by a backslash (\).
`/regexp/I'
`\%regexp%I'
The I modifier to regular-expression matching is a GNU extension which causes the regexp to be matched in a case-insensitive manner.

If no addresses are given, then all lines are matched; if one address is given, then only lines matching that address are matched.

An address range can be specified by specifying two addresses separated by a comma (,). An address range matches lines starting from where the first address matches, and continues until the second address matches (inclusively). If the second address is a regexp, then checking for the ending match will start with the line following the line which matched the first address. If the second address is a number less than (or equal to) the line matching the first address, then only the one line is matched.

Appending the ! character to the end of an address specification will negate the sense of the match. That is, if the ! character follows an address range, then only lines which do not match the address range will be selected. This also works for singleton addresses, and, perhaps perversely, for the null address.

Overview of regular expression syntax

[[I may add a brief overview of regular expressions at a later date; for now see any of the various other documentations for regular expressions, such as the AWK info page.]]

Where SED buffers data

SED maintains two data buffers: the active pattern space, and the auxiliary hold space. In "normal" operation, SED reads in one line from the input stream and places it in the pattern space. This pattern space is where text manipulations occur. The hold space is initially empty, but there are commands for moving data between the pattern and hold spaces.

Often used commands

If you use SED at all, you will quite likely want to know these commands.

`#'
[No addresses allowed.] The # "command" begins a comment; the comment continues until the next newline. If you are concerned about portability, be aware that some implementations of SED (which are not POSIX.2 conformant) may only support a single one-line comment, and then only when the very first character of the script is a #. Warning: if the first two characters of the SED script are #n, then the -n (no-autoprint) option is forced. If you want to put a comment in the first line of your script and that comment begins with the letter `n' and you do not want this behavior, then be sure to either use a capital `N', or place at least one space before the `n'.
`s/regexp/replacement/flags'
(The / characters may be uniformly replaced by any other single character within any given s command.) The / character (or whatever other character is used in its stead) can appear in the regexp or replacement only if it is preceded by a \ character. Also newlines may appear in the regexp using the two character sequence \n. The s command attempts to match the pattern space against the supplied regexp. If the match is successful, then that portion of the pattern space which was matched is replaced with replacement. The replacement can contain \n (n being a number from 1 to 9, inclusive) references, which refer to the portion of the match which is contained between the nth \( and its matching \). Also, the replacement can contain unescaped & characters which will reference the whole matched portion of the pattern space. To include a literal \, &, or newline in the final replacement, be sure to precede the desired \, &, or newline in the replacement with a \. The s command can be followed with zero or more of the following flags:
`g'
Apply the replacement to all matches to the regexp, not just the first.
`p'
If the substitution was made, then print the new pattern space.
`number'
Only replace the numberth match of the regexp.
`w file-name'
If the substitution was made, then write out the result to the named file.
`I'
(This is a GNU extension.) Match regexp in a case-insensitive manner.
`q'
[At most one address allowed.] Exit SED without processing any more commands or input. Note that the current pattern space is printed if auto-print is not disabled.
`d'
Delete the pattern space; immediately start next cycle.
`p'
Print out the pattern space (to the standard output). This command is usually only used in conjunction with the -n command-line option. Note: some implementations of SED, such as this one, will double-print lines when auto-print is not disabled and the p command is given. Other implementations will only print the line once. Both ways conform with the POSIX.2 standard, and so neither way can be considered to be in error. Portable SED scripts should thus avoid relying on either behavior; either use the -n option and explicitly print what you want, or avoid use of the p command (and also the p flag to the s command).
`n'
If auto-print is not disabled, print the pattern space, then, regardless, replace the pattern space with the next line of input. If there is no more input then SED exits without processing any more commands.
`{ commands }'
A group of commands may be enclosed between { and } characters. (The } must appear in a zero-address command context.) This is particularly useful when you want a group of commands to be triggered by a single address (or address-range) match.

Less frequently used commands

Though perhaps less frequently used than those in the previous section, some very small yet useful SED scripts can be built with these commands.

`y/source-chars/dest-chars/'
(The / characters may be uniformly replaced by any other single character within any given y command.) Transliterate any characters in the pattern space which match any of the source-chars with the corresponding character in dest-chars. Instances of the / (or whatever other character is used in its stead), \, or newlines can appear in the source-chars or dest-chars lists, provide that each instance is escaped by a \. The source-chars and dest-chars lists must contain the same number of characters (after de-escaping).
`a\'
`text'
[At most one address allowed.] Queue the lines of text which follow this command (each but the last ending with a \, which will be removed from the output) to be output at the end of the current cycle, or when the next input line is read.
`i\'
`text'
[At most one address allowed.] Immediately output the lines of text which follow this command (each but the last ending with a \, which will be removed from the output).
`c\'
`text'
Delete the lines matching the address or address-range, and output the lines of text which follow this command (each but the last ending with a \, which will be removed from the output) in place of the last line (or in place of each line, if no addresses were specified). A new cycle is started after this command is done, since the pattern space will have been deleted.
`='
[At most one address allowed.] Print out the current input line number (with a trailing newline).
`l'
Print the pattern space in an unambiguous form: non-printable characters (and the \ character) are printed in C-style escaped form; long lines are split, with a trailing \ character to indicate the split; the end of each line is marked with a $.
`r filename'
[At most one address allowed.] Queue the contents of filename to be read and inserted into the output stream at the end of the current cycle, or when the next input line is read. Note that if filename cannot be read, it is treated as if it were an empty file, without any error indication.
`w filename'
Write the pattern space to filename. The filename will be created (or truncated) before the first input line is read; all w commands (including instances of w flag on successful s commands) which refer to the same filename are output through the same FILE stream.
`D'
Delete text in the pattern space up to the first newline. If any text is left, restart cycle with the resultant pattern space (without reading a new line of input), otherwise start a normal new cycle.
`N'
Add a newline to the pattern space, then append the next line of input to the pattern space. If there is no more input then SED exits without processing any more commands.
`P'
Print out the portion of the pattern space up to the first newline.
`h'
Replace the contents of the hold space with the contents of the pattern space.
`H'
Append a newline to the contents of the hold space, and then append the contents of the pattern space to that of the hold space.
`g'
Replace the contents of the pattern space with the contents of the hold space.
`G'
Append a newline to the contents of the pattern space, and then append the contents of the hold space to that of the pattern space.
`x'
Exchange the contents of the hold and pattern spaces.

Commands for die-hard SED programmers

In most cases, use of these commands indicates that you are probably better off programming in something like PERL. But occasionally one is committed to sticking with SED, and these commands can enable one to write quite convoluted scripts.

`: label'
[No addresses allowed.] Specify the location of label for the b and t commands. In all other respects, a no-op.
`b label'
Unconditionally branch to label. The label may be omitted, in which case the next cycle is started.
`t label'
Branch to label only if there has been a successful substitution since the last input line was read or t branch was taken. The label may be omitted, in which case the next cycle is started.

Some sample scripts

[[Not this release, sorry. But check out the scripts in the testsuite directory, and the amazing dc.sed script in the top-level directory of this distribution.]]

About the (non-)limitations on line length

For those who want to write portable SED scripts, be aware that some implementations have been known to limit line lengths (for the pattern and hold spaces) to be no more than 4000 bytes. The POSIX.2 standard specifies that conforming SED implementations shall support at least 8192 byte line lengths. GNU SED has no built-in limit on line length; as long as SED can malloc() more (virtual) memory, it will allow lines as long as you care to feed it (or construct within it).

Other resources for learning about SED

In addition to several books that have been written about SED (either specifically or as chapters in books which discuss shell programming), one can find out more about SED (including suggestions of a few books) from the FAQ for the seders mailing list, available from any of:

 http://www.dbnet.ece.ntua.gr/~george/sed/sedfaq.html
 http://www.ptug.org/sed/sedfaq.htm
 http://www.wollery.demon.co.uk/sedtut10.txt

There is an informal "seders" mailing list manually maintained by Al Aab. To subscribe, send e-mail to af137@torfree.net with a brief description of your interest.

Reporting bugs

Email bug reports to bug-gnu-utils@gnu.org. Be sure to include the word "sed" somewhere in the "Subject:" field.

Concept Index

This is a general index of all issues discussed in this manual, with the exception of the SED commands and command-line options.

a

  • Adding a block of text after a line
  • Address, as a regular expression
  • Address, last line
  • Address, numeric
  • Addresses, in SED scripts
  • Addtional reading about SED
  • Append hold space to pattern space
  • Append next input line to pattern space
  • Append pattern space to hold space

    • b

  • Backreferences, in regular expressions
  • Branch to a label, if s/// succeeded
  • Branch to a label, unconditionally
  • Buffer spaces, pattern and hold
  • Bugs, reporting

    • c

  • Case-insensitive matching
  • Caveat -- #n on first line
  • Caveat -- p command and -n flag
  • Command groups
  • Comments, in scripts
  • Conditional branch
  • Copy hold space into pattern space
  • Copy pattern space into hold space

    • d

  • Delete first line from pattern space
  • Deleting lines

    • e

  • Exchange hold space with pattern space
  • Excluding lines

    • f

  • Files to be processed as input
  • Flow of control in scripts

    • g

  • Global substitution
  • GNU extensions, I modifier, GNU extensions, I modifier
  • GNU extensions, n~m addresses
  • GNU extensions, unlimited line length
  • Goto, in scripts
  • Grouping commands

    • h

  • Hold space, appending from pattern space
  • Hold space, appending to pattern space
  • Hold space, copy into pattern space
  • Hold space, copying pattern space into
  • Hold space, definition
  • Hold space, exchange with pattern space

    • i

  • Insert text from a file
  • Inserting a block of text before a line

    • l

  • Labels, in scripts
  • Last line, selecting
  • Line number, print
  • Line selection
  • Line, selecting by number
  • Line, selecting by regular expression match
  • Line, selecting last
  • List pattern space

    • n

  • Next input line, append to pattern space
  • Next input line, replace pattern space with

    • p

  • Parenthesized substrings
  • Pattern space, definition
  • Portability, comments
  • Portability, line length limitations
  • Portability, p command and -n flag
  • Print first line from pattern space
  • Print line number
  • Print selected lines
  • Print unambiguous representation of pattern space
  • Printing text after substitution

    • q

  • Quitting

    • r

  • Range of lines
  • Read next input line
  • Read text from a file
  • Replace hold space with copy of pattern space
  • Replace pattern space with copy of hold space
  • Replace specific input lines
  • Replacing all text matching regexp in a line
  • Replacing only nth match of regexp in a line
  • Replacing text matching regexp
  • Replacing text matching regexp, options

    • s

  • Script structure
  • Script, from a file
  • Script, from command line
  • SED program structure
  • Selected lines, replacing
  • Selecting lines to process
  • Selecting non-matching lines
  • Several lines, selecting
  • Slash character, in regular expressions
  • Spaces, pattern and hold
  • Standard input, processing as input
  • Stream editor
  • Substitution of text
  • Substitution of text, options

    • t

  • Text, appending
  • Text, insertion
  • Transliteration

    • u

  • Usage summary, printing

    • v

  • Version, printing

    • w

  • Write result of a substitution to file
  • Write to a file

    • Command and Option Index

    This is an alphabetical list of all SED commands and command-line opions.

    #

  • # (comment) command

    • -

  • -n, forcing from within a script

    • :

  • : (label) command

    • =

  • = (print line number) command

    • a

  • a (append text lines) command

    • b

  • b (branch) command

    • c

  • c (change to text lines) command

    • d

  • D (delete first line) command
  • d (delete) command

    • g

  • G (appending Get) command
  • g (get) command

    • h

  • H (append Hold) command
  • h (hold) command

    • i

  • i (insert text lines) command

    • l

  • l (list unambiguously) command

    • n

  • N (append Next line) command
  • n (next-line) command

    • p

  • P (print first line) command
  • p (print) command

    • q

  • q (quit) command

    • r

  • r (read file) command

    • s

  • s (substitute) command
  • s command, option flags

    • t

  • t (conditional branch) command

    • w

  • w (write file) command

    • x

  • x (eXchange) command

    • y

  • y (transliterate) command

    • {

  • {} command grouping

    • This document was generated on 28 October 1999 using the texi2html translator version 1.54.


GNU shar utilities

GNU sharutils, version 4.1.9

A set of shell archiver utilities

Edition 4.1.9, 28 October

Jan Dj@"arv
Pinard

Table of Contents

  • Introduction to both programs
  • Invoking the shar program
    • Selecting files
    • Splitting output
    • Controlling the shar headers
    • Selecting how files are stocked
    • Protecting against transmission errors
    • Producing different kinds of shars
  • Invoking the unshar program
  • Miscellaneous considerations

Copyright (C) 1994 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

Introduction to both programs

GNU shar makes so-called shell archives out of many files, preparing them for transmission by electronic mail services. A shell archive is a collection of files that can be unpacked by /bin/sh. A wide range of features provide extensive flexibility in manufacturing shars and in specifying shar smartness. For example, shar may compress files, uuencode binary files, split long files and construct multi-part mailings, ensure correct unsharing order, and provide simplistic checksums. See section Invoking the shar program.

GNU unshar scans a set of mail messages looking for the start of shell archives. It will automatically strip off the mail headers and other introductory text. The archive bodies are then unpacked by a copy of the shell. unshar may also process files containing concatenated shell archives. See section Invoking the unshar program.

GNU shar has a long history. All along this long road, numerous users contributed various improvements. The file `THANKS', from the GNU shar distribution, contain all names still having valid email addresses, as far as we know.

Please help me getting the history straight, for the following information is approximative. James Gosling wrote the public domain shar 1.x. William Davidsen rewrote it as shar 2.x. Warren Tucker brought modifications and called it shar 3.x. Richard Gumpertz maintained it until 1990. Pinard, from the public domain shar 3.49, made GNU shar 4.x, in 1994. Some modules and other code sections were freely borrowed from other GNU distributions, bringing this shar under the terms of the GNU General Public License.

Your feedback helps us to make a better and more portable product. Mail suggestions and bug reports (including documentation errors) for these programs to `bug-gnu-utils@prep.ai.mit.edu'.

Invoking the shar program

The format of the shar command is one of:

shar [ option ] ... file ...
shar -S [ option ] ...

In the first form, the file list is given as command arguments. In the second form, the file list is read from standard input. The resulting archive is sent to standard output unless the -o option is given.

Options can be given in any order. Some options depend on each other: the -o option is required if the -l or -L option is used. The -n option is required if the -a option is used. Also see -V below.

Some options are special purpose:

--help
Print a help summary on standard output, then immediately exits.
--version
Print the version number of the program on standard output, then immediately exits.
-q
--quiet
Verbose off at shar time. Messages are usually issued on standard error to let the user follow the progress, while making the archives. This option inhibits these messages.

Selecting files

-p
--intermix-type
Allow positional parameter options. The options -M, -B, -T, -z and -Z may be embedded, and files to the right of the option will be processed in the specified mode. Without the -p option, embedded options would be interpreted as file names. See section Selecting how files are stocked for more information on these options.
-S
--stdin-file-list
Read list of files to be packed from the standard input rather than from the command line. Input must be one file name per line. This switch is especially useful when the command line will not hold the list of files to be packed. For example:
find . -type f -print | shar -S -o /tmp/big.shar
If -p is specified on the command line, then the options -M, -B, -T, -z and -Z may be included in the standard input (on a line separate from file names). The maximum number of lines of standard input, file names and options, may not exceed 1024.

Splitting output

-o prefix
--output-prefix=prefix
Save the archive to files `prefix.01' through `prefix.nnn' instead of standard output. This option must be used when the -l or the -L switches are used. When prefix contains any `%' character, prefix is then interpreted as a sprintf format, which should be able to display a single decimal number. When prefix does not contain such a `%' character, the string `.%02d' is internally appended.
-l size
--whole-size-limit=size
Limit the output file size to size times 1024 bytes but don't split input files. This allows the recipient of the shell archives to unpack them in any order.
-L size
--split-size-limit=size
Limit output file size to size times 1024 bytes and split files if necessary. The archives created with this option must be unpacked in the correct order. If the recipient of the shell archives wants to put all of them in a single folder, she shall save them in the correct order for unshar, used with option -e, to unpack them all at once. See section Invoking the unshar program. For people used to saving all the shell archives into a single mail folder, care must be taken to save them in the appropriate order. For those having the appropriate tools (like Masanobu Umeda's rmailsort package for GNU Emacs), shell archives can be saved in any order, then sorted by increasing date (or send time) before massive unpacking.

Controlling the shar headers

-n name
--archive-name=name
Name of archive to be included in the header of the shar files. Also see the -a switch further down.
-s address
--submitter=address
The -s option allows for overriding the email address for the submitter, for when the default is not appropriate. The automatically determined address looks like `username@hostname'.
-a
--net-headers
Allows automatic generation of headers:
Submitted-by: address
Archive-name: name/partnn
The name must be given with the -n switch. If name includes a `/', then `/part' isn't used. Thus `-n xyzzy' produces:
xyzzy/part01
xyzzy/part02
while `-n xyzzy/patch' produces:
xyzzy/patch01
xyzzy/patch02
and `-n xyzzy/patch01.' produces:
xyzzy/patch01.01
xyzzy/patch01.02
-c
--cut-mark
Start the shar with a cut line. A line saying `Cut here' is placed at the start of each output file.

Selecting how files are stocked

-T
--text-files
Treat all files as text, regardless of their contents.
-B
--uuencode
Treat all files as binary, use uuencode prior to packing. This increases the size of the archive. The recipient must have uudecode in order to unpack.
Use of uuencode is not appreciated by many on the net, because
people like to readily see, by mere inspection of a shell archive,
what it is about.
-M
--mixed-uuencode
Mixed mode. Automatically determine if the files are text or binary and archive correctly. Files found to be binary are uuencoded prior to packing. This option is selected by default. For a file is considered to be a text file, instead of a binary file, all the following should be true simultaneously:
  1. The file does not contain any ASCII control character besides BS (backspace), HT (horizontal tab), LF (new line) or FF (form feed).
  2. The file does not contains a DEL (delete).
  3. The file contains no character with its eighth-bit set.
  4. The file, unless totally empty, terminates with a LF (newline).
  5. No line in the file contains more than 200 characters. For counting purpose, lines are separated by a LF (newline).
-z
--gzip
Use gzip and uuencode on all files prior to packing. The recipient must have uudecode and gzip (used with -d) in order to unpack. Usage of -z in net shars will cause you to be flamed off the earth.
-g level
--level-for-gzip=level
When doing compression, use -level as a parameter to gzip. The -g option turns on the -z option by default. The default value is 9, that is, maximum compression.
-Z
--compress
Use compress and uuencode on all files prior to packing. The recipient must have uudecode and compress (used with -d) in order to unpack. Option -C is a synonymous for -Z, but is deprecated. Usage of -Z in net shars will cause you to be flamed off the earth.
-b bits
--bits-per-code=bits
When doing compression, use -bx as a parameter to compress. The -B option turns on the -Z option by default. The default value is 12, foreseeing the memory limitations of some compress programs on smallish systems, at unshar time.

Protecting against transmission errors

Transmission of shell archives is not always free of errors. So one should make consistency checks on the receiving site. A very simple (and unreliable) method is running the UNIX wc tool on the output file. This can report the number of characters in the file.

As one can guess this does not catch all errors. Especially changing of a character value does not change the computed check sum. To achieve this goal better method were invented and standardized. One very strong is MD5 (MD = message digests). This is standardized in RFC 1321. The produced shell scripts do not force the md5sum program to be installed on the system. This is necessary because it is not yet part of every UNIX. The program is however not necessary for producing the shell archive.

-w
--no-character-count
Do not check with `wc -c' after unpack. The default is to check.
-D
--no-md5-digest
Do not check with `md5sum' after unpack. The default is to check.
-F
--force-prefix
Prepend the prefix character to every line even if not required. This option may slightly increase the size of the archive, especially if -B or -Z is used. Normally, the prefix character is `X'. If the parameter to the -d option starts with `X', then the prefix character becomes `Y'.
-d string
--here-delimiter=string
Use string to delimit the files in the shar instead of `SHAR_EOF'. This is for those who want to personalize their shar files.

Producing different kinds of shars

-V
--vanilla-operation
This option produces vanilla shars which rely only upon the existence of echo, test and sed in the unpacking environment. The -V disables options offensive to the network cop (or brown shirt). It also changes the default from mixed mode -M to text mode -T. Warnings are produced if option -B, -z, -Z, -p or -M is specified (any of which does or might require uudecode, gzip or compress in the unpacking environment).
-P
--no-piping
In the shar file, use a temporary file to hold the file to uudecode, instead of using pipes. This option is mandatory when you know the unpacking uudecode is unwilling to merely read its standard input. Richard Marks wrote what is certainly the most (in)famous of these, for MSDOS :-). (Here is a side note from the maintainer. Why isnt't this option the default? In the past history of shar, it was decided that piping was better, surely because it is less demanding on disk space, and people seem to be happy with this. Besides, I think that the uudecode from Richard Marks, on MSDOS, is wrong in refusing to handle stdin. So far that I remember, he has the strong opinion that a program without any parameters should give its --help output. Besides that, should I say, his uuencode and uudecode programs are full-featured, one of the most complete set I ever saw. But Richard will not release his sources, he wants to stay in control.)
-x
--no-check-existing
Overwrite existing files without checking. If neither -x nor -X is specified, when unpacking itself, the shell archive will check for and not overwrite existing files (unless -c is passed as a parameter to the script when unpacking).
-X
--query-user
Interactively overwrite existing files. Use of -X produces shars which will cause problems with some unshar-style procedures, particularily when used together with vanilla mode (-V). Use this feature mainly for archives to be passed among agreeable parties. Certainly, -X is not for shell archives which are to be submitted to Usenet or other public networks. The problem is that unshar programs or procedures often feed `/bin/sh' from its standard input, thus putting `/bin/sh' and the shell archive script in competition for input lines. As an attempt to alleviate this problem, shar will try to detect if `/dev/tty' exists at the receiving site and will use it to read user replies. But this does not work in all cases, it may happen that the receiving user will have to avoid using unshar programs or procedures, and call /bin/sh directly. In vanilla mode, using `/dev/tty' is not even attempted.
-m
--no-timestamp
Avoid generating touch commands to restore the file modification dates when unpacking files from the archive. When the timestamp relationship is not preserved, some files like `configure' or `*.info' may be uselessly remade after unpacking. This is why, when this option is not used, a special effort is made to restore timestamps,
-Q
--quiet-unshar
Verbose off at unshar time. Disables the inclusion of comments to be output when the archive is unpacked.
-f
--basename
Use only the last file name component of each input file name, ignoring any prefix directories. This is sometimes useful when building a shar from several directories, or another directory. If a directory name is passed to shar, the substructure of that directory will be restored whether -f is specified or not.

Invoking the unshar program

The format of the unshar command is:

unshar [ option ] ... [ file ... ]

Each file is processed in turn, as a shell archive or a collection of shell archives. If no files are given, then standard input is processed instead.

Options:

--version
Print the version number of the program on standard output, then immediately exits.
--help
Print an help summary on standard output, then immediately exits.
-d directory
--directory=directory
Change directory to directory before unpacking any files.
-c
--overwrite
-f
--force
Passed as an option to the shar file. Many shell archive scripts (including those produced by shar 3.40 and newer) accepts a -c argument to indicate that existing files should be overwritten. The option -f is provided for a more unique interface. Many programs (such as cp and mv) use this option to trigger the very same action.
-e
--exit-0
This option exists mainly for people who collect many shell archives into a single mail folder. With this option, unshar isolates each different shell archive from the others which have been put in the same file, unpacking each in turn, from the beginning of the file towards its end. Its proper operation relies on the fact that many shar files are terminated by a `exit 0' at the beginning of a line. Option -e is internally equivalent to -E "exit 0".
-E string
--split-at=string
This option works like -e, but it allows you to specify the string that separates archives if `exit 0' isn't appropriate. For example, noticing that most `.signatures' have a `--' on a line right before them, one can sometimes use `--split-at=--' for splitting shell archives which lack the `exit 0' line at end. The signature will then be skipped altogether with the headers of the following message.

Miscellaneous considerations

Here is a place-holder for many considerations which do not fit elsewhere, while not worth a section for themselves.

Be careful that the output file(s) are not included in the inputs or shar may loop until the disk fills up. Be particularly careful when a directory is passed to shar that the output files are not in that directory (or a subdirectory of that directory).

When a directory is passed to shar, it may be scanned more than once, to conserve memory. Therefore, one should be careful to not change the directory contents while shar is running.

No attempt is made to restore the protection and modification dates for directories, even if this is done by default for files. Thus, if a directory is given to shar, the protection and modification dates of corresponding unpacked directory may not match those of the original.

Use of the -M or -B options will slow down the archive process. Use of the -z or -Z options may slow the archive process considerably.

Let us conclude by a showing a few examples of shar usage:

shar *.c > cprog.shar
shar -Q *.[ch] > cprog.shar
shar -B -l28 -oarc.sh. *.arc
shar -f /lcl/src/u*.c > u.sh

The first shows how to make a shell archive out of all C program sources. The second produces a shell archive with all `.c' and `.h' files, which unpacks silently. The third gives a shell archive of all uuencoded `.arc' files, into files `arc.sh.01' through to `arc.sh.nnn'. The last example gives a shell archive which will use only the file names at unpack time.

This document was generated on 7 November 1998 using the texi2html translator version 1.52.


GNU tar

GNU tar: an archiver tool

FTP release, version 1.12, 24 April 1997

Melissa Weisshaus, Jay Fenlason,
Thomas Bushnell, n/BSG, Amy Gorin

Table of Contents

  • Introduction
    • Some Definitions
    • What tar Does
    • How tar Archives are Named
    • POSIX Compliance
    • GNU tar Authors
    • Reporting bugs or suggestions
  • Tutorial Introduction to tar
    • Basic tar Operations and Options
    • The Three Most Frequently Used Operations
    • Two Frequently Used Options
      • The `--file' Option
      • The `--verbose' Option
      • Getting Help: Using the --help Option
    • How to Create Archives
      • Preparing a Practice Directory for Examples
      • Creating the Archive
      • Running `--create' with `--verbose'
      • Short Forms with `create'
      • Archiving Directories
    • How to List Archives
      • Listing the Contents of a Stored Directory
    • How to Extract Members from an Archive
      • Extracting an Entire Archive
      • Extracting Specific Files
      • Extracting Files that are Directories
      • Commands That Will Fail
    • Going Further Ahead in this Manual
  • Invoking GNU tar
    • General Synopsis of tar
    • Using tar Options
    • The Three Option Styles
      • Mnemonic Option Style
      • Short Option Style
      • Old Option Style
      • Mixing Option Styles
    • All tar Options
      • Operations
      • tar Options
      • Short Options Cross Reference
    • GNU tar documentation
    • Checking tar progress
    • Asking for Confirmation During Operations
  • GNU tar Operations
    • Basic GNU tar Operations
    • Advanced GNU tar Operations
      • The Five Advanced tar Operations
      • How to Add Files to Existing Archives: --append
        • Appending Files to an Archive
        • Multiple Files with the Same Name
      • Updating an Archive
        • How to Update an Archive Using --update
      • Combining Archives with --concatenate
      • Removing Archive Members Using `--delete'
      • Comparing Archive Members with the File System
    • Options Used by --extract
      • Options to Help Read Archives
        • Reading Full Records
        • Ignoring Blocks of Zeros
        • Ignore Fail Read
      • Changing How tar Writes Files
        • Options to Prevent Overwriting Files
        • Keep Old Files
        • Unlink First
        • Recursive Unlink
        • Setting Modification Times
        • Setting Access Permissions
        • Writing to Standard Output
        • Removing Files
      • Coping with Scarce Resources
        • Starting File
        • Same Order
    • Backup options
    • Notable tar Usages
    • Looking Ahead: The Rest of this Manual
  • Performing Backups and Restoring Files
    • Using tar to Perform Full Dumps
    • Using tar to Perform Incremental Dumps
    • The Incremental Options
    • Levels of Backups
    • Setting Parameters for Backups and Restoration
      • An Example Text of `Backup-specs'
      • Syntax for `Backup-specs'
    • Using the Backup Scripts
    • Using the Restore Script
  • Choosing Files and Names for tar
    • Choosing and Naming Archive Files
    • Selecting Archive Members
    • Reading Names from a File
    • Excluding Some Files
      • Problems with Using the exclude Options
    • Wildcards Patterns and Matching
    • Operating Only on New Files
    • Descending into Directories
    • Crossing Filesystem Boundaries
      • Changing the Working Directory
      • Absolute File Names
  • Date input formats
    • General date syntax
    • Calendar date item
    • Time of day item
    • Timezone item
    • Day of week item
    • Relative item in date strings
    • Pure numbers in date strings
    • Authors of getdate
  • Controlling the Archive Format
    • Making tar Archives More Portable
      • Portable Names
      • Symbolic Links
      • Old V7 Archives
      • GNU tar and POSIX tar
      • Checksumming Problems
    • Using Less Space through Compression
      • Creating and Reading Compressed Archives
      • Archiving Sparse Files
    • Handling File Attributes
    • The Standard Format
    • GNU Extensions to the Archive Format
    • Comparison of tar and cpio
  • Tapes and Other Archive Media
    • Device Selection and Switching
    • The Remote Tape Server
    • Some Common Problems and their Solutions
    • Blocking
      • Format Variations
      • The Blocking Factor of an Archive
    • Many Archives on One Tape
      • Tape Positions and Tape Marks
      • The mt Utility
    • Using Multiple Tapes
      • Archives Longer than One Tape or Disk
      • Tape Files
    • Including a Label in the Archive
    • Verifying Data as It is Stored
    • Write Protection
  • Index

Introduction

Welcome to the GNU tar manual. GNU tar is used to create and manipulate files (archives) which are actually collections of many other files; the program provides users with an organized and systematic method for controlling a large amount of data.

The first part of this chapter introduces you to various terms that will recur throughout the book. It also tells you who has worked on GNU tar and its documentation, and where you should send bug reports or comments.

The second chapter is a tutorial (see section Tutorial Introduction to tar) which provides a gentle introduction for people who are new to using tar. It is meant to be self contained, not requiring any reading from subsequent chapters to make sense. It moves from topic to topic in a logical, progressive order, building on information already explained.

Although the tutorial is paced and structured to allow beginners to learn how to use tar, it is not intended solely for beginners. The tutorial explains how to use the three most frequently used operations (`create', `list', and `extract') as well as two frequently used options (`file' and `verbose'). The other chapters do not refer to the tutorial frequently; however, if a section discusses something which is a complex variant of a basic concept, there may be a cross reference to that basic concept. (The entire book, including the tutorial, assumes that the reader understands some basic concepts of using a Unix-type operating system; see section Tutorial Introduction to tar.)

The third chapter presents the remaining five operations, and information about using tar options and option syntax.

@FIXME{this sounds more like a GNU Project Manuals Concept [tm] more than the reality. should think about whether this makes sense to say here, or not.} The other chapters are meant to be used as a reference. Each chapter presents everything that needs to be said about a specific topic.

One of the chapters (see section Date input formats) exists in its entirety in other GNU manuals, and is mostly self-contained. In addition, one section of this manual (see section The Standard Format) contains a big quote which is taken directly from tar sources.

In general, we give both the long and short (abbreviated) option names at least once in each section where the relevant option is covered, so that novice readers will become familiar with both styles. (A few options have no short versions, and the relevant sections will indicate this.)

Some Definitions

The tar program is used to create and manipulate tar archives. An archive is a single file which contains the contents of many files, while still identifying the names of the files, their owner(s), and so forth. (In addition, archives record access permissions, user and group, size in bytes, and last modification time. Some archives also record the file names in each archived directory, as well as other file and directory information.) You can use tar to create a new archive in a specified directory.

The files inside an archive are called members. Within this manual, we use the term file to refer only to files accessible in the normal ways (by ls, cat, and so forth), and the term member to refer only to the members of an archive. Similarly, a file name is the name of a file, as it resides in the filesystem, and a member name is the name of an archive member within the archive.

The term extraction refers to the process of copying an archive member (or multiple members) into a file in the filesystem. Extracting all the members of an archive is often called extracting the archive. The term unpack can also be used to refer to the extraction of many or all the members of an archive. Extracting an archive does not destroy the archive's structure, just as creating an archive does not destroy the copies of the files that exist outside of the archive. You may also list the members in a given archive (this is often thought of as "printing" them to the standard output, or the command line), or append members to a pre-existing archive. All of these operations can be peformed using tar.

What tar Does

The tar program provides the ability to create tar archives, as well as various other kinds of manipulation. For example, you can use tar on previously created archives to extract files, to store additional files, or to update or list files which were already stored.

Initially, tar archives were used to store files conveniently on magnetic tape. The name `tar' comes from this use; it stands for tape archiver. Despite the utility's name, tar can direct its output to available devices, files, or other programs (using pipes). tar may even access remote devices or files (as archives).

@FIXME{the following table entries need a bit of work..}

You can use tar archives in many ways. We want to stress a few of them: storage, backup, and transportation.

Storage
Often, tar archives are used to store related files for convenient file transfer over a network. For example, the GNU Project distributes its software bundled into tar archives, so that all the files relating to a particular program (or set of related programs) can be transferred as a single unit. A magnetic tape can store several files in sequence. However, the tape has no names for these files; it only knows their relative position on the tape. One way to store several files on one tape and retain their names is by creating a tar archive. Even when the basic transfer mechanism can keep track of names, as FTP can, the nuisance of handling multiple files, directories, and multiple links makes tar archives useful. Archive files are also used for long-term storage. You can think of this as transportation from the present into the future. (It is a science-fiction idiom that you can move through time as well as in space; the idea here is that tar can be used to move archives in all dimensions, even time!)
Backup
Because the archive created by tar is capable of preserving file information and directory structure, tar is commonly used for performing full and incremental backups of disks. A backup puts a collection of files (possibly pertaining to many users and projects) together on a disk or a tape. This guards against accidental destruction of the information in those files. GNU tar has special features that allow it to be used to make incremental and full dumps of all the files in a filesystem.
Transportation
You can create an archive on one system, transfer it to another system, and extract the contents there. This allows you to transport a group of files from one system to another.

How tar Archives are Named

Conventionally, tar archives are given names ending with `.tar'. This is not necessary for tar to operate properly, but this manual follows that convention in order to accustom readers to it and to make examples more clear.

Often, people refer to tar archives as "tar files," and archive members as "files" or "entries". For people familiar with the operation of tar, this causes no difficulty. However, in this manual, we consistently refer to "archives" and "archive members" to make learning to use tar easier for novice users.

POSIX Compliance

@FIXME{must ask franc,ois about this. dan hagerty thinks this might be an issue, but we're not really sure at this time. dan just tried a test case of mixing up options' orders while the variable was set, and there was no problem...}

We make some of our recommendations throughout this book for one reason in addition to what we think of as "good sense". The main additional reason for a recommendation is to be compliant with the POSIX standards. If you set the shell environment variable POSIXLY_CORRECT, GNU tar will force you to adhere to these standards. Therefore, if this variable is set and you violate one of the POSIX standards in the way you phrase a command, for example, GNU tar will not allow the command and will signal an error message. You would then have to reorder the options or rephrase the command to comply with the POSIX standards.

There is a chance in the future that, if you set this environment variable, your archives will be forced to comply with POSIX standards, also. No GNU tar extensions will be allowed.

GNU tar Authors

GNU tar was originally written by John Gilmore, and modified by many people. The GNU enhancements were written by Jay Fenlason, then Joy Kendall, and the whole package has been further maintained by Thomas Bushnell, n/BSG, and finally Fran@,{c}ois Pinard, with the help of numerous and kind users.

We wish to stress that tar is a collective work, and owes much to all those people who reported problems, offered solutions and other insights, or shared their thoughts and suggestions. An impressive, yet partial list of those contributors can be found in the `THANKS' file from the GNU tar distribution.

@FIXME{i want all of these names mentioned, Absolutely. BUT, i'm not sure i want to spell out the history in this detail, at least not for the printed book. i'm just not sure it needs to be said this way. i'll think about it.}

@FIXME{History is more important, and surely more interesting, than actual names. Quoting names without history would be meaningless. FP}

Jay Fenlason put together a draft of a GNU tar manual, borrowing notes from the original man page from John Gilmore. This draft has been distributed in tar versions 1.04 (or even before?) @FIXME{huh? IMO, either we know or we don't; the parenthetical is confusing.} through 1.10, then withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy Gorin worked on a tutorial and manual for GNU tar. Fran@,{c}ois Pinard put version 1.11.8 of the manual together by taking information from all these sources and merging them. Melissa Weisshaus finally edited and redesigned the book to create version 1.12. @FIXME{update version number as necessary; i'm being optimistic!} @FIXME{Someone [maybe karl berry? maybe bob chassell? maybe melissa? maybe julie sussman?] needs to properly index the thing.}

For version 1.12, Daniel Hagerty contributed a great deal of technical consulting. In particular, he is the primary author of section Performing Backups and Restoring Files.

Reporting bugs or suggestions

If you find problems or have suggestions about this program or manual, please report them to `bug-gnu-utils@prep.ai.mit.edu'.

Tutorial Introduction to tar

This chapter guides you through some basic examples of three tar operations: `--create', `--list', and `--extract'. If you already know how to use some other version of tar, then you may not need to read this chapter. This chapter omits most complicated details about how tar works.

This chapter is paced to allow beginners to learn about tar slowly. At the same time, we will try to cover all the basic aspects of these three operations. In order to accomplish both of these tasks, we have made certain assumptions about your knowledge before reading this manual, and the hardware you will be using:

  • Before you start to work through this tutorial, you should understand what the terms "archive" and "archive member" mean (see section Some Definitions). In addition, you should understand something about how Unix-type operating systems work, and you should know how to use some basic utilities. For example, you should know how to create, list, copy, rename, edit, and delete files and directories; how to change between directories; and how to figure out where you are in the filesystem. You should have some basic understanding of directory structure and how files are named according to which directory they are in. You should understand concepts such as standard output and standard input, what various definitions of the term "argument" mean, the differences between relative and absolute path names, and @FIXME{what else?}.
  • This manual assumes that you are working from your own home directory (unless we state otherwise). In this tutorial, you will create a directory to practice tar commands in. When we show path names, we will assume that those paths are relative to your home directory. For example, my home directory path is `/home/fsf/melissa'. All of my examples are in a subdirectory of the directory named by that path name; the subdirectory is called `practice'.
  • In general, we show examples of archives which exist on (or can be written to, or worked with from) a directory on a hard disk. In most cases, you could write those archives to, or work with them on any other device, such as a tape drive. However, some of the later examples in the tutorial and next chapter will not work on tape drives. Additionally, working with tapes is much more complicated than working with hard disks. For these reasons, the tutorial does not cover working with tape drives. See section Tapes and Other Archive Media for complete information on using tar archives with tape drives. @FIXME{this is a cop out. need to add some simple tape drive info.}

In the examples, `$' represents a typical shell prompt. It precedes lines you should type; to make this more clear, those lines are shown in this font, as opposed to lines which represent the computer's response; those lines are shown in this font, or sometimes `like this'. When we have lines which are too long to be displayed in any other way, we will show them like this:

This is an example of a line which would otherwise not fit in this space.

@FIXME{how often do we use smallexample?}

Basic tar Operations and Options

tar can take a wide variety of arguments which specify and define the actions it will have on the particular set of files or the archive. The main types of arguments to tar fall into one of two classes: operations, and options.

Some arguments fall into a class called operations; exactly one of these is both allowed and required for any instance of using tar; you may not specify more than one. People sometimes speak of operating modes. You are in a particular operating mode when you have specified the operation which specifies it; there are eight operations in total, and thus there are eight operating modes.

The other arguments fall into the class known as options. You are not required to specify any options, and you are allowed to specify more than one at a time (depending on the way you are using tar at that time). Some options are used so frequently, and are so useful for helping you type commands more carefully that they are effectively "required". We will discuss them in this chapter.

You can write most of the tar operations and options in any of three forms: long (mnemonic) form, short form, and old style. Some of the operations and options have no short or "old" forms; however, the operations and options which we will cover in this tutorial have corresponding abbreviations. @FIXME{make sure this is still the case, at the end} We will indicate those abbreviations appropriately to get you used to seeing them. (Note that the "old style" option forms exist in GNU tar for compatibility with Unix tar. We present a full discussion of this way of writing options and operations appears in section Old Option Style, and we discuss the other two styles of writing options in section Mnemonic Option Style and section Short Option Style.)

In the examples and in the text of this tutorial, we usually use the long forms of operations and options; but the "short" forms produce the same result and can make typing long tar commands easier. For example, instead of typing

tar --create --verbose --file=afiles.tar apple angst aspic

you can type

tar -c -v -f afiles.tar apple angst aspic

or even

tar -cvf afiles.tar apple angst aspic

For more information on option syntax, see section Advanced GNU tar Operations. In discussions in the text, when we name an option by its long form, we also give the corresponding short option in parentheses.

The term, "option", can be confusing at times, since "operations" are often lumped in with the actual, optional "options" in certain general class statements. For example, we just talked about "short and long forms of options and operations". However, experienced tar users often refer to these by shorthand terms such as, "short and long options". This term assumes that the "operations" are included, also. Context will help you determine which definition of "options" to use.

Similarly, the term "command" can be confusing, as it is often used in two different ways. People sometimes refer to tar "commands". A tar command is the entire command line of user input which tells tar what to do -- including the operation, options, and any arguments (file names, pipes, other commands, etc). However, you will also sometimes hear the term "the tar command". When the word "command" is used specifically like this, a person is usually referring to the tar operation, not the whole line. Again, use context to figure out which of the meanings the speaker intends.

The Three Most Frequently Used Operations

Here are the three most frequently used operations (both short and long forms), as well as a brief description of their meanings. The rest of this chapter will cover how to use these operations in detail. We will present the rest of the operations in the next chapter.

--create
-c
Create a new tar archive.
--list
-t
List the contents of an archive.
--extract
-x
Extract one or more members from an archive.

Two Frequently Used Options

To understand how to run tar in the three operating modes listed previously, you also need to understand how to use two of the options to tar: `--file' (which takes an archive file as an argument) and `--verbose'. (You are usually not required to specify either of these options when you run tar, but they can be very useful in making things more clear and helping you avoid errors.)

The `--file' Option

--file=archive-name
-f archive-name
Specify the name of an archive file.

You can specify an argument for the --file=archive-name (-f archive-name) option whenever you use tar; this option determines the name of the archive file that tar will work on.

If you don't specify this argument, then tar will use a default, usually some physical tape drive attached to your machine. If there is no tape drive attached, or the default is not meaningful, then tar will print an error message. The error message might look roughly like one of the following:

tar: can't open /dev/rmt8 : No such device or address
tar: can't open /dev/rsmt0 : I/O error

To avoid confusion, we recommend that you always specfiy an archive file name by using --file=archive-name (-f archive-name) when writing your tar commands. For more information on using the --file=archive-name (-f archive-name) option, see section Choosing and Naming Archive Files.

The `--verbose' Option

--verbose
-v
Show the files being worked on as tar is running.

--verbose (-v) shows details about the results of running tar. This can be especially useful when the results might not be obvious. For example, if you want to see the progress of tar as it writes files into the archive, you can use the `--verbose' option. In the beginning, you may find it useful to use `--verbose' at all times; when you are more accustomed to tar, you will likely want to use it at certain times but not at others. We will use `--verbose' at times to help make something clear, and we will give many examples both using and not using `--verbose' to show the differences.

Sometimes, a single instance of `--verbose' on the command line will show a full, `ls' style listing of an archive or files, giving sizes, owners, and similar information. Other times, `--verbose' will only show files or members that the particular operation is operating on at the time. In the latter case, you can use `--verbose' twice in a command to get a listing such as that in the former case. For example, instead of saying

tar -cvf afiles.tar apple angst aspic

above, you might say

tar -cvvf afiles.tar apple angst aspic

This works equally well using short or long forms of options. Using long forms, you would simply write out the mnemonic form of the option twice, like this:

$ tar --create --verbose --verbose ...

Note that you must double the hyphens properly each time.

Later in the tutorial, we will give examples using `--verbose --verbose'.

Getting Help: Using the --help Option

--help
The `--help' option to tar prints out a very brief list of all operations and option available for the current version of tar available on your system.

How to Create Archives

@UNREVISED

One of the basic operations of tar is --create (-c), which you use to create a tar archive. We will explain `--create' first because, in order to learn about the other operations, you will find it useful to have an archive available to practice on.

To make this easier, in this section you will first create a directory containing three files. Then, we will show you how to create an archive (inside the new directory). Both the directory, and the archive are specifically for you to practice on. The rest of this chapter and the next chapter will show many examples using this directory and the files you will create: some of those files may be other directories and other archives.

The three files you will archive in this example are called `blues', `folk', and `jazz'. The archive is called `collection.tar'.

This section will proceed slowly, detailing how to use `--create' in verbose mode, and showing examples using both short and long forms. In the rest of the tutorial, and in the examples in the next chapter, we will proceed at a slightly quicker pace. This section moves more slowly to allow beginning users to understand how tar works.

Preparing a Practice Directory for Examples

To follow along with this and future examples, create a new directory called `practice' containing files called `blues', `folk' and `jazz'. The files can contain any information you like: ideally, they should contain information which relates to their names, and be of different lengths. Our examples assume that `practice' is a subdirectory of your home directory.

Now cd to the directory named `practice'; `practice' is now your working directory. (Please note: Although the full path name of this directory is `/homedir/practice', in our examples we will refer to this directory as `practice'; the homedir is presumed.

In general, you should check that the files to be archived exist where you think they do (in the working directory) by running ls. Because you just created the directory and the files and have changed to that directory, you probably don't need to do that this time.

It is very important to make sure there isn't already a file in the working directory with the archive name you intend to use (in this case, `collection.tar'), or that you don't care about its contents. Whenever you use `create', tar will erase the current contents of the file named by --file=archive-name (-f archive-name) if it exists. tar will not tell you if you are about to overwrite a file unless you specify an option which does this @FIXME{xref to the node for --backup!}. To add files to an existing archive, you need to use a different option, such as --append (-r); see section How to Add Files to Existing Archives: --append for information on how to do this.

Creating the Archive

To place the files `blues', `folk', and `jazz' into an archive named `collection.tar', use the following command:

$ tar --create --file=collection.tar blues folk jazz

The order of the arguments is not very important, when using long option forms. You could also say:

$ tar blues --create folk --file=collection.tar jazz

However, you can see that this order is harder to understand; this is why we will list the arguments in the order that makes the commands easiest to understand (and we encourage you to do the same when you use tar, to avoid errors).

Note that the part of the command which says, --file=collection.tar is considered to be one argument. If you substituted any other string of characters for `collection.tar', then that string would become the name of the archive file you create.

The order of the options becomes more important when you begin to use short forms. With short forms, if you type commands in the wrong order (even if you type them correctly in all other ways), you may end up with results you don't expect. For this reason, it is a good idea to get into the habit of typing options in the order that makes inherent sense. See section Short Forms with `create' for more information on this.

In this example, you type the command as shown above: `--create' is the operation which creates the new archive (`collection.tar'), and `--file' is the option which lets you give it the name you chose. The files, `blues', `folk', and `jazz', are now members of the archive, `collection.tar' (they are file name arguments to the `--create' operation) @FIXME{xref here to the discussion of file name args?}. Now that they are are in the archive, they are called archive members, not files @FIXME{xref to definitions?}.

When you create an archive, you must specify which files you want placed in the archive. If you do not specify any archive members, GNU tar will complain.

If you now list the contents of the working directory (ls), you will find the archive file listed as well as the files you saw previously:

blues   folk   jazz   collection.tar

Creating the archive `collection.tar' did not destroy the copies of the files in the directory.

Keep in mind that if you don't indicate an operation, tar will not run and will prompt you for one. If you don't name any files, tar will complain. You must have write access to the working directory, or else you will not be able to create an archive in that directory.

Caution: Do not attempt to use --create (-c) to add files to an existing archive; it will delete the archive and write a new one. Use --append (-r) instead. See section How to Add Files to Existing Archives: --append.

Running `--create' with `--verbose'

If you include the --verbose (-v) option on the command line, tar will list the files it is acting on as it is working. In verbose mode, the create example above would appear as:

$ tar --create --verbose --file=collection.tar blues folk jazz
blues
folk
jazz

This example is just like the example we showed which did not use `--verbose', except that tar generated the remaining lines (note the different font styles).

In the rest of the examples in this chapter, we will frequently use verbose mode so we can show actions or tar responses that you would otherwise not see, and which are important for you to understand.

Short Forms with `create'

As we said before, the --create (-c) operation is one of the most basic uses of tar, and you will use it countless times. Eventually, you will probably want to use abbreviated (or "short") forms of options. A full discussion of the three different forms that options can take appears in section The Three Option Styles; for now, here is what the previous example (including the --verbose (-v) option) looks like using short option forms:

$ tar -cvf collection.tar blues folk jazz
blues
folk
jazz

As you can see, the system responds the same no matter whether you use long or short option forms.

@FIXME{i don't like how this is worded:} One difference between using short and long option forms is that, although the exact placement of arguments following options is no more specific when using short forms, it is easier to become confused and make a mistake when using short forms. For example, suppose you attempted the above example in the following way:

$ tar -cfv collection.tar blues folk jazz

In this case, tar will make an archive file called `v', containing the files `blues', `folk', and `jazz', because the `v' is the closest "file name" to the `-f' option, and is thus taken to be the chosen archive file name. tar will try to add a file called `collection.tar' to the `v' archive file; if the file `collection.tar' did not already exist, tar will report an error indicating that this file does not exist. If the file `collection.tar' does already exist (e.g., from a previous command you may have run), then tar will add this file to the archive. Because the `-v' option did not get registered, tar will not run under `verbose' mode, and will not report its progress.

The end result is that you may be quite confused about what happened, and possibly overwrite a file. To illustrate this further, we will show you how an example we showed previously would look using short forms.

This example,

$ tar blues --create folk --file=collection.tar jazz

is confusing as it is. When shown using short forms, however, it becomes much more so:

$ tar blues -c folk -f collection.tar jazz

It would be very easy to put the wrong string of characters immediately following the `-f', but doing that could sacrifice valuable data.

For this reason, we recommend that you pay very careful attention to the order of options and placement of file and archive names, especially when using short option forms. Not having the option name written out mnemonically can affect how well you remember which option does what, and therefore where different names have to be placed. (Placing options in an unusual order can also cause tar to report an error if you have set the shell environment variable, POSIXLY_CORRECT; see section POSIX Compliance for more information on this.)

Archiving Directories

You can archive a directory by specifying its directory name as a file name argument to tar. The files in the directory will be archived relative to the working directory, and the directory will be re-created along with its contents when the archive is extracted.

To archive a directory, first move to its superior directory. If you have followed the previous instructions in this tutorial, you should type:

$ cd ..
$

This will put you into the directory which contains `practice', i.e. your home directory. Once in the superior directory, you can specify the subdirectory, `practice', as a file name argument. To store `practice' in the new archive file `music.tar', type:

$ tar --create --verbose --file=music.tar practice

tar should output:

practice/
practice/blues
practice/folk
practice/jazz
practice/collection.tar

Note that the archive thus created is not in the subdirectory `practice', but rather in the current working directory--the directory from which tar was invoked. Before trying to archive a directory from its superior directory, you should make sure you have write access to the superior directory itself, not only the directory you are trying archive with tar. For example, you will probably not be able to store your home directory in an archive by invoking tar from the root directory; See section Absolute File Names. (Note also that `collection.tar', the original archive file, has itself been archived. tar will accept any file as a file to be archived, regardless of its content. When `music.tar' is extracted, the archive file `collection.tar' will be re-written into the file system).

If you give tar a command such as

$ tar --create --file=foo.tar .

tar will report `tar: foo.tar is the archive; not dumped'. This happens because tar creates the archive `foo.tar' in the current directory before putting any files into it. Then, when tar attempts to add all the files in the directory `.' to the archive, it notices that the file `foo.tar' is the same as the archive, and skips it. (It makes no sense to put an archive into itself.) GNU tar will continue in this case, and create the archive normally, except for the exclusion of that one file. (Please note: Other versions of tar are not so clever; they will enter an infinite loop when this happens, so you should not depend on this behavior unless you are certain you are running GNU tar. @FIXME{bob doesn't like this sentence, since he does it all the time, and we've been doing it in the editing passes for this manual: In general, make sure that the archive is not inside a directory being dumped.})

How to List Archives

Frequently, you will find yourself wanting to determine exactly what a particular archive contains. You can use the --list (-t) operation to get the member names as they currently appear in the archive, as well as various attributes of the files at the time they were archived. For example, you can examine the archive `collection.tar' that you created in the last section with the command,

$ tar --list --file=collection.tar

The output of tar would then be:

blues
folk
jazz

@FIXME{we hope this will change. if it doesn't, need to show the creation of bfiles somewhere above!!! : }

The archive `bfiles.tar' would list as follows:

./birds
baboon
./box

Be sure to use a --file=archive-name (-f archive-name) option just as with --create (-c) to specify the name of the archive.

If you use the --verbose (-v) option with `--list', then tar will print out a listing reminiscent of `ls -l', showing owner, file size, and so forth.

If you had used --verbose (-v) mode, the example above would look like:

$ tar --list --verbose --file=collection.tar folk
-rw-rw-rw- myself user 62 1990-05-23 10:55 folk

You can specify one or more individual member names as arguments when using `list'. In this case, tar will only list the names of members you identify. For example, tar --list --file=afiles.tar apple would only print `apple'.

@FIXME{we hope the relevant aspects of this will change:}Because tar preserves paths, file names must be specified as they appear in the archive (ie., relative to the directory from which the archive was created). Therefore, it is essential when specifying member names to tar that you give the exact member names. For example, tar --list --file=bfiles birds would produce an error message something like `tar: birds: Not found in archive', because there is no member named `birds', only one named `./birds'. While the names `birds' and `./birds' name the same file, member names are compared using a simplistic name comparison, in which an exact match is necessary. See section Absolute File Names.

However, tar --list --file=collection.tar folk would respond with `folk', because `folk' is in the archive file `collection.tar'. If you are not sure of the exact file name, try listing all the files in the archive and searching for the one you expect to find; remember that if you use `--list' with no file names as arguments, tar will print the names of all the members stored in the specified archive.

Listing the Contents of a Stored Directory

@UNREVISED

@FIXME{i changed the order of these nodes around and haven't had a chance to play around with this node's example, yet. i have to play with it and see what it actually does for my own satisfaction, even if what it says *is* correct..}

To get information about the contents of an archived directory, use the directory name as a file name argument in conjunction with --list (-t). To find out file attributes, include the --verbose (-v) option.

For example, to find out about files in the directory `practice', in the archive file `music.tar', type:

$ tar --list --verbose --file=music.tar practice

tar responds:

drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
-rw-rw-rw- myself user 42 1990-05-21 13:29 practice/blues
-rw-rw-rw- myself user 62 1990-05-23 10:55 practice/folk
-rw-rw-rw- myself user 40 1990-05-21 13:30 practice/jazz
-rw-rw-rw- myself user 10240 1990-05-31 21:49 practice/collection.tar

When you use a directory name as a file name argument, tar acts on all the files (including sub-directories) in that directory.

How to Extract Members from an Archive

@UNREVISED

Creating an archive is only half the job--there is no point in storing files in an archive if you can't retrieve them. The act of retrieving members from an archive so they can be used and manipulated as unarchived files again is called extraction. To extract files from an archive, use the --extract (--get, -x) operation. As with --create (-c), specify the name of the archive with --file=archive-name (-f archive-name). Extracting an archive does not modify the archive in any way; you can extract it multiple times if you want or need to.

Using `--extract', you can extract an entire archive, or specific files. The files can be directories containing other files, or not. As with --create (-c) and --list (-t), you may use the short or the long form of the operation without affecting the performance.

Extracting an Entire Archive

To extract an entire archive, specify the archive file name only, with no individual file names as arguments. For example,

$ tar -xvf collection.tar

produces this:

-rw-rw-rw- me user     28 1996-10-18 16:31 jazz
-rw-rw-rw- me user     21 1996-09-23 16:44 blues
-rw-rw-rw- me user     20 1996-09-23 16:44 folk

Extracting Specific Files

To extract specific archive members, give their exact member names as arguments, as printed by --list (-t). If you had mistakenly deleted one of the files you had placed in the archive `collection.tar' earlier (say, `blues'), you can extract it from the archive without changing the archive's structure. It will be identical to the original file `blues' that you deleted. @FIXME{check this; will the times, permissions, owner, etc be the same, also?}

First, make sure you are in the `practice' directory, and list the files in the directory. Now, delete the file, `blues', and list the files in the directory again.

You can now extract the member `blues' from the archive file `collection.tar' like this:

$ tar --extract --file=collection.tar blues

If you list the files in the directory again, you will see that the file `blues' has been restored, with its original permissions, creation times, and owner. @FIXME{This is only accidentally true, but not in general. In most cases, one has to be root for restoring the owner, and use a special option for restoring permissions. Here, it just happens that the restoring user is also the owner of the archived members, and that the current umask is compatible with original permissions.} (These parameters will be identical to those which the file had when you originally placed it in the archive; any changes you may have made before deleting the file from the file system, however, will not have been made to the archive member.) The archive file, `collection.tar', is the same as it was before you extracted `blues'. You can confirm this by running tar with --list (-t).

@FIXME{we hope this will change:}Remember that as with other operations, specifying the exact member name is important. tar --extract --file=bfiles.tar birds will fail, because there is no member named `birds'. To extract the member named `./birds', you must specify tar --extract --file=bfiles.tar ./birds. To find the exact member names of the members of an archive, use --list (-t) (see section How to List Archives).

If you give the --verbose (-v) option, then --extract (--get, -x) will print the names of the archive members as it extracts them.

Extracting Files that are Directories

Extracting directories which are members of an archive is similar to extracting other files. The main difference to be aware of is that if the extracted directory has the same name as any directory already in the working directory, then files in the extracted directory will be placed into the directory of the same name. Likewise, if there are files in the pre-existing directory with the same names as the members which you extract, the files from the extracted archive will overwrite the files already in the working directory (and possible subdirectories). This will happen regardless of whether or not the files in the working directory were more recent than those extracted.

However, if a file was stored with a directory name as part of its file name, and that directory does not exist under the working directory when the file is extracted, tar will create the directory.

We can demonstrate how to use `--extract' to extract a directory file with an example. Change to the `practice' directory if you weren't there, and remove the files `folk' and `jazz'. Then, go back to the parent directory and extract the archive `music.tar'. You may either extract the entire archive, or you may extract only the files you just deleted. To extract the entire archive, don't give any file names as arguments after the archive name `music.tar'. To extract only the files you deleted, use the following command:

$ tar -xvf music.tar practice/folk practice/jazz

@FIXME{need to show tar's response; used verbose above. also, here's a good place to demonstrate the -v -v thing. have to write that up (should be trivial, but i'm too tired!).}

Because you created the directory with `practice' as part of the file names of each of the files by archiving the `practice' directory as `practice', you must give `practice' as part of the file names when you extract those files from the archive.

@FIXME{IMPORTANT! show the final structure, here. figure out what it will be.}

Commands That Will Fail

Here are some sample commands you might try which will not work, and why they won't work.

If you try to use this command,

$ tar -xvf music.tar folk jazz

you will get the following response:

tar: folk: Not found in archive
tar: jazz: Not found in archive
$

This is because these files were not originally in the parent directory `..', where the archive is located; they were in the `practice' directory, and their file names reflect this:

$ tar -tvf music.tar
practice/folk
practice/jazz
practice/rock

@FIXME{make sure the above works when going through the examples in order...}

Likewise, if you try to use this command,

$ tar -tvf music.tar folk jazz

you would get a similar response. Members with those names are not in the archive. You must use the correct member names in order to extract the files from the archive.

If you have forgotten the correct names of the files in the archive, use tar --list --verbose to list them correctly.

@FIXME{more examples, here? hag thinks it's a good idea.}

Going Further Ahead in this Manual

@FIXME{need to write up a node here about the things that are going to be in the rest of the manual.}

Invoking GNU tar

@UNREVISED

This chapter is about how one invokes the GNU tar command, from the command synopsis (see section General Synopsis of tar). There are numerous options, and many styles for writing them. One mandatory option specifies the operation tar should perform (see section Operations), other options are meant to detail how this operation should be performed (see section tar Options). Non-option arguments are not always interpreted the same way, depending on what the operation is.

You will find in this chapter everything about option styles and rules for writing them (see section The Three Option Styles). On the other hand, operations and options are fully described elsewhere, in other chapters. Here, you will find only synthetic descriptions for operations and options, together with pointers to other parts of the tar manual.

Some options are so special they are fully described right in this chapter. They have the effect of inhibiting the normal operation of tar or else, they globally alter the amount of feedback the user receives about what is going on. These are the --help and --version (see section GNU tar documentation), --verbose (-v) (see section Checking tar progress) and --interactive (-w) options (see section Asking for Confirmation During Operations).

General Synopsis of tar

The GNU tar program is invoked as either one of:

tar option... [name]...
tar letter... [argument]... [option]... [name]...

The second form is for when old options are being used.

You can use tar to store files in an archive, to extract them from an archive, and to do other types of archive manipulation. The primary argument to tar, which is called the operation, specifies which action to take. The other arguments to tar are either options, which change the way tar performs an operation, or file names or archive members, which specify the files or members tar is to act on.

You can actually type in arguments in any order, even if in this manual the options always precede the other arguments, to make examples easier to understand. Further, the option stating the main operation mode (the tar main command) is usually given first.

Each name in the synopsis above is interpreted as an archive member name when the main command is one of --compare (--diff, -d), --delete, --extract (--get, -x), --list (-t) or --update (-u). When naming archive members, you must give the exact name of the member in the archive, as it is printed by --list (-t). For --append (-r) and --create (-c), these name arguments specify the names of either files or directory hierarchies to place in the archive. These files or hierarchies should already exist in the file system, prior to the execution of the tar command.

tar interprets relative file names as being relative to the working directory. tar will make all file names relative (by removing leading slashes when archiving or restoring files), unless you specify otherwise (using the --absolute-names (-P) option). See section Absolute File Names, for more information about --absolute-names (-P).

If you give the name of a directory as either a file name or a member name, then tar acts recursively on all the files and directories beneath that directory. For example, the name `/' identifies all the files in the filesystem to tar.

The distinction between file names and archive member names is especially important when shell globbing is used, and sometimes a source of confusion for newcomers. See section Wildcards Patterns and Matching, for more information about globbing. The problem is that shells may only glob using existing files in the file system. Only tar itself may glob on archive members, so when needed, you must ensure that wildcard characters reach tar without being interpreted by the shell first. Using a backslash before `*' or `?', or putting the whole argument between quotes, is usually sufficient for this.

Even if names are often specified on the command line, they can also be read from a text file in the file system, using the --files-from=file-of-names (-T file-of-names) option.

If you don't use any file name arguments, --append (-r), --delete and --concatenate (--catenate, -A) will do nothing, while --create (-c) will usually yield a diagnostic and inhibit tar execution. The other operations of tar (--list (-t), --extract (--get, -x), --compare (--diff, -d), and --update (-u)) will act on the entire contents of the archive.

Besides successful exits, GNU tar may fail for many reasons. Some reasons correspond to bad usage, that is, when the tar command is improperly written. Errors may be encountered later, while encountering an error processing the archive or the files. Some errors are recoverable, in which case the failure is delayed until tar has completed all its work. Some errors are such that it would not meaningful, or at least risky, to continue processing: tar then aborts processing immediately. All abnormal exits, whether immediate or delayed, should always be clearly diagnosed on stderr, after a line stating the nature of the error.

GNU tar returns only a few exit statuses. I'm really aiming simplicity in that area, for now. If you are not using the --compare (--diff, -d) option, zero means that everything went well, besides maybe innocuous warnings. Nonzero means that something went wrong. Right now, as of today, "nonzero" is almost always 2, except for remote operations, where it may be 128.

Using tar Options

GNU tar has a total of eight operating modes which allow you to perform a variety of tasks. You are required to choose one operating mode each time you employ the tar program by specifying one, and only one operation as an argument to the tar command (two lists of four operations each may be found at section The Three Most Frequently Used Operations and section The Five Advanced tar Operations). Depending on circumstances, you may also wish to customize how the chosen operating mode behaves. For example, you may wish to change the way the output looks, or the format of the files that you wish to archive may require you to do something special in order to make the archive look right.

You can customize and control tar's performance by running tar with one or more options (such as --verbose (-v), which we used in the tutorial). As we said in the tutorial, options are arguments to tar which are (as their name suggests) optional. Depending on the operating mode, you may specify one or more options. Different options will have different effects, but in general they all change details of the operation, such as archive format, archive name, or level of user interaction. Some options make sense with all operating modes, while others are meaningful only with particular modes. You will likely use some options frequently, while you will only use others infrequently, or not at all. (A full list of options is available in see section All tar Options.)

Note that tar options are case sensitive. For example, the options `-T' and `-t' are different; the first requires an argument for stating the name of a file providing a list of names, while the second does not require an argument and is another way to write --list (-t).

In addition to the eight operations, there are many options to tar, and three different styles for writing both: long (mnemonic) form, short form, and old style. These styles are discussed below. Both the options and the operations can be written in any of these three styles.

@FIXME{menu at end of this node. need to think of an actual outline for this chapter; probably do that after stuff from chap. 4 is incorporated.}

The Three Option Styles

There are three styles for writing operations and options to the command line invoking tar. The different styles were developed at different times during the history of tar. These styles will be presented below, from the most recent to the oldest.

Some options must take an argument. (For example, --file=archive-name (-f archive-name) takes the name of an archive file as an argument. If you do not supply an archive file name, tar will use a default, but this can be confusing; thus, we recommend that you always supply a specific archive file name.) Where you place the arguments generally depends on which style of options you choose. We will detail specific information relevant to each option style in the sections on the different option styles, below. The differences are subtle, yet can often be very important; incorrect option placement can cause you to overwrite a number of important files. We urge you to note these differences, and only use the option style(s) which makes the most sense to you until you feel comfortable with the others.

@FIXME{hag to write a brief paragraph on the option(s) which can optionally take an argument}

Mnemonic Option Style

@FIXME{have to decide whether or ot to replace other occurrences of "mnemonic" with "long", or *ugh* vice versa.}

Each option has at least one long (or mnemonic) name starting with two dashes in a row, e.g. `list'. The long names are more clear than their corresponding short or old names. It sometimes happens that a single mnemonic option has many different different names which are synonymous, such as `--compare' and `--diff'. In addition, long option names can be given unique abbreviations. For example, `--cre' can be used in place of `--create' because there is no other mnemonic option which begins with `cre'. (One way to find this out is by trying it and seeing what happens; if a particular abbreviation could represent more than one option, tar will tell you that that abbreviation is ambiguous and you'll know that that abbreviation won't work. You may also choose to run `tar --help' to see a list of options. Be aware that if you run tar with a unique abbreviation for the long name of an option you didn't want to use, you are stuck; tar will perform the command as ordered.)

Mnemonic options are meant to be obvious and easy to remember, and their meanings are generally easier to discern than those of their corresponding short options (see below). For example:

$ tar --create --verbose --blocking-factor=20 --file=/dev/rmt0

gives a fairly good set of hints about what the command does, even for those not fully acquainted with tar.

Mnemonic options which require arguments take those arguments immediately following the option name; they are introduced by an equal sign. For example, the `--file' option (which tells the name of the tar archive) is given a file such as `archive.tar' as argument by using the notation `--file=archive.tar' for the mnemonic option.

Short Option Style

Most options also have a short option name. Short options start with a single dash, and are followed by a single character, e.g. `-t' (which is equivalent to `--list'). The forms are absolutely identical in function; they are interchangeable.

The short option names are faster to type than long option names.

Short options which require arguments take their arguments immediately following the option, usually separated by white space. It is also possible to stick the argument right after the short option name, using no intervening space. For example, you might write `-f archive.tar' or `-farchive.tar' instead of using `--file=archive.tar'. Both `--file=archive-name' and `-f archive-name' denote the option which indicates a specific archive, here named `archive.tar'.

Short options' letters may be clumped together, but you are not required to do this (as compared to old options; see below). When short options are clumped as a set, use one (single) dash for them all, e.g. `tar -cvf'. Only the last option in such a set is allowed to have an argument(1).

When the options are separated, the argument for each option which requires an argument directly follows that option, as is usual for Unix programs. For example:

$ tar -c -v -b 20 -f /dev/rmt0

If you reorder short options' locations, be sure to move any arguments that belong to them. If you do not move the arguments properly, you may end up overwriting files.

Old Option Style

@UNREVISED

Like short options, old options are single letters. However, old options must be written together as a single clumped set, without spaces separating them or dashes preceding them(2). This set of letters must be the first to appear on the command line, after the tar program name and some whitespace; old options cannot appear anywhere else. The letter of an old option is exactly the same letter as the corresponding short option. For example, the old option `t' is the same as the short option `-t', and consequently, the same as the mnemonic option `--list'. So for example, the command `tar cv' specifies the option `-v' in addition to the operation `-c'.

@FIXME{bob suggests having an uglier example. :-) }

When options that need arguments are given together with the command, all the associated arguments follow, in the same order as the options. Thus, the example given previously could also be written in the old style as follows:

$ tar cvbf 20 /dev/rmt0

Here, `20' is the argument of `-b' and `/dev/rmt0' is the argument of `-f'.

On the other hand, this old style syntax makes it difficult to match option letters with their corresponding arguments, and is often confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20' is the argument for `-b', `/dev/rmt0' is the argument for `-f', and `-v' does not have a corresponding argument. Even using short options like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next to the option they pertain to.

If you want to reorder the letters in the old option argument, be sure to reorder any corresponding argument appropriately.

This old way of writing tar options can surprise even experienced users. For example, the two commands:

tar cfz archive.tar.gz file
tar -cfz archive.tar.gz file

are quite different. The first example uses `archive.tar.gz' as the value for option `f' and recognizes the option `z'. The second example, however, uses `z' as the value for option `f'---probably not what was intended.

Old options are kept for compatibility with old versions of tar.

This second example could be corrected in many ways, among which the following are equivalent:

tar -czf archive.tar.gz file
tar -cf archive.tar.gz -z file
tar cf archive.tar.gz -z file

@FIXME{still could explain this better; it's redundant:}

As far as we know, all tar programs, GNU and non-GNU, support old options. GNU tar supports them not only for historical reasons, but also because many people are used to them. For compatibility with Unix tar, the first argument is always treated as containing command and option letters even if it doesn't start with `-'. Thus, `tar c' is equivalent to `tar -c:' both of them specify the --create (-c) command to create an archive.

Mixing Option Styles

All three styles may be intermixed in a single tar command, so long as the rules for each style are fully respected(3). Old style options and either of the modern styles of options may be mixed within a single tar command. However, old style options must be introduced as the first arguments only, following the rule for old options (old options must appear directly after the tar command and some whitespace). Modern options may be given only after all arguments to the old options have been collected. If this rule is not respected, a modern option might be falsely interpreted as the value of the argument to one of the old style options.

For example, all the following commands are wholly equivalent, and illustrate the many combinations and orderings of option styles.

tar --create --file=archive.tar
tar --create -f archive.tar
tar --create -farchive.tar
tar --file=archive.tar --create
tar --file=archive.tar -c
tar -c --file=archive.tar
tar -c -f archive.tar
tar -c -farchive.tar
tar -cf archive.tar
tar -cfarchive.tar
tar -f archive.tar --create
tar -f archive.tar -c
tar -farchive.tar --create
tar -farchive.tar -c
tar c --file=archive.tar
tar c -f archive.tar
tar c -farchive.tar
tar cf archive.tar
tar f archive.tar --create
tar f archive.tar -c
tar fc archive.tar

On the other hand, the following commands are not equivalent to the previous set:

tar -f -c archive.tar
tar -fc archive.tar
tar -fcarchive.tar
tar -farchive.tarc
tar cfarchive.tar

These last examples mean something completely different from what the user intended (judging based on the example in the previous set which uses long options, whose intent is therefore very clear). The first four specify that the tar archive would be a file named `-c', `c', `carchive.tar' or `archive.tarc', respectively. The first two examples also specify a single non-option, name argument having the value `archive.tar'. The last example contains only old style option letters (repeating option `c' twice), not all of which are meaningful (eg., `.', `h', or `i'), with no argument value. @FIXME{not sure i liked the first sentence of this paragraph..}

All tar Options

The coming manual sections contain an alphabetical listing of all tar operations and options, with brief descriptions and cross references to more in-depth explanations in the body of the manual. They also contain an alphabetically arranged table of the short option forms with their corresponding long option. You can use this table as a reference for deciphering tar commands in scripts.

Operations

--append
-r
Appends files to the end of the archive. See section How to Add Files to Existing Archives: --append.
--catenate
-A
Same as `--concatenate'. See section Combining Archives with --concatenate.
--compare
-d
Compares archive members with their counterparts in the file system, and reports differences in file size, mode, owner, modification date and contents. See section Comparing Archive Members with the File System.
--concatenate
-A
Appends other tar archives to the end of the archive. See section Combining Archives with --concatenate.
--create
-c
Creates a new tar archive. See section How to Create Archives.
--delete
Deletes members from the archive. Don't try this on a archive on a tape! See section Removing Archive Members Using `--delete'.
--diff
-d
Same `--compare'. See section Comparing Archive Members with the File System.
--extract
-x
Extracts members from the archive into the file system. See section How to Extract Members from an Archive.
--get
-x
Same as `--extract'. See section How to Extract Members from an Archive.
--list
-t
Lists the members in an archive. See section How to List Archives.
--update
-u
@FIXME{It was: A combination of the `--compare' and `--append' operations. This is not true and rather misleading, as --compare (--diff, -d) does a lot more than --update (-u) for ensuring files are identical.} Adds files to the end of the archive, but only if they are newer than their counterparts already in the archive, or if they do not already exist in the archive. See section Updating an Archive.

tar Options

--absolute-names
-P
Normally when creating an archive, tar strips an initial `/' from member names. This option disables that behavior. @FIXME-xref{}.
--after-date
(See `--newer'; @FIXME-pxref{}.)
--atime-preserve
Tells tar to preserve the access time field in a file's inode when dumping it. @FIXME-xref{}.
--backup=backup-type
Rather than deleting files from the file system, tar will back them up using simple or numbered backups, depending upon backup-type. @FIXME-xref{}.
--block-number
-R
With this option present, tar prints error messages for read errors with the block number in the archive file. @FIXME-xref{}.
--blocking-factor=blocking
-b blocking
Sets the blocking factor tar uses to blocking x 512 bytes per record. @FIXME-xref{}.
--checkpoint
This option directs tar to print periodic checkpoint messages as it reads through the archive. Its intended for when you want a visual indication that tar is still running, but don't want to see `--verbose' output. @FIXME-xref{}.
--compress
--uncompress
-Z
tar will use the compress program when reading or writing the archive. This allows you to directly act on archives while saving space. @FIXME-xref{}.
--confirmation
(See `--interactive'; @FIXME-pxref{}.)
--dereference
-h
When creating a tar archive, tar will archive the file that a symbolic link points to, rather than archiving the symlink. @FIXME-xref{}.
--directory=dir
-C dir
When this option is specified, tar will change its current directory to dir before performing any operations. When this option is used during archive creation, it is order sensitive. @FIXME-xref{}.
--exclude=pattern
When performing operations, tar will skip files that match pattern. @FIXME-xref{}.
--exclude-from=file
-X file
Similar to `--exclude', except tar will use the list of patterns in the file file. @FIXME-xref{}.
--file=archive
-f archive
tar will use the file archive as the tar archive it performs operations on, rather than tar's compilation dependent default. @FIXME-xref{}.
--files-from=file
-T file
tar will use the contents of file as a list of archive members or files to operate on, in addition to those specified on the command-line. @FIXME-xref{}.
--force-local
Forces tar to interpret the filename given to `--file' as a local file, even if it looks like a remote tape drive name. @FIXME-xref{}.
--group=group
Files added to the tar archive will have a group id of group, rather than the group from the source file. group is first decoded as a group symbolic name, but if this interpretation fails, it has to be a decimal numeric group ID. @FIXME-xref{}. Also see the comments for the --owner=user option.
--gunzip
(See `--gzip'; @FIXME-pxref{}.)
--gzip
--gunzip
--ungzip
-z
This option tells tar to read or write archives through gzip, allowing tar to directly operate on several kinds of compressed archives transparently. @FIXME-xref{}.
--help
tar will print out a short message summarizing the operations and options to tar and exit. @FIXME-xref{}.
--ignore-failed-read
Instructs tar to exit successfully if it encounters an unreadable file. See section Options to Help Read Archives.
--ignore-umask
@FIXME{does this exist?} (See `--preserve-permissions'; see section Changing How tar Writes Files.)
--ignore-zeros
-i
With this option, tar will ignore zeroed blocks in the archive, which normally signals EOF. See section Options to Help Read Archives.
--incremental
-G
Used to inform tar that it is working with an old GNU-format incremental backup archive. It is intended primarily for backwards compatibility only. @FIXME-xref{}.
--info-script=script-file
--new-volume-script=script-file
-F script-file
When tar is performing multi-tape backups, script-file is run at the end of each tape. @FIXME-xref{}.
--interactive
--confirmation
-w
Specifies that tar should ask the user for confirmation before performing potentially destructive options, such as overwriting files. @FIXME-xref{}.
--keep-old-files
-k
When extracting files from an archive, tar will not overwrite existing files if this option is present. See section Changing How tar Writes Files.
--label=name
-V name
When creating an archive, instructs tar to write name as a name record in the archive. When extracting or listing archives, tar will only operate on archives that have a label matching the pattern specified in name. @FIXME-xref{}.
--listed-incremental=snapshot-file
-g snapshot-file
During a `--create' operation, specifies that the archive that tar creates is a new GNU-format incremental backup, using snapshot-file to determine which files to backup. With other operations, informs tar that the archive is in incremental format. @FIXME-xref{}.
--mode=permissions
When adding files to an archive, tar will use permissions for the archive members, rather than the permissions from the files. The program chmod and this tar option share the same syntax for what permissions might be. See section `File permissions' in GNU file utilities. This reference also has useful information for those not being overly familiar with the Unix permission system. Of course, permissions might be plainly specified as an octal number. However, by using generic symbolic modifications to mode bits, this allows more flexibility. For example, the value `a+rw' adds read and write permissions for everybody, while retaining executable bits on directories or on any other file already marked as executable.
--multi-volume
-M
Informs tar that it should create or otherwise operate on a multi-volume tar archive. @FIXME-xref{}.
--new-volume-script
(see --info-script)
--newer=date
--after-date=date
-N
When creating an archive, tar will only add files that have changed since date. @FIXME-xref{}.
--newer-mtime
In conjunction with `--newer', tar will only add files whose contents have changed (as opposed to just `--newer', which will also back up files for which any status information has changed).
--no-recursion
With this option, tar will not recurse into directories unless a directory is explicitly named as an argument to tar. @FIXME-xref{}.
--null
When tar is using the `--files-from' option, this option instructs tar to expect filenames terminated with NUL, so tar can correctly work with file names that contain newlines. @FIXME-xref{}.
--numeric-owner
This option will notify tar that it should use numeric user and group IDs when creating a tar file, rather than names. @FIXME-xref{}.
--old-archive
(See `--portability'; @FIXME-pxref{}.)
--one-file-system
-l
Used when creating an archive. Prevents tar from recursing into directories that are on different file systems from the current directory. @FIXME-xref{}.
--owner=user
Specifies that tar should use user as the owner of members when creating archives, instead of the user associated with the source file. user is first decoded as a user symbolic name, but if this interpretation fails, it has to be a decimal numeric user ID. @FIXME-xref{}. There is no value indicating a missing number, and `0' usually means root. Some people like to force `0' as the value to offer in their distributions for the owner of files, because the root user is anonymous anyway, so that might as well be the owner of anonymous archives.
--portability
--old-archive
-o
Tells tar to create an archive that is compatible with Unix V7 tar. @FIXME-xref{}.
--posix
Instructs tar to create a POSIX compliant tar archive. @FIXME-xref{}.
--preserve
Synonymous with specifying both `--preserve-permissions' and `--same-order'. @FIXME-xref{}.
--preserve-order
(See `--same-order'; see section Options to Help Read Archives.)
--preserve-permissions
--same-permissions
-p
When tar is extracting an archive, it normally subtracts the users' umask from the permissions specified in the archive and uses that number as the permissions to create the destination file. Specifying this option instructs tar that it should use the permissions directly from the archive. See section Changing How tar Writes Files.
--read-full-records
-B
Specifies that tar should reblock its input, for reading from pipes on systems with buggy implementations. See section Options to Help Read Archives.
--record-size=size
Instructs tar to use size bytes per record when accessing the archive. @FIXME-xref{}.
--recursive-unlink
Similar to the `--unlink-first' option, removing existing directory hierarchies before extracting directories of the same name from the archive. See section Changing How tar Writes Files.
--remove-files
Directs tar to remove the source file from the file system after appending it to an archive. @FIXME-xref{}.
--rsh-command=cmd
Notifies tar that is should use cmd to communicate with remote devices. @FIXME-xref{}.
--same-order
--preserve-order
-s
This option is an optimization for tar when running on machines with small amounts of memory. It informs tar that the list of file arguments has already been sorted to match the order of files in the archive. See section Options to Help Read Archives.
--same-owner
When extracting an archive, tar will attempt to preserve the owner specified in the tar archive with this option present. @FIXME-xref{}.
--same-permissions
(See `--preserve-permissions'; see section Changing How tar Writes Files.)
--show-omitted-dirs
Instructs tar to mention directories its skipping over when operating on a tar archive. @FIXME-xref{}.
--sparse
-S
Invokes a GNU extension when adding files to an archive that handles sparse files efficiently. @FIXME-xref{}.
--starting-file=name
-K name
This option affects extraction only; tar will skip extracting files in the archive until it finds one that matches name. See section Coping with Scarce Resources.
--suffix=suffix
Alters the suffix tar uses when backing up files from the default `~'. @FIXME-xref{}.
--tape-length=num
-L num
Specifies the length of tapes that tar is writing as being num x 1024 bytes long. @FIXME-xref{}.
--to-stdout
-O
During extraction, tar will extract files to stdout rather than to the file system. See section Changing How tar Writes Files.
--totals
Displays the total number of bytes written after creating an archive. @FIXME-xref{}.
--touch
-m
Sets the modification time of extracted files to the extraction time, rather than the modification time stored in the archive. See section Changing How tar Writes Files.
--uncompress
(See `--compress'; @FIXME-pxref{}.)
--ungzip
(See `--gzip'; @FIXME-pxref{}.)
--unlink-first
-U
Directs tar to remove the corresponding file from the file system before extracting it from the archive. See section Changing How tar Writes Files.
--use-compress-program=prog
Instructs tar to access the archive through prog, which is presumed to be a compression program of some sort. @FIXME-xref{}.
--verbose
-v
Specifies that tar should be more verbose about the operations its performing. This option can be specified multiple times for some operations to increase the amount of information displayed. @FIXME-xref{}.
--verify
-W
Verifies that the archive was correctly written when creating an archive. @FIXME-xref{}.
--version
tar will print an informational message about what version it is and a copyright message, some credits, and then exit. @FIXME-xref{}.
--volno-file=file
Used in conjunction with `--multi-volume'. tar will keep track of which volume of a multi-volume archive its working in file. @FIXME-xref{}.

Short Options Cross Reference

Here is an alphabetized list of all of the short option forms, matching them with the equivalent long option.

-A
`--concatenate'
-B
`--read-full-records'
-C
`--directory'
-F
`--info-script'
-G
`--incremental'
-K
`--starting-file'
-L
`--tape-length'
-M
`--multi-volume'
-N
`--newer'
-O
`--to-stdout'
-P
`--absolute-names'
-R
`--block-number'
-S
`--sparse'
-T
`--files-from'
-U
`--unlink-first'
-V
`--label'
-W
`--verify'
-X
`--exclude-from'
-Z
`--compress'
-b
`--blocking-factor'
-c
`--create'
-d
`--compare'
-f
`--file'
-g
`--listed-incremental'
-h
`--dereference'
-i
`--ignore-zeros'
-k
`--keep-old-files'
-l
`--one-file-system'
-m
`--touch'
-o
`--portability'
-p
`--preserve-permissions'
-r
`--append'
-s
`--same-order'
-t
`--list'
-u
`--update'
-v
`--verbose'
-w
`--interactive'
-x
`--extract'
-z
`--gzip'

GNU tar documentation

Being careful, the first thing is really checking that you are using GNU tar, indeed. The --version option will generate a message giving confirmation that you are using GNU tar, with the precise version of GNU tar you are using. tar identifies itself and prints the version number to the standard output, then immediately exits successfully, without doing anything else, ignoring all other options. For example, `tar --version' might return:

tar (GNU tar) 1.12

The first occurrence of `tar' in the result above is the program name in the package (for example, rmt is another program), while the second occurrence of `tar' is the name of the package itself, containing possibly many programs. The package is currently named `tar', after the name of the main program it contains(4).

Another thing you might want to do is checking the spelling or meaning of some particular tar option, without resorting to this manual, for once you have carefully read it. GNU tar has a short help feature, triggerable through the --help option. By using this option, tar will print a usage message listing all available options on standard output, then exit successfully, without doing anything else and ignoring all other options. Even if this is only a brief summary, it may be several screens long. So, if you are not using some kind of scrollable window, you might prefer to use something like:

$ tar --help | less

presuming, here, that you like using less for a pager. Other popular pagers are more and pg. If you know about some keyword which interests you and do not want to read all the --help output, another common idiom is doing:

tar --help | grep keyword

for getting only the pertinent lines.

The perceptive reader would have noticed some contradiction in the previous paragraphs. It is written that both --version and --help print something, and have all other options ignored. In fact, they cannot ignore each other, and one of them has to win. We do not specify which is stronger, here; experiment if you really wonder!

The short help output is quite succint, and you might have to get back to the full documentation for precise points. If you are reading this paragraph, you already have the tar manual in some form. This manual is available in printed form, as a kind of small book. It may printed out of the GNU tar distribution, provided you have TeX already installed somewhere, and a laser printer around. Just configure the distribution, execute the command `make dvi', then print `doc/tar.dvi' the usual way (contact your local guru to know how). If GNU tar has been conveniently installed at your place, this manual is also available in interactive, hypertextual form as an Info file. Just call `info tar' or, if you do not have the info program handy, use the Info reader provided within GNU Emacs, calling `tar' from the main Info menu.

There is currently no man page for GNU tar. If you observe such a man page on the system you are running, either it does not long to GNU tar, or it has not been produced by GNU. Currently, GNU tar documentation is provided in Texinfo format only, if we except, of course, the short result of tar --help.

Checking tar progress

Typically, tar performs most operations without reporting any information to the user except error messages. When using tar with many options, particularly ones with complicated or difficult-to-predict behavior, it is possible to make serious mistakes. tar provides several options that make observing tar easier. These options cause tar to print information as it progresses in its job, and you might want to use them just for being more careful about what is going on, or merely for entertaining yourself. If you have encountered a problem when operating on an archive, however, you may need more information than just an error message in order to solve the problem. The following options can be helpful diagnostic tools.

Normally, the --list (-t) command to list an archive prints just the file names (one per line) and the other commands are silent. When used with most operations, the --verbose (-v) option causes tar to print the name of each file or archive member as it is processed. This and the other options which make tar print status information can be useful in monitoring tar.

With --create (-c) or --extract (--get, -x), --verbose (-v) used once just prints the names of the files or members as they are processed. Using it twice causes tar to print a longer listing (reminiscent of `ls -l') for each member. Since --list (-t) already prints the names of the members, --verbose (-v) used once with --list (-t) causes tar to print an `ls -l' type listing of the files in the archive. The following examples both extract members with long list output:

$ tar --extract --file=archive.tar --verbose --verbose
$ tar xvv archive.tar

Verbose output appears on the standard output except when an archive is being written to the standard output, as with `tar --create --file=- --verbose' (`tar cfv -', or even `tar cv'---if the installer let standard output be the default archive). In that case tar writes verbose output to the standard error stream.

The --totals option--which is only meaningful when used with --create (-c)---causes tar to print the total amount written to the archive, after it has been fully created.

The --checkpoint option prints an occasional message as tar reads or writes the archive. In fact, it print directory names while reading the archive. It is designed for those who don't need the more detailed (and voluminous) output of --block-number (-R), but do want visual confirmation that tar is actually making forward progress.

@FIXME{There is some confusion here. It seems that -R once wrote a message at `every' record read or written.}

The --show-omitted-dirs option, when reading an archive--with --list (-t) or --extract (--get, -x), for example--causes a message to be printed for each directory in the archive which is skipped. This happens regardless of the reason for skipping: the directory might not have been named on the command line (implicitly or explicitly), it might be excluded by the use of the --exclude=pattern option, or some other reason.

If --block-number (-R) is used, tar prints, along with every message it would normally produce, the block number within the archive where the message was triggered. Also, supplementary messages are triggered when reading blocks full of NULs, or when hitting end of file on the archive. As of now, if the archive if properly terminated with a NUL block, the reading of the file may stop before end of file is met, so the position of end of file will not usually show when --block-number (-R) is used. Note that GNU tar drains the archive before exiting when reading the archive from a pipe.

This option is especially useful when reading damaged archives, since it helps pinpoint the damaged sections. It can also be used with --list (-t) when listing a file-system backup tape, allowing you to choose among several backup tapes when retrieving a file later, in favor of the tape where the file appears earliest (closest to the front of the tape). @FIXME-xref{when the node name is set and the backup section written}.

Asking for Confirmation During Operations

Typically, tar carries out a command without stopping for further instructions. In some situations however, you may want to exclude some files and archive members from the operation (for instance if disk or storage space is tight). You can do this by excluding certain files automatically (see section Choosing Files and Names for tar), or by performing an operation interactively, using the --interactive (-w) option. tar also accepts `--confirmation' for this option.

When the --interactive (-w) option is specified, before reading, writing, or deleting files, tar first prints a message for each such file, telling what operation it intends to take, then asks for confirmation on the terminal. The actions which require confirmation include adding a file to the archive, extracting a file from the archive, deleting a file from the archive, and deleting a file from disk. To confirm the action, you must type a line of input beginning with `y'. If your input line begins with anything other than `y', tar skips that file.

If tar is reading the archive from the standard input, tar opens the file `/dev/tty' to support the interactive communications.

Verbose output is normally sent to standard output, separate from other error messages. However, if the archive is produced directly on standard output, then verbose output is mixed with errors on stderr. Producing the archive on standard output may be used as a way to avoid using disk space, when the archive is soon to be consumed by another process reading it, say. Some people felt the need of producing an archive on stdout, still willing to segregate between verbose output and error output. A possible approach would be using a named pipe to receive the archive, and having the consumer process to read from that named pipe. This has the advantage of letting standard output free to receive verbose output, all separate from errors.

GNU tar Operations

Basic GNU tar Operations

The basic tar operations, --create (-c), --list (-t) and --extract (--get, -x), are currently presented and described in the tutorial chapter of this manual. This section provides some complementary notes for these operations.

--create (-c)
Creating an empty archive would have some kind of elegance. One can initialize an empty archive and later use --append (-r) for adding all members. Some applications would not welcome making an exception in the way of adding the first archive member. On the other hand, many people reported that it is dangerously too easy for tar to destroy a magnetic tape with an empty archive(5). The two most common errors are:
  1. Mistakingly using create instead of extract, when the intent was to extract the full contents of an archive. This error is likely: keys c and x are right next ot each other on the QWERTY keyboard. Instead of being unpacked, the archive then gets wholly destroyed. When users speak about exploding an archive, they usually mean something else :-).
  2. Forgetting the argument to file, when the intent was to create an archive with a single file in it. This error is likely because a tired user can easily add the f key to the cluster of option letters, by the mere force of habit, without realizing the full consequence of doing so. The usual consequence is that the single file, which was meant to be saved, is rather destroyed.
So, recognizing the likelihood and the catastrophical nature of these errors, GNU tar now takes some distance from elegance, and cowardly refuses to create an archive when --create (-c) option is given, there are no arguments besides options, and --files-from=file-of-names (-T file-of-names) option is not used. To get around the cautiousness of GNU tar and nevertheless create an archive with nothing in it, one may still use, as the value for the --files-from=file-of-names (-T file-of-names) option, a file with no names in it, as shown in the following commands:
tar --create --file=empty-archive.tar --files-from=/dev/null
tar cfT empty-archive.tar /dev/null
--extract (--get, -x)
A socket is stored, within a GNU tar archive, as a pipe.
--list (-t)
GNU tar now shows dates as `1996-11-09', while it used to show them as `Nov 11 1996'. (One can revert to the old behavior by defining USE_OLD_CTIME in `src/list.c' before reinstalling.) But preferrably, people you should get used to ISO 8601 dates. Local American dates should be made available again with full date localisation support, once ready. In the meantime, programs not being localisable for dates should prefer international dates, that's really the way to go. Look up http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html if you are curious, it contains a detailed explanation of the ISO 8601 standard.

Advanced GNU tar Operations

Now that you have learned the basics of using GNU tar, you may want to learn about further ways in which tar can help you.

This chapter presents five, more advanced operations which you probably won't use on a daily basis, but which serve more specialized functions. We also explain the different styles of options and why you might want to use one or another, or a combination of them in your tar commands. Additionally, this chapter includes options which allow you to define the output from tar more carefully, and provide help and error correction in special circumstances.

@FIXME{check this after the chapter is actually revised to make sure it still introduces the info in the chapter correctly : ).}

The Five Advanced tar Operations

@UNREVISED

In the last chapter, you learned about the first three operations to tar. This chapter presents the remaining five operations to tar: `--append', `--update', `--concatenate', `--delete', and `--compare'.

You are not likely to use these operations as frequently as those covered in the last chapter; however, since they perform specialized functions, they are quite useful when you do need to use them. We will give examples using the same directory and files that you created in the last chapter. As you may recall, the directory is called `practice', the files are `jazz', `blues', `folk', `rock', and the two archive files you created are `collection.tar' and `music.tar'.

We will also use the archive files `afiles.tar' and `bfiles.tar'. `afiles.tar' contains the members `apple', `angst', and `aspic'. `bfiles.tar' contains the members `./birds', `baboon', and `./box'.

Unless we state otherwise, all practicing you do and examples you follow in this chapter will take place in the `practice' directory that you created in the previous chapter; see section Preparing a Practice Directory for Examples. (Below in this section, we will remind you of the state of the examples where the last chapter left them.)

The five operations that we will cover in this chapter are:

--append
-r
Add new entries to an archive that already exists.
--update
-r
Add more recent copies of archive members to the end of an archive, if they exist.
--concatenate
--catenate
-A
Add one or more pre-existing archives to the end of another archive.
--delete
Delete items from an archive (does not work on tapes).
--compare
--diff
-d
Compare archive members to their counterparts in the file system.

Currently, the listing of the directory using ls is as follows:

The archive file `collection.tar' looks like this:

$ tar -tvf collection.tar

The archive file `music.tar' looks like this:

$ tar -tvf music.tar

@FIXME{need to fill in the above!!!}

How to Add Files to Existing Archives: --append

@UNREVISED

If you want to add files to an existing archive, you don't need to create a new archive; you can use --append (-r). The archive must already exist in order to use `--append'. (A related operation is the `--update' operation; you can use this to add newer versions of archive members to an existing archive. To learn how to do this with `--update', see section Updating an Archive.)

@FIXME{Explain in second paragraph whether you can get to the previous version -- explain whole situation somewhat more clearly.}

If you use --append (-r) to add a file that has the same name as an archive member to an archive containing that archive member, then the old member is not deleted. What does happen, however, is somewhat complex. tar allows you to have infinite numbers of files with the same name. Some operations treat these same-named members no differently than any other set of archive members: for example, if you view an archive with --list (-t), you will see all of those members listed, with their modification times, owners, etc.

Other operations don't deal with these members as perfectly as you might prefer; if you were to use --extract (--get, -x) to extract the archive, only the most recently added copy of a member with the same name as four other members would end up in the working directory. This is because `--extract' extracts an archive in the order the members appeared in the archive; the most recently archived members will be extracted last. Additionally, an extracted member will overwrite a file of the same name which existed in the directory already, and tar will not prompt you about this. Thus, only the most recently archived member will end up being extracted, as it will overwrite the one extracted before it, and so on.

@FIXME{ hag -- you might want to incorporate some of the above into the MMwtSN node; not sure. i didn't know how to make it simpler...}

There are a few ways to get around this. @FIXME-xref{Multiple Members with the Same Name}.

If you want to replace an archive member, use --delete to delete the member you want to remove from the archive, , and then use `--append' to add the member you want to be in the archive. Note that you can not change the order of the archive; the most recently added member will still appear last. In this sense, you cannot truely "replace" one member with another. (Replacing one member with another will not work on certain types of media, such as tapes; see section Removing Archive Members Using `--delete' and section Tapes and Other Archive Media, for more information.)

Appending Files to an Archive

@UNREVISED

The simplest way to add a file to an already existing archive is the --append (-r) operation, which writes specified files into the archive whether or not they are already among the archived files. When you use `--append', you must specify file name arguments, as there is no default. If you specify a file that already exists in the archive, another copy of the file will be added to the end of the archive. As with other operations, the member names of the newly added files will be exactly the same as their names given on the command line. The --verbose (-v) option will print out the names of the files as they are written into the archive.

`--append' cannot be performed on some tape drives, unfortunately, due to deficiencies in the formats those tape drives use. The archive must be a valid tar archive, or else the results of using this operation will be unpredictable. See section Tapes and Other Archive Media.

To demonstrate using `--append' to add a file to an archive, create a file called `rock' in the `practice' directory. Make sure you are in the `practice' directory. Then, run the following tar command to add `rock' to `collection.tar':

$ tar --append --file=collection.tar rock

If you now use the --list (-t) operation, you will see that `rock' has been added to the archive:

$ tar --list --file=collection.tar
-rw-rw-rw- me user     28 1996-10-18 16:31 jazz
-rw-rw-rw- me user     21 1996-09-23 16:44 blues
-rw-rw-rw- me user     20 1996-09-23 16:44 folk
-rw-rw-rw- me user     20 1996-09-23 16:44 rock

@FIXME{in theory, dan will (soon) try to turn this node into what it's title claims it will become...}

Multiple Files with the Same Name

You can use --append (-r) to add copies of files which have been updated since the archive was created. (However, we do not recommend doing this since there is another tar option called `--update'; see section Updating an Archive for more information. We describe this use of `--append' here for the sake of completeness.) @FIXME{is this really a good idea, to give this whole description for something which i believe is basically a Stupid way of doing something? certain aspects of it show ways in which tar is more broken than i'd personally like to admit to, specifically the last sentence. On the other hand, i don't think it's a good idea to be saying that re explicitly don't recommend using something, but i can't see any better way to deal with the situation.} When you extract the archive, the older version will be effectively lost. This works because files are extracted from an archive in the order in which they were archived. Thus, when the archive is extracted, a file archived later in time will overwrite a file of the same name which was archived earlier, even though the older version of the file will remain in the archive unless you delete all versions of the file.

Supposing you change the file `blues' and then append the changed version to `collection.tar'. As you saw above, the original `blues' is in the archive `collection.tar'. If you change the file and append the new version of the file to the archive, there will be two copies in the archive. When you extract the archive, the older version of the file will be extracted first, and then overwritten by the newer version when it is extracted.

You can append the new, changed copy of the file `blues' to the archive in this way:

$ tar --append --verbose --file=collection.tar blues
blues

Because you specified the `--verbose' option, tar has printed the name of the file being appended as it was acted on. Now list the contents of the archive:

$ tar --list --verbose --file=collection.tar
-rw-rw-rw- me user     28 1996-10-18 16:31 jazz
-rw-rw-rw- me user     21 1996-09-23 16:44 blues
-rw-rw-rw- me user     20 1996-09-23 16:44 folk
-rw-rw-rw- me user     20 1996-09-23 16:44 rock
-rw-rw-rw- me user     58 1996-10-24 18:30 blues

The newest version of `blues' is now at the end of the archive (note the different creation dates and file sizes). If you extract the archive, the older version of the file `blues' will be overwritten by the newer version. You can confirm this by extracting the archive and running `ls' on the directory. See section Changing How tar Writes Files for more information. (Please note: This is the case unless you employ the --backup option; @FIXME-ref{Multiple Members with the Same Name}.)

Updating an Archive

@UNREVISED

In the previous section, you learned how to use --append (-r) to add a file to an existing archive. A related operation is --update (-u). The `--update' operation updates a tar archive by comparing the date of the specified archive members against the date of the file with the same name. If the file has been modified more recently than the archive member, then the newer version of the file is added to the archive (as with --append (-r)).

Unfortunately, you cannot use `--update' with magnetic tape drives. The operation will fail.

@FIXME{other examples of media on which --update will fail? need to ask charles and/or mib/thomas/dave shevett..}

Both `--update' and `--append' work by adding to the end of the archive. When you extract a file from the archive, only the version stored last will wind up in the file system, unless you use the --backup option (@FIXME-ref{Multiple Members with the Same Name}).

How to Update an Archive Using --update

You must use file name arguments with the --update (-u) operation. If you don't specify any files, tar won't act on any files and won't tell you that it didn't do anything (which may end up confusing you).

@FIXME{note: the above parenthetical added because in fact, this behavior just confused the author. :-) }

To see the `--update' option at work, create a new file, `classical', in your practice directory, and some extra text to the file `blues', using any text editor. Then invoke tar with the `update' operation and the --verbose (-v) option specified, using the names of all the files in the practice directory as file name arguments:

$ tar --update -v -f collection.tar blues folk rock classical
blues
classical
$

Because we have specified verbose mode, tar prints out the names of the files it is working on, which in this case are the names of the files that needed to be updated. If you run `tar --list' and look at the archive, you will see `blues' and `classical' at its end. There will be a total of two versions of the member `blues'; the one at the end will be newer and larger, since you added text before updating it.

(The reason tar does not overwrite the older file when updating it is because writing to the middle of a section of tape is a difficult process. Tapes are not designed to go backward. See section Tapes and Other Archive Media for more information about tapes.

--update (-u) is not suitable for performing backups for two reasons: it does not change directory content entries, and it lengthens the archive every time it is used. The GNU tar options intended specifically for backups are more efficient. If you need to run backups, please consult section Performing Backups and Restoring Files.

Combining Archives with --concatenate

Sometimes it may be convenient to add a second archive onto the end of an archive rather than adding individual files to the archive. To add one or more archives to the end of another archive, you should use the --concatenate (--catenate, -A) operation.

To use `--concatenate', name the archives to be concatenated on the command line. (Nothing happens if you don't list any.) The members, and their member names, will be copied verbatim from those archives. If this causes multiple members to have the same name, it does not delete any members; all the members with the same name coexist. For information on how this affects reading the archive, @FIXME-ref{Multiple Members with the Same Name}.

To demonstrate how `--concatenate' works, create two small archives called `bluesrock.tar' and `folkjazz.tar', using the relevant files from `practice':

$ tar -cvf bluesrock.tar blues rock
blues
classical
$ tar -cvf folkjazz.tar folk jazz
folk
jazz

If you like, You can run `tar --list' to make sure the archives contain what they are supposed to:

$ tar -tvf bluesrock.tar
-rw-rw-rw- melissa user    105 1997-01-21 19:42 blues
-rw-rw-rw- melissa user     33 1997-01-20 15:34 rock
$ tar -tvf folkjazz.tar
-rw-rw-rw- melissa user     20 1996-09-23 16:44 folk
-rw-rw-rw- melissa user     65 1997-01-30 14:15 jazz

We can concatenate these two archives with tar:

$ cd ..
$ tar --concatenate --file=bluesrock.tar jazzfolk.tar

If you now list the contents of the `bluesclass.tar', you will see that now it also contains the archive members of `jazzfolk.tar':

$ tar --list --file=bluesrock.tar
blues
rock
jazz
folk

When you use `--concatenate', the source and target archives must already exist and must have been created using compatable format parameters (@FIXME-pxref{Matching Format Parameters}). The new, concatenated archive will be called by the same name as the first archive listed on the command line. @FIXME{is there a way to specify a new name?}

Like --append (-r), this operation cannot be performed on some tape drives, due to deficiencies in the formats those tape drives use.

It may seem more intuitive to you to want or try to use cat to concatenate two archives instead of using the `--concatenate' operation; after all, cat is the utility for combining files.

However, tar archives incorporate an end-of-file marker which must be removed if the concatenated archives are to be read properly as one archive. `--concatenate' removes the end-of-archive marker from the target archive before each new archive is appended. If you use cat to combine the archives, the result will not be a valid tar format archive. If you need to retrieve files from an archive that was added to using the cat utility, use the --ignore-zeros (-i) option. See section Ignoring Blocks of Zeros for further information on dealing with archives improperly combined using the cat shell utility.

@FIXME{this shouldn't go here. where should it go?} You must specify the source archives using --file=archive-name (-f archive-name) (see section Choosing and Naming Archive Files). If you do not specify the target archive, tar uses the value of the environment variable TAPE, or, if this has not been set, the default archive name.

Removing Archive Members Using `--delete'

@UNREVISED

You can remove members from an archive by using the --delete option. Specify the name of the archive with --file=archive-name (-f archive-name) and then specify the names of the members to be deleted; if you list no member names, nothing will be deleted. The --verbose (-v) option will cause tar to print the names of the members as they are deleted. As with --extract (--get, -x), you must give the exact member names when using `tar --delete'. `--delete' will remove all versions of the named file from the archive. The `--delete' operation can run very slowly.

Unlike other operations, `--delete' has no short form.

This operation will rewrite the archive. You can only use `--delete' on an archive if the archive device allows you to write to any point on the media, such as a disk; because of this, it does not work on magnetic tapes. Do not try to delete an archive member from a magnetic tape; the action will not succeed, and you will be likely to scramble the archive and damage your tape. There is no safe way (except by completely re-writing the archive) to delete files from most kinds of magnetic tape. See section Tapes and Other Archive Media.

To delete all versions of the file `blues' from the archive `collection.tar' in the `practice' directory, make sure you are in that directory, and then,

$ tar --list --file=collection.tar
blues
folk
jazz
rock
practice/blues
practice/folk
practice/jazz
practice/rock
practice/blues
$ tar --delete --file=collection.tar blues
$ tar --list --file=collection.tar
folk
jazz
rock
$

@FIXME{I changed the order of these nodes around and haven't had a chance to fix the above example's results, yet. I have to play with this and follow it and see what it actually does!}

The --delete option has been reported to work properly when tar acts as a filter from stdin to stdout.

Comparing Archive Members with the File System

@UNREVISED

The `--compare' (`-d'), or `--diff' operation compares specified archive members against files with the same names, and then reports differences in file size, mode, owner, modification date and contents. You should only specify archive member names, not file names. If you do not name any members, then tar will compare the entire archive. If a file is represented in the archive but does not exist in the file system, tar reports a difference.

You have to specify the record size of the archive when modifying an archive with a non-default record size.

tar ignores files in the file system that do not have corresponding members in the archive.

The following example compares the archive members `rock', `blues' and `funk' in the archive `bluesrock.tar' with files of the same name in the file system. (Note that there is no file, `funk'; tar will report an error message.)

$ tar --compare --file=bluesrock.tar rock blues funk
rock
blues
tar: funk not found in archive

@FIXME{what does this actually depend on? i'm making a guess, here.}Depending on the system where you are running tar and the version you are running, tar may have a different error message, such as:

funk: does not exist

@FIXME-xref{somewhere, for more information about format parameters. Melissa says: such as "format variations"? But why? Clearly I don't get it yet; I'll deal when I get to that section.}

The spirit behind the --compare (--diff, -d) option is to check whether the archive represents the current state of files on disk, more than validating the integrity of the archive media. For this later goal, See section Verifying Data as It is Stored.

Options Used by --extract

@UNREVISED

@FIXME{i need to get dan to go over these options with me and see if there's a better way of organizing them.}

The previous chapter showed how to use --extract (--get, -x) to extract an archive into the filesystem. Various options cause tar to extract more information than just file contents, such as the owner, the permissions, the modification date, and so forth. This section presents options to be used with `--extract' when certain special considerations arise. You may review the information presented in section How to Extract Members from an Archive for more basic information about the `--extract' operation.

Options to Help Read Archives

@UNREVISED

Normally, tar will request data in full record increments from an archive storage device. If the device cannot return a full record, tar will report an error. However, some devices do not always return full records, or do not require the last record of an archive to be padded out to the next record boundary. To keep reading until you obtain a full record, or to accept an incomplete record if it contains an end-of-archive marker, specify the --read-full-records (-B) option in conjunction with the --extract (--get, -x) or --list (-t) operations. See section Blocking.

The --read-full-records (-B) option is turned on by default when tar reads an archive from standard input, or from a remote machine. This is because on BSD Unix systems, attempting to read a pipe returns however much happens to be in the pipe, even if it is less than was requested. If this option were not enabled, tar would fail as soon as it read an incomplete record from the pipe.

If you're not sure of the blocking factor of an archive, you can read the archive by specifying --read-full-records (-B) and --blocking-factor=512-size (-b 512-size), using a blocking factor larger than what the archive uses. This lets you avoid having to determine the blocking factor of an archive. See section The Blocking Factor of an Archive.

Reading Full Records

@FIXME{need sentence or so of intro here}

--read-full-records
-B
Use in conjunction with --extract (--get, -x) to read an archive which contains incomplete records, or one which has a blocking factor less than the one specified.

Ignoring Blocks of Zeros

Normally, tar stops reading when it encounters a block of zeros between file entries (which usually indicates the end of the archive). --ignore-zeros (-i) allows tar to completely read an archive which contains a block of zeros before the end (i.e. a damaged archive, or one which was created by cat-ing several archives together).

The --ignore-zeros (-i) option is turned off by default because many versions of tar write garbage after the end-of-archive entry, since that part of the media is never supposed to be read. GNU tar does not write after the end of an archive, but seeks to maintain compatablity among archiving utilities.

--ignore-zeros
-i
To ignore blocks of zeros (ie. end-of-archive entries) which may be encountered while reading an archive. Use in conjunction with --extract (--get, -x) or --list (-t).

Ignore Fail Read

@FIXME{Is this in the right place? It doesn't exist anywhere else in the book (except the appendix), and has no further explanation. For that matter, what does it mean?!}

--ignore-failed-read
Do not exit with nonzero on unreadable files or directories.

Changing How tar Writes Files

@UNREVISED

@FIXME{need to mention the brand new option, --backup}

Options to Prevent Overwriting Files

Normally, tar writes extracted files into the file system without regard to the files already on the system; i.e., files with the same names as archive members are overwritten when the archive is extracted. If the name of a corresponding file name is a symbolic link, the file pointed to by the symbolic link will be overwritten instead of the symbolic link itself (if this is possible). Moreover, special devices, empty directories and even symbolic links are automatically removed if they are found to be on the way of the proper extraction.

To prevent tar from extracting an archive member from an archive if doing so will overwrite a file in the file system, use --keep-old-files (-k) in conjunction with `--extract'. When this option is specified, tar will report an error stating the name of the files in conflict instead of overwriting the file with the corresponding extracted archive member.

@FIXME{these two P's have problems. i don't understand what they're trying to talk about well enough to fix them; i may have just made them worse (in particular the first of the two). waiting to talk with hag.}

The --unlink-first (-U) option removes existing files, symbolic links, empty directories, devices, etc., prior to extracting over them. In particular, using this option will prevent replacing an already existing symbolic link by the name of an extracted file, since the link itself is removed prior to the extraction, rather than the file it points to. On some systems, the backing store for the executable is the original program text. You could use the --unlink-first (-U) option to prevent segmentation violations or other woes when extracting arbitrary executables over currently running copies. Note that if something goes wrong with the extraction and you did use this option, you might end up with no file at all. Without this option, if something goes wrong with the extraction, the existing file is not overwritten and preserved.

@FIXME{huh?} If you specify the --recursive-unlink option, tar removes anything that keeps you from extracting a file as far as current permissions will allow it. This could include removal of the contents of a full directory hierarchy. For example, someone using this feature may be very surprised at the results when extracting a directory entry from the archive. This option can be dangerous; be very aware of what you are doing if you choose to use it.

Keep Old Files

--keep-old-files
-k
Do not overwrite existing files from archive. The --keep-old-files (-k) option prevents tar from over-writing existing files with files with the same name from the archive. The --keep-old-files (-k) option is meaningless with --list (-t). Prevents tar from overwriting files in the file system during extraction.

Unlink First

--unlink-first
-U
Try removing files before extracting over them, instead of trying to overwrite them.

Recursive Unlink

--recursive-unlink
When this option is specified, try removing files and directory hierarchies before extracting over them. This is a dangerous option!

Some people argue that GNU tar should not hesitate to overwrite files with other files when extracting. When extracting a tar archive, they expect to see a faithful copy of the state of the filesystem when the archive was created. It is debatable that this would always be a proper behaviour. For example, suppose one has an archive in which `usr/local' is a link to `usr/local2'. Since then, maybe the site removed the link and renamed the whole hierarchy from `/usr/local2' to `/usr/local'. Such things happen all the time. I guess it would not be welcome at all that GNU tar removes the whole hierarchy just to make room for the link to be reinstated (unless it also simultaneously restores the full `/usr/local2', of course! GNU tar is indeed able to remove a whole hierarchy to reestablish a symbolic link, for example, but only if --recursive-unlink is specified to allow this behaviour. In any case, single files are silently removed.

Setting Modification Times

Normally, tar sets the modification times of extracted files to the modification times recorded for the files in the archive, but limits the permissions of extracted files by the current umask setting.

To set the modification times of extracted files to the time when the files were extracted, use the --touch (-m) option in conjunction with --extract (--get, -x).

--touch
-m
Sets the modification time of extracted archive members to the time they were extracted, not the time recorded for them in the archive. Use in conjunction with --extract (--get, -x).

Setting Access Permissions

To set the modes (access permissions) of extracted files to those recorded for those files in the archive, use `--same-persmissions' in conjunction with the --extract (--get, -x) operation. @FIXME{Should be aliased to ignore-umask.}

--preserve-permission
--same-permission
--ignore-umask
-p
Set modes of extracted archive members to those recorded in the archive, instead of current umask settings. Use in conjunction with --extract (--get, -x).

@FIXME{Following paragraph needs to be rewritten: why doesnt' this cat files together, why is this useful. is it really useful with more than one file?}

Writing to Standard Output

To write the extracted files to the standard output, instead of creating the files on the file system, use --to-stdout (-O) in conjunction with --extract (--get, -x). This option is useful if you are extracting files to send them through a pipe, and do not need to preserve them in the file system. If you extract multiple members, they appear on standard output concatenated, in the order they are found in the archive.

--to-stdout
-O
Writes files to the standard output. Used in conjunction with --extract (--get, -x). Extract files to standard output. When this option is used, instead of creating the files specified, tar writes the contents of the files extracted to its standard output. This may be useful if you are only extracting the files in order to send them through a pipe. This option is meaningless with --list (-t).

@FIXME{Why would you want to do such a thing, how are files separated on the standard output? is this useful with more that one file? Are pipes the real reason?}

Removing Files

@FIXME{the various macros in the front of the manual think that this option goes in this section. i have no idea; i only know it's nowhere else in the book...}

--remove-files
Remove files after adding them to the archive.

Coping with Scarce Resources

@UNREVISED

Starting File

--starting-file=name
-K name
Starts an operation in the middle of an archive. Use in conjunction with --extract (--get, -x) or --list (-t).

If a previous attempt to extract files failed due to lack of disk space, you can use --starting-file=name (-K name) to start extracting only after member name of the archive. This assumes, of course, that there is now free space, or that you are now extracting into a different file system. (You could also choose to suspend tar, remove unnecessary files from the file system, and then restart the same tar operation. In this case, --starting-file=name (-K name) is not necessary. See section Using tar to Perform Incremental Dumps, See section Asking for Confirmation During Operations, and section Excluding Some Files.)

Same Order

--same-order
--preserve-order
-s
To process large lists of file names on machines with small amounts of memory. Use in conjunction with --compare (--diff, -d), --list (-t) or --extract (--get, -x).

@FIXME{we don't need/want --preserve to exist any more (from melissa: ie, don't want that *version* of the option to exist, or don't want the option to exist in either version?}

@FIXME{i think this explanation is lacking.}

The --same-order (--preserve-order, -s) option tells tar that the list of file names to be listed or extracted is sorted in the same order as the files in the archive. This allows a large list of names to be used, even on a small machine that would not otherwise be able to hold all the names in memory at the same time. Such a sorted list can easily be created by running `tar -t' on the archive and editing its output.

This option is probably never needed on modern computer systems.

Backup options

GNU tar offers options for making backups of files before writing new versions. These options control the details of these backups. They may apply to the archive itself before it is created or rewritten, as well as individual extracted members. Other GNU programs (cp, install, ln, and mv, for example) offer similar options.

Backup options may prove unexpectedly useful when extracting archives containing many members having identical name, or when extracting archives on systems having file name limitations, making different members appear has having similar names through the side-effect of name truncation. (This is true only if we have a good scheme for truncated backup names, which I'm not sure at all: I suspect work is needed in this area.) When any existing file is backed up before being overwritten by extraction, then clashing files are automatically be renamed to be unique, and the true name is kept for only the last file of a series of clashing files. By using verbose mode, users may track exactly what happens.

At the detail level, some decisions are still experimental, and may change in the future, we are waiting comments from our users. So, please do not learn to depend blindly on the details of the backup features. For example, currently, directories themselves are never renamed through using these options, so, extracting a file over a directory still has good chances to fail. Also, backup options apply to created archives, not only to extracted members. For created archives, backups will not be attempted when the archive is a block or character device, or when it refers to a remote file.

For the sake of simplicity and efficiency, backups are made by renaming old files prior to creation or extraction, and not by copying. The original name is restored if the file creation fails. If a failure occurs after a partial extraction of a file, both the backup and the partially extracted file are kept.

`--backup'
Make backups of files that are about to be overwritten or removed. Without this option, the original versions are destroyed.
`--suffix=suffix'
Append suffix to each backup file made with `-b'. If this option is not specified, the value of the SIMPLE_BACKUP_SUFFIX environment variable is used. And if SIMPLE_BACKUP_SUFFIX is not set, the default is `~', just as in Emacs.
`--version-control=method'
Use method to determine the type of backups made with --backup. If this option is not specified, the value of the VERSION_CONTROL environment variable is used. And if VERSION_CONTROL is not set, the default backup type is `existing'. This option corresponds to the Emacs variable `version-control'; the same values for method are accepted as in Emacs. This options also more descriptive name. The valid methods (unique abbreviations are accepted):
`t'
`numbered'
Always make numbered backups.
`nil'
`existing'
Make numbered backups of files that already have them, simple backups of the others.
`never'
`simple'
Always make simple backups.

Some people express the desire to always use the op-backup option, by defining some kind of alias or script. This is not as easy as one may thing, due to the fact old style options should appear first and consume arguments a bit inpredictably for an alias or script. But, if you are ready to give up using old style options, you may resort to using something like (a Bourne shell function here):

tar () { /usr/local/bin/tar --backup $*; }

Notable tar Usages

@UNREVISED

@FIXME{Using Unix file linking capability to recreate directory structures--linking files into one subdirectory and then tarring that directory.}

@FIXME{Nice hairy example using absolute-names, newer, etc.}

You can easily use archive files to transport a group of files from one system to another: put all relevant files into an archive on one computer system, transfer the archive to another system, and extract the contents there. The basic transfer medium might be magnetic tape, Internet FTP, or even electronic mail (though you must encode the archive with uuencode in order to transport it properly by mail). Both machines do not have to use the same operating system, as long as they both support the tar program.

For example, here is how you might copy a directory's contents from one disk to another, while preserving the dates, modes, owners and link-structure of all the files therein. In this case, the transfer medium is a pipe, which is one a Unix redirection mechanism:

$ cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)

The command also works using short option forms:

@FIXME{The following using standard input/output correct??}

$ cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)

This is one of the easiest methods to transfer a tar archive.

Looking Ahead: The Rest of this Manual

You have now seen how to use all eight of the operations available to tar, and a number of the possible options. The next chapter explains how to choose and change file and archive names, how to use files to store names of other files which you can then call as arguments to tar (this can help you save time if you expect to archive the same list of files a number of times), and how to @FIXME{in case it's not obvious, i'm making this up in some sense based on my imited memory of what the next chapter *really* does. i just wanted to flesh out this final section a little bit so i'd remember to sitck it in here. :-)}

If there are too many files to conveniently list on the command line, you can list the names in a file, and tar will read that file. See section Reading Names from a File.

There are various ways of causing tar to skip over some files, and not archive them. See section Choosing Files and Names for tar.

Performing Backups and Restoring Files

@UNREVISED

GNU tar is distributed along with the scripts which the Free Software Foundation uses for performing backups. There is no corresponding scripts available yet for doing restoration of files. Even if there is a good chance those scripts may be satisfying to you, they are not the only scripts or methods available for doing backups and restore. You may well create your own, or use more sophisticated packages dedicated to that purpose.

Some users are enthusiastic about Amanda (The Advanced Maryland Automatic Network Disk Archiver), a backup system developed by James da Silva `jds@cs.umd.edu' and available on many Unix systems. This is free software, and it is available at these places:

http://www.cs.umd.edu/projects/amanda/amanda.html
ftp://ftp.cs.umd.edu/pub/amanda

Here is a possible plan for a future documentation about the backuping scripts which are provided within the GNU tar distribution.

.* dumps
. + what are dumps

. + different levels of dumps
.  - full dump = dump everything
.  - level 1, level 2 dumps etc, -
    A level n dump dumps everything changed since the last level
    n-1 dump (?)

. + how to use scripts for dumps  (ie, the concept)
.  - scripts to run after editing backup specs (details)

. + Backup Specs, what is it.
.  - how to customize
.  - actual text of script  [/sp/dump/backup-specs]

. + Problems
.  - rsh doesn't work
.  - rtape isn't installed
.  - (others?)

. + the --incremental option of tar

. + tapes
.  - write protection
.  - types of media
.   : different sizes and types, useful for different things
.  - files and tape marks
     one tape mark between files, two at end.
.  - positioning the tape
     MT writes two at end of write,
       backspaces over one when writing again.

This chapter documents both the provided FSF scripts and tar options which are more specific to usage as a backup tool.

To back up a file system means to create archives that contain all the files in that file system. Those archives can then be used to restore any or all of those files (for instance if a disk crashes or a file is accidently deleted). File system backups are also called dumps.

Using tar to Perform Full Dumps

@UNREVISED

Full dumps should only be made when no other people or programs are modifying files in the filesystem. If files are modified while tar is making the backup, they may not be stored properly in the archive, in which case you won't be able to restore them if you have to. (Files not being modified are written with no trouble, and do not corrupt the entire archive.)

You will want to use the --label=archive-label (-V archive-label) option to give the archive a volume label, so you can tell what this archive is even if the label falls off the tape, or anything like that.

Unless the filesystem you are dumping is guaranteed to fit on one volume, you will need to use the --multi-volume (-M) option. Make sure you have enough tapes on hand to complete the backup.

If you want to dump each filesystem separately you will need to use the --one-file-system (-l) option to prevent tar from crossing filesystem boundaries when storing (sub)directories.

The --incremental (-G) option is not needed, since this is a complete copy of everything in the filesystem, and a full restore from this backup would only be done onto a completely empty disk.

Unless you are in a hurry, and trust the tar program (and your tapes), it is a good idea to use the --verify (-W) option, to make sure your files really made it onto the dump properly. This will also detect cases where the file was modified while (or just after) it was being archived. Not all media (notably cartridge tapes) are capable of being verified, unfortunately.

--listed-incremental=snapshot-file (-g snapshot-file) take a file name argument always. If the file doesn't exist, run a level zero dump, creating the file. If the file exists, uses that file to see what has changed.

--incremental (-G) @FIXME{look it up}

--incremental (-G) handle old GNU-format incremental backup.

This option should only be used when creating an incremental backup of a filesystem. When the --incremental (-G) option is used, tar writes, at the beginning of the archive, an entry for each of the directories that will be operated on. The entry for a directory includes a list of all the files in the directory at the time the dump was done, and a flag for each file indicating whether the file is going to be put in the archive. This information is used when doing a complete incremental restore.

Note that this option causes tar to create a non-standard archive that may not be readable by non-GNU versions of the tar program.

The --incremental (-G) option means the archive is an incremental backup. Its meaning depends on the command that it modifies.

If the --incremental (-G) option is used with --list (-t), tar will list, for each directory in the archive, the list of files in that directory at the time the archive was created. This information is put out in a format that is not easy for humans to read, but which is unambiguous for a program: each file name is preceded by either a `Y' if the file is present in the archive, an `N' if the file is not included in the archive, or a `D' if the file is a directory (and is included in the archive). Each file name is terminated by a null character. The last file is followed by an additional null and a newline to indicate the end of the data.

If the --incremental (-G) option is used with --extract (--get, -x), then when the entry for a directory is found, all files that currently exist in that directory but are not listed in the archive are deleted from the directory.

This behavior is convenient when you are restoring a damaged file system from a succession of incremental backups: it restores the entire state of the file system to that which obtained when the backup was made. If you don't use --incremental (-G), the file system will probably fill up with files that shouldn't exist any more.

--listed-incremental=snapshot-file (-g snapshot-file) handle new GNU-format incremental backup. This option handles new GNU-format incremental backup. It has much the same effect as --incremental (-G), but also the time when the dump is done and the list of directories dumped is written to the given file. When restoring, only files newer than the saved time are restored, and the direcotyr list is used to speed up operations.

--listed-incremental=snapshot-file (-g snapshot-file) acts like --incremental (-G), but when used in conjunction with --create (-c) will also cause tar to use the file file, which contains information about the state of the filesystem at the time of the last backup, to decide which files to include in the archive being created. That file will then be updated by tar. If the file file does not exist when this option is specified, tar will create it, and include all appropriate files in the archive.

The file, which is archive independent, contains the date it was last modified and a list of devices, inode numbers and directory names. tar will archive files with newer mod dates or inode change times, and directories with an unchanged inode number and device but a changed directory name. The file is updated after the files to be archived are determined, but before the new archive is actually created.

GNU tar actually writes the file twice: once before the data and written, and once after.

Using tar to Perform Incremental Dumps

@UNREVISED

Performing incremental dumps is similar to performing full dumps, although a few more options will usually be needed.

You will need to use the `-N date' option to tell tar to only store files that have been modified since date. date should be the date and time of the last full/incremental dump.

A standard scheme is to do a monthly (full) dump once a month, a weekly dump once a week of everything since the last monthly and a daily every day of everything since the last (weekly or monthly) dump.

Here is a copy of the script used to dump the filesystems of the machines here at the Free Software Foundation. This script is run via cron late at night when people are least likely to be using the machines. This script dumps several filesystems from several machines at once (via NFS). The operator is responsible for ensuring that all the machines will be up at the time the dump happens. If a machine is not running, its files will not be dumped, and the next day's incremental dump will not store files that would have gone onto that dump.

#!/bin/csh
# Dump thingie
set now = `date`
set then = `cat date.nfs.dump`
/u/hack/bin/tar -c -G -v\
 -f /dev/rtu20\
 -b 126\
 -N "$then"\
 -V "Dump from $then to $now"\
 /alpha-bits/gp\
 /gnu/hack\
 /hobbes/u\
 /spiff/u\
 /sugar-bombs/u
echo $now > date.nfs.dump
mt -f /dev/rtu20 rew

Output from this script is stored in a file, for the operator to read later.

This script uses the file `date.nfs.dump' to store the date/time of the last dump.

Since this is a streaming tape drive, no attempt to verify the archive is done. This is also why the high blocking factor (126) is used. The tape drive must also be rewound by the mt command after the dump is made.

The Incremental Options

@UNREVISED

--incremental (-G) is used in conjunction with --create (-c), --extract (--get, -x) or --list (-t) when backing up and restoring file systems. An archive cannot be extracted or listed with the --incremental (-G) option specified unless it was created with the option specified. This option should only be used by a script, not by the user, and is usually disregarded in favor of --listed-incremental=snapshot-file (-g snapshot-file), which is described below.

--incremental (-G) in conjunction with --create (-c) causes tar to write, at the beginning of the archive, an entry for each of the directories that will be archived. The entry for a directory includes a list of all the files in the directory at the time the archive was created and a flag for each file indicating whether or not the file is going to be put in the archive.

Note that this option causes tar to create a non-standard archive that may not be readable by non-GNU versions of the tar program.

--incremental (-G) in conjunction with --extract (--get, -x) causes tar to read the lists of directory contents previously stored in the archive, delete files in the file system that did not exist in their directories when the archive was created, and then extract the files in the archive.

This behavior is convenient when restoring a damaged file system from a succession of incremental backups: it restores the entire state of the file system to that which obtained when the backup was made. If --incremental (-G) isn't specified, the file system will probably fill up with files that shouldn't exist any more.

--incremental (-G) in conjunction with --list (-t), causes tar to print, for each directory in the archive, the list of files in that directory at the time the archive was created. This information is put out in a format that is not easy for humans to read, but which is unambiguous for a program: each file name is preceded by either a `Y' if the file is present in the archive, an `N' if the file is not included in the archive, or a `D' if the file is a directory (and is included in the archive). Each file name is terminated by a null character. The last file is followed by an additional null and a newline to indicate the end of the data.

--listed-incremental=snapshot-file (-g snapshot-file) acts like --incremental (-G), but when used in conjunction with --create (-c) will also cause tar to use the file snapshot-file, which contains information about the state of the file system at the time of the last backup, to decide which files to include in the archive being created. That file will then be updated by tar. If the file file does not exist when this option is specified, tar will create it, and include all appropriate files in the archive.

The file file, which is archive independent, contains the date it was last modified and a list of devices, inode numbers and directory names. tar will archive files with newer mod dates or inode change times, and directories with an unchanged inode number and device but a changed directory name. The file is updated after the files to be archived are determined, but before the new archive is actually created.

Despite it should be obvious that a device has a non-volatile value, NFS devices have non-dependable values when an automounter gets in the picture. This led to a great deal of spurious redumping in incremental dumps, so it is somewhat useless to compare two NFS devices numbers over time. So tar now considers all NFS devices as being equal when it comes to comparing directories; this is fairly gross, but there does not seem to be a better way to go.

@FIXME{this section needs to be written}

Levels of Backups

@UNREVISED

An archive containing all the files in the file system is called a full backup or full dump. You could insure your data by creating a full dump every day. This strategy, however, would waste a substantial amount of archive media and user time, as unchanged files are daily re-archived.

It is more efficient to do a full dump only occasionally. To back up files between full dumps, you can a incremental dump. A level one dump archives all the files that have changed since the last full dump.

A typical dump strategy would be to perform a full dump once a week, and a level one dump once a day. This means some versions of files will in fact be archived more than once, but this dump strategy makes it possible to restore a file system to within one day of accuracy by only extracting two archives--the last weekly (full) dump and the last daily (level one) dump. The only information lost would be in files changed or created since the last daily backup. (Doing dumps more than once a day is usually not worth the trouble).

GNU tar comes with scripts you can use to do full and level-one dumps. Using scripts (shell programs) to perform backups and restoration is a convenient and reliable alternative to typing out file name lists and tar commands by hand.

Before you use these scripts, you need to edit the file `backup-specs', which specifies parameters used by the backup scripts and by the restore script. @FIXME{There is no such restore script!}. @FIXME-xref{Script Syntax}. Once the backup parameters are set, you can perform backups or restoration by running the appropriate script.

The name of the restore script is restore. @FIXME{There is no such restore script!}. The names of the level one and full backup scripts are, respectively, level-1 and level-0. The level-0 script also exists under the name weekly, and the level-1 under the name daily---these additional names can be changed according to your backup schedule. @FIXME-xref{Scripted Restoration}, for more information on running the restoration script. @FIXME-xref{Scripted Backups}, for more information on running the backup scripts.

Please Note: The backup scripts and the restoration scripts are designed to be used together. While it is possible to restore files by hand from an archive which was created using a backup script, and to create an archive by hand which could then be extracted using the restore script, it is easier to use the scripts. @FIXME{There is no such restore script!}. See section Using tar to Perform Incremental Dumps, and See section Using tar to Perform Incremental Dumps, before making such an attempt.

@FIXME{shorten node names}

Setting Parameters for Backups and Restoration

@UNREVISED

The file `backup-specs' specifies backup parameters for the backup and restoration scripts provided with tar. You must edit `backup-specs' to fit your system configuration and schedule before using these scripts.

@FIXME{This about backup scripts needs to be written: BS is a shell script .... thus ... `backup-specs' is in shell script syntax.}

@FIXME-xref{Script Syntax}, for an explanation of this syntax.

@FIXME{Whats a parameter .... looked at by the backup scripts ... which will be expecting to find ... now syntax ... value is linked to lame ... `backup-specs' specifies the following parameters:}

`ADMINISTRATOR'
The user name of the backup administrator.
`BACKUP_HOUR'
The hour at which the backups are done. This can be a number from 0 to 23, or the string `now'.
`TAPE_FILE'
The device tar writes the archive to. This device should be attached to the host on which the dump scripts are run. @FIXME{examples for all ...}
`TAPE_STATUS'
The command to use to obtain the status of the archive device, including error count. On some tape drives there may not be such a command; in that case, simply use `TAPE_STATUS=false'.
`BLOCKING'
The blocking factor tar will use when writing the dump archive. See section The Blocking Factor of an Archive.
`BACKUP_DIRS'
A list of file systems to be dumped. You can include any directory name in the list--subdirectories on that file system will be included, regardless of how they may look to other networked machines. Subdirectories on other file systems will be ignored. The host name specifies which host to run tar on, and should normally be the host that actually contains the file system. However, the host machine must have GNU tar installed, and must be able to access the directory containing the backup scripts and their support files using the same file name that is used on the machine where the scripts are run (ie. what pwd will print when in that directory on that machine). If the host that contains the file system does not have this capability, you can specify another host as long as it can access the file system through NFS.
`BACKUP_FILES'
A list of individual files to be dumped. These should be accessible from the machine on which the backup script is run. @FIXME{Same file name, be specific. Through NFS ...}

An Example Text of `Backup-specs'

@UNREVISED

The following is the text of `backup-specs' as it appears at FSF:

# site-specific parameters for file system backup.

ADMINISTRATOR=friedman
BACKUP_HOUR=1
TAPE_FILE=/dev/nrsmt0
TAPE_STATUS="mts -t $TAPE_FILE"
BLOCKING=124
BACKUP_DIRS="
    albert:/fs/fsf
    apple-gunkies:/gd
    albert:/fs/gd2
    albert:/fs/gp
    geech:/usr/jla
    churchy:/usr/roland
    albert:/
    albert:/usr
    apple-gunkies:/
    apple-gunkies:/usr
    gnu:/hack
    gnu:/u
    apple-gunkies:/com/mailer/gnu
    apple-gunkies:/com/archive/gnu"

BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"

Syntax for `Backup-specs'

@UNREVISED

`backup-specs' is in shell script syntax. The following conventions should be considered when editing the script: @FIXME{"conventions?"}

A quoted string is considered to be contiguous, even if it is on more than one line. Therefore, you cannot include commented-out lines within a multi-line quoted string. BACKUP_FILES and BACKUP_DIRS are the two most likely parameters to be multi-line.

A quoted string typically cannot contain wildcards. In `backup-specs', however, the parameters BACKUP_DIRS and BACKUP_FILES can contain wildcards.

Using the Backup Scripts

@UNREVISED

The syntax for running a backup script is:

`script-name' [time-to-be-run]

where time-to-be-run can be a specific system time, or can be now. If you do not specify a time, the script runs at the time specified in `backup-specs' (@FIXME-pxref{Script Syntax}).

You should start a script with a tape or disk mounted. Once you start a script, it prompts you for new tapes or disks as it needs them. Media volumes don't have to correspond to archive files--a multi-volume archive can be started in the middle of a tape that already contains the end of another multi-volume archive. The restore script prompts for media by its archive volume, so to avoid an error message you should keep track of which tape (or disk) contains which volume of the archive. @FIXME{There is no such restore script!}. @FIXME-xref{Scripted Restoration}. @FIXME{Have file names changed?}

The backup scripts write two files on the file system. The first is a record file in `/etc/tar-backup/', which is used by the scripts to store and retrieve information about which files were dumped. This file is not meant to be read by humans, and should not be deleted by them. @FIXME-xref{incremental and listed-incremental}, for a more detailed explanation of this file.

The second file is a log file containing the names of the file systems and files dumped, what time the backup was made, and any error messages that were generated, as well as how much space was left in the media volume after the last volume of the archive was written. You should check this log file after every backup. The file name is `log-mmm-ddd-yyyy-level-1' or `log-mmm-ddd-yyyy-full'.

The script also prints the name of each system being dumped to the standard output.

Using the Restore Script

@UNREVISED

Warning: The GNU tar distribution does not provide any such restore script yet. This section is only listed here for documentation maintenance purposes. In any case, all contents is subject to change as things develop.

@FIXME{A section on non-scripted restore may be a good idea.}

To restore files that were archived using a scripted backup, use the restore script. The syntax for the script is:

where ***** are the file systems to restore from, and ***** is a regular expression which specifies which files to restore. If you specify --all, the script restores all the files in the file system.

You should start the restore script with the media containing the first volume of the archive mounted. The script will prompt for other volumes as they are needed. If the archive is on tape, you don't need to rewind the tape to to its beginning--if the tape head is positioned past the beginning of the archive, the script will rewind the tape as needed. @FIXME-xref{Media}, for a discussion of tape positioning.

If you specify `--all' as the files argument, the restore script extracts all the files in the archived file system into the active file system.

Warning: The script will delete files from the active file system if they were not in the file system when the archive was made.

See section Using tar to Perform Incremental Dumps, and section Using tar to Perform Incremental Dumps, for an explanation of how the script makes that determination.

@FIXME{this may be an option, not a given}

Choosing Files and Names for tar

@UNREVISED

@FIXME{Melissa (still) Doesn't Really Like This "Intro" Paragraph!!!}

Certain options to tar enable you to specify a name for your archive. Other options let you decide which files to include or exclude from the archive, based on when or whether files were modified, whether the file names do or don't match specified patterns, or whether files are in specified directories.

Choosing and Naming Archive Files

@UNREVISED

@FIXME{should the title of this section actually be, "naming an archive"?}

By default, tar uses an archive file name that was compiled when it was built on the system; usually this name refers to some physical tape drive on the machine. However, the person who installed tar on the system may not set the default to a meaningful value as far as most users are concerned. As a result, you will usually want to tell tar where to find (or create) the archive. The --file=archive-name (-f archive-name) option allows you to either specify or name a file to use as the archive instead of the default archive file location.

--file=archive-name
-f archive-name
Name the archive to create or operate on. Use in conjunction with any operation.

For example, in this tar command,

$ tar -cvf collection.tar blues folk jazz

`collection.tar' is the name of the archive. It must directly follow the `-f' option, since whatever directly follows `-f' will end up naming the archive. If you neglect to specify an archive name, you may end up overwriting a file in the working directory with the archive you create since tar will use this file's name for the archive name.

An archive can be saved as a file in the file system, sent through a pipe or over a network, or written to an I/O device such as a tape, floppy disk, or CD write drive.

If you do not name the archive, tar uses the value of the environment variable TAPE as the file name for the archive. If that is not available, tar uses a default, compiled-in archive name, usually that for tape unit zero (ie. `/dev/tu00'). tar always needs an archive name.

If you use `-' as an archive-name, tar reads the archive from standard input (when listing or extracting files), or writes it to standard output (when creating an archive). If you use `-' as an archive-name when modifying an archive, tar reads the original archive from its standard input and writes the entire new archive to its standard output.

@FIXME{might want a different example here; this is already used in "notable tar usages".}

$ cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)

@FIXME{help!}

To specify an archive file on a device attached to a remote machine, use the following:

--file=hostname:/dev/file name

tar will complete the remote connection, if possible, and prompt you for a username and password. If you use `--file=@hostname:/dev/file name', tar will complete the remote connection, if possible, using your username as the username on the remote machine.

If the archive file name includes a colon (`:'), then it is assumed to be a file on another machine. If the archive file is `user@host:file', then file is used on the host host. The remote host is accessed using the rsh program, with a username of user. If the username is omitted (along with the `@' sign), then your user name will be used. (This is the normal rsh behavior.) It is necessary for the remote machine, in addition to permitting your rsh access, to have the `/usr/ucb/rmt' program installed. If you need to use a file whose name includes a colon, then the remote tape drive behavior can be inhibited by using the --force-local option.

@FIXME{i know we went over this yesterday, but bob (and now i do again, too) thinks it's out of the middle of nowhere. it doesn't seem to tie into what came before it well enough <<i moved it now, is it better here?>>. bob also comments that if Amanda isn't free software, we shouldn't mention it..}

When the archive is being created to `/dev/null', GNU tar tries to minimize input and output operations. The Amanda backup system, when used with GNU tar, has an initial sizing pass which uses this feature.

Selecting Archive Members

File Name arguments specify which files in the file system tar operates on, when creating or adding to an archive, or which archive members tar operates on, when reading or deleting from an archive. See section The Five Advanced tar Operations.

To specify file names, you can include them as the last arguments on the command line, as follows:

tar operation [option1 option2 ...] [file name-1 file name-2 ...]

If you specify a directory name as a file name argument, all the files in that directory are operated on by tar.

If you do not specify files when tar is invoked with --create (-c), tar operates on all the non-directory files in the working directory. If you specify either --list (-t) or --extract (--get, -x), tar operates on all the archive members in the archive. If you specify any operation other than one of these three, tar does nothing.

By default, tar takes file names from the command line. However, there are other ways to specify file or member names, or to modify the manner in which tar selects the files or members upon which to operate; @FIXME{add xref here}. In general, these methods work both for specifying the names of files and archive members.

Reading Names from a File

@UNREVISED

Instead of giving the names of files or archive members on the command line, you can put the names into a file, and then use the --files-from=file-of-names (-T file-of-names) option to tar. Give the name of the file which contains the list of files to include as the argument to `--files-from'. In the list, the file names should be separated by newlines. You will frequently use this option when you have generated the list of files to archive with the find utility.

--files-from=file name
-T file name
Get names to extract or create from file file name.

If you give a single dash as a file name for `--files-from', (i.e., you specify either `--files-from=-' or `-T -'), then the file names are read from standard input.

Unless you are running tar with `--create', you can not use both `--files-from=-' and `--file=-' (`-f -') in the same command.

@FIXME{add bob's example, from his message on 2-10-97}

The following example shows how to use find to generate a list of files smaller than 400K in length and put that list into a file called `small-files'. You can then use the `-T' option to tar to specify the files from that file, `small-files', to create the archive `little.tgz'. (The `-z' option to tar compresses the archive with gzip; see section Creating and Reading Compressed Archives for more information.)

$ find . -size -400 -print > small-files
$ tar -c -v -z -T small-files -f little.tgz

@FIXME{say more here to conclude the example/section?}

The --null option causes --files-from=file-of-names (-T file-of-names) to read file names terminated by a NUL instead of a newline, so files whose names contain newlines can be archived using `--files-from'.

--null
Only consider NUL terminated file names, instead of files that terminate in a newline.

The `--null' option is just like the one in GNU xargs and cpio, and is useful with the `-print0' predicate of GNU find. In tar, `--null' also causes --directory=directory (-C directory) options to be treated as file names to archive, in case there are any files out there called `-C'.

This example shows how to use find to generate a list of files larger than 800K in length and put that list into a file called `long-files'. The `-print0' option to find just just like `-print', except that it separates files with a NUL rather than with a newline. You can then run tar with both the `--null' and `-T' options to specify that tar get the files from that file, `long-files', to create the archive `big.tgz'. The `--null' option to tar will cause tar to recognize the NUL separator between files.

$ find . -size +800 -print0 > long-files
$ tar -c -v --null --files-from=long-files --file=big.tar

@FIXME{say anything else here to conclude the section?}

Excluding Some Files

@UNREVISED

To avoid operating on files whose names match a particular pattern, use the --exclude=pattern or --exclude-from=file-of-patterns (-X file-of-patterns) options.

--exclude=pattern
Causes tar to ignore files that match the pattern.

The --exclude=pattern option will prevent any file or member which matches the shell wildcards (pattern) from being operated on (pattern can be a single file name or a more complex expression). For example, if you want to create an archive with all the contents of `/tmp' except the file `/tmp/foo', you can use the command `tar --create --file=arch.tar --exclude=foo'. You may give multiple `--exclude' options.

--exclude-from=file
-X file
Causes tar to ignore files that match the patterns listed in file.

Use the `--exclude-from=file-of-patterns' option to read a list of shell wildcards, one per line, from file; tar will ignore files matching those regular expressions. Thus if tar is called as `tar -c -X foo .' and the file `foo' contains a single line `*.o', no files whose names end in `.o' will be added to the archive.

@FIXME{do the exclude options files need to have stuff separated by newlines the same as the files-from option does?}

Problems with Using the exclude Options

@FIXME{put in for the editor's/editors' amusement, but should be taken out in the final draft, just in case! : }

Some users find `exclude' options confusing. Here are some common pitfalls:

  • The main operating mode of tar will always act on file names listed on the command line, no matter whether or not there is an exclusion which would otherwise affect them. In the example above, if you create an archive and exclude files that end with `*.o', but explicitly name the file `catc.o' after all the options have been listed, `catc.o' will be included in the archive.
  • You can sometimes confuse the meanings of --exclude=pattern and --exclude-from=file-of-patterns (-X file-of-patterns). Be careful: use --exclude=pattern when files to be excluded are given as a pattern on the command line. Use `--exclude-from=file-of-patterns' to introduce the name of a file which contains a list of patterns, one per line; each of these patterns can exclude zero, one, or many files.
  • When you use --exclude=pattern, be sure to quote the pattern parameter, so GNU tar sees wildcard characters like `*'. If you do not do this, the shell might expand the `*' itself using files at hand, so tar might receive a list of files instead of one pattern, or none at all, making the command somewhat illegal. This might not correspond to what you want. For example, write:
    $ tar -c -f archive.tar -X '*/tmp/*' directory
    rather than:
    $ tar -c -f archive.tar -X */tmp/* directory
  • You must use use shell syntax, or globbing, rather than regexp syntax, when using exclude options in tar. If you try to use regexp syntax to describe files to be excluded, your command might fail.
  • In earlier versions of tar, what is now the `--exclude-from=file-of-patterns' option was called `--exclude-pattern' instead. Now, `--exclude=pattern' applies to patterns listed on the command line and `--exclude-from=file-of-patterns' applies to patterns listed in a file.

Wildcards Patterns and Matching

Globbing is the operation by which wildcard characters, `*' or `?' for example, are replaced and expanded into all existing files matching the given pattern. However, tar often uses wildcard patterns for matching (or globbing) archive members instead of actual files in the filesystem. Wildcard patterns are also used for verifying volume labels of tar archives. This section has the purpose of explaining wildcard syntax for tar.

@FIXME{the next few paragraphs need work.}

A pattern should be written according to shell syntax, using wildcard characters to effect globbing. Most characters in the pattern stand for themselves in the matched string, and case is significant: `a' will match only `a', and not `A'. The character `?' in the pattern matches any single character in the matched string. The character `*' in the pattern matches zero, one, or more single characters in the matched string. The character `\' says to take the following character of the pattern literally; it is useful when one needs to match the `?', `*', `[' or `\' characters, themselves.

The character `[', up to the matching `]', introduces a character class. A character class is a list of acceptable characters for the next single character of the matched string. For example, `[abcde]' would match any of the first five letters of the alphabet. Note that within a character class, all of the "special characters" listed above other than `\' lose their special meaning; for example, `[-\\[*?]]' would match any of the characters, `-', `\', `[', `*', `?', or `]'. (Due to parsing constraints, the characters `-' and `]' must either come first or last in a character class.)

If the first character of the class after the opening `[' is `!' or `^', then the meaning of the class is reversed. Rather than listing character to match, it lists those characters which are forbidden as the next single character of the matched string.

Other characters of the class stand for themselves. The special construction `[a-e]', using an hyphen between two letters, is meant to represent all characters between a and e, inclusive.

@FIXME{need to add a sentence or so here to make this clear for those who don't have dan around.}

Periods (`.') or forward slashes (`/') are not considered special for wildcard matches. However, if a pattern completely matches a directory prefix of a matched string, then it matches the full matched string: excluding a directory also excludes all the files beneath it.

There are some discussions floating in the air and asking for modifications in the way GNU tar accomplishes wildcard matches. We perceive any change of semantics in this area as a delicate thing to impose on GNU tar users. On the other hand, the GNU project should be progressive enough to correct any ill design: compatibility at all price is not always a good attitude. In conclusion, it is possible that slight amendments be later brought to the previous description. Your opinions on the matter are welcome.

Operating Only on New Files

@UNREVISED

The --after-date=date (--newer=date, -N date) option causes tar to only work on files whose modification or inode-changed times are newer than the date given. If you use this option when creating or appending to an archive, the archive will only include new files. If you use `--after-date' when extracting an archive, tar will only extract files newer than the date you specify.

If you only want tar to make the date comparison based on modification of the actual contents of the file (rather than inode changes), then use the --newer-mtime=date option.

You may use these options with any operation. Note that these options differ from the --update (-u) operation in that they allow you to specify a particular date against which tar can compare when deciding whether or not to archive the files.

--after-date=date
--newer=date
-N date
Only store files newer than date. Acts on files only if their modification or inode-changed times are later than date. Use in conjunction with any operation.
--newer-mtime=date
Acts like --after-date=date (--newer=date, -N date), but only looks at modification times.

These options limit tar to only operating on files which have been modified after the date specified. A file is considered to have changed if the contents have been modified, or if the owner, permissions, and so forth, have been changed. (For more information on how to specify a date, see section Date input formats; remember that the entire date argument must be quoted if it contains any spaces.)

Gurus would say that --after-date=date (--newer=date, -N date) tests both the mtime (time the contents of the file were last modified) and ctime (time the file's status was last changed: owner, permissions, etc) fields, while --newer-mtime=date tests only mtime field.

To be precise, --after-date=date (--newer=date, -N date) checks both mtime and ctime and processes the file if either one is more recent than date, while --newer-mtime=date only checks mtime and disregards ctime. Neither uses atime (the last time the contents of the file were looked at).

Date specifiers can have embedded spaces. Because of this, you may need to quote date arguments to keep the shell from parsing them as separate arguments.

@FIXME{Need example of --newer-mtime with quoted argument.}

Please Note: --after-date=date (--newer=date, -N date) and --newer-mtime=date should not be used for incremental backups. Some files (such as those in renamed directories) are not selected properly by these options. See section The Incremental Options.

To select files newer than the modification time of a file that already exists, you can use the `--reference' (`-r') option of GNU date, available in GNU shell utilities 1.13 or later. It returns the timestamp of that already existing file; this timestamp expands to become the referent date which `--newer' uses to determine which files to archive. For example, you could say,

$ tar -cf archive.tar --newer="`date -r file`" /home

which tells @FIXME{need to fill this in!}.

Descending into Directories

@UNREVISED

@FIXME{arrggh! this is still somewhat confusing to me. :-< }

@FIXME{show dan bob's comments, from 2-10-97}

Usually, tar will recursively explore all directories (either those given on the command line or through the --files-from=file-of-names (-T file-of-names) option) for the various files they contain. However, you may not always want tar to act this way.

The --no-recursion option inhibits tar's recursive descent into specified directories. If you specify `--no-recursion', you can use the find utility for hunting through levels of directories to construct a list of file names which you could then pass to tar. find allows you to be more selective when choosing which files to archive; see section Reading Names from a File for more information on using find with tar, or look.

--no-recursion
Prevents tar from recursively descending directories.

When you use `--no-recursion', GNU tar grabs directory entries themselves, but does not descend on them recursively. Many people use find for locating files they want to back up, and since tar usually recursively descends on directories, they have to use the `! -d' option to find @FIXME{needs more explanation or a cite to another info file} as they usually do not want all the files in a directory. They then use the option to archive the files located via find.

The problem when restoring files archived in this manner is that the directories themselves are not in the archive; so the --same-permissions (--preserve-permissions, -p) option does not affect them--while users might really like it to. Specifying --no-recursion is a way to tell tar to grab only the directory entries given to it, adding no new files on its own.

@FIXME{example here}

Crossing Filesystem Boundaries

@UNREVISED

tar will normally automatically cross file system boundaries in order to archive files which are part of a directory tree. You can change this behavior by running tar and specifying --one-file-system (-l). This option only affects files that are archived because they are in a directory that is being archived; tar will still archive files explicitly named on the command line or through --files-from=file-of-names (-T file-of-names), regardless of where they reside.

--one-file-system
-l
Prevents tar from crossing file system boundaries when archiving. Use in conjunction with any write operation.

The `--one-file-system' option causes tar to modify its normal behavior in archiving the contents of directories. If a file in a directory is not on the same filesystem as the directory itself, then tar will not archive that file. If the file is a directory itself, tar will not archive anything beneath it; in other words, tar will not cross mount points.

It is reported that using this option, the mount point is is archived, but nothing under it.

This option is useful for making full or incremental archival backups of a file system. If this option is used in conjunction with --verbose (-v), files that are excluded are mentioned by name on the standard error.

Changing the Working Directory

@FIXME{need to read over this node now for continuity; i've switched things around some.}

@UNREVISED

To change the working directory in the middle of a list of file names, either on the command line or in a file specified using --files-from=file-of-names (-T file-of-names), use --directory=directory (-C directory). This will change the working directory to the directory directory after that point in the list.

--directory=directory
-C directory
Changes the working directory in the middle of a command line.

For example,

$ tar -c -f jams.tar grape prune -C food cherry

will place the files `grape' and `prune' from the current directory into the archive `jams.tar', followed by the file `cherry' from the directory `food'. This option is especially useful when you have several widely separated files that you want to store in the same archive.

Note that the file `cherry' is recorded in the archive under the precise name `cherry', not `food/cherry'. Thus, the archive will contain three files that all appear to have come from the same directory; if the archive is extracted with plain `tar --extract', all three files will be written in the current directory.

Contrast this with the command,

$ tar -c -f jams.tar grape prune -C food red/cherry

which records the third file in the archive under the name `red/cherry' so that, if the archive is extracted using `tar --extract', the third file will be written in a subdirectory named `orange-colored'.

You can use the `--directory' option to make the archive independent of the original name of the directory holding the files. The following command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a' into the archive `foo.tar':

$ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a

However, the names of the archive members will be exactly what they were on the command line: `passwd', `hosts', and `libc.a'. They will not appear to be related by file name to the original directories where those files were located.

Note that `--directory' options are interpreted consecutively. If `--directory' specifies a relative file name, it is interpreted relative to the then current directory, which might not be the same as the original current working directory of tar, due to a previous `--directory' option.

@FIXME{dan: does this mean that you *can* use the short option form, but you can *not* use the long option form with --files-from? or is this totally screwed?}

When using `--files-from' (see section Reading Names from a File), you can put `-C' options in the file list. Unfortunately, you cannot put `--directory' options in the file list. (This interpretation can be disabled by using the --null option.)

Absolute File Names

@UNREVISED

-P
--absolute-names
Do not strip leading slashes from file names.

By default, GNU tar drops a leading `/' on input or output. This option turns off this behavior; it is equivalent to changing to the root directory before running tar (except it also turns off the usual warning message).

When tar extracts archive members from an archive, it strips any leading slashes (`/') from the member name. This causes absolute member names in the archive to be treated as relative file names. This allows you to have such members extracted wherever you want, instead of being restricted to extracting the member in the exact directory named in the archive. For example, if the archive member has the name `/etc/passwd', tar will extract it as if the name were really `etc/passwd'.

Other tar programs do not do this. As a result, if you create an archive whose member names start with a slash, they will be difficult for other people with a non-GNU tar program to use. Therefore, GNU tar also strips leading slashes from member names when putting members into the archive. For example, if you ask tar to add the file `/bin/ls' to an archive, it will do so, but the member name will be `bin/ls'.

If you use the --absolute-names (-P) option, tar will do neither of these transformations.

To archive or extract files relative to the root directory, specify the --absolute-names (-P) option.

Normally, tar acts on files relative to the working directory--ignoring superior directory names when archiving, and ignoring leading slashes when extracting.

When you specify --absolute-names (-P), tar stores file names including all superior directory names, and preserves leading slashes. If you only invoked tar from the root directory you would never need the --absolute-names (-P) option, but using this option may be more convenient than switching to root.

@FIXME{Should be an example in the tutorial/wizardry section using this to transfer files between systems.}

@FIXME{Is write access an issue?}

--absolute-names
Preserves full file names (inclusing superior dirctory names) when archiving files. Preserves leading slash when extracting files.

@FIXME{this is still horrible; need to talk with dan on monday.}

tar prints out a message about removing the `/' from file names. This message appears once per GNU tar invocation. It represents something which ought to be told; ignoring what it means can cause very serious surprises, later.

Some people, nevertheless, do not want to see this message. Wanting to play really dangerously, one may of course redirect tar standard error to the sink. For example, under sh:

$ tar -c -f archive.tar /home 2> /dev/null

Another solution, both nicer and simpler, would be to change to the `/' directory first, and then avoid absolute notation. For example:

$ (cd / && tar -c -f archive.tar home)
$ tar -c -f archive.tar -C  / home

Date input formats

Our units of temporal measurement, from seconds on up to months, are so complicated, asymmetrical and disjunctive so as to make coherent mental reckoning in time all but impossible. Indeed, had some tyrannical god contrived to enslave our minds to time, to make it all but impossible for us to escape subjection to sodden routines and unpleasant surprises, he could hardly have done better than handing down our present system. It is like a set of trapezoidal building blocks, with no vertical or horizontal surfaces, like a language in which the simplest thought demands ornate constructions, useless particles and lengthy circumlocutions. Unlike the more successful patterns of language and science, which enable us to face experience boldly or at least level-headedly, our system of temporal calculation silently and persistently encourages our terror of time.

... It is as though architects had to measure length in feet, width in meters and height in ells; as though basic instruction manuals demanded a knowledge of five different languages. It is no wonder then that we often look into our own immediate past or future, last Tuesday or a week from Sunday, with feelings of helpless confusion. ...

--- Robert Grudin, Time and the Art of Living.

This section describes the textual date representations that GNU programs accept. These are the strings you, as a user, can supply as arguments to the various programs. The C interface (via the getdate function) is not described here.

Although the date syntax here can represent any possible time since zero A.D., computer integers are not big enough for such a (comparatively) long time. The earliest date semantically allowed on Unix systems is midnight, 1 January 1970 UCT.

General date syntax

A date is a string, possibly empty, containing many items separated by whitespace. The whitespace may be omitted when no ambiguity arises. The empty string means the beginning of today (i.e., midnight). Order of the items is immaterial. A date string may contain many flavors of items:

  • calendar date items
  • time of the day items
  • time zone items
  • day of the week items
  • relative items
  • pure numbers.

We describe each of these item types in turn, below.

A few numbers may be written out in words in most contexts. This is most useful for specifying day of the week items or relative items (see below). Here is the list: `first' for 1, `next' for 2, `third' for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6, `seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10, `eleventh' for 11 and `twelfth' for 12. Also, `last' means exactly -1.

When a month is written this way, it is still considered to be written numerically, instead of being "spelled in full"; this changes the allowed strings.

Alphabetic case is completely ignored in dates. Comments may be introduced between round parentheses, as long as included parentheses are properly nested. Hyphens not followed by a digit are currently ignored. Leading zeros on numbers are ignored.

Calendar date item

A calendar date item specifies a day of the year. It is specified differently, depending on whether the month is specified numerically or literally. All these strings specify the same calendar date:

1970-09-17           # ISO 8601.
70-9-17              # This century assumed by default.
70-09-17             # Leading zeros are ignored.
9/17/72              # Common U.S. writing.
24 September 1972
24 Sept 72           # September has a special abbreviation.
24 Sep 72            # Three-letter abbreviations always allowed.
Sep 24, 1972
24-sep-72
24sep72

The year can also be omitted. In this case, the last specified year is used, or the current year if none. For example:

9/17
sep 17

Here are the rules.

For numeric months, the ISO 8601 format `year-month-day' is allowed, where year is any positive number, month is a number between 01 and 12, and day is a number between 01 and 31. A leading zero must be present if a number is less than ten. If year is less than 100, then 1900 is added to it to force a date in this century. The construct `month/day/year', popular in the United States, is accepted. Also `month/day', omitting the year.

Literal months may be spelled out in full: `January', `February', `March', `April', `May', `June', `July', `August', `September', `October', `November' or `December'. Literal months may be abbreviated to their first three letters, possibly followed by an abbreviating dot. It is also permitted to write `Sept' instead of `September'.

When months are written literally, the calendar date may be given as any of the following:

day month year
day month
month day year
day-month-year

Or, omitting the year:

month day

Time of day item

A time of day item in date strings specifies the time on a given day. Here are some examples, all of which represent the same time:

20:02:0
20:02
8:02pm
20:02-0500      # In EST (Eastern U.S. Standard Time).

More generally, the time of the day may be given as `hour:minute:second', where hour is a number between 0 and 23, minute is a number between 0 and 59, and second is a number between 0 and 59. Alternatively, `:second' can be omitted, in which case it is taken to be zero.

If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), hour is restricted to run from 1 to 12, and `:minute' may be omitted (taken to be zero). `am' indicates the first half of the day, `pm' indicates the second half of the day. In this notation, 12 is the predecessor of 1: midnight is `12am' while noon is `12pm'.

The time may alternatively be followed by a timezone correction, expressed as `shhmm', where s is `+' or `-', hh is a number of zone hours and mm is a number of zone minutes. When a timezone correction is given this way, it forces interpretation of the time in UTC, overriding any previous specification for the timezone or the local timezone. The minute part of the time of the day may not be elided when a timezone correction is used. This is the only way to specify a timezone correction by fractional parts of an hour.

Either `am'/`pm' or a timezone correction may be specified, but not both.

Timezone item

A timezone item specifies an international timezone, indicated by a small set of letters. Any included period is ignored. Military timezone designations use a single letter. Currently, only integral zone hours may be represented in a timezone item. See the previous section for a finer control over the timezone correction.

Here are many non-daylight-savings-time timezones, indexed by the zone hour value.

+000
`GMT' for Greenwich Mean, `UT' or `UTC' for Universal (Coordinated), `WET' for Western European and `Z' for militaries.
+100
`WAT' for West Africa and `A' for militaries.
+200
`AT' for Azores and `B' for militaries.
+300
`C' for militaries.
+400
`AST' for Atlantic Standard and `D' for militaries.
+500
`E' for militaries and `EST' for Eastern Standard.
+600
`CST' for Central Standard and `F' for militaries.
+700
`G' for militaries and `MST' for Mountain Standard.
+800
`H' for militaries and `PST' for Pacific Standard.
+900
`I' for militaries and `YST' for Yukon Standard.
+1000
`AHST' for Alaska-Hawaii Standard, `CAT' for Central Alaska, `HST' for Hawaii Standard and `K' for militaries.
+1100
`L' for militaries and `NT' for Nome.
+1200
`IDLW' for International Date Line West and `M' for militaries.
-100
`CET' for Central European, `FWT' for French Winter, `MET' for Middle European, `MEWT' for Middle European Winter, `N' for militaries and `SWT' for Swedish Winter.
-200
`EET' for Eastern European, USSR Zone 1 and `O' for militaries.
-300
`BT' for Baghdad, USSR Zone 2 and `P' for militaries.
-400
`Q' for militaries and `ZP4' for USSR Zone 3.
-500
`R' for militaries and `ZP5' for USSR Zone 4.
-600
`S' for militaries and `ZP6' for USSR Zone 5.
-700
`T' for militaries and `WAST' for West Australian Standard.
-800
`CCT' for China Coast, USSR Zone 7 and `U' for militaries.
-900
`JST' for Japan Standard, USSR Zone 8 and `V' for militaries.
-1000
`EAST' for East Australian Standard, `GST' for Guam Standard, USSR Zone 9 and `W' for militaries.
-1100
`X' for militaries.
-1200
`IDLE' for International Date Line East, `NZST' for New Zealand Standard, `NZT' for New Zealand and `Y' for militaries.

Here are many DST timezones, indexed by the zone hour value. Also, by following a non-DST timezone by the string `DST' in a separate word (that is, separated by some whitespace), the corresponding DST timezone may be specified.

0
`BST' for British Summer.
+400
`ADT' for Atlantic Daylight.
+500
`EDT' for Eastern Daylight.
+600
`CDT' for Central Daylight.
+700
`MDT' for Mountain Daylight.
+800
`PDT' for Pacific Daylight.
+900
`YDT' for Yukon Daylight.
+1000
`HDT' for Hawaii Daylight.
-100
`MEST' for Middle European Summer, `MESZ' for Middle European Summer, `SST' for Swedish Summer and `FST' for French Summer.
-700
`WADT' for West Australian Daylight.
-1000
`EADT' for Eastern Australian Daylight.
-1200
`NZDT' for New Zealand Daylight.

Day of week item

The explicit mention of a day of the week will forward the date (only if necessary) to reach that day of the week in the future.

Days of the week may be spelled out in full: `Sunday', `Monday', `Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may be abbreviated to their first three letters, optionally followed by a period. The special abbreviations `Tues' for `Tuesday', `Wednes' for `Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.

A number may precede a day of the week item to move forward supplementary weeks. It is best used in expression like `third monday'. In this context, `last day' or `next day' is also acceptable; they move one week before or after the day that day by itself would represent.

A comma following a day of the week item is ignored.

Relative item in date strings

Relative items adjust a date (or the current date if none) forward or backward. The effects of relative items accumulate. Here are some examples:

1 year
1 year ago
3 years
2 days

The unit of time displacement may be selected by the string `year' or `month' for moving by whole years or months. These are fuzzy units, as years and months are not all of equal duration. More precise units are `fortnight' which is worth 14 days, `week' worth 7 days, `day' worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60 seconds, and `second' or `sec' worth one second. An `s' suffix on these units is accepted and ignored.

The unit of time may be preceded by a multiplier, given as an optionally signed number. Unsigned numbers are taken as positively signed. No number at all implies 1 for a multiplier. Following a relative item by the string `ago' is equivalent to preceding the unit by a multiplicator with value -1.

The string `tomorrow' is worth one day in the future (equivalent to `day'), the string `yesterday' is worth one day in the past (equivalent to `day ago').

The strings `now' or `today' are relative items corresponding to zero-valued time displacement, these strings come from the fact a zero-valued time displacement represents the current time when not otherwise change by previous items. They may be used to stress other items, like in `12:00 today'. The string `this' also has the meaning of a zero-valued time displacement, but is preferred in date strings like `this thursday'.

When a relative item makes the resulting date to cross the boundary between DST and non-DST (or vice-versa), the hour is adjusted according to the local time.

Pure numbers in date strings

The precise intepretation of a pure decimal number is dependent of the context in the date string.

If the decimal number is of the form yyyymmdd and no other calendar date item (see section Calendar date item) appears before it in the date string, then yyyy is read as the year, mm as the month number and dd as the day of the month, for the specified calendar date.

If the decimal number is of the form hhmm and no other time of day item appears before it in the date string, then hh is read as the hour of the day and mm as the minute of the hour, for the specified time of the day. mm can also be omitted.

If both a calendar date and a time of day appear to the left of a number in the date string, but no relative item, then the number overrides the year.

Authors of getdate

getdate was originally implemented by Steven M. Bellovin (`smb@research.att.com') while at the University of North Carolina at Chapel Hill. The code was later tweaked by a couple of people on Usenet, then completely overhauled by Rich $alz (`rsalz@bbn.com') and Jim Berets (`jberets@bbn.com') in August, 1990. Various revisions for the GNU system were made by David MacKenzie, Jim Meyering, and others.

This chapter was originally produced by Fran@,{c}ois Pinard (`pinard@iro.umontreal.ca') from the `getdate.y' source code, and then edited by K. Berry (`kb@cs.umb.edu').

Controlling the Archive Format

@FIXME{need an intro here}

Making tar Archives More Portable

Creating a tar archive on a particular system that is meant to be useful later on many other machines and with other versions of tar is more challenging than you might think. tar archive formats have been evolving since the first versions of Unix. Many such formats are around, and are not always comptible with each other. This section discusses a few problems, and gives some advice about making tar archives more portable.

One golden rule is simplicity. For example, limit your tar archives to contain only regular files and directories, avoiding other kind of special files. Do not attempt to save sparse files or contiguous files as such. Let's discuss a few more problems, in turn.

Portable Names

Use straight file and directory names, made up of printable ASCII characters, avoiding colons, slashes, backslashes, spaces, and other dangerous characters. Avoid deep directory nesting. Accounting for oldish System V machines, limit your file and directory names to 14 characters or less.

If you intend to have your tar archives to be read under MSDOS, you should not rely on case distinction for file names, and you might use the GNU doschk program for helping you further diagnosing illegal MSDOS names, which are even more limited than System V's.

Symbolic Links

Normally, when tar archives a symbolic link, it writes a block to the archive naming the target of the link. In that way, the tar archive is a faithful record of the filesystem contents. --dereference (-h) is used with --create (-c), and causes tar to archive the files symbolic links point to, instead of the links themselves. When this option is used, when tar encounters a symbolic link, it will archive the linked-to file, instead of simply recording the presence of a symbolic link.

The name under which the file is stored in the file system is not recorded in the archive. To record both the symbolic link name and the file name in the system, archive the file under both names. If all links were recorded automatically by tar, an extracted file might be linked to a file name that no longer exists in the file system.

If a linked-to file is encountered again by tar while creating the same archive, an entire second copy of it will be stored. (This might be considered a bug.)

So, for portable archives, do not archive symbolic links as such, and use --dereference (-h): many systems do not support symbolic links, and moreover, your distribution might be unusable if it contains unresolved symbolic links.

Old V7 Archives

Certain old versions of tar cannot handle additional information recorded by newer tar programs. To create an archive in V7 format (not ANSI), which can be read by these old versions, specify the --old-archive (-o) option in conjunction with the --create (-c). tar also accepts `--portability' for this option. When you specify it, tar leaves out information about directories, pipes, fifos, contiguous files, and device files, and specifies file ownership by group and user IDs instead of group and user names.

When updating an archive, do not use --old-archive (-o) unless the archive was created with using this option.

In most cases, a new format archive can be read by an old tar program without serious trouble, so this option should seldom be needed. On the other hand, most modern tars are able to read old format archives, so it might be safer for you to always use --old-archive (-o) for your distributions.

GNU tar and POSIX tar

GNU tar was based on an early draft of the POSIX 1003.1 ustar standard. GNU extensions to tar, such as the support for file names longer than 100 characters, use portions of the tar header record which were specified in that POSIX draft as unused. Subsequent changes in POSIX have allocated the same parts of the header record for other purposes. As a result, GNU tar is incompatible with the current POSIX spec, and with tar programs that follow it.

We plan to reimplement these GNU extensions in a new way which is upward compatible with the latest POSIX tar format, but we don't know when this will be done.

In the mean time, there is simply no telling what might happen if you read a GNU tar archive, which uses the GNU extensions, using some other tar program. So if you want to read the archive with another tar program, be sure to write it using the `--old-archive' option (`-o').

@FIXME{is there a way to tell which flavor of tar was used to write a particular archive before you try to read it?}

Traditionally, old tars have a limit of 100 characters. GNU tar attempted two different approaches to overcome this limit, using and extending a format specified by a draft of some P1003.1. The first way was not that successful, and involved `@MaNgLeD@' file names, or such; while a second approach used `././@LongLink' and other tricks, yielding better success. In theory, GNU tar should be able to handle file names of practically unlimited length. So, if GNU tar fails to dump and retrieve files having more than 100 characters, then there is a bug in GNU tar, indeed.

But, being strictly POSIX, the limit was still 100 characters. For various other purposes, GNU tar used areas left unassigned in the POSIX draft. POSIX later revised P1003.1 ustar format by assigning previously unused header fields, in such a way that the upper limit for file name length was raised to 256 characters. However, the actual POSIX limit oscillates between 100 and 256, depending on the precise location of slashes in full file name (this is rather ugly). Since GNU tar use the same fields for quite other purposes, it became incompatible with the latest POSIX standards.

For longer or non-fitting file names, we plan to use yet another set of GNU extensions, but this time, complying with the provisions POSIX offers for extending the format, rather than conflicting with it. Whenever an archive uses old GNU tar extension format or POSIX extensions, would it be for very long file names or other specialities, this archive becomes non-portable to other tar implementations. In fact, anything can happen. The most forgiving tars will merely unpack the file using a wrong name, and maybe create another file named something like `@LongName', with the true file name in it. tars not protecting themselves may segment violate!

Compatibility concerns make all this thing more difficult, as we will have to support all these things together, for a while. GNU tar should be able to produce and read true POSIX format files, while being able to detect old GNU tar formats, besides old V7 format, and process them conveniently. It would take years before this whole area stabilizes...

There are plans to raise this 100 limit to 256, and yet produce POSIX conformant archives. Past 256, I do not know yet if GNU tar will go non-POSIX again, or merely refuse to archive the file.

There are plans so GNU tar support more fully the latest POSIX format, while being able to read old V7 format, GNU (semi-POSIX plus extension), as well as full POSIX. One may ask if there is part of the POSIX format that we still cannot support. This simple question has a complex answer. Maybe that, on intimate look, some strong limitations will pop up, but until now, nothing sounds too difficult (but see below). I only have these few pages of POSIX telling about `Extended tar Format' (P1003.1-1990 -- section 10.1.1), and there are references to other parts of the standard I do not have, which should normally enforce limitations on stored file names (I suspect things like fixing what / and NUL means). There are also some points which the standard does not make clear, Existing practice will then drive what I should do.

POSIX mandates that, when a file name cannot fit within 100 to 256 characters (the variance comes from the fact a / is ideally needed as the 156'th character), or a link name cannot fit within 100 characters, a warning should be issued and the file not be stored. Unless some --posix option is given (or POSIXLY_CORRECT is set), I suspect that GNU tar should disobey this specification, and automatically switch to using GNU extensions to overcome file name or link name length limitations.

There is a problem, however, which I did not intimately studied yet. Given a truly POSIX archive with names having more than 100 characters, I guess that GNU tar up to 1.11.8 will process it as if it were an old V7 archive, and be fooled by some fields which are coded differently. So, the question is to decide if the next generation of GNU tar should produce POSIX format by default, whenever possible, producing archives older versions of GNU tar might not be able to read correctly. I fear that we will have to suffer such a choice one of these days, if we want GNU tar to go closer to POSIX. We can rush it. Another possibility is to produce the current GNU tar format by default for a few years, but have GNU tar versions from some 1.POSIX and up able to recognize all three formats, and let older GNU tar fade out slowly. Then, we could switch to producing POSIX format by default, with not much harm to those still having (very old at that time) GNU tar versions prior to 1.POSIX.

POSIX format cannot represent very long names, volume headers, splitting of files in multi-volumes, sparse files, and incremental dumps; these would be all disallowed if --posix or POSIXLY_CORRECT. Otherwise, if tar is given long names, or `-[VMSgG]', then it should automatically go non-POSIX. I think this is easily granted without much discussion.

Another point is that only mtime is stored in POSIX archives, while GNU tar currently also store atime and ctime. If we want GNU tar to go closer to POSIX, my choice would be to drop atime and ctime support on average. On the other hand, I perceive that full dumps or incremental dumps need atime and ctime support, so for those special applications, POSIX has to be avoided altogether.

A few users requested that --sparse (-S) be always active by default, I think that before replying to them, we have to decide if we want GNU tar to go closer to POSIX on average, while producing files. My choice would be to go closer to POSIX in the long run. Besides possible double reading, I do not see any point of not trying to save files as sparse when creating archives which are neither POSIX nor old-V7, so the actual --sparse (-S) would become selected by default when producing such archives, whatever the reason is. So, --sparse (-S) alone might be redefined to force GNU-format archives, and recover its previous meaning from this fact.

GNU-format as it exists now can easily fool other POSIX tar, as it uses fields which POSIX considers to be part of the file name prefix. I wonder if it would not be a good idea, in the long run, to try changing GNU-format so any added field (like ctime, atime, file offset in subsequent volumes, or sparse file descriptions) be wholly and always pushed into an extension block, instead of using space in the POSIX header block. I could manage to do that portably between future GNU tars. So other POSIX tars might be at least able to provide kind of correct listings for the archives produced by GNU tar, if not able to process them otherwise.

Using these projected extensions might induce older tars to fail. We would use the same approach as for POSIX. I'll put out a tar capable of reading POSIXier, yet extended archives, but will not produce this format by default, in GNU mode. In a few years, when newer GNU tars will have flooded out tar 1.11.X and previous, we could switch to producing POSIXier extended archives, with no real harm to users, as almost all existing GNU tars will be ready to read POSIXier format. In fact, I'll do both changes at the same time, in a few years, and just prepare tar for both changes, without effecting them, from 1.POSIX. (Both changes: 1--using POSIX convention for getting over 100 characters; 2--avoiding mangling POSIX headers for GNU extensions, using only POSIX mandated extension techniques).

So, a future tar will have a --posix flag forcing the usage of truly POSIX headers, and so, producing archives previous GNU tar will not be able to read. So, once pretest will announce that feature, it would be particularly useful that users test how exchangeable will be archives between GNU tar with --posix and other POSIX tar.

In a few years, when GNU tar will produce POSIX headers by default, --posix will have a strong meaning and will disallow GNU extensions. But in the meantime, for a long while, --posix in GNU tar will not disallow GNU extensions like --label=archive-label (-V archive-label), --multi-volume (-M), --sparse (-S), or very long file or link names. However, --posix with GNU extensions will use POSIX headers with reserved-for-users extensions to headers, and I will be curious to know how well or bad POSIX tars will react to these.

GNU tar prior to 1.POSIX, and after 1.POSIX without --posix, generates and checks `ustar ', with two suffixed spaces. This is sufficient for older GNU tar not to recognize POSIX archives, and consequently, wrongly decide those archives are in old V7 format. It is a useful bug for me, because GNU tar has other POSIX incompatibilities, and I need to segregate GNU tar semi-POSIX archives from truly POSIX archives, for GNU tar should be somewhat compatible with itself, while migrating closer to latest POSIX standards. So, I'll be very careful about how and when I will do the correction.

Checksumming Problems

SunOS and HP-UX tar fail to accept archives created using GNU tar and containing non-ASCII file names, that is, file names having characters with the eight bit set, because they use signed checksums, while GNU tar uses unsigned checksums while creating archives, as per POSIX standards. On reading, GNU tar computes both checksums and accept any. It is somewhat worrying that a lot of people may go around doing backup of their files using faulty (or at least non-standard) software, not learning about it until it's time to restore their missing files with an incompatible file extractor, or vice versa.

GNU tar compute checksums both ways, and accept any on read, so GNU tar can read Sun tapes even with their wrong checksums. GNU tar produces the standard checksum, however, raising incompatibilities with Sun. That is to say, GNU tar has not been modified to produce incorrect archives to be read by buggy tar's. I've been told that more recent Sun tar now read standard archives, so maybe Sun did a similar patch, after all?

The story seems to be that when Sun first imported tar sources on their system, they recompiled it without realizing that the checksums were computed differently, because of a change in the default signing of char's in their compiler. So they started computing checksums wrongly. When they later realized their mistake, they merely decided to stay compatible with it, and with themselves afterwards. Presumably, but I do not really know, HP-UX has chosen that their tar archives to be compatible with Sun's. The current standards do not favor Sun tar format. In any case, it now falls on the shoulders of SunOS and HP-UX users to get a tar able to read the good archives they receive.

Using Less Space through Compression

Creating and Reading Compressed Archives

@UNREVISED

-z
--gzip
--ungzip
Filter the archive through gzip.

@FIXME{ach; these two bits orig from "compare" (?). where to put?} Some format parameters must be taken into consideration when modifying an archive: @FIXME{???}. Compressed archives cannot be modified.

You can use `--gzip' and `--gunzip' on physical devices (tape drives, etc.) and remote files as well as on normal files; data to or from such devices or remote files is reblocked by another copy of the tar program to enforce the specified (or default) record size. The default compression parameters are used; if you need to override them, avoid the --gzip (--gunzip, --ungzip, -z) option and run gzip explicitly. (Or set the `GZIP' environment variable.)

The --gzip (--gunzip, --ungzip, -z) option does not work with the --multi-volume (-M) option, or with the --update (-u), --append (-r), --concatenate (--catenate, -A), or --delete operations.

It is not exact to say that GNU tar is to work in concert with gzip in a way similar to zip, say. Surely, it is possible that tar and gzip be done with a single call, like in:

$ tar cfz archive.tar.gz subdir

to save all of `subdir' into a gzip'ed archive. Later you can do:

$ tar xfz archive.tar.gz

to explode and unpack.

The difference is that the whole archive is compressed. With zip, archive members are archived individually. tar's method yields better compression. On the other hand, one can view the contents of a zip archive without having to decompress it. As for the tar and gzip tandem, you need to decompress the archive to see its contents. However, this may be done without needing disk space, by using pipes internally:

$ tar tfz archive.tar.gz

About corrupted compressed archives: gzip'ed files have no redundancy, for maximum compression. The adaptive nature of the compression scheme means that the compression tables are implicitly spread all over the archive. If you lose a few blocks, the dynamic construction of the compression tables becomes unsychronized, and there is little chance that you could recover later in the archive.

There are pending suggestions for having a per-volume or per-file compression in GNU tar. This would allow for viewing the contents without decompression, and for resynchronizing decompression at every volume or file, in case of corrupted archives. Doing so, we might loose some compressibility. But this would have make recovering easier. So, there are pros and cons. We'll see!

-Z
--compress
--uncompress
Filter the archive through compress. Otherwise like --gzip (--gunzip, --ungzip, -z).
--use-compress-program=prog
Filter through prog (must accept `-d').

--compress (--uncompress, -Z) stores an archive in compressed format. This option is useful in saving time over networks and space in pipes, and when storage space is at a premium. --compress (--uncompress, -Z) causes tar to compress when writing the archive, or to uncompress when reading the archive.

To perform compression and uncompression on the archive, tar runs the compress utility. tar uses the default compression parameters; if you need to override them, avoid the --compress (--uncompress, -Z) option and run the compress utility explicitly. It is useful to be able to call the compress utility from within tar because the compress utility by itself cannot access remote tape drives.

The --compress (--uncompress, -Z) option will not work in conjunction with the --multi-volume (-M) option or the --append (-r), --update (-u), --append (-r) and --delete operations. See section The Five Advanced tar Operations, for more information on these operations.

If there is no compress utility available, tar will report an error. Please note that the compress program may be covered by a patent, and therefore we recommend you stop using it.

--compress
--uncompress
-z
-Z
When this option is specified, tar will compress (when writing an archive), or uncompress (when reading an archive). Used in conjunction with the --create (-c), --extract (--get, -x), --list (-t) and --compare (--diff, -d) operations.

You can have archives be compressed by using the --gzip (--gunzip, --ungzip, -z) option. This will arrange for tar to use the gzip program to be used to compress or uncompress the archive wren writing or reading it.

To use the older, obsolete, compress program, use the --compress (--uncompress, -Z) option. The GNU Project recommends you not use compress, because there is a patent covering the algorithm it uses. You could be sued for patent infringment merely by running compress.

I have one question, or maybe it's a suggestion if there isn't a way to do it now. I would like to use --gzip (--gunzip, --ungzip, -z), but I'd also like the output to be fed through a program like GNU ecc (actually, right now that's `exactly' what I'd like to use :-)), basically adding ECC protection on top of compression. It seems as if this should be quite easy to do, but I can't work out exactly how to go about it. Of course, I can pipe the standard output of tar through ecc, but then I lose (though I haven't started using it yet, I confess) the ability to have tar use rmt for it's I/O (I think).

I think the most straightforward thing would be to let me specify a general set of filters outboard of compression (preferably ordered, so the order can be automatically reversed on input operations, and with the options they require specifiable), but beggars shouldn't be choosers and anything you decide on would be fine with me.

By the way, I like ecc but if (as the comments say) it can't deal with loss of block sync, I'm tempted to throw some time at adding that capability. Supposing I were to actually do such a thing and get it (apparantly) working, do you accept contributed changes to utilities like that? (Leigh Clayton `loc@soliton.com', May 1995).

Isn't that exactly the role of the --use-compress-prog=program option? I never tried it myself, but I suspect you may want to write a prog script or program able to filter stdin to stdout to way you want. It should recognize the `-d' option, for when extraction is needed rather than creation.

It has been reported that if one writes compressed data (through the --gzip (--gunzip, --ungzip, -z) or --compress (--uncompress, -Z) options) to a DLT and tries to use the DLT compression mode, the data will actually get bigger and one will end up with less space on the tape.

Archiving Sparse Files

@UNREVISED

-S
--sparse
Handle sparse files efficiently.

This option causes all files to be put in the archive to be tested for sparseness, and handled specially if they are. The --sparse (-S) option is useful when many dbm files, for example, are being backed up. Using this option dramatically decreases the amount of space needed to store such a file.

In later versions, this option may be removed, and the testing and treatment of sparse files may be done automatically with any special GNU options. For now, it is an option needing to be specified on the command line with the creation or updating of an archive.

Files in the filesystem occasionally have "holes." A hole in a file is a section of the file's contents which was never written. The contents of a hole read as all zeros. On many operating systems, actual disk storage is not allocated for holes, but they are counted in the length of the file. If you archive such a file, tar could create an archive longer than the original. To have tar attempt to recognize the holes in a file, use --sparse (-S). When you use the --sparse (-S) option, then, for any file using less disk space than would be expected from its length, tar searches the file for consecutive stretches of zeros. It then records in the archive for the file where the consecutive stretches of zeros are, and only archives the "real contents" of the file. On extraction (using --sparse (-S) is not needed on extraction) any such files have hols created wherever the continuous stretches of zeros were found. Thus, if you use --sparse (-S), tar archives won't take more space than the original.

A file is sparse if it contains blocks of zeros whose existence is recorded, but that have no space allocated on disk. When you specify the --sparse (-S) option in conjunction with the --create (-c) operation, tar tests all files for sparseness while archiving. If tar finds a file to be sparse, it uses a sparse representation of the file in the archive. See section How to Create Archives, for more information about creating archives.

--sparse (-S) is useful when archiving files, such as dbm files, likely to contain many nulls. This option dramatically decreases the amount of space needed to store such an archive.

Please Note: Always use --sparse (-S) when performing file system backups, to avoid archiving the expanded forms of files stored sparsely in the system.

Even if your system has no sparse files currently, some may be created in the future. If you use --sparse (-S) while making file system backups as a matter of course, you can be assured the archive will never take more space on the media than the files take on disk (otherwise, archiving a disk filled with sparse files might take hundreds of tapes). @FIXME-xref{incremental when node name is set.}

tar ignores the --sparse (-S) option when reading an archive.

--sparse
-S
Files stored sparsely in the file system are represented sparsely in the archive. Use in conjunction with write operations.

However, users should be well aware that at archive creation time, GNU tar still has to read whole disk file to locate the holes, and so, even if sparse files use little space on disk and in the archive, they may sometimes require inordinate amount of time for reading and examining all-zero blocks of a file. Although it works, it's painfully slow for a large (sparse) file, even though the resulting tar archive may be small. (One user reports that dumping a `core' file of over 400 megabytes, but with only about 3 megabytes of actual data, took about 9 minutes on a Sun Sparstation ELC, with full CPU utilisation.)

This reading is required in all cases and is not related to the fact the --sparse (-S) option is used or not, so by merely not using the option, you are not saving time(6).

Programs like dump do not have to read the entire file; by examining the file system directly, they can determine in advance exactly where the holes are and thus avoid reading through them. The only data it need read are the actual allocated data blocks. GNU tar uses a more portable and straightforward archiving approach, it would be fairly difficult that it does otherwise. Elizabeth Zwicky writes to `comp.unix.internals', on 1990-12-10:

What I did say is that you cannot tell the difference between a hole and an equivalent number of nulls without reading raw blocks. st_blocks at best tells you how many holes there are; it doesn't tell you where. Just as programs may, conceivably, care what st_blocks is (care to name one that does?), they may also care where the holes are (I have no examples of this one either, but it's equally imaginable).

I conclude from this that good archivers are not portable. One can arguably conclude that if you want a portable program, you can in good conscience restore files with as many holes as possible, since you can't get it right.

Handling File Attributes

@UNREVISED

When tar reads files, this causes them to have the access times updated. To have tar attempt to set the access times back to what they were before they were read, use the --atime-preserve option. This doesn't work for files that you don't own, unless you're root, and it doesn't interact with incremental dumps nicely (see section Performing Backups and Restoring Files), but it is good enough for some purposes.

Handling of file attributes

--atime-preserve
Do not change access times on dumped files.
-m
--touch
Do not extract file modified time. When this option is used, tar leaves the modification times of the files it extracts as the time when the files were extracted, instead of setting it to the time recorded in the archive. This option is meaningless with --list (-t).
--same-owner
Create extracted files with the same ownership they have in the archive. When using super-user at extraction time, ownership is always restored. So, this option is meaningful only for non-root users, when tar is executed on those systems able to give files away. This is considered as a security flaw by many people, at least because it makes quite difficult to correctly account users for the disk space they occupy. Also, the suid or sgid attributes of files are easily and silently lost when files are given away. When writing an archive, tar writes the user id and user name separately. If it can't find a user name (because the user id is not in `/etc/passwd'), then it does not write one. When restoring, and doing a chmod like when you use --same-permissions (--preserve-permissions, -p) (@FIXME{same-owner?}), it tries to look the name (if one was written) up in `/etc/passwd'. If it fails, then it uses the user id stored in the archive instead.
--numeric-owner
The --numeric-owner option allows (ANSI) archives to be written without user/group name information or such information to be ignored when extracting. It effectively disables the generation and/or use of user/group name information. This option forces extraction using the numeric ids from the archive, ignoring the names. This is useful in certain circumstances, when restoring a backup from an emergency floppy with different passwd/group files for example. It is otherwise impossible to extract files with the right ownerships if the password file in use during the extraction does not match the one belonging to the filesystem(s) being extracted. This occurs, for example, if you are restoring your files after a major crash and had booted from an emergency floppy with no password file or put your disk into another machine to do the restore. The numeric ids are always saved into tar archives. The identifying names are added at create time when provided by the system, unless --old-archive (-o) is used. Numeric ids could be used when moving archives between a collection of machines using a centralized management for attribution of numeric ids to users and groups. This is often made through using the NIS capabilities. When making a tar file for distribution to other sites, it is sometimes cleaner to use a single owner for all files in the distribution, and nicer to specify the write permission bits of the files as stored in the archive independently of their actual value on the file system. The way to prepare a clean distribution is usually to have some Makefile rule creating a directory, copying all needed files in that directory, then setting ownership and permissions as wanted (there are a lot of possible schemes), and only then making a tar archive out of this directory, before cleaning everything out. Of course, we could add a lot of options to GNU tar for fine tuning permissions and ownership. This is not the good way, I think. GNU tar is already crowded with options and moreover, the approach just explained gives you a great deal of control already.
-p
--same-permissions
--preserve-permissions
Extract all protection information. This option causes tar to set the modes (access permissions) of extracted files exactly as recorded in the archive. If this option is not used, the current umask setting limits the permissions on extracted files. This option is meaningless with --list (-t).
--preserve
Same as both --same-permissions (--preserve-permissions, -p) and --same-order (--preserve-order, -s). The --preserve option has no equivalent short option name. It is equivalent to --same-permissions (--preserve-permissions, -p) plus --same-order (--preserve-order, -s). @FIXME{I do not see the purpose of such an option. (Neither I. FP.)}

The Standard Format

@UNREVISED

While an archive may contain many files, the archive itself is a single ordinary file. Like any other file, an archive file can be written to a storage device such as a tape or disk, sent through a pipe or over a network, saved on the active file system, or even stored in another archive. An archive file is not easy to read or manipulate without using the tar utility or Tar mode in GNU Emacs.

Physically, an archive consists of a series of file entries terminated by an end-of-archive entry, which consists of 512 zero bytes. A file entry usually describes one of the files in the archive (an archive member), and consists of a file header and the contents of the file. File headers contain file names and statistics, checksum information which tar uses to detect file corruption, and information about file types.

Archives are permitted to have more than one member with the same member name. One way this situation can occur is if more than one version of a file has been stored in the archive. For information about adding new versions of a file to an archive, see section Updating an Archive, and to learn more about having more than one archive member with the same name, see @FIXME-xref{-backup node, when it's written}.

In addition to entries describing archive members, an archive may contain entries which tar itself uses to store information. See section Including a Label in the Archive, for an example of such an archive entry.

A tar archive file contains a series of blocks. Each block contains BLOCKSIZE bytes. Although this format may be thought of as being on magnetic tape, other media are often used.

Each file archived is represented by a header block which describes the file, followed by zero or more blocks which give the contents of the file. At the end of the archive file there may be a block filled with binary zeros as an end-of-file marker. A reasonable system should write a block of zeros at the end, but must not assume that such a block exists when reading an archive.

The blocks may be blocked for physical I/O operations. Each record of n blocks (where n is set by the --blocking-factor=512-size (-b 512-size) option to tar) is written with a single `write ()' operation. On magnetic tapes, the result of such a write is a single record. When writing an archive, the last record of blocks should be written at the full size, with blocks after the zero block containing all zeros. When reading an archive, a reasonable system should properly handle an archive whose last record is shorter than the rest, or which contains garbage records after a zero block.

The header block is defined in C as follows. In the GNU tar distribution, this is part of file `src/tar.h':

/* GNU tar Archive Format description.  */

/* If OLDGNU_COMPATIBILITY is not zero, tar produces archives which, by
   default, are readable by older versions of GNU tar.  This can be
   overriden by using --posix; in this case, POSIXLY_CORRECT in environment
   may be set for enforcing stricter conformance.  If OLDGNU_COMPATIBILITY
   is zero or undefined, tar will eventually produces archives which, by
   default, POSIX compatible; then either using --posix or defining
   POSIXLY_CORRECT enforces stricter conformance.

   This #define will disappear in a few years.  FP, June 1995.  */
#define OLDGNU_COMPATIBILITY 1

/*---------------------------------------------.
| `tar' Header Block, from POSIX 1003.1-1990.  |
`---------------------------------------------*/

/* POSIX header.  */

struct posix_header
{                               /* byte offset */
  char name[100];               /*   0 */
  char mode[8];                 /* 100 */
  char uid[8];                  /* 108 */
  char gid[8];                  /* 116 */
  char size[12];                /* 124 */
  char mtime[12];               /* 136 */
  char chksum[8];               /* 148 */
  char typeflag;                /* 156 */
  char linkname[100];           /* 157 */
  char magic[6];                /* 257 */
  char version[2];              /* 263 */
  char uname[32];               /* 265 */
  char gname[32];               /* 297 */
  char devmajor[8];             /* 329 */
  char devminor[8];             /* 337 */
  char prefix[155];             /* 345 */
                                /* 500 */
};

#define TMAGIC   "ustar"        /* ustar and a null */
#define TMAGLEN  6
#define TVERSION "00"           /* 00 and no null */
#define TVERSLEN 2

/* Values used in typeflag field.  */
#define REGTYPE  '0'            /* regular file */
#define AREGTYPE '\0'           /* regular file */
#define LNKTYPE  '1'            /* link */
#define SYMTYPE  '2'            /* reserved */
#define CHRTYPE  '3'            /* character special */
#define BLKTYPE  '4'            /* block special */
#define DIRTYPE  '5'            /* directory */
#define FIFOTYPE '6'            /* FIFO special */
#define CONTTYPE '7'            /* reserved */

/* Bits used in the mode field, values in octal.  */
#define TSUID    04000          /* set UID on execution */
#define TSGID    02000          /* set GID on execution */
#define TSVTX    01000          /* reserved */
                                /* file permissions */
#define TUREAD   00400          /* read by owner */
#define TUWRITE  00200          /* write by owner */
#define TUEXEC   00100          /* execute/search by owner */
#define TGREAD   00040          /* read by group */
#define TGWRITE  00020          /* write by group */
#define TGEXEC   00010          /* execute/search by group */
#define TOREAD   00004          /* read by other */
#define TOWRITE  00002          /* write by other */
#define TOEXEC   00001          /* execute/search by other */

/*-------------------------------------.
| `tar' Header Block, GNU extensions.  |
`-------------------------------------*/

/* In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for
   contiguous files, so maybe disobeying the `reserved' comment in POSIX
   header description.  I suspect these were meant to be used this way, and
   should not have really been `reserved' in the published standards.  */

/* *BEWARE* *BEWARE* *BEWARE* that the following information is still
   boiling, and may change.  Even if the OLDGNU format description should be
   accurate, the so-called GNU format is not yet fully decided.  It is
   surely meant to use only extensions allowed by POSIX, but the sketch
   below repeats some ugliness from the OLDGNU format, which should rather
   go away.  Sparse files should be saved in such a way that they do *not*
   require two passes at archive creation time.  Huge files get some POSIX
   fields to overflow, alternate solutions have to be sought for this.  */

/* Descriptor for a single file hole.  */

struct sparse
{                               /* byte offset */
  char offset[12];              /*   0 */
  char numbytes[12];            /*  12 */
                                /*  24 */
};

/* Sparse files are not supported in POSIX ustar format.  For sparse files
   with a POSIX header, a GNU extra header is provided which holds overall
   sparse information and a few sparse descriptors.  When an old GNU header
   replaces both the POSIX header and the GNU extra header, it holds some
   sparse descriptors too.  Whether POSIX or not, if more sparse descriptors
   are still needed, they are put into as many successive sparse headers as
   necessary.  The following constants tell how many sparse descriptors fit
   in each kind of header able to hold them.  */

#define SPARSES_IN_EXTRA_HEADER  16
#define SPARSES_IN_OLDGNU_HEADER 4
#define SPARSES_IN_SPARSE_HEADER 21

/* The GNU extra header contains some information GNU tar needs, but not
   foreseen in POSIX header format.  It is only used after a POSIX header
   (and never with old GNU headers), and immediately follows this POSIX
   header, when typeflag is a letter rather than a digit, so signaling a GNU
   extension.  */

struct extra_header
{                               /* byte offset */
  char atime[12];               /*   0 */
  char ctime[12];               /*  12 */
  char offset[12];              /*  24 */
  char realsize[12];            /*  36 */
  char longnames[4];            /*  48 */
  char unused_pad1[68];         /*  52 */
  struct sparse sp[SPARSES_IN_EXTRA_HEADER];
                                /* 120 */
  char isextended;              /* 504 */
                                /* 505 */
};

/* Extension header for sparse files, used immediately after the GNU extra
   header, and used only if all sparse information cannot fit into that
   extra header.  There might even be many such extension headers, one after
   the other, until all sparse information has been recorded.  */

struct sparse_header
{                               /* byte offset */
  struct sparse sp[SPARSES_IN_SPARSE_HEADER];
                                /*   0 */
  char isextended;              /* 504 */
                                /* 505 */
};

/* The old GNU format header conflicts with POSIX format in such a way that
   POSIX archives may fool old GNU tar's, and POSIX tar's might well be
   fooled by old GNU tar archives.  An old GNU format header uses the space
   used by the prefix field in a POSIX header, and cumulates information
   normally found in a GNU extra header.  With an old GNU tar header, we
   never see any POSIX header nor GNU extra header.  Supplementary sparse
   headers are allowed, however.  */

struct oldgnu_header
{                               /* byte offset */
  char unused_pad1[345];        /*   0 */
  char atime[12];               /* 345 */
  char ctime[12];               /* 357 */
  char offset[12];              /* 369 */
  char longnames[4];            /* 381 */
  char unused_pad2;             /* 385 */
  struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
                                /* 386 */
  char isextended;              /* 482 */
  char realsize[12];            /* 483 */
                                /* 495 */
};

/* OLDGNU_MAGIC uses both magic and version fields, which are contiguous.
   Found in an archive, it indicates an old GNU header format, which will be
   hopefully become obsolescent.  With OLDGNU_MAGIC, uname and gname are
   valid, though the header is not truly POSIX conforming.  */
#define OLDGNU_MAGIC "ustar  "  /* 7 chars and a null */

/* The standards committee allows only capital A through capital Z for
   user-defined expansion.  */

/* This is a dir entry that contains the names of files that were in the
   dir at the time the dump was made.  */
#define GNUTYPE_DUMPDIR 'D'

/* Identifies the *next* file on the tape as having a long linkname.  */
#define GNUTYPE_LONGLINK 'K'

/* Identifies the *next* file on the tape as having a long name.  */
#define GNUTYPE_LONGNAME 'L'

/* This is the continuation of a file that began on another volume.  */
#define GNUTYPE_MULTIVOL 'M'

/* For storing filenames that do not fit into the main header.  */
#define GNUTYPE_NAMES 'N'

/* This is for sparse files.  */
#define GNUTYPE_SPARSE 'S'

/* This file is a tape/volume header.  Ignore it on extraction.  */
#define GNUTYPE_VOLHDR 'V'

/*--------------------------------------.
| tar Header Block, overall structure.  |
`--------------------------------------*/

/* tar files are made in basic blocks of this size.  */
#define BLOCKSIZE 512

enum archive_format
{
  DEFAULT_FORMAT,               /* format to be decided later */
  V7_FORMAT,                    /* old V7 tar format */
  OLDGNU_FORMAT,                /* GNU format as per before tar 1.12 */
  POSIX_FORMAT,                 /* restricted, pure POSIX format */
  GNU_FORMAT                    /* POSIX format with GNU extensions */
};

union block
{
  char buffer[BLOCKSIZE];
  struct posix_header header;
  struct extra_header extra_header;
  struct oldgnu_header oldgnu_header;
  struct sparse_header sparse_header;
};

/* End of Format description.  */

All characters in header blocks are represented by using 8-bit characters in the local variant of ASCII. Each field within the structure is contiguous; that is, there is no padding used within the structure. Each character on the archive medium is stored contiguously.

Bytes representing the contents of files (after the header block of each file) are not translated in any way and are not constrained to represent characters in any character set. The tar format does not distinguish text files from binary files, and no translation of file contents is performed.

The name, linkname, magic, uname, and gname are null-terminated character strings. All other fileds are zero-filled octal numbers in ASCII. Each numeric field of width w contains w minus 2 digits, a space, and a null, except size, and mtime, which do not contain the trailing null.

The name field is the file name of the file, with directory names (if any) preceding the file name, separated by slashes.

@FIXME{how big a name before field overflows?}

The mode field provides nine bits specifying file permissions and three bits to specify the Set UID, Set GID, and Save Text (sticky) modes. Values for these bits are defined above. When special permissions are required to create a file with a given mode, and the user restoring files from the archive does not hold such permissions, the mode bit(s) specifying those special permissions are ignored. Modes which are not supported by the operating system restoring files from the archive will be ignored. Unsupported modes should be faked up when creating or updating an archive; e.g. the group permission could be copied from the other permission.

The uid and gid fields are the numeric user and group ID of the file owners, respectively. If the operating system does not support numeric user or group IDs, these fields should be ignored.

The size field is the size of the file in bytes; linked files are archived with this field specified as zero. @FIXME-xref{Modifiers}, in particular the --incremental (-G) option.

The mtime field is the modification time of the file at the time it was archived. It is the ASCII representation of the octal value of the last time the file was modified, represented as an integer number of seconds since January 1, 1970, 00:00 Coordinated Universal Time.

The chksum field is the ASCII representation of the octal value of the simple sum of all bytes in the header block. Each 8-bit byte in the header is added to an unsigned integer, initialized to zero, the precision of which shall be no less than seventeen bits. When calculating the checksum, the chksum field is treated as if it were all blanks.

The typeflag field specifies the type of file archived. If a particular implementation does not recognize or permit the specified type, the file will be extracted as if it were a regular file. As this action occurs, tar issues a warning to the standard error.

The atime and ctime fields are used in making incremental backups; they store, respectively, the particular file's access time and last inode-change time.

The offset is used by the --multi-volume (-M) option, when making a multi-volume archive. The offset is number of bytes into the file that we need to restart at to continue the file on the next tape, i.e., where we store the location that a continued file is continued at.

The following fields were added to deal with sparse files. A file is sparse if it takes in unallocated blocks which end up being represented as zeros, i.e., no useful data. A test to see if a file is sparse is to look at the number blocks allocated for it versus the number of characters in the file; if there are fewer blocks allocated for the file than would normally be allocated for a file of that size, then the file is sparse. This is the method tar uses to detect a sparse file, and once such a file is detected, it is treated differently from non-sparse files.

Sparse files are often dbm files, or other database-type files which have data at some points and emptiness in the greater part of the file. Such files can appear to be very large when an `ls -l' is done on them, when in truth, there may be a very small amount of important data contained in the file. It is thus undesirable to have tar think that it must back up this entire file, as great quantities of room are wasted on empty blocks, which can lead to running out of room on a tape far earlier than is necessary. Thus, sparse files are dealt with so that these empty blocks are not written to the tape. Instead, what is written to the tape is a description, of sorts, of the sparse file: where the holes are, how big the holes are, and how much data is found at the end of the hole. This way, the file takes up potentially far less room on the tape, and when the file is extracted later on, it will look exactly the way it looked beforehand. The following is a description of the fields used to handle a sparse file:

The sp is an array of struct sparse. Each struct sparse contains two 12-character strings which represent an offset into the file and a number of bytes to be written at that offset. The offset is absolute, and not relative to the offset in preceding array element.

The header can hold four of these struct sparse at the moment; if more are needed, they are not stored in the header.

The isextended flag is set when an extended_header is needed to deal with a file. Note that this means that this flag can only be set when dealing with a sparse file, and it is only set in the event that the description of the file will not fit in the alloted room for sparse structures in the header. In other words, an extended_header is needed.

The extended_header structure is used for sparse files which need more sparse structures than can fit in the header. The header can fit 4 such structures; if more are needed, the flag isextended gets set and the next block is an extended_header.

Each extended_header structure contains an array of 21 sparse structures, along with a similar isextended flag that the header had. There can be an indeterminate number of such extended_headers to describe a sparse file.

REGTYPE
AREGTYPE
These flags represent a regular file. In order to be compatible with older versions of tar, a typeflag value of AREGTYPE should be silently recognized as a regular file. New archives should be created using REGTYPE. Also, for backward compatibility, tar treats a regular file whose name ends with a slash as a directory.
LNKTYPE
This flag represents a file linked to another file, of any type, previously archived. Such files are identified in Unix by each file having the same device and inode number. The linked-to name is specified in the linkname field with a trailing null.
SYMTYPE
This represents a symbolic link to another file. The linked-to name is specified in the linkname field with a trailing null.
CHRTYPE
BLKTYPE
These represent character special files and block special files respectively. In this case the devmajor and devminor fields will contain the major and minor device numbers respectively. Operating systems may map the device specifications to their own local specification, or may ignore the entry.
DIRTYPE
This flag specifies a directory or sub-directory. The directory name in the name field should end with a slash. On systems where disk allocation is performed on a directory basis, the size field will contain the maximum number of bytes (which may be rounded to the nearest disk block allocation unit) which the directory may hold. A size field of zero indicates no such limiting. Systems which do not support limiting in this manner should ignore the size field.
FIFOTYPE
This specifies a FIFO special file. Note that the archiving of a FIFO file archives the existence of this file and not its contents.
CONTTYPE
This specifies a contiguous file, which is the same as a normal file except that, in operating systems which support it, all its space is allocated contiguously on the disk. Operating systems which do not allow contiguous allocation should silently treat this type as a normal file.
A ... Z
These are reserved for custom implementations. Some of these are used in the GNU modified format, as described below.

Other values are reserved for specification in future revisions of the P1003 standard, and should not be used by any tar program.

The magic field indicates that this archive was output in the P1003 archive format. If this field contains TMAGIC, the uname and gname fields will contain the ASCII representation of the owner and group of the file respectively. If found, the user and group IDs are used rather than the values in the uid and gid fields.

For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages 169-173 (section 10.1) for Archive/Interchange File Format; and IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940 (section E.4.48) for pax - Portable archive interchange.

GNU Extensions to the Archive Format

@UNREVISED

The GNU format uses additional file types to describe new types of files in an archive. These are listed below.

GNUTYPE_DUMPDIR
'D'
This represents a directory and a list of files created by the --incremental (-G) option. The size field gives the total size of the associated list of files. Each file name is preceded by either a `Y' (the file should be in this archive) or an `N'. (The file is a directory, or is not stored in the archive.) Each file name is terminated by a null. There is an additional null after the last file name.
GNUTYPE_MULTIVOL
'M'
This represents a file continued from another volume of a multi-volume archive created with the --multi-volume (-M) option. The original type of the file is not given here. The size field gives the maximum size of this piece of the file (assuming the volume does not end before the file is written out). The offset field gives the offset from the beginning of the file where this part of the file begins. Thus size plus offset should equal the original size of the file.
GNUTYPE_SPARSE
'S'
This flag indicates that we are dealing with a sparse file. Note that archiving a sparse file requires special operations to find holes in the file, which mark the positions of these holes, along with the number of bytes of data to be found after the hole.
GNUTYPE_VOLHDR
'V'
This file type is used to mark the volume header that was given with the --label=archive-label (-V archive-label) option when the archive was created. The name field contains the name given after the --label=archive-label (-V archive-label) option. The size field is zero. Only the first file in each volume of an archive should have this type.

You may have trouble reading a GNU format archive on a non-GNU system if the options --incremental (-G), --multi-volume (-M), --sparse (-S), or --label=archive-label (-V archive-label) were used when writing the archive. In general, if tar does not use the GNU-added fields of the header, other versions of tar should be able to read the archive. Otherwise, the tar program will give an error, the most likely one being a checksum error.

Comparison of tar and cpio

@UNREVISED

@FIXME{Reorganize the following material}

The cpio archive formats, like tar, do have maximum pathname lengths. The binary and old ASCII formats have a max path length of 256, and the new ASCII and CRC ASCII formats have a max path length of 1024. GNU cpio can read and write archives with arbitrary pathname lengths, but other cpio implementations may crash unexplainedly trying to read them.

tar handles symbolic links in the form in which it comes in BSD; cpio doesn't handle symbolic links in the form in which it comes in System V prior to SVR4, and some vendors may have added symlinks to their system without enhancing cpio to know about them. Others may have enhanced it in a way other than the way I did it at Sun, and which was adopted by AT&T (and which is, I think, also present in the cpio that Berkeley picked up from AT&T and put into a later BSD release--I think I gave them my changes).

(SVR4 does some funny stuff with tar; basically, its cpio can handle tar format input, and write it on output, and it probably handles symbolic links. They may not have bothered doing anything to enhance tar as a result.)

cpio handles special files; traditional tar doesn't.

tar comes with V7, System III, System V, and BSD source; cpio comes only with System III, System V, and later BSD (4.3-tahoe and later).

tar's way of handling multiple hard links to a file can handle file systems that support 32-bit inumbers (e.g., the BSD file system); cpios way requires you to play some games (in its "binary" format, i-numbers are only 16 bits, and in its "portable ASCII" format, they're 18 bits--it would have to play games with the "file system ID" field of the header to make sure that the file system ID/i-number pairs of different files were always different), and I don't know which cpios, if any, play those games. Those that don't might get confused and think two files are the same file when they're not, and make hard links between them.

tars way of handling multiple hard links to a file places only one copy of the link on the tape, but the name attached to that copy is the only one you can use to retrieve the file; cpios way puts one copy for every link, but you can retrieve it using any of the names.

What type of check sum (if any) is used, and how is this calculated.

See the attached manual pages for tar and cpio format. tar uses a checksum which is the sum of all the bytes in the tar header for a file; cpio uses no checksum.

If anyone knows why cpio was made when tar was present at the unix scene,

It wasn't. cpio first showed up in PWB/UNIX 1.0; no generally-available version of UNIX had tar at the time. I don't know whether any version that was generally available within AT&T had tar, or, if so, whether the people within AT&T who did cpio knew about it.

On restore, if there is a corruption on a tape tar will stop at that point, while cpio will skip over it and try to restore the rest of the files.

The main difference is just in the command syntax and header format.

tar is a little more tape-oriented in that everything is blocked to start on a record boundary.

Is there any differences between the ability to recover crashed archives between the two of them. (Is there any chance of recovering crashed archives at all.)

Theoretically it should be easier under tar since the blocking lets you find a header with some variation of `dd skip=nn'. However, modern cpio's and variations have an option to just search for the next file header after an error with a reasonable chance of re-syncing. However, lots of tape driver software won't allow you to continue past a media error which should be the only reason for getting out of sync unless a file changed sizes while you were writing the archive.

If anyone knows why cpio was made when tar was present at the unix scene, please tell me about this too.

Probably because it is more media efficient (by not blocking everything and using only the space needed for the headers where tar always uses 512 bytes per file header) and it knows how to archive special files.

You might want to look at the freely available alternatives. The major ones are afio, GNU tar, and pax, each of which have their own extensions with some backwards compatibility.

Sparse files were tarred as sparse files (which you can easily test, because the resulting archive gets smaller, and GNU cpio can no longer read it).

Tapes and Other Archive Media

@UNREVISED

A few special cases about tape handling warrant more detailed description. These special cases are discussed below.

Many complexities surround the use of tar on tape drives. Since the creation and manipulation of archives located on magnetic tape was the original purpose of tar, it contains many features making such manipulation easier.

Archives are usually written on dismountable media--tape cartridges, mag tapes, or floppy disks.

The amount of data a tape or disk holds depends not only on its size, but also on how it is formatted. A 2400 foot long reel of mag tape holds 40 megabytes of data when formated at 1600 bits per inch. The physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.

Magnetic media are re-usable--once the archive on a tape is no longer needed, the archive can be erased and the tape or disk used over. Media quality does deteriorate with use, however. Most tapes or disks should be disgarded when they begin to produce data errors. EXABYTE tape cartridges should be disgarded when they generate an error count (number of non-usable bits) of more than 10k.

Magnetic media are written and erased using magnetic fields, and should be protected from such fields to avoid damage to stored data. Sticking a floppy disk to a filing cabinet using a magnet is probably not a good idea.

Device Selection and Switching

@UNREVISED

-f [hostname:]file
--file=[hostname:]file
Use archive file or device file on hostname.

This option is used to specify the file name of the archive tar works on.

If the file name is `-', tar reads the archive from standard input (when listing or extracting), or writes it to standard output (when creating). If the `-' file name is given when updating an archive, tar will read the original archive from its standard input, and will write the entire new archive to its standard output.

If the file name contains a `:', it is interpreted as `hostname:file name'. If the hostname contains an at sign (@), it is treated as `user@hostname:file name'. In either case, tar will invoke the command rsh (or remsh) to start up an `/etc/rmt' on the remote machine. If you give an alternate login name, it will be given to the rsh. Naturally, the remote machine must have an executable `/etc/rmt'. This program is free software from the University of California, and a copy of the source code can be found with the sources for tar; it's compiled and installed by default.

If this option is not given, but the environment variable TAPE is set, its value is used; otherwise, old versions of tar used a default archive name (which was picked when tar was compiled). The default is normally set up to be the first tape drive or other transportable I/O medium on the system.

Starting with version 1.11.5, GNU tar uses standard input and standard output as the default device, and I will not try anymore supporting automatic device detection at installation time. This was failing really in too many cases, it was hopeless. This is now completely left to the installer to override standard input and standard output for default device, if this seems preferrable to him/her. Further, I think most actual usages of tar are done with pipes or disks, not really tapes, cartridges or diskettes.

Some users think that using standard input and output is running after trouble. This could lead to a nasty surprise on your screen if you forget to specify an output file name--especially if you are going through a network or terminal server capable of buffering large amounts of output. We had so many bug reports in that area of configuring default tapes automatically, and so many contradicting requests, that we finally consider the problem to be portably intractable. We could of course use something like `/dev/tape' as a default, but this is also running after various kind of trouble, going from hung processes to accidental destruction of real tapes. After having seen all this mess, using standard input and output as a default really sounds like the only clean choice left, and a very useful one too.

GNU tar reads and writes archive in records, I suspect this is the main reason why block devices are preferred over character devices. Most probably, block devices are more efficient too. The installer could also check for `DEFTAPE' in `<sys/mtio.h>'.

--force-local
Archive file is local even if it contains a colon.
--rsh-command=command
Use remote command instead of rsh. This option exists so that people who use something other than the standard rsh (e.g., a Kerberized rsh) can access a remote device. When this command is not used, the shell command found when the tar program was installed is used instead. This is the first found of `/usr/ucb/rsh', `/usr/bin/remsh', `/usr/bin/rsh', `/usr/bsd/rsh' or `/usr/bin/nsh'. The installer may have overriden this by defining the environment variable RSH at installation time.
-[0-7][lmh]
Specify drive and density.
-M
--multi-volume
Create/list/extract multi-volume archive. This option causes tar to write a multi-volume archive--one that may be larger than will fit on the medium used to hold it. See section Archives Longer than One Tape or Disk.
-L num
--tape-length=num
Change tape after writing num x 1024 bytes. This option might be useful when your tape drivers do not properly detect end of physical tapes. By being slightly conservative on the maximum tape length, you might avoid the problem entirely.
-F file
--info-script=file
--new-volume-script=file
Execute `file' at end of each tape. This implies --multi-volume (-M).

The Remote Tape Server

In order to access the tape drive on a remote machine, tar uses the remote tape server written at the University of California at Berkeley. The remote tape server must be installed as `/etc/rmt' on any machine whose tape drive you want to use. tar calls `/etc/rmt' by running an rsh or remsh to the remote machine, optionally using a different login name if one is supplied.

A copy of the source for the remote tape server is provided. It is Copyright (C) 1983 by the Regents of the University of California, but can be freely distributed. Instructions for compiling and installing it are included in the `Makefile'.

Unless you use the --absolute-names (-P) option, GNU tar will not allow you to create an archive that contains absolute file names (a file name beginning with `/'.) If you try, tar will automatically remove the leading `/' from the file names it stores in the archive. It will also type a warning message telling you what it is doing.

When reading an archive that was created with a different tar program, GNU tar automatically extracts entries in the archive which have absolute file names as if the file names were not absolute. This is an important feature. A visitor here once gave a tar tape to an operator to restore; the operator used Sun tar instead of GNU tar, and the result was that it replaced large portions of our `/bin' and friends with versions from the tape; needless to say, we were unhappy about having to recover the file system from backup tapes.

For example, if the archive contained a file `/usr/bin/computoy', GNU tar would extract the file to `usr/bin/computoy', relative to the current directory. If you want to extract the files in an archive to the same absolute names that they had when the archive was created, you should do a `cd /' before extracting the files from the archive, or you should either use the --absolute-names (-P) option, or use the command `tar -C / ...'.

Some versions of Unix (Ultrix 3.1 is know to have this problem), can claim that a short write near the end of a tape succeeded, when it actually failed. This will result in the -M option not working correctly. The best workaround at the moment is to use a significantly larger blocking factor than the default 20.

In order to update an archive, tar must be able to backspace the archive in order to reread or rewrite a record that was just read (or written). This is currently possible only on two kinds of files: normal disk files (or any other file that can be backspaced with `lseek'), and industry-standard 9-track magnetic tape (or any other kind of tape that can be backspaced with the MTIOCTOP ioctl.

This means that the --append (-r), --update (-u), --concatenate (--catenate, -A), and --delete commands will not work on any other kind of file. Some media simply cannot be backspaced, which means these commands and options will never be able to work on them. These non-backspacing media include pipes and cartridge tape drives.

Some other media can be backspaced, and tar will work on them once tar is modified to do so.

Archives created with the --multi-volume (-M), --label=archive-label (-V archive-label), and --incremental (-G) options may not be readable by other version of tar. In particular, restoring a file that was split over a volume boundary will require some careful work with dd, if it can be done at all. Other versions of tar may also create an empty file whose name is that of the volume header. Some versions of tar may create normal files instead of directories archived with the --incremental (-G) option.

Some Common Problems and their Solutions

errors from system:
permission denied
no such file or directory
not owner

errors from tar:
directory checksum error
header format error

errors from media/system:
i/o error
device busy

Blocking

@UNREVISED

Block and record terminology is rather confused, and it is also confusing to the expert reader. On the other hand, readers who are new to the field have a fresh mind, and they may safely skip the next two paragraphs, as the remainder of this manual uses those two terms in a quite consistent way.

John Gilmore, the writer of the public domain tar from which GNU tar was originally derived, wrote (June 1995):

The nomenclature of tape drives comes from IBM, where I believe they were invented for the IBM 650 or so. On IBM mainframes, what is recorded on tape are tape blocks. The logical organization of data is into records. There are various ways of putting records into blocks, including F (fixed sized records), V (variable sized records), FB (fixed blocked: fixed size records, n to a block), VB (variable size records, n to a block), VSB (variable spanned blocked: variable sized records that can occupy more than one block), etc. The JCL `DD RECFORM=' parameter specified this to the operating system.

The Unix man page on tar was totally confused about this. When I wrote PD TAR, I used the historically correct terminology (tar writes data records, which are grouped into blocks). It appears that the bogus terminology made it into POSIX (no surprise here), and now Fran@,{c}ois has migrated that terminology back into the source code too.

The term physical block means the basic transfer chunk from or to a device, after which reading or writing may stop without anything being lost. In this manual, the term block usually refers to a disk physical block, assuming that each disk block is 512 bytes in length. It is true that some disk devices have different physical blocks, but tar ignore these differences in its own format, which is meant to be portable, so a tar block is always 512 bytes in length, and block always mean a tar block. The term logical block often represents the basic chunk of allocation of many disk blocks as a single entity, which the operating system treats somewhat atomically; this concept is only barely used in GNU tar.

The term physical record is another way to speak of a physical block, those two terms are somewhat interchangeable. In this manual, the term record usually refers to a tape physical block, assuming that the tar archive is kept on magnetic tape. It is true that archives may be put on disk or used with pipes, but nevertheless, tar tries to read and write the archive one record at a time, whatever the medium in use. One record is made up of an integral number of blocks, and this operation of putting many disk blocks into a single tape block is called reblocking, or more simply, blocking. The term logical record refers to the logical organization of many characters into something meaningful to the application. The term unit record describes a small set of characters which are transmitted whole to or by the application, and often refers to a line of text. Those two last terms are unrelated to what we call a record in GNU tar.

When writing to tapes, tar writes the contents of the archive in chunks known as records. To change the default blocking factor, use the --blocking-factor=512-size (-b 512-size) option. Each record will then be composed of 512-size blocks. (Each tar block is 512 bytes. See section The Standard Format.) Each file written to the archive uses at least one full record. As a result, using a larger record size can result in more wasted space for small files. On the other hand, a larger record size can often be read and written much more efficiently.

Further complicating the problem is that some tape drives ignore the blocking entirely. For these, a larger record size can still improve performance (because the software layers above the tape drive still honor the blocking), but not as dramatically as on tape drives that honor blocking.

When reading an archive, tar can usually figure out the record size on itself. When this is the case, and a non-standard record size was used when the archive was created, tar will print a message about a non-standard blocking factor, and then operate normally. On some tape devices, however, tar cannot figure out the record size itself. On most of those, you can specify a blocking factor (with --blocking-factor=512-size (-b 512-size)) larger than the actual blocking factor, and then use the --read-full-records (-B) option. (If you specify a blocking factor with --blocking-factor=512-size (-b 512-size) and don't use the --read-full-records (-B) option, then tar will not attempt to figure out the recording size itself.) On some devices, you must always specify the record size exactly with --blocking-factor=512-size (-b 512-size) when reading, because tar cannot figure it out. In any case, use --list (-t) before doing any extractions to see whether tar is reading the archive correctly.

tar blocks are all fixed size (512 bytes), and its scheme for putting them into records is to put a whole number of them (one or more) into each record. tar records are all the same size; at the end of the file there's a block containing all zeros, which is how you tell that the remainder of the last record(s) are garbage.

In a standard tar file (no options), the block size is 512 and the record size is 10240, for a blocking factor of 20. What the --blocking-factor=512-size (-b 512-size) option does is sets the blocking factor, changing the record size while leaving the block size at 512 bytes. 20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives; most tape drives these days prefer much bigger records in order to stream and not waste tape. When writing tapes for myself, some tend to use a factor of the order of 2048, say, giving a record size of around one megabyte.

If you use a blocking factor larger than 20, older tar programs might not be able to read the archive, so we recommend this as a limit to use in practice. GNU tar, however, will support arbitrarily large record sizes, limited only by the amount of virtual memory or the physical characteristics of the tape device.

Format Variations

@UNREVISED

Format parameters specify how an archive is written on the archive media. The best choice of format parameters will vary depending on the type and number of files being archived, and on the media used to store the archive.

To specify format parameters when accessing or creating an archive, you can use the options described in the following sections. If you do not specify any format parameters, tar uses default parameters. You cannot modify a compressed archive. If you create an archive with the --blocking-factor=512-size (-b 512-size) option specified (see section The Blocking Factor of an Archive), you must specify that blocking-factor when operating on the archive. See section Controlling the Archive Format, for other examples of format parameter considerations.

The Blocking Factor of an Archive

@UNREVISED

The data in an archive is grouped into blocks, which are 512 bytes. Blocks are read and written in whole number multiples called records. The number of blocks in a record (ie. the size of a record in units of 512 bytes) is called the blocking factor. The --blocking-factor=512-size (-b 512-size) option specifies the blocking factor of an archive. The default blocking factor is typically 20 (ie. 10240 bytes), but can be specified at installation. To find out the blocking factor of an existing archive, use `tar --list --file=archive-name'. This may not work on some devices.

Records are separated by gaps, which waste space on the archive media. If you are archiving on magnetic tape, using a larger blocking factor (and therefore larger records) provides faster throughput and allows you to fit more data on a tape (because there are fewer gaps). If you are archiving on cartridge, a very large blocking factor (say 126 or more) greatly increases performance. A smaller blocking factor, on the other hand, may be usefull when archiving small files, to avoid archiving lots of nulls as tar fills out the archive to the end of the record. In general, the ideal record size depends on the size of the inter-record gaps on the tape you are using, and the average size of the files you are archiving. See section How to Create Archives, for information on writing archives.

@FIXME{Need example of using a cartridge with blocking factor=126 or more.}

Archives with blocking factors larger than 20 cannot be read by very old versions of tar, or by some newer versions of tar running on old machines with small address spaces. With GNU tar, the blocking factor of an archive is limited only by the maximum record size of the device containing the archive, or by the amount of available virtual memory.

Also, on some systems, not using adequate blocking factors, as sometimes imposed by the device drivers, may yield unexpected diagnostics. For example, this has been reported:

Cannot write to /dev/dlt: Invalid argument

In such cases, it sometimes happen that the tar bundled by the system is aware of block size idiosyncrasies, while GNU tar requires an explicit specification for the block size, which it cannot guess. This yields some people to consider GNU tar is misbehaving, because by comparison, the bundle tar works OK. Adding -b 256, for example, might resolve the problem.

If you use a non-default blocking factor when you create an archive, you must specify the same blocking factor when you modify that archive. Some archive devices will also require you to specify the blocking factor when reading that archive, however this is not typically the case. Usually, you can use --list (-t) without specifying a blocking factor---tar reports a non-default record size and then lists the archive members as it would normally. To extract files from an archive with a non-standard blocking factor (particularly if you're not sure what the blocking factor is), you can usually use the --read-full-records (-B) option while specifying a blocking factor larger then the blocking factor of the archive (ie. `tar --extract --read-full-records --blocking-factor=300'. See section How to List Archives, for more information on the --list (-t) operation. See section Options to Help Read Archives, for a more detailed explanation of that option.

--blocking-factor=number
-b number
Specifies the blocking factor of an archive. Can be used with any operation, but is usually not necessary with --list (-t).

Device blocking

-b blocks
--blocking-factor=blocks
Set record size to blocks * 512 bytes. This option is used to specify a blocking factor for the archive. When reading or writing the archive, tar, will do reads and writes of the archive in records of block*512 bytes. This is true even when the archive is compressed. Some devices requires that all write operations be a multiple of a certain size, and so, tar pads the archive out to the next record boundary. The default blocking factor is set when tar is compiled, and is typically 20. Blocking factors larger than 20 cannot be read by very old versions of tar, or by some newer versions of tar running on old machines with small address spaces. With a magnetic tape, larger records give faster throughput and fit more data on a tape (because there are fewer inter-record gaps). If the archive is in a disk file or a pipe, you may want to specify a smaller blocking factor, since a large one will result in a large number of null bytes at the end of the archive. When writing cartridge or other streaming tapes, a much larger blocking factor (say 126 or more) will greatly increase performance. However, you must specify the same blocking factor when reading or updating the archive. Apparently, Exabyte drives have a physical block size of 8K bytes. If we choose our blocksize as a multiple of 8k bytes, then the problem seems to dissapper. Id est, we are using block size of 112 right now, and we haven't had the problem since we switched... With GNU tar the blocking factor is limited only by the maximum record size of the device containing the archive, or by the amount of available virtual memory. However, deblocking or reblocking is virtually avoided in a special case which often occurs in practice, but which requires all the following conditions to be simultaneously true:
  • the archive is subject to a compression option,
  • the archive is not handled through standard input or output, nor redirected nor piped,
  • the archive is directly handled to a local disk, instead of any special device,
  • --blocking-factor=512-size (-b 512-size) is not explicitely specified on the tar invocation.
In previous versions of GNU tar, the `--compress-block' option (or even older: `--block-compress') was necessary to reblock compressed archives. It is now a dummy option just asking not to be used, and otherwise ignored. If the output goes directly to a local disk, and not through stdout, then the last write is not extended to a full record size. Otherwise, reblocking occurs. Here are a few other remarks on this topic:
  • gzip will complain about trailing garbage if asked to uncompress a compressed archive on tape, there is an option to turn the message off, but it breaks the regularity of simply having to use `prog -d' for decompression. It would be nice if gzip was silently ignoring any number of trailing zeros. I'll ask Jean-loup Gailly, by sending a copy of this message to him.
  • compress does not show this problem, but as Jean-loup pointed out to Michael, `compress -d' silently adds garbage after the result of decompression, which tar ignores because it already recognized its end-of-file indicator. So this bug may be safely ignored.
  • `gzip -d -q' will be silent about the trailing zeros indeed, but will still return an exit status of 2 which tar reports in turn. tar might ignore the exit status returned, but I hate doing that, as it weakens the protection tar offers users against other possible problems at decompression time. If gzip was silently skipping trailing zeros and also avoiding setting the exit status in this innocuous case, that would solve this situation.
  • tar should become more solid at not stopping to read a pipe at the first null block encountered. This inelegantly breaks the pipe. tar should rather drain the pipe out before exiting itself.
-i
--ignore-zeros
Ignore blocks of zeros in archive (means EOF). The --ignore-zeros (-i) option causes tar to ignore blocks of zeros in the archive. Normally a block of zeros indicates the end of the archive, but when reading a damaged archive, or one which was created by cat-ing several archives together, this option allows tar to read the entire archive. This option is not on by default because many versions of tar write garbage after the zeroed blocks. Note that this option causes tar to read to the end of the archive file, which may sometimes avoid problems when multiple files are stored on a single physical tape.
-B
--read-full-records
Reblock as we read (for reading 4.2BSD pipes). If --read-full-records (-B) is used, tar will not panic if an attempt to read a record from the archive does not return a full record. Instead, tar will keep reading until it has obtained a full record. This option is turned on by default when tar is reading an archive from standard input, or from a remote machine. This is because on BSD Unix systems, a read of a pipe will return however much happens to be in the pipe, even if it is less than tar requested. If this option was not used, tar would fail as soon as it read an incomplete record from the pipe. This option is also useful with the commands for updating an archive.

Tape blocking

@FIXME{Appropriate options should be moved here from elsewhere.}

When handling various tapes or cartridges, you have to take care of selecting a proper blocking, that is, the number of disk blocks you put together as a single tape block on the tape, without intervening tape gaps. A tape gap is a small landing area on the tape with no information on it, used for decelerating the tape to a full stop, and for later regaining the reading or writing speed. When the tape driver starts reading a record, the record has to be read whole without stopping, as a tape gap is needed to stop the tape motion without loosing information.

Using higher blocking (putting more disk blocks per tape block) will use the tape more efficiently as there will be less tape gaps. But reading such tapes may be more difficult for the system, as more memory will be required to receive at once the whole record. Further, if there is a reading error on a huge record, this is less likely that the system will succeed in recovering the information. So, blocking should not be too low, nor it should be too high. tar uses by default a blocking of 20 for historical reasons, and it does not really matter when reading or writing to disk. Current tape technology would easily accomodate higher blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs. We were told that for some DLT drives, the blocking should be a multiple of 4Kb, preferably 64Kb (-b 128) or 256 for decent performance. Other manufacturers may use different recommendations for the same tapes. This might also depends of the buffering techniques used inside modern tape controllers. Some imposes a minimum blocking, or a maximum blocking. Others request blocking to be some exponent of two.

So, there is no fixed rule for blocking. But blocking at read time should ideally be the same as blocking used at write time. At one place I know, with a wide variety of equipment, they found it best to use a blocking of 32 to guarantee that their tapes are fully interchangeable.

I was also told that, for recycled tapes, prior erasure (by the same drive unit that will be used to create the archives) sometimes lowers the error rates observed at rewriting time.

I might also use `--number-blocks' instead of `--block-number', so `--block' will then expand to `--blocking-factor' unambiguously.

Many Archives on One Tape

@FIXME{Appropriate options should be moved here from elsewhere.}

Most tape devices have two entries in the `/dev' directory, or entries that come in pairs, which differ only in the minor number for this device. Let's take for example `/dev/tape', which often points to the only or usual tape device of a given system. There might be a corresponding `/dev/nrtape' or `/dev/ntape'. The simpler name is the rewinding version of the device, while the name having `nr' in it is the no rewinding version of the same device.

A rewinding tape device will bring back the tape to its beginning point automatically when this device is opened or closed. Since tar opens the archive file before using it and closes it afterwards, this means that a simple:

$ tar cf /dev/tape directory

will reposition the tape to its beginning both prior and after saving directory contents to it, thus erasing prior tape contents and making it so that any subsequent write operation will destroy what has just been saved.

So, a rewinding device is normally meant to hold one and only one file. If you want to put more than one tar archive on a given tape, you will need to avoid using the rewinding version of the tape device. You will also have to pay special attention to tape positioning. Errors in positionning may overwrite the valuable data already on your tape. Many people, burnt by past experiences, will only use rewinding devices and limit themselves to one file per tape, precisely to avoid the risk of such errors. Be fully aware that writing at the wrong position on a tape loses all information past this point and most probably until the end of the tape, and this destroyed information cannot be recovered.

To save directory-1 as a first archive at the beginning of a tape, and leave that tape ready for a second archive, you should use:

$ mt -f /dev/nrtape rewind
$ tar cf /dev/nrtape directory-1

Tape marks are special magnetic patterns written on the tape media, which are later recognizable by the reading hardware. These marks are used after each file, when there are many on a single tape. An empty file (that is to say, two tape marks in a row) signal the logical end of the tape, after which no file exist. Usually, non-rewinding tape device drivers will react to the close request issued by tar by first writing two tape marks after your archive, and by backspacing over one of these. So, if you remove the tape at that time from the tape drive, it is properly terminated. But if you write another file at the current position, the second tape mark will be erased by the new information, leaving only one tape mark between files.

So, you may now save directory-2 as a second archive after the first on the same tape by issuing the command:

$ tar cf /dev/nrtape directory-2

and so on for all the archives you want to put on the same tape.

Another usual case is that you do not write all the archives the same day, and you need to remove and store the tape between two archive sessions. In general, you must remember how many files are already saved on your tape. Suppose your tape already has 16 files on it, and that you are ready to write the 17th. You have to take care of skipping the first 16 tape marks before saving directory-17, say, by using these commands:

$ mt -f /dev/nrtape rewind
$ mt -f /dev/nrtape fsf 16
$ tar cf /dev/nrtape directory-17

In all the previous examples, we put aside blocking considerations, but you should do the proper things for that as well. See section Blocking.

Tape Positions and Tape Marks

@UNREVISED

Just as archives can store more than one file from the file system, tapes can store more than one archive file. To keep track of where archive files (or any other type of file stored on tape) begin and end, tape archive devices write magnetic tape marks on the archive media. Tape drives write one tape mark between files, two at the end of all the file entries.

If you think of data as a series of records "rrrr"'s, and tape marks as "*"'s, a tape might look like the following:

rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------

Tape devices read and write tapes using a read/write tape head---a physical part of the device which can only access one point on the tape at a time. When you use tar to read or write archive data from a tape device, the device will begin reading or writing from wherever on the tape the tape head happens to be, regardless of which archive or what part of the archive the tape head is on. Before writing an archive, you should make sure that no data on the tape will be overwritten (unless it is no longer needed). Before reading an archive, you should make sure the tape head is at the beginning of the archive you want to read. (The restore script will find the archive automatically. @FIXME{There is no such restore script!}. @FIXME-xref{Scripted Restoration}). See section The mt Utility, for an explanation of the tape moving utility.

If you want to add new archive file entries to a tape, you should advance the tape to the end of the existing file entries, backspace over the last tape mark, and write the new archive file. If you were to add two archives to the example above, the tape might look like the following:

rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------

The mt Utility

@UNREVISED

@FIXME{Is it true that this only works on non-block devices? should explain the difference, (fixed or variable).} See section The Blocking Factor of an Archive.

You can use the mt utility to advance or rewind a tape past a specified number of archive files on the tape. This will allow you to move to the beginning of an archive before extracting or reading it, or to the end of all the archives before writing a new one. @FIXME{Why isn't there an "advance 'til you find two tape marks together"?}

The syntax of the mt command is:

mt [-f tapename] operation [number]

where tapename is the name of the tape device, number is the number of times an operation is performed (with a default of one), and operation is one of the following:

@FIXME{is there any use for record operations?}

eof
weof
Writes number tape marks at the current position on the tape.
fsf
Moves tape position forward number files.
bsf
Moves tape position back number files.
rewind
Rewinds the tape. (Ignores number).
offline
rewoff1
Rewinds the tape and takes the tape device off-line. (Ignores number).
status
Prints status information about the tape unit.

@FIXME{Is there a better way to frob the spacing on the list?}

If you don't specify a tapename, mt uses the environment variable TAPE; if TAPE does not exist, mt uses the device `/dev/rmt12'.

mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecognized, and 2 if an operation failed.

@FIXME{New node on how to find an archive?}

If you use --extract (--get, -x) with the --label=archive-label (-V archive-label) option specified, tar will read an archive label (the tape head has to be positioned on it) and print an error if the archive label doesn't match the archive-name specified. archive-name can be any regular expression. If the labels match, tar extracts the archive. See section Including a Label in the Archive. @FIXME-xref{Matching Format Parameters}. @FIXME{fix cross references} `tar --list --label' will cause tar to print the label.

@FIXME{Program to list all the labels on a tape?}

Using Multiple Tapes

@UNREVISED

Often you might want to write a large archive, one larger than will fit on the actual tape you are using. In such a case, you can run multiple tar commands, but this can be inconvenient, particularly if you are using options like --exclude=pattern or dumping entire filesystems. Therefore, tar supports multiple tapes automatically.

Use --multi-volume (-M) on the command line, and then tar will, when it reaches the end of the tape, prompt for another tape, and continue the archive. Each tape will have an independent archive, and can be read without needing the other. (As an exception to this, the file that tar was archiving when it ran out of tape will usually be split between the two archives; in this case you need to extract from the first archive, using --multi-volume (-M), and then put in the second tape when prompted, so tar can restore both halves of the file.)

GNU tar multi-volume archives do not use a truly portable format. You need GNU tar at both end to process them properly.

When prompting for a new tape, tar accepts any of the following responses:

?
Request tar to explain possible responses
q
Request tar to exit immediately.
n file name
Request tar to write the next volume on the file file name.
!
Request tar to run a subshell.
y
Request tar to begin writing the next volume.

(You should only type `y' after you have changed the tape; otherwise tar will write over the volume it just finished.)

If you want more elaborate behavior than this, give tar the --info-script=script-name (--new-volume-script=script-name, -F script-name) option. The file script-name is expected to be a program (or shell script) to be run instead of the normal prompting procedure. When the program finishes, tar will immediately begin writing the next volume. The behavior of the `n' response to the normal tape-change prompt is not available if you use --info-script=script-name (--new-volume-script=script-name, -F script-name).

The method tar uses to detect end of tape is not perfect, and fails on some operating systems or on some devices. You can use the --tape-length=1024-size (-L 1024-size) option if tar can't detect the end of the tape itself. This option selects --multi-volume (-M) automatically. The size argument should then be the usable size of the tape. But for many devices, and floppy disks in particular, this option is never required for real, as far as we know.

The volume number used by tar in its tape-change prompt can be changed; if you give the --volno-file=file-of-number option, then file-of-number should be an unexisting file to be created, or else, a file already containing a decimal number. That number will be used as the volume number of the first volume written. When tar is finished, it will rewrite the file with the now-current volume number. (This does not change the volume number written on a tape label, as per section Including a Label in the Archive, it only affects the number used in the prompt.)

If you want tar to cycle through a series of tape drives, then you can use the `n' response to the tape-change prompt. This is error prone, however, and doesn't work at all with --info-script=script-name (--new-volume-script=script-name, -F script-name). Therefore, if you give tar multiple --file=archive-name (-f archive-name) options, then the specified files will be used, in sequence, as the successive volumes of the archive. Only when the first one in the sequence needs to be used again will tar prompt for a tape change (or run the info script).

Multi-volume archives

With --multi-volume (-M), tar will not abort when it cannot read or write any more data. Instead, it will ask you to prepare a new volume. If the archive is on a magnetic tape, you should change tapes now; if the archive is on a floppy disk, you should change disks, etc.

Each volume of a multi-volume archive is an independent tar archive, complete in itself. For example, you can list or extract any volume alone; just don't specify --multi-volume (-M). However, if one file in the archive is split across volumes, the only way to extract it successfully is with a multi-volume extract command `--extract --multi-volume' (`-xM') starting on or before the volume where the file begins.

For example, let's presume someone has two tape drives on a system named `/dev/tape0' and `/dev/tape1'. For having GNU tar to switch to the second drive when it needs to write the second tape, and then back to the first tape, etc., just do either of:

$ tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 files
$ tar cMff /dev/tape0 /dev/tape1 files

Archives Longer than One Tape or Disk

@UNREVISED

To create an archive that is larger than will fit on a single unit of the media, use the --multi-volume (-M) option in conjunction with the --create (-c) option (see section How to Create Archives). A multi-volume archive can be manipulated like any other archive (provided the --multi-volume (-M) option is specified), but is stored on more than one tape or disk.

When you specify --multi-volume (-M), tar does not report an error when it comes to the end of an archive volume (when reading), or the end of the media (when writing). Instead, it prompts you to load a new storage volume. If the archive is on a magnetic tape, you should change tapes when you see the prompt; if the archive is on a floppy disk, you should change disks; etc.

You can read each individual volume of a multi-volume archive as if it were an archive by itself. For example, to list the contents of one volume, use --list (-t), without --multi-volume (-M) specified. To extract an archive member from one volume (assuming it is described that volume), use --extract (--get, -x), again without --multi-volume (-M).

If an archive member is split across volumes (ie. its entry begins on one volume of the media and ends on another), you need to specify --multi-volume (-M) to extract it successfully. In this case, you should load the volume where the archive member starts, and use `tar --extract --multi-volume'---tar will prompt for later volumes as it needs them. See section Extracting an Entire Archive, for more information about extracting archives.

--info-script=script-name (--new-volume-script=script-name, -F script-name) is like --multi-volume (-M), except that tar does not prompt you directly to change media volumes when a volume is full--instead, tar runs commands you have stored in script-name. For example, this option can be used to eject cassettes, or to broadcast messages such as `Someone please come change my tape' when performing unattended backups. When script-name is done, tar will assume that the media has been changed.

Multi-volume archives can be modified like any other archive. To add files to a multi-volume archive, you need to only mount the last volume of the archive media (and new volumes, if needed). For all other operations, you need to use the entire archive.

If a multi-volume archive was labeled using --label=archive-label (-V archive-label) (see section Including a Label in the Archive) when it was created, tar will not automatically label volumes which are added later. To label subsequent volumes, specify --label=archive-label (-V archive-label) again in conjunction with the --append (-r), --update (-u) or --concatenate (--catenate, -A) operation.

@FIXME{example}

@FIXME{There should be a sample program here, including an exit before end. Is the exit status even checked in tar? :-(}

--multi-volume
-M
Creates a multi-volume archive, when used in conjunction with --create (-c). To perform any other operation on a multi-volume archive, specify --multi-volume (-M) in conjunction with that operation.
--info-script=program-file
-F program-file
Creates a multi-volume archive via a script. Used in conjunction with --create (-c).

Beware that there is no real standard about the proper way, for a tar archive, to span volume boundaries. If you have a multi-volume created by some vendor's tar, there is almost no chance you could read all the volumes with GNU tar. The converse is also true: you may not expect multi-volume archives created by GNU tar to be fully recovered by vendor's tar. Since there is little chance that, in mixed system configurations, some vendor's tar will work on another vendor's machine, and there is a great chance that GNU tar will work on most of them, your best bet is to install GNU tar on all machines between which you know exchange of files is possible.

Tape Files

@UNREVISED

To give the archive a name which will be recorded in it, use the --label=archive-label (-V archive-label) option. This will write a special block identifying volume-label as the name of the archive to the front of the archive which will be displayed when the archive is listed with --list (-t). If you are creating a multi-volume archive with --multi-volume (-M) (@FIXME-pxref{Using Multiple Tapes}), then the volume label will have `Volume nnn' appended to the name you give, where nnn is the number of the volume of the archive. (If you use the --label=archive-label (-V archive-label) option when reading an archive, it checks to make sure the label on the tape matches the one you give. See section Including a Label in the Archive.

When tar writes an archive to tape, it creates a single tape file. If multiple archives are written to the same tape, one after the other, they each get written as separate tape files. When extracting, it is necessary to position the tape at the right place before running tar. To do this, use the mt command. For more information on the mt command and on the organization of tapes into a sequence of tape files, see section The mt Utility.

People seem to often do:

--label="some-prefix `date +some-format`"

or such, for pushing a common date in all volumes or an archive set.

Including a Label in the Archive

@UNREVISED

-V name
--label=name
Create archive with volume name name.

This option causes tar to write out a volume header at the beginning of the archive. If --multi-volume (-M) is used, each volume of the archive will have a volume header of `name Volume n', where n is 1 for the first volume, 2 for the next, and so on.

@FIXME{Should the arg to --label be a quoted string?? No.}

To avoid problems caused by misplaced paper labels on the archive media, you can include a label entry--an archive member which contains the name of the archive--in the archive itself. Use the --label=archive-label (-V archive-label) option in conjunction with the --create (-c) operation to include a label entry in the archive as it is being created.

If you create an archive using both --label=archive-label (-V archive-label) and --multi-volume (-M), each volume of the archive will have an archive label of the form `archive-label Volume n', where n is 1 for the first volume, 2 for the next, and so on. @FIXME-xref{Multi-Volume Archives}, for information on creating multiple volume archives.

If you list or extract an archive using --label=archive-label (-V archive-label), tar will print an error if the archive label doesn't match the archive-label specified, and will then not list nor extract the archive. In those cases, archive-label argument is interpreted as a globbing-style pattern which must match the actual magnetic volume label. See section Excluding Some Files, for a precise description of how match is attempted(7). If the switch --multi-volume (-M) is being used, the volume label matcher will also suffix archive-label by ` Volume [1-9]*' if the initial match fails, before giving up. Since the volume numbering is automatically added in labels at creation time, it sounded logical to equally help the user taking care of it when the archive is being read.

The --label=archive-label (-V archive-label) was once called `--volume', but is not available under that name anymore.

To find out an archive's label entry (or to find out if an archive has a label at all), use `tar --list --verbose'. tar will print the label first, and then print archive member information, as in the example below:

$ tar --verbose --list --file=iamanarchive
V--------- 0 0        0 1992-03-07 12:01 iamalabel--Volume Header--
-rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename
--label=archive-label
-V archive-label
Includes an archive-label at the beginning of the archive when the archive is being created, when used in conjunction with the --create (-c) option. Checks to make sure the archive label matches the one specified (when used in conjunction with the --extract (--get, -x) option.

To get a common information on all tapes of a series, use the --label=archive-label (-V archive-label) option. For having this information different in each series created through a single script used on a regular basis, just manage to get some date string as part of the label. For example:

$ tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"
$ tar --create --file=/dev/tape --multi-volume \
     --volume="Daily backup for `date +%Y-%m-%d`"

Also note that each label has its own date and time, which corresponds to when GNU tar initially attempted to write it, often soon after the operator launches tar or types the carriage return telling that the next tape is ready. Comparing date labels does give an idea of tape throughput only if the delays for rewinding tapes and the operator switching them were negligible, which is ususally not the case.

@FIXME{was --volume}

Verifying Data as It is Stored

-W
--verify
Attempt to verify the archive after writing.

This option causes tar to verify the archive after writing it. Each volume is checked after it is written, and any discrepancies are recorded on the standard error output.

Verification requires that the archive be on a back-space-able medium. This means pipes, some cartridge tape drives, and some other devices cannot be verified.

You can insure the accuracy of an archive by comparing files in the system with archive members. tar can compare an archive to the file system as the archive is being written, to verify a write operation, or can compare a previously written archive, to insure that it is up to date.

To check for discrepancies in an archive immediately after it is written, use the --verify (-W) option in conjunction with the --create (-c) operation. When this option is specified, tar checks archive members against their counterparts in the file system, and reports discrepancies on the standard error. In multi-volume archives, each volume is verified after it is written, before the next volume is written.

To verify an archive, you must be able to read it from before the end of the last written entry. This option is useful for detecting data errors on some tapes. Archives written to pipes, some cartridge tape drives, and some other devices cannot be verified.

One can explicitely compare an already made archive with the file system by using the --compare (--diff, -d) option, instead of using the more automatic --verify (-W) option. See section Comparing Archive Members with the File System.

Note that these two options have a slightly different intent. The --compare (--diff, -d) option how identical are the logical contents of some archive with what is on your disks, while the --verify (-W) option is really for checking if the physical contents agree and if the recording media itself is of dependable quality. So, for the --verify (-W) operation, tar tries to defeat all in-memory cache pertaining to the archive, while it lets the speed optimization undisturbed for the --compare (--diff, -d) option. If you nevertheless use --compare (--diff, -d) for media verification, you may have to defeat the in-memory cache yourself, maybe by opening and reclosing the door latch of your recording unit, forcing some doubt in your operating system about the fact this is really the same volume as the one just written or read.

The --verify (-W) option would not be necessary if drivers were indeed able to detect dependably all write failures. This sometimes require many magnetic heads, some able to read after the writes occurred. One would not say that drivers unable to detect all cases are necessarily flawed, as long as programming is concerned.

Write Protection

Almost all tapes and diskettes, and in a few rare cases, even disks can be write protected, to protect data on them from being changed. Once an archive is written, you should write protect the media to prevent the archive from being accidently overwritten or deleted. (This will protect the archive from being changed with a tape or floppy drive--it will not protect it from magnet fields or other physical hazards).

The write protection device itself is usually an integral part of the physical media, and can be a two position (write enabled/write disabled) switch, a notch which can be popped out or covered, a ring which can be removed from the center of a tape reel, or some other changeable feature.

Index

Jump to: - - a - b - c - d - e - f - g - h - i - j - l - m - n - o - p - r - s - t - u - v - w - y

-

  • --list with file name arguments

    • a

  • abbreviations for months
  • absolute file names
  • Adding archives to an archive
  • Adding files to an Archive
  • Age, excluding files by
  • ago in date strings
  • Alaska-Hawaii Time
  • am in date strings
  • Appending files to an Archive
  • archive
  • Archive creation
  • archive member
  • Archive Name
  • Archives, Appending files to
  • Archiving Directories
  • Atlantic Standard Time
  • authors of getdate
  • Avoiding recursion in directories
  • Azores Time

    • b

  • backup files, type made
  • backup options
  • backup suffix
  • backups, making
  • Baghdad Time
  • beginning of time, for Unix
  • Bellovin, Steven M.
  • Berets, Jim
  • Berry, K.
  • Block number where error occured
  • Blocking Factor
  • blocking factor
  • Blocks per record
  • bug reports
  • Bytes per record

    • c

  • calendar date item
  • case, ignored in dates
  • cat vs concatenate
  • Central Alaska Time
  • Central European Time
  • Central Standard Time
  • Changing directory mid-stream
  • Character class, excluding characters from
  • China Coast Time
  • Choosing an archive file
  • comments, in dates
  • Compressed archives
  • concatenate vs cat
  • Concatenating Archives
  • corrupted archives, corrupted archives

    • d

  • DAT blocking
  • date format, ISO 8601
  • date input formats
  • day in date strings, day in date strings
  • day of week item
  • daylight savings time
  • Deleting files from an archive
  • Deleting from tape archives
  • Descending directories, avoiding
  • Directing output
  • Directories, Archiving
  • Directories, avoiding recursion
  • Directory, changing mid-stream
  • Disk space, running out of
  • displacement of dates
  • Double-checking a write operation
  • dumps, full
  • dumps, incremental

    • e

  • East Australian Standard Time
  • Eastern European Time
  • Eastern Standard Time
  • End-of-archive entries, ignoring
  • entry
  • epoch, for Unix
  • Error message, block number of
  • Exabyte blocking
  • exclude
  • exclude-from
  • Excluding characters from a character class
  • Excluding file by age
  • Excluding files by file system
  • Excluding files by name and pattern
  • exit status
  • Extraction
  • extraction

    • f

  • Feedback from tar
  • file name
  • File Name arguments, alternatives
  • File name arguments, using --list with
  • File names, excluding files by
  • File names, terminated by NUL
  • File names, using symbolic links
  • File system boundaries, not crossing
  • first in date strings
  • Format Options
  • Format Parameters
  • Format, old style
  • fortnight in date strings
  • French Winter Time
  • full dumps

    • g

  • general date syntax
  • getdate
  • Getting more information during the operation
  • Greenwich Mean Time
  • Guam Standard Time

    • h

  • Hawaii Standard Time
  • hour in date strings

    • i

  • Ignoring end-of-archive entries
  • incremental dumps
  • Information during operation
  • Information on progress and status of operations
  • Interactive operation
  • International Date Line East
  • International Date Line West
  • ISO 8601 date format
  • items in date strings

    • j

  • Japan Standard Time

    • l

  • Labeling an archive
  • Labelling multi-volume archives
  • Labels on the archive media
  • Large lists of file names on small machines
  • last day
  • last in date strings
  • Lists of file names

    • m

  • MacKenzie, David
  • member
  • member name
  • Members, replacing with other members
  • Meyering, Jim
  • Middle European Time
  • Middle European Winter Time
  • Middle of the archive, starting in the
  • midnight in date strings
  • minute in date strings
  • minutes, timezone correction by
  • Modes of extracted files
  • Modification time, excluding files by
  • Modification times of extracted files
  • month in date strings
  • month names in date strings
  • months, written-out
  • Mountain Standard Time
  • Multi-volume archives

    • n

  • Naming an archive
  • New Zealand Standard Time
  • next day
  • next in date strings
  • Nome Standard Time
  • noon in date strings
  • now in date strings
  • ntape device
  • NUL terminated file names
  • Number of blocks per record
  • Number of bytes per record
  • numbers, written-out

    • o

  • Old style archives
  • Old style format
  • option syntax, traditional
  • Options when reading archives
  • Options, archive format specifying
  • Options, format specifying
  • ordinal numbers
  • Overwriting old files, prevention

    • p

  • Pacific Standard Time
  • Permissions of extracted files
  • Pinard, F.
  • pm in date strings
  • Progress information
  • Protecting old files
  • pure numbers in date strings

    • r

  • Reading file names from a file
  • Reading incomplete records
  • Record Size
  • Records, incomplete
  • Recursion in directories, avoiding
  • relative items in date strings
  • remote tape drive
  • Removing files from an archive
  • Replacing members with other members
  • reporting bugs
  • Resurrecting files from an archive
  • Retrieving files from an archive
  • return status
  • rmt
  • Running out of space
  • Running out of space during extraction

    • s

  • Salz, Rich
  • SIMPLE_BACKUP_SUFFIX
  • Small memory
  • Space on the disk, recovering from lack of
  • Sparse Files
  • Specifying archive members
  • Specifying files to act on
  • Standard input and output
  • Standard output, writing extracted files to
  • Status information
  • Storing archives in compressed format
  • Swedish Winter Time
  • Symbolic link as file name

    • t

  • tape blocking
  • tape marks
  • tape positioning
  • Tapes, using --delete and
  • tar
  • tar archive
  • tar entry
  • tar file
  • tar to standard input and output
  • this in date strings
  • time of day item
  • timezone correction
  • timezone item
  • today in date strings
  • tomorrow in date strings

    • u

  • Ultrix 3.1 and write failure
  • Universal Coordinated Time
  • unpacking
  • Updating an archive
  • USSR Zone
  • uuencode

    • v

  • Verbose operation
  • Verifying a write operation
  • Verifying the currency of an archive
  • Version of the tar program
  • version-control Emacs variable
  • VERSION_CONTROL

    • w

  • week in date strings
  • West African Time
  • West Australian Standard Time
  • Western European Time
  • Where is the archive?
  • Working directory, specifying
  • Writing extracted files to standard output
  • Writing new archives

    • y

  • year in date strings
  • yesterday in date strings
  • Yukon Standard Time

    • Footnotes

    (1)

    Clustering many options, the last of which has an argument, is a rather opaque way to write options. Some wonder if GNU getopt should not even be made helpful enough for considering such usages as invalid.

    (2)

    Beware that if you precede options with a dash, you are announcing the short option style instead of the old option style; short options are decoded differently.

    (3)

    Before GNU tar version 1.11.6, a bug prevented intermixing old style options with mnemonic options in some cases.

    (4)

    There are plans to merge the cpio and tar packages into a single one which would be called paxutils. So, who knows if, one of this days, the --version would not yield `tar (GNU paxutils) 3.2'

    (5)

    This is well described in Unix-haters Handbook, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG Books, ISBN 1-56884-203-1.

    (6)

    Well! We should say the whole truth, here. When --sparse (-S) is selected while creating an archive, the current tar algorithm requires sparse files to be read twice, not once. We hope to develop a new archive format for saving sparse files in which one pass will be sufficient.

    (7)

    Previous versions of tar used full regular expression matching, or before that, only exact string matching, instead of wildcard matchers. We decided for the sake of simplicity to use a uniform matching device through tar.

    This document was generated on 7 November 1998 using the texi2html translator version 1.52.


The Termcap Library

The Termcap Manual

The Termcap Library and Data Base

Second Edition

December 1992

Richard M. Stallman

Table of Contents

  • Introduction
  • The Termcap Library
    • Preparing to Use the Termcap Library
    • Finding a Terminal Description: tgetent
    • Interrogating the Terminal Description
    • Initialization for Use of Termcap
    • Padding
      • Why Pad, and How
      • When There Is Not Enough Padding
      • Specifying Padding in a Terminal Description
      • Performing Padding with tputs
    • Filling In Parameters
      • Describing the Encoding
      • Sending Display Commands with Parameters
        • tparam
        • tgoto
  • The Format of the Data Base
    • Terminal Description Format
    • Writing the Capabilities
    • Terminal Type Name Conventions
    • Inheriting from Related Descriptions
    • When Changes in the Data Base Take Effect
  • Definitions of the Terminal Capabilities
    • Basic Characteristics
    • Screen Size
    • Cursor Motion
    • Wrapping
    • Scrolling
    • Windows
    • Clearing Parts of the Screen
    • Insert/Delete Line
    • Insert/Delete Character
    • Standout and Appearance Modes
    • Underlining
    • Cursor Visibility
    • Bell
    • Keypad and Function Keys
    • Meta Key
    • Initialization
    • Padding Capabilities
    • Status Line
    • Half-Line Motion
    • Controlling Printers Attached to Terminals
  • Summary of Capability Names
  • Variable and Function Index
  • Capability Index
  • Concept Index

Introduction

Termcap is a library and data base that enables programs to use display terminals in a terminal-independent manner. It originated in Berkeley Unix.

The termcap data base describes the capabilities of hundreds of different display terminals in great detail. Some examples of the information recorded for a terminal could include how many columns wide it is, what string to send to move the cursor to an arbitrary position (including how to encode the row and column numbers), how to scroll the screen up one or several lines, and how much padding is needed for such a scrolling operation.

The termcap library is provided for easy access this data base in programs that want to do terminal-independent character-based display output.

This manual describes the GNU version of the termcap library, which has some extensions over the Unix version. All the extensions are identified as such, so this manual also tells you how to use the Unix termcap.

The GNU version of the termcap library is available free as source code, for use in free programs, and runs on Unix and VMS systems (at least). You can find it in the GNU Emacs distribution in the files `termcap.c' and `tparam.c'.

This manual was written for the GNU project, whose goal is to develop a complete free operating system upward-compatible with Unix for user programs. The project is approximately two thirds complete. For more information on the GNU project, including the GNU Emacs editor and the mostly-portable optimizing C compiler, send one dollar to

Free Software Foundation
675 Mass Ave
Cambridge, MA 02139

The Termcap Library

The termcap library is the application programmer's interface to the termcap data base. It contains functions for the following purposes:

  • Finding the description of the user's terminal type (tgetent).
  • Interrogating the description for information on various topics (tgetnum, tgetflag, tgetstr).
  • Computing and performing padding (tputs).
  • Encoding numeric parameters such as cursor positions into the terminal-specific form required for display commands (tparam, tgoto).

Preparing to Use the Termcap Library

To use the termcap library in a program, you need two kinds of preparation:

  • The compiler needs declarations of the functions and variables in the library. On GNU systems, it suffices to include the header file `termcap.h' in each source file that uses these functions and variables. On Unix systems, there is often no such header file. Then you must explictly declare the variables as external. You can do likewise for the functions, or let them be implicitly declared and cast their values from type int to the appropriate type. We illustrate the declarations of the individual termcap library functions with ANSI C prototypes because they show how to pass the arguments. If you are not using the GNU C compiler, you probably cannot use function prototypes, so omit the argument types and names from your declarations.
  • The linker needs to search the library. Usually either `-ltermcap' or `-ltermlib' as an argument when linking will do this.

Finding a Terminal Description: tgetent

An application program that is going to use termcap must first look up the description of the terminal type in use. This is done by calling tgetent, whose declaration in ANSI Standard C looks like:

int tgetent (char *buffer, char *termtype);

This function finds the description and remembers it internally so that you can interrogate it about specific terminal capabilities (see section Interrogating the Terminal Description).

The argument termtype is a string which is the name for the type of terminal to look up. Usually you would obtain this from the environment variable TERM using getenv ("TERM").

If you are using the GNU version of termcap, you can alternatively ask tgetent to allocate enough space. Pass a null pointer for buffer, and tgetent itself allocates the storage using malloc. There is no way to get the address that was allocated, and you shouldn't try to free the storage.

With the Unix version of termcap, you must allocate space for the description yourself and pass the address of the space as the argument buffer. There is no way you can tell how much space is needed, so the convention is to allocate a buffer 2048 characters long and assume that is enough. (Formerly the convention was to allocate 1024 characters and assume that was enough. But one day, for one kind of terminal, that was not enough.)

No matter how the space to store the description has been obtained, termcap records its address internally for use when you later interrogate the description with tgetnum, tgetstr or tgetflag. If the buffer was allocated by termcap, it will be freed by termcap too if you call tgetent again. If the buffer was provided by you, you must make sure that its contents remain unchanged for as long as you still plan to interrogate the description.

The return value of tgetent is -1 if there is some difficulty accessing the data base of terminal types, 0 if the data base is accessible but the specified type is not defined in it, and some other value otherwise.

Here is how you might use the function tgetent:

#ifdef unix
static char term_buffer[2048];
#else
#define term_buffer 0
#endif

init_terminal_data ()
{
  char *termtype = getenv ("TERM");
  int success;

  if (termtype == 0)
    fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");

  success = tgetent (term_buffer, termtype);
  if (success < 0)
    fatal ("Could not access the termcap data base.\n");
  if (success == 0)
    fatal ("Terminal type `%s' is not defined.\n", termtype);
}

Here we assume the function fatal prints an error message and exits.

If the environment variable TERMCAP is defined, its value is used to override the terminal type data base. The function tgetent checks the value of TERMCAP automatically. If the value starts with `/' then it is taken as a file name to use as the data base file, instead of `/etc/termcap' which is the standard data base. If the value does not start with `/' then it is itself used as the terminal description, provided that the terminal type termtype is among the types it claims to apply to. See section The Format of the Data Base, for information on the format of a terminal description.

Interrogating the Terminal Description

Each piece of information recorded in a terminal description is called a capability. Each defined terminal capability has a two-letter code name and a specific meaning. For example, the number of columns is named `co'. See section Definitions of the Terminal Capabilities, for definitions of all the standard capability names.

Once you have found the proper terminal description with tgetent (see section Finding a Terminal Description: tgetent), your application program must interrogate it for various terminal capabilities. You must specify the two-letter code of the capability whose value you seek.

Capability values can be numeric, boolean (capability is either present or absent) or strings. Any particular capability always has the same value type; for example, `co' always has a numeric value, while `am' (automatic wrap at margin) is always a flag, and `cm' (cursor motion command) always has a string value. The documentation of each capability says which type of value it has.

There are three functions to use to get the value of a capability, depending on the type of value the capability has. Here are their declarations in ANSI C:

int tgetnum (char *name);
int tgetflag (char *name);
char *tgetstr (char *name, char **area);
tgetnum
Use tgetnum to get a capability value that is numeric. The argument name is the two-letter code name of the capability. If the capability is present, tgetnum returns the numeric value (which is nonnegative). If the capability is not mentioned in the terminal description, tgetnum returns -1.
tgetflag
Use tgetflag to get a boolean value. If the capability name is present in the terminal description, tgetflag returns 1; otherwise, it returns 0.
tgetstr
Use tgetstr to get a string value. It returns a pointer to a string which is the capability value, or a null pointer if the capability is not present in the terminal description. There are two ways tgetstr can find space to store the string value:
  • You can ask tgetstr to allocate the space. Pass a null pointer for the argument area, and tgetstr will use malloc to allocate storage big enough for the value. Termcap will never free this storage or refer to it again; you should free it when you are finished with it. This method is more robust, since there is no need to guess how much space is needed. But it is supported only by the GNU termcap library.
  • You can provide the space. Provide for the argument area the address of a pointer variable of type char *. Before calling tgetstr, initialize the variable to point at available space. Then tgetstr will store the string value in that space and will increment the pointer variable to point after the space that has been used. You can use the same pointer variable for many calls to tgetstr. There is no way to determine how much space is needed for a single string, and no way for you to prevent or handle overflow of the area you have provided. However, you can be sure that the total size of all the string values you will obtain from the terminal description is no greater than the size of the description (unless you get the same capability twice). You can determine that size with strlen on the buffer you provided to tgetent. See below for an example. Providing the space yourself is the only method supported by the Unix version of termcap.

Note that you do not have to specify a terminal type or terminal description for the interrogation functions. They automatically use the description found by the most recent call to tgetent.

Here is an example of interrogating a terminal description for various capabilities, with conditionals to select between the Unix and GNU methods of providing buffer space.

char *tgetstr ();

char *cl_string, *cm_string;
int height;
int width;
int auto_wrap;

char PC;   /* For tputs.  */
char *BC;  /* For tgoto.  */
char *UP;

interrogate_terminal ()
{
#ifdef UNIX
  /* Here we assume that an explicit term_buffer
     was provided to tgetent.  */
  char *buffer
    = (char *) malloc (strlen (term_buffer));
#define BUFFADDR &buffer
#else
#define BUFFADDR 0
#endif

  char *temp;

  /* Extract information we will use.  */
  cl_string = tgetstr ("cl", BUFFADDR);
  cm_string = tgetstr ("cm", BUFFADDR);
  auto_wrap = tgetflag ("am");
  height = tgetnum ("li");
  width = tgetnum ("co");

  /* Extract information that termcap functions use.  */
  temp = tgetstr ("pc", BUFFADDR);
  PC = temp ? *temp : 0;
  BC = tgetstr ("le", BUFFADDR);
  UP = tgetstr ("up", BUFFADDR);
}

See section Padding, for information on the variable PC. See section Sending Display Commands with Parameters, for information on UP and BC.

Initialization for Use of Termcap

Before starting to output commands to a terminal using termcap, an application program should do two things:

  • Initialize various global variables which termcap library output functions refer to. These include PC and ospeed for padding (see section Performing Padding with tputs) and UP and BC for cursor motion (see section tgoto).
  • Tell the kernel to turn off alteration and padding of horizontal-tab characters sent to the terminal.

To turn off output processing in Berkeley Unix you would use ioctl with code TIOCLSET to set the bit named LLITOUT, and clear the bits ANYDELAY using TIOCSETN. In POSIX or System V, you must clear the bit named OPOST. Refer to the system documentation for details.

If you do not set the terminal flags properly, some older terminals will not work. This is because their commands may contain the characters that normally signify newline, carriage return and horizontal tab--characters which the kernel thinks it ought to modify before output.

When you change the kernel's terminal flags, you must arrange to restore them to their normal state when your program exits. This implies that the program must catch fatal signals such as SIGQUIT and SIGINT and restore the old terminal flags before actually terminating.

Modern terminals' commands do not use these special characters, so if you do not care about problems with old terminals, you can leave the kernel's terminal flags unaltered.

Padding

Padding means outputting null characters following a terminal display command that takes a long time to execute. The terminal description says which commands require padding and how much; the function tputs, described below, outputs a terminal command while extracting from it the padding information, and then outputs the padding that is necessary.

Why Pad, and How

Most types of terminal have commands that take longer to execute than they do to send over a high-speed line. For example, clearing the screen may take 20msec once the entire command is received. During that time, on a 9600 bps line, the terminal could receive about 20 additional output characters while still busy clearing the screen. Every terminal has a certain amount of buffering capacity to remember output characters that cannot be processed yet, but too many slow commands in a row can cause the buffer to fill up. Then any additional output that cannot be processed immediately will be lost.

To avoid this problem, we normally follow each display command with enough useless charaters (usually null characters) to fill up the time that the display command needs to execute. This does the job if the terminal throws away null characters without using up space in the buffer (which most terminals do). If enough padding is used, no output can ever be lost. The right amount of padding avoids loss of output without slowing down operation, since the time used to transmit padding is time that nothing else could be done.

The number of padding characters needed for an operation depends on the line speed. In fact, it is proportional to the line speed. A 9600 baud line transmits about one character per msec, so the clear screen command in the example above would need about 20 characters of padding. At 1200 baud, however, only about 3 characters of padding are needed to fill up 20msec.

When There Is Not Enough Padding

There are several common manifestations of insufficient padding.

  • Emacs displays `I-search: ^Q-' at the bottom of the screen. This means that the terminal thought its buffer was getting full of display commands, so it tried to tell the computer to stop sending any.
  • The screen is garbled intermittently, or the details of garbling vary when you repeat the action. (A garbled screen could be due to a command which is simply incorrect, or to user option in the terminal which doesn't match the assumptions of the terminal description, but this usually leads to reproducible failure.) This means that the buffer did get full, and some commands were lost. Many changeable factors can change which ones are lost.
  • Screen is garbled at high output speeds but not at low speeds. Padding problems nearly always go away at low speeds, usually even at 1200 baud. This means that a high enough speed permits commands to arrive faster than they can be executed.

Although any obscure command on an obscure terminal might lack padding, in practice problems arise most often from the clearing commands `cl' and `cd' (see section Clearing Parts of the Screen), the scrolling commands `sf' and `sr' (see section Scrolling), and the line insert/delete commands `al' and `dl' (see section Insert/Delete Line).

Occasionally the terminal description fails to define `sf' and some programs will use `do' instead, so you may get a problem with `do'. If so, first define `sf' just like `do', then add some padding to `sf'.

The best strategy is to add a lot of padding at first, perhaps 200 msec. This is much more than enough; in fact, it should cause a visible slowdown. (If you don't see a slowdown, the change has not taken effect; see section When Changes in the Data Base Take Effect.) If this makes the problem go away, you have found the right place to add padding; now reduce the amount until the problem comes back, then increase it again. If the problem remains, either it is in some other capability or it is not a matter of padding at all.

Keep in mind that on many terminals the correct padding for insert/delete line or for scrolling is cursor-position dependent. If you get problems from scrolling a large region of the screen but not from scrolling a small part (just a few lines moving), it may mean that fixed padding should be replaced with position-dependent padding.

Specifying Padding in a Terminal Description

In the terminal description, the amount of padding required by each display command is recorded as a sequence of digits at the front of the command. These digits specify the padding time in milliseconds (msec). They can be followed optionally by a decimal point and one more digit, which is a number of tenths of msec.

Sometimes the padding needed by a command depends on the cursor position. For example, the time taken by an "insert line" command is usually proportional to the number of lines that need to be moved down or cleared. An asterisk (`*') following the padding time says that the time should be multiplied by the number of screen lines affected by the command.

:al=1.3*\E[L:

is used to describe the "insert line" command for a certain terminal. The padding required is 1.3 msec per line affected. The command itself is `ESC [ L'.

The padding time specified in this way tells tputs how many pad characters to output. See section Performing Padding with tputs.

Two special capability values affect padding for all commands. These are the `pc' and `pb'. The variable `pc' specifies the character to pad with, and `pb' the speed below which no padding is needed. The defaults for these variables, a null character and 0, are correct for most terminals. See section Padding Capabilities.

Performing Padding with tputs

Use the termcap function tputs to output a string containing an optional padding spec of the form described above (see section Specifying Padding in a Terminal Description). The function tputs strips off and decodes the padding spec, outputs the rest of the string, and then outputs the appropriate padding. Here is its declaration in ANSI C:

char PC;
short ospeed;

int tputs (char *string, int nlines, int (*outfun) ());

Here string is the string (including padding spec) to be output; nlines is the number of lines affected by the operation, which is used to multiply the amount of padding if the padding spec ends with a `*'. Finally, outfun is a function (such as fputchar) that is called to output each character. When actually called, outfun should expect one argument, a character.

The operation of tputs is controlled by two global variables, ospeed and PC. The value of ospeed is supposed to be the terminal output speed, encoded as in the ioctl system call which gets the speed information. This is needed to compute the number of padding characters. The value of PC is the character used for padding.

You are responsible for storing suitable values into these variables before using tputs. The value stored into the PC variable should be taken from the `pc' capability in the terminal description (see section Padding Capabilities). Store zero in PC if there is no `pc' capability.

The argument nlines requires some thought. Normally, it should be the number of lines whose contents will be cleared or moved by the command. For cursor motion commands, or commands that do editing within one line, use the value 1. For most commands that affect multiple lines, such as `al' (insert a line) and `cd' (clear from the cursor to the end of the screen), nlines should be the screen height minus the current vertical position (origin 0). For multiple insert and scroll commands such as `AL' (insert multiple lines), that same value for nlines is correct; the number of lines being inserted is not correct.

If a "scroll window" feature is used to reduce the number of lines affected by a command, the value of nlines should take this into account. This is because the delay time required depends on how much work the terminal has to do, and the scroll window feature reduces the work. See section Scrolling.

Commands such as `ic' and `dc' (insert or delete characters) are problematical because the padding needed by these commands is proportional to the number of characters affected, which is the number of columns from the cursor to the end of the line. It would be nice to have a way to specify such a dependence, and there is no need for dependence on vertical position in these commands, so it is an obvious idea to say that for these commands nlines should really be the number of columns affected. However, the definition of termcap clearly says that nlines is always the number of lines affected, even in this case, where it is always 1. It is not easy to change this rule now, because too many programs and terminal descriptions have been written to follow it.

Because nlines is always 1 for the `ic' and `dc' strings, there is no reason for them to use `*', but some of them do. These should be corrected by deleting the `*'. If, some day, such entries have disappeared, it may be possible to change to a more useful convention for the nlines argument for these operations without breaking any programs.

Filling In Parameters

Some terminal control strings require numeric parameters. For example, when you move the cursor, you need to say what horizontal and vertical positions to move it to. The value of the terminal's `cm' capability, which says how to move the cursor, cannot simply be a string of characters; it must say how to express the cursor position numbers and where to put them within the command.

The specifications of termcap include conventions as to which string-valued capabilities require parameters, how many parameters, and what the parameters mean; for example, it defines the `cm' string to take two parameters, the vertical and horizontal positions, with 0,0 being the upper left corner. These conventions are described where the individual commands are documented.

Termcap also defines a language used within the capability definition for specifying how and where to encode the parameters for output. This language uses character sequences starting with `%'. (This is the same idea as printf, but the details are different.) The language for parameter encoding is described in this section.

A program that is doing display output calls the functions tparam or tgoto to encode parameters according to the specifications. These functions produce a string containing the actual commands to be output (as well a padding spec which must be processed with tputs; see section Padding).

Describing the Encoding

A terminal command string that requires parameters contains special character sequences starting with `%' to say how to encode the parameters. These sequences control the actions of tparam and tgoto.

The parameters values passed to tparam or tgoto are considered to form a vector. A pointer into this vector determines the next parameter to be processed. Some of the `%'-sequences encode one parameter and advance the pointer to the next parameter. Other `%'-sequences alter the pointer or alter the parameter values without generating output.

For example, the `cm' string for a standard ANSI terminal is written as `\E[%i%d;%dH'. (`\E' stands for ESC.) `cm' by convention always requires two parameters, the vertical and horizontal goal positions, so this string specifies the encoding of two parameters. Here `%i' increments the two values supplied, and each `%d' encodes one of the values in decimal. If the cursor position values 20,58 are encoded with this string, the result is `\E[21;59H'.

First, here are the `%'-sequences that generate output. Except for `%%', each of them encodes one parameter and advances the pointer to the following parameter.

`%%'
Output a single `%'. This is the only way to represent a literal `%' in a terminal command with parameters. `%%' does not use up a parameter.
`%d'
As in printf, output the next parameter in decimal.
`%2'
Like `%02d' in printf: output the next parameter in decimal, and always use at least two digits.
`%3'
Like `%03d' in printf: output the next parameter in decimal, and always use at least three digits. Note that `%4' and so on are not defined.
`%.'
Output the next parameter as a single character whose ASCII code is the parameter value. Like `%c' in printf.
`%+char'
Add the next parameter to the character char, and output the resulting character. For example, `%+ ' represents 0 as a space, 1 as `!', etc.

The following `%'-sequences specify alteration of the parameters (their values, or their order) rather than encoding a parameter for output. They generate no output; they are used only for their side effects on the parameters. Also, they do not advance the "next parameter" pointer except as explicitly stated. Only `%i', `%r' and `%>' are defined in standard Unix termcap. The others are GNU extensions.

`%i'
Increment the next two parameters. This is used for terminals that expect cursor positions in origin 1. For example, `%i%d,%d' would output two parameters with `1' for 0, `2' for 1, etc.
`%r'
Interchange the next two parameters. This is used for terminals whose cursor positioning command expects the horizontal position first.
`%s'
Skip the next parameter. Do not output anything.
`%b'
Back up one parameter. The last parameter used will become once again the next parameter to be output, and the next output command will use it. Using `%b' more than once, you can back up any number of parameters, and you can refer to each parameter any number of times.
`%>c1c2'
Conditionally increment the next parameter. Here c1 and c2 are characters which stand for their ASCII codes as numbers. If the next parameter is greater than the ASCII code of c1, the ASCII code of c2 is added to it.
`%a op type pos'
Perform arithmetic on the next parameter, do not use it up, and do not output anything. Here op specifies the arithmetic operation, while type and pos together specify the other operand. Spaces are used above to separate the operands for clarity; the spaces don't appear in the data base, where this sequence is exactly five characters long. The character op says what kind of arithmetic operation to perform. It can be any of these characters:
`='
assign a value to the next parameter, ignoring its old value. The new value comes from the other operand.
`+'
add the other operand to the next parameter.
`-'
subtract the other operand from the next parameter.
`*'
multiply the next parameter by the other operand.
`/'
divide the next parameter by the other operand.
The "other operand" may be another parameter's value or a constant; the character type says which. It can be:
`p'
Use another parameter. The character pos says which parameter to use. Subtract 64 from its ASCII code to get the position of the desired parameter relative to this one. Thus, the character `A' as pos means the parameter after the next one; the character `?' means the parameter before the next one.
`c'
Use a constant value. The character pos specifies the value of the constant. The 0200 bit is cleared out, so that 0200 can be used to represent zero.

The following `%'-sequences are special purpose hacks to compensate for the weird designs of obscure terminals. They modify the next parameter or the next two parameters but do not generate output and do not use up any parameters. `%m' is a GNU extension; the others are defined in standard Unix termcap.

`%n'
Exclusive-or the next parameter with 0140, and likewise the parameter after next.
`%m'
Complement all the bits of the next parameter and the parameter after next.
`%B'
Encode the next parameter in BCD. It alters the value of the parameter by adding six times the quotient of the parameter by ten. Here is a C statement that shows how the new value is computed:
parm = (parm / 10) * 16 + parm % 10;
`%D'
Transform the next parameter as needed by Delta Data terminals. This involves subtracting twice the remainder of the parameter by 16.
parm -= 2 * (parm % 16);

Sending Display Commands with Parameters

The termcap library functions tparam and tgoto serve as the analog of printf for terminal string parameters. The newer function tparam is a GNU extension, more general but missing from Unix termcap. The original parameter-encoding function is tgoto, which is preferable for cursor motion.

tparam

The function tparam can encode display commands with any number of parameters and allows you to specify the buffer space. It is the preferred function for encoding parameters for all but the `cm' capability. Its ANSI C declaration is as follows:

char *tparam (char *ctlstring, char *buffer, int size, int parm1,...)

The arguments are a control string ctlstring (the value of a terminal capability, presumably), an output buffer buffer and size, and any number of integer parameters to be encoded. The effect of tparam is to copy the control string into the buffer, encoding parameters according to the `%' sequences in the control string.

You describe the output buffer by its address, buffer, and its size in bytes, size. If the buffer is not big enough for the data to be stored in it, tparam calls malloc to get a larger buffer. In either case, tparam returns the address of the buffer it ultimately uses. If the value equals buffer, your original buffer was used. Otherwise, a new buffer was allocated, and you must free it after you are done with printing the results. If you pass zero for size and buffer, tparam always allocates the space with malloc.

All capabilities that require parameters also have the ability to specify padding, so you should use tputs to output the string produced by tparam. See section Padding. Here is an example.

{
char *buf;
char buffer[40];

buf = tparam (command, buffer, 40, parm);
tputs (buf, 1, fputchar);
if (buf != buffer)
free (buf);
}

If a parameter whose value is zero is encoded with `%.'-style encoding, the result is a null character, which will confuse tputs. This would be a serious problem, but luckily `%.' encoding is used only by a few old models of terminal, and only for the `cm' capability. To solve the problem, use tgoto rather than tparam to encode the `cm' capability.

tgoto

The special case of cursor motion is handled by tgoto. There are two reasons why you might choose to use tgoto:

  • For Unix compatibility, because Unix termcap does not have tparam.
  • For the `cm' capability, since tgoto has a special feature to avoid problems with null characters, tabs and newlines on certain old terminal types that use `%.' encoding for that capability.

Here is how tgoto might be declared in ANSI C:

char *tgoto (char *cstring, int hpos, int vpos)

There are three arguments, the terminal description's `cm' string and the two cursor position numbers; tgoto computes the parametrized string in an internal static buffer and returns the address of that buffer. The next time you use tgoto the same buffer will be reused.

Parameters encoded with `%.' encoding can generate null characters, tabs or newlines. These might cause trouble: the null character because tputs would think that was the end of the string, the tab because the kernel or other software might expand it into spaces, and the newline becaue the kernel might add a carriage-return, or padding characters normally used for a newline. To prevent such problems, tgoto is careful to avoid these characters. Here is how this works: if the target cursor position value is such as to cause a problem (that is to say, zero, nine or ten), tgoto increments it by one, then compensates by appending a string to move the cursor back or up one position.

The compensation strings to use for moving back or up are found in global variables named BC and UP. These are actual external C variables with upper case names; they are declared char *. It is up to you to store suitable values in them, normally obtained from the `le' and `up' terminal capabilities in the terminal description with tgetstr. Alternatively, if these two variables are both zero, the feature of avoiding nulls, tabs and newlines is turned off.

It is safe to use tgoto for commands other than `cm' only if you have stored zero in BC and UP.

Note that tgoto reverses the order of its operands: the horizontal position comes before the vertical position in the arguments to tgoto, even though the vertical position comes before the horizontal in the parameters of the `cm' string. If you use tgoto with a command such as `AL' that takes one parameter, you must pass the parameter to tgoto as the "vertical position".

The Format of the Data Base

The termcap data base of terminal descriptions is stored in the file `/etc/termcap'. It contains terminal descriptions, blank lines, and comments.

A terminal description starts with one or more names for the terminal type. The information in the description is a series of capability names and values. The capability names have standard meanings (see section Definitions of the Terminal Capabilities) and their values describe the terminal.

Terminal Description Format

Aside from comments (lines starting with `#', which are ignored), each nonblank line in the termcap data base is a terminal description. A terminal description is nominally a single line, but it can be split into multiple lines by inserting the two characters `\ newline'. This sequence is ignored wherever it appears in a description.

The preferred way to split the description is between capabilities: insert the four characters `: \ newline tab' immediately before any colon. This allows each sub-line to start with some indentation. This works because, after the `\ newline' are ignored, the result is `: tab :'; the first colon ends the preceding capability and the second colon starts the next capability. If you split with `\ newline' alone, you may not add any indentation after them.

Here is a real example of a terminal description:

dw|vt52|DEC vt52:\
        :cr=^M:do=^J:nl=^J:bl=^G:\
        :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\
        :cm=\EY%+ %+ :co#80:li#24:\
        :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:

Each terminal description begins with several names for the terminal type. The names are separated by `|' characters, and a colon ends the last name. The first name should be two characters long; it exists only for the sake of very old Unix systems and is never used in modern systems. The last name should be a fully verbose name such as "DEC vt52" or "Ann Arbor Ambassador with 48 lines". The other names should include whatever the user ought to be able to specify to get this terminal type, such as `vt52' or `aaa-48'. See section Terminal Type Name Conventions, for information on how to choose terminal type names.

After the terminal type names come the terminal capabilities, separated by colons and with a colon after the last one. Each capability has a two-letter name, such as `cm' for "cursor motion string" or `li' for "number of display lines".

Writing the Capabilities

There are three kinds of capabilities: flags, numbers, and strings. Each kind has its own way of being written in the description. Each defined capability has by convention a particular kind of value; for example, `li' always has a numeric value and `cm' always a string value.

A flag capability is thought of as having a boolean value: the value is true if the capability is present, false if not. When the capability is present, just write its name between two colons.

A numeric capability has a value which is a nonnegative number. Write the capability name, a `#', and the number, between two colons. For example, `...:li#48:...' is how you specify the `li' capability for 48 lines.

A string-valued capability has a value which is a sequence of characters. Usually these are the characters used to perform some display operation. Write the capability name, a `=', and the characters of the value, between two colons. For example, `...:cm=\E[%i%d;%dH:...' is how the cursor motion command for a standard ANSI terminal would be specified.

Special characters in the string value can be expressed using `\'-escape sequences as in C; in addition, `\E' stands for ESC. `^' is also a kind of escape character; `^' followed by char stands for the control-equivalent of char. Thus, `^a' stands for the character control-a, just like `\001'. `\' and `^' themselves can be represented as `\\' and `\^'.

To include a colon in the string, you must write `\072'. You might ask, "Why can't `\:' be used to represent a colon?" The reason is that the interrogation functions do not count slashes while looking for a capability. Even if `:ce=ab\:cd:' were interpreted as giving the `ce' capability the value `ab:cd', it would also appear to define `cd' as a flag.

The string value will often contain digits at the front to specify padding (see section Padding) and/or `%'-sequences within to specify how to encode parameters (see section Filling In Parameters). Although these things are not to be output literally to the terminal, they are considered part of the value of the capability. They are special only when the string value is processed by tputs, tparam or tgoto. By contrast, `\' and `^' are considered part of the syntax for specifying the characters in the string.

Let's look at the VT52 example again:

dw|vt52|DEC vt52:\
        :cr=^M:do=^J:nl=^J:bl=^G:\
        :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\
        :cm=\EY%+ %+ :co#80:li#24:\
        :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:

Here we see the numeric-valued capabilities `co' and `li', the flags `bs' and `pt', and many string-valued capabilities. Most of the strings start with ESC represented as `\E'. The rest contain control characters represented using `^'. The meanings of the individual capabilities are defined elsewhere (see section Definitions of the Terminal Capabilities).

Terminal Type Name Conventions

There are conventions for choosing names of terminal types. For one thing, all letters should be in lower case. The terminal type for a terminal in its most usual or most fundamental mode of operation should not have a hyphen in it.

If the same terminal has other modes of operation which require different terminal descriptions, these variant descriptions are given names made by adding suffixes with hyphens. Such alternate descriptions are used for two reasons:

  • When the terminal has a switch that changes its behavior. Since the computer cannot tell how the switch is set, the user must tell the computer by choosing the appropriate terminal type name. For example, the VT-100 has a setup flag that controls whether the cursor wraps at the right margin. If this flag is set to "wrap", you must use the terminal type `vt100-am'. Otherwise you must use `vt100-nam'. Plain `vt100' is defined as a synonym for either `vt100-am' or `vt100-nam' depending on the preferences of the local site. The standard suffix `-am' stands for "automatic margins".
  • To give the user a choice in how to use the terminal. This is done when the terminal has a switch that the computer normally controls. For example, the Ann Arbor Ambassador can be configured with many screen sizes ranging from 20 to 60 lines. Fewer lines make bigger characters but more lines let you see more of what you are editing. As a result, users have different preferences. Therefore, termcap provides terminal types for many screen sizes. If you choose type `aaa-30', the terminal will be configured to use 30 lines; if you choose `aaa-48', 48 lines will be used, and so on.

Here is a list of standard suffixes and their conventional meanings:

`-w'
Short for "wide". This is a mode that gives the terminal more columns than usual. This is normally a user option.
`-am'
"Automatic margins". This is an alternate description for use when the terminal's margin-wrap switch is on; it contains the `am' flag. The implication is that normally the switch is off and the usual description for the terminal says that the switch is off.
`-nam'
"No automatic margins". The opposite of `-am', this names an alternative description which lacks the `am' flag. This implies that the terminal is normally operated with the margin-wrap switch turned on, and the normal description of the terminal says so.
`-na'
"No arrows". This terminal description initializes the terminal to keep its arrow keys in local mode. This is a user option.
`-rv'
"Reverse video". This terminal description causes text output for normal video to appear as reverse, and text output for reverse video to come out as normal. Often this description differs from the usual one by interchanging the two strings which turn reverse video on and off. This is a user option; you can choose either the "reverse video" variant terminal type or the normal terminal type, and termcap will obey.
`-s'
"Status". Says to enable use of a status line which ordinary output does not touch (see section Status Line). Some terminals have a special line that is used only as a status line. For these terminals, there is no need for an `-s' variant; the status line commands should be defined by default. On other terminals, enabling a status line means removing one screen line from ordinary use and reducing the effective screen height. For these terminals, the user can choose the `-s' variant type to request use of a status line.
`-nlines'
Says to operate with nlines lines on the screen, for terminals such as the Ambassador which provide this as an option. Normally this is a user option; by choosing the terminal type, you control how many lines termcap will use.
`-npagesp'
Says that the terminal has npages pages worth of screen memory, for terminals where this is a hardware option.
`-unk'
Says that description is not for direct use, but only for reference in `tc' capabilities. Such a description is a kind of subroutine, because it describes the common characteristics of several variant descriptions that would use other suffixes in place of `-unk'.

Inheriting from Related Descriptions

When two terminal descriptions are similar, their identical parts do not need to be given twice. Instead, one of the two can be defined in terms of the other, using the `tc' capability. We say that one description refers to the other, or inherits from the other.

The `tc' capability must be the last one in the terminal description, and its value is a string which is the name of another terminal type which is referred to. For example,

N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
        :ti=\E[2J\E[30;0;0;30p:\
        :te=\E[60;0;0;30p\E[30;1H\E[J:\
        :li#30:tc=aaa-unk:

defines the terminal type `aaa-30' (also known as plain `aaa') in terms of `aaa-unk', which defines everything about the Ambassador that is independent of screen height. The types `aaa-36', `aaa-48' and so on for other screen heights are likewise defined to inherit from `aaa-unk'.

The capabilities overridden by `aaa-30' include `li', which says how many lines there are, and `ti' and `te', which configure the terminal to use that many lines.

The effective terminal description for type `aaa' consists of the text shown above followed by the text of the description of `aaa-unk'. The `tc' capability is handled automatically by tgetent, which finds the description thus referenced and combines the two descriptions (see section Finding a Terminal Description: tgetent). Therefore, only the implementor of the terminal descriptions needs to think about using `tc'. Users and application programmers do not need to be concerned with it.

Since the reference terminal description is used last, capabilities specified in the referring description override any specifications of the same capabilities in the reference description.

The referring description can cancel out a capability without specifying any new value for it by means of a special trick. Write the capability in the referring description, with the character `@' after the capability name, as follows:

NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
        :am@:tc=aaa-30:

When Changes in the Data Base Take Effect

Each application program must read the terminal description from the data base, so a change in the data base is effective for all jobs started after the change is made.

The change will usually have no effect on a job that have been in existence since before the change. The program probably read the terminal description once, when it was started, and is continuing to use what it read then. If the program does not have a feature for reexamining the data base, then you will need to run it again (probably killing the old job).

If the description in use is coming from the TERMCAP environment variable, then the data base file is effectively overridden, and changes in it will have no effect until you change the TERMCAP variable as well. For example, some users' `.login' files automatically copy the terminal description into TERMCAP to speed startup of applications. If you have done this, you will need to change the TERMCAP variable to make the changed data base take effect.

Definitions of the Terminal Capabilities

This section is divided into many subsections, each for one aspect of use of display terminals. For writing a display program, you usually need only check the subsections for the operations you want to use. For writing a terminal description, you must read each subsection and fill in the capabilities described there.

String capabilities that are display commands may require numeric parameters (see section Filling In Parameters). Most such capabilities do not use parameters. When a capability requires parameters, this is explicitly stated at the beginning of its definition. In simple cases, the first or second sentence of the definition mentions all the parameters, in the order they should be given, using a name in italics for each one. For example, the `rp' capability is a command that requires two parameters; its definition begins as follows:

String of commands to output a graphic character c, repeated n times.

In complex cases or when there are many parameters, they are described explicitly.

When a capability is described as obsolete, this means that programs should not be written to look for it, but terminal descriptions should still be written to provide it.

When a capability is described as very obsolete, this means that it should be omitted from terminal descriptions as well.

Basic Characteristics

This section documents the capabilities that describe the basic and nature of the terminal, and also those that are relevant to the output of graphic characters.

`os'
Flag whose presence means that the terminal can overstrike. This means that outputting a graphic character does not erase whatever was present in the same character position before. The terminals that can overstrike include printing terminals, storage tubes (all obsolete nowadays), and many bit-map displays.
`eo'
Flag whose presence means that outputting a space erases a character position even if the terminal supports overstriking. If this flag is not present and overstriking is supported, output of a space has no effect except to move the cursor. (On terminals that do not support overstriking, you can always assume that outputting a space at a position erases whatever character was previously displayed there.)
`gn'
Flag whose presence means that this terminal type is a generic type which does not really describe any particular terminal. Generic types are intended for use as the default type assigned when the user connects to the system, with the intention that the user should specify what type he really has. One example of a generic type is the type `network'. Since the generic type cannot say how to do anything interesting with the terminal, termcap-using programs will always find that the terminal is too weak to be supported if the user has failed to specify a real terminal type in place of the generic one. The `gn' flag directs these programs to use a different error message: "You have not specified your real terminal type", rather than "Your terminal is not powerful enough to be used".
`hc'
Flag whose presence means this is a hardcopy terminal.
`rp'
String of commands to output a graphic character c, repeated n times. The first parameter value is the ASCII code for the desired character, and the second parameter is the number of times to repeat the character. Often this command requires padding proportional to the number of times the character is repeated. This effect can be had by using parameter arithmetic with `%'-sequences to compute the amount of padding, then generating the result as a number at the front of the string so that tputs will treat it as padding.
`hz'
Flag whose presence means that the ASCII character `~' cannot be output on this terminal because it is used for display commands. Programs handle this flag by checking all text to be output and replacing each `~' with some other character(s). If this is not done, the screen will be thoroughly garbled. The old Hazeltine terminals that required such treatment are probably very rare today, so you might as well not bother to support this flag.
`CC'
String whose presence means the terminal has a settable command character. The value of the string is the default command character (which is usually ESC). All the strings of commands in the terminal description should be written to use the default command character. If you are writing an application program that changes the command character, use the `CC' capability to figure out how to translate all the display commands to work with the new command character. Most programs have no reason to look at the `CC' capability.
`xb'
Flag whose presence identifies Superbee terminals which are unable to transmit the characters ESC and Control-C. Programs which support this flag are supposed to check the input for the code sequences sent by the F1 and F2 keys, and pretend that ESC or Control-C (respectively) had been read. But this flag is obsolete, and not worth supporting.

Screen Size

A terminal description has two capabilities, `co' and `li', that describe the screen size in columns and lines. But there is more to the question of screen size than this.

On some operating systems the "screen" is really a window and the effective width can vary. On some of these systems, tgetnum uses the actual width of the window to decide what value to return for the `co' capability, overriding what is actually written in the terminal description. On other systems, it is up to the application program to check the actual window width using a system call. For example, on BSD 4.3 systems, the system call ioctl with code TIOCGWINSZ will tell you the current screen size.

On all window systems, termcap is powerless to advise the application program if the user resizes the window. Application programs must deal with this possibility in a system-dependent fashion. On some systems the C shell handles part of the problem by detecting changes in window size and setting the TERMCAP environment variable appropriately. This takes care of application programs that are started subsequently. It does not help application programs already running.

On some systems, including BSD 4.3, all programs using a terminal get a signal named SIGWINCH whenever the screen size changes. Programs that use termcap should handle this signal by using ioctl TIOCGWINSZ to learn the new screen size.

`co'
Numeric value, the width of the screen in character positions. Even hardcopy terminals normally have a `co' capability.
`li'
Numeric value, the height of the screen in lines.

Cursor Motion

Termcap assumes that the terminal has a cursor, a spot on the screen where a visible mark is displayed, and that most display commands take effect at the position of the cursor. It follows that moving the cursor to a specified location is very important.

There are many terminal capabilities for different cursor motion operations. A terminal description should define as many as possible, but most programs do not need to use most of them. One capability, `cm', moves the cursor to an arbitrary place on the screen; this by itself is sufficient for any application as long as there is no need to support hardcopy terminals or certain old, weak displays that have only relative motion commands. Use of other cursor motion capabilities is an optimization, enabling the program to output fewer characters in some common cases.

If you plan to use the relative cursor motion commands in an application program, you must know what the starting cursor position is. To do this, you must keep track of the cursor position and update the records each time anything is output to the terminal, including graphic characters. In addition, it is necessary to know whether the terminal wraps after writing in the rightmost column. See section Wrapping.

One other motion capability needs special mention: `nw' moves the cursor to the beginning of the following line, perhaps clearing all the starting line after the cursor, or perhaps not clearing at all. This capability is a least common denominator that is probably supported even by terminals that cannot do most other things such as `cm' or `do'. Even hardcopy terminals can support `nw'.

`cm'
String of commands to position the cursor at line l, column c. Both parameters are origin-zero, and are defined relative to the screen, not relative to display memory. All display terminals except a few very obsolete ones support `cm', so it is acceptable for an application program to refuse to operate on terminals lacking `cm'.
`ho'
String of commands to move the cursor to the upper left corner of the screen (this position is called the home position). In terminals where the upper left corner of the screen is not the same as the beginning of display memory, this command must go to the upper left corner of the screen, not the beginning of display memory. Every display terminal supports this capability, and many application programs refuse to operate if the `ho' capability is missing.
`ll'
String of commands to move the cursor to the lower left corner of the screen. On some terminals, moving up from home position does this, but programs should never assume that will work. Just output the `ll' string (if it is provided); if moving to home position and then moving up is the best way to get there, the `ll' command will do that.
`cr'
String of commands to move the cursor to the beginning of the line it is on. If this capability is not specified, many programs assume they can use the ASCII carriage return character for this.
`le'
String of commands to move the cursor left one column. Unless the `bw' flag capability is specified, the effect is undefined if the cursor is at the left margin; do not use this command there. If `bw' is present, this command may be used at the left margin, and it wraps the cursor to the last column of the preceding line.
`nd'
String of commands to move the cursor right one column. The effect is undefined if the cursor is at the right margin; do not use this command there, not even if `am' is present.
`up'
String of commands to move the cursor vertically up one line. The effect of sending this string when on the top line is undefined; programs should never use it that way.
`do'
String of commands to move the cursor vertically down one line. The effect of sending this string when on the bottom line is undefined; programs should never use it that way. Some programs do use `do' to scroll up one line if used at the bottom line, if `sf' is not defined but `sr' is. This is only to compensate for certain old, incorrect terminal descriptions. (In principle this might actually lead to incorrect behavior on other terminals, but that seems to happen rarely if ever.) But the proper solution is that the terminal description should define `sf' as well as `do' if the command is suitable for scrolling. The original idea was that this string would not contain a newline character and therefore could be used without disabling the kernel's usual habit of converting of newline into a carriage-return newline sequence. But many terminal descriptions do use newline in the `do' string, so this is not possible; a program which sends the `do' string must disable output conversion in the kernel (see section Initialization for Use of Termcap).
`bw'
Flag whose presence says that `le' may be used in column zero to move to the last column of the preceding line. If this flag is not present, `le' should not be used in column zero.
`nw'
String of commands to move the cursor to start of next line, possibly clearing rest of line (following the cursor) before moving.
`DO', `UP', `LE', `RI'
Strings of commands to move the cursor n lines down vertically, up vertically, or n columns left or right. Do not attempt to move past any edge of the screen with these commands; the effect of trying that is undefined. Only a few terminal descriptions provide these commands, and most programs do not use them.
`CM'
String of commands to position the cursor at line l, column c, relative to display memory. Both parameters are origin-zero. This capability is present only in terminals where there is a difference between screen-relative and memory-relative addressing, and not even in all such terminals.
`ch'
String of commands to position the cursor at column c in the same line it is on. This is a special case of `cm' in which the vertical position is not changed. The `ch' capability is provided only when it is faster to output than `cm' would be in this special case. Programs should not assume most display terminals have `ch'.
`cv'
String of commands to position the cursor at line l in the same column. This is a special case of `cm' in which the horizontal position is not changed. The `cv' capability is provided only when it is faster to output than `cm' would be in this special case. Programs should not assume most display terminals have `cv'.
`sc'
String of commands to make the terminal save the current cursor position. Only the last saved position can be used. If this capability is present, `rc' should be provided also. Most terminals have neither.
`rc'
String of commands to make the terminal restore the last saved cursor position. If this capability is present, `sc' should be provided also. Most terminals have neither.
`ff'
String of commands to advance to the next page, for a hardcopy terminal.
`ta'
String of commands to move the cursor right to the next hardware tab stop column. Missing if the terminal does not have any kind of hardware tabs. Do not send this command if the kernel's terminal modes say that the kernel is expanding tabs into spaces.
`bt'
String of commands to move the cursor left to the previous hardware tab stop column. Missing if the terminal has no such ability; many terminals do not. Do not send this command if the kernel's terminal modes say that the kernel is expanding tabs into spaces.

The following obsolete capabilities should be included in terminal descriptions when appropriate, but should not be looked at by new programs.

`nc'
Flag whose presence means the terminal does not support the ASCII carriage return character as `cr'. This flag is needed because old programs assume, when the `cr' capability is missing, that ASCII carriage return can be used for the purpose. We use `nc' to tell the old programs that carriage return may not be used. New programs should not assume any default for `cr', so they need not look at `nc'. However, descriptions should contain `nc' whenever they do not contain `cr'.
`xt'
Flag whose presence means that the ASCII tab character may not be used for cursor motion. This flag exists because old programs assume, when the `ta' capability is missing, that ASCII tab can be used for the purpose. We use `xt' to tell the old programs not to use tab. New programs should not assume any default for `ta', so they need not look at `xt' in connection with cursor motion. Note that `xt' also has implications for standout mode (see section Standout and Appearance Modes). It is obsolete in regard to cursor motion but not in regard to standout. In fact, `xt' means that the terminal is a Teleray 1061.
`bc'
Very obsolete alternative name for the `le' capability.
`bs'
Flag whose presence means that the ASCII character backspace may be used to move the cursor left. Obsolete; look at `le' instead.
`nl'
Obsolete capability which is a string that can either be used to move the cursor down or to scroll. The same string must scroll when used on the bottom line and move the cursor when used on any other line. New programs should use `do' or `sf', and ignore `nl'. If there is no `nl' capability, some old programs assume they can use the newline character for this purpose. These programs follow a bad practice, but because they exist, it is still desirable to define the `nl' capability in a terminal description if the best way to move down is not a newline.

Wrapping

Wrapping means moving the cursor from the right margin to the left margin of the following line. Some terminals wrap automatically when a graphic character is output in the last column, while others do not. Most application programs that use termcap need to know whether the terminal wraps. There are two special flag capabilities to describe what the terminal does when a graphic character is output in the last column.

`am'
Flag whose presence means that writing a character in the last column causes the cursor to wrap to the beginning of the next line. If `am' is not present, writing in the last column leaves the cursor at the place where the character was written. Writing in the last column of the last line should be avoided on terminals with `am', as it may or may not cause scrolling to occur (see section Scrolling). Scrolling is surely not what you would intend. If your program needs to check the `am' flag, then it also needs to check the `xn' flag which indicates that wrapping happens in a strange way. Many common terminals have the `xn' flag.
`xn'
Flag whose presence means that the cursor wraps in a strange way. At least two distinct kinds of strange behavior are known; the termcap data base does not contain anything to distinguish the two. On Concept-100 terminals, output in the last column wraps the cursor almost like an ordinary `am' terminal. But if the next thing output is a newline, it is ignored. DEC VT-100 terminals (when the wrap switch is on) do a different strange thing: the cursor wraps only if the next thing output is another graphic character. In fact, the wrap occurs when the following graphic character is received by the terminal, before the character is placed on the screen. On both of these terminals, after writing in the last column a following graphic character will be displayed in the first column of the following line. But the effect of relative cursor motion characters such as newline or backspace at such a time depends on the terminal. The effect of erase or scrolling commands also depends on the terminal. You can't assume anything about what they will do on a terminal that has `xn'. So, to be safe, you should never do these things at such a time on such a terminal. To be sure of reliable results on a terminal which has the `xn' flag, output a `cm' absolute positioning command after writing in the last column. Another safe thing to do is to output carriage-return newline, which will leave the cursor at the beginning of the following line.
`LP'
Flag whose presence means that it is safe to write in the last column of the last line without worrying about undesired scrolling. `LP' indicates the DEC flavor of `xn' strangeness.

Scrolling

Scrolling means moving the contents of the screen up or down one or more lines. Moving the contents up is forward scrolling; moving them down is reverse scrolling.

Scrolling happens after each line of output during ordinary output on most display terminals. But in an application program that uses termcap for random-access output, scrolling happens only when explicitly requested with the commands in this section.

Some terminals have a scroll region feature. This lets you limit the effect of scrolling to a specified range of lines. Lines outside the range are unaffected when scrolling happens. The scroll region feature is available if either `cs' or `cS' is present.

`sf'
String of commands to scroll the screen one line up, assuming it is output with the cursor at the beginning of the bottom line.
`sr'
String of commands to scroll the screen one line down, assuming it is output with the cursor at the beginning of the top line.
`do'
A few programs will try to use `do' to do the work of `sf'. This is not really correct--it is an attempt to compensate for the absence of a `sf' command in some old terminal descriptions. Since these terminal descriptions do define `sr', perhaps at one time the definition of `do' was different and it could be used for scrolling as well. But it isn't desirable to combine these two functions in one capability, since scrolling often requires more padding than simply moving the cursor down. Defining `sf' and `do' separately allows you to specify the padding properly. Also, all sources agree that `do' should not be relied on to do scrolling. So the best approach is to add `sf' capabilities to the descriptions of these terminals, copying the definition of `do' if that does scroll.
`SF'
String of commands to scroll the screen n lines up, assuming it is output with the cursor at the beginning of the bottom line.
`SR'
String of commands to scroll the screen n lines down, assuming it is output with the cursor at the beginning of the top line.
`cs'
String of commands to set the scroll region. This command takes two parameters, start and end, which are the line numbers (origin-zero) of the first line to include in the scroll region and of the last line to include in it. When a scroll region is set, scrolling is limited to the specified range of lines; lines outside the range are not affected by scroll commands. Do not try to move the cursor outside the scroll region. The region remains set until explicitly removed. To remove the scroll region, use another `cs' command specifying the full height of the screen. The cursor position is undefined after the `cs' command is set, so position the cursor with `cm' immediately afterward.
`cS'
String of commands to set the scroll region using parameters in different form. The effect is the same as if `cs' were used. Four parameters are required:
  1. Total number of lines on the screen.
  2. Number of lines above desired scroll region.
  3. Number of lines below (outside of) desired scroll region.
  4. Total number of lines on the screen, the same as the first parameter.
This capability is a GNU extension that was invented to allow the Ann Arbor Ambassador's scroll-region command to be described; it could also be done by putting non-Unix `%'-sequences into a `cs' string, but that would have confused Unix programs that used the `cs' capability with the Unix termcap. Currently only GNU Emacs uses the `cS' capability.
`ns'
Flag which means that the terminal does not normally scroll for ordinary sequential output. For modern terminals, this means that outputting a newline in ordinary sequential output with the cursor on the bottom line wraps to the top line. For some obsolete terminals, other things may happen. The terminal may be able to scroll even if it does not normally do so. If the `sf' capability is provided, it can be used for scrolling regardless of `ns'.
`da'
Flag whose presence means that lines scrolled up off the top of the screen may come back if scrolling down is done subsequently. The `da' and `db' flags do not, strictly speaking, affect how to scroll. But programs that scroll usually need to clear the lines scrolled onto the screen, if these flags are present.
`db'
Flag whose presence means that lines scrolled down off the bottom of the screen may come back if scrolling up is done subsequently.
`lm'
Numeric value, the number of lines of display memory that the terminal has. A value of zero means that the terminal has more display memory than can fit on the screen, but no fixed number of lines. (The number of lines may depend on the amount of text in each line.)

Any terminal description that defines `SF' should also define `sf'; likewise for `SR' and `sr'. However, many terminals can only scroll by one line at a time, so it is common to find `sf' and not `SF', or `sr' without `SR'.

Therefore, all programs that use the scrolling facilities should be prepared to work with `sf' in the case that `SF' is absent, and likewise with `sr'. On the other hand, an application program that uses only `sf' and not `SF' is acceptable, though slow on some terminals.

When outputting a scroll command with tputs, the nlines argument should be the total number of lines in the portion of the screen being scrolled. Very often these commands require padding proportional to this number of lines. See section Padding.

Windows

A window, in termcap, is a rectangular portion of the screen to which all display operations are restricted. Wrapping, clearing, scrolling, insertion and deletion all operate as if the specified window were all the screen there was.

`wi'
String of commands to set the terminal output screen window. This string requires four parameters, all origin-zero:
  1. The first line to include in the window.
  2. The last line to include in the window.
  3. The first column to include in the window.
  4. The last column to include in the window.

Most terminals do not support windows.

Clearing Parts of the Screen

There are several terminal capabilities for clearing parts of the screen to blank. All display terminals support the `cl' string, and most display terminals support all of these capabilities.

`cl'
String of commands to clear the entire screen and position the cursor at the upper left corner.
`cd'
String of commands to clear the line the cursor is on, and all the lines below it, down to the bottom of the screen. This command string should be used only with the cursor in column zero; their effect is undefined if the cursor is elsewhere.
`ce'
String of commands to clear from the cursor to the end of the current line.
`ec'
String of commands to clear n characters, starting with the character that the cursor is on. This command string is expected to leave the cursor position unchanged. The parameter n should never be large enough to reach past the right margin; the effect of such a large parameter would be undefined.

Clear to end of line (`ce') is extremely important in programs that maintain an updating display. Nearly all display terminals support this operation, so it is acceptable for a an application program to refuse to work if `ce' is not present. However, if you do not want this limitation, you can accomplish clearing to end of line by outputting spaces until you reach the right margin. In order to do this, you must know the current horizontal position. Also, this technique assumes that writing a space will erase. But this happens to be true on all the display terminals that fail to support `ce'.

Insert/Delete Line

Inserting a line means creating a blank line in the middle of the screen, and pushing the existing lines of text apart. In fact, the lines above the insertion point do not change, while the lines below move down, and one is normally lost at the bottom of the screen.

Deleting a line means causing the line to disappear from the screen, closing up the gap by moving the lines below it upward. A new line appears at the bottom of the screen. Usually this line is blank, but on terminals with the `db' flag it may be a line previously moved off the screen bottom by scrolling or line insertion.

Insertion and deletion of lines is useful in programs that maintain an updating display some parts of which may get longer or shorter. They are also useful in editors for scrolling parts of the screen, and for redisplaying after lines of text are killed or inserted.

Many terminals provide commands to insert or delete a single line at the cursor position. Some provide the ability to insert or delete several lines with one command, using the number of lines to insert or delete as a parameter. Always move the cursor to column zero before using any of these commands.

`al'
String of commands to insert a blank line before the line the cursor is on. The existing line, and all lines below it, are moved down. The last line in the screen (or in the scroll region, if one is set) disappears and in most circumstances is discarded. It may not be discarded if the `db' is present (see section Scrolling). The cursor must be at the left margin before this command is used. This command does not move the cursor.
`dl'
String of commands to delete the line the cursor is on. The following lines move up, and a blank line appears at the bottom of the screen (or bottom of the scroll region). If the terminal has the `db' flag, a nonblank line previously pushed off the screen bottom may reappear at the bottom. The cursor must be at the left margin before this command is used. This command does not move the cursor.
`AL'
String of commands to insert n blank lines before the line that the cursor is on. It is like `al' repeated n times, except that it is as fast as one `al'.
`DL'
String of commands to delete n lines starting with the line that the cursor is on. It is like `dl' repeated n times, except that it is as fast as one `dl'.

Any terminal description that defines `AL' should also define `al'; likewise for `DL' and `dl'. However, many terminals can only insert or delete one line at a time, so it is common to find `al' and not `AL', or `dl' without `DL'.

Therefore, all programs that use the insert and delete facilities should be prepared to work with `al' in the case that `AL' is absent, and likewise with `dl'. On the other hand, it is acceptable to write an application that uses only `al' and `dl' and does not look for `AL' or `DL' at all.

If a terminal does not support line insertion and deletion directly, but does support a scroll region, the effect of insertion and deletion can be obtained with scrolling. However, it is up to the individual user program to check for this possibility and use the scrolling commands to get the desired result. It is fairly important to implement this alternate strategy, since it is the only way to get the effect of line insertion and deletion on the popular VT100 terminal.

Insertion and deletion of lines is affected by the scroll region on terminals that have a settable scroll region. This is useful when it is desirable to move any few consecutive lines up or down by a few lines. See section Scrolling.

The line pushed off the bottom of the screen is not lost if the terminal has the `db' flag capability; instead, it is pushed into display memory that does not appear on the screen. This is the same thing that happens when scrolling pushes a line off the bottom of the screen. Either reverse scrolling or deletion of a line can bring the apparently lost line back onto the bottom of the screen. If the terminal has the scroll region feature as well as `db', the pushed-out line really is lost if a scroll region is in effect.

When outputting an insert or delete command with tputs, the nlines argument should be the total number of lines from the cursor to the bottom of the screen (or scroll region). Very often these commands require padding proportional to this number of lines. See section Padding.

For `AL' and `DL' the nlines argument should not depend on the number of lines inserted or deleted; only the total number of lines affected. This is because it is just as fast to insert two or n lines with `AL' as to insert one line with `al'.

Insert/Delete Character

Inserting a character means creating a blank space in the middle of a line, and pushing the rest of the line rightward. The character in the rightmost column is lost.

Deleting a character means causing the character to disappear from the screen, closing up the gap by moving the rest of the line leftward. A blank space appears in the rightmost column.

Insertion and deletion of characters is useful in programs that maintain an updating display some parts of which may get longer or shorter. It is also useful in editors for redisplaying the results of editing within a line.

Many terminals provide commands to insert or delete a single character at the cursor position. Some provide the ability to insert or delete several characters with one command, using the number of characters to insert or delete as a parameter.

Many terminals provide an insert mode in which outputting a graphic character has the added effect of inserting a position for that character. A special command string is used to enter insert mode and another is used to exit it. The reason for designing a terminal with an insert mode rather than an insert command is that inserting character positions is usually followed by writing characters into them. With insert mode, this is as fast as simply writing the characters, except for the fixed overhead of entering and leaving insert mode. However, when the line speed is great enough, padding may be required for the graphic characters output in insert mode.

Some terminals require you to enter insert mode and then output a special command for each position to be inserted. Or they may require special commands to be output before or after each graphic character to be inserted.

Deletion of characters is usually accomplished by a straightforward command to delete one or several positions; but on some terminals, it is necessary to enter a special delete mode before using the delete command, and leave delete mode afterward. Sometimes delete mode and insert mode are the same mode.

Some terminals make a distinction between character positions in which a space character has been output and positions which have been cleared. On these terminals, the effect of insert or delete character runs to the first cleared position rather than to the end of the line. In fact, the effect may run to more than one line if there is no cleared position to stop the shift on the first line. These terminals are identified by the `in' flag capability.

On terminals with the `in' flag, the technique of skipping over characters that you know were cleared, and then outputting text later on in the same line, causes later insert and delete character operations on that line to do nonstandard things. A program that has any chance of doing this must check for the `in' flag and must be careful to write explicit space characters into the intermediate columns when `in' is present.

A plethora of terminal capabilities are needed to describe all of this complexity. Here is a list of them all. Following the list, we present an algorithm for programs to use to take proper account of all of these capabilities.

`im'
String of commands to enter insert mode. If the terminal has no special insert mode, but it can insert characters with a special command, `im' should be defined with a null value, because the `vi' editor assumes that insertion of a character is impossible if `im' is not provided. New programs should not act like `vi'. They should pay attention to `im' only if it is defined.
`ei'
String of commands to leave insert mode. This capability must be present if `im' is. On a few old terminals the same string is used to enter and exit insert mode. This string turns insert mode on if it was off, and off it it was on. You can tell these terminals because the `ei' string equals the `im' string. If you want to support these terminals, you must always remember accurately whether insert mode is in effect. However, these terminals are obsolete, and it is reasonable to refuse to support them. On all modern terminals, you can safely output `ei' at any time to ensure that insert mode is turned off.
`ic'
String of commands to insert one character position at the cursor. The cursor does not move. If outputting a graphic character while in insert mode is sufficient to insert the character, then the `ic' capability should be defined with a null value. If your terminal offers a choice of ways to insert--either use insert mode or use a special command--then define `im' and do not define `ic', since this gives the most efficient operation when several characters are to be inserted. Do not define both strings, for that means that both must be used each time insertion is done.
`ip'
String of commands to output following an inserted graphic character in insert mode. Often it is used just for a padding spec, when padding is needed after an inserted character (see section Padding).
`IC'
String of commands to insert n character positions at and after the cursor. It has the same effect as repeating the `ic' string and a space, n times. If `IC' is provided, application programs may use it without first entering insert mode.
`mi'
Flag whose presence means it is safe to move the cursor while in insert mode and assume the terminal remains in insert mode.
`in'
Flag whose presence means that the terminal distinguishes between character positions in which space characters have been output and positions which have been cleared.

An application program can assume that the terminal can do character insertion if any one of the capabilities `IC', `im', `ic' or `ip' is provided.

To insert n blank character positions, move the cursor to the place to insert them and follow this algorithm:

  1. If an `IC' string is provided, output it with parameter n and you are finished. Otherwise (or if you don't want to bother to look for an `IC' string) follow the remaining steps.
  2. Output the `im' string, if there is one, unless the terminal is already in insert mode.
  3. Repeat steps 4 through 6, n times.
  4. Output the `ic' string if any.
  5. Output a space.
  6. Output the `ip' string if any.
  7. Output the `ei' string, eventually, to exit insert mode. There is no need to do this right away. If the `mi' flag is present, you can move the cursor and the cursor will remain in insert mode; then you can do more insertion elsewhere without reentering insert mode.

To insert n graphic characters, position the cursor and follow this algorithm:

  1. If an `IC' string is provided, output it with parameter n, then output the graphic characters, and you are finished. Otherwise (or if you don't want to bother to look for an `IC' string) follow the remaining steps.
  2. Output the `im' string, if there is one, unless the terminal is already in insert mode.
  3. For each character to be output, repeat steps 4 through 6.
  4. Output the `ic' string if any.
  5. Output the next graphic character.
  6. Output the `ip' string if any.
  7. Output the `ei' string, eventually, to exit insert mode. There is no need to do this right away. If the `mi' flag is present, you can move the cursor and the cursor will remain in insert mode; then you can do more insertion elsewhere without reentering insert mode.

Note that this is not the same as the original Unix termcap specifications in one respect: it assumes that the `IC' string can be used without entering insert mode. This is true as far as I know, and it allows you be able to avoid entering and leaving insert mode, and also to be able to avoid the inserted-character padding after the characters that go into the inserted positions.

Deletion of characters is less complicated; deleting one column is done by outputting the `dc' string. However, there may be a delete mode that must be entered with `dm' in order to make `dc' work.

`dc'
String of commands to delete one character position at the cursor. If `dc' is not present, the terminal cannot delete characters.
`DC'
String of commands to delete n characters starting at the cursor. It has the same effect as repeating the `dc' string n times. Any terminal description that has `DC' also has `dc'.
`dm'
String of commands to enter delete mode. If not present, there is no delete mode, and `dc' can be used at any time (assuming there is a `dc').
`ed'
String of commands to exit delete mode. This must be present if `dm' is.

To delete n character positions, position the cursor and follow these steps:

  1. If the `DC' string is present, output it with parameter n and you are finished. Otherwise, follow the remaining steps.
  2. Output the `dm' string, unless you know the terminal is already in delete mode.
  3. Output the `dc' string n times.
  4. Output the `ed' string eventually. If the flag capability `mi' is present, you can move the cursor and do more deletion without leaving and reentering delete mode.

As with the `IC' string, we have departed from the original termcap specifications by assuming that `DC' works without entering delete mode even though `dc' would not.

If the `dm' and `im' capabilities are both present and have the same value, it means that the terminal has one mode for both insertion and deletion. It is useful for a program to know this, because then it can do insertions after deletions, or vice versa, without leaving insert/delete mode and reentering it.

Standout and Appearance Modes

Appearance modes are modifications to the ways characters are displayed. Typical appearance modes include reverse video, dim, bright, blinking, underlined, invisible, and alternate character set. Each kind of terminal supports various among these, or perhaps none.

For each type of terminal, one appearance mode or combination of them that looks good for highlighted text is chosen as the standout mode. The capabilities `so' and `se' say how to enter and leave standout mode. Programs that use appearance modes only to highlight some text generally use the standout mode so that they can work on as many terminals as possible. Use of specific appearance modes other than "underlined" and "alternate character set" is rare.

Terminals that implement appearance modes fall into two general classes as to how they do it.

In some terminals, the presence or absence of any appearance mode is recorded separately for each character position. In these terminals, each graphic character written is given the appearance modes current at the time it is written, and keeps those modes until it is erased or overwritten. There are special commands to turn the appearance modes on or off for characters to be written in the future.

In other terminals, the change of appearance modes is represented by a marker that belongs to a certain screen position but affects all following screen positions until the next marker. These markers are traditionally called magic cookies.

The same capabilities (`so', `se', `mb' and so on) for turning appearance modes on and off are used for both magic-cookie terminals and per-character terminals. On magic cookie terminals, these give the commands to write the magic cookies. On per-character terminals, they change the current modes that affect future output and erasure. Some simple applications can use these commands without knowing whether or not they work by means of cookies.

However, a program that maintains and updates a display needs to know whether the terminal uses magic cookies, and exactly what their effect is. This information comes from the `sg' capability.

The `sg' capability is a numeric capability whose presence indicates that the terminal uses magic cookies for appearance modes. Its value is the number of character positions that a magic cookie occupies. Usually the cookie occupies one or more character positions on the screen, and these character positions are displayed as blank, but in some terminals the cookie has zero width.

The `sg' capability describes both the magic cookie to turn standout on and the cookie to turn it off. This makes the assumption that both kinds of cookie have the same width on the screen. If that is not true, the narrower cookie must be "widened" with spaces until it has the same width as the other.

On some magic cookie terminals, each line always starts with normal display; in other words, the scope of a magic cookie never extends over more than one line. But on other terminals, one magic cookie affects all the lines below it unless explicitly canceled. Termcap does not define any way to distinguish these two ways magic cookies can work. To be safe, it is best to put a cookie at the beginning of each line.

On some per-character terminals, standout mode or other appearance modes may be canceled by moving the cursor. On others, moving the cursor has no effect on the state of the appearance modes. The latter class of terminals are given the flag capability `ms' ("can move in standout"). All programs that might have occasion to move the cursor while appearance modes are turned on must check for this flag; if it is not present, they should reset appearance modes to normal before doing cursor motion.

A program that has turned on only standout mode should use `se' to reset the standout mode to normal. A program that has turned on only alternate character set mode should use `ae' to return it to normal. If it is possible that any other appearance modes are turned on, use the `me' capability to return them to normal.

Note that the commands to turn on one appearance mode, including `so' and `mb' ... `mr', if used while some other appearance modes are turned on, may combine the two modes on some terminals but may turn off the mode previously enabled on other terminals. This is because some terminals do not have a command to set or clear one appearance mode without changing the others. Programs should not attempt to use appearance modes in combination except with `sa', and when switching from one single mode to another should always turn off the previously enabled mode and then turn on the new desired mode.

On some old terminals, the `so' and `se' commands may be the same command, which has the effect of turning standout on if it is off, or off it is on. It is therefore risky for a program to output extra `se' commands for good measure. Fortunately, all these terminals are obsolete.

Programs that update displays in which standout-text may be replaced with non-standout text must check for the `xs' flag. In a per-character terminal, this flag says that the only way to remove standout once written is to clear that portion of the line with the `ce' string or something even more powerful (see section Clearing Parts of the Screen); just writing new characters at those screen positions will not change the modes in effect there. In a magic cookie terminal, `xs' says that the only way to remove a cookie is to clear a portion of the line that includes the cookie; writing a different cookie at the same position does not work.

Such programs must also check for the `xt' flag, which means that the terminal is a Teleray 1061. On this terminal it is impossible to position the cursor at the front of a magic cookie, so the only two ways to remove a cookie are (1) to delete the line it is on or (2) to position the cursor at least one character before it (possibly on a previous line) and output the `se' string, which on these terminals finds and removes the next `so' magic cookie on the screen. (It may also be possible to remove a cookie which is not at the beginning of a line by clearing that line.) The `xt' capability also has implications for the use of tab characters, but in that regard it is obsolete (See section Cursor Motion).

`so'
String of commands to enter standout mode.
`se'
String of commands to leave standout mode.
`sg'
Numeric capability, the width on the screen of the magic cookie. This capability is absent in terminals that record appearance modes character by character.
`ms'
Flag whose presence means that it is safe to move the cursor while the appearance modes are not in the normal state. If this flag is absent, programs should always reset the appearance modes to normal before moving the cursor.
`xs'
Flag whose presence means that the only way to reset appearance modes already on the screen is to clear to end of line. On a per-character terminal, you must clear the area where the modes are set. On a magic cookie terminal, you must clear an area containing the cookie. See the discussion above.
`xt'
Flag whose presence means that the cursor cannot be positioned right in front of a magic cookie, and that `se' is a command to delete the next magic cookie following the cursor. See discussion above.
`mb'
String of commands to enter blinking mode.
`md'
String of commands to enter double-bright mode.
`mh'
String of commands to enter half-bright mode.
`mk'
String of commands to enter invisible mode.
`mp'
String of commands to enter protected mode.
`mr'
String of commands to enter reverse-video mode.
`me'
String of commands to turn off all appearance modes, including standout mode and underline mode. On some terminals it also turns off alternate character set mode; on others, it may not. This capability must be present if any of `mb' ... `mr' is present.
`as'
String of commands to turn on alternate character set mode. This mode assigns some or all graphic characters an alternate picture on the screen. There is no standard as to what the alternate pictures look like.
`ae'
String of commands to turn off alternate character set mode.
`sa'
String of commands to turn on an arbitrary combination of appearance modes. It accepts 9 parameters, each of which controls a particular kind of appearance mode. A parameter should be 1 to turn its appearance mode on, or zero to turn that mode off. Most terminals do not support the `sa' capability, even among those that do have various appearance modes. The nine parameters are, in order, standout, underline, reverse, blink, half-bright, double-bright, blank, protect, alt char set.

Underlining

Underlining on most terminals is a kind of appearance mode, much like standout mode. Therefore, it may be implemented using magic cookies or as a flag in the terminal whose current state affects each character that is output. See section Standout and Appearance Modes, for a full explanation.

The `ug' capability is a numeric capability whose presence indicates that the terminal uses magic cookies for underlining. Its value is the number of character positions that a magic cookie for underlining occupies; it is used for underlining just as `sg' is used for standout. Aside from the simplest applications, it is impossible to use underlining correctly without paying attention to the value of `ug'.

`us'
String of commands to turn on underline mode or to output a magic cookie to start underlining.
`ue'
String of commands to turn off underline mode or to output a magic cookie to stop underlining.
`ug'
Width of magic cookie that represents a change of underline mode; or missing, if the terminal does not use a magic cookie for this.
`ms'
Flag whose presence means that it is safe to move the cursor while the appearance modes are not in the normal state. Underlining is an appearance mode. If this flag is absent, programs should always turn off underlining before moving the cursor.

There are two other, older ways of doing underlining: there can be a command to underline a single character, or the output of `_', the ASCII underscore character, as an overstrike could cause a character to be underlined. New programs need not bother to handle these capabilities unless the author cares strongly about the obscure terminals which support them. However, terminal descriptions should provide these capabilities when appropriate.

`uc'
String of commands to underline the character under the cursor, and move the cursor right.
`ul'
Flag whose presence means that the terminal can underline by overstriking an underscore character (`_'); some terminals can do this even though they do not support overstriking in general. An implication of this flag is that when outputting new text to overwrite old text, underscore characters must be treated specially lest they underline the old text instead.

Cursor Visibility

Some terminals have the ability to make the cursor invisible, or to enhance it. Enhancing the cursor is often done by programs that plan to use the cursor to indicate to the user a position of interest that may be anywhere on the screen--for example, the Emacs editor enhances the cursor on entry. Such programs should always restore the cursor to normal on exit.

`vs'
String of commands to enhance the cursor.
`vi'
String of commands to make the cursor invisible.
`ve'
String of commands to return the cursor to normal.

If you define either `vs' or `vi', you must also define `ve'.

Bell

Here we describe commands to make the terminal ask for the user to pay attention to it.

`bl'
String of commands to cause the terminal to make an audible sound. If this capability is absent, the terminal has no way to make a suitable sound.
`vb'
String of commands to cause the screen to flash to attract attention ("visible bell"). If this capability is absent, the terminal has no way to do such a thing.

Keypad and Function Keys

Many terminals have arrow and function keys that transmit specific character sequences to the computer. Since the precise sequences used depend on the terminal, termcap defines capabilities used to say what the sequences are. Unlike most termcap string-valued capabilities, these are not strings of commands to be sent to the terminal, rather strings that are received from the terminal.

Programs that expect to use keypad keys should check, initially, for a `ks' capability and send it, to make the keypad actually transmit. Such programs should also send the `ke' string when exiting.

`ks'
String of commands to make the keypad keys transmit. If this capability is not provided, but the others in this section are, programs may assume that the keypad keys always transmit.
`ke'
String of commands to make the keypad keys work locally. This capability is provided only if `ks' is.
`kl'
String of input characters sent by typing the left-arrow key. If this capability is missing, you cannot expect the terminal to have a left-arrow key that transmits anything to the computer.
`kr'
String of input characters sent by typing the right-arrow key.
`ku'
String of input characters sent by typing the up-arrow key.
`kd'
String of input characters sent by typing the down-arrow key.
`kh'
String of input characters sent by typing the "home-position" key.
`K1' ... `K5'
Strings of input characters sent by the five other keys in a 3-by-3 array that includes the arrow keys, if the keyboard has such a 3-by-3 array. Note that one of these keys may be the "home-position" key, in which case one of these capabilities will have the same value as the `kh' key.
`k0'
String of input characters sent by function key 10 (or 0, if the terminal has one labeled 0).
`k1' ... `k9'
Strings of input characters sent by function keys 1 through 9, provided for those function keys that exist.
`kn'
Number: the number of numbered function keys, if there are more than 10.
`l0' ... `l9'
Strings which are the labels appearing on the keyboard on the keys described by the capabilities `k0' ... `l9'. These capabilities should be left undefined if the labels are `f0' or `f10' and `f1' ... `f9'.
`kH'
String of input characters sent by the "home down" key, if there is one.
`kb'
String of input characters sent by the "backspace" key, if there is one.
`ka'
String of input characters sent by the "clear all tabs" key, if there is one.
`kt'
String of input characters sent by the "clear tab stop this column" key, if there is one.
`kC'
String of input characters sent by the "clear screen" key, if there is one.
`kD'
String of input characters sent by the "delete character" key, if there is one.
`kL'
String of input characters sent by the "delete line" key, if there is one.
`kM'
String of input characters sent by the "exit insert mode" key, if there is one.
`kE'
String of input characters sent by the "clear to end of line" key, if there is one.
`kS'
String of input characters sent by the "clear to end of screen" key, if there is one.
`kI'
String of input characters sent by the "insert character" or "enter insert mode" key, if there is one.
`kA'
String of input characters sent by the "insert line" key, if there is one.
`kN'
String of input characters sent by the "next page" key, if there is one.
`kP'
String of input characters sent by the "previous page" key, if there is one.
`kF'
String of input characters sent by the "scroll forward" key, if there is one.
`kR'
String of input characters sent by the "scroll reverse" key, if there is one.
`kT'
String of input characters sent by the "set tab stop in this column" key, if there is one.
`ko'
String listing the other function keys the terminal has. This is a very obsolete way of describing the same information found in the `kH' ... `kT' keys. The string contains a list of two-character termcap capability names, separated by commas. The meaning is that for each capability name listed, the terminal has a key which sends the string which is the value of that capability. For example, the value `:ko=cl,ll,sf,sr:' says that the terminal has four function keys which mean "clear screen", "home down", "scroll forward" and "scroll reverse".

Meta Key

A Meta key is a key on the keyboard that modifies each character you type by controlling the 0200 bit. This bit is on if and only if the Meta key is held down when the character is typed. Characters typed using the Meta key are called Meta characters. Emacs uses Meta characters as editing commands.

`km'
Flag whose presence means that the terminal has a Meta key.
`mm'
String of commands to enable the functioning of the Meta key.
`mo'
String of commands to disable the functioning of the Meta key.

If the terminal has `km' but does not have `mm' and `mo', it means that the Meta key always functions. If it has `mm' and `mo', it means that the Meta key can be turned on or off. Send the `mm' string to turn it on, and the `mo' string to turn it off. I do not know why one would ever not want it to be on.

Initialization

`ti'
String of commands to put the terminal into whatever special modes are needed or appropriate for programs that move the cursor nonsequentially around the screen. Programs that use termcap to do full-screen display should output this string when they start up.
`te'
String of commands to undo what is done by the `ti' string. Programs that output the `ti' string on entry should output this string when they exit.
`is'
String of commands to initialize the terminal for each login session.
`if'
String which is the name of a file containing the string of commands to initialize the terminal for each session of use. Normally `is' and `if' are not both used.
`i1'
`i3'
Two more strings of commands to initialize the terminal for each login session. The `i1' string (if defined) is output before `is' or `if', and the `i3' string (if defined) is output after. The reason for having three separate initialization strings is to make it easier to define a group of related terminal types with slightly different initializations. Define two or three of the strings in the basic type; then the other types can override one or two of the strings.
`rs'
String of commands to reset the terminal from any strange mode it may be in. Normally this includes the `is' string (or other commands with the same effects) and more. What would go in the `rs' string but not in the `is' string are annoying or slow commands to bring the terminal back from strange modes that nobody would normally use.
`it'
Numeric value, the initial spacing between hardware tab stop columns when the terminal is powered up. Programs to initialize the terminal can use this to decide whether there is a need to set the tab stops. If the initial width is 8, well and good; if it is not 8, then the tab stops should be set; if they cannot be set, the kernel is told to convert tabs to spaces, and other programs will observe this and do likewise.
`ct'
String of commands to clear all tab stops.
`st'
String of commands to set tab stop at current cursor column on all lines.
`NF'
Flag whose presence means that the terminal does not support XON/XOFF flow control. Programs should not send XON (C-q) or XOFF (C-s) characters to the terminal.

Padding Capabilities

There are two terminal capabilities that exist just to explain the proper way to obey the padding specifications in all the command string capabilities. One, `pc', must be obeyed by all termcap-using programs.

`pb'
Numeric value, the lowest baud rate at which padding is actually needed. Programs may check this and refrain from doing any padding at lower speeds.
`pc'
String of commands for padding. The first character of this string is to be used as the pad character, instead of using null characters for padding. If `pc' is not provided, use null characters. Every program that uses termcap must look up this capability and use it to set the variable PC that is used by tputs. See section Padding.

Some termcap capabilities exist just to specify the amount of padding that the kernel should give to cursor motion commands used in ordinary sequential output.

`dC'
Numeric value, the number of msec of padding needed for the carriage-return character.
`dN'
Numeric value, the number of msec of padding needed for the newline (linefeed) character.
`dB'
Numeric value, the number of msec of padding needed for the backspace character.
`dF'
Numeric value, the number of msec of padding needed for the formfeed character.
`dT'
Numeric value, the number of msec of padding needed for the tab character.

In some systems, the kernel uses the above capabilities; in other systems, the kernel uses the paddings specified in the string capabilities `cr', `sf', `le', `ff' and `ta'. Descriptions of terminals which require such padding should contain the `dC' ... `dT' capabilities and also specify the appropriate padding in the corresponding string capabilities. Since no modern terminals require padding for ordinary sequential output, you probably won't need to do either of these things.

Status Line

A status line is a line on the terminal that is not used for ordinary display output but instead used for a special message. The intended use is for a continuously updated description of what the user's program is doing, and that is where the name "status line" comes from, but in fact it could be used for anything. The distinguishing characteristic of a status line is that ordinary output to the terminal does not affect it; it changes only if the special status line commands of this section are used.

`hs'
Flag whose presence means that the terminal has a status line. If a terminal description specifies that there is a status line, it must provide the `ts' and `fs' capabilities.
`ts'
String of commands to move the terminal cursor into the status line. Usually these commands must specifically record the old cursor position for the sake of the `fs' string.
`fs'
String of commands to move the cursor back from the status line to its previous position (outside the status line).
`es'
Flag whose presence means that other display commands work while writing the status line. In other words, one can clear parts of it, insert or delete characters, move the cursor within it using `ch' if there is a `ch' capability, enter and leave standout mode, and so on.
`ds'
String of commands to disable the display of the status line. This may be absent, if there is no way to disable the status line display.
`ws'
Numeric value, the width of the status line. If this capability is absent in a terminal that has a status line, it means the status line is the same width as the other lines. Note that the value of `ws' is sometimes as small as 8.

Half-Line Motion

Some terminals have commands for moving the cursor vertically by half-lines, useful for outputting subscripts and superscripts. Mostly it is hardcopy terminals that have such features.

`hu'
String of commands to move the cursor up half a line. If the terminal is a display, it is your responsibility to avoid moving up past the top line; however, most likely the terminal that supports this is a hardcopy terminal and there is nothing to be concerned about.
`hd'
String of commands to move the cursor down half a line. If the terminal is a display, it is your responsibility to avoid moving down past the bottom line, etc.

Controlling Printers Attached to Terminals

Some terminals have attached hardcopy printer ports. They may be able to copy the screen contents to the printer; they may also be able to redirect output to the printer. Termcap does not have anything to tell the program whether the redirected output appears also on the screen; it does on some terminals but not all.

`ps'
String of commands to cause the contents of the screen to be printed. If it is absent, the screen contents cannot be printed.
`po'
String of commands to redirect further output to the printer.
`pf'
String of commands to terminate redirection of output to the printer. This capability must be present in the description if `po' is.
`pO'
String of commands to redirect output to the printer for next n characters of output, regardless of what they are. Redirection will end automatically after n characters of further output. Until then, nothing that is output can end redirection, not even the `pf' string if there is one. The number n should not be more than 255. One use of this capability is to send non-text byte sequences (such as bit-maps) to the printer.

Most terminals with printers do not support all of `ps', `po' and `pO'; any one or two of them may be supported. To make a program that can send output to all kinds of printers, it is necessary to check for all three of these capabilities, choose the most convenient of the ones that are provided, and use it in its own appropriate fashion.

Summary of Capability Names

Here are all the terminal capability names in alphabetical order with a brief description of each. For cross references to their definitions, see the index of capability names (see section Capability Index).

`ae'
String to turn off alternate character set mode.
`al'
String to insert a blank line before the cursor.
`AL'
String to insert n blank lines before the cursor.
`am'
Flag: output to last column wraps cursor to next line.
`as'
String to turn on alternate character set mode.like.
`bc'
Very obsolete alternative name for the `le' capability.
`bl'
String to sound the bell.
`bs'
Obsolete flag: ASCII backspace may be used for leftward motion.
`bt'
String to move the cursor left to the previous hardware tab stop column.
`bw'
Flag: `le' at left margin wraps to end of previous line.
`CC'
String to change terminal's command character.
`cd'
String to clear the line the cursor is on, and following lines.
`ce'
String to clear from the cursor to the end of the line.
`ch'
String to position the cursor at column c in the same line.
`cl'
String to clear the entire screen and put cursor at upper left corner.
`cm'
String to position the cursor at line l, column c.
`CM'
String to position the cursor at line l, column c, relative to display memory.
`co'
Number: width of the screen.
`cr'
String to move cursor sideways to left margin.
`cs'
String to set the scroll region.
`cS'
Alternate form of string to set the scroll region.
`ct'
String to clear all tab stops.
`cv'
String to position the cursor at line l in the same column.
`da'
Flag: data scrolled off top of screen may be scrolled back.
`db'
Flag: data scrolled off bottom of screen may be scrolled back.
`dB'
Obsolete number: msec of padding needed for the backspace character.
`dc'
String to delete one character position at the cursor.
`dC'
Obsolete number: msec of padding needed for the carriage-return character.
`DC'
String to delete n characters starting at the cursor.
`dF'
Obsolete number: msec of padding needed for the formfeed character.
`dl'
String to delete the line the cursor is on.
`DL'
String to delete n lines starting with the cursor's line.
`dm'
String to enter delete mode.
`dN'
Obsolete number: msec of padding needed for the newline character.
`do'
String to move the cursor vertically down one line.
`DO'
String to move cursor vertically down n lines.
`ds'
String to disable the display of the status line.
`dT'
Obsolete number: msec of padding needed for the tab character.
`ec'
String of commands to clear n characters at cursor.
`ed'
String to exit delete mode.
`ei'
String to leave insert mode.
`eo'
Flag: output of a space can erase an overstrike.
`es'
Flag: other display commands work while writing the status line.
`ff'
String to advance to the next page, for a hardcopy terminal.
`fs'
String to move the cursor back from the status line to its previous position (outside the status line).
`gn'
Flag: this terminal type is generic, not real.
`hc'
Flag: hardcopy terminal.
`hd'
String to move the cursor down half a line.
`ho'
String to position cursor at upper left corner.
`hs'
Flag: the terminal has a status line.
`hu'
String to move the cursor up half a line.
`hz'
Flag: terminal cannot accept `~' as output.
`i1'
String to initialize the terminal for each login session.
`i3'
String to initialize the terminal for each login session.
`ic'
String to insert one character position at the cursor.
`IC'
String to insert n character positions at the cursor.
`if'
String naming a file of commands to initialize the terminal.
`im'
String to enter insert mode.
`in'
Flag: outputting a space is different from moving over empty positions.
`ip'
String to output following an inserted character in insert mode.
`is'
String to initialize the terminal for each login session.
`it'
Number: initial spacing between hardware tab stop columns.
`k0'
String of input sent by function key 0 or 10.
`k1 ... k9'
Strings of input sent by function keys 1 through 9.
`K1 ... K5'
Strings sent by the five other keys in 3-by-3 array with arrows.
`ka'
String of input sent by the "clear all tabs" key.
`kA'
String of input sent by the "insert line" key.
`kb'
String of input sent by the "backspace" key.
`kC'
String of input sent by the "clear screen" key.
`kd'
String of input sent by typing the down-arrow key.
`kD'
String of input sent by the "delete character" key.
`ke'
String to make the function keys work locally.
`kE'
String of input sent by the "clear to end of line" key.
`kF'
String of input sent by the "scroll forward" key.
`kh'
String of input sent by typing the "home-position" key.
`kH'
String of input sent by the "home down" key.
`kI'
String of input sent by the "insert character" or "enter insert mode" key.
`kl'
String of input sent by typing the left-arrow key.
`kL'
String of input sent by the "delete line" key.
`km'
Flag: the terminal has a Meta key.
`kM'
String of input sent by the "exit insert mode" key.
`kn'
Numeric value, the number of numbered function keys.
`kN'
String of input sent by the "next page" key.
`ko'
Very obsolete string listing the terminal's named function keys.
`kP'
String of input sent by the "previous page" key.
`kr'
String of input sent by typing the right-arrow key.
`kR'
String of input sent by the "scroll reverse" key.
`ks'
String to make the function keys transmit.
`kS'
String of input sent by the "clear to end of screen" key.
`kt'
String of input sent by the "clear tab stop this column" key.
`kT'
String of input sent by the "set tab stop in this column" key.
`ku'
String of input sent by typing the up-arrow key.
`l0'
String on keyboard labelling function key 0 or 10.
`l1 ... l9'
Strings on keyboard labelling function keys 1 through 9.
`le'
String to move the cursor left one column.
`LE'
String to move cursor left n columns.
`li'
Number: height of the screen.
`ll'
String to position cursor at lower left corner.
`lm'
Number: lines of display memory.
`LP'
Flag: writing to last column of last line will not scroll.
`mb'
String to enter blinking mode.
`md'
String to enter double-bright mode.
`me'
String to turn off all appearance modes
`mh'
String to enter half-bright mode.
`mi'
Flag: cursor motion in insert mode is safe.
`mk'
String to enter invisible mode.
`mm'
String to enable the functioning of the Meta key.
`mo'
String to disable the functioning of the Meta key.
`mp'
String to enter protected mode.
`mr'
String to enter reverse-video mode.
`ms'
Flag: cursor motion in standout mode is safe.
`nc'
Obsolete flag: do not use ASCII carriage-return on this terminal.
`nd'
String to move the cursor right one column.
`NF'
Flag: do not use XON/XOFF flow control.
`nl'
Obsolete alternative name for the `do' and `sf' capabilities.
`ns'
Flag: the terminal does not normally scroll for sequential output.
`nw'
String to move to start of next line, possibly clearing rest of old line.
`os'
Flag: terminal can overstrike.
`pb'
Number: the lowest baud rate at which padding is actually needed.
`pc'
String containing character for padding.
`pf'
String to terminate redirection of output to the printer.
`po'
String to redirect further output to the printer.
`pO'
String to redirect n characters ofoutput to the printer.
`ps'
String to print the screen on the attached printer.
`rc'
String to move to last saved cursor position.
`RI'
String to move cursor right n columns.
`rp'
String to output character c repeated n times.
`rs'
String to reset the terminal from any strange modes.
`sa'
String to turn on an arbitrary combination of appearance modes.
`sc'
String to save the current cursor position.
`se'
String to leave standout mode.
`sf'
String to scroll the screen one line up.
`SF'
String to scroll the screen n lines up.
`sg'
Number: width of magic standout cookie. Absent if magic cookies are not used.
`so'
String to enter standout mode.
`sr'
String to scroll the screen one line down.
`SR'
String to scroll the screen n line down.
`st'
String to set tab stop at current cursor column on all lines. programs.
`ta'
String to move the cursor right to the next hardware tab stop column.
`te'
String to return terminal to settings for sequential output.
`ti'
String to initialize terminal for random cursor motion.
`ts'
String to move the terminal cursor into the status line.
`uc'
String to underline one character and move cursor right.
`ue'
String to turn off underline mode
`ug'
Number: width of underlining magic cookie. Absent if underlining doesn't use magic cookies.
`ul'
Flag: underline by overstriking with an underscore.
`up'
String to move the cursor vertically up one line.
`UP'
String to move cursor vertically up n lines.
`us'
String to turn on underline mode
`vb'
String to make the screen flash.
`ve'
String to return the cursor to normal.
`vi'
String to make the cursor invisible.
`vs'
String to enhance the cursor.
`wi'
String to set the terminal output screen window.
`ws'
Number: the width of the status line.
`xb'
Flag: superbee terminal.
`xn'
Flag: cursor wraps in a strange way.
`xs'
Flag: clearing a line is the only way to clear the appearance modes of positions in that line (or, only way to remove magic cookies on that line).
`xt'
Flag: Teleray 1061; several strange characteristics.

Variable and Function Index

Jump to: b - o - p - t - u

b

  • BC

    • o

  • ospeed

    • p

  • PC

    • t

  • tgetent
  • tgetflag
  • tgetnum
  • tgetstr
  • tgoto
  • tparam
  • tputs

    • u

  • UP

    • Capability Index

    Jump to: a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - r - s - t - u - v - w - x

    a

  • ae
  • AL
  • al
  • am
  • as

    • b

  • bc
  • bl
  • bs
  • bt
  • bw

    • c

  • CC
  • cd
  • ce
  • ch
  • cl
  • cm
  • CM
  • co
  • cr
  • cS
  • cs
  • ct
  • cv

    • d

  • da
  • dB
  • db
  • DC
  • dC
  • dc
  • dF
  • DL
  • dl
  • dm
  • dN
  • DO
  • do
  • ds
  • dT

    • e

  • ec
  • ed
  • ei
  • eo
  • es

    • f

  • ff
  • fs

    • g

  • gn

    • h

  • hc
  • hd
  • ho
  • hs
  • hu
  • hz

    • i

  • i1
  • i3
  • IC
  • ic
  • if
  • im
  • in
  • ip
  • is
  • it

    • k

  • K1...K5
  • k1...k9
  • kA...kT
  • ka...ku
  • km

    • l

  • l0...l9
  • LE
  • le
  • li
  • ll
  • lm
  • LP

    • m

  • mb
  • md
  • me
  • mh
  • mi
  • mk
  • mm
  • mo
  • mp
  • mr
  • ms, ms

    • n

  • nc
  • nd
  • NF
  • nl
  • ns
  • nw

    • o

  • os

    • p

  • pb
  • pc
  • pf
  • pO
  • po
  • ps

    • r

  • rc
  • RI
  • rp
  • rs

    • s

  • sa
  • sc
  • se
  • sf
  • SF
  • sg
  • so
  • SR
  • sr
  • st

    • t

  • ta
  • te
  • ti
  • ts

    • u

  • uc
  • ue
  • ug
  • ul
  • UP
  • up
  • us

    • v

  • vb
  • ve
  • vi
  • vs

    • w

  • wi
  • ws

    • x

  • xb
  • xn
  • xs
  • xt, xt

    • Concept Index

    Jump to: % - a - b - c - d - e - g - h - i - l - m - n - o - p - r - s - t - u - v - w

    %

  • %

    • a

  • appearance modes

    • b

  • bell

    • c

  • clearing the screen
  • command character
  • cursor motion

    • d

  • delete character
  • delete line
  • delete mode
  • description format

    • e

  • erasing

    • g

  • generic terminal type

    • h

  • home position

    • i

  • inheritance
  • initialization
  • insert character
  • insert line
  • insert mode

    • l

  • line speed

    • m

  • magic cookie
  • meta key

    • n

  • names of terminal types

    • o

  • overstrike

    • p

  • padding, padding
  • parameters
  • printer

    • r

  • repeat output
  • reset

    • s

  • screen size, screen size, screen size
  • scrolling
  • standout
  • status line
  • Superbee

    • t

  • tab stops
  • termcap
  • terminal flags (kernel)

    • u

  • underlining

    • v

  • visibility
  • visible bell

    • w

  • window
  • wrapping, wrapping

    • This document was generated on 7 November 1998 using the texi2html translator version 1.52.


Texinfo

The GNU Documentation Format

for Texinfo version 3.12

February 1998

Robert J. Chassell
Richard M. Stallman

Texinfo Copying Conditions

The programs currently being distributed that relate to Texinfo include portions of GNU Emacs, plus other separate programs (including makeinfo, info, texindex, and `texinfo.tex'). These programs are free; this means that everyone is free to use them and free to redistribute them on a free basis. The Texinfo-related programs are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of the programs that relate to Texinfo, that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the Texinfo related programs, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to Texinfo. If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.

The precise conditions of the licenses for the programs currently being distributed that relate to Texinfo are found in the General Public Licenses that accompany them.

Overview of Texinfo

Texinfo (1) is a documentation system that uses a single source file to produce both on-line information and printed output. This means that instead of writing two different documents, one for the on-line help or other on-line information and the other for a typeset manual or other printed work, you need write only one document. When the work is revised, you need revise only one document. (You can read the on-line information, known as an Info file, with an Info documentation-reading program.)

    or an Info file.
  • Info Files: What is an Info file?
  • Printed Books: Characteristics of a printed book or manual.
  • Formatting Commands: @-commands are used for formatting.
  • Conventions: General rules for writing a Texinfo file.
  • Comments: How to write comments and mark regions that the formatting commands will ignore.
  • Minimum: What a Texinfo file must have.
  • Six Parts: Usually, a Texinfo file has six parts.
  • Short Sample: A short sample Texinfo file.
  • Acknowledgements

Using Texinfo, you can create a printed document with the normal features of a book, including chapters, sections, cross references, and indices. From the same Texinfo source file, you can create a menu-driven, on-line Info file with nodes, menus, cross references, and indices. You can, if you wish, make the chapters and sections of the printed document correspond to the nodes of the on-line information; and you use the same cross references and indices for both the Info file and the printed work. The GNU Emacs Manual is a good example of a Texinfo file, as is this manual.

To make a printed document, you process a Texinfo source file with the TeX typesetting program. This creates a DVI file that you can typeset and print as a book or report. (Note that the Texinfo language is completely different from TeX's usual language, plain TeX.) If you do not have TeX, but do have troff or nroff, you can use the texi2roff program instead.

To make an Info file, you process a Texinfo source file with the makeinfo utility or Emacs's texinfo-format-buffer command; this creates an Info file that you can install on-line.

TeX and texi2roff work with many types of printers; similarly, Info works with almost every type of computer terminal. This power makes Texinfo a general purpose system, but brings with it a constraint, which is that a Texinfo file may contain only the customary "typewriter" characters (letters, numbers, spaces, and punctuation marks) but no special graphics.

A Texinfo file is a plain ASCII file containing text and @-commands (words preceded by an `@') that tell the typesetting and formatting programs what to do. You may edit a Texinfo file with any text editor; but it is especially convenient to use GNU Emacs since that editor has a special mode, called Texinfo mode, that provides various Texinfo-related features. (See section Using Texinfo Mode.)

Before writing a Texinfo source file, you should become familiar with the Info documentation reading program and learn about nodes, menus, cross references, and the rest. (See Info file `info', node `Top', for more information.)

You can use Texinfo to create both on-line help and printed manuals; moreover, Texinfo is freely redistributable. For these reasons, Texinfo is the format in which documentation for GNU utilities and libraries is written.

Info files

An Info file is a Texinfo file formatted so that the Info documentation reading program can operate on it. (makeinfo and texinfo-format-buffer are two commands that convert a Texinfo file into an Info file.)

Info files are divided into pieces called nodes, each of which contains the discussion of one topic. Each node has a name, and contains both text for the user to read and pointers to other nodes, which are identified by their names. The Info program displays one node at a time, and provides commands with which the user can move to other related nodes.

Each node of an Info file may have any number of child nodes that describe subtopics of the node's topic. The names of child nodes are listed in a menu within the parent node; this allows you to use certain Info commands to move to one of the child nodes. Generally, an Info file is organized like a book. If a node is at the logical level of a chapter, its child nodes are at the level of sections; likewise, the child nodes of sections are at the level of subsections.

All the children of any one parent are linked together in a bidirectional chain of `Next' and `Previous' pointers. The `Next' pointer provides a link to the next section, and the `Previous' pointer provides a link to the previous section. This means that all the nodes that are at the level of sections within a chapter are linked together. Normally the order in this chain is the same as the order of the children in the parent's menu. Each child node records the parent node name as its `Up' pointer. The last child has no `Next' pointer, and the first child has the parent both as its `Previous' and as its `Up' pointer.(2)

The book-like structuring of an Info file into nodes that correspond to chapters, sections, and the like is a matter of convention, not a requirement. The `Up', `Previous', and `Next' pointers of a node can point to any other nodes, and a menu can contain any other nodes. Thus, the node structure can be any directed graph. But it is usually more comprehensible to follow a structure that corresponds to the structure of chapters and sections in a printed book or report.

In addition to menus and to `Next', `Previous', and `Up' pointers, Info provides pointers of another kind, called references, that can be sprinkled throughout the text. This is usually the best way to represent links that do not fit a hierarchical structure.

Usually, you will design a document so that its nodes match the structure of chapters and sections in the printed output. But occasionally there are times when this is not right for the material being discussed. Therefore, Texinfo uses separate commands to specify the node structure for the Info file and the section structure for the printed output.

Generally, you enter an Info file through a node that by convention is named `Top'. This node normally contains just a brief summary of the file's purpose, and a large menu through which the rest of the file is reached. From this node, you can either traverse the file systematically by going from node to node, or you can go to a specific node listed in the main menu, or you can search the index menus and then go directly to the node that has the information you want. Alternatively, with the standalone Info program, you can specify specific menu items on the command line (see section `Top' in Info).

If you want to read through an Info file in sequence, as if it were a printed manual, you can hit SPC repeatedly, or you get the whole file with the advanced Info command g *. (See Info file `info', node `Expert'.)

The `dir' file in the `info' directory serves as the departure point for the whole Info system. From it, you can reach the `Top' nodes of each of the documents in a complete Info system.

Printed Books

A Texinfo file can be formatted and typeset as a printed book or manual. To do this, you need TeX, a powerful, sophisticated typesetting program written by Donald Knuth.(3)

A Texinfo-based book is similar to any other typeset, printed work: it can have a title page, copyright page, table of contents, and preface, as well as chapters, numbered or unnumbered sections and subsections, page headers, cross references, footnotes, and indices.

You can use Texinfo to write a book without ever having the intention of converting it into on-line information. You can use Texinfo for writing a printed novel, and even to write a printed memo, although this latter application is not recommended since electronic mail is so much easier.

TeX is a general purpose typesetting program. Texinfo provides a file called `texinfo.tex' that contains information (definitions or macros) that TeX uses when it typesets a Texinfo file. (`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX commands, which TeX can then process to create the typeset document.) `texinfo.tex' contains the specifications for printing a document.

Most often, documents are printed on 8.5 inch by 11 inch pages (216mm by 280mm; this is the default size), but you can also print for 7 inch by 9.25 inch pages (178mm by 235mm; the @smallbook size) or on European A4 size paper (@afourpaper). (See section Printing "Small" Books. Also, see section Printing on A4 Paper.)

By changing the parameters in `texinfo.tex', you can change the size of the printed document. In addition, you can change the style in which the printed document is formatted; for example, you can change the sizes and fonts used, the amount of indentation for each paragraph, the degree to which words are hyphenated, and the like. By changing the specifications, you can make a book look dignified, old and serious, or light-hearted, young and cheery.

TeX is freely distributable. It is written in a superset of Pascal called WEB and can be compiled either in Pascal or (by using a conversion program that comes with the TeX distribution) in C. (See section `TeX Mode' in The GNU Emacs Manual, for information about TeX.)

TeX is very powerful and has a great many features. Because a Texinfo file must be able to present information both on a character-only terminal in Info form and in a typeset book, the formatting commands that Texinfo supports are necessarily limited.

See section How to Obtain TeX.

@-commands

In a Texinfo file, the commands that tell TeX how to typeset the printed manual and tell makeinfo and texinfo-format-buffer how to create an Info file are preceded by `@'; they are called @-commands. For example, @node is the command to indicate a node and @chapter is the command to indicate the start of a chapter.

Please note: All the @-commands, with the exception of the @TeX{} command, must be written entirely in lower case.

The Texinfo @-commands are a strictly limited set of constructs. The strict limits make it possible for Texinfo files to be understood both by TeX and by the code that converts them into Info files. You can display Info files on any terminal that displays alphabetic and numeric characters. Similarly, you can print the output generated by TeX on a wide variety of printers.

Depending on what they do or what arguments(4) they take, you need to write @-commands on lines of their own or as part of sentences:

  • Write a command such as @noindent at the beginning of a line as the only text on the line. (@noindent prevents the beginning of the next line from being indented as the beginning of a paragraph.)
  • Write a command such as @chapter at the beginning of a line followed by the command's arguments, in this case the chapter title, on the rest of the line. (@chapter creates chapter titles.)
  • Write a command such as @dots{} wherever you wish but usually within a sentence. (@dots{} creates dots ...)
  • Write a command such as @code{sample-code} wherever you wish (but usually within a sentence) with its argument, sample-code in this example, between the braces. (@code marks text as being code.)
  • Write a command such as @example at the beginning of a line of its own; write the body-text on following lines; and write the matching @end command, @end example in this case, at the beginning of a line of its own after the body-text. (@example ... @end example indents and typesets body-text as an example.)

As a general rule, a command requires braces if it mingles among other text; but it does not need braces if it starts a line of its own. The non-alphabetic commands, such as @:, are exceptions to the rule; they do not need braces.

As you gain experience with Texinfo, you will rapidly learn how to write the different commands: the different ways to write commands make it easier to write and read Texinfo files than if all commands followed exactly the same syntax. (For details about @-command syntax, see section @-Command Syntax.)

General Syntactic Conventions

All printable ASCII characters except `@', `{' and `}' can appear in a Texinfo file and stand for themselves. `@' is the escape character which introduces commands. `{' and `}' should be used only to surround arguments to certain commands. To put one of these special characters into the document, put an `@' character in front of it, like this: `@@', `@{', and `@}'.

It is customary in TeX to use doubled single-quote characters to begin and end quotations: @tt{ " } and @w{@tt{ " }}. This convention should be followed in Texinfo files. TeX converts doubled single-quote characters to left- and right-hand doubled quotation marks, "like this", and Info converts doubled single-quote characters to ASCII double-quotes: @tt{ " } and @tt{ " } to @w{@tt{ " }}.

Use three hyphens in a row, `---', for a dash--like this. In TeX, a single or double hyphen produces a printed dash that is shorter than the usual typeset dash. Info reduces three hyphens to two for display on the screen.

To prevent a paragraph from being indented in the printed manual, put the command @noindent on a line by itself before the paragraph.

If you mark off a region of the Texinfo file with the @iftex and @end iftex commands, that region will appear only in the printed copy; in that region, you can use certain commands borrowed from plain TeX that you cannot use in Info. Likewise, if you mark off a region with the @ifinfo and @end ifinfo commands, that region will appear only in the Info file; in that region, you can use Info commands that you cannot use in TeX. Similarly for @ifhtml ... @end ifhtml, @ifnothtml ... @end ifnothtml, @ifnotinfo ... @end ifnotinfo, @ifnottex ... @end ifnottex, See section Conditionally Visible Text.

Caution: Do not use tabs in a Texinfo file! TeX uses variable-width fonts, which means that it cannot predefine a tab to work in all circumstances. Consequently, TeX treats tabs like single spaces, and that is not what they look like. Furthermore, makeinfo does nothing special with tabs, and thus a tab character in your input file may appear differently in the output.

To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple spaces when you press the TAB key.

Also, you can run untabify in Emacs to convert tabs in a region to multiple spaces.

Don't use tabs.

Comments

You can write comments in a Texinfo file that will not appear in either the Info file or the printed manual by using the @comment command (which may be abbreviated to @c). Such comments are for the person who reads the Texinfo file. All the text on a line that follows either @comment or @c is a comment; the rest of the line does not appear in either the Info file or the printed manual. (Often, you can write the @comment or @c in the middle of a line, and only the text that follows after the @comment or @c command does not appear; but some commands, such as @settitle and @setfilename, work on a whole line. You cannot use @comment or @c in a line beginning with such a command.)

You can write long stretches of text that will not appear in either the Info file or the printed manual by using the @ignore and @end ignore commands. Write each of these commands on a line of its own, starting each command at the beginning of the line. Text between these two commands does not appear in the processed output. You can use @ignore and @end ignore for writing comments. Often, @ignore and @end ignore is used to enclose a part of the copying permissions that applies to the Texinfo source file of a document, but not to the Info or printed version of the document.

What a Texinfo File Must Have

By convention, the names of Texinfo files end with one of the extensions `.texinfo', `.texi', or `.tex'. The longer extension is preferred since it describes more clearly to a human reader the nature of the file. The shorter extensions are for operating systems that cannot handle long file names.

In order to be made into a printed manual and an Info file, a Texinfo file must begin with lines like this:

\input texinfo
@setfilename info-file-name
@settitle name-of-manual

The contents of the file follow this beginning, and then you must end a Texinfo file with a line like this:

@bye

The `\input texinfo' line tells TeX to use the `texinfo.tex' file, which tells TeX how to translate the Texinfo @-commands into TeX typesetting commands. (Note the use of the backslash, `\'; this is correct for TeX.) The `@setfilename' line provides a name for the Info file and tells TeX to open auxiliary files. The `@settitle' line specifies a title for the page headers (or footers) of the printed manual.

The @bye line at the end of the file on a line of its own tells the formatters that the file is ended and to stop formatting.

Usually, you will not use quite such a spare format, but will include mode setting and start-of-header and end-of-header lines at the beginning of a Texinfo file, like this:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename info-file-name
@settitle name-of-manual
@c %**end of header

In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo mode when you edit the file.

The @c lines which surround the `@setfilename' and `@settitle' lines are optional, but you need them in order to run TeX or Info on just part of the file. (See section Start of Header, for more information.)

Furthermore, you will usually provide a Texinfo file with a title page, indices, and the like. But the minimum, which can be useful for short documents, is just the three lines at the beginning and the one line at the end.

Six Parts of a Texinfo File

Generally, a Texinfo file contains more than the minimal beginning and end--it usually contains six parts:

1. Header
The Header names the file, tells TeX which definitions' file to use, and performs other "housekeeping" tasks.
2. Summary Description and Copyright
The Summary Description and Copyright segment describes the document and contains the copyright notice and copying permissions for the Info file. The segment must be enclosed between @ifinfo and @end ifinfo commands so that the formatters place it only in the Info file.
3. Title and Copyright
The Title and Copyright segment contains the title and copyright pages and copying permissions for the printed manual. The segment must be enclosed between @titlepage and @end titlepage commands. The title and copyright page appear only in the printed manual.
4. `Top' Node and Master Menu
The Master Menu contains a complete menu of all the nodes in the whole Info file. It appears only in the Info file, in the `Top' node.
5. Body
The Body of the document may be structured like a traditional book or encyclopedia or it may be free form.
6. End
The End contains commands for printing indices and generating the table of contents, and the @bye command on a line of its own.

A Short Sample Texinfo File

Here is a complete but very short Texinfo file, in six parts. The first three parts of the file, from `\input texinfo' through to `@end titlepage', look more intimidating than they are. Most of the material is standard boilerplate; when you write a manual, simply insert the names for your own manual in this segment. (See section Beginning a Texinfo File.)

In the following, the sample text is indented; comments on it are not. The complete file, without any comments, is shown in section A Sample Texinfo File.

Part 1: Header

The header does not appear in either the Info file or the printed output. It sets various parameters, including the name of the Info file and the title used in the header.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header

@setchapternewpage odd

Part 2: Summary Description and Copyright

The summary description and copyright segment does not appear in the printed document.

@ifinfo
This is a short example of a complete Texinfo file.

Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end ifinfo

Part 3: Titlepage and Copyright

The titlepage segment does not appear in the Info file.

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

Part 4: `Top' Node and Master Menu

The `Top' node contains the master menu for the Info file. Since a printed manual uses a table of contents rather than a menu, the master menu appears only in the Info file.

@node    Top,       First Chapter, ,         (dir)
@comment node-name, next,          previous, up

@menu
* First Chapter::    The first chapter is the
                     only chapter in this sample.
* Concept Index::    This index has two entries.
@end menu

Part 5: The Body of the Document

The body segment contains all the text of the document, but not the indices or table of contents. This example illustrates a node and a chapter containing an enumerated list.

@node    First Chapter, Concept Index, Top,      Top
@comment node-name,     next,          previous, up
@chapter First Chapter
@cindex Sample index entry

This is the contents of the first chapter.
@cindex Another sample index entry

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @code{makeinfo} and @code{texinfo-format-buffer}
commands transform a Texinfo file such as this into
an Info file; and @TeX{} typesets it for a printed
manual.

Part 6: The End of the Document

The end segment contains commands both for generating an index in a node and unnumbered chapter of its own and for generating the table of contents; and it contains the @bye command that marks the end of the document.

@node    Concept Index,    ,  First Chapter, Top
@comment node-name,    next,  previous,      up
@unnumbered Concept Index

@printindex cp

@contents
@bye

The Results

Here is what the contents of the first chapter of the sample look like:

This is the contents of the first chapter.

Here is a numbered list.

  1. This is the first item.
  2. This is the second item.

The makeinfo and texinfo-format-buffer commands transform a Texinfo file such as this into an Info file; and TeX typesets it for a printed manual.

Acknowledgements

Richard M. Stallman wrote Edition 1.0 of this manual. Robert J. Chassell revised and extended it, starting with Edition 1.1. Karl Berry made updates for the Texinfo 3.8 and subsequent releases, starting with Edition 2.22.

Our thanks go out to all who helped improve this work, particularly to Fran@,{c}ois Pinard and David D. Zuhn, who tirelessly recorded and reported mistakes and obscurities; our special thanks go to Melissa Weisshaus for her frequent and often tedious reviews of nearly similar editions. Our mistakes are our own.

Please send suggestions and corrections to:

Internet address:
    bug-texinfo@gnu.org

Please include the manual's edition number and update date in your messages.

Using Texinfo Mode

You may edit a Texinfo file with any text editor you choose. A Texinfo file is no different from any other ASCII file. However, GNU Emacs comes with a special mode, called Texinfo mode, that provides Emacs commands and tools to help ease your work.

This chapter describes features of GNU Emacs' Texinfo mode but not any features of the Texinfo formatting language. If you are reading this manual straight through from the beginning, you may want to skim through this chapter briefly and come back to it after reading succeeding chapters which describe the Texinfo formatting language in detail.

  • Emacs Editing: Texinfo mode adds to GNU Emacs' general purpose editing features.
  • Inserting: How to insert frequently used @-commands.
  • Showing the Structure: How to show the structure of a file.
  • Updating Nodes and Menus: How to update or create new nodes and menus.
  • Info Formatting: How to format for Info.
  • Printing: How to format and print part or all of a file.
  • Texinfo Mode Summary: Summary of all the Texinfo mode commands.

Texinfo mode provides special features for working with Texinfo files:

  • Insert frequently used @-commands.
  • Automatically create @node lines.
  • Show the structure of a Texinfo source file.
  • Automatically create or update the `Next', `Previous', and `Up' pointers of a node.
  • Automatically create or update menus.
  • Automatically create a master menu.
  • Format a part or all of a file for Info.
  • Typeset and print part or all of a file.

Perhaps the two most helpful features are those for inserting frequently used @-commands and for creating node pointers and menus.

The Usual GNU Emacs Editing Commands

In most cases, the usual Text mode commands work the same in Texinfo mode as they do in Text mode. Texinfo mode adds new editing commands and tools to GNU Emacs' general purpose editing features. The major difference concerns filling. In Texinfo mode, the paragraph separation variable and syntax table are redefined so that Texinfo commands that should be on lines of their own are not inadvertently included in paragraphs. Thus, the M-q (fill-paragraph) command will refill a paragraph but not mix an indexing command on a line adjacent to it into the paragraph.

In addition, Texinfo mode sets the page-delimiter variable to the value of texinfo-chapter-level-regexp; by default, this is a regular expression matching the commands for chapters and their equivalents, such as appendices. With this value for the page delimiter, you can jump from chapter title to chapter title with the C-x ] (forward-page) and C-x [ (backward-page) commands and narrow to a chapter with the C-x p (narrow-to-page) command. (See section `Pages' in The GNU Emacs Manual, for details about the page commands.)

You may name a Texinfo file however you wish, but the convention is to end a Texinfo file name with one of the three extensions `.texinfo', `.texi', or `.tex'. A longer extension is preferred, since it is explicit, but a shorter extension may be necessary for operating systems that limit the length of file names. GNU Emacs automatically enters Texinfo mode when you visit a file with a `.texinfo' or `.texi' extension. Also, Emacs switches to Texinfo mode when you visit a file that has `-*-texinfo-*-' in its first line. If ever you are in another mode and wish to switch to Texinfo mode, type M-x texinfo-mode.

Like all other Emacs features, you can customize or enhance Texinfo mode as you wish. In particular, the keybindings are very easy to change. The keybindings described here are the default or standard ones.

Inserting Frequently Used Commands

Texinfo mode provides commands to insert various frequently used @-commands into the buffer. You can use these commands to save keystrokes.

The insert commands are invoked by typing C-c twice and then the first letter of the @-command:

C-c C-c c
M-x texinfo-insert-@code
Insert @code{} and put the cursor between the braces.
C-c C-c d
M-x texinfo-insert-@dfn
Insert @dfn{} and put the cursor between the braces.
C-c C-c e
M-x texinfo-insert-@end
Insert @end and attempt to insert the correct following word, such as `example' or `table'. (This command does not handle nested lists correctly, but inserts the word appropriate to the immediately preceding list.)
C-c C-c i
M-x texinfo-insert-@item
Insert @item and put the cursor at the beginning of the next line.
C-c C-c k
M-x texinfo-insert-@kbd
Insert @kbd{} and put the cursor between the braces.
C-c C-c n
M-x texinfo-insert-@node
Insert @node and a comment line listing the sequence for the `Next', `Previous', and `Up' nodes. Leave point after the @node.
C-c C-c o
M-x texinfo-insert-@noindent
Insert @noindent and put the cursor at the beginning of the next line.
C-c C-c s
M-x texinfo-insert-@samp
Insert @samp{} and put the cursor between the braces.
C-c C-c t
M-x texinfo-insert-@table
Insert @table followed by a SPC and leave the cursor after the SPC.
C-c C-c v
M-x texinfo-insert-@var
Insert @var{} and put the cursor between the braces.
C-c C-c x
M-x texinfo-insert-@example
Insert @example and put the cursor at the beginning of the next line.
C-c C-c {
M-x texinfo-insert-braces
Insert {} and put the cursor between the braces.
C-c C-c }
C-c C-c ]
M-x up-list
Move from between a pair of braces forward past the closing brace. Typing C-c C-c ] is easier than typing C-c C-c }, which is, however, more mnemonic; hence the two keybindings. (Also, you can move out from between braces by typing C-f.)

To put a command such as @code{...} around an existing word, position the cursor in front of the word and type C-u 1 C-c C-c c. This makes it easy to edit existing plain text. The value of the prefix argument tells Emacs how many words following point to include between braces---`1' for one word, `2' for two words, and so on. Use a negative argument to enclose the previous word or words. If you do not specify a prefix argument, Emacs inserts the @-command string and positions the cursor between the braces. This feature works only for those @-commands that operate on a word or words within one line, such as @kbd and @var.

This set of insert commands was created after analyzing the frequency with which different @-commands are used in the GNU Emacs Manual and the GDB Manual. If you wish to add your own insert commands, you can bind a keyboard macro to a key, use abbreviations, or extend the code in `texinfo.el'.

C-c C-c C-d (texinfo-start-menu-description) is an insert command that works differently from the other insert commands. It inserts a node's section or chapter title in the space for the description in a menu entry line. (A menu entry has three parts, the entry name, the node name, and the description. Only the node name is required, but a description helps explain what the node is about. See section The Parts of a Menu.)

To use texinfo-start-menu-description, position point in a menu entry line and type C-c C-c C-d. The command looks for and copies the title that goes with the node name, and inserts the title as a description; it positions point at beginning of the inserted text so you can edit it. The function does not insert the title if the menu entry line already contains a description.

This command is only an aid to writing descriptions; it does not do the whole job. You must edit the inserted text since a title tends to use the same words as a node name but a useful description uses different words.

Showing the Section Structure of a File

You can show the section structure of a Texinfo file by using the C-c C-s command (texinfo-show-structure). This command shows the section structure of a Texinfo file by listing the lines that begin with the @-commands for @chapter, @section, and the like. It constructs what amounts to a table of contents. These lines are displayed in another buffer called the `*Occur*' buffer. In that buffer, you can position the cursor over one of the lines and use the C-c C-c command (occur-mode-goto-occurrence), to jump to the corresponding spot in the Texinfo file.

C-c C-s
M-x texinfo-show-structure
Show the @chapter, @section, and such lines of a Texinfo file.
C-c C-c
M-x occur-mode-goto-occurrence
Go to the line in the Texinfo file corresponding to the line under the cursor in the `*Occur*' buffer.

If you call texinfo-show-structure with a prefix argument by typing C-u C-c C-s, it will list not only those lines with the @-commands for @chapter, @section, and the like, but also the @node lines. (This is how the texinfo-show-structure command worked without an argument in the first version of Texinfo. It was changed because @node lines clutter up the `*Occur*' buffer and are usually not needed.) You can use texinfo-show-structure with a prefix argument to check whether the `Next', `Previous', and `Up' pointers of an @node line are correct.

Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark off the region of the buffer that you are interested in by using the C-x n n (narrow-to-region) command and texinfo-show-structure will work on only that region. To see the whole buffer again, use C-x n w (widen). (See section `Narrowing' in The GNU Emacs Manual, for more information about the narrowing commands.)

In addition to providing the texinfo-show-structure command, Texinfo mode sets the value of the page delimiter variable to match the chapter-level @-commands. This enables you to use the C-x ] (forward-page) and C-x [ (backward-page) commands to move forward and backward by chapter, and to use the C-x p (narrow-to-page) command to narrow to a chapter. See section `Pages' in The GNU Emacs Manual, for more information about the page commands.

Updating Nodes and Menus

Texinfo mode provides commands for automatically creating or updating menus and node pointers. The commands are called "update" commands because their most frequent use is for updating a Texinfo file after you have worked on it; but you can use them to insert the `Next', `Previous', and `Up' pointers into an @node line that has none and to create menus in a file that has none.

If you do not use the updating commands, you need to write menus and node pointers by hand, which is a tedious task.

  • Updating Requirements: How to structure a Texinfo file for using the updating command.
  • Other Updating Commands: How to indent descriptions, insert missing nodes lines, and update nodes in sequence.

You can use the updating commands

  • to insert or update the `Next', `Previous', and `Up' pointers of a node,
  • to insert or update the menu for a section, and
  • to create a master menu for a Texinfo source file.

You can also use the commands to update all the nodes and menus in a region or in a whole Texinfo file.

The updating commands work only with conventional Texinfo files, which are structured hierarchically like books. In such files, a structuring command line must follow closely after each @node line, except for the `Top' @node line. (A structuring command line is a line beginning with @chapter, @section, or other similar command.)

You can write the structuring command line on the line that follows immediately after an @node line or else on the line that follows after a single @comment line or a single @ifinfo line. You cannot interpose more than one line between the @node line and the structuring command line; and you may interpose only an @comment line or an @ifinfo line.

Commands which work on a whole buffer require that the `Top' node be followed by a node with an @chapter or equivalent-level command. Note that the menu updating commands will not create a main or master menu for a Texinfo file that has only @chapter-level nodes! The menu updating commands only create menus within nodes for lower level nodes. To create a menu of chapters, you must provide a `Top' node.

The menu updating commands remove menu entries that refer to other Info files since they do not refer to nodes within the current buffer. This is a deficiency. Rather than use menu entries, you can use cross references to refer to other Info files. None of the updating commands affect cross references.

Texinfo mode has five updating commands that are used most often: two are for updating the node pointers or menu of a single node (or a region); two are for updating every node pointer and menu in a file; and one, the texinfo-master-menu command, is for creating a master menu for a complete file, and optionally, for updating every node and menu in the whole Texinfo file.

The texinfo-master-menu command is the primary command:

C-c C-u m
M-x texinfo-master-menu
Create or update a master menu that includes all the other menus (incorporating the descriptions from pre-existing menus, if any). With an argument (prefix argument, C-u, if interactive), first create or update all the nodes and all the regular menus in the buffer before constructing the master menu. (See section The `Top' Node and Master Menu, for more about a master menu.) For texinfo-master-menu to work, the Texinfo file must have a `Top' node and at least one subsequent node. After extensively editing a Texinfo file, you can type the following:
C-u M-x texinfo-master-menu
or
C-u C-c C-u m
This updates all the nodes and menus completely and all at once.

The other major updating commands do smaller jobs and are designed for the person who updates nodes and menus as he or she writes a Texinfo file.

The commands are:

C-c C-u C-n
M-x texinfo-update-node
Insert the `Next', `Previous', and `Up' pointers for the node that point is within (i.e., for the @node line preceding point). If the @node line has pre-existing `Next', `Previous', or `Up' pointers in it, the old pointers are removed and new ones inserted. With an argument (prefix argument, C-u, if interactive), this command updates all @node lines in the region (which is the text between point and mark).
C-c C-u C-m
M-x texinfo-make-menu
Create or update the menu in the node that point is within. With an argument (C-u as prefix argument, if interactive), the command makes or updates menus for the nodes which are either within or a part of the region. Whenever texinfo-make-menu updates an existing menu, the descriptions from that menu are incorporated into the new menu. This is done by copying descriptions from the existing menu to the entries in the new menu that have the same node names. If the node names are different, the descriptions are not copied to the new menu.
C-c C-u C-e
M-x texinfo-every-node-update
Insert or update the `Next', `Previous', and `Up' pointers for every node in the buffer.
C-c C-u C-a
M-x texinfo-all-menus-update
Create or update all the menus in the buffer. With an argument (C-u as prefix argument, if interactive), first insert or update all the node pointers before working on the menus. If a master menu exists, the texinfo-all-menus-update command updates it; but the command does not create a new master menu if none already exists. (Use the texinfo-master-menu command for that.) When working on a document that does not merit a master menu, you can type the following:
C-u C-c C-u C-a
or
C-u M-x texinfo-all-menus-update
This updates all the nodes and menus.

The texinfo-column-for-description variable specifies the column to which menu descriptions are indented. By default, the value is 32 although it is often useful to reduce it to as low as 24. You can set the variable with the M-x edit-options command (see section `Editing Variable Values' in The GNU Emacs Manual) or with the M-x set-variable command (see section `Examining and Setting Variables' in The GNU Emacs Manual).

Also, the texinfo-indent-menu-description command may be used to indent existing menu descriptions to a specified column. Finally, if you wish, you can use the texinfo-insert-node-lines command to insert missing @node lines into a file. (See section Other Updating Commands, for more information.)

Updating Requirements

To use the updating commands, you must organize the Texinfo file hierarchically with chapters, sections, subsections, and the like. When you construct the hierarchy of the manual, do not `jump down' more than one level at a time: you can follow the `Top' node with a chapter, but not with a section; you can follow a chapter with a section, but not with a subsection. However, you may `jump up' any number of levels at one time--for example, from a subsection to a chapter.

Each @node line, with the exception of the line for the `Top' node, must be followed by a line with a structuring command such as @chapter, @section, or @unnumberedsubsec.

Each @node line/structuring-command line combination must look either like this:

@node     Comments,  Minimum, Conventions, Overview
@comment  node-name, next,    previous,    up
@section Comments

or like this (without the @comment line):

@node Comments, Minimum, Conventions, Overview
@section Comments

In this example, `Comments' is the name of both the node and the section. The next node is called `Minimum' and the previous node is called `Conventions'. The `Comments' section is within the `Overview' node, which is specified by the `Up' pointer. (Instead of an @comment line, you can write an @ifinfo line.)

If a file has a `Top' node, it must be called `top' or `Top' and be the first node in the file.

The menu updating commands create a menu of sections within a chapter, a menu of subsections within a section, and so on. This means that you must have a `Top' node if you want a menu of chapters.

Incidentally, the makeinfo command will create an Info file for a hierarchically organized Texinfo file that lacks `Next', `Previous' and `Up' pointers. Thus, if you can be sure that your Texinfo file will be formatted with makeinfo, you have no need for the `update node' commands. (See section Creating an Info File, for more information about makeinfo.) However, both makeinfo and the texinfo-format-... commands require that you insert menus in the file.

Other Updating Commands

In addition to the five major updating commands, Texinfo mode possesses several less frequently used updating commands:

M-x texinfo-insert-node-lines
Insert @node lines before the @chapter, @section, and other sectioning commands wherever they are missing throughout a region in a Texinfo file. With an argument (C-u as prefix argument, if interactive), the texinfo-insert-node-lines command not only inserts @node lines but also inserts the chapter or section titles as the names of the corresponding nodes. In addition, it inserts the titles as node names in pre-existing @node lines that lack names. Since node names should be more concise than section or chapter titles, you must manually edit node names so inserted. For example, the following marks a whole buffer as a region and inserts @node lines and titles throughout:
C-x h C-u M-x texinfo-insert-node-lines
(Note that this command inserts titles as node names in @node lines; the texinfo-start-menu-description command (see section Inserting Frequently Used Commands) inserts titles as descriptions in menu entries, a different action. However, in both cases, you need to edit the inserted text.)
M-x texinfo-multiple-files-update
Update nodes and menus in a document built from several separate files. With C-u as a prefix argument, create and insert a master menu in the outer file. With a numeric prefix argument, such as C-u 2, first update all the menus and all the `Next', `Previous', and `Up' pointers of all the included files before creating and inserting a master menu in the outer file. The texinfo-multiple-files-update command is described in the appendix on @include files. See section texinfo-multiple-files-update.
M-x texinfo-indent-menu-description
Indent every description in the menu following point to the specified column. You can use this command to give yourself more space for descriptions. With an argument (C-u as prefix argument, if interactive), the texinfo-indent-menu-description command indents every description in every menu in the region. However, this command does not indent the second and subsequent lines of a multi-line description.
M-x texinfo-sequential-node-update
Insert the names of the nodes immediately following and preceding the current node as the `Next' or `Previous' pointers regardless of those nodes' hierarchical level. This means that the `Next' node of a subsection may well be the next chapter. Sequentially ordered nodes are useful for novels and other documents that you read through sequentially. (However, in Info, the g * command lets you look through the file sequentially, so sequentially ordered nodes are not strictly necessary.) With an argument (prefix argument, if interactive), the texinfo-sequential-node-update command sequentially updates all the nodes in the region.

Formatting for Info

Texinfo mode provides several commands for formatting part or all of a Texinfo file for Info. Often, when you are writing a document, you want to format only part of a file--that is, a region.

You can use either the texinfo-format-region or the makeinfo-region command to format a region:

C-c C-e C-r
M-x texinfo-format-region
C-c C-m C-r
M-x makeinfo-region
Format the current region for Info.

You can use either the texinfo-format-buffer or the makeinfo-buffer command to format a whole buffer:

C-c C-e C-b
M-x texinfo-format-buffer
C-c C-m C-b
M-x makeinfo-buffer
Format the current buffer for Info.

For example, after writing a Texinfo file, you can type the following:

C-u C-c C-u m
or
C-u M-x texinfo-master-menu

This updates all the nodes and menus. Then type the following to create an Info file:

C-c C-m C-b
or
M-x makeinfo-buffer

For TeX or the Info formatting commands to work, the file must include a line that has @setfilename in its header.

See section Creating an Info File, for details about Info formatting.

Formatting and Printing

Typesetting and printing a Texinfo file is a multi-step process in which you first create a file for printing (called a DVI file), and then print the file. Optionally, you may also create indices. To do this, you must run the texindex command after first running the tex typesetting command; and then you must run the tex command again. Or else run the texi2dvi command which automatically creates indices as needed (see section Format using texi2dvi).

Often, when you are writing a document, you want to typeset and print only part of a file to see what it will look like. You can use the texinfo-tex-region and related commands for this purpose. Use the texinfo-tex-buffer command to format all of a buffer.

C-c C-t C-b
M-x texinfo-tex-buffer
Run texi2dvi on the buffer. In addition to running TeX on the buffer, this command automatically creates or updates indices as needed.
C-c C-t C-r
M-x texinfo-tex-region
Run TeX on the region.
C-c C-t C-i
M-x texinfo-texindex
Run texindex to sort the indices of a Texinfo file formatted with texinfo-tex-region. The texinfo-tex-region command does not run texindex automatically; it only runs the tex typesetting command. You must run the texinfo-tex-region command a second time after sorting the raw index files with the texindex command. (Usually, you do not format an index when you format a region, only when you format a buffer. Now that the texi2dvi command exists, there is little or no need for this command.)
C-c C-t C-p
M-x texinfo-tex-print
Print the file (or the part of the file) previously formatted with texinfo-tex-buffer or texinfo-tex-region.

For texinfo-tex-region or texinfo-tex-buffer to work, the file must start with a `\input texinfo' line and must include an @settitle line. The file must end with @bye on a line by itself. (When you use texinfo-tex-region, you must surround the @settitle line with start-of-header and end-of-header lines.)

See section Format and Print Hardcopy, for a description of the other TeX related commands, such as tex-show-print-queue.

Texinfo Mode Summary

In Texinfo mode, each set of commands has default keybindings that begin with the same keys. All the commands that are custom-created for Texinfo mode begin with C-c. The keys are somewhat mnemonic.

Insert Commands

The insert commands are invoked by typing C-c twice and then the first letter of the @-command to be inserted. (It might make more sense mnemonically to use C-c C-i, for `custom insert', but C-c C-c is quick to type.)

C-c C-c c       Insert `@code'.
C-c C-c d       Insert `@dfn'.
C-c C-c e       Insert `@end'.
C-c C-c i       Insert `@item'.
C-c C-c n       Insert `@node'.
C-c C-c s       Insert `@samp'.
C-c C-c v       Insert `@var'.
C-c C-c {       Insert braces.
C-c C-c ]
C-c C-c }       Move out of enclosing braces.

C-c C-c C-d     Insert a node's section title
                in the space for the description
                in a menu entry line.

Show Structure

The texinfo-show-structure command is often used within a narrowed region.

C-c C-s         List all the headings.

The Master Update Command

The texinfo-master-menu command creates a master menu; and can be used to update every node and menu in a file as well.

C-c C-u m
M-x texinfo-master-menu
                Create or update a master menu.

C-u C-c C-u m   With C-u as a prefix argument, first
                create or update all nodes and regular
                menus, and then create a master menu.

Update Pointers

The update pointer commands are invoked by typing C-c C-u and then either C-n for texinfo-update-node or C-e for texinfo-every-node-update.

C-c C-u C-n     Update a node.
C-c C-u C-e     Update every node in the buffer.

Update Menus

Invoke the update menu commands by typing C-c C-u and then either C-m for texinfo-make-menu or C-a for texinfo-all-menus-update. To update both nodes and menus at the same time, precede C-c C-u C-a with C-u.

C-c C-u C-m     Make or update a menu.

C-c C-u C-a     Make or update all
                menus in a buffer.

C-u C-c C-u C-a With C-u as a prefix argument,
                first create or update all nodes and
                then create or update all menus.

Format for Info

The Info formatting commands that are written in Emacs Lisp are invoked by typing C-c C-e and then either C-r for a region or C-b for the whole buffer.

The Info formatting commands that are written in C and based on the makeinfo program are invoked by typing C-c C-m and then either C-r for a region or C-b for the whole buffer.

Use the texinfo-format... commands:

C-c C-e C-r     Format the region.
C-c C-e C-b     Format the buffer.

Use makeinfo:

C-c C-m C-r     Format the region.
C-c C-m C-b     Format the buffer.
C-c C-m C-l     Recenter the makeinfo output buffer.
C-c C-m C-k     Kill the makeinfo formatting job.

Typeset and Print

The TeX typesetting and printing commands are invoked by typing C-c C-t and then another control command: C-r for texinfo-tex-region, C-b for texinfo-tex-buffer, and so on.

C-c C-t C-r     Run TeX on the region.
C-c C-t C-b     Run texi2dvi on the buffer.
C-c C-t C-i     Run texindex.
C-c C-t C-p     Print the DVI file.
C-c C-t C-q     Show the print queue.
C-c C-t C-d     Delete a job from the print queue.
C-c C-t C-k     Kill the current TeX formatting job.
C-c C-t C-x     Quit a currently stopped TeX formatting job.
C-c C-t C-l     Recenter the output buffer.

Other Updating Commands

The `other updating commands' do not have standard keybindings because they are rarely used.

M-x texinfo-insert-node-lines
                Insert missing @node lines in region.
                With C-u as a prefix argument,
                use section titles as node names.

M-x texinfo-multiple-files-update
                Update a multi-file document.
                With C-u 2 as a prefix argument,
                create or update all nodes and menus
                in all included files first.

M-x texinfo-indent-menu-description
                Indent descriptions.

M-x texinfo-sequential-node-update
                Insert node pointers in strict sequence.

Beginning a Texinfo File

Certain pieces of information must be provided at the beginning of a Texinfo file, such as the name of the file and the title of the document.

  • Sample Beginning: Here is a sample beginning for a Texinfo file.
  • Header: The very beginning of a Texinfo file.
  • Info Summary and Permissions: Summary and copying permissions for Info.
  • Titlepage & Copyright Page: Creating the title and copyright pages.
  • The Top Node: Creating the `Top' node and master menu.
  • Software Copying Permissions: Ensure that you and others continue to have the right to use and share software.

Generally, the beginning of a Texinfo file has four parts:

  1. The header, delimited by special comment lines, that includes the commands for naming the Texinfo file and telling TeX what definitions file to use when processing the Texinfo file.
  2. A short statement of what the file is about, with a copyright notice and copying permissions. This is enclosed in @ifinfo and @end ifinfo commands so that the formatters place it only in the Info file.
  3. A title page and copyright page, with a copyright notice and copying permissions. This is enclosed between @titlepage and @end titlepage commands. The title and copyright page appear only in the printed manual.
  4. The `Top' node that contains a menu for the whole Info file. The contents of this node appear only in the Info file.

Also, optionally, you may include the copying conditions for a program and a warranty disclaimer. The copying section will be followed by an introduction or else by the first chapter of the manual.

Since the copyright notice and copying permissions for the Texinfo document (in contrast to the copying permissions for a program) are in parts that appear only in the Info file or only in the printed manual, this information must be given twice.

Sample Texinfo File Beginning

The following sample shows what is needed.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename name-of-info-file
@settitle name-of-manual
@setchapternewpage odd
@c %**end of header

@ifinfo
This file documents ...

Copyright year copyright-owner

Permission is granted to ...
@end ifinfo

@c  This title page illustrates only one of the
@c  two methods of forming a title page.

@titlepage
@title name-of-manual-when-printed
@subtitle subtitle-if-any
@subtitle second-subtitle
@author author

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} year copyright-owner

Published by ...

Permission is granted to ...
@end titlepage

@node Top, Overview, , (dir)

@ifinfo
This document describes ...

This document applies to version ...
of the program named ...
@end ifinfo

@menu
* Copying::          Your rights and freedoms.
* First Chapter::    Getting started ...
* Second Chapter::              ...
  ...
  ...
@end menu

@node    First Chapter, Second Chapter, top,      top
@comment node-name,     next,           previous, up
@chapter First Chapter
@cindex Index entry for First Chapter

The Texinfo File Header

Texinfo files start with at least three lines that provide Info and TeX with necessary information. These are the \input texinfo line, the @settitle line, and the @setfilename line. If you want to run TeX on just a part of the Texinfo File, you must write the @settitle and @setfilename lines between start-of-header and end-of-header lines.

Thus, the beginning of a Texinfo file looks like this:

\input texinfo   @c -*-texinfo-*-
@setfilename sample.info
@settitle Sample Document

or else like this:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header
  • First Line: The first line of a Texinfo file.
  • Start of Header: Formatting a region requires this.
  • setfilename: Tell Info the name of the Info file.
  • settitle: Create a title for the printed work.
  • setchapternewpage: Start chapters on right-hand pages.
  • paragraphindent: An option to specify paragraph indentation.
  • End of Header: Formatting a region requires this.

The First Line of a Texinfo File

Every Texinfo file that is to be the top-level input to TeX must begin with a line that looks like this:

\input texinfo   @c -*-texinfo-*-

This line serves two functions:

  1. When the file is processed by TeX, the `\input texinfo' command tells TeX to load the macros needed for processing a Texinfo file. These are in a file called `texinfo.tex', which is usually located in the `/usr/lib/tex/macros' directory. TeX uses the backslash, `\', to mark the beginning of a command, just as Texinfo uses `@'. The `texinfo.tex' file causes the switch from `\' to `@'; before the switch occurs, TeX requires `\', which is why it appears at the beginning of the file.
  2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode specification tells Emacs to use Texinfo mode.

Start of Header

Write a start-of-header line on the second line of a Texinfo file. Follow the start-of-header line with @setfilename and @settitle lines and, optionally, with other command lines, such as @smallbook or @footnotestyle; and then by an end-of-header line (see section End of Header).

With these lines, you can format part of a Texinfo file for Info or typeset part for printing.

A start-of-header line looks like this:

@c %**start of header

The odd string of characters, `%**', is to ensure that no other comment is accidentally taken for a start-of-header line.

@setfilename

In order to serve as the primary input file for either makeinfo or TeX, a Texinfo file must contain a line that looks like this:

@setfilename info-file-name

Write the @setfilename command at the beginning of a line and follow it on the same line by the Info file name. Do not write anything else on the line; anything on the line after the command is considered part of the file name, including what would otherwise be a comment.

The @setfilename line specifies the name of the Info file to be generated. This name should be different from the name of the Texinfo file. There are two conventions for choosing the name: you can either remove the `.texi' extension from the input file name, or replace it with the `.info' extension.

Some operating systems cannot handle long file names. You can run into a problem even when the file name you specify is itself short enough. This occurs because the Info formatters split a long Info file into short indirect subfiles, and name them by appending `-1', `-2', ..., `-10', `-11', and so on, to the original file name. (See section Tag Files and Split Files.) The subfile name `texinfo.info-10', for example, is too long for some systems; so the Info file name for this document is `texinfo' rather than `texinfo.info'.

The Info formatting commands ignore everything written before the @setfilename line, which is why the very first line of the file (the \input line) does not show up in the output.

The @setfilename line produces no output when you typeset a manual with TeX, but it nevertheless is essential: it opens the index, cross-reference, and other auxiliary files used by Texinfo, and also reads `texinfo.cnf' if that file is present on your system (see section Preparing to Use TeX).

@settitle

In order to be made into a printed manual, a Texinfo file must contain a line that looks like this:

@settitle title

Write the @settitle command at the beginning of a line and follow it on the same line by the title. This tells TeX the title to use in a header or footer. Do not write anything else on the line; anything on the line after the command is considered part of the title, including a comment.

Conventionally, when TeX formats a Texinfo file for double-sided output, the title is printed in the left-hand (even-numbered) page headings and the current chapter title is printed in the right-hand (odd-numbered) page headings. (TeX learns the title of each chapter from each @chapter command.) Page footers are not printed.

Even if you are printing in a single-sided style, TeX looks for an @settitle command line, in case you include the manual title in the heading.

The @settitle command should precede everything that generates actual output in TeX.

Although the title in the @settitle command is usually the same as the title on the title page, it does not affect the title as it appears on the title page. Thus, the two do not need not match exactly; and the title in the @settitle command can be a shortened or expanded version of the title as it appears on the title page. (See section @titlepage.)

TeX prints page headings only for that text that comes after the @end titlepage command in the Texinfo file, or that comes after an @headings command that turns on headings. (See section The @headings Command, for more information.)

You may, if you wish, create your own, customized headings and footings. See section Page Headings, for a detailed discussion of this process.

@setchapternewpage

In a book or a manual, text is usually printed on both sides of the paper, chapters start on right-hand pages, and right-hand pages have odd numbers. But in short reports, text often is printed only on one side of the paper. Also in short reports, chapters sometimes do not start on new pages, but are printed on the same page as the end of the preceding chapter, after a small amount of vertical whitespace.

You can use the @setchapternewpage command with various arguments to specify how TeX should start chapters and whether it should typeset pages for printing on one or both sides of the paper (single-sided or double-sided printing).

Write the @setchapternewpage command at the beginning of a line followed by its argument.

For example, you would write the following to cause each chapter to start on a fresh odd-numbered page:

@setchapternewpage odd

You can specify one of three alternatives with the @setchapternewpage command:

@setchapternewpage off
Cause TeX to typeset a new chapter on the same page as the last chapter, after skipping some vertical whitespace. Also, cause TeX to format page headers for single-sided printing. (You can override the headers format with the @headings double command; see section The @headings Command.)
@setchapternewpage on
Cause TeX to start new chapters on new pages and to typeset page headers for single-sided printing. This is the form most often used for short reports. This alternative is the default.
@setchapternewpage odd
Cause TeX to start new chapters on new, odd-numbered pages (right-handed pages) and to typeset for double-sided printing. This is the form most often used for books and manuals.

Texinfo does not have an @setchapternewpage even command.

(You can countermand or modify an @setchapternewpage command with an @headings command. See section The @headings Command.)

At the beginning of a manual or book, pages are not numbered--for example, the title and copyright pages of a book are not numbered. By convention, table of contents pages are numbered with roman numerals and not in sequence with the rest of the document.

Since an Info file does not have pages, the @setchapternewpage command has no effect on it.

Usually, you do not write an @setchapternewpage command for single-sided printing, but accept the default which is to typeset for single-sided printing and to start new chapters on new pages. Usually, you write an @setchapternewpage odd command for double-sided printing.

Paragraph Indenting

The Info formatting commands may insert spaces at the beginning of the first line of each paragraph, thereby indenting that paragraph. You can use the @paragraphindent command to specify the indentation. Write an @paragraphindent command at the beginning of a line followed by either `asis' or a number. The template is:

@paragraphindent indent

The Info formatting commands indent according to the value of indent:

  • If the value of indent is `asis', the Info formatting commands do not change the existing indentation.
  • If the value of indent is zero, the Info formatting commands delete existing indentation.
  • If the value of indent is greater than zero, the Info formatting commands indent the paragraph by that number of spaces.

The default value of indent is `asis'.

Write the @paragraphindent command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you write the command between the start-of-header and end-of-header lines, the region formatting commands indent paragraphs as specified.)

A peculiarity of the texinfo-format-buffer and texinfo-format-region commands is that they do not indent (nor fill) paragraphs that contain @w or @* commands. See section Refilling Paragraphs, for a detailed description of what goes on.

End of Header

Follow the header lines with an end-of-header line. An end-of-header line looks like this:

@c %**end of header

If you include the @setchapternewpage command between the start-of-header and end-of-header lines, TeX will typeset a region as that command specifies. Similarly, if you include an @smallbook command between the start-of-header and end-of-header lines, TeX will typeset a region in the "small" book format.

See section Start of Header.

Summary and Copying Permissions for Info

The title page and the copyright page appear only in the printed copy of the manual; therefore, the same information must be inserted in a section that appears only in the Info file. This section usually contains a brief description of the contents of the Info file, a copyright notice, and copying permissions.

The copyright notice should read:

Copyright year copyright-owner

and be put on a line by itself.

Standard text for the copyright permissions is contained in an appendix to this manual; see section `ifinfo' Copying Permissions, for the complete text.

The permissions text appears in an Info file before the first node. This mean that a reader does not see this text when reading the file using Info, except when using the advanced Info command g *.

The Title and Copyright Pages

A manual's name and author are usually printed on a title page. Sometimes copyright information is printed on the title page as well; more often, copyright information is printed on the back of the title page.

The title and copyright pages appear in the printed manual, but not in the Info file. Because of this, it is possible to use several slightly obscure TeX typesetting commands that cannot be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual.

See section Titlepage Copying Permissions, for the standard text for the copyright permissions.

  • titlepage: Create a title for the printed document.
  • titlefont center sp: The @titlefont, @center, and @sp commands.
  • title subtitle author: The @title, @subtitle, and @author commands.
  • Copyright & Permissions: How to write the copyright notice and include copying permissions.
  • end titlepage: Turn on page headings after the title and copyright pages.
  • headings on off: An option for turning headings on and off and double or single sided printing.

@titlepage

Start the material for the title page and following copyright page with @titlepage on a line by itself and end it with @end titlepage on a line by itself.

The @end titlepage command starts a new page and turns on page numbering. (See section Page Headings, for details about how to generate page headings.) All the material that you want to appear on unnumbered pages should be put between the @titlepage and @end titlepage commands. By using the @page command you can force a page break within the region delineated by the @titlepage and @end titlepage commands and thereby create more than one unnumbered page. This is how the copyright page is produced. (The @titlepage command might perhaps have been better named the @titleandadditionalpages command, but that would have been rather long!)

When you write a manual about a computer program, you should write the version of the program to which the manual applies on the title page. If the manual changes more frequently than the program or is independent of it, you should also include an edition number(5) for the manual. This helps readers keep track of which manual is for which version of the program. (The `Top' node should also contain this information; see section @top.)

Texinfo provides two main methods for creating a title page. One method uses the @titlefont, @sp, and @center commands to generate a title page in which the words on the page are centered.

The second method uses the @title, @subtitle, and @author commands to create a title page with black rules under the title and author lines and the subtitle text set flush to the right hand side of the page. With this method, you do not specify any of the actual formatting of the title page. You specify the text you want, and Texinfo does the formatting. You may use either method.

For extremely simple applications, Texinfo also provides a command @shorttitlepage which takes a single argument as the title. The argument is typeset on a page by itself and followed by a blank page.

@titlefont, @center, and @sp

You can use the @titlefont, @sp, and @center commands to create a title page for a printed document. (This is the first of the two methods for creating a title page in Texinfo.)

Use the @titlefont command to select a large font suitable for the title itself.

For example:

@titlefont{Texinfo}

Use the @center command at the beginning of a line to center the remaining text on that line. Thus,

@center @titlefont{Texinfo}

centers the title, which in this example is "Texinfo" printed in the title font.

Use the @sp command to insert vertical space. For example:

@sp 2

This inserts two blank lines on the printed page. (See section @sp n: Insert Blank Lines, for more information about the @sp command.)

A template for this method looks like this:

@titlepage
@sp 10
@center @titlefont{name-of-manual-when-printed}
@sp 2
@center subtitle-if-any
@sp 2
@center author
...
@end titlepage

The spacing of the example fits an 8 1/2 by 11 inch manual.

@title, @subtitle, and @author

You can use the @title, @subtitle, and @author commands to create a title page in which the vertical and horizontal spacing is done for you automatically. This contrasts with the method described in the previous section, in which the @sp command is needed to adjust vertical spacing.

Write the @title, @subtitle, or @author commands at the beginning of a line followed by the title, subtitle, or author.

The @title command produces a line in which the title is set flush to the left-hand side of the page in a larger than normal font. The title is underlined with a black rule.

The @subtitle command sets subtitles in a normal-sized font flush to the right-hand side of the page.

The @author command sets the names of the author or authors in a middle-sized font flush to the left-hand side of the page on a line near the bottom of the title page. The names are underlined with a black rule that is thinner than the rule that underlines the title. (The black rule only occurs if the @author command line is followed by an @page command line.)

There are two ways to use the @author command: you can write the name or names on the remaining part of the line that starts with an @author command:

@author by Jane Smith and John Doe

or you can write the names one above each other by using two (or more) @author commands:

@author Jane Smith
@author John Doe

(Only the bottom name is underlined with a black rule.)

A template for this method looks like this:

@titlepage
@title name-of-manual-when-printed
@subtitle subtitle-if-any
@subtitle second-subtitle
@author author
@page
...
@end titlepage

Copyright Page and Permissions

By international treaty, the copyright notice for a book should be either on the title page or on the back of the title page. The copyright notice should include the year followed by the name of the organization or person who owns the copyright.

When the copyright notice is on the back of the title page, that page is customarily not numbered. Therefore, in Texinfo, the information on the copyright page should be within @titlepage and @end titlepage commands.

Use the @page command to cause a page break. To push the copyright notice and the other text on the copyright page towards the bottom of the page, you can write a somewhat mysterious line after the @page command that reads like this:

@vskip 0pt plus 1filll

This is a TeX command that is not supported by the Info formatting commands. The @vskip command inserts whitespace. The `0pt plus 1filll' means to put in zero points of mandatory whitespace, and as much optional whitespace as needed to push the following text to the bottom of the page. Note the use of three `l's in the word `filll'; this is the correct usage in TeX.

In a printed manual, the @copyright{} command generates a `c' inside a circle. (In Info, it generates `(C)'.) The copyright notice itself has the following legally defined sequence:

Copyright © year copyright-owner

It is customary to put information on how to get a manual after the copyright notice, followed by the copying permissions for the manual.

Note that permissions must be given here as well as in the summary segment within @ifinfo and @end ifinfo that immediately follows the header since this text appears only in the printed manual and the `ifinfo' text appears only in the Info file.

See section Sample Permissions, for the standard text.

Heading Generation

An @end titlepage command on a line by itself not only marks the end of the title and copyright pages, but also causes TeX to start generating page headings and page numbers.

To repeat what is said elsewhere, Texinfo has two standard page heading formats, one for documents which are printed on one side of each sheet of paper (single-sided printing), and the other for documents which are printed on both sides of each sheet (double-sided printing). (See section @setchapternewpage.) You can specify these formats in different ways:

  • The conventional way is to write an @setchapternewpage command before the title page commands, and then have the @end titlepage command start generating page headings in the manner desired. (See section @setchapternewpage.)
  • Alternatively, you can use the @headings command to prevent page headings from being generated or to start them for either single or double-sided printing. (Write an @headings command immediately after the @end titlepage command. See section The @headings Command, for more information.)
  • Or, you may specify your own page heading and footing format. See section Page Headings, for detailed information about page headings and footings.

Most documents are formatted with the standard single-sided or double-sided format, using @setchapternewpage odd for double-sided printing and no @setchapternewpage command for single-sided printing.

The @headings Command

The @headings command is rarely used. It specifies what kind of page headings and footings to print on each page. Usually, this is controlled by the @setchapternewpage command. You need the @headings command only if the @setchapternewpage command does not do what you want, or if you want to turn off pre-defined page headings prior to defining your own. Write an @headings command immediately after the @end titlepage command.

You can use @headings as follows:

@headings off
Turn off printing of page headings.
@headings single
Turn on page headings appropriate for single-sided printing.
@headings double
Turn on page headings appropriate for double-sided printing. The two commands, @headings on and @headings double, are synonymous.
@headings singleafter
@headings doubleafter
Turn on single or double headings, respectively, after the current page is output.
@headings on
Turn on page headings: single if `@setchapternewpage on', double otherwise.

For example, suppose you write @setchapternewpage off before the @titlepage command to tell TeX to start a new chapter on the same page as the end of the last chapter. This command also causes TeX to typeset page headers for single-sided printing. To cause TeX to typeset for double sided printing, write @headings double after the @end titlepage command.

You can stop TeX from generating any page headings at all by writing @headings off on a line of its own immediately after the line containing the @end titlepage command, like this:

@end titlepage
@headings off

The @headings off command overrides the @end titlepage command, which would otherwise cause TeX to print page headings.

You can also specify your own style of page heading and footing. See section Page Headings, for more information.

The `Top' Node and Master Menu

The `Top' node is the node from which you enter an Info file.

A `Top' node should contain a brief description of the Info file and an extensive, master menu for the whole Info file. This helps the reader understand what the Info file is about. Also, you should write the version number of the program to which the Info file applies; or, at least, the edition number.

The contents of the `Top' node should appear only in the Info file; none of it should appear in printed output, so enclose it between @ifinfo and @end ifinfo commands. (TeX does not print either an @node line or a menu; they appear only in Info; strictly speaking, you are not required to enclose these parts between @ifinfo and @end ifinfo, but it is simplest to do so. See section Conditionally Visible Text.)

  • Master Menu Parts: A master menu has three or more parts.

Sometimes, you will want to place an @top sectioning command line containing the title of the document immediately after the @node Top line (see section The @top Sectioning Command, for more information).

For example, the beginning of the Top node of this manual contains an @top sectioning command, a short description, and edition and version information. It looks like this:

...
@end titlepage

@ifinfo
@node Top, Copying, , (dir)
@top Texinfo

Texinfo is a documentation system...

This is edition...
...
@end ifinfo

@menu
* Copying::                 Texinfo is freely
                              redistributable.
* Overview::                What is Texinfo?
...
@end menu

In a `Top' node, the `Previous', and `Up' nodes usually refer to the top level directory of the whole Info system, which is called `(dir)'. The `Next' node refers to the first node that follows the main or master menu, which is usually the copying permissions, introduction, or first chapter.

Parts of a Master Menu

A master menu is a detailed main menu listing all the nodes in a file.

A master menu is enclosed in @menu and @end menu commands and does not appear in the printed document.

Generally, a master menu is divided into parts.

  • The first part contains the major nodes in the Texinfo file: the nodes for the chapters, chapter-like sections, and the appendices.
  • The second part contains nodes for the indices.
  • The third and subsequent parts contain a listing of the other, lower level nodes, often ordered by chapter. This way, rather than go through an intermediary menu, an inquirer can go directly to a particular node when searching for specific information. These menu items are not required; add them if you think they are a convenience. If you do use them, put @detailmenu before the first one, and @end detailmenu after the last; otherwise, makeinfo will get confused.

Each section in the menu can be introduced by a descriptive line. So long as the line does not begin with an asterisk, it will not be treated as a menu entry. (See section Writing a Menu, for more information.)

For example, the master menu for this manual looks like the following (but has many more entries):

@menu
* Copying::             Texinfo is freely
                          redistributable.
* Overview::            What is Texinfo?
* Texinfo Mode::        Special features in GNU Emacs.
...
...
* Command and Variable Index::
                        An entry for each @-command.
* Concept Index::       An entry for each concept.

@detailmenu
 -- The Detailed Node Listing ---

Overview of Texinfo

* Info Files::          What is an Info file?
* Printed Manuals::     Characteristics of
                          a printed manual.
...
...

Using Texinfo Mode

* Info on a Region::    Formatting part of a file
                          for Info.
...
...
@end detailmenu
@end menu

Software Copying Permissions

If the Texinfo file has a section containing the "General Public License" and the distribution information and a warranty disclaimer for the software that is documented, this section usually follows the `Top' node. The General Public License is very important to Project GNU software. It ensures that you and others will continue to have a right to use and share the software.

The copying and distribution information and the disclaimer are followed by an introduction or else by the first chapter of the manual.

Although an introduction is not a required part of a Texinfo file, it is very helpful. Ideally, it should state clearly and concisely what the file is about and who would be interested in reading it. In general, an introduction would follow the licensing and distribution information, although sometimes people put it earlier in the document. Usually, an introduction is put in an @unnumbered section. (See section @unnumbered, @appendix.)

Ending a Texinfo File

The end of a Texinfo file should include the commands that create indices and generate detailed and summary tables of contents. And it must include the @bye command that marks the last line processed by TeX.

For example:

@node    Concept Index,     , Variables Index, Top
@c        node-name,    next, previous,        up
@unnumbered Concept Index

@printindex cp

@contents
@bye
  • Printing Indices & Menus: How to print an index in hardcopy and generate index menus in Info.
  • Contents: How to create a table of contents.
  • File End: How to mark the end of a file.

Index Menus and Printing an Index

To print an index means to include it as part of a manual or Info file. This does not happen automatically just because you use @cindex or other index-entry generating commands in the Texinfo file; those just cause the raw data for the index to be accumulated. To generate an index, you must include the @printindex command at the place in the document where you want the index to appear. Also, as part of the process of creating a printed manual, you must run a program called texindex (see section Format and Print Hardcopy) to sort the raw data to produce a sorted index file. The sorted index file is what is actually used to print the index.

Texinfo offers six different types of predefined index: the concept index, the function index, the variables index, the keystroke index, the program index, and the data type index (see section Predefined Indices). Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg', and `tp'. You may merge indices, or put them into separate sections (see section Combining Indices); or you may define your own indices (see section Defining New Indices).

The @printindex command takes a two-letter index name, reads the corresponding sorted index file and formats it appropriately into an index.

The @printindex command does not generate a chapter heading for the index. Consequently, you should precede the @printindex command with a suitable section or chapter command (usually @unnumbered) to supply the chapter heading and put the index into the table of contents. Precede the @unnumbered command with an @node line.

For example:

@node Variable Index, Concept Index, Function Index, Top
@comment    node-name,         next,       previous, up
@unnumbered Variable Index

@printindex vr

@node     Concept Index,     , Variable Index, Top
@comment      node-name, next,       previous, up
@unnumbered Concept Index

@printindex cp

@summarycontents
@contents
@bye

(Readers often prefer that the concept index come last in a book, since that makes it easiest to find.)

Generating a Table of Contents

The @chapter, @section, and other structuring commands supply the information to make up a table of contents, but they do not cause an actual table to appear in the manual. To do this, you must use the @contents and @summarycontents commands:

@contents
Generate a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. (Headings generated by the @heading series of commands do not appear in the table of contents.) The @contents command should be written on a line by itself.
@shortcontents
@summarycontents
(@summarycontents is a synonym for @shortcontents; the two commands are exactly the same.) Generate a short or summary table of contents that lists only the chapters (and appendices and unnumbered chapters). Omit sections, subsections and subsubsections. Only a long manual needs a short table of contents in addition to the full table of contents. Write the @shortcontents command on a line by itself right before the @contents command.

The table of contents commands automatically generate a chapter-like heading at the top of the first table of contents page. Write the table of contents commands at the very end of a Texinfo file, just before the @bye command, following any index sections--anything in the Texinfo file after the table of contents commands will be omitted from the table of contents.

When you print a manual with a table of contents, the table of contents are printed last and numbered with roman numerals. You need to place those pages in their proper place, after the title page, yourself. (This is the only collating you need to do for a printed manual. The table of contents is printed last because it is generated after the rest of the manual is typeset.)

Here is an example of where to write table of contents commands:

indices...
@shortcontents
@contents
@bye

Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the @contents and @shortcontents commands.

@bye File Ending

An @bye command terminates TeX or Info formatting. None of the formatting commands see any of the file following @bye. The @bye command should be on a line by itself.

If you wish, you may follow the @bye line with notes. These notes will not be formatted and will not appear in either Info or a printed manual; it is as if text after @bye were within @ignore ... @end ignore. Also, you may follow the @bye line with a local variables list. See section Using the Local Variables List, for more information.

Chapter Structuring

The chapter structuring commands divide a document into a hierarchy of chapters, sections, subsections, and subsubsections. These commands generate large headings; they also provide information for the table of contents of a printed manual (see section Generating a Table of Contents).

The chapter structuring commands do not create an Info node structure, so normally you should put an @node command immediately before each chapter structuring command (see section Nodes). The only time you are likely to use the chapter structuring commands without using the node structuring commands is if you are writing a document that contains no cross references and will never be transformed into Info format.

It is unlikely that you will ever write a Texinfo file that is intended only as an Info file and not as a printable document. If you do, you might still use chapter structuring commands to create a heading at the top of each node--but you don't need to.

  • Tree Structuring: A manual is like an upside down tree ...
  • Structuring Command Types: How to divide a manual into parts.
  • makeinfo top: The @top command, part of the `Top' node.
  • chapter
  • unnumbered & appendix
  • majorheading & chapheading
  • section
  • unnumberedsec appendixsec heading
  • subsection
  • unnumberedsubsec appendixsubsec subheading
  • subsubsection: Commands for the lowest level sections.
  • Raise/lower sections: How to change commands' hierarchical level.

Tree Structure of Sections

A Texinfo file is usually structured like a book with chapters, sections, subsections, and the like. This structure can be visualized as a tree (or rather as an upside-down tree) with the root at the top and the levels corresponding to chapters, sections, subsection, and subsubsections.

Here is a diagram that shows a Texinfo file with three chapters, each of which has two sections.

                          Top
                           |
         -------------------------------------
        |                  |                  |
     Chapter 1          Chapter 2          Chapter 3
        |                  |                  |
     --------           --------           --------
    |        |         |        |         |        |
 Section  Section   Section  Section   Section  Section
   1.1      1.2       2.1      2.2       3.1      3.2

In a Texinfo file that has this structure, the beginning of Chapter 2 looks like this:

@node    Chapter 2,  Chapter 3, Chapter 1, top
@chapter Chapter 2

The chapter structuring commands are described in the sections that follow; the @node and @menu commands are described in following chapters. (See section Nodes, and see section Menus.)

Types of Structuring Commands

The chapter structuring commands fall into four groups or series, each of which contains structuring commands corresponding to the hierarchical levels of chapters, sections, subsections, and subsubsections.

The four groups are the @chapter series, the @unnumbered series, the @appendix series, and the @heading series.

Each command produces titles that have a different appearance on the printed page or Info file; only some of the commands produce titles that are listed in the table of contents of a printed book or manual.

  • The @chapter and @appendix series of commands produce numbered or lettered entries both in the body of a printed work and in its table of contents.
  • The @unnumbered series of commands produce unnumbered entries both in the body of a printed work and in its table of contents. The @top command, which has a special use, is a member of this series (see section @top).
  • The @heading series of commands produce unnumbered headings that do not appear in a table of contents. The heading commands never start a new page.
  • The @majorheading command produces results similar to using the @chapheading command but generates a larger vertical whitespace before the heading.
  • When an @setchapternewpage command says to do so, the @chapter, @unnumbered, and @appendix commands start new pages in the printed manual; the @heading commands do not.

Here are the four groups of chapter structuring commands:

@top

The @top command is a special sectioning command that you use only after an `@node Top' line at the beginning of a Texinfo file. The @top command tells the makeinfo formatter which node is the `Top' node. It has the same typesetting effect as @unnumbered (see section @unnumbered, @appendix). For detailed information, see section The @top Sectioning Command.

@chapter

@chapter identifies a chapter in the document. Write the command at the beginning of a line and follow it on the same line by the title of the chapter.

For example, this chapter in this manual is entitled "Chapter Structuring"; the @chapter line looks like this:

@chapter Chapter Structuring

In TeX, the @chapter command creates a chapter in the document, specifying the chapter title. The chapter is numbered automatically.

In Info, the @chapter command causes the title to appear on a line by itself, with a line of asterisks inserted underneath. Thus, in Info, the above example produces the following output:

Chapter Structuring
*******************

Texinfo also provides a command @centerchap, which is analogous to @unnumbered, but centers its argument in the printed output. This kind of stylistic choice is not usually offered by Texinfo.

@unnumbered, @appendix

Use the @unnumbered command to create a chapter that appears in a printed manual without chapter numbers of any kind. Use the @appendix command to create an appendix in a printed manual that is labelled by letter instead of by number.

For Info file output, the @unnumbered and @appendix commands are equivalent to @chapter: the title is printed on a line by itself with a line of asterisks underneath. (See section @chapter.)

To create an appendix or an unnumbered chapter, write an @appendix or @unnumbered command at the beginning of a line and follow it on the same line by the title, as you would if you were creating a chapter.

@majorheading, @chapheading

The @majorheading and @chapheading commands put chapter-like headings in the body of a document.

However, neither command causes TeX to produce a numbered heading or an entry in the table of contents; and neither command causes TeX to start a new page in a printed manual.

In TeX, an @majorheading command generates a larger vertical whitespace before the heading than an @chapheading command but is otherwise the same.

In Info, the @majorheading and @chapheading commands are equivalent to @chapter: the title is printed on a line by itself with a line of asterisks underneath. (See section @chapter.)

@section

In a printed manual, an @section command identifies a numbered section within a chapter. The section title appears in the table of contents. In Info, an @section command provides a title for a segment of text, underlined with `='.

This section is headed with an @section command and looks like this in the Texinfo file:

@section @code{@@section}

To create a section, write the @section command at the beginning of a line and follow it on the same line by the section title.

Thus,

@section This is a section

produces

This is a section
=================

in Info.

@unnumberedsec, @appendixsec, @heading

The @unnumberedsec, @appendixsec, and @heading commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the @section command. (See section @section.)

@unnumberedsec
The @unnumberedsec command may be used within an unnumbered chapter or within a regular chapter or appendix to provide an unnumbered section.
@appendixsec
@appendixsection
@appendixsection is a longer spelling of the @appendixsec command; the two are synonymous. Conventionally, the @appendixsec or @appendixsection command is used only within appendices.
@heading
You may use the @heading command anywhere you wish for a section-style heading that will not appear in the table of contents.

The @subsection Command

Subsections are to sections as sections are to chapters. (See section @section.) In Info, subsection titles are underlined with `-'. For example,

@subsection This is a subsection

produces

This is a subsection
--------------------

In a printed manual, subsections are listed in the table of contents and are numbered three levels deep.

The @subsection-like Commands

The @unnumberedsubsec, @appendixsubsec, and @subheading commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the @subsection command. (See section The @subsection Command.)

In Info, the @subsection-like commands generate a title underlined with hyphens. In a printed manual, an @subheading command produces a heading like that of a subsection except that it is not numbered and does not appear in the table of contents. Similarly, an @unnumberedsubsec command produces an unnumbered heading like that of a subsection and an @appendixsubsec command produces a subsection-like heading labelled with a letter and numbers; both of these commands produce headings that appear in the table of contents.

The `subsub' Commands

The fourth and lowest level sectioning commands in Texinfo are the `subsub' commands. They are:

@subsubsection
Subsubsections are to subsections as subsections are to sections. (See section The @subsection Command.) In a printed manual, subsubsection titles appear in the table of contents and are numbered four levels deep.
@unnumberedsubsubsec
Unnumbered subsubsection titles appear in the table of contents of a printed manual, but lack numbers. Otherwise, unnumbered subsubsections are the same as subsubsections. In Info, unnumbered subsubsections look exactly like ordinary subsubsections.
@appendixsubsubsec
Conventionally, appendix commands are used only for appendices and are lettered and numbered appropriately in a printed manual. They also appear in the table of contents. In Info, appendix subsubsections look exactly like ordinary subsubsections.
@subsubheading
The @subsubheading command may be used anywhere that you need a small heading that will not appear in the table of contents. In Info, subsubheadings look exactly like ordinary subsubsection headings.

In Info, `subsub' titles are underlined with periods. For example,

@subsubsection This is a subsubsection

produces

This is a subsubsection
.......................

@raisesections and @lowersections

The @raisesections and @lowersections commands raise and lower the hierarchical level of chapters, sections, subsections and the like. The @raisesections command changes sections to chapters, subsections to sections, and so on. The @lowersections command changes chapters to sections, sections to subsections, and so on.

An @lowersections command is useful if you wish to include text that is written as an outer or standalone Texinfo file in another Texinfo file as an inner, included file. If you write the command at the beginning of the file, all your @chapter commands are formatted as if they were @section commands, all your @section command are formatted as if they were @subsection commands, and so on.

@raisesections raises a command one level in the chapter structuring hierarchy:

  Change           To

@subsection     @section,
@section        @chapter,
@heading        @chapheading,
          etc.

@lowersections lowers a command one level in the chapter structuring hierarchy:

  Change           To

@chapter        @section,
@subsection     @subsubsection,
@heading        @subheading,
          etc.

An @raisesections or @lowersections command changes only those structuring commands that follow the command in the Texinfo file. Write an @raisesections or @lowersections command on a line of its own.

An @lowersections command cancels an @raisesections command, and vice versa. Typically, the commands are used like this:

@lowersections
@include somefile.texi
@raisesections

Without the @raisesections, all the subsequent sections in your document will be lowered.

Repeated use of the commands continue to raise or lower the hierarchical level a step at a time.

An attempt to raise above `chapters' reproduces chapter commands; an attempt to lower below `subsubsections' reproduces subsubsection commands.

Nodes

Nodes are the primary segments of a Texinfo file. They do not themselves impose a hierarchic or any other kind of structure on a file. Nodes contain node pointers that name other nodes, and can contain menus which are lists of nodes. In Info, the movement commands can carry you to a pointed-to node or to a node listed in a menu. Node pointers and menus provide structure for Info files just as chapters, sections, subsections, and the like, provide structure for printed books.

    Info output and printed output.
  • Node Menu Illustration: A diagram, and sample nodes and menus.
  • node: How to write a node, in detail.
  • makeinfo Pointer Creation: How to create node pointers with makeinfo.

The node and menu commands and the chapter structuring commands are independent of each other:

  • In Info, node and menu commands provide structure. The chapter structuring commands generate headings with different kinds of underlining--asterisks for chapters, hyphens for sections, and so on; they do nothing else.
  • In TeX, the chapter structuring commands generate chapter and section numbers and tables of contents. The node and menu commands provide information for cross references; they do nothing else.

You can use node pointers and menus to structure an Info file any way you want; and you can write a Texinfo file so that its Info output has a different structure than its printed output. However, most Texinfo files are written such that the structure for the Info output corresponds to the structure for the printed output. It is not convenient to do otherwise.

Generally, printed output is structured in a tree-like hierarchy in which the chapters are the major limbs from which the sections branch out. Similarly, node pointers and menus are organized to create a matching structure in the Info output.

Node and Menu Illustration

Here is a copy of the diagram shown earlier that illustrates a Texinfo file with three chapters, each of which contains two sections.

Note that the "root" is at the top of the diagram and the "leaves" are at the bottom. This is how such a diagram is drawn conventionally; it illustrates an upside-down tree. For this reason, the root node is called the `Top' node, and `Up' node pointers carry you closer to the root.

                          Top
                           |
         -------------------------------------
        |                  |                  |
     Chapter 1          Chapter 2          Chapter 3
        |                  |                  |
     --------           --------           --------
    |        |         |        |         |        |
 Section  Section   Section  Section   Section  Section
   1.1      1.2       2.1      2.2       3.1      3.2

Write the beginning of the node for Chapter 2 like this:

@node     Chapter 2,  Chapter 3, Chapter 1, top
@comment  node-name,  next,      previous,  up

This @node line says that the name of this node is "Chapter 2", the name of the `Next' node is "Chapter 3", the name of the `Previous' node is "Chapter 1", and the name of the `Up' node is "Top".

Please Note: `Next' refers to the next node at the same hierarchical level in the manual, not necessarily to the next node within the Texinfo file. In the Texinfo file, the subsequent node may be at a lower level--a section-level node may follow a chapter-level node, and a subsection-level node may follow a section-level node. `Next' and `Previous' refer to nodes at the same hierarchical level. (The `Top' node contains the exception to this rule. Since the `Top' node is the only node at that level, `Next' refers to the first following node, which is almost always a chapter or chapter-level node.)

To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter 2. (See section Menus.) You would write the menu just before the beginning of Section 2.1, like this:

    @menu
    * Sect. 2.1::    Description of this section.
    * Sect. 2.2::
    @end menu

Write the node for Sect. 2.1 like this:

    @node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
    @comment  node-name, next,      previous,  up

In Info format, the `Next' and `Previous' pointers of a node usually lead to other nodes at the same level--from chapter to chapter or from section to section (sometimes, as shown, the `Previous' pointer points up); an `Up' pointer usually leads to a node at the level above (closer to the `Top' node); and a `Menu' leads to nodes at a level below (closer to `leaves'). (A cross reference can point to a node at any level; see section Cross References.)

Usually, an @node command and a chapter structuring command are used in sequence, along with indexing commands. (You may follow the @node line with a comment line that reminds you which pointer is which.)

Here is the beginning of the chapter in this manual called "Ending a Texinfo File". This shows an @node line followed by a comment line, an @chapter line, and then by indexing lines.

@node    Ending a File, Structuring, Beginning a File, Top
@comment node-name,     next,        previous,         up
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending

The @node Command

A node is a segment of text that begins at an @node command and continues until the next @node command. The definition of node is different from that for chapter or section. A chapter may contain sections and a section may contain subsections; but a node cannot contain subnodes; the text of a node continues only until the next @node command in the file. A node usually contains only one chapter structuring command, the one that follows the @node line. On the other hand, in printed output nodes are used only for cross references, so a chapter or section may contain any number of nodes. Indeed, a chapter usually contains several nodes, one for each section, subsection, and subsubsection.

To create a node, write an @node command at the beginning of a line, and follow it with four arguments, separated by commas, on the rest of the same line. These arguments are the name of the node, and the names of the `Next', `Previous', and `Up' pointers, in that order. You may insert spaces before each pointer if you wish; the spaces are ignored. You must write the name of the node, and the names of the `Next', `Previous', and `Up' pointers, all on the same line. Otherwise, the formatters fail. (See Info file `info', node `Top', for more information about nodes in Info.)

Usually, you write one of the chapter-structuring command lines immediately after an @node line--for example, an @section or @subsection line. (See section Types of Structuring Commands.)

Please note: The GNU Emacs Texinfo mode updating commands work only with Texinfo files in which @node lines are followed by chapter structuring lines. See section Updating Requirements.

TeX uses @node lines to identify the names to use for cross references. For this reason, you must write @node lines in a Texinfo file that you intend to format for printing, even if you do not intend to format it for Info. (Cross references, such as the one at the end of this sentence, are made with @xref and its related commands; see section Cross References.)

  • Writing a Node: How to write an @node line.
  • Node Line Tips: Keep names short.
  • Node Line Requirements: Keep names unique, without @-commands.
  • First Node: How to write a `Top' node.
  • makeinfo top command: How to use the @top command.
  • Top Node Summary: Write a brief description for readers.

The name of a node identifies the node. The pointers enable you to reach other nodes and consist of the names of those nodes.

Normally, a node's `Up' pointer contains the name of the node whose menu mentions that node. The node's `Next' pointer contains the name of the node that follows that node in that menu and its `Previous' pointer contains the name of the node that precedes it in that menu. When a node's `Previous' node is the same as its `Up' node, both node pointers name the same node.

Usually, the first node of a Texinfo file is the `Top' node, and its `Up' and `Previous' pointers point to the `dir' file, which contains the main menu for all of Info.

The `Top' node itself contains the main or master menu for the manual. Also, it is helpful to include a brief description of the manual in the `Top' node. See section The First Node, for information on how to write the first node of a Texinfo file.

How to Write an @node Line

The easiest way to write an @node line is to write @node at the beginning of a line and then the name of the node, like this:

@node node-name

If you are using GNU Emacs, you can use the update node commands provided by Texinfo mode to insert the names of the pointers; or you can leave the pointers out of the Texinfo file and let makeinfo insert node pointers into the Info file it creates. (See section Using Texinfo Mode, and section Creating Pointers with makeinfo.)

Alternatively, you can insert the `Next', `Previous', and `Up' pointers yourself. If you do this, you may find it helpful to use the Texinfo mode keyboard command C-c C-c n. This command inserts `@node' and a comment line listing the names of the pointers in their proper order. The comment line helps you keep track of which arguments are for which pointers. This comment line is especially useful if you are not familiar with Texinfo.

The template for a node line with `Next', `Previous', and `Up' pointers looks like this:

@node node-name, next, previous, up

If you wish, you can ignore @node lines altogether in your first draft and then use the texinfo-insert-node-lines command to create @node lines for you. However, we do not recommend this practice. It is better to name the node itself at the same time that you write a segment so you can easily make cross references. A large number of cross references are an especially important feature of a good Info file.

After you have inserted an @node line, you should immediately write an @-command for the chapter or section and insert its name. Next (and this is important!), put in several index entries. Usually, you will find at least two and often as many as four or five ways of referring to the node in the index. Use them all. This will make it much easier for people to find the node.

@node Line Tips

Here are three suggestions:

  • Try to pick node names that are informative but short. In the Info file, the file name, node name, and pointer names are all inserted on one line, which may run into the right edge of the window. (This does not cause a problem with Info, but is ugly.)
  • Try to pick node names that differ from each other near the beginnings of their names. This way, it is easy to use automatic name completion in Info.
  • By convention, node names are capitalized just as they would be for section or chapter titles--initial and significant words are capitalized; others are not.

@node Line Requirements

Here are several requirements for @node lines:

  • All the node names for a single Info file must be unique. Duplicates confuse the Info movement commands. This means, for example, that if you end every chapter with a summary, you must name each summary node differently. You cannot just call each one "Summary". You may, however, duplicate the titles of chapters, sections, and the like. Thus you can end each chapter in a book with a section called "Summary", so long as the node names for those sections are all different.
  • A pointer name must be the name of a node. The node to which a pointer points may come before or after the node containing the pointer.
  • You cannot use any of the Texinfo @-commands in a node name; @-commands confuse Info. Thus, the beginning of the section called @chapter looks like this:
    @node  chapter, unnumbered & appendix, makeinfo top, Structuring
@comment  node-name,  next,  previous,  up
@section @code{@@chapter}
@findex chapter
  • You cannot use commas or apostrophes within a node name; these confuse TeX or the Info formatters. For example, the following is a section title:
    @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
    The corresponding node name is:
    unnumberedsec appendixsec heading
  • Case is significant.

The First Node

The first node of a Texinfo file is the Top node, except in an included file (see section Include Files). The Top node contains the main or master menu for the document, and a short summary of the document (see section The `Top' Node Summary).

The Top node (which must be named `top' or `Top') should have as its `Up' node the name of a node in another file, where there is a menu that leads to this file. Specify the file name in parentheses. If the file is to be installed directly in the Info directory file, use `(dir)' as the parent of the Top node; this is short for `(dir)top', and specifies the Top node in the `dir' file, which contains the main menu for the Info system as a whole. For example, the @node Top line of this manual looks like this:

@node Top, Copying, , (dir)

(You can use the Texinfo updating commands or the makeinfo utility to insert these pointers automatically.)

Do not define the `Previous' node of the Top node to be `(dir)', as it causes confusing behavior for users: if you are in the Top node and hits DEL to go backwards, you wind up in the middle of the some other entry in the `dir' file, which has nothing to do with what you were reading.

See section Installing an Info File, for more information about installing an Info file in the `info' directory.

The @top Sectioning Command

A special sectioning command, @top, has been created for use with the @node Top line. The @top sectioning command tells makeinfo that it marks the `Top' node in the file. It provides the information that makeinfo needs to insert node pointers automatically. Write the @top command at the beginning of the line immediately following the @node Top line. Write the title on the remaining part of the same line as the @top command.

In Info, the @top sectioning command causes the title to appear on a line by itself, with a line of asterisks inserted underneath.

In TeX and texinfo-format-buffer, the @top sectioning command is merely a synonym for @unnumbered. Neither of these formatters require an @top command, and do nothing special with it. You can use @chapter or @unnumbered after the @node Top line when you use these formatters. Also, you can use @chapter or @unnumbered when you use the Texinfo updating commands to create or update pointers and menus.

The `Top' Node Summary

You can help readers by writing a summary in the `Top' node, after the @top line, before the main or master menu. The summary should briefly describe the document. In Info, this summary will appear just before the master menu. In a printed manual, this summary will appear on a page of its own.

If you do not want the summary to appear on a page of its own in a printed manual, you can enclose the whole of the `Top' node, including the @node Top line and the @top sectioning command line or other sectioning command line between @ifinfo and @end ifinfo. This prevents any of the text from appearing in the printed output. (see section Conditionally Visible Text). You can repeat the brief description from the `Top' node within @iftex ... @end iftex at the beginning of the first chapter, for those who read the printed manual. This saves paper and may look neater.

You should write the version number of the program to which the manual applies in the summary. This helps the reader keep track of which manual is for which version of the program. If the manual changes more frequently than the program or is independent of it, you should also include an edition number for the manual. (The title page should also contain this information: see section @titlepage.)

Creating Pointers with makeinfo

The makeinfo program has a feature for automatically creating node pointers for a hierarchically organized file that lacks them.

When you take advantage of this feature, you do not need to write the `Next', `Previous', and `Up' pointers after the name of a node. However, you must write a sectioning command, such as @chapter or @section, on the line immediately following each truncated @node line. You cannot write a comment line after a node line; the section line must follow it immediately.

In addition, you must follow the `Top' @node line with a line beginning with @top to mark the `Top' node in the file. See section @top.

Finally, you must write the name of each node (except for the `Top' node) in a menu that is one or more hierarchical levels above the node's hierarchical level.

This node pointer insertion feature in makeinfo is an alternative to the menu and pointer creation and update commands in Texinfo mode. (See section Updating Nodes and Menus.) It is especially helpful to people who do not use GNU Emacs for writing Texinfo documents.

Menus

Menus contain pointers to subordinate nodes.(6) In Info, you use menus to go to such nodes. Menus have no effect in printed manuals and do not appear in them.

By convention, a menu is put at the end of a node since a reader who uses the menu may not see text that follows it.

A node that has a menu should not contain much text. If you have a lot of text and a menu, move most of the text into a new subnode--all but a few lines. Otherwise, a reader with a terminal that displays only a few lines may miss the menu and its associated text. As a practical matter, you should locate a menu within 20 lines of the beginning of the node.

  • Writing a Menu: What is a menu?
  • Menu Parts: A menu entry has three parts.
  • Less Cluttered Menu Entry: Two part menu entry.
  • Menu Example: Two and three part menu entries.
  • Other Info Files: How to refer to a different Info file.

The short text before a menu may look awkward in a printed manual. To avoid this, you can write a menu near the beginning of its node and follow the menu by an @node line, and then an @heading line located within @ifinfo and @end ifinfo. This way, the menu, @node line, and title appear only in the Info file, not the printed document.

For example, the preceding two paragraphs follow an Info-only menu, @node line, and heading, and look like this:

@menu
* Menu Location::             Put a menu in a short node.
* Writing a Menu::            What is a menu?
* Menu Parts::                A menu entry has three parts.
* Less Cluttered Menu Entry:: Two part menu entry.
* Menu Example::              Two and three part entries.
* Other Info Files::          How to refer to a different
                                Info file.
@end menu

@node Menu Location, Writing a Menu, , Menus
@ifinfo
@heading Menus Need Short Nodes
@end ifinfo

The Texinfo file for this document contains more than a dozen examples of this procedure. One is at the beginning of this chapter; another is at the beginning of the "Cross References" chapter.

Writing a Menu

A menu consists of an @menu command on a line by itself followed by menu entry lines or menu comment lines and then by an @end menu command on a line by itself.

A menu looks like this:

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.
@end menu

In a menu, every line that begins with an `* ' is a menu entry. (Note the space after the asterisk.) A line that does not start with an `* ' may also appear in a menu. Such a line is not a menu entry but is a menu comment line that appears in the Info file. In the example above, the line `Larger Units of Text' is a menu comment line; the two lines starting with `* ' are menu entries.

The Parts of a Menu

A menu entry has three parts, only the second of which is required:

  1. The menu entry name (optional).
  2. The name of the node (required).
  3. A description of the item (optional).

The template for a menu entry looks like this:

* menu-entry-name: node-name.   description

Follow the menu entry name with a single colon and follow the node name with tab, comma, period, or newline.

In Info, a user selects a node with the m (Info-menu) command. The menu entry name is what the user types after the m command.

The third part of a menu entry is a descriptive phrase or sentence. Menu entry names and node names are often short; the description explains to the reader what the node is about. A useful description complements the node name rather than repeats it. The description, which is optional, can spread over two or more lines; if it does, some authors prefer to indent the second line while others prefer to align it with the first (and all others). It's up to you.

Less Cluttered Menu Entry

When the menu entry name and node name are the same, you can write the name immediately after the asterisk and space at the beginning of the line and follow the name with two colons.

For example, write

* Name::                                    description

instead of

* Name: Name.                               description

You should use the node name for the menu entry name whenever possible, since it reduces visual clutter in the menu.

A Menu Example

A menu looks like this in Texinfo:

@menu
* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.
@end menu

This produces:

* menu:

* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.

Here is an example as you might see it in a Texinfo file:

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.
@end menu

This produces:

* menu:
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.

In this example, the menu has two entries. `Files' is both a menu entry name and the name of the node referred to by that name. `Multiples' is the menu entry name; it refers to the node named `Buffers'. The line `Larger Units of Text' is a comment; it appears in the menu, but is not an entry.

Since no file name is specified with either `Files' or `Buffers', they must be the names of nodes in the same Info file (see section Referring to Other Info Files).

Referring to Other Info Files

You can create a menu entry that enables a reader in Info to go to a node in another Info file by writing the file name in parentheses just before the node name. In this case, you should use the three-part menu entry format, which saves the reader from having to type the file name.

The format looks like this:

@menu
* first-entry-name:(filename)nodename.     description
* second-entry-name:(filename)second-node. description
@end menu

For example, to refer directly to the `Outlining' and `Rebinding' nodes in the Emacs Manual, you would write a menu like this:

@menu
* Outlining: (emacs)Outline Mode. The major mode for
                                  editing outlines.
* Rebinding: (emacs)Rebinding.    How to redefine the
                                  meaning of a key.
@end menu

If you do not list the node name, but only name the file, then Info presumes that you are referring to the `Top' node.

The `dir' file that contains the main menu for Info has menu entries that list only file names. These take you directly to the `Top' nodes of each Info document. (See section Installing an Info File.)

For example:

* Info: (info).         Documentation browsing system.
* Emacs: (emacs).       The extensible, self-documenting
                        text editor.

(The `dir' top level directory for the Info system is an Info file, not a Texinfo file, but a menu entry looks the same in both types of file.)

Note that the GNU Emacs Texinfo mode menu updating commands only work with nodes within the current buffer, so you cannot use them to create menus that refer to other files. You must write such menus by hand.

Cross References

Cross references are used to refer the reader to other parts of the same or different Texinfo files. In Texinfo, nodes are the places to which cross references can refer.

  • Cross Reference Commands: A summary of the different commands.
  • Cross Reference Parts: A cross reference has several parts.
  • xref: Begin a reference with `See' ...
  • Top Node Naming: How to refer to the beginning of another file.
  • ref: A reference for the last part of a sentence.
  • pxref: How to write a parenthetical cross reference.
  • inforef: How to refer to an Info-only file.
  • uref: How to refer to a uniform resource locator.

Often, but not always, a printed document should be designed so that it can be read sequentially. People tire of flipping back and forth to find information that should be presented to them as they need it.

However, in any document, some information will be too detailed for the current context, or incidental to it; use cross references to provide access to such information. Also, an on-line help system or a reference manual is not like a novel; few read such documents in sequence from beginning to end. Instead, people look up what they need. For this reason, such creations should contain many cross references to help readers find other information that they may not have read.

In a printed manual, a cross reference results in a page reference, unless it is to another manual altogether, in which case the cross reference names that manual.

In Info, a cross reference results in an entry that you can follow using the Info `f' command. (See Info file `info', node `Help-Adv'.)

The various cross reference commands use nodes to define cross reference locations. This is evident in Info, in which a cross reference takes you to the specified node. TeX also uses nodes to define cross reference locations, but the action is less obvious. When TeX generates a DVI file, it records nodes' page numbers and uses the page numbers in making references. Thus, if you are writing a manual that will only be printed, and will not be used on-line, you must nonetheless write @node lines to name the places to which you make cross references.

Different Cross Reference Commands

There are four different cross reference commands:

@xref
Used to start a sentence in the printed manual saying `See ...' or an Info cross-reference saying `*Note name: node.'.
@ref
Used within or, more often, at the end of a sentence; same as @xref for Info; produces just the reference in the printed manual without a preceding `See'.
@pxref
Used within parentheses to make a reference that suits both an Info file and a printed book. Starts with a lower case `see' within the printed manual. (`p' is for `parenthesis'.)
@inforef
Used to make a reference to an Info file for which there is no printed manual.

(The @cite command is used to make references to books and manuals for which there is no corresponding Info file and, therefore, no node to which to point. See section @cite{reference}.)

Parts of a Cross Reference

A cross reference command requires only one argument, which is the name of the node to which it refers. But a cross reference command may contain up to four additional arguments. By using these arguments, you can provide a cross reference name for Info, a topic description or section title for the printed output, the name of a different Info file, and the name of a different printed manual.

Here is a simple cross reference example:

@xref{Node name}.

which produces

*Note Node name::.

and

See Section nnn [Node name], page ppp.

Here is an example of a full five-part cross reference:

@xref{Node name, Cross Reference Name, Particular Topic,
info-file-name, A Printed Manual}, for details.

which produces

*Note Cross Reference Name: (info-file-name)Node name,
for details.

in Info and

See section "Particular Topic" in A Printed Manual, for details.

in a printed book.

The five possible arguments for a cross reference are:

  1. The node name (required). This is the node to which the cross reference takes you. In a printed document, the location of the node provides the page reference only for references within the same document.
  2. The cross reference name for the Info reference, if it is to be different from the node name. If you include this argument, it becomes the first part of the cross reference. It is usually omitted.
  3. A topic description or section name. Often, this is the title of the section. This is used as the name of the reference in the printed manual. If omitted, the node name is used.
  4. The name of the Info file in which the reference is located, if it is different from the current file. You need not include any `.info' suffix on the file name, since Info readers try appending it automatically.
  5. The name of a printed manual from a different Texinfo file.

The template for a full five argument cross reference looks like this:

@xref{node-name, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

Cross references with one, two, three, four, and five arguments are described separately following the description of @xref.

Write a node name in a cross reference in exactly the same way as in the @node line, including the same capitalization; otherwise, the formatters may not find the reference.

You can write cross reference commands within a paragraph, but note how Info and TeX format the output of each of the various commands: write @xref at the beginning of a sentence; write @pxref only within parentheses, and so on.

@xref

The @xref command generates a cross reference for the beginning of a sentence. The Info formatting commands convert it into an Info cross reference, which the Info `f' command can use to bring you directly to another node. The TeX typesetting commands convert it into a page reference, or a reference to another book or manual.

  • One Argument: @xref with one argument.
  • Two Arguments: @xref with two arguments.
  • Three Arguments: @xref with three arguments.
  • Four and Five Arguments: @xref with four and five arguments.

Most often, an Info cross reference looks like this:

*Note node-name::.

or like this

*Note cross-reference-name: node-name.

In TeX, a cross reference looks like this:

See Section section-number [node-name], page page.

or like this

See Section section-number [title-or-topic], page page.

The @xref command does not generate a period or comma to end the cross reference in either the Info file or the printed output. You must write that period or comma yourself; otherwise, Info will not recognize the end of the reference. (The @pxref command works differently. See section @pxref.)

Please note: A period or comma must follow the closing brace of an @xref. It is required to terminate the cross reference. This period or comma will appear in the output, both in the Info file and in the printed manual.

@xref must refer to an Info node by name. Use @node to define the node (see section How to Write an @node Line).

@xref is followed by several arguments inside braces, separated by commas. Whitespace before and after these commas is ignored.

A cross reference requires only the name of a node; but it may contain up to four additional arguments. Each of these variations produces a cross reference that looks somewhat different.

Please note: Commas separate arguments in a cross reference; avoid including them in the title or other part lest the formatters mistake them for separators.

@xref with One Argument

The simplest form of @xref takes one argument, the name of another node in the same Info file. The Info formatters produce output that the Info readers can use to jump to the reference; TeX produces output that specifies the page and section number for you.

For example,

@xref{Tropical Storms}.

produces

*Note Tropical Storms::.

and

See Section 3.1 [Tropical Storms], page 24.

(Note that in the preceding example the closing brace is followed by a period.)

You can write a clause after the cross reference, like this:

@xref{Tropical Storms}, for more info.

which produces

*Note Tropical Storms::, for more info.

See Section 3.1 [Tropical Storms], page 24, for more info.

(Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.)

@xref with Two Arguments

With two arguments, the second is used as the name of the Info cross reference, while the first is still the name of the node to which the cross reference points.

The template is like this:

@xref{node-name, cross-reference-name}.

For example,

@xref{Electrical Effects, Lightning}.

produces:

*Note Lightning: Electrical Effects.

and

See Section 5.2 [Electrical Effects], page 57.

(Note that in the preceding example the closing brace is followed by a period; and that the node name is printed, not the cross reference name.)

You can write a clause after the cross reference, like this:

@xref{Electrical Effects, Lightning}, for more info.

which produces

*Note Lightning: Electrical Effects, for more info.

and

See Section 5.2 [Electrical Effects], page 57, for more info.

(Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.)

@xref with Three Arguments

A third argument replaces the node name in the TeX output. The third argument should be the name of the section in the printed output, or else state the topic discussed by that section. Often, you will want to use initial upper case letters so it will be easier to read when the reference is printed. Use a third argument when the node name is unsuitable because of syntax or meaning.

Remember to avoid placing a comma within the title or topic section of a cross reference, or within any other section. The formatters divide cross references into arguments according to the commas; a comma within a title or other section will divide it into two arguments. In a reference, you need to write a title such as "Clouds, Mist, and Fog" without the commas.

Also, remember to write a comma or period after the closing brace of a @xref to terminate the cross reference. In the following examples, a clause follows a terminating comma.

The template is like this:

@xref{node-name, cross-reference-name, title-or-topic}.

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning},
for details.

produces

*Note Lightning: Electrical Effects, for details.

and

See Section 5.2 [Thunder and Lightning], page 57, for details.

If a third argument is given and the second one is empty, then the third argument serves both. (Note how two commas, side by side, mark the empty second argument.)

@xref{Electrical Effects, , Thunder and Lightning},
for details.

produces

*Note Thunder and Lightning: Electrical Effects, for details.

and

See Section 5.2 [Thunder and Lightning], page 57, for details.

As a practical matter, it is often best to write cross references with just the first argument if the node name and the section title are the same, and with the first and third arguments if the node name and title are different.

Here are several examples from The GNU Awk User's Guide:

@xref{Sample Program}.
@xref{Glossary}.
@xref{Case-sensitivity, ,Case-sensitivity in Matching}.
@xref{Close Output, , Closing Output Files and Pipes},
   for more information.
@xref{Regexp, , Regular Expressions as Patterns}.

@xref with Four and Five Arguments

In a cross reference, a fourth argument specifies the name of another Info file, different from the file in which the reference appears, and a fifth argument specifies its title as a printed manual.

Remember that a comma or period must follow the closing brace of an @xref command to terminate the cross reference. In the following examples, a clause follows a terminating comma.

The template is:

@xref{node-name, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning,
weather, An Introduction to Meteorology}, for details.

produces

*Note Lightning: (weather)Electrical Effects, for details.

The name of the Info file is enclosed in parentheses and precedes the name of the node.

In a printed manual, the reference looks like this:

See section "Thunder and Lightning" in An Introduction to Meteorology, for details.

The title of the printed manual is typeset in italics; and the reference lacks a page number since TeX cannot know to which page a reference refers when that reference is to another manual.

Often, you will leave out the second argument when you use the long version of @xref. In this case, the third argument, the topic description, will be used as the cross reference name in Info.

The template looks like this:

@xref{node-name, , title-or-topic, info-file-name,
printed-manual-title}, for details.

which produces

*Note title-or-topic: (info-file-name)node-name, for details.

and

See section title-or-topic in printed-manual-title, for details.

For example,

@xref{Electrical Effects, , Thunder and Lightning,
weather, An Introduction to Meteorology}, for details.

produces

*Note Thunder and Lightning: (weather)Electrical Effects,
for details.

and

See section "Thunder and Lightning" in An Introduction to Meteorology, for details.

On rare occasions, you may want to refer to another Info file that is within a single printed manual--when multiple Texinfo files are incorporated into the same TeX run but make separate Info files. In this case, you need to specify only the fourth argument, and not the fifth.

Naming a `Top' Node

In a cross reference, you must always name a node. This means that in order to refer to a whole manual, you must identify the `Top' node by writing it as the first argument to the @xref command. (This is different from the way you write a menu entry; see section Referring to Other Info Files.) At the same time, to provide a meaningful section topic or title in the printed cross reference (instead of the word `Top'), you must write an appropriate entry for the third argument to the @xref command.

Thus, to make a cross reference to The GNU Make Manual, write:

@xref{Top, , Overview, make, The GNU Make Manual}.

which produces

*Note Overview: (make)Top.

and

See section "Overview" in The GNU Make Manual.

In this example, `Top' is the name of the first node, and `Overview' is the name of the first section of the manual.

@ref

@ref is nearly the same as @xref except that it does not generate a `See' in the printed output, just the reference itself. This makes it useful as the last part of a sentence.

For example,

For more information, see @ref{Hurricanes}.

produces

For more information, see *Note Hurricanes.

and

For more information, see Section 8.2 [Hurricanes], page 123.

The @ref command sometimes leads writers to express themselves in a manner that is suitable for a printed manual but looks awkward in the Info format. Bear in mind that your audience will be using both the printed and the Info format.

For example,

Sea surges are described in @ref{Hurricanes}.

produces

Sea surges are described in Section 6.7 [Hurricanes], page 72.

in a printed document, and the following in Info:

Sea surges are described in *Note Hurricanes::.

Caution: You must write a period or comma immediately after an @ref command with two or more arguments. Otherwise, Info will not find the end of the cross reference entry and its attempt to follow the cross reference will fail. As a general rule, you should write a period or comma after every @ref command. This looks best in both the printed and the Info output.

@pxref

The parenthetical reference command, @pxref, is nearly the same as @xref, but you use it only inside parentheses and you do not type a comma or period after the command's closing brace. The command differs from @xref in two ways:

  1. TeX typesets the reference for the printed manual with a lower case `see' rather than an upper case `See'.
  2. The Info formatting commands automatically end the reference with a closing colon or period.

Because one type of formatting automatically inserts closing punctuation and the other does not, you should use @pxref only inside parentheses as part of another sentence. Also, you yourself should not insert punctuation after the reference, as you do with @xref.

@pxref is designed so that the output looks right and works right between parentheses both in printed output and in an Info file. In a printed manual, a closing comma or period should not follow a cross reference within parentheses; such punctuation is wrong. But in an Info file, suitable closing punctuation must follow the cross reference so Info can recognize its end. @pxref spares you the need to use complicated methods to put a terminator into one form of the output and not the other.

With one argument, a parenthetical cross reference looks like this:

... storms cause flooding (@pxref{Hurricanes}) ...

which produces

... storms cause flooding (*Note Hurricanes::) ...

and

... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ...

With two arguments, a parenthetical cross reference has this template:

... (@pxref{node-name, cross-reference-name}) ...

which produces

... (*Note cross-reference-name: node-name.) ...

and

... (see Section nnn [node-name], page ppp) ...

@pxref can be used with up to five arguments just like @xref (see section @xref).

Please note: Use @pxref only as a parenthetical reference. Do not try to use @pxref as a clause in a sentence. It will look bad in either the Info file, the printed output, or both.

Also, parenthetical cross references look best at the ends of sentences. Although you may write them in the middle of a sentence, that location breaks up the flow of text.

@inforef

@inforef is used for cross references to Info files for which there are no printed manuals. Even in a printed manual, @inforef generates a reference directing the user to look in an Info file.

The command takes either two or three arguments, in the following order:

  1. The node name.
  2. The cross reference name (optional).
  3. The Info file name.

Separate the arguments with commas, as with @xref. Also, you must terminate the reference with a comma or period after the `}', as you do with @xref.

The template is:

@inforef{node-name, cross-reference-name, info-file-name},

Thus,

@inforef{Expert, Advanced Info commands, info},
for more information.

produces

*Note Advanced Info commands: (info)Expert,
for more information.

and

See Info file `info', node `Expert', for more information.

Similarly,

@inforef{Expert, , info}, for more information.

produces

*Note (info)Expert::, for more information.

and

See Info file `info', node `Expert', for more information.

The converse of @inforef is @cite, which is used to refer to printed works for which no Info form exists. See section @cite{reference}.

@uref{url[, displayed-text]}

@uref produces a reference to a uniform resource locator (URL). It takes one mandatory argument, the URL, and one optional argument, the text to display (the default is the URL itself). In HTML output, @uref produces a link you can follow. For example:

The official GNU ftp site is
@uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}

produces (in text):

The official GNU ftp site is
ftp://ftp.gnu.ai.mit.edu/pub/gnu

whereas

The official
@uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
  GNU ftp site} holds programs and texts.

produces (in text):

The official GNU ftp site holds
programs and texts.

and (in HTML):

The official GNU ftp
site holds programs and texts.

To merely indicate a URL, use @url (see section @url{uniform-resource-locator}).

Marking Words and Phrases

In Texinfo, you can mark words and phrases in a variety of ways. The Texinfo formatters use this information to determine how to highlight the text. You can specify, for example, whether a word or phrase is a defining occurrence, a metasyntactic variable, or a symbol used in a program. Also, you can emphasize text.

  • Indicating: How to indicate definitions, files, etc.
  • Emphasis: How to emphasize text.

Indicating Definitions, Commands, etc.

Texinfo has commands for indicating just what kind of object a piece of text refers to. For example, metasyntactic variables are marked by @var, and code by @code. Since the pieces of text are labelled by commands that tell what kind of object they are, it is easy to change the way the Texinfo formatters prepare such text. (Texinfo is an intentional formatting language rather than a typesetting formatting language.)

For example, in a printed manual, code is usually illustrated in a typewriter font; @code tells TeX to typeset this text in this font. But it would be easy to change the way TeX highlights code to use another font, and this change would not effect how keystroke examples are highlighted. If straight typesetting commands were used in the body of the file and you wanted to make a change, you would need to check every single occurrence to make sure that you were changing code and not something else that should not be changed.

  • code: How to indicate code.
  • kbd: How to show keyboard input.
  • key: How to specify keys.
  • samp: How to show a literal sequence of characters.
  • var: How to indicate a metasyntactic variable.
  • file: How to indicate the name of a file.
  • dfn: How to specify a definition.
  • cite: How to refer to a book that is not in Info.
  • url: How to indicate a world wide web reference.
  • email: How to indicate an electronic mail address.

The highlighting commands can be used to generate useful information from the file, such as lists of functions or file names. It is possible, for example, to write a program in Emacs Lisp (or a keyboard macro) to insert an index entry after every paragraph that contains words or phrases marked by a specified command. You could do this to construct an index of functions if you had not already made the entries.

The commands serve a variety of purposes:

@code{sample-code}
Indicate text that is a literal example of a piece of a program.
@kbd{keyboard-characters}
Indicate keyboard input.
@key{key-name}
Indicate the conventional name for a key on a keyboard.
@samp{text}
Indicate text that is a literal example of a sequence of characters.
@var{metasyntactic-variable}
Indicate a metasyntactic variable.
@url{uniform-resource-locator}
Indicate a uniform resource locator for the World Wide Web.
@file{file-name}
Indicate the name of a file.
@email{email-address[, displayed-text]}
Indicate an electronic mail address.
@dfn{term}
Indicate the introductory or defining use of a term.
@cite{reference}
Indicate the name of a book.

@code{sample-code}

Use the @code command to indicate text that is a piece of a program and which consists of entire syntactic tokens. Enclose the text in braces.

Thus, you should use @code for an expression in a program, for the name of a variable or function used in a program, or for a keyword. Also, you should use @code for the name of a program, such as diff, that is a name used in the machine. (You should write the name of a program in the ordinary text font if you regard it as a new English word, such as `Emacs' or `Bison'.)

Use @code for environment variables such as TEXINPUTS, and other variables.

Use @code for command names in command languages that resemble programming languages, such as Texinfo or the shell. For example, @code and @samp are produced by writing `@code{@@code}' and `@code{@@samp}' in the Texinfo source, respectively.

Note, however, that you should not use @code for shell options such as `-c' when such options stand alone. (Use @samp.) Also, an entire shell command often looks better if written using @samp rather than @code. In this case, the rule is to choose the more pleasing format.

It is incorrect to alter the case of a word inside an @code command when it appears at the beginning of a sentence. Most computer languages are case sensitive. In C, for example, Printf is different from the identifier printf, and most likely is a misspelling of it. Even in languages which are not case sensitive, it is confusing to a human reader to see identifiers spelled in different ways. Pick one spelling and always use that. If you do not want to start a sentence with a command written all in lower case, you should rearrange the sentence.

Do not use the @code command for a string of characters shorter than a syntactic token. If you are writing about `TEXINPU', which is just a part of the name for the TEXINPUTS environment variable, you should use @samp.

In particular, you should not use the @code command when writing about the characters used in a token; do not, for example, use @code when you are explaining what letters or printable symbols can be used in the names of functions. (Use @samp.) Also, you should not use @code to mark text that is considered input to programs unless the input is written in a language that is like a programming language. For example, you should not use @code for the keystroke commands of GNU Emacs (use @kbd instead) although you may use @code for the names of the Emacs Lisp functions that the keystroke commands invoke.

In the printed manual, @code causes TeX to typeset the argument in a typewriter face. In the Info file, it causes the Info formatting commands to use single quotation marks around the text.

For example,

Use @code{diff} to compare two files.

produces this in the printed manual:

Use diff to compare two files.

and this in the Info file:

Use `diff' to compare two files.

@kbd{keyboard-characters}

Use the @kbd command for characters of input to be typed by users. For example, to refer to the characters M-a, write

@kbd{M-a}

and to refer to the characters M-x shell, write

@kbd{M-x shell}

The @kbd command has the same effect as @code in Info, but by default produces a different font (slanted typewriter instead of normal typewriter) in the printed manual, so users can distinguish the characters they are supposed to type from those the computer outputs.

Since the usage of @kbd varies from manual to manual, you can control the font switching with the @kbdinputstyle command. This command has no effect on Info output. Write this command at the beginning of a line with a single word as an argument, one of the following:

`code'
Always use the same font for @kbd as @code.
`example'
Use the distinguishing font for @kbd only in @example and similar environments.
`example'
(the default) Always use the distinguishing font for @kbd.

You can embed another @-command inside the braces of an @kbd command. Here, for example, is the way to describe a command that would be described more verbosely as "press an `r' and then press the RET key":

@kbd{r @key{RET}}

This produces: r RET

You also use the @kbd command if you are spelling out the letters you type; for example:

To give the @code{logout} command,
type the characters @kbd{l o g o u t @key{RET}}.

This produces:

To give the logout command, type the characters l o g o u t RET.

(Also, this example shows that you can add spaces for clarity. If you really want to mention a space character as one of the characters of input, write @key{SPC} for it.)

@key{key-name}

Use the @key command for the conventional name for a key on a keyboard, as in:

@key{RET}

You can use the @key command within the argument of an @kbd command when the sequence of characters to be typed includes one or more keys that are described by name.

For example, to produce C-x ESC you would type:

@kbd{C-x @key{ESC}}

Here is a list of the recommended names for keys:

SPC
Space
RET
Return
LFD
Linefeed (however, since most keyboards nowadays do not have a Linefeed key, it might be better to call this character C-j.
TAB
Tab
BS
Backspace
ESC
Escape
DEL
Delete
SHIFT
Shift
CTRL
Control
META
Meta

There are subtleties to handling words like `meta' or `ctrl' that are names of modifier keys. When mentioning a character in which the modifier key is used, such as Meta-a, use the @kbd command alone; do not use the @key command; but when you are referring to the modifier key in isolation, use the @key command. For example, write `@kbd{Meta-a}' to produce Meta-a and `@key{META}' to produce META.

@samp{text}

Use the @samp command to indicate text that is a literal example or `sample' of a sequence of characters in a file, string, pattern, etc. Enclose the text in braces. The argument appears within single quotation marks in both the Info file and the printed manual; in addition, it is printed in a fixed-width font.

To match @samp{foo} at the end of the line,
use the regexp @samp{foo$}.

produces

To match `foo' at the end of the line, use the regexp `foo$'.

Any time you are referring to single characters, you should use @samp unless @kbd or @key is more appropriate. Use @samp for the names of command-line options (except in an @table, where @code seems to read more easily). Also, you may use @samp for entire statements in C and for entire shell commands--in this case, @samp often looks better than @code. Basically, @samp is a catchall for whatever is not covered by @code, @kbd, or @key.

Only include punctuation marks within braces if they are part of the string you are specifying. Write punctuation marks outside the braces if those punctuation marks are part of the English text that surrounds the string. In the following sentence, for example, the commas and period are outside of the braces:

In English, the vowels are @samp{a}, @samp{e},
@samp{i}, @samp{o}, @samp{u}, and sometimes
@samp{y}.

This produces:

In English, the vowels are `a', `e', `i', `o', `u', and sometimes `y'.

@var{metasyntactic-variable}

Use the @var command to indicate metasyntactic variables. A metasyntactic variable is something that stands for another piece of text. For example, you should use a metasyntactic variable in the documentation of a function to describe the arguments that are passed to that function.

Do not use @var for the names of particular variables in programming languages. These are specific names from a program, so @code is correct for them. For example, the Emacs Lisp variable texinfo-tex-command is not a metasyntactic variable; it is properly formatted using @code.

The effect of @var in the Info file is to change the case of the argument to all upper case; in the printed manual, to italicize it.

For example,

To delete file @var{filename},
type @code{rm @var{filename}}.

produces

To delete file filename, type rm filename.

(Note that @var may appear inside @code, @samp, @file, etc.)

Write a metasyntactic variable all in lower case without spaces, and use hyphens to make it more readable. Thus, the Texinfo source for the illustration of how to begin a Texinfo manual looks like this:

\input texinfo
@@setfilename @var{info-file-name}
@@settitle @var{name-of-manual}

This produces:

\input texinfo
@setfilename info-file-name
@settitle name-of-manual

In some documentation styles, metasyntactic variables are shown with angle brackets, for example:

..., type rm <filename>

However, that is not the style that Texinfo uses. (You can, of course, modify the sources to TeX and the Info formatting commands to output the <...> format if you wish.)

@file{file-name}

Use the @file command to indicate text that is the name of a file, buffer, or directory, or is the name of a node in Info. You can also use the command for file name suffixes. Do not use @file for symbols in a programming language; use @code.

Currently, @file is equivalent to @samp in its effects. For example,

The @file{.el} files are in
the @file{/usr/local/emacs/lisp} directory.

produces

The `.el' files are in the `/usr/local/emacs/lisp' directory.

@dfn{term}

Use the @dfn command to identify the introductory or defining use of a technical term. Use the command only in passages whose purpose is to introduce a term which will be used again or which the reader ought to know. Mere passing mention of a term for the first time does not deserve @dfn. The command generates italics in the printed manual, and double quotation marks in the Info file. For example:

Getting rid of a file is called @dfn{deleting} it.

produces

Getting rid of a file is called deleting it.

As a general rule, a sentence containing the defining occurrence of a term should be a definition of the term. The sentence does not need to say explicitly that it is a definition, but it should contain the information of a definition--it should make the meaning clear.

@cite{reference}

Use the @cite command for the name of a book that lacks a companion Info file. The command produces italics in the printed manual, and quotation marks in the Info file.

(If a book is written in Texinfo, it is better to use a cross reference command since a reader can easily follow such a reference in Info. See section @xref.)

@url{uniform-resource-locator}

Use the @url to indicate a uniform resource locator on the World Wide Web. This is analogous to @file, @var, etc., and is purely for markup purposes. It does not produce a link you can follow in HTML output (the @uref command does, see section @uref{url[, displayed-text]}). It is useful for example URL's which do not actually exist. For example:

For example, the url might be
@url{http://host.domain.org/path}.

@email{email-address[, displayed-text]}

Use the @email command to indicate an electronic mail address. It takes one mandatory argument, the address, and one optional argument, the text to display (the default is the address itself).

In Info and TeX, the address is shown in angle brackets, preceded by the text to display if any. In HTML output, @email produces a `mailto' link that usually brings up a mail composition window. For example:

Send bug reports to @email{bug-texinfo@@gnu.org}.
Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.

produces

Send bug reports to bug-texinfo@gnu.org.
Send suggestions to the same place.

Emphasizing Text

Usually, Texinfo changes the font to mark words in the text according to what category the words belong to; an example is the @code command. Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two commands to do this. Also, Texinfo has several commands that specify the font in which TeX will typeset text. These commands have no affect on Info and only one of them, the @r command, has any regular use.

  • emph & strong: How to emphasize text in Texinfo.
  • Smallcaps: How to use the small caps font.
  • Fonts: Various font commands for printed output.
  • Customized Highlighting: How to define highlighting commands.

@emph{text} and @strong{text}

The @emph and @strong commands are for emphasis; @strong is stronger. In printed output, @emph produces italics and @strong produces bold.

For example,

@quotation
@strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
files in the directory.
@end quotation

produces the following in printed output:

Caution: rm * .[^.]* removes all files in the directory.

and the following in Info:

     *Caution*: `rm * .[^.]*' removes *all*
     files in the directory.

The @strong command is seldom used except to mark what is, in effect, a typographical element, such as the word `Caution' in the preceding example.

In the Info file, both @emph and @strong put asterisks around the text.

Caution: Do not use @emph or @strong with the word `Note'; Info will mistake the combination for a cross reference. Use a phrase such as Please note or Caution instead.

@sc{text}: The Small Caps Font

Use the `@sc' command to set text in the printed output in A SMALL CAPS FONT and set text in the Info file in upper case letters.

Write the text between braces in lower case, like this:

The @sc{acm} and @sc{ieee} are technical societies.

This produces:

The ACM and IEEE are technical societies.

TeX typesets the small caps font in a manner that prevents the letters from `jumping out at you on the page'. This makes small caps text easier to read than text in all upper case. The Info formatting commands set all small caps text in upper case.

If the text between the braces of an @sc command is upper case, TeX typesets in FULL-SIZE CAPITALS. Use full-size capitals sparingly.

You may also use the small caps font for a jargon word such as ATO (a NASA word meaning `abort to orbit').

There are subtleties to using the small caps font with a jargon word such as CDR, a word used in Lisp programming. In this case, you should use the small caps font when the word refers to the second and subsequent elements of a list (the CDR of the list), but you should use `@code' when the word refers to the Lisp function of the same spelling.

Fonts for Printing, Not Info

Texinfo provides four font commands that specify font changes in the printed manual but have no effect in the Info file. @i requests italic font (in some versions of TeX, a slanted font is used), @b requests bold face, @t requests the fixed-width, typewriter-style font used by @code, and @r requests a roman font, which is the usual font in which text is printed. All four commands apply to an argument that follows, surrounded by braces.

Only the @r command has much use: in example programs, you can use the @r command to convert code comments from the fixed-width font to a roman font. This looks better in printed output.

For example,

@lisp
(+ 2 2)    ; @r{Add two plus two.}
@end lisp

produces

(+ 2 2)    ; Add two plus two.

If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo language.

Customized Highlighting

You can use regular TeX commands inside of @iftex ... @end iftex to create your own customized highlighting commands for Texinfo. The easiest way to do this is to equate your customized commands with pre-existing commands, such as those for italics. Such new commands work only with TeX.

You can use the @definfoenclose command inside of @ifinfo ... @end ifinfo to define commands for Info with the same names as new commands for TeX. @definfoenclose creates new commands for Info that mark text by enclosing it in strings that precede and follow the text. (7)

Here is how to create a new @-command called @phoo that causes TeX to typeset its argument in italics and causes Info to display the argument between `//' and `\\'.

For TeX, write the following to equate the @phoo command with the existing @i italics command:

@iftex
@global@let@phoo=@i
@end iftex

This defines @phoo as a command that causes TeX to typeset the argument to @phoo in italics. @global@let tells TeX to equate the next argument with the argument that follows the equals sign.

For Info, write the following to tell the Info formatters to enclose the argument between `//' and `\\':

@ifinfo
@definfoenclose phoo, //, \\
@end ifinfo

Write the @definfoenclose command on a line and follow it with three arguments separated by commas (commas are used as separators in an @node line in the same way).

  • The first argument to @definfoenclose is the @-command name without the `@';
  • the second argument is the Info start delimiter string; and,
  • the third argument is the Info end delimiter string.

The latter two arguments enclose the highlighted text in the Info file. A delimiter string may contain spaces. Neither the start nor end delimiter is required. However, if you do not provide a start delimiter, you must follow the command name with two commas in a row; otherwise, the Info formatting commands will misinterpret the end delimiter string as a start delimiter string.

After you have defined @phoo both for TeX and for Info, you can then write @phoo{bar} to see `//bar\\' in Info and see bar in italics in printed output.

Note that each definition applies to its own formatter: one for TeX, the other for Info.

Here is another example:

@ifinfo
@definfoenclose headword, , :
@end ifinfo
@iftex
@global@let@headword=@b
@end iftex

This defines @headword as an Info formatting command that inserts nothing before and a colon after the argument and as a TeX formatting command to typeset its argument in bold.

Quotations and Examples

Quotations and examples are blocks of text consisting of one or more whole paragraphs that are set off from the bulk of the text and treated differently. They are usually indented.

In Texinfo, you always begin a quotation or example by writing an @-command at the beginning of a line by itself, and end it by writing an @end command that is also at the beginning of a line by itself. For instance, you begin an example by writing @example by itself at the beginning of a line and end the example by writing @end example on a line by itself, at the beginning of that line.

  • Block Enclosing Commands: Use different constructs for different purposes.
  • quotation: How to write a quotation.
  • example: How to write an example in a fixed-width font.
  • noindent: How to prevent paragraph indentation.
  • Lisp Example: How to illustrate Lisp code.
  • smallexample & smalllisp: Forms for the @smallbook option.
  • display: How to write an example in the current font.
  • format: How to write an example that does not narrow the margins.
  • exdent: How to undo the indentation of a line.
  • flushleft & flushright: How to push text flushleft or flushright.
  • cartouche: How to draw cartouches around examples.

The Block Enclosing Commands

Here are commands for quotations and examples:

@quotation
Indicate text that is quoted. The text is filled, indented, and printed in a roman font by default.
@example
Illustrate code, commands, and the like. The text is printed in a fixed-width font, and indented but not filled.
@lisp
Illustrate Lisp code. The text is printed in a fixed-width font, and indented but not filled.
@smallexample
Illustrate code, commands, and the like. Similar to @example, except that in TeX this command typesets text in a smaller font for the smaller @smallbook format than for the 8.5 by 11 inch format.
@smalllisp
Illustrate Lisp code. Similar to @lisp, except that in TeX this command typesets text in a smaller font for the smaller @smallbook format than for the 8.5 by 11 inch format.
@display
Display illustrative text. The text is indented but not filled, and no font is specified (so, by default, the font is roman).
@format
Print illustrative text. The text is not indented and not filled and no font is specified (so, by default, the font is roman).

The @exdent command is used within the above constructs to undo the indentation of a line.

The @flushleft and @flushright commands are used to line up the left or right margins of unfilled text.

The @noindent command may be used after one of the above constructs to prevent the following text from being indented as a new paragraph.

You can use the @cartouche command within one of the above constructs to highlight the example or quotation by drawing a box with rounded corners around it. (The @cartouche command affects only the printed manual; it has no effect in the Info file; see section Drawing Cartouches Around Examples.)

@quotation

The text of a quotation is processed normally except that:

  • the margins are closer to the center of the page, so the whole of the quotation is indented;
  • the first lines of paragraphs are indented no more than other lines;
  • in the printed output, interparagraph spacing is reduced.

This is an example of text written between an @quotation command and an @end quotation command. An @quotation command is most often used to indicate text that is excerpted from another (real or hypothetical) printed work.

Write an @quotation command as text on a line by itself. This line will disappear from the output. Mark the end of the quotation with a line beginning with and containing only @end quotation. The @end quotation line will likewise disappear from the output. Thus, the following,

@quotation
This is
a foo.
@end quotation

produces

This is a foo.

@example

The @example command is used to indicate an example that is not part of the running text, such as computer input or output.

This is an example of text written between an
@example command
and an @end example command.
The text is indented but not filled.

In the printed manual, the text is typeset in a
fixed-width font, and extra spaces and blank lines are
significant.  In the Info file, an analogous result is
obtained by indenting each line with five spaces.

Write an @example command at the beginning of a line by itself. This line will disappear from the output. Mark the end of the example with an @end example command, also written at the beginning of a line by itself. The @end example will disappear from the output.

For example,

@example
mv foo bar
@end example

produces

mv foo bar

Since the lines containing @example and @end example will disappear, you should put a blank line before the @example and another blank line after the @end example. (Remember that blank lines between the beginning @example and the ending @end example will appear in the output.)

Caution: Do not use tabs in the lines of an example (or anywhere else in Texinfo, for that matter)! TeX treats tabs as single spaces, and that is not what they look like. This is a problem with TeX. (If necessary, in Emacs, you can use M-x untabify to convert tabs in a region to multiple spaces.)

Examples are often, logically speaking, "in the middle" of a paragraph, and the text continues after an example should not be indented. The @noindent command prevents a piece of text from being indented as if it were a new paragraph.

(The @code command is used for examples of code that are embedded within sentences, not set off from preceding and following text. See section @code{sample-code}.)

@noindent

An example or other inclusion can break a paragraph into segments. Ordinarily, the formatters indent text that follows an example as a new paragraph. However, you can prevent this by writing @noindent at the beginning of a line by itself preceding the continuation text.

For example:

@example
This is an example
@end example

@noindent
This line is not indented.  As you can see, the
beginning of the line is fully flush left with the line
that follows after it.  (This whole example is between
@code{@@display} and @code{@@end display}.)

produces

This is an example

This line is not indented.  As you can see, the
beginning of the line is fully flush left with the line
that follows after it.  (This whole example is between
@display and @end display.)

To adjust the number of blank lines properly in the Info file output, remember that the line containing @noindent does not generate a blank line, and neither does the @end example line.

In the Texinfo source file for this manual, each line that says `produces' is preceded by a line containing @noindent.

Do not put braces after an @noindent command; they are not necessary, since @noindent is a command used outside of paragraphs (see section @-Command Syntax).

@lisp

The @lisp command is used for Lisp code. It is synonymous with the @example command.

This is an example of text written between an
@lisp command and an @end lisp command.

Use @lisp instead of @example to preserve information regarding the nature of the example. This is useful, for example, if you write a function that evaluates only and all the Lisp code in a Texinfo file. Then you can use the Texinfo file as a Lisp library.(8)

Mark the end of @lisp with @end lisp on a line by itself.

@smallexample and @smalllisp

In addition to the regular @example and @lisp commands, Texinfo has two other "example-style" commands. These are the @smallexample and @smalllisp commands. Both these commands are designed for use with the @smallbook command that causes TeX to produce a printed manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format.

In TeX, the @smallexample and @smalllisp commands typeset text in a smaller font for the smaller @smallbook format than for the 8.5 by 11 inch format. Consequently, many examples containing long lines fit in a narrower, @smallbook page without needing to be shortened. Both commands typeset in the normal font size when you format for the 8.5 by 11 inch size; indeed, in this situation, the @smallexample and @smalllisp commands are defined to be the @example and @lisp commands.

In Info, the @smallexample and @smalllisp commands are equivalent to the @example and @lisp commands, and work exactly the same.

Mark the end of @smallexample or @smalllisp with @end smallexample or @end smalllisp, respectively.

Here is an example written in the small font used by the @smallexample and @smalllisp commands:

The @smallexample and @smalllisp commands make it
easier to prepare smaller format manuals without forcing you to edit
examples by hand to fit them onto narrower pages.

As a general rule, a printed document looks better if you write all the
examples in a chapter consistently in @example or in
@smallexample.  Only occasionally should you mix the two
formats.

See section Printing "Small" Books, for more information
about the @smallbook command.

@display

The @display command begins a kind of example.  It is like the
@example command
except that, in
a printed manual, @display does not select the fixed-width
font.  In fact, it does not specify the font at all, so that the text
appears in the same font it would have appeared in without the
@display command.

This is an example of text written between an @display command
and an @end display command.  The @display command
indents the text, but does not fill it.

@format

The @format command is similar to @example except
that, in the printed manual, @format does not select the
fixed-width font and does not narrow the margins.

This is an example of text written between an @format command
and an @end format command.  As you can see
from this example,
the @format command does not fill the text.

@exdent: Undoing a Line's Indentation

The @exdent command removes any indentation a line might have.
The command is written at the beginning of a line and applies only to
the text that follows the command that is on the same line.  Do not use
braces around the text.  In a printed manual, the text on an
@exdent line is printed in the roman font.

@exdent is usually used within examples.  Thus,

@example
This line follows an @@example command.
@exdent This line is exdented.
This line follows the exdented line.
The @@end example comes on the next line.
@end group

produces

This line follows an @example command.
This line is exdented.
This line follows the exdented line.
The @end example comes on the next line.

In practice, the @exdent command is rarely used.
Usually, you un-indent text by ending the example and
returning the page to its normal width.

@flushleft and @flushright

The @flushleft and @flushright commands line up the
ends of lines on the left and right margins of a page,
but do not fill the text.  The commands are written on lines of their
own, without braces.  The @flushleft and @flushright
commands are ended by @end flushleft and @end
flushright commands on lines of their own.

For example,

@flushleft
This text is
written flushleft.
@end flushleft

produces

This text is
written flushleft.

@flushright produces the type of indentation often used in the
return address of letters.  For example,

@flushright
Here is an example of text written
flushright.  The @code{@flushright} command
right justifies every line but leaves the
left end ragged.
@end flushright

produces

Here is an example of text written
flushright.  The @flushright command
right justifies every line but leaves the
left end ragged.

Drawing Cartouches Around Examples

In a printed manual, the @cartouche command draws a box with
rounded corners around its contents.  You can use this command to
further highlight an example or quotation.  For instance, you could
write a manual in which one type of example is surrounded by a cartouche
for emphasis.

The @cartouche command affects only the printed manual; it has
no effect in the Info file.

For example,

@example
@cartouche
% pwd
/usr/local/share/emacs
@end cartouche
@end example

surrounds the two-line example with a box with rounded corners, in the
printed manual.

In a printed manual, the example looks like this:

% pwd
/usr/local/lib/emacs/info

Lists and Tables

Texinfo has several ways of making lists and tables.  Lists can be
bulleted or numbered; two-column tables can highlight the items in
the first column; multi-column tables are also supported.

  • itemize: How to construct a simple list.

  • enumerate: How to construct a numbered list.

  • Two-column Tables: How to construct a two-column table.

  • Multi-column Tables: How to construct generalized tables.

Texinfo automatically indents the text in lists or tables, and numbers
an enumerated list.  This last feature is useful if you modify the
list, since you do not need to renumber it yourself.

Numbered lists and tables begin with the appropriate @-command at the
beginning of a line, and end with the corresponding @end
command on a line by itself.  The table and itemized-list commands
also require that you write formatting information on the same line as
the beginning @-command.

Begin an enumerated list, for example, with an @enumerate
command and end the list with an @end enumerate command.
Begin an itemized list with an @itemize command, followed on
the same line by a formatting command such as @bullet, and end
the list with an @end itemize command.

Precede each element of a list with an @item or @itemx
command.

Here is an itemized list of the different kinds of table and lists:

  •

Itemized lists with and without bullets.

  •

Enumerated lists, using numbers or letters.

  •

Two-column tables with highlighting.

Here is an enumerated list with the same items:

  1.

Itemized lists with and without bullets.

  2.

Enumerated lists, using numbers or letters.

  3.

Two-column tables with highlighting.

And here is a two-column table with the same items and their
@-commands:

@itemize

Itemized lists with and without bullets.

@enumerate

Enumerated lists, using numbers or letters.

@table

@ftable

@vtable

Two-column tables with indexing.

Making an Itemized List

The @itemize command produces sequences of indented
paragraphs, with a bullet or other mark inside the left margin
at the beginning of each paragraph for which such a mark is desired.

Begin an itemized list by writing @itemize at the beginning of
a line.  Follow the command, on the same line, with a character or a
Texinfo command that generates a mark.  Usually, you will write
@bullet after @itemize, but you can use
@minus, or any character or any special symbol that results in
a single character in the Info file.  (When you write @bullet
or @minus after an @itemize command, you may omit the
`{}'.)

Write the text of the indented paragraphs themselves after the
@itemize, up to another line that says @end
itemize.

Before each paragraph for which a mark in the margin is desired, write
a line that says just @item.  Do not write any other text on this
line.

Usually, you should put a blank line before an @item.  This
puts a blank line in the Info file. (TeX inserts the proper
interline whitespace in either case.)  Except when the entries are
very brief, these blank lines make the list look better.

Here is an example of the use of @itemize, followed by the
output it produces.  Note that @bullet produces an `*' in
Info and a round dot in TeX.

@itemize @bullet
@item
Some text for foo.

@item
Some text
for bar.
@end itemize

This produces:

  •

Some text for foo.

  •

Some text
for bar.

Itemized lists may be embedded within other itemized lists.  Here is a
list marked with dashes embedded in a list marked with bullets:

@itemize @bullet
@item
First item.

@itemize @minus
@item
Inner item.

@item
Second inner item.
@end itemize

@item
Second outer item.
@end itemize

This produces:

  •

First item.

    •

Inner item.

    •

Second inner item.

  •

Second outer item.

Making a Numbered or Lettered List

@enumerate is like @itemize (see section Making an Itemized List), except that the labels on the items are
successive integers or letters instead of bullets.

Write the @enumerate command at the beginning of a line.  The
command does not require an argument, but accepts either a number or a
letter as an option.  Without an argument, @enumerate starts the
list with the number `1'.  With a numeric argument, such as
`3', the command starts the list with that number.  With an upper
or lower case letter, such as `a' or `A', the command starts
the list with that letter.

Write the text of the enumerated list in the same way you write an
itemized list: put @item on a line of its own before the start
of each paragraph that you want enumerated.  Do not write any other text
on the line beginning with @item.

You should put a blank line between entries in the list.
This generally makes it easier to read the Info file.

Here is an example of @enumerate without an argument:

@enumerate
@item
Underlying causes.

@item
Proximate causes.
@end enumerate

This produces:

  1.

Underlying causes.

  2.

Proximate causes.

Here is an example with an argument of 3:

@enumerate 3
@item
Predisposing causes.

@item
Precipitating causes.

@item
Perpetuating causes.
@end enumerate

This produces:

  1.

Predisposing causes.

  2.

Precipitating causes.

  3.

Perpetuating causes.

Here is a brief summary of the alternatives.  The summary is constructed
using @enumerate with an argument of a.

  1.

@enumerate

Without an argument, produce a numbered list, starting with the number
1.

  2.

@enumerate positive-integer

With a (positive) numeric argument, start a numbered list with that
number.  You can use this to continue a list that you interrupted with
other text.

  3.

@enumerate upper-case-letter

With an upper case letter as argument, start a list
in which each item is marked
by a letter, beginning with that upper case letter.

  4.

@enumerate lower-case-letter

With a lower case letter as argument, start a list
in which each item is marked by
a letter, beginning with that lower case letter.

You can also nest enumerated lists, as in an outline.

Making a Two-column Table

@table is similar to @itemize (see section Making an Itemized List), but allows you to specify a name or heading line for
each item.  The @table command is used to produce two-column
tables, and is especially useful for glossaries, explanatory
exhibits, and command-line option summaries.

  • ftable vtable: Automatic indexing for two-column tables.

  • itemx: How to put more entries in the first column.

Write the @table command at the beginning of a line and follow
it on the same line with an argument that is a Texinfo "indicating"
command such as @code, @samp, @var, or
@kbd (see section Indicating Definitions, Commands, etc.).  Although these commands are usually
followed by arguments in braces, in this case you use the command name
without an argument because @item will supply the argument.
This command will be applied to the text that goes into the first column
of each item and determines how it will be highlighted.  For example,
@code will cause the text in the first column to be highlighted
with an @code command.  (We recommend @code for
@table's of command-line options.)

You may also choose to use the @asis command as an argument to
@table.  @asis is a command that does nothing; if you
use this command after @table, TeX and the Info formatting
commands output the first column entries without added highlighting
("as is").

(The @table command may work with other commands besides those
listed here.  However, you can only use commands that normally take
arguments in braces.)

Begin each table entry with an @item command at the beginning
of a line.  Write the first column text on the same line as the
@item command.  Write the second column text on the line
following the @item line and on subsequent lines.  (You do not
need to type anything for an empty second column entry.)  You may
write as many lines of supporting text as you wish, even several
paragraphs.  But only text on the same line as the @item will
be placed in the first column.

Normally, you should put a blank line before an @item line.
This puts a blank like in the Info file.  Except when the entries are
very brief, a blank line looks better.

The following table, for example, highlights the text in the first
column with an @samp command:

@table @samp
@item foo
This is the text for
@samp{foo}.

@item bar
Text for @samp{bar}.
@end table

This produces:

`foo'

This is the text for
`foo'.

`bar'

Text for `bar'.

If you want to list two or more named items with a single block of
text, use the @itemx command.  (See section @itemx.)

@ftable and @vtable

The @ftable and @vtable commands are the same as the
@table command except that @ftable automatically enters
each of the items in the first column of the table into the index of
functions and @vtable automatically enters each of the items in
the first column of the table into the index of variables.  This
simplifies the task of creating indices.  Only the items on the same
line as the @item commands are indexed, and they are indexed in
exactly the form that they appear on that line.  See section Creating Indices, for more information about indices.

Begin a two-column table using @ftable or @vtable by
writing the @-command at the beginning of a line, followed on the same
line by an argument that is a Texinfo command such as @code,
exactly as you would for an @table command; and end the table
with an @end ftable or @end vtable command on a line by
itself.

See the example for @table in the previous section.

@itemx

Use the @itemx command inside a table when you have two or more
first column entries for the same item, each of which should appear on a
line of its own.  Use @itemx for all but the first entry;
@itemx should always follow an @item command.  The
@itemx command works exactly like @item except that it
does not generate extra vertical space above the first column text.

For example,

@table @code
@item upcase
@itemx downcase
These two functions accept a character or a string as
argument, and return the corresponding upper case (lower
case) character or string.
@end table

This produces:

upcase

downcase

These two functions accept a character or a string as
argument, and return the corresponding upper case (lower
case) character or string.

(Note also that this example illustrates multi-line supporting text in
a two-column table.)

Multi-column Tables

@multitable allows you to construct tables with any number of
columns, with each column having any width you like.

You define the column widths on the @multitable line itself, and
write each row of the actual table following an @item command,
with columns separated by an @tab command.  Finally, @end
multitable completes the table.  Details in the sections below.

  • Multitable Column Widths: Defining multitable column widths.

  • Multitable Rows: Defining multitable rows, with examples.

Multitable Column Widths

You can define the column widths for a multitable in two ways: as
fractions of the line length; or with a prototype row.  Mixing the two
methods is not supported.  In either case, the widths are defined
entirely on the same line as the @multitable command.

  1.

To specify column widths as fractions of the line length, write
@columnfractions and the decimal numbers (presumably less than
1) after the @multitable command, as in:

    @multitable @columnfractions .33 .33 .33

The fractions need not add up exactly to 1.0, as these do
not.  This allows you to produce tables that do not need the full line
length.

  2.

To specify a prototype row, write the longest entry for each column
enclosed in braces after the @multitable command.  For example:

    @multitable {some text for column one} {for column two}

The first column will then have the width of the typeset `some text for
column one', and the second column the width of `for column two'.

The prototype entries need not appear in the table itself.

Although we used simple text in this example, the prototype entries can
contain Texinfo commands; markup commands such as @code are
particularly likely to be useful.

Multitable Rows

After the @multitable command defining the column widths (see
the previous section), you begin each row in the body of a multitable
with @item, and separate the column entries with @tab.
Line breaks are not special within the table body, and you may break
input lines in your source file as necessary.

Here is a complete example of a multi-column table (the text is from
The GNU Emacs Manual, see section `Splitting Windows' in The GNU Emacs Manual):

@multitable @columnfractions .15 .45 .4
@item Key @tab Command @tab Description
@item C-x 2
@tab @code{split-window-vertically}
@tab Split the selected window into two windows,
with one above the other.
@item C-x 3
@tab @code{split-window-horizontally}
@tab Split the selected window into two windows
positioned side by side.
@item C-Mouse-2
@tab
@tab In the mode line or scroll bar of a window,
split that window.
@end multitable

produces:

Key C-x 2
C-x 3
C-Mouse-2

Command | Description
split-window-vertically | Split the selected window into two windows, with one above the other.
split-window-horizontally | Split the selected window into two windows positioned side by side.
 | In the mode line or scroll bar of a window, split that window.

Creating Indices

Using Texinfo, you can generate indices without having to sort and
collate entries manually.  In an index, the entries are listed in
alphabetical order, together with information on how to find the
discussion of each entry.  In a printed manual, this information
consists of page numbers.  In an Info file, this information is a menu
entry leading to the first node referenced.

Texinfo provides several predefined kinds of index: an index
for functions, an index for variables, an index for concepts, and so
on.  You can combine indices or use them for other than their
canonical purpose.  If you wish, you can define your own indices.

  • Index Entries: Choose different words for index entries.

  • Predefined Indices: Use different indices for different kinds
                                  of entry.

  • Indexing Commands: How to make an index entry.

  • Combining Indices: How to combine indices.

  • New Indices: How to define your own indices.

Making Index Entries

When you are making index entries, it is good practice to think of the
different ways people may look for something.  Different people
do not think of the same words when they look something up.  A
helpful index will have items indexed under all the different words
that people may use.  For example, one reader may think it obvious that
the two-letter names for indices should be listed under "Indices,
two-letter names", since the word "Index" is the general concept.
But another reader may remember the specific concept of two-letter
names and search for the entry listed as "Two letter names for
indices".  A good index will have both entries and will help both
readers.

Like typesetting, the construction of an index is a highly skilled,
professional art, the subtleties of which are not appreciated until you
need to do it yourself.

See section Index Menus and Printing an Index, for information about printing an index
at the end of a book or creating an index menu in an Info file.

Predefined Indices

Texinfo provides six predefined indices:

  •

A concept index listing concepts that are discussed.

  •

A function index listing functions (such as entry points of
libraries).

  •

A variables index listing variables (such as global variables
of libraries).

  •

A keystroke index listing keyboard commands.

  •

A program index listing names of programs.

  •

A data type index listing data types (such as structures defined in
header files).

Not every manual needs all of these, and most manuals use two or three
of them.  This manual has two indices: a
concept index and an @-command index (that is actually the function
index but is called a command index in the chapter heading).  Two or
more indices can be combined into one using the @synindex or
@syncodeindex commands.  See section Combining Indices.

Defining the Entries of an Index

The data to make an index come from many individual indexing commands
scattered throughout the Texinfo source file.  Each command says to add
one entry to a particular index; after formatting, the index will give
the current page number or node name as the reference.

An index entry consists of an indexing command at the beginning of a
line followed, on the rest of the line, by the entry.

For example, this section begins with the following five entries for
the concept index:

@cindex Defining indexing entries
@cindex Index entries
@cindex Entries for an index
@cindex Specifying index entries
@cindex Creating index entries

Each predefined index has its own indexing command---@cindex
for the concept index, @findex for the function index, and so
on.

Concept index entries consist of text.  The best way to write an index
is to choose entries that are terse yet clear.  If you can do this,
the index often looks better if the entries are not capitalized, but
written just as they would appear in the middle of a sentence.
(Capitalize proper names and acronyms that always call for upper case
letters.)  This is the case convention we use in most GNU manuals'
indices.

If you don't see how to make an entry terse yet clear, make it longer
and clear--not terse and confusing.  If many of the entries are several
words long, the index may look better if you use a different convention:
to capitalize the first word of each entry.  But do not capitalize a
case-sensitive name such as a C or Lisp function name or a shell
command; that would be a spelling error.

Whichever case convention you use, please use it consistently!

Entries in indices other than the concept index are symbol names in
programming languages, or program names; these names are usually
case-sensitive, so use upper and lower case as required for them.

By default, entries for a concept index are printed in a small roman
font and entries for the other indices are printed in a small
@code font.  You may change the way part of an entry is
printed with the usual Texinfo commands, such as @file for
file names and @emph for emphasis (see section Marking Words and Phrases).

The six indexing commands for predefined indices are:

@cindex concept

Make an entry in the concept index for concept.

@findex function

Make an entry in the function index for function.

@vindex variable

Make an entry in the variable index for variable.

@kindex keystroke

Make an entry in the key index for keystroke.

@pindex program

Make an entry in the program index for program.

@tindex data type

Make an entry in the data type index for data type.

Caution: Do not use a colon in an index entry.  In Info, a
colon separates the menu entry name from the node name.  An extra
colon confuses Info.
See section The Parts of a Menu,
for more information about the structure of a menu entry.

If you write several identical index entries in different places in a
Texinfo file, the index in the printed manual will list all the pages to
which those entries refer.  However, the index in the Info file will
list only the node that references the first of those
index entries.  Therefore, it is best to write indices in which each
entry refers to only one place in the Texinfo file.  Fortunately, this
constraint is a feature rather than a loss since it means that the index
will be easy to use.  Otherwise, you could create an index that lists
several pages for one entry and your reader would not know to which page
to turn.  If you have two identical entries for one topic, change the
topics slightly, or qualify them to indicate the difference.

You are not actually required to use the predefined indices for their
canonical purposes.  For example, suppose you wish to index some C
preprocessor macros.  You could put them in the function index along
with actual functions, just by writing @findex commands for
them; then, when you print the "Function Index" as an unnumbered
chapter, you could give it the title `Function and Macro Index' and
all will be consistent for the reader.  Or you could put the macros in
with the data types by writing @tindex commands for them, and
give that index a suitable title so the reader will understand.
(See section Index Menus and Printing an Index.)

Combining Indices

Sometimes you will want to combine two disparate indices such as functions
and concepts, perhaps because you have few enough of one of them that
a separate index for them would look silly.

You could put functions into the concept index by writing
@cindex commands for them instead of @findex commands,
and produce a consistent manual by printing the concept index with the
title `Function and Concept Index' and not printing the `Function
Index' at all; but this is not a robust procedure.  It works only if
your document is never included as part of another
document that is designed to have a separate function index; if your
document were to be included with such a document, the functions from
your document and those from the other would not end up together.
Also, to make your function names appear in the right font in the
concept index, you would need to enclose every one of them between
the braces of @code.

  • syncodeindex: How to merge two indices, using @code
                                  font for the merged-from index.

  • synindex: How to merge two indices, using the
                                  default font of the merged-to index.

@syncodeindex

When you want to combine functions and concepts into one index, you
should index the functions with @findex and index the concepts
with @cindex, and use the @syncodeindex command to
redirect the function index entries into the concept index.

The @syncodeindex command takes two arguments; they are the name
of the index to redirect, and the name of the index to redirect it to.
The template looks like this:

@syncodeindex from to

For this purpose, the indices are given two-letter names:

`cp'

concept index

`fn'

function index

`vr'

variable index

`ky'

key index

`pg'

program index

`tp'

data type index

Write an @syncodeindex command before or shortly after the
end-of-header line at the beginning of a Texinfo file.  For example,
to merge a function index with a concept index, write the
following:

@syncodeindex fn cp

This will cause all entries designated for the function index to merge
in with the concept index instead.

To merge both a variables index and a function index into a concept
index, write the following:

@syncodeindex vr cp
@syncodeindex fn cp

The @syncodeindex command puts all the entries from the `from'
index (the redirected index) into the @code font, overriding
whatever default font is used by the index to which the entries are
now directed.  This way, if you direct function names from a function
index into a concept index, all the function names are printed in the
@code font as you would expect.

@synindex

The @synindex command is nearly the same as the
@syncodeindex command, except that it does not put the
`from' index  entries into the @code font; rather it puts
them in the roman font.  Thus, you use @synindex when you
merge a concept index into a function index.

See section Index Menus and Printing an Index, for information about printing an index
at the end of a book or creating an index menu in an Info file.

Defining New Indices

In addition to the predefined indices, you may use the
@defindex and @defcodeindex commands to define new
indices.  These commands create new indexing @-commands with which
you mark index entries.  The @defindex command is used like
this:

@defindex name

The name of an index should be a two letter word, such as `au'.
For example:

@defindex au

This defines a new index, called the `au' index.  At the same
time, it creates a new indexing command, @auindex, that you
can use to make index entries.  Use the new indexing command just as
you would use a predefined indexing command.

For example, here is a section heading followed by a concept index
entry and two `au' index entries.

@section Cognitive Semantics
@cindex kinesthetic image schemas
@auindex Johnson, Mark
@auindex Lakoff, George

(Evidently, `au' serves here as an abbreviation for "author".)
Texinfo constructs the new indexing command by concatenating the name
of the index with `index'; thus, defining an `au' index
leads to the automatic creation of an @auindex command.

Use the @printindex command to print the index, as you do with
the predefined indices.  For example:

@node Author Index, Subject Index, , Top
@unnumbered Author Index

@printindex au

The @defcodeindex is like the @defindex command, except
that, in the printed output, it prints entries in an @code font
instead of a roman font.  Thus, it parallels the @findex command
rather than the @cindex command.

You should define new indices within or right after the end-of-header
line of a Texinfo file, before any @synindex or
@syncodeindex commands (see section The Texinfo File Header).

Special Insertions

Texinfo provides several commands for inserting characters that have
special meaning in Texinfo, such as braces, and for other graphic
elements that do not correspond to simple characters you can type.

These are:

  • Braces, `@' and periods.

  • Whitespace within and around a sentence.

  • Accents.

  • Dots and bullets.

  • The TeX logo and the copyright symbol.

  • Mathematical expressions.

  • Braces Atsigns: How to insert braces, `@'.

  • Inserting Space: How to insert the right amount of space
                                  within a sentence.

  • Inserting Accents: How to insert accents and special characters.

  • Dots Bullets: How to insert dots and bullets.

  • TeX and copyright: How to insert the TeX logo
                                  and the copyright symbol.

  • pounds: How to insert the pounds currency symbol.

  • minus: How to insert a minus sign.

  • math: How to format a mathematical expression.

  • Glyphs: How to indicate results of evaluation,
                                  expansion of macros, errors, etc.

  • Images: How to include graphics.

Inserting @ and Braces

`@' and curly braces are special characters in Texinfo.  To insert
these characters so they appear in text, you must put an `@' in
front of these characters to prevent Texinfo from misinterpreting
them.

Do not put braces after any of these commands; they are not
necessary.

  • Inserting An Atsign: How to insert `@'.

  • Inserting Braces: How to insert `{' and `}'.

Inserting `@' with @@

@@ stands for a single `@' in either printed or Info
output.

Do not put braces after an @@ command.

Inserting `{' and `}'with @{ and @}

@{ stands for a single `{' in either printed or Info
output.

@} stands for a single `}' in either printed or Info
output.

Do not put braces after either an @{ or an @}
command.

Inserting Space

The following sections describe commands that control spacing of various
kinds within and after sentences.

  • Not Ending a Sentence: Sometimes a . doesn't end a sentence.

  • Ending a Sentence: Sometimes it does.

  • Multiple Spaces: Inserting multiple spaces.

  • dmn: How to format a dimension.

Not Ending a Sentence

Depending on whether a period or exclamation point or question mark is
inside or at the end of a sentence, less or more space is inserted after
a period in a typeset manual.  Since it is not always possible for
Texinfo to determine when a period ends a sentence and when it is used
in an abbreviation, special commands are needed in some circumstances.
(Usually, Texinfo can guess how to handle periods, so you do not need to
use the special commands; you just enter a period as you would if you
were using a typewriter, which means you put two spaces after the
period, question mark, or exclamation mark that ends a sentence.)

Use the @: command after a period, question mark,
exclamation mark, or colon that should not be followed by extra space.
For example, use @: after periods that end abbreviations
which are not at the ends of sentences.

For example,

The s.o.p.@: has three parts ...
The s.o.p. has three parts ...

produces the following.  If you look carefully at this printed output,
you will see a little more whitespace after `s.o.p.' in the second
line.

The s.o.p. has three parts ...

The s.o.p. has three parts ...

(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
Procedure".)

@: has no effect on the Info output.  Do not put braces after
@:.

Ending a Sentence

Use @. instead of a period, @! instead of an
exclamation point, and @? instead of a question mark at the end
of a sentence that ends with a single capital letter.  Otherwise, TeX
will think the letter is an abbreviation and will not insert the correct
end-of-sentence spacing.  Here is an example:

Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

produces the following.  If you look carefully at this printed output,
you will see a little more whitespace after the `W' in the first
line.

Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

In the Info file output, @. is equivalent to a simple
`.'; likewise for @! and @?.

The meanings of @: and @. in Texinfo are designed to
work well with the Emacs sentence motion commands (see section `Sentences' in The GNU Emacs Manual).  This made it necessary for them to be
incompatible with some other formatting systems that use @-commands.

Do not put braces after any of these commands.

Multiple Spaces

Ordinarily, TeX collapses multiple whitespace characters (space, tab,
and newline) into a single space.  Info output, on the other hand,
preserves whitespace as you type it, except for changing a newline into
a space; this is why it is important to put two spaces at the end of
sentences in Texinfo documents.

Occasionally, you may want to actually insert several consecutive
spaces, either for purposes of example (what your program does with
multiple spaces as input), or merely for purposes of appearance in
headings or lists.  Texinfo supports three commands:
@SPACE, @TAB, and @NL, all of
which insert a single space into the output.  (Here,
@SPACE represents an `@' character followed by a
space, i.e., `@ ', and TAB and NL represent the tab
character and end-of-line, i.e., when `@' is the last character on
a line.)

For example,

Spacey@ @ @ @
example.

produces

Spacey
example.

Other possible uses of @SPACE have been subsumed by
@multitable (see section Multi-column Tables).

Do not follow any of these commands with braces.

@dmn{dimension}: Format a Dimension

At times, you may want to write `12pt' or
`8.5in' with little or no space between the number and the
abbreviation for the dimension.  You can use the @dmn command
to do this.  On seeing the command, TeX inserts just enough space
for proper typesetting; the Info formatting commands insert no space
at all, since the Info file does not require it.

To use the @dmn command, write the number and then follow it
immediately, with no intervening space, by @dmn, and then by
the dimension within braces.  For example,

A4 paper is 8.27@dmn{in} wide.

produces

A4 paper is 8.27in wide.

Not everyone uses this style.  Some people prefer `8.27 in.@:'
or `8.27 inches' to `8.27@dmn{in}' in the Texinfo file.
In these cases, however, the formatters may insert a line break between
the number and the dimension, so use @w (see section @w{text}: Prevent Line Breaks).  Also, if
you write a period after an abbreviation within a sentence, you should
write `@:' after the period to prevent TeX from inserting extra
whitespace, as shown here.  See section Inserting Space.

Inserting Accents

Here is a table with the commands Texinfo provides for inserting
floating accents.  The commands with non-alphabetic names do not take
braces around their argument (which is taken to be the next character).
(Exception: @, does take braces around its argument.)
This is so as to make the source as convenient to type and read as
possible, since accented characters are very common in some languages.

Command               @"o@'o@,{c}@=o@^o@`o@~o@dotaccent{o}@H{o}@ringaccent{o}@tieaccent{oo}@u{o}@ubaraccent{o}@udotaccent{o}@v{o}
Output | What
@"o | umlaut accent
'o | acute accent
@,{c} | cedilla accent
@=o | macron/overbar accent
@^o | circumflex accent
`o | grave accent
@~o | tilde accent
@dotaccent{o} | overdot accent
@H{o} | long Hungarian umlaut
@ringaccent{o} | ring accent
@tieaccent{oo} | tie-after accent
@u{o} | breve accent
@ubaraccent{o} | underbar accent
@udotaccent{o} | underdot accent
@v{o} | hacek or check accent

This table lists the Texinfo commands for inserting other characters
commonly used in languages other than English.

@exclamdown{}@questiondown{}@aa{},@AA{}@ae{},@AE{}@dotless{i}@dotless{j}@l{},@L{}@o{},@O{}@oe{},@OE{}@ss{}
¡ | upside-down !
¿ | upside-down ?
å,Å | A,a with circle
æ,Æ | ae,AE ligatures
@dotless{i} | dotless i
@dotless{j} | dotless j
l/,L/ | suppressed-L,l
ø,Ø | O,o with slash
oe,OE | OE,oe ligatures
ß | es-zet or sharp S

Inserting Ellipsis, Dots, and Bullets

An ellipsis (a line of dots) is not typeset as a string of
periods, so a special command is used for ellipsis in Texinfo.  The
@bullet command is special, too.  Each of these commands is
followed by a pair of braces, `{}', without any whitespace
between the name of the command and the braces.  (You need to use braces
with these commands because you can use them next to other text; without
the braces, the formatters would be confused.  See section @-Command Syntax, for further information.)

  • dots: How to insert dots ...

  • bullet: How to insert a bullet.

@dots{} (...)

Use the @dots{} command to generate an ellipsis, which is
three dots in a row, appropriately spaced, like this: `...'.  Do
not simply write three periods in the input file; that would work for
the Info file output, but would produce the wrong amount of space
between the periods in the printed manual.

Similarly, the @enddots{} command generates an
end-of-sentence ellipsis (four dots) ....

Here is an ellipsis: ...
Here are three periods in a row: ...

In printed output, the three periods in a row are closer together than
the dots in the ellipsis.

@bullet{} (*)

Use the @bullet{} command to generate a large round dot, or
the closest possible thing to one.  In Info, an asterisk is used.

Here is a bullet: *

When you use @bullet in @itemize, you do not need to
type the braces, because @itemize supplies them.
(See section Making an Itemized List.)

Inserting TeX and the Copyright Symbol

The logo `TeX' is typeset in a special fashion and it needs an
@-command.  The copyright symbol, `©', is also special.
Each of these commands is followed by a pair of braces, `{}',
without any whitespace between the name of the command and the
braces.

  • tex: How to insert the TeX logo.

  • copyright symbol: How to use @copyright{}.

@TeX{} (TeX)

Use the @TeX{} command to generate `TeX'.  In a printed
manual, this is a special logo that is different from three ordinary
letters.  In Info, it just looks like `TeX'.  The
@TeX{} command is unique among Texinfo commands in that the
T and the X are in upper case.

@copyright{} (©)

Use the @copyright{} command to generate `©'.  In
a printed manual, this is a `c' inside a circle, and in Info,
this is `(C)'.

@pounds{} (£): Pounds Sterling

Use the @pounds{} command to generate `£'.  In a
printed manual, this is the symbol for the currency pounds sterling.
In Info, it is a `#'.  Other currency symbols are unfortunately not
available.

@minus{} (-): Inserting a Minus Sign

Use the @minus{} command to generate a minus sign.  In a
fixed-width font, this is a single hyphen, but in a proportional font,
the symbol is the customary length for a minus sign--a little longer
than a hyphen, shorter than an em-dash:

`-' is a minus sign generated with `@minus{}',

`-' is a hyphen generated with the character `-',

`---' is an em-dash for text.

In the fixed-width font used by Info, @minus{} is the same
as a hyphen.

You should not use @minus{} inside @code or
@example because the width distinction is not made in the
fixed-width font they use.

When you use @minus to specify the mark beginning each entry in
an itemized list, you do not need to type the braces
(see section Making an Itemized List.)

@math: Inserting Mathematical Expressions

You can write a short mathematical expression with the @math
command.  Write the mathematical expression between braces, like this:

@math{(a + b)(a + b) = a^2 + 2ab + b^2}

This produces the following in TeX:

(a + b)(a + b) = a^2 + 2ab + b^2

and the following in Info:

(a + b)(a + b) = a^2 + 2ab + b^2

Thus, the @math command has no effect on the Info output.

For complex mathematical expressions, you can also use TeX directly
(see section Raw Formatter Commands).  When you use TeX directly,
remember to write the mathematical expression between one or two
`$' (dollar-signs) as appropriate.

Glyphs for Examples

In Texinfo, code is often illustrated in examples that are delimited
by @example and @end example, or by @lisp and
@end lisp.  In such examples, you can indicate the results of
evaluation or an expansion using `=>' or
`==>'.  Likewise, there are commands to insert glyphs
to indicate
printed output, error messages, equivalence of expressions, and the
location of point.

The glyph-insertion commands do not need to be used within an example, but
most often they are.  Every  glyph-insertion command is followed by a pair of
left- and right-hand braces.

  • result: How to show the result of expression.

  • expansion: How to indicate an expansion.

  • Print Glyph: How to indicate printed output.

  • Error Glyph: How to indicate an error message.

  • Equivalence: How to indicate equivalence.

  • Point Glyph: How to indicate the location of point.

=>

@result{} points to the result of an expression.

==>

@expansion{} shows the results of a macro expansion.

-|

@print{} indicates printed output.

error-->

@error{} indicates that the following text is an error
message.

==

@equiv{} indicates the exact equivalence of two forms.

-!-

@point{} shows the location of point.

  • result

  • expansion

  • Print Glyph

  • Error Glyph

  • Equivalence

  • Point Glyph

@result{} (=>): Indicating Evaluation

Use the @result{} command to indicate the result of
evaluating an expression.

The @result{} command is displayed as `=>' in Info and
as `=>' in the printed output.

Thus, the following,

(cdr '(1 2 3))
     => (2 3)

may be read as "(cdr '(1 2 3)) evaluates to (2 3)".

@expansion{} (==>): Indicating an Expansion

When an expression is a macro call, it expands into a new expression.
You can indicate the result of the expansion with the
@expansion{} command.

The @expansion{} command is displayed as `==>' in Info and
as `==>' in the printed output.

For example, the following

@lisp
(third '(a b c))
     @expansion{} (car (cdr (cdr '(a b c))))
     @result{} c
@end lisp

produces

(third '(a b c))
     ==> (car (cdr (cdr '(a b c))))
     => c

which may be read as:

(third '(a b c)) expands to (car (cdr (cdr '(a b c))));
the result of evaluating the expression is c.

Often, as in this case, an example looks better if the
@expansion{} and @result{} commands are indented
five spaces.

@print{} (-|): Indicating Printed Output

Sometimes an expression will print output during its execution.  You
can indicate the printed output with the @print{} command.

The @print{} command is displayed as `-|' in Info and
as `-|' in the printed output.

In the following example, the printed text is indicated with
`-|', and the value of the expression follows on the
last line.

(progn (print 'foo) (print 'bar))
     -| foo
     -| bar
     => bar

In a Texinfo source file, this example is written as follows:

@lisp
(progn (print 'foo) (print 'bar))
     @print{} foo
     @print{} bar
     @result{} bar
@end lisp

@error{} (error-->): Indicating an Error Message

A piece of code may cause an error when you evaluate it.  You can
designate the error message with the @error{} command.

The @error{} command is displayed as `error-->' in Info
and as `error-->' in the printed output.

Thus,

@lisp
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@end lisp

produces

(+ 23 'x)
error--> Wrong type argument: integer-or-marker-p, x

This indicates that the following error message is printed
when you evaluate the expression:

Wrong type argument: integer-or-marker-p, x

`error-->' itself is not part of the error message.

@equiv{} (==): Indicating Equivalence

Sometimes two expressions produce identical results.  You can indicate the
exact equivalence of two forms with the @equiv{} command.

The @equiv{} command is displayed as `==' in Info and
as `==' in the printed output.

Thus,

@lisp
(make-sparse-keymap) @equiv{} (list 'keymap)
@end lisp

produces

(make-sparse-keymap) == (list 'keymap)

This indicates that evaluating (make-sparse-keymap) produces
identical results to evaluating (list 'keymap).

@point{} (-!-): Indicating Point in a Buffer

Sometimes you need to show an example of text in an Emacs buffer.  In
such examples, the convention is to include the entire contents of the
buffer in question between two lines of dashes containing the buffer
name.

You can use the `@point{}' command to show the location of point
in the text in the buffer.  (The symbol for point, of course, is not
part of the text in the buffer; it indicates the place between
two characters where point is located.)

The @point{} command is displayed as `-!-' in Info and
as `-!-' in the printed output.

The following example shows the contents of buffer `foo' before
and after evaluating a Lisp command to insert the word changed.

---------- Buffer: foo ----------
This is the -!-contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     => nil
---------- Buffer: foo ----------
This is the changed -!-contents of foo.
---------- Buffer: foo ----------

In a Texinfo source file, the example is written like this:

@example
---------- Buffer: foo ----------
This is the @point{}contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     @result{} nil
---------- Buffer: foo ----------
This is the changed @point{}contents of foo.
---------- Buffer: foo ----------
@end example

Inserting Images

You can insert an image in an external file with the @image
command:

@image{filename, [width], [height]}

The filename argument is mandatory, and must not have an
extension, because the different processors support different formats:
TeX reads the file `filename.eps' (Encapsulated PostScript
format); makeinfo uses `filename.txt' verbatim for
Info output (more or less as if it was an @example).  HTML
output requires `filename.jpg'.

The optional width and height arguments specify the size to
scale the image to (they are ignored for Info output).  If they are both
specified, the image is presented in its natural size (given in the
file); if only one is specified, the other is scaled proportionately;
and if both are specified, both are respected, thus possibly distorting
the original image by changing its aspect ratio.

The width and height may be specified using any valid TeX
dimension, namely:

pt

point (72.27pt = 1in)

pc

pica (1pc = 12pt)

bp

big point (72bp = 1in)

in

inch

cm

centimeter (2.54cm = 1in)

mm

millimeter (10mm = 1cm)

dd

did@^ot point (1157dd = 1238pt)

cc

cicero (1cc = 12dd)

sp

scaled point (65536sp = 1pt)

For example, the following will scale a file `ridt.eps' to one
inch vertically, with the width scaled proportionately:

@image{ridt,,1in}

For @image to work with TeX, the file `epsf.tex' must be
installed somewhere that TeX can find it.  This file is included in
the Texinfo distribution and is available from
ftp://ftp.tug.org/tex/epsf.tex.

Making and Preventing Breaks

Usually, a Texinfo file is processed both by TeX and by one of the
Info formatting commands.  Line, paragraph, or page breaks sometimes
occur in the `wrong' place in one or other form of output.  You must
ensure that text looks right both in the printed manual and in the
Info file.

For example, in a printed manual, page breaks may occur awkwardly in
the middle of an example; to prevent this, you can hold text together
using a grouping command that keeps the text from being split across
two pages.  Conversely, you may want to force a page break where none
would occur normally.  Fortunately, problems like these do not often
arise.  When they do, use the break, break prevention, or pagination
commands.

  • Line Breaks: How to force a single line to use two lines.

  • - and hyphenation: How to tell TeX about hyphenation points.

  • w: How to prevent unwanted line breaks.

  • sp: How to insert blank lines.

  • page: How to force the start of a new page.

  • group: How to prevent unwanted page breaks.

  • need: Another way to prevent unwanted page breaks.

The break commands create or allow line and paragraph breaks:

@*

Force a line break.

@sp n

Skip n blank lines.

@-

Insert a discretionary hyphen.

@hyphenation{hy-phen-a-ted words}

Define hyphen points in hy-phen-a-ted words.

The line-break-prevention command holds text together all on one
line:

@w{text}

Prevent text from being split and hyphenated across two lines.

The pagination commands apply only to printed output, since Info
files do not have pages.

@page

Start a new page in the printed manual.

@group

Hold text together that must appear on one printed page.

@need mils

Start a new printed page if not enough space on this one.

@*: Generate Line Breaks

The @* command forces a line break in both the printed manual and
in Info.

For example,

This line @* is broken @*in two places.

produces

This line
 is broken
in two places.

(Note that the space after the first @* command is faithfully
carried down to the next line.)

The @* command is often used in a file's copyright page:

This is edition 2.0 of the Texinfo documentation,@*
and is for ...

In this case, the @* command keeps TeX from stretching the
line across the whole page in an ugly manner.

Please note: Do not write braces after an @* command;
they are not needed.

Do not write an @refill command at the end of a paragraph
containing an @* command; it will cause the paragraph to be
refilled after the line break occurs, negating the effect of the line
break.

@- and @hyphenation: Helping TeX hyphenate

Although TeX's hyphenation algorithm is generally pretty good, it
does miss useful hyphenation points from time to time.  (Or, far more
rarely, insert an incorrect hyphenation.)  So, for documents with an
unusual vocabulary or when fine-tuning for a printed edition, you may
wish to help TeX out.  Texinfo supports two commands for this:

@-

Insert a discretionary hyphen, i.e., a place where TeX can (but does
not have to) hyphenate.  This is especially useful when you notice
an overfull hbox is due to TeX missing a hyphenation (see section Overfull "hboxes").  TeX will not insert any hyphenation points in a word
containing @-.

@hyphenation{hy-phen-a-ted words}

Tell TeX how to hyphenate hy-phen-a-ted words.  As shown, you
put a `-' at each hyphenation point.  For example:

@hyphenation{man-u-script man-u-scripts}

TeX only uses the specified hyphenation points when the
words match exactly, so give all necessary variants.

Info output is not hyphenated, so these commands have no effect there.

@w{text}: Prevent Line Breaks

@w{text} outputs text and prohibits line breaks
within text.

You can use the @w command to prevent TeX from automatically
hyphenating a long name or phrase that happens to fall near the end of a
line.

You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.

produces

You can copy GNU software from `ftp.gnu.ai.mit.edu'.

Caution: Do not write an @refill command at the end
of a paragraph containing an @w command; it will cause the
paragraph to be refilled and may thereby negate the effect of the
@w command.

@sp n: Insert Blank Lines

A line beginning with and containing only @sp n
generates n blank lines of space in both the printed manual and
the Info file.  @sp also forces a paragraph break.  For
example,

@sp 2

generates two blank lines.

The @sp command is most often used in the title page.

@page: Start a New Page

A line containing only @page starts a new page in a printed
manual.  The command has no effect on Info files since they are not
paginated.  An @page command is often used in the @titlepage
section of a Texinfo file to start the copyright page.

@group: Prevent Page Breaks

The @group command (on a line by itself) is used inside an
@example or similar construct to begin an unsplittable vertical
group, which will appear entirely on one page in the printed output.
The group is terminated by a line containing only @end group.
These two lines produce no output of their own, and in the Info file
output they have no effect at all.

Although @group would make sense conceptually in a wide
variety of contexts, its current implementation works reliably only
within @example and variants, and within @display,
@format, @flushleft and @flushright.
See section Quotations and Examples.  (What all these commands have in
common is that each line of input produces a line of output.)  In
other contexts, @group can cause anomalous vertical
spacing.

This formatting requirement means that you should write:

@example
@group
...
@end group
@end example

with the @group and @end group commands inside the
@example and @end example commands.

The @group command is most often used to hold an example
together on one page.  In this Texinfo manual, more than 100 examples
contain text that is enclosed between @group and @end
group.

If you forget to end a group, you may get strange and unfathomable
error messages when you run TeX.  This is because TeX keeps
trying to put the rest of the Texinfo file onto the one page and does
not start to generate error messages until it has processed
considerable text.  It is a good rule of thumb to look for a missing
@end group if you get incomprehensible error messages in
TeX.

@need mils: Prevent Page Breaks

A line containing only @need n starts
a new page in a printed manual if fewer than n mils (thousandths
of an inch) remain on the current page.  Do not use
braces around the argument n.  The @need command has no
effect on Info files since they are not paginated.

This paragraph is preceded by an @need command that tells
TeX to start a new page if fewer than 800 mils (eight-tenths
inch) remain on the page.  It looks like this:

@need 800
This paragraph is preceded by ...

The @need command is useful for preventing orphans (single
lines at the bottoms of printed pages).

Definition Commands

The @deffn command and the other definition commands
enable you to describe functions, variables, macros, commands, user
options, special forms and other such artifacts in a uniform
format.

In the Info file, a definition causes the entity
category---`Function', `Variable', or whatever--to appear at the
beginning of the first line of the definition, followed by the
entity's name and arguments.  In the printed manual, the command
causes TeX to print the entity's name and its arguments on the left
margin and print the category next to the right margin.  In both
output formats, the body of the definition is indented.  Also, the
name of the entity is entered into the appropriate index:
@deffn enters the name into the index of functions,
@defvr enters it into the index of variables, and so
on.

A manual need not and should not contain more than one definition for
a given name.  An appendix containing a summary should use
@table rather than the definition commands.

  • Def Cmd Template: How to structure a description using a
                                  definition command.

  • Optional Arguments: How to handle optional and repeated arguments.

  • deffnx: How to group two or more `first' lines.

  • Def Cmds in Detail: All the definition commands.

  • Def Cmd Conventions: Conventions for writing definitions.

  • Sample Function Definition

The Template for a Definition

The @deffn command is used for definitions of entities that
resemble functions.  To write a definition using the @deffn
command, write the @deffn command at the beginning of a line
and follow it on the same line by the category of the entity, the name
of the entity itself, and its arguments (if any).  Then write the body
of the definition on succeeding lines.  (You may embed examples in the
body.)  Finally, end the definition with an @end deffn command
written on a line of its own.  (The other definition commands follow
the same format.)

The template for a definition looks like this:

@deffn category name arguments...
body-of-definition
@end deffn

For example,

@deffn Command forward-word count
This command moves point forward @var{count} words
(or backward if @var{count} is negative). ...
@end deffn

produces

Command: forward-word count

This function moves point forward count words
(or backward if count is negative). ...

Capitalize the category name like a title.  If the name of the
category contains spaces, as in the phrase `Interactive Command',
write braces around it.  For example:

@deffn {Interactive Command} isearch-forward
...
@end deffn

Otherwise, the second word will be mistaken for the name of the
entity.

Some of the definition commands are more general than others.  The
@deffn command, for example, is the general definition command
for functions and the like--for entities that may take arguments.  When
you use this command, you specify the category to which the entity
belongs.  The @deffn command possesses three predefined,
specialized variations, @defun, @defmac, and
@defspec, that specify the category for you: "Function",
"Macro", and "Special Form" respectively.  (In Lisp, a special form
is an entity much like a function.)  The @defvr command also is
accompanied by several predefined, specialized variations for describing
particular kinds of variables.

The template for a specialized definition, such as @defun, is
similar to the template for a generalized definition, except that you
do not need to specify the category:

@defun name arguments...
body-of-definition
@end defun

Thus,

@defun buffer-end flag
This function returns @code{(point-min)} if @var{flag}
is less than 1, @code{(point-max)} otherwise.
...
@end defun

produces

Function: buffer-end flag

This function returns (point-min) if flag is less than 1,
(point-max) otherwise.  ...

See section A Sample Function Definition, for a more detailed example of a function
definition, including the use of @example inside the
definition.

The other specialized commands work like @defun.

Optional and Repeated Arguments

Some entities take optional or repeated arguments, which may be
specified by a distinctive glyph that uses square brackets and
ellipses.  For example, a special form often breaks its argument list
into separate arguments in more complicated ways than a
straightforward function.

An argument enclosed within square brackets is optional.
Thus, the phrase
`[optional-arg]' means that
optional-arg is optional.
An argument followed by an ellipsis is optional
and may be repeated more than once.
Thus, `repeated-args...' stands for zero or more arguments.
Parentheses are used when several arguments are grouped
into additional levels of list structure in Lisp.

Here is the @defspec line of an example of an imaginary
special form:

Special Form: foobar (var [from to [inc]]) body...

In this example, the arguments from and to are optional,
but must both be present or both absent.  If they are present,
inc may optionally be specified as well.  These arguments are
grouped with the argument var into a list, to distinguish them
from body, which includes all remaining elements of the
form.

In a Texinfo source file, this @defspec line is written like
this (except it would not be split over two lines, as it is in this
example).

@defspec foobar (@var{var} [@var{from} @var{to}
     [@var{inc}]]) @var{body}@dots{}

The function is listed in the Command and Variable Index under
`foobar'.

Two or More `First' Lines

To create two or more `first' or header lines for a definition, follow
the first @deffn line by a line beginning with @deffnx.
The @deffnx command works exactly like @deffn
except that it does not generate extra vertical white space between it
and the preceding line.

For example,

@deffn {Interactive Command} isearch-forward
@deffnx {Interactive Command} isearch-backward
These two search commands are similar except ...
@end deffn

produces

Interactive Command: isearch-forward

Interactive Command: isearch-backward

These two search commands are similar except ...

Each of the other definition commands has an `x' form: @defunx,
@defvrx, @deftypefunx, etc.

The `x' forms work just like @itemx; see section @itemx.

The Definition Commands

Texinfo provides more than a dozen definition commands, all of which
are described in this section.

The definition commands automatically enter the name of the entity in
the appropriate index: for example, @deffn, @defun,
and @defmac enter function names in the index of functions;
@defvr and @defvar enter variable names in the index
of variables.

Although the examples that follow mostly illustrate Lisp, the commands
can be used for other programming languages.

  • Functions Commands: Commands for functions and similar entities.

  • Variables Commands: Commands for variables and similar entities.

  • Typed Functions: Commands for functions in typed languages.

  • Typed Variables: Commands for variables in typed languages.

  • Abstract Objects: Commands for object-oriented programming.

  • Data Types: The definition command for data types.

Functions and Similar Entities

This section describes the commands for describing functions and similar
entities:

@deffn category name arguments...

The @deffn command is the general definition command for
functions, interactive commands, and similar entities that may take
arguments.  You must choose a term to describe the category of entity
being defined; for example, "Function" could be used if the entity is
a function.  The @deffn command is written at the beginning of a
line and is followed on the same line by the category of entity being
described, the name of this particular entity, and its arguments, if
any.  Terminate the definition with @end deffn on a line of its
own.
For example, here is a definition:

@deffn Command forward-char nchars
Move point forward @var{nchars} characters.
@end deffn

This shows a rather terse definition for a "command" named
forward-char with one argument, nchars.

@deffn prints argument names such as nchars in italics or
upper case, as if @var had been used, because we think of these
names as metasyntactic variables--they stand for the actual argument
values.  Within the text of the description, write an argument name
explicitly with @var to refer to the value of the argument.  In
the example above, we used `@var{nchars}' in this way.

The template for @deffn is:

@deffn category name arguments...
body-of-definition
@end deffn

@defun name arguments...

The @defun command is the definition command for functions.
@defun is equivalent to `@deffn Function
...'.
For example,

@defun set symbol new-value
Change the value of the symbol @var{symbol}
to @var{new-value}.
@end defun

shows a rather terse definition for a function set whose
arguments are symbol and new-value.  The argument names on
the @defun line automatically appear in italics or upper case as
if they were enclosed in @var.  Terminate the definition with
@end defun on a line of its own.
The template is:

@defun function-name arguments...
body-of-definition
@end defun

@defun creates an entry in the index of functions.

@defmac name arguments...

The @defmac command is the definition command for macros.
@defmac is equivalent to `@deffn Macro ...' and
works like @defun.

@defspec name arguments...

The @defspec command is the definition command for special
forms.  (In Lisp, a special form is an entity much like a function,
see section `Special Forms' in GNU Emacs Lisp Reference Manual.)
@defspec is equivalent to `@deffn {Special Form}
...' and works like @defun.

Variables and Similar Entities

Here are the commands for defining variables and similar
entities:

@defvr category name

The @defvr command is a general definition command for
something like a variable--an entity that records a value.  You must
choose a term to describe the category of entity being defined; for
example, "Variable" could be used if the entity is a variable.
Write the @defvr command at the beginning of a line and
followed it on the same line by the category of the entity and the
name of the entity.
Capitalize the category name like a title.  If the name of the category
contains spaces, as in the name "User Option", enclose it in braces.
Otherwise, the second word will be mistaken for the name of the entity.
For example,

@defvr {User Option} fill-column
This buffer-local variable specifies
the maximum width of filled lines.
...
@end defvr

Terminate the definition with @end defvr on a line of its
own.
The template is:

@defvr category name
body-of-definition
@end defvr

@defvr creates an entry in the index of variables for name.

@defvar name

The @defvar command is the definition command for variables.
@defvar is equivalent to `@defvr Variable
...'.
For example:

@defvar kill-ring
...
@end defvar

The template is:

@defvar name
body-of-definition
@end defvar

@defvar creates an entry in the index of variables for
name.

@defopt name

The @defopt command is the definition command for user
options, i.e., variables intended for users to change according to
taste; Emacs has many such (see section `Variables' in The GNU Emacs Manual).  @defopt is equivalent to `@defvr {User
Option} ...' and works like @defvar.

Functions in Typed Languages

The @deftypefn command and its variations are for describing
functions in languages in which you must declare types of variables and
functions, such as C and C++.

@deftypefn category data-type name arguments...

The @deftypefn command is the general definition command for
functions and similar entities that may take arguments and that are
typed.  The @deftypefn command is written at the beginning of
a line and is followed on the same line by the category of entity
being described, the type of the returned value, the name of this
particular entity, and its arguments, if any.
For example,

@deftypefn {Library Function} int foobar
   (int @var{foo}, float @var{bar})
...
@end deftypefn

(where the text before the "...", shown above as two lines, would
actually be a single line in a real Texinfo file) produces the following
in Info:

-- Library Function: int foobar (int FOO, float BAR)
...

In a printed manual, it produces:

Library Function: int foobar (int foo, float bar)

...

This means that foobar is a "library function" that returns an
int, and its arguments are foo (an int) and
bar (a float).
The argument names that you write in @deftypefn are not subject
to an implicit @var---since the actual names of the arguments in
@deftypefn are typically scattered among data type names and
keywords, Texinfo cannot find them without help.  Instead, you must write
@var explicitly around the argument names.  In the example
above, the argument names are `foo' and `bar'.
The template for @deftypefn is:

@deftypefn category data-type name arguments ...
body-of-description
@end deftypefn

Note that if the category or data type is more than one
word then it must be enclosed in braces to make it a single argument.
If you are describing a procedure in a language that has packages,
such as Ada, you might consider using @deftypefn in a manner
somewhat contrary to the convention described in the preceding
paragraphs.
For example:

@deftypefn stacks private push
        (@var{s}:in out stack;
        @var{n}:in integer)
...
@end deftypefn

(The @deftypefn arguments are shown split into three lines, but
would be a single line in a real Texinfo file.)

In this instance, the procedure is classified as belonging to the
package stacks rather than classified as a `procedure' and its
data type is described as private.  (The name of the procedure
is push, and its arguments are s and n.)
@deftypefn creates an entry in the index of functions for
name.

@deftypefun data-type name arguments...

The @deftypefun command is the specialized definition command
for functions in typed languages.  The command is equivalent to
`@deftypefn Function ...'.
Thus,

@deftypefun int foobar (int @var{foo}, float @var{bar})
...
@end deftypefun

produces the following in Info:

-- Function: int foobar (int FOO, float BAR)
...

and the following in a printed manual:

Function: int foobar (int foo, float bar)

...

The template is:

@deftypefun type name arguments...
body-of-description
@end deftypefun

@deftypefun creates an entry in the index of functions for
name.

Variables in Typed Languages

Variables in typed languages are handled in a manner similar to
functions in typed languages.  See section Functions in Typed Languages.  The general
definition command @deftypevr corresponds to
@deftypefn and the specialized definition command
@deftypevar corresponds to @deftypefun.

@deftypevr category data-type name

The @deftypevr command is the general definition command for
something like a variable in a typed language--an entity that records
a value.  You must choose a term to describe the category of the
entity being defined; for example, "Variable" could be used if the
entity is a variable.
The @deftypevr command is written at the beginning of a line
and is followed on the same line by the category of the entity
being described, the data type, and the name of this particular
entity.
For example:

@deftypevr {Global Flag} int enable
...
@end deftypevr

produces the following in Info:

-- Global Flag: int enable
...

and the following in a printed manual:

Global Flag: int enable

...

The template is:

@deftypevr category data-type name
body-of-description
@end deftypevr

@deftypevr creates an entry in the index of variables for
name.

@deftypevar data-type name

The @deftypevar command is the specialized definition command
for variables in typed languages.  @deftypevar is equivalent
to `@deftypevr Variable ...'.
For example:

@deftypevar int fubar
...
@end deftypevar

produces the following in Info:

-- Variable: int fubar
...

and the following in a printed manual:

Variable: int fubar

...

The template is:

@deftypevar data-type name
body-of-description
@end deftypevar

@deftypevar creates an entry in the index of variables for
name.

Object-Oriented Programming

Here are the commands for formatting descriptions about abstract
objects, such as are used in object-oriented programming.  A class is
a defined type of abstract object.  An instance of a class is a
particular object that has the type of the class.  An instance
variable is a variable that belongs to the class but for which each
instance has its own value.

In a definition, if the name of a class is truly a name defined in the
programming system for a class, then you should write an @code
around it.  Otherwise, it is printed in the usual text font.

@defcv category class name

The @defcv command is the general definition command for
variables associated with classes in object-oriented programming.  The
@defcv command is followed by three arguments: the category of
thing being defined, the class to which it belongs, and its
name.  Thus,

@defcv {Class Option} Window border-pattern
...
@end defcv

illustrates how you would write the first line of a definition of the
border-pattern class option of the class Window.
The template is

@defcv category class name
...
@end defcv

@defcv creates an entry in the index of variables.

@defivar class name

The @defivar command is the definition command for instance
variables in object-oriented programming.  @defivar is
equivalent to `@defcv {Instance Variable} ...'
The template is:

@defivar class instance-variable-name
body-of-definition
@end defivar

@defivar creates an entry in the index of variables.

@defop category class name arguments...

The @defop command is the general definition command for
entities that may resemble methods in object-oriented programming.
These entities take arguments, as functions do, but are associated
with particular classes of objects.
For example, some systems have constructs called wrappers that
are associated with classes as methods are, but that act more like
macros than like functions.  You could use @defop Wrapper to
describe one of these.
Sometimes it is useful to distinguish methods and operations.
You can think of an operation as the specification for a method.
Thus, a window system might specify that all window classes have a
method named expose; we would say that this window system
defines an expose operation on windows in general.  Typically,
the operation has a name and also specifies the pattern of arguments;
all methods that implement the operation must accept the same
arguments, since applications that use the operation do so without
knowing which method will implement it.
Often it makes more sense to document operations than methods.  For
example, window application developers need to know about the
expose operation, but need not be concerned with whether a
given class of windows has its own method to implement this operation.
To describe this operation, you would write:

@defop Operation windows expose

The @defop command is written at the beginning of a line and
is followed on the same line by the overall name of the category of
operation, the name of the class of the operation, the name of the
operation, and its arguments, if any.
The template is:

@defop category class name arguments...
body-of-definition
@end defop

@defop creates an entry, such as `expose on
windows', in the index of functions.

@defmethod class name arguments...

The @defmethod command is the definition command for methods
in object-oriented programming.  A method is a kind of function that
implements an operation for a particular class of objects and its
subclasses.  In the Lisp Machine, methods actually were functions, but
they were usually defined with defmethod.

@defmethod is equivalent to `@defop Method ...'.
The command is written at the beginning of a line and is followed by
the name of the class of the method, the name of the method, and its
arguments, if any.
For example,

@defmethod bar-class bar-method argument
...
@end defmethod

illustrates the definition for a method called bar-method of
the class bar-class.  The method takes an argument.
The template is:

@defmethod class method-name arguments...
body-of-definition
@end defmethod

@defmethod creates an entry, such as `bar-method on
bar-class', in the index of functions.

@deftypemethod class data-type name arguments...

The @deftypemethod command is the definition command for methods
in object-oriented typed languages, such as C++ and Java.  It is similar
to the @defmethod command with the addition of the
data-type parameter to specify the return type of the method.

Data Types

Here is the command for data types:

@deftp category name attributes...

The @deftp command is the generic definition command for data
types.  The command is written at the beginning of a line and is
followed on the same line by the category, by the name of the type
(which is a word like int or float), and then by names of
attributes of objects of that type.  Thus, you could use this command
for describing int or float, in which case you could use
data type as the category.  (A data type is a category of
certain objects for purposes of deciding which operations can be
performed on them.)
In Lisp, for example,  pair names a particular data
type, and an object of that type has two slots called the
CAR and the CDR.  Here is how you would write the first line
of a definition of pair.

@deftp {Data type} pair car cdr
...
@end deftp

The template is:

@deftp category name-of-type attributes...
body-of-definition
@end deftp

@deftp creates an entry in the index of data types.

Conventions for Writing Definitions

When you write a definition using @deffn, @defun, or
one of the other definition commands, please take care to use
arguments that indicate the meaning, as with the count argument
to the forward-word function.  Also, if the name of an argument
contains the name of a type, such as integer, take care that the
argument actually is of that type.

A Sample Function Definition

A function definition uses the @defun and @end defun
commands.  The name of the function follows immediately after the
@defun command and it is followed, on the same line, by the
parameter list.

Here is a definition from section `Calling Functions' in The GNU Emacs Lisp Reference Manual.

Function: apply function &rest arguments

apply calls function with arguments, just
like funcall but with one difference: the last of
arguments is a list of arguments to give to
function, rather than a single argument.  We also say
that this list is appended to the other arguments.

apply returns the result of calling function.
As with funcall, function must either be a Lisp
function or a primitive function; special forms and macros
do not make sense in apply.

(setq f 'list)
     => list
(apply f 'x 'y 'z)
error--> Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     => 10
(apply '+ '(1 2 3 4))
     => 10

(apply 'append '((a b c) nil (x y z) nil))
     => (a b c x y z)

An interesting example of using apply is found in the description
of mapcar.

In the Texinfo source file, this example looks like this:

@defun apply function &rest arguments

@code{apply} calls @var{function} with
@var{arguments}, just like @code{funcall} but with one
difference: the last of @var{arguments} is a list of
arguments to give to @var{function}, rather than a single
argument.  We also say that this list is @dfn{appended}
to the other arguments.

@code{apply} returns the result of calling
@var{function}.  As with @code{funcall},
@var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make
sense in @code{apply}.

@example
(setq f 'list)
     @result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     @result{} 10
(apply '+ '(1 2 3 4))
     @result{} 10

(apply 'append '((a b c) nil (x y z) nil))
     @result{} (a b c x y z)
@end example

An interesting example of using @code{apply} is found
in the description of @code{mapcar}.@refill
@end defun

In this manual, this function is listed in the Command and Variable
Index under apply.

Ordinary variables and user options are described using a format like
that for functions except that variables do not take arguments.

Footnotes

A footnote is for a reference that documents or elucidates the
primary text.(9)

  • Footnote Commands: How to write a footnote in Texinfo.

  • Footnote Styles: Controlling how footnotes appear in Info.

Footnote Commands

In Texinfo, footnotes are created with the @footnote command.
This command is followed immediately by a left brace, then by the text
of the footnote, and then by a terminating right brace.  Footnotes may
be of any length (they will be broken across pages if necessary), but
are usually short.  The template is:

ordinary text@footnote{text of footnote}

As shown here, the @footnote command should come right after the
text being footnoted, with no intervening space; otherwise, the
formatters the footnote mark might end up starting up a line.

For example, this clause is followed by a sample
footnote(10); in the Texinfo
source, it looks like this:

...a sample footnote@footnote{Here is the sample
footnote.}; in the Texinfo source...

Warning: Don't use footnotes in the argument of the
@item command for a @table table.  This doesn't work, and
because of limitations of TeX, there is no way to fix it.  You must
put the footnote into the body text of the table.

In a printed manual or book, the reference mark for a footnote is a
small, superscripted number; the text of the footnote appears at the
bottom of the page, below a horizontal line.

In Info, the reference mark for a footnote is a pair of parentheses
with the footnote number between them, like this: `(1)'.

Footnote Styles

Info has two footnote styles, which determine where the text of the
footnote is located:

  •

In the `End' node style, all the footnotes for a single node
are placed at the end of that node.  The footnotes are separated from
the rest of the node by a line of dashes with the word
`Footnotes' within it.  Each footnote begins with an
`(n)' reference mark.
Here is an example of a single footnote in the end of node style:

     --------- Footnotes ---------

(1)  Here is a sample footnote.

  •

In the `Separate' node style, all the footnotes for a single
node are placed in an automatically constructed node of
their own.  In this style, a "footnote reference" follows
each `(n)' reference mark in the body of the
node.  The footnote reference is actually a cross reference
which you use to reach the footnote node.
The name of the node containing the footnotes is constructed
by appending `-Footnotes' to the name of the node
that contains the footnotes. (Consequently, the footnotes'
node for the `Footnotes' node is
`Footnotes-Footnotes'!)  The footnotes' node has an
`Up' node pointer that leads back to its parent node.
Here is how the first footnote in this manual looks after being
formatted for Info in the separate node style:

    File: texinfo.info  Node: Overview-Footnotes, Up: Overview

(1) Note that the first syllable of "Texinfo" is
pronounced like "speck", not "hex". ...

A Texinfo file may be formatted into an Info file with either footnote
style.

Use the @footnotestyle command to specify an Info file's
footnote style.  Write this command at the beginning of a line followed
by an argument, either `end' for the end node style or
`separate' for the separate node style.

For example,

@footnotestyle end

or

@footnotestyle separate

Write an @footnotestyle command before or shortly after the
end-of-header line at the beginning of a Texinfo file.  (If you
include the @footnotestyle command between the start-of-header
and end-of-header lines, the region formatting commands will format
footnotes as specified.)

If you do not specify a footnote style, the formatting commands use
their default style.  Currently, texinfo-format-buffer and
texinfo-format-region use the `separate' style and
makeinfo uses the `end' style.

This chapter contains two footnotes.

Conditionally Visible Text

Sometimes it is good to use different text for a printed manual and
its corresponding Info file.  In this case, you can use the
conditional commands to specify which text is for the printed manual
and which is for the Info file.

  • Conditional Not Commands: Specifying text for not HTML, Info, or TeX.

  • Raw Formatter Commands: Using raw TeX or HTML commands.

  • set clear value: Designating which text to format (for
                                  all output formats); and how to set a
                                  flag to a string that you can insert.

@ifinfo begins segments of text that should be ignored
by TeX when it
typesets the printed manual.  The segment of text appears only
in the Info file.
The @ifinfo command should appear on a line by itself;  end
the Info-only text with a line containing @end ifinfo by
itself.  At the beginning of a Texinfo file, the Info permissions are
contained within a region marked by @ifinfo and @end
ifinfo. (See section Summary and Copying Permissions for Info.)

The @iftex and @end iftex commands are similar to the
@ifinfo and @end ifinfo commands, except that they
specify text that will appear in the printed manual but not in the Info
file.  Likewise for @ifhtml and @end ifhtml, which
specify text to appear only in HTML output.

For example,

@iftex
This text will appear only in the printed manual.
@end iftex
@ifinfo
However, this text will appear only in Info.
@end ifinfo

The preceding example produces the following line:
This text will appear only in the printed manual.

Note how you only see one of the two lines, depending on whether you
are reading the Info version or the printed version of this
manual.

The @titlepage command is a special variant of @iftex that
is used for making the title and copyright pages of the printed
manual.  (See section @titlepage.)

Conditional Not Commands

You can specify text to be included in any output format other
than some given one with the @ifnot... commands:

@ifnothtml ... @end ifnothtml
@ifnotinfo ... @end ifnotinfo
@ifnottex ... @end ifnottex

(The @ifnot... command and the @end command must
actually appear on lines by themselves.)

If the output file is not being made for the given format, the region is
included.  Otherwise, it is ignored.

The regions delimited by these commands are ordinary Texinfo source as
with @iftex, not raw formatter source as with @tex.

Raw Formatter Commands

Inside a region delineated by @iftex and @end iftex, you
can embed some raw TeX commands.  Info will ignore these commands
since they are only in that part of the file which is seen by TeX.
You can write the TeX commands as you would write them in a normal
TeX file, except that you must replace the `\' used by TeX
with an `@'.  For example, in the @titlepage section of a
Texinfo file, you can use the TeX command @vskip to format
the copyright page.  (The @titlepage command causes Info to
ignore the region automatically, as it does with the @iftex
command.)

However, many features of plain TeX will not work, as they are
overridden by Texinfo features.

You can enter plain TeX completely, and use `\' in the TeX
commands, by delineating a region with the @tex and @end
tex commands.  (The @tex command also causes Info to ignore the
region, like the @iftex command.)  The sole exception is that
@ chracter still introduces a command, so that @end tex
can be recognized properly.

For example, here is a mathematical expression written in
plain TeX:

@tex
$$ \chi^2 = \sum_{i=1}^N
          \left (y_i - (a + b x_i)
          \over \sigma_i\right)^2 $$
@end tex

The output of this example will appear only in a printed manual.  If
you are reading this in Info, you will not see the equation that appears
in the printed manual.
In a printed manual, the above expression looks like
this:

Analogously, you can use @ifhtml ... @end ifhtml to delimit
a region to be included in HTML output only, and @html ...
@end ifhtml for a region of raw HTML (again, except that @ is
still the escape character, so the @end command can be
recognized.)

@set, @clear, and @value

You can direct the Texinfo formatting commands to format or ignore parts
of a Texinfo file with the @set, @clear, @ifset,
and @ifclear commands.

In addition, you can use the @set flag command to set the
value of flag to a string of characters; and use
@value{flag} to insert that string.  You can use
@set, for example, to set a date and use @value to
insert the date in several places in the Texinfo file.

  • ifset ifclear: Format a region if a flag is set.

  • value: Replace a flag with a string.

  • value Example: An easy way to update edition information.

@ifset and @ifclear

When a flag is set, the Texinfo formatting commands format text
between subsequent pairs of @ifset flag and @end
ifset commands.  When the flag is cleared, the Texinfo formatting
commands do not format the text.

Use the @set flag command to turn on, or set, a
flag; a flag can be any single word.  The format for the
command looks like this:

@set flag

Write the conditionally formatted text between @ifset flag
and @end ifset commands, like this:

@ifset flag
conditional-text
@end ifset

For example, you can create one document that has two variants, such as
a manual for a `large' and `small' model:

You can use this machine to dig up shrubs
without hurting them.

@set large

@ifset large
It can also dig up fully grown trees.
@end ifset

Remember to replant promptly ...

In the example, the formatting commands will format the text between
@ifset large and @end ifset because the large
flag is set.

Use the @clear flag command to turn off, or clear,
a flag.  Clearing a flag is the opposite of setting a flag.  The
command looks like this:

@clear flag

Write the command on a line of its own.

When flag is cleared, the Texinfo formatting commands do
not format the text between @ifset flag and
@end ifset; that text is ignored and does not appear in either
printed or Info output.

For example, if you clear the flag of the preceding example by writing
an @clear large command after the @set large command
(but before the conditional text), then the Texinfo formatting commands
ignore the text between the @ifset large and @end ifset
commands.  In the formatted output, that text does not appear; in both
printed and Info output, you see only the lines that say, "You can use
this machine to dig up shrubs without hurting them.  Remember to replant
promptly ...".

If a flag is cleared with an @clear flag command, then
the formatting commands format text between subsequent pairs of
@ifclear and @end ifclear commands.  But if the flag
is set with @set flag, then the formatting commands do
not format text between an @ifclear and an @end
ifclear command; rather, they ignore that text.  An @ifclear
command looks like this:

@ifclear flag

In brief, the commands are:

@set flag

Tell the Texinfo formatting commands that flag is set.

@clear flag

Tell the Texinfo formatting commands that flag is cleared.

@ifset flag

If flag is set, tell the Texinfo formatting commands to format
the text up to the following @end ifset command.
If flag is cleared, tell the Texinfo formatting commands to
ignore text up to the following @end ifset command.

@ifclear flag

If flag is set, tell the Texinfo formatting commands to ignore
the text up to the following @end ifclear command.
If flag is cleared, tell the Texinfo formatting commands to
format the text up to the following @end ifclear
command.

@value

You can use the @set command to specify a value for a flag,
which is expanded by the @value command.  The value is a string
a characters.

Write the @set command like this:

@set foo This is a string.

This sets the value of foo to "This is a string."

The Texinfo formatters replace an @value{flag} command with
the string to which flag is set.

Thus, when foo is set as shown above, the Texinfo formatters convert

@value{foo}
to
This is a string.

You can write an @value command within a paragraph; but you
must write an @set command on a line of its own.

If you write the @set command like this:

@set foo

without specifying a string, the value of foo is an empty string.

If you clear a previously set flag with an @clear flag
command, a subsequent @value{flag} command is invalid and the
string is replaced with an error message that says `{No value for
"flag"}'.

For example, if you set foo as follows:

@set how-much very, very, very

then the formatters transform

It is a @value{how-much} wet day.
into
It is a very, very, very wet day.

If you write

@clear how-much

then the formatters transform

It is a @value{how-much} wet day.
into
It is a {No value for "how-much"} wet day.

@value Example

You can use the @value command to limit the number of places you
need to change when you record an update to a manual.
Here is how it is done in The GNU Make Manual:

Set the flags:

@set EDITION 0.35 Beta
@set VERSION 3.63 Beta
@set UPDATED 14 August 1992
@set UPDATE-MONTH August 1992

Write text for the first @ifinfo section, for people reading the
Texinfo file:

This is Edition @value{EDITION},
last updated @value{UPDATED},
of @cite{The GNU Make Manual},
for @code{make}, Version @value{VERSION}.

Write text for the title page, for people reading the printed manual:

@title GNU Make
@subtitle A Program for Directing Recompilation
@subtitle Edition @value{EDITION}, ...
@subtitle @value{UPDATE-MONTH}

(On a printed cover, a date listing the month and the year looks less
fussy than a date listing the day as well as the month and year.)

Write text for the Top node, for people reading the Info file:

This is Edition @value{EDITION}
of the @cite{GNU Make Manual},
last updated @value{UPDATED}
for @code{make} Version @value{VERSION}.

After you format the manual, the text in the first @ifinfo
section looks like this:

This is Edition 0.35 Beta, last updated 14 August 1992,
of `The GNU Make Manual', for `make', Version 3.63 Beta.

When you update the manual, change only the values of the flags; you do
not need to rewrite the three sections.

Macros: Defining New Texinfo Commands

A Texinfo macro allows you to define a new Texinfo command as any
sequence of text and/or existing commands (including other macros).  The
macro can have any number of parameters---text you supply each
time you use the macro.  (This has nothing to do with the
@defmac command, which is for documenting macros in the subject
of the manual; see section The Template for a Definition.)

  • Defining Macros: Both defining and undefining new commands.

  • Invoking Macros: Using a macro, once you've defined it.

Defining Macros

You use the Texinfo @macro command to define a macro.  For example:

@macro macro-name{param1, param2, ...}
text ... \param1\ ...
@end macro

The parameters param1, param2, ... correspond to
arguments supplied when the macro is subsequently used in the document
(see the next section).

If a macro needs no parameters, you can define it either with an empty
list (`@macro foo {}') or with no braces at all (`@macro
foo').

The definition or body of the macro can contain any Texinfo
commands, including previously-defined macros.  (It is not possible to
have mutually recursive Texinfo macros.)  In the body, instances of a
parameter name surrounded by backslashes, as in `\param1\' in
the example above, are replaced by the corresponding argument from the
macro invocation.

You can undefine a macro foo with @unmacro foo.
It is not an error to undefine a macro that is already undefined.
For example:

@unmacro foo

Invoking Macros

After a macro is defined (see the previous section), you can use
(invoke) it in your document like this:

@macro-name {arg1, arg2, ...}

and the result will be just as if you typed the body of
macro-name at that spot.  For example:

@macro foo {p, q}
Together: \p\ & \q\.
@end macro
@foo{a, b}

produces:

Together: a & b.

Thus, the arguments and parameters are separated by commas and delimited
by braces; any whitespace after (but not before) a comma is ignored.  To
insert a comma, brace, or backslash in an argument, prepend a backslash,
as in

@macro-name {\\\{\}\,}

which will pass the (almost certainly error-producing) argument
`\{},' to macro-name.

If the macro is defined to take a single argument, and is invoked
without any braces, the entire rest of the line after the macro name is
supplied as the argument.  For example:

@macro bar {p}
Twice: \p\, \p\.
@end macro
@bar aah

produces:

Twice: aah, aah.

Format and Print Hardcopy

There are three major shell commands for making a printed manual from a
Texinfo file: one for converting the Texinfo file into a file that will be
printed, a second for sorting indices, and a third for printing the
formatted document.  When you use the shell commands, you can either
work directly in the operating system shell or work within a shell
inside GNU Emacs.

If you are using GNU Emacs, you can use commands provided by Texinfo
mode instead of shell commands.  In addition to the three commands to
format a file, sort the indices, and print the result, Texinfo mode
offers key bindings for commands to recenter the output buffer, show the
print queue, and delete a job from the print queue.

  • Format with tex/texindex: How to format in a shell.

  • Format with texi2dvi: A simpler way to use the shell.

  • Print with lpr: How to print.

  • Within Emacs: How to format and print from an Emacs shell.

  • Texinfo Mode Printing: How to format and print in Texinfo mode.

  • Compile-Command: How to print using Emacs's compile command.

  • Requirements Summary: TeX formatting requirements summary.

  • Preparing for TeX: What you need to do to use TeX.

  • Overfull hboxes: What are and what to do with overfull hboxes.

  • smallbook: How to print small format books and manuals.

  • A4 Paper: How to print on European A4 paper.

  • Cropmarks and Magnification: How to print marks to indicate the size
                                of pages and how to print scaled up output.

The typesetting program called TeX is used for formatting a Texinfo
file.  TeX is a very powerful typesetting program and, if used right,
does an exceptionally good job.  (See section How to Obtain TeX, for information on how to obtain TeX.)

The makeinfo, texinfo-format-region, and
texinfo-format-buffer commands read the very same @-commands
in the Texinfo file as does TeX, but process them differently to
make an Info file; see section Creating an Info File.

Format using tex and texindex

Format the Texinfo file with the shell command tex followed by
the name of the Texinfo file.  For example:

tex foo.texi

TeX will produce a DVI file as well as several auxiliary
files containing information for indices, cross references, etc.  The
DVI file (for DeVice Independent file) can be printed on virtually
any printe (see the following sections).

The tex formatting command itself does not sort the indices; it
writes an output file of unsorted index data.  (The texi2dvi
command automatically generates indices; see section Format using texi2dvi.)  To generate a printed index after
running the tex command, you first need a sorted index to work
from.  The texindex command sorts indices.  (The source file
`texindex.c' comes as part of the standard Texinfo distribution,
among other places.)

The tex formatting command outputs unsorted index files under
names that obey a standard convention: the name of your main input file
with any `.tex' (or similar, see section `tex invocation' in Web2c) extension removed, followed by the two letter names of indices.
For example, the raw index output files for the input file
`foo.texinfo' would be `foo.cp', `foo.vr', `foo.fn',
`foo.tp', `foo.pg' and `foo.ky'.  Those are exactly the
arguments to give to texindex.

Instead of specifying all the unsorted index file names explicitly, you
can use `??' as shell wildcards and give the command in this
form:

texindex foo.??

This command will run texindex on all the unsorted index files,
including any that you have defined yourself using @defindex
or @defcodeindex.  (You may execute `texindex foo.??'
even if there are similarly named files with two letter extensions
that are not index files, such as `foo.el'.  The texindex
command reports but otherwise ignores such files.)

For each file specified, texindex generates a sorted index file
whose name is made by appending `s' to the input file name.  The
@printindex command knows to look for a file of that name
(see section Index Menus and Printing an Index).  texindex does not alter the
raw index output file.

After you have sorted the indices, you need to rerun the tex
formatting command on the Texinfo file.  This regenerates the DVI file,
this time with up-to-date index entries.

Finally, you may need to run tex one more time, to get the page
numbers in the cross-references correct.

To summarize, this is a four step process:

  1.

Run tex on your Texinfo file.  This generates a DVI file (with
undefined cross-references and no indices), and the raw index files
(with two letter extensions).

  2.

Run texindex on the raw index files.  This creates the
corresponding sorted index files (with three letter extensions).

  3.

Run tex again on your Texinfo file.  This regenerates the DVI
file, this time with indices and defined cross-references, but with page
numbers for the cross-references from last time, generally incorrect.

  4.

Run tex one last time.  This time the correct page numbers are
written for the cross-references.

Alternatively, it's a one-step process: run texi2dvi.

You need not run texindex each time after you run tex.  If
you do not, on the next run, the tex formatting command will use
whatever sorted index files happen to exist from the previous use of
texindex.  This is usually ok while you are
debugging.

Format using texi2dvi

The texi2dvi command automatically runs both tex and
texindex as many times as necessary to produce a DVI file with
up-to-date, sorted indices.  It simplifies the
tex---texindex---tex sequence described in the
previous section.

The syntax for texi2dvi is like this (where `prompt$' is your
shell prompt):

prompt$ texi2dvi filename...

For a list of options, run `texi2dvi --help'.

Shell Print Using lpr -d

The precise command to print a DVI file depends on your system
installation, but `lpr -d' is common.  The command may require the
DVI file name without any extension or with a `.dvi'
extension.  (If it is `lpr', you must include the `.dvi'.)

The following commands, for example, will (probably) suffice to sort the
indices, format, and print the Bison Manual:

tex bison.texinfo
texindex bison.??
tex bison.texinfo
lpr -d bison.dvi

(Remember that the shell commands may be different at your site; but
these are commonly used versions.)

Using the texi2dvi shell script, you simply need type:

texi2dvi bison.texinfo
lpr -d bison.dvi

From an Emacs Shell

You can give formatting and printing commands from a shell within GNU
Emacs.  To create a shell within Emacs, type M-x shell.  In this
shell, you can format and print the document.  See section Format and Print Hardcopy, for details.

You can switch to and from the shell buffer while tex is
running and do other editing.  If you are formatting a long document
on a slow machine, this can be very convenient.

You can also use texi2dvi from an Emacs shell.  For example,
here is how to use texi2dvi to format and print Using and
Porting GNU CC from a shell within Emacs:

texi2dvi gcc.texinfo
lpr -d gcc.dvi

Formatting and Printing in Texinfo Mode

Texinfo mode provides several predefined key commands for TeX
formatting and printing.  These include commands for sorting indices,
looking at the printer queue, killing the formatting job, and
recentering the display of the buffer in which the operations
occur.

C-c C-t C-b

M-x texinfo-tex-buffer

Run texi2dvi on the current buffer.

C-c C-t C-r

M-x texinfo-tex-region

Run TeX on the current region.

C-c C-t C-i

M-x texinfo-texindex

Sort the indices of a Texinfo file formatted with
texinfo-tex-region.

C-c C-t C-p

M-x texinfo-tex-print

Print a DVI file that was made with texinfo-tex-region or
texinfo-tex-buffer.

C-c C-t C-q

M-x tex-show-print-queue

Show the print queue.

C-c C-t C-d

M-x texinfo-delete-from-print-queue

Delete a job from the print queue; you will be prompted for the job
number shown by a preceding C-c C-t C-q command
(texinfo-show-tex-print-queue).

C-c C-t C-k

M-x tex-kill-job

Kill the currently running TeX job started by
texinfo-tex-region or texinfo-tex-buffer, or any other
process running in the Texinfo shell buffer.

C-c C-t C-x

M-x texinfo-quit-job

Quit a TeX formatting job that has stopped because of an error by
sending an x to it.  When you do this, TeX preserves a record
of what it did in a `.log' file.

C-c C-t C-l

M-x tex-recenter-output-buffer

Redisplay the shell buffer in which the TeX printing and formatting
commands are run to show its most recent output.

Thus, the usual sequence of commands for formatting a buffer is as
follows (with comments to the right):

C-c C-t C-b             Run texi2dvi on the buffer.
C-c C-t C-p             Print the DVI file.
C-c C-t C-q             Display the printer queue.

The Texinfo mode TeX formatting commands start a subshell in Emacs
called the `*tex-shell*'.  The texinfo-tex-command,
texinfo-texindex-command, and tex-dvi-print-command
commands are all run in this shell.

You can watch the commands operate in the `*tex-shell*' buffer,
and you can switch to and from and use the `*tex-shell*' buffer
as you would any other shell buffer.

The formatting and print commands depend on the values of several variables.
The default values are:

     Variable                              Default value

texinfo-texi2dvi-command                  "texi2dvi"
texinfo-tex-command                       "tex"
texinfo-texindex-command                  "texindex"
texinfo-delete-from-print-queue-command   "lprm"
texinfo-tex-trailer                       "@bye"
tex-start-of-header                       "%**start"
tex-end-of-header                         "%**end"
tex-dvi-print-command                     "lpr -d"
tex-show-queue-command                    "lpq"

You can change the values of these variables with the M-x
edit-options command (see section `Editing Variable Values' in The GNU Emacs Manual), with the M-x set-variable command
(see section `Examining and Setting Variables' in The GNU Emacs Manual), or with your `.emacs' initialization file
(see section `Init File' in The GNU Emacs Manual).

Using the Local Variables List

Yet another way to apply the TeX formatting command to a Texinfo file
is to put that command in a local variables list at the end of the
Texinfo file.  You can then specify the tex or texi2dvi
commands as a compile-command and have Emacs run it by typing
M-x compile.  This creates a special shell called the
`*compilation*' buffer in which Emacs runs the compile command.
For example, at the end of the `gdb.texinfo' file, after the
@bye, you could put the following:

Local Variables:
compile-command: "texi2dvi gdb.texinfo"
End:

This technique is most often used by programmers who also compile programs
this way; see section `Compilation' in The GNU Emacs Manual.

TeX Formatting Requirements Summary

Every Texinfo file that is to be input to TeX must begin with a
\input command and must contain an @setfilename command:

\input texinfo
@setfilename arg-not-used-by-TeX

The first command instructs TeX to load the macros it needs to
process a Texinfo file and the second command opens auxiliary files.

Every Texinfo file must end with a line that terminates TeX's
processing and forces out unfinished pages:

@bye

Strictly speaking, these lines are all a Texinfo file needs to be
processed successfully by TeX.

Usually, however, the beginning includes an @settitle command to
define the title of the printed manual, an @setchapternewpage
command, a title page, a copyright page, and permissions.  Besides an
@bye, the end of a file usually includes indices and a table of
contents.  (And of course most manuals contain a body of text as well.)

For more information, see
section @settitle,
section @setchapternewpage,
section Page Headings,
section The Title and Copyright Pages,
section Index Menus and Printing an Index, and
section Generating a Table of Contents.

Preparing to Use TeX

TeX needs to know where to find the `texinfo.tex' file that you
have told it to input with the `\input texinfo' command at the
beginning of the first line.  The `texinfo.tex' file tells TeX
how to handle @-commands; it is included in all standard GNU
distributions.

Usually, the `texinfo.tex' file is put under the default directory
that contains TeX macros
(`/usr/local/share/texmf/tex/texinfo/texinfo.tex' by default) when
GNU Emacs or other GNU software is installed.  In this case, TeX will
find the file and you do not need to do anything special.
Alternatively, you can put `texinfo.tex' in the current directory
when you run TeX, and TeX will find it there.

Also, you should install `epsf.tex' in the same place as
`texinfo.tex', if it is not already installed from another
distribution.  This file is needed to support the @image command
(see section Inserting Images).

Optionally, you may create an additional `texinfo.cnf', and install
it as well.  This file is read by TeX at the @setfilename
command (see section @setfilename).  You can put any
commands you like there according to local site-wide conventions, and
they will be read by TeX when processing any Texinfo document.  For
example, if `texinfo.cnf' contains the a single line
`@afourpaper' (see section Printing on A4 Paper), then all Texinfo documents will
be processed with that page size in effect.  If you have nothing to put
in `texinfo.cnf', you do not need to create it.

If neither of the above locations for these system files suffice for
you, you can specify the directories explicitly.  For
`texinfo.tex', you can do this by writing the complete path for the
file after the \input command.  Another way, that works for both
`texinfo.tex' and `texinfo.cnf' (and any other file TeX
might read), is to set the TEXINPUTS environment variable in your
`.cshrc' or `.profile' file.

Which you use of `.cshrc' or `.profile' depends on
whether you use a Bourne shell-compatible (sh, bash,
ksh, ...) or C shell-compatible (csh, tcsh)
command interpreter.  The latter read the `.cshrc' file for
initialization information, and the former read `.profile'.

In a `.cshrc' file, you could use the following csh command
sequence:

setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros

In a `.profile' file, you could use the following sh command
sequence:

TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
export TEXINPUTS

This would cause TeX to look for `\input' file first in the current
directory, indicated by the `.', then in a hypothetical user's
`me/mylib' directory, and finally in a system directory.

Overfull "hboxes"

TeX is sometimes unable to typeset a line without extending it into
the right margin.  This can occur when TeX comes upon what it
interprets as a long word that it cannot hyphenate, such as an
electronic mail network address or a very long title.  When this
happens, TeX prints an error message like this:

Overfull \hbox (20.76302pt too wide)

(In TeX, lines are in "horizontal boxes", hence the term, "hbox".
The backslash, `\', is the TeX equivalent of `@'.)

TeX also provides the line number in the Texinfo source file and
the text of the offending line, which is marked at all the places that
TeX knows how to hyphenate words.
See section Catching Errors with TeX Formatting,
for more information about typesetting errors.

If the Texinfo file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur, or you can decide to leave it.  A
small excursion into the right margin often does not matter and may not
even be noticeable.

However, unless told otherwise, TeX will print a large, ugly, black
rectangle beside the line that contains the overfull hbox.  This is so
you will notice the location of the problem if you are correcting a
draft.

To prevent such a monstrosity from marring your final printout, write
the following in the beginning of the Texinfo file on a line of its own,
before the @titlepage command:

@finalout

Printing "Small" Books

By default, TeX typesets pages for printing in an 8.5 by 11 inch
format.  However, you can direct TeX to typeset a document in a 7 by
9.25 inch format that is suitable for bound books by inserting the
following command on a line by itself at the beginning of the Texinfo
file, before the title page:

@smallbook

(Since regular sized books are often about 7 by 9.25 inches, this
command might better have been called the @regularbooksize
command, but it came to be called the @smallbook command by
comparison to the 8.5 by 11 inch format.)

If you write the @smallbook command between the
start-of-header and end-of-header lines, the Texinfo mode TeX
region formatting command, texinfo-tex-region, will format the
region in "small" book size (see section Start of Header).

The Free Software Foundation distributes printed copies of The GNU
Emacs Manual and other manuals in the "small" book size.
See section @smallexample and @smalllisp, for information about commands that make it easier
to produce examples for a smaller manual.

Alternatively, to avoid embedding this physical paper size in your
document, use texi2dvi to format your document (see section Format using texi2dvi), and supply `-t @smallbook' as an argument.  Then
other people do not have to change the document source file to format it
differently.

Printing on A4 Paper

You can tell TeX to typeset a document for printing on European size
A4 paper with the @afourpaper command.  Write the command on a
line by itself between @iftex and @end iftex lines near
the beginning of the Texinfo file, before the title page:

For example, this is how you would write the header for this manual:

\input texinfo    @c -*-texinfo-*-
@c %**start of header
@setfilename texinfo
@settitle Texinfo
@syncodeindex vr fn
@iftex
@afourpaper
@end iftex
@c %**end of header

Alternatively, to avoid embedding this physical paper size in your
document, use texi2dvi to format your document (see section Format using texi2dvi), and supply `-t @afourpaper' as an argument.  Then
other people do not have to change the document source file to format it
differently.

Another alternative: put the @afourpaper command in the file
`texinfo.cnf' that TeX will read.  (No need for @iftex
there.)  This will automatically typeset all the Texinfo documents at
your site with that paper size in effect.

Cropmarks and Magnification

You can attempt to direct TeX to print cropmarks at the corners of
pages with the @cropmarks command.  Write the @cropmarks
command on a line by itself between @iftex and @end
iftex lines near the beginning of the Texinfo file, before the title
page, like this:

@iftex
@cropmarks
@end iftex

This command is mainly for printers that typeset several pages on one
sheet of film; but you can attempt to use it to mark the corners of a
book set to 7 by 9.25 inches with the @smallbook command.
(Printers will not produce cropmarks for regular sized output that is
printed on regular sized paper.)  Since different printing machines work
in different ways, you should explore the use of this command with a
spirit of adventure.  You may have to redefine the command in the
`texinfo.tex' definitions file.

You can attempt to direct TeX to typeset pages larger or smaller than
usual with the \mag TeX command.  Everything that is typeset
is scaled proportionally larger or smaller.  (\mag stands for
"magnification".)  This is not a Texinfo @-command, but is a
plain TeX command that is prefixed with a backslash.  You have to
write this command between @tex and @end tex
(see section Raw Formatter Commands).

Follow the \mag command with an `=' and then a number that
is 1000 times the magnification you desire.  For example, to print pages
at 1.2 normal size, write the following near the beginning of the
Texinfo file, before the title page:

@tex
\mag=1200
@end tex

With some printing technologies, you can print normal-sized copies that
look better than usual by using a larger-than-normal master.

Depending on your system, \mag may not work or may work only at
certain magnifications.  Be prepared to experiment.

Creating an Info File

makeinfo is a utility that converts a Texinfo file into an Info
file; texinfo-format-region and texinfo-format-buffer are
GNU Emacs functions that do the same.

A Texinfo file must contain an @setfilename line near its
beginning, otherwise the Info formatting commands will fail.

For information on installing the Info file in the Info system, see
section Installing an Info File.

  • Invoking makeinfo: How to run makeinfo from a shell.

  • makeinfo options: Specify fill-column and other options.

  • Pointer Validation: How to check that pointers point somewhere.

  • makeinfo in Emacs: How to run makeinfo from Emacs.

  • texinfo-format commands: Two Info formatting commands written
                                  in Emacs Lisp are an alternative
                                  to makeinfo.

  • Batch Formatting: How to format for Info in Emacs Batch mode.

  • Tag and Split Files: How tagged and split files help Info
                                  to run better.

The makeinfo utility creates an Info file from a Texinfo source
file more quickly than either of the Emacs formatting commands and
provides better error messages.  We recommend it.  makeinfo is a
C program that is independent of Emacs.  You do not need to run Emacs to
use makeinfo, which means you can use makeinfo on machines
that are too small to run Emacs. You can run makeinfo in
any one of three ways: from an operating system shell, from a shell
inside Emacs, or by typing a key command in Texinfo mode in Emacs.

The texinfo-format-region and the texinfo-format-buffer
commands are useful if you cannot run makeinfo.  Also, in some
circumstances, they format short regions or buffers more quickly than
makeinfo.

Running makeinfo from a Shell

To create an Info file from a Texinfo file, type makeinfo
followed by the name of the Texinfo file.  Thus, to create the Info
file for Bison, type the following to the shell:
is the prompt):

makeinfo bison.texinfo

(You can run a shell inside Emacs by typing M-x shell.)

Options for makeinfo

The makeinfo command takes a number of options.  Most often,
options are used to set the value of the fill column and specify the
footnote style.  Each command line option is a word preceded by
`--' or a letter preceded by `-'.  You can use abbreviations
for the long option names as long as they are unique.

For example, you could use the following shell command to create an Info
file for `bison.texinfo' in which each line is filled to only 68
columns:

makeinfo --fill-column=68 bison.texinfo

You can write two or more options in sequence, like this:

makeinfo --no-split --fill-column=70 ...

This would keep the Info file together as one possibly very long
file and would also set the fill column to 70.

The options are:

-D var

Cause the variable var to be defined.  This is equivalent to
@set var in the Texinfo file (see section @set, @clear, and @value).

--error-limit=limit

Set the maximum number of errors that makeinfo will report
before exiting (on the assumption that continuing would be useless);
default 100.

--fill-column=width

Specify the maximum number of columns in a line; this is the right-hand
edge of a line.  Paragraphs that are filled will be filled to this
width.  (Filling is the process of breaking up and connecting lines so
that lines are the same length as or shorter than the number specified
as the fill column.  Lines are broken between words.) The default value
is 72.

--footnote-style=style

Set the footnote style to style, either `end' for the end
node style (the default) or `separate' for the separate node style.
The value set by this option overrides the value set in a Texinfo file
by an @footnotestyle command (see section Footnotes).  When the
footnote style is `separate', makeinfo makes a new node
containing the footnotes found in the current node.  When the footnote
style is `end', makeinfo places the footnote references at
the end of the current node.

--force

Ordinarily, if the input file has errors, the output files are not
created.  With this option, they are preserved.

--help

Print a usage message listing all available options, then exit successfully.

-I dir

Add dir to the directory search list for finding files that are
included using the @include command.  By default,
makeinfo searches only the current directory.

--no-headers

Do not include menus or node lines in the output.  This results in an
ASCII file that you cannot read in Info since it does not contain
the requisite nodes or menus. It is primarily useful to extract certain
pieces of a manual into separate files to be included in a distribution,
such as `INSTALL' files.

--no-split

Suppress the splitting stage of makeinfo.  By default, large
output files (where the size is greater than 70k bytes) are split into
smaller subfiles, each one approximately 50k bytes.

--no-pointer-validate

--no-validate

Suppress the pointer-validation phase of makeinfo.  Normally,
after a Texinfo file is processed, some consistency checks are made to
ensure that cross references can be resolved, etc.
See section Pointer Validation.

--no-warn

Suppress warning messages (but not error messages).  You might
want this if the file you are creating has examples of Texinfo cross
references within it, and the nodes that are referenced do not actually
exist.

--no-number-footnotes

Suppress automatic footnote numbering.  By default, makeinfo
numbers each footnote sequentially in a single node, resetting the
current footnote number to 1 at the start of each node.

--output=file

-o file

Specify that the output should be directed to file and not to the
file name specified in the @setfilename command found in the
Texinfo source (see section @setfilename).  If file is `-', output
goes to standard output and `--no-split' is implied.

-P dir

Prepend dir to the directory search list for @include.
See `-I' for more details.

--paragraph-indent=indent

Set the paragraph indentation style to indent.  The value set by
this option overrides the value set in a Texinfo file by an
@paragraphindent command (see section Paragraph Indenting).  The value
of indent is interpreted as follows:

`asis'

Preserve any existing indentation at the starts of paragraphs.

`0' or `none'

Delete any existing indentation.

num

Indent each paragraph by that number of spaces.

--reference-limit=limit

Set the value of the number of references to a node that
makeinfo will make without reporting a warning.  If a node has more
than this number of references in it, makeinfo will make the
references but also report a warning.  The default is 1000.

-U var

Cause var to be undefined.  This is equivalent to
@clear var in the Texinfo file (see section @set, @clear, and @value).

--verbose

Cause makeinfo to display messages saying what it is doing.
Normally, makeinfo only outputs messages if there are errors or
warnings.

--version

Print the version number, then exit successfully.

Pointer Validation

If you do not suppress pointer-validation, makeinfo will check
the validity of the final Info file.  Mostly, this means ensuring that
nodes you have referenced really exist.  Here is a complete list of what
is checked:

  1.

If a `Next', `Previous', or `Up' node reference is a reference to a
node in the current file and is not an external reference such as to
`(dir)', then the referenced node must exist.

  2.

In every node, if the `Previous' node is different from the `Up' node,
then the `Previous' node must also be pointed to by a `Next' node.

  3.

Every node except the `Top' node must have an `Up' pointer.

  4.

The node referenced by an `Up' pointer must contain a reference to the
current node in some manner other than through a `Next' reference.
This includes menu entries and cross references.

  5.

If the `Next' reference of a node is not the same as the `Next' reference
of the `Up' reference, then the node referenced by the `Next' pointer
must have a `Previous' pointer that points back to the current node.
This rule allows the last node in a section to point to the first node
of the next chapter.

Running makeinfo inside Emacs

You can run makeinfo in GNU Emacs Texinfo mode by using either the
makeinfo-region or the makeinfo-buffer commands.  In
Texinfo mode, the commands are bound to C-c C-m C-r and C-c
C-m C-b by default.

C-c C-m C-r

M-x makeinfo-region

Format the current region for Info.

C-c C-m C-b

M-x makeinfo-buffer

Format the current buffer for Info.

When you invoke either makeinfo-region or
makeinfo-buffer, Emacs prompts for a file name, offering the
name of the visited file as the default.  You can edit the default
file name in the minibuffer if you wish, before pressing RET to
start the makeinfo process.

The Emacs makeinfo-region and makeinfo-buffer commands
run the makeinfo program in a temporary shell buffer.  If
makeinfo finds any errors, Emacs displays the error messages in
the temporary buffer.

You can parse the error messages by typing C-x `
(next-error).  This causes Emacs to go to and position the
cursor on the line in the Texinfo source that makeinfo thinks
caused the error.  See section `Running make or Compilers Generally' in The GNU Emacs Manual, for more
information about using the next-error command.

In addition, you can kill the shell in which the makeinfo
command is running or make the shell buffer display its most recent
output.

C-c C-m C-k

M-x makeinfo-kill-job

Kill the current running makeinfo job created by
makeinfo-region or makeinfo-buffer.

C-c C-m C-l

M-x makeinfo-recenter-output-buffer

Redisplay the makeinfo shell buffer to display its most recent
output.

(Note that the parallel commands for killing and recentering a TeX
job are C-c C-t C-k and C-c C-t C-l.  See section Formatting and Printing in Texinfo Mode.)

You can specify options for makeinfo by setting the
makeinfo-options variable with either the M-x
edit-options or the M-x set-variable command, or by setting the
variable in your `.emacs' initialization file.

For example, you could write the following in your `.emacs' file:

(setq makeinfo-options
      "--paragraph-indent=0 --no-split
       --fill-column=70 --verbose")

For more information, see section Options for makeinfo, as well as "Editing Variable Values,""Examining and
Setting Variables," and "Init File" in the The GNU Emacs
Manual.

The texinfo-format... Commands

In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
file with the texinfo-format-region command.  This formats the
current region and displays the formatted text in a temporary buffer
called `*Info Region*'.

Similarly, you can format a buffer with the
texinfo-format-buffer command.  This command creates a new
buffer and generates the Info file in it.  Typing C-x C-s will
save the Info file under the name specified by the
@setfilename line which must be near the beginning of the
Texinfo file.

C-c C-e C-r

texinfo-format-region

Format the current region for Info.

C-c C-e C-b

texinfo-format-buffer

Format the current buffer for Info.

The texinfo-format-region and texinfo-format-buffer
commands provide you with some error checking, and other functions can
provide you with further help in finding formatting errors.  These
procedures are described in an appendix; see section Formatting Mistakes.
However, the makeinfo program is often faster and
provides better error checking (see section Running makeinfo inside Emacs).

Batch Formatting

You can format Texinfo files for Info using batch-texinfo-format
and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
including a shell inside of Emacs.  (See section `Command Line Switches and Arguments' in The GNU Emacs Manual.)

Here is a shell command to format all the files that end in
`.texinfo' in the current directory:

emacs -batch -funcall batch-texinfo-format *.texinfo

Emacs processes all the files listed on the command line, even if an
error occurs while attempting to format some of them.

Run batch-texinfo-format only with Emacs in Batch mode as shown;
it is not interactive.  It kills the Batch mode Emacs on completion.

batch-texinfo-format is convenient if you lack makeinfo
and want to format several Texinfo files at once.  When you use Batch
mode, you create a new Emacs process.  This frees your current Emacs, so
you can continue working in it.  (When you run
texinfo-format-region or texinfo-format-buffer, you cannot
use that Emacs for anything else until the command finishes.)

Tag Files and Split Files

If a Texinfo file has more than 30,000 bytes,
texinfo-format-buffer automatically creates a tag table
for its Info file;  makeinfo always creates a tag table.  With
a tag table, Info can jump to new nodes more quickly than it can
otherwise.

In addition, if the Texinfo file contains more than about 70,000
bytes, texinfo-format-buffer and makeinfo split the
large Info file into shorter indirect subfiles of about 50,000
bytes each.  Big files are split into smaller files so that Emacs does
not need to make a large buffer to hold the whole of a large Info
file; instead, Emacs allocates just enough memory for the small, split
off file that is needed at the time.  This way, Emacs avoids wasting
memory when you run Info.  (Before splitting was implemented, Info
files were always kept short and include files were designed as
a way to create a single, large printed manual out of the smaller Info
files.  See section Include Files, for more information.  Include files are
still used for very large documents, such as The Emacs Lisp
Reference Manual, in which each chapter is a separate file.)

When a file is split, Info itself makes use of a shortened version of
the original file that contains just the tag table and references to
the files that were split off.  The split off files are called
indirect files.

The split off files have names that are created by appending `-1',
`-2', `-3' and so on to the file name specified by the
@setfilename command.  The shortened version of the original file
continues to have the name specified by @setfilename.

At one stage in writing this document, for example, the Info file was saved
as `test-texinfo' and that file looked like this:

Info file: test-texinfo,    -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo

^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
...

(But `test-texinfo' had far more nodes than are shown here.)  Each of
the split off, indirect files, `test-texinfo-1',
`test-texinfo-2', and `test-texinfo-3', is listed in this file
after the line that says `Indirect:'.  The tag table is listed after
the line that says `Tag table:'.

In the list of indirect files, the number following the file name
records the cumulative number of bytes in the preceding indirect files,
not counting the file list itself, the tag table, or the permissions
text in each file.  In the tag table, the number following the node name
records the location of the beginning of the node, in bytes from the
beginning.

If you are using texinfo-format-buffer to create Info files,
you may want to run the Info-validate command.  (The
makeinfo command does such a good job on its own, you do not
need Info-validate.)  However, you cannot run the M-x
Info-validate node-checking command on indirect files.  For
information on how to prevent files from being split and how to
validate the structure of the nodes, see section Running Info-validate.

Installing an Info File

Info files are usually kept in the `info' directory.  You can read
Info files using the standalone Info program or the Info reader built
into Emacs.  (See Info file `info', node `Top', for an introduction to Info.)

  • New Info File: Listing a new info file.

  • Other Info Directories: How to specify Info files that are
                                  located in other directories.

  • Installing Dir Entries: How to specify what menu entry to add
                                  to the Info directory.

  • Invoking install-info: install-info options.

For Info to work, the `info' directory must contain a file that
serves as a top level directory for the Info system.  By convention,
this file is called `dir'.  (You can find the location of this file
within Emacs by typing C-h i to enter Info and then typing
C-x C-f to see the pathname to the `info' directory.)

The `dir' file is itself an Info file.  It contains the top level
menu for all the Info files in the system.  The menu looks like
this:

* Menu:

* Info:    (info).     Documentation browsing system.
* Emacs:   (emacs).    The extensible, self-documenting
                       text editor.
* Texinfo: (texinfo).  With one source file, make
                       either a printed manual using
                       TeX or an Info file.
...

Each of these menu entries points to the `Top' node of the Info file
that is named in parentheses.  (The menu entry does not need to
specify the `Top' node, since Info goes to the `Top' node if no node
name is mentioned.  See section Referring to Other Info Files.)

Thus, the `Info' entry points to the `Top' node of the
`info' file and the `Emacs' entry points to the `Top' node
of the `emacs' file.

In each of the Info files, the `Up' pointer of the `Top' node refers
back to the dir file.  For example, the line for the `Top'
node of the Emacs manual looks like this in Info:

File: emacs  Node: Top, Up: (DIR), Next: Distrib

(Note that in this case, the `dir' file name is written in upper
case letters--it can be written in either upper or lower case.  Info
has a feature that it will change the case of the file name to lower
case if it cannot find the name as written.)

Listing a New Info File

To add a new Info file to your system, you must write a menu entry to
add to the menu in the `dir' file in the `info' directory.
For example, if you were adding documentation for GDB, you would write
the following new entry:

* GDB: (gdb).           The source-level C debugger.

The first part of the menu entry is the menu entry name, followed by a
colon.  The second part is the name of the Info file, in parentheses,
followed by a period.  The third part is the description.

The name of an Info file often has a `.info' extension.  Thus, the
Info file for GDB might be called either `gdb' or `gdb.info'.
The Info reader programs automatically try the file name both with and
without `.info'; so it is better to avoid clutter and not to write
`.info' explicitly in the menu entry.  For example, the GDB menu
entry should use just `gdb' for the file name, not `gdb.info'.

Info Files in Other Directories

If an Info file is not in the `info' directory, there are three
ways to specify its location:

  •

Write the pathname in the `dir' file as the second part of the
menu.

  •

If you are using Emacs, list the name of the file in a second `dir'
file, in its directory; and then add the name of that directory to the
Info-directory-list variable in your personal or site
initialization file.

This tells Emacs where to look for `dir' files.  Emacs merges the
files named `dir' from each of the listed directories.  (In Emacs
version 18, you can set the Info-directory variable to the name
of only one directory.)

  •

Specify the Info directory name in the INFOPATH environment
variable in your `.profile' or `.cshrc' initialization file.
(Only you and others who set this environment variable will be able to
find Info files whose location is specified this way.)

For example, to reach a test file in the `/home/bob/manuals'
directory, you could add an entry like this to the menu in the
`dir' file:

* Test: (/home/bob/manuals/info-test).  Bob's own test file.

In this case, the absolute file name of the `info-test' file is
written as the second part of the menu entry.

Alternatively, you could write the following in your `.emacs'
file:

(setq Info-directory-list
      '("/home/bob/manuals"
        "/usr/local/info"))

This tells Emacs to merge the `dir' file from the
`/home/bob/manuals' directory with the `dir' file from the
`/usr/local/info' directory.  Info will list the
`/home/bob/manuals/info-test' file as a menu entry in the
`/home/bob/manuals/dir' file.

Finally, you can tell Info where to look by setting the INFOPATH
environment variable in your `.cshrc' or `.profile' file.  If
you use a Bourne-compatible shell such as sh or bash for
your shell command interpreter, you set the INFOPATH environment
variable in the `.profile' initialization file; but if you use
csh or tcsh, you must set the variable in the
`.cshrc' initialization file.  The two types of shells use
different syntax.

  •

In a `.cshrc' file, you could set the INFOPATH
variable as follows:

    setenv INFOPATH .:~/manuals:/usr/local/emacs/info

  •

In a `.profile' file, you would achieve the same effect by
writing:

    INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
export INFOPATH

The `.' indicates the current directory as usual.  Emacs uses the
INFOPATH environment variable to initialize the value of Emacs's
own Info-directory-list variable.

However you set INFOPATH, if its last character is a colon, this
is replaced by the default (compiled-in) path.  This gives you a way to
augment the default path with new directories without having to list all
the standard places.  For example (using sh syntax:

INFOPATH=/local/info:
export INFOPATH

will search `/local/info' first, then the standard directories.
Leading or doubled colons are not treated specially.

Installing Info Directory Files

When you install an Info file onto your system, you can use the program
install-info to update the Info directory file `dir'.
Normally the makefile for the package runs install-info, just
after copying the Info file into its proper installed location.

In order for the Info file to work with install-info, you should
use the commands @dircategory and @direntry in the
Texinfo source file.  Use @direntry to specify the menu entry to
add to the Info directory file, and use @dircategory to specify
which part of the Info directory to put it in.  Here is how these
commands are used in this manual:

@dircategory Texinfo documentation system
@direntry
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
@end direntry

Here's what this produces in the Info file:

INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
END-INFO-DIR-ENTRY

The install-info program sees these lines in the Info file, and
that is how it knows what to do.

Always use the @direntry and @dircategory commands near
the beginning of the Texinfo input, before the first @node
command.  If you use them later on in the input, install-info
will not notice them.

If you use @dircategory more than once in the Texinfo source,
each usage specifies one category; the new menu entry is added to the
Info directory file in each of the categories you specify.  If you use
@direntry more than once, each usage specifies one menu entry;
each of these menu entries is added to the directory in each of the
specified categories.

Invoking install-info

install-info inserts menu entries from an Info file into the
top-level `dir' file in the Info system (see the previous sections
for an explanation of how the `dir' file works).  It's most often
run as part of software installation, or when constructing a dir file
for all manuals on a system.  Synopsis:

install-info [option]... [info-file [dir-file]]

If info-file or dir-file are not specified, the various
options (described below) that define them must be.  There are no
compile-time defaults, and standard input is never used.
install-info can read only one info file and write only one dir
file per invocation.

If dir-file (however specified) does not exist,
install-info creates it if possible (with no entries).

Options:

--delete

Delete the entries in info-file from dir-file.  The file
name in the entry in dir-file must be info-file (except for
an optional `.info' in either one).  Don't insert any new entries.

--dir-file=name

Specify file name of the Info directory file.  This is equivalent to
using the dir-file argument.

--entry=text

Insert text as an Info directory entry; text should have the
form of an Info menu item line plus zero or more extra lines starting
with whitespace.  If you specify more than one entry, they are all
added.  If you don't specify any entries, they are determined from
information in the Info file itself.

--help

Display a usage message listing basic usage and all available options,
then exit successfully.

--info-file=file

Specify Info file to install in the directory.
This is equivalent to using the info-file argument.

--info-dir=dir

Equivalent to `--dir-file=dir/dir'.

--item=text

Same as `--entry=text'.  An Info directory entry is actually
a menu item.

--quiet

Suppress warnings.

--remove

Same as `--delete'.

--section=sec

Put this file's entries in section sec of the directory.  If you
specify more than one section, all the entries are added in each of the
sections.  If you don't specify any sections, they are determined from
information in the Info file itself.

--version

Display version information and exit successfully.

@-Command List

Here is an alphabetical list of the @-commands in Texinfo.  Square
brackets, [ ], indicate optional arguments; an ellipsis,
`...', indicates repeated text.

@whitespace

An @ followed by a space, tab, or newline produces a normal,
stretchable, interword space.  See section Multiple Spaces.

@!

Generate an exclamation point that really does end a sentence (usually
after an end-of-sentence capital letter).  See section Ending a Sentence.

@"

@'

Generate an umlaut or acute accent, respectively, over the next
character, as in @"o and 'o.  See section Inserting Accents.

@*

Force a line break. Do not end a paragraph that uses @* with
an @refill command.  See section @*: Generate Line Breaks.

@,{c}

Generate a cedilla accent under c, as in @,{c}.  See section Inserting Accents.

@-

Insert a discretionary hyphenation point.  See section @- and @hyphenation: Helping TeX hyphenate.

@.

Produce a period that really does end a sentence (usually after an
end-of-sentence capital letter).  See section Ending a Sentence.

@:

Indicate to TeX that an immediately preceding period, question
mark, exclamation mark, or colon does not end a sentence.  Prevent
TeX from inserting extra whitespace as it does at the end of a
sentence.  The command has no effect on the Info file output.
See section Not Ending a Sentence.

@=

Generate a macro (bar) accent over the next character, as in @=o.
See section Inserting Accents.

@?

Generate a question mark that really does end a sentence (usually after
an end-of-sentence capital letter).  See section Ending a Sentence.

@@

Stands for an at sign, `@'.
See section Inserting @ and Braces.

@^

@`

Generate a circumflex (hat) or grave accent, respectively, over the next
character, as in @^o.
See section Inserting Accents.

@{

Stands for a left brace, `{'.
See section Inserting @ and Braces.

@}

Stands for a right-hand brace, `}'.

See section Inserting @ and Braces.

@=

Generate a tilde accent over the next character, as in @~N.
See section Inserting Accents.

@AA{}

@aa{}

Generate the uppercase and lowercase Scandinavian A-ring letters,
respectively: Å, å.  See section Inserting Accents.

@AE{}

@ae{}

Generate the uppercase and lowercase AE ligatures, respectively:
Æ, æ.  See section Inserting Accents.

@afourpaper

Change page dimensions for the A4 paper size.
Only allowed inside @iftex ... @end iftex.
See section Printing on A4 Paper.

@appendix title

Begin an appendix.  The title appears in the table
of contents of a printed manual.  In Info, the title is
underlined with asterisks.  See section @unnumbered, @appendix.

@appendixsec title

@appendixsection title

Begin an appendix section within an appendix.  The section title appears
in the table of contents of a printed manual.  In Info, the title is
underlined with equal signs.  @appendixsection is a longer
spelling of the @appendixsec command.  See section @unnumberedsec, @appendixsec, @heading.

@appendixsubsec title

Begin an appendix subsection within an appendix.  The title appears
in the table of contents of a printed manual.  In Info, the title is
underlined with hyphens.  See section The @subsection-like Commands.

@appendixsubsubsec title

Begin an appendix subsubsection within an appendix subsection.  The
title appears in the table of contents of a printed manual.  In Info,
the title is underlined with periods.  See section The `subsub' Commands.

@asis

Used following @table, @ftable, and @vtable to
print the table's first column without highlighting ("as is").
See section Making a Two-column Table.

@author author

Typeset author flushleft and underline it.  See section @title, @subtitle, and @author.

@b{text}

Print text in bold font.  No effect in Info.  See section Fonts for Printing, Not Info.

@bullet{}

Generate a large round dot, or the closest possible
thing to one.  See section @bullet{} (*).

@bye

Stop formatting a file.  The formatters do not see the contents of a
file following an @bye command.  See section Ending a Texinfo File.

@c comment

Begin a comment in Texinfo.  The rest of the line does not appear in
either the Info file or the printed manual.  A synonym for
@comment.  See section Comments.

@cartouche

Highlight an example or quotation by drawing a box with rounded
corners around it.  Pair with @end cartouche.  No effect in
Info.  See section Drawing Cartouches Around Examples.)

@center line-of-text

Center the line of text following the command.
See section @titlefont, @center, and @sp.

@centerchap line-of-text

Like @chapter, but centers the chapter title.  See section @chapter.

@chapheading title

Print a chapter-like heading in the text, but not in the table of
contents of a printed manual.  In Info, the title is underlined with
asterisks.  See section @majorheading, @chapheading.

@chapter title

Begin a chapter.  The chapter title appears in the table of
contents of a printed manual.  In Info, the title is underlined with
asterisks.  See section @chapter.

@cindex entry

Add entry to the index of concepts.  See section Making Index Entries.

@cite{reference}

Highlight the name of a book or other reference that lacks a
companion Info file.  See section @cite{reference}.

@clear flag

Unset flag, preventing the Texinfo formatting commands from
formatting text between subsequent pairs of @ifset flag
and @end ifset commands, and preventing
@value{flag} from expanding to the value to which
flag is set.
See section @set, @clear, and @value.

@code{sample-code}

Highlight text that is an expression, a syntactically complete token
of a program, or a program name.  See section @code{sample-code}.

@comment comment

Begin a comment in Texinfo.  The rest of the line does not appear in
either the Info file or the printed manual.  A synonym for @c.
See section Comments.

@contents

Print a complete table of contents.  Has no effect in Info, which uses
menus instead.  See section Generating a Table of Contents.

@copyright{}

Generate a copyright symbol.  See section @copyright{} (©).

@defcodeindex index-name

Define a new index and its indexing command.  Print entries in an
@code font.  See section Defining New Indices.

@defcv category class name

@defcvx category class name

Format a description for a variable associated with a class in
object-oriented programming.  Takes three arguments: the category of
thing being defined, the class to which it belongs, and its name.
See section Definition Commands, and section Two or More `First' Lines.

@deffn category name arguments...

@deffnx category name arguments...

Format a description for a function, interactive command, or similar
entity that may take arguments.  @deffn takes as arguments the
category of entity being described, the name of this particular
entity, and its arguments, if any.  See section Definition Commands.

@defindex index-name

Define a new index and its indexing command.  Print entries in a roman
font.  See section Defining New Indices.

@definfoenclose new-command, before, after,

Create new @-command for Info that marks text by enclosing it in
strings that precede and follow the text.  Write definition inside of
@ifinfo ... @end ifinfo. See section Customized Highlighting.

@defivar class instance-variable-name

@defivarx class instance-variable-name

This command formats a description for an instance variable in
object-oriented programming.  The command is equivalent to `@defcv
{Instance Variable} ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defmac macro-name arguments...

@defmacx macro-name arguments...

Format a description for a macro.  The command is equivalent to
`@deffn Macro ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defmethod class method-name arguments...

@defmethodx class method-name arguments...

Format a description for a method in object-oriented programming.  The
command is equivalent to `@defop Method ...'.  Takes as
arguments the name of the class of the method, the name of the
method, and its arguments, if any.  See section Definition Commands, and
section Two or More `First' Lines.

@defop category class name arguments...

@defopx category class name arguments...

Format a description for an operation in object-oriented programming.
@defop takes as arguments the overall name of the category of
operation, the name of the class of the operation, the name of the
operation, and its arguments, if any.  See section Definition Commands, and section Two or More `First' Lines.

@defopt option-name

@defoptx option-name

Format a description for a user option.  The command is equivalent to
`@defvr {User Option} ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defspec special-form-name arguments...

@defspecx special-form-name arguments...

Format a description for a special form.  The command is equivalent to
`@deffn {Special Form} ...'.  See section Definition Commands,
and section Two or More `First' Lines.

@deftp category name-of-type attributes...

@deftpx category name-of-type attributes...

Format a description for a data type.  @deftp takes as arguments
the category, the name of the type (which is a word like `int' or
`float'), and then the names of attributes of objects of that type.
See section Definition Commands, and section Two or More `First' Lines.

@deftypefn classification data-type name arguments...

@deftypefnx classification data-type name arguments...

Format a description for a function or similar entity that may take
arguments and that is typed.  @deftypefn takes as arguments the
classification of entity being described, the type, the name of the
entity, and its arguments, if any.  See section Definition Commands, and
section Two or More `First' Lines.

@deftypefun data-type function-name arguments...

@deftypefunx data-type function-name arguments...

Format a description for a function in a typed language.
The command is equivalent to `@deftypefn Function ...'.
See section Definition Commands,
and section Two or More `First' Lines.

@deftypemethod class data-type method-name arguments...

@deftypemethodx class data-type method-name arguments...

Format a description for a typed method in object-oriented programming.
Takes as arguments the name of the class of the method, the return type
of the method, the name of the method, and its arguments, if any.
See section Definition Commands, and section Two or More `First' Lines.

@deftypevr classification data-type name

@deftypevrx classification data-type name

Format a description for something like a variable in a typed
language--an entity that records a value.  Takes as arguments the
classification of entity being described, the type, and the name of the
entity.  See section Definition Commands, and section Two or More `First' Lines.

@deftypevar data-type variable-name

@deftypevarx data-type variable-name

Format a description for a variable in a typed language.  The command is
equivalent to `@deftypevr Variable ...'.  See section Definition Commands, and section Two or More `First' Lines.

@defun function-name arguments...

@defunx function-name arguments...

Format a description for functions.  The command is equivalent to
`@deffn Function ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defvar variable-name

@defvarx variable-name

Format a description for variables.  The command is equivalent to
`@defvr Variable ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defvr category name

@defvrx category name

Format a description for any kind of variable.  @defvr takes
as arguments the category of the entity and the name of the entity.
See section Definition Commands,
and section Two or More `First' Lines.

@detailmenu{}

Avoid makeinfo confusion stemming from the detailed node listing
in a master menu.  See section Parts of a Master Menu.

@dfn{term}

Highlight the introductory or defining use of a term.
See section @dfn{term}.

@dircategory dirpart

Specify a part of the Info directory menu where this file's entry should
go.  See section Installing Info Directory Files.

@direntry

Begin the Info directory menu entry for this file.
See section Installing Info Directory Files.

@display

Begin a kind of example.  Indent text, do not fill, do not select a
new font.  Pair with @end display.  See section @display.

@dmn{dimension}

Format a unit of measure, as in 12pt.  Causes TeX to insert a
thin space before dimension.  No effect in Info.
See section @dmn{dimension}: Format a Dimension.

@dotaccent{c}

Generate a dot accent over the character c, as in @dotaccent{oo}.
See section Inserting Accents.

@dots{}

Insert an ellipsis: `...'.
See section @dots{} (...).

@email{address[, displayed-text]}

Indicate an electronic mail address.
See section @email{email-address[, displayed-text]}.

@emph{text}

Highlight text; text is displayed in italics in printed
output, and surrounded by asterisks in Info.  See section Emphasizing Text.

@end environment

Ends environment, as in `@end example'.  See section @-commands.

@enddots{}

Generate an end-of-sentence of ellipsis, like this ....
See section @dots{} (...).

@enumerate [number-or-letter]

Begin a numbered list, using @item for each entry.
Optionally, start list with number-or-letter.  Pair with
@end enumerate.  See section Making a Numbered or Lettered List.

@equiv{}

Indicate to the reader the exact equivalence of two forms with a
glyph: `=='.  See section @equiv{} (==): Indicating Equivalence.

@error{}

Indicate to the reader with a glyph that the following text is
an error message: `error-->'.  See section @error{} (error-->): Indicating an Error Message.

@evenfooting [left] @| [center] @| [right]

@evenheading [left] @| [center] @| [right]

Specify page footings resp. headings for even-numbered (left-hand)
pages.  Only allowed inside @iftex.  See section How to Make Your Own Headings.

@everyfooting [left] @| [center] @| [right]

@everyheading [left] @| [center] @| [right]

Specify page footings resp. headings for every page.  Not relevant to
Info.  See section How to Make Your Own Headings.

@example

Begin an example.  Indent text, do not fill, and select fixed-width font.
Pair with @end example.  See section @example.

@exclamdown{}

Produce an upside-down exclamation point.  See section Inserting Accents.

@exdent line-of-text

Remove any indentation a line might have.  See section @exdent: Undoing a Line's Indentation.

@expansion{}

Indicate the result of a macro expansion to the reader with a special
glyph: `==>'.
See section @expansion{} (==>): Indicating an Expansion.

@file{filename}

Highlight the name of a file, buffer, node, or directory.  See section @file{file-name}.

@finalout

Prevent TeX from printing large black warning rectangles beside
over-wide lines.  See section Overfull "hboxes".

@findex entry

Add entry to the index of functions.  See section Making Index Entries.

@flushleft

@flushright

Left justify every line but leave the right end ragged.
Leave font as is.  Pair with @end flushleft.
@flushright analogous.
See section @flushleft and @flushright.

@footnote{text-of-footnote}

Enter a footnote.  Footnote text is printed at the bottom of the page
by TeX; Info may format in either `End' node or `Separate' node style.
See section Footnotes.

@footnotestyle style

Specify an Info file's footnote style, either `end' for the end
node style or `separate' for the separate node style.
See section Footnotes.

@format

Begin a kind of example.  Like @example or @display,
but do not narrow the margins and do not select the fixed-width font.
Pair with @end format.  See section @example.

@ftable formatting-command

Begin a two-column table, using @item for each entry.
Automatically enter each of the items in the first column into the
index of functions.  Pair with @end ftable.  The same as
@table, except for indexing.  See section @ftable and @vtable.

@group

Hold text together that must appear on one printed page.  Pair with
@end group.  Not relevant to Info.  See section @group: Prevent Page Breaks.

@H{c}

Generate the long Hungarian umlaut accent over c, as in @H{o}.

@heading title

Print an unnumbered section-like heading in the text, but not in the
table of contents of a printed manual.  In Info, the title is
underlined with equal signs.  See section @unnumberedsec, @appendixsec, @heading.

@headings on-off-single-double

Turn page headings on or off, and/or specify single-sided or double-sided
page headings for printing.  See section The @headings Command.

@html

Enter HTML completely.  Pair with @end html.  See section Raw Formatter Commands.

@hyphenation{hy-phen-a-ted words}

Explicitly define hyphenation points.  See section @- and @hyphenation: Helping TeX hyphenate.

@i{text}

Print text in italic font.  No effect in Info.
See section Fonts for Printing, Not Info.

@ifclear flag

If flag is cleared, the Texinfo formatting commands format text
between @ifclear flag and the following @end
ifclear command.
See section @set, @clear, and @value.

@ifhtml

@ifinfo

Begin a stretch of text that will be ignored by TeX when it typesets
the printed manual.  The text appears only in the HTML resp. Info
file.  Pair with @end ifhtml resp. @end ifinfo.
See section Conditionally Visible Text.

@ifnothtml

@ifnotinfo

@ifnottex

Begin a stretch of text that will be ignored in one output format but
not the others.  The text appears only in the format not specified.
Pair with @end ifnothtml resp. @end ifnotinfo resp.
@end ifnotinfo.  See section Conditionally Visible Text.

@ifset flag

If flag is set, the Texinfo formatting commands format text
between @ifset flag and the following @end ifset
command.
See section @set, @clear, and @value.

@iftex

Begin a stretch of text that will not appear in the Info file, but
will be processed only by TeX.  Pair with @end iftex.
See section Conditionally Visible Text.

@ignore

Begin a stretch of text that will not appear in either the Info file
or the printed output.  Pair with @end ignore.
See section Comments.

@image{filename, [width], [height]}

Include graphics image in external filename scaled to the given
width and/or height.  See section Inserting Images.

@include filename

Incorporate the contents of the file filename into the Info file
or printed document.  See section Include Files.

@inforef{node-name, [entry-name], info-file-name}

Make a cross reference to an Info file for which there is no printed
manual.  See section @inforef.

\input macro-definitions-file

Use the specified macro definitions file.  This command is used only
in the first line of a Texinfo file to cause TeX to make use of the
`texinfo' macro definitions file.  The backslash in \input
is used instead of an @ because TeX does not
recognize @ until after it has read the definitions file.
See section The Texinfo File Header.

@item

Indicate the beginning of a marked paragraph for @itemize and
@enumerate; indicate the beginning of the text of a first column
entry for @table, @ftable, and @vtable.
See section Lists and Tables.

@itemize  mark-generating-character-or-command

Produce a sequence of indented paragraphs, with a mark inside the left
margin at the beginning of each paragraph.  Pair with @end
itemize.  See section Making an Itemized List.

@itemx

Like @item but do not generate extra vertical space above the
item text.  See section @itemx.

@kbd{keyboard-characters}

Indicate text that is characters of input to be typed by
users.  See section @kbd{keyboard-characters}.

@kbdinputstyle style

Specify when @kbd should use a font distinct from @code.
See section @kbd{keyboard-characters}.

@key{key-name}

Indicate a name for a key on a keyboard.
See section @key{key-name}.

@kindex entry

Add entry to the index of keys.
See section Making Index Entries.

@L{}

@l{}

Generate the uppercase and lowercase Polish suppressed-L letters,
respectively: L/, l/.

@lisp

Begin an example of Lisp code.  Indent text, do not fill, and select
fixed-width font.  Pair with @end lisp.  See section @lisp.

@lowersections

Change subsequent chapters to sections, sections to subsections, and so
on. See section @raisesections and @lowersections.

@macro macro-name {params}

Define a new Texinfo command @macro-name{params}.
Only supported by makeinfo and texi2dvi.  See section Defining Macros.

@majorheading title

Print a chapter-like heading in the text, but not in the table of
contents of a printed manual.  Generate more vertical whitespace before
the heading than the @chapheading command.  In Info, the chapter
heading line is underlined with asterisks.  See section @majorheading, @chapheading.

@math{mathematical-expression}

Format a mathematical expression.
See section @math: Inserting Mathematical Expressions.

@menu

Mark the beginning of a menu of nodes in Info.  No effect in a printed
manual.  Pair with @end menu.  See section Menus.

@minus{}

Generate a minus sign, `-'.  See section @minus{} (-): Inserting a Minus Sign.

@multitable column-width-spec

Begin a multi-column table.  Pair with @end multitable.
See section Multitable Column Widths.

@need n

Start a new page in a printed manual if fewer than n mils
(thousandths of an inch) remain on the current page.  See section @need mils: Prevent Page Breaks.

@node name, next, previous, up

Define the beginning of a new node in Info, and serve as a locator for
references for TeX.  See section The @node Command.

@noindent

Prevent text from being indented as if it were a new paragraph.
See section @noindent.

@O{}

@o{}

Generate the uppercase and lowercase O-with-slash letters, respectively:
Ø, ø.

@oddfooting [left] @| [center] @| [right]

@oddheading [left] @| [center] @| [right]

Specify page footings resp. headings for odd-numbered (right-hand)
pages.  Only allowed inside @iftex.  See section How to Make Your Own Headings.

@OE{}

@oe{}

Generate the uppercase and lowercase OE ligatures, respectively:
OE, oe.  See section Inserting Accents.

@page

Start a new page in a printed manual.  No effect in Info.
See section @page: Start a New Page.

@paragraphindent indent

Indent paragraphs by indent number of spaces; delete indentation
if the value of indent is 0; and do not change indentation if
indent is asis. See section Paragraph Indenting.

@pindex entry

Add entry to the index of programs.  See section Making Index Entries.

@point{}

Indicate the position of point in a buffer to the reader with a
glyph: `-!-'.  See section @point{} (-!-): Indicating Point in a Buffer.

@pounds{}

Generate the pounds sterling currency sign.
See section @pounds{} (£): Pounds Sterling.

@print{}

Indicate printed output to the reader with a glyph:
`-|'.  See section @print{} (-|): Indicating Printed Output.

@printindex index-name

Print an alphabetized two-column index in a printed manual or generate
an alphabetized menu of index entries for Info.  See section Index Menus and Printing an Index.

@pxref{node-name, [entry], [topic-or-title], [info-file], [manual]}

Make a reference that starts with a lower case `see' in a printed
manual.  Use within parentheses only.  Do not follow command with a
punctuation mark--the Info formatting commands automatically insert
terminating punctuation as needed.  Only the first argument is mandatory.
See section @pxref.

@questiondown{}

Generate an upside-down question mark.  See section Inserting Accents.

@quotation

Narrow the margins to indicate text that is quoted from another real
or imaginary work.  Write command on a line of its own.  Pair with
@end quotation.  See section @quotation.

@r{text}

Print text in roman font.  No effect in Info.
See section Fonts for Printing, Not Info.

@raisesections

Change subsequent sections to chapters, subsections to sections, and so
on.  See section @raisesections and @lowersections.

@ref{node-name, [entry], [topic-or-title], [info-file], [manual]}

Make a reference.  In a printed manual, the reference does not start
with a `See'.  Follow command with a punctuation mark.  Only the first
argument is mandatory.  See section @ref.

@refill

In Info, refill and indent the paragraph after all the other processing
has been done.  No effect on TeX, which always refills.  This command
is no longer needed, since all formatters now automatically refill.
See section Refilling Paragraphs.

@result{}

Indicate the result of an expression to the reader with a special
glyph: `=>'.  See section @result{} (=>): Indicating Evaluation.

@ringaccent{c}

Generate a ring accent over the next character, as in @ringaccent{o}.
See section Inserting Accents.

@samp{text}

Highlight text that is a literal example of a sequence of
characters.  Used for single characters, for statements, and often for
entire shell commands.  See section @samp{text}.

@sc{text}

Set text in a printed output in THE SMALL CAPS FONT and
set text in the Info file in uppercase letters.
See section @sc{text}: The Small Caps Font.

@section title

Begin a section within a chapter.  In a printed manual, the section
title is numbered and appears in the table of contents.  In Info, the
title is underlined with equal signs.  See section @section.

@set flag [string]

Make flag active, causing the Texinfo formatting commands to
format text between subsequent pairs of @ifset flag and
@end ifset commands.  Optionally, set value of flag to
string.
See section @set, @clear, and @value.

@setchapternewpage on-off-odd

Specify whether chapters start on new pages, and if so, whether on
odd-numbered (right-hand) new pages.  See section @setchapternewpage.

@setfilename info-file-name

Provide a name to be used by the Info file.  This command is essential
for TeX formatting as well, even though it produces no output.
See section @setfilename.

@settitle title

Provide a title for page headers in a printed manual.
See section @settitle.

@shortcontents

Print a short table of contents.  Not relevant to Info, which uses
menus rather than tables of contents.  A synonym for
@summarycontents.  See section Generating a Table of Contents.

@shorttitlepage{title}

Generate a minimal title page.  See section @titlepage.

@smallbook

Cause TeX to produce a printed manual in a 7 by 9.25 inch format
rather than the regular 8.5 by 11 inch format.  See section Printing "Small" Books.  Also, see section @smallexample and @smalllisp.

@smallexample

Indent text to indicate an example.  Do not fill, select fixed-width
font.  In @smallbook format, print text in a smaller font than
with @example.  Pair with @end smallexample.
See section @smallexample and @smalllisp.

@smalllisp

Begin an example of Lisp code.  Indent text, do not fill, select
fixed-width font.  In @smallbook format, print text in a
smaller font.  Pair with @end smalllisp.  See section @smallexample and @smalllisp.

@sp n

Skip n blank lines.  See section @sp n: Insert Blank Lines.

@ss{}

Generate the German sharp-S es-zet letter, ß.  See section Inserting Accents.

@strong text

Emphasize text by typesetting it in a bold font for the
printed manual and by surrounding it with asterisks for Info.
See section @emph{text} and @strong{text}.

@subheading title

Print an unnumbered subsection-like heading in the text, but not in
the table of contents of a printed manual.  In Info, the title is
underlined with hyphens.  See section The @subsection-like Commands.

@subsection title

Begin a subsection within a section.  In a printed manual, the
subsection title is numbered and appears in the table of contents.  In
Info, the title is underlined with hyphens.  See section The @subsection Command.

@subsubheading title

Print an unnumbered subsubsection-like heading in the text, but not in
the table of contents of a printed manual.  In Info, the title is
underlined with periods.  See section The `subsub' Commands.

@subsubsection title

Begin a subsubsection within a subsection.  In a printed manual,
the subsubsection title is numbered and appears in the table of
contents.  In Info, the title is underlined with periods.
See section The `subsub' Commands.

@subtitle title

In a printed manual, set a subtitle in a normal sized font flush to
the right-hand side of the page.  Not relevant to Info, which does not
have title pages.  See section @title, @subtitle, and @author.

@summarycontents

Print a short table of contents.  Not relevant to Info, which uses
menus rather than tables of contents.  A synonym for
@shortcontents.  See section Generating a Table of Contents.

@syncodeindex from-index into-index

Merge the index named in the first argument into the index named in
the second argument, printing the entries from the first index in
@code font.  See section Combining Indices.

@synindex from-index into-index

Merge the index named in the first argument into the index named in
the second argument.  Do not change the font of from-index
entries.  See section Combining Indices.

@t{text}

Print text in a fixed-width, typewriter-like font.
No effect in Info.  See section Fonts for Printing, Not Info.

@tab

Separate columns in a multitable.  See section Multitable Rows.

@table formatting-command

Begin a two-column table, using @item for each entry.  Write
each first column entry on the same line as @item.  First
column entries are printed in the font resulting from
formatting-command.  Pair with @end table.
See section Making a Two-column Table.
Also see section @ftable and @vtable,
and section @itemx.

@TeX{}

Insert the logo TeX.  See section Inserting TeX and the Copyright Symbol.

@tex

Enter TeX completely.  Pair with @end tex.  See section Raw Formatter Commands.

@thischapter

@thischaptername

@thisfile

@thispage

@thistitle

Only allowed in a heading or footing.  Stands for the number and name of
the current chapter (in the format `Chapter 1: Title'), the chapter name
only, the filename, the current page number, and the title of the
document, respectively.  See section How to Make Your Own Headings.

@tieaccent{cc}

Generate a tie-after accent over the next two characters cc, as in
`@tieaccent{oo}'.  See section Inserting Accents.

@tindex entry

Add entry to the index of data types.  See section Making Index Entries.

@title title

In a printed manual, set a title flush to the left-hand side of the
page in a larger than normal font and underline it with a black rule.
Not relevant to Info, which does not have title pages.  See section @title, @subtitle, and @author.

@titlefont{text}

In a printed manual, print text in a larger than normal font.
Not relevant to Info, which does not have title pages.
See section @titlefont, @center, and @sp.

@titlepage

Indicate to Texinfo the beginning of the title page.  Write command on
a line of its own.  Pair with @end titlepage.  Nothing between
@titlepage and @end titlepage appears in Info.
See section @titlepage.

@today{}

Insert the current date, in `1 Jan 1900' style.  See section How to Make Your Own Headings.

@top title

In a Texinfo file to be formatted with makeinfo, identify the
topmost @node line in the file, which must be written on the line
immediately preceding the @top command.  Used for
makeinfo's node pointer insertion feature.  The title is
underlined with asterisks.  Both the @node line and the @top
line normally should be enclosed by @ifinfo and @end
ifinfo.  In TeX and texinfo-format-buffer, the @top
command is merely a synonym for @unnumbered.  See section Creating Pointers with makeinfo.

@u{c}

@ubaraccent{c}

@udotaccent{c}

Generate a breve, underbar, or underdot accent, respectively, over or
under the character c, as in @u{o}, @ubaraccent{o},
@udotaccent{o}.  See section Inserting Accents.

@unnumbered title

In a printed manual, begin a chapter that appears without chapter
numbers of any kind.  The title appears in the table of contents of a
printed manual.  In Info, the title is underlined with asterisks.
See section @unnumbered, @appendix.

@unnumberedsec title

In a printed manual, begin a section that appears without section
numbers of any kind.  The title appears in the table of contents of a
printed manual.  In Info, the title is underlined with equal signs.
See section @unnumberedsec, @appendixsec, @heading.

@unnumberedsubsec title

In a printed manual, begin an unnumbered subsection within a
chapter.  The title appears in the table of contents of a printed
manual.  In Info, the title is underlined with hyphens.
See section The @subsection-like Commands.

@unnumberedsubsubsec title

In a printed manual, begin an unnumbered subsubsection within a
chapter.  The title appears in the table of contents of a printed
manual.  In Info, the title is underlined with periods.
See section The `subsub' Commands.

@uref{url[, displayed-text}

Define a cross reference to an external uniform resource locator for the
World Wide Web.  See section @url{uniform-resource-locator}.

@url{url}

Indicate text that is a uniform resource locator for the World Wide
Web.  See section @url{uniform-resource-locator}.

@v{c}

Generate check accent over the character c, as in @v{o}.
See section Inserting Accents.

@value{flag}

Replace flag with the value to which it is set by @set
flag.
See section @set, @clear, and @value.

@var{metasyntactic-variable}

Highlight a metasyntactic variable, which is something that stands for
another piece of text.  See section @var{metasyntactic-variable}.

@vindex entry

Add entry to the index of variables.  See section Making Index Entries.

@vskip amount

In a printed manual, insert whitespace so as to push text on the
remainder of the page towards the bottom of the page.  Used in
formatting the copyright page with the argument `0pt plus
1filll'.  (Note spelling of `filll'.)  @vskip may be used
only in contexts ignored for Info.  See section Copyright Page and Permissions.

@vtable formatting-command

Begin a two-column table, using @item for each entry.
Automatically enter each of the items in the first column into the
index of variables.  Pair with @end vtable.  The same as
@table, except for indexing.  See section @ftable and @vtable.

@w{text}

Prevent text from being split across two lines.  Do not end a
paragraph that uses @w with an @refill command.
See section @w{text}: Prevent Line Breaks.

@xref{node-name, [entry], [topic-or-title], [info-file], [manual]}

Make a reference that starts with `See' in a printed manual.  Follow
command with a punctuation mark.  Only the first argument is
mandatory.  See section @xref.

Tips and Hints

Here are some tips for writing Texinfo documentation:

  •

Write in the present tense, not in the past or the future.

  •

Write actively!  For example, write "We recommend that ..." rather
than "It is recommended that ...".

  •

Use 70 or 72 as your fill column.  Longer lines are hard to read.

  •

Include a copyright notice and copying permissions.

Index, Index, Index!

Write many index entries, in different ways.
Readers like indices; they are helpful and convenient.

Although it is easiest to write index entries as you write the body of
the text, some people prefer to write entries afterwards.  In either
case, write an entry before the paragraph to which it applies.  This
way, an index entry points to the first page of a paragraph that is
split across pages.

Here are more hints we have found valuable:

  •

Write each index entry differently, so each entry refers to a different
place in the document.

  •

Write index entries only where a topic is discussed significantly.  For
example, it is not useful to index "debugging information" in a
chapter on reporting bugs.  Someone who wants to know about debugging
information will certainly not find it in that chapter.

  •

Consistently capitalize the first word of every concept index entry,
or else consistently use lower case.  Terse entries often call for
lower case; longer entries for capitalization.  Whichever case
convention you use, please use one or the other consistently!  Mixing
the two styles looks bad.

  •

Always capitalize or use upper case for those words in an index for
which this is proper, such as names of countries or acronyms.  Always
use the appropriate case for case-sensitive names, such as those in C or
Lisp.

  •

Write the indexing commands that refer to a whole section immediately
after the section command, and write the indexing commands that refer to
the paragraph before the paragraph.

In the example that follows, a blank line comes after the index
entry for "Leaping":

    @section The Dog and the Fox
@cindex Jumping, in general
@cindex Leaping

@cindex Dog, lazy, jumped over
@cindex Lazy dog jumped over
@cindex Fox, jumps over dog
@cindex Quick fox jumps over dog
The quick brown fox jumps over the lazy dog.

(Note that the example shows entries for the same concept that are
written in different ways---`Lazy dog', and `Dog, lazy'---so
readers can look up the concept in different ways.)

Blank Lines

  •

Insert a blank line between a sectioning command and the first following
sentence or paragraph, or between the indexing commands associated with
the sectioning command and the first following sentence or paragraph, as
shown in the tip on indexing.  Otherwise, a formatter may fold title and
paragraph together.

  •

Always insert a blank line before an @table command and after an
@end table command; but never insert a blank line after an
@table command or before an @end table command.

For example,

    Types of fox:

@table @samp
@item Quick
Jump over lazy dogs.

@item Brown
Also jump over lazy dogs.
@end table

@noindent
On the other hand, ...

Insert blank lines before and after @itemize ... @end
itemize and @enumerate ... @end enumerate in the
same way.

Complete Phrases

Complete phrases are easier to read than ...

  •

Write entries in an itemized list as complete sentences; or at least, as
complete phrases.  Incomplete expressions ... awkward ... like
this.

  •

Write the prefatory sentence or phrase for a multi-item list or table as
a complete expression.  Do not write "You can set:"; instead, write
"You can set these variables:".  The former expression sounds cut off.

Editions, Dates and Versions

Write the edition and version numbers and date in three places in every
manual:

  1.

In the first @ifinfo section, for people reading the Texinfo file.

  2.

In the @titlepage section, for people reading the printed manual.

  3.

In the `Top' node, for people reading the Info file.

Also, it helps to write a note before the first @ifinfo
section to explain what you are doing.

For example:

@c ===> NOTE! <==
@c Specify the edition and version numbers and date
@c in *three* places:
@c   1. First ifinfo section  2. title page  3. top node
@c To find the locations, search for !!set

@ifinfo
@c !!set edition, date, version
This is Edition 4.03, January 1992,
of the @cite{GDB Manual} for GDB Version 4.3.
...

---or use @set and @value
(see section @value Example).

Definition Commands

Definition commands are @deffn, @defun,
@defmac, and the like, and enable you to write descriptions in
a uniform format.

  •

Write just one definition command for each entity you define with a
definition command.  The automatic indexing feature creates an index
entry that leads the reader to the definition.

  •

Use @table ... @end table in an appendix that
contains a summary of functions, not @deffn or other definition
commands.

Capitalization

  •

Capitalize "Texinfo"; it is a name.  Do not write the `x' or
`i' in upper case.

  •

Capitalize "Info"; it is a name.

  •

Write TeX using the @TeX{} command.  Note the uppercase
`T' and `X'.  This command causes the formatters to
typeset the name according to the wishes of Donald Knuth, who wrote
TeX.

Spaces

Do not use spaces to format a Texinfo file, except inside of
@example ... @end example and similar commands.

For example, TeX fills the following:

    @kbd{C-x v}
    @kbd{M-x vc-next-action}
       Perform the next logical operation
       on the version-controlled file
       corresponding to the current buffer.

so it looks like this:

    C-x v
    M-x vc-next-action
       Perform the next logical operation on the version-controlled file
       corresponding to the current buffer.

In this case, the text should be formatted with
@table, @item, and @itemx, to create a table.

@code, @samp, @var, and `---'

  •

Use @code around Lisp symbols, including command names.
For example,

    The main function is @code{vc-next-action}, ...

  •

Avoid putting letters such as `s' immediately after an
`@code'.  Such letters look bad.

  •

Use @var around meta-variables.  Do not write angle brackets
around them.

  •

Use three hyphens in a row, `---', to indicate a long dash.  TeX
typesets these as a long dash and the Info formatters reduce three
hyphens to two.

Periods Outside of Quotes

Place periods and other punctuation marks outside of quotations,
unless the punctuation is part of the quotation.  This practice goes
against publishing conventions in the United States, but enables the
reader to distinguish between the contents of the quotation and the
whole passage.

For example, you should write the following sentence with the period
outside the end quotation marks:

Evidently, `au' is an abbreviation for "author".

since `au' does not serve as an  abbreviation for
`author.' (with a period following the word).

Introducing New Terms

  •

Introduce new terms so that a reader who does not know them can
understand them from context; or write a definition for the term.

For example, in the following, the terms "check in", "register" and
"delta" are all appearing for the first time; the example sentence should be
rewritten so they are understandable.

The major function assists you in checking in a file to your
version control system and registering successive sets of changes to
it as deltas.

  •

Use the @dfn command around a word being introduced, to indicate
that the reader should not expect to know the meaning already, and
should expect to learn the meaning from this passage.

@pxref

Absolutely never use @pxref except in the special context for
which it is designed: inside parentheses, with the closing parenthesis
following immediately after the closing brace.  One formatter
automatically inserts closing punctuation and the other does not.  This
means that the output looks right both in printed output and in an Info
file, but only when the command is used inside parentheses.

Invoking from a Shell

You can invoke programs such as Emacs, GCC, and gawk from a
shell.  The documentation for each program should contain a section that
describes this.  Unfortunately, if the node names and titles for these
sections are all different, readers find it hard to search for the
section.

Name such sections with a phrase beginning with the word
`Invoking ...', as in `Invoking Emacs'; this way
users can find the section easily.

ANSI C Syntax

When you use @example to describe a C function's calling
conventions, use the ANSI C syntax, like this:

void dld_init (char *@var{path});

And in the subsequent discussion, refer to the argument values by
writing the same argument names, again highlighted with
@var.

Avoid the obsolete style that looks like this:

#include <dld.h>

dld_init (path)
char *path;

Also, it is best to avoid writing #include above the
declaration just to indicate that the function is declared in a
header file.  The practice may give the misimpression that the
#include belongs near the declaration of the function.  Either
state explicitly which header file holds the declaration or, better
yet, name the header file used for a group of functions at the
beginning of the section that describes the functions.

Bad Examples

Here are several examples of bad writing to avoid:

In this example, say, " ... you must @dfn{check
in} the new version."  That flows better.

When you are done editing the file, you must perform a
@dfn{check in}.

In the following example, say, "... makes a unified interface such as VC
mode possible."

SCCS, RCS and other version-control systems all perform similar
functions in broadly similar ways (it is this resemblance which makes
a unified control mode like this possible).

And in this example, you should specify what `it' refers to:

If you are working with other people, it assists in coordinating
everyone's changes so they do not step on each other.

And Finally ...

  •

Pronounce TeX as if the `X' were a Greek `chi', as the last
sound in the name `Bach'.  But pronounce Texinfo as in `speck':
"teckinfo".

  •

Write notes for yourself at the very end of a Texinfo file after the
@bye.  None of the formatters process text after the
@bye; it is as if the text were within @ignore ...
@end ignore.

A Sample Texinfo File

Here is a complete, short sample Texinfo file, without any commentary.
You can see this file, with comments, in the first chapter.
See section A Short Sample Texinfo File.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header

@setchapternewpage odd

@ifinfo
This is a short example of a complete Texinfo file.

Copyright 1990 Free Software Foundation, Inc.
@end ifinfo

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

@node    Top,       First Chapter,         , (dir)
@comment node-name, next,          previous, up

@menu
* First Chapter::    The first chapter is the
                     only chapter in this sample.
* Concept Index::    This index has two entries.
@end menu

@node    First Chapter, Concept Index, Top,      Top
@comment node-name,     next,          previous, up
@chapter First Chapter
@cindex Sample index entry

This is the contents of the first chapter.
@cindex Another sample index entry

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @code{makeinfo} and @code{texinfo-format-buffer}
commands transform a Texinfo file such as this into
an Info file; and @TeX{} typesets it for a printed
manual.

@node    Concept Index,    ,  First Chapter, Top
@comment node-name,    next,  previous,      up
@unnumbered Concept Index

@printindex cp

@contents
@bye

Sample Permissions

Texinfo files should contain sections that tell the readers that they
have the right to copy and distribute the Texinfo file, the Info file,
and the printed manual.

Also, if you are writing a manual about software, you should explain
that the software is free and either include the GNU General Public
License (GPL) or provide a reference to it.  See section `Distribution' in The GNU Emacs Manual, for an example of the text
that could be used in the software "Distribution", "General Public
License", and "NO WARRANTY" sections of a document.  See section Texinfo Copying Conditions, for an example of a brief explanation
of how the copying conditions provide you with rights.

  • ifinfo Permissions: Sample `ifinfo' copying permissions.

  • Titlepage Permissions: Sample Titlepage copying permissions.

In a Texinfo file, the first @ifinfo section usually begins
with a line that says what the file documents.  This is what a person
reading the unprocessed Texinfo file or using the advanced Info
command g * sees first.  See Info file `info', node `Expert', for more information. (A reader using the regular
Info commands usually starts reading at the first node and skips
this first section, which is not in a node.)

In the @ifinfo section, the summary sentence is followed by a
copyright notice and then by the copying permission notice.  One of
the copying permission paragraphs is enclosed in @ignore and
@end ignore commands.  This paragraph states that the Texinfo
file can be processed through TeX and printed, provided the printed
manual carries the proper copying permission notice.  This paragraph
is not made part of the Info file since it is not relevant to the Info
file; but it is a mandatory part of the Texinfo file since it permits
people to process the Texinfo file in TeX and print the
results.

In the printed manual, the Free Software Foundation copying permission
notice follows the copyright notice and publishing information and is
located within the region delineated by the @titlepage and
@end titlepage commands.  The copying permission notice is exactly
the same as the notice in the @ifinfo section except that the
paragraph enclosed in @ignore and @end ignore commands is
not part of the notice.

To make it simple to insert a permission notice into each section of
the Texinfo file, sample permission notices for each section are
reproduced in full below.

Note that you may need to specify the correct name of a section
mentioned in the permission notice.  For example, in The GDB
Manual, the name of the section referring to the General Public
License is called the "GDB General Public License", but in the
sample shown below, that section is referred to generically as the
"GNU General Public License".  If the Texinfo file does not carry a
copy of the General Public License, leave out the reference to it, but
be sure to include the rest of the sentence.

`ifinfo' Copying Permissions

In the @ifinfo section of a Texinfo file, the standard Free
Software Foundation permission notice reads as follows:

This file documents ...

Copyright 1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Titlepage Copying Permissions

In the @titlepage section of a Texinfo file, the standard Free
Software Foundation copying permission notice follows the copyright
notice and publishing information.  The standard phrasing is as
follows:

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Include Files

When TeX or an Info formatting command sees an @include
command in a Texinfo file, it processes the contents of the file named
by the command and incorporates them into the DVI or Info file being
created.  Index entries from the included file are incorporated into
the indices of the output file.

Include files let you keep a single large document as a collection of
conveniently small parts.

  • Using Include Files: How to use the @include command.

  • texinfo-multiple-files-update: How to create and update nodes and
                                  menus when using included files.

  • Include File Requirements: What texinfo-multiple-files-update expects.

  • Sample Include File: A sample outer file with included files
                                  within it; and a sample included file.

  • Include Files Evolution: How use of the @include command
                                  has changed over time.

How to Use Include Files

To include another file within a Texinfo file, write the
@include command at the beginning of a line and follow it on
the same line by the name of a file to be included.  For
example:

@include buffers.texi

An included file should simply be a segment of text that you expect to
be included as is into the overall or outer Texinfo file; it
should not contain the standard beginning and end parts of a Texinfo
file.  In particular, you should not start an included file with a
line saying `\input texinfo'; if you do, that phrase is inserted
into the output file as is.  Likewise, you should not end an included
file with an @bye command; nothing after @bye is
formatted.

In the past, you were required to write an @setfilename line at the
beginning of an included file, but no longer.  Now, it does not matter
whether you write such a line.  If an @setfilename line exists
in an included file, it is ignored.

Conventionally, an included file begins with an @node line that
is followed by an @chapter line.  Each included file is one
chapter.  This makes it easy to use the regular node and menu creating
and updating commands to create the node pointers and menus within the
included file.  However, the simple Emacs node and menu creating and
updating commands do not work with multiple Texinfo files.  Thus you
cannot use these commands to fill in the `Next', `Previous', and `Up'
pointers of the @node line that begins the included file.  Also,
you cannot use the regular commands to create a master menu for the
whole file.  Either you must insert the menus and the `Next',
`Previous', and `Up' pointers by hand, or you must use the GNU Emacs
Texinfo mode command, texinfo-multiple-files-update, that is
designed for @include files.

texinfo-multiple-files-update

GNU Emacs Texinfo mode provides the texinfo-multiple-files-update
command.  This command creates or updates `Next', `Previous', and `Up'
pointers of included files as well as those in the outer or overall
Texinfo file, and it creates or updates a main menu in the outer file.
Depending whether you call it with optional arguments, the command
updates only the pointers in the first @node line of the
included files or all of them:

M-x texinfo-multiple-files-update

Called without any arguments:

  •

Create or update the `Next', `Previous', and `Up' pointers of the
first @node line in each file included in an outer or overall
Texinfo file.

  •

Create or update the `Top' level node pointers of the outer or
overall file.

  •

Create or update a main menu in the outer file.

C-u M-x texinfo-multiple-files-update

Called with C-u as a prefix argument:

  •

Create or update pointers in the first @node line in each
included file.

  •

Create or update the `Top' level node pointers of the outer file.

  •

Create and insert a master menu in the outer file.  The master menu
is made from all the menus in all the included files.

C-u 8 M-x texinfo-multiple-files-update

Called with a numeric prefix argument, such as C-u 8:

  •

Create or update all the `Next', `Previous', and `Up' pointers
of all the included files.

  •

Create or update all the menus of all the included
files.

  •

Create or update the `Top' level node pointers of the outer or
overall file.

  •

And then create a master menu in the outer file.  This is similar to
invoking texinfo-master-menu with an argument when you are
working with just one file.

Note the use of the prefix argument in interactive use: with a regular
prefix argument, just C-u, the
texinfo-multiple-files-update command inserts a master menu;
with a numeric prefix argument, such as C-u 8, the command
updates every pointer and menu in all the files and then inserts a
master menu.

Include File Requirements

If you plan to use the texinfo-multiple-files-update command,
the outer Texinfo file that lists included files within it should
contain nothing but the beginning and end parts of a Texinfo file, and
a number of @include commands listing the included files.  It
should not even include indices, which should be listed in an included
file of their own.

Moreover, each of the included files must contain exactly one highest
level node (conventionally, @chapter or equivalent),
and this node must be the first node in the included file.
Furthermore, each of these highest level nodes in each included file
must be at the same hierarchical level in the file structure.
Usually, each is an @chapter, an @appendix, or an
@unnumbered node.  Thus, normally, each included file contains
one, and only one, chapter or equivalent-level node.

The outer file should contain only one node, the `Top' node.  It
should not contain any nodes besides the single `Top' node.  The
texinfo-multiple-files-update command will not process
them.

Sample File with @include

Here is an example of a complete outer Texinfo file with @include files
within it before running texinfo-multiple-files-update, which
would insert a main or master menu:

\input texinfo @c -*-texinfo-*-
@setfilename  include-example.info
@settitle Include Example

@setchapternewpage odd
@titlepage
@sp 12
@center @titlefont{Include Example}
@sp 2
@center by Whom Ever

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998 Free Software Foundation, Inc.
@end titlepage

@ifinfo
@node Top, First, , (dir)
@top Master Menu
@end ifinfo

@include foo.texinfo
@include bar.texinfo
@include concept-index.texinfo

@summarycontents
@contents

@bye

An included file, such as `foo.texinfo', might look like
this:

@node First, Second, , Top
@chapter First Chapter

Contents of first chapter ...

The full contents of `concept-index.texinfo' might be as simple as this:

@node Concept Index, , Second, Top
@unnumbered Concept Index

@printindex cp

The outer Texinfo source file for The GNU Emacs Lisp Reference
Manual is named `elisp.texi'.  This outer file contains a master
menu with 417 entries and a list of 41 @include
files.

Evolution of Include Files

When Info was first created, it was customary to create many small
Info files on one subject.  Each Info file was formatted from its own
Texinfo source file.  This custom meant that Emacs did not need to
make a large buffer to hold the whole of a large Info file when
someone wanted information; instead, Emacs allocated just enough
memory for the small Info file that contained the particular
information sought.  This way, Emacs could avoid wasting memory.

References from one file to another were made by referring to the file
name as well as the node name. (See section Referring to Other Info Files.  Also, see section @xref with Four and Five Arguments.)

Include files were designed primarily as a way to create a single,
large printed manual out of several smaller Info files.  In a printed
manual, all the references were within the same document, so TeX
could automatically determine the references' page numbers.  The Info
formatting commands used include files only for creating joint
indices; each of the individual Texinfo files had to be formatted for
Info individually.  (Each, therefore, required its own
@setfilename line.)

However, because large Info files are now split automatically, it is
no longer necessary to keep them small.

Nowadays, multiple Texinfo files are used mostly for large documents,
such as The GNU Emacs Lisp Reference Manual, and for projects
in which several different people write different sections of a
document simultaneously.

In addition, the Info formatting commands have been extended to work
with the @include command so as to create a single large Info
file that is split into smaller files if necessary.  This means that
you can write menus and cross references without naming the different
Texinfo files.

Page Headings

Most printed manuals contain headings along the top of every page
except the title and copyright pages.  Some manuals also contain
footings.  (Headings and footings have no meaning to Info, which is
not paginated.)

  • Heading Format: Standard page heading formats.

  • Heading Choice: How to specify the type of page heading.

  • Custom Headings: How to create your own headings and footings.

Texinfo provides standard page heading formats for manuals that are
printed on one side of each sheet of paper and for manuals that are
printed on both sides of the paper.  Typically, you will use these
formats, but you can specify your own format if you wish.

In addition, you can specify whether chapters should begin on a new
page, or merely continue the same page as the previous chapter; and if
chapters begin on new pages, you can specify whether they must be
odd-numbered pages.

By convention, a book is printed on both sides of each sheet of paper.
When you open a book, the right-hand page is odd-numbered, and
chapters begin on right-hand pages--a preceding left-hand page is
left blank if necessary.  Reports, however, are often printed on just
one side of paper, and chapters begin on a fresh page immediately
following the end of the preceding chapter.  In short or informal
reports, chapters often do not begin on a new page at all, but are
separated from the preceding text by a small amount of whitespace.

The @setchapternewpage command controls whether chapters begin
on new pages, and whether one of the standard heading formats is used.
In addition, Texinfo has several heading and footing commands that you
can use to generate your own heading and footing formats.

In Texinfo, headings and footings are single lines at the tops and
bottoms of pages; you cannot create multiline headings or footings.
Each header or footer line is divided into three parts: a left part, a
middle part, and a right part.  Any part, or a whole line, may be left
blank.  Text for the left part of a header or footer line is set
flushleft; text for the middle part is centered; and, text for the
right part is set flushright.

Standard Heading Formats

Texinfo provides two standard heading formats, one for manuals printed
on one side of each sheet of paper, and the other for manuals printed
on both sides of the paper.

By default, nothing is specified for the footing of a Texinfo file,
so the footing remains blank.

The standard format for single-sided printing consists of a header
line in which the left-hand part contains the name of the chapter, the
central part is blank, and the right-hand part contains the page
number.

A single-sided page looks like this:

   _______________________
  |                       |
  | chapter   page number |
  |                       |
  | Start of text ...     |
  | ...                   |
  |                       |

The standard format for two-sided printing depends on whether the page
number is even or odd.  By convention, even-numbered pages are on the
left- and odd-numbered pages are on the right.  (TeX will adjust the
widths of the left- and right-hand margins.  Usually, widths are
correct, but during double-sided printing, it is wise to check that
pages will bind properly--sometimes a printer will produce output in
which the even-numbered pages have a larger right-hand margin than the
odd-numbered pages.)

In the standard double-sided format, the left part of the left-hand
(even-numbered) page contains the page number, the central part is
blank, and the right part contains the title (specified by the
@settitle command).  The left part of the right-hand
(odd-numbered) page contains the name of the chapter, the central part
is blank, and the right part contains the page number.

Two pages, side by side as in an open book, look like this:

   _______________________     _______________________
  |                       |   |                       |
  | page number     title |   | chapter   page number |
  |                       |   |                       |
  | Start of text ...     |   | More  text ...        |
  | ...                   |   | ...                   |
  |                       |   |                       |

The chapter name is preceded by the word "Chapter", the chapter number
and a colon.  This makes it easier to keep track of where you are in the
manual.

Specifying the Type of Heading

TeX does not begin to generate page headings for a standard Texinfo
file until it reaches the @end titlepage command.  Thus, the
title and copyright pages are not numbered.  The @end
titlepage command causes TeX to begin to generate page headings
according to a standard format specified by the
@setchapternewpage command that precedes the
@titlepage section.

There are four possibilities:

No @setchapternewpage command

Cause TeX to specify the single-sided heading format, with chapters
on new pages. This is the same as @setchapternewpage on.

@setchapternewpage on

Specify the single-sided heading format, with chapters on new pages.

@setchapternewpage off

Cause TeX to start a new chapter on the same page as the last page of
the preceding chapter, after skipping some vertical whitespace.  Also
cause TeX to typeset for single-sided printing.  (You can override
the headers format with the @headings double command; see
section The @headings Command.)

@setchapternewpage odd

Specify the double-sided heading format, with chapters on new pages.

Texinfo lacks an @setchapternewpage even command.

How to Make Your Own Headings

You can use the standard headings provided with Texinfo or specify
your own.  By default, Texinfo has no footers, so if you specify them,
the available page size for the main text will be slightly reduced.

Texinfo provides six commands for specifying headings and
footings.  The @everyheading command and
@everyfooting command generate page headers and footers
that are the same for both even- and odd-numbered pages.
The @evenheading command and @evenfooting
command generate headers and footers for even-numbered
(left-hand) pages; and the @oddheading command and
@oddfooting command generate headers and footers for
odd-numbered (right-hand) pages.

Write custom heading specifications in the Texinfo file immediately
after the @end titlepage command.  Enclose your specifications
between @iftex and @end iftex commands since the
texinfo-format-buffer command may not recognize them.  Also,
you must cancel the predefined heading commands with the
@headings off command before defining your own
specifications.

Here is how to tell TeX to place the chapter name at the left, the
page number in the center, and the date at the right of every header
for both even- and odd-numbered pages:

@iftex
@headings off
@everyheading @thischapter @| @thispage @| @today{}
@end iftex

You need to divide the left part from the central part and the central
part from the right part by inserting `@|' between parts.
Otherwise, the specification command will not be able to tell where
the text for one part ends and the next part begins.

Each part can contain text or @-commands.  The text
is printed as if the part were within an ordinary paragraph in the
body of the page.  The @-commands replace
themselves with the page number, date, chapter name, or
whatever.

Here are the six heading and footing commands:

@everyheading left @| center @| right

@everyfooting left @| center @| right

The `every' commands specify the format for both even- and odd-numbered
pages.  These commands are for documents that are printed on one side
of each sheet of paper, or for documents in which you want symmetrical
headers or footers.

@evenheading left @| center @| right

@oddheading  left @| center @| right

@evenfooting left @| center @| right

@oddfooting  left @| center @| right

The `even' and `odd' commands specify the format for even-numbered
pages and odd-numbered pages.  These commands are for books and
manuals that are printed on both sides of each sheet of paper.

Use the `@this...' series of @-commands to
provide the names of chapters
and sections and the page number.  You can use the
`@this...' commands in the left, center, or right portions
of headers and footers, or anywhere else in a Texinfo file so long as
they are between @iftex and @end iftex commands.

Here are the `@this...' commands:

@thispage

Expands to the current page number.

@thischaptername

Expands to the name of the current chapter.

@thischapter

Expands to the number and name of the current
chapter, in the format `Chapter 1: Title'.

@thistitle

Expands to the name of the document, as specified by the
@settitle command.

@thisfile

For @include files only: expands to the name of the current
@include file.  If the current Texinfo source file is not an
@include file, this command has no effect.  This command does
not provide the name of the current Texinfo source file unless
it is an @include file.  (See section Include Files, for more
information about @include files.)

You can also use the @today{} command, which expands to the
current date, in `1 Jan 1900' format.

Other @-commands and text are printed in a header or footer just as
if they were in the body of a page.  It is useful to incorporate text,
particularly when you are writing drafts:

@iftex
@headings off
@everyheading @emph{Draft!} @| @thispage @| @thischapter
@everyfooting @| @| Version: 0.27: @today{}
@end iftex

Beware of overlong titles: they may overlap another part of the
header or footer and blot it out.

Formatting Mistakes

Besides mistakes in the content of your documentation, there
are two kinds of mistake you can make with Texinfo:  you can make mistakes
with @-commands, and you can make mistakes with the structure of the
nodes and chapters.

Emacs has two tools for catching the @-command mistakes and two for
catching structuring mistakes.

For finding problems with @-commands, you can run TeX or a region
formatting command on the region that has a problem; indeed, you can
run these commands on each region as you write it.

For finding problems with the structure of nodes and chapters, you can use
C-c C-s (texinfo-show-structure) and the related occur
command and you can use the M-x Info-validate command.

  • Debugging with Info: How to catch errors with Info formatting.

  • Debugging with TeX: How to catch errors with TeX formatting.

  • Using texinfo-show-structure: How to use texinfo-show-structure.

  • Using occur: How to list all lines containing a pattern.

  • Running Info-Validate: How to find badly referenced nodes.

The makeinfo program does an excellent job of catching errors
and reporting them--far better than texinfo-format-region or
texinfo-format-buffer.  In addition, the various functions for
automatically creating and updating node pointers and menus remove
many opportunities for human error.

If you can, use the updating commands to create and insert pointers
and menus.  These prevent many errors.  Then use makeinfo (or
its Texinfo mode manifestations, makeinfo-region and
makeinfo-buffer) to format your file and check for other
errors.  This is the best way to work with Texinfo.  But if you
cannot use makeinfo, or your problem is very puzzling, then you
may want to use the tools described in this appendix.

Catching Errors with Info Formatting

After you have written part of a Texinfo file, you can use the
texinfo-format-region or the makeinfo-region command to
see whether the region formats properly.

Most likely, however, you are reading this section because for some
reason you cannot use the makeinfo-region command; therefore, the
rest of this section presumes that you are using
texinfo-format-region.

If you have made a mistake with an @-command,
texinfo-format-region will stop processing at or after the
error and display an error message.  To see where in the buffer the
error occurred, switch to the `*Info Region*' buffer; the cursor
will be in a position that is after the location of the error.  Also,
the text will not be formatted after the place where the error
occurred (or more precisely, where it was detected).

For example, if you accidentally end a menu with the command @end
menus with an `s' on the end, instead of with @end menu, you
will see an error message that says:

@end menus is not handled by texinfo

The cursor will stop at the point in the buffer where the error
occurs, or not long after it.  The buffer will look like this:

---------- Buffer: *Info Region* ----------
* Menu:

* Using texinfo-show-structure::  How to use
                                  `texinfo-show-structure'
                                  to catch mistakes.
* Running Info-Validate::         How to check for
                                  unreferenced nodes.
@end menus
-!-
---------- Buffer: *Info Region* ----------

The texinfo-format-region command sometimes provides slightly
odd error messages.  For example, the following cross reference fails to format:

(@xref{Catching Mistakes, for more info.)

In this case, texinfo-format-region detects the missing closing
brace but displays a message that says `Unbalanced parentheses'
rather than `Unbalanced braces'.  This is because the formatting
command looks for mismatches between braces as if they were
parentheses.

Sometimes texinfo-format-region fails to detect mistakes.  For
example, in the following, the closing brace is swapped with the
closing parenthesis:

(@xref{Catching Mistakes), for more info.}

Formatting produces:

(*Note for more info.: Catching Mistakes)

The only way for you to detect this error is to realize that the
reference should have looked like this:

(*Note Catching Mistakes::, for more info.)

Incidentally, if you are reading this node in Info and type f
RET (Info-follow-reference), you will generate an error
message that says:

No such node: "Catching Mistakes) The only way ...

This is because Info perceives the example of the error as the first
cross reference in this node and if you type a RET immediately
after typing the Info f command, Info will attempt to go to the
referenced node.  If you type f catch TAB RET, Info
will complete the node name of the correctly written example and take
you to the `Catching Mistakes' node.  (If you try this, you can return
from the `Catching Mistakes' node by typing l
(Info-last).)

Catching Errors with TeX Formatting

You can also catch mistakes when you format a file with TeX.

Usually, you will want to do this after you have run
texinfo-format-buffer (or, better, makeinfo-buffer) on
the same file, because texinfo-format-buffer sometimes displays
error messages that make more sense than TeX.  (See section Catching Errors with Info Formatting, for more information.)

For example, TeX was run on a Texinfo file, part of which is shown
here:

---------- Buffer: texinfo.texi ----------
name of the Texinfo file as an extension.  The
@samp{??} are `wildcards' that cause the shell to
substitute all the raw index files.  (@xref{sorting
indices, for more information about sorting
indices.)@refill
---------- Buffer: texinfo.texi ----------

(The cross reference lacks a closing brace.)
TeX produced the following output, after which it stopped:

---------- Buffer: *tex-shell* ----------
Runaway argument?
{sorting indices, for more information about sorting
indices.) @refill @ETC.
! Paragraph ended before @xref was complete.
<to be read again>
                   @par
l.27

?
---------- Buffer: *tex-shell* ----------

In this case, TeX produced an accurate and
understandable error message:

Paragraph ended before @xref was complete.

`@par' is an internal TeX command of no relevance to Texinfo.
`l.27' means that TeX detected the problem on line 27 of the
Texinfo file.  The `?' is the prompt TeX uses in this
circumstance.

Unfortunately, TeX is not always so helpful, and sometimes you must
truly be a Sherlock Holmes to discover what went wrong.

In any case, if you run into a problem like this, you can do one of three
things.

  1.

You can tell TeX to continue running and ignore just this error by
typing RET at the `?' prompt.

  2.

You can tell TeX to continue running and to ignore all errors as best
it can by typing r RET at the `?' prompt.
This is often the best thing to do.  However, beware: the one error
may produce a cascade of additional error messages as its consequences
are felt through the rest of the file.  To stop TeX when it is
producing such an avalanche of error messages, type C-c (or
C-c C-c, if you are running a shell inside Emacs).

  3.

You can tell TeX to stop this run by typing x RET
at the `?' prompt.

Please note that if you are running TeX inside Emacs, you need to
switch to the shell buffer and line at which TeX offers the `?'
prompt.

Sometimes TeX will format a file without producing error messages even
though there is a problem.  This usually occurs if a command is not ended
but TeX is able to continue processing anyhow.  For example, if you fail
to end an itemized list with the @end itemize command, TeX will
write a DVI file that you can print out.  The only error message that
TeX will give you is the somewhat mysterious comment that

(@end occurred inside a group at level 1)

However, if you print the DVI file, you will find that the text
of the file that follows the itemized list is entirely indented as if
it were part of the last item in the itemized list.  The error message
is the way TeX says that it expected to find an @end
command somewhere in the file; but that it could not determine where
it was needed.

Another source of notoriously hard-to-find errors is a missing
@end group command.  If you ever are stumped by
incomprehensible errors, look for a missing @end group command
first.

If the Texinfo file lacks header lines,
TeX may stop in the
beginning of its run and display output that looks like the following.
The `*' indicates that TeX is waiting for input.

This is TeX, Version 3.14159 (Web2c 7.0)
(test.texinfo [1])
*

In this case, simply type \end RET after the asterisk.  Then
write the header lines in the Texinfo file and run the TeX command
again. (Note the use of the backslash, `\'.  TeX uses `\'
instead of `@'; and in this circumstance, you are working
directly with TeX, not with Texinfo.)

Using texinfo-show-structure

It is not always easy to keep track of the nodes, chapters, sections, and
subsections of a Texinfo file.  This is especially true if you are revising
or adding to a Texinfo file that someone else has written.

In GNU Emacs, in Texinfo mode, the texinfo-show-structure
command lists all the lines that begin with the @-commands that
specify the structure: @chapter, @section,
@appendix, and so on.  With an argument (C-u
as prefix argument, if interactive),
the command also shows the @node lines.  The
texinfo-show-structure command is bound to C-c C-s in
Texinfo mode, by default.

The lines are displayed in a buffer called the `*Occur*' buffer,
indented by hierarchical level.  For example, here is a part of what was
produced by running texinfo-show-structure on this manual:

 Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
 in buffer texinfo.texi.
 ...
 4177:@chapter Nodes
 4198:    @heading Two Paths
 4231:    @section Node and Menu Illustration
 4337:    @section The @code{@@node} Command
 4393:        @subheading Choosing Node and Pointer Names
 4417:        @subsection How to Write an @code{@@node} Line
 4469:        @subsection @code{@@node} Line Tips
 ...

This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin
with the @section, @subheading, and @subsection
commands respectively.  If you move your cursor into the `*Occur*'
window, you can position the cursor over one of the lines and use the
C-c C-c command (occur-mode-goto-occurrence), to jump to
the corresponding spot in the Texinfo file.  See section `Using Occur' in The GNU Emacs Manual, for more
information about occur-mode-goto-occurrence.

The first line in the `*Occur*' window describes the regular
expression specified by texinfo-heading-pattern.  This regular
expression is the pattern that texinfo-show-structure looks for.
See section `Using Regular Expressions' in The GNU Emacs Manual,
for more information.

When you invoke the texinfo-show-structure command, Emacs will
display the structure of the whole buffer.  If you want to see the
structure of just a part of the buffer, of one chapter, for example,
use the C-x n n (narrow-to-region) command to mark the
region.  (See section `Narrowing' in The GNU Emacs Manual.)  This is
how the example used above was generated.  (To see the whole buffer
again, use C-x n w (widen).)

If you call texinfo-show-structure with a prefix argument by
typing C-u C-c C-s, it will list lines beginning with
@node as well as the lines beginning with the @-sign commands
for @chapter, @section, and the like.

You can remind yourself of the structure of a Texinfo file by looking at
the list in the `*Occur*' window; and if you have mis-named a node
or left out a section, you can correct the mistake.

Using occur

Sometimes the texinfo-show-structure command produces too much
information.  Perhaps you want to remind yourself of the overall structure
of a Texinfo file, and are overwhelmed by the detailed list produced by
texinfo-show-structure.  In this case, you can use the occur
command directly.  To do this, type

M-x occur

and then, when prompted, type a regexp, a regular expression for
the pattern you want to match.  (See section `Regular Expressions' in The GNU Emacs Manual.)  The occur command works from
the current location of the cursor in the buffer to the end of the
buffer.  If you want to run occur on the whole buffer, place
the cursor at the beginning of the buffer.

For example, to see all the lines that contain the word
`@chapter' in them, just type `@chapter'.  This will
produce a list of the chapters.  It will also list all the sentences
with `@chapter' in the middle of the line.

If you want to see only those lines that start with the word
`@chapter', type `^@chapter' when prompted by
occur.  If you want to see all the lines that end with a word
or phrase, end the last word with a `$'; for example,
`catching mistakes$'.  This can be helpful when you want to see
all the nodes that are part of the same chapter or section and
therefore have the same `Up' pointer.

See section `Using Occur' in The GNU Emacs Manual,
for more information.

Finding Badly Referenced Nodes

You can use the Info-validate command to check whether any of
the `Next', `Previous', `Up' or other node pointers fail to point to a
node.  This command checks that every node pointer points to an
existing node.  The Info-validate command works only on Info
files, not on Texinfo files.

The makeinfo program validates pointers automatically, so you
do not need to use the Info-validate command if you are using
makeinfo.  You only may need to use Info-validate if you
are unable to run makeinfo and instead must create an Info file
using texinfo-format-region or texinfo-format-buffer, or
if you write an Info file from scratch.

  • Using Info-validate: How to run Info-validate.

  • Unsplit: How to create an unsplit file.

  • Tagifying: How to tagify a file.

  • Splitting: How to split a file manually.

Running Info-validate

To use Info-validate, visit the Info file you wish to check and
type:

M-x Info-validate

(Note that the Info-validate command requires an upper case
`I'.  You may also need to create a tag table before running
Info-validate.  See section Tagifying a File.)

If your file is valid, you will receive a message that says "File appears
valid".  However, if you have a pointer that does not point to a node,
error messages will be displayed in a buffer called `*problems in
info file*'.

For example, Info-validate was run on a test file that contained
only the first node of this manual.  One of the messages said:

In node "Overview", invalid Next: Texinfo Mode

This meant that the node called `Overview' had a `Next' pointer that
did not point to anything (which was true in this case, since the test file
had only one node in it).

Now suppose we add a node named `Texinfo Mode' to our test case
but we do not specify a `Previous' for this node.  Then we will get
the following error message:

In node "Texinfo Mode", should have Previous: Overview

This is because every `Next' pointer should be matched by a
`Previous' (in the node where the `Next' points) which points back.

Info-validate also checks that all menu entries and cross references
point to actual nodes.

Note that Info-validate requires a tag table and does not work
with files that have been split.  (The texinfo-format-buffer
command automatically splits large files.)  In order to use
Info-validate on a large file, you must run
texinfo-format-buffer with an argument so that it does not split
the Info file; and you must create a tag table for the unsplit
file.

Creating an Unsplit File

You can run Info-validate only on a single Info file that has a
tag table.  The command will not work on the indirect subfiles that
are generated when a master file is split.  If you have a large file
(longer than 70,000 bytes or so), you need to run the
texinfo-format-buffer or makeinfo-buffer command in such
a way that it does not create indirect subfiles.  You will also need
to create a tag table for the Info file.  After you have done this,
you can run Info-validate and look for badly referenced
nodes.

The first step is to create an unsplit Info file.  To prevent
texinfo-format-buffer from splitting a Texinfo file into
smaller Info files, give a prefix to the M-x
texinfo-format-buffer command:

C-u M-x texinfo-format-buffer

or else

C-u C-c C-e C-b

When you do this, Texinfo will not split the file and will not create
a tag table for it.

Tagifying a File

After creating an unsplit Info file, you must create a tag table for
it.  Visit the Info file you wish to tagify and type:

M-x Info-tagify

(Note the upper case `I' in Info-tagify.)  This creates an
Info file with a tag table that you can validate.

The third step is to validate the Info file:

M-x Info-validate

(Note the upper case `I' in Info-validate.)
In brief, the steps are:

C-u M-x texinfo-format-buffer
M-x Info-tagify
M-x Info-validate

After you have validated the node structure, you can rerun
texinfo-format-buffer in the normal way so it will construct a
tag table and split the file automatically, or you can make the tag
table and split the file manually.

Splitting a File Manually

You should split a large file or else let the
texinfo-format-buffer or makeinfo-buffer command do it
for you automatically.  (Generally you will let one of the formatting
commands do this job for you.  See section Creating an Info File.)

The split-off files are called the indirect subfiles.

Info files are split to save memory.  With smaller files, Emacs does not
have make such a large buffer to hold the information.

If an Info file has more than 30 nodes, you should also make a tag
table for it. See section Running Info-validate, for information
about creating a tag table.  (Again, tag tables are usually created
automatically by the formatting command; you only need to create a tag
table yourself if you are doing the job manually.  Most likely, you
will do this for a large, unsplit file on which you have run
Info-validate.)

Visit the Info file you wish to tagify and split and type the two
commands:

M-x Info-tagify
M-x Info-split

(Note that the `I' in `Info' is upper case.)

When you use the Info-split command, the buffer is modified into a
(small) Info file which lists the indirect subfiles.  This file should be
saved in place of the original visited file.  The indirect subfiles are
written in the same directory the original file is in, with names generated
by appending `-' and a number to the original file name.

The primary file still functions as an Info file, but it contains just
the tag table and a directory of subfiles.

Refilling Paragraphs

The @refill command refills and, optionally, indents the first
line of a paragraph.(11) The
@refill command is no longer important, but we describe it here
because you once needed it.  You will see it in many old Texinfo
files.

Without refilling, paragraphs containing long @-constructs may look
bad after formatting because the formatter removes @-commands and
shortens some lines more than others.  In the past, neither the
texinfo-format-region command nor the
texinfo-format-buffer command refilled paragraphs
automatically.  The @refill command had to be written at the
end of every paragraph to cause these formatters to fill them.  (Both
TeX and makeinfo have always refilled paragraphs
automatically.)  Now, all the Info formatters automatically fill and
indent those paragraphs that need to be filled and indented.

The @refill command causes texinfo-format-region and
texinfo-format-buffer to refill a paragraph in the Info file
after all the other processing has been done.  For this reason,
you can not use @refill with a paragraph containing either
@* or @w{ ... } since the refilling action will
override those two commands.

The texinfo-format-region and texinfo-format-buffer
commands now automatically append @refill to the end of each
paragraph that should be filled.  They do not append @refill to
the ends of paragraphs that contain @* or @w{ ...}
and therefore do not refill or indent them.

@-Command Syntax

The character `@' is used to start special Texinfo commands.
(It has the same meaning that `\' has in plain TeX.)  Texinfo
has four types of @-command:

1. Non-alphabetic commands.

These commands consist of an @ followed by a punctuation mark or other
character that is not part of the alphabet.  Non-alphabetic commands are
almost always part of the text within a paragraph, and never take any
argument.  The two characters (@ and the other one) are complete in
themselves; none is followed by braces.  The non-alphabetic commands
are: @., @:, @*, @SPACE,
@TAB, @NL, @@, @{, and
@}.

2. Alphabetic commands that do not require arguments.

These commands start with @ followed by a word followed by left- and
right-hand braces.  These commands insert special symbols in the
document; they do not require arguments.  For example,
@dots{} => `...', @equiv{}
=> `==', @TeX{} => `TeX',
and @bullet{} => `*'.

3. Alphabetic commands that require arguments within braces.

These commands start with @ followed by a letter or a word, followed by an
argument within braces.  For example, the command @dfn indicates
the introductory or defining use of a term; it is used as follows: `In
Texinfo, @@-commands are @dfn{mark-up} commands.'

4. Alphabetic commands that occupy an entire line.

These commands occupy an entire line.  The line starts with @,
followed by the name of the command (a word); for example, @center
or @cindex.  If no argument is needed, the word is followed by
the end of the line.  If there is an argument, it is separated from
the command name by a space.  Braces are not used.

Thus, the alphabetic commands fall into classes that have
different argument syntaxes.  You cannot tell to which class a command
belongs by the appearance of its name, but you can tell by the
command's meaning: if the command stands for a glyph, it is in
class 2 and does not require an argument; if it makes sense to use the
command together with other text as part of a paragraph, the command
is in class 3 and must be followed by an argument in braces;
otherwise, it is in class 4 and uses the rest of the line as its
argument.

The purpose of having a different syntax for commands of classes 3 and
4 is to make Texinfo files easier to read, and also to help the GNU
Emacs paragraph and filling commands work properly.  There is only one
exception to this rule: the command @refill, which is always
used at the end of a paragraph immediately following the final period
or other punctuation character.  @refill takes no argument and
does not require braces.  @refill never confuses the
Emacs paragraph commands because it cannot appear at the beginning of
a line.

How to Obtain TeX

TeX is freely redistributable.  You can obtain TeX for Unix
systems via anonymous ftp or on physical media.  The core material
consists of the Web2c TeX distribution (http://tug.org/web2c).

Instructions for retrieval by anonymous ftp and information on other
available distributions:

ftp://tug.org/tex/unixtex.ftp
http://tug.org/unixtex.ftp

The Free Software Foundation provides a core distribution on its Source
Code CD-ROM suitable for printing Texinfo manuals; the University of
Washington maintains and supports a tape distribution; the TeX Users
Group co-sponsors a complete CD-ROM TeX distribution.

  •

For the FSF Source Code CD-ROM, please contact:

    Free Software Foundation, Inc.
59 Temple Place Suite 330
Boston, MA   02111-1307
USA
Telephone: +1-617-542-5942
Fax: (including Japan) +1-617-542-2652
Free Dial Fax (in Japan):
      0031-13-2473 (KDD)
      0066-3382-0158 (IDC)
Electronic mail: gnu@gnu.org

  •

To order a complete distribution on CD-ROM, please see
http://tug.org/tex-live.html.  (This distribution is also
available by FTP; see the URL's above.)

  •

To order a full distribution from the University of Washington on either
a 1/4in 4-track QIC-24 cartridge or a 4mm DAT cartridge,
send $210 to:

    Pierre A. MacKay
Denny Hall, Mail Stop DH-10
University of Washington
Seattle, WA   98195
USA
Telephone: +1-206-543-2268
Electronic mail: mackay@cs.washington.edu

Please make checks payable to the University of Washington.
Checks must be in U.S. dollars, drawn on a U.S. bank.  Overseas
sites: please add to the base cost, if desired, $20.00 for shipment via
air parcel post, or $30.00 for shipment via courier.

Many other TeX distributions are available; see
http://tug.org/.

Command and Variable Index

This is an alphabetical list of all the @-commands, assorted Emacs Lisp
functions, and several variables.  To make the list easier to use, the
commands are listed without their preceding `@'.

!

  • ! (end of sentence)

    •

    "

  • "

    •

    '

  • '

    •

    (

  • (newline)

  • (space)

  • (tab)

    •

    *

  • * (force line break)

    •

    ,

  • ,

    •

    -

  • -

    •

    .

  • .  (end of sentence)

    •

    :

  • : (suppress widening)

    •

    =

  • =

    •

    ?

  • ? (end of sentence)

    •

    @

  • @ (single `@')

    •

    ^

  • ^

    •

    `

  • `

    •

    a

  • AA

  • aa

  • AE

  • ae

  • afourpaper

  • appendix

  • appendixsec

  • appendixsection

  • appendixsubsec

  • appendixsubsubsec

  • apply

  • asis

  • author

    •

    b

  • b (bold font)

  • buffer-end

  • bullet

  • bye, bye

    •

    c

  • c (comment)

  • cartouche

  • center

  • centerchap

  • chapheading

  • chapter

  • cindex

  • cite

  • clear

  • code

  • columnfractions

  • comment

  • contents

  • copyright, copyright

  • cropmarks

    •

    d

  • defcodeindex

  • defcv

  • deffn

  • deffnx

  • defindex

  • definfoenclose

  • defivar

  • defmac

  • defmethod, defmethod

  • defop

  • defopt

  • defspec

  • deftp

  • deftypefn

  • deftypefun

  • deftypevar

  • deftypevr

  • defun

  • defvar

  • defvr

  • dfn

  • dircategory

  • direntry

  • display

  • dmn

  • dotaccent

  • dotless

  • dots

    •

    e

  • email

  • emph

  • end, end

  • end titlepage

  • enumerate

  • evenfooting

  • evenheading

  • everyfooting

  • everyheading

  • example

  • exclamdown

  • exdent

    •

    f

  • file

  • filll

  • finalout

  • findex

  • flushleft

  • flushright

  • foobar, foobar, foobar

  • footnote

  • footnotestyle

  • format

  • forward-word

  • ftable

    •

    g

  • group

    •

    h

  • H

  • heading

  • headings

  • html

  • hyphenation

    •

    i

  • i (italic font)

  • ifclear

  • ifhtml, ifhtml

  • ifinfo

  • ifnothtml

  • ifnotinfo

  • ifnottex

  • ifset

  • iftex

  • ignore

  • image

  • include

  • Info-validate

  • inforef

  • input (TeX command)

  • isearch-backward

  • isearch-forward

  • item, item, item

  • itemize

  • itemx

    •

    k

  • kbd

  • kbdinputstyle

  • key

  • kindex

    •

    l

  • L

  • l

  • lisp

  • lowersections

    •

    m

  • macro

  • mag (TeX command)

  • majorheading

  • makeinfo-buffer

  • makeinfo-kill-job

  • makeinfo-recenter-output-buffer

  • makeinfo-region

  • math

  • menu

  • minus

  • multitable

    •

    n

  • need

  • next-error

  • noindent

    •

    o

  • O

  • o

  • occur

  • occur-mode-goto-occurrence

  • oddfooting

  • oddheading

  • OE

  • oe

    •

    p

  • page

  • paragraphindent

  • pindex

  • pounds

  • printindex

  • pxref

    •

    q

  • questiondown

  • quotation

    •

    r

  • r (Roman font)

  • raisesections

  • ref

  • refill

  • ringaccent

    •

    s

  • samp

  • sc (small caps font)

  • section

  • set

  • setchapternewpage

  • setfilename

  • settitle

  • shortcontents

  • shorttitlepage

  • smallbook

  • smallexample

  • smalllisp

  • sp (line spacing)

  • sp (titlepage line spacing)

  • ss

  • strong

  • subheading

  • subsection

  • subsubheading

  • subsubsection

  • subtitle

  • summarycontents

  • syncodeindex, syncodeindex

  • synindex

    •

    t

  • t (typewriter font)

  • table

  • tex

  • tex (command)

  • texinfo-all-menus-update

  • texinfo-every-node-update

  • texinfo-format-buffer, texinfo-format-buffer, texinfo-format-buffer

  • texinfo-format-region, texinfo-format-region, texinfo-format-region

  • texinfo-indent-menu-description

  • texinfo-insert-@code

  • texinfo-insert-@dfn

  • texinfo-insert-@end

  • texinfo-insert-@example

  • texinfo-insert-@item

  • texinfo-insert-@kbd

  • texinfo-insert-@node

  • texinfo-insert-@noindent

  • texinfo-insert-@samp

  • texinfo-insert-@table

  • texinfo-insert-@var

  • texinfo-insert-braces

  • texinfo-insert-node-lines

  • texinfo-make-menu

  • texinfo-master-menu

  • texinfo-multiple-files-update

  • texinfo-multiple-files-update (in brief)

  • texinfo-sequential-node-update

  • texinfo-show-structure, texinfo-show-structure

  • texinfo-start-menu-description

  • texinfo-tex-buffer

  • texinfo-tex-print

  • texinfo-tex-region

  • texinfo-update-node

  • thischapter

  • thischaptername

  • thisfile

  • thispage

  • thistitle

  • tieaccent

  • tindex

  • title

  • titlefont

  • titlepage

  • today

  • top (@-command)

    •

    u

  • u

  • ubaraccent

  • udotaccent

  • unmacro

  • unnumbered

  • unnumberedsec

  • unnumberedsubsec

  • unnumberedsubsubsec

  • up-list

  • uref

  • url

    •

    v

  • v

  • value

  • var

  • vindex

  • vskip

  • vtable

    •

    w

  • w (prevent line break)

    •

    x

  • xref

    •

    {

  • { (single `{')

    •

    }

  • } (single `}')

    •

    ~

  • ~

    •

    Concept Index

    &

  • ¡

  • ¿

  • Å

  • Æ

  • Ø

  • ß

  • å

  • æ

  • ø

    •

    (

  • (dir) as Up node of Top node

    •

    .

  • .cshrc initialization file

  • .profile initialization file

    •

    :

  • `:' last in INFOPATH

    •

    @

  • @-command in nodename

  • @-command list

  • @-command syntax

  • @-commands

  • @dotless{i}

  • @dotless{j}

  • @include file sample

  • @menu parts

  • @node line writing

    •

    a

  • A4 paper, printing on

  • Abbreviations for keys

  • Accents, inserting

  • Acute accent

  • Adding a new info file

  • Alphabetical @-command list

  • Another Info directory

  • Apostrophe in nodename

  • Arguments, repeated and optional

  • Aspect ratio of images

  • Automatic pointer creation with makeinfo

  • Automatically insert nodes, menus

    •

    b

  • Backslash, and macros

  • Badly referenced nodes

  • Batch formatting for Info

  • Beginning a Texinfo file

  • Beginning line of a Texinfo file

  • Berry, Karl

  • Big points

  • Black rectangle in hardcopy

  • Blank lines

  • Body of a macro

  • Book characteristics, printed

  • Book, printing small

  • Box with rounded corners

  • Braces and argument syntax

  • Braces, inserting

  • Braces, when to use

  • Breaks in a line

  • Breve accent

  • Buffer formatting and printing

  • Bullets, inserting

    •

    c

  • Case in nodename

  • Catching errors with Info formatting

  • Catching errors with TeX formatting

  • Catching mistakes

  • Cedilla accent

  • Centimeters

  • Chapter structuring

  • Characteristics, printed books or manuals

  • Chassell, Robert J.

  • Check accent

  • Checking for badly referenced nodes

  • Ciceros

  • Circumflex accent

  • code, arg to @kbdinputstyle

  • Column widths, defining for multitables

  • Combining indices

  • Comma in nodename

  • Command definitions

  • Commands to insert special characters

  • Commands using raw HTML

  • Commands using raw TeX

  • Commands, inserting them

  • Comments

  • Compile command for formatting

  • Conditionally visible text

  • Conditions for copying Texinfo

  • Contents, Table of

  • Contents-like outline of file structure

  • Conventions for writing definitions

  • Conventions, syntactic

  • Copying conditions

  • Copying permissions

  • Copying software

  • Copyright page

  • Correcting mistakes

  • Create nodes, menus automatically

  • Creating an Info file

  • Creating an unsplit file

  • Creating index entries

  • Creating indices

  • Creating pointers with makeinfo

  • Cropmarks for printing

  • Cross reference parts

  • Cross references

  • Cross references using @inforef

  • Cross references using @pxref

  • Cross references using @ref

  • Cross references using @xref

  • Customized highlighting

  • Customizing of TeX for Texinfo

    •

    d

  • Debugging the Texinfo structure

  • Debugging with Info formatting

  • Debugging with TeX formatting

  • Defining indexing entries

  • Defining macros

  • Defining new indices

  • Defining new Texinfo commands

  • Definition commands

  • Definition conventions

  • Definition template

  • Definitions grouped together

  • Description for menu, start

  • Did@^ot points

  • Different cross reference commands

  • Dimension formatting

  • Dimensions and image sizes

  • `dir' directory for Info installation

  • `dir' file listing

  • `dir', created by install-info

  • Display formatting

  • distinct, arg to @kbdinputstyle

  • Distorting images

  • Distribution

  • Dot accent

  • Dotless i, j

  • Dots, inserting, Dots, inserting

  • Double-colon menu entries

  • DVI file

    •

    e

  • Ellipsis, inserting

  • Emacs

  • Emacs shell, format, print from

  • Emphasizing text

  • Emphasizing text, font for

  • enable

  • Enclosure command for Info

  • `End' node footnote style

  • End of header line

  • End titlepage starts headings

  • Ending a Sentence

  • Ending a Texinfo file

  • Entries for an index

  • Entries, making index

  • Enumeration

  • epsf.tex

  • epsf.tex, installing

  • Equivalence, indicating it

  • Error message, indicating it

  • Errors, parsing

  • Es-zet

  • European A4 paper

  • Evaluation glyph

  • Example for a small book

  • Example menu

  • example, arg to @kbdinputstyle

  • Examples, formatting them

  • Expansion, indicating it

    •

    f

  • File beginning

  • File ending

  • File section structure, showing it

  • Filling paragraphs

  • Final output

  • Finding badly referenced nodes

  • Fine-tuning, and hyphenation

  • First line of a Texinfo file

  • First node

  • Floating accents, inserting

  • Fonts for indices

  • Fonts for printing, not for Info

  • Footings

  • Footnotes

  • Format a dimension

  • Format and print hardcopy

  • Format and print in Texinfo mode

  • Format with the compile command

  • Format, print from Emacs shell

  • Formats for images

  • Formatting a file for Info

  • Formatting commands

  • Formatting examples

  • Formatting for Info

  • Formatting for printing

  • Formatting headings and footings

  • Formatting requirements

  • Formatting with tex and texindex

  • Frequently used commands, inserting

  • fubar

  • Function definitions

    •

    g

  • General syntactic conventions

  • Generating menus with indices

  • German S

  • Globbing

  • Glyphs

  • GNU Emacs

  • GNU Emacs shell, format, print from

  • Going to other Info files' nodes

  • Grave accent

  • Group (hold text together vertically)

  • Grouping two definitions together

    •

    h

  • Hardcopy, printing it

  • `hboxes', overfull

  • Header for Texinfo files

  • Header of a Texinfo file

  • Headings

  • Headings, page, begin to appear

  • Height of images

  • Highlighting text

  • Highlighting, customized

  • Hints

  • Holding text together vertically

  • HTML commands, using ordinary

  • Hungariam umlaut accent

  • Hyphenation, helping TeX do

  • Hyphenation, preventing

    •

    i

  • If text conditionally visible

  • `ifinfo' permissions

  • Ignored before @setfilename

  • Ignored text

  • Image formats

  • Images, inserting

  • Inches

  • Include file requirements

  • Include file sample

  • Include files

  • Include files, and section levels

  • Indentation undoing

  • Indenting paragraphs

  • Index entries

  • Index entries, making

  • Index entry writing

  • Index font types

  • Indexing commands, predefined

  • Indexing table entries automatically

  • Indicating commands, definitions, etc.

  • Indicating evaluation

  • Indices

  • Indices, combining them

  • Indices, defining new

  • Indices, printing and menus

  • Indices, sorting

  • Indices, two letter names

  • Indirect subfiles

  • Info batch formatting

  • Info file installation

  • Info file requires @setfilename

  • Info file, listing new one

  • Info file, splitting manually

  • Info files

  • Info formatting

  • Info installed in another directory

  • Info validating a large file

  • Info, creating an on-line file

  • Info-directory-list

  • Info; other files' nodes

  • INFOPATH

  • Initialization file for TeX input

  • Insert nodes, menus automatically

  • Inserting @, braces

  • Inserting accents

  • Inserting dots, Inserting dots

  • Inserting ellipsis

  • Inserting frequently used commands

  • Inserting space

  • Inserting special characters and symbols

  • install-info

  • Installing an Info file

  • Installing Info in another directory

  • Introduction, as part of file

  • Invoking macros

  • Itemization

    •

    k

  • keyboard input

  • Keys, recommended names

  • Knuth, Donald

    •

    l

  • L/

  • l/

  • Larger or smaller pages

  • Less cluttered menu entry

  • License agreement

  • Line breaks

  • Line breaks, preventing

  • Line length, column widths as fraction of

  • Line spacing

  • Lisp example

  • Lisp example for a small book

  • List of  @-commands

  • Listing a new info file

  • Lists and tables, making

  • Local variables

  • Location of menus

  • Looking for badly referenced nodes

  • lpr (DVI print command)

    •

    m

  • Macro definitions, Macro definitions

  • Macro invocation

  • Macron accent

  • Macros

  • Macros, undefining

  • Magnified printing

  • mailto link

  • makeinfo inside Emacs

  • makeinfo options

  • Making a printed manual

  • Making a tag table automatically

  • Making a tag table manually

  • Making cross references

  • Making line and page breaks

  • Making lists and tables

  • Manual characteristics, printed

  • Marking text within a paragraph

  • Marking words and phrases

  • Master menu

  • Master menu parts

  • Mathematical expressions, Mathematical expressions

  • Menu description, start

  • Menu entries with two colons

  • Menu example

  • Menu location

  • Menu parts

  • Menu writing

  • Menus

  • Menus generated with indices

  • META key

  • Meta-syntactic chars for arguments

  • Millimeters

  • Minimal requirements for formatting

  • Minimal Texinfo file (requirements)

  • Mistakes, catching

  • Mode, using Texinfo

  • Multiple spaces

  • Multitable column widths

  • Multitable rows

  • Must have in Texinfo file

  • Mutually recursive macros

    •

    n

  • Names for indices

  • Names of index files

  • Names recommended for keys

  • Naming a `Top' Node in references

  • Need space at page bottom

  • New index defining

  • New info file, listing it in `dir' file

  • New Texinfo commands, defining

  • Node line requirements

  • Node line writing

  • Node, `Top'

  • Node, defined

  • Nodename must be unique

  • Nodename, cannot contain

  • Nodes for menus are short

  • Nodes in other Info files

  • Nodes, catching mistakes

  • Nodes, checking for badly referenced

  • Not ending a sentence

    •

    o

  • Obtaining TeX

  • Occurrences, listing with @occur

  • OE

  • oe

  • Optional and repeated arguments

  • Options for makeinfo

  • Ordinary HTML commands, using

  • Ordinary TeX commands, using

  • Other Info files' nodes

  • Outline of file structure, showing it

  • Overfull `hboxes'

  • Overview of Texinfo

    •

    p

  • Page breaks

  • Page delimiter in Texinfo mode

  • Page headings

  • Page numbering

  • Page sizes for books

  • page-delimiter

  • Pages, starting odd

  • Paper size, European A4

  • Paragraph indentation

  • Paragraph, marking text within

  • Parsing errors

  • Part of file formatting and printing

  • Parts of a cross reference

  • Parts of a master menu

  • Parts of a menu

  • Periods, inserting

  • Permissions

  • Permissions, printed

  • Picas

  • Pictures, inserting

  • Pinard, Fran@,{c}ois

  • plain TeX

  • Point, indicating it in a buffer

  • Pointer creation with makeinfo

  • Pointer validation with makeinfo

  • Points (dimension)

  • Predefined indexing commands

  • Predefined names for indices

  • Preparing to use TeX

  • Preventing line and page breaks

  • Previous node of Top node

  • Print and format in Texinfo mode

  • Print, format from Emacs shell

  • Printed book and manual characteristics

  • Printed output, indicating it

  • Printed permissions

  • Printing a region or buffer

  • Printing an index

  • Printing cropmarks

  • Problems, catching

  • Prototype row, column widths defined by

    •

    q

  • Quotations

    •

    r

  • Raising and lowering sections

  • Raw formatter commands

  • Recommended names for keys

  • Rectangle, ugly, black in hardcopy

  • Recursion, mutual

  • References

  • References using @inforef

  • References using @pxref

  • References using @ref

  • References using @xref

  • Referring to other Info files

  • Refilling paragraphs

  • Region formatting and printing

  • Region printing in Texinfo mode

  • Repeated and optional arguments

  • Required in Texinfo file

  • Requirements for formatting

  • Requirements for include files

  • Requirements for updating commands

  • Result of an expression

  • ridt.eps

  • Ring accent

  • Rows, of a multitable

  • Running an Info formatter

  • Running Info-validate

  • Running makeinfo in Emacs

    •

    s

  • Sample @include file

  • Sample function definition

  • Sample Texinfo file

  • Sample Texinfo file, no comments

  • Scaled points

  • Section structure of a file, showing it

  • Sections, raising and lowering

  • Sentence ending punctuation

  • Sentence non-ending punctuation

  • `Separate' footnote style

  • Sharp S

  • Shell formatting with tex and texindex

  • Shell, format, print from

  • Shell, running makeinfo in

  • Short nodes for menus

  • Showing the section structure of a file

  • Showing the structure of a file

  • Site-wide Texinfo configuration file

  • Size of printed book

  • slanted typewriter font, for @kbd

  • Small book example

  • Small book size

  • Small caps font

  • Software copying permissions

  • Sorting indices

  • Spaces (blank lines)

  • Spacing, inserting

  • Special characters, commands to insert

  • Special insertions

  • Special typesetting commands

  • Specifying index entries

  • Splitting an Info file manually

  • Stallman, Richard M.

  • Start of header line

  • Starting chapters

  • Structure of a file, showing it

  • Structure, catching mistakes in

  • Structuring of chapters

  • Subsection-like commands

  • Subsub commands

  • Syntactic conventions

  • Syntax, optional & repeated arguments

    •

    t

  • tab

  • Table of contents

  • Tables and lists, making

  • Tables with indexes

  • Tables, making multi-column

  • Tables, making two-column

  • Tabs; don't use!

  • Tag table, making automatically

  • Tag table, making manually

  • Template for a definition

  • TeX commands, using ordinary

  • TeX index sorting

  • TeX input initialization

  • TeX, how to obtain

  • texi2dvi

  • texi2dvi (shell script)

  • texindex, texindex

  • Texinfo commands, defining new

  • Texinfo file beginning

  • Texinfo file ending

  • Texinfo file header

  • Texinfo file minimum

  • Texinfo file section structure, showing it

  • Texinfo mode

  • Texinfo overview

  • Texinfo printed book characteristics

  • texinfo.cnf, texinfo.cnf

  • texinfo.cnf installation

  • texinfo.tex, installing

  • TEXINPUTS, TEXINPUTS

  • TEXINPUTS environment variable

  • Text, conditionally visible

  • Thin space between number, dimension

  • Tie-after accent

  • Tilde accent

  • Tips

  • Title page

  • Titlepage end starts headings

  • Titlepage permissions

  • `Top' node

  • Top node is first

  • `Top' node naming for references

  • `Top' node summary

  • Tree structuring

  • Two `First' Lines for @deffn

  • Two letter names for indices

  • Two named items for @table

  • Two part menu entry

  • Typesetting commands for dots, etc.

    •

    u

  • Umlaut accent

  • Uncluttered menu entry

  • Undefining macros

  • Underbar accent

  • Underdot accent

  • Uniform resource locator, indicating

  • Uniform resource locator, referring to

  • Unique nodename requirement

  • Unprocessed text

  • Unsplit file creation

  • Up node of Top node

  • Updating nodes and menus

  • Updating requirements

  • URL, indicating

  • URL, referring to

  • Usage tips

  • user input

  • User options, marking

  • User-defined Texinfo commands

    •

    v

  • Validating a large file

  • Validation of pointers

  • Value of an expression, indicating

  • version number, finding

  • Vertical whitespace (`vskip')

  • Vertically holding text together

  • Visibility of conditional text

    •

    w

  • Weisshaus, Melissa

  • Whitespace, inserting, Whitespace, inserting

  • Width of images

  • Widths, defining multitable column

  • Wildcards

  • Words and phrases, marking them

  • Writing a menu

  • Writing an @node line

  • Writing index entries

    •

    z

  • Zuhn, David D.

    •

This document was generated on 25 September 1999 using the
texi2html
translator version 1.54.


Texinfo 4.0

Texinfo

The GNU Documentation Format

for Texinfo version 4.0, 28 September 1999

Robert J. Chassell
Richard M. Stallman

Table of Contents

  • Texinfo Copying Conditions
  • Overview of Texinfo
    • Reporting Bugs
    • Using Texinfo
    • Info files
    • Printed Books
    • @-commands
    • General Syntactic Conventions
    • Comments
    • What a Texinfo File Must Have
    • Six Parts of a Texinfo File
    • A Short Sample Texinfo File
    • Acknowledgements and History
  • Using Texinfo Mode
    • The Usual GNU Emacs Editing Commands
    • Inserting Frequently Used Commands
    • Showing the Section Structure of a File
    • Updating Nodes and Menus
      • Updating Requirements
      • Other Updating Commands
    • Formatting for Info
    • Formatting and Printing
    • Texinfo Mode Summary
  • Beginning a Texinfo File
    • Sample Texinfo File Beginning
    • The Texinfo File Header
      • The First Line of a Texinfo File
      • Start of Header
      • @setfilename
      • @settitle
      • @setchapternewpage
      • Paragraph Indenting
      • @exampleindent: Environment Indenting
      • End of Header
    • Summary and Copying Permissions for Info
    • The Title and Copyright Pages
      • @titlepage
      • @titlefont, @center, and @sp
      • @title, @subtitle, and @author
      • Copyright Page and Permissions
      • Heading Generation
      • The @headings Command
    • The `Top' Node and Master Menu
      • `Top' Node Title
      • Parts of a Master Menu
    • Software Copying Permissions
  • Ending a Texinfo File
    • Index Menus and Printing an Index
    • Generating a Table of Contents
    • @bye File Ending
  • Chapter Structuring
    • Tree Structure of Sections
    • Structuring Command Types
    • @top
    • @chapter
    • @unnumbered and @appendix
    • @majorheading, @chapheading
    • @section
    • @unnumberedsec, @appendixsec, @heading
    • The @subsection Command
    • The @subsection-like Commands
    • The `subsub' Commands
    • @raisesections and @lowersections
  • Nodes
    • Two Paths
    • Node and Menu Illustration
    • The @node Command
      • Choosing Node and Pointer Names
      • How to Write an @node Line
      • @node Line Tips
      • @node Line Requirements
      • The First Node
      • The @top Sectioning Command
      • The `Top' Node Summary
    • Creating Pointers with makeinfo
    • @anchor: Defining Arbitrary Cross-reference Targets
  • Menus
    • Writing a Menu
    • The Parts of a Menu
    • Less Cluttered Menu Entry
    • A Menu Example
    • Referring to Other Info Files
  • Cross References
    • Different Cross Reference Commands
    • Parts of a Cross Reference
    • @xref
      • @xref with One Argument
      • @xref with Two Arguments
      • @xref with Three Arguments
      • @xref with Four and Five Arguments
    • Naming a `Top' Node
    • @ref
    • @pxref
    • @inforef
    • @uref{url[, text][, replacement]}
  • Marking Words and Phrases
    • Indicating Definitions, Commands, etc.
      • @code{sample-code}
      • @kbd{keyboard-characters}
      • @key{key-name}
      • @samp{text}
      • @var{metasyntactic-variable}
      • @env{environment-variable}
      • @file{file-name}
      • @command{command-name}
      • @option{option-name}
      • @dfn{term}
      • @cite{reference}
      • @acronym{acronym}
      • @url{uniform-resource-locator}
      • @email{email-address[, displayed-text]}
    • Emphasizing Text
      • @emph{text} and @strong{text}
      • @sc{text}: The Small Caps Font
      • Fonts for Printing, Not Info
  • Quotations and Examples
    • Block Enclosing Commands
    • @quotation
    • @example
    • @noindent
    • @lisp
    • @small... Block Commands
    • @display and @smalldisplay
    • @format and @smallformat
    • @exdent: Undoing a Line's Indentation
    • @flushleft and @flushright
    • Drawing Cartouches Around Examples
  • Lists and Tables
    • @itemize: Making an Itemized List
    • @enumerate: Making a Numbered or Lettered List
    • Making a Two-column Table
      • @ftable and @vtable
      • @itemx
    • Multi-column Tables
      • Multitable Column Widths
      • Multitable Rows
  • Indices
    • Making Index Entries
    • Predefined Indices
    • Defining the Entries of an Index
    • Combining Indices
      • @syncodeindex
      • @synindex
    • Defining New Indices
  • Special Insertions
    • Inserting @ and Braces
      • Inserting `@' with @@
      • Inserting `{' and `}'with @{ and @}
    • Inserting Space
      • Not Ending a Sentence
      • Ending a Sentence
      • Multiple Spaces
      • @dmn{dimension}: Format a Dimension
    • Inserting Accents
    • Inserting Ellipsis and Bullets
      • @dots{} (...) and @enddots{} (....)
      • @bullet{} (*)
    • Inserting TeX and the Copyright Symbol
      • @TeX{} (TeX)
      • @copyright{} (©)
    • @pounds{} (£): Pounds Sterling
    • @minus{} (-): Inserting a Minus Sign
    • @math: Inserting Mathematical Expressions
    • Glyphs for Examples
      • @result{} (=>): Indicating Evaluation
      • @expansion{} (==>): Indicating an Expansion
      • @print{} (-|): Indicating Printed Output
      • @error{} (error-->): Indicating an Error Message
      • @equiv{} (==): Indicating Equivalence
      • @point{} (-!-): Indicating Point in a Buffer
    • Footnotes
      • Footnote Commands
      • Footnote Styles
    • Inserting Images
  • Making and Preventing Breaks
    • @*: Generate Line Breaks
    • @- and @hyphenation: Helping TeX hyphenate
    • @w{text}: Prevent Line Breaks
    • @sp n: Insert Blank Lines
    • @page: Start a New Page
    • @group: Prevent Page Breaks
    • @need mils: Prevent Page Breaks
  • Definition Commands
    • The Template for a Definition
    • Optional and Repeated Arguments
    • Two or More `First' Lines
    • The Definition Commands
      • Functions and Similar Entities
      • Variables and Similar Entities
      • Functions in Typed Languages
      • Variables in Typed Languages
      • Object-Oriented Programming
      • Data Types
    • Conventions for Writing Definitions
    • A Sample Function Definition
  • Conditionally Visible Text
    • Conditional Commands
    • Conditional Not Commands
    • Raw Formatter Commands
    • @set, @clear, and @value
      • @ifset and @ifclear
      • @set and @value
      • @value Example
  • Internationalization
    • @documentlanguage cc: Set the Document Language
    • @documentencoding enc: Set Input Encoding
  • Defining New Texinfo Commands
    • Defining Macros
    • Invoking Macros
    • Macro Details
    • `@alias new=existing'
    • `definfoenclose': Customized Highlighting
  • Formatting and Printing Hardcopy
    • Use TeX
    • Format with tex and texindex
    • Format with texi2dvi
    • Shell Print Using lpr -d
    • From an Emacs Shell
    • Formatting and Printing in Texinfo Mode
    • Using the Local Variables List
    • TeX Formatting Requirements Summary
    • Preparing for TeX
    • Overfull "hboxes"
    • Printing "Small" Books
    • Printing on A4 Paper
    • @pagesizes [width][, height]: Custom page sizes
    • Cropmarks and Magnification
    • PDF Output
  • Creating and Installing Info Files
    • Creating an Info File
      • makeinfo Preferred
      • Running makeinfo from a Shell
      • Options for makeinfo
      • Pointer Validation
      • Running makeinfo inside Emacs
      • The texinfo-format... Commands
      • Batch Formatting
      • Tag Files and Split Files
      • Generating HTML
    • Installing an Info File
      • The Directory File `dir'
      • Listing a New Info File
      • Info Files in Other Directories
      • Installing Info Directory Files
      • Invoking install-info
  • @-Command List
  • Tips and Hints
  • A Sample Texinfo File
  • Sample Permissions
    • `ifinfo' Copying Permissions
    • Titlepage Copying Permissions
  • Include Files
    • How to Use Include Files
    • texinfo-multiple-files-update
    • Include File Requirements
    • Sample File with @include
    • Evolution of Include Files
  • Page Headings
    • Standard Heading Formats
    • Specifying the Type of Heading
    • How to Make Your Own Headings
  • Formatting Mistakes
    • Catching Errors with Info Formatting
    • Catching Errors with TeX Formatting
    • Using texinfo-show-structure
    • Using occur
    • Finding Badly Referenced Nodes
      • Running Info-validate
      • Creating an Unsplit File
      • Tagifying a File
      • Splitting a File Manually
  • Refilling Paragraphs
  • @-Command Syntax
  • How to Obtain TeX
  • Command and Variable Index
  • Concept Index

Texinfo Copying Conditions

The programs currently being distributed that relate to Texinfo include portions of GNU Emacs, plus other separate programs (including makeinfo, info, texindex, and `texinfo.tex'). These programs are free; this means that everyone is free to use them and free to redistribute them on a free basis. The Texinfo-related programs are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of the programs that relate to Texinfo, that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the Texinfo related programs, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to Texinfo. If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.

The precise conditions of the licenses for the programs currently being distributed that relate to Texinfo are found in the General Public Licenses that accompany them.

Overview of Texinfo

Texinfo (1) is a documentation system that uses a single source file to produce both online information and printed output. This means that instead of writing two different documents, one for the online information and the other for a printed work, you need write only one document. Therefore, when the work is revised, you need revise only that one document.

Reporting Bugs

We welcome bug reports or suggestions for the Texinfo system, both programs and documentation. Please email them to bug-texinfo@gnu.org. You can get the latest version of Texinfo from ftp://ftp.gnu.org/gnu/texinfo/ and its mirrors worldwide.

For bug reports, please include enough information for the maintainers to reproduce the problem. Generally speaking, that means:

  • the version number of Texinfo and the program(s) or manual(s) involved.
  • hardware, operating system, and compiler versions.
  • any unusual options you gave to @command{configure}.
  • the contents of any input files necessary to reproduce the bug.
  • a description of the problem and samples of any erroneous output.
  • anything else that you think would be helpful.

When in doubt whether something is needed or not, include it. It's better to include too much than to leave out something important.

Patches are most welcome; if possible, please make them with `diff -c' (see section `Overview' in Comparing and Merging Files) and include `ChangeLog' entries (see section `Change Log' in The GNU Emacs Manual).

When sending email, please do not encode or split the messages in any way if possible; it's much easier to deal with one plain text message, however large, than many small ones. GNU shar is a convenient way of packaging multiple and/or binary files for email.

Using Texinfo

Using Texinfo, you can create a printed document with the normal features of a book, including chapters, sections, cross references, and indices. From the same Texinfo source file, you can create a menu-driven, online Info file with nodes, menus, cross references, and indices. You can also create from that same source file an HTML output file suitable for use with a web browser. The GNU Emacs Manual is a good example of a Texinfo file, as is this manual.

To make a printed document, you process a Texinfo source file with the TeX typesetting program (but the Texinfo language is very different from TeX's usual language, plain TeX). This creates a DVI file that you can typeset and print as a book or report (see section Formatting and Printing Hardcopy).

To output an Info file, process your Texinfo source with the makeinfo utility or Emacs's texinfo-format-buffer command. You can install the result in your Info tree (see section Installing an Info File).

To output an HTML file, process your Texinfo source with makeinfo using the `--html' option. You can (for example) install the result on your web site.

If you are a programmer and would like to contribute to the GNU project by implementing additional output formats for Texinfo, that would be excellent. But please do not write a separate translator texi2foo for your favorite format foo! That is the hard way to do the job, and makes extra work in subsequent maintenance, since the Texinfo language is continually being enhanced and updated. Instead, the best approach is modify makeinfo to generate the new format, as it does now for Info and HTML.

TeX works with virtually all printers; Info works with virtually all computer terminals; the HTML output works with virtually all web browsers. Thus Texinfo can be used by almost any computer user.

A Texinfo source file is a plain ASCII file containing text and @-commands (words preceded by an `@') that tell the typesetting and formatting programs what to do. You may edit a Texinfo file with any text editor; but it is especially convenient to use GNU Emacs since that editor has a special mode, called Texinfo mode, that provides various Texinfo-related features. (See section Using Texinfo Mode.)

Before writing a Texinfo source file, you should learn about nodes, menus, cross references, and the rest, for example by reading this manual.

You can use Texinfo to create both online help and printed manuals; moreover, Texinfo is freely redistributable. For these reasons, Texinfo is the official documentation format of the GNU project. More information is available at the GNU documentation web page.

From time to time, proposals are made to generate traditional Unix man pages from Texinfo source. This is not likely to ever be supported, because man pages have a very strict conventional format. Merely enhancing @command{makeinfo} to output troff format would be insufficient. Generating a good man page therefore requires a completely different source than the typical Texinfo applications of generating a good user manual or a good reference manual. This makes generating man pages incompatible with the Texinfo design goal of not having to document the same information in different ways for different output formats. You might as well just write the man page directly.

If you wish to support man pages, the program @command{help2man} may be useful; it generates a traditional man page from the `--help' output of a program. In fact, this is currently used to generate man pages for the Texinfo programs themselves. It is free software written by Brendan O'Dea, available from http://www.ozemail.com.au/~bod/help2man.tar.gz.

Info files

An Info file is a Texinfo file formatted so that the Info documentation reading program can operate on it. (makeinfo and texinfo-format-buffer are two commands that convert a Texinfo file into an Info file.)

Info files are divided into pieces called nodes, each of which contains the discussion of one topic. Each node has a name, and contains both text for the user to read and pointers to other nodes, which are identified by their names. The Info program displays one node at a time, and provides commands with which the user can move to other related nodes.

Each node of an Info file may have any number of child nodes that describe subtopics of the node's topic. The names of child nodes are listed in a menu within the parent node; this allows you to use certain Info commands to move to one of the child nodes. Generally, an Info file is organized like a book. If a node is at the logical level of a chapter, its child nodes are at the level of sections; likewise, the child nodes of sections are at the level of subsections.

All the children of any one parent are linked together in a bidirectional chain of `Next' and `Previous' pointers. The `Next' pointer provides a link to the next section, and the `Previous' pointer provides a link to the previous section. This means that all the nodes that are at the level of sections within a chapter are linked together. Normally the order in this chain is the same as the order of the children in the parent's menu. Each child node records the parent node name as its `Up' pointer. The last child has no `Next' pointer, and the first child has the parent both as its `Previous' and as its `Up' pointer.(2)

The book-like structuring of an Info file into nodes that correspond to chapters, sections, and the like is a matter of convention, not a requirement. The `Up', `Previous', and `Next' pointers of a node can point to any other nodes, and a menu can contain any other nodes. Thus, the node structure can be any directed graph. But it is usually more comprehensible to follow a structure that corresponds to the structure of chapters and sections in a printed book or report.

In addition to menus and to `Next', `Previous', and `Up' pointers, Info provides pointers of another kind, called references, that can be sprinkled throughout the text. This is usually the best way to represent links that do not fit a hierarchical structure.

Usually, you will design a document so that its nodes match the structure of chapters and sections in the printed output. But occasionally there are times when this is not right for the material being discussed. Therefore, Texinfo uses separate commands to specify the node structure for the Info file and the section structure for the printed output.

Generally, you enter an Info file through a node that by convention is named `Top'. This node normally contains just a brief summary of the file's purpose, and a large menu through which the rest of the file is reached. From this node, you can either traverse the file systematically by going from node to node, or you can go to a specific node listed in the main menu, or you can search the index menus and then go directly to the node that has the information you want. Alternatively, with the standalone Info program, you can specify specific menu items on the command line (see section `Top' in Info).

If you want to read through an Info file in sequence, as if it were a printed manual, you can hit SPC repeatedly, or you get the whole file with the advanced Info command g *. (See Info file `info', node `Expert'.)

The `dir' file in the `info' directory serves as the departure point for the whole Info system. From it, you can reach the `Top' nodes of each of the documents in a complete Info system.

If you wish to refer to an Info file in a URI, you can use the (unofficial) syntax exemplified in the following. This works with Emacs/W3, for example:

info:///usr/info/emacs#Dissociated%20Press
info:emacs#Dissociated%20Press
info://localhost/usr/info/emacs#Dissociated%20Press

The @command{info} program itself does not follow URI's of any kind.

Printed Books

A Texinfo file can be formatted and typeset as a printed book or manual. To do this, you need TeX, a powerful, sophisticated typesetting program written by Donald Knuth.(3)

A Texinfo-based book is similar to any other typeset, printed work: it can have a title page, copyright page, table of contents, and preface, as well as chapters, numbered or unnumbered sections and subsections, page headers, cross references, footnotes, and indices.

You can use Texinfo to write a book without ever having the intention of converting it into online information. You can use Texinfo for writing a printed novel, and even to write a printed memo, although this latter application is not recommended since electronic mail is so much easier.

TeX is a general purpose typesetting program. Texinfo provides a file `texinfo.tex' that contains information (definitions or macros) that TeX uses when it typesets a Texinfo file. (`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX commands, which TeX can then process to create the typeset document.) `texinfo.tex' contains the specifications for printing a document. You can get the latest version of `texinfo.tex' from ftp://ftp.gnu.org/gnu/texinfo.tex.

Most often, documents are printed on 8.5 inch by 11 inch pages (216mm by 280mm; this is the default size), but you can also print for 7 inch by 9.25 inch pages (178mm by 235mm; the @smallbook size) or on European A4 size paper (@afourpaper). (See section Printing "Small" Books. Also, see section Printing on A4 Paper.)

By changing the parameters in `texinfo.tex', you can change the size of the printed document. In addition, you can change the style in which the printed document is formatted; for example, you can change the sizes and fonts used, the amount of indentation for each paragraph, the degree to which words are hyphenated, and the like. By changing the specifications, you can make a book look dignified, old and serious, or light-hearted, young and cheery.

TeX is freely distributable. It is written in a superset of Pascal called WEB and can be compiled either in Pascal or (by using a conversion program that comes with the TeX distribution) in C. (See section `TeX Mode' in The GNU Emacs Manual, for information about TeX.)

TeX is very powerful and has a great many features. Because a Texinfo file must be able to present information both on a character-only terminal in Info form and in a typeset book, the formatting commands that Texinfo supports are necessarily limited.

To get a copy of TeX, see section How to Obtain TeX.

@-commands

In a Texinfo file, the commands that tell TeX how to typeset the printed manual and tell makeinfo and texinfo-format-buffer how to create an Info file are preceded by `@'; they are called @-commands. For example, @node is the command to indicate a node and @chapter is the command to indicate the start of a chapter.

Please note: All the @-commands, with the exception of the @TeX{} command, must be written entirely in lower case.

The Texinfo @-commands are a strictly limited set of constructs. The strict limits make it possible for Texinfo files to be understood both by TeX and by the code that converts them into Info files. You can display Info files on any terminal that displays alphabetic and numeric characters. Similarly, you can print the output generated by TeX on a wide variety of printers.

Depending on what they do or what arguments(4) they take, you need to write @-commands on lines of their own or as part of sentences:

  • Write a command such as @noindent at the beginning of a line as the only text on the line. (@noindent prevents the beginning of the next line from being indented as the beginning of a paragraph.)
  • Write a command such as @chapter at the beginning of a line followed by the command's arguments, in this case the chapter title, on the rest of the line. (@chapter creates chapter titles.)
  • Write a command such as @dots{} wherever you wish but usually within a sentence. (@dots{} creates dots ...)
  • Write a command such as @code{sample-code} wherever you wish (but usually within a sentence) with its argument, sample-code in this example, between the braces. (@code marks text as being code.)
  • Write a command such as @example on a line of its own; write the body-text on following lines; and write the matching @end command, @end example in this case, at the on a line of its own after the body-text. (@example ... @end example indents and typesets body-text as an example.) It's usually ok to indent environment commands like this, but in complicated and hard-to-define circumstances the extra spaces cause extra space to appear in the output, so beware.

As a general rule, a command requires braces if it mingles among other text; but it does not need braces if it starts a line of its own. The non-alphabetic commands, such as @:, are exceptions to the rule; they do not need braces.

As you gain experience with Texinfo, you will rapidly learn how to write the different commands: the different ways to write commands make it easier to write and read Texinfo files than if all commands followed exactly the same syntax. (For details about @-command syntax, see section @-Command Syntax.)

General Syntactic Conventions

This section describes the general conventions used in all Texinfo documents.

  • All printable ASCII characters except `@', `{' and `}' can appear in a Texinfo file and stand for themselves. `@' is the escape character which introduces commands. `{' and `}' should be used only to surround arguments to certain commands. To put one of these special characters into the document, put an `@' character in front of it, like this: `@@', `@{', and `@}'.
  • It is customary in TeX to use doubled single-quote characters to begin and end quotations: " and " . This convention should be followed in Texinfo files. TeX converts doubled single-quote characters to left- and right-hand doubled quotation marks, "like this", and Info converts doubled single-quote characters to ASCII double-quotes: " and " to " .
  • Use three hyphens in a row, `---', for a dash--like this. In TeX, a single or double hyphen produces a printed dash that is shorter than the usual typeset dash. Info reduces three hyphens to two for display on the screen.
  • To prevent a paragraph from being indented in the printed manual, put the command @noindent on a line by itself before the paragraph.
  • If you mark off a region of the Texinfo file with the @iftex and @end iftex commands, that region will appear only in the printed copy; in that region, you can use certain commands borrowed from plain TeX that you cannot use in Info. Likewise, if you mark off a region with the @ifinfo and @end ifinfo commands, that region will appear only in the Info file; in that region, you can use Info commands that you cannot use in TeX. Similarly for @ifhtml ... @end ifhtml, @ifnothtml ... @end ifnothtml, @ifnotinfo ... @end ifnotinfo, @ifnottex ... @end ifnottex. See section Conditionally Visible Text.

Caution: Do not use tabs in a Texinfo file! TeX uses variable-width fonts, which means that it cannot predefine a tab to work in all circumstances. Consequently, TeX treats tabs like single spaces, and that is not what they look like. Furthermore, makeinfo does nothing special with tabs, and thus a tab character in your input file may appear differently in the output.

To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple spaces when you press the TAB key.

Also, you can run untabify in Emacs to convert tabs in a region to multiple spaces.

Comments

You can write comments in a Texinfo file that will not appear in either the Info file or the printed manual by using the @comment command (which may be abbreviated to @c). Such comments are for the person who revises the Texinfo file. All the text on a line that follows either @comment or @c is a comment; the rest of the line does not appear in either the Info file or the printed manual. (Often, you can write the @comment or @c in the middle of a line, and only the text that follows after the @comment or @c command does not appear; but some commands, such as @settitle and @setfilename, work on a whole line. You cannot use @comment or @c in a line beginning with such a command.)

You can write long stretches of text that will not appear in either the Info file or the printed manual by using the @ignore and @end ignore commands. Write each of these commands on a line of its own, starting each command at the beginning of the line. Text between these two commands does not appear in the processed output. You can use @ignore and @end ignore for writing comments. Often, @ignore and @end ignore is used to enclose a part of the copying permissions that applies to the Texinfo source file of a document, but not to the Info or printed version of the document.

What a Texinfo File Must Have

By convention, the names of Texinfo files end with one of the extensions `.texinfo', `.texi', `.txi', or `.tex'. The longer extension is preferred since it describes more clearly to a human reader the nature of the file. The shorter extensions are for operating systems that cannot handle long file names.

In order to be made into a printed manual and an Info file, a Texinfo file must begin with lines like this:

\input texinfo
@setfilename info-file-name
@settitle name-of-manual

The contents of the file follow this beginning, and then you must end a Texinfo file with a line like this:

@bye

The `\input texinfo' line tells TeX to use the `texinfo.tex' file, which tells TeX how to translate the Texinfo @-commands into TeX typesetting commands. (Note the use of the backslash, `\'; this is correct for TeX.) The `@setfilename' line provides a name for the Info file and tells TeX to open auxiliary files. The `@settitle' line specifies a title for the page headers (or footers) of the printed manual.

The @bye line at the end of the file on a line of its own tells the formatters that the file is ended and to stop formatting.

Usually, you will not use quite such a spare format, but will include mode setting and start-of-header and end-of-header lines at the beginning of a Texinfo file, like this:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename info-file-name
@settitle name-of-manual
@c %**end of header

In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo mode when you edit the file.

The @c lines which surround the `@setfilename' and `@settitle' lines are optional, but you need them in order to run TeX or Info on just part of the file. (See section Start of Header, for more information.)

Furthermore, you will usually provide a Texinfo file with a title page, indices, and the like. But the minimum, which can be useful for short documents, is just the three lines at the beginning and the one line at the end.

Six Parts of a Texinfo File

Generally, a Texinfo file contains more than the minimal beginning and end--it usually contains six parts:

1. Header
The Header names the file, tells TeX which definitions' file to use, and performs other "housekeeping" tasks.
2. Summary Description and Copyright
The Summary Description and Copyright segment describes the document and contains the copyright notice and copying permissions for the Info file. The segment must be enclosed between @ifinfo and @end ifinfo commands so that the formatters place it only in the Info file.
3. Title and Copyright
The Title and Copyright segment contains the title and copyright pages and copying permissions for the printed manual. The segment must be enclosed between @titlepage and @end titlepage commands. The title and copyright page appear only in the printed manual.
4. `Top' Node and Master Menu
The Master Menu contains a complete menu of all the nodes in the whole Info file. It appears only in the Info file, in the `Top' node.
5. Body
The Body of the document may be structured like a traditional book or encyclopedia or it may be free form.
6. End
The End contains commands for printing indices and generating the table of contents, and the @bye command on a line of its own.

A Short Sample Texinfo File

Here is a complete but very short Texinfo file, in six parts. The first three parts of the file, from `\input texinfo' through to `@end titlepage', look more intimidating than they are. Most of the material is standard boilerplate; when you write a manual, simply insert the names for your own manual in this segment. (See section Beginning a Texinfo File.)

In the following, the sample text is indented; comments on it are not. The complete file, without any comments, is shown in section A Sample Texinfo File.

Part 1: Header

The header does not appear in either the Info file or the printed output. It sets various parameters, including the name of the Info file and the title used in the header.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@setchapternewpage odd
@c %**end of header

Part 2: Summary Description and Copyright

The summary description and copyright segment does not appear in the printed document.

@ifinfo
This is a short example of a complete Texinfo file.

Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end ifinfo

Part 3: Titlepage and Copyright

The titlepage segment does not appear in the Info file.

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

Part 4: `Top' Node and Master Menu

The `Top' node contains the master menu for the Info file. Since a printed manual uses a table of contents rather than a menu, the master menu appears only in the Info file.

@node    Top,       First Chapter, ,         (dir)
@comment node-name, next,          previous, up

@menu
* First Chapter::    The first chapter is the
                     only chapter in this sample.
* Concept Index::    This index has two entries.
@end menu

Part 5: The Body of the Document

The body segment contains all the text of the document, but not the indices or table of contents. This example illustrates a node and a chapter containing an enumerated list.

@node    First Chapter, Concept Index, Top,      Top
@comment node-name,     next,          previous, up
@chapter First Chapter
@cindex Sample index entry

This is the contents of the first chapter.
@cindex Another sample index entry

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @code{makeinfo} and @code{texinfo-format-buffer}
commands transform a Texinfo file such as this into
an Info file; and @TeX{} typesets it for a printed
manual.

Part 6: The End of the Document

The end segment contains commands for generating an index in a node and unnumbered chapter of its own, (usually) for generating the table of contents, and the @bye command that marks the end of the document.

@node    Concept Index,    ,  First Chapter, Top
@unnumbered Concept Index

@printindex cp

@contents
@bye

The Results

Here is what the contents of the first chapter of the sample look like:

This is the contents of the first chapter.

Here is a numbered list.

  1. This is the first item.
  2. This is the second item.

The makeinfo and texinfo-format-buffer commands transform a Texinfo file such as this into an Info file; and TeX typesets it for a printed manual.

Acknowledgements and History

Richard M. Stallman invented the Texinfo format, wrote the initial processors, and created Edition 1.0 of this manual. Robert J. Chassell greatly revised and extended the manual, starting with Edition 1.1. Brian Fox was responsible for the standalone Texinfo distribution until version 3.8, and wrote the standalone @command{makeinfo} and @command{info}. Karl Berry has made the updates since Texinfo 3.8 and subsequent releases, starting with Edition 2.22 of the manual.

Our thanks go out to all who helped improve this work, particularly to Fran@,{c}ois Pinard and David D. Zuhn, who tirelessly recorded and reported mistakes and obscurities; our special thanks go to Melissa Weisshaus for her frequent and often tedious reviews of nearly similar editions. The indefatigable Eli Zaretskii and Andreas Schwab have provided patches beyond counting. Zack Weinberg did the impossible by implementing the macro syntax in `texinfo.tex'. Dozens of others have contributed patches and suggestions, they are gratefully acknowledged in the `ChangeLog' file. Our mistakes are our own.

A bit of history: in the 1970's at CMU, Brian Reid developed a program and format named Scribe to mark up documents for printing. It used the @ character to introduce commands as Texinfo does and strived to describe document contents rather than formatting.

Meanwhile, people at MIT developed another, not too dissimilar format called Bolio. This then was converted to using TeX as its typesetting language: BoTeX.

BoTeX could only be used as a markup language for documents to be printed, not for online documents. Richard Stallman (RMS) worked on both Bolio and BoTeX. He also developed a nifty on-line help format called Info, and then combined BoTeX and Info to create Texinfo, a mark up language for text that is intended to be read both on line and as printed hard copy.

Using Texinfo Mode

You may edit a Texinfo file with any text editor you choose. A Texinfo file is no different from any other ASCII file. However, GNU Emacs comes with a special mode, called Texinfo mode, that provides Emacs commands and tools to help ease your work.

This chapter describes features of GNU Emacs' Texinfo mode but not any features of the Texinfo formatting language. If you are reading this manual straight through from the beginning, you may want to skim through this chapter briefly and come back to it after reading succeeding chapters which describe the Texinfo formatting language in detail.

Texinfo mode provides special features for working with Texinfo files. You can:

  • Insert frequently used @-commands.
  • Automatically create @node lines.
  • Show the structure of a Texinfo source file.
  • Automatically create or update the `Next', `Previous', and `Up' pointers of a node.
  • Automatically create or update menus.
  • Automatically create a master menu.
  • Format a part or all of a file for Info.
  • Typeset and print part or all of a file.

Perhaps the two most helpful features are those for inserting frequently used @-commands and for creating node pointers and menus.

The Usual GNU Emacs Editing Commands

In most cases, the usual Text mode commands work the same in Texinfo mode as they do in Text mode. Texinfo mode adds new editing commands and tools to GNU Emacs' general purpose editing features. The major difference concerns filling. In Texinfo mode, the paragraph separation variable and syntax table are redefined so that Texinfo commands that should be on lines of their own are not inadvertently included in paragraphs. Thus, the M-q (fill-paragraph) command will refill a paragraph but not mix an indexing command on a line adjacent to it into the paragraph.

In addition, Texinfo mode sets the page-delimiter variable to the value of texinfo-chapter-level-regexp; by default, this is a regular expression matching the commands for chapters and their equivalents, such as appendices. With this value for the page delimiter, you can jump from chapter title to chapter title with the C-x ] (forward-page) and C-x [ (backward-page) commands and narrow to a chapter with the C-x p (narrow-to-page) command. (See section `Pages' in The GNU Emacs Manual, for details about the page commands.)

You may name a Texinfo file however you wish, but the convention is to end a Texinfo file name with one of the extensions `.texinfo', `.texi', `.txi', or `.tex'. A longer extension is preferred, since it is explicit, but a shorter extension may be necessary for operating systems that limit the length of file names. GNU Emacs automatically enters Texinfo mode when you visit a file with a `.texinfo', `.texi' or `.txi' extension. Also, Emacs switches to Texinfo mode when you visit a file that has `-*-texinfo-*-' in its first line. If ever you are in another mode and wish to switch to Texinfo mode, type M-x texinfo-mode.

Like all other Emacs features, you can customize or enhance Texinfo mode as you wish. In particular, the keybindings are very easy to change. The keybindings described here are the default or standard ones.

Inserting Frequently Used Commands

Texinfo mode provides commands to insert various frequently used @-commands into the buffer. You can use these commands to save keystrokes.

The insert commands are invoked by typing C-c twice and then the first letter of the @-command:

C-c C-c c
M-x texinfo-insert-@code
Insert @code{} and put the cursor between the braces.
C-c C-c d
M-x texinfo-insert-@dfn
Insert @dfn{} and put the cursor between the braces.
C-c C-c e
M-x texinfo-insert-@end
Insert @end and attempt to insert the correct following word, such as `example' or `table'. (This command does not handle nested lists correctly, but inserts the word appropriate to the immediately preceding list.)
C-c C-c i
M-x texinfo-insert-@item
Insert @item and put the cursor at the beginning of the next line.
C-c C-c k
M-x texinfo-insert-@kbd
Insert @kbd{} and put the cursor between the braces.
C-c C-c n
M-x texinfo-insert-@node
Insert @node and a comment line listing the sequence for the `Next', `Previous', and `Up' nodes. Leave point after the @node.
C-c C-c o
M-x texinfo-insert-@noindent
Insert @noindent and put the cursor at the beginning of the next line.
C-c C-c s
M-x texinfo-insert-@samp
Insert @samp{} and put the cursor between the braces.
C-c C-c t
M-x texinfo-insert-@table
Insert @table followed by a SPC and leave the cursor after the SPC.
C-c C-c v
M-x texinfo-insert-@var
Insert @var{} and put the cursor between the braces.
C-c C-c x
M-x texinfo-insert-@example
Insert @example and put the cursor at the beginning of the next line.
C-c C-c {
M-x texinfo-insert-braces
Insert {} and put the cursor between the braces.
C-c C-c }
C-c C-c ]
M-x up-list
Move from between a pair of braces forward past the closing brace. Typing C-c C-c ] is easier than typing C-c C-c }, which is, however, more mnemonic; hence the two keybindings. (Also, you can move out from between braces by typing C-f.)

To put a command such as @code{...} around an existing word, position the cursor in front of the word and type C-u 1 C-c C-c c. This makes it easy to edit existing plain text. The value of the prefix argument tells Emacs how many words following point to include between braces---`1' for one word, `2' for two words, and so on. Use a negative argument to enclose the previous word or words. If you do not specify a prefix argument, Emacs inserts the @-command string and positions the cursor between the braces. This feature works only for those @-commands that operate on a word or words within one line, such as @kbd and @var.

This set of insert commands was created after analyzing the frequency with which different @-commands are used in the GNU Emacs Manual and the GDB Manual. If you wish to add your own insert commands, you can bind a keyboard macro to a key, use abbreviations, or extend the code in `texinfo.el'.

C-c C-c C-d (texinfo-start-menu-description) is an insert command that works differently from the other insert commands. It inserts a node's section or chapter title in the space for the description in a menu entry line. (A menu entry has three parts, the entry name, the node name, and the description. Only the node name is required, but a description helps explain what the node is about. See section The Parts of a Menu.)

To use texinfo-start-menu-description, position point in a menu entry line and type C-c C-c C-d. The command looks for and copies the title that goes with the node name, and inserts the title as a description; it positions point at beginning of the inserted text so you can edit it. The function does not insert the title if the menu entry line already contains a description.

This command is only an aid to writing descriptions; it does not do the whole job. You must edit the inserted text since a title tends to use the same words as a node name but a useful description uses different words.

Showing the Section Structure of a File

You can show the section structure of a Texinfo file by using the C-c C-s command (texinfo-show-structure). This command shows the section structure of a Texinfo file by listing the lines that begin with the @-commands for @chapter, @section, and the like. It constructs what amounts to a table of contents. These lines are displayed in another buffer called the `*Occur*' buffer. In that buffer, you can position the cursor over one of the lines and use the C-c C-c command (occur-mode-goto-occurrence), to jump to the corresponding spot in the Texinfo file.

C-c C-s
M-x texinfo-show-structure
Show the @chapter, @section, and such lines of a Texinfo file.
C-c C-c
M-x occur-mode-goto-occurrence
Go to the line in the Texinfo file corresponding to the line under the cursor in the `*Occur*' buffer.

If you call texinfo-show-structure with a prefix argument by typing C-u C-c C-s, it will list not only those lines with the @-commands for @chapter, @section, and the like, but also the @node lines. You can use texinfo-show-structure with a prefix argument to check whether the `Next', `Previous', and `Up' pointers of an @node line are correct.

Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark off the region of the buffer that you are interested in by using the C-x n n (narrow-to-region) command and texinfo-show-structure will work on only that region. To see the whole buffer again, use C-x n w (widen). (See section `Narrowing' in The GNU Emacs Manual, for more information about the narrowing commands.)

In addition to providing the texinfo-show-structure command, Texinfo mode sets the value of the page delimiter variable to match the chapter-level @-commands. This enables you to use the C-x ] (forward-page) and C-x [ (backward-page) commands to move forward and backward by chapter, and to use the C-x p (narrow-to-page) command to narrow to a chapter. See section `Pages' in The GNU Emacs Manual, for more information about the page commands.

Updating Nodes and Menus

Texinfo mode provides commands for automatically creating or updating menus and node pointers. The commands are called "update" commands because their most frequent use is for updating a Texinfo file after you have worked on it; but you can use them to insert the `Next', `Previous', and `Up' pointers into an @node line that has none and to create menus in a file that has none.

If you do not use the updating commands, you need to write menus and node pointers by hand, which is a tedious task.

You can use the updating commands to:

  • insert or update the `Next', `Previous', and `Up' pointers of a node,
  • insert or update the menu for a section, and
  • create a master menu for a Texinfo source file.

You can also use the commands to update all the nodes and menus in a region or in a whole Texinfo file.

The updating commands work only with conventional Texinfo files, which are structured hierarchically like books. In such files, a structuring command line must follow closely after each @node line, except for the `Top' @node line. (A structuring command line is a line beginning with @chapter, @section, or other similar command.)

You can write the structuring command line on the line that follows immediately after an @node line or else on the line that follows after a single @comment line or a single @ifinfo line. You cannot interpose more than one line between the @node line and the structuring command line; and you may interpose only an @comment line or an @ifinfo line.

Commands which work on a whole buffer require that the `Top' node be followed by a node with an @chapter or equivalent-level command. The menu updating commands will not create a main or master menu for a Texinfo file that has only @chapter-level nodes! The menu updating commands only create menus within nodes for lower level nodes. To create a menu of chapters, you must provide a `Top' node.

The menu updating commands remove menu entries that refer to other Info files since they do not refer to nodes within the current buffer. This is a deficiency. Rather than use menu entries, you can use cross references to refer to other Info files. None of the updating commands affect cross references.

Texinfo mode has five updating commands that are used most often: two are for updating the node pointers or menu of a single node (or a region); two are for updating every node pointer and menu in a file; and one, the texinfo-master-menu command, is for creating a master menu for a complete file, and optionally, for updating every node and menu in the whole Texinfo file.

The texinfo-master-menu command is the primary command:

C-c C-u m
M-x texinfo-master-menu
Create or update a master menu that includes all the other menus (incorporating the descriptions from pre-existing menus, if any). With an argument (prefix argument, C-u, if interactive), first create or update all the nodes and all the regular menus in the buffer before constructing the master menu. (See section The `Top' Node and Master Menu, for more about a master menu.) For texinfo-master-menu to work, the Texinfo file must have a `Top' node and at least one subsequent node. After extensively editing a Texinfo file, you can type the following:
C-u M-x texinfo-master-menu
or
C-u C-c C-u m
This updates all the nodes and menus completely and all at once.

The other major updating commands do smaller jobs and are designed for the person who updates nodes and menus as he or she writes a Texinfo file.

The commands are:

C-c C-u C-n
M-x texinfo-update-node
Insert the `Next', `Previous', and `Up' pointers for the node that point is within (i.e., for the @node line preceding point). If the @node line has pre-existing `Next', `Previous', or `Up' pointers in it, the old pointers are removed and new ones inserted. With an argument (prefix argument, C-u, if interactive), this command updates all @node lines in the region (which is the text between point and mark).
C-c C-u C-m
M-x texinfo-make-menu
Create or update the menu in the node that point is within. With an argument (C-u as prefix argument, if interactive), the command makes or updates menus for the nodes which are either within or a part of the region. Whenever texinfo-make-menu updates an existing menu, the descriptions from that menu are incorporated into the new menu. This is done by copying descriptions from the existing menu to the entries in the new menu that have the same node names. If the node names are different, the descriptions are not copied to the new menu.
C-c C-u C-e
M-x texinfo-every-node-update
Insert or update the `Next', `Previous', and `Up' pointers for every node in the buffer.
C-c C-u C-a
M-x texinfo-all-menus-update
Create or update all the menus in the buffer. With an argument (C-u as prefix argument, if interactive), first insert or update all the node pointers before working on the menus. If a master menu exists, the texinfo-all-menus-update command updates it; but the command does not create a new master menu if none already exists. (Use the texinfo-master-menu command for that.) When working on a document that does not merit a master menu, you can type the following:
C-u C-c C-u C-a
or
C-u M-x texinfo-all-menus-update
This updates all the nodes and menus.

The texinfo-column-for-description variable specifies the column to which menu descriptions are indented. By default, the value is 32 although it is often useful to reduce it to as low as 24. You can set the variable with the M-x edit-options command (see section `Editing Variable Values' in The GNU Emacs Manual) or with the M-x set-variable command (see section `Examining and Setting Variables' in The GNU Emacs Manual).

Also, the texinfo-indent-menu-description command may be used to indent existing menu descriptions to a specified column. Finally, if you wish, you can use the texinfo-insert-node-lines command to insert missing @node lines into a file. (See section Other Updating Commands, for more information.)

Updating Requirements

To use the updating commands, you must organize the Texinfo file hierarchically with chapters, sections, subsections, and the like. When you construct the hierarchy of the manual, do not `jump down' more than one level at a time: you can follow the `Top' node with a chapter, but not with a section; you can follow a chapter with a section, but not with a subsection. However, you may `jump up' any number of levels at one time--for example, from a subsection to a chapter.

Each @node line, with the exception of the line for the `Top' node, must be followed by a line with a structuring command such as @chapter, @section, or @unnumberedsubsec.

Each @node line/structuring-command line combination must look either like this:

@node     Comments,  Minimum, Conventions, Overview
@comment  node-name, next,    previous,    up
@section Comments

or like this (without the @comment line):

@node Comments, Minimum, Conventions, Overview
@section Comments

In this example, `Comments' is the name of both the node and the section. The next node is called `Minimum' and the previous node is called `Conventions'. The `Comments' section is within the `Overview' node, which is specified by the `Up' pointer. (Instead of an @comment line, you may also write an @ifinfo line.)

If a file has a `Top' node, it must be called `top' or `Top' and be the first node in the file.

The menu updating commands create a menu of sections within a chapter, a menu of subsections within a section, and so on. This means that you must have a `Top' node if you want a menu of chapters.

Incidentally, the makeinfo command will create an Info file for a hierarchically organized Texinfo file that lacks `Next', `Previous' and `Up' pointers. Thus, if you can be sure that your Texinfo file will be formatted with makeinfo, you have no need for the update node commands. (See section Creating an Info File, for more information about makeinfo.) However, both makeinfo and the texinfo-format-... commands require that you insert menus in the file.

Other Updating Commands

In addition to the five major updating commands, Texinfo mode possesses several less frequently used updating commands:

M-x texinfo-insert-node-lines
Insert @node lines before the @chapter, @section, and other sectioning commands wherever they are missing throughout a region in a Texinfo file. With an argument (C-u as prefix argument, if interactive), the texinfo-insert-node-lines command not only inserts @node lines but also inserts the chapter or section titles as the names of the corresponding nodes. In addition, it inserts the titles as node names in pre-existing @node lines that lack names. Since node names should be more concise than section or chapter titles, you must manually edit node names so inserted. For example, the following marks a whole buffer as a region and inserts @node lines and titles throughout:
C-x h C-u M-x texinfo-insert-node-lines
This command inserts titles as node names in @node lines; the texinfo-start-menu-description command (see section Inserting Frequently Used Commands) inserts titles as descriptions in menu entries, a different action. However, in both cases, you need to edit the inserted text.
M-x texinfo-multiple-files-update
Update nodes and menus in a document built from several separate files. With C-u as a prefix argument, create and insert a master menu in the outer file. With a numeric prefix argument, such as C-u 2, first update all the menus and all the `Next', `Previous', and `Up' pointers of all the included files before creating and inserting a master menu in the outer file. The texinfo-multiple-files-update command is described in the appendix on @include files. See section texinfo-multiple-files-update.
M-x texinfo-indent-menu-description
Indent every description in the menu following point to the specified column. You can use this command to give yourself more space for descriptions. With an argument (C-u as prefix argument, if interactive), the texinfo-indent-menu-description command indents every description in every menu in the region. However, this command does not indent the second and subsequent lines of a multi-line description.
M-x texinfo-sequential-node-update
Insert the names of the nodes immediately following and preceding the current node as the `Next' or `Previous' pointers regardless of those nodes' hierarchical level. This means that the `Next' node of a subsection may well be the next chapter. Sequentially ordered nodes are useful for novels and other documents that you read through sequentially. (However, in Info, the g * command lets you look through the file sequentially, so sequentially ordered nodes are not strictly necessary.) With an argument (prefix argument, if interactive), the texinfo-sequential-node-update command sequentially updates all the nodes in the region.

Formatting for Info

Texinfo mode provides several commands for formatting part or all of a Texinfo file for Info. Often, when you are writing a document, you want to format only part of a file--that is, a region.

You can use either the texinfo-format-region or the makeinfo-region command to format a region:

C-c C-e C-r
M-x texinfo-format-region
C-c C-m C-r
M-x makeinfo-region
Format the current region for Info.

You can use either the texinfo-format-buffer or the makeinfo-buffer command to format a whole buffer:

C-c C-e C-b
M-x texinfo-format-buffer
C-c C-m C-b
M-x makeinfo-buffer
Format the current buffer for Info.

For example, after writing a Texinfo file, you can type the following:

C-u C-c C-u m
or
C-u M-x texinfo-master-menu

This updates all the nodes and menus. Then type the following to create an Info file:

C-c C-m C-b
or
M-x makeinfo-buffer

For TeX or the Info formatting commands to work, the file must include a line that has @setfilename in its header.

See section Creating an Info File, for details about Info formatting.

Formatting and Printing

Typesetting and printing a Texinfo file is a multi-step process in which you first create a file for printing (called a DVI file), and then print the file. Optionally, you may also create indices. To do this, you must run the texindex command after first running the tex typesetting command; and then you must run the tex command again. Or else run the texi2dvi command which automatically creates indices as needed (see section Format with texi2dvi).

Often, when you are writing a document, you want to typeset and print only part of a file to see what it will look like. You can use the texinfo-tex-region and related commands for this purpose. Use the texinfo-tex-buffer command to format all of a buffer.

C-c C-t C-b
M-x texinfo-tex-buffer
Run texi2dvi on the buffer. In addition to running TeX on the buffer, this command automatically creates or updates indices as needed.
C-c C-t C-r
M-x texinfo-tex-region
Run TeX on the region.
C-c C-t C-i
M-x texinfo-texindex
Run texindex to sort the indices of a Texinfo file formatted with texinfo-tex-region. The texinfo-tex-region command does not run texindex automatically; it only runs the tex typesetting command. You must run the texinfo-tex-region command a second time after sorting the raw index files with the texindex command. (Usually, you do not format an index when you format a region, only when you format a buffer. Now that the texi2dvi command exists, there is little or no need for this command.)
C-c C-t C-p
M-x texinfo-tex-print
Print the file (or the part of the file) previously formatted with texinfo-tex-buffer or texinfo-tex-region.

For texinfo-tex-region or texinfo-tex-buffer to work, the file must start with a `\input texinfo' line and must include an @settitle line. The file must end with @bye on a line by itself. (When you use texinfo-tex-region, you must surround the @settitle line with start-of-header and end-of-header lines.)

See section Formatting and Printing Hardcopy, for a description of the other TeX related commands, such as tex-show-print-queue.

Texinfo Mode Summary

In Texinfo mode, each set of commands has default keybindings that begin with the same keys. All the commands that are custom-created for Texinfo mode begin with C-c. The keys are somewhat mnemonic.

Insert Commands

The insert commands are invoked by typing C-c twice and then the first letter of the @-command to be inserted. (It might make more sense mnemonically to use C-c C-i, for `custom insert', but C-c C-c is quick to type.)

C-c C-c c       Insert `@code'.
C-c C-c d       Insert `@dfn'.
C-c C-c e       Insert `@end'.
C-c C-c i       Insert `@item'.
C-c C-c n       Insert `@node'.
C-c C-c s       Insert `@samp'.
C-c C-c v       Insert `@var'.
C-c C-c {       Insert braces.
C-c C-c ]
C-c C-c }       Move out of enclosing braces.

C-c C-c C-d     Insert a node's section title
                in the space for the description
                in a menu entry line.

Show Structure

The texinfo-show-structure command is often used within a narrowed region.

C-c C-s         List all the headings.

The Master Update Command

The texinfo-master-menu command creates a master menu; and can be used to update every node and menu in a file as well.

C-c C-u m
M-x texinfo-master-menu
                Create or update a master menu.

C-u C-c C-u m   With C-u as a prefix argument, first
                create or update all nodes and regular
                menus, and then create a master menu.

Update Pointers

The update pointer commands are invoked by typing C-c C-u and then either C-n for texinfo-update-node or C-e for texinfo-every-node-update.

C-c C-u C-n     Update a node.
C-c C-u C-e     Update every node in the buffer.

Update Menus

Invoke the update menu commands by typing C-c C-u and then either C-m for texinfo-make-menu or C-a for texinfo-all-menus-update. To update both nodes and menus at the same time, precede C-c C-u C-a with C-u.

C-c C-u C-m     Make or update a menu.

C-c C-u C-a     Make or update all
                menus in a buffer.

C-u C-c C-u C-a With C-u as a prefix argument,
                first create or update all nodes and
                then create or update all menus.

Format for Info

The Info formatting commands that are written in Emacs Lisp are invoked by typing C-c C-e and then either C-r for a region or C-b for the whole buffer.

The Info formatting commands that are written in C and based on the makeinfo program are invoked by typing C-c C-m and then either C-r for a region or C-b for the whole buffer.

Use the texinfo-format... commands:

C-c C-e C-r     Format the region.
C-c C-e C-b     Format the buffer.

Use makeinfo:

C-c C-m C-r     Format the region.
C-c C-m C-b     Format the buffer.
C-c C-m C-l     Recenter the makeinfo output buffer.
C-c C-m C-k     Kill the makeinfo formatting job.

Typeset and Print

The TeX typesetting and printing commands are invoked by typing C-c C-t and then another control command: C-r for texinfo-tex-region, C-b for texinfo-tex-buffer, and so on.

C-c C-t C-r     Run TeX on the region.
C-c C-t C-b     Run texi2dvi on the buffer.
C-c C-t C-i     Run texindex.
C-c C-t C-p     Print the DVI file.
C-c C-t C-q     Show the print queue.
C-c C-t C-d     Delete a job from the print queue.
C-c C-t C-k     Kill the current TeX formatting job.
C-c C-t C-x     Quit a currently stopped TeX formatting job.
C-c C-t C-l     Recenter the output buffer.

Other Updating Commands

The remaining updating commands do not have standard keybindings because they are rarely used.

M-x texinfo-insert-node-lines
                Insert missing @node lines in region.
                With C-u as a prefix argument,
                use section titles as node names.

M-x texinfo-multiple-files-update
                Update a multi-file document.
                With C-u 2 as a prefix argument,
                create or update all nodes and menus
                in all included files first.

M-x texinfo-indent-menu-description
                Indent descriptions.

M-x texinfo-sequential-node-update
                Insert node pointers in strict sequence.

Beginning a Texinfo File

Certain pieces of information must be provided at the beginning of a Texinfo file, such as the name of the file and the title of the document.

Generally, the beginning of a Texinfo file has four parts:

  1. The header, delimited by special comment lines, that includes the commands for naming the Texinfo file and telling TeX what definitions file to use when processing the Texinfo file.
  2. A short statement of what the file is about, with a copyright notice and copying permissions. This is enclosed in @ifinfo and @end ifinfo commands so that the formatters place it only in the Info file.
  3. A title page and copyright page, with a copyright notice and copying permissions. This is enclosed between @titlepage and @end titlepage commands. The title and copyright page appear only in the printed manual.
  4. The `Top' node that contains a menu for the whole Info file. The contents of this node appear only in the Info file.

Also, optionally, you may include the copying conditions for a program and a warranty disclaimer. The copying section will be followed by an introduction or else by the first chapter of the manual.

Since the copyright notice and copying permissions for the Texinfo document (in contrast to the copying permissions for a program) are in parts that appear only in the Info file or only in the printed manual, this information must be given twice.

Sample Texinfo File Beginning

The following sample shows what is needed.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename name-of-info-file
@settitle name-of-manual
@setchapternewpage odd
@c %**end of header

@ifinfo
This file documents ...

Copyright year copyright-owner

Permission is granted to ...
@end ifinfo

@c  This title page illustrates only one of the
@c  two methods of forming a title page.

@titlepage
@title name-of-manual-when-printed
@subtitle subtitle-if-any
@subtitle second-subtitle
@author author

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} year copyright-owner

Published by ...

Permission is granted to ...
@end titlepage

@node Top, Overview, , (dir)

@ifinfo
This document describes ...

This document applies to version ...
of the program named ...
@end ifinfo

@menu
* Copying::          Your rights and freedoms.
* First Chapter::    Getting started ...
* Second Chapter::              ...
  ...
  ...
@end menu

@node    First Chapter, Second Chapter, top,      top
@comment node-name,     next,           previous, up
@chapter First Chapter
@cindex Index entry for First Chapter

The Texinfo File Header

Texinfo files start with at least three lines that provide Info and TeX with necessary information. These are the \input texinfo line, the @settitle line, and the @setfilename line. If you want to run TeX on just a part of the Texinfo File, you must write the @settitle and @setfilename lines between start-of-header and end-of-header lines.

Thus, the beginning of a Texinfo file looks like this:

\input texinfo   @c -*-texinfo-*-
@setfilename sample.info
@settitle Sample Document

or else like this:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header

The First Line of a Texinfo File

Every Texinfo file that is to be the top-level input to TeX must begin with a line that looks like this:

\input texinfo   @c -*-texinfo-*-

This line serves two functions:

  1. When the file is processed by TeX, the `\input texinfo' command tells TeX to load the macros needed for processing a Texinfo file. These are in a file called `texinfo.tex', which is usually located in the `/usr/lib/tex/macros' directory. TeX uses the backslash, `\', to mark the beginning of a command, just as Texinfo uses `@'. The `texinfo.tex' file causes the switch from `\' to `@'; before the switch occurs, TeX requires `\', which is why it appears at the beginning of the file.
  2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode specification tells Emacs to use Texinfo mode.

Start of Header

Write a start-of-header line on the second line of a Texinfo file. Follow the start-of-header line with @setfilename and @settitle lines and, optionally, with other command lines, such as @smallbook or @footnotestyle; and then by an end-of-header line (see section End of Header).

With these lines, you can format part of a Texinfo file for Info or typeset part for printing.

A start-of-header line looks like this:

@c %**start of header

The odd string of characters, `%**', is to ensure that no other comment is accidentally taken for a start-of-header line.

@setfilename

In order to serve as the primary input file for either makeinfo or TeX, a Texinfo file must contain a line that looks like this:

@setfilename info-file-name

Write the @setfilename command at the beginning of a line and follow it on the same line by the Info file name. Do not write anything else on the line; anything on the line after the command is considered part of the file name, including what would otherwise be a comment.

The @setfilename line specifies the name of the output file to be generated. This name should be different from the name of the Texinfo file. There are two conventions for choosing the name: you can either remove the extension (such as `.texi') from the input file name, or replace it with the `.info' extension. When producing HTML output, makeinfo will replace any extension with `html', or add `.html' if the given name has no extension.

Some operating systems cannot handle long file names. You can run into a problem even when the file name you specify is itself short enough. This occurs because the Info formatters split a long Info file into short indirect subfiles, and name them by appending `-1', `-2', ..., `-10', `-11', and so on, to the original file name. (See section Tag Files and Split Files.) The subfile name `texinfo.info-10', for example, is too long for some systems; so the Info file name for this document is `texinfo' rather than `texinfo.info'. When makeinfo is running on operating systems such as MS-DOS which impose grave limits on file names, it will sometimes remove some characters from the original file name to leave enough space for the subfile suffix, thus producing files named `texin-10', `gcc.i12', etc.

The Info formatting commands ignore everything written before the @setfilename line, which is why the very first line of the file (the \input line) does not show up in the output.

The @setfilename line produces no output when you typeset a manual with TeX, but it is nevertheless essential: it opens the index, cross-reference, and other auxiliary files used by Texinfo, and also reads `texinfo.cnf' if that file is present on your system (see section Preparing for TeX).

@settitle

In order to be made into a printed manual, a Texinfo file must contain a line that looks like this:

@settitle title

Write the @settitle command at the beginning of a line and follow it on the same line by the title. This tells TeX the title to use in a header or footer. Do not write anything else on the line; anything on the line after the command is considered part of the title, including a comment.

Conventionally, when TeX formats a Texinfo file for double-sided output, the title is printed in the left-hand (even-numbered) page headings and the current chapter title is printed in the right-hand (odd-numbered) page headings. (TeX learns the title of each chapter from each @chapter command.) Page footers are not printed.

Even if you are printing in a single-sided style, TeX looks for an @settitle command line, in case you include the manual title in the heading.

The @settitle command should precede everything that generates actual output in TeX.

Although the title in the @settitle command is usually the same as the title on the title page, it does not affect the title as it appears on the title page. Thus, the two do not need not match exactly; and the title in the @settitle command can be a shortened or expanded version of the title as it appears on the title page. (See section @titlepage.)

TeX prints page headings only for that text that comes after the @end titlepage command in the Texinfo file, or that comes after an @headings command that turns on headings. (See section The @headings Command, for more information.)

You may, if you wish, create your own, customized headings and footings. See section Page Headings, for a detailed discussion of this process.

@setchapternewpage

In an officially bound book, text is usually printed on both sides of the paper, chapters start on right-hand pages, and right-hand pages have odd numbers. But in short reports, text often is printed only on one side of the paper. Also in short reports, chapters sometimes do not start on new pages, but are printed on the same page as the end of the preceding chapter, after a small amount of vertical whitespace.

You can use the @setchapternewpage command with various arguments to specify how TeX should start chapters and whether it should format headers for printing on one or both sides of the paper (single-sided or double-sided printing).

Write the @setchapternewpage command at the beginning of a line followed by its argument.

For example, you would write the following to cause each chapter to start on a fresh odd-numbered page:

@setchapternewpage odd

You can specify one of three alternatives with the @setchapternewpage command:

@setchapternewpage off
Cause TeX to typeset a new chapter on the same page as the last chapter, after skipping some vertical whitespace. Also, cause TeX to format page headers for single-sided printing. (You can override the headers format with the @headings double command; see section The @headings Command.)
@setchapternewpage on
Cause TeX to start new chapters on new pages and to format page headers for single-sided printing. This is the form most often used for short reports or personal printing. This alternative is the default.
@setchapternewpage odd
Cause TeX to start new chapters on new, odd-numbered pages (right-handed pages) and to typeset for double-sided printing. This is the form most often used for books and manuals.

Texinfo does not have an @setchapternewpage even command.

You can countermand or modify the effect on headers of an @setchapternewpage command with an @headings command. See section The @headings Command.

At the beginning of a manual or book, pages are not numbered--for example, the title and copyright pages of a book are not numbered. By convention, table of contents pages are numbered with roman numerals and not in sequence with the rest of the document.

Since an Info file does not have pages, the @setchapternewpage command has no effect on it.

We recommend not including any @setchapternewpage command in your manual sources at all, since the desired output is not intrinsic to the document. Instead, if you don't want the default option (no blank pages, same headers on all pages) use the @option{--texinfo} option to @command{texi2dvi} to specify the output you want.

Paragraph Indenting

The Texinfo processors may insert whitespace at the beginning of the first line of each paragraph, thereby indenting that paragraph. You can use the @paragraphindent command to specify this indentation. Write an @paragraphindent command at the beginning of a line followed by either `asis' or a number:

@paragraphindent indent

The indentation is according to the value of indent:

asis
Do not change the existing indentation (not implemented in TeX).
0
Omit all indentation.
n
Indent by n space characters in Info output, by n ems in TeX.

The default value of indent is `asis'. @paragraphindent is ignored for HTML output.

Write the @paragraphindent command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you write the command between the start-of-header and end-of-header lines, the region formatting commands indent paragraphs as specified.)

A peculiarity of the texinfo-format-buffer and texinfo-format-region commands is that they do not indent (nor fill) paragraphs that contain @w or @* commands. See section Refilling Paragraphs, for further information.

@exampleindent: Environment Indenting

The Texinfo processors indent each line of @example and similar environments. You can use the @exampleindent command to specify this indentation. Write an @exampleindent command at the beginning of a line followed by either `asis' or a number:

@exampleindent indent

The indentation is according to the value of indent:

asis
Do not change the existing indentation (not implemented in TeX).
0
Omit all indentation.
n
Indent environments by n space characters in Info output, by n ems in TeX.

The default value of indent is 5. @exampleindent is ignored for HTML output.

Write the @exampleindent command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you write the command between the start-of-header and end-of-header lines, the region formatting commands indent examples as specified.)

End of Header

Follow the header lines with an end-of-header line. An end-of-header line looks like this:

@c %**end of header

If you include the @setchapternewpage command between the start-of-header and end-of-header lines, TeX will typeset a region as that command specifies. Similarly, if you include an @smallbook command between the start-of-header and end-of-header lines, TeX will typeset a region in the "small" book format.

See section Start of Header.

Summary and Copying Permissions for Info

The title page and the copyright page appear only in the printed copy of the manual; therefore, the same information must be inserted in a section that appears only in the Info file. This section usually contains a brief description of the contents of the Info file, a copyright notice, and copying permissions.

The copyright notice should read:

Copyright year copyright-owner

and be put on a line by itself.

Standard text for the copyright permissions is contained in an appendix to this manual; see section `ifinfo' Copying Permissions, for the complete text.

The permissions text appears in an Info file before the first node. This mean that a reader does not see this text when reading the file using Info, except when using the advanced Info command g *.

The Title and Copyright Pages

A manual's name and author are usually printed on a title page. Sometimes copyright information is printed on the title page as well; more often, copyright information is printed on the back of the title page.

The title and copyright pages appear in the printed manual, but not in the Info file. Because of this, it is possible to use several slightly obscure TeX typesetting commands that cannot be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual.

You may wish to include titlepage-like information for plain text output. Simply place any such leading material between @ifinfo and @end ifinfo; @command{makeinfo} includes this in its plain text output. It will not show up in the Info readers.

See section Titlepage Copying Permissions, for the standard text for the copyright permissions.

@titlepage

Start the material for the title page and following copyright page with @titlepage on a line by itself and end it with @end titlepage on a line by itself.

The @end titlepage command starts a new page and turns on page numbering. (See section Page Headings, for details about how to generate page headings.) All the material that you want to appear on unnumbered pages should be put between the @titlepage and @end titlepage commands. You can force the table of contents to appear there with the @setcontentsaftertitlepage command (see section Generating a Table of Contents).

By using the @page command you can force a page break within the region delineated by the @titlepage and @end titlepage commands and thereby create more than one unnumbered page. This is how the copyright page is produced. (The @titlepage command might perhaps have been better named the @titleandadditionalpages command, but that would have been rather long!)

When you write a manual about a computer program, you should write the version of the program to which the manual applies on the title page. If the manual changes more frequently than the program or is independent of it, you should also include an edition number(5) for the manual. This helps readers keep track of which manual is for which version of the program. (The `Top' node should also contain this information; see section @top.)

Texinfo provides two main methods for creating a title page. One method uses the @titlefont, @sp, and @center commands to generate a title page in which the words on the page are centered.

The second method uses the @title, @subtitle, and @author commands to create a title page with black rules under the title and author lines and the subtitle text set flush to the right hand side of the page. With this method, you do not specify any of the actual formatting of the title page. You specify the text you want, and Texinfo does the formatting.

You may use either method, or you may combine them; see the examples in the sections below.

For extremely simple applications, and for the bastard title page in traditional book front matter, Texinfo also provides a command @shorttitlepage which takes a single argument as the title. The argument is typeset on a page by itself and followed by a blank page.

@titlefont, @center, and @sp

You can use the @titlefont, @sp, and @center commands to create a title page for a printed document. (This is the first of the two methods for creating a title page in Texinfo.)

Use the @titlefont command to select a large font suitable for the title itself. You can use @titlefont more than once if you have an especially long title.

For example:

@titlefont{Texinfo}

Use the @center command at the beginning of a line to center the remaining text on that line. Thus,

@center @titlefont{Texinfo}

centers the title, which in this example is "Texinfo" printed in the title font.

Use the @sp command to insert vertical space. For example:

@sp 2

This inserts two blank lines on the printed page. (See section @sp n: Insert Blank Lines, for more information about the @sp command.)

A template for this method looks like this:

@titlepage
@sp 10
@center @titlefont{name-of-manual-when-printed}
@sp 2
@center subtitle-if-any
@sp 2
@center author
...
@end titlepage

The spacing of the example fits an 8.5 by 11 inch manual.

@title, @subtitle, and @author

You can use the @title, @subtitle, and @author commands to create a title page in which the vertical and horizontal spacing is done for you automatically. This contrasts with the method described in the previous section, in which the @sp command is needed to adjust vertical spacing.

Write the @title, @subtitle, or @author commands at the beginning of a line followed by the title, subtitle, or author.

The @title command produces a line in which the title is set flush to the left-hand side of the page in a larger than normal font. The title is underlined with a black rule. Only a single line is allowed; the @* command may not be used to break the title into two lines. To handle very long titles, you may find it profitable to use both @title and @titlefont; see the final example in this section.

The @subtitle command sets subtitles in a normal-sized font flush to the right-hand side of the page.

The @author command sets the names of the author or authors in a middle-sized font flush to the left-hand side of the page on a line near the bottom of the title page. The names are underlined with a black rule that is thinner than the rule that underlines the title. (The black rule only occurs if the @author command line is followed by an @page command line.)

There are two ways to use the @author command: you can write the name or names on the remaining part of the line that starts with an @author command:

@author by Jane Smith and John Doe

or you can write the names one above each other by using two (or more) @author commands:

@author Jane Smith
@author John Doe

(Only the bottom name is underlined with a black rule.)

A template for this method looks like this:

@titlepage
@title name-of-manual-when-printed
@subtitle subtitle-if-any
@subtitle second-subtitle
@author author
@page
...
@end titlepage

You may also combine the @titlefont method described in the previous section and @title method described in this one. This may be useful if you have a very long title. Here is a real-life example:

@titlepage
@titlefont{GNU Software}
@sp 1
@title for MS-Windows and MS-DOS
@subtitle Edition @value{edition} for Release @value{cd-edition}
@author by Daniel Hagerty, Melissa Weisshaus
@author and Eli Zaretskii

(The use of @value here is explained in section @value Example.)

Copyright Page and Permissions

By international treaty, the copyright notice for a book should be either on the title page or on the back of the title page. The copyright notice should include the year followed by the name of the organization or person who owns the copyright.

When the copyright notice is on the back of the title page, that page is customarily not numbered. Therefore, in Texinfo, the information on the copyright page should be within @titlepage and @end titlepage commands.

Use the @page command to cause a page break. To push the copyright notice and the other text on the copyright page towards the bottom of the page, you can write a somewhat mysterious line after the @page command that reads like this:

@vskip 0pt plus 1filll

This is a TeX command that is not supported by the Info formatting commands. The @vskip command inserts whitespace. The `0pt plus 1filll' means to put in zero points of mandatory whitespace, and as much optional whitespace as needed to push the following text to the bottom of the page. Note the use of three `l's in the word `filll'; this is the correct usage in TeX.

In a printed manual, the @copyright{} command generates a `c' inside a circle. (In Info, it generates `(C)'.) The copyright notice itself has the following legally defined sequence:

Copyright © year copyright-owner

It is customary to put information on how to get a manual after the copyright notice, followed by the copying permissions for the manual.

Permissions must be given here as well as in the summary segment within @ifinfo and @end ifinfo that immediately follows the header since this text appears only in the printed manual and the `ifinfo' text appears only in the Info file.

See section Sample Permissions, for the standard text.

Heading Generation

An @end titlepage command on a line by itself not only marks the end of the title and copyright pages, but also causes TeX to start generating page headings and page numbers.

To repeat what is said elsewhere, Texinfo has two standard page heading formats, one for documents which are printed on one side of each sheet of paper (single-sided printing), and the other for documents which are printed on both sides of each sheet (double-sided printing). (See section @setchapternewpage.) You can specify these formats in different ways:

  • The conventional way is to write an @setchapternewpage command before the title page commands, and then have the @end titlepage command start generating page headings in the manner desired. (See section @setchapternewpage.)
  • Alternatively, you can use the @headings command to prevent page headings from being generated or to start them for either single or double-sided printing. (Write an @headings command immediately after the @end titlepage command. See section The @headings Command, for more information.)
  • Or, you may specify your own page heading and footing format. See section Page Headings, for detailed information about page headings and footings.

Most documents are formatted with the standard single-sided or double-sided format, using @setchapternewpage odd for double-sided printing and no @setchapternewpage command for single-sided printing.

The @headings Command

The @headings command is rarely used. It specifies what kind of page headings and footings to print on each page. Usually, this is controlled by the @setchapternewpage command. You need the @headings command only if the @setchapternewpage command does not do what you want, or if you want to turn off pre-defined page headings prior to defining your own. Write an @headings command immediately after the @end titlepage command.

You can use @headings as follows:

@headings off
Turn off printing of page headings.
@headings single
Turn on page headings appropriate for single-sided printing.
@headings double
@headings on
Turn on page headings appropriate for double-sided printing. The two commands, @headings on and @headings double, are synonymous.
@headings singleafter
@headings doubleafter
Turn on single or double headings, respectively, after the current page is output.
@headings on
Turn on page headings: single if `@setchapternewpage on', double otherwise.

For example, suppose you write @setchapternewpage off before the @titlepage command to tell TeX to start a new chapter on the same page as the end of the last chapter. This command also causes TeX to typeset page headers for single-sided printing. To cause TeX to typeset for double sided printing, write @headings double after the @end titlepage command.

You can stop TeX from generating any page headings at all by writing @headings off on a line of its own immediately after the line containing the @end titlepage command, like this:

@end titlepage
@headings off

The @headings off command overrides the @end titlepage command, which would otherwise cause TeX to print page headings.

You can also specify your own style of page heading and footing. See section Page Headings, for more information.

The `Top' Node and Master Menu

The `Top' node is the node from which you enter an Info file.

A `Top' node should contain a brief description of the Info file and an extensive, master menu for the whole Info file. This helps the reader understand what the Info file is about. Also, you should write the version number of the program to which the Info file applies; or, at least, the edition number.

The contents of the `Top' node should appear only in the Info file; none of it should appear in printed output, so enclose it between @ifinfo and @end ifinfo commands. (TeX does not print either an @node line or a menu; they appear only in Info; strictly speaking, you are not required to enclose these parts between @ifinfo and @end ifinfo, but it is simplest to do so. See section Conditionally Visible Text.)

`Top' Node Title

Sometimes, you will want to place an @top sectioning command line containing the title of the document immediately after the @node Top line (see section The @top Sectioning Command, for more information).

For example, the beginning of the Top node of this manual contains an @top sectioning command, a short description, and edition and version information. It looks like this:

...
@end titlepage

@ifnottex
@node Top, Copying, , (dir)
@top Texinfo

Texinfo is a documentation system...

This is edition...
...
@end ifnottex

@menu
* Copying::                 Texinfo is freely
                              redistributable.
* Overview::                What is Texinfo?
...
@end menu

In a `Top' node, the `Previous', and `Up' nodes usually refer to the top level directory of the whole Info system, which is called `(dir)'. The `Next' node refers to the first node that follows the main or master menu, which is usually the copying permissions, introduction, or first chapter.

Parts of a Master Menu

A master menu is a detailed main menu listing all the nodes in a file.

A master menu is enclosed in @menu and @end menu commands and does not appear in the printed document.

Generally, a master menu is divided into parts.

  • The first part contains the major nodes in the Texinfo file: the nodes for the chapters, chapter-like sections, and the appendices.
  • The second part contains nodes for the indices.
  • The third and subsequent parts contain a listing of the other, lower level nodes, often ordered by chapter. This way, rather than go through an intermediary menu, an inquirer can go directly to a particular node when searching for specific information. These menu items are not required; add them if you think they are a convenience. If you do use them, put @detailmenu before the first one, and @end detailmenu after the last; otherwise, makeinfo will get confused.

Each section in the menu can be introduced by a descriptive line. So long as the line does not begin with an asterisk, it will not be treated as a menu entry. (See section Writing a Menu, for more information.)

For example, the master menu for this manual looks like the following (but has many more entries):

@menu
* Copying::             Texinfo is freely
                          redistributable.
* Overview::            What is Texinfo?
* Texinfo Mode::        Special features in GNU Emacs.
...
...
* Command and Variable Index::
                        An entry for each @-command.
* Concept Index::       An entry for each concept.

@detailmenu
 -- The Detailed Node Listing ---

Overview of Texinfo

* Info Files::          What is an Info file?
* Printed Manuals::     Characteristics of
                          a printed manual.
...
...

Using Texinfo Mode

* Info on a Region::    Formatting part of a file
                          for Info.
...
...
@end detailmenu
@end menu

Software Copying Permissions

If the Texinfo file has a section containing the "General Public License" and the distribution information and a warranty disclaimer for the software that is documented, this section usually follows the `Top' node. The General Public License is very important to Project GNU software. It ensures that you and others will continue to have a right to use and share the software.

The copying and distribution information and the disclaimer are followed by an introduction or else by the first chapter of the manual.

Although an introduction is not a required part of a Texinfo file, it is very helpful. Ideally, it should state clearly and concisely what the file is about and who would be interested in reading it. In general, an introduction would follow the licensing and distribution information, although sometimes people put it earlier in the document. Usually, an introduction is put in an @unnumbered section. (See section @unnumbered and @appendix.)

Ending a Texinfo File

The end of a Texinfo file should include commands to create indices and (usually) to generate detailed and summary tables of contents. And it must include the @bye command that marks the last line processed by TeX.

For example:

@node    Concept Index,     , Variables Index, Top
@c        node-name,    next, previous,        up
@unnumbered Concept Index

@printindex cp

@contents
@bye

Index Menus and Printing an Index

To print an index means to include it as part of a manual or Info file. This does not happen automatically just because you use @cindex or other index-entry generating commands in the Texinfo file; those just cause the raw data for the index to be accumulated. To generate an index, you must include the @printindex command at the place in the document where you want the index to appear. Also, as part of the process of creating a printed manual, you must run a program called texindex (see section Formatting and Printing Hardcopy) to sort the raw data to produce a sorted index file. The sorted index file is what is actually used to print the index.

Texinfo offers six different types of predefined index: the concept index, the function index, the variables index, the keystroke index, the program index, and the data type index (see section Predefined Indices). Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg', and `tp'. You may merge indices, or put them into separate sections (see section Combining Indices); or you may define your own indices (see section Defining New Indices).

The @printindex command takes a two-letter index name, reads the corresponding sorted index file and formats it appropriately into an index.

The @printindex command does not generate a chapter heading for the index. Consequently, you should precede the @printindex command with a suitable section or chapter command (usually @unnumbered) to supply the chapter heading and put the index into the table of contents. Precede the @unnumbered command with an @node line.

For example:

@node Variable Index, Concept Index, Function Index, Top
@comment    node-name,         next,       previous, up
@unnumbered Variable Index

@printindex vr

@node     Concept Index,     , Variable Index, Top
@comment      node-name, next,       previous, up
@unnumbered Concept Index

@printindex cp

Readers often prefer that the concept index come last in a book, since that makes it easiest to find. Having just one index helps readers also, since then they have only one place to look (see section @synindex).

Generating a Table of Contents

The @chapter, @section, and other structuring commands supply the information to make up a table of contents, but they do not cause an actual table to appear in the manual. To do this, you must use the @contents and/or @summarycontents command(s).

@contents
Generate a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. (Headings generated by the @heading series of commands do not appear in the table of contents.)
@shortcontents
@summarycontents
(@summarycontents is a synonym for @shortcontents; the two commands are exactly the same.) Generate a short or summary table of contents that lists only the chapters (and appendices and unnumbered chapters). Omit sections, subsections and subsubsections. Only a long manual needs a short table of contents in addition to the full table of contents.

Both contents commands should be written on a line by themselves. The contents commands automatically generate a chapter-like heading at the top of the first table of contents page, so don't include any sectioning command such as @unnumbered before them.

Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the contents commands. But the contents are included in plain text output (generated by makeinfo --no-headers).

The contents commands can be placed either at the very end of the file, after any indices (see the previous section) and just before the @bye (see the next section), or near the beginning of the file, after the @end titlepage (see section @titlepage). The advantage to the former is that then the contents output is always up to date, because it reflects the processing just done. The advantage to the latter is that the contents are printed in the proper place, thus you do not need to rearrange the DVI file with @command{dviselect} or shuffle paper. However, contents commands at the beginning of the document are ignored when outputting to standard output.

As an author, you can put the contents commands wherever you prefer. But if you are a user simply printing a manual, you may wish to print the contents after the title page even if the author put the contents commands at the end of the document (as is the case in most existing Texinfo documents). You can do this by specifying @setcontentsaftertitlepage and/or @setshortcontentsaftertitlepage. The first prints only the main contents after the @end titlepage; the second prints both the short contents and the main contents. In either case, any subsequent @contents or @shortcontents is ignored (unless no @end titlepage is ever encountered).

You need to include the @set...contentsaftertitlepage commands early in the document (just after @setfilename, for example). Or, if you're using @command{texi2dvi} (see section Format with @code{texi2dvi}), you can use its @option{--texinfo} option to specify this without altering the source file at all. For example:

texi2dvi --texinfo=@setshortcontentsaftertitlepage foo.texi

@bye File Ending

An @bye command terminates TeX or Info formatting. None of the formatting commands see any of the file following @bye. The @bye command should be on a line by itself.

If you wish, you may follow the @bye line with notes. These notes will not be formatted and will not appear in either Info or a printed manual; it is as if text after @bye were within @ignore ... @end ignore. Also, you may follow the @bye line with a local variables list. See section Using the Local Variables List, for more information.

Chapter Structuring

The chapter structuring commands divide a document into a hierarchy of chapters, sections, subsections, and subsubsections. These commands generate large headings; they also provide information for the table of contents of a printed manual (see section Generating a Table of Contents).

The chapter structuring commands do not create an Info node structure, so normally you should put an @node command immediately before each chapter structuring command (see section Nodes). The only time you are likely to use the chapter structuring commands without using the node structuring commands is if you are writing a document that contains no cross references and will never be transformed into Info format.

It is unlikely that you will ever write a Texinfo file that is intended only as an Info file and not as a printable document. If you do, you might still use chapter structuring commands to create a heading at the top of each node--but you don't need to.

Tree Structure of Sections

A Texinfo file is usually structured like a book with chapters, sections, subsections, and the like. This structure can be visualized as a tree (or rather as an upside-down tree) with the root at the top and the levels corresponding to chapters, sections, subsection, and subsubsections.

Here is a diagram that shows a Texinfo file with three chapters, each of which has two sections.

                          Top
                           |
         -------------------------------------
        |                  |                  |
     Chapter 1          Chapter 2          Chapter 3
        |                  |                  |
     --------           --------           --------
    |        |         |        |         |        |
 Section  Section   Section  Section   Section  Section
   1.1      1.2       2.1      2.2       3.1      3.2

In a Texinfo file that has this structure, the beginning of Chapter 2 looks like this:

@node    Chapter 2,  Chapter 3, Chapter 1, top
@chapter Chapter 2

The chapter structuring commands are described in the sections that follow; the @node and @menu commands are described in following chapters. (See section Nodes, and see section Menus.)

Structuring Command Types

The chapter structuring commands fall into four groups or series, each of which contains structuring commands corresponding to the hierarchical levels of chapters, sections, subsections, and subsubsections.

The four groups are the @chapter series, the @unnumbered series, the @appendix series, and the @heading series.

Each command produces titles that have a different appearance on the printed page or Info file; only some of the commands produce titles that are listed in the table of contents of a printed book or manual.

  • The @chapter and @appendix series of commands produce numbered or lettered entries both in the body of a printed work and in its table of contents.
  • The @unnumbered series of commands produce unnumbered entries both in the body of a printed work and in its table of contents. The @top command, which has a special use, is a member of this series (see section @top).
  • The @heading series of commands produce unnumbered headings that do not appear in a table of contents. The heading commands never start a new page.
  • The @majorheading command produces results similar to using the @chapheading command but generates a larger vertical whitespace before the heading.
  • When an @setchapternewpage command says to do so, the @chapter, @unnumbered, and @appendix commands start new pages in the printed manual; the @heading commands do not.

Here are the four groups of chapter structuring commands:

Numbered In contents @chapter@section@subsection@subsubsection
 |  | No new page
Unnumbered | Lettered and numbered | Unnumbered
In contents | In contents | Not in contents
@top |  | @majorheading
@unnumbered | @appendix | @chapheading
@unnumberedsec | @appendixsec | @heading
@unnumberedsubsec | @appendixsubsec | @subheading
@unnumberedsubsubsec | @appendixsubsubsec | @subsubheading

@top

The @top command is a special sectioning command that you use only after an `@node Top' line at the beginning of a Texinfo file. The @top command tells the makeinfo formatter which node is the `Top' node, so it can use it as the root of the node tree if your manual uses implicit pointers. It has the same typesetting effect as @unnumbered (see section @unnumbered and @appendix). For detailed information, see section The @top Sectioning Command.

The @top node and its menu (if any) is conventionally wrapped in an @ifnottex conditional so that it will appear only in Info and HTML output, not TeX.

@chapter

@chapter identifies a chapter in the document. Write the command at the beginning of a line and follow it on the same line by the title of the chapter.

For example, this chapter in this manual is entitled "Chapter Structuring"; the @chapter line looks like this:

@chapter Chapter Structuring

In TeX, the @chapter command creates a chapter in the document, specifying the chapter title. The chapter is numbered automatically.

In Info, the @chapter command causes the title to appear on a line by itself, with a line of asterisks inserted underneath. Thus, in Info, the above example produces the following output:

Chapter Structuring
*******************

Texinfo also provides a command @centerchap, which is analogous to @unnumbered, but centers its argument in the printed output. This kind of stylistic choice is not usually offered by Texinfo.

@unnumbered and @appendix

Use the @unnumbered command to create a chapter that appears in a printed manual without chapter numbers of any kind. Use the @appendix command to create an appendix in a printed manual that is labelled by letter instead of by number.

For Info file output, the @unnumbered and @appendix commands are equivalent to @chapter: the title is printed on a line by itself with a line of asterisks underneath. (See section @chapter.)

To create an appendix or an unnumbered chapter, write an @appendix or @unnumbered command at the beginning of a line and follow it on the same line by the title, as you would if you were creating a chapter.

@majorheading, @chapheading

The @majorheading and @chapheading commands put chapter-like headings in the body of a document.

However, neither command causes TeX to produce a numbered heading or an entry in the table of contents; and neither command causes TeX to start a new page in a printed manual.

In TeX, an @majorheading command generates a larger vertical whitespace before the heading than an @chapheading command but is otherwise the same.

In Info, the @majorheading and @chapheading commands are equivalent to @chapter: the title is printed on a line by itself with a line of asterisks underneath. (See section @chapter.)

@section

In a printed manual, an @section command identifies a numbered section within a chapter. The section title appears in the table of contents. In Info, an @section command provides a title for a segment of text, underlined with `='.

This section is headed with an @section command and looks like this in the Texinfo file:

@section @code{@@section}

To create a section, write the @section command at the beginning of a line and follow it on the same line by the section title.

Thus,

@section This is a section

produces

This is a section
=================

in Info.

@unnumberedsec, @appendixsec, @heading

The @unnumberedsec, @appendixsec, and @heading commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the @section command. (See section @section.)

@unnumberedsec
The @unnumberedsec command may be used within an unnumbered chapter or within a regular chapter or appendix to provide an unnumbered section.
@appendixsec
@appendixsection
@appendixsection is a longer spelling of the @appendixsec command; the two are synonymous. Conventionally, the @appendixsec or @appendixsection command is used only within appendices.
@heading
You may use the @heading command anywhere you wish for a section-style heading that will not appear in the table of contents.

The @subsection Command

Subsections are to sections as sections are to chapters. (See section @section.) In Info, subsection titles are underlined with `-'. For example,

@subsection This is a subsection

produces

This is a subsection
--------------------

In a printed manual, subsections are listed in the table of contents and are numbered three levels deep.

The @subsection-like Commands

The @unnumberedsubsec, @appendixsubsec, and @subheading commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the @subsection command. (See section The @subsection Command.)

In Info, the @subsection-like commands generate a title underlined with hyphens. In a printed manual, an @subheading command produces a heading like that of a subsection except that it is not numbered and does not appear in the table of contents. Similarly, an @unnumberedsubsec command produces an unnumbered heading like that of a subsection and an @appendixsubsec command produces a subsection-like heading labelled with a letter and numbers; both of these commands produce headings that appear in the table of contents.

The `subsub' Commands

The fourth and lowest level sectioning commands in Texinfo are the `subsub' commands. They are:

@subsubsection
Subsubsections are to subsections as subsections are to sections. (See section The @subsection Command.) In a printed manual, subsubsection titles appear in the table of contents and are numbered four levels deep.
@unnumberedsubsubsec
Unnumbered subsubsection titles appear in the table of contents of a printed manual, but lack numbers. Otherwise, unnumbered subsubsections are the same as subsubsections. In Info, unnumbered subsubsections look exactly like ordinary subsubsections.
@appendixsubsubsec
Conventionally, appendix commands are used only for appendices and are lettered and numbered appropriately in a printed manual. They also appear in the table of contents. In Info, appendix subsubsections look exactly like ordinary subsubsections.
@subsubheading
The @subsubheading command may be used anywhere that you need a small heading that will not appear in the table of contents. In Info, subsubheadings look exactly like ordinary subsubsection headings.

In Info, `subsub' titles are underlined with periods. For example,

@subsubsection This is a subsubsection

produces

This is a subsubsection
.......................

@raisesections and @lowersections

The @raisesections and @lowersections commands raise and lower the hierarchical level of chapters, sections, subsections and the like. The @raisesections command changes sections to chapters, subsections to sections, and so on. The @lowersections command changes chapters to sections, sections to subsections, and so on.

An @lowersections command is useful if you wish to include text that is written as an outer or standalone Texinfo file in another Texinfo file as an inner, included file. If you write the command at the beginning of the file, all your @chapter commands are formatted as if they were @section commands, all your @section command are formatted as if they were @subsection commands, and so on.

@raisesections raises a command one level in the chapter structuring hierarchy:

  Change           To

@subsection     @section,
@section        @chapter,
@heading        @chapheading,
          etc.

@lowersections lowers a command one level in the chapter structuring hierarchy:

  Change           To

@chapter        @section,
@subsection     @subsubsection,
@heading        @subheading,
          etc.

An @raisesections or @lowersections command changes only those structuring commands that follow the command in the Texinfo file. Write an @raisesections or @lowersections command on a line of its own.

An @lowersections command cancels an @raisesections command, and vice versa. Typically, the commands are used like this:

@lowersections
@include somefile.texi
@raisesections

Without the @raisesections, all the subsequent sections in your document will be lowered.

Repeated use of the commands continue to raise or lower the hierarchical level a step at a time.

An attempt to raise above `chapters' reproduces chapter commands; an attempt to lower below `subsubsections' reproduces subsubsection commands.

Nodes

Nodes are the primary segments of a Texinfo file. They do not themselves impose a hierarchical or any other kind of structure on a file. Nodes contain node pointers that name other nodes, and can contain menus which are lists of nodes. In Info, the movement commands can carry you to a pointed-to node or to a node listed in a menu. Node pointers and menus provide structure for Info files just as chapters, sections, subsections, and the like, provide structure for printed books.

Two Paths

The node and menu commands and the chapter structuring commands are technically independent of each other:

  • In Info, node and menu commands provide structure. The chapter structuring commands generate headings with different kinds of underlining--asterisks for chapters, hyphens for sections, and so on; they do nothing else.
  • In TeX, the chapter structuring commands generate chapter and section numbers and tables of contents. The node and menu commands provide information for cross references; they do nothing else.

You can use node pointers and menus to structure an Info file any way you want; and you can write a Texinfo file so that its Info output has a different structure than its printed output. However, virtually all Texinfo files are written such that the structure for the Info output corresponds to the structure for the printed output. It is neither convenient nor understandable to the reader to do otherwise.

Generally, printed output is structured in a tree-like hierarchy in which the chapters are the major limbs from which the sections branch out. Similarly, node pointers and menus are organized to create a matching structure in the Info output.

Node and Menu Illustration

Here is a copy of the diagram shown earlier that illustrates a Texinfo file with three chapters, each of which contains two sections.

The "root" is at the top of the diagram and the "leaves" are at the bottom. This is how such a diagram is drawn conventionally; it illustrates an upside-down tree. For this reason, the root node is called the `Top' node, and `Up' node pointers carry you closer to the root.

                          Top
                           |
         -------------------------------------
        |                  |                  |
     Chapter 1          Chapter 2          Chapter 3
        |                  |                  |
     --------           --------           --------
    |        |         |        |         |        |
 Section  Section   Section  Section   Section  Section
   1.1      1.2       2.1      2.2       3.1      3.2

The fully-written command to start Chapter 2 would be this:

@node     Chapter 2,  Chapter 3, Chapter 1, Top
@comment  node-name,  next,      previous,  up

This @node line says that the name of this node is "Chapter 2", the name of the `Next' node is "Chapter 3", the name of the `Previous' node is "Chapter 1", and the name of the `Up' node is "Top". You can omit writing out these node names if your document is hierarchically organized (see section Creating Pointers with makeinfo), but the pointer relationships still obtain.

Please Note: `Next' refers to the next node at the same hierarchical level in the manual, not necessarily to the next node within the Texinfo file. In the Texinfo file, the subsequent node may be at a lower level--a section-level node most often follows a chapter-level node, for example. `Next' and `Previous' refer to nodes at the same hierarchical level. (The `Top' node contains the exception to this rule. Since the `Top' node is the only node at that level, `Next' refers to the first following node, which is almost always a chapter or chapter-level node.)

To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter 2. (See section Menus.) You would write the menu just before the beginning of Section 2.1, like this:

    @menu
    * Sect. 2.1::    Description of this section.
    * Sect. 2.2::
    @end menu

Write the node for Sect. 2.1 like this:

    @node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
    @comment  node-name, next,      previous,  up

In Info format, the `Next' and `Previous' pointers of a node usually lead to other nodes at the same level--from chapter to chapter or from section to section (sometimes, as shown, the `Previous' pointer points up); an `Up' pointer usually leads to a node at the level above (closer to the `Top' node); and a `Menu' leads to nodes at a level below (closer to `leaves'). (A cross reference can point to a node at any level; see section Cross References.)

Usually, an @node command and a chapter structuring command are used in sequence, along with indexing commands. (You may follow the @node line with a comment line that reminds you which pointer is which.)

Here is the beginning of the chapter in this manual called "Ending a Texinfo File". This shows an @node line followed by a comment line, an @chapter line, and then by indexing lines.

@node    Ending a File, Structuring, Beginning a File, Top
@comment node-name,     next,        previous,         up
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending

The @node Command

A node is a segment of text that begins at an @node command and continues until the next @node command. The definition of node is different from that for chapter or section. A chapter may contain sections and a section may contain subsections; but a node cannot contain subnodes; the text of a node continues only until the next @node command in the file. A node usually contains only one chapter structuring command, the one that follows the @node line. On the other hand, in printed output nodes are used only for cross references, so a chapter or section may contain any number of nodes. Indeed, a chapter usually contains several nodes, one for each section, subsection, and subsubsection.

To create a node, write an @node command at the beginning of a line, and follow it with up to four arguments, separated by commas, on the rest of the same line. The first argument is required; it is the name of this node. The subsequent arguments are the names of the `Next', `Previous', and `Up' pointers, in that order, and may be omitted if your Texinfo document is hierarchically organized (see section Creating Pointers with makeinfo).

You may insert spaces before each name if you wish; the spaces are ignored. You must write the name of the node and the names of the `Next', `Previous', and `Up' pointers all on the same line. Otherwise, the formatters fail. (See Info file `info', node `Top', for more information about nodes in Info.)

Usually, you write one of the chapter-structuring command lines immediately after an @node line--for example, an @section or @subsection line. (See section Structuring Command Types.)

Please note: The GNU Emacs Texinfo mode updating commands work only with Texinfo files in which @node lines are followed by chapter structuring lines. See section Updating Requirements.

TeX uses @node lines to identify the names to use for cross references. For this reason, you must write @node lines in a Texinfo file that you intend to format for printing, even if you do not intend to format it for Info. (Cross references, such as the one at the end of this sentence, are made with @xref and related commands; see section Cross References.)

Choosing Node and Pointer Names

The name of a node identifies the node. The pointers enable you to reach other nodes and consist of the names of those nodes.

Normally, a node's `Up' pointer contains the name of the node whose menu mentions that node. The node's `Next' pointer contains the name of the node that follows that node in that menu and its `Previous' pointer contains the name of the node that precedes it in that menu. When a node's `Previous' node is the same as its `Up' node, both node pointers name the same node.

Usually, the first node of a Texinfo file is the `Top' node, and its `Up' and `Previous' pointers point to the `dir' file, which contains the main menu for all of Info.

The `Top' node itself contains the main or master menu for the manual. Also, it is helpful to include a brief description of the manual in the `Top' node. See section The First Node, for information on how to write the first node of a Texinfo file.

Even when you explicitly specify all pointers, that does not mean you can write the nodes in the Texinfo source file in an arbitrary order! Because TeX processes the file sequentially, irrespective of node pointers, you must write the nodes in the order you wish them to appear in the printed output.

How to Write an @node Line

The easiest way to write an @node line is to write @node at the beginning of a line and then the name of the node, like this:

@node node-name

If you are using GNU Emacs, you can use the update node commands provided by Texinfo mode to insert the names of the pointers; or you can leave the pointers out of the Texinfo file and let makeinfo insert node pointers into the Info file it creates. (See section Using Texinfo Mode, and section Creating Pointers with makeinfo.)

Alternatively, you can insert the `Next', `Previous', and `Up' pointers yourself. If you do this, you may find it helpful to use the Texinfo mode keyboard command C-c C-c n. This command inserts `@node' and a comment line listing the names of the pointers in their proper order. The comment line helps you keep track of which arguments are for which pointers. This comment line is especially useful if you are not familiar with Texinfo.

The template for a fully-written-out node line with `Next', `Previous', and `Up' pointers looks like this:

@node node-name, next, previous, up

If you wish, you can ignore @node lines altogether in your first draft and then use the texinfo-insert-node-lines command to create @node lines for you. However, we do not recommend this practice. It is better to name the node itself at the same time that you write a segment so you can easily make cross references. A large number of cross references are an especially important feature of a good Info file.

After you have inserted an @node line, you should immediately write an @-command for the chapter or section and insert its name. Next (and this is important!), put in several index entries. Usually, you will find at least two and often as many as four or five ways of referring to the node in the index. Use them all. This will make it much easier for people to find the node.

@node Line Tips

Here are three suggestions:

  • Try to pick node names that are informative but short. In the Info file, the file name, node name, and pointer names are all inserted on one line, which may run into the right edge of the window. (This does not cause a problem with Info, but is ugly.)
  • Try to pick node names that differ from each other near the beginnings of their names. This way, it is easy to use automatic name completion in Info.
  • By convention, node names are capitalized just as they would be for section or chapter titles--initial and significant words are capitalized; others are not.

@node Line Requirements

Here are several requirements for @node lines:

  • All the node names for a single Info file must be unique. Duplicates confuse the Info movement commands. This means, for example, that if you end every chapter with a summary, you must name each summary node differently. You cannot just call each one "Summary". You may, however, duplicate the titles of chapters, sections, and the like. Thus you can end each chapter in a book with a section called "Summary", so long as the node names for those sections are all different.
  • A pointer name must be the name of a node. The node to which a pointer points may come before or after the node containing the pointer.
  • @-commands used in node names generally confuse Info, so you should avoid them. For a few rare cases when this is useful, Texinfo has limited support for using @-commands in node names; see section Pointer Validation. Thus, the beginning of the section called @chapter looks like this:
    @node  chapter, unnumbered & appendix, makeinfo top, Structuring
@comment  node-name,  next,  previous,  up
@section @code{@@chapter}
@findex chapter
  • Unfortunately, you cannot use periods, commas, colons or apostrophes within a node name; these confuse TeX or the Info formatters. For example, the following is a section title:
    @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
    The corresponding node name is:
    unnumberedsec appendixsec heading
  • Case is significant.

The First Node

The first node of a Texinfo file is the Top node, except in an included file (see section Include Files). The Top node contains the main or master menu for the document, and a short summary of the document (see section The `Top' Node Summary).

The Top node (which must be named `top' or `Top') should have as its `Up' node the name of a node in another file, where there is a menu that leads to this file. Specify the file name in parentheses. If the file is to be installed directly in the Info directory file, use `(dir)' as the parent of the Top node; this is short for `(dir)top', and specifies the Top node in the `dir' file, which contains the main menu for the Info system as a whole. For example, the @node Top line of this manual looks like this:

@node Top, Copying, , (dir)

(You can use the Texinfo updating commands or the makeinfo utility to insert these pointers automatically.)

Do not define the `Previous' node of the Top node to be `(dir)', as it causes confusing behavior for users: if you are in the Top node and hits DEL to go backwards, you wind up in the middle of the some other entry in the `dir' file, which has nothing to do with what you were reading.

See section Installing an Info File, for more information about installing an Info file in the `info' directory.

The @top Sectioning Command

A special sectioning command, @top, has been created for use with the @node Top line. The @top sectioning command tells makeinfo that it marks the `Top' node in the file. It provides the information that makeinfo needs to insert node pointers automatically. Write the @top command at the beginning of the line immediately following the @node Top line. Write the title on the remaining part of the same line as the @top command.

In Info, the @top sectioning command causes the title to appear on a line by itself, with a line of asterisks inserted underneath.

In TeX and texinfo-format-buffer, the @top sectioning command is merely a synonym for @unnumbered. Neither of these formatters require an @top command, and do nothing special with it. You can use @chapter or @unnumbered after the @node Top line when you use these formatters. Also, you can use @chapter or @unnumbered when you use the Texinfo updating commands to create or update pointers and menus.

The `Top' Node Summary

You can help readers by writing a summary in the `Top' node, after the @top line, before the main or master menu. The summary should briefly describe the document. In Info, this summary will appear just before the master menu. In a printed manual, this summary will appear on a page of its own.

If you do not want the summary to appear on a page of its own in a printed manual, you can enclose the whole of the `Top' node, including the @node Top line and the @top sectioning command line or other sectioning command line between @ifinfo and @end ifinfo. This prevents any of the text from appearing in the printed output. (see section Conditionally Visible Text). You can repeat the brief description from the `Top' node within @iftex ... @end iftex at the beginning of the first chapter, for those who read the printed manual. This saves paper and may look neater.

You should write the version number of the program to which the manual applies in the summary. This helps the reader keep track of which manual is for which version of the program. If the manual changes more frequently than the program or is independent of it, you should also include an edition number for the manual. (The title page should also contain this information: see section @titlepage.)

Creating Pointers with makeinfo

The makeinfo program has a feature for automatically defining node pointers for a hierarchically organized file.

When you take advantage of this feature, you do not need to write the `Next', `Previous', and `Up' pointers after the name of a node. However, you must write a sectioning command, such as @chapter or @section, on the line immediately following each truncated @node line (except that comment lines may intervene).

In addition, you must follow the `Top' @node line with a line beginning with @top to mark the `Top' node in the file. See section @top.

Finally, you must write the name of each node (except for the `Top' node) in a menu that is one or more hierarchical levels above the node's hierarchical level.

This node pointer insertion feature in makeinfo relieves you from the need to update menus and pointers manually or with Texinfo mode commands. (See section Updating Nodes and Menus.)

@anchor: Defining Arbitrary Cross-reference Targets

An anchor is a position in your document, labeled so that cross-references can refer to it, just as they can to nodes. You create an anchor with the @anchor command, and give the label as a normal brace-delimited argument. For example:

This marks the @anchor{x-spot}spot.
...
@xref{x-spot,,the spot}.

produces:

This marks the spot.
...
See [the spot], page 1.

As you can see, the @anchor command itself produces no output. This example defines an anchor `x-spot' just before the word `spot'. You can refer to it later with an @xref or other cross-reference command, as shown. See section Cross References, for details on the cross-reference commands.

It is best to put @anchor commands just before the position you wish to refer to; that way, the reader's eye is led on to the correct text when they jump to the anchor. You can put the @anchor command on a line by itself if that helps readability of the source. Spaces are always ignored after @anchor.

Anchor names and node names may not conflict. Anchors and nodes are given similar treatment in some ways; for example, the goto-node command in standalone Info takes either an anchor name or a node name as an argument. (See section `goto-node' in GNU Info.)

Menus

Menus contain pointers to subordinate nodes.(6) In Info, you use menus to go to such nodes. Menus have no effect in printed manuals and do not appear in them.

By convention, a menu is put at the end of a node since a reader who uses the menu may not see text that follows it. Furthermore, a node that has a menu should not contain much text. If you have a lot of text and a menu, move most of the text into a new subnode--all but a few lines. Otherwise, a reader with a terminal that displays only a few lines may miss the menu and its associated text. As a practical matter, you should locate a menu within 20 lines of the beginning of the node.

The short text before a menu may look awkward in a printed manual. To avoid this, you can write a menu near the beginning of its node and follow the menu by an @node line, and then an @heading line located within @ifinfo and @end ifinfo. This way, the menu, @node line, and title appear only in the Info file, not the printed document.

For example, the preceding two paragraphs follow an Info-only menu, @node line, and heading, and look like this:

@menu
* Menu Location::             Put a menu in a short node.
* Writing a Menu::            What is a menu?
* Menu Parts::                A menu entry has three parts.
* Less Cluttered Menu Entry:: Two part menu entry.
* Menu Example::              Two and three part entries.
* Other Info Files::          How to refer to a different
                                Info file.
@end menu

@node Menu Location, Writing a Menu, , Menus
@ifinfo
@heading Menus Need Short Nodes
@end ifinfo

The Texinfo file for this document contains more than a dozen examples of this procedure. One is at the beginning of this chapter; another is at the beginning of section Cross References.

Writing a Menu

A menu consists of an @menu command on a line by itself followed by menu entry lines or menu comment lines and then by an @end menu command on a line by itself.

A menu looks like this:

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.
@end menu

In a menu, every line that begins with an `* ' is a menu entry. (Note the space after the asterisk.) A line that does not start with an `* ' may also appear in a menu. Such a line is not a menu entry but is a menu comment line that appears in the Info file. In the example above, the line `Larger Units of Text' is a menu comment line; the two lines starting with `* ' are menu entries. Space characters in a menu are preserved as-is; this allows you to format the menu as you wish.

The Parts of a Menu

A menu entry has three parts, only the second of which is required:

  1. The menu entry name (optional).
  2. The name of the node (required).
  3. A description of the item (optional).

The template for a menu entry looks like this:

* menu-entry-name: node-name.   description

Follow the menu entry name with a single colon and follow the node name with tab, comma, period, or newline.

In Info, a user selects a node with the m (Info-menu) command. The menu entry name is what the user types after the m command.

The third part of a menu entry is a descriptive phrase or sentence. Menu entry names and node names are often short; the description explains to the reader what the node is about. A useful description complements the node name rather than repeats it. The description, which is optional, can spread over two or more lines; if it does, some authors prefer to indent the second line while others prefer to align it with the first (and all others). It's up to you.

Less Cluttered Menu Entry

When the menu entry name and node name are the same, you can write the name immediately after the asterisk and space at the beginning of the line and follow the name with two colons.

For example, write

* Name::                                    description

instead of

* Name: Name.                               description

You should use the node name for the menu entry name whenever possible, since it reduces visual clutter in the menu.

A Menu Example

A menu looks like this in Texinfo:

@menu
* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.
@end menu

This produces:

* menu:

* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.

Here is an example as you might see it in a Texinfo file:

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.
@end menu

This produces:

* menu:
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.

In this example, the menu has two entries. `Files' is both a menu entry name and the name of the node referred to by that name. `Multiples' is the menu entry name; it refers to the node named `Buffers'. The line `Larger Units of Text' is a comment; it appears in the menu, but is not an entry.

Since no file name is specified with either `Files' or `Buffers', they must be the names of nodes in the same Info file (see section Referring to Other Info Files).

Referring to Other Info Files

You can create a menu entry that enables a reader in Info to go to a node in another Info file by writing the file name in parentheses just before the node name. In this case, you should use the three-part menu entry format, which saves the reader from having to type the file name.

The format looks like this:

@menu
* first-entry-name:(filename)nodename.     description
* second-entry-name:(filename)second-node. description
@end menu

For example, to refer directly to the `Outlining' and `Rebinding' nodes in the Emacs Manual, you would write a menu like this:

@menu
* Outlining: (emacs)Outline Mode. The major mode for
                                  editing outlines.
* Rebinding: (emacs)Rebinding.    How to redefine the
                                  meaning of a key.
@end menu

If you do not list the node name, but only name the file, then Info presumes that you are referring to the `Top' node.

The `dir' file that contains the main menu for Info has menu entries that list only file names. These take you directly to the `Top' nodes of each Info document. (See section Installing an Info File.)

For example:

* Info: (info).         Documentation browsing system.
* Emacs: (emacs).       The extensible, self-documenting
                        text editor.

(The `dir' top level directory for the Info system is an Info file, not a Texinfo file, but a menu entry looks the same in both types of file.)

The GNU Emacs Texinfo mode menu updating commands only work with nodes within the current buffer, so you cannot use them to create menus that refer to other files. You must write such menus by hand.

Cross References

Cross references are used to refer the reader to other parts of the same or different Texinfo files. In Texinfo, nodes and anchors are the places to which cross references can refer.

Often, but not always, a printed document should be designed so that it can be read sequentially. People tire of flipping back and forth to find information that should be presented to them as they need it.

However, in any document, some information will be too detailed for the current context, or incidental to it; use cross references to provide access to such information. Also, an online help system or a reference manual is not like a novel; few read such documents in sequence from beginning to end. Instead, people look up what they need. For this reason, such creations should contain many cross references to help readers find other information that they may not have read.

In a printed manual, a cross reference results in a page reference, unless it is to another manual altogether, in which case the cross reference names that manual.

In Info, a cross reference results in an entry that you can follow using the Info `f' command. (See Info file `info', node `Help-Adv'.)

The various cross reference commands use nodes (or anchors, see section @anchor: Defining Arbitrary Cross-reference Targets) to define cross reference locations. This is evident in Info, in which a cross reference takes you to the specified location. TeX also uses nodes to define cross reference locations, but the action is less obvious. When TeX generates a DVI file, it records each node's page number and uses the page numbers in making references. Thus, if you are writing a manual that will only be printed, and will not be used online, you must nonetheless write @node lines to name the places to which you make cross references.

Different Cross Reference Commands

There are four different cross reference commands:

@xref
Used to start a sentence in the printed manual saying `See ...' or an Info cross-reference saying `*Note name: node.'.
@ref
Used within or, more often, at the end of a sentence; same as @xref for Info; produces just the reference in the printed manual without a preceding `See'.
@pxref
Used within parentheses to make a reference that suits both an Info file and a printed book. Starts with a lower case `see' within the printed manual. (`p' is for `parenthesis'.)
@inforef
Used to make a reference to an Info file for which there is no printed manual.

(The @cite command is used to make references to books and manuals for which there is no corresponding Info file and, therefore, no node to which to point. See section @cite{reference}.)

Parts of a Cross Reference

A cross reference command requires only one argument, which is the name of the node to which it refers. But a cross reference command may contain up to four additional arguments. By using these arguments, you can provide a cross reference name for Info, a topic description or section title for the printed output, the name of a different Info file, and the name of a different printed manual.

Here is a simple cross reference example:

@xref{Node name}.

which produces

*Note Node name::.

and

See Section nnn [Node name], page ppp.

Here is an example of a full five-part cross reference:

@xref{Node name, Cross Reference Name, Particular Topic,
info-file-name, A Printed Manual}, for details.

which produces

*Note Cross Reference Name: (info-file-name)Node name,
for details.

in Info and

See section "Particular Topic" in A Printed Manual, for details.

in a printed book.

The five possible arguments for a cross reference are:

  1. The node or anchor name (required). This is the location to which the cross reference takes you. In a printed document, the location of the node provides the page reference only for references within the same document.
  2. The cross reference name for the Info reference, if it is to be different from the node name. If you include this argument, it becomes the first part of the cross reference. It is usually omitted.
  3. A topic description or section name. Often, this is the title of the section. This is used as the name of the reference in the printed manual. If omitted, the node name is used.
  4. The name of the Info file in which the reference is located, if it is different from the current file. You need not include any `.info' suffix on the file name, since Info readers try appending it automatically.
  5. The name of a printed manual from a different Texinfo file.

The template for a full five argument cross reference looks like this:

@xref{node-name, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

Cross references with one, two, three, four, and five arguments are described separately following the description of @xref.

Write a node name in a cross reference in exactly the same way as in the @node line, including the same capitalization; otherwise, the formatters may not find the reference.

You can write cross reference commands within a paragraph, but note how Info and TeX format the output of each of the various commands: write @xref at the beginning of a sentence; write @pxref only within parentheses, and so on.

@xref

The @xref command generates a cross reference for the beginning of a sentence. The Info formatting commands convert it into an Info cross reference, which the Info `f' command can use to bring you directly to another node. The TeX typesetting commands convert it into a page reference, or a reference to another book or manual.

Most often, an Info cross reference looks like this:

*Note node-name::.

or like this

*Note cross-reference-name: node-name.

In TeX, a cross reference looks like this:

See Section section-number [node-name], page page.

or like this

See Section section-number [title-or-topic], page page.

The @xref command does not generate a period or comma to end the cross reference in either the Info file or the printed output. You must write that period or comma yourself; otherwise, Info will not recognize the end of the reference. (The @pxref command works differently. See section @pxref.)

Please note: A period or comma must follow the closing brace of an @xref. It is required to terminate the cross reference. This period or comma will appear in the output, both in the Info file and in the printed manual.

@xref must refer to an Info node by name. Use @node to define the node (see section How to Write an @node Line).

@xref is followed by several arguments inside braces, separated by commas. Whitespace before and after these commas is ignored.

A cross reference requires only the name of a node; but it may contain up to four additional arguments. Each of these variations produces a cross reference that looks somewhat different.

Please note: Commas separate arguments in a cross reference; avoid including them in the title or other part lest the formatters mistake them for separators.

@xref with One Argument

The simplest form of @xref takes one argument, the name of another node in the same Info file. The Info formatters produce output that the Info readers can use to jump to the reference; TeX produces output that specifies the page and section number for you.

For example,

@xref{Tropical Storms}.

produces

*Note Tropical Storms::.

and

See Section 3.1 [Tropical Storms], page 24.

(Note that in the preceding example the closing brace is followed by a period.)

You can write a clause after the cross reference, like this:

@xref{Tropical Storms}, for more info.

which produces

*Note Tropical Storms::, for more info.

and

See Section 3.1 [Tropical Storms], page 24, for more info.

(Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.)

@xref with Two Arguments

With two arguments, the second is used as the name of the Info cross reference, while the first is still the name of the node to which the cross reference points.

The template is like this:

@xref{node-name, cross-reference-name}.

For example,

@xref{Electrical Effects, Lightning}.

produces:

*Note Lightning: Electrical Effects.

and

See Section 5.2 [Electrical Effects], page 57.

(Note that in the preceding example the closing brace is followed by a period; and that the node name is printed, not the cross reference name.)

You can write a clause after the cross reference, like this:

@xref{Electrical Effects, Lightning}, for more info.

which produces

*Note Lightning: Electrical Effects, for more info.

and

See Section 5.2 [Electrical Effects], page 57, for more info.

(Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.)

@xref with Three Arguments

A third argument replaces the node name in the TeX output. The third argument should be the name of the section in the printed output, or else state the topic discussed by that section. Often, you will want to use initial upper case letters so it will be easier to read when the reference is printed. Use a third argument when the node name is unsuitable because of syntax or meaning.

Remember to avoid placing a comma within the title or topic section of a cross reference, or within any other section. The formatters divide cross references into arguments according to the commas; a comma within a title or other section will divide it into two arguments. In a reference, you need to write a title such as "Clouds, Mist, and Fog" without the commas.

Also, remember to write a comma or period after the closing brace of an @xref to terminate the cross reference. In the following examples, a clause follows a terminating comma.

The template is like this:

@xref{node-name, cross-reference-name, title-or-topic}.

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning},
for details.

produces

*Note Lightning: Electrical Effects, for details.

and

See Section 5.2 [Thunder and Lightning], page 57, for details.

If a third argument is given and the second one is empty, then the third argument serves both. (Note how two commas, side by side, mark the empty second argument.)

@xref{Electrical Effects, , Thunder and Lightning},
for details.

produces

*Note Thunder and Lightning: Electrical Effects, for details.

and

See Section 5.2 [Thunder and Lightning], page 57, for details.

As a practical matter, it is often best to write cross references with just the first argument if the node name and the section title are the same, and with the first and third arguments if the node name and title are different.

Here are several examples from The GNU Awk User's Guide:

@xref{Sample Program}.
@xref{Glossary}.
@xref{Case-sensitivity, ,Case-sensitivity in Matching}.
@xref{Close Output, , Closing Output Files and Pipes},
   for more information.
@xref{Regexp, , Regular Expressions as Patterns}.

@xref with Four and Five Arguments

In a cross reference, a fourth argument specifies the name of another Info file, different from the file in which the reference appears, and a fifth argument specifies its title as a printed manual.

Remember that a comma or period must follow the closing brace of an @xref command to terminate the cross reference. In the following examples, a clause follows a terminating comma.

The template is:

@xref{node-name, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning,
weather, An Introduction to Meteorology}, for details.

produces

*Note Lightning: (weather)Electrical Effects, for details.

The name of the Info file is enclosed in parentheses and precedes the name of the node.

In a printed manual, the reference looks like this:

See section "Thunder and Lightning" in An Introduction to Meteorology, for details.

The title of the printed manual is typeset in italics; and the reference lacks a page number since TeX cannot know to which page a reference refers when that reference is to another manual.

Often, you will leave out the second argument when you use the long version of @xref. In this case, the third argument, the topic description, will be used as the cross reference name in Info.

The template looks like this:

@xref{node-name, , title-or-topic, info-file-name,
printed-manual-title}, for details.

which produces

*Note title-or-topic: (info-file-name)node-name, for details.

and

See section title-or-topic in printed-manual-title, for details.

For example,

@xref{Electrical Effects, , Thunder and Lightning,
weather, An Introduction to Meteorology}, for details.

produces

*Note Thunder and Lightning: (weather)Electrical Effects,
for details.

and

See section "Thunder and Lightning" in An Introduction to Meteorology, for details.

On rare occasions, you may want to refer to another Info file that is within a single printed manual--when multiple Texinfo files are incorporated into the same TeX run but make separate Info files. In this case, you need to specify only the fourth argument, and not the fifth.

Naming a `Top' Node

In a cross reference, you must always name a node. This means that in order to refer to a whole manual, you must identify the `Top' node by writing it as the first argument to the @xref command. (This is different from the way you write a menu entry; see section Referring to Other Info Files.) At the same time, to provide a meaningful section topic or title in the printed cross reference (instead of the word `Top'), you must write an appropriate entry for the third argument to the @xref command.

Thus, to make a cross reference to The GNU Make Manual, write:

@xref{Top, , Overview, make, The GNU Make Manual}.

which produces

*Note Overview: (make)Top.

and

See section "Overview" in The GNU Make Manual.

In this example, `Top' is the name of the first node, and `Overview' is the name of the first section of the manual.

@ref

@ref is nearly the same as @xref except that it does not generate a `See' in the printed output, just the reference itself. This makes it useful as the last part of a sentence.

For example,

For more information, see @ref{Hurricanes}.

produces

For more information, see *Note Hurricanes::.

and

For more information, see Section 8.2 [Hurricanes], page 123.

The @ref command sometimes leads writers to express themselves in a manner that is suitable for a printed manual but looks awkward in the Info format. Bear in mind that your audience will be using both the printed and the Info format.

For example,

Sea surges are described in @ref{Hurricanes}.

produces

Sea surges are described in Section 6.7 [Hurricanes], page 72.

in a printed document, and the following in Info:

Sea surges are described in *Note Hurricanes::.

Caution: You must write a period, comma, or right parenthesis immediately after an @ref command with two or more arguments. Otherwise, Info will not find the end of the cross reference entry and its attempt to follow the cross reference will fail. As a general rule, you should write a period or comma after every @ref command. This looks best in both the printed and the Info output.

@pxref

The parenthetical reference command, @pxref, is nearly the same as @xref, but you use it only inside parentheses and you do not type a comma or period after the command's closing brace. The command differs from @xref in two ways:

  1. TeX typesets the reference for the printed manual with a lower case `see' rather than an upper case `See'.
  2. The Info formatting commands automatically end the reference with a closing colon or period.

Because one type of formatting automatically inserts closing punctuation and the other does not, you should use @pxref only inside parentheses as part of another sentence. Also, you yourself should not insert punctuation after the reference, as you do with @xref.

@pxref is designed so that the output looks right and works right between parentheses both in printed output and in an Info file. In a printed manual, a closing comma or period should not follow a cross reference within parentheses; such punctuation is wrong. But in an Info file, suitable closing punctuation must follow the cross reference so Info can recognize its end. @pxref spares you the need to use complicated methods to put a terminator into one form of the output and not the other.

With one argument, a parenthetical cross reference looks like this:

... storms cause flooding (@pxref{Hurricanes}) ...

which produces

... storms cause flooding (*Note Hurricanes::) ...

and

... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ...

With two arguments, a parenthetical cross reference has this template:

... (@pxref{node-name, cross-reference-name}) ...

which produces

... (*Note cross-reference-name: node-name.) ...

and

... (see Section nnn [node-name], page ppp) ...

@pxref can be used with up to five arguments just like @xref (see section @xref).

Please note: Use @pxref only as a parenthetical reference. Do not try to use @pxref as a clause in a sentence. It will look bad in either the Info file, the printed output, or both.

Also, parenthetical cross references look best at the ends of sentences. Although you may write them in the middle of a sentence, that location breaks up the flow of text.

@inforef

@inforef is used for cross references to Info files for which there are no printed manuals. Even in a printed manual, @inforef generates a reference directing the user to look in an Info file.

The command takes either two or three arguments, in the following order:

  1. The node name.
  2. The cross reference name (optional).
  3. The Info file name.

Separate the arguments with commas, as with @xref. Also, you must terminate the reference with a comma or period after the `}', as you do with @xref.

The template is:

@inforef{node-name, cross-reference-name, info-file-name},

Thus,

@inforef{Expert, Advanced Info commands, info},
for more information.

produces

*Note Advanced Info commands: (info)Expert,
for more information.

and

See Info file `info', node `Expert', for more information.

Similarly,

@inforef{Expert, , info}, for more information.

produces

*Note (info)Expert::, for more information.

and

See Info file `info', node `Expert', for more information.

The converse of @inforef is @cite, which is used to refer to printed works for which no Info form exists. See section @cite{reference}.

@uref{url[, text][, replacement]}

@uref produces a reference to a uniform resource locator (url). It takes one mandatory argument, the url, and two optional arguments which control the text that is displayed. In HTML output, @uref produces a link you can follow.

The second argument, if specified, is the text to display (the default is the url itself); in Info and DVI output, but not in HTML output, the url is also output.

The third argument, on the other hand, if specified is also the text to display, but the url is not output in any format. This is useful when the text is already sufficiently referential, as in a man page. If the third argument is given, the second argument is ignored.

The simple one argument form, where the url is both the target and the text of the link:

The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.

produces:

The official GNU ftp site is ftp://ftp.gnu.org/gnu.

An example of the two-argument form:

The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} holds
programs and texts.

produces:

The official GNU ftp site holds
programs and texts.

that is, the Info output is this:

The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds
programs and texts.

and the HTML output is this:

The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> holds
programs and texts.

An example of the three-argument form:

The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program ...

produces:

The http://example.org/man.cgi/1/ls program ...

but with HTML:

The <a href="http://example.org/man.cgi/1/ls">ls(1)</a> program ...

To merely indicate a url without creating a link people can follow, use @url (see section @url{uniform-resource-locator}).

Some people prefer to display url's in the unambiguous format:

<URL:http://host/path>

You can use this form in the input file if you wish. We feel it's not necessary to clutter up the output with the extra `<URL:' and `>', since any software that tries to detect url's in text already has to detect them without the `<URL:' to be useful.

Marking Words and Phrases

In Texinfo, you can mark words and phrases in a variety of ways. The Texinfo formatters use this information to determine how to highlight the text. You can specify, for example, whether a word or phrase is a defining occurrence, a metasyntactic variable, or a symbol used in a program. Also, you can emphasize text, in several different ways.

Indicating Definitions, Commands, etc.

Texinfo has commands for indicating just what kind of object a piece of text refers to. For example, metasyntactic variables are marked by @var, and code by @code. Since the pieces of text are labelled by commands that tell what kind of object they are, it is easy to change the way the Texinfo formatters prepare such text. (Texinfo is an intentional formatting language rather than a typesetting formatting language.)

For example, in a printed manual, code is usually illustrated in a typewriter font; @code tells TeX to typeset this text in this font. But it would be easy to change the way TeX highlights code to use another font, and this change would not affect how keystroke examples are highlighted. If straight typesetting commands were used in the body of the file and you wanted to make a change, you would need to check every single occurrence to make sure that you were changing code and not something else that should not be changed.

The highlighting commands can be used to extract useful information from the file, such as lists of functions or file names. It is possible, for example, to write a program in Emacs Lisp (or a keyboard macro) to insert an index entry after every paragraph that contains words or phrases marked by a specified command. You could do this to construct an index of functions if you had not already made the entries.

The commands serve a variety of purposes:

@code{sample-code}
Indicate text that is a literal example of a piece of a program.
@kbd{keyboard-characters}
Indicate keyboard input.
@key{key-name}
Indicate the conventional name for a key on a keyboard.
@samp{text}
Indicate text that is a literal example of a sequence of characters.
@var{metasyntactic-variable}
Indicate a metasyntactic variable.
@env{environment-variable}
Indicate an environment variable.
@file{file-name}
Indicate the name of a file.
@command{command-name}
Indicate the name of a command.
@option{option}
Indicate a command-line option.
@dfn{term}
Indicate the introductory or defining use of a term.
@cite{reference}
Indicate the name of a book.
@acronym{acronym}
Indicate an acronym.
@url{uniform-resource-locator}
Indicate a uniform resource locator for the World Wide Web.
@email{email-address[, displayed-text]}
Indicate an electronic mail address.

@code{sample-code}

Use the @code command to indicate text that is a piece of a program and which consists of entire syntactic tokens. Enclose the text in braces.

Thus, you should use @code for an expression in a program, for the name of a variable or function used in a program, or for a keyword in a programming language.

Use @code for command names in languages that resemble programming languages, such as Texinfo. For example, @code and @samp are produced by writing `@code{@@code}' and `@code{@@samp}' in the Texinfo source, respectively.

It is incorrect to alter the case of a word inside an @code command when it appears at the beginning of a sentence. Most computer languages are case sensitive. In C, for example, Printf is different from the identifier printf, and most likely is a misspelling of it. Even in languages which are not case sensitive, it is confusing to a human reader to see identifiers spelled in different ways. Pick one spelling and always use that. If you do not want to start a sentence with a command name written all in lower case, you should rearrange the sentence.

In the printed manual, @code causes TeX to typeset the argument in a typewriter face. In the Info file, it causes the Info formatting commands to use single quotation marks around the text.

For example,

The function returns @code{nil}.

produces this in the printed manual:

The function returns nil.

and this in the Info file:

The function returns `nil'.

Here are some cases for which it is preferable not to use @code:

  • For shell command names such as @command{ls} (use @command).
  • For shell options such as `-c' when such options stand alone (use @option).
  • Also, an entire shell command often looks better if written using @samp rather than @code. In this case, the rule is to choose the more pleasing format.
  • For environment variable such as @env{TEXINPUTS} (use @env).
  • For a string of characters shorter than a syntactic token. For example, if you are writing about `goto-ch', which is just a part of the name for the goto-char Emacs Lisp function, you should use @samp.
  • In general, when writing about the characters used in a token; for example, do not use @code when you are explaining what letters or printable symbols can be used in the names of functions. (Use @samp.) Also, you should not use @code to mark text that is considered input to programs unless the input is written in a language that is like a programming language. For example, you should not use @code for the keystroke commands of GNU Emacs (use @kbd instead) although you may use @code for the names of the Emacs Lisp functions that the keystroke commands invoke.

Since @command, @option, and @env were introduced relatively recently, it is acceptable to use @code or @samp for command names, options, and environment variables. The new commands allow you to express the markup more precisely, but there is no real harm in using the older commands, and of course the long-standing manuals do so.

@kbd{keyboard-characters}

Use the @kbd command for characters of input to be typed by users. For example, to refer to the characters M-a, write

@kbd{M-a}

and to refer to the characters M-x shell, write

@kbd{M-x shell}

The @kbd command has the same effect as @code in Info, but by default produces a different font (slanted typewriter instead of normal typewriter) in the printed manual, so users can distinguish the characters they are supposed to type from those the computer outputs.

Since the usage of @kbd varies from manual to manual, you can control the font switching with the @kbdinputstyle command. This command has no effect on Info output. Write this command at the beginning of a line with a single word as an argument, one of the following:

`code'
Always use the same font for @kbd as @code.
`example'
Use the distinguishing font for @kbd only in @example and similar environments.
`distinct'
(the default) Always use the distinguishing font for @kbd.

You can embed another @-command inside the braces of an @kbd command. Here, for example, is the way to describe a command that would be described more verbosely as "press an `r' and then press the RET key":

@kbd{r @key{RET}}

This produces: r RET

You also use the @kbd command if you are spelling out the letters you type; for example:

To give the @code{logout} command,
type the characters @kbd{l o g o u t @key{RET}}.

This produces:

To give the logout command, type the characters l o g o u t RET.

(Also, this example shows that you can add spaces for clarity. If you really want to mention a space character as one of the characters of input, write @key{SPC} for it.)

@key{key-name}

Use the @key command for the conventional name for a key on a keyboard, as in:

@key{RET}

You can use the @key command within the argument of an @kbd command when the sequence of characters to be typed includes one or more keys that are described by name.

For example, to produce C-x ESC you would type:

@kbd{C-x @key{ESC}}

Here is a list of the recommended names for keys:

SPC
Space
RET
Return
LFD
Linefeed (however, since most keyboards nowadays do not have a Linefeed key, it might be better to call this character C-j.
TAB
Tab
BS
Backspace
ESC
Escape
DEL
Delete
SHIFT
Shift
CTRL
Control
META
Meta

There are subtleties to handling words like `meta' or `ctrl' that are names of modifier keys. When mentioning a character in which the modifier key is used, such as Meta-a, use the @kbd command alone; do not use the @key command; but when you are referring to the modifier key in isolation, use the @key command. For example, write `@kbd{Meta-a}' to produce Meta-a and `@key{META}' to produce META.

@samp{text}

Use the @samp command to indicate text that is a literal example or `sample' of a sequence of characters in a file, string, pattern, etc. Enclose the text in braces. The argument appears within single quotation marks in both the Info file and the printed manual; in addition, it is printed in a fixed-width font.

To match @samp{foo} at the end of the line,
use the regexp @samp{foo$}.

produces

To match `foo' at the end of the line, use the regexp `foo$'.

Any time you are referring to single characters, you should use @samp unless @kbd or @key is more appropriate. Also, you may use @samp for entire statements in C and for entire shell commands--in this case, @samp often looks better than @code. Basically, @samp is a catchall for whatever is not covered by @code, @kbd, or @key.

Only include punctuation marks within braces if they are part of the string you are specifying. Write punctuation marks outside the braces if those punctuation marks are part of the English text that surrounds the string. In the following sentence, for example, the commas and period are outside of the braces:

In English, the vowels are @samp{a}, @samp{e},
@samp{i}, @samp{o}, @samp{u}, and sometimes
@samp{y}.

This produces:

In English, the vowels are `a', `e', `i', `o', `u', and sometimes `y'.

@var{metasyntactic-variable}

Use the @var command to indicate metasyntactic variables. A metasyntactic variable is something that stands for another piece of text. For example, you should use a metasyntactic variable in the documentation of a function to describe the arguments that are passed to that function.

Do not use @var for the names of particular variables in programming languages. These are specific names from a program, so @code is correct for them (see section @code{sample-code}). For example, the Emacs Lisp variable texinfo-tex-command is not a metasyntactic variable; it is properly formatted using @code.

Do not use @var for environment variables either; @env is correct for them (see the next section).

The effect of @var in the Info file is to change the case of the argument to all upper case. In the printed manual and HTML output, the argument is printed in slanted type.

For example,

To delete file @var{filename},
type @samp{rm @var{filename}}.

produces

To delete file filename, type `rm filename'.

(Note that @var may appear inside @code, @samp, @file, etc.)

Write a metasyntactic variable all in lower case without spaces, and use hyphens to make it more readable. Thus, the Texinfo source for the illustration of how to begin a Texinfo manual looks like this:

\input texinfo
@@setfilename @var{info-file-name}
@@settitle @var{name-of-manual}

This produces:

\input texinfo
@setfilename info-file-name
@settitle name-of-manual

In some documentation styles, metasyntactic variables are shown with angle brackets, for example:

..., type rm <filename>

However, that is not the style that Texinfo uses. (You can, of course, modify the sources to `texinfo.tex' and the Info formatting commands to output the <...> format if you wish.)

@env{environment-variable}

Use the @env command to indicate environment variables, as used by many operating systems, including GNU. Do not use it for metasyntactic variables; use @var instead (see the previous section).

@env is equivalent to @code in its effects. For example:

The @env{PATH} environment variable sets the search path for commands.

produces

The @env{PATH} environment variable sets the search path for commands.

@file{file-name}

Use the @file command to indicate text that is the name of a file, buffer, or directory, or is the name of a node in Info. You can also use the command for file name suffixes. Do not use @file for symbols in a programming language; use @code.

Currently, @file is equivalent to @samp in its effects. For example,

The @file{.el} files are in
the @file{/usr/local/emacs/lisp} directory.

produces

The `.el' files are in the `/usr/local/emacs/lisp' directory.

@command{command-name}

Use the @command command to indicate command names, such as @command{ls} or @command{cc}.

@command is equivalent to @code in its effects. For example:

The command @command{ls} lists directory contents.

produces

The command @command{ls} lists directory contents.

You should write the name of a program in the ordinary text font, rather than using @command, if you regard it as a new English word, such as `Emacs' or `Bison'.

When writing an entire shell command invocation, as in `ls -l', you should use either @samp or @code at your discretion.

@option{option-name}

Use the @option command to indicate a command-line option; for example, @option{-l} or @option{--version} or @option{--output=filename}.

@option is equivalent to @samp in its effects. For example:

The option @option{-l} produces a long listing.

produces

The option @option{-l} produces a long listing.

In tables, putting options inside @code produces a more pleasing effect.

@dfn{term}

Use the @dfn command to identify the introductory or defining use of a technical term. Use the command only in passages whose purpose is to introduce a term which will be used again or which the reader ought to know. Mere passing mention of a term for the first time does not deserve @dfn. The command generates italics in the printed manual, and double quotation marks in the Info file. For example:

Getting rid of a file is called @dfn{deleting} it.

produces

Getting rid of a file is called deleting it.

As a general rule, a sentence containing the defining occurrence of a term should be a definition of the term. The sentence does not need to say explicitly that it is a definition, but it should contain the information of a definition--it should make the meaning clear.

@cite{reference}

Use the @cite command for the name of a book that lacks a companion Info file. The command produces italics in the printed manual, and quotation marks in the Info file.

If a book is written in Texinfo, it is better to use a cross reference command since a reader can easily follow such a reference in Info. See section @xref.

@acronym{acronym}

Use the @acronym command for abbreviations written in all capital letters, such as `@acronym{NASA}'. The abbreviation is given as the single argument in braces, as in `@acronym{NASA}'. As a matter of style, or for particular abbreviations, you may prefer to use periods, as in `@acronym{F.B.I.}'.

In TeX and HTML, the argument is printed in a slightly smaller font size. In Info or plain text output, this command changes nothing.

@url{uniform-resource-locator}

Use the @url command to indicate a uniform resource locator on the World Wide Web. This is analogous to @file, @var, etc., and is purely for markup purposes. It does not produce a link you can follow in HTML output (use the @uref command for that, see section @uref{url[, text][, replacement]}). It is useful for url's which do not actually exist. For example:

For example, the url might be @url{http://example.org/path}.

which produces:

For example, the url might be http://example.org/path.

@email{email-address[, displayed-text]}

Use the @email command to indicate an electronic mail address. It takes one mandatory argument, the address, and one optional argument, the text to display (the default is the address itself).

In Info and TeX, the address is shown in angle brackets, preceded by the text to display if any. In HTML output, @email produces a `mailto' link that usually brings up a mail composition window. For example:

Send bug reports to @email{bug-texinfo@@gnu.org}.
Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.

produces

Send bug reports to bug-texinfo@gnu.org.
Send suggestions to the same place.

Emphasizing Text

Usually, Texinfo changes the font to mark words in the text according to what category the words belong to; an example is the @code command. Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two commands to do this. Also, Texinfo has several commands that specify the font in which TeX will typeset text. These commands have no effect on Info and only one of them, the @r command, has any regular use.

@emph{text} and @strong{text}

The @emph and @strong commands are for emphasis; @strong is stronger. In printed output, @emph produces italics and @strong produces bold.

For example,

@quotation
@strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
files in the directory.
@end quotation

produces the following in printed output:

Caution: `rm * .[^.]*' removes all files in the directory.

and the following in Info:

     *Caution*: `rm * .[^.]*' removes _all_
     files in the directory.

The @strong command is seldom used except to mark what is, in effect, a typographical element, such as the word `Caution' in the preceding example.

In the Info output, @emph surrounds the text with underscores (`_'), and @strong puts asterisks around the text.

Caution: Do not use @strong with the word `Note'; Info will mistake the combination for a cross reference. Use a phrase such as Please note or Caution instead.

@sc{text}: The Small Caps Font

Use the `@sc' command to set text in the printed and the HTML output in A SMALL CAPS FONT and set text in the Info file in upper case letters. Write the text you want to be in small caps (where possible) between braces in lower case, like this:

The @sc{acm} and @sc{ieee} are technical societies.

This produces:

The ACM and IEEE are technical societies.

TeX typesets the small caps font in a manner that prevents the letters from `jumping out at you on the page'. This makes small caps text easier to read than text in all upper case--but it's usually better to use regular mixed case anyway. The Info formatting commands set all small caps text in upper case. In HTML, the text is upper-cased and a smaller font is used to render it.

If the text between the braces of an @sc command is uppercase, TeX typesets in FULL-SIZE CAPITALS. Use full-size capitals sparingly, if ever, and since it's redundant to mark all-uppercase text with @sc, @command{makeinfo} warns about such usage.

You may also use the small caps font for a jargon word such as ATO (a NASA word meaning `abort to orbit').

There are subtleties to using the small caps font with a jargon word such as CDR, a word used in Lisp programming. In this case, you should use the small caps font when the word refers to the second and subsequent elements of a list (the CDR of the list), but you should use `@code' when the word refers to the Lisp function of the same spelling.

Fonts for Printing, Not Info

Texinfo provides four font commands that specify font changes in the printed manual but have no effect in the Info file. @i requests italic font (in some versions of TeX, a slanted font is used), @b requests bold face, @t requests the fixed-width, typewriter-style font used by @code, and @r requests a roman font, which is the usual font in which text is printed. All four commands apply to an argument that follows, surrounded by braces.

Only the @r command has much use: in example programs, you can use the @r command to convert code comments from the fixed-width font to a roman font. This looks better in printed output.

For example,

@lisp
(+ 2 2)    ; @r{Add two plus two.}
@end lisp

produces

(+ 2 2)    ; Add two plus two.

If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo language.

Quotations and Examples

Quotations and examples are blocks of text consisting of one or more whole paragraphs that are set off from the bulk of the text and treated differently. They are usually indented.

In Texinfo, you always begin a quotation or example by writing an @-command at the beginning of a line by itself, and end it by writing an @end command that is also at the beginning of a line by itself. For instance, you begin an example by writing @example by itself at the beginning of a line and end the example by writing @end example on a line by itself, at the beginning of that line.

Block Enclosing Commands

Here are commands for quotations and examples, explained further in the following sections:

@quotation
Indicate text that is quoted. The text is filled, indented, and printed in a roman font by default.
@example
Illustrate code, commands, and the like. The text is printed in a fixed-width font, and indented but not filled.
@smallexample
Same as @example, except that in TeX this command typesets text in a smaller font for the @smallbook format than for the default 8.5 by 11 inch format.
@lisp
Like @example, but specifically for illustrating Lisp code. The text is printed in a fixed-width font, and indented but not filled.
@smalllisp
Is to @lisp as @smallexample is to @example.
@display
Display illustrative text. The text is indented but not filled, and no font is selected (so, by default, the font is roman).
@smalldisplay
Is to @display as @smallexample is to @example.
@format
Like @display (the text is not filled and no font is selected), but the text is not indented.
@smallformat
Is to @format as @smallexample is to @example.

The @exdent command is used within the above constructs to undo the indentation of a line.

The @flushleft and @flushright commands are used to line up the left or right margins of unfilled text.

The @noindent command may be used after one of the above constructs to prevent the following text from being indented as a new paragraph.

You can use the @cartouche command within one of the above constructs to highlight the example or quotation by drawing a box with rounded corners around it. See section Drawing Cartouches Around Examples.

@quotation

The text of a quotation is processed normally except that:

  • the margins are closer to the center of the page, so the whole of the quotation is indented;
  • the first lines of paragraphs are indented no more than other lines;
  • in the printed output, interparagraph spacing is reduced.

This is an example of text written between an @quotation command and an @end quotation command. An @quotation command is most often used to indicate text that is excerpted from another (real or hypothetical) printed work.

Write an @quotation command as text on a line by itself. This line will disappear from the output. Mark the end of the quotation with a line beginning with and containing only @end quotation. The @end quotation line will likewise disappear from the output. Thus, the following,

@quotation
This is
a foo.
@end quotation

produces

This is a foo.

@example

The @example command is used to indicate an example that is not part of the running text, such as computer input or output.

This is an example of text written between an
@example command
and an @end example command.
The text is indented but not filled.

In the printed manual, the text is typeset in a
fixed-width font, and extra spaces and blank lines are
significant.  In the Info file, an analogous result is
obtained by indenting each line with five spaces.

Write an @example command at the beginning of a line by itself. Mark the end of the example with an @end example command, also written at the beginning of a line by itself.

For example,

@example
mv foo bar
@end example

produces

mv foo bar

The lines containing @example and @end example will disappear from the output. To make the output look good, you should put a blank line before the @example and another blank line after the @end example. Note that blank lines inside the beginning @example and the ending @end example will appear in the output.

Caution: Do not use tabs in the lines of an example (or anywhere else in Texinfo, for that matter)! TeX treats tabs as single spaces, and that is not what they look like. This is a problem with TeX. (If necessary, in Emacs, you can use M-x untabify to convert tabs in a region to multiple spaces.)

Examples are often, logically speaking, "in the middle" of a paragraph, and the text that continues after an example should not be indented. The @noindent command prevents a piece of text from being indented as if it were a new paragraph.

(The @code command is used for examples of code that are embedded within sentences, not set off from preceding and following text. See section @code{sample-code}.)

@noindent

An example or other inclusion can break a paragraph into segments. Ordinarily, the formatters indent text that follows an example as a new paragraph. However, you can prevent this by writing @noindent at the beginning of a line by itself preceding the continuation text.

For example:

@example
This is an example
@end example

@noindent
This line is not indented.  As you can see, the
beginning of the line is fully flush left with the line
that follows after it.  (This whole example is between
@code{@@display} and @code{@@end display}.)

produces

This is an example

This line is not indented.  As you can see, the
beginning of the line is fully flush left with the line
that follows after it.  (This whole example is between
@display and @end display.)

To adjust the number of blank lines properly in the Info file output, remember that the line containing @noindent does not generate a blank line, and neither does the @end example line.

In the Texinfo source file for this manual, each line that says `produces' is preceded by a line containing @noindent.

Do not put braces after an @noindent command; they are not necessary, since @noindent is a command used outside of paragraphs (see section @-Command Syntax).

@lisp

The @lisp command is used for Lisp code. It is synonymous with the @example command.

This is an example of text written between an
@lisp command and an @end lisp command.

Use @lisp instead of @example to preserve information regarding the nature of the example. This is useful, for example, if you write a function that evaluates only and all the Lisp code in a Texinfo file. Then you can use the Texinfo file as a Lisp library.(7)

Mark the end of @lisp with @end lisp on a line by itself.

@small... Block Commands

In addition to the regular @example and @lisp commands, Texinfo has "small" example-style commands. These are @smalldisplay, @smallexample, @smallformat, and @smalllisp. All of these commands are designed for use with the @smallbook command (which causes TeX to format a printed book for a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size).

In TeX, the @small... commands typeset text in a smaller font for the smaller @smallbook format than for the 8.5 by 11 inch format. Consequently, many examples containing long lines fit in a narrower, @smallbook page without needing to be shortened. Both commands typeset in the normal font size when you format for the 8.5 by 11 inch size. Indeed, in this situation, the @small... commands are equivalent to their non-small versions.

In Info, the @small... commands are also equivalent to their non-small companion commands.

Mark the end of an @small... block with a corresponding @end small.... For example, pair @smallexample with @end smallexample.

Here is an example written in the small font used by the @smallexample and @smalllisp commands:

The @small... commands make it easier to prepare smaller
format manuals without forcing you to edit examples by hand to fit them
onto narrower pages.

As a general rule, a printed document looks better if you use only one
of (for example) @example or in @smallexample
consistently within a chapter.  Only occasionally should you mix the two
formats.

See section Printing "Small" Books, for more information
about the @smallbook command.

@display and @smalldisplay

The @display command begins a kind of example.  It is like the
@example command
except that, in
a printed manual, @display does not select the fixed-width
font.  In fact, it does not specify the font at all, so that the text
appears in the same font it would have appeared in without the
@display command.

This is an example of text written between an @display command
and an @end display command.  The @display command
indents the text, but does not fill it.

Texinfo also provides a command @smalldisplay, which is like
@display but uses a smaller font in @smallbook format.
See section @small... Block Commands.

@format and @smallformat

The @format command is similar to @example except
that, in the printed manual, @format does not select the
fixed-width font and does not narrow the margins.

This is an example of text written between an @format command
and an @end format command.  As you can see
from this example,
the @format command does not fill the text.

Texinfo also provides a command @smallformat, which is like
@format but uses a smaller font in @smallbook format.
See section @small... Block Commands.

@exdent: Undoing a Line's Indentation

The @exdent command removes any indentation a line might have.
The command is written at the beginning of a line and applies only to
the text that follows the command that is on the same line.  Do not use
braces around the text.  In a printed manual, the text on an
@exdent line is printed in the roman font.

@exdent is usually used within examples.  Thus,

@example
This line follows an @@example command.
@exdent This line is exdented.
This line follows the exdented line.
The @@end example comes on the next line.
@end group

produces

This line follows an @example command.
This line is exdented.
This line follows the exdented line.
The @end example comes on the next line.

In practice, the @exdent command is rarely used.
Usually, you un-indent text by ending the example and
returning the page to its normal width.

@flushleft and @flushright

The @flushleft and @flushright commands line up the
ends of lines on the left and right margins of a page,
but do not fill the text.  The commands are written on lines of their
own, without braces.  The @flushleft and @flushright
commands are ended by @end flushleft and @end
flushright commands on lines of their own.

For example,

@flushleft
This text is
written flushleft.
@end flushleft

produces

This text is
written flushleft.

@flushright produces the type of indentation often used in the
return address of letters.  For example,

@flushright
Here is an example of text written
flushright.  The @code{@flushright} command
right justifies every line but leaves the
left end ragged.
@end flushright

produces

Here is an example of text written
flushright.  The @flushright command
right justifies every line but leaves the
left end ragged.

Drawing Cartouches Around Examples

In a printed manual, the @cartouche command draws a box with
rounded corners around its contents.  You can use this command to
further highlight an example or quotation.  For instance, you could
write a manual in which one type of example is surrounded by a cartouche
for emphasis.

@cartouche affects only the printed manual; it has no effect in
other output files.

For example,

@example
@cartouche
% pwd
/usr/local/share/emacs
@end cartouche
@end example

surrounds the two-line example with a box with rounded corners, in the
printed manual.

In a printed manual, the example looks like this:

% pwd
/usr/local/lib/emacs/info

Lists and Tables

Texinfo has several ways of making lists and tables.  Lists can be
bulleted or numbered; two-column tables can highlight the items in
the first column; multi-column tables are also supported.

Texinfo automatically indents the text in lists or tables, and numbers
an enumerated list.  This last feature is useful if you modify the
list, since you do not need to renumber it yourself.

Numbered lists and tables begin with the appropriate @-command at the
beginning of a line, and end with the corresponding @end
command on a line by itself.  The table and itemized-list commands
also require that you write formatting information on the same line as
the beginning @-command.

Begin an enumerated list, for example, with an @enumerate
command and end the list with an @end enumerate command.
Begin an itemized list with an @itemize command, followed on
the same line by a formatting command such as @bullet, and end
the list with an @end itemize command.

Precede each element of a list with an @item or @itemx
command.

Here is an itemized list of the different kinds of table and lists:

  •

Itemized lists with and without bullets.

  •

Enumerated lists, using numbers or letters.

  •

Two-column tables with highlighting.

Here is an enumerated list with the same items:

  1.

Itemized lists with and without bullets.

  2.

Enumerated lists, using numbers or letters.

  3.

Two-column tables with highlighting.

And here is a two-column table with the same items and their
@-commands:

@itemize

Itemized lists with and without bullets.

@enumerate

Enumerated lists, using numbers or letters.

@table

@ftable

@vtable

Two-column tables, optionally with indexing.

@itemize: Making an Itemized List

The @itemize command produces sequences of indented
paragraphs, with a bullet or other mark inside the left margin
at the beginning of each paragraph for which such a mark is desired.

Begin an itemized list by writing @itemize at the beginning of
a line.  Follow the command, on the same line, with a character or a
Texinfo command that generates a mark.  Usually, you will write
@bullet after @itemize, but you can use
@minus, or any command or character that results in a single
character in the Info file.  If you don't want any mark at all, use
@w.  (When you write the mark command such as
@bullet after an @itemize command, you may omit the
`{}'.)  If you don't specify a mark command, the default is
@bullet.

Write the text of the indented paragraphs themselves after the
@itemize, up to another line that says @end
itemize.

Before each paragraph for which a mark in the margin is desired, write a
line that says just @item.  It is ok to have text following the
@item.

Usually, you should put a blank line before an @item.  This
puts a blank line in the Info file. (TeX inserts the proper
interline whitespace in either case.)  Except when the entries are
very brief, these blank lines make the list look better.

Here is an example of the use of @itemize, followed by the
output it produces.  @bullet produces an `*' in Info and a
round dot in TeX.

@itemize @bullet
@item
Some text for foo.

@item
Some text
for bar.
@end itemize

This produces:

  •

Some text for foo.

  •

Some text
for bar.

Itemized lists may be embedded within other itemized lists.  Here is a
list marked with dashes embedded in a list marked with bullets:

@itemize @bullet
@item
First item.

@itemize @minus
@item
Inner item.

@item
Second inner item.
@end itemize

@item
Second outer item.
@end itemize

This produces:

  •

First item.

    •

Inner item.

    •

Second inner item.

  •

Second outer item.

@enumerate: Making a Numbered or Lettered List

@enumerate is like @itemize (see section @itemize: Making an Itemized List), except that the labels on the items are
successive integers or letters instead of bullets.

Write the @enumerate command at the beginning of a line.  The
command does not require an argument, but accepts either a number or a
letter as an option.  Without an argument, @enumerate starts the
list with the number `1'.  With a numeric argument, such as
`3', the command starts the list with that number.  With an upper
or lower case letter, such as `a' or `A', the command starts
the list with that letter.

Write the text of the enumerated list in the same way you write an
itemized list: put @item on a line of its own before the start
of each paragraph that you want enumerated.  Do not write any other text
on the line beginning with @item.

You should put a blank line between entries in the list.
This generally makes it easier to read the Info file.

Here is an example of @enumerate without an argument:

@enumerate
@item
Underlying causes.

@item
Proximate causes.
@end enumerate

This produces:

  1.

Underlying causes.

  2.

Proximate causes.

Here is an example with an argument of 3:

@enumerate 3
@item
Predisposing causes.

@item
Precipitating causes.

@item
Perpetuating causes.
@end enumerate

This produces:

  1.

Predisposing causes.

  2.

Precipitating causes.

  3.

Perpetuating causes.

Here is a brief summary of the alternatives.  The summary is constructed
using @enumerate with an argument of a.

  1.

@enumerate

Without an argument, produce a numbered list, starting with the number
1.

  2.

@enumerate positive-integer

With a (positive) numeric argument, start a numbered list with that
number.  You can use this to continue a list that you interrupted with
other text.

  3.

@enumerate upper-case-letter

With an upper case letter as argument, start a list
in which each item is marked
by a letter, beginning with that upper case letter.

  4.

@enumerate lower-case-letter

With a lower case letter as argument, start a list
in which each item is marked by
a letter, beginning with that lower case letter.

You can also nest enumerated lists, as in an outline.

Making a Two-column Table

@table is similar to @itemize (see section @itemize: Making an Itemized List), but allows you to specify a name or heading line for
each item.  The @table command is used to produce two-column
tables, and is especially useful for glossaries, explanatory
exhibits, and command-line option summaries.

Write the @table command at the beginning of a line and follow
it on the same line with an argument that is a Texinfo "indicating"
command such as @code, @samp, @var, or
@kbd (see section Indicating Definitions, Commands, etc.).  Although these commands are usually
followed by arguments in braces, in this case you use the command name
without an argument because @item will supply the argument.
This command will be applied to the text that goes into the first column
of each item and determines how it will be highlighted.  For example,
@code will cause the text in the first column to be highlighted
with an @code command.  (We recommend @code for
@table's of command-line options.)

You may also choose to use the @asis command as an argument to
@table.  @asis is a command that does nothing; if you
use this command after @table, TeX and the Info formatting
commands output the first column entries without added highlighting
("as is").

(The @table command may work with other commands besides those
listed here.  However, you can only use commands that normally take
arguments in braces.)

Begin each table entry with an @item command at the beginning
of a line.  Write the first column text on the same line as the
@item command.  Write the second column text on the line
following the @item line and on subsequent lines.  (You do not
need to type anything for an empty second column entry.)  You may
write as many lines of supporting text as you wish, even several
paragraphs.  But only text on the same line as the @item will
be placed in the first column, including any footnote.

Normally, you should put a blank line before an @item line.
This puts a blank like in the Info file.  Except when the entries are
very brief, a blank line looks better.

The following table, for example, highlights the text in the first
column with an @samp command:

@table @samp
@item foo
This is the text for
@samp{foo}.

@item bar
Text for @samp{bar}.
@end table

This produces:

`foo'

This is the text for
`foo'.

`bar'

Text for `bar'.

If you want to list two or more named items with a single block of
text, use the @itemx command.  (See section @itemx.)

@ftable and @vtable

The @ftable and @vtable commands are the same as the
@table command except that @ftable automatically enters
each of the items in the first column of the table into the index of
functions and @vtable automatically enters each of the items in
the first column of the table into the index of variables.  This
simplifies the task of creating indices.  Only the items on the same
line as the @item commands are indexed, and they are indexed in
exactly the form that they appear on that line.  See section Indices,
for more information about indices.

Begin a two-column table using @ftable or @vtable by
writing the @-command at the beginning of a line, followed on the same
line by an argument that is a Texinfo command such as @code,
exactly as you would for an @table command; and end the table
with an @end ftable or @end vtable command on a line by
itself.

See the example for @table in the previous section.

@itemx

Use the @itemx command inside a table when you have two or more
first column entries for the same item, each of which should appear on a
line of its own.  Use @itemx for all but the first entry;
@itemx should always follow an @item command.  The
@itemx command works exactly like @item except that it
does not generate extra vertical space above the first column text.

For example,

@table @code
@item upcase
@itemx downcase
These two functions accept a character or a string as
argument, and return the corresponding upper case (lower
case) character or string.
@end table

This produces:

upcase

downcase

These two functions accept a character or a string as
argument, and return the corresponding upper case (lower
case) character or string.

(Note also that this example illustrates multi-line supporting text in
a two-column table.)

Multi-column Tables

@multitable allows you to construct tables with any number of
columns, with each column having any width you like.

You define the column widths on the @multitable line itself, and
write each row of the actual table following an @item command,
with columns separated by an @tab command.  Finally, @end
multitable completes the table.  Details in the sections below.

Multitable Column Widths

You can define the column widths for a multitable in two ways: as
fractions of the line length; or with a prototype row.  Mixing the two
methods is not supported.  In either case, the widths are defined
entirely on the same line as the @multitable command.

  1.

To specify column widths as fractions of the line length, write
@columnfractions and the decimal numbers (presumably less than
1) after the @multitable command, as in:

    @multitable @columnfractions .33 .33 .33

The fractions need not add up exactly to 1.0, as these do
not.  This allows you to produce tables that do not need the full line
length.  You can use a leading zero if you wish.

  2.

To specify a prototype row, write the longest entry for each column
enclosed in braces after the @multitable command.  For example:

    @multitable {some text for column one} {for column two}

The first column will then have the width of the typeset `some text for
column one', and the second column the width of `for column two'.

The prototype entries need not appear in the table itself.

Although we used simple text in this example, the prototype entries can
contain Texinfo commands; markup commands such as @code are
particularly likely to be useful.

Multitable Rows

After the @multitable command defining the column widths (see
the previous section), you begin each row in the body of a multitable
with @item, and separate the column entries with @tab.
Line breaks are not special within the table body, and you may break
input lines in your source file as necessary.

Here is a complete example of a multi-column table (the text is from
The GNU Emacs Manual, see section `Splitting Windows' in The GNU Emacs Manual):

@multitable @columnfractions .15 .45 .4
@item Key @tab Command @tab Description
@item C-x 2
@tab @code{split-window-vertically}
@tab Split the selected window into two windows,
with one above the other.
@item C-x 3
@tab @code{split-window-horizontally}
@tab Split the selected window into two windows
positioned side by side.
@item C-Mouse-2
@tab
@tab In the mode line or scroll bar of a window,
split that window.
@end multitable

produces:

Key C-x 2
C-x 3
C-Mouse-2

Command | Description
split-window-vertically | Split the selected window into two windows, with one above the other.
split-window-horizontally | Split the selected window into two windows positioned side by side.
 | In the mode line or scroll bar of a window, split that window.

Indices

Using Texinfo, you can generate indices without having to sort and
collate entries manually.  In an index, the entries are listed in
alphabetical order, together with information on how to find the
discussion of each entry.  In a printed manual, this information
consists of page numbers.  In an Info file, this information is a menu
entry leading to the first node referenced.

Texinfo provides several predefined kinds of index: an index
for functions, an index for variables, an index for concepts, and so
on.  You can combine indices or use them for other than their
canonical purpose.  If you wish, you can define your own indices.

Making Index Entries

When you are making index entries, it is good practice to think of the
different ways people may look for something.  Different people
do not think of the same words when they look something up.  A
helpful index will have items indexed under all the different words
that people may use.  For example, one reader may think it obvious that
the two-letter names for indices should be listed under "Indices,
two-letter names", since the word "Index" is the general concept.
But another reader may remember the specific concept of two-letter
names and search for the entry listed as "Two letter names for
indices".  A good index will have both entries and will help both
readers.

Like typesetting, the construction of an index is a highly skilled,
professional art, the subtleties of which are not appreciated until you
need to do it yourself.

See section Index Menus and Printing an Index, for information about printing an index
at the end of a book or creating an index menu in an Info file.

Predefined Indices

Texinfo provides six predefined indices:

  •

A concept index listing concepts that are discussed.

  •

A function index listing functions (such as entry points of
libraries).

  •

A variables index listing variables (such as global variables
of libraries).

  •

A keystroke index listing keyboard commands.

  •

A program index listing names of programs.

  •

A data type index listing data types (such as structures defined in
header files).

Not every manual needs all of these, and most manuals use two or three
of them.  This manual has two indices: a
concept index and an @-command index (that is actually the function
index but is called a command index in the chapter heading).  Two or
more indices can be combined into one using the @synindex or
@syncodeindex commands.  See section Combining Indices.

Defining the Entries of an Index

The data to make an index come from many individual indexing commands
scattered throughout the Texinfo source file.  Each command says to add
one entry to a particular index; after formatting, the index will give
the current page number or node name as the reference.

An index entry consists of an indexing command at the beginning of a
line followed, on the rest of the line, by the entry.

For example, this section begins with the following five entries for
the concept index:

@cindex Defining indexing entries
@cindex Index entries
@cindex Entries for an index
@cindex Specifying index entries
@cindex Creating index entries

Each predefined index has its own indexing command---@cindex
for the concept index, @findex for the function index, and so
on.

Concept index entries consist of text.  The best way to write an index
is to choose entries that are terse yet clear.  If you can do this,
the index often looks better if the entries are not capitalized, but
written just as they would appear in the middle of a sentence.
(Capitalize proper names and acronyms that always call for upper case
letters.)  This is the case convention we use in most GNU manuals'
indices.

If you don't see how to make an entry terse yet clear, make it longer
and clear--not terse and confusing.  If many of the entries are several
words long, the index may look better if you use a different convention:
to capitalize the first word of each entry.  But do not capitalize a
case-sensitive name such as a C or Lisp function name or a shell
command; that would be a spelling error.

Whichever case convention you use, please use it consistently!

Entries in indices other than the concept index are symbol names in
programming languages, or program names; these names are usually
case-sensitive, so use upper and lower case as required for them.

By default, entries for a concept index are printed in a small roman
font and entries for the other indices are printed in a small
@code font.  You may change the way part of an entry is
printed with the usual Texinfo commands, such as @file for
file names and @emph for emphasis (see section Marking Words and Phrases).

The six indexing commands for predefined indices are:

@cindex concept

Make an entry in the concept index for concept.

@findex function

Make an entry in the function index for function.

@vindex variable

Make an entry in the variable index for variable.

@kindex keystroke

Make an entry in the key index for keystroke.

@pindex program

Make an entry in the program index for program.

@tindex data type

Make an entry in the data type index for data type.

Caution: Do not use a colon in an index entry.  In Info, a
colon separates the menu entry name from the node name, so a colon in
the entry itself confuses Info.  See section The Parts of a Menu, for more information about the structure of a menu entry.

You are not actually required to use the predefined indices for their
canonical purposes.  For example, suppose you wish to index some C
preprocessor macros.  You could put them in the function index along
with actual functions, just by writing @findex commands for
them; then, when you print the "Function Index" as an unnumbered
chapter, you could give it the title `Function and Macro Index' and
all will be consistent for the reader.  Or you could put the macros in
with the data types by writing @tindex commands for them, and
give that index a suitable title so the reader will understand.
(See section Index Menus and Printing an Index.)

Combining Indices

Sometimes you will want to combine two disparate indices such as functions
and concepts, perhaps because you have few enough of one of them that
a separate index for them would look silly.

You could put functions into the concept index by writing
@cindex commands for them instead of @findex commands,
and produce a consistent manual by printing the concept index with the
title `Function and Concept Index' and not printing the `Function
Index' at all; but this is not a robust procedure.  It works only if
your document is never included as part of another
document that is designed to have a separate function index; if your
document were to be included with such a document, the functions from
your document and those from the other would not end up together.
Also, to make your function names appear in the right font in the
concept index, you would need to enclose every one of them between
the braces of @code.

@syncodeindex

When you want to combine functions and concepts into one index, you
should index the functions with @findex and index the concepts
with @cindex, and use the @syncodeindex command to
redirect the function index entries into the concept index.

The @syncodeindex command takes two arguments; they are the name
of the index to redirect, and the name of the index to redirect it to.
The template looks like this:

@syncodeindex from to

For this purpose, the indices are given two-letter names:

`cp'

concept index

`fn'

function index

`vr'

variable index

`ky'

key index

`pg'

program index

`tp'

data type index

Write an @syncodeindex command before or shortly after the
end-of-header line at the beginning of a Texinfo file.  For example,
to merge a function index with a concept index, write the
following:

@syncodeindex fn cp

This will cause all entries designated for the function index to merge
in with the concept index instead.

To merge both a variables index and a function index into a concept
index, write the following:

@syncodeindex vr cp
@syncodeindex fn cp

The @syncodeindex command puts all the entries from the `from'
index (the redirected index) into the @code font, overriding
whatever default font is used by the index to which the entries are
now directed.  This way, if you direct function names from a function
index into a concept index, all the function names are printed in the
@code font as you would expect.

@synindex

The @synindex command is nearly the same as the
@syncodeindex command, except that it does not put the
`from' index  entries into the @code font; rather it puts
them in the roman font.  Thus, you use @synindex when you
merge a concept index into a function index.

See section Index Menus and Printing an Index, for information about printing an index
at the end of a book or creating an index menu in an Info file.

Defining New Indices

In addition to the predefined indices, you may use the
@defindex and @defcodeindex commands to define new
indices.  These commands create new indexing @-commands with which
you mark index entries.  The @defindex command is used like
this:

@defindex name

The name of an index should be a two letter word, such as `au'.
For example:

@defindex au

This defines a new index, called the `au' index.  At the same
time, it creates a new indexing command, @auindex, that you
can use to make index entries.  Use the new indexing command just as
you would use a predefined indexing command.

For example, here is a section heading followed by a concept index
entry and two `au' index entries.

@section Cognitive Semantics
@cindex kinesthetic image schemas
@auindex Johnson, Mark
@auindex Lakoff, George

(Evidently, `au' serves here as an abbreviation for "author".)
Texinfo constructs the new indexing command by concatenating the name
of the index with `index'; thus, defining an `au' index
leads to the automatic creation of an @auindex command.

Use the @printindex command to print the index, as you do with
the predefined indices.  For example:

@node Author Index, Subject Index, , Top
@unnumbered Author Index

@printindex au

The @defcodeindex is like the @defindex command, except
that, in the printed output, it prints entries in an @code font
instead of a roman font.  Thus, it parallels the @findex command
rather than the @cindex command.

You should define new indices within or right after the end-of-header
line of a Texinfo file, before any @synindex or
@syncodeindex commands (see section The Texinfo File Header).

Special Insertions

Texinfo provides several commands for inserting characters that have
special meaning in Texinfo, such as braces, and for other graphic
elements that do not correspond to simple characters you can type.

These are:

  • Braces and `@'.

  • Whitespace within and around a sentence.

  • Accents.

  • Dots and bullets.

  • The TeX logo and the copyright symbol.

  • The pounds currency symbol.

  • The minus sign.

  • Mathematical expressions.

  • Glyphs for evaluation, macros, errors, etc.

  • Footnotes.

  • Images.

Inserting @ and Braces

`@' and curly braces are special characters in Texinfo.  To insert
these characters so they appear in text, you must put an `@' in
front of these characters to prevent Texinfo from misinterpreting
them.

Do not put braces after any of these commands; they are not
necessary.

Inserting `@' with @@

@@ stands for a single `@' in either printed or Info
output.

Do not put braces after an @@ command.

Inserting `{' and `}'with @{ and @}

@{ stands for a single `{' in either printed or Info
output.

@} stands for a single `}' in either printed or Info
output.

Do not put braces after either an @{ or an @}
command.

Inserting Space

The following sections describe commands that control spacing of various
kinds within and after sentences.

Not Ending a Sentence

Depending on whether a period or exclamation point or question mark is
inside or at the end of a sentence, less or more space is inserted after
a period in a typeset manual.  Since it is not always possible
to determine when a period ends a sentence and when it is used
in an abbreviation, special commands are needed in some circumstances.
Usually, Texinfo can guess how to handle periods, so you do not need to
use the special commands; you just enter a period as you would if you
were using a typewriter, which means you put two spaces after the
period, question mark, or exclamation mark that ends a sentence.

Use the @: command after a period, question mark,
exclamation mark, or colon that should not be followed by extra space.
For example, use @: after periods that end abbreviations
which are not at the ends of sentences.

For example,

The s.o.p.@: has three parts ...
The s.o.p. has three parts ...

produces the following.  If you look carefully at this printed output,
you will see a little more whitespace after `s.o.p.' in the second
line.

The s.o.p. has three parts ...

The s.o.p. has three parts ...

(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
Procedure".)

@: has no effect on the Info output.  Do not put braces after
@:.

Ending a Sentence

Use @. instead of a period, @! instead of an
exclamation point, and @? instead of a question mark at the end
of a sentence that ends with a single capital letter.  Otherwise, TeX
will think the letter is an abbreviation and will not insert the correct
end-of-sentence spacing.  Here is an example:

Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

produces the following.  If you look carefully at this printed output,
you will see a little more whitespace after the `W' in the first
line.

Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

In the Info file output, @. is equivalent to a simple
`.'; likewise for @! and @?.

The meanings of @: and @. in Texinfo are designed to
work well with the Emacs sentence motion commands (see section `Sentences' in The GNU Emacs Manual).

Do not put braces after any of these commands.

Multiple Spaces

Ordinarily, TeX collapses multiple whitespace characters (space, tab,
and newline) into a single space.  Info output, on the other hand,
preserves whitespace as you type it, except for changing a newline into
a space; this is why it is important to put two spaces at the end of
sentences in Texinfo documents.

Occasionally, you may want to actually insert several consecutive
spaces, either for purposes of example (what your program does with
multiple spaces as input), or merely for purposes of appearance in
headings or lists.  Texinfo supports three commands:
@SPACE, @TAB, and @NL, all of
which insert a single space into the output.  (Here,
@SPACE represents an `@' character followed by a
space, i.e., `@ ', and TAB and NL represent the tab
character and end-of-line, i.e., when `@' is the last character on
a line.)

For example,

Spacey@ @ @ @
example.

produces

Spacey
example.

Other possible uses of @SPACE have been subsumed by
@multitable (see section Multi-column Tables).

Do not follow any of these commands with braces.

@dmn{dimension}: Format a Dimension

At times, you may want to write `12pt' or
`8.5in' with little or no space between the number and the
abbreviation for the dimension.  You can use the @dmn command
to do this.  On seeing the command, TeX inserts just enough space
for proper typesetting; the Info formatting commands insert no space
at all, since the Info file does not require it.

To use the @dmn command, write the number and then follow it
immediately, with no intervening space, by @dmn, and then by
the dimension within braces.  For example,

A4 paper is 8.27@dmn{in} wide.

produces

A4 paper is 8.27in wide.

Not everyone uses this style.  Some people prefer `8.27 in.@:'
or `8.27 inches' to `8.27@dmn{in}' in the Texinfo file.
In these cases, however, the formatters may insert a line break between
the number and the dimension, so use @w (see section @w{text}: Prevent Line Breaks).  Also, if
you write a period after an abbreviation within a sentence, you should
write `@:' after the period to prevent TeX from inserting extra
whitespace, as shown here.  See section Not Ending a Sentence.

Inserting Accents

Here is a table with the commands Texinfo provides for inserting
floating accents.  The commands with non-alphabetic names do not take
braces around their argument (which is taken to be the next character).
(Exception: @, does take braces around its argument.)
This is so as to make the source as convenient to type and read as
possible, since accented characters are very common in some languages.

Command               @"o@'o@,{c}@=o@^o@`o@~o@dotaccent{o}@H{o}@ringaccent{o}@tieaccent{oo}@u{o}@ubaraccent{o}@udotaccent{o}@v{o}
Output | What
@"o | umlaut accent
'o | acute accent
@,{c} | cedilla accent
@=o | macron/overbar accent
@^o | circumflex accent
`o | grave accent
@~o | tilde accent
@dotaccent{o} | overdot accent
@H{o} | long Hungarian umlaut
@ringaccent{o} | ring accent
@tieaccent{oo} | tie-after accent
@u{o} | breve accent
@ubaraccent{o} | underbar accent
@udotaccent{o} | underdot accent
@v{o} | hacek or check accent

This table lists the Texinfo commands for inserting other characters
commonly used in languages other than English.

@exclamdown{}@questiondown{}@aa{},@AA{}@ae{},@AE{}@dotless{i}@dotless{j}@l{},@L{}@o{},@O{}@oe{},@OE{}@ss{}
¡ | upside-down !
¿ | upside-down ?
å,Å | a,A with circle
æ,Æ | ae,AE ligatures
@dotless{i} | dotless i
@dotless{j} | dotless j
l/,L/ | suppressed-L,l
ø,Ø | O,o with slash
oe,OE | oe,OE ligatures
ß | es-zet or sharp S

Inserting Ellipsis and Bullets

An ellipsis (a line of dots) is not typeset as a string of
periods, so a special command is used for ellipsis in Texinfo.  The
@bullet command is special, too.  Each of these commands is
followed by a pair of braces, `{}', without any whitespace
between the name of the command and the braces.  (You need to use braces
with these commands because you can use them next to other text; without
the braces, the formatters would be confused.  See section @-Command Syntax, for further information.)

@dots{} (...) and @enddots{} (....)

Use the @dots{} command to generate an ellipsis, which is
three dots in a row, appropriately spaced, like this: `...'.  Do
not simply write three periods in the input file; that would work for
the Info file output, but would produce the wrong amount of space
between the periods in the printed manual.

Similarly, the @enddots{} command generates an
end-of-sentence ellipsis (four dots) ....

Here is an ellipsis: ...
Here are three periods in a row: ...

In printed output, the three periods in a row are closer together than
the dots in the ellipsis.

@bullet{} (*)

Use the @bullet{} command to generate a large round dot, or
the closest possible thing to one.  In Info, an asterisk is used.

Here is a bullet: *

When you use @bullet in @itemize, you do not need to
type the braces, because @itemize supplies them.
(See section @itemize: Making an Itemized List.)

Inserting TeX and the Copyright Symbol

The logo `TeX' is typeset in a special fashion and it needs an
@-command.  The copyright symbol, `©', is also special.
Each of these commands is followed by a pair of braces, `{}',
without any whitespace between the name of the command and the
braces.

@TeX{} (TeX)

Use the @TeX{} command to generate `TeX'.  In a printed
manual, this is a special logo that is different from three ordinary
letters.  In Info, it just looks like `TeX'.  The
@TeX{} command is unique among Texinfo commands in that the
`T' and the `X' are in upper case.

@copyright{} (©)

Use the @copyright{} command to generate `©'.  In
a printed manual, this is a `c' inside a circle, and in Info,
this is `(C)'.

@pounds{} (£): Pounds Sterling

Use the @pounds{} command to generate `£'.  In a
printed manual, this is the symbol for the currency pounds sterling.
In Info, it is a `#'.  Other currency symbols are unfortunately not
available.

@minus{} (-): Inserting a Minus Sign

Use the @minus{} command to generate a minus sign.  In a
fixed-width font, this is a single hyphen, but in a proportional font,
the symbol is the customary length for a minus sign--a little longer
than a hyphen, shorter than an em-dash:

`-' is a minus sign generated with `@minus{}',

`-' is a hyphen generated with the character `-',

`---' is an em-dash for text.

In the fixed-width font used by Info, @minus{} is the same
as a hyphen.

You should not use @minus{} inside @code or
@example because the width distinction is not made in the
fixed-width font they use.

When you use @minus to specify the mark beginning each entry in
an itemized list, you do not need to type the braces
(see section @itemize: Making an Itemized List.)

@math: Inserting Mathematical Expressions

You can write a short mathematical expression with the @math
command.  Write the mathematical expression between braces, like this:

@math{(a + b)(a + b) = a^2 + 2ab + b^2}

This produces the following in TeX:

(a + b)(a + b) = a^2 + 2ab + b^2

and the following in Info:

(a + b)(a + b) = a^2 + 2ab + b^2

Thus, the @math command has no effect on the Info output.

For complex mathematical expressions, you can also use TeX directly
(see section Raw Formatter Commands).  When you use TeX directly,
remember to write the mathematical expression between one or two
`$' (dollar-signs) as appropriate.

Glyphs for Examples

In Texinfo, code is often illustrated in examples that are delimited
by @example and @end example, or by @lisp and
@end lisp.  In such examples, you can indicate the results of
evaluation or an expansion using `=>' or
`==>'.  Likewise, there are commands to insert glyphs
to indicate
printed output, error messages, equivalence of expressions, and the
location of point.

The glyph-insertion commands do not need to be used within an example, but
most often they are.  Every  glyph-insertion command is followed by a pair of
left- and right-hand braces.

=>

@result{} points to the result of an expression.

==>

@expansion{} shows the results of a macro expansion.

-|

@print{} indicates printed output.

error-->

@error{} indicates that the following text is an error
message.

==

@equiv{} indicates the exact equivalence of two forms.

-!-

@point{} shows the location of point.

@result{} (=>): Indicating Evaluation

Use the @result{} command to indicate the result of
evaluating an expression.

The @result{} command is displayed as `=>' in Info and
as `=>' in the printed output.

Thus, the following,

(cdr '(1 2 3))
     => (2 3)

may be read as "(cdr '(1 2 3)) evaluates to (2 3)".

@expansion{} (==>): Indicating an Expansion

When an expression is a macro call, it expands into a new expression.
You can indicate the result of the expansion with the
@expansion{} command.

The @expansion{} command is displayed as `==>' in Info and
as `==>' in the printed output.

For example, the following

@lisp
(third '(a b c))
     @expansion{} (car (cdr (cdr '(a b c))))
     @result{} c
@end lisp

produces

(third '(a b c))
     ==> (car (cdr (cdr '(a b c))))
     => c

which may be read as:

(third '(a b c)) expands to (car (cdr (cdr '(a b c))));
the result of evaluating the expression is c.

Often, as in this case, an example looks better if the
@expansion{} and @result{} commands are indented
five spaces.

@print{} (-|): Indicating Printed Output

Sometimes an expression will print output during its execution.  You
can indicate the printed output with the @print{} command.

The @print{} command is displayed as `-|' in Info and
as `-|' in the printed output.

In the following example, the printed text is indicated with
`-|', and the value of the expression follows on the
last line.

(progn (print 'foo) (print 'bar))
     -| foo
     -| bar
     => bar

In a Texinfo source file, this example is written as follows:

@lisp
(progn (print 'foo) (print 'bar))
     @print{} foo
     @print{} bar
     @result{} bar
@end lisp

@error{} (error-->): Indicating an Error Message

A piece of code may cause an error when you evaluate it.  You can
designate the error message with the @error{} command.

The @error{} command is displayed as `error-->' in Info
and as `error-->' in the printed output.

Thus,

@lisp
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@end lisp

produces

(+ 23 'x)
error--> Wrong type argument: integer-or-marker-p, x

This indicates that the following error message is printed
when you evaluate the expression:

Wrong type argument: integer-or-marker-p, x

`error-->' itself is not part of the error message.

@equiv{} (==): Indicating Equivalence

Sometimes two expressions produce identical results.  You can indicate the
exact equivalence of two forms with the @equiv{} command.

The @equiv{} command is displayed as `==' in Info and
as `==' in the printed output.

Thus,

@lisp
(make-sparse-keymap) @equiv{} (list 'keymap)
@end lisp

produces

(make-sparse-keymap) == (list 'keymap)

This indicates that evaluating (make-sparse-keymap) produces
identical results to evaluating (list 'keymap).

@point{} (-!-): Indicating Point in a Buffer

Sometimes you need to show an example of text in an Emacs buffer.  In
such examples, the convention is to include the entire contents of the
buffer in question between two lines of dashes containing the buffer
name.

You can use the `@point{}' command to show the location of point
in the text in the buffer.  (The symbol for point, of course, is not
part of the text in the buffer; it indicates the place between
two characters where point is located.)

The @point{} command is displayed as `-!-' in Info and
as `-!-' in the printed output.

The following example shows the contents of buffer `foo' before
and after evaluating a Lisp command to insert the word changed.

---------- Buffer: foo ----------
This is the -!-contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     => nil
---------- Buffer: foo ----------
This is the changed -!-contents of foo.
---------- Buffer: foo ----------

In a Texinfo source file, the example is written like this:

@example
---------- Buffer: foo ----------
This is the @point{}contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     @result{} nil
---------- Buffer: foo ----------
This is the changed @point{}contents of foo.
---------- Buffer: foo ----------
@end example

Footnotes

A footnote is for a reference that documents or elucidates the
primary text.(8)

Footnote Commands

In Texinfo, footnotes are created with the @footnote command.
This command is followed immediately by a left brace, then by the text
of the footnote, and then by a terminating right brace.  Footnotes may
be of any length (they will be broken across pages if necessary), but
are usually short.  The template is:

ordinary text@footnote{text of footnote}

As shown here, the @footnote command should come right after the
text being footnoted, with no intervening space; otherwise, the footnote
marker might end up starting a line.

For example, this clause is followed by a sample footnote(9); in the Texinfo source, it looks like
this:

...a sample footnote@footnote{Here is the sample
footnote.}; in the Texinfo source...

In a printed manual or book, the reference mark for a footnote is a
small, superscripted number; the text of the footnote appears at the
bottom of the page, below a horizontal line.

In Info, the reference mark for a footnote is a pair of parentheses
with the footnote number between them, like this: `(1)'.  The
reference mark is followed by a cross-reference link to the footnote's
text.

In the HTML output, footnote references are marked with a small,
superscripted number which is rendered as a hypertext link to the
footnote text.

By the way, footnotes in the argument of an @item command for a
@table must be on the same line as the @item
(as usual).  See section Making a Two-column Table.

Footnote Styles

Info has two footnote styles, which determine where the text of the
footnote is located:

  •

In the `End' node style, all the footnotes for a single node
are placed at the end of that node.  The footnotes are separated from
the rest of the node by a line of dashes with the word
`Footnotes' within it.  Each footnote begins with an
`(n)' reference mark.
Here is an example of a single footnote in the end of node style:

     --------- Footnotes ---------

(1)  Here is a sample footnote.

  •

In the `Separate' node style, all the footnotes for a single
node are placed in an automatically constructed node of
their own.  In this style, a "footnote reference" follows
each `(n)' reference mark in the body of the
node.  The footnote reference is actually a cross reference
which you use to reach the footnote node.
The name of the node with the footnotes is constructed
by appending `-Footnotes' to the name of the node
that contains the footnotes. (Consequently, the footnotes'
node for the `Footnotes' node is
`Footnotes-Footnotes'!)  The footnotes' node has an
`Up' node pointer that leads back to its parent node.
Here is how the first footnote in this manual looks after being
formatted for Info in the separate node style:

    File: texinfo.info  Node: Overview-Footnotes, Up: Overview

(1) The first syllable of "Texinfo" is pronounced like "speck", not
"hex". ...

A Texinfo file may be formatted into an Info file with either footnote
style.

Use the @footnotestyle command to specify an Info file's
footnote style.  Write this command at the beginning of a line followed
by an argument, either `end' for the end node style or
`separate' for the separate node style.

For example,

@footnotestyle end

or

@footnotestyle separate

Write an @footnotestyle command before or shortly after the
end-of-header line at the beginning of a Texinfo file.  (If you
include the @footnotestyle command between the start-of-header
and end-of-header lines, the region formatting commands will format
footnotes as specified.)

If you do not specify a footnote style, the formatting commands use
their default style.  Currently, texinfo-format-buffer and
texinfo-format-region use the `separate' style and
makeinfo uses the `end' style.

Inserting Images

You can insert an image given in an external file with the
@image command:

@image{filename, [width], [height]}

The filename argument is mandatory, and must not have an
extension, because the different processors support different formats:

  •

TeX reads the file `filename.eps' (Encapsulated PostScript
format).

  •

PDFTeX reads `filename.pdf' (Adobe's Portable Document Format).

  •

makeinfo uses `filename.txt' verbatim for
Info output (more or less as if it was an @example).

  •

makeinfo producing HTML output tries `filename.png';
if that does not exist, it tries `filename.jpg'.  If that
does not exist either, it complains.  (We cannot support GIF format due
to patents.)

The optional width and height arguments specify the size to
scale the image to (they are ignored for Info output).  If neither is
specified, the image is presented in its natural size (given in the
file); if only one is specified, the other is scaled proportionately;
and if both are specified, both are respected, thus possibly distorting
the original image by changing its aspect ratio.

The width and height may be specified using any valid TeX
dimension, namely:

pt

point (72.27pt = 1in)

pc

pica (1pc = 12pt)

bp

big point (72bp = 1in)

in

inch

cm

centimeter (2.54cm = 1in)

mm

millimeter (10mm = 1cm)

dd

did@^ot point (1157dd = 1238pt)

cc

cicero (1cc = 12dd)

sp

scaled point (65536sp = 1pt)

For example, the following will scale a file `ridt.eps' to one
inch vertically, with the width scaled proportionately:

@image{ridt,,1in}

For @image to work with TeX, the file `epsf.tex' must be
installed somewhere that TeX can find it.  (The standard location is
`texmf/tex/generic/dvips/epsf.tex', where texmf is a
root of your TeX directory tree.)  This file is included in the
Texinfo distribution and is available from
ftp://tug.org/tex/epsf.tex.

@image can be used within a line as well as for displayed
figures.  Therefore, if you intend it to be displayed, be sure to leave
a blank line before the command, or the output will run into the
preceding text.

Making and Preventing Breaks

Usually, a Texinfo file is processed both by TeX and by one of the
Info formatting commands.  Line, paragraph, or page breaks sometimes
occur in the `wrong' place in one or other form of output.  You must
ensure that text looks right both in the printed manual and in the
Info file.

For example, in a printed manual, page breaks may occur awkwardly in
the middle of an example; to prevent this, you can hold text together
using a grouping command that keeps the text from being split across
two pages.  Conversely, you may want to force a page break where none
would occur normally.  Fortunately, problems like these do not often
arise.  When they do, use the break, break prevention, or pagination
commands.

The break commands create or allow line and paragraph breaks:

@*

Force a line break.

@sp n

Skip n blank lines.

@-

Insert a discretionary hyphen.

@hyphenation{hy-phen-a-ted words}

Define hyphen points in hy-phen-a-ted words.

The line-break-prevention command holds text together all on one
line:

@w{text}

Prevent text from being split and hyphenated across two lines.

The pagination commands apply only to printed output, since Info
files do not have pages.

@page

Start a new page in the printed manual.

@group

Hold text together that must appear on one printed page.

@need mils

Start a new printed page if not enough space on this one.

@*: Generate Line Breaks

The @* command forces a line break in both the printed manual and
in Info.

For example,

This line @* is broken @*in two places.

produces

This line
 is broken
in two places.

(Note that the space after the first @* command is faithfully
carried down to the next line.)

The @* command is often used in a file's copyright page:

This is edition 2.0 of the Texinfo documentation,@*
and is for ...

In this case, the @* command keeps TeX from stretching the
line across the whole page in an ugly manner.

Please note: Do not write braces after an @* command;
they are not needed.

Do not write an @refill command at the end of a paragraph
containing an @* command; it will cause the paragraph to be
refilled after the line break occurs, negating the effect of the line
break.

@- and @hyphenation: Helping TeX hyphenate

Although TeX's hyphenation algorithm is generally pretty good, it
does miss useful hyphenation points from time to time.  (Or, far more
rarely, insert an incorrect hyphenation.)  So, for documents with an
unusual vocabulary or when fine-tuning for a printed edition, you may
wish to help TeX out.  Texinfo supports two commands for this:

@-

Insert a discretionary hyphen, i.e., a place where TeX can (but does
not have to) hyphenate.  This is especially useful when you notice
an overfull hbox is due to TeX missing a hyphenation (see section Overfull "hboxes").  TeX will not insert any hyphenation points in a word
containing @-.

@hyphenation{hy-phen-a-ted words}

Tell TeX how to hyphenate hy-phen-a-ted words.  As shown, you
put a `-' at each hyphenation point.  For example:

@hyphenation{man-u-script man-u-scripts}

TeX only uses the specified hyphenation points when the
words match exactly, so give all necessary variants.

Info output is not hyphenated, so these commands have no effect there.

@w{text}: Prevent Line Breaks

@w{text} outputs text and prohibits line breaks
within text.

You can use the @w command to prevent TeX from automatically
hyphenating a long name or phrase that happens to fall near the end of a
line.  For example:

You can copy GNU software from @w{@samp{ftp.gnu.org}}.

produces

You can copy GNU software from `ftp.gnu.org'.

You can also use @w to produce a non-breakable space:

None of the formatters will break at this@w{ }space.

@sp n: Insert Blank Lines

A line beginning with and containing only @sp n
generates n blank lines of space in both the printed manual and
the Info file.  @sp also forces a paragraph break.  For
example,

@sp 2

generates two blank lines.

The @sp command is most often used in the title page.

@page: Start a New Page

A line containing only @page starts a new page in a printed
manual.  The command has no effect on Info files since they are not
paginated.  An @page command is often used in the @titlepage
section of a Texinfo file to start the copyright page.

@group: Prevent Page Breaks

The @group command (on a line by itself) is used inside an
@example or similar construct to begin an unsplittable vertical
group, which will appear entirely on one page in the printed output.
The group is terminated by a line containing only @end group.
These two lines produce no output of their own, and in the Info file
output they have no effect at all.

Although @group would make sense conceptually in a wide
variety of contexts, its current implementation works reliably only
within @example and variants, and within @display,
@format, @flushleft and @flushright.
See section Quotations and Examples.  (What all these commands have in
common is that each line of input produces a line of output.)  In
other contexts, @group can cause anomalous vertical
spacing.

This formatting requirement means that you should write:

@example
@group
...
@end group
@end example

with the @group and @end group commands inside the
@example and @end example commands.

The @group command is most often used to hold an example
together on one page.  In this Texinfo manual, more than 100 examples
contain text that is enclosed between @group and @end
group.

If you forget to end a group, you may get strange and unfathomable
error messages when you run TeX.  This is because TeX keeps
trying to put the rest of the Texinfo file onto the one page and does
not start to generate error messages until it has processed
considerable text.  It is a good rule of thumb to look for a missing
@end group if you get incomprehensible error messages in
TeX.

@need mils: Prevent Page Breaks

A line containing only @need n starts
a new page in a printed manual if fewer than n mils (thousandths
of an inch) remain on the current page.  Do not use
braces around the argument n.  The @need command has no
effect on Info files since they are not paginated.

This paragraph is preceded by an @need command that tells
TeX to start a new page if fewer than 800 mils (eight-tenths
inch) remain on the page.  It looks like this:

@need 800
This paragraph is preceded by ...

The @need command is useful for preventing orphans (single
lines at the bottoms of printed pages).

Definition Commands

The @deffn command and the other definition commands
enable you to describe functions, variables, macros, commands, user
options, special forms and other such artifacts in a uniform
format.

In the Info file, a definition causes the entity
category---`Function', `Variable', or whatever--to appear at the
beginning of the first line of the definition, followed by the
entity's name and arguments.  In the printed manual, the command
causes TeX to print the entity's name and its arguments on the left
margin and print the category next to the right margin.  In both
output formats, the body of the definition is indented.  Also, the
name of the entity is entered into the appropriate index:
@deffn enters the name into the index of functions,
@defvr enters it into the index of variables, and so
on.

A manual need not and should not contain more than one definition for
a given name.  An appendix containing a summary should use
@table rather than the definition commands.

The Template for a Definition

The @deffn command is used for definitions of entities that
resemble functions.  To write a definition using the @deffn
command, write the @deffn command at the beginning of a line
and follow it on the same line by the category of the entity, the name
of the entity itself, and its arguments (if any).  Then write the body
of the definition on succeeding lines.  (You may embed examples in the
body.)  Finally, end the definition with an @end deffn command
written on a line of its own.  (The other definition commands follow
the same format.)

The template for a definition looks like this:

@deffn category name arguments...
body-of-definition
@end deffn

For example,

@deffn Command forward-word count
This command moves point forward @var{count} words
(or backward if @var{count} is negative). ...
@end deffn

produces

Command: forward-word count

This function moves point forward count words
(or backward if count is negative). ...

Capitalize the category name like a title.  If the name of the
category contains spaces, as in the phrase `Interactive Command',
write braces around it.  For example:

@deffn {Interactive Command} isearch-forward
...
@end deffn

Otherwise, the second word will be mistaken for the name of the
entity.

Some of the definition commands are more general than others.  The
@deffn command, for example, is the general definition command
for functions and the like--for entities that may take arguments.  When
you use this command, you specify the category to which the entity
belongs.  The @deffn command possesses three predefined,
specialized variations, @defun, @defmac, and
@defspec, that specify the category for you: "Function",
"Macro", and "Special Form" respectively.  (In Lisp, a special form
is an entity much like a function.)  The @defvr command also is
accompanied by several predefined, specialized variations for describing
particular kinds of variables.

The template for a specialized definition, such as @defun, is
similar to the template for a generalized definition, except that you
do not need to specify the category:

@defun name arguments...
body-of-definition
@end defun

Thus,

@defun buffer-end flag
This function returns @code{(point-min)} if @var{flag}
is less than 1, @code{(point-max)} otherwise.
...
@end defun

produces

Function: buffer-end flag

This function returns (point-min) if flag is less than 1,
(point-max) otherwise.  ...

See section A Sample Function Definition, for a more detailed example of a function
definition, including the use of @example inside the
definition.

The other specialized commands work like @defun.

Optional and Repeated Arguments

Some entities take optional or repeated arguments, which may be
specified by a distinctive glyph that uses square brackets and
ellipses.  For example, a special form often breaks its argument list
into separate arguments in more complicated ways than a
straightforward function.

An argument enclosed within square brackets is optional.
Thus, the phrase
`[optional-arg]' means that
optional-arg is optional.
An argument followed by an ellipsis is optional
and may be repeated more than once.
Thus, `repeated-args...' stands for zero or more arguments.
Parentheses are used when several arguments are grouped
into additional levels of list structure in Lisp.

Here is the @defspec line of an example of an imaginary
special form:

Special Form: foobar (var [from to [inc]]) body...

In this example, the arguments from and to are optional,
but must both be present or both absent.  If they are present,
inc may optionally be specified as well.  These arguments are
grouped with the argument var into a list, to distinguish them
from body, which includes all remaining elements of the
form.

In a Texinfo source file, this @defspec line is written like
this (except it would not be split over two lines, as it is in this
example).

@defspec foobar (@var{var} [@var{from} @var{to}
     [@var{inc}]]) @var{body}@dots{}

The function is listed in the Command and Variable Index under
`foobar'.

Two or More `First' Lines

To create two or more `first' or header lines for a definition, follow
the first @deffn line by a line beginning with @deffnx.
The @deffnx command works exactly like @deffn
except that it does not generate extra vertical white space between it
and the preceding line.

For example,

@deffn {Interactive Command} isearch-forward
@deffnx {Interactive Command} isearch-backward
These two search commands are similar except ...
@end deffn

produces

Interactive Command: isearch-forward

Interactive Command: isearch-backward

These two search commands are similar except ...

Each definition command has an `x' form: @defunx,
@defvrx, @deftypefunx, etc.

The `x' forms work just like @itemx; see section @itemx.

The Definition Commands

Texinfo provides more than a dozen definition commands, all of which
are described in this section.

The definition commands automatically enter the name of the entity in
the appropriate index: for example, @deffn, @defun,
and @defmac enter function names in the index of functions;
@defvr and @defvar enter variable names in the index
of variables.

Although the examples that follow mostly illustrate Lisp, the commands
can be used for other programming languages.

Functions and Similar Entities

This section describes the commands for describing functions and similar
entities:

@deffn category name arguments...

The @deffn command is the general definition command for
functions, interactive commands, and similar entities that may take
arguments.  You must choose a term to describe the category of entity
being defined; for example, "Function" could be used if the entity is
a function.  The @deffn command is written at the beginning of a
line and is followed on the same line by the category of entity being
described, the name of this particular entity, and its arguments, if
any.  Terminate the definition with @end deffn on a line of its
own.
For example, here is a definition:

@deffn Command forward-char nchars
Move point forward @var{nchars} characters.
@end deffn

This shows a rather terse definition for a "command" named
forward-char with one argument, nchars.

@deffn prints argument names such as nchars in italics or
upper case, as if @var had been used, because we think of these
names as metasyntactic variables--they stand for the actual argument
values.  Within the text of the description, write an argument name
explicitly with @var to refer to the value of the argument.  In
the example above, we used `@var{nchars}' in this way.

The template for @deffn is:

@deffn category name arguments...
body-of-definition
@end deffn

@defun name arguments...

The @defun command is the definition command for functions.
@defun is equivalent to `@deffn Function
...'.
For example,

@defun set symbol new-value
Change the value of the symbol @var{symbol}
to @var{new-value}.
@end defun

shows a rather terse definition for a function set whose
arguments are symbol and new-value.  The argument names on
the @defun line automatically appear in italics or upper case as
if they were enclosed in @var.  Terminate the definition with
@end defun on a line of its own.
The template is:

@defun function-name arguments...
body-of-definition
@end defun

@defun creates an entry in the index of functions.

@defmac name arguments...

The @defmac command is the definition command for macros.
@defmac is equivalent to `@deffn Macro ...' and
works like @defun.

@defspec name arguments...

The @defspec command is the definition command for special
forms.  (In Lisp, a special form is an entity much like a function,
see section `Special Forms' in GNU Emacs Lisp Reference Manual.)
@defspec is equivalent to `@deffn {Special Form}
...' and works like @defun.

Variables and Similar Entities

Here are the commands for defining variables and similar
entities:

@defvr category name

The @defvr command is a general definition command for
something like a variable--an entity that records a value.  You must
choose a term to describe the category of entity being defined; for
example, "Variable" could be used if the entity is a variable.
Write the @defvr command at the beginning of a line and
follow it on the same line by the category of the entity and the
name of the entity.

Capitalize the category name like a title.  If the name of the category
contains spaces, as in the name "User Option", enclose it in braces.
Otherwise, the second word will be mistaken for the name of the entity.
For example,

@defvr {User Option} fill-column
This buffer-local variable specifies
the maximum width of filled lines.
...
@end defvr

Terminate the definition with @end defvr on a line of its
own.
The template is:

@defvr category name
body-of-definition
@end defvr

@defvr creates an entry in the index of variables for name.

@defvar name

The @defvar command is the definition command for variables.
@defvar is equivalent to `@defvr Variable
...'.
For example:

@defvar kill-ring
...
@end defvar

The template is:

@defvar name
body-of-definition
@end defvar

@defvar creates an entry in the index of variables for
name.

@defopt name

The @defopt command is the definition command for user
options, i.e., variables intended for users to change according to
taste; Emacs has many such (see section `Variables' in The GNU Emacs Manual).  @defopt is equivalent to `@defvr {User
Option} ...' and works like @defvar.

Functions in Typed Languages

The @deftypefn command and its variations are for describing
functions in languages in which you must declare types of variables and
functions, such as C and C++.

@deftypefn category data-type name arguments...

The @deftypefn command is the general definition command for
functions and similar entities that may take arguments and that are
typed.  The @deftypefn command is written at the beginning of
a line and is followed on the same line by the category of entity
being described, the type of the returned value, the name of this
particular entity, and its arguments, if any.
For example,

@deftypefn {Library Function} int foobar
   (int @var{foo}, float @var{bar})
...
@end deftypefn

(where the text before the "...", shown above as two lines, would
actually be a single line in a real Texinfo file) produces the following
in Info:

-- Library Function: int foobar (int FOO, float BAR)
...

In a printed manual, it produces:

Library Function: int foobar (int foo, float bar)

...

This means that foobar is a "library function" that returns an
int, and its arguments are foo (an int) and
bar (a float).
The argument names that you write in @deftypefn are not subject
to an implicit @var---since the actual names of the arguments in
@deftypefn are typically scattered among data type names and
keywords, Texinfo cannot find them without help.  Instead, you must write
@var explicitly around the argument names.  In the example
above, the argument names are `foo' and `bar'.
The template for @deftypefn is:

@deftypefn category data-type name arguments ...
body-of-description
@end deftypefn

Note that if the category or data type is more than one
word then it must be enclosed in braces to make it a single argument.
If you are describing a procedure in a language that has packages,
such as Ada, you might consider using @deftypefn in a manner
somewhat contrary to the convention described in the preceding
paragraphs.
For example:

@deftypefn stacks private push
        (@var{s}:in out stack;
        @var{n}:in integer)
...
@end deftypefn

(The @deftypefn arguments are shown split into three lines, but
would be a single line in a real Texinfo file.)

In this instance, the procedure is classified as belonging to the
package stacks rather than classified as a `procedure' and its
data type is described as private.  (The name of the procedure
is push, and its arguments are s and n.)
@deftypefn creates an entry in the index of functions for
name.

@deftypefun data-type name arguments...

The @deftypefun command is the specialized definition command
for functions in typed languages.  The command is equivalent to
`@deftypefn Function ...'.
Thus,

@deftypefun int foobar (int @var{foo}, float @var{bar})
...
@end deftypefun

produces the following in Info:

-- Function: int foobar (int FOO, float BAR)
...

and the following in a printed manual:

Function: int foobar (int foo, float bar)

...

The template is:

@deftypefun type name arguments...
body-of-description
@end deftypefun

@deftypefun creates an entry in the index of functions for
name.

Variables in Typed Languages

Variables in typed languages are handled in a manner similar to
functions in typed languages.  See section Functions in Typed Languages.  The general
definition command @deftypevr corresponds to
@deftypefn and the specialized definition command
@deftypevar corresponds to @deftypefun.

@deftypevr category data-type name

The @deftypevr command is the general definition command for
something like a variable in a typed language--an entity that records
a value.  You must choose a term to describe the category of the
entity being defined; for example, "Variable" could be used if the
entity is a variable.
The @deftypevr command is written at the beginning of a line
and is followed on the same line by the category of the entity
being described, the data type, and the name of this particular
entity.
For example:

@deftypevr {Global Flag} int enable
...
@end deftypevr

produces the following in Info:

-- Global Flag: int enable
...

and the following in a printed manual:

Global Flag: int enable

...

The template is:

@deftypevr category data-type name
body-of-description
@end deftypevr

@deftypevr creates an entry in the index of variables for
name.

@deftypevar data-type name

The @deftypevar command is the specialized definition command
for variables in typed languages.  @deftypevar is equivalent
to `@deftypevr Variable ...'.
For example:

@deftypevar int fubar
...
@end deftypevar

produces the following in Info:

-- Variable: int fubar
...

and the following in a printed manual:

Variable: int fubar

...

The template is:

@deftypevar data-type name
body-of-description
@end deftypevar

@deftypevar creates an entry in the index of variables for
name.

Object-Oriented Programming

Here are the commands for formatting descriptions about abstract
objects, such as are used in object-oriented programming.  A class is
a defined type of abstract object.  An instance of a class is a
particular object that has the type of the class.  An instance
variable is a variable that belongs to the class but for which each
instance has its own value.

In a definition, if the name of a class is truly a name defined in the
programming system for a class, then you should write an @code
around it.  Otherwise, it is printed in the usual text font.

@defcv category class name

The @defcv command is the general definition command for
variables associated with classes in object-oriented programming.  The
@defcv command is followed by three arguments: the category of
thing being defined, the class to which it belongs, and its
name.  Thus,

@defcv {Class Option} Window border-pattern
...
@end defcv

illustrates how you would write the first line of a definition of the
border-pattern class option of the class Window.
The template is:

@defcv category class name
...
@end defcv

@defcv creates an entry in the index of variables.

@defivar class name

The @defivar command is the definition command for instance
variables in object-oriented programming.  @defivar is
equivalent to `@defcv {Instance Variable} ...'
The template is:

@defivar class instance-variable-name
body-of-definition
@end defivar

@defivar creates an entry in the index of variables.

@deftypeivar class data-type name

The @deftypeivar command is the definition command for typed
instance variables in object-oriented programming.  It is similar to
@defivar with the addition of the data-type parameter to
specify the type of the instance variable.  @deftypeivar creates an
entry in the index of variables.

@defop category class name arguments...

The @defop command is the general definition command for
entities that may resemble methods in object-oriented programming.
These entities take arguments, as functions do, but are associated with
particular classes of objects.
For example, some systems have constructs called wrappers that
are associated with classes as methods are, but that act more like
macros than like functions.  You could use @defop Wrapper to
describe one of these.
Sometimes it is useful to distinguish methods and operations.
You can think of an operation as the specification for a method.
Thus, a window system might specify that all window classes have a
method named expose; we would say that this window system
defines an expose operation on windows in general.  Typically,
the operation has a name and also specifies the pattern of arguments;
all methods that implement the operation must accept the same
arguments, since applications that use the operation do so without
knowing which method will implement it.
Often it makes more sense to document operations than methods.  For
example, window application developers need to know about the
expose operation, but need not be concerned with whether a
given class of windows has its own method to implement this operation.
To describe this operation, you would write:

@defop Operation windows expose

The @defop command is written at the beginning of a line and
is followed on the same line by the overall name of the category of
operation, the name of the class of the operation, the name of the
operation, and its arguments, if any.
The template is:

@defop category class name arguments...
body-of-definition
@end defop

@defop creates an entry, such as `expose on
windows', in the index of functions.

@deftypeop category class data-type name arguments...

The @deftypeop command is the definition command for typed
operations in object-oriented programming.  It is similar to
@defop with the addition of the data-type parameter to
specify the return type of the method.  @deftypeop creates an
entry in the index of functions.

@defmethod class name arguments...

The @defmethod command is the definition command for methods
in object-oriented programming.  A method is a kind of function that
implements an operation for a particular class of objects and its
subclasses.

@defmethod is equivalent to `@defop Method ...'.
The command is written at the beginning of a line and is followed by
the name of the class of the method, the name of the method, and its
arguments, if any.
For example:

@defmethod bar-class bar-method argument
...
@end defmethod

illustrates the definition for a method called bar-method of
the class bar-class.  The method takes an argument.
The template is:

@defmethod class method-name arguments...
body-of-definition
@end defmethod

@defmethod creates an entry, such as `bar-method on
bar-class', in the index of functions.

@deftypemethod class data-type name arguments...

The @deftypemethod command is the definition command for methods
in object-oriented typed languages, such as C++ and Java.  It is similar
to the @defmethod command with the addition of the
data-type parameter to specify the return type of the method.

Data Types

Here is the command for data types:

@deftp category name attributes...

The @deftp command is the generic definition command for data
types.  The command is written at the beginning of a line and is
followed on the same line by the category, by the name of the type
(which is a word like int or float), and then by names of
attributes of objects of that type.  Thus, you could use this command
for describing int or float, in which case you could use
data type as the category.  (A data type is a category of
certain objects for purposes of deciding which operations can be
performed on them.)
In Lisp, for example,  pair names a particular data
type, and an object of that type has two slots called the
CAR and the CDR.  Here is how you would write the first line
of a definition of pair.

@deftp {Data type} pair car cdr
...
@end deftp

The template is:

@deftp category name-of-type attributes...
body-of-definition
@end deftp

@deftp creates an entry in the index of data types.

Conventions for Writing Definitions

When you write a definition using @deffn, @defun, or
one of the other definition commands, please take care to use
arguments that indicate the meaning, as with the count argument
to the forward-word function.  Also, if the name of an argument
contains the name of a type, such as integer, take care that the
argument actually is of that type.

A Sample Function Definition

A function definition uses the @defun and @end defun
commands.  The name of the function follows immediately after the
@defun command and it is followed, on the same line, by the
parameter list.

Here is a definition from section `Calling Functions' in The GNU Emacs Lisp Reference Manual.

Function: apply function &rest arguments

apply calls function with arguments, just
like funcall but with one difference: the last of
arguments is a list of arguments to give to
function, rather than a single argument.  We also say
that this list is appended to the other arguments.

apply returns the result of calling function.
As with funcall, function must either be a Lisp
function or a primitive function; special forms and macros
do not make sense in apply.

(setq f 'list)
     => list
(apply f 'x 'y 'z)
error--> Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     => 10
(apply '+ '(1 2 3 4))
     => 10

(apply 'append '((a b c) nil (x y z) nil))
     => (a b c x y z)

An interesting example of using apply is found in the description
of mapcar.

In the Texinfo source file, this example looks like this:

@defun apply function &rest arguments
@code{apply} calls @var{function} with
@var{arguments}, just like @code{funcall} but with one
difference: the last of @var{arguments} is a list of
arguments to give to @var{function}, rather than a single
argument.  We also say that this list is @dfn{appended}
to the other arguments.

@code{apply} returns the result of calling
@var{function}.  As with @code{funcall},
@var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make
sense in @code{apply}.

@example
(setq f 'list)
     @result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     @result{} 10
(apply '+ '(1 2 3 4))
     @result{} 10

(apply 'append '((a b c) nil (x y z) nil))
     @result{} (a b c x y z)
@end example

An interesting example of using @code{apply} is found
in the description of @code{mapcar}.
@end defun

In this manual, this function is listed in the Command and Variable
Index under apply.

Ordinary variables and user options are described using a format like
that for functions except that variables do not take arguments.

Conditionally Visible Text

Sometimes it is good to use different text for different output formats.
For example, you can use the conditional commands to specify
different text for the printed manual and the Info output.

Conditional commands may not be nested.

The conditional commands comprise the following categories.

  • Commands for HTML, Info, or TeX.

  • Commands for not HTML, Info, or TeX.

  • Raw TeX or HTML commands.

  •

Substituting text for all formats, and testing if a flag is set or clear.

Conditional Commands

@ifinfo begins segments of text that should be ignored by TeX
when it typesets the printed manual.  The segment of text appears only
in the Info file.  The @ifinfo command should appear on a line
by itself; end the Info-only text with a line containing @end
ifinfo by itself.  At the beginning of a Texinfo file, the Info
permissions are contained within a region marked by @ifinfo and
@end ifinfo. (See section Summary and Copying Permissions for Info.)

The @iftex and @end iftex commands are similar to the
@ifinfo and @end ifinfo commands, except that they
specify text that will appear in the printed manual but not in the Info
file.  Likewise for @ifhtml and @end ifhtml, which
specify text to appear only in HTML output.

For example,

@iftex
This text will appear only in the printed manual.
@end iftex
@ifinfo
However, this text will appear only in Info.
@end ifinfo
@ifhtml
And this text will only appear in HTML.
@end ifhtml

The preceding example produces the following line:
This text will appear only in the printed manual.
And this text will only appear in HTML.

Notice that you only see one of the input lines, depending on which
version of the manual you are reading.

Conditional Not Commands

You can specify text to be included in any output format other
than some given one with the @ifnot... commands:

@ifnothtml ... @end ifnothtml
@ifnotinfo ... @end ifnotinfo
@ifnottex ... @end ifnottex

(The @ifnot... command and the @end command must
actually appear on lines by themselves.)

If the output file is not being made for the given format, the region is
included.  Otherwise, it is ignored.

The regions delimited by these commands are ordinary Texinfo source as
with @iftex, not raw formatter source as with @tex
(see section Raw Formatter Commands).

Raw Formatter Commands

Inside a region delineated by @iftex and @end iftex, you
can embed some raw TeX commands.  Info will ignore these commands
since they are only in that part of the file which is seen by TeX.
You can write the TeX commands as you would write them in a normal
TeX file, except that you must replace the `\' used by TeX
with an `@'.  For example, in the @titlepage section of a
Texinfo file, you can use the TeX command @vskip to format
the copyright page.  (The @titlepage command causes Info to
ignore the region automatically, as it does with the @iftex
command.)

However, many features of plain TeX will not work, as they are
overridden by Texinfo features.

You can enter plain TeX completely, and use `\' in the TeX
commands, by delineating a region with the @tex and @end
tex commands.  (The @tex command also causes Info to ignore the
region, like the @iftex command.)  The sole exception is that the
@ character still introduces a command, so that @end tex
can be recognized properly.

For example, here is a mathematical expression written in
plain TeX:

@tex
$$ \chi^2 = \sum_{i=1}^N
          \left (y_i - (a + b x_i)
          \over \sigma_i\right)^2 $$
@end tex

The output of this example will appear only in a printed manual.  If
you are reading this in Info, you will not see the equation that appears
in the printed manual.
In a printed manual, the above expression looks like
this:

Analogously, you can use @ifhtml ... @end ifhtml to delimit
a region to be included in HTML output only, and @html ...
@end html for a region of raw HTML (again, except that @ is
still the escape character, so the @end command can be
recognized.)

@set, @clear, and @value

You can direct the Texinfo formatting commands to format or ignore parts
of a Texinfo file with the @set, @clear, @ifset,
and @ifclear commands.

In addition, you can use the @set flag command to set the
value of flag to a string of characters; and use
@value{flag} to insert that string.  You can use
@set, for example, to set a date and use @value to
insert the date in several places in the Texinfo file.

@ifset and @ifclear

When a flag is set, the Texinfo formatting commands format text
between subsequent pairs of @ifset flag and @end
ifset commands.  When the flag is cleared, the Texinfo formatting
commands do not format the text.

Use the @set flag command to turn on, or set, a
flag; a flag name can be any single word, containing
letters, numerals, hyphens, or underscores.

The format for the command looks like this:

@set flag

Write the conditionally formatted text between @ifset flag
and @end ifset commands, like this:

@ifset flag
conditional-text
@end ifset

For example, you can create one document that has two variants, such as
a manual for a `large' and `small' model:

You can use this machine to dig up shrubs
without hurting them.

@set large

@ifset large
It can also dig up fully grown trees.
@end ifset

Remember to replant promptly ...

In the example, the formatting commands will format the text between
@ifset large and @end ifset because the large
flag is set.

Use the @clear flag command to turn off, or clear,
a flag.  Clearing a flag is the opposite of setting a flag.  The
command looks like this:

@clear flag

Write the command on a line of its own.

When flag is cleared, the Texinfo formatting commands do
not format the text between @ifset flag and
@end ifset; that text is ignored and does not appear in either
printed or Info output.

For example, if you clear the flag of the preceding example by writing
an @clear large command after the @set large command
(but before the conditional text), then the Texinfo formatting commands
ignore the text between the @ifset large and @end ifset
commands.  In the formatted output, that text does not appear; in both
printed and Info output, you see only the lines that say, "You can use
this machine to dig up shrubs without hurting them.  Remember to replant
promptly ...".

If a flag is cleared with an @clear flag command, then
the formatting commands format text between subsequent pairs of
@ifclear and @end ifclear commands.  But if the flag
is set with @set flag, then the formatting commands do
not format text between an @ifclear and an @end
ifclear command; rather, they ignore that text.  An @ifclear
command looks like this:

@ifclear flag

In brief, the commands are:

@set flag

Tell the Texinfo formatting commands that flag is set.

@clear flag

Tell the Texinfo formatting commands that flag is cleared.

@ifset flag

If flag is set, tell the Texinfo formatting commands to format
the text up to the following @end ifset command.
If flag is cleared, tell the Texinfo formatting commands to
ignore text up to the following @end ifset command.

@ifclear flag

If flag is set, tell the Texinfo formatting commands to ignore
the text up to the following @end ifclear command.
If flag is cleared, tell the Texinfo formatting commands to
format the text up to the following @end ifclear
command.

@set and @value

You can use the @set command to specify a value for a flag,
which is expanded by the @value command.  A flag is an
identifier; for best results, use only letters and numerals in a flag
name, not `-' or `_'---they will work in some contexts, but
not all, due to limitations in TeX.  The value is just a string of
characters, the remainder of the input line.

Write the @set command like this:

@set foo This is a string.

This sets the value of the flag foo to "This is a string.".

The Texinfo formatters then replace an @value{flag}
command with the string to which flag is set.  Thus, when
foo is set as shown above, the Texinfo formatters convert

@value{foo}
to
This is a string.

You can write an @value command within a paragraph; but you
must write an @set command on a line of its own.

If you write the @set command like this:

@set foo

without specifying a string, the value of foo is an empty string.

If you clear a previously set flag with @clear flag, a
subsequent @value{flag} command is invalid and the string is
replaced with an error message that says `{No value for
"flag"}'.

For example, if you set foo as follows:

@set how-much very, very, very

then the formatters transform

It is a @value{how-much} wet day.
into
It is a very, very, very wet day.

If you write

@clear how-much

then the formatters transform

It is a @value{how-much} wet day.
into
It is a {No value for "how-much"} wet day.

@value Example

You can use the @value command to limit the number of places you
need to change when you record an update to a manual.  Here is how it is
done in The GNU Make Manual:

  1.

Set the flags:

    @set EDITION 0.35 Beta
@set VERSION 3.63 Beta
@set UPDATED 14 August 1992
@set UPDATE-MONTH August 1992

  2.

Write text for the first @ifinfo section, for people reading the
Texinfo file:

    This is Edition @value{EDITION},
last updated @value{UPDATED},
of @cite{The GNU Make Manual},
for @code{make}, version @value{VERSION}.

  3.

Write text for the title page, for people reading the printed manual:

    @title GNU Make
@subtitle A Program for Directing Recompilation
@subtitle Edition @value{EDITION}, ...
@subtitle @value{UPDATE-MONTH}

(On a printed cover, a date listing the month and the year looks less
fussy than a date listing the day as well as the month and year.)

  4.

Write text for the Top node, for people reading the Info file:

    This is Edition @value{EDITION}
of the @cite{GNU Make Manual},
last updated @value{UPDATED}
for @code{make} Version @value{VERSION}.

After you format the manual, the text in the first @ifinfo
section looks like this:

    This is Edition 0.35 Beta, last updated 14 August 1992,
of `The GNU Make Manual', for `make', Version 3.63 Beta.

When you update the manual, change only the values of the flags; you do
not need to edit the three sections.

Internationalization

Texinfo has some support for writing in languages other than English,
although this area still needs considerable work.

For a list of the various accented and special characters Texinfo
supports, see section Inserting Accents.

@documentlanguage cc: Set the Document Language

The @documentlanguage command declares the current document
language.  Write it on a line by itself, with a two-letter ISO-639
language code following (list is included below).  If you have a
multilingual document, the intent is to be able to use this command
multiple times, to declare each language change.  If the command is not
used at all, the default is en for English.

At present, this command is ignored in Info and HTML output.  For
TeX, it causes the file `txi-cc.tex' to be read (if it
exists).  Such a file appropriately redefines the various English words
used in TeX output, such as `Chapter', `See', and so on.

It would be good if this command also changed TeX's ideas of the
current hyphenation patterns (via the TeX primitive
\language), but this is unfortunately not currently implemented.

Here is the list of valid language codes.  This list comes from
the free
translation project.  In the future we may wish to allow the 3-letter
POV codes described at http://www.sil.org/ethnologue/#contents.
This will be necessary to support African languages.

aaamaybebibrcsdeenetfifrgdguhihyieitjwklkskyltmgmlmrmynlomplqurosashslsosssvtetitntsuguzwoyozu
Afar | ab | Abkhazian | af | Afrikaans
Amharic | ar | Arabic | as | Assamese
Aymara | az | Azerbaijani | ba | Bashkir
Byelorussian | bg | Bulgarian | bh | Bihari
Bislama | bn | Bengali; Bangla | bo | Tibetan
Breton | ca | Catalan | co | Corsican
Czech | cy | Welsh | da | Danish
German | dz | Bhutani | el | Greek
English | eo | Esperanto | es | Spanish
Estonian | eu | Basque | fa | Persian
Finnish | fj | Fiji | fo | Faroese
French | fy | Frisian | ga | Irish
Scots Gaelic | gl | Galician | gn | Guarani
Gujarati | ha | Hausa | he | Hebrew
Hindi | hr | Croatian | hu | Hungarian
Armenian | ia | Interlingua | id | Indonesian
Interlingue | ik | Inupiak | is | Icelandic
Italian | iu | Inuktitut | ja | Japanese
Javanese | ka | Georgian | kk | Kazakh
Greenlandic | km | Cambodian | kn | Kannada
Kashmiri | ko | Korean | ku | Kurdish
Kirghiz | la | Latin | ln | Lingala
Lithuanian | lo | Laothian | lv | Latvian, Lettish
Malagasy | mi | Maori | mk | Macedonian
Malayalam | mn | Mongolian | mo | Moldavian
Marathi | ms | Malay | mt | Maltese
Burmese | na | Nauru | ne | Nepali
Dutch | no | Norwegian | oc | Occitan
(Afan) Oromo | or | Oriya | pa | Punjabi
Polish | ps | Pashto, Pushto | pt | Portuguese
Quechua | rm | Rhaeto-Romance | rn | Kirundi
Romanian | ru | Russian | rw | Kinyarwanda
Sanskrit | sd | Sindhi | sg | Sangro
Serbo-Croatian | si | Sinhalese | sk | Slovak
Slovenian | sm | Samoan | sn | Shona
Somali | sq | Albanian | sr | Serbian
Siswati | st | Sesotho | su | Sundanese
Swedish | sw | Swahili | ta | Tamil
Telugu | tg | Tajik | th | Thai
Tigrinya | tk | Turkmen | tl | Tagalog
Setswana | to | Tonga | tr | Turkish
Tsonga | tt | Tatar | tw | Twi
Uighur | uk | Ukrainian | ur | Urdu
Uzbek | vi | Vietnamese | vo | Volapuk
Wolof | xh | Xhosa | yi | Yiddish
Yoruba | za | Zhuang | zh | Chinese
Zulu

@documentencoding enc: Set Input Encoding

The @documentencoding command declares the input document
encoding.  Write it on a line by itself, with a valid encoding
specification following, such as `ISO-8859-1'.

At present, this is used only in HTML output from makeinfo.  If a
document encoding enc is specified, it is used in the
`<meta>' tag is included in the `<head>' of the output:

<meta http-equiv="Content-Type" content="text/html; charset=enc">

Defining New Texinfo Commands

Texinfo provides several ways to define new commands:

  •

A Texinfo macro allows you to define a new Texinfo command as any
sequence of text and/or existing commands (including other macros).  The
macro can have any number of parameters---text you supply each
time you use the macro.

Incidentally, these macros have nothing to do with the @defmac
command, which is for documenting macros in the subject of the manual
(see section The Template for a Definition).

  •

`@alias' is a convenient way to define a new name for an existing
command.

  •

`@definfoenclose' allows you to define new commands with
customized output in the Info file.

Defining Macros

You use the Texinfo @macro command to define a macro, like this:

@macro macroname{param1, param2, ...}
text ... \param1\ ...
@end macro

The parameters param1, param2, ... correspond to
arguments supplied when the macro is subsequently used in the document
(described in the next section).

For a macro to work with TeX, macroname must consist entirely
of letters: no digits, hyphens, underscores, or other special characters.

If a macro needs no parameters, you can define it either with an empty
list (`@macro foo {}') or with no braces at all (`@macro
foo').

The definition or body of the macro can contain most Texinfo
commands, including previously-defined macros.  Not-yet-defined macro
invocations are not allowed; thus, it is not possible to have mutually
recursive Texinfo macros.  Also, a macro definition that defines another
macro does not work in TeX due to limitations in the design of
@macro.

In the macro body, instances of a parameter name surrounded by
backslashes, as in `\param1\' in the example above, are
replaced by the corresponding argument from the macro invocation.  You
can use parameter names any number of times in the body, including zero.

To get a single `\' in the macro expansion, use `\\'.  Any
other use of `\' in the body yields a warning.

The newlines after the @macro line and before the @end
macro line are ignored, that is, not included in the macro body.  All
other whitespace is treated according to the usual Texinfo rules.

To allow a macro to be used recursively, that is, in an argument to a
call to itself, you must define it with `@rmacro', like this:

@rmacro rmac
a\arg\b
@end rmacro
...
@rmac{1@rmac{text}2}

This produces the output `a1atextb2b'.  With `@macro' instead of
`@rmacro', an error message is given.

You can undefine a macro foo with @unmacro foo.
It is not an error to undefine a macro that is already undefined.
For example:

@unmacro foo

Invoking Macros

After a macro is defined (see the previous section), you can use
(invoke) it in your document like this:

@macroname {arg1, arg2, ...}

and the result will be just as if you typed the body of
macroname at that spot.  For example:

@macro foo {p, q}
Together: \p\ & \q\.
@end macro
@foo{a, b}

produces:

Together: a & b.

Thus, the arguments and parameters are separated by commas and delimited
by braces; any whitespace after (but not before) a comma is ignored.
The braces are required in the invocation (but not the definition), even
when the macro takes no arguments, consistent with all other Texinfo
commands.  For example:

@macro argless {}
No arguments here.
@end macro
@argless{}

produces:

No arguments here.

To insert a comma, brace, or backslash in an argument, prepend a
backslash, as in

@macname {\\\{\}\,}

which will pass the (almost certainly error-producing) argument
`\{},' to macname.

If the macro is defined to take a single argument, and is invoked
without any braces, the entire rest of the line after the macro name is
supplied as the argument.  For example:

@macro bar {p}
Twice: \p\ & \p\.
@end macro
@bar aah

produces:

Twice: aah & aah.

If the macro is defined to take a single argument, and is invoked with
braces, the braced text is passed as the argument, regardless of
commas.  For example:

@macro bar {p}
Twice: \p\ & \p\.
@end macro
@bar{a,b}

produces:

Twice: a,b & a,b.

Macro Details

Due to unavoidable disparities in the TeX and @command{makeinfo}
implementations, Texinfo macros have the following limitations.

  •

All macros are expanded inside at least one TeX group.  This means
that @set and other such commands will have no effect inside a macro.

  •

Macros containing a command which must be on a line by itself, such as a
conditional, cannot be invoked in the middle of a line.

  •

The TeX implementation cannot construct macros that define macros in
the natural way.  To do this, you must use conditionals and raw TeX.
For example:

    @ifinfo
@macro ctor {name, arg}
@macro \name\
something involving \arg\ somehow
@end macro
@end macro
@end ifinfo
@tex
\gdef\ctor#1{\ctorx#1,}
\gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}}
@end tex

  •

It is best to avoid comments inside macro definitions.

`@alias new=existing'

The `@alias' command defines a new command to be just like an
existing one.  This is useful for defining additional markup names, thus
preserving semantic information in the input even though the output
result may be the same.

Write the `@alias' command on a line by itself, followed by the
new command name, an equals sign, and the existing command name.
Whitespace around the equals sign is ignored.  Thus:

@alias new = existing

For example, if your document contains citations for both books and
some other media (movies, for example), you might like to define a
macro @moviecite{} that does the same thing as an ordinary
@cite{} but conveys the extra semantic information as well.
You'd do this as follows:

@alias moviecite = cite

Macros do not always have the same effect due to vagaries of argument
parsing.  Also, aliases are much simpler to define than macros.  So the
command is not redundant.  (It was also heavily used in the Jargon File!)

Aliases must not be recursive, directly or indirectly.

`definfoenclose': Customized Highlighting

A @definfoenclose command may be used to define a highlighting
command for Info, but not for TeX.  A command defined using
@definfoenclose marks text by enclosing it in strings that
precede and follow the text.  You can use this to get closer control of
your Info output.

Presumably, if you define a command with @definfoenclose for Info,
you will create a corresponding command for TeX, either in
`texinfo.tex', `texinfo.cnf', or within an `@iftex' in
your document.

Write a @definfoenclose command on a line and follow it with
three arguments separated by commas.  The first argument to
@definfoenclose is the @-command name (without the @);
the second argument is the Info start delimiter string; and the third
argument is the Info end delimiter string.  The latter two arguments
enclose the highlighted text in the Info file.  A delimiter string may
contain spaces.  Neither the start nor end delimiter is required.  If
you do not want a start delimiter but do want an end delimiter, you must
follow the command name with two commas in a row; otherwise, the Info
formatting commands will naturally misinterpret the end delimiter string
you intended as the start delimiter string.

If you do a @definfoenclose on the name of a pre-defined macro
(such as @emph, @strong, @t, or @i), the
enclosure definition will override the built-in definition.

An enclosure command defined this way takes one argument in braces; this
is intended for new markup commands (see section Marking Words and Phrases).

For example, you can write:

@definfoenclose phoo,//,\\

near the beginning of a Texinfo file to define @phoo as an Info
formatting command that inserts `//' before and `\\' after the argument
to @phoo.  You can then write @phoo{bar} wherever you
want `//bar\\' highlighted in Info.

Also, for TeX formatting, you could write

@iftex
@global@let@phoo=@i
@end iftex

to define @phoo as a command that causes TeX to typeset the
argument to @phoo in italics.

Note that each definition applies to its own formatter: one for TeX,
the other for texinfo-format-buffer or
texinfo-format-region.  The @definfoenclose command need
not be within `@ifinfo', but the raw TeX commands do need to be
in `@iftex'.

Here is another example: write

@definfoenclose headword, , :

near the beginning of the file, to define @headword as an Info
formatting command that inserts nothing before and a colon after the
argument to @headword.

`@definfoenclose' definitions must not be recursive, directly or
indirectly.

Formatting and Printing Hardcopy

There are three major shell commands for making a printed manual from a
Texinfo file: one for converting the Texinfo file into a file that will be
printed, a second for sorting indices, and a third for printing the
formatted document.  When you use the shell commands, you can either
work directly in the operating system shell or work within a shell
inside GNU Emacs.

If you are using GNU Emacs, you can use commands provided by Texinfo
mode instead of shell commands.  In addition to the three commands to
format a file, sort the indices, and print the result, Texinfo mode
offers key bindings for commands to recenter the output buffer, show the
print queue, and delete a job from the print queue.

Use TeX

The typesetting program called TeX is used for formatting a Texinfo
file.  TeX is a very powerful typesetting program and, if used correctly,
does an exceptionally good job.  (See section How to Obtain TeX, for information on how to obtain TeX.)

The makeinfo, texinfo-format-region, and
texinfo-format-buffer commands read the very same @-commands
in the Texinfo file as does TeX, but process them differently to
make an Info file (see section Creating an Info File).

Format with tex and texindex

Format the Texinfo file with the shell command tex followed by
the name of the Texinfo file.  For example:

tex foo.texi

TeX will produce a DVI file as well as several auxiliary
files containing information for indices, cross references, etc.  The
DVI file (for DeVice Independent file) can be printed on virtually
any device (see the following sections).

The tex formatting command itself does not sort the indices; it
writes an output file of unsorted index data.  (The texi2dvi
command automatically generates indices; see section Format with texi2dvi.)  To generate a printed index after
running the tex command, you first need a sorted index to work
from.  The texindex command sorts indices.  (The source file
`texindex.c' comes as part of the standard Texinfo distribution,
among other places.)

The tex formatting command outputs unsorted index files under
names that obey a standard convention: the name of your main input file
with any `.tex' (or similar, see section `tex invocation' in Web2c) extension removed, followed by the two letter names of indices.
For example, the raw index output files for the input file
`foo.texinfo' would be `foo.cp', `foo.vr', `foo.fn',
`foo.tp', `foo.pg' and `foo.ky'.  Those are exactly the
arguments to give to texindex.

Instead of specifying all the unsorted index file names explicitly, you
can use `??' as shell wildcards and give the command in this
form:

texindex foo.??

This command will run texindex on all the unsorted index files,
including any that you have defined yourself using @defindex
or @defcodeindex.  (You may execute `texindex foo.??'
even if there are similarly named files with two letter extensions
that are not index files, such as `foo.el'.  The texindex
command reports but otherwise ignores such files.)

For each file specified, texindex generates a sorted index file
whose name is made by appending `s' to the input file name.  The
@printindex command looks for a file with that name
(see section Index Menus and Printing an Index).  texindex does not alter the
raw index output file.

After you have sorted the indices, you need to rerun the tex
formatting command on the Texinfo file.  This regenerates the DVI file,
this time with up-to-date index entries.

Finally, you may need to run tex one more time, to get the page
numbers in the cross-references correct.

To summarize, this is a five step process:

  1.

Run tex on your Texinfo file.  This generates a DVI file (with
undefined cross-references and no indices), and the raw index files
(with two letter extensions).

  2.

Run texindex on the raw index files.  This creates the
corresponding sorted index files (with three letter extensions).

  3.

Run tex again on your Texinfo file.  This regenerates the DVI
file, this time with indices and defined cross-references, but with page
numbers for the cross-references from last time, generally incorrect.

  4.

Sort the indices again, with texindex.

  5.

Run tex one last time.  This time the correct page numbers are
written for the cross-references.

Alternatively, it's a one-step process: run texi2dvi
(see section Format with texi2dvi).

You need not run texindex each time after you run tex.  If
you do not, on the next run, the tex formatting command will use
whatever sorted index files happen to exist from the previous use of
texindex.  This is usually ok while you are debugging.

Sometimes you may wish to print a document while you know it is
incomplete, or to print just one chapter of a document.  In that case,
the usual auxiliary files that TeX creates and warnings TeX gives
when cross-references are not satisfied are just nuisances.  You can
avoid them with the @novalidate command, which you must give
before the @setfilename command
(see section @setfilename).  Thus, the beginning of
your file would look approximately like this:

\input texinfo
@novalidate
@setfilename myfile.info
...

@novalidate also turns off validation in
makeinfo, just like its --no-validate option
(see section Pointer Validation).

Format with texi2dvi

The texi2dvi command automatically runs both tex and
texindex as many times as necessary to produce a DVI file with
sorted indices and all cross-references resolved.  It simplifies the
tex---texindex---tex---tex sequence
described in the previous section.

To run texi2dvi on an input file `foo.texi', do this (where
`prompt$ ' is your shell prompt):

prompt$ texi2dvi foo.texi

As shown in this example, the input filenames to texi2dvi must
include any extension (`.texi', `.texinfo', etc.).  Under
MS-DOS and perhaps in other circumstances, you may need to run `sh
texi2dvi foo.texi' instead of relying on the operating system to invoke
the shell on the `texi2dvi' script.

Perhaps the most useful option to texi2dvi is
`--texinfo=cmd'.  This inserts cmd on a line by itself
after the @setfilename in a temporary copy of the input file
before running TeX.  With this, you can specify different printing
formats, such as @smallbook (see section Printing "Small" Books),
@afourpaper (see section Printing on A4 Paper), or @pageparams
(see section @pagesizes [width][, height]: Custom page sizes), without actually changing the document source.
(You can also do this on a site-wide basis with `texinfo.cnf';
see section Preparing for TeX).

For a list of other options, run `texi2dvi --help'.

Shell Print Using lpr -d

The precise command to print a DVI file depends on your system
installation, but `lpr -d' is common.  The command may require the
DVI file name without any extension or with a `.dvi'
extension.  (If it is `lpr', you must include the `.dvi'.)

For example, the following commands, will (perhaps) suffice to sort the
indices, format, and print the Bison Manual:

tex bison.texinfo
texindex bison.??
tex bison.texinfo
lpr -d bison.dvi

(Remember that the shell commands may be different at your site; but
these are commonly used versions.)

Using the texi2dvi shell script, you simply need type:

texi2dvi bison.texinfo
lpr -d bison.dvi

lpr is a standard program on Unix systems, but it is usually
absent on MS-DOS/MS-Windows.  Some network packages come with a
program named lpr, but these are usually limited to sending files
to a print server over the network, and generally don't support the
`-d' option.  If you are unfortunate enough to work on one of these
systems, you have several alternative ways of printing DVI files:

  • Find and install a Unix-like lpr program, or its clone.

If you can do that, you will be able to print DVI files just like
described above.

  • Send the DVI files to a network printer queue for DVI files.

Some network printers have special queues for printing DVI files.  You
should be able to set up your network software to send files to that
queue.  In some cases, the version of lpr which comes with your
network software will have a special option to send a file to specific
queues, like this:

    lpr -Qdvi -hprint.server.domain bison.dvi

  • Convert the DVI file to a Postscript or PCL file and send it to your

local printer.  See section `dvips invocation' in Dvips, and the man
pages for dvilj, for detailed description of these tools.  Once
the DVI file is converted to the format your local printer understands
directly, just send it to the appropriate port, usually `PRN'.

From an Emacs Shell

You can give formatting and printing commands from a shell within GNU
Emacs.  To create a shell within Emacs, type M-x shell.  In this
shell, you can format and print the document.  See section Formatting and Printing Hardcopy, for details.

You can switch to and from the shell buffer while tex is
running and do other editing.  If you are formatting a long document
on a slow machine, this can be very convenient.

You can also use texi2dvi from an Emacs shell.  For example,
here is how to use texi2dvi to format and print Using and
Porting GNU CC from a shell within Emacs:

texi2dvi gcc.texinfo
lpr -d gcc.dvi

Formatting and Printing in Texinfo Mode

Texinfo mode provides several predefined key commands for TeX
formatting and printing.  These include commands for sorting indices,
looking at the printer queue, killing the formatting job, and
recentering the display of the buffer in which the operations
occur.

C-c C-t C-b

M-x texinfo-tex-buffer

Run texi2dvi on the current buffer.

C-c C-t C-r

M-x texinfo-tex-region

Run TeX on the current region.

C-c C-t C-i

M-x texinfo-texindex

Sort the indices of a Texinfo file formatted with
texinfo-tex-region.

C-c C-t C-p

M-x texinfo-tex-print

Print a DVI file that was made with texinfo-tex-region or
texinfo-tex-buffer.

C-c C-t C-q

M-x tex-show-print-queue

Show the print queue.

C-c C-t C-d

M-x texinfo-delete-from-print-queue

Delete a job from the print queue; you will be prompted for the job
number shown by a preceding C-c C-t C-q command
(texinfo-show-tex-print-queue).

C-c C-t C-k

M-x tex-kill-job

Kill the currently running TeX job started by either
texinfo-tex-region or texinfo-tex-buffer, or any other
process running in the Texinfo shell buffer.

C-c C-t C-x

M-x texinfo-quit-job

Quit a TeX formatting job that has stopped because of an error by
sending an x to it.  When you do this, TeX preserves a record
of what it did in a `.log' file.

C-c C-t C-l

M-x tex-recenter-output-buffer

Redisplay the shell buffer in which the TeX printing and formatting
commands are run to show its most recent output.

Thus, the usual sequence of commands for formatting a buffer is as
follows (with comments to the right):

C-c C-t C-b             Run texi2dvi on the buffer.
C-c C-t C-p             Print the DVI file.
C-c C-t C-q             Display the printer queue.

The Texinfo mode TeX formatting commands start a subshell in Emacs
called the `*tex-shell*'.  The texinfo-tex-command,
texinfo-texindex-command, and tex-dvi-print-command
commands are all run in this shell.

You can watch the commands operate in the `*tex-shell*' buffer,
and you can switch to and from and use the `*tex-shell*' buffer
as you would any other shell buffer.

The formatting and print commands depend on the values of several variables.
The default values are:

     Variable                              Default value

texinfo-texi2dvi-command                  "texi2dvi"
texinfo-tex-command                       "tex"
texinfo-texindex-command                  "texindex"
texinfo-delete-from-print-queue-command   "lprm"
texinfo-tex-trailer                       "@bye"
tex-start-of-header                       "%**start"
tex-end-of-header                         "%**end"
tex-dvi-print-command                     "lpr -d"
tex-show-queue-command                    "lpq"

You can change the values of these variables with the M-x
edit-options command (see section `Editing Variable Values' in The GNU Emacs Manual), with the M-x set-variable command
(see section `Examining and Setting Variables' in The GNU Emacs Manual), or with your `.emacs' initialization file
(see section `Init File' in The GNU Emacs Manual).

Beginning with version 20, GNU Emacs offers a user-friendly interface,
called Customize, for changing values of user-definable variables.
See section `Easy Customization Interface' in The GNU Emacs Manual, for more details about this.  The Texinfo variables can
be found in the `Development/Docs/Texinfo' group, once you invoke
the M-x customize command.

Using the Local Variables List

Yet another way to apply the TeX formatting command to a Texinfo file
is to put that command in a local variables list at the end of the
Texinfo file.  You can then specify the tex or texi2dvi
commands as a compile-command and have Emacs run it by typing
M-x compile.  This creates a special shell called the
`*compilation*' buffer in which Emacs runs the compile command.
For example, at the end of the `gdb.texinfo' file, after the
@bye, you could put the following:

Local Variables:
compile-command: "texi2dvi gdb.texinfo"
End:

This technique is most often used by programmers who also compile programs
this way; see section `Compilation' in The GNU Emacs Manual.

TeX Formatting Requirements Summary

Every Texinfo file that is to be input to TeX must begin with a
\input command and must contain an @setfilename command:

\input texinfo
@setfilename arg-not-used-by-TeX

The first command instructs TeX to load the macros it needs to
process a Texinfo file and the second command opens auxiliary files.

Every Texinfo file must end with a line that terminates TeX's
processing and forces out unfinished pages:

@bye

Strictly speaking, these lines are all a Texinfo file needs to be
processed successfully by TeX.

Usually, however, the beginning includes an @settitle command to
define the title of the printed manual, an @setchapternewpage
command, a title page, a copyright page, and permissions.  Besides an
@bye, the end of a file usually includes indices and a table of
contents.  (And of course most manuals contain a body of text as well.)

For more information, see:

  • section @settitle

  • section @setchapternewpage

  • section Page Headings

  • section The Title and Copyright Pages

  • section Index Menus and Printing an Index

  • section Generating a Table of Contents

Preparing for TeX

TeX needs to know where to find the `texinfo.tex' file that you
have told it to input with the `\input texinfo' command at the
beginning of the first line.  The `texinfo.tex' file tells TeX
how to handle @-commands; it is included in all standard GNU
distributions.

Usually, the `texinfo.tex' file is put under the default directory
that contains TeX macros
(`/usr/local/share/texmf/tex/texinfo/texinfo.tex' by default) when
GNU Emacs or other GNU software is installed.  In this case, TeX will
find the file and you do not need to do anything special.
Alternatively, you can put `texinfo.tex' in the current directory
when you run TeX, and TeX will find it there.

Also, you should install `epsf.tex' in the same place as
`texinfo.tex', if it is not already installed from another
distribution.  This file is needed to support the @image command
(see section Inserting Images).

Optionally, you may create an additional `texinfo.cnf', and install
it as well.  This file is read by TeX when the @setfilename
command is executed (see section @setfilename).  You can put any
commands you like there, according to local site-wide conventions.  They
will be read by TeX when processing any Texinfo document.  For
example, if `texinfo.cnf' contains the line `@afourpaper'
(see section Printing on A4 Paper), then all Texinfo documents will be processed with
that page size in effect.  If you have nothing to put in
`texinfo.cnf', you do not need to create it.

If neither of the above locations for these system files suffice for
you, you can specify the directories explicitly.  For
`texinfo.tex', you can do this by writing the complete path for the
file after the \input command.  Another way, that works for both
`texinfo.tex' and `texinfo.cnf' (and any other file TeX
might read), is to set the TEXINPUTS environment variable in your
`.cshrc' or `.profile' file.

Which you use of `.cshrc' or `.profile' depends on
whether you use a Bourne shell-compatible (sh, bash,
ksh, ...) or C shell-compatible (csh, tcsh)
command interpreter.  The latter read the `.cshrc' file for
initialization information, and the former read `.profile'.

In a `.cshrc' file, you could use the following csh command
sequence:

setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros

In a `.profile' file, you could use the following sh command
sequence:

TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
export TEXINPUTS

On MS-DOS/MS-Windows, you would say it like this(10):

set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros

It is customary for DOS/Windows users to put such commands in the
`autoexec.bat' file, or in the Windows Registry.

These settings would cause TeX to look for `\input' file first
in the current directory, indicated by the `.', then in a
hypothetical user's `me/mylib' directory, and finally in a system
directory `/usr/lib/tex/macros'.

Finally, you may wish to dump a `.fmt' file (see section `Memory dumps' in Web2c) so that TeX can load Texinfo faster.  (The
disadvantage is that then updating `texinfo.tex' requires
redumping.)  You can do this by running this command, assuming
`epsf.tex' is findable by TeX:

initex texinfo @dump

(@dump is a TeX primitive.)  You'll then need to move
`texinfo.fmt' to wherever your .fmt files are found;
typically this will be in the subdirectory `web2c' of your TeX
installation, for example, `/usr/local/share/tex/web2c'.

Overfull "hboxes"

TeX is sometimes unable to typeset a line without extending it into
the right margin.  This can occur when TeX comes upon what it
interprets as a long word that it cannot hyphenate, such as an
electronic mail network address or a very long title.  When this
happens, TeX prints an error message like this:

Overfull @hbox (20.76302pt too wide)

(In TeX, lines are in "horizontal boxes", hence the term, "hbox".
`@hbox' is a TeX primitive not needed in the Texinfo language.)

TeX also provides the line number in the Texinfo source file and
the text of the offending line, which is marked at all the places that
TeX considered hyphenation.
See section Catching Errors with TeX Formatting,
for more information about typesetting errors.

If the Texinfo file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur, or you can decide to leave it.  A
small excursion into the right margin often does not matter and may not
even be noticeable.

If you have many overfull boxes and/or an antipathy to rewriting, you
can coerce TeX into greatly increasing the allowable interword
spacing, thus (if you're lucky) avoiding many of the bad line breaks,
like this:

@tex
\global\emergencystretch = .9\hsize
@end tex

(You can adjust the fraction as needed.)  This huge value for
\emergencystretch cannot be the default, since then the typeset
output would generally be of noticeably lower quality.  The default
value is `.15\hsize'.  \hsize is the TeX dimension
containing the current line width.

For what overfull boxes you have, however, TeX will print a large,
ugly, black rectangle beside the line that contains the overfull hbox
unless told otherwise.  This is so you will notice the location of the
problem if you are correcting a draft.

To prevent such a monstrosity from marring your final printout, write
the following in the beginning of the Texinfo file on a line of its own,
before the @titlepage command:

@finalout

Printing "Small" Books

By default, TeX typesets pages for printing in an 8.5 by 11 inch
format.  However, you can direct TeX to typeset a document in a 7 by
9.25 inch format that is suitable for bound books by inserting the
following command on a line by itself at the beginning of the Texinfo
file, before the title page:

@smallbook

(Since many books are about 7 by 9.25 inches, this command might better
have been called the @regularbooksize command, but it came to be
called the @smallbook command by comparison to the 8.5 by 11 inch format.)

If you write the @smallbook command between the
start-of-header and end-of-header lines, the Texinfo mode TeX
region formatting command, texinfo-tex-region, will format the
region in "small" book size (see section Start of Header).

See section @small... Block Commands, for information about
commands that make it easier to produce examples for a smaller manual.

See section Format with texi2dvi, and section Preparing for TeX, for other ways to format with @smallbook that do not
require changing the source file.

Printing on A4 Paper

You can tell TeX to format a document for printing on European size
A4 paper with the @afourpaper command.  Write the command on a
line by itself near the beginning of the Texinfo file, before the title
page.  For example, this is how you would write the header for this
manual:

\input texinfo    @c -*-texinfo-*-
@c %**start of header
@setfilename texinfo
@settitle Texinfo
@afourpaper
@c %**end of header

See section Format with texi2dvi, and section Preparing for TeX, for other ways to format with @afourpaper that do not
require changing the source file.

You may or may not prefer the formatting that results from the command
@afourlatex.  There's also @afourwide for A4 paper in
wide format.

@pagesizes [width][, height]: Custom page sizes

You can explicitly specify the height and (optionally) width of the main
text area on the page with the @pagesizes command.  Write this
on a line by itself near the beginning of the Texinfo file, before the
title page.  The height comes first, then the width if desired,
separated by a comma.  Examples:

@pagesizes 200mm,150mm

and

@pagesizes 11.5in

This would be reasonable for printing on B5-size paper.  To emphasize,
this command specifies the size of the text area, not the size of
the paper (which is 250mm by 177mm for B5, 14in by
8.5in for legal).

To make more elaborate changes, such as changing any of the page
margins, you must define a new command in `texinfo.tex' (or
`texinfo.cnf', see section Preparing for TeX).

See section Format with texi2dvi, and section Preparing for TeX, for other ways to specify @pagesizes that do not
require changing the source file.

@pagesizes is ignored by makeinfo.

Cropmarks and Magnification

You can (attempt to) direct TeX to print cropmarks at the corners of
pages with the @cropmarks command.  Write the @cropmarks
command on a line by itself between @iftex and @end
iftex lines near the beginning of the Texinfo file, before the title
page, like this:

@iftex
@cropmarks
@end iftex

This command is mainly for printers that typeset several pages on one
sheet of film; but you can attempt to use it to mark the corners of a
book set to 7 by 9.25 inches with the @smallbook command.
(Printers will not produce cropmarks for regular sized output that is
printed on regular sized paper.)  Since different printing machines work
in different ways, you should explore the use of this command with a
spirit of adventure.  You may have to redefine the command in
`texinfo.tex'.

You can attempt to direct TeX to typeset pages larger or smaller than
usual with the \mag TeX command.  Everything that is typeset
is scaled proportionally larger or smaller.  (\mag stands for
"magnification".)  This is not a Texinfo @-command, but is a
plain TeX command that is prefixed with a backslash.  You have to
write this command between @tex and @end tex
(see section Raw Formatter Commands).

Follow the \mag command with an `=' and then a number that
is 1000 times the magnification you desire.  For example, to print pages
at 1.2 normal size, write the following near the beginning of the
Texinfo file, before the title page:

@tex
\mag=1200
@end tex

With some printing technologies, you can print normal-sized copies that
look better than usual by giving a larger-than-normal master to your
print shop.  They do the reduction, thus effectively increasing the
resolution.

Depending on your system, DVI files prepared with a
nonstandard-\mag may not print or may print only with certain
magnifications.  Be prepared to experiment.

PDF Output

You can generate a PDF output file from Texinfo source by using the
@command{pdftex} program to process your file instead of plain
@command{tex}.  Just run `pdftex foo.texi' instead of @samp{tex
foo.texi}, or give the `--pdf' option to @command{texi2dvi}.

PDF stands for Portable Document Format, and was invented by Adobe
Systems.  The
file format
definition is freely available, as is a
free viewer for the X window
system.  Since PDF is a binary format, there is no `@ifpdf' or
`@pdf' command by analogy with the other output formats.

Despite the `portable' in the name, PDF files are nowhere near as
portable in practice as the plain ASCII formats (Info, HTML) Texinfo
also supports (portability relative to DVI is arguable).  They also tend
to be much larger and do not support the bitmap fonts used by TeX (by
default) very well.  Nevertheless, a PDF file does preserve an actual
printed document on a screen as faithfully as possible, unlike HTML,
say, so have their place.

PDF support in Texinfo is fairly rudimentary.

Creating and Installing Info Files

This chapter describes how to create and install info files.  See section Info files, for general information about the file format itself.

Creating an Info File

makeinfo is a program that converts a Texinfo file into an Info
file, HTML file, or plain text.  texinfo-format-region and
texinfo-format-buffer are GNU Emacs functions that convert
Texinfo to Info.

For information on installing the Info file in the Info system,
see section Installing an Info File.

makeinfo Preferred

The makeinfo utility creates an Info file from a Texinfo source
file more quickly than either of the Emacs formatting commands and
provides better error messages.  We recommend it.  makeinfo is a
C program that is independent of Emacs.  You do not need to run Emacs to
use makeinfo, which means you can use makeinfo on machines
that are too small to run Emacs.  You can run makeinfo in any one
of three ways: from an operating system shell, from a shell inside
Emacs, or by typing the C-c C-m C-r or the C-c C-m C-b
command in Texinfo mode in Emacs.

The texinfo-format-region and the texinfo-format-buffer
commands are useful if you cannot run makeinfo.  Also, in some
circumstances, they format short regions or buffers more quickly than
makeinfo.

Running makeinfo from a Shell

To create an Info file from a Texinfo file, type makeinfo
followed by the name of the Texinfo file.  Thus, to create the Info
file for Bison, type the following to the shell:

makeinfo bison.texinfo

(You can run a shell inside Emacs by typing M-x shell.)

Options for makeinfo

The makeinfo command takes a number of options.  Most often,
options are used to set the value of the fill column and specify the
footnote style.  Each command line option is a word preceded by
`--' or a letter preceded by `-'.  You can use abbreviations
for the long option names as long as they are unique.

For example, you could use the following shell command to create an Info
file for `bison.texinfo' in which each line is filled to only 68
columns:

makeinfo --fill-column=68 bison.texinfo

You can write two or more options in sequence, like this:

makeinfo --no-split --fill-column=70 ...

This would keep the Info file together as one possibly very long
file and would also set the fill column to 70.

The options are:

-D var

Cause the variable var to be defined.  This is equivalent to
@set var in the Texinfo file (see section @set, @clear, and @value).

--commands-in-node-names

Allow @-commands in node names.  This is not recommended, as it
can probably never be implemented in TeX.  It also makes
makeinfo much slower.  Also, this option is ignored when
`--no-validate' is used.  See section Pointer Validation, for more
details.

--error-limit=limit

-e limit

Set the maximum number of errors that makeinfo will report
before exiting (on the assumption that continuing would be useless);
default 100.

--fill-column=width

-f width

Specify the maximum number of columns in a line; this is the right-hand
edge of a line.  Paragraphs that are filled will be filled to this
width.  (Filling is the process of breaking up and connecting lines so
that lines are the same length as or shorter than the number specified
as the fill column.  Lines are broken between words.) The default value
is 72.  Ignored with `--html'.

--footnote-style=style

-s style

Set the footnote style to style, either `end' for the end
node style (the default) or `separate' for the separate node style.
The value set by this option overrides the value set in a Texinfo file
by an @footnotestyle command (see section Footnotes).  When the
footnote style is `separate', makeinfo makes a new node
containing the footnotes found in the current node.  When the footnote
style is `end', makeinfo places the footnote references at
the end of the current node.  Ignored with `--html'.

--force

-F

Ordinarily, if the input file has errors, the output files are not
created.  With this option, they are preserved.

--help

-h

Print a usage message listing all available options, then exit successfully.

--html

Generate HTML output rather than Info.  See section Generating HTML.

-I dir

Append dir to the directory search list for finding files that
are included using the @include command.  By default,
makeinfo searches only the current directory.  If dir is
not given, the current directory `.' is appended.  Note that
dir can actually be a list of several directories separated by the
usual path separator character (`:' on Unix, `;' on
MS-DOS/MS-Windows).

--macro-expand=file

-E file

Output the Texinfo source with all the macros expanded to the named
file.  Normally, the results of macro expansion are used internally by
makeinfo and then discarded.  This option is used by
@command{texi2dvi} if you are using an old version of `texinfo.tex'
that does not support @macro.

--no-headers

For Info output, do not include menus or node lines in the output and
write to standard output (unless @option{--output} is specified).  This
results in an ASCII file that you cannot read in Info since it does
not contain the requisite nodes or menus.  It is primarily useful to
extract certain pieces of a manual into separate files to be included in
a distribution, such as `INSTALL' files.

For HTML output, if `--no-split' is also specified, do not include a
navigation links at the top of each node.  See section Generating HTML.

--no-split

Suppress the splitting stage of makeinfo.  By default, large
output files (where the size is greater than 70k bytes) are split into
smaller subfiles.  For Info output, each one is approximately 50k bytes.
For HTML output, each file contains one node (see section Generating HTML).

--no-pointer-validate

--no-validate

Suppress the pointer-validation phase of makeinfo.  This can also
be done with the @novalidate command (see section Use TeX).  Normally, after a Texinfo file is processed, some consistency
checks are made to ensure that cross references can be resolved, etc.
See section Pointer Validation.

--no-warn

Suppress warning messages (but not error messages).  You might
want this if the file you are creating has examples of Texinfo cross
references within it, and the nodes that are referenced do not actually
exist.

--number-sections

Output chapter, section, and appendix numbers as in printed manuals.

--no-number-footnotes

Suppress automatic footnote numbering.  By default, makeinfo
numbers each footnote sequentially in a single node, resetting the
current footnote number to 1 at the start of each node.

--output=file

-o file

Specify that the output should be directed to file and not to the
file name specified in the @setfilename command found in the
Texinfo source (see section @setfilename).  If file is `-', output
goes to standard output and `--no-split' is implied.  For split
HTML output, file is the name of the output file for the top node
(see section Generating HTML).

-P dir

Prepend dir to the directory search list for @include.
If dir is not given, the current directory `.' is prepended.
See `-I' for more details.

--paragraph-indent=indent

-p indent

Set the paragraph indentation style to indent.  The value set by
this option overrides the value set in a Texinfo file by an
@paragraphindent command (see section Paragraph Indenting).  The value
of indent is interpreted as follows:

`asis'

Preserve any existing indentation at the starts of paragraphs.

`0' or `none'

Delete any existing indentation.

num

Indent each paragraph by num spaces.

--reference-limit=limit

-r limit

Set the value of the number of references to a node that
makeinfo will make without reporting a warning.  If a node has more
than this number of references in it, makeinfo will make the
references but also report a warning.  The default is 1000.

-U var

Cause var to be undefined.  This is equivalent to
@clear var in the Texinfo file (see section @set, @clear, and @value).

--verbose

Cause makeinfo to display messages saying what it is doing.
Normally, makeinfo only outputs messages if there are errors or
warnings.

--version

-V

Print the version number, then exit successfully.

Pointer Validation

If you do not suppress pointer validation with the `--no-validate'
option or the @novalidate command in the source file (see section Use TeX), makeinfo will check the validity of the final
Info file.  Mostly, this means ensuring that nodes you have referenced
really exist.  Here is a complete list of what is checked:

  1.

If a `Next', `Previous', or `Up' node reference is a reference to a
node in the current file and is not an external reference such as to
`(dir)', then the referenced node must exist.

  2.

In every node, if the `Previous' node is different from the `Up' node,
then the node pointed to by the `Previous' field must have a `Next'
field which points back to this node.

  3.

Every node except the `Top' node must have an `Up' pointer.

  4.

The node referenced by an `Up' pointer must itself reference the current
node through a menu item, unless the node referenced by `Up'
has the form `(file)'.

  5.

If the `Next' reference of a node is not the same as the `Next' reference
of the `Up' reference, then the node referenced by the `Next' pointer
must have a `Previous' pointer that points back to the current node.
This rule allows the last node in a section to point to the first node
of the next chapter.

  6.

Every node except `Top' should be referenced by at least one other node,
either via the `Previous' or `Next' links, or via a menu or a
cross-reference.

Some Texinfo documents might fail during the validation phase because
they use commands like @value and @definfoenclose in
node definitions and cross-references inconsistently.  Consider the
following example:

@set nodename Node 1

@node @value{nodename}, Node 2, Top, Top

This is node 1.

@node Node 2, , Node 1, Top

This is node 2.

Here, the node "Node 1" was referenced both verbatim and through
@value.

By default, makeinfo fails such cases, because node names are not
fully expanded until they are written to the output file.  You should
always try to reference nodes consistently; e.g., in the above example,
the second @node line should have also used @value.
However, if, for some reason, you must reference node names
inconsistently, and makeinfo fails to validate the file, you can
use the `--commands-in-node-names' option to force makeinfo
to perform the expensive expansion of all node names it finds in the
document.  This might considerably slow down the program, though;
twofold increase in conversion time was measured for large documents
such as the Jargon file.

The support for @-commands in @node directives is not
general enough to be freely used.  For example, if the example above
redefined nodename somewhere in the document, makeinfo
will fail to convert it, even if invoked with the
`--commands-in-node-names' option.

`--commands-in-node-names' has no effect if the `--no-validate'
option is given.

Running makeinfo inside Emacs

You can run makeinfo in GNU Emacs Texinfo mode by using either the
makeinfo-region or the makeinfo-buffer commands.  In
Texinfo mode, the commands are bound to C-c C-m C-r and C-c
C-m C-b by default.

C-c C-m C-r

M-x makeinfo-region

Format the current region for Info.

C-c C-m C-b

M-x makeinfo-buffer

Format the current buffer for Info.

When you invoke either makeinfo-region or
makeinfo-buffer, Emacs prompts for a file name, offering the
name of the visited file as the default.  You can edit the default
file name in the minibuffer if you wish, before pressing RET to
start the makeinfo process.

The Emacs makeinfo-region and makeinfo-buffer commands
run the makeinfo program in a temporary shell buffer.  If
makeinfo finds any errors, Emacs displays the error messages in
the temporary buffer.

You can parse the error messages by typing C-x `
(next-error).  This causes Emacs to go to and position the
cursor on the line in the Texinfo source that makeinfo thinks
caused the error.  See section `Running make or Compilers Generally' in The GNU Emacs Manual, for more
information about using the next-error command.

In addition, you can kill the shell in which the makeinfo
command is running or make the shell buffer display its most recent
output.

C-c C-m C-k

M-x makeinfo-kill-job

Kill the current running makeinfo job
(from makeinfo-region or makeinfo-buffer).

C-c C-m C-l

M-x makeinfo-recenter-output-buffer

Redisplay the makeinfo shell buffer to display its most recent
output.

(Note that the parallel commands for killing and recentering a TeX
job are C-c C-t C-k and C-c C-t C-l.  See section Formatting and Printing in Texinfo Mode.)

You can specify options for makeinfo by setting the
makeinfo-options variable with either the M-x
edit-options or the M-x set-variable command, or by setting the
variable in your `.emacs' initialization file.

For example, you could write the following in your `.emacs' file:

(setq makeinfo-options
      "--paragraph-indent=0 --no-split
       --fill-column=70 --verbose")

For more information, see section Options for makeinfo, as well as "Editing Variable Values," "Examining
and Setting Variables," and "Init File" in The GNU Emacs
Manual.

The texinfo-format... Commands

In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
file with the texinfo-format-region command.  This formats the
current region and displays the formatted text in a temporary buffer
called `*Info Region*'.

Similarly, you can format a buffer with the
texinfo-format-buffer command.  This command creates a new
buffer and generates the Info file in it.  Typing C-x C-s will
save the Info file under the name specified by the
@setfilename line which must be near the beginning of the
Texinfo file.

C-c C-e C-r

texinfo-format-region

Format the current region for Info.

C-c C-e C-b

texinfo-format-buffer

Format the current buffer for Info.

The texinfo-format-region and texinfo-format-buffer
commands provide you with some error checking, and other functions can
provide you with further help in finding formatting errors.  These
procedures are described in an appendix; see section Formatting Mistakes.
However, the makeinfo program is often faster and
provides better error checking (see section Running makeinfo inside Emacs).

Batch Formatting

You can format Texinfo files for Info using batch-texinfo-format
and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
including a shell inside of Emacs.  (See section `Command Line Switches and Arguments' in The GNU Emacs Manual.)

Here is a shell command to format all the files that end in
`.texinfo' in the current directory:

emacs -batch -funcall batch-texinfo-format *.texinfo

Emacs processes all the files listed on the command line, even if an
error occurs while attempting to format some of them.

Run batch-texinfo-format only with Emacs in Batch mode as shown;
it is not interactive.  It kills the Batch mode Emacs on completion.

batch-texinfo-format is convenient if you lack makeinfo
and want to format several Texinfo files at once.  When you use Batch
mode, you create a new Emacs process.  This frees your current Emacs, so
you can continue working in it.  (When you run
texinfo-format-region or texinfo-format-buffer, you cannot
use that Emacs for anything else until the command finishes.)

Tag Files and Split Files

If a Texinfo file has more than 30,000 bytes,
texinfo-format-buffer automatically creates a tag table
for its Info file;  makeinfo always creates a tag table.  With
a tag table, Info can jump to new nodes more quickly than it can
otherwise.

In addition, if the Texinfo file contains more than about 70,000
bytes, texinfo-format-buffer and makeinfo split the
large Info file into shorter indirect subfiles of about 50,000
bytes each.  Big files are split into smaller files so that Emacs does
not need to make a large buffer to hold the whole of a large Info
file; instead, Emacs allocates just enough memory for the small, split-off
file that is needed at the time.  This way, Emacs avoids wasting
memory when you run Info.  (Before splitting was implemented, Info
files were always kept short and include files were designed as
a way to create a single, large printed manual out of the smaller Info
files.  See section Include Files, for more information.  Include files are
still used for very large documents, such as The Emacs Lisp
Reference Manual, in which each chapter is a separate file.)

When a file is split, Info itself makes use of a shortened version of
the original file that contains just the tag table and references to
the files that were split off.  The split-off files are called
indirect files.

The split-off files have names that are created by appending `-1',
`-2', `-3' and so on to the file name specified by the
@setfilename command.  The shortened version of the original file
continues to have the name specified by @setfilename.

At one stage in writing this document, for example, the Info file was saved
as the file `test-texinfo' and that file looked like this:

Info file: test-texinfo,    -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo

^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
...

(But `test-texinfo' had far more nodes than are shown here.)  Each of
the split-off, indirect files, `test-texinfo-1',
`test-texinfo-2', and `test-texinfo-3', is listed in this file
after the line that says `Indirect:'.  The tag table is listed after
the line that says `Tag table:'.

In the list of indirect files, the number following the file name
records the cumulative number of bytes in the preceding indirect files,
not counting the file list itself, the tag table, or the permissions
text in each file.  In the tag table, the number following the node name
records the location of the beginning of the node, in bytes from the
beginning of the (unsplit) output.

If you are using texinfo-format-buffer to create Info files,
you may want to run the Info-validate command.  (The
makeinfo command does such a good job on its own, you do not
need Info-validate.)  However, you cannot run the M-x
Info-validate node-checking command on indirect files.  For
information on how to prevent files from being split and how to
validate the structure of the nodes, see section Running Info-validate.

Generating HTML

As an alternative to the normal Info format output you can use the
`--html' option to generate output in HTML format, for installation
on a web site (for example).  In this release, HTML output from
makeinfo is monolithic, splitting the output by chapter or node
is not supported.  We hope to implement this feature soon.

The HTML output file is named according to @setfilename, but
with any `.info' extension replaced with `.html'.

Texinfo input marked up with the @ifhtml command will produce
output only with the `--html' option supplied.  Input marked up
with the @html is passed literally to the output (suppressing
the normal escaping of input `<', `>' and `&' characters
which have special significance in HTML).

The `--footnote-style' option is currently ignored for HTML output;
footnotes are hyperlinked at the end of the output file.

The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866).  The
exception is that HTML 3.2 tables are generated from the
@multitable command, but tagged to degrade as well as possible
in browsers without table support.  Please report output from an
error-free run of makeinfo which violates the HTML 3.2 DTD as a
bug.

Navigation bars are inserted at the start of nodes, similarly to Info
output.  The `--no-headers' option will suppress this if used with
`--no-split'.  Header <link> elements in split output can
support info-like navigation with browsers like Lynx and Emacs W3
which implement this HTML 1.0 feature.  You still won't normally get
the multi-file regexp and index search facilities provided by Info
readers.  Otherwise, hyperlinks are generated from Texinfo commands
where appropriate.  `@xref' commands to other documents are
generated assuming the other document is available in HTML form too, and
`.html' is appended to the `@xref' Info file name.  This
presumably will often not work.

Installing an Info File

Info files are usually kept in the `info' directory.  You can read
Info files using the standalone Info program or the Info reader built
into Emacs.  (See Info file `info', node `Top', for an introduction to Info.)

The Directory File `dir'

For Info to work, the `info' directory must contain a file that
serves as a top level directory for the Info system.  By convention,
this file is called `dir'.  (You can find the location of this file
within Emacs by typing C-h i to enter Info and then typing
C-x C-f to see the pathname to the `info' directory.)

The `dir' file is itself an Info file.  It contains the top level
menu for all the Info files in the system.  The menu looks like
this:

* Menu:
* Info:    (info).     Documentation browsing system.
* Emacs:   (emacs).    The extensible, self-documenting
                       text editor.
* Texinfo: (texinfo).  With one source file, make
                       either a printed manual using
                       TeX or an Info file.
...

Each of these menu entries points to the `Top' node of the Info file
that is named in parentheses.  (The menu entry does not need to
specify the `Top' node, since Info goes to the `Top' node if no node
name is mentioned.  See section Referring to Other Info Files.)

Thus, the `Info' entry points to the `Top' node of the
`info' file and the `Emacs' entry points to the `Top' node
of the `emacs' file.

In each of the Info files, the `Up' pointer of the `Top' node refers
back to the dir file.  For example, the line for the `Top'
node of the Emacs manual looks like this in Info:

File: emacs  Node: Top, Up: (DIR), Next: Distrib

In this case, the `dir' file name is written in upper case
letters--it can be written in either upper or lower case.  This is not
true in general, it is a special case for `dir'.

Listing a New Info File

To add a new Info file to your system, you must write a menu entry to
add to the menu in the `dir' file in the `info' directory.
For example, if you were adding documentation for GDB, you would write
the following new entry:

* GDB: (gdb).           The source-level C debugger.

The first part of the menu entry is the menu entry name, followed by a
colon.  The second part is the name of the Info file, in parentheses,
followed by a period.  The third part is the description.

The name of an Info file often has a `.info' extension.  Thus, the
Info file for GDB might be called either `gdb' or `gdb.info'.
The Info reader programs automatically try the file name both with and
without `.info' (11); so it is better to avoid
clutter and not to write `.info' explicitly in the menu entry.  For
example, the GDB menu entry should use just `gdb' for the file
name, not `gdb.info'.

Info Files in Other Directories

If an Info file is not in the `info' directory, there are three
ways to specify its location:

  1.

Write the pathname in the `dir' file as the second part of the menu.

  2.

If you are using Emacs, list the name of the file in a second `dir'
file, in its directory; and then add the name of that directory to the
Info-directory-list variable in your personal or site
initialization file.

This variable tells Emacs where to look for `dir' files (the files
must be named `dir').  Emacs merges the files named `dir' from
each of the listed directories.  (In Emacs version 18, you can set the
Info-directory variable to the name of only one
directory.)

  3.

Specify the Info directory name in the INFOPATH environment
variable in your `.profile' or `.cshrc' initialization file.
(Only you and others who set this environment variable will be able to
find Info files whose location is specified this way.)

For example, to reach a test file in the `/home/bob/info'
directory, you could add an entry like this to the menu in the
standard `dir' file:

* Test: (/home/bob/info/info-test).  Bob's own test file.

In this case, the absolute file name of the `info-test' file is
written as the second part of the menu entry.

Alternatively, you could write the following in your `.emacs'
file:

(require 'info)
(setq Info-directory-list
      (cons (expand-file-name "/home/bob/info") Info-directory-list))

This tells Emacs to merge the `dir' file from the
`/home/bob/info' directory with the system `dir' file.  Info
will list the `/home/bob/info/info-test' file as a menu entry in
the `/home/bob/info/dir' file.  Emacs does the merging only
when M-x info is first run, so if you want to set
Info-directory-list in an Emacs session where you've already run
info, you must (setq Info-dir-contents nil) to force Emacs
to recompose the `dir' file.

Finally, you can tell Info where to look by setting the INFOPATH
environment variable in your shell startup file, such as `.cshrc',
`.profile' or `autoexec.bat'.  If you use a Bourne-compatible
shell such as sh or bash for your shell command
interpreter, you set the INFOPATH environment variable in the
`.profile' initialization file; but if you use csh or
tcsh, you set the variable in the `.cshrc' initialization
file.  On MS-DOS/MS-Windows systems, you must set INFOPATH in
your `autoexec.bat' file or in the Registry.  Each type of shell
uses a different syntax.

  •

In a `.cshrc' file, you could set the INFOPATH
variable as follows:

    setenv INFOPATH .:~/info:/usr/local/emacs/info

  •

In a `.profile' file, you would achieve the same effect by
writing:

    INFOPATH=.:$HOME/info:/usr/local/emacs/info
export INFOPATH

  •

In a `autoexec.bat' file, you write this command(12):

    set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info

The `.' indicates the current directory as usual.  Emacs uses the
INFOPATH environment variable to initialize the value of Emacs's
own Info-directory-list variable.  The stand-alone Info reader
merges any files named `dir' in any directory listed in the
@env{INFOPATH} variable into a single menu presented to you in the node
called `(dir)Top'.

However you set @env{INFOPATH}, if its last character is a
colon(13), this
is replaced by the default (compiled-in) path.  This gives you a way to
augment the default path with new directories without having to list all
the standard places.  For example (using sh syntax):

INFOPATH=/local/info:
export INFOPATH

will search `/local/info' first, then the standard directories.
Leading or doubled colons are not treated specially.

When you create your own `dir' file for use with
Info-directory-list or @env{INFOPATH}, it's easiest to start by
copying an existing `dir' file and replace all the text after the
`* Menu:' with your desired entries.  That way, the punctuation and
special CTRL-_ characters that Info needs will be present.

Installing Info Directory Files

When you install an Info file onto your system, you can use the program
install-info to update the Info directory file `dir'.
Normally the makefile for the package runs install-info, just
after copying the Info file into its proper installed location.

In order for the Info file to work with install-info, you should
use the commands @dircategory and
@direntry...@end direntry in the Texinfo source
file.  Use @direntry to specify the menu entries to add to the
Info directory file, and use @dircategory to specify which part
of the Info directory to put it in.  Here is how these commands are used
in this manual:

@dircategory Texinfo documentation system
@direntry
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
@end direntry

Here's what this produces in the Info file:

INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
END-INFO-DIR-ENTRY

The install-info program sees these lines in the Info file, and
that is how it knows what to do.

Always use the @direntry and @dircategory commands near
the beginning of the Texinfo input, before the first @node
command.  If you use them later on in the input, install-info
will not notice them.

If you use @dircategory more than once in the Texinfo source,
each usage specifies the `current' category; any subsequent
@direntry commands will add to that category.

Here are some recommended @dircategory categories: `GNU
packages', `GNU programming tools', `GNU programming documentation',
`GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual
utilities'.  The idea is to include the `invoking' node for every
program installed by a package under `Individual utilities', and an
entry for the manual as a whole in the appropriate other category.

Invoking install-info

install-info inserts menu entries from an Info file into the
top-level `dir' file in the Info system (see the previous sections
for an explanation of how the `dir' file works).  It's most often
run as part of software installation, or when constructing a `dir' file
for all manuals on a system.  Synopsis:

install-info [option]... [info-file [dir-file]]

If info-file or dir-file are not specified, the options
(described below) that define them must be.  There are no compile-time
defaults, and standard input is never used.  install-info can
read only one Info file and write only one `dir' file per invocation.

If dir-file (however specified) does not exist,
install-info creates it if possible (with no entries).

If any input file is compressed with gzip (see section `Invoking gzip' in Gzip), install-info automatically uncompresses it
for reading.  And if dir-file is compressed, install-info
also automatically leaves it compressed after writing any changes.
If dir-file itself does not exist, install-info tries to
open `dir-file.gz'.

Options:

--delete

Delete the entries in info-file from dir-file.  The file
name in the entry in dir-file must be info-file (except for
an optional `.info' in either one).  Don't insert any new entries.

--dir-file=name

-d name

Specify file name of the Info directory file.  This is equivalent to
using the dir-file argument.

--entry=text

-e text

Insert text as an Info directory entry; text should have the
form of an Info menu item line plus zero or more extra lines starting
with whitespace.  If you specify more than one entry, they are all
added.  If you don't specify any entries, they are determined from
information in the Info file itself.

--help

-h

Display a usage message listing basic usage and all available options,
then exit successfully.

--info-file=file

-i file

Specify Info file to install in the directory.
Equivalent to using the info-file argument.

--info-dir=dir

-D dir

Specify the directory where `dir' resides.
Equivalent to `--dir-file=dir/dir'.

--item=text

Same as `--entry=text'.  An Info directory entry is actually
a menu item.

--quiet

Suppress warnings.

--remove

-r

Same as `--delete'.

--section=sec

-s sec

Put this file's entries in section sec of the directory.  If you
specify more than one section, all the entries are added in each of the
sections.  If you don't specify any sections, they are determined from
information in the Info file itself.

--version

-V

Display version information and exit successfully.

@-Command List

Here is an alphabetical list of the @-commands in Texinfo.  Square
brackets, [ ], indicate optional arguments; an ellipsis,
`...', indicates repeated text.

@whitespace

An @ followed by a space, tab, or newline produces a normal,
stretchable, interword space.  See section Multiple Spaces.

@!

Generate an exclamation point that really does end a sentence (usually
after an end-of-sentence capital letter).  See section Ending a Sentence.

@"

@'

Generate an umlaut or acute accent, respectively, over the next
character, as in @"o and 'o.  See section Inserting Accents.

@*

Force a line break. Do not end a paragraph that uses @* with
an @refill command.  See section @*: Generate Line Breaks.

@,{c}

Generate a cedilla accent under c, as in @,{c}.  See section Inserting Accents.

@-

Insert a discretionary hyphenation point.  See section @- and @hyphenation: Helping TeX hyphenate.

@.

Produce a period that really does end a sentence (usually after an
end-of-sentence capital letter).  See section Ending a Sentence.

@:

Indicate to TeX that an immediately preceding period, question
mark, exclamation mark, or colon does not end a sentence.  Prevent
TeX from inserting extra whitespace as it does at the end of a
sentence.  The command has no effect on the Info file output.
See section Not Ending a Sentence.

@=

Generate a macron (bar) accent over the next character, as in @=o.
See section Inserting Accents.

@?

Generate a question mark that really does end a sentence (usually after
an end-of-sentence capital letter).  See section Ending a Sentence.

@@

Stands for an at sign, `@'.
See section Inserting @ and Braces.

@^

@`

Generate a circumflex (hat) or grave accent, respectively, over the next
character, as in @^o.
See section Inserting Accents.

@{

Stands for a left brace, `{'.
See section Inserting @ and Braces.

@}

Stands for a right-hand brace, `}'.

See section Inserting @ and Braces.

@~

Generate a tilde accent over the next character, as in @~N.
See section Inserting Accents.

@AA{}

@aa{}

Generate the uppercase and lowercase Scandinavian A-ring letters,
respectively: Å, å.  See section Inserting Accents.

@acronym{abbrev}

Tag abbrev as an acronym, that is, an abbreviation written in all
capital letters, such as `NASA'.  See section @acronym{acronym}.

@AE{}

@ae{}

Generate the uppercase and lowercase AE ligatures, respectively:
Æ, æ.  See section Inserting Accents.

@afourlatex

@afourpaper

@afourwide

Change page dimensions for the A4 paper size.  See section Printing on A4 Paper.

@alias new=existing

Make the command `@new' an alias for the existing command
`@existing'.  See section `@alias new'=existing.

@anchor{name}

Define name as the current location for use as a cross-reference
target.  See section @anchor: Defining Arbitrary Cross-reference Targets.

@appendix title

Begin an appendix.  The title appears in the table
of contents of a printed manual.  In Info, the title is
underlined with asterisks.  See section @unnumbered and @appendix.

@appendixsec title

@appendixsection title

Begin an appendix section within an appendix.  The section title appears
in the table of contents of a printed manual.  In Info, the title is
underlined with equal signs.  @appendixsection is a longer
spelling of the @appendixsec command.  See section @unnumberedsec, @appendixsec, @heading.

@appendixsubsec title

Begin an appendix subsection within an appendix.  The title appears
in the table of contents of a printed manual.  In Info, the title is
underlined with hyphens.  See section The @subsection-like Commands.

@appendixsubsubsec title

Begin an appendix subsubsection within an appendix subsection.  The
title appears in the table of contents of a printed manual.  In Info,
the title is underlined with periods.  See section The `subsub' Commands.

@asis

Used following @table, @ftable, and @vtable to
print the table's first column without highlighting ("as is").
See section Making a Two-column Table.

@author author

Typeset author flushleft and underline it.  See section @title, @subtitle, and @author.

@b{text}

Print text in bold font.  No effect in Info.  See section Fonts for Printing, Not Info.

@bullet{}

Generate a large round dot, or the closest possible
thing to one.  See section @bullet{} (*).

@bye

Stop formatting a file.  The formatters do not see the contents of a
file following an @bye command.  See section Ending a Texinfo File.

@c comment

Begin a comment in Texinfo.  The rest of the line does not appear in
either the Info file or the printed manual.  A synonym for
@comment.  See section Comments.

@cartouche

Highlight an example or quotation by drawing a box with rounded
corners around it.  Pair with @end cartouche.  No effect in
Info.  See section Drawing Cartouches Around Examples.)

@center line-of-text

Center the line of text following the command.
See section @titlefont, @center, and @sp.

@centerchap line-of-text

Like @chapter, but centers the chapter title.  See section @chapter.

@chapheading title

Print a chapter-like heading in the text, but not in the table of
contents of a printed manual.  In Info, the title is underlined with
asterisks.  See section @majorheading, @chapheading.

@chapter title

Begin a chapter.  The chapter title appears in the table of
contents of a printed manual.  In Info, the title is underlined with
asterisks.  See section @chapter.

@cindex entry

Add entry to the index of concepts.  See section Making Index Entries.

@cite{reference}

Highlight the name of a book or other reference that lacks a
companion Info file.  See section @cite{reference}.

@clear flag

Unset flag, preventing the Texinfo formatting commands from
formatting text between subsequent pairs of @ifset flag
and @end ifset commands, and preventing
@value{flag} from expanding to the value to which
flag is set.
See section @set, @clear, and @value.

@code{sample-code}

Highlight text that is an expression, a syntactically complete token
of a program, or a program name.  See section @code{sample-code}.

@command{command-name}

Indicate a command name, such as @command{ls}.
See section @command{command-name}.

@comment comment

Begin a comment in Texinfo.  The rest of the line does not appear in
either the Info file or the printed manual.  A synonym for @c.
See section Comments.

@contents

Print a complete table of contents.  Has no effect in Info, which uses
menus instead.  See section Generating a Table of Contents.

@copyright{}

Generate a copyright symbol.  See section @copyright{} (©).

@defcodeindex index-name

Define a new index and its indexing command.  Print entries in an
@code font.  See section Defining New Indices.

@defcv category class name

@defcvx category class name

Format a description for a variable associated with a class in
object-oriented programming.  Takes three arguments: the category of
thing being defined, the class to which it belongs, and its name.
See section Definition Commands, and section Two or More `First' Lines.

@deffn category name arguments...

@deffnx category name arguments...

Format a description for a function, interactive command, or similar
entity that may take arguments.  @deffn takes as arguments the
category of entity being described, the name of this particular
entity, and its arguments, if any.  See section Definition Commands.

@defindex index-name

Define a new index and its indexing command.  Print entries in a roman
font.  See section Defining New Indices.

@definfoenclose newcmd, before, after,

Create new @-command newcmd for Info that marks text by enclosing
it in strings that precede and follow the text.  See section `definfoenclose': Customized Highlighting.

@defivar class instance-variable-name

@defivarx class instance-variable-name

This command formats a description for an instance variable in
object-oriented programming.  The command is equivalent to `@defcv
{Instance Variable} ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defmac macroname arguments...

@defmacx macroname arguments...

Format a description for a macro.  The command is equivalent to
`@deffn Macro ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defmethod class method-name arguments...

@defmethodx class method-name arguments...

Format a description for a method in object-oriented programming.  The
command is equivalent to `@defop Method ...'.  Takes as
arguments the name of the class of the method, the name of the
method, and its arguments, if any.  See section Definition Commands, and
section Two or More `First' Lines.

@defop category class name arguments...

@defopx category class name arguments...

Format a description for an operation in object-oriented programming.
@defop takes as arguments the overall name of the category of
operation, the name of the class of the operation, the name of the
operation, and its arguments, if any.  See section Definition Commands, and section Object-Oriented Programming.

@defopt option-name

@defoptx option-name

Format a description for a user option.  The command is equivalent to
`@defvr {User Option} ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defspec special-form-name arguments...

@defspecx special-form-name arguments...

Format a description for a special form.  The command is equivalent to
`@deffn {Special Form} ...'.  See section Definition Commands,
and section Two or More `First' Lines.

@deftp category name-of-type attributes...

@deftpx category name-of-type attributes...

Format a description for a data type.  @deftp takes as arguments
the category, the name of the type (which is a word like `int' or
`float'), and then the names of attributes of objects of that type.
See section Definition Commands, and section Data Types.

@deftypefn classification data-type name arguments...

@deftypefnx classification data-type name arguments...

Format a description for a function or similar entity that may take
arguments and that is typed.  @deftypefn takes as arguments the
classification of entity being described, the type, the name of the
entity, and its arguments, if any.  See section Definition Commands, and
section Two or More `First' Lines.

@deftypefun data-type function-name arguments...

@deftypefunx data-type function-name arguments...

Format a description for a function in a typed language.
The command is equivalent to `@deftypefn Function ...'.
See section Definition Commands, and section Two or More `First' Lines.

@deftypeivar class data-type variable-name

@deftypeivarx class data-type variable-name

Format a description for a typed instance variable in object-oriented
programming. See section Definition Commands, and section Object-Oriented Programming.

@deftypemethod class data-type method-name arguments...

@deftypemethodx class data-type method-name arguments...

Format a description for a typed method in object-oriented programming.
See section Definition Commands, and section Two or More `First' Lines.

@deftypeop category class data-type name arguments...

@deftypeopx category class data-type name arguments...

Format a description for a typed operation in object-oriented programming.
See section Definition Commands, and section Object-Oriented Programming.

@deftypevar data-type variable-name

@deftypevarx data-type variable-name

Format a description for a variable in a typed language.  The command is
equivalent to `@deftypevr Variable ...'.  See section Definition Commands, and section Two or More `First' Lines.

@deftypevr classification data-type name

@deftypevrx classification data-type name

Format a description for something like a variable in a typed
language--an entity that records a value.  Takes as arguments the
classification of entity being described, the type, and the name of the
entity.  See section Definition Commands, and section Two or More `First' Lines.

@defun function-name arguments...

@defunx function-name arguments...

Format a description for functions.  The command is equivalent to
`@deffn Function ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defvar variable-name

@defvarx variable-name

Format a description for variables.  The command is equivalent to
`@defvr Variable ...'.  See section Definition Commands, and
section Two or More `First' Lines.

@defvr category name

@defvrx category name

Format a description for any kind of variable.  @defvr takes
as arguments the category of the entity and the name of the entity.
See section Definition Commands,
and section Two or More `First' Lines.

@detailmenu

Avoid makeinfo confusion stemming from the detailed node listing
in a master menu.  See section Parts of a Master Menu.

@dfn{term}

Highlight the introductory or defining use of a term.
See section @dfn{term}.

@dircategory dirpart

Specify a part of the Info directory menu where this file's entry should
go.  See section Installing Info Directory Files.

@direntry

Begin the Info directory menu entry for this file.  Pair with
@end direntry.  See section Installing Info Directory Files.

@display

Begin a kind of example.  Like @example (indent text, do not
fill), but do not select a new font.  Pair with @end display.
See section @display and @smalldisplay.

@dmn{dimension}

Format a unit of measure, as in 12pt.  Causes TeX to insert a
thin space before dimension.  No effect in Info.
See section @dmn{dimension}: Format a Dimension.

@documentencoding enc

Declare the input encoding as enc.
See section @documentencoding enc: Set Input Encoding.

@documentlanguage CC

Declare the document language as the two-character ISO-639 abbreviation
CC.  See section @documentlanguage cc: Set the Document Language.

@dotaccent{c}

Generate a dot accent over the character c, as in @dotaccent{o}.
See section Inserting Accents.

@dots{}

Insert an ellipsis: `...'.
See section @dots{} (...) and @enddots{} (....).

@email{address[, displayed-text]}

Indicate an electronic mail address.
See section @email{email-address[, displayed-text]}.

@emph{text}

Highlight text; text is displayed in italics in printed
output, and surrounded by asterisks in Info.  See section Emphasizing Text.

@end environment

Ends environment, as in `@end example'.  See section @-commands.

@env{environment-variable}

Indicate an environment variable name, such as @env{PATH}.
See section @env{environment-variable}.

@enddots{}

Generate an end-of-sentence of ellipsis, like this ....
See section @dots{} (...) and @enddots{} (....).

@enumerate [number-or-letter]

Begin a numbered list, using @item for each entry.
Optionally, start list with number-or-letter.  Pair with
@end enumerate.  See section @enumerate: Making a Numbered or Lettered List.

@equiv{}

Indicate to the reader the exact equivalence of two forms with a
glyph: `=='.  See section @equiv{} (==): Indicating Equivalence.

@error{}

Indicate to the reader with a glyph that the following text is
an error message: `error-->'.  See section @error{} (error-->): Indicating an Error Message.

@evenfooting [left] @| [center] @| [right]

@evenheading [left] @| [center] @| [right]

Specify page footings resp. headings for even-numbered (left-hand)
pages.  Only allowed inside @iftex.  See section How to Make Your Own Headings.

@everyfooting [left] @| [center] @| [right]

@everyheading [left] @| [center] @| [right]

Specify page footings resp. headings for every page.  Not relevant to
Info.  See section How to Make Your Own Headings.

@example

Begin an example.  Indent text, do not fill, and select fixed-width font.
Pair with @end example.  See section @example.

@exampleindent indent

Indent example-like environments by indent number of spaces
(perhaps 0).  See section @exampleindent: Environment Indenting.

@exclamdown{}

Produce an upside-down exclamation point.  See section Inserting Accents.

@exdent line-of-text

Remove any indentation a line might have.  See section @exdent: Undoing a Line's Indentation.

@expansion{}

Indicate the result of a macro expansion to the reader with a special
glyph: `==>'.
See section @expansion{} (==>): Indicating an Expansion.

@file{filename}

Highlight the name of a file, buffer, node, or directory.  See section @file{file-name}.

@finalout

Prevent TeX from printing large black warning rectangles beside
over-wide lines.  See section Overfull "hboxes".

@findex entry

Add entry to the index of functions.  See section Making Index Entries.

@flushleft

@flushright

Left justify every line but leave the right end ragged.
Leave font as is.  Pair with @end flushleft.
@flushright analogous.
See section @flushleft and @flushright.

@footnote{text-of-footnote}

Enter a footnote.  Footnote text is printed at the bottom of the page
by TeX; Info may format in either `End' node or `Separate' node style.
See section Footnotes.

@footnotestyle style

Specify an Info file's footnote style, either `end' for the end
node style or `separate' for the separate node style.
See section Footnotes.

@format

Begin a kind of example.  Like @display, but do not narrow the
margins.  Pair with @end format.  See section @example.

@ftable formatting-command

Begin a two-column table, using @item for each entry.
Automatically enter each of the items in the first column into the
index of functions.  Pair with @end ftable.  The same as
@table, except for indexing.  See section @ftable and @vtable.

@group

Hold text together that must appear on one printed page.  Pair with
@end group.  Not relevant to Info.  See section @group: Prevent Page Breaks.

@H{c}

Generate the long Hungarian umlaut accent over c, as in @H{o}.

@heading title

Print an unnumbered section-like heading in the text, but not in the
table of contents of a printed manual.  In Info, the title is
underlined with equal signs.  See section @unnumberedsec, @appendixsec, @heading.

@headings on-off-single-double

Turn page headings on or off, and/or specify single-sided or double-sided
page headings for printing.  See section The @headings Command.

@html

Enter HTML completely.  Pair with @end html.  See section Raw Formatter Commands.

@hyphenation{hy-phen-a-ted words}

Explicitly define hyphenation points.  See section @- and @hyphenation: Helping TeX hyphenate.

@i{text}

Print text in italic font.  No effect in Info.
See section Fonts for Printing, Not Info.

@ifclear flag

If flag is cleared, the Texinfo formatting commands format text
between @ifclear flag and the following @end
ifclear command.
See section @set, @clear, and @value.

@ifhtml

@ifinfo

Begin a stretch of text that will be ignored by TeX when it typesets
the printed manual.  The text appears only in the HTML resp. Info
file.  Pair with @end ifhtml resp. @end ifinfo.
See section Conditionally Visible Text.

@ifnothtml

@ifnotinfo

@ifnottex

Begin a stretch of text that will be ignored in one output format but
not the others.  The text appears only in the format not specified.
Pair with @end ifnothtml resp. @end ifnotinfo resp.
@end ifnotinfo.  See section Conditionally Visible Text.

@ifset flag

If flag is set, the Texinfo formatting commands format text
between @ifset flag and the following @end ifset
command.
See section @set, @clear, and @value.

@iftex

Begin a stretch of text that will not appear in the Info file, but
will be processed only by TeX.  Pair with @end iftex.
See section Conditionally Visible Text.

@ignore

Begin a stretch of text that will not appear in either the Info file
or the printed output.  Pair with @end ignore.
See section Comments.

@image{filename, [width], [height]}

Include graphics image in external filename scaled to the given
width and/or height.  See section Inserting Images.

@include filename

Incorporate the contents of the file filename into the Info file
or printed document.  See section Include Files.

@inforef{node-name, [entry-name], info-file-name}

Make a cross reference to an Info file for which there is no printed
manual.  See section @inforef.

\input macro-definitions-file

Use the specified macro definitions file.  This command is used only
in the first line of a Texinfo file to cause TeX to make use of the
`texinfo' macro definitions file.  The backslash in \input
is used instead of an @ because TeX does not
recognize @ until after it has read the definitions file.
See section The Texinfo File Header.

@item

Indicate the beginning of a marked paragraph for @itemize and
@enumerate; indicate the beginning of the text of a first column
entry for @table, @ftable, and @vtable.
See section Lists and Tables.

@itemize  mark-generating-character-or-command

Produce a sequence of indented paragraphs, with a mark inside the left
margin at the beginning of each paragraph.  Pair with @end
itemize.  See section @itemize: Making an Itemized List.

@itemx

Like @item but do not generate extra vertical space above the
item text.  See section @itemx.

@kbd{keyboard-characters}

Indicate text that is characters of input to be typed by
users.  See section @kbd{keyboard-characters}.

@kbdinputstyle style

Specify when @kbd should use a font distinct from @code.
See section @kbd{keyboard-characters}.

@key{key-name}

Indicate a name for a key on a keyboard.
See section @key{key-name}.

@kindex entry

Add entry to the index of keys.
See section Making Index Entries.

@L{}

@l{}

Generate the uppercase and lowercase Polish suppressed-L letters,
respectively: L/, l/.

@lisp

Begin an example of Lisp code.  Indent text, do not fill, and select
fixed-width font.  Pair with @end lisp.  See section @lisp.

@lowersections

Change subsequent chapters to sections, sections to subsections, and so
on. See section @raisesections and @lowersections.

@macro macroname {params}

Define a new Texinfo command @macroname{params}.
Only supported by makeinfo and texi2dvi.  See section Defining Macros.

@majorheading title

Print a chapter-like heading in the text, but not in the table of
contents of a printed manual.  Generate more vertical whitespace before
the heading than the @chapheading command.  In Info, the chapter
heading line is underlined with asterisks.  See section @majorheading, @chapheading.

@math{mathematical-expression}

Format a mathematical expression.
See section @math: Inserting Mathematical Expressions.

@menu

Mark the beginning of a menu of nodes in Info.  No effect in a printed
manual.  Pair with @end menu.  See section Menus.

@minus{}

Generate a minus sign, `-'.  See section @minus{} (-): Inserting a Minus Sign.

@multitable column-width-spec

Begin a multi-column table.  Pair with @end multitable.
See section Multitable Column Widths.

@need n

Start a new page in a printed manual if fewer than n mils
(thousandths of an inch) remain on the current page.  See section @need mils: Prevent Page Breaks.

@node name, next, previous, up

Define the beginning of a new node in Info, and serve as a locator for
references for TeX.  See section The @node Command.

@noindent

Prevent text from being indented as if it were a new paragraph.
See section @noindent.

@novalidate

Suppress validation of node references, omit creation of auxiliary files
with TeX.  Use before @setfilename.  See section Pointer Validation.

@O{}

@o{}

Generate the uppercase and lowercase O-with-slash letters, respectively:
Ø, ø.

@oddfooting [left] @| [center] @| [right]

@oddheading [left] @| [center] @| [right]

Specify page footings resp. headings for odd-numbered (right-hand)
pages.  Only allowed inside @iftex.  See section How to Make Your Own Headings.

@OE{}

@oe{}

Generate the uppercase and lowercase OE ligatures, respectively:
OE, oe.  See section Inserting Accents.

@option{option-name}

Indicate a command-line option, such as @option{-l} or @option{--help}.
See section @option{option-name}.

@page

Start a new page in a printed manual.  No effect in Info.
See section @page: Start a New Page.

@pagesizes [width][, height]

Change page dimensions.  See section @pagesizes [width][, height]: Custom page sizes.

@paragraphindent indent

Indent paragraphs by indent number of spaces (perhaps 0); preserve
source file indentation if indent is asis.
See section Paragraph Indenting.

@pindex entry

Add entry to the index of programs.  See section Making Index Entries.

@point{}

Indicate the position of point in a buffer to the reader with a
glyph: `-!-'.  See section @point{} (-!-): Indicating Point in a Buffer.

@pounds{}

Generate the pounds sterling currency sign.
See section @pounds{} (£): Pounds Sterling.

@print{}

Indicate printed output to the reader with a glyph:
`-|'.  See section @print{} (-|): Indicating Printed Output.

@printindex index-name

Print an alphabetized two-column index in a printed manual or generate
an alphabetized menu of index entries for Info.  See section Index Menus and Printing an Index.

@pxref{node-name, [entry], [topic-or-title], [info-file], [manual]}

Make a reference that starts with a lower case `see' in a printed
manual.  Use within parentheses only.  Do not follow command with a
punctuation mark--the Info formatting commands automatically insert
terminating punctuation as needed.  Only the first argument is mandatory.
See section @pxref.

@questiondown{}

Generate an upside-down question mark.  See section Inserting Accents.

@quotation

Narrow the margins to indicate text that is quoted from another real
or imaginary work.  Write command on a line of its own.  Pair with
@end quotation.  See section @quotation.

@r{text}

Print text in roman font.  No effect in Info.
See section Fonts for Printing, Not Info.

@raisesections

Change subsequent sections to chapters, subsections to sections, and so
on.  See section @raisesections and @lowersections.

@ref{node-name, [entry], [topic-or-title], [info-file], [manual]}

Make a reference.  In a printed manual, the reference does not start
with a `See'.  Follow command with a punctuation mark.  Only the first
argument is mandatory.  See section @ref.

@refill

In Info, refill and indent the paragraph after all the other processing
has been done.  No effect on TeX, which always refills.  This command
is no longer needed, since all formatters now automatically refill.
See section Refilling Paragraphs.

@result{}

Indicate the result of an expression to the reader with a special
glyph: `=>'.  See section @result{} (=>): Indicating Evaluation.

@ringaccent{c}

Generate a ring accent over the next character, as in @ringaccent{o}.
See section Inserting Accents.

@samp{text}

Highlight text that is a literal example of a sequence of
characters.  Used for single characters, for statements, and often for
entire shell commands.  See section @samp{text}.

@sc{text}

Set text in a printed output in THE SMALL CAPS FONT and
set text in the Info file in uppercase letters.
See section @sc{text}: The Small Caps Font.

@section title

Begin a section within a chapter.  In a printed manual, the section
title is numbered and appears in the table of contents.  In Info, the
title is underlined with equal signs.  See section @section.

@set flag [string]

Make flag active, causing the Texinfo formatting commands to
format text between subsequent pairs of @ifset flag and
@end ifset commands.  Optionally, set value of flag to
string.
See section @set, @clear, and @value.

@setchapternewpage on-off-odd

Specify whether chapters start on new pages, and if so, whether on
odd-numbered (right-hand) new pages.  See section @setchapternewpage.

@setcontentsaftertitlepage

Put the table of contents after the `@end titlepage' even if the
@contents command is not there.  See section Generating a Table of Contents.

@setfilename info-file-name

Provide a name to be used by the Info file.  This command is essential
for TeX formatting as well, even though it produces no output.
See section @setfilename.

@setshortcontentsaftertitlepage

Place the short table of contents after the `@end titlepage'
command even if the @shortcontents command is not there.
See section Generating a Table of Contents.

@settitle title

Provide a title for page headers in a printed manual.
See section @settitle.

@shortcontents

Print a short table of contents.  Not relevant to Info, which uses
menus rather than tables of contents.  A synonym for
@summarycontents.  See section Generating a Table of Contents.

@shorttitlepage title

Generate a minimal title page.  See section @titlepage.

@smallbook

Cause TeX to produce a printed manual in a 7 by 9.25 inch format
rather than the regular 8.5 by 11 inch format.  See section Printing "Small" Books.  Also, see section @small... Block Commands.

@smalldisplay

Begin a kind of example.  Like @smallexample (indent text, no
filling), but do not select the fixed-width font.  In @smallbook
format, print text in a smaller font than with @display.  Pair
with @end smalldisplay.  See section @small... Block Commands.

@smallexample

Indent text to indicate an example.  Do not fill, select fixed-width
font.  In @smallbook format, print text in a smaller font than
with @example.  Pair with @end smallexample.
See section @small... Block Commands.

@smallformat

Begin a kind of example.  Like @smalldisplay, but do not narrow
the margins and do not select the fixed-width font.
In @smallbook format, print text in a smaller font than
with @format.  Pair with @end smallformat.
See section @small... Block Commands.

@smalllisp

Begin an example of Lisp code.  Indent text, do not fill, select
fixed-width font.  In @smallbook format, print text in a
smaller font.  Pair with @end smalllisp.  See section @small... Block Commands.

@sp n

Skip n blank lines.  See section @sp n: Insert Blank Lines.

@ss{}

Generate the German sharp-S es-zet letter, ß.  See section Inserting Accents.

@strong {text}

Emphasize text by typesetting it in a bold font for the
printed manual and by surrounding it with asterisks for Info.
See section @emph{text} and @strong{text}.

@subheading title

Print an unnumbered subsection-like heading in the text, but not in
the table of contents of a printed manual.  In Info, the title is
underlined with hyphens.  See section The @subsection-like Commands.

@subsection title

Begin a subsection within a section.  In a printed manual, the
subsection title is numbered and appears in the table of contents.  In
Info, the title is underlined with hyphens.  See section The @subsection Command.

@subsubheading title

Print an unnumbered subsubsection-like heading in the text, but not in
the table of contents of a printed manual.  In Info, the title is
underlined with periods.  See section The `subsub' Commands.

@subsubsection title

Begin a subsubsection within a subsection.  In a printed manual,
the subsubsection title is numbered and appears in the table of
contents.  In Info, the title is underlined with periods.
See section The `subsub' Commands.

@subtitle title

In a printed manual, set a subtitle in a normal sized font flush to
the right-hand side of the page.  Not relevant to Info, which does not
have title pages.  See section @title, @subtitle, and @author.

@summarycontents

Print a short table of contents.  Not relevant to Info, which uses
menus rather than tables of contents.  A synonym for
@shortcontents.  See section Generating a Table of Contents.

@syncodeindex from-index into-index

Merge the index named in the first argument into the index named in
the second argument, printing the entries from the first index in
@code font.  See section Combining Indices.

@synindex from-index into-index

Merge the index named in the first argument into the index named in
the second argument.  Do not change the font of from-index
entries.  See section Combining Indices.

@t{text}

Print text in a fixed-width, typewriter-like font.
No effect in Info.  See section Fonts for Printing, Not Info.

@tab

Separate columns in a multitable.  See section Multitable Rows.

@table formatting-command

Begin a two-column table, using @item for each entry.  Write
each first column entry on the same line as @item.  First
column entries are printed in the font resulting from
formatting-command.  Pair with @end table.
See section Making a Two-column Table.
Also see section @ftable and @vtable,
and section @itemx.

@TeX{}

Insert the logo TeX.  See section Inserting TeX and the Copyright Symbol.

@tex

Enter TeX completely.  Pair with @end tex.  See section Raw Formatter Commands.

@thischapter

@thischaptername

@thisfile

@thispage

@thistitle

Only allowed in a heading or footing.  Stands for the number and name of
the current chapter (in the format `Chapter 1: Title'), the chapter name
only, the filename, the current page number, and the title of the
document, respectively.  See section How to Make Your Own Headings.

@tieaccent{cc}

Generate a tie-after accent over the next two characters cc, as in
`@tieaccent{oo}'.  See section Inserting Accents.

@tindex entry

Add entry to the index of data types.  See section Making Index Entries.

@title title

In a printed manual, set a title flush to the left-hand side of the
page in a larger than normal font and underline it with a black rule.
Not relevant to Info, which does not have title pages.  See section @title, @subtitle, and @author.

@titlefont{text}

In a printed manual, print text in a larger than normal font.
Not relevant to Info, which does not have title pages.
See section @titlefont, @center, and @sp.

@titlepage

Indicate to Texinfo the beginning of the title page.  Write command on
a line of its own.  Pair with @end titlepage.  Nothing between
@titlepage and @end titlepage appears in Info.
See section @titlepage.

@today{}

Insert the current date, in `1 Jan 1900' style.  See section How to Make Your Own Headings.

@top title

In a Texinfo file to be formatted with makeinfo, identify the
topmost @node line in the file, which must be written on the line
immediately preceding the @top command.  Used for
makeinfo's node pointer insertion feature.  The title is
underlined with asterisks.  Both the @node line and the @top
line normally should be enclosed by @ifinfo and @end
ifinfo.  In TeX and texinfo-format-buffer, the @top
command is merely a synonym for @unnumbered.  See section Creating Pointers with makeinfo.

@u{c}

@ubaraccent{c}

@udotaccent{c}

Generate a breve, underbar, or underdot accent, respectively, over or
under the character c, as in @u{o}, @ubaraccent{o},
@udotaccent{o}.  See section Inserting Accents.

@unnumbered title

In a printed manual, begin a chapter that appears without chapter
numbers of any kind.  The title appears in the table of contents of a
printed manual.  In Info, the title is underlined with asterisks.
See section @unnumbered and @appendix.

@unnumberedsec title

In a printed manual, begin a section that appears without section
numbers of any kind.  The title appears in the table of contents of a
printed manual.  In Info, the title is underlined with equal signs.
See section @unnumberedsec, @appendixsec, @heading.

@unnumberedsubsec title

In a printed manual, begin an unnumbered subsection within a
chapter.  The title appears in the table of contents of a printed
manual.  In Info, the title is underlined with hyphens.
See section The @subsection-like Commands.

@unnumberedsubsubsec title

In a printed manual, begin an unnumbered subsubsection within a
chapter.  The title appears in the table of contents of a printed
manual.  In Info, the title is underlined with periods.
See section The `subsub' Commands.

@uref{url[, displayed-text][, replacement}

Define a cross reference to an external uniform resource locator for the
World Wide Web.  See section @uref{url[, text][, replacement]}.

@url{url}

Indicate text that is a uniform resource locator for the World Wide
Web.  See section @url{uniform-resource-locator}.

@v{c}

Generate check accent over the character c, as in @v{o}.
See section Inserting Accents.

@value{flag}

Replace flag with the value to which it is set by @set
flag.
See section @set, @clear, and @value.

@var{metasyntactic-variable}

Highlight a metasyntactic variable, which is something that stands for
another piece of text.  See section @var{metasyntactic-variable}.

@vindex entry

Add entry to the index of variables.  See section Making Index Entries.

@vskip amount

In a printed manual, insert whitespace so as to push text on the
remainder of the page towards the bottom of the page.  Used in
formatting the copyright page with the argument `0pt plus
1filll'.  (Note spelling of `filll'.)  @vskip may be used
only in contexts ignored for Info.  See section Copyright Page and Permissions.

@vtable formatting-command

Begin a two-column table, using @item for each entry.
Automatically enter each of the items in the first column into the
index of variables.  Pair with @end vtable.  The same as
@table, except for indexing.  See section @ftable and @vtable.

@w{text}

Prevent text from being split across two lines.  Do not end a
paragraph that uses @w with an @refill command.
See section @w{text}: Prevent Line Breaks.

@xref{node-name, [entry], [topic-or-title], [info-file], [manual]}

Make a reference that starts with `See' in a printed manual.  Follow
command with a punctuation mark.  Only the first argument is
mandatory.  See section @xref.

Tips and Hints

Here are some tips for writing Texinfo documentation:

  •

Write in the present tense, not in the past or the future.

  •

Write actively!  For example, write "We recommend that ..." rather
than "It is recommended that ...".

  •

Use 70 or 72 as your fill column.  Longer lines are hard to read.

  •

Include a copyright notice and copying permissions.

Index, Index, Index!

Write many index entries, in different ways.
Readers like indices; they are helpful and convenient.

Although it is easiest to write index entries as you write the body of
the text, some people prefer to write entries afterwards.  In either
case, write an entry before the paragraph to which it applies.  This
way, an index entry points to the first page of a paragraph that is
split across pages.

Here are more hints we have found valuable:

  •

Write each index entry differently, so each entry refers to a different
place in the document.

  •

Write index entries only where a topic is discussed significantly.  For
example, it is not useful to index "debugging information" in a
chapter on reporting bugs.  Someone who wants to know about debugging
information will certainly not find it in that chapter.

  •

Consistently capitalize the first word of every concept index entry,
or else consistently use lower case.  Terse entries often call for
lower case; longer entries for capitalization.  Whichever case
convention you use, please use one or the other consistently!  Mixing
the two styles looks bad.

  •

Always capitalize or use upper case for those words in an index for
which this is proper, such as names of countries or acronyms.  Always
use the appropriate case for case-sensitive names, such as those in C or
Lisp.

  •

Write the indexing commands that refer to a whole section immediately
after the section command, and write the indexing commands that refer to
a paragraph before that paragraph.

In the example that follows, a blank line comes after the index
entry for "Leaping":

    @section The Dog and the Fox
@cindex Jumping, in general
@cindex Leaping

@cindex Dog, lazy, jumped over
@cindex Lazy dog jumped over
@cindex Fox, jumps over dog
@cindex Quick fox jumps over dog
The quick brown fox jumps over the lazy dog.

(Note that the example shows entries for the same concept that are
written in different ways---`Lazy dog', and `Dog, lazy'---so
readers can look up the concept in different ways.)

Blank Lines

  •

Insert a blank line between a sectioning command and the first following
sentence or paragraph, or between the indexing commands associated with
the sectioning command and the first following sentence or paragraph, as
shown in the tip on indexing.  Otherwise, a formatter may fold title and
paragraph together.

  •

Always insert a blank line before an @table command and after an
@end table command; but never insert a blank line after an
@table command or before an @end table command.

For example,

    Types of fox:

@table @samp
@item Quick
Jump over lazy dogs.

@item Brown
Also jump over lazy dogs.
@end table

@noindent
On the other hand, ...

Insert blank lines before and after @itemize ... @end
itemize and @enumerate ... @end enumerate in the
same way.

Complete Phrases

Complete phrases are easier to read than ...

  •

Write entries in an itemized list as complete sentences; or at least, as
complete phrases.  Incomplete expressions ... awkward ... like
this.

  •

Write the prefatory sentence or phrase for a multi-item list or table as
a complete expression.  Do not write "You can set:"; instead, write
"You can set these variables:".  The former expression sounds cut off.

Editions, Dates and Versions

Write the edition and version numbers and date in three places in every
manual:

  1.

In the first @ifinfo section, for people reading the Texinfo file.

  2.

In the @titlepage section, for people reading the printed manual.

  3.

In the `Top' node, for people reading the Info file.

Also, it helps to write a note before the first @ifinfo
section to explain what you are doing.

For example:

@c ===> NOTE! <==
@c Specify the edition and version numbers and date
@c in *three* places:
@c   1. First ifinfo section  2. title page  3. top node
@c To find the locations, search for !!set

@ifinfo
@c !!set edition, date, version
This is Edition 4.03, January 1992,
of the @cite{GDB Manual} for GDB Version 4.3.
...

---or use @set and @value
(see section @value Example).

Definition Commands

Definition commands are @deffn, @defun,
@defmac, and the like, and enable you to write descriptions in
a uniform format.

  •

Write just one definition command for each entity you define with a
definition command.  The automatic indexing feature creates an index
entry that leads the reader to the definition.

  •

Use @table ... @end table in an appendix that
contains a summary of functions, not @deffn or other definition
commands.

Capitalization

  •

Capitalize "Texinfo"; it is a name.  Do not write the `x' or
`i' in upper case.

  •

Capitalize "Info"; it is a name.

  •

Write TeX using the @TeX{} command.  Note the uppercase
`T' and `X'.  This command causes the formatters to
typeset the name according to the wishes of Donald Knuth, who wrote
TeX.

Spaces

Do not use spaces to format a Texinfo file, except inside of
@example ... @end example and similar commands.

For example, TeX fills the following:

    @kbd{C-x v}
    @kbd{M-x vc-next-action}
       Perform the next logical operation
       on the version-controlled file
       corresponding to the current buffer.

so it looks like this:

    C-x v
    M-x vc-next-action
       Perform the next logical operation on the version-controlled file
       corresponding to the current buffer.

In this case, the text should be formatted with
@table, @item, and @itemx, to create a table.

@code, @samp, @var, and `---'

  •

Use @code around Lisp symbols, including command names.
For example,

    The main function is @code{vc-next-action}, ...

  •

Avoid putting letters such as `s' immediately after an
`@code'.  Such letters look bad.

  •

Use @var around meta-variables.  Do not write angle brackets
around them.

  •

Use three hyphens in a row, `---', to indicate a long dash.  TeX
typesets these as a long dash and the Info formatters reduce three
hyphens to two.

Periods Outside of Quotes

Place periods and other punctuation marks outside of quotations,
unless the punctuation is part of the quotation.  This practice goes
against publishing conventions in the United States, but enables the
reader to distinguish between the contents of the quotation and the
whole passage.

For example, you should write the following sentence with the period
outside the end quotation marks:

Evidently, `au' is an abbreviation for "author".

since `au' does not serve as an  abbreviation for
`author.' (with a period following the word).

Introducing New Terms

  •

Introduce new terms so that a reader who does not know them can
understand them from context; or write a definition for the term.

For example, in the following, the terms "check in", "register" and
"delta" are all appearing for the first time; the example sentence should be
rewritten so they are understandable.

The major function assists you in checking in a file to your
version control system and registering successive sets of changes to
it as deltas.

  •

Use the @dfn command around a word being introduced, to indicate
that the reader should not expect to know the meaning already, and
should expect to learn the meaning from this passage.

@pxref

Absolutely never use @pxref except in the special context for
which it is designed: inside parentheses, with the closing parenthesis
following immediately after the closing brace.  One formatter
automatically inserts closing punctuation and the other does not.  This
means that the output looks right both in printed output and in an Info
file, but only when the command is used inside parentheses.

Invoking from a Shell

You can invoke programs such as Emacs, GCC, and gawk from a
shell.  The documentation for each program should contain a section that
describes this.  Unfortunately, if the node names and titles for these
sections are all different, readers find it hard to search for the
section.

Name such sections with a phrase beginning with the word
`Invoking ...', as in `Invoking Emacs'; this way
users can find the section easily.

ANSI C Syntax

When you use @example to describe a C function's calling
conventions, use the ANSI C syntax, like this:

void dld_init (char *@var{path});

And in the subsequent discussion, refer to the argument values by
writing the same argument names, again highlighted with
@var.

Avoid the obsolete style that looks like this:

#include <dld.h>

dld_init (path)
char *path;

Also, it is best to avoid writing #include above the
declaration just to indicate that the function is declared in a
header file.  The practice may give the misimpression that the
#include belongs near the declaration of the function.  Either
state explicitly which header file holds the declaration or, better
yet, name the header file used for a group of functions at the
beginning of the section that describes the functions.

Bad Examples

Here are several examples of bad writing to avoid:

In this example, say, " ... you must @dfn{check
in} the new version."  That flows better.

When you are done editing the file, you must perform a
@dfn{check in}.

In the following example, say, "... makes a unified interface such as VC
mode possible."

SCCS, RCS and other version-control systems all perform similar
functions in broadly similar ways (it is this resemblance which makes
a unified control mode like this possible).

And in this example, you should specify what `it' refers to:

If you are working with other people, it assists in coordinating
everyone's changes so they do not step on each other.

And Finally ...

  •

Pronounce TeX as if the `X' were a Greek `chi', as the last
sound in the name `Bach'.  But pronounce Texinfo as in `speck':
"teckinfo".

  •

Write notes for yourself at the very end of a Texinfo file after the
@bye.  None of the formatters process text after the
@bye; it is as if the text were within @ignore ...
@end ignore.

A Sample Texinfo File

Here is a complete, short sample Texinfo file, without any commentary.
You can see this file, with comments, in the first chapter.
See section A Short Sample Texinfo File.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header

@setchapternewpage odd

@ifinfo
This is a short example of a complete Texinfo file.

Copyright 1990 Free Software Foundation, Inc.
@end ifinfo

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

@node    Top,       First Chapter,         , (dir)
@comment node-name, next,          previous, up

@menu
* First Chapter::    The first chapter is the
                     only chapter in this sample.
* Concept Index::    This index has two entries.
@end menu

@node    First Chapter, Concept Index, Top,      Top
@comment node-name,     next,          previous, up
@chapter First Chapter
@cindex Sample index entry

This is the contents of the first chapter.
@cindex Another sample index entry

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @code{makeinfo} and @code{texinfo-format-buffer}
commands transform a Texinfo file such as this into
an Info file; and @TeX{} typesets it for a printed
manual.

@node    Concept Index,    ,  First Chapter, Top
@comment node-name,    next,  previous,      up
@unnumbered Concept Index

@printindex cp

@contents
@bye

Sample Permissions

Texinfo files should contain sections that tell the readers that they
have the right to copy and distribute the Texinfo file, the Info file,
and the printed manual.

Also, if you are writing a manual about software, you should explain
that the software is free and either include the GNU General Public
License (GPL) or provide a reference to it.  See section `Distribution' in The GNU Emacs Manual, for an example of the text
that could be used in the software "Distribution", "General Public
License", and "NO WARRANTY" sections of a document.  See section Texinfo Copying Conditions, for an example of a brief explanation
of how the copying conditions provide you with rights.

In a Texinfo file, the first @ifinfo section usually begins
with a line that says what the file documents.  This is what a person
reading the unprocessed Texinfo file or using the advanced Info
command g * sees first.  See Info file `info', node `Expert', for more information. (A reader using the regular
Info commands usually starts reading at the first node and skips
this first section, which is not in a node.)

In the @ifinfo section, the summary sentence is followed by a
copyright notice and then by the copying permission notice.  One of
the copying permission paragraphs is enclosed in @ignore and
@end ignore commands.  This paragraph states that the Texinfo
file can be processed through TeX and printed, provided the printed
manual carries the proper copying permission notice.  This paragraph
is not made part of the Info file since it is not relevant to the Info
file; but it is a mandatory part of the Texinfo file since it permits
people to process the Texinfo file in TeX and print the
results.

In the printed manual, the Free Software Foundation copying permission
notice follows the copyright notice and publishing information and is
located within the region delineated by the @titlepage and
@end titlepage commands.  The copying permission notice is exactly
the same as the notice in the @ifinfo section except that the
paragraph enclosed in @ignore and @end ignore commands is
not part of the notice.

To make it simple to insert a permission notice into each section of
the Texinfo file, sample permission notices for each section are
reproduced in full below.

You may need to specify the correct name of a section mentioned in the
permission notice.  For example, in The GDB Manual, the name of
the section referring to the General Public License is called the "GDB
General Public License", but in the sample shown below, that section is
referred to generically as the "GNU General Public License".  If the
Texinfo file does not carry a copy of the General Public License, leave
out the reference to it, but be sure to include the rest of the
sentence.

`ifinfo' Copying Permissions

In the @ifinfo section of a Texinfo file, the standard Free
Software Foundation permission notice reads as follows:

This file documents ...

Copyright 1999 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Titlepage Copying Permissions

In the @titlepage section of a Texinfo file, the standard Free
Software Foundation copying permission notice follows the copyright
notice and publishing information.  The standard phrasing is as
follows:

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Include Files

When TeX or an Info formatting command sees an @include
command in a Texinfo file, it processes the contents of the file named
by the command and incorporates them into the DVI or Info file being
created.  Index entries from the included file are incorporated into
the indices of the output file.

Include files let you keep a single large document as a collection of
conveniently small parts.

How to Use Include Files

To include another file within a Texinfo file, write the
@include command at the beginning of a line and follow it on
the same line by the name of a file to be included.  For
example:

@include buffers.texi

An included file should simply be a segment of text that you expect to
be included as is into the overall or outer Texinfo file; it
should not contain the standard beginning and end parts of a Texinfo
file.  In particular, you should not start an included file with a
line saying `\input texinfo'; if you do, that phrase is inserted
into the output file as is.  Likewise, you should not end an included
file with an @bye command; nothing after @bye is
formatted.

In the past, you were required to write an @setfilename line at the
beginning of an included file, but no longer.  Now, it does not matter
whether you write such a line.  If an @setfilename line exists
in an included file, it is ignored.

Conventionally, an included file begins with an @node line that
is followed by an @chapter line.  Each included file is one
chapter.  This makes it easy to use the regular node and menu creating
and updating commands to create the node pointers and menus within the
included file.  However, the simple Emacs node and menu creating and
updating commands do not work with multiple Texinfo files.  Thus you
cannot use these commands to fill in the `Next', `Previous', and `Up'
pointers of the @node line that begins the included file.  Also,
you cannot use the regular commands to create a master menu for the
whole file.  Either you must insert the menus and the `Next',
`Previous', and `Up' pointers by hand, or you must use the GNU Emacs
Texinfo mode command, texinfo-multiple-files-update, that is
designed for @include files.

texinfo-multiple-files-update

GNU Emacs Texinfo mode provides the texinfo-multiple-files-update
command.  This command creates or updates `Next', `Previous', and `Up'
pointers of included files as well as those in the outer or overall
Texinfo file, and it creates or updates a main menu in the outer file.
Depending whether you call it with optional arguments, the command
updates only the pointers in the first @node line of the
included files or all of them:

M-x texinfo-multiple-files-update

Called without any arguments:

  •

Create or update the `Next', `Previous', and `Up' pointers of the
first @node line in each file included in an outer or overall
Texinfo file.

  •

Create or update the `Top' level node pointers of the outer or
overall file.

  •

Create or update a main menu in the outer file.

C-u M-x texinfo-multiple-files-update

Called with C-u as a prefix argument:

  •

Create or update pointers in the first @node line in each
included file.

  •

Create or update the `Top' level node pointers of the outer file.

  •

Create and insert a master menu in the outer file.  The master menu
is made from all the menus in all the included files.

C-u 8 M-x texinfo-multiple-files-update

Called with a numeric prefix argument, such as C-u 8:

  •

Create or update all the `Next', `Previous', and `Up' pointers
of all the included files.

  •

Create or update all the menus of all the included
files.

  •

Create or update the `Top' level node pointers of the outer or
overall file.

  •

And then create a master menu in the outer file.  This is similar to
invoking texinfo-master-menu with an argument when you are
working with just one file.

Note the use of the prefix argument in interactive use: with a regular
prefix argument, just C-u, the
texinfo-multiple-files-update command inserts a master menu;
with a numeric prefix argument, such as C-u 8, the command
updates every pointer and menu in all the files and then inserts a
master menu.

Include File Requirements

If you plan to use the texinfo-multiple-files-update command,
the outer Texinfo file that lists included files within it should
contain nothing but the beginning and end parts of a Texinfo file, and
a number of @include commands listing the included files.  It
should not even include indices, which should be listed in an included
file of their own.

Moreover, each of the included files must contain exactly one highest
level node (conventionally, @chapter or equivalent),
and this node must be the first node in the included file.
Furthermore, each of these highest level nodes in each included file
must be at the same hierarchical level in the file structure.
Usually, each is an @chapter, an @appendix, or an
@unnumbered node.  Thus, normally, each included file contains
one, and only one, chapter or equivalent-level node.

The outer file should contain only one node, the `Top' node.  It
should not contain any nodes besides the single `Top' node.  The
texinfo-multiple-files-update command will not process
them.

Sample File with @include

Here is an example of a complete outer Texinfo file with @include files
within it before running texinfo-multiple-files-update, which
would insert a main or master menu:

\input texinfo @c -*-texinfo-*-
@setfilename  include-example.info
@settitle Include Example

@setchapternewpage odd
@titlepage
@sp 12
@center @titlefont{Include Example}
@sp 2
@center by Whom Ever

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999 Free Software Foundation, Inc.
@end titlepage

@ifinfo
@node Top, First, , (dir)
@top Master Menu
@end ifinfo

@include foo.texinfo
@include bar.texinfo
@include concept-index.texinfo

@summarycontents
@contents

@bye

An included file, such as `foo.texinfo', might look like
this:

@node First, Second, , Top
@chapter First Chapter

Contents of first chapter ...

The full contents of `concept-index.texinfo' might be as simple as this:

@node Concept Index
@unnumbered Concept Index

@printindex cp

The outer Texinfo source file for The GNU Emacs Lisp Reference
Manual is named `elisp.texi'.  This outer file contains a master
menu with 417 entries and a list of 41 @include
files.

Evolution of Include Files

When Info was first created, it was customary to create many small
Info files on one subject.  Each Info file was formatted from its own
Texinfo source file.  This custom meant that Emacs did not need to
make a large buffer to hold the whole of a large Info file when
someone wanted information; instead, Emacs allocated just enough
memory for the small Info file that contained the particular
information sought.  This way, Emacs could avoid wasting memory.

References from one file to another were made by referring to the file
name as well as the node name. (See section Referring to Other Info Files.  Also, see section @xref with Four and Five Arguments.)

Include files were designed primarily as a way to create a single,
large printed manual out of several smaller Info files.  In a printed
manual, all the references were within the same document, so TeX
could automatically determine the references' page numbers.  The Info
formatting commands used include files only for creating joint
indices; each of the individual Texinfo files had to be formatted for
Info individually.  (Each, therefore, required its own
@setfilename line.)

However, because large Info files are now split automatically, it is
no longer necessary to keep them small.

Nowadays, multiple Texinfo files are used mostly for large documents,
such as The GNU Emacs Lisp Reference Manual, and for projects
in which several different people write different sections of a
document simultaneously.

In addition, the Info formatting commands have been extended to work
with the @include command so as to create a single large Info
file that is split into smaller files if necessary.  This means that
you can write menus and cross references without naming the different
Texinfo files.

Page Headings

Most printed manuals contain headings along the top of every page
except the title and copyright pages.  Some manuals also contain
footings.  (Headings and footings have no meaning to Info, which is
not paginated.)

Texinfo provides standard page heading formats for manuals that are
printed on one side of each sheet of paper and for manuals that are
printed on both sides of the paper.  Typically, you will use these
formats, but you can specify your own format if you wish.

In addition, you can specify whether chapters should begin on a new
page, or merely continue the same page as the previous chapter; and if
chapters begin on new pages, you can specify whether they must be
odd-numbered pages.

By convention, a book is printed on both sides of each sheet of paper.
When you open a book, the right-hand page is odd-numbered, and
chapters begin on right-hand pages--a preceding left-hand page is
left blank if necessary.  Reports, however, are often printed on just
one side of paper, and chapters begin on a fresh page immediately
following the end of the preceding chapter.  In short or informal
reports, chapters often do not begin on a new page at all, but are
separated from the preceding text by a small amount of whitespace.

The @setchapternewpage command controls whether chapters begin
on new pages, and whether one of the standard heading formats is used.
In addition, Texinfo has several heading and footing commands that you
can use to generate your own heading and footing formats.

In Texinfo, headings and footings are single lines at the tops and
bottoms of pages; you cannot create multiline headings or footings.
Each header or footer line is divided into three parts: a left part, a
middle part, and a right part.  Any part, or a whole line, may be left
blank.  Text for the left part of a header or footer line is set
flushleft; text for the middle part is centered; and, text for the
right part is set flushright.

Standard Heading Formats

Texinfo provides two standard heading formats, one for manuals printed
on one side of each sheet of paper, and the other for manuals printed
on both sides of the paper.

By default, nothing is specified for the footing of a Texinfo file,
so the footing remains blank.

The standard format for single-sided printing consists of a header
line in which the left-hand part contains the name of the chapter, the
central part is blank, and the right-hand part contains the page
number.

A single-sided page looks like this:

   _______________________
  |                       |
  | chapter   page number |
  |                       |
  | Start of text ...     |
  | ...                   |
  |                       |

The standard format for two-sided printing depends on whether the page
number is even or odd.  By convention, even-numbered pages are on the
left- and odd-numbered pages are on the right.  (TeX will adjust the
widths of the left- and right-hand margins.  Usually, widths are
correct, but during double-sided printing, it is wise to check that
pages will bind properly--sometimes a printer will produce output in
which the even-numbered pages have a larger right-hand margin than the
odd-numbered pages.)

In the standard double-sided format, the left part of the left-hand
(even-numbered) page contains the page number, the central part is
blank, and the right part contains the title (specified by the
@settitle command).  The left part of the right-hand
(odd-numbered) page contains the name of the chapter, the central part
is blank, and the right part contains the page number.

Two pages, side by side as in an open book, look like this:

   _______________________     _______________________
  |                       |   |                       |
  | page number     title |   | chapter   page number |
  |                       |   |                       |
  | Start of text ...     |   | More  text ...        |
  | ...                   |   | ...                   |
  |                       |   |                       |

The chapter name is preceded by the word "Chapter", the chapter number
and a colon.  This makes it easier to keep track of where you are in the
manual.

Specifying the Type of Heading

TeX does not begin to generate page headings for a standard Texinfo
file until it reaches the @end titlepage command.  Thus, the
title and copyright pages are not numbered.  The @end
titlepage command causes TeX to begin to generate page headings
according to a standard format specified by the
@setchapternewpage command that precedes the
@titlepage section.

There are four possibilities:

No @setchapternewpage command

Cause TeX to specify the single-sided heading format, with chapters
on new pages. This is the same as @setchapternewpage on.

@setchapternewpage on

Specify the single-sided heading format, with chapters on new pages.

@setchapternewpage off

Cause TeX to start a new chapter on the same page as the last page of
the preceding chapter, after skipping some vertical whitespace.  Also
cause TeX to typeset for single-sided printing.  (You can override
the headers format with the @headings double command; see
section The @headings Command.)

@setchapternewpage odd

Specify the double-sided heading format, with chapters on new pages.

Texinfo lacks an @setchapternewpage even command.

How to Make Your Own Headings

You can use the standard headings provided with Texinfo or specify
your own.  By default, Texinfo has no footers, so if you specify them,
the available page size for the main text will be slightly reduced.

Texinfo provides six commands for specifying headings and
footings:

  •

@everyheading @everyfooting generate page headers and
footers that are the same for both even- and odd-numbered pages.

  •

@evenheading and @evenfooting command generate headers
and footers for even-numbered (left-hand) pages.

  •

@oddheading and @oddfooting generate headers and footers
for odd-numbered (right-hand) pages.

Write custom heading specifications in the Texinfo file immediately
after the @end titlepage command.  Enclose your specifications
between @iftex and @end iftex commands since the
texinfo-format-buffer command may not recognize them.  Also,
you must cancel the predefined heading commands with the
@headings off command before defining your own
specifications.

Here is how to tell TeX to place the chapter name at the left, the
page number in the center, and the date at the right of every header
for both even- and odd-numbered pages:

@iftex
@headings off
@everyheading @thischapter @| @thispage @| @today{}
@end iftex

You need to divide the left part from the central part and the central
part from the right part by inserting `@|' between parts.
Otherwise, the specification command will not be able to tell where
the text for one part ends and the next part begins.

Each part can contain text or @-commands.  The text
is printed as if the part were within an ordinary paragraph in the
body of the page.  The @-commands replace
themselves with the page number, date, chapter name, or
whatever.

Here are the six heading and footing commands:

@everyheading left @| center @| right

@everyfooting left @| center @| right

The `every' commands specify the format for both even- and odd-numbered
pages.  These commands are for documents that are printed on one side
of each sheet of paper, or for documents in which you want symmetrical
headers or footers.

@evenheading left @| center @| right

@oddheading  left @| center @| right

@evenfooting left @| center @| right

@oddfooting  left @| center @| right

The `even' and `odd' commands specify the format for even-numbered
pages and odd-numbered pages.  These commands are for books and
manuals that are printed on both sides of each sheet of paper.

Use the `@this...' series of @-commands to
provide the names of chapters
and sections and the page number.  You can use the
`@this...' commands in the left, center, or right portions
of headers and footers, or anywhere else in a Texinfo file so long as
they are between @iftex and @end iftex commands.

Here are the `@this...' commands:

@thispage

Expands to the current page number.

@thischaptername

Expands to the name of the current chapter.

@thischapter

Expands to the number and name of the current
chapter, in the format `Chapter 1: Title'.

@thistitle

Expands to the name of the document, as specified by the
@settitle command.

@thisfile

For @include files only: expands to the name of the current
@include file.  If the current Texinfo source file is not an
@include file, this command has no effect.  This command does
not provide the name of the current Texinfo source file unless
it is an @include file.  (See section Include Files, for more
information about @include files.)

You can also use the @today{} command, which expands to the
current date, in `1 Jan 1900' format.

Other @-commands and text are printed in a header or footer just as
if they were in the body of a page.  It is useful to incorporate text,
particularly when you are writing drafts:

@iftex
@headings off
@everyheading @emph{Draft!} @| @thispage @| @thischapter
@everyfooting @| @| Version: 0.27: @today{}
@end iftex

Beware of overlong titles: they may overlap another part of the
header or footer and blot it out.

Formatting Mistakes

Besides mistakes in the content of your documentation, there
are two kinds of mistake you can make with Texinfo:  you can make mistakes
with @-commands, and you can make mistakes with the structure of the
nodes and chapters.

Emacs has two tools for catching the @-command mistakes and two for
catching structuring mistakes.

For finding problems with @-commands, you can run TeX or a region
formatting command on the region that has a problem; indeed, you can
run these commands on each region as you write it.

For finding problems with the structure of nodes and chapters, you can use
C-c C-s (texinfo-show-structure) and the related occur
command and you can use the M-x Info-validate command.

The makeinfo program does an excellent job of catching errors
and reporting them--far better than texinfo-format-region or
texinfo-format-buffer.  In addition, the various functions for
automatically creating and updating node pointers and menus remove
many opportunities for human error.

If you can, use the updating commands to create and insert pointers
and menus.  These prevent many errors.  Then use makeinfo (or
its Texinfo mode manifestations, makeinfo-region and
makeinfo-buffer) to format your file and check for other
errors.  This is the best way to work with Texinfo.  But if you
cannot use makeinfo, or your problem is very puzzling, then you
may want to use the tools described in this appendix.

Catching Errors with Info Formatting

After you have written part of a Texinfo file, you can use the
texinfo-format-region or the makeinfo-region command to
see whether the region formats properly.

Most likely, however, you are reading this section because for some
reason you cannot use the makeinfo-region command; therefore, the
rest of this section presumes that you are using
texinfo-format-region.

If you have made a mistake with an @-command,
texinfo-format-region will stop processing at or after the
error and display an error message.  To see where in the buffer the
error occurred, switch to the `*Info Region*' buffer; the cursor
will be in a position that is after the location of the error.  Also,
the text will not be formatted after the place where the error
occurred (or more precisely, where it was detected).

For example, if you accidentally end a menu with the command @end
menus with an `s' on the end, instead of with @end menu, you
will see an error message that says:

@end menus is not handled by texinfo

The cursor will stop at the point in the buffer where the error
occurs, or not long after it.  The buffer will look like this:

---------- Buffer: *Info Region* ----------
* Menu:

* Using texinfo-show-structure::  How to use
                                  `texinfo-show-structure'
                                  to catch mistakes.
* Running Info-Validate::         How to check for
                                  unreferenced nodes.
@end menus
-!-
---------- Buffer: *Info Region* ----------

The texinfo-format-region command sometimes provides slightly
odd error messages.  For example, the following cross reference fails to format:

(@xref{Catching Mistakes, for more info.)

In this case, texinfo-format-region detects the missing closing
brace but displays a message that says `Unbalanced parentheses'
rather than `Unbalanced braces'.  This is because the formatting
command looks for mismatches between braces as if they were
parentheses.

Sometimes texinfo-format-region fails to detect mistakes.  For
example, in the following, the closing brace is swapped with the
closing parenthesis:

(@xref{Catching Mistakes), for more info.}

Formatting produces:

(*Note for more info.: Catching Mistakes)

The only way for you to detect this error is to realize that the
reference should have looked like this:

(*Note Catching Mistakes::, for more info.)

Incidentally, if you are reading this node in Info and type f
RET (Info-follow-reference), you will generate an error
message that says:

No such node: "Catching Mistakes) The only way ...

This is because Info perceives the example of the error as the first
cross reference in this node and if you type a RET immediately
after typing the Info f command, Info will attempt to go to the
referenced node.  If you type f catch TAB RET, Info
will complete the node name of the correctly written example and take
you to the `Catching Mistakes' node.  (If you try this, you can return
from the `Catching Mistakes' node by typing l
(Info-last).)

Catching Errors with TeX Formatting

You can also catch mistakes when you format a file with TeX.

Usually, you will want to do this after you have run
texinfo-format-buffer (or, better, makeinfo-buffer) on
the same file, because texinfo-format-buffer sometimes displays
error messages that make more sense than TeX.  (See section Catching Errors with Info Formatting, for more information.)

For example, TeX was run on a Texinfo file, part of which is shown
here:

---------- Buffer: texinfo.texi ----------
name of the Texinfo file as an extension.  The
@samp{??} are `wildcards' that cause the shell to
substitute all the raw index files.  (@xref{sorting
indices, for more information about sorting
indices.)@refill
---------- Buffer: texinfo.texi ----------

(The cross reference lacks a closing brace.)
TeX produced the following output, after which it stopped:

---------- Buffer: *tex-shell* ----------
Runaway argument?
{sorting indices, for more information about sorting
indices.) @refill @ETC.
! Paragraph ended before @xref was complete.
<to be read again>
                   @par
l.27

?
---------- Buffer: *tex-shell* ----------

In this case, TeX produced an accurate and
understandable error message:

Paragraph ended before @xref was complete.

`@par' is an internal TeX command of no relevance to Texinfo.
`l.27' means that TeX detected the problem on line 27 of the
Texinfo file.  The `?' is the prompt TeX uses in this
circumstance.

Unfortunately, TeX is not always so helpful, and sometimes you must
truly be a Sherlock Holmes to discover what went wrong.

In any case, if you run into a problem like this, you can do one of three
things.

  1.

You can tell TeX to continue running and ignore just this error by
typing RET at the `?' prompt.

  2.

You can tell TeX to continue running and to ignore all errors as best
it can by typing r RET at the `?' prompt.
This is often the best thing to do.  However, beware: the one error
may produce a cascade of additional error messages as its consequences
are felt through the rest of the file.  To stop TeX when it is
producing such an avalanche of error messages, type C-c (or
C-c C-c, if you are running a shell inside Emacs).

  3.

You can tell TeX to stop this run by typing x RET
at the `?' prompt.

If you are running TeX inside Emacs, you need to switch to the shell
buffer and line at which TeX offers the `?' prompt.

Sometimes TeX will format a file without producing error messages even
though there is a problem.  This usually occurs if a command is not ended
but TeX is able to continue processing anyhow.  For example, if you fail
to end an itemized list with the @end itemize command, TeX will
write a DVI file that you can print out.  The only error message that
TeX will give you is the somewhat mysterious comment that

(@end occurred inside a group at level 1)

However, if you print the DVI file, you will find that the text
of the file that follows the itemized list is entirely indented as if
it were part of the last item in the itemized list.  The error message
is the way TeX says that it expected to find an @end
command somewhere in the file; but that it could not determine where
it was needed.

Another source of notoriously hard-to-find errors is a missing
@end group command.  If you ever are stumped by
incomprehensible errors, look for a missing @end group command
first.

If the Texinfo file lacks header lines,
TeX may stop in the
beginning of its run and display output that looks like the following.
The `*' indicates that TeX is waiting for input.

This is TeX, Version 3.14159 (Web2c 7.0)
(test.texinfo [1])
*

In this case, simply type \end RET after the asterisk.  Then
write the header lines in the Texinfo file and run the TeX command
again. (Note the use of the backslash, `\'.  TeX uses `\'
instead of `@'; and in this circumstance, you are working
directly with TeX, not with Texinfo.)

Using texinfo-show-structure

It is not always easy to keep track of the nodes, chapters, sections, and
subsections of a Texinfo file.  This is especially true if you are revising
or adding to a Texinfo file that someone else has written.

In GNU Emacs, in Texinfo mode, the texinfo-show-structure
command lists all the lines that begin with the @-commands that
specify the structure: @chapter, @section,
@appendix, and so on.  With an argument (C-u
as prefix argument, if interactive),
the command also shows the @node lines.  The
texinfo-show-structure command is bound to C-c C-s in
Texinfo mode, by default.

The lines are displayed in a buffer called the `*Occur*' buffer,
indented by hierarchical level.  For example, here is a part of what was
produced by running texinfo-show-structure on this manual:

 Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
 in buffer texinfo.texi.
 ...
 4177:@chapter Nodes
 4198:    @heading Two Paths
 4231:    @section Node and Menu Illustration
 4337:    @section The @code{@@node} Command
 4393:        @subheading Choosing Node and Pointer Names
 4417:        @subsection How to Write an @code{@@node} Line
 4469:        @subsection @code{@@node} Line Tips
 ...

This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin
with the @section, @subheading, and @subsection
commands respectively.  If you move your cursor into the `*Occur*'
window, you can position the cursor over one of the lines and use the
C-c C-c command (occur-mode-goto-occurrence), to jump to
the corresponding spot in the Texinfo file.  See section `Using Occur' in The GNU Emacs Manual, for more
information about occur-mode-goto-occurrence.

The first line in the `*Occur*' window describes the regular
expression specified by texinfo-heading-pattern.  This regular
expression is the pattern that texinfo-show-structure looks for.
See section `Using Regular Expressions' in The GNU Emacs Manual,
for more information.

When you invoke the texinfo-show-structure command, Emacs will
display the structure of the whole buffer.  If you want to see the
structure of just a part of the buffer, of one chapter, for example,
use the C-x n n (narrow-to-region) command to mark the
region.  (See section `Narrowing' in The GNU Emacs Manual.)  This is
how the example used above was generated.  (To see the whole buffer
again, use C-x n w (widen).)

If you call texinfo-show-structure with a prefix argument by
typing C-u C-c C-s, it will list lines beginning with
@node as well as the lines beginning with the @-sign commands
for @chapter, @section, and the like.

You can remind yourself of the structure of a Texinfo file by looking at
the list in the `*Occur*' window; and if you have mis-named a node
or left out a section, you can correct the mistake.

Using occur

Sometimes the texinfo-show-structure command produces too much
information.  Perhaps you want to remind yourself of the overall structure
of a Texinfo file, and are overwhelmed by the detailed list produced by
texinfo-show-structure.  In this case, you can use the occur
command directly.  To do this, type

M-x occur

and then, when prompted, type a regexp, a regular expression for
the pattern you want to match.  (See section `Regular Expressions' in The GNU Emacs Manual.)  The occur command works from
the current location of the cursor in the buffer to the end of the
buffer.  If you want to run occur on the whole buffer, place
the cursor at the beginning of the buffer.

For example, to see all the lines that contain the word
`@chapter' in them, just type `@chapter'.  This will
produce a list of the chapters.  It will also list all the sentences
with `@chapter' in the middle of the line.

If you want to see only those lines that start with the word
`@chapter', type `^@chapter' when prompted by
occur.  If you want to see all the lines that end with a word
or phrase, end the last word with a `$'; for example,
`catching mistakes$'.  This can be helpful when you want to see
all the nodes that are part of the same chapter or section and
therefore have the same `Up' pointer.

See section `Using Occur' in The GNU Emacs Manual,
for more information.

Finding Badly Referenced Nodes

You can use the Info-validate command to check whether any of
the `Next', `Previous', `Up' or other node pointers fail to point to a
node.  This command checks that every node pointer points to an
existing node.  The Info-validate command works only on Info
files, not on Texinfo files.

The makeinfo program validates pointers automatically, so you
do not need to use the Info-validate command if you are using
makeinfo.  You only may need to use Info-validate if you
are unable to run makeinfo and instead must create an Info file
using texinfo-format-region or texinfo-format-buffer, or
if you write an Info file from scratch.

Running Info-validate

To use Info-validate, visit the Info file you wish to check and
type:

M-x Info-validate

Note that the Info-validate command requires an upper case
`I'.  You may also need to create a tag table before running
Info-validate.  See section Tagifying a File.

If your file is valid, you will receive a message that says "File appears
valid".  However, if you have a pointer that does not point to a node,
error messages will be displayed in a buffer called `*problems in
info file*'.

For example, Info-validate was run on a test file that contained
only the first node of this manual.  One of the messages said:

In node "Overview", invalid Next: Texinfo Mode

This meant that the node called `Overview' had a `Next' pointer that
did not point to anything (which was true in this case, since the test file
had only one node in it).

Now suppose we add a node named `Texinfo Mode' to our test case
but we do not specify a `Previous' for this node.  Then we will get
the following error message:

In node "Texinfo Mode", should have Previous: Overview

This is because every `Next' pointer should be matched by a
`Previous' (in the node where the `Next' points) which points back.

Info-validate also checks that all menu entries and cross references
point to actual nodes.

Info-validate requires a tag table and does not work with files
that have been split.  (The texinfo-format-buffer command
automatically splits large files.)  In order to use Info-validate
on a large file, you must run texinfo-format-buffer with an
argument so that it does not split the Info file; and you must create a
tag table for the unsplit file.

Creating an Unsplit File

You can run Info-validate only on a single Info file that has a
tag table.  The command will not work on the indirect subfiles that
are generated when a master file is split.  If you have a large file
(longer than 70,000 bytes or so), you need to run the
texinfo-format-buffer or makeinfo-buffer command in such
a way that it does not create indirect subfiles.  You will also need
to create a tag table for the Info file.  After you have done this,
you can run Info-validate and look for badly referenced
nodes.

The first step is to create an unsplit Info file.  To prevent
texinfo-format-buffer from splitting a Texinfo file into
smaller Info files, give a prefix to the M-x
texinfo-format-buffer command:

C-u M-x texinfo-format-buffer

or else

C-u C-c C-e C-b

When you do this, Texinfo will not split the file and will not create
a tag table for it.

Tagifying a File

After creating an unsplit Info file, you must create a tag table for
it.  Visit the Info file you wish to tagify and type:

M-x Info-tagify

(Note the upper case `I' in Info-tagify.)  This creates an
Info file with a tag table that you can validate.

The third step is to validate the Info file:

M-x Info-validate

(Note the upper case `I' in Info-validate.)
In brief, the steps are:

C-u M-x texinfo-format-buffer
M-x Info-tagify
M-x Info-validate

After you have validated the node structure, you can rerun
texinfo-format-buffer in the normal way so it will construct a
tag table and split the file automatically, or you can make the tag
table and split the file manually.

Splitting a File Manually

You should split a large file or else let the
texinfo-format-buffer or makeinfo-buffer command do it
for you automatically.  (Generally you will let one of the formatting
commands do this job for you.  See section Creating an Info File.)

The split-off files are called the indirect subfiles.

Info files are split to save memory.  With smaller files, Emacs does not
have make such a large buffer to hold the information.

If an Info file has more than 30 nodes, you should also make a tag
table for it. See section Running Info-validate, for information
about creating a tag table.  (Again, tag tables are usually created
automatically by the formatting command; you only need to create a tag
table yourself if you are doing the job manually.  Most likely, you
will do this for a large, unsplit file on which you have run
Info-validate.)

Visit the Info file you wish to tagify and split and type the two
commands:

M-x Info-tagify
M-x Info-split

(Note that the `I' in `Info' is upper case.)

When you use the Info-split command, the buffer is modified into a
(small) Info file which lists the indirect subfiles.  This file should be
saved in place of the original visited file.  The indirect subfiles are
written in the same directory the original file is in, with names generated
by appending `-' and a number to the original file name.

The primary file still functions as an Info file, but it contains just
the tag table and a directory of subfiles.

Refilling Paragraphs

The @refill command refills and, optionally, indents the first
line of a paragraph.(14) The
@refill command is no longer important, but we describe it here
because you once needed it.  You will see it in many old Texinfo
files.

Without refilling, paragraphs containing long @-constructs may look
bad after formatting because the formatter removes @-commands and
shortens some lines more than others.  In the past, neither the
texinfo-format-region command nor the
texinfo-format-buffer command refilled paragraphs
automatically.  The @refill command had to be written at the
end of every paragraph to cause these formatters to fill them.  (Both
TeX and makeinfo have always refilled paragraphs
automatically.)  Now, all the Info formatters automatically fill and
indent those paragraphs that need to be filled and indented.

The @refill command causes texinfo-format-region and
texinfo-format-buffer to refill a paragraph in the Info file
after all the other processing has been done.  For this reason,
you can not use @refill with a paragraph containing either
@* or @w{ ... } since the refilling action will
override those two commands.

The texinfo-format-region and texinfo-format-buffer
commands now automatically append @refill to the end of each
paragraph that should be filled.  They do not append @refill to
the ends of paragraphs that contain @* or @w{ ...}
and therefore do not refill or indent them.

@-Command Syntax

The character `@' is used to start special Texinfo commands.
(It has the same meaning that `\' has in plain TeX.)  Texinfo
has four types of @-command:

1. Non-alphabetic commands.

These commands consist of an @ followed by a punctuation mark or other
character that is not part of the alphabet.  Non-alphabetic commands are
almost always part of the text within a paragraph, and never take any
argument.  The two characters (@ and the other one) are complete in
themselves; none is followed by braces.  The non-alphabetic commands
are: @., @:, @*, @SPACE,
@TAB, @NL, @@, @{, and
@}.

2. Alphabetic commands that do not require arguments.

These commands start with @ followed by a word followed by left- and
right-hand braces.  These commands insert special symbols in the
document; they do not require arguments.  For example,
@dots{} => `...', @equiv{}
=> `==', @TeX{} => `TeX',
and @bullet{} => `*'.

3. Alphabetic commands that require arguments within braces.

These commands start with @ followed by a letter or a word, followed by an
argument within braces.  For example, the command @dfn indicates
the introductory or defining use of a term; it is used as follows: `In
Texinfo, @@-commands are @dfn{mark-up} commands.'

4. Alphabetic commands that occupy an entire line.

These commands occupy an entire line.  The line starts with @,
followed by the name of the command (a word); for example, @center
or @cindex.  If no argument is needed, the word is followed by
the end of the line.  If there is an argument, it is separated from
the command name by a space.  Braces are not used.

Thus, the alphabetic commands fall into classes that have
different argument syntaxes.  You cannot tell to which class a command
belongs by the appearance of its name, but you can tell by the
command's meaning: if the command stands for a glyph, it is in
class 2 and does not require an argument; if it makes sense to use the
command together with other text as part of a paragraph, the command
is in class 3 and must be followed by an argument in braces;
otherwise, it is in class 4 and uses the rest of the line as its
argument.

The purpose of having a different syntax for commands of classes 3 and
4 is to make Texinfo files easier to read, and also to help the GNU
Emacs paragraph and filling commands work properly.  There is only one
exception to this rule: the command @refill, which is always
used at the end of a paragraph immediately following the final period
or other punctuation character.  @refill takes no argument and
does not require braces.  @refill never confuses the
Emacs paragraph commands because it cannot appear at the beginning of
a line.

How to Obtain TeX

TeX is freely redistributable.  You can obtain TeX for Unix
systems via anonymous ftp or on physical media.  The core material
consists of the Web2c TeX distribution (http://tug.org/web2c).

Instructions for retrieval by anonymous ftp and information on other
available distributions:

ftp://tug.org/tex/unixtex.ftp
http://tug.org/unixtex.ftp

The Free Software Foundation provides a core distribution on its Source
Code CD-ROM suitable for printing Texinfo manuals.  To order it, contact:

Free Software Foundation, Inc.
59 Temple Place Suite 330
Boston, MA   02111-1307
USA
Telephone: +1-617-542-5942
Fax: (including Japan) +1-617-542-2652
Free Dial Fax (in Japan):
      0031-13-2473 (KDD)
      0066-3382-0158 (IDC)
Electronic mail: gnu@gnu.org

Many other TeX distributions are available; see
http://tug.org/.

Command and Variable Index

This is an alphabetical list of all the @-commands, assorted Emacs Lisp
functions, and several variables.  To make the list easier to use, the
commands are listed without their preceding `@'.

!

  • ! (end of sentence)

    •

    "

  • "

    •

    '

  • '

    •

    (

  • (newline)

  • (space)

  • (tab)

    •

    *

  • * (force line break)

    •

    ,

  • ,

    •

    -

  • -

    •

    .

  • .  (end of sentence)

    •

    :

  • : (suppress widening)

    •

    =

  • =

    •

    ?

  • ? (end of sentence)

    •

    @

  • @ (single `@')

    •

    \

  • \emergencystretch

    •

    ^

  • ^

    •

    `

  • `

    •

    a

  • AA

  • aa

  • acronym

  • AE

  • ae

  • afourlatex

  • afourpaper

  • alias

  • anchor

  • appendix

  • appendixsec

  • appendixsection

  • appendixsubsec

  • appendixsubsubsec

  • apply

  • asis

  • author

    •

    b

  • b (bold font)

  • buffer-end

  • bullet

  • bye, bye

    •

    c

  • c (comment)

  • cartouche

  • center

  • centerchap

  • chapheading

  • chapter

  • cindex

  • cite

  • clear

  • code

  • columnfractions

  • command

  • comment

  • contents

  • copyright, copyright

  • cropmarks

    •

    d

  • defcodeindex

  • defcv

  • deffn

  • deffnx

  • defindex

  • definfoenclose

  • defivar

  • defmac

  • defmethod, defmethod

  • defop

  • defopt

  • defspec

  • deftp

  • deftypefn

  • deftypefun

  • deftypeivar

  • deftypeop

  • deftypevar

  • deftypevr

  • defun

  • defvar

  • defvr

  • Development/Docs/Texinfo Customize group

  • dfn

  • dircategory

  • direntry

  • display

  • dmn

  • documentencoding

  • documentlanguage

  • dotaccent

  • dotless

  • dots

    •

    e

  • email

  • emph

  • end, end

  • end titlepage

  • enddots

  • enumerate

  • env

  • equiv

  • error

  • evenfooting

  • evenheading

  • everyfooting

  • everyheading

  • example

  • exampleindent

  • exclamdown

  • exdent

  • expansion

    •

    f

  • file

  • filll

  • finalout

  • findex

  • flushleft

  • flushright

  • foobar, foobar, foobar

  • footnote

  • footnotestyle

  • format

  • forward-word

  • ftable

    •

    g

  • group

    •

    h

  • H

  • hbox

  • heading

  • headings

  • headword

  • html

  • hyphenation

    •

    i

  • i (italic font)

  • ifclear

  • ifhtml, ifhtml

  • ifinfo

  • ifnothtml

  • ifnotinfo

  • ifnottex

  • ifset

  • iftex

  • ignore

  • image

  • include

  • Info-validate

  • inforef

  • input (TeX command)

  • isearch-backward

  • isearch-forward

  • item, item, item

  • itemize

  • itemx

    •

    k

  • kbd

  • kbdinputstyle

  • key

  • kindex

    •

    l

  • L

  • l

  • lisp

  • lowersections

    •

    m

  • macro

  • mag (TeX command)

  • majorheading

  • makeinfo-buffer

  • makeinfo-kill-job

  • makeinfo-recenter-output-buffer

  • makeinfo-region

  • math

  • menu

  • minus

  • multitable

    •

    n

  • need

  • next-error

  • node

  • noindent

  • novalidate

    •

    o

  • O

  • o

  • occur

  • occur-mode-goto-occurrence

  • oddfooting

  • oddheading

  • OE

  • oe

  • option

    •

    p

  • page

  • page, within @titlepage

  • pagesizes

  • paragraphindent

  • phoo

  • pindex

  • point

  • pounds

  • print

  • printindex

  • pxref

    •

    q

  • questiondown

  • quotation

    •

    r

  • r (Roman font)

  • raisesections

  • ref

  • refill

  • result

  • ringaccent

  • rmacro

    •

    s

  • samp

  • sc (small caps font)

  • section

  • set

  • setchapternewpage

  • setcontentsaftertitlepage

  • setfilename

  • setshortcontentsaftertitlepage

  • settitle

  • shortcontents

  • shorttitlepage

  • smallbook

  • smalldisplay, smalldisplay

  • smallexample

  • smallformat, smallformat

  • smalllisp

  • sp (line spacing)

  • sp (titlepage line spacing)

  • ss

  • strong

  • subheading

  • subsection

  • subsubheading

  • subsubsection

  • subtitle

  • summarycontents

  • syncodeindex, syncodeindex

  • synindex

    •

    t

  • t (typewriter font)

  • tab

  • table

  • tex

  • tex (command)

  • texinfo-all-menus-update

  • texinfo-every-node-update

  • texinfo-format-buffer, texinfo-format-buffer, texinfo-format-buffer

  • texinfo-format-region, texinfo-format-region, texinfo-format-region

  • texinfo-indent-menu-description

  • texinfo-insert-@code

  • texinfo-insert-@dfn

  • texinfo-insert-@end

  • texinfo-insert-@example

  • texinfo-insert-@item

  • texinfo-insert-@kbd

  • texinfo-insert-@node

  • texinfo-insert-@noindent

  • texinfo-insert-@samp

  • texinfo-insert-@table

  • texinfo-insert-@var

  • texinfo-insert-braces

  • texinfo-insert-node-lines

  • texinfo-make-menu

  • texinfo-master-menu

  • texinfo-multiple-files-update

  • texinfo-multiple-files-update (in brief)

  • texinfo-sequential-node-update

  • texinfo-show-structure, texinfo-show-structure

  • texinfo-start-menu-description

  • texinfo-tex-buffer

  • texinfo-tex-print

  • texinfo-tex-region

  • texinfo-update-node

  • thischapter

  • thischaptername

  • thisfile

  • thispage

  • thistitle

  • tieaccent

  • tindex

  • title

  • titlefont

  • titlepage

  • today

  • top (@-command)

    •

    u

  • u

  • ubaraccent

  • udotaccent

  • unmacro

  • unnumbered

  • unnumberedsec

  • unnumberedsubsec

  • unnumberedsubsubsec

  • up-list

  • uref

  • url

    •

    v

  • v

  • value

  • var

  • vindex

  • vskip

  • vtable

    •

    w

  • w (prevent line break)

    •

    x

  • xref

    •

    {

  • { (single `{')

    •

    }

  • } (single `}')

    •

    ~

  • ~

    •

    Concept Index

    &

  • ¡

  • ¿

  • Å

  • Æ

  • Ø

  • ß

  • å

  • æ

  • ø

    •

    (

  • (dir) as Up node of Top node

    •

    .

  • .cshrc initialization file

  • .profile initialization file

    •

    :

  • `:' last in @env{INFOPATH}

    •

    <

  • <URL: convention, not used

    •

    @

  • @-command list

  • @-command syntax

  • @-commands

  • @-commands in @node, limited support

  • @-commands in nodename

  • @dotless{i}

  • @dotless{j}

  • @include file sample

  • @menu parts

  • @node line writing

  • @value in @node lines

  • @w, for blank items

    •

    \

  • `\input' source line ignored

    •

    a

  • A4 paper, printing on

  • Abbreviations for keys

  • Abbreviations, tagging

  • Accents, inserting

  • Acronyms, tagging

  • Acute accent

  • Adding a new info file

  • African languages

  • Aliases, command

  • Alphabetical @-command list

  • Anchors

  • Another Info directory

  • Apostrophe in nodename

  • Arguments, repeated and optional

  • ASCII text output

  • Aspect ratio of images

  • autoexec.bat

  • Automatic pointer creation with makeinfo

  • Automatically insert nodes, menus

  • Auxiliary files, avoiding

    •

    b

  • B5 paper, printing on

  • Backslash in macros

  • Backslash, and macros

  • Badly referenced nodes

  • Bastard title page

  • Batch formatting for Info

  • Beginning a Texinfo file

  • Beginning line of a Texinfo file

  • Berry, Karl

  • Big points

  • Black rectangle in hardcopy

  • Blank lines

  • Body of a macro

  • Bolio

  • Book characteristics, printed

  • Book, printing small

  • BoTeX

  • Box with rounded corners

  • Box, ugly black in hardcopy

  • Braces and argument syntax

  • Braces, inserting

  • Braces, when to use

  • Breaks in a line

  • Breve accent

  • Buffer formatting and printing

  • Bugs, reporting

  • Bullets, inserting

    •

    c

  • Case in nodename

  • Case, not altering in @code

  • Catching errors with Info formatting

  • Catching errors with TeX formatting

  • Catching mistakes

  • Cedilla accent

  • Centimeters

  • Chapter structuring

  • Chapters, formatting one at a time

  • Characteristics, printed books or manuals

  • Characters, invalid in node name

  • Chassell, Robert J.

  • Check accent

  • Checking for badly referenced nodes

  • Checklist for bug reports

  • Ciceros

  • Circumflex accent

  • code, arg to @kbdinputstyle

  • Colon in nodename

  • Column widths, defining for multitables

  • Combining indices

  • Comma in nodename

  • Command aliases

  • Command definitions

  • Command names, indicating

  • Command syntax

  • Commands to insert special characters

  • Commands using raw HTML

  • Commands using raw TeX

  • Commands, inserting them

  • Comments

  • Compile command for formatting

  • Compressed files, reading

  • Conditionally visible text

  • Conditions for copying Texinfo

  • Contents, after title page

  • Contents, Table of

  • Contents-like outline of file structure

  • Conventions for writing definitions

  • Conventions, syntactic

  • Copying conditions

  • Copying permissions

  • Copying software

  • Copyright page

  • Correcting mistakes

  • Create nodes, menus automatically

  • Creating an Info file

  • Creating an unsplit file

  • Creating index entries

  • Creating pointers with makeinfo

  • Cropmarks for printing

  • Cross reference parts

  • Cross references

  • Cross references using @inforef

  • Cross references using @pxref

  • Cross references using @ref

  • Cross references using @xref

  • Cross-reference targets, arbitrary

  • Custom page sizes

  • Customize Emacs package

  • Customized highlighting

  • Customizing of TeX for Texinfo

    •

    d

  • Debugging the Texinfo structure

  • Debugging with Info formatting

  • Debugging with TeX formatting

  • Defining indexing entries

  • Defining macros

  • Defining new indices

  • Defining new Texinfo commands

  • Definition commands

  • Definition conventions

  • Definition template

  • Definitions grouped together

  • Definitions, a.k.a. macros

  • Depth of text area

  • Description for menu, start

  • Details of macro usage

  • Did@^ot points

  • Different cross reference commands

  • Dimension formatting

  • Dimensions and image sizes

  • `dir' directory for Info installation

  • `dir' file listing

  • `dir' file, creating your own

  • `dir' files and Info directories

  • Dir files, compressed

  • `dir', created by install-info

  • Display formatting

  • distinct, arg to @kbdinputstyle

  • Distorting images

  • Distribution

  • Docbook output format

  • Document input encoding

  • Document language, declaring

  • Dot accent

  • Dotless i, j

  • Dots, inserting, Dots, inserting

  • Double-colon menu entries

  • Dumping a .fmt file

  • DVI file

    •

    e

  • Ellipsis, inserting

  • Emacs

  • Emacs shell, format, print from

  • Emphasizing text

  • Emphasizing text, font for

  • enable

  • Encoding, declaring

  • `End' node footnote style

  • End of header line

  • End titlepage starts headings

  • Ending a Sentence

  • Ending a Texinfo file

  • Entries for an index

  • Entries, making index

  • Enumeration

  • Environment indentation

  • epsf.tex

  • epsf.tex, installing

  • Equivalence, indicating it

  • Error message, indicating it

  • Errors, parsing

  • Es-zet

  • European A4 paper

  • Evaluation glyph

  • Example for a small book

  • Example indentation

  • Example menu

  • example, arg to @kbdinputstyle

  • Examples, formatting them

  • Expanding macros

  • Expansion, indicating it

  • Expressions in a program, indicating

    •

    f

  • F.B.I., as acronym

  • File beginning

  • File ending

  • File section structure, showing it

  • Filling paragraphs

  • Final output

  • Finding badly referenced nodes

  • Fine-tuning, and hyphenation

  • First line of a Texinfo file

  • First node

  • Floating accents, inserting

  • Flooding

  • Fonts for indices

  • Fonts for printing, not for Info

  • Footings

  • Footnotes

  • Format a dimension

  • Format and print hardcopy

  • Format and print in Texinfo mode

  • Format file, dumping

  • Format with the compile command

  • Format, print from Emacs shell

  • Formats for images

  • Formatting a file for Info

  • Formatting commands

  • Formatting examples

  • Formatting for Info

  • Formatting for printing

  • Formatting headings and footings

  • Formatting requirements

  • Formatting with tex and texindex

  • Frequently used commands, inserting

  • fubar

  • Function definitions

    •

    g

  • General syntactic conventions

  • Generating menus with indices

  • Generating plain text files

  • German S

  • GIF, unsupported due to patents

  • Globbing

  • Glyphs

  • GNU Emacs

  • GNU Emacs shell, format, print from

  • Going to other Info files' nodes

  • Grave accent

  • Group (hold text together vertically)

  • Grouping two definitions together

    •

    h

  • Hardcopy, printing it

  • `hboxes', overfull

  • Header for Texinfo files

  • Header of a Texinfo file

  • Headings

  • Headings, page, begin to appear

  • Height of images

  • Height of text area

  • help2man

  • Highlighting text

  • Highlighting, customized

  • Hints

  • History of Texinfo

  • Holding text together vertically

  • href, producing HTML

  • HTML

  • HTML commands, using ordinary

  • http-equiv, and charset

  • Hungarian umlaut accent

  • Hurricanes

  • Hyphenation patterns, language-dependent

  • Hyphenation, helping TeX do

  • Hyphenation, preventing

    •

    i

  • If text conditionally visible

  • `ifinfo' permissions

  • Ignored before @setfilename

  • Ignored text

  • Image formats

  • Images, inserting

  • Inches

  • Include file requirements

  • Include file sample

  • Include files

  • Include files, and section levels

  • Indentation undoing

  • Indenting environments

  • Indenting paragraphs

  • Index entries

  • Index entries, making

  • Index entry writing

  • Index file names

  • Index font types

  • Indexing commands, predefined

  • Indexing table entries automatically

  • Indicating commands, definitions, etc.

  • Indicating evaluation

  • Indices

  • Indices, combining them

  • Indices, defining new

  • Indices, printing and menus

  • Indices, sorting

  • Indices, two letter names

  • Indirect subfiles

  • Info batch formatting

  • Info file installation

  • Info file requires @setfilename

  • Info file, listing a new

  • Info file, splitting manually

  • Info files

  • Info formatting

  • Info installed in another directory

  • Info validating a large file

  • Info, creating an online file

  • Info-directory-list

  • Info; other files' nodes

  • INFOPATH

  • Initialization file for TeX input

  • Input encoding, declaring

  • Insert nodes, menus automatically

  • Inserting @, braces

  • Inserting accents

  • Inserting dots, Inserting dots

  • Inserting ellipsis

  • Inserting frequently used commands

  • Inserting space

  • Inserting special characters and symbols

  • `INSTALL' file, generating

  • install-info

  • Installing an Info file

  • Installing Info in another directory

  • Internationalization

  • Introduction to Texinfo

  • Introduction, as part of file

  • Invalid characters in node names

  • Invoking macros

  • ISO 639 codes

  • Itemization

    •

    j

  • JPEG image format

    •

    k

  • Keyboard input

  • Keys, recommended names

  • Keywords, indicating

  • Knuth, Donald

    •

    l

  • L/

  • l/

  • Language codes

  • Language, declaring

  • Larger or smaller pages

  • Legal paper, printing on

  • Less cluttered menu entry

  • License agreement

  • Line breaks

  • Line breaks, preventing

  • Line length, column widths as fraction of

  • Line spacing

  • Lisp example

  • Lisp example for a small book

  • List of  @-commands

  • Listing a new info file

  • Lists and tables, making

  • Local variables

  • Location of menus

  • Looking for badly referenced nodes

  • lpr (DVI print command)

  • lpr-d, replacements on MS-DOS/MS-Windows

    •

    m

  • Macro definitions, Macro definitions

  • Macro details

  • Macro invocation

  • Macron accent

  • Macros

  • Macros, undefining

  • Magnified printing

  • mailto link

  • makeinfo

  • makeinfo inside Emacs

  • makeinfo options

  • Making a printed manual

  • Making a tag table automatically

  • Making a tag table manually

  • Making cross references

  • Making line and page breaks

  • Making lists and tables

  • Man page output, not supported

  • Man page, reference to

  • Manual characteristics, printed

  • Margins on page, not controllable

  • Marking text within a paragraph

  • Marking words and phrases

  • Master menu

  • Master menu parts

  • Mathematical expressions, Mathematical expressions

  • Menu description, start

  • Menu entries with two colons

  • Menu example

  • Menu location

  • Menu parts

  • Menu writing

  • Menus

  • Menus generated with indices

  • meta HTML tag, and charset

  • META key

  • Meta-syntactic chars for arguments

  • Millimeters

  • Minimal requirements for formatting

  • Minimal Texinfo file (requirements)

  • Mistakes, catching

  • Mode, using Texinfo

  • Multiple spaces

  • Multitable column widths

  • Multitable rows

  • Must have in Texinfo file

  • Mutually recursive macros

    •

    n

  • Names for indices

  • Names of index files

  • Names recommended for keys

  • Naming a `Top' Node in references

  • NASA, as acronym

  • Navigation links, omitting

  • Need space at page bottom

  • New index defining

  • New info file, listing it in `dir' file

  • New Texinfo commands, defining

  • Node line requirements

  • Node line writing

  • Node name must be unique

  • Node name, should not contain @-commands

  • Node names, choosing

  • Node, `Top'

  • Node, defined

  • Nodes for menus are short

  • Nodes in other Info files

  • Nodes, catching mistakes

  • Nodes, checking for badly referenced

  • Non-breakable space

  • Not ending a sentence

    •

    o

  • O'Dea, Brendan

  • Obtaining TeX

  • Occurrences, listing with @occur

  • OE

  • oe

  • Optional and repeated arguments

  • Options for makeinfo

  • Ordinary HTML commands, using

  • Ordinary TeX commands, using

  • Other Info files' nodes

  • Outline of file structure, showing it

  • Output file splitting

  • Output formats, supporting more

  • Overfull `hboxes'

  • Overview of Texinfo

    •

    p

  • Page breaks

  • Page delimiter in Texinfo mode

  • Page headings

  • Page numbering

  • Page sizes for books

  • Page sizes, customized

  • page-delimiter

  • Pages, starting odd

  • Paper size, European A4

  • Paragraph indentation

  • Paragraph, marking text within

  • Paragraphs, filling

  • Parameters to macros

  • Parsing errors

  • Part of file formatting and printing

  • Parts of a cross reference

  • Parts of a master menu

  • Parts of a menu

  • PDF output

  • pdftex

  • pdftex, and images

  • Period in nodename

  • Periods, inserting

  • Permissions

  • Permissions, printed

  • Picas

  • Pictures, inserting

  • Pinard, Fran@,{c}ois

  • plain TeX

  • Plain text output

  • PNG image format

  • Point, indicating in a buffer

  • Pointer creation with makeinfo

  • Pointer validation with makeinfo

  • Pointer validation, suppressing, Pointer validation, suppressing

  • Points (dimension)

  • Predefined indexing commands

  • Predefined names for indices

  • Preparing for TeX

  • Preventing line and page breaks

  • Previous node of Top node

  • Print and format in Texinfo mode

  • Print, format from Emacs shell

  • Printed book and manual characteristics

  • Printed output, indicating it

  • Printed permissions

  • Printing a region or buffer

  • Printing an index

  • Printing cropmarks

  • Printing DVI files, on MS-DOS/MS-Windows

  • Printing hardcopy

  • Problems, catching

  • Program names, indicating

  • Prototype row, column widths defined by

    •

    q

  • Quotations

    •

    r

  • Raising and lowering sections

  • Raw formatter commands

  • Recommended names for keys

  • Rectangle, black in hardcopy

  • Recursion, mutual

  • Recursive macro invocations

  • Reference to @-commands

  • References

  • References using @inforef

  • References using @pxref

  • References using @ref

  • References using @xref

  • Referring to other Info files

  • Refilling paragraphs

  • Region formatting and printing

  • Region printing in Texinfo mode

  • Reid, Brian

  • Repeated and optional arguments

  • Reporting bugs

  • Required in Texinfo file

  • Requirements for formatting

  • Requirements for include files

  • Requirements for updating commands

  • Reserved words, indicating

  • Result of an expression

  • ridt.eps

  • Ring accent

  • Rows, of a multitable

  • Running an Info formatter

  • Running Info-validate

  • Running macros

  • Running makeinfo in Emacs

    •

    s

  • Sample @include file

  • Sample function definition

  • Sample permissions

  • Sample Texinfo file

  • Sample Texinfo file, no comments

  • Scaled points

  • Schwab, Andreas

  • Scribe

  • Sea surges

  • Section structure of a file, showing it

  • Sections, raising and lowering

  • Sentence ending punctuation

  • Sentence non-ending punctuation

  • `Separate' footnote style

  • SGML-tools output format

  • Sharp S

  • Shell formatting with tex and texindex

  • Shell printing, on MS-DOS/MS-Windows

  • Shell, format, print from

  • Shell, running makeinfo in

  • Short nodes for menus

  • Short table of contents

  • Showing the section structure of a file

  • Showing the structure of a file

  • Site-wide Texinfo configuration file

  • Size of printed book

  • slanted typewriter font, for @kbd

  • Small book example

  • Small book size

  • Small caps font

  • Software copying permissions

  • Sorting indices

  • Source file

  • Space, inserting horizontal

  • Space, inserting vertical

  • Spaces in macros

  • Spaces, in menus

  • Spacing, inserting

  • Special characters, commands to insert

  • Special insertions

  • Special typesetting commands

  • Specifying index entries

  • Splitting an Info file manually

  • Splitting of output files

  • Stallman, Richard M.

  • Start of header line

  • Starting chapters

  • Structure of a file, showing it

  • Structure, catching mistakes in

  • Structuring of chapters

  • Subsection-like commands

  • Subsub commands

  • Suggestions for Texinfo, making

  • Syntactic conventions

  • Syntactic tokens, indicating

  • Syntax, of @-commands

  • Syntax, optional & repeated arguments

    •

    t

  • Table of contents

  • Table of contents, after title page

  • Tables and lists, making

  • Tables with indexes

  • Tables, making multi-column

  • Tables, making two-column

  • Tabs; don't use!

  • Tag table, making automatically

  • Tag table, making manually

  • Targets for cross-references, arbitrary

  • Template for a definition

  • TeX commands, using ordinary

  • TeX index sorting

  • TeX input initialization

  • TeX, how to obtain

  • texi2dvi

  • texi2dvi (shell script)

  • texi2roff, unsupported software

  • texindex, texindex

  • Texinfo commands, defining new

  • Texinfo file beginning

  • Texinfo file ending

  • Texinfo file header

  • Texinfo file minimum

  • Texinfo file section structure, showing it

  • Texinfo mode

  • Texinfo overview

  • Texinfo printed book characteristics

  • Texinfo, introduction to

  • texinfo.cnf

  • texinfo.cnf installation

  • texinfo.tex, installing

  • TEXINPUTS, TEXINPUTS

  • TEXINPUTS environment variable

  • Text width and height

  • Text, conditionally visible

  • Text, marking up

  • Thin space between number, dimension

  • Tie-after accent

  • Tied space

  • Tilde accent

  • Tips

  • Title page

  • Title page, bastard

  • Titlepage end starts headings

  • Titlepage permissions

  • Titlepage, for plain text

  • `Top' node

  • Top node is first

  • `Top' node naming for references

  • `Top' node summary

  • Tree structuring

  • Two `First' Lines for @deffn

  • Two letter names for indices

  • Two named items for @table

  • Two part menu entry

  • `txi-cc.tex'

  • Typesetting commands for dots, etc.

    •

    u

  • Ugly black rectangles in hardcopy

  • Umlaut accent

  • Unbreakable space

  • Uncluttered menu entry

  • Undefining macros

  • Underbar accent

  • Underdot accent

  • Uniform resource locator, indicating

  • Uniform resource locator, referring to

  • Unique nodename requirement

  • Unprocessed text

  • Unsplit file creation

  • Up node of Top node

  • Updating nodes and menus

  • Updating requirements

  • URI syntax for Info

  • URL, indicating

  • URL, referring to

  • Usage tips

  • user input

  • User options, marking

  • User-defined Texinfo commands

  • Using Texinfo in general

    •

    v

  • Validating a large file

  • Validation of pointers

  • Value of an expression, indicating

  • version number, finding

  • Vertical whitespace (`vskip')

  • Vertically holding text together

  • Visibility of conditional text

    •

    w

  • Weinberg, Zack

  • Weisshaus, Melissa

  • Whitespace in macros

  • Whitespace, inserting

  • Width of images

  • Width of text area

  • Widths, defining multitable column

  • Wildcards

  • Words and phrases, marking them

  • Writing a menu

  • Writing an @node line

  • Writing index entries

    •

    z

  • Zaretskii, Eli

  • Zuhn, David D.

    •

    Footnotes

    (1)

    The first syllable of "Texinfo" is pronounced
like "speck", not "hex".  This odd pronunciation is derived from,
but is not the same as, the pronunciation of TeX.  In the word
TeX, the `X' is actually the Greek letter "chi" rather than
the English letter "ex".  Pronounce TeX as if the `X' were the
last sound in the name `Bach'; but pronounce Texinfo as if the `x'
were a `k'.  Spell "Texinfo" with a capital "T" and the other
letters in lower case.

    (2)

    In some documents, the first child has no `Previous'
pointer.  Occasionally, the last child has the node name of the next
following higher level node as its `Next' pointer.

    (3)

    You can also use the

texi2roff program if you
do not have TeX; since Texinfo is designed for use with TeX,
texi2roff is not described here.  texi2roff is not part of
the standard GNU distribution and is not maintained or up-to-date with
all the Texinfo features described in this manual.

    (4)

    The word
argument comes from the way it is used in mathematics and does not
refer to a dispute between two people; it refers to the information
presented to the command.  According to the Oxford English
Dictionary, the word derives from the Latin for to make clear,
prove; thus it came to mean `the evidence offered as proof', which is
to say, `the information offered', which led to its mathematical
meaning.  In its other thread of derivation, the word came to mean `to
assert in a manner against which others may make counter assertions',
which led to the meaning of `argument' as a dispute.

    (5)

    We have found
that it is helpful to refer to versions of manuals as `editions' and
versions of programs as `versions'; otherwise, we find we are liable to
confuse each other in conversation by referring to both the
documentation and the software with the same words.

    (6)

    Menus can
carry you to any node, regardless of the hierarchical structure; even to
nodes in a different Info file.  However, the GNU Emacs Texinfo mode
updating commands work only to create menus of subordinate nodes.
Conventionally, cross references are used to refer to other nodes.

    (7)

    It would be straightforward to extend Texinfo to work
in a similar fashion for C, Fortran, or other languages.

    (8)

    A footnote should complement or expand upon
the primary text, but a reader should not need to read a footnote to
understand the primary text.  For a thorough discussion of footnotes,
see The Chicago Manual of Style, which is published by the
University of Chicago Press.

    (9)

    Here
is the sample footnote.

    (10)

    Note the use
of the `;' character, instead of `:', as directory separator
on these systems.

    (11)

    On MS-DOS/MS-Windows systems, Info will
try the `.inf' extension as well.

    (12)

    Note the
use of `;' as the directory separator, and a different syntax for
using values of other environment variables.

    (13)

    On MS-DOS/MS-Windows systems, use semi-colon instead.

    (14)

    Perhaps the command should have been
called the @refillandindent command, but @refill is
shorter and the name was chosen before indenting was possible.

This document was generated on 23 August 2000 using the
texi2html
translator version 1.54.


Texinfo

The GNU Documentation Format

Edition 2.23, for Texinfo Version Three

October 1996

Robert J. Chassell
Richard M. Stallman

Table of Contents

  • Texinfo Copying Conditions
  • Overview of Texinfo
    • Info files
    • Printed Books
    • @-commands
    • General Syntactic Conventions
    • Comments
    • What a Texinfo File Must Have
    • Six Parts of a Texinfo File
    • A Short Sample Texinfo File
    • Acknowledgements
  • Using Texinfo Mode
    • The Usual GNU Emacs Editing Commands
    • Inserting Frequently Used Commands
    • Showing the Section Structure of a File
    • Updating Nodes and Menus
      • Updating Requirements
      • Other Updating Commands
    • Formatting for Info
    • Formatting and Printing
    • Texinfo Mode Summary
  • Beginning a Texinfo File
    • Sample Texinfo File Beginning
    • The Texinfo File Header
      • The First Line of a Texinfo File
      • Start of Header
      • @setfilename
      • @settitle
      • @setchapternewpage
      • Paragraph Indenting
      • End of Header
    • Summary and Copying Permissions for Info
    • The Title and Copyright Pages
      • @titlepage
      • @titlefont, @center, and @sp
      • @title, @subtitle, and @author
      • Copyright Page and Permissions
      • Heading Generation
      • The @headings Command
    • The `Top' Node and Master Menu
      • Parts of a Master Menu
    • Software Copying Permissions
  • Ending a Texinfo File
    • Index Menus and Printing an Index
    • Generating a Table of Contents
    • @bye File Ending
  • Chapter Structuring
    • Tree Structure of Sections
    • Types of Structuring Command
    • @top
    • @chapter
    • @unnumbered, @appendix
    • @majorheading, @chapheading
    • @section
    • @unnumberedsec, @appendixsec, @heading
    • The @subsection Command
    • The @subsection-like Commands
    • The `subsub' Commands
    • @raisesections and @lowersections
  • Nodes
    • Node and Menu Illustration
    • The @node Command
      • How to Write an @node Line
      • @node Line Tips
      • @node Line Requirements
      • The First Node
      • The @top Sectioning Command
      • The `Top' Node Summary
    • Creating Pointers with makeinfo
  • Menus
    • Writing a Menu
    • The Parts of a Menu
    • Less Cluttered Menu Entry
    • A Menu Example
    • Referring to Other Info Files
  • Cross References
    • Different Cross Reference Commands
    • Parts of a Cross Reference
    • @xref
      • @xref with One Argument
      • @xref with Two Arguments
      • @xref with Three Arguments
      • @xref with Four and Five Arguments
    • Naming a `Top' Node
    • @ref
    • @pxref
    • @inforef
  • Marking Words and Phrases
    • Indicating Definitions, Commands, etc.
      • @code{sample-code}
      • @kbd{keyboard-characters}
      • @key{key-name}
      • @samp{text}
      • @var{metasyntactic-variable}
      • @file{file-name}
      • @dfn{term}
      • @cite{reference}
      • @url{uniform-resource-locator}
      • @email{email-address}
    • Emphasizing Text
      • @emph{text} and @strong{text}
      • @sc{text}: The Small Caps Font
      • Fonts for Printing, Not Info
      • Customized Highlighting
  • Quotations and Examples
    • The Block Enclosing Commands
    • @quotation
    • @example
    • @noindent
    • @lisp
    • @smallexample and @smalllisp
    • @display
    • @format
    • @exdent: Undoing a Line's Indentation
    • @flushleft and @flushright
    • Drawing Cartouches Around Examples
  • Making Lists and Tables
    • Making an Itemized List
    • Making a Numbered or Lettered List
    • Making a Two-column Table
      • @ftable and @vtable
      • @itemx
    • Multi-column Tables
      • Multitable Column Widths
      • Multitable Rows
  • Creating Indices
    • Making Index Entries
    • Predefined Indices
    • Defining the Entries of an Index
    • Combining Indices
      • @syncodeindex
      • @synindex
    • Defining New Indices
  • Special Insertions
    • Inserting @ and Braces
      • Inserting `@' with @@
      • Inserting `{' and `}'with @{ and @}
    • Inserting Space
      • Not Ending a Sentence
      • Ending a Sentence
      • Multiple Spaces
      • @dmn{dimension}: Format a Dimension
    • Inserting Accents
    • Inserting Ellipsis, Dots, and Bullets
      • @dots{}
      • @bullet{}
    • Inserting TeX and the Copyright Symbol
      • @TeX{}
      • @copyright{}
    • @pounds{}
    • @minus{}: Inserting a Minus Sign
    • @math: Inserting Mathematical Expressions
  • Glyphs for Examples
    • =>: Indicating Evaluation
    • ==>: Indicating an Expansion
    • -|: Indicating Printed Output
    • error-->: Indicating an Error Message
    • ==: Indicating Equivalence
    • Indicating Point in a Buffer
  • Making and Preventing Breaks
    • @*: Generate Line Breaks
    • @- and @hyphenation: Helping TeX hyphenate
    • @w{text}: Prevent Line Breaks
    • @sp n: Insert Blank Lines
    • @page: Start a New Page
    • @group: Prevent Page Breaks
    • @need mils: Prevent Page Breaks
  • Definition Commands
    • The Template for a Definition
    • Optional and Repeated Arguments
    • Two or More `First' Lines
    • The Definition Commands
      • Functions and Similar Entities
      • Variables and Similar Entities
      • Functions in Typed Languages
      • Variables in Typed Languages
      • Object-Oriented Programming
      • Data Types
    • Conventions for Writing Definitions
    • A Sample Function Definition
  • Footnotes
    • Footnote Commands
    • Footnote Styles
  • Conditionally Visible Text
    • Using Ordinary TeX Commands
    • @set, @clear, and @value
      • @ifset and @ifclear
      • @value
      • @value Example
  • Macros: Defining New Texinfo Commands
    • Defining Macros
    • Invoking Macros
  • Format and Print Hardcopy
    • Format using tex and texindex
    • Format using texi2dvi
    • Shell Print Using lpr -d
    • From an Emacs Shell ...
    • Formatting and Printing in Texinfo Mode
    • Using the Local Variables List
    • TeX Formatting Requirements Summary
    • Preparing to Use TeX
    • Overfull "hboxes"
    • Printing "Small" Books
    • Printing on A4 Paper
    • Cropmarks and Magnification
  • Creating an Info File
    • Running makeinfo from a Shell
    • Options for makeinfo
    • Pointer Validation
    • Running makeinfo inside Emacs
    • The texinfo-format... Commands
    • Batch Formatting
    • Tag Files and Split Files
  • Installing an Info File
    • Listing a New Info File
    • Info Files in Other Directories
    • Installing Info Directory Files
    • Invoking install-info
  • @-Command List
  • Tips and Hints
  • A Sample Texinfo File
  • Sample Permissions
    • `ifinfo' Copying Permissions
    • Titlepage Copying Permissions
  • Include Files
    • How to Use Include Files
    • texinfo-multiple-files-update
    • Include File Requirements
    • Sample File with @include
    • Evolution of Include Files
  • Page Headings
    • Standard Heading Formats
    • Specifying the Type of Heading
    • How to Make Your Own Headings
  • Formatting Mistakes
    • Catching Errors with Info Formatting
    • Catching Errors with TeX Formatting
    • Using texinfo-show-structure
    • Using occur
    • Finding Badly Referenced Nodes
      • Running Info-validate
      • Creating an Unsplit File
      • Tagifying a File
      • Splitting a File Manually
  • Refilling Paragraphs
  • @-Command Syntax
  • How to Obtain TeX
  • Second Edition Features
    • New Texinfo Mode Commands
    • New Texinfo @-Commands
  • Command and Variable Index
  • Concept Index

index (arbitrarily chosen to be the concept index).

@dircategory Texinfo documentation system @direntry * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. Updating info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.

@shorttitlepage Texinfo

Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996 Free Software Foundation, Inc.

This is the second edition of the Texinfo documentation,
and is consistent with version 2 of `texinfo.tex'.

Published by the Free Software Foundation
59 Temple Place Suite 330,
Boston, MA 02111-1307 USA
Printed copies are available for $15 each.
ISBN 1-882114-64-7

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

Cover art by Etienne Suvasa.

Texinfo Copying Conditions

The programs currently being distributed that relate to Texinfo include portions of GNU Emacs, plus other separate programs (including makeinfo, info, texindex, and `texinfo.tex'). These programs are free; this means that everyone is free to use them and free to redistribute them on a free basis. The Texinfo-related programs are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of these programs that they might get from you.

Specifically, we want to make sure that you have the right to give away copies of the programs that relate to Texinfo, that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the Texinfo related programs, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to Texinfo. If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.

The precise conditions of the licenses for the programs currently being distributed that relate to Texinfo are found in the General Public Licenses that accompany them.

Overview of Texinfo

Texinfo (1) is a documentation system that uses a single source file to produce both on-line information and printed output. This means that instead of writing two different documents, one for the on-line help or other on-line information and the other for a typeset manual or other printed work, you need write only one document. When the work is revised, you need revise only one document. (You can read the on-line information, known as an Info file, with an Info documentation-reading program.)

Using Texinfo, you can create a printed document with the normal features of a book, including chapters, sections, cross references, and indices. From the same Texinfo source file, you can create a menu-driven, on-line Info file with nodes, menus, cross references, and indices. You can, if you wish, make the chapters and sections of the printed document correspond to the nodes of the on-line information; and you use the same cross references and indices for both the Info file and the printed work. The GNU Emacs Manual is a good example of a Texinfo file, as is this manual.

To make a printed document, you process a Texinfo source file with the TeX typesetting program. This creates a DVI file that you can typeset and print as a book or report. (Note that the Texinfo language is completely different from TeX's usual language, plain TeX.) If you do not have TeX, but do have troff or nroff, you can use the texi2roff program instead.

To make an Info file, you process a Texinfo source file with the makeinfo utility or Emacs's texinfo-format-buffer command; this creates an Info file that you can install on-line.

TeX and texi2roff work with many types of printer; similarly, Info works with almost every type of computer terminal. This power makes Texinfo a general purpose system, but brings with it a constraint, which is that a Texinfo file may contain only the customary "typewriter" characters (letters, numbers, spaces, and punctuation marks) but no special graphics.

A Texinfo file is a plain ASCII file containing text and @-commands (words preceded by an `@') that tell the typesetting and formatting programs what to do. You may edit a Texinfo file with any text editor; but it is especially convenient to use GNU Emacs since that editor has a special mode, called Texinfo mode, that provides various Texinfo-related features. (See section Using Texinfo Mode.)

Before writing a Texinfo source file, you should become familiar with the Info documentation reading program and learn about nodes, menus, cross references, and the rest. (See Info file `info', node `Top', for more information.)

You can use Texinfo to create both on-line help and printed manuals; moreover, Texinfo is freely redistributable. For these reasons, Texinfo is the format in which documentation for GNU utilities and libraries is written.

Info files

An Info file is a Texinfo file formatted so that the Info documentation reading program can operate on it. (makeinfo and texinfo-format-buffer are two commands that convert a Texinfo file into an Info file.)

Info files are divided into pieces called nodes, each of which contains the discussion of one topic. Each node has a name, and contains both text for the user to read and pointers to other nodes, which are identified by their names. The Info program displays one node at a time, and provides commands with which the user can move to other related nodes.

Each node of an Info file may have any number of child nodes that describe subtopics of the node's topic. The names of child nodes are listed in a menu within the parent node; this allows you to use certain Info commands to move to one of the child nodes. Generally, an Info file is organized like a book. If a node is at the logical level of a chapter, its child nodes are at the level of sections; likewise, the child nodes of sections are at the level of subsections.

All the children of any one parent are linked together in a bidirectional chain of `Next' and `Previous' pointers. The `Next' pointer provides a link to the next section, and the `Previous' pointer provides a link to the previous section. This means that all the nodes that are at the level of sections within a chapter are linked together. Normally the order in this chain is the same as the order of the children in the parent's menu. Each child node records the parent node name as its `Up' pointer. The last child has no `Next' pointer, and the first child has the parent both as its `Previous' and as its `Up' pointer.(2)

The book-like structuring of an Info file into nodes that correspond to chapters, sections, and the like is a matter of convention, not a requirement. The `Up', `Previous', and `Next' pointers of a node can point to any other nodes, and a menu can contain any other nodes. Thus, the node structure can be any directed graph. But it is usually more comprehensible to follow a structure that corresponds to the structure of chapters and sections in a printed book or report.

In addition to menus and to `Next', `Previous', and `Up' pointers, Info provides pointers of another kind, called references, that can be sprinkled throughout the text. This is usually the best way to represent links that do not fit a hierarchical structure.

Usually, you will design a document so that its nodes match the structure of chapters and sections in the printed output. But there are times when this is not right for the material being discussed. Therefore, Texinfo uses separate commands to specify the node structure for the Info file and the section structure for the printed output.

Generally, you enter an Info file through a node that by convention is called `Top'. This node normally contains just a brief summary of the file's purpose, and a large menu through which the rest of the file is reached. From this node, you can either traverse the file systematically by going from node to node, or you can go to a specific node listed in the main menu, or you can search the index menus and then go directly to the node that has the information you want.

If you want to read through an Info file in sequence, as if it were a printed manual, you can get the whole file with the advanced Info command g* RET. (See Info file `info', node `Expert'.)

The `dir' file in the `info' directory serves as the departure point for the whole Info system. From it, you can reach the `Top' nodes of each of the documents in a complete Info system.

Printed Books

A Texinfo file can be formatted and typeset as a printed book or manual. To do this, you need TeX, a powerful, sophisticated typesetting program written by Donald Knuth.(3)

A Texinfo-based book is similar to any other typeset, printed work: it can have a title page, copyright page, table of contents, and preface, as well as chapters, numbered or unnumbered sections and subsections, page headers, cross references, footnotes, and indices.

You can use Texinfo to write a book without ever having the intention of converting it into on-line information. You can use Texinfo for writing a printed novel, and even to write a printed memo, although this latter application is not recommended since electronic mail is so much easier.

TeX is a general purpose typesetting program. Texinfo provides a file called `texinfo.tex' that contains information (definitions or macros) that TeX uses when it typesets a Texinfo file. (`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX commands, which TeX can then process to create the typeset document.) `texinfo.tex' contains the specifications for printing a document.

Most often, documents are printed on 8.5 inch by 11 inch pages (216mm by 280mm; this is the default size), but you can also print for 7 inch by 9.25 inch pages (178mm by 235mm; the @smallbook size) or on European A4 size paper (@afourpaper). (See section Printing "Small" Books. Also, see section Printing on A4 Paper.)

By changing the parameters in `texinfo.tex', you can change the size of the printed document. In addition, you can change the style in which the printed document is formatted; for example, you can change the sizes and fonts used, the amount of indentation for each paragraph, the degree to which words are hyphenated, and the like. By changing the specifications, you can make a book look dignified, old and serious, or light-hearted, young and cheery.

TeX is freely distributable. It is written in a dialect of Pascal called WEB and can be compiled either in Pascal or (by using a conversion program that comes with the TeX distribution) in C. (See section `TeX Mode' in The GNU Emacs Manual, for information about TeX.)

TeX is very powerful and has a great many features. Because a Texinfo file must be able to present information both on a character-only terminal in Info form and in a typeset book, the formatting commands that Texinfo supports are necessarily limited.

See section How to Obtain TeX.

@-commands

In a Texinfo file, the commands that tell TeX how to typeset the printed manual and tell makeinfo and texinfo-format-buffer how to create an Info file are preceded by `@'; they are called @-commands. For example, @node is the command to indicate a node and @chapter is the command to indicate the start of a chapter.

Please note: All the @-commands, with the exception of the @TeX{} command, must be written entirely in lower case.

The Texinfo @-commands are a strictly limited set of constructs. The strict limits make it possible for Texinfo files to be understood both by TeX and by the code that converts them into Info files. You can display Info files on any terminal that displays alphabetic and numeric characters. Similarly, you can print the output generated by TeX on a wide variety of printers.

Depending on what they do or what arguments(4) they take, you need to write @-commands on lines of their own or as part of sentences:

  • Write a command such as @noindent at the beginning of a line as the only text on the line. (@noindent prevents the beginning of the next line from being indented as the beginning of a paragraph.)
  • Write a command such as @chapter at the beginning of a line followed by the command's arguments, in this case the chapter title, on the rest of the line. (@chapter creates chapter titles.)
  • Write a command such as @dots{} wherever you wish but usually within a sentence. (@dots{} creates dots ...)
  • Write a command such as @code{sample-code} wherever you wish (but usually within a sentence) with its argument, sample-code in this example, between the braces. (@code marks text as being code.)
  • Write a command such as @example at the beginning of a line of its own; write the body-text on following lines; and write the matching @end command, @end example in this case, at the beginning of a line of its own after the body-text. (@example ... @end example indents and typesets body-text as an example.)

As a general rule, a command requires braces if it mingles among other text; but it does not need braces if it starts a line of its own. The non-alphabetic commands, such as @:, are exceptions to the rule; they do not need braces.

As you gain experience with Texinfo, you will rapidly learn how to write the different commands: the different ways to write commands make it easier to write and read Texinfo files than if all commands followed exactly the same syntax. (For details about @-command syntax, see section @-Command Syntax.)

General Syntactic Conventions

All printable ASCII characters except `@', `{' and `}' can appear in a Texinfo file and stand for themselves. `@' is the escape character which introduces commands. `{' and `}' should be used only to surround arguments to certain commands. To put one of these special characters into the document, put an `@' character in front of it, like this: `@@', `@{', and `@}'.

It is customary in TeX to use doubled single-quote characters to begin and end quotations: @tt{ " } and @w{@tt{ " }}. This convention should be followed in Texinfo files. TeX converts doubled single-quote characters to left- and right-hand doubled quotation marks, "like this", and Info converts doubled single-quote characters to ASCII double-quotes: @tt{ " } and @tt{ " } to @w{@tt{ " }}.

Use three hyphens in a row, `---', for a dash--like this. In TeX, a single or even a double hyphen produces a printed dash that is shorter than the usual typeset dash. Info reduces three hyphens to two for display on the screen.

To prevent a paragraph from being indented in the printed manual, put the command @noindent on a line by itself before the paragraph.

If you mark off a region of the Texinfo file with the @iftex and @end iftex commands, that region will appear only in the printed copy; in that region, you can use certain commands borrowed from plain TeX that you cannot use in Info. Likewise, if you mark off a region with the @ifinfo and @end ifinfo commands, that region will appear only in the Info file; in that region, you can use Info commands that you cannot use in TeX. Similarly for @ifhtml and @end ifhtml. See section Conditionally Visible Text.

Caution: Do not use tabs in a Texinfo file! TeX uses variable-width fonts, which means that it cannot predefine a tab to work in all circumstances. Consequently, TeX treats tabs like single spaces, and that is not what they look like.

To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple spaces when you press the TAB key.

Also, you can run untabify in Emacs to convert tabs in a region to multiple spaces.

Comments

You can write comments in a Texinfo file that will not appear in either the Info file or the printed manual by using the @comment command (which may be abbreviated to @c). Such comments are for the person who reads the Texinfo file. All the text on a line that follows either @comment or @c is a comment; the rest of the line does not appear in either the Info file or the printed manual. (Often, you can write the @comment or @c in the middle of a line, and only the text that follows after the @comment or @c command does not appear; but some commands, such as @settitle and @setfilename, work on a whole line. You cannot use @comment or @c in a line beginning with such a command.)

You can write long stretches of text that will not appear in either the Info file or the printed manual by using the @ignore and @end ignore commands. Write each of these commands on a line of its own, starting each command at the beginning of the line. Text between these two commands does not appear in the processed output. You can use @ignore and @end ignore for writing comments. Often, @ignore and @end ignore is used to enclose a part of the copying permissions that applies to the Texinfo source file of a document, but not to the Info or printed version of the document.

What a Texinfo File Must Have

By convention, the names of Texinfo files end with one of the extensions `.texinfo', `.texi', or `.tex'. The longer extension is preferred since it describes more clearly to a human reader the nature of the file. The shorter extensions are for operating systems that cannot handle long file names.

In order to be made into a printed manual and an Info file, a Texinfo file must begin with lines like this:

\input texinfo
@setfilename info-file-name
@settitle name-of-manual

The contents of the file follow this beginning, and then you must end a Texinfo file with a line like this:

@bye

The `\input texinfo' line tells TeX to use the `texinfo.tex' file, which tells TeX how to translate the Texinfo @-commands into TeX typesetting commands. (Note the use of the backslash, `\'; this is correct for TeX.) The `@setfilename' line provides a name for the Info file and tells TeX to open auxiliary files. The `@settitle' line specifies a title for the page headers (or footers) of the printed manual.

The @bye line at the end of the file on a line of its own tells the formatters that the file is ended and to stop formatting.

Usually, you will not use quite such a spare format, but will include mode setting and start-of-header and end-of-header lines at the beginning of a Texinfo file, like this:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename info-file-name
@settitle name-of-manual
@c %**end of header

In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo mode when you edit the file.

The @c lines which surround the `@setfilename' and `@settitle' lines are optional, but you need them in order to run TeX or Info on just part of the file. (See section Start of Header, for more information.)

Furthermore, you will usually provide a Texinfo file with a title page, indices, and the like. But the minimum, which can be useful for short documents, is just the three lines at the beginning and the one line at the end.

Six Parts of a Texinfo File

Generally, a Texinfo file contains more than the minimal beginning and end--it usually contains six parts:

1. Header
The Header names the file, tells TeX which definitions' file to use, and performs other "housekeeping" tasks.
2. Summary Description and Copyright
The Summary Description and Copyright segment describes the document and contains the copyright notice and copying permissions for the Info file. The segment must be enclosed between @ifinfo and @end ifinfo commands so that the formatters place it only in the Info file.
3. Title and Copyright
The Title and Copyright segment contains the title and copyright pages and copying permissions for the printed manual. The segment must be enclosed between @titlepage and @end titlepage commands. The title and copyright page appear only in the printed manual.
4. `Top' Node and Master Menu
The Master Menu contains a complete menu of all the nodes in the whole Info file. It appears only in the Info file, in the `Top' node.
5. Body
The Body of the document may be structured like a traditional book or encyclopedia or it may be free form.
6. End
The End contains commands for printing indices and generating the table of contents, and the @bye command on a line of its own.

A Short Sample Texinfo File

Here is a complete but very short Texinfo file, in 6 parts. The first three parts of the file, from `\input texinfo' through to `@end titlepage', look more intimidating than they are. Most of the material is standard boilerplate; when you write a manual, simply insert the names for your own manual in this segment. (See section Beginning a Texinfo File.)

In the following, the sample text is indented; comments on it are not. The complete file, without any comments, is shown in section A Sample Texinfo File.

Part 1: Header

The header does not appear in either the Info file or the
printed output. It sets various parameters, including the
name of the Info file and the title used in the header.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header

@setchapternewpage odd

Part 2: Summary Description and Copyright

The summary description and copyright segment does not
appear in the printed document.

@ifinfo
This is a short example of a complete Texinfo file.

Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end ifinfo

Part 3: Titlepage and Copyright

The titlepage segment does not appear in the Info file.

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

Part 4: `Top' Node and Master Menu

The `Top' node contains the master menu for the Info file.
Since a printed manual uses a table of contents rather than
a menu, the master menu appears only in the Info file.

@node    Top,       First Chapter, (dir),    (dir)
@comment node-name, next,          previous, up

@menu
* First Chapter::    The first chapter is the
                     only chapter in this sample.
* Concept Index::    This index has two entries.
@end menu

Part 5: The Body of the Document

The body segment contains all the text of the document, but not the indices or table of contents. This example illustrates a node and a chapter containing an enumerated list.

@node    First Chapter, Concept Index, Top,      Top
@comment node-name,     next,          previous, up
@chapter First Chapter
@cindex Sample index entry

This is the contents of the first chapter.
@cindex Another sample index entry

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @code{makeinfo} and @code{texinfo-format-buffer}
commands transform a Texinfo file such as this into
an Info file; and @TeX{} typesets it for a printed
manual.

Part 6: The End of the Document

The end segment contains commands both for generating an index in a node and unnumbered chapter of its own and for generating the table of contents; and it contains the @bye command that marks the end of the document.

@node    Concept Index,    ,  First Chapter, Top
@comment node-name,    next,  previous,      up
@unnumbered Concept Index

@printindex cp

@contents
@bye

The Results

Here is what the contents of the first chapter of the sample look like:

This is the contents of the first chapter.

Here is a numbered list.

  1. This is the first item.
  2. This is the second item.

The makeinfo and texinfo-format-buffer commands transform a Texinfo file such as this into an Info file; and TeX typesets it for a printed manual.

Acknowledgements

Richard M. Stallman wrote Edition 1.0 of this manual. Robert J. Chassell revised and extended it, starting with Edition 1.1. Karl Berry made updates for the Texinfo 3.8 and subsequent releases, starting with Edition 2.22.

Our thanks go out to all who helped improve this work, particularly to Fran@,{c}ois Pinard and David D. Zuhn, who tirelessly recorded and reported mistakes and obscurities; our special thanks go to Melissa Weisshaus for her frequent and often tedious reviews of nearly similar editions. Our mistakes are our own.

Please send suggestions and corrections to:

Internet address:
    bug-texinfo@prep.ai.mit.edu

Please include the manual's edition number and update date in your messages.

Using Texinfo Mode

You may edit a Texinfo file with any text editor you choose. A Texinfo file is no different from any other ASCII file. However, GNU Emacs comes with a special mode, called Texinfo mode, that provides Emacs commands and tools to help ease your work.

This chapter describes features of GNU Emacs' Texinfo mode but not any features of the Texinfo formatting language. If you are reading this manual straight through from the beginning, you may want to skim through this chapter briefly and come back to it after reading succeeding chapters which describe the Texinfo formatting language in detail.

Texinfo mode provides special features for working with Texinfo files:

  • Insert frequently used @-commands.
  • Automatically create @node lines.
  • Show the structure of a Texinfo source file.
  • Automatically create or update the `Next',
    `Previous', and `Up' pointers of a node.
  • Automatically create or update menus.
  • Automatically create a master menu.
  • Format a part or all of a file for Info.
  • Typeset and print part or all of a file.

Perhaps the two most helpful features are those for inserting frequently used @-commands and for creating node pointers and menus.

The Usual GNU Emacs Editing Commands

In most cases, the usual Text mode commands work the same in Texinfo mode as they do in Text mode. Texinfo mode adds new editing commands and tools to GNU Emacs' general purpose editing features. The major difference concerns filling. In Texinfo mode, the paragraph separation variable and syntax table are redefined so that Texinfo commands that should be on lines of their own are not inadvertently included in paragraphs. Thus, the M-q (fill-paragraph) command will refill a paragraph but not mix an indexing command on a line adjacent to it into the paragraph.

In addition, Texinfo mode sets the page-delimiter variable to the value of texinfo-chapter-level-regexp; by default, this is a regular expression matching the commands for chapters and their equivalents, such as appendices. With this value for the page delimiter, you can jump from chapter title to chapter title with the C-x ] (forward-page) and C-x [ (backward-page) commands and narrow to a chapter with the C-x p (narrow-to-page) command. (See section `Pages' in The GNU Emacs Manual, for details about the page commands.)

You may name a Texinfo file however you wish, but the convention is to end a Texinfo file name with one of the three extensions `.texinfo', `.texi', or `.tex'. A longer extension is preferred, since it is explicit, but a shorter extension may be necessary for operating systems that limit the length of file names. GNU Emacs automatically enters Texinfo mode when you visit a file with a `.texinfo' or `.texi' extension. Also, Emacs switches to Texinfo mode when you visit a file that has `-*-texinfo-*-' in its first line. If ever you are in another mode and wish to switch to Texinfo mode, type M-x texinfo-mode.

Like all other Emacs features, you can customize or enhance Texinfo mode as you wish. In particular, the keybindings are very easy to change. The keybindings described here are the default or standard ones.

Inserting Frequently Used Commands

Texinfo mode provides commands to insert various frequently used @-commands into the buffer. You can use these commands to save keystrokes.

The insert commands are invoked by typing C-c twice and then the first letter of the @-command:

C-c C-c c
M-x texinfo-insert-@code
Insert @code{} and put the cursor between the braces.
C-c C-c d
M-x texinfo-insert-@dfn
Insert @dfn{} and put the cursor between the braces.
C-c C-c e
M-x texinfo-insert-@end
Insert @end and attempt to insert the correct following word, such as `example' or `table'. (This command does not handle nested lists correctly, but inserts the word appropriate to the immediately preceding list.)
C-c C-c i
M-x texinfo-insert-@item
Insert @item and put the cursor at the beginning of the next line.
C-c C-c k
M-x texinfo-insert-@kbd
Insert @kbd{} and put the cursor between the braces.
C-c C-c n
M-x texinfo-insert-@node
Insert @node and a comment line listing the sequence for the `Next', `Previous', and `Up' nodes. Leave point after the @node.
C-c C-c o
M-x texinfo-insert-@noindent
Insert @noindent and put the cursor at the beginning of the next line.
C-c C-c s
M-x texinfo-insert-@samp
Insert @samp{} and put the cursor between the braces.
C-c C-c t
M-x texinfo-insert-@table
Insert @table followed by a SPC and leave the cursor after the SPC.
C-c C-c v
M-x texinfo-insert-@var
Insert @var{} and put the cursor between the braces.
C-c C-c x
M-x texinfo-insert-@example
Insert @example and put the cursor at the beginning of the next line.
C-c C-c {
M-x texinfo-insert-braces
Insert {} and put the cursor between the braces.
C-c C-c }
C-c C-c ]
M-x up-list
Move from between a pair of braces forward past the closing brace. Typing C-c C-c ] is easier than typing C-c C-c }, which is, however, more mnemonic; hence the two keybindings. (Also, you can move out from between braces by typing C-f.)

To put a command such as @code{...} around an existing word, position the cursor in front of the word and type C-u 1 C-c C-c c. This makes it easy to edit existing plain text. The value of the prefix argument tells Emacs how many words following point to include between braces--1 for one word, 2 for two words, and so on. Use a negative argument to enclose the previous word or words. If you do not specify a prefix argument, Emacs inserts the @-command string and positions the cursor between the braces. This feature works only for those @-commands that operate on a word or words within one line, such as @kbd and @var.

This set of insert commands was created after analyzing the frequency with which different @-commands are used in the GNU Emacs Manual and the GDB Manual. If you wish to add your own insert commands, you can bind a keyboard macro to a key, use abbreviations, or extend the code in `texinfo.el'.

C-c C-c C-d (texinfo-start-menu-description) is an insert command that works differently from the other insert commands. It inserts a node's section or chapter title in the space for the description in a menu entry line. (A menu entry has three parts, the entry name, the node name, and the description. Only the node name is required, but a description helps explain what the node is about. See section The Parts of a Menu.)

To use texinfo-start-menu-description, position point in a menu entry line and type C-c C-c C-d. The command looks for and copies the title that goes with the node name, and inserts the title as a description; it positions point at beginning of the inserted text so you can edit it. The function does not insert the title if the menu entry line already contains a description.

This command is only an aid to writing descriptions; it does not do the whole job. You must edit the inserted text since a title tends to use the same words as a node name but a useful description uses different words.

Showing the Section Structure of a File

You can show the section structure of a Texinfo file by using the C-c C-s command (texinfo-show-structure). This command shows the section structure of a Texinfo file by listing the lines that begin with the @-commands for @chapter, @section, and the like. It constructs what amounts to a table of contents. These lines are displayed in another buffer called the `*Occur*' buffer. In that buffer, you can position the cursor over one of the lines and use the C-c C-c command (occur-mode-goto-occurrence), to jump to the corresponding spot in the Texinfo file.

C-c C-s
M-x texinfo-show-structure
Show the @chapter, @section, and such lines of a Texinfo file.
C-c C-c
M-x occur-mode-goto-occurrence
Go to the line in the Texinfo file corresponding to the line under the cursor in the `*Occur*' buffer.

If you call texinfo-show-structure with a prefix argument by typing C-u C-c C-s, it will list not only those lines with the @-commands for @chapter, @section, and the like, but also the @node lines. (This is how the texinfo-show-structure command worked without an argument in the first version of Texinfo. It was changed because @node lines clutter up the `*Occur*' buffer and are usually not needed.) You can use texinfo-show-structure with a prefix argument to check whether the `Next', `Previous', and `Up' pointers of an @node line are correct.

Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark off the region of the buffer that you are interested in by using the C-x n n (narrow-to-region) command and texinfo-show-structure will work on only that region. To see the whole buffer again, use C-x n w (widen). (See section `Narrowing' in The GNU Emacs Manual, for more information about the narrowing commands.)

In addition to providing the texinfo-show-structure command, Texinfo mode sets the value of the page delimiter variable to match the chapter-level @-commands. This enables you to use the C-x ] (forward-page) and C-x [ (backward-page) commands to move forward and backward by chapter, and to use the C-x p (narrow-to-page) command to narrow to a chapter. See section `Pages' in The GNU Emacs Manual, for more information about the page commands.

Updating Nodes and Menus

Texinfo mode provides commands for automatically creating or updating menus and node pointers. The commands are called "update" commands because their most frequent use is for updating a Texinfo file after you have worked on it; but you can use them to insert the `Next', `Previous', and `Up' pointers into an @node line that has none and to create menus in a file that has none.

If you do not use the updating commands, you need to write menus and node pointers by hand, which is a tedious task.

You can use the updating commands

  • to insert or update the `Next', `Previous', and `Up' pointers of a node,
  • to insert or update the menu for a section, and
  • to create a master menu for a Texinfo source file.

You can also use the commands to update all the nodes and menus in a region or in a whole Texinfo file.

The updating commands work only with conventional Texinfo files, which are structured hierarchically like books. In such files, a structuring command line must follow closely after each @node line, except for the `Top' @node line. (A structuring command line is a line beginning with @chapter, @section, or other similar command.)

You can write the structuring command line on the line that follows immediately after an @node line or else on the line that follows after a single @comment line or a single @ifinfo line. You cannot interpose more than one line between the @node line and the structuring command line; and you may interpose only an @comment line or an @ifinfo line.

Commands which work on a whole buffer require that the `Top' node be followed by a node with an @chapter or equivalent-level command. Note that the menu updating commands will not create a main or master menu for a Texinfo file that has only @chapter-level nodes! The menu updating commands only create menus within nodes for lower level nodes. To create a menu of chapters, you must provide a `Top' node.

The menu updating commands remove menu entries that refer to other Info files since they do not refer to nodes within the current buffer. This is a deficiency. Rather than use menu entries, you can use cross references to refer to other Info files. None of the updating commands affect cross references.

Texinfo mode has five updating commands that are used most often: two are for updating the node pointers or menu of a single node (or a region); two are for updating every node pointer and menu in a file; and one, the texinfo-master-menu command, is for creating a master menu for a complete file, and optionally, for updating every node and menu in the whole Texinfo file.

The texinfo-master-menu command is the primary command:

C-c C-u m
M-x texinfo-master-menu
Create or update a master menu that includes all the other menus (incorporating the descriptions from pre-existing menus, if any). With an argument (prefix argument, C-u, if interactive), first create or update all the nodes and all the regular menus in the buffer before constructing the master menu. (See section The `Top' Node and Master Menu, for more about a master menu.) For texinfo-master-menu to work, the Texinfo file must have a `Top' node and at least one subsequent node. After extensively editing a Texinfo file, you can type the following:
C-u M-x texinfo-master-menu
or
C-u C-c C-u m
This updates all the nodes and menus completely and all at once.

The other major updating commands do smaller jobs and are designed for the person who updates nodes and menus as he or she writes a Texinfo file.

The commands are:

C-c C-u C-n
M-x texinfo-update-node
Insert the `Next', `Previous', and `Up' pointers for the node that point is within (i.e., for the @node line preceding point). If the @node line has pre-existing `Next', `Previous', or `Up' pointers in it, the old pointers are removed and new ones inserted. With an argument (prefix argument, C-u, if interactive), this command updates all @node lines in the region (which is the text between point and mark).
C-c C-u C-m
M-x texinfo-make-menu
Create or update the menu in the node that point is within. With an argument (C-u as prefix argument, if interactive), the command makes or updates menus for the nodes which are either within or a part of the region. Whenever texinfo-make-menu updates an existing menu, the descriptions from that menu are incorporated into the new menu. This is done by copying descriptions from the existing menu to the entries in the new menu that have the same node names. If the node names are different, the descriptions are not copied to the new menu.
C-c C-u C-e
M-x texinfo-every-node-update
Insert or update the `Next', `Previous', and `Up' pointers for every node in the buffer.
C-c C-u C-a
M-x texinfo-all-menus-update
Create or update all the menus in the buffer. With an argument (C-u as prefix argument, if interactive), first insert or update all the node pointers before working on the menus. If a master menu exists, the texinfo-all-menus-update command updates it; but the command does not create a new master menu if none already exists. (Use the texinfo-master-menu command for that.) When working on a document that does not merit a master menu, you can type the following:
C-u C-c C-u C-a
or
C-u M-x texinfo-all-menus-update
This updates all the nodes and menus.

The texinfo-column-for-description variable specifies the column to which menu descriptions are indented. By default, the value is 32 although it is often useful to reduce it to as low as 24. You can set the variable with the M-x edit-options command (see section `Editing Variable Values' in The GNU Emacs Manual) or with the M-x set-variable command (see section `Examining and Setting Variables' in The GNU Emacs Manual).

Also, the texinfo-indent-menu-description command may be used to indent existing menu descriptions to a specified column. Finally, if you wish, you can use the texinfo-insert-node-lines command to insert missing @node lines into a file. (See section Other Updating Commands, for more information.)

Updating Requirements

To use the updating commands, you must organize the Texinfo file hierarchically with chapters, sections, subsections, and the like. When you construct the hierarchy of the manual, do not `jump down' more than one level at a time: you can follow the `Top' node with a chapter, but not with a section; you can follow a chapter with a section, but not with a subsection. However, you may `jump up' any number of levels at one time--for example, from a subsection to a chapter.

Each @node line, with the exception of the line for the `Top' node, must be followed by a line with a structuring command such as @chapter, @section, or @unnumberedsubsec.

Each @node line/structuring-command line combination must look either like this:

@node     Comments,  Minimum, Conventions, Overview
@comment  node-name, next,    previous,    up
@section Comments

or like this (without the @comment line):

@node Comments, Minimum, Conventions, Overview
@section Comments

In this example, `Comments' is the name of both the node and the section. The next node is called `Minimum' and the previous node is called `Conventions'. The `Comments' section is within the `Overview' node, which is specified by the `Up' pointer. (Instead of an @comment line, you can write an @ifinfo line.)

If a file has a `Top' node, it must be called `top' or `Top' and be the first node in the file.

The menu updating commands create a menu of sections within a chapter, a menu of subsections within a section, and so on. This means that you must have a `Top' node if you want a menu of chapters.

Incidentally, the makeinfo command will create an Info file for a hierarchically organized Texinfo file that lacks `Next', `Previous' and `Up' pointers. Thus, if you can be sure that your Texinfo file will be formatted with makeinfo, you have no need for the `update node' commands. (See section Creating an Info File, for more information about makeinfo.) However, both makeinfo and the texinfo-format-... commands require that you insert menus in the file.

Other Updating Commands

In addition to the five major updating commands, Texinfo mode possesses several less frequently used updating commands:

M-x texinfo-insert-node-lines
Insert @node lines before the @chapter, @section, and other sectioning commands wherever they are missing throughout a region in a Texinfo file. With an argument (C-u as prefix argument, if interactive), the texinfo-insert-node-lines command not only inserts @node lines but also inserts the chapter or section titles as the names of the corresponding nodes. In addition, it inserts the titles as node names in pre-existing @node lines that lack names. Since node names should be more concise than section or chapter titles, you must manually edit node names so inserted. For example, the following marks a whole buffer as a region and inserts @node lines and titles throughout:
C-x h C-u M-x texinfo-insert-node-lines
(Note that this command inserts titles as node names in @node lines; the texinfo-start-menu-description command (see section Inserting Frequently Used Commands) inserts titles as descriptions in menu entries, a different action. However, in both cases, you need to edit the inserted text.)
M-x texinfo-multiple-files-update
Update nodes and menus in a document built from several separate files. With C-u as a prefix argument, create and insert a master menu in the outer file. With a numeric prefix argument, such as C-u 2, first update all the menus and all the `Next', `Previous', and `Up' pointers of all the included files before creating and inserting a master menu in the outer file. The texinfo-multiple-files-update command is described in the appendix on @include files. See section texinfo-multiple-files-update.
M-x texinfo-indent-menu-description
Indent every description in the menu following point to the specified column. You can use this command to give yourself more space for descriptions. With an argument (C-u as prefix argument, if interactive), the texinfo-indent-menu-description command indents every description in every menu in the region. However, this command does not indent the second and subsequent lines of a multi-line description.
M-x texinfo-sequential-node-update
Insert the names of the nodes immediately following and preceding the current node as the `Next' or `Previous' pointers regardless of those nodes' hierarchical level. This means that the `Next' node of a subsection may well be the next chapter. Sequentially ordered nodes are useful for novels and other documents that you read through sequentially. (However, in Info, the g* RET command lets you look through the file sequentially, so sequentially ordered nodes are not strictly necessary.) With an argument (prefix argument, if interactive), the texinfo-sequential-node-update command sequentially updates all the nodes in the region.

Formatting for Info

Texinfo mode provides several commands for formatting part or all of a Texinfo file for Info. Often, when you are writing a document, you want to format only part of a file--that is, a region.

You can use either the texinfo-format-region or the makeinfo-region command to format a region:

C-c C-e C-r
M-x texinfo-format-region
C-c C-m C-r
M-x makeinfo-region
Format the current region for Info.

You can use either the texinfo-format-buffer or the makeinfo-buffer command to format a whole buffer:

C-c C-e C-b
M-x texinfo-format-buffer
C-c C-m C-b
M-x makeinfo-buffer
Format the current buffer for Info.

For example, after writing a Texinfo file, you can type the following:

C-u C-c C-u m
or
C-u M-x texinfo-master-menu

This updates all the nodes and menus. Then type the following to create an Info file:

C-c C-m C-b
or
M-x makeinfo-buffer

For TeX or the Info formatting commands to work, the file must include a line that has @setfilename in its header.

See section Creating an Info File, for details about Info formatting.

Formatting and Printing

Typesetting and printing a Texinfo file is a multi-step process in which you first create a file for printing (called a DVI file), and then print the file. Optionally, you may also create indices. To do this, you must run the texindex command after first running the tex typesetting command; and then you must run the tex command again. Or else run the texi2dvi command which automatically creates indices as needed.

Often, when you are writing a document, you want to typeset and print only part of a file to see what it will look like. You can use the texinfo-tex-region and related commands for this purpose. Use the texinfo-tex-buffer command to format all of a buffer.

C-c C-t C-b
M-x texinfo-tex-buffer
Run texi2dvi on the buffer. In addition to running TeX on the buffer, this command automatically creates or updates indices as needed.
C-c C-t C-r
M-x texinfo-tex-region
Run TeX on the region.
C-c C-t C-i
M-x texinfo-texindex
Run texindex to sort the indices of a Texinfo file formatted with texinfo-tex-region. The texinfo-tex-region command does not run texindex automatically; it only runs the tex typesetting command. You must run the texinfo-tex-region command a second time after sorting the raw index files with the texindex command. (Usually, you do not format an index when you format a region, only when you format a buffer. Now that the texi2dvi command exists, there is no little need for this command.)
C-c C-t C-p
M-x texinfo-tex-print
Print the file (or the part of the file) previously formatted with texinfo-tex-buffer or texinfo-tex-region.

For texinfo-tex-region or texinfo-tex-buffer to work, the file must start with a `\input texinfo' line and must include an @settitle line. The file must end with @bye on a line by itself. (When you use texinfo-tex-region, you must surround the @settitle line with start-of-header and end-of-header lines.)

See section Format and Print Hardcopy, for a description of the other TeX related commands, such as tex-show-print-queue.

Texinfo Mode Summary

In Texinfo mode, each set of commands has default keybindings that begin with the same keys. All the commands that are custom-created for Texinfo mode begin with C-c. The keys are somewhat mnemonic.

Insert Commands

The insert commands are invoked by typing C-c twice and then the first letter of the @-command to be inserted. (It might make more sense mnemonically to use C-c C-i, for `custom insert', but C-c C-c is quick to type.)

C-c C-c c       Insert `@code'.
C-c C-c d       Insert `@dfn'.
C-c C-c e       Insert `@end'.
C-c C-c i       Insert `@item'.
C-c C-c n       Insert `@node'.
C-c C-c s       Insert `@samp'.
C-c C-c v       Insert `@var'.
C-c C-c {       Insert braces.
C-c C-c ]
C-c C-c }       Move out of enclosing braces.

C-c C-c C-d     Insert a node's section title
                in the space for the description
                in a menu entry line.

Show Structure

The texinfo-show-structure command is often used within a narrowed region.

C-c C-s         List all the headings.

The Master Update Command

The texinfo-master-menu command creates a master menu; and can be used to update every node and menu in a file as well.

C-c C-u m
M-x texinfo-master-menu
                Create or update a master menu.

C-u C-c C-u m   With C-u as a prefix argument, first
                create or update all nodes and regular
                menus, and then create a master menu.

Update Pointers

The update pointer commands are invoked by typing C-c C-u and then either C-n for texinfo-update-node or C-e for texinfo-every-node-update.

C-c C-u C-n     Update a node.
C-c C-u C-e     Update every node in the buffer.

Update Menus

Invoke the update menu commands by typing C-c C-u and then either C-m for texinfo-make-menu or C-a for texinfo-all-menus-update. To update both nodes and menus at the same time, precede C-c C-u C-a with C-u.

C-c C-u C-m     Make or update a menu.

C-c C-u C-a     Make or update all
                menus in a buffer.

C-u C-c C-u C-a With C-u as a prefix argument,
                first create or update all nodes and
                then create or update all menus.

Format for Info

The Info formatting commands that are written in Emacs Lisp are invoked by typing C-c C-e and then either C-r for a region or C-b for the whole buffer.

The Info formatting commands that are written in C and based on the makeinfo program are invoked by typing C-c C-m and then either C-r for a region or C-b for the whole buffer.

Use the texinfo-format... commands:

C-c C-e C-r     Format the region.
C-c C-e C-b     Format the buffer.

Use makeinfo:

C-c C-m C-r     Format the region.
C-c C-m C-b     Format the buffer.
C-c C-m C-l     Recenter the makeinfo output buffer.
C-c C-m C-k     Kill the makeinfo formatting job.

Typeset and Print

The TeX typesetting and printing commands are invoked by typing C-c C-t and then another control command: C-r for texinfo-tex-region, C-b for texinfo-tex-buffer, and so on.

C-c C-t C-r     Run TeX on the region.
C-c C-t C-b     Run texi2dvi on the buffer.
C-c C-t C-i     Run texindex.
C-c C-t C-p     Print the DVI file.
C-c C-t C-q     Show the print queue.
C-c C-t C-d     Delete a job from the print queue.
C-c C-t C-k     Kill the current TeX formatting job.
C-c C-t C-x     Quit a currently stopped TeX formatting job.
C-c C-t C-l     Recenter the output buffer.

Other Updating Commands

The `other updating commands' do not have standard keybindings because they are rarely used.

M-x texinfo-insert-node-lines
                Insert missing @node lines in region.
                With C-u as a prefix argument,
                use section titles as node names.

M-x texinfo-multiple-files-update
                Update a multi-file document.
                With C-u 2 as a prefix argument,
                create or update all nodes and menus
                in all included files first.

M-x texinfo-indent-menu-description
                Indent descriptions.

M-x texinfo-sequential-node-update
                Insert node pointers in strict sequence.

Beginning a Texinfo File

Certain pieces of information must be provided at the beginning of a Texinfo file, such as the name of the file and the title of the document.

Generally, the beginning of a Texinfo file has four parts:

  1. The header, delimited by special comment lines, that includes the commands for naming the Texinfo file and telling TeX what definitions' file to use when processing the Texinfo file.
  2. A short statement of what the file is about, with a copyright notice and copying permissions. This is enclosed in @ifinfo and @end ifinfo commands so that the formatters place it only in the Info file.
  3. A title page and copyright page, with a copyright notice and copying permissions. This is enclosed between @titlepage and @end titlepage commands. The title and copyright page appear only in the printed manual.
  4. The `Top' node that contains a menu for the whole Info file. The contents of this node appear only in the Info file.

Also, optionally, you may include the copying conditions for a program and a warranty disclaimer. The copying section will be followed by an introduction or else by the first chapter of the manual.

Since the copyright notice and copying permissions for the Texinfo document (in contrast to the copying permissions for a program) are in parts that appear only in the Info file or only in the printed manual, this information must be given twice.

Sample Texinfo File Beginning

The following sample shows what is needed.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename name-of-info-file
@settitle name-of-manual
@setchapternewpage odd
@c %**end of header

@ifinfo
This file documents ...

Copyright year copyright-owner

Permission is granted to ...
@end ifinfo

@c  This title page illustrates only one of the
@c  two methods of forming a title page.

@titlepage
@title name-of-manual-when-printed
@subtitle subtitle-if-any
@subtitle second-subtitle
@author author

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} year copyright-owner

Published by ...

Permission is granted to ...
@end titlepage

@node Top, Overview, (dir), (dir)

@ifinfo
This document describes ...

This document applies to version ...
of the program named ...
@end ifinfo

@menu
* Copying::          Your rights and freedoms.
* First Chapter::    Getting started ...
* Second Chapter::              ...
  ...
  ...
@end menu

@node    First Chapter, Second Chapter, top,      top
@comment node-name,     next,           previous, up
@chapter First Chapter
@cindex Index entry for First Chapter

The Texinfo File Header

Texinfo files start with at least three lines that provide Info and TeX with necessary information. These are the \input texinfo line, the @settitle line, and the @setfilename line. If you want to run TeX on just a part of the Texinfo File, you must write the @settitle and @setfilename lines between start-of-header and end-of-header lines.

Thus, the beginning of a Texinfo file looks like this:

\input texinfo   @c -*-texinfo-*-
@setfilename sample.info
@settitle Sample Document

or else like this:

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header

The First Line of a Texinfo File

Every Texinfo file that is to be the top-level input to TeX must begin with a line that looks like this:

\input texinfo   @c -*-texinfo-*-

This line serves two functions:

  1. When the file is processed by TeX, the \input texinfo command tells TeX to load the macros needed for processing a Texinfo file. These are in a file called `texinfo.tex', which is usually located in the `/usr/lib/tex/macros' directory. TeX uses the backslash, `\', to mark the beginning of a command, just as Texinfo uses @. The `texinfo.tex' file causes the switch from `\' to `@'; before the switch occurs, TeX requires `\', which is why it appears at the beginning of the file.
  2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode specification tells Emacs to use Texinfo mode.

Start of Header

Write a start-of-header line on the second line of a Texinfo file. Follow the start-of-header line with @setfilename and @settitle lines and, optionally, with other command lines, such as @smallbook or @footnotestyle; and then by an end-of-header line (see section End of Header).

With these lines, you can format part of a Texinfo file for Info or typeset part for printing.

A start-of-header line looks like this:

@c %**start of header

The odd string of characters, `%**', is to ensure that no other comment is accidentally taken for a start-of-header line.

@setfilename

In order to serve as the primary input file for either makeinfo or TeX, a Texinfo file must contain a line that looks like this:

@setfilename info-file-name

Write the @setfilename command at the beginning of a line and follow it on the same line by the Info file name. Do not write anything else on the line; anything on the line after the command is considered part of the file name, including a comment.

The @setfilename line specifies the name of the Info file to be generated. This name should be different from the name of the Texinfo file. There are two conventions for choosing the name: you can either remove the `.tex' extension from the input file name, or replace it with the `.info' extension.

Some operating systems cannot handle long file names. You can run into a problem even when the file name you specify is itself short enough. This occurs because the Info formatters split a long Info file into short indirect subfiles, and name them by appending `-1', `-2', ..., `-10', `-11', and so on, to the original file name. (See section Tag Files and Split Files.) The subfile name `texinfo.info-10', for example, is too long for some systems; so the Info file name for this document is `texinfo' rather than `texinfo.info'.

The Info formatting commands ignore everything written before the @setfilename line, which is why the very first line of the file (the \input line) does not need to be commented out.

The @setfilename line produces no output when you typeset a printed manual, but is does an essential job: it opens the index, cross-reference, and other auxiliary files used by Texinfo.

@settitle

In order to be made into a printed manual, a Texinfo file must contain a line that looks like this:

@settitle title

Write the @settitle command at the beginning of a line and follow it on the same line by the title. This tells TeX the title to use in a header or footer. Do not write anything else on the line; anything on the line after the command is considered part of the title, including a comment.

Conventionally, when TeX formats a Texinfo file for double-sided output, the title is printed in the left-hand (even-numbered) page headings and the current chapter title is printed in the right-hand (odd-numbered) page headings. (TeX learns the title of each chapter from each @chapter command.) Page footers are not printed.

Even if you are printing in a single-sided style, TeX looks for an @settitle command line, in case you include the manual title in the heading.

The @settitle command should precede everything that generates actual output in TeX.

Although the title in the @settitle command is usually the same as the title on the title page, it does not affect the title as it appears on the title page. Thus, the two do not need not match exactly; and the title in the @settitle command can be a shortened or expanded version of the title as it appears on the title page. (See section @titlepage.)

TeX prints page headings only for that text that comes after the @end titlepage command in the Texinfo file, or that comes after an @headings command that turns on headings. (See section The @headings Command, for more information.)

You may, if you wish, create your own, customized headings and footings. See section Page Headings, for a detailed discussion of this process.

@setchapternewpage

In a book or a manual, text is usually printed on both sides of the paper, chapters start on right-hand pages, and right-hand pages have odd numbers. But in short reports, text often is printed only on one side of the paper. Also in short reports, chapters sometimes do not start on new pages, but are printed on the same page as the end of the preceding chapter, after a small amount of vertical whitespace.

You can use the @setchapternewpage command with various arguments to specify how TeX should start chapters and whether it should typeset pages for printing on one or both sides of the paper (single-sided or double-sided printing).

Write the @setchapternewpage command at the beginning of a line followed by its argument.

For example, you would write the following to cause each chapter to start on a fresh odd-numbered page:

@setchapternewpage odd

You can specify one of three alternatives with the @setchapternewpage command:

@setchapternewpage off
Cause TeX to typeset a new chapter on the same page as the last chapter, after skipping some vertical whitespace. Also, cause TeX to format page headers for single-sided printing. (You can override the headers format with the @headings double command; see section The @headings Command.)
@setchapternewpage on
Cause TeX to start new chapters on new pages and to typeset page headers for single-sided printing. This is the form most often used for short reports. This alternative is the default.
@setchapternewpage odd
Cause TeX to start new chapters on new, odd-numbered pages (right-handed pages) and to typeset for double-sided printing. This is the form most often used for books and manuals.

Texinfo does not have an @setchapternewpage even command.

(You can countermand or modify an @setchapternewpage command with an @headings command. See section The @headings Command.)

At the beginning of a manual or book, pages are not numbered--for example, the title and copyright pages of a book are not numbered. By convention, table of contents pages are numbered with roman numerals and not in sequence with the rest of the document.

Since an Info file does not have pages, the @setchapternewpage command has no effect on it.

Usually, you do not write an @setchapternewpage command for single-sided printing, but accept the default which is to typeset for single-sided printing and to start new chapters on new pages. Usually, you write an @setchapternewpage odd command for double-sided printing.

Paragraph Indenting

The Info formatting commands may insert spaces at the beginning of the first line of each paragraph, thereby indenting that paragraph. You can use the @paragraphindent command to specify the indentation. Write an @paragraphindent command at the beginning of a line followed by either `asis' or a number. The template is:

@paragraphindent indent

The Info formatting commands indent according to the value of indent:

  • If the value of indent is `asis', the Info formatting commands do not change the existing indentation.
  • If the value of indent is 0, the Info formatting commands delete existing indentation.
  • If the value of indent is greater than 0, the Info formatting commands indent the paragraph by that number of spaces.

The default value of indent is `asis'.

Write the @paragraphindent command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you write the command between the start-of-header and end-of-header lines, the region formatting commands indent paragraphs as specified.)

A peculiarity of the texinfo-format-buffer and texinfo-format-region commands is that they do not indent (nor fill) paragraphs that contain @w or @* commands. See section Refilling Paragraphs, for a detailed description of what goes on.

End of Header

Follow the header lines with an end-of-header line. An end-of-header line looks like this:

@c %**end of header

If you include the @setchapternewpage command between the start-of-header and end-of-header lines, TeX will typeset a region as that command specifies. Similarly, if you include an @smallbook command between the start-of-header and end-of-header lines, TeX will typeset a region in the "small" book format.

See section Start of Header.

Summary and Copying Permissions for Info

The title page and the copyright page appear only in the printed copy of the manual; therefore, the same information must be inserted in a section that appears only in the Info file. This section usually contains a brief description of the contents of the Info file, a copyright notice, and copying permissions.

The copyright notice should read:

Copyright year copyright-owner

and be put on a line by itself.

Standard text for the copyright permissions is contained in an appendix to this manual; see section `ifinfo' Copying Permissions, for the complete text.

The permissions text appears in an Info file before the first node. This mean that a reader does not see this text when reading the file using Info, except when using the advanced Info command g *.

The Title and Copyright Pages

A manual's name and author are usually printed on a title page. Sometimes copyright information is printed on the title page as well; more often, copyright information is printed on the back of the title page.

The title and copyright pages appear in the printed manual, but not in the Info file. Because of this, it is possible to use several slightly obscure TeX typesetting commands that cannot be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual.

See section Titlepage Copying Permissions, for the standard text for the copyright permissions.

@titlepage

Start the material for the title page and following copyright page with @titlepage on a line by itself and end it with @end titlepage on a line by itself.

The @end titlepage command starts a new page and turns on page numbering. (See section Page Headings, for details about how to generate page headings.) All the material that you want to appear on unnumbered pages should be put between the @titlepage and @end titlepage commands. By using the @page command you can force a page break within the region delineated by the @titlepage and @end titlepage commands and thereby create more than one unnumbered page. This is how the copyright page is produced. (The @titlepage command might perhaps have been better named the @titleandadditionalpages command, but that would have been rather long!)

When you write a manual about a computer program, you should write the version of the program to which the manual applies on the title page. If the manual changes more frequently than the program or is independent of it, you should also include an edition number(5) for the manual. This helps readers keep track of which manual is for which version of the program. (The `Top' node should also contain this information; see section @top.)

Texinfo provides two main methods for creating a title page. One method uses the @titlefont, @sp, and @center commands to generate a title page in which the words on the page are centered.

The second method uses the @title, @subtitle, and @author commands to create a title page with black rules under the title and author lines and the subtitle text set flush to the right hand side of the page. With this method, you do not specify any of the actual formatting of the title page. You specify the text you want, and Texinfo does the formatting. You may use either method.

For extremely simple applications, Texinfo also provides a command @shorttitlepage which takes a single argument as the title. The argument is typeset on a page by itself and followed by a blank page.

@titlefont, @center, and @sp

You can use the @titlefont, @sp, and @center commands to create a title page for a printed document. (This is the first of the two methods for creating a title page in Texinfo.)

Use the @titlefont command to select a large font suitable for the title itself.

For example:

@titlefont{Texinfo}

Use the @center command at the beginning of a line to center the remaining text on that line. Thus,

@center @titlefont{Texinfo}

centers the title, which in this example is "Texinfo" printed in the title font.

Use the @sp command to insert vertical space. For example:

@sp 2

This inserts two blank lines on the printed page. (See section @sp n: Insert Blank Lines, for more information about the @sp command.)

A template for this method looks like this:

@titlepage
@sp 10
@center @titlefont{name-of-manual-when-printed}
@sp 2
@center subtitle-if-any
@sp 2
@center author
...
@end titlepage

The spacing of the example fits an 8 1/2 by 11 inch manual.

@title, @subtitle, and @author

You can use the @title, @subtitle, and @author commands to create a title page in which the vertical and horizontal spacing is done for you automatically. This contrasts with the method described in the previous section, in which the @sp command is needed to adjust vertical spacing.

Write the @title, @subtitle, or @author commands at the beginning of a line followed by the title, subtitle, or author.

The @title command produces a line in which the title is set flush to the left-hand side of the page in a larger than normal font. The title is underlined with a black rule.

The @subtitle command sets subtitles in a normal-sized font flush to the right-hand side of the page.

The @author command sets the names of the author or authors in a middle-sized font flush to the left-hand side of the page on a line near the bottom of the title page. The names are underlined with a black rule that is thinner than the rule that underlines the title. (The black rule only occurs if the @author command line is followed by an @page command line.)

There are two ways to use the @author command: you can write the name or names on the remaining part of the line that starts with an @author command:

@author by Jane Smith and John Doe

or you can write the names one above each other by using two (or more) @author commands:

@author Jane Smith
@author John Doe

(Only the bottom name is underlined with a black rule.)

A template for this method looks like this:

@titlepage
@title name-of-manual-when-printed
@subtitle subtitle-if-any
@subtitle second-subtitle
@author author
@page
...
@end titlepage

Copyright Page and Permissions

By international treaty, the copyright notice for a book should be either on the title page or on the back of the title page. The copyright notice should include the year followed by the name of the organization or person who owns the copyright.

When the copyright notice is on the back of the title page, that page is customarily not numbered. Therefore, in Texinfo, the information on the copyright page should be within @titlepage and @end titlepage commands.

Use the @page command to cause a page break. To push the copyright notice and the other text on the copyright page towards the bottom of the page, you can write a somewhat mysterious line after the @page command that reads like this:

@vskip 0pt plus 1filll

This is a TeX command that is not supported by the Info formatting commands. The @vskip command inserts whitespace. The `0pt plus 1filll' means to put in zero points of mandatory whitespace, and as much optional whitespace as needed to push the following text to the bottom of the page. Note the use of three `l's in the word `filll'; this is the correct usage in TeX.

In a printed manual, the @copyright{} command generates a `c' inside a circle. (In Info, it generates `(C)'.) The copyright notice itself has the following legally defined sequence:

Copyright (C) year copyright-owner

It is customary to put information on how to get a manual after the copyright notice, followed by the copying permissions for the manual.

Note that permissions must be given here as well as in the summary segment within @ifinfo and @end ifinfo that immediately follows the header since this text appears only in the printed manual and the `ifinfo' text appears only in the Info file.

See section Sample Permissions, for the standard text.

Heading Generation

An @end titlepage command on a line by itself not only marks the end of the title and copyright pages, but also causes TeX to start generating page headings and page numbers.

To repeat what is said elsewhere, Texinfo has two standard page heading formats, one for documents which are printed on one side of each sheet of paper (single-sided printing), and the other for documents which are printed on both sides of each sheet (double-sided printing). (See section @setchapternewpage.) You can specify these formats in different ways:

  • The conventional way is to write an @setchapternewpage command before the title page commands, and then have the @end titlepage command start generating page headings in the manner desired. (See section @setchapternewpage.)
  • Alternatively, you can use the @headings command to prevent page headings from being generated or to start them for either single or double-sided printing. (Write an @headings command immediately after the @end titlepage command. See section The @headings Command, for more information.)
  • Or, you may specify your own page heading and footing format. See section Page Headings, for detailed information about page headings and footings.

Most documents are formatted with the standard single-sided or double-sided format, using @setchapternewpage odd for double-sided printing and no @setchapternewpage command for single-sided printing.

The @headings Command

The @headings command is rarely used. It specifies what kind of page headings and footings to print on each page. Usually, this is controlled by the @setchapternewpage command. You need the @headings command only if the @setchapternewpage command does not do what you want, or if you want to turn off pre-defined page headings prior to defining your own. Write an @headings command immediately after the @end titlepage command.

You can use @headings as follows:

@headings off
Turn off printing of page headings.
@headings single
Turn on page headings appropriate for single-sided printing.
@headings double
Turn on page headings appropriate for double-sided printing. The two commands, @headings on and @headings double, are synonymous.
@headings singleafter
@headings doubleafter
Turn on single or double headings, respectively, after the current page is output.
@headings on
Turn on page headings: single if `@setchapternewpage on', double otherwise.

For example, suppose you write @setchapternewpage off before the @titlepage command to tell TeX to start a new chapter on the same page as the end of the last chapter. This command also causes TeX to typeset page headers for single-sided printing. To cause TeX to typeset for double sided printing, write @headings double after the @end titlepage command.

You can stop TeX from generating any page headings at all by writing @headings off on a line of its own immediately after the line containing the @end titlepage command, like this:

@end titlepage
@headings off

The @headings off command overrides the @end titlepage command, which would otherwise cause TeX to print page headings.

You can also specify your own style of page heading and footing. See section Page Headings, for more information.

The `Top' Node and Master Menu

The `Top' node is the node from which you enter an Info file.

A `Top' node should contain a brief description of the Info file and an extensive, master menu for the whole Info file. This helps the reader understand what the Info file is about. Also, you should write the version number of the program to which the Info file applies; or, at least, the edition number.

The contents of the `Top' node should appear only in the Info file; none of it should appear in printed output, so enclose it between @ifinfo and @end ifinfo commands. (TeX does not print either an @node line or a menu; they appear only in Info; strictly speaking, you are not required to enclose these parts between @ifinfo and @end ifinfo, but it is simplest to do so. See section Conditionally Visible Text.)

Sometimes, you will want to place an @top sectioning command line containing the title of the document immediately after the @node Top line (see section The @top Sectioning Command, for more information).

For example, the beginning of the Top node of this manual contains an @top sectioning command, a short description, and edition and version information. It looks like this:

...
@end titlepage

@ifinfo
@node Top, Copying, (dir), (dir)
@top Texinfo

Texinfo is a documentation system...

This is edition...
...
@end ifinfo

@menu
* Copying::                 Texinfo is freely
                              redistributable.
* Overview::                What is Texinfo?
...
@end menu

In a `Top' node, the `Previous', and `Up' nodes usually refer to the top level directory of the whole Info system, which is called `(dir)'. The `Next' node refers to the first node that follows the main or master menu, which is usually the copying permissions, introduction, or first chapter.

Parts of a Master Menu

A master menu is a detailed main menu listing all the nodes in a file.

A master menu is enclosed in @menu and @end menu commands and does not appear in the printed document.

Generally, a master menu is divided into parts.

  • The first part contains the major nodes in the Texinfo file: the nodes for the chapters, chapter-like sections, and the appendices.
  • The second part contains nodes for the indices.
  • The third and subsequent parts contain a listing of the other, lower level nodes, often ordered by chapter. This way, rather than go through an intermediary menu, an inquirer can go directly to a particular node when searching for specific information. These menu items are not required; add them if you think they are a convenience. If you do use them, put @detailmenu before the first one, and @end detailmenu after the last; otherwise, makeinfo will get confused.

Each section in the menu can be introduced by a descriptive line. So long as the line does not begin with an asterisk, it will not be treated as a menu entry. (See section Writing a Menu, for more information.)

For example, the master menu for this manual looks like the following (but has many more entries):

@menu
* Copying::             Texinfo is freely
                          redistributable.
* Overview::            What is Texinfo?
* Texinfo Mode::        Special features in GNU Emacs.
...
...
* Command and Variable Index::
                        An entry for each @-command.
* Concept Index::       An entry for each concept.

@detailmenu
 --- The Detailed Node Listing ---

Overview of Texinfo

* Info Files::          What is an Info file?
* Printed Manuals::     Characteristics of
                          a printed manual.
...
...

Using Texinfo Mode

* Info on a Region::    Formatting part of a file
                          for Info.
...
...
@end detailmenu
@end menu

Software Copying Permissions

If the Texinfo file has a section containing the "General Public License" and the distribution information and a warranty disclaimer for the software that is documented, this section usually follows the `Top' node. The General Public License is very important to Project GNU software. It ensures that you and others will continue to have a right to use and share the software.

The copying and distribution information and the disclaimer are followed by an introduction or else by the first chapter of the manual.

Although an introduction is not a required part of a Texinfo file, it is very helpful. Ideally, it should state clearly and concisely what the file is about and who would be interested in reading it. In general, an introduction would follow the licensing and distribution information, although sometimes people put it earlier in the document. Usually, an introduction is put in an @unnumbered section. (See section @unnumbered, @appendix.)

Ending a Texinfo File

The end of a Texinfo file should include the commands that create indices and generate detailed and summary tables of contents. And it must include the @bye command that marks the last line processed by TeX.

For example:

@node    Concept Index,     , Variables Index, Top
@c        node-name,    next, previous,        up
@unnumbered Concept Index

@printindex cp

@contents
@bye

Index Menus and Printing an Index

To print an index means to include it as part of a manual or Info file. This does not happen automatically just because you use @cindex or other index-entry generating commands in the Texinfo file; those just cause the raw data for the index to be accumulated. To generate an index, you must include the @printindex command at the place in the document where you want the index to appear. Also, as part of the process of creating a printed manual, you must run a program called texindex (see section Format and Print Hardcopy) to sort the raw data to produce a sorted index file. The sorted index file is what is actually used to print the index.

Texinfo offers six different types of predefined index: the concept index, the function index, the variables index, the keystroke index, the program index, and the data type index (see section Predefined Indices). Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg', and `tp'. You may merge indices, or put them into separate sections (see section Combining Indices); or you may define your own indices (see section Defining New Indices).

The @printindex command takes a two-letter index name, reads the corresponding sorted index file and formats it appropriately into an index.

The @printindex command does not generate a chapter heading for the index. Consequently, you should precede the @printindex command with a suitable section or chapter command (usually @unnumbered) to supply the chapter heading and put the index into the table of contents. Precede the @unnumbered command with an @node line.

For example:

@node Variable Index, Concept Index, Function Index, Top
@comment    node-name,         next,       previous, up
@unnumbered Variable Index

@printindex vr

@node     Concept Index,     , Variable Index, Top
@comment      node-name, next,       previous, up
@unnumbered Concept Index

@printindex cp

@summarycontents
@contents
@bye

(Readers often prefer that the concept index come last in a book, since that makes it easiest to find.)

Generating a Table of Contents

The @chapter, @section, and other structuring commands supply the information to make up a table of contents, but they do not cause an actual table to appear in the manual. To do this, you must use the @contents and @summarycontents commands:

@contents
Generate a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. (Headings generated by the @heading series of commands do not appear in the table of contents.) The @contents command should be written on a line by itself.
@shortcontents
@summarycontents
(@summarycontents is a synonym for @shortcontents; the two commands are exactly the same.) Generate a short or summary table of contents that lists only the chapters (and appendices and unnumbered chapters). Omit sections, subsections and subsubsections. Only a long manual needs a short table of contents in addition to the full table of contents. Write the @shortcontents command on a line by itself right before the @contents command.

The table of contents commands automatically generate a chapter-like heading at the top of the first table of contents page. Write the table of contents commands at the very end of a Texinfo file, just before the @bye command, following any index sections--anything in the Texinfo file after the table of contents commands will be omitted from the table of contents.

When you print a manual with a table of contents, the table of contents are printed last and numbered with roman numerals. You need to place those pages in their proper place, after the title page, yourself. (This is the only collating you need to do for a printed manual. The table of contents is printed last because it is generated after the rest of the manual is typeset.)

Here is an example of where to write table of contents commands:

indices...
@shortcontents
@contents
@bye

Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the @contents and @shortcontents commands.

@bye File Ending

An @bye command terminates TeX or Info formatting. None of the formatting commands see any of the file following @bye. The @bye command should be on a line by itself.

If you wish, you may follow the @bye line with notes. These notes will not be formatted and will not appear in either Info or a printed manual; it is as if text after @bye were within @ignore ... @end ignore. Also, you may follow the @bye line with a local variables list. See section Using the Local Variables List, for more information.

Chapter Structuring

The chapter structuring commands divide a document into a hierarchy of chapters, sections, subsections, and subsubsections. These commands generate large headings; they also provide information for the table of contents of a printed manual (see section Generating a Table of Contents).

The chapter structuring commands do not create an Info node structure, so normally you should put an @node command immediately before each chapter structuring command (see section Nodes). The only time you are likely to use the chapter structuring commands without using the node structuring commands is if you are writing a document that contains no cross references and will never be transformed into Info format.

It is unlikely that you will ever write a Texinfo file that is intended only as an Info file and not as a printable document. If you do, you might still use chapter structuring commands to create a heading at the top of each node--but you don't need to.

Tree Structure of Sections

A Texinfo file is usually structured like a book with chapters, sections, subsections, and the like. This structure can be visualized as a tree (or rather as an upside-down tree) with the root at the top and the levels corresponding to chapters, sections, subsection, and subsubsections.

Here is a diagram that shows a Texinfo file with three chapters, each of which has two sections.

                          Top
                           |
         -------------------------------------
        |                  |                  |
     Chapter 1          Chapter 2          Chapter 3
        |                  |                  |
     --------           --------           --------
    |        |         |        |         |        |
 Section  Section   Section  Section   Section  Section
   1.1      1.2       2.1      2.2       3.1      3.2

In a Texinfo file that has this structure, the beginning of Chapter 2 looks like this:

@node    Chapter 2,  Chapter 3, Chapter 1, top
@chapter Chapter 2

The chapter structuring commands are described in the sections that follow; the @node and @menu commands are described in following chapters. (See section Nodes, and see section Menus.)

Types of Structuring Command

The chapter structuring commands fall into four groups or series, each of which contains structuring commands corresponding to the hierarchical levels of chapters, sections, subsections, and subsubsections.

The four groups are the @chapter series, the @unnumbered series, the @appendix series, and the @heading series.

Each command produces titles that have a different appearance on the printed page or Info file; only some of the commands produce titles that are listed in the table of contents of a printed book or manual.

  • The @chapter and @appendix series of commands produce numbered or lettered entries both in the body of a printed work and in its table of contents.
  • The @unnumbered series of commands produce unnumbered entries both in the body of a printed work and in its table of contents. The @top command, which has a special use, is a member of this series (see section @top).
  • The @heading series of commands produce unnumbered headings that do not appear in a table of contents. The heading commands never start a new page.
  • The @majorheading command produces results similar to using the @chapheading command but generates a larger vertical whitespace before the heading.
  • When an @setchapternewpage command says to do so, the @chapter, @unnumbered, and @appendix commands start new pages in the printed manual; the @heading commands do not.

Here are the four groups of chapter structuring commands:

@top

The @top command is a special sectioning command that you use only after an @node Top line at the beginning of a Texinfo file. The @top command tells the makeinfo formatter which node is the `Top' node. It has the same typesetting effect as @unnumbered (see section @unnumbered, @appendix). For detailed information, see section The @top Sectioning Command.

@chapter

@chapter identifies a chapter in the document. Write the command at the beginning of a line and follow it on the same line by the title of the chapter.

For example, this chapter in this manual is entitled "Chapter Structuring"; the @chapter line looks like this:

@chapter Chapter Structuring

In TeX, the @chapter command creates a chapter in the document, specifying the chapter title. The chapter is numbered automatically.

In Info, the @chapter command causes the title to appear on a line by itself, with a line of asterisks inserted underneath. Thus, in Info, the above example produces the following output:

Chapter Structuring
*******************

Texinfo also provides a command @centerchap, which is analogous to @unnumbered, but centers its argument in the printed output. This kind of stylistic choice is not usually offered by Texinfo.

@unnumbered, @appendix

Use the @unnumbered command to create a chapter that appears in a printed manual without chapter numbers of any kind. Use the @appendix command to create an appendix in a printed manual that is labelled by letter instead of by number.

For Info file output, the @unnumbered and @appendix commands are equivalent to @chapter: the title is printed on a line by itself with a line of asterisks underneath. (See section @chapter.)

To create an appendix or an unnumbered chapter, write an @appendix or @unnumbered command at the beginning of a line and follow it on the same line by the title, as you would if you were creating a chapter.

@majorheading, @chapheading

The @majorheading and @chapheading commands put chapter-like headings in the body of a document.

However, neither command causes TeX to produce a numbered heading or an entry in the table of contents; and neither command causes TeX to start a new page in a printed manual.

In TeX, an @majorheading command generates a larger vertical whitespace before the heading than an @chapheading command but is otherwise the same.

In Info, the @majorheading and @chapheading commands are equivalent to @chapter: the title is printed on a line by itself with a line of asterisks underneath. (See section @chapter.)

@section

In a printed manual, an @section command identifies a numbered section within a chapter. The section title appears in the table of contents. In Info, an @section command provides a title for a segment of text, underlined with `='.

This section is headed with an @section command and looks like this in the Texinfo file:

@section @code{@@section}

To create a section, write the @section command at the beginning of a line and follow it on the same line by the section title.

Thus,

@section This is a section

produces

This is a section
=================

in Info.

@unnumberedsec, @appendixsec, @heading

The @unnumberedsec, @appendixsec, and @heading commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the @section command. (See section @section.)

@unnumberedsec
The @unnumberedsec command may be used within an unnumbered chapter or within a regular chapter or appendix to provide an unnumbered section.
@appendixsec
@appendixsection
@appendixsection is a longer spelling of the @appendixsec command; the two are synonymous. Conventionally, the @appendixsec or @appendixsection command is used only within appendices.
@heading
You may use the @heading command anywhere you wish for a section-style heading that will not appear in the table of contents.

The @subsection Command

Subsections are to sections as sections are to chapters. (See section @section.) In Info, subsection titles are underlined with `-'. For example,

@subsection This is a subsection

produces

This is a subsection
--------------------

In a printed manual, subsections are listed in the table of contents and are numbered three levels deep.

The @subsection-like Commands

The @unnumberedsubsec, @appendixsubsec, and @subheading commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the @subsection command. (See section The @subsection Command.)

In Info, the @subsection-like commands generate a title underlined with hyphens. In a printed manual, an @subheading command produces a heading like that of a subsection except that it is not numbered and does not appear in the table of contents. Similarly, an @unnumberedsubsec command produces an unnumbered heading like that of a subsection and an @appendixsubsec command produces a subsection-like heading labelled with a letter and numbers; both of these commands produce headings that appear in the table of contents.

The `subsub' Commands

The fourth and lowest level sectioning commands in Texinfo are the `subsub' commands. They are:

@subsubsection
Subsubsections are to subsections as subsections are to sections. (See section The @subsection Command.) In a printed manual, subsubsection titles appear in the table of contents and are numbered four levels deep.
@unnumberedsubsubsec
Unnumbered subsubsection titles appear in the table of contents of a printed manual, but lack numbers. Otherwise, unnumbered subsubsections are the same as subsubsections. In Info, unnumbered subsubsections look exactly like ordinary subsubsections.
@appendixsubsubsec
Conventionally, appendix commands are used only for appendices and are lettered and numbered appropriately in a printed manual. They also appear in the table of contents. In Info, appendix subsubsections look exactly like ordinary subsubsections.
@subsubheading
The @subsubheading command may be used anywhere that you need a small heading that will not appear in the table of contents. In Info, subsubheadings look exactly like ordinary subsubsection headings.

In Info, `subsub' titles are underlined with periods. For example,

@subsubsection This is a subsubsection

produces

This is a subsubsection
.......................

@raisesections and @lowersections

The @raisesections and @lowersections commands raise and lower the hierarchical level of chapters, sections, subsections and the like. The @raisesections command changes sections to chapters, subsections to sections, and so on. The @lowersections command changes chapters to sections, sections to subsections, and so on.

An @lowersections command is useful if you wish to include text that is written as an outer or standalone Texinfo file in another Texinfo file as an inner, included file. If you write the command at the beginning of the file, all your @chapter commands are formatted as if they were @section commands, all your @section command are formatted as if they were @subsection commands, and so on.

@raisesections raises a command one level in the chapter structuring hierarchy:

  Change           To

@subsection     @section,
@section        @chapter,
@heading        @chapheading,
          etc.

@lowersections lowers a command one level in the chapter structuring hierarchy:

  Change           To

@chapter        @section,
@subsection     @subsubsection,
@heading        @subheading,
          etc.

An @raisesections or @lowersections command changes only those structuring commands that follow the command in the Texinfo file. Write an @raisesections or @lowersections command on a line of its own.

An @lowersections command cancels an @raisesections command, and vice versa.

Repeated use of the commands continue to raise or lower the hierarchical level a step at a time.

An attempt to raise above `chapters' reproduces chapter commands; an attempt to lower below `subsubsections' reproduces subsubsection commands.

Nodes

Nodes are the primary segments of a Texinfo file. They do not themselves impose a hierarchic or any other kind of structure on a file. Nodes contain node pointers that name other nodes, and can contain menus which are lists of nodes. In Info, the movement commands can carry you to a pointed-to node or to a node listed in a menu. Node pointers and menus provide structure for Info files just as chapters, sections, subsections, and the like, provide structure for printed books.

The node and menu commands and the chapter structuring commands are independent of each other:

  • In Info, node and menu commands provide structure. The chapter structuring commands generate headings with different kinds of underlining--asterisks for chapters, hyphens for sections, and so on; they do nothing else.
  • In TeX, the chapter structuring commands generate chapter and section numbers and tables of contents. The node and menu commands provide information for cross references; they do nothing else.

You can use node pointers and menus to structure an Info file any way you want; and you can write a Texinfo file so that its Info output has a different structure than its printed output. However, most Texinfo files are written such that the structure for the Info output corresponds to the structure for the printed output. It is not convenient to do otherwise.

Generally, printed output is structured in a tree-like hierarchy in which the chapters are the major limbs from which the sections branch out. Similarly, node pointers and menus are organized to create a matching structure in the Info output.

Node and Menu Illustration

Here is a copy of the diagram shown earlier that illustrates a Texinfo file with three chapters, each of which contains two sections.

Note that the "root" is at the top of the diagram and the "leaves" are at the bottom. This is how such a diagram is drawn conventionally; it illustrates an upside-down tree. For this reason, the root node is called the `Top' node, and `Up' node pointers carry you closer to the root.

                          Top
                           |
         -------------------------------------
        |                  |                  |
     Chapter 1          Chapter 2          Chapter 3
        |                  |                  |
     --------           --------           --------
    |        |         |        |         |        |
 Section  Section   Section  Section   Section  Section
   1.1      1.2       2.1      2.2       3.1      3.2

Write the beginning of the node for Chapter 2 like this:

@node     Chapter 2,  Chapter 3, Chapter 1, top
@comment  node-name,  next,      previous,  up

This @node line says that the name of this node is "Chapter 2", the name of the `Next' node is "Chapter 3", the name of the `Previous' node is "Chapter 1", and the name of the `Up' node is "Top".

Please Note: `Next' refers to the next node at the same hierarchical level in the manual, not necessarily to the next node within the Texinfo file. In the Texinfo file, the subsequent node may be at a lower level--a section-level node may follow a chapter-level node, and a subsection-level node may follow a section-level node. `Next' and `Previous' refer to nodes at the same hierarchical level. (The `Top' node contains the exception to this rule. Since the `Top' node is the only node at that level, `Next' refers to the first following node, which is almost always a chapter or chapter-level node.)

To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter 2. (See section Menus.) You would write the menu just before the beginning of Section 2.1, like this:

    @menu
    * Sect. 2.1::    Description of this section.
    * Sect. 2.2::
    @end menu

Write the node for Sect. 2.1 like this:

    @node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
    @comment  node-name, next,      previous,  up

In Info format, the `Next' and `Previous' pointers of a node usually lead to other nodes at the same level--from chapter to chapter or from section to section (sometimes, as shown, the `Previous' pointer points up); an `Up' pointer usually leads to a node at the level above (closer to the `Top' node); and a `Menu' leads to nodes at a level below (closer to `leaves'). (A cross reference can point to a node at any level; see section Cross References.)

Usually, an @node command and a chapter structuring command are used in sequence, along with indexing commands. (You may follow the @node line with a comment line that reminds you which pointer is which.)

Here is the beginning of the chapter in this manual called "Ending a Texinfo File". This shows an @node line followed by a comment line, an @chapter line, and then by indexing lines.

@node    Ending a File, Structuring, Beginning a File, Top
@comment node-name,     next,        previous,         up
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending

The @node Command

A node is a segment of text that begins at an @node command and continues until the next @node command. The definition of node is different from that for chapter or section. A chapter may contain sections and a section may contain subsections; but a node cannot contain subnodes; the text of a node continues only until the next @node command in the file. A node usually contains only one chapter structuring command, the one that follows the @node line. On the other hand, in printed output nodes are used only for cross references, so a chapter or section may contain any number of nodes. Indeed, a chapter usually contains several nodes, one for each section, subsection, and subsubsection.

To create a node, write an @node command at the beginning of a line, and follow it with four arguments, separated by commas, on the rest of the same line. These arguments are the name of the node, and the names of the `Next', `Previous', and `Up' pointers, in that order. You may insert spaces before each pointer if you wish; the spaces are ignored. You must write the name of the node, and the names of the `Next', `Previous', and `Up' pointers, all on the same line. Otherwise, the formatters fail. (See Info file `info', node `Top', for more information about nodes in Info.)

Usually, you write one of the chapter-structuring command lines immediately after an @node line--for example, an @section or @subsection line. (See section Types of Structuring Command.)

Please note: The GNU Emacs Texinfo mode updating commands work only with Texinfo files in which @node lines are followed by chapter structuring lines. See section Updating Requirements.

TeX uses @node lines to identify the names to use for cross references. For this reason, you must write @node lines in a Texinfo file that you intend to format for printing, even if you do not intend to format it for Info. (Cross references, such as the one at the end of this sentence, are made with @xref and its related commands; see section Cross References.)

The name of a node identifies the node. The pointers enable you to reach other nodes and consist of the names of those nodes.

Normally, a node's `Up' pointer contains the name of the node whose menu mentions that node. The node's `Next' pointer contains the name of the node that follows that node in that menu and its `Previous' pointer contains the name of the node that precedes it in that menu. When a node's `Previous' node is the same as its `Up' node, both node pointers name the same node.

Usually, the first node of a Texinfo file is the `Top' node, and its `Up' and `Previous' pointers point to the `dir' file, which contains the main menu for all of Info.

The `Top' node itself contains the main or master menu for the manual. Also, it is helpful to include a brief description of the manual in the `Top' node. See section The First Node, for information on how to write the first node of a Texinfo file.

How to Write an @node Line

The easiest way to write an @node line is to write @node at the beginning of a line and then the name of the node, like this:

@node node-name

If you are using GNU Emacs, you can use the update node commands provided by Texinfo mode to insert the names of the pointers; or you can leave the pointers out of the Texinfo file and let makeinfo insert node pointers into the Info file it creates. (See section Using Texinfo Mode, and section Creating Pointers with makeinfo.)

Alternatively, you can insert the `Next', `Previous', and `Up' pointers yourself. If you do this, you may find it helpful to use the Texinfo mode keyboard command C-c C-c n. This command inserts `@node' and a comment line listing the names of the pointers in their proper order. The comment line helps you keep track of which arguments are for which pointers. This comment line is especially useful if you are not familiar with Texinfo.

The template for a node line with `Next', `Previous', and `Up' pointers looks like this:

@node node-name, next, previous, up

If you wish, you can ignore @node lines altogether in your first draft and then use the texinfo-insert-node-lines command to create @node lines for you. However, we do not recommend this practice. It is better to name the node itself at the same time that you write a segment so you can easily make cross references. A large number of cross references are an especially important feature of a good Info file.

After you have inserted an @node line, you should immediately write an @-command for the chapter or section and insert its name. Next (and this is important!), put in several index entries. Usually, you will find at least two and often as many as four or five ways of referring to the node in the index. Use them all. This will make it much easier for people to find the node.

@node Line Tips

Here are three suggestions:

  • Try to pick node names that are informative but short. In the Info file, the file name, node name, and pointer names are all inserted on one line, which may run into the right edge of the window. (This does not cause a problem with Info, but is ugly.)
  • Try to pick node names that differ from each other near the beginnings of their names. This way, it is easy to use automatic name completion in Info.
  • By convention, node names are capitalized just as they would be for section or chapter titles--initial and significant words are capitalized; others are not.

@node Line Requirements

Here are several requirements for @node lines:

  • All the node names for a single Info file must be unique. Duplicates confuse the Info movement commands. This means, for example, that if you end every chapter with a summary, you must name each summary node differently. You cannot just call each one "Summary". You may, however, duplicate the titles of chapters, sections, and the like. Thus you can end each chapter in a book with a section called "Summary", so long as the node names for those sections are all different.
  • A pointer name must be the name of a node. The node to which a pointer points may come before or after the node containing the pointer.
  • You cannot use any of the Texinfo @-commands in a node name; @-commands confuse Info. Thus, the beginning of the section called @chapter looks like this:
    @node  chapter, unnumbered & appendix, makeinfo top, Structuring
@comment  node-name,  next,  previous,  up
@section @code{@@chapter}
@findex chapter
  • You cannot use commas, colons, or apostrophes within a node name; these confuse TeX or the Info formatters. For example, the following is a section title:
    @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
    The corresponding node name is:
    unnumberedsec appendixsec heading
  • Case is significant.

The First Node

The first node of a Texinfo file is the `Top' node, except in an included file (see section Include Files).

The `Top' node (which must be named `top' or `Top') should have as its `Up' and `Previous' nodes the name of a node in another file, where there is a menu that leads to this file. Specify the file name in parentheses. If the file is to be installed directly in the Info directory file, use `(dir)' as the parent of the `Top' node; this is short for `(dir)top', and specifies the `Top' node in the `dir' file, which contains the main menu for Info. For example, the @node Top line of this manual looks like this:

@node Top, Overview, (dir), (dir)

(You may use the Texinfo updating commands or the makeinfo utility to insert these `Next' and `(dir)' pointers automatically.)

See section Installing an Info File, for more information about installing an Info file in the `info' directory.

The `Top' node contains the main or master menu for the document.

The @top Sectioning Command

A special sectioning command, @top, has been created for use with the @node Top line. The @top sectioning command tells makeinfo that it marks the `Top' node in the file. It provides the information that makeinfo needs to insert node pointers automatically. Write the @top command at the beginning of the line immediately following the @node Top line. Write the title on the remaining part of the same line as the @top command.

In Info, the @top sectioning command causes the title to appear on a line by itself, with a line of asterisks inserted underneath.

In TeX and texinfo-format-buffer, the @top sectioning command is merely a synonym for @unnumbered. Neither of these formatters require an @top command, and do nothing special with it. You can use @chapter or @unnumbered after the @node Top line when you use these formatters. Also, you can use @chapter or @unnumbered when you use the Texinfo updating commands to create or update pointers and menus.

The `Top' Node Summary

You can help readers by writing a summary in the `Top' node, after the @top line, before the main or master menu. The summary should briefly describe the document. In Info, this summary will appear just before the master menu. In a printed manual, this summary will appear on a page of its own.

If you do not want the summary to appear on a page of its own in a printed manual, you can enclose the whole of the `Top' node, including the @node Top line and the @top sectioning command line or other sectioning command line between @ifinfo and @end ifinfo. This prevents any of the text from appearing in the printed output. (see section Conditionally Visible Text). You can repeat the brief description from the `Top' node within @iftex ... @end iftex at the beginning of the first chapter, for those who read the printed manual. This saves paper and may look neater.

You should write the version number of the program to which the manual applies in the summary. This helps the reader keep track of which manual is for which version of the program. If the manual changes more frequently than the program or is independent of it, you should also include an edition number for the manual. (The title page should also contain this information: see section @titlepage.)

Creating Pointers with makeinfo

The makeinfo program has a feature for automatically creating node pointers for a hierarchically organized file that lacks them.

When you take advantage of this feature, you do not need to write the `Next', `Previous', and `Up' pointers after the name of a node. However, you must write a sectioning command, such as @chapter or @section, on the line immediately following each truncated @node line. You cannot write a comment line after a node line; the section line must follow it immediately.

In addition, you must follow the `Top' @node line with a line beginning with @top to mark the `Top' node in the file. See section @top.

Finally, you must write the name of each node (except for the `Top' node) in a menu that is one or more hierarchical levels above the node's hierarchical level.

This node pointer insertion feature in makeinfo is an alternative to the menu and pointer creation and update commands in Texinfo mode. (See section Updating Nodes and Menus.) It is especially helpful to people who do not use GNU Emacs for writing Texinfo documents.

Menus

Menus contain pointers to subordinate nodes.(6) In Info, you use menus to go to such nodes. Menus have no effect in printed manuals and do not appear in them.

By convention, a menu is put at the end of a node since a reader who uses the menu may not see text that follows it.

A node that has a menu should not contain much text. If you have a lot of text and a menu, move most of the text into a new subnode--all but a few lines. Otherwise, a reader with a terminal that displays only a few lines may miss the menu and its associated text. As a practical matter, you should locate a menu within 20 lines of the beginning of the node.

The short text before a menu may look awkward in a printed manual. To avoid this, you can write a menu near the beginning of its node and follow the menu by an @node line, and then an @heading line located within @ifinfo and @end ifinfo. This way, the menu, @node line, and title appear only in the Info file, not the printed document.

For example, the preceding two paragraphs follow an Info-only menu, @node line, and heading, and look like this:

@menu
* Menu Location::             Put a menu in a short node.
* Writing a Menu::            What is a menu?
* Menu Parts::                A menu entry has three parts.
* Less Cluttered Menu Entry:: Two part menu entry.
* Menu Example::              Two and three part entries.
* Other Info Files::          How to refer to a different
                                Info file.
@end menu

@node Menu Location, Writing a Menu, , Menus
@ifinfo
@heading Menus Need Short Nodes
@end ifinfo

The Texinfo file for this document contains more than a dozen examples of this procedure. One is at the beginning of this chapter; another is at the beginning of the "Cross References" chapter.

Writing a Menu

A menu consists of an @menu command on a line by itself followed by menu entry lines or menu comment lines and then by an @end menu command on a line by itself.

A menu looks like this:

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.
@end menu

In a menu, every line that begins with an `* ' is a menu entry. (Note the space after the asterisk.) A line that does not start with an `* ' may also appear in a menu. Such a line is not a menu entry but is a menu comment line that appears in the Info file. In the example above, the line `Larger Units of Text' is a menu comment line; the two lines starting with `* ' are menu entries.

The Parts of a Menu

A menu entry has three parts, only the second of which is required:

  1. The menu entry name.
  2. The name of the node (required).
  3. A description of the item.

The template for a menu entry looks like this:

* menu-entry-name: node-name.   description

Follow the menu entry name with a single colon and follow the node name with tab, comma, period, or newline.

In Info, a user selects a node with the m (Info-menu) command. The menu entry name is what the user types after the m command.

The third part of a menu entry is a descriptive phrase or sentence. Menu entry names and node names are often short; the description explains to the reader what the node is about. The description, which is optional, can spread over two or more lines. A useful description complements the node name rather than repeats it.

Less Cluttered Menu Entry

When the menu entry name and node name are the same, you can write the name immediately after the asterisk and space at the beginning of the line and follow the name with two colons.

For example, write

* Name::                                    description

instead of

* Name: Name.                               description

You should use the node name for the menu entry name whenever possible, since it reduces visual clutter in the menu.

A Menu Example

A menu looks like this in Texinfo:

@menu
* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.
@end menu

This produces:

* menu:

* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.

Here is an example as you might see it in a Texinfo file:

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.
@end menu

This produces:

* menu:
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                  several files at once.

In this example, the menu has two entries. `Files' is both a menu entry name and the name of the node referred to by that name. `Multiples' is the menu entry name; it refers to the node named `Buffers'. The line `Larger Units of Text' is a comment; it appears in the menu, but is not an entry.

Since no file name is specified with either `Files' or `Buffers', they must be the names of nodes in the same Info file (see section Referring to Other Info Files).

Referring to Other Info Files

You can create a menu entry that enables a reader in Info to go to a node in another Info file by writing the file name in parentheses just before the node name. In this case, you should use the three-part menu entry format, which saves the reader from having to type the file name.

The format looks like this:

@menu
* first-entry-name:(filename)nodename.     description
* second-entry-name:(filename)second-node. description
@end menu

For example, to refer directly to the `Outlining' and `Rebinding' nodes in the Emacs Manual, you would write a menu like this:

@menu
* Outlining: (emacs)Outline Mode. The major mode for
                                  editing outlines.
* Rebinding: (emacs)Rebinding.    How to redefine the
                                  meaning of a key.
@end menu

If you do not list the node name, but only name the file, then Info presumes that you are referring to the `Top' node.

The `dir' file that contains the main menu for Info has menu entries that list only file names. These take you directly to the `Top' nodes of each Info document. (See section Installing an Info File.)

For example:

* Info: (info).         Documentation browsing system.
* Emacs: (emacs).       The extensible, self-documenting
                        text editor.

(The `dir' top level directory for the Info system is an Info file, not a Texinfo file, but a menu entry looks the same in both types of file.)

Note that the GNU Emacs Texinfo mode menu updating commands only work with nodes within the current buffer, so you cannot use them to create menus that refer to other files. You must write such menus by hand.

Cross References

Cross references are used to refer the reader to other parts of the same or different Texinfo files. In Texinfo, nodes are the places to which cross references can refer.

Often, but not always, a printed document should be designed so that it can be read sequentially. People tire of flipping back and forth to find information that should be presented to them as they need it.

However, in any document, some information will be too detailed for the current context, or incidental to it; use cross references to provide access to such information. Also, an on-line help system or a reference manual is not like a novel; few read such documents in sequence from beginning to end. Instead, people look up what they need. For this reason, such creations should contain many cross references to help readers find other information that they may not have read.

In a printed manual, a cross reference results in a page reference, unless it is to another manual altogether, in which case the cross reference names that manual.

In Info, a cross reference results in an entry that you can follow using the Info `f' command. (See Info file `info', node `Help-Adv'.)

The various cross reference commands use nodes to define cross reference locations. This is evident in Info, in which a cross reference takes you to the specified node. TeX also uses nodes to define cross reference locations, but the action is less obvious. When TeX generates a DVI file, it records nodes' page numbers and uses the page numbers in making references. Thus, if you are writing a manual that will only be printed, and will not be used on-line, you must nonetheless write @node lines to name the places to which you make cross references.

Different Cross Reference Commands

There are four different cross reference commands:

@xref
Used to start a sentence in the printed manual saying `See ...' or an Info cross-reference saying `*Note name: node.'.
@ref
Used within or, more often, at the end of a sentence; same as @xref for Info; produces just the reference in the printed manual without a preceding `See'.
@pxref
Used within parentheses to make a reference that suits both an Info file and a printed book. Starts with a lower case `see' within the printed manual. (`p' is for `parenthesis'.)
@inforef
Used to make a reference to an Info file for which there is no printed manual.

(The @cite command is used to make references to books and manuals for which there is no corresponding Info file and, therefore, no node to which to point. See section @cite{reference}.)

Parts of a Cross Reference

A cross reference command requires only one argument, which is the name of the node to which it refers. But a cross reference command may contain up to four additional arguments. By using these arguments, you can provide a cross reference name for Info, a topic description or section title for the printed output, the name of a different Info file, and the name of a different printed manual.

Here is a simple cross reference example:

@xref{Node name}.

which produces

*Note Node name::.

and

See Section nnn [Node name], page ppp.

Here is an example of a full five-part cross reference:

@xref{Node name, Cross Reference Name, Particular Topic,
info-file-name, A Printed Manual}, for details.

which produces

*Note Cross Reference Name: (info-file-name)Node name,
for details.

in Info and

See section "Particular Topic" in A Printed Manual, for details.

in a printed book.

The five possible arguments for a cross reference are:

  1. The node name (required). This is the node to which the cross reference takes you. In a printed document, the location of the node provides the page reference only for references within the same document.
  2. The cross reference name for the Info reference, if it is to be different from the node name. If you include this argument, it argument becomes the first part of the cross reference. It is usually omitted.
  3. A topic description or section name. Often, this is the title of the section. This is used as the name of the reference in the printed manual. If omitted, the node name is used.
  4. The name of the Info file in which the reference is located, if it is different from the current file.
  5. The name of a printed manual from a different Texinfo file.

The template for a full five argument cross reference looks like this:

@xref{node-name, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

Cross references with one, two, three, four, and five arguments are described separately following the description of @xref.

Write a node name in a cross reference in exactly the same way as in the @node line, including the same capitalization; otherwise, the formatters may not find the reference.

You can write cross reference commands within a paragraph, but note how Info and TeX format the output of each of the various commands: write @xref at the beginning of a sentence; write @pxref only within parentheses, and so on.

@xref

The @xref command generates a cross reference for the beginning of a sentence. The Info formatting commands convert it into an Info cross reference, which the Info `f' command can use to bring you directly to another node. The TeX typesetting commands convert it into a page reference, or a reference to another book or manual.

Most often, an Info cross reference looks like this:

*Note node-name::.

or like this

*Note cross-reference-name: node-name.

In TeX, a cross reference looks like this:

See Section section-number [node-name], page page.

or like this

See Section section-number [title-or-topic], page page.

The @xref command does not generate a period or comma to end the cross reference in either the Info file or the printed output. You must write that period or comma yourself; otherwise, Info will not recognize the end of the reference. (The @pxref command works differently. See section @pxref.)

Please note: A period or comma must follow the closing brace of an @xref. It is required to terminate the cross reference. This period or comma will appear in the output, both in the Info file and in the printed manual.

@xref must refer to an Info node by name. Use @node to define the node (see section How to Write an @node Line).

@xref is followed by several arguments inside braces, separated by commas. Whitespace before and after these commas is ignored.

A cross reference requires only the name of a node; but it may contain up to four additional arguments. Each of these variations produces a cross reference that looks somewhat different.

Please note: Commas separate arguments in a cross reference; avoid including them in the title or other part lest the formatters mistake them for separators.

@xref with One Argument

The simplest form of @xref takes one argument, the name of another node in the same Info file. The Info formatters produce output that the Info readers can use to jump to the reference; TeX produces output that specifies the page and section number for you.

For example,

@xref{Tropical Storms}.

produces

*Note Tropical Storms::.

and

See Section 3.1 [Tropical Storms], page 24.

(Note that in the preceding example the closing brace is followed by a period.)

You can write a clause after the cross reference, like this:

@xref{Tropical Storms}, for more info.

which produces

*Note Tropical Storms::, for more info.

See Section 3.1 [Tropical Storms], page 24, for more info.

(Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.)

@xref with Two Arguments

With two arguments, the second is used as the name of the Info cross reference, while the first is still the name of the node to which the cross reference points.

The template is like this:

@xref{node-name, cross-reference-name}.

For example,

@xref{Electrical Effects, Lightning}.

produces:

*Note Lightning: Electrical Effects.

and

See Section 5.2 [Electrical Effects], page 57.

(Note that in the preceding example the closing brace is followed by a period; and that the node name is printed, not the cross reference name.)

You can write a clause after the cross reference, like this:

@xref{Electrical Effects, Lightning}, for more info.

which produces

*Note Lightning: Electrical Effects, for more info.

and

See Section 5.2 [Electrical Effects], page 57, for more info.

(Note that in the preceding example the closing brace is followed by a comma, and then by the clause, which is followed by a period.)

@xref with Three Arguments

A third argument replaces the node name in the TeX output. The third argument should be the name of the section in the printed output, or else state the topic discussed by that section. Often, you will want to use initial upper case letters so it will be easier to read when the reference is printed. Use a third argument when the node name is unsuitable because of syntax or meaning.

Remember to avoid placing a comma within the title or topic section of a cross reference, or within any other section. The formatters divide cross references into arguments according to the commas; a comma within a title or other section will divide it into two arguments. In a reference, you need to write a title such as "Clouds, Mist, and Fog" without the commas.

Also, remember to write a comma or period after the closing brace of a @xref to terminate the cross reference. In the following examples, a clause follows a terminating comma.

The template is like this:

@xref{node-name, cross-reference-name, title-or-topic}.

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning},
for details.

produces

*Note Lightning: Electrical Effects, for details.

and

See Section 5.2 [Thunder and Lightning], page 57, for details.

If a third argument is given and the second one is empty, then the third argument serves both. (Note how two commas, side by side, mark the empty second argument.)

@xref{Electrical Effects, , Thunder and Lightning},
for details.

produces

*Note Thunder and Lightning: Electrical Effects, for details.

and

See Section 5.2 [Thunder and Lightning], page 57, for details.

As a practical matter, it is often best to write cross references with just the first argument if the node name and the section title are the same, and with the first and third arguments if the node name and title are different.

Here are several examples from The GAWK Manual:

@xref{Sample Program}.
@xref{Glossary}.
@xref{Case-sensitivity, ,Case-sensitivity in Matching}.
@xref{Close Output, , Closing Output Files and Pipes},
   for more information.
@xref{Regexp, , Regular Expressions as Patterns}.

@xref with Four and Five Arguments

In a cross reference, a fourth argument specifies the name of another Info file, different from the file in which the reference appears, and a fifth argument specifies its title as a printed manual.

Remember that a comma or period must follow the closing brace of an @xref command to terminate the cross reference. In the following examples, a clause follows a terminating comma.

The template is:

@xref{node-name, cross-reference-name, title-or-topic,
info-file-name, printed-manual-title}.

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning,
weather, An Introduction to Meteorology}, for details.

produces

*Note Lightning: (weather)Electrical Effects, for details.

The name of the Info file is enclosed in parentheses and precedes the name of the node.

In a printed manual, the reference looks like this:

See section "Thunder and Lightning" in An Introduction to Meteorology, for details.

The title of the printed manual is typeset in italics; and the reference lacks a page number since TeX cannot know to which page a reference refers when that reference is to another manual.

Often, you will leave out the second argument when you use the long version of @xref. In this case, the third argument, the topic description, will be used as the cross reference name in Info.

The template looks like this:

@xref{node-name, , title-or-topic, info-file-name,
printed-manual-title}, for details.

which produces

*Note title-or-topic: (info-file-name)node-name, for details.

and

See section title-or-topic in printed-manual-title, for details.

For example,

@xref{Electrical Effects, , Thunder and Lightning,
weather, An Introduction to Meteorology}, for details.

produces

*Note Thunder and Lightning: (weather)Electrical Effects,
for details.

and

See section "Thunder and Lightning" in An Introduction to Meteorology, for details.

On rare occasions, you may want to refer to another Info file that is within a single printed manual--when multiple Texinfo files are incorporated into the same TeX run but make separate Info files. In this case, you need to specify only the fourth argument, and not the fifth.

Naming a `Top' Node

In a cross reference, you must always name a node. This means that in order to refer to a whole manual, you must identify the `Top' node by writing it as the first argument to the @xref command. (This is different from the way you write a menu entry; see section Referring to Other Info Files.) At the same time, to provide a meaningful section topic or title in the printed cross reference (instead of the word `Top'), you must write an appropriate entry for the third argument to the @xref command.

Thus, to make a cross reference to The GNU Make Manual, write:

@xref{Top, , Overview, make, The GNU Make Manual}.

which produces

*Note Overview: (make)Top.

and

See section "Overview" in The GNU Make Manual.

In this example, `Top' is the name of the first node, and `Overview' is the name of the first section of the manual.

@ref

@ref is nearly the same as @xref except that it does not generate a `See' in the printed output, just the reference itself. This makes it useful as the last part of a sentence.

For example,

For more information, see @ref{Hurricanes}.

produces

For more information, see *Note Hurricanes.

and

For more information, see Section 8.2 [Hurricanes], page 123.

The @ref command sometimes leads writers to express themselves in a manner that is suitable for a printed manual but looks awkward in the Info format. Bear in mind that your audience will be using both the printed and the Info format.

For example,

Sea surges are described in @ref{Hurricanes}.

produces

Sea surges are described in Section 6.7 [Hurricanes], page 72.

in a printed document, and the following in Info:

Sea surges are described in *Note Hurricanes::.

Caution: You must write a period or comma immediately after an @ref command with two or more arguments. Otherwise, Info will not find the end of the cross reference entry and its attempt to follow the cross reference will fail. As a general rule, you should write a period or comma after every @ref command. This looks best in both the printed and the Info output.

@pxref

The parenthetical reference command, @pxref, is nearly the same as @xref, but you use it only inside parentheses and you do not type a comma or period after the command's closing brace. The command differs from @xref in two ways:

  1. TeX typesets the reference for the printed manual with a lower case `see' rather than an upper case `See'.
  2. The Info formatting commands automatically end the reference with a closing colon or period.

Because one type of formatting automatically inserts closing punctuation and the other does not, you should use @pxref only inside parentheses as part of another sentence. Also, you yourself should not insert punctuation after the reference, as you do with @xref.

@pxref is designed so that the output looks right and works right between parentheses both in printed output and in an Info file. In a printed manual, a closing comma or period should not follow a cross reference within parentheses; such punctuation is wrong. But in an Info file, suitable closing punctuation must follow the cross reference so Info can recognize its end. @pxref spares you the need to use complicated methods to put a terminator into one form of the output and not the other.

With one argument, a parenthetical cross reference looks like this:

... storms cause flooding (@pxref{Hurricanes}) ...

which produces

... storms cause flooding (*Note Hurricanes::) ...

and

... storms cause flooding (see Section 6.7 [Hurricanes], page 72) ...

With two arguments, a parenthetical cross reference has this template:

... (@pxref{node-name, cross-reference-name}) ...

which produces

... (*Note cross-reference-name: node-name.) ...

and

... (see Section nnn [node-name], page ppp) ...

@pxref can be used with up to five arguments just like @xref (see section @xref).

Please note: Use @pxref only as a parenthetical reference. Do not try to use @pxref as a clause in a sentence. It will look bad in either the Info file, the printed output, or both.

Also, parenthetical cross references look best at the ends of sentences. Although you may write them in the middle of a sentence, that location breaks up the flow of text.

@inforef

@inforef is used for cross references to Info files for which there are no printed manuals. Even in a printed manual, @inforef generates a reference directing the user to look in an Info file.

The command takes either two or three arguments, in the following order:

  1. The node name.
  2. The cross reference name (optional).
  3. The Info file name.

Separate the arguments with commas, as with @xref. Also, you must terminate the reference with a comma or period after the `}', as you do with @xref.

The template is:

@inforef{node-name, cross-reference-name, info-file-name},

Thus,

@inforef{Expert, Advanced Info commands, info},
for more information.

produces

*Note Advanced Info commands: (info)Expert,
for more information.

and

See Info file `info', node `Expert', for more information.

Similarly,

@inforef{Expert, , info}, for more information.

produces

*Note (info)Expert::, for more information.

and

See Info file `info', node `Expert', for more information.

The converse of @inforef is @cite, which is used to refer to printed works for which no Info form exists. See section @cite{reference}.

Marking Words and Phrases

In Texinfo, you can mark words and phrases in a variety of ways. The Texinfo formatters use this information to determine how to highlight the text. You can specify, for example, whether a word or phrase is a defining occurrence, a metasyntactic variable, or a symbol used in a program. Also, you can emphasize text.

Indicating Definitions, Commands, etc.

Texinfo has commands for indicating just what kind of object a piece of text refers to. For example, metasyntactic variables are marked by @var, and code by @code. Since the pieces of text are labelled by commands that tell what kind of object they are, it is easy to change the way the Texinfo formatters prepare such text. (Texinfo is an intentional formatting language rather than a typesetting formatting language.)

For example, in a printed manual, code is usually illustrated in a typewriter font; @code tells TeX to typeset this text in this font. But it would be easy to change the way TeX highlights code to use another font, and this change would not effect how keystroke examples are highlighted. If straight typesetting commands were used in the body of the file and you wanted to make a change, you would need to check every single occurrence to make sure that you were changing code and not something else that should not be changed.

The highlighting commands can be used to generate useful information from the file, such as lists of functions or file names. It is possible, for example, to write a program in Emacs Lisp (or a keyboard macro) to insert an index entry after every paragraph that contains words or phrases marked by a specified command. You could do this to construct an index of functions if you had not already made the entries.

The commands serve a variety of purposes:

@code{sample-code}
Indicate text that is a literal example of a piece of a program.
@kbd{keyboard-characters}
Indicate keyboard input.
@key{key-name}
Indicate the conventional name for a key on a keyboard.
@samp{text}
Indicate text that is a literal example of a sequence of characters.
@var{metasyntactic-variable}
Indicate a metasyntactic variable.
@url{uniform-resource-locator}
Indicate a uniform resource locator for the World Wide Web.
@file{file-name}
Indicate the name of a file.
@email{email-address}
Indicate an electronic mail address.
@dfn{term}
Indicate the introductory or defining use of a term.
@cite{reference}
Indicate the name of a book.

@code{sample-code}

Use the @code command to indicate text that is a piece of a program and which consists of entire syntactic tokens. Enclose the text in braces.

Thus, you should use @code for an expression in a program, for the name of a variable or function used in a program, or for a keyword. Also, you should use @code for the name of a program, such as diff, that is a name used in the machine. (You should write the name of a program in the ordinary text font if you regard it as a new English word, such as `Emacs' or `Bison'.)

Use @code for environment variables such as TEXINPUTS, and other variables.

Use @code for command names in command languages that resemble programming languages, such as Texinfo or the shell. For example, @code and @samp are produced by writing `@code{@@code}' and `@code{@@samp}' in the Texinfo source, respectively.

Note, however, that you should not use @code for shell options such as `-c' when such options stand alone. (Use @samp.) Also, an entire shell command often looks better if written using @samp rather than @code. In this case, the rule is to choose the more pleasing format.

It is incorrect to alter the case of a word inside an @code command when it appears at the beginning of a sentence. Most computer languages are case sensitive. In C, for example, Printf is different from the identifier printf, and most likely is a misspelling of it. Even in languages which are not case sensitive, it is confusing to a human reader to see identifiers spelled in different ways. Pick one spelling and always use that. If you do not want to start a sentence with a command written all in lower case, you should rearrange the sentence.

Do not use the @code command for a string of characters shorter than a syntactic token. If you are writing about `TEXINPU', which is just a part of the name for the TEXINPUTS environment variable, you should use @samp.

In particular, you should not use the @code command when writing about the characters used in a token; do not, for example, use @code when you are explaining what letters or printable symbols can be used in the names of functions. (Use @samp.) Also, you should not use @code to mark text that is considered input to programs unless the input is written in a language that is like a programming language. For example, you should not use @code for the keystroke commands of GNU Emacs (use @kbd instead) although you may use @code for the names of the Emacs Lisp functions that the keystroke commands invoke.

In the printed manual, @code causes TeX to typeset the argument in a typewriter face. In the Info file, it causes the Info formatting commands to use single quotation marks around the text.

For example,

Use @code{diff} to compare two files.

produces this in the printed manual:

Use diff to compare two files.

and this in the Info file:

Use `diff' to compare two files.

@kbd{keyboard-characters}

Use the @kbd command for characters of input to be typed by users. For example, to refer to the characters M-a, write

@kbd{M-a}

and to refer to the characters M-x shell, write

@kbd{M-x shell}

The @kbd command has the same effect as @code in Info, but may produce a different font in a printed manual.

You can embed another @-command inside the braces of an @kbd command. Here, for example, is the way to describe a command that would be described more verbosely as "press an `r' and then press the RET key":

@kbd{r @key{RET}}

This produces: r RET

You also use the @kbd command if you are spelling out the letters you type; for example:

To give the @code{logout} command,
type the characters @kbd{l o g o u t @key{RET}}.

This produces:

To give the logout command, type the characters l o g o u t RET.

(Also, this example shows that you can add spaces for clarity. If you really want to mention a space character as one of the characters of input, write @key{SPC} for it.)

@key{key-name}

Use the @key command for the conventional name for a key on a keyboard, as in:

@key{RET}

You can use the @key command within the argument of an @kbd command when the sequence of characters to be typed includes one or more keys that are described by name.

For example, to produce C-x ESC you would type:

@kbd{C-x @key{ESC}}

Here is a list of the recommended names for keys:

SPC
Space
RET
Return
LFD
Linefeed (however, since most keyboards nowadays do not have a Linefeed key, it might be better to call this character C-j.
TAB
Tab
BS
Backspace
ESC
Escape
DEL
Delete
SHIFT
Shift
CTRL
Control
META
Meta

There are subtleties to handling words like `meta' or `ctrl' that are names of shift keys. When mentioning a character in which the shift key is used, such as Meta-a, use the @kbd command alone; do not use the @key command; but when you are referring to the shift key in isolation, use the @key command. For example, write `@kbd{Meta-a}' to produce Meta-a and `@key{META}' to produce META.

@samp{text}

Use the @samp command to indicate text that is a literal example or `sample' of a sequence of characters in a file, string, pattern, etc. Enclose the text in braces. The argument appears within single quotation marks in both the Info file and the printed manual; in addition, it is printed in a fixed-width font.

To match @samp{foo} at the end of the line,
use the regexp @samp{foo$}.

produces

To match `foo' at the end of the line, use the regexp `foo$'.

Any time you are referring to single characters, you should use @samp unless @kbd is more appropriate. Use @samp for the names of command-line options. Also, you may use @samp for entire statements in C and for entire shell commands--in this case, @samp often looks better than @code. Basically, @samp is a catchall for whatever is not covered by @code, @kbd, or @key.

Only include punctuation marks within braces if they are part of the string you are specifying. Write punctuation marks outside the braces if those punctuation marks are part of the English text that surrounds the string. In the following sentence, for example, the commas and period are outside of the braces:

In English, the vowels are @samp{a}, @samp{e},
@samp{i}, @samp{o}, @samp{u}, and sometimes
@samp{y}.

This produces:

In English, the vowels are `a', `e', `i', `o', `u', and sometimes `y'.

@var{metasyntactic-variable}

Use the @var command to indicate metasyntactic variables. A metasyntactic variable is something that stands for another piece of text. For example, you should use a metasyntactic variable in the documentation of a function to describe the arguments that are passed to that function.

Do not use @var for the names of particular variables in programming languages. These are specific names from a program, so @code is correct for them. For example, the Lisp variable texinfo-tex-command is not a metasyntactic variable; it is properly formatted using @code.

The effect of @var in the Info file is to change the case of the argument to all upper case; in the printed manual, to italicize it.

For example,

To delete file @var{filename},
type @code{rm @var{filename}}.

produces

To delete file filename, type rm filename.

(Note that @var may appear inside @code, @samp, @file, etc.)

Write a metasyntactic variable all in lower case without spaces, and use hyphens to make it more readable. Thus, the Texinfo source for the illustration of how to begin a Texinfo manual looks like this:

\input texinfo
@@setfilename @var{info-file-name}
@@settitle @var{name-of-manual}

This produces:

\input texinfo
@setfilename info-file-name
@settitle name-of-manual

In some documentation styles, metasyntactic variables are shown with angle brackets, for example:

..., type rm <filename>

However, that is not the style that Texinfo uses. (You can, of course, modify the sources to TeX and the Info formatting commands to output the <...> format if you wish.)

@file{file-name}

Use the @file command to indicate text that is the name of a file, buffer, or directory, or is the name of a node in Info. You can also use the command for file name suffixes. Do not use @file for symbols in a programming language; use @code.

Currently, @file is equivalent to @samp in its effects. For example,

The @file{.el} files are in
the @file{/usr/local/emacs/lisp} directory.

produces

The `.el' files are in the `/usr/local/emacs/lisp' directory.

@dfn{term}

Use the @dfn command to identify the introductory or defining use of a technical term. Use the command only in passages whose purpose is to introduce a term which will be used again or which the reader ought to know. Mere passing mention of a term for the first time does not deserve @dfn. The command generates italics in the printed manual, and double quotation marks in the Info file. For example:

Getting rid of a file is called @dfn{deleting} it.

produces

Getting rid of a file is called deleting it.

As a general rule, a sentence containing the defining occurrence of a term should be a definition of the term. The sentence does not need to say explicitly that it is a definition, but it should contain the information of a definition--it should make the meaning clear.

@cite{reference}

Use the @cite command for the name of a book that lacks a companion Info file. The command produces italics in the printed manual, and quotation marks in the Info file.

(If a book is written in Texinfo, it is better to use a cross reference command since a reader can easily follow such a reference in Info. See section @xref.)

@url{uniform-resource-locator}

Use the @url command to indicate a uniform resource locator on the World Wide Web. For example:

The official GNU ftp site is
@url{ftp://ftp.gnu.ai.mit.edu/pub/gnu}.

In Info and TeX, this acts like @samp. When Texinfo is converted to HTML, this produces a link you can follow.

@email{email-address}

Use the @email command to indicate an electronic mail address. For example:

Send bug reports to bug-texinfo@prep.ai.mit.edu.

In Info and TeX, this acts like @samp. When we have support for conversion of Texinfo to HTML, this will produce a link you can follow to bring up a mail composition window initialized with email-address.

Emphasizing Text

Usually, Texinfo changes the font to mark words in the text according to what category the words belong to; an example is the @code command. Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two commands to do this. Also, Texinfo has several commands that specify the font in which TeX will typeset text. These commands have no affect on Info and only one of them, the @r command, has any regular use.

@emph{text} and @strong{text}

The @emph and @strong commands are for emphasis; @strong is stronger. In printed output, @emph produces italics and @strong produces bold.

For example,

@quotation
@strong{Caution:} @code{rm * .[^.]*} removes @emph{all}
files in the directory.
@end quotation

produces the following in printed output:

Caution: rm * .[^.]* removes all files in the directory.

and the following in Info:

     *Caution*: `rm * .[^.]*' removes *all*
     files in the directory.

The @strong command is seldom used except to mark what is, in effect, a typographical element, such as the word `Caution' in the preceding example.

In the Info file, both @emph and @strong put asterisks around the text.

Caution: Do not use @emph or @strong with the word `Note'; Info will mistake the combination for a cross reference. Use a phrase such as Please note or Caution instead.

@sc{text}: The Small Caps Font

Use the `@sc' command to set text in the printed output in A SMALL CAPS FONT and set text in the Info file in upper case letters.

Write the text between braces in lower case, like this:

The @sc{acm} and @sc{ieee} are technical societies.

This produces:

The ACM and IEEE are technical societies.

TeX typesets the small caps font in a manner that prevents the letters from `jumping out at you on the page'. This makes small caps text easier to read than text in all upper case. The Info formatting commands set all small caps text in upper case.

If the text between the braces of an @sc command is upper case, TeX typesets in FULL-SIZE CAPITALS. Use full-size capitals sparingly.

You may also use the small caps font for a jargon word such as ATO (a NASA word meaning `abort to orbit').

There are subtleties to using the small caps font with a jargon word such as CDR, a word used in Lisp programming. In this case, you should use the small caps font when the word refers to the second and subsequent elements of a list (the CDR of the list), but you should use `@code' when the word refers to the Lisp function of the same spelling.

Fonts for Printing, Not Info

Texinfo provides four font commands that specify font changes in the printed manual but have no effect in the Info file. @i requests italic font (in some versions of TeX, a slanted font is used), @b requests bold face, @t requests the fixed-width, typewriter-style font used by @code, and @r requests a roman font, which is the usual font in which text is printed. All four commands apply to an argument that follows, surrounded by braces.

Only the @r command has much use: in example programs, you can use the @r command to convert code comments from the fixed-width font to a roman font. This looks better in printed output.

For example,

@lisp
(+ 2 2)    ; @r{Add two plus two.}
@end lisp

produces

(+ 2 2)    ; Add two plus two.

If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo language.

Customized Highlighting

You can use regular TeX commands inside of @iftex ... @end iftex to create your own customized highlighting commands for Texinfo. The easiest way to do this is to equate your customized commands with pre-existing commands, such as those for italics. Such new commands work only with TeX.

You can use the @definfoenclose command inside of @ifinfo ... @end ifinfo to define commands for Info with the same names as new commands for TeX. @definfoenclose creates new commands for Info that mark text by enclosing it in strings that precede and follow the text. (7)

Here is how to create a new @-command called @phoo that causes TeX to typeset its argument in italics and causes Info to display the argument between `//' and `\\'.

For TeX, write the following to equate the @phoo command with the existing @i italics command:

@iftex
@global@let@phoo=@i
@end iftex

This defines @phoo as a command that causes TeX to typeset the argument to @phoo in italics. @global@let tells TeX to equate the next argument with the argument that follows the equals sign.

For Info, write the following to tell the Info formatters to enclose the argument between `//' and `\\':

@ifinfo
@definfoenclose phoo, //, \\
@end ifinfo

Write the @definfoenclose command on a line and follow it with three arguments separated by commas (commas are used as separators in an @node line in the same way).

  • The first argument to @definfoenclose is the @-command name without the `@';
  • the second argument is the Info start delimiter string; and,
  • the third argument is the Info end delimiter string.

The latter two arguments enclose the highlighted text in the Info file. A delimiter string may contain spaces. Neither the start nor end delimiter is required. However, if you do not provide a start delimiter, you must follow the command name with two commas in a row; otherwise, the Info formatting commands will misinterpret the end delimiter string as a start delimiter string.

After you have defined @phoo both for TeX and for Info, you can then write @phoo{bar} to see `//bar\\' in Info and see bar in italics in printed output.

Note that each definition applies to its own formatter: one for TeX, the other for Info.

Here is another example:

@ifinfo
@definfoenclose headword, , :
@end ifinfo
@iftex
@global@let@headword=@b
@end iftex

This defines @headword as an Info formatting command that inserts nothing before and a colon after the argument and as a TeX formatting command to typeset its argument in bold.

Quotations and Examples

Quotations and examples are blocks of text consisting of one or more whole paragraphs that are set off from the bulk of the text and treated differently. They are usually indented.

In Texinfo, you always begin a quotation or example by writing an @-command at the beginning of a line by itself, and end it by writing an @end command that is also at the beginning of a line by itself. For instance, you begin an example by writing @example by itself at the beginning of a line and end the example by writing @end example on a line by itself, at the beginning of that line.

The Block Enclosing Commands

Here are commands for quotations and examples:

@quotation
Indicate text that is quoted. The text is filled, indented, and printed in a roman font by default.
@example
Illustrate code, commands, and the like. The text is printed in a fixed-width font, and indented but not filled.
@lisp
Illustrate Lisp code. The text is printed in a fixed-width font, and indented but not filled.
@smallexample
Illustrate code, commands, and the like. Similar to @example, except that in TeX this command typesets text in a smaller font for the smaller @smallbook format than for the 8.5 by 11 inch format.
@smalllisp
Illustrate Lisp code. Similar to @lisp, except that in TeX this command typesets text in a smaller font for the smaller @smallbook format than for the 8.5 by 11 inch format.
@display
Display illustrative text. The text is indented but not filled, and no font is specified (so, by default, the font is roman).
@format
Print illustrative text. The text is not indented and not filled and no font is specified (so, by default, the font is roman).

The @exdent command is used within the above constructs to undo the indentation of a line.

The @flushleft and @flushright commands are used to line up the left or right margins of unfilled text.

The @noindent command may be used after one of the above constructs to prevent the following text from being indented as a new paragraph.

You can use the @cartouche command within one of the above constructs to highlight the example or quotation by drawing a box with rounded corners around it. (The @cartouche command affects only the printed manual; it has no effect in the Info file; see section Drawing Cartouches Around Examples.)

@quotation

The text of a quotation is processed normally except that:

  • the margins are closer to the center of the page, so the whole of the quotation is indented;
  • the first lines of paragraphs are indented no more than other lines;
  • in the printed output, interparagraph spacing is reduced.

This is an example of text written between an @quotation command and an @end quotation command. An @quotation command is most often used to indicate text that is excerpted from another (real or hypothetical) printed work.

Write an @quotation command as text on a line by itself. This line will disappear from the output. Mark the end of the quotation with a line beginning with and containing only @end quotation. The @end quotation line will likewise disappear from the output. Thus, the following,

@quotation
This is
a foo.
@end quotation

produces

This is a foo.

@example

The @example command is used to indicate an example that is not part of the running text, such as computer input or output.

This is an example of text written between an
@example command
and an @end example command.
The text is indented but not filled.

In the printed manual, the text is typeset in a
fixed-width font, and extra spaces and blank lines are
significant.  In the Info file, an analogous result is
obtained by indenting each line with five spaces.

Write an @example command at the beginning of a line by itself. This line will disappear from the output. Mark the end of the example with an @end example command, also written at the beginning of a line by itself. The @end example will disappear from the output.

For example,

@example
mv foo bar
@end example

produces

mv foo bar

Since the lines containing @example and @end example will disappear, you should put a blank line before the @example and another blank line after the @end example. (Remember that blank lines between the beginning @example and the ending @end example will appear in the output.)

Caution: Do not use tabs in the lines of an example (or anywhere else in Texinfo, for that matter)! TeX treats tabs as single spaces, and that is not what they look like. This is a problem with TeX. (If necessary, in Emacs, you can use M-x untabify to convert tabs in a region to multiple spaces.)

Examples are often, logically speaking, "in the middle" of a paragraph, and the text continues after an example should not be indented. The @noindent command prevents a piece of text from being indented as if it were a new paragraph.

(The @code command is used for examples of code that are embedded within sentences, not set off from preceding and following text. See section @code{sample-code}.)

@noindent

An example or other inclusion can break a paragraph into segments. Ordinarily, the formatters indent text that follows an example as a new paragraph. However, you can prevent this by writing @noindent at the beginning of a line by itself preceding the continuation text.

For example:

@example
This is an example
@end example

@noindent
This line is not indented.  As you can see, the
beginning of the line is fully flush left with the line
that follows after it.  (This whole example is between
@code{@@display} and @code{@@end display}.)

produces

This is an example

This line is not indented.  As you can see, the
beginning of the line is fully flush left with the line
that follows after it.  (This whole example is between
@display and @end display.)

To adjust the number of blank lines properly in the Info file output, remember that the line containing @noindent does not generate a blank line, and neither does the @end example line.

In the Texinfo source file for this manual, each line that says `produces' is preceded by a line containing @noindent.

Do not put braces after an @noindent command; they are not necessary, since @noindent is a command used outside of paragraphs (see section @-Command Syntax).

@lisp

The @lisp command is used for Lisp code. It is synonymous with the @example command.

This is an example of text written between an
@lisp command and an @end lisp command.

Use @lisp instead of @example so as to preserve information regarding the nature of the example. This is useful, for example, if you write a function that evaluates only and all the Lisp code in a Texinfo file. Then you can use the Texinfo file as a Lisp library.(8)

Mark the end of @lisp with @end lisp on a line by itself.

@smallexample and @smalllisp

In addition to the regular @example and @lisp commands, Texinfo has two other "example-style" commands. These are the @smallexample and @smalllisp commands. Both these commands are designed for use with the @smallbook command that causes TeX to produce a printed manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format.

In TeX, the @smallexample and @smalllisp commands typeset text in a smaller font for the smaller @smallbook format than for the 8.5 by 11 inch format. Consequently, many examples containing long lines fit in a narrower, @smallbook page without needing to be shortened. Both commands typeset in the normal font size when you format for the 8.5 by 11 inch size; indeed, in this situation, the @smallexample and @smalllisp commands are defined to be the @example and @lisp commands.

In Info, the @smallexample and @smalllisp commands are equivalent to the @example and @lisp commands, and work exactly the same.

Mark the end of @smallexample or @smalllisp with @end smallexample or @end smalllisp, respectively.

Here is an example written in the small font used by the @smallexample and @smalllisp commands:

This is an example of text written between @smallexample and
@end smallexample.  In Info and in an 8.5 by 11 inch manual,
this text appears in its normal size; but in a 7 by 9.25 inch manual,
this text appears in a smaller font.

The @smallexample and @smalllisp commands make it easier to prepare smaller format manuals without forcing you to edit examples by hand to fit them onto narrower pages.

As a general rule, a printed document looks better if you write all the examples in a chapter consistently in @example or in @smallexample. Only occasionally should you mix the two formats.

See section Printing "Small" Books, for more information about the @smallbook command.

@display

The @display command begins a kind of example. It is like the @example command except that, in a printed manual, @display does not select the fixed-width font. In fact, it does not specify the font at all, so that the text appears in the same font it would have appeared in without the @display command.

This is an example of text written between an @display command
and an @end display command.  The @display command
indents the text, but does not fill it.

@format

The @format command is similar to @example except that, in the printed manual, @format does not select the fixed-width font and does not narrow the margins.

This is an example of text written between an @format command
and an @end format command.  As you can see
from this example,
the @format command does not fill the text.

@exdent: Undoing a Line's Indentation

The @exdent command removes any indentation a line might have. The command is written at the beginning of a line and applies only to the text that follows the command that is on the same line. Do not use braces around the text. In a printed manual, the text on an @exdent line is printed in the roman font.

@exdent is usually used within examples. Thus,

@example
This line follows an @@example command.
@exdent This line is exdented.
This line follows the exdented line.
The @@end example comes on the next line.
@end group

produces

This line follows an @example command.
This line is exdented.
This line follows the exdented line.
The @end example comes on the next line.

In practice, the @exdent command is rarely used. Usually, you un-indent text by ending the example and returning the page to its normal width.

@flushleft and @flushright

The @flushleft and @flushright commands line up the ends of lines on the left and right margins of a page, but do not fill the text. The commands are written on lines of their own, without braces. The @flushleft and @flushright commands are ended by @end flushleft and @end flushright commands on lines of their own.

For example,

@flushleft
This text is
written flushleft.
@end flushleft

produces

This text is
written flushleft.

Flushright produces the type of indentation often used in the return address of letters.

For example,

@flushright
Here is an example of text written
flushright.  The @code{@flushright} command
right justifies every line but leaves the
left end ragged.
@end flushright

produces

Here is an example of text written
flushright.  The @flushright command
right justifies every line but leaves the
left end ragged.

Drawing Cartouches Around Examples

In a printed manual, the @cartouche command draws a box with rounded corners around its contents. You can use this command to further highlight an example or quotation. For instance, you could write a manual in which one type of example is surrounded by a cartouche for emphasis.

The @cartouche command affects only the printed manual; it has no effect in the Info file.

For example,

@example
@cartouche
% pwd
/usr/local/lib/emacs/info
@end cartouche
@end example

surrounds the two-line example with a box with rounded corners, in the printed manual.

In a printed manual, the example looks like this:

% pwd
/usr/local/lib/emacs/info

Making Lists and Tables

Texinfo has several ways of making lists and two-column tables. Lists can be bulleted or numbered, while two-column tables can highlight the items in the first column.

Texinfo automatically indents the text in lists or tables, and numbers an enumerated list. This last feature is useful if you modify the list, since you do not need to renumber it yourself.

Numbered lists and tables begin with the appropriate @-command at the beginning of a line, and end with the corresponding @end command on a line by itself. The table and itemized-list commands also require that you write formatting information on the same line as the beginning @-command.

Begin an enumerated list, for example, with an @enumerate command and end the list with an @end enumerate command. Begin an itemized list with an @itemize command, followed on the same line by a formatting command such as @bullet, and end the list with an @end itemize command.

Precede each element of a list with an @item or @itemx command.

Here is an itemized list of the different kinds of table and lists:

  • Itemized lists with and without bullets.
  • Enumerated lists, using numbers or letters.
  • Two-column tables with highlighting.

Here is an enumerated list with the same items:

  1. Itemized lists with and without bullets.
  2. Enumerated lists, using numbers or letters.
  3. Two-column tables with highlighting.

And here is a two-column table with the same items and their @-commands:

@itemize
Itemized lists with and without bullets.
@enumerate
Enumerated lists, using numbers or letters.
@table
@ftable
@vtable
Two-column tables with indexing.

Making an Itemized List

The @itemize command produces sequences of indented paragraphs, with a bullet or other mark inside the left margin at the beginning of each paragraph for which such a mark is desired.

Begin an itemized list by writing @itemize at the beginning of a line. Follow the command, on the same line, with a character or a Texinfo command that generates a mark. Usually, you will write @bullet after @itemize, but you can use @minus, or any character or any special symbol that results in a single character in the Info file. (When you write @bullet or @minus after an @itemize command, you may omit the `{}'.)

Write the text of the indented paragraphs themselves after the @itemize, up to another line that says @end itemize.

Before each paragraph for which a mark in the margin is desired, write a line that says just @item. Do not write any other text on this line.

Usually, you should put a blank line before an @item. This puts a blank line in the Info file. (TeX inserts the proper interline whitespace in either case.) Except when the entries are very brief, these blank lines make the list look better.

Here is an example of the use of @itemize, followed by the output it produces. Note that @bullet produces an `*' in Info and a round dot in TeX.

@itemize @bullet
@item
Some text for foo.

@item
Some text
for bar.
@end itemize

This produces:

  • Some text for foo.
  • Some text for bar.

Itemized lists may be embedded within other itemized lists. Here is a list marked with dashes embedded in a list marked with bullets:

@itemize @bullet
@item
First item.

@itemize @minus
@item
Inner item.

@item
Second inner item.
@end itemize

@item
Second outer item.
@end itemize

This produces:

  • First item.
    • Inner item.
    • Second inner item.
  • Second outer item.

Making a Numbered or Lettered List

@enumerate is like @itemize except that the marks in the left margin contain successive integers or letters. (See section Making an Itemized List.)

Write the @enumerate command at the beginning of a line. The command does not require an argument, but accepts either a number or a letter as an option. Without an argument, @enumerate starts the list with the number 1. With a numeric argument, such as 3, the command starts the list with that number. With an upper or lower case letter, such as a or A, the command starts the list with that letter.

Write the text of the enumerated list in the same way you write an itemized list: put @item on a line of its own before the start of each paragraph that you want enumerated. Do not write any other text on the line beginning with @item.

You should put a blank line between entries in the list. This generally makes it easier to read the Info file.

Here is an example of @enumerate without an argument:

@enumerate
@item
Underlying causes.

@item
Proximate causes.
@end enumerate

This produces:

  1. Underlying causes.
  2. Proximate causes.

Here is an example with an argument of 3:

@enumerate 3
@item
Predisposing causes.

@item
Precipitating causes.

@item
Perpetuating causes.
@end enumerate

This produces:

  1. Predisposing causes.
  2. Precipitating causes.
  3. Perpetuating causes.

Here is a brief summary of the alternatives. The summary is constructed using @enumerate with an argument of a.

  1. @enumerate Without an argument, produce a numbered list, starting with the number 1.
  2. @enumerate positive-integer With a (positive) numeric argument, start a numbered list with that number. You can use this to continue a list that you interrupted with other text.
  3. @enumerate upper-case-letter With an upper case letter as argument, start a list in which each item is marked by a letter, beginning with that upper case letter.
  4. @enumerate lower-case-letter With a lower case letter as argument, start a list in which each item is marked by a letter, beginning with that lower case letter.

You can also nest enumerated lists, as in an outline.

Making a Two-column Table

@table is similar to @itemize, but the command allows you to specify a name or heading line for each item. (See section Making an Itemized List.) The @table command is used to produce two-column tables, and is especially useful for glossaries and explanatory exhibits.

Write the @table command at the beginning of a line and follow it on the same line with an argument that is a Texinfo command such as @code, @samp, @var, or @kbd. Although these commands are usually followed by arguments in braces, in this case you use the command name without an argument because @item will supply the argument. This command will be applied to the text that goes into the first column of each item and determines how it will be highlighted. For example, @samp will cause the text in the first column to be highlighted with an @samp command.

You may also choose to use the @asis command as an argument to @table. @asis is a command that does nothing; if you use this command after @table, TeX and the Info formatting commands output the first column entries without added highlighting (`as is').

(The @table command may work with other commands besides those listed here. However, you can only use commands that normally take arguments in braces.)

Begin each table entry with an @item command at the beginning of a line. Write the first column text on the same line as the @item command. Write the second column text on the line following the @item line and on subsequent lines. (You do not need to type anything for an empty second column entry.) You may write as many lines of supporting text as you wish, even several paragraphs. But only text on the same line as the @item will be placed in the first column.

Normally, you should put a blank line before an @item line. This puts a blank like in the Info file. Except when the entries are very brief, a blank line looks better.

The following table, for example, highlights the text in the first column with an @samp command:

@table @samp
@item foo
This is the text for
@samp{foo}.

@item bar
Text for @samp{bar}.
@end table

This produces:

`foo'
This is the text for `foo'.
`bar'
Text for `bar'.

If you want to list two or more named items with a single block of text, use the @itemx command. (See section @itemx.)

@ftable and @vtable

The @ftable and @vtable commands are the same as the @table command except that @ftable automatically enters each of the items in the first column of the table into the index of functions and @vtable automatically enters each of the items in the first column of the table into the index of variables. This simplifies the task of creating indices. Only the items on the same line as the @item commands are indexed, and they are indexed in exactly the form that they appear on that line. See section Creating Indices, for more information about indices.

Begin a two-column table using @ftable or @vtable by writing the @-command at the beginning of a line, followed on the same line by an argument that is a Texinfo command such as @code, exactly as you would for an @table command; and end the table with an @end ftable or @end vtable command on a line by itself.

See the example for @table in the previous section.

@itemx

Use the @itemx command inside a table when you have two or more first column entries for the same item, each of which should appear on a line of its own. Use @itemx for all but the first entry. The @itemx command works exactly like @item except that it does not generate extra vertical space above the first column text.

For example,

@table @code
@item upcase
@itemx downcase
These two functions accept a character or a string as
argument, and return the corresponding upper case (lower
case) character or string.
@end table

This produces:

upcase
downcase
These two functions accept a character or a string as argument, and return the corresponding upper case (lower case) character or string.

(Note also that this example illustrates multi-line supporting text in a two-column table.)

Multi-column Tables

@multitable allows you to construct tables with any number of columns, with each column having any width you like.

You define the column widths on the @multitable line itself, and write each row of the actual table following an @item command, with columns separated by an @tab command. Finally, @end multitable completes the table. Details in the sections below.

Multitable Column Widths

You can define the column widths for a multitable in two ways: as fractions of the line length; or with a prototype row. Mixing the two methods is not supported. In either case, the widths are defined entirely on the same line as the @multitable command.

  1. To specify column widths as fractions of the line length, write @columnfractions and the decimal numbers (presumably less than 1) after the @multitable command, as in:
    @multitable @columnfractions .33 .33 .33
    The fractions need not add up exactly to 1.0, as these do not. This allows you to produce tables that do not need the full line length.
  2. To specify a prototype row, write the longest entry for each column enclosed in braces after the @multitable command. For example:
    @multitable {some text for column one} {for column two}
    The first column will then have the width of the typeset `some text for column one', and the second column the width of `for column two'. The prototype entries need not appear in the table itself. Although we used simple text in this example, the prototype entries can contain Texinfo commands; markup commands such as @code are particularly likely to be useful.

Multitable Rows

After the @multitable command defining the column widths (see the previous section), you begin each row in the body of a multitable with @item, and separate the column entries with @tab. Line breaks are not special within the table body, and you may break input lines in your source file as necessary.

Here is a complete example of a multi-column table (the text is from the GNU Emacs manual):

@multitable @columnfractions .15 .45 .4
@item Key @tab Command @tab Description
@item C-x 2
@tab @code{split-window-vertically}
@tab Split the selected window into two windows,
with one above the other.
@item C-x 3
@tab @code{split-window-horizontally}
@tab Split the selected window into two windows
positioned side by side.
@item C-Mouse-2
@tab
@tab In the mode line or scroll bar of a window,
split that window.
@end multitable

produces:

with one above the other. positioned side by side. split that window.
Key @tab Command @tab Description
C-x 2 | split-window-vertically | Split the selected window into two windows,
C-x 3 | split-window-horizontally | Split the selected window into two windows
C-Mouse-2 |  | In the mode line or scroll bar of a window,

Creating Indices

Using Texinfo, you can generate indices without having to sort and collate entries manually. In an index, the entries are listed in alphabetical order, together with information on how to find the discussion of each entry. In a printed manual, this information consists of page numbers. In an Info file, this information is a menu entry leading to the first node referenced.

Texinfo provides several predefined kinds of index: an index for functions, an index for variables, an index for concepts, and so on. You can combine indices or use them for other than their canonical purpose. If you wish, you can define your own indices.

Making Index Entries

When you are making index entries, it is good practice to think of the different ways people may look for something. Different people do not think of the same words when they look something up. A helpful index will have items indexed under all the different words that people may use. For example, one reader may think it obvious that the two-letter names for indices should be listed under "Indices, two-letter names", since the word "Index" is the general concept. But another reader may remember the specific concept of two-letter names and search for the entry listed as "Two letter names for indices". A good index will have both entries and will help both readers.

Like typesetting, the construction of an index is a highly skilled, professional art, the subtleties of which are not appreciated until you need to do it yourself.

See section Index Menus and Printing an Index, for information about printing an index at the end of a book or creating an index menu in an Info file.

Predefined Indices

Texinfo provides six predefined indices:

  • A concept index listing concepts that are discussed.
  • A function index listing functions (such as entry points of libraries).
  • A variables index listing variables (such as global variables of libraries).
  • A keystroke index listing keyboard commands.
  • A program index listing names of programs.
  • A data type index listing data types (such as structures defined in header files).

Not every manual needs all of these, and most manuals use two or three of them. This manual has two indices: a concept index and an @-command index (that is actually the function index but is called a command index in the chapter heading). Two or more indices can be combined into one using the @synindex or @syncodeindex commands. See section Combining Indices.

Defining the Entries of an Index

The data to make an index come from many individual indexing commands scattered throughout the Texinfo source file. Each command says to add one entry to a particular index; after formatting, the index will give the current page number or node name as the reference.

An index entry consists of an indexing command at the beginning of a line followed, on the rest of the line, by the entry.

For example, this section begins with the following five entries for the concept index:

@cindex Defining indexing entries
@cindex Index entries
@cindex Entries for an index
@cindex Specifying index entries
@cindex Creating index entries

Each predefined index has its own indexing command---@cindex for the concept index, @findex for the function index, and so on.

Concept index entries consist of text. The best way to write an index is to choose entries that are terse yet clear. If you can do this, the index often looks better if the entries are not capitalized, but written just as they would appear in the middle of a sentence. (Capitalize proper names and acronyms that always call for upper case letters.) This is the case convention we use in most GNU manuals' indices.

If you don't see how to make an entry terse yet clear, make it longer and clear--not terse and confusing. If many of the entries are several words long, the index may look better if you use a different convention: to capitalize the first word of each entry. But do not capitalize a case-sensitive name such as a C or Lisp function name or a shell command; that would be a spelling error.

Whichever case convention you use, please use it consistently!

Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so use upper and lower case as required for them.

By default, entries for a concept index are printed in a small roman font and entries for the other indices are printed in a small @code font. You may change the way part of an entry is printed with the usual Texinfo commands, such as @file for file names and @emph for emphasis (see section Marking Words and Phrases).

The six indexing commands for predefined indices are:

@cindex concept
Make an entry in the concept index for concept.
@findex function
Make an entry in the function index for function.
@vindex variable
Make an entry in the variable index for variable.
@kindex keystroke
Make an entry in the key index for keystroke.
@pindex program
Make an entry in the program index for program.
@tindex data type
Make an entry in the data type index for data type.

Caution: Do not use a colon in an index entry. In Info, a colon separates the menu entry name from the node name. An extra colon confuses Info. See section The Parts of a Menu, for more information about the structure of a menu entry.

If you write several identical index entries in different places in a Texinfo file, the index in the printed manual will list all the pages to which those entries refer. However, the index in the Info file will list only the node that references the first of those index entries. Therefore, it is best to write indices in which each entry refers to only one place in the Texinfo file. Fortunately, this constraint is a feature rather than a loss since it means that the index will be easy to use. Otherwise, you could create an index that lists several pages for one entry and your reader would not know to which page to turn. If you have two identical entries for one topic, change the topics slightly, or qualify them to indicate the difference.

You are not actually required to use the predefined indices for their canonical purposes. For example, suppose you wish to index some C preprocessor macros. You could put them in the function index along with actual functions, just by writing @findex commands for them; then, when you print the "Function Index" as an unnumbered chapter, you could give it the title `Function and Macro Index' and all will be consistent for the reader. Or you could put the macros in with the data types by writing @tindex commands for them, and give that index a suitable title so the reader will understand. (See section Index Menus and Printing an Index.)

Combining Indices

Sometimes you will want to combine two disparate indices such as functions and concepts, perhaps because you have few enough of one of them that a separate index for them would look silly.

You could put functions into the concept index by writing @cindex commands for them instead of @findex commands, and produce a consistent manual by printing the concept index with the title `Function and Concept Index' and not printing the `Function Index' at all; but this is not a robust procedure. It works only if your document is never included as part of another document that is designed to have a separate function index; if your document were to be included with such a document, the functions from your document and those from the other would not end up together. Also, to make your function names appear in the right font in the concept index, you would need to enclose every one of them between the braces of @code.

@syncodeindex

When you want to combine functions and concepts into one index, you should index the functions with @findex and index the concepts with @cindex, and use the @syncodeindex command to redirect the function index entries into the concept index.

The @syncodeindex command takes two arguments; they are the name of the index to redirect, and the name of the index to redirect it to. The template looks like this:

@syncodeindex from to

For this purpose, the indices are given two-letter names:

`cp'
concept index
`fn'
function index
`vr'
variable index
`ky'
key index
`pg'
program index
`tp'
data type index

Write an @syncodeindex command before or shortly after the end-of-header line at the beginning of a Texinfo file. For example, to merge a function index with a concept index, write the following:

@syncodeindex fn cp

This will cause all entries designated for the function index to merge in with the concept index instead.

To merge both a variables index and a function index into a concept index, write the following:

@syncodeindex vr cp
@syncodeindex fn cp

The @syncodeindex command puts all the entries from the `from' index (the redirected index) into the @code font, overriding whatever default font is used by the index to which the entries are now directed. This way, if you direct function names from a function index into a concept index, all the function names are printed in the @code font as you would expect.

@synindex

The @synindex command is nearly the same as the @syncodeindex command, except that it does not put the `from' index entries into the @code font; rather it puts them in the roman font. Thus, you use @synindex when you merge a concept index into a function index.

See section Index Menus and Printing an Index, for information about printing an index at the end of a book or creating an index menu in an Info file.

Defining New Indices

In addition to the predefined indices, you may use the @defindex and @defcodeindex commands to define new indices. These commands create new indexing @-commands with which you mark index entries. The @defindex command is used like this:

@defindex name

The name of an index should be a two letter word, such as `au'. For example:

@defindex au

This defines a new index, called the `au' index. At the same time, it creates a new indexing command, @auindex, that you can use to make index entries. Use the new indexing command just as you would use a predefined indexing command.

For example, here is a section heading followed by a concept index entry and two `au' index entries.

@section Cognitive Semantics
@cindex kinesthetic image schemas
@auindex Johnson, Mark
@auindex Lakoff, George

(Evidently, `au' serves here as an abbreviation for "author".) Texinfo constructs the new indexing command by concatenating the name of the index with `index'; thus, defining an `au' index leads to the automatic creation of an @auindex command.

Use the @printindex command to print the index, as you do with the predefined indices. For example:

@node Author Index, Subject Index, , Top
@unnumbered Author Index

@printindex au

The @defcodeindex is like the @defindex command, except that, in the printed output, it prints entries in an @code font instead of a roman font. Thus, it parallels the @findex command rather than the @cindex command.

You should define new indices within or right after the end-of-header line of a Texinfo file, before any @synindex or @syncodeindex commands (see section The Texinfo File Header).

Special Insertions

Texinfo provides several commands for formatting dimensions, for inserting single characters that have special meaning in Texinfo, such as braces, and for inserting special graphic symbols that do not correspond to characters, such as dots and bullets.

These are:

  • Braces, `@' and periods.
  • Format a dimension, such as `12pt'.
  • Dots and bullets.
  • The TeX logo and the copyright symbol.
  • A minus sign.

Inserting @ and Braces

`@' and curly braces are special characters in Texinfo. To insert these characters so they appear in text, you must put an `@' in front of these characters to prevent Texinfo from misinterpreting them.

Do not put braces after any of these commands; they are not necessary.

Inserting `@' with @@

@@ stands for a single `@' in either printed or Info output.

Do not put braces after an @@ command.

Inserting `{' and `}'with @{ and @}

@{ stands for a single `{' in either printed or Info output.

@} stands for a single `}' in either printed or Info output.

Do not put braces after either an @{ or an @} command.

Inserting Space

The following sections describe commands that control spacing of various kinds within and after sentences.

Not Ending a Sentence

Depending on whether a period or exclamation point or question mark is inside or at the end of a sentence, less or more space is inserted after a period in a typeset manual. Since it is not always possible for Texinfo to determine when a period ends a sentence and when it is used in an abbreviation, special commands are needed in some circumstances. (Usually, Texinfo can guess how to handle periods, so you do not need to use the special commands; you just enter a period as you would if you were using a typewriter, which means you put two spaces after the period, question mark, or exclamation mark that ends a sentence.)

Use the @: command after a period, question mark, exclamation mark, or colon that should not be followed by extra space. For example, use @: after periods that end abbreviations which are not at the ends of sentences. @: has no effect on the Info file output.

For example,

The s.o.p.@: has three parts ...
The s.o.p. has three parts ...

produces the following. If you look carefully at this printed output, you will see a little more whitespace after `s.o.p.' in the second line.

The s.o.p. has three parts ...
The s.o.p. has three parts ...

@: has no effect on the Info output. (`s.o.p.' is an abbreviation for "Standard Operating Procedure".)

Do not put braces after @:.

Ending a Sentence

Use @. instead of a period, @! instead of an exclamation point, and @? instead of a question mark at the end of a sentence that ends with a single capital letter. Otherwise, TeX will think the letter is an abbreviation and will not insert the correct end-of-sentence spacing. Here is an example:

Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

produces the following. If you look carefully at this printed output, you will see a little more whitespace after the `W' in the first line.

Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.

In the Info file output, @. is equivalent to a simple `.'; likewise for @! and @?.

The meanings of @: and @. in Texinfo are designed to work well with the Emacs sentence motion commands (see section `Sentences' in GNU Emacs). This made it necessary for them to be incompatible with some other formatting systems that use @-commands.

Do not put braces after any of these commands.

Multiple Spaces

Ordinarily, TeX collapses multiple whitespace characters (space, tab, and newline) into a single space. (Info output, on the other hand, preserves whitespace as you type it, except for changing a newline into a space; this is why it is important to put two spaces at the end of sentences in Texinfo documents.)

Occasionally, you may want to actually insert several consecutive spaces, either for purposes of example (what your program does with multiple spaces as input), or merely for purposes of appearance in headings or lists. Texinfo supports three commands: @ , @TAB, and @NL, all of which insert a single space into the output. (Here, TAB and NL represent the tab character and end-of-line, i.e., when `@' is the last character on a line.)

For example,

Spacey@ @ @ @
example.

produces

Spacey
example.

Other possible uses of @ have been subsumed by @multitable (see section Multi-column Tables).

Do not follow any of these commands with braces.

@dmn{dimension}: Format a Dimension

At times, you may want to write `12pt' or `8.5in' with little or no space between the number and the abbreviation for the dimension. You can use the @dmn command to do this. On seeing the command, TeX inserts just enough space for proper typesetting; the Info formatting commands insert no space at all, since the Info file does not require it.

To use the @dmn command, write the number and then follow it immediately, with no intervening space, by @dmn, and then by the dimension within braces.

For example,

A4 paper is 8.27@dmn{in} wide.

produces

A4 paper is 8.27in wide.

Not everyone uses this style. Instead of writing `8.27@dmn{in}' in the Texinfo file, you may write `8.27 in.' or `8.27 inches'. (In these cases, the formatters may insert a line break between the number and the dimension. Also, if you write a period after an abbreviation within a sentence, you should write `@:' after the period to prevent TeX from inserting extra whitespace. See section Inserting Space.

Inserting Accents

Here is a table with the commands Texinfo provides for inserting floating accents. The commands with non-alphabetic names do not take braces around their argument (which is taken to be the next character). (Exception: @, does take braces around its argument.) This is so as to make the source as convenient to type and read as possible, since accented characters are very common in some languages.

  • Command @tab Output @tab What
  • @"o @tab @"o @tab umlaut accent
  • @'o @tab 'o @tab acute accent
  • @,{c} @tab @,{c} @tab cedilla accent
  • @=o @tab @=o @tab macron/overbar accent
  • @^o @tab @^o @tab circumflex accent
  • @`o @tab `o @tab grave accent
  • @~o @tab @~o @tab tilde accent
  • @dotaccent{o} @tab @dotaccent{o} @tab overdot accent
  • @H{o} @tab @H{o} @tab long Hungarian umlaut
  • @ringaccent{o} @tab @ringaccent{o} @tab ring accent
  • @tieaccent{oo} @tab @tieaccent{oo} @tab tie-after accent
  • @u{o} @tab @u{o} @tab breve accent
  • @ubaraccent{o} @tab @ubaraccent{o} @tab underbar accent
  • @udotaccent{o} @tab @udotaccent{o} @tab underdot accent
  • @v{o} @tab @v{o} @tab hacek or check accent This table lists the Texinfo commands for inserting other characters commonly used in languages other than English.
  • @exclamdown{} @tab @exclamdown{} @tab upside-down !
  • @questiondown{} @tab @questiondown{} @tab upside-down ?
  • @aa{},@AA{} @tab @aa{},@AA{} @tab A,a with circle
  • @ae{},@AE{} @tab @ae{},@AE{} @tab ae,AE ligatures
  • @dotless{i} @tab @dotless{i} @tab dotless i
  • @dotless{j} @tab @dotless{j} @tab dotless j
  • @l{},@L{} @tab @l{},@L{} @tab suppressed-L,l
  • @o{},@O{} @tab @o{},@O{} @tab O,o with slash
  • @oe{},@OE{} @tab @oe{},@OE{} @tab OE,oe ligatures
  • @ss{} @tab @ss{} @tab es-zet or sharp S

    Inserting Ellipsis, Dots, and Bullets

    An ellipsis (a line of dots) is not typeset as a string of periods, so a special command is used for ellipsis in Texinfo. The @bullet command is special, too. Each of these commands is followed by a pair of braces, `{}', without any whitespace between the name of the command and the braces. (You need to use braces with these commands because you can use them next to other text; without the braces, the formatters would be confused. See section @-Command Syntax, for further information.)

    @dots{}

    Use the @dots{} command to generate an ellipsis, which is three dots in a row, appropriately spaced, like this: `...'. Do not simply write three periods in the input file; that would work for the Info file output, but would produce the wrong amount of space between the periods in the printed manual.

    Similarly, the @enddots{} command generates an end-of-sentence ellipsis (four dots) @enddots{}

    Here is an ellipsis: ... Here are three periods in a row: ...

    In printed output, the three periods in a row are closer together than the dots in the ellipsis.

    @bullet{}

    Use the @bullet{} command to generate a large round dot, or the closest possible thing to one. In Info, an asterisk is used.

    Here is a bullet: *

    When you use @bullet in @itemize, you do not need to type the braces, because @itemize supplies them. (See section Making an Itemized List.)

    Inserting TeX and the Copyright Symbol

    The logo `TeX' is typeset in a special fashion and it needs an @-command. The copyright symbol, `(C)', is also special. Each of these commands is followed by a pair of braces, `{}', without any whitespace between the name of the command and the braces.

    @TeX{}

    Use the @TeX{} command to generate `TeX'. In a printed manual, this is a special logo that is different from three ordinary letters. In Info, it just looks like `TeX'. The @TeX{} command is unique among Texinfo commands in that the T and the X are in upper case.

    @copyright{}

    Use the @copyright{} command to generate `(C)'. In a printed manual, this is a `c' inside a circle, and in Info, this is `(C)'.

    @pounds{}

    Use the @pounds{} command to generate `@pounds{}'. In a printed manual, this is the symbol for the currency pounds sterling. In Info, it is a `#'. Other currency symbols are unfortunately not available.

    @minus{}: Inserting a Minus Sign

    Use the @minus{} command to generate a minus sign. In a fixed-width font, this is a single hyphen, but in a proportional font, the symbol is the customary length for a minus sign--a little longer than a hyphen.

    You can compare the two forms:

    `-' is a minus sign generated with `@minus{}',

`-' is a hyphen generated with the character `-'.

    In the fixed-width font used by Info, @minus{} is the same as a hyphen.

    You should not use @minus{} inside @code or @example because the width distinction is not made in the fixed-width font they use.

    When you use @minus to specify the mark beginning each entry in an itemized list, you do not need to type the braces (see section Making an Itemized List.)

    @math: Inserting Mathematical Expressions

    You can write a short mathematical expression with the @math command. Write the mathematical expression between braces, like this:

    @math{(a + b)(a + b) = a^2 + 2ab + b^2}

    This produces the following in TeX:

    (a + b)(a + b) = a^2 + 2ab + b^2

    and the following in Info:

    (a + b)(a + b) = a^2 + 2ab + b^2

    The @math command has no effect on the Info output. Currently, it has limited effect on typeset output. However, this may change since TeX itself is designed for mathematical typesetting and does a splendid job.

    Certainly, for complex mathematical expressions, you could use TeX directly. See section Using Ordinary TeX Commands. When you use TeX directly, remember to write the mathematical expression between one or two `$' (dollar-signs) as appropriate.

    Glyphs for Examples

    In Texinfo, code is often illustrated in examples that are delimited by @example and @end example, or by @lisp and @end lisp. In such examples, you can indicate the results of evaluation or an expansion using `=>' or `==>'. Likewise, there are commands to insert glyphs to indicate printed output, error messages, equivalence of expressions, and the location of point.

    The glyph-insertion commands do not need to be used within an example, but most often they are. Every glyph-insertion command is followed by a pair of left- and right-hand braces.

    =>
    @result{} points to the result of an expression.
    ==>
    @expansion{} shows the results of a macro expansion.
    -|
    @print{} indicates printed output.
    error-->
    @error{} indicates that the following text is an error message.
    ==
    @equiv{} indicates the exact equivalence of two forms.
    -!-
    @point{} shows the location of point.

    =>: Indicating Evaluation

    Use the @result{} command to indicate the result of evaluating an expression.

    The @result{} command is displayed as `=>' in Info and as `=>' in the printed output.

    Thus, the following,

    (cdr '(1 2 3))
     => (2 3)

    may be read as "(cdr '(1 2 3)) evaluates to (2 3)".

    ==>: Indicating an Expansion

    When an expression is a macro call, it expands into a new expression. You can indicate the result of the expansion with the @expansion{} command.

    The @expansion{} command is displayed as `==>' in Info and as `==>' in the printed output.

    For example, the following

    @lisp
(third '(a b c))
     @expansion{} (car (cdr (cdr '(a b c))))
     @result{} c
@end lisp

    produces

    (third '(a b c))
     ==> (car (cdr (cdr '(a b c))))
     => c

    which may be read as:

    (third '(a b c)) expands to (car (cdr (cdr '(a b c)))); the result of evaluating the expression is c.

    Often, as in this case, an example looks better if the @expansion{} and @result{} commands are indented five spaces.

    -|: Indicating Printed Output

    Sometimes an expression will print output during its execution. You can indicate the printed output with the @print{} command.

    The @print{} command is displayed as `-|' in Info and as `-|' in the printed output.

    In the following example, the printed text is indicated with `-|', and the value of the expression follows on the last line.

    (progn (print 'foo) (print 'bar))
     -| foo
     -| bar
     => bar

    In a Texinfo source file, this example is written as follows:

    @lisp
(progn (print 'foo) (print 'bar))
     @print{} foo
     @print{} bar
     @result{} bar
@end lisp

    error-->: Indicating an Error Message

    A piece of code may cause an error when you evaluate it. You can designate the error message with the @error{} command.

    The @error{} command is displayed as `error-->' in Info and as `error-->' in the printed output.

    Thus,

    @lisp
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@end lisp

    produces

    (+ 23 'x)
error--> Wrong type argument: integer-or-marker-p, x

    This indicates that the following error message is printed when you evaluate the expression:

    Wrong type argument: integer-or-marker-p, x

    Note that `error-->' itself is not part of the error message.

    ==: Indicating Equivalence

    Sometimes two expressions produce identical results. You can indicate the exact equivalence of two forms with the @equiv{} command.

    The @equiv{} command is displayed as `==' in Info and as `==' in the printed output.

    Thus,

    @lisp
(make-sparse-keymap) @equiv{} (list 'keymap)
@end lisp

    produces

    (make-sparse-keymap) == (list 'keymap)

    This indicates that evaluating (make-sparse-keymap) produces identical results to evaluating (list 'keymap).

    Indicating Point in a Buffer

    Sometimes you need to show an example of text in an Emacs buffer. In such examples, the convention is to include the entire contents of the buffer in question between two lines of dashes containing the buffer name.

    You can use the `@point{}' command to show the location of point in the text in the buffer. (The symbol for point, of course, is not part of the text in the buffer; it indicates the place between two characters where point is located.)

    The @point{} command is displayed as `-!-' in Info and as `-!-' in the printed output.

    The following example shows the contents of buffer `foo' before and after evaluating a Lisp command to insert the word changed.

    ---------- Buffer: foo ----------
This is the -!-contents of foo.
---------- Buffer: foo ----------

    (insert "changed ")
     => nil
---------- Buffer: foo ----------
This is the changed -!-contents of foo.
---------- Buffer: foo ----------

    In a Texinfo source file, the example is written like this:

    @example
---------- Buffer: foo ----------
This is the @point{}contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     @result{} nil
---------- Buffer: foo ----------
This is the changed @point{}contents of foo.
---------- Buffer: foo ----------
@end example

    Making and Preventing Breaks

    Usually, a Texinfo file is processed both by TeX and by one of the Info formatting commands. Line, paragraph, or page breaks sometimes occur in the `wrong' place in one or other form of output. You must ensure that text looks right both in the printed manual and in the Info file.

    For example, in a printed manual, page breaks may occur awkwardly in the middle of an example; to prevent this, you can hold text together using a grouping command that keeps the text from being split across two pages. Conversely, you may want to force a page break where none would occur normally. Fortunately, problems like these do not often arise. When they do, use the break, break prevention, or pagination commands.

    The break commands create or allow line and paragraph breaks:

    @*
    Force a line break.
    @sp n
    Skip n blank lines.
    @-
    Insert a discretionary hyphen.
    @hyphenation{hy-phen-a-ted words}
    Define hyphen points in hy-phen-a-ted words.

    The line-break-prevention command holds text together all on one line:

    @w{text}
    Prevent text from being split and hyphenated across two lines.

    The pagination commands apply only to printed output, since Info files do not have pages.

    @page
    Start a new page in the printed manual.
    @group
    Hold text together that must appear on one printed page.
    @need mils
    Start a new printed page if not enough space on this one.

    @*: Generate Line Breaks

    The @* command forces a line break in both the printed manual and in Info.

    For example,

    This line @* is broken @*in two places.

    produces

    This line
 is broken
in two places.

    (Note that the space after the first @* command is faithfully carried down to the next line.)

    The @* command is often used in a file's copyright page:

    This is edition 2.0 of the Texinfo documentation,@*
and is for ...

    In this case, the @* command keeps TeX from stretching the line across the whole page in an ugly manner.

    Please note: Do not write braces after an @* command; they are not needed.

    Do not write an @refill command at the end of a paragraph containing an @* command; it will cause the paragraph to be refilled after the line break occurs, negating the effect of the line break.

    @- and @hyphenation: Helping TeX hyphenate

    Although TeX's hyphenation algorithm is generally pretty good, it does miss useful hyphenation points from time to time. (Or, far more rarely, insert an incorrect hyphenation.) So, for documents with an unusual vocabulary or when fine-tuning for a printed edition, you may wish to help TeX out. Texinfo supports two commands for this:

    @-
    Insert a discretionary hyphen, i.e., a place where TeX can (but does not have to) hyphenate. This is especially useful when you notice an overfull hbox is due to TeX missing a hyphenation (see section Overfull "hboxes"). TeX will not insert any hyphenation points in a word containing @-.
    @hyphenation{hy-phen-a-ted words}
    Tell TeX how to hyphenate hy-phen-a-ted words. As shown, you put a `-' at each hyphenation point. For example:
    @hyphenation{man-u-script man-u-scripts}
    TeX only uses the specified hyphenation points when the words match exactly, so give all necessary variants.

    Info output is not hyphenated, so these commands have no effect there.

    @w{text}: Prevent Line Breaks

    @w{text} outputs text and prohibits line breaks within text.

    You can use the @w command to prevent TeX from automatically hyphenating a long name or phrase that accidentally falls near the end of a line.

    You can copy GNU software from @w{@file{prep.ai.mit.edu}}.

    produces

    You can copy GNU software from `prep.ai.mit.edu'.

    Caution: Do not write an @refill command at the end of a paragraph containing an @w command; it will cause the paragraph to be refilled and may thereby negate the effect of the @w command.

    @sp n: Insert Blank Lines

    A line beginning with and containing only @sp n generates n blank lines of space in both the printed manual and the Info file. @sp also forces a paragraph break. For example,

    @sp 2

    generates two blank lines.

    The @sp command is most often used in the title page.

    @page: Start a New Page

    A line containing only @page starts a new page in a printed manual. The command has no effect on Info files since they are not paginated. An @page command is often used in the @titlepage section of a Texinfo file to start the copyright page.

    @group: Prevent Page Breaks

    The @group command (on a line by itself) is used inside an @example or similar construct to begin an unsplittable vertical group, which will appear entirely on one page in the printed output. The group is terminated by a line containing only @end group. These two lines produce no output of their own, and in the Info file output they have no effect at all.

    Although @group would make sense conceptually in a wide variety of contexts, its current implementation works reliably only within @example and variants, and within @display, @format, @flushleft and @flushright. See section Quotations and Examples. (What all these commands have in common is that each line of input produces a line of output.) In other contexts, @group can cause anomalous vertical spacing.

    This formatting requirement means that you should write:

    @example
@group
...
@end group
@end example

    with the @group and @end group commands inside the @example and @end example commands.

    The @group command is most often used to hold an example together on one page. In this Texinfo manual, more than 100 examples contain text that is enclosed between @group and @end group.

    If you forget to end a group, you may get strange and unfathomable error messages when you run TeX. This is because TeX keeps trying to put the rest of the Texinfo file onto the one page and does not start to generate error messages until it has processed considerable text. It is a good rule of thumb to look for a missing @end group if you get incomprehensible error messages in TeX.

    @need mils: Prevent Page Breaks

    A line containing only @need n starts a new page in a printed manual if fewer than n mils (thousandths of an inch) remain on the current page. Do not use braces around the argument n. The @need command has no effect on Info files since they are not paginated.

    This paragraph is preceded by an @need command that tells TeX to start a new page if fewer than 800 mils (eight-tenths inch) remain on the page. It looks like this:

    @need 800
This paragraph is preceded by ...

    The @need command is useful for preventing orphans (single lines at the bottoms of printed pages).

    Definition Commands

    The @deffn command and the other definition commands enable you to describe functions, variables, macros, commands, user options, special forms and other such artifacts in a uniform format.

    In the Info file, a definition causes the entity category---`Function', `Variable', or whatever--to appear at the beginning of the first line of the definition, followed by the entity's name and arguments. In the printed manual, the command causes TeX to print the entity's name and its arguments on the left margin and print the category next to the right margin. In both output formats, the body of the definition is indented. Also, the name of the entity is entered into the appropriate index: @deffn enters the name into the index of functions, @defvr enters it into the index of variables, and so on.

    A manual need not and should not contain more than one definition for a given name. An appendix containing a summary should use @table rather than the definition commands.

    The Template for a Definition

    The @deffn command is used for definitions of entities that resemble functions. To write a definition using the @deffn command, write the @deffn command at the beginning of a line and follow it on the same line by the category of the entity, the name of the entity itself, and its arguments (if any). Then write the body of the definition on succeeding lines. (You may embed examples in the body.) Finally, end the definition with an @end deffn command written on a line of its own. (The other definition commands follow the same format.)

    The template for a definition looks like this:

    @deffn category name arguments...
body-of-definition
@end deffn

    For example,

    @deffn Command forward-word count
This command moves point forward @var{count} words
(or backward if @var{count} is negative). ...
@end deffn

    produces

    Command: forward-word count
    This function moves point forward count words (or backward if count is negative). ...

    Capitalize the category name like a title. If the name of the category contains spaces, as in the phrase `Interactive Command', write braces around it. For example:

    @deffn {Interactive Command} isearch-forward
...
@end deffn

    Otherwise, the second word will be mistaken for the name of the entity.

    Some of the definition commands are more general than others. The @deffn command, for example, is the general definition command for functions and the like--for entities that may take arguments. When you use this command, you specify the category to which the entity belongs. The @deffn command possesses three predefined, specialized variations, @defun, @defmac, and @defspec, that specify the category for you: "Function", "Macro", and "Special Form" respectively. The @defvr command also is accompanied by several predefined, specialized variations for describing particular kinds of variables.

    The template for a specialized definition, such as @defun, is similar to the template for a generalized definition, except that you do not need to specify the category:

    @defun name arguments...
body-of-definition
@end defun

    Thus,

    @defun buffer-end flag
This function returns @code{(point-min)} if @var{flag}
is less than 1, @code{(point-max)} otherwise.
...
@end defun

    produces

    Function: buffer-end flag
    This function returns (point-min) if flag is less than 1, (point-max) otherwise. ...

    See section A Sample Function Definition, for a more detailed example of a function definition, including the use of @example inside the definition.

    The other specialized commands work like @defun.

    Optional and Repeated Arguments

    Some entities take optional or repeated arguments, which may be specified by a distinctive glyph that uses square brackets and ellipses. For example, a special form often breaks its argument list into separate arguments in more complicated ways than a straightforward function.

    An argument enclosed within square brackets is optional. Thus, the phrase `[optional-arg]' means that optional-arg is optional. An argument followed by an ellipsis is optional and may be repeated more than once. Thus, `repeated-args...' stands for zero or more arguments. Parentheses are used when several arguments are grouped into additional levels of list structure in Lisp.

    Here is the @defspec line of an example of an imaginary special form:

    Special Form: foobar (var [from to [inc]]) body...

    In this example, the arguments from and to are optional, but must both be present or both absent. If they are present, inc may optionally be specified as well. These arguments are grouped with the argument var into a list, to distinguish them from body, which includes all remaining elements of the form.

    In a Texinfo source file, this @defspec line is written like this (except it would not be split over two lines, as it is in this example).

    @defspec foobar (@var{var} [@var{from} @var{to}
     [@var{inc}]]) @var{body}@dots{}

    The function is listed in the Command and Variable Index under `foobar'.

    Two or More `First' Lines

    To create two or more `first' or header lines for a definition, follow the first @deffn line by a line beginning with @deffnx. The @deffnx command works exactly like @deffn except that it does not generate extra vertical white space between it and the preceding line.

    For example,

    @deffn {Interactive Command} isearch-forward
@deffnx {Interactive Command} isearch-backward
These two search commands are similar except ...
@end deffn

    produces

    Interactive Command: isearch-forward
    Interactive Command: isearch-backward
    These two search commands are similar except ...

    Each of the other definition commands has an `x' form: @defunx, @defvrx, @deftypefunx, etc.

    The `x' forms work just like @itemx; see section @itemx.

    The Definition Commands

    Texinfo provides more than a dozen definition commands, all of which are described in this section.

    The definition commands automatically enter the name of the entity in the appropriate index: for example, @deffn, @defun, and @defmac enter function names in the index of functions; @defvr and @defvar enter variable names in the index of variables.

    Although the examples that follow mostly illustrate Lisp, the commands can be used for other programming languages.

    Functions and Similar Entities

    This section describes the commands for describing functions and similar entities:

    @deffn category name arguments...
    The @deffn command is the general definition command for functions, interactive commands, and similar entities that may take arguments. You must choose a term to describe the category of entity being defined; for example, "Function" could be used if the entity is a function. The @deffn command is written at the beginning of a line and is followed on the same line by the category of entity being described, the name of this particular entity, and its arguments, if any. Terminate the definition with @end deffn on a line of its own. For example, here is a definition:
    @deffn Command forward-char nchars
Move point forward @var{nchars} characters.
@end deffn
    This shows a rather terse definition for a "command" named forward-char with one argument, nchars. @deffn prints argument names such as nchars in italics or upper case, as if @var had been used, because we think of these names as metasyntactic variables--they stand for the actual argument values. Within the text of the description, write an argument name explicitly with @var to refer to the value of the argument. In the example above, we used `@var{nchars}' in this way. The template for @deffn is:
    @deffn category name arguments...
body-of-definition
@end deffn
    @defun name arguments...
    The @defun command is the definition command for functions. @defun is equivalent to `@deffn Function ...'. For example,
    @defun set symbol new-value
Change the value of the symbol @var{symbol}
to @var{new-value}.
@end defun
    shows a rather terse definition for a function set whose arguments are symbol and new-value. The argument names on the @defun line automatically appear in italics or upper case as if they were enclosed in @var. Terminate the definition with @end defun on a line of its own. The template is:
    @defun function-name arguments...
body-of-definition
@end defun
    @defun creates an entry in the index of functions.
    @defmac name arguments...
    The @defmac command is the definition command for macros. @defmac is equivalent to `@deffn Macro ...' and works like @defun.
    @defspec name arguments...
    The @defspec command is the definition command for special forms. (In Lisp, a special form is an entity much like a function.) @defspec is equivalent to `@deffn {Special Form} ...' and works like @defun.

    Variables and Similar Entities

    Here are the commands for defining variables and similar entities:

    @defvr category name
    The @defvr command is a general definition command for something like a variable--an entity that records a value. You must choose a term to describe the category of entity being defined; for example, "Variable" could be used if the entity is a variable. Write the @defvr command at the beginning of a line and followed it on the same line by the category of the entity and the name of the entity. Capitalize the category name like a title. If the name of the category contains spaces, as in the name `User Option', write braces around it. Otherwise, the second word will be mistaken for the name of the entity, for example:
    @defvr {User Option} fill-column
This buffer-local variable specifies
the maximum width of filled lines.
...
@end defvr
    Terminate the definition with @end defvr on a line of its own. The template is:
    @defvr category name
body-of-definition
@end defvr
    @defvr creates an entry in the index of variables for name.
    @defvar name
    The @defvar command is the definition command for variables. @defvar is equivalent to `@defvr Variable ...'. For example:
    @defvar kill-ring
...
@end defvar
    The template is:
    @defvar name
body-of-definition
@end defvar
    @defvar creates an entry in the index of variables for name.
    @defopt name
    The @defopt command is the definition command for user options. @defopt is equivalent to `@defvr {User Option} ...' and works like @defvar.

    Functions in Typed Languages

    The @deftypefn command and its variations are for describing functions in C or any other language in which you must declare types of variables and functions.

    @deftypefn category data-type name arguments...
    The @deftypefn command is the general definition command for functions and similar entities that may take arguments and that are typed. The @deftypefn command is written at the beginning of a line and is followed on the same line by the category of entity being described, the type of the returned value, the name of this particular entity, and its arguments, if any. For example,
    @deftypefn {Library Function} int foobar
   (int @var{foo}, float @var{bar})
...
@end deftypefn
    (where the text before the "...", shown above as two lines, would actually be a single line in a real Texinfo file) produces the following in Info:
    -- Library Function: int foobar (int FOO, float BAR)
...
    In a printed manual, it produces:

    Library Function: int foobar (int foo, float bar)
    ...
    This means that foobar is a "library function" that returns an int, and its arguments are foo (an int) and bar (a float). The argument names that you write in @deftypefn are not subject to an implicit @var---since the actual names of the arguments in @deftypefn are typically scattered among data type names and keywords, Texinfo cannot find them without help. Instead, you must write @var explicitly around the argument names. In the example above, the argument names are `foo' and `bar'. The template for @deftypefn is:
    @deftypefn category data-type name arguments ...
body-of-description
@end deftypefn
    Note that if the category or data type is more than one word then it must be enclosed in braces to make it a single argument. If you are describing a procedure in a language that has packages, such as Ada, you might consider using @deftypefn in a manner somewhat contrary to the convention described in the preceding paragraphs. For example:
    @deftypefn stacks private push
        (@var{s}:in out stack;
        @var{n}:in integer)
...
@end deftypefn
    (The @deftypefn arguments are shown split into three lines, but would be a single line in a real Texinfo file.) In this instance, the procedure is classified as belonging to the package stacks rather than classified as a `procedure' and its data type is described as private. (The name of the procedure is push, and its arguments are s and n.) @deftypefn creates an entry in the index of functions for name.
    @deftypefun data-type name arguments...
    The @deftypefun command is the specialized definition command for functions in typed languages. The command is equivalent to `@deftypefn Function ...'. Thus,
    @deftypefun int foobar (int @var{foo}, float @var{bar})
...
@end deftypefun
    produces the following in Info:
    -- Function: int foobar (int FOO, float BAR)
...
    and the following in a printed manual:

    Function: int foobar (int foo, float bar)
    ...
    The template is:
    @deftypefun type name arguments...
body-of-description
@end deftypefun
    @deftypefun creates an entry in the index of functions for name.

    Variables in Typed Languages

    Variables in typed languages are handled in a manner similar to functions in typed languages. See section Functions in Typed Languages. The general definition command @deftypevr corresponds to @deftypefn and the specialized definition command @deftypevar corresponds to @deftypefun.

    @deftypevr category data-type name
    The @deftypevr command is the general definition command for something like a variable in a typed language--an entity that records a value. You must choose a term to describe the category of the entity being defined; for example, "Variable" could be used if the entity is a variable. The @deftypevr command is written at the beginning of a line and is followed on the same line by the category of the entity being described, the data type, and the name of this particular entity. For example:
    @deftypevr {Global Flag} int enable
...
@end deftypevr
    produces the following in Info:
    -- Global Flag: int enable
...
    and the following in a printed manual:

    Global Flag: int enable
    ...
    The template is:
    @deftypevr category data-type name
body-of-description
@end deftypevr
    @deftypevr creates an entry in the index of variables for name.
    @deftypevar data-type name
    The @deftypevar command is the specialized definition command for variables in typed languages. @deftypevar is equivalent to `@deftypevr Variable ...'. For example:
    @deftypevar int fubar
...
@end deftypevar
    produces the following in Info:
    -- Variable: int fubar
...
    and the following in a printed manual:

    Variable: int fubar
    ...
    The template is:
    @deftypevar data-type name
body-of-description
@end deftypevar
    @deftypevar creates an entry in the index of variables for name.

    Object-Oriented Programming

    Here are the commands for formatting descriptions about abstract objects, such as are used in object-oriented programming. A class is a defined type of abstract object. An instance of a class is a particular object that has the type of the class. An instance variable is a variable that belongs to the class but for which each instance has its own value.

    In a definition, if the name of a class is truly a name defined in the programming system for a class, then you should write an @code around it. Otherwise, it is printed in the usual text font.

    @defcv category class name
    The @defcv command is the general definition command for variables associated with classes in object-oriented programming. The @defcv command is followed by three arguments: the category of thing being defined, the class to which it belongs, and its name. Thus,
    @defcv {Class Option} Window border-pattern
...
@end defcv
    illustrates how you would write the first line of a definition of the border-pattern class option of the class Window. The template is
    @defcv category class name
...
@end defcv
    @defcv creates an entry in the index of variables.
    @defivar class name
    The @defivar command is the definition command for instance variables in object-oriented programming. @defivar is equivalent to `@defcv {Instance Variable} ...' The template is:
    @defivar class instance-variable-name
body-of-definition
@end defivar
    @defivar creates an entry in the index of variables.
    @defop category class name arguments...
    The @defop command is the general definition command for entities that may resemble methods in object-oriented programming. These entities take arguments, as functions do, but are associated with particular classes of objects. For example, some systems have constructs called wrappers that are associated with classes as methods are, but that act more like macros than like functions. You could use @defop Wrapper to describe one of these. Sometimes it is useful to distinguish methods and operations. You can think of an operation as the specification for a method. Thus, a window system might specify that all window classes have a method named expose; we would say that this window system defines an expose operation on windows in general. Typically, the operation has a name and also specifies the pattern of arguments; all methods that implement the operation must accept the same arguments, since applications that use the operation do so without knowing which method will implement it. Often it makes more sense to document operations than methods. For example, window application developers need to know about the expose operation, but need not be concerned with whether a given class of windows has its own method to implement this operation. To describe this operation, you would write:
    @defop Operation windows expose
    The @defop command is written at the beginning of a line and is followed on the same line by the overall name of the category of operation, the name of the class of the operation, the name of the operation, and its arguments, if any. The template is:
    @defop category class name arguments...
body-of-definition
@end defop
    @defop creates an entry, such as `expose on windows', in the index of functions.
    @defmethod class name arguments...
    The @defmethod command is the definition command for methods in object-oriented programming. A method is a kind of function that implements an operation for a particular class of objects and its subclasses. In the Lisp Machine, methods actually were functions, but they were usually defined with defmethod. @defmethod is equivalent to `@defop Method ...'. The command is written at the beginning of a line and is followed by the name of the class of the method, the name of the method, and its arguments, if any. For example,
    @defmethod bar-class bar-method argument
...
@end defmethod
    illustrates the definition for a method called bar-method of the class bar-class. The method takes an argument. The template is:
    @defmethod class method-name arguments...
body-of-definition
@end defmethod
    @defmethod creates an entry, such as `bar-method on bar-class', in the index of functions.

    Data Types

    Here is the command for data types:

    @deftp category name attributes...
    The @deftp command is the generic definition command for data types. The command is written at the beginning of a line and is followed on the same line by the category, by the name of the type (which is a word like int or float), and then by names of attributes of objects of that type. Thus, you could use this command for describing int or float, in which case you could use data type as the category. (A data type is a category of certain objects for purposes of deciding which operations can be performed on them.) In Lisp, for example, pair names a particular data type, and an object of that type has two slots called the CAR and the CDR. Here is how you would write the first line of a definition of pair.
    @deftp {Data type} pair car cdr
...
@end deftp
    The template is:
    @deftp category name-of-type attributes...
body-of-definition
@end deftp
    @deftp creates an entry in the index of data types.

    Conventions for Writing Definitions

    When you write a definition using @deffn, @defun, or one of the other definition commands, please take care to use arguments that indicate the meaning, as with the count argument to the forward-word function. Also, if the name of an argument contains the name of a type, such as integer, take care that the argument actually is of that type.

    A Sample Function Definition

    A function definition uses the @defun and @end defun commands. The name of the function follows immediately after the @defun command and it is followed, on the same line, by the parameter list.

    Here is a definition from The GNU Emacs Lisp Reference Manual. (See section `Calling Functions' in The GNU Emacs Lisp Reference Manual.)

    Function: apply function &rest arguments
    apply calls function with arguments, just like funcall but with one difference: the last of arguments is a list of arguments to give to function, rather than a single argument. We also say that this list is appended to the other arguments.

    apply returns the result of calling function. As with funcall, function must either be a Lisp function or a primitive function; special forms and macros do not make sense in apply.

    (setq f 'list)
     => list
(apply f 'x 'y 'z)
error--> Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     => 10
(apply '+ '(1 2 3 4))
     => 10

(apply 'append '((a b c) nil (x y z) nil))
     => (a b c x y z)

    An interesting example of using apply is found in the description of mapcar.

    In the Texinfo source file, this example looks like this:

    @defun apply function &rest arguments

@code{apply} calls @var{function} with
@var{arguments}, just like @code{funcall} but with one
difference: the last of @var{arguments} is a list of
arguments to give to @var{function}, rather than a single
argument.  We also say that this list is @dfn{appended}
to the other arguments.

@code{apply} returns the result of calling
@var{function}.  As with @code{funcall},
@var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make
sense in @code{apply}.

@example
(setq f 'list)
     @result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
     @result{} 10
(apply '+ '(1 2 3 4))
     @result{} 10

(apply 'append '((a b c) nil (x y z) nil))
     @result{} (a b c x y z)
@end example

An interesting example of using @code{apply} is found
in the description of @code{mapcar}.@refill
@end defun

    In this manual, this function is listed in the Command and Variable Index under apply.

    Ordinary variables and user options are described using a format like that for functions except that variables do not take arguments.

    Footnotes

    A footnote is for a reference that documents or elucidates the primary text.(9)

    Footnote Commands

    In Texinfo, footnotes are created with the @footnote command. This command is followed immediately by a left brace, then by the text of the footnote, and then by a terminating right brace. The template is:

    @footnote{text}

    Footnotes may be of any length, but are usually short.

    For example, this clause is followed by a sample footnote(10); in the Texinfo source, it looks like this:

    ...a sample footnote @footnote{Here is the sample
footnote.}; in the Texinfo source...

    Warning: Don't use footnotes in the argument of the @item command for a @table table. This doesn't work; because of limitations of TeX, there is no way to fix it. To avoid the problem, move the footnote into the body text of the table.

    In a printed manual or book, the reference mark for a footnote is a small, superscripted number; the text of the footnote appears at the bottom of the page, below a horizontal line.

    In Info, the reference mark for a footnote is a pair of parentheses with the footnote number between them, like this: `(1)'.

    Footnote Styles

    Info has two footnote styles, which determine where the text of the footnote is located:

    • In the `End' node style, all the footnotes for a single node are placed at the end of that node. The footnotes are separated from the rest of the node by a line of dashes with the word `Footnotes' within it. Each footnote begins with an `(n)' reference mark. Here is an example of a single footnote in the end of node style:
       --------- Footnotes ---------

(1)  Here is a sample footnote.
    • In the `Separate' node style, all the footnotes for a single node are placed in an automatically constructed node of their own. In this style, a "footnote reference" follows each `(n)' reference mark in the body of the node. The footnote reference is actually a cross reference which you use to reach the footnote node. The name of the node containing the footnotes is constructed by appending `-Footnotes' to the name of the node that contains the footnotes. (Consequently, the footnotes' node for the `Footnotes' node is `Footnotes-Footnotes'!) The footnotes' node has an `Up' node pointer that leads back to its parent node. Here is how the first footnote in this manual looks after being formatted for Info in the separate node style:
      File: texinfo.info  Node: Overview-Footnotes, Up: Overview

(1) Note that the first syllable of "Texinfo" is
pronounced like "speck", not "hex". ...

    A Texinfo file may be formatted into an Info file with either footnote style.

    Use the @footnotestyle command to specify an Info file's footnote style. Write this command at the beginning of a line followed by an argument, either `end' for the end node style or `separate' for the separate node style.

    For example,

    @footnotestyle end

    or

    @footnotestyle separate

    Write an @footnotestyle command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you include the @footnotestyle command between the start-of-header and end-of-header lines, the region formatting commands will format footnotes as specified.)

    If you do not specify a footnote style, the formatting commands use their default style. Currently, texinfo-format-buffer and texinfo-format-region use the `separate' style and makeinfo uses the `end' style.

    This chapter contains two footnotes.

    Conditionally Visible Text

    Sometimes it is good to use different text for a printed manual and its corresponding Info file. In this case, you can use the conditional commands to specify which text is for the printed manual and which is for the Info file.

    @ifinfo begins segments of text that should be ignored by TeX when it typesets the printed manual. The segment of text appears only in the Info file. The @ifinfo command should appear on a line by itself; end the Info-only text with a line containing @end ifinfo by itself. At the beginning of a Texinfo file, the Info permissions are contained within a region marked by @ifinfo and @end ifinfo. (See section Summary and Copying Permissions for Info.)

    The @iftex and @end iftex commands are similar to the @ifinfo and @end ifinfo commands, except that they specify text that will appear in the printed manual but not in the Info file. Likewise for @ifhtml and @end ifhtml, which specify text to appear only in HTML output.

    For example,

    @iftex
This text will appear only in the printed manual.
@end iftex

@ifinfo
However, this text will appear only in Info.
@end ifinfo

    The preceding example produces the following line:

    This text will appear only in the printed manual.

    Note how you only see one of the two lines, depending on whether you are reading the Info version or the printed version of this manual.

    The @titlepage command is a special variant of @iftex that is used for making the title and copyright pages of the printed manual. (See section @titlepage.)

    Using Ordinary TeX Commands

    Inside a region delineated by @iftex and @end iftex, you can embed some plain TeX commands. Info will ignore these commands since they are only in that part of the file which is seen by TeX. You can write the TeX commands as you would write them in a normal TeX file, except that you must replace the `\' used by TeX with an `@'. For example, in the @titlepage section of a Texinfo file, you can use the TeX command @vskip to format the copyright page. (The @titlepage command causes Info to ignore the region automatically, as it does with the @iftex command.)

    However, many features of plain TeX will not work, as they are overridden by features of Texinfo.

    You can enter plain TeX completely, and use `\' in the TeX commands, by delineating a region with the @tex and @end tex commands. (The @tex command also causes Info to ignore the region, like the @iftex command.)

    For example, here is a mathematical expression written in plain TeX:

    @tex
$$ \chi^2 = \sum_{i=1}^N
          \left (y_i - (a + b x_i)
          \over \sigma_i\right)^2 $$
@end tex

    The output of this example will appear only in a printed manual. If you are reading this in Info, you will not see anything after this paragraph. In a printed manual, the above expression looks like this:

    @set, @clear, and @value

    You can direct the Texinfo formatting commands to format or ignore parts of a Texinfo file with the @set, @clear, @ifset, and @ifclear commands.

    In addition, you can use the @set flag command to set the value of flag to a string of characters; and use @value{flag} to insert that string. You can use @set, for example, to set a date and use @value to insert the date in several places in the Texinfo file.

    @ifset and @ifclear

    When a flag is set, the Texinfo formatting commands format text between subsequent pairs of @ifset flag and @end ifset commands. When the flag is cleared, the Texinfo formatting commands do not format the text.

    Use the @set flag command to turn on, or set, a flag; a flag can be any single word. The format for the command looks like this:

    @set flag

    Write the conditionally formatted text between @ifset flag and @end ifset commands, like this:

    @ifset flag
conditional-text
@end ifset

    For example, you can create one document that has two variants, such as a manual for a `large' and `small' model:

    You can use this machine to dig up shrubs
without hurting them.

@set large

@ifset large
It can also dig up fully grown trees.
@end ifset

Remember to replant promptly ...

    In the example, the formatting commands will format the text between @ifset large and @end ifset because the large flag is set.

    Use the @clear flag command to turn off, or clear, a flag. Clearing a flag is the opposite of setting a flag. The command looks like this:

    @clear flag

    Write the command on a line of its own.

    When flag is cleared, the Texinfo formatting commands do not format the text between @ifset flag and @end ifset; that text is ignored and does not appear in either printed or Info output.

    For example, if you clear the flag of the preceding example by writing an @clear large command after the @set large command (but before the conditional text), then the Texinfo formatting commands ignore the text between the @ifset large and @end ifset commands. In the formatted output, that text does not appear; in both printed and Info output, you see only the lines that say, "You can use this machine to dig up shrubs without hurting them. Remember to replant promptly ...".

    If a flag is cleared with an @clear flag command, then the formatting commands format text between subsequent pairs of @ifclear and @end ifclear commands. But if the flag is set with @set flag, then the formatting commands do not format text between an @ifclear and an @end ifclear command; rather, they ignore that text. An @ifclear command looks like this:

    @ifclear flag

    In brief, the commands are:

    @set flag
    Tell the Texinfo formatting commands that flag is set.
    @clear flag
    Tell the Texinfo formatting commands that flag is cleared.
    @ifset flag
    If flag is set, tell the Texinfo formatting commands to format the text up to the following @end ifset command. If flag is cleared, tell the Texinfo formatting commands to ignore text up to the following @end ifset command.
    @ifclear flag
    If flag is set, tell the Texinfo formatting commands to ignore the text up to the following @end ifclear command. If flag is cleared, tell the Texinfo formatting commands to format the text up to the following @end ifclear command.

    @value

    You can use the @set command to specify a value for a flag, which is expanded by the @value command. The value is a string a characters.

    Write the @set command like this:

    @set foo This is a string.

    This sets the value of foo to "This is a string."

    The Texinfo formatters replace an @value{flag} command with the string to which flag is set.

    Thus, when foo is set as shown above, the Texinfo formatters convert

    @value{foo}
to
This is a string.

    You can write an @value command within a paragraph; but you must write an @set command on a line of its own.

    If you write the @set command like this:

    @set foo

    without specifying a string, the value of foo is an empty string.

    If you clear a previously set flag with an @clear flag command, a subsequent @value{flag} command is invalid and the string is replaced with an error message that says `{No value for "flag"}'.

    For example, if you set foo as follows:

    @set how-much very, very, very

    then the formatters transform

    It is a @value{how-much} wet day.
into
It is a very, very, very wet day.

    If you write

    @clear how-much

    then the formatters transform

    It is a @value{how-much} wet day.
into
It is a {No value for "how-much"} wet day.

    @value Example

    You can use the @value command to limit the number of places you need to change when you record an update to a manual. Here is how it is done in The GNU Make Manual:

    Set the flags:

    @set EDITION 0.35 Beta
@set VERSION 3.63 Beta
@set UPDATED 14 August 1992
@set UPDATE-MONTH August 1992

    Write text for the first @ifinfo section, for people reading the Texinfo file:

    This is Edition @value{EDITION},
last updated @value{UPDATED},
of @cite{The GNU Make Manual},
for @code{make}, Version @value{VERSION}.

    Write text for the title page, for people reading the printed manual:

    @title GNU Make
@subtitle A Program for Directing Recompilation
@subtitle Edition @value{EDITION}, ...
@subtitle @value{UPDATE-MONTH}

    (On a printed cover, a date listing the month and the year looks less fussy than a date listing the day as well as the month and year.)

    Write text for the Top node, for people reading the Info file:

    This is Edition @value{EDITION}
of the @cite{GNU Make Manual},
last updated @value{UPDATED}
for @code{make} Version @value{VERSION}.

    After you format the manual, the text in the first @ifinfo section looks like this:

    This is Edition 0.35 Beta, last updated 14 August 1992,
of `The GNU Make Manual', for `make', Version 3.63 Beta.

    When you update the manual, change only the values of the flags; you do not need to rewrite the three sections.

    Macros: Defining New Texinfo Commands

    A Texinfo macro allows you to define a new Texinfo command as any sequence of text and/or existing commands (including other macros). The macro can have any number of parameters---text you supply each time you use the macro. (This has nothing to do with the @defmac command, which is for documenting macros in the subject of the manual; see section The Template for a Definition.)

    Defining Macros

    You use the Texinfo @macro command to define a macro. For example:

    @macro macro-name{param1, param2, ...}
text ... \param1\ ...
@end macro

    The parameters param1, param2, ... correspond to arguments supplied when the macro is subsequently used in the document (see the next section).

    If a macro needs no parameters, you can define it either with an empty list (`@macro foo {}') or with no braces at all (`@macro foo').

    The definition or body of the macro can contain any Texinfo commands, including previously-defined macros. (It is not possible to have mutually recursive Texinfo macros.) In the body, instances of a parameter name surrounded by backslashes, as in `\param1\' in the example above, are replaced by the corresponding argument from the macro invocation.

    You can undefine a macro foo with @unmacro foo. It is not an error to undefine a macro that is already undefined. For example:

    @unmacro foo

    Invoking Macros

    After a macro is defined (see the previous section), you can use (invoke) it in your document like this:

    @macro-name {arg1, arg2, ...}

    and the result will be just as if you typed the body of macro-name at that spot. For example:

    @macro foo {p, q}
Together: \p\ & \q\.
@end macro
@foo{a, b}

    produces:

    Together: a & b.

    Thus, the arguments and parameters are separated by commas and delimited by braces; any whitespace after (but not before) a comma is ignored. To insert a comma, brace, or backslash in an argument, prepend a backslash, as in

    @macro-name {\\\{\}\,}

    which will pass the (almost certainly error-producing) argument `\{},' to macro-name.

    If the macro is defined to take a single argument, and is invoked without any braces, the entire rest of the line after the macro name is supplied as the argument. For example:

    @macro bar {p}
Twice: \p\, \p\.
@end macro
@bar aah

    produces:

    Twice: aah, aah.

    Format and Print Hardcopy

    There are three major shell commands for making a printed manual from a Texinfo file: one for converting the Texinfo file into a file that will be printed, a second for sorting indices, and a third for printing the formatted document. When you use the shell commands, you can either work directly in the operating system shell or work within a shell inside GNU Emacs.

    If you are using GNU Emacs, you can use commands provided by Texinfo mode instead of shell commands. In addition to the three commands to format a file, sort the indices, and print the result, Texinfo mode offers key bindings for commands to recenter the output buffer, show the print queue, and delete a job from the print queue.

    The typesetting program called TeX is used for formatting a Texinfo file. TeX is a very powerful typesetting program and, if used right, does an exceptionally good job. See section How to Obtain TeX, for information on how to obtain TeX.

    The makeinfo, texinfo-format-region, and texinfo-format-buffer commands read the very same @-commands in the Texinfo file as does TeX, but process them differently to make an Info file; see section Creating an Info File.

    Format using tex and texindex

    Format the Texinfo file with the shell command tex followed by the name of the Texinfo file. This command produces a formatted DVI file as well as several auxiliary files containing indices, cross references, etc. The DVI file (for DeVice Independent file) can be printed on a wide variety of printers.

    The tex formatting command itself does not sort the indices; it writes an output file of unsorted index data. This is a misfeature of TeX. (The texi2dvi command automatically generates indices; see section Format using texi2dvi.) To generate a printed index after running the tex command, you first need a sorted index to work from. The texindex command sorts indices. (The source file `texindex.c' comes as part of the standard GNU distribution and is usually installed when Emacs is installed.)

    The tex formatting command outputs unsorted index files under names that obey a standard convention. These names are the name of your main input file to the tex formatting command, with everything after the first period thrown away, and the two letter names of indices added at the end. For example, the raw index output files for the input file `foo.texinfo' would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'. Those are exactly the arguments to give to texindex.

    Or else, you can use `??' as "wild-cards" and give the command in this form:

    texindex foo.??

    This command will run texindex on all the unsorted index files, including any that you have defined yourself using @defindex or @defcodeindex. (You may execute `texindex foo.??' even if there are similarly named files with two letter extensions that are not index files, such as `foo.el'. The texindex command reports but otherwise ignores such files.)

    For each file specified, texindex generates a sorted index file whose name is made by appending `s' to the input file name. The @printindex command knows to look for a file of that name. texindex does not alter the raw index output file.

    After you have sorted the indices, you need to rerun the tex formatting command on the Texinfo file. This regenerates a formatted DVI file with up-to-date index entries.(11)

    To summarize, this is a three step process:

    1. Run the tex formatting command on the Texinfo file. This generates the formatted DVI file as well as the raw index files with two letter extensions.
    2. Run the shell command texindex on the raw index files to sort them. This creates the corresponding sorted index files.
    3. Rerun the tex formatting command on the Texinfo file. This regenerates a formatted DVI file with the index entries in the correct order. This second run also corrects the page numbers for the cross references. (The tables of contents are always correct.)

    You need not run texindex each time after you run the tex formatting. If you do not, on the next run, the tex formatting command will use whatever sorted index files happen to exist from the previous use of texindex. This is usually OK while you are debugging.

    Format using texi2dvi

    The texi2dvi command is a shell script that automatically runs both tex and texindex as many times as necessary to produce a DVI file with up-to-date, sorted indices. It simplifies the tex---texindex---tex sequence described in the previous section.

    The syntax for texi2dvi is like this (where `prompt$' is the shell prompt):

    prompt$ texi2dvi filename...

    Shell Print Using lpr -d

    You can print a DVI file with the DVI print command. The precise printing command to use depends on your system; `lpr -d' is common. The DVI print command may require a file name without any extension or with a `.dvi' extension.

    The following commands, for example, sort the indices, format, and print the Bison Manual (where `%' is the shell prompt):

    % tex bison.texinfo
% texindex bison.??
% tex bison.texinfo
% lpr -d bison.dvi

    (Remember that the shell commands may be different at your site; but these are commonly used versions.)

    Using the texi2dvi shell script, you simply need type:

    % texi2dvi bison.texinfo
% lpr -d bison.dvi

    From an Emacs Shell ...

    You can give formatting and printing commands from a shell within GNU Emacs. To create a shell within Emacs, type M-x shell. In this shell, you can format and print the document. See section Format and Print Hardcopy, for details.

    You can switch to and from the shell buffer while tex is running and do other editing. If you are formatting a long document on a slow machine, this can be very convenient.

    You can also use texi2dvi from an Emacs shell. For example, here is how to use texi2dvi to format and print Using and Porting GNU CC from a shell within Emacs (where `%' is the shell prompt):

    % texi2dvi gcc.texinfo
% lpr -d gcc.dvi

    Formatting and Printing in Texinfo Mode

    Texinfo mode provides several predefined key commands for TeX formatting and printing. These include commands for sorting indices, looking at the printer queue, killing the formatting job, and recentering the display of the buffer in which the operations occur.

    C-c C-t C-b
    M-x texinfo-tex-buffer
    Run texi2dvi on the current buffer.
    C-c C-t C-r
    M-x texinfo-tex-region
    Run TeX on the current region.
    C-c C-t C-i
    M-x texinfo-texindex
    Sort the indices of a Texinfo file formatted with texinfo-tex-region.
    C-c C-t C-p
    M-x texinfo-tex-print
    Print a DVI file that was made with texinfo-tex-region or texinfo-tex-buffer.
    C-c C-t C-q
    M-x tex-show-print-queue
    Show the print queue.
    C-c C-t C-d
    M-x texinfo-delete-from-print-queue
    Delete a job from the print queue; you will be prompted for the job number shown by a preceding C-c C-t C-q command (texinfo-show-tex-print-queue).
    C-c C-t C-k
    M-x tex-kill-job
    Kill the currently running TeX job started by texinfo-tex-region or texinfo-tex-buffer, or any other process running in the Texinfo shell buffer.
    C-c C-t C-x
    M-x texinfo-quit-job
    Quit a TeX formatting job that has stopped because of an error by sending an x to it. When you do this, TeX preserves a record of what it did in a `.log' file.
    C-c C-t C-l
    M-x tex-recenter-output-buffer
    Redisplay the shell buffer in which the TeX printing and formatting commands are run to show its most recent output.

    Thus, the usual sequence of commands for formatting a buffer is as follows (with comments to the right):

    C-c C-t C-b             Run texi2dvi on the buffer.
C-c C-t C-p             Print the DVI file.
C-c C-t C-q             Display the printer queue.

    The Texinfo mode TeX formatting commands start a subshell in Emacs called the `*tex-shell*'. The texinfo-tex-command, texinfo-texindex-command, and tex-dvi-print-command commands are all run in this shell.

    You can watch the commands operate in the `*tex-shell*' buffer, and you can switch to and from and use the `*tex-shell*' buffer as you would any other shell buffer.

    The formatting and print commands depend on the values of several variables. The default values are:

         Variable                              Default value

texinfo-texi2dvi-command                  "texi2dvi"
texinfo-tex-command                       "tex"
texinfo-texindex-command                  "texindex"
texinfo-delete-from-print-queue-command   "lprm"
texinfo-tex-trailer                       "@bye"
tex-start-of-header                       "%**start"
tex-end-of-header                         "%**end"
tex-dvi-print-command                     "lpr -d"
tex-show-queue-command                    "lpq"

    You can change the values of these variables with the M-x edit-options command (see section `Editing Variable Values' in The GNU Emacs Manual), with the M-x set-variable command (see section `Examining and Setting Variables' in The GNU Emacs Manual), or with your `.emacs' initialization file (see section `Init File' in The GNU Emacs Manual).

    Using the Local Variables List

    Yet another way to apply the TeX formatting command to a Texinfo file is to put that command in a local variables list at the end of the Texinfo file. You can then specify the tex or texi2dvi commands as a compile-command and have Emacs run it by typing M-x compile. This creates a special shell called the `*compilation*' buffer in which Emacs runs the compile command. For example, at the end of the `gdb.texinfo' file, after the @bye, you could put the following:

    @c Local Variables:
@c compile-command: "texi2dvi gdb.texinfo"
@c End:

    This technique is most often used by programmers who also compile programs this way; see section `Compilation' in The GNU Emacs Manual.

    TeX Formatting Requirements Summary

    Every Texinfo file that is to be input to TeX must begin with a \input command and must contain an @setfilename command and an @settitle command:

    \input texinfo
@setfilename arg-not-used-by-TeX
@settitle name-of-manual

    The first command instructs TeX to load the macros it needs to process a Texinfo file, the second command opens auxiliary files, and the third specifies the title of printed manual.

    Every Texinfo file must end with a line that terminates TeX processing and forces out unfinished pages:

    @bye

    Strictly speaking, these four lines are all a Texinfo file needs for TeX, besides the body. (The @setfilename line is the only line that a Texinfo file needs for Info formatting.)

    Usually, the file's first line contains an `@c -*-texinfo-*-' comment that causes Emacs to switch to Texinfo mode when you edit the file. In addition, the beginning usually includes an @setchapternewpage command, a title page, a copyright page, and permissions. Besides an @bye, the end of a file usually includes indices and a table of contents.

    For more information, see section @setchapternewpage, section Page Headings, section The Title and Copyright Pages, section Index Menus and Printing an Index, and section Generating a Table of Contents.

    Preparing to Use TeX

    TeX needs to know where to find the `texinfo.tex' file that you have told it to input with the `\input texinfo' command at the beginning of the first line. The `texinfo.tex' file tells TeX how to handle @-commands. (`texinfo.tex' is included in the standard GNU distributions.)

    Usually, the `texinfo.tex' file is put in the default directory that contains TeX macros (the `/usr/lib/tex/macros' directory) when GNU Emacs or other GNU software is installed. In this case, TeX will find the file and you do not need to do anything special. Alternatively, you can put `texinfo.tex' in the directory in which the Texinfo source file is located, and TeX will find it there.

    However, you may want to specify the location of the \input file yourself. One way to do this is to write the complete path for the file after the \input command. Another way is to set the TEXINPUTS environment variable in your `.cshrc' or `.profile' file. The TEXINPUTS environment variable will tell TeX where to find the `texinfo.tex' file and any other file that you might want TeX to use.

    Whether you use a `.cshrc' or `.profile' file depends on whether you use csh, sh, or bash for your shell command interpreter. When you use csh, it looks to the `.cshrc' file for initialization information, and when you use sh or bash, it looks to the `.profile' file.

    In a `.cshrc' file, you could use the following csh command sequence:

    setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros

    In a `.profile' file, you could use the following sh command sequence:

    TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros
export TEXINPUTS

    This would cause TeX to look for `\input' file first in the current directory, indicated by the `.', then in a hypothetical user's `me/mylib' directory, and finally in the system library.

    Overfull "hboxes"

    TeX is sometimes unable to typeset a line without extending it into the right margin. This can occur when TeX comes upon what it interprets as a long word that it cannot hyphenate, such as an electronic mail network address or a very long title. When this happens, TeX prints an error message like this:

    Overfull \hbox (20.76302pt too wide)

    (In TeX, lines are in "horizontal boxes", hence the term, "hbox". The backslash, `\', is the TeX equivalent of `@'.)

    TeX also provides the line number in the Texinfo source file and the text of the offending line, which is marked at all the places that TeX knows how to hyphenate words. See section Catching Errors with TeX Formatting, for more information about typesetting errors.

    If the Texinfo file has an overfull hbox, you can rewrite the sentence so the overfull hbox does not occur, or you can decide to leave it. A small excursion into the right margin often does not matter and may not even be noticeable.

    However, unless told otherwise, TeX will print a large, ugly, black rectangle beside the line that contains the overfull hbox. This is so you will notice the location of the problem if you are correcting a draft.

    To prevent such a monstrosity from marring your final printout, write the following in the beginning of the Texinfo file on a line of its own, before the @titlepage command:

    @finalout

    Printing "Small" Books

    By default, TeX typesets pages for printing in an 8.5 by 11 inch format. However, you can direct TeX to typeset a document in a 7 by 9.25 inch format that is suitable for bound books by inserting the following command on a line by itself at the beginning of the Texinfo file, before the title page:

    @smallbook

    (Since regular sized books are often about 7 by 9.25 inches, this command might better have been called the @regularbooksize command, but it came to be called the @smallbook command by comparison to the 8.5 by 11 inch format.)

    If you write the @smallbook command between the start-of-header and end-of-header lines, the Texinfo mode TeX region formatting command, texinfo-tex-region, will format the region in "small" book size (see section Start of Header).

    The Free Software Foundation distributes printed copies of The GNU Emacs Manual and other manuals in the "small" book size. See section @smallexample and @smalllisp, for information about commands that make it easier to produce examples for a smaller manual.

    Printing on A4 Paper

    You can tell TeX to typeset a document for printing on European size A4 paper with the @afourpaper command. Write the command on a line by itself between @iftex and @end iftex lines near the beginning of the Texinfo file, before the title page:

    For example, this is how you would write the header for this manual:

    \input texinfo    @c -*-texinfo-*-
@c %**start of header
@setfilename texinfo
@settitle Texinfo
@syncodeindex vr fn
@iftex
@afourpaper
@end iftex
@c %**end of header

    Cropmarks and Magnification

    You can attempt to direct TeX to print cropmarks at the corners of pages with the @cropmarks command. Write the @cropmarks command on a line by itself between @iftex and @end iftex lines near the beginning of the Texinfo file, before the title page, like this:

    @iftex
@cropmarks
@end iftex

    This command is mainly for printers that typeset several pages on one sheet of film; but you can attempt to use it to mark the corners of a book set to 7 by 9.25 inches with the @smallbook command. (Printers will not produce cropmarks for regular sized output that is printed on regular sized paper.) Since different printing machines work in different ways, you should explore the use of this command with a spirit of adventure. You may have to redefine the command in the `texinfo.tex' definitions file.

    You can attempt to direct TeX to typeset pages larger or smaller than usual with the \mag TeX command. Everything that is typeset is scaled proportionally larger or smaller. (\mag stands for "magnification".) This is not a Texinfo @-command, but is a plain TeX command that is prefixed with a backslash. You have to write this command between @tex and @end tex (see section Using Ordinary TeX Commands).

    Follow the \mag command with an `=' and then a number that is 1000 times the magnification you desire. For example, to print pages at 1.2 normal size, write the following near the beginning of the Texinfo file, before the title page:

    @tex
\mag=1200
@end tex

    With some printing technologies, you can print normal-sized copies that look better than usual by using a larger-than-normal master.

    Depending on your system, \mag may not work or may work only at certain magnifications. Be prepared to experiment.

    Creating an Info File

    makeinfo is a utility that converts a Texinfo file into an Info file; texinfo-format-region and texinfo-format-buffer are GNU Emacs functions that do the same.

    A Texinfo file must possess an @setfilename line near its beginning, otherwise the Info formatting commands will fail.

    For information on installing the Info file in the Info system, see section Installing an Info File.

    The makeinfo utility creates an Info file from a Texinfo source file more quickly than either of the Emacs formatting commands and provides better error messages. We recommend it. makeinfo is a C program that is independent of Emacs. You do not need to run Emacs to use makeinfo, which means you can use makeinfo on machines that are too small to run Emacs. You can run makeinfo in any one of three ways: from an operating system shell, from a shell inside Emacs, or by typing a key command in Texinfo mode in Emacs.

    The texinfo-format-region and the texinfo-format-buffer commands are useful if you cannot run makeinfo. Also, in some circumstances, they format short regions or buffers more quickly than makeinfo.

    Running makeinfo from a Shell

    To create an Info file from a Texinfo file, type makeinfo followed by the name of the Texinfo file. Thus, to create the Info file for Bison, type the following at the shell prompt (where `%' is the prompt):

    % makeinfo bison.texinfo

    (You can run a shell inside Emacs by typing M-x shell.)

    Options for makeinfo

    The makeinfo command takes a number of options. Most often, options are used to set the value of the fill column and specify the footnote style. Each command line option is a word preceded by `--' (12) or a letter preceded by `-'. You can use abbreviations for the option names as long as they are unique.

    For example, you could use the following command to create an Info file for `bison.texinfo' in which each line is filled to only 68 columns (where `%' is the prompt):

    % makeinfo --fill-column=68 bison.texinfo

    You can write two or more options in sequence, like this:

    % makeinfo --no-split --fill-column=70 ...

    This would keep the Info file together as one possibly very long file and would also set the fill column to 70.

    If you wish to discover which version of makeinfo you are using, type:

    % makeinfo --version

    The options are:

    -D var
    Cause var to be defined. This is equivalent to @set var in the Texinfo file.
    --error-limit limit
    Set the maximum number of errors that makeinfo will report before exiting (on the assumption that continuing would be useless). The default number of errors that can be reported before makeinfo gives up is 100.
    --fill-column width
    Specify the maximum number of columns in a line; this is the right-hand edge of a line. Paragraphs that are filled will be filled to this width. (Filling is the process of breaking up and connecting lines so that lines are the same length as or shorter than the number specified as the fill column. Lines are broken between words.) The default value for fill-column is 72.
    --footnote-style style
    Set the footnote style to style, either `end' for the end node style or `separate' for the separate node style. The value set by this option overrides the value set in a Texinfo file by an @footnotestyle command. When the footnote style is `separate', makeinfo makes a new node containing the footnotes found in the current node. When the footnote style is `end', makeinfo places the footnote references at the end of the current node.
    -I dir
    Add dir to the directory search list for finding files that are included using the @include command. By default, makeinfo searches only the current directory.
    --no-headers
    Do not include menus or node lines in the output. This results in an ASCII file that you cannot read in Info since it does not contain the requisite nodes or menus; but you can print such a file in a single, typewriter-like font and produce acceptable output.
    --no-split
    Suppress the splitting stage of makeinfo. Normally, large output files (where the size is greater than 70k bytes) are split into smaller subfiles, each one approximately 50k bytes. If you specify `--no-split', makeinfo will not split up the output file.
    --no-pointer-validate
    --no-validate
    Suppress the pointer-validation phase of makeinfo. Normally, after a Texinfo file is processed, some consistency checks are made to ensure that cross references can be resolved, etc. See section Pointer Validation.
    --no-warn
    Suppress the output of warning messages. This does not suppress the output of error messages, only warnings. You might want this if the file you are creating has examples of Texinfo cross references within it, and the nodes that are referenced do not actually exist.
    --no-number-footnotes
    Suppress automatic footnote numbering. By default, makeinfo numbers each footnote sequentially in a single node, resetting the current footnote number to 1 at the start of each node.
    --output file
    -o file
    Specify that the output should be directed to file and not to the file name specified in the @setfilename command found in the Texinfo source. file can be the special token `-', which specifies standard output.
    --paragraph-indent indent
    Set the paragraph indentation style to indent. The value set by this option overrides the value set in a Texinfo file by an @paragraphindent command. The value of indent is interpreted as follows:
    • If the value of indent is `asis', do not change the existing indentation at the starts of paragraphs.
    • If the value of indent is zero, delete any existing indentation.
    • If the value of indent is greater than zero, indent each paragraph by that number of spaces.
    --reference-limit limit
    Set the value of the number of references to a node that makeinfo will make without reporting a warning. If a node has more than this number of references in it, makeinfo will make the references but also report a warning.
    -U var
    Cause var to be undefined. This is equivalent to @clear var in the Texinfo file.
    --verbose
    Cause makeinfo to display messages saying what it is doing. Normally, makeinfo only outputs messages if there are errors or warnings.
    --version
    Report the version number of this copy of makeinfo.

    Pointer Validation

    If you do not suppress pointer-validation, makeinfo will check the validity of the final Info file. Mostly, this means ensuring that nodes you have referenced really exist. Here is a complete list of what is checked:

    1. If a `Next', `Previous', or `Up' node reference is a reference to a node in the current file and is not an external reference such as to `(dir)', then the referenced node must exist.
    2. In every node, if the `Previous' node is different from the `Up' node, then the `Previous' node must also be pointed to by a `Next' node.
    3. Every node except the `Top' node must have an `Up' pointer.
    4. The node referenced by an `Up' pointer must contain a reference to the current node in some manner other than through a `Next' reference. This includes menu entries and cross references.
    5. If the `Next' reference of a node is not the same as the `Next' reference of the `Up' reference, then the node referenced by the `Next' pointer must have a `Previous' pointer that points back to the current node. This rule allows the last node in a section to point to the first node of the next chapter.

    Running makeinfo inside Emacs

    You can run makeinfo in GNU Emacs Texinfo mode by using either the makeinfo-region or the makeinfo-buffer commands. In Texinfo mode, the commands are bound to C-c C-m C-r and C-c C-m C-b by default.

    C-c C-m C-r
    M-x makeinfo-region
    Format the current region for Info.
    C-c C-m C-b
    M-x makeinfo-buffer
    Format the current buffer for Info.

    When you invoke either makeinfo-region or makeinfo-buffer, Emacs prompts for a file name, offering the name of the visited file as the default. You can edit the default file name in the minibuffer if you wish, before typing RET to start the makeinfo process.

    The Emacs makeinfo-region and makeinfo-buffer commands run the makeinfo program in a temporary shell buffer. If makeinfo finds any errors, Emacs displays the error messages in the temporary buffer.

    You can parse the error messages by typing C-x ` (next-error). This causes Emacs to go to and position the cursor on the line in the Texinfo source that makeinfo thinks caused the error. See section `Running make or Compilers Generally' in The GNU Emacs Manual, for more information about using the next-error command.

    In addition, you can kill the shell in which the makeinfo command is running or make the shell buffer display its most recent output.

    C-c C-m C-k
    M-x makeinfo-kill-job
    Kill the current running makeinfo job created by makeinfo-region or makeinfo-buffer.
    C-c C-m C-l
    M-x makeinfo-recenter-output-buffer
    Redisplay the makeinfo shell buffer to display its most recent output.

    (Note that the parallel commands for killing and recentering a TeX job are C-c C-t C-k and C-c C-t C-l. See section Formatting and Printing in Texinfo Mode.)

    You can specify options for makeinfo by setting the makeinfo-options variable with either the M-x edit-options or the M-x set-variable command, or by setting the variable in your `.emacs' initialization file.

    For example, you could write the following in your `.emacs' file:

    (setq makeinfo-options
      "--paragraph-indent=0 --no-split
       --fill-column=70 --verbose")

    For more information, see section Options for makeinfo, as well as "Editing Variable Values,""Examining and Setting Variables," and "Init File" in the The GNU Emacs Manual.

    The texinfo-format... Commands

    In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo file with the texinfo-format-region command. This formats the current region and displays the formatted text in a temporary buffer called `*Info Region*'.

    Similarly, you can format a buffer with the texinfo-format-buffer command. This command creates a new buffer and generates the Info file in it. Typing C-x C-s will save the Info file under the name specified by the @setfilename line which must be near the beginning of the Texinfo file.

    C-c C-e C-r
    texinfo-format-region
    Format the current region for Info.
    C-c C-e C-b
    texinfo-format-buffer
    Format the current buffer for Info.

    The texinfo-format-region and texinfo-format-buffer commands provide you with some error checking, and other functions can provide you with further help in finding formatting errors. These procedures are described in an appendix; see section Formatting Mistakes. However, the makeinfo program is often faster and provides better error checking (see section Running makeinfo inside Emacs).

    Batch Formatting

    You can format Texinfo files for Info using batch-texinfo-format and Emacs Batch mode. You can run Emacs in Batch mode from any shell, including a shell inside of Emacs. (See section `Command Line Switches and Arguments' in The GNU Emacs Manual.)

    Here is the command to format all the files that end in `.texinfo' in the current directory (where `%' is the shell prompt):

    % emacs -batch -funcall batch-texinfo-format *.texinfo

    Emacs processes all the files listed on the command line, even if an error occurs while attempting to format some of them.

    Run batch-texinfo-format only with Emacs in Batch mode as shown; it is not interactive. It kills the Batch mode Emacs on completion.

    batch-texinfo-format is convenient if you lack makeinfo and want to format several Texinfo files at once. When you use Batch mode, you create a new Emacs process. This frees your current Emacs, so you can continue working in it. (When you run texinfo-format-region or texinfo-format-buffer, you cannot use that Emacs for anything else until the command finishes.)

    Tag Files and Split Files

    If a Texinfo file has more than 30,000 bytes, texinfo-format-buffer automatically creates a tag table for its Info file; makeinfo always creates a tag table. With a tag table, Info can jump to new nodes more quickly than it can otherwise.

    In addition, if the Texinfo file contains more than about 70,000 bytes, texinfo-format-buffer and makeinfo split the large Info file into shorter indirect subfiles of about 50,000 bytes each. Big files are split into smaller files so that Emacs does not need to make a large buffer to hold the whole of a large Info file; instead, Emacs allocates just enough memory for the small, split off file that is needed at the time. This way, Emacs avoids wasting memory when you run Info. (Before splitting was implemented, Info files were always kept short and include files were designed as a way to create a single, large printed manual out of the smaller Info files. See section Include Files, for more information. Include files are still used for very large documents, such as The Emacs Lisp Reference Manual, in which each chapter is a separate file.)

    When a file is split, Info itself makes use of a shortened version of the original file that contains just the tag table and references to the files that were split off. The split off files are called indirect files.

    The split off files have names that are created by appending `-1', `-2', `-3' and so on to the file name specified by the @setfilename command. The shortened version of the original file continues to have the name specified by @setfilename.

    At one stage in writing this document, for example, the Info file was saved as `test-texinfo' and that file looked like this:

    Info file: test-texinfo,    -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo

^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
...

    (But `test-texinfo' had far more nodes than are shown here.) Each of the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and `test-texinfo-3', is listed in this file after the line that says `Indirect:'. The tag table is listed after the line that says `Tag table:'.

    In the list of indirect files, the number following the file name records the cumulative number of bytes in the preceding indirect files, not counting the file list itself, the tag table, or the permissions text in each file. In the tag table, the number following the node name records the location of the beginning of the node, in bytes from the beginning.

    If you are using texinfo-format-buffer to create Info files, you may want to run the Info-validate command. (The makeinfo command does such a good job on its own, you do not need Info-validate.) However, you cannot run the M-x Info-validate node-checking command on indirect files. For information on how to prevent files from being split and how to validate the structure of the nodes, see section Running Info-validate.

    Installing an Info File

    Info files are usually kept in the `info' directory. You can read Info files using the standalone Info program or the Info reader built into Emacs. (See Info file `info', node `Top', for an introduction to Info.)

    For Info to work, the `info' directory must contain a file that serves as a top level directory for the Info system. By convention, this file is called `dir'. (You can find the location of this file within Emacs by typing C-h i to enter Info and then typing C-x C-f to see the pathname to the `info' directory.)

    The `dir' file is itself an Info file. It contains the top level menu for all the Info files in the system. The menu looks like this:

    * Menu:

* Info:    (info).     Documentation browsing system.
* Emacs:   (emacs).    The extensible, self-documenting
                       text editor.
* Texinfo: (texinfo).  With one source file, make
                       either a printed manual using
                       TeX or an Info file.
...

    Each of these menu entries points to the `Top' node of the Info file that is named in parentheses. (The menu entry does not need to specify the `Top' node, since Info goes to the `Top' node if no node name is mentioned. See section Referring to Other Info Files.)

    Thus, the `Info' entry points to the `Top' node of the `info' file and the `Emacs' entry points to the `Top' node of the `emacs' file.

    In each of the Info files, the `Up' pointer of the `Top' node refers back to the dir file. For example, the line for the `Top' node of the Emacs manual looks like this in Info:

    File: emacs  Node: Top, Up: (DIR), Next: Distrib

    (Note that in this case, the `dir' file name is written in upper case letters--it can be written in either upper or lower case. Info has a feature that it will change the case of the file name to lower case if it cannot find the name as written.)

    Listing a New Info File

    To add a new Info file to your system, you must write a menu entry to add to the menu in the `dir' file in the `info' directory. For example, if you were adding documentation for GDB, you would write the following new entry:

    * GDB: (gdb).           The source-level C debugger.

    The first part of the menu entry is the menu entry name, followed by a colon. The second part is the name of the Info file, in parentheses, followed by a period. The third part is the description.

    The name of an Info file often has a `.info' extension. Thus, the Info file for GDB might be called either `gdb' or `gdb.info'. The Info reader programs automatically try the file name both with and without `.info'; so it is better to avoid clutter and not to write `.info' explicitly in the menu entry. For example, the GDB menu entry should use just `gdb' for the file name, not `gdb.info'.

    Info Files in Other Directories

    If an Info file is not in the `info' directory, there are three ways to specify its location:

    • Write the pathname in the `dir' file as the second part of the menu.
    • If you are using Emacs, list the name of the file in a second `dir' file, in its directory; and then add the name of that directory to the Info-directory-list variable in your personal or site initialization file. This tells Emacs's Info reader where to look for `dir' files. Emacs merges the files named `dir' from each of the listed directories. (In Emacs Version 18, you can set the Info-directory variable to the name of only one directory.)
    • Specify the `info' directory name in the INFOPATH environment variable in your `.profile' or `.cshrc' initialization file. (Only you and others who set this environment variable will be able to find Info files whose location is specified this way.)

    For example, to reach a test file in the `~bob/manuals' directory, you could add an entry like this to the menu in the `dir' file:

    * Test: (/home/bob/manuals/info-test).  Bob's own test file.

    In this case, the absolute file name of the `info-test' file is written as the second part of the menu entry.

    Alternatively, you could write the following in your `.emacs' file:

    (setq Info-directory-list
      '("/home/bob/manuals"
        "/usr/local/emacs/info"))

    This tells Emacs to merge the `dir' file from the `/home/bob/manuals' directory with the `dir' file from the `"/usr/local/emacs/info'" directory. Info will list the `/home/bob/manuals/info-test' file as a menu entry in the `/home/bob/manuals/dir' file.

    Finally, you can tell Info where to look by setting the INFOPATH environment variable in your `.cshrc' or `.profile' file.

    If you use sh or bash for your shell command interpreter, you must set the INFOPATH environment variable in the `.profile' initialization file; but if you use csh, you must set the variable in the `.cshrc' initialization file. The two files use slightly different command formats.

    • In a `.cshrc' file, you could set the INFOPATH variable as follows:
      setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info
    • In a `.profile' file, you would achieve the same effect by writing:
      INFOPATH=.:~bob/manuals:/usr/local/emacs/info
export INFOPATH

    The `.' indicates the current directory. Emacs uses the INFOPATH environment variable to initialize the value of Emacs's own Info-directory-list variable.

    Installing Info Directory Files

    When you install an Info file onto your system, you can use the program install-info to update the Info directory file `dir'. Normally the makefile for the package runs install-info, just after copying the Info file into its proper installed location.

    In order for the Info file to work with install-info, you should use the commands @dircategory and @direntry in the Texinfo source file. Use @direntry to specify the menu entry to add to the Info directory file, and use @dircategory to specify which part of the Info directory to put it in. Here is how these commands are used in this manual:

    @dircategory Texinfo documentation system
@direntry
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
@end direntry

    Here's what this produces in the Info file:

    INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
END-INFO-DIR-ENTRY

    The install-info program sees these lines in the Info file, and that is how it knows what to do.

    Always use the @direntry and @dircategory commands near the beginning of the Texinfo input, before the first @node command. If you use them later on in the input, install-info will not notice them.

    If you use @dircategory more than once in the Texinfo source, each usage specifies one category; the new menu entry is added to the Info directory file in each of the categories you specify. If you use @direntry more than once, each usage specifies one menu entry; each of these menu entries is added to the directory in each of the specified categories.

    Invoking install-info

    install-info inserts menu entries from an Info file into the top-level `dir' file in the Info system (see the previous sections for an explanation of how the `dir' file works). It's most often run as part of software installation, or when constructing a dir file for all manuals on a system. Synopsis:

    install-info [option]... [info-file [dir-file]]

    If info-file or dir-file are not specified, the various options (described below) that define them must be. There are no compile-time defaults, and standard input is never used. install-info can read only one info file and write only one dir file per invocation.

    Options:

    `--delete'
    Only delete existing entries in info-file; don't insert any new entries.
    `--dir-file=name'
    Specify file name of the Info directory file. This is equivalent to using the dir-file argument.
    `--entry=text'
    Insert text as an Info directory entry; text should have the form of an Info menu item line plus zero or more extra lines starting with whitespace. If you specify more than one entry, they are all added. If you don't specify any entries, they are determined from information in the Info file itself.
    `--help'
    Display a usage message listing basic usage and all available options, then exit successfully.
    `--info-file=file'
    Specify Info file to install in the directory. This is equivalent to using the info-file argument.
    `--info-dir=dir'
    Equivalent to `--dir-file=dir/dir'.
    `--item=text'
    Same as --entry=text. An Info directory entry is actually a menu item.
    `--quiet'
    Suppress warnings.
    `--remove'
    Same as --delete.
    `--section=sec'
    Put this file's entries in section sec of the directory. If you specify more than one section, all the entries are added in each of the sections. If you don't specify any sections, they are determined from information in the Info file itself.
    `--version'
    Display version information and exit successfully.

    @-Command List

    Here is an alphabetical list of the @-commands in Texinfo. Square brackets, [ ], indicate optional arguments; an ellipsis, `...', indicates repeated text.

    @whitespace
    An @ followed by a space, tab, or newline produces a normal, stretchable, interword space. See section Multiple Spaces.
    @!
    Generate an exclamation point that really does end a sentence (usually after an end-of-sentence capital letter). See section Ending a Sentence.
    @"
    @'
    Generate an umlaut or acute accent, respectively, over the next character, as in @"o and 'o. See section Inserting Accents.
    @*
    Force a line break. Do not end a paragraph that uses @* with an @refill command. See section @*: Generate Line Breaks.
    @,{c}
    Generate a cedilla accent under c, as in @,{c}. See section Inserting Accents.
    @-
    Insert a discretionary hyphenation point. See section @- and @hyphenation: Helping TeX hyphenate.
    @.
    Produce a period that really does end a sentence (usually after an end-of-sentence capital letter). See section Ending a Sentence.
    @:
    Indicate to TeX that an immediately preceding period, question mark, exclamation mark, or colon does not end a sentence. Prevent TeX from inserting extra whitespace as it does at the end of a sentence. The command has no effect on the Info file output. See section Not Ending a Sentence.
    @=
    Generate a macro (bar) accent over the next character, as in @=o. See section Inserting Accents.
    @?
    Generate a question mark that really does end a sentence (usually after an end-of-sentence capital letter). See section Ending a Sentence.
    @@
    Stands for an at sign, `@'.
    See section Inserting @ and Braces.
    @^
    @`
    Generate a circumflex (hat) or grave accent, respectively, over the next character, as in @^o. See section Inserting Accents.
    @{
    Stands for a left brace, `{'.
    See section Inserting @ and Braces.
    @}
    Stands for a right-hand brace, `}'.
    See section Inserting @ and Braces.
    @=
    Generate a tilde accent over the next character, as in @~N. See section Inserting Accents.
    @AA{}
    @aa{}
    Generate the uppercase and lowercase Scandinavian A-ring letters, respectively: @AA{}, @aa{}. See section Inserting Accents.
    @AE{}
    @ae{}
    Generate the uppercase and lowercase AE ligatures, respectively: @AE{}, @ae{}. See section Inserting Accents.
    @appendix title
    Begin an appendix. The title appears in the table of contents of a printed manual. In Info, the title is underlined with asterisks. See section @unnumbered, @appendix.
    @appendixsec title
    @appendixsection title
    Begin an appendix section within an appendix. The section title appears in the table of contents of a printed manual. In Info, the title is underlined with equal signs. @appendixsection is a longer spelling of the @appendixsec command. See section @unnumberedsec, @appendixsec, @heading.
    @appendixsubsec title
    Begin an appendix subsection within an appendix. The title appears in the table of contents of a printed manual. In Info, the title is underlined with hyphens. See section The @subsection-like Commands.
    @appendixsubsubsec title
    Begin an appendix subsubsection within a subappendix. The title appears in the table of contents of a printed manual. In Info, the title is underlined with periods. See section The `subsub' Commands.
    @asis
    Used following @table, @ftable, and @vtable to print the table's first column without highlighting ("as is"). See section Making a Two-column Table.
    @author author
    Typeset author flushleft and underline it. See section @title, @subtitle, and @author.
    @b{text}
    Print text in bold font. No effect in Info. See section Fonts for Printing, Not Info.
    @bullet{}
    Generate a large round dot, or the closest possible thing to one. See section @bullet{}.
    @bye
    Stop formatting a file. The formatters do not see the contents of a file following an @bye command. See section Ending a Texinfo File.
    @c comment
    Begin a comment in Texinfo. The rest of the line does not appear in either the Info file or the printed manual. A synonym for @comment. See section Comments.
    @cartouche
    Highlight an example or quotation by drawing a box with rounded corners around it. Pair with @end cartouche. No effect in Info. See section Drawing Cartouches Around Examples.)
    @center line-of-text
    Center the line of text following the command. See section @titlefont, @center, and @sp.
    @centerchap line-of-text
    Like @chapter, but centers the chapter title. See section @chapter.
    @chapheading title
    Print a chapter-like heading in the text, but not in the table of contents of a printed manual. In Info, the title is underlined with asterisks. See section @majorheading, @chapheading.
    @chapter title
    Begin a chapter. The chapter title appears in the table of contents of a printed manual. In Info, the title is underlined with asterisks. See section @chapter.
    @cindex entry
    Add entry to the index of concepts. See section Making Index Entries.
    @cite{reference}
    Highlight the name of a book or other reference that lacks a companion Info file. See section @cite{reference}.
    @clear flag
    Unset flag, preventing the Texinfo formatting commands from formatting text between subsequent pairs of @ifset flag and @end ifset commands, and preventing @value{flag} from expanding to the value to which flag is set. See section @set, @clear, and @value.
    @code{sample-code}
    Highlight text that is an expression, a syntactically complete token of a program, or a program name. See section @code{sample-code}.
    @comment comment
    Begin a comment in Texinfo. The rest of the line does not appear in either the Info file or the printed manual. A synonym for @c. See section Comments.
    @contents
    Print a complete table of contents. Has no effect in Info, which uses menus instead. See section Generating a Table of Contents.
    @copyright{}
    Generate a copyright symbol. See section @copyright{}.
    @defcodeindex index-name
    Define a new index and its indexing command. Print entries in an @code font. See section Defining New Indices.
    @defcv category class name
    @defcvx category class name
    Format a description for a variable associated with a class in object-oriented programming. Takes three arguments: the category of thing being defined, the class to which it belongs, and its name. See section Definition Commands, and section Two or More `First' Lines.
    @deffn category name arguments...
    @deffnx category name arguments...
    Format a description for a function, interactive command, or similar entity that may take arguments. @deffn takes as arguments the category of entity being described, the name of this particular entity, and its arguments, if any. See section Definition Commands.
    @defindex index-name
    Define a new index and its indexing command. Print entries in a roman font. See section Defining New Indices.
    @definfoenclose new-command, before, after,
    Create new @-command for Info that marks text by enclosing it in strings that precede and follow the text. Write definition inside of @ifinfo ... @end ifinfo. See section Customized Highlighting.
    @defivar class instance-variable-name
    @defivarx class instance-variable-name
    This command formats a description for an instance variable in object-oriented programming. The command is equivalent to `@defcv {Instance Variable} ...'. See section Definition Commands, and section Two or More `First' Lines.
    @defmac macro-name arguments...
    @defmacx macro-name arguments...
    Format a description for a macro. The command is equivalent to `@deffn Macro ...'. See section Definition Commands, and section Two or More `First' Lines.
    @defmethod class method-name arguments...
    @defmethodx class method-name arguments...
    Format a description for a method in object-oriented programming. The command is equivalent to `@defop Method ...'. Takes as arguments the name of the class of the method, the name of the method, and its arguments, if any. See section Definition Commands, and section Two or More `First' Lines.
    @defop category class name arguments...
    @defopx category class name arguments...
    Format a description for an operation in object-oriented programming. @defop takes as arguments the overall name of the category of operation, the name of the class of the operation, the name of the operation, and its arguments, if any. See section Definition Commands, and section Two or More `First' Lines.
    @defopt option-name
    @defoptx option-name
    Format a description for a user option. The command is equivalent to `@defvr {User Option} ...'. See section Definition Commands, and section Two or More `First' Lines.
    @defspec special-form-name arguments...
    @defspecx special-form-name arguments...
    Format a description for a special form. The command is equivalent to `@deffn {Special Form} ...'. See section Definition Commands, and section Two or More `First' Lines.
    @deftp category name-of-type attributes...
    @deftpx category name-of-type attributes...
    Format a description for a data type. @deftp takes as arguments the category, the name of the type (which is a word like `int' or `float'), and then the names of attributes of objects of that type. See section Definition Commands, and section Two or More `First' Lines.
    @deftypefn classification data-type name arguments...
    @deftypefnx classification data-type name arguments...
    Format a description for a function or similar entity that may take arguments and that is typed. @deftypefn takes as arguments the classification of entity being described, the type, the name of the entity, and its arguments, if any. See section Definition Commands, and section Two or More `First' Lines.
    @deftypefun data-type function-name arguments...
    @deftypefunx data-type function-name arguments...
    Format a description for a function in a typed language. The command is equivalent to `@deftypefn Function ...'. See section Definition Commands, and section Two or More `First' Lines.
    @deftypevr classification data-type name
    @deftypevrx classification data-type name
    Format a description for something like a variable in a typed language--an entity that records a value. Takes as arguments the classification of entity being described, the type, and the name of the entity. See section Definition Commands, and section Two or More `First' Lines.
    @deftypevar data-type variable-name
    @deftypevarx data-type variable-name
    Format a description for a variable in a typed language. The command is equivalent to `@deftypevr Variable ...'. See section Definition Commands, and section Two or More `First' Lines.
    @defun function-name arguments...
    @defunx function-name arguments...
    Format a description for functions. The command is equivalent to `@deffn Function ...'. See section Definition Commands, and section Two or More `First' Lines.
    @defvar variable-name
    @defvarx variable-name
    Format a description for variables. The command is equivalent to `@defvr Variable ...'. See section Definition Commands, and section Two or More `First' Lines.
    @defvr category name
    @defvrx category name
    Format a description for any kind of variable. @defvr takes as arguments the category of the entity and the name of the entity. See section Definition Commands, and section Two or More `First' Lines.
    @detailmenu{}
    Use to avoid Makeinfo confusion stemming from the detailed node listing in a master menu. See section Parts of a Master Menu.
    @dfn{term}
    Highlight the introductory or defining use of a term. See section @dfn{term}.
    @dircategory dirpart
    Specify a part of the Info directory menu where this file's entry should go. See section Installing Info Directory Files.
    @direntry
    Begin the Info directory menu entry for this file. See section Installing Info Directory Files.
    @display
    Begin a kind of example. Indent text, do not fill, do not select a new font. Pair with @end display. See section @display.
    @dmn{dimension}
    Format a unit of measure, as in 12pt. Causes TeX to insert a thin space before dimension. No effect in Info. See section @dmn{dimension}: Format a Dimension.
    @dots{}
    Insert an ellipsis: `...'. See section @dots{}.
    @email{address}
    Indicate an electronic mail address. See section @email{email-address}.
    @emph{text}
    Highlight text; text is displayed in italics in printed output, and surrounded by asterisks in Info. See section Emphasizing Text.
    @end environment
    Ends environment, as in `@end example'. See section @-commands.
    @enddots{}
    Generate an end-of-sentence of ellipsis, like this @enddots{} See section @dots{}.
    @enumerate [number-or-letter]
    Begin a numbered list, using @item for each entry. Optionally, start list with number-or-letter. Pair with @end enumerate. See section Making a Numbered or Lettered List.
    @equiv{}
    Indicate to the reader the exact equivalence of two forms with a glyph: `=='. See section ==: Indicating Equivalence.
    @error{}
    Indicate to the reader with a glyph that the following text is an error message: `error-->'. See section error-->: Indicating an Error Message.
    @evenfooting [left] @| [center] @| [right]
    Specify page footings for even-numbered (left-hand) pages. Not relevant to Info. See section How to Make Your Own Headings.
    @evenheading [left] @| [center] @| [right]
    Specify page headings for even-numbered (left-hand) pages. Only supported within @iftex. See section How to Make Your Own Headings.
    @everyfooting [left] @| [center] @| [right]
    @everyheading [left] @| [center] @| [right]
    Specify page footings resp. headings for every page. Not relevant to Info. See section How to Make Your Own Headings.
    @example
    Begin an example. Indent text, do not fill, and select fixed-width font. Pair with @end example. See section @example.
    @exclamdown{}
    Generate an upside-down exclamation point. See section Inserting Accents.
    @exdent line-of-text
    Remove any indentation a line might have. See section @exdent: Undoing a Line's Indentation.
    @expansion{}
    Indicate the result of a macro expansion to the reader with a special glyph: `==>'. See section ==>: Indicating an Expansion.
    @file{filename}
    Highlight the name of a file, buffer, node, or directory. See section @file{file-name}.
    @finalout
    Prevent TeX from printing large black warning rectangles beside over-wide lines. See section Overfull "hboxes".
    @findex entry
    Add entry to the index of functions. See section Making Index Entries.
    @flushleft
    @flushright
    Left justify every line but leave the right end ragged. Leave font as is. Pair with @end flushleft. @flushright analogous. See section @flushleft and @flushright.
    @footnote{text-of-footnote}
    Enter a footnote. Footnote text is printed at the bottom of the page by TeX; Info may format in either `End' node or `Separate' node style. See section Footnotes.
    @footnotestyle style
    Specify an Info file's footnote style, either `end' for the end node style or `separate' for the separate node style. See section Footnotes.
    @format
    Begin a kind of example. Like @example or @display, but do not narrow the margins and do not select the fixed-width font. Pair with @end format. See section @example.
    @ftable formatting-command
    Begin a two-column table, using @item for each entry. Automatically enter each of the items in the first column into the index of functions. Pair with @end ftable. The same as @table, except for indexing. See section @ftable and @vtable.
    @group
    Hold text together that must appear on one printed page. Pair with @end group. Not relevant to Info. See section @group: Prevent Page Breaks.
    @H{c}
    Generate the long Hungarian umlaut accent over c, as in @H{o}.
    @heading title
    Print an unnumbered section-like heading in the text, but not in the table of contents of a printed manual. In Info, the title is underlined with equal signs. See section @unnumberedsec, @appendixsec, @heading.
    @headings on-off-single-double
    Turn page headings on or off, and/or specify single-sided or double-sided page headings for printing. See section The @headings Command.
    @i{text}
    Print text in italic font. No effect in Info. See section Fonts for Printing, Not Info.
    @ifclear flag
    If flag is cleared, the Texinfo formatting commands format text between @ifclear flag and the following @end ifclear command. See section @set, @clear, and @value.
    @ifhtml
    @ifinfo
    Begin a stretch of text that will be ignored by TeX when it typesets the printed manual. The text appears only in the HTML resp. Info file. Pair with @end ifhtml resp. @end ifinfo. See section Conditionally Visible Text.
    @ifset flag
    If flag is set, the Texinfo formatting commands format text between @ifset flag and the following @end ifset command. See section @set, @clear, and @value.
    @iftex
    Begin a stretch of text that will not appear in the Info file, but will be processed only by TeX. Pair with @end iftex. See section Conditionally Visible Text.
    @ignore
    Begin a stretch of text that will not appear in either the Info file or the printed output. Pair with @end ignore. See section Comments.
    @include filename
    Incorporate the contents of the file filename into the Info file or printed document. See section Include Files.
    @inforef{node-name, [entry-name], info-file-name}
    Make a cross reference to an Info file for which there is no printed manual. See section @inforef.
    \input macro-definitions-file
    Use the specified macro definitions file. This command is used only in the first line of a Texinfo file to cause TeX to make use of the `texinfo' macro definitions file. The backslash in \input is used instead of an @ because TeX does not recognize @ until after it has read the definitions file. See section The Texinfo File Header.
    @item
    Indicate the beginning of a marked paragraph for @itemize and @enumerate; indicate the beginning of the text of a first column entry for @table, @ftable, and @vtable. See section Making Lists and Tables.
    @itemize mark-generating-character-or-command
    Produce a sequence of indented paragraphs, with a mark inside the left margin at the beginning of each paragraph. Pair with @end itemize. See section Making an Itemized List.
    @itemx
    Like @item but do not generate extra vertical space above the item text. See section @itemx.
    @kbd{keyboard-characters}
    Indicate text that is characters of input to be typed by users. See section @kbd{keyboard-characters}.
    @key{key-name}
    Highlight key-name, a name for a key on a keyboard. See section @key{key-name}.
    @kindex entry
    Add entry to the index of keys. See section Making Index Entries.
    @L{}
    @l{}
    Generate the uppercase and lowercase Polish suppressed-L letters, respectively: @L{}, @l{}.
    @global@letnew-command=existing-command
    Equate a new highlighting command with an existing one. Only for TeX. Write definition inside of @iftex ... @end iftex. See section Customized Highlighting.
    @lisp
    Begin an example of Lisp code. Indent text, do not fill, and select fixed-width font. Pair with @end lisp. See section @lisp.
    @lowersections
    Change subsequent chapters to sections, sections to subsections, and so on. See section @raisesections and @lowersections.
    @macro macro-name {params}
    Define a new Texinfo command @macro-name{params}. Only supported by Makeinfo and Texi2dvi. See section Defining Macros.
    @majorheading title
    Print a chapter-like heading in the text, but not in the table of contents of a printed manual. Generate more vertical whitespace before the heading than the @chapheading command. In Info, the chapter heading line is underlined with asterisks. See section @majorheading, @chapheading.
    @math{mathematical-expression}
    Format a mathematical expression. See section @math: Inserting Mathematical Expressions.
    @menu
    Mark the beginning of a menu of nodes in Info. No effect in a printed manual. Pair with @end menu. See section Menus.
    @minus{}
    Generate a minus sign, `-'. See section @minus{}: Inserting a Minus Sign.
    @multitable column-width-spec
    Begin a multi-column table. Pair with @end multitable. See section Multitable Column Widths.
    @need n
    Start a new page in a printed manual if fewer than n mils (thousandths of an inch) remain on the current page. See section @need mils: Prevent Page Breaks.
    @node name, next, previous, up
    Define the beginning of a new node in Info, and serve as a locator for references for TeX. See section The @node Command.
    @noindent
    Prevent text from being indented as if it were a new paragraph. See section @noindent.
    @O{}
    @o{}
    Generate the uppercase and lowercase Owith-slash letters, respectively: @O{}, @o{}.
    @oddfooting [left] @| [center] @| [right]
    @oddheading [left] @| [center] @| [right]
    Specify page footings resp. headings for odd-numbered (right-hand) pages. Only allowed inside @iftex. See section How to Make Your Own Headings.
    @OE{}
    @oe{}
    Generate the uppercase and lowercase OE ligatures, respectively: @OE{}, @oe{}. See section Inserting Accents.
    @page
    Start a new page in a printed manual. No effect in Info. See section @page: Start a New Page.
    @paragraphindent indent
    Indent paragraphs by indent number of spaces; delete indentation if the value of indent is 0; and do not change indentation if indent is asis. See section Paragraph Indenting.
    @pindex entry
    Add entry to the index of programs. See section Making Index Entries.
    @point{}
    Indicate the position of point in a buffer to the reader with a glyph: `-!-'. See section Indicating Point in a Buffer.
    @pounds{}
    Generate the pounds sterling currency sign. See section @pounds{}.
    @print{}
    Indicate printed output to the reader with a glyph: `-|'. See section -|: Indicating Printed Output.
    @printindex index-name
    Print an alphabetized two-column index in a printed manual or generate an alphabetized menu of index entries for Info. See section Index Menus and Printing an Index.
    @pxref{node-name, [entry], [topic-or-title], [info-file], [manual]}
    Make a reference that starts with a lower case `see' in a printed manual. Use within parentheses only. Do not follow command with a punctuation mark--the Info formatting commands automatically insert terminating punctuation as needed. Only the first argument is mandatory. See section @pxref.
    @questiondown{}
    Generate an upside-down question mark. See section Inserting Accents.
    @quotation
    Narrow the margins to indicate text that is quoted from another real or imaginary work. Write command on a line of its own. Pair with @end quotation. See section @quotation.
    @r{text}
    Print text in roman font. No effect in Info. See section Fonts for Printing, Not Info.
    @raisesections
    Change subsequent sections to chapters, subsections to sections, and so on. See section @raisesections and @lowersections.
    @ref{node-name, [entry], [topic-or-title], [info-file], [manual]}
    Make a reference. In a printed manual, the reference does not start with a `See'. Follow command with a punctuation mark. Only the first argument is mandatory. See section @ref.
    @refill
    In Info, refill and indent the paragraph after all the other processing has been done. No effect on TeX, which always refills. This command is no longer needed, since all formatters now automatically refill. See section Refilling Paragraphs.
    @result{}
    Indicate the result of an expression to the reader with a special glyph: `=>'. See section =>: Indicating Evaluation.
    @ringaccent{c}
    Generate a ring accent over the next character, as in @ringaccent{o}. See section Inserting Accents.
    @samp{text}
    Highlight text that is a literal example of a sequence of characters. Used for single characters, for statements, and often for entire shell commands. See section @samp{text}.
    @sc{text}
    Set text in a printed output in THE SMALL CAPS FONT and set text in the Info file in uppercase letters. See section @sc{text}: The Small Caps Font.
    @section title
    Begin a section within a chapter. In a printed manual, the section title is numbered and appears in the table of contents. In Info, the title is underlined with equal signs. See section @section.
    @set flag [string]
    Make flag active, causing the Texinfo formatting commands to format text between subsequent pairs of @ifset flag and @end ifset commands. Optionally, set value of flag to string. See section @set, @clear, and @value.
    @setchapternewpage on-off-odd
    Specify whether chapters start on new pages, and if so, whether on odd-numbered (right-hand) new pages. See section @setchapternewpage.
    @setfilename info-file-name
    Provide a name to be used by the Info file. This command is essential for TeX formatting as well, even though it produces no output. See section @setfilename.
    @settitle title
    Provide a title for page headers in a printed manual. See section @settitle.
    @shortcontents
    Print a short table of contents. Not relevant to Info, which uses menus rather than tables of contents. A synonym for @summarycontents. See section Generating a Table of Contents.
    @shorttitlepage{title}
    Generate a minimal title page. See section @titlepage.
    @smallbook
    Cause TeX to produce a printed manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format. See section Printing "Small" Books. Also, see section @smallexample and @smalllisp.
    @smallexample
    Indent text to indicate an example. Do not fill, select fixed-width font. In @smallbook format, print text in a smaller font than with @example. Pair with @end smallexample. See section @smallexample and @smalllisp.
    @smalllisp
    Begin an example of Lisp code. Indent text, do not fill, select fixed-width font. In @smallbook format, print text in a smaller font. Pair with @end smalllisp. See section @smallexample and @smalllisp.
    @sp n
    Skip n blank lines. See section @sp n: Insert Blank Lines.
    @ss{}
    Generate the German sharp-S es-zet letter, @ss{}. See section Inserting Accents.
    @strong text
    Emphasize text by typesetting it in a bold font for the printed manual and by surrounding it with asterisks for Info. See section @emph{text} and @strong{text}.
    @subheading title
    Print an unnumbered subsection-like heading in the text, but not in the table of contents of a printed manual. In Info, the title is underlined with hyphens. See section The @subsection-like Commands.
    @subsection title
    Begin a subsection within a section. In a printed manual, the subsection title is numbered and appears in the table of contents. In Info, the title is underlined with hyphens. See section The @subsection Command.
    @subsubheading title
    Print an unnumbered subsubsection-like heading in the text, but not in the table of contents of a printed manual. In Info, the title is underlined with periods. See section The `subsub' Commands.
    @subsubsection title
    Begin a subsubsection within a subsection. In a printed manual, the subsubsection title is numbered and appears in the table of contents. In Info, the title is underlined with periods. See section The `subsub' Commands.
    @subtitle title
    In a printed manual, set a subtitle in a normal sized font flush to the right-hand side of the page. Not relevant to Info, which does not have title pages. See section @title, @subtitle, and @author.
    @summarycontents
    Print a short table of contents. Not relevant to Info, which uses menus rather than tables of contents. A synonym for @shortcontents. See section Generating a Table of Contents.
    @syncodeindex from-index into-index
    Merge the index named in the first argument into the index named in the second argument, printing the entries from the first index in @code font. See section Combining Indices.
    @synindex from-index into-index
    Merge the index named in the first argument into the index named in the second argument. Do not change the font of from-index entries. See section Combining Indices.
    @t{text}
    Print text in a fixed-width, typewriter-like font. No effect in Info. See section Fonts for Printing, Not Info.
    @tab
    Separate columns in a multitable. See section Multitable Rows.
    @table formatting-command
    Begin a two-column table, using @item for each entry. Write each first column entry on the same line as @item. First column entries are printed in the font resulting from formatting-command. Pair with @end table. See section Making a Two-column Table. Also see section @ftable and @vtable, and section @itemx.
    @TeX{}
    Insert the logo TeX. See section Inserting TeX and the Copyright Symbol.
    @tex
    Enter TeX completely. Pair with @end tex. See section Using Ordinary TeX Commands.
    @thischapter
    @thischaptername
    @thisfile
    @thispage
    @thistitle
    Only allowed in a heading or footing. Stands for the number and name of the current chapter (in the format `Chapter 1: Title'), the chapter name only, the filename, the current page number, and the title of the document, respectively. See section How to Make Your Own Headings.
    @tindex entry
    Add entry to the index of data types. See section Making Index Entries.
    @title title
    In a printed manual, set a title flush to the left-hand side of the page in a larger than normal font and underline it with a black rule. Not relevant to Info, which does not have title pages. See section @title, @subtitle, and @author.
    @titlefont{text}
    In a printed manual, print text in a larger than normal font. Not relevant to Info, which does not have title pages. See section @titlefont, @center, and @sp.
    @titlepage
    Indicate to Texinfo the beginning of the title page. Write command on a line of its own. Pair with @end titlepage. Nothing between @titlepage and @end titlepage appears in Info. See section @titlepage.
    @today{}
    Insert the current date, in `1 Jan 1900' style. See section How to Make Your Own Headings.
    @top title
    In a Texinfo file to be formatted with makeinfo, identify the topmost @node line in the file, which must be written on the line immediately preceding the @top command. Used for makeinfo's node pointer insertion feature. The title is underlined with asterisks. Both the @node line and the @top line normally should be enclosed by @ifinfo and @end ifinfo. In TeX and texinfo-format-buffer, the @top command is merely a synonym for @unnumbered. See section Creating Pointers with makeinfo.
    @uc
    @ubaraccentc
    @udotaccentc
    Generate a breve, underbar, or underdot accent, respectively, over or under the character c, as in @u{o}, @ubaraccent{o}, @udotaccent{o}. See section Inserting Accents.
    @unnumbered title
    In a printed manual, begin a chapter that appears without chapter numbers of any kind. The title appears in the table of contents of a printed manual. In Info, the title is underlined with asterisks. See section @unnumbered, @appendix.
    @unnumberedsec title
    In a printed manual, begin a section that appears without section numbers of any kind. The title appears in the table of contents of a printed manual. In Info, the title is underlined with equal signs. See section @unnumberedsec, @appendixsec, @heading.
    @unnumberedsubsec title
    In a printed manual, begin an unnumbered subsection within a chapter. The title appears in the table of contents of a printed manual. In Info, the title is underlined with hyphens. See section The @subsection-like Commands.
    @unnumberedsubsubsec title
    In a printed manual, begin an unnumbered subsubsection within a chapter. The title appears in the table of contents of a printed manual. In Info, the title is underlined with periods. See section The `subsub' Commands.
    @url{url}
    Highlight text that is a uniform resource locator for the World Wide Web. See section @url{uniform-resource-locator}.
    @vc
    Generate check accent over the character c, as in @v{o}. See section Inserting Accents.
    @value{flag}
    Replace flag with the value to which it is set by @set flag. See section @set, @clear, and @value.
    @var{metasyntactic-variable}
    Highlight a metasyntactic variable, which is something that stands for another piece of text. See section @var{metasyntactic-variable}.
    @vindex entry
    Add entry to the index of variables. See section Making Index Entries.
    @vskip amount
    In a printed manual, insert whitespace so as to push text on the remainder of the page towards the bottom of the page. Used in formatting the copyright page with the argument `0pt plus 1filll'. (Note spelling of `filll'.) @vskip may be used only in contexts ignored for Info. See section Copyright Page and Permissions.
    @vtable formatting-command
    Begin a two-column table, using @item for each entry. Automatically enter each of the items in the first column into the index of variables. Pair with @end vtable. The same as @table, except for indexing. See section @ftable and @vtable.
    @w{text}
    Prevent text from being split across two lines. Do not end a paragraph that uses @w with an @refill command. See section @w{text}: Prevent Line Breaks.
    @xref{node-name, [entry], [topic-or-title], [info-file], [manual]}
    Make a reference that starts with `See' in a printed manual. Follow command with a punctuation mark. Only the first argument is mandatory. See section @xref.

    Tips and Hints

    Here are some tips for writing Texinfo documentation:

    • Write in the present tense, not in the past or the future.
    • Write actively! For example, write "We recommend that ..." rather than "It is recommended that ...".
    • Use 70 or 72 as your fill column. Longer lines are hard to read.
    • Include a copyright notice and copying permissions.

    Index, index, index!

    Write many index entries, in different ways. Readers like indices; they are helpful and convenient.

    Although it is easiest to write index entries as you write the body of the text, some people prefer to write entries afterwards. In either case, write an entry before the paragraph to which it applies. This way, an index entry points to the first page of a paragraph that is split across pages.

    Here are more hints we have found valuable:

    • Write each index entry differently, so each entry refers to a different place in the document.
    • Write index entries only where a topic is discussed significantly. For example, it is not useful to index "debugging information" in a chapter on reporting bugs. Someone who wants to know about debugging information will certainly not find it in that chapter.
    • Consistently capitalize the first word of every concept index entry, or else consistently use lower case. Terse entries often call for lower case; longer entries for capitalization. Whichever case convention you use, please use one or the other consistently! Mixing the two styles looks bad.
    • Always capitalize or use upper case for those words in an index for which this is proper, such as names of countries or acronyms. Always use the appropriate case for case-sensitive names, such as those in C or Lisp.
    • Write the indexing commands that refer to a whole section immediately after the section command, and write the indexing commands that refer to the paragraph before the paragraph. In the example that follows, a blank line comes after the index entry for "Leaping":
      @section The Dog and the Fox
@cindex Jumping, in general
@cindex Leaping

@cindex Dog, lazy, jumped over
@cindex Lazy dog jumped over
@cindex Fox, jumps over dog
@cindex Quick fox jumps over dog
The quick brown fox jumps over the lazy dog.
      (Note that the example shows entries for the same concept that are written in different ways---`Lazy dog', and `Dog, lazy'---so readers can look up the concept in different ways.)

    Blank lines

    • Insert a blank line between a sectioning command and the first following sentence or paragraph, or between the indexing commands associated with the sectioning command and the first following sentence or paragraph, as shown in the tip on indexing. Otherwise, a formatter may fold title and paragraph together.
    • Always insert a blank line before an @table command and after an @end table command; but never insert a blank line after an @table command or before an @end table command. For example,
      Types of fox:

@table @samp
@item Quick
Jump over lazy dogs.

@item Brown
Also jump over lazy dogs.
@end table

@noindent
On the other hand, ...
      Insert blank lines before and after @itemize ... @end itemize and @enumerate ... @end enumerate in the same way.

    Complete phrases

    Complete phrases are easier to read than ...

    • Write entries in an itemized list as complete sentences; or at least, as complete phrases. Incomplete expressions ... awkward ... like this.
    • Write the prefatory sentence or phrase for a multi-item list or table as a complete expression. Do not write "You can set:"; instead, write "You can set these variables:". The former expression sounds cut off.

    Editions, dates and versions

    Write the edition and version numbers and date in three places in every manual:

    1. In the first @ifinfo section, for people reading the Texinfo file.
    2. In the @titlepage section, for people reading the printed manual.
    3. In the `Top' node, for people reading the Info file.

    Also, it helps to write a note before the first @ifinfo section to explain what you are doing.

    For example:

    @c ===> NOTE! <==
@c Specify the edition and version numbers and date
@c in *three* places:
@c   1. First ifinfo section  2. title page  3. top node
@c To find the locations, search for !!set

@ifinfo
@c !!set edition, date, version
This is Edition 4.03, January 1992,
of the @cite{GDB Manual} for GDB Version 4.3.
...

    ---or use @set and @value (see section @value Example).

    Definition Commands

    Definition commands are @deffn, @defun, @defmac, and the like, and enable you to write descriptions in a uniform format.

    • Write just one definition command for each entity you define with a definition command. The automatic indexing feature creates an index entry that leads the reader to the definition.
    • Use @table ... @end table in an appendix that contains a summary of functions, not @deffn or other definition commands.

    Capitalization

    • Capitalize `Texinfo'; it is a name. Do not write the `x' or `i' in upper case.
    • Capitalize `Info'; it is a name.
    • Write TeX using the @TeX{} command. Note the uppercase `T' and `X'. This command causes the formatters to typeset the name according to the wishes of Donald Knuth, who wrote TeX.

    Spaces

    Do not use spaces to format a Texinfo file, except inside of @example ... @end example and similar commands.

    For example, TeX fills the following:

        @kbd{C-x v}
    @kbd{M-x vc-next-action}
       Perform the next logical operation
       on the version-controlled file
       corresponding to the current buffer.

    so it looks like this:

    C-x v M-x vc-next-action Perform the next logical operation on the version-controlled file corresponding to the current buffer.

    In this case, the text should be formatted with @table, @item, and @itemx, to create a table.

    @code, @samp, @var, and `---'

    • Use @code around Lisp symbols, including command names. For example,
      The main function is @code{vc-next-action}, ...
    • Avoid putting letters such as `s' immediately after an `@code'. Such letters look bad.
    • Use @var around meta-variables. Do not write angle brackets around them.
    • Use three hyphens in a row, `---', to indicate a long dash. TeX typesets these as a long dash and the Info formatters reduce three hyphens to two.

    Periods Outside of Quotes

    Place periods and other punctuation marks outside of quotations, unless the punctuation is part of the quotation. This practice goes against publishing conventions in the United States, but enables the reader to distinguish between the contents of the quotation and the whole passage.

    For example, you should write the following sentence with the period outside the end quotation marks:

    Evidently, `au' is an abbreviation for ``author''.

    since `au' does not serve as an abbreviation for `author.' (with a period following the word).

    Introducing New Terms

    • Introduce new terms so that a reader who does not know them can understand them from context; or write a definition for the term. For example, in the following, the terms "check in", "register" and "delta" are all appearing for the first time; the example sentence should be rewritten so they are understandable.

      The major function assists you in checking in a file to your version control system and registering successive sets of changes to it as deltas.

    • Use the @dfn command around a word being introduced, to indicate that the reader should not expect to know the meaning already, and should expect to learn the meaning from this passage.

    @pxref

    Absolutely never use @pxref except in the special context for which it is designed: inside parentheses, with the closing parenthesis following immediately after the closing brace. One formatter automatically inserts closing punctuation and the other does not. This means that the output looks right both in printed output and in an Info file, but only when the command is used inside parentheses.

    Invoking from a Shell

    You can invoke programs such as Emacs, GCC, and GAWK from a shell. The documentation for each program should contain a section that describes this. Unfortunately, if the node names and titles for these sections are all different, readers find it hard to search for the section.

    Name such sections with a phrase beginning with the word `Invoking ...', as in `Invoking Emacs'; this way users can find the section easily.

    ANSI C Syntax

    When you use @example to describe a C function's calling conventions, use the ANSI C syntax, like this:

    void dld_init (char *@var{path});

    And in the subsequent discussion, refer to the argument values by writing the same argument names, again highlighted with @var.

    Avoid the obsolete style that looks like this:

    #include <dld.h>

dld_init (path)
char *path;

    Also, it is best to avoid writing #include above the declaration just to indicate that the function is declared in a header file. The practice may give the misimpression that the #include belongs near the declaration of the function. Either state explicitly which header file holds the declaration or, better yet, name the header file used for a group of functions at the beginning of the section that describes the functions.

    Bad Examples

    Here are several examples of bad writing to avoid:

    In this example, say, " ... you must @dfn{check in} the new version." That flows better.

    When you are done editing the file, you must perform a @dfn{check in}.

    In the following example, say, "... makes a unified interface such as VC mode possible."

    SCCS, RCS and other version-control systems all perform similar functions in broadly similar ways (it is this resemblance which makes a unified control mode like this possible).

    And in this example, you should specify what `it' refers to:

    If you are working with other people, it assists in coordinating everyone's changes so they do not step on each other.

    And Finally ...

    • Pronounce TeX as if the `X' were a Greek `chi', as the last sound in the name `Bach'. But pronounce Texinfo as in `speck': `teckinfo'.
    • Write notes for yourself at the very end of a Texinfo file after the @bye. None of the formatters process text after the @bye; it is as if the text were within @ignore ... @end ignore.

    A Sample Texinfo File

    Here is a complete, short sample Texinfo file, without any commentary. You can see this file, with comments, in the first chapter. See section A Short Sample Texinfo File.

    \input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sample.info
@settitle Sample Document
@c %**end of header

@setchapternewpage odd

@ifinfo
This is a short example of a complete Texinfo file.

Copyright 1990 Free Software Foundation, Inc.
@end ifinfo

@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Sample Title}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

@node    Top,       First Chapter, (dir),    (dir)
@comment node-name, next,          previous, up

@menu
* First Chapter::    The first chapter is the
                     only chapter in this sample.
* Concept Index::    This index has two entries.
@end menu

@node    First Chapter, Concept Index, Top,      Top
@comment node-name,     next,          previous, up
@chapter First Chapter
@cindex Sample index entry

This is the contents of the first chapter.
@cindex Another sample index entry

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

The @code{makeinfo} and @code{texinfo-format-buffer}
commands transform a Texinfo file such as this into
an Info file; and @TeX{} typesets it for a printed
manual.

@node    Concept Index,    ,  First Chapter, Top
@comment node-name,    next,  previous,      up
@unnumbered Concept Index

@printindex cp

@contents
@bye

    Sample Permissions

    Texinfo files should contain sections that tell the readers that they have the right to copy and distribute the Texinfo file, the Info file, and the printed manual.

    Also, if you are writing a manual about software, you should explain that the software is free and either include the GNU General Public License (GPL) or provide a reference to it. See section `Distribution' in The GNU Emacs Manual, for an example of the text that could be used in the software "Distribution", "General Public License", and "NO WARRANTY" sections of a document. See section Texinfo Copying Conditions, for an example of a brief explanation of how the copying conditions provide you with rights.

    In a Texinfo file, the first @ifinfo section usually begins with a line that says what the file documents. This is what a person reading the unprocessed Texinfo file or using the advanced Info command g * sees first. See Info file `info', node `Expert', for more information. (A reader using the regular Info commands usually starts reading at the first node and skips this first section, which is not in a node.)

    In the @ifinfo section, the summary sentence is followed by a copyright notice and then by the copying permission notice. One of the copying permission paragraphs is enclosed in @ignore and @end ignore commands. This paragraph states that the Texinfo file can be processed through TeX and printed, provided the printed manual carries the proper copying permission notice. This paragraph is not made part of the Info file since it is not relevant to the Info file; but it is a mandatory part of the Texinfo file since it permits people to process the Texinfo file in TeX and print the results.

    In the printed manual, the Free Software Foundation copying permission notice follows the copyright notice and publishing information and is located within the region delineated by the @titlepage and @end titlepage commands. The copying permission notice is exactly the same as the notice in the @ifinfo section except that the paragraph enclosed in @ignore and @end ignore commands is not part of the notice.

    To make it simple to insert a permission notice into each section of the Texinfo file, sample permission notices for each section are reproduced in full below.

    Note that you may need to specify the correct name of a section mentioned in the permission notice. For example, in The GDB Manual, the name of the section referring to the General Public License is called the "GDB General Public License", but in the sample shown below, that section is referred to generically as the "GNU General Public License". If the Texinfo file does not carry a copy of the General Public License, leave out the reference to it, but be sure to include the rest of the sentence.

    `ifinfo' Copying Permissions

    In the @ifinfo section of a Texinfo file, the standard Free Software Foundation permission notice reads as follows:

    This file documents ...

Copyright 1992 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

    Titlepage Copying Permissions

    In the @titlepage section of a Texinfo file, the standard Free Software Foundation copying permission notice follows the copyright notice and publishing information. The standard phrasing is as follows:

    Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and
this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified
versions of this manual under the conditions for
verbatim copying, provided also that the sections
entitled ``Copying'' and ``GNU General Public License''
are included exactly as in the original, and provided
that the entire resulting derived work is distributed
under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute
translations of this manual into another language,
under the above conditions for modified versions,
except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

    Include Files

    When TeX or an Info formatting command sees an @include command in a Texinfo file, it processes the contents of the file named by the command and incorporates them into the DVI or Info file being created. Index entries from the included file are incorporated into the indices of the output file.

    Include files let you keep a single large document as a collection of conveniently small parts.

    How to Use Include Files

    To include another file within a Texinfo file, write the @include command at the beginning of a line and follow it on the same line by the name of a file to be included. For example:

    @include buffers.texi

    An included file should simply be a segment of text that you expect to be included as is into the overall or outer Texinfo file; it should not contain the standard beginning and end parts of a Texinfo file. In particular, you should not start an included file with a line saying `\input texinfo'; if you do, that phrase is inserted into the output file as is. Likewise, you should not end an included file with an @bye command; nothing after @bye is formatted.

    In the past, you were required to write an @setfilename line at the beginning of an included file, but no longer. Now, it does not matter whether you write such a line. If an @setfilename line exists in an included file, it is ignored.

    Conventionally, an included file begins with an @node line that is followed by an @chapter line. Each included file is one chapter. This makes it easy to use the regular node and menu creating and updating commands to create the node pointers and menus within the included file. However, the simple Emacs node and menu creating and updating commands do not work with multiple Texinfo files. Thus you cannot use these commands to fill in the `Next', `Previous', and `Up' pointers of the @node line that begins the included file. Also, you cannot use the regular commands to create a master menu for the whole file. Either you must insert the menus and the `Next', `Previous', and `Up' pointers by hand, or you must use the GNU Emacs Texinfo mode command, texinfo-multiple-files-update, that is designed for @include files.

    texinfo-multiple-files-update

    GNU Emacs Texinfo mode provides the texinfo-multiple-files-update command. This command creates or updates `Next', `Previous', and `Up' pointers of included files as well as those in the outer or overall Texinfo file, and it creates or updates a main menu in the outer file. Depending whether you call it with optional arguments, the command updates only the pointers in the first @node line of the included files or all of them:

    M-x texinfo-multiple-files-update
    Called without any arguments:
    • Create or update the `Next', `Previous', and `Up' pointers of the first @node line in each file included in an outer or overall Texinfo file.
    • Create or update the `Top' level node pointers of the outer or overall file.
    • Create or update a main menu in the outer file.
    C-u M-x texinfo-multiple-files-update
    Called with C-u as a prefix argument:
    • Create or update pointers in the first @node line in each included file.
    • Create or update the `Top' level node pointers of the outer file.
    • Create and insert a master menu in the outer file. The master menu is made from all the menus in all the included files.
    C-u 8 M-x texinfo-multiple-files-update
    Called with a numeric prefix argument, such as C-u 8:
    • Create or update all the `Next', `Previous', and `Up' pointers of all the included files.
    • Create or update all the menus of all the included files.
    • Create or update the `Top' level node pointers of the outer or overall file.
    • And then create a master menu in the outer file. This is similar to invoking texinfo-master-menu with an argument when you are working with just one file.

    Note the use of the prefix argument in interactive use: with a regular prefix argument, just C-u, the texinfo-multiple-files-update command inserts a master menu; with a numeric prefix argument, such as C-u 8, the command updates every pointer and menu in all the files and then inserts a master menu.

    Include File Requirements

    If you plan to use the texinfo-multiple-files-update command, the outer Texinfo file that lists included files within it should contain nothing but the beginning and end parts of a Texinfo file, and a number of @include commands listing the included files. It should not even include indices, which should be listed in an included file of their own.

    Moreover, each of the included files must contain exactly one highest level node (conventionally, @chapter or equivalent), and this node must be the first node in the included file. Furthermore, each of these highest level nodes in each included file must be at the same hierarchical level in the file structure. Usually, each is an @chapter, an @appendix, or an @unnumbered node. Thus, normally, each included file contains one, and only one, chapter or equivalent-level node.

    The outer file should contain only one node, the `Top' node. It should not contain any nodes besides the single `Top' node. The texinfo-multiple-files-update command will not process them.

    Sample File with @include

    Here is an example of a complete outer Texinfo file with @include files within it before running texinfo-multiple-files-update, which would insert a main or master menu:

    \input texinfo @c -*-texinfo-*-
@setfilename  include-example.info
@settitle Include Example

@setchapternewpage odd
@titlepage
@sp 12
@center @titlefont{Include Example}
@sp 2
@center by Whom Ever

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Free Software Foundation, Inc.
@end titlepage

@ifinfo
@node Top, First, (dir), (dir)
@top Master Menu
@end ifinfo

@include foo.texinfo
@include bar.texinfo
@include concept-index.texinfo

@summarycontents
@contents

@bye

    An included file, such as `foo.texinfo', might look like this:

    @node First, Second, , Top
@chapter First Chapter

Contents of first chapter ...

    The full contents of `concept-index.texinfo' might be as simple as this:

    @node Concept Index, , Second, Top
@unnumbered Concept Index

@printindex cp

    The outer Texinfo source file for The GNU Emacs Lisp Reference Manual is named `elisp.texi'. This outer file contains a master menu with 417 entries and a list of 41 @include files.

    Evolution of Include Files

    When Info was first created, it was customary to create many small Info files on one subject. Each Info file was formatted from its own Texinfo source file. This custom meant that Emacs did not need to make a large buffer to hold the whole of a large Info file when someone wanted information; instead, Emacs allocated just enough memory for the small Info file that contained the particular information sought. This way, Emacs could avoid wasting memory.

    References from one file to another were made by referring to the file name as well as the node name. (See section Referring to Other Info Files. Also, see section @xref with Four and Five Arguments.)

    Include files were designed primarily as a way to create a single, large printed manual out of several smaller Info files. In a printed manual, all the references were within the same document, so TeX could automatically determine the references' page numbers. The Info formatting commands used include files only for creating joint indices; each of the individual Texinfo files had to be formatted for Info individually. (Each, therefore, required its own @setfilename line.)

    However, because large Info files are now split automatically, it is no longer necessary to keep them small.

    Nowadays, multiple Texinfo files are used mostly for large documents, such as The GNU Emacs Lisp Reference Manual, and for projects in which several different people write different sections of a document simultaneously.

    In addition, the Info formatting commands have been extended to work with the @include command so as to create a single large Info file that is split into smaller files if necessary. This means that you can write menus and cross references without naming the different Texinfo files.

    Page Headings

    Most printed manuals contain headings along the top of every page except the title and copyright pages. Some manuals also contain footings. (Headings and footings have no meaning to Info, which is not paginated.)

    Texinfo provides standard page heading formats for manuals that are printed on one side of each sheet of paper and for manuals that are printed on both sides of the paper. Usually, you will use one or other of these formats, but you can specify your own format, if you wish.

    In addition, you can specify whether chapters should begin on a new page, or merely continue the same page as the previous chapter; and if chapters begin on new pages, you can specify whether they must be odd-numbered pages.

    By convention, a book is printed on both sides of each sheet of paper. When you open a book, the right-hand page is odd-numbered, and chapters begin on right-hand pages--a preceding left-hand page is left blank if necessary. Reports, however, are often printed on just one side of paper, and chapters begin on a fresh page immediately following the end of the preceding chapter. In short or informal reports, chapters often do not begin on a new page at all, but are separated from the preceding text by a small amount of whitespace.

    The @setchapternewpage command controls whether chapters begin on new pages, and whether one of the standard heading formats is used. In addition, Texinfo has several heading and footing commands that you can use to generate your own heading and footing formats.

    In Texinfo, headings and footings are single lines at the tops and bottoms of pages; you cannot create multiline headings or footings. Each header or footer line is divided into three parts: a left part, a middle part, and a right part. Any part, or a whole line, may be left blank. Text for the left part of a header or footer line is set flushleft; text for the middle part is centered; and, text for the right part is set flushright.

    Standard Heading Formats

    Texinfo provides two standard heading formats, one for manuals printed on one side of each sheet of paper, and the other for manuals printed on both sides of the paper.

    By default, nothing is specified for the footing of a Texinfo file, so the footing remains blank.

    The standard format for single-sided printing consists of a header line in which the left-hand part contains the name of the chapter, the central part is blank, and the right-hand part contains the page number.

    A single-sided page looks like this:

       _______________________
  |                       |
  | chapter   page number |
  |                       |
  | Start of text ...     |
  | ...                   |
  |                       |

    The standard format for two-sided printing depends on whether the page number is even or odd. By convention, even-numbered pages are on the left- and odd-numbered pages are on the right. (TeX will adjust the widths of the left- and right-hand margins. Usually, widths are correct, but during double-sided printing, it is wise to check that pages will bind properly--sometimes a printer will produce output in which the even-numbered pages have a larger right-hand margin than the odd-numbered pages.)

    In the standard double-sided format, the left part of the left-hand (even-numbered) page contains the page number, the central part is blank, and the right part contains the title (specified by the @settitle command). The left part of the right-hand (odd-numbered) page contains the name of the chapter, the central part is blank, and the right part contains the page number.

    Two pages, side by side as in an open book, look like this:

       _______________________     _______________________
  |                       |   |                       |
  | page number     title |   | chapter   page number |
  |                       |   |                       |
  | Start of text ...     |   | More  text ...        |
  | ...                   |   | ...                   |
  |                       |   |                       |

    The chapter name is preceded by the word `Chapter', the chapter number and a colon. This makes it easier to keep track of where you are in the manual.

    Specifying the Type of Heading

    TeX does not begin to generate page headings for a standard Texinfo file until it reaches the @end titlepage command. Thus, the title and copyright pages are not numbered. The @end titlepage command causes TeX to begin to generate page headings according to a standard format specified by the @setchapternewpage command that precedes the @titlepage section.

    There are four possibilities:

    No @setchapternewpage command
    Cause TeX to specify the single-sided heading format, with chapters on new pages. This is the same as @setchapternewpage on.
    @setchapternewpage on
    Specify the single-sided heading format, with chapters on new pages.
    @setchapternewpage off
    Cause TeX to start a new chapter on the same page as the last page of the preceding chapter, after skipping some vertical whitespace. Also cause TeX to typeset for single-sided printing. (You can override the headers format with the @headings double command; see section The @headings Command.)
    @setchapternewpage odd
    Specify the double-sided heading format, with chapters on new pages.

    Texinfo lacks an @setchapternewpage even command.

    How to Make Your Own Headings

    You can use the standard headings provided with Texinfo or specify your own.

    Texinfo provides six commands for specifying headings and footings. The @everyheading command and @everyfooting command generate page headers and footers that are the same for both even- and odd-numbered pages. The @evenheading command and @evenfooting command generate headers and footers for even-numbered (left-hand) pages; and the @oddheading command and @oddfooting command generate headers and footers for odd-numbered (right-hand) pages.

    Write custom heading specifications in the Texinfo file immediately after the @end titlepage command. Enclose your specifications between @iftex and @end iftex commands since the texinfo-format-buffer command may not recognize them. Also, you must cancel the predefined heading commands with the @headings off command before defining your own specifications.

    Here is how to tell TeX to place the chapter name at the left, the page number in the center, and the date at the right of every header for both even- and odd-numbered pages:

    @iftex
@headings off
@everyheading @thischapter @| @thispage @| @today{}
@end iftex

    You need to divide the left part from the central part and the central part from the right had part by inserting `@|' between parts. Otherwise, the specification command will not be able to tell where the text for one part ends and the next part begins.

    Each part can contain text or @-commands. The text is printed as if the part were within an ordinary paragraph in the body of the page. The @-commands replace themselves with the page number, date, chapter name, or whatever.

    Here are the six heading and footing commands:

    @everyheading left @| center @| right
    @everyfooting left @| center @| right
    The `every' commands specify the format for both even- and odd-numbered pages. These commands are for documents that are printed on one side of each sheet of paper, or for documents in which you want symmetrical headers or footers.
    @evenheading left @| center @| right
    @oddheading left @| center @| right
    @evenfooting left @| center @| right
    @oddfooting left @| center @| right
    The `even' and `odd' commands specify the format for even-numbered pages and odd-numbered pages. These commands are for books and manuals that are printed on both sides of each sheet of paper.

    Use the `@this...' series of @-commands to provide the names of chapters and sections and the page number. You can use the `@this...' commands in the left, center, or right portions of headers and footers, or anywhere else in a Texinfo file so long as they are between @iftex and @end iftex commands.

    Here are the `@this...' commands:

    @thispage
    Expands to the current page number.
    @thischaptername
    Expands to the name of the current chapter.
    @thischapter
    Expands to the number and name of the current chapter, in the format `Chapter 1: Title'.
    @thistitle
    Expands to the name of the document, as specified by the @settitle command.
    @thisfile
    For @include files only: expands to the name of the current @include file. If the current Texinfo source file is not an @include file, this command has no effect. This command does not provide the name of the current Texinfo source file unless it is an @include file. (See section Include Files, for more information about @include files.)

    You can also use the @today{} command, which expands to the current date, in `1 Jan 1900' format.

    Other @-commands and text are printed in a header or footer just as if they were in the body of a page. It is useful to incorporate text, particularly when you are writing drafts:

    @iftex
@headings off
@everyheading @emph{Draft!} @| @thispage @| @thischapter
@everyfooting @| @| Version: 0.27: @today{}
@end iftex

    Beware of overlong titles: they may overlap another part of the header or footer and blot it out.

    Formatting Mistakes

    Besides mistakes in the content of your documentation, there are two kinds of mistake you can make with Texinfo: you can make mistakes with @-commands, and you can make mistakes with the structure of the nodes and chapters.

    Emacs has two tools for catching the @-command mistakes and two for catching structuring mistakes.

    For finding problems with @-commands, you can run TeX or a region formatting command on the region that has a problem; indeed, you can run these commands on each region as you write it.

    For finding problems with the structure of nodes and chapters, you can use C-c C-s (texinfo-show-structure) and the related occur command and you can use the M-x Info-validate command.

    The makeinfo program does an excellent job of catching errors and reporting them--far better than texinfo-format-region or texinfo-format-buffer. In addition, the various functions for automatically creating and updating node pointers and menus remove many opportunities for human error.

    If you can, use the updating commands to create and insert pointers and menus. These prevent many errors. Then use makeinfo (or its Texinfo mode manifestations, makeinfo-region and makeinfo-buffer) to format your file and check for other errors. This is the best way to work with Texinfo. But if you cannot use makeinfo, or your problem is very puzzling, then you may want to use the tools described in this appendix.

    Catching Errors with Info Formatting

    After you have written part of a Texinfo file, you can use the texinfo-format-region or the makeinfo-region command to see whether the region formats properly.

    Most likely, however, you are reading this section because for some reason you cannot use the makeinfo-region command; therefore, the rest of this section presumes that you are using texinfo-format-region.

    If you have made a mistake with an @-command, texinfo-format-region will stop processing at or after the error and display an error message. To see where in the buffer the error occurred, switch to the `*Info Region*' buffer; the cursor will be in a position that is after the location of the error. Also, the text will not be formatted after the place where the error occurred (or more precisely, where it was detected).

    For example, if you accidentally end a menu with the command @end menus with an `s' on the end, instead of with @end menu, you will see an error message that says:

    @end menus is not handled by texinfo

    The cursor will stop at the point in the buffer where the error occurs, or not long after it. The buffer will look like this:

    ---------- Buffer: *Info Region* ----------
* Menu:

* Using texinfo-show-structure::  How to use
                                  `texinfo-show-structure'
                                  to catch mistakes.
* Running Info-Validate::         How to check for
                                  unreferenced nodes.
@end menus
-!-
---------- Buffer: *Info Region* ----------

    The texinfo-format-region command sometimes provides slightly odd error messages. For example, the following cross reference fails to format:

    (@xref{Catching Mistakes, for more info.)

    In this case, texinfo-format-region detects the missing closing brace but displays a message that says `Unbalanced parentheses' rather than `Unbalanced braces'. This is because the formatting command looks for mismatches between braces as if they were parentheses.

    Sometimes texinfo-format-region fails to detect mistakes. For example, in the following, the closing brace is swapped with the closing parenthesis:

    (@xref{Catching Mistakes), for more info.}

    Formatting produces:

    (*Note for more info.: Catching Mistakes)

    The only way for you to detect this error is to realize that the reference should have looked like this:

    (*Note Catching Mistakes::, for more info.)

    Incidentally, if you are reading this node in Info and type f RET (Info-follow-reference), you will generate an error message that says:

    No such node: "Catching Mistakes) The only way ...

    This is because Info perceives the example of the error as the first cross reference in this node and if you type a RET immediately after typing the Info f command, Info will attempt to go to the referenced node. If you type f catch TAB RET, Info will complete the node name of the correctly written example and take you to the `Catching Mistakes' node. (If you try this, you can return from the `Catching Mistakes' node by typing l (Info-last).)

    Catching Errors with TeX Formatting

    You can also catch mistakes when you format a file with TeX.

    Usually, you will want to do this after you have run texinfo-format-buffer (or, better, makeinfo-buffer) on the same file, because texinfo-format-buffer sometimes displays error messages that make more sense than TeX. (See section Catching Errors with Info Formatting, for more information.)

    For example, TeX was run on a Texinfo file, part of which is shown here:

    ---------- Buffer: texinfo.texi ----------
name of the Texinfo file as an extension.  The
@samp{??} are `wildcards' that cause the shell to
substitute all the raw index files.  (@xref{sorting
indices, for more information about sorting
indices.)@refill
---------- Buffer: texinfo.texi ----------

    (The cross reference lacks a closing brace.) TeX produced the following output, after which it stopped:

    ---------- Buffer: *tex-shell* ----------
Runaway argument?
{sorting indices, for more information about sorting
indices.) @refill @ETC.
! Paragraph ended before @xref was complete.
<to be read again>
                   @par
l.27

?
---------- Buffer: *tex-shell* ----------

    In this case, TeX produced an accurate and understandable error message:

    Paragraph ended before @xref was complete.

    `@par' is an internal TeX command of no relevance to Texinfo. `l.27' means that TeX detected the problem on line 27 of the Texinfo file. The `?' is the prompt TeX uses in this circumstance.

    Unfortunately, TeX is not always so helpful, and sometimes you must truly be a Sherlock Holmes to discover what went wrong.

    In any case, if you run into a problem like this, you can do one of three things.

    1. You can tell TeX to continue running and ignore just this error by typing RET at the `?' prompt.
    2. You can tell TeX to continue running and to ignore all errors as best it can by typing r RET at the `?' prompt. This is often the best thing to do. However, beware: the one error may produce a cascade of additional error messages as its consequences are felt through the rest of the file. (To stop TeX when it is producing such an avalanche of error messages, type C-d (or C-c C-d, if you are running a shell inside Emacs.))
    3. You can tell TeX to stop this run by typing x RET at the `?' prompt.

    Please note that if you are running TeX inside Emacs, you need to switch to the shell buffer and line at which TeX offers the `?' prompt.

    Sometimes TeX will format a file without producing error messages even though there is a problem. This usually occurs if a command is not ended but TeX is able to continue processing anyhow. For example, if you fail to end an itemized list with the @end itemize command, TeX will write a DVI file that you can print out. The only error message that TeX will give you is the somewhat mysterious comment that

    (@end occurred inside a group at level 1)

    However, if you print the DVI file, you will find that the text of the file that follows the itemized list is entirely indented as if it were part of the last item in the itemized list. The error message is the way TeX says that it expected to find an @end command somewhere in the file; but that it could not determine where it was needed.

    Another source of notoriously hard-to-find errors is a missing @end group command. If you ever are stumped by incomprehensible errors, look for a missing @end group command first.

    If the Texinfo file lacks header lines, TeX may stop in the beginning of its run and display output that looks like the following. The `*' indicates that TeX is waiting for input.

    This is TeX, Version 3.14159 (Web2c 7.0)
(test.texinfo [1])
*

    In this case, simply type \end RET after the asterisk. Then write the header lines in the Texinfo file and run the TeX command again. (Note the use of the backslash, `\'. TeX uses `\' instead of `@'; and in this circumstance, you are working directly with TeX, not with Texinfo.)

    Using texinfo-show-structure

    It is not always easy to keep track of the nodes, chapters, sections, and subsections of a Texinfo file. This is especially true if you are revising or adding to a Texinfo file that someone else has written.

    In GNU Emacs, in Texinfo mode, the texinfo-show-structure command lists all the lines that begin with the @-commands that specify the structure: @chapter, @section, @appendix, and so on. With an argument (C-u as prefix argument, if interactive), the command also shows the @node lines. The texinfo-show-structure command is bound to C-c C-s in Texinfo mode, by default.

    The lines are displayed in a buffer called the `*Occur*' buffer, indented by hierarchical level. For example, here is a part of what was produced by running texinfo-show-structure on this manual:

     Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
 in buffer texinfo.texi.
 ...
 4177:@chapter Nodes
 4198:    @heading Two Paths
 4231:    @section Node and Menu Illustration
 4337:    @section The @code{@@node} Command
 4393:        @subheading Choosing Node and Pointer Names
 4417:        @subsection How to Write an @code{@@node} Line
 4469:        @subsection @code{@@node} Line Tips
 ...

    This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin with the @section, @subheading, and @subsection commands respectively. If you move your cursor into the `*Occur*' window, you can position the cursor over one of the lines and use the C-c C-c command (occur-mode-goto-occurrence), to jump to the corresponding spot in the Texinfo file. See section `Using Occur' in The GNU Emacs Manual, for more information about occur-mode-goto-occurrence.

    The first line in the `*Occur*' window describes the regular expression specified by texinfo-heading-pattern. This regular expression is the pattern that texinfo-show-structure looks for. See section `Using Regular Expressions' in The GNU Emacs Manual, for more information.

    When you invoke the texinfo-show-structure command, Emacs will display the structure of the whole buffer. If you want to see the structure of just a part of the buffer, of one chapter, for example, use the C-x n n (narrow-to-region) command to mark the region. (See section `Narrowing' in The GNU Emacs Manual.) This is how the example used above was generated. (To see the whole buffer again, use C-x n w (widen).)

    If you call texinfo-show-structure with a prefix argument by typing C-u C-c C-s, it will list lines beginning with @node as well as the lines beginning with the @-sign commands for @chapter, @section, and the like.

    You can remind yourself of the structure of a Texinfo file by looking at the list in the `*Occur*' window; and if you have mis-named a node or left out a section, you can correct the mistake.

    Using occur

    Sometimes the texinfo-show-structure command produces too much information. Perhaps you want to remind yourself of the overall structure of a Texinfo file, and are overwhelmed by the detailed list produced by texinfo-show-structure. In this case, you can use the occur command directly. To do this, type

    M-x occur

    and then, when prompted, type a regexp, a regular expression for the pattern you want to match. (See section `Regular Expressions' in The GNU Emacs Manual.) The occur command works from the current location of the cursor in the buffer to the end of the buffer. If you want to run occur on the whole buffer, place the cursor at the beginning of the buffer.

    For example, to see all the lines that contain the word `@chapter' in them, just type `@chapter'. This will produce a list of the chapters. It will also list all the sentences with `@chapter' in the middle of the line.

    If you want to see only those lines that start with the word `@chapter', type `^@chapter' when prompted by occur. If you want to see all the lines that end with a word or phrase, end the last word with a `$'; for example, `catching mistakes$'. This can be helpful when you want to see all the nodes that are part of the same chapter or section and therefore have the same `Up' pointer.

    See section `Using Occur' in The GNU Emacs Manual, for more information.

    Finding Badly Referenced Nodes

    You can use the Info-validate command to check whether any of the `Next', `Previous', `Up' or other node pointers fail to point to a node. This command checks that every node pointer points to an existing node. The Info-validate command works only on Info files, not on Texinfo files.

    The makeinfo program validates pointers automatically, so you do not need to use the Info-validate command if you are using makeinfo. You only may need to use Info-validate if you are unable to run makeinfo and instead must create an Info file using texinfo-format-region or texinfo-format-buffer, or if you write an Info file from scratch.

    Running Info-validate

    To use Info-validate, visit the Info file you wish to check and type:

    M-x Info-validate

    (Note that the Info-validate command requires an upper case `I'. You may also need to create a tag table before running Info-validate. See section Tagifying a File.)

    If your file is valid, you will receive a message that says "File appears valid". However, if you have a pointer that does not point to a node, error messages will be displayed in a buffer called `*problems in info file*'.

    For example, Info-validate was run on a test file that contained only the first node of this manual. One of the messages said:

    In node "Overview", invalid Next: Texinfo Mode

    This meant that the node called `Overview' had a `Next' pointer that did not point to anything (which was true in this case, since the test file had only one node in it).

    Now suppose we add a node named `Texinfo Mode' to our test case but we do not specify a `Previous' for this node. Then we will get the following error message:

    In node "Texinfo Mode", should have Previous: Overview

    This is because every `Next' pointer should be matched by a `Previous' (in the node where the `Next' points) which points back.

    Info-validate also checks that all menu entries and cross references point to actual nodes.

    Note that Info-validate requires a tag table and does not work with files that have been split. (The texinfo-format-buffer command automatically splits large files.) In order to use Info-validate on a large file, you must run texinfo-format-buffer with an argument so that it does not split the Info file; and you must create a tag table for the unsplit file.

    Creating an Unsplit File

    You can run Info-validate only on a single Info file that has a tag table. The command will not work on the indirect subfiles that are generated when a master file is split. If you have a large file (longer than 70,000 bytes or so), you need to run the texinfo-format-buffer or makeinfo-buffer command in such a way that it does not create indirect subfiles. You will also need to create a tag table for the Info file. After you have done this, you can run Info-validate and look for badly referenced nodes.

    The first step is to create an unsplit Info file. To prevent texinfo-format-buffer from splitting a Texinfo file into smaller Info files, give a prefix to the M-x texinfo-format-buffer command:

    C-u M-x texinfo-format-buffer

    or else

    C-u C-c C-e C-b

    When you do this, Texinfo will not split the file and will not create a tag table for it.

    Tagifying a File

    After creating an unsplit Info file, you must create a tag table for it. Visit the Info file you wish to tagify and type:

    M-x Info-tagify

    (Note the upper case `I' in Info-tagify.) This creates an Info file with a tag table that you can validate.

    The third step is to validate the Info file:

    M-x Info-validate

    (Note the upper case `I' in Info-validate.) In brief, the steps are:

    C-u M-x texinfo-format-buffer
M-x Info-tagify
M-x Info-validate

    After you have validated the node structure, you can rerun texinfo-format-buffer in the normal way so it will construct a tag table and split the file automatically, or you can make the tag table and split the file manually.

    Splitting a File Manually

    You should split a large file or else let the texinfo-format-buffer or makeinfo-buffer command do it for you automatically. (Generally you will let one of the formatting commands do this job for you. See section Creating an Info File.)

    The split-off files are called the indirect subfiles.

    Info files are split to save memory. With smaller files, Emacs does not have make such a large buffer to hold the information.

    If an Info file has more than 30 nodes, you should also make a tag table for it. See section Running Info-validate, for information about creating a tag table. (Again, tag tables are usually created automatically by the formatting command; you only need to create a tag table yourself if you are doing the job manually. Most likely, you will do this for a large, unsplit file on which you have run Info-validate.)

    Visit the Info file you wish to tagify and split and type the two commands:

    M-x Info-tagify
M-x Info-split

    (Note that the `I' in `Info' is upper case.)

    When you use the Info-split command, the buffer is modified into a (small) Info file which lists the indirect subfiles. This file should be saved in place of the original visited file. The indirect subfiles are written in the same directory the original file is in, with names generated by appending `-' and a number to the original file name.

    The primary file still functions as an Info file, but it contains just the tag table and a directory of subfiles.

    Refilling Paragraphs

    The @refill command refills and, optionally, indents the first line of a paragraph.(13) The @refill command is no longer important, but we describe it here because you once needed it. You will see it in many old Texinfo files.

    Without refilling, paragraphs containing long @-constructs may look bad after formatting because the formatter removes @-commands and shortens some lines more than others. In the past, neither the texinfo-format-region command nor the texinfo-format-buffer command refilled paragraphs automatically. The @refill command had to be written at the end of every paragraph to cause these formatters to fill them. (Both TeX and makeinfo have always refilled paragraphs automatically.) Now, all the Info formatters automatically fill and indent those paragraphs that need to be filled and indented.

    The @refill command causes texinfo-format-region and texinfo-format-buffer to refill a paragraph in the Info file after all the other processing has been done. For this reason, you can not use @refill with a paragraph containing either @* or @w{ ... } since the refilling action will override those two commands.

    The texinfo-format-region and texinfo-format-buffer commands now automatically append @refill to the end of each paragraph that should be filled. They do not append @refill to the ends of paragraphs that contain @* or @w{ ...} and therefore do not refill or indent them.

    @-Command Syntax

    The character `@' is used to start special Texinfo commands. (It has the same meaning that `\' has in plain TeX.) Texinfo has four types of @-command:

    1. Non-alphabetic commands.
    These commands consist of an @ followed by a punctuation mark or other character that is not part of the alphabet. Non-alphabetic commands are almost always part of the text within a paragraph, and never take any argument. The two characters (@ and the other one) are complete in themselves; none is followed by braces. The non-alphabetic commands are: @., @:, @*, @@, @{, and @}.
    2. Alphabetic commands that do not require arguments.
    These commands start with @ followed by a word followed by left- and right-hand braces. These commands insert special symbols in the document; they do not require arguments. For example, @dots{} => `...', @equiv{} => `==', @TeX{} => `TeX', and @bullet{} => `*'.
    3. Alphabetic commands that require arguments within braces.
    These commands start with @ followed by a letter or a word, followed by an argument within braces. For example, the command @dfn indicates the introductory or defining use of a term; it is used as follows: `In Texinfo, @@-commands are @dfn{mark-up} commands.'
    4. Alphabetic commands that occupy an entire line.
    These commands occupy an entire line. The line starts with @, followed by the name of the command (a word); for example, @center or @cindex. If no argument is needed, the word is followed by the end of the line. If there is an argument, it is separated from the command name by a space. Braces are not used.

    Thus, the alphabetic commands fall into classes that have different argument syntaxes. You cannot tell to which class a command belongs by the appearance of its name, but you can tell by the command's meaning: if the command stands for a glyph, it is in class 2 and does not require an argument; if it makes sense to use the command together with other text as part of a paragraph, the command is in class 3 and must be followed by an argument in braces; otherwise, it is in class 4 and uses the rest of the line as its argument.

    The purpose of having a different syntax for commands of classes 3 and 4 is to make Texinfo files easier to read, and also to help the GNU Emacs paragraph and filling commands work properly. There is only one exception to this rule: the command @refill, which is always used at the end of a paragraph immediately following the final period or other punctuation character. @refill takes no argument and does not require braces. @refill never confuses the Emacs paragraph commands because it cannot appear at the beginning of a line.

    How to Obtain TeX

    TeX is freely redistributable. You can obtain TeX for Unix systems via anonymous ftp or on tape or CD-ROM. The core material consists of Karl Berry's Web2c TeX distribution.

    On-line retrieval instructions are available from either:

    ftp://ftp.tug.org/tex/unixtex.ftp
http://www.tug.org/unixtex.ftp

    The Free Software Foundation provides a core distribution on its Source Code CD-ROM suitable for printing Texinfo manuals; the University of Washington maintains and supports a tape distribution; the TeX Users Group co-sponsors a complete CD-ROM TeX distribution.

    For the FSF Source Code CD-ROM, please contact:

    Free Software Foundation, Inc.
59 Temple Place Suite 330
Boston, MA w{ } 02111-1307
USA

Telephone: +1--617--542--5942
Fax: (including Japan) +1--617--542--2652
Free Dial Fax (in Japan):
      0031--13--2473 (KDD)
      0066--3382--0158 (IDC)
Electronic mail: gnu@prep.ai.mit.edu

    To order a full distribution on CD-ROM, please see:

    http://www.tug.org/tex-live.html

    (The distribution is also available by FTP; see the URL's above.)

    To order a full distribution from the University of Washington on either a 1/4in 4-track QIC-24 cartridge or a 4mm DAT cartridge, send $210 to:

    Pierre A. MacKay
Denny Hall, Mail Stop DH-10
University of Washington
Seattle, WA   98195
USA

Telephone: +1--206--543--2268
Electronic mail: mackay@cs.washington.edu

    Please make checks payable to the University of Washington. Checks must be in U.S. dollars, drawn on a U.S. bank.

    Prepaid orders are the only orders that can now be handled. Overseas sites: please add to the base cost, if desired, $20.00 for shipment via air parcel post, or $30.00 for shipment via courier.

    Please check with the above for current prices and formats.

    Second Edition Features

    The second edition of the Texinfo manual describes more than 20 new Texinfo mode commands and more than 50 previously undocumented Texinfo @-commands. This edition is more than twice the length of the first edition.

    Here is a brief description of the new commands.

    New Texinfo Mode Commands

    Texinfo mode provides commands and features especially designed for working with Texinfo files. More than 20 new commands have been added, including commands for automatically creating and updating both nodes and menus. This is a tedious task when done by hand.

    The keybindings are intended to be somewhat mnemonic.

    Update all nodes and menus

    The texinfo-master-menu command is the primary command:

    C-c C-u m
    M-x texinfo-master-menu
    Create or update a master menu. With C-u as a prefix argument, first create or update all nodes and regular menus.

    Update Pointers

    Create or update `Next', `Previous', and `Up' node pointers.

    See section Updating Nodes and Menus.

    C-c C-u C-n
    M-x texinfo-update-node
    Update a node.
    C-c C-u C-e
    M-x texinfo-every-node-update
    Update every node in the buffer.

    Update Menus

    Create or update menus.

    See section Updating Nodes and Menus.

    C-c C-u C-m
    M-x texinfo-make-menu
    Make or update a menu.
    C-c C-u C-a
    M-x texinfo-all-menus-update
    Make or update all the menus in a buffer. With C-u as a prefix argument, first update all the nodes.

    Insert Title as Description

    Insert a node's chapter or section title in the space for the description in a menu entry line; position point so you can edit the insert. (This command works somewhat differently than the other insertion commands, which insert only a predefined string.)

    See section Inserting Frequently Used Commands.

    C-c C-c C-d
    Insert title.

    Format for Info

    Provide keybindings both for the Info formatting commands that are written in Emacs Lisp and for makeinfo that is written in C.

    See section Formatting for Info.

    Use the Emacs lisp texinfo-format... commands:

    C-c C-e C-r
    Format the region.
    C-c C-e C-b
    Format the buffer.

    Use makeinfo:

    C-c C-m C-r
    Format the region.
    C-c C-m C-b
    Format the buffer.
    C-c C-m C-l
    Recenter the makeinfo output buffer.
    C-c C-m C-k
    Kill the makeinfo formatting job.

    Typeset and Print

    Typeset and print Texinfo documents from within Emacs.

    See section Formatting and Printing.

    C-c C-t C-b
    Run texi2dvi on the buffer.
    C-c C-t C-r
    Run TeX on the region.
    C-c C-t C-i
    Run texindex.
    C-c C-t C-p
    Print the DVI file.
    C-c C-t C-q
    Show the print queue.
    C-c C-t C-d
    Delete a job from the print queue.
    C-c C-t C-k
    Kill the current TeX formatting job.
    C-c C-t C-x
    Quit a currently stopped TeX formatting job.
    C-c C-t C-l
    Recenter the output buffer.

    Other Updating Commands

    The "other updating commands" do not have standard keybindings because they are used less frequently.

    See section Other Updating Commands.

    M-x texinfo-insert-node-lines
    Insert missing @node lines using section titles as node names.
    M-x texinfo-multiple-files-update
    Update a multi-file document. With a numeric prefix, such as C-u 8, update every pointer and menu in all the files and then insert a master menu.
    M-x texinfo-indent-menu-description
    Indent descriptions in menus.
    M-x texinfo-sequential-node-update
    Insert node pointers in strict sequence.

    New Texinfo @-Commands

    The second edition of the Texinfo manual describes more than 50 commands that were not described in the first edition. A third or so of these commands existed in Texinfo but were not documented in the manual; the others are new. Here is a listing, with brief descriptions of them:

    Indexing

    Create your own index, and merge indices.

    See section Creating Indices.

    @defindex index-name
    Define a new index and its indexing command. See also the @defcodeindex command.
    @synindex from-index into-index
    Merge the from-index index into the into-index index. See also the @syncodeindex command.

    Definitions

    Describe functions, variables, macros, commands, user options, special forms, and other such artifacts in a uniform format.

    See section Definition Commands.

    @deffn category name arguments...
    Format a description for functions, interactive commands, and similar entities.
    @defvr, @defop, ...
    15 other related commands.

    Glyphs

    Indicate the results of evaluation, expansion, printed output, an error message, equivalence of expressions, and the location of point.

    See section Glyphs for Examples.

    @equiv{}
    ==
    Equivalence:
    @error{}
    error-->
    Error message
    @expansion{}
    ==>
    Macro expansion
    @point{}
    -!-
    Position of point
    @print{}
    -|
    Printed output
    @result{}
    =>
    Result of an expression

    Page Headings

    Customize page headings.

    See section Page Headings.

    @headings on-off-single-double
    Headings on or off, single, or double-sided.
    @evenfooting [left] @| [center] @| [right]
    Footings for even-numbered (left-hand) pages.
    @evenheading, @everyheading, @oddheading, ...
    Five other related commands.
    @thischapter
    Insert name of chapter and chapter number.
    @thischaptername, @thisfile, @thistitle, @thispage
    Related commands.

    Formatting

    Format blocks of text.

    See section Quotations and Examples, and
    section Making Lists and Tables.

    @cartouche
    Draw rounded box surrounding text (not in Info).
    @enumerate optional-arg
    Enumerate a list with letters or numbers.
    @exdent line-of-text
    Remove indentation.
    @flushleft
    Left justify.
    @flushright
    Right justify.
    @format
    Do not narrow nor change font.
    @ftable formatting-command
    @vtable formatting-command
    Two-column table with indexing.
    @lisp
    For an example of Lisp code.
    @smallexample
    @smalllisp
    Like @table and @lisp but for @smallbook.

    Conditionals

    Conditionally format text.

    See section @set, @clear, and @value.

    @set flag [string]
    Set a flag. Optionally, set value of flag to string.
    @clear flag
    Clear a flag.
    @value{flag}
    Replace with value to which flag is set.
    @ifset flag
    Format, if flag is set.
    @ifclear flag
    Ignore, if flag is set.

    @heading series for Titles

    Produce unnumbered headings that do not appear in a table of contents.

    See section Chapter Structuring.

    @heading title
    Unnumbered section-like heading not listed in the table of contents of a printed manual.
    @chapheading, @majorheading, @subheading, @subsubheading
    Related commands.

    Font commands

    See section @sc{text}: The Small Caps Font, and
    section Fonts for Printing, Not Info.

    @r{text}
    Print in roman font.
    @sc{text}
    Print in SMALL CAPS font.

    Miscellaneous

    See section @title, @subtitle, and @author,
    see section Customized Highlighting,
    see section Overfull "hboxes",
    see section Footnotes,
    see section @dmn{dimension}: Format a Dimension,
    see section @raisesections and @lowersections,
    see section @math: Inserting Mathematical Expressions.
    see section @minus{}: Inserting a Minus Sign,
    see section Paragraph Indenting,
    see section Different Cross Reference Commands,
    see section @title, @subtitle, and @author, and
    see section How to Make Your Own Headings.

    @author author
    Typeset author's name.
    @finalout
    Produce cleaner printed output.
    @footnotestyle end-or-separate
    Specify footnote style.
    @dmn{dimension}
    Format a dimension.
    @global@letnew-cmd=existing-cmd
    Define a highlighting command for TeX. (TeX only.)
    @lowersections
    Reduce hierarchical level of sectioning commands.
    @math{mathematical-expression}
    Format a mathematical expression.
    @minus{}
    Generate a minus sign.
    @paragraphindent asis-or-number
    Specify paragraph indentation.
    @raisesections
    Raise hierarchical level of sectioning commands.
    @ref{node-name, [entry], [topic-or-title], [info-file], [manual]}
    Make a reference. In the printed manual, the reference does not start with the word `see'.
    @title title
    Typeset title in the alternative title page format.
    @subtitle subtitle
    Typeset subtitle in the alternative title page format.
    @today{}
    Insert the current date.

    Command and Variable Index

    This is an alphabetical list of all the @-commands, assorted Emacs Lisp functions, and several variables. To make the list easier to use, the commands are listed without their preceding `@'.

    Jump to: ! - " - ' - ( - * - , - - - . - : - = - ? - @ - ^ - ` - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - q - r - s - t - u - v - w - x - { - } - ~

    !

  • ! (end of sentence)

    • "

  • "

    • '

  • '

    • (

  • (newline)
  • (space)
  • (tab)

    • *

  • * (force line break)

    • ,

  • ,

    • -

  • -

    • .

  • . (end of sentence)

    • :

  • : (suppress widening)

    • =

  • =

    • ?

  • ? (end of sentence)

    • @

  • @ (single `@')

    • ^

  • ^

    • `

  • `

    • a

  • AA
  • aa
  • AE
  • ae
  • afourpaper
  • appendix
  • appendixsec
  • appendixsection
  • appendixsubsec
  • appendixsubsubsec
  • apply
  • author

    • b

  • b (bold font)
  • buffer-end
  • bullet
  • bye, bye

    • c

  • c (comment)
  • cartouche
  • center
  • centerchap
  • chapheading
  • chapter
  • cindex
  • cite
  • clear
  • code
  • columnfractions
  • comment
  • contents
  • copyright, copyright
  • cropmarks

    • d

  • defcodeindex
  • defcv
  • deffn
  • deffnx
  • defindex
  • definfoenclose
  • defivar
  • defmac
  • defmethod
  • defop
  • defopt
  • defspec
  • deftp
  • deftypefn
  • deftypefun
  • deftypevar
  • deftypevr
  • defun
  • defvar
  • defvr
  • dfn
  • dircategory
  • direntry
  • display
  • dmn
  • dotaccent
  • dotless
  • dots

    • e

  • email
  • emph
  • end, end
  • end titlepage
  • enumerate
  • evenfooting
  • evenheading
  • everyfooting
  • everyheading
  • example
  • exclamdown
  • exdent

    • f

  • file
  • filll
  • finalout
  • findex
  • flushleft
  • flushright
  • foobar, foobar, foobar
  • footnote
  • footnotestyle
  • format
  • forward-word
  • ftable

    • g

  • group

    • h

  • H
  • heading
  • headings
  • hyphenation

    • i

  • i (italic font)
  • ifclear
  • ifhtml
  • ifinfo
  • ifset
  • iftex
  • ignore
  • include
  • Info-validate
  • inforef
  • input (TeX command)
  • isearch-backward
  • isearch-forward
  • item, item, item
  • itemize
  • itemx

    • k

  • kbd
  • key
  • kindex

    • l

  • L
  • l
  • lisp
  • lowersections

    • m

  • macro
  • mag (TeX command)
  • majorheading
  • makeinfo-buffer
  • makeinfo-kill-job
  • makeinfo-recenter-output-buffer
  • makeinfo-region
  • math
  • menu
  • minus
  • multitable

    • n

  • need
  • next-error
  • noindent

    • o

  • O
  • o
  • occur
  • occur-mode-goto-occurrence
  • oddfooting
  • oddheading
  • OE
  • oe

    • p

  • page
  • paragraphindent
  • pindex
  • pounds
  • printindex
  • pxref

    • q

  • questiondown
  • quotation

    • r

  • r (Roman font)
  • raisesections
  • ref
  • refill
  • ringaccent

    • s

  • samp
  • sc (small caps font)
  • section
  • set
  • setchapternewpage
  • setfilename
  • settitle
  • shortcontents
  • shorttitlepage
  • smallbook
  • smallexample
  • smalllisp
  • sp (line spacing)
  • sp (titlepage line spacing)
  • ss
  • strong
  • subheading
  • subsection
  • subsubheading
  • subsubsection
  • subtitle
  • summarycontents
  • syncodeindex, syncodeindex
  • synindex

    • t

  • t (typewriter font)
  • table
  • tex
  • tex (command)
  • texinfo-all-menus-update
  • texinfo-every-node-update
  • texinfo-format-buffer, texinfo-format-buffer, texinfo-format-buffer
  • texinfo-format-region, texinfo-format-region, texinfo-format-region
  • texinfo-indent-menu-description
  • texinfo-insert-@code
  • texinfo-insert-@dfn
  • texinfo-insert-@end
  • texinfo-insert-@example
  • texinfo-insert-@item
  • texinfo-insert-@kbd
  • texinfo-insert-@node
  • texinfo-insert-@noindent
  • texinfo-insert-@samp
  • texinfo-insert-@table
  • texinfo-insert-@var
  • texinfo-insert-braces
  • texinfo-insert-node-lines
  • texinfo-make-menu
  • texinfo-master-menu
  • texinfo-multiple-files-update
  • texinfo-multiple-files-update (in brief)
  • texinfo-sequential-node-update
  • texinfo-show-structure, texinfo-show-structure
  • texinfo-start-menu-description
  • texinfo-tex-buffer
  • texinfo-tex-print
  • texinfo-tex-region
  • texinfo-update-node
  • thischapter
  • thischaptername
  • thisfile
  • thispage
  • thistitle
  • tieaccent
  • tindex
  • title
  • titlefont
  • titlepage
  • today
  • top (@-command)

    • u

  • u
  • ubaraccent
  • udotaccent
  • unmacro
  • unnumbered
  • unnumberedsec
  • unnumberedsubsec
  • unnumberedsubsubsec
  • up-list
  • url

    • v

  • v
  • value
  • var
  • vindex
  • vskip
  • vtable

    • w

  • w (prevent line break)

    • x

  • xref

    • {

  • { (single `{')

    • }

  • } (single `}')

    • ~

  • ~

    • Concept Index

    Jump to: . - @ - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - q - r - s - t - u - v - w - z

    .

  • .cshrc initialization file
  • .profile initialization file

    • @

  • @-command in nodename
  • @-command list
  • @-command syntax
  • @-commands
  • @AA{}
  • @aa{}
  • @AE{}
  • @ae{}
  • @dotless{i}
  • @dotless{j}
  • @exclamdown{}
  • @include file sample
  • @l{}
  • @L{}
  • @menu parts
  • @node line writing
  • @OE{}
  • @oe{}
  • @O{}
  • @o{}
  • @questiondown{}
  • @ss{}

    • a

  • A4 paper, printing on
  • Abbreviations for keys
  • Accents, inserting
  • Acute accent
  • Adding a new info file
  • Alphabetical @-command list
  • Another Info directory
  • Apostrophe in nodename
  • Arguments, repeated and optional
  • Automatic pointer creation with makeinfo
  • Automatically insert nodes, menus

    • b

  • Backslash, and macros
  • Badly referenced nodes
  • Batch formatting for Info
  • Beginning a Texinfo file
  • Beginning line of a Texinfo file
  • Berry, Karl
  • Black rectangle in hardcopy
  • Blank lines
  • Body of a macro
  • Book characteristics, printed
  • Book, printing small
  • Box with rounded corners
  • Braces and argument syntax
  • Braces, inserting
  • Braces, when to use
  • Breaks in a line
  • Breve accent
  • Buffer formatting and printing
  • Bullets, inserting

    • c

  • Case in nodename
  • Catching errors with Info formatting
  • Catching errors with TeX formatting
  • Catching mistakes
  • Cedilla accent
  • Chapter structuring
  • Characteristics, printed books or manuals
  • Chassell, Robert J.
  • Check accent
  • Checking for badly referenced nodes
  • Circumflex accent
  • Colon in nodename
  • Column widths, defining for multitables
  • Combining indices
  • Comma in nodename
  • Command definitions
  • Commands to insert special characters
  • Commands using ordinary TeX
  • Commands, inserting them
  • Comments
  • Compile command for formatting
  • Conditionally visible text
  • Conditions for copying Texinfo
  • Contents, Table of
  • Contents-like outline of file structure
  • Conventions for writing definitions
  • Conventions, syntactic
  • Copying conditions
  • Copying permissions
  • Copying software
  • Copyright page
  • Correcting mistakes
  • Create nodes, menus automatically
  • Creating an Info file
  • Creating an unsplit file
  • Creating index entries
  • Creating indices
  • Creating pointers with makeinfo
  • Cropmarks for printing
  • Cross reference parts
  • Cross references
  • Cross references using @inforef
  • Cross references using @pxref
  • Cross references using @ref
  • Cross references using @xref
  • Customized highlighting

    • d

  • Debugging the Texinfo structure
  • Debugging with Info formatting
  • Debugging with TeX formatting
  • Defining indexing entries
  • Defining macros
  • Defining new indices
  • Defining new Texinfo commands
  • Definition commands
  • Definition conventions
  • Definition template
  • Definitions grouped together
  • Description for menu, start
  • Different cross reference commands
  • Dimension formatting
  • `dir' directory for Info installation
  • `dir' file listing
  • Display formatting
  • Distribution
  • Dot accent
  • Dotless i, j
  • Dots, inserting, Dots, inserting
  • Double-colon menu entries
  • DVI file

    • e

  • Ellipsis, inserting
  • Emacs
  • Emacs shell, format, print from
  • Emphasizing text
  • Emphasizing text, font for
  • enable
  • Enclosure command for Info
  • `End' node footnote style
  • End of header line
  • End titlepage starts headings
  • Ending a Sentence
  • Ending a Texinfo file
  • Entries for an index
  • Entries, making index
  • Enumeration
  • Equivalence, indicating it
  • Error message, indicating it
  • Errors, parsing
  • Es-zet
  • European A4 paper
  • Evaluation glyph
  • Example for a small book
  • Example menu
  • Examples, formatting them
  • Expansion, indicating it

    • f

  • File beginning
  • File ending
  • File section structure, showing it
  • Filling paragraphs
  • Final output
  • Finding badly referenced nodes
  • Fine-tuning, and hyphenation
  • First line of a Texinfo file
  • First node
  • Floating accents, inserting
  • Fonts for indices
  • Fonts for printing, not for Info
  • Footings
  • Footnotes
  • Format a dimension
  • Format and print hardcopy
  • Format and print in Texinfo mode
  • Format with the compile command
  • Format, print from Emacs shell
  • Formatting a file for Info
  • Formatting commands
  • Formatting examples
  • Formatting for Info
  • Formatting for printing
  • Formatting headings and footings
  • Formatting requirements
  • Formatting with tex and texindex
  • Frequently used commands, inserting
  • fubar
  • Function definitions

    • g

  • General syntactic conventions
  • Generating menus with indices
  • German S
  • Glyphs
  • GNU Emacs
  • GNU Emacs shell, format, print from
  • Going to other Info files' nodes
  • Grave accent
  • Group (hold text together vertically)
  • Grouping two definitions together

    • h

  • Hardcopy, printing it
  • `hboxes', overfull
  • Header for Texinfo files
  • Header of a Texinfo file
  • Headings
  • Headings, page, begin to appear
  • Highlighting text
  • Highlighting, customized
  • Hints
  • Holding text together vertically
  • Hungariam umlaut accent
  • Hyphenation, helping TeX do
  • Hyphenation, preventing

    • i

  • If text conditionally visible
  • `ifinfo' permissions
  • Ignored text
  • Include file requirements
  • Include file sample
  • Include files
  • Indentation undoing
  • Indenting paragraphs
  • Index entries
  • Index entries, making
  • Index entry writing
  • Index font types
  • Indexing commands, predefined
  • Indexing table entries automatically
  • Indicating commands, definitions, etc.
  • Indicating evaluation
  • Indices
  • Indices, combining them
  • Indices, defining new
  • Indices, printing and menus
  • Indices, sorting
  • Indices, two letter names
  • Indirect subfiles
  • Info batch formatting
  • Info file installation
  • Info file requires @setfilename
  • Info file, listing new one
  • Info file, splitting manually
  • Info files
  • Info formatting
  • Info installed in another directory
  • Info validating a large file
  • Info, creating an on-line file
  • Info-directory-list
  • Info; other files' nodes
  • INFOPATH
  • Initialization file for TeX input
  • Insert nodes, menus automatically
  • Inserting @, braces
  • Inserting accents
  • Inserting dots, Inserting dots
  • Inserting ellipsis
  • Inserting frequently used commands
  • Inserting space
  • Inserting special characters and symbols
  • install-info
  • Installing an Info file
  • Installing Info in another directory
  • Introduction, as part of file
  • Invoking macros
  • Itemization

    • k

  • Keys, recommended names
  • Knuth, Donald

    • l

  • Larger or smaller pages
  • Less cluttered menu entry
  • License agreement
  • Line breaks
  • Line breaks, preventing
  • Line length, column widths as fraction of
  • Line spacing
  • Lisp example
  • Lisp example for a small book
  • List of @-commands
  • Listing a new info file
  • Lists and tables, making them
  • Local variables
  • Location of menus
  • Looking for badly referenced nodes
  • lpr (DVI print command)

    • m

  • Macro definitions, Macro definitions
  • Macro invocation
  • Macron accent
  • Macros
  • Macros, undefining
  • Magnified printing
  • makeinfo inside Emacs
  • makeinfo options
  • Making a printed manual
  • Making a tag table automatically
  • Making a tag table manually
  • Making cross references
  • Making line and page breaks
  • Making lists and tables
  • Manual characteristics, printed
  • Marking text within a paragraph
  • Marking words and phrases
  • Master menu
  • Master menu parts
  • Mathematical expressions, Mathematical expressions
  • Menu description, start
  • Menu entries with two colons
  • Menu example
  • Menu location
  • Menu parts
  • Menu writing
  • Menus
  • Menus generated with indices
  • META key
  • Meta-syntactic chars for arguments
  • Minimal Texinfo file (requirements)
  • Mistakes, catching
  • Mode, using Texinfo
  • Multiple spaces
  • Multitable column widths
  • Multitable rows
  • Must have in Texinfo file
  • Mutually recursive macros

    • n

  • Names for indices
  • Names recommended for keys
  • Naming a `Top' Node in references
  • Need space at page bottom
  • New index defining
  • New info file, listing it in `dir' file
  • New Texinfo commands, defining
  • Node line requirements
  • Node line writing
  • Node, `Top'
  • Node, defined
  • Nodename must be unique
  • Nodename, cannot contain
  • Nodes for menus are short
  • Nodes in other Info files
  • Nodes, catching mistakes
  • Nodes, checking for badly referenced
  • Not ending a sentence

    • o

  • Obtaining TeX
  • Occurrences, listing with @occur
  • Optional and repeated arguments
  • Options for makeinfo
  • Ordinary TeX commands, using
  • Other Info files' nodes
  • Outline of file structure, showing it
  • Overfull `hboxes'
  • Overview of Texinfo

    • p

  • Page breaks
  • Page delimiter in Texinfo mode
  • Page headings
  • Page numbering
  • Page sizes for books
  • page-delimiter
  • Pages, starting odd
  • Paper size, European A4
  • Paragraph indentation
  • Paragraph, marking text within
  • Parsing errors
  • Part of file formatting and printing
  • Parts of a cross reference
  • Parts of a master menu
  • Parts of a menu
  • Periods, inserting
  • Permissions
  • Permissions, printed
  • Pinard, Fran@,{c}ois
  • plain TeX
  • Point, indicating it in a buffer
  • Pointer creation with makeinfo
  • Pointer validation with makeinfo
  • Predefined indexing commands
  • Predefined names for indices
  • Preparing to use TeX
  • Preventing line and page breaks
  • Print and format in Texinfo mode
  • Print, format from Emacs shell
  • Printed book and manual characteristics
  • Printed output, indicating it
  • Printed permissions
  • Printing a region or buffer
  • Printing an index
  • Printing cropmarks
  • Problems, catching
  • Prototype row, column widths defined by

    • q

  • Quotations

    • r

  • Raising and lowering sections
  • Recommended names for keys
  • Rectangle, ugly, black in hardcopy
  • Recursion, mutual
  • References
  • References using @inforef
  • References using @pxref
  • References using @ref
  • References using @xref
  • Referring to other Info files
  • Refilling paragraphs
  • Region formatting and printing
  • Region printing in Texinfo mode
  • Repeated and optional arguments
  • Required in Texinfo file
  • Requirements for formatting
  • Requirements for include files
  • Requirements for updating commands
  • Result of an expression
  • Ring accent
  • Rows, of a multitable
  • Running an Info formatter
  • Running Info-validate
  • Running makeinfo in Emacs

    • s

  • Sample @include file
  • Sample function definition
  • Sample Texinfo file
  • Sample Texinfo file, no comments
  • Section structure of a file, showing it
  • Sections, raising and lowering
  • Sentence ending punctuation
  • Sentence non-ending punctuation
  • `Separate' footnote style
  • Sharp S
  • Shell formatting with tex and texindex
  • Shell, format, print from
  • Shell, running makeinfo in
  • Short nodes for menus
  • Showing the section structure of a file
  • Showing the structure of a file
  • Size of printed book
  • Small book example
  • Small book size
  • Small caps font
  • Software copying permissions
  • Sorting indices
  • Spaces (blank lines)
  • Spacing, inserting
  • Special characters, commands to insert
  • Special insertions
  • Special typesetting commands
  • Specifying index entries
  • Splitting an Info file manually
  • Stallman, Richard M.
  • Start of header line
  • Starting chapters
  • Structure of a file, showing it
  • Structure, catching mistakes in
  • Structuring of chapters
  • Subsection-like commands
  • Subsub commands
  • Syntactic conventions
  • Syntax, optional & repeated arguments

    • t

  • tab
  • Table of contents
  • Tables and lists, making them
  • Tables with indexes
  • Tables, making multi-column
  • Tables, making two-column
  • Tabs; don't use!
  • Tag table, making automatically
  • Tag table, making manually
  • Template for a definition
  • TeX commands, using ordinary
  • TeX index sorting
  • TeX input initialization
  • TeX, how to obtain
  • texi2dvi (shell script)
  • texindex, texindex
  • Texinfo commands, defining new
  • Texinfo file beginning
  • Texinfo file ending
  • Texinfo file header
  • Texinfo file minimum
  • Texinfo file section structure, showing it
  • Texinfo mode
  • Texinfo overview
  • Texinfo printed book characteristics
  • TEXINPUTS
  • TEXINPUTS environment variable
  • Text, conditionally visible
  • Thin space between number, dimension
  • Tie-after accent
  • Tilde accent
  • Tips
  • Title page
  • Titlepage end starts headings
  • Titlepage permissions
  • `Top' node
  • `Top' node is first
  • `Top' node naming for references
  • `Top' node summary
  • Tree structuring
  • Two `First' Lines for @deffn
  • Two letter names for indices
  • Two named items for @table
  • Two part menu entry
  • Typesetting commands for dots, etc.

    • u

  • Umlaut accent
  • Uncluttered menu entry
  • Undefining macros
  • Underbar accent
  • Underdot accent
  • Unique nodename requirement
  • Unprocessed text
  • Unsplit file creation
  • Updating nodes and menus
  • Updating requirements
  • Usage tips
  • User-defined Texinfo commands

    • v

  • Validating a large file
  • Validation of pointers
  • Value of an expression, indicating
  • version number, finding
  • Vertical whitespace (`vskip')
  • Vertically holding text together
  • Visibility of conditional text

    • w

  • Weisshaus, Melissa
  • Whitespace, inserting, Whitespace, inserting
  • Widths, defining multitable column
  • Words and phrases, marking them
  • Writing a menu
  • Writing an @node line
  • Writing index entries

    • z

  • Zuhn, David D.

    • Footnotes

    (1)

    Note that the first syllable of "Texinfo" is pronounced like "speck", not "hex". This odd pronunciation is derived from, but is not the same as, the pronunciation of TeX. In the word TeX, the `X' is actually the Greek letter "chi" rather than the English letter "ex". Pronounce TeX as if the `X' were the last sound in the name `Bach'; but pronounce Texinfo as if the `x' were a `k'. Spell "Texinfo" with a capital "T" and write the other letters in lower case.

    (2)

    In some documents, the first child has no `Previous' pointer. Occasionally, the last child has the node name of the next following higher level node as its `Next' pointer.

    (3)

    You can also use the texi2roff program if you do not have TeX; since Texinfo is designed for use with TeX, texi2roff is not described here. texi2roff is part of the standard GNU distribution.

    (4)

    The word argument comes from the way it is used in mathematics and does not refer to a disputation between two people; it refers to the information presented to the command. According to the Oxford English Dictionary, the word derives from the Latin for to make clear, prove; thus it came to mean `the evidence offered as proof', which is to say, `the information offered', which led to its mathematical meaning. In its other thread of derivation, the word came to mean `to assert in a manner against which others may make counter assertions', which led to the meaning of `argument' as a disputation.

    (5)

    We have found that it is helpful to refer to versions of manuals as `editions' and versions of programs as `versions'; otherwise, we find we are liable to confuse each other in conversation by referring to both the documentation and the software with the same words.

    (6)

    Menus can carry you to any node, regardless of the hierarchical structure; even to nodes in a different Info file. However, the GNU Emacs Texinfo mode updating commands work only to create menus of subordinate nodes. Conventionally, cross references are used to refer to other nodes.

    (7)

    Currently, @definfoenclose works only with texinfo-format-buffer and texinfo-format-region, not with makeinfo.

    (8)

    It would be straightforward to extend Texinfo to work in a similar fashion for C, FORTRAN, or other languages.

    (9)

    A footnote should complement or expand upon the primary text, but a reader should not need to read a footnote to understand the primary text. For a thorough discussion of footnotes, see The Chicago Manual of Style, which is published by the University of Chicago Press.

    (10)

    Here is the sample footnote.

    (11)

    If you use more than one index and have cross references to an index other than the first, you must run tex three times to get correct output: once to generate raw index data; again (after texindex) to output the text of the indices and determine their true page numbers; and a third time to output correct page numbers in cross references to them. However, cross references to indices are rare.

    (12)

    `--' has replaced `+', the old introductory character, to maintain POSIX.2 compatibility without losing long-named options.

    (13)

    Perhaps the command should have been called the @refillandindent command, but @refill is shorter and the name was chosen before indenting was possible.

    This document was generated on 7 November 1998 using the texi2html translator version 1.52.


GNU text utilities

This manual documents version 2.0 of the GNU text utilities.

1. Introduction | Caveats, overview, and authors.
2. Common options
3. Output of entire files | cat tac nl od
4. Formatting file contents | fmt pr fold
5. Output of parts of files | head tail split csplit
6. Summarizing files | wc sum cksum md5sum
7. Operating on sorted files | sort uniq comm ptx tsort
8. Operating on fields within a line | cut paste join
9. Operating on characters | tr expand unexpand
10. Opening the software toolbox | The software tools philosophy.
Index | General index.

-- The Detailed Node Listing ---

Output of entire files

3.1 cat: Concatenate and write files | Concatenate and write files.
3.2 tac: Concatenate and write files in reverse | Concatenate and write files in reverse.
3.3 nl: Number lines and write files | Number lines and write files.
3.4 od: Write files in octal or other formats | Write files in octal or other formats.

Formatting file contents

4.1 fmt: Reformat paragraph text | Reformat paragraph text.
4.2 pr: Paginate or columnate files for printing | Paginate or columnate files for printing.
4.3 fold: Wrap input lines to fit in specified width | Wrap input lines to fit in specified width.

Output of parts of files

5.1 head: Output the first part of files | Output the first part of files.
5.2 tail: Output the last part of files | Output the last part of files.
5.3 split: Split a file into fixed-size pieces | Split a file into fixed-size pieces.
5.4 csplit: Split a file into context-determined pieces | Split a file into context-determined pieces.

Summarizing files

6.1 wc: Print byte, word, and line counts | Print byte, word, and line counts.
6.2 sum: Print checksum and block counts | Print checksum and block counts.
6.3 cksum: Print CRC checksum and byte counts | Print CRC checksum and byte counts.
6.4 md5sum: Print or check message-digests | Print or check message-digests.

Operating on sorted files

7.1 sort: Sort text files | Sort text files.
7.2 uniq: Uniquify files | Uniquify files.
7.3 comm: Compare two sorted files line by line | Compare two sorted files line by line.
7.5 ptx: Produce permuted indexes | Produce a permuted index of file contents.
7.4 tsort: Topological sort | Topological sort.

ptx: Produce permuted indexes

7.5.1 General options | Options which affect general program behavior.
7.5.2 Charset selection | Underlying character set considerations.
7.5.3 Word selection and input processing | Input fields, contexts, and keyword selection.
7.5.4 Output formatting | Types of output format, and sizing the fields.
7.5.5 The GNU extensions to ptx

Operating on fields within a line

8.1 cut: Print selected parts of lines | Print selected parts of lines.
8.2 paste: Merge lines of files | Merge lines of files.
8.3 join: Join lines on a common field | Join lines on a common field.

Operating on characters

9.1 tr: Translate, squeeze, and/or delete characters | Translate, squeeze, and/or delete characters.
9.2 expand: Convert tabs to spaces | Convert tabs to spaces.
9.3 unexpand: Convert spaces to tabs | Convert spaces to tabs.

tr: Translate, squeeze, and/or delete characters

9.1.1 Specifying sets of characters
9.1.2 Translating Changing one characters to another.
9.1.3 Squeezing repeats and deleting
9.1.4 Warning messages

Opening the software toolbox

Toolbox introduction
I/O redirection
The who command
The cut command
The sort command
The uniq command
Putting the tools together

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Introduction

This manual is incomplete: No attempt is made to explain basic concepts in a way suitable for novices. Thus, if you are interested, please get involved in improving this manual. The entire GNU community will benefit.

The GNU text utilities are mostly compatible with the POSIX.2 standard.

Please report bugs to bug-textutils@gnu.org. Remember to include the version number, machine architecture, input files, and any other information needed to reproduce the bug: your input, what you expected, what you got, and why it is wrong. Diffs are welcome, but please include a description of the problem as well, since this is sometimes difficult to infer. See section `Bugs' in GNU CC.

This manual was originally derived from the Unix man pages in the distribution, which were written by David MacKenzie and updated by Jim Meyering. What you are reading now is the authoritative documentation for these utilities; the man pages are no longer being maintained. The original fmt man page was written by Ross Paterson. François Pinard did the initial conversion to Texinfo format. Karl Berry did the indexing, some reorganization, and editing of the results. Richard Stallman contributed his usual invaluable insights to the overall process.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. Common options

Certain options are available in all these programs. Rather than writing identical descriptions for each of the programs, they are described here. (In fact, every GNU program accepts (or should accept) these options.)

A few of these programs take arbitrary strings as arguments. In those cases, `--help' and `--version' are taken as these options only if there is one and exactly one command line argument.

`--help'
Print a usage message listing all available options, then exit successfully.

`--version'
Print the version number, then exit successfully.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. Output of entire files

These commands read and write entire files, possibly transforming them in some way.

3.1 cat: Concatenate and write files | Concatenate and write files.
3.2 tac: Concatenate and write files in reverse | Concatenate and write files in reverse.
3.3 nl: Number lines and write files | Number lines and write files.
3.4 od: Write files in octal or other formats | Write files in octal or other formats.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 cat: Concatenate and write files

cat copies each file (`-' means standard input), or standard input if none are given, to standard output. Synopsis:

cat [option] [file]...

The program accepts the following options. Also see 2. Common options.

`-A'
`--show-all'
Equivalent to `-vET'.

`-B'
`--binary'
On MS-DOS and MS-Windows only, read and write the files in binary mode. By default, cat on MS-DOS/MS-Windows uses binary mode only when standard output is redirected to a file or a pipe; this option overrides that. Binary file I/O is used so that the files retain their format (Unix text as opposed to DOS text and binary), because cat is frequently used as a file-copying program. Some options (see below) cause cat read and write files in text mode because then the original file contents aren't important (e.g., when lines are numbered by cat, or when line endings should be marked). This is so these options work as DOS/Windows users would expect; for example, DOS-style text files have their lines end with the CR-LF pair of characters which won't be processed as an empty line by `-b' unless the file is read in text mode.

`-b'
`--number-nonblank'
Number all nonblank output lines, starting with 1. On MS-DOS and MS-Windows, this option causes cat to read and write files in text mode.

`-e'
Equivalent to `-vE'.

`-E'
`--show-ends'
Display a `$' after the end of each line. On MS-DOS and MS-Windows, this option causes cat to read and write files in text mode.

`-n'
`--number'
Number all output lines, starting with 1. On MS-DOS and MS-Windows, this option causes cat to read and write files in text mode.

`-s'
`--squeeze-blank'
Replace multiple adjacent blank lines with a single blank line. On MS-DOS and MS-Windows, this option causes cat to read and write files in text mode.

`-t'
Equivalent to `-vT'.

`-T'
`--show-tabs'
Display TAB characters as `^I'.

`-u'
Ignored; for Unix compatibility.

`-v'
`--show-nonprinting'
Display control characters except for LFD and TAB using `^' notation and precede characters that have the high bit set with `M-'. On MS-DOS and MS-Windows, this option causes cat to read files and standard input in DOS binary mode, so the CR characters at the end of each line are also visible.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 tac: Concatenate and write files in reverse

tac copies each file (`-' means standard input), or standard input if none are given, to standard output, reversing the records (lines by default) in each separately. Synopsis:

tac [option]... [file]...

Records are separated by instances of a string (newline by default). By default, this separator string is attached to the end of the record that it follows in the file.

The program accepts the following options. Also see 2. Common options.

`-b'
`--before'
The separator is attached to the beginning of the record that it precedes in the file.

`-r'
`--regex'
Treat the separator string as a regular expression. Users of tac on MS-DOS/MS-Windows should note that, since tac reads files in binary mode, each line of a text file might end with a CR/LF pair instead of the Unix-style LF.

`-s separator'
`--separator=separator'
Use separator as the record separator, instead of newline.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 nl: Number lines and write files

nl writes each file (`-' means standard input), or standard input if none are given, to standard output, with line numbers added to some or all of the lines. Synopsis:

nl [option]... [file]...

nl decomposes its input into (logical) pages; by default, the line number is reset to 1 at the top of each logical page. nl treats all of the input files as a single document; it does not reset line numbers or logical pages between files.

A logical page consists of three sections: header, body, and footer. Any of the sections can be empty. Each can be numbered in a different style from the others.

The beginnings of the sections of logical pages are indicated in the input file by a line containing exactly one of these delimiter strings:

`\:\:\:'
start of header;
`\:\:'
start of body;
`\:'
start of footer.

The two characters from which these strings are made can be changed from `\' and `:' via options (see below), but the pattern and length of each string cannot be changed.

A section delimiter is replaced by an empty line on output. Any text that comes before the first section delimiter string in the input file is considered to be part of a body section, so nl treats a file that contains no section delimiters as a single body section.

The program accepts the following options. Also see 2. Common options.

`-b style'
`--body-numbering=style'
Select the numbering style for lines in the body section of each logical page. When a line is not numbered, the current line number is not incremented, but the line number separator character is still prepended to the line. The styles are:

`a'
number all lines,
`t'
number only nonempty lines (default for body),
`n'
do not number lines (default for header and footer),
`pregexp'
number only lines that contain a match for regexp.

`-d cd'
`--section-delimiter=cd'
Set the section delimiter characters to cd; default is `\:'. If only c is given, the second remains `:'. (Remember to protect `\' or other metacharacters from shell expansion with quotes or extra backslashes.)

`-f style'
`--footer-numbering=style'
Analogous to `--body-numbering'.

`-h style'
`--header-numbering=style'
Analogous to `--body-numbering'.

`-i number'
`--page-increment=number'
Increment line numbers by number (default 1).

`-l number'
`--join-blank-lines=number'
Consider number (default 1) consecutive empty lines to be one logical line for numbering, and only number the last one. Where fewer than number consecutive empty lines occur, do not number them. An empty line is one that contains no characters, not even spaces or tabs.

`-n format'
`--number-format=format'
Select the line numbering format (default is rn):

`ln'
left justified, no leading zeros;
`rn'
right justified, no leading zeros;
`rz'
right justified, leading zeros.

`-p'
`--no-renumber'
Do not reset the line number at the start of a logical page.

`-s string'
`--number-separator=string'
Separate the line number from the text line in the output with string (default is the TAB character).

`-v number'
`--starting-line-number=number'
Set the initial line number on each logical page to number (default 1).

`-w number'
`--number-width=number'
Use number characters for line numbers (default 6).

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4 od: Write files in octal or other formats

od writes an unambiguous representation of each file (`-' means standard input), or standard input if none are given. Synopsis:

od [option]... [file]...
od -C [file] [[+]offset [[+]label]]

Each line of output consists of the offset in the input, followed by groups of data from the file. By default, od prints the offset in octal, and each group of file data is two bytes of input printed as a single octal number.

The program accepts the following options. Also see 2. Common options.

`-A radix'
`--address-radix=radix'
Select the base in which file offsets are printed. radix can be one of the following:

`d'
decimal;
`o'
octal;
`x'
hexadecimal;
`n'
none (do not print offsets).

The default is octal.

`-j bytes'
`--skip-bytes=bytes'
Skip bytes input bytes before formatting and writing. If bytes begins with `0x' or `0X', it is interpreted in hexadecimal; otherwise, if it begins with `0', in octal; otherwise, in decimal. Appending `b' multiplies bytes by 512, `k' by 1024, and `m' by 1048576.

`-N bytes'
`--read-bytes=bytes'
Output at most bytes bytes of the input. Prefixes and suffixes on bytes are interpreted as for the `-j' option.

`-s [n]'
`--strings[=n]'
Instead of the normal output, output only string constants: at least n (3 by default) consecutive ASCII graphic characters, followed by a null (zero) byte.

`-t type'
`--format=type'
Select the format in which to output the file data. type is a string of one or more of the below type indicator characters. If you include more than one type indicator character in a single type string, or use this option more than once, od writes one copy of each output line using each of the data types that you specified, in the order that you specified.

Adding a trailing "z" to any type specification appends a display of the ASCII character representation of the printable characters to the output line generated by the type specification.

`a'
named character,
`c'
ASCII character or backslash escape,
`d'
signed decimal,
`f'
floating point,
`o'
octal,
`u'
unsigned decimal,
`x'
hexadecimal.

The type a outputs things like `sp' for space, `nl' for newline, and `nul' for a null (zero) byte. Type c outputs ` ', `\n', and \0, respectively.

Except for types `a' and `c', you can specify the number of bytes to use in interpreting each number in the given data type by following the type indicator character with a decimal integer. Alternately, you can specify the size of one of the C compiler's built-in data types by following the type indicator character with one of the following characters. For integers (`d', `o', `u', `x'):

`C'
char,
`S'
short,
`I'
int,
`L'
long.

For floating point (f):

F
float,
D
double,
L
long double.

`-v'
`--output-duplicates'
Output consecutive lines that are identical. By default, when two or more consecutive output lines would be identical, od outputs only the first line, and puts just an asterisk on the following line to indicate the elision.

`-w[n]'
`--width[=n]'
Dump n input bytes per output line. This must be a multiple of the least common multiple of the sizes associated with the specified output types. If n is omitted, the default is 32. If this option is not given at all, the default is 16.

The next several options map the old, pre-POSIX format specification options to the corresponding POSIX format specs. GNU od accepts any combination of old- and new-style options. Format specification options accumulate.

`-a'
Output as named characters. Equivalent to `-ta'.

`-b'
Output as octal bytes. Equivalent to `-toC'.

`-c'
Output as ASCII characters or backslash escapes. Equivalent to `-tc'.

`-d'
Output as unsigned decimal shorts. Equivalent to `-tu2'.

`-f'
Output as floats. Equivalent to `-tfF'.

`-h'
Output as hexadecimal shorts. Equivalent to `-tx2'.

`-i'
Output as decimal shorts. Equivalent to `-td2'.

`-l'
Output as decimal longs. Equivalent to `-td4'.

`-o'
Output as octal shorts. Equivalent to `-to2'.

`-x'
Output as hexadecimal shorts. Equivalent to `-tx2'.

`-C'
`--traditional'
Recognize the pre-POSIX non-option arguments that traditional od accepted. The following syntax:

od --traditional [file] [[+]offset[.][b] [[+]label[.][b]]]

can be used to specify at most one file and optional arguments specifying an offset and a pseudo-start address, label. By default, offset is interpreted as an octal number specifying how many input bytes to skip before formatting and writing. The optional trailing decimal point forces the interpretation of offset as a decimal number. If no decimal is specified and the offset begins with `0x' or `0X' it is interpreted as a hexadecimal number. If there is a trailing `b', the number of bytes skipped will be offset multiplied by 512. The label argument is interpreted just like offset, but it specifies an initial pseudo-address. The pseudo-addresses are displayed in parentheses following any normal address.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Formatting file contents

These commands reformat the contents of files.

4.1 fmt: Reformat paragraph text | Reformat paragraph text.
4.2 pr: Paginate or columnate files for printing | Paginate or columnate files for printing.
4.3 fold: Wrap input lines to fit in specified width | Wrap input lines to fit in specified width.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 fmt: Reformat paragraph text

fmt fills and joins lines to produce output lines of (at most) a given number of characters (75 by default). Synopsis:

fmt [option]... [file]...

fmt reads from the specified file arguments (or standard input if none are given), and writes to standard output.

By default, blank lines, spaces between words, and indentation are preserved in the output; successive input lines with different indentation are not joined; tabs are expanded on input and introduced on output.

fmt prefers breaking lines at the end of a sentence, and tries to avoid line breaks after the first word of a sentence or before the last word of a sentence. A sentence break is defined as either the end of a paragraph or a word ending in any of `.?!', followed by two spaces or end of line, ignoring any intervening parentheses or quotes. Like TeX, fmt reads entire "paragraphs" before choosing line breaks; the algorithm is a variant of that in "Breaking Paragraphs Into Lines" (Donald E. Knuth and Michael F. Plass, Software--Practice and Experience, 11 (1981), 1119--1184).

The program accepts the following options. Also see 2. Common options.

`-c'
`--crown-margin'
Crown margin mode: preserve the indentation of the first two lines within a paragraph, and align the left margin of each subsequent line with that of the second line.

`-t'
`--tagged-paragraph'
Tagged paragraph mode: like crown margin mode, except that if indentation of the first line of a paragraph is the same as the indentation of the second, the first line is treated as a one-line paragraph.

`-s'
`--split-only'
Split lines only. Do not join short lines to form longer ones. This prevents sample lines of code, and other such "formatted" text from being unduly combined.

`-u'
`--uniform-spacing'
Uniform spacing. Reduce spacing between words to one space, and spacing between sentences to two spaces.

`-width'
`-w width'
`--width=width'
Fill output lines up to width characters (default 75). fmt initially tries to make lines about 7% shorter than this, to give it room to balance line lengths.

`-p prefix'
`--prefix=prefix'
Only lines beginning with prefix (possibly preceded by whitespace) are subject to formatting. The prefix and any preceding whitespace are stripped for the formatting and then re-attached to each formatted output line. One use is to format certain kinds of program comments, while leaving the code unchanged.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2 pr: Paginate or columnate files for printing

pr writes each file (`-' means standard input), or standard input if none are given, to standard output, paginating and optionally outputting in multicolumn format; optionally merges all files, printing all in parallel, one per column. Synopsis:

pr [option]... [file]...

By default, a 5-line header is printed at each page: two blank lines; a line with the date, the filename, and the page count; and two more blank lines. A footer of five blank lines is also printed. With the `-F' option, a 3-line header is printed: the leading two blank lines are omitted; no footer is used. The default page_length in both cases is 66 lines. The default number of text lines changes from 56 (without `-F') to 63 (with `-F'). The text line of the header takes up the full page_width in the form `yyyy-mm-dd HH:MM string Page nnnn'. String is a centered header string.

Form feeds in the input cause page breaks in the output. Multiple form feeds produce empty pages.

Columns are of equal width, separated by an optional string (default is `space'). For multicolumn output, lines will always be truncated to page_width (default 72), unless you use the `-J' option. For single column output no line truncation occurs by default. Use `-W' option to truncate lines in that case.

Including version 1.22i:

Some small letter options (`-s', `-w') has been redefined with the object of a better posix compliance. The output of some further cases has been adapted to other unixes. A violation of downward compatibility has to be accepted.

Some new capital letter options (`-J', `-S', `-W') has been introduced to turn off unexpected interferences of small letter options. The `-N' option and the second argument last_page of `+FIRST_PAGE' offer more flexibility. The detailed handling of form feeds set in the input files requires `-T' option.

Capital letter options dominate small letter ones.

Some of the option-arguments (compare `-s', `-S', `-e', `-i', `-n') cannot be specified as separate arguments from the preceding option letter (already stated in the posix specification).

The program accepts the following options. Also see 2. Common options.

`+first_page[:last_page]'
`--pages=first_page[:last_page]'
Begin printing with page first_page and stop with last_page. Missing `:last_page' implies end of file. While estimating the number of skipped pages each form feed in the input file results in a new page. Page counting with and without `+first_page' is identical. By default, counting starts with the first page of input file (not first page printed). Line numbering may be altered by `-N' option.

`-column'
`--columns=column'
With each single file, produce column columns of output (default is 1) and print columns down, unless `-a' is used. The column width is automatically decreased as column increases; unless you use the `-W/-w' option to increase page_width as well. This option might well cause some lines to be truncated. The number of lines in the columns on each page are balanced. The options `-e' and `-i' are on for multiple text-column output. Together with `-J' option column alignment and line truncation is turned off. Lines of full length are joined in a free field format and `-S' option may set field separators. `-column' may not be used with `-m' option.

`-a'
`--across'
With each single file, print columns across rather than down. The `-column' option must be given with column greater than one. If a line is too long to fit in a column, it is truncated.

`-c'
`--show-control-chars'
Print control characters using hat notation (e.g., `^G'); print other unprintable characters in octal backslash notation. By default, unprintable characters are not changed.

`-d'
`--double-space'
Double space the output.

`-e[in-tabchar[in-tabwidth]]'
`--expand-tabs[=in-tabchar[in-tabwidth]]'
Expand tabs to spaces on input. Optional argument in-tabchar is the input tab character (default is the TAB character). Second optional argument in-tabwidth is the input tab character's width (default is 8).

`-f'
`-F'
`--form-feed'
Use a form feed instead of newlines to separate output pages. The default page length of 66 lines is not altered. But the number of lines of text per page changes from default 56 to 63 lines.

`-h HEADER'
`--header=HEADER'
Replace the filename in the header with the centered string header. Left-hand-side truncation (marked by a `*') may occur if the total header line `yyyy-mm-dd HH:MM HEADER Page nnnn' becomes larger than page_width. `-h ""' prints a blank line header. Don't use `-h""'. A space between the `-h' option and the argument is always indispensable.

`-i[out-tabchar[out-tabwidth]]'
`--output-tabs[=out-tabchar[out-tabwidth]]'
Replace spaces with tabs on output. Optional argument out-tabchar is the output tab character (default is the TAB character). Second optional argument out-tabwidth is the output tab character's width (default is 8).

`-J'
`--join-lines'
Merge lines of full length. Used together with the column options `-column', `-a -column' or `-m'. Turns off `-W/-w' line truncation; no column alignment used; may be used with `-S[string]'. `-J' has been introduced (together with `-W' and `-S') to disentangle the old (posix compliant) options `-w' and `-s' along with the three column options.

`-l page_length'
`--length=page_length'
Set the page length to page_length (default 66) lines, including the lines of the header [and the footer]. If page_length is less than or equal 10 (and <= 3 with `-F'), the header and footer are omitted, and all form feeds set in input files are eliminated, as if the `-T' option had been given.

`-m'
`--merge'
Merge and print all files in parallel, one in each column. If a line is too long to fit in a column, it is truncated, unless `-J' option is used. `-S[string]' may be used. Empty pages in some files (form feeds set) produce empty columns, still marked by string. The result is a continuous line numbering and column marking throughout the whole merged file. Completely empty merged pages show no separators or line numbers. The default header becomes `yyyy-mm-dd HH:MM <blanks> Page nnnn'; may be used with `-h header' to fill up the middle blank part.

`-n[number-separator[digits]]'
`--number-lines[=number-separator[digits]]'
Provide digits digit line numbering (default for digits is 5). With multicolumn output the number occupies the first digits column positions of each text column or only each line of `-m' output. With single column output the number precedes each line just as `-m' does. Default counting of the line numbers starts with 1st line of the input file (not the 1st line printed, compare the `--page' option and `-N' option). Optional argument number-separator is the character appended to the line number to separate it from the text followed. The default separator is the TAB character. In a strict sense a TAB is always printed with single column output only. The TAB-width varies with the TAB-position, e.g. with the left margin specified by `-o' option. With multicolumn output priority is given to `equal width of output columns' (a posix specification). The TAB-width is fixed to the value of the 1st column and does not change with different values of left margin. That means a fixed number of spaces is always printed in the place of the number-separator tab. The tabification depends upon the output position.

`-N line_number'
`--first-line-number=line_number'
Start line counting with the number line_number at first line of first page printed (in most cases not the first line of the input file).

`-o margin'
`--indent=margin'
Indent each line with a margin margin spaces wide (default is zero). The total page width is the size of the margin plus the page_width set with the `-W/-w' option. A limited overflow may occur with numbered single column output (compare `-n' option).

`-r'
`--no-file-warnings'
Do not print a warning message when an argument file cannot be opened. (The exit status will still be nonzero, however.)

`-s[char]'
`--separator[=char]'
Separate columns by a single character char. Default for char is the TAB character without `-w' and `no character' with `-w'. Without `-s' default separator `space' is set. `-s[char]' turns off line truncation of all three column options (`-COLUMN'|`-a -COLUMN'|`-m') except `-w' is set. That is a posix compliant formulation.

`-S[string]'
`--sep-string[=string]'
Use string to separate output columns. The `-S' option doesn't affect the `-W/-w' option, unlike the `-s' option which does. It does not affect line truncation or column alignment. Without `-S', and with `-J', pr uses the default output separator, TAB. Without `-S' or `-J', pr uses a `space' (same as `-S" "'). Using `-S' with no string is equivalent to `-S""'. Note that for some of pr's options the single-letter option character must be followed immediately by any corresponding argument; there may not be any intervening white space. `-S/-s' is one of them. Don't use `-S "STRING"'. POSIX requires this.

`-t'
`--omit-header'
Do not print the usual header [and footer] on each page, and do not fill out the bottom of pages (with blank lines or a form feed). No page structure is produced, but form feeds set in the input files are retained. The predefined pagination is not changed. `-t' or `-T' may be useful together with other options; e.g.: `-t -e4', expand TAB characters in the input file to 4 spaces but don't make any other changes. Use of `-t' overrides `-h'.

`-T'
`--omit-pagination'
Do not print header [and footer]. In addition eliminate all form feeds set in the input files.

`-v'
`--show-nonprinting'
Print unprintable characters in octal backslash notation.

`-w page_width'
`--width=page_width'
Set page width to page_width characters for multiple text-column output only (default for page_width is 72). `-s[CHAR]' turns off the default page width and any line truncation and column alignment. Lines of full length are merged, regardless of the column options set. No page_width setting is possible with single column output. A posix compliant formulation.

`-W page_width'
`--page_width=page_width'
Set the page width to page_width characters. That's valid with and without a column option. Text lines are truncated, unless `-J' is used. Together with one of the three column options (`-column', `-a -column' or `-m') column alignment is always used. The separator options `-S' or `-s' don't affect the `-W' option. Default is 72 characters. Without `-W page_width' and without any of the column options NO line truncation is used (defined to keep downward compatibility and to meet most frequent tasks). That's equivalent to `-W 72 -J'. With and without `-W page_width' the header line is always truncated to avoid line overflow.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3 fold: Wrap input lines to fit in specified width

fold writes each file (`-' means standard input), or standard input if none are given, to standard output, breaking long lines. Synopsis:

fold [option]... [file]...

By default, fold breaks lines wider than 80 columns. The output is split into as many lines as necessary.

fold counts screen columns by default; thus, a tab may count more than one column, backspace decreases the column count, and carriage return sets the column to zero.

The program accepts the following options. Also see 2. Common options.

`-b'
`--bytes'
Count bytes rather than columns, so that tabs, backspaces, and carriage returns are each counted as taking up one column, just like other characters.

`-s'
`--spaces'
Break at word boundaries: the line is broken after the last blank before the maximum line length. If the line contains no such blanks, the line is broken at the maximum line length as usual.

`-w width'
`--width=width'
Use a maximum line length of width columns instead of 80.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Output of parts of files

These commands output pieces of the input.

5.1 head: Output the first part of files | Output the first part of files.
5.2 tail: Output the last part of files | Output the last part of files.
5.3 split: Split a file into fixed-size pieces | Split a file into fixed-size pieces.
5.4 csplit: Split a file into context-determined pieces | Split a file into context-determined pieces.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 head: Output the first part of files

head prints the first part (10 lines by default) of each file; it reads from standard input if no files are given or when given a file of `-'. Synopses:

head [option]... [file]...
head -number [option]... [file]...

If more than one file is specified, head prints a one-line header consisting of
==> file name <==
before the output for each file.

head accepts two option formats: the new one, in which numbers are arguments to the options (`-q -n 1'), and the old one, in which the number precedes any option letters (`-1q').

The program accepts the following options. Also see 2. Common options.

`-countoptions'
This option is only recognized if it is specified first. count is a decimal number optionally followed by a size letter (`b', `k', `m') as in -c, or `l' to mean count by lines, or other option letters (`cqv').

`-c bytes'
`--bytes=bytes'
Print the first bytes bytes, instead of initial lines. Appending `b' multiplies bytes by 512, `k' by 1024, and `m' by 1048576.

`-n n'
`--lines=n'
Output the first n lines.

`-q'
`--quiet'
`--silent'
Never print file name headers.

`-v'
`--verbose'
Always print file name headers.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 tail: Output the last part of files

tail prints the last part (10 lines by default) of each file; it reads from standard input if no files are given or when given a file of `-'. Synopses:

tail [option]... [file]...
tail -number [option]... [file]...
tail +number [option]... [file]...

If more than one file is specified, tail prints a one-line header consisting of
==> file name <==
before the output for each file.

GNU tail can output any amount of data (some other versions of tail cannot). It also has no `-r' option (print in reverse), since reversing a file is really a different job from printing the end of a file; BSD tail (which is the one with -r) can only reverse files that are at most as large as its buffer, which is typically 32k. A more reliable and versatile way to reverse files is the GNU tac command.

tail accepts two option formats: the new one, in which numbers are arguments to the options (`-n 1'), and the old one, in which the number precedes any option letters (`-1' or `+1').

If any option-argument is a number n starting with a `+', tail begins printing with the nth item from the start of each file, instead of from the end.

The program accepts the following options. Also see 2. Common options.

`-count'
`+count'
This option is only recognized if it is specified first. count is a decimal number optionally followed by a size letter (`b', `k', `m') as in -c, or `l' to mean count by lines, or other option letters (`cfqv').

`-c bytes'
`--bytes=bytes'
Output the last bytes bytes, instead of final lines. Appending `b' multiplies bytes by 512, `k' by 1024, and `m' by 1048576.

`-f'
`--follow[=how]'
Loop forever trying to read more characters at the end of the file, presumably because the file is growing. This option is ignored when reading from a pipe. If more than one file is given, tail prints a header whenever it gets output from a different file, to indicate which file that output is from.

There are two ways to specify how you'd like to track files with this option, but that difference is noticeable only when a followed file is removed or renamed. If you'd like to continue to track the end of a growing file even after it has been unlinked, use `--follow=descriptor'. This is the default behavior, but it is not useful if you're tracking a log file that may be rotated (removed or renamed, then reopened). In that case, use `--follow=name' to track the named file by reopening it periodically to see if it has been removed and recreated by some other program.

No matter which method you use, if the tracked file is determined to have shrunk, tail prints a message saying the file has been truncated and resumes tracking the end of the file from the newly-determined endpoint.

When a file is removed, tail's behavior depends on whether it is following the name or the descriptor. When following by name, tail can detect that a file has been removed and gives a message to that effect, and if `--retry' has been specified it will continue checking periodically to see if the file reappears. When following a descriptor, tail does not detect that the file has been unlinked or renamed and issues no message; even though the file may no longer be accessible via its original name, it may still be growing.

The option values `descriptor' and `name' may be specified only with the long form of the option, not with `-f'.

`--retry'
This option is meaningful only when following by name. Without this option, when tail encounters a file that doesn't exist or is otherwise inaccessible, it reports that fact and never checks it again.

`--sleep-interval=n'
Change the number of seconds to wait between iterations (the default is 1). During one iteration, every specified file is checked to see if it has changed size.

`--pid=pid'
When following by name or by descriptor, you may specify the process ID, pid, of the sole writer of all file arguments. Then, shortly after that process terminates, tail will also terminate. This will work properly only if the writer and the tailing process are running on the same machine. For example, to save the output of a build in a file and to watch the file grow, if you invoke make and tail like this then the tail process will stop when your build completes. Without this option, you would have had to kill the tail -f process yourself.
$ make >& makerr & tail --pid=$! -f makerr
If you specify a pid that is not in use or that does not correspond to the process that is writing to the tailed files, then tail may terminate long before any files stop growing or it may not terminate until long after the real writer has terminated.

`--max-consecutive-size-changes=n'
This option is meaningful only when following by name. Use it to control how long tail follows the descriptor of a file that continues growing at a rapid pace even after it is deleted or renamed. After detecting n consecutive size changes for a file, open/fstat the file to determine if that file name is still associated with the same device/inode-number pair as before. See the output of tail --help for the default value.

`--max-unchanged-stats=n'
When tailing a file by name, if there have been this many consecutive iterations for which the size has remained the same, then open/fstat the file to determine if that file name is still associated with the same device/inode-number pair as before. When following a log file that is rotated this is approximately the number of seconds between when tail prints the last pre-rotation lines and when it prints the lines that have accumulated in the new log file. See the output of tail --help for the default value. This option is meaningful only when following by name.

`-n n'
`--lines=n'
Output the last n lines.

`-q'
`-quiet'
`--silent'
Never print file name headers.

`-v'
`--verbose'
Always print file name headers.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.3 split: Split a file into fixed-size pieces

split creates output files containing consecutive sections of input (standard input if none is given or input is `-'). Synopsis:

split [option] [input [prefix]]

By default, split puts 1000 lines of input (or whatever is left over for the last section), into each output file.

The output files' names consist of prefix (`x' by default) followed by a group of letters `aa', `ab', and so on, such that concatenating the output files in sorted order by file name produces the original input file. (If more than 676 output files are required, split uses `zaa', `zab', etc.)

The program accepts the following options. Also see 2. Common options.

`-lines'
`-l lines'
`--lines=lines'
Put lines lines of input into each output file.

`-b bytes'
`--bytes=bytes'
Put the first bytes bytes of input into each output file. Appending `b' multiplies bytes by 512, `k' by 1024, and `m' by 1048576.

`-C bytes'
`--line-bytes=bytes'
Put into each output file as many complete lines of input as possible without exceeding bytes bytes. For lines longer than bytes bytes, put bytes bytes into each output file until less than bytes bytes of the line are left, then continue normally. bytes has the same format as for the `--bytes' option.

`--verbose'
Write a diagnostic to standard error just before each output file is opened.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4 csplit: Split a file into context-determined pieces

csplit creates zero or more output files containing sections of input (standard input if input is `-'). Synopsis:

csplit [option]... input pattern...

The contents of the output files are determined by the pattern arguments, as detailed below. An error occurs if a pattern argument refers to a nonexistent line of the input file (e.g., if no remaining line matches a given regular expression). After every pattern has been matched, any remaining input is copied into one last output file.

By default, csplit prints the number of bytes written to each output file after it has been created.

The types of pattern arguments are:

`n'
Create an output file containing the input up to but not including line n (a positive integer). If followed by a repeat count, also create an output file containing the next line lines of the input file once for each repeat.

`/regexp/[offset]'
Create an output file containing the current line up to (but not including) the next line of the input file that contains a match for regexp. The optional offset is a `+' or `-' followed by a positive integer. If it is given, the input up to the matching line plus or minus offset is put into the output file, and the line after that begins the next section of input.

`%regexp%[offset]'
Like the previous type, except that it does not create an output file, so that section of the input file is effectively ignored.

`{repeat-count}'
Repeat the previous pattern repeat-count additional times. repeat-count can either be a positive integer or an asterisk, meaning repeat as many times as necessary until the input is exhausted.

The output files' names consist of a prefix (`xx' by default) followed by a suffix. By default, the suffix is an ascending sequence of two-digit decimal numbers from `00' and up to `99'. In any case, concatenating the output files in sorted order by filename produces the original input file.

By default, if csplit encounters an error or receives a hangup, interrupt, quit, or terminate signal, it removes any output files that it has created so far before it exits.

The program accepts the following options. Also see 2. Common options.

`-f prefix'
`--prefix=prefix'
Use prefix as the output file name prefix.

`-b suffix'
`--suffix=suffix'
Use suffix as the output file name suffix. When this option is specified, the suffix string must include exactly one printf(3)-style conversion specification, possibly including format specification flags, a field width, a precision specifications, or all of these kinds of modifiers. The format letter must convert a binary integer argument to readable form; thus, only `d', `i', `u', `o', `x', and `X' conversions are allowed. The entire suffix is given (with the current output file number) to sprintf(3) to form the file name suffixes for each of the individual output files in turn. If this option is used, the `--digits' option is ignored.

`-n digits'
`--digits=digits'
Use output file names containing numbers that are digits digits long instead of the default 2.

`-k'
`--keep-files'
Do not remove output files when errors are encountered.

`-z'
`--elide-empty-files'
Suppress the generation of zero-length output files. (In cases where the section delimiters of the input file are supposed to mark the first lines of each of the sections, the first output file will generally be a zero-length file unless you use this option.) The output file sequence numbers always run consecutively starting from 0, even when this option is specified.

`-s'
`-q'
`--silent'
`--quiet'
Do not print counts of output file sizes.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Summarizing files

These commands generate just a few numbers representing entire contents of files.

6.1 wc: Print byte, word, and line counts | Print byte, word, and line counts.
6.2 sum: Print checksum and block counts | Print checksum and block counts.
6.3 cksum: Print CRC checksum and byte counts | Print CRC checksum and byte counts.
6.4 md5sum: Print or check message-digests | Print or check message-digests.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.1 wc: Print byte, word, and line counts

wc counts the number of bytes, whitespace-separated words, and newlines in each given file, or standard input if none are given or for a file of `-'. Synopsis:

wc [option]... [file]...

wc prints one line of counts for each file, and if the file was given as an argument, it prints the file name following the counts. If more than one file is given, wc prints a final line containing the cumulative counts, with the file name `total'. The counts are printed in this order: newlines, words, bytes. By default, each count is output right-justified in a 7-byte field with one space between fields so that the numbers and file names line up nicely in columns. However, POSIX requires that there be exactly one space separating columns. You can make wc use the POSIX-mandated output format by setting the POSIXLY_CORRECT environment variable.

By default, wc prints all three counts. Options can specify that only certain counts be printed. Options do not undo others previously given, so

wc --bytes --words

prints both the byte counts and the word counts.

With the --max-line-length option, wc prints the length of the longest line per file, and if there is more than one file it prints the maximum (not the sum) of those lengths.

The program accepts the following options. Also see 2. Common options.

`-c'
`--bytes'
`--chars'
Print only the byte counts.

`-w'
`--words'
Print only the word counts.

`-l'
`--lines'
Print only the newline counts.

`-L'
`--max-line-length'
Print only the maximum line lengths.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.2 sum: Print checksum and block counts

sum computes a 16-bit checksum for each given file, or standard input if none are given or for a file of `-'. Synopsis:

sum [option]... [file]...

sum prints the checksum for each file followed by the number of blocks in the file (rounded up). If more than one file is given, file names are also printed (by default). (With the `--sysv' option, corresponding file name are printed when there is at least one file argument.)

By default, GNU sum computes checksums using an algorithm compatible with BSD sum and prints file sizes in units of 1024-byte blocks.

The program accepts the following options. Also see 2. Common options.

`-r'
Use the default (BSD compatible) algorithm. This option is included for compatibility with the System V sum. Unless `-s' was also given, it has no effect.

`-s'
`--sysv'
Compute checksums using an algorithm compatible with System V sum's default, and print file sizes in units of 512-byte blocks.

sum is provided for compatibility; the cksum program (see next section) is preferable in new applications.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.3 cksum: Print CRC checksum and byte counts

cksum computes a cyclic redundancy check (CRC) checksum for each given file, or standard input if none are given or for a file of `-'. Synopsis:

cksum [option]... [file]...

cksum prints the CRC checksum for each file along with the number of bytes in the file, and the filename unless no arguments were given.

cksum is typically used to ensure that files transferred by unreliable means (e.g., netnews) have not been corrupted, by comparing the cksum output for the received files with the cksum output for the original files (typically given in the distribution).

The CRC algorithm is specified by the POSIX.2 standard. It is not compatible with the BSD or System V sum algorithms (see the previous section); it is more robust.

The only options are `--help' and `--version'. See section 2. Common options.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6.4 md5sum: Print or check message-digests

md5sum computes a 128-bit checksum (or fingerprint or message-digest) for each specified file. If a file is specified as `-' or if no files are given md5sum computes the checksum for the standard input. md5sum can also determine whether a file and checksum are consistent. Synopses:

md5sum [option]... [file]...
md5sum [option]... --check [file]

For each file, `md5sum' outputs the MD5 checksum, a flag indicating a binary or text input file, and the filename. If file is omitted or specified as `-', standard input is read.

The program accepts the following options. Also see 2. Common options.

`-b'
`--binary'
Treat all input files as binary. This option has no effect on Unix systems, since they don't distinguish between binary and text files. This option is useful on systems that have different internal and external character representations. On MS-DOS and MS-Windows, this is the default.

`-c'
`--check'
Read filenames and checksum information from the single file (or from stdin if no file was specified) and report whether each named file and the corresponding checksum data are consistent. The input to this mode of md5sum is usually the output of a prior, checksum-generating run of `md5sum'. Each valid line of input consists of an MD5 checksum, a binary/text flag, and then a filename. Binary files are marked with `*', text with ` '. For each such line, md5sum reads the named file and computes its MD5 checksum. Then, if the computed message digest does not match the one on the line with the filename, the file is noted as having failed the test. Otherwise, the file passes the test. By default, for each valid line, one line is written to standard output indicating whether the named file passed the test. After all checks have been performed, if there were any failures, a warning is issued to standard error. Use the `--status' option to inhibit that output. If any listed file cannot be opened or read, if any valid line has an MD5 checksum inconsistent with the associated file, or if no valid line is found, md5sum exits with nonzero status. Otherwise, it exits successfully.

`--status'
This option is useful only when verifying checksums. When verifying checksums, don't generate the default one-line-per-file diagnostic and don't output the warning summarizing any failures. Failures to open or read a file still evoke individual diagnostics to standard error. If all listed files are readable and are consistent with the associated MD5 checksums, exit successfully. Otherwise exit with a status code indicating there was a failure.

`-t'
`--text'
Treat all input files as text files. This is the reverse of `--binary'.

`-w'
`--warn'
When verifying checksums, warn about improperly formatted MD5 checksum lines. This option is useful only if all but a few lines in the checked input are valid.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. Operating on sorted files

These commands work with (or produce) sorted files.

7.1 sort: Sort text files | Sort text files.
7.2 uniq: Uniquify files | Uniquify files.
7.3 comm: Compare two sorted files line by line | Compare two sorted files line by line.
7.5 ptx: Produce permuted indexes | Produce a permuted index of file contents.
7.4 tsort: Topological sort | Topological sort.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.1 sort: Sort text files

sort sorts, merges, or compares all the lines from the given files, or standard input if none are given or for a file of `-'. By default, sort writes the results to standard output. Synopsis:

sort [option]... [file]...

sort has three modes of operation: sort (the default), merge, and check for sortedness. The following options change the operation mode:

`-c'
Check whether the given files are already sorted: if they are not all sorted, print an error message and exit with a status of 1. Otherwise, exit successfully.

`-m'
Merge the given files by sorting them as a group. Each input file must always be individually sorted. It always works to sort instead of merge; merging is provided because it is faster, in the case where it works.

A pair of lines is compared as follows: if any key fields have been specified, sort compares each pair of fields, in the order specified on the command line, according to the associated ordering options, until a difference is found or no fields are left. Unless otherwise specified, all comparisons use the character collating sequence specified by the LC_COLLATE locale.

If any of the global options `Mbdfinr' are given but no key fields are specified, sort compares the entire lines according to the global options.

Finally, as a last resort when all keys compare equal (or if no ordering options were specified at all), sort compares the entire lines. The last resort comparison honors the `-r' global option. The `-s' (stable) option disables this last-resort comparison so that lines in which all fields compare equal are left in their original relative order. If no fields or global options are specified, `-s' has no effect.

GNU sort (as specified for all GNU utilities) has no limits on input line length or restrictions on bytes allowed within lines. In addition, if the final byte of an input file is not a newline, GNU sort silently supplies one. A line's trailing newline is part of the line for comparison purposes; for example, with no options in an ASCII locale, a line starting with a tab sorts before an empty line because tab precedes newline in the ASCII collating sequence.

Upon any error, sort exits with a status of `2'.

If the environment variable TMPDIR is set, sort uses its value as the directory for temporary files instead of `/tmp'. The `-T tempdir' option in turn overrides the environment variable.

The following options affect the ordering of output lines. They may be specified globally or as part of a specific key field. If no key fields are specified, global options apply to comparison of entire lines; otherwise the global options are inherited by key fields that do not specify any special options of their own. The `-b', `-d', `-f' and `-i' options classify characters according to the LC_CTYPE locale.

`-b'
Ignore leading blanks when finding sort keys in each line.

`-d'
Sort in phone directory order: ignore all characters except letters, digits and blanks when sorting.

`-f'
Fold lowercase characters into the equivalent uppercase characters when sorting so that, for example, `b' and `B' sort as equal.

`-g'
Sort numerically, using the standard C function strtod to convert a prefix of each line to a double-precision floating point number. This allows floating point numbers to be specified in scientific notation, like 1.0e-34 and 10e100. Do not report overflow, underflow, or conversion errors. Use the following collating sequence:

  • Lines that do not start with numbers (all considered to be equal).
  • NaNs ("Not a Number" values, in IEEE floating point arithmetic) in a consistent but machine-dependent order.
  • Minus infinity.
  • Finite numbers in ascending numeric order (with -0 and +0 equal).
  • Plus infinity.

Use this option only if there is no alternative; it is much slower than `-n' and it can lose information when converting to floating point.

`-i'
Ignore unprintable characters.

`-M'
An initial string, consisting of any amount of whitespace, followed by a month name abbreviation, is folded to UPPER case and compared in the order `JAN' < `FEB' < ... < `DEC'. Invalid names compare low to valid names. The LC_TIME locale determines the month spellings.

`-n'
Sort numerically: the number begins each line; specifically, it consists of optional whitespace, an optional `-' sign, and zero or more digits possibly separated by thousands separators, optionally followed by a radix character and zero or more digits. The LC_NUMERIC locale specifies the radix character and thousands separator.

sort -n uses what might be considered an unconventional method to compare strings representing floating point numbers. Rather than first converting each string to the C double type and then comparing those values, sort aligns the radix characters in the two strings and compares the strings a character at a time. One benefit of using this approach is its speed. In practice this is much more efficient than performing the two corresponding string-to-double (or even string-to-integer) conversions and then comparing doubles. In addition, there is no corresponding loss of precision. Converting each string to double before comparison would limit precision to about 16 digits on most systems.

Neither a leading `+' nor exponential notation is recognized. To compare such strings numerically, use the `-g' option.

`-r'
Reverse the result of comparison, so that lines with greater key values appear earlier in the output instead of later.

Other options are:

`-o output-file'
Write output to output-file instead of standard output. If output-file is one of the input files, sort copies it to a temporary file before sorting and writing the output to output-file.

`-t separator'
Use character separator as the field separator when finding the sort keys in each line. By default, fields are separated by the empty string between a non-whitespace character and a whitespace character. That is, given the input line ` foo bar', sort breaks it into fields ` foo' and ` bar'. The field separator is not considered to be part of either the field preceding or the field following.

`-u'
For the default case or the `-m' option, only output the first of a sequence of lines that compare equal. For the `-c' option, check that no pair of consecutive lines compares equal.

`-k pos1[,pos2]'
The recommended, POSIX, option for specifying a sort field. The field consists of the part of the line between pos1 and pos2 (or the end of the line, if pos2 is omitted), inclusive. Fields and character positions are numbered starting with 1. So to sort on the second field, you'd use `-k 2,2' See below for more examples.

`-z'
Treat the input as a set of lines, each terminated by a zero byte (ASCII NUL (Null) character) instead of an ASCII LF (Line Feed). This option can be useful in conjunction with `perl -0' or `find -print0' and `xargs -0' which do the same in order to reliably handle arbitrary pathnames (even those which contain Line Feed characters.)

`+pos1[-pos2]'
The obsolete, traditional option for specifying a sort field. The field consists of the line between pos1 and up to but not including pos2 (or the end of the line if pos2 is omitted). Fields and character positions are numbered starting with 0. See below.

In addition, when GNU sort is invoked with exactly one argument, options `--help' and `--version' are recognized. See section 2. Common options.

Historical (BSD and System V) implementations of sort have differed in their interpretation of some options, particularly `-b', `-f', and `-n'. GNU sort follows the POSIX behavior, which is usually (but not always!) like the System V behavior. According to POSIX, `-n' no longer implies `-b'. For consistency, `-M' has been changed in the same way. This may affect the meaning of character positions in field specifications in obscure cases. The only fix is to add an explicit `-b'.

A position in a sort field specified with the `-k' or `+' option has the form `f.c', where f is the number of the field to use and c is the number of the first character from the beginning of the field (for `+pos') or from the end of the previous field (for `-pos'). If the `.c' is omitted, it is taken to be the first character in the field. If the `-b' option was specified, the `.c' part of a field specification is counted from the first nonblank character of the field (for `+pos') or from the first nonblank character following the previous field (for `-pos').

A sort key option may also have any of the option letters `Mbdfinr' appended to it, in which case the global ordering options are not used for that particular field. The `-b' option may be independently attached to either or both of the `+pos' and `-pos' parts of a field specification, and if it is inherited from the global options it will be attached to both. Keys may span multiple fields.

Here are some examples to illustrate various combinations of options. In them, the POSIX `-k' option is used to specify sort keys rather than the obsolete `+pos1-pos2' syntax.

  • Sort in descending (reverse) numeric order.

    sort -nr

    Sort alphabetically, omitting the first and second fields. This uses a single key composed of the characters beginning at the start of field three and extending to the end of each line.

    sort -k3

  • Sort numerically on the second field and resolve ties by sorting alphabetically on the third and fourth characters of field five. Use `:' as the field delimiter.

    sort -t : -k 2,2n -k 5.3,5.4

    Note that if you had written `-k 2' instead of `-k 2,2' `sort' would have used all characters beginning in the second field and extending to the end of the line as the primary numeric key. For the large majority of applications, treating keys spanning more than one field as numeric will not do what you expect.

    Also note that the `n' modifier was applied to the field-end specifier for the first key. It would have been equivalent to specify `-k 2n,2' or `-k 2n,2n'. All modifiers except `b' apply to the associated field, regardless of whether the modifier character is attached to the field-start and/or the field-end part of the key specifier.

  • Sort the password file on the fifth field and ignore any leading white space. Sort lines with equal values in field five on the numeric user ID in field three.

    sort -t : -k 5b,5 -k 3,3n /etc/passwd

    An alternative is to use the global numeric modifier `-n'.

    sort -t : -n -k 5b,5 -k 3,3 /etc/passwd

  • Generate a tags file in case insensitive sorted order.
    find src -type f -print0 | sort -t / -z -f | xargs -0 etags --append

    The use of `-print0', `-z', and `-0' in this case mean that pathnames that contain Line Feed characters will not get broken up by the sort operation.

    Finally, to ignore both leading and trailing white space, you could have applied the `b' modifier to the field-end specifier for the first key,

    sort -t : -n -k 5b,5b -k 3,3 /etc/passwd

    or by using the global `-b' modifier instead of `-n' and an explicit `n' with the second key specifier.

    sort -t : -b -k 5,5 -k 3,3n /etc/passwd

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.2 uniq: Uniquify files

uniq writes the unique lines in the given `input', or standard input if nothing is given or for an input name of `-'. Synopsis:

uniq [option]... [input [output]]

By default, uniq prints the unique lines in a sorted file, i.e., discards all but one of identical successive lines. Optionally, it can instead show only lines that appear exactly once, or lines that appear more than once.

The input must be sorted. If your input is not sorted, perhaps you want to use sort -u.

If no output file is specified, uniq writes to standard output.

The program accepts the following options. Also see 2. Common options.

`-n'
`-f n'
`--skip-fields=n'
Skip n fields on each line before checking for uniqueness. Fields are sequences of non-space non-tab characters that are separated from each other by at least one spaces or tabs.

`+n'
`-s n'
`--skip-chars=n'
Skip n characters before checking for uniqueness. If you use both the field and character skipping options, fields are skipped over first.

`-c'
`--count'
Print the number of times each line occurred along with the line.

`-i'
`--ignore-case'
Ignore differences in case when comparing lines.

`-d'
`--repeated'
Print only duplicate lines.

`-D'
`--all-repeated'
Print all duplicate lines and only duplicate lines. This option is useful mainly in conjunction with other options e.g., to ignore case or to compare only selected fields. This is a GNU extension.

`-u'
`--unique'
Print only unique lines.

`-w n'
`--check-chars=n'
Compare n characters on each line (after skipping any specified fields and characters). By default the entire rest of the lines are compared.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.3 comm: Compare two sorted files line by line

comm writes to standard output lines that are common, and lines that are unique, to two input files; a file name of `-' means standard input. Synopsis:

comm [option]... file1 file2

Before comm can be used, the input files must be sorted using the collating sequence specified by the LC_COLLATE locale, with trailing newlines significant. If an input file ends in a non-newline character, a newline is silently appended. The sort command with no options always outputs a file that is suitable input to comm.

With no options, comm produces three column output. Column one contains lines unique to file1, column two contains lines unique to file2, and column three contains lines common to both files. Columns are separated by a single TAB character.

The options `-1', `-2', and `-3' suppress printing of the corresponding columns. Also see 2. Common options.

Unlike some other comparison utilities, comm has an exit status that does not depend on the result of the comparison. Upon normal completion comm produces an exit code of zero. If there is an error it exits with nonzero status.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.4 tsort: Topological sort

tsort performs a topological sort on the given file, or standard input if no input file is given or for a file of `-'. Synopsis:

tsort [option] [file]

tsort reads its input as pairs of strings, separated by blanks, indicating a partial ordering. The output is a total ordering that corresponds to the given partial ordering.

For example

tsort <<EOF
a b c
d
e f
b c d e
EOF

will produce the output

a
b
c
d
e
f

tsort will detect cycles in the input and writes the first cycle encountered to standard error.

Note that for a given partial ordering, generally there is no unique total ordering.

The only options are `--help' and `--version'. See section 2. Common options.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5 ptx: Produce permuted indexes

ptx reads a text file and essentially produces a permuted index, with each keyword in its context. The calling sketch is either one of:

ptx [option ...] [file ...]
ptx -G [option ...] [input [output]]

The `-G' (or its equivalent: `--traditional') option disables all GNU extensions and revert to traditional mode, thus introducing some limitations, and changes several of the program's default option values. When `-G' is not specified, GNU extensions are always enabled. GNU extensions to ptx are documented wherever appropriate in this document. For the full list, see See section 7.5.5 The GNU extensions to ptx.

Individual options are explained in incoming sections.

When GNU extensions are enabled, there may be zero, one or several file after the options. If there is no file, the program reads the standard input. If there is one or several file, they give the name of input files which are all read in turn, as if all the input files were concatenated. However, there is a full contextual break between each file and, when automatic referencing is requested, file names and line numbers refer to individual text input files. In all cases, the program produces the permuted index onto the standard output.

When GNU extensions are not enabled, that is, when the program operates in traditional mode, there may be zero, one or two parameters besides the options. If there is no parameters, the program reads the standard input and produces the permuted index onto the standard output. If there is only one parameter, it names the text input to be read instead of the standard input. If two parameters are given, they give respectively the name of the input file to read and the name of the output file to produce. Be very careful to note that, in this case, the contents of file given by the second parameter is destroyed. This behaviour is dictated only by System V ptx compatibility, because GNU Standards discourage output parameters not introduced by an option.

Note that for any file named as the value of an option or as an input text file, a single dash - may be used, in which case standard input is assumed. However, it would not make sense to use this convention more than once per program invocation.

7.5.1 General options | Options which affect general program behaviour.
7.5.2 Charset selection | Underlying character set considerations.
7.5.3 Word selection and input processing | Input fields, contexts, and keyword selection.
7.5.4 Output formatting | Types of output format, and sizing the fields.
7.5.5 The GNU extensions to ptx

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.1 General options

`-C'
`--copyright'
Prints a short note about the Copyright and copying conditions, then exit without further processing.

`-G'
`--traditional'
As already explained, this option disables all GNU extensions to ptx and switch to traditional mode.

`--help'
Prints a short help on standard output, then exit without further processing.

`--version'
Prints the program verison on standard output, then exit without further processing.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.2 Charset selection

As it is setup now, the program assumes that the input file is coded using 8-bit ISO 8859-1 code, also known as Latin-1 character set, unless if it is compiled for MS-DOS, in which case it uses the character set of the IBM-PC. (GNU ptx is not known to work on smaller MS-DOS machines anymore.) Compared to 7-bit ASCII, the set of characters which are letters is then different, this fact alters the behaviour of regular expression matching. Thus, the default regular expression for a keyword allows foreign or diacriticized letters. Keyword sorting, however, is still crude; it obeys the underlying character set ordering quite blindly.

`-f'
`--ignore-case'
Fold lower case letters to upper case for sorting.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.3 Word selection and input processing

`-b file'
`--break-file=file'

This option provides an alternative (to `-W') method of describing which characters make up words. It introduces the name of a file which contains a list of characters which cannot be part of one word, this file is called the Break file. Any character which is not part of the Break file is a word constituent. If both options `-b' and `-W' are specified, then `-W' has precedence and `-b' is ignored.

When GNU extensions are enabled, the only way to avoid newline as a break character is to write all the break characters in the file with no newline at all, not even at the end of the file. When GNU extensions are disabled, spaces, tabs and newlines are always considered as break characters even if not included in the Break file.

`-i file'
`--ignore-file=file'

The file associated with this option contains a list of words which will never be taken as keywords in concordance output. It is called the Ignore file. The file contains exactly one word in each line; the end of line separation of words is not subject to the value of the `-S' option.

There is a default Ignore file used by ptx when this option is not specified, usually found in `/usr/local/lib/eign' if this has not been changed at installation time. If you want to deactivate the default Ignore file, specify /dev/null instead.

`-o file'
`--only-file=file'

The file associated with this option contains a list of words which will be retained in concordance output, any word not mentioned in this file is ignored. The file is called the Only file. The file contains exactly one word in each line; the end of line separation of words is not subject to the value of the `-S' option.

There is no default for the Only file. In the case there are both an Only file and an Ignore file, a word will be subject to be a keyword only if it is given in the Only file and not given in the Ignore file.

`-r'
`--references'

On each input line, the leading sequence of non white characters will be taken to be a reference that has the purpose of identifying this input line on the produced permuted index. For more information about reference production, see See section 7.5.4 Output formatting. Using this option changes the default value for option `-S'.

Using this option, the program does not try very hard to remove references from contexts in output, but it succeeds in doing so when the context ends exactly at the newline. If option `-r' is used with `-S' default value, or when GNU extensions are disabled, this condition is always met and references are completely excluded from the output contexts.

`-S regexp'
`--sentence-regexp=regexp'

This option selects which regular expression will describe the end of a line or the end of a sentence. In fact, there is other distinction between end of lines or end of sentences than the effect of this regular expression, and input line boundaries have no special significance outside this option. By default, when GNU extensions are enabled and if `-r' option is not used, end of sentences are used. In this case, the precise regex is imported from GNU emacs:

[.?!][]\"')}]*\\($\\|\t\\|  \\)[ \t\n]*

Whenever GNU extensions are disabled or if `-r' option is used, end of lines are used; in this case, the default regexp is just:

\n

Using an empty regexp is equivalent to completely disabling end of line or end of sentence recognition. In this case, the whole file is considered to be a single big line or sentence. The user might want to disallow all truncation flag generation as well, through option `-F ""'. See section `Syntax of Regular Expressions' in The GNU Emacs Manual.

When the keywords happen to be near the beginning of the input line or sentence, this often creates an unused area at the beginning of the output context line; when the keywords happen to be near the end of the input line or sentence, this often creates an unused area at the end of the output context line. The program tries to fill those unused areas by wrapping around context in them; the tail of the input line or sentence is used to fill the unused area on the left of the output line; the head of the input line or sentence is used to fill the unused area on the right of the output line.

As a matter of convenience to the user, many usual backslashed escape sequences, as found in the C language, are recognized and converted to the corresponding characters by ptx itself.

`-W regexp'
`--word-regexp=regexp'

This option selects which regular expression will describe each keyword. By default, if GNU extensions are enabled, a word is a sequence of letters; the regexp used is `\w+'. When GNU extensions are disabled, a word is by default anything which ends with a space, a tab or a newline; the regexp used is `[^ \t\n]+'.

An empty regexp is equivalent to not using this option, letting the default dive in. See section `Syntax of Regular Expressions' in The GNU Emacs Manual.

As a matter of convenience to the user, many usual backslashed escape sequences, as found in the C language, are recognized and converted to the corresponding characters by ptx itself.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.4 Output formatting

Output format is mainly controlled by `-O' and `-T' options, described in the table below. When neither `-O' nor `-T' is selected, and if GNU extensions are enabled, the program choose an output format suited for a dumb terminal. Each keyword occurrence is output to the center of one line, surrounded by its left and right contexts. Each field is properly justified, so the concordance output could readily be observed. As a special feature, if automatic references are selected by option `-A' and are output before the left context, that is, if option `-R' is not selected, then a colon is added after the reference; this nicely interfaces with GNU Emacs next-error processing. In this default output format, each white space character, like newline and tab, is merely changed to exactly one space, with no special attempt to compress consecutive spaces. This might change in the future. Except for those white space characters, every other character of the underlying set of 256 characters is transmitted verbatim.

Output format is further controlled by the following options.

`-g number'
`--gap-size=number'

Select the size of the minimum white gap between the fields on the output line.

`-w number'
`--width=number'

Select the output maximum width of each final line. If references are used, they are included or excluded from the output maximum width depending on the value of option `-R'. If this option is not selected, that is, when references are output before the left context, the output maximum width takes into account the maximum length of all references. If this options is selected, that is, when references are output after the right context, the output maximum width does not take into account the space taken by references, nor the gap that precedes them.

`-A'
`--auto-reference'

Select automatic references. Each input line will have an automatic reference made up of the file name and the line ordinal, with a single colon between them. However, the file name will be empty when standard input is being read. If both `-A' and `-r' are selected, then the input reference is still read and skipped, but the automatic reference is used at output time, overriding the input reference.

`-R'
`--right-side-refs'

In default output format, when option `-R' is not used, any reference produced by the effect of options `-r' or `-A' are given to the far right of output lines, after the right context. In default output format, when option `-R' is specified, references are rather given to the beginning of each output line, before the left context. For any other output format, option `-R' is almost ignored, except for the fact that the width of references is not taken into account in total output width given by `-w' whenever `-R' is selected.

This option is automatically selected whenever GNU extensions are disabled.

`-F string'
`--flac-truncation=string'

This option will request that any truncation in the output be reported using the string string. Most output fields theoretically extend towards the beginning or the end of the current line, or current sentence, as selected with option `-S'. But there is a maximum allowed output line width, changeable through option `-w', which is further divided into space for various output fields. When a field has to be truncated because cannot extend until the beginning or the end of the current line to fit in the, then a truncation occurs. By default, the string used is a single slash, as in `-F /'.

string may have more than one character, as in `-F ...'. Also, in the particular case string is empty (`-F ""'), truncation flagging is disabled, and no truncation marks are appended in this case.

As a matter of convenience to the user, many usual backslashed escape sequences, as found in the C language, are recognized and converted to the corresponding characters by ptx itself.

`-M string'
`--macro-name=string'

Select another string to be used instead of `xx', while generating output suitable for nroff, troff or TeX.

`-O'
`--format=roff'

Choose an output format suitable for nroff or troff processing. Each output line will look like:

.xx "tail" "before" "keyword_and_after" "head" "ref"

so it will be possible to write an `.xx' roff macro to take care of the output typesetting. This is the default output format when GNU extensions are disabled. Option `-M' might be used to change `xx' to another macro name.

In this output format, each non-graphical character, like newline and tab, is merely changed to exactly one space, with no special attempt to compress consecutive spaces. Each quote character: " is doubled so it will be correctly processed by nroff or troff.

`-T'
`--format=tex'

Choose an output format suitable for TeX processing. Each output line will look like:

\xx {tail}{before}{keyword}{after}{head}{ref}

so it will be possible to write a \xx definition to take care of the output typesetting. Note that when references are not being produced, that is, neither option `-A' nor option `-r' is selected, the last parameter of each \xx call is inhibited. Option `-M' might be used to change `xx' to another macro name.

In this output format, some special characters, like $, %, &, # and _ are automatically protected with a backslash. Curly brackets {, } are also protected with a backslash, but also enclosed in a pair of dollar signs to force mathematical mode. The backslash itself produces the sequence \backslash{}. Circumflex and tilde diacritics produce the sequence ^\{ } and ~\{ } respectively. Other diacriticized characters of the underlying character set produce an appropriate TeX sequence as far as possible. The other non-graphical characters, like newline and tab, and all others characters which are not part of ASCII, are merely changed to exactly one space, with no special attempt to compress consecutive spaces. Let me know how to improve this special character processing for TeX.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7.5.5 The GNU extensions to ptx

This version of ptx contains a few features which do not exist in System V ptx. These extra features are suppressed by using the `-G' command line option, unless overridden by other command line options. Some GNU extensions cannot be recovered by overriding, so the simple rule is to avoid `-G' if you care about GNU extensions. Here are the differences between this program and System V ptx.

  • This program can read many input files at once, it always writes the resulting concordance on standard output. On the other end, System V ptx reads only one file and produce the result on standard output or, if a second file parameter is given on the command, to that file.

    Having output parameters not introduced by options is a quite dangerous practice which GNU avoids as far as possible. So, for using ptx portably between GNU and System V, you should pay attention to always use it with a single input file, and always expect the result on standard output. You might also want to automatically configure in a `-G' option to ptx calls in products using ptx, if the configurator finds that the installed ptx accepts `-G'.

  • The only options available in System V ptx are options `-b', `-f', `-g', `-i', `-o', `-r', `-t' and `-w'. All other options are GNU extensions and are not repeated in this enumeration. Moreover, some options have a slightly different meaning when GNU extensions are enabled, as explained below.

  • By default, concordance output is not formatted for troff or nroff. It is rather formatted for a dumb terminal. troff or nroff output may still be selected through option `-O'.

  • Unless `-R' option is used, the maximum reference width is subtracted from the total output line width. With GNU extensions disabled, width of references is not taken into account in the output line width computations.

  • All 256 characters, even NULs, are always read and processed from input file with no adverse effect, even if GNU extensions are disabled. However, System V ptx does not accept 8-bit characters, a few control characters are rejected, and the tilde ~ is condemned.

  • Input line length is only limited by available memory, even if GNU extensions are disabled. However, System V ptx processes only the first 200 characters in each line.

  • The break (non-word) characters default to be every character except all letters of the underlying character set, diacriticized or not. When GNU extensions are disabled, the break characters default to space, tab and newline only.

  • The program makes better use of output line width. If GNU extensions are disabled, the program rather tries to imitate System V ptx, but still, there are some slight disposition glitches this program does not completely reproduce.

  • The user can specify both an Ignore file and an Only file. This is not allowed with System V ptx.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8. Operating on fields within a line

8.1 cut: Print selected parts of lines | Print selected parts of lines.
8.2 paste: Merge lines of files | Merge lines of files.
8.3 join: Join lines on a common field | Join lines on a common field.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.1 cut: Print selected parts of lines

cut writes to standard output selected parts of each line of each input file, or standard input if no files are given or for a file name of `-'. Synopsis:

cut [option]... [file]...

In the table which follows, the byte-list, character-list, and field-list are one or more numbers or ranges (two numbers separated by a dash) separated by commas. Bytes, characters, and fields are numbered from starting at 1. Incomplete ranges may be given: `-m' means `1-m'; `n-' means `n' through end of line or last field.

The program accepts the following options. Also see 2. Common options.

`-b byte-list'
`--bytes=byte-list'
Print only the bytes in positions listed in byte-list. Tabs and backspaces are treated like any other character; they take up 1 byte.

`-c character-list'
`--characters=character-list'
Print only characters in positions listed in character-list. The same as `-b' for now, but internationalization will change that. Tabs and backspaces are treated like any other character; they take up 1 character.

`-f field-list'
`--fields=field-list'
Print only the fields listed in field-list. Fields are separated by a TAB character by default.

`-d input_delim_byte'
`--delimiter=input_delim_byte'
For `-f', fields are separated in the input by the first character in input_delim_byte (default is TAB).

`-n'
Do not split multi-byte characters (no-op for now).

`-s'
`--only-delimited'
For `-f', do not print lines that do not contain the field separator character.

`--output-delimiter=output_delim_string'
For `-f', output fields are separated by output_delim_string The default is to use the input delimiter.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.2 paste: Merge lines of files

paste writes to standard output lines consisting of sequentially corresponding lines of each given file, separated by a TAB character. Standard input is used for a file name of `-' or if no input files are given.

Synopsis:

paste [option]... [file]...

The program accepts the following options. Also see 2. Common options.

`-s'
`--serial'
Paste the lines of one file at a time rather than one line from each file.

`-d delim-list'
`--delimiters delim-list'
Consecutively use the characters in delim-list instead of TAB to separate merged lines. When delim-list is exhausted, start again at its beginning.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

8.3 join: Join lines on a common field

join writes to standard output a line for each pair of input lines that have identical join fields. Synopsis:

join [option]... file1 file2

Either file1 or file2 (but not both) can be `-', meaning standard input. file1 and file2 should be already sorted in increasing textual order on the join fields, using the collating sequence specified by the LC_COLLATE locale. Unless the `-t' option is given, the input should be sorted ignoring blanks at the start of the join field, as in sort -b. If the `--ignore-case' option is given, lines should be sorted without regard to the case of characters in the join field, as in sort -f.

The defaults are: the join field is the first field in each line; fields in the input are separated by one or more blanks, with leading blanks on the line ignored; fields in the output are separated by a space; each output line consists of the join field, the remaining fields from file1, then the remaining fields from file2.

The program accepts the following options. Also see 2. Common options.

`-a file-number'
Print a line for each unpairable line in file file-number (either `1' or `2'), in addition to the normal output.

`-e string'
Replace those output fields that are missing in the input with string.

`-i'
`--ignore-case'
Ignore differences in case when comparing keys. With this option, the lines of the input files must be ordered in the same way. Use `sort -f' to produce this ordering.

`-1 field'
`-j1 field'
Join on field field (a positive integer) of file 1.

`-2 field'
`-j2 field'
Join on field field (a positive integer) of file 2.

`-j field'
Equivalent to `-1 field -2 field'.

`-o field-list...'
Construct each output line according to the format in field-list. Each element in field-list is either the single character `0' or has the form m.n where the file number, m, is `1' or `2' and n is a positive field number.

A field specification of `0' denotes the join field. In most cases, the functionality of the `0' field spec may be reproduced using the explicit m.n that corresponds to the join field. However, when printing unpairable lines (using either of the `-a' or `-v' options), there is no way to specify the join field using m.n in field-list if there are unpairable lines in both files. To give join that functionality, POSIX invented the `0' field specification notation.

The elements in field-list are separated by commas or blanks. Multiple field-list arguments can be given after a single `-o' option; the values of all lists given with `-o' are concatenated together. All output lines -- including those printed because of any -a or -v option -- are subject to the specified field-list.

`-t char'
Use character char as the input and output field separator.

`-v file-number'
Print a line for each unpairable line in file file-number (either `1' or `2'), instead of the normal output.

In addition, when GNU join is invoked with exactly one argument, options `--help' and `--version' are recognized. See section 2. Common options.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9. Operating on characters

This commands operate on individual characters.

9.1 tr: Translate, squeeze, and/or delete characters | Translate, squeeze, and/or delete characters.
9.2 expand: Convert tabs to spaces | Convert tabs to spaces.
9.3 unexpand: Convert spaces to tabs | Convert spaces to tabs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1 tr: Translate, squeeze, and/or delete characters

Synopsis:

tr [option]... set1 [set2]

tr copies standard input to standard output, performing one of the following operations:

  • translate, and optionally squeeze repeated characters in the result,
  • squeeze repeated characters,
  • delete characters,
  • delete characters, then squeeze repeated characters from the result.

The set1 and (if given) set2 arguments define ordered sets of characters, referred to below as set1 and set2. These sets are the characters of the input that tr operates on. The `--complement' (`-c') option replaces set1 with its complement (all of the characters that are not in set1).

9.1.1 Specifying sets of characters
9.1.2 Translating Changing one characters to another.
9.1.3 Squeezing repeats and deleting
9.1.4 Warning messages

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1.1 Specifying sets of characters

The format of the set1 and set2 arguments resembles the format of regular expressions; however, they are not regular expressions, only lists of characters. Most characters simply represent themselves in these strings, but the strings can contain the shorthands listed below, for convenience. Some of them can be used only in set1 or set2, as noted below.

Backslash escapes

A backslash followed by a character not listed below causes an error message.

`\a'
Control-G.
`\b'
Control-H.
`\f'
Control-L.
`\n'
Control-J.
`\r'
Control-M.
`\t'
Control-I.
`\v'
Control-K.
`\ooo'
The character with the value given by ooo, which is 1 to 3 octal digits,
`\\'
A backslash.

Ranges

The notation `m-n' expands to all of the characters from m through n, in ascending order. m should collate before n; if it doesn't, an error results. As an example, `0-9' is the same as `0123456789'. Although GNU tr does not support the System V syntax that uses square brackets to enclose ranges, translations specified in that format will still work as long as the brackets in string1 correspond to identical brackets in string2.

Repeated characters

The notation `[c*n]' in set2 expands to n copies of character c. Thus, `[y*6]' is the same as `yyyyyy'. The notation `[c*]' in string2 expands to as many copies of c as are needed to make set2 as long as set1. If n begins with `0', it is interpreted in octal, otherwise in decimal.

Character classes

The notation `[:class:]' expands to all of the characters in the (predefined) class class. The characters expand in no particular order, except for the upper and lower classes, which expand in ascending order. When the `--delete' (`-d') and `--squeeze-repeats' (`-s') options are both given, any character class can be used in set2. Otherwise, only the character classes lower and upper are accepted in set2, and then only if the corresponding character class (upper and lower, respectively) is specified in the same relative position in set1. Doing this specifies case conversion. The class names are given below; an error results when an invalid class name is given.

alnum
Letters and digits.
alpha
Letters.
blank
Horizontal whitespace.
cntrl
Control characters.
digit
Digits.
graph
Printable characters, not including space.
lower
Lowercase letters.
print
Printable characters, including space.
punct
Punctuation characters.
space
Horizontal or vertical whitespace.
upper
Uppercase letters.
xdigit
Hexadecimal digits.

Equivalence classes

The syntax `[=c=]' expands to all of the characters that are equivalent to c, in no particular order. Equivalence classes are a relatively recent invention intended to support non-English alphabets. But there seems to be no standard way to define them or determine their contents. Therefore, they are not fully implemented in GNU tr; each character's equivalence class consists only of that character, which is of no particular use.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1.2 Translating

tr performs translation when set1 and set2 are both given and the `--delete' (`-d') option is not given. tr translates each character of its input that is in set1 to the corresponding character in set2. Characters not in set1 are passed through unchanged. When a character appears more than once in set1 and the corresponding characters in set2 are not all the same, only the final one is used. For example, these two commands are equivalent:

tr aaa xyz
tr a z

A common use of tr is to convert lowercase characters to uppercase. This can be done in many ways. Here are three of them:

tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
tr a-z A-Z
tr '[:lower:]' '[:upper:]'

When tr is performing translation, set1 and set2 typically have the same length. If set1 is shorter than set2, the extra characters at the end of set2 are ignored.

On the other hand, making set1 longer than set2 is not portable; POSIX.2 says that the result is undefined. In this situation, BSD tr pads set2 to the length of set1 by repeating the last character of set2 as many times as necessary. System V tr truncates set1 to the length of set2.

By default, GNU tr handles this case like BSD tr. When the `--truncate-set1' (`-t') option is given, GNU tr handles this case like the System V tr instead. This option is ignored for operations other than translation.

Acting like System V tr in this case breaks the relatively common BSD idiom:

tr -cs A-Za-z0-9 '\012'

because it converts only zero bytes (the first element in the complement of set1), rather than all non-alphanumerics, to newlines.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1.3 Squeezing repeats and deleting

When given just the `--delete' (`-d') option, tr removes any input characters that are in set1.

When given just the `--squeeze-repeats' (`-s') option, tr replaces each input sequence of a repeated character that is in set1 with a single occurrence of that character.

When given both `--delete' and `--squeeze-repeats', tr first performs any deletions using set1, then squeezes repeats from any remaining characters using set2.

The `--squeeze-repeats' option may also be used when translating, in which case tr first performs translation, then squeezes repeats from any remaining characters using set2.

Here are some examples to illustrate various combinations of options:

  • Remove all zero bytes:

    tr -d '\000'

  • Put all words on lines by themselves. This converts all non-alphanumeric characters to newlines, then squeezes each string of repeated newlines into a single newline:

    tr -cs 'a-zA-Z0-9' '[\n*]'

  • Convert each sequence of repeated newlines to a single newline:

    tr -s '\n'

  • Find doubled occurrences of words in a document. For example, people often write "the the" with the duplicated words separated by a newline. The bourne shell script below works first by converting each sequence of punctuation and blank characters to a single newline. That puts each "word" on a line by itself. Next it maps all uppercase characters to lower case, and finally it runs uniq with the `-d' option to print out only the words that were adjacent duplicates.

    #!/bin/sh
cat "$@" \
  | tr -s '[:punct:][:blank:]' '\n' \
  | tr '[:upper:]' '[:lower:]' \
  | uniq -d

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.1.4 Warning messages

Setting the environment variable POSIXLY_CORRECT turns off the following warning and error messages, for strict compliance with POSIX.2. Otherwise, the following diagnostics are issued:

  1. When the `--delete' option is given but `--squeeze-repeats' is not, and set2 is given, GNU tr by default prints a usage message and exits, because set2 would not be used. The POSIX specification says that set2 must be ignored in this case. Silently ignoring arguments is a bad idea.

  2. When an ambiguous octal escape is given. For example, `\400' is actually `\40' followed by the digit `0', because the value 400 octal does not fit into a single byte.

GNU tr does not provide complete BSD or System V compatibility. For example, it is impossible to disable interpretation of the POSIX constructs `[:alpha:]', `[=c=]', and `[c*10]'. Also, GNU tr does not delete zero bytes automatically, unlike traditional Unix versions, which provide no way to preserve zero bytes.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.2 expand: Convert tabs to spaces

expand writes the contents of each given file, or standard input if none are given or for a file of `-', to standard output, with tab characters converted to the appropriate number of spaces. Synopsis:

expand [option]... [file]...

By default, expand converts all tabs to spaces. It preserves backspace characters in the output; they decrement the column count for tab calculations. The default action is equivalent to `-8' (set tabs every 8 columns).

The program accepts the following options. Also see 2. Common options.

`-tab1[,tab2]...'
`-t tab1[,tab2]...'
`--tabs=tab1[,tab2]...'
If only one tab stop is given, set the tabs tab1 spaces apart (default is 8). Otherwise, set the tabs at columns tab1, tab2, ... (numbered from 0), and replace any tabs beyond the last tabstop given with single spaces. If the tabstops are specified with the `-t' or `--tabs' option, they can be separated by blanks as well as by commas.

`-i'
`--initial'
Only convert initial tabs (those that precede all non-space or non-tab characters) on each line to spaces.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

9.3 unexpand: Convert spaces to tabs

unexpand writes the contents of each given file, or standard input if none are given or for a file of `-', to standard output, with strings of two or more space or tab characters converted to as many tabs as possible followed by as many spaces as are needed. Synopsis:

unexpand [option]... [file]...

By default, unexpand converts only initial spaces and tabs (those that precede all non space or tab characters) on each line. It preserves backspace characters in the output; they decrement the column count for tab calculations. By default, tabs are set at every 8th column.

The program accepts the following options. Also see 2. Common options.

`-tab1[,tab2]...'
`-t tab1[,tab2]...'
`--tabs=tab1[,tab2]...'
If only one tab stop is given, set the tabs tab1 spaces apart instead of the default 8. Otherwise, set the tabs at columns tab1, tab2, ... (numbered from 0), and leave spaces and tabs beyond the tabstops given unchanged. If the tabstops are specified with the `-t' or `--tabs' option, they can be separated by blanks as well as by commas. This option implies the `-a' option.

`-a'
`--all'
Convert all strings of two or more spaces or tabs, not just initial ones, to tabs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

10. Opening the software toolbox

This chapter originally appeared in Linux Journal, volume 1, number 2, in the What's GNU? column. It was written by Arnold Robbins.

Toolbox introduction
I/O redirection
The who command
The cut command
The sort command
The uniq command
Putting the tools together

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Toolbox introduction

This month's column is only peripherally related to the GNU Project, in that it describes a number of the GNU tools on your Linux system and how they might be used. What it's really about is the "Software Tools" philosophy of program development and usage.

The software tools philosophy was an important and integral concept in the initial design and development of Unix (of which Linux and GNU are essentially clones). Unfortunately, in the modern day press of Internetworking and flashy GUIs, it seems to have fallen by the wayside. This is a shame, since it provides a powerful mental model for solving many kinds of problems.

Many people carry a Swiss Army knife around in their pants pockets (or purse). A Swiss Army knife is a handy tool to have: it has several knife blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, and perhaps a number of other things on it. For the everyday, small miscellaneous jobs where you need a simple, general purpose tool, it's just the thing.

On the other hand, an experienced carpenter doesn't build a house using a Swiss Army knife. Instead, he has a toolbox chock full of specialized tools--a saw, a hammer, a screwdriver, a plane, and so on. And he knows exactly when and where to use each tool; you won't catch him hammering nails with the handle of his screwdriver.

The Unix developers at Bell Labs were all professional programmers and trained computer scientists. They had found that while a one-size-fits-all program might appeal to a user because there's only one program to use, in practice such programs are

  1. difficult to write,

  2. difficult to maintain and debug, and

  3. difficult to extend to meet new situations.

Instead, they felt that programs should be specialized tools. In short, each program "should do one thing well." No more and no less. Such programs are simpler to design, write, and get right--they only do one thing.

Furthermore, they found that with the right machinery for hooking programs together, that the whole was greater than the sum of the parts. By combining several special purpose programs, you could accomplish a specific task that none of the programs was designed for, and accomplish it much more quickly and easily than if you had to write a special purpose program. We will see some (classic) examples of this further on in the column. (An important additional point was that, if necessary, take a detour and build any software tools you may need first, if you don't already have something appropriate in the toolbox.)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

I/O redirection

Hopefully, you are familiar with the basics of I/O redirection in the shell, in particular the concepts of "standard input," "standard output," and "standard error". Briefly, "standard input" is a data source, where data comes from. A program should not need to either know or care if the data source is a disk file, a keyboard, a magnetic tape, or even a punched card reader. Similarly, "standard output" is a data sink, where data goes to. The program should neither know nor care where this might be. Programs that only read their standard input, do something to the data, and then send it on, are called "filters", by analogy to filters in a water pipeline.

With the Unix shell, it's very easy to set up data pipelines:

program_to_create_data | filter1 | .... | filterN > final.pretty.data

We start out by creating the raw data; each filter applies some successive transformation to the data, until by the time it comes out of the pipeline, it is in the desired form.

This is fine and good for standard input and standard output. Where does the standard error come in to play? Well, think about filter1 in the pipeline above. What happens if it encounters an error in the data it sees? If it writes an error message to standard output, it will just disappear down the pipeline into filter2's input, and the user will probably never see it. So programs need a place where they can send error messages so that the user will notice them. This is standard error, and it is usually connected to your console or window, even if you have redirected standard output of your program away from your screen.

For filter programs to work together, the format of the data has to be agreed upon. The most straightforward and easiest format to use is simply lines of text. Unix data files are generally just streams of bytes, with lines delimited by the ASCII LF (Line Feed) character, conventionally called a "newline" in the Unix literature. (This is '\n' if you're a C programmer.) This is the format used by all the traditional filtering programs. (Many earlier operating systems had elaborate facilities and special purpose programs for managing binary data. Unix has always shied away from such things, under the philosophy that it's easiest to simply be able to view and edit your data with a text editor.)

OK, enough introduction. Let's take a look at some of the tools, and then we'll see how to hook them together in interesting ways. In the following discussion, we will only present those command line options that interest us. As you should always do, double check your system documentation for the full story.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

The who command

The first program is the who command. By itself, it generates a list of the users who are currently logged in. Although I'm writing this on a single-user system, we'll pretend that several people are logged in:

$ who
arnold   console Jan 22 19:57
miriam   ttyp0   Jan 23 14:19(:0.0)
bill     ttyp1   Jan 21 09:32(:0.0)
arnold   ttyp2   Jan 23 20:48(:0.0)

Here, the `$' is the usual shell prompt, at which I typed who. There are three people logged in, and I am logged in twice. On traditional Unix systems, user names are never more than eight characters long. This little bit of trivia will be useful later. The output of who is nice, but the data is not all that exciting.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

The cut command

The next program we'll look at is the cut command. This program cuts out columns or fields of input data. For example, we can tell it to print just the login name and full name from the `/etc/passwd file'. The `/etc/passwd' file has seven fields, separated by colons:

arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/ksh

To get the first and fifth fields, we would use cut like this:

$ cut -d: -f1,5 /etc/passwd
root:Operator
...
arnold:Arnold D. Robbins
miriam:Miriam A. Robbins
...

With the `-c' option, cut will cut out specific characters (i.e., columns) in the input lines. This command looks like it might be useful for data filtering.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

The sort command

Next we'll look at the sort command. This is one of the most powerful commands on a Unix-style system; one that you will often find yourself using when setting up fancy data plumbing. The sort command reads and sorts each file named on the command line. It then merges the sorted data and writes it to standard output. It will read standard input if no files are given on the command line (thus making it into a filter). The sort is based on the character collating sequence or based on user-supplied ordering criteria.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

The uniq command

Finally (at least for now), we'll look at the uniq program. When sorting data, you will often end up with duplicate lines, lines that are identical. Usually, all you need is one instance of each line. This is where uniq comes in. The uniq program reads its standard input, which it expects to be sorted. It only prints out one copy of each duplicated line. It does have several options. Later on, we'll use the `-c' option, which prints each unique line, preceded by a count of the number of times that line occurred in the input.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Putting the tools together

Now, let's suppose this is a large BBS system with dozens of users logged in. The management wants the SysOp to write a program that will generate a sorted list of logged in users. Furthermore, even if a user is logged in multiple times, his or her name should only show up in the output once.

The SysOp could sit down with the system documentation and write a C program that did this. It would take perhaps a couple of hundred lines of code and about two hours to write it, test it, and debug it. However, knowing the software toolbox, the SysOp can instead start out by generating just a list of logged on users:

$ who | cut -c1-8
arnold
miriam
bill
arnold

Next, sort the list:

$ who | cut -c1-8 | sort
arnold
arnold
bill
miriam

Finally, run the sorted list through uniq, to weed out duplicates:

$ who | cut -c1-8 | sort | uniq
arnold
bill
miriam

The sort command actually has a `-u' option that does what uniq does. However, uniq has other uses for which one cannot substitute `sort -u'.

The SysOp puts this pipeline into a shell script, and makes it available for all the users on the system:

# cat > /usr/local/bin/listusers
who | cut -c1-8 | sort | uniq
^D
# chmod +x /usr/local/bin/listusers

There are four major points to note here. First, with just four programs, on one command line, the SysOp was able to save about two hours worth of work. Furthermore, the shell pipeline is just about as efficient as the C program would be, and it is much more efficient in terms of programmer time. People time is much more expensive than computer time, and in our modern "there's never enough time to do everything" society, saving two hours of programmer time is no mean feat.

Second, it is also important to emphasize that with the combination of the tools, it is possible to do a special purpose job never imagined by the authors of the individual programs.

Third, it is also valuable to build up your pipeline in stages, as we did here. This allows you to view the data at each stage in the pipeline, which helps you acquire the confidence that you are indeed using these tools correctly.

Finally, by bundling the pipeline in a shell script, other users can use your command, without having to remember the fancy plumbing you set up for them. In terms of how you run them, shell scripts and compiled programs are indistinguishable.

After the previous warm-up exercise, we'll look at two additional, more complicated pipelines. For them, we need to introduce two more tools.

The first is the tr command, which stands for "transliterate." The tr command works on a character-by-character basis, changing characters. Normally it is used for things like mapping upper case to lower case:

$ echo ThIs ExAmPlE HaS MIXED case! | tr '[A-Z]' '[a-z]'
this example has mixed case!

There are several options of interest:

`-c'
work on the complement of the listed characters, i.e., operations apply to characters not in the given set

`-d'
delete characters in the first set from the output

`-s'
squeeze repeated characters in the output into just one character.

We will be using all three options in a moment.

The other command we'll look at is comm. The comm command takes two sorted input files as input data, and prints out the files' lines in three columns. The output columns are the data lines unique to the first file, the data lines unique to the second file, and the data lines that are common to both. The `-1', `-2', and `-3' command line options omit the respective columns. (This is non-intuitive and takes a little getting used to.) For example:

$ cat f1
11111
22222
33333
44444
$ cat f2
00000
22222
33333
55555
$ comm f1 f2
        00000
11111
                22222
                33333
44444
        55555

The single dash as a filename tells comm to read standard input instead of a regular file.

Now we're ready to build a fancy pipeline. The first application is a word frequency counter. This helps an author determine if he or she is over-using certain words.

The first step is to change the case of all the letters in our input file to one case. "The" and "the" are the same word when doing counting.

$ tr '[A-Z]' '[a-z]' < whats.gnu | ...

The next step is to get rid of punctuation. Quoted words and unquoted words should be treated identically; it's easiest to just get the punctuation out of the way.

$ tr '[A-Z]' '[a-z]' < whats.gnu | tr -cd '[A-Za-z0-9_ \012]' | ...

The second tr command operates on the complement of the listed characters, which are all the letters, the digits, the underscore, and the blank. The `\012' represents the newline character; it has to be left alone. (The ASCII tab character should also be included for good measure in a production script.)

At this point, we have data consisting of words separated by blank space. The words only contain alphanumeric characters (and the underscore). The next step is break the data apart so that we have one word per line. This makes the counting operation much easier, as we will see shortly.

$ tr '[A-Z]' '[a-z]' < whats.gnu | tr -cd '[A-Za-z0-9_ \012]' |
> tr -s '[ ]' '\012' | ...

This command turns blanks into newlines. The `-s' option squeezes multiple newline characters in the output into just one. This helps us avoid blank lines. (The `>' is the shell's "secondary prompt." This is what the shell prints when it notices you haven't finished typing in all of a command.)

We now have data consisting of one word per line, no punctuation, all one case. We're ready to count each word:

$ tr '[A-Z]' '[a-z]' < whats.gnu | tr -cd '[A-Za-z0-9_ \012]' |
> tr -s '[ ]' '\012' | sort | uniq -c | ...

At this point, the data might look something like this:

  60 a
   2 able
   6 about
   1 above
   2 accomplish
   1 acquire
   1 actually
   2 additional

The output is sorted by word, not by count! What we want is the most frequently used words first. Fortunately, this is easy to accomplish, with the help of two more sort options:

`-n'
do a numeric sort, not a textual one

`-r'
reverse the order of the sort

The final pipeline looks like this:

$ tr '[A-Z]' '[a-z]' < whats.gnu | tr -cd '[A-Za-z0-9_ \012]' |
> tr -s '[ ]' '\012' | sort | uniq -c | sort -nr
 156 the
  60 a
  58 to
  51 of
  51 and
 ...

Whew! That's a lot to digest. Yet, the same principles apply. With six commands, on two lines (really one long one split for convenience), we've created a program that does something interesting and useful, in much less time than we could have written a C program to do the same thing.

A minor modification to the above pipeline can give us a simple spelling checker! To determine if you've spelled a word correctly, all you have to do is look it up in a dictionary. If it is not there, then chances are that your spelling is incorrect. So, we need a dictionary. If you have the Slackware Linux distribution, you have the file `/usr/lib/ispell/ispell.words', which is a sorted, 38,400 word dictionary.

Now, how to compare our file with the dictionary? As before, we generate a sorted list of words, one per line:

$ tr '[A-Z]' '[a-z]' < whats.gnu | tr -cd '[A-Za-z0-9_ \012]' |
> tr -s '[ ]' '\012' | sort -u | ...

Now, all we need is a list of words that are not in the dictionary. Here is where the comm command comes in.

$ tr '[A-Z]' '[a-z]' < whats.gnu | tr -cd '[A-Za-z0-9_ \012]' |
> tr -s '[ ]' '\012' | sort -u |
> comm -23 - /usr/lib/ispell/ispell.words

The `-2' and `-3' options eliminate lines that are only in the dictionary (the second file), and lines that are in both files. Lines only in the first file (standard input, our stream of words), are words that are not in the dictionary. These are likely candidates for spelling errors. This pipeline was the first cut at a production spelling checker on Unix.

There are some other tools that deserve brief mention.

grep
search files for text that matches a regular expression

egrep
like grep, but with more powerful regular expressions

wc
count lines, words, characters

tee
a T-fitting for data pipes, copies data to files and to standard output

sed
the stream editor, an advanced tool

awk
a data manipulation language, another advanced tool

The software tools philosophy also espoused the following bit of advice: "Let someone else do the hard part." This means, take something that gives you most of what you need, and then massage it the rest of the way until it's in the form that you want.

To summarize:

  1. Each program should do one thing well. No more, no less.

  2. Combining programs with appropriate plumbing leads to results where the whole is greater than the sum of the parts. It also leads to novel uses of programs that the authors might never have imagined.

  3. Programs should never print extraneous header or trailer data, since these could get sent on down a pipeline. (A point we didn't mention earlier.)

  4. Let someone else do the hard part.

  5. Know your toolbox! Use each program appropriately. If you don't have an appropriate tool, build one.

As of this writing, all the programs we've discussed are available via anonymous ftp from prep.ai.mit.edu as `/pub/gnu/textutils-1.9.tar.gz'.(1)

None of what I have presented in this column is new. The Software Tools philosophy was first introduced in the book Software Tools, by Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X). This book showed how to write and use software tools. It was written in 1976, using a preprocessor for FORTRAN named ratfor (RATional FORtran). At the time, C was not as ubiquitous as it is now; FORTRAN was. The last chapter presented a ratfor to FORTRAN processor, written in ratfor. ratfor looks an awful lot like C; if you know C, you won't have any problem following the code.

In 1981, the book was updated and made available as Software Tools in Pascal (Addison-Wesley, ISBN 0-201-10342-7). Both books remain in print, and are well worth reading if you're a programmer. They certainly made a major change in how I view programming.

Initially, the programs in both books were available (on 9-track tape) from Addison-Wesley. Unfortunately, this is no longer the case, although you might be able to find copies floating around the Internet. For a number of years, there was an active Software Tools Users Group, whose members had ported the original ratfor programs to essentially every computer system with a FORTRAN compiler. The popularity of the group waned in the middle '80s as Unix began to spread beyond universities.

With the current proliferation of GNU code and other clones of Unix programs, these programs now receive little attention; modern C versions are much more efficient and do more than these programs do. Nevertheless, as exposition of good programming style, and evangelism for a still-valuable philosophy, these books are unparalleled, and I recommend them highly.

Acknowledgment: I would like to express my gratitude to Brian Kernighan of Bell Labs, the original Software Toolsmith, for reviewing this column.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Index

Jump to: + - 1
A B C D E F G H I J K L M N O P R S T U V W X

 | Index Entry | Section
+ |  |
 | +count | 5.2 tail: Output the last part of files
 | +first_page[:last_page] | 4.2 pr: Paginate or columnate files for printing
 | +n | 7.2 uniq: Uniquify files
- |  |
 | --across | 4.2 pr: Paginate or columnate files for printing
 | --address-radix | 3.4 od: Write files in octal or other formats
 | --all | 9.3 unexpand: Convert spaces to tabs
 | --all-repeated | 7.2 uniq: Uniquify files
 | --before | 3.2 tac: Concatenate and write files in reverse
 | --binary | 3.1 cat: Concatenate and write files
 | --binary | 6.4 md5sum: Print or check message-digests
 | --body-numbering | 3.3 nl: Number lines and write files
 | --bytes | 4.3 fold: Wrap input lines to fit in specified width
 | --bytes | 5.1 head: Output the first part of files
 | --bytes | 5.2 tail: Output the last part of files
 | --bytes | 5.3 split: Split a file into fixed-size pieces
 | --bytes | 6.1 wc: Print byte, word, and line counts
 | --bytes | 8.1 cut: Print selected parts of lines
 | --characters | 8.1 cut: Print selected parts of lines
 | --chars | 6.1 wc: Print byte, word, and line counts
 | --check-chars | 7.2 uniq: Uniquify files
 | --columns | 4.2 pr: Paginate or columnate files for printing
 | --count | 7.2 uniq: Uniquify files
 | --crown-margin | 4.1 fmt: Reformat paragraph text
 | --delimiter | 8.1 cut: Print selected parts of lines
 | --delimiters | 8.2 paste: Merge lines of files
 | --digits | 5.4 csplit: Split a file into context-determined pieces
 | --double-space | 4.2 pr: Paginate or columnate files for printing
 | --elide-empty-files | 5.4 csplit: Split a file into context-determined pieces
 | --expand-tabs | 4.2 pr: Paginate or columnate files for printing
 | --fields | 8.1 cut: Print selected parts of lines
 | --first-line-number | 4.2 pr: Paginate or columnate files for printing
 | --follow | 5.2 tail: Output the last part of files
 | --footer-numbering | 3.3 nl: Number lines and write files
 | --form-feed | 4.2 pr: Paginate or columnate files for printing
 | --format | 3.4 od: Write files in octal or other formats
 | --header | 4.2 pr: Paginate or columnate files for printing
 | --header-numbering | 3.3 nl: Number lines and write files
 | --help | 2. Common options
 | --ignore-case | 7.2 uniq: Uniquify files
 | --ignore-case | 8.3 join: Join lines on a common field
 | --indent | 4.2 pr: Paginate or columnate files for printing
 | --initial | 9.2 expand: Convert tabs to spaces
 | --join-blank-lines | 3.3 nl: Number lines and write files
 | --join-lines | 4.2 pr: Paginate or columnate files for printing
 | --keep-files | 5.4 csplit: Split a file into context-determined pieces
 | --length | 4.2 pr: Paginate or columnate files for printing
 | --line-bytes | 5.3 split: Split a file into fixed-size pieces
 | --lines | 5.1 head: Output the first part of files
 | --lines | 5.2 tail: Output the last part of files
 | --lines | 5.3 split: Split a file into fixed-size pieces
 | --lines | 6.1 wc: Print byte, word, and line counts
 | --max-consecutive-size-changes | 5.2 tail: Output the last part of files
 | --max-line-length | 6.1 wc: Print byte, word, and line counts
 | --max-unchanged-stats | 5.2 tail: Output the last part of files
 | --merge | 4.2 pr: Paginate or columnate files for printing
 | --no-file-warnings | 4.2 pr: Paginate or columnate files for printing
 | --no-renumber | 3.3 nl: Number lines and write files
 | --number | 3.1 cat: Concatenate and write files
 | --number-format | 3.3 nl: Number lines and write files
 | --number-lines | 4.2 pr: Paginate or columnate files for printing
 | --number-nonblank | 3.1 cat: Concatenate and write files
 | --number-separator | 3.3 nl: Number lines and write files
 | --number-width | 3.3 nl: Number lines and write files
 | --omit-header | 4.2 pr: Paginate or columnate files for printing
 | --omit-pagination | 4.2 pr: Paginate or columnate files for printing
 | --only-delimited | 8.1 cut: Print selected parts of lines
 | --output-delimiter | 8.1 cut: Print selected parts of lines
 | --output-duplicates | 3.4 od: Write files in octal or other formats
 | --output-tabs | 4.2 pr: Paginate or columnate files for printing
 | --page-increment | 3.3 nl: Number lines and write files
 | --page_width | 4.2 pr: Paginate or columnate files for printing
 | --pages | 4.2 pr: Paginate or columnate files for printing
 | --pid | 5.2 tail: Output the last part of files
 | --prefix | 5.4 csplit: Split a file into context-determined pieces
 | --quiet | 5.1 head: Output the first part of files
 | --quiet | 5.2 tail: Output the last part of files
 | --quiet | 5.4 csplit: Split a file into context-determined pieces
 | --read-bytes | 3.4 od: Write files in octal or other formats
 | --regex | 3.2 tac: Concatenate and write files in reverse
 | --repeated | 7.2 uniq: Uniquify files
 | --retry | 5.2 tail: Output the last part of files
 | --section-delimiter | 3.3 nl: Number lines and write files
 | --sep-string | 4.2 pr: Paginate or columnate files for printing
 | --separator | 3.2 tac: Concatenate and write files in reverse
 | --separator | 4.2 pr: Paginate or columnate files for printing
 | --serial | 8.2 paste: Merge lines of files
 | --show-all | 3.1 cat: Concatenate and write files
 | --show-control-chars | 4.2 pr: Paginate or columnate files for printing
 | --show-ends | 3.1 cat: Concatenate and write files
 | --show-nonprinting | 3.1 cat: Concatenate and write files
 | --show-nonprinting | 4.2 pr: Paginate or columnate files for printing
 | --show-tabs | 3.1 cat: Concatenate and write files
 | --silent | 5.1 head: Output the first part of files
 | --silent | 5.2 tail: Output the last part of files
 | --silent | 5.4 csplit: Split a file into context-determined pieces
 | --skip-bytes | 3.4 od: Write files in octal or other formats
 | --skip-chars | 7.2 uniq: Uniquify files
 | --skip-fields | 7.2 uniq: Uniquify files
 | --sleep-interval | 5.2 tail: Output the last part of files
 | --spaces | 4.3 fold: Wrap input lines to fit in specified width
 | --split-only | 4.1 fmt: Reformat paragraph text
 | --squeeze-blank | 3.1 cat: Concatenate and write files
 | --starting-line-number | 3.3 nl: Number lines and write files
 | --status | 6.4 md5sum: Print or check message-digests
 | --strings | 3.4 od: Write files in octal or other formats
 | --suffix | 5.4 csplit: Split a file into context-determined pieces
 | --sysv | 6.2 sum: Print checksum and block counts
 | --tabs | 9.2 expand: Convert tabs to spaces
 | --tabs | 9.3 unexpand: Convert spaces to tabs
 | --tagged-paragraph | 4.1 fmt: Reformat paragraph text
 | --text | 6.4 md5sum: Print or check message-digests
 | --traditional | 3.4 od: Write files in octal or other formats
 | --uniform-spacing | 4.1 fmt: Reformat paragraph text
 | --unique | 7.2 uniq: Uniquify files
 | --verbose | 5.1 head: Output the first part of files
 | --verbose | 5.2 tail: Output the last part of files
 | --verbose | 5.3 split: Split a file into fixed-size pieces
 | --version | 2. Common options
 | --warn | 6.4 md5sum: Print or check message-digests
 | --width | 3.4 od: Write files in octal or other formats
 | --width | 4.1 fmt: Reformat paragraph text
 | --width | 4.2 pr: Paginate or columnate files for printing
 | --width | 4.3 fold: Wrap input lines to fit in specified width
 | --words | 6.1 wc: Print byte, word, and line counts
 | -1 | 7.3 comm: Compare two sorted files line by line
 | -1 | 8.3 join: Join lines on a common field
 | -2 | 7.3 comm: Compare two sorted files line by line
 | -2 | 8.3 join: Join lines on a common field
 | -3 | 7.3 comm: Compare two sorted files line by line
 | -A | 3.1 cat: Concatenate and write files
 | -a | 3.4 od: Write files in octal or other formats
 | -a | 4.2 pr: Paginate or columnate files for printing
 | -A | 3.4 od: Write files in octal or other formats
 | -a | 8.3 join: Join lines on a common field
 | -a | 9.3 unexpand: Convert spaces to tabs
 | -b | 3.1 cat: Concatenate and write files
 | -B | 3.1 cat: Concatenate and write files
 | -b | 3.2 tac: Concatenate and write files in reverse
 | -b | 3.3 nl: Number lines and write files
 | -b | 3.4 od: Write files in octal or other formats
 | -b | 4.3 fold: Wrap input lines to fit in specified width
 | -b | 5.3 split: Split a file into fixed-size pieces
 | -b | 5.4 csplit: Split a file into context-determined pieces
 | -b | 6.4 md5sum: Print or check message-digests
 | -b | 7.1 sort: Sort text files
 | -b | 8.1 cut: Print selected parts of lines
 | -c | 3.4 od: Write files in octal or other formats
 | -C | 5.3 split: Split a file into fixed-size pieces
 | -c | 4.1 fmt: Reformat paragraph text
 | -c | 4.2 pr: Paginate or columnate files for printing
 | -c | 5.1 head: Output the first part of files
 | -c | 5.2 tail: Output the last part of files
 | -c | 6.1 wc: Print byte, word, and line counts
 | -c | 7.1 sort: Sort text files
 | -c | 7.2 uniq: Uniquify files
 | -c | 8.1 cut: Print selected parts of lines
 | -column | 4.2 pr: Paginate or columnate files for printing
 | -count | 5.1 head: Output the first part of files
 | -count | 5.2 tail: Output the last part of files
 | -d | 3.3 nl: Number lines and write files
 | -D | 7.2 uniq: Uniquify files
 | -d | 3.4 od: Write files in octal or other formats
 | -d | 4.2 pr: Paginate or columnate files for printing
 | -d | 7.1 sort: Sort text files
 | -d | 7.2 uniq: Uniquify files
 | -d | 8.1 cut: Print selected parts of lines
 | -d | 8.2 paste: Merge lines of files
 | -e | 3.1 cat: Concatenate and write files
 | -E | 3.1 cat: Concatenate and write files
 | -e | 4.2 pr: Paginate or columnate files for printing
 | -e | 8.3 join: Join lines on a common field
 | -f | 3.3 nl: Number lines and write files
 | -F | 4.2 pr: Paginate or columnate files for printing
 | -f | 3.4 od: Write files in octal or other formats
 | -f | 4.2 pr: Paginate or columnate files for printing
 | -f | 5.2 tail: Output the last part of files
 | -f | 5.4 csplit: Split a file into context-determined pieces
 | -f | 7.1 sort: Sort text files
 | -f | 7.2 uniq: Uniquify files
 | -f | 8.1 cut: Print selected parts of lines
 | -g | 7.1 sort: Sort text files
 | -h | 3.3 nl: Number lines and write files
 | -h | 3.4 od: Write files in octal or other formats
 | -h | 4.2 pr: Paginate or columnate files for printing
 | -i | 3.3 nl: Number lines and write files
 | -i | 3.4 od: Write files in octal or other formats
 | -i | 4.2 pr: Paginate or columnate files for printing
 | -i | 7.1 sort: Sort text files
 | -i | 7.2 uniq: Uniquify files
 | -i | 8.3 join: Join lines on a common field
 | -i | 9.2 expand: Convert tabs to spaces
 | -J | 4.2 pr: Paginate or columnate files for printing
 | -j | 3.4 od: Write files in octal or other formats
 | -j1 | 8.3 join: Join lines on a common field
 | -j2 | 8.3 join: Join lines on a common field
 | -k | 5.4 csplit: Split a file into context-determined pieces
 | -k | 7.1 sort: Sort text files
 | -l | 3.3 nl: Number lines and write files
 | -L | 6.1 wc: Print byte, word, and line counts
 | -l | 3.4 od: Write files in octal or other formats
 | -l | 4.2 pr: Paginate or columnate files for printing
 | -l | 5.3 split: Split a file into fixed-size pieces
 | -l | 6.1 wc: Print byte, word, and line counts
 | -m | 4.2 pr: Paginate or columnate files for printing
 | -M | 7.1 sort: Sort text files
 | -m | 7.1 sort: Sort text files
 | -n | 3.1 cat: Concatenate and write files
 | -N | 3.4 od: Write files in octal or other formats
 | -N | 4.2 pr: Paginate or columnate files for printing
 | -n | 3.3 nl: Number lines and write files
 | -n | 4.2 pr: Paginate or columnate files for printing
 | -n | 5.1 head: Output the first part of files
 | -n | 5.2 tail: Output the last part of files
 | -n | 5.4 csplit: Split a file into context-determined pieces
 | -n | 7.1 sort: Sort text files
 | -n | 7.2 uniq: Uniquify files
 | -n | 8.1 cut: Print selected parts of lines
 | -o | 3.4 od: Write files in octal or other formats
 | -o | 4.2 pr: Paginate or columnate files for printing
 | -o | 7.1 sort: Sort text files
 | -p | 3.3 nl: Number lines and write files
 | -q | 5.1 head: Output the first part of files
 | -q | 5.2 tail: Output the last part of files
 | -q | 5.4 csplit: Split a file into context-determined pieces
 | -r | 3.2 tac: Concatenate and write files in reverse
 | -r | 4.2 pr: Paginate or columnate files for printing
 | -r | 6.2 sum: Print checksum and block counts
 | -r | 7.1 sort: Sort text files
 | -S | 4.2 pr: Paginate or columnate files for printing
 | -s | 3.1 cat: Concatenate and write files
 | -s | 3.2 tac: Concatenate and write files in reverse
 | -s | 3.3 nl: Number lines and write files
 | -s | 3.4 od: Write files in octal or other formats
 | -s | 4.1 fmt: Reformat paragraph text
 | -s | 4.2 pr: Paginate or columnate files for printing
 | -s | 4.3 fold: Wrap input lines to fit in specified width
 | -s | 5.4 csplit: Split a file into context-determined pieces
 | -s | 6.2 sum: Print checksum and block counts
 | -s | 7.2 uniq: Uniquify files
 | -s | 8.1 cut: Print selected parts of lines
 | -s | 8.2 paste: Merge lines of files
 | -t | 3.1 cat: Concatenate and write files
 | -T | 3.1 cat: Concatenate and write files
 | -T | 4.2 pr: Paginate or columnate files for printing
 | -t | 3.4 od: Write files in octal or other formats
 | -t | 4.1 fmt: Reformat paragraph text
 | -t | 4.2 pr: Paginate or columnate files for printing
 | -t | 6.4 md5sum: Print or check message-digests
 | -t | 7.1 sort: Sort text files
 | -t | 9.2 expand: Convert tabs to spaces
 | -t | 9.3 unexpand: Convert spaces to tabs
 | -tab | 9.2 expand: Convert tabs to spaces
 | -tab | 9.3 unexpand: Convert spaces to tabs
 | -u | 3.1 cat: Concatenate and write files
 | -u | 4.1 fmt: Reformat paragraph text
 | -u | 7.1 sort: Sort text files
 | -u | 7.2 uniq: Uniquify files
 | -v | 3.1 cat: Concatenate and write files
 | -v | 3.3 nl: Number lines and write files
 | -v | 3.4 od: Write files in octal or other formats
 | -v | 4.2 pr: Paginate or columnate files for printing
 | -v | 5.1 head: Output the first part of files
 | -v | 5.2 tail: Output the last part of files
 | -W | 4.2 pr: Paginate or columnate files for printing
 | -w | 3.3 nl: Number lines and write files
 | -w | 3.4 od: Write files in octal or other formats
 | -w | 4.1 fmt: Reformat paragraph text
 | -w | 4.2 pr: Paginate or columnate files for printing
 | -w | 4.3 fold: Wrap input lines to fit in specified width
 | -w | 6.1 wc: Print byte, word, and line counts
 | -w | 6.4 md5sum: Print or check message-digests
 | -w | 7.2 uniq: Uniquify files
 | -width | 4.1 fmt: Reformat paragraph text
 | -x | 3.4 od: Write files in octal or other formats
 | -z | 5.4 csplit: Split a file into context-determined pieces
 | -z | 7.1 sort: Sort text files
1 |  |
 | 128-bit checksum | 6.4 md5sum: Print or check message-digests
 | 16-bit checksum | 6.2 sum: Print checksum and block counts
A |  |
 | across columns | 4.2 pr: Paginate or columnate files for printing
 | all duplicate lines, outputting | 7.2 uniq: Uniquify files
 | alnum | 9.1.1 Specifying sets of characters
 | alpha | 9.1.1 Specifying sets of characters
 | ASCII dump of files | 3.4 od: Write files in octal or other formats
B |  |
 | backslash escapes | 9.1.1 Specifying sets of characters
 | binary and text I/O in cat | 3.1 cat: Concatenate and write files
 | binary input files | 6.4 md5sum: Print or check message-digests
 | blank | 9.1.1 Specifying sets of characters
 | blank lines, numbering | 3.3 nl: Number lines and write files
 | blanks, ignoring leading | 7.1 sort: Sort text files
 | body, numbering | 3.3 nl: Number lines and write files
 | BSD sum | 6.2 sum: Print checksum and block counts
 | BSD tail | 5.2 tail: Output the last part of files
 | bugs, reporting | 1. Introduction
 | byte count | 6.1 wc: Print byte, word, and line counts
C |  |
 | case folding | 7.1 sort: Sort text files
 | cat | 3.1 cat: Concatenate and write files
 | characters classes | 9.1.1 Specifying sets of characters
 | checking for sortedness | 7.1 sort: Sort text files
 | checksum, 128-bit | 6.4 md5sum: Print or check message-digests
 | checksum, 16-bit | 6.2 sum: Print checksum and block counts
 | cksum | 6.3 cksum: Print CRC checksum and byte counts
 | cntrl | 9.1.1 Specifying sets of characters
 | comm | 7.3 comm: Compare two sorted files line by line
 | common field, joining on | 8.3 join: Join lines on a common field
 | common lines | 7.3 comm: Compare two sorted files line by line
 | common options | 2. Common options
 | comparing sorted files | 7.3 comm: Compare two sorted files line by line
 | concatenate and write files | 3.1 cat: Concatenate and write files
 | context splitting | 5.4 csplit: Split a file into context-determined pieces
 | converting tabs to spaces | 9.2 expand: Convert tabs to spaces
 | copying files | 3.1 cat: Concatenate and write files
 | CRC checksum | 6.3 cksum: Print CRC checksum and byte counts
 | crown margin | 4.1 fmt: Reformat paragraph text
 | csplit | 5.4 csplit: Split a file into context-determined pieces
 | cut | 8.1 cut: Print selected parts of lines
 | cyclic redundancy check | 6.3 cksum: Print CRC checksum and byte counts
D |  |
 | deleting characters | 9.1.3 Squeezing repeats and deleting
 | descriptor follow option | 5.2 tail: Output the last part of files
 | differing lines | 7.3 comm: Compare two sorted files line by line
 | digit | 9.1.1 Specifying sets of characters
 | double spacing | 4.2 pr: Paginate or columnate files for printing
 | down columns | 4.2 pr: Paginate or columnate files for printing
 | duplicate lines, outputting | 7.2 uniq: Uniquify files
E |  |
 | empty lines, numbering | 3.3 nl: Number lines and write files
 | entire files, output of | 3. Output of entire files
 | equivalence classes | 9.1.1 Specifying sets of characters
 | expand | 9.2 expand: Convert tabs to spaces
F |  |
 | field separator character | 7.1 sort: Sort text files
 | file contents, dumping unambiguously | 3.4 od: Write files in octal or other formats
 | file offset radix | 3.4 od: Write files in octal or other formats
 | fingerprint, 128-bit | 6.4 md5sum: Print or check message-digests
 | first part of files, outputting | 5.1 head: Output the first part of files
 | fmt | 4.1 fmt: Reformat paragraph text
 | fold | 4.3 fold: Wrap input lines to fit in specified width
 | folding long input lines | 4.3 fold: Wrap input lines to fit in specified width
 | footers, numbering | 3.3 nl: Number lines and write files
 | formatting file contents | 4. Formatting file contents
G |  |
 | general numeric sort | 7.1 sort: Sort text files
 | graph | 9.1.1 Specifying sets of characters
 | growing files | 5.2 tail: Output the last part of files
H |  |
 | head | 5.1 head: Output the first part of files
 | headers, numbering | 3.3 nl: Number lines and write files
 | help, online | 2. Common options
 | hex dump of files | 3.4 od: Write files in octal or other formats
I |  |
 | indenting lines | 4.2 pr: Paginate or columnate files for printing
 | initial part of files, outputting | 5.1 head: Output the first part of files
 | initial tabs, converting | 9.2 expand: Convert tabs to spaces
 | input tabs | 4.2 pr: Paginate or columnate files for printing
 | introduction | 1. Introduction
J |  |
 | join | 8.3 join: Join lines on a common field
K |  |
 | Knuth, Donald E. | 4.1 fmt: Reformat paragraph text
L |  |
 | last part of files, outputting | 5.2 tail: Output the last part of files
 | LC_COLLATE | 7.1 sort: Sort text files
 | LC_COLLATE | 7.3 comm: Compare two sorted files line by line
 | LC_COLLATE | 8.3 join: Join lines on a common field
 | LC_CTYPE | 7.1 sort: Sort text files
 | LC_NUMERIC | 7.1 sort: Sort text files
 | LC_TIME | 7.1 sort: Sort text files
 | left margin | 4.2 pr: Paginate or columnate files for printing
 | line count | 6.1 wc: Print byte, word, and line counts
 | line numbering | 3.3 nl: Number lines and write files
 | line-breaking | 4.1 fmt: Reformat paragraph text
 | line-by-line comparison | 7.3 comm: Compare two sorted files line by line
 | ln format for nl | 3.3 nl: Number lines and write files
 | logical pages, numbering on | 3.3 nl: Number lines and write files
 | lower | 9.1.1 Specifying sets of characters
M |  |
 | md5sum | 6.4 md5sum: Print or check message-digests
 | merging files | 8.2 paste: Merge lines of files
 | merging files in parallel | 4.2 pr: Paginate or columnate files for printing
 | merging sorted files | 7.1 sort: Sort text files
 | message-digest, 128-bit | 6.4 md5sum: Print or check message-digests
 | months, sorting by | 7.1 sort: Sort text files
 | multicolumn output, generating | 4.2 pr: Paginate or columnate files for printing
N |  |
 | name follow option | 5.2 tail: Output the last part of files
 | nl | 3.3 nl: Number lines and write files
 | numbering lines | 3.3 nl: Number lines and write files
 | numeric sort | 7.1 sort: Sort text files
O |  |
 | octal dump of files | 3.4 od: Write files in octal or other formats
 | od | 3.4 od: Write files in octal or other formats
 | operating on characters | 9. Operating on characters
 | operating on sorted files | 7. Operating on sorted files
 | output file name prefix | 5.3 split: Split a file into fixed-size pieces
 | output file name prefix | 5.4 csplit: Split a file into context-determined pieces
 | output file name suffix | 5.4 csplit: Split a file into context-determined pieces
 | output of entire files | 3. Output of entire files
 | output of parts of files | 5. Output of parts of files
 | output tabs | 4.2 pr: Paginate or columnate files for printing
 | overwriting of input, allowed | 7.1 sort: Sort text files
P |  |
 | paragraphs, reformatting | 4.1 fmt: Reformat paragraph text
 | parts of files, output of | 5. Output of parts of files
 | paste | 8.2 paste: Merge lines of files
 | phone directory order | 7.1 sort: Sort text files
 | pieces, splitting a file into | 5.3 split: Split a file into fixed-size pieces
 | Plass, Michael F. | 4.1 fmt: Reformat paragraph text
 | POSIX.2 | 1. Introduction
 | POSIXLY_CORRECT | 9.1.4 Warning messages
 | pr | 4.2 pr: Paginate or columnate files for printing
 | print | 9.1.1 Specifying sets of characters
 | printing, preparing files for | 4.2 pr: Paginate or columnate files for printing
 | ptx | 7.5 ptx: Produce permuted indexes
 | punct | 9.1.1 Specifying sets of characters
R |  |
 | radix for file offsets | 3.4 od: Write files in octal or other formats
 | ranges | 9.1.1 Specifying sets of characters
 | reformatting paragraph text | 4.1 fmt: Reformat paragraph text
 | repeated characters | 9.1.1 Specifying sets of characters
 | reverse sorting | 7.1 sort: Sort text files
 | reversing files | 3.2 tac: Concatenate and write files in reverse
 | rn format for nl | 3.3 nl: Number lines and write files
 | rz format for nl | 3.3 nl: Number lines and write files
S |  |
 | screen columns | 4.3 fold: Wrap input lines to fit in specified width
 | section delimiters of pages | 3.3 nl: Number lines and write files
 | sentences and line-breaking | 4.1 fmt: Reformat paragraph text
 | sort | 7.1 sort: Sort text files
 | sort field | 7.1 sort: Sort text files
 | sort zero-terminated lines | 7.1 sort: Sort text files
 | sorted files, operations on | 7. Operating on sorted files
 | sorting files | 7.1 sort: Sort text files
 | space | 9.1.1 Specifying sets of characters
 | specifying sets of characters | 9.1.1 Specifying sets of characters
 | split | 5.3 split: Split a file into fixed-size pieces
 | splitting a file into pieces | 5.3 split: Split a file into fixed-size pieces
 | splitting a file into pieces by context | 5.4 csplit: Split a file into context-determined pieces
 | squeezing blank lines | 3.1 cat: Concatenate and write files
 | squeezing repeat characters | 9.1.3 Squeezing repeats and deleting
 | string constants, outputting | 3.4 od: Write files in octal or other formats
 | sum | 6.2 sum: Print checksum and block counts
 | summarizing files | 6. Summarizing files
 | System V sum | 6.2 sum: Print checksum and block counts
T |  |
 | tabs to spaces, converting | 9.2 expand: Convert tabs to spaces
 | tabstops, setting | 9.2 expand: Convert tabs to spaces
 | tac | 3.2 tac: Concatenate and write files in reverse
 | tagged paragraphs | 4.1 fmt: Reformat paragraph text
 | tail | 5.2 tail: Output the last part of files
 | telephone directory order | 7.1 sort: Sort text files
 | text input files | 6.4 md5sum: Print or check message-digests
 | text utilities |
 | text, reformatting | 4.1 fmt: Reformat paragraph text
 | TMPDIR | 7.1 sort: Sort text files
 | topological sort | 7.4 tsort: Topological sort
 | total counts | 6.1 wc: Print byte, word, and line counts
 | tr | 9.1 tr: Translate, squeeze, and/or delete characters
 | translating characters | 9.1.2 Translating
 | tsort | 7.4 tsort: Topological sort
 | type size | 3.4 od: Write files in octal or other formats
U |  |
 | unexpand | 9.3 unexpand: Convert spaces to tabs
 | uniq | 7.2 uniq: Uniquify files
 | unique lines, outputting | 7.2 uniq: Uniquify files
 | uniquify files | 7.2 uniq: Uniquify files
 | uniquifying output | 7.1 sort: Sort text files
 | unprintable characters, ignoring | 7.1 sort: Sort text files
 | upper | 9.1.1 Specifying sets of characters
 | utilities for text handling |
V |  |
 | verifying MD5 checksums | 6.4 md5sum: Print or check message-digests
 | verifying MD5 checksums | 6.4 md5sum: Print or check message-digests
 | version number, finding | 2. Common options
W |  |
 | wc | 6.1 wc: Print byte, word, and line counts
 | word count | 6.1 wc: Print byte, word, and line counts
 | wrapping long input lines | 4.3 fold: Wrap input lines to fit in specified width
X |  |
 | xdigit | 9.1.1 Specifying sets of characters

Jump to: + - 1
A B C D E F G H I J K L M N O P R S T U V W X

[Top] [Contents] [Index] [ ? ]

Footnotes

(1)

Version 1.9 was current when this column was written. Check the nearest GNU archive for the current version. The main GNU FTP site is now ftp.gnu.org.

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Introduction
    2. Common options
    3. Output of entire files
      3.1 cat: Concatenate and write files
      3.2 tac: Concatenate and write files in reverse
      3.3 nl: Number lines and write files
      3.4 od: Write files in octal or other formats
    4. Formatting file contents
      4.1 fmt: Reformat paragraph text
      4.2 pr: Paginate or columnate files for printing
      4.3 fold: Wrap input lines to fit in specified width
    5. Output of parts of files
      5.1 head: Output the first part of files
      5.2 tail: Output the last part of files
      5.3 split: Split a file into fixed-size pieces
      5.4 csplit: Split a file into context-determined pieces
    6. Summarizing files
      6.1 wc: Print byte, word, and line counts
      6.2 sum: Print checksum and block counts
      6.3 cksum: Print CRC checksum and byte counts
      6.4 md5sum: Print or check message-digests
    7. Operating on sorted files
      7.1 sort: Sort text files
      7.2 uniq: Uniquify files
      7.3 comm: Compare two sorted files line by line
      7.4 tsort: Topological sort
      7.5 ptx: Produce permuted indexes
        7.5.1 General options
        7.5.2 Charset selection
        7.5.3 Word selection and input processing
        7.5.4 Output formatting
        7.5.5 The GNU extensions to ptx
    8. Operating on fields within a line
      8.1 cut: Print selected parts of lines
      8.2 paste: Merge lines of files
      8.3 join: Join lines on a common field
    9. Operating on characters
      9.1 tr: Translate, squeeze, and/or delete characters
        9.1.1 Specifying sets of characters
        9.1.2 Translating
        9.1.3 Squeezing repeats and deleting
        9.1.4 Warning messages
      9.2 expand: Convert tabs to spaces
      9.3 unexpand: Convert spaces to tabs
    10. Opening the software toolbox
      Toolbox introduction
      I/O redirection
      The who command
      The cut command
      The sort command
      The uniq command
      Putting the tools together
    Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Introduction
2. Common options
3. Output of entire files
4. Formatting file contents
5. Output of parts of files
6. Summarizing files
7. Operating on sorted files
8. Operating on fields within a line
9. Operating on characters
10. Opening the software toolbox
Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated by Paul Visscher on December, 28 2000 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated by Paul Visscher on December, 28 2000 using texi2html


Portable Terminal Control From Scripts

tput and tabs

Edition 2.0, for version 2.0

December 1995

by David MacKenzie and Junio Hamano

Table of Contents

  • tput: Portable Terminal Control
    • Using tput
    • Output and Exit Status
    • Yet More Examples
    • Capabilities
      • Boolean Capabilities
      • Numeric Capabilities
      • String Capabilities
    • Error Messages
  • tabs: Setting Terminal Tabs
    • Options
    • Tab Specification
    • Canned tab specifications
    • Examples

tput: Portable Terminal Control

The tput command allows shell scripts to do things like clear the screen, underline text, and center text no matter how wide the screen is. To do these things, it translates the terminal-independent name of a terminal capability into its actual value for the terminal type being used.

tput takes as an argument the name of a Unix System V terminfo capability, which it translates into the equivalent termcap capability name (see section Capabilities, for a list of the equivalencies). Terminfo is a database that is similar to termcap but which has different capability names and is stored in a different format. The GNU tput command takes a terminfo name as an argument to make it compatible with the Unix System V tput command.

There are three types of terminfo (and termcap) capabilities: string, Boolean, and numeric. String capabilities either cause a special effect on the terminal when they are displayed or are the value sent by a special key on the terminal (the latter type are probably of no use in shell scripts). Numeric and Boolean capabilities give information about the terminal such as how many columns wide it is or whether whether it has a meta key. See section Output and Exit Status, for more detailed information on the three types of capabilities.

The format of the tput command is illustrated below.

tput [options] capability [parameter ...]
tput [options] longname
tput [options] init
tput [options] reset

GNU tput takes the following options:

[-T terminal-type] [--terminal=terminal-type]
[-t] [--termcap]
[-S] [--standard-input]
[-V] [--version]

Here is an example of how to clear the terminal screen using tput:

tput clear

Using tput

The format of the tput command is illustrated below.

tput [options] capability [parameter ...]
tput [options] longname
tput [options] init
tput [options] reset

GNU tput takes the following options:

[-T terminal-type] [--terminal=terminal-type]
[-t] [--termcap]
[-S] [--standard-input]
[-V] [--version]

Some string capabilities accept parameters, such as the number of lines to delete or the column to move to. These parameters are specified on the command line following the capability name. They are always numbers.

`-T termtype'
`--terminal=termtype'
This option indicates the type of terminal. By default, this value is taken from the `TERM' environment variable.
`-t'
`--termcap'
GNU tput by default accepts termcap name if the capability a user specifies is not a terminfo name. This option tells tput not to try terminfo names and look up only termcap names.
`-S'
`--standard-input'
This option tells tput to read a sequence of capabilities and parameters from the standard input. Only string capabilities can be used in this mode.
`-V'
`--version'
This option displays the version of tput.

When `longname' is specified, tput displays the long descriptive name for the terminal type.

When `init' is specified, tput sends the initialization strings for the terminal. If the terminal's tab width is other than 8, and it cannot be reset, the tab expansion in the tty driver is turned on. Otherwise, tab width is reset to 8 and the tab expansion is turned off.

When `reset' is specified, tput sends the reset strings for the terminal and then follows the same initialization sequence as tput `init'.

Below are some example uses of tput. See section Capabilities, for a complete list of the functions that tput can cause terminals to perform. Note that not all terminals can perform any given function. See section Yet More Examples, for some more complex samples of tput use.

The following command moves the cursor to row 10, column 30 of the screen:

tput cup 10 30

The following command makes the cursor invisible:

tput civis

The following command makes the cursor visible again:

tput cnorm

The following command deletes 10 lines below and including the one on which the cursor is positioned:

tput dl 10

Output and Exit Status

The tput command produces different kinds of output for each of the three types of terminal capabilities: string, numeric, and Boolean.

If the terminfo capability given on the command line is a string capability, tput displays its value and exits with a status of 0. If the capability is not defined for the terminal type being used, tput produces no output and exits with a status of 1.

If the capability is a numeric capability, tput displays its value (an integer). If the capability is not defined for the terminal type being used, tput displays the value `-1'. The exit status is always 0 for numeric capabilities, unless an error occurs (see section Error Messages for a complete list of the possible exit status values).

If the capability is a Boolean capability, tput produces no output and exits with status 0 if the capability is defined for the terminal type being used, or status 1 if the capability is not defined. See section `Definitions of the Terminal Capabilities' in Termcap, for a more detailed description of termcap capabilities.

The values of numeric capabilities should be saved into shell variables so they can be used later without having to run tput again. Here is how it can be done:

For the Bourne, Bourne-again, and Korn shells:

To set an environment variable: COLUMNS=`tput cols` export COLUMNS

To set a local variable: tabwidth=`tput it`

For the C shell:

To set an environment variable: setenv COLUMNS `tput cols`

To set a local variable: set tabwidth = `tput it`

The values of string capabilities can be saved in shell variables in the same way, then displayed later using the echo command. Since echo is built into most shells, it runs more quickly than tput does. However, using echo instead of tput to display string values can cause problems for capabilities that use padding, because null padding characters cannot be passed as arguments to commands, including echo.

Yet More Examples

Here are some more advanced examples of using tput; most involve some shell programming. Because the C shell's flow control (decision making) constructs differ from those of the other shells, these examples do not work under the C shell.

The following sequence of commands prints `I am infalible' and then crosses it out on terminals that can overstrike, and prints `I am on strike' on terminals that cannot.

if tput os; then
    echo 'I am infalible\r- -- ---------'
else
    echo 'I am on strike'
fi

The following example is a shell script that centers a line of text given as command line arguments. An alternative approach would be to have tput send the `rep' terminfo capability to print the multiple spaces instead of using the while loop.

COLUMNS=`tput cols` export COLUMNS # Get screen width.
echo "$@" | awk '
{ spaces = ('$COLUMNS' - length) / 2
  while (spaces-- > 0) printf (" ")
  print
}'

The following commands cause the terminal to save the current cursor position, print `Hello, World' centered in the screen in reverse video, then return to the original cursor position.

COLUMNS=`tput cols`
LINES=`tput lines`
line=`expr $LINES / 2`
column=`expr \( $COLUMNS - 6 \) / 2`
tput sc
tput cup $line $column
tput rev
echo 'Hello, World'
tput sgr0
tput rc

The middle three lines of the above example can also be written using `--standard-input'.

tput --standard-input <<EOF
sc
cup $line $column
rev
EOF

Capabilities

Boolean Capabilities

Name    Termcap Description
        Equiv.

am      am      Has automatic margins
bw      bw      `cub1' wraps from column 0 to last column
chts    HC      Cursor is hard to see
da      da      Display may be retained above screen
db      db      Display may be retained below screen
eo      eo      Can erase overstrikes with a blank
eslok   es      Using escape on status line is ok
gn      gn      Generic line type (e.g., `dialup', `switch')
hc      hc      Hardcopy terminal
hs      hs      Has a status line
hz      hz      Hazeltine; cannot print tildes
in      in      Insert mode distinguishes nulls
km      km      Has a meta key (a shift that sets parity bit)
mc5i    5i      Data sent to printer does not echo on screen
mir     mi      Safe to move while in insert mode
msgr    ms      Safe to move in standout modes
npc     NP      No pad character is needed
nrrmc   NR      `smcup' does not reverse `rmcup'
nxon    nx      Padding does not work; xon/xoff is required
os      os      Overstrikes
ul      ul      Underline character overstrikes
xenl    xn      Newline ignored after 80 columns (Concept)
xhp     xs      Standout is not erased by overwriting (HP)
xon     xo      Uses xon/xoff handshaking
xsb     xb      Beehive (f1=escape, f2=ctrl-c)
xt      xt      Tabs are destructive, magic `smso' (t1061)

Numeric Capabilities

Name    Termcap Description
        Equiv.

cols    co      Number of columns in a line
it      it      Width of initial tab settings
lh      lh      Number of rows in each label
lines   li      Number of lines on screen or page
lm      lm      Lines of memory if > `lines'; 0 means varies
lw      lw      Number of columns in each label
nlab    Nl      Number of labels on screen (start at 1)
pb      pb      Lowest baud rate where padding is needed
vt      vt      Virtual terminal number (CB/Unix)
wsl     ws      Number of columns in status line
xmc     sg      Number of blanks left by `smso' or `rmso'

String Capabilities

In the following table, `(P)' following an explanation means that the capability takes one or more parameters (and is evaluated by the tparam function, or in the case of `cup', tgoto); `(*)' means that padding may be based on the number of lines affected; and `#n' refers to the `n'th parameter.

Name    Termcap Description
        Equiv.

acsc    ac      Graphic character set pairs aAbBcC - default vt100
bel     bl      Ring bell (beep)
blink   mb      Begin blinking mode
bold    md      Begin double intensity mode
cbt     bt      Back tab
civis   vi      Make cursor invisible
clear   cl      Clear screen (*)
cmdch   CC      Settable command character in prototype
cnorm   ve      Make cursor normal (undo `cvvis' & `civis)'
cr      cr      Carriage return (*)
csr     cs      Change scrolling region to lines #1 through #2 (P)
cub     LE      Move cursor left #1 spaces (P)
cub1    le      Move cursor left one space
cud     DO      Move cursor down #1 lines (P*)
cud1    do      Move cursor down one line
cuf     RI      Move cursor right #1 spaces (P*)
cuf1    nd      Move cursor right one space
cup     cm      Move cursor to row #1, column #2 of screen (P)
cuu     UP      Move cursor up #1 lines (P*)
cuu1    up      Move cursor up one line
cvvis   vs      Make cursor very visible
dch     DC      Delete #1 characters (P*)
dch1    dc      Delete one character (*)
dim     mh      Begin half intensity mode
dl      DL      Delete #1 lines (P*)
dl1     dl      Delete one line (*)
dsl     ds      Disable status line
ech     ec      Erase #1 characters (P)
ed      cd      Clear to end of display (*)
el      ce      Clear to end of line
el1     cb      Clear to beginning of line, inclusive
enacs   eA      Enable alternate character set
ff      ff      Form feed for hardcopy terminal (*)
flash   vb      Visible bell (must not move cursor)
fsl     fs      Return from status line
hd      hd      Move cursor down one-half line
home    ho      Home cursor (if no `cup')
hpa     ch      Move cursor to column #1 (P)
ht      ta      Tab to next 8 space hardware tab stop
hts     st      Set a tab in all rows, current column
hu      hu      Move cursor up one-half line
ich     IC      Insert #1 blank characters (P*)
ich1    ic      Insert one blank character
if      if      Name of file containing initialization string
il      AL      Add #1 new blank lines (P*)
il1     al      Add one new blank line (*)
ind     sf      Scroll forward (up) one line
indn    SF      Scroll forward #1 lines (P)
invis   mk      Begin invisible text mode
ip      ip      Insert pad after character inserted (*)
iprog   iP      Path of program for initialization
is1     i1      Terminal initialization string
is2     is      Terminal initialization string
is3     i3      Terminal initialization string
kBEG    &9      Shifted beginning key
kCAN    &0      Shifted cancel key
kCMD    *1      Shifted command key
kCPY    *2      Shifted copy key
kCRT    *3      Shifted create key
kDC     *4      Shifted delete char key
kDL     *5      Shifted delete line key
kEND    *7      Shifted end key
kEOL    *8      Shifted clear line key
kEXT    *9      Shifted exit key
kFND    *0      Shifted find key
kHLP    #1      Shifted help key
kHOM    #2      Shifted home key
kIC     #3      Shifted input key
kLFT    #4      Shifted left arrow key
kMOV    %b      Shifted move key
kMSG    %a      Shifted message key
kNXT    %c      Shifted next key
kOPT    %d      Shifted options key
kPRT    %f      Shifted print key
kPRV    %e      Shifted prev key
kRDO    %g      Shifted redo key
kRES    %j      Shifted resume key
kRIT    %i      Shifted right arrow
kRPL    %h      Shifted replace key
kSAV    !1      Shifted save key
kSPD    !2      Shifted suspend key
kUND    !3      Shifted undo key
ka1     K1      Upper left of keypad
ka3     K3      Upper right of keypad
kb2     K2      Center of keypad
kbeg    @1      Beginning key
kbs     kb      Backspace key
kc1     K4      Lower left of keypad
kc3     K5      Lower right of keypad
kcan    @2      Cancel key
kcbt    kB      Back tab key
kclo    @3      Close key
kclr    kC      Clear screen or erase key
kcmd    @4      Command key
kcpy    @5      Copy key
kcrt    @6      Create key
kctab   kt      Clear tab key
kcub1   kl      Left arrow key
kcud1   kd      Down arrow key
kcuf1   kr      Right arrow key
kcuu1   ku      Up arrow key
kdch1   kD      Delete character key
kdl1    kL      Delete line key
ked     kS      Clear to end of screen key
kel     kE      Clear to end of line key
kend    @7      End key
kent    @8      Enter/send key (unreliable)
kext    @9      Exit key
kf0     k0      Function key f0
kf1     k1      Function key f1
kf10    k;      Function key f10
kf11    F1      Function key f11
kf12    F2      Function key f12
kf13    F3      Function key f13
kf14    F4      Function key f14
kf15    F5      Function key f15
kf16    F6      Function key f16
kf17    F7      Function key f17
kf18    F8      Function key f18
kf19    F9      Function key f19
kf2     k2      Function key f2
kf20    FA      Function key f20
kf21    FB      Function key f21
kf22    FC      Function key f22
kf23    FD      Function key f23
kf24    FE      Function key f24
kf25    FF      Function key f25
kf26    FG      Function key f26
kf27    FH      Function key f27
kf28    FI      Function key f28
kf29    FJ      Function key f29
kf3     k3      Function key f3
kf30    FK      Function key f30
kf31    FL      Function key f31
kf32    FM      Function key f32
kf33    FN      Function key f13
kf34    FO      Function key f34
kf35    FP      Function key f35
kf36    FQ      Function key f36
kf37    FR      Function key f37
kf38    FS      Function key f38
kf39    FT      Function key f39
kf4     k4      Function key f4
kf40    FU      Function key f40
kf41    FV      Function key f41
kf42    FW      Function key f42
kf43    FX      Function key f43
kf44    FY      Function key f44
kf45    FZ      Function key f45
kf46    Fa      Function key f46
kf47    Fb      Function key f47
kf48    Fc      Function key f48
kf49    Fd      Function key f49
kf5     k5      Function key f5
kf50    Fe      Function key f50
kf51    Ff      Function key f51
kf52    Fg      Function key f52
kf53    Fh      Function key f53
kf54    Fi      Function key f54
kf55    Fj      Function key f55
kf56    Fk      Function key f56
kf57    Fl      Function key f57
kf58    Fm      Function key f58
kf59    Fn      Function key f59
kf6     k6      Function key f6
kf60    Fo      Function key f60
kf61    Fp      Function key f61
kf62    Fq      Function key f62
kf63    Fr      Function key f63
kf7     k7      Function key f7
kf8     k8      Function key f8
kf9     k9      Function key f9
kfnd    @0      Find key
khlp    %1      Help key
khome   kh      Home key
khts    kT      Set tab key
kich1   kI      Ins char/enter ins mode key
kil1    kA      Insert line key
kind    kF      Scroll forward/down key
kll     kH      Home down key
kmov    %4      Move key
kmrk    %2      Mark key
kmsg    %3      Message key
knp     kN      Next page key
knxt    %5      Next object key
kopn    %6      Open key
kopt    %7      Options key
kpp     kP      Previous page key
kprt    %9      Print or copy key
kprv    %8      Previous object key
krdo    %0      Redo key
kref    &1      Reference key
kres    &5      Resume key
krfr    &2      Refresh key
kri     kR      Scroll backward/up key
krmir   kM      rmir or smir in insert mode
krpl    &3      Replace key
krst    &4      Restart key
ksav    &6      Save key
kslt    *6      Select key
kspd    &7      Suspend key
ktbc    ka      Clear all tabs key
kund    &8      Undo key
lf0     l0      Label on function key f0 if not `f0'
lf1     l1      Label on function key f1 if not `f1'
lf10    la      Label on function key f10 if not `f10'
lf2     l2      Label on function key f2 if not `f2'
lf3     l3      Label on function key f3 if not `f3'
lf4     l4      Label on function key f4 if not `f4'
lf5     l5      Label on function key f5 if not `f5'
lf6     l6      Label on function key f6 if not `f6'
lf7     l7      Label on function key f7 if not `f7'
lf8     l8      Label on function key f8 if not `f8'
lf9     l9      Label on function key f9 if not `f9'
ll      ll      Go to last line, first column (if no `cup')
mc0     ps      Print screen contents
mc4     pf      Turn printer off
mc5     po      Turn printer on
mc5p    pO      Turn printer on for #1 bytes (P)
mgc     MC      Clear left and right soft margins
mrcup   CM      Move cursor to row #1, column #2 of memory (P)
nel     nw      Newline (like cr followed by lf)
pad     pc      Pad character (rather than nul)
pfkey   pk      Program function key #1 to type string #2 (P)
pfloc   pl      Program function key #1 to execute string #2 (P)
pfx     px      Program function key #1 to transmit string #2 (P)
pln     pn      Program label #1 to show string #2 (P)
prot    mp      Begin protected mode
rc      rc      Restore cursor to position of last `sc'
rep     rp      Repeat character #1, #2 times (P*)
rev     mr      Begin reverse video mode
rf      rf      Name of file containing reset string
rfi     RF      Send next input character (for ptys)
ri      sr      Scroll backward (down) one line
rin     SR      Scroll backward #1 lines (P)
rmacs   ae      End alternate character set
rmam    RA      Turn off automatic margins
rmcup   te      String to end programs that use `cup'
rmdc    ed      End delete mode
rmir    ei      End insert mode
rmkx    ke      End keypad transmit mode
rmln    LF      Turn off soft labels
rmm     mo      End meta mode
rmp     rP      Like `ip' but when in replace mode
rmso    se      End standout mode
rmul    ue      End underscore mode
rmxon   RX      Turn off xon/xoff handshaking
rs1     r1      Reset terminal to sane modes
rs2     r2      Reset terminal to sane modes
rs3     r3      Reset terminal to sane modes
sc      sc      Save cursor position
sgr     sa      Define video attributes #1 through #9 (P)
sgr0    me      Turn off all attributes
smacs   as      Begin alternate character set
smam    SA      Turn on automatic margins
smcup   ti      String to begin programs that use `cup'
smdc    dm      Begin delete mode
smgl    ML      Set soft left margin to #1 (P)
smgr    MR      Set soft right margin to #1 (P)
smir    im      Begin insert mode
smkx    ks      Begin keypad transmit mode
smln    LO      Turn on soft labels
smm     mm      Begin meta mode (8th bit set)
smso    so      Begin standout mode
smul    us      Begin underscore mode
smxon   SX      Turn on xon/xoff handshaking
tbc     ct      Clear all tab stops
tsl     ts      Go to status line, column #1 (P)
uc      uc      Underscore one character and move past it
vpa     cv      Move cursor to row #1 (P)
wind    wi      Set window to lines #1-#2, columns #3-#4 (P)
xoffc   XF      xoff character
xonc    XN      xon character

Error Messages

tput displays various error messages if problems occur. In addition, it exits with one of the following status values:

0
Normal status; the given capability is present.
1
The given Boolean or string capability is not present.
2
Usage error; tput was given invalid arguments.
3
The terminal type given (either in the `TERM' environment variable or by the `-T' switch) is unknown, or the termcap database can not be read.
4
The given capability is unknown.

tabs: Setting Terminal Tabs

The tabs command is used to specify and set hardware tab stops on terminals that have remotely-settable tab stops.

The tabs command is used to specify and set hardware tab stops on terminals that have remotely-settable tab stops.

tabs [options] tab-specification

Options

The options supported by GNU tabs are:

-T termtype
--terminal=termtype
Specify the terminal type, overriding the environment variable TERM.
-V
--version
Show the version number of GNU tabs and exit.
-h
--help
Show the command line usage of GNU tabs and exit.

Tab Specification

GNU tabs accepts the following types of tab specification:

n1[,n2,...]
Set tab stops at columns n1, n2, ... The leftmost column is the column 1. n2 and the rest of the list can be of the form `+num', in which case it specifies the increment from the tab stop last specified by the list.
-n
Set tab stops at every n columns. For most of the terminals, the standard tab stop setting is the equivalent of `-8'.
-code
--code=code
-C code
Set tab stops using one of the "canned" specification. The second and the third formats are useful if the name of the canned specification conflicts with one of the long options supportred by GNU tabs.
--filename
--file=filename
--F filename
Read the first line of filename, find parameters separated by blanks enclosed by <: and :> on that line, find a parameter that begins with t, and then use it as tab specification. If any of the above steps fails, set tab stops to every 8 columns. The second and the third formats are useful if the name of the file conflicts with one of the long options supportred by GNU tabs.

Canned tab specifications

GNU tabs supports the following "canned" specifications:

`a'
Assembler, IBM S/370, first format (1,10,16,36,72)
`a2'
Assembler, IBM S/370, second format (1,10,16,40,72)
`c'
COBOL, normal format (1,8,12,16,20,55)
`c2'
COBOL, compact format (1,6,10,14,49)
`c3'
COBOL, compact format with more tab stops@hfill@break (1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67)
`f'
FORTRAN (1,7,11,15,19,23)
`p'
PL/I (1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61)
`s'
SNOBOL (1,10,55)
`u'
UNIVAC 1100 Assembler (1,12,20,44)

Examples

To set tab stops for editing FORTRAN programs on an xterm, use the following tabs command:

tabs -f --terminal=xterm

Another example: a source file of FORTRAN program may contain its own tab specification on its first line:

C <: t1,7,11,15,19,23,72 :>

Before editing this file, the tabs command can be used to set tab stops to columns this file expects:

tabs --Sample.f

This document was generated on 7 November 1998 using the texi2html translator version 1.52.


GNU Wget Manual

GNU Wget

The noninteractive downloading utility

Updated for Wget 1.8.1, December 2001

by Hrvoje Nik@v{s}i'{c} and the developers

Table of Contents

  • Overview
  • Invoking
    • URL Format
    • Option Syntax
    • Basic Startup Options
    • Logging and Input File Options
    • Download Options
    • Directory Options
    • HTTP Options
    • FTP Options
    • Recursive Retrieval Options
    • Recursive Accept/Reject Options
  • Recursive Retrieval
  • Following Links
    • Spanning Hosts
    • Types of Files
    • Directory-Based Limits
    • Relative Links
    • Following FTP Links
  • Time-Stamping
    • Time-Stamping Usage
    • HTTP Time-Stamping Internals
    • FTP Time-Stamping Internals
  • Startup File
    • Wgetrc Location
    • Wgetrc Syntax
    • Wgetrc Commands
    • Sample Wgetrc
  • Examples
    • Simple Usage
    • Advanced Usage
    • Very Advanced Usage
  • Various
    • Proxies
    • Distribution
    • Mailing List
    • Reporting Bugs
    • Portability
    • Signals
  • Appendices
    • Robots
    • Security Considerations
    • Contributors
  • Copying
    • GNU General Public License
    • Preamble
    • TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
    • How to Apply These Terms to Your New Programs
    • GNU Free Documentation License
    • ADDENDUM: How to use this License for your documents
  • Concept Index

@dircategory Net Utilities @dircategory World Wide Web * Wget: (wget). The non-interactive network downloader.

Copyright (C) 1996, 1997, 1998, 2000, 2001 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License" and "GNU Free Documentation License", with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Overview

GNU Wget is a free utility for non-interactive download of files from the Web. It supports HTTP, HTTPS, and FTP protocols, as well as retrieval through HTTP proxies.

This chapter is a partial overview of Wget's features.

  • Wget is non-interactive, meaning that it can work in the background, while the user is not logged on. This allows you to start a retrieval and disconnect from the system, letting Wget finish the work. By contrast, most of the Web browsers require constant user's presence, which can be a great hindrance when transferring a lot of data.
  • Wget can follow links in HTML pages and create local versions of remote web sites, fully recreating the directory structure of the original site. This is sometimes referred to as "recursive downloading." While doing that, Wget respects the Robot Exclusion Standard (`/robots.txt'). Wget can be instructed to convert the links in downloaded HTML files to the local files for offline viewing.
  • File name wildcard matching and recursive mirroring of directories are available when retrieving via FTP. Wget can read the time-stamp information given by both HTTP and FTP servers, and store it locally. Thus Wget can see if the remote file has changed since last retrieval, and automatically retrieve the new version if it has. This makes Wget suitable for mirroring of FTP sites, as well as home pages.
  • Wget has been designed for robustness over slow or unstable network connections; if a download fails due to a network problem, it will keep retrying until the whole file has been retrieved. If the server supports regetting, it will instruct the server to continue the download from where it left off.
  • Wget supports proxy servers, which can lighten the network load, speed up retrieval and provide access behind firewalls. However, if you are behind a firewall that requires that you use a socks style gateway, you can get the socks library and build Wget with support for socks. Wget also supports the passive FTP downloading as an option.
  • Builtin features offer mechanisms to tune which links you wish to follow (see section Following Links).
  • The retrieval is conveniently traced with printing dots, each dot representing a fixed amount of data received (1KB by default). These representations can be customized to your preferences.
  • Most of the features are fully configurable, either through command line options, or via the initialization file `.wgetrc' (see section Startup File). Wget allows you to define global startup files (`/usr/local/etc/wgetrc' by default) for site settings.
  • Finally, GNU Wget is free software. This means that everyone may use it, redistribute it and/or modify it under the terms of the GNU General Public License, as published by the Free Software Foundation (see section Copying).

Invoking

By default, Wget is very simple to invoke. The basic syntax is:

wget [option]... [URL]...

Wget will simply download all the URLs specified on the command line. URL is a Uniform Resource Locator, as defined below.

However, you may wish to change some of the default parameters of Wget. You can do it two ways: permanently, adding the appropriate command to `.wgetrc' (see section Startup File), or specifying it on the command line.

URL Format

URL is an acronym for Uniform Resource Locator. A uniform resource locator is a compact string representation for a resource available via the Internet. Wget recognizes the URL syntax as per RFC1738. This is the most widely used form (square brackets denote optional parts):

http://host[:port]/directory/file
ftp://host[:port]/directory/file

You can also encode your username and password within a URL:

ftp://user:password@host/path
http://user:password@host/path

Either user or password, or both, may be left out. If you leave out either the HTTP username or password, no authentication will be sent. If you leave out the FTP username, `anonymous' will be used. If you leave out the FTP password, your email address will be supplied as a default password.(1)

You can encode unsafe characters in a URL as `%xy', xy being the hexadecimal representation of the character's ASCII value. Some common unsafe characters include `%' (quoted as `%25'), `:' (quoted as `%3A'), and `@' (quoted as `%40'). Refer to RFC1738 for a comprehensive list of unsafe characters.

Wget also supports the type feature for FTP URLs. By default, FTP documents are retrieved in the binary mode (type `i'), which means that they are downloaded unchanged. Another useful mode is the `a' (ASCII) mode, which converts the line delimiters between the different operating systems, and is thus useful for text files. Here is an example:

ftp://host/directory/file;type=a

Two alternative variants of URL specification are also supported, because of historical (hysterical?) reasons and their widespreaded use.

FTP-only syntax (supported by NcFTP):

host:/dir/file

HTTP-only syntax (introduced by Netscape):

host[:port]/dir/file

These two alternative forms are deprecated, and may cease being supported in the future.

If you do not understand the difference between these notations, or do not know which one to use, just use the plain ordinary format you use with your favorite browser, like Lynx or Netscape.

Option Syntax

Since Wget uses GNU getopts to process its arguments, every option has a short form and a long form. Long options are more convenient to remember, but take time to type. You may freely mix different option styles, or specify options after the command-line arguments. Thus you may write:

wget -r --tries=10 http://fly.srk.fer.hr/ -o log

The space between the option accepting an argument and the argument may be omitted. Instead `-o log' you can write `-olog'.

You may put several options that do not require arguments together, like:

wget -drc URL

This is a complete equivalent of:

wget -d -r -c URL

Since the options can be specified after the arguments, you may terminate them with `--'. So the following will try to download URL `-x', reporting failure to `log':

wget -o log -- -x

The options that accept comma-separated lists all respect the convention that specifying an empty list clears its value. This can be useful to clear the `.wgetrc' settings. For instance, if your `.wgetrc' sets exclude_directories to `/cgi-bin', the following example will first reset it, and then set it to exclude `/~nobody' and `/~somebody'. You can also clear the lists in `.wgetrc' (see section Wgetrc Syntax).

wget -X '' -X /~nobody,/~somebody

Basic Startup Options

`-V'
`--version'
Display the version of Wget.
`-h'
`--help'
Print a help message describing all of Wget's command-line options.
`-b'
`--background'
Go to background immediately after startup. If no output file is specified via the `-o', output is redirected to `wget-log'.
`-e command'
`--execute command'
Execute command as if it were a part of `.wgetrc' (see section Startup File). A command thus invoked will be executed after the commands in `.wgetrc', thus taking precedence over them.

Logging and Input File Options

`-o logfile'
`--output-file=logfile'
Log all messages to logfile. The messages are normally reported to standard error.
`-a logfile'
`--append-output=logfile'
Append to logfile. This is the same as `-o', only it appends to logfile instead of overwriting the old log file. If logfile does not exist, a new file is created.
`-d'
`--debug'
Turn on debug output, meaning various information important to the developers of Wget if it does not work properly. Your system administrator may have chosen to compile Wget without debug support, in which case `-d' will not work. Please note that compiling with debug support is always safe--Wget compiled with the debug support will not print any debug info unless requested with `-d'. See section Reporting Bugs, for more information on how to use `-d' for sending bug reports.
`-q'
`--quiet'
Turn off Wget's output.
`-v'
`--verbose'
Turn on verbose output, with all the available data. The default output is verbose.
`-nv'
`--non-verbose'
Non-verbose output--turn off verbose without being completely quiet (use `-q' for that), which means that error messages and basic information still get printed.
`-i file'
`--input-file=file'
Read URLs from file, in which case no URLs need to be on the command line. If there are URLs both on the command line and in an input file, those on the command lines will be the first ones to be retrieved. The file need not be an HTML document (but no harm if it is)---it is enough if the URLs are just listed sequentially. However, if you specify `--force-html', the document will be regarded as `html'. In that case you may have problems with relative links, which you can solve either by adding <base href="url"> to the documents or by specifying `--base=url' on the command line.
`-F'
`--force-html'
When input is read from a file, force it to be treated as an HTML file. This enables you to retrieve relative links from existing HTML files on your local disk, by adding <base href="url"> to HTML, or using the `--base' command-line option.
`-B URL'
`--base=URL'
When used in conjunction with `-F', prepends URL to relative links in the file specified by `-i'.

Download Options

`--bind-address=ADDRESS'
When making client TCP/IP connections, bind() to ADDRESS on the local machine. ADDRESS may be specified as a hostname or IP address. This option can be useful if your machine is bound to multiple IPs.
`-t number'
`--tries=number'
Set number of retries to number. Specify 0 or `inf' for infinite retrying.
`-O file'
`--output-document=file'
The documents will not be written to the appropriate files, but all will be concatenated together and written to file. If file already exists, it will be overwritten. If the file is `-', the documents will be written to standard output. Including this option automatically sets the number of tries to 1.
`-nc'
`--no-clobber'
If a file is downloaded more than once in the same directory, Wget's behavior depends on a few options, including `-nc'. In certain cases, the local file will be clobbered, or overwritten, upon repeated download. In other cases it will be preserved. When running Wget without `-N', `-nc', or `-r', downloading the same file in the same directory will result in the original copy of file being preserved and the second copy being named `file.1'. If that file is downloaded yet again, the third copy will be named `file.2', and so on. When `-nc' is specified, this behavior is suppressed, and Wget will refuse to download newer copies of `file'. Therefore, "no-clobber" is actually a misnomer in this mode--it's not clobbering that's prevented (as the numeric suffixes were already preventing clobbering), but rather the multiple version saving that's prevented. When running Wget with `-r', but without `-N' or `-nc', re-downloading a file will result in the new copy simply overwriting the old. Adding `-nc' will prevent this behavior, instead causing the original version to be preserved and any newer copies on the server to be ignored. When running Wget with `-N', with or without `-r', the decision as to whether or not to download a newer copy of a file depends on the local and remote timestamp and size of the file (see section Time-Stamping). `-nc' may not be specified at the same time as `-N'. Note that when `-nc' is specified, files with the suffixes `.html' or (yuck) `.htm' will be loaded from the local disk and parsed as if they had been retrieved from the Web.
`-c'
`--continue'
Continue getting a partially-downloaded file. This is useful when you want to finish up a download started by a previous instance of Wget, or by another program. For instance:
wget -c ftp://sunsite.doc.ic.ac.uk/ls-lR.Z
If there is a file named `ls-lR.Z' in the current directory, Wget will assume that it is the first portion of the remote file, and will ask the server to continue the retrieval from an offset equal to the length of the local file. Note that you don't need to specify this option if you just want the current invocation of Wget to retry downloading a file should the connection be lost midway through. This is the default behavior. `-c' only affects resumption of downloads started prior to this invocation of Wget, and whose local files are still sitting around. Without `-c', the previous example would just download the remote file to `ls-lR.Z.1', leaving the truncated `ls-lR.Z' file alone. Beginning with Wget 1.7, if you use `-c' on a non-empty file, and it turns out that the server does not support continued downloading, Wget will refuse to start the download from scratch, which would effectively ruin existing contents. If you really want the download to start from scratch, remove the file. Also beginning with Wget 1.7, if you use `-c' on a file which is of equal size as the one on the server, Wget will refuse to download the file and print an explanatory message. The same happens when the file is smaller on the server than locally (presumably because it was changed on the server since your last download attempt)---because "continuing" is not meaningful, no download occurs. On the other side of the coin, while using `-c', any file that's bigger on the server than locally will be considered an incomplete download and only (length(remote) - length(local)) bytes will be downloaded and tacked onto the end of the local file. This behavior can be desirable in certain cases--for instance, you can use `wget -c' to download just the new portion that's been appended to a data collection or log file. However, if the file is bigger on the server because it's been changed, as opposed to just appended to, you'll end up with a garbled file. Wget has no way of verifying that the local file is really a valid prefix of the remote file. You need to be especially careful of this when using `-c' in conjunction with `-r', since every file will be considered as an "incomplete download" candidate. Another instance where you'll get a garbled file if you try to use `-c' is if you have a lame HTTP proxy that inserts a "transfer interrupted" string into the local file. In the future a "rollback" option may be added to deal with this case. Note that `-c' only works with FTP servers and with HTTP servers that support the Range header.
`--progress=type'
Select the type of the progress indicator you wish to use. Legal indicators are "dot" and "bar". The "dot" indicator is used by default. It traces the retrieval by printing dots on the screen, each dot representing a fixed amount of downloaded data. When using the dotted retrieval, you may also set the style by specifying the type as `dot:style'. Different styles assign different meaning to one dot. With the default style each dot represents 1K, there are ten dots in a cluster and 50 dots in a line. The binary style has a more "computer"-like orientation--8K dots, 16-dots clusters and 48 dots per line (which makes for 384K lines). The mega style is suitable for downloading very large files--each dot represents 64K retrieved, there are eight dots in a cluster, and 48 dots on each line (so each line contains 3M). Specifying `--progress=bar' will draw a nice ASCII progress bar graphics (a.k.a "thermometer" display) to indicate retrieval. If the output is not a TTY, this option will be ignored, and Wget will revert to the dot indicator. If you want to force the bar indicator, use `--progress=bar:force'.
`-N'
`--timestamping'
Turn on time-stamping. See section Time-Stamping, for details.
`-S'
`--server-response'
Print the headers sent by HTTP servers and responses sent by FTP servers.
`--spider'
When invoked with this option, Wget will behave as a Web spider, which means that it will not download the pages, just check that they are there. You can use it to check your bookmarks, e.g. with:
wget --spider --force-html -i bookmarks.html
This feature needs much more work for Wget to get close to the functionality of real WWW spiders.
`-T seconds'
`--timeout=seconds'
Set the read timeout to seconds seconds. Whenever a network read is issued, the file descriptor is checked for a timeout, which could otherwise leave a pending connection (uninterrupted read). The default timeout is 900 seconds (fifteen minutes). Setting timeout to 0 will disable checking for timeouts. Please do not lower the default timeout value with this option unless you know what you are doing.
`-w seconds'
`--wait=seconds'
Wait the specified number of seconds between the retrievals. Use of this option is recommended, as it lightens the server load by making the requests less frequent. Instead of in seconds, the time can be specified in minutes using the m suffix, in hours using h suffix, or in days using d suffix. Specifying a large value for this option is useful if the network or the destination host is down, so that Wget can wait long enough to reasonably expect the network error to be fixed before the retry.
`--waitretry=seconds'
If you don't want Wget to wait between every retrieval, but only between retries of failed downloads, you can use this option. Wget will use linear backoff, waiting 1 second after the first failure on a given file, then waiting 2 seconds after the second failure on that file, up to the maximum number of seconds you specify. Therefore, a value of 10 will actually make Wget wait up to (1 + 2 + ... + 10) = 55 seconds per file. Note that this option is turned on by default in the global `wgetrc' file.
`--random-wait'
Some web sites may perform log analysis to identify retrieval programs such as Wget by looking for statistically significant similarities in the time between requests. This option causes the time between requests to vary between 0 and 2 * wait seconds, where wait was specified using the `-w' or `--wait' options, in order to mask Wget's presence from such analysis. A recent article in a publication devoted to development on a popular consumer platform provided code to perform this analysis on the fly. Its author suggested blocking at the class C address level to ensure automated retrieval programs were blocked despite changing DHCP-supplied addresses. The `--random-wait' option was inspired by this ill-advised recommendation to block many unrelated users from a web site due to the actions of one.
`-Y on/off'
`--proxy=on/off'
Turn proxy support on or off. The proxy is on by default if the appropriate environmental variable is defined.
`-Q quota'
`--quota=quota'
Specify download quota for automatic retrievals. The value can be specified in bytes (default), kilobytes (with `k' suffix), or megabytes (with `m' suffix). Note that quota will never affect downloading a single file. So if you specify `wget -Q10k ftp://wuarchive.wustl.edu/ls-lR.gz', all of the `ls-lR.gz' will be downloaded. The same goes even when several URLs are specified on the command-line. However, quota is respected when retrieving either recursively, or from an input file. Thus you may safely type `wget -Q2m -i sites'---download will be aborted when the quota is exceeded. Setting quota to 0 or to `inf' unlimits the download quota.

Directory Options

`-nd'
`--no-directories'
Do not create a hierarchy of directories when retrieving recursively. With this option turned on, all files will get saved to the current directory, without clobbering (if a name shows up more than once, the filenames will get extensions `.n').
`-x'
`--force-directories'
The opposite of `-nd'---create a hierarchy of directories, even if one would not have been created otherwise. E.g. `wget -x http://fly.srk.fer.hr/robots.txt' will save the downloaded file to `fly.srk.fer.hr/robots.txt'.
`-nH'
`--no-host-directories'
Disable generation of host-prefixed directories. By default, invoking Wget with `-r http://fly.srk.fer.hr/' will create a structure of directories beginning with `fly.srk.fer.hr/'. This option disables such behavior.
`--cut-dirs=number'
Ignore number directory components. This is useful for getting a fine-grained control over the directory where recursive retrieval will be saved. Take, for example, the directory at `ftp://ftp.xemacs.org/pub/xemacs/'. If you retrieve it with `-r', it will be saved locally under `ftp.xemacs.org/pub/xemacs/'. While the `-nH' option can remove the `ftp.xemacs.org/' part, you are still stuck with `pub/xemacs'. This is where `--cut-dirs' comes in handy; it makes Wget not "see" number remote directory components. Here are several examples of how `--cut-dirs' option works.
No options        -> ftp.xemacs.org/pub/xemacs/
-nH               -> pub/xemacs/
-nH --cut-dirs=1  -> xemacs/
-nH --cut-dirs=2  -> .

--cut-dirs=1      -> ftp.xemacs.org/xemacs/
...
If you just want to get rid of the directory structure, this option is similar to a combination of `-nd' and `-P'. However, unlike `-nd', `--cut-dirs' does not lose with subdirectories--for instance, with `-nH --cut-dirs=1', a `beta/' subdirectory will be placed to `xemacs/beta', as one would expect.
`-P prefix'
`--directory-prefix=prefix'
Set directory prefix to prefix. The directory prefix is the directory where all other files and subdirectories will be saved to, i.e. the top of the retrieval tree. The default is `.' (the current directory).

HTTP Options

`-E'
`--html-extension'
If a file of type `text/html' is downloaded and the URL does not end with the regexp `\.[Hh][Tt][Mm][Ll]?', this option will cause the suffix `.html' to be appended to the local filename. This is useful, for instance, when you're mirroring a remote site that uses `.asp' pages, but you want the mirrored pages to be viewable on your stock Apache server. Another good use for this is when you're downloading the output of CGIs. A URL like `http://site.com/article.cgi?25' will be saved as `article.cgi?25.html'. Note that filenames changed in this way will be re-downloaded every time you re-mirror a site, because Wget can't tell that the local `X.html' file corresponds to remote URL `X' (since it doesn't yet know that the URL produces output of type `text/html'. To prevent this re-downloading, you must use `-k' and `-K' so that the original version of the file will be saved as `X.orig' (see section Recursive Retrieval Options).
`--http-user=user'
`--http-passwd=password'
Specify the username user and password password on an HTTP server. According to the type of the challenge, Wget will encode them using either the basic (insecure) or the digest authentication scheme. Another way to specify username and password is in the URL itself (see section URL Format). For more information about security issues with Wget, See section Security Considerations.
`-C on/off'
`--cache=on/off'
When set to off, disable server-side cache. In this case, Wget will send the remote server an appropriate directive (`Pragma: no-cache') to get the file from the remote service, rather than returning the cached version. This is especially useful for retrieving and flushing out-of-date documents on proxy servers. Caching is allowed by default.
`--cookies=on/off'
When set to off, disable the use of cookies. Cookies are a mechanism for maintaining server-side state. The server sends the client a cookie using the Set-Cookie header, and the client responds with the same cookie upon further requests. Since cookies allow the server owners to keep track of visitors and for sites to exchange this information, some consider them a breach of privacy. The default is to use cookies; however, storing cookies is not on by default.
`--load-cookies file'
Load cookies from file before the first HTTP retrieval. file is a textual file in the format originally used by Netscape's `cookies.txt' file. You will typically use this option when mirroring sites that require that you be logged in to access some or all of their content. The login process typically works by the web server issuing an HTTP cookie upon receiving and verifying your credentials. The cookie is then resent by the browser when accessing that part of the site, and so proves your identity. Mirroring such a site requires Wget to send the same cookies your browser sends when communicating with the site. This is achieved by `--load-cookies'---simply point Wget to the location of the `cookies.txt' file, and it will send the same cookies your browser would send in the same situation. Different browsers keep textual cookie files in different locations:
Netscape 4.x.
The cookies are in `~/.netscape/cookies.txt'.
Mozilla and Netscape 6.x.
Mozilla's cookie file is also named `cookies.txt', located somewhere under `~/.mozilla', in the directory of your profile. The full path usually ends up looking somewhat like `~/.mozilla/default/some-weird-string/cookies.txt'.
Internet Explorer.
You can produce a cookie file Wget can use by using the File menu, Import and Export, Export Cookies. This has been tested with Internet Explorer 5; it is not guaranteed to work with earlier versions.
Other browsers.
If you are using a different browser to create your cookies, `--load-cookies' will only work if you can locate or produce a cookie file in the Netscape format that Wget expects.
If you cannot use `--load-cookies', there might still be an alternative. If your browser supports a "cookie manager", you can use it to view the cookies used when accessing the site you're mirroring. Write down the name and value of the cookie, and manually instruct Wget to send those cookies, bypassing the "official" cookie support:
wget --cookies=off --header "Cookie: name=value"
`--save-cookies file'
Save cookies from file at the end of session. Cookies whose expiry time is not specified, or those that have already expired, are not saved.
`--ignore-length'
Unfortunately, some HTTP servers (CGI programs, to be more precise) send out bogus Content-Length headers, which makes Wget go wild, as it thinks not all the document was retrieved. You can spot this syndrome if Wget retries getting the same document again and again, each time claiming that the (otherwise normal) connection has closed on the very same byte. With this option, Wget will ignore the Content-Length header--as if it never existed.
`--header=additional-header'
Define an additional-header to be passed to the HTTP servers. Headers must contain a `:' preceded by one or more non-blank characters, and must not contain newlines. You may define more than one additional header by specifying `--header' more than once.
wget --header='Accept-Charset: iso-8859-2' \
     --header='Accept-Language: hr'        \
       http://fly.srk.fer.hr/
Specification of an empty string as the header value will clear all previous user-defined headers.
`--proxy-user=user'
`--proxy-passwd=password'
Specify the username user and password password for authentication on a proxy server. Wget will encode them using the basic authentication scheme.
`--referer=url'
Include `Referer: url' header in HTTP request. Useful for retrieving documents with server-side processing that assume they are always being retrieved by interactive web browsers and only come out properly when Referer is set to one of the pages that point to them.
`-s'
`--save-headers'
Save the headers sent by the HTTP server to the file, preceding the actual contents, with an empty line as the separator.
`-U agent-string'
`--user-agent=agent-string'
Identify as agent-string to the HTTP server. The HTTP protocol allows the clients to identify themselves using a User-Agent header field. This enables distinguishing the WWW software, usually for statistical purposes or for tracing of protocol violations. Wget normally identifies as `Wget/version', version being the current version number of Wget. However, some sites have been known to impose the policy of tailoring the output according to the User-Agent-supplied information. While conceptually this is not such a bad idea, it has been abused by servers denying information to clients other than Mozilla or Microsoft Internet Explorer. This option allows you to change the User-Agent line issued by Wget. Use of this option is discouraged, unless you really know what you are doing.

FTP Options

`-nr'
`--dont-remove-listing'
Don't remove the temporary `.listing' files generated by FTP retrievals. Normally, these files contain the raw directory listings received from FTP servers. Not removing them can be useful for debugging purposes, or when you want to be able to easily check on the contents of remote server directories (e.g. to verify that a mirror you're running is complete). Note that even though Wget writes to a known filename for this file, this is not a security hole in the scenario of a user making `.listing' a symbolic link to `/etc/passwd' or something and asking root to run Wget in his or her directory. Depending on the options used, either Wget will refuse to write to `.listing', making the globbing/recursion/time-stamping operation fail, or the symbolic link will be deleted and replaced with the actual `.listing' file, or the listing will be written to a `.listing.number' file. Even though this situation isn't a problem, though, root should never run Wget in a non-trusted user's directory. A user could do something as simple as linking `index.html' to `/etc/passwd' and asking root to run Wget with `-N' or `-r' so the file will be overwritten.
`-g on/off'
`--glob=on/off'
Turn FTP globbing on or off. Globbing means you may use the shell-like special characters (wildcards), like `*', `?', `[' and `]' to retrieve more than one file from the same directory at once, like:
wget ftp://gnjilux.srk.fer.hr/*.msg
By default, globbing will be turned on if the URL contains a globbing character. This option may be used to turn globbing on or off permanently. You may have to quote the URL to protect it from being expanded by your shell. Globbing makes Wget look for a directory listing, which is system-specific. This is why it currently works only with Unix FTP servers (and the ones emulating Unix ls output).
`--passive-ftp'
Use the passive FTP retrieval scheme, in which the client initiates the data connection. This is sometimes required for FTP to work behind firewalls.
`--retr-symlinks'
Usually, when retrieving FTP directories recursively and a symbolic link is encountered, the linked-to file is not downloaded. Instead, a matching symbolic link is created on the local filesystem. The pointed-to file will not be downloaded unless this recursive retrieval would have encountered it separately and downloaded it anyway. When `--retr-symlinks' is specified, however, symbolic links are traversed and the pointed-to files are retrieved. At this time, this option does not cause Wget to traverse symlinks to directories and recurse through them, but in the future it should be enhanced to do this. Note that when retrieving a file (not a directory) because it was specified on the commandline, rather than because it was recursed to, this option has no effect. Symbolic links are always traversed in this case.

Recursive Retrieval Options

`-r'
`--recursive'
Turn on recursive retrieving. See section Recursive Retrieval, for more details.
`-l depth'
`--level=depth'
Specify recursion maximum depth level depth (see section Recursive Retrieval). The default maximum depth is 5.
`--delete-after'
This option tells Wget to delete every single file it downloads, after having done so. It is useful for pre-fetching popular pages through a proxy, e.g.:
wget -r -nd --delete-after http://whatever.com/~popular/page/
The `-r' option is to retrieve recursively, and `-nd' to not create directories. Note that `--delete-after' deletes files on the local machine. It does not issue the `DELE' command to remote FTP sites, for instance. Also note that when `--delete-after' is specified, `--convert-links' is ignored, so `.orig' files are simply not created in the first place.
`-k'
`--convert-links'
After the download is complete, convert the links in the document to make them suitable for local viewing. This affects not only the visible hyperlinks, but any part of the document that links to external content, such as embedded images, links to style sheets, hyperlinks to non-HTML content, etc. Each link will be changed in one of the two ways:
  • The links to files that have been downloaded by Wget will be changed to refer to the file they point to as a relative link. Example: if the downloaded file `/foo/doc.html' links to `/bar/img.gif', also downloaded, then the link in `doc.html' will be modified to point to `../bar/img.gif'. This kind of transformation works reliably for arbitrary combinations of directories.
  • The links to files that have not been downloaded by Wget will be changed to include host name and absolute path of the location they point to. Example: if the downloaded file `/foo/doc.html' links to `/bar/img.gif' (or to `../bar/img.gif'), then the link in `doc.html' will be modified to point to `http://hostname/bar/img.gif'.
Because of this, local browsing works reliably: if a linked file was downloaded, the link will refer to its local name; if it was not downloaded, the link will refer to its full Internet address rather than presenting a broken link. The fact that the former links are converted to relative links ensures that you can move the downloaded hierarchy to another directory. Note that only at the end of the download can Wget know which links have been downloaded. Because of that, the work done by `-k' will be performed at the end of all the downloads.
`-K'
`--backup-converted'
When converting a file, back up the original version with a `.orig' suffix. Affects the behavior of `-N' (see section HTTP Time-Stamping Internals).
`-m'
`--mirror'
Turn on options suitable for mirroring. This option turns on recursion and time-stamping, sets infinite recursion depth and keeps FTP directory listings. It is currently equivalent to `-r -N -l inf -nr'.
`-p'
`--page-requisites'
This option causes Wget to download all the files that are necessary to properly display a given HTML page. This includes such things as inlined images, sounds, and referenced stylesheets. Ordinarily, when downloading a single HTML page, any requisite documents that may be needed to display it properly are not downloaded. Using `-r' together with `-l' can help, but since Wget does not ordinarily distinguish between external and inlined documents, one is generally left with "leaf documents" that are missing their requisites. For instance, say document `1.html' contains an <IMG> tag referencing `1.gif' and an <A> tag pointing to external document `2.html'. Say that `2.html' is similar but that its image is `2.gif' and it links to `3.html'. Say this continues up to some arbitrarily high number. If one executes the command:
wget -r -l 2 http://site/1.html
then `1.html', `1.gif', `2.html', `2.gif', and `3.html' will be downloaded. As you can see, `3.html' is without its requisite `3.gif' because Wget is simply counting the number of hops (up to 2) away from `1.html' in order to determine where to stop the recursion. However, with this command:
wget -r -l 2 -p http://site/1.html
all the above files and `3.html''s requisite `3.gif' will be downloaded. Similarly,
wget -r -l 1 -p http://site/1.html
will cause `1.html', `1.gif', `2.html', and `2.gif' to be downloaded. One might think that:
wget -r -l 0 -p http://site/1.html
would download just `1.html' and `1.gif', but unfortunately this is not the case, because `-l 0' is equivalent to `-l inf'---that is, infinite recursion. To download a single HTML page (or a handful of them, all specified on the commandline or in a `-i' URL input file) and its (or their) requisites, simply leave off `-r' and `-l':
wget -p http://site/1.html
Note that Wget will behave as if `-r' had been specified, but only that single page and its requisites will be downloaded. Links from that page to external documents will not be followed. Actually, to download a single page and all its requisites (even if they exist on separate websites), and make sure the lot displays properly locally, this author likes to use a few options in addition to `-p':
wget -E -H -k -K -p http://site/document
To finish off this topic, it's worth knowing that Wget's idea of an external document link is any URL specified in an <A> tag, an <AREA> tag, or a <LINK> tag other than <LINK REL="stylesheet">.

Recursive Accept/Reject Options

`-A acclist --accept acclist'
`-R rejlist --reject rejlist'
Specify comma-separated lists of file name suffixes or patterns to accept or reject (see section Types of Files for more details).
`-D domain-list'
`--domains=domain-list'
Set domains to be followed. domain-list is a comma-separated list of domains. Note that it does not turn on `-H'.
`--exclude-domains domain-list'
Specify the domains that are not to be followed. (see section Spanning Hosts).
`--follow-ftp'
Follow FTP links from HTML documents. Without this option, Wget will ignore all the FTP links.
`--follow-tags=list'
Wget has an internal table of HTML tag / attribute pairs that it considers when looking for linked documents during a recursive retrieval. If a user wants only a subset of those tags to be considered, however, he or she should be specify such tags in a comma-separated list with this option.
`-G list'
`--ignore-tags=list'
This is the opposite of the `--follow-tags' option. To skip certain HTML tags when recursively looking for documents to download, specify them in a comma-separated list. In the past, the `-G' option was the best bet for downloading a single page and its requisites, using a commandline like:
wget -Ga,area -H -k -K -r http://site/document
However, the author of this option came across a page with tags like <LINK REL="home" HREF="/"> and came to the realization that `-G' was not enough. One can't just tell Wget to ignore <LINK>, because then stylesheets will not be downloaded. Now the best bet for downloading a single page and its requisites is the dedicated `--page-requisites' option.
`-H'
`--span-hosts'
Enable spanning across hosts when doing recursive retrieving (see section Spanning Hosts).
`-L'
`--relative'
Follow relative links only. Useful for retrieving a specific home page without any distractions, not even those from the same hosts (see section Relative Links).
`-I list'
`--include-directories=list'
Specify a comma-separated list of directories you wish to follow when downloading (see section Directory-Based Limits for more details.) Elements of list may contain wildcards.
`-X list'
`--exclude-directories=list'
Specify a comma-separated list of directories you wish to exclude from download (see section Directory-Based Limits for more details.) Elements of list may contain wildcards.
`-np'
`--no-parent'
Do not ever ascend to the parent directory when retrieving recursively. This is a useful option, since it guarantees that only the files below a certain hierarchy will be downloaded. See section Directory-Based Limits, for more details.

Recursive Retrieval

GNU Wget is capable of traversing parts of the Web (or a single HTTP or FTP server), following links and directory structure. We refer to this as to recursive retrieving, or recursion.

With HTTP URLs, Wget retrieves and parses the HTML from the given URL, documents, retrieving the files the HTML document was referring to, through markups like href, or src. If the freshly downloaded file is also of type text/html, it will be parsed and followed further.

Recursive retrieval of HTTP and HTML content is breadth-first. This means that Wget first downloads the requested HTML document, then the documents linked from that document, then the documents linked by them, and so on. In other words, Wget first downloads the documents at depth 1, then those at depth 2, and so on until the specified maximum depth.

The maximum depth to which the retrieval may descend is specified with the `-l' option. The default maximum depth is five layers.

When retrieving an FTP URL recursively, Wget will retrieve all the data from the given directory tree (including the subdirectories up to the specified depth) on the remote server, creating its mirror image locally. FTP retrieval is also limited by the depth parameter. Unlike HTTP recursion, FTP recursion is performed depth-first.

By default, Wget will create a local directory tree, corresponding to the one found on the remote server.

Recursive retrieving can find a number of applications, the most important of which is mirroring. It is also useful for WWW presentations, and any other opportunities where slow network connections should be bypassed by storing the files locally.

You should be warned that recursive downloads can overload the remote servers. Because of that, many administrators frown upon them and may ban access from your site if they detect very fast downloads of big amounts of content. When downloading from Internet servers, consider using the `-w' option to introduce a delay between accesses to the server. The download will take a while longer, but the server administrator will not be alarmed by your rudeness.

Of course, recursive download may cause problems on your machine. If left to run unchecked, it can easily fill up the disk. If downloading from local network, it can also take bandwidth on the system, as well as consume memory and CPU.

Try to specify the criteria that match the kind of download you are trying to achieve. If you want to download only one page, use `--page-requisites' without any additional recursion. If you want to download things under one directory, use `-np' to avoid downloading things from other directories. If you want to download all the files from one directory, use `-l 1' to make sure the recursion depth never exceeds one. See section Following Links, for more information about this.

Recursive retrieval should be used with care. Don't say you were not warned.

Following Links

When retrieving recursively, one does not wish to retrieve loads of unnecessary data. Most of the time the users bear in mind exactly what they want to download, and want Wget to follow only specific links.

For example, if you wish to download the music archive from `fly.srk.fer.hr', you will not want to download all the home pages that happen to be referenced by an obscure part of the archive.

Wget possesses several mechanisms that allows you to fine-tune which links it will follow.

Spanning Hosts

Wget's recursive retrieval normally refuses to visit hosts different than the one you specified on the command line. This is a reasonable default; without it, every retrieval would have the potential to turn your Wget into a small version of google.

However, visiting different hosts, or host spanning, is sometimes a useful option. Maybe the images are served from a different server. Maybe you're mirroring a site that consists of pages interlinked between three servers. Maybe the server has two equivalent names, and the HTML pages refer to both interchangeably.

Span to any host---`-H'
The `-H' option turns on host spanning, thus allowing Wget's recursive run to visit any host referenced by a link. Unless sufficient recursion-limiting criteria are applied depth, these foreign hosts will typically link to yet more hosts, and so on until Wget ends up sucking up much more data than you have intended.
Limit spanning to certain domains---`-D'
The `-D' option allows you to specify the domains that will be followed, thus limiting the recursion only to the hosts that belong to these domains. Obviously, this makes sense only in conjunction with `-H'. A typical example would be downloading the contents of `www.server.com', but allowing downloads from `images.server.com', etc.:
wget -rH -Dserver.com http://www.server.com/
You can specify more than one address by separating them with a comma, e.g. `-Ddomain1.com,domain2.com'.
Keep download off certain domains---`--exclude-domains'
If there are domains you want to exclude specifically, you can do it with `--exclude-domains', which accepts the same type of arguments of `-D', but will exclude all the listed domains. For example, if you want to download all the hosts from `foo.edu' domain, with the exception of `sunsite.foo.edu', you can do it like this:
wget -rH -Dfoo.edu --exclude-domains sunsite.foo.edu \
    http://www.foo.edu/

Types of Files

When downloading material from the web, you will often want to restrict the retrieval to only certain file types. For example, if you are interested in downloading GIFs, you will not be overjoyed to get loads of PostScript documents, and vice versa.

Wget offers two options to deal with this problem. Each option description lists a short name, a long name, and the equivalent command in `.wgetrc'.

`-A acclist'
`--accept acclist'
`accept = acclist'
The argument to `--accept' option is a list of file suffixes or patterns that Wget will download during recursive retrieval. A suffix is the ending part of a file, and consists of "normal" letters, e.g. `gif' or `.jpg'. A matching pattern contains shell-like wildcards, e.g. `books*' or `zelazny*196[0-9]*'. So, specifying `wget -A gif,jpg' will make Wget download only the files ending with `gif' or `jpg', i.e. GIFs and JPEGs. On the other hand, `wget -A "zelazny*196[0-9]*"' will download only files beginning with `zelazny' and containing numbers from 1960 to 1969 anywhere within. Look up the manual of your shell for a description of how pattern matching works. Of course, any number of suffixes and patterns can be combined into a comma-separated list, and given as an argument to `-A'.
`-R rejlist'
`--reject rejlist'
`reject = rejlist'
The `--reject' option works the same way as `--accept', only its logic is the reverse; Wget will download all files except the ones matching the suffixes (or patterns) in the list. So, if you want to download a whole page except for the cumbersome MPEGs and .AU files, you can use `wget -R mpg,mpeg,au'. Analogously, to download all files except the ones beginning with `bjork', use `wget -R "bjork*"'. The quotes are to prevent expansion by the shell.

The `-A' and `-R' options may be combined to achieve even better fine-tuning of which files to retrieve. E.g. `wget -A "*zelazny*" -R .ps' will download all the files having `zelazny' as a part of their name, but not the PostScript files.

Note that these two options do not affect the downloading of HTML files; Wget must load all the HTMLs to know where to go at all--recursive retrieval would make no sense otherwise.

Directory-Based Limits

Regardless of other link-following facilities, it is often useful to place the restriction of what files to retrieve based on the directories those files are placed in. There can be many reasons for this--the home pages may be organized in a reasonable directory structure; or some directories may contain useless information, e.g. `/cgi-bin' or `/dev' directories.

Wget offers three different options to deal with this requirement. Each option description lists a short name, a long name, and the equivalent command in `.wgetrc'.

`-I list'
`--include list'
`include_directories = list'
`-I' option accepts a comma-separated list of directories included in the retrieval. Any other directories will simply be ignored. The directories are absolute paths. So, if you wish to download from `http://host/people/bozo/' following only links to bozo's colleagues in the `/people' directory and the bogus scripts in `/cgi-bin', you can specify:
wget -I /people,/cgi-bin http://host/people/bozo/
`-X list'
`--exclude list'
`exclude_directories = list'
`-X' option is exactly the reverse of `-I'---this is a list of directories excluded from the download. E.g. if you do not want Wget to download things from `/cgi-bin' directory, specify `-X /cgi-bin' on the command line. The same as with `-A'/`-R', these two options can be combined to get a better fine-tuning of downloading subdirectories. E.g. if you want to load all the files from `/pub' hierarchy except for `/pub/worthless', specify `-I/pub -X/pub/worthless'.
`-np'
`--no-parent'
`no_parent = on'
The simplest, and often very useful way of limiting directories is disallowing retrieval of the links that refer to the hierarchy above than the beginning directory, i.e. disallowing ascent to the parent directory/directories. The `--no-parent' option (short `-np') is useful in this case. Using it guarantees that you will never leave the existing hierarchy. Supposing you issue Wget with:
wget -r --no-parent http://somehost/~luzer/my-archive/
You may rest assured that none of the references to `/~his-girls-homepage/' or `/~luzer/all-my-mpegs/' will be followed. Only the archive you are interested in will be downloaded. Essentially, `--no-parent' is similar to `-I/~luzer/my-archive', only it handles redirections in a more intelligent fashion.

Relative Links

When `-L' is turned on, only the relative links are ever followed. Relative links are here defined those that do not refer to the web server root. For example, these links are relative:

<a href="foo.gif">
<a href="foo/bar.gif">
<a href="../foo/bar.gif">

These links are not relative:

<a href="/foo.gif">
<a href="/foo/bar.gif">
<a href="http://www.server.com/foo/bar.gif">

Using this option guarantees that recursive retrieval will not span hosts, even without `-H'. In simple cases it also allows downloads to "just work" without having to convert links.

This option is probably not very useful and might be removed in a future release.

Following FTP Links

The rules for FTP are somewhat specific, as it is necessary for them to be. FTP links in HTML documents are often included for purposes of reference, and it is often inconvenient to download them by default.

To have FTP links followed from HTML documents, you need to specify the `--follow-ftp' option. Having done that, FTP links will span hosts regardless of `-H' setting. This is logical, as FTP links rarely point to the same host where the HTTP server resides. For similar reasons, the `-L' options has no effect on such downloads. On the other hand, domain acceptance (`-D') and suffix rules (`-A' and `-R') apply normally.

Also note that followed links to FTP directories will not be retrieved recursively further.

Time-Stamping

One of the most important aspects of mirroring information from the Internet is updating your archives.

Downloading the whole archive again and again, just to replace a few changed files is expensive, both in terms of wasted bandwidth and money, and the time to do the update. This is why all the mirroring tools offer the option of incremental updating.

Such an updating mechanism means that the remote server is scanned in search of new files. Only those new files will be downloaded in the place of the old ones.

A file is considered new if one of these two conditions are met:

  1. A file of that name does not already exist locally.
  2. A file of that name does exist, but the remote file was modified more recently than the local file.

To implement this, the program needs to be aware of the time of last modification of both local and remote files. We call this information the time-stamp of a file.

The time-stamping in GNU Wget is turned on using `--timestamping' (`-N') option, or through timestamping = on directive in `.wgetrc'. With this option, for each file it intends to download, Wget will check whether a local file of the same name exists. If it does, and the remote file is older, Wget will not download it.

If the local file does not exist, or the sizes of the files do not match, Wget will download the remote file no matter what the time-stamps say.

Time-Stamping Usage

The usage of time-stamping is simple. Say you would like to download a file so that it keeps its date of modification.

wget -S http://www.gnu.ai.mit.edu/

A simple ls -l shows that the time stamp on the local file equals the state of the Last-Modified header, as returned by the server. As you can see, the time-stamping info is preserved locally, even without `-N' (at least for HTTP).

Several days later, you would like Wget to check if the remote file has changed, and download it if it has.

wget -N http://www.gnu.ai.mit.edu/

Wget will ask the server for the last-modified date. If the local file has the same timestamp as the server, or a newer one, the remote file will not be re-fetched. However, if the remote file is more recent, Wget will proceed to fetch it.

The same goes for FTP. For example:

wget "ftp://ftp.ifi.uio.no/pub/emacs/gnus/*"

(The quotes around that URL are to prevent the shell from trying to interpret the `*'.)

After download, a local directory listing will show that the timestamps match those on the remote server. Reissuing the command with `-N' will make Wget re-fetch only the files that have been modified since the last download.

If you wished to mirror the GNU archive every week, you would use a command like the following, weekly:

wget --timestamping -r ftp://ftp.gnu.org/pub/gnu/

Note that time-stamping will only work for files for which the server gives a timestamp. For HTTP, this depends on getting a Last-Modified header. For FTP, this depends on getting a directory listing with dates in a format that Wget can parse (see section FTP Time-Stamping Internals).

HTTP Time-Stamping Internals

Time-stamping in HTTP is implemented by checking of the Last-Modified header. If you wish to retrieve the file `foo.html' through HTTP, Wget will check whether `foo.html' exists locally. If it doesn't, `foo.html' will be retrieved unconditionally.

If the file does exist locally, Wget will first check its local time-stamp (similar to the way ls -l checks it), and then send a HEAD request to the remote server, demanding the information on the remote file.

The Last-Modified header is examined to find which file was modified more recently (which makes it "newer"). If the remote file is newer, it will be downloaded; if it is older, Wget will give up.(2)

When `--backup-converted' (`-K') is specified in conjunction with `-N', server file `X' is compared to local file `X.orig', if extant, rather than being compared to local file `X', which will always differ if it's been converted by `--convert-links' (`-k').

Arguably, HTTP time-stamping should be implemented using the If-Modified-Since request.

FTP Time-Stamping Internals

In theory, FTP time-stamping works much the same as HTTP, only FTP has no headers--time-stamps must be ferreted out of directory listings.

If an FTP download is recursive or uses globbing, Wget will use the FTP LIST command to get a file listing for the directory containing the desired file(s). It will try to analyze the listing, treating it like Unix ls -l output, extracting the time-stamps. The rest is exactly the same as for HTTP. Note that when retrieving individual files from an FTP server without using globbing or recursion, listing files will not be downloaded (and thus files will not be time-stamped) unless `-N' is specified.

Assumption that every directory listing is a Unix-style listing may sound extremely constraining, but in practice it is not, as many non-Unix FTP servers use the Unixoid listing format because most (all?) of the clients understand it. Bear in mind that RFC959 defines no standard way to get a file list, let alone the time-stamps. We can only hope that a future standard will define this.

Another non-standard solution includes the use of MDTM command that is supported by some FTP servers (including the popular wu-ftpd), which returns the exact time of the specified file. Wget may support this command in the future.

Startup File

Once you know how to change default settings of Wget through command line arguments, you may wish to make some of those settings permanent. You can do that in a convenient way by creating the Wget startup file---`.wgetrc'.

Besides `.wgetrc' is the "main" initialization file, it is convenient to have a special facility for storing passwords. Thus Wget reads and interprets the contents of `$HOME/.netrc', if it finds it. You can find `.netrc' format in your system manuals.

Wget reads `.wgetrc' upon startup, recognizing a limited set of commands.

Wgetrc Location

When initializing, Wget will look for a global startup file, `/usr/local/etc/wgetrc' by default (or some prefix other than `/usr/local', if Wget was not installed there) and read commands from there, if it exists.

Then it will look for the user's file. If the environmental variable WGETRC is set, Wget will try to load that file. Failing that, no further attempts will be made.

If WGETRC is not set, Wget will try to load `$HOME/.wgetrc'.

The fact that user's settings are loaded after the system-wide ones means that in case of collision user's wgetrc overrides the system-wide wgetrc (in `/usr/local/etc/wgetrc' by default). Fascist admins, away!

Wgetrc Syntax

The syntax of a wgetrc command is simple:

variable = value

The variable will also be called command. Valid values are different for different commands.

The commands are case-insensitive and underscore-insensitive. Thus `DIr__PrefiX' is the same as `dirprefix'. Empty lines, lines beginning with `#' and lines containing white-space only are discarded.

Commands that expect a comma-separated list will clear the list on an empty command. So, if you wish to reset the rejection list specified in global `wgetrc', you can do it with:

reject =

Wgetrc Commands

The complete set of commands is listed below. Legal values are listed after the `='. Simple Boolean values can be set or unset using `on' and `off' or `1' and `0'. A fancier kind of Boolean allowed in some cases is the lockable Boolean, which may be set to `on', `off', `always', or `never'. If an option is set to `always' or `never', that value will be locked in for the duration of the Wget invocation--commandline options will not override.

Some commands take pseudo-arbitrary values. address values can be hostnames or dotted-quad IP addresses. n can be any positive integer, or `inf' for infinity, where appropriate. string values can be any non-empty string.

Most of these commands have commandline equivalents (see section Invoking), though some of the more obscure or rarely used ones do not.

accept/reject = string
Same as `-A'/`-R' (see section Types of Files).
add_hostdir = on/off
Enable/disable host-prefixed file names. `-nH' disables it.
continue = on/off
If set to on, force continuation of preexistent partially retrieved files. See `-c' before setting it.
background = on/off
Enable/disable going to background--the same as `-b' (which enables it).
backup_converted = on/off
Enable/disable saving pre-converted files with the suffix `.orig'---the same as `-K' (which enables it).
base = string
Consider relative URLs in URL input files forced to be interpreted as HTML as being relative to string---the same as `-B'.
bind_address = address
Bind to address, like the `--bind-address' option.
cache = on/off
When set to off, disallow server-caching. See the `-C' option.
convert links = on/off
Convert non-relative links locally. The same as `-k'.
cookies = on/off
When set to off, disallow cookies. See the `--cookies' option.
load_cookies = file
Load cookies from file. See `--load-cookies'.
save_cookies = file
Save cookies to file. See `--save-cookies'.
cut_dirs = n
Ignore n remote directory components.
debug = on/off
Debug mode, same as `-d'.
delete_after = on/off
Delete after download--the same as `--delete-after'.
dir_prefix = string
Top of directory tree--the same as `-P'.
dirstruct = on/off
Turning dirstruct on or off--the same as `-x' or `-nd', respectively.
domains = string
Same as `-D' (see section Spanning Hosts).
dot_bytes = n
Specify the number of bytes "contained" in a dot, as seen throughout the retrieval (1024 by default). You can postfix the value with `k' or `m', representing kilobytes and megabytes, respectively. With dot settings you can tailor the dot retrieval to suit your needs, or you can use the predefined styles (see section Download Options).
dots_in_line = n
Specify the number of dots that will be printed in each line throughout the retrieval (50 by default).
dot_spacing = n
Specify the number of dots in a single cluster (10 by default).
exclude_directories = string
Specify a comma-separated list of directories you wish to exclude from download--the same as `-X' (see section Directory-Based Limits).
exclude_domains = string
Same as `--exclude-domains' (see section Spanning Hosts).
follow_ftp = on/off
Follow FTP links from HTML documents--the same as `--follow-ftp'.
follow_tags = string
Only follow certain HTML tags when doing a recursive retrieval, just like `--follow-tags'.
force_html = on/off
If set to on, force the input filename to be regarded as an HTML document--the same as `-F'.
ftp_proxy = string
Use string as FTP proxy, instead of the one specified in environment.
glob = on/off
Turn globbing on/off--the same as `-g'.
header = string
Define an additional header, like `--header'.
html_extension = on/off
Add a `.html' extension to `text/html' files without it, like `-E'.
http_passwd = string
Set HTTP password.
http_proxy = string
Use string as HTTP proxy, instead of the one specified in environment.
http_user = string
Set HTTP user to string.
ignore_length = on/off
When set to on, ignore Content-Length header; the same as `--ignore-length'.
ignore_tags = string
Ignore certain HTML tags when doing a recursive retrieval, just like `-G' / `--ignore-tags'.
include_directories = string
Specify a comma-separated list of directories you wish to follow when downloading--the same as `-I'.
input = string
Read the URLs from string, like `-i'.
kill_longer = on/off
Consider data longer than specified in content-length header as invalid (and retry getting it). The default behaviour is to save as much data as there is, provided there is more than or equal to the value in Content-Length.
logfile = string
Set logfile--the same as `-o'.
login = string
Your user name on the remote machine, for FTP. Defaults to `anonymous'.
mirror = on/off
Turn mirroring on/off. The same as `-m'.
netrc = on/off
Turn reading netrc on or off.
noclobber = on/off
Same as `-nc'.
no_parent = on/off
Disallow retrieving outside the directory hierarchy, like `--no-parent' (see section Directory-Based Limits).
no_proxy = string
Use string as the comma-separated list of domains to avoid in proxy loading, instead of the one specified in environment.
output_document = string
Set the output filename--the same as `-O'.
page_requisites = on/off
Download all ancillary documents necessary for a single HTML page to display properly--the same as `-p'.
passive_ftp = on/off/always/never
Set passive FTP---the same as `--passive-ftp'. Some scripts and `.pm' (Perl module) files download files using `wget --passive-ftp'. If your firewall does not allow this, you can set `passive_ftp = never' to override the commandline.
passwd = string
Set your FTP password to password. Without this setting, the password defaults to `username@hostname.domainname'.
progress = string
Set the type of the progress indicator. Legal types are "dot" and "bar".
proxy_user = string
Set proxy authentication user name to string, like `--proxy-user'.
proxy_passwd = string
Set proxy authentication password to string, like `--proxy-passwd'.
referer = string
Set HTTP `Referer:' header just like `--referer'. (Note it was the folks who wrote the HTTP spec who got the spelling of "referrer" wrong.)
quiet = on/off
Quiet mode--the same as `-q'.
quota = quota
Specify the download quota, which is useful to put in the global `wgetrc'. When download quota is specified, Wget will stop retrieving after the download sum has become greater than quota. The quota can be specified in bytes (default), kbytes `k' appended) or mbytes (`m' appended). Thus `quota = 5m' will set the quota to 5 mbytes. Note that the user's startup file overrides system settings.
reclevel = n
Recursion level--the same as `-l'.
recursive = on/off
Recursive on/off--the same as `-r'.
relative_only = on/off
Follow only relative links--the same as `-L' (see section Relative Links).
remove_listing = on/off
If set to on, remove FTP listings downloaded by Wget. Setting it to off is the same as `-nr'.
retr_symlinks = on/off
When set to on, retrieve symbolic links as if they were plain files; the same as `--retr-symlinks'.
robots = on/off
Use (or not) `/robots.txt' file (see section Robots). Be sure to know what you are doing before changing the default (which is `on').
server_response = on/off
Choose whether or not to print the HTTP and FTP server responses--the same as `-S'.
span_hosts = on/off
Same as `-H'.
timeout = n
Set timeout value--the same as `-T'.
timestamping = on/off
Turn timestamping on/off. The same as `-N' (see section Time-Stamping).
tries = n
Set number of retries per URL---the same as `-t'.
use_proxy = on/off
Turn proxy support on/off. The same as `-Y'.
verbose = on/off
Turn verbose on/off--the same as `-v'/`-nv'.
wait = n
Wait n seconds between retrievals--the same as `-w'.
waitretry = n
Wait up to n seconds between retries of failed retrievals only--the same as `--waitretry'. Note that this is turned on by default in the global `wgetrc'.
randomwait = on/off
Turn random between-request wait times on or off. The same as `--random-wait'.

Sample Wgetrc

This is the sample initialization file, as given in the distribution. It is divided in two section--one for global usage (suitable for global startup file), and one for local usage (suitable for `$HOME/.wgetrc'). Be careful about the things you change.

Note that almost all the lines are commented out. For a command to have any effect, you must remove the `#' character at the beginning of its line.

###
### Sample Wget initialization file .wgetrc
###

## You can use this file to change the default behaviour of wget or to
## avoid having to type many many command-line options. This file does
## not contain a comprehensive list of commands -- look at the manual
## to find out what you can put into this file.
##
## Wget initialization file can reside in /usr/local/etc/wgetrc
## (global, for all users) or $HOME/.wgetrc (for a single user).
##
## To use the settings in this file, you will have to uncomment them,
## as well as change them, in most cases, as the values on the
## commented-out lines are the default values (e.g. "off").

##
## Global settings (useful for setting up in /usr/local/etc/wgetrc).
## Think well before you change them, since they may reduce wget's
## functionality, and make it behave contrary to the documentation:
##

# You can set retrieve quota for beginners by specifying a value
# optionally followed by 'K' (kilobytes) or 'M' (megabytes).  The
# default quota is unlimited.
#quota = inf

# You can lower (or raise) the default number of retries when
# downloading a file (default is 20).
#tries = 20

# Lowering the maximum depth of the recursive retrieval is handy to
# prevent newbies from going too "deep" when they unwittingly start
# the recursive retrieval.  The default is 5.
#reclevel = 5

# Many sites are behind firewalls that do not allow initiation of
# connections from the outside.  On these sites you have to use the
# `passive' feature of FTP.  If you are behind such a firewall, you
# can turn this on to make Wget use passive FTP by default.
#passive_ftp = off

# The "wait" command below makes Wget wait between every connection.
# If, instead, you want Wget to wait only between retries of failed
# downloads, set waitretry to maximum number of seconds to wait (Wget
# will use "linear backoff", waiting 1 second after the first failure
# on a file, 2 seconds after the second failure, etc. up to this max).
waitretry = 10

##
## Local settings (for a user to set in his $HOME/.wgetrc).  It is
## *highly* undesirable to put these settings in the global file, since
## they are potentially dangerous to "normal" users.
##
## Even when setting up your own ~/.wgetrc, you should know what you
## are doing before doing so.
##

# Set this to on to use timestamping by default:
#timestamping = off

# It is a good idea to make Wget send your email address in a `From:'
# header with your request (so that server administrators can contact
# you in case of errors).  Wget does *not* send `From:' by default.
#header = From: Your Name <username@site.domain>

# You can set up other headers, like Accept-Language.  Accept-Language
# is *not* sent by default.
#header = Accept-Language: en

# You can set the default proxies for Wget to use for http and ftp.
# They will override the value in the environment.
#http_proxy = http://proxy.yoyodyne.com:18023/
#ftp_proxy = http://proxy.yoyodyne.com:18023/

# If you do not want to use proxy at all, set this to off.
#use_proxy = on

# You can customize the retrieval outlook.  Valid options are default,
# binary, mega and micro.
#dot_style = default

# Setting this to off makes Wget not download /robots.txt.  Be sure to
# know *exactly* what /robots.txt is and how it is used before changing
# the default!
#robots = on

# It can be useful to make Wget wait between connections.  Set this to
# the number of seconds you want Wget to wait.
#wait = 0

# You can force creating directory structure, even if a single is being
# retrieved, by setting this to on.
#dirstruct = off

# You can turn on recursive retrieving by default (don't do this if
# you are not sure you know what it means) by setting this to on.
#recursive = off

# To always back up file X as X.orig before converting its links (due
# to -k / --convert-links / convert_links = on having been specified),
# set this variable to on:
#backup_converted = off

# To have Wget follow FTP links from HTML files by default, set this
# to on:
#follow_ftp = off

Examples

The examples are divided into three sections loosely based on their complexity.

Simple Usage

  • Say you want to download a URL. Just type:
    wget http://fly.srk.fer.hr/
  • But what will happen if the connection is slow, and the file is lengthy? The connection will probably fail before the whole file is retrieved, more than once. In this case, Wget will try getting the file until it either gets the whole of it, or exceeds the default number of retries (this being 20). It is easy to change the number of tries to 45, to insure that the whole file will arrive safely:
    wget --tries=45 http://fly.srk.fer.hr/jpg/flyweb.jpg
  • Now let's leave Wget to work in the background, and write its progress to log file `log'. It is tiring to type `--tries', so we shall use `-t'.
    wget -t 45 -o log http://fly.srk.fer.hr/jpg/flyweb.jpg &
    The ampersand at the end of the line makes sure that Wget works in the background. To unlimit the number of retries, use `-t inf'.
  • The usage of FTP is as simple. Wget will take care of login and password.
    wget ftp://gnjilux.srk.fer.hr/welcome.msg
  • If you specify a directory, Wget will retrieve the directory listing, parse it and convert it to HTML. Try:
    wget ftp://prep.ai.mit.edu/pub/gnu/
links index.html

Advanced Usage

  • You have a file that contains the URLs you want to download? Use the `-i' switch:
    wget -i file
    If you specify `-' as file name, the URLs will be read from standard input.
  • Create a five levels deep mirror image of the GNU web site, with the same directory structure the original has, with only one try per document, saving the log of the activities to `gnulog':
    wget -r http://www.gnu.org/ -o gnulog
  • The same as the above, but convert the links in the HTML files to point to local files, so you can view the documents off-line:
    wget --convert-links -r http://www.gnu.org/ -o gnulog
  • Retrieve only one HTML page, but make sure that all the elements needed for the page to be displayed, such as inline images and external style sheets, are also downloaded. Also make sure the downloaded page references the downloaded links.
    wget -p --convert-links http://www.server.com/dir/page.html
    The HTML page will be saved to `www.server.com/dir/page.html', and the images, stylesheets, etc., somewhere under `www.server.com/', depending on where they were on the remote server.
  • The same as the above, but without the `www.server.com/' directory. In fact, I don't want to have all those random server directories anyway--just save all those files under a `download/' subdirectory of the current directory.
    wget -p --convert-links -nH -nd -Pdownload \
     http://www.server.com/dir/page.html
  • Retrieve the index.html of `www.lycos.com', showing the original server headers:
    wget -S http://www.lycos.com/
  • Save the server headers with the file, perhaps for post-processing.
    wget -s http://www.lycos.com/
more index.html
  • Retrieve the first two levels of `wuarchive.wustl.edu', saving them to `/tmp'.
    wget -r -l2 -P/tmp ftp://wuarchive.wustl.edu/
  • You want to download all the GIFs from a directory on an HTTP server. You tried `wget http://www.server.com/dir/*.gif', but that didn't work because HTTP retrieval does not support globbing. In that case, use:
    wget -r -l1 --no-parent -A.gif http://www.server.com/dir/
    More verbose, but the effect is the same. `-r -l1' means to retrieve recursively (see section Recursive Retrieval), with maximum depth of 1. `--no-parent' means that references to the parent directory are ignored (see section Directory-Based Limits), and `-A.gif' means to download only the GIF files. `-A "*.gif"' would have worked too.
  • Suppose you were in the middle of downloading, when Wget was interrupted. Now you do not want to clobber the files already present. It would be:
    wget -nc -r http://www.gnu.org/
  • If you want to encode your own username and password to HTTP or FTP, use the appropriate URL syntax (see section URL Format).
    wget ftp://hniksic:mypassword@unix.server.com/.emacs
  • You would like the output documents to go to standard output instead of to files?
    wget -O - http://jagor.srce.hr/ http://www.srce.hr/
    You can also combine the two options and make pipelines to retrieve the documents from remote hotlists:
    wget -O - http://cool.list.com/ | wget --force-html -i -

Very Advanced Usage

  • If you wish Wget to keep a mirror of a page (or FTP subdirectories), use `--mirror' (`-m'), which is the shorthand for `-r -l inf -N'. You can put Wget in the crontab file asking it to recheck a site each Sunday:
    crontab
0 0 * * 0 wget --mirror http://www.gnu.org/ -o /home/me/weeklog
  • In addition to the above, you want the links to be converted for local viewing. But, after having read this manual, you know that link conversion doesn't play well with timestamping, so you also want Wget to back up the original HTML files before the conversion. Wget invocation would look like this:
    wget --mirror --convert-links --backup-converted  \
     http://www.gnu.org/ -o /home/me/weeklog
  • But you've also noticed that local viewing doesn't work all that well when HTML files are saved under extensions other than `.html', perhaps because they were served as `index.cgi'. So you'd like Wget to rename all the files served with content-type `text/html' to `name.html'.
    wget --mirror --convert-links --backup-converted \
     --html-extension -o /home/me/weeklog        \
     http://www.gnu.org/
    Or, with less typing:
    wget -m -k -K -E http://www.gnu.org/ -o /home/me/weeklog

Various

This chapter contains all the stuff that could not fit anywhere else.

Proxies

Proxies are special-purpose HTTP servers designed to transfer data from remote servers to local clients. One typical use of proxies is lightening network load for users behind a slow connection. This is achieved by channeling all HTTP and FTP requests through the proxy which caches the transferred data. When a cached resource is requested again, proxy will return the data from cache. Another use for proxies is for companies that separate (for security reasons) their internal networks from the rest of Internet. In order to obtain information from the Web, their users connect and retrieve remote data using an authorized proxy.

Wget supports proxies for both HTTP and FTP retrievals. The standard way to specify proxy location, which Wget recognizes, is using the following environment variables:

http_proxy
This variable should contain the URL of the proxy for HTTP connections.
ftp_proxy
This variable should contain the URL of the proxy for FTP connections. It is quite common that HTTP_PROXY and FTP_PROXY are set to the same URL.
no_proxy
This variable should contain a comma-separated list of domain extensions proxy should not be used for. For instance, if the value of no_proxy is `.mit.edu', proxy will not be used to retrieve documents from MIT.

In addition to the environment variables, proxy location and settings may be specified from within Wget itself.

`-Y on/off'
`--proxy=on/off'
`proxy = on/off'
This option may be used to turn the proxy support on or off. Proxy support is on by default, provided that the appropriate environment variables are set.
`http_proxy = URL'
`ftp_proxy = URL'
`no_proxy = string'
These startup file variables allow you to override the proxy settings specified by the environment.

Some proxy servers require authorization to enable you to use them. The authorization consists of username and password, which must be sent by Wget. As with HTTP authorization, several authentication schemes exist. For proxy authorization only the Basic authentication scheme is currently implemented.

You may specify your username and password either through the proxy URL or through the command-line options. Assuming that the company's proxy is located at `proxy.company.com' at port 8001, a proxy URL location containing authorization data might look like this:

http://hniksic:mypassword@proxy.company.com:8001/

Alternatively, you may use the `proxy-user' and `proxy-password' options, and the equivalent `.wgetrc' settings proxy_user and proxy_passwd to set the proxy username and password.

Distribution

Like all GNU utilities, the latest version of Wget can be found at the master GNU archive site prep.ai.mit.edu, and its mirrors. For example, Wget 1.8.1 can be found at ftp://prep.ai.mit.edu/gnu/wget/wget-1.8.1.tar.gz

Mailing List

Wget has its own mailing list at wget@sunsite.dk, thanks to Karsten Thygesen. The mailing list is for discussion of Wget features and web, reporting Wget bugs (those that you think may be of interest to the public) and mailing announcements. You are welcome to subscribe. The more people on the list, the better!

To subscribe, send mail to wget-subscribe@sunsite.dk. the magic word `subscribe' in the subject line. Unsubscribe by mailing to wget-unsubscribe@sunsite.dk.

The mailing list is archived at http://fly.srk.fer.hr/archive/wget. Alternative archive is available at http://www.mail-archive.com/wget%40sunsite.auc.dk/.

Reporting Bugs

You are welcome to send bug reports about GNU Wget to bug-wget@gnu.org.

Before actually submitting a bug report, please try to follow a few simple guidelines.

  1. Please try to ascertain that the behaviour you see really is a bug. If Wget crashes, it's a bug. If Wget does not behave as documented, it's a bug. If things work strange, but you are not sure about the way they are supposed to work, it might well be a bug.
  2. Try to repeat the bug in as simple circumstances as possible. E.g. if Wget crashes while downloading `wget -rl0 -kKE -t5 -Y0 http://yoyodyne.com -o /tmp/log', you should try to see if the crash is repeatable, and if will occur with a simpler set of options. You might even try to start the download at the page where the crash occurred to see if that page somehow triggered the crash. Also, while I will probably be interested to know the contents of your `.wgetrc' file, just dumping it into the debug message is probably a bad idea. Instead, you should first try to see if the bug repeats with `.wgetrc' moved out of the way. Only if it turns out that `.wgetrc' settings affect the bug, mail me the relevant parts of the file.
  3. Please start Wget with `-d' option and send the log (or the relevant parts of it). If Wget was compiled without debug support, recompile it. It is much easier to trace bugs with debug support on.
  4. If Wget has crashed, try to run it in a debugger, e.g. gdb `which wget` core and type where to get the backtrace.

Portability

Since Wget uses GNU Autoconf for building and configuring, and avoids using "special" ultra--mega--cool features of any particular Unix, it should compile (and work) on all common Unix flavors.

Various Wget versions have been compiled and tested under many kinds of Unix systems, including Solaris, Linux, SunOS, OSF (aka Digital Unix), Ultrix, *BSD, IRIX, and others; refer to the file `MACHINES' in the distribution directory for a comprehensive list. If you compile it on an architecture not listed there, please let me know so I can update it.

Wget should also compile on the other Unix systems, not listed in `MACHINES'. If it doesn't, please let me know.

Thanks to kind contributors, this version of Wget compiles and works on Microsoft Windows 95 and Windows NT platforms. It has been compiled successfully using MS Visual C++ 4.0, Watcom, and Borland C compilers, with Winsock as networking software. Naturally, it is crippled of some features available on Unix, but it should work as a substitute for people stuck with Windows. Note that the Windows port is neither tested nor maintained by me--all questions and problems should be reported to Wget mailing list at wget@sunsite.dk where the maintainers will look at them.

Signals

Since the purpose of Wget is background work, it catches the hangup signal (SIGHUP) and ignores it. If the output was on standard output, it will be redirected to a file named `wget-log'. Otherwise, SIGHUP is ignored. This is convenient when you wish to redirect the output of Wget after having started it.

$ wget http://www.ifi.uio.no/~larsi/gnus.tar.gz &
$ kill -HUP %%     # Redirect the output to wget-log

Other than that, Wget will not try to interfere with signals in any way. C-c, kill -TERM and kill -KILL should kill it alike.

Appendices

This chapter contains some references I consider useful.

Robots

It is extremely easy to make Wget wander aimlessly around a web site, sucking all the available data in progress. `wget -r site', and you're set. Great? Not for the server admin.

While Wget is retrieving static pages, there's not much of a problem. But for Wget, there is no real difference between a static page and the most demanding CGI. For instance, a site I know has a section handled by an, uh, bitchin' CGI script that converts all the Info files to HTML. The script can and does bring the machine to its knees without providing anything useful to the downloader.

For such and similar cases various robot exclusion schemes have been devised as a means for the server administrators and document authors to protect chosen portions of their sites from the wandering of robots.

The more popular mechanism is the Robots Exclusion Standard, or RES, written by Martijn Koster et al. in 1994. It specifies the format of a text file containing directives that instruct the robots which URL paths to avoid. To be found by the robots, the specifications must be placed in `/robots.txt' in the server root, which the robots are supposed to download and parse.

Wget supports RES when downloading recursively. So, when you issue:

wget -r http://www.server.com/

First the index of `www.server.com' will be downloaded. If Wget finds that it wants to download more documents from that server, it will request `http://www.server.com/robots.txt' and, if found, use it for further downloads. `robots.txt' is loaded only once per each server.

Until version 1.8, Wget supported the first version of the standard, written by Martijn Koster in 1994 and available at http://www.robotstxt.org/wc/norobots.html. As of version 1.8, Wget has supported the additional directives specified in the internet draft `<draft-koster-robots-00.txt>' titled "A Method for Web Robots Control". The draft, which has as far as I know never made to an RFC, is available at http://www.robotstxt.org/wc/norobots-rfc.txt.

This manual no longer includes the text of the Robot Exclusion Standard.

The second, less known mechanism, enables the author of an individual document to specify whether they want the links from the file to be followed by a robot. This is achieved using the META tag, like this:

<meta name="robots" content="nofollow">

This is explained in some detail at http://www.robotstxt.org/wc/meta-user.html. Wget supports this method of robot exclusion in addition to the usual `/robots.txt' exclusion.

Security Considerations

When using Wget, you must be aware that it sends unencrypted passwords through the network, which may present a security problem. Here are the main issues, and some solutions.

  1. The passwords on the command line are visible using ps. If this is a problem, avoid putting passwords from the command line--e.g. you can use `.netrc' for this.
  2. Using the insecure basic authentication scheme, unencrypted passwords are transmitted through the network routers and gateways.
  3. The FTP passwords are also in no way encrypted. There is no good solution for this at the moment.
  4. Although the "normal" output of Wget tries to hide the passwords, debugging logs show them, in all forms. This problem is avoided by being careful when you send debug logs (yes, even when you send them to me).

Contributors

GNU Wget was written by Hrvoje Nik@v{s}i'{c} hniksic@arsdigita.com. However, its development could never have gone as far as it has, were it not for the help of many people, either with bug reports, feature proposals, patches, or letters saying "Thanks!".

Special thanks goes to the following people (no particular order):

  • Karsten Thygesen--donated system resources such as the mailing list, web space, and FTP space, along with a lot of time to make these actually work.
  • Shawn McHorse--bug reports and patches.
  • Kaveh R. Ghazi--on-the-fly ansi2knr-ization. Lots of portability fixes.
  • Gordon Matzigkeit---`.netrc' support.
  • Zlatko @v{C}alu@v{s}i'{c}, Tomislav Vujec and Dra@v{z}en Ka@v{c}ar--feature suggestions and "philosophical" discussions.
  • Darko Budor--initial port to Windows.
  • Antonio Rosella--help and suggestions, plus the Italian translation.
  • Tomislav Petrovi'{c}, Mario Miko@v{c}evi'{c}---many bug reports and suggestions.
  • Fran@,{c}ois Pinard--many thorough bug reports and discussions.
  • Karl Eichwalder--lots of help with internationalization and other things.
  • Junio Hamano--donated support for Opie and HTTP Digest authentication.
  • The people who provided donations for development, including Brian Gough.

The following people have provided patches, bug/build reports, useful suggestions, beta testing services, fan mail and all the other things that make maintenance so much fun:

Ian Abbott Tim Adam, Adrian Aichner, Martin Baehr, Dieter Baron, Roger Beeman, Dan Berger, T. Bharath, Paul Bludov, Daniel Bodea, Mark Boyns, John Burden, Wanderlei Cavassin, Gilles Cedoc, Tim Charron, Noel Cragg, Kristijan @v{C}onka@v{s}, John Daily, Andrew Davison, Andrew Deryabin, Ulrich Drepper, Marc Duponcheel, Damir D@v{z}eko, Alan Eldridge, Aleksandar Erkalovi'{c}, Andy Eskilsson, Christian Fraenkel, Masashi Fujita, Howard Gayle, Marcel Gerrits, Lemble Gregory, Hans Grobler, Mathieu Guillaume, Dan Harkless, Herold Heiko, Jochen Hein, Karl Heuer, HIROSE Masaaki, Gregor Hoffleit, Erik Magnus Hulthen, Richard Huveneers, Jonas Jensen, Simon Josefsson, Mario Juri'{c}, Hack Kampbj@o rn, Const Kaplinsky, Goran Kezunovi'{c}, Robert Kleine, KOJIMA Haime, Fila Kolodny, Alexander Kourakos, Martin Kraemer, Hrvoje Lacko, Daniel S. Lewart, Nicol'{a}s Lichtmeier, Dave Love, Alexander V. Lukyanov, Jordan Mendelson, Lin Zhe Min, Tim Mooney, Simon Munton, Charlie Negyesi, R. K. Owen, Andrew Pollock, Steve Pothier, Jan P@v{r}ikryl, Marin Purgar, Csaba R'{a}duly, Keith Refson, Tyler Riddle, Tobias Ringstrom, Edward J. Sabol, Heinz Salzmann, Robert Schmidt, Andreas Schwab, Chris Seawood, Toomas Soome, Tage Stabell-Kulo, Sven Sternberger, Markus Strasser, John Summerfield, Szakacsits Szabolcs, Mike Thomas, Philipp Thomas, Dave Turner, Russell Vincent, Charles G Waldman, Douglas E. Wegscheid, Jasmin Zainul, Bojan @v{Z}drnja, Kristijan Zimmer.

Apologies to all who I accidentally left out, and many thanks to all the subscribers of the Wget mailing list.

Copying

GNU Wget is licensed under the GNU GPL, which makes it free software.

Please note that "free" in "free software" refers to liberty, not price. As some GNU project advocates like to point out, think of "free speech" rather than "free beer". The exact and legally binding distribution terms are spelled out below; in short, you have the right (freedom) to run and change Wget and distribute it to other people, and even--if you want--charge money for doing either. The important restriction is that you have to grant your recipients the same rights and impose the same restrictions.

This method of licensing software is also known as open source because, among other things, it makes sure that all recipients will receive the source code along with the program, and be able to improve it. The GNU project prefers the term "free software" for reasons outlined at http://www.gnu.org/philosophy/free-software-for-freedom.html.

The exact license terms are defined by this paragraph and the GNU General Public License it refers to:

GNU Wget is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

GNU Wget is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as part of this manual; if you did not receive it, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

In addition to this, this manual is free in the same sense:

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License" and "GNU Free Documentation License", with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

The full texts of the GNU General Public License and of the GNU Free Documentation License are available below.

GNU General Public License

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and an idea of what it does.
Copyright (C) 19yy  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

GNU Free Documentation License

Version 1.1, March 2000

Copyright (C) 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
  2. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
  3. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies.
  4. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
  5. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
    C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    D. Preserve all the copyright notices of the Document.
    E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
    H. Include an unaltered copy of this License.
    I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
    N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.
    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
  6. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."
  7. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
  8. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
  9. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
  10. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
  11. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1
  or any later version published by the Free Software Foundation;
  with the Invariant Sections being list their titles, with the
  Front-Cover Texts being list, and with the Back-Cover Texts being list.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Concept Index

Jump to: . - a - b - c - d - e - f - g - h - i - l - m - n - o - p - q - r - s - t - u - v - w

.

  • .html extension
  • .listing files, removing
  • .netrc
  • .wgetrc

    • a

  • accept directories
  • accept suffixes
  • accept wildcards
  • append to log
  • arguments
  • authentication

    • b

  • backing up converted files
  • base for relative links in input file
  • bind() address
  • bug reports
  • bugs

    • c

  • cache
  • client IP address
  • clobbering, file
  • command line
  • Content-Length, ignore
  • continue retrieval
  • contributors
  • conversion of links
  • cookies
  • cookies, loading
  • cookies, saving
  • copying
  • cut directories

    • d

  • debug
  • delete after retrieval
  • directories
  • directories, exclude
  • directories, include
  • directory limits
  • directory prefix
  • dot style
  • downloading multiple times

    • e

  • examples
  • exclude directories
  • execute wgetrc command

    • f

  • features
  • filling proxy cache
  • follow FTP links
  • following ftp links
  • following links
  • force html
  • free software
  • ftp time-stamping

    • g

  • GFDL
  • globbing, toggle
  • GPL

    • h

  • hangup
  • header, add
  • hosts, spanning
  • http password
  • http referer
  • http time-stamping
  • http user

    • i

  • ignore length
  • include directories
  • incomplete downloads
  • incremental updating
  • input-file
  • invoking
  • IP address, client

    • l

  • latest version
  • link conversion
  • links
  • list
  • loading cookies
  • location of wgetrc
  • log file

    • m

  • mailing list
  • mirroring

    • n

  • no parent
  • no warranty
  • no-clobber
  • nohup
  • number of retries

    • o

  • operating systems
  • option syntax
  • output file
  • overview

    • p

  • page requisites
  • passive ftp
  • pause
  • portability
  • progress indicator
  • proxies
  • proxy, proxy
  • proxy authentication
  • proxy filling
  • proxy password
  • proxy user

    • q

  • quiet
  • quota

    • r

  • random wait
  • recursion
  • recursive retrieval
  • redirecting output
  • referer, http
  • reject directories
  • reject suffixes
  • reject wildcards
  • relative links
  • reporting bugs
  • required images, downloading
  • resume download
  • retries
  • retries, waiting between
  • retrieving
  • robots
  • robots.txt

    • s

  • sample wgetrc
  • saving cookies
  • security
  • server maintenance
  • server response, print
  • server response, save
  • signal handling
  • spanning hosts
  • spider
  • startup
  • startup file
  • suffixes, accept
  • suffixes, reject
  • symbolic links, retrieving
  • syntax of options
  • syntax of wgetrc

    • t

  • tag-based recursive pruning
  • time-stamping
  • time-stamping usage
  • timeout
  • timestamping
  • tries
  • types of files

    • u

  • updating the archives
  • URL
  • URL syntax
  • usage, time-stamping
  • user-agent

    • v

  • various
  • verbose

    • w

  • wait
  • wait, random
  • waiting between retries
  • Wget as spider
  • wgetrc
  • wgetrc commands
  • wgetrc location
  • wgetrc syntax
  • wildcards, accept
  • wildcards, reject

    • Footnotes

    (1)

    If you have a `.netrc' file in your home directory, password will also be searched for there.

    (2)

    As an additional check, Wget will look at the Content-Length header, and compare the sizes; if they are not the same, the remote file will be downloaded no matter what the time-stamp says.

    This document was generated on 17 January 2002 using texi2html 1.56k.